@sequio/cli 0.1.0

package/bin/sequio.js

@@ -0,0 +1,53 @@
+#!/usr/bin/env node
+/**
+ * The `sequio` binary. Two modes:
+ *
+ *   • **Published** — the package ships a built `dist/cli.js`; we import it
+ *     directly (plain Node, no toolchain needed), and it resolves the sibling
+ *     `@sequio/*` packages from `node_modules`.
+ *
+ *   • **From source (this repo)** — there is no `dist/` yet, so — mirroring how
+ *     the repo runs its other Node entry points (route-b, the verify scripts) —
+ *     we execute `src/cli.ts` through tsx, pinning this package's tsconfig so its
+ *     `paths` resolve `@sequio/*` straight from source without a prior build.
+ */
+import { spawn } from 'node:child_process';
+import { createRequire } from 'node:module';
+import { dirname, resolve } from 'node:path';
+import { existsSync } from 'node:fs';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const here = dirname(fileURLToPath(import.meta.url));
+const built = resolve(here, '../dist/cli.js');
+
+if (existsSync(built)) {
+  // Published: run the built entry (it self-invokes `main`).
+  await import(pathToFileURL(built).href);
+} else {
+  // From source: launch `src/cli.ts` through tsx.
+  const require = createRequire(import.meta.url);
+  const entry = resolve(here, '../src/cli.ts');
+
+  // Resolve tsx's bin from its manifest so this works regardless of where the
+  // (hoisted) dependency landed in the workspace's node_modules.
+  const tsxPkgPath = require.resolve('tsx/package.json');
+  const tsxPkg = require('tsx/package.json');
+  const tsxBin = resolve(dirname(tsxPkgPath), typeof tsxPkg.bin === 'string' ? tsxPkg.bin : tsxPkg.bin.tsx);
+
+  // Pin the tsconfig tsx uses to this package's own — it carries the `paths` that
+  // resolve @sequio/engine, @sequio/runtime and @sequio/server/route-b straight
+  // from source. Without this, tsx would pick up whatever tsconfig sits at the
+  // cwd (e.g. the workspace-root solution config, which has no `paths`), and the
+  // bare imports would fall back to the engine's unbuilt `dist/` and fail.
+  const tsconfig = resolve(here, '../tsconfig.json');
+
+  const child = spawn(process.execPath, [tsxBin, entry, ...process.argv.slice(2)], {
+    stdio: 'inherit',
+    env: { ...process.env, TSX_TSCONFIG_PATH: tsconfig },
+  });
+  child.on('close', (code) => process.exit(code ?? 1));
+  child.on('error', (err) => {
+    console.error('✖ failed to launch sequio:', err.message);
+    process.exit(1);
+  });
+}

package/dist/args.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Pure argument parsing for the `sequio` CLI. Kept free of any I/O so it can be
+ * unit-tested directly: hand it an argv array, get back a discriminated
+ * {@link CliCommand} (or a help/version/error sentinel). `cli.ts` does the I/O.
+ */
+/** `sequio render <file> [-o out] [--scale N] [--verify]`. */
+export interface RenderCommand {
+    kind: 'render';
+    /** Path to the entry composition file (its `defineComposition` default export). */
+    file: string;
+    /** Output video path. `undefined` → `out.mp4`. */
+    out?: string;
+    /** Output resolution multiplier (N× the composition size). @default 1 */
+    scale: number;
+    /** Assert a valid video container came out (non-zero exit otherwise). */
+    verify: boolean;
+}
+/** `sequio preview <file> [--watch] [-p port] [--host]`. */
+export interface PreviewCommand {
+    kind: 'preview';
+    /** Path to the entry composition file. */
+    file: string;
+    /** Re-run the composition in the browser whenever a project file changes. */
+    watch: boolean;
+    /** Dev-server port. @default 6180 */
+    port: number;
+    /** Bind to `0.0.0.0` (expose on the network) instead of localhost. */
+    host: boolean;
+}
+/** `sequio frame <file> [-t sec] [-o out.png] [--scale N]`. */
+export interface FrameCommand {
+    kind: 'frame';
+    /** Path to the entry composition file. */
+    file: string;
+    /** Time (seconds) to sample. Clamped to `[0, duration]`. @default 0 */
+    time: number;
+    /** Output image path. `undefined` → `frame.png`. */
+    out?: string;
+    /** Output resolution multiplier (N× the composition size). @default 1 */
+    scale: number;
+}
+/** Show usage / version / a parse error and exit. */
+export interface MetaCommand {
+    kind: 'help' | 'version' | 'error';
+    /** For `error`: the message to print (before usage) and exit non-zero. */
+    message?: string;
+}
+export type CliCommand = RenderCommand | PreviewCommand | FrameCommand | MetaCommand;
+export declare const DEFAULT_PREVIEW_PORT = 6180;
+export declare const USAGE = "sequio \u2014 programmable-timeline CLI\n\nUsage:\n  sequio render <file> [options]     Encode a composition to a video file\n  sequio frame <file> [options]      Export a single frame at a time as a PNG\n  sequio preview <file> [options]    Serve a live in-browser preview\n\nRender options (pure Node, PixiJS WebGPU \u2014 needs a GPU or Mesa lavapipe):\n  -o, --out <path>     Output path (default: out.mp4)\n  -s, --scale <n>      Render at n\u00D7 the composition resolution (default: 1)\n      --verify         Assert a valid video container came out\n\nFrame options (pure Node, PixiJS WebGPU \u2014 needs a GPU or Mesa lavapipe):\n  -t, --time <sec>     Timeline time to sample, in seconds (default: 0)\n  -o, --out <path>     Output PNG path (default: frame.png)\n  -s, --scale <n>      Render at n\u00D7 the composition resolution (default: 1)\n\nPreview options:\n  -w, --watch          Re-run on any project-file change (live reload)\n  -p, --port <n>       Dev-server port (default: 6180)\n      --host           Expose the server on the local network (0.0.0.0)\n\nGlobal:\n  -h, --help           Show this help\n  -v, --version        Print the version\n\n<file> is a TS/JS module whose default export is a\ndefineComposition(builder) (or a bare builder). Its sibling files are\nbundled with it, so relative imports (./scene, ./title) resolve.";
+/** Parse `process.argv.slice(2)` into a {@link CliCommand}. Never throws. */
+export declare function parseArgs(argv: string[]): CliCommand;
+//# sourceMappingURL=args.d.ts.map

package/dist/assets-node.d.ts

@@ -0,0 +1,9 @@
+import { AssetLoader } from '@sequio/runtime';
+/**
+ * Build an {@link AssetLoader} rooted at `projectRoot` (the entry file's
+ * directory). Reads `projectRoot/<path>` and wraps the bytes in a `Blob` (which
+ * both `ImageSource` and `VideoSource` accept). Refuses paths that escape the
+ * root and reports a missing file clearly.
+ */
+export declare function nodeAssetLoader(projectRoot: string): AssetLoader;
+//# sourceMappingURL=assets-node.d.ts.map

package/dist/assets.d.ts

@@ -0,0 +1,17 @@
+/**
+ * CLI-side helpers for a composition's **local media assets** (the runtime owns
+ * the `loadAsset` contract — see `@sequio/runtime`'s `assets.ts`). These two
+ * concerns are the CLI's: which project files are *binary assets* (so
+ * {@link readBundle} keeps them out of the text bundle) and their MIME type (so
+ * the preview dev server can serve them over `/__asset/…`).
+ */
+/**
+ * Whether a project file is a binary media/font asset rather than source code.
+ * {@link readBundle} skips these so a (potentially large) local `.mp4` is never
+ * read as UTF-8 into the JSON bundle — the browser fetches it via `/__asset/…`
+ * and Node reads it off disk (see `assets-node.ts`) instead.
+ */
+export declare function isBinaryAssetPath(path: string): boolean;
+/** MIME type for a media path, for the preview server's `/__asset/` responses. */
+export declare function mimeForAsset(path: string): string;
+//# sourceMappingURL=assets.d.ts.map

package/dist/bundle.d.ts

@@ -0,0 +1,9 @@
+import { RuntimeBundle } from '@sequio/runtime';
+/**
+ * Snapshot the project around `entryFile` into a {@link RuntimeBundle}.
+ *
+ * @param entryFile Path (absolute or cwd-relative) to the entry module.
+ * @throws if the file does not exist under its own directory.
+ */
+export declare function readBundle(entryFile: string): RuntimeBundle;
+//# sourceMappingURL=bundle.d.ts.map

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.js

@@ -0,0 +1,34 @@
+import { p as n, s as t, a as i, b as l, U as c, v as p } from "./version-B2TKvZen.js";
+async function u(s) {
+  const e = n(s);
+  switch (e.kind) {
+    case "help":
+      return console.log(c), 0;
+    case "version":
+      return console.log(p), 0;
+    case "error":
+      return console.error(`✖ ${e.message}
+`), console.error(c), 2;
+    case "render":
+      return l(e.file, { out: e.out, scale: e.scale, verify: e.verify });
+    case "frame":
+      return i(e.file, { out: e.out, time: e.time, scale: e.scale });
+    case "preview": {
+      const r = await t(e.file, {
+        port: e.port,
+        host: e.host,
+        watch: e.watch
+      });
+      return console.log(`▸ sequio preview → ${r.url}`), console.log(`  serving ${e.file}${e.watch ? " (watching for changes)" : ""}`), console.log("  press Ctrl-C to stop."), await new Promise((a) => {
+        const o = () => {
+          r.close().finally(() => a());
+        };
+        process.once("SIGINT", o), process.once("SIGTERM", o);
+      }), 0;
+    }
+  }
+}
+u(process.argv.slice(2)).then((s) => process.exit(s)).catch((s) => {
+  console.error("✖", s instanceof Error ? s.message : s), process.exit(1);
+});
+//# sourceMappingURL=cli.js.map

package/dist/externals.d.ts

@@ -0,0 +1,4 @@
+import { Externals } from '@sequio/runtime';
+/** Bare-specifier → module value for user code. `import gsap from 'gsap'` works. */
+export declare function cliExternals(): Externals;
+//# sourceMappingURL=externals.d.ts.map

package/dist/externals.js

@@ -0,0 +1,8 @@
+import r from "gsap";
+function n() {
+  return { gsap: r };
+}
+export {
+  n as cliExternals
+};
+//# sourceMappingURL=externals.js.map

package/dist/frame.d.ts

@@ -0,0 +1,14 @@
+export interface FrameOptions {
+    /** Time (seconds) to sample. Clamped to `[0, duration]`. @default 0 */
+    time?: number;
+    /** Output PNG path. @default frame.png */
+    out?: string;
+    /** Output resolution multiplier (N× the composition size). @default 1 */
+    scale?: number;
+}
+/**
+ * Export one frame of `entryFile` to a PNG, returning the process exit code
+ * (0 = success).
+ */
+export declare function runFrame(entryFile: string, options?: FrameOptions): Promise<number>;
+//# sourceMappingURL=frame.d.ts.map

package/dist/index.d.ts

@@ -0,0 +1,22 @@
+/**
+ * `@sequio/cli` — the `sequio` command line.
+ *
+ * Three commands, all thin front-ends over infrastructure the other packages
+ * already own:
+ *  - `render <file>` → snapshot the composition into a {@link RuntimeBundle} and
+ *    hand it to the server's Route B (pure Node, WebGPU) to encode a video.
+ *  - `frame <file>` → the same Route B path, but seek to one time and write a
+ *    single PNG — a fast visual check without a full render.
+ *  - `preview <file>` → boot a Vite dev server whose page runs the same
+ *    `Runtime` → `Composer` → `preview()` path in-browser; `--watch` live-reloads.
+ *
+ * This barrel is the programmatic surface (used by tests and embedders); the
+ * `sequio` binary is `bin/sequio.js`, which runs `src/cli.ts`.
+ */
+export { parseArgs, USAGE, DEFAULT_PREVIEW_PORT, type CliCommand, type RenderCommand, type FrameCommand, type PreviewCommand, type MetaCommand, } from './args';
+export { readBundle } from './bundle';
+export { runRender, type RenderOptions } from './render';
+export { runFrame, type FrameOptions } from './frame';
+export { startPreviewServer, type PreviewServer, type PreviewServerOptions, } from './preview';
+export { version } from './version';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,12 @@
+import { D as s, U as e, p as n, r as v, a as E, b as d, s as o, v as p } from "./version-B2TKvZen.js";
+export {
+  s as DEFAULT_PREVIEW_PORT,
+  e as USAGE,
+  n as parseArgs,
+  v as readBundle,
+  E as runFrame,
+  d as runRender,
+  o as startPreviewServer,
+  p as version
+};
+//# sourceMappingURL=index.js.map

package/dist/preview.d.ts

@@ -0,0 +1,17 @@
+export interface PreviewServerOptions {
+    port?: number;
+    host?: boolean;
+    watch?: boolean;
+}
+export interface PreviewServer {
+    /** The URL the preview is served at. */
+    url: string;
+    /** Shut the server (and any file watcher) down. */
+    close(): Promise<void>;
+}
+/**
+ * Start the preview dev server for `entryFile`. Resolves once it is listening;
+ * the returned handle carries the URL and a {@link PreviewServer.close}.
+ */
+export declare function startPreviewServer(entryFile: string, options?: PreviewServerOptions): Promise<PreviewServer>;
+//# sourceMappingURL=preview.d.ts.map

package/dist/render.d.ts

@@ -0,0 +1,11 @@
+export interface RenderOptions {
+    out?: string;
+    verify?: boolean;
+    /** Output resolution multiplier (N× the composition size). @default 1 */
+    scale?: number;
+}
+/**
+ * Render `entryFile` to a video, returning the process exit code (0 = success).
+ */
+export declare function runRender(entryFile: string, options?: RenderOptions): Promise<number>;
+//# sourceMappingURL=render.d.ts.map

package/dist/version-B2TKvZen.js

@@ -0,0 +1,338 @@
+import { resolve as f, dirname as m, basename as S } from "node:path";
+import { cliExternals as h } from "./externals.js";
+import { readFileSync as E, existsSync as w, statSync as P, createReadStream as x } from "node:fs";
+import { fileURLToPath as U } from "node:url";
+import { resolveAssetPath as R } from "@sequio/runtime";
+import { NodeFileSystem as N } from "@sequio/runtime/node-fs";
+import { createRequire as C } from "node:module";
+const v = 6180, z = `sequio — programmable-timeline CLI
+
+Usage:
+  sequio render <file> [options]     Encode a composition to a video file
+  sequio frame <file> [options]      Export a single frame at a time as a PNG
+  sequio preview <file> [options]    Serve a live in-browser preview
+
+Render options (pure Node, PixiJS WebGPU — needs a GPU or Mesa lavapipe):
+  -o, --out <path>     Output path (default: out.mp4)
+  -s, --scale <n>      Render at n× the composition resolution (default: 1)
+      --verify         Assert a valid video container came out
+
+Frame options (pure Node, PixiJS WebGPU — needs a GPU or Mesa lavapipe):
+  -t, --time <sec>     Timeline time to sample, in seconds (default: 0)
+  -o, --out <path>     Output PNG path (default: frame.png)
+  -s, --scale <n>      Render at n× the composition resolution (default: 1)
+
+Preview options:
+  -w, --watch          Re-run on any project-file change (live reload)
+  -p, --port <n>       Dev-server port (default: ${v})
+      --host           Expose the server on the local network (0.0.0.0)
+
+Global:
+  -h, --help           Show this help
+  -v, --version        Print the version
+
+<file> is a TS/JS module whose default export is a
+defineComposition(builder) (or a bare builder). Its sibling files are
+bundled with it, so relative imports (./scene, ./title) resolve.`;
+function X(t) {
+  if (t[0] === "--" && (t = t.slice(1)), t.length === 0) return { kind: "help" };
+  const e = t[0];
+  return e === "-h" || e === "--help" ? { kind: "help" } : e === "-v" || e === "--version" ? { kind: "version" } : e === "render" ? j(t.slice(1)) : e === "frame" ? A(t.slice(1)) : e === "preview" ? F(t.slice(1)) : { kind: "error", message: `Unknown command: ${e}` };
+}
+function j(t) {
+  let e, i, l = 1, c = !1;
+  for (let o = 0; o < t.length; o++) {
+    const r = t[o];
+    if (r === "-h" || r === "--help") return { kind: "help" };
+    if (r === "-o" || r === "--out") {
+      if (i = t[++o], i === void 0) return { kind: "error", message: `${r} needs a path` };
+    } else if (r === "-s" || r === "--scale") {
+      const n = t[++o], s = Number(n);
+      if (!(s >= 1) || !Number.isFinite(s)) return { kind: "error", message: `${r} needs a number ≥ 1, got: ${n}` };
+      l = s;
+    } else if (r === "--verify") c = !0;
+    else {
+      if (r.startsWith("-")) return { kind: "error", message: `Unknown option: ${r}` };
+      if (e === void 0) e = r;
+      else return { kind: "error", message: `Unexpected argument: ${r}` };
+    }
+  }
+  return e === void 0 ? { kind: "error", message: "render needs a <file>" } : { kind: "render", file: e, out: i, scale: l, verify: c };
+}
+function A(t) {
+  let e, i, l = 0, c = 1;
+  for (let o = 0; o < t.length; o++) {
+    const r = t[o];
+    if (r === "-h" || r === "--help") return { kind: "help" };
+    if (r === "-o" || r === "--out") {
+      if (i = t[++o], i === void 0) return { kind: "error", message: `${r} needs a path` };
+    } else if (r === "-t" || r === "--time") {
+      const n = t[++o], s = Number(n);
+      if (!Number.isFinite(s) || s < 0) return { kind: "error", message: `${r} needs a number ≥ 0, got: ${n}` };
+      l = s;
+    } else if (r === "-s" || r === "--scale") {
+      const n = t[++o], s = Number(n);
+      if (!(s >= 1) || !Number.isFinite(s)) return { kind: "error", message: `${r} needs a number ≥ 1, got: ${n}` };
+      c = s;
+    } else {
+      if (r.startsWith("-")) return { kind: "error", message: `Unknown option: ${r}` };
+      if (e === void 0) e = r;
+      else return { kind: "error", message: `Unexpected argument: ${r}` };
+    }
+  }
+  return e === void 0 ? { kind: "error", message: "frame needs a <file>" } : { kind: "frame", file: e, time: l, out: i, scale: c };
+}
+function F(t) {
+  let e, i = !1, l = !1, c = v;
+  for (let o = 0; o < t.length; o++) {
+    const r = t[o];
+    if (r === "-h" || r === "--help") return { kind: "help" };
+    if (r === "-w" || r === "--watch") i = !0;
+    else if (r === "--host") l = !0;
+    else if (r === "-p" || r === "--port") {
+      const n = t[++o], s = Number(n);
+      if (!Number.isInteger(s) || s <= 0 || s > 65535)
+        return { kind: "error", message: `${r} needs a valid port, got: ${n}` };
+      c = s;
+    } else {
+      if (r.startsWith("-")) return { kind: "error", message: `Unknown option: ${r}` };
+      if (e === void 0) e = r;
+      else return { kind: "error", message: `Unexpected argument: ${r}` };
+    }
+  }
+  return e === void 0 ? { kind: "error", message: "preview needs a <file>" } : { kind: "preview", file: e, watch: i, port: c, host: l };
+}
+const T = /* @__PURE__ */ new Set([
+  // images
+  "png",
+  "jpg",
+  "jpeg",
+  "gif",
+  "webp",
+  "avif",
+  "bmp",
+  "ico",
+  // video
+  "mp4",
+  "webm",
+  "mov",
+  "mkv",
+  "avi",
+  "m4v",
+  // audio
+  "mp3",
+  "wav",
+  "m4a",
+  "aac",
+  "ogg",
+  "oga",
+  "flac",
+  "opus",
+  // fonts
+  "ttf",
+  "otf",
+  "woff",
+  "woff2"
+]);
+function $(t) {
+  const e = t.lastIndexOf(".");
+  return e < 0 ? "" : t.slice(e + 1).toLowerCase();
+}
+function q(t) {
+  return T.has($(t));
+}
+function W(t) {
+  return {
+    png: "image/png",
+    jpg: "image/jpeg",
+    jpeg: "image/jpeg",
+    gif: "image/gif",
+    webp: "image/webp",
+    avif: "image/avif",
+    bmp: "image/bmp",
+    ico: "image/x-icon",
+    mp4: "video/mp4",
+    webm: "video/webm",
+    mov: "video/quicktime",
+    mkv: "video/x-matroska",
+    avi: "video/x-msvideo",
+    m4v: "video/x-m4v",
+    mp3: "audio/mpeg",
+    wav: "audio/wav",
+    m4a: "audio/mp4",
+    aac: "audio/aac",
+    ogg: "audio/ogg",
+    oga: "audio/ogg",
+    flac: "audio/flac",
+    opus: "audio/opus",
+    ttf: "font/ttf",
+    otf: "font/otf",
+    woff: "font/woff",
+    woff2: "font/woff2"
+  }[$(t)] ?? "application/octet-stream";
+}
+function p(t) {
+  const e = f(t), i = m(e), l = "/" + S(e), c = new N(i), o = {};
+  for (const r of c.listFiles()) {
+    if (q(r)) continue;
+    const n = c.readFile(r);
+    n !== null && (o[r] = n);
+  }
+  if (o[l] === void 0)
+    throw new Error(`Entry file not found: ${t}`);
+  return { files: o, entry: l };
+}
+function b(t) {
+  const e = f(t);
+  return async (i) => {
+    const l = f(e, i);
+    if (l !== e && !l.startsWith(e + "/"))
+      throw new Error(`asset path escapes the project root: ${i}`);
+    let c;
+    try {
+      c = E(l);
+    } catch {
+      throw new Error(
+        `local asset not found: ${i} (looked in ${e}). Drop the file there, or reference a network URL instead.`
+      );
+    }
+    return new Blob([new Uint8Array(c)]);
+  };
+}
+function O(t) {
+  return t.length >= 12 && Buffer.from(t.subarray(4, 8)).toString("latin1") === "ftyp" ? "mp4" : t.length >= 4 && t[0] === 26 && t[1] === 69 && t[2] === 223 && t[3] === 163 ? "webm" : null;
+}
+async function Y(t, e = {}) {
+  const i = p(t), l = m(f(t)), { renderBundleToFile: c } = await import("@sequio/server/route-b");
+  try {
+    const o = e.out ?? "out.mp4";
+    console.log(`Rendering ${t} (pure Node, WebGPU)${e.scale && e.scale !== 1 ? ` @ ${e.scale}×` : ""} …`);
+    let r = -1;
+    const n = await c(i, {
+      out: o,
+      scale: e.scale,
+      // Make gsap (and any other CLI-provided lib) resolvable to the composition
+      // in the Node render, same as the browser preview does.
+      externals: h(),
+      // Resolve `loadAsset('./clip.mp4')` against the project directory on disk,
+      // so a local image/video renders the same as it previews (contract #3).
+      loadAsset: b(l),
+      onProgress: (s) => {
+        const a = Math.round(s * 100);
+        a !== r && a % 10 === 0 && (r = a, process.stdout.write(`\r  ${a}%`));
+      }
+    });
+    if (process.stdout.write("\r     \r"), console.log(
+      `✅ wrote ${n.out} (${n.frames} frames, ${n.container}/${n.videoCodec}, ${n.bytes} bytes${n.audio ? ", +audio" : ""})`
+    ), e.verify) {
+      const a = (await import("node:fs")).readFileSync(n.out), d = O(a);
+      if (!d || a.length < 500)
+        throw new Error(`--verify failed: not a valid container (detected=${d}, size=${a.length})`);
+      console.log(`✅ verified: valid ${d} container.`);
+    }
+    return 0;
+  } catch (o) {
+    return console.error("✖", o instanceof Error ? o.message : String(o)), 1;
+  }
+}
+async function K(t, e = {}) {
+  const i = p(t), l = m(f(t)), { renderBundleFrameToFile: c } = await import("@sequio/server/route-b");
+  try {
+    const o = e.out ?? "frame.png", r = e.time ?? 0;
+    console.log(
+      `Rendering ${t} frame @ t=${r}s (pure Node, WebGPU)${e.scale && e.scale !== 1 ? ` @ ${e.scale}×` : ""} …`
+    );
+    const n = await c(i, {
+      out: o,
+      time: r,
+      scale: e.scale,
+      // Make gsap (and any other CLI-provided lib) resolvable to the composition
+      // in the Node render, same as the browser preview does.
+      externals: h(),
+      // Resolve `loadAsset('./clip.mp4')` against the project directory on disk,
+      // so a local image/video renders the same as it previews (contract #3).
+      loadAsset: b(l)
+    }), s = n.time !== r ? ` (clamped from ${r}s)` : "";
+    return console.log(
+      `✅ wrote ${n.out} (${n.width}×${n.height}, t=${n.time}s${s}, ${n.bytes} bytes)`
+    ), 0;
+  } catch (o) {
+    return console.error("✖", o instanceof Error ? o.message : String(o)), 1;
+  }
+}
+const k = m(U(import.meta.url)), _ = f(k, "../preview"), y = {};
+for (const [t, e] of [
+  ["@sequio/engine", "../../engine/src/index.ts"],
+  ["@sequio/runtime", "../../runtime/src/index.ts"],
+  ["@sequio/cli/externals", "./externals.ts"]
+]) {
+  const i = f(k, e);
+  w(i) && (y[t] = i);
+}
+async function Q(t, e = {}) {
+  const i = f(t), l = m(i);
+  p(i);
+  const { createServer: c } = await import("vite"), o = await c({
+    configFile: !1,
+    root: _,
+    logLevel: "warn",
+    server: {
+      port: e.port ?? 6180,
+      host: e.host ? !0 : "localhost",
+      strictPort: !0
+    },
+    resolve: {
+      alias: y
+    },
+    plugins: [
+      {
+        name: "sequio-preview-bundle",
+        configureServer(n) {
+          if (n.middlewares.use("/__bundle", (s, a) => {
+            try {
+              const d = p(i);
+              a.setHeader("Content-Type", "application/json"), a.setHeader("Cache-Control", "no-store"), a.end(JSON.stringify(d));
+            } catch (d) {
+              a.statusCode = 500, a.setHeader("Content-Type", "application/json"), a.end(JSON.stringify({ error: d instanceof Error ? d.message : String(d) }));
+            }
+          }), n.middlewares.use("/__asset", (s, a) => {
+            try {
+              const d = (s.url ?? "").split("?")[0], g = R(decodeURIComponent(d)), u = f(l, g);
+              if (u !== l && !u.startsWith(l + "/"))
+                return a.statusCode = 403, a.end("forbidden");
+              if (!w(u) || !P(u).isFile())
+                return a.statusCode = 404, a.end(`asset not found: ${g}`);
+              a.setHeader("Content-Type", W(g)), a.setHeader("Cache-Control", "no-store"), x(u).pipe(a);
+            } catch (d) {
+              a.statusCode = 400, a.end(d instanceof Error ? d.message : String(d));
+            }
+          }), e.watch) {
+            n.watcher.add(l);
+            const s = (a) => {
+              f(a).startsWith(l) && n.ws.send({ type: "full-reload", path: "*" });
+            };
+            n.watcher.on("change", s), n.watcher.on("add", s), n.watcher.on("unlink", s);
+          }
+        }
+      }
+    ]
+  });
+  return await o.listen(), {
+    url: o.resolvedUrls?.local[0] ?? `http://localhost:${e.port ?? 6180}/`,
+    async close() {
+      await o.close();
+    }
+  };
+}
+const G = C(import.meta.url), I = G("../package.json"), Z = I.version;
+export {
+  v as D,
+  z as U,
+  K as a,
+  Y as b,
+  X as p,
+  p as r,
+  Q as s,
+  Z as v
+};
+//# sourceMappingURL=version-B2TKvZen.js.map

package/dist/version.d.ts

@@ -0,0 +1,2 @@
+export declare const version: string;
+//# sourceMappingURL=version.d.ts.map

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@sequio/cli",
+  "version": "0.1.0",
+  "description": "The sequio command-line: `sequio render <file>` encodes a composition to video (pure Node, PixiJS WebGPU), `sequio frame <file>` writes a single-frame PNG, and `sequio preview <file>` serves a live in-browser preview (with --watch).",
+  "type": "module",
+  "license": "MIT",
+  "author": "slightc",
+  "homepage": "https://sequio-demo.vercel.app/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/slightc/sequio.git",
+    "directory": "packages/cli"
+  },
+  "bugs": {
+    "url": "https://github.com/slightc/sequio/issues"
+  },
+  "bin": {
+    "sequio": "./bin/sequio.js"
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./externals": {
+      "types": "./dist/externals.d.ts",
+      "import": "./dist/externals.js"
+    }
+  },
+  "files": [
+    "dist",
+    "bin",
+    "preview",
+    "!dist/**/*.map"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "cli",
+    "video-editor",
+    "render",
+    "preview",
+    "pixijs"
+  ],
+  "dependencies": {
+    "gsap": "^3.12.0",
+    "vite": "^6.0.0",
+    "@sequio/engine": "^0.1.1",
+    "@sequio/server": "^0.1.0",
+    "@sequio/runtime": "^0.1.0"
+  },
+  "scripts": {
+    "dev": "tsx src/cli.ts",
+    "build": "vite build",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "verify:cli": "tsx scripts/verify-cli.ts"
+  }
+}

package/preview/assets.ts

@@ -0,0 +1,22 @@
+/**
+ * The browser {@link AssetLoader} for `sequio preview`: fetch a composition's
+ * project-relative media file from the dev server's `/__asset/…` static route
+ * (see `src/preview.ts`) and return it as a `Blob`, so `await loadAsset('./clip.mp4')`
+ * resolves in the in-browser preview exactly as it does in the Node render
+ * (contract #3). The runtime normalizes the path before calling this.
+ */
+import type { AssetLoader } from '@sequio/runtime';
+
+/** The preview's asset loader: the dev server serves project files under `/__asset/`. */
+export function browserAssetLoader(): AssetLoader {
+  return async (path: string): Promise<Blob> => {
+    const res = await fetch(`/__asset/${path}`, { cache: 'no-store' });
+    if (!res.ok) {
+      throw new Error(
+        `local asset not found: ${path} (HTTP ${res.status}). ` +
+          `Drop the file into the composition's folder, or reference a network URL.`,
+      );
+    }
+    return res.blob();
+  };
+}

package/preview/index.html

@@ -0,0 +1,115 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>sequio preview</title>
+    <style>
+      :root {
+        color-scheme: dark;
+        --bg: #0b0b0e;
+        --panel: #16161c;
+        --border: #2a2a33;
+        --fg: #e6e6ea;
+        --muted: #9a9aa6;
+        --accent: #38bdf8;
+        --err: #f87171;
+        --ok: #4ade80;
+      }
+      * { box-sizing: border-box; }
+      body {
+        margin: 0;
+        min-height: 100vh;
+        display: flex;
+        flex-direction: column;
+        background: var(--bg);
+        color: var(--fg);
+        font: 14px/1.5 ui-sans-serif, system-ui, -apple-system, Segoe UI, Roboto, sans-serif;
+      }
+      header {
+        display: flex;
+        align-items: center;
+        gap: 12px;
+        padding: 10px 16px;
+        border-bottom: 1px solid var(--border);
+        background: var(--panel);
+      }
+      header .brand { font-weight: 600; letter-spacing: 0.02em; }
+      header .file { color: var(--muted); font-family: ui-monospace, monospace; font-size: 12px; }
+      main {
+        flex: 1;
+        display: flex;
+        align-items: center;
+        justify-content: center;
+        padding: 16px;
+        overflow: auto;
+      }
+      #stage {
+        display: flex;
+        align-items: center;
+        justify-content: center;
+        max-width: 100%;
+      }
+      #stage canvas {
+        /* Pixi (autoDensity) sets explicit inline width/height on the canvas,
+           which makes max-width/max-height clamp each axis independently and
+           breaks the aspect ratio when only one binds. Force width/height back
+           to auto so the intrinsic buffer ratio is used and the max-* limits
+           scale it proportionally. */
+        width: auto !important;
+        height: auto !important;
+        max-width: 100%;
+        max-height: 78vh;
+        background: #000;
+        border: 1px solid var(--border);
+        border-radius: 6px;
+      }
+      footer {
+        display: flex;
+        align-items: center;
+        gap: 12px;
+        padding: 10px 16px;
+        border-top: 1px solid var(--border);
+        background: var(--panel);
+      }
+      button {
+        background: #23232c;
+        color: var(--fg);
+        border: 1px solid var(--border);
+        border-radius: 6px;
+        padding: 6px 12px;
+        cursor: pointer;
+        font: inherit;
+      }
+      button:disabled { opacity: 0.5; cursor: default; }
+      button:hover:not(:disabled) { border-color: var(--accent); }
+      input[type='range'] { flex: 1; accent-color: var(--accent); }
+      .time { color: var(--muted); font-family: ui-monospace, monospace; font-size: 12px; min-width: 92px; }
+      .log {
+        padding: 8px 16px;
+        font-family: ui-monospace, monospace;
+        font-size: 12px;
+        white-space: pre-wrap;
+        color: var(--muted);
+        border-top: 1px solid var(--border);
+        background: #101015;
+      }
+      .log.ok { color: var(--ok); }
+      .log.err { color: var(--err); }
+    </style>
+  </head>
+  <body>
+    <header>
+      <span class="brand">▸ sequio preview</span>
+      <span class="file" id="file"></span>
+    </header>
+    <main><div id="stage"></div></main>
+    <footer>
+      <button id="play" disabled>▶ Play</button>
+      <input id="scrub" type="range" min="0" max="1" step="0.001" value="0" disabled />
+      <span class="time" id="time">0.00 / 0.00s</span>
+    </footer>
+    <div class="log" id="log">Loading…</div>
+    <script type="module" src="/preview.ts"></script>
+  </body>
+</html>

package/preview/preview.ts

@@ -0,0 +1,112 @@
+/**
+ * The browser half of `sequio preview`. Fetches `/__bundle` (the project
+ * snapshot the dev server serves), compiles + runs it with the {@link Runtime}
+ * into a {@link Composer}, and plays the resulting graph live via
+ * `composer.preview(stage)` — the same in-browser render core studio's Code Mode
+ * uses. With `--watch`, the dev server issues a full-reload on any file change,
+ * so this module simply re-runs from scratch on load.
+ */
+import { Runtime, type PreviewHandle, type RuntimeBundle } from '@sequio/runtime';
+// Browser-safe subpath so the preview page resolves the same `cliExternals` in
+// both hosts: from source in this repo (alias in src/preview.ts) and from the
+// published `dist/externals.js` when installed from npm.
+import { cliExternals } from '@sequio/cli/externals';
+import { browserAssetLoader } from './assets';
+
+function $<T extends HTMLElement>(id: string): T {
+  return document.getElementById(id) as T;
+}
+
+const stageEl = $<HTMLDivElement>('stage');
+const fileEl = $<HTMLSpanElement>('file');
+const logEl = $<HTMLDivElement>('log');
+const playBtn = $<HTMLButtonElement>('play');
+const scrub = $<HTMLInputElement>('scrub');
+const timeLabel = $<HTMLSpanElement>('time');
+
+function log(message: string, kind: 'info' | 'ok' | 'err' = 'info'): void {
+  logEl.textContent = message;
+  logEl.className = `log${kind === 'ok' ? ' ok' : kind === 'err' ? ' err' : ''}`;
+}
+
+function fmt(t: number): string {
+  return t.toFixed(2);
+}
+
+let preview: PreviewHandle | null = null;
+
+function updateTransport(t: number): void {
+  if (!preview) return;
+  scrub.value = String(t);
+  timeLabel.textContent = `${fmt(t)} / ${fmt(preview.duration)}s`;
+  playBtn.textContent = preview.playing ? '⏸ Pause' : '▶ Play';
+}
+
+playBtn.addEventListener('click', () => {
+  if (!preview) return;
+  if (preview.playing) preview.pause();
+  else preview.play();
+  updateTransport(preview.clock.currentTime);
+});
+
+scrub.addEventListener('input', () => {
+  if (!preview) return;
+  preview.pause();
+  const t = parseFloat(scrub.value);
+  preview.seek(t);
+  updateTransport(t);
+});
+
+async function boot(): Promise<void> {
+  log('Loading composition…');
+  try {
+    const res = await fetch('/__bundle', { cache: 'no-store' });
+    const bundle = (await res.json()) as RuntimeBundle & { error?: string };
+    if (!res.ok || bundle.error) throw new Error(bundle.error ?? `bundle request failed (${res.status})`);
+
+    fileEl.textContent = bundle.entry;
+
+    const composer = await new Runtime({
+      ...bundle,
+      externals: cliExternals(),
+      // Resolve `loadAsset('./clip.mp4')` by fetching the file the dev server
+      // serves under /__asset/ (readBundle keeps binary assets out of the bundle).
+      loadAsset: browserAssetLoader(),
+    }).run();
+    stageEl.replaceChildren();
+    preview = await composer.preview(stageEl);
+
+    scrub.min = '0';
+    scrub.max = String(preview.duration);
+    scrub.disabled = false;
+    playBtn.disabled = false;
+    preview.clock.onTick((t) => updateTransport(t));
+    // Reaching the end auto-pauses the clock but fires no further tick, so
+    // refresh the transport (Play button label, scrub) on `ended` too.
+    preview.clock.onEnded(() => updateTransport(preview!.clock.currentTime));
+    updateTransport(0);
+
+    const tracks = preview.built.compositor.getTracks();
+    const clips = tracks.reduce((n, t) => n + t.clips.length, 0);
+    log(
+      `Ran ${Object.keys(bundle.files).length} file(s) → ${tracks.length} track(s), ` +
+        `${clips} clip(s), ${fmt(preview.duration)}s. Ready.`,
+      'ok',
+    );
+    // Publish a result the `verify:cli` harness can assert on (repo convention).
+    (window as unknown as { __PREVIEW_TEST__: unknown }).__PREVIEW_TEST__ = {
+      ok: tracks.length > 0 && preview.duration > 0,
+      tracks: tracks.length,
+      clips,
+      duration: preview.duration,
+    };
+  } catch (err) {
+    log(err instanceof Error ? (err.stack ?? err.message) : String(err), 'err');
+    (window as unknown as { __PREVIEW_TEST__: unknown }).__PREVIEW_TEST__ = {
+      ok: false,
+      error: err instanceof Error ? err.message : String(err),
+    };
+  }
+}
+
+void boot();