@chanlerdev/scorel 0.0.1

package/docs/spec/ship/S0038-webui-cancel-multiclient.md

@@ -0,0 +1,65 @@
+# S0038: WebUI Cancel And Multi-client Share
+
+## Goal
+
+Wire WebUI composer Cancel to daemon `cancel` (restored in S0032), and validate that WebUI and CLI sharing the same remote daemon session see identical event streams in real time.
+
+## Scope
+
+- Composer Cancel button:
+  - Visible only while a turn is in flight (`turn_start` received, `turn_end` not yet).
+  - Click calls `client.cancel()`. Optimistic UI: button enters "cancelling…" state until daemon echoes a `turn_end` with `stopReason: "cancelled"` (or equivalent).
+  - On daemon error response, surface inline error and re-enable Send.
+- Cancel hotkey: `Esc` while composer is focused, mirrors button. Document behavior.
+- Optimistic semantics:
+  - Server-side cancellation is best-effort (S0032 acceptance criteria); UI must not pretend a turn ended until daemon confirms.
+- Multi-client smoke wiring:
+  - No code in this spec for the smoke itself; it's a manual validation. But add a `lib/diagnostics/connection-summary.ts` exposing `Device.id`, `remoteIdentity.deviceId`, currently subscribed `sessionId`, and last applied `streamLastSeq`. Render a dev-only debug panel under `/devices/:deviceId/projects/:projectSlug/sessions/:sessionId?debug=1` that shows this summary.
+- Manual smoke (recorded in spec as the validation):
+  1. Start daemon with real LLM provider.
+  2. Open WebUI on the same session.
+  3. Open `scorel attach --remote ws://... --session <id>` simultaneously.
+  4. Send prompt from WebUI; verify CLI shows identical events.
+  5. Send prompt from CLI; verify WebUI shows identical events.
+  6. While a long tool call runs, click Cancel in WebUI; verify both clients receive `turn_end` with cancelled stop reason.
+  7. Repeat (6) but click cancel in CLI (Ctrl-C); verify both clients receive cancelled.
+
+## Not In Scope
+
+- `New Chat` (S0039).
+- WebUI implementation of `scorel attach`-style logs panel.
+- Automated end-to-end harness (Playwright); manual is fine v1.
+
+## Acceptance Criteria
+
+- WebUI Cancel button appears at the right time, dispatches `cancel`, transitions UI on daemon `turn_end`.
+- Esc keybind works.
+- Diagnostics debug panel renders the documented summary when `?debug=1` is appended; absent otherwise.
+- Manual smoke (above) passes on a real daemon + real LLM provider.
+- `pnpm --filter @scorel/webui typecheck && pnpm --filter @scorel/webui test` passes.
+- Repo `pnpm typecheck && pnpm test` passes.
+
+## Tests
+
+- Composer cancel-button visibility tests (turn_start visible, turn_end hidden, error keeps button hidden).
+- Cancel dispatch test: clicking calls `client.cancel()`; daemon error response shows inline error.
+- Esc hotkey test (jsdom keyboard event).
+- Manual smoke: documented above.
+
+## Affected Paths
+
+- `apps/webui/components/chatbox/composer.tsx` (extend with Cancel)
+- `apps/webui/components/chatbox/composer.test.tsx`
+- `apps/webui/lib/connection/session.ts` (track `inFlight` state from turn events)
+- `apps/webui/lib/diagnostics/connection-summary.ts` (new)
+- `apps/webui/components/chatbox/debug-panel.tsx` (new — only mounted when `?debug=1`)
+- `apps/webui/app/devices/[deviceId]/projects/[projectSlug]/sessions/[sessionId]/page.tsx` (mount debug panel conditionally)
+- `docs/ROADMAP.md` (M5 step entry for S0038)
+- `self/discussions/2026-05-30-webui-rebuild-brainstorm.md` (append manual smoke result note)
+
+## Risks And Boundaries
+
+- Cancellation race: the user may click Cancel while a `turn_end` is in flight; UI must accept the late `turn_end` and clear the cancelling state cleanly.
+- Multi-tab WebUI on the same session: each tab dispatches its own cancel; daemon dedup by session id; final `turn_end` is shared.
+- Debug panel must be inert in production builds — gate strictly by `?debug=1`; do not ship it on by default.
+- Smoke is manual; document it precisely so the next person runs it identically.

package/docs/spec/ship/S0039-webui-e2e-newchat.md

@@ -0,0 +1,74 @@
+# S0039: WebUI End-to-End Validation And New Chat
+
+## Goal
+
+Add `New Chat` (creates a new session under the currently selected project) and run a full real-daemon, real-LLM end-to-end pass. This spec is the gate for marking M5 WebUI Done.
+
+## Scope
+
+- `New Chat` action in sidebar:
+  - Visible only when a project is selected (`/devices/:deviceId/projects/:projectSlug` or descendants).
+  - Click flow:
+    1. Call `client.createSession({ meta: { projectSlug, model: <default-from-daemon-config>, title: "New chat" } })`.
+    2. Daemon returns `{ sessionId }`.
+    3. Optimistically prepend the new session to `DeviceProject.sessions`.
+    4. Navigate to `/devices/:deviceId/projects/:projectSlug/sessions/:sessionId`.
+  - Failure: surface inline toast/banner; do not navigate.
+- Session-creation server side already exists (`create_session` in protocol/daemon). v1 does not introduce cwd input; the daemon decides cwd by its own startup. Document this.
+- End-to-end validation matrix (manual, gated on real LLM provider):
+  1. Fresh state: clear `~/.scorel/`, clear browser localStorage.
+  2. Start daemon: `scorel daemon serve --remote --token TOKEN --port PORT --cwd /path/to/repo`.
+  3. WebUI: open root, navigate to `/settings`, add Device with the daemon's link/token. Verify sidebar dot turns green.
+  4. Verify Device → Project tree shows the cwd's project; `displayName` is `basename(cwd)`.
+  5. Click `New Chat`. Verify navigation to a new session route and an empty chatbox.
+  6. Send "list files" prompt. Verify streaming text + tool call(s) + tool result(s) render correctly.
+  7. Click Cancel mid-tool-loop on a longer prompt; verify cancel acknowledged.
+  8. Open `scorel attach --remote ws://… --session <id>` in another terminal; verify both clients show identical transcript.
+  9. Send prompt from CLI; verify WebUI updates live.
+  10. Reload WebUI tab; chatbox restored from cache, then resyncs.
+  11. Stop daemon; sidebar shows offline state. Restart daemon; click Reconnect; sidebar returns to green.
+  12. Refresh `~/.scorel/sessions/`: confirm a JSONL file exists with the right `projectSlug` in header.
+- WebUI README in `apps/webui/README.md` documenting the dev workflow:
+  - install / dev / build commands
+  - how to point WebUI at a real daemon
+  - known limitations (token cleartext in localStorage; manual reconnect on errors; no Skills/Plugins/Automations v1)
+
+## Not In Scope
+
+- Optional Playwright wiring is welcome but not required; if added, it is supplementary to the manual matrix.
+- Custom `cwd` input on `New Chat`.
+- Project search, session search.
+- Branch / fork / compact UX.
+
+## Acceptance Criteria
+
+- `New Chat` button creates a session via daemon and navigates to it; failure shows banner without navigating.
+- Manual end-to-end validation matrix above passes on a real daemon + real LLM provider on the engineer's local machine; results recorded in `self/discussions/2026-05-30-webui-rebuild-brainstorm.md` append section.
+- README in `apps/webui` describes the user-visible dev workflow accurately.
+- `pnpm --filter @scorel/webui typecheck && pnpm --filter @scorel/webui test` passes.
+- Repo `pnpm typecheck && pnpm test` passes.
+- `docs/ROADMAP.md` M5 status updated to **Done** in this spec's commit chain (only the final spec flips status).
+
+## Tests
+
+- Unit test for `New Chat` action: stubs `createSession`, asserts optimistic prepend + navigation.
+- Failure path test: error response keeps cache untouched and surfaces banner.
+- Manual: full matrix as above.
+
+## Affected Paths
+
+- `apps/webui/lib/sync/session-create.ts` (new)
+- `apps/webui/lib/sync/session-create.test.ts` (new)
+- `apps/webui/components/shell/new-chat-button.tsx` (new)
+- `apps/webui/components/shell/sidebar.tsx` (mount New Chat in proper slot)
+- `apps/webui/README.md` (new)
+- `docs/ROADMAP.md` (M5 status → Done)
+- `docs/spec/client.md` (note `createSession` is part of WebUI flow now)
+- `self/discussions/2026-05-30-webui-rebuild-brainstorm.md` (append validation results)
+
+## Risks And Boundaries
+
+- **`New Chat` cwd**: v1 ties new sessions to daemon cwd. If a user wants different cwd, they must run a separate daemon. Document clearly.
+- **Default model**: pulled from daemon config. WebUI does not let the user pick model v1; raise as a follow-up.
+- **Manual matrix repeatability**: relies on the engineer's environment; record exact commands and observed behavior in the discussion log so the next pass is reproducible.
+- **Marking M5 Done**: once this spec ships, ROADMAP M5 status flips to Done; any further WebUI feature work uses new milestone or post-M5 specs.

package/docs/spec/ship/S0040-webui-codex-visual-tokens.md

@@ -0,0 +1,227 @@
+# S0040: WebUI Codex-Style Visual Pass + Design Tokens
+
+## Goal
+
+Replace the v1 zinc-grayscale Tailwind utility soup with a Codex App-style visual pass: warm-paper background, ink-blue accent, serif display + sans body + JetBrains Mono code. Introduce CSS-variable-backed design tokens so every component reads semantic classes (`bg-surface`, `text-muted`, `border-subtle`, `text-accent`) instead of literal hex / `zinc-*`. No new functionality — purely a visual + token foundation that S0041 (markdown) and S0042 (streaming UX) build on.
+
+Locked decisions live in `self/discussions/2026-05-31-webui-polish-brainstorm.md` §5.5 and §5.5.1. This spec is the implementation contract.
+
+## Scope
+
+### Design tokens — `apps/webui/app/globals.css`
+
+Define semantic CSS variables on `:root`. **Do not write `dark:` variants in this spec; dark mode is backlog.** Schema:
+
+```css
+:root {
+  /* color */
+  --color-bg: #f6f1e7;            /* warm paper */
+  --color-surface: #fbf7ee;       /* card / sidebar surface */
+  --color-surface-raised: #ffffff;/* composer, modal */
+  --color-border: #e6dfd0;        /* subtle separator */
+  --color-border-strong: #c9bfa8;
+  --color-text: #1f1b16;          /* primary text */
+  --color-text-muted: #5b524a;
+  --color-text-faint: #8a8076;
+  --color-accent: #1e3a8a;        /* ink-blue primary action */
+  --color-accent-hover: #1e40af;
+  --color-accent-soft: #dbe3f5;   /* accent background tint */
+  --color-status-ok: #2f7d4f;
+  --color-status-warn: #b27a18;
+  --color-status-err: #b3261e;
+  --color-status-idle: #8a8076;
+
+  /* typography */
+  --font-display: "Newsreader", ui-serif, Georgia, serif;
+  --font-body: -apple-system, BlinkMacSystemFont, "Segoe UI", system-ui, sans-serif;
+  --font-mono: "JetBrains Mono", ui-monospace, "SF Mono", Menlo, monospace;
+
+  /* sizes */
+  --text-xs: 12px;  --leading-xs: 18px;
+  --text-sm: 13px;  --leading-sm: 20px;
+  --text-base: 14px; --leading-base: 22px;
+  --text-md: 16px;  --leading-md: 24px;
+  --text-lg: 18px;  --leading-lg: 26px;
+  --text-xl: 22px;  --leading-xl: 30px;
+
+  /* spacing — 4px step */
+  --space-1: 4px; --space-2: 8px; --space-3: 12px; --space-4: 16px;
+  --space-5: 20px; --space-6: 24px; --space-8: 32px;
+
+  /* radius */
+  --radius-sm: 4px; --radius-md: 6px; --radius-lg: 10px;
+
+  /* shadow */
+  --shadow-sm: 0 1px 2px rgba(31, 27, 22, 0.05);
+  --shadow-md: 0 2px 8px rgba(31, 27, 22, 0.08);
+  --shadow-focus: 0 0 0 3px rgba(30, 58, 138, 0.25);
+}
+```
+
+### Tailwind theme.extend — `apps/webui/tailwind.config.ts`
+
+Map every CSS var to a Tailwind utility. After this spec, components write `bg-surface`, `text-muted`, `border-subtle`, `text-accent`, `font-display`, `text-md`, `space-y-3`, `rounded-md`, `shadow-md`, etc. Concretely:
+
+```ts
+theme: {
+  extend: {
+    colors: {
+      bg: "var(--color-bg)",
+      surface: "var(--color-surface)",
+      "surface-raised": "var(--color-surface-raised)",
+      border: { DEFAULT: "var(--color-border)", strong: "var(--color-border-strong)" },
+      subtle: "var(--color-border)",
+      faint: "var(--color-text-faint)",
+      muted: "var(--color-text-muted)",
+      accent: { DEFAULT: "var(--color-accent)", hover: "var(--color-accent-hover)", soft: "var(--color-accent-soft)" },
+      status: {
+        ok: "var(--color-status-ok)",
+        warn: "var(--color-status-warn)",
+        err: "var(--color-status-err)",
+        idle: "var(--color-status-idle)",
+      },
+    },
+    textColor: {
+      DEFAULT: "var(--color-text)",
+      muted: "var(--color-text-muted)",
+      faint: "var(--color-text-faint)",
+      accent: "var(--color-accent)",
+    },
+    fontFamily: {
+      display: "var(--font-display)",
+      sans: "var(--font-body)",
+      mono: "var(--font-mono)",
+    },
+    fontSize: {
+      xs: ["var(--text-xs)", "var(--leading-xs)"],
+      sm: ["var(--text-sm)", "var(--leading-sm)"],
+      base: ["var(--text-base)", "var(--leading-base)"],
+      md: ["var(--text-md)", "var(--leading-md)"],
+      lg: ["var(--text-lg)", "var(--leading-lg)"],
+      xl: ["var(--text-xl)", "var(--leading-xl)"],
+    },
+    spacing: {
+      1: "var(--space-1)", 2: "var(--space-2)", 3: "var(--space-3)",
+      4: "var(--space-4)", 5: "var(--space-5)", 6: "var(--space-6)", 8: "var(--space-8)",
+    },
+    borderRadius: { sm: "var(--radius-sm)", md: "var(--radius-md)", lg: "var(--radius-lg)" },
+    boxShadow: {
+      sm: "var(--shadow-sm)",
+      md: "var(--shadow-md)",
+      focus: "var(--shadow-focus)",
+    },
+  },
+},
+```
+
+### Fonts — self-host woff2
+
+- Add dev dependency `@fontsource/newsreader` (serif display) and `@fontsource/jetbrains-mono`.
+- Body sans uses platform `system-ui` stack (no font load → instant first paint).
+- Import the two npm font packages in `apps/webui/app/layout.tsx` once at the top: `import "@fontsource/newsreader/400.css"; import "@fontsource/newsreader/600.css"; import "@fontsource/jetbrains-mono/400.css"; import "@fontsource/jetbrains-mono/500.css";`
+- No Google Fonts network calls. Document in README that fonts are bundled.
+
+### Component refactor (utility-class swap)
+
+Replace literal `zinc-*` / `emerald-*` / `red-*` / `amber-*` references with semantic tokens across:
+
+- `apps/webui/app/layout.tsx` — `bg-bg text-text font-sans`; main shell flex layout untouched.
+- `apps/webui/components/shell/topbar.tsx` — `bg-surface border-b border-subtle`; title in `font-display text-lg`; "disconnected" badge uses `text-faint`; Settings link uses `text-accent hover:text-accent-hover`.
+- `apps/webui/components/shell/sidebar.tsx` — `bg-surface border-r border-subtle`; section headers `font-display text-sm text-muted`; tree rows `text-sm text-text`; active row `bg-accent-soft text-accent` + left border 2px accent.
+- `apps/webui/components/shell/device-status.tsx` — dot colors map: idle→`bg-status-idle`, connecting/reconnecting→`bg-status-warn`, connected→`bg-status-ok`, error→`bg-status-err`. Tooltip text uses semantic colors.
+- `apps/webui/components/shell/project-node.tsx` / `session-node.tsx` / `new-chat-button.tsx` — same swap.
+- `apps/webui/components/settings/device-form.tsx` / `device-list.tsx` — form fields adopt `bg-surface-raised border border-subtle rounded-md`; primary submit `bg-accent text-surface-raised hover:bg-accent-hover`; destructive (Delete) `text-status-err border-status-err`.
+- `apps/webui/components/chatbox/composer.tsx` — textarea on `bg-surface-raised border border-subtle rounded-md` with `focus-visible:shadow-focus`; Send button `bg-accent`; Cancel button `bg-status-err` only while in-flight.
+- `apps/webui/components/chatbox/transcript.tsx` — `bg-bg`; turn separator uses `border-t border-subtle/50`.
+- `apps/webui/components/chatbox/turn-user.tsx` — user bubble `bg-accent-soft border border-subtle rounded-md p-3`; text in `text-text` body sans.
+- `apps/webui/components/chatbox/turn-assistant.tsx` — assistant `bg-surface border border-subtle rounded-md p-3`; serif display reserved for any future heading inside content (not used in this spec).
+- `apps/webui/components/chatbox/turn-tool.tsx` — `bg-surface-raised border border-subtle rounded-md`; collapse toggle uses `text-accent`; JSON dump in `font-mono text-xs text-muted`.
+- `apps/webui/components/chatbox/debug-panel.tsx` — keep fixed bottom-right; `bg-surface-raised text-text border border-subtle shadow-md font-mono text-xs`. Header `font-display text-sm`.
+
+### Focus ring + hover globals
+
+- All interactive elements use `focus-visible:outline-none focus-visible:shadow-focus` (no rings on mouse focus).
+- Button hover uses double axis: `hover:bg-*-hover hover:border-strong`.
+- Add a `.btn-primary` / `.btn-ghost` / `.btn-danger` class set in `globals.css` for Send / Cancel / Delete reuse, OR keep utility-only — pick utility-only for v1 to avoid CSS-vs-Tailwind dual ownership. Document choice inline.
+
+### Layout density
+
+- Sidebar internal padding `p-3` (12px), section gap `space-y-2`, row height ~28px.
+- Chatbox transcript max-width `max-w-3xl mx-auto` to mirror Codex App reading width on wide screens.
+- Composer fixed bottom of chatbox column with `p-3` and 1px top border.
+- Topbar height ~44px (`h-11`), `px-4`.
+
+### Boundary rule update
+
+- `apps/webui/src/package-boundaries.test.ts`: extend the allowed externals to include the two `@fontsource/*` packages. Justify each in PR description.
+
+## Not In Scope
+
+- Dark mode (backlog).
+- Markdown / code highlight rendering inside chatbox (S0041).
+- Streaming cursor animation, autoscroll behavior, jump-to-bottom button (S0042).
+- Tool block specialization (Bash/Edit/diff viewer; not in this milestone — unified rendering decided in §5.5).
+- Cmd+K, keyboard shortcuts, sidebar collapse persistence (backlog).
+- Base UI integration scaffolding (introduced as needed in S0041 / later spec; this spec stays utility-only).
+- Tailwind plugin `@tailwindcss/typography` — not added until S0041 needs it for markdown prose.
+- Animations beyond focus ring transitions.
+
+## Acceptance Criteria
+
+- `apps/webui/app/globals.css` defines every CSS var listed in §Scope under `:root`.
+- `apps/webui/tailwind.config.ts` `theme.extend` exposes them as semantic Tailwind classes.
+- No literal `zinc-*` / `emerald-*` / `red-*` / `amber-*` colors remain in `apps/webui/{app,components}/**/*.{ts,tsx}`. Verified by an extended boundary test.
+- Every interactive element (button, link, input, summary, listitem with click) has `focus-visible:shadow-focus`.
+- `@fontsource/newsreader` and `@fontsource/jetbrains-mono` imported once in `app/layout.tsx`. Build emits font woff2 to static output. No Google Fonts request observed at runtime.
+- Topbar, Sidebar, Chatbox, Settings page, Composer all visibly use warm-paper background, serif display for headings, ink-blue accent for primary actions.
+- `apps/webui/src/package-boundaries.test.ts` extended:
+  1. Allowed externals: include `@fontsource/newsreader` and `@fontsource/jetbrains-mono`.
+  2. New rule: scan non-test `.ts`/`.tsx` under `app/`, `components/` and fail if any literal `(zinc|emerald|red|amber|sky|stone|slate|gray)-\d{2,3}` appears (regex match in className strings). The test allows the matched class only inside test files (already excluded).
+- `pnpm --filter @scorel/app-webui typecheck && pnpm --filter @scorel/app-webui test` passes.
+- `pnpm --filter @scorel/app-webui build` succeeds; bundle size delta from font packages documented in PR description.
+- Repo-level `pnpm typecheck && pnpm test` passes.
+- Manual visual check (browser, after `pnpm --filter @scorel/app-webui dev`): seven routes render with the new visual; engineer takes a screenshot of the chatbox route and pastes it into PR description.
+
+## Tests
+
+- Extend `apps/webui/src/package-boundaries.test.ts` with:
+  - `it("forbids literal palette utilities outside design tokens")` — regex over allowed source files.
+  - `it("allows @fontsource/* packages in externals whitelist")` — import scanner already covers this; add explicit assertion.
+- Update one existing component test (`device-status.test.tsx` is the cleanest) to assert the dot now uses `bg-status-ok` etc., not `bg-emerald-500`.
+- All other component tests should keep passing without modification (semantic classes are interchangeable with literal palette as far as Testing Library assertions on visible text go). If any test asserts a literal palette className, update it to the new token name.
+- Manual: run `pnpm --filter @scorel/app-webui dev`; click through Settings → Add Device → /devices/:id → Project → Session → New Chat. Confirm the warm paper + ink-blue + serif headings impression on each screen.
+
+## Affected Paths
+
+- `apps/webui/app/globals.css`
+- `apps/webui/app/layout.tsx`
+- `apps/webui/tailwind.config.ts`
+- `apps/webui/package.json` (+ `pnpm-lock.yaml`) — add `@fontsource/newsreader`, `@fontsource/jetbrains-mono`
+- `apps/webui/components/shell/topbar.tsx`
+- `apps/webui/components/shell/sidebar.tsx`
+- `apps/webui/components/shell/device-status.tsx`
+- `apps/webui/components/shell/device-status.test.tsx`
+- `apps/webui/components/shell/project-node.tsx`
+- `apps/webui/components/shell/session-node.tsx`
+- `apps/webui/components/shell/new-chat-button.tsx`
+- `apps/webui/components/settings/device-form.tsx`
+- `apps/webui/components/settings/device-list.tsx`
+- `apps/webui/components/chatbox/composer.tsx`
+- `apps/webui/components/chatbox/transcript.tsx`
+- `apps/webui/components/chatbox/turn-user.tsx`
+- `apps/webui/components/chatbox/turn-assistant.tsx`
+- `apps/webui/components/chatbox/turn-tool.tsx`
+- `apps/webui/components/chatbox/debug-panel.tsx`
+- `apps/webui/src/package-boundaries.test.ts`
+- `docs/ROADMAP.md` — add M5.10 polish stage entry, flip S0040 row to Done
+- `apps/webui/README.md` — note self-hosted fonts and design token approach
+
+## Risks And Boundaries
+
+- **Color contrast**: warm paper + ink-blue passes WCAG AA on body text but the muted variant (`#5b524a` on `#f6f1e7`) sits near the threshold. If a reviewer eyeballs it as too low, raise `--color-text-muted` luminance one notch — do not ship below AA.
+- **Font load FOUT**: woff2 self-hosted is fast but still flashes once. Acceptable v1; document.
+- **Token churn**: changing one CSS var shifts the whole UI. That is the point. PR review must walk every screen.
+- **Tailwind 4 + var-only colors**: Tailwind 4's color resolver supports `var()` natively; no `rgb(var(--x) / <alpha-value>)` trick needed. Verify in `next build`.
+- **Boundary test regex**: the literal-palette ban must allow `prose-zinc` (Tailwind typography plugin variant) once S0041 adds it; regex should match standalone `\b(zinc|...)-\d` only, not as a suffix or prefix component. Implement carefully.
+- **No dark mode**: every CSS var is single-value. When dark mode lands, flip to `prefers-color-scheme: dark` block in `globals.css` reusing the same var names. Components stay unchanged.
+- **PR scope**: this spec touches almost every UI file. Keep one commit per `S0040: feat: …` per repo convention; final commit message: `S0040: feat: apply codex-style visual pass with design tokens`.

package/docs/spec/ship/S0041-webui-markdown-and-tool-block.md

@@ -0,0 +1,248 @@
+# S0041: WebUI Markdown Rendering, Code Highlight, Unified Tool Block
+
+## Goal
+
+Replace the v1 plain `<pre>` text in `turn-user.tsx` / `turn-assistant.tsx` with a real markdown renderer (GFM + sanitize), add lazy-loaded Shiki code highlighting, render thinking blocks (default folded), and route the existing tool result JSON dump through the same markdown pipeline so every turn type shares one rendering path. Locks the stack chosen in `self/discussions/2026-05-31-webui-polish-brainstorm.md` §8.2.2.
+
+Builds on S0040 design tokens (semantic colors, fonts, focus ring).
+
+## Stack
+
+- `react-markdown@^10.1.0` — React-tree renderer, no `dangerouslySetInnerHTML`.
+- `remark-gfm@^4.0.1` — tables, task lists, strikethrough, autolink.
+- `rehype-sanitize@^6.0.0` — schema-based hast sanitization (XSS guard).
+- `shiki@^4.1.0` + `@shikijs/rehype@^4.1.0` — VS Code-grade syntax highlighting, lazy split out of the main bundle.
+- `@tailwindcss/typography@^0.5.x` (Tailwind 4 compatible) — provides `prose` defaults; tinted to design tokens.
+
+## Scope
+
+### `apps/webui/components/chatbox/markdown-view.tsx` (new)
+
+Single source of truth for any markdown-bearing content. Exports `<MarkdownView text={...} />`.
+
+Behavior:
+
+- `react-markdown` configured with `remarkPlugins=[remarkGfm]`, `rehypePlugins=[[rehypeSanitize, sanitizeSchema]]`.
+- **Never enable `rehype-raw`.** Document inline.
+- Custom `components`:
+  - `code` (inline) → `<code class="rounded bg-surface-raised px-1 text-mono text-xs">`.
+  - `code` (block) → lazy `<ShikiCodeBlock>` (see below). Fallback `<pre><code>` shown via `<Suspense>`.
+  - `a` → `target="_blank" rel="noreferrer noopener"` forced; tokenized class `text-accent hover:text-accent-hover underline-offset-2 hover:underline`.
+  - `table` / `th` / `td` → `border border-subtle text-sm` (typography plugin handles most, this enforces token).
+  - `ul[data-task-list] li` (GFM task list) → unstyled bullet, checkbox stays as rendered.
+- Wrapper `<div class="prose prose-sm max-w-none">` plus `prose-tweak` overrides (defined in `globals.css`) to swap heading/link/code colors to design tokens.
+- Memoize the component on the `text` prop. Same prop reference → no re-parse.
+
+### `apps/webui/components/chatbox/shiki-code-block.tsx` (new, lazy)
+
+Default-export only, imported via `lazy(() => import("./shiki-code-block"))` from `markdown-view.tsx`.
+
+Behavior:
+
+- Uses `createHighlighterCore` from Shiki with **on-demand language imports** so the initial chunk only carries the highlighter engine + theme; languages stream in.
+- Single highlighter singleton at module scope.
+- Theme: one light theme that matches design tokens — pick `github-light-default` (warm) and override its background via wrapper to `bg-surface-raised`.
+- Props: `{ lang: string; code: string }`.
+- If `lang` not yet loaded: kick off `loadLanguage(lang)` once, render `<pre>{code}</pre>` until ready, then re-render highlighted.
+- "Copy" button at top-right of each code block (icon-only, `text-faint hover:text-text`); uses `navigator.clipboard.writeText`.
+
+### `apps/webui/components/chatbox/turn-user.tsx` (modify)
+
+Replace `<pre class="whitespace-pre-wrap font-sans text-sm">{part.text}</pre>` with `<MarkdownView text={part.text} />`.
+
+User markdown is rendered (matches ChatGPT / Claude norms). User input is local — no untrusted source — but still passes through the same sanitizer for consistency.
+
+### `apps/webui/components/chatbox/turn-assistant.tsx` (modify)
+
+Same swap for the `text` part. Streaming text path also routes through `MarkdownView`. Streaming cursor (▋) handled in S0042; this spec keeps current `▋` rendering as a sibling element next to `MarkdownView`, not interleaved into the markdown stream.
+
+Add a new render branch for **thinking** parts: when `part.kind === "thinking"`, render a default-collapsed `<details>` block:
+
+```tsx
+<details class="border border-subtle rounded-md p-2 my-2 bg-surface text-muted">
+  <summary class="cursor-pointer select-none font-display text-sm">Thinking…</summary>
+  <MarkdownView text={part.text} />
+</details>
+```
+
+Thinking is folded by default per locked decision. The protocol already carries `ThinkingContentBlock`; the projector currently treats it as text — extend `lib/events/projector.ts` so an assistant content block of type `"thinking"` becomes a `TurnPart` with `kind: "thinking"`. Update the union type accordingly.
+
+### `apps/webui/components/chatbox/turn-tool.tsx` (modify, unify)
+
+Replace the raw JSON dump with a unified-rendering path:
+
+```tsx
+const fenced = "```json\n" + JSON.stringify(payload, null, 2) + "\n```";
+return <MarkdownView text={fenced} />;
+```
+
+The `tool_call` and `tool_result` parts both pass their structured payload (args / result) through this fence. Shiki highlights the JSON automatically. Keeps the "unified rendering" decision (§5.5) intact: no Bash/Edit/diff specialization; just one path.
+
+The collapsible `<details>` outer wrapper stays — collapsed by default for `tool_call`, expanded by default for `tool_result` whose `isError === true`.
+
+### `apps/webui/lib/events/projector.ts` (modify)
+
+Extend `TurnPart` union:
+
+```ts
+export type TurnPart =
+  | { kind: "text"; text: string }
+  | { kind: "thinking"; text: string }                           // new
+  | { kind: "tool_call"; toolCallId: string; toolName: string; args: unknown }
+  | { kind: "tool_result"; toolCallId: string; toolName: string; result: unknown; isError?: boolean };
+```
+
+When projecting an `assistant_message`, walk `message.content`:
+
+- `text` → push `{kind: "text", text}`.
+- `thinking` → push `{kind: "thinking", text}`.
+- `tool_call` → unchanged.
+
+For streaming, `text_delta` continues to merge into the in-flight `text` part. **Thinking blocks are not streamed today** (no transient delta for thinking); they only appear in the final `assistant_message`. Document.
+
+### `apps/webui/app/globals.css` (modify)
+
+Add `prose-tweak` overrides to align Tailwind typography defaults to design tokens. Example:
+
+```css
+.prose-tweak {
+  --tw-prose-body: var(--color-text);
+  --tw-prose-headings: var(--color-text);
+  --tw-prose-links: var(--color-accent);
+  --tw-prose-bold: var(--color-text);
+  --tw-prose-code: var(--color-text);
+  --tw-prose-pre-bg: var(--color-surface-raised);
+  --tw-prose-pre-code: var(--color-text);
+  --tw-prose-quotes: var(--color-text-muted);
+  --tw-prose-th-borders: var(--color-border);
+  --tw-prose-td-borders: var(--color-border);
+}
+```
+
+Wrapper in `markdown-view.tsx`: `<div class="prose prose-sm max-w-none prose-tweak">`.
+
+### `apps/webui/tailwind.config.ts` (modify)
+
+Add `@tailwindcss/typography` to `plugins`. Ensure Tailwind 4 compat — if the plugin is not yet released for v4 at install time, fall back to a manual minimal `prose` ruleset in `globals.css` and document. Implementation note: Tailwind 4 supports v0.5.x typography in compatible mode at the time this spec is written; verify on install.
+
+### `apps/webui/package.json` (modify)
+
+Add dependencies:
+
+```json
+"react-markdown": "^10.1.0",
+"remark-gfm": "^4.0.1",
+"rehype-sanitize": "^6.0.0",
+"shiki": "^4.1.0",
+"@shikijs/rehype": "^4.1.0",
+"@tailwindcss/typography": "^0.5.16"
+```
+
+(versions floor; pnpm install will resolve latest patch.)
+
+### `apps/webui/src/package-boundaries.test.ts` (modify)
+
+Extend `ALLOWED_EXTERNALS` with `react-markdown`, `remark-gfm`, `rehype-sanitize`, `shiki`, `@shikijs/rehype`. Add `@tailwindcss/typography` only if it appears in TS imports (it usually only lives in `tailwind.config.ts`, which is on the test scan list). PR description must justify each addition in one line.
+
+## Streaming refresh strategy
+
+Per §8.2.6:
+
+- `MarkdownView` is `memo` on `text` prop.
+- Each `text_delta` event triggers a single `setState` in the assistant turn; only that turn's `MarkdownView` re-parses.
+- A 16ms `requestAnimationFrame` batch lives in the `transcript.tsx` streaming hook (or wherever `text_delta` already integrates) so high-rate token streams cap at one parse per frame. Existing code may already throttle implicitly via React 18's automatic batching; if not, add `useEffect` + `requestAnimationFrame` flush.
+- No mid-token splitting / merge-segment optimization. Accept brief flicker on unclosed `**` or open code fences. If real-world feedback is bad, S0041.1 swaps to `streamdown` (runner-up). Document this fallback in PR.
+
+## Sanitizer schema
+
+Defined inline in `markdown-view.tsx`. Start from `defaultSchema` (`rehype-sanitize`):
+
+```ts
+const sanitizeSchema: Schema = {
+  ...defaultSchema,
+  attributes: {
+    ...defaultSchema.attributes,
+    code: [...(defaultSchema.attributes?.code ?? []), ["className"]],
+    span: [...(defaultSchema.attributes?.span ?? []), ["className"]],
+    a: [...(defaultSchema.attributes?.a ?? []), ["target"], ["rel"]],
+  },
+  tagNames: (defaultSchema.tagNames ?? []).filter(t => t !== "script" && t !== "style"),
+};
+```
+
+PR review must walk this schema once.
+
+## Not In Scope
+
+- Dark mode (backlog).
+- Streaming cursor animation, autoscroll, jump-to-bottom (S0042).
+- Tool block specialization (Bash/Edit/Read/diff viewer/TodoWrite list — not in this milestone).
+- Cmd+K / shortcuts / sidebar persistence (backlog).
+- Mermaid / KaTeX / Mathjax (none of these enabled in sanitizer schema).
+- Image rendering: defaultSchema permits `<img>` with `src` allowlist; we leave it as default but no special UI.
+- Search / find-in-transcript.
+- streamdown runner-up — only switch if real-world flicker is unacceptable; not part of this spec.
+
+## Acceptance Criteria
+
+- `MarkdownView` renders user, assistant, and tool turns through one component.
+- GFM features observable: tables, task lists, strikethrough, autolink, code fences.
+- Sanitizer drops `<script>`, `<style>`, `onerror`, `javascript:` href; verified by unit tests.
+- Code blocks render via lazy Shiki: first paint shows un-highlighted `<pre>`, then highlighted version once Shiki chunk loads. Bundle analyzer (`next build`) shows Shiki in a separate chunk, not in the main route bundle.
+- Thinking blocks render as `<details>` collapsed-by-default with serif `Thinking…` summary.
+- Tool turns render JSON via `\`\`\`json` fence, syntactically highlighted.
+- Streaming text accumulation works: while `text_delta` events flow, the assistant turn's markdown re-parses each frame; no React error boundary triggers on mid-stream unclosed markdown.
+- All link `<a>` elements have `target="_blank" rel="noreferrer noopener"`.
+- `apps/webui/src/package-boundaries.test.ts` allows the six new externals; PR description justifies each.
+- `pnpm --filter @scorel/app-webui typecheck && pnpm --filter @scorel/app-webui test` passes.
+- `pnpm --filter @scorel/app-webui build` succeeds; bundle analyzer output captured in PR description; main route `First Load JS` increase ≤ 35 KB gzip (28 KB target + headroom).
+- Repo-level `pnpm typecheck && pnpm test` passes.
+- Manual visual smoke: open chatbox; LLM reply containing headings, lists, a code block, an inline link, a table → all render with design-token colors and serif headings.
+
+## Tests
+
+- `apps/webui/components/chatbox/markdown-view.test.tsx` (new):
+  - Renders headings, lists, table, link.
+  - Strips `<script>` and `<img onerror>`.
+  - Forces `rel="noreferrer noopener"` on `<a>`.
+  - Code block falls back to `<pre>` before Shiki resolves (mock the lazy import).
+  - Memoization: same `text` prop → no re-parse (assert via render counter).
+- `apps/webui/components/chatbox/turn-tool.test.tsx` (new):
+  - Tool result with structured object → JSON fence path → renders within MarkdownView.
+  - Default collapsed for `tool_call`, expanded for error `tool_result`.
+- `apps/webui/components/chatbox/turn-assistant.test.tsx` (extend):
+  - Thinking part renders as `<details>` collapsed.
+  - Streaming text re-renders without unmount when delta extends.
+- `apps/webui/lib/events/projector.test.ts` (extend):
+  - Assistant message with thinking + text + tool_call content blocks projects to three TurnParts in order.
+- Manual: real LLM session with markdown-rich reply; visually compare to design.
+
+## Affected Paths
+
+- `apps/webui/components/chatbox/markdown-view.tsx` (new)
+- `apps/webui/components/chatbox/markdown-view.test.tsx` (new)
+- `apps/webui/components/chatbox/shiki-code-block.tsx` (new, lazy chunk)
+- `apps/webui/components/chatbox/turn-user.tsx`
+- `apps/webui/components/chatbox/turn-assistant.tsx`
+- `apps/webui/components/chatbox/turn-assistant.test.tsx`
+- `apps/webui/components/chatbox/turn-tool.tsx`
+- `apps/webui/components/chatbox/turn-tool.test.tsx` (new)
+- `apps/webui/lib/events/projector.ts`
+- `apps/webui/lib/events/projector.test.ts`
+- `apps/webui/app/globals.css` (prose-tweak overrides)
+- `apps/webui/tailwind.config.ts` (typography plugin)
+- `apps/webui/package.json` (+ `pnpm-lock.yaml`)
+- `apps/webui/src/package-boundaries.test.ts`
+- `docs/ROADMAP.md` — flip S0041 row to Done
+- `apps/webui/README.md` — note markdown stack and security considerations (no rehype-raw, sanitize schema)
+
+## Risks And Boundaries
+
+- **XSS**: hardest risk. PR review must inspect `sanitizeSchema` and confirm `rehype-raw` is absent. CI lint hint: a unit test hard-codes a malicious payload (`<img src=x onerror=alert(1)>`) and asserts it does not appear in DOM.
+- **Streaming flicker**: unclosed `**` / fence → state jump on token close. Accept v1; document. Fallback to streamdown if real-world bad.
+- **Bundle**: 28 KB target + Shiki lazy. Watch grammar JSON size — only load languages on demand. If a code block requests `lang="rust"`, Shiki fetches `wasm/onig` + `rust.json` (~50 KB gzip per language). Acceptable.
+- **Typography plugin compat**: Tailwind 4 + `@tailwindcss/typography` 0.5 may need `important: true` or a class override. If plugin breaks build, fallback path (manual prose CSS in `globals.css`) is in scope but a deviation note in PR is mandatory.
+- **Boundary test churn**: five new whitelist entries in one PR. Justify each.
+- **Thinking block UX**: defaulting to folded means users may not notice the model's reasoning trail. Acceptable; future spec can flip default per project setting.
+- **memo correctness**: `MarkdownView` `memo` on `text` only; if `components` prop is recreated each render, memo breaks. Define `components` as module-scope constant.
+- **SSR**: `react-markdown` is ESM-only and works in server components, but `turn-*.tsx` are `"use client"`, so no SSR boundary issue. Lazy Shiki import is client-only — safe.