@sequio/skill 0.1.0

package/README.md

@@ -0,0 +1,68 @@
+# `@sequio/skill`
+
+An installable **AI Agent Skill** and an **`llms.txt`** that teach an AI assistant
+how to use [sequio](https://github.com/slightc/sequio) — how to build a
+`Track / Clip / Effect` object graph, animate it, and preview / export / render
+video. Drop it into any project that consumes `@sequio/engine` so the assistant
+working in that repo already knows the API and the mental model.
+
+This package ships **no runtime code** — just docs an agent reads.
+
+```
+skills/sequio/
+  SKILL.md              the skill (YAML frontmatter: name + description, then the guide)
+  references/
+    api.md              the full public surface, grouped by module
+    recipes.md          copy-paste composition patterns
+llms.txt                the llms.txt index (llmstxt.org) — links to the canonical docs
+```
+
+## What's inside
+
+- **`SKILL.md`** — an [Agent Skill](https://docs.claude.com/en/docs/claude-code/skills):
+  a Markdown file with `name` / `description` frontmatter that an AI agent
+  auto-loads when a task involves sequio (composing video, timelines, `TextClip`,
+  `Compositor`, rendering an MP4 from code, …). It links to the two reference
+  files for the exact API and fuller examples.
+- **`llms.txt`** — a root-level [`/llms.txt`](https://llmstxt.org/) index: a short
+  project summary plus curated links to sequio's docs, reference, and examples, so
+  any LLM tool (not just Claude) can discover the canonical material.
+
+## Install the skill into your project
+
+Agent Skills live under `.claude/skills/<name>/`. Copy this package's `skills/`
+folder there:
+
+```bash
+# from your project root, after `npm install @sequio/skill` (or pnpm/yarn)
+mkdir -p .claude/skills
+cp -R node_modules/@sequio/skill/skills/sequio .claude/skills/sequio
+```
+
+Or symlink it so it tracks the installed version:
+
+```bash
+ln -s ../../node_modules/@sequio/skill/skills/sequio .claude/skills/sequio
+```
+
+Commit `.claude/skills/sequio/` and every agent working in the repo picks it up.
+The skill is host-agnostic Markdown — any tool that reads Agent Skills can use it.
+
+## Serve the `llms.txt`
+
+If your project (or sequio's) has a website, publish `llms.txt` at the site root
+so it is reachable at `https://your-site/llms.txt` — the convention LLM tools look
+for. The file also stands alone as a compact, link-first briefing you can paste
+into any assistant.
+
+```bash
+cp node_modules/@sequio/skill/llms.txt public/llms.txt   # e.g. for a Vite/Next site
+```
+
+## Keeping it accurate
+
+The skill's source of truth is the engine barrel
+(`packages/engine/src/index.ts`). When the public API changes, update
+`references/api.md` (and `SKILL.md` if the mental model shifts) in the same
+change — the package's tests assert the frontmatter is well-formed and that every
+intra-skill and `llms.txt` on-disk link still resolves.

package/llms.txt

@@ -0,0 +1,53 @@
+# sequio
+
+> sequio is a command-style object-graph engine for building video editors on top
+> of PixiJS v8. You construct a tree of Track / Clip / Effect objects and drive a
+> 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.
+
+Key facts an assistant should hold before writing sequio code:
+
+- Packages: `@sequio/engine` (the SDK), `@sequio/runtime` (compile+run TS/JS into
+  a `Composer`), `@sequio/server` (server-side render), `@sequio/cli` (the
+  `sequio render` / `sequio preview` commands), `@sequio/studio` (reference editor).
+- Author a composition as a module whose default export is
+  `defineComposition(builder)`; inside, `new Compositor(...)`, add `VisualTrack`s,
+  `track.add(new TextClip(...))`, return `{ compositor, duration? }`.
+- Times are seconds at the API boundary. Clips carry `.start` / `.end` and a
+  `.transform` (position/scale/rotation/anchor/alpha, each keyframable).
+- Invariant: `render(t)` is a pure function of (object graph, t) — reproducible
+  export, golden-frame tests. Preview and export share one render core.
+- `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.
+
+## 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).
+- [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.
+
+## Reference
+
+- [Public API surface](https://github.com/slightc/sequio/blob/main/packages/engine/src/index.ts): the engine barrel — the single source of truth for what is stable API.
+- [Agent Skill: SKILL.md](https://github.com/slightc/sequio/blob/main/packages/skill/skills/sequio/SKILL.md): the installable skill that teaches how to use sequio.
+- [Skill API cheatsheet](https://github.com/slightc/sequio/blob/main/packages/skill/skills/sequio/references/api.md): every exported class/type, grouped by module.
+- [Skill recipes](https://github.com/slightc/sequio/blob/main/packages/skill/skills/sequio/references/recipes.md): copy-paste composition patterns.
+
+## Examples
+
+- [CLI sample composition](https://github.com/slightc/sequio/blob/main/packages/cli/example/index.ts): a title + shapes, GSAP-driven entrance, embedded font.
+- [YC-style 15s motion poster](https://github.com/slightc/sequio/blob/main/packages/cli/example/yc-spot/index.ts): a multi-scene showcase built entirely from ShapeClip/TextClip/GroupClip.
+
+## Optional
+
+- [Project website](https://sequio-demo.vercel.app/): home, demo gallery (live sequio renders), in-browser Code Mode, API reference.
+- [README](https://github.com/slightc/sequio/blob/main/README.md): package table, quick start, install.
+- [Roadmap & milestones](https://github.com/slightc/sequio/blob/main/todo/README.md): what's implemented vs. in progress.

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@sequio/skill",
+  "version": "0.1.0",
+  "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",
+  "author": "slightc",
+  "homepage": "https://sequio-demo.vercel.app/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/slightc/sequio.git",
+    "directory": "packages/skill"
+  },
+  "bugs": {
+    "url": "https://github.com/slightc/sequio/issues"
+  },
+  "files": [
+    "skills",
+    "llms.txt",
+    "README.md"
+  ],
+  "exports": {
+    "./llms.txt": "./llms.txt",
+    "./skill": "./skills/sequio/SKILL.md"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "sequio",
+    "agent-skill",
+    "claude",
+    "llms-txt",
+    "ai",
+    "video-editor",
+    "pixijs"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}

package/skills/sequio/SKILL.md

@@ -0,0 +1,181 @@
+---
+name: sequio
+description: >-
+  Build, preview, and export/render video with sequio (@sequio/engine +
+  @sequio/runtime + @sequio/cli). Use this whenever a task involves composing
+  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
+  video", "timeline / track / clip", "render an mp4 from code", "TextClip",
+  "Compositor", "defineComposition".
+---
+
+# Using sequio
+
+sequio is a **command-style object-graph engine** for building video on top of
+**PixiJS v8**. You construct a tree of `Track / Clip / Effect` objects and drive
+a clock; the SDK owns decode, composite, audio, and export. It is *not*
+declarative JSON — you write ordinary imperative TypeScript with the engine's own
+classes, so anything that runs in a demo runs everywhere (browser preview,
+browser export, server render).
+
+## Decide the entry point first
+
+Pick the package that matches the task before writing code:
+
+| Goal | Use | Import from |
+|---|---|---|
+| 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` |
+| 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
+API) and drive it with the **CLI** — that is the path the examples use.
+
+## The mental model (do not fight these)
+
+sequio rests on five invariants. Respect them and everything composes; break them
+and preview/export diverge:
+
+1. **Async `prepare` / sync `render`.** Decoding is async; a frame is a pure sync
+   render once inputs are ready. You rarely call these directly — the Compositor,
+   preview clock, and Exporter do.
+2. **`render(t)` is a pure function of (object graph, `t`).** No dependence on the
+   previous frame or wall-clock. This is what makes export reproducible. Never
+   store per-frame mutable state that a later `render(t)` reads back.
+3. **Preview and export share one render core** — same resolution and color
+   pipeline. A composition that looks right in preview renders identically.
+4. **Explicit resource ownership.** Every SDK object has `dispose()`. Long-lived
+   apps must dispose what they create; a one-shot render is torn down for you.
+5. **Invalidate / dirty-flag.** The engine never repaints on its own. Mutating a
+   property marks the graph dirty; the host schedules a repaint.
+
+## Author a composition (the common path)
+
+A composition is a TS/JS module whose default export is `defineComposition(builder)`.
+Inside the builder you `new` engine classes exactly like a demo — no `env`
+plumbing. Times are **seconds** at the API boundary.
+
+```ts
+import { Compositor, VisualTrack, TextClip, ShapeClip, easeInOutCubic } from '@sequio/engine';
+import { defineComposition } from '@sequio/runtime';
+
+export default defineComposition(async () => {
+  const compositor = new Compositor({ width: 1280, height: 720, fps: 30, background: 0x0b0b0e });
+  await compositor.init();
+
+  // A background rectangle for the whole timeline.
+  const bg = new VisualTrack();
+  const backdrop = new ShapeClip({ kind: 'rect', width: 1280, height: 720, fill: 0x0f172a });
+  backdrop.start = 0;
+  backdrop.end = 4;
+  backdrop.transform.anchor.setStatic([0, 0]);
+  backdrop.transform.position.setStatic([0, 0]);
+  bg.add(backdrop);
+  compositor.addTrack(bg);
+
+  // A title on a higher track (z-index stacks tracks).
+  const text = new VisualTrack();
+  text.zIndex = 1;
+  const title = new TextClip({ text: 'sequio', fontSize: 72, fill: 0xffffff });
+  title.start = 0;
+  title.end = 4;
+  title.transform.anchor.setStatic([0.5, 0.5]);
+  // Keyframe the position (values interpolate with the given easing).
+  title.transform.position.setKeyframes([
+    { time: 0, value: [640, 300] },
+    { time: 4, value: [640, 420], easing: easeInOutCubic },
+  ]);
+  text.add(title);
+  compositor.addTrack(text);
+
+  return { compositor, duration: 4 }; // `duration` optional — derived from clip ends
+});
+```
+
+Then, from the workspace root:
+
+```bash
+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 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
+**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
+
+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:
+
+```bash
+sequio frame composition.ts --time 2.5 --out /tmp/check.png    # then open/view the PNG
+```
+
+`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.
+
+## Core building blocks
+
+- **`Compositor({ width, height, fps?, background?, timebase? })`** — the root. Call
+  `await compositor.init()` before adding tracks; `compositor.addTrack(track)`.
+- **Tracks**: `VisualTrack` (stacked by `.zIndex`) and `AudioTrack`. A track holds
+  clips: `track.add(clip)`.
+- **Clips** carry `.start` / `.end` (seconds) and a `.transform` (a `Transform2D`
+  with `position`, `scale`, `rotation`, `anchor`, `alpha` — each an
+  `AnimatableProperty` you drive with `.setStatic(v)` or `.setKeyframes([...])`):
+  - `TextClip({ text, fontFamily?, fontSize?, fill? })`
+  - `ImageClip` / `VideoClip` (backed by an `ImageSource` / `VideoSource`)
+  - `ShapeClip({ kind: 'rect' | 'ellipse' | ..., width, height, fill })`
+  - `GroupClip` — nest clips and transform them together.
+- **`anchor`** is normalized (`[0.5, 0.5]` = center); `position` is in pixels.
+
+## Animation
+
+- **Keyframes** — `prop.setKeyframes([{ time, value, easing? }, ...])`. Easings are
+  exported: `linear`, `easeInOutCubic`, `cubicBezier(...)`, etc.
+- **GSAP** — the engine ships *no* gsap dependency but has a binding. The host
+  injects gsap; the CLI already does, so a composition can just:
+  ```ts
+  import gsap from 'gsap';
+  import { gsapClipAnimator } from '@sequio/engine';
+  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).
+
+## Media, fonts, effects, audio, export — quick pointers
+
+- **Media**: `new VideoSource({ src })` / `new ImageSource({ src })` accept a URL or
+  a `Blob`. For a file next to the composition, use runtime's
+  `await loadAsset('./clip.mp4')` (host provides the bytes; never bundled).
+- **Fonts**: `await fonts.load({ family, src })` before using the family in a
+  `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).
+- **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(...)`.
+
+## Before you finish
+
+- Load `references/api.md` for the exact public surface (every exported class/type)
+  and `references/recipes.md` for fuller copy-paste patterns.
+- Keep the public API surface honest: it is whatever
+  `packages/engine/src/index.ts` exports.
+- If a code path throws "not implemented", that milestone is unbuilt — see the
+  pointer in the error and `todo/`. Do not paper over it.

package/skills/sequio/references/api.md

@@ -0,0 +1,105 @@
+# sequio public API reference
+
+The stable public surface is exactly what `@sequio/engine`'s barrel
+(`packages/engine/src/index.ts`) exports. This mirrors it, grouped by module.
+Internal helpers (`Reconciler`, `FrameCache`, `TextureManager`, demux/mux
+adapters) are exported for advanced extension but are **not** stable API.
+
+Times are **seconds** at the API boundary, quantized to frames internally via
+`Timebase`.
+
+## Time & clock
+
+- `Timebase` — frame quantization (`new Timebase(fps)`).
+- `Clock`, `RealtimeClock`, `FixedStepClock` — preview uses `RealtimeClock`;
+  export uses a fixed step so no frame is dropped.
+
+## Animation
+
+- `Transform2D` — a clip's spatial state: `position`, `scale`, `rotation`,
+  `anchor`, `alpha` (each an `AnimatableProperty`).
+- `AnimatableProperty` / `Keyframe` — `.setStatic(value)` or
+  `.setKeyframes([{ time, value, easing? }, ...])`.
+- 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`.
+- GSAP binding (engine has no gsap dep): `gsapClipAnimator`, `gsapTextAnimator`,
+  `identityTarget`; types `GsapLike`, `GsapTimelineLike`, `GsapTarget`.
+- Text layout: `computeTextParts`, `MeasureWidth`.
+
+## Media
+
+- `MediaSource`, `VisualSource`, `SourceMetadata`.
+- `VideoSource` (`VideoSourceOptions`) — decode via Mediabunny; `src` = URL | Blob.
+- `ImageSource` (`ImageSourceOptions`).
+- `AudioSource` (`AudioSourceOptions`).
+- Decoder seam: `VideoDecoderBackend`, `DecodedFrame`, `MediabunnyVideoDecoder`,
+  `setFrameImageExtractor` / `FrameImageExtractor`, `MediabunnyDemux`, `VideoInput`.
+- `FrameCache`, `Closable`.
+- Mediabunny module control (dual-package hazard): `loadMediabunny`,
+  `setMediabunnyModule`, `MediabunnyModule`.
+
+## Texture
+
+- `TextureManager` — GPU byte budget + LRU eviction.
+
+## Text / fonts
+
+- `FontManager`, `fonts` (singleton), `buildGoogleCss2Url`; types `FontSpec`,
+  `GoogleFontSpec`.
+- `fonts.load({ family, src })` before rendering a `TextClip` in that family.
+
+## Compositor graph
+
+- `Compositor` (`CompositorOptions`) — root. `new Compositor({ width, height,
+  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`.
+- Every clip has `.start` / `.end` (seconds) and `.transform` (`Transform2D`).
+
+## Effects & transitions
+
+- `Effect`, `EffectRegistry` (`EffectFactory`), `registerBuiltins`,
+  `BUILTIN_EFFECTS`.
+- Effects: `ColorEffect`, `BlurEffect`, `BulgeEffect`, `PerspectiveEffect`,
+  `DisplacementEffect` (`DisplacementEffectOptions`).
+- Warp math: `Mat3`, `Quad`, `Vec2`, `UNIT_QUAD`, `squareToQuad`, `invert3x3`,
+  `applyHomography`, `perspectiveSampleMatrix`, `bulgeSourceUv`.
+- Transitions: `Transition`, `CrossfadeTransition`, `crossfadeAlpha`.
+- Status: color/blur/warp + crossfade done; chroma/LUT/wipe TODO.
+
+## Audio
+
+- `AudioEngine` — Web Audio live + OfflineAudioContext for export.
+- Scheduling helpers: `clipPlaybackAt`, `effectiveGain`, `fadeFactor`,
+  `gainEventsAt`; types `ClipPlayback`, `GainEvent`.
+
+## Export
+
+- `Exporter` (`ExportOptions`, `ExportFrameOptions`), `ExportCancelledError`.
+- `ExportSink`, `ResolvedExportOptions`, `exportFrameTimes`,
+  `MediabunnyExportSink`.
+
+## Re-exported PixiJS types (type-only)
+
+- `Renderer`, `AutoDetectOptions`, `BLEND_MODES` — so a consumer types against the
+  injected renderer / clip blend mode without importing `pixi.js` directly.
+
+## Core primitives
+
+- `Disposable`, `Subscription`, `createSubscription`.
+
+## Runtime authoring API (`@sequio/runtime`)
+
+- `defineComposition(builder)` — default-export a builder that returns
+  `{ compositor, audioEngine?, duration? }`.
+- `loadAsset('./path')` — fetch a local media file as a `Blob` (host-provided).
+- `Runtime`, `Composer` — compile+link+run files → a `Composer` that previews,
+  exports (client), or `toBundle()`s source for server render.
+- `@sequio/runtime/node-fs` (subpath) — `NodeFileSystem` for real-disk files.

package/skills/sequio/references/recipes.md

@@ -0,0 +1,191 @@
+# sequio recipes
+
+Copy-paste patterns. Each is an imperative composition — the same code runs in
+browser preview, browser export, and server render (contract #3). Author them as
+a `defineComposition(builder)` module and drive with `sequio preview` / `sequio
+render`, or lift the body into an app that owns its own clock.
+
+## 1. Title over a background
+
+```ts
+import { Compositor, VisualTrack, TextClip, ShapeClip } from '@sequio/engine';
+import { defineComposition } from '@sequio/runtime';
+
+export default defineComposition(async () => {
+  const c = new Compositor({ width: 1280, height: 720, fps: 30 });
+  await c.init();
+
+  const bg = new VisualTrack();
+  const rect = new ShapeClip({ kind: 'rect', width: 1280, height: 720, fill: 0x101018 });
+  rect.start = 0; rect.end = 5;
+  rect.transform.anchor.setStatic([0, 0]);
+  rect.transform.position.setStatic([0, 0]);
+  bg.add(rect);
+  c.addTrack(bg);
+
+  const layer = new VisualTrack();
+  layer.zIndex = 1;
+  const title = new TextClip({ text: 'Hello', fontSize: 96, fill: 0xffffff });
+  title.start = 0; title.end = 5;
+  title.transform.anchor.setStatic([0.5, 0.5]);
+  title.transform.position.setStatic([640, 360]);
+  layer.add(title);
+  c.addTrack(layer);
+
+  return { compositor: c, duration: 5 };
+});
+```
+
+## 2. Keyframed motion + fade
+
+```ts
+import { easeOutCubic } from '@sequio/engine';
+// clip.transform properties are AnimatableProperty — keyframe any of them.
+clip.transform.position.setKeyframes([
+  { time: 0, value: [200, 360] },
+  { time: 1.2, value: [640, 360], easing: easeOutCubic },
+]);
+clip.transform.scale.setKeyframes([
+  { time: 0, value: [0.6, 0.6] },
+  { time: 1.2, value: [1, 1], easing: easeOutCubic },
+]);
+clip.transform.alpha.setKeyframes([
+  { time: 0, value: 0 },
+  { time: 0.6, value: 1 },
+]);
+```
+
+## 3. GSAP-driven entrance (CLI injects gsap)
+
+```ts
+import gsap from 'gsap';
+import { gsapClipAnimator } from '@sequio/engine';
+
+title.animator = gsapClipAnimator(gsap, (tl, o) => {
+  tl.from(o, { y: -80, alpha: 0, duration: 0.8, ease: 'back.out(1.7)' });
+});
+```
+
+The binding seeks a **paused** gsap timeline so `render(t)` stays pure. In your
+own app (not the CLI) you must inject gsap via `RuntimeOptions.externals` or use
+it directly — the engine declares only the structural `GsapLike` types.
+
+## 4. Per-character text drop-in
+
+```ts
+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
+});
+```
+
+For gsap-driven per-part motion use `gsapTextAnimator(gsap, split, builder)`.
+
+## 5. Video and image clips
+
+```ts
+import { Compositor, VisualTrack, VideoClip, ImageClip, VideoSource, ImageSource } from '@sequio/engine';
+import { defineComposition, loadAsset } from '@sequio/runtime';
+
+export default defineComposition(async () => {
+  const c = new Compositor({ width: 1920, height: 1080, fps: 30 });
+  await c.init();
+
+  // URL sources (browser fetch / Node UrlSource) — nothing committed to the repo:
+  const web = new ImageSource({ src: 'https://picsum.photos/id/1015/1280/720' });
+  // Local file next to the composition — host provides the bytes, never bundled:
+  const local = new VideoSource({ src: await loadAsset('./clip.mp4') });
+
+  const track = new VisualTrack();
+  const img = new ImageClip({ source: web });
+  img.start = 0; img.end = 3;
+  const vid = new VideoClip({ source: local });
+  vid.start = 3; vid.end = 8;
+  track.add(img); track.add(vid);
+  c.addTrack(track);
+
+  return { compositor: c };
+});
+```
+
+## 6. Custom font (preview == render)
+
+```ts
+import { fonts, TextClip } from '@sequio/engine';
+
+// Load an explicit web font so Node render matches browser preview
+// (system defaults differ per platform). `src` may be a URL or a data: URL.
+await fonts.load({ family: 'Poppins', src: POPPINS_DATA_URL });
+const title = new TextClip({ text: 'sequio', fontFamily: 'Poppins', fontSize: 72, fill: 0xffffff });
+```
+
+## 7. An effect on a clip + a crossfade
+
+```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 });
+```
+
+(Effect/transition constructor options vary — check `references/api.md` and the
+class in `packages/engine/src/effects/`. chroma/LUT/wipe are not yet built.)
+
+## 8. Export from your own app (not the CLI)
+
+Two ways:
+
+- Runtime `Composer`: `const blob = await composer.export({ format: 'mp4' });`
+- Engine `Exporter` directly against a `Compositor`:
+  ```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
+  ```
+
+## 9. Server-side render (no browser)
+
+Snapshot a composition's files into a bundle and hand it to Route B:
+
+```bash
+pnpm sequio render composition.ts --out out.mp4 --scale 2
+# or, from a RuntimeBundle programmatically:
+#   import { renderBundleToFile } from '@sequio/server/route-b';
+#   await renderBundleToFile(bundle, { out: 'out.mp4', scale: 2 });
+```
+
+Route B is pure Node + PixiJS WebGPU (Dawn); it needs a GPU or the Mesa lavapipe
+software driver.
+
+## 10. Quick visual check — export a single frame (no full render)
+
+The fast way to confirm a composition looks right without rendering the whole
+video (and without a browser). `sequio frame` seeks to one time and writes a PNG
+through the same render core as `render`:
+
+```bash
+sequio frame composition.ts --time 2.5 --out /tmp/check.png   # then open/view the PNG
+sequio frame composition.ts --time 0    --out /tmp/start.png --scale 2
+```
+
+- `--time <sec>` is clamped to `[0, duration]` (so `--time 999` gives the last frame).
+- `--scale N` renders at N× like `render`.
+- Needs a WebGPU host (GPU or Mesa lavapipe), same as `render`.
+
+Recommended iterate loop for an agent: edit the composition → `sequio frame` at a
+few representative times → look at the PNGs → only `sequio render` once it's right.
+Programmatically it's `renderBundleFrameToFile(bundle, { out, time, scale })` from
+`@sequio/server/route-b`, or `runFrame(file, { out, time, scale })` from `@sequio/cli`.
+
+## Gotchas
+
+- Call `await compositor.init()` before adding tracks.
+- `anchor` is normalized (`[0.5,0.5]` = center); `position` is pixels.
+- Set both `.start` and `.end` on every clip, in seconds.
+- Don't read the previous frame's state inside a render — `render(t)` must be pure.
+- In a long-lived app, `dispose()` what you create; a one-shot render tears down
+  for you.