@moxxy/plugin-channel-web 0.27.0

package/src/discovery.test.ts

@@ -0,0 +1,40 @@
+import { describe, expect, it, vi } from 'vitest';
+import type { ServiceRegistry } from '@moxxy/sdk';
+import { webChannelPlugin } from './index.js';
+
+/**
+ * The discovery-loadable default export resolves the tunnel registry + the
+ * shared viewSurface/webControls refs + the configured default tunnel from the
+ * service registry in onInit (a lazy `tunnels` object keeps the tools + boot
+ * hook present), instead of the host `{ getTunnel, publishSurface, … }` closure.
+ */
+describe('webChannelPlugin (discovery-loadable)', () => {
+  it('exposes the web channel + tunnel tools + an onInit hook', () => {
+    expect(webChannelPlugin.channels?.map((c) => c.name)).toContain('web');
+    const tools = webChannelPlugin.tools?.map((t) => t.name) ?? [];
+    expect(tools).toContain('web_set_tunnel');
+    expect(tools).toContain('web_tunnel_status');
+    expect(typeof webChannelPlugin.hooks?.onInit).toBe('function');
+  });
+
+  it('onInit resolves tunnelProviders + viewSurface + webControls', () => {
+    const tp = { getActive: () => null, list: () => [], setActive: () => {} };
+    const get = vi.fn((name: string) => {
+      switch (name) {
+        case 'tunnelProviders':
+          return tp;
+        case 'viewSurface':
+          return { current: null };
+        case 'webControls':
+          return { current: null };
+        default:
+          return undefined;
+      }
+    });
+    const services = { get, register: () => {}, require: () => undefined, has: () => true } as unknown as ServiceRegistry;
+    webChannelPlugin.hooks!.onInit!({ services } as never);
+    expect(get).toHaveBeenCalledWith('tunnelProviders');
+    expect(get).toHaveBeenCalledWith('viewSurface');
+    expect(get).toHaveBeenCalledWith('webControls');
+  });
+});

package/src/frontend/chat.test.ts

@@ -0,0 +1,47 @@
+import { describe, expect, it } from 'vitest';
+import { createElement } from 'react';
+import { renderToStaticMarkup } from 'react-dom/server';
+import { ChatPanel } from './chat.js';
+import type { TranscriptMessage } from './socket.js';
+
+const noop = (): void => undefined;
+const render = (messages: TranscriptMessage[], status: { text: string; error: boolean } | null = null): string =>
+  renderToStaticMarkup(createElement(ChatPanel, { messages, status, onSend: noop, onClose: noop }));
+
+describe('ChatPanel', () => {
+  it('shows a hint + the input when empty', () => {
+    const html = render([]);
+    expect(html).toContain('Chat with the agent');
+    expect(html).toMatch(/add a price filter/);
+    expect(html).toContain('placeholder="Ask for changes');
+  });
+
+  it('renders user and assistant messages distinctly', () => {
+    const html = render([
+      { role: 'user', text: 'add a price filter' },
+      { role: 'assistant', text: 'Done — filtered by price.' },
+    ]);
+    expect(html).toContain('add a price filter');
+    expect(html).toContain('Done — filtered by price.');
+    expect(html).toContain('chat-msg user');
+    expect(html).toContain('chat-msg assistant');
+  });
+
+  it('shows working / error status', () => {
+    expect(render([], { text: 'working…', error: false })).toContain('working');
+    const err = render([], { text: 'boom', error: true });
+    expect(err).toContain('chat-status err');
+    expect(err).toContain('boom');
+  });
+
+  it('is an accessible modal dialog with a live message region', () => {
+    // Focus trap / Escape / focus restoration are effect-driven and need a DOM
+    // harness (this package's vitest env is `node`); the static markup still
+    // asserts the ARIA contract a screen reader relies on.
+    const html = render([{ role: 'assistant', text: 'hi' }]);
+    expect(html).toContain('role="dialog"');
+    expect(html).toContain('aria-modal="true"');
+    expect(html).toContain('aria-live="polite"');
+    expect(html).toMatch(/role="log"/);
+  });
+});

package/src/frontend/chat.tsx

@@ -0,0 +1,138 @@
+import { useCallback, useEffect, useRef, useState, type KeyboardEvent } from 'react';
+import type { TranscriptMessage } from './socket';
+import { FileDiffView } from './render-diff';
+
+/** Whether the user has asked the OS to reduce motion (SSR-safe). */
+function prefersReducedMotion(): boolean {
+  return (
+    typeof window !== 'undefined' &&
+    typeof window.matchMedia === 'function' &&
+    window.matchMedia('(prefers-reduced-motion: reduce)').matches
+  );
+}
+
+/** Focusable descendants of a container, in DOM order, for the focus trap. */
+function focusableWithin(root: HTMLElement | null): HTMLElement[] {
+  if (!root) return [];
+  const sel = 'a[href], button:not([disabled]), input:not([disabled]), select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex="-1"])';
+  return Array.from(root.querySelectorAll<HTMLElement>(sel)).filter(
+    (el) => el.offsetParent !== null || el === document.activeElement,
+  );
+}
+
+/**
+ * On-demand chat panel (opened from the floating button) for refining the
+ * generated view. Messages flow over the same WS as `prompt` frames → an agent
+ * turn → the agent re-runs present_view and the view updates live.
+ *
+ * Implemented as an accessible modal dialog: focus moves into the input on open
+ * and is restored to the opener (the FAB) on close, Tab is trapped inside the
+ * panel, Escape dismisses it, and the message/status region is an aria-live
+ * region so screen-reader users hear the agent's replies.
+ */
+export function ChatPanel(props: {
+  messages: ReadonlyArray<TranscriptMessage>;
+  status: { text: string; error: boolean } | null;
+  onSend: (text: string) => void;
+  onClose: () => void;
+}): JSX.Element {
+  const { messages, status, onSend, onClose } = props;
+  const [text, setText] = useState('');
+  const endRef = useRef<HTMLDivElement>(null);
+  const panelRef = useRef<HTMLDivElement>(null);
+  const inputRef = useRef<HTMLInputElement>(null);
+
+  useEffect(() => {
+    endRef.current?.scrollIntoView({ behavior: prefersReducedMotion() ? 'auto' : 'smooth' });
+  }, [messages, status]);
+
+  // Focus the input on open; restore focus to the element that had it (the FAB)
+  // when the dialog unmounts, so keyboard users aren't dumped at the page top.
+  useEffect(() => {
+    const opener = typeof document !== 'undefined' ? (document.activeElement as HTMLElement | null) : null;
+    inputRef.current?.focus();
+    return () => opener?.focus?.();
+  }, []);
+
+  const onKeyDown = useCallback(
+    (e: KeyboardEvent<HTMLDivElement>) => {
+      if (e.key === 'Escape') {
+        e.stopPropagation();
+        onClose();
+        return;
+      }
+      if (e.key !== 'Tab') return;
+      // Trap Tab within the panel so focus never escapes to the obscured view.
+      const focusables = focusableWithin(panelRef.current);
+      if (focusables.length === 0) return;
+      const first = focusables[0]!;
+      const last = focusables[focusables.length - 1]!;
+      const active = document.activeElement;
+      if (e.shiftKey && active === first) {
+        e.preventDefault();
+        last.focus();
+      } else if (!e.shiftKey && active === last) {
+        e.preventDefault();
+        first.focus();
+      }
+    },
+    [onClose],
+  );
+
+  return (
+    <div
+      className="chat-panel"
+      role="dialog"
+      aria-modal="true"
+      aria-label="Chat with the agent"
+      ref={panelRef}
+      onKeyDown={onKeyDown}
+    >
+      <div className="chat-head">
+        <span>Chat with the agent</span>
+        <button className="chat-x" onClick={onClose} aria-label="Close chat">
+          ×
+        </button>
+      </div>
+      <div className="chat-msgs" role="log" aria-live="polite" aria-relevant="additions text">
+        {messages.length === 0 && (
+          <div className="chat-hint">Ask the agent to change this view — e.g. “add a price filter” or “sort by departure time”.</div>
+        )}
+        {messages.map((m, i) =>
+          m.role === 'diff' ? (
+            <FileDiffView key={i} display={m.display} />
+          ) : (
+            <div key={i} className={`chat-msg ${m.role}`}>
+              {m.text}
+            </div>
+          ),
+        )}
+        {status && (
+          <div className={status.error ? 'chat-status err' : 'chat-status'} role="status">
+            {status.error ? `⚠ ${status.text}` : status.text}
+          </div>
+        )}
+        <div ref={endRef} />
+      </div>
+      <form
+        className="chat-input"
+        onSubmit={(e) => {
+          e.preventDefault();
+          const t = text.trim();
+          if (!t) return;
+          onSend(t);
+          setText('');
+        }}
+      >
+        <input
+          ref={inputRef}
+          value={text}
+          onChange={(e) => setText(e.target.value)}
+          placeholder="Ask for changes…"
+          aria-label="Ask the agent for changes"
+        />
+        <button type="submit">Send</button>
+      </form>
+    </div>
+  );
+}

package/src/frontend/index.html

@@ -0,0 +1,178 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <!-- Defense-in-depth, mirrors the HTTP CSP header in channel.ts serveFile.
+         Scripts are 'self' only (no inline); the inline <style> below needs
+         style-src 'unsafe-inline'; connect-src permits the surface WebSocket. -->
+    <meta
+      http-equiv="Content-Security-Policy"
+      content="default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' data: https:; connect-src 'self' ws: wss:; base-uri 'none'; form-action 'none'; frame-ancestors 'none'"
+    />
+    <meta name="referrer" content="no-referrer" />
+    <title>moxxy</title>
+    <!--moxxy:base-->
+    <style>
+      :root {
+        --bg: #0f1115; --panel: #171a21; --panel2: #1e222b; --line: #2a2f3a;
+        --fg: #e6e9ef; --muted: #8b93a7; --accent: #5b8cff; --ok: #3fb950;
+        --warn: #d29922; --danger: #f85149; --radius: 10px;
+      }
+      * { box-sizing: border-box; }
+      body { margin: 0; background: var(--bg); color: var(--fg);
+        font: 15px/1.5 -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif; }
+      .app { max-width: 760px; margin: 0 auto; min-height: 100vh; display: flex; flex-direction: column; }
+      header { display: flex; align-items: center; justify-content: space-between;
+        padding: 14px 18px; border-bottom: 1px solid var(--line); font-weight: 600; }
+      header .status { font-weight: 400; font-size: 13px; color: var(--muted); }
+      header .status.ok { color: var(--ok); }
+      header .back { background: var(--panel2); color: var(--fg); border: 1px solid var(--line);
+        border-radius: 8px; padding: 4px 10px; font: inherit; font-size: 13px; cursor: pointer; margin-right: 10px; }
+      main { flex: 1; padding: 18px; display: flex; flex-direction: column; gap: 18px; }
+      .empty { color: var(--muted); text-align: center; padding: 48px 0; }
+      footer { padding: 12px 18px; border-top: 1px solid var(--line); }
+      footer form { display: flex; gap: 8px; }
+      footer input { flex: 1; background: var(--panel2); border: 1px solid var(--line);
+        color: var(--fg); border-radius: var(--radius); padding: 10px 12px; font: inherit; }
+      footer button { background: var(--accent); color: #fff; border: 0; border-radius: var(--radius);
+        padding: 0 16px; font: inherit; font-weight: 600; cursor: pointer; }
+      .transcript { display: flex; flex-direction: column; gap: 8px; }
+      .msg { padding: 9px 12px; border-radius: var(--radius); max-width: 85%; white-space: pre-wrap; }
+      .msg.user { align-self: flex-end; background: var(--accent); color: #fff; }
+      .msg.assistant { align-self: flex-start; background: var(--panel); border: 1px solid var(--line); }
+      .turn-status { color: var(--muted); font-size: 13px; font-style: italic; }
+      .turn-status.err { color: var(--danger); font-style: normal; }
+      /* view primitives */
+      .v-title { font-size: 20px; margin: 0 0 12px; }
+      .v-stack { display: flex; flex-direction: column; }
+      .v-stack[data-gap="sm"], .v-row[data-gap="sm"] { gap: 6px; }
+      .v-stack[data-gap="md"], .v-row[data-gap="md"], .v-grid[data-gap="md"] { gap: 12px; }
+      .v-stack[data-gap="lg"], .v-row[data-gap="lg"], .v-grid[data-gap="lg"] { gap: 20px; }
+      .v-stack:not([data-gap]) { gap: 10px; }
+      .v-row { display: flex; flex-direction: row; align-items: center; gap: 10px; flex-wrap: wrap; }
+      .v-row[data-align="start"] { align-items: flex-start; }
+      .v-row[data-align="end"] { align-items: flex-end; }
+      .v-row[data-justify="between"] { justify-content: space-between; }
+      .v-row[data-justify="center"] { justify-content: center; }
+      .v-row[data-justify="end"] { justify-content: flex-end; }
+      .v-grid { display: grid; gap: 12px; }
+      .v-card { background: var(--panel); border: 1px solid var(--line); border-radius: var(--radius); padding: 14px; }
+      .v-card[data-accent="success"] { border-left: 3px solid var(--ok); }
+      .v-card[data-accent="warn"] { border-left: 3px solid var(--warn); }
+      .v-card[data-accent="danger"] { border-left: 3px solid var(--danger); }
+      .v-card-title { font-weight: 600; margin-bottom: 8px; }
+      .v-divider { border: 0; border-top: 1px solid var(--line); margin: 4px 0; }
+      .v-heading { margin: 4px 0; }
+      .v-text[data-tone="muted"] { color: var(--muted); }
+      .v-text[data-tone="success"] { color: var(--ok); }
+      .v-text[data-tone="warn"] { color: var(--warn); }
+      .v-text[data-tone="danger"] { color: var(--danger); }
+      .v-text[data-weight="bold"] { font-weight: 700; }
+      .v-badge { display: inline-block; padding: 2px 8px; border-radius: 999px; font-size: 13px;
+        background: var(--panel2); border: 1px solid var(--line); }
+      .v-badge[data-tone="success"] { color: var(--ok); border-color: var(--ok); }
+      .v-badge[data-tone="warn"] { color: var(--warn); border-color: var(--warn); }
+      .v-badge[data-tone="danger"] { color: var(--danger); border-color: var(--danger); }
+      .v-image { max-width: 100%; border-radius: var(--radius); }
+      .v-link { color: var(--accent); }
+      .v-list { margin: 0; padding-left: 20px; }
+      .v-table { border-collapse: collapse; width: 100%; }
+      .v-table th, .v-table td { border: 1px solid var(--line); padding: 7px 10px; }
+      .v-table th { background: var(--panel2); }
+      .v-form { display: flex; flex-direction: column; gap: 12px; }
+      .v-field { display: flex; flex-direction: column; gap: 4px; flex: 1; min-width: 120px; }
+      .v-label { font-size: 13px; color: var(--muted); }
+      .v-field input, .v-field select { background: var(--panel2); border: 1px solid var(--line);
+        color: var(--fg); border-radius: 8px; padding: 8px 10px; font: inherit; }
+      .v-check { display: flex; align-items: center; gap: 6px; }
+      .v-form-actions { display: flex; gap: 8px; }
+      .v-btn { background: var(--panel2); color: var(--fg); border: 1px solid var(--line);
+        border-radius: 8px; padding: 8px 14px; font: inherit; cursor: pointer; }
+      .v-btn[data-variant="primary"] { background: var(--accent); color: #fff; border-color: var(--accent); }
+      .v-btn[data-variant="danger"] { background: var(--danger); color: #fff; border-color: var(--danger); }
+      .v-unknown { color: var(--warn); font-size: 13px; }
+      /* loading states */
+      .v-spinner { display: flex; align-items: center; gap: 10px; color: var(--muted); padding: 8px 0; }
+      .v-spin { width: 16px; height: 16px; border-radius: 50%; border: 2px solid var(--line);
+        border-top-color: var(--accent); animation: v-rot 0.8s linear infinite; }
+      @keyframes v-rot { to { transform: rotate(360deg); } }
+      .v-skeleton { display: flex; flex-direction: column; gap: 10px; }
+      .v-skel-row { height: 16px; border-radius: 6px;
+        background: linear-gradient(90deg, var(--panel) 25%, var(--panel2) 37%, var(--panel) 63%);
+        background-size: 400% 100%; animation: v-shimmer 1.4s ease infinite; }
+      .v-skel-row:nth-child(odd) { width: 90%; }
+      .v-skel-row:nth-child(3n) { width: 70%; }
+      @keyframes v-shimmer { 0% { background-position: 100% 50%; } 100% { background-position: 0 50%; } }
+      /* floating chat */
+      .chat-fab { position: fixed; right: 20px; bottom: 20px; width: 52px; height: 52px;
+        border-radius: 50%; border: 0; background: var(--accent); color: #fff; font-size: 22px;
+        cursor: pointer; box-shadow: 0 6px 20px rgba(0,0,0,0.45); display: flex; align-items: center;
+        justify-content: center; z-index: 50; }
+      .chat-fab:hover { filter: brightness(1.08); }
+      .chat-dot { position: absolute; top: 10px; right: 10px; width: 10px; height: 10px;
+        border-radius: 50%; background: var(--danger); border: 2px solid var(--bg); }
+      .chat-panel { position: fixed; right: 20px; bottom: 20px; width: min(380px, calc(100vw - 40px));
+        height: min(520px, calc(100vh - 40px)); background: var(--panel); border: 1px solid var(--line);
+        border-radius: 14px; box-shadow: 0 10px 40px rgba(0,0,0,0.5); display: flex; flex-direction: column;
+        overflow: hidden; z-index: 50; }
+      .chat-head { display: flex; align-items: center; justify-content: space-between;
+        padding: 12px 14px; border-bottom: 1px solid var(--line); font-weight: 600; }
+      .chat-x { background: none; border: 0; color: var(--muted); font-size: 22px; line-height: 1;
+        cursor: pointer; padding: 0 4px; }
+      .chat-x:hover { color: var(--fg); }
+      .chat-msgs { flex: 1; overflow-y: auto; padding: 12px 14px; display: flex; flex-direction: column; gap: 8px; }
+      .chat-hint { color: var(--muted); font-size: 13px; }
+      .chat-msg { padding: 8px 11px; border-radius: 12px; max-width: 88%; white-space: pre-wrap;
+        word-break: break-word; font-size: 14px; }
+      .chat-msg.user { align-self: flex-end; background: var(--accent); color: #fff; }
+      .chat-msg.assistant { align-self: flex-start; background: var(--panel2); border: 1px solid var(--line); }
+      .chat-status { color: var(--muted); font-size: 12px; font-style: italic; }
+      .chat-status.err { color: var(--danger); font-style: normal; }
+      .chat-input { display: flex; gap: 8px; padding: 10px 12px; border-top: 1px solid var(--line); }
+      .chat-input input { flex: 1; background: var(--panel2); border: 1px solid var(--line); color: var(--fg);
+        border-radius: 10px; padding: 9px 11px; font: inherit; }
+      .chat-input button { background: var(--accent); color: #fff; border: 0; border-radius: 10px;
+        padding: 0 14px; font: inherit; font-weight: 600; cursor: pointer; }
+      /* file diff */
+      .v-diff { align-self: stretch; border: 1px solid var(--line); border-radius: var(--radius);
+        overflow: hidden; background: var(--panel); font-size: 12.5px; }
+      .v-diff-head { display: flex; align-items: center; justify-content: space-between; gap: 8px;
+        padding: 6px 10px; background: var(--panel2); border-bottom: 1px solid var(--line); }
+      .v-diff-path { font-weight: 600; word-break: break-all; }
+      .v-diff-sum { color: var(--ok); font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+        white-space: nowrap; }
+      .v-diff-body { overflow-x: auto; font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+        line-height: 1.45; }
+      .v-diff-row { display: flex; white-space: pre; }
+      .v-diff-no { flex: 0 0 auto; width: 3.5em; padding: 0 8px; text-align: right; color: var(--muted);
+        user-select: none; border-right: 1px solid var(--line); }
+      .v-diff-mark { flex: 0 0 auto; width: 1.5em; text-align: center; user-select: none; color: var(--muted); }
+      .v-diff-text { flex: 1 1 auto; padding-right: 10px; }
+      .v-diff-ctx { color: var(--muted); }
+      .v-diff-add { background: rgba(63, 185, 80, 0.16); }
+      .v-diff-add .v-diff-mark, .v-diff-add .v-diff-text { color: var(--ok); }
+      .v-diff-del { background: rgba(248, 81, 73, 0.16); }
+      .v-diff-del .v-diff-mark, .v-diff-del .v-diff-text { color: var(--danger); }
+      .v-diff-gap { color: var(--muted); opacity: 0.6; }
+      .v-diff-gap .v-diff-mark { color: var(--muted); }
+      .v-diff-trunc { padding: 4px 10px; color: var(--warn); font-size: 12px;
+        border-top: 1px solid var(--line); background: var(--panel2); }
+      /* Screen-reader-only: present in the a11y tree (live-region announcements)
+         but visually removed. Standard clip pattern, no layout impact. */
+      .visually-hidden { position: absolute; width: 1px; height: 1px; padding: 0;
+        margin: -1px; overflow: hidden; clip: rect(0 0 0 0); white-space: nowrap; border: 0; }
+      /* Respect a user's reduced-motion preference: stop the infinite spinner
+         and skeleton shimmer (vestibular safety) and neutralize transitions. */
+      @media (prefers-reduced-motion: reduce) {
+        .v-spin { animation: none; }
+        .v-skel-row { animation: none; background: var(--panel2); }
+        * { transition: none !important; scroll-behavior: auto !important; }
+      }
+    </style>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script src="app.js"></script>
+  </body>
+</html>

package/src/frontend/main.tsx

@@ -0,0 +1,87 @@
+import { useEffect, useState } from 'react';
+import { createRoot } from 'react-dom/client';
+import { stripTokenFromUrl, useViewSocket } from './socket';
+import { renderNode } from './render';
+import { ChatPanel } from './chat';
+
+/**
+ * The web surface is a RENDERING surface for the agent-built app — not a chat.
+ * A floating button opens a chat panel ON DEMAND so the user can ask the agent
+ * to refine the view ("add a price filter", "make the cards bigger"); the agent
+ * re-runs present_view and the view updates live.
+ */
+function App(): JSX.Element {
+  const { connected, view, canGoBack, messages, status, dispatch, navigate, goBack, sendPrompt } = useViewSocket();
+  const [chatOpen, setChatOpen] = useState(false);
+  const [seen, setSeen] = useState(0);
+  useEffect(() => {
+    if (chatOpen) setSeen(messages.length);
+  }, [chatOpen, messages.length]);
+  const unread = !chatOpen && messages.length > seen;
+
+  return (
+    <div className="app">
+      <header>
+        <span>
+          {canGoBack && (
+            <button className="back" onClick={goBack} aria-label="Back">
+              ‹ Back
+            </button>
+          )}
+          moxxy
+        </span>
+        <span
+          className={connected ? 'status ok' : 'status'}
+          role="status"
+          aria-live="polite"
+        >
+          {connected ? '● live' : '○ connecting…'}
+        </span>
+      </header>
+      <main>
+        {view ? (
+          <div className="view">{renderNode(view.doc.root, { dispatch, navigate })}</div>
+        ) : (
+          <div className="empty">{status ? status.text : 'No view yet — ask the agent to build you an app.'}</div>
+        )}
+        {view && status && (
+          <div
+            className={status.error ? 'turn-status err' : 'turn-status'}
+            role="status"
+            aria-live="polite"
+          >
+            {status.error ? `⚠ ${status.text}` : status.text}
+          </div>
+        )}
+      </main>
+      {chatOpen ? (
+        <ChatPanel messages={messages} status={status} onSend={sendPrompt} onClose={() => setChatOpen(false)} />
+      ) : (
+        <button
+          className="chat-fab"
+          onClick={() => setChatOpen(true)}
+          aria-label={unread ? 'Chat with the agent — new message' : 'Chat with the agent'}
+        >
+          <span aria-hidden>💬</span>
+          {/* The dot is a non-text colour cue; the unread state itself is also
+              carried in aria-label above (colour is never the sole signal) and
+              announced via the off-screen live region below. */}
+          {unread && <span className="chat-dot" aria-hidden="true" />}
+        </button>
+      )}
+      {/* Off-screen live region: announces that the agent replied while the chat
+          panel is closed, so a screen-reader user isn't left silent (the red FAB
+          dot is purely visual). */}
+      <div className="visually-hidden" role="status" aria-live="polite">
+        {unread ? 'The agent sent a new message. Open chat to read it.' : ''}
+      </div>
+    </div>
+  );
+}
+
+// Drop the bearer token from the visible URL after socket.ts has captured it
+// (socket is imported above, so its module-level capture has already run).
+stripTokenFromUrl();
+
+const root = document.getElementById('root');
+if (root) createRoot(root).render(<App />);

package/src/frontend/render-diff.test.ts

@@ -0,0 +1,86 @@
+import { describe, expect, it } from 'vitest';
+import { createElement } from 'react';
+import { renderToStaticMarkup } from 'react-dom/server';
+import type { FileDiffDisplay } from '@moxxy/sdk';
+import { FileDiffView } from './render-diff.js';
+
+const render = (display: FileDiffDisplay): string => renderToStaticMarkup(createElement(FileDiffView, { display }));
+
+const baseDisplay: FileDiffDisplay = {
+  kind: 'file-diff',
+  path: 'src/foo.ts',
+  mode: 'update',
+  added: 2,
+  removed: 1,
+  hunks: [
+    {
+      oldStart: 1,
+      oldLines: 2,
+      newStart: 1,
+      newLines: 3,
+      lines: [
+        { kind: 'context', text: 'keep me', oldNo: 1, newNo: 1 },
+        { kind: 'del', text: 'old line', oldNo: 2 },
+        { kind: 'add', text: 'new line', newNo: 2 },
+        { kind: 'add', text: 'extra line', newNo: 3 },
+      ],
+    },
+  ],
+};
+
+describe('FileDiffView', () => {
+  it('renders an Update header with the path and a +/- summary', () => {
+    const html = render(baseDisplay);
+    expect(html).toContain('Update · src/foo.ts');
+    expect(html).toContain('+2 −1');
+  });
+
+  it('uses Create for new files', () => {
+    const html = render({ ...baseDisplay, mode: 'create' });
+    expect(html).toContain('Create · src/foo.ts');
+  });
+
+  it('applies add/del backgrounds and dim context classes with markers', () => {
+    const html = render(baseDisplay);
+    expect(html).toContain('v-diff-add');
+    expect(html).toContain('v-diff-del');
+    expect(html).toContain('v-diff-ctx');
+    expect(html).toContain('new line');
+    expect(html).toContain('old line');
+  });
+
+  it('shows gutter numbers (new for add/context, old for deletions)', () => {
+    const html = render(baseDisplay);
+    // del shows old number 2; first add shows new number 2; context shows 1.
+    expect(html).toMatch(/v-diff-no[^>]*>1</);
+    expect(html).toMatch(/v-diff-no[^>]*>2</);
+    expect(html).toMatch(/v-diff-no[^>]*>3</);
+  });
+
+  it('inserts a ⋯ gap row between non-contiguous hunks', () => {
+    const twoHunks: FileDiffDisplay = {
+      ...baseDisplay,
+      hunks: [
+        baseDisplay.hunks[0]!,
+        { oldStart: 40, oldLines: 1, newStart: 41, newLines: 1, lines: [{ kind: 'context', text: 'far away', oldNo: 40, newNo: 41 }] },
+      ],
+    };
+    const html = render(twoHunks);
+    expect(html).toContain('v-diff-gap');
+    expect(html).toContain('⋯');
+  });
+
+  it('renders a truncation notice when truncated', () => {
+    const html = render({ ...baseDisplay, truncated: true });
+    expect(html).toContain('diff truncated');
+  });
+
+  it('keeps the compact "+X −Y" count glyph (not the prose fileDiffSummary form)', () => {
+    // The dedup pulls rowsOf/gutter/verb from @moxxy/sdk/tool-display but
+    // deliberately keeps the local plusMinus: the shared fileDiffSummary
+    // renders "Added N lines, removed M line", which this header must NOT use.
+    const html = render(baseDisplay);
+    expect(html).toContain('+2 −1');
+    expect(html).not.toContain('Added 2 lines');
+  });
+});

package/src/frontend/render-diff.tsx

@@ -0,0 +1,66 @@
+import type { FileDiffDisplay, DiffLine } from '@moxxy/sdk';
+import { toDiffRows, diffGutterNo, fileDiffVerb } from '@moxxy/sdk/tool-display';
+
+/**
+ * Renders a {@link FileDiffDisplay} as a classic diff: a line-number gutter,
+ * +/- markers, green background for added lines, red for removed, dim context,
+ * and a `⋯` separator between non-contiguous hunks.
+ *
+ * Row-flattening, the gutter number, and the header verb come from
+ * `@moxxy/sdk/tool-display` (the dependency-free subpath — only type-erased
+ * imports plus those tiny pure helpers reach the browser bundle). The `+X −Y`
+ * count summary stays local: the shared `fileDiffSummary` renders human prose
+ * ("Added N lines, removed M line"), not this compact glyph form.
+ */
+
+/** "+10 −1" style summary of the change counts. */
+function plusMinus(display: FileDiffDisplay): string {
+  return `+${display.added} −${display.removed}`;
+}
+
+/** Gutter number for a line — new number, or old for deletions. */
+function gutter(line: DiffLine): string {
+  const n = diffGutterNo(line);
+  return n === undefined ? '' : String(n);
+}
+
+const MARKER: Record<DiffLine['kind'], string> = { context: ' ', add: '+', del: '-' };
+const ROW_CLASS: Record<DiffLine['kind'], string> = {
+  context: 'v-diff-ctx',
+  add: 'v-diff-add',
+  del: 'v-diff-del',
+};
+
+export function FileDiffView(props: { display: FileDiffDisplay }): JSX.Element {
+  const { display } = props;
+  const verb = fileDiffVerb(display);
+  const rows = toDiffRows(display);
+  return (
+    <div className="v-diff">
+      <div className="v-diff-head">
+        <span className="v-diff-path">
+          {verb} · {display.path}
+        </span>
+        <span className="v-diff-sum">{plusMinus(display)}</span>
+      </div>
+      <div className="v-diff-body">
+        {rows.map((row, i) =>
+          row.kind === 'gap' ? (
+            <div key={i} className="v-diff-row v-diff-gap">
+              <span className="v-diff-no" />
+              <span className="v-diff-mark">⋯</span>
+              <span className="v-diff-text" />
+            </div>
+          ) : (
+            <div key={i} className={`v-diff-row ${ROW_CLASS[row.kind]}`}>
+              <span className="v-diff-no">{gutter(row)}</span>
+              <span className="v-diff-mark">{MARKER[row.kind]}</span>
+              <span className="v-diff-text">{row.text}</span>
+            </div>
+          ),
+        )}
+      </div>
+      {display.truncated && <div className="v-diff-trunc">diff truncated</div>}
+    </div>
+  );
+}