Skip to content

armgit / hypit

Public Imported from GitHub
0

Clone any viral video with AI agents. Not just a script, the whole workflow: swap the face, the words, the B-roll, ship 100 variants in one command, and get your 100M views.

docs: split quickstart into per-component sub-pages

rpone5348844381bf
diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts
index d66cccb0..d5fa7692 100644
--- a/docs/.vitepress/config.ts
+++ b/docs/.vitepress/config.ts
@@ -14,7 +14,19 @@ const enTheme = {
],
sidebar: {
"/quickstart": [
- { text: "Getting Started", items: [{ text: "Quickstart", link: "/quickstart" }] },
+ {
+ text: "Getting Started",
+ items: [
+ { text: "Overview", link: "/quickstart" },
+ { text: "Script", link: "/quickstart/script" },
+ { text: "SVS Stylesheets", link: "/quickstart/styles" },
+ { text: "Media & Generation", link: "/quickstart/generation" },
+ { text: "Timing & Assembly", link: "/quickstart/timing" },
+ { text: "Caption, B-roll & Text", link: "/quickstart/tracks" },
+ { text: "Film & Rendering", link: "/quickstart/composition" },
+ { text: "Run Source & Builds", link: "/quickstart/run" },
+ ],
+ },
],
"/guide/": [
{
@@ -44,7 +56,19 @@ const zhTheme = {
],
sidebar: {
"/zh/quickstart": [
- { text: "开始使用", items: [{ text: "Quickstart", link: "/zh/quickstart" }] },
+ {
+ text: "开始使用",
+ items: [
+ { text: "概览", link: "/zh/quickstart" },
+ { text: "Script", link: "/zh/quickstart/script" },
+ { text: "SVS 样式表", link: "/zh/quickstart/styles" },
+ { text: "媒体与生成", link: "/zh/quickstart/generation" },
+ { text: "时序与装配", link: "/zh/quickstart/timing" },
+ { text: "字幕、B-roll 与文字", link: "/zh/quickstart/tracks" },
+ { text: "Film 与渲染", link: "/zh/quickstart/composition" },
+ { text: "Run Source 与 Build", link: "/zh/quickstart/run" },
+ ],
+ },
],
"/zh/guide/": [
{
diff --git a/docs/quickstart.md b/docs/quickstart.md
index 77c3d0ad..e473bef8 100644
--- a/docs/quickstart.md
+++ b/docs/quickstart.md
@@ -37,17 +37,15 @@ Every Build takes three separate inputs:
Author Source says *what*. Run Source says *which*. Runtime Profile says *where*.
-## Check a video graph (free)
+## Your first graph check
The `talking-film-graph-check` example compiles a complete video graph — Script, Seedance, Speech,
WhisperX, Gemini Caption, B-roll, Text, Film, HyperFrames — without calling any external service.
```bash
-# Compile the Author Source.
pnpm narratage check examples/talking-film-graph-check/main.svml \
--package-lock examples/talking-film-graph-check/svml.packages.lock --root .
-# Compile the Run Source and inspect the frozen plan.
pnpm narratage plan examples/talking-film-graph-check/build.svrun \
--package-lock examples/talking-film-graph-check/svml.packages.lock --root .
```
@@ -56,84 +54,17 @@ pnpm narratage plan examples/talking-film-graph-check/build.svrun \
and outputs the frozen BuildPlan — every Operation and Needs the Scheduler would issue. Inspect it
before spending money.
-## Run a real Build (paid)
-
-The `echo-pro-aroll` example is a four-take Seedance Mini talking-head film.
-
-Prerequisites:
-
-- `KIE_API_KEY`, `GOOGLE_CLOUD_PROJECT`, `GOOGLE_APPLICATION_CREDENTIALS_JSON` in env
-- `ffmpeg`, `ffprobe`, Chrome
-- Local WhisperX service running (see `services/whisperx/README.md`)
-- Local assets in `examples/echo-pro-aroll/assets/` (not committed)
-
-```bash
-# Diagnose the Runtime environment.
-pnpm narratage doctor examples/echo-pro-aroll/svml.runtime.json
-
-# Submit the Build.
-pnpm narratage build examples/echo-pro-aroll/build.svrun \
- --runtime examples/echo-pro-aroll/svml.runtime.json \
- --package-lock examples/echo-pro-aroll/svml.packages.lock \
- --root . \
- --build-id echo-pro-film-001 \
- --follow
-
-# Retrieve the final video.
-pnpm narratage get echo-pro-film-001 \
- --runtime examples/echo-pro-aroll/svml.runtime.json \
- --name final.video \
- --to examples/echo-pro-aroll/output/final.mp4
-```
-
-Every accepted intermediate Record and Artifact is archived before the Build completes. `get`
-makes an optional copy of an already durable Record.
-
-## Reuse previous results
-
-Narratage has no implicit cache. Reusing a result is explicit Run Graph authoring — declare zero-input
-Candidates backed by historical Records and connect them through Satisfaction edges:
-
-```xml
-<?svml using="@narratage/run-text@1"?>
-<svrun version="1" targets="delivery">
- <author source="./main.svml"/>
- <target-set id="delivery">
- <target output="final.video" accepts="substitute"/>
- </target-set>
-
- <build-record id="hook-video"
- build="echo-pro-film-001" output="hook-take.video"/>
- <satisfy output="hook-take.video"
- candidate="hook-video" fidelity="substitute"/>
-</svrun>
-```
-
-The compiled plan prunes all upstream Operations that the substitute Candidates replace. This is a
-new Build, not a continuation.
-
-```bash
-pnpm narratage build examples/echo-pro-aroll/reuse-generated.svrun \
- --runtime examples/echo-pro-aroll/svml.runtime.json \
- --package-lock examples/echo-pro-aroll/svml.packages.lock \
- --root . --build-id echo-pro-film-reuse-001 --follow
-```
-
-## CLI reference
-
-```text
-narratage lock-packages <lock> --package name [--package name ...] [--root dir]
-narratage doctor <runtime.json>
-narratage gc <runtime.json> [--apply]
-narratage check <source> [--package-lock file] [--root dir]
-narratage plan <run-source> [--package-lock file] [--root dir]
-narratage build <run-source> --runtime profile [--build-id id] [--follow]
-narratage status <build-id> --runtime profile
-narratage builds --runtime profile
-narratage inspect <build-id> --runtime profile
-narratage get <build-id> --runtime profile [--name x|--record x|--output x|--artifact x] [--to path]
-narratage cancel <build-id> --runtime profile
-```
+## Guide contents
+
+| Guide | Topic |
+|---|---|
+| [Script](./quickstart/script.md) | Segments, Role Cues, Dual Text, Selections, Moments, text projections |
+| [SVS Stylesheets](./quickstart/styles.md) | CSS-like Recipes for film, caption, B-roll, text, speech and fonts |
+| [Media & Generation](./quickstart/generation.md) | media:Image, media:Audio, estimate:Speech, Seedance, speaker:Take |
+| [Timing & Assembly](./quickstart/timing.md) | speech:Spine, whisperx:Alignment, ProgramSpace, SemanticMap |
+| [Caption, B-roll & Text](./quickstart/tracks.md) | caption:Style/Program/Planner/Track, broll:Track, text:Track |
+| [Film & Rendering](./quickstart/composition.md) | film:Film, render:Video, full pipeline walkthrough |
+| [Run Source & Builds](./quickstart/run.md) | .svrun syntax, targets, reuse, runtime profile, build workflow |
## Next
diff --git a/docs/quickstart/composition.md b/docs/quickstart/composition.md
new file mode 100644
index 00000000..87ad65d7
--- /dev/null
+++ b/docs/quickstart/composition.md
@@ -0,0 +1,239 @@
+---
+title: Film & Rendering
+description: Composing tracks into a film and rendering to video.
+---
+
+# Film & Rendering
+
+Film is the final assembly stage. It takes all peer Tracks, validates them, and produces a
+Composition. The renderer then compiles that Composition into an MP4 video.
+
+```svml
+<import as="film" from="@narratage/film@1"/>
+<import as="render" from="@narratage/render-hyperframes@1"/>
+```
+
+## film:Film
+
+Assembles all Tracks into a single Composition. Film itself has no domain knowledge — it does not
+know what a caption is, what B-roll is, or what speech is. It takes any VisualTrack or AudioTrack
+and layers them by stacking order.
+
+```svml
+<film:Film id="main" space={speech.space} appearance={studio.film.vertical}>
+ <film:Track source={speech.visual}/>
+ <film:Track source={speech.audioTrack}/>
+ <film:Track source={captions.track}/>
+ <film:Track source={product-broll.visual}/>
+ <film:Track source={titles.track}/>
+</film:Film>
+```
+
+| Attribute | Required | Description |
+|---|---|---|
+| `id` | yes | Unique identifier |
+| `space` | yes | ProgramSpace from `speech:Spine` — defines duration and frame rate |
+| `appearance` | yes | SVS film Recipe — canvas width, height, frame rate, background |
+
+### film:Track
+
+Each `<film:Track>` child adds a Track source to the composition:
+
+| Attribute | Required | Description |
+|---|---|---|
+| `source` | yes | A VisualTrack or AudioTrack from any upstream component |
+
+Common Track sources:
+
+| Source | Type | From |
+|---|---|---|
+| `{speech.visual}` | VisualTrack | `speech:Spine` — full-screen talking head |
+| `{speech.audioTrack}` | AudioTrack | `speech:Spine` — synchronized audio |
+| `{captions.track}` | VisualTrack | `caption:Track` — timed captions |
+| `{cards.visual}` | VisualTrack | `broll:Track` — B-roll overlays |
+| `{titles.track}` | VisualTrack | `text:Track` — text overlays |
+
+### Track stacking
+
+Tracks are **flat** — there is no nesting or grouping. Z-ordering is determined entirely by the
+`stack-order` property in each Track's SVS Recipe. Lower values go behind; higher values render on
+top.
+
+Typical stacking order:
+
+| stack-order | Content |
+|---|---|
+| 10 | Speech visual (full-screen talking head) |
+| 40 | B-roll overlays |
+| 70 | Captions |
+| 90 | Text overlays |
+
+One component can emit multiple visual elements (Presents) at different z-positions, which
+interleave with other components' Presents. The final render flattens all Presents, sorts by
+absolute stacking key, and paints them onto one canvas.
+
+**Output:** `{main.composition}` — the complete Composition, passed to the renderer.
+
+## render:Video
+
+Compiles the Composition into a finished video via the HyperFrames renderer.
+
+```svml
+<render:Video id="final" composition={main.composition} space={speech.space}/>
+```
+
+| Attribute | Required | Description |
+|---|---|---|
+| `id` | yes | Unique identifier |
+| `composition` | yes | Composition from `film:Film` |
+| `space` | yes | ProgramSpace from `speech:Spine` |
+
+The renderer:
+
+1. Compiles the Composition into a `HyperframesDocument` — an HTML representation of every frame
+2. Renders each frame through Chrome/Chromium
+3. Encodes the frame sequence into video
+4. Mixes the audio Tracks
+5. Muxes video + audio into the final MP4
+
+**Output:** `{final.video}` — the finished video file. This is the most common Build Target.
+
+## Full pipeline walkthrough
+
+The complete data flow from Script to rendered video. This example is based on
+`examples/talking-film-graph-check/` — the smallest complete graph.
+
+### Author Source (`main.svml`)
+
+```svml
+<?svml using="@narratage/text@1"?>
+
+<svml>
+ <import from="@narratage/script@1"/>
+ <import as="seedance" from="@narratage/seedance@1"/>
+ <import as="speech" from="@narratage/speech-spine@1"/>
+ <import as="whisperx" from="@narratage/whisperx@1"/>
+ <import as="caption" from="@narratage/caption@1"/>
+ <import as="caption-ai" from="@narratage/caption-gemini@1"/>
+ <import as="broll" from="@narratage/broll@1"/>
+ <import as="text" from="@narratage/text-track@1"/>
+ <import as="film" from="@narratage/film@1"/>
+ <import as="render" from="@narratage/render-hyperframes@1"/>
+ <import as="studio" source="./studio.svs"/>
+
+ <!-- 1. Script: the semantic truth -->
+ <script id="story">
+ <opening><HOST>Meaning @demo becomes the source @/demo.</opening>
+ </script>
+
+ <!-- 2. Generation: Seedance talking head + standalone video -->
+ <seedance:Prompt id="direction">
+ Locked medium close-up in a quiet daylight studio.
+ </seedance:Prompt>
+ <seedance:Speech id="take" model="mini"
+ dialogue={story.segment.opening.dialogue}
+ prompt={direction} duration="5"/>
+ <seedance:Video id="motion" model="mini"
+ prompt={direction} duration="5"/>
+
+ <!-- 3. Timing: assemble spine and align words -->
+ <speech:Spine id="speech">
+ <speech:Take source={take} segment={story.segment.opening}/>
+ </speech:Spine>
+ <whisperx:Alignment id="timing" narrative={story} audio={speech.audio}/>
+
+ <!-- 4. Tracks: captions, B-roll, text -->
+ <caption:Style id="base-caption" appearance={studio.caption.base}>
+ <caption:Cues>Prefer short complete semantic phrases.</caption:Cues>
+ <caption:Field id="important" type="boolean"
+ min-per-cue="0" max-per-cue="2">
+ Select zero, one, or two words whose emphasis best communicates
+ this Cue.
+ </caption:Field>
+ </caption:Style>
+ <caption:Program id="caption-program" narrative={story}
+ default={base-caption}/>
+ <caption-ai:Planner id="cue-plan" narrative={story}
+ program={caption-program} model="gemini-2.5-flash"/>
+ <caption:Track id="captions" narrative={story} map={timing.map}
+ space={speech.space} plan={cue-plan.plan} program={caption-program}/>
+
+ <broll:Track id="cards" map={timing.map} space={speech.space}>
+ <broll:Item source={motion.video} during={story.selection.demo}
+ appearance={studio.broll.card}/>
+ </broll:Track>
+
+ <text:Track id="titles" space={speech.space}>
+ <text:Item text="MEANING" during="full"
+ appearance={studio.text.title}/>
+ </text:Track>
+
+ <!-- 5. Film: compose all tracks -->
+ <film:Film id="main" space={speech.space}
+ appearance={studio.film.vertical}>
+ <film:Track source={speech.visual}/>
+ <film:Track source={speech.audioTrack}/>
+ <film:Track source={cards.visual}/>
+ <film:Track source={captions.track}/>
+ <film:Track source={titles.track}/>
+ </film:Film>
+
+ <!-- 6. Render: compile to MP4 -->
+ <render:Video id="final" composition={main.composition}
+ space={speech.space}/>
+</svml>
+```
+
+### Stylesheet (`studio.svs`)
+
+```svs
+<?svml using="@narratage/svs@1"?>
+
+<sheet version="1">
+ film.vertical {
+ width: 1080; height: 1920; frame-rate: 30; background: #09090B;
+ }
+ broll.card {
+ stack-order: 40; x: 0.1; y: 0.2; width: 0.8; height: 0.5;
+ fit: cover; background: #111116; radius: 20;
+ enter: slide-up 4f; exit: fade 4f;
+ }
+ caption.base {
+ stack-order: 70; x: 0.08; y: 0.76; width: 0.84;
+ font: Inter; weight: 600; size: 58; line-height: 1; align: center;
+ fill: #FFFFFF; background: #09090BCC; padding: 16 24; radius: 18;
+ }
+ text.title {
+ stack-order: 90; x: 0.06; y: 0.06; width: 0.88; height: 0.1;
+ font: Inter; weight: 900; size: 64; align: center;
+ fill: #FFFFFF; tracking: -1;
+ }
+</sheet>
+```
+
+### Run Source (`build.svrun`)
+
+```svml
+<?svml using="@narratage/run-text@1"?>
+
+<svrun version="1" targets="delivery">
+ <author source="./main.svml"/>
+ <target-set id="delivery">
+ <target output="final.video" accepts="exact"/>
+ </target-set>
+</svrun>
+```
+
+### Compile and verify
+
+```bash
+pnpm narratage check examples/talking-film-graph-check/main.svml \
+ --package-lock examples/talking-film-graph-check/svml.packages.lock --root .
+
+pnpm narratage plan examples/talking-film-graph-check/build.svrun \
+ --package-lock examples/talking-film-graph-check/svml.packages.lock --root .
+```
+
+`check` compiles the Author Graph — validates all imports, types, and graph edges without calling
+any external service. `plan` additionally compiles the Run Source and outputs the frozen BuildPlan
+showing every Operation the Scheduler would issue. Inspect the plan before spending money.
diff --git a/docs/quickstart/generation.md b/docs/quickstart/generation.md
new file mode 100644
index 00000000..18618ac9
--- /dev/null
+++ b/docs/quickstart/generation.md
@@ -0,0 +1,286 @@
+---
+title: Media & Generation
+description: Declaring media assets and generating video with Seedance.
+---
+
+# Media & Generation
+
+This page covers components that declare static assets and generate new media — the raw materials
+that flow into the timing and track stages downstream.
+
+Every component shown here must be imported by its package specifier before use:
+
+```svml
+<import as="media" from="@narratage/media@1"/>
+<import as="estimate" from="@narratage/estimate@1"/>
+<import as="seedance" from="@narratage/seedance@1"/>
+<import as="speaker" from="@narratage/seedance-speaker@1"/>
+```
+
+## media:Image
+
+Declares a content-addressed image asset from a local file.
+
+```svml
+<media:Image id="presenter" src="./assets/presenter.png"/>
+```
+
+| Attribute | Required | Description |
+|---|---|---|
+| `id` | yes | Unique identifier for the component |
+| `src` | yes | Path to the image file, relative to the `.svml` source |
+
+The image is referenced downstream via `{presenter}` — for example, as a character reference in
+`seedance:Speech` or as a B-roll source.
+
+## media:Audio
+
+Declares a content-addressed audio asset from a local file.
+
+```svml
+<media:Audio id="presenter-voice" src="./assets/presenter-voice.mp3"/>
+```
+
+| Attribute | Required | Description |
+|---|---|---|
+| `id` | yes | Unique identifier |
+| `src` | yes | Path to the audio file, relative to the `.svml` source |
+
+Typically used as a voice-timbre reference for `speaker:Take`.
+
+## estimate:Speech
+
+Deterministic speech duration estimation from Script text. No external service call — the estimate is
+computed locally from word count and pace parameters.
+
+```svml
+<estimate:Speech id="hook-duration"
+ source={story.segment.hook.speech}
+ policy={studio.speech.normal}/>
+```
+
+| Attribute | Required | Description |
+|---|---|---|
+| `id` | yes | Unique identifier |
+| `source` | yes | Script text to estimate — typically `{script.segment.NAME.speech}` |
+| `policy` | yes | SVS speech Recipe controlling pace and bounds |
+
+The `policy` references an SVS Recipe (see [SVS Stylesheets](./styles.md#speech-estimation)):
+
+```svs
+speech.normal {
+ language: en;
+ pace: normal;
+ padding: 0.3;
+ min: 4;
+ max: 15;
+ rounding: ceil;
+}
+```
+
+You can also specify estimation parameters inline instead of using an SVS policy:
+
+```svml
+<estimate:Speech id="opening-duration"
+ source={story.segment.opening.speech}
+ language="en" pace="normal" padding="0.3" min="4" max="15" rounding="ceil"/>
+```
+
+**Output:** `{hook-duration.duration}` — the estimated duration in seconds, passed to generation
+components.
+
+## seedance:Prompt
+
+A reusable text block that provides visual direction for Seedance generation.
+
+```svml
+<seedance:Prompt id="alice-direction">
+ Locked medium close-up. Alice speaks directly to camera in a quiet daylight studio.
+ Calm, curious delivery; natural breathing and restrained hand movement.
+</seedance:Prompt>
+```
+
+| Attribute | Required | Description |
+|---|---|---|
+| `id` | yes | Unique identifier |
+
+The element body is the prompt text. Referenced by `seedance:Speech` and `seedance:Video` via their
+`prompt` attribute.
+
+## seedance:Speech
+
+Generates a talking-head video clip via the Seedance model. This is the low-level generation
+component — it directly specifies the dialogue, prompt, and duration.
+
+```svml
+<seedance:Speech id="alice-take" model="mini"
+ dialogue={story.segment.opening.dialogue}
+ prompt={alice-direction}
+ duration="8">
+ <seedance:Reference image={alice-reference} role="character"/>
+</seedance:Speech>
+```
+
+| Attribute | Required | Description |
+|---|---|---|
+| `id` | yes | Unique identifier |
+| `model` | yes | Seedance model name: `mini` |
+| `dialogue` | yes | Script text to lip-sync — typically `{script.segment.NAME.dialogue}` |
+| `prompt` | yes | Visual direction — reference to a `seedance:Prompt` |
+| `duration` | yes | Clip duration in seconds (number or `{estimate.duration}` reference) |
+| `resolution` | no | Output resolution: `480p`, `720p` (default varies by model) |
+| `aspect-ratio` | no | Output aspect ratio: `9:16`, `16:9`, `1:1` |
+
+### seedance:Reference
+
+Child element that provides a reference image for character consistency:
+
+```svml
+<seedance:Reference image={alice-reference} role="character"/>
+```
+
+| Attribute | Required | Description |
+|---|---|---|
+| `image` | yes | Reference to a `media:Image` component |
+| `role` | yes | How this reference is used: `character`, `subject` |
+
+**Output:** `{alice-take}` or `{alice-take.video}` — the generated video, passed to `speech:Spine`.
+
+## seedance:Video
+
+Generates a standalone video clip (not a talking-head — no dialogue lip-sync).
+
+```svml
+<seedance:Video id="product-motion" model="mini"
+ prompt={product-direction} duration="5">
+ <seedance:Reference image={product-reference} role="subject"/>
+</seedance:Video>
+```
+
+| Attribute | Required | Description |
+|---|---|---|
+| `id` | yes | Unique identifier |
+| `model` | yes | Seedance model name: `mini` |
+| `prompt` | yes | Visual direction — reference to a `seedance:Prompt` |
+| `duration` | yes | Clip duration in seconds |
+
+Also accepts `<seedance:Reference>` children for reference images.
+
+**Output:** `{product-motion.video}` — used as a B-roll source.
+
+## speaker:Take
+
+A higher-level talking-head component built on top of Prompt Kit. Instead of writing a raw prompt,
+you provide a Recipe with generation settings and a Kit that assembles the prompt automatically.
+
+```svml
+<import as="speaker" from="@narratage/seedance-speaker@1"/>
+<import as="ugc" source="../../packages/seedance-speaker/kits/official-ugc-v1.svs"/>
+
+<speaker:Take id="hook-take"
+ dialogue={story.segment.hook.dialogue}
+ duration={hook-duration.duration}
+ recipe={studio.speaker.echo-pro}
+ kit={ugc.official-ugc-v1}>
+ <speaker:Reference image={presenter-clean} role="character-and-scene"/>
+ <speaker:Reference audio={presenter-voice} role="voice-timbre"/>
+</speaker:Take>
+```
+
+| Attribute | Required | Description |
+|---|---|---|
+| `id` | yes | Unique identifier |
+| `dialogue` | yes | Script text — typically `{script.segment.NAME.dialogue}` |
+| `duration` | yes | Estimated duration from `estimate:Speech` |
+| `recipe` | yes | SVS speaker Recipe (see [SVS Stylesheets](./styles.md#speaker)) |
+| `kit` | yes | Prompt Kit SVS — the template that assembles the prompt |
+
+### speaker:Reference
+
+Child element providing reference media. Accepts both images and audio:
+
+```svml
+<speaker:Reference image={presenter-clean} role="character-and-scene"/>
+<speaker:Reference audio={presenter-voice} role="voice-timbre"/>
+```
+
+| Attribute | Required | Description |
+|---|---|---|
+| `image` | one of image/audio | Reference to a `media:Image` |
+| `audio` | one of image/audio | Reference to a `media:Audio` |
+| `role` | yes | Reference purpose: `character-and-scene`, `voice-timbre` |
+
+**Output:** `{hook-take.video}` — the generated video, passed to `speech:Spine`.
+
+### Prompt Kits
+
+A Prompt Kit is a special SVS file that defines a structured prompt template with ordered blocks,
+variant choices, axis parameters, and slots. The official kit is at
+`packages/seedance-speaker/kits/official-ugc-v1.svs`.
+
+The kit is imported using the Prompt Kit SVS parser:
+
+```svs
+<?svml using="@narratage/prompt-kit/svs@1"?>
+```
+
+The Recipe in `studio.svs` sets the axis parameter values (composition-stability, camera-motion,
+edit-rhythm, performance, gesture, voice-mode), and the kit assembles them into a complete prompt
+automatically.
+
+## Combination example
+
+A four-take setup with estimated durations feeding into `speaker:Take` generation:
+
+```svml
+<import as="media" from="@narratage/media@1"/>
+<import as="estimate" from="@narratage/estimate@1"/>
+<import as="speaker" from="@narratage/seedance-speaker@1"/>
+<import as="studio" source="./studio.svs"/>
+<import as="ugc" source="../../packages/seedance-speaker/kits/official-ugc-v1.svs"/>
+
+<media:Image id="presenter-clean" src="./assets/presenter-clean.png"/>
+<media:Image id="presenter-with-echo" src="./assets/presenter-with-echo.png"/>
+<media:Audio id="presenter-voice" src="./assets/presenter-voice.mp3"/>
+
+<estimate:Speech id="hook-duration"
+ source={story.segment.hook.speech} policy={studio.speech.normal}/>
+<estimate:Speech id="meeting-duration"
+ source={story.segment.meeting.speech} policy={studio.speech.normal}/>
+<estimate:Speech id="evidence-duration"
+ source={story.segment.evidence.speech} policy={studio.speech.normal}/>
+<estimate:Speech id="payoff-duration"
+ source={story.segment.payoff.speech} policy={studio.speech.normal}/>
+
+<speaker:Take id="hook-take" dialogue={story.segment.hook.dialogue}
+ duration={hook-duration.duration} recipe={studio.speaker.echo-pro}
+ kit={ugc.official-ugc-v1}>
+ <speaker:Reference image={presenter-clean} role="character-and-scene"/>
+ <speaker:Reference audio={presenter-voice} role="voice-timbre"/>
+</speaker:Take>
+
+<speaker:Take id="meeting-take" dialogue={story.segment.meeting.dialogue}
+ duration={meeting-duration.duration} recipe={studio.speaker.echo-pro}
+ kit={ugc.official-ugc-v1}>
+ <speaker:Reference image={presenter-with-echo} role="character-and-scene"/>
+ <speaker:Reference audio={presenter-voice} role="voice-timbre"/>
+</speaker:Take>
+
+<speaker:Take id="evidence-take" dialogue={story.segment.evidence.dialogue}
+ duration={evidence-duration.duration} recipe={studio.speaker.echo-pro}
+ kit={ugc.official-ugc-v1}>
+ <speaker:Reference image={presenter-with-echo} role="character-and-scene"/>
+ <speaker:Reference audio={presenter-voice} role="voice-timbre"/>
+</speaker:Take>
+
+<speaker:Take id="payoff-take" dialogue={story.segment.payoff.dialogue}
+ duration={payoff-duration.duration} recipe={studio.speaker.echo-pro}
+ kit={ugc.official-ugc-v1}>
+ <speaker:Reference image={presenter-clean} role="character-and-scene"/>
+ <speaker:Reference audio={presenter-voice} role="voice-timbre"/>
+</speaker:Take>
+```
+
+Each `speaker:Take` produces a `{*.video}` output that feeds into `speech:Spine` in the next stage.
+Different takes can use different reference images (e.g. the presenter holding a product in some
+Segments but not others) while sharing the same voice timbre and generation recipe.
diff --git a/docs/quickstart/run.md b/docs/quickstart/run.md
new file mode 100644
index 00000000..7538da7c
--- /dev/null
+++ b/docs/quickstart/run.md
@@ -0,0 +1,308 @@
+---
+title: Run Source & Builds
+description: Declaring build targets, reusing results and configuring the runtime.
+---
+
+# Run Source & Builds
+
+The Run Source (`.svrun`) declares **what to build** — which outputs to demand, what fidelity to
+accept, and optionally how to reuse results from prior Builds. The Runtime Profile
+(`svml.runtime.json`) declares **where to run** — endpoints, credentials, concurrency, and
+permissions.
+
+Neither of these changes what the video **is**. That is the Author Source's job.
+
+## Run Source syntax
+
+Every `.svrun` file begins with its processing instruction:
+
+```svml
+<?svml using="@narratage/run-text@1"?>
+```
+
+### Minimal Run Source
+
+```svml
+<?svml using="@narratage/run-text@1"?>
+
+<svrun version="1" targets="delivery">
+ <author source="./main.svml"/>
+ <target-set id="delivery">
+ <target output="final.video" accepts="exact"/>
+ </target-set>
+</svrun>
+```
+
+| Element | Description |
+|---|---|
+| `<svrun>` | Root element. `version="1"`, `targets` names the active target-set |
+| `<author>` | Mandatory. `source` points to the `.svml` Author Source |
+| `<target-set>` | A named set of demanded outputs |
+| `<target>` | One demanded output: `output` names a Logical Output, `accepts` sets fidelity |
+
+### Targets
+
+A **Target** names an output required by the Build and the worst fidelity it accepts:
+
+- `accepts="exact"` — the output must be exactly what the author declared
+- `accepts="substitute"` — an acceptable replacement is allowed (e.g. a prior generation)
+
+There is no privileged "final video" root. Any public Logical Output from any component can be a
+Target. The compiler only executes Operations needed to satisfy the demanded Targets — everything
+else is pruned.
+
+### Multiple targets
+
+You can demand multiple outputs from one Build:
+
+```svml
+<target-set id="delivery">
+ <target output="final.video" accepts="exact"/>
+ <target output="captions.track" accepts="exact"/>
+</target-set>
+```
+
+Or define multiple target-sets and switch between them:
+
+```svml
+<svrun version="1" targets="preview">
+ <author source="./main.svml"/>
+
+ <target-set id="preview">
+ <target output="captions.track" accepts="substitute"/>
+ </target-set>
+
+ <target-set id="delivery">
+ <target output="final.video" accepts="exact"/>
+ </target-set>
+</svrun>
+```
+
+The `targets` attribute on `<svrun>` selects which set is active.
+
+## Reusing results
+
+Narratage has no implicit cache. Reusing a result is explicit Run Graph authoring — you declare
+historical Records as zero-input Candidates and connect them through Satisfaction edges.
+
+```svml
+<?svml using="@narratage/run-text@1"?>
+
+<svrun version="1" targets="delivery">
+ <author source="./main.svml"/>
+ <target-set id="delivery">
+ <target output="final.video" accepts="substitute"/>
+ </target-set>
+
+ <build-record id="hook-video"
+ build="echo-pro-film-001" output="hook-take.video"/>
+ <build-record id="meeting-video"
+ build="echo-pro-film-001" output="meeting-take.video"/>
+ <build-record id="evidence-video"
+ build="echo-pro-film-001" output="evidence-take.video"/>
+ <build-record id="payoff-video"
+ build="echo-pro-film-001" output="payoff-take.video"/>
+
+ <satisfy output="hook-take.video"
+ candidate="hook-video" fidelity="substitute"/>
+ <satisfy output="meeting-take.video"
+ candidate="meeting-video" fidelity="substitute"/>
+ <satisfy output="evidence-take.video"
+ candidate="evidence-video" fidelity="substitute"/>
+ <satisfy output="payoff-take.video"
+ candidate="payoff-video" fidelity="substitute"/>
+</svrun>
+```
+
+### build-record
+
+Declares a zero-input Candidate backed by a historical Record from a previous Build:
+
+| Attribute | Description |
+|---|---|
+| `id` | Local Candidate id within this Run Source |
+| `build` | The build-id of the previous Build |
+| `output` | The Logical Output name from that Build |
+
+### satisfy
+
+Connects a Candidate to a Logical Output:
+
+| Attribute | Description |
+|---|---|
+| `output` | The Logical Output to satisfy |
+| `candidate` | The Candidate id (from `build-record`) |
+| `fidelity` | `exact` or `substitute` |
+
+The compiled plan prunes all upstream Operations that the substitute Candidates replace. This is a
+new Build, not a continuation of the old one. Downstream processing (normalization, WhisperX,
+captioning, rendering) still runs against the reused media.
+
+### Fidelity model
+
+- **`exact`** — the Candidate precisely matches what the author declared
+- **`substitute`** — the Candidate is an acceptable replacement
+
+Substitute fidelity is **monotonic**: once a substitute enters the graph, it propagates downstream.
+You cannot wash it back to exact. If the final target accepts `substitute`, downstream Operations
+that consume substitute inputs produce substitute results.
+
+## Runtime Profile
+
+The Runtime Profile (`svml.runtime.json`) tells the system **where** to run each type of work:
+
+```json
+{
+ "format": "svml.runtime-config@1",
+ "packageLock": "./svml.packages.lock",
+ "runtimePackageLock": "./svml.runtime-packages.lock",
+ "endpoints": [
+ {
+ "use": "@narratage/provider-kie",
+ "instance": "kie.main",
+ "lane": "generation",
+ "config": {
+ "apiKeyEnv": "KIE_API_KEY",
+ "defaultConcurrency": 2
+ }
+ },
+ {
+ "use": "@narratage/provider-media-local",
+ "instance": "media.main",
+ "lane": "media",
+ "config": { "defaultConcurrency": 2 }
+ },
+ {
+ "use": "@narratage/provider-whisperx-local",
+ "instance": "whisperx.main",
+ "lane": "alignment",
+ "config": { "defaultConcurrency": 1 }
+ },
+ {
+ "use": "@narratage/provider-google-vertex",
+ "instance": "vertex.main",
+ "lane": "planning",
+ "config": {
+ "projectEnv": "GOOGLE_CLOUD_PROJECT",
+ "credentialsEnv": "GOOGLE_APPLICATION_CREDENTIALS_JSON",
+ "location": "global",
+ "defaultConcurrency": 1
+ }
+ },
+ {
+ "use": "@narratage/provider-hyperframes-local",
+ "instance": "hyperframes.main",
+ "lane": "render",
+ "config": {
+ "workers": 2,
+ "quality": "standard",
+ "defaultConcurrency": 1
+ }
+ }
+ ],
+ "permissions": [
+ "filesystem:whisperx-staging",
+ "network:aiplatform.googleapis.com",
+ "network:api.kie.ai",
+ "network:kieai.redpandaai.co",
+ "network:whisperx-loopback",
+ "process:hyperframes",
+ "process:media"
+ ],
+ "scheduling": {
+ "maxConcurrency": 4,
+ "lanes": {
+ "generation": 2,
+ "media": 2,
+ "alignment": 1,
+ "planning": 1,
+ "render": 1
+ }
+ }
+}
+```
+
+### Endpoints
+
+Each endpoint binds a Provider package to a named instance with a concurrency lane:
+
+| Field | Description |
+|---|---|
+| `use` | Provider package name (e.g. `@narratage/provider-kie`) |
+| `instance` | Unique instance identifier |
+| `lane` | Scheduling lane for concurrency control |
+| `config` | Provider-specific configuration (API keys, concurrency, etc.) |
+
+### Permissions
+
+Explicit grants for filesystem, network, and process access. The scheduler refuses Operations that
+require permissions not listed here.
+
+### Scheduling
+
+`maxConcurrency` limits total parallel Operations. `lanes` sets per-lane concurrency limits to
+prevent one type of work from starving others.
+
+## Build workflow
+
+### 1. Diagnose the environment
+
+```bash
+pnpm narratage doctor examples/echo-pro-aroll/svml.runtime.json
+```
+
+Doctor checks that every endpoint is reachable, credentials are valid, and required executables
+(`ffmpeg`, `ffprobe`, Chrome) are available.
+
+### 2. Inspect the plan
+
+```bash
+pnpm narratage plan examples/echo-pro-aroll/build.svrun \
+ --package-lock examples/echo-pro-aroll/svml.packages.lock --root .
+```
+
+Review the frozen BuildPlan before spending money. The plan shows every Operation and Needs the
+Scheduler would issue.
+
+### 3. Submit the Build
+
+```bash
+pnpm narratage build examples/echo-pro-aroll/build.svrun \
+ --runtime examples/echo-pro-aroll/svml.runtime.json \
+ --package-lock examples/echo-pro-aroll/svml.packages.lock \
+ --root . \
+ --build-id echo-pro-film-001 \
+ --follow
+```
+
+| Flag | Description |
+|---|---|
+| `--runtime` | Path to the Runtime Profile |
+| `--package-lock` | Path to the package lock file |
+| `--root` | Workspace root directory |
+| `--build-id` | User-chosen identifier for this Build (used for retrieval and reuse) |
+| `--follow` | Stream Build progress to the terminal |
+
+### 4. Retrieve results
+
+```bash
+pnpm narratage get echo-pro-film-001 \
+ --runtime examples/echo-pro-aroll/svml.runtime.json \
+ --name final.video \
+ --to examples/echo-pro-aroll/output/final.mp4
+```
+
+Every accepted intermediate Record and Artifact is archived before the Build completes. `get` makes
+a copy of an already durable Record.
+
+### 5. Reuse in a new Build
+
+Create a new `.svrun` file that references the completed Build's Records (see [Reusing results](#reusing-results)
+above), then submit it:
+
+```bash
+pnpm narratage build examples/echo-pro-aroll/reuse-generated.svrun \
+ --runtime examples/echo-pro-aroll/svml.runtime.json \
+ --package-lock examples/echo-pro-aroll/svml.packages.lock \
+ --root . --build-id echo-pro-film-reuse-001 --follow
+```
diff --git a/docs/quickstart/script.md b/docs/quickstart/script.md
new file mode 100644
index 00000000..4ceefaab
--- /dev/null
+++ b/docs/quickstart/script.md
@@ -0,0 +1,262 @@
+---
+title: Script
+description: The Script Surface — Segments, Role Cues, Dual Text, Selections, Moments and text projections.
+---
+
+# Script
+
+The `<script>` element holds every word the narrator or speakers say. Script is **prose-first**: it
+contains no timecodes, no media references, no styling, no generation parameters. Everything else in
+the pipeline reads the Script; the Script reads nothing.
+
+```svml
+<import from="@narratage/script@1"/>
+
+<script id="story">
+ <opening>
+ <HOST> Hello world.
+ </opening>
+</script>
+```
+
+The import `@narratage/script@1` activates the Script Surface. The `id` attribute lets other
+components refer to the Script and its parts.
+
+## Segments
+
+Segments are ordered blocks of spoken content. The tag name **is** the id — it must be unique within
+a Script.
+
+```svml
+<script id="story">
+ <opening>
+ Hello world.
+ </opening>
+
+ <pause/>
+
+ <middle>
+ This is the second part.
+ </middle>
+
+ <close>
+ Goodbye.
+ </close>
+</script>
+```
+
+- A Segment can be self-closing (`<pause/>`). An empty Segment has structure but no speech tokens; it
+ does not imply silence or any default duration.
+- Segments cannot nest — every Segment is a top-level child of `<script>`.
+- Segment names follow XML naming rules: letters, digits, hyphens, underscores.
+
+Other components reference individual Segments via `{story.segment.opening}` and their text
+projections via `{story.segment.opening.dialogue}` or `{story.segment.opening.speech}`.
+
+## Role Cues
+
+Role Cues identify **who says what** inside a Segment. They are not speaker entities, do not select a
+voice, and do not create characters.
+
+```svml
+<dialogue>
+ <ALICE> What time is it?
+ <BOB> It's 8:30.
+</dialogue>
+```
+
+- A Role Cue has **no close tag**. A turn continues until the next Role Cue or the end of the Segment.
+- A Segment must be either entirely with or entirely without Role Cues — mixing is an error.
+- The label is 1–32 characters.
+
+Role Cues produce different text projections:
+
+| Projection | Output for the example above |
+|---|---|
+| **dialogue** | `ALICE: What time is it?`<br>`BOB: It's 8:30.` |
+| **speech** | `What time is it?`<br>`It's 8:30.` |
+| **caption** | `What time is it?`<br>`It's 8:30.` |
+
+The dialogue projection includes Role Cue prefixes. Speech and caption projections strip them.
+Components like `seedance:Speech` use `{story.segment.dialogue.dialogue}` (with labels) while
+`caption:Track` uses the caption projection (without labels).
+
+## Dual Text
+
+When what is displayed on screen differs from what is spoken:
+
+```svml
+<explanation>
+ <HOST> We call it <SVML | semantic video markup language>.
+</explanation>
+```
+
+The left side goes to the **caption** projection; the right side goes to **dialogue** and **speech**.
+
+| Projection | Output |
+|---|---|
+| **caption** | `We call it SVML.` |
+| **speech** | `We call it semantic video markup language.` |
+
+An empty left side is legal:
+
+```svml
+<HOST> I was < | um> saying that this works.
+```
+
+This means "um" is spoken but never displayed as a caption. The two sides can have different word
+counts — this is an N:M text mapping, not a 1:1 substitution.
+
+## Selections
+
+Selections are named time **ranges** declared inline:
+
+```svml
+<script id="story">
+ @whole
+ <opening>
+ <HOST> @problem Current tools make agents operate a timeline. @/problem
+ </opening>
+
+ <answer>
+ <HOST> @solution SVML removes that editing loop. @/solution
+ </answer>
+ @/whole~
+</script>
+```
+
+### Syntax
+
+| Marker | Meaning |
+|---|---|
+| `@id` | Open, right-absorbing (starts at the next word) |
+| `~@id` | Open, left-absorbing (starts at the previous word's end) |
+| `@/id` | Close, left-absorbing (ends at the previous word's end) |
+| `@/id~` | Close, right-absorbing (ends at the next word's start) |
+
+The `~` suffix/prefix controls whether the boundary snaps to the left or right. Default open is
+right-absorbing; default close is left-absorbing.
+
+### Non-contiguous Selections
+
+The same id can appear multiple times to create a Selection with gaps:
+
+```svml
+<demo>
+ <HOST> @beat First point. @/beat Then something else. @beat Third point. @/beat
+</demo>
+```
+
+`{story.selection.beat}` now covers two disjoint ranges.
+
+### Crossing Selections
+
+Selections are not required to nest like XML tags. They can cross each other:
+
+```svml
+<demo>
+ <HOST> @a One @b two @/a three @/b.
+</demo>
+```
+
+Selection markers are zero-width and never appear in any text projection. They compile into
+`SelectionSet` values containing `Range[]`. Script itself contains no seconds or frame numbers —
+timing comes from WhisperX alignment.
+
+Other components reference Selections via `{story.selection.problem}` to bind visual content to
+semantic moments in the narrative.
+
+## Moments
+
+Moments are named time **points** (not ranges):
+
+```svml
+<ecosystem>
+ <HOST> @ranking! Image generation, video generation, captions and B-roll
+ all become reusable components.
+</ecosystem>
+```
+
+| Marker | Meaning |
+|---|---|
+| `@id!` | Right-absorbing (point at the next word's start) |
+| `~@id!` | Left-absorbing (point at the previous word's end) |
+
+Moments compile into `MomentSet` values containing `Point[]`. Selection and Moment share the same
+name namespace — the same id cannot be used for both.
+
+Other components reference Moments via `{story.moment.ranking}`.
+
+## Slots
+
+Variable interpolation for templated Scripts:
+
+```svml
+<intro>
+ <HOST> Meet <${product} | ${product_pronunciation}>.
+</intro>
+```
+
+Slot ids are 1–64 characters, starting with a letter or underscore. Binding values are literal
+text — they cannot inject SVML syntax. Slots are parsed first, then bound.
+
+## Comments and escaping
+
+```svml
+<!-- This is a comment. Comments never enter any projection. -->
+
+<demo>
+ <HOST> Follow us \@svml on social media.
+</demo>
+```
+
+Reserved syntax starters must be escaped:
+
+| Escape | Produces |
+|---|---|
+| `\@` | literal `@` |
+| `\<` | literal `<` |
+| `\${` | literal `${` |
+| `\\` | literal `\` |
+
+Inside Dual Text, also escape `\|` and `\>`.
+
+## Combination example
+
+A complete Script using all constructs together:
+
+```svml
+<script id="story">
+ @whole
+ <hook>
+ <HOST> @problem Girls, you need to hear this. Never let anyone take credit
+ for your work. @/problem
+ </hook>
+
+ <meeting>
+ <HOST> @solution Then I found <Echo Pro | echo pro>: a card-sized recorder
+ that snaps onto the back of my phone. @ranking! I brought it to one
+ meeting. @/solution
+ </meeting>
+
+ <evidence>
+ <HOST> That gave me @emphasis the courage I was missing @/emphasis.
+ </evidence>
+
+ <payoff>
+ <HOST> And guess what? I'm sitting in my old boss's chair now.
+ </payoff>
+ @/whole~
+</script>
+```
+
+This Script declares:
+
+- Four Segments: `hook`, `meeting`, `evidence`, `payoff`
+- One Role Cue: `HOST` (consistent across all Segments)
+- One Dual Text: `<Echo Pro | echo pro>` (displayed as "Echo Pro", spoken as "echo pro")
+- Three Selections: `whole` (entire Script), `problem`, `solution`, `emphasis`
+- One Moment: `ranking` (marks the instant "I brought it to one meeting")
+
+Downstream components reference these by name: `{story.segment.hook.dialogue}` for generation,
+`{story.selection.problem}` for B-roll timing, `{story.moment.ranking}` for a visual card reveal.
diff --git a/docs/quickstart/styles.md b/docs/quickstart/styles.md
new file mode 100644
index 00000000..7e18dfdd
--- /dev/null
+++ b/docs/quickstart/styles.md
@@ -0,0 +1,400 @@
+---
+title: SVS Stylesheets
+description: The SVS Recipe language — CSS-like stylesheets for film, caption, B-roll, text and generation settings.
+---
+
+# SVS Stylesheets
+
+SVS (`.svs`) files define reusable, typed configuration values using a CSS-like syntax. They
+configure film dimensions, caption appearance, B-roll layout, text styling, speech estimation
+parameters, generation settings, and custom fonts. SVS values are called **Recipes** — they are
+immutable typed Records that consuming components validate and interpret.
+
+## Basic syntax
+
+```svs
+<?svml using="@narratage/svs@1"?>
+
+<sheet version="1" id="studio">
+ film.vertical {
+ width: 1080;
+ height: 1920;
+ frame-rate: 30;
+ background: #09090B;
+ }
+
+ /* Comments use CSS-style block syntax. */
+ caption.primary {
+ fill: #FFFFFF;
+ size: 58;
+ }
+</sheet>
+```
+
+- The processing instruction `<?svml using="@narratage/svs@1"?>` selects the SVS parser.
+- The `<sheet>` element wraps all declarations. The `id` attribute becomes the top-level namespace.
+- Each block is `namespace.name { ... }` with `;`-terminated key-value properties.
+- Comments use `/* ... */`.
+
+## Importing and referencing
+
+Import an SVS file in your `.svml` source with a namespace prefix:
+
+```svml
+<import as="studio" source="./studio.svs"/>
+```
+
+Then reference individual Recipes via `{studio.film.vertical}`, `{studio.caption.primary}`, etc.
+The prefix comes from the `as=` attribute; the path comes from `namespace.name` in the sheet.
+
+## Film
+
+Film appearance — canvas dimensions and background color.
+
+```svs
+film.vertical {
+ width: 1080;
+ height: 1920;
+ frame-rate: 30;
+ background: #09090B;
+}
+```
+
+| Property | Description |
+|---|---|
+| `width` | Canvas width in pixels |
+| `height` | Canvas height in pixels |
+| `frame-rate` | Frames per second (typically 30) |
+| `background` | Canvas clear color (hex) |
+
+Referenced by `film:Film` via the `appearance` attribute:
+
+```svml
+<film:Film id="main" space={speech.space} appearance={studio.film.vertical}>
+```
+
+## Caption
+
+Caption visual appearance — position, typography, and container styling.
+
+```svs
+caption.dialogue {
+ stack-order: 70;
+ x: 0.08;
+ y: 0.76;
+ width: 0.84;
+ font: Inter;
+ weight: 600;
+ size: 58;
+ line-height: 0.96;
+ align: center;
+ fill: #FFFFFF;
+ background: #09090BCC;
+ padding: 16 24;
+ radius: 18;
+}
+```
+
+| Property | Description |
+|---|---|
+| `stack-order` | Z-stacking order among all Tracks (higher = on top) |
+| `x`, `y` | Position as fraction of canvas (0–1) |
+| `width` | Width as fraction of canvas |
+| `font` | Font family name or SVS font reference |
+| `weight` | Font weight (400–900) |
+| `size` | Font size in pixels |
+| `line-height` | Line height multiplier |
+| `align` | Text alignment: `left`, `center`, `right` |
+| `fill` | Text color (hex, supports alpha) |
+| `background` | Container background color (hex, supports alpha like `#09090BCC`) |
+| `padding` | Container padding in pixels (single value or `vertical horizontal`) |
+| `radius` | Container border radius in pixels |
+
+Referenced by `caption:Style` via the `appearance` attribute:
+
+```svml
+<caption:Style id="primary-caption" appearance={studio.caption.dialogue}>
+```
+
+### Per-role caption styles
+
+Define multiple caption Recipes for different speakers:
+
+```svs
+caption.alice {
+ stack-order: 70;
+ x: 0.08; y: 0.76; width: 0.84;
+ font: Inter; weight: 600; size: 58;
+ fill: #73FBD3;
+ background: #09090BCC;
+ padding: 16 24; radius: 18;
+}
+
+caption.bob {
+ stack-order: 70;
+ x: 0.08; y: 0.76; width: 0.84;
+ font: Inter; weight: 600; size: 58;
+ fill: #FFD166;
+ background: #09090BCC;
+ padding: 16 24; radius: 18;
+}
+```
+
+Then assign them via `caption:Program`:
+
+```svml
+<caption:Program id="caption-program" narrative={story} default={studio.caption.dialogue}>
+ <caption:Use role="ALICE" style={alice-caption}/>
+ <caption:Use role="BOB" style={bob-caption}/>
+</caption:Program>
+```
+
+## B-roll
+
+B-roll item appearance — position, fit, container, and enter/exit animations.
+
+```svs
+broll.product {
+ stack-order: 40;
+ x: 0.08;
+ y: 0.20;
+ width: 0.84;
+ height: 0.48;
+ fit: contain;
+ background: #111116;
+ radius: 28;
+ enter: slide-up 8f;
+ exit: fade 6f;
+}
+```
+
+| Property | Description |
+|---|---|
+| `stack-order` | Z-stacking order |
+| `x`, `y` | Position as fraction of canvas |
+| `width`, `height` | Size as fraction of canvas |
+| `fit` | How the source fits the container: `cover`, `contain` |
+| `background` | Container background color |
+| `radius` | Container border radius |
+| `enter` | Enter animation: `slide-up Nf`, `fade Nf` (N = frames) |
+| `exit` | Exit animation: `fade Nf`, `slide-down Nf` |
+
+Referenced by `broll:Item` via the `appearance` attribute:
+
+```svml
+<broll:Item source={motion.video} during={story.selection.demo}
+ appearance={studio.broll.product}/>
+```
+
+## Text
+
+Text overlay appearance — position, typography.
+
+```svs
+text.title {
+ stack-order: 90;
+ x: 0.06;
+ y: 0.06;
+ width: 0.88;
+ height: 0.10;
+ font: Inter;
+ weight: 900;
+ size: 64;
+ align: center;
+ fill: #FFFFFF;
+ tracking: -1;
+}
+```
+
+| Property | Description |
+|---|---|
+| `stack-order` | Z-stacking order |
+| `x`, `y` | Position as fraction of canvas |
+| `width`, `height` | Size as fraction of canvas |
+| `font` | Font family name |
+| `weight` | Font weight |
+| `size` | Font size in pixels |
+| `align` | Text alignment |
+| `fill` | Text color |
+| `tracking` | Letter spacing adjustment |
+
+Referenced by `text:Item` via the `appearance` attribute:
+
+```svml
+<text:Item text="MEANING" during="full" appearance={studio.text.title}/>
+```
+
+## Speech estimation
+
+Parameters for deterministic speech duration estimation.
+
+```svs
+speech.normal {
+ language: en;
+ pace: normal;
+ padding: 0.3;
+ min: 4;
+ max: 15;
+ rounding: ceil;
+}
+```
+
+| Property | Description |
+|---|---|
+| `language` | Language code (e.g. `en`) |
+| `pace` | Speaking pace: `slow`, `normal`, `fast` |
+| `padding` | Extra padding in seconds added to the estimate |
+| `min` | Minimum duration in seconds |
+| `max` | Maximum duration in seconds |
+| `rounding` | Rounding mode: `ceil`, `floor`, `round` |
+
+Referenced by `estimate:Speech` via the `policy` attribute:
+
+```svml
+<estimate:Speech id="hook-duration" source={story.segment.hook.speech}
+ policy={studio.speech.normal}/>
+```
+
+## Speaker
+
+Seedance Speaker generation settings — the Recipe that controls how `speaker:Take` generates a
+talking-head clip.
+
+```svs
+speaker.echo-pro {
+ kind: ugc-talking-head;
+ model: mini;
+ resolution: 720p;
+ aspect-ratio: 9:16;
+ composition-stability: soft-locked;
+ camera-motion: none;
+ edit-rhythm: continuous-take;
+ performance: natural-explainer;
+ gesture: natural;
+ voice-mode: single-speaker;
+}
+```
+
+| Property | Description |
+|---|---|
+| `kind` | Generation kind (e.g. `ugc-talking-head`) |
+| `model` | Model name: `mini` |
+| `resolution` | Output resolution: `480p`, `720p`, `1080p` |
+| `aspect-ratio` | Output aspect ratio: `9:16`, `16:9`, `1:1` |
+| `composition-stability` | Camera/composition consistency: `flexible-ugc`, `soft-locked`, `strict-locked` |
+| `camera-motion` | Camera movement: `none`, `subtle-punch-in-return` |
+| `edit-rhythm` | Editing style: `continuous-take`, `pause-trim-jump-cuts` |
+| `performance` | Acting style: `natural-explainer`, `high-energy-ugc`, `calm-authority`, `reactive-playful` |
+| `gesture` | Gesture intensity: `restrained`, `compact`, `natural`, `expressive` |
+| `voice-mode` | Voice configuration: `single-speaker` |
+
+Referenced by `speaker:Take` via the `recipe` attribute:
+
+```svml
+<speaker:Take id="hook-take" dialogue={story.segment.hook.dialogue}
+ duration={hook-duration.duration} recipe={studio.speaker.echo-pro} kit={ugc.official-ugc-v1}>
+```
+
+## Font declarations
+
+Declare local font files for use in captions and text overlays.
+
+```svs
+font.inter-semibold {
+ src: ./assets/Inter-SemiBold.woff2;
+ weight: 600;
+ style: normal;
+}
+
+font.inter-black {
+ src: ./assets/Inter-Black.woff2;
+ weight: 900;
+ style: normal;
+}
+```
+
+| Property | Description |
+|---|---|
+| `src` | Path to the font file (relative to the SVS file) |
+| `weight` | Font weight this file provides |
+| `style` | Font style: `normal`, `italic` |
+
+Font paths are resolved at compile time and become `FontArtifactRef` values. Reference them by name
+in other SVS blocks:
+
+```svs
+caption.dialogue {
+ font: inter-semibold;
+ /* ... */
+}
+```
+
+## Combination example
+
+A complete `studio.svs` file for a four-take talking-head project:
+
+```svs
+<?svml using="@narratage/svs@1"?>
+
+<sheet version="1" id="studio">
+ speech.normal {
+ language: en;
+ pace: normal;
+ padding: 0.3;
+ min: 4;
+ max: 15;
+ rounding: ceil;
+ }
+
+ speaker.echo-pro {
+ kind: ugc-talking-head;
+ model: mini;
+ resolution: 720p;
+ aspect-ratio: 9:16;
+ composition-stability: soft-locked;
+ camera-motion: none;
+ edit-rhythm: continuous-take;
+ performance: natural-explainer;
+ gesture: natural;
+ voice-mode: single-speaker;
+ }
+
+ film.vertical {
+ width: 720;
+ height: 1280;
+ frame-rate: 30;
+ background: #09090B;
+ }
+
+ caption.primary {
+ stack-order: 70;
+ x: 0.08;
+ y: 0.74;
+ width: 0.84;
+ font: Inter;
+ weight: 800;
+ size: 44;
+ line-height: 1;
+ align: center;
+ fill: #FFFFFF;
+ background: #09090BCC;
+ padding: 14 20;
+ radius: 16;
+ }
+</sheet>
+```
+
+This file is imported once in the `.svml` source and its values are referenced throughout:
+
+```svml
+<import as="studio" source="./studio.svs"/>
+
+<estimate:Speech id="hook-duration" source={story.segment.hook.speech}
+ policy={studio.speech.normal}/>
+
+<speaker:Take id="hook-take" ... recipe={studio.speaker.echo-pro} .../>
+
+<caption:Style id="primary-caption" appearance={studio.caption.primary} .../>
+
+<film:Film id="main" space={speech.space} appearance={studio.film.vertical}>
+```
diff --git a/docs/quickstart/timing.md b/docs/quickstart/timing.md
new file mode 100644
index 00000000..a11dbc39
--- /dev/null
+++ b/docs/quickstart/timing.md
@@ -0,0 +1,161 @@
+---
+title: Timing & Assembly
+description: Speech Spine assembly and WhisperX alignment — connecting generated takes to a unified timeline.
+---
+
+# Timing & Assembly
+
+After generation, individual takes must be concatenated into one continuous A/V coordinate space,
+and the spoken words must be measured against the actual audio to create a timing map. These two
+steps produce the **ProgramSpace** and **SemanticMap** that every downstream component depends on.
+
+```svml
+<import as="speech" from="@narratage/speech-spine@1"/>
+<import as="whisperx" from="@narratage/whisperx@1"/>
+```
+
+## speech:Spine
+
+Concatenates multiple takes into one ordered audio/visual coordinate space. The Spine defines the
+program order — the final sequence of Segments in the finished video.
+
+```svml
+<speech:Spine id="speech">
+ <speech:Take source={hook-take.video} segment={story.segment.hook}/>
+ <speech:Take source={meeting-take.video} segment={story.segment.meeting}/>
+ <speech:Take source={evidence-take.video} segment={story.segment.evidence}/>
+ <speech:Take source={payoff-take.video} segment={story.segment.payoff}/>
+</speech:Spine>
+```
+
+| Attribute | Required | Description |
+|---|---|---|
+| `id` | yes | Unique identifier |
+
+### speech:Take
+
+Each `<speech:Take>` child binds a generated video to a Script Segment:
+
+| Attribute | Required | Description |
+|---|---|---|
+| `source` | yes | Generated video — from `seedance:Speech`, `speaker:Take`, etc. |
+| `segment` | yes | Script Segment this take corresponds to — e.g. `{story.segment.hook}` |
+
+The order of `<speech:Take>` children **determines the program order**. The first take starts at
+time zero; each subsequent take follows immediately.
+
+### Outputs
+
+The Spine produces four outputs used by downstream components:
+
+| Output | Type | Used by |
+|---|---|---|
+| `{speech.visual}` | VisualTrack | `film:Film` — the full-screen talking-head video |
+| `{speech.audio}` | Audio | `whisperx:Alignment` — raw audio for word timing |
+| `{speech.audioTrack}` | AudioTrack | `film:Film` — the synchronized audio |
+| `{speech.space}` | ProgramSpace | Everything — the unified duration and frame domain |
+
+## whisperx:Alignment
+
+Measures word-level timing by running WhisperX speech-to-text alignment on the Spine's audio output.
+This produces the **SemanticMap** — the bridge between Script text and physical time.
+
+```svml
+<whisperx:Alignment id="timing" narrative={story} audio={speech.audio}/>
+```
+
+| Attribute | Required | Description |
+|---|---|---|
+| `id` | yes | Unique identifier |
+| `narrative` | yes | The Script component — e.g. `{story}` |
+| `audio` | yes | Audio from the Speech Spine — `{speech.audio}` |
+
+### Output
+
+| Output | Type | Used by |
+|---|---|---|
+| `{timing.map}` | CompleteSemanticMap | `caption:Track`, `broll:Track`, `text:Track` — timed placement |
+
+The SemanticMap maps every authored Script anchor to a time point. It covers all `2M + 2N` identities
+(where M = total speech tokens, N = number of Segments). This is how Selections and Moments declared
+in the Script become real time ranges and points for downstream visual components.
+
+## ProgramSpace
+
+ProgramSpace is not a component you declare — it is produced by `speech:Spine` and flows to every
+component that needs to know the total program duration and frame domain.
+
+```svml
+<film:Film id="main" space={speech.space} ...>
+<caption:Track id="captions" ... space={speech.space} .../>
+<text:Track id="titles" space={speech.space}>
+<render:Video id="final" composition={main.composition} space={speech.space}/>
+```
+
+ProgramSpace owns:
+
+- **Duration** — the total program length
+- **Frame rate** — rational frame rate (e.g. 30fps)
+- **Frame domain** — exact frame numbers for the entire program
+
+Every component that operates in the time domain takes a `space` attribute pointing to
+`{speech.space}`.
+
+## SemanticMap
+
+The SemanticMap is the typed bridge between Script text and physical time. When you write
+`during={story.selection.demo}` on a B-roll item, the component uses the SemanticMap to look up the
+exact frame range that Selection covers. Without a SemanticMap, Selections and Moments have no
+physical meaning.
+
+Components that use the map take it via the `map` attribute:
+
+```svml
+<broll:Track id="cards" map={timing.map} ...>
+<caption:Track id="captions" ... map={timing.map} .../>
+```
+
+Each point in the map can be:
+
+- **measured** — directly observed by WhisperX alignment
+- **derived** — computed from measured points via interpolation
+- **estimated** — from the initial duration estimate (used before alignment runs)
+
+## Combination example
+
+The complete timing stage, from generated takes to map and space:
+
+```svml
+<import as="speech" from="@narratage/speech-spine@1"/>
+<import as="whisperx" from="@narratage/whisperx@1"/>
+
+<!-- Assemble takes in program order -->
+<speech:Spine id="speech">
+ <speech:Take source={opening-take} segment={story.segment.opening}/>
+ <speech:Take source={answer-take} segment={story.segment.answer}/>
+</speech:Spine>
+
+<!-- Measure word timing -->
+<whisperx:Alignment id="timing" narrative={story} audio={speech.audio}/>
+
+<!-- Downstream components now reference: -->
+<!-- {speech.space} — ProgramSpace for duration/frame domain -->
+<!-- {speech.visual} — VisualTrack for the talking-head video -->
+<!-- {speech.audioTrack} — AudioTrack for synchronized audio -->
+<!-- {timing.map} — SemanticMap for Selection/Moment timing -->
+```
+
+The data flow:
+
+```text
+speaker:Take outputs ──► speech:Spine ──► whisperx:Alignment
+ │ │
+ .visual .map (SemanticMap)
+ .audio │
+ .audioTrack ▼
+ .space ──────────► caption:Track
+ │ broll:Track
+ │ text:Track
+ ▼ film:Film
+ film:Film render:Video
+```
diff --git a/docs/quickstart/tracks.md b/docs/quickstart/tracks.md
new file mode 100644
index 00000000..a4f11cfa
--- /dev/null
+++ b/docs/quickstart/tracks.md
@@ -0,0 +1,357 @@
+---
+title: Caption, B-roll & Text
+description: Visual track components — captions, B-roll overlays and text overlays.
+---
+
+# Caption, B-roll & Text
+
+Every audiovisual contribution entering the final composition is a peer **Track**. Tracks are flat
+(no nesting), and their z-order is determined by the `stack-order` property in SVS. This page
+covers the three main visual Track types: captions, B-roll, and text overlays.
+
+## Caption system
+
+Captions are built from four components that form a pipeline:
+
+```text
+caption:Style → caption:Program → caption-ai:Planner → caption:Track
+```
+
+```svml
+<import as="caption" from="@narratage/caption@1"/>
+<import as="caption-ai" from="@narratage/caption-gemini@1"/>
+```
+
+### caption:Style
+
+Declares a complete visual appearance plus planning instructions for one style of caption.
+
+```svml
+<caption:Style id="primary-caption" appearance={studio.caption.primary}
+ mode="proportional-word">
+ <caption:Cues>
+ Split each Script Segment into short complete semantic phrases of two to
+ seven words. Never cross a sentence or Segment boundary.
+ </caption:Cues>
+ <caption:Field id="important" type="boolean" min-per-cue="1" max-per-cue="2">
+ Select one or two words whose emphasis best communicates this Cue.
+ </caption:Field>
+</caption:Style>
+```
+
+| Attribute | Required | Description |
+|---|---|---|
+| `id` | yes | Unique identifier |
+| `appearance` | yes | SVS caption Recipe — position, font, colors, container |
+| `mode` | no | Caption timing mode, e.g. `proportional-word` |
+
+**Children:**
+
+- `<caption:Cues>` — natural-language instructions for the AI planner telling it how to split text
+ into cues. The planner receives display text (left side of Dual Text) and these instructions, but
+ never audio or timing data.
+- `<caption:Field>` — declares a typed per-atom annotation. The planner assigns these fields to
+ individual words within each cue.
+
+| `<caption:Field>` attribute | Description |
+|---|---|
+| `id` | Field name (e.g. `important`) |
+| `type` | Field type: `boolean` |
+| `min-per-cue` | Minimum annotations per cue |
+| `max-per-cue` | Maximum annotations per cue |
+
+The element body of `<caption:Field>` is a natural-language instruction for the planner.
+
+### caption:Program
+
+Assigns caption styles to the narrative. Declares a default style and optional per-role or
+per-Selection overrides.
+
+```svml
+<caption:Program id="caption-program" narrative={story} default={primary-caption}>
+ <caption:Use role="ALICE" style={alice-caption}/>
+ <caption:Use role="BOB" style={bob-caption}/>
+ <caption:Use on={story.selection.product-demo} style={dialogue-caption}/>
+</caption:Program>
+```
+
+| Attribute | Required | Description |
+|---|---|---|
+| `id` | yes | Unique identifier |
+| `narrative` | yes | The Script component |
+| `default` | yes | Default `caption:Style` for all text |
+
+**Children:**
+
+`<caption:Use>` applies style overrides. Rules are applied in source order — last match wins.
+
+| `<caption:Use>` attribute | Description |
+|---|---|
+| `role` | Match by Role Cue label (e.g. `"ALICE"`) |
+| `on` | Match by Selection reference (e.g. `{story.selection.product-demo}`) |
+| `style` | The `caption:Style` to apply |
+
+Use `role=` to give different speakers different caption colors. Use `on=` to override style during
+specific Selections (e.g. a product demo section uses a different caption style).
+
+### caption-ai:Planner
+
+AI-driven cue planning via Gemini. The planner receives the display text atoms, the Style
+instructions, and the Program assignments. It splits text into cues and assigns Field values.
+
+```svml
+<caption-ai:Planner id="caption-plan" narrative={story}
+ program={caption-program} model="gemini-2.5-flash"/>
+```
+
+| Attribute | Required | Description |
+|---|---|---|
+| `id` | yes | Unique identifier |
+| `narrative` | yes | The Script component |
+| `program` | yes | The `caption:Program` |
+| `model` | yes | Gemini model: `gemini-2.5-flash` |
+
+The planner never receives audio, timing data, or the speech side of Dual Text. It works entirely
+from the caption (display) projection.
+
+**Output:** `{caption-plan.plan}` — the cue plan, passed to `caption:Track`.
+
+### caption:Track
+
+Joins the cue plan, SemanticMap, ProgramSpace, and Program to produce a timed VisualTrack.
+
+```svml
+<caption:Track id="captions" narrative={story} map={timing.map}
+ space={speech.space} program={caption-program} plan={caption-plan.plan}/>
+```
+
+| Attribute | Required | Description |
+|---|---|---|
+| `id` | yes | Unique identifier |
+| `narrative` | yes | The Script component |
+| `map` | yes | SemanticMap from `whisperx:Alignment` |
+| `space` | yes | ProgramSpace from `speech:Spine` |
+| `program` | yes | The `caption:Program` |
+| `plan` | yes | Cue plan from `caption-ai:Planner` |
+
+**Output:** `{captions.track}` — a VisualTrack added to `film:Film`.
+
+### Caption combination example
+
+The full caption pipeline with per-role styles:
+
+```svml
+<caption:Style id="dialogue-caption" appearance={studio.caption.dialogue}>
+ <caption:Cues>Use short complete semantic phrases, two to five words.</caption:Cues>
+</caption:Style>
+
+<caption:Style id="alice-caption" appearance={studio.caption.alice}>
+ <caption:Cues>Use short complete semantic phrases, two to five words.</caption:Cues>
+ <caption:Field id="important" type="boolean" min-per-cue="0" max-per-cue="2">
+ Select at most two words whose emphasis best communicates this Cue.
+ </caption:Field>
+</caption:Style>
+
+<caption:Style id="bob-caption" appearance={studio.caption.bob}>
+ <caption:Cues>Use short complete semantic phrases, two to five words.</caption:Cues>
+</caption:Style>
+
+<caption:Program id="caption-program" narrative={story} default={dialogue-caption}>
+ <caption:Use role="ALICE" style={alice-caption}/>
+ <caption:Use role="BOB" style={bob-caption}/>
+ <caption:Use on={story.selection.product-demo} style={dialogue-caption}/>
+</caption:Program>
+
+<caption-ai:Planner id="caption-plan" narrative={story}
+ program={caption-program} model="gemini-2.5-flash"/>
+
+<caption:Track id="captions" narrative={story} map={timing.map}
+ space={speech.space} program={caption-program} plan={caption-plan.plan}/>
+```
+
+ALICE gets green captions (`#73FBD3`), BOB gets gold (`#FFD166`), and during the product-demo
+Selection both switch to the neutral dialogue style. The `important` Field only applies to ALICE's
+style — her emphasized words get special treatment.
+
+## B-roll
+
+B-roll overlays generated or provided video/images at semantic time positions.
+
+```svml
+<import as="broll" from="@narratage/broll@1"/>
+```
+
+### broll:Track
+
+Container for B-roll items. Takes the SemanticMap for timing resolution.
+
+```svml
+<broll:Track id="product-broll" map={timing.map} space={speech.space}>
+ <broll:Item source={product-motion.video}
+ during={story.selection.product-demo}
+ appearance={studio.broll.product}/>
+</broll:Track>
+```
+
+| Attribute | Required | Description |
+|---|---|---|
+| `id` | yes | Unique identifier |
+| `map` | yes | SemanticMap from `whisperx:Alignment` |
+| `space` | no | ProgramSpace (required by some configurations) |
+
+### broll:Item
+
+Each item places a source at a semantic time position with styled appearance:
+
+```svml
+<broll:Item source={product-motion.video}
+ during={story.selection.product-demo}
+ appearance={studio.broll.product}/>
+```
+
+| Attribute | Required | Description |
+|---|---|---|
+| `source` | yes | Video or image — from `seedance:Video`, `media:Image`, etc. |
+| `during` | yes | Selection reference — when this item appears |
+| `appearance` | yes | SVS broll Recipe — position, size, fit, animations |
+
+The `during` attribute takes a Selection reference like `{story.selection.product-demo}`. The B-roll
+item appears on screen for exactly the duration of that Selection, as resolved through the
+SemanticMap.
+
+The appearance Recipe controls enter/exit animations:
+
+```svs
+broll.product {
+ stack-order: 40;
+ x: 0.08; y: 0.20; width: 0.84; height: 0.48;
+ fit: contain;
+ background: #111116;
+ radius: 28;
+ enter: slide-up 8f;
+ exit: fade 6f;
+}
+```
+
+**Output:** `{product-broll.visual}` — a VisualTrack added to `film:Film`.
+
+### B-roll example
+
+B-roll with a generated Seedance video appearing during a Script Selection:
+
+```svml
+<seedance:Prompt id="product-direction">
+ A clean vertical product film: the written script becomes semantic regions,
+ then those regions assemble into a finished video.
+</seedance:Prompt>
+
+<seedance:Video id="product-motion" model="mini"
+ prompt={product-direction} duration="5">
+ <seedance:Reference image={product-reference} role="subject"/>
+</seedance:Video>
+
+<broll:Track id="product-broll" map={timing.map}>
+ <broll:Item source={product-motion.video}
+ during={story.selection.product-demo}
+ appearance={studio.broll.product}/>
+</broll:Track>
+```
+
+## Text overlays
+
+Static or timed text displayed on screen — titles, callouts, lower thirds.
+
+```svml
+<import as="text" from="@narratage/text-track@1"/>
+```
+
+### text:Track
+
+Container for text items.
+
+```svml
+<text:Track id="titles" space={speech.space}>
+ <text:Item text="EDIT MEANING, NOT TIMELINES" during="full"
+ appearance={studio.text.title}/>
+</text:Track>
+```
+
+| Attribute | Required | Description |
+|---|---|---|
+| `id` | yes | Unique identifier |
+| `space` | yes | ProgramSpace from `speech:Spine` |
+| `map` | no | SemanticMap — needed when items use Selection-based timing |
+
+### text:Item
+
+Each item is a text string placed at a time position:
+
+```svml
+<text:Item text="MEANING" during="full" appearance={studio.text.title}/>
+```
+
+| Attribute | Required | Description |
+|---|---|---|
+| `text` | yes | The text string to display |
+| `during` | yes | When to show: `"full"` (entire program) or a Selection reference |
+| `appearance` | yes | SVS text Recipe — position, font, size, color |
+
+The `during` attribute accepts either the literal string `"full"` for the entire program duration, or
+a Selection reference for semantic timing:
+
+```svml
+<text:Track id="callout" space={speech.space} map={timing.map}>
+ <text:Item text="EXACTLY THE RIGHT MOMENT"
+ during={story.selection.callout}
+ appearance={studio.text.callout}/>
+</text:Track>
+```
+
+**Output:** `{titles.track}` — a VisualTrack added to `film:Film`.
+
+## Combination example
+
+All three track types together in one source file:
+
+```svml
+<import as="caption" from="@narratage/caption@1"/>
+<import as="caption-ai" from="@narratage/caption-gemini@1"/>
+<import as="broll" from="@narratage/broll@1"/>
+<import as="text" from="@narratage/text-track@1"/>
+
+<!-- Captions: primary style for all text -->
+<caption:Style id="base-caption" appearance={studio.caption.base}>
+ <caption:Cues>Prefer short complete semantic phrases.</caption:Cues>
+ <caption:Field id="important" type="boolean" min-per-cue="0" max-per-cue="2">
+ Select zero, one, or two words whose emphasis best communicates this Cue.
+ </caption:Field>
+</caption:Style>
+<caption:Program id="caption-program" narrative={story} default={base-caption}/>
+<caption-ai:Planner id="cue-plan" narrative={story}
+ program={caption-program} model="gemini-2.5-flash"/>
+<caption:Track id="captions" narrative={story} map={timing.map}
+ space={speech.space} plan={cue-plan.plan} program={caption-program}/>
+
+<!-- B-roll: generated video during a Selection -->
+<broll:Track id="cards" map={timing.map} space={speech.space}>
+ <broll:Item source={motion.video} during={story.selection.demo}
+ appearance={studio.broll.card}/>
+</broll:Track>
+
+<!-- Text: persistent title overlay -->
+<text:Track id="titles" space={speech.space}>
+ <text:Item text="MEANING" during="full" appearance={studio.text.title}/>
+</text:Track>
+
+<!-- All three tracks feed into Film -->
+<film:Film id="main" space={speech.space} appearance={studio.film.vertical}>
+ <film:Track source={speech.visual}/>
+ <film:Track source={speech.audioTrack}/>
+ <film:Track source={cards.visual}/>
+ <film:Track source={captions.track}/>
+ <film:Track source={titles.track}/>
+</film:Film>
+```
+
+The `stack-order` in each SVS Recipe determines z-ordering: speech visual at 10, B-roll at 40,
+captions at 70, text at 90. Higher values render on top.
diff --git a/docs/zh/quickstart.md b/docs/zh/quickstart.md
index 76dec191..adaf6451 100644
--- a/docs/zh/quickstart.md
+++ b/docs/zh/quickstart.md
@@ -35,17 +35,15 @@ pnpm test
Author Source 说明*做什么*。Run Source 说明*要哪些*。Runtime Profile 说明*在哪里做*。
-## 检查一张视频图(免费)
+## 第一次图检查
`talking-film-graph-check` 示例会编译一张完整的视频图 —— Script、Seedance、Speech、
WhisperX、Gemini Caption、B-roll、Text、Film、HyperFrames —— 全程不调用任何外部服务。
```bash
-# 编译 Author Source。
pnpm narratage check examples/talking-film-graph-check/main.svml \
--package-lock examples/talking-film-graph-check/svml.packages.lock --root .
-# 编译 Run Source 并查看冻结后的 plan。
pnpm narratage plan examples/talking-film-graph-check/build.svrun \
--package-lock examples/talking-film-graph-check/svml.packages.lock --root .
```
@@ -53,84 +51,17 @@ pnpm narratage plan examples/talking-film-graph-check/build.svrun \
`check` 产出带类型的 Author Graph。`plan` 绑定 Author Graph 与 Run Graph,解析 Targets,
并输出冻结的 BuildPlan —— 其中包含 Scheduler 将会发出的每一个 Operation 与 Needs。花钱之前先检查它。
-## 跑一次真实的 Build(付费)
-
-`echo-pro-aroll` 示例是一部由四条 take 构成的 Seedance Mini 口播人像影片。
-
-前置条件:
-
-- 环境变量中配置 `KIE_API_KEY`、`GOOGLE_CLOUD_PROJECT`、`GOOGLE_APPLICATION_CREDENTIALS_JSON`
-- `ffmpeg`、`ffprobe`、Chrome
-- 本地 WhisperX 服务正在运行(参见 `services/whisperx/README.md`)
-- `examples/echo-pro-aroll/assets/` 下的本地素材(未纳入版本库)
-
-```bash
-# 诊断 Runtime 环境。
-pnpm narratage doctor examples/echo-pro-aroll/svml.runtime.json
-
-# 提交 Build。
-pnpm narratage build examples/echo-pro-aroll/build.svrun \
- --runtime examples/echo-pro-aroll/svml.runtime.json \
- --package-lock examples/echo-pro-aroll/svml.packages.lock \
- --root . \
- --build-id echo-pro-film-001 \
- --follow
-
-# 取回最终视频。
-pnpm narratage get echo-pro-film-001 \
- --runtime examples/echo-pro-aroll/svml.runtime.json \
- --name final.video \
- --to examples/echo-pro-aroll/output/final.mp4
-```
-
-每一个被接受的中间 Record 与 Artifact 都会在 Build 完成之前归档。`get` 只是对一个已经持久化的
-Record 做一次可选的复制。
-
-## 复用既有结果
-
-SVML 没有隐式缓存。复用结果是显式的 Run Graph 编写工作 —— 声明由历史 Records 支撑的零输入
-Candidates,再用 Satisfaction edges 把它们接起来:
-
-```xml
-<?svml using="@narratage/run-text@1"?>
-<svrun version="1" targets="delivery">
- <author source="./main.svml"/>
- <target-set id="delivery">
- <target output="final.video" accepts="substitute"/>
- </target-set>
-
- <build-record id="hook-video"
- build="echo-pro-film-001" output="hook-take.video"/>
- <satisfy output="hook-take.video"
- candidate="hook-video" fidelity="substitute"/>
-</svrun>
-```
-
-编译出的 plan 会剪掉所有被 substitute Candidates 取代的上游 Operations。这是一次新的 Build,
-而不是对上一次的续跑。
-
-```bash
-pnpm narratage build examples/echo-pro-aroll/reuse-generated.svrun \
- --runtime examples/echo-pro-aroll/svml.runtime.json \
- --package-lock examples/echo-pro-aroll/svml.packages.lock \
- --root . --build-id echo-pro-film-reuse-001 --follow
-```
-
-## CLI 参考
-
-```text
-narratage lock-packages <lock> --package name [--package name ...] [--root dir]
-narratage doctor <runtime.json>
-narratage gc <runtime.json> [--apply]
-narratage check <source> [--package-lock file] [--root dir]
-narratage plan <run-source> [--package-lock file] [--root dir]
-narratage build <run-source> --runtime profile [--build-id id] [--follow]
-narratage status <build-id> --runtime profile
-narratage builds --runtime profile
-narratage inspect <build-id> --runtime profile
-narratage get <build-id> --runtime profile [--name x|--record x|--output x|--artifact x] [--to path]
-narratage cancel <build-id> --runtime profile
-```
+## 指南目录
+
+| 指南 | 主题 |
+|---|---|
+| [Script](./quickstart/script.md) | Segment、Role Cue、Dual Text、Selection、Moment、文字投影 |
+| [SVS 样式表](./quickstart/styles.md) | CSS 风格的 Recipe:film、caption、B-roll、text、speech、字体 |
+| [媒体与生成](./quickstart/generation.md) | media:Image、media:Audio、estimate:Speech、Seedance、speaker:Take |
+| [时序与装配](./quickstart/timing.md) | speech:Spine、whisperx:Alignment、ProgramSpace、SemanticMap |
+| [字幕、B-roll 与文字](./quickstart/tracks.md) | caption:Style/Program/Planner/Track、broll:Track、text:Track |
+| [Film 与渲染](./quickstart/composition.md) | film:Film、render:Video、完整流水线演练 |
+| [Run Source 与 Build](./quickstart/run.md) | .svrun 语法、targets、复用、runtime profile、build 工作流 |
## 下一步
diff --git a/docs/zh/quickstart/composition.md b/docs/zh/quickstart/composition.md
new file mode 100644
index 00000000..1c0e19f4
--- /dev/null
+++ b/docs/zh/quickstart/composition.md
@@ -0,0 +1,235 @@
+---
+title: Film 与渲染
+description: 将 Track 组合为 Film 并渲染为视频。
+---
+
+# Film 与渲染
+
+Film 是最终的组装阶段。它接收所有对等的 Track,对其进行验证,并生成一个
+Composition。然后渲染器将该 Composition 编译为 MP4 视频。
+
+```svml
+<import as="film" from="@narratage/film@1"/>
+<import as="render" from="@narratage/render-hyperframes@1"/>
+```
+
+## film:Film
+
+将所有 Track 组装为单一的 Composition。Film 本身没有领域知识——它不知道什么是字幕、
+什么是 B-roll、什么是语音。它接收任何 VisualTrack 或 AudioTrack,并按堆叠顺序将它们分层。
+
+```svml
+<film:Film id="main" space={speech.space} appearance={studio.film.vertical}>
+ <film:Track source={speech.visual}/>
+ <film:Track source={speech.audioTrack}/>
+ <film:Track source={captions.track}/>
+ <film:Track source={product-broll.visual}/>
+ <film:Track source={titles.track}/>
+</film:Film>
+```
+
+| 属性 | 必填 | 说明 |
+|---|---|---|
+| `id` | 是 | 唯一标识符 |
+| `space` | 是 | 来自 `speech:Spine` 的 ProgramSpace——定义时长和帧率 |
+| `appearance` | 是 | SVS Film Recipe——画布宽度、高度、帧率、背景 |
+
+### film:Track
+
+每个 `<film:Track>` 子元素向 Composition 添加一个 Track 来源:
+
+| 属性 | 必填 | 说明 |
+|---|---|---|
+| `source` | 是 | 来自任何上游组件的 VisualTrack 或 AudioTrack |
+
+常见的 Track 来源:
+
+| 来源 | 类型 | 来自 |
+|---|---|---|
+| `{speech.visual}` | VisualTrack | `speech:Spine`——全屏说话人画面 |
+| `{speech.audioTrack}` | AudioTrack | `speech:Spine`——同步音频 |
+| `{captions.track}` | VisualTrack | `caption:Track`——定时字幕 |
+| `{cards.visual}` | VisualTrack | `broll:Track`——B-roll 叠加层 |
+| `{titles.track}` | VisualTrack | `text:Track`——文字叠加层 |
+
+### Track 堆叠
+
+Track 是**扁平的**——没有嵌套或分组。Z 轴排序完全由每个 Track 的 SVS Recipe 中的
+`stack-order` 属性决定。较低的值在后面;较高的值渲染在上面。
+
+典型的堆叠顺序:
+
+| stack-order | 内容 |
+|---|---|
+| 10 | 语音画面(全屏说话人画面) |
+| 40 | B-roll 叠加层 |
+| 70 | 字幕 |
+| 90 | 文字叠加层 |
+
+一个组件可以在不同的 z 位置发出多个视觉元素(Presents),这些元素会与其他组件的 Presents
+交错排列。最终渲染会将所有 Presents 展平,按绝对堆叠键排序,然后绘制到一个画布上。
+
+**输出:** `{main.composition}`——完整的 Composition,传递给渲染器。
+
+## render:Video
+
+通过 HyperFrames 渲染器将 Composition 编译为最终视频。
+
+```svml
+<render:Video id="final" composition={main.composition} space={speech.space}/>
+```
+
+| 属性 | 必填 | 说明 |
+|---|---|---|
+| `id` | 是 | 唯一标识符 |
+| `composition` | 是 | 来自 `film:Film` 的 Composition |
+| `space` | 是 | 来自 `speech:Spine` 的 ProgramSpace |
+
+渲染器:
+
+1. 将 Composition 编译为 `HyperframesDocument`——每一帧的 HTML 表示
+2. 通过 Chrome/Chromium 渲染每一帧
+3. 将帧序列编码为视频
+4. 混合音频 Track
+5. 将视频和音频混合封装为最终的 MP4
+
+**输出:** `{final.video}`——最终的视频文件。这是最常见的 Build Target。
+
+## 完整的管线流程
+
+从 Script 到渲染视频的完整数据流。本示例基于
+`examples/talking-film-graph-check/`——最小的完整图。
+
+### Author Source (`main.svml`)
+
+```svml
+<?svml using="@narratage/text@1"?>
+
+<svml>
+ <import from="@narratage/script@1"/>
+ <import as="seedance" from="@narratage/seedance@1"/>
+ <import as="speech" from="@narratage/speech-spine@1"/>
+ <import as="whisperx" from="@narratage/whisperx@1"/>
+ <import as="caption" from="@narratage/caption@1"/>
+ <import as="caption-ai" from="@narratage/caption-gemini@1"/>
+ <import as="broll" from="@narratage/broll@1"/>
+ <import as="text" from="@narratage/text-track@1"/>
+ <import as="film" from="@narratage/film@1"/>
+ <import as="render" from="@narratage/render-hyperframes@1"/>
+ <import as="studio" source="./studio.svs"/>
+
+ <!-- 1. Script: the semantic truth -->
+ <script id="story">
+ <opening><HOST>Meaning @demo becomes the source @/demo.</opening>
+ </script>
+
+ <!-- 2. Generation: Seedance talking head + standalone video -->
+ <seedance:Prompt id="direction">
+ Locked medium close-up in a quiet daylight studio.
+ </seedance:Prompt>
+ <seedance:Speech id="take" model="mini"
+ dialogue={story.segment.opening.dialogue}
+ prompt={direction} duration="5"/>
+ <seedance:Video id="motion" model="mini"
+ prompt={direction} duration="5"/>
+
+ <!-- 3. Timing: assemble spine and align words -->
+ <speech:Spine id="speech">
+ <speech:Take source={take} segment={story.segment.opening}/>
+ </speech:Spine>
+ <whisperx:Alignment id="timing" narrative={story} audio={speech.audio}/>
+
+ <!-- 4. Tracks: captions, B-roll, text -->
+ <caption:Style id="base-caption" appearance={studio.caption.base}>
+ <caption:Cues>Prefer short complete semantic phrases.</caption:Cues>
+ <caption:Field id="important" type="boolean"
+ min-per-cue="0" max-per-cue="2">
+ Select zero, one, or two words whose emphasis best communicates
+ this Cue.
+ </caption:Field>
+ </caption:Style>
+ <caption:Program id="caption-program" narrative={story}
+ default={base-caption}/>
+ <caption-ai:Planner id="cue-plan" narrative={story}
+ program={caption-program} model="gemini-2.5-flash"/>
+ <caption:Track id="captions" narrative={story} map={timing.map}
+ space={speech.space} plan={cue-plan.plan} program={caption-program}/>
+
+ <broll:Track id="cards" map={timing.map} space={speech.space}>
+ <broll:Item source={motion.video} during={story.selection.demo}
+ appearance={studio.broll.card}/>
+ </broll:Track>
+
+ <text:Track id="titles" space={speech.space}>
+ <text:Item text="MEANING" during="full"
+ appearance={studio.text.title}/>
+ </text:Track>
+
+ <!-- 5. Film: compose all tracks -->
+ <film:Film id="main" space={speech.space}
+ appearance={studio.film.vertical}>
+ <film:Track source={speech.visual}/>
+ <film:Track source={speech.audioTrack}/>
+ <film:Track source={cards.visual}/>
+ <film:Track source={captions.track}/>
+ <film:Track source={titles.track}/>
+ </film:Film>
+
+ <!-- 6. Render: compile to MP4 -->
+ <render:Video id="final" composition={main.composition}
+ space={speech.space}/>
+</svml>
+```
+
+### 样式表 (`studio.svs`)
+
+```svs
+<?svml using="@narratage/svs@1"?>
+
+<sheet version="1">
+ film.vertical {
+ width: 1080; height: 1920; frame-rate: 30; background: #09090B;
+ }
+ broll.card {
+ stack-order: 40; x: 0.1; y: 0.2; width: 0.8; height: 0.5;
+ fit: cover; background: #111116; radius: 20;
+ enter: slide-up 4f; exit: fade 4f;
+ }
+ caption.base {
+ stack-order: 70; x: 0.08; y: 0.76; width: 0.84;
+ font: Inter; weight: 600; size: 58; line-height: 1; align: center;
+ fill: #FFFFFF; background: #09090BCC; padding: 16 24; radius: 18;
+ }
+ text.title {
+ stack-order: 90; x: 0.06; y: 0.06; width: 0.88; height: 0.1;
+ font: Inter; weight: 900; size: 64; align: center;
+ fill: #FFFFFF; tracking: -1;
+ }
+</sheet>
+```
+
+### Run Source (`build.svrun`)
+
+```svml
+<?svml using="@narratage/run-text@1"?>
+
+<svrun version="1" targets="delivery">
+ <author source="./main.svml"/>
+ <target-set id="delivery">
+ <target output="final.video" accepts="exact"/>
+ </target-set>
+</svrun>
+```
+
+### 编译与验证
+
+```bash
+pnpm narratage check examples/talking-film-graph-check/main.svml \
+ --package-lock examples/talking-film-graph-check/svml.packages.lock --root .
+
+pnpm narratage plan examples/talking-film-graph-check/build.svrun \
+ --package-lock examples/talking-film-graph-check/svml.packages.lock --root .
+```
+
+`check` 编译 Author Graph——验证所有导入、类型和图的边,而不调用任何外部服务。`plan`
+还会额外编译 Run Source 并输出冻结的 BuildPlan,展示调度器将发出的每个 Operation。在花费资金之前请先检查计划。
diff --git a/docs/zh/quickstart/generation.md b/docs/zh/quickstart/generation.md
new file mode 100644
index 00000000..a091b3ed
--- /dev/null
+++ b/docs/zh/quickstart/generation.md
@@ -0,0 +1,273 @@
+---
+title: 媒体与生成
+description: 声明媒体资源并使用 Seedance 生成视频。
+---
+
+# 媒体与生成
+
+本页介绍用于声明静态资源和生成新媒体的组件——这些是流入下游时序和 Track 阶段的原始素材。
+
+此处展示的每个组件在使用前都必须通过包标识符导入:
+
+```svml
+<import as="media" from="@narratage/media@1"/>
+<import as="estimate" from="@narratage/estimate@1"/>
+<import as="seedance" from="@narratage/seedance@1"/>
+<import as="speaker" from="@narratage/seedance-speaker@1"/>
+```
+
+## media:Image
+
+声明一个来自本地文件的内容寻址图片资源。
+
+```svml
+<media:Image id="presenter" src="./assets/presenter.png"/>
+```
+
+| 属性 | 必填 | 说明 |
+|---|---|---|
+| `id` | 是 | 组件的唯一标识符 |
+| `src` | 是 | 图片文件路径,相对于 `.svml` 源文件 |
+
+该图片在下游通过 `{presenter}` 引用——例如,作为 `seedance:Speech` 中的角色参考或作为 B-roll 来源。
+
+## media:Audio
+
+声明一个来自本地文件的内容寻址音频资源。
+
+```svml
+<media:Audio id="presenter-voice" src="./assets/presenter-voice.mp3"/>
+```
+
+| 属性 | 必填 | 说明 |
+|---|---|---|
+| `id` | 是 | 唯一标识符 |
+| `src` | 是 | 音频文件路径,相对于 `.svml` 源文件 |
+
+通常用作 `speaker:Take` 的语音音色参考。
+
+## estimate:Speech
+
+基于 Script 文本的确定性语音时长估算。无需外部服务调用——估算根据字数和语速参数在本地计算。
+
+```svml
+<estimate:Speech id="hook-duration"
+ source={story.segment.hook.speech}
+ policy={studio.speech.normal}/>
+```
+
+| 属性 | 必填 | 说明 |
+|---|---|---|
+| `id` | 是 | 唯一标识符 |
+| `source` | 是 | 要估算的 Script 文本——通常为 `{script.segment.NAME.speech}` |
+| `policy` | 是 | 控制语速和边界的 SVS 语音 Recipe |
+
+`policy` 引用一个 SVS Recipe(参见 [SVS 样式表](./styles.md#speech-estimation)):
+
+```svs
+speech.normal {
+ language: en;
+ pace: normal;
+ padding: 0.3;
+ min: 4;
+ max: 15;
+ rounding: ceil;
+}
+```
+
+你也可以直接内联指定估算参数,而不使用 SVS policy:
+
+```svml
+<estimate:Speech id="opening-duration"
+ source={story.segment.opening.speech}
+ language="en" pace="normal" padding="0.3" min="4" max="15" rounding="ceil"/>
+```
+
+**输出:** `{hook-duration.duration}`——估算的时长(秒),传递给生成组件。
+
+## seedance:Prompt
+
+一个可复用的文本块,为 Seedance 生成提供视觉指导。
+
+```svml
+<seedance:Prompt id="alice-direction">
+ Locked medium close-up. Alice speaks directly to camera in a quiet daylight studio.
+ Calm, curious delivery; natural breathing and restrained hand movement.
+</seedance:Prompt>
+```
+
+| 属性 | 必填 | 说明 |
+|---|---|---|
+| `id` | 是 | 唯一标识符 |
+
+元素主体即为提示文本。通过 `seedance:Speech` 和 `seedance:Video` 的 `prompt` 属性引用。
+
+## seedance:Speech
+
+通过 Seedance 模型生成说话人头部视频片段。这是低层级的生成组件——直接指定对话、提示和时长。
+
+```svml
+<seedance:Speech id="alice-take" model="mini"
+ dialogue={story.segment.opening.dialogue}
+ prompt={alice-direction}
+ duration="8">
+ <seedance:Reference image={alice-reference} role="character"/>
+</seedance:Speech>
+```
+
+| 属性 | 必填 | 说明 |
+|---|---|---|
+| `id` | 是 | 唯一标识符 |
+| `model` | 是 | Seedance 模型名称:`mini` |
+| `dialogue` | 是 | 要进行口型同步的 Script 文本——通常为 `{script.segment.NAME.dialogue}` |
+| `prompt` | 是 | 视觉指导——引用 `seedance:Prompt` |
+| `duration` | 是 | 片段时长(秒)(数字或 `{estimate.duration}` 引用) |
+| `resolution` | 否 | 输出分辨率:`480p`、`720p`(默认值因模型而异) |
+| `aspect-ratio` | 否 | 输出宽高比:`9:16`、`16:9`、`1:1` |
+
+### seedance:Reference
+
+提供参考图片以保持角色一致性的子元素:
+
+```svml
+<seedance:Reference image={alice-reference} role="character"/>
+```
+
+| 属性 | 必填 | 说明 |
+|---|---|---|
+| `image` | 是 | 引用 `media:Image` 组件 |
+| `role` | 是 | 该参考的用途:`character`、`subject` |
+
+**输出:** `{alice-take}` 或 `{alice-take.video}`——生成的视频,传递给 `speech:Spine`。
+
+## seedance:Video
+
+生成独立的视频片段(非说话人头部——无对话口型同步)。
+
+```svml
+<seedance:Video id="product-motion" model="mini"
+ prompt={product-direction} duration="5">
+ <seedance:Reference image={product-reference} role="subject"/>
+</seedance:Video>
+```
+
+| 属性 | 必填 | 说明 |
+|---|---|---|
+| `id` | 是 | 唯一标识符 |
+| `model` | 是 | Seedance 模型名称:`mini` |
+| `prompt` | 是 | 视觉指导——引用 `seedance:Prompt` |
+| `duration` | 是 | 片段时长(秒) |
+
+同样接受 `<seedance:Reference>` 子元素作为参考图片。
+
+**输出:** `{product-motion.video}`——用作 B-roll 来源。
+
+## speaker:Take
+
+基于 Prompt Kit 构建的更高层级说话人头部组件。无需编写原始提示,你只需提供一个包含生成设置的 Recipe 和一个自动组装提示的 Kit。
+
+```svml
+<import as="speaker" from="@narratage/seedance-speaker@1"/>
+<import as="ugc" source="../../packages/seedance-speaker/kits/official-ugc-v1.svs"/>
+
+<speaker:Take id="hook-take"
+ dialogue={story.segment.hook.dialogue}
+ duration={hook-duration.duration}
+ recipe={studio.speaker.echo-pro}
+ kit={ugc.official-ugc-v1}>
+ <speaker:Reference image={presenter-clean} role="character-and-scene"/>
+ <speaker:Reference audio={presenter-voice} role="voice-timbre"/>
+</speaker:Take>
+```
+
+| 属性 | 必填 | 说明 |
+|---|---|---|
+| `id` | 是 | 唯一标识符 |
+| `dialogue` | 是 | Script 文本——通常为 `{script.segment.NAME.dialogue}` |
+| `duration` | 是 | 来自 `estimate:Speech` 的估算时长 |
+| `recipe` | 是 | SVS speaker Recipe(参见 [SVS 样式表](./styles.md#speaker)) |
+| `kit` | 是 | Prompt Kit SVS——用于组装提示的模板 |
+
+### speaker:Reference
+
+提供参考媒体的子元素。同时接受图片和音频:
+
+```svml
+<speaker:Reference image={presenter-clean} role="character-and-scene"/>
+<speaker:Reference audio={presenter-voice} role="voice-timbre"/>
+```
+
+| 属性 | 必填 | 说明 |
+|---|---|---|
+| `image` | image/audio 二选一 | 引用 `media:Image` |
+| `audio` | image/audio 二选一 | 引用 `media:Audio` |
+| `role` | 是 | 参考用途:`character-and-scene`、`voice-timbre` |
+
+**输出:** `{hook-take.video}`——生成的视频,传递给 `speech:Spine`。
+
+### Prompt Kits
+
+Prompt Kit 是一种特殊的 SVS 文件,定义了包含有序块、变体选择、轴参数和 Slot 的结构化提示模板。官方 Kit 位于 `packages/seedance-speaker/kits/official-ugc-v1.svs`。
+
+该 Kit 使用 Prompt Kit SVS 解析器导入:
+
+```svs
+<?svml using="@narratage/prompt-kit/svs@1"?>
+```
+
+`studio.svs` 中的 Recipe 设置轴参数值(composition-stability、camera-motion、edit-rhythm、performance、gesture、voice-mode),Kit 会自动将它们组装成完整的提示。
+
+## 组合示例
+
+一个四段拍摄的设置,估算时长作为输入传递给 `speaker:Take` 生成:
+
+```svml
+<import as="media" from="@narratage/media@1"/>
+<import as="estimate" from="@narratage/estimate@1"/>
+<import as="speaker" from="@narratage/seedance-speaker@1"/>
+<import as="studio" source="./studio.svs"/>
+<import as="ugc" source="../../packages/seedance-speaker/kits/official-ugc-v1.svs"/>
+
+<media:Image id="presenter-clean" src="./assets/presenter-clean.png"/>
+<media:Image id="presenter-with-echo" src="./assets/presenter-with-echo.png"/>
+<media:Audio id="presenter-voice" src="./assets/presenter-voice.mp3"/>
+
+<estimate:Speech id="hook-duration"
+ source={story.segment.hook.speech} policy={studio.speech.normal}/>
+<estimate:Speech id="meeting-duration"
+ source={story.segment.meeting.speech} policy={studio.speech.normal}/>
+<estimate:Speech id="evidence-duration"
+ source={story.segment.evidence.speech} policy={studio.speech.normal}/>
+<estimate:Speech id="payoff-duration"
+ source={story.segment.payoff.speech} policy={studio.speech.normal}/>
+
+<speaker:Take id="hook-take" dialogue={story.segment.hook.dialogue}
+ duration={hook-duration.duration} recipe={studio.speaker.echo-pro}
+ kit={ugc.official-ugc-v1}>
+ <speaker:Reference image={presenter-clean} role="character-and-scene"/>
+ <speaker:Reference audio={presenter-voice} role="voice-timbre"/>
+</speaker:Take>
+
+<speaker:Take id="meeting-take" dialogue={story.segment.meeting.dialogue}
+ duration={meeting-duration.duration} recipe={studio.speaker.echo-pro}
+ kit={ugc.official-ugc-v1}>
+ <speaker:Reference image={presenter-with-echo} role="character-and-scene"/>
+ <speaker:Reference audio={presenter-voice} role="voice-timbre"/>
+</speaker:Take>
+
+<speaker:Take id="evidence-take" dialogue={story.segment.evidence.dialogue}
+ duration={evidence-duration.duration} recipe={studio.speaker.echo-pro}
+ kit={ugc.official-ugc-v1}>
+ <speaker:Reference image={presenter-with-echo} role="character-and-scene"/>
+ <speaker:Reference audio={presenter-voice} role="voice-timbre"/>
+</speaker:Take>
+
+<speaker:Take id="payoff-take" dialogue={story.segment.payoff.dialogue}
+ duration={payoff-duration.duration} recipe={studio.speaker.echo-pro}
+ kit={ugc.official-ugc-v1}>
+ <speaker:Reference image={presenter-clean} role="character-and-scene"/>
+ <speaker:Reference audio={presenter-voice} role="voice-timbre"/>
+</speaker:Take>
+```
+
+每个 `speaker:Take` 生成一个 `{*.video}` 输出,传递给下一阶段的 `speech:Spine`。不同的拍摄段可以使用不同的参考图片(例如,演示者在某些 Segment 中持有产品而在其他段中没有),同时共享相同的语音音色和生成 Recipe。
diff --git a/docs/zh/quickstart/run.md b/docs/zh/quickstart/run.md
new file mode 100644
index 00000000..c28b422f
--- /dev/null
+++ b/docs/zh/quickstart/run.md
@@ -0,0 +1,292 @@
+---
+title: Run Source 与 Build
+description: 声明 Build 目标、复用结果以及配置运行时环境。
+---
+
+# Run Source 与 Build
+
+Run Source(`.svrun`)声明**要构建什么**——需要哪些输出、接受什么保真度,以及可选地如何复用先前 Build 的结果。Runtime Profile(`svml.runtime.json`)声明**在哪里运行**——endpoint、凭证、并发数和权限。
+
+这两者都不会改变视频**是什么**。那是 Author Source 的职责。
+
+## Run Source 语法
+
+每个 `.svrun` 文件都以其处理指令开头:
+
+```svml
+<?svml using="@narratage/run-text@1"?>
+```
+
+### 最简 Run Source
+
+```svml
+<?svml using="@narratage/run-text@1"?>
+
+<svrun version="1" targets="delivery">
+ <author source="./main.svml"/>
+ <target-set id="delivery">
+ <target output="final.video" accepts="exact"/>
+ </target-set>
+</svrun>
+```
+
+| 元素 | 说明 |
+|---|---|
+| `<svrun>` | 根元素。`version="1"`,`targets` 指定活跃的 target-set |
+| `<author>` | 必需。`source` 指向 `.svml` Author Source |
+| `<target-set>` | 一组命名的需求输出集合 |
+| `<target>` | 单个需求输出:`output` 指定逻辑输出名,`accepts` 设置保真度 |
+
+### Target
+
+**Target** 指定 Build 所需的输出及其可接受的最低保真度:
+
+- `accepts="exact"` ——输出必须与作者声明的完全一致
+- `accepts="substitute"` ——允许使用可接受的替代品(例如先前生成的结果)
+
+不存在特权化的"最终视频"根节点。任何组件的任何公开逻辑输出都可以作为 Target。编译器仅执行满足所需 Target 所必要的 Operation——其余一切均被裁剪。
+
+### 多个 Target
+
+可以在一次 Build 中请求多个输出:
+
+```svml
+<target-set id="delivery">
+ <target output="final.video" accepts="exact"/>
+ <target output="captions.track" accepts="exact"/>
+</target-set>
+```
+
+也可以定义多个 target-set 并在它们之间切换:
+
+```svml
+<svrun version="1" targets="preview">
+ <author source="./main.svml"/>
+
+ <target-set id="preview">
+ <target output="captions.track" accepts="substitute"/>
+ </target-set>
+
+ <target-set id="delivery">
+ <target output="final.video" accepts="exact"/>
+ </target-set>
+</svrun>
+```
+
+`<svrun>` 上的 `targets` 属性选择当前活跃的集合。
+
+## 复用结果
+
+Narratage 没有隐式缓存。复用结果是显式的运行图编写——你将历史 Record 声明为零输入 Candidate,并通过 Satisfaction 边将它们连接起来。
+
+```svml
+<?svml using="@narratage/run-text@1"?>
+
+<svrun version="1" targets="delivery">
+ <author source="./main.svml"/>
+ <target-set id="delivery">
+ <target output="final.video" accepts="substitute"/>
+ </target-set>
+
+ <build-record id="hook-video"
+ build="echo-pro-film-001" output="hook-take.video"/>
+ <build-record id="meeting-video"
+ build="echo-pro-film-001" output="meeting-take.video"/>
+ <build-record id="evidence-video"
+ build="echo-pro-film-001" output="evidence-take.video"/>
+ <build-record id="payoff-video"
+ build="echo-pro-film-001" output="payoff-take.video"/>
+
+ <satisfy output="hook-take.video"
+ candidate="hook-video" fidelity="substitute"/>
+ <satisfy output="meeting-take.video"
+ candidate="meeting-video" fidelity="substitute"/>
+ <satisfy output="evidence-take.video"
+ candidate="evidence-video" fidelity="substitute"/>
+ <satisfy output="payoff-take.video"
+ candidate="payoff-video" fidelity="substitute"/>
+</svrun>
+```
+
+### build-record
+
+声明一个由先前 Build 的历史 Record 支持的零输入 Candidate:
+
+| 属性 | 说明 |
+|---|---|
+| `id` | 此 Run Source 内的本地 Candidate 标识符 |
+| `build` | 先前 Build 的 build-id |
+| `output` | 该 Build 中的逻辑输出名 |
+
+### satisfy
+
+将 Candidate 连接到逻辑输出:
+
+| 属性 | 说明 |
+|---|---|
+| `output` | 要满足的逻辑输出 |
+| `candidate` | Candidate 标识符(来自 `build-record`) |
+| `fidelity` | `exact` 或 `substitute` |
+
+编译后的计划会裁剪所有被替代 Candidate 取代的上游 Operation。这是一次新的 Build,而非旧 Build 的延续。下游处理(归一化、WhisperX、字幕生成、渲染)仍然会对复用的媒体执行。
+
+### 保真度模型
+
+- **`exact`** ——Candidate 与作者声明的内容精确匹配
+- **`substitute`** ——Candidate 是一个可接受的替代品
+
+替代保真度是**单调的**:一旦替代品进入图中,它会向下游传播。你无法将其恢复为 exact。如果最终 Target 接受 `substitute`,那么消费替代输入的下游 Operation 也会产生替代结果。
+
+## Runtime Profile
+
+Runtime Profile(`svml.runtime.json`)告诉系统**在哪里**执行每种类型的工作:
+
+```json
+{
+ "format": "svml.runtime-config@1",
+ "packageLock": "./svml.packages.lock",
+ "runtimePackageLock": "./svml.runtime-packages.lock",
+ "endpoints": [
+ {
+ "use": "@narratage/provider-kie",
+ "instance": "kie.main",
+ "lane": "generation",
+ "config": {
+ "apiKeyEnv": "KIE_API_KEY",
+ "defaultConcurrency": 2
+ }
+ },
+ {
+ "use": "@narratage/provider-media-local",
+ "instance": "media.main",
+ "lane": "media",
+ "config": { "defaultConcurrency": 2 }
+ },
+ {
+ "use": "@narratage/provider-whisperx-local",
+ "instance": "whisperx.main",
+ "lane": "alignment",
+ "config": { "defaultConcurrency": 1 }
+ },
+ {
+ "use": "@narratage/provider-google-vertex",
+ "instance": "vertex.main",
+ "lane": "planning",
+ "config": {
+ "projectEnv": "GOOGLE_CLOUD_PROJECT",
+ "credentialsEnv": "GOOGLE_APPLICATION_CREDENTIALS_JSON",
+ "location": "global",
+ "defaultConcurrency": 1
+ }
+ },
+ {
+ "use": "@narratage/provider-hyperframes-local",
+ "instance": "hyperframes.main",
+ "lane": "render",
+ "config": {
+ "workers": 2,
+ "quality": "standard",
+ "defaultConcurrency": 1
+ }
+ }
+ ],
+ "permissions": [
+ "filesystem:whisperx-staging",
+ "network:aiplatform.googleapis.com",
+ "network:api.kie.ai",
+ "network:kieai.redpandaai.co",
+ "network:whisperx-loopback",
+ "process:hyperframes",
+ "process:media"
+ ],
+ "scheduling": {
+ "maxConcurrency": 4,
+ "lanes": {
+ "generation": 2,
+ "media": 2,
+ "alignment": 1,
+ "planning": 1,
+ "render": 1
+ }
+ }
+}
+```
+
+### Endpoint
+
+每个 endpoint 将一个 Provider 包绑定到具有并发通道的命名实例:
+
+| 字段 | 说明 |
+|---|---|
+| `use` | Provider 包名(例如 `@narratage/provider-kie`) |
+| `instance` | 唯一的实例标识符 |
+| `lane` | 用于并发控制的调度通道 |
+| `config` | Provider 专属配置(API 密钥、并发数等) |
+
+### 权限
+
+对文件系统、网络和进程访问的显式授权。调度器会拒绝需要未在此列出的权限的 Operation。
+
+### 调度
+
+`maxConcurrency` 限制总的并行 Operation 数。`lanes` 设置每个通道的并发上限,以防止某一类工作饿死其他工作。
+
+## Build 工作流
+
+### 1. 诊断环境
+
+```bash
+pnpm narratage doctor examples/echo-pro-aroll/svml.runtime.json
+```
+
+Doctor 检查每个 endpoint 是否可达、凭证是否有效,以及所需的可执行文件(`ffmpeg`、`ffprobe`、Chrome)是否可用。
+
+### 2. 检查计划
+
+```bash
+pnpm narratage plan examples/echo-pro-aroll/build.svrun \
+ --package-lock examples/echo-pro-aroll/svml.packages.lock --root .
+```
+
+在花费资金之前审查冻结的 BuildPlan。该计划展示调度器将发出的每个 Operation 和 Needs。
+
+### 3. 提交 Build
+
+```bash
+pnpm narratage build examples/echo-pro-aroll/build.svrun \
+ --runtime examples/echo-pro-aroll/svml.runtime.json \
+ --package-lock examples/echo-pro-aroll/svml.packages.lock \
+ --root . \
+ --build-id echo-pro-film-001 \
+ --follow
+```
+
+| 标志 | 说明 |
+|---|---|
+| `--runtime` | Runtime Profile 的路径 |
+| `--package-lock` | 包锁定文件的路径 |
+| `--root` | 工作区根目录 |
+| `--build-id` | 用户为此 Build 选择的标识符(用于检索和复用) |
+| `--follow` | 将 Build 进度流式输出到终端 |
+
+### 4. 获取结果
+
+```bash
+pnpm narratage get echo-pro-film-001 \
+ --runtime examples/echo-pro-aroll/svml.runtime.json \
+ --name final.video \
+ --to examples/echo-pro-aroll/output/final.mp4
+```
+
+每个被接受的中间 Record 和 Artifact 在 Build 完成前都会被归档。`get` 会复制一份已持久化的 Record。
+
+### 5. 在新 Build 中复用
+
+创建一个引用已完成 Build 的 Record 的新 `.svrun` 文件(参见上文[复用结果](#复用结果)),然后提交:
+
+```bash
+pnpm narratage build examples/echo-pro-aroll/reuse-generated.svrun \
+ --runtime examples/echo-pro-aroll/svml.runtime.json \
+ --package-lock examples/echo-pro-aroll/svml.packages.lock \
+ --root . --build-id echo-pro-film-reuse-001 --follow
+```
diff --git a/docs/zh/quickstart/script.md b/docs/zh/quickstart/script.md
new file mode 100644
index 00000000..11e568e2
--- /dev/null
+++ b/docs/zh/quickstart/script.md
@@ -0,0 +1,245 @@
+---
+title: Script
+description: Script Surface——Segment、Role Cue、Dual Text、Selection、Moment 与文本投影。
+---
+
+# Script
+
+`<script>` 元素承载旁白或讲者说出的每一个字。Script 以**散文为先**:它不包含时间码、不引用媒体、不设定样式、不携带生成参数。管线中的其他组件都会读取 Script;Script 本身不读取任何内容。
+
+```svml
+<import from="@narratage/script@1"/>
+
+<script id="story">
+ <opening>
+ <HOST> Hello world.
+ </opening>
+</script>
+```
+
+引入 `@narratage/script@1` 会激活 Script Surface。`id` 属性让其他组件可以引用该 Script 及其各部分。
+
+## Segment
+
+Segment 是按顺序排列的语音内容块。标签名**即**其 id——在同一个 Script 内必须唯一。
+
+```svml
+<script id="story">
+ <opening>
+ Hello world.
+ </opening>
+
+ <pause/>
+
+ <middle>
+ This is the second part.
+ </middle>
+
+ <close>
+ Goodbye.
+ </close>
+</script>
+```
+
+- Segment 可以是自闭合标签(`<pause/>`)。空的 Segment 拥有结构但没有语音词元;它并不意味着静音或任何默认时长。
+- Segment 不能嵌套——每个 Segment 都是 `<script>` 的顶层子元素。
+- Segment 名称遵循 XML 命名规则:字母、数字、连字符、下划线。
+
+其他组件通过 `{story.segment.opening}` 引用单个 Segment,通过 `{story.segment.opening.dialogue}` 或 `{story.segment.opening.speech}` 引用其文本投影。
+
+## Role Cue
+
+Role Cue 标识 Segment 内部**谁说了什么**。它们不是讲者实体,不选择语音,也不创建角色。
+
+```svml
+<dialogue>
+ <ALICE> What time is it?
+ <BOB> It's 8:30.
+</dialogue>
+```
+
+- Role Cue **没有关闭标签**。一段话从当前 Role Cue 开始,延续到下一个 Role Cue 或 Segment 结尾为止。
+- 一个 Segment 必须全部使用或全部不使用 Role Cue——混用会导致错误。
+- 标签长度为 1–32 个字符。
+
+Role Cue 会产生不同的文本投影:
+
+| 投影 | 上例的输出 |
+|---|---|
+| **dialogue** | `ALICE: What time is it?`<br>`BOB: It's 8:30.` |
+| **speech** | `What time is it?`<br>`It's 8:30.` |
+| **caption** | `What time is it?`<br>`It's 8:30.` |
+
+dialogue 投影包含 Role Cue 前缀。speech 和 caption 投影会去除前缀。像 `seedance:Speech` 这样的组件使用 `{story.segment.dialogue.dialogue}`(带标签),而 `caption:Track` 使用 caption 投影(不带标签)。
+
+## Dual Text
+
+当屏幕上显示的文字与实际说出的文字不同时:
+
+```svml
+<explanation>
+ <HOST> We call it <SVML | semantic video markup language>.
+</explanation>
+```
+
+左侧进入 **caption** 投影;右侧进入 **dialogue** 和 **speech** 投影。
+
+| 投影 | 输出 |
+|---|---|
+| **caption** | `We call it SVML.` |
+| **speech** | `We call it semantic video markup language.` |
+
+左侧为空是合法的:
+
+```svml
+<HOST> I was < | um> saying that this works.
+```
+
+这意味着 "um" 会被说出但永远不会显示为字幕。两侧可以有不同的单词数量——这是一种 N:M 文本映射,而非 1:1 替换。
+
+## Selection
+
+Selection 是内联声明的具名时间**范围**:
+
+```svml
+<script id="story">
+ @whole
+ <opening>
+ <HOST> @problem Current tools make agents operate a timeline. @/problem
+ </opening>
+
+ <answer>
+ <HOST> @solution SVML removes that editing loop. @/solution
+ </answer>
+ @/whole~
+</script>
+```
+
+### 语法
+
+| 标记 | 含义 |
+|---|---|
+| `@id` | 打开,右吸附(从下一个单词开始) |
+| `~@id` | 打开,左吸附(从前一个单词的末尾开始) |
+| `@/id` | 关闭,左吸附(在前一个单词的末尾结束) |
+| `@/id~` | 关闭,右吸附(在下一个单词的起始处结束) |
+
+`~` 后缀/前缀控制边界是吸附到左边还是右边。默认的打开标记为右吸附;默认的关闭标记为左吸附。
+
+### 非连续 Selection
+
+同一个 id 可以多次出现,以创建带有间隔的 Selection:
+
+```svml
+<demo>
+ <HOST> @beat First point. @/beat Then something else. @beat Third point. @/beat
+</demo>
+```
+
+`{story.selection.beat}` 现在覆盖两个不相邻的范围。
+
+### 交叉 Selection
+
+Selection 不要求像 XML 标签那样嵌套,它们可以互相交叉:
+
+```svml
+<demo>
+ <HOST> @a One @b two @/a three @/b.
+</demo>
+```
+
+Selection 标记是零宽度的,不会出现在任何文本投影中。它们编译为包含 `Range[]` 的 `SelectionSet` 值。Script 本身不包含秒数或帧号——时间信息来自 WhisperX 对齐。
+
+其他组件通过 `{story.selection.problem}` 引用 Selection,将视觉内容绑定到叙事中的语义时刻。
+
+## Moment
+
+Moment 是具名的时间**点**(不是范围):
+
+```svml
+<ecosystem>
+ <HOST> @ranking! Image generation, video generation, captions and B-roll
+ all become reusable components.
+</ecosystem>
+```
+
+| 标记 | 含义 |
+|---|---|
+| `@id!` | 右吸附(时间点位于下一个单词的起始处) |
+| `~@id!` | 左吸附(时间点位于前一个单词的末尾) |
+
+Moment 编译为包含 `Point[]` 的 `MomentSet` 值。Selection 和 Moment 共享同一命名空间——同一个 id 不能同时用于两者。
+
+其他组件通过 `{story.moment.ranking}` 引用 Moment。
+
+## Slot
+
+用于模板化 Script 的变量插值:
+
+```svml
+<intro>
+ <HOST> Meet <${product} | ${product_pronunciation}>.
+</intro>
+```
+
+Slot id 为 1–64 个字符,以字母或下划线开头。绑定值为纯文本——它们无法注入 SVML 语法。Slot 先被解析,再进行绑定。
+
+## 注释与转义
+
+```svml
+<!-- This is a comment. Comments never enter any projection. -->
+
+<demo>
+ <HOST> Follow us \@svml on social media.
+</demo>
+```
+
+保留语法起始符必须转义:
+
+| 转义 | 产生 |
+|---|---|
+| `\@` | 字面量 `@` |
+| `\<` | 字面量 `<` |
+| `\${` | 字面量 `${` |
+| `\\` | 字面量 `\` |
+
+在 Dual Text 内部,还需转义 `\|` 和 `\>`。
+
+## 综合示例
+
+一个使用所有语法构造的完整 Script:
+
+```svml
+<script id="story">
+ @whole
+ <hook>
+ <HOST> @problem Girls, you need to hear this. Never let anyone take credit
+ for your work. @/problem
+ </hook>
+
+ <meeting>
+ <HOST> @solution Then I found <Echo Pro | echo pro>: a card-sized recorder
+ that snaps onto the back of my phone. @ranking! I brought it to one
+ meeting. @/solution
+ </meeting>
+
+ <evidence>
+ <HOST> That gave me @emphasis the courage I was missing @/emphasis.
+ </evidence>
+
+ <payoff>
+ <HOST> And guess what? I'm sitting in my old boss's chair now.
+ </payoff>
+ @/whole~
+</script>
+```
+
+此 Script 声明了:
+
+- 四个 Segment:`hook`、`meeting`、`evidence`、`payoff`
+- 一个 Role Cue:`HOST`(在所有 Segment 中保持一致)
+- 一个 Dual Text:`<Echo Pro | echo pro>`(显示为 "Echo Pro",说出为 "echo pro")
+- 三个 Selection:`whole`(整个 Script)、`problem`、`solution`、`emphasis`
+- 一个 Moment:`ranking`(标记 "I brought it to one meeting" 这一瞬间)
+
+下游组件通过名称引用这些内容:`{story.segment.hook.dialogue}` 用于生成,`{story.selection.problem}` 用于 B-roll 时间绑定,`{story.moment.ranking}` 用于视觉卡片揭示。
diff --git a/docs/zh/quickstart/styles.md b/docs/zh/quickstart/styles.md
new file mode 100644
index 00000000..771a64f6
--- /dev/null
+++ b/docs/zh/quickstart/styles.md
@@ -0,0 +1,394 @@
+---
+title: SVS 样式表
+description: SVS Recipe 语言——用于影片、字幕、B-roll、文本及生成设置的类 CSS 样式表。
+---
+
+# SVS 样式表
+
+SVS(`.svs`)文件使用类 CSS 语法定义可复用的类型化配置值。它们用于配置影片尺寸、字幕外观、B-roll 布局、文本样式、语音估算参数、生成设置和自定义字体。SVS 中的值称为 **Recipe**——它们是不可变的类型化记录,由消费组件进行验证和解释。
+
+## 基本语法
+
+```svs
+<?svml using="@narratage/svs@1"?>
+
+<sheet version="1" id="studio">
+ film.vertical {
+ width: 1080;
+ height: 1920;
+ frame-rate: 30;
+ background: #09090B;
+ }
+
+ /* Comments use CSS-style block syntax. */
+ caption.primary {
+ fill: #FFFFFF;
+ size: 58;
+ }
+</sheet>
+```
+
+- 处理指令 `<?svml using="@narratage/svs@1"?>` 用于选择 SVS 解析器。
+- `<sheet>` 元素包裹所有声明。`id` 属性成为顶层命名空间。
+- 每个块的格式为 `namespace.name { ... }`,属性以 `;` 结尾的键值对形式书写。
+- 注释使用 `/* ... */`。
+
+## 导入与引用
+
+在 `.svml` 源文件中通过命名空间前缀导入 SVS 文件:
+
+```svml
+<import as="studio" source="./studio.svs"/>
+```
+
+然后通过 `{studio.film.vertical}`、`{studio.caption.primary}` 等方式引用各个 Recipe。前缀来自 `as=` 属性;路径来自样式表中的 `namespace.name`。
+
+## Film
+
+Film 外观——画布尺寸和背景颜色。
+
+```svs
+film.vertical {
+ width: 1080;
+ height: 1920;
+ frame-rate: 30;
+ background: #09090B;
+}
+```
+
+| 属性 | 描述 |
+|---|---|
+| `width` | 画布宽度(像素) |
+| `height` | 画布高度(像素) |
+| `frame-rate` | 每秒帧数(通常为 30) |
+| `background` | 画布清除颜色(十六进制) |
+
+通过 `film:Film` 的 `appearance` 属性引用:
+
+```svml
+<film:Film id="main" space={speech.space} appearance={studio.film.vertical}>
+```
+
+## 字幕
+
+字幕视觉外观——位置、排版和容器样式。
+
+```svs
+caption.dialogue {
+ stack-order: 70;
+ x: 0.08;
+ y: 0.76;
+ width: 0.84;
+ font: Inter;
+ weight: 600;
+ size: 58;
+ line-height: 0.96;
+ align: center;
+ fill: #FFFFFF;
+ background: #09090BCC;
+ padding: 16 24;
+ radius: 18;
+}
+```
+
+| 属性 | 描述 |
+|---|---|
+| `stack-order` | 所有 Track 之间的 Z 轴层叠顺序(值越大越靠前) |
+| `x`、`y` | 位置,以画布比例表示(0–1) |
+| `width` | 宽度,以画布比例表示 |
+| `font` | 字体族名称或 SVS 字体引用 |
+| `weight` | 字体粗细(400–900) |
+| `size` | 字体大小(像素) |
+| `line-height` | 行高倍数 |
+| `align` | 文本对齐方式:`left`、`center`、`right` |
+| `fill` | 文本颜色(十六进制,支持透明度) |
+| `background` | 容器背景颜色(十六进制,支持透明度,如 `#09090BCC`) |
+| `padding` | 容器内边距(像素)(单个值或 `垂直 水平`) |
+| `radius` | 容器圆角半径(像素) |
+
+通过 `caption:Style` 的 `appearance` 属性引用:
+
+```svml
+<caption:Style id="primary-caption" appearance={studio.caption.dialogue}>
+```
+
+### 按角色设置字幕样式
+
+为不同说话者定义多个字幕 Recipe:
+
+```svs
+caption.alice {
+ stack-order: 70;
+ x: 0.08; y: 0.76; width: 0.84;
+ font: Inter; weight: 600; size: 58;
+ fill: #73FBD3;
+ background: #09090BCC;
+ padding: 16 24; radius: 18;
+}
+
+caption.bob {
+ stack-order: 70;
+ x: 0.08; y: 0.76; width: 0.84;
+ font: Inter; weight: 600; size: 58;
+ fill: #FFD166;
+ background: #09090BCC;
+ padding: 16 24; radius: 18;
+}
+```
+
+然后通过 `caption:Program` 进行分配:
+
+```svml
+<caption:Program id="caption-program" narrative={story} default={studio.caption.dialogue}>
+ <caption:Use role="ALICE" style={alice-caption}/>
+ <caption:Use role="BOB" style={bob-caption}/>
+</caption:Program>
+```
+
+## B-roll
+
+B-roll 项目外观——位置、适配方式、容器以及进入/退出动画。
+
+```svs
+broll.product {
+ stack-order: 40;
+ x: 0.08;
+ y: 0.20;
+ width: 0.84;
+ height: 0.48;
+ fit: contain;
+ background: #111116;
+ radius: 28;
+ enter: slide-up 8f;
+ exit: fade 6f;
+}
+```
+
+| 属性 | 描述 |
+|---|---|
+| `stack-order` | Z 轴层叠顺序 |
+| `x`、`y` | 位置,以画布比例表示 |
+| `width`、`height` | 尺寸,以画布比例表示 |
+| `fit` | 源内容适配容器的方式:`cover`、`contain` |
+| `background` | 容器背景颜色 |
+| `radius` | 容器圆角半径 |
+| `enter` | 进入动画:`slide-up Nf`、`fade Nf`(N = 帧数) |
+| `exit` | 退出动画:`fade Nf`、`slide-down Nf` |
+
+通过 `broll:Item` 的 `appearance` 属性引用:
+
+```svml
+<broll:Item source={motion.video} during={story.selection.demo}
+ appearance={studio.broll.product}/>
+```
+
+## 文本
+
+文本叠加层外观——位置、排版。
+
+```svs
+text.title {
+ stack-order: 90;
+ x: 0.06;
+ y: 0.06;
+ width: 0.88;
+ height: 0.10;
+ font: Inter;
+ weight: 900;
+ size: 64;
+ align: center;
+ fill: #FFFFFF;
+ tracking: -1;
+}
+```
+
+| 属性 | 描述 |
+|---|---|
+| `stack-order` | Z 轴层叠顺序 |
+| `x`、`y` | 位置,以画布比例表示 |
+| `width`、`height` | 尺寸,以画布比例表示 |
+| `font` | 字体族名称 |
+| `weight` | 字体粗细 |
+| `size` | 字体大小(像素) |
+| `align` | 文本对齐方式 |
+| `fill` | 文本颜色 |
+| `tracking` | 字间距调整 |
+
+通过 `text:Item` 的 `appearance` 属性引用:
+
+```svml
+<text:Item text="MEANING" during="full" appearance={studio.text.title}/>
+```
+
+## 语音估算
+
+确定性语音时长估算的参数。
+
+```svs
+speech.normal {
+ language: en;
+ pace: normal;
+ padding: 0.3;
+ min: 4;
+ max: 15;
+ rounding: ceil;
+}
+```
+
+| 属性 | 描述 |
+|---|---|
+| `language` | 语言代码(如 `en`) |
+| `pace` | 语速:`slow`、`normal`、`fast` |
+| `padding` | 添加到估算值的额外填充时间(秒) |
+| `min` | 最小时长(秒) |
+| `max` | 最大时长(秒) |
+| `rounding` | 取整模式:`ceil`、`floor`、`round` |
+
+通过 `estimate:Speech` 的 `policy` 属性引用:
+
+```svml
+<estimate:Speech id="hook-duration" source={story.segment.hook.speech}
+ policy={studio.speech.normal}/>
+```
+
+## Speaker
+
+Seedance Speaker 生成设置——控制 `speaker:Take` 如何生成说话人头像片段的 Recipe。
+
+```svs
+speaker.echo-pro {
+ kind: ugc-talking-head;
+ model: mini;
+ resolution: 720p;
+ aspect-ratio: 9:16;
+ composition-stability: soft-locked;
+ camera-motion: none;
+ edit-rhythm: continuous-take;
+ performance: natural-explainer;
+ gesture: natural;
+ voice-mode: single-speaker;
+}
+```
+
+| 属性 | 描述 |
+|---|---|
+| `kind` | 生成类型(如 `ugc-talking-head`) |
+| `model` | 模型名称:`mini` |
+| `resolution` | 输出分辨率:`480p`、`720p`、`1080p` |
+| `aspect-ratio` | 输出宽高比:`9:16`、`16:9`、`1:1` |
+| `composition-stability` | 镜头/构图一致性:`flexible-ugc`、`soft-locked`、`strict-locked` |
+| `camera-motion` | 镜头运动:`none`、`subtle-punch-in-return` |
+| `edit-rhythm` | 剪辑风格:`continuous-take`、`pause-trim-jump-cuts` |
+| `performance` | 表演风格:`natural-explainer`、`high-energy-ugc`、`calm-authority`、`reactive-playful` |
+| `gesture` | 手势强度:`restrained`、`compact`、`natural`、`expressive` |
+| `voice-mode` | 语音配置:`single-speaker` |
+
+通过 `speaker:Take` 的 `recipe` 属性引用:
+
+```svml
+<speaker:Take id="hook-take" dialogue={story.segment.hook.dialogue}
+ duration={hook-duration.duration} recipe={studio.speaker.echo-pro} kit={ugc.official-ugc-v1}>
+```
+
+## 字体声明
+
+声明本地字体文件,以便在字幕和文本叠加层中使用。
+
+```svs
+font.inter-semibold {
+ src: ./assets/Inter-SemiBold.woff2;
+ weight: 600;
+ style: normal;
+}
+
+font.inter-black {
+ src: ./assets/Inter-Black.woff2;
+ weight: 900;
+ style: normal;
+}
+```
+
+| 属性 | 描述 |
+|---|---|
+| `src` | 字体文件路径(相对于 SVS 文件) |
+| `weight` | 该文件提供的字体粗细 |
+| `style` | 字体样式:`normal`、`italic` |
+
+字体路径在编译时解析,并成为 `FontArtifactRef` 值。在其他 SVS 块中通过名称引用:
+
+```svs
+caption.dialogue {
+ font: inter-semibold;
+ /* ... */
+}
+```
+
+## 综合示例
+
+一个完整的 `studio.svs` 文件,用于四段式说话人头像项目:
+
+```svs
+<?svml using="@narratage/svs@1"?>
+
+<sheet version="1" id="studio">
+ speech.normal {
+ language: en;
+ pace: normal;
+ padding: 0.3;
+ min: 4;
+ max: 15;
+ rounding: ceil;
+ }
+
+ speaker.echo-pro {
+ kind: ugc-talking-head;
+ model: mini;
+ resolution: 720p;
+ aspect-ratio: 9:16;
+ composition-stability: soft-locked;
+ camera-motion: none;
+ edit-rhythm: continuous-take;
+ performance: natural-explainer;
+ gesture: natural;
+ voice-mode: single-speaker;
+ }
+
+ film.vertical {
+ width: 720;
+ height: 1280;
+ frame-rate: 30;
+ background: #09090B;
+ }
+
+ caption.primary {
+ stack-order: 70;
+ x: 0.08;
+ y: 0.74;
+ width: 0.84;
+ font: Inter;
+ weight: 800;
+ size: 44;
+ line-height: 1;
+ align: center;
+ fill: #FFFFFF;
+ background: #09090BCC;
+ padding: 14 20;
+ radius: 16;
+ }
+</sheet>
+```
+
+该文件在 `.svml` 源文件中导入一次,其值在整个文件中被引用:
+
+```svml
+<import as="studio" source="./studio.svs"/>
+
+<estimate:Speech id="hook-duration" source={story.segment.hook.speech}
+ policy={studio.speech.normal}/>
+
+<speaker:Take id="hook-take" ... recipe={studio.speaker.echo-pro} .../>
+
+<caption:Style id="primary-caption" appearance={studio.caption.primary} .../>
+
+<film:Film id="main" space={speech.space} appearance={studio.film.vertical}>
+```
diff --git a/docs/zh/quickstart/timing.md b/docs/zh/quickstart/timing.md
new file mode 100644
index 00000000..54a7aaa4
--- /dev/null
+++ b/docs/zh/quickstart/timing.md
@@ -0,0 +1,149 @@
+---
+title: 时序与装配
+description: Speech Spine 装配与 WhisperX 对齐——将生成的片段连接到统一时间线。
+---
+
+# 时序与装配
+
+生成完成后,各个片段必须拼接成一个连续的音视频坐标空间,并且需要将语音内容与实际音频进行比对,以创建时序映射。这两个步骤产生 **ProgramSpace** 和 **SemanticMap**,所有下游组件均依赖于它们。
+
+```svml
+<import as="speech" from="@narratage/speech-spine@1"/>
+<import as="whisperx" from="@narratage/whisperx@1"/>
+```
+
+## speech:Spine
+
+将多个片段拼接成一个有序的音视频坐标空间。Spine 定义了节目顺序——即最终视频中 Segment 的排列序列。
+
+```svml
+<speech:Spine id="speech">
+ <speech:Take source={hook-take.video} segment={story.segment.hook}/>
+ <speech:Take source={meeting-take.video} segment={story.segment.meeting}/>
+ <speech:Take source={evidence-take.video} segment={story.segment.evidence}/>
+ <speech:Take source={payoff-take.video} segment={story.segment.payoff}/>
+</speech:Spine>
+```
+
+| 属性 | 必填 | 描述 |
+|---|---|---|
+| `id` | 是 | 唯一标识符 |
+
+### speech:Take
+
+每个 `<speech:Take>` 子元素将一个生成的视频绑定到一个 Script Segment:
+
+| 属性 | 必填 | 描述 |
+|---|---|---|
+| `source` | 是 | 生成的视频——来自 `seedance:Speech`、`speaker:Take` 等 |
+| `segment` | 是 | 此片段对应的 Script Segment——例如 `{story.segment.hook}` |
+
+`<speech:Take>` 子元素的排列顺序**决定了节目顺序**。第一个片段从时间零点开始;后续片段依次紧接。
+
+### 输出
+
+Spine 产生四个输出,供下游组件使用:
+
+| 输出 | 类型 | 使用方 |
+|---|---|---|
+| `{speech.visual}` | VisualTrack | `film:Film`——全屏真人出镜视频 |
+| `{speech.audio}` | Audio | `whisperx:Alignment`——用于词级时序的原始音频 |
+| `{speech.audioTrack}` | AudioTrack | `film:Film`——同步音频 |
+| `{speech.space}` | ProgramSpace | 所有组件——统一的时长和帧域 |
+
+## whisperx:Alignment
+
+通过对 Spine 的音频输出运行 WhisperX 语音转文本对齐,测量词级时序。这将产生 **SemanticMap**——连接 Script 文本与物理时间的桥梁。
+
+```svml
+<whisperx:Alignment id="timing" narrative={story} audio={speech.audio}/>
+```
+
+| 属性 | 必填 | 描述 |
+|---|---|---|
+| `id` | 是 | 唯一标识符 |
+| `narrative` | 是 | Script 组件——例如 `{story}` |
+| `audio` | 是 | 来自 Speech Spine 的音频——`{speech.audio}` |
+
+### 输出
+
+| 输出 | 类型 | 使用方 |
+|---|---|---|
+| `{timing.map}` | CompleteSemanticMap | `caption:Track`、`broll:Track`、`text:Track`——定时放置 |
+
+SemanticMap 将每个 Script 中标注的锚点映射到一个时间点。它覆盖所有 `2M + 2N` 个标识(其中 M = 语音词元总数,N = Segment 数量)。这就是 Script 中声明的 Selection 和 Moment 如何转化为下游视觉组件所需的实际时间范围和时间点。
+
+## ProgramSpace
+
+ProgramSpace 不是一个需要声明的组件——它由 `speech:Spine` 产生,并传递给每个需要知道总节目时长和帧域的组件。
+
+```svml
+<film:Film id="main" space={speech.space} ...>
+<caption:Track id="captions" ... space={speech.space} .../>
+<text:Track id="titles" space={speech.space}>
+<render:Video id="final" composition={main.composition} space={speech.space}/>
+```
+
+ProgramSpace 包含:
+
+- **时长**——节目总长度
+- **帧率**——有理帧率(例如 30fps)
+- **帧域**——整个节目的精确帧编号
+
+每个在时间域中运行的组件都通过 `space` 属性指向 `{speech.space}`。
+
+## SemanticMap
+
+SemanticMap 是连接 Script 文本与物理时间的类型化桥梁。当你在 B-roll 项上写 `during={story.selection.demo}` 时,组件会使用 SemanticMap 查找该 Selection 覆盖的精确帧范围。没有 SemanticMap,Selection 和 Moment 就没有物理意义。
+
+使用该映射的组件通过 `map` 属性接收它:
+
+```svml
+<broll:Track id="cards" map={timing.map} ...>
+<caption:Track id="captions" ... map={timing.map} .../>
+```
+
+映射中的每个点可以是:
+
+- **测量值**——由 WhisperX 对齐直接观测得到
+- **推导值**——通过插值从测量值计算得出
+- **估算值**——来自初始时长估计(在对齐运行之前使用)
+
+## 组合示例
+
+完整的时序阶段,从生成的片段到映射和空间:
+
+```svml
+<import as="speech" from="@narratage/speech-spine@1"/>
+<import as="whisperx" from="@narratage/whisperx@1"/>
+
+<!-- Assemble takes in program order -->
+<speech:Spine id="speech">
+ <speech:Take source={opening-take} segment={story.segment.opening}/>
+ <speech:Take source={answer-take} segment={story.segment.answer}/>
+</speech:Spine>
+
+<!-- Measure word timing -->
+<whisperx:Alignment id="timing" narrative={story} audio={speech.audio}/>
+
+<!-- Downstream components now reference: -->
+<!-- {speech.space} — ProgramSpace for duration/frame domain -->
+<!-- {speech.visual} — VisualTrack for the talking-head video -->
+<!-- {speech.audioTrack} — AudioTrack for synchronized audio -->
+<!-- {timing.map} — SemanticMap for Selection/Moment timing -->
+```
+
+数据流向:
+
+```text
+speaker:Take outputs ──► speech:Spine ──► whisperx:Alignment
+ │ │
+ .visual .map (SemanticMap)
+ .audio │
+ .audioTrack ▼
+ .space ──────────► caption:Track
+ │ broll:Track
+ │ text:Track
+ ▼ film:Film
+ film:Film render:Video
+```
diff --git a/docs/zh/quickstart/tracks.md b/docs/zh/quickstart/tracks.md
new file mode 100644
index 00000000..0e7977f0
--- /dev/null
+++ b/docs/zh/quickstart/tracks.md
@@ -0,0 +1,342 @@
+---
+title: 字幕、B-roll 与文字
+description: 视觉 Track 组件——字幕、B-roll 叠加层和文字叠加层。
+---
+
+# 字幕、B-roll 与文字
+
+每个进入最终合成的视听内容都是一个对等的 **Track**。Track 是扁平的(无嵌套),其 z 轴顺序由 SVS 中的 `stack-order` 属性决定。本页介绍三种主要的视觉 Track 类型:字幕、B-roll 和文字叠加层。
+
+## 字幕系统
+
+字幕由四个组件构成一条流水线:
+
+```text
+caption:Style → caption:Program → caption-ai:Planner → caption:Track
+```
+
+```svml
+<import as="caption" from="@narratage/caption@1"/>
+<import as="caption-ai" from="@narratage/caption-gemini@1"/>
+```
+
+### caption:Style
+
+声明一种字幕样式的完整视觉外观及规划指令。
+
+```svml
+<caption:Style id="primary-caption" appearance={studio.caption.primary}
+ mode="proportional-word">
+ <caption:Cues>
+ Split each Script Segment into short complete semantic phrases of two to
+ seven words. Never cross a sentence or Segment boundary.
+ </caption:Cues>
+ <caption:Field id="important" type="boolean" min-per-cue="1" max-per-cue="2">
+ Select one or two words whose emphasis best communicates this Cue.
+ </caption:Field>
+</caption:Style>
+```
+
+| 属性 | 必填 | 描述 |
+|---|---|---|
+| `id` | 是 | 唯一标识符 |
+| `appearance` | 是 | SVS 字幕 Recipe——位置、字体、颜色、容器 |
+| `mode` | 否 | 字幕计时模式,例如 `proportional-word` |
+
+**子元素:**
+
+- `<caption:Cues>` —— 给 AI 规划器的自然语言指令,告诉它如何将文本拆分为提示单元。规划器接收显示文本(Dual Text 的左侧)和这些指令,但不会接收音频或时间数据。
+- `<caption:Field>` —— 声明一个有类型的逐词注解。规划器将这些字段分配给每个提示单元中的各个词。
+
+| `<caption:Field>` 属性 | 描述 |
+|---|---|
+| `id` | 字段名称(例如 `important`) |
+| `type` | 字段类型:`boolean` |
+| `min-per-cue` | 每个提示单元的最少注解数 |
+| `max-per-cue` | 每个提示单元的最多注解数 |
+
+`<caption:Field>` 的元素主体是给规划器的自然语言指令。
+
+### caption:Program
+
+将字幕样式分配给叙事。声明一个默认样式,并可选择按角色或按 Selection 覆盖。
+
+```svml
+<caption:Program id="caption-program" narrative={story} default={primary-caption}>
+ <caption:Use role="ALICE" style={alice-caption}/>
+ <caption:Use role="BOB" style={bob-caption}/>
+ <caption:Use on={story.selection.product-demo} style={dialogue-caption}/>
+</caption:Program>
+```
+
+| 属性 | 必填 | 描述 |
+|---|---|---|
+| `id` | 是 | 唯一标识符 |
+| `narrative` | 是 | Script 组件 |
+| `default` | 是 | 所有文本的默认 `caption:Style` |
+
+**子元素:**
+
+`<caption:Use>` 用于应用样式覆盖。规则按源代码顺序应用——后匹配优先。
+
+| `<caption:Use>` 属性 | 描述 |
+|---|---|
+| `role` | 按 Role Cue 标签匹配(例如 `"ALICE"`) |
+| `on` | 按 Selection 引用匹配(例如 `{story.selection.product-demo}`) |
+| `style` | 要应用的 `caption:Style` |
+
+使用 `role=` 为不同说话者设置不同的字幕颜色。使用 `on=` 在特定 Selection 期间覆盖样式(例如产品演示部分使用不同的字幕样式)。
+
+### caption-ai:Planner
+
+通过 Gemini 驱动的 AI 提示单元规划。规划器接收显示文本原子、Style 指令和 Program 分配,将文本拆分为提示单元并分配 Field 值。
+
+```svml
+<caption-ai:Planner id="caption-plan" narrative={story}
+ program={caption-program} model="gemini-2.5-flash"/>
+```
+
+| 属性 | 必填 | 描述 |
+|---|---|---|
+| `id` | 是 | 唯一标识符 |
+| `narrative` | 是 | Script 组件 |
+| `program` | 是 | `caption:Program` |
+| `model` | 是 | Gemini 模型:`gemini-2.5-flash` |
+
+规划器不会接收音频、时间数据或 Dual Text 的语音侧。它完全基于字幕(显示)投影进行工作。
+
+**输出:**`{caption-plan.plan}` —— 提示单元计划,传递给 `caption:Track`。
+
+### caption:Track
+
+将提示单元计划、SemanticMap、ProgramSpace 和 Program 组合在一起,生成一个带时间信息的 VisualTrack。
+
+```svml
+<caption:Track id="captions" narrative={story} map={timing.map}
+ space={speech.space} program={caption-program} plan={caption-plan.plan}/>
+```
+
+| 属性 | 必填 | 描述 |
+|---|---|---|
+| `id` | 是 | 唯一标识符 |
+| `narrative` | 是 | Script 组件 |
+| `map` | 是 | 来自 `whisperx:Alignment` 的 SemanticMap |
+| `space` | 是 | 来自 `speech:Spine` 的 ProgramSpace |
+| `program` | 是 | `caption:Program` |
+| `plan` | 是 | 来自 `caption-ai:Planner` 的提示单元计划 |
+
+**输出:**`{captions.track}` —— 添加到 `film:Film` 的 VisualTrack。
+
+### 字幕组合示例
+
+包含按角色样式的完整字幕流水线:
+
+```svml
+<caption:Style id="dialogue-caption" appearance={studio.caption.dialogue}>
+ <caption:Cues>Use short complete semantic phrases, two to five words.</caption:Cues>
+</caption:Style>
+
+<caption:Style id="alice-caption" appearance={studio.caption.alice}>
+ <caption:Cues>Use short complete semantic phrases, two to five words.</caption:Cues>
+ <caption:Field id="important" type="boolean" min-per-cue="0" max-per-cue="2">
+ Select at most two words whose emphasis best communicates this Cue.
+ </caption:Field>
+</caption:Style>
+
+<caption:Style id="bob-caption" appearance={studio.caption.bob}>
+ <caption:Cues>Use short complete semantic phrases, two to five words.</caption:Cues>
+</caption:Style>
+
+<caption:Program id="caption-program" narrative={story} default={dialogue-caption}>
+ <caption:Use role="ALICE" style={alice-caption}/>
+ <caption:Use role="BOB" style={bob-caption}/>
+ <caption:Use on={story.selection.product-demo} style={dialogue-caption}/>
+</caption:Program>
+
+<caption-ai:Planner id="caption-plan" narrative={story}
+ program={caption-program} model="gemini-2.5-flash"/>
+
+<caption:Track id="captions" narrative={story} map={timing.map}
+ space={speech.space} program={caption-program} plan={caption-plan.plan}/>
+```
+
+ALICE 使用绿色字幕(`#73FBD3`),BOB 使用金色字幕(`#FFD166`),在 product-demo Selection 期间两者都切换为中性对话样式。`important` Field 仅应用于 ALICE 的样式——她的强调词会获得特殊处理。
+
+## B-roll
+
+B-roll 在语义时间位置叠加生成的或预先提供的视频/图像。
+
+```svml
+<import as="broll" from="@narratage/broll@1"/>
+```
+
+### broll:Track
+
+B-roll 项目的容器。接收 SemanticMap 用于时间解析。
+
+```svml
+<broll:Track id="product-broll" map={timing.map} space={speech.space}>
+ <broll:Item source={product-motion.video}
+ during={story.selection.product-demo}
+ appearance={studio.broll.product}/>
+</broll:Track>
+```
+
+| 属性 | 必填 | 描述 |
+|---|---|---|
+| `id` | 是 | 唯一标识符 |
+| `map` | 是 | 来自 `whisperx:Alignment` 的 SemanticMap |
+| `space` | 否 | ProgramSpace(某些配置需要) |
+
+### broll:Item
+
+每个项目将一个来源放置在语义时间位置上,并附带样式外观:
+
+```svml
+<broll:Item source={product-motion.video}
+ during={story.selection.product-demo}
+ appearance={studio.broll.product}/>
+```
+
+| 属性 | 必填 | 描述 |
+|---|---|---|
+| `source` | 是 | 视频或图像——来自 `seedance:Video`、`media:Image` 等 |
+| `during` | 是 | Selection 引用——该项目何时出现 |
+| `appearance` | 是 | SVS B-roll Recipe——位置、大小、适配方式、动画 |
+
+`during` 属性接收一个 Selection 引用,如 `{story.selection.product-demo}`。B-roll 项目在屏幕上显示的时长恰好等于该 Selection 的持续时间,通过 SemanticMap 解析确定。
+
+外观 Recipe 控制进场/退场动画:
+
+```svs
+broll.product {
+ stack-order: 40;
+ x: 0.08; y: 0.20; width: 0.84; height: 0.48;
+ fit: contain;
+ background: #111116;
+ radius: 28;
+ enter: slide-up 8f;
+ exit: fade 6f;
+}
+```
+
+**输出:**`{product-broll.visual}` —— 添加到 `film:Film` 的 VisualTrack。
+
+### B-roll 示例
+
+B-roll 搭配生成的 Seedance 视频,在 Script Selection 期间出现:
+
+```svml
+<seedance:Prompt id="product-direction">
+ A clean vertical product film: the written script becomes semantic regions,
+ then those regions assemble into a finished video.
+</seedance:Prompt>
+
+<seedance:Video id="product-motion" model="mini"
+ prompt={product-direction} duration="5">
+ <seedance:Reference image={product-reference} role="subject"/>
+</seedance:Video>
+
+<broll:Track id="product-broll" map={timing.map}>
+ <broll:Item source={product-motion.video}
+ during={story.selection.product-demo}
+ appearance={studio.broll.product}/>
+</broll:Track>
+```
+
+## 文字叠加层
+
+在屏幕上显示的静态或定时文字——标题、标注、下方三分之一字幕条。
+
+```svml
+<import as="text" from="@narratage/text-track@1"/>
+```
+
+### text:Track
+
+文字项目的容器。
+
+```svml
+<text:Track id="titles" space={speech.space}>
+ <text:Item text="EDIT MEANING, NOT TIMELINES" during="full"
+ appearance={studio.text.title}/>
+</text:Track>
+```
+
+| 属性 | 必填 | 描述 |
+|---|---|---|
+| `id` | 是 | 唯一标识符 |
+| `space` | 是 | 来自 `speech:Spine` 的 ProgramSpace |
+| `map` | 否 | SemanticMap——当项目使用基于 Selection 的计时时需要 |
+
+### text:Item
+
+每个项目是放置在某个时间位置的一段文本字符串:
+
+```svml
+<text:Item text="MEANING" during="full" appearance={studio.text.title}/>
+```
+
+| 属性 | 必填 | 描述 |
+|---|---|---|
+| `text` | 是 | 要显示的文本字符串 |
+| `during` | 是 | 何时显示:`"full"`(整个节目时长)或 Selection 引用 |
+| `appearance` | 是 | SVS 文字 Recipe——位置、字体、大小、颜色 |
+
+`during` 属性接受字面字符串 `"full"`(表示整个节目时长),或 Selection 引用(用于语义计时):
+
+```svml
+<text:Track id="callout" space={speech.space} map={timing.map}>
+ <text:Item text="EXACTLY THE RIGHT MOMENT"
+ during={story.selection.callout}
+ appearance={studio.text.callout}/>
+</text:Track>
+```
+
+**输出:**`{titles.track}` —— 添加到 `film:Film` 的 VisualTrack。
+
+## 组合示例
+
+三种 Track 类型在一个源文件中协同使用:
+
+```svml
+<import as="caption" from="@narratage/caption@1"/>
+<import as="caption-ai" from="@narratage/caption-gemini@1"/>
+<import as="broll" from="@narratage/broll@1"/>
+<import as="text" from="@narratage/text-track@1"/>
+
+<!-- Captions: primary style for all text -->
+<caption:Style id="base-caption" appearance={studio.caption.base}>
+ <caption:Cues>Prefer short complete semantic phrases.</caption:Cues>
+ <caption:Field id="important" type="boolean" min-per-cue="0" max-per-cue="2">
+ Select zero, one, or two words whose emphasis best communicates this Cue.
+ </caption:Field>
+</caption:Style>
+<caption:Program id="caption-program" narrative={story} default={base-caption}/>
+<caption-ai:Planner id="cue-plan" narrative={story}
+ program={caption-program} model="gemini-2.5-flash"/>
+<caption:Track id="captions" narrative={story} map={timing.map}
+ space={speech.space} plan={cue-plan.plan} program={caption-program}/>
+
+<!-- B-roll: generated video during a Selection -->
+<broll:Track id="cards" map={timing.map} space={speech.space}>
+ <broll:Item source={motion.video} during={story.selection.demo}
+ appearance={studio.broll.card}/>
+</broll:Track>
+
+<!-- Text: persistent title overlay -->
+<text:Track id="titles" space={speech.space}>
+ <text:Item text="MEANING" during="full" appearance={studio.text.title}/>
+</text:Track>
+
+<!-- All three tracks feed into Film -->
+<film:Film id="main" space={speech.space} appearance={studio.film.vertical}>
+ <film:Track source={speech.visual}/>
+ <film:Track source={speech.audioTrack}/>
+ <film:Track source={cards.visual}/>
+ <film:Track source={captions.track}/>
+ <film:Track source={titles.track}/>
+</film:Film>
+```
+
+每个 SVS Recipe 中的 `stack-order` 决定 z 轴排序:语音视觉层为 10,B-roll 为 40,字幕为 70,文字为 90。数值越高,渲染层越靠上。