@moxxy/plugin-channel-web 0.27.0

package/src/frontend/view-store.test.ts

@@ -0,0 +1,104 @@
+import { describe, expect, it } from 'vitest';
+import type { ViewDoc } from '@moxxy/sdk';
+import { applyView, canGoBack, currentEntry, goBack, initialNav, navigateTo } from './view-store.js';
+
+const doc = (tag = 'view'): ViewDoc => ({ root: { kind: 'element', tag, props: {}, children: [] } });
+const frame = (viewId: string, name?: string): { viewId: string; name?: string; doc: ViewDoc } => ({
+  viewId,
+  ...(name ? { name } : {}),
+  doc: doc(),
+});
+
+describe('view-store', () => {
+  it('caches a view and makes it current', () => {
+    const s = applyView(initialNav, frame('v1', 'search'));
+    expect(currentEntry(s)?.key).toBe('search');
+    expect(currentEntry(s)?.viewId).toBe('v1');
+    expect(canGoBack(s)).toBe(false);
+  });
+
+  it('pushes distinct screens onto history; Back pops them', () => {
+    let s = applyView(initialNav, frame('v1', 'search'));
+    s = applyView(s, frame('v2', 'results'));
+    expect(currentEntry(s)?.key).toBe('results');
+    expect(canGoBack(s)).toBe(true);
+    s = goBack(s);
+    expect(currentEntry(s)?.key).toBe('search');
+    expect(canGoBack(s)).toBe(false);
+    // goBack at the root is a no-op.
+    expect(goBack(s)).toBe(s);
+  });
+
+  it('re-rendering the current screen updates in place without growing history', () => {
+    let s = applyView(initialNav, frame('v1', 'results'));
+    const depth = s.history.length;
+    s = applyView(s, frame('v2', 'results')); // same name → update in place
+    expect(s.history.length).toBe(depth);
+    expect(currentEntry(s)?.viewId).toBe('v2'); // latest doc/viewId wins
+  });
+
+  it('keys by viewId when a view has no name', () => {
+    let s = applyView(initialNav, frame('v1'));
+    s = applyView(s, frame('v2'));
+    expect(s.history).toEqual(['v1', 'v2']);
+  });
+
+  it('navigateTo a cached view switches client-side; uncached returns null', () => {
+    let s = applyView(initialNav, frame('v1', 'search'));
+    s = applyView(s, frame('v2', 'results'));
+    const back = navigateTo(s, 'search');
+    expect(back).not.toBeNull();
+    expect(currentEntry(back!)?.key).toBe('search');
+    expect(navigateTo(s, 'detail')).toBeNull(); // not cached → caller asks the agent
+  });
+
+  it('navigateTo the current screen is a no-op (no duplicate history entry)', () => {
+    const s = applyView(initialNav, frame('v1', 'search'));
+    expect(navigateTo(s, 'search')).toBe(s);
+  });
+
+  it('bounds the cache: an unbounded stream of unnamed views does not grow forever', () => {
+    // Worst case: a long session presents 500 distinct UNNAMED views (each a new
+    // viewId, never coalesced). The browser must not leak one ViewDoc per render.
+    let s = initialNav;
+    for (let i = 0; i < 500; i++) s = applyView(s, frame(`v${i}`));
+    expect(Object.keys(s.cache).length).toBeLessThanOrEqual(64);
+    expect(s.order.length).toBeLessThanOrEqual(64);
+    // The current (newest) view is always still present and navigable.
+    expect(currentEntry(s)?.viewId).toBe('v499');
+  });
+
+  it('bounds history under pressure yet every Back target stays in cache (no dangling)', () => {
+    // Flood with unnamed views (each pushes a fresh history frame). History is
+    // FIFO-trimmed, but the INVARIANT must hold: every key still on the history
+    // stack has a live cache entry, so Back can never dereference a missing doc.
+    let s = initialNav;
+    for (let i = 0; i < 500; i++) s = applyView(s, frame(`x${i}`));
+    expect(s.history.length).toBeLessThanOrEqual(50);
+    let back = s;
+    while (canGoBack(back)) {
+      back = goBack(back);
+      expect(currentEntry(back)).not.toBeNull(); // never a dangling history key
+    }
+  });
+
+  it('preserves recent Back targets — a screen visited just before the flood is still reachable', () => {
+    // 'recent' is pushed, then a modest run of unnamed views within the history
+    // cap: it must remain on the stack AND in cache (recency is what's retained).
+    let s = applyView(initialNav, frame('r', 'recent'));
+    for (let i = 0; i < 10; i++) s = applyView(s, frame(`y${i}`));
+    expect(s.cache['recent']).toBeDefined();
+    let back = s;
+    while (canGoBack(back)) back = goBack(back);
+    expect(currentEntry(back)?.key).toBe('recent');
+  });
+
+  it('keeps the cache map and order array consistent after eviction', () => {
+    let s = initialNav;
+    for (let i = 0; i < 200; i++) s = applyView(s, frame(`v${i}`));
+    // order and cache must be the SAME key set (no dangling refs either way).
+    expect(new Set(s.order)).toEqual(new Set(Object.keys(s.cache)));
+    // and every history key must be cached (Back integrity).
+    for (const key of s.history) expect(s.cache[key]).toBeDefined();
+  });
+});

package/src/frontend/view-store.ts

@@ -0,0 +1,120 @@
+import type { ViewDoc } from '@moxxy/sdk';
+
+/**
+ * Pure navigation state for the multi-view app — a view cache keyed by logical
+ * name (falling back to viewId) plus a history stack. Kept DOM-free and pure so
+ * it is unit-testable; the React hook in socket.ts is a thin wrapper.
+ *
+ * Model: each `view` frame caches its doc and pushes onto history (unless it
+ * re-renders the screen already on top — then it updates in place). `navigateTo`
+ * only succeeds client-side when the target is cached; otherwise the caller asks
+ * the agent to build it (a `navigate:<name>` turn). `goBack` pops the stack.
+ */
+export interface ViewEntry {
+  readonly key: string;
+  readonly viewId: string;
+  readonly doc: ViewDoc;
+}
+
+export interface NavState {
+  readonly cache: Readonly<Record<string, ViewEntry>>;
+  readonly history: ReadonlyArray<string>;
+  /** Cache insertion order (oldest first), used to LRU-evict so the map stays bounded. */
+  readonly order: ReadonlyArray<string>;
+}
+
+export const initialNav: NavState = { cache: {}, history: [], order: [] };
+
+/**
+ * Cap on the navigable history depth. Each UNNAMED view (keyed by its
+ * ever-incrementing viewId, so never coalesced) pushes a fresh history frame,
+ * which in turn PINS its cache entry — so without a history bound a long session
+ * presenting many unnamed views would grow `history` AND `cache` (one full
+ * ViewDoc per render) without limit. We trim the OLDEST history frames first
+ * (a user can't realistically Back through hundreds of screens), then evict any
+ * now-unreferenced cache entries. The current view and recent Back targets are
+ * always retained.
+ */
+const MAX_HISTORY = 50;
+/**
+ * Cap on distinct cached view docs. Bounds the cache independently of history so
+ * that even if history stays short, an LRU of off-stack screens can't grow
+ * forever. Never evicts a view still referenced by the (already-bounded) stack.
+ */
+const MAX_CACHED_VIEWS = 64;
+
+export interface ViewFrameLike {
+  readonly viewId: string;
+  readonly name?: string;
+  readonly doc: ViewDoc;
+}
+
+/** Cache a freshly-arrived view and make it current. */
+export function applyView(state: NavState, frame: ViewFrameLike): NavState {
+  const key = frame.name ?? frame.viewId;
+  const cache: Record<string, ViewEntry> = { ...state.cache, [key]: { key, viewId: frame.viewId, doc: frame.doc } };
+  const top = state.history[state.history.length - 1];
+  const history = top === key ? state.history.slice() : [...state.history, key];
+  // Refresh recency: move (or add) key to the tail of the insertion order.
+  const order = [...state.order.filter((k) => k !== key), key];
+  return prune({ cache, history, order });
+}
+
+/**
+ * Keep both `history` and `cache` bounded while preserving the invariant that
+ * `cache` keys === `order` keys, and every `history` key is in `cache` (so Back
+ * never dangles). First trim the oldest history frames past {@link MAX_HISTORY}
+ * (FIFO — drop the deepest Back targets); then LRU-evict cache entries past
+ * {@link MAX_CACHED_VIEWS}, oldest first, but NEVER one still on the (now
+ * bounded) history stack.
+ */
+function prune(state: NavState): NavState {
+  let history = state.history;
+  if (history.length > MAX_HISTORY) {
+    history = history.slice(history.length - MAX_HISTORY);
+  }
+  const live = new Set(history);
+  const cache: Record<string, ViewEntry> = { ...state.cache };
+  const order = [...state.order];
+  // Walk oldest→newest, dropping evictable (non-history) keys until within cap.
+  for (let i = 0; i < order.length && order.length > MAX_CACHED_VIEWS; ) {
+    const key = order[i]!;
+    if (live.has(key)) {
+      i += 1; // pinned by history — skip, keep it
+      continue;
+    }
+    order.splice(i, 1);
+    delete cache[key];
+  }
+  return { cache, history, order };
+}
+
+/**
+ * Client-side navigation to a cached view. Returns the new state, or null if the
+ * target isn't cached (caller should request it from the agent instead).
+ */
+export function navigateTo(state: NavState, name: string): NavState | null {
+  if (!state.cache[name]) return null;
+  const top = state.history[state.history.length - 1];
+  if (top === name) return state;
+  // Cap history depth so repeated back-and-forth navigation can't grow it
+  // without bound (drop the oldest Back targets first). `name` is already
+  // cached, so trimming history never strands the entry referenced here.
+  const pushed = [...state.history, name];
+  const history = pushed.length > MAX_HISTORY ? pushed.slice(pushed.length - MAX_HISTORY) : pushed;
+  return { ...state, history };
+}
+
+export function goBack(state: NavState): NavState {
+  if (state.history.length <= 1) return state;
+  return { ...state, history: state.history.slice(0, -1) };
+}
+
+export function currentEntry(state: NavState): ViewEntry | null {
+  const key = state.history[state.history.length - 1];
+  return key ? state.cache[key] ?? null : null;
+}
+
+export function canGoBack(state: NavState): boolean {
+  return state.history.length > 1;
+}

package/src/index.ts

@@ -0,0 +1,212 @@
+import { defineChannel, definePlugin, defineTool, z, type Plugin, type TunnelProviderDef } from '@moxxy/sdk';
+import { proxyTunnel } from '@moxxy/plugin-tunnel-proxy';
+import { WebChannel, type WebSurfaceControls } from './channel.js';
+import { normalizeTunnelName, readTunnelSetting, writeTunnelSetting } from './tunnel-settings.js';
+
+export { WebChannel, type WebChannelOptions, type WebStartOpts, type WebSurfaceControls } from './channel.js';
+export { EventProjector } from './projector.js';
+export { readTunnelSetting, writeTunnelSetting, normalizeTunnelName } from './tunnel-settings.js';
+export { actionPrompt, type ServerFrame, type ClientFrame } from './protocol.js';
+
+/** Live access to the session's tunnel registry (injected by the CLI builder). */
+export interface TunnelControls {
+  list(): string[];
+  active(): string | null;
+  setActive(name: string): void;
+  isAvailable(name: string): Promise<boolean>;
+}
+
+export interface BuildWebChannelOptions {
+  readonly getTunnel?: () => TunnelProviderDef | null;
+  readonly publishSurface?: (surface: { url: string; nextViewId: () => string } | null) => void;
+  readonly publishControls?: (controls: WebSurfaceControls | null) => void;
+  /** Read the live surface controls (for live tunnel switching from the tool). */
+  readonly getControls?: () => WebSurfaceControls | null;
+  /** Live tunnel registry access for the web_set_tunnel / web_tunnel_status tools. */
+  readonly tunnels?: TunnelControls;
+  /** Static default tunnel (from config.channels.web.tunnel) when no persisted setting. */
+  readonly defaultTunnel?: string;
+  /** Override the persisted settings file path (tests). Defaults to ~/.moxxy/web.json. */
+  readonly settingsFile?: string;
+}
+
+/**
+ * Build the web channel plugin. The CLI passes closures over the concrete
+ * Session (mirroring the Telegram plugin's vault injection). Contributes:
+ *  - the `web` channel (surface + action round-trip),
+ *  - the self-hosted `proxy` tunnel provider (registered; `localhost` is the
+ *    core-seeded default),
+ *  - `web_set_tunnel` / `web_tunnel_status` tools so the user/agent can switch
+ *    the tunnel at runtime — persisted to ~/.moxxy/web.json,
+ *  - an onInit hook that applies the persisted (or configured) tunnel on boot.
+ */
+export function buildWebChannelPlugin(opts: BuildWebChannelOptions = {}): Plugin {
+  const def = defineChannel({
+    name: 'web',
+    description:
+      'Browser surface that renders agent-authored view-spec UIs over a WebSocket and routes form/button actions back into the session. Exposes itself via the self-hosted proxy relay so users on other channels can open it.',
+    create: (deps) => {
+      const o = deps.options ?? {};
+      return new WebChannel({
+        ...(typeof o.port === 'number' ? { port: o.port } : {}),
+        ...(typeof o.host === 'string' ? { host: o.host } : {}),
+        ...(typeof o.authToken === 'string'
+          ? { authToken: o.authToken }
+          : process.env.MOXXY_WEB_TOKEN
+            ? { authToken: process.env.MOXXY_WEB_TOKEN }
+            : {}),
+        ...(Array.isArray(o.allowedTools) ? { allowedTools: o.allowedTools as string[] } : {}),
+        ...(opts.getTunnel ? { getTunnel: opts.getTunnel } : {}),
+        ...(opts.publishSurface ? { publishSurface: opts.publishSurface } : {}),
+        ...(opts.publishControls ? { publishControls: opts.publishControls } : {}),
+        logger: deps.logger as never,
+      });
+    },
+  });
+
+  const tunnels = opts.tunnels;
+  const tools = tunnels
+    ? [
+        defineTool({
+          name: 'web_set_tunnel',
+          description:
+            'Choose how the web app surface is exposed: "proxy" (public URL via the self-hosted relay, for remote channels like Telegram) or "none"/"localhost" (loopback only). Persisted to ~/.moxxy/web.json and applied immediately if a surface is live. Use when the user asks to change or disable the tunnel.',
+          inputSchema: z.object({ provider: z.string().min(1) }),
+          permission: { action: 'prompt' },
+          // Persists the choice, then (re)establishes the tunnel through the
+          // live surface controls — the relay host is config-dependent, so
+          // the net surface is genuinely dynamic.
+          isolation: {
+            capabilities: {
+              fs: {
+                read: [opts.settingsFile ?? '~/.moxxy/web.json'],
+                write: [opts.settingsFile ?? '~/.moxxy/web.json'],
+              },
+              net: { mode: 'any' },
+              timeMs: 60_000,
+            },
+          },
+          handler: async ({ provider }) => {
+            const name = normalizeTunnelName(provider);
+            if (!tunnels.list().includes(name)) {
+              return { ok: false, error: `unknown tunnel "${provider}"`, available: ['none', ...tunnels.list()] };
+            }
+            const available = await tunnels.isAvailable(name);
+            if (!available) {
+              return { ok: false, error: `${name} is not available` };
+            }
+            tunnels.setActive(name);
+            await writeTunnelSetting(name, opts.settingsFile);
+            const url = (await opts.getControls?.()?.retunnel()) ?? null;
+            return { ok: true, active: name, ...(url ? { url } : { note: 'applies when the web surface (re)starts' }) };
+          },
+        }),
+        defineTool({
+          name: 'web_tunnel_status',
+          description: 'Report the active web tunnel provider and the available options.',
+          inputSchema: z.object({}),
+          // Pure registry view — no fs / net / subprocess.
+          isolation: { capabilities: { net: { mode: 'none' }, timeMs: 10_000 } },
+          handler: () => ({ active: tunnels.active(), available: ['none', ...tunnels.list()] }),
+        }),
+      ]
+    : [];
+
+  return definePlugin({
+    name: '@moxxy/plugin-channel-web',
+    version: '0.0.0',
+    channels: [def],
+    tunnelProviders: [proxyTunnel],
+    tools,
+    hooks: tunnels
+      ? {
+          onInit: () => {
+            // Apply the persisted choice (or the configured default) on boot.
+            const chosen = readTunnelSetting(opts.settingsFile) ?? (opts.defaultTunnel ? normalizeTunnelName(opts.defaultTunnel) : undefined);
+            if (chosen && tunnels.list().includes(chosen)) {
+              try {
+                tunnels.setActive(chosen);
+              } catch {
+                /* keep the seeded default */
+              }
+            }
+          },
+        }
+      : {},
+  });
+}
+
+interface TunnelRegistryLike {
+  getActive(): TunnelProviderDef | null;
+  list(): ReadonlyArray<TunnelProviderDef>;
+  setActive(name: string): void;
+}
+interface SurfaceRef {
+  current: { url: string; nextViewId: () => string } | null;
+}
+interface ControlsRef {
+  current: WebSurfaceControls | null;
+}
+
+/**
+ * Discovery-loadable default export. Resolves the tunnel registry
+ * (`'tunnelProviders'`), the shared web-surface ref (`'viewSurface'`, read by the
+ * view plugin) + web-controls ref (`'webControls'`) and the configured default
+ * tunnel (`'webDefaultTunnel'`) from the inter-plugin service registry in
+ * `onInit`, instead of the host `{ getTunnel, publishSurface, … }` closure. A
+ * lazy `tunnels` object keeps the `web_set_tunnel`/`web_tunnel_status` tools +
+ * the boot tunnel-apply hook present (built before onInit), deferring every
+ * registry call to the resolved instance.
+ */
+export const webChannelPlugin: Plugin = (() => {
+  let tp: TunnelRegistryLike | null = null;
+  let surfaceRef: SurfaceRef | null = null;
+  let controlsRef: ControlsRef | null = null;
+  let defaultTunnel: string | undefined;
+
+  const tunnels: TunnelControls = {
+    list: () => tp?.list().map((p) => p.name) ?? [],
+    active: () => tp?.getActive()?.name ?? null,
+    setActive: (n) => {
+      tp?.setActive(n);
+    },
+    isAvailable: async (n) => {
+      const p = tp?.list().find((x) => x.name === n);
+      return p?.isAvailable ? p.isAvailable() : true;
+    },
+  };
+  const opts: BuildWebChannelOptions = {
+    getTunnel: () => tp?.getActive() ?? null,
+    publishSurface: (s) => {
+      if (surfaceRef) surfaceRef.current = s;
+    },
+    publishControls: (c) => {
+      if (controlsRef) controlsRef.current = c;
+    },
+    getControls: () => controlsRef?.current ?? null,
+    tunnels,
+    get defaultTunnel(): string | undefined {
+      return defaultTunnel;
+    },
+  };
+
+  const plugin = buildWebChannelPlugin(opts);
+  const innerOnInit = plugin.hooks?.onInit;
+
+  return definePlugin({
+    ...plugin,
+    hooks: {
+      ...plugin.hooks,
+      onInit: (ctx) => {
+        tp = ctx.services.get<TunnelRegistryLike>('tunnelProviders') ?? null;
+        surfaceRef = ctx.services.get<SurfaceRef>('viewSurface') ?? null;
+        controlsRef = ctx.services.get<ControlsRef>('webControls') ?? null;
+        defaultTunnel = ctx.services.get<string>('webDefaultTunnel') ?? undefined;
+        // Now the refs are resolved → apply the persisted/default tunnel on boot.
+        return innerOnInit?.(ctx);
+      },
+    },
+  });
+})();
+
+export default webChannelPlugin;

package/src/projector.test.ts

@@ -0,0 +1,172 @@
+import { describe, expect, it } from 'vitest';
+import type { MoxxyEvent } from '@moxxy/sdk';
+import { EventProjector } from './projector.js';
+
+// Minimal event factory — only the fields the projector reads.
+function ev(partial: Record<string, unknown>): MoxxyEvent {
+  return { turnId: 't1', sessionId: 's1', source: 'system', id: 'e', seq: 0, ts: 0, ...partial } as unknown as MoxxyEvent;
+}
+
+const sampleDoc = { root: { kind: 'element', tag: 'view', props: {}, children: [] } };
+
+describe('EventProjector', () => {
+  it('emits a view frame from a present_view tool_result', () => {
+    const p = new EventProjector();
+    expect(p.project(ev({ type: 'tool_call_requested', callId: 'c1', name: 'present_view', input: { fallbackText: 'fb' } }))).toEqual([]);
+    const frames = p.project(ev({ type: 'tool_result', callId: 'c1', ok: true, output: { ast: sampleDoc } }));
+    expect(frames).toHaveLength(1);
+    const f = frames[0]!;
+    expect(f.kind).toBe('view');
+    if (f.kind !== 'view') return;
+    expect(f.doc).toEqual(sampleDoc);
+    expect(f.replaces).toBeNull();
+    expect(f.fallbackText).toBe('fb');
+  });
+
+  it('sets `replaces` to the prior view id on the second view', () => {
+    const p = new EventProjector();
+    p.project(ev({ type: 'tool_call_requested', callId: 'c1', name: 'present_view', input: {} }));
+    const first = p.project(ev({ type: 'tool_result', callId: 'c1', ok: true, output: { ast: sampleDoc } }))[0]!;
+    p.project(ev({ type: 'tool_call_requested', callId: 'c2', name: 'present_view', input: {} }));
+    const second = p.project(ev({ type: 'tool_result', callId: 'c2', ok: true, output: { ast: sampleDoc } }))[0]!;
+    if (first.kind !== 'view' || second.kind !== 'view') throw new Error('expected views');
+    expect(second.replaces).toBe(first.viewId);
+    expect(second.viewId).not.toBe(first.viewId);
+  });
+
+  it('carries the view name from the AST root onto the frame', () => {
+    const p = new EventProjector();
+    p.project(ev({ type: 'tool_call_requested', callId: 'c1', name: 'present_view', input: {} }));
+    const namedDoc = { root: { kind: 'element', tag: 'view', props: { name: 'search' }, children: [] } };
+    const f = p.project(ev({ type: 'tool_result', callId: 'c1', ok: true, output: { ast: namedDoc } }))[0]!;
+    expect(f.kind === 'view' && f.name).toBe('search');
+  });
+
+  it('omits name when the view has none', () => {
+    const p = new EventProjector();
+    p.project(ev({ type: 'tool_call_requested', callId: 'c1', name: 'present_view', input: {} }));
+    const f = p.project(ev({ type: 'tool_result', callId: 'c1', ok: true, output: { ast: sampleDoc } }))[0]!;
+    expect(f.kind === 'view' && f.name).toBeUndefined();
+  });
+
+  it('ignores tool_result for non-present_view calls', () => {
+    const p = new EventProjector();
+    expect(p.project(ev({ type: 'tool_result', callId: 'x', ok: true, output: { ast: sampleDoc } }))).toEqual([]);
+  });
+
+  it('emits a file-diff frame from a Write/Edit tool_result carrying a display', () => {
+    const p = new EventProjector();
+    const display = {
+      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: 'a', oldNo: 1, newNo: 1 },
+            { kind: 'del', text: 'b', oldNo: 2 },
+            { kind: 'add', text: 'b2', newNo: 2 },
+            { kind: 'add', text: 'c', newNo: 3 },
+          ],
+        },
+      ],
+    };
+    const frames = p.project(ev({ type: 'tool_result', callId: 'w1', name: 'Write', ok: true, output: { forModel: 'Updated', display } }));
+    expect(frames).toEqual([{ kind: 'file-diff', turnId: 't1', display }]);
+  });
+
+  it('does NOT emit a file-diff frame for a failed write result', () => {
+    const p = new EventProjector();
+    const display = { kind: 'file-diff', path: 'x', mode: 'create', added: 1, removed: 0, hunks: [] };
+    expect(p.project(ev({ type: 'tool_result', callId: 'w2', ok: false, output: { display } }))).toEqual([]);
+  });
+
+  it('hides synthesized [ui-action] prompts but shows real ones', () => {
+    const p = new EventProjector();
+    expect(p.project(ev({ type: 'user_prompt', text: '[ui-action] ...' }))).toEqual([]);
+    const frames = p.project(ev({ type: 'user_prompt', text: 'find flights' }));
+    expect(frames[0]).toMatchObject({ kind: 'message', role: 'user', text: 'find flights' });
+  });
+
+  it('emits assistant message + done status, and tool status for other tools', () => {
+    const p = new EventProjector();
+    expect(p.project(ev({ type: 'tool_call_requested', callId: 'c', name: 'web_fetch', input: {} }))[0]).toMatchObject({
+      kind: 'status',
+      phase: 'tool',
+    });
+    const frames = p.project(ev({ type: 'assistant_message', content: 'done!', stopReason: 'end_turn' }));
+    expect(frames.find((f) => f.kind === 'message')).toMatchObject({ role: 'assistant', text: 'done!' });
+    expect(frames.find((f) => f.kind === 'status')).toMatchObject({ phase: 'done' });
+  });
+
+  it('does NOT emit a done status when the assistant stops to use a tool', () => {
+    const p = new EventProjector();
+    const frames = p.project(ev({ type: 'assistant_message', content: 'thinking', stopReason: 'tool_use' }));
+    expect(frames.some((f) => f.kind === 'status' && f.phase === 'done')).toBe(false);
+    expect(frames.some((f) => f.kind === 'message')).toBe(true);
+  });
+
+  it('skips empty assistant messages but still ends the turn', () => {
+    const p = new EventProjector();
+    const frames = p.project(ev({ type: 'assistant_message', content: '   ', stopReason: 'end_turn' }));
+    expect(frames.some((f) => f.kind === 'message')).toBe(false);
+    expect(frames.some((f) => f.kind === 'status' && f.phase === 'done')).toBe(true);
+  });
+
+  it('emits an error status for a failed present_view tool_result', () => {
+    const p = new EventProjector();
+    p.project(ev({ type: 'tool_call_requested', callId: 'c1', name: 'present_view', input: {} }));
+    const frames = p.project(ev({ type: 'tool_result', callId: 'c1', ok: false, error: { message: 'bad', kind: 'threw' } }));
+    expect(frames).toEqual([{ kind: 'status', turnId: 't1', phase: 'error', text: 'view failed to render' }]);
+  });
+
+  it('emits nothing for a present_view result missing an ast', () => {
+    const p = new EventProjector();
+    p.project(ev({ type: 'tool_call_requested', callId: 'c1', name: 'present_view', input: {} }));
+    expect(p.project(ev({ type: 'tool_result', callId: 'c1', ok: true, output: {} }))).toEqual([]);
+  });
+
+  it('maps error events to an error status', () => {
+    const p = new EventProjector();
+    expect(p.project(ev({ type: 'error', message: 'boom', kind: 'fatal' }))).toEqual([
+      { kind: 'status', turnId: 't1', phase: 'error', text: 'boom' },
+    ]);
+  });
+
+  it('handles two present_view calls in one turn, each replacing the last', () => {
+    const p = new EventProjector();
+    p.project(ev({ type: 'tool_call_requested', callId: 'a', name: 'present_view', input: {} }));
+    const first = p.project(ev({ type: 'tool_result', callId: 'a', ok: true, output: { ast: sampleDoc } }))[0]!;
+    p.project(ev({ type: 'tool_call_requested', callId: 'b', name: 'present_view', input: {} }));
+    const second = p.project(ev({ type: 'tool_result', callId: 'b', ok: true, output: { ast: sampleDoc } }))[0]!;
+    if (first.kind !== 'view' || second.kind !== 'view') throw new Error('views');
+    expect(second.replaces).toBe(first.viewId);
+  });
+
+  it('ignores event types it does not render', () => {
+    const p = new EventProjector();
+    expect(p.project(ev({ type: 'tool_call_approved', callId: 'c' }))).toEqual([]);
+    expect(p.project(ev({ type: 'provider_request' }))).toEqual([]);
+  });
+
+  it('stays correct after a long run of aborted present_view calls (pending map bounded)', () => {
+    // Each present_view tool_call without a matching tool_result simulates an
+    // aborted/errored turn — its pending entry would otherwise leak forever.
+    // After many such aborts the projector must remain functional and still
+    // render a fresh, fully-resolved view.
+    const p = new EventProjector();
+    for (let i = 0; i < 500; i++) {
+      expect(p.project(ev({ type: 'tool_call_requested', callId: `abort${i}`, name: 'present_view', input: {} }))).toEqual([]);
+    }
+    p.project(ev({ type: 'tool_call_requested', callId: 'live', name: 'present_view', input: {} }));
+    const frames = p.project(ev({ type: 'tool_result', callId: 'live', ok: true, output: { ast: sampleDoc } }));
+    expect(frames).toHaveLength(1);
+    expect(frames[0]!.kind).toBe('view');
+  });
+});