videowright 0.1.0

package/dist/timeline/loadVoiceover.js

@@ -0,0 +1,38 @@
+/**
+ * Load a voiceover module from disk.
+ *
+ * Resolves the voiceover.ts file via the shared ts-loader, then
+ * resolves audio_file and provider_timing_file to absolute paths.
+ */
+import { existsSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { UserError } from "../cli/errors.js";
+import { loadModule } from "../cli/ts_loader.js";
+export async function loadVoiceover(args) {
+    const { videoFolder, slug } = args;
+    const voiceoverPath = resolve(videoFolder, "audio", "originals", "voiceovers", slug, "voiceover.ts");
+    if (!existsSync(voiceoverPath)) {
+        throw new UserError(`Voiceover not found: ${voiceoverPath}`, `Check that audio/originals/voiceovers/${slug}/voiceover.ts exists in your video folder.`);
+    }
+    const mod = await loadModule(voiceoverPath);
+    const voiceover = mod.default;
+    if (!voiceover || typeof voiceover !== "object" || !voiceover.audio_file) {
+        throw new UserError(`Invalid voiceover module at ${voiceoverPath}`, "The voiceover.ts file must default-export a Voiceover object with at least an audio_file field.");
+    }
+    const voiceoverFolder = dirname(voiceoverPath);
+    const audioFilePath = resolve(voiceoverFolder, voiceover.audio_file);
+    if (!existsSync(audioFilePath)) {
+        throw new UserError(`Voiceover audio file not found: ${audioFilePath}`, `The audio_file "${voiceover.audio_file}" referenced in ${voiceoverPath} does not exist.`);
+    }
+    // Rewrite audio_file to an absolute path so callers can resolve it
+    // without knowing the source folder.
+    const resolvedVoiceover = {
+        ...voiceover,
+        audio_file: audioFilePath,
+        provider_timing_file: voiceover.provider_timing_file
+            ? resolve(voiceoverFolder, voiceover.provider_timing_file)
+            : undefined,
+    };
+    return { voiceover: resolvedVoiceover, voiceoverFolder, audioFilePath };
+}
+//# sourceMappingURL=loadVoiceover.js.map

package/dist/timeline/loadVoiceover.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"loadVoiceover.js","sourceRoot":"","sources":["../../src/timeline/loadVoiceover.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAC7C,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC7C,OAAO,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAcjD,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,IAAuB;IAC1D,MAAM,EAAE,WAAW,EAAE,IAAI,EAAE,GAAG,IAAI,CAAC;IAEnC,MAAM,aAAa,GAAG,OAAO,CAC5B,WAAW,EACX,OAAO,EACP,WAAW,EACX,YAAY,EACZ,IAAI,EACJ,cAAc,CACd,CAAC;IACF,IAAI,CAAC,UAAU,CAAC,aAAa,CAAC,EAAE,CAAC;QAChC,MAAM,IAAI,SAAS,CAClB,wBAAwB,aAAa,EAAE,EACvC,yCAAyC,IAAI,4CAA4C,CACzF,CAAC;IACH,CAAC;IAED,MAAM,GAAG,GAAG,MAAM,UAAU,CAAC,aAAa,CAAC,CAAC;IAC5C,MAAM,SAAS,GAAG,GAAG,CAAC,OAAoB,CAAC;IAE3C,IAAI,CAAC,SAAS,IAAI,OAAO,SAAS,KAAK,QAAQ,IAAI,CAAC,SAAS,CAAC,UAAU,EAAE,CAAC;QAC1E,MAAM,IAAI,SAAS,CAClB,+BAA+B,aAAa,EAAE,EAC9C,iGAAiG,CACjG,CAAC;IACH,CAAC;IAED,MAAM,eAAe,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;IAC/C,MAAM,aAAa,GAAG,OAAO,CAAC,eAAe,EAAE,SAAS,CAAC,UAAU,CAAC,CAAC;IAErE,IAAI,CAAC,UAAU,CAAC,aAAa,CAAC,EAAE,CAAC;QAChC,MAAM,IAAI,SAAS,CAClB,mCAAmC,aAAa,EAAE,EAClD,mBAAmB,SAAS,CAAC,UAAU,mBAAmB,aAAa,kBAAkB,CACzF,CAAC;IACH,CAAC;IAED,mEAAmE;IACnE,qCAAqC;IACrC,MAAM,iBAAiB,GAAc;QACpC,GAAG,SAAS;QACZ,UAAU,EAAE,aAAa;QACzB,oBAAoB,EAAE,SAAS,CAAC,oBAAoB;YACnD,CAAC,CAAC,OAAO,CAAC,eAAe,EAAE,SAAS,CAAC,oBAAoB,CAAC;YAC1D,CAAC,CAAC,SAAS;KACZ,CAAC;IAEF,OAAO,EAAE,SAAS,EAAE,iBAAiB,EAAE,eAAe,EAAE,aAAa,EAAE,CAAC;AACzE,CAAC"}

package/dist/timeline/resolveTiming.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Resolve the active timing for a playback or render session.
+ *
+ * Implements the four-level precedence described in the architecture doc:
+ *   1. CLI audio track (explicit --audio-track <id>)
+ *   2. default_audio_track from timeline.ts
+ *   3. default_timing from timeline.ts
+ *   4. Per-segment SegmentSpec.advances
+ *
+ * --audio-track none suppresses levels 1 and 2 but preserves level 3.
+ */
+import type { AudioTrack, SegmentSpec, Timing } from "../types.js";
+/** Minimal segment shape needed for timing resolution (id + advances). */
+export type TimingSegment = Pick<SegmentSpec, "id" | "advances">;
+export type ResolvedTiming = {
+    source: "audio_track" | "default_timing" | "segments";
+    audioTrack?: AudioTrack;
+    perSegment: Record<string, number[]>;
+};
+export interface ResolveTimingArgs {
+    segments: TimingSegment[];
+    defaultTiming?: Timing;
+    defaultAudioTrack?: AudioTrack;
+    cliAudioTrackId?: string | "none";
+    cliAudioTrackModule?: AudioTrack;
+}
+export declare function resolveTiming(args: ResolveTimingArgs): ResolvedTiming;
+//# sourceMappingURL=resolveTiming.d.ts.map

package/dist/timeline/resolveTiming.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolveTiming.d.ts","sourceRoot":"","sources":["../../src/timeline/resolveTiming.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAEnE,0EAA0E;AAC1E,MAAM,MAAM,aAAa,GAAG,IAAI,CAAC,WAAW,EAAE,IAAI,GAAG,UAAU,CAAC,CAAC;AAEjE,MAAM,MAAM,cAAc,GAAG;IAC5B,MAAM,EAAE,aAAa,GAAG,gBAAgB,GAAG,UAAU,CAAC;IACtD,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;CACrC,CAAC;AAEF,MAAM,WAAW,iBAAiB;IACjC,QAAQ,EAAE,aAAa,EAAE,CAAC;IAC1B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,iBAAiB,CAAC,EAAE,UAAU,CAAC;IAC/B,eAAe,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAClC,mBAAmB,CAAC,EAAE,UAAU,CAAC;CACjC;AAED,wBAAgB,aAAa,CAAC,IAAI,EAAE,iBAAiB,GAAG,cAAc,CA2CrE"}

package/dist/timeline/resolveTiming.js

@@ -0,0 +1,63 @@
+/**
+ * Resolve the active timing for a playback or render session.
+ *
+ * Implements the four-level precedence described in the architecture doc:
+ *   1. CLI audio track (explicit --audio-track <id>)
+ *   2. default_audio_track from timeline.ts
+ *   3. default_timing from timeline.ts
+ *   4. Per-segment SegmentSpec.advances
+ *
+ * --audio-track none suppresses levels 1 and 2 but preserves level 3.
+ */
+export function resolveTiming(args) {
+    const { segments, defaultTiming, defaultAudioTrack, cliAudioTrackId, cliAudioTrackModule } = args;
+    // Build base from segment advances
+    const base = {};
+    for (const seg of segments) {
+        base[seg.id] = seg.advances;
+    }
+    // Determine the active timing source
+    const isNone = cliAudioTrackId === "none";
+    // Level 1: explicit CLI audio track
+    if (!isNone && cliAudioTrackModule) {
+        return {
+            source: "audio_track",
+            audioTrack: cliAudioTrackModule,
+            perSegment: overlayTiming(base, cliAudioTrackModule.timing),
+        };
+    }
+    // Level 2: default audio track from timeline
+    if (!isNone && defaultAudioTrack) {
+        return {
+            source: "audio_track",
+            audioTrack: defaultAudioTrack,
+            perSegment: overlayTiming(base, defaultAudioTrack.timing),
+        };
+    }
+    // Level 3: default timing
+    if (defaultTiming) {
+        return {
+            source: "default_timing",
+            perSegment: overlayTiming(base, defaultTiming),
+        };
+    }
+    // Level 4: segment advances only
+    return {
+        source: "segments",
+        perSegment: base,
+    };
+}
+/**
+ * Overlay a Timing's perSegment entries on top of a base record.
+ * Segments present in the Timing win; absent segments keep their base value.
+ */
+function overlayTiming(base, timing) {
+    const result = { ...base };
+    for (const [segId, advances] of Object.entries(timing.perSegment)) {
+        if (advances) {
+            result[segId] = advances;
+        }
+    }
+    return result;
+}
+//# sourceMappingURL=resolveTiming.js.map

package/dist/timeline/resolveTiming.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolveTiming.js","sourceRoot":"","sources":["../../src/timeline/resolveTiming.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAqBH,MAAM,UAAU,aAAa,CAAC,IAAuB;IACpD,MAAM,EAAE,QAAQ,EAAE,aAAa,EAAE,iBAAiB,EAAE,eAAe,EAAE,mBAAmB,EAAE,GAAG,IAAI,CAAC;IAElG,mCAAmC;IACnC,MAAM,IAAI,GAA6B,EAAE,CAAC;IAC1C,KAAK,MAAM,GAAG,IAAI,QAAQ,EAAE,CAAC;QAC5B,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,GAAG,CAAC,QAAQ,CAAC;IAC7B,CAAC;IAED,qCAAqC;IACrC,MAAM,MAAM,GAAG,eAAe,KAAK,MAAM,CAAC;IAE1C,oCAAoC;IACpC,IAAI,CAAC,MAAM,IAAI,mBAAmB,EAAE,CAAC;QACpC,OAAO;YACN,MAAM,EAAE,aAAa;YACrB,UAAU,EAAE,mBAAmB;YAC/B,UAAU,EAAE,aAAa,CAAC,IAAI,EAAE,mBAAmB,CAAC,MAAM,CAAC;SAC3D,CAAC;IACH,CAAC;IAED,6CAA6C;IAC7C,IAAI,CAAC,MAAM,IAAI,iBAAiB,EAAE,CAAC;QAClC,OAAO;YACN,MAAM,EAAE,aAAa;YACrB,UAAU,EAAE,iBAAiB;YAC7B,UAAU,EAAE,aAAa,CAAC,IAAI,EAAE,iBAAiB,CAAC,MAAM,CAAC;SACzD,CAAC;IACH,CAAC;IAED,0BAA0B;IAC1B,IAAI,aAAa,EAAE,CAAC;QACnB,OAAO;YACN,MAAM,EAAE,gBAAgB;YACxB,UAAU,EAAE,aAAa,CAAC,IAAI,EAAE,aAAa,CAAC;SAC9C,CAAC;IACH,CAAC;IAED,iCAAiC;IACjC,OAAO;QACN,MAAM,EAAE,UAAU;QAClB,UAAU,EAAE,IAAI;KAChB,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,SAAS,aAAa,CAAC,IAA8B,EAAE,MAAc;IACpE,MAAM,MAAM,GAAG,EAAE,GAAG,IAAI,EAAE,CAAC;IAC3B,KAAK,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,UAAU,CAAC,EAAE,CAAC;QACnE,IAAI,QAAQ,EAAE,CAAC;YACd,MAAM,CAAC,KAAK,CAAC,GAAG,QAAQ,CAAC;QAC1B,CAAC;IACF,CAAC;IACD,OAAO,MAAM,CAAC;AACf,CAAC"}

package/dist/timeline/validateTiming.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Validation for Timing and Voiceover objects.
+ *
+ * Called at CLI startup after loading timeline / voiceover modules.
+ * Errors block execution; warnings are printed but do not block.
+ */
+import type { AudioTrack, Timing } from "../types.js";
+export type ValidationResult = {
+    ok: true;
+    warnings: string[];
+} | {
+    ok: false;
+    errors: string[];
+    warnings: string[];
+};
+/**
+ * Validate a Timing object against known segment ids.
+ *
+ * - Warns on segment ids in `perSegment` that are not in `segmentIds`.
+ * - Errors on non-array values, empty arrays, non-positive numbers, or non-finite numbers.
+ */
+export declare function validateTiming(timing: Timing, segmentIds: string[]): ValidationResult;
+/**
+ * Validate an AudioTrack object's file references.
+ *
+ * - Errors if `audio_file` does not exist on disk.
+ */
+export declare function validateAudioTrack(audioTrack: AudioTrack, videoFolder: string): ValidationResult;
+//# sourceMappingURL=validateTiming.d.ts.map

package/dist/timeline/validateTiming.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validateTiming.d.ts","sourceRoot":"","sources":["../../src/timeline/validateTiming.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAEtD,MAAM,MAAM,gBAAgB,GACzB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,EAAE,MAAM,EAAE,CAAA;CAAE,GAChC;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,EAAE,CAAC;IAAC,QAAQ,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC;AAEvD;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,GAAG,gBAAgB,CAsCrF;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,GAAG,gBAAgB,CAahG"}

package/dist/timeline/validateTiming.js

@@ -0,0 +1,62 @@
+/**
+ * Validation for Timing and Voiceover objects.
+ *
+ * Called at CLI startup after loading timeline / voiceover modules.
+ * Errors block execution; warnings are printed but do not block.
+ */
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+/**
+ * Validate a Timing object against known segment ids.
+ *
+ * - Warns on segment ids in `perSegment` that are not in `segmentIds`.
+ * - Errors on non-array values, empty arrays, non-positive numbers, or non-finite numbers.
+ */
+export function validateTiming(timing, segmentIds) {
+    const errors = [];
+    const warnings = [];
+    const knownIds = new Set(segmentIds);
+    for (const [segId, advances] of Object.entries(timing.perSegment)) {
+        if (!knownIds.has(segId)) {
+            warnings.push(`Timing references unknown segment "${segId}" -- possible typo or renamed segment.`);
+        }
+        if (!advances)
+            continue;
+        if (!Array.isArray(advances)) {
+            errors.push(`Timing for segment "${segId}": expected an array of numbers.`);
+            continue;
+        }
+        if (advances.length === 0) {
+            errors.push(`Timing for segment "${segId}": advances array must not be empty.`);
+            continue;
+        }
+        for (let i = 0; i < advances.length; i++) {
+            const v = advances[i];
+            if (typeof v !== "number" || !Number.isFinite(v) || v <= 0) {
+                errors.push(`Timing for segment "${segId}": advances[${i}] must be a positive finite number (got ${v}).`);
+            }
+        }
+    }
+    if (errors.length > 0) {
+        return { ok: false, errors, warnings };
+    }
+    return { ok: true, warnings };
+}
+/**
+ * Validate an AudioTrack object's file references.
+ *
+ * - Errors if `audio_file` does not exist on disk.
+ */
+export function validateAudioTrack(audioTrack, videoFolder) {
+    const errors = [];
+    const warnings = [];
+    const audioPath = resolve(videoFolder, audioTrack.audio_file);
+    if (!existsSync(audioPath)) {
+        errors.push(`Audio track file not found: ${audioPath}`);
+    }
+    if (errors.length > 0) {
+        return { ok: false, errors, warnings };
+    }
+    return { ok: true, warnings };
+}
+//# sourceMappingURL=validateTiming.js.map

package/dist/timeline/validateTiming.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validateTiming.js","sourceRoot":"","sources":["../../src/timeline/validateTiming.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAOpC;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAAC,MAAc,EAAE,UAAoB;IAClE,MAAM,MAAM,GAAa,EAAE,CAAC;IAC5B,MAAM,QAAQ,GAAa,EAAE,CAAC;IAC9B,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAC,UAAU,CAAC,CAAC;IAErC,KAAK,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,UAAU,CAAC,EAAE,CAAC;QACnE,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC;YAC1B,QAAQ,CAAC,IAAI,CACZ,sCAAsC,KAAK,wCAAwC,CACnF,CAAC;QACH,CAAC;QAED,IAAI,CAAC,QAAQ;YAAE,SAAS;QAExB,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAC;YAC9B,MAAM,CAAC,IAAI,CAAC,uBAAuB,KAAK,kCAAkC,CAAC,CAAC;YAC5E,SAAS;QACV,CAAC;QAED,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC3B,MAAM,CAAC,IAAI,CAAC,uBAAuB,KAAK,sCAAsC,CAAC,CAAC;YAChF,SAAS;QACV,CAAC;QAED,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,QAAQ,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YAC1C,MAAM,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC;YACtB,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;gBAC5D,MAAM,CAAC,IAAI,CACV,uBAAuB,KAAK,eAAe,CAAC,2CAA2C,CAAC,IAAI,CAC5F,CAAC;YACH,CAAC;QACF,CAAC;IACF,CAAC;IAED,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACvB,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC;IACxC,CAAC;IACD,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;AAC/B,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,kBAAkB,CAAC,UAAsB,EAAE,WAAmB;IAC7E,MAAM,MAAM,GAAa,EAAE,CAAC;IAC5B,MAAM,QAAQ,GAAa,EAAE,CAAC;IAE9B,MAAM,SAAS,GAAG,OAAO,CAAC,WAAW,EAAE,UAAU,CAAC,UAAU,CAAC,CAAC;IAC9D,IAAI,CAAC,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC;QAC5B,MAAM,CAAC,IAAI,CAAC,+BAA+B,SAAS,EAAE,CAAC,CAAC;IACzD,CAAC;IAED,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACvB,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC;IACxC,CAAC;IACD,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;AAC/B,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,216 @@
+/**
+ * Public types for the Videowright library.
+ */
+export declare const SEGMENT_BRAND: unique symbol;
+/** Runtime context passed to segment lifecycle methods. */
+export interface PlayerContext {
+    /** Pauses play() until the next user advance (interactive) or scheduled beat (render). */
+    waitForNext(): Promise<void>;
+    /** Pauses play() for the given duration in milliseconds. */
+    hold(ms: number): Promise<void>;
+    /** Aborted when the segment is unmounted. */
+    signal: AbortSignal;
+    /** Current player mode. */
+    mode: "interactive" | "render";
+    /** Milliseconds since this segment instance was mounted. */
+    clock(): number;
+}
+/** User-facing spec passed to defineSegment. */
+export interface SegmentSpec {
+    /** Unique id matching the segment's folder name under segments/. */
+    id: string;
+    /**
+     * Segment-relative seconds at which to fire each 'next' advance during render.
+     * Must be monotonically increasing. All values must be positive numbers.
+     *
+     * Length = number of triggerNext() calls required to traverse this segment, INCLUDING
+     * the final press that transitions to the next segment.
+     *
+     * Examples:
+     * - `play() { await ctx.hold(3000); }` -> 1 press total -> `advances: [3.0]`
+     * - `play() { await ctx.waitForNext(); }` -> 2 presses -> `advances: [t1, t2]`
+     * - `play() { await ctx.waitForNext(); await ctx.waitForNext(); }` -> 3 presses -> `advances: [t1, t2, t3]`
+     *
+     * Ignored in dev (interactive) mode -- interactive presses drive timing.
+     * REQUIRED on every segment.
+     */
+    advances: number[];
+    /** Voiceover text for this segment (used by script() helper and HUD). */
+    voiceover?: string;
+    /** Freeform notes (not rendered). */
+    notes?: string;
+    /** Called when the player gives the segment its host element. Optional. */
+    mount?(el: HTMLElement, ctx: PlayerContext): void | Promise<void>;
+    /** Main animation/content logic. Required. */
+    play(ctx: PlayerContext): Promise<void>;
+    /** Called when the segment is removed. Optional. */
+    unmount?(): void;
+    /** Override default next behavior. Return true to consume the press. */
+    next?(): boolean;
+    /** Override default prev behavior. Return true to consume the press. */
+    prev?(): boolean;
+}
+/** A validated segment object returned by defineSegment. */
+export interface Segment extends SegmentSpec {
+    readonly [SEGMENT_BRAND]: true;
+}
+/** A single entry in a timeline's segments array. */
+export interface TimelineEntry {
+    /** Segment id to resolve (maps to segments/<id>/index.ts). */
+    id: string;
+    /** Transition to use when entering this segment. String name or configured object. */
+    transition?: string | {
+        type: string;
+        [k: string]: unknown;
+    };
+}
+/** Timeline-level metadata. */
+export interface TimelineMeta {
+    /** Video title (required). */
+    title: string;
+    /** Style slug for this video. Falls back to config defaultStyle. */
+    style?: string;
+    /** Aspect ratio string, e.g. '16:9'. Falls back to config default. */
+    aspectRatio?: string;
+    /** Resolution as [width, height]. Falls back to config default. */
+    resolution?: [number, number];
+    /** Frames per second. Falls back to config default. */
+    fps?: number;
+}
+/** TimelineMeta after applyMetaDefaults has filled in resolution, fps, and aspectRatio. */
+export type ResolvedTimelineMeta = TimelineMeta & Required<Pick<TimelineMeta, "resolution" | "fps" | "aspectRatio">>;
+/** A complete timeline definition (default export of a timeline.ts file). */
+export interface Timeline {
+    meta: TimelineMeta;
+    segments: TimelineEntry[];
+    /** Standalone timing overrides (used when no audio track is active). */
+    default_timing?: Timing;
+    /** Default audio track for this video. */
+    default_audio_track?: AudioTrack;
+}
+/**
+ * Per-segment advance schedule overrides. Used by voiceovers and as a
+ * standalone timing layer (`default_timing` on Timeline).
+ *
+ * Keys are segment ids; values are advance times in seconds (same units as
+ * SegmentSpec.advances). A Timing only needs to specify segments it wants
+ * to override -- unspecified segments fall back to their own `advances`.
+ */
+export type Timing = {
+    perSegment: Partial<Record<string, number[]>>;
+};
+/**
+ * A single voiceover for a video. Stored at
+ * `videos/<video>/audio/originals/voiceovers/<slug>/voiceover.ts`.
+ */
+export type Voiceover = {
+    /**
+     * Audio file path, relative to the voiceover.ts file's directory (e.g.,
+     * `"./audio.mp3"`). After loading via `loadVoiceover()`, rewritten to an
+     * absolute path.
+     *
+     * Note: this differs from `AudioTrack.audio_file` which is relative to
+     * the video folder. The difference exists because voiceover modules are
+     * loaded by `loadVoiceover()` which knows the voiceover.ts location,
+     * while audio tracks are imported into timeline.ts and resolved from the
+     * video folder by render.ts.
+     */
+    audio_file: string;
+    /** Provider that produced the audio. */
+    provider: "elevenlabs" | "manual";
+    /**
+     * Provider timing JSON path. Same resolution rules as `audio_file`:
+     * relative to voiceover.ts directory on disk, absolute after
+     * `loadVoiceover()`.
+     */
+    provider_timing_file?: string;
+    /** Per-segment advance timing synced to this audio. */
+    timing: Timing;
+    /** Freeform notes about this voiceover. */
+    notes?: string;
+    /**
+     * ElevenLabs voice ID for this voiceover. Used by the API flow to select
+     * the voice for TTS generation. When omitted, defaults to Asher
+     * (`tMvyQtpCVQ0DkixuYm6J`). Ignored when provider is "manual".
+     */
+    eleven_labs_voice_id?: string;
+};
+/**
+ * A rendered audio track for a video. Stored at
+ * `videos/<video>/audio/tracks/<id>/track.ts`.
+ *
+ * Combines voice-over, SFX, and music into a single rendered audio file.
+ * The timeline references the active track via `default_audio_track`.
+ */
+export type AudioTrack = {
+    /**
+     * Path to the rendered audio file, relative to the video folder (the
+     * directory containing timeline.ts). Both loadAudioTrack() and the
+     * default_audio_track import path resolve this from the video folder.
+     * loadAudioTrack() rewrites it to an absolute path on return.
+     */
+    audio_file: string;
+    /** Length of the rendered audio in seconds. */
+    length_s: number;
+    /**
+     * Per-segment advance timing synced to this audio track. Computed by the
+     * sync-to-audio skill from the plan_snapshot + per-cue VO timing.json files.
+     * Same shape and semantics as Voiceover.timing.
+     */
+    timing: Timing;
+    /** Path to the audio plan that produced this track (relative to track.ts). */
+    audio_plan_path?: string;
+    /** Path to the point-in-time plan snapshot for this track (relative to track.ts). */
+    plan_snapshot_path?: string;
+    /** ISO timestamp when this track was rendered. */
+    created_at?: string;
+    /** Freeform notes about this track. */
+    notes?: string;
+};
+/** Context passed to transition functions. */
+export interface TransitionContext {
+    direction: "forward" | "backward";
+    duration?: number;
+}
+/** A transition function that animates between two slot elements. */
+export type Transition = (outgoing: HTMLElement, incoming: HTMLElement, ctx: TransitionContext) => Promise<void>;
+/** Summary of a single video for the homepage and routing. */
+export interface VideoSummary {
+    /** Directory name under videos/ -- also the URL slug. */
+    slug: string;
+    /** Absolute path to videos/<slug>/timeline.ts. */
+    timelinePath: string;
+    /** meta.title from the timeline. Falls back to slug if load failed. */
+    title: string;
+    /** Resolved style: meta.style ?? config.defaultStyle ?? "unknown". */
+    style: string;
+    /** mtime of timeline.ts (epoch ms). Used for sort order. */
+    mtimeMs: number;
+    /** Error message if loading the timeline threw. */
+    loadError?: string;
+}
+/** Project-level info exposed to the browser via a virtual module. */
+export interface ProjectInfo {
+    /** Basename of cwd. Shown in the top bar. */
+    projectName: string;
+    /** Videos sorted by mtime descending. */
+    videos: VideoSummary[];
+}
+/** Repo-wide configuration from videowright.config.ts. */
+export interface Config {
+    /** Setup marker; bumped when layout changes. */
+    projectStructure: "v1";
+    /** Slug of the default style in styles/<slug>/. Required after setup. */
+    defaultStyle?: string;
+    /** Default values for timeline meta fields. */
+    defaults?: {
+        resolution?: [number, number];
+        fps?: number;
+        aspectRatio?: string;
+    };
+    /** Custom transition loaders keyed by name. */
+    transitions?: Record<string, () => Promise<{
+        default: Transition;
+    }>>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,6 @@
+/**
+ * Public types for the Videowright library.
+ */
+// ---- Segment brand ----
+export const SEGMENT_BRAND = Symbol.for("videowright.segment");
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,0BAA0B;AAE1B,MAAM,CAAC,MAAM,aAAa,GAAkB,MAAM,CAAC,GAAG,CAAC,qBAAqB,CAAC,CAAC"}

package/package.json

@@ -0,0 +1,47 @@
+{
+	"name": "videowright",
+	"version": "0.1.0",
+	"type": "module",
+	"description": "Build animated explainer videos with your coding agent",
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/scosman/videowright.git"
+	},
+	"homepage": "https://github.com/scosman/videowright",
+	"bugs": {
+		"url": "https://github.com/scosman/videowright/issues"
+	},
+	"keywords": ["video", "animation", "explainer", "coding agent", "agentic coding"],
+	"bin": {
+		"videowright": "dist/cli/bin.js"
+	},
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.js"
+		},
+		"./cli": {
+			"types": "./dist/cli/index.d.ts",
+			"import": "./dist/cli/index.js"
+		}
+	},
+	"files": ["dist", "skill", "src/cli/entry"],
+	"scripts": {
+		"build": "tsc -b",
+		"test": "vitest run",
+		"test:watch": "vitest",
+		"test:e2e": "npm run build && npx playwright test"
+	},
+	"dependencies": {
+		"tsx": "^4.19.0",
+		"vite": "^6.3.5"
+	},
+	"devDependencies": {
+		"@playwright/test": "^1.59.1",
+		"@types/node": "^25.6.2",
+		"jsdom": "^29.1.1",
+		"vitest": "^3.1.3",
+		"yaml": "^2.8.4"
+	}
+}

package/skill/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: videowright
+description: Author HTML/CSS/JS animated explainer videos using Videowright. Trigger on requests to create a video, edit a segment, add or change a style, generate a VO script, run the dev server, or export.
+---
+
+# Videowright
+
+Videowright lets you author high-quality animated explainer videos in HTML/CSS/JS. Videos are composed from segments — self-contained TypeScript modules that own a DOM element and animate it. A `Timeline` orders segments with transitions, the dev server plays them interactively, and the render pipeline exports to MP4. The core authoring primitives are `defineSegment`, `defineConfig`, and the `Timeline` type.
+
+## When to trigger
+
+- "Make me a video about X"
+- "Add a segment to \<video\>"
+- "Edit the intro of \<video\>"
+- "Add a style" / "Change the default style"
+- "Match the look of \<past video\>"
+- "Generate a script for \<video\>"
+- "Add a voiceover" / "Generate a voiceover" / "Record a voiceover"
+- "Add sound effects" / "Add music" / "Add audio"
+- "Run the dev server" / "Preview the video"
+- "Export the video" / "Render the video"
+- "Write tests for \<video\>"
+- Any time `videowright.config.ts` is referenced or the user mentions Videowright
+
+## Setup gate
+
+Before doing any work, check `videowright.config.ts` at the repo root:
+
+- If the file **does not exist**, OR `defaultStyle` is missing or empty string: load [references/setup.md](references/setup.md) and follow it before continuing.
+- Otherwise: skip `setup.md`. Proceed with intent dispatch below.
+
+## Intent dispatch
+
+Read the user's request and route to the matching reference file:
+
+| Intent | Reference |
+|---|---|
+| First-time setup of a Videowright project | [references/setup.md](references/setup.md) |
+| New video | [references/new_video.md](references/new_video.md) |
+| Edit a video (add/remove/reorder segments, restyle, rewrite VO) | [references/create_or_edit_video.md](references/create_or_edit_video.md) |
+| Add a new style | [references/setup_new_style.md](references/setup_new_style.md) |
+| Change the default style | [references/styles.md](references/styles.md) |
+| Match a past video's style | [references/styles.md](references/styles.md) |
+| Generate or regenerate a VO script | [references/audio.md](references/audio.md) |
+| Add a voiceover (AI-generated or manual) | [references/audio.md](references/audio.md) |
+| Add sound effects or music | [references/audio.md](references/audio.md) |
+| Run or review the dev server | [references/dev_server.md](references/dev_server.md) |
+| Export the video | [references/export.md](references/export.md) |
+| Write tests | [references/testing.md](references/testing.md) |
+
+If the user's request does not map to a clear intent, ask one focused question listing the options above. Do not guess.
+
+## Core principles
+
+- **Use `defineSegment` always.** It is the canonical authoring path. It handles beat tracking, abort signals, and typing.
+- **Fill the frame.** Text and visual elements should be large, legible, and use the full video canvas — body text 36px+ at 1080p, headings 64px+, content containers spanning 80-90%+ of the video width. Avoid excessive margins, padding, or whitespace that shrinks content into a small portion of the frame. If text is too small to read comfortably at normal playback size, make it bigger or remove it. Small decorative labels are acceptable when intentional, but body text, headings, stats, and key visuals must dominate the frame. This is a video, not a web page — there is no scrolling, so every pixel of every frame matters.
+- **`waitForNext()` for audio-aligned beats; `hold(ms)` for pacing within a beat.** Use `ctx.waitForNext()` at every point where the video should sync to an audio track advance — this keeps timing decoupled from any single audio recording, so swapping audio tracks only requires new timing data, not re-authoring segments. Use `ctx.hold(ms)` for pauses that are internal to a beat (entrance animations, dwell time before the next interactive point). Do not bake audio-specific durations into `hold()` calls — that couples the segment to one recording and forces re-authoring to swap narration.
+- **Render-safety CR on every segment.** After writing or modifying a segment, review it against the render-safety checklist in [references/create_or_edit_video.md](references/create_or_edit_video.md) (Step 2b). This catches patterns that work in dev but may produce suboptimal results in render (e.g., hold-driven mutation loops where WAAPI would give smoother interpolation).
+- **No `duration` field on segments.** There is no duration property — the segment decides when it is done via its `play()` function.
+- **Any web tech is welcome inside segments.** Three.js, Lottie, animated SVG, shadcn/React, GSAP, echarts — all encouraged. The segment owns its DOM; attach a shadow root if isolation is wanted.
+- **PLAN.md is the working memory.** Read it before iterating on a video; append after meaningful changes. Never delete log entries.
+- **Reuse, don't copy.** Top-level `segments/`, `components/`, `transitions/` are shared across all videos. Any video can use any segment. Don't duplicate.
+- **Audio-first authoring is the default for new videos with VO.** Write the script, then scaffold segments to match. This produces coherent videos.
+- **One-shot when the input is rich.** Never ask a question whose answer is already in the user's input. When the user provides a complete brief, draft the plan and confirm — don't interrogate.

package/skill/assets/hello_world/PLAN.md

@@ -0,0 +1,31 @@
+# Plan: Hello Videowright
+
+## Purpose
+- Audience: First-time Videowright users
+- Takeaway: See a working video end-to-end and understand the segment + timeline model
+- Constraints / hard guidelines: Keep it short (3 segments). Showcase style tokens and voiceover fields.
+
+## Style
+- Active style: editorial-mono
+- Notes: Uses Editorial Mono as a clean, content-first default. Swap to any other built-in pack or create your own.
+
+## Audio intent
+- Mode: silent
+- Notes: The template ships silent so first render is video-only. The `voiceover_script/script.md` and per-segment `voiceover` fields are pre-populated to demonstrate the script workflow; add audio by sourcing a VO and building a track under `audio/tracks/v1/`.
+
+## Segment outline
+1. hello-intro -- Title card with animated entrance
+2. editorial-mono-sample-kinetic -- Style showcase demonstrating kinetic typography
+3. hello-outro -- Closing card with call to action
+
+## Script (if applicable)
+see voiceover_script/script.md
+
+---
+
+## Log
+
+### YYYY-MM-DD -- Initial scaffold
+- Created via Videowright setup flow
+- 3 segments: intro, style sample, outro
+- Editorial Mono style applied via timeline.ts top-of-file import

package/skill/assets/hello_world/README.md

@@ -0,0 +1,27 @@
+# Hello Videowright
+
+A starter video created during Videowright setup.
+
+## Segments
+
+- **hello-intro** -- Title card with animated entrance
+- **editorial-mono-sample-kinetic** -- Kinetic typography showcase (from the Editorial Mono style pack)
+- **hello-outro** -- Closing card with call to action
+
+## Running
+
+```bash
+npx videowright dev
+```
+
+The dev server auto-discovers the most recent timeline. To target this video explicitly:
+
+```bash
+npx videowright dev videos/hello_videowright/timeline.ts
+```
+
+## Editing
+
+- Describe what you want to change and the agent will update segments, timelines, and styles for you
+- The dev server reloads automatically on file changes
+- See `PLAN.md` for the video's design and history