Story Mode & Visual Insights

Relevant source files

The following files were used as context for generating this wiki page:

• components/TypewriterMarkdown.tsx
• components/VisualInsightsRenderer.tsx
• netlify/functions/utils/insights-guru.cjs
• tests/visual-guru-mode.test.js
• INSIGHTS_UI_IMPROVEMENTS.md
• SESSION_COMPLETE.md

The Story Mode and Visual Insights features transform the AI-generated analysis from plain text into a dynamic and engaging user experience. This is achieved by rendering insights with a "typewriter" effect to simulate a real-time AI conversation and by enabling a "Visual Guru" mode that generates structured JSON for data visualizations instead of just text. These enhancements aim to make the insights more polished, professional, and easier to interpret.

Sources: INSIGHTS_UI_IMPROVEMENTS.md, SESSION_COMPLETE.md, tests/visual-guru-mode.test.js

Architecture and Components

The system is composed of several key UI components and a specific backend prompt-engineering strategy to generate the desired output format.

This diagram illustrates the relationship between the main UI components responsible for rendering insights.

chart blocks| VisualInsightsRenderer

Sources: [INSIGHTS_UI_IMPROVEMENTS.md](https://github.com/Treystu/BMSview/blob/HEAD/INSIGHTS_UI_IMPROVEMENTS.md), [components/VisualInsightsRenderer.tsx:29-41](https://github.com/Treystu/BMSview/blob/HEAD/components/VisualInsightsRenderer.tsx#L29-L41)

### TypewriterMarkdown Component

This component is central to the "Story Mode" experience. It takes a string of markdown content and renders it progressively, character by character, simulating an AI typing in real-time. It replaces a basic `<pre>` tag to provide a more polished and modern interface.

Sources: [components/TypewriterMarkdown.tsx](https://github.com/Treystu/BMSview/blob/HEAD/components/TypewriterMarkdown.tsx), [INSIGHTS_UI_IMPROVEMENTS.md](https://github.com/Treystu/BMSview/blob/HEAD/INSIGHTS_UI_IMPROVEMENTS.md)

#### Key Features
- **Progressive Text Reveal**: Uses `setInterval` to update the displayed text, creating a typewriter effect.
- **Full Markdown Support**: Leverages `react-markdown` and `remark-gfm` to support headings, lists, tables, code blocks, and other markdown syntax.
- **Custom Styling**: Applies Tailwind CSS `prose` classes for professional typography and custom styles for elements like code blocks and blockquotes.
- **Blinking Cursor**: Displays a blinking cursor at the end of the text while typing.
- **Specialized Renderers**: Includes a custom renderer for ````chart` code blocks, which are handled by the `VisualInsightsRenderer` component.

Sources: [components/TypewriterMarkdown.tsx:18-26, 60-106](https://github.com/Treystu/BMSview/blob/HEAD/components/TypewriterMarkdown.tsx#L18-L26), [INSIGHTS_UI_IMPROVEMENTS.md](https://github.com/Treystu/BMSview/blob/HEAD/INSIGHTS_UI_IMPROVEMENTS.md)

#### Component Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `content` | `string` | - | **Required.** The full markdown string to be rendered. |
| `speed` | `number` | `20` | The number of characters to reveal per update interval. |
| `interval` | `number` | `50` | The time in milliseconds between each text update. |
| `className` | `string` | `''` | Additional CSS classes to apply to the container. |
| `onComplete` | `() => void` | - | An optional callback function that fires when the typewriter effect is complete. |

Sources: [components/TypewriterMarkdown.tsx:11-17](https://github.com/Treystu/BMSview/blob/HEAD/components/TypewriterMarkdown.tsx#L11-L17)

### VisualInsightsRenderer Component

This component is responsible for parsing and rendering the special ````chart` code blocks generated by the AI in "Visual Guru" mode. It transforms the JSON configuration within these blocks into actual data visualizations.

Sources: [components/VisualInsightsRenderer.tsx](https://github.com/Treystu/BMSview/blob/HEAD/components/VisualInsightsRenderer.tsx), [tests/visual-guru-mode.test.js](https://github.com/Treystu/BMSview/blob/HEAD/tests/visual-guru-mode.test.js)

#### Chart Configuration

The component expects a JSON object inside a ````chart` block. This JSON defines the chart's properties and data.

```json
{
  "chartType": "line",
  "title": "State of Charge (SOC) Trend",
  "data": {
    "labels": ["Day 1", "Day 2", "Day 3"],
    "datasets": [{
      "label": "SOC %",
      "data": [85, 88, 82]
    }]
  },
  "dimensions": {
    "aspectRatio": "16:9",
    "preferredWidth": "full"
  }
}

Sources: tests/visual-guru-mode.test.js:100-110, netlify/functions/utils/insights-guru.cjs

Chart Dimensions

The dimensions property in the chart configuration controls the layout and size of the rendered chart.

Property	Type	Supported Values	Description
aspectRatio	string	'16:9', '4:3', '1:1', '2:1', '3:2'	The aspect ratio of the chart.
preferredWidth	string	'full', 'half', 'third'	The desired width relative to the container.
minHeight	number	-	Minimum height in pixels.
maxHeight	number	-	Maximum height in pixels.

Sources: components/VisualInsightsRenderer.tsx:13-22, tests/visual-guru-mode.test.js:203-211

Visual Guru Mode

To enable the generation of visual insights, a specific insightMode called visual_guru is used. When this mode is active, the backend prompt engineering instructs the Gemini AI to respond with structured JSON for charts instead of narrative text.

Sources: tests/visual-guru-mode.test.js:48-58

Backend Prompt Engineering

The buildGuruPrompt function in netlify/functions/utils/insights-guru.cjs constructs a specialized prompt for the visual_guru mode.

Key Instructions in the Prompt:

• Primary Goal: The main goal is to generate structured JSON data for charts, enclosed in ````chart` blocks.
• Forbidden Responses: The AI is explicitly told NOT to respond with conversational text like "I cannot generate images" or "Here is a description of a chart." It must provide the JSON configuration.
• Chart Types: The prompt provides examples of supported chart types, including line, bar, gauge, stacked_bar, and area.
• Dimension Guidance: Instructions on using aspectRatio and preferredWidth are included to ensure proper chart layout.
• Fallback: If no time-series data is available, the AI is instructed to generate status badges instead of charts.

This diagram shows the sequence for generating and rendering a visual insight.

chart JSON block
Backend-->>Frontend: Stream response to client
Frontend->>Frontend: TypewriterMarkdown renders text
Note right of Frontend: Detects ```chart block
Frontend->>Frontend: VisualInsightsRenderer parses JSON and renders chart
Frontend-->>User: Display text and chart

Sources: [tests/visual-guru-mode.test.js:48-143](https://github.com/Treystu/BMSview/blob/HEAD/tests/visual-guru-mode.test.js#L48-L143), [netlify/functions/utils/insights-guru.cjs](https://github.com/Treystu/BMSview/blob/HEAD/netlify/functions/utils/insights-guru.cjs), [components/VisualInsightsRenderer.tsx:29-41](https://github.com/Treystu/BMSview/blob/HEAD/components/VisualInsightsRenderer.tsx#L29-L41)

## Conclusion

The Story Mode and Visual Insights features represent a significant enhancement to the user interface of BMSview. By combining the `TypewriterMarkdown` component for an engaging text display and the `VisualInsightsRenderer` for data-driven charts, the application delivers AI analysis in a more intuitive, professional, and visually appealing format. The `visual_guru` insight mode is the key enabler, bridging the gap between the AI's analytical capabilities and the frontend's rendering power.

Sources: [INSIGHTS_UI_IMPROVEMENTS.md](https://github.com/Treystu/BMSview/blob/HEAD/INSIGHTS_UI_IMPROVEMENTS.md), [SESSION_COMPLETE.md](https://github.com/Treystu/BMSview/blob/HEAD/SESSION_COMPLETE.md)