@grackle-ai/web-components 0.110.3 → 0.112.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@grackle-ai/web-components",
-  "version": "0.110.3",
+  "version": "0.112.0",
   "description": "Presentational React component library for the Grackle web UI",
   "license": "MIT",
   "sideEffects": [
@@ -46,7 +46,7 @@
     "remark-gfm": "^4.0.0",
     "lucide-react": "~0.474.0",
     "react-router": "^7.0.0",
-    "@grackle-ai/common": "0.110.3"
+    "@grackle-ai/common": "0.112.0"
   },
   "devDependencies": {
     "@rushstack/heft": "1.2.7",

package/rush-logs/web-components._phase_build.cache.log

@@ -1,4 +1,4 @@
 Build cache hit.
-Cache key: de557b666a8980e74bc5c775dc53097f779f8d53
+Cache key: c8b4fba3a6cfb704f3582f1197cac0fc11abbc50
 Clearing cached folders: dist, storybook-static, .rush/temp/operation/_phase_build
 Successfully restored output from the build cache.

package/rush-logs/web-components._phase_build.log

@@ -10,9 +10,9 @@ transforming...
 ✓ 2715 modules transformed.
 rendering chunks...
 computing gzip size...
-dist/index.css    156.09 kB │ gzip:  20.37 kB
-dist/index.js   1,589.58 kB │ gzip: 401.03 kB
-✓ built in 5.83s
+dist/index.css    158.47 kB │ gzip:  20.60 kB
+dist/index.js   1,590.94 kB │ gzip: 401.57 kB
+✓ built in 5.74s
 [build:vite-build] Vite build completed.
- ---- build finished (39.698s) ---- 
--------------------- Finished (39.701s) --------------------
+ ---- build finished (74.958s) ---- 
+-------------------- Finished (74.961s) --------------------

package/rush-logs/web-components._phase_test.cache.log

@@ -1,4 +1,4 @@
 Build cache hit.
-Cache key: 6bc9700f6b9938b330a84bd0f8c7ef5a7e3dbfb6
+Cache key: e2794f6b3dd02e58a0ca34e8c438c22d25296c3e
 Clearing cached folders: .rush/temp/operation/_phase_test
 Successfully restored output from the build cache.

package/rush-logs/web-components._phase_test.log

@@ -5,28 +5,30 @@ The provided list of phases does not contain all phase dependencies. You may nee
 
  RUN  v3.2.4 /home/runner/work/grackle/grackle/packages/web-components
 
- ✓ src/utils/eventContent.test.ts (38 tests) 103ms
  ✓ src/utils/sessionEvents.test.ts (14 tests) 54ms
- ✓ src/utils/dashboard.test.ts (4 tests) 28ms
- ✓ src/utils/route-config.test.ts (23 tests) 45ms
- ✓ src/utils/scrollUtils.test.ts (11 tests) 19ms
- ✓ src/utils/breadcrumbs.test.ts (18 tests) 108ms
- ✓ src/components/tools/classifyTool.test.ts (6 tests) 17ms
- ✓ src/components/tools/toolCardHelpers.test.ts (10 tests) 21ms
- ✓ src/components/display/extractText.test.tsx (8 tests) 6ms
- ✓ src/components/editable/useEditableField.test.tsx (17 tests) 154ms
- ✓ src/hooks/useEventSelection.test.ts (13 tests) 114ms
- ✓ src/components/notifications/UpdateBanner.test.tsx (4 tests) 73ms
- ✓ src/components/display/McpAppWidget.test.tsx (3 tests) 251ms
- ✓ src/utils/grackleHostStyleVariables.test.ts (2 tests) 229ms
+ ✓ src/utils/eventContent.test.ts (38 tests) 139ms
+ ✓ src/utils/dashboard.test.ts (4 tests) 7ms
+ ✓ src/utils/route-config.test.ts (23 tests) 30ms
+ ✓ src/utils/scrollUtils.test.ts (11 tests) 24ms
+ ✓ src/utils/breadcrumbs.test.ts (18 tests) 55ms
+ ✓ src/components/tools/toolCardHelpers.test.ts (10 tests) 27ms
+ ✓ src/components/tools/classifyTool.test.ts (6 tests) 28ms
+ ✓ src/components/display/extractText.test.tsx (8 tests) 32ms
+ ✓ src/hooks/useEventSelection.test.ts (13 tests) 131ms
+ ✓ src/components/editable/useEditableField.test.tsx (17 tests) 200ms
+ ✓ src/components/notifications/UpdateBanner.test.tsx (4 tests) 264ms
+ ✓ src/utils/grackleHostStyleVariables.test.ts (2 tests) 540ms
+   ✓ grackleHostStyleVariables > always returns the MCP-standard fallback variables  516ms
+ ✓ src/components/display/McpAppWidget.test.tsx (3 tests) 501ms
+   ✓ McpAppWidget > mounts an iframe host for the widget  321ms
 
  Test Files  14 passed (14)
       Tests  171 passed (171)
-   Start at  14:51:21
-   Duration  13.26s (transform 2.17s, setup 0ms, collect 16.02s, tests 1.22s, environment 8.39s, prepare 5.24s)
+   Start at  22:02:20
+   Duration  16.20s (transform 2.92s, setup 0ms, collect 17.59s, tests 2.03s, environment 14.57s, prepare 5.64s)
 
 [test:vitest] Vitest completed.
-[test:storybook-test] Starting Storybook static server on port 45689...
+[test:storybook-test] Starting Storybook static server on port 38719...
 [test:storybook-test] Storybook server ready. Running interaction tests...
 jest-haste-map: duplicate manual mock found: adapter-manager
   The following files share their name; please delete one of them:
@@ -103,21 +105,21 @@ jest-haste-map: duplicate manual mock found: token-push
     * <rootDir>/packages/server/dist/__mocks__/token-push.js
     * <rootDir>/packages/server/src/__mocks__/token-push.ts
 
-jest-haste-map: duplicate manual mock found: utils/format-gh-error
-  The following files share their name; please delete one of them:
-    * <rootDir>/packages/server/dist/__mocks__/utils/format-gh-error.js
-    * <rootDir>/packages/server/src/__mocks__/utils/format-gh-error.ts
-
 jest-haste-map: duplicate manual mock found: utils/exec
   The following files share their name; please delete one of them:
     * <rootDir>/packages/server/dist/__mocks__/utils/exec.js
     * <rootDir>/packages/server/src/__mocks__/utils/exec.ts
 
+jest-haste-map: duplicate manual mock found: utils/format-gh-error
+  The following files share their name; please delete one of them:
+    * <rootDir>/packages/server/dist/__mocks__/utils/format-gh-error.js
+    * <rootDir>/packages/server/src/__mocks__/utils/format-gh-error.ts
+
 jest-haste-map: duplicate manual mock found: utils/network
   The following files share their name; please delete one of them:
     * <rootDir>/packages/server/dist/__mocks__/utils/network.js
     * <rootDir>/packages/server/src/__mocks__/utils/network.ts
 
 [test:storybook-test] Storybook interaction tests completed.
- ---- test finished (68.057s) ---- 
--------------------- Finished (68.063s) --------------------
+ ---- test finished (115.550s) ---- 
+-------------------- Finished (115.554s) --------------------

package/src/components/chat/ChatInput.module.scss

@@ -7,7 +7,7 @@
 .bar {
   @include surface-panel;
   display: flex;
-  align-items: center;
+  align-items: flex-end;
   gap: var(--space-sm);
   padding: var(--space-sm) var(--space-md);
   border-top: 1px solid var(--border-subtle);
@@ -22,9 +22,17 @@
 // Form controls
 // ---------------------------------------------------------------------------
 
-.input {
+.textarea {
   @include input-field;
   flex: 1;
+  // Auto-resizing multiline composer: starts at one row and grows (JS sets the
+  // inline height); max-height must match MAX_COMPOSER_HEIGHT_PX in ChatInput.tsx.
+  box-sizing: border-box;
+  resize: none;
+  max-height: 200px;
+  overflow-y: auto;
+  line-height: var(--line-height);
+  font-family: var(--font-ui);
 
   @include mobile {
     min-width: 0;

package/src/components/chat/ChatInput.stories.tsx

@@ -134,3 +134,38 @@ export const SendModeActive: Story = {
     await expect(canvas.getByRole("button", { name: "Send" })).toBeDisabled();
   },
 };
+
+/**
+ * The composer is multiline: a plain Enter inserts a newline and does NOT submit.
+ */
+export const ComposerEnterInsertsNewline: Story = {
+  args: {
+    mode: "send",
+    sessionId: "sess-1",
+    environmentId: "local",
+  },
+  play: async ({ canvas, args }) => {
+    const input = canvas.getByPlaceholderText("Type a message...");
+    await userEvent.type(input, "line one{Enter}line two");
+    await expect(input).toHaveValue("line one\nline two");
+    await expect(args.onSendInput).not.toHaveBeenCalled();
+  },
+};
+
+/**
+ * Ctrl/Cmd+Enter submits the composer (mirrors clicking Send) and clears the box.
+ */
+export const ComposerCtrlEnterSubmits: Story = {
+  args: {
+    mode: "send",
+    sessionId: "sess-1",
+    environmentId: "local",
+  },
+  play: async ({ canvas, args }) => {
+    const input = canvas.getByPlaceholderText("Type a message...");
+    await userEvent.type(input, "hello there");
+    await userEvent.keyboard("{Control>}{Enter}{/Control}");
+    await expect(args.onSendInput).toHaveBeenCalledWith("sess-1", "hello there");
+    await expect(input).toHaveValue("");
+  },
+};

package/src/components/chat/ChatInput.tsx

@@ -1,8 +1,14 @@
-import { useState, type FormEvent, type JSX } from "react";
+import { useState, useLayoutEffect, useRef, type FormEvent, type KeyboardEvent, type JSX } from "react";
 import type { ToastVariant } from "../../context/ToastContext.js";
 import type { Environment, PersonaData } from "../../hooks/types.js";
 import styles from "./ChatInput.module.scss";
 
+/**
+ * Maximum height (px) the composer grows to before scrolling internally.
+ * Must stay in sync with `max-height` on `.textarea` in ChatInput.module.scss.
+ */
+const MAX_COMPOSER_HEIGHT_PX: number = 200;
+
 // --- Helpers ---
 
 /** Returns true when the environment with the given ID is disconnected or in error. */
@@ -41,6 +47,77 @@ function DisconnectedBanner({ environmentId, onReconnect }: DisconnectedBannerPr
   );
 }
 
+/** Props for the auto-resizing chat composer textarea. */
+interface ComposerTextAreaProps {
+  /** Current text value. */
+  value: string;
+  /** Called on every keystroke with the new value. */
+  onChange: (value: string) => void;
+  /** Called when the user submits via Ctrl/Cmd+Enter. */
+  onSubmit: () => void;
+  /** Placeholder text shown when empty. */
+  placeholder: string;
+  /** Whether the textarea is disabled. */
+  disabled?: boolean;
+  /** Whether to auto-focus the textarea on mount. */
+  autoFocus?: boolean;
+  /** Accessible label for the textarea. */
+  ariaLabel: string;
+}
+
+/**
+ * Auto-resizing multiline chat composer.
+ *
+ * Enter inserts a newline; Ctrl/Cmd+Enter submits (the Send button submits too).
+ * The textarea grows with its content up to {@link MAX_COMPOSER_HEIGHT_PX}, then
+ * scrolls internally.
+ */
+function ComposerTextArea({
+  value,
+  onChange,
+  onSubmit,
+  placeholder,
+  disabled,
+  autoFocus,
+  ariaLabel,
+}: ComposerTextAreaProps): JSX.Element {
+  const ref = useRef<HTMLTextAreaElement>(null);
+
+  // Auto-resize: collapse to measure natural height, then grow to fit (capped).
+  useLayoutEffect(() => {
+    const el = ref.current;
+    if (!el) {
+      return;
+    }
+    el.style.height = "auto";
+    el.style.height = `${Math.min(el.scrollHeight, MAX_COMPOSER_HEIGHT_PX)}px`;
+  }, [value]);
+
+  const handleKeyDown = (e: KeyboardEvent<HTMLTextAreaElement>): void => {
+    // Ctrl/Cmd+Enter submits; plain Enter falls through to insert a newline.
+    // The isComposing guard avoids submitting mid-IME composition (e.g. CJK input).
+    if (e.key === "Enter" && (e.metaKey || e.ctrlKey) && !e.nativeEvent.isComposing) {
+      e.preventDefault();
+      onSubmit();
+    }
+  };
+
+  return (
+    <textarea
+      ref={ref}
+      rows={1}
+      value={value}
+      onChange={(e) => onChange(e.target.value)}
+      onKeyDown={handleKeyDown}
+      placeholder={placeholder}
+      disabled={disabled}
+      autoFocus={autoFocus}
+      className={styles.textarea}
+      aria-label={ariaLabel}
+    />
+  );
+}
+
 // --- Main component ---
 
 /** Chat input mode determines the action performed on submit. */
@@ -92,8 +169,8 @@ export function ChatInput({
 
   const envDisconnected = isEnvDisconnected(environmentId, environments);
 
-  const handleSubmit = (e: FormEvent): void => {
-    e.preventDefault();
+  /** Performs the mode-specific submit action. Called by the form and Ctrl/Cmd+Enter. */
+  const submit = (): void => {
     if (!text.trim()) {
       return;
     }
@@ -122,6 +199,11 @@ export function ChatInput({
     }
   };
 
+  const handleSubmit = (e: FormEvent): void => {
+    e.preventDefault();
+    submit();
+  };
+
   // --- spawn mode ---
   if (mode === "spawn") {
     return (
@@ -129,7 +211,7 @@ export function ChatInput({
         <span className={styles.badge}>
           new chat
         </span>
-        <input type="text" value={text} onChange={(e) => setText(e.target.value)} placeholder="Enter prompt..." autoFocus className={styles.input} aria-label="Enter prompt" />
+        <ComposerTextArea value={text} onChange={setText} onSubmit={submit} placeholder="Enter prompt..." autoFocus ariaLabel="Enter prompt" />
         {showPersonaSelect && (
           <select value={spawnPersonaId} onChange={(e) => setSpawnPersonaId(e.target.value)} className={styles.select} aria-label="Select persona">
             <option value="">(Default)</option>
@@ -147,7 +229,7 @@ export function ChatInput({
   if (mode === "start") {
     return (
       <form onSubmit={handleSubmit} className={styles.bar}>
-        <input type="text" value={text} onChange={(e) => setText(e.target.value)} placeholder="Type a message..." autoFocus className={styles.input} aria-label="Type a message" />
+        <ComposerTextArea value={text} onChange={setText} onSubmit={submit} placeholder="Type a message..." autoFocus ariaLabel="Type a message" />
         <button type="submit" disabled={!text.trim()} className={styles.btnPrimary}>Send</button>
       </form>
     );
@@ -159,7 +241,7 @@ export function ChatInput({
       {envDisconnected && environmentId && (
         <DisconnectedBanner environmentId={environmentId} onReconnect={onProvisionEnvironment} />
       )}
-      <input type="text" value={text} onChange={(e) => setText(e.target.value)} placeholder="Type a message..." autoFocus={!envDisconnected} disabled={envDisconnected} className={styles.input} aria-label="Type a message" />
+      <ComposerTextArea value={text} onChange={setText} onSubmit={submit} placeholder="Type a message..." autoFocus={!envDisconnected} disabled={envDisconnected} ariaLabel="Type a message" />
       <span title={envDisconnected ? "Environment is unavailable — reconnect first" : undefined}>
         <button type="submit" disabled={!text.trim() || envDisconnected} className={styles.btnPrimary}>Send</button>
       </span>

package/src/components/display/EventRenderer.module.scss

@@ -81,91 +81,7 @@
   padding-left: var(--space-xs);
   line-height: var(--line-height);
 
-  // --- Markdown element styles ---
-
-  h1, h2, h3, h4, h5, h6 {
-    margin: var(--space-sm) 0 var(--space-xs);
-    font-weight: var(--font-weight-bold);
-  }
-
-  h1 { font-size: 1.4em; }
-  h2 { font-size: 1.2em; }
-  h3 { font-size: 1.1em; }
-
-  p {
-    margin: var(--space-xs) 0;
-  }
-
-  pre {
-    @include surface-inset;
-    padding: var(--space-sm);
-    margin: var(--space-xs) 0;
-    overflow: auto;
-    font-size: 11px;
-    white-space: pre-wrap;
-  }
-
-  code {
-    font-family: var(--font-mono);
-    font-size: 0.9em;
-    background: var(--bg-overlay);
-    padding: 1px 4px;
-    border-radius: var(--radius-sm);
-  }
-
-  pre code {
-    background: none;
-    padding: 0;
-  }
-
-  table {
-    border-collapse: collapse;
-    margin: var(--space-xs) 0;
-    font-size: var(--font-size-sm);
-    width: 100%;
-  }
-
-  th, td {
-    border: 1px solid var(--border-subtle);
-    padding: var(--space-xs) var(--space-sm);
-    text-align: left;
-  }
-
-  th {
-    background: var(--bg-overlay);
-    font-weight: var(--font-weight-bold);
-  }
-
-  ul, ol {
-    padding-left: var(--space-lg);
-    margin: var(--space-xs) 0;
-  }
-
-  li {
-    margin: 2px 0;
-  }
-
-  strong {
-    font-weight: var(--font-weight-bold);
-  }
-
-  a {
-    color: var(--accent-blue);
-    text-decoration: underline;
-  }
-
-  hr {
-    border: none;
-    border-top: 1px solid var(--border-subtle);
-    margin: var(--space-sm) 0;
-  }
-
-  blockquote {
-    border-left: 3px solid var(--border-subtle);
-    padding-left: var(--space-sm);
-    margin: var(--space-xs) 0;
-    color: var(--text-secondary);
-  }
+  @include markdown-content;
 }
 
 // --- Copy button positioning ---
@@ -220,6 +136,23 @@
   font-size: var(--font-size-sm);
   line-height: var(--line-height);
 
+  @include markdown-content;
+
+  // Collapse outer block margins so the bubble hugs its markdown content.
+  & > :first-child {
+    margin-top: 0;
+  }
+
+  & > :last-child {
+    margin-bottom: 0;
+  }
+
+  // Keep wide block content (code, tables) within the bubble bounds.
+  pre,
+  table {
+    max-width: 100%;
+  }
+
   @include mobile {
     max-width: 90%;
   }

package/src/components/display/EventRenderer.stories.tsx

@@ -170,6 +170,22 @@ export const MarkdownParagraphWrapping: Story = {
   },
 };
 
+/** User input events render as markdown (bold, lists, inline code) inside the bubble. */
+export const UserMessageMarkdown: Story = {
+  args: {
+    event: makeEvent({
+      eventType: "user_input",
+      content: "Please fix **the bug** in:\n\n- `index.ts`\n- `app.ts`",
+    }),
+  },
+  play: async ({ canvas }) => {
+    await expect(canvas.getByTestId("user-input-content")).toBeInTheDocument();
+    await expect(canvas.getByText("the bug").tagName).toBe("STRONG");
+    await expect(canvas.getAllByRole("listitem")).toHaveLength(2);
+    await expect(canvas.getByText("index.ts").tagName).toBe("CODE");
+  },
+};
+
 /** System context event renders as collapsible prompt. */
 export const SystemContext: Story = {
   args: {

package/src/components/display/EventRenderer.tsx

@@ -107,13 +107,25 @@ const markdownComponents: Record<string, typeof CodeBlockWrapper> = {
   pre: CodeBlockWrapper,
 };
 
+/**
+ * Renders a markdown string with GFM support and syntax-highlighted code blocks.
+ *
+ * Shared by both assistant text events and user input events so the two render
+ * through an identical pipeline.
+ */
+function MarkdownContent({ content }: { content: string }): JSX.Element {
+  return (
+    <Markdown remarkPlugins={[remarkGfm]} rehypePlugins={[rehypePrismPlus]} components={markdownComponents}>
+      {content}
+    </Markdown>
+  );
+}
+
 /** Renders an assistant text output event with markdown formatting. */
 function TextEvent({ content }: { content: string }): JSX.Element {
   return (
     <div className={styles.textEvent}>
-      <Markdown remarkPlugins={[remarkGfm]} rehypePlugins={[rehypePrismPlus]} components={markdownComponents}>
-        {content}
-      </Markdown>
+      <MarkdownContent content={content} />
     </div>
   );
 }
@@ -140,11 +152,13 @@ function StatusEvent({ content }: { content: string }): JSX.Element {
   );
 }
 
-/** Renders a user input event, right-aligned to distinguish it from agent output. */
+/** Renders a user input event as markdown, right-aligned to distinguish it from agent output. */
 function UserInputEvent({ content }: { content: string }): JSX.Element {
   return (
     <div className={styles.userInputEvent}>
-      <span className={styles.userInputContent}>{content}</span>
+      <div className={styles.userInputContent} data-testid="user-input-content">
+        <MarkdownContent content={content} />
+      </div>
     </div>
   );
 }

package/src/components/display/EventStream.stories.tsx

@@ -5,6 +5,8 @@ import type { DisplayEvent } from "../../utils/sessionEvents.js";
 import { makeEvent, makeSession, makeEnvironment } from "../../test-utils/storybook-helpers.js";
 
 const sampleEvents: DisplayEvent[] = [
+  // User messages render as markdown, same as agent output.
+  makeEvent({ eventType: "user_input", content: "Can you check **`auth.ts`**? The `refreshToken` flow looks broken:\n\n1. token isn't refreshed before expiry\n2. the retry has an off-by-one", timestamp: "2026-01-01T00:00:00Z" }),
   makeEvent({ eventType: "text", content: "First message", timestamp: "2026-01-01T00:00:01Z" }),
   makeEvent({ eventType: "text", content: "Second message", timestamp: "2026-01-01T00:00:02Z" }),
   makeEvent({ eventType: "text", content: "Third message", timestamp: "2026-01-01T00:00:03Z" }),
@@ -12,7 +14,7 @@ const sampleEvents: DisplayEvent[] = [
 
 /** A richer set of events including non-content types for selection mode tests. */
 const mixedEvents: DisplayEvent[] = [
-  makeEvent({ eventType: "user_input", content: "Fix the bug", timestamp: "2026-01-01T00:00:01Z" }),
+  makeEvent({ eventType: "user_input", content: "Fix the **login bug** in `auth.ts`:\n\n- token isn't refreshed\n- expiry check is off-by-one", timestamp: "2026-01-01T00:00:01Z" }),
   makeEvent({ eventType: "text", content: "Looking into it.", timestamp: "2026-01-01T00:00:02Z" }),
   makeEvent({ eventType: "status", content: "running", timestamp: "2026-01-01T00:00:03Z" }),
   makeEvent({ eventType: "text", content: "Found the issue in auth.ts", timestamp: "2026-01-01T00:00:04Z" }),

package/src/mocks/mockData.ts

@@ -265,6 +265,12 @@ export const MOCK_EVENTS: SessionEvent[] = [
     content: "You are a senior backend engineer. Focus on security best practices and thorough testing.\nProject: acme/alpha — Node.js + Express REST API\nTask: Implement auth middleware using JWT tokens\n\nNote: A previous session attempted this task but was interrupted. Pick up where it left off.",
     raw: JSON.stringify({ systemContext: true }),
   },
+  {
+    sessionId: "sess-001",
+    eventType: "user_input",
+    timestamp: "2026-02-27T08:15:03Z",
+    content: "Pick up the **JWT auth migration** from the previous session. A few requirements:\n\n- use `jsonwebtoken`, not `jose`\n- access tokens expire in `24h`\n- store refresh tokens in the DB\n\nMake sure the existing tests still pass.",
+  },
   {
     sessionId: "sess-001",
     eventType: "text",
@@ -492,6 +498,12 @@ export const MOCK_EVENTS: SessionEvent[] = [
     timestamp: "2026-02-27T08:15:42Z",
     content: "All 14 tests pass. Here's a summary of the changes:\n\n### Changes made\n\n| File | Action |\n|------|--------|\n| `src/middleware/auth.ts` | Rewrote to verify JWT Bearer tokens |\n| `src/routes/login.ts` | Now issues JWT access + refresh tokens |\n| `src/routes/protected.ts` | Updated to read `req.user` from JWT payload |\n| `src/middleware/__tests__/auth.test.ts` | Updated tests for JWT verification |\n\n### Key decisions\n- **Access token expiry**: 24 hours (configurable via `JWT_SECRET` env var)\n- **Refresh tokens**: 48-byte random hex, stored in DB\n- **Error handling**: Distinguishes expired tokens (401) from invalid tokens (403)",
   },
+  {
+    sessionId: "sess-001",
+    eventType: "user_input",
+    timestamp: "2026-02-27T08:15:50Z",
+    content: "Looks great! Two follow-ups:\n\n1. add a `/refresh` endpoint that swaps a refresh token for a new access token\n2. note the token flow in `README.md`",
+  },
 
   // ── sess-002: completed unit test session ──
 

package/src/styles/mixins.scss

@@ -264,6 +264,99 @@ $tablet: 1024px;
   font-weight: var(--font-weight-medium);
 }
 
+// =============================================================================
+// Markdown Content
+// =============================================================================
+
+/// Styles for a rendered react-markdown element tree (headings, code, tables,
+/// lists, links, etc.). Applied to any container that renders markdown output,
+/// e.g. agent text events and user message bubbles.
+@mixin markdown-content {
+  h1, h2, h3, h4, h5, h6 {
+    margin: var(--space-sm) 0 var(--space-xs);
+    font-weight: var(--font-weight-bold);
+  }
+
+  h1 { font-size: 1.4em; }
+  h2 { font-size: 1.2em; }
+  h3 { font-size: 1.1em; }
+
+  p {
+    margin: var(--space-xs) 0;
+  }
+
+  pre {
+    @include surface-inset;
+    padding: var(--space-sm);
+    margin: var(--space-xs) 0;
+    overflow: auto;
+    font-size: 11px;
+    white-space: pre-wrap;
+  }
+
+  code {
+    font-family: var(--font-mono);
+    font-size: 0.9em;
+    background: var(--bg-overlay);
+    padding: 1px 4px;
+    border-radius: var(--radius-sm);
+  }
+
+  pre code {
+    background: none;
+    padding: 0;
+  }
+
+  table {
+    border-collapse: collapse;
+    margin: var(--space-xs) 0;
+    font-size: var(--font-size-sm);
+    width: 100%;
+  }
+
+  th, td {
+    border: 1px solid var(--border-subtle);
+    padding: var(--space-xs) var(--space-sm);
+    text-align: left;
+  }
+
+  th {
+    background: var(--bg-overlay);
+    font-weight: var(--font-weight-bold);
+  }
+
+  ul, ol {
+    padding-left: var(--space-lg);
+    margin: var(--space-xs) 0;
+  }
+
+  li {
+    margin: 2px 0;
+  }
+
+  strong {
+    font-weight: var(--font-weight-bold);
+  }
+
+  a {
+    color: var(--accent-blue);
+    text-decoration: underline;
+  }
+
+  hr {
+    border: none;
+    border-top: 1px solid var(--border-subtle);
+    margin: var(--space-sm) 0;
+  }
+
+  blockquote {
+    border-left: 3px solid var(--border-subtle);
+    padding-left: var(--space-sm);
+    margin: var(--space-xs) 0;
+    color: var(--text-secondary);
+  }
+}
+
 // =============================================================================
 // Animation Helpers
 // =============================================================================