@cats-inc/cats-platform 0.1.21 → 0.3.4

package/scripts/testing/check-usage-app.mts

@@ -0,0 +1,266 @@
+#!/usr/bin/env node
+// Integration-only: built App archive + real host surface/route + fixture runtime.
+// Usage: node --import tsx scripts/testing/check-usage-app.mts --apps-lock <path>
+// Requires CATS_TEST_PLAYWRIGHT_MODULE (absolute module file) and CATS_TEST_BROWSER_EXECUTABLE.
+import assert from 'node:assert/strict';
+import { createServer } from 'node:http';
+import { mkdtemp, mkdir, readFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { build } from 'esbuild';
+import { resolveAppLock } from '#cats-app-package';
+import { installRendererPackage } from '../../src/platform/apps/packageInstaller.js';
+import { FileCatsAppRegistry } from '../../src/platform/apps/registry.js';
+import { resolveCatsAppStoragePathsFromChatState } from '../../src/platform/apps/paths.js';
+import { projectUsageSnapshot, projectUsageQuotaRefresh } from '../../src/runtime/usageSnapshot.js';
+import { toPlatformInstalledAppDescriptor } from '../../src/platform/apps/envelope.js';
+import { routeRequest } from '../../src/app/server/requestRouter.js';
+import type { ResolvedServerDependencies } from '../../src/app/server/contracts.js';
+import { loadConfig } from '../../src/config.js';
+import { createDefaultCoreState } from '../../src/core/model/index.js';
+import { MemoryCoreStore } from '../../src/core/store.js';
+import { createEmptyPlatformAuthState, createFirstAdminLocalAuthState, MemoryPlatformAuthStore } from '../../src/platform/auth/index.js';
+
+const args = process.argv.slice(2);
+if (args.includes('--help')) {
+  process.stdout.write('Usage: node --import tsx scripts/testing/check-usage-app.mts --apps-lock <path> [--renderer-root <built renderer directory>] [--electron] [--check-loading-recovery]\nRequires CATS_TEST_PLAYWRIGHT_MODULE and CATS_TEST_BROWSER_EXECUTABLE; no real user state is read.\n');
+  process.exit(0);
+}
+const lockPath = args[args.indexOf('--apps-lock') + 1];
+const rendererRoot = args.includes('--renderer-root') ? path.resolve(args[args.indexOf('--renderer-root') + 1]!) : null;
+if (args.includes('--electron') && args.includes('--check-loading-recovery')) {
+  throw new Error('Loading fault injection requires Chromium/Edge. Run Electron functional checks without --check-loading-recovery.');
+}
+if (args.indexOf('--apps-lock') < 0 || !lockPath || !process.env.CATS_TEST_PLAYWRIGHT_MODULE || !process.env.CATS_TEST_BROWSER_EXECUTABLE) throw new Error('App lock and isolated browser test inputs are required.');
+const root = await mkdtemp(path.join(tmpdir(), 'cats-usage-browser-'));
+const chatStatePath = path.join(root, 'state', 'chat-state.local.json');
+const apps = await resolveAppLock(path.resolve(lockPath));
+const usage = apps.find((app) => app.id === 'cats.usage');
+if (!usage) throw new Error('The selected lock must contain a built Usage package.');
+const entryPath = rendererRoot ? '/apps/cats.usage' : `/?appVersion=${encodeURIComponent(usage.version)}`;
+await installRendererPackage({ chatStatePath, bytes: usage.bytes, pin: usage, source: 'local-package', enable: true });
+const registry = new FileCatsAppRegistry({ registryPath: resolveCatsAppStoragePathsFromChatState(chatStatePath).registryPath });
+const bundle = rendererRoot ? null : await build({ entryPoints: [fileURLToPath(new URL('./usage-app-smoke-renderer.tsx', import.meta.url))], bundle: true,
+  format: 'esm', platform: 'browser', write: false, jsx: 'automatic', define: { 'process.env.NODE_ENV': '"production"' } });
+const js = bundle?.outputFiles[0]!.contents;
+const installed = (await registry.getInstalledApp(usage.id))!;
+const hostEnvelope = {
+  app: { name: 'cats-platform', stage: 'phase-2-shell', runtimeBoundary: 'cats-runtime' },
+  products: [], installedApps: [toPlatformInstalledAppDescriptor(installed)],
+  desktop: { startAtLogin: false, openWindowOnStartup: true, systemTrayEnabled: true,
+    mobilePairing: { enabled: false, transport: 'tailscale', installId: null, displayName: null } },
+  language: { uiLanguagePreference: 'zh-TW' },
+  lobby: { animationMode: 'reduced', cats: [] },
+  runtime: { baseUrl: 'http://127.0.0.1', reachable: true, status: 'ok', service: 'cats-runtime' },
+  runtimeSetup: { source: 'runtime', bootstrapRequired: false, status: 'ready', stateStatus: 'ready', summary: 'Ready',
+    scannedAt: null, lastManualScanAt: null, appliedAt: null, providerCount: 0, availableCount: 0,
+    providersReadyToApply: [], providersNeedingAttention: [], suggestedProviders: [], canRunManualScan: true, canApply: false, error: null },
+  metadata: { generatedAt: new Date().toISOString(), host: '127.0.0.1', port: 0 },
+  bootstrapAttemptId: null, scopeId: 'isolated-usage-smoke', setupCompleteAt: new Date().toISOString(),
+  ownerDisplayName: 'Test', ownerAvatarColor: null, ownerAvatarUrl: null, lastProductSurface: null, guideCat: null,
+};
+let offline = false; let epoch = 'fixture-epoch'; let stale = false; let reads = 0;
+const queries: string[] = [];
+const timestamp = () => new Date().toISOString();
+const totals = (totalTokens: number | null, currency = 'USD') => ({ observations: totalTokens === null ? 0 : 1,
+  inputTokens: totalTokens === null ? null : Math.floor(totalTokens * 0.8), outputTokens: totalTokens === null ? null : Math.ceil(totalTokens * 0.2),
+  totalTokens, costs: totalTokens === null ? [] : [{ currency, amount: 0.12, observations: 1 }],
+  confidence: { reported: totalTokens === null ? 0 : 1, aggregated: 0, estimated: 0, unknown: 0 }, lastObservedAt: timestamp() });
+const runtimeClient = { async getUsageSnapshot() {
+  reads++; if (offline) throw new Error('Fixture offline');
+  const observedAt = new Date(Date.now() - (stale ? 600_000 : 30_000)).toISOString();
+  const resetsAt = new Date(Date.now() + (stale ? -60_000 : 3_600_000)).toISOString();
+  const targets = ['claude', 'codex', 'copilot', 'antigravity', 'kiro'].map((provider, index) => {
+    const queried = queries.includes(provider);
+    const source = queried ? { claude: 'claude.get_usage', codex: 'codex.account/rateLimits/read',
+      copilot: 'copilot.account.getQuota', antigravity: 'antigravity.usage' }[provider]
+      : index === 0 ? 'claude.rate_limit_event' : index === 1 ? 'codex.account/rateLimits/updated' : null;
+    const windows = queried && provider === 'copilot' ? [
+      { id: 'premium_interactions', unit: 'requests', used: 0, limit: 1500, remaining: 1500, usedPercent: 0, resetsAt },
+      { id: 'chat', unit: 'requests', used: 0, unlimited: true, resetsAt },
+    ] : queried ? [{ id: provider === 'antigravity' ? 'gemini_models_weekly' : 'seven_day', unit: 'percent',
+      usedPercent: provider === 'claude' ? 6 : 22, windowMinutes: 10080, resetsAt }]
+      : index < 2 ? [{ id: index ? 'primary' : 'five_hour', unit: 'percent', usedPercent: index ? 60 : 25, resetsAt, windowMinutes: 300 }] : [];
+    return { provider, instance: 'default', backend: 'cli', usage: totals(index >= 2 ? null : 12500 + index * 1000, index ? 'EUR' : 'USD'), guardrails: [],
+      quota: { status: index === 4 ? 'unsupported' : windows.length ? 'available' : 'unavailable', freshness: stale ? 'stale' : 'fresh',
+        source, observedAt: windows.length ? observedAt : null, accountId: null, accountLinkage: 'unverified',
+        automaticRefresh: false, refreshSupported: index < 4, windows } };
+  });
+  return { schemaVersion: 1, generatedAt: timestamp(), runtime: { status: 'available', epoch },
+    coverage: { mode: 'memory', scope: 'runtime_observed_results', startedAt: observedAt, retainedRecords: 2, droppedRecords: 0, droppedQuotaTargets: 0, truncated: false, historyAvailable: false },
+    totals: { ...totals(26000), costs: [{ currency: 'USD', amount: 0.12 }, { currency: 'EUR', amount: 0.12 }] }, targets,
+    sessions: targets.slice(0, 2).map((target, index) => ({ ...target, sessionId: `fixture-session-${index + 1}` })), incidents: [], guardrails: [] };
+}, async refreshUsageQuota(target: { provider: string; instance: string }) {
+  assert.equal(target.instance, 'default'); assert.ok(['codex', 'copilot', 'claude', 'antigravity'].includes(target.provider));
+  queries.push(target.provider);
+  return { status: 'updated', nextRefreshAt: null, snapshot: await this.getUsageSnapshot() };
+} };
+const sessionSecret = 'isolated-usage-smoke-session-secret';
+const auth = await createFirstAdminLocalAuthState({ state: createEmptyPlatformAuthState(), displayName: 'Test',
+  identifier: 'test@example.test', password: 'isolated-fixture-password', sessionSecret, sessionTtlMs: 600_000 });
+const core = createDefaultCoreState(); core.setupCompleteAt = new Date().toISOString();
+const dependencies = { shared: {
+  config: loadConfig({ CATS_HOME_DIR: root, CATS_PLATFORM_DIR: root, CATS_CHAT_STATE_PATH: chatStatePath,
+    CATS_AUTH_SESSION_SECRET: sessionSecret }),
+  coreStore: new MemoryCoreStore(core), authStore: new MemoryPlatformAuthStore(auth.state),
+  runtimeClient: { getUsageSnapshot: async () => projectUsageSnapshot(await runtimeClient.getUsageSnapshot()),
+    refreshUsageQuota: async (target: { provider: string; instance: string }) => projectUsageQuotaRefresh(await runtimeClient.refreshUsageQuota(target)) },
+}, chat: {}, work: {}, code: {} } as unknown as ResolvedServerDependencies;
+// Use the same temp path as the package installer regardless of config environment aliases.
+dependencies.shared.config.chatStatePath = chatStatePath;
+const server = createServer(async (request, response) => {
+  try {
+    const url = new URL(request.url ?? '/', 'http://127.0.0.1');
+    if (rendererRoot && url.pathname === '/api/app-shell') {
+      response.writeHead(200, { 'content-type': 'application/json' }); response.end(JSON.stringify(hostEnvelope)); return;
+    }
+    if (url.pathname === '/smoke.js') { response.writeHead(200, { 'content-type': 'text/javascript' }); response.end(js); return; }
+    if (url.pathname.startsWith('/api/')) {
+      if (url.pathname.startsWith('/api/apps/') || url.pathname === '/api/auth/status') { await routeRequest(request, response, dependencies); return; }
+      response.writeHead(404); response.end(); return;
+    }
+    if (rendererRoot) {
+      const asset = url.pathname.startsWith('/assets/') ? url.pathname.slice(1) : 'index.html';
+      const assetPath = path.resolve(rendererRoot, asset);
+      if (!assetPath.startsWith(`${rendererRoot}${path.sep}`)) { response.writeHead(404); response.end(); return; }
+      const contentType = asset.endsWith('.js') ? 'text/javascript' : asset.endsWith('.css') ? 'text/css' : 'text/html';
+      response.writeHead(200, { 'content-type': contentType, 'cache-control': 'no-store' });
+      response.end(await readFile(assetPath)); return;
+    }
+    response.writeHead(200, { 'content-type': 'text/html', 'cache-control': 'no-store' });
+    response.end('<!doctype html><html><head><meta name="viewport" content="width=device-width, initial-scale=1"></head><body style="margin:0;background:#f4f5f2"><div id="root"></div><script type="module" src="/smoke.js"></script></body></html>');
+  } catch { response.writeHead(500); response.end('Fixture failure'); }
+});
+await new Promise<void>((resolve) => server.listen(0, '127.0.0.1', resolve));
+const address = server.address();
+if (!address || typeof address === 'string') throw new Error('No fixture port');
+const { chromium, _electron } = await import(pathToFileURL(process.env.CATS_TEST_PLAYWRIGHT_MODULE).href);
+const electronMode = args.includes('--electron');
+await mkdir(path.join(root, 'electron-profile'), { recursive: true });
+const browser = electronMode
+  ? await _electron.launch({ executablePath: process.env.CATS_TEST_BROWSER_EXECUTABLE,
+    env: { ...process.env, CATS_USAGE_SMOKE_PROFILE_DIR: path.join(root, 'electron-profile') },
+    args: [fileURLToPath(new URL('./usage-app-smoke-electron.cjs', import.meta.url))] })
+  : await chromium.launch({ executablePath: process.env.CATS_TEST_BROWSER_EXECUTABLE, headless: true });
+try {
+  const page = electronMode ? await browser.firstWindow()
+    : await browser.newPage({ viewport: { width: 1440, height: 1200 }, locale: 'zh-TW' });
+  await page.context().addCookies([{ name: 'cats_session', value: auth.session.token, url: `http://127.0.0.1:${address.port}` }]);
+  const errors: string[] = []; page.on('pageerror', (error: Error) => errors.push(error.message));
+  await page.goto(`http://127.0.0.1:${address.port}${entryPath}`);
+  const frame = page.frameLocator('iframe[title="Usage"]');
+  try { await frame.getByText('75% 剩餘', { exact: true }).waitFor({ timeout: 15_000 }); }
+  catch (error) {
+    process.stderr.write(`${JSON.stringify({ errors, body: await page.locator('body').innerText(), secure: await page.evaluate(() => isSecureContext) })}\n`);
+    throw error;
+  }
+  assert.equal(await page.locator('iframe').getAttribute('sandbox'), 'allow-scripts');
+  process.stdout.write('Usage iframe rendered and received the fixture snapshot.\n');
+  assert.equal(await frame.getByText('尚未支援', { exact: true }).count(), 1);
+  assert.equal(queries.length, 0, 'Opening the App never queries a CLI');
+  assert.equal(await frame.locator('[data-query-provider="kiro"]').count(), 0);
+  for (const provider of ['copilot', 'claude', 'antigravity']) {
+    await new Promise((resolve) => setTimeout(resolve, 1100));
+    await frame.locator(`[data-query-provider="${provider}"]`).click();
+    try { await frame.getByText(/已透過 .* CLI 取得額度回報/).first().waitFor({ timeout: 5000 }); }
+    catch (error) {
+      process.stderr.write(`${JSON.stringify({ queries, provider, body: await page.locator('body').innerText(),
+        frame: await frame.locator('body').innerText({ timeout: 1000 }).catch(() => 'Frame unavailable'), errors })}\n`);
+      throw error;
+    }
+    const expected = provider === 'copilot' ? /1,500 requests/ : provider === 'claude' ? /^94% 剩餘$/ : /^78% 剩餘$/;
+    await frame.getByText(expected).first().waitFor();
+  }
+  assert.deepEqual(queries, ['copilot', 'claude', 'antigravity']);
+  await frame.getByText('不限額', { exact: true }).waitFor();
+  assert.equal(await frame.locator('.stat .cost').innerText(), 'USD 0.12\nEUR 0.12');
+  const innerFrame = page.frames().find((candidate: { parentFrame(): unknown }) => candidate.parentFrame() !== null);
+  assert.ok(innerFrame);
+  await innerFrame.evaluate(() => new Promise((resolve) => requestAnimationFrame(() => requestAnimationFrame(resolve))));
+  const frameBounds = await page.locator('iframe').boundingBox();
+  assert.ok(frameBounds && frameBounds.width >= 800 && frameBounds.height >= 520, 'Dashboard has a usable desktop viewport');
+  const screenshotDir = path.resolve('build', 'usage-smoke'); await mkdir(screenshotDir, { recursive: true });
+  if (!electronMode) {
+    // Viewport/frame captures keep the opaque iframe's paint surface intact.
+    // Chromium full-page resizing can mispaint that surface even with correct DOM bounds.
+    await page.screenshot({ path: path.join(screenshotDir, 'usage-desktop.png') });
+    await page.locator('iframe').screenshot({ path: path.join(screenshotDir, 'usage-frame.png') });
+  }
+  await frame.locator('#provider').selectOption('copilot');
+  assert.equal(await frame.locator('.stat').first().locator('strong').innerText(), '—');
+  await frame.locator('#provider').selectOption('claude');
+  assert.equal(await frame.locator('.provider').count(), 1);
+  assert.equal(await frame.locator('tbody tr').count(), 1);
+  await frame.locator('#provider').selectOption('');
+  const refresh = async () => {
+    // The real host deliberately permits at most one UI request per second.
+    await new Promise((resolve) => setTimeout(resolve, 1100));
+    const before = reads;
+    await frame.getByRole('button', { name: '重新整理', exact: true }).click();
+    await page.waitForFunction(() => document.querySelector('iframe') !== null);
+    for (let attempt = 0; reads === before && attempt < 30; attempt++) await new Promise((resolve) => setTimeout(resolve, 50));
+    assert.ok(reads > before, 'Refresh reached the real host route');
+  };
+  offline = true; await refresh();
+  await frame.getByText('Runtime 無法連線 · 以下保留最後快照', { exact: true }).waitFor();
+  assert.equal(await frame.getByText('94% 剩餘', { exact: true }).count(), 1);
+  offline = false; stale = true; await refresh();
+  await frame.getByText('已過回報的重設時間；目前沒有可靠的未來重設時間', { exact: true }).first().waitFor();
+  assert.equal(await frame.getByText('94% 剩餘', { exact: true }).count(), 1);
+  epoch = 'fixture-restarted'; await refresh();
+  await frame.getByText('Runtime 已重新啟動，本次用量觀測區間已重設。', { exact: true }).waitFor();
+  await page.setViewportSize({ width: 390, height: 844 });
+  if (!electronMode) await page.screenshot({ path: path.join(screenshotDir, 'usage-mobile.png'), fullPage: true });
+  assert.equal(await innerFrame.evaluate(() => document.documentElement.scrollWidth <= window.innerWidth), true);
+  assert.equal(await innerFrame.evaluate(() => { try { return !!parent.document.body; } catch { return false; } }), false);
+  assert.equal(await innerFrame.evaluate(async () => { try { await fetch('/api/apps'); return true; } catch { return false; } }), false);
+  await registry.updateAppState('cats.usage', { installState: 'disabled' });
+  await new Promise((resolve) => setTimeout(resolve, 1100));
+  await frame.getByRole('button', { name: '重新整理', exact: true }).click();
+  await page.getByRole('alert').waitFor();
+  assert.equal(await page.locator('iframe').count(), 0);
+  await registry.updateAppState('cats.usage', { installState: 'enabled' });
+  offline = false; stale = false;
+  if (rendererRoot) {
+    await page.getByRole('button', { name: '返回大廳', exact: true }).click();
+    await page.getByRole('button', { name: /Usage/ }).click();
+    await page.frameLocator('iframe[title="Usage"]').getByText('94% 剩餘', { exact: true }).waitFor();
+  }
+  if (args.includes('--check-loading-recovery')) {
+    await page.clock.install();
+    const rendererPattern = '**/api/apps/cats.usage/renderer?*';
+    let releaseRequest!: () => void;
+    await page.route(rendererPattern, async (route: any) => {
+      await new Promise<void>((resolve) => { releaseRequest = resolve; });
+      await route.abort().catch(() => {}); // The host timeout may already have aborted it.
+    });
+    await page.goto(`http://127.0.0.1:${address.port}${entryPath}`);
+    await page.getByRole('status').filter({ hasText: '載入 Usage' }).waitFor();
+    await page.clock.fastForward(15_001);
+    await page.getByRole('alert').filter({ hasText: '載入逾時' }).waitFor();
+    await page.screenshot({ path: path.join(screenshotDir, 'usage-loading-timeout.png') });
+    await page.unroute(rendererPattern);
+    releaseRequest();
+    await page.getByRole('button', { name: '重新載入', exact: true }).click();
+    await page.frameLocator('iframe[title="Usage"]').getByText('94% 剩餘', { exact: true }).waitFor();
+    await page.route(rendererPattern, async (route: any) => {
+      const response = await route.fetch();
+      await route.fulfill({ response, json: { ...await response.json(), sdk: '' } });
+    });
+    await page.goto(`http://127.0.0.1:${address.port}${entryPath}`);
+    await page.locator('iframe[title="Usage"]').waitFor();
+    await page.clock.fastForward(15_001);
+    await page.getByRole('alert').filter({ hasText: '載入逾時' }).waitFor();
+    assert.equal(await page.locator('iframe').count(), 0);
+    await page.unroute(rendererPattern);
+    await page.getByRole('button', { name: '重新載入', exact: true }).click();
+    await page.frameLocator('iframe[title="Usage"]').getByText('94% 剩餘', { exact: true }).waitFor();
+  }
+  assert.deepEqual(errors, []);
+  process.stdout.write(`${JSON.stringify({ ok: true, reads, queries, rendererRoot, electronMode, loadingRecovery: args.includes('--check-loading-recovery'),
+    app: { id: usage.id, version: usage.version, sha256: usage.sha256 }, screenshotDir: electronMode ? null : screenshotDir, isolatedRegistry: root }, null, 2)}\n`);
+} finally {
+  await browser.close();
+  await new Promise<void>((resolve, reject) => server.close((error) => error ? reject(error) : resolve()));
+}

package/scripts/testing/conversation-navigation-smoke-electron.cjs

@@ -0,0 +1,134 @@
+// Usage: invoked by conversation-navigation-smoke.mjs; never run against real state.
+// CATS_NAV_SMOKE_URL selects the fixture server, PROFILE isolates Electron state,
+// and OUTPUT selects the screenshot/result directory. No Desktop supervisor loads.
+const { app, BrowserWindow } = require('electron');
+const { writeFile } = require('node:fs/promises');
+const path = require('node:path');
+app.setPath('userData', process.env.CATS_NAV_SMOKE_PROFILE);
+app.whenReady().then(async () => {
+  const window = new BrowserWindow({ width: 1440, height: 1000, show: false,
+    webPreferences: { sandbox: true, contextIsolation: true, nodeIntegration: false, backgroundThrottling: false, offscreen: true } });
+  window.webContents.setFrameRate(60);
+  const errors = [];
+  window.webContents.on('console-message', (event) => { if (event.level === 'error') errors.push(event.message); });
+  try {
+    await window.loadURL(process.env.CATS_NAV_SMOKE_URL);
+    const result = await window.webContents.executeJavaScript(`(async () => {
+      const wait = async (predicate, label) => {
+        const started = performance.now();
+        while (!predicate()) {
+          if (performance.now() - started > 10000) throw new Error('Timeout: ' + label + '\\n' + document.body.innerText);
+          await new Promise(resolve => setTimeout(resolve, 10));
+        }
+        await new Promise(resolve => requestAnimationFrame(() => requestAnimationFrame(resolve)));
+      };
+      await wait(() => document.body.innerText.includes('Transcript 1'), 'initial Chat render');
+      const fixture = window.__navigationSmoke;
+      const click = (title) => {
+        const row = [...document.querySelectorAll('button,a,[role="button"],span')].find(el => el.textContent.trim() === title);
+        if (!row) throw new Error('Missing navigation control: ' + title);
+        row.click();
+      };
+      fixture.click = click;
+      fixture.wait = wait;
+      fixture.delays.shell = 60000;
+      fixture.delays.preference = 2000;
+      const timings = [];
+      const checks = [];
+      for (const index of [1, 2, 3]) {
+        const start = performance.now(); click('Conversation ' + (index + 1));
+        await wait(() => document.body.innerText.includes('Transcript ' + (index + 1)), 'cold conversation ' + index);
+        timings.push({ kind: 'cold', conversation: index + 1, ms: performance.now() - start });
+      }
+      fixture.delays.snapshot = 2000;
+      for (const index of [0, 2, 1, 3, 0]) {
+        const start = performance.now(); click('Conversation ' + (index + 1));
+        await wait(() => document.body.innerText.includes('Transcript ' + (index + 1)), 'warm conversation ' + index);
+        const ms = performance.now() - start;
+        if (ms >= 1500) throw new Error('Warm navigation waited for a delayed response: ' + ms);
+        timings.push({ kind: 'warm', conversation: index + 1, ms });
+      }
+      fixture.pushReply(fixture.ids[0], 'Background reply received');
+      await wait(() => document.body.innerText.includes('Background reply received'), 'subscription update');
+      click('Conversation 2');
+      await wait(() => document.body.innerText.includes('Transcript 2'), 'leave updated conversation');
+      click('Conversation 1');
+      await wait(() => document.body.innerText.includes('Background reply received'), 'retained updated transcript');
+      const type = (value) => {
+        const input = document.querySelector('textarea');
+        if (!input) throw new Error('Missing composer textarea');
+        Object.getOwnPropertyDescriptor(HTMLTextAreaElement.prototype, 'value').set.call(input, value);
+        input.dispatchEvent(new Event('input', { bubbles: true }));
+      };
+      type('Keep conversation one draft');
+      await wait(() => document.querySelector('textarea')?.value === 'Keep conversation one draft', 'composer edit');
+      click('New Chat');
+      await wait(() => location.pathname.endsWith('/new'), 'new chat');
+      if (document.querySelector('textarea')?.value) throw new Error('New chat inherited conversation draft');
+      click('Conversation 1');
+      await wait(() => document.querySelector('textarea')?.value === 'Keep conversation one draft', 'restore conversation draft after New Chat');
+      checks.push('cold/warm A/B/C/D navigation', 'background update retention', 'conversation draft after New Chat');
+      fixture.delays.snapshot = 20;
+      for (const serverClose of [false, true]) {
+        const body = serverClose ? 'Recovered server read failure' : 'Recovered disconnected stream';
+        fixture.disconnect(fixture.ids[0], serverClose);
+        if (!document.body.innerText.includes('Transcript 1')) throw new Error('Disconnect cleared retained transcript');
+        fixture.pushReply(fixture.ids[0], body, false);
+        await wait(() => document.body.innerText.includes(body), body);
+      }
+      checks.push('network and server-error reconnection');
+      click('Group Chat');
+      await wait(() => location.pathname.includes('/new'), 'group draft');
+      checks.push({ mode: 'group draft', path: location.pathname, text: document.body.innerText });
+      click('Parallel Chat');
+      await wait(() => location.pathname.includes('/new'), 'parallel draft');
+      checks.push({ mode: 'parallel draft', path: location.pathname, text: document.body.innerText });
+      click('group fixture');
+      await wait(() => document.body.innerText.includes('group transcript'), 'group room');
+      checks.push({ mode: 'group room', text: document.body.innerText });
+      click('Fixture Cat Two');
+      await wait(() => document.body.innerText.includes('direct transcript'), 'direct lane');
+      checks.push({ mode: 'direct lane', text: document.body.innerText });
+      click('Conversation 1');
+      await wait(() => document.querySelector('textarea')?.value === 'Keep conversation one draft', 'draft after other chat modes');
+      return { timings, checks, calls: fixture.calls, text: document.body.innerText };
+    })()`);
+    result.errors = errors;
+    await writeFile(path.join(process.env.CATS_NAV_SMOKE_OUTPUT, 'result.json'), JSON.stringify(result, null, 2));
+    await writeFile(path.join(process.env.CATS_NAV_SMOKE_OUTPUT, 'chat.png'), (await window.webContents.capturePage()).toPNG());
+    for (const [control, marker, name] of [
+      ['Group Chat', 'Add another model to collaborate', 'group-draft'],
+      ['Parallel Chat', 'Follows lead', 'parallel-draft'],
+      ['group fixture', 'group transcript', 'group-room'],
+      ['Fixture Cat Two', 'direct transcript', 'direct-lane'],
+    ]) {
+      await window.webContents.executeJavaScript(`(async () => {
+        const fixture = window.__navigationSmoke;
+        fixture.click(${JSON.stringify(control)});
+        await fixture.wait(() => document.body.innerText.includes(${JSON.stringify(marker)}), ${JSON.stringify(name)});
+      })()`);
+      await writeFile(path.join(process.env.CATS_NAV_SMOKE_OUTPUT, `${name}.png`), (await window.webContents.capturePage()).toPNG());
+    }
+    await window.webContents.executeJavaScript(`(async () => {
+      document.querySelector('.recentOverflowButton').click();
+      await window.__navigationSmoke.wait(() => document.querySelector('.recentOverflowMenu'), 'sidebar overflow');
+      const menu = document.querySelector('.recentOverflowMenu');
+      const bounds = menu.getBoundingClientRect();
+      const topElement = document.elementFromPoint(bounds.x + bounds.width / 2, bounds.y + bounds.height / 2);
+      if (!menu.contains(topElement)) throw new Error('Sidebar overflow is obscured');
+    })()`);
+    await writeFile(path.join(process.env.CATS_NAV_SMOKE_OUTPUT, 'sidebar-overflow.png'), (await window.webContents.capturePage()).toPNG());
+    if (errors.length) throw new Error(errors.join('\n'));
+    window.webContents.stopPainting();
+    window.destroy();
+    app.quit();
+  } catch (error) {
+    await writeFile(path.join(process.env.CATS_NAV_SMOKE_OUTPUT, 'failure.png'), (await window.webContents.capturePage()).toPNG());
+    console.error(error);
+    console.error(errors.join('\n'));
+    window.webContents.stopPainting();
+    window.destroy();
+    process.exitCode = 1;
+    app.quit();
+  }
+});

package/scripts/testing/conversation-navigation-smoke-renderer.tsx

@@ -0,0 +1,102 @@
+// Isolated production Chat renderer. All services below use synthetic fixture data.
+import React from 'react';
+import { createRoot } from 'react-dom/client';
+import { BrowserRouter, Route, Routes } from 'react-router-dom';
+import { QueryClientProvider } from '@tanstack/react-query';
+import { GuideCatPlacementProvider } from '../../src/app/renderer/GuideCatPlacementProvider.js';
+import { sharedQueryClient } from '../../src/products/shared/renderer/queryClient.js';
+import type { AppShellPayload } from '../../src/products/shared/api/workspaceContracts.js';
+import type { ChannelSubscriptionState } from '../../src/products/shared/renderer/entitySubscriptionChannelDispatcher.js';
+import '../../src/design/index.css';
+
+const fixture = await (await fetch('/fixture.json')).json();
+const ids: string[] = fixture.ids;
+const payloads = fixture.payloads as Record<string, AppShellPayload>;
+const snapshots = fixture.snapshots as Record<string, ChannelSubscriptionState>;
+const calls: Array<{ url: string; method: string; at: number }> = [];
+const sources = new Set<FixtureEventSource>();
+const delays = { shell: 0, preference: 2_000, snapshot: 20 };
+let selected = ids[0];
+let shellCalls = 0;
+const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));
+
+class FixtureEventSource extends EventTarget {
+  onerror: (() => void) | null = null;
+  closed = false;
+  constructor(readonly url: string) {
+    super(); sources.add(this);
+    calls.push({ url, method: 'SSE', at: performance.now() });
+    const params = new URL(url, location.origin).searchParams;
+    const id = params.get('id');
+    if (params.get('kind') === 'channel' && id) {
+      void sleep(delays.snapshot).then(() => {
+        if (!this.closed) this.emit('snapshot', { kind: 'channel', id, version: 1, state: snapshots[id] });
+      });
+    }
+  }
+  emit(type: string, data: unknown) { this.dispatchEvent(new MessageEvent(type, { data: JSON.stringify(data) })); }
+  close() { this.closed = true; sources.delete(this); }
+}
+Object.defineProperty(globalThis, 'EventSource', { value: FixtureEventSource, configurable: true });
+globalThis.fetch = async (input, init) => {
+  const url = String(input); calls.push({ url, method: init?.method ?? 'GET', at: performance.now() });
+  if (url === '/api/app-shell') {
+    if (shellCalls++ > 0) await sleep(delays.shell);
+    return Response.json(payloads[selected]);
+  }
+  if (url === '/api/preferences') {
+    await sleep(delays.preference);
+    selected = JSON.parse(String(init?.body)).selectedChannelId ?? selected;
+    return Response.json({ preferences: { selectedChannelId: selected } });
+  }
+  if (url === '/api/core') return Response.json(fixture.core);
+  if (url === '/api/core/approvals') return Response.json({ approvals: [] });
+  if (url === '/api/providers') return Response.json({ state: 'ready', warnings: [], providers: ids.map((id, index) => {
+    const channel = snapshots[id].selectedChannel;
+    return { id: channel.pendingProvider, label: channel.pendingProvider,
+      defaultModel: channel.pendingModel, defaultInstance: 'native', defaultBackend: 'cli',
+      instances: [{ id: 'native', label: 'Native', target: 'cli/native', backend: 'cli', default: true }],
+      modelsPath: `/api/providers/${channel.pendingProvider}/models` };
+  }) });
+  const provider = /^\/api\/providers\/([^/]+)\/models/u.exec(url)?.[1];
+  if (provider) {
+    const channel = Object.values(snapshots).find((snapshot) => snapshot.selectedChannel.pendingProvider === provider)!.selectedChannel;
+    const model = { id: channel.pendingModel, label: channel.pendingModel, default: true };
+    const catalog = { provider, backend: 'cli', instance: 'cli/native', source: 'dynamic', cache: null,
+      defaultModel: channel.pendingModel, models: [model], entries: [model], presets: [], warnings: [],
+      defaultSelection: channel.pendingModelSelection, support: { tier: 'full', notes: [] },
+      controls: [{ key: `${provider}.reasoning_effort`, label: 'Reasoning effort', kind: 'enum', scope: 'both',
+        values: ['low', 'medium', 'high', 'max'].map((value) => ({ value, label: value })) }] };
+    return Response.json({ catalog });
+  }
+  if (/\/api\/channels\/[^/]+$/u.test(url) && init?.method === 'PATCH') {
+    const id = url.split('/').at(-1)!;
+    Object.assign(snapshots[id].selectedChannel, JSON.parse(String(init.body)));
+    return Response.json({ channel: payloads[id].chat.channels.find((channel) => channel.id === id) });
+  }
+  return Response.json({});
+};
+(window as any).__navigationSmoke = { ids, calls, delays, payloads, snapshots,
+  disconnect(id: string, serverClose = false) {
+    for (const source of sources) {
+      if (!source.url.includes(`id=${id}`)) continue;
+      if (serverClose) source.emit('close', { reason: 'Temporary fixture read failure', retryable: true });
+      else source.onerror?.();
+    }
+  },
+  pushReply(id: string, body: string, notify = true) {
+  const state = snapshots[id];
+  state.selectedChannel.messages.push({ ...state.selectedChannel.messages.at(-1)!, id: crypto.randomUUID(), body });
+  for (const source of sources) {
+    if (notify && source.url.includes(`id=${id}`)) source.emit('patch', { kind: 'channel', id, version: 1, patch: { kind: 'message.appended', state } });
+  }
+} };
+const { default: App } = await import('../../src/products/chat/renderer/App.js');
+createRoot(document.getElementById('root')!).render(
+  <QueryClientProvider client={sharedQueryClient}><BrowserRouter useTransitions={false}>
+    <GuideCatPlacementProvider guideCat={null} placement="docked" floatingAnchor={null}
+      sidecarMode="auto" onPersistSeen={() => {}} onCommit={() => {}}>
+      <Routes><Route path="/chat/*" element={<App />} /></Routes>
+    </GuideCatPlacementProvider>
+  </BrowserRouter></QueryClientProvider>,
+);

package/scripts/testing/conversation-navigation-smoke.mjs

@@ -0,0 +1,67 @@
+/**
+ * Usage: node scripts/testing/conversation-navigation-smoke.mjs [--help]
+ * Builds an isolated production Chat renderer and verifies navigation in hidden
+ * Electron/Chromium. All records and services are synthetic; user data is untouched.
+ * Writes build/conversation-navigation-smoke/result.json and a screenshot.
+ */
+import { build } from 'esbuild';
+import { mkdir, mkdtemp, readFile, rm } from 'node:fs/promises';
+import { createServer } from 'node:http';
+import { spawn } from 'node:child_process';
+import { once } from 'node:events';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import electron from 'electron';
+
+if (process.argv.includes('--help')) {
+  console.log('Usage: node scripts/testing/conversation-navigation-smoke.mjs\nSynthetic Chat navigation verification in hidden Electron. Results: build/conversation-navigation-smoke/.');
+  process.exit(0);
+}
+const out = path.resolve('build/conversation-navigation-smoke');
+const temporary = await mkdtemp(path.join(tmpdir(), 'cats-navigation-browser-'));
+await mkdir(out, { recursive: true });
+await build({ entryPoints: ['tests/fixtures/conversationNavigation.ts'], outfile: path.join(out, 'fixture.mjs'),
+  platform: 'node', format: 'esm', bundle: true, packages: 'external' });
+await build({ entryPoints: ['scripts/testing/conversation-navigation-smoke-renderer.tsx'], outfile: path.join(out, 'renderer.js'),
+  platform: 'browser', format: 'esm', bundle: true, define: { 'process.env.NODE_ENV': '"production"' },
+  loader: { '.woff2': 'file', '.woff': 'file', '.png': 'file', '.svg': 'file' } });
+const { createConversationNavigationFixture } = await import(pathToFileURL(path.join(out, 'fixture.mjs')));
+const fixture = await createConversationNavigationFixture(temporary, true);
+const allIds = fixture.state.channels.map((channel) => channel.id);
+const body = JSON.stringify({ ids: fixture.ids, payloads: Object.fromEntries(allIds.map((id) => [id, fixture.payload(id)])),
+  snapshots: Object.fromEntries(allIds.map((id) => [id, fixture.snapshot(id)])), core: await fixture.store.readCore() });
+const server = createServer(async (request, response) => {
+  try {
+    if (request.url === '/fixture.json') { response.setHeader('content-type', 'application/json'); response.end(body); return; }
+    const name = path.basename(new URL(request.url, 'http://localhost').pathname);
+    if (/\.(?:js|css|woff2?|png|svg)$/u.test(name)) {
+      response.setHeader('content-type', name.endsWith('.js') ? 'text/javascript' : name.endsWith('.css') ? 'text/css' : 'application/octet-stream');
+      response.end(await readFile(path.join(out, name))); return;
+    }
+    response.setHeader('content-type', 'text/html');
+    response.end('<!doctype html><html><head><link rel="stylesheet" href="/renderer.css"></head><body><div id="root"></div><script type="module" src="/renderer.js"></script></body></html>');
+  } catch (error) { response.writeHead(500); response.end(String(error)); }
+});
+server.listen(0, '127.0.0.1');
+await once(server, 'listening');
+const url = `http://127.0.0.1:${server.address().port}/chat/chats/${fixture.ids[0]}`;
+const childEnv = { ...process.env, CATS_NAV_SMOKE_URL: url,
+  CATS_NAV_SMOKE_PROFILE: path.join(temporary, 'electron'), CATS_NAV_SMOKE_OUTPUT: out };
+delete childEnv.ELECTRON_RUN_AS_NODE;
+const child = spawn(electron, ['scripts/testing/conversation-navigation-smoke-electron.cjs'], {
+  windowsHide: true, stdio: 'inherit', env: childEnv,
+});
+try {
+  const [code] = await once(child, 'exit');
+  if (code !== 0) throw new Error(`Navigation browser verification exited ${code}`);
+  const result = JSON.parse(await readFile(path.join(out, 'result.json'), 'utf8'));
+  console.log(JSON.stringify({ timings: result.timings,
+    checks: result.checks.map((check) => typeof check === 'string' ? check : check.mode), errors: result.errors }, null, 2));
+} finally {
+  server.closeAllConnections();
+  await new Promise((resolve) => server.close(resolve));
+  if (path.dirname(path.resolve(temporary)) !== path.resolve(tmpdir())
+    || !path.basename(temporary).startsWith('cats-navigation-browser-')) throw new Error('Unexpected smoke cleanup path');
+  await rm(temporary, { recursive: true, force: true });
+}

package/scripts/testing/usage-app-smoke-electron.cjs

@@ -0,0 +1,10 @@
+// Isolated Electron fixture: no Desktop supervisor, user profile, or live services.
+const { app, BrowserWindow } = require('electron');
+app.setPath('userData', process.env.CATS_USAGE_SMOKE_PROFILE_DIR);
+app.whenReady().then(async () => {
+  globalThis.testWindow = new BrowserWindow({ width: 1440, height: 1200, show: false,
+    webPreferences: { contextIsolation: true, nodeIntegration: false, sandbox: true, backgroundThrottling: false },
+  });
+  await globalThis.testWindow.loadURL('about:blank');
+});
+app.on('window-all-closed', () => app.quit());

package/scripts/testing/usage-app-smoke-renderer.tsx

@@ -0,0 +1,8 @@
+import { createRoot } from 'react-dom/client';
+import { AppRendererSurface } from '../../src/app/renderer/AppRendererSurface.js';
+import { installCsrfFetch } from '../../src/app/renderer/csrfFetch.js';
+
+installCsrfFetch();
+createRoot(document.getElementById('root')!).render(<AppRendererSurface appId="cats.usage" version={new URLSearchParams(location.search).get('appVersion') ?? ''}
+  title="Usage" locale={new URLSearchParams(location.search).get('locale') ?? 'zh-TW'}
+  onLobby={() => { document.body.textContent = 'Returned to lobby'; }} />);

package/scripts/validate-release-assets.mjs

@@ -34,7 +34,10 @@ const PROJECT_ROOT = resolve(dirname(SCRIPT_PATH), '..');
  */
 export const DESKTOP_RELEASE_MATRIX = [
   { platform: 'windows', formats: ['nsis'], arches: ['x64'] },
-  // macOS ships x64 only; Apple Silicon runs it under Rosetta 2.
+  // macOS ships x64 only: there is no macOS arm64 test environment, so a
+  // universal build would ship a slice nobody executed before release. Apple
+  // Silicon runs this under Rosetta 2. SPEC-111 section 8 records the exit
+  // condition for revisiting it.
   { platform: 'macos', formats: ['dmg', 'zip'], arches: ['x64'] },
   // Linux ships an arm64 .deb. electron-updater installs it with dpkg, which
   // needs elevation -- unlike the per-user Windows path.