@antst/dashi 0.1.0-alpha.5

package/lib/renderer.js

@@ -0,0 +1,414 @@
+import { Editor, TuiAltScreen, TuiMainScreen, stripTerminalSequences, truncateToWidth, wrapTextWithAnsi, } from '@earendil-works/pi-tui';
+import { caretOffset, installInput } from './input.js';
+import { hasCompletionTrigger } from './completion-trigger.js';
+import { createProcessTerminal } from './terminal-guard.js';
+const RESET = '\u001B[0m';
+const BOLD_CYAN = '\u001B[1;36m';
+const DIM = '\u001B[2m';
+const FAINT_BORDER = '\u001B[90m';
+const GREEN = '\u001B[32m';
+const RED = '\u001B[31m';
+const YELLOW = '\u001B[33m';
+const COPY_LIMIT = 64 * 1024;
+const OVERSCAN_CELLS = 8;
+const THEME_GENERATION = 1;
+const SPINNER_FRAMES = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+const SPINNER_INTERVAL_MS = 80;
+export function supportsOsc52(terminalType) {
+    return terminalType?.toLocaleLowerCase() !== 'dumb';
+}
+function setEditor(editor, text, cursor) {
+    editor.setText(text);
+    if (cursor === undefined)
+        return;
+    const lines = text.split('\n');
+    const lineIndex = Math.max(0, Math.min(cursor.line, lines.length - 1));
+    const line = lines[lineIndex] ?? '';
+    const col = Math.max(0, Math.min(cursor.col, line.length));
+    const suffix = `${line.slice(col)}${lines.slice(lineIndex + 1).map(value => `\n${value}`).join('')}`;
+    const graphemes = [...new Intl.Segmenter(undefined, { granularity: 'grapheme' }).segment(suffix)].length;
+    for (let step = 0; step < graphemes; step++)
+        editor.handleInput('\u001B[D');
+}
+function toolText(cell, mode, accessible) {
+    const card = cell.tool;
+    const color = cell.kind === 'error' ? RED : cell.pending ? YELLOW : GREEN;
+    const marker = accessible
+        ? `[${cell.kind === 'error' ? 'error' : cell.pending === true ? 'pending' : 'done'}]`
+        : cell.pending === true ? '○' : '●';
+    if (card === undefined)
+        return `${color}${marker} ${plain(cell.text)}${RESET}`;
+    const status = card.status === undefined ? '' : `  ${DIM}${plain(card.status)}${RESET}`;
+    const summaries = card.diffs?.map(diff => `${plain(diff.path)} ${GREEN}+${String(diff.added)}${RESET} ${RED}-${String(diff.removed)}${RESET}`) ?? [];
+    const head = `${color}${marker} ${plain(card.title)}${RESET}${status}${summaries.length === 0 ? '' : `  ${summaries.join(' · ')}`}`;
+    if (mode !== 'expanded' || cell.collapsed === true)
+        return head;
+    const body = card.diffs === undefined
+        ? card.body
+        : card.diffs.flatMap(diff => [`${FAINT_BORDER}── ${plain(diff.path)}${RESET}`, ...diff.lines.map(value => plain(value))]).join('\n');
+    return body === undefined || body === '' ? head : `${head}\n${DIM}${plain(body, true)}${RESET}`;
+}
+function cellText(cell, toolMode, accessible, now = Date.now()) {
+    if (cell.tool !== undefined || cell.kind === 'tool')
+        return toolText(cell, toolMode, accessible);
+    const raw = accessible && cell.kind === 'todo'
+        ? cell.text.replace(/^✓ /gmu, '[done] ').replace(/^● /gmu, '[active] ').replace(/^○ /gmu, '[pending] ')
+        : cell.text;
+    const safe = plain(raw, true);
+    switch (cell.kind) {
+        case 'user': return `${BOLD_CYAN}You${RESET}\n${safe}`;
+        case 'assistant': return `${BOLD_CYAN}Assistant${RESET}\n${safe}`;
+        case 'command': {
+            const elapsed = cell.elapsedMs ?? (cell.startedAt === undefined ? undefined : Math.max(0, now - cell.startedAt));
+            const marker = cell.pending === true
+                ? accessible ? '[running]' : SPINNER_FRAMES[Math.floor(now / SPINNER_INTERVAL_MS) % SPINNER_FRAMES.length]
+                : accessible ? '[done]' : '◆';
+            return `${cell.pending === true ? YELLOW : DIM}${marker} ${safe}${elapsed === undefined ? '' : ` · ${duration(elapsed)}`}${RESET}`;
+        }
+        case 'context': return `${DIM}Context · ${safe}${RESET}`;
+        case 'shell': return `${DIM}Shell${RESET}\n${safe}`;
+        case 'compaction': return `${DIM}${accessible ? '[compacted]' : '↻'} ${safe}${RESET}`;
+        case 'reasoning': return cell.collapsed
+            ? `${DIM}Thinking · ${[...safe].length} characters${RESET}`
+            : `${DIM}Thinking${RESET}\n${safe}`;
+        case 'outcome': return `${DIM}${accessible ? '[done]' : '✓'} ${safe}${RESET}`;
+        case 'todo': return cell.collapsed ? `${DIM}${safe}${RESET}` : `${BOLD_CYAN}${safe}${RESET}`;
+        case 'error': return `${RED}Error · ${safe}${RESET}${cell.detail === undefined ? '' : `\n${DIM}${plain(cell.detail)}${RESET}`}`;
+    }
+}
+function duration(ms) {
+    const seconds = Math.max(0, Math.floor(ms / 1_000));
+    if (seconds < 60)
+        return `${String(seconds)}s`;
+    const minutes = Math.floor(seconds / 60);
+    if (minutes < 60)
+        return `${String(minutes)}m ${String(seconds % 60)}s`;
+    return `${String(Math.floor(minutes / 60))}h ${String(minutes % 60)}m`;
+}
+function jobElapsed(job, now) {
+    return Math.max(0, (job.finishedAt ?? now) - job.startedAt);
+}
+function subagentElapsed(subagent, now) {
+    if (subagent.elapsedMs === undefined)
+        return undefined;
+    if (subagent.active === undefined)
+        return subagent.elapsedMs;
+    const through = subagent.state === 'running' ? now : subagent.active.through;
+    return subagent.elapsedMs + Math.max(0, through - subagent.active.since);
+}
+function activities(state) {
+    return [
+        ...(state.root?.subagents ?? []).map(value => ({ kind: 'subagent', value })),
+        ...(state.root?.jobs ?? []).map(value => ({ kind: 'job', value })),
+    ];
+}
+function latestPendingCommand(cells) {
+    for (let index = cells.length - 1; index >= 0; index--) {
+        const cell = cells[index];
+        if (cell?.kind === 'command' && cell.pending === true)
+            return cell;
+    }
+}
+function activityText(activity, now) {
+    if (activity.kind === 'job') {
+        const job = activity.value;
+        return `Job · ${job.label} · ${job.status} · ${duration(jobElapsed(job, now))}${job.detail === undefined ? '' : ` · ${job.detail}`}`;
+    }
+    const subagent = activity.value;
+    const elapsed = subagentElapsed(subagent, now);
+    return `Subagent · ${subagent.label} · ${subagent.state}${elapsed === undefined ? '' : ` · ${duration(elapsed)}`}${subagent.summary === undefined ? '' : ` · ${subagent.summary}`}`;
+}
+function plain(text, preserveNewlines = false) {
+    const withoutC1 = text
+        .replace(/\u009B[0-?]*[ -/]*[@-~]/gu, '')
+        .replace(/[\u0080-\u009F]/gu, '');
+    return [...stripTerminalSequences(withoutC1)].map(character => {
+        const code = character.codePointAt(0) ?? 0;
+        if (preserveNewlines && character === '\n')
+            return character;
+        return code < 32 || code === 127 ? ' ' : character;
+    }).join('');
+}
+function line(text, width) {
+    return truncateToWidth(text, Math.max(1, width), '…');
+}
+function theme() {
+    const identity = (text) => text;
+    return {
+        borderColor: text => `${FAINT_BORDER}${text}${RESET}`,
+        selectList: {
+            selectedPrefix: identity,
+            selectedText: identity,
+            description: identity,
+            scrollInfo: identity,
+            noMatch: identity,
+        },
+    };
+}
+export function createRenderer(options) {
+    const terminal = options.terminal ?? createProcessTerminal(options.inline ? undefined : lines => {
+        options.dispatch({ type: 'scroll', direction: lines > 0 ? 'page-up' : 'page-down', lines: Math.abs(lines) });
+    });
+    const terminalType = options.terminalType ?? (options.terminal === undefined ? process.env.TERM : undefined);
+    const accessible = options.accessible === true || terminalType?.toLocaleLowerCase() === 'dumb';
+    const osc52 = supportsOsc52(terminalType);
+    const tui = options.inline
+        ? new TuiMainScreen(terminal, true)
+        : new TuiAltScreen(terminal, true, undefined, { mouse: true });
+    const editor = new Editor(tui, theme(), { paddingX: 1 });
+    editor.disableSubmit = true;
+    editor.onChange = text => {
+        const caret = caretOffset(text, editor.getCursor());
+        options.dispatch({
+            type: 'composer-changed', text, caret, completion: hasCompletionTrigger(text, caret),
+        });
+    };
+    const lineCache = new Map();
+    let animationTimer;
+    const cellLines = (cell, width, toolMode, now) => {
+        const key = `${THEME_GENERATION}:${accessible}:${width}:${toolMode}:${cell.key}:${cell.kind}:${cell.pending === true}:${cell.collapsed === true}:${cell.startedAt ?? ''}:${cell.elapsedMs ?? ''}:${cell.text}:${cell.detail ?? ''}:${JSON.stringify(cell.tool)}`;
+        const cached = cell.pending === true ? undefined : lineCache.get(key);
+        if (cached !== undefined)
+            return cached;
+        const rendered = wrapTextWithAnsi(cellText(cell, toolMode, accessible, now), Math.max(1, width - 2)).map(value => `  ${value}`);
+        if (cell.pending !== true) {
+            lineCache.set(key, rendered);
+            if (lineCache.size > 512)
+                lineCache.delete(lineCache.keys().next().value);
+        }
+        return rendered;
+    };
+    const optionLine = (label, number, cursor, selected) => `${cursor ? BOLD_CYAN : DIM}${cursor ? accessible ? '>' : '›' : ' '} ${String(number)} ${selected ? '[x]' : '[ ]'} ${plain(label)}${RESET}`;
+    const announcement = (title, count, selected, cursor = 0) => {
+        if (!accessible)
+            return title;
+        const items = `${String(count)} item${count === 1 ? '' : 's'}`;
+        return selected === undefined ? `${title} · ${items}`
+            : `${title} · ${items} · selected ${String(cursor + 1)}: ${selected}`;
+    };
+    const decisionPanel = (decision, width, rows) => {
+        if (decision.kind === 'approval') {
+            const choices = ['Allow once', 'Reject', 'Cancel'];
+            const heading = announcement(`Approval · ${plain(decision.toolName)}`, choices.length, choices[decision.cursor], decision.cursor);
+            const prompt = wrapTextWithAnsi(`${BOLD_CYAN}${heading}${RESET}\n${plain(decision.prompt, true)}`, width);
+            return [...prompt, ...choices.map((choice, index) => optionLine(choice, index + 1, decision.cursor === index, false))];
+        }
+        const question = decision.questions[decision.index];
+        if (question === undefined)
+            return [`${RED}Invalid empty question batch${RESET}`];
+        const planReview = question.intent?.kind === 'plan-review';
+        const heading = planReview ? 'Plan review' : question.header ?? `Question ${String(decision.index + 1)}/${String(decision.questions.length)}`;
+        const selected = question.options[decision.cursor]?.label ?? 'Other (type an answer)';
+        const announced = announcement(plain(heading), question.options.length + 1, selected, decision.cursor);
+        const prompt = wrapTextWithAnsi(`${BOLD_CYAN}${announced}${RESET}\n${plain(question.question, true)}`, width);
+        const choiceRows = question.options.map((option, index) => optionLine(option.description === undefined ? option.label : `${option.label} — ${option.description}`, index + 1, decision.cursor === index, decision.selected.includes(option.label)));
+        choiceRows.push(optionLine('Other (type an answer)', question.options.length + 1, decision.cursor === question.options.length, false));
+        const detailLimit = planReview ? Math.max(3, rows - prompt.length - choiceRows.length - 5) : 3;
+        const detail = question.detail === undefined ? [] : wrapTextWithAnsi(`${DIM}${plain(question.detail, true)}${RESET}`, width).slice(0, detailLimit);
+        const custom = decision.cursor === question.options.length ? editor.render(width) : [];
+        const rendered = [...prompt, ...detail, ...choiceRows, ...custom];
+        return rows < 12 ? rendered.slice(0, Math.max(2, rows - 4)) : rendered;
+    };
+    const historyPanel = (overlay, state, width, rows) => {
+        const selected = state.cells[overlay.cursor];
+        const radius = Math.max(1, Math.min(4, Math.floor((rows - 6) / 2)));
+        const start = Math.max(0, overlay.cursor - radius);
+        const end = Math.min(state.cells.length, overlay.cursor + radius + 1);
+        const selectedSummary = selected === undefined ? undefined
+            : `${selected.kind} · ${plain(selected.tool?.title ?? selected.text).split('\n')[0] ?? ''}`;
+        const result = [`${BOLD_CYAN}${announcement('History', state.cells.length, selectedSummary, overlay.cursor)}${RESET}`];
+        for (let index = start; index < end; index++) {
+            const cell = state.cells[index];
+            if (cell === undefined)
+                continue;
+            const summary = plain(cell.tool?.title ?? cell.text).split('\n')[0] ?? '';
+            result.push(line(`${index === overlay.cursor ? accessible ? '>' : '›' : ' '} ${cell.kind} · ${summary}`, width));
+        }
+        if (overlay.expanded && selected !== undefined) {
+            result.push('', ...wrapTextWithAnsi(cellText(selected, 'expanded', accessible), width).slice(0, Math.max(2, rows - result.length - 4)));
+        }
+        result.push(`${DIM}↑↓ select · Enter expand · / search · y copy · Esc close${RESET}`);
+        return result;
+    };
+    const detailsPanel = (overlay, state, width, rows) => {
+        const items = activities(state);
+        const cursor = Math.min(overlay.cursor, Math.max(0, items.length - 1));
+        const radius = Math.max(1, Math.floor((rows - 7) / 2));
+        const start = Math.max(0, cursor - radius);
+        const end = Math.min(items.length, cursor + radius + 1);
+        const now = Date.now();
+        const selectedItem = items[cursor];
+        const result = [`${BOLD_CYAN}${announcement('Activity', items.length, selectedItem === undefined ? undefined : activityText(selectedItem, now), cursor)}${RESET}`];
+        for (let index = start; index < end; index++) {
+            const item = items[index];
+            if (item !== undefined)
+                result.push(line(`${index === cursor ? accessible ? '>' : '›' : ' '} ${activityText(item, now)}`, width));
+        }
+        const selected = items[cursor];
+        if (overlay.expanded && selected !== undefined) {
+            const detail = selected.kind === 'job'
+                ? [selected.value.id, `kind: ${selected.value.kind}`, `state: ${selected.value.status}`,
+                    ...(selected.value.detail === undefined ? [] : [selected.value.detail])]
+                : [selected.value.id, `mode: ${selected.value.mode}`, `state: ${selected.value.state}`,
+                    ...(selected.value.tokens === undefined ? [] : [`tokens: ${String(selected.value.tokens)}`]),
+                    ...(selected.value.summary === undefined ? [] : [selected.value.summary])];
+            result.push('', ...detail.flatMap(value => wrapTextWithAnsi(`${DIM}${plain(value)}${RESET}`, width)));
+        }
+        result.push(`${DIM}↑↓ select · Enter details · Esc close${RESET}`);
+        return result.slice(0, Math.max(2, rows - 3));
+    };
+    const overlayPanel = (overlay, state, width, rows) => {
+        if (overlay.kind === 'history')
+            return historyPanel(overlay, state, width, rows);
+        if (overlay.kind === 'details')
+            return detailsPanel(overlay, state, width, rows);
+        if (overlay.kind === 'info') {
+            return [
+                `${BOLD_CYAN}${announcement(plain(overlay.title), overlay.lines.length)}${RESET}`,
+                ...overlay.lines.flatMap(value => wrapTextWithAnsi(plain(value, true), width)),
+                `${DIM}Enter or Esc to close${RESET}`,
+            ].slice(0, Math.max(2, rows - 3));
+        }
+        if (overlay.kind === 'confirm') {
+            const choices = [overlay.acceptLabel, 'Cancel'];
+            return [
+                `${YELLOW}${announcement(plain(overlay.title), choices.length, choices[overlay.cursor], overlay.cursor)}${RESET}`,
+                ...overlay.detail.flatMap(value => wrapTextWithAnsi(plain(value, true), width)),
+                optionLine(overlay.acceptLabel, 1, overlay.cursor === 0, false),
+                optionLine('Cancel', 2, overlay.cursor === 1, false),
+            ].slice(0, Math.max(2, rows - 3));
+        }
+        const selected = overlay.options[overlay.cursor];
+        const result = [
+            line(`${BOLD_CYAN}${announcement(plain(overlay.title), overlay.options.length, selected === undefined ? undefined : plain(selected.label), overlay.cursor)}${RESET}`, width),
+            ...(overlay.notice === undefined ? [] : [`${DIM}${plain(overlay.notice)}${RESET}`]),
+        ];
+        let group;
+        for (const [index, option] of overlay.options.entries()) {
+            if (option.group !== undefined && option.group !== group) {
+                group = option.group;
+                result.push(`${DIM}${plain(group)}${RESET}`);
+            }
+            const detail = option.detail === undefined ? '' : ` — ${plain(option.detail)}`;
+            const active = option.active === true ? accessible ? ' [active]' : ' ●' : '';
+            const danger = option.danger === true ? ` ${YELLOW}${accessible ? '[danger]' : '!'}${RESET}` : '';
+            result.push(line(`${index === overlay.cursor ? BOLD_CYAN : DIM}${index === overlay.cursor ? accessible ? '>' : '›' : ' '} ${String(index + 1)} ${plain(option.label)}${active}${detail}${RESET}${danger}`, width));
+        }
+        return result.slice(0, Math.max(2, rows - (overlay.purpose === 'completion' ? 6 : 3)));
+    };
+    const document = {
+        invalidate() { editor.invalidate(); },
+        render(width) {
+            const state = options.readState();
+            const now = Date.now();
+            const pendingCommand = latestPendingCommand(state.cells);
+            if (pendingCommand !== undefined && animationTimer === undefined) {
+                animationTimer = setTimeout(() => {
+                    animationTimer = undefined;
+                    tui.requestRender();
+                }, accessible ? 1_000 : SPINNER_INTERVAL_MS);
+            }
+            else if (pendingCommand === undefined && animationTimer !== undefined) {
+                clearTimeout(animationTimer);
+                animationTimer = undefined;
+            }
+            const rows = Math.max(1, terminal.rows);
+            if (width < 32 || rows < 8)
+                return [line('dashi — enlarge terminal to continue', width)];
+            const root = state.root;
+            const cwd = plain(root?.cwd ?? state.cwd);
+            const title = root === undefined
+                ? `${BOLD_CYAN}dashi${RESET}  ${DIM}no session${RESET}`
+                : `${BOLD_CYAN}dashi${RESET}  ${plain(root.title ?? root.id)}`;
+            const identity = root === undefined ? cwd : `${plain(root.id)}  ${DIM}${cwd}${RESET}`;
+            const header = width >= 100
+                ? [line(`${title}  ${DIM}${identity}${RESET}`, width)]
+                : [line(title, width), line(`${DIM}${identity}${RESET}`, width)];
+            const baseStatusText = state.exitArmed
+                ? `${DIM}Ctrl+C or Ctrl+D again to exit${RESET}`
+                : state.decisions.length > 0
+                    ? `${DIM}decision 1/${String(state.decisions.length)} · ↑↓/1-9 choose · Enter answer · Esc cancel${RESET}`
+                    : state.search !== undefined
+                        ? `${DIM}${state.search.scope} search · Enter next · Shift+Enter previous · Esc close${RESET}`
+                        : state.overlay !== undefined
+                            ? `${DIM}${plain(state.overlay.kind === 'list' ? state.overlay.purpose : state.overlay.kind === 'history'
+                                ? 'history' : state.overlay.kind === 'details' ? 'activity' : state.overlay.title)} · ↑↓ choose · Enter select · Esc close${RESET}`
+                            : pendingCommand !== undefined
+                                ? `${DIM}running ${plain(pendingCommand.text).split(/\s/u)[0] ?? 'command'}${pendingCommand.startedAt === undefined ? '' : ` · ${duration(now - pendingCommand.startedAt)}`}${RESET}`
+                                : root === undefined
+                                    ? `${DIM}no session · cards ${state.toolMode} · Ctrl+J newline · Ctrl+L redraw${RESET}`
+                                    : root.status === 'running'
+                                        ? `${DIM}running · ${plain(root.model)} · Enter ${state.sendMode === 'steer' ? 'steer' : 'queue next turn'} · Ctrl+T toggle · cards ${state.toolMode} · Esc interrupt${RESET}`
+                                        : `${DIM}idle · ${plain(root.model)} · Enter send · cards ${state.toolMode}${RESET}`;
+            const activityCount = activities(state).length;
+            const baseStatus = `${baseStatusText}${root?.contextPercent === undefined ? '' : ` · ${String(root.contextPercent)}% context`}${activityCount === 0 ? '' : ' · Ctrl+B activity'}`;
+            const status = state.newOutput === 0 ? baseStatus
+                : `${YELLOW}${accessible ? '[new]' : '↓'} ${String(state.newOutput)} new output${state.newOutput === 1 ? '' : 's'} · Ctrl+End${RESET} · ${baseStatus}`;
+            const decision = state.decisions[0];
+            const attachmentRows = state.attachments.map((attachment, index) => line(`${YELLOW}[image ${String(index + 1)}]${RESET} ${plain(attachment.name)} · ${attachment.mediaType} · ${String(attachment.bytes)} B · ${plain(attachment.path)}`, width));
+            const activityRows = decision !== undefined || state.search !== undefined || state.overlay !== undefined
+                ? [] : activities(state).map(item => line(`${DIM}${activityText(item, now)}${RESET}`, width));
+            const control = decision !== undefined
+                ? decisionPanel(decision, width, rows)
+                : state.search !== undefined
+                    ? [
+                        ...(state.search.scope === 'history' && state.overlay?.kind === 'history'
+                            ? historyPanel(state.overlay, state, width, rows).slice(0, Math.max(2, rows - 8)) : []),
+                        `${BOLD_CYAN}${announcement(`Search ${state.search.scope}`, state.search.matches.length, state.search.matches.length === 0 ? undefined : `match ${String(state.search.cursor + 1)}`, state.search.cursor)}${RESET}`,
+                        ...editor.render(width),
+                        `${DIM}${state.search.matches.length === 0 ? 'no matches' : `${String(state.search.cursor + 1)}/${String(state.search.matches.length)}`} · Enter next · Shift+Enter previous${RESET}`,
+                    ]
+                    : state.overlay === undefined
+                        ? [...activityRows, ...attachmentRows, ...editor.render(width)]
+                        : [
+                            ...overlayPanel(state.overlay, state, width, rows),
+                            ...(state.overlay.kind === 'list' && state.overlay.purpose === 'completion'
+                                ? [...attachmentRows, ...editor.render(width)]
+                                : []),
+                        ];
+            const fixedRows = header.length + control.length + 2;
+            const filtered = state.cells
+                .filter(cell => !(state.toolMode === 'hidden' && (cell.tool !== undefined || cell.kind === 'tool')));
+            const available = Math.max(0, rows - fixedRows);
+            const end = Math.max(0, filtered.length - Math.min(state.scrollOffset, Math.max(0, filtered.length - 1)));
+            const start = Math.max(0, end - available - OVERSCAN_CELLS);
+            const materialized = options.inline ? filtered : filtered.slice(start, end);
+            materializedCount = materialized.length;
+            const transcript = materialized.flatMap(cell => [...cellLines(cell, width, state.toolMode, now), '']);
+            const visible = options.inline ? transcript : transcript.slice(-available);
+            const spacerRows = options.inline ? 0 : Math.max(0, available - visible.length);
+            return [...header, '', ...Array.from({ length: spacerRows }, () => ''), ...visible, ...control, line(status, width)];
+        },
+    };
+    let materializedCount = 0;
+    tui.addChild(document);
+    tui.setFocus(editor);
+    installInput(tui, {
+        ...options,
+        insertNewline: () => { editor.insertTextAtCursor('\n'); },
+        readComposerCursor: () => editor.getCursor(),
+    });
+    return {
+        bell: () => { terminal.write('\u0007'); },
+        copy(text) {
+            if (!osc52)
+                return 'unsupported';
+            const safe = plain(text, true);
+            if (Buffer.byteLength(safe, 'utf8') > COPY_LIMIT)
+                return 'too-large';
+            terminal.write(`\u001B]52;c;${Buffer.from(safe).toString('base64')}\u0007`);
+            return 'ok';
+        },
+        drainInput: () => terminal.drainInput(),
+        materializedCells: () => materializedCount,
+        render: force => { tui.renderNow(force); },
+        setComposer: (text, cursor) => { setEditor(editor, text, cursor); },
+        start: () => { tui.start(); },
+        stop: preserveScreen => {
+            if (animationTimer !== undefined)
+                clearTimeout(animationTimer);
+            animationTimer = undefined;
+            tui.stop({ preserveScreen });
+        },
+    };
+}

package/lib/rewind.d.ts

@@ -0,0 +1,18 @@
+import type { SessionEvent } from '@deepseek-ai/dsh-session';
+import type { Overlay, OverlayValue } from './state.js';
+export interface RewindBoundary {
+    readonly atSeq?: number;
+    readonly label: string;
+    readonly prompt: string;
+}
+/** Return the text of a direct human message, excluding injected context. */
+export declare function humanPrompt(event: SessionEvent): string | undefined;
+export declare function humanPrompts(events: readonly SessionEvent[]): readonly string[];
+/** Derive each human prompt and its controller-valid containing-turn cut. */
+export declare function rewindBoundaries(events: readonly SessionEvent[]): readonly RewindBoundary[];
+export declare function rewindOverlay(events: readonly SessionEvent[], roller: boolean): Overlay;
+export declare function rewindActionOverlay(boundary: Extract<OverlayValue, {
+    kind: 'rewind-boundary';
+}>): Overlay;
+/** Read a fork's durable source boundary without storing lineage separately. */
+export declare function inheritedTurn(events: readonly SessionEvent[], inheritedCount: number): number | undefined;

package/lib/rewind.js

@@ -0,0 +1,84 @@
+/** Return the text of a direct human message, excluding injected context. */
+export function humanPrompt(event) {
+    if (event.type !== 'user/message' || event.data.source.kind !== 'user')
+        return undefined;
+    const text = event.data.content
+        .filter(block => block.type === 'text')
+        .map(block => block.text).join('');
+    return text === '' ? undefined : text;
+}
+export function humanPrompts(events) {
+    return events.flatMap(event => humanPrompt(event) ?? []);
+}
+/** Derive each human prompt and its controller-valid containing-turn cut. */
+export function rewindBoundaries(events) {
+    const boundaries = [];
+    let previousEnd;
+    let openTurn;
+    let prompted = false;
+    for (const event of events) {
+        if (event.type === 'turn/start') {
+            openTurn = event.data.turn;
+            prompted = false;
+        }
+        else if (event.type === 'user/message' && openTurn !== undefined) {
+            const prompt = humanPrompt(event);
+            if (prompt !== undefined) {
+                boundaries.push({
+                    ...(previousEnd === undefined ? {} : { atSeq: previousEnd.seq }),
+                    label: `${prompt.replaceAll(/\s+/gu, ' ')}${prompted ? ' · mid-turn' : ''}`,
+                    prompt,
+                });
+                prompted = true;
+            }
+        }
+        else if (event.type === 'turn/end') {
+            previousEnd = event;
+            openTurn = undefined;
+            prompted = false;
+        }
+    }
+    return boundaries;
+}
+export function rewindOverlay(events, roller) {
+    const boundaries = rewindBoundaries(events);
+    return {
+        cursor: Math.max(0, boundaries.length - 1),
+        kind: 'list',
+        options: boundaries.map(boundary => ({
+            label: boundary.label,
+            value: {
+                kind: 'rewind-boundary', prompt: boundary.prompt, roller,
+                ...(boundary.atSeq === undefined ? {} : { atSeq: boundary.atSeq }),
+            },
+        })),
+        purpose: 'rewind',
+        title: 'Rewind to a prompt',
+    };
+}
+export function rewindActionOverlay(boundary) {
+    const base = {
+        prompt: boundary.prompt,
+        ...(boundary.atSeq === undefined ? {} : { atSeq: boundary.atSeq }),
+    };
+    const options = [
+        ...(boundary.roller ? [{
+                label: 'Restore code and conversation', value: { ...base, kind: 'rewind', mode: 'both' },
+            }] : []),
+        { label: 'Restore conversation', value: { ...base, kind: 'rewind', mode: 'conversation' } },
+        ...(boundary.roller ? [{
+                label: 'Restore code', value: { ...base, kind: 'rewind', mode: 'code' },
+            }] : []),
+        { label: 'Never mind', value: { kind: 'open-rewind' } },
+    ];
+    return { cursor: 0, kind: 'list', options, purpose: 'rewind-action', title: boundary.prompt };
+}
+/** Read a fork's durable source boundary without storing lineage separately. */
+export function inheritedTurn(events, inheritedCount) {
+    for (let index = Math.min(inheritedCount, events.length) - 1; index >= 0; index--) {
+        const event = events[index];
+        if (event?.type === 'turn/end')
+            return event.data.turn;
+    }
+    return undefined;
+}

package/lib/session-export.d.ts

@@ -0,0 +1,3 @@
+import type { TerminalCell } from './state.js';
+/** Format the existing terminal projection as a portable Markdown transcript. */
+export declare function markdownTranscript(sessionId: string, cwd: string, title: string | undefined, cells: readonly TerminalCell[]): string;

package/lib/session-export.js

@@ -0,0 +1,27 @@
+function heading(kind) {
+    return kind === 'user' ? 'User'
+        : kind === 'assistant' ? 'Assistant'
+            : kind === 'reasoning' ? 'Reasoning'
+                : kind[0]?.toUpperCase() + kind.slice(1);
+}
+function body(cell) {
+    const parts = [cell.text];
+    if (cell.detail !== undefined && cell.detail !== cell.text)
+        parts.push(cell.detail);
+    if (cell.tool?.body !== undefined)
+        parts.push(cell.tool.body);
+    for (const diff of cell.tool?.diffs ?? []) {
+        parts.push(`${diff.path} (+${String(diff.added)} -${String(diff.removed)})`, ...diff.lines);
+    }
+    return parts.filter(Boolean).join('\n\n');
+}
+/** Format the existing terminal projection as a portable Markdown transcript. */
+export function markdownTranscript(sessionId, cwd, title, cells) {
+    const sections = cells.filter(cell => cell.pending !== true).map(cell => `## ${heading(cell.kind)}\n\n${body(cell)}`);
+    return [
+        `# ${title ?? 'Untitled DSH session'}`,
+        `Session: \`${sessionId}\`  `,
+        `Working directory: \`${cwd}\``,
+        ...sections,
+    ].join('\n\n').trimEnd() + '\n';
+}

package/lib/session-list.d.ts

@@ -0,0 +1,15 @@
+import type { SessionSummary } from '@deepseek-ai/dsh-api-session-controller';
+export interface SessionListOptions {
+    readonly all: boolean;
+    readonly cwd?: string;
+    readonly json: boolean;
+}
+/** Parse only the profile-provided `sessions list` grammar. */
+export declare function parseSessionListArgs(args: readonly string[]): SessionListOptions | undefined;
+export declare function sessionTitle(item: SessionSummary): string | undefined;
+export declare function isSessionId(value: string): boolean;
+/** Resolve one native title exactly, then by case-insensitive substring. */
+export declare function sessionMatches(items: readonly SessionSummary[], value: string, cwd?: string): readonly SessionSummary[];
+export declare function sessionNotFound(value: string): Error;
+/** Format ordinary roots from DSH's native catalog without adding live-process facts. */
+export declare function formatSessionList(items: readonly SessionSummary[], cwd: string | undefined, json: boolean): string;

package/lib/session-list.js

@@ -0,0 +1,65 @@
+/** Parse only the profile-provided `sessions list` grammar. */
+export function parseSessionListArgs(args) {
+    if (args[0] !== 'sessions' || args[1] !== 'list')
+        return undefined;
+    let all = false;
+    let cwd;
+    let json = false;
+    for (let index = 2; index < args.length; index++) {
+        const argument = args[index];
+        if (argument === '--all' && !all && cwd === undefined)
+            all = true;
+        else if (argument === '--json' && !json)
+            json = true;
+        else if (argument === '--cwd' && cwd === undefined && !all) {
+            cwd = args[++index];
+            if (cwd === undefined || cwd === '')
+                return undefined;
+        }
+        else
+            return undefined;
+    }
+    return { all, json, ...(cwd === undefined ? {} : { cwd }) };
+}
+export function sessionTitle(item) {
+    const title = item.projections?.values.title;
+    return typeof title === 'string' && title !== '' ? title : undefined;
+}
+export function isSessionId(value) {
+    return /^session-[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$/iu.test(value);
+}
+/** Resolve one native title exactly, then by case-insensitive substring. */
+export function sessionMatches(items, value, cwd) {
+    const scoped = items.filter(item => item.origin === undefined && (cwd === undefined || item.cwd === cwd));
+    const exact = scoped.filter(item => sessionTitle(item) === value);
+    return exact.length > 0 ? exact : scoped.filter(item => sessionTitle(item)?.toLocaleLowerCase().includes(value.toLocaleLowerCase()));
+}
+export function sessionNotFound(value) {
+    return new Error(`no session named ${JSON.stringify(value)}`);
+}
+function terminalJson(value, space) {
+    return JSON.stringify(value, undefined, space).replace(/[\u0080-\u009f]/gu, character => `\\u${(character.codePointAt(0) ?? 0).toString(16).padStart(4, '0')}`);
+}
+function terminalField(value) {
+    return terminalJson(value).slice(1, -1);
+}
+/** Format ordinary roots from DSH's native catalog without adding live-process facts. */
+export function formatSessionList(items, cwd, json) {
+    const sessions = items
+        .filter(item => item.origin === undefined && (cwd === undefined || item.cwd === cwd))
+        .map(item => ({
+        sessionId: String(item.sessionId),
+        title: sessionTitle(item) ?? null,
+        ...(item.cwd === undefined ? {} : { cwd: item.cwd }),
+        updatedAt: new Date(item.updatedAt).toISOString(),
+    }));
+    if (json)
+        return terminalJson({ version: 1, sessions }, 2);
+    const records = sessions.map(item => [
+        terminalField(item.sessionId), terminalField(item.title ?? 'Untitled'),
+        terminalField(item.cwd ?? 'cwd unavailable'), item.updatedAt,
+    ]);
+    const headers = ['UUID', 'TITLE', 'CWD', 'UPDATED'];
+    const widths = headers.map((header, index) => Math.max(header.length, ...records.map(row => row[index]?.length ?? 0)));
+    return [headers, ...records].map(row => row.map((value, index) => index === row.length - 1 ? value : value.padEnd(widths[index] ?? 0)).join('  ')).join('\n');
+}