videowright 0.1.0

package/README.md

@@ -0,0 +1,91 @@
+# Videowright
+
+**Compose animated explainer videos using any web technology.**
+
+Videowright is a small library and agent skill for vibe-coding animated videos in HTML/CSS/JS. Inside each segment, use whatever the browser supports -- Three.js, Lottie, animated SVG, GSAP, React, CSS keyframes, ECharts, raw canvas. Videowright handles sequencing, transitions, and playback.
+
+## Install
+
+```bash
+npm install videowright
+```
+
+## Quick start
+
+Videowright is designed to work with a coding agent. Add the skill reference to your `.claude/CLAUDE.md`:
+
+```
+Read `node_modules/videowright/skill/SKILL.md` for the Videowright agent skill.
+```
+
+Then ask Claude to create a video. The skill scaffolds a project, writes segments, and guides iteration.
+
+### Manual usage
+
+```ts
+import { defineSegment } from 'videowright';
+
+let host: HTMLElement | null = null;
+
+export default defineSegment({
+  id: 'intro',
+  voiceover: 'Welcome to our product.',
+
+  mount(el, ctx) {
+    host = el;
+    el.innerHTML = '<h1 style="opacity:0">Hello</h1>';
+  },
+
+  async play(ctx) {
+    host!.querySelector('h1')!.animate(
+      [{ opacity: 0 }, { opacity: 1 }],
+      { duration: 500, fill: 'forwards' }
+    );
+    await ctx.hold(600);
+    await ctx.waitForNext();
+  },
+
+  unmount() {
+    host = null;
+  },
+});
+```
+
+Preview with hot reload:
+
+```bash
+npx videowright dev
+```
+
+## API
+
+| Export | Purpose |
+|---|---|
+| `defineSegment(spec)` | Author a segment with beat tracking and abort signal |
+| `defineConfig(config)` | Type-safe `videowright.config.ts` |
+| `script(timeline, segmentLoaders)` | Concatenate voiceover text into a Markdown document (async) |
+| `Player` | The player runtime |
+| `fade`, `slideLeft`, `slideRight`, `slideUp`, `slideDown`, `cut` | Built-in transitions |
+
+### Types
+
+`Segment`, `SegmentSpec`, `PlayerContext`, `Timeline`, `TimelineEntry`, `TimelineMeta`, `Transition`, `TransitionContext`, `Config`
+
+## CLI
+
+| Command | Description |
+|---|---|
+| `videowright dev [path]` | Open the player with hot reload |
+| `videowright script [path]` | Print the concatenated voiceover script (`--write` to save) |
+
+## Agent skill
+
+The npm package includes a Claude Code skill at `skill/SKILL.md`. It teaches the agent to scaffold projects, author segments, maintain style guides, and iterate on videos conversationally.
+
+## License
+
+[MIT](../../LICENSE). All runtime dependencies are MIT, ISC, or BSD-3-Clause.
+
+---
+
+Full documentation, architecture, and a 7-segment demo: [github.com/scosman/video_forge](https://github.com/scosman/video_forge)

package/dist/cli/argv.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Minimal argv parser wrapping node:util parseArgs.
+ * Extracts the subcommand from argv[2], then parses remaining flags.
+ */
+export type Command = "dev" | "script" | "render" | "help" | "version";
+export interface ParsedArgs {
+    command: Command;
+    positional?: string;
+    flags: {
+        port?: number;
+        write?: boolean;
+        verbose?: boolean;
+        width?: number;
+        height?: number;
+        fps?: number;
+        output?: string;
+        audioTrack?: string;
+    };
+}
+export declare class ArgvError extends Error {
+    name: string;
+}
+/**
+ * Parse process.argv (or a supplied argv array).
+ * Throws ArgvError on invalid input.
+ */
+export declare function parseArgv(argv?: string[]): ParsedArgs;
+//# sourceMappingURL=argv.d.ts.map

package/dist/cli/argv.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"argv.d.ts","sourceRoot":"","sources":["../../src/cli/argv.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,MAAM,MAAM,OAAO,GAAG,KAAK,GAAG,QAAQ,GAAG,QAAQ,GAAG,MAAM,GAAG,SAAS,CAAC;AAEvE,MAAM,WAAW,UAAU;IAC1B,OAAO,EAAE,OAAO,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE;QACN,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,KAAK,CAAC,EAAE,OAAO,CAAC;QAChB,OAAO,CAAC,EAAE,OAAO,CAAC;QAClB,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,GAAG,CAAC,EAAE,MAAM,CAAC;QACb,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,UAAU,CAAC,EAAE,MAAM,CAAC;KACpB,CAAC;CACF;AAWD,qBAAa,SAAU,SAAQ,KAAK;IAC1B,IAAI,SAAe;CAC5B;AAED;;;GAGG;AACH,wBAAgB,SAAS,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,GAAG,UAAU,CAgHrD"}

package/dist/cli/argv.js

@@ -0,0 +1,115 @@
+/**
+ * Minimal argv parser wrapping node:util parseArgs.
+ * Extracts the subcommand from argv[2], then parses remaining flags.
+ */
+import { parseArgs } from "node:util";
+const KNOWN_COMMANDS = new Set(["dev", "script", "render"]);
+/** Flags that only apply to the `render` command. Rejected on all other commands. */
+const RENDER_ONLY_FLAGS = ["width", "height", "fps", "output"];
+const RENDER_ONLY_COMMANDS = new Set(["render"]);
+/** Flags that apply to render. */
+const AUDIO_TRACK_COMMANDS = new Set(["render"]);
+export class ArgvError extends Error {
+    name = "ArgvError";
+}
+/**
+ * Parse process.argv (or a supplied argv array).
+ * Throws ArgvError on invalid input.
+ */
+export function parseArgv(argv) {
+    const raw = argv ?? process.argv.slice(2);
+    // Handle --help and --version anywhere
+    if (raw.includes("--help")) {
+        return { command: "help", flags: {} };
+    }
+    if (raw.includes("--version")) {
+        return { command: "version", flags: {} };
+    }
+    const subcommand = raw[0];
+    if (!subcommand) {
+        return { command: "help", flags: {} };
+    }
+    if (!KNOWN_COMMANDS.has(subcommand)) {
+        throw new ArgvError(`Unknown command: ${subcommand}`);
+    }
+    const remaining = raw.slice(1);
+    const { values, positionals } = parseArgs({
+        args: remaining,
+        options: {
+            port: { type: "string" },
+            write: { type: "boolean", default: false },
+            verbose: { type: "boolean", default: false },
+            width: { type: "string" },
+            height: { type: "string" },
+            fps: { type: "string" },
+            output: { type: "string" },
+            "audio-track": { type: "string" },
+        },
+        allowPositionals: true,
+        strict: true,
+    });
+    if (positionals.length > 1) {
+        throw new ArgvError(`Too many positional arguments for "${subcommand}": expected at most 1, got ${positionals.length}`);
+    }
+    const portStr = values.port;
+    let port;
+    if (portStr !== undefined) {
+        port = Number.parseInt(portStr, 10);
+        if (Number.isNaN(port) || port < 1 || port > 65535) {
+            throw new ArgvError(`Invalid port: ${portStr}`);
+        }
+    }
+    const widthStr = values.width;
+    let width;
+    if (widthStr !== undefined) {
+        width = Number.parseInt(widthStr, 10);
+        if (Number.isNaN(width) || width < 1 || width !== Number(widthStr)) {
+            throw new ArgvError(`Invalid width: ${widthStr} (must be a positive integer)`);
+        }
+    }
+    const heightStr = values.height;
+    let height;
+    if (heightStr !== undefined) {
+        height = Number.parseInt(heightStr, 10);
+        if (Number.isNaN(height) || height < 1 || height !== Number(heightStr)) {
+            throw new ArgvError(`Invalid height: ${heightStr} (must be a positive integer)`);
+        }
+    }
+    const fpsStr = values.fps;
+    let fps;
+    if (fpsStr !== undefined) {
+        fps = Number.parseInt(fpsStr, 10);
+        if (Number.isNaN(fps) || fps < 1 || fps > 120) {
+            throw new ArgvError(`Invalid fps: ${fpsStr}`);
+        }
+    }
+    const command = subcommand;
+    // Reject render-only flags on commands that don't support them
+    if (!RENDER_ONLY_COMMANDS.has(command)) {
+        for (const flag of RENDER_ONLY_FLAGS) {
+            if (values[flag] !== undefined) {
+                throw new ArgvError(`--${flag} is only valid for the "render" command`);
+            }
+        }
+    }
+    // Reject --audio-track on commands that don't support it
+    const audioTrack = values["audio-track"];
+    if (audioTrack !== undefined && !AUDIO_TRACK_COMMANDS.has(command)) {
+        throw new ArgvError(`--audio-track is only valid for the "render" command`);
+    }
+    return {
+        command,
+        positional: positionals[0],
+        flags: {
+            port,
+            write: values.write,
+            verbose: values.verbose,
+            width,
+            height,
+            fps,
+            output: values.output,
+            audioTrack,
+        },
+    };
+}
+//# sourceMappingURL=argv.js.map

package/dist/cli/argv.js.map

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

package/dist/cli/bin.d.ts

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+/**
+ * Binary entry point for the `videowright` CLI.
+ * Separated from index.ts so the module can be imported without auto-running.
+ */
+export {};
+//# sourceMappingURL=bin.d.ts.map

package/dist/cli/bin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bin.d.ts","sourceRoot":"","sources":["../../src/cli/bin.ts"],"names":[],"mappings":";AAEA;;;GAGG"}

package/dist/cli/bin.js

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+/**
+ * Binary entry point for the `videowright` CLI.
+ * Separated from index.ts so the module can be imported without auto-running.
+ */
+import { main } from "./index.js";
+main().then((code) => {
+    process.exitCode = code;
+});
+//# sourceMappingURL=bin.js.map

package/dist/cli/bin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bin.js","sourceRoot":"","sources":["../../src/cli/bin.ts"],"names":[],"mappings":";AAEA;;;GAGG;AAEH,OAAO,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAElC,IAAI,EAAE,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE;IACpB,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC;AACzB,CAAC,CAAC,CAAC"}

package/dist/cli/dev.d.ts

@@ -0,0 +1,19 @@
+/**
+ * `videowright dev` — boot a Vite dev server for the whole project.
+ * Discovers all videos at boot and exposes them via a virtual module.
+ */
+export interface DevOptions {
+    cwd: string;
+    port?: number;
+    verbose?: boolean;
+}
+export interface DevResult {
+    url: string;
+    close: () => Promise<void>;
+}
+/**
+ * Run the dev server flow. Returns the running server info.
+ * Throws UserError on missing config.
+ */
+export declare function runDev(opts: DevOptions): Promise<DevResult>;
+//# sourceMappingURL=dev.d.ts.map

package/dist/cli/dev.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dev.d.ts","sourceRoot":"","sources":["../../src/cli/dev.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAiBH,MAAM,WAAW,UAAU;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,SAAS;IACzB,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3B;AAED;;;GAGG;AACH,wBAAsB,MAAM,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,SAAS,CAAC,CAiHjE"}

package/dist/cli/dev.js

@@ -0,0 +1,104 @@
+/**
+ * `videowright dev` — boot a Vite dev server for the whole project.
+ * Discovers all videos at boot and exposes them via a virtual module.
+ */
+import { existsSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { findConfig } from "./discover.js";
+import { discoverAllVideos } from "./discover_project.js";
+import { UserError } from "./errors.js";
+import { findPackageRoot, fullReloadPlugin, globalsVirtualModulePlugin, projectVirtualModulePlugin, segmentDiscoveryPlugin, videoRouteMiddlewarePlugin, } from "./vite_helpers.js";
+/**
+ * Run the dev server flow. Returns the running server info.
+ * Throws UserError on missing config.
+ */
+export async function runDev(opts) {
+    const { cwd, port, verbose } = opts;
+    // Validate config exists (fast error before Vite boot)
+    const configPath = findConfig(cwd);
+    if (!configPath) {
+        throw new UserError(`No videowright.config.ts found at ${cwd}`, "The Videowright skill can scaffold one. Run setup first.");
+    }
+    if (verbose) {
+        console.log(`config: ${configPath}`);
+    }
+    const pkgRoot = findPackageRoot();
+    const entryDir = resolve(pkgRoot, "src/cli/entry");
+    if (!existsSync(resolve(entryDir, "index.html"))) {
+        throw new UserError("Internal entry HTML not found", "Reinstall videowright; this is a packaging bug.");
+    }
+    const serverPort = port ?? 5173;
+    // Discover all videos. Initial discovery uses plain import() since
+    // the Vite server isn't started yet. Reloads (triggered by file
+    // changes) use ssrLoadModule for reliable Vite-aware loading.
+    const projectInfo = await discoverAllVideos(cwd);
+    if (verbose) {
+        console.log(`videos discovered: ${projectInfo.videos.length}`);
+        for (const v of projectInfo.videos) {
+            console.log(`  ${v.slug}: "${v.title}" (${v.style})${v.loadError ? ` [error: ${v.loadError}]` : ""}`);
+        }
+    }
+    // Globals for the entry files. In multi-video mode, timelinePath is unused
+    // (video_view.ts reads per-video paths from ProjectInfo). It's still required
+    // by the VwGlobals interface because render_entry.ts uses it.
+    const globals = {
+        timelinePath: "",
+        consumerRoot: cwd,
+    };
+    // Mutable project info reference — the middleware reads the latest slugs
+    // each request so newly-added videos are immediately routable.
+    let currentProjectInfo = projectInfo;
+    const getKnownSlugs = () => currentProjectInfo.videos.map((v) => v.slug);
+    // We need a mutable reference to the server for the reload callback.
+    // The variable is assigned right after createServer returns, before any
+    // reload can fire.
+    let serverRef = null;
+    const { createServer } = await import("vite");
+    const server = await createServer({
+        configFile: false,
+        root: entryDir,
+        plugins: [
+            fullReloadPlugin(),
+            segmentDiscoveryPlugin(cwd),
+            globalsVirtualModulePlugin(globals),
+            videoRouteMiddlewarePlugin(getKnownSlugs),
+            projectVirtualModulePlugin(projectInfo, {
+                consumerRoot: cwd,
+                onReload: async () => {
+                    const info = await discoverAllVideos(cwd, serverRef ?? undefined);
+                    currentProjectInfo = info;
+                    return info;
+                },
+            }),
+        ],
+        build: {
+            rollupOptions: {
+                input: {
+                    index: join(entryDir, "index.html"),
+                    video: join(entryDir, "video.html"),
+                    render: join(entryDir, "render.html"),
+                },
+            },
+        },
+        server: {
+            port: serverPort,
+            strictPort: false,
+            fs: {
+                allow: [cwd, pkgRoot],
+            },
+        },
+        resolve: {
+            alias: {
+                "@consumer": cwd,
+            },
+        },
+    });
+    serverRef = server;
+    await server.listen();
+    const address = server.resolvedUrls?.local?.[0] ?? `http://localhost:${serverPort}/`;
+    return {
+        url: address,
+        close: () => server.close(),
+    };
+}
+//# sourceMappingURL=dev.js.map

package/dist/cli/dev.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dev.js","sourceRoot":"","sources":["../../src/cli/dev.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAC3C,OAAO,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAC1D,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAExC,OAAO,EACN,eAAe,EACf,gBAAgB,EAChB,0BAA0B,EAC1B,0BAA0B,EAC1B,sBAAsB,EACtB,0BAA0B,GAC1B,MAAM,mBAAmB,CAAC;AAa3B;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,MAAM,CAAC,IAAgB;IAC5C,MAAM,EAAE,GAAG,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;IAEpC,uDAAuD;IACvD,MAAM,UAAU,GAAG,UAAU,CAAC,GAAG,CAAC,CAAC;IACnC,IAAI,CAAC,UAAU,EAAE,CAAC;QACjB,MAAM,IAAI,SAAS,CAClB,qCAAqC,GAAG,EAAE,EAC1C,0DAA0D,CAC1D,CAAC;IACH,CAAC;IAED,IAAI,OAAO,EAAE,CAAC;QACb,OAAO,CAAC,GAAG,CAAC,WAAW,UAAU,EAAE,CAAC,CAAC;IACtC,CAAC;IAED,MAAM,OAAO,GAAG,eAAe,EAAE,CAAC;IAClC,MAAM,QAAQ,GAAG,OAAO,CAAC,OAAO,EAAE,eAAe,CAAC,CAAC;IAEnD,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,QAAQ,EAAE,YAAY,CAAC,CAAC,EAAE,CAAC;QAClD,MAAM,IAAI,SAAS,CAClB,+BAA+B,EAC/B,iDAAiD,CACjD,CAAC;IACH,CAAC;IAED,MAAM,UAAU,GAAG,IAAI,IAAI,IAAI,CAAC;IAEhC,mEAAmE;IACnE,gEAAgE;IAChE,8DAA8D;IAC9D,MAAM,WAAW,GAAG,MAAM,iBAAiB,CAAC,GAAG,CAAC,CAAC;IAEjD,IAAI,OAAO,EAAE,CAAC;QACb,OAAO,CAAC,GAAG,CAAC,sBAAsB,WAAW,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC;QAC/D,KAAK,MAAM,CAAC,IAAI,WAAW,CAAC,MAAM,EAAE,CAAC;YACpC,OAAO,CAAC,GAAG,CACV,KAAK,CAAC,CAAC,IAAI,MAAM,CAAC,CAAC,KAAK,MAAM,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,SAAS,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CACxF,CAAC;QACH,CAAC;IACF,CAAC;IAED,2EAA2E;IAC3E,8EAA8E;IAC9E,8DAA8D;IAC9D,MAAM,OAAO,GAAc;QAC1B,YAAY,EAAE,EAAE;QAChB,YAAY,EAAE,GAAG;KACjB,CAAC;IAEF,yEAAyE;IACzE,+DAA+D;IAC/D,IAAI,kBAAkB,GAAG,WAAW,CAAC;IAErC,MAAM,aAAa,GAAG,GAAG,EAAE,CAAC,kBAAkB,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;IAEzE,qEAAqE;IACrE,wEAAwE;IACxE,mBAAmB;IACnB,IAAI,SAAS,GAAmE,IAAI,CAAC;IAErF,MAAM,EAAE,YAAY,EAAE,GAAG,MAAM,MAAM,CAAC,MAAM,CAAC,CAAC;IAE9C,MAAM,MAAM,GAAG,MAAM,YAAY,CAAC;QACjC,UAAU,EAAE,KAAK;QACjB,IAAI,EAAE,QAAQ;QACd,OAAO,EAAE;YACR,gBAAgB,EAAE;YAClB,sBAAsB,CAAC,GAAG,CAAC;YAC3B,0BAA0B,CAAC,OAAO,CAAC;YACnC,0BAA0B,CAAC,aAAa,CAAC;YACzC,0BAA0B,CAAC,WAAW,EAAE;gBACvC,YAAY,EAAE,GAAG;gBACjB,QAAQ,EAAE,KAAK,IAAI,EAAE;oBACpB,MAAM,IAAI,GAAG,MAAM,iBAAiB,CAAC,GAAG,EAAE,SAAS,IAAI,SAAS,CAAC,CAAC;oBAClE,kBAAkB,GAAG,IAAI,CAAC;oBAC1B,OAAO,IAAI,CAAC;gBACb,CAAC;aACD,CAAC;SACF;QACD,KAAK,EAAE;YACN,aAAa,EAAE;gBACd,KAAK,EAAE;oBACN,KAAK,EAAE,IAAI,CAAC,QAAQ,EAAE,YAAY,CAAC;oBACnC,KAAK,EAAE,IAAI,CAAC,QAAQ,EAAE,YAAY,CAAC;oBACnC,MAAM,EAAE,IAAI,CAAC,QAAQ,EAAE,aAAa,CAAC;iBACrC;aACD;SACD;QACD,MAAM,EAAE;YACP,IAAI,EAAE,UAAU;YAChB,UAAU,EAAE,KAAK;YACjB,EAAE,EAAE;gBACH,KAAK,EAAE,CAAC,GAAG,EAAE,OAAO,CAAC;aACrB;SACD;QACD,OAAO,EAAE;YACR,KAAK,EAAE;gBACN,WAAW,EAAE,GAAG;aAChB;SACD;KACD,CAAC,CAAC;IAEH,SAAS,GAAG,MAAM,CAAC;IAEnB,MAAM,MAAM,CAAC,MAAM,EAAE,CAAC;IAEtB,MAAM,OAAO,GAAG,MAAM,CAAC,YAAY,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,IAAI,oBAAoB,UAAU,GAAG,CAAC;IAErF,OAAO;QACN,GAAG,EAAE,OAAO;QACZ,KAAK,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,KAAK,EAAE;KAC3B,CAAC;AACH,CAAC"}

package/dist/cli/discover.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Config and timeline discovery for the CLI.
+ */
+/**
+ * Look for videowright.config.ts at the given cwd.
+ * Returns the absolute path if found, null otherwise.
+ */
+export declare function findConfig(cwd: string): string | null;
+/**
+ * Discover all videos under <root>/videos/. Returns absolute timeline.ts paths.
+ * No sorting at this layer -- caller sorts.
+ */
+export declare function findAllTimelines(root: string): string[];
+/**
+ * Resolve a positional arg to a timeline path.
+ * - First tries it as a slug (videos/<arg>/timeline.ts exists).
+ * - Then tries it as a literal path (resolved relative to root).
+ * - Returns the absolute path if resolved, null if neither works.
+ */
+export declare function resolveSlugOrPath(arg: string, root: string): string | null;
+/**
+ * Find a timeline file.
+ * - If hint is provided, resolve relative to cwd. Returns absolute path if found.
+ *   Throws UserError if the explicit path does not exist.
+ * - If no hint, scan cwd/videos/.../timeline.ts, sort by mtime desc, return the most recent.
+ *   Returns null if no videos found (caller decides how to surface this).
+ */
+export declare function findTimeline(cwd: string, hint?: string): string | null;
+//# sourceMappingURL=discover.d.ts.map

package/dist/cli/discover.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"discover.d.ts","sourceRoot":"","sources":["../../src/cli/discover.ts"],"names":[],"mappings":"AAAA;;GAEG;AAMH;;;GAGG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAGrD;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAyBvD;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAc1E;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAoCtE"}

package/dist/cli/discover.js

@@ -0,0 +1,104 @@
+/**
+ * Config and timeline discovery for the CLI.
+ */
+import { existsSync, readdirSync, statSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { UserError } from "./errors.js";
+/**
+ * Look for videowright.config.ts at the given cwd.
+ * Returns the absolute path if found, null otherwise.
+ */
+export function findConfig(cwd) {
+    const configPath = join(cwd, "videowright.config.ts");
+    return existsSync(configPath) ? resolve(configPath) : null;
+}
+/**
+ * Discover all videos under <root>/videos/. Returns absolute timeline.ts paths.
+ * No sorting at this layer -- caller sorts.
+ */
+export function findAllTimelines(root) {
+    const videosDir = join(root, "videos");
+    if (!existsSync(videosDir))
+        return [];
+    let entries;
+    try {
+        entries = readdirSync(videosDir);
+    }
+    catch {
+        return [];
+    }
+    const paths = [];
+    for (const entry of entries) {
+        const entryPath = join(videosDir, entry);
+        try {
+            if (!statSync(entryPath).isDirectory())
+                continue;
+        }
+        catch {
+            continue;
+        }
+        const timelinePath = join(entryPath, "timeline.ts");
+        if (existsSync(timelinePath)) {
+            paths.push(resolve(timelinePath));
+        }
+    }
+    return paths;
+}
+/**
+ * Resolve a positional arg to a timeline path.
+ * - First tries it as a slug (videos/<arg>/timeline.ts exists).
+ * - Then tries it as a literal path (resolved relative to root).
+ * - Returns the absolute path if resolved, null if neither works.
+ */
+export function resolveSlugOrPath(arg, root) {
+    // Try as slug first
+    const slugPath = join(root, "videos", arg, "timeline.ts");
+    if (existsSync(slugPath)) {
+        return resolve(slugPath);
+    }
+    // Try as literal path
+    const literalPath = resolve(root, arg);
+    if (existsSync(literalPath)) {
+        return resolve(literalPath);
+    }
+    return null;
+}
+/**
+ * Find a timeline file.
+ * - If hint is provided, resolve relative to cwd. Returns absolute path if found.
+ *   Throws UserError if the explicit path does not exist.
+ * - If no hint, scan cwd/videos/.../timeline.ts, sort by mtime desc, return the most recent.
+ *   Returns null if no videos found (caller decides how to surface this).
+ */
+export function findTimeline(cwd, hint) {
+    if (hint) {
+        const resolved = resolve(cwd, hint);
+        if (!existsSync(resolved)) {
+            throw new UserError(`Timeline not found: ${resolved}`, `Check that the file exists. Expected at: ${resolved}`);
+        }
+        return resolved;
+    }
+    const videosDir = join(cwd, "videos");
+    if (!existsSync(videosDir))
+        return null;
+    let entries;
+    try {
+        entries = readdirSync(videosDir);
+    }
+    catch {
+        return null;
+    }
+    const candidates = [];
+    for (const entry of entries) {
+        const timelinePath = join(videosDir, entry, "timeline.ts");
+        if (existsSync(timelinePath)) {
+            const stat = statSync(timelinePath);
+            candidates.push({ path: resolve(timelinePath), mtime: stat.mtimeMs });
+        }
+    }
+    if (candidates.length === 0)
+        return null;
+    candidates.sort((a, b) => b.mtime - a.mtime);
+    return candidates[0].path;
+}
+//# sourceMappingURL=discover.js.map

package/dist/cli/discover.js.map

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

package/dist/cli/discover_project.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Shared project discovery: finds config and timeline, throws UserError on missing.
+ * Used by dev, script, and render commands.
+ */
+import type { ViteDevServer } from "vite";
+import type { ProjectInfo } from "../types.js";
+export interface DiscoveredProject {
+    configPath: string;
+    timelinePath: string;
+}
+/**
+ * Find config and timeline for a consumer project.
+ * Throws UserError with actionable hints on missing config or timeline.
+ *
+ * @param cwd - Consumer repo root
+ * @param positional - Optional explicit timeline path
+ * @param commandName - Command name for error messages (e.g. "dev", "render")
+ */
+export declare function discoverProject(cwd: string, positional: string | undefined, commandName: string): DiscoveredProject;
+/**
+ * Discover the project and load summaries for every video under videos/.
+ * Used by `dev` (whole project) and `render` (when prompting / auto-picking).
+ *
+ * When a Vite server is provided, timelines are loaded via `ssrLoadModule`
+ * which handles Vite-specific imports (CSS, virtual modules). Without a
+ * server, uses dynamic `import()` which may fail for files with Vite imports.
+ */
+export declare function discoverAllVideos(root: string, viteServer?: ViteDevServer): Promise<ProjectInfo>;
+//# sourceMappingURL=discover_project.d.ts.map

package/dist/cli/discover_project.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"discover_project.d.ts","sourceRoot":"","sources":["../../src/cli/discover_project.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,MAAM,CAAC;AAC1C,OAAO,KAAK,EAAU,WAAW,EAA0B,MAAM,aAAa,CAAC;AAI/E,MAAM,WAAW,iBAAiB;IACjC,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAC9B,GAAG,EAAE,MAAM,EACX,UAAU,EAAE,MAAM,GAAG,SAAS,EAC9B,WAAW,EAAE,MAAM,GACjB,iBAAiB,CAkBnB;AAED;;;;;;;GAOG;AACH,wBAAsB,iBAAiB,CACtC,IAAI,EAAE,MAAM,EACZ,UAAU,CAAC,EAAE,aAAa,GACxB,OAAO,CAAC,WAAW,CAAC,CA2EtB"}