feat(story-mode): draw a Claude session's turns as comic pages, live

Story Mode is an opt-in header button (showStoryButton, per device, default
off, kept off phones) that opens the active Claude Code session as comic pages:
one page per prompt, panels for reading code, planning, helpers, edits, tests
(POW/KRAK), questions and saving, each with a plain story caption and a
Director's cut caption naming the tools. Files open in the existing file
preview, the code page opens the exact diff, a test board opens the output,
and a running turn redraws as Claude works.

Server: GET /api/sessions/:id/story (experimental) reads a bounded tail of the
session's own transcript. A pure core (src/story-mode.ts) reduces lines,
joins tool calls with their results, splits turns at prompts and
turn_duration, and groups events into at most 12 panels; Bash calls are
sorted by what the command does. The reader (src/story-reader.ts) caches
reduced entries and reads only appended bytes while the file grows.

Frontend: story-mode.js (canvas frame engine, live refresh from transcript and
hook SSE events plus a poll while a turn runs, details drawer, the wire) and
story-mode.css, with two self-hosted OFL comic fonts.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
This commit is contained in:
Codeman maintainer committed 2026-10-18 09:22:06 +02:00
1 parent 0ab71d61d1
commit 2653db10b5
27 files changed
+5746 -6

No files matched your search

+157
View File
@@ -0,0 +1,157 @@
/**
* @fileoverview GET /api/sessions/:id/story (Story Mode) against invented transcripts in a temp dir,
* plus the reader's incremental tail read. Port: N/A (app.inject()).
*/
import { appendFileSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { afterEach, beforeEach, describe, expect, it } from 'vitest';
import { createRouteTestHarness } from './_route-test-utils.js';
import { registerStoryRoutes } from '../../src/web/routes/story-routes.js';
import { clearStoryReaderCache, readStoryEntries } from '../../src/story-reader.js';
import { bash, demoTurn, end, prompt, read, resetClock, said } from '../story-fixtures.js';
const URL = '/api/sessions/test-session-1/story';
const jsonl = (lines: unknown[]) => lines.map((l) => JSON.stringify(l)).join('\n') + '\n';
let dir: string;
let transcript: string;
async function setup(opts: { hookPath?: string | null; mode?: string; remote?: unknown; docker?: unknown } = {}) {
const h = await createRouteTestHarness((app, ctx) => registerStoryRoutes(app, ctx));
const session = h.ctx._session as unknown as Record<string, unknown>;
if (opts.mode) session.mode = opts.mode;
if (opts.remote) session.remote = opts.remote;
if (opts.docker) session.docker = opts.docker;
h.ctx.getTranscriptPath.mockReturnValue(opts.hookPath === undefined ? transcript : opts.hookPath);
return h;
}
beforeEach(() => {
resetClock();
clearStoryReaderCache();
dir = mkdtempSync(join(tmpdir(), 'story-route-'));
transcript = join(dir, 'conversation.jsonl');
});
afterEach(() => {
rmSync(dir, { recursive: true, force: true });
});
describe('GET /api/sessions/:id/story', () => {
it('draws the newest turn of the hook-reported transcript', async () => {
writeFileSync(transcript, jsonl([prompt('first job'), said('Done.'), end(2000), ...demoTurn()]));
const { app } = await setup();
const res = await app.inject({ method: 'GET', url: URL });
expect(res.statusCode).toBe(200);
const body = res.json();
expect(body.success).toBe(true);
expect(body.data.supported).toBe(true);
expect(body.data.turns.map((t: { prompt: string }) => t.prompt)).toEqual([
'first job',
'The checkout button does nothing on phones. Can you fix it?',
]);
expect(body.data.page.panels.map((p: { kind: string }) => p.kind)).toEqual([
'mission',
'investigate',
'plan',
'backup',
'loop',
'save',
'complete',
]);
// Nothing a Read or an Edit result carried in full ever leaves the server.
expect(res.body).not.toContain('FILE CONTENT');
expect(res.body).not.toContain('WHOLE ORIGINAL FILE');
});
it('draws an older turn by id and answers page null for an unknown one', async () => {
writeFileSync(transcript, jsonl([prompt('first job'), said('Done.'), end(2000), ...demoTurn()]));
const { app } = await setup();
const list = (await app.inject({ method: 'GET', url: URL })).json().data.turns;
const older = await app.inject({ method: 'GET', url: `${URL}?turn=${encodeURIComponent(list[0].id)}` });
expect(older.json().data.page).toMatchObject({ prompt: 'first job', complete: true });
const gone = await app.inject({ method: 'GET', url: `${URL}?turn=nope` });
expect(gone.json().data.page).toBeNull();
});
it('is supported with no turns when there is no transcript yet', async () => {
const { app } = await setup({ hookPath: null });
const res = await app.inject({ method: 'GET', url: URL });
expect(res.json()).toEqual({ success: true, data: { supported: true, turns: [], page: null } });
});
it('answers unsupported for a CLI that writes no Claude transcript', async () => {
const { app } = await setup({ mode: 'codex' });
const data = (await app.inject({ method: 'GET', url: URL })).json().data;
expect(data.supported).toBe(false);
expect(data.reason).toMatch(/different CLI/);
});
it('answers unsupported for remote and Docker sessions, whose transcript is not on this host', async () => {
for (const where of [{ remote: { hostId: 'h1' } }, { docker: { containerName: 'c1' } }]) {
clearStoryReaderCache();
const { app } = await setup(where);
const data = (await app.inject({ method: 'GET', url: URL })).json().data;
expect(data).toMatchObject({ supported: false });
}
});
it('never reads a hook path that is not a transcript', async () => {
writeFileSync(join(dir, 'secret.txt'), jsonl(demoTurn()));
const { app } = await setup({ hookPath: join(dir, 'secret.txt') });
const res = await app.inject({ method: 'GET', url: URL });
expect(res.json().data).toEqual({ supported: true, turns: [], page: null });
});
it('fails with OPERATION_FAILED when the transcript cannot be read', async () => {
const { app } = await setup({ hookPath: join(dir, 'missing.jsonl') });
const res = await app.inject({ method: 'GET', url: URL });
expect(res.statusCode).toBe(500);
expect(res.json()).toMatchObject({ success: false, errorCode: 'OPERATION_FAILED' });
});
it('404s an unknown session', async () => {
const { app } = await setup();
const res = await app.inject({ method: 'GET', url: '/api/sessions/nope/story' });
expect(res.statusCode).toBe(404);
});
it('a live turn grows as the transcript grows', async () => {
writeFileSync(transcript, jsonl([prompt('go'), ...read('r1', '/w/a.ts')]));
const { app } = await setup();
const before = (await app.inject({ method: 'GET', url: URL })).json().data.page;
expect(before.panels.map((p: { kind: string }) => p.kind)).toEqual(['mission', 'investigate']);
expect(before.panels[1].live).toBe(true);
appendFileSync(transcript, jsonl([...bash('b1', 'npm test', 'Run tests', ' Tests 4 passed (4)'), end(9000)]));
const after = (await app.inject({ method: 'GET', url: URL })).json().data.page;
expect(after.panels.map((p: { kind: string }) => p.kind)).toEqual(['mission', 'investigate', 'check', 'complete']);
expect(after.complete).toBe(true);
});
});
describe('readStoryEntries', () => {
it('leaves a line that is still being written for the next read', async () => {
const full = JSON.stringify(prompt('half written'));
writeFileSync(transcript, jsonl([prompt('one')]) + full.slice(0, 20));
const first = await readStoryEntries(transcript);
expect(first.entries.map((e) => e.k)).toEqual(['prompt']);
appendFileSync(transcript, full.slice(20) + '\n');
const second = await readStoryEntries(transcript);
expect(second.entries.filter((e) => e.k === 'prompt')).toHaveLength(2);
});
it('starts over when the file was replaced by a shorter one', async () => {
writeFileSync(transcript, jsonl([prompt('one'), prompt('two'), prompt('three')]));
await readStoryEntries(transcript);
writeFileSync(transcript, jsonl([prompt('new')]));
const again = await readStoryEntries(transcript);
expect(again.entries.map((e) => (e.k === 'prompt' ? e.text : e.k))).toEqual(['new']);
});
it('shares one read between concurrent callers', async () => {
writeFileSync(transcript, jsonl(demoTurn()));
const [a, b] = await Promise.all([readStoryEntries(transcript), readStoryEntries(transcript)]);
expect(a.entries).toBe(b.entries);
});
});