@sequio/skill 0.1.0 → 0.1.2

package/llms.txt

@@ -5,8 +5,10 @@
 > clock; the SDK owns the low-level runtime — decode, composite, audio, export.
 > Compositions are ordinary imperative TypeScript (you `new` the engine's own
 > classes), so the same code previews in a browser, exports in a browser, and
-> renders on a server. Persistence, schema, undo, collaboration and UI are out of
-> scope — they belong to the layer above.
+> renders on a server. sequio does not render HTML/CSS — there is no DOM/JSX or
+> declarative-template layer; you build the object graph in code. Persistence,
+> schema, undo, collaboration and UI are out of scope — they belong to the layer
+> above.
 
 Key facts an assistant should hold before writing sequio code:
 
@@ -23,14 +25,16 @@ Key facts an assistant should hold before writing sequio code:
 - `sequio render <file>` encodes to video (pure-Node WebGPU; needs a GPU or Mesa
   lavapipe). `sequio frame <file> --time <sec>` exports a single frame as a PNG
   through the same render core — the fast way to visually check a composition
-  before a full render. `sequio preview <file> --watch` serves a live preview.
+  before a full render. `sequio audio <file>` exports only the audio mix to an
+  audio-only file (mp3 default; also m4a/wav/ogg/webm). `sequio preview <file>
+  --watch` serves a live preview.
 
 ## Docs
 
 - [Architecture & the five contracts](https://github.com/slightc/sequio/blob/main/docs/architecture.md): modules, invariants, and the public-surface table.
 - [Runtime](https://github.com/slightc/sequio/blob/main/docs/runtime.md): compile + link + run multi-file TS/JS into a `Composer`; `defineComposition`, `loadAsset`, externals.
 - [CLI](https://github.com/slightc/sequio/blob/main/docs/cli.md): `sequio render` / `sequio preview --watch`, `--scale`, fonts, local/network media.
-- [Server-side rendering](https://github.com/slightc/sequio/blob/main/docs/server-side-rendering.md): the `TimelineSpec` protocol and both render routes (headless Chrome / pure-Node WebGPU).
+- [Server-side rendering](https://github.com/slightc/sequio/blob/main/docs/server-side-rendering.md): re-run a composition's own code (a `RuntimeBundle`, via `renderBundleToFile`) on a server through either render route (headless Chrome / pure-Node WebGPU) — no spec to serialize or keep in sync.
 - [Text animation](https://github.com/slightc/sequio/blob/main/docs/text-animation.md): clip/text animators, split motion, the GSAP binding.
 - [Contributor / agent guide (AGENT.md)](https://github.com/slightc/sequio/blob/main/AGENT.md): conventions, monorepo layout, working agreement.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sequio/skill",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "An installable AI Agent Skill (SKILL.md) + llms.txt that teach an AI assistant how to use sequio — build a Track/Clip/Effect object graph, preview, and export/render video.",
   "type": "module",
   "license": "MIT",

package/skills/sequio/SKILL.md

@@ -6,7 +6,9 @@ description: >-
   video/motion-graphics programmatically — creating a timeline of tracks and
   clips (text, image, video, shapes), animating them (keyframes or GSAP),
   applying effects/transitions, mixing audio, and exporting to MP4/WebM or
-  rendering server-side. Triggers: "sequio", "video editor SDK", "compose a
+  rendering server-side. sequio does NOT render HTML/CSS — compositions are
+  imperative TypeScript that `new`s engine classes, not a declarative DOM/JSX
+  framework. Triggers: "sequio", "video editor SDK", "compose a
   video", "timeline / track / clip", "render an mp4 from code", "TextClip",
   "Compositor", "defineComposition".
 ---
@@ -28,7 +30,7 @@ Pick the package that matches the task before writing code:
 |---|---|---|
 | Drive an object graph in an app you control | **engine** directly | `@sequio/engine` |
 | Author a self-contained composition file that previews **and** renders | **runtime** authoring API | `@sequio/engine` + `@sequio/runtime` |
-| Turn a composition file into an `.mp4`, a single-frame PNG, or a live preview from a terminal | **cli** | `sequio render` / `sequio frame` / `sequio preview` |
+| Turn a composition file into an `.mp4`, a single-frame PNG, or a live preview from a terminal | **cli** | `sequio check` / `sequio render` / `sequio frame` / `sequio preview` |
 | Render a composition to a file on a server (no browser) | **server** Route B | `@sequio/server/route-b` |
 
 For most "make me a video from code" tasks, author a **composition file** (runtime
@@ -98,33 +100,53 @@ export default defineComposition(async () => {
 Then, from the workspace root:
 
 ```bash
+sequio check   composition.ts                            # static validation — no GPU, offline (the pre-flight lint)
 sequio preview composition.ts --watch                    # live in-browser preview, reloads on edit
 sequio frame   composition.ts --time 2 --out shot.png     # export ONE frame at t=2s as a PNG (fast visual check)
+sequio audio   composition.ts --out track.mp3            # export ONLY the audio mix (mp3 default; also m4a/wav/ogg/webm)
 sequio render  composition.ts --out out.mp4              # encode the whole thing to video (pure-Node WebGPU)
 sequio render  composition.ts --out out.mp4 --scale 2    # 2× resolution (sharp text/edges)
 ```
 
-`sequio render` and `sequio frame` need a WebGPU host — a real GPU or the Mesa
+`sequio render`, `sequio frame` and `sequio audio` need a WebGPU host — a real GPU or the Mesa
 **lavapipe** software driver (`apt install mesa-vulkan-drivers`; then
 `export VK_ICD_FILENAMES=/usr/share/vulkan/icd.d/lvp_icd.json`). Without one they
 throw a clear error.
 
-### Check your work fast: export a single frame
+### Verify loop: `check` → `frame` → `render`
 
-When iterating on a composition **without** a live browser (e.g. you're an agent
-editing code), don't render the whole video to see if it's right — export one
-frame and look at it:
+Tighten the loop from coarsest-and-cheapest to full render. As an agent editing
+code, run them in this order:
 
 ```bash
-sequio frame composition.ts --time 2.5 --out /tmp/check.png    # then open/view the PNG
+sequio check composition.ts                                   # 1. offline lint — no GPU, no browser, fast
+sequio frame composition.ts --time 2.5 --out /tmp/check.png    # 2. render ONE frame, then open/view the PNG
+sequio render composition.ts --out out.mp4                     # 3. encode the whole video
 ```
 
-`frame` runs the **same render core** as `render` (contract #3), so the PNG is
-exactly what the video would contain at that instant — the fast way to confirm
-layout, position, and color before committing to a full render. `--time` is
-clamped to `[0, duration]`; `--scale N` renders at N× like `render`. This is the
-recommended verify loop: edit → `sequio frame` at a few representative times →
-eyeball → then `sequio render` once it looks right.
+**1. `check` — does the code build a legal object graph?** It compiles + links +
+runs the builder with a **null renderer** (no WebGPU) and walks the graph for the
+mistakes that are cheap to catch offline: illegal clip times (`end ≤ start`), a
+keyframe outside its clip's interval (dead keyframe), a `TextClip.fontFamily` no
+`fonts.load(...)` registered (silent system-font fallback — breaks
+preview↔render), a transition whose two clips don't overlap, an `anchor` outside
+`0..1`, a missing local `loadAsset` file. Exits non-zero on any error;
+`--json` emits a machine-readable `Diagnostic[]`. A green `check` doesn't prove
+the picture is right — but a **red `check` means don't bother rendering yet**.
+It's GPU-free and offline, so run it after every edit.
+
+**2. `frame` — does the frame *look* right?** `frame` runs the **same render
+core** as `render` (contract #3), so the PNG is exactly what the video would
+contain at that instant — the way to confirm layout, position, and color.
+`--time` is clamped to `[0, duration]`; `--scale N` renders at N× like `render`.
+
+**3. `render`** once `check` is green and a couple of `frame`s look right.
+
+> `check` deliberately does **not** decode media, hit the network, or compile
+> shaders — those need a browser/GPU and are what `frame`/`render` are for. A
+> composition that fetches a remote image or decodes video *in its builder* gets
+> a `B4` **warning** from `check` (the code compiled fine; verify the picture
+> with `frame`), not a failure.
 
 ## Core building blocks
 
@@ -153,8 +175,13 @@ eyeball → then `sequio render` once it looks right.
   clip.animator = gsapClipAnimator(gsap, (tl, o) => tl.from(o, { y: -60, alpha: 0, ease: 'back.out(1.7)' }));
   ```
   The binding seeks a **paused** timeline, keeping `render(t)` pure.
-- **Text motion** — `TextClip.split` + `StaggerTextAnimator` / `gsapTextAnimator`
-  animate per line/word/char (e.g. a staggered drop-in).
+- **Text motion** — `TextClip.split` + `TextClip.textAnimator` (`StaggerTextAnimator`
+  / `gsapTextAnimator`) animate per line/word/char (e.g. a staggered drop-in).
+- **Bring your own** — the four seams are subclass/implement points: subclass
+  `Effect` / `Transition` (or an engine effect) and implement `ClipAnimator`
+  (`clip.animator`) / `TextAnimator` (`textClip.textAnimator`). Build on the
+  engine's own classes and no `pixi.js` is needed — same in preview and render.
+  See recipe 7b and `packages/cli/example/custom-fx/`.
 
 ## Media, fonts, effects, audio, export — quick pointers
 
@@ -165,11 +192,16 @@ eyeball → then `sequio render` once it looks right.
   `TextClip`. Load an explicit web font so preview and Node render match — system
   defaults differ per platform.
 - **Effects/Transitions**: `ColorEffect`, `BlurEffect`, `BulgeEffect`,
-  `CrossfadeTransition`, etc. (some — chroma/LUT/wipe — are still TODO).
+  `CrossfadeTransition`, etc. (some — chroma/LUT/wipe — are still TODO). Attach an
+  effect with `clip.effects.push(fx)`; bind a transition with
+  `track.addTransition(new T(frames).between(a, b))` over the clips' overlap.
+  Roll your own by subclassing — see recipe 7b.
 - **Audio**: `AudioTrack` + `AudioSource`; `AudioEngine` mixes (Web Audio live,
   OfflineAudioContext for export).
-- **Export in an app** (not the CLI): use `Exporter` from `@sequio/engine`, or a
-  runtime `Composer`'s `composer.export(...)`.
+- **Export in an app** (not the CLI): use `Exporter` from `@sequio/engine`
+  (`export(...)` → video, `exportFrame(t, ...)` → one still image, `exportAudio(...)`
+  → audio-only file), or a runtime `Composer`'s `composer.export(...)`. Audio-only
+  on the CLI is `sequio audio composition.ts` (recipe 11).
 
 ## Before you finish
 

package/skills/sequio/references/api.md

@@ -19,13 +19,16 @@ Times are **seconds** at the API boundary, quantized to frames internally via
 - `Transform2D` — a clip's spatial state: `position`, `scale`, `rotation`,
   `anchor`, `alpha` (each an `AnimatableProperty`).
 - `AnimatableProperty` / `Keyframe` — `.setStatic(value)` or
-  `.setKeyframes([{ time, value, easing? }, ...])`.
+  `.setKeyframes([{ time, value, easing? }, ...])`; `.valueAt(t)`, `.animated`,
+  `.keyframeTimes` (sorted keyframe times, for static validation).
 - Easings: `linear`, `hold`, `cubicBezier`, `easeInQuad`, `easeOutQuad`,
   `easeInOutQuad`, `easeInCubic`, `easeOutCubic`, `easeInOutCubic`. Type `Easing`.
 - Clip/text animators: `ClipAnimator`, `TextAnimator`, `StaggerTextAnimator`,
   `TweenAnimator`, `IDENTITY_SAMPLE`, `lerpSample`, `AnimationSample`, plus
   `TextPart` / `TextSplit` / `StaggerOrder` / `StaggerTextOptions` /
-  `TweenAnimatorOptions`.
+  `TweenAnimatorOptions`. `ClipAnimator` (`sampleAt`) and `TextAnimator`
+  (`sampleForPart`) are **extension seams** — implement your own for custom motion
+  (assign to `clip.animator` / `textClip.textAnimator`); see recipe 7b.
 - GSAP binding (engine has no gsap dep): `gsapClipAnimator`, `gsapTextAnimator`,
   `identityTarget`; types `GsapLike`, `GsapTimelineLike`, `GsapTarget`.
 - Text layout: `computeTextParts`, `MeasureWidth`.
@@ -51,6 +54,8 @@ Times are **seconds** at the API boundary, quantized to frames internally via
 - `FontManager`, `fonts` (singleton), `buildGoogleCss2Url`; types `FontSpec`,
   `GoogleFontSpec`.
 - `fonts.load({ family, src })` before rendering a `TextClip` in that family.
+- `fonts.families()` — the family names a load has been requested for (used by
+  `sequio check` to catch a `TextClip` referencing an unregistered font).
 
 ## Compositor graph
 
@@ -58,10 +63,28 @@ Times are **seconds** at the API boundary, quantized to frames internally via
   fps?, background?, timebase?, createRenderer?, resolution? })`, then
   `await init()`, `addTrack(track)`, `renderPreview(t)`.
 - Tracks: `Track`, `VisualTrack` (stacks by `.zIndex`), `AudioTrack`.
-- Clips: `Clip`, `VisualClip`, `AudioClip`; concrete `VideoClip`, `ImageClip`,
-  `TextClip`, `ShapeClip`, `GroupClip`. Types: `TextStyleLike`, `ShapeSpec`,
-  `ShapeKind`.
+  `TextClip`, `ShapeClip`, `GroupClip`. Types: `TextStyleLike`, `TextStrokeLike`,
+  `ShapeSpec`, `ShapeKind`, `MaskSpec`.
 - Every clip has `.start` / `.end` (seconds) and `.transform` (`Transform2D`).
+- Time-remap on any clip: `.speed` (default `1`; time-line seconds → `speed`×
+  source seconds — variable-speed + pitch shift for audio) and `.reversed`
+  (default `false`; 倒放 — plays the same source window backwards. Video feeds a
+  decreasing source time to the decoder (decoded in GOP batches so reverse isn't
+  O(GOP²)); audio plays a reversed copy of the buffer, since Web Audio has no
+  negative playback rate). `clip.sourceTimeAt(t)` is the resulting source time —
+  the single mapping both decode-prep and render use, so `speed`/`reversed` set
+  on the clip apply everywhere.
+- `TextClip` style (`TextStyleLike`): `text`, `fontFamily`, `fontSize`
+  (animatable), `fill`, plus pass-throughs `fontWeight`, `fontStyle`
+  (`'italic'`), `letterSpacing`, `align`, `lineHeight` and `stroke`
+  (`TextStrokeLike` `{ color, width }` → hollow / outlined type). Weight and
+  letter-spacing feed measurement too, so split-text layout stays correct.
+- `VisualClip.maskShape` (`MaskSpec`): clip the content to a rounded-rect
+  (`kind:'rect'`, big `radius` → arch/stadium) or `ellipse` (circle crop), sized
+  explicitly (`width`/`height`, optional `x`/`y`, `inset`). Apply it to a
+  container-backed clip — a `GroupClip` wrapping the image — since a Sprite
+  cannot be masked by its own child; lay the content out from `(0,0)` in the
+  group.
 
 ## Effects & transitions
 
@@ -72,6 +95,10 @@ Times are **seconds** at the API boundary, quantized to frames internally via
 - Warp math: `Mat3`, `Quad`, `Vec2`, `UNIT_QUAD`, `squareToQuad`, `invert3x3`,
   `applyHomography`, `perspectiveSampleMatrix`, `bulgeSourceUv`.
 - Transitions: `Transition`, `CrossfadeTransition`, `crossfadeAlpha`.
+- Extend: subclass `Effect` (or an engine effect) for a custom filter/param, and
+  `Transition` (or `CrossfadeTransition`) for a custom mix — no `pixi.js` needed if
+  you build on the engine's own classes. Attach: `clip.effects.push(fx)`,
+  `track.addTransition(new T(frames).between(a, b))`. See recipe 7b.
 - Status: color/blur/warp + crossfade done; chroma/LUT/wipe TODO.
 
 ## Audio
@@ -82,9 +109,14 @@ Times are **seconds** at the API boundary, quantized to frames internally via
 
 ## Export
 
-- `Exporter` (`ExportOptions`, `ExportFrameOptions`), `ExportCancelledError`.
+- `Exporter` (`ExportOptions`, `ExportFrameOptions`, `AudioExportOptions`),
+  `ExportCancelledError`. `Exporter.export` → video, `exportFrame` → one still
+  image, `exportAudio` → audio-only file (the `AudioEngine` offline mix).
 - `ExportSink`, `ResolvedExportOptions`, `exportFrameTimes`,
   `MediabunnyExportSink`.
+- Audio-only: `AudioExportSink`, `AudioExportFormat`
+  (`'m4a' | 'mp3' | 'wav' | 'ogg' | 'webm'`), `ResolvedAudioExportOptions`,
+  `MediabunnyAudioExportSink`.
 
 ## Re-exported PixiJS types (type-only)
 

package/skills/sequio/references/recipes.md

@@ -76,13 +76,16 @@ it directly — the engine declares only the structural `GsapLike` types.
 import { StaggerTextAnimator } from '@sequio/engine';
 
 title.split = 'char';                       // split into per-character parts
-title.animator = new StaggerTextAnimator({
-  each: 0.04,                               // stagger between parts
-  from: (o) => ({ y: -40, alpha: 0 }),      // starting sample per part
+title.textAnimator = new StaggerTextAnimator({
+  from: { y: -40, alpha: 0 },               // each part starts 40px up + invisible
+  stagger: 0.04,                            // delay between consecutive parts (s)
+  duration: 0.5,                            // per-part animation length (s)
 });
 ```
 
-For gsap-driven per-part motion use `gsapTextAnimator(gsap, split, builder)`.
+Split text uses `textAnimator` (a `TextAnimator`); a whole-clip animator uses
+`animator` (a `ClipAnimator`) — don't mix the two fields. For gsap-driven per-part
+motion use `gsapTextAnimator(gsap, split, builder)`.
 
 ## 5. Video and image clips
 
@@ -127,24 +130,97 @@ const title = new TextClip({ text: 'sequio', fontFamily: 'Poppins', fontSize: 72
 ```ts
 import { BlurEffect, CrossfadeTransition } from '@sequio/engine';
 
-clip.effects.add(new BlurEffect({ strength: 8 }));
-// A crossfade between two overlapping clips on a track (overlap drives it):
-track.transition = new CrossfadeTransition({ duration: 0.5 });
+const blur = new BlurEffect();
+blur.strength.setStatic(8);            // strength is an AnimatableProperty (keyframe it too)
+clip.effects.push(blur);               // `effects` is an array
+
+// A crossfade between two OVERLAPPING clips on one track — their overlap is the
+// transition window (bind order is direction: from → to):
+track.addTransition(new CrossfadeTransition(15).between(clipA, clipB)); // 15 frames
 ```
 
-(Effect/transition constructor options vary — check `references/api.md` and the
-class in `packages/engine/src/effects/`. chroma/LUT/wipe are not yet built.)
+(chroma/LUT/wipe are not yet built — check `references/api.md` and the classes in
+`packages/engine/src/effects/`. To author your own, see the next recipe.)
 
-## 8. Export from your own app (not the CLI)
+## 7b. Bring your own — custom effect · transition · animation
+
+All four extension points are plain subclasses/implementations imported from
+`@sequio/engine` only. Build on the engine's own classes (or keep the animators
+pure math) and you need **no `pixi.js`**, so they render the same in preview
+(WebGL) and Node render (WebGPU). Full worked demo: `packages/cli/example/custom-fx/`.
+
+```ts
+// ── a custom EFFECT — subclass an engine effect, reuse its built-in filter ──
+import { BlurEffect, AnimatableProperty } from '@sequio/engine';
+class FocusPull extends BlurEffect {
+  readonly focus = new AnimatableProperty<number>(0);     // 0 sharp → 1 blurred
+  constructor(readonly maxBlur = 28) { super(); }
+  override updateAt(t: number) {
+    this.strength.setStatic(this.focus.valueAt(t) * this.maxBlur);
+    super.updateAt(t);                                     // let BlurEffect push it into the filter
+  }
+}
+const fx = new FocusPull(30);
+fx.focus.setKeyframes([{ time: 0, value: 1 }, { time: 0.8, value: 0 }]);
+clip.effects.push(fx);
+
+// ── a custom TRANSITION — subclass CrossfadeTransition, reshape the curve ──
+import { CrossfadeTransition, easeInOutCubic } from '@sequio/engine';
+class EasedCrossfade extends CrossfadeTransition {
+  override progressAt(t: number) { return easeInOutCubic(super.progressAt(t)); }
+}
+track.addTransition(new EasedCrossfade(30).between(clipA, clipB));
+
+// ── a custom whole-clip ANIMATION — implement ClipAnimator (pure sampleAt) ──
+import type { AnimationSample, ClipAnimator } from '@sequio/engine';
+class OrbitAnimator implements ClipAnimator {
+  constructor(private r = 90, private period = 2.6) {}
+  sampleAt(localT: number): AnimationSample {              // sampled at t - clip.start
+    const a = (localT / this.period) * Math.PI * 2;
+    return { x: Math.cos(a) * this.r, y: Math.sin(a) * this.r, rotation: a };
+  }
+}
+clip.animator = new OrbitAnimator();
+
+// ── a custom TEXT ANIMATION — implement TextAnimator (per split part) ──
+import type { AnimationSample, TextAnimator, TextPart } from '@sequio/engine';
+import { easeOutCubic } from '@sequio/engine';
+class DropInText implements TextAnimator {
+  constructor(private stagger = 0.06, private dur = 0.5, private drop = 70) {}
+  sampleForPart(part: TextPart, localT: number): AnimationSample {
+    const k = (localT - part.index * this.stagger) / this.dur;
+    const p = k <= 0 ? 0 : k >= 1 ? 1 : easeOutCubic(k);
+    return { y: -this.drop * (1 - p), alpha: p };
+  }
+}
+title.split = 'char';
+title.textAnimator = new DropInText();
+```
+
+`sampleAt` / `sampleForPart` / `updateAt(t)` / `render(t)` must be **pure functions
+of time** (contract #2) — no wall-clock, no dependence on the previous frame — so
+export stays reproducible. An `AnimationSample` composes over the clip's base
+transform: `x`/`y`/`rotation` add, `scaleX`/`scaleY`/`alpha` multiply.
 
-Two ways:
+## 8. Export from your own app (not the CLI)
 
 - Runtime `Composer`: `const blob = await composer.export({ format: 'mp4' });`
-- Engine `Exporter` directly against a `Compositor`:
+- Engine `Exporter` directly against a `Compositor` + `AudioEngine` — one object,
+  three exits (all reuse the same render/audio core, contract #3):
   ```ts
   import { Exporter } from '@sequio/engine';
-  const exporter = new Exporter(compositor, { duration, fps: 30, format: 'mp4' });
-  const blob = await exporter.run();       // FixedStep loop, awaits prepare — no dropped frames
+  const exporter = new Exporter(compositor, audioEngine);
+
+  // Video: FixedStep loop, awaits prepare — no dropped frames.
+  const movie = await exporter.export({ fps: 30, container: 'mp4' });
+
+  // One still image at a time (no fps boundary needed).
+  const still = await exporter.exportFrame(2.5, { type: 'image/png' });
+
+  // Audio only — just the AudioEngine offline mix, no frames rendered, no GPU.
+  const track = await exporter.exportAudio({ format: 'mp3' });
+  //   format: 'mp3' (default) | 'm4a' | 'wav' | 'ogg' | 'webm'
+  //   codec defaults per format (mp3 / aac / pcm-s16 / opus); bitrate, range, sampleRate optional
   ```
 
 ## 9. Server-side render (no browser)
@@ -181,6 +257,176 @@ few representative times → look at the PNGs → only `sequio render` once it's
 Programmatically it's `renderBundleFrameToFile(bundle, { out, time, scale })` from
 `@sequio/server/route-b`, or `runFrame(file, { out, time, scale })` from `@sequio/cli`.
 
+## 11. Export just the audio (no video)
+
+Encode only the composition's audio track — the same `AudioEngine` offline mix the
+video export muxes — to an audio-only file:
+
+```bash
+sequio audio composition.ts --out track.mp3                 # default format: mp3
+sequio audio composition.ts --format m4a --out track.m4a    # or m4a / wav / ogg / webm
+sequio audio composition.ts --out track.wav --bitrate 192000
+```
+
+- `--format` is `mp3` (default) `| m4a | wav | ogg | webm`; when omitted it's
+  inferred from `--out`'s extension. `--bitrate` is ignored for `wav` (PCM).
+- Same Route B path as `render`, so it needs a WebGPU host (GPU or Mesa lavapipe).
+- Programmatically it's `exportBundleAudioToFile(bundle, { out, format, bitrate })`
+  from `@sequio/server/route-b`, or `runAudio(file, { out, format, bitrate })` from
+  `@sequio/cli`; in-app it's `Exporter.exportAudio(...)` (recipe 8).
+
+## 12. Bring your own spec (JSON → object graph)
+
+sequio ships **no** persistent schema — an imperative `defineComposition` module
+is the only portable format the SDK blesses (the server re-runs that code via a
+`RuntimeBundle`, contract #3). If your app already has a document model — a Y.Doc,
+a database row, an editor's own JSON — **you own the schema**, and mapping it onto
+the engine is a ~30-line builder. This is a **pattern, not an API**: copy it and
+bend it to your data; don't look for an official spec type to import.
+
+The mapping has four moving parts, all mechanical:
+
+1. **keyframes** → `prop.setStatic(v)` for a constant, `prop.setKeyframes([...])` to animate.
+2. **easing** → a name→function lookup table (easings are just exported functions).
+3. **fonts** → `await fonts.load(...)` up front, before any `TextClip` uses the family.
+4. **effects** → a `type` switch that `new`s the engine effect and writes its params.
+
+```ts
+import {
+  Compositor, VisualTrack, TextClip, ShapeClip, ImageClip, ImageSource,
+  BlurEffect, ColorEffect, fonts,
+  linear, easeOutCubic, easeInOutCubic,
+  type Easing, type Effect,
+} from '@sequio/engine';
+import { defineComposition, loadAsset } from '@sequio/runtime';
+
+// ── YOUR schema (you define this — here's a minimal one) ─────────────────────
+type Prop<T> = T | { keyframes: Array<{ time: number; value: T; easing?: string }> };
+interface MySpec {
+  width: number; height: number; fps: number; background?: number;
+  fonts?: { family: string; src: string }[];
+  clips: Array<{
+    type: 'text' | 'shape' | 'image';
+    start: number; end: number;
+    position?: Prop<[number, number]>;
+    opacity?: Prop<number>;
+    text?: string; fontFamily?: string; fill?: number;   // text
+    width?: number; height?: number; src?: string;       // shape / image
+    effects?: Array<{ type: 'blur' | 'color'; strength?: number; brightness?: number }>;
+  }>;
+}
+
+// ── the fixed lookup tables ──────────────────────────────────────────────────
+const EASINGS: Record<string, Easing> = { linear, easeOutCubic, easeInOutCubic };
+
+function applyProp<T>(p: { setStatic(v: T): void; setKeyframes(k: any[]): void }, s: Prop<T> | undefined) {
+  if (s === undefined) return;
+  if (typeof s === 'object' && s !== null && 'keyframes' in s)
+    p.setKeyframes(s.keyframes.map((k) => ({ ...k, easing: k.easing ? EASINGS[k.easing] : undefined })));
+  else p.setStatic(s as T);
+}
+
+function buildEffect(e: { type: string; strength?: number; brightness?: number }): Effect {
+  if (e.type === 'blur') { const fx = new BlurEffect(); if (e.strength != null) fx.strength.setStatic(e.strength); return fx; }
+  const fx = new ColorEffect(); if (e.brightness != null) fx.brightness.setStatic(e.brightness); return fx;
+}
+
+// ── the builder: MySpec → Composer ───────────────────────────────────────────
+export function fromSpec(spec: MySpec) {
+  return defineComposition(async () => {
+    const c = new Compositor({ width: spec.width, height: spec.height, fps: spec.fps, background: spec.background });
+    await c.init();
+    for (const f of spec.fonts ?? []) await fonts.load(f);      // fonts BEFORE clips
+
+    const track = new VisualTrack();
+    for (const cs of spec.clips) {
+      let clip;
+      if (cs.type === 'text')  clip = new TextClip({ text: cs.text!, fontFamily: cs.fontFamily, fill: cs.fill });
+      else if (cs.type === 'shape') clip = new ShapeClip({ kind: 'rect', width: cs.width!, height: cs.height!, fill: cs.fill ?? 0xffffff });
+      else clip = new ImageClip(new ImageSource({ src: cs.src! }));
+      clip.start = cs.start; clip.end = cs.end;
+      applyProp(clip.transform.position, cs.position);
+      applyProp(clip.opacity, cs.opacity);
+      for (const e of cs.effects ?? []) clip.effects.push(buildEffect(e));
+      track.add(clip);
+    }
+    c.addTrack(track);
+    return { compositor: c };
+  });
+}
+```
+
+Feed it your JSON and you get a `Composer` that previews, exports and
+server-renders like any other composition:
+
+```ts
+export default fromSpec(JSON.parse(await loadAsset('./timeline.json')));
+```
+
+**Why the SDK doesn't ship this for you:** any real product already has a document
+model (undo, collaboration, its own field names); an official spec would just be a
+second schema to fight. The fuller reference implementation — video/audio clips,
+`sourceIn`/`sourceOut`, blend modes, a global grade — lives in
+`packages/server/src/timeline.ts` (the `TimelineSpec` type + `buildTimeline`). Read
+it for the complete pattern, then write your own.
+
+**Trust boundary:** a `RuntimeBundle` is *code* — re-running it executes arbitrary
+TS/JS on your server. Serve bundles only from trusted (first-party) sources. For a
+multi-tenant or public-facing service, accept *data* (a tenant's JSON + your
+builder above), never their code, and allowlist any media `src` URL your builder
+fetches. See `docs/server-side-rendering.md` § 信任边界与安全模型.
+
+## Outlined / echoed / italic display text
+
+`TextStyleLike` passes weight, italic, letter-spacing and a stroke straight into
+Pixi's text style — so one family covers bold / hollow / italic cuts:
+
+```ts
+// Hollow outlined word: pale fill + a coloured stroke.
+new TextClip({ text: 'SUPER', fontFamily: 'Oswald', fontSize: 150, fill: 0xf7cfcf,
+  fontWeight: '700', letterSpacing: 2, stroke: { color: 0xa5120f, width: 4 } });
+
+// Bold italic call-to-action.
+new TextClip({ text: 'MAKE IT YOURS', fontFamily: 'Oswald', fontSize: 96,
+  fill: 0xa5120f, fontWeight: '700', fontStyle: 'italic' });
+```
+
+An "echo" stack (fading after-image) is N copies with decreasing opacity:
+
+```ts
+const g = new GroupClip();
+for (let i = 0; i < 4; i++) {
+  const t = new TextClip({ text: 'PROMO', fontFamily: 'Oswald', fontSize: 150, fill: 0xffffff, fontWeight: '700' });
+  t.start = 0; t.end = 3;
+  t.transform.anchor.setStatic([0, 0]);
+  t.transform.position.setStatic([0, i * 205]);
+  t.opacity.setStatic(Math.pow(0.7, i)); // each copy fainter
+  g.add(t);
+}
+```
+
+## Arch / circle-cropped photo (`maskShape`)
+
+Clip an image to a rounded-rect (arch) or ellipse. Mask a **`GroupClip`** that
+wraps the image — a Sprite can't be masked by its own child — and lay the image
+out from `(0, 0)` in the group, sized to fill the mask:
+
+```ts
+const src = new ImageSource({ src: 'https://…?w=760&h=1500&fit=crop' }); // pre-crop to region aspect
+const meta = await src.load();
+const img = new ImageClip(src);
+img.start = 0; img.end = 3;
+img.transform.anchor.setStatic([0, 0]);
+img.transform.scale.setStatic([760 / meta.width, 1500 / meta.height]);
+
+const arch = new GroupClip();
+arch.start = 0; arch.end = 3;
+arch.transform.anchor.setStatic([0, 0]);
+arch.transform.position.setStatic([170, -60]);            // where the arch sits
+arch.maskShape = { kind: 'rect', width: 760, height: 1500, radius: 380 }; // big radius → arch
+arch.add(img);
+```
+
 ## Gotchas
 
 - Call `await compositor.init()` before adding tracks.