@sequio/runtime 0.1.0

package/dist/assets.d.ts

@@ -0,0 +1,46 @@
+/**
+ * **Local media assets** for a composition.
+ *
+ * A composition run by the runtime describes its video imperatively and can pull
+ * in local media — an `image` / `video` sitting next to it — through a single
+ * host-provided hook. The composition asks for a file by a project-relative path
+ * and gets back a `Blob`, which both `ImageSource` and `VideoSource` accept:
+ *
+ * ```ts
+ * import { defineComposition, loadAsset } from '@sequio/runtime';
+ * export default defineComposition(async () => {
+ *   const video = new VideoSource({ src: await loadAsset('./clip.mp4') });
+ *   const image = new ImageSource({ src: await loadAsset('./assets/photo.jpg') });
+ *   // …
+ * });
+ * ```
+ *
+ * The runtime owns the *contract* (the `loadAsset` symbol on `@sequio/runtime`
+ * and the path rules here); the **host** supplies the actual bytes via
+ * {@link RuntimeOptions.loadAsset}, so the same `loadAsset('./clip.mp4')` resolves
+ * identically wherever the composition runs (contract #3): the browser preview
+ * fetches it from the dev server, the Node render reads it off disk, an editor
+ * serves it from an upload store. Assets stay **out of the source bundle** (which
+ * is text-only), so a large local `.mp4` never bloats what's transferred or
+ * committed.
+ */
+/**
+ * A host's binary-asset resolver: map a project-relative media path (already
+ * cleaned by {@link resolveAssetPath}) to its bytes as a `Blob`.
+ */
+export type AssetLoader = (path: string) => Promise<Blob>;
+/**
+ * Canonicalise a composition's asset reference to a clean project-relative path.
+ * Accepts `./clip.mp4`, `clip.mp4` or `/clip.mp4` and returns `clip.mp4`;
+ * `./assets/x.png` → `assets/x.png`. Paths resolve against the **project root**
+ * (the bundle's virtual `/`). Rejects anything that escapes it (`..`), so a host
+ * loader can never be steered outside the project directory.
+ */
+export declare function resolveAssetPath(path: string): string;
+/**
+ * The default `loadAsset` when a host wires no {@link AssetLoader}: fail loudly
+ * (per the repo's "throw, don't render silent black" convention) so a composition
+ * that references a local file isn't silently handed nothing.
+ */
+export declare const NO_ASSET_LOADER: AssetLoader;
+//# sourceMappingURL=assets.d.ts.map

package/dist/compile.d.ts

@@ -0,0 +1,16 @@
+/** Which language a file is written in, inferred from its extension. */
+export type SourceLang = 'ts' | 'tsx' | 'js' | 'jsx' | 'json';
+/** Infer the language from a file path's extension (defaults to `ts`). */
+export declare function langOf(path: string): SourceLang;
+export interface CompileResult {
+    /** The emitted CommonJS code. */
+    code: string;
+    /** Syntactic diagnostics as human-readable strings (empty when clean). */
+    diagnostics: string[];
+}
+/**
+ * Transpile `code` (a TS/JS source) to CommonJS. `.json` is wrapped as a module
+ * exporting the parsed value. Throws on a hard parse failure with the file name.
+ */
+export declare function compileModule(code: string, fileName: string): CompileResult;
+//# sourceMappingURL=compile.d.ts.map

package/dist/composer.d.ts

@@ -0,0 +1,74 @@
+import { AudioEngine, Compositor, ExportOptions, RealtimeClock } from '@sequio/engine';
+import { Composition, CompositionEnv } from './composition';
+/** A portable snapshot of the program: its source files and entry path. */
+export interface RuntimeBundle {
+    /** Absolute virtual path → source text. */
+    files: Record<string, string>;
+    /** Entry module path (e.g. `/index.ts`). */
+    entry: string;
+}
+/** A built, initialized composition graph plus a teardown. */
+export interface BuiltComposition {
+    compositor: Compositor;
+    audioEngine: AudioEngine;
+    /** Timeline duration in seconds (builder value, else derived from clip ends). */
+    duration: number;
+    /** Dispose the compositor and its audio engine. */
+    dispose(): void;
+}
+/** A live preview: the built graph, its clock, and media-element-style controls. */
+export interface PreviewHandle {
+    readonly built: BuiltComposition;
+    readonly clock: RealtimeClock;
+    readonly view: HTMLCanvasElement;
+    readonly duration: number;
+    play(): void;
+    pause(): void;
+    seek(t: number): void;
+    readonly playing: boolean;
+    dispose(): void;
+}
+/**
+ * Re-links + runs the program for a given environment and returns its
+ * {@link Composition}. The runtime supplies this so each build gets a fresh graph
+ * whose engine `Compositor` already has the environment's options folded in —
+ * which is why user code just writes `new Compositor({ width, height, timebase })`
+ * with no env plumbing.
+ */
+export type CompositionLinker = (env: CompositionEnv) => Composition;
+export declare class Composer {
+    private readonly link;
+    private readonly bundle;
+    constructor(link: CompositionLinker, bundle: RuntimeBundle);
+    /** The entry module path the program ran from. */
+    get entry(): string;
+    /** The source files, as a fresh copy (edit freely; the Composer keeps its own). */
+    get files(): Record<string, string>;
+    /**
+     * The portable code bundle to hand to server-side rendering: the same files +
+     * entry, run by a runtime on the server. This replaces "serialize a spec" —
+     * the code itself is what ships, so there's no schema to drift.
+     */
+    toBundle(): RuntimeBundle;
+    /** `JSON.stringify(composer)` yields the portable bundle. */
+    toJSON(): RuntimeBundle;
+    /**
+     * Run the builder to a fresh, initialized graph. The caller owns the result and
+     * must {@link BuiltComposition.dispose} it. `env` lets a host inject a renderer
+     * (Node) or an output scale; it defaults to the browser (`{}`).
+     */
+    build(env?: Partial<CompositionEnv>): Promise<BuiltComposition>;
+    /**
+     * Build the graph and start a preview loop. If `container` is given the
+     * compositor's canvas is appended to it. Returns a {@link PreviewHandle} with
+     * play/pause/seek; the first frame renders immediately so the canvas is never
+     * blank before playback starts.
+     */
+    preview(container?: HTMLElement, env?: Partial<CompositionEnv>): Promise<PreviewHandle>;
+    /**
+     * Render the composition to a video `Blob` in the client. Builds a fresh graph,
+     * runs the engine's {@link Exporter} over `[0, duration]`, then disposes it.
+     */
+    export(options?: Partial<ExportOptions>, onProgress?: (progress: number) => void): Promise<Blob>;
+}
+//# sourceMappingURL=composer.d.ts.map

package/dist/composition.d.ts

@@ -0,0 +1,49 @@
+import { AudioEngine, Compositor, CompositorOptions } from '@sequio/engine';
+/** Brand marking a value produced by {@link defineComposition}. */
+export declare const COMPOSITION_TAG: "@sequio/runtime:composition";
+/**
+ * The live object graph a builder returns: an initialized {@link Compositor} plus
+ * (optionally) the {@link AudioEngine} driving its audio, and the timeline length.
+ */
+export interface CompositionResult {
+    /** The built + `init()`-ed compositor to preview / export / server-render. */
+    compositor: Compositor;
+    /** The audio engine for preview playback and the export mix, if any. */
+    audioEngine?: AudioEngine;
+    /**
+     * Timeline duration in seconds. Optional — when omitted it's derived from the
+     * largest clip end across the compositor's tracks (see {@link deriveDuration}).
+     */
+    duration?: number;
+}
+/**
+ * The environment a composition is built in. The same builder runs for client
+ * preview, client export and server render; `compositorOptions` is how the host
+ * injects what differs (a Node WebGPU renderer, an output scale), so portable
+ * code spreads it into `new Compositor({ ... })`.
+ */
+export interface CompositionEnv {
+    /** Merge into the `Compositor` options. Browser: `{}`; Node: `{ createRenderer, resolution }`. */
+    readonly compositorOptions: Partial<CompositorOptions>;
+    /** Where this build runs, in case user code wants to branch (e.g. output scale). */
+    readonly target: 'preview' | 'export' | 'server';
+}
+/** A function that builds a live composition. May be async (it `await`s `init()`). */
+export type CompositionBuilder = (env: CompositionEnv) => CompositionResult | Promise<CompositionResult>;
+/** A tagged builder returned by {@link defineComposition}. */
+export interface Composition {
+    readonly __tag: typeof COMPOSITION_TAG;
+    readonly build: CompositionBuilder;
+}
+/** Whether `value` is a {@link Composition} produced by {@link defineComposition}. */
+export declare function isComposition(value: unknown): value is Composition;
+/**
+ * Tag a builder function as a composition. Kept intentionally thin — all the
+ * power is in the builder body (real engine classes, real control flow); this
+ * just marks the value so the runtime can tell "the user returned a composition"
+ * from "the user returned something else", and fails loudly if handed a non-function.
+ */
+export declare function defineComposition(build: CompositionBuilder): Composition;
+/** Largest clip end across every track of a compositor (the timeline duration). */
+export declare function deriveDuration(compositor: Compositor): number;
+//# sourceMappingURL=composition.d.ts.map

package/dist/index.cjs

@@ -0,0 +1,3 @@
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const d=require("typescript"),f=require("@sequio/engine");function R(s){const e=Object.create(null,{[Symbol.toStringTag]:{value:"Module"}});if(s){for(const t in s)if(t!=="default"){const n=Object.getOwnPropertyDescriptor(s,t);Object.defineProperty(e,t,n.get?n:{enumerable:!0,get:()=>s[t]})}}return e.default=s,Object.freeze(e)}const x=R(f);function u(s){const e=s.startsWith("/"),t=[];for(const n of s.split("/"))n===""||n==="."||(n===".."?t.length>0&&t[t.length-1]!==".."?t.pop():e||t.push(".."):t.push(n));return(e?"/":"")+t.join("/")}function y(s){const e=u(s),t=e.lastIndexOf("/");return t<=0?"/":e.slice(0,t)}function T(s,e){return e.startsWith("/")?u(e):u(`${s}/${e}`)}class m{files=new Map;constructor(e={}){for(const[t,n]of Object.entries(e))this.writeFile(t,n)}writeFile(e,t){this.files.set(u(e.startsWith("/")?e:`/${e}`),t)}deleteFile(e){return this.files.delete(u(e.startsWith("/")?e:`/${e}`))}readFile(e){const t=this.files.get(u(e));return t===void 0?null:t}exists(e){return this.files.has(u(e))}listFiles(){return[...this.files.keys()].sort()}}function S(s){return s.endsWith(".tsx")?"tsx":s.endsWith(".ts")?"ts":s.endsWith(".jsx")?"jsx":s.endsWith(".json")?"json":s.endsWith(".js")||s.endsWith(".mjs")||s.endsWith(".cjs")?"js":"ts"}function O(s,e){const t=S(e);if(t==="json"){let r;try{r=JSON.parse(s)}catch(l){throw new Error(`Failed to parse JSON module ${e}: ${l.message}`)}return{code:`module.exports = ${JSON.stringify(r)};`,diagnostics:[]}}const n=d.transpileModule(s,{fileName:e,reportDiagnostics:!0,compilerOptions:{module:d.ModuleKind.CommonJS,target:d.ScriptTarget.ES2020,esModuleInterop:!0,isolatedModules:!0,jsx:t==="tsx"||t==="jsx"?d.JsxEmit.Preserve:d.JsxEmit.None,allowJs:!0}}),o=(n.diagnostics??[]).map(r=>d.flattenDiagnosticMessageText(r.messageText,`
+`));return{code:n.outputText,diagnostics:o}}const M=[".ts",".tsx",".js",".jsx",".mjs",".cjs",".json"];class p extends Error{constructor(e,t){super(`Cannot resolve module '${e}' from '${t}'`),this.specifier=e,this.from=t,this.name="ModuleResolutionError"}}class C{fs;externals;compile;cache=new Map;constructor(e){this.fs=e.fs,this.externals=e.externals??{},this.compile=e.compile??((t,n)=>O(t,n).code)}resolve(e,t){const n=T(t,e),o=[n,...M.map(r=>n+r),...M.map(r=>u(`${n}/index${r}`))];for(const r of o)if(this.fs.exists(r))return r;return null}isBare(e){return!e.startsWith("./")&&!e.startsWith("../")&&!e.startsWith("/")}require(e,t){if(this.isBare(e)){if(e in this.externals)return this.externals[e];throw new p(e,t)}const n=this.resolve(e,y(t));if(!n)throw new p(e,t);return this.load(n)}load(e){const t=u(e),n=this.cache.get(t);if(n)return n.exports;const o=this.fs.readFile(t);if(o===null)throw new Error(`File not found: ${t}`);const r={exports:{}};this.cache.set(t,r);const l=this.compile(o,t),h=c=>this.require(c,t),i=y(t),a=new Function("exports","require","module","__filename","__dirname",l);try{a(r.exports,h,r,t,i)}catch(c){if(this.cache.delete(t),c instanceof p)throw c;const g=c instanceof Error?c.message:String(c);throw new Error(`Error executing module '${t}': ${g}`)}return r.exports}run(e){const t=this.fs.exists(e)?u(e):this.resolve(e.startsWith(".")?e:`./${e}`,"/");if(!t)throw new Error(`Entry module not found: ${e}`);return this.load(t)}}function I(s){const e=[];for(const t of s.replace(/\\/g,"/").split("/"))if(!(t===""||t===".")){if(t==="..")throw new Error(`asset path escapes the project root: ${s}`);e.push(t)}if(e.length===0)throw new Error(`empty asset path: ${s}`);return e.join("/")}const b=s=>{throw new Error(`loadAsset('${s}'): this runtime has no asset loader. The host must pass RuntimeOptions.loadAsset (the sequio CLI does this for both preview and render). To avoid a local file entirely, reference a network URL instead.`)},E="@sequio/runtime:composition";function j(s){return typeof s=="object"&&s!==null&&s.__tag===E&&typeof s.build=="function"}function v(s){if(typeof s!="function")throw new Error("defineComposition expects a builder function (env) => { compositor, duration }.");return{__tag:E,build:s}}function $(s){let e=0;for(const t of s.getTracks())for(const n of t.clips)n.end>e&&(e=n.end);return e}const W={compositorOptions:{},target:"export"};class k{constructor(e,t){this.link=e,this.bundle=t}get entry(){return this.bundle.entry}get files(){return{...this.bundle.files}}toBundle(){return{files:{...this.bundle.files},entry:this.bundle.entry}}toJSON(){return this.toBundle()}async build(e={}){const t={...W,...e},n=await this.link(t).build(t),o=n.compositor,r=n.duration??$(o),l=n.audioEngine??new f.AudioEngine(new f.Timebase(30));return{compositor:o,audioEngine:l,duration:r,dispose(){l.dispose(),o.dispose()}}}async preview(e,t={}){const n=await this.build({target:"preview",...t}),{compositor:o,audioEngine:r,duration:l}=n,h=o.view;e&&e.append(h);const i=new f.RealtimeClock;i.duration=l;let a=!1;const c=i.onTick(w=>o.renderPreview(w)),g=i.onEnded(()=>{a=!1,r.pause()});return i.seek(0),o.renderPreview(0),{built:n,clock:i,view:h,duration:l,get playing(){return a},play(){a=!0,i.play(),r.play(i.currentTime)},pause(){a=!1,i.pause(),r.pause()},seek(w){i.seek(w),o.renderPreview(i.currentTime),a&&r.seek(i.currentTime)},dispose(){a=!1,c.unsubscribe(),g.unsubscribe(),i.pause(),n.dispose()}}}async export(e={},t){const n=await this.build({target:"export"});try{return await new f.Exporter(n.compositor,n.audioEngine).export({fps:30,range:[0,n.duration],audio:!1,...e},t)}finally{n.dispose()}}}const A={defineComposition:v,isComposition:j,COMPOSITION_TAG:E,loadAsset:b},D="@sequio/runtime",F="@sequio/engine",_=["/index.ts","/index.tsx","/index.js","/main.ts","/main.js"];function L(s){if(Object.keys(s).length===0)return x;class e extends x.Compositor{constructor(n){super({...n,...s})}}return{...x,Compositor:e}}function U(s){return s?s instanceof m||typeof s.readFile=="function"?s:new m(s):new m}function P(s){let e=s;if(e&&typeof e=="object"&&"default"in e&&(e=e.default),j(e))return e;if(typeof e=="function")return v(e);throw new Error("Entry module must export (as default) a Composition from defineComposition(builder) or a builder function.")}class N{fs;entry;hostExternals;compileCache=new Map;constructor(e={}){this.fs=U(e.files),this.entry=e.entry;const t=e.loadAsset??b,n={...A,loadAsset:o=>t(I(o))};this.hostExternals={[D]:n,...e.externals}}get fileSystem(){return this.fs}resolveEntry(){if(this.entry)return this.entry;for(const e of _)if(this.fs.exists(e))return e;throw new Error(`No entry module. Provide one, or add ${_.join(" / ")}. Have: ${this.fs.listFiles().join(", ")||"(no files)"}`)}toBundle(e){const t={};for(const n of this.fs.listFiles()){const o=this.fs.readFile(n);o!==null&&(t[n]=o)}return{files:t,entry:e}}compile=(e,t)=>{const n=`${t}\0${e}`;let o=this.compileCache.get(n);return o===void 0&&(o=O(e,t).code,this.compileCache.set(n,o)),o};link(e){const t={[F]:L(e.compositorOptions),...this.hostExternals},n=new C({fs:this.fs,externals:t,compile:this.compile});return P(n.run(this.resolveEntry()))}runToComposition(){return this.link({compositorOptions:{},target:"preview"})}async run(){const e=this.resolveEntry();return this.runToComposition(),new k(t=>this.link(t),this.toBundle(e))}}async function q(s,e={}){return new N({files:s,...e}).run()}exports.COMPOSITION_TAG=E;exports.Composer=k;exports.ENGINE_MODULE_ID=F;exports.InMemoryFileSystem=m;exports.ModuleResolutionError=p;exports.ModuleRuntime=C;exports.NO_ASSET_LOADER=b;exports.RUNTIME_MODULE_API=A;exports.RUNTIME_MODULE_ID=D;exports.Runtime=N;exports.compileModule=O;exports.defineComposition=v;exports.deriveDuration=$;exports.dirname=y;exports.isComposition=j;exports.joinPath=T;exports.langOf=S;exports.normalizePath=u;exports.resolveAssetPath=I;exports.runComposition=q;
+//# sourceMappingURL=index.cjs.map

package/dist/index.d.ts

@@ -0,0 +1,26 @@
+/**
+ * `@sequio/runtime` — compile and run multi-file TS/JS into a
+ * {@link Composer}.
+ *
+ * The runtime takes a set of source files (an in-memory {@link InMemoryFileSystem}
+ * or an injected real one), transpiles each with the TypeScript compiler, links
+ * them with a tiny CommonJS loader, and runs the entry. The program describes a
+ * video **imperatively** — it `new`s the engine's own classes inside a
+ * `defineComposition(builder)` (same style as the `example/` demos), so a user
+ * can bring their own `Clip` / `Effect` subclasses with no schema to keep in
+ * sync. The result is a {@link Composer} that previews and exports in the browser
+ * and whose `toBundle()` (the source files themselves) is what feeds server-side
+ * rendering — one object, three destinations.
+ *
+ * Everything here is browser-safe. A Node/real-filesystem adapter lives in
+ * `@sequio/runtime/node-fs` (imports `node:fs`, kept out of this
+ * barrel) so importing the runtime never drags Node built-ins into a bundle.
+ */
+export { type FileSystem, InMemoryFileSystem, normalizePath, dirname, joinPath, } from './vfs';
+export { compileModule, langOf, type CompileResult, type SourceLang, } from './compile';
+export { ModuleRuntime, ModuleResolutionError, type Externals, type ModuleRuntimeOptions, } from './module-runtime';
+export { type AssetLoader, resolveAssetPath, NO_ASSET_LOADER, } from './assets';
+export { defineComposition, isComposition, deriveDuration, COMPOSITION_TAG, type Composition, type CompositionBuilder, type CompositionEnv, type CompositionResult, } from './composition';
+export { Runtime, runComposition, RUNTIME_MODULE_API, RUNTIME_MODULE_ID, ENGINE_MODULE_ID, type RuntimeOptions, } from './runtime';
+export { Composer, type PreviewHandle, type RuntimeBundle, type BuiltComposition, } from './composer';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,397 @@
+import d from "typescript";
+import * as m from "@sequio/engine";
+import { AudioEngine as $, Timebase as C, RealtimeClock as M, Exporter as _ } from "@sequio/engine";
+function u(s) {
+  const t = s.startsWith("/"), e = [];
+  for (const n of s.split("/"))
+    n === "" || n === "." || (n === ".." ? e.length > 0 && e[e.length - 1] !== ".." ? e.pop() : t || e.push("..") : e.push(n));
+  return (t ? "/" : "") + e.join("/");
+}
+function g(s) {
+  const t = u(s), e = t.lastIndexOf("/");
+  return e <= 0 ? "/" : t.slice(0, e);
+}
+function k(s, t) {
+  return t.startsWith("/") ? u(t) : u(`${s}/${t}`);
+}
+class w {
+  files = /* @__PURE__ */ new Map();
+  constructor(t = {}) {
+    for (const [e, n] of Object.entries(t)) this.writeFile(e, n);
+  }
+  /** Add/replace a file. Keys are normalized to absolute paths. */
+  writeFile(t, e) {
+    this.files.set(u(t.startsWith("/") ? t : `/${t}`), e);
+  }
+  /** Remove a file; returns whether it existed. */
+  deleteFile(t) {
+    return this.files.delete(u(t.startsWith("/") ? t : `/${t}`));
+  }
+  readFile(t) {
+    const e = this.files.get(u(t));
+    return e === void 0 ? null : e;
+  }
+  exists(t) {
+    return this.files.has(u(t));
+  }
+  listFiles() {
+    return [...this.files.keys()].sort();
+  }
+}
+function F(s) {
+  return s.endsWith(".tsx") ? "tsx" : s.endsWith(".ts") ? "ts" : s.endsWith(".jsx") ? "jsx" : s.endsWith(".json") ? "json" : s.endsWith(".js") || s.endsWith(".mjs") || s.endsWith(".cjs") ? "js" : "ts";
+}
+function v(s, t) {
+  const e = F(t);
+  if (e === "json") {
+    let r;
+    try {
+      r = JSON.parse(s);
+    } catch (l) {
+      throw new Error(`Failed to parse JSON module ${t}: ${l.message}`);
+    }
+    return { code: `module.exports = ${JSON.stringify(r)};`, diagnostics: [] };
+  }
+  const n = d.transpileModule(s, {
+    fileName: t,
+    reportDiagnostics: !0,
+    compilerOptions: {
+      module: d.ModuleKind.CommonJS,
+      target: d.ScriptTarget.ES2020,
+      esModuleInterop: !0,
+      // Keep the transform isolated & fast — no cross-file inference. Matches how
+      // the linker treats each file independently.
+      isolatedModules: !0,
+      jsx: e === "tsx" || e === "jsx" ? d.JsxEmit.Preserve : d.JsxEmit.None,
+      // `require`/`module`/`exports` are provided by the linker's wrapper.
+      allowJs: !0
+    }
+  }), o = (n.diagnostics ?? []).map(
+    (r) => d.flattenDiagnosticMessageText(r.messageText, `
+`)
+  );
+  return { code: n.outputText, diagnostics: o };
+}
+const y = [".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs", ".json"];
+class x extends Error {
+  constructor(t, e) {
+    super(`Cannot resolve module '${t}' from '${e}'`), this.specifier = t, this.from = e, this.name = "ModuleResolutionError";
+  }
+}
+class S {
+  fs;
+  externals;
+  compile;
+  cache = /* @__PURE__ */ new Map();
+  constructor(t) {
+    this.fs = t.fs, this.externals = t.externals ?? {}, this.compile = t.compile ?? ((e, n) => v(e, n).code);
+  }
+  /**
+   * Resolve a relative specifier against the VFS to a concrete file path, or
+   * `null` if nothing matches. Bare specifiers are handled by {@link require}
+   * against `externals` and are not resolved here.
+   */
+  resolve(t, e) {
+    const n = k(e, t), o = [
+      n,
+      ...y.map((r) => n + r),
+      ...y.map((r) => u(`${n}/index${r}`))
+    ];
+    for (const r of o)
+      if (this.fs.exists(r)) return r;
+    return null;
+  }
+  /** Whether a specifier is bare (a package name, not a path). */
+  isBare(t) {
+    return !t.startsWith("./") && !t.startsWith("../") && !t.startsWith("/");
+  }
+  /**
+   * `require` as seen from a module located at `fromPath`. Returns the resolved
+   * module's `exports` (bare specifiers return the injected external verbatim).
+   */
+  require(t, e) {
+    if (this.isBare(t)) {
+      if (t in this.externals) return this.externals[t];
+      throw new x(t, e);
+    }
+    const n = this.resolve(t, g(e));
+    if (!n) throw new x(t, e);
+    return this.load(n);
+  }
+  /** Load (and cache) the module at an already-resolved absolute path. */
+  load(t) {
+    const e = u(t), n = this.cache.get(e);
+    if (n) return n.exports;
+    const o = this.fs.readFile(e);
+    if (o === null) throw new Error(`File not found: ${e}`);
+    const r = { exports: {} };
+    this.cache.set(e, r);
+    const l = this.compile(o, e), f = (c) => this.require(c, e), i = g(e), a = new Function(
+      "exports",
+      "require",
+      "module",
+      "__filename",
+      "__dirname",
+      l
+    );
+    try {
+      a(r.exports, f, r, e, i);
+    } catch (c) {
+      if (this.cache.delete(e), c instanceof x) throw c;
+      const h = c instanceof Error ? c.message : String(c);
+      throw new Error(`Error executing module '${e}': ${h}`);
+    }
+    return r.exports;
+  }
+  /** Load the entry module and return its `exports`. */
+  run(t) {
+    const e = this.fs.exists(t) ? u(t) : this.resolve(t.startsWith(".") ? t : `./${t}`, "/");
+    if (!e) throw new Error(`Entry module not found: ${t}`);
+    return this.load(e);
+  }
+}
+function A(s) {
+  const t = [];
+  for (const e of s.replace(/\\/g, "/").split("/"))
+    if (!(e === "" || e === ".")) {
+      if (e === "..") throw new Error(`asset path escapes the project root: ${s}`);
+      t.push(e);
+    }
+  if (t.length === 0) throw new Error(`empty asset path: ${s}`);
+  return t.join("/");
+}
+const b = (s) => {
+  throw new Error(
+    `loadAsset('${s}'): this runtime has no asset loader. The host must pass RuntimeOptions.loadAsset (the sequio CLI does this for both preview and render). To avoid a local file entirely, reference a network URL instead.`
+  );
+}, E = "@sequio/runtime:composition";
+function O(s) {
+  return typeof s == "object" && s !== null && s.__tag === E && typeof s.build == "function";
+}
+function T(s) {
+  if (typeof s != "function")
+    throw new Error("defineComposition expects a builder function (env) => { compositor, duration }.");
+  return { __tag: E, build: s };
+}
+function W(s) {
+  let t = 0;
+  for (const e of s.getTracks())
+    for (const n of e.clips) n.end > t && (t = n.end);
+  return t;
+}
+const I = { compositorOptions: {}, target: "export" };
+class R {
+  constructor(t, e) {
+    this.link = t, this.bundle = e;
+  }
+  /** The entry module path the program ran from. */
+  get entry() {
+    return this.bundle.entry;
+  }
+  /** The source files, as a fresh copy (edit freely; the Composer keeps its own). */
+  get files() {
+    return { ...this.bundle.files };
+  }
+  /**
+   * The portable code bundle to hand to server-side rendering: the same files +
+   * entry, run by a runtime on the server. This replaces "serialize a spec" —
+   * the code itself is what ships, so there's no schema to drift.
+   */
+  toBundle() {
+    return { files: { ...this.bundle.files }, entry: this.bundle.entry };
+  }
+  /** `JSON.stringify(composer)` yields the portable bundle. */
+  toJSON() {
+    return this.toBundle();
+  }
+  /**
+   * Run the builder to a fresh, initialized graph. The caller owns the result and
+   * must {@link BuiltComposition.dispose} it. `env` lets a host inject a renderer
+   * (Node) or an output scale; it defaults to the browser (`{}`).
+   */
+  async build(t = {}) {
+    const e = { ...I, ...t }, n = await this.link(e).build(e), o = n.compositor, r = n.duration ?? W(o), l = n.audioEngine ?? new $(new C(30));
+    return {
+      compositor: o,
+      audioEngine: l,
+      duration: r,
+      dispose() {
+        l.dispose(), o.dispose();
+      }
+    };
+  }
+  /**
+   * Build the graph and start a preview loop. If `container` is given the
+   * compositor's canvas is appended to it. Returns a {@link PreviewHandle} with
+   * play/pause/seek; the first frame renders immediately so the canvas is never
+   * blank before playback starts.
+   */
+  async preview(t, e = {}) {
+    const n = await this.build({ target: "preview", ...e }), { compositor: o, audioEngine: r, duration: l } = n, f = o.view;
+    t && t.append(f);
+    const i = new M();
+    i.duration = l;
+    let a = !1;
+    const c = i.onTick((p) => o.renderPreview(p)), h = i.onEnded(() => {
+      a = !1, r.pause();
+    });
+    return i.seek(0), o.renderPreview(0), {
+      built: n,
+      clock: i,
+      view: f,
+      duration: l,
+      get playing() {
+        return a;
+      },
+      play() {
+        a = !0, i.play(), r.play(i.currentTime);
+      },
+      pause() {
+        a = !1, i.pause(), r.pause();
+      },
+      seek(p) {
+        i.seek(p), o.renderPreview(i.currentTime), a && r.seek(i.currentTime);
+      },
+      dispose() {
+        a = !1, c.unsubscribe(), h.unsubscribe(), i.pause(), n.dispose();
+      }
+    };
+  }
+  /**
+   * Render the composition to a video `Blob` in the client. Builds a fresh graph,
+   * runs the engine's {@link Exporter} over `[0, duration]`, then disposes it.
+   */
+  async export(t = {}, e) {
+    const n = await this.build({ target: "export" });
+    try {
+      return await new _(n.compositor, n.audioEngine).export(
+        { fps: 30, range: [0, n.duration], audio: !1, ...t },
+        e
+      );
+    } finally {
+      n.dispose();
+    }
+  }
+}
+const N = {
+  defineComposition: T,
+  isComposition: O,
+  COMPOSITION_TAG: E,
+  loadAsset: b
+}, D = "@sequio/runtime", L = "@sequio/engine", j = ["/index.ts", "/index.tsx", "/index.js", "/main.ts", "/main.js"];
+function q(s) {
+  if (Object.keys(s).length === 0) return m;
+  class t extends m.Compositor {
+    constructor(n) {
+      super({ ...n, ...s });
+    }
+  }
+  return { ...m, Compositor: t };
+}
+function J(s) {
+  return s ? s instanceof w || typeof s.readFile == "function" ? s : new w(s) : new w();
+}
+function U(s) {
+  let t = s;
+  if (t && typeof t == "object" && "default" in t && (t = t.default), O(t)) return t;
+  if (typeof t == "function") return T(t);
+  throw new Error(
+    "Entry module must export (as default) a Composition from defineComposition(builder) or a builder function."
+  );
+}
+class B {
+  fs;
+  entry;
+  hostExternals;
+  /** Transpiled output cached across re-links (linking runs once per build). */
+  compileCache = /* @__PURE__ */ new Map();
+  constructor(t = {}) {
+    this.fs = J(t.files), this.entry = t.entry;
+    const e = t.loadAsset ?? b, n = {
+      ...N,
+      loadAsset: (o) => e(A(o))
+    };
+    this.hostExternals = {
+      [D]: n,
+      ...t.externals
+    };
+  }
+  /** The filesystem backing this runtime (add/edit files then re-`run`). */
+  get fileSystem() {
+    return this.fs;
+  }
+  resolveEntry() {
+    if (this.entry) return this.entry;
+    for (const t of j) if (this.fs.exists(t)) return t;
+    throw new Error(
+      `No entry module. Provide one, or add ${j.join(" / ")}. Have: ${this.fs.listFiles().join(", ") || "(no files)"}`
+    );
+  }
+  /** Snapshot the current files into a portable {@link RuntimeBundle}. */
+  toBundle(t) {
+    const e = {};
+    for (const n of this.fs.listFiles()) {
+      const o = this.fs.readFile(n);
+      o !== null && (e[n] = o);
+    }
+    return { files: e, entry: t };
+  }
+  compile = (t, e) => {
+    const n = `${e}\0${t}`;
+    let o = this.compileCache.get(n);
+    return o === void 0 && (o = v(t, e).code, this.compileCache.set(n, o)), o;
+  };
+  /**
+   * Compile + link + run the entry for a given environment and return the
+   * {@link Composition} it produced. Called once per build so the injected engine
+   * `Compositor` carries that environment's options (implicit `compositorOptions`)
+   * and each build gets independent module state. Transpilation is cached, so
+   * re-linking only re-executes the (cheap) module bodies.
+   */
+  link(t) {
+    const e = {
+      [L]: q(t.compositorOptions),
+      ...this.hostExternals
+    }, n = new S({ fs: this.fs, externals: e, compile: this.compile });
+    return U(n.run(this.resolveEntry()));
+  }
+  /**
+   * Compile + run the program and return the {@link Composition} its entry
+   * produced (the tagged builder), without wrapping it in a `Composer`. Uses the
+   * plain browser environment (no injected renderer).
+   */
+  runToComposition() {
+    return this.link({ compositorOptions: {}, target: "preview" });
+  }
+  /** Compile + run the program and wrap its result in a {@link Composer}. */
+  async run() {
+    const t = this.resolveEntry();
+    return this.runToComposition(), new R((e) => this.link(e), this.toBundle(t));
+  }
+}
+async function G(s, t = {}) {
+  return new B({ files: s, ...t }).run();
+}
+export {
+  E as COMPOSITION_TAG,
+  R as Composer,
+  L as ENGINE_MODULE_ID,
+  w as InMemoryFileSystem,
+  x as ModuleResolutionError,
+  S as ModuleRuntime,
+  b as NO_ASSET_LOADER,
+  N as RUNTIME_MODULE_API,
+  D as RUNTIME_MODULE_ID,
+  B as Runtime,
+  v as compileModule,
+  T as defineComposition,
+  W as deriveDuration,
+  g as dirname,
+  O as isComposition,
+  k as joinPath,
+  F as langOf,
+  u as normalizePath,
+  A as resolveAssetPath,
+  G as runComposition
+};
+//# sourceMappingURL=index.js.map

package/dist/module-runtime.d.ts

@@ -0,0 +1,41 @@
+import { FileSystem } from './vfs';
+/** A module value keyed by a bare specifier the sandbox can `require`. */
+export type Externals = Record<string, unknown>;
+export interface ModuleRuntimeOptions {
+    fs: FileSystem;
+    /** Bare-specifier → module value (e.g. the runtime API, the engine). */
+    externals?: Externals;
+    /** Transform a source file to CommonJS. Defaults to {@link compileModule}. */
+    compile?: (code: string, fileName: string) => string;
+}
+/** A resolution failure that names the specifier and the importer. */
+export declare class ModuleResolutionError extends Error {
+    readonly specifier: string;
+    readonly from: string;
+    constructor(specifier: string, from: string);
+}
+export declare class ModuleRuntime {
+    private readonly fs;
+    private readonly externals;
+    private readonly compile;
+    private readonly cache;
+    constructor(options: ModuleRuntimeOptions);
+    /**
+     * Resolve a relative specifier against the VFS to a concrete file path, or
+     * `null` if nothing matches. Bare specifiers are handled by {@link require}
+     * against `externals` and are not resolved here.
+     */
+    resolve(specifier: string, fromDir: string): string | null;
+    /** Whether a specifier is bare (a package name, not a path). */
+    private isBare;
+    /**
+     * `require` as seen from a module located at `fromPath`. Returns the resolved
+     * module's `exports` (bare specifiers return the injected external verbatim).
+     */
+    require(specifier: string, fromPath: string): unknown;
+    /** Load (and cache) the module at an already-resolved absolute path. */
+    load(path: string): unknown;
+    /** Load the entry module and return its `exports`. */
+    run(entryPath: string): unknown;
+}
+//# sourceMappingURL=module-runtime.d.ts.map

package/dist/node-fs.cjs

@@ -0,0 +1,2 @@
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const r=require("node:fs"),o=require("node:path");function l(s,t){const e=t.replace(/^\/+/,"");return o.resolve(s,e)}function u(s,t){return"/"+o.relative(s,t).split(o.sep).join("/")}class a{constructor(t){this.rootDir=t}readFile(t){const e=l(this.rootDir,t);try{return!r.existsSync(e)||!r.statSync(e).isFile()?null:r.readFileSync(e,"utf8")}catch{return null}}exists(t){const e=l(this.rootDir,t);try{return r.existsSync(e)&&r.statSync(e).isFile()}catch{return!1}}listFiles(){const t=[],e=n=>{for(const i of r.readdirSync(n,{withFileTypes:!0})){if(i.name==="node_modules"||i.name.startsWith("."))continue;const c=o.join(n,i.name);i.isDirectory()?e(c):i.isFile()&&t.push(u(this.rootDir,c))}};try{e(this.rootDir)}catch{}return t.sort()}}exports.NodeFileSystem=a;
+//# sourceMappingURL=node-fs.cjs.map

package/dist/node-fs.d.ts

@@ -0,0 +1,9 @@
+import { FileSystem } from './vfs';
+export declare class NodeFileSystem implements FileSystem {
+    private readonly rootDir;
+    constructor(rootDir: string);
+    readFile(path: string): string | null;
+    exists(path: string): boolean;
+    listFiles(): string[];
+}
+//# sourceMappingURL=node-fs.d.ts.map

package/dist/node-fs.js

@@ -0,0 +1,48 @@
+import { existsSync as n, statSync as l, readFileSync as u, readdirSync as a } from "node:fs";
+import { join as f, resolve as h, relative as y, sep as m } from "node:path";
+function c(i, t) {
+  const r = t.replace(/^\/+/, "");
+  return h(i, r);
+}
+function d(i, t) {
+  return "/" + y(i, t).split(m).join("/");
+}
+class D {
+  constructor(t) {
+    this.rootDir = t;
+  }
+  readFile(t) {
+    const r = c(this.rootDir, t);
+    try {
+      return !n(r) || !l(r).isFile() ? null : u(r, "utf8");
+    } catch {
+      return null;
+    }
+  }
+  exists(t) {
+    const r = c(this.rootDir, t);
+    try {
+      return n(r) && l(r).isFile();
+    } catch {
+      return !1;
+    }
+  }
+  listFiles() {
+    const t = [], r = (s) => {
+      for (const e of a(s, { withFileTypes: !0 })) {
+        if (e.name === "node_modules" || e.name.startsWith(".")) continue;
+        const o = f(s, e.name);
+        e.isDirectory() ? r(o) : e.isFile() && t.push(d(this.rootDir, o));
+      }
+    };
+    try {
+      r(this.rootDir);
+    } catch {
+    }
+    return t.sort();
+  }
+}
+export {
+  D as NodeFileSystem
+};
+//# sourceMappingURL=node-fs.js.map

package/dist/runtime.d.ts

@@ -0,0 +1,93 @@
+import { CompositorOptions } from '@sequio/engine';
+import { Composer } from './composer';
+import { Composition, CompositionEnv, defineComposition, isComposition } from './composition';
+import { Externals } from './module-runtime';
+import { FileSystem } from './vfs';
+import { AssetLoader } from './assets';
+/**
+ * The module object exposed to sandboxed code as `@sequio/runtime`.
+ *
+ * `loadAsset` here is the *default* (no host loader → throws {@link NO_ASSET_LOADER});
+ * a {@link Runtime} instance overrides it with the host's {@link AssetLoader} so a
+ * composition's `loadAsset('./clip.mp4')` reaches real bytes.
+ */
+export declare const RUNTIME_MODULE_API: {
+    defineComposition: typeof defineComposition;
+    isComposition: typeof isComposition;
+    COMPOSITION_TAG: "@sequio/runtime:composition";
+    loadAsset: AssetLoader;
+};
+/** Bare specifier under which the authoring API is injected. */
+export declare const RUNTIME_MODULE_ID = "@sequio/runtime";
+/** Bare specifier under which the engine namespace is injected. */
+export declare const ENGINE_MODULE_ID = "@sequio/engine";
+export interface RuntimeOptions {
+    /** Source files. Either a ready {@link FileSystem} or a path→content map. */
+    files?: FileSystem | Record<string, string>;
+    /** Entry module path. @default '/index.ts' (falls back to `/index.js`, `/main.ts`). */
+    entry?: string;
+    /**
+     * Extra bare modules user code may `import`. Merged over the built-in
+     * `@sequio/engine` and `@sequio/runtime` modules
+     * (host entries win on key collision), so a host can expose more libraries.
+     */
+    externals?: Externals;
+    /**
+     * Resolver for **local media assets** a composition pulls in with
+     * `loadAsset('./clip.mp4')` (imported from `@sequio/runtime`). The host maps a
+     * project-relative path to its bytes as a `Blob`; the runtime normalizes the
+     * path ({@link resolveAssetPath}) before calling it. Left unset, `loadAsset`
+     * throws a clear error — assets are opt-in and never bundled. See
+     * [`assets.ts`](./assets.ts).
+     */
+    loadAsset?: AssetLoader;
+}
+/**
+ * A copy of the engine namespace whose `Compositor` folds `overrides` into every
+ * construction. This is how `env.compositorOptions` is injected **implicitly**:
+ * user code writes a plain `new Compositor({ width, height, timebase })` — exactly
+ * like a demo — and a host (a Node WebGPU renderer, an output scale) still reaches
+ * it. Overrides win on conflict so a server's `createRenderer` takes precedence.
+ * With no overrides (the browser default) the real namespace is returned as-is.
+ */
+export declare function engineForEnv(overrides: Partial<CompositorOptions>): Externals[string];
+export declare class Runtime {
+    private readonly fs;
+    private readonly entry;
+    private readonly hostExternals;
+    /** Transpiled output cached across re-links (linking runs once per build). */
+    private readonly compileCache;
+    constructor(options?: RuntimeOptions);
+    /** The filesystem backing this runtime (add/edit files then re-`run`). */
+    get fileSystem(): FileSystem;
+    private resolveEntry;
+    /** Snapshot the current files into a portable {@link RuntimeBundle}. */
+    private toBundle;
+    private compile;
+    /**
+     * Compile + link + run the entry for a given environment and return the
+     * {@link Composition} it produced. Called once per build so the injected engine
+     * `Compositor` carries that environment's options (implicit `compositorOptions`)
+     * and each build gets independent module state. Transpilation is cached, so
+     * re-linking only re-executes the (cheap) module bodies.
+     */
+    link(env: CompositionEnv): Composition;
+    /**
+     * Compile + run the program and return the {@link Composition} its entry
+     * produced (the tagged builder), without wrapping it in a `Composer`. Uses the
+     * plain browser environment (no injected renderer).
+     */
+    runToComposition(): Composition;
+    /** Compile + run the program and wrap its result in a {@link Composer}. */
+    run(): Promise<Composer>;
+}
+/**
+ * One-shot convenience: build a {@link Runtime} from `files`/options and run it.
+ *
+ * ```ts
+ * const composer = await runComposition({ '/index.ts': "export default defineComposition(async () => {…})" });
+ * await composer.preview(document.body);
+ * ```
+ */
+export declare function runComposition(files: RuntimeOptions['files'], options?: Omit<RuntimeOptions, 'files'>): Promise<Composer>;
+//# sourceMappingURL=runtime.d.ts.map

package/dist/vfs.d.ts

@@ -0,0 +1,44 @@
+/**
+ * A minimal **virtual filesystem** the module runtime reads source files from.
+ *
+ * The runtime never touches `node:fs` directly — it resolves and reads modules
+ * through this interface. That keeps the core browser-safe (the studio "code
+ * mode" runs entirely in the tab against an {@link InMemoryFileSystem}) while
+ * letting a host inject a **real** filesystem instead: any object satisfying
+ * {@link FileSystem} works, so a Node caller can wrap `node:fs` (see
+ * `src/node-fs.ts`, kept out of the browser barrel).
+ *
+ * Paths are POSIX-style, absolute from a virtual root `/`. The runtime
+ * normalizes relative imports to absolute paths before calling {@link readFile}.
+ */
+export interface FileSystem {
+    /** Return the file's text, or `null` if it doesn't exist. */
+    readFile(path: string): string | null;
+    /** Whether a regular file exists at `path`. */
+    exists(path: string): boolean;
+    /** Every file path this filesystem can serve (used for diagnostics). */
+    listFiles(): string[];
+}
+/** Collapse `.`/`..` segments and force a single leading `/`. */
+export declare function normalizePath(path: string): string;
+/** Directory portion of a normalized path (`/a/b/c.ts` → `/a/b`). */
+export declare function dirname(path: string): string;
+/** Join a base directory with a (possibly relative) specifier, normalized. */
+export declare function joinPath(base: string, specifier: string): string;
+/**
+ * An in-memory {@link FileSystem} backed by a plain path→content map. This is
+ * the default for the browser (the code-mode editor keeps its files here) and
+ * makes the module runtime unit-testable with no disk.
+ */
+export declare class InMemoryFileSystem implements FileSystem {
+    private readonly files;
+    constructor(files?: Record<string, string>);
+    /** Add/replace a file. Keys are normalized to absolute paths. */
+    writeFile(path: string, content: string): void;
+    /** Remove a file; returns whether it existed. */
+    deleteFile(path: string): boolean;
+    readFile(path: string): string | null;
+    exists(path: string): boolean;
+    listFiles(): string[];
+}
+//# sourceMappingURL=vfs.d.ts.map

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@sequio/runtime",
+  "version": "0.1.0",
+  "description": "Compile and run multi-file TS/JS (virtual or injected real filesystem) into a Composer that renders/exports in the client or feeds server-side rendering.",
+  "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/runtime"
+  },
+  "bugs": {
+    "url": "https://github.com/slightc/sequio/issues"
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./node-fs": {
+      "types": "./dist/node-fs.d.ts",
+      "import": "./dist/node-fs.js",
+      "require": "./dist/node-fs.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.map"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "typescript",
+    "compile",
+    "virtual-filesystem",
+    "video-editor",
+    "composer"
+  ],
+  "dependencies": {
+    "typescript": "^5.7.0",
+    "@sequio/engine": "^0.1.1"
+  },
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "verify:runtime": "node scripts/verify-page.cjs example/runtime-test.html __RUNTIME_TEST__ \"runtime compile+run\""
+  }
+}