fix(web): harden typed SPA chat lifecycle

Co-Authored-By: Claude Haiku 4.5 <[email protected]>

apps/web/src/spa/pages/chat-error-boundary.spec.tsx

@@ -0,0 +1,58 @@
+import { act } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+import { createMemoryRouter, RouterProvider, type RouteObject } from 'react-router-dom';
+import { afterAll, afterEach, beforeAll, describe, expect, it, vi } from 'vitest';
+import { ChatRouteErrorBoundary } from './chat-error-boundary';
+
+beforeAll(() => {
+  Object.defineProperty(globalThis, 'IS_REACT_ACT_ENVIRONMENT', {
+    configurable: true,
+    value: true,
+  });
+});
+
+afterAll(() => {
+  Reflect.deleteProperty(globalThis, 'IS_REACT_ACT_ENVIRONMENT');
+});
+
+function Boom(): never {
+  throw new Error('render blew up');
+}
+
+let root: Root | null;
+let container: HTMLElement;
+
+afterEach(async () => {
+  await act(async () => {
+    root?.unmount();
+  });
+  document.body.replaceChildren();
+  root = null;
+});
+
+describe('ChatRouteErrorBoundary', () => {
+  it('renders a recoverable, non-blank fallback when the /chat route element throws during render', async () => {
+    const routeObjects: RouteObject[] = [
+      { path: '/chat', element: <Boom />, errorElement: <ChatRouteErrorBoundary /> },
+    ];
+    const router = createMemoryRouter(routeObjects, { initialEntries: ['/chat'] });
+
+    container = document.createElement('div');
+    document.body.append(container);
+    root = createRoot(container);
+
+    const consoleErrorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+    try {
+      await act(async () => {
+        root?.render(<RouterProvider router={router} />);
+      });
+
+      expect(consoleErrorSpy).toHaveBeenCalled();
+    } finally {
+      consoleErrorSpy.mockRestore();
+    }
+
+    expect(container.textContent).not.toBe('');
+    expect(container.querySelector('[role="alert"]')).toBeTruthy();
+  });
+});

apps/web/src/spa/pages/chat-error-boundary.tsx

@@ -0,0 +1,22 @@
+import type { ReactElement } from 'react';
+import { useRouteError } from 'react-router-dom';
+
+/**
+ * `/chat` renders live, server-driven state (streamed text, tool calls,
+ * manifests) that can carry malformed payloads no compile-time contract can
+ * fully rule out at every dereference site. This is the last line of
+ * defense: if something still throws during render, show a recoverable
+ * alert instead of leaving the user on a blank/white screen.
+ */
+export function ChatRouteErrorBoundary(): ReactElement {
+  useRouteError();
+
+  return (
+    <div role="alert" className="flex min-h-screen flex-col items-center justify-center gap-3 p-8">
+      <p className="text-sm font-medium">Something went wrong loading chat.</p>
+      <a href="/chat" className="text-sm underline">
+        Reload chat
+      </a>
+    </div>
+  );
+}

apps/web/src/spa/pages/chat.spec.tsx

@@ -233,7 +233,7 @@ describe('ChatPage', () => {
     });
   });
 
-  it('shows visible alert surfaces for a server error and a failed command result', async () => {
+  it('shows visible alert surfaces for a server error and a stable failure copy for a failed command result', async () => {
     await act(async () => {
       fake.serverEmit('message:ack', { conversationId: 'c1', messageId: 'm1' });
       fake.serverEmit('error', { conversationId: 'c1', error: 'The model is unavailable' });
@@ -241,14 +241,116 @@ describe('ChatPage', () => {
         conversationId: 'c1',
         command: 'model',
         success: false,
-        message: 'unknown model id',
+        message: 'raw internal detail: stack trace at line 42',
       });
     });
 
     const alerts = [...container.querySelectorAll('[role="alert"]')];
     const alertText = alerts.map((node) => node.textContent).join(' ');
     expect(alertText).toContain('The model is unavailable');
-    expect(alertText).toContain('unknown model id');
+    // Sanitized client copy, not the raw server-provided detail.
+    expect(alertText).toContain('Command failed.');
+    expect(alertText).not.toContain('raw internal detail');
+  });
+
+  it('renders a safe fallback when session:info arrives with a malformed (non-array) availableThinkingLevels, without throwing', async () => {
+    await act(async () => {
+      fake.serverEmit('message:ack', { conversationId: 'c1', messageId: 'm1' });
+      fake.serverEmitRaw('session:info', {
+        conversationId: 'c1',
+        provider: 'anthropic',
+        modelId: 'claude',
+        thinkingLevel: 'medium',
+        availableThinkingLevels: null,
+      });
+    });
+
+    expect(container.querySelector('section[aria-label="Session info"]')).toBeTruthy();
+    const select = container.querySelector(
+      'select[aria-label="Thinking level"]',
+    ) as HTMLSelectElement;
+    expect(select).toBeTruthy();
+    // A malformed level list still shows a visible, safe placeholder option
+    // rather than a silently empty select.
+    expect([...select.options]).toHaveLength(1);
+    expect(select.options[0]?.textContent).toMatch(/unavailable/i);
+
+    await act(async () => {
+      selectValue(select, '');
+    });
+    expect(fake.emitted.filter((e) => e.event === 'set:thinking')).toHaveLength(0);
+  });
+
+  it('renders honest unavailable labels — not fabricated zeros — when agent:end usage has malformed/missing numeric fields', async () => {
+    await act(async () => {
+      fake.serverEmit('message:ack', { conversationId: 'c1', messageId: 'm1' });
+      fake.serverEmit('agent:start', { conversationId: 'c1' });
+      fake.serverEmitRaw('agent:end', {
+        conversationId: 'c1',
+        usage: {
+          provider: { nested: 'object' },
+          modelId: undefined,
+          thinkingLevel: 'medium',
+          tokens: { total: 'not-a-number' },
+          cost: undefined,
+          context: { percent: null, window: 200000 },
+        },
+      });
+    });
+
+    const usage = container.querySelector('[aria-label="Usage"]');
+    expect(usage).toBeTruthy();
+    expect(usage?.textContent).toContain('tokens unavailable');
+    expect(usage?.textContent).toContain('cost unavailable');
+    expect(usage?.textContent).not.toContain('0 tokens');
+    expect(usage?.textContent).not.toContain('$0.0000');
+    expect(usage?.textContent).toContain('unknown/unknown');
+  });
+
+  it('renders a safe fallback for message:ack when messageId is a malformed non-string value, without throwing', async () => {
+    await expect(
+      act(async () => {
+        fake.serverEmitRaw('message:ack', { conversationId: 'c1', messageId: { bad: 'object' } });
+      }),
+    ).resolves.not.toThrow();
+
+    const status = [...container.querySelectorAll('[role="status"]')].find((node) =>
+      node.textContent?.includes('Message accepted'),
+    );
+    expect(status).toBeTruthy();
+    // A malformed messageId gets a stable, visible fallback — never blank,
+    // never the raw object.
+    expect(status?.textContent).toContain('unknown');
+  });
+
+  it('renders safely and does not throw when system:reload.message is a malformed non-string value', async () => {
+    await expect(
+      act(async () => {
+        fake.serverEmitRaw('system:reload', {
+          commands: [],
+          skills: [],
+          providers: [],
+          message: { bad: 'object' },
+        });
+      }),
+    ).resolves.not.toThrow();
+
+    const status = container.querySelector('[role="status"]');
+    expect(status).toBeTruthy();
+    // A malformed reload message renders a stable, visible fallback rather
+    // than a silently empty status line.
+    expect(status?.textContent).toContain('Commands reloaded.');
+  });
+
+  it('renders safely and does not throw when a scoped error carries a malformed non-string error value', async () => {
+    await expect(
+      act(async () => {
+        fake.serverEmit('message:ack', { conversationId: 'c1', messageId: 'm1' });
+        fake.serverEmitRaw('error', { conversationId: 'c1', error: ['not', 'a', 'string'] });
+      }),
+    ).resolves.not.toThrow();
+
+    expect(container.querySelector('[role="alert"]')).toBeTruthy();
   });
 
   it('sends a message with optional provider/model fields and emits abort from the Stop control', async () => {

apps/web/src/spa/pages/chat.tsx

@@ -2,10 +2,25 @@ import type { ReactElement } from 'react';
 import { CommandsPanel } from '@/spa/chat/commands-panel';
 import { Composer } from '@/spa/chat/composer';
 import { MessageTranscript } from '@/spa/chat/message-transcript';
+import { asFiniteNumberOrNull, asString } from '@/spa/chat/runtime-guards';
 import { SessionPanel } from '@/spa/chat/session-panel';
 import { ToolCallList } from '@/spa/chat/tool-call-list';
 import { useChatConnection } from '@/spa/chat/use-chat-connection';
 
+/** Renders a real value normally, but an honest "unavailable" label instead
+ * of a fabricated `0` for a missing/malformed count — a real `0 tokens` and
+ * an unknown token count must never look the same. */
+function formatTokens(value: unknown): string {
+  const tokens = asFiniteNumberOrNull(value);
+  return tokens === null ? 'tokens unavailable' : `${tokens} tokens`;
+}
+
+/** Same honesty guarantee as `formatTokens`, for cost. */
+function formatCost(value: unknown): string {
+  const cost = asFiniteNumberOrNull(value);
+  return cost === null ? 'cost unavailable' : `$${cost.toFixed(4)}`;
+}
+
 export function ChatPage(): ReactElement {
   const { state, actions } = useChatConnection();
   const hasConversation = state.conversationId !== null;
@@ -18,19 +33,20 @@ export function ChatPage(): ReactElement {
 
       {state.systemReload ? (
         <div role="status" className="border-b px-4 py-2 text-sm">
-          {state.systemReload.message}
+          {asString(state.systemReload.message)}
         </div>
       ) : null}
 
       {state.error ? (
         <div role="alert" className="border-b px-4 py-2 text-sm">
-          {state.error}
+          {asString(state.error)}
         </div>
       ) : null}
 
       {state.ack ? (
         <div role="status" className="border-b px-4 py-1 text-xs opacity-70">
-          Message accepted · conversation {state.ack.conversationId} · id {state.ack.messageId}
+          Message accepted · conversation {asString(state.ack.conversationId, 'unknown')} · id{' '}
+          {asString(state.ack.messageId, 'unknown')}
         </div>
       ) : null}
 
@@ -48,8 +64,8 @@ export function ChatPage(): ReactElement {
 
       {state.usage ? (
         <div aria-label="Usage" className="px-4 pb-2 text-xs opacity-80">
-          {state.usage.tokens.total} tokens · ${state.usage.cost.toFixed(4)} ·{' '}
-          {state.usage.provider}/{state.usage.modelId}
+          {formatTokens(state.usage.tokens?.total)} · {formatCost(state.usage.cost)} ·{' '}
+          {asString(state.usage.provider, 'unknown')}/{asString(state.usage.modelId, 'unknown')}
         </div>
       ) : null}
 
@@ -68,6 +84,7 @@ export function ChatPage(): ReactElement {
         onSend={actions.sendMessage}
         onStop={actions.abort}
         streaming={state.streaming}
+        sending={state.sending}
         hasConversation={hasConversation}
       />
     </div>