reelson 0.7.0

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

@@ -0,0 +1,93 @@
+/**
+ * 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 type { LoadedConfig } from '../../reelson-record/scripts/config.ts'
+import { plan } from './build.ts'
+import { hyperframesOn } from './hyperframes.ts'
+import { round } from './timeline.ts'
+import { checkZoom, zoomOverlaps } from './zooms.ts'
+
+export interface CheckOptions {
+    hyperframes?: boolean
+    log?: (line: string) => void
+}
+
+/** Returns the number of problems found (0 = ready to render). */
+export function check(demoDir: string, config: LoadedConfig, options: CheckOptions = {}): number {
+    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'] as const) {
+        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
+}
+

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

@@ -0,0 +1,163 @@
+import { round } from "./timeline.js";
+import { calloutsAtTop, landscapeLayout } from "./portrait.js";
+const MEDIA = { recording: 'assets/recording.mp4', narration: 'assets/narration.m4a', music: 'assets/music.m4a', voice: 'assets/voice.m4a' };
+/** HyperFrames track per slot: the recap cross-fades with the outro, so they sit on different tracks. */
+const TRACKS = { intro: 3, recap: 2, outro: 3 };
+export function renderComposition(input) {
+    const { timeline: t, text } = input;
+    const layout = input.layout ?? landscapeLayout(t);
+    const atTop = calloutsAtTop(t, layout);
+    // Everything the stage and section scripts animate from. Times are composition seconds.
+    const demo = {
+        total: t.total,
+        clipStart: t.clipStart,
+        clipDuration: t.clipDuration,
+        mediaStart: t.mediaStart,
+        sections: { intro: t.intro, recap: t.recap, outro: t.outro },
+        callouts: t.callouts.map(({ source: _source, say: _say, ...c }, i) => (atTop.has(i) ? { ...c, top: true } : c)),
+        zooms: input.zooms,
+        cursor: input.cursor !== undefined ? input.cursor : t.cursor,
+        layout: { format: layout.format, stage: layout.stage, bandZoom: layout.bandZoom, camera: layout.camera },
+        transitions: t.transitions.map(({ at, gap }) => ({ at, gap })),
+        chip: { steps: text.stepsChip, seconds: text.secondsChip },
+    };
+    const shared = {
+        LANG: escapeHtml(text.language),
+        BRAND_COLOR: escapeHtml(text.brand.color),
+        BRAND_COLOR_SOFT: escapeHtml(text.brand.colorSoft),
+        BRAND: escapeHtml(text.brand.name),
+        BRAND_SUB: escapeHtml(text.brand.tagline),
+        BRAND_LOGO: escapeHtml(text.logo),
+        EYEBROW: escapeHtml(text.brand.eyebrow),
+        TITLE: escapeHtml(text.title),
+        SUBTITLE: escapeHtml(text.subtitle),
+        OUTRO_TITLE: escapeHtml(text.recapTitle),
+        TOTAL: String(t.total),
+        FRAME_W: String(layout.frame.width),
+        FRAME_H: String(layout.frame.height),
+        FOOTAGE_W: String(layout.footage.width),
+        FOOTAGE_H: String(layout.footage.height),
+        STAGE_W: String(layout.stage.width),
+        STAGE_H: String(layout.stage.height),
+        BAND_ZOOM: String(layout.bandZoom),
+        FORMAT: layout.phone ? `${layout.format} phone` : layout.format,
+    };
+    const unfilled = new Set();
+    const fill = (source, values) => source.replace(/{{([A-Z_]+)}}/g, (match, key) => {
+        if (key in values) {
+            return values[key];
+        }
+        unfilled.add(match);
+        return match;
+    });
+    const parts = input.sections.map((s) => {
+        const slot = t[s.slot];
+        if (!slot) {
+            throw new Error(`the timeline has no ${s.slot} (recap "none") but a ${s.slot} section was given`);
+        }
+        const values = {
+            ...shared,
+            START: String(slot.start),
+            DURATION: String(slot.duration),
+            TRACK: String(TRACKS[s.slot]),
+            ASSETS: s.assets,
+        };
+        const label = `${s.slot}: ${s.name}`;
+        return {
+            slot: s.slot,
+            css: `      /* ── ${label} ── */\n${indent(fill(s.css, values).trim(), 6)}`,
+            html: `      <!-- ── ${label} ── -->\n${indent(band(fill(s.html, values).trim(), layout.format === 'landscape' || (layout.format === 'square' ? s.square : s.portrait)), 6)}`,
+            js: `      // ── ${label} ──\n      ;((section) => {\n${indent(fill(s.js, values).trim(), 8)}\n` +
+                `      })(DEMO.sections.${s.slot});`,
+        };
+    });
+    const part = (slot) => parts.find((p) => p.slot === slot) ?? { html: '', css: '', js: '' };
+    const html = fill(input.stage, {
+        ...shared,
+        SECTION_STYLES: parts.map((p) => p.css).join('\n\n'),
+        // Each slot has its own place in the stage: the intro sits under #screen, recap and outro above it.
+        INTRO: part('intro').html,
+        RECAP: part('recap').html,
+        OUTRO: part('outro').html,
+        SECTION_SCRIPTS: parts.map((p) => p.js).join('\n\n'),
+        VIDEOS: renderVideoSegments(t, (input.media ?? MEDIA).recording),
+        TRANSITIONS: t.transitions.map((tr, i) => renderTransitionCard(tr, i, t.belt)).join('\n'),
+        AUDIO: input.narration ? renderNarration(t, (input.media ?? MEDIA).narration) : '',
+        MUSIC: (input.music ? renderMusic(t, (input.media ?? MEDIA).music) : '') +
+            (input.voice ? `\n${renderVoice(t, input.media?.voice ?? MEDIA.voice)}` : ''),
+        // JSON is valid JS; escaping "<" keeps "</script>" in a callout from closing the tag.
+        DEMO: JSON.stringify(demo, null, 2)
+            // Number tuples (cursor [t, x, y], camera [t, k, x, y, h]) one per line, not one number per line.
+            .replace(/\[\s+((?:-?[\d.]+,\s+)+-?[\d.]+)\s+\]/g, (_m, inner) => `[${inner.split(/,\s+/).join(', ')}]`)
+            .replace(/</g, '\\u003c')
+            .replace(/\n/g, '\n      '),
+    });
+    if (unfilled.size) {
+        throw new Error(`template placeholders left unfilled: ${[...unfilled].join(', ')}`);
+    }
+    return html;
+}
+/**
+ * A section without its own layout for this format (portrait, square): mark its root so the
+ * stage zooms its 16:9 card to the width.
+ */
+function band(html, laidOut = false) {
+    return laidOut ? html : html.replace(/^(<section\b[^>]*\bclass=")([^"]*)"/, '$1$2 band"');
+}
+function indent(block, spaces) {
+    const pad = ' '.repeat(spaces);
+    return block
+        .split('\n')
+        .map((line) => (line.trim() ? pad + line : ''))
+        .join('\n');
+}
+/**
+ * One <video> clip per stretch of footage between hand-offs (same file,
+ * different data-media-start), so the footage pauses while a card is on screen.
+ */
+function renderVideoSegments(t, src) {
+    return t.segments
+        .map((s, i) => {
+        const id = i === 0 ? 'recording' : `recording-${i + 1}`;
+        return `          <video id="${id}" class="clip" src="${src}" muted playsinline
+            data-start="${s.start}" data-duration="${s.duration}" data-media-start="${s.mediaStart}" data-track-index="1"></video>`;
+    })
+        .join('\n');
+}
+/** Markup for a hand-off card; the template's builder animates it from DEMO.transitions. */
+function renderTransitionCard(tr, i, belt) {
+    const { card } = tr;
+    const roles = card.from && card.to
+        ? `
+          <div class="roles">
+            <div class="role from">${escapeHtml(card.from)}</div>
+            <div class="arrow"></div>
+            <div class="role to"><div class="fill"></div><span>${escapeHtml(card.to)}</span></div>
+          </div>`
+        : '';
+    const subtitle = card.subtitle
+        ? `
+          <p class="subtitle">${escapeHtml(card.subtitle)}</p>`
+        : '';
+    return `      <!-- Hand-off ${i + 1}: demo.transition() in the scenario -->
+      <section id="transition-${i}" class="clip transition-card" data-start="${round(tr.at - belt)}" data-duration="${round(tr.gap + 2 * belt)}" data-track-index="2">
+        <div class="stack">${roles}
+          <h1 class="title">${escapeHtml(card.title)}</h1>${subtitle}
+        </div>
+      </section>`;
+}
+function renderNarration(t, src) {
+    return `      <!-- Narration from the recording (kept in sync via the same start/media-start) -->
+      <audio id="narration" class="clip" src="${src}" data-start="${t.clipStart}" data-duration="${round(t.mediaEnd - t.mediaStart)}" data-media-start="${t.mediaStart}" data-track-index="3"></audio>`;
+}
+function renderMusic(t, src) {
+    return `      <!-- Music bed, pre-rendered by reelson build (trim + loudnorm + fades) -->
+      <audio id="music" class="clip" src="${src}" data-start="0" data-duration="${t.total}" data-track-index="4"></audio>`;
+}
+function renderVoice(t, src) {
+    return `      <!-- Voice-over, pre-mixed by reelson build (each callout spoken as it appears) -->
+      <audio id="voice" class="clip" src="${src}" data-start="0" data-duration="${t.total}" data-track-index="5"></audio>`;
+}
+export function escapeHtml(s) {
+    return s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+}

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

@@ -0,0 +1,241 @@
+/**
+ * Assembles a template's stage.html and the chosen sections into one
+ * composition, filled from a computed timeline. Pure (strings in, string out),
+ * so the output is golden-tested. See templates/README.md for the contract.
+ */
+import type { Slot, Timeline } from './timeline.ts'
+import { round } from './timeline.ts'
+import { calloutsAtTop, landscapeLayout, type Layout } from './portrait.ts'
+import type { Zoom } from './zooms.ts'
+
+export interface CompositionText {
+    language: string
+    brand: { name: string; tagline: string; eyebrow: string; color: string; colorSoft: string }
+    /** assets/ path of the brand logo, or '' to draw the text wordmark. */
+    logo: string
+    title: string
+    subtitle: string
+    recapTitle: string
+    /** Intro chip halves, already pluralised: "4 steps", "27 seconds". */
+    stepsChip: string
+    secondsChip: string
+}
+
+/** One section's files, read by the build. */
+export interface SectionSource {
+    slot: Slot
+    name: string
+    html: string
+    css: string
+    js: string
+    /** Where the section's own assets/ were copied, relative to video/ ('' if it has none). */
+    assets: string
+    /** Has its own portrait layout; otherwise its root gets class "band" (portrait zooms it). */
+    portrait?: boolean
+    /** Has its own square layout; otherwise its root gets class "band" (square zooms it). */
+    square?: boolean
+}
+
+export interface CompositionInput {
+    stage: string
+    /** In slot order; the recap is left out when the video has none. */
+    sections: SectionSource[]
+    timeline: Timeline
+    zooms: Zoom[]
+    text: CompositionText
+    /** assets/narration.m4a exists (the recording had an audio track). */
+    narration: boolean
+    /** assets/music.m4a exists. */
+    music: boolean
+    /** The voice-over track exists (media.voice). */
+    voice?: boolean
+    /** Stage/frame/footage sizes and the portrait camera; default: the landscape stage. */
+    layout?: Layout
+    /** Overrides the timeline's cursor layer (portrait and square move it into their footage scale). */
+    cursor?: Timeline['cursor']
+    /** The media files (default assets/recording.mp4, narration.m4a, music.m4a). */
+    media?: { recording: string; narration: string; music: string; voice?: string }
+}
+
+const MEDIA = { recording: 'assets/recording.mp4', narration: 'assets/narration.m4a', music: 'assets/music.m4a', voice: 'assets/voice.m4a' }
+
+/** HyperFrames track per slot: the recap cross-fades with the outro, so they sit on different tracks. */
+const TRACKS: Record<Slot, number> = { intro: 3, recap: 2, outro: 3 }
+
+export function renderComposition(input: CompositionInput): string {
+    const { timeline: t, text } = input
+    const layout = input.layout ?? landscapeLayout(t)
+    const atTop = calloutsAtTop(t, layout)
+
+    // Everything the stage and section scripts animate from. Times are composition seconds.
+    const demo = {
+        total: t.total,
+        clipStart: t.clipStart,
+        clipDuration: t.clipDuration,
+        mediaStart: t.mediaStart,
+        sections: { intro: t.intro, recap: t.recap, outro: t.outro },
+        callouts: t.callouts.map(({ source: _source, say: _say, ...c }, i) => (atTop.has(i) ? { ...c, top: true } : c)),
+        zooms: input.zooms,
+        cursor: input.cursor !== undefined ? input.cursor : t.cursor,
+        layout: { format: layout.format, stage: layout.stage, bandZoom: layout.bandZoom, camera: layout.camera },
+        transitions: t.transitions.map(({ at, gap }) => ({ at, gap })),
+        chip: { steps: text.stepsChip, seconds: text.secondsChip },
+    }
+
+    const shared: Record<string, string> = {
+        LANG: escapeHtml(text.language),
+        BRAND_COLOR: escapeHtml(text.brand.color),
+        BRAND_COLOR_SOFT: escapeHtml(text.brand.colorSoft),
+        BRAND: escapeHtml(text.brand.name),
+        BRAND_SUB: escapeHtml(text.brand.tagline),
+        BRAND_LOGO: escapeHtml(text.logo),
+        EYEBROW: escapeHtml(text.brand.eyebrow),
+        TITLE: escapeHtml(text.title),
+        SUBTITLE: escapeHtml(text.subtitle),
+        OUTRO_TITLE: escapeHtml(text.recapTitle),
+        TOTAL: String(t.total),
+        FRAME_W: String(layout.frame.width),
+        FRAME_H: String(layout.frame.height),
+        FOOTAGE_W: String(layout.footage.width),
+        FOOTAGE_H: String(layout.footage.height),
+        STAGE_W: String(layout.stage.width),
+        STAGE_H: String(layout.stage.height),
+        BAND_ZOOM: String(layout.bandZoom),
+        FORMAT: layout.phone ? `${layout.format} phone` : layout.format,
+    }
+    const unfilled = new Set<string>()
+    const fill = (source: string, values: Record<string, string>): string =>
+        source.replace(/{{([A-Z_]+)}}/g, (match, key: string) => {
+            if (key in values) {
+                return values[key]
+            }
+            unfilled.add(match)
+            return match
+        })
+
+    const parts = input.sections.map((s) => {
+        const slot = t[s.slot]
+        if (!slot) {
+            throw new Error(`the timeline has no ${s.slot} (recap "none") but a ${s.slot} section was given`)
+        }
+        const values = {
+            ...shared,
+            START: String(slot.start),
+            DURATION: String(slot.duration),
+            TRACK: String(TRACKS[s.slot]),
+            ASSETS: s.assets,
+        }
+        const label = `${s.slot}: ${s.name}`
+        return {
+            slot: s.slot,
+            css: `      /* ── ${label} ── */\n${indent(fill(s.css, values).trim(), 6)}`,
+            html: `      <!-- ── ${label} ── -->\n${indent(band(fill(s.html, values).trim(), layout.format === 'landscape' || (layout.format === 'square' ? s.square : s.portrait)), 6)}`,
+            js:
+                `      // ── ${label} ──\n      ;((section) => {\n${indent(fill(s.js, values).trim(), 8)}\n` +
+                `      })(DEMO.sections.${s.slot});`,
+        }
+    })
+
+    const part = (slot: Slot) => parts.find((p) => p.slot === slot) ?? { html: '', css: '', js: '' }
+    const html = fill(input.stage, {
+        ...shared,
+        SECTION_STYLES: parts.map((p) => p.css).join('\n\n'),
+        // Each slot has its own place in the stage: the intro sits under #screen, recap and outro above it.
+        INTRO: part('intro').html,
+        RECAP: part('recap').html,
+        OUTRO: part('outro').html,
+        SECTION_SCRIPTS: parts.map((p) => p.js).join('\n\n'),
+        VIDEOS: renderVideoSegments(t, (input.media ?? MEDIA).recording),
+        TRANSITIONS: t.transitions.map((tr, i) => renderTransitionCard(tr, i, t.belt)).join('\n'),
+        AUDIO: input.narration ? renderNarration(t, (input.media ?? MEDIA).narration) : '',
+        MUSIC:
+            (input.music ? renderMusic(t, (input.media ?? MEDIA).music) : '') +
+            (input.voice ? `\n${renderVoice(t, input.media?.voice ?? MEDIA.voice)}` : ''),
+        // JSON is valid JS; escaping "<" keeps "</script>" in a callout from closing the tag.
+        DEMO: JSON.stringify(demo, null, 2)
+            // Number tuples (cursor [t, x, y], camera [t, k, x, y, h]) one per line, not one number per line.
+            .replace(/\[\s+((?:-?[\d.]+,\s+)+-?[\d.]+)\s+\]/g, (_m, inner: string) => `[${inner.split(/,\s+/).join(', ')}]`)
+            .replace(/</g, '\\u003c')
+            .replace(/\n/g, '\n      '),
+    })
+    if (unfilled.size) {
+        throw new Error(`template placeholders left unfilled: ${[...unfilled].join(', ')}`)
+    }
+
+    return html
+}
+
+/**
+ * A section without its own layout for this format (portrait, square): mark its root so the
+ * stage zooms its 16:9 card to the width.
+ */
+function band(html: string, laidOut = false): string {
+    return laidOut ? html : html.replace(/^(<section\b[^>]*\bclass=")([^"]*)"/, '$1$2 band"')
+}
+
+function indent(block: string, spaces: number): string {
+    const pad = ' '.repeat(spaces)
+    return block
+        .split('\n')
+        .map((line) => (line.trim() ? pad + line : ''))
+        .join('\n')
+}
+
+/**
+ * One <video> clip per stretch of footage between hand-offs (same file,
+ * different data-media-start), so the footage pauses while a card is on screen.
+ */
+function renderVideoSegments(t: Timeline, src: string): string {
+    return t.segments
+        .map((s, i) => {
+            const id = i === 0 ? 'recording' : `recording-${i + 1}`
+
+            return `          <video id="${id}" class="clip" src="${src}" muted playsinline
+            data-start="${s.start}" data-duration="${s.duration}" data-media-start="${s.mediaStart}" data-track-index="1"></video>`
+        })
+        .join('\n')
+}
+
+/** Markup for a hand-off card; the template's builder animates it from DEMO.transitions. */
+function renderTransitionCard(tr: Timeline['transitions'][number], i: number, belt: number): string {
+    const { card } = tr
+    const roles =
+        card.from && card.to
+            ? `
+          <div class="roles">
+            <div class="role from">${escapeHtml(card.from)}</div>
+            <div class="arrow"></div>
+            <div class="role to"><div class="fill"></div><span>${escapeHtml(card.to)}</span></div>
+          </div>`
+            : ''
+    const subtitle = card.subtitle
+        ? `
+          <p class="subtitle">${escapeHtml(card.subtitle)}</p>`
+        : ''
+
+    return `      <!-- Hand-off ${i + 1}: demo.transition() in the scenario -->
+      <section id="transition-${i}" class="clip transition-card" data-start="${round(tr.at - belt)}" data-duration="${round(tr.gap + 2 * belt)}" data-track-index="2">
+        <div class="stack">${roles}
+          <h1 class="title">${escapeHtml(card.title)}</h1>${subtitle}
+        </div>
+      </section>`
+}
+
+function renderNarration(t: Timeline, src: string): string {
+    return `      <!-- Narration from the recording (kept in sync via the same start/media-start) -->
+      <audio id="narration" class="clip" src="${src}" data-start="${t.clipStart}" data-duration="${round(t.mediaEnd - t.mediaStart)}" data-media-start="${t.mediaStart}" data-track-index="3"></audio>`
+}
+
+function renderMusic(t: Timeline, src: string): string {
+    return `      <!-- Music bed, pre-rendered by reelson build (trim + loudnorm + fades) -->
+      <audio id="music" class="clip" src="${src}" data-start="0" data-duration="${t.total}" data-track-index="4"></audio>`
+}
+
+function renderVoice(t: Timeline, src: string): string {
+    return `      <!-- Voice-over, pre-mixed by reelson build (each callout spoken as it appears) -->
+      <audio id="voice" class="clip" src="${src}" data-start="0" data-duration="${t.total}" data-track-index="5"></audio>`
+}
+
+export function escapeHtml(s: string): string {
+    return s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;')
+}

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

@@ -0,0 +1,138 @@
+/**
+ * The one place the HyperFrames version is pinned. Everything that renders or
+ * checks goes through `hyperframes()`, so an upgrade is a one-line change here
+ * (verified by the CI smoke test).
+ */
+import { spawnSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { copyFileSync, existsSync, mkdtempSync, readdirSync, readFileSync, realpathSync, rmSync, statSync, symlinkSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, resolve } from 'node:path';
+export const HYPERFRAMES_VERSION = '0.8.46';
+/** Runs `npx hyperframes@<pinned> <args>` in `cwd`; returns the exit code. */
+export function hyperframes(args, cwd) {
+    const run = spawnSync('npx', ['--yes', `hyperframes@${HYPERFRAMES_VERSION}`, ...args], {
+        cwd,
+        stdio: 'inherit',
+    });
+    return run.status ?? 1;
+}
+/**
+ * Runs `hyperframes <args>` on one composition of a built video (index.html, portrait.html,
+ * square.html). `check` and `snapshot` only look at index.html, and lint a project with several
+ * root compositions as an error — so the composition runs alone, as the index.html of a scratch
+ * project that links the built assets. Output paths in `args` must be absolute.
+ */
+export function hyperframesOn(videoDir, composition, args) {
+    if (composition === 'index.html' && args[0] !== 'check') {
+        return hyperframes(args, videoDir);
+    }
+    const scratch = mkdtempSync(resolve(tmpdir(), 'reelson-hf-'));
+    try {
+        symlinkSync(resolve(videoDir, 'assets'), resolve(scratch, 'assets'));
+        copyFileSync(resolve(videoDir, 'hyperframes.json'), resolve(scratch, 'hyperframes.json'));
+        copyFileSync(resolve(videoDir, composition), resolve(scratch, 'index.html'));
+        writeFileSync(resolve(scratch, 'package.json'), '{ "private": true }\n');
+        return hyperframes(args, scratch);
+    }
+    finally {
+        rmSync(scratch, { recursive: true, force: true });
+    }
+}
+/** HyperFrames' default frame rate (renders and snapshots): a video's last frame is at total − 1/FPS. */
+export const FPS = 30;
+/** Render flags that keep the 2x capture sharp (see the reelson-compose skill). */
+export const RENDER_FLAGS = ['--video-frame-format', 'jpg', '-q', 'delivery'];
+/** A quick look: half the frames, draft encoding — about twice as fast. */
+export const DRAFT_FLAGS = ['--video-frame-format', 'jpg', '-q', 'draft', '--fps', '15'];
+/**
+ * Renders `videoDir` to `output` (relative to it) with `flags`, unless nothing it depends on
+ * changed since the last render there: index.html, every asset (by size and mtime), the
+ * flags and the pinned HyperFrames version. Returns 'rendered' | 'unchanged' | 'failed'.
+ */
+export function renderIfChanged(videoDir, output, flags, force = false, composition = 'index.html') {
+    const target = resolve(videoDir, output);
+    const stamp = `${target}.key`;
+    const key = renderKey(videoDir, [...flags, output], composition);
+    if (!force && existsSync(target) && existsSync(stamp) && readFileSync(stamp, 'utf8') === key) {
+        return 'unchanged';
+    }
+    const which = composition === 'index.html' ? [] : ['-c', composition];
+    if (hyperframes(['render', '.', ...which, ...flags, '-o', output], videoDir) !== 0) {
+        return 'failed';
+    }
+    writeFileSync(stamp, key);
+    return 'rendered';
+}
+/** The README-sized GIF `render --gif` makes: width (px), frame rate and palette size. */
+export const GIF = { width: 720, fps: 12, colors: 128 };
+/**
+ * Converts a rendered MP4 (relative to `videoDir`) to `output` with ffmpeg — a palette made for this
+ * video, no dithering (it turns the soft backgrounds into noise and doubles the size). Skipped when the
+ * MP4 has not been re-rendered since (its .key is unchanged). HyperFrames' own GIF encoder is not used:
+ * it fails with ffmpeg 7.0 and renders every frame a second time.
+ */
+export function gifIfChanged(videoDir, source, output, force = false) {
+    const target = resolve(videoDir, output);
+    const stamp = `${target}.key`;
+    const sourceKey = resolve(videoDir, `${source}.key`);
+    const key = createHash('sha1')
+        .update(existsSync(sourceKey) ? readFileSync(sourceKey) : String(statSync(resolve(videoDir, source)).mtimeMs))
+        .update(JSON.stringify(GIF))
+        .digest('hex');
+    if (!force && existsSync(target) && existsSync(stamp) && readFileSync(stamp, 'utf8') === key) {
+        return 'unchanged';
+    }
+    const filter = `fps=${GIF.fps},scale=${GIF.width}:-2:flags=lanczos,split[a][b];` +
+        `[a]palettegen=stats_mode=diff:max_colors=${GIF.colors}[p];[b][p]paletteuse=dither=none:diff_mode=rectangle`;
+    const run = spawnSync('ffmpeg', ['-y', '-loglevel', 'error', '-i', resolve(videoDir, source), '-vf', filter, '-loop', '0', target], {
+        stdio: 'inherit',
+    });
+    if (run.status !== 0) {
+        return 'failed';
+    }
+    writeFileSync(stamp, key);
+    return 'rendered';
+}
+export function renderKey(videoDir, args, composition = 'index.html') {
+    const hash = createHash('sha1').update(HYPERFRAMES_VERSION).update(JSON.stringify(args));
+    hash.update(readFileSync(resolve(videoDir, composition)));
+    const walk = (dir) => {
+        for (const entry of readdirSync(dir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+            const path = resolve(dir, entry.name);
+            if (entry.isDirectory()) {
+                walk(path);
+            }
+            else if (!entry.name.endsWith('.key')) {
+                const { size, mtimeMs } = statSync(path);
+                hash.update(`${path}:${size}:${mtimeMs}\n`);
+            }
+        }
+    };
+    if (existsSync(resolve(videoDir, 'assets'))) {
+        walk(resolve(videoDir, 'assets'));
+    }
+    return hash.digest('hex');
+}
+let dist = null;
+/**
+ * The pinned HyperFrames package's dist/ (player + runtime), from the npx cache.
+ * The studio serves both from here, so the preview works offline.
+ */
+export function hyperframesDist() {
+    if (dist) {
+        return dist;
+    }
+    const which = spawnSync('npm', ['exec', '--yes', `--package=hyperframes@${HYPERFRAMES_VERSION}`, '-c', 'which hyperframes'], {
+        encoding: 'utf8',
+    });
+    const bin = which.stdout.trim().split('\n').at(-1);
+    if (which.status !== 0 || !bin) {
+        throw new Error(`could not install hyperframes@${HYPERFRAMES_VERSION}: ${which.stderr.trim()}`);
+    }
+    dist = resolve(dirname(realpathSync(bin)), '..', 'dist');
+    if (!existsSync(resolve(dist, 'hyperframes-player.global.js'))) {
+        throw new Error(`no HyperFrames player in ${dist}`);
+    }
+    return dist;
+}