reelson 0.7.0

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

@@ -0,0 +1,532 @@
+/**
+ * Builds a demo's HyperFrames project from its video.json.
+ *
+ *   reelson build <slug|dir> [--title ".."] [--subtitle ".."] [--trim-start s] [--trim-end s]
+ *                            [--template name] [--intro name] [--recap name|none] [--outro name]
+ *                            [--music file | --no-music]
+ *
+ * video.json is the source of truth; video/ is generated and can be deleted at
+ * any time. The first build creates video.json from markers.json (one callout
+ * per marker, a suggested trim); the flags above edit video.json in place.
+ *
+ * Writes <demo>/video/{index.html, hyperframes.json, package.json, assets/*}:
+ * the template's stage with the chosen intro/recap/outro sections, its own assets
+ * (vendored GSAP + fonts), each section's assets, the brand logo, the recording, narration
+ * (when the recording has audio) and the music bed (trimmed, loudness-normalised,
+ * faded; cached between builds).
+ */
+import { spawnSync } from 'node:child_process'
+import { copyFileSync, cpSync, existsSync, mkdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs'
+import { basename, extname, resolve } from 'node:path'
+import { countLabel, fromRoot, type LoadedConfig } from '../../reelson-record/scripts/config.ts'
+import { renderComposition, type CompositionInput } from './composition.ts'
+import { phoneLayout, portraitLayout, squareLayout } from './portrait.ts'
+import { renderVoiceTrack, spokenLength, voiceLines, voiceSettings } from './voice.ts'
+import { HYPERFRAMES_VERSION, RENDER_FLAGS } from './hyperframes.ts'
+import {
+    readMarkers,
+    readSection,
+    readVideoSpec,
+    ReelsonError,
+    resolveDesign,
+    videoSchemaRef,
+    type Design,
+    type Section,
+} from './project.ts'
+import {
+    computeTimeline,
+    defaultCallouts,
+    round,
+    type Markers,
+    type SectionChoice,
+    type Timeline,
+    type TrimPoint,
+    type VideoSpec,
+} from './timeline.ts'
+import { compositionClicks, followPath, planZoom, ZoomError, type CompClick, type Zoom } from './zooms.ts'
+
+export interface BuildOptions {
+    title?: string
+    subtitle?: string
+    trimStart?: TrimPoint
+    trimEnd?: TrimPoint
+    template?: string
+    /** Section per slot; stored in video.json `sections`. */
+    sections?: SectionChoice
+    /** A file for this video, or false for none; undefined keeps video.json / config. */
+    music?: string | false
+    log?: (line: string) => void
+}
+
+export interface Plan {
+    spec: VideoSpec
+    markers: Markers
+    design: Design
+    timeline: Timeline
+    clicks: CompClick[]
+    zooms: Zoom[]
+    warnings: string[]
+    /** video.json did not exist and was derived from markers.json. */
+    created: boolean
+}
+
+/** Everything a build needs, computed without touching video/ (check uses it too). */
+export function plan(demoDir: string, config: LoadedConfig, options: BuildOptions = {}): Plan {
+    const markers = readMarkers(demoDir)
+    const existing = readVideoSpec(demoDir)
+    const spec: VideoSpec = existing ?? {
+        title: options.title ?? humanize(basename(demoDir)),
+        // Follows the recording: a re-record never leaves a stale trim behind.
+        trim: { start: 'auto' },
+        callouts: defaultCallouts(markers),
+        zooms: [],
+    }
+    applyOptions(spec, options)
+
+    return { ...planSpec(demoDir, spec, markers, config), created: existing === null }
+}
+
+/** The plan for a given video.json (validated elsewhere), without reading it from disk. */
+export function planSpec(demoDir: string, spec: VideoSpec, markers: Markers, config: LoadedConfig): Omit<Plan, 'created'> {
+    const design = resolveDesign(spec.template ?? config.template, [config.sections, spec.sections], config)
+    let computed
+    try {
+        // With a voice-over, the callouts wait for their (cached) lines to be said.
+        const voice = voiceSettings(spec, config)
+        computed = computeTimeline(markers, spec, design.timing, voice ? spokenLength(voice, resolve(demoDir, 'voice')) : undefined)
+    } catch (error) {
+        throw new ReelsonError(`${resolve(demoDir, 'video.json')}: ${(error as Error).message}`)
+    }
+    const { timeline, warnings } = computed
+    const clicks = compositionClicks(markers, timeline)
+    const zooms = (spec.zooms ?? []).map((z, i) => {
+        try {
+            const zoom = planZoom(z, clicks, timeline)
+            if (z.follow && timeline.cursor) {
+                zoom.path = followPath(zoom, timeline.cursor, timeline.viewport)
+            } else if (z.follow) {
+                warnings.push(`zoom ${i + 1}: "follow" needs the cursor log of a record.cursor "layer" recording — it stays on its focus`)
+            }
+            return zoom
+        } catch (error) {
+            if (error instanceof ZoomError) {
+                throw new ReelsonError(`video.json zooms[${i}]: ${error.message}`)
+            }
+            throw error
+        }
+    })
+
+    return { spec, markers, design, timeline, clicks, zooms, warnings }
+}
+
+/** What `build` made: the plan, plus the timelines of the portrait and square versions (their takes' own timing). */
+export interface Built extends Plan {
+    versions: { portrait: Timeline; square: Timeline | null }
+}
+
+export function build(demoDir: string, config: LoadedConfig, options: BuildOptions = {}): Built {
+    const log = options.log ?? console.log
+    const recording = resolve(demoDir, 'recording.mp4')
+    if (!existsSync(recording)) {
+        throw new ReelsonError(`missing ${recording} — run \`reelson record\` first (or export one from OpenScreen)`)
+    }
+    const result = plan(demoDir, config, options)
+    const { spec, timeline, design } = result
+    const { template } = design
+
+    // video.json first: it is the source of truth even if a later step fails.
+    const specPath = resolve(demoDir, 'video.json')
+    const serialized = serializeVideoSpec(spec, demoDir, config)
+    if (!existsSync(specPath) || readFileSync(specPath, 'utf8') !== serialized) {
+        writeFileSync(specPath, serialized)
+        log(result.created ? `created ${specPath} — word the callouts and add zooms there` : `updated ${specPath}`)
+    }
+
+    const videoDir = resolve(demoDir, 'video')
+    const assets = resolve(videoDir, 'assets')
+    mkdirSync(assets, { recursive: true })
+    if (existsSync(resolve(template.dir, 'assets'))) {
+        cpSync(resolve(template.dir, 'assets'), assets, { recursive: true, preserveTimestamps: true })
+    }
+    const sections = Object.values(design.sections)
+        .filter((section): section is Section => section !== null)
+        .map((section) => {
+            const source = readSection(section)
+            if (source.assets) {
+                cpSync(resolve(section.dir, 'assets'), resolve(videoDir, source.assets), { recursive: true, preserveTimestamps: true })
+            }
+            return source
+        })
+    const logo = copyLogo(spec, config, assets, log)
+    copyIfChanged(recording, resolve(assets, 'recording.mp4'))
+    const narration = extractNarration(recording, resolve(assets, 'narration.m4a'), timeline, log)
+    const voice = voiceTrack(demoDir, config, spec, timeline, resolve(assets, 'voice.m4a'), log)
+    const music = renderMusicBed(spec, config, timeline, resolve(assets, 'music.m4a'), narration || voice, log)
+
+    const brand = { ...config.brand, ...spec.brand }
+    const composition = {
+        stage: readFileSync(resolve(template.dir, 'stage.html'), 'utf8'),
+        sections,
+        timeline,
+        zooms: result.zooms,
+        narration,
+        music,
+        voice,
+        text: {
+            language: config.language,
+            brand,
+            logo,
+            title: spec.title,
+            subtitle: spec.subtitle ?? '',
+            recapTitle: spec.recapTitle ?? config.strings.recapTitle,
+            stepsChip: countLabel(timeline.callouts.length, config.strings.stepsLabel, config.language),
+            secondsChip: countLabel(Math.round(timeline.total), config.strings.secondsLabel, config.language),
+        },
+    }
+    const html = renderComposition(composition)
+    writeFileSync(resolve(videoDir, 'index.html'), html)
+    // The same video for phones (`reelson render --portrait`): from the phone take when there
+    // is one (video.json "portrait"), else a camera framing each element on this recording.
+    const portrait = renderPortrait(demoDir, config, spec, composition, result, assets, log)
+    writeFileSync(resolve(videoDir, 'portrait.html'), portrait.html)
+    // The square video (`reelson render --square`): only from a square take, which fills it.
+    const square = renderSquare(demoDir, config, spec, composition, result, assets, log)
+    if (square) {
+        writeFileSync(resolve(videoDir, 'square.html'), square.html)
+    } else {
+        rmSync(resolve(videoDir, 'square.html'), { force: true })
+    }
+    writeFileSync(
+        resolve(videoDir, 'hyperframes.json'),
+        JSON.stringify(
+            {
+                $schema: 'https://hyperframes.heygen.com/schema/hyperframes.json',
+                paths: { blocks: 'compositions', components: 'compositions/components', assets: 'assets' },
+                // autoProxy swaps big media for a downscaled proxy, which throws away the 2x capture.
+                media: { autoProxy: false },
+            },
+            null,
+            2,
+        ) + '\n',
+    )
+    const hf = `npx --yes hyperframes@${HYPERFRAMES_VERSION}`
+    writeFileSync(
+        resolve(videoDir, 'package.json'),
+        JSON.stringify(
+            {
+                name: `reelson-video-${basename(demoDir)}`,
+                private: true,
+                type: 'module',
+                scripts: { dev: `${hf} preview`, check: `${hf} check`, render: `${hf} render ${RENDER_FLAGS.join(' ')}` },
+            },
+            null,
+            2,
+        ) + '\n',
+    )
+
+    const t = timeline
+    const { intro, recap, outro } = design.sections
+    log(`built ${resolve(videoDir, 'index.html')} (template '${template.name}')`)
+    log(
+        `  timeline: intro/${intro.name} 0–${t.intro.duration}s | recording ${t.clipStart}–${t.clipEnd}s (media ${t.mediaStart}–${t.mediaEnd}s) | ` +
+            (recap && t.recap ? `recap/${recap.name} ${t.recap.start}–${round(t.recap.start + t.recap.duration)}s | ` : 'no recap | ') +
+            `outro/${outro.name} ${t.outro.start}–${t.total}s`,
+    )
+    if (t.transitions.length) {
+        log(`  hand-off card(s) at ${t.transitions.map((tr) => `${tr.at}s`).join(', ')}`)
+    }
+    log(`  frame ${t.frame.width}x${t.frame.height}, ${t.callouts.length} callout(s), ${result.zooms.length} zoom(s)`)
+    for (const w of result.warnings) {
+        log(`  warning: ${w}`)
+    }
+
+    return { ...result, versions: { portrait: portrait.timeline, square: square?.timeline ?? null } }
+}
+
+/** The portrait composition (see `build`). */
+function renderPortrait(
+    demoDir: string,
+    config: LoadedConfig,
+    spec: VideoSpec,
+    composition: CompositionInput,
+    result: Omit<Plan, 'created'>,
+    assets: string,
+    log: (line: string) => void,
+): { html: string; timeline: Timeline } {
+    const source = spec.portrait ?? 'auto'
+    const phoneTake = resolve(demoDir, 'recording.mobile.mp4')
+    const phoneMarkers = resolve(demoDir, 'markers.mobile.json')
+    const hasPhone = existsSync(phoneTake) && existsSync(phoneMarkers)
+    if (source === 'mobile' && !hasPhone) {
+        log('  warning: video.json "portrait": "mobile", but there is no phone take — run `reelson record <slug> --mobile`; using the desktop camera')
+    }
+    if (source !== 'desktop' && hasPhone) {
+        try {
+            // The same video.json on the phone take: callouts follow their markers; zooms are
+            // numbered by the desktop clicks, so they don't apply.
+            const markers = JSON.parse(readFileSync(phoneMarkers, 'utf8')) as Markers
+            const phone = planSpec(demoDir, { ...spec, zooms: [] }, markers, config)
+            copyIfChanged(phoneTake, resolve(assets, 'recording.mobile.mp4'))
+            const narration = extractNarration(phoneTake, resolve(assets, 'narration.mobile.m4a'), phone.timeline, () => {})
+            const voice = voiceTrack(demoDir, config, spec, phone.timeline, resolve(assets, 'voice.mobile.m4a'), () => {})
+            const music = renderMusicBed(spec, config, phone.timeline, resolve(assets, 'music.mobile.m4a'), narration || voice, () => {})
+            const layout = phoneLayout(phone.timeline)
+            log(`  portrait: the phone take (${markers.viewport.width}x${markers.viewport.height}), ${phone.timeline.total}s`)
+            const html = renderComposition({
+                ...composition,
+                timeline: phone.timeline,
+                layout: layout.layout,
+                cursor: layout.cursor,
+                zooms: [],
+                narration,
+                music,
+                voice,
+                media: {
+                    recording: 'assets/recording.mobile.mp4',
+                    narration: 'assets/narration.mobile.m4a',
+                    music: 'assets/music.mobile.m4a',
+                    voice: 'assets/voice.mobile.m4a',
+                },
+                text: {
+                    ...composition.text,
+                    stepsChip: countLabel(phone.timeline.callouts.length, config.strings.stepsLabel, config.language),
+                    secondsChip: countLabel(Math.round(phone.timeline.total), config.strings.secondsLabel, config.language),
+                },
+            })
+            return { html, timeline: phone.timeline }
+        } catch (error) {
+            log(`  warning: the phone take does not fit video.json (${(error as Error).message}) — portrait uses the desktop camera`)
+        }
+    }
+    const camera = portraitLayout(result.timeline)
+    return { html: renderComposition({ ...composition, layout: camera.layout, cursor: camera.cursor, zooms: camera.zooms }), timeline: result.timeline }
+}
+
+/**
+ * The square composition (see `build`), or null without a square take (or one that no longer
+ * fits video.json).
+ */
+function renderSquare(
+    demoDir: string,
+    config: LoadedConfig,
+    spec: VideoSpec,
+    composition: CompositionInput,
+    result: Omit<Plan, 'created'>,
+    assets: string,
+    log: (line: string) => void,
+): { html: string; timeline: Timeline } | null {
+    const take = resolve(demoDir, 'recording.square.mp4')
+    const takeMarkers = resolve(demoDir, 'markers.square.json')
+    if (!existsSync(take) || !existsSync(takeMarkers)) {
+        return null
+    }
+    try {
+        // The same video.json on the square take: callouts follow their markers. Zooms are
+        // anchored by click number, so they carry over only while the clicks match.
+        const markers = JSON.parse(readFileSync(takeMarkers, 'utf8')) as Markers
+        const clicks = markers.clicks?.length ?? 0
+        const desktopClicks = result.markers.clicks?.length ?? 0
+        const sameClicks = clicks === desktopClicks
+        if (!sameClicks && spec.zooms?.length) {
+            log(`  warning: the square take has ${clicks} click(s), the desktop take ${desktopClicks} — the square video leaves out the zooms`)
+        }
+        const plan = planSpec(demoDir, sameClicks ? spec : { ...spec, zooms: [] }, markers, config)
+        copyIfChanged(take, resolve(assets, 'recording.square.mp4'))
+        const narration = extractNarration(take, resolve(assets, 'narration.square.m4a'), plan.timeline, () => {})
+        const voice = voiceTrack(demoDir, config, spec, plan.timeline, resolve(assets, 'voice.square.m4a'), () => {})
+        const music = renderMusicBed(spec, config, plan.timeline, resolve(assets, 'music.square.m4a'), narration || voice, () => {})
+        const layout = squareLayout(plan.timeline)
+        log(`  square: the square take (${markers.viewport.width}x${markers.viewport.height}), ${plan.timeline.total}s`)
+        const html = renderComposition({
+            ...composition,
+            timeline: plan.timeline,
+            layout: layout.layout,
+            cursor: layout.cursor,
+            zooms: plan.zooms,
+            narration,
+            music,
+            voice,
+            media: {
+                recording: 'assets/recording.square.mp4',
+                narration: 'assets/narration.square.m4a',
+                music: 'assets/music.square.m4a',
+                voice: 'assets/voice.square.m4a',
+            },
+            text: {
+                ...composition.text,
+                stepsChip: countLabel(plan.timeline.callouts.length, config.strings.stepsLabel, config.language),
+                secondsChip: countLabel(Math.round(plan.timeline.total), config.strings.secondsLabel, config.language),
+            },
+        })
+        return { html, timeline: plan.timeline }
+    } catch (error) {
+        log(`  warning: the square take does not fit video.json (${(error as Error).message}) — re-record it: \`reelson record ${basename(demoDir)} --square\``)
+        return null
+    }
+}
+
+/** The voice-over track for one version (see voice.ts); false when the video has none. */
+function voiceTrack(demoDir: string, config: LoadedConfig, spec: VideoSpec, t: Timeline, target: string, log: (l: string) => void): boolean {
+    const settings = voiceSettings(spec, config)
+    if (!settings) {
+        return false
+    }
+    return renderVoiceTrack(voiceLines(t, spec, settings), settings, resolve(demoDir, 'voice'), t.total, target, log)
+}
+
+function applyOptions(spec: VideoSpec, o: BuildOptions): void {
+    if (o.title !== undefined) spec.title = o.title
+    if (o.subtitle !== undefined) spec.subtitle = o.subtitle
+    if (o.template !== undefined) spec.template = o.template
+    if (o.sections && Object.keys(o.sections).length) spec.sections = { ...spec.sections, ...o.sections }
+    if (o.trimStart !== undefined) spec.trim = { ...spec.trim, start: o.trimStart }
+    if (o.trimEnd !== undefined) spec.trim = { ...spec.trim, end: o.trimEnd }
+    if (o.music !== undefined) spec.music = o.music
+}
+
+function humanize(slug: string): string {
+    const words = slug.replace(/[-_]+/g, ' ').trim()
+    return words.charAt(0).toUpperCase() + words.slice(1)
+}
+
+/** video.json as the build writes it: `$schema` first, then a stable, readable key order. */
+export function serializeVideoSpec(spec: VideoSpec, demoDir: string, config: LoadedConfig): string {
+    return JSON.stringify({ $schema: videoSchemaRef(demoDir, config), ...withoutSchema(spec) }, null, 4) + '\n'
+}
+
+/** video.json in a stable, readable key order, without `$schema` (re-added on write). */
+function withoutSchema(spec: VideoSpec): VideoSpec {
+    const { $schema: _ignored, ...rest } = spec as VideoSpec & { $schema?: string }
+    const order: (keyof VideoSpec)[] = ['title', 'subtitle', 'template', 'sections', 'recapTitle', 'brand', 'trim', 'music', 'callouts', 'zooms', 'cursor', 'voice', 'portrait', 'formats']
+    const known = order.filter((k) => rest[k] !== undefined).map((k) => [k, rest[k]])
+    const others = Object.entries(rest).filter(([k]) => !order.includes(k as keyof VideoSpec))
+
+    return Object.fromEntries([...known, ...others]) as VideoSpec
+}
+
+const LOGO_TYPES = ['.svg', '.png', '.webp']
+
+/**
+ * brand.logo (video.json over demo.config.json) → assets/brand-logo.<ext>. Returns its
+ * path for the composition, or '' when the brand is drawn as a text wordmark.
+ */
+function copyLogo(spec: VideoSpec, config: LoadedConfig, assets: string, log: (l: string) => void): string {
+    const file = spec.brand?.logo !== undefined ? spec.brand.logo : config.brand.logo
+    if (!file) {
+        return ''
+    }
+    const source = fromRoot(config, file)
+    const ext = extname(source).toLowerCase()
+    if (!LOGO_TYPES.includes(ext)) {
+        throw new ReelsonError(`brand.logo must be ${LOGO_TYPES.join(', ')} (SVG stays sharpest), got ${source}`)
+    }
+    if (!existsSync(source)) {
+        throw new ReelsonError(`brand logo not found: ${source} — fix brand.logo, or set it to null for the text wordmark`)
+    }
+    const height = ext === '.png' ? pngHeight(source) : null
+    if (height !== null && height < MIN_LOGO_HEIGHT) {
+        log(`  warning: ${basename(source)} is ${height}px tall — under ${MIN_LOGO_HEIGHT}px it looks soft on the cards; use an SVG or a taller PNG`)
+    }
+    const name = `brand-logo${ext}`
+    copyIfChanged(source, resolve(assets, name))
+
+    return `assets/${name}`
+}
+
+/** The biggest wordmark (168px tall on the outro) at 2x, so the logo stays crisp. */
+const MIN_LOGO_HEIGHT = 340
+
+function pngHeight(path: string): number | null {
+    const header = readFileSync(path).subarray(0, 24)
+    return header.toString('ascii', 12, 16) === 'IHDR' ? header.readUInt32BE(20) : null
+}
+
+function copyIfChanged(from: string, to: string): void {
+    if (existsSync(to)) {
+        const a = statSync(from)
+        const b = statSync(to)
+        if (a.size === b.size && b.mtimeMs >= a.mtimeMs) {
+            return
+        }
+    }
+    copyFileSync(from, to)
+}
+
+/** Extracts the recording's audio track (OpenScreen voiceover), if any. */
+function extractNarration(source: string, target: string, t: Timeline, log: (l: string) => void): boolean {
+    const probe = spawnSync(
+        'ffprobe',
+        ['-v', 'error', '-select_streams', 'a', '-show_entries', 'stream=codec_name', '-of', 'csv=p=0', source],
+        { encoding: 'utf8' },
+    )
+    if (probe.status !== 0 || probe.stdout.trim() === '') {
+        return false
+    }
+    if (t.transitions.length) {
+        log('  warning: narration is not split at hand-offs; it drifts after the first transition card')
+    }
+    if (existsSync(target) && statSync(target).mtimeMs >= statSync(source).mtimeMs) {
+        return true
+    }
+    const extract = spawnSync('ffmpeg', ['-y', '-loglevel', 'error', '-i', source, '-vn', '-c:a', 'aac', '-b:a', '160k', target], {
+        stdio: 'inherit',
+    })
+    if (extract.status !== 0) {
+        log('  warning: ffmpeg could not extract the audio track; continuing without narration')
+        return false
+    }
+    log('  audio track found — narration extracted to assets/narration.m4a')
+    return true
+}
+
+/**
+ * Pre-renders the music bed with ffmpeg (trim, loudnorm, fades) so the
+ * composition plays it at unity. Cached: re-rendered only when the source,
+ * length or loudness changes.
+ */
+function renderMusicBed(
+    spec: VideoSpec,
+    config: LoadedConfig,
+    t: Timeline,
+    target: string,
+    underNarration: boolean,
+    log: (l: string) => void,
+): boolean {
+    const choice = spec.music ?? null
+    if (choice === false) {
+        return false
+    }
+    const file = typeof choice === 'string' ? choice : config.music.file
+    if (!file) {
+        log('  no music: set music.file in demo.config.json (or "music" in video.json)')
+        return false
+    }
+    const source = fromRoot(config, file)
+    if (!existsSync(source)) {
+        throw new ReelsonError(`music not found: ${source} — fix music.file / video.json "music", or set "music": false`)
+    }
+    const lufs = underNarration ? config.music.lufsUnderNarration : config.music.lufs
+    const fadeOut = 3
+    const key = JSON.stringify({ source, mtime: statSync(source).mtimeMs, total: t.total, lufs })
+    const stamp = `${target}.key`
+    if (existsSync(target) && existsSync(stamp) && readFileSync(stamp, 'utf8') === key) {
+        return true
+    }
+    const filters = [
+        `atrim=0:${t.total}`,
+        `loudnorm=I=${lufs}:TP=-3:LRA=9`,
+        'afade=t=in:st=0:d=0.8',
+        `afade=t=out:st=${round(t.total - fadeOut)}:d=${fadeOut}`,
+    ].join(',')
+    const render = spawnSync(
+        'ffmpeg',
+        ['-y', '-loglevel', 'error', '-i', source, '-vn', '-af', filters, '-c:a', 'aac', '-b:a', '160k', target],
+        { stdio: 'inherit' },
+    )
+    if (render.status !== 0) {
+        throw new ReelsonError('ffmpeg could not render the music bed')
+    }
+    writeFileSync(stamp, key)
+    log(`  music bed: ${basename(source)} → assets/music.m4a (${lufs} LUFS, fades 0.8s/${fadeOut}s)`)
+    return true
+}

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

@@ -0,0 +1,24 @@
+export function captionCues(timeline, title, subtitle) {
+    const intro = subtitle ? `${title}\n${subtitle}` : title;
+    return [
+        { start: 0, end: timeline.intro.exit, text: intro },
+        ...timeline.callouts.map((c) => ({ start: c.at, end: c.at + c.duration, text: c.text })),
+    ].filter((c) => c.end > c.start && c.text.trim());
+}
+export function toSrt(cues) {
+    const time = (s) => clock(s, ',');
+    return cues.map((c, i) => `${i + 1}\n${time(c.start)} --> ${time(c.end)}\n${c.text}\n`).join('\n');
+}
+export function toVtt(cues) {
+    const time = (s) => clock(s, '.');
+    return `WEBVTT\n\n${cues.map((c) => `${time(c.start)} --> ${time(c.end)}\n${c.text}\n`).join('\n')}`;
+}
+/** 00:01:02,345 (SRT) / 00:01:02.345 (WebVTT). */
+function clock(seconds, separator) {
+    const ms = Math.max(0, Math.round(seconds * 1000));
+    const pad = (n, width = 2) => String(n).padStart(width, '0');
+    const h = Math.floor(ms / 3_600_000);
+    const m = Math.floor((ms % 3_600_000) / 60_000);
+    const s = Math.floor((ms % 60_000) / 1000);
+    return `${pad(h)}:${pad(m)}:${pad(s)}${separator}${pad(ms % 1000, 3)}`;
+}

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

@@ -0,0 +1,40 @@
+/**
+ * Captions for a rendered video: the title while the intro is on screen, then one cue per
+ * callout, in composition time — the same words the viewer reads on the cards, as a
+ * subtitle track for players, social uploads and screen readers. Pure.
+ */
+import type { Timeline } from './timeline.ts'
+
+export interface Cue {
+    start: number
+    end: number
+    text: string
+}
+
+export function captionCues(timeline: Timeline, title: string, subtitle?: string): Cue[] {
+    const intro = subtitle ? `${title}\n${subtitle}` : title
+    return [
+        { start: 0, end: timeline.intro.exit, text: intro },
+        ...timeline.callouts.map((c) => ({ start: c.at, end: c.at + c.duration, text: c.text })),
+    ].filter((c) => c.end > c.start && c.text.trim())
+}
+
+export function toSrt(cues: Cue[]): string {
+    const time = (s: number) => clock(s, ',')
+    return cues.map((c, i) => `${i + 1}\n${time(c.start)} --> ${time(c.end)}\n${c.text}\n`).join('\n')
+}
+
+export function toVtt(cues: Cue[]): string {
+    const time = (s: number) => clock(s, '.')
+    return `WEBVTT\n\n${cues.map((c) => `${time(c.start)} --> ${time(c.end)}\n${c.text}\n`).join('\n')}`
+}
+
+/** 00:01:02,345 (SRT) / 00:01:02.345 (WebVTT). */
+function clock(seconds: number, separator: ',' | '.'): string {
+    const ms = Math.max(0, Math.round(seconds * 1000))
+    const pad = (n: number, width = 2) => String(n).padStart(width, '0')
+    const h = Math.floor(ms / 3_600_000)
+    const m = Math.floor((ms % 3_600_000) / 60_000)
+    const s = Math.floor((ms % 60_000) / 1000)
+    return `${pad(h)}:${pad(m)}:${pad(s)}${separator}${pad(ms % 1000, 3)}`
+}

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

@@ -0,0 +1,80 @@
+/**
+ * Checks a demo before rendering:
+ *   1. demo.config.json and video.json match their schemas (typos are errors);
+ *   2. the timeline resolves (callouts point at real markers, trims make sense);
+ *   3. every zoom rides along with the cursor (style guide #13) — see zooms.ts;
+ *   4. `hyperframes check` on each built composition — landscape, portrait, square (lint,
+ *      runtime, layout, contrast).
+ *
+ *   reelson check <slug|dir> [--no-hyperframes]
+ */
+import { existsSync, statSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { plan } from "./build.js";
+import { hyperframesOn } from "./hyperframes.js";
+import { round } from "./timeline.js";
+import { checkZoom, zoomOverlaps } from "./zooms.js";
+/** Returns the number of problems found (0 = ready to render). */
+export function check(demoDir, config, options = {}) {
+    const log = options.log ?? console.log;
+    const result = plan(demoDir, config);
+    let problems = 0;
+    if (result.created) {
+        log('✗ no video.json yet — run `reelson build` first');
+        return 1;
+    }
+    for (const w of result.warnings) {
+        log(`! ${w}`);
+    }
+    for (const edge of ['start', 'end']) {
+        if (typeof result.spec.trim?.[edge] === 'number') {
+            log(`! trim.${edge} is a fixed time — after a re-record it cuts in the wrong place; ` +
+                (edge === 'start' ? 'use "auto" or ' : 'use ') +
+                '{ "marker": "…", "offset": … } / { "click": n, "offset": … } instead');
+        }
+    }
+    if ((result.spec.zooms ?? []).length && !result.clicks.length) {
+        log('✗ zooms need logged clicks — re-record with the current reelson-record scripts');
+        problems++;
+    }
+    const overlaps = zoomOverlaps(result.zooms);
+    result.zooms.forEach((z, i) => {
+        const { problems: checked, framed } = checkZoom(z, result.clicks, result.timeline);
+        const found = [...checked, ...overlaps.filter((o) => o.index === i).map((o) => o.message)];
+        const label = `zoom ${i + 1} (${z.at}–${round(z.at + z.duration)}s, in ${z.in}s / out ${z.out}s, ${z.scale}x at ${z.x},${z.y})`;
+        if (found.length) {
+            problems += found.length;
+            log(`✗ ${label}`);
+            found.forEach((p) => log(`    ${p}`));
+        }
+        else {
+            log(`✓ ${label}: ${framed.map((c) => `${c.kind} #${c.index} ${c.comp}s`).join(', ')}`);
+        }
+    });
+    if (!result.zooms.length) {
+        log('✓ no zooms');
+    }
+    const videoDir = resolve(demoDir, 'video');
+    const index = resolve(videoDir, 'index.html');
+    if (!existsSync(index)) {
+        log('✗ video/ is not built — run `reelson build`');
+        return problems + 1;
+    }
+    if (statSync(resolve(demoDir, 'video.json')).mtimeMs > statSync(index).mtimeMs) {
+        log('! video.json changed since the last build — run `reelson build` (render does it for you)');
+    }
+    if (options.hyperframes !== false) {
+        for (const composition of ['index.html', 'portrait.html', 'square.html']) {
+            if (!existsSync(resolve(videoDir, composition))) {
+                continue;
+            }
+            log(`\n${composition}:`);
+            if (hyperframesOn(videoDir, composition, ['check', '.']) !== 0) {
+                log(`✗ hyperframes check failed (${composition})`);
+                problems++;
+            }
+        }
+    }
+    log(problems ? `\n${problems} problem(s)` : '\nready to render');
+    return problems;
+}