reelson 0.7.0

package/skills/reelson-compose/scripts/studio.ts

@@ -0,0 +1,394 @@
+/**
+ * `reelson studio <slug>`: a local preview and editor for a demo. The built
+ * composition plays in the HyperFrames player above a timeline drawn from the
+ * same plan the build uses (sections, callouts, zooms, hand-offs, clicks,
+ * markers, audio). video.json, markers.json, the recording and every
+ * template/section folder are watched: a change rebuilds and the page reloads
+ * in place, at the same time.
+ *
+ * Edits made on the page come back as a whole video.json (PUT /api/video): it
+ * is validated and planned before it is written, and refused if video.json
+ * changed on disk since the page loaded it.
+ *
+ *   reelson studio <slug|dir> [--port 4800] [--no-open]
+ */
+import { createHash } from 'node:crypto'
+import { existsSync, readFileSync, statSync, watch, writeFileSync, type FSWatcher } from 'node:fs'
+import { createServer, type IncomingMessage, type ServerResponse } from 'node:http'
+import { basename, extname, resolve, sep } from 'node:path'
+import { fromRoot, type LoadedConfig } from '../../reelson-record/scripts/config.ts'
+import { build, planSpec, serializeVideoSpec, type Plan } from './build.ts'
+import { hyperframesDist } from './hyperframes.ts'
+import { BUILTIN_SECTIONS, BUILTIN_TEMPLATES, catalog, readMarkers, ReelsonError, validateVideoSpec } from './project.ts'
+import { defaultCallouts, round, SLOTS, type VideoSpec } from './timeline.ts'
+import { checkZoom, zoomOverlaps } from './zooms.ts'
+
+const STUDIO_DIR = resolve(import.meta.dirname, '../studio')
+
+/** What the studio page draws: the plan, flattened to plain JSON in composition seconds. */
+export interface StudioData {
+    slug: string
+    title: string
+    total: number
+    frame: { width: number; height: number }
+    template: string
+    /** video.json as on disk (without `$schema`): what the page edits. */
+    spec: VideoSpec
+    /** The trim window and the recording's length, in recording seconds. */
+    media: { start: number; end: number; duration: number }
+    /** What a trim edge can be tied to, in recording seconds (click: when its glide starts). */
+    anchors: { markers: { label: string; at: number }[]; clicks: { n: number; at: number }[] }
+    /** Composition ↔ recording time: one entry per stretch of footage between hand-offs. */
+    segments: { start: number; duration: number; mediaStart: number }[]
+    sections: { slot: 'intro' | 'recording' | 'recap' | 'outro'; name: string; start: number; end: number; detail: string }[]
+    /** `source`: index in `spec.callouts` (or in the default callouts when it has none). */
+    callouts: { n: number; source: number; at: number; end: number; text: string; group?: string }[]
+    zooms: { n: number; at: number; end: number; in: number; out: number; scale: number; x: number; y: number; problems: string[] }[]
+    handOffs: { at: number; end: number; belt: number; title: string; subtitle?: string; from?: string; to?: string }[]
+    clicks: { n: number; kind: 'click' | 'type'; glide: number; at: number; until: number }[]
+    markers: { label: string; at: number; recordingAt: number; used: boolean }[]
+    audio: { narration: { start: number; end: number } | null; music: { start: number; end: number } | null }
+    /**
+     * 'layer': drawn by the video (size, ripple and `presses` apply); 'hidden': logged but
+     * turned off in video.json; 'filmed': part of the footage, nothing to set.
+     */
+    cursor: { state: 'layer' | 'hidden' | 'filmed'; size: number; ripple: boolean; presses: number[] }
+    warnings: string[]
+}
+
+export function studioData(slug: string, result: Plan, audio: { narration: boolean; music: boolean }): StudioData {
+    const { spec, markers, design, timeline: t, clicks, zooms, warnings } = result
+    const { intro, recap, outro } = design.sections
+    const sections: StudioData['sections'] = [
+        { slot: 'intro', name: intro.name, start: 0, end: t.intro.duration, detail: `hands over at ${t.intro.exit}s` },
+        {
+            slot: 'recording',
+            name: 'recording',
+            start: t.clipStart,
+            end: t.clipEnd,
+            detail: `media ${t.mediaStart}–${t.mediaEnd}s of ${markers.durationSeconds}s`,
+        },
+    ]
+    if (recap && t.recap) {
+        sections.push({
+            slot: 'recap',
+            name: recap.name,
+            start: t.recap.start,
+            end: round(t.recap.start + t.recap.duration),
+            detail: `holds ${t.recap.maxSteps} steps`,
+        })
+    }
+    sections.push({ slot: 'outro', name: outro.name, start: t.outro.start, end: t.total, detail: '' })
+
+    // Without callouts in video.json the build makes one per marker, so all of them are used.
+    const overlaps = zoomOverlaps(zooms)
+    const used = new Set((spec.callouts ?? defaultCallouts(markers)).map((c) => c.marker).filter(Boolean))
+
+    return {
+        slug,
+        title: spec.title,
+        total: t.total,
+        frame: t.frame,
+        template: design.template.name,
+        // The page edits callouts by index, so the default ones are spelled out.
+        spec: { ...withoutSchema(spec), callouts: spec.callouts ?? defaultCallouts(markers) },
+        media: { start: t.mediaStart, end: t.mediaEnd, duration: markers.durationSeconds },
+        anchors: {
+            markers: markers.markers.map((m) => ({ label: m.label, at: m.at })),
+            clicks: (markers.clicks ?? []).map((c, i) => ({ n: i + 1, at: c.move ?? c.at })),
+        },
+        segments: t.segments,
+        sections,
+        callouts: t.callouts.map((c, i) => ({
+            n: i + 1,
+            source: c.source,
+            at: c.at,
+            end: round(c.at + c.duration),
+            text: c.text,
+            ...(c.group ? { group: c.group } : {}),
+        })),
+        zooms: zooms.map((z, i) => ({
+            n: i + 1,
+            at: z.at,
+            end: round(z.at + z.duration),
+            in: z.in,
+            out: z.out,
+            scale: z.scale,
+            x: z.x,
+            y: z.y,
+            problems: [...checkZoom(z, clicks, t).problems, ...overlaps.filter((o) => o.index === i).map((o) => o.message)],
+        })),
+        handOffs: t.transitions.map((tr) => ({
+            at: tr.at,
+            end: round(tr.at + tr.gap),
+            belt: t.belt,
+            title: tr.card.title,
+            ...(tr.card.subtitle ? { subtitle: tr.card.subtitle } : {}),
+            ...(tr.card.from ? { from: tr.card.from } : {}),
+            ...(tr.card.to ? { to: tr.card.to } : {}),
+        })),
+        clicks: clicks.map((c) => ({ n: c.index, kind: c.kind, glide: c.glide, at: c.comp, until: c.until })),
+        markers: markers.markers
+            .filter((m) => m.at >= t.mediaStart && m.at <= t.mediaEnd)
+            .map((m) => ({ label: m.label, at: t.toComposition(m.at), recordingAt: m.at, used: used.has(m.label) })),
+        audio: {
+            narration: audio.narration ? { start: t.clipStart, end: t.clipEnd } : null,
+            music: audio.music ? { start: 0, end: t.total } : null,
+        },
+        cursor: t.cursor
+            ? { state: 'layer', size: t.cursor.size, ripple: t.cursor.ripple, presses: t.cursor.presses.map(([at]) => at) }
+            : {
+                  state: markers.cursor && !markers.cursor.drawn ? 'hidden' : 'filmed',
+                  size: spec.cursor ? (spec.cursor.size ?? 44) : 44,
+                  ripple: spec.cursor ? (spec.cursor.ripple ?? true) : true,
+                  presses: [],
+              },
+        warnings,
+    }
+}
+
+/** A short hash of video.json as it is on disk ('' when there is none). */
+export function specRevision(demoDir: string): string {
+    const path = resolve(demoDir, 'video.json')
+    return existsSync(path) ? createHash('sha1').update(readFileSync(path)).digest('hex').slice(0, 12) : ''
+}
+
+/**
+ * The page's edit (PUT /api/video): refused (409) if video.json changed since the page read
+ * it (`base` is the revision it read), refused (422) if it fails the schema or the plan —
+ * nothing is written then — else written as the build would write it. The caller rebuilds.
+ */
+export function applyEdit(
+    demoDir: string,
+    config: LoadedConfig,
+    body: { base?: string; spec?: unknown },
+): { status: number; body: { error?: string; warnings?: string[] }; written?: string } {
+    if (body.base !== specRevision(demoDir)) {
+        return { status: 409, body: { error: 'video.json changed on disk since the page loaded it — reloaded; redo the edit' } }
+    }
+    try {
+        const spec = validateVideoSpec(body.spec, 'the edit')
+        const { warnings } = planSpec(demoDir, spec, readMarkers(demoDir), config)
+        const written = serializeVideoSpec(spec, demoDir, config)
+        writeFileSync(resolve(demoDir, 'video.json'), written)
+        return { status: 200, body: { warnings }, written }
+    } catch (e) {
+        return { status: 422, body: { error: (e as Error).message } }
+    }
+}
+
+function withoutSchema(spec: VideoSpec): VideoSpec {
+    const { $schema: _schema, ...rest } = spec as VideoSpec & { $schema?: string }
+    return rest
+}
+
+export interface StudioOptions {
+    port?: number
+    log?: (line: string) => void
+}
+
+/** Builds the demo, then serves the studio until the process exits. Resolves with its URL. */
+export async function studio(demoDir: string, config: LoadedConfig, options: StudioOptions = {}): Promise<string> {
+    const log = options.log ?? console.log
+    const slug = basename(demoDir)
+    const videoDir = resolve(demoDir, 'video')
+    const dist = hyperframesDist()
+
+    let data: StudioData | null = null
+    let error: string | null = null
+    let version = 0
+    const clients = new Set<ServerResponse>()
+    const rebuild = (): void => {
+        try {
+            const result = build(demoDir, config, { log: () => {} })
+            const has = (file: string) => existsSync(resolve(videoDir, 'assets', file))
+            data = studioData(slug, result, { narration: has('narration.m4a'), music: has('music.m4a') })
+            error = null
+        } catch (e) {
+            // Keep serving the last good build; the page shows the error until the next save fixes it.
+            error = (e as Error).message
+        }
+        version++
+        for (const client of clients) {
+            client.write(`data: ${JSON.stringify({ version, error })}\n\n`)
+        }
+    }
+    rebuild()
+    if (!data) {
+        throw new ReelsonError(error ?? 'build failed')
+    }
+
+    const specPath = resolve(demoDir, 'video.json')
+    const revision = (): string => specRevision(demoDir)
+    // What the page can pick from: re-read per request, so a new section shows up without a restart.
+    const choices = () => {
+        const found = catalog(config)
+        return {
+            templates: found.templates.map((t) => t.name),
+            ...Object.fromEntries(SLOTS.map((slot) => [slot, found.sections[slot].map((s) => s.name)])),
+        }
+    }
+    /** The page's edit: checked like a build would, then written and built. */
+    let written: string | null = null
+    const edit = (body: { base?: string; spec?: unknown }): { status: number; body: object } => {
+        const result = applyEdit(demoDir, config, body)
+        if (result.written === undefined) {
+            return result
+        }
+        written = result.written
+        rebuild()
+        // Written either way; a failed build shows on the page like any other.
+        return { status: 200, body: { ...result.body, error, revision: revision() } }
+    }
+
+    const server = createServer((req, res) => {
+        const url = new URL(req.url ?? '/', 'http://localhost')
+        const path = decodeURIComponent(url.pathname)
+        if (path === '/') {
+            return sendFile(res, resolve(STUDIO_DIR, 'index.html'))
+        }
+        if (path.startsWith('/studio/')) {
+            const file = resolve(STUDIO_DIR, `.${path.slice('/studio'.length)}`)
+            if (file.startsWith(STUDIO_DIR + sep)) {
+                return sendFile(res, file)
+            }
+        }
+        if (path === '/api/plan') {
+            return send(res, 200, 'application/json', JSON.stringify({ version, error, revision: revision(), choices: choices(), data }))
+        }
+        if (path === '/api/video' && req.method === 'PUT') {
+            readBody(req).then(
+                (raw) => {
+                    let body
+                    try {
+                        body = JSON.parse(raw)
+                    } catch {
+                        return send(res, 400, 'application/json', JSON.stringify({ error: 'the edit is not JSON' }))
+                    }
+                    const result = edit(body)
+                    send(res, result.status, 'application/json', JSON.stringify(result.body))
+                },
+                () => send(res, 400, 'application/json', JSON.stringify({ error: 'unreadable request' })),
+            )
+            return
+        }
+        if (path === '/api/events') {
+            res.writeHead(200, { 'content-type': 'text/event-stream', 'cache-control': 'no-cache', connection: 'keep-alive' })
+            res.write(': connected\n\n')
+            clients.add(res)
+            req.on('close', () => clients.delete(res))
+            return
+        }
+        if (path === '/hf/player.js') {
+            return sendFile(res, resolve(dist, 'hyperframes-player.global.js'))
+        }
+        if (path === '/hf/runtime.js') {
+            return sendFile(res, resolve(dist, 'hyperframe.runtime.iife.js'))
+        }
+        if (path === '/video/index.html') {
+            // The runtime ships with the page instead of the player fetching it from a CDN.
+            const html = readFileSync(resolve(videoDir, 'index.html'), 'utf8').replace(
+                '</head>',
+                '    <script src="/hf/runtime.js"></script>\n  </head>',
+            )
+            return send(res, 200, 'text/html', html)
+        }
+        if (path.startsWith('/video/')) {
+            const file = resolve(videoDir, `.${path.slice('/video'.length)}`)
+            if (file.startsWith(videoDir + sep)) {
+                return sendFile(res, file, req.headers.range)
+            }
+        }
+        send(res, 404, 'text/plain', 'not found')
+    })
+
+    // Rebuild on any input the build reads; editors write in bursts, so settle first.
+    let timer: NodeJS.Timeout | undefined
+    const schedule = (): void => {
+        clearTimeout(timer)
+        timer = setTimeout(() => {
+            rebuild()
+            log(error ? `rebuild failed: ${error}` : `rebuilt (${new Date().toLocaleTimeString()})`)
+        }, 250)
+    }
+    const inputs = new Set(['video.json', 'markers.json', 'recording.mp4'])
+    // The page's own writes are already built; only a change from elsewhere rebuilds.
+    const ownWrite = (file: string): boolean =>
+        file === 'video.json' && written !== null && existsSync(specPath) && readFileSync(specPath, 'utf8') === written
+    const watchers: FSWatcher[] = [
+        watch(demoDir, (_event, file) => file && inputs.has(file.toString()) && !ownWrite(file.toString()) && schedule()),
+        ...[
+            BUILTIN_TEMPLATES,
+            BUILTIN_SECTIONS,
+            resolve(fromRoot(config, config.videosDir), '_templates'),
+            resolve(fromRoot(config, config.videosDir), '_sections'),
+        ]
+            .filter((dir) => existsSync(dir))
+            .map((dir) => watch(dir, { recursive: true }, schedule)),
+    ]
+    if (config.path) {
+        watchers.push(watch(config.path, schedule))
+    }
+    server.on('close', () => watchers.forEach((w) => w.close()))
+
+    const port = options.port ?? 4800
+    await new Promise<void>((done, fail) => {
+        server.once('error', (e: NodeJS.ErrnoException) =>
+            fail(e.code === 'EADDRINUSE' ? new ReelsonError(`port ${port} is in use — pass --port`) : e),
+        )
+        server.listen(port, '127.0.0.1', done)
+    })
+
+    return `http://localhost:${port}/`
+}
+
+function readBody(req: IncomingMessage): Promise<string> {
+    return new Promise((done, fail) => {
+        const chunks: Buffer[] = []
+        req.on('data', (chunk: Buffer) => chunks.push(chunk))
+        req.on('end', () => done(Buffer.concat(chunks).toString('utf8')))
+        req.on('error', fail)
+    })
+}
+
+const TYPES: Record<string, string> = {
+    '.html': 'text/html',
+    '.js': 'text/javascript',
+    '.css': 'text/css',
+    '.json': 'application/json',
+    '.svg': 'image/svg+xml',
+    '.png': 'image/png',
+    '.webp': 'image/webp',
+    '.woff2': 'font/woff2',
+    '.mp4': 'video/mp4',
+    '.m4a': 'audio/mp4',
+}
+
+function send(res: ServerResponse, status: number, type: string, body: string | Buffer): void {
+    res.writeHead(status, { 'content-type': type, 'cache-control': 'no-store' })
+    res.end(body)
+}
+
+/** A file, with byte ranges so the browser can seek video and audio. */
+function sendFile(res: ServerResponse, file: string, range?: string): void {
+    if (!existsSync(file) || !statSync(file).isFile()) {
+        return send(res, 404, 'text/plain', 'not found')
+    }
+    const type = TYPES[extname(file).toLowerCase()] ?? 'application/octet-stream'
+    const body = readFileSync(file)
+    const match = range?.match(/^bytes=(\d*)-(\d*)$/)
+    if (!match) {
+        res.writeHead(200, { 'content-type': type, 'content-length': body.length, 'accept-ranges': 'bytes', 'cache-control': 'no-store' })
+        return void res.end(body)
+    }
+    const start = match[1] ? Number(match[1]) : Math.max(0, body.length - Number(match[2]))
+    const end = match[1] && match[2] ? Math.min(Number(match[2]), body.length - 1) : body.length - 1
+    res.writeHead(206, {
+        'content-type': type,
+        'content-length': end - start + 1,
+        'content-range': `bytes ${start}-${end}/${body.length}`,
+        'accept-ranges': 'bytes',
+        'cache-control': 'no-store',
+    })
+    res.end(body.subarray(start, end + 1))
+}

package/skills/reelson-compose/scripts/timeline.js

@@ -0,0 +1,271 @@
+/**
+ * The composition timeline, computed from a recording's markers.json and the
+ * video's video.json. Pure: no files, no ffmpeg — so it is unit-tested.
+ *
+ *   intro (0 → exit) → recording (callouts, zooms, hand-off cards)
+ *   → recap (optional) → outro
+ *
+ * video.json times are recording times; everything this module returns is in
+ * composition seconds.
+ */
+/**
+ * Timeline constants (seconds). The stage keys come from the template's
+ * template.json, the rest from the section chosen for each slot (section.json).
+ */
+export const STAGE_TIMING = {
+    overlap: 0.4, // recording → recap → outro cross-fades
+    calloutDuration: 3.0,
+    /** A step's callout stays this long after its marker (the result), next step permitting. */
+    calloutHold: 1.2,
+    /** The least a step's callout is up before the next step's may replace it. */
+    calloutMinimum: 1.8,
+    transitionGap: 2.6, // seconds a hand-off card holds between the two belts
+    belt: 0.9, // the recording's exit before a hand-off card (matches the stage)
+    maxW: 1600, // the framed recording's box inside the 1920x1080 stage
+    maxH: 940,
+};
+/** A spoken callout stays up this long after its line ends (a breath before the next step). */
+const SPOKEN_TAIL = 0.3;
+export const SECTION_TIMING = {
+    intro: {
+        duration: 4.0, // intro clip length
+        exit: 3.0, // the intro hands over and the recording starts (= clipStart)
+    },
+    recap: {
+        base: 2.4, // + perStep per step, capped at max
+        perStep: 0.45,
+        max: 7.5,
+        maxSteps: 10, // the recap's capacity
+    },
+    outro: {
+        duration: 2.6,
+    },
+};
+export const SLOTS = Object.keys(SECTION_TIMING);
+export const TIMING_DEFAULTS = { stage: STAGE_TIMING, ...SECTION_TIMING };
+export class TimelineError extends Error {
+}
+export function computeTimeline(markers, spec, timing = TIMING_DEFAULTS, 
+/**
+ * Voice-over: seconds from a callout appearing until its spoken line is done (0: silent or
+ * not spoken yet). Such a callout stays up at least that long, and the next one waits.
+ */
+spoken = () => 0) {
+    const warnings = [];
+    const mediaStart = Math.max(0, resolveTrimPoint(spec.trim?.start, markers, 'start') ?? 0);
+    const mediaEnd = Math.min(resolveTrimPoint(spec.trim?.end, markers, 'end') ?? markers.durationSeconds, markers.durationSeconds);
+    const mediaDuration = round(mediaEnd - mediaStart);
+    if (mediaDuration <= 0) {
+        throw new TimelineError(`trim window is empty (start ${mediaStart}s, end ${mediaEnd}s)`);
+    }
+    const stage = timing.stage;
+    const clipStart = timing.intro.exit;
+    const handOffs = (markers.transitions ?? []).filter((t) => t.at > mediaStart && t.at < mediaEnd);
+    const gap = stage.transitionGap;
+    const clipDuration = round(mediaDuration + gap * handOffs.length);
+    const clipEnd = round(clipStart + clipDuration);
+    const toComposition = (t) => round(clipStart + (t - mediaStart) + gap * handOffs.filter((h) => h.at <= t).length);
+    const transitions = handOffs.map((card, i) => ({
+        at: round(clipStart + (card.at - mediaStart) + gap * i),
+        gap,
+        card,
+    }));
+    const bounds = [mediaStart, ...handOffs.map((t) => t.at), mediaEnd];
+    const segments = bounds.slice(0, -1).map((from, i) => ({
+        start: round(clipStart + (from - mediaStart) + gap * i),
+        duration: round(bounds[i + 1] - from),
+        mediaStart: round(from),
+    }));
+    // Callouts: resolve each to a recording time, keep the ones inside the window, in order.
+    const specs = spec.callouts ?? defaultCallouts(markers);
+    const unknown = specs.filter((c) => c.marker !== undefined && !markers.markers.some((m) => m.label === c.marker));
+    if (unknown.length) {
+        throw new TimelineError(`callout(s) reference unknown markers: ${unknown.map((c) => JSON.stringify(c.marker)).join(', ')} ` +
+            `— markers.json has ${markers.markers.map((m) => JSON.stringify(m.label)).join(', ') || 'none'}`);
+    }
+    const timed = specs
+        .map((c, source) => {
+        if ((c.marker === undefined) === (c.at === undefined)) {
+            throw new TimelineError(`callout "${c.text}" needs exactly one of \`marker\` or \`at\``);
+        }
+        if (c.offset !== undefined && c.marker === undefined) {
+            throw new TimelineError(`callout "${c.text}": \`offset\` shifts a \`marker\`; with \`at\`, change \`at\` instead`);
+        }
+        if (c.anchor !== undefined && c.marker === undefined) {
+            throw new TimelineError(`callout "${c.text}": \`anchor\` needs a \`marker\``);
+        }
+        if (c.at !== undefined) {
+            return { ...c, recordingAt: c.at, shownUntil: c.at, source };
+        }
+        const marker = markers.markers.find((m) => m.label === c.marker).at;
+        const start = c.anchor === 'marker' ? marker : stepStart(markers, marker, mediaStart);
+        return { ...c, recordingAt: round(start + (c.offset ?? 0)), shownUntil: marker, source };
+    })
+        .filter((c) => {
+        const inside = c.recordingAt >= mediaStart && c.recordingAt <= mediaEnd;
+        if (!inside) {
+            warnings.push(`callout "${c.text}" at ${c.recordingAt}s is outside the trim window — dropped`);
+        }
+        return inside;
+    })
+        .sort((a, b) => a.recordingAt - b.recordingAt);
+    const transitionTimes = transitions.map((t) => t.at);
+    // When each shows. A step that starts as the footage does waits for the recording to
+    // arrive; one that starts right after the previous (a step that was only a page load) waits
+    // until that one has been up long enough to read. An explicit `at` is kept as given.
+    // With a voice-over, that is until its line has been said (and never past the recording).
+    const speaking = timed.map((c) => spoken(c));
+    const minimum = (i) => Math.max(stage.calloutMinimum, speaking[i] ? speaking[i] + SPOKEN_TAIL : 0);
+    const starts = [];
+    timed.forEach((c, i) => {
+        const at = toComposition(c.recordingAt);
+        const after = i ? starts[i - 1] + minimum(i - 1) : 0;
+        starts.push(c.at === undefined
+            ? round(Math.max(at, clipStart + stage.belt, Math.min(after, Math.max(at, clipEnd - stage.calloutMinimum))))
+            : at);
+    });
+    const callouts = timed.map((c, i) => {
+        const at = starts[i];
+        const next = starts[i + 1];
+        const nextTransition = transitionTimes.find((t) => t > at);
+        // Never overlap the next callout or a hand-off card; never outlive the recording.
+        const cap = Math.min(next !== undefined ? next - 0.2 : Infinity, nextTransition !== undefined ? nextTransition - stage.belt - 0.1 : Infinity, clipEnd - 0.3);
+        // Through its step, and a moment on its result (the marker), at least calloutDuration.
+        const wanted = Math.max(stage.calloutDuration, toComposition(c.shownUntil) - at + stage.calloutHold, speaking[i]);
+        const duration = round(c.duration ?? Math.max(1, Math.min(wanted, cap - at)));
+        if (c.duration !== undefined && at + c.duration > cap + 0.01) {
+            warnings.push(`callout "${c.text}" (${c.duration}s) overlaps the next step or the end of the recording`);
+        }
+        if (speaking[i] > duration + 0.25) {
+            warnings.push(`voice-over: "${c.say || c.text}" is still being said ${round(speaking[i] - duration)}s after its callout goes — ` +
+                'shorten its `say`, or pause longer in the scenario');
+        }
+        // Two-actor videos: tag each step with who does it (the hand-off card's roles).
+        const before = handOffs.filter((t) => t.at <= c.recordingAt);
+        const group = c.group ?? (before.length ? before.at(-1)?.to : handOffs[0]?.from);
+        return { at, duration, text: c.text, ...(group ? { group } : {}), ...(c.say !== undefined ? { say: c.say } : {}), source: c.source };
+    });
+    const recapTiming = timing.recap;
+    if (recapTiming && callouts.length > recapTiming.maxSteps) {
+        warnings.push(`${callouts.length} callouts — the recap holds ${recapTiming.maxSteps}; merge or drop steps (extra ones are left out of the recap)`);
+    }
+    const scale = Math.min(stage.maxW / markers.viewport.width, stage.maxH / markers.viewport.height);
+    // recording → recap → outro, each cross-fading into the next by `overlap`. Without a
+    // recap the outro waits for the recording to fade out: its text never lands on the footage.
+    const recapStart = round(clipEnd - stage.overlap);
+    const recap = recapTiming
+        ? {
+            start: recapStart,
+            duration: round(Math.min(recapTiming.max, recapTiming.base + recapTiming.perStep * Math.min(callouts.length, recapTiming.maxSteps))),
+            maxSteps: recapTiming.maxSteps,
+        }
+        : null;
+    const outroStart = recap ? round(recap.start + recap.duration - stage.overlap) : clipEnd;
+    const total = round(outroStart + timing.outro.duration);
+    const frame = {
+        width: Math.round(markers.viewport.width * scale),
+        height: Math.round(markers.viewport.height * scale),
+    };
+    const log = markers.cursor;
+    if (spec.cursor !== undefined && (!log || log.drawn)) {
+        warnings.push('video.json `cursor` has no effect: this recording has the cursor filmed in — re-record (record.cursor "layer") to draw it as a layer');
+    }
+    let cursor = null;
+    if (log && !log.drawn && spec.cursor !== false && log.path.length) {
+        const inside = (t) => t >= mediaStart && t <= mediaEnd;
+        // Where the cursor rests when the footage starts: the last move before the trim.
+        const before = log.path.filter(([t]) => t < mediaStart).at(-1);
+        const path = [
+            ...(before ? [[clipStart, before[1], before[2]]] : []),
+            ...log.path.filter(([t]) => inside(t)).map(([t, x, y]) => [toComposition(t), x, y]),
+        ];
+        cursor = {
+            size: spec.cursor?.size ?? 44,
+            ripple: spec.cursor?.ripple ?? true,
+            idle: spec.cursor?.idle ?? 0,
+            scale: Math.round((frame.width / markers.viewport.width) * 10000) / 10000,
+            path,
+            presses: log.presses.filter(([t]) => inside(t)).map(([t, x, y]) => [toComposition(t), x, y]),
+        };
+    }
+    return {
+        timeline: {
+            total,
+            intro: { start: 0, duration: timing.intro.duration, exit: timing.intro.exit },
+            recap,
+            outro: { start: outroStart, duration: timing.outro.duration },
+            clipStart,
+            clipDuration,
+            clipEnd,
+            mediaStart: round(mediaStart),
+            mediaEnd: round(mediaEnd),
+            belt: stage.belt,
+            frame,
+            viewport: markers.viewport,
+            transitions,
+            segments,
+            callouts,
+            cursor,
+            focus: (markers.focus ?? [])
+                .filter((f) => f.at >= mediaStart && f.at <= mediaEnd)
+                .map((f) => ({ ...f, at: toComposition(f.at) })),
+            toComposition,
+        },
+        warnings,
+    };
+}
+/** A trim edge in recording seconds (undefined: not set). */
+/**
+ * When the step that ends at `marker` began: the first glide (or click) after the previous
+ * marker — and after `from`, the trim — else the marker itself (nothing logged in between,
+ * e.g. a page load).
+ */
+export function stepStart(markers, marker, from) {
+    const previous = Math.max(from, ...markers.markers.map((m) => m.at).filter((at) => at < marker - 1e-6));
+    const first = (markers.clicks ?? [])
+        .map((c) => c.move ?? c.at)
+        .filter((t) => t >= previous - 1e-6 && t < marker)
+        .sort((a, b) => a - b)[0];
+    return first ?? marker;
+}
+export function resolveTrimPoint(point, markers, edge) {
+    if (point === undefined || typeof point === 'number') {
+        return point;
+    }
+    if (point === 'auto') {
+        if (edge === 'end') {
+            throw new TimelineError('trim.end cannot be "auto" — leave it out to keep the recording to its end');
+        }
+        return suggestTrimStart(markers);
+    }
+    if ('marker' in point) {
+        const found = markers.markers.find((m) => m.label === point.marker);
+        if (!found) {
+            throw new TimelineError(`trim.${edge}: no marker "${point.marker}" — markers.json has ${markers.markers.map((m) => JSON.stringify(m.label)).join(', ') || 'none'}`);
+        }
+        return round(found.at + (point.offset ?? 0));
+    }
+    const click = markers.clicks?.[point.click - 1];
+    if (!click) {
+        throw new TimelineError(`trim.${edge}: no click ${point.click} — markers.json has ${markers.clicks?.length ?? 0}`);
+    }
+    return round((click.move ?? click.at) + (point.offset ?? 0));
+}
+/** Where the footage should start: just before the first logged glide (after the login). */
+export function suggestTrimStart(markers) {
+    const candidates = [
+        ...(markers.clicks ?? []).map((c) => (c.move ?? c.at) - 0.5),
+        ...markers.markers.map((m) => m.at - 0.8),
+    ];
+    if (!candidates.length) {
+        return 0;
+    }
+    return Math.max(0, round(Math.min(...candidates)));
+}
+/** One callout per marker, worded as the marker label: the starting point of a new video.json. */
+export function defaultCallouts(markers) {
+    return markers.markers.map((m) => ({ marker: m.label, text: m.label }));
+}
+export function round(n) {
+    return Math.round(n * 100) / 100;
+}