@sequio/server 0.1.0

package/dist/index.js

@@ -0,0 +1,166 @@
+import { TextClip as g, ShapeClip as w, ImageSource as y, ImageClip as b, VideoSource as I, VideoClip as v, BlurEffect as S, ColorEffect as x, Timebase as k, Compositor as C, VisualTrack as O, AudioEngine as p, AudioSource as z, AudioClip as E, easeInOutCubic as F, easeOutCubic as T, easeInCubic as A, easeInOutQuad as H, easeOutQuad as M, easeInQuad as W, hold as Q, linear as R, fonts as d } from "@sequio/engine";
+const V = {
+  linear: R,
+  hold: Q,
+  easeInQuad: W,
+  easeOutQuad: M,
+  easeInOutQuad: H,
+  easeInCubic: A,
+  easeOutCubic: T,
+  easeInOutCubic: F
+};
+function s(t, e) {
+  e !== void 0 && (typeof e == "object" && e !== null && "keyframes" in e ? t.setKeyframes(e.keyframes.map((o) => ({ time: o.time, value: o.value, easing: o.easing ? V[o.easing] : void 0 }))) : t.setStatic(e));
+}
+function c(t) {
+  if (t.type === "blur") {
+    const o = new S();
+    return t.strength !== void 0 && o.strength.setStatic(t.strength), o;
+  }
+  const e = new x();
+  return t.brightness !== void 0 && e.brightness.setStatic(t.brightness), t.contrast !== void 0 && e.contrast.setStatic(t.contrast), t.saturation !== void 0 && e.saturation.setStatic(t.saturation), e;
+}
+function B(t, e) {
+  t.start = e.start, t.end = e.end, e.sourceIn !== void 0 && (t.sourceIn = e.sourceIn), e.sourceOut !== void 0 && (t.sourceOut = e.sourceOut), e.speed !== void 0 && (t.speed = e.speed), e.blendMode && (t.blendMode = e.blendMode), s(t.opacity, e.opacity);
+  const o = e.transform;
+  o && (o.anchor && t.transform.anchor.setStatic(o.anchor), s(t.transform.position, o.position), s(t.transform.scale, o.scale), s(t.transform.rotation, o.rotation));
+  for (const i of e.effects ?? []) t.effects.push(c(i));
+}
+async function G(t, e) {
+  let o;
+  if (t.type === "text")
+    o = new g({ text: t.text, fontFamily: t.fontFamily, fill: t.fill }), s(o.fontSize, t.fontSize);
+  else if (t.type === "shape")
+    o = new w(t.shape);
+  else if (t.type === "image") {
+    const i = new y({ src: t.src });
+    await i.load(), e.push(i), o = new b(i);
+  } else {
+    const i = new I({ src: t.src, cacheFrames: t.cacheFrames, lookahead: t.lookahead });
+    await i.load(), e.push(i), o = new v(i);
+  }
+  return B(o, t), o;
+}
+function j(t) {
+  let e = 0;
+  for (const o of t.tracks ?? []) for (const i of o.clips) e = Math.max(e, i.end);
+  for (const o of t.audio ?? []) e = Math.max(e, o.end);
+  return e;
+}
+async function D(t) {
+  for (const e of t ?? [])
+    e.google ? await d.loadGoogleFont({ family: e.family, weights: e.google.weights, italic: e.google.italic }) : e.src && await d.load({ family: e.family, src: e.src });
+  await d.ready();
+}
+async function N(t, e = {}) {
+  const o = new k(t.fps), i = new C({
+    width: t.width,
+    height: t.height,
+    timebase: o,
+    background: t.background ?? 0,
+    origin: t.origin,
+    createRenderer: e.createRenderer,
+    resolution: e.resolution
+  });
+  await i.init(), await (e.loadFonts ?? D)(t.fonts);
+  const f = [];
+  for (const n of t.tracks ?? []) {
+    if (n.clips.length === 0) continue;
+    const r = new O();
+    r.zIndex = n.zIndex ?? 0;
+    for (const a of n.clips) r.add(await G(a, f));
+    i.addTrack(r);
+  }
+  for (const n of t.effects ?? []) i.effects.push(c(n));
+  const u = new p(o), l = (t.audio?.length ?? 0) > 0;
+  for (const n of t.audio ?? []) {
+    const r = new z({ src: n.src });
+    await r.load(), f.push(r);
+    const a = new E();
+    a.start = n.start, a.end = n.end, n.sourceIn !== void 0 && (a.sourceIn = n.sourceIn), n.gain !== void 0 && a.gain.setStatic(n.gain), n.fadeIn !== void 0 && (a.fadeIn = n.fadeIn), n.fadeOut !== void 0 && (a.fadeOut = n.fadeOut), u.schedule(a, r);
+  }
+  const h = t.range ?? [0, j(t)], m = { audio: l, ...t.export };
+  return {
+    compositor: i,
+    audioEngine: u,
+    range: h,
+    exportOptions: m,
+    hasAudio: l,
+    dispose() {
+      for (const n of f) n.dispose();
+      i.dispose();
+    }
+  };
+}
+function P() {
+  return {
+    width: 320,
+    height: 180,
+    fps: 30,
+    background: 1052692,
+    range: [0, 2],
+    tracks: [
+      // Background: a full-frame teal rectangle.
+      {
+        zIndex: 0,
+        clips: [
+          {
+            type: "shape",
+            shape: { kind: "rect", width: 320, height: 180, fill: 1013358 },
+            start: 0,
+            end: 2,
+            transform: { anchor: [0, 0], position: [0, 0] }
+          }
+        ]
+      },
+      // Foreground: a circle sliding left→right while the title fades in.
+      {
+        zIndex: 1,
+        clips: [
+          {
+            type: "shape",
+            shape: { kind: "ellipse", width: 48, height: 48, fill: 16096779 },
+            start: 0,
+            end: 2,
+            transform: {
+              anchor: [0.5, 0.5],
+              position: {
+                keyframes: [
+                  { time: 0, value: [40, 180 / 2] },
+                  { time: 2, value: [280, 180 / 2], easing: "easeInOutCubic" }
+                ]
+              }
+            },
+            // A filter (shader) — renders on the server only via Route B's WebGPU backend.
+            effects: [{ type: "blur", strength: 4 }]
+          },
+          {
+            type: "text",
+            text: "Server-Side Render",
+            fontSize: 26,
+            fill: 16766474,
+            // coloured text — exercises the BGRA swizzle on the Node path
+            start: 0,
+            end: 2,
+            transform: { anchor: [0.5, 0.5], position: [320 / 2, 40] },
+            opacity: {
+              keyframes: [
+                { time: 0, value: 0 },
+                { time: 0.6, value: 1, easing: "easeOutQuad" }
+              ]
+            }
+          }
+        ]
+      }
+    ],
+    export: { container: "mp4", videoCodec: "avc", bitrate: 2e6 }
+  };
+}
+export {
+  G as buildClip,
+  c as buildEffect,
+  N as buildTimeline,
+  P as sampleTimeline,
+  j as timelineEnd
+};
+//# sourceMappingURL=index.js.map

package/dist/route-b/env.d.ts

@@ -0,0 +1,15 @@
+import { AutoDetectOptions, MediabunnyModule, Renderer } from '@sequio/engine';
+/** The mediabunny instance carrying the node-av encoders. Call after {@link setupNodeEnvironment}. */
+export declare function getMediabunny(): MediabunnyModule;
+/**
+ * Install the browser-global shims and return the GPU handle. Idempotent.
+ * Throws if no WebGPU adapter is available (no GPU and no software Vulkan
+ * driver) — the caller should surface that as "Route B unavailable on this host".
+ */
+export declare function setupNodeEnvironment(): Promise<void>;
+/**
+ * A {@link CompositorOptions.createRenderer} factory that builds a PixiJS WebGPU
+ * renderer in Node. Requires {@link setupNodeEnvironment} to have run.
+ */
+export declare function createNodeWebGPURenderer(options: Partial<AutoDetectOptions>): Promise<Renderer>;
+//# sourceMappingURL=env.d.ts.map

package/dist/route-b/export-node.d.ts

@@ -0,0 +1,46 @@
+import { AudioEngine, Compositor, Renderer } from '@sequio/engine';
+export interface NodeExportOptions {
+    fps: number;
+    range: [number, number];
+    /** Output file path. The extension is corrected to match the encoded container. */
+    out: string;
+    /** Preferred container; falls back to what node-av can encode. */
+    container?: 'mp4' | 'webm';
+    videoCodec?: string;
+    bitrate?: number;
+    /** Mux the {@link AudioEngine}'s offline mix as an audio track. */
+    audio?: {
+        engine: AudioEngine;
+        codec?: string;
+        bitrate?: number;
+    };
+    onProgress?: (p: number) => void;
+}
+/**
+ * Render a single frame at `t` and return it as tightly-packed RGBA bytes plus
+ * its pixel dimensions. Same await-prepare → render → GPU-readback path as the
+ * per-frame loop in {@link renderTimelineToFile}, factored out for the
+ * single-frame (image) export that `sequio frame` uses. The `renderer` must be
+ * the WebGPU renderer backing `compositor`.
+ */
+export declare function renderFrameRGBA(compositor: Compositor, renderer: Renderer, t: number): Promise<{
+    rgba: Uint8Array;
+    width: number;
+    height: number;
+}>;
+/**
+ * Render `compositor`'s timeline over `range` at `fps` and write a video file to
+ * `out` (extension corrected to the container actually encoded). The `renderer`
+ * must be the WebGPU renderer backing the compositor, since we read frames off
+ * its GPU. Tries the preferred codec first, falling back through VP9/VP8/WebM if
+ * node-av can't encode it.
+ */
+export declare function renderTimelineToFile(compositor: Compositor, renderer: Renderer, opts: NodeExportOptions): Promise<{
+    frames: number;
+    bytes: number;
+    out: string;
+    container: string;
+    videoCodec: string;
+    audio: boolean;
+}>;
+//# sourceMappingURL=export-node.d.ts.map

package/dist/route-b/fonts-node.d.ts

@@ -0,0 +1,24 @@
+import { FontSpec } from '../src/timeline';
+/**
+ * Extract the font-file URLs from a Google Fonts css2 stylesheet. Pure and
+ * testable — css2 returns one `@font-face { … src: url(X) … }` per subset/weight.
+ */
+export declare function parseGoogleFontUrls(css: string): string[];
+/** Register every font a timeline references with `@napi-rs/canvas`'s GlobalFonts. */
+export declare function loadFontsNode(specs: FontSpec[] | undefined): Promise<void>;
+/**
+ * Bridge the engine's {@link FontManager} to Node so a composition's own font
+ * loads reach the text rasterizer.
+ *
+ * In a browser, `fonts.load(...)` / `fonts.loadGoogleFont(...)` register into
+ * `document.fonts`, which PixiJS's text measurement reads. In Node those calls
+ * are no-ops (text is drawn via `@napi-rs/canvas`, whose fonts come from
+ * `GlobalFonts`). The `TimelineSpec` route sidesteps this by taking a separate
+ * `spec.fonts` list; the **code/bundle** route has no such list — the composition
+ * loads fonts imperatively — so we retarget `FontManager`'s (overridable) load
+ * hooks at {@link loadFontsNode}. After this runs, the same `fonts.load*` call a
+ * composition makes renders identically in the browser preview and the Node
+ * render (contract #3). Idempotent; call once after {@link setupNodeEnvironment}.
+ */
+export declare function bridgeFontManagerToNode(): void;
+//# sourceMappingURL=fonts-node.d.ts.map

package/dist/route-b/frame-node.d.ts

@@ -0,0 +1,28 @@
+import { AssetLoader, Externals, RuntimeBundle } from '@sequio/runtime';
+export interface RenderFrameNodeOptions {
+    /** Output image path. The extension is corrected to `.png`. */
+    out: string;
+    /** Time (seconds) to sample. Clamped to `[0, duration]`. @default 0 */
+    time?: number;
+    /** Output resolution multiplier (N× the composition size). @default 1 */
+    scale?: number;
+    /** Extra bare modules the composition may `import` (e.g. `gsap`); see {@link renderBundleToFile}. */
+    externals?: Externals;
+    /** Resolver for local media assets (`loadAsset('./clip.mp4')`); see {@link renderBundleToFile}. */
+    loadAsset?: AssetLoader;
+}
+export interface RenderFrameNodeResult {
+    /** The written file path (extension corrected to `.png`). */
+    out: string;
+    /** The time actually sampled (the request, clamped to `[0, duration]`). */
+    time: number;
+    width: number;
+    height: number;
+    bytes: number;
+}
+/**
+ * Compile + run `bundle`, seek to `opts.time`, and write that single frame to
+ * `opts.out` (as PNG). The built graph is disposed before returning.
+ */
+export declare function renderBundleFrameToFile(bundle: RuntimeBundle, opts: RenderFrameNodeOptions): Promise<RenderFrameNodeResult>;
+//# sourceMappingURL=frame-node.d.ts.map

package/dist/route-b/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * `@sequio/server/route-b` — the pure-Node (PixiJS WebGPU) server-render route,
+ * as a programmatic API. **Node-only**: importing this pulls in the Node
+ * environment adapter (`env.ts` → pixi.js, jsdom, @napi-rs/canvas, webgpu,
+ * @mediabunny/server), so it is deliberately kept out of the browser-safe main
+ * barrel (`@sequio/server`) and reached via this subpath, mirroring how the
+ * runtime keeps `@sequio/runtime/node-fs` separate.
+ *
+ * Needs a WebGPU-capable host: a real GPU or a software Vulkan driver (Mesa
+ * lavapipe). See `docs/server-side-rendering.md`.
+ */
+export { setupNodeEnvironment, createNodeWebGPURenderer, getMediabunny } from './env';
+export { renderTimelineToFile, renderFrameRGBA, type NodeExportOptions } from './export-node';
+export { loadFontsNode, bridgeFontManagerToNode } from './fonts-node';
+export { renderBundleToFile, type RenderBundleNodeOptions, type RenderBundleNodeResult, } from './render-bundle';
+export { renderBundleFrameToFile, type RenderFrameNodeOptions, type RenderFrameNodeResult, } from './frame-node';
+//# sourceMappingURL=index.d.ts.map

package/dist/route-b/render-bundle.d.ts

@@ -0,0 +1,41 @@
+import { AssetLoader, Externals, RuntimeBundle } from '@sequio/runtime';
+export interface RenderBundleNodeOptions {
+    /** Output file path. The extension is corrected to match the encoded container. */
+    out: string;
+    /** Output resolution multiplier (N× the composition size). @default 1 */
+    scale?: number;
+    /** Preferred container; falls back to what node-av can encode. */
+    container?: 'mp4' | 'webm';
+    videoCodec?: string;
+    bitrate?: number;
+    onProgress?: (p: number) => void;
+    /**
+     * Extra bare modules the composition may `import` (merged over the built-in
+     * `@sequio/engine` / `@sequio/runtime`). This is the seam a host uses to make a
+     * third-party library — e.g. `gsap` — resolvable to user code in the Node
+     * render, exactly as it is in the browser preview. The server itself pulls in
+     * nothing: the caller (`sequio render`) owns the library and passes it here.
+     */
+    externals?: Externals;
+    /**
+     * Resolver for a composition's **local media assets** (`loadAsset('./clip.mp4')`).
+     * Passed straight to the {@link Runtime}; `sequio render` supplies a loader that
+     * reads the files off disk next to the entry, so a local `image`/`video` renders
+     * the same as it previews (contract #3). Assets are never part of the bundle.
+     */
+    loadAsset?: AssetLoader;
+}
+export interface RenderBundleNodeResult {
+    frames: number;
+    bytes: number;
+    out: string;
+    container: string;
+    videoCodec: string;
+    audio: boolean;
+}
+/**
+ * Compile + run `bundle` and render it to `opts.out` via the Node WebGPU pipeline.
+ * The caller owns nothing — the built graph is disposed before returning.
+ */
+export declare function renderBundleToFile(bundle: RuntimeBundle, opts: RenderBundleNodeOptions): Promise<RenderBundleNodeResult>;
+//# sourceMappingURL=render-bundle.d.ts.map

package/dist/route-b.js

@@ -0,0 +1,326 @@
+import { createRequire as J } from "node:module";
+import { exportFrameTimes as Q, FontManager as X, buildGoogleCss2Url as Y } from "@sequio/engine";
+import { Runtime as H } from "@sequio/runtime";
+let W = !1;
+const L = Symbol("napi-canvas");
+let I = null;
+function K() {
+  if (!I) throw new Error("getMediabunny() before setupNodeEnvironment()");
+  return I;
+}
+async function q() {
+  if (W) return;
+  const { JSDOM: a } = await import("jsdom"), e = new a("<!doctype html><html><body></body></html>");
+  for (const o of ["window", "document", "navigator", "HTMLElement", "Node", "DOMParser"])
+    if (globalThis[o] === void 0 && e.window[o] !== void 0)
+      try {
+        globalThis[o] = e.window[o];
+      } catch {
+      }
+  const t = globalThis;
+  t.requestAnimationFrame ??= (o) => setTimeout(() => o(Date.now()), 16), t.cancelAnimationFrame ??= (o) => clearTimeout(o), t.addEventListener ??= () => {
+  }, t.removeEventListener ??= () => {
+  };
+  const r = await import("webgpu"), d = r.create([]);
+  for (const [o, n] of Object.entries(r.globals ?? {}))
+    if (globalThis[o] === void 0)
+      try {
+        globalThis[o] = n;
+      } catch {
+      }
+  if (Object.defineProperty(globalThis.navigator, "gpu", { value: d, configurable: !0 }), !await d.requestAdapter())
+    throw new Error(
+      "No WebGPU adapter — Route B needs a GPU or a software Vulkan driver (install Mesa lavapipe: `apt install mesa-vulkan-drivers`)."
+    );
+  const s = r.globals, f = s?.GPURenderPassEncoder?.prototype;
+  if (f?.setBindGroup) {
+    const o = f.setBindGroup;
+    f.setBindGroup = function(n, ...i) {
+      return o.call(this, Number(n), ...i);
+    };
+  }
+  const l = s?.GPUQueue?.prototype;
+  if (l?.copyExternalImageToTexture && l.writeTexture) {
+    const o = l.copyExternalImageToTexture;
+    l.copyExternalImageToTexture = function(...n) {
+      const i = n[0], g = n[1], m = i?.source;
+      if (m && m[L]) {
+        const y = m.width, x = m.height, S = m.getContext("2d").getImageData(0, 0, y, x).data, j = String(g.texture?.format ?? "").startsWith("bgra"), _ = g.premultipliedAlpha === !0, A = new Uint8Array(y * x * 4);
+        for (let k = 0; k < y * x; k++) {
+          const v = k * 4;
+          let R = S[v], U = S[v + 1], E = S[v + 2];
+          const G = S[v + 3];
+          _ && (R = (R * G + 127) / 255 | 0, U = (U * G + 127) / 255 | 0, E = (E * G + 127) / 255 | 0), j ? (A[v] = E, A[v + 1] = U, A[v + 2] = R, A[v + 3] = G) : (A[v] = R, A[v + 1] = U, A[v + 2] = E, A[v + 3] = G);
+        }
+        return this.writeTexture(
+          { texture: g.texture, mipLevel: g.mipLevel ?? 0, origin: g.origin ?? {}, aspect: g.aspect ?? "all" },
+          A,
+          { offset: 0, bytesPerRow: y * 4, rowsPerImage: x },
+          { width: y, height: x, depthOrArrayLayers: 1 }
+        );
+      }
+      return o.apply(this, n);
+    };
+  }
+  const { createCanvas: h, loadImage: p } = await import("@napi-rs/canvas"), w = (o, n) => {
+    const i = h(o || 1, n || 1);
+    i[L] = !0;
+    const g = i.getContext.bind(i);
+    return i.getContext = (m, ...y) => m === "2d" ? g("2d", ...y) : null, i.addEventListener = () => {
+    }, i.removeEventListener = () => {
+    }, i.style = {}, i.getBoundingClientRect = () => ({
+      x: 0,
+      y: 0,
+      top: 0,
+      left: 0,
+      right: i.width,
+      bottom: i.height,
+      width: i.width,
+      height: i.height
+    }), i;
+  }, b = globalThis;
+  b.createImageBitmap === void 0 && (b.createImageBitmap = async (o) => {
+    const n = o;
+    if (!n?.arrayBuffer) return o;
+    const { Buffer: i } = await import("node:buffer"), g = await p(i.from(await n.arrayBuffer())), m = w(g.width, g.height);
+    return m.getContext("2d").drawImage(g, 0, 0), m;
+  });
+  const B = await import("pixi.js"), T = globalThis.DOMParser;
+  B.DOMAdapter.set({
+    createCanvas: (o, n) => w(o, n),
+    createImage: () => w(1, 1),
+    getCanvasRenderingContext2D: () => h(1, 1).getContext("2d").constructor,
+    getWebGLRenderingContext: () => function() {
+    },
+    getNavigator: () => globalThis.navigator,
+    getBaseUrl: () => "http://localhost/",
+    getFontFaceSet: () => {
+    },
+    fetch: (...o) => fetch(...o),
+    parseXML: (o) => new T().parseFromString(o, "text/xml")
+  });
+  const C = B.CanvasSource.test.bind(B.CanvasSource);
+  B.CanvasSource.test = ((o) => !!(o && o[L]) || C(o));
+  const u = J(import.meta.url), { registerMediabunnyServer: F } = u("@mediabunny/server");
+  F(), I = u("mediabunny");
+  const { setMediabunnyModule: O, setFrameImageExtractor: P } = await import("@sequio/engine");
+  O(I), P(async (o) => {
+    const n = o, i = n.codedWidth, g = n.codedHeight, m = new Uint8Array(n.allocationSize({ format: "RGBA" }));
+    await n.copyTo(m, { format: "RGBA" });
+    const y = w(i, g), x = y.getContext("2d"), D = x.createImageData(i, g);
+    return D.data.set(m), x.putImageData(D, 0, 0), y;
+  });
+  const M = await import("node-web-audio-api");
+  for (const o of ["OfflineAudioContext", "AudioContext", "AudioBuffer"])
+    globalThis[o] === void 0 && M[o] && (globalThis[o] = M[o]);
+  W = !0;
+}
+async function V(a) {
+  const { WebGPURenderer: e } = await import("pixi.js"), t = new e();
+  return await t.init({
+    width: a.width,
+    height: a.height,
+    background: a.background,
+    backgroundAlpha: 1,
+    // MSAA for shape/text edges. Export renders into antialiased RenderTextures
+    // (RT-level MSAA is what actually smooths the pixels read back), but honor the
+    // compositor's choice here too so the renderer and its targets agree.
+    antialias: a.antialias ?? !0,
+    // Honor the compositor's resolution. Text and other Canvas-rasterized content
+    // (PIXI.Text glyph atlases) are generated at the *renderer's* resolution, so
+    // dropping it here rasterizes glyphs at 1× and upscales them into a higher-res
+    // frame — blurry text at `--scale 2`. Match the render-texture resolution.
+    resolution: a.resolution ?? 1
+    // No canvas presentation — we render to RenderTextures and read them back.
+  }), t;
+}
+const Z = (a) => a === "vp8" || a === "vp9" || a === "av1";
+function ee(a) {
+  const e = [];
+  a.codec ? e.push({ container: a.container ?? (Z(a.codec) ? "webm" : "mp4"), codec: a.codec }) : a.container === "webm" && e.push({ container: "webm", codec: "vp9" }), e.push(
+    { container: "mp4", codec: "avc" },
+    { container: "webm", codec: "vp9" },
+    { container: "webm", codec: "vp8" },
+    { container: "mp4", codec: "av1" }
+  );
+  const t = /* @__PURE__ */ new Set();
+  return e.filter((r) => t.has(r.codec) ? !1 : (t.add(r.codec), !0));
+}
+async function z(a, e) {
+  const t = a.gpu.device, r = a.texture.getGpuSource(e), d = e.pixelWidth, c = e.pixelHeight, s = globalThis, f = Math.ceil(d * 4 / 256) * 256, l = t.createBuffer({ size: f * c, usage: s.GPUBufferUsage.COPY_DST | s.GPUBufferUsage.MAP_READ }), h = t.createCommandEncoder();
+  h.copyTextureToBuffer(
+    { texture: r },
+    { buffer: l, bytesPerRow: f, rowsPerImage: c },
+    { width: d, height: c, depthOrArrayLayers: 1 }
+  ), t.queue.submit([h.finish()]), await l.mapAsync(s.GPUMapMode.READ);
+  const p = new Uint8Array(l.getMappedRange()), w = new Uint8Array(d * c * 4);
+  for (let b = 0; b < c; b++) {
+    const B = b * f;
+    for (let T = 0; T < d; T++) {
+      const C = B + T * 4, u = (b * d + T) * 4;
+      w[u] = p[C + 2], w[u + 1] = p[C + 1], w[u + 2] = p[C], w[u + 3] = p[C + 3];
+    }
+  }
+  return l.unmap(), l.destroy(), w;
+}
+async function te(a, e, t) {
+  const r = e;
+  await a.prepare(t);
+  const d = a.renderToTexture(t);
+  try {
+    const c = d.source;
+    return { rgba: await z(r, c), width: c.pixelWidth, height: c.pixelHeight };
+  } finally {
+    d.destroy(!0);
+  }
+}
+function oe(a) {
+  return /VideoFrame is not defined|not supported by this browser|VideoEncoder is not|Invalid (video|audio) codec|Unknown codec/.test(String(a));
+}
+async function ae(a, e, t) {
+  const { Output: r, Mp4OutputFormat: d, WebMOutputFormat: c, FilePathTarget: s, VideoSampleSource: f, VideoSample: l, AudioBufferSource: h } = K(), p = await import("node:fs"), w = await import("node:path"), b = Q(t.range, t.fps), B = e, T = ee({ container: t.container, codec: t.videoCodec });
+  let C = null;
+  for (const u of T) {
+    const F = w.format({ ...w.parse(t.out), base: void 0, ext: `.${u.container}` }), O = u.container === "webm" ? new c() : new d({ fastStart: "in-memory" }), P = new r({ format: O, target: new s(F) });
+    let M = null;
+    try {
+      const o = new f({ codec: u.codec, bitrate: t.bitrate ?? 5e6 });
+      if (P.addVideoTrack(o), t.audio) {
+        const n = u.container === "webm" ? "opus" : t.audio.codec ?? "aac";
+        M = new h({ codec: n, bitrate: t.audio.bitrate ?? 128e3 }), P.addAudioTrack(M);
+      }
+      await P.start();
+      for (let n = 0; n < b.length; n++) {
+        const i = b[n];
+        await a.prepare(i);
+        const g = a.renderToTexture(i);
+        try {
+          const m = g.source, y = await z(B, m), x = new l(y, { format: "RGBA", codedWidth: m.pixelWidth, codedHeight: m.pixelHeight, timestamp: i, duration: 1 / t.fps });
+          await o.add(x), x.close();
+        } finally {
+          g.destroy(!0);
+        }
+        t.onProgress?.((n + 1) / b.length);
+      }
+      if (M && t.audio) {
+        const n = await t.audio.engine.renderOffline(Math.max(0, t.range[1] - t.range[0]));
+        await M.add(n);
+      }
+      return await P.finalize(), { frames: b.length, bytes: p.statSync(F).size, out: F, container: u.container, videoCodec: u.codec, audio: !!M };
+    } catch (o) {
+      C = o, await P.cancel().catch(() => {
+      });
+      try {
+        p.unlinkSync(F);
+      } catch {
+      }
+      if (oe(o)) {
+        console.warn(`⚠ node-av can't encode ${u.container}/${u.codec} here — trying the next codec…`);
+        continue;
+      }
+      throw o;
+    }
+  }
+  throw new Error(
+    "No server-side video encoder available (tried " + T.map((u) => u.codec).join(", ") + "). Route B encodes through @mediabunny/server (node-av / FFmpeg); ensure its native binary is built (`pnpm rebuild node-av`). Last error: " + String(C)
+  );
+}
+function re(a) {
+  const e = [], t = /src:\s*url\(([^)]+)\)/g;
+  let r;
+  for (; r = t.exec(a); )
+    e.push(r[1].replace(/["']/g, "").trim());
+  return e;
+}
+const ne = "Mozilla/5.0";
+async function N(a) {
+  if (!a?.length) return;
+  const { GlobalFonts: e } = await import("@napi-rs/canvas"), { Buffer: t } = await import("node:buffer");
+  for (const r of a)
+    if (r.google) {
+      const d = Y(r.google.cssBase ?? "https://fonts.googleapis.com/css2", {
+        family: r.family,
+        weights: r.google.weights,
+        italic: r.google.italic
+      }), c = await (await fetch(d, { headers: { "User-Agent": ne } })).text();
+      for (const s of re(c)) {
+        const f = t.from(await (await fetch(s)).arrayBuffer());
+        e.register(f, r.family);
+      }
+    } else if (r.src) {
+      const d = t.from(await (await fetch(r.src)).arrayBuffer());
+      e.register(d, r.family);
+    }
+}
+function $() {
+  const a = X.prototype;
+  a.loadFace = (e) => {
+    const t = /^\s*url\(\s*['"]?([^'")]+)['"]?\s*\)\s*$/.exec(e.src)?.[1] ?? (/^\s*(url|local)\s*\(/.test(e.src) ? null : e.src);
+    return t ? N([{ family: e.family, src: t }]) : Promise.resolve();
+  }, a.loadGoogle = (e) => N([{ family: e.family, google: { weights: e.weights, italic: e.italic, cssBase: e.cssBase } }]);
+}
+async function ge(a, e) {
+  await q(), $();
+  const t = Math.max(1, e.scale ?? 1);
+  let r = null;
+  const c = await (await new H({ ...a, externals: e.externals, loadAsset: e.loadAsset }).run()).build({
+    target: "server",
+    compositorOptions: {
+      createRenderer: async (s) => (r = await V(s), r),
+      resolution: t
+    }
+  });
+  try {
+    const s = c.compositor.timebase.fps;
+    return await ae(c.compositor, r, {
+      fps: s,
+      range: [0, c.duration],
+      out: e.out,
+      container: e.container,
+      videoCodec: e.videoCodec,
+      bitrate: e.bitrate,
+      onProgress: e.onProgress
+    });
+  } finally {
+    c.dispose();
+  }
+}
+async function ie(a, e, t, r) {
+  const { createCanvas: d } = await import("@napi-rs/canvas"), c = await import("node:fs"), s = d(t, r), f = s.getContext("2d"), l = f.createImageData(t, r);
+  l.data.set(e), f.putImageData(l, 0, 0);
+  const h = await s.encode("png");
+  return c.writeFileSync(a, h), h.length;
+}
+function ce(a) {
+  return a.replace(/\.[^./\\]*$/, "") + ".png";
+}
+async function me(a, e) {
+  await q(), $();
+  const t = Math.max(1, e.scale ?? 1);
+  let r = null;
+  const c = await (await new H({ ...a, externals: e.externals, loadAsset: e.loadAsset }).run()).build({
+    target: "server",
+    compositorOptions: {
+      createRenderer: async (s) => (r = await V(s), r),
+      resolution: t
+    }
+  });
+  try {
+    const s = Math.min(Math.max(e.time ?? 0, 0), c.duration), { rgba: f, width: l, height: h } = await te(c.compositor, r, s), p = ce(e.out), w = await ie(p, f, l, h);
+    return { out: p, time: s, width: l, height: h, bytes: w };
+  } finally {
+    c.dispose();
+  }
+}
+export {
+  $ as bridgeFontManagerToNode,
+  V as createNodeWebGPURenderer,
+  K as getMediabunny,
+  N as loadFontsNode,
+  me as renderBundleFrameToFile,
+  ge as renderBundleToFile,
+  te as renderFrameRGBA,
+  ae as renderTimelineToFile,
+  q as setupNodeEnvironment
+};
+//# sourceMappingURL=route-b.js.map

package/dist/src/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * `@sequio/server` — server-side rendering.
+ *
+ * Public surface: the serializable {@link TimelineSpec} protocol and the
+ * {@link buildTimeline} builder that rebuilds the SDK object graph from it. Both
+ * SSR routes (Route A headless Chrome in `route-a/`, Route B pure Node in
+ * `route-b/`) and the editor's "Server Render" button consume this protocol.
+ *
+ * The Node-only render workers (`route-b/*`) are intentionally NOT re-exported
+ * here so importing this barrel stays browser-safe (no jsdom / napi-canvas).
+ */
+export * from './timeline';
+export { sampleTimeline } from './sample-timeline';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/sample-timeline.d.ts

@@ -0,0 +1,3 @@
+import { TimelineSpec } from './timeline';
+export declare function sampleTimeline(): TimelineSpec;
+//# sourceMappingURL=sample-timeline.d.ts.map

package/dist/src/timeline.d.ts

@@ -0,0 +1,172 @@
+import { AudioEngine, AutoDetectOptions, BLEND_MODES, Compositor, Effect, Renderer, ShapeSpec, VisualClip } from '@sequio/engine';
+/** Named easing curves usable in a keyframe spec. */
+export type EasingName = 'linear' | 'hold' | 'easeInQuad' | 'easeOutQuad' | 'easeInOutQuad' | 'easeInCubic' | 'easeOutCubic' | 'easeInOutCubic';
+/**
+ * A filter/effect on a clip or the whole frame. Effects are shaders — they need
+ * a GPU renderer (so on the server they require Route B's WebGPU backend, not the
+ * Canvas fallback). Params are static here for brevity.
+ */
+export type EffectSpec = {
+    type: 'blur';
+    strength?: number;
+} | {
+    type: 'color';
+    brightness?: number;
+    contrast?: number;
+    saturation?: number;
+};
+/** A property that is either a constant value or a keyframed animation. */
+export type PropSpec<T> = T | {
+    keyframes: Array<{
+        time: number;
+        value: T;
+        easing?: EasingName;
+    }>;
+};
+export interface TransformSpec {
+    position?: PropSpec<[number, number]>;
+    scale?: PropSpec<[number, number]>;
+    rotation?: PropSpec<number>;
+    /** Normalized anchor (0..1); static only. Default `[0.5, 0.5]`. */
+    anchor?: [number, number];
+}
+interface BaseClipSpec {
+    /** Timeline interval, seconds. `end` is exclusive (`[start, end)`). */
+    start: number;
+    end: number;
+    sourceIn?: number;
+    sourceOut?: number;
+    speed?: number;
+    opacity?: PropSpec<number>;
+    blendMode?: BLEND_MODES;
+    transform?: TransformSpec;
+    /** Filters applied to this clip (needs Route B's GPU backend on the server). */
+    effects?: EffectSpec[];
+}
+export interface TextClipSpec extends BaseClipSpec {
+    type: 'text';
+    text: string;
+    fontFamily?: string;
+    fontSize?: PropSpec<number>;
+    fill?: number | string;
+}
+export interface ShapeClipSpec extends BaseClipSpec {
+    type: 'shape';
+    shape: ShapeSpec;
+}
+export interface ImageClipSpec extends BaseClipSpec {
+    type: 'image';
+    /** URL/data-URI the headless browser can fetch. */
+    src: string;
+}
+export interface VideoClipSpec extends BaseClipSpec {
+    type: 'video';
+    /** URL/data-URI the headless browser can fetch. */
+    src: string;
+    /** Decoded-frame ring size (bounds memory for big sources). */
+    cacheFrames?: number;
+    lookahead?: number;
+}
+export type ClipSpec = TextClipSpec | ShapeClipSpec | ImageClipSpec | VideoClipSpec;
+export interface TrackSpec {
+    zIndex?: number;
+    clips: ClipSpec[];
+}
+/** An audio clip scheduled into the {@link AudioEngine} for the exported mix. */
+export interface AudioClipSpec {
+    src: string;
+    start: number;
+    end: number;
+    sourceIn?: number;
+    gain?: number;
+    fadeIn?: number;
+    fadeOut?: number;
+}
+export interface FontSpec {
+    family: string;
+    /** Self-hosted URL. Mutually exclusive with {@link google}. */
+    src?: string;
+    /** Load from Google Fonts instead of a self-hosted URL. */
+    google?: {
+        weights?: number[];
+        italic?: boolean;
+        cssBase?: string;
+    };
+}
+export interface ExportSpec {
+    container?: 'mp4' | 'webm';
+    videoCodec?: string;
+    audioCodec?: string;
+    bitrate?: number;
+    audioBitrate?: number;
+    /** Mux the audio mix. Auto-enabled when the timeline has audio clips. */
+    audio?: boolean;
+}
+/** The full, JSON-serializable description of a timeline to render. */
+export interface TimelineSpec {
+    width: number;
+    height: number;
+    fps: number;
+    background?: number;
+    /** Normalized coordinate origin (`0..1`); default `[0, 0]`. */
+    origin?: [number, number];
+    /**
+     * Explicit render range `[start, end]` in seconds. Defaults to
+     * `[0, maxClipEnd]` — the whole timeline.
+     */
+    range?: [number, number];
+    fonts?: FontSpec[];
+    tracks?: TrackSpec[];
+    audio?: AudioClipSpec[];
+    /** Global filters over the whole composite (a master grade / blur). */
+    effects?: EffectSpec[];
+    export?: ExportSpec;
+}
+/** Everything the exporter path needs, plus a teardown that frees every source. */
+export interface BuiltTimeline {
+    compositor: Compositor;
+    audioEngine: AudioEngine;
+    range: [number, number];
+    exportOptions: ExportSpec;
+    hasAudio: boolean;
+    /** Dispose the compositor and every source/decoder this build created. */
+    dispose(): void;
+}
+/** Construct a built-in effect (filter) from its spec. */
+export declare function buildEffect(spec: EffectSpec): Effect;
+/**
+ * Construct one clip from its spec. Image/Video sources are loaded (async) and
+ * pushed onto `sources` for later disposal. Text/Shape clips need no source and
+ * resolve without touching the browser, so this is unit-testable for them.
+ */
+export declare function buildClip(spec: ClipSpec, sources: {
+    dispose(): void;
+}[]): Promise<VisualClip>;
+/** Largest clip end across all visual + audio clips (the timeline duration). */
+export declare function timelineEnd(spec: TimelineSpec): number;
+/**
+ * Overrides that let {@link buildTimeline} run outside a browser (server-side
+ * rendering). Both default to the browser behaviour.
+ */
+export interface BuildOverrides {
+    /** Custom GPU renderer factory (e.g. Node WebGPU via Dawn). */
+    createRenderer?: (options: Partial<AutoDetectOptions>) => Promise<Renderer>;
+    /** Custom font loader (e.g. Node `GlobalFonts.register`) replacing `document.fonts`. */
+    loadFonts?: (specs: FontSpec[] | undefined) => Promise<void>;
+    /**
+     * Backing-store scale for the output. `2` renders/exports at 2× the timeline's
+     * `width`×`height` (crisper text/vectors, larger file). In a browser this
+     * defaults to `devicePixelRatio`; in Node there's none, so the default is `1`
+     * and a caller (e.g. the SSR worker's `--scale`) can bump it here.
+     */
+    resolution?: number;
+}
+/**
+ * Rebuild the SDK object graph from a {@link TimelineSpec} and initialize the
+ * GPU renderer, ready for {@link Exporter.export}. Loads fonts and every
+ * image/video source up front. The caller must {@link BuiltTimeline.dispose}
+ * when done (frees the compositor and every source/decoder).
+ */
+export declare function buildTimeline(spec: TimelineSpec, overrides?: BuildOverrides): Promise<BuiltTimeline>;
+export {};
+//# sourceMappingURL=timeline.d.ts.map

package/package.json

@@ -0,0 +1,75 @@
+{
+  "name": "@sequio/server",
+  "version": "0.1.0",
+  "description": "Server-side rendering for sequio: a serializable TimelineSpec protocol plus Route B — pure Node, PixiJS WebGPU. (Route A, headless Chrome, is a repo-internal harness and not part of the published package.)",
+  "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/server"
+  },
+  "bugs": {
+    "url": "https://github.com/slightc/sequio/issues"
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./route-b": {
+      "types": "./dist/route-b/index.d.ts",
+      "import": "./dist/route-b.js"
+    }
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.map"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "server-side-rendering",
+    "pixijs",
+    "webgpu",
+    "video",
+    "headless"
+  ],
+  "dependencies": {
+    "mediabunny": "^1.49.0",
+    "pixi.js": "^8.6.0",
+    "@sequio/engine": "^0.1.1",
+    "@sequio/runtime": "^0.1.0"
+  },
+  "optionalDependencies": {
+    "@mediabunny/server": "^1.50.4",
+    "@napi-rs/canvas": "^1.0.2",
+    "jsdom": "^29.1.1",
+    "node-web-audio-api": "^2.0.0",
+    "webgpu": "^0.4.0"
+  },
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "verify:ssr": "node scripts/verify-page.cjs route-a/ssr-render.html __SSR_TEST__ \"server-side render\"",
+    "verify:ssr-node": "tsx route-b/render.ts --verify --out .ssr-out/node-demo.mp4",
+    "verify:ssr-node-audio": "tsx route-b/verify-audio.ts",
+    "verify:ssr-node-font": "tsx route-b/verify-font.ts",
+    "verify:ssr-node-media": "tsx route-b/verify-media.ts",
+    "ssr:render": "node route-a/ssr-render.cjs",
+    "ssr:render-node": "tsx route-b/render.ts"
+  }
+}