@moxxy/plugin-channel-web 0.27.0

package/src/frontend/render.test.ts

@@ -0,0 +1,166 @@
+import { describe, expect, it } from 'vitest';
+import { renderToStaticMarkup } from 'react-dom/server';
+import type { ReactElement } from 'react';
+import type { ViewNode } from '@moxxy/sdk';
+import { renderNode } from './render.js';
+
+const noop = (): void => undefined;
+const handlers = { dispatch: noop, navigate: noop };
+const render = (node: ViewNode): string => renderToStaticMarkup(renderNode(node, handlers) as ReactElement);
+
+const el = (
+  tag: string,
+  props: Record<string, string | number | boolean> = {},
+  children: ViewNode[] = [],
+  action?: { name: string; fields: string[] },
+  nav?: string,
+): ViewNode => ({ kind: 'element', tag, props, children, ...(action ? { action } : {}), ...(nav ? { nav } : {}) });
+const txt = (value: string): ViewNode => ({ kind: 'text', value });
+
+describe('frontend renderNode — security (the second wall)', () => {
+  it('escapes text so injected HTML cannot execute', () => {
+    const html = render(el('view', {}, [el('text', {}, [txt('<img src=x onerror=alert(1)>')])]));
+    expect(html).not.toContain('<img');
+    expect(html).toContain('&lt;img');
+  });
+
+  it('renders an unknown tag as an inert placeholder, never the raw tag', () => {
+    const html = render(el('view', {}, [el('script', {}, [txt('alert(1)')])]));
+    expect(html.toLowerCase()).toContain('unsupported');
+    expect(html).not.toContain('<script');
+  });
+
+  it('never emits event-handler attributes (handlers are functions, dropped by static render)', () => {
+    const html = render(el('view', {}, [el('button', { label: 'Go' }, [], { name: 'go', fields: [] })]));
+    expect(html).toContain('Go');
+    expect(html).not.toContain('onclick=');
+    expect(html).not.toContain('onsubmit=');
+  });
+
+  it('neutralizes a javascript: href — rendered as plain text, never a clickable anchor', () => {
+    const html = render(el('view', {}, [el('link', { href: 'javascript:alert(1)' }, [txt('click me')])]));
+    expect(html).toContain('click me');
+    expect(html).not.toContain('href=');
+    expect(html).not.toContain('javascript:');
+  });
+
+  it('neutralizes a data:text href', () => {
+    const html = render(el('view', {}, [el('link', { href: 'data:text/html,<script>1</script>' }, [txt('x')])]));
+    expect(html).not.toContain('href=');
+    expect(html).not.toContain('data:text');
+  });
+
+  it('neutralizes a javascript: href split by ASCII whitespace/control chars (browser strips them on click)', () => {
+    // The HTML5 URL parser strips tab/newline/CR (and leading C0 controls)
+    // before scheme resolution, so each of these executes as `javascript:` on
+    // click. The render-time gate must block them all → plain text, no href.
+    for (const href of [
+      'java\tscript:alert(1)',
+      'java\nscript:alert(1)',
+      'java\rscript:alert(1)',
+      'jav ascript:alert(1)',
+      '
javascript:alert(1)',
+    ]) {
+      const html = render(el('view', {}, [el('link', { href }, [txt('click me')])]));
+      expect(html).toContain('click me');
+      expect(html).not.toContain('href=');
+      expect(html.toLowerCase()).not.toContain('script:');
+    }
+  });
+
+  it('blocks an <img> whose src scheme is split by whitespace/control chars', () => {
+    for (const src of ['java\tscript:alert(1)', '
javascript:alert(1)']) {
+      const html = render(el('view', {}, [el('image', { src })]));
+      expect(html).not.toContain('<img');
+      expect(html.toLowerCase()).toContain('blocked image');
+    }
+  });
+
+  it('still renders an https/relative link untouched (valid flows unchanged)', () => {
+    const a = render(el('view', {}, [el('link', { href: 'https://example.com/p?q=1' }, [txt('site')])]));
+    expect(a).toContain('href="https://example.com/p?q=1"');
+    // a relative href stays a clickable external anchor
+    const rel = render(el('view', {}, [el('link', { href: '/local/path' }, [txt('local')])]));
+    expect(rel).toContain('href="/local/path"');
+  });
+
+  it('blocks an <img> with a non-image data: or javascript: src', () => {
+    for (const src of ['javascript:alert(1)', 'data:text/html,<script>1</script>']) {
+      const html = render(el('view', {}, [el('image', { src })]));
+      expect(html).not.toContain('<img');
+      expect(html.toLowerCase()).toContain('blocked image');
+    }
+  });
+
+  it('still renders safe https links and data:image sources', () => {
+    const a = render(el('view', {}, [el('link', { href: 'https://example.com' }, [txt('site')])]));
+    expect(a).toContain('href="https://example.com"');
+    const img = render(el('view', {}, [el('image', { src: 'data:image/png;base64,AAAA' })]));
+    expect(img).toContain('<img');
+  });
+});
+
+describe('frontend renderNode — correctness', () => {
+  it('renders the view title and nested content', () => {
+    const html = render(el('view', { title: 'Trip' }, [el('card', { title: 'Flight' }, [el('text', {}, [txt('hi')])])]));
+    expect(html).toContain('Trip');
+    expect(html).toContain('Flight');
+    expect(html).toContain('hi');
+  });
+
+  it('renders a form with a named input and the submit label', () => {
+    const html = render(
+      el('view', {}, [el('form', { submit: 'Search' }, [el('input', { name: 'from', label: 'From' })], { name: 'search', fields: ['from'] })]),
+    );
+    expect(html).toContain('<form');
+    expect(html).toContain('name="from"');
+    expect(html).toContain('Search');
+    expect(html).toContain('From');
+  });
+
+  it('renders a table with header and cell', () => {
+    const html = render(
+      el('view', {}, [el('table', {}, [el('tr', {}, [el('th', {}, [txt('H')]), el('td', {}, [txt('1')])])])]),
+    );
+    expect(html).toContain('<table');
+    expect(html).toContain('<th');
+    expect(html).toContain('<td');
+    expect(html).toContain('H');
+  });
+
+  it('renders the heading at the requested level (clamped 1–3)', () => {
+    expect(render(el('view', {}, [el('heading', { level: 2 }, [txt('Hi')])]))).toContain('<h2');
+    expect(render(el('view', {}, [el('heading', { level: 9 }, [txt('Hi')])]))).toContain('<h3');
+  });
+
+  it('renders an ordered vs unordered list', () => {
+    expect(render(el('view', {}, [el('list', { ordered: true }, [el('item', {}, [txt('a')])])]))).toContain('<ol');
+    expect(render(el('view', {}, [el('list', {}, [el('item', {}, [txt('a')])])]))).toContain('<ul');
+  });
+
+  it('renders a spinner and a skeleton with the requested rows', () => {
+    expect(render(el('view', {}, [el('spinner', { label: 'Loading…' })]))).toContain('v-spin');
+    const sk = render(el('view', {}, [el('skeleton', { rows: 4 })]));
+    expect((sk.match(/v-skel-row/g) ?? []).length).toBe(4);
+  });
+
+  it('renders an external link with safe rel/target', () => {
+    const html = render(el('view', {}, [el('link', { href: 'https://example.com' }, [txt('site')])]));
+    expect(html).toContain('href="https://example.com"');
+    expect(html).toContain('rel="noreferrer"');
+  });
+
+  it('renders a nav link (to) as a clickable anchor, not an external target', () => {
+    const html = render(el('view', {}, [el('link', { to: 'search' }, [txt('Back')], undefined, 'search')]));
+    expect(html).toContain('Back');
+    expect(html).toContain('<a');
+    expect(html).not.toContain('rel="noreferrer"'); // not an external link
+    expect(html).not.toContain('onclick='); // handler is a function, never an attribute
+  });
+
+  it('renders a nav button (to) with no handler attribute', () => {
+    const html = render(el('view', {}, [el('button', { to: 'results', label: 'See results' }, [], undefined, 'results')]));
+    expect(html).toContain('See results');
+    expect(html).not.toContain('onclick=');
+  });
+});

package/src/frontend/render.tsx

@@ -0,0 +1,274 @@
+import { createElement, type ReactNode } from 'react';
+import type { ViewNode } from '@moxxy/sdk';
+import { isSafeViewUrl } from './url-safety.js';
+
+export type Dispatch = (action: { name: string }, formValues: Record<string, string>) => void;
+
+export interface RenderHandlers {
+  /** Submit/click an `action` element → agent turn. */
+  dispatch: Dispatch;
+  /** A `to`/`nav` element → client-side navigation (or a build turn if uncached). */
+  navigate: (name: string) => void;
+}
+
+/**
+ * Maps the validated AST to React elements via a FIXED tag→element switch.
+ * This switch IS the allow-list (defense in depth alongside the parser): an
+ * unknown tag renders an inert placeholder, never raw HTML or evaluated code.
+ * Agent strings only ever land as escaped React text or typed attributes.
+ *
+ * Two interaction paths: `node.nav` (a `to` target) navigates client-side; an
+ * `action` drives an agent turn. Neither is ever an injected handler string.
+ */
+export function renderNode(node: ViewNode, h: RenderHandlers, key?: number): ReactNode {
+  if (node.kind === 'text') return node.value;
+  const p = node.props;
+  const kids = node.children.map((c, i) => renderNode(c, h, i));
+  const s = (v: unknown): string | undefined => (v == null ? undefined : String(v));
+
+  switch (node.tag) {
+    case 'view':
+      return (
+        <div className="v-view" key={key}>
+          {p.title ? <h1 className="v-title">{String(p.title)}</h1> : null}
+          {kids}
+        </div>
+      );
+    case 'stack':
+      return (
+        <div className="v-stack" data-gap={s(p.gap)} data-align={s(p.align)} key={key}>
+          {kids}
+        </div>
+      );
+    case 'row':
+      return (
+        <div className="v-row" data-gap={s(p.gap)} data-align={s(p.align)} data-justify={s(p.justify)} key={key}>
+          {kids}
+        </div>
+      );
+    case 'grid':
+      return (
+        <div className="v-grid" style={{ gridTemplateColumns: `repeat(${Number(p.cols) || 1}, 1fr)` }} data-gap={s(p.gap)} key={key}>
+          {kids}
+        </div>
+      );
+    case 'card':
+      return (
+        <div className="v-card" data-accent={s(p.accent)} key={key}>
+          {p.title ? <div className="v-card-title">{String(p.title)}</div> : null}
+          {kids}
+        </div>
+      );
+    case 'divider':
+      return <hr className="v-divider" key={key} />;
+    case 'spinner':
+      return (
+        <div className="v-spinner" role="status" aria-live="polite" aria-busy="true" key={key}>
+          <span className="v-spin" aria-hidden="true" />
+          <span className="v-text" data-tone="muted">{p.label ? String(p.label) : 'Loading…'}</span>
+        </div>
+      );
+    case 'skeleton': {
+      const rows = Math.min(12, Math.max(1, Number(p.rows) || 3));
+      return (
+        <div className="v-skeleton" key={key}>
+          {Array.from({ length: rows }, (_, i) => (
+            <div className="v-skel-row" key={i} />
+          ))}
+        </div>
+      );
+    }
+    case 'heading': {
+      const lvl = Math.min(3, Math.max(1, Number(p.level) || 2));
+      return createElement(`h${lvl}`, { className: 'v-heading', key }, kids);
+    }
+    case 'text':
+      return (
+        <span className="v-text" data-tone={s(p.tone)} data-weight={s(p.weight)} key={key}>
+          {kids}
+        </span>
+      );
+    case 'badge':
+      return (
+        <span className="v-badge" data-tone={s(p.tone)} key={key}>
+          {kids}
+        </span>
+      );
+    case 'image': {
+      // Render-time URL re-validation (second wall, mirrors validateDoc):
+      // an unsafe scheme renders an inert placeholder, never an <img src>.
+      const src = String(p.src);
+      if (!isSafeViewUrl(src, 'src')) {
+        return (
+          <div className="v-unknown" key={key}>
+            [blocked image: disallowed URL scheme]
+          </div>
+        );
+      }
+      return <img className="v-image" src={src} alt={p.alt ? String(p.alt) : ''} key={key} />;
+    }
+    case 'link': {
+      // A `to` link navigates client-side; otherwise it is an external anchor.
+      if (node.nav) {
+        return (
+          <a
+            className="v-link"
+            href="#"
+            key={key}
+            onClick={(e) => {
+              e.preventDefault();
+              h.navigate(node.nav!);
+            }}
+          >
+            {kids}
+          </a>
+        );
+      }
+      // Render-time URL re-validation (second wall, mirrors validateDoc):
+      // an unsafe href (javascript:, data:text/*, …) renders as plain text
+      // — the click-XSS payload never becomes a clickable anchor.
+      const href = String(p.href);
+      if (!isSafeViewUrl(href, 'href')) {
+        return (
+          <span className="v-link" key={key}>
+            {kids}
+          </span>
+        );
+      }
+      return (
+        <a className="v-link" href={href} target="_blank" rel="noreferrer" key={key}>
+          {kids}
+        </a>
+      );
+    }
+    case 'list':
+      return p.ordered ? (
+        <ol className="v-list" key={key}>{kids}</ol>
+      ) : (
+        <ul className="v-list" key={key}>{kids}</ul>
+      );
+    case 'item':
+      return <li className="v-item" key={key}>{kids}</li>;
+    case 'table':
+      return (
+        <table className="v-table" key={key}>
+          <tbody>{kids}</tbody>
+        </table>
+      );
+    case 'tr':
+      return <tr key={key}>{kids}</tr>;
+    case 'th':
+      // scope="col" lets screen readers associate header cells with their
+      // column for the data tables agents commonly build.
+      return <th scope="col" style={{ textAlign: align(p.align) }} key={key}>{kids}</th>;
+    case 'td':
+      return <td style={{ textAlign: align(p.align) }} key={key}>{kids}</td>;
+    case 'form':
+      return <FormEl node={node} dispatch={h.dispatch} key={key}>{kids}</FormEl>;
+    case 'input':
+      return (
+        <label className="v-field" key={key}>
+          {p.label ? <span className="v-label">{String(p.label)}</span> : null}
+          <input
+            name={String(p.name)}
+            type={p.type ? String(p.type) : 'text'}
+            placeholder={p.placeholder ? String(p.placeholder) : ''}
+            defaultValue={p.value != null ? String(p.value) : undefined}
+            required={!!p.required}
+          />
+        </label>
+      );
+    case 'select':
+      return (
+        <label className="v-field" key={key}>
+          {p.label ? <span className="v-label">{String(p.label)}</span> : null}
+          <select name={String(p.name)} defaultValue={p.value != null ? String(p.value) : undefined}>
+            {kids}
+          </select>
+        </label>
+      );
+    case 'option':
+      return <option value={String(p.value)} key={key}>{kids}</option>;
+    case 'checkbox':
+      return (
+        <label className="v-check" key={key}>
+          <input type="checkbox" name={String(p.name)} defaultChecked={!!p.checked} />
+          {p.label ? <span>{String(p.label)}</span> : null}
+        </label>
+      );
+    case 'button':
+      return <ActionButton node={node} handlers={h} key={key} />;
+    default:
+      return (
+        <div className="v-unknown" key={key}>
+          [unsupported: {node.tag}]
+        </div>
+      );
+  }
+}
+
+function align(v: unknown): 'left' | 'center' | 'right' {
+  return v === 'center' || v === 'right' ? v : 'left';
+}
+
+function gatherFormValues(form: HTMLFormElement | null): Record<string, string> {
+  const out: Record<string, string> = {};
+  if (!form) return out;
+  new FormData(form).forEach((value, key) => {
+    out[key] = String(value);
+  });
+  return out;
+}
+
+function pick(values: Record<string, string>, fields: ReadonlyArray<string>): Record<string, string> {
+  if (fields.length === 0) return values;
+  const out: Record<string, string> = {};
+  for (const f of fields) if (f in values) out[f] = values[f]!;
+  return out;
+}
+
+function FormEl(props: { node: Extract<ViewNode, { kind: 'element' }>; dispatch: Dispatch; children: ReactNode }): ReactNode {
+  const { node, dispatch, children } = props;
+  const name = node.action?.name ?? '';
+  const submitLabel = node.props.submit ? String(node.props.submit) : 'Submit';
+  return (
+    <form
+      className="v-form"
+      onSubmit={(e) => {
+        e.preventDefault();
+        dispatch({ name }, gatherFormValues(e.currentTarget));
+      }}
+    >
+      {children}
+      <div className="v-form-actions">
+        <button type="submit" className="v-btn" data-variant="primary">
+          {submitLabel}
+        </button>
+      </div>
+    </form>
+  );
+}
+
+function ActionButton(props: { node: Extract<ViewNode, { kind: 'element' }>; handlers: RenderHandlers }): ReactNode {
+  const { node, handlers } = props;
+  return (
+    <button
+      type="button"
+      className="v-btn"
+      data-variant={node.props.variant != null ? String(node.props.variant) : undefined}
+      onClick={(e) => {
+        // `to`/nav takes precedence (client-side); else fire the agent action.
+        if (node.nav) {
+          handlers.navigate(node.nav);
+          return;
+        }
+        if (node.action) {
+          const values = gatherFormValues((e.currentTarget as HTMLButtonElement).closest('form'));
+          handlers.dispatch({ name: node.action.name }, pick(values, node.action.fields));
+        }
+      }}
+    >
+      {String(node.props.label ?? 'OK')}
+    </button>
+  );
+}

package/src/frontend/socket.ts

@@ -0,0 +1,212 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+import type { FileDiffDisplay, ViewDoc } from '@moxxy/sdk';
+import type { ClientFrame, ServerFrame } from '../protocol';
+import { applyView, canGoBack, currentEntry, goBack, initialNav, navigateTo, type NavState } from './view-store';
+
+/** Reconnect backoff bounds for the surface WebSocket. */
+const MIN_RECONNECT_MS = 500;
+const MAX_RECONNECT_MS = 8_000;
+
+/**
+ * The auth token, captured from `?t` at module load — BEFORE the address bar is
+ * cleaned (see stripTokenFromUrl) — so reconnects and the WS handshake keep
+ * working after the visible URL no longer carries it.
+ */
+const CAPTURED_TOKEN: string =
+  typeof window !== 'undefined' ? new URLSearchParams(window.location.search).get('t') ?? '' : '';
+
+function readAuthToken(): string {
+  return CAPTURED_TOKEN;
+}
+
+/**
+ * Drop the `?t=…` token from the visible URL (history-replace, no navigation)
+ * once it has been captured, so the bearer token isn't persisted to browser
+ * history / shoulder-surfed from the address bar. The WS still authenticates
+ * from {@link CAPTURED_TOKEN}. Safe no-op when there is no token or no History.
+ */
+export function stripTokenFromUrl(): void {
+  if (typeof window === 'undefined' || !window.history?.replaceState) return;
+  const url = new URL(window.location.href);
+  if (!url.searchParams.has('t')) return;
+  url.searchParams.delete('t');
+  window.history.replaceState(null, '', `${url.pathname}${url.search}${url.hash}`);
+}
+
+/** A prose turn from the user or assistant, mirrored into the transcript. */
+export interface TranscriptText {
+  readonly role: 'assistant' | 'user';
+  readonly text: string;
+}
+
+/** A structured file diff (from a Write/Edit tool result) shown inline in the stream. */
+export interface TranscriptDiff {
+  readonly role: 'diff';
+  readonly display: FileDiffDisplay;
+}
+
+/** One entry in the chat stream — prose or a rendered diff. */
+export type TranscriptMessage = TranscriptText | TranscriptDiff;
+
+export interface ViewSocket {
+  readonly connected: boolean;
+  readonly view: { viewId: string; doc: ViewDoc } | null;
+  readonly canGoBack: boolean;
+  readonly messages: TranscriptMessage[];
+  readonly status: { text: string; error: boolean } | null;
+  /** Submit a form / click an action button → agent turn. */
+  dispatch(action: { name: string }, formValues: Record<string, string>): void;
+  /** Navigate to a named view — instant if cached, else ask the agent to build it. */
+  navigate(name: string): void;
+  goBack(): void;
+  sendPrompt(text: string): void;
+}
+
+/** Opens the surface WebSocket and reduces inbound frames into navigable view state. */
+export function useViewSocket(): ViewSocket {
+  const [connected, setConnected] = useState(false);
+  const [nav, setNav] = useState<NavState>(initialNav);
+  const [messages, setMessages] = useState<TranscriptMessage[]>([]);
+  const [status, setStatus] = useState<{ text: string; error: boolean } | null>(null);
+  const wsRef = useRef<WebSocket | null>(null);
+  const navRef = useRef<NavState>(initialNav);
+  const setNavState = useCallback((next: NavState) => {
+    navRef.current = next;
+    setNav(next);
+  }, []);
+
+  const sendAction = useCallback((action: { name: string }, formValues: Record<string, string>) => {
+    const ws = wsRef.current;
+    if (!ws || ws.readyState !== WebSocket.OPEN) return;
+    const frame: ClientFrame = {
+      kind: 'action',
+      actionId: Math.random().toString(36).slice(2),
+      viewId: currentEntry(navRef.current)?.viewId ?? null,
+      action,
+      formValues,
+    };
+    ws.send(JSON.stringify(frame));
+    setStatus({ text: 'working…', error: false });
+  }, []);
+
+  useEffect(() => {
+    // The token is captured ONCE here, before main.tsx may strip `?t` from the
+    // visible address bar (history.replaceState) to keep it out of browser
+    // history. Reconnects reuse this captured copy.
+    const token = readAuthToken();
+    const proto = window.location.protocol === 'https:' ? 'wss' : 'ws';
+    // Base path the surface is served under (e.g. `/web` behind the proxy relay,
+    // `''` locally) — injected into the page by the server.
+    const base = (window as unknown as { __MOXXY_BASE__?: string }).__MOXXY_BASE__ ?? '';
+    const wsUrl = `${proto}://${window.location.host}${base}/ws?t=${encodeURIComponent(token)}`;
+
+    let disposed = false;
+    let reconnectTimer: ReturnType<typeof setTimeout> | null = null;
+    let backoffMs = MIN_RECONNECT_MS;
+
+    const handleMessage = (ev: MessageEvent): void => {
+      let frame: ServerFrame;
+      try {
+        frame = JSON.parse(String(ev.data)) as ServerFrame;
+      } catch {
+        return;
+      }
+      if (frame.kind === 'view') {
+        setNavState(applyView(navRef.current, frame));
+        setStatus(null);
+      } else if (frame.kind === 'message') {
+        setMessages((prev) => [...prev, { role: frame.role, text: frame.text }]);
+      } else if (frame.kind === 'file-diff') {
+        setMessages((prev) => [...prev, { role: 'diff', display: frame.display }]);
+      } else if (frame.kind === 'status') {
+        if (frame.phase === 'done') setStatus(null);
+        else if (frame.phase === 'error') setStatus({ text: frame.text || 'error', error: true });
+        else setStatus({ text: frame.text || 'working…', error: false });
+      } else if (frame.kind === 'ack') {
+        // A rejected action (e.g. the agent is mid-turn) would otherwise leave
+        // the optimistic "working…" spinner up forever — clear it with a notice.
+        // An accepted action keeps the working status until its turn completes.
+        if (!frame.accepted) {
+          setStatus({
+            text: frame.reason === 'busy' ? 'agent is busy — try again in a moment' : 'action rejected',
+            error: true,
+          });
+        }
+      }
+    };
+
+    const connect = (): void => {
+      if (disposed) return;
+      const ws = new WebSocket(wsUrl);
+      wsRef.current = ws;
+      ws.onopen = () => {
+        backoffMs = MIN_RECONNECT_MS;
+        setConnected(true);
+      };
+      ws.onmessage = handleMessage;
+      ws.onclose = () => {
+        wsRef.current = null;
+        setConnected(false);
+        if (disposed) return;
+        // Tunnels (cloudflared/ngrok) and mobile networks drop routinely; the
+        // server also closes all sockets on retunnel/stop. Reconnect with capped
+        // exponential backoff instead of going permanently dead.
+        reconnectTimer = setTimeout(connect, backoffMs);
+        backoffMs = Math.min(backoffMs * 2, MAX_RECONNECT_MS);
+      };
+      // An 'error' that doesn't also fire 'close' would otherwise strand us; the
+      // browser always follows a failed/closed socket with 'close', so the
+      // reconnect is driven from there. The explicit handler just suppresses the
+      // unhandled-error console noise.
+      ws.onerror = () => undefined;
+    };
+
+    connect();
+    return () => {
+      disposed = true;
+      if (reconnectTimer) clearTimeout(reconnectTimer);
+      const ws = wsRef.current;
+      wsRef.current = null;
+      if (ws) {
+        ws.onclose = null;
+        ws.close();
+      }
+    };
+  }, [setNavState]);
+
+  const navigate = useCallback(
+    (name: string) => {
+      const next = navigateTo(navRef.current, name);
+      if (next) {
+        setNavState(next); // cached → instant, no agent turn
+      } else {
+        sendAction({ name: `navigate:${name}` }, {}); // uncached → ask the agent to build it
+      }
+    },
+    [sendAction, setNavState],
+  );
+
+  const back = useCallback(() => setNavState(goBack(navRef.current)), [setNavState]);
+
+  const sendPrompt = useCallback((text: string) => {
+    const ws = wsRef.current;
+    if (!ws || ws.readyState !== WebSocket.OPEN) return;
+    const frame: ClientFrame = { kind: 'prompt', text };
+    ws.send(JSON.stringify(frame));
+    setMessages((prev) => [...prev, { role: 'user', text }]);
+    setStatus({ text: 'working…', error: false });
+  }, []);
+
+  const entry = currentEntry(nav);
+  return {
+    connected,
+    view: entry ? { viewId: entry.viewId, doc: entry.doc } : null,
+    canGoBack: canGoBack(nav),
+    messages,
+    status,
+    dispatch: sendAction,
+    navigate,
+    goBack: back,
+    sendPrompt,
+  };
+}

package/src/frontend/url-safety.ts

@@ -0,0 +1,33 @@
+/**
+ * Render-time URL-scheme allow-list for agent-authored `href`/`src` values.
+ *
+ * VERBATIM COPY of `isSafeViewUrl` in `packages/sdk/src/view-renderer.ts` —
+ * the canonical check the parser (`parseView`) and `validateDoc` enforce.
+ * The browser bundle is built standalone (esbuild, platform: browser, see
+ * `scripts/build-web.mjs`) and cannot import the sdk root, which drags in
+ * node builtins — so the check is duplicated here. KEEP THE TWO IN LOCKSTEP.
+ *
+ * Decision (audit A44): allowed schemes are `https:`, `http:`, `mailto:`,
+ * `tel:`, plus relative/fragment URLs; `data:` only as an `img src` and only
+ * `data:image/*`. Everything else — notably `javascript:`, `vbscript:`,
+ * `data:text/*` — is rejected. Views are shared with third parties, so a
+ * `javascript:` link is click-XSS; this is the second wall in case an AST
+ * ever reaches the renderer without passing the parser.
+ */
+export function isSafeViewUrl(url: string, attr: string): boolean {
+  // Make the SAFETY DECISION on the form the browser actually resolves: the
+  // HTML5 URL parser strips ALL ASCII whitespace and C0 control chars (tab,
+  // newline, CR, …) from anywhere in a URL before resolving the scheme, so
+  // `java\tscript:` resolves to `javascript:` on click. Collapse every
+  // U+0000–U+0020 char (all ASCII whitespace + C0 controls, which also covers
+  // the leading/trailing space the old `trim()` handled) before checking;
+  // removing these from a genuinely-safe http/https/mailto/relative URL still
+  // resolves to the same scheme, so valid links keep working. The RAW `url` is
+  // still what render.tsx blocks or emits — only this gate sees the collapsed
+  // form. Keep in lockstep with `packages/sdk/src/view-renderer.ts`.
+  const u = url.replace(/[\u0000-\u0020]/g, '').toLowerCase();
+  if (u.startsWith('javascript:') || u.startsWith('vbscript:')) return false;
+  if (u.startsWith('data:')) return attr === 'src' && u.startsWith('data:image/');
+  if (/^[a-z][a-z0-9+.-]*:/.test(u)) return /^(https?:|mailto:|tel:)/.test(u);
+  return true; // relative / fragment
+}