@drscrewdriver/dsh-better-display 0.3.3-fork.1

package/tests/live-turn.test.ts

@@ -0,0 +1,218 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import type { AssistantChatData, ChatConversationViewNode } from '@deepseek-ai/dsh-client-ui-chat/client';
+import type { AssistantBlock, TurnLocation } from '@deepseek-ai/dsh-client-ui-conversation/client';
+import { assistantSegments, processExpanded } from '../src/client/projection.ts';
+import type { TurnBoundary } from '../src/client/projection.ts';
+import { foldSummary, presentLiveTurn, segmentLiveTurn, splitChain } from '../src/client/live-turn.ts';
+import type { LiveStep } from '../src/client/live-turn.ts';
+import { readerFlow } from '../src/client/tool-activity.ts';
+
+const open: TurnBoundary = { status: 'open', reason: null, latestStep: 4, closingStep: null };
+const completed: TurnBoundary = { status: 'closed', reason: 'completed', latestStep: 4, closingStep: 4 };
+
+function reasoning(id: string, text = `思考 ${id}`): LiveStep {
+  return { kind: 'reasoning', key: id, nodeKey: id, start: 0, blocks: [{ kind: 'reasoning', text }], step: Number(id.replace(/\D/g, '') || 0) };
+}
+function body(id: string, text = `输出 ${id}`): LiveStep {
+  return { kind: 'body', key: id, nodeKey: id, start: 1, blocks: [{ kind: 'text', text }], step: 0 };
+}
+function tool(id: string): LiveStep {
+  return { kind: 'tool', key: id, entry: { kind: 'tool', key: id, callId: id, step: 0, order: 0, draft: { kind: 'tool-call', callId: id, name: 'bash', argsRaw: '{}' } } };
+}
+function user(id: string): LiveStep {
+  return { kind: 'user', key: id, nodeKey: id };
+}
+function other(id: string): LiveStep {
+  return { kind: 'other', key: id, nodeKey: id };
+}
+
+function kinds(items: ReturnType<typeof presentLiveTurn>) {
+  return items.map(item => item.kind === 'fold' ? ['fold', item.summary, item.steps.map(step => step.key)] : [item.kind, item.key]);
+}
+
+test('body or tool alone never folds, including after the first reasoning', () => {
+  assert.equal(splitChain([reasoning('1')]).fold, null);
+  assert.equal(splitChain([reasoning('1'), body('2')]).fold, null);
+  assert.equal(splitChain([reasoning('1'), body('2'), tool('3')]).fold, null);
+  assert.equal(splitChain([body('2'), tool('3')]).fold, null);
+  assert.equal(splitChain([other('ctx'), reasoning('1'), body('2')]).fold, null);
+});
+
+test('a second reasoning folds every prior step into one box, then a third folds everything before it', () => {
+  const first = splitChain([reasoning('1'), body('2'), tool('3')]);
+  assert.equal(first.fold, null);
+  assert.deepEqual(first.open.map(step => step.key), ['1', '2', '3']);
+
+  const second = splitChain([reasoning('1'), body('2'), tool('3'), reasoning('4')]);
+  assert.deepEqual(second.fold?.map(step => step.key), ['1', '2', '3']);
+  assert.deepEqual(second.open.map(step => step.key), ['4']);
+  assert.equal(foldSummary(second.fold!), '思考×1 · 输出×1 · 工具×1');
+  if (second.fold?.[0]?.kind !== 'reasoning') throw new Error('folded reasoning missing');
+  assert.equal(second.fold[0].blocks[0]?.kind === 'reasoning' && second.fold[0].blocks[0].text, '思考 1');
+  assert.equal(foldSummary(second.fold).includes('思考 1'), false);
+
+  const withTool = splitChain([reasoning('1'), body('2'), tool('3'), reasoning('4'), tool('5')]);
+  assert.deepEqual(withTool.fold?.map(step => step.key), ['1', '2', '3']);
+  assert.deepEqual(withTool.open.map(step => step.key), ['4', '5']);
+
+  const third = splitChain([reasoning('1'), body('2'), tool('3'), reasoning('4'), tool('5'), reasoning('6')]);
+  assert.deepEqual(third.fold?.map(step => step.key), ['1', '2', '3', '4', '5']);
+  assert.deepEqual(third.open.map(step => step.key), ['6']);
+  assert.equal(foldSummary(third.fold!), '思考×2 · 输出×1 · 工具×2');
+
+  const latest = splitChain([reasoning('1'), body('2'), tool('3'), reasoning('4'), tool('5'), reasoning('6'), body('7')]);
+  assert.deepEqual(latest.fold?.map(step => step.key), ['1', '2', '3', '4', '5']);
+  assert.deepEqual(latest.open.map(step => step.key), ['6', '7']);
+});
+
+test('fold presentation keeps prior step keys so the reader can collapse the same process fragments in place', () => {
+  const chain = [reasoning('1'), body('2'), tool('3')];
+  const before = presentLiveTurn(chain, open);
+  assert.deepEqual(before.map(item => item.key), ['1', '2', '3']);
+
+  const second = presentLiveTurn([...chain, reasoning('4')], open);
+  assert.equal(second[0]?.kind, 'fold');
+  if (second[0]?.kind !== 'fold') throw new Error('missing fold');
+  assert.equal(second[0].key, 'live-fold:1');
+  assert.deepEqual(second[0].steps.map(step => step.key), before.map(item => item.key));
+  assert.deepEqual(second.filter(item => item.kind === 'open').map(item => item.key), ['4']);
+
+  const third = presentLiveTurn([...chain, reasoning('4'), tool('5'), reasoning('6')], open);
+  if (third[0]?.kind !== 'fold') throw new Error('missing grown fold');
+  assert.equal(third[0].key, 'live-fold:1');
+  assert.deepEqual(third[0].steps.map(step => step.key), ['1', '2', '3', '4', '5']);
+});
+
+test('presentLiveTurn keeps a single prior box rather than one fold per step', () => {
+  const items = presentLiveTurn([reasoning('1'), body('2'), tool('3'), reasoning('4'), tool('5'), reasoning('6'), body('7')], open);
+  const folds = items.filter(item => item.kind === 'fold');
+  assert.equal(folds.length, 1);
+  if (folds[0]?.kind !== 'fold') throw new Error('missing fold');
+  assert.equal(folds[0].steps.length, 5);
+  assert.deepEqual(items.filter(item => item.kind === 'open').map(item => item.key), ['6', '7']);
+});
+
+test('mid-turn user insert resets the chain; only the next reasoning folds post-insert priors', () => {
+  const before = presentLiveTurn([reasoning('1'), body('2'), tool('3'), user('insert'), body('4'), tool('5')], open);
+  assert.deepEqual(kinds(before), [
+    ['open', '1'], ['open', '2'], ['open', '3'],
+    ['user', 'insert'],
+    ['open', '4'], ['open', '5'],
+  ]);
+
+  const after = presentLiveTurn([reasoning('1'), body('2'), tool('3'), user('insert'), body('4'), tool('5'), reasoning('6')], open);
+  assert.deepEqual(kinds(after), [
+    ['open', '1'], ['open', '2'], ['open', '3'],
+    ['user', 'insert'],
+    ['fold', '输出×1 · 工具×1', ['4', '5']],
+    ['open', '6'],
+  ]);
+  const folds = after.filter(item => item.kind === 'fold');
+  assert.equal(folds.length, 1);
+  if (folds[0]?.kind !== 'fold') throw new Error('missing insert fold');
+  assert.ok(!folds[0].steps.some(step => ['1', '2', '3', 'insert'].includes(step.key)));
+});
+
+test('each chain has at most one fold box; a later chain does not split priors into per-step folds', () => {
+  const items = presentLiveTurn([
+    reasoning('1'), body('2'), tool('3'), reasoning('4'),
+    user('insert'),
+    body('5'), tool('6'), reasoning('7'),
+  ], open);
+  const folds = items.filter(item => item.kind === 'fold');
+  assert.equal(folds.length, 2);
+  if (folds[0]?.kind !== 'fold' || folds[1]?.kind !== 'fold') throw new Error('expected one box per chain');
+  assert.deepEqual(folds[0].steps.map(step => step.key), ['1', '2', '3']);
+  assert.deepEqual(folds[1].steps.map(step => step.key), ['5', '6']);
+  assert.equal(folds[0].summary, '思考×1 · 输出×1 · 工具×1');
+  assert.equal(folds[1].summary, '输出×1 · 工具×1');
+});
+
+test('successful turn close disables live fold so the existing final-answer rules still apply', () => {
+  const items = presentLiveTurn([reasoning('1'), body('2'), tool('3'), reasoning('4'), body('final')], completed);
+  assert.equal(items.some(item => item.kind === 'fold'), false);
+  assert.deepEqual(items.map(item => item.kind), ['open', 'open', 'open', 'open', 'open']);
+  assert.equal(processExpanded(undefined, completed), false);
+  assert.equal(processExpanded(undefined, { ...completed, reason: 'error' }), true);
+  assert.equal(processExpanded(undefined, { ...completed, reason: 'interrupted' }), true);
+  assert.equal(processExpanded(undefined, { ...completed, reason: 'blocked' }), true);
+  assert.equal(processExpanded(undefined, { status: 'unknown', reason: null, latestStep: -1, closingStep: null }), true);
+});
+
+test('error, interrupt, approval-blocked and unknown terminals do not live-fold away the transcript', () => {
+  const steps = [reasoning('1'), body('2'), tool('3'), reasoning('4')];
+  for (const reason of ['error', 'interrupted', 'aborted', 'blocked', 'max-tokens', 'future-terminal']) {
+    const items = presentLiveTurn(steps, { status: 'closed', reason, latestStep: 4, closingStep: 4 });
+    assert.equal(items.some(item => item.kind === 'fold'), false, reason);
+    assert.equal(processExpanded(undefined, { status: 'closed', reason, latestStep: 4, closingStep: 4 }), true, reason);
+  }
+  assert.equal(presentLiveTurn(steps, { status: 'unknown', reason: null, latestStep: -1, closingStep: null }).some(item => item.kind === 'fold'), false);
+});
+
+test('segmentation uses existing assistantSegments and tool boundaries and does not invent empty reasoning', () => {
+  const think: AssistantBlock = { kind: 'reasoning', text: '第一段思考' };
+  const moreThink: AssistantBlock = { kind: 'reasoning', text: '同一思考步骤' };
+  const text: AssistantBlock = { kind: 'text', text: '中途说明' };
+  const call: AssistantBlock = { kind: 'tool-call', callId: 'c1', name: 'bash', argsRaw: '{"command":"ls"}' };
+  const empty: AssistantBlock = { kind: 'reasoning', text: '   ' };
+  assert.deepEqual(assistantSegments([think, moreThink, text, call, empty]).map(part => [part.kind, part.start]), [
+    ['reasoning', 0], ['body', 2], ['reasoning', 4],
+  ]);
+
+  const data: AssistantChatData = { status: 'running', turn: 1, step: 0, blocks: [think, moreThink, text, call], time: 1 };
+  const node = {
+    key: 'a', id: 'a', kind: 'assistant-step', target: 'chat', data, anchorSeq: 10, visibility: 'visible',
+    location: { kind: 'step', step: { step: 0 } },
+  } as unknown as ChatConversationViewNode;
+  const turn = { turn: 1, steps: [{ step: 0, start: { seq: 10 }, data: { get: () => data } }] } as unknown as TurnLocation;
+  const flow = readerFlow({ key: 'turn:1', turn: 1, keys: ['a'] }, turn, key => key === 'a' ? node : undefined);
+  const steps = segmentLiveTurn(flow, key => key === 'a' ? node : undefined);
+  assert.deepEqual(steps.map(step => step.kind), ['reasoning', 'body', 'tool']);
+  assert.equal(steps[0]?.kind === 'reasoning' && steps[0].blocks.length, 2);
+  if (steps[0]?.kind !== 'reasoning') throw new Error('missing reasoning');
+  assert.equal(steps[0].blocks[0], think);
+  assert.equal(steps[0].blocks[1], moreThink);
+
+  const blankData: AssistantChatData = { ...data, blocks: [empty, text] };
+  const blank = { ...node, data: blankData } as unknown as ChatConversationViewNode;
+  const blankTurn = { turn: 1, steps: [{ step: 0, start: { seq: 10 }, data: { get: () => blankData } }] } as unknown as TurnLocation;
+  const blankFlow = readerFlow({ key: 'turn:1', turn: 1, keys: ['a'] }, blankTurn, () => blank);
+  assert.deepEqual(segmentLiveTurn(blankFlow, () => blank).map(step => step.kind), ['body']);
+});
+
+test('steering in the flow is a chain reset, same as a mid-turn user message', () => {
+  const think: AssistantBlock = { kind: 'reasoning', text: '先想' };
+  const text: AssistantBlock = { kind: 'text', text: '先说' };
+  const later: AssistantBlock = { kind: 'reasoning', text: '插入后再想' };
+  const first: AssistantChatData = { status: 'settled', turn: 1, step: 0, blocks: [think, text], time: 1 };
+  const second: AssistantChatData = { status: 'running', turn: 1, step: 1, blocks: [later], time: 2 };
+  const assistant = (key: string, seq: number, data: AssistantChatData) => ({
+    key, id: key, kind: 'assistant-step', target: 'chat', data, anchorSeq: seq, visibility: 'visible',
+    location: { kind: 'step', step: { step: data.step } },
+  }) as unknown as ChatConversationViewNode;
+  const steer = {
+    key: 'steer', id: 'steer', kind: 'steering', target: 'chat', data: { content: [{ type: 'text', text: '请改方向' }] },
+    anchorSeq: 15, visibility: 'visible', location: { kind: 'turn', turn: { turn: 1 } },
+  } as unknown as ChatConversationViewNode;
+  const nodes = new Map<string, ChatConversationViewNode>([
+    ['a', assistant('a', 10, first)],
+    ['steer', steer],
+    ['b', assistant('b', 20, second)],
+  ]);
+  const flow = readerFlow({ key: 'turn:1', turn: 1, keys: ['a', 'steer', 'b'] }, undefined, key => nodes.get(key));
+  const items = presentLiveTurn(segmentLiveTurn(flow, key => nodes.get(key)), open);
+  assert.deepEqual(kinds(items), [
+    ['open', 'a:reasoning:0'], ['open', 'a:body:1'],
+    ['user', 'steer'],
+    ['open', 'b:reasoning:0'],
+  ]);
+});
+
+test('disabling auto-fold keeps all steps open as plain streaming steps', () => {
+  const steps = [reasoning('1'), body('2'), tool('3'), reasoning('4'), tool('5'), reasoning('6')];
+  const items = presentLiveTurn(steps, open, false);
+  assert.equal(items.some(item => item.kind === 'fold'), false);
+  assert.deepEqual(items.map(item => item.key), ['1', '2', '3', '4', '5', '6']);
+  assert.deepEqual(items.map(item => item.kind), ['open', 'open', 'open', 'open', 'open', 'open']);
+});

package/tests/mcp-apps.test.ts

@@ -0,0 +1,157 @@
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import type { Code } from 'mdast';
+import {
+  isMcpAppCodeBlock,
+  extractMcpAppTitle,
+  extractMcpAppHeight,
+  ensureHtmlDocument,
+  extractHtmlTitle,
+  formatReceiptPrompt,
+  findComposerTextarea,
+  fillComposerDom,
+} from '../src/client/mcp-app.js';
+import { parseGfmWithMath } from '../src/client/markdown/parse.js';
+
+test('isMcpAppCodeBlock detects all valid MCP App code block formats', () => {
+  // Direct lang tags
+  assert.equal(isMcpAppCodeBlock('mcp-app', null, '<div>test</div>'), true);
+  assert.equal(isMcpAppCodeBlock('mcpapp', null, '<div>test</div>'), true);
+  assert.equal(isMcpAppCodeBlock('mcp-ui', null, '<div>test</div>'), true);
+  assert.equal(isMcpAppCodeBlock('mcp', null, '<div>test</div>'), true);
+  assert.equal(isMcpAppCodeBlock('mcp-app:html', null, '<div>test</div>'), true);
+  assert.equal(isMcpAppCodeBlock('html:mcp-app', null, '<div>test</div>'), true);
+
+  // Meta indicators
+  assert.equal(isMcpAppCodeBlock('html', 'mcp-app title="测试"', '<div>test</div>'), true);
+  assert.equal(isMcpAppCodeBlock(null, 'sep-1865', '<div>test</div>'), true);
+
+  // Content heuristic for SEP-1865 JSON-RPC
+  const quizSnippet = `
+    window.parent.postMessage({
+      jsonrpc: "2.0",
+      method: "ui/submit",
+      params: { choice: "A" }
+    }, "*");
+  `;
+  assert.equal(isMcpAppCodeBlock('html', null, quizSnippet), true);
+
+  // Negative cases
+  assert.equal(isMcpAppCodeBlock('typescript', null, 'const x = 1;'), false);
+  assert.equal(isMcpAppCodeBlock('json', null, '{"a": 1}'), false);
+  assert.equal(isMcpAppCodeBlock('html', null, '<h1>Hello World</h1>'), false);
+  assert.equal(isMcpAppCodeBlock(null, null, ''), false);
+});
+
+test('extractMcpAppTitle extracts title from meta or html content', () => {
+  assert.equal(extractMcpAppTitle('title="双盲方案盲选评测器"', '<div>test</div>'), '双盲方案盲选评测器');
+  assert.equal(extractMcpAppTitle("title='架构方案对比'", '<div>test</div>'), '架构方案对比');
+  assert.equal(extractMcpAppTitle(null, '<!DOCTYPE html><html><head><title>网页标题评测</title></head></html>'), '网页标题评测');
+  assert.equal(extractMcpAppTitle(null, '<div>无标题内容</div>'), undefined);
+});
+
+test('extractMcpAppHeight parses explicit height budget from meta', () => {
+  assert.equal(extractMcpAppHeight('title="看板" height=600'), 600);
+  assert.equal(extractMcpAppHeight('height="550px"'), 550);
+  assert.equal(extractMcpAppHeight('height=50'), undefined); // too small
+  assert.equal(extractMcpAppHeight('title="普通"'), undefined);
+});
+
+test('extractHtmlTitle extracts document title accurately', () => {
+  assert.equal(extractHtmlTitle('<title>我的测试 App</title>'), '我的测试 App');
+  assert.equal(extractHtmlTitle('<title  class="main" > 性能看板 </title>'), '性能看板');
+  assert.equal(extractHtmlTitle('<div>没有标题</div>'), undefined);
+});
+
+test('ensureHtmlDocument wraps bare fragments and preserves complete documents with theme bridge', () => {
+  const completeHtml = '<!DOCTYPE html>\n<html><head><title>Test</title></head><body>Content</body></html>';
+  const processed = ensureHtmlDocument(completeHtml, 'dark');
+  assert.ok(processed.includes('<title>Test</title>'));
+  assert.ok(processed.includes('<body>Content</body>'));
+  assert.ok(processed.includes('applyTheme'));
+
+  const fragment = '<div class="quiz"><h2>Question</h2></div>';
+  const wrapped = ensureHtmlDocument(fragment, 'dark');
+  assert.ok(wrapped.startsWith('<!DOCTYPE html>'));
+  assert.ok(wrapped.includes('<html lang="zh-CN" data-theme="dark" class="dark"'));
+  assert.ok(wrapped.includes(fragment));
+});
+
+test('markdown parsing correctly extracts MCP App code fence and prepares for McpAppFrame mounting', () => {
+  const markdown = `
+这里是为您生成的方案评测器，请在下方直接点击交互：
+
+\`\`\`mcp-app title="双盲方案盲选评测器"
+<!DOCTYPE html>
+<html lang="zh-CN">
+<head>
+  <meta charset="UTF-8">
+  <title>双盲方案盲选评测器</title>
+</head>
+<body>
+  <div class="quiz-card">
+    <h3>题目</h3>
+    <button onclick="submitChoice('B')">B: 延迟消息队列</button>
+  </div>
+</body>
+</html>
+\`\`\`
+
+如有其他疑问，请随时告诉我。
+  `.trim();
+
+  const root = parseGfmWithMath(markdown);
+  const codeNode = root.children.find((child): child is Code => child.type === 'code');
+  assert.ok(codeNode, 'Must contain a code block node');
+  assert.equal(codeNode.lang, 'mcp-app');
+  assert.equal(codeNode.meta, 'title="双盲方案盲选评测器"');
+  assert.equal(isMcpAppCodeBlock(codeNode.lang, codeNode.meta, codeNode.value), true);
+  assert.equal(extractMcpAppTitle(codeNode.meta, codeNode.value), '双盲方案盲选评测器');
+  assert.ok(ensureHtmlDocument(codeNode.value).includes('延迟消息队列'));
+});
+
+test('formatReceiptPrompt formats clean, natural conversational text without extra whitespace or raw JSON dump', () => {
+  const quizParams = {
+    task: 'architecture_quiz_completed',
+    choice: 'B',
+    desc: '延迟消息队列',
+  };
+  const prompt = formatReceiptPrompt(quizParams, '双盲方案盲选评测器');
+  assert.equal(prompt, '我在「双盲方案盲选评测器」中选择了：B（延迟消息队列）。请根据我的选择继续。');
+  assert.ok(!prompt.includes('\n'), 'Must not contain multiline newlines');
+  assert.ok(!prompt.includes('{'), 'Must not dump raw JSON braces');
+
+  const variantParams = {
+    selectedVariant: 'Skill_v2',
+    score: 95,
+  };
+  assert.equal(formatReceiptPrompt(variantParams), '我在方案评测中选择了：Skill_v2，得分：95。请根据该方案继续分析。');
+
+  const actionParams = {
+    action: 'reset_counter',
+    payload: { count: 0 },
+  };
+  assert.equal(formatReceiptPrompt(actionParams, '计数器'), '[计数器] 已完成 reset_counter: {"count":0}');
+});
+
+test('ensureHtmlDocument injects theme bridge and auto-height reporter into complete documents', () => {
+  const completeHtml = '<!DOCTYPE html>\n<html><head><title>Demo</title></head><body><div class="box">hi</div></body></html>';
+  const processed = ensureHtmlDocument(completeHtml, 'dark');
+  assert.ok(processed.includes('<title>Demo</title>'));
+  assert.ok(processed.includes('<body><div class="box">hi</div></body>'));
+  // Theme bridge must apply the initial theme and listen for live host updates
+  // (host pushes ui/initialize result / host-context-changed carrying hostContext.theme).
+  assert.ok(processed.includes('applyTheme("dark")'));
+  assert.ok(processed.includes('hostContext'));
+  // Auto-height reporter must observe the body and emit SEP-1865 resize events.
+  assert.ok(processed.includes('ResizeObserver'));
+  assert.ok(processed.includes('ui/resize'));
+});
+
+test('findComposerTextarea is importable and null-safe without a DOM', () => {
+  assert.equal(findComposerTextarea(undefined as unknown as Document), null);
+});
+
+test('fillComposerDom refuses without a DOM instead of throwing', () => {
+  assert.equal(fillComposerDom('hello'), false);
+});

package/tests/message-chrome.test.ts

@@ -0,0 +1,29 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { formatMessageClock, formatRanFor, formatRunDuration } from '../src/client/message-chrome.ts';
+
+test('run duration matches official Chat labels', () => {
+  assert.equal(formatRunDuration(0), '0秒');
+  assert.equal(formatRunDuration(19_000), '19秒');
+  assert.equal(formatRunDuration(118_000), '1分58秒');
+  assert.equal(formatRunDuration(65_000), '1分05秒');
+  assert.equal(formatRanFor(118_000), '用时 1分58秒');
+});
+
+test('same calendar day is HH:mm', () => {
+  const now = new Date(2026, 8, 11, 16, 40).getTime();
+  const time = new Date(2026, 8, 11, 16, 36).getTime();
+  assert.equal(formatMessageClock(time, now), '16:36');
+});
+
+test('earlier this year includes month and day', () => {
+  const now = new Date(2026, 8, 11, 16, 40).getTime();
+  const time = new Date(2026, 7, 3, 9, 5).getTime();
+  assert.equal(formatMessageClock(time, now), '8月3日 09:05');
+});
+
+test('other years include the year', () => {
+  const now = new Date(2026, 8, 11, 16, 40).getTime();
+  const time = new Date(2025, 11, 31, 23, 4).getTime();
+  assert.equal(formatMessageClock(time, now), '2025年12月31日 23:04');
+});

package/tests/official-slots.test.ts

@@ -0,0 +1,112 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { memo } from 'react';
+import { SlotCore } from '@deepseek-ai/dsh-client-ui-slots';
+import { mirrorOfficialSlot, readerTailMatch, type CompositionRegistry } from '../src/client/official-slots.js';
+
+function registry(kind: 'keyed' | 'chain' | 'list' = 'keyed') {
+  const core = new SlotCore();
+  const register = (options: object, component: unknown) => (core.register as Function)(options, component) as () => void;
+  register({ name: 'root', children: {
+    source: { kind, scope: 'session' },
+    reader: { kind, scope: 'session' },
+  } }, () => null);
+  const slots: CompositionRegistry = {
+    register,
+    spec: key => core.spec(key as never),
+    entriesOfSlot: key => core.entriesOfSlot(key),
+    subscribe: (key, fn) => core.subscribe(key, fn),
+    inject: () => { throw new Error('not used by the subtree test'); },
+  };
+  return { core, slots, register };
+}
+const changed = () => new Promise(resolve => queueMicrotask(resolve));
+
+test('official present cards retain their data while the existing Reader produced row stays unique', () => {
+  const original = Object.freeze({ produced: Object.freeze(['/work/code.ts']), presented: Object.freeze([{ path: '/work/report.pdf', seq: 42 }]), future: 'retained' });
+  assert.deepEqual(readerTailMatch(original, ['/work/code.ts']), { produced: [], presented: original.presented, future: 'retained' });
+  assert.equal(readerTailMatch(original), original);
+  assert.deepEqual(readerTailMatch({ produced: ['/work/code.ts', '/work/new.ts'], presented: [] }, ['/work/code.ts']), { produced: ['/work/new.ts'], presented: [] });
+  assert.deepEqual(original.produced, ['/work/code.ts']);
+  const future = { artifacts: ['/work/report.pdf'] };
+  assert.equal(readerTailMatch(future), future);
+});
+
+test('official memo components retain injection, store, locale and selector metadata', () => {
+  const { core, slots, register } = registry('chain');
+  const component = memo(() => null);
+  const inject = () => ({ hooks: { status: { getSnapshot: () => 1, subscribe: () => () => {} } } });
+  const select = (owner: unknown) => owner;
+  const store = { create: () => ({}) };
+  register({ name: 'source', select, inject, store, locale: 'feedback', priority: -7 }, component);
+  const before = core.entriesOfSlot('source')[0];
+  const stop = mirrorOfficialSlot(slots, 'source', 'reader', 'reader.children');
+  const mirrored = core.entriesOfSlot('reader')[0];
+  assert.equal(mirrored.component, component);
+  assert.equal(mirrored.inject, inject);
+  assert.equal(mirrored.select, select);
+  assert.equal(mirrored.store, store);
+  assert.equal(mirrored.locale, 'feedback');
+  assert.equal(mirrored.options.priority, -7);
+  assert.equal(core.entriesOfSlot('source')[0], before);
+  stop();
+  assert.equal(core.entriesOfSlot('reader').length, 0);
+  assert.equal(core.entriesOfSlot('source')[0], before);
+});
+
+test('nested declarations use distinct seats and are disposed without touching the source', () => {
+  const { core, slots, register } = registry();
+  const hookContext = { hooks: { turnData: () => () => 'live' } };
+  register({ name: 'source', key: 'read-image', children: { images: { kind: 'single', scope: 'session', inject: hookContext } } }, () => null);
+  const child = memo(() => null);
+  register({ name: 'images', locale: 'images' }, child);
+  const before = core.snapshot('source');
+  const stop = mirrorOfficialSlot(slots, 'source', 'reader', 'reader.children');
+  assert.equal(core.entriesOfSlot('reader.children/images')[0].component, child);
+  assert.equal(slots.spec('reader.children/images')?.inject, hookContext);
+  assert.deepEqual(core.snapshot('source'), before);
+  stop();
+  assert.equal(slots.spec('reader.children/images'), undefined);
+  assert.equal(core.entriesOfSlot('images')[0].component, child);
+});
+
+test('new registrations do not remount existing cards; winner changes and unload reconcile', async () => {
+  const { core, slots, register } = registry();
+  const first = memo(() => null);
+  const second = memo(() => null);
+  const fallback = memo(() => null);
+  register({ name: 'source', key: 'read' }, first);
+  const stop = mirrorOfficialSlot(slots, 'source', 'reader', 'reader.children');
+  const originalSeat = core.entriesOfSlot('reader')[0];
+  const removeNew = register({ name: 'source', key: 'new-official-tool' }, second);
+  await changed();
+  assert.equal(core.entriesOfSlot('reader').find(e => e.options.key === 'read'), originalSeat);
+  assert.equal(core.entriesOfSlot('reader').length, 2);
+  const restore = register({ name: 'source', key: 'read', priority: -1 }, fallback);
+  await changed();
+  assert.equal(core.entriesOfSlot('reader').find(e => e.options.key === 'read')?.component, fallback);
+  restore();
+  removeNew();
+  await changed();
+  assert.equal(core.entriesOfSlot('reader').length, 1);
+  assert.equal(core.entriesOfSlot('reader')[0].component, first);
+  stop();
+  register({ name: 'source', key: 'after-reader-unload' }, second);
+  await changed();
+  assert.equal(core.entriesOfSlot('reader').length, 0);
+});
+
+test('partial setup rolls back its own registrations on a nested contract failure', () => {
+  const { core, slots, register } = registry();
+  register({ name: 'source', key: 'nested', children: { detail: { kind: 'single', scope: 'session' } } }, () => null);
+  register({ name: 'detail' }, () => null);
+  const failing = { ...slots, register(options: Parameters<CompositionRegistry['register']>[0], component: unknown) {
+    if (options.name === 'reader.children/detail') throw new Error('fixture failure');
+    return slots.register(options, component);
+  } };
+  assert.throws(() => mirrorOfficialSlot(failing, 'source', 'reader', 'reader.children'), /fixture failure/);
+  assert.equal(core.entriesOfSlot('reader').length, 0);
+  assert.equal(slots.spec('reader.children/detail'), undefined);
+  assert.equal(core.entriesOfSlot('source').length, 1);
+  assert.equal(core.entriesOfSlot('detail').length, 1);
+});

package/tests/open-file.test.ts

@@ -0,0 +1,114 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { readFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import {
+  deliverableOpenModeOf,
+  fileAddressFor,
+  isFolderOpenPath,
+  modeFromSnapshot,
+  openDeliverableFile,
+  resolveOpenWorkspacePath,
+} from '../src/client/open-file.ts';
+
+test('index still routes opens through #13 open-mode, not a forced sidebar', () => {
+  const index = readFileSync(resolve(dirname(fileURLToPath(import.meta.url)), '../src/client/index.tsx'), 'utf8');
+  assert.match(index, /modeFromSnapshot\(prefs\)/);
+  assert.match(index, /openDeliverableFile/);
+  assert.doesNotMatch(index, /openOnDesktop/);
+  assert.doesNotMatch(index, /sidebarRight\.openResource!\(address\)/);
+});
+
+test('deliverable open mode defaults to external', () => {
+  assert.equal(deliverableOpenModeOf(undefined), 'external');
+  assert.equal(deliverableOpenModeOf('external'), 'external');
+  assert.equal(deliverableOpenModeOf('sidebar'), 'sidebar');
+  assert.equal(deliverableOpenModeOf('other'), 'external');
+  assert.equal(modeFromSnapshot(undefined), 'external');
+  assert.equal(modeFromSnapshot({ getSnapshot: () => ({}) }), 'external');
+});
+
+test('folder affordances stay on the OS path', () => {
+  assert.equal(isFolderOpenPath('.'), true);
+  assert.equal(isFolderOpenPath(''), true);
+  assert.equal(isFolderOpenPath('src/a.ts'), false);
+});
+
+test('fileAddressFor matches official session-scoped grammar', () => {
+  assert.equal(
+    fileAddressFor('s1', '/repo', 'src/client/Reader.tsx'),
+    'dsh-resource://file/session/s1/src/client/Reader.tsx',
+  );
+  assert.equal(
+    fileAddressFor('s1', '/repo', '/repo/src/a.ts'),
+    'dsh-resource://file/session/s1/src/a.ts',
+  );
+  assert.equal(
+    fileAddressFor('id with space', undefined, 'notes and more.md'),
+    'dsh-resource://file/session/id%20with%20space/notes%20and%20more.md',
+  );
+});
+
+test('sidebar mode opens the right-panel address; external uses the system opener', async () => {
+  const opened: string[] = [];
+  const sidebar: string[] = [];
+  const resolve = (cwd: string | undefined, path: string) => `${cwd ?? ''}/${path}`;
+
+  assert.equal(await openDeliverableFile({
+    path: 'a.ts',
+    mode: 'external',
+    sessionId: 's1',
+    cwd: '/repo',
+    resolveWorkspacePath: resolve,
+    openExternal: async (path) => { opened.push(path); },
+    openSidebar: (address) => { sidebar.push(address); },
+  }), 'external');
+  assert.deepEqual(opened, ['/repo/a.ts']);
+  assert.deepEqual(sidebar, []);
+
+  assert.equal(await openDeliverableFile({
+    path: 'a.ts',
+    mode: 'sidebar',
+    sessionId: 's1',
+    cwd: '/repo',
+    resolveWorkspacePath: resolve,
+    openExternal: async (path) => { opened.push(path); },
+    openSidebar: (address) => { sidebar.push(address); },
+  }), 'sidebar');
+  assert.deepEqual(sidebar, ['dsh-resource://file/session/s1/a.ts']);
+  assert.deepEqual(opened, ['/repo/a.ts']);
+});
+
+test('missing Sidebar API warns and falls back to the system opener', async () => {
+  const warnings: string[] = [];
+  const opened: string[] = [];
+  assert.equal(await openDeliverableFile({
+    path: 'a.ts',
+    mode: 'sidebar',
+    sessionId: 's1',
+    cwd: '/repo',
+    resolveWorkspacePath: (_cwd, path) => path,
+    openExternal: async (path) => { opened.push(path); },
+    warn: (message) => { warnings.push(message); },
+  }), 'external');
+  assert.deepEqual(opened, ['a.ts']);
+  assert.match(warnings[0] ?? '', /sidebarRight.openResource is not available/);
+});
+
+test('workspace folder clicks stay external even when sidebar mode is on', async () => {
+  const sidebar: string[] = [];
+  const opened: string[] = [];
+  assert.equal(await openDeliverableFile({
+    path: '.',
+    mode: 'sidebar',
+    sessionId: 's1',
+    cwd: '/repo',
+    resolveWorkspacePath: (cwd, path) => `${cwd}/${path}`,
+    openExternal: async (path) => { opened.push(path); },
+    openSidebar: (address) => { sidebar.push(address); },
+  }), 'external');
+  assert.deepEqual(opened, ['/repo']);
+  assert.deepEqual(sidebar, []);
+  assert.equal(resolveOpenWorkspacePath('/repo', '.', (cwd, path) => `${cwd}/${path}`), '/repo');
+});