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: document the components a reader could not find

rponecca2df02f1e5
diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts
index 4b6ce2ee..9a8a940c 100644
--- a/docs/.vitepress/config.ts
+++ b/docs/.vitepress/config.ts
@@ -139,8 +139,9 @@ const enTheme = {
{ text: "Script", link: "/quickstart/script" },
{ text: "SVS Stylesheets", link: "/quickstart/styles" },
{ text: "Media & Generation", link: "/quickstart/generation" },
+ { text: "Image Operations", link: "/quickstart/images" },
{ text: "Timing & Assembly", link: "/quickstart/timing" },
- { text: "Caption, Media, Typography & Audio Tracks", link: "/quickstart/tracks" },
+ { text: "Tracks", link: "/quickstart/tracks" },
{ text: "Film & Rendering", link: "/quickstart/composition" },
{ text: "Live Preview", link: "/quickstart/preview" },
{ text: "Run Source & Builds", link: "/quickstart/run" },
@@ -183,8 +184,9 @@ const zhTheme = {
{ text: "Script", link: "/zh/quickstart/script" },
{ text: "SVS 样式表", link: "/zh/quickstart/styles" },
{ text: "媒体与生成", link: "/zh/quickstart/generation" },
+ { text: "图片操作", link: "/zh/quickstart/images" },
{ text: "时序与装配", link: "/zh/quickstart/timing" },
- { text: "字幕、Media、Typography 与 Audio 轨道", link: "/zh/quickstart/tracks" },
+ { text: "轨道", link: "/zh/quickstart/tracks" },
{ text: "Film 与渲染", link: "/zh/quickstart/composition" },
{ text: "实时预览", link: "/zh/quickstart/preview" },
{ text: "Run Source 与 Build", link: "/zh/quickstart/run" },
diff --git a/docs/quickstart/images.md b/docs/quickstart/images.md
new file mode 100644
index 00000000..971a8180
--- /dev/null
+++ b/docs/quickstart/images.md
@@ -0,0 +1,102 @@
+---
+title: Image Operations
+description: Compose, correct and cut out images before they reach a generator or a Track.
+---
+
+# Image Operations
+
+Three packages work on a picture and hand back a picture. None of them produces a Track: each output
+is an image you reference downstream — as a Seedance reference frame, as a Media Item, or as the
+source of another operation.
+
+They all need an endpoint. `image-compose` and `image-transform` ask for the raster capability, which
+`@narratage/provider-image-opencv-local` answers by running OpenCV in a bounded Python process on
+your own machine; `background-removal` asks for its own capability, which `@narratage/provider-kie`
+answers remotely. No example in this repository binds either, so add the endpoint to your
+[Runtime Profile](/guide/runtime-profile) before planning a Build that uses one.
+
+## Composing layers
+
+`compose:Image` paints layers onto one canvas, in the order they are written, and hands back a PNG.
+
+```svml
+<import as="compose" from="@narratage/image-compose@1"/>
+```
+
+The element takes `id` and `canvas`, and optionally `background` — which must carry alpha, as
+`#RRGGBBAA`, and defaults to fully transparent. Its children are `compose:Layer`, at least one and at
+most sixty-four, each empty:
+
+| Attribute | Takes |
+|---|---|
+| `source` | required — an image |
+| `frame` | required — a `space:Frame` |
+| `fit` | optional — `contain` (default), `cover` or `stretch` |
+| `interpolation` | optional — `nearest`, `linear`, `cubic`, `area` or `lanczos` (default) |
+| `opacity` | optional — 0 to 1, default 1 |
+
+```svml
+<compose:Image id="card" canvas={portrait} background="#00000000">
+ <compose:Layer source={background.image} frame={full} fit="cover"/>
+ <compose:Layer source={product.image} frame={product-frame} fit="contain"/>
+</compose:Image>
+```
+
+**Output:** `{card.image}` — an image, not a Track.
+
+## Correcting an image
+
+An `image:Program` is a named list of operations; an `image:Transform` runs one over a source. The
+split is deliberate: a program written once is applied to every shot that needs the same treatment.
+
+```svml
+<import as="image" from="@narratage/image-transform@1"/>
+```
+
+`image:Program` takes only `id`, and holds its operations as children, applied in the order written:
+
+| Operation | Attributes |
+|---|---|
+| `Crop` | `x`, `y`, `width`, `height`; optional `unit="fraction" \| "pixel"` |
+| `Resize` | `width`, `height`; optional `fit`, `interpolation`, `background` |
+| `Rotate` | `degrees`, which must be `90`, `180` or `270` |
+| `Flip` | optional `axis="horizontal" \| "vertical" \| "both"` |
+| `Denoise` | optional `luma`, `chroma`, `template-window`, `search-window`, `saturation-recovery` |
+| `Color` | optional `exposure-stops`, `contrast`, `saturation`, `temperature`, `tint`, `gamma` |
+| `Sharpen` | optional `amount`, `radius`, `threshold` |
+| `Blur` | `sigma` |
+| `Alpha` | optional `mode="preserve" \| "flatten"`; `background` is required by `flatten` and refused by `preserve` |
+| `Encode` | optional `format="png" \| "jpeg" \| "webp"`, `quality`, `background` |
+
+A program may hold at most one `Encode`, and it must be last. Every operation but `Blur`, `Rotate`
+and `Crop` runs on defaults alone, so `<image:Denoise/>` is a complete instruction.
+
+`image:Transform` takes `id`, `source` and `program`, all required.
+
+```svml
+<image:Program id="clean-gpt-image">
+ <image:Denoise/>
+ <image:Encode format="png"/>
+</image:Program>
+
+<image:Transform id="clean-shot" source={shot.image} program={clean-gpt-image}/>
+```
+
+**Output:** `{clean-shot.image}`. The program on its own produces no image — it is a recipe, and
+naming it in a `Transform` is what runs it.
+
+## Removing a background
+
+```svml
+<import as="remove" from="@narratage/background-removal@1"/>
+```
+
+`remove:Background` is empty and takes `id` and `source`. It picks no model, threshold or storage —
+that is the endpoint's business, not the Source's.
+
+```svml
+<remove:Background id="cutout" source={portrait.image}/>
+```
+
+**Output:** `{cutout.image}` — typically fed to a Media Item so a presenter sits over the picture
+rather than in a box.
diff --git a/docs/quickstart/tracks.md b/docs/quickstart/tracks.md
index 7fba5737..38186502 100644
--- a/docs/quickstart/tracks.md
+++ b/docs/quickstart/tracks.md
@@ -1,9 +1,9 @@
---
-title: Caption, Media, Typography & Audio Tracks
+title: Tracks
description: Peer track components — captions, media, typography and authored audio.
---
-# Caption, Media, Typography & Audio Tracks
+# Tracks
Every audiovisual contribution entering the final composition is a peer **Track**. Tracks are flat
(no nesting), and visual z-order is determined by the `stack-order` property in SVS. This page
@@ -327,6 +327,190 @@ placement, timing, style and motion. Use inline `P`/`Span`/`Break` when the auth
**Output:** `{titles.track}` — a VisualTrack added to `film:Film`.
+## Ranking boards
+
+A board animates an ordered list against the Script: it enters on a Selection, moves on Moments, and
+settles on a Moment that ends it. Four variants share one shape — a container, its own item tag, and
+its own style tag.
+
+| Container | Item | Style |
+|---|---|---|
+| `ranking:TierBoard` | `ranking:TierItem` | `ranking:TierBoardStyle` |
+| `ranking:Column` | `ranking:ColumnItem` | `ranking:ColumnStyle` |
+| `ranking:TopThree` | `ranking:TopThreeItem` | `ranking:TopThreeStyle` |
+| `ranking:TypewriterList` | `ranking:TypewriterItem` | `ranking:TypewriterListStyle` |
+
+```svml
+<import as="ranking" from="@narratage/ranking@1"/>
+```
+
+### The style tag
+
+Empty, and all three attributes required: `id`, `recipe` (an SVS Recipe) and `font` (a Font Stack or
+Font artifact). The recipe carries the board's own keys — rows, colours, motion — and is validated
+against the variant, so a Column recipe on a TierBoard is refused by name.
+
+### The container tag
+
+| Attribute | Takes |
+|---|---|
+| `map` | the Semantic Map that places words |
+| `space` | the Program Space |
+| `frame` | a `space:Frame` |
+| `during` | a Selection — the board is on screen for it |
+| `triggers` | a Moment — rows move on it |
+| `terminal` | a Moment — the board settles on it |
+| `style` | the matching style record, and only that variant's |
+| `title` | `TypewriterList` only, and required there: a string or a Text reference |
+| `appear-sound`, `move-sound` | optional Synchronized Media |
+
+`move-sound` is refused on `TopThree`, which has no move phase. On a `TierBoard` it needs at least
+one item with `entry="stage"`, and on a `TypewriterList` at least one `winner="true"` — a sound with
+nothing to sound on is an authoring mistake, not a silent no-op.
+
+### The item tags
+
+Each variant takes its own, at least one, and ids must be unique within a board.
+
+- **`TierItem`** — `tier` (required, matching a row id in the recipe), `icon` (required), optional
+ `entry="direct" | "stage"` and `stack`. Row labels come from the recipe, not the tag.
+- **`ColumnItem`** and **`TopThreeItem`** — `label` (required: a string or a Text reference), optional
+ `icon` and `stack`. `TopThree` takes at most three.
+- **`TypewriterItem`** — copy comes from `text=` or from the element's own text, one or the other;
+ optional `winner="true"`, `stack`, and `emphasis-start` / `emphasis-end`, which are counted in
+ graphemes and must be given together.
+
+```svml
+<ranking:ColumnStyle id="board-style" recipe={studio.ranking.board} font={ui-font}/>
+<ranking:Column id="board" map={timing.map} space={speech.space} frame={board-frame}
+ during={story.selection.board} triggers={story.moment.place} terminal={story.moment.done}
+ style={board-style}>
+ <ranking:ColumnItem id="row-regen" label="ReGen" icon={icon-regen}/>
+ <ranking:ColumnItem id="row-chatgpt" label="ChatGPT" icon={icon-chatgpt}/>
+ <ranking:ColumnItem id="row-remini" label="Remini" icon={icon-remini}/>
+</ranking:Column>
+```
+
+**Output:** `{board.visual}` — a VisualTrack. A board given a sound also exports `{board.audio}`, an
+AudioTrack; without one there is no audio output to add.
+
+## Card decks
+
+A deck holds cards in depth: one is in front, the others recede behind it, and each new card is dealt
+on a Moment. Where a Media Item places one shot in one Frame, a deck keeps a stack of them in the
+same Frame and moves the whole stack.
+
+```svml
+<import as="deck" from="@narratage/deck-track@1"/>
+```
+
+### deck:DepthStack
+
+`id`, `map`, `space`, `canvas`, `frame` and `appearance` are all required, as is `until`, which says
+what ends the deck: the literal `"program.end"`, a Moment, or a Selection. Only with a Selection may
+you add `until-boundary="start" | "end"` to choose which edge of it ends the deck; the default is
+`end`, and giving the attribute in the other two cases is refused rather than ignored.
+
+### deck:Card
+
+A direct child of the stack, self-closing, at least one, and dealt in document order.
+
+| Attribute | Takes |
+|---|---|
+| `source` | required — a still image, a Synchronized Medium, or a Compositable Surface |
+| `extent` | required for a still image and refused for anything else |
+| `at` | required — the Moment the card is dealt on |
+| `appearance` | optional — its own Recipe, otherwise the stack's |
+| `label` | optional — a `deck:Label` record |
+
+### deck:Label
+
+`id` and `font` are required. The copy is either the `content=` reference or the element's own text —
+give both and it is refused. `size`, `color`, `align`, `block` and `padding` are optional.
+
+```svml
+<space:Frame id="deck-frame" within={vertical} left="44%" top="60%" right="98%" bottom="88%"/>
+<deck:DepthStack id="deck" map={timing.map} space={speech.space} canvas={vertical}
+ frame={deck-frame} appearance={studio.deck.stack} until={story.moment.done}>
+ <deck:Card id="card-spatial" source={icon-spatial} extent={square} at={story.moment.deal-one}/>
+ <deck:Card id="card-type" source={icon-type} extent={square} at={story.moment.deal-two}/>
+</deck:DepthStack>
+```
+
+**Output:** `{deck.track}` — a VisualTrack, an ordinary peer of every other Track in the Film.
+
+## Screen overlays
+
+Effects that cover the picture rather than sit in a Frame: a flash on a cut, a vignette that holds
+for a Selection, grain over the whole programme. One Track carries them all, and each child is one
+effect bound to its own window.
+
+```svml
+<import as="screen" from="@narratage/screen-overlay@1"/>
+```
+
+`screen:Track` takes `id`, `canvas` and `space`. Its children are the effects, at least one, each
+empty, each with a required `z` for stacking order and a window that is one of:
+
+| Window | Written |
+|---|---|
+| The whole programme | `during="program"` |
+| A Selection | `during={story.selection.x} map={timing.map}` |
+| A Moment, for a length | `at={story.moment.x} for="12f" map={timing.map}` |
+| An explicit span | `start="…" end="…"`, optionally against a `selection=` or `moment=` |
+
+Anything bound to the Script needs `map`; an explicit span with no Script source must not have one.
+Lengths are `12f`, `250ms` or `1.5s`, and `occurrences="each"` repeats an effect at every occurrence
+of its marker rather than the first.
+
+Eleven effects are available — `Flash`, `ColorWash`, `Vignette`, `ScanLines`, `DirectionalMatte`,
+`WhipVeil`, `GlitchVeil`, `Grain`, `LightLeak`, `Bokeh` and `TVStatic` — and each carries its own
+required attributes, such as `color` / `intensity` / `attack` / `hold` / `decay` on a `Flash`, or
+`center-x` / `center-y` / `radius-x` / `radius-y` / `softness` / `color` / `opacity` on a `Vignette`.
+None have defaults: an effect states its whole shape or is refused.
+
+```svml
+<screen:Track id="effects" space={speech.space} canvas={vertical}>
+ <screen:Flash during={story.selection.overlay} map={timing.map} z="80"
+ color="#ffffff" intensity="0.6" attack="2" hold="2" decay="6"/>
+</screen:Track>
+```
+
+**Output:** `{effects.track}` — a VisualTrack.
+
+## Comment stickers
+
+Social-style comment cards placed in a Frame: an avatar, an author, the comment itself, and an
+optional metadata line.
+
+```svml
+<import as="comment" from="@narratage/comment-sticker@1"/>
+```
+
+`comment:Style` is empty and takes `id`, `recipe` and `font`, all required. The recipe carries the
+card's whole appearance — background, border, radius, tail, avatar, the three text rows, and the
+enter/hold/exit motion — and every key has a default, so a recipe may set only what it changes.
+
+`comment:Track` takes `id`, `canvas` and `space`. It takes `map` only if one of its stickers binds to
+the Script, and giving `map` when none does is refused rather than ignored.
+
+`comment:Sticker` requires `id`, `frame` and `style`, and takes the same windows as a screen overlay
+above. Its copy is either the `comment=` attribute or the element's own text — both is refused. The
+optional `author`, `header` and `meta` each take a string or a Text reference, `avatar` takes an
+image, and there is no `z`: stacking order comes from the recipe's `stack-order`.
+
+```svml
+<comment:Style id="social" recipe={studio.comment} font={ui-font}/>
+<comment:Track id="comments" canvas={vertical} space={speech.space} map={timing.map}>
+ <comment:Sticker id="one" frame={comment-frame} style={social} avatar={viewer-avatar}
+ author="@viewer" meta="Featured" during={story.selection.reaction}>
+ Wait, it pinned the caption to the word, not the second.
+ </comment:Sticker>
+</comment:Track>
+```
+
+**Output:** `{comments.track}` — a VisualTrack.
+
## Combination example
All four track families together in one source file:
diff --git a/docs/zh/quickstart/images.md b/docs/zh/quickstart/images.md
new file mode 100644
index 00000000..a926dc8a
--- /dev/null
+++ b/docs/zh/quickstart/images.md
@@ -0,0 +1,89 @@
+---
+title: 图片操作
+description: 在图片流向生成器或 Track 之前,对它做合成、校正与抠图。
+---
+
+# 图片操作
+
+有三个包接收一张图片、交还一张图片。它们都不产出 Track:每个输出都是一张可供下游引用的图片——作为 Seedance 的参考帧、作为 Media Item,或作为下一次操作的来源。
+
+它们都需要 endpoint。`image-compose` 与 `image-transform` 索取 raster 能力,由 `@narratage/provider-image-opencv-local` 在你自己机器上以受限的 Python 进程运行 OpenCV 来满足;`background-removal` 索取的是它自己声明的能力,由 `@narratage/provider-kie` 远程满足。本仓库没有任何示例绑定过这两者,所以在 plan 一次用到它们的 Build 之前,先把 endpoint 加进你的 [Runtime Profile](/zh/guide/runtime-profile)。
+
+## 合成图层
+
+`compose:Image` 按书写顺序把各图层画到同一张画布上,交还一张 PNG。
+
+```svml
+<import as="compose" from="@narratage/image-compose@1"/>
+```
+
+元素接受 `id` 与 `canvas`,以及可选的 `background`——它必须带 alpha,写作 `#RRGGBBAA`,默认为完全透明。子元素是 `compose:Layer`,至少一个、至多六十四个,各自为空:
+
+| 属性 | 取值 |
+|---|---|
+| `source` | 必填——一张图片 |
+| `frame` | 必填——一个 `space:Frame` |
+| `fit` | 可选——`contain`(默认)、`cover` 或 `stretch` |
+| `interpolation` | 可选——`nearest`、`linear`、`cubic`、`area` 或 `lanczos`(默认) |
+| `opacity` | 可选——0 到 1,默认 1 |
+
+```svml
+<compose:Image id="card" canvas={portrait} background="#00000000">
+ <compose:Layer source={background.image} frame={full} fit="cover"/>
+ <compose:Layer source={product.image} frame={product-frame} fit="contain"/>
+</compose:Image>
+```
+
+**输出:** `{card.image}`——一张图片,不是 Track。
+
+## 校正图片
+
+`image:Program` 是一份具名的操作清单,`image:Transform` 把它作用在某个来源上。这样拆开是有意的:一份写好的 program 可以套用到每一个需要同样处理的镜头上。
+
+```svml
+<import as="image" from="@narratage/image-transform@1"/>
+```
+
+`image:Program` 只接受 `id`,操作以子元素形式书写,按书写顺序依次施加:
+
+| 操作 | 属性 |
+|---|---|
+| `Crop` | `x`、`y`、`width`、`height`;可选 `unit="fraction" \| "pixel"` |
+| `Resize` | `width`、`height`;可选 `fit`、`interpolation`、`background` |
+| `Rotate` | `degrees`,只能是 `90`、`180` 或 `270` |
+| `Flip` | 可选 `axis="horizontal" \| "vertical" \| "both"` |
+| `Denoise` | 可选 `luma`、`chroma`、`template-window`、`search-window`、`saturation-recovery` |
+| `Color` | 可选 `exposure-stops`、`contrast`、`saturation`、`temperature`、`tint`、`gamma` |
+| `Sharpen` | 可选 `amount`、`radius`、`threshold` |
+| `Blur` | `sigma` |
+| `Alpha` | 可选 `mode="preserve" \| "flatten"`;`flatten` 要求给出 `background`,`preserve` 则拒绝它 |
+| `Encode` | 可选 `format="png" \| "jpeg" \| "webp"`、`quality`、`background` |
+
+一份 program 至多只能有一个 `Encode`,且必须放在最后。除 `Blur`、`Rotate` 与 `Crop` 之外,每个操作都能仅凭默认值运行,所以 `<image:Denoise/>` 本身就是一条完整的指令。
+
+`image:Transform` 接受 `id`、`source` 与 `program`,全部必填。
+
+```svml
+<image:Program id="clean-gpt-image">
+ <image:Denoise/>
+ <image:Encode format="png"/>
+</image:Program>
+
+<image:Transform id="clean-shot" source={shot.image} program={clean-gpt-image}/>
+```
+
+**输出:** `{clean-shot.image}`。program 本身不产出任何图片——它是一份配方,在 `Transform` 中指名它才会真正运行。
+
+## 去除背景
+
+```svml
+<import as="remove" from="@narratage/background-removal@1"/>
+```
+
+`remove:Background` 必须为空,接受 `id` 与 `source`。它不挑选模型、阈值或存储——那是 endpoint 的事,不是 Source 的事。
+
+```svml
+<remove:Background id="cutout" source={portrait.image}/>
+```
+
+**输出:** `{cutout.image}`——通常喂给一个 Media Item,好让出镜者叠在画面上,而不是待在一个方框里。
diff --git a/docs/zh/quickstart/tracks.md b/docs/zh/quickstart/tracks.md
index 7bd1a7e9..fccb5dff 100644
--- a/docs/zh/quickstart/tracks.md
+++ b/docs/zh/quickstart/tracks.md
@@ -1,9 +1,9 @@
---
-title: 字幕、Media、Typography 与 Audio 轨道
+title: 轨道
description: 对等 Track 组件——字幕、媒体、排版与作者声明的音频。
---
-# 字幕、Media、Typography 与 Audio 轨道
+# 轨道
每个进入最终合成的视听内容都是一个对等的 **Track**。Track 是扁平的(无嵌套);视觉层的
z 轴顺序由 SVS 中的 `stack-order` 属性决定。本页介绍 Caption、Media、Typography 与 Audio
@@ -273,6 +273,157 @@ Run 时,继续使用内联 `P`/`Span`/`Break`。
**输出:**`{titles.track}` —— 添加到 `film:Film` 的 VisualTrack。
+## 榜单板
+
+榜单板让一份有序列表跟着 Script 动起来:在某个 Selection 期间出现,在 Moment 上移动,在另一个 Moment 上定格。四个变体共用同一套形状——一个容器、它专属的条目标签、以及它专属的样式标签。
+
+| 容器 | 条目 | 样式 |
+|---|---|---|
+| `ranking:TierBoard` | `ranking:TierItem` | `ranking:TierBoardStyle` |
+| `ranking:Column` | `ranking:ColumnItem` | `ranking:ColumnStyle` |
+| `ranking:TopThree` | `ranking:TopThreeItem` | `ranking:TopThreeStyle` |
+| `ranking:TypewriterList` | `ranking:TypewriterItem` | `ranking:TypewriterListStyle` |
+
+```svml
+<import as="ranking" from="@narratage/ranking@1"/>
+```
+
+### 样式标签
+
+标签必须为空,三个属性全部必填:`id`、`recipe`(一份 SVS Recipe)与 `font`(Font Stack 或字体产物)。Recipe 承载这块板自己的键——行、配色、动效——并且会按变体校验,把 Column 的 recipe 给 TierBoard 会被指名拒绝。
+
+### 容器标签
+
+| 属性 | 取值 |
+|---|---|
+| `map` | 安放词语的 Semantic Map |
+| `space` | Program Space |
+| `frame` | 一个 `space:Frame` |
+| `during` | 一个 Selection——板在此期间留在画面上 |
+| `triggers` | 一个 Moment——行在它上面移动 |
+| `terminal` | 一个 Moment——板在它上面定格 |
+| `style` | 对应的样式记录,且只接受本变体的 |
+| `title` | 仅 `TypewriterList` 有,且必填:字符串或 Text 引用 |
+| `appear-sound`、`move-sound` | 可选,Synchronized Media |
+
+`move-sound` 在 `TopThree` 上会被拒绝——它没有移动阶段。在 `TierBoard` 上它要求至少有一个 `entry="stage"` 的条目,在 `TypewriterList` 上要求至少有一个 `winner="true"`:声音没有可响之处是创作错误,而不是静默的空操作。
+
+### 条目标签
+
+每个变体只接受自己的那一种,至少一个,且 id 在同一块板内不可重复。
+
+- **`TierItem`** —— `tier`(必填,须与 recipe 中某一行的 id 对上)、`icon`(必填),可选 `entry="direct" | "stage"` 与 `stack`。行的文字来自 recipe,不写在标签上。
+- **`ColumnItem`** 与 **`TopThreeItem`** —— `label`(必填:字符串或 Text 引用),可选 `icon` 与 `stack`。`TopThree` 最多三条。
+- **`TypewriterItem`** —— 文案来自 `text=` 或元素自身的文字,二者取其一;可选 `winner="true"`、`stack`,以及 `emphasis-start` / `emphasis-end`,二者按字素计数且必须成对出现。
+
+```svml
+<ranking:ColumnStyle id="board-style" recipe={studio.ranking.board} font={ui-font}/>
+<ranking:Column id="board" map={timing.map} space={speech.space} frame={board-frame}
+ during={story.selection.board} triggers={story.moment.place} terminal={story.moment.done}
+ style={board-style}>
+ <ranking:ColumnItem id="row-regen" label="ReGen" icon={icon-regen}/>
+ <ranking:ColumnItem id="row-chatgpt" label="ChatGPT" icon={icon-chatgpt}/>
+ <ranking:ColumnItem id="row-remini" label="Remini" icon={icon-remini}/>
+</ranking:Column>
+```
+
+**输出:** `{board.visual}`——一条 VisualTrack。带了声音的板还会导出 `{board.audio}`,一条 AudioTrack;没有声音时就没有这个输出。
+
+## 卡片堆
+
+卡片堆按深度排布卡片:一张在最前,其余向后退去,每张新卡在一个 Moment 上发出。Media Item 是把一个镜头放进一个 Frame,而卡片堆是在同一个 Frame 里维持一叠并整体移动它们。
+
+```svml
+<import as="deck" from="@narratage/deck-track@1"/>
+```
+
+### deck:DepthStack
+
+`id`、`map`、`space`、`canvas`、`frame` 与 `appearance` 全部必填,`until` 同样必填——它说明什么结束这叠卡片:字面量 `"program.end"`、一个 Moment,或一个 Selection。只有在指向 Selection 时才可以再加 `until-boundary="start" | "end"` 来选择用它的哪一端结束,默认是 `end`;在另外两种情况下给出这个属性会被拒绝,而不是被忽略。
+
+### deck:Card
+
+DepthStack 的直接子元素,自闭合,至少一张,按书写顺序发出。
+
+| 属性 | 取值 |
+|---|---|
+| `source` | 必填——静态图片、Synchronized Medium 或 Compositable Surface |
+| `extent` | 静态图片必填,其余情况给了会被拒绝 |
+| `at` | 必填——这张卡发出的 Moment |
+| `appearance` | 可选——它自己的 Recipe,否则沿用整叠的 |
+| `label` | 可选——一条 `deck:Label` 记录 |
+
+### deck:Label
+
+`id` 与 `font` 必填。文案来自 `content=` 引用或元素自身的文字,两个都给会被拒绝。`size`、`color`、`align`、`block`、`padding` 可选。
+
+```svml
+<space:Frame id="deck-frame" within={vertical} left="44%" top="60%" right="98%" bottom="88%"/>
+<deck:DepthStack id="deck" map={timing.map} space={speech.space} canvas={vertical}
+ frame={deck-frame} appearance={studio.deck.stack} until={story.moment.done}>
+ <deck:Card id="card-spatial" source={icon-spatial} extent={square} at={story.moment.deal-one}/>
+ <deck:Card id="card-type" source={icon-type} extent={square} at={story.moment.deal-two}/>
+</deck:DepthStack>
+```
+
+**输出:** `{deck.track}`——一条 VisualTrack,与 Film 中其它每一条 Track 平级。
+
+## 屏幕叠加层
+
+覆盖在整个画面之上、而非落在某个 Frame 里的效果:切点上的一次闪白、持续整个 Selection 的暗角、铺满全片的颗粒。一条 Track 承载全部,每个子元素是一个效果加它自己的时间窗。
+
+```svml
+<import as="screen" from="@narratage/screen-overlay@1"/>
+```
+
+`screen:Track` 接受 `id`、`canvas` 与 `space`。它的子元素就是各个效果,至少一个,各自为空,都必须带 `z` 决定层叠顺序,并且各有一个时间窗,形式是以下之一:
+
+| 时间窗 | 写法 |
+|---|---|
+| 整个节目 | `during="program"` |
+| 一个 Selection | `during={story.selection.x} map={timing.map}` |
+| 一个 Moment,持续一段时长 | `at={story.moment.x} for="12f" map={timing.map}` |
+| 显式区间 | `start="…" end="…"`,可另外指定 `selection=` 或 `moment=` |
+
+凡是绑定到 Script 的都需要 `map`;不带 Script 来源的显式区间则不能给 `map`。时长写作 `12f`、`250ms` 或 `1.5s`,`occurrences="each"` 让效果在标记的每一次出现处重复,而不只是第一次。
+
+可用的效果有十一种——`Flash`、`ColorWash`、`Vignette`、`ScanLines`、`DirectionalMatte`、`WhipVeil`、`GlitchVeil`、`Grain`、`LightLeak`、`Bokeh` 与 `TVStatic`——每种各有自己的必填属性,例如 `Flash` 的 `color` / `intensity` / `attack` / `hold` / `decay`,或 `Vignette` 的 `center-x` / `center-y` / `radius-x` / `radius-y` / `softness` / `color` / `opacity`。它们都没有默认值:一个效果要么把自己的形状说全,要么被拒绝。
+
+```svml
+<screen:Track id="effects" space={speech.space} canvas={vertical}>
+ <screen:Flash during={story.selection.overlay} map={timing.map} z="80"
+ color="#ffffff" intensity="0.6" attack="2" hold="2" decay="6"/>
+</screen:Track>
+```
+
+**输出:** `{effects.track}`——一条 VisualTrack。
+
+## 评论贴纸
+
+放置在 Frame 中的社交风格评论卡:头像、作者、评论正文,以及可选的一行附注。
+
+```svml
+<import as="comment" from="@narratage/comment-sticker@1"/>
+```
+
+`comment:Style` 必须为空,接受 `id`、`recipe` 与 `font`,全部必填。Recipe 承载整张卡的外观——背景、描边、圆角、气泡尾、头像、三行文字,以及进入/停留/退出的动效——每个键都有默认值,所以一份 recipe 只需写它要改的部分。
+
+`comment:Track` 接受 `id`、`canvas` 与 `space`。只有当它的某张贴纸绑定到 Script 时才接受 `map`;没有任何贴纸绑定却给了 `map` 会被拒绝,而不是被忽略。
+
+`comment:Sticker` 必填 `id`、`frame` 与 `style`,时间窗与上面的屏幕叠加层相同。它的文案来自 `comment=` 属性或元素自身的文字,两个都给会被拒绝。可选的 `author`、`header` 与 `meta` 各接受字符串或 Text 引用,`avatar` 接受一张图片;这里没有 `z`,层叠顺序来自 recipe 的 `stack-order`。
+
+```svml
+<comment:Style id="social" recipe={studio.comment} font={ui-font}/>
+<comment:Track id="comments" canvas={vertical} space={speech.space} map={timing.map}>
+ <comment:Sticker id="one" frame={comment-frame} style={social} avatar={viewer-avatar}
+ author="@viewer" meta="Featured" during={story.selection.reaction}>
+ 原来它把字幕钉在词上,而不是钉在秒上。
+ </comment:Sticker>
+</comment:Track>
+```
+
+**输出:** `{comments.track}`——一条 VisualTrack。
+
## 组合示例
四类 Track 在一个源文件中协同使用: