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.

feat: establish shared track authoring foundations

kashorin4d714877aa44
diff --git a/docs/README.md b/docs/README.md
index 53649b7d..ab49a01a 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -41,6 +41,24 @@ the working tree contains only documents that should inform current implementati
- [`../spec/script-surface.md`](../spec/script-surface.md)
- [`../spec/author-surface-binding.md`](../spec/author-surface-binding.md)
- [`../spec/caption-program.md`](../spec/caption-program.md)
+- [`../spec/caption-fine.md`](../spec/caption-fine.md) — implemented first field-free Caption Style
+ family and its completed browser evidence.
+- [`../spec/track-authoring.md`](../spec/track-authoring.md) — shared package-authoring discipline;
+ the temporal projection and occurrence-expansion design governs the next Track migration.
+- [`../spec/spatial-layout.md`](../spec/spatial-layout.md) — shared Canvas/Frame/Point/Path geometry,
+ two-frame fitting, alignment and explicit backing-layer boundary.
+- [`../spec/text-track.md`](../spec/text-track.md) — complete two-dimensional Text model, old-system
+ and editor attack audit, terminal-IR gaps and Caption feedback.
+- [`../spec/ranking-track.md`](../spec/ranking-track.md) — old Ranking audit, separate official
+ components, triggered group schedule and renderer-neutral migration plan.
+- [`../spec/media-track.md`](../spec/media-track.md) — unified Item/Sequence media model, ordered
+ layers, playback, motion, internal handoffs, audio projection and Speech reuse.
+- [`../spec/deck-track.md`](../spec/deck-track.md) — independent depth-stack Deck Track, collection
+ state, visible neighborhood and deterministic whole-group reflow.
+- [`../spec/audio-track.md`](../spec/audio-track.md) — explicit normalized audio inputs, temporal
+ placement, sample occupancy, mixing boundary and old-system migration.
+- [`../spec/screen-overlay.md`](../spec/screen-overlay.md) — self-contained full-canvas visual
+ contributions and the hard boundary against cross-Track adjustment effects.
- [`../spec/track-composition.md`](../spec/track-composition.md)
- [`../spec/track-expressiveness.md`](../spec/track-expressiveness.md)
- [`../spec/visual-ir.md`](../spec/visual-ir.md)
diff --git a/docs/quickstart/composition.md b/docs/quickstart/composition.md
index c4a55756..5ed453fc 100644
--- a/docs/quickstart/composition.md
+++ b/docs/quickstart/composition.md
@@ -9,6 +9,7 @@ Film is the final assembly stage. It takes all peer Tracks, validates them, and
Composition. The renderer then compiles that Composition into an MP4 video.
```svml
+<import as="space" from="@narratage/spatial@1"/>
<import as="film" from="@narratage/film@1"/>
<import as="render" from="@narratage/render-hyperframes@1"/>
```
@@ -20,7 +21,8 @@ know what a caption is, what B-roll is, or what speech is. It takes any VisualTr
and layers them by stacking order.
```svml
-<film:Film id="main" space={speech.space} appearance={studio.film.vertical}>
+<space:Canvas id="vertical" width="1080" height="1920"/>
+<film:Film id="main" canvas={vertical} space={speech.space} appearance={studio.film.vertical}>
<film:Track source={speech.visual}/>
<film:Track source={speech.audioTrack}/>
<film:Track source={captions.track}/>
@@ -32,8 +34,9 @@ and layers them by stacking order.
| Attribute | Required | Description |
|---|---|---|
| `id` | yes | Unique identifier |
+| `canvas` | yes | Explicit CanvasSpace shared with Track layout |
| `space` | yes | ProgramSpace from `speech:Spine` — defines duration and frame rate |
-| `appearance` | yes | SVS film Recipe — canvas width, height, frame rate, background |
+| `appearance` | yes | SVS Film Recipe — the canvas clear color |
### film:Track
@@ -118,6 +121,7 @@ The complete data flow from Script to rendered video. This example is based on
<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="space" from="@narratage/spatial@1"/>
<import as="film" from="@narratage/film@1"/>
<import as="render" from="@narratage/render-hyperframes@1"/>
<import as="studio" source="./studio.svs"/>
@@ -157,13 +161,17 @@ The complete data flow from Script to rendered video. This example is based on
appearance={studio.broll.card}/>
</broll:Track>
+ <space:Canvas id="vertical" width="1080" height="1920"/>
+ <space:Frame id="title-frame" within={vertical}
+ left="6%" top="6%" right="6%" bottom="84%"/>
<text:Track id="titles" space={speech.space}>
<text:Item text="MEANING" during="full"
+ frame={title-frame}
appearance={studio.text.title}/>
</text:Track>
<!-- 5. Film: compose all tracks -->
- <film:Film id="main" space={speech.space}
+ <film:Film id="main" canvas={vertical} space={speech.space}
appearance={studio.film.vertical}>
<film:Track source={speech.visual}/>
<film:Track source={speech.audioTrack}/>
@@ -185,7 +193,7 @@ The complete data flow from Script to rendered video. This example is based on
<sheet version="1">
film.vertical {
- width: 1080; height: 1920; frame-rate: 30; background: #09090B;
+ background: #09090B;
}
broll.card {
stack-order: 40; x: 0.1; y: 0.2; width: 0.8; height: 0.5;
@@ -199,7 +207,7 @@ The complete data flow from Script to rendered video. This example is based on
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;
+ stack-order: 90;
font: Inter; weight: 900; size: 64; align: center;
fill: #FFFFFF; tracking: -1;
}
diff --git a/docs/quickstart/styles.md b/docs/quickstart/styles.md
index 385e98b9..4d7fb943 100644
--- a/docs/quickstart/styles.md
+++ b/docs/quickstart/styles.md
@@ -6,7 +6,7 @@ description: The SVS Recipe language — CSS-like stylesheets for film, caption,
# 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
+configure Film appearance, caption appearance, B-roll layout, text styling, speech estimation
parameters, generation settings, and typography choices. SVS values are called **Recipes** — they are
immutable typed Records that consuming components validate and interpret.
@@ -17,9 +17,6 @@ immutable typed Records that consuming components validate and interpret.
<sheet version="1" id="studio">
film.vertical {
- width: 1080;
- height: 1920;
- frame-rate: 30;
background: #09090B;
}
@@ -49,28 +46,24 @@ The prefix comes from the `as=` attribute; the path comes from `namespace.name`
## Film
-Film appearance — canvas dimensions and background color.
+Film appearance owns only the canvas clear color. Canvas dimensions are an explicit
+`space:Canvas` graph value, while frame rate comes from ProgramSpace.
```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}>
+<space:Canvas id="vertical" width="1080" height="1920"/>
+<film:Film id="main" canvas={vertical} space={speech.space} appearance={studio.film.vertical}>
```
## Caption Fine
@@ -199,15 +192,11 @@ Referenced by `broll:Item` via the `appearance` attribute:
## Text
-Text overlay appearance — position, typography.
+Text overlay appearance — typography and Paint. Placement is a separate `SpatialFrame` graph edge.
```svs
text.title {
stack-order: 90;
- x: 0.06;
- y: 0.06;
- width: 0.88;
- height: 0.10;
font: Inter;
weight: 900;
size: 64;
@@ -220,8 +209,6 @@ text.title {
| 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 |
@@ -232,7 +219,8 @@ text.title {
Referenced by `text:Item` via the `appearance` attribute:
```svml
-<text:Item text="MEANING" during="full" appearance={studio.text.title}/>
+<text:Item text="MEANING" during="full" frame={title-frame}
+ appearance={studio.text.title}/>
```
## Speech estimation
@@ -383,9 +371,6 @@ A complete `studio.svs` file for a four-take talking-head project:
}
film.vertical {
- width: 720;
- height: 1280;
- frame-rate: 30;
background: #09090B;
}
@@ -421,5 +406,6 @@ This file is imported once in the `.svml` source and its values are referenced t
<caption-fine:Style id="primary-caption" recipe={studio.caption.primary}/>
-<film:Film id="main" space={speech.space} appearance={studio.film.vertical}>
+<space:Canvas id="vertical" width="720" height="1280"/>
+<film:Film id="main" canvas={vertical} space={speech.space} appearance={studio.film.vertical}>
```
diff --git a/docs/quickstart/timing.md b/docs/quickstart/timing.md
index 94968d7d..f91cc789 100644
--- a/docs/quickstart/timing.md
+++ b/docs/quickstart/timing.md
@@ -86,7 +86,7 @@ ProgramSpace is not a component you declare — it is produced by `speech:Spine`
component that needs to know the total program duration and frame domain.
```svml
-<film:Film id="main" space={speech.space} ...>
+<film:Film id="main" canvas={vertical} space={speech.space} ...>
<caption-fine:Track id="captions" ... space={speech.space} .../>
<text:Track id="titles" space={speech.space}>
<render:Video id="final" composition={main.composition} space={speech.space}/>
diff --git a/docs/quickstart/tracks.md b/docs/quickstart/tracks.md
index 56b9b0fa..514f6d4c 100644
--- a/docs/quickstart/tracks.md
+++ b/docs/quickstart/tracks.md
@@ -5,6 +5,11 @@ description: Visual track components — captions, B-roll overlays and text over
# Caption, B-roll & Text
+> **Executable-slice note:** Caption Fine is the current complete package. The B-roll and Text
+> sections document today's executable vertical slices. Their intended replacement author models
+> are specified in `spec/media-track.md`, `spec/spatial-layout.md` and `spec/text-track.md`; examples
+> using those future Surfaces will replace these sections only after the packages execute.
+
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.
@@ -116,12 +121,15 @@ rules replace the whole Style on a Role or explicit Caption word subset, with th
<caption:Use role="BOB" style={bob-caption}/>
<caption:Use words={story.caption.selection.product-demo}
style={dialogue-caption}/>
+ <caption:Mute words={story.caption.selection.private}/>
</caption:Program>
```
`role=` is convenient author syntax for a word subset, not a temporal condition. `words=` consumes
the Caption-specific projection of a Script Selection; the public time Selection remains only a
pair of semantic anchors. Partial ownership of an indivisible Dual Text display word is rejected.
+`Mute` uses that same exact word projection, stays out of Gemini, and hides those complete Atoms
+after Cue planning without regrouping the Cue.
### caption-ai:Planner
@@ -242,8 +250,12 @@ Static or timed text displayed on screen — titles, callouts, lower thirds.
Container for text items.
```svml
+<space:Canvas id="vertical" width="1080" height="1920"/>
+<space:Frame id="title-frame" within={vertical}
+ left="6%" top="6%" right="6%" bottom="84%"/>
<text:Track id="titles" space={speech.space}>
<text:Item text="EDIT MEANING, NOT TIMELINES" during="full"
+ frame={title-frame}
appearance={studio.text.title}/>
</text:Track>
```
@@ -259,14 +271,16 @@ Container for text items.
Each item is a text string placed at a time position:
```svml
-<text:Item text="MEANING" during="full" appearance={studio.text.title}/>
+<text:Item text="MEANING" during="full" frame={title-frame}
+ 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 |
+| `frame` | yes | Explicit `SpatialFrame` defining placement and available layout area |
+| `appearance` | yes | SVS text Recipe — stacking, font, size and Paint |
The `during` attribute accepts either the literal string `"full"` for the entire program duration, or
a Selection reference for semantic timing:
@@ -275,6 +289,7 @@ a Selection reference for semantic timing:
<text:Track id="callout" space={speech.space} map={timing.map}>
<text:Item text="EXACTLY THE RIGHT MOMENT"
during={story.selection.callout}
+ frame={callout-frame}
appearance={studio.text.callout}/>
</text:Track>
```
@@ -291,6 +306,7 @@ All three track types together in one source file:
<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="space" from="@narratage/spatial@1"/>
<!-- Captions: primary style for all text -->
<caption-fine:Style id="base-caption" recipe={studio.caption.base}/>
@@ -306,13 +322,19 @@ All three track types together in one source file:
appearance={studio.broll.card}/>
</broll:Track>
+<!-- Shared placement is an explicit edge, separate from Text appearance. -->
+<space:Canvas id="vertical" width="1080" height="1920"/>
+<space:Frame id="title-frame" within={vertical}
+ left="6%" top="6%" right="6%" bottom="84%"/>
+
<!-- Text: persistent title overlay -->
<text:Track id="titles" space={speech.space}>
- <text:Item text="MEANING" during="full" appearance={studio.text.title}/>
+ <text:Item text="MEANING" during="full" frame={title-frame}
+ appearance={studio.text.title}/>
</text:Track>
<!-- All three tracks feed into Film -->
-<film:Film id="main" space={speech.space} appearance={studio.film.vertical}>
+<film:Film id="main" canvas={vertical} space={speech.space} appearance={studio.film.vertical}>
<film:Track source={speech.visual}/>
<film:Track source={speech.audioTrack}/>
<film:Track source={cards.visual}/>
diff --git a/docs/zh/quickstart/composition.md b/docs/zh/quickstart/composition.md
index 8fd1a057..8ed6847c 100644
--- a/docs/zh/quickstart/composition.md
+++ b/docs/zh/quickstart/composition.md
@@ -9,6 +9,7 @@ Film 是最终的组装阶段。它接收所有对等的 Track,对其进行验
Composition。然后渲染器将该 Composition 编译为 MP4 视频。
```svml
+<import as="space" from="@narratage/spatial@1"/>
<import as="film" from="@narratage/film@1"/>
<import as="render" from="@narratage/render-hyperframes@1"/>
```
@@ -19,7 +20,8 @@ Composition。然后渲染器将该 Composition 编译为 MP4 视频。
什么是 B-roll、什么是语音。它接收任何 VisualTrack 或 AudioTrack,并按堆叠顺序将它们分层。
```svml
-<film:Film id="main" space={speech.space} appearance={studio.film.vertical}>
+<space:Canvas id="vertical" width="1080" height="1920"/>
+<film:Film id="main" canvas={vertical} space={speech.space} appearance={studio.film.vertical}>
<film:Track source={speech.visual}/>
<film:Track source={speech.audioTrack}/>
<film:Track source={captions.track}/>
@@ -31,8 +33,9 @@ Composition。然后渲染器将该 Composition 编译为 MP4 视频。
| 属性 | 必填 | 说明 |
|---|---|---|
| `id` | 是 | 唯一标识符 |
+| `canvas` | 是 | 与 Track 布局共享的显式 CanvasSpace |
| `space` | 是 | 来自 `speech:Spine` 的 ProgramSpace——定义时长和帧率 |
-| `appearance` | 是 | SVS Film Recipe——画布宽度、高度、帧率、背景 |
+| `appearance` | 是 | SVS Film Recipe——画布清除颜色 |
### film:Track
@@ -115,6 +118,7 @@ Track 是**扁平的**——没有嵌套或分组。Z 轴排序完全由每个 T
<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="space" from="@narratage/spatial@1"/>
<import as="film" from="@narratage/film@1"/>
<import as="render" from="@narratage/render-hyperframes@1"/>
<import as="studio" source="./studio.svs"/>
@@ -154,13 +158,17 @@ Track 是**扁平的**——没有嵌套或分组。Z 轴排序完全由每个 T
appearance={studio.broll.card}/>
</broll:Track>
+ <space:Canvas id="vertical" width="1080" height="1920"/>
+ <space:Frame id="title-frame" within={vertical}
+ left="6%" top="6%" right="6%" bottom="84%"/>
<text:Track id="titles" space={speech.space}>
<text:Item text="MEANING" during="full"
+ frame={title-frame}
appearance={studio.text.title}/>
</text:Track>
<!-- 5. Film: compose all tracks -->
- <film:Film id="main" space={speech.space}
+ <film:Film id="main" canvas={vertical} space={speech.space}
appearance={studio.film.vertical}>
<film:Track source={speech.visual}/>
<film:Track source={speech.audioTrack}/>
@@ -182,7 +190,7 @@ Track 是**扁平的**——没有嵌套或分组。Z 轴排序完全由每个 T
<sheet version="1">
film.vertical {
- width: 1080; height: 1920; frame-rate: 30; background: #09090B;
+ background: #09090B;
}
broll.card {
stack-order: 40; x: 0.1; y: 0.2; width: 0.8; height: 0.5;
@@ -196,7 +204,7 @@ Track 是**扁平的**——没有嵌套或分组。Z 轴排序完全由每个 T
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;
+ stack-order: 90;
font: Inter; weight: 900; size: 64; align: center;
fill: #FFFFFF; tracking: -1;
}
diff --git a/docs/zh/quickstart/styles.md b/docs/zh/quickstart/styles.md
index 088725be..584d9966 100644
--- a/docs/zh/quickstart/styles.md
+++ b/docs/zh/quickstart/styles.md
@@ -14,9 +14,6 @@ SVS(`.svs`)文件使用类 CSS 语法定义可复用的类型化配置值。
<sheet version="1" id="studio">
film.vertical {
- width: 1080;
- height: 1920;
- frame-rate: 30;
background: #09090B;
}
@@ -45,28 +42,24 @@ SVS(`.svs`)文件使用类 CSS 语法定义可复用的类型化配置值。
## Film
-Film 外观——画布尺寸和背景颜色。
+Film 外观只拥有画布清除颜色。画布尺寸是显式的 `space:Canvas` 图值,帧率来自
+ProgramSpace。
```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}>
+<space:Canvas id="vertical" width="1080" height="1920"/>
+<film:Film id="main" canvas={vertical} space={speech.space} appearance={studio.film.vertical}>
```
## Caption Fine
@@ -195,15 +188,11 @@ broll.product {
## 文本
-文本叠加层外观——位置、排版。
+文本叠加层外观——排版与 Paint。位置由另一条 `SpatialFrame` 图边提供。
```svs
text.title {
stack-order: 90;
- x: 0.06;
- y: 0.06;
- width: 0.88;
- height: 0.10;
font: Inter;
weight: 900;
size: 64;
@@ -216,8 +205,6 @@ text.title {
| 属性 | 描述 |
|---|---|
| `stack-order` | Z 轴层叠顺序 |
-| `x`、`y` | 位置,以画布比例表示 |
-| `width`、`height` | 尺寸,以画布比例表示 |
| `font` | 字体族名称 |
| `weight` | 字体粗细 |
| `size` | 字体大小(像素) |
@@ -228,7 +215,8 @@ text.title {
通过 `text:Item` 的 `appearance` 属性引用:
```svml
-<text:Item text="MEANING" during="full" appearance={studio.text.title}/>
+<text:Item text="MEANING" during="full" frame={title-frame}
+ appearance={studio.text.title}/>
```
## 语音估算
@@ -377,9 +365,6 @@ Recipe 的环境字体兜底名,适合原型,但不能保证字节级复现
}
film.vertical {
- width: 720;
- height: 1280;
- frame-rate: 30;
background: #09090B;
}
@@ -415,5 +400,6 @@ Recipe 的环境字体兜底名,适合原型,但不能保证字节级复现
<caption-fine:Style id="primary-caption" recipe={studio.caption.primary}/>
-<film:Film id="main" space={speech.space} appearance={studio.film.vertical}>
+<space:Canvas id="vertical" width="720" height="1280"/>
+<film:Film id="main" canvas={vertical} space={speech.space} appearance={studio.film.vertical}>
```
diff --git a/docs/zh/quickstart/timing.md b/docs/zh/quickstart/timing.md
index 07ac37e6..fbef90db 100644
--- a/docs/zh/quickstart/timing.md
+++ b/docs/zh/quickstart/timing.md
@@ -78,7 +78,7 @@ SemanticMap 将每个 Script 中标注的锚点映射到一个时间点。它覆
ProgramSpace 不是一个需要声明的组件——它由 `speech:Spine` 产生,并传递给每个需要知道总节目时长和帧域的组件。
```svml
-<film:Film id="main" space={speech.space} ...>
+<film:Film id="main" canvas={vertical} space={speech.space} ...>
<caption-fine:Track id="captions" ... space={speech.space} .../>
<text:Track id="titles" space={speech.space}>
<render:Video id="final" composition={main.composition} space={speech.space}/>
diff --git a/docs/zh/quickstart/tracks.md b/docs/zh/quickstart/tracks.md
index c1c8c16e..214983b6 100644
--- a/docs/zh/quickstart/tracks.md
+++ b/docs/zh/quickstart/tracks.md
@@ -5,6 +5,10 @@ description: 视觉 Track 组件——字幕、B-roll 叠加层和文字叠加
# 字幕、B-roll 与文字
+> **当前可执行切片:** Caption Fine 已完整实现。B-roll 与文字章节描述的是今天仍可运行的
+> 纵向切片;它们的目标模型分别记录在 `spec/media-track.md`、`spec/spatial-layout.md` 与
+> `spec/text-track.md`。只有对应新包真正可运行后,教程才会改用新语法。
+
每个进入最终合成的视听内容都是一个对等的 **Track**。Track 是扁平的(无嵌套),其 z 轴顺序由 SVS 中的 `stack-order` 属性决定。本页介绍三种主要的视觉 Track 类型:字幕、B-roll 和文字叠加层。
## 字幕系统
@@ -87,11 +91,14 @@ Program 消费 Script 显式输出的完整有序显示词全集。一个必填
<caption:Use role="BOB" style={bob-caption}/>
<caption:Use words={story.caption.selection.product-demo}
style={dialogue-caption}/>
+ <caption:Mute words={story.caption.selection.private}/>
</caption:Program>
```
`role=` 是词子集查询的作者语法,不是时间条件。`words=` 接收 Selection 的字幕专用
词投影;通用 Selection 的公开值仍只有语义首尾锚点。
+`Mute` 消费同一份精确词投影,不进入 Gemini;它在 Cue 规划完成后隐藏这些完整 Atom,
+既不重新分 Cue,也不把字幕可见性变成 Core 的通用时间遮罩。
### caption-ai:Planner
@@ -209,8 +216,12 @@ B-roll 搭配生成的 Seedance 视频,在 Script Selection 期间出现:
文字项目的容器。
```svml
+<space:Canvas id="vertical" width="1080" height="1920"/>
+<space:Frame id="title-frame" within={vertical}
+ left="6%" top="6%" right="6%" bottom="84%"/>
<text:Track id="titles" space={speech.space}>
<text:Item text="EDIT MEANING, NOT TIMELINES" during="full"
+ frame={title-frame}
appearance={studio.text.title}/>
</text:Track>
```
@@ -226,14 +237,16 @@ B-roll 搭配生成的 Seedance 视频,在 Script Selection 期间出现:
每个项目是放置在某个时间位置的一段文本字符串:
```svml
-<text:Item text="MEANING" during="full" appearance={studio.text.title}/>
+<text:Item text="MEANING" during="full" frame={title-frame}
+ appearance={studio.text.title}/>
```
| 属性 | 必填 | 描述 |
|---|---|---|
| `text` | 是 | 要显示的文本字符串 |
| `during` | 是 | 何时显示:`"full"`(整个节目时长)或 Selection 引用 |
-| `appearance` | 是 | SVS 文字 Recipe——位置、字体、大小、颜色 |
+| `frame` | 是 | 显式 `SpatialFrame`,定义位置和可用排版区域 |
+| `appearance` | 是 | SVS 文字 Recipe——层级、字体、大小与 Paint |
`during` 属性接受字面字符串 `"full"`(表示整个节目时长),或 Selection 引用(用于语义计时):
@@ -241,6 +254,7 @@ B-roll 搭配生成的 Seedance 视频,在 Script Selection 期间出现:
<text:Track id="callout" space={speech.space} map={timing.map}>
<text:Item text="EXACTLY THE RIGHT MOMENT"
during={story.selection.callout}
+ frame={callout-frame}
appearance={studio.text.callout}/>
</text:Track>
```
@@ -257,6 +271,7 @@ B-roll 搭配生成的 Seedance 视频,在 Script Selection 期间出现:
<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="space" from="@narratage/spatial@1"/>
<!-- Captions: primary style for all text -->
<caption-fine:Style id="base-caption" recipe={studio.caption.base}/>
@@ -272,13 +287,19 @@ B-roll 搭配生成的 Seedance 视频,在 Script Selection 期间出现:
appearance={studio.broll.card}/>
</broll:Track>
+<!-- 共享位置是显式边,与 Text 外观分开。 -->
+<space:Canvas id="vertical" width="1080" height="1920"/>
+<space:Frame id="title-frame" within={vertical}
+ left="6%" top="6%" right="6%" bottom="84%"/>
+
<!-- Text: persistent title overlay -->
<text:Track id="titles" space={speech.space}>
- <text:Item text="MEANING" during="full" appearance={studio.text.title}/>
+ <text:Item text="MEANING" during="full" frame={title-frame}
+ appearance={studio.text.title}/>
</text:Track>
<!-- All three tracks feed into Film -->
-<film:Film id="main" space={speech.space} appearance={studio.film.vertical}>
+<film:Film id="main" canvas={vertical} space={speech.space} appearance={studio.film.vertical}>
<film:Track source={speech.visual}/>
<film:Track source={speech.audioTrack}/>
<film:Track source={cards.visual}/>
diff --git a/examples/talking-film-golden/main.svml b/examples/talking-film-golden/main.svml
index cb8679a6..62d4d41e 100644
--- a/examples/talking-film-golden/main.svml
+++ b/examples/talking-film-golden/main.svml
@@ -17,6 +17,7 @@
<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="space" from="@narratage/spatial@1"/>
<import as="film" from="@narratage/film@1"/>
<import as="render" from="@narratage/render-hyperframes@1"/>
<import as="studio" source="./studio.svs"/>
@@ -136,16 +137,21 @@
plan={caption-plan.plan}
/>
+ <space:Canvas id="vertical" width="1080" height="1920"/>
+ <space:Frame id="title-frame" within={vertical}
+ left="6%" top="6%" right="6%" bottom="84%"/>
+
<text:Track id="titles" space={speech.space}>
<text:Item
text="EDIT MEANING, NOT TIMELINES"
during="full"
+ frame={title-frame}
appearance={studio.text.title}
/>
</text:Track>
<!-- Child order is organizational. Every Present carries its own absolute stack position. -->
- <film:Film id="main" space={speech.space} appearance={studio.film.vertical}>
+ <film:Film id="main" canvas={vertical} space={speech.space} appearance={studio.film.vertical}>
<film:Track source={speech.visual}/>
<film:Track source={speech.audioTrack}/>
<film:Track source={product-broll.visual}/>
diff --git a/examples/talking-film-golden/studio.svs b/examples/talking-film-golden/studio.svs
index 403e35a1..2f645be1 100644
--- a/examples/talking-film-golden/studio.svs
+++ b/examples/talking-film-golden/studio.svs
@@ -16,9 +16,6 @@
}
film.vertical {
- width: 1080;
- height: 1920;
- frame-rate: 30;
background: #09090B;
}
@@ -106,10 +103,6 @@
text.title {
stack-order: 90;
- x: 0.06;
- y: 0.06;
- width: 0.88;
- height: 0.10;
font: inter-black;
weight: 900;
size: 64;
diff --git a/examples/talking-film-graph-check/main.svml b/examples/talking-film-graph-check/main.svml
index 39da298c..3b3f09d1 100644
--- a/examples/talking-film-graph-check/main.svml
+++ b/examples/talking-film-graph-check/main.svml
@@ -10,6 +10,7 @@
<import as="caption-fine" from="@narratage/caption-fine@1"/>
<import as="caption-ai" from="@narratage/caption-gemini@1"/>
<import as="text" from="@narratage/text-track@1"/>
+ <import as="space" from="@narratage/spatial@1"/>
<import as="film" from="@narratage/film@1"/>
<import as="render" from="@narratage/render-hyperframes@1"/>
<import as="studio" source="./studio.svs"/>
@@ -37,11 +38,15 @@
<caption-fine:Track id="captions" display={story.caption} correspondence={story.caption.correspondence}
map={timing.map} space={speech.space}
plan={cue-plan.plan} program={caption-program}/>
+ <space:Canvas id="vertical" width="1080" height="1920"/>
+ <space:Frame id="title-frame" within={vertical}
+ left="6%" top="6%" right="6%" bottom="84%"/>
<text:Track id="titles" space={speech.space}>
- <text:Item text="MEANING" during="full" appearance={studio.text.title}/>
+ <text:Item text="MEANING" during="full" frame={title-frame}
+ appearance={studio.text.title}/>
</text:Track>
- <film:Film id="main" space={speech.space} appearance={studio.film.vertical}>
+ <film:Film id="main" canvas={vertical} space={speech.space} appearance={studio.film.vertical}>
<film:Track source={speech.visual}/>
<film:Track source={speech.audioTrack}/>
<film:Track source={cards.visual}/>
diff --git a/examples/talking-film-graph-check/studio.svs b/examples/talking-film-graph-check/studio.svs
index 9d3e30eb..e37174c6 100644
--- a/examples/talking-film-graph-check/studio.svs
+++ b/examples/talking-film-graph-check/studio.svs
@@ -1,7 +1,7 @@
<?svml using="@narratage/svs@1"?>
<sheet version="1">
- film.vertical { width: 1080; height: 1920; frame-rate: 30; background: #09090B; }
+ film.vertical { 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;
@@ -18,7 +18,7 @@
cue-enter: fade; cue-enter-frames: 4; cue-exit: fade; cue-exit-frames: 4;
}
text.title {
- stack-order: 90; x: 0.06; y: 0.06; width: 0.88; height: 0.1; font: Inter;
+ stack-order: 90; font: Inter;
weight: 900; size: 64; align: center; fill: #FFFFFF; tracking: -1;
}
</sheet>
diff --git a/examples/talking-film-graph-check/svml.packages.lock b/examples/talking-film-graph-check/svml.packages.lock
index 06c598e7..d559f33b 100644
--- a/examples/talking-film-graph-check/svml.packages.lock
+++ b/examples/talking-film-graph-check/svml.packages.lock
@@ -14,17 +14,17 @@
{
"name": "@narratage/caption-fine",
"version": "0.0.0-dev",
- "digest": "sha256:1dbfb8e75d745ccda9d6e086fa360ab458b19acd51f6b14214a52819bd0703b8"
+ "digest": "sha256:eff4590782f030b3e5c2d7d16c073943d1563d122db53f48f1c89e67e25811ce"
},
{
"name": "@narratage/caption-gemini",
"version": "0.0.0-dev",
- "digest": "sha256:418af81230bf3ac8a7e307484b6098f283575bbae0b18a94cb525c3b52ce26e8"
+ "digest": "sha256:9744f6fee5bb6f69c232ca1dcff1db21e20f5d5e28257dae1944d70e5358a6bd"
},
{
"name": "@narratage/caption",
"version": "0.0.0-dev",
- "digest": "sha256:3a569665a5bc60fde2f049786f76928e0729b4fd723c91a38d568014f53cdbb1"
+ "digest": "sha256:6c33baaaee4cb439cd2a0592504bc29a1f7cfc3fa3c663820637fb45e6523991"
},
{
"name": "@narratage/component-kit",
@@ -54,7 +54,7 @@
{
"name": "@narratage/film",
"version": "0.0.0-dev",
- "digest": "sha256:c847365263d42a5136daeac728188dfabb00b9ad4dac669682022d33e7d8f997"
+ "digest": "sha256:f17a912d29b69f86c35becc31c50d2ef7d9421a7c7acdb53f68be35aabb84b78"
},
{
"name": "@narratage/generation",
@@ -136,6 +136,11 @@
"version": "0.0.0-dev",
"digest": "sha256:8bbfa48c0fde45639578902c907d9190bd5bbb8a03bd59fca8fd364b820a3184"
},
+ {
+ "name": "@narratage/spatial",
+ "version": "0.0.0-dev",
+ "digest": "sha256:6ca15f348ffb032d9862aa4f476ff7910e26e23017f459d7502ddd71bfd1a940"
+ },
{
"name": "@narratage/speech-alignment",
"version": "0.0.0-dev",
@@ -164,12 +169,17 @@
{
"name": "@narratage/svs",
"version": "0.0.0-dev",
- "digest": "sha256:8973ec01d5c9390da4e5a3f74c7e5af0a4bb49e15796e98e748b75ce62363d9d"
+ "digest": "sha256:6054e6dc0fed6195e881ba3d980eed86b33168252b1f38757618343c41e76898"
+ },
+ {
+ "name": "@narratage/temporal",
+ "version": "0.0.0-dev",
+ "digest": "sha256:86f27c2e4dde016f871c404b603a41adb0b551913163eb7ff00ad969e7296886"
},
{
"name": "@narratage/text-track",
"version": "0.0.0-dev",
- "digest": "sha256:03f9bdfb00df7dabbf196e48bdd56c8a581079fbdd2fb7c97ef0df0d4096fdc5"
+ "digest": "sha256:54b31088b141e2cbce6201314433ed3a048d6a4f3fd7b4d204dcfd64bf0fa52d"
},
{
"name": "@narratage/text",
@@ -209,7 +219,7 @@
"version": "0.0.0-dev"
},
"facetsDigest": "sha256:29d590f5b5b125db139773046ce48eba938c675f39ed2b1cdda7e24bff1ea75a",
- "closureDigest": "sha256:2ff3c105fc9d1117bc5f9bde39ffd12fc4cb69764ffaa77022e37ba4d105963f"
+ "closureDigest": "sha256:0e66298d657de9705e2fd4ff6807f9f840a133c182698c4428b9071b32375a67"
},
{
"specifier": "@narratage/caption",
@@ -217,8 +227,8 @@
"name": "@narratage/caption",
"version": "0.0.0-dev"
},
- "facetsDigest": "sha256:73dfafd232af1ba279fc9d2cb4715ad7518a697f97d5279b4b88a1f3ee24eb19",
- "closureDigest": "sha256:0bf34edc64b304226c0d59faa5853bdbc729083a660f1f3214c0e484a689f049"
+ "facetsDigest": "sha256:453e1a9e707850357a1d076387b11e4e70e416ebbed1e220817519dec3467344",
+ "closureDigest": "sha256:4e6159cbb484bc3ff42aded8655b6f48680ccfd35cbc4a0b5a7703f90ad31187"
},
{
"specifier": "@narratage/caption-fine",
@@ -226,8 +236,8 @@
"name": "@narratage/caption-fine",
"version": "0.0.0-dev"
},
- "facetsDigest": "sha256:4eb6e1dbde32fe5090c4080749f3903072ce7d7725c52785f7d03563aa7c9a59",
- "closureDigest": "sha256:ee3ea312a961632c3af80daeefe087125fc97055ac92b92edc9563a5a0e9ab4e"
+ "facetsDigest": "sha256:d88c93d7dd955581dc4137a65e32a4ae1cf22b7c4ee2cbbb496b8b9f71325f4b",
+ "closureDigest": "sha256:3f2310ac164d73aae783b6f1e2d41483c1417bf75cb44c35e1d1c6fe64da4a17"
},
{
"specifier": "@narratage/caption-gemini",
@@ -235,8 +245,8 @@
"name": "@narratage/caption-gemini",
"version": "0.0.0-dev"
},
- "facetsDigest": "sha256:83573766921453a6961390645bad28929d7ebec400cb9aae00e6b4ca83e94ac3",
- "closureDigest": "sha256:da5c121fc168e08ac6d09b214de405bad045f624c1aac29be92b1ed128c34108"
+ "facetsDigest": "sha256:9d363283f203fcac1403ab88927c0232a1000dc1db330faee9e40ce63bd250fb",
+ "closureDigest": "sha256:39f07b712f705487e17af373879c949d4c795ea29b437be49d5bf0d2038bf55e"
},
{
"specifier": "@narratage/composition",
@@ -254,7 +264,7 @@
"version": "0.0.0-dev"
},
"facetsDigest": "sha256:195e4840e8238866ccd6ae9362e990e124bf69de41fba71758436f1959609fbb",
- "closureDigest": "sha256:5d3bfee43e26aff29f07cefa8a6cde83ce36af4dc185e1c9d2578886d5cb88d8"
+ "closureDigest": "sha256:323a82a2db80e6ba21178dd278e4a391552bcb0cb54d3bb54eb699e5cf1adfd9"
},
{
"specifier": "@narratage/film",
@@ -262,8 +272,8 @@
"name": "@narratage/film",
"version": "0.0.0-dev"
},
- "facetsDigest": "sha256:78df513364725a6434b44b349d834dd5f754cf3da53036ed90aca62c38fd2bbc",
- "closureDigest": "sha256:24eaafd5632206142f0a037973b33421c68d0890fa251d683ea1a25f07b2e481"
+ "facetsDigest": "sha256:efee0fdfbfe306cac9a4d79122c69b594bb3e56e040ec618481ea638da97013c",
+ "closureDigest": "sha256:b61b788768b556160cddb481c35e1535d91f9d5e9337deb0506dbfa6afe422dd"
},
{
"specifier": "@narratage/generation",
@@ -364,6 +374,15 @@
"facetsDigest": "sha256:0935b3fde2040ca370ba47b09da4ac7285067709cbf77885b01b74a02ed1765f",
"closureDigest": "sha256:c5ec936affa7d20bdeb1e3f57f691c10f60a885bda1b1335325c7b6bdb98b818"
},
+ {
+ "specifier": "@narratage/spatial",
+ "package": {
+ "name": "@narratage/spatial",
+ "version": "0.0.0-dev"
+ },
+ "facetsDigest": "sha256:1a3004524c7cdb09be7c84dfdfac577a7e133b7f7b6e6c2301298aaad91053aa",
+ "closureDigest": "sha256:beff3382fe5d2d7a237644a524b4dcca409ccf8da04100e64f0340f84506f395"
+ },
{
"specifier": "@narratage/speech",
"package": {
@@ -416,7 +435,7 @@
"version": "0.0.0-dev"
},
"facetsDigest": "sha256:9cc7c397d2cd97b5a3e814886b6553b6d236fd8825df0d056e328b7f0cf20163",
- "closureDigest": "sha256:1e341927d7c9efe75a372b7e87681891a30127f426e040597458614e60d4b810"
+ "closureDigest": "sha256:6acbe73fe544447499f51bb74ee3c6e1d67ba34cbef12a33bbee8b34f8a1bc49"
},
{
"specifier": "@narratage/text-track",
@@ -424,8 +443,8 @@
"name": "@narratage/text-track",
"version": "0.0.0-dev"
},
- "facetsDigest": "sha256:956cb6d53a1db24e822af86b24cdaa0054d7daadc3828ace40fa6497a9fa5e68",
- "closureDigest": "sha256:0b5eaf76d1a3109826da9427a2dd431364f6903f7b16431224839e5a07e9c66b"
+ "facetsDigest": "sha256:54dd6c09b7e39090ac844d681228b2043018851684be40fbcde8ee7c6e378484",
+ "closureDigest": "sha256:517db51a395163ab01aa23642940154f1d109a1f7af56f1bb53fbe01cfb26dfb"
},
{
"specifier": "@narratage/visual-ir",
@@ -446,5 +465,5 @@
"closureDigest": "sha256:747dda39abd4c81eba23f4db6be19698dfe653517bdd1fc7b9896a3839bbda3f"
}
],
- "digest": "sha256:f90f463681d78c06d1885b0edcf10c855cd1ae9935aba7af4d31d83d64b1c403"
+ "digest": "sha256:800eeda337d08eaa7cdd3199c1f83a63c7e28ae00dbaf2e35770b20b6be01dc1"
}
diff --git a/examples/talking-film-live/main.svml b/examples/talking-film-live/main.svml
index d935ea55..8ae24a72 100644
--- a/examples/talking-film-live/main.svml
+++ b/examples/talking-film-live/main.svml
@@ -11,6 +11,7 @@
<import as="caption-fine" from="@narratage/caption-fine@1"/>
<import as="caption-ai" from="@narratage/caption-gemini@1"/>
<import as="text" from="@narratage/text-track@1"/>
+ <import as="space" from="@narratage/spatial@1"/>
<import as="film" from="@narratage/film@1"/>
<import as="render" from="@narratage/render-hyperframes@1"/>
<import as="studio" source="./studio.svs"/>
@@ -109,15 +110,20 @@
plan={caption-plan.plan}
/>
+ <space:Canvas id="vertical" width="480" height="854"/>
+ <space:Frame id="callout-frame" within={vertical}
+ left="8%" top="10%" right="8%" bottom="80%"/>
+
<text:Track id="callout" space={speech.space} map={timing.map}>
<text:Item
text="EXACTLY THE RIGHT MOMENT"
during={story.selection.callout}
+ frame={callout-frame}
appearance={studio.text.callout}
/>
</text:Track>
- <film:Film id="main" space={speech.space} appearance={studio.film.vertical}>
+ <film:Film id="main" canvas={vertical} space={speech.space} appearance={studio.film.vertical}>
<film:Track source={speech.visual}/>
<film:Track source={speech.audioTrack}/>
<film:Track source={captions.track}/>
diff --git a/examples/talking-film-live/studio.svs b/examples/talking-film-live/studio.svs
index 14d8a859..0309ef40 100644
--- a/examples/talking-film-live/studio.svs
+++ b/examples/talking-film-live/studio.svs
@@ -2,9 +2,6 @@
<sheet version="1">
film.vertical {
- width: 480;
- height: 854;
- frame-rate: 30;
background: #09090B;
}
@@ -28,10 +25,6 @@
text.callout {
stack-order: 85;
- x: 0.08;
- y: 0.10;
- width: 0.84;
- height: 0.10;
font: Inter;
weight: 900;
size: 27;
diff --git a/examples/talking-film-live/svml.packages.lock b/examples/talking-film-live/svml.packages.lock
index e82842dc..bbd3c8ec 100644
--- a/examples/talking-film-live/svml.packages.lock
+++ b/examples/talking-film-live/svml.packages.lock
@@ -9,17 +9,17 @@
{
"name": "@narratage/caption-fine",
"version": "0.0.0-dev",
- "digest": "sha256:1dbfb8e75d745ccda9d6e086fa360ab458b19acd51f6b14214a52819bd0703b8"
+ "digest": "sha256:eff4590782f030b3e5c2d7d16c073943d1563d122db53f48f1c89e67e25811ce"
},
{
"name": "@narratage/caption-gemini",
"version": "0.0.0-dev",
- "digest": "sha256:418af81230bf3ac8a7e307484b6098f283575bbae0b18a94cb525c3b52ce26e8"
+ "digest": "sha256:9744f6fee5bb6f69c232ca1dcff1db21e20f5d5e28257dae1944d70e5358a6bd"
},
{
"name": "@narratage/caption",
"version": "0.0.0-dev",
- "digest": "sha256:3a569665a5bc60fde2f049786f76928e0729b4fd723c91a38d568014f53cdbb1"
+ "digest": "sha256:6c33baaaee4cb439cd2a0592504bc29a1f7cfc3fa3c663820637fb45e6523991"
},
{
"name": "@narratage/component-kit",
@@ -49,7 +49,7 @@
{
"name": "@narratage/film",
"version": "0.0.0-dev",
- "digest": "sha256:c847365263d42a5136daeac728188dfabb00b9ad4dac669682022d33e7d8f997"
+ "digest": "sha256:f17a912d29b69f86c35becc31c50d2ef7d9421a7c7acdb53f68be35aabb84b78"
},
{
"name": "@narratage/generation",
@@ -131,6 +131,11 @@
"version": "0.0.0-dev",
"digest": "sha256:8bbfa48c0fde45639578902c907d9190bd5bbb8a03bd59fca8fd364b820a3184"
},
+ {
+ "name": "@narratage/spatial",
+ "version": "0.0.0-dev",
+ "digest": "sha256:6ca15f348ffb032d9862aa4f476ff7910e26e23017f459d7502ddd71bfd1a940"
+ },
{
"name": "@narratage/speech-alignment",
"version": "0.0.0-dev",
@@ -159,12 +164,17 @@
{
"name": "@narratage/svs",
"version": "0.0.0-dev",
- "digest": "sha256:8973ec01d5c9390da4e5a3f74c7e5af0a4bb49e15796e98e748b75ce62363d9d"
+ "digest": "sha256:6054e6dc0fed6195e881ba3d980eed86b33168252b1f38757618343c41e76898"
+ },
+ {
+ "name": "@narratage/temporal",
+ "version": "0.0.0-dev",
+ "digest": "sha256:86f27c2e4dde016f871c404b603a41adb0b551913163eb7ff00ad969e7296886"
},
{
"name": "@narratage/text-track",
"version": "0.0.0-dev",
- "digest": "sha256:03f9bdfb00df7dabbf196e48bdd56c8a581079fbdd2fb7c97ef0df0d4096fdc5"
+ "digest": "sha256:54b31088b141e2cbce6201314433ed3a048d6a4f3fd7b4d204dcfd64bf0fa52d"
},
{
"name": "@narratage/text",
@@ -203,8 +213,8 @@
"name": "@narratage/caption",
"version": "0.0.0-dev"
},
- "facetsDigest": "sha256:73dfafd232af1ba279fc9d2cb4715ad7518a697f97d5279b4b88a1f3ee24eb19",
- "closureDigest": "sha256:0bf34edc64b304226c0d59faa5853bdbc729083a660f1f3214c0e484a689f049"
+ "facetsDigest": "sha256:453e1a9e707850357a1d076387b11e4e70e416ebbed1e220817519dec3467344",
+ "closureDigest": "sha256:4e6159cbb484bc3ff42aded8655b6f48680ccfd35cbc4a0b5a7703f90ad31187"
},
{
"specifier": "@narratage/caption-fine",
@@ -212,8 +222,8 @@
"name": "@narratage/caption-fine",
"version": "0.0.0-dev"
},
- "facetsDigest": "sha256:4eb6e1dbde32fe5090c4080749f3903072ce7d7725c52785f7d03563aa7c9a59",
- "closureDigest": "sha256:ee3ea312a961632c3af80daeefe087125fc97055ac92b92edc9563a5a0e9ab4e"
+ "facetsDigest": "sha256:d88c93d7dd955581dc4137a65e32a4ae1cf22b7c4ee2cbbb496b8b9f71325f4b",
+ "closureDigest": "sha256:3f2310ac164d73aae783b6f1e2d41483c1417bf75cb44c35e1d1c6fe64da4a17"
},
{
"specifier": "@narratage/caption-gemini",
@@ -221,8 +231,8 @@
"name": "@narratage/caption-gemini",
"version": "0.0.0-dev"
},
- "facetsDigest": "sha256:83573766921453a6961390645bad28929d7ebec400cb9aae00e6b4ca83e94ac3",
- "closureDigest": "sha256:da5c121fc168e08ac6d09b214de405bad045f624c1aac29be92b1ed128c34108"
+ "facetsDigest": "sha256:9d363283f203fcac1403ab88927c0232a1000dc1db330faee9e40ce63bd250fb",
+ "closureDigest": "sha256:39f07b712f705487e17af373879c949d4c795ea29b437be49d5bf0d2038bf55e"
},
{
"specifier": "@narratage/composition",
@@ -240,7 +250,7 @@
"version": "0.0.0-dev"
},
"facetsDigest": "sha256:195e4840e8238866ccd6ae9362e990e124bf69de41fba71758436f1959609fbb",
- "closureDigest": "sha256:5d3bfee43e26aff29f07cefa8a6cde83ce36af4dc185e1c9d2578886d5cb88d8"
+ "closureDigest": "sha256:323a82a2db80e6ba21178dd278e4a391552bcb0cb54d3bb54eb699e5cf1adfd9"
},
{
"specifier": "@narratage/film",
@@ -248,8 +258,8 @@
"name": "@narratage/film",
"version": "0.0.0-dev"
},
- "facetsDigest": "sha256:78df513364725a6434b44b349d834dd5f754cf3da53036ed90aca62c38fd2bbc",
- "closureDigest": "sha256:24eaafd5632206142f0a037973b33421c68d0890fa251d683ea1a25f07b2e481"
+ "facetsDigest": "sha256:efee0fdfbfe306cac9a4d79122c69b594bb3e56e040ec618481ea638da97013c",
+ "closureDigest": "sha256:b61b788768b556160cddb481c35e1535d91f9d5e9337deb0506dbfa6afe422dd"
},
{
"specifier": "@narratage/generation",
@@ -350,6 +360,15 @@
"facetsDigest": "sha256:0935b3fde2040ca370ba47b09da4ac7285067709cbf77885b01b74a02ed1765f",
"closureDigest": "sha256:c5ec936affa7d20bdeb1e3f57f691c10f60a885bda1b1335325c7b6bdb98b818"
},
+ {
+ "specifier": "@narratage/spatial",
+ "package": {
+ "name": "@narratage/spatial",
+ "version": "0.0.0-dev"
+ },
+ "facetsDigest": "sha256:1a3004524c7cdb09be7c84dfdfac577a7e133b7f7b6e6c2301298aaad91053aa",
+ "closureDigest": "sha256:beff3382fe5d2d7a237644a524b4dcca409ccf8da04100e64f0340f84506f395"
+ },
{
"specifier": "@narratage/speech",
"package": {
@@ -402,7 +421,7 @@
"version": "0.0.0-dev"
},
"facetsDigest": "sha256:9cc7c397d2cd97b5a3e814886b6553b6d236fd8825df0d056e328b7f0cf20163",
- "closureDigest": "sha256:1e341927d7c9efe75a372b7e87681891a30127f426e040597458614e60d4b810"
+ "closureDigest": "sha256:6acbe73fe544447499f51bb74ee3c6e1d67ba34cbef12a33bbee8b34f8a1bc49"
},
{
"specifier": "@narratage/text-track",
@@ -410,8 +429,8 @@
"name": "@narratage/text-track",
"version": "0.0.0-dev"
},
- "facetsDigest": "sha256:956cb6d53a1db24e822af86b24cdaa0054d7daadc3828ace40fa6497a9fa5e68",
- "closureDigest": "sha256:0b5eaf76d1a3109826da9427a2dd431364f6903f7b16431224839e5a07e9c66b"
+ "facetsDigest": "sha256:54dd6c09b7e39090ac844d681228b2043018851684be40fbcde8ee7c6e378484",
+ "closureDigest": "sha256:517db51a395163ab01aa23642940154f1d109a1f7af56f1bb53fbe01cfb26dfb"
},
{
"specifier": "@narratage/visual-ir",
@@ -432,5 +451,5 @@
"closureDigest": "sha256:747dda39abd4c81eba23f4db6be19698dfe653517bdd1fc7b9896a3839bbda3f"
}
],
- "digest": "sha256:64160099ccdc7eca13febaf148f2398e73ccf1d317c5c6b6d88871b8ac79c278"
+ "digest": "sha256:58a17736766cf221b419200451180c1a9e2baca7a9f91ccf41b4100799a20dfa"
}
diff --git a/examples/talking-head-aroll/main.svml b/examples/talking-head-aroll/main.svml
index 04284064..db69de2a 100644
--- a/examples/talking-head-aroll/main.svml
+++ b/examples/talking-head-aroll/main.svml
@@ -10,6 +10,7 @@
<import as="caption" from="@narratage/caption@1"/>
<import as="caption-fine" from="@narratage/caption-fine@1"/>
<import as="caption-ai" from="@narratage/caption-gemini@1"/>
+ <import as="space" from="@narratage/spatial@1"/>
<import as="film" from="@narratage/film@1"/>
<import as="render" from="@narratage/render-hyperframes@1"/>
<import as="studio" source="./studio.svs"/>
@@ -122,7 +123,8 @@
plan={caption-plan.plan}
/>
- <film:Film id="main" space={speech.space} appearance={studio.film.vertical}>
+ <space:Canvas id="vertical" width="720" height="1280"/>
+ <film:Film id="main" canvas={vertical} space={speech.space} appearance={studio.film.vertical}>
<film:Track source={speech.visual}/>
<film:Track source={speech.audioTrack}/>
<film:Track source={captions.track}/>
diff --git a/examples/talking-head-aroll/studio.svs b/examples/talking-head-aroll/studio.svs
index bc935e45..1341ccff 100644
--- a/examples/talking-head-aroll/studio.svs
+++ b/examples/talking-head-aroll/studio.svs
@@ -25,9 +25,6 @@
}
film.vertical {
- width: 720;
- height: 1280;
- frame-rate: 30;
background: #09090B;
}
diff --git a/examples/talking-head-aroll/svml.packages.lock b/examples/talking-head-aroll/svml.packages.lock
index 68fc9a59..309ab1a1 100644
--- a/examples/talking-head-aroll/svml.packages.lock
+++ b/examples/talking-head-aroll/svml.packages.lock
@@ -9,17 +9,17 @@
{
"name": "@narratage/caption-fine",
"version": "0.0.0-dev",
- "digest": "sha256:1dbfb8e75d745ccda9d6e086fa360ab458b19acd51f6b14214a52819bd0703b8"
+ "digest": "sha256:eff4590782f030b3e5c2d7d16c073943d1563d122db53f48f1c89e67e25811ce"
},
{
"name": "@narratage/caption-gemini",
"version": "0.0.0-dev",
- "digest": "sha256:418af81230bf3ac8a7e307484b6098f283575bbae0b18a94cb525c3b52ce26e8"
+ "digest": "sha256:9744f6fee5bb6f69c232ca1dcff1db21e20f5d5e28257dae1944d70e5358a6bd"
},
{
"name": "@narratage/caption",
"version": "0.0.0-dev",
- "digest": "sha256:3a569665a5bc60fde2f049786f76928e0729b4fd723c91a38d568014f53cdbb1"
+ "digest": "sha256:6c33baaaee4cb439cd2a0592504bc29a1f7cfc3fa3c663820637fb45e6523991"
},
{
"name": "@narratage/component-kit",
@@ -49,7 +49,7 @@
{
"name": "@narratage/film",
"version": "0.0.0-dev",
- "digest": "sha256:c847365263d42a5136daeac728188dfabb00b9ad4dac669682022d33e7d8f997"
+ "digest": "sha256:f17a912d29b69f86c35becc31c50d2ef7d9421a7c7acdb53f68be35aabb84b78"
},
{
"name": "@narratage/generation",
@@ -141,6 +141,11 @@
"version": "0.0.0-dev",
"digest": "sha256:8bbfa48c0fde45639578902c907d9190bd5bbb8a03bd59fca8fd364b820a3184"
},
+ {
+ "name": "@narratage/spatial",
+ "version": "0.0.0-dev",
+ "digest": "sha256:6ca15f348ffb032d9862aa4f476ff7910e26e23017f459d7502ddd71bfd1a940"
+ },
{
"name": "@narratage/speech-alignment",
"version": "0.0.0-dev",
@@ -169,7 +174,7 @@
{
"name": "@narratage/svs",
"version": "0.0.0-dev",
- "digest": "sha256:8973ec01d5c9390da4e5a3f74c7e5af0a4bb49e15796e98e748b75ce62363d9d"
+ "digest": "sha256:6054e6dc0fed6195e881ba3d980eed86b33168252b1f38757618343c41e76898"
},
{
"name": "@narratage/text",
@@ -208,8 +213,8 @@
"name": "@narratage/caption",
"version": "0.0.0-dev"
},
- "facetsDigest": "sha256:73dfafd232af1ba279fc9d2cb4715ad7518a697f97d5279b4b88a1f3ee24eb19",
- "closureDigest": "sha256:0bf34edc64b304226c0d59faa5853bdbc729083a660f1f3214c0e484a689f049"
+ "facetsDigest": "sha256:453e1a9e707850357a1d076387b11e4e70e416ebbed1e220817519dec3467344",
+ "closureDigest": "sha256:4e6159cbb484bc3ff42aded8655b6f48680ccfd35cbc4a0b5a7703f90ad31187"
},
{
"specifier": "@narratage/caption-fine",
@@ -217,8 +222,8 @@
"name": "@narratage/caption-fine",
"version": "0.0.0-dev"
},
- "facetsDigest": "sha256:4eb6e1dbde32fe5090c4080749f3903072ce7d7725c52785f7d03563aa7c9a59",
- "closureDigest": "sha256:ee3ea312a961632c3af80daeefe087125fc97055ac92b92edc9563a5a0e9ab4e"
+ "facetsDigest": "sha256:d88c93d7dd955581dc4137a65e32a4ae1cf22b7c4ee2cbbb496b8b9f71325f4b",
+ "closureDigest": "sha256:3f2310ac164d73aae783b6f1e2d41483c1417bf75cb44c35e1d1c6fe64da4a17"
},
{
"specifier": "@narratage/caption-gemini",
@@ -226,8 +231,8 @@
"name": "@narratage/caption-gemini",
"version": "0.0.0-dev"
},
- "facetsDigest": "sha256:83573766921453a6961390645bad28929d7ebec400cb9aae00e6b4ca83e94ac3",
- "closureDigest": "sha256:da5c121fc168e08ac6d09b214de405bad045f624c1aac29be92b1ed128c34108"
+ "facetsDigest": "sha256:9d363283f203fcac1403ab88927c0232a1000dc1db330faee9e40ce63bd250fb",
+ "closureDigest": "sha256:39f07b712f705487e17af373879c949d4c795ea29b437be49d5bf0d2038bf55e"
},
{
"specifier": "@narratage/composition",
@@ -245,7 +250,7 @@
"version": "0.0.0-dev"
},
"facetsDigest": "sha256:195e4840e8238866ccd6ae9362e990e124bf69de41fba71758436f1959609fbb",
- "closureDigest": "sha256:5d3bfee43e26aff29f07cefa8a6cde83ce36af4dc185e1c9d2578886d5cb88d8"
+ "closureDigest": "sha256:323a82a2db80e6ba21178dd278e4a391552bcb0cb54d3bb54eb699e5cf1adfd9"
},
{
"specifier": "@narratage/film",
@@ -253,8 +258,8 @@
"name": "@narratage/film",
"version": "0.0.0-dev"
},
- "facetsDigest": "sha256:78df513364725a6434b44b349d834dd5f754cf3da53036ed90aca62c38fd2bbc",
- "closureDigest": "sha256:24eaafd5632206142f0a037973b33421c68d0890fa251d683ea1a25f07b2e481"
+ "facetsDigest": "sha256:efee0fdfbfe306cac9a4d79122c69b594bb3e56e040ec618481ea638da97013c",
+ "closureDigest": "sha256:b61b788768b556160cddb481c35e1535d91f9d5e9337deb0506dbfa6afe422dd"
},
{
"specifier": "@narratage/generation",
@@ -317,7 +322,7 @@
"version": "0.0.0-dev"
},
"facetsDigest": "sha256:f04988c69c3b953fd02c4c791bf542bff61464c6aa593f49c71347cc03a422f9",
- "closureDigest": "sha256:0be6f17010ebfe3fd8d4c4bdd386b78ab1274dde9573c047f68f7f36b2c2e70a"
+ "closureDigest": "sha256:f22b35cfa7f59979b371df9f08f720732c744be8c992224da094749cc6a1bb87"
},
{
"specifier": "@narratage/render-hyperframes",
@@ -362,7 +367,7 @@
"version": "0.0.0-dev"
},
"facetsDigest": "sha256:af969a55984b7ebe51faa77b446bca2ab6403a214a1ba6f4a23e6ac82e1901a4",
- "closureDigest": "sha256:ad5579d4078403ec4baa3e8930a6c037cd707ae96bf61482b25580183f0db1e9"
+ "closureDigest": "sha256:b30255b77c98ccf3823880b484a9dfc5a35e15800ab1f3bcd4a4f195b5061991"
},
{
"specifier": "@narratage/semantic-map",
@@ -373,6 +378,15 @@
"facetsDigest": "sha256:0935b3fde2040ca370ba47b09da4ac7285067709cbf77885b01b74a02ed1765f",
"closureDigest": "sha256:c5ec936affa7d20bdeb1e3f57f691c10f60a885bda1b1335325c7b6bdb98b818"
},
+ {
+ "specifier": "@narratage/spatial",
+ "package": {
+ "name": "@narratage/spatial",
+ "version": "0.0.0-dev"
+ },
+ "facetsDigest": "sha256:1a3004524c7cdb09be7c84dfdfac577a7e133b7f7b6e6c2301298aaad91053aa",
+ "closureDigest": "sha256:beff3382fe5d2d7a237644a524b4dcca409ccf8da04100e64f0340f84506f395"
+ },
{
"specifier": "@narratage/speech",
"package": {
@@ -425,7 +439,7 @@
"version": "0.0.0-dev"
},
"facetsDigest": "sha256:9cc7c397d2cd97b5a3e814886b6553b6d236fd8825df0d056e328b7f0cf20163",
- "closureDigest": "sha256:1e341927d7c9efe75a372b7e87681891a30127f426e040597458614e60d4b810"
+ "closureDigest": "sha256:6acbe73fe544447499f51bb74ee3c6e1d67ba34cbef12a33bbee8b34f8a1bc49"
},
{
"specifier": "@narratage/visual-ir",
@@ -446,5 +460,5 @@
"closureDigest": "sha256:747dda39abd4c81eba23f4db6be19698dfe653517bdd1fc7b9896a3839bbda3f"
}
],
- "digest": "sha256:18a9f1f0b8cae9165dbb880d6f13ed2c14206caa5fb90c639719bc7ea2512d39"
+ "digest": "sha256:f1734754956b8e58a39b0572c2eab9f7edc224a1e850bf2b2e4c041c103790f3"
}
diff --git a/package.json b/package.json
index e433d94f..c2512aed 100644
--- a/package.json
+++ b/package.json
@@ -60,6 +60,8 @@
"@narratage/speech-spine": "workspace:*",
"@narratage/svs": "workspace:*",
"@narratage/text-track": "workspace:*",
+ "@narratage/temporal": "workspace:*",
+ "@narratage/spatial": "workspace:*",
"@narratage/visual-ir": "workspace:*",
"@narratage/whisperx": "workspace:*",
"@types/node": "24.10.1",
diff --git a/packages/caption-fine/src/render.ts b/packages/caption-fine/src/render.ts
index 05967b6e..ffda0a88 100644
--- a/packages/caption-fine/src/render.ts
+++ b/packages/caption-fine/src/render.ts
@@ -1,4 +1,4 @@
-import { assertCaptionProgramForDisplay, assertTimedCaptionProjection } from "@narratage/caption";
+import { applyCaptionMute, assertCaptionProgramForDisplay, assertTimedCaptionProjection } from "@narratage/caption";
import type { CaptionProgram, TimedCaptionProjection } from "@narratage/caption";
import { assertVisualTrackIdentity, sealVisualTrack } from "@narratage/composition";
import type {
@@ -24,7 +24,7 @@ import type {
FineCaptionUnderline,
} from "./types.js";
-export const renderFineCaptionImplementationDigest = digestOf("@narratage/caption-fine/full-orthogonal-renderer@1");
+export const renderFineCaptionImplementationDigest = digestOf("@narratage/caption-fine/full-orthogonal-renderer-with-mute@1");
function frameAt(space: ProgramSpace, seconds: number): number {
return Math.round(seconds * space.frameRate.numerator / space.frameRate.denominator);
@@ -661,6 +661,7 @@ export function renderFineCaption(
assertTimedCaptionProjection(projection);
assertCaptionProgramForDisplay(program, display);
if (projection.displaySequenceId !== display.id) throw new Error("Fine Caption received another display sequence");
+ const visibleProjection = applyCaptionMute(projection, program, display);
assertProgramSpaceIdentity(space);
const styles = new Map(program.styles.map((style) => [style.id, style]));
const wordText = new Map(display.words.map((word) => [word.id, word.text]));
@@ -672,7 +673,7 @@ export function renderFineCaption(
assertFineCaptionParameters(style.rendering.parameters as unknown as FineCaptionParameters);
}
const totalFrames = programSpaceFrameCount(space);
- const presents = projection.cues.flatMap((cue) => {
+ const presents = visibleProjection.cues.flatMap((cue) => {
const atoms = cue.atoms.map((timing) => atomById.get(timing.atomId));
if (atoms.some((atom) => atom === undefined)) throw new Error(`Fine Caption Cue ${cue.id} references unknown Atom`);
const resolvedAtoms = atoms.map((atom) => atom!);
diff --git a/packages/caption-fine/test/caption-fine.test.ts b/packages/caption-fine/test/caption-fine.test.ts
index c5d33965..4c762b7c 100644
--- a/packages/caption-fine/test/caption-fine.test.ts
+++ b/packages/caption-fine/test/caption-fine.test.ts
@@ -77,6 +77,88 @@ test("one Fine renderer handles uniform Cue appearance as one peer VisualTrack",
assert.equal(fineCaptionParameters(recipe).activePaint.fill, "#FFD54A");
});
+test("Fine applies Caption Mute after planning without regrouping Cues", () => {
+ const narrative = parseScript("mute.svml", "<line>Keep hidden words visible.</line>");
+ const display = captionDisplaySequence(narrative, "story.caption");
+ const style = fineCaptionStyle("primary", recipe);
+ const muted = display.words.slice(1, 3);
+ const program = resolveCaptionProgram(display, "captions", style, [], [{
+ id: "hide-middle",
+ words: {
+ contract: "svml.caption-display-word-subset@1",
+ id: "selection:hide-middle",
+ sequenceId: display.id,
+ wordIds: muted.map((word) => word.id),
+ },
+ }]);
+ const projection: TimedCaptionProjection = {
+ contract: "svml.timed-caption-projection@1",
+ displaySequenceId: display.id,
+ cues: [{
+ id: "cue:1",
+ runId: program.runs[0]!.id,
+ styleId: style.id,
+ segmentId: "line",
+ startSec: 0,
+ endSec: 2,
+ atoms: display.atoms.map((atom, index) => ({
+ atomId: atom.id,
+ startSec: index * 0.4,
+ endSec: index * 0.4 + 0.3,
+ })),
+ fields: [],
+ }],
+ };
+ const space = sealProgramSpace({
+ contract: "svml.program-space@1",
+ durationSec: 2,
+ frameRate: { numerator: 30, denominator: 1 },
+ });
+
+ const track = renderFineCaption(projection, program, display, space);
+ assert.equal(track.presents.length, 1);
+ assert.deepEqual(track.presents[0]!.span, { startFrame: 0, endFrameExclusive: 60 });
+ const renderedWords = track.presents[0]!.elements
+ .filter((element) => element.kind === "text")
+ .map((element) => element.kind === "text" ? element.text : undefined);
+ assert.deepEqual(renderedWords, ["Keep", "visible."]);
+});
+
+test("Fine emits no Present for a fully muted Cue", () => {
+ const narrative = parseScript("mute-all.svml", "<line>Hide everything.</line>");
+ const display = captionDisplaySequence(narrative, "story.caption");
+ const style = fineCaptionStyle("primary", recipe);
+ const program = resolveCaptionProgram(display, "captions", style, [], [{
+ id: "hide-all",
+ words: {
+ contract: "svml.caption-display-word-subset@1",
+ id: "all",
+ sequenceId: display.id,
+ wordIds: display.words.map((word) => word.id),
+ },
+ }]);
+ const projection: TimedCaptionProjection = {
+ contract: "svml.timed-caption-projection@1",
+ displaySequenceId: display.id,
+ cues: [{
+ id: "cue:1",
+ runId: program.runs[0]!.id,
+ styleId: style.id,
+ segmentId: "line",
+ startSec: 0,
+ endSec: 1,
+ atoms: display.atoms.map((atom) => ({ atomId: atom.id, startSec: 0, endSec: 1 })),
+ fields: [],
+ }],
+ };
+ const track = renderFineCaption(projection, program, display, sealProgramSpace({
+ contract: "svml.program-space@1",
+ durationSec: 1,
+ frameRate: { numerator: 30, denominator: 1 },
+ }));
+ assert.deepEqual(track.presents, []);
+});
+
test("Fine resolves the complete orthogonal Paint, anchor, karaoke and motion surface", () => {
const parameters = fineCaptionParameters({
...recipe,
diff --git a/packages/caption-gemini/test/planning.test.ts b/packages/caption-gemini/test/planning.test.ts
index 8ed268ab..4103bc38 100644
--- a/packages/caption-gemini/test/planning.test.ts
+++ b/packages/caption-gemini/test/planning.test.ts
@@ -122,6 +122,27 @@ test("a field-free Style requires only Cue boundaries", () => {
request.runs[0]!.atoms.map((atom) => atom.id));
});
+test("Caption Mute stays out of Gemini while muted Atoms remain in the immutable plan", () => {
+ const parsed = parseScript("mute.svml", "<line>Keep this private phrase in the authored plan.</line>");
+ const display = captionDisplaySequence(parsed, "story.caption");
+ const muted = display.words.slice(2, 4);
+ const program = resolveCaptionProgram(display, "captions", style("fine"), [], [{
+ id: "private",
+ words: {
+ contract: "svml.caption-display-word-subset@1",
+ id: "selection:private",
+ sequenceId: display.id,
+ wordIds: muted.map((word) => word.id),
+ },
+ }]);
+ const request = compileCaptionGeminiRequest(display, program, options());
+
+ assert.deepEqual(request.runs.flatMap((run) => run.atoms.flatMap((atom) => atom.words.map((word) => word.id))),
+ display.words.map((word) => word.id));
+ assert.equal(request.prompt.includes("mutedWordIds"), false);
+ assert.equal(request.prompt.includes("visibility"), false);
+});
+
test("one Word may carry multiple independent field assignments", () => {
const parsed = parseScript("multi.svml", "<line>one two three four five.</line>");
const display = captionDisplaySequence(parsed, "story.caption");
diff --git a/packages/caption/README.md b/packages/caption/README.md
index 47ef9ebd..8817c37d 100644
--- a/packages/caption/README.md
+++ b/packages/caption/README.md
@@ -18,9 +18,14 @@ Runtime policy.
<caption:Program id="captions" display={story.caption} default={plain}>
<caption:Use role="ALICE" style={impact}/>
<caption:Use words={story.caption.selection.special} style={plain}/>
+ <caption:Mute words={story.caption.selection.private}/>
</caption:Program>
```
+`Mute` is a post-planning whole-Atom visibility rule. It does not change Script truth, Gemini
+input, Cue cuts, semantic timing, or Core. The common Caption timing join omits those Atoms from
+the timed visual projection while preserving each surviving Cue's original identity and span.
+
The default covers all display Words. Ordered `Use` rules replace whole Styles; later matches win.
No rule may split a multiword Atom. `role=` is author-surface sugar for an explicit display-word
subset, not a second time-range language.
diff --git a/packages/caption/src/index.ts b/packages/caption/src/index.ts
index 34d1e511..41573b39 100644
--- a/packages/caption/src/index.ts
+++ b/packages/caption/src/index.ts
@@ -30,6 +30,6 @@ export {
sealCaptionProgram,
sealCaptionStyle,
} from "./style.js";
-export type { CaptionStyleApplication } from "./style.js";
-export { assertTimedCaptionProjection, temporalizeCaptionPlan } from "./temporalize.js";
+export type { CaptionMuteApplication, CaptionStyleApplication } from "./style.js";
+export { applyCaptionMute, assertTimedCaptionProjection, temporalizeCaptionPlan } from "./temporalize.js";
export type * from "./types.js";
diff --git a/packages/caption/src/manifest.ts b/packages/caption/src/manifest.ts
index 0e26bda3..cf753f3c 100644
--- a/packages/caption/src/manifest.ts
+++ b/packages/caption/src/manifest.ts
@@ -13,14 +13,14 @@ export const captionTypes = {
plan: { module: captionModuleRef, name: "CaptionPlan" },
timedProjection: { module: captionModuleRef, name: "TimedCaptionProjection" },
} satisfies Record<string, TypeRef>;
-export const captionPlanImplementationDigest = digestOf("@narratage/caption/temporalize-whole-atoms-plan@1");
+export const captionPlanImplementationDigest = digestOf("@narratage/caption/temporalize-whole-atoms-with-mute@1");
export const captionValidatorDigests = {
style: digestOf("@narratage/caption/validate-style@1"),
- program: digestOf("@narratage/caption/validate-display-program@1"),
+ program: digestOf("@narratage/caption/validate-display-program-with-mute@1"),
plan: digestOf("@narratage/caption/validate-atom-plan@1"),
timedProjection: digestOf("@narratage/caption/validate-timed-atoms@1"),
} as const;
-export const captionProgramSurfaceImplementationDigest = digestOf("@narratage/caption/display-program-surface@1");
+export const captionProgramSurfaceImplementationDigest = digestOf("@narratage/caption/display-program-surface-with-mute@1");
const string = { kind: "string", minLength: 1 } as const;
const number = { kind: "number", minimum: 0 } as const;
@@ -58,7 +58,7 @@ const timedCaptionCue = object({
export const timedCaptionProjectionSchema: ValueSchema = object({
contract: { schema: { kind: "literal", value: "svml.timed-caption-projection@1" } },
displaySequenceId: { schema: string },
- cues: { schema: { kind: "array", minItems: 1, items: timedCaptionCue } },
+ cues: { schema: { kind: "array", items: timedCaptionCue } },
});
const captionFieldValueSchema: ValueSchema = {
@@ -99,6 +99,7 @@ export const captionProgramSchema: ValueSchema = object({
id: { schema: string }, displaySequenceId: { schema: string }, defaultStyleId: { schema: string },
styles: { schema: { kind: "array", minItems: 1, items: captionStyleSchema } },
runs: { schema: { kind: "array", minItems: 1, items: captionProgramRun } },
+ mutedWordIds: { schema: { kind: "array", items: string } },
});
export const captionManifest: ModuleManifest = {
diff --git a/packages/caption/src/style.ts b/packages/caption/src/style.ts
index 28f59363..519b6d25 100644
--- a/packages/caption/src/style.ts
+++ b/packages/caption/src/style.ts
@@ -18,6 +18,11 @@ export type CaptionStyleApplication = {
readonly style: CaptionStyleIntent;
};
+export type CaptionMuteApplication = {
+ readonly id: string;
+ readonly words: CaptionDisplayWordSubset;
+};
+
const ID = /^[A-Za-z][A-Za-z0-9_.-]{0,127}$/u;
function assert(condition: unknown, message: string): asserts condition {
@@ -123,6 +128,10 @@ export function assertCaptionProgram(value: CaptionProgram): void {
assert(new Set(planned).size === planned.length, "Caption Program runs repeat a display word");
assert(value.runs.every((run) => styles.has(run.styleId) && run.wordIds.length > 0),
"Caption Program run style is invalid");
+ assert(Array.isArray(value.mutedWordIds)
+ && value.mutedWordIds.every((wordId) => typeof wordId === "string" && wordId.length > 0)
+ && new Set(value.mutedWordIds).size === value.mutedWordIds.length,
+ "Caption Program muted display words are invalid or repeated");
}
/** Bind a Program's immutable display universe to the exact Script-produced sequence. */
@@ -132,6 +141,12 @@ export function assertCaptionProgramForDisplay(value: CaptionProgram, sequence:
assert(value.displaySequenceId === sequence.id
&& value.runs.flatMap((run) => run.wordIds).join("\0") === sequence.words.map((word) => word.id).join("\0"),
"Caption Program does not partition its CaptionDisplaySequence exactly once and in order");
+ assertCaptionDisplayWordSubset({
+ contract: "svml.caption-display-word-subset@1",
+ id: `${value.id}:mute`,
+ sequenceId: sequence.id,
+ wordIds: value.mutedWordIds,
+ }, sequence);
const runByWord = new Map(value.runs.flatMap((run) => run.wordIds.map((id) => [id, run.id] as const)));
for (const atom of sequence.atoms) {
assert(new Set(atom.wordIds.map((id) => runByWord.get(id))).size === 1,
@@ -145,6 +160,7 @@ export function resolveCaptionProgram(
id: string,
defaultStyle: CaptionStyleIntent,
applications: readonly CaptionStyleApplication[],
+ mutes: readonly CaptionMuteApplication[] = [],
): CaptionProgram {
assertCaptionDisplaySequence(sequence);
assertCaptionStyle(defaultStyle);
@@ -154,6 +170,11 @@ export function resolveCaptionProgram(
assertCaptionDisplayWordSubset(application.words, sequence);
assert(application.words.wordIds.length > 0, `Caption application ${application.id} selects no visible display word`);
});
+ mutes.forEach((mute) => {
+ assert(ID.test(mute.id), "Caption Mute identity is invalid");
+ assertCaptionDisplayWordSubset(mute.words, sequence);
+ assert(mute.words.wordIds.length > 0, `Caption Mute ${mute.id} selects no display word`);
+ });
const styles = new Map<string, CaptionStyleIntent>([[defaultStyle.id, defaultStyle]]);
applications.forEach((application) => {
const previous = styles.get(application.style.id);
@@ -197,6 +218,9 @@ export function resolveCaptionProgram(
defaultStyleId: defaultStyle.id,
styles: [...styles.values()],
runs: runs.map(({ turnId: _turn, segmentId: _segment, ...run }) => run),
+ mutedWordIds: sequence.words
+ .filter((word) => mutes.some((mute) => mute.words.wordIds.includes(word.id)))
+ .map((word) => word.id),
});
assertCaptionProgramForDisplay(program, sequence);
return program;
diff --git a/packages/caption/src/surface.ts b/packages/caption/src/surface.ts
index 74387b9f..43b00bd4 100644
--- a/packages/caption/src/surface.ts
+++ b/packages/caption/src/surface.ts
@@ -10,7 +10,7 @@ import type {
import { captionTypes } from "./manifest.js";
import { captionWordsForRole } from "./display.js";
import { resolveCaptionProgram } from "./style.js";
-import type { CaptionStyleApplication } from "./style.js";
+import type { CaptionMuteApplication, CaptionStyleApplication } from "./style.js";
import type { CaptionStyleIntent } from "./types.js";
function sameType(left: SurfaceResolvedReference["type"], right: SurfaceResolvedReference["type"]): boolean {
@@ -81,13 +81,17 @@ export const decodeCaptionProgramSurface: StructuredSurfaceHandler = ({ element,
`${element.name}.default`,
);
const applications: CaptionStyleApplication[] = [];
+ const mutes: CaptionMuteApplication[] = [];
for (const child of element.children) {
if (child.kind === "text") {
- if (child.value.trim()) throw new Error(`${element.name} accepts only Use children`);
+ if (child.value.trim()) throw new Error(`${element.name} accepts only Use or Mute children`);
continue;
}
- if (localName(child.name) !== "Use") throw new Error(`${element.name} accepts only Use children`);
- attributes(child, ["style"], ["role", "words"]);
+ const childName = localName(child.name);
+ if (childName !== "Use" && childName !== "Mute") {
+ throw new Error(`${element.name} accepts only Use or Mute children`);
+ }
+ attributes(child, childName === "Use" ? ["style"] : [], ["role", "words"]);
const role = optionalString(child, "role");
const wordsAttribute = child.attributes.words;
if ((role === undefined) === (wordsAttribute === undefined)) {
@@ -99,16 +103,20 @@ export const decodeCaptionProgramSurface: StructuredSurfaceHandler = ({ element,
`${child.name}.words`,
)
: captionWordsForRole(sequence, role);
- applications.push({
- id: `${id}.use.${applications.length + 1}`,
- words,
- style: inline<CaptionStyleIntent>(
- reference(child, "style", captionTypes.style, resolveReference),
- `${child.name}.style`,
- ),
- });
+ if (childName === "Mute") {
+ mutes.push({ id: `${id}.mute.${mutes.length + 1}`, words });
+ } else {
+ applications.push({
+ id: `${id}.use.${applications.length + 1}`,
+ words,
+ style: inline<CaptionStyleIntent>(
+ reference(child, "style", captionTypes.style, resolveReference),
+ `${child.name}.style`,
+ ),
+ });
+ }
}
- const program = resolveCaptionProgram(sequence, id, defaultStyle, applications);
+ const program = resolveCaptionProgram(sequence, id, defaultStyle, applications, mutes);
return {
records: [{ id, type: captionTypes.program, value: { kind: "inline", value: program }, range: element.range }],
components: [],
diff --git a/packages/caption/src/temporalize.ts b/packages/caption/src/temporalize.ts
index 6835dcf2..8e24c662 100644
--- a/packages/caption/src/temporalize.ts
+++ b/packages/caption/src/temporalize.ts
@@ -8,6 +8,41 @@ import { assertCaptionPlanForProgram } from "./plan.js";
import { assertCaptionProgramForDisplay } from "./style.js";
import type { CaptionPlan, CaptionProgram, TimedCaptionProjection } from "./types.js";
+/**
+ * Apply Caption-owned post-planning visibility without changing Cue identity, timing or grouping.
+ * The operation is idempotent so Style-family renderers may enforce the contract defensively.
+ */
+export function applyCaptionMute(
+ projection: TimedCaptionProjection,
+ program: CaptionProgram,
+ display: CaptionDisplaySequence,
+): TimedCaptionProjection {
+ assertTimedCaptionProjection(projection);
+ assertCaptionProgramForDisplay(program, display);
+ if (projection.displaySequenceId !== display.id) {
+ throw new Error("Caption Mute received another display sequence");
+ }
+ const mutedWords = new Set(program.mutedWordIds);
+ const mutedAtoms = new Set(display.atoms
+ .filter((atom) => atom.wordIds.every((wordId) => mutedWords.has(wordId)))
+ .map((atom) => atom.id));
+ const result: TimedCaptionProjection = {
+ contract: "svml.timed-caption-projection@1",
+ displaySequenceId: projection.displaySequenceId,
+ cues: projection.cues.flatMap((cue) => {
+ const atoms = cue.atoms.filter((atom) => !mutedAtoms.has(atom.atomId));
+ if (atoms.length === 0) return [];
+ return [{
+ ...cue,
+ atoms,
+ fields: cue.fields.filter((field) => !mutedWords.has(field.wordId)),
+ }];
+ }),
+ };
+ assertTimedCaptionProjection(result);
+ return result;
+}
+
/** Join whole authored Caption Atoms to measured speech time. No display-word time is invented. */
export function temporalizeCaptionPlan(
display: CaptionDisplaySequence,
@@ -52,12 +87,11 @@ export function temporalizeCaptionPlan(
fields: cue.fields.map((field) => ({ ...field })),
};
}));
- const result: TimedCaptionProjection = {
+ const result = applyCaptionMute({
contract: "svml.timed-caption-projection@1",
displaySequenceId: display.id,
cues,
- };
- assertTimedCaptionProjection(result);
+ }, program, display);
return result;
}
diff --git a/packages/caption/src/types.ts b/packages/caption/src/types.ts
index affcb81d..b417286c 100644
--- a/packages/caption/src/types.ts
+++ b/packages/caption/src/types.ts
@@ -65,7 +65,7 @@ export type CaptionProgramRun = {
readonly wordIds: readonly string[];
};
-/** Total, ordered style assignment over one Caption display universe. */
+/** Total, ordered style assignment plus an explicit post-planning visibility mask. */
export type CaptionProgram = {
readonly contract: "svml.caption-program@1";
readonly id: string;
@@ -73,6 +73,8 @@ export type CaptionProgram = {
readonly defaultStyleId: string;
readonly styles: readonly CaptionStyleIntent[];
readonly runs: readonly CaptionProgramRun[];
+ /** Ordered display-word ids hidden by the renderer. They remain present in CaptionPlan. */
+ readonly mutedWordIds: readonly string[];
};
export type TimedCaptionCue = {
diff --git a/packages/caption/test/caption.test.ts b/packages/caption/test/caption.test.ts
index 11db4031..360b5698 100644
--- a/packages/caption/test/caption.test.ts
+++ b/packages/caption/test/caption.test.ts
@@ -3,14 +3,18 @@ import test from "node:test";
import {
assertCaptionPlanForProgram,
+ captionTypes,
+ decodeCaptionProgramSurface,
resolveCaptionProgram,
sealCaptionPlan,
sealCaptionStyle,
temporalizeCaptionPlan,
} from "@narratage/caption";
import type { CaptionFieldDeclaration, CaptionStyleIntent } from "@narratage/caption";
-import type { Narrative } from "@narratage/narrative";
-import { digestOf } from "@narratage/protocol";
+import { narrativeTypes } from "@narratage/narrative";
+import type { CaptionDisplayWordSubset, Narrative } from "@narratage/narrative";
+import { canonicalize, digestOf, recordDigest } from "@narratage/protocol";
+import type { StoredValue, TypeRef } from "@narratage/protocol";
import { sealProgramSpace } from "@narratage/program-space";
import { sealSpeechBasis } from "@narratage/speech";
import type { SpeechAudioBasis } from "@narratage/speech";
@@ -23,6 +27,7 @@ import {
captionSelectionWordSubset,
parseScript,
} from "@narratage/script";
+import type { StructuredElement, SurfaceResolvedReference } from "@narratage/text";
function locate(narrative: Narrative, durationSec: number, segments: readonly AlignedTranscriptSegment[]) {
const space = sealProgramSpace({
@@ -110,6 +115,137 @@ test("Selection and Role project to ordered whole-Atom display-word subsets", ()
assert.deepEqual(program.runs.map((run) => run.styleId), ["normal", "alice"]);
});
+test("Caption Mute is an ordered whole-Atom visibility mask and does not change planning runs", () => {
+ const parsed = parseScript("mute.svml", "<line>Keep this hidden phrase visible ending.</line>");
+ const display = captionDisplaySequence(parsed, "story.caption");
+ const mutedWords = [display.words[2]!, display.words[3]!];
+ const program = resolveCaptionProgram(display, "captions", style("normal"), [], [{
+ id: "hide-middle",
+ words: {
+ contract: "svml.caption-display-word-subset@1",
+ id: "selection:hide-middle",
+ sequenceId: display.id,
+ wordIds: mutedWords.map((word) => word.id),
+ },
+ }]);
+
+ assert.deepEqual(program.mutedWordIds, mutedWords.map((word) => word.id));
+ assert.deepEqual(program.runs.flatMap((run) => run.wordIds), display.words.map((word) => word.id));
+});
+
+test("Caption timing applies Mute after planning and preserves the original Cue window", () => {
+ const parsed = parseScript("mute-timing.svml", "<line>Keep this hidden phrase visible.</line>");
+ const display = captionDisplaySequence(parsed, "story.caption");
+ const correspondence = captionCorrespondence(parsed, display.id);
+ const mutedWordIds = [display.words[0]!.id, display.words[2]!.id];
+ const program = resolveCaptionProgram(display, "captions", style("normal"), [], [{
+ id: "hide-disconnected",
+ words: {
+ contract: "svml.caption-display-word-subset@1",
+ id: "selection:hide-disconnected",
+ sequenceId: display.id,
+ wordIds: mutedWordIds,
+ },
+ }]);
+ const plan = sealCaptionPlan({
+ contract: "svml.caption-plan@1",
+ runs: [{
+ id: program.runs[0]!.id,
+ styleId: program.runs[0]!.styleId,
+ cues: [{ id: "cue:1", atomIds: display.atoms.map((atom) => atom.id), fields: [] }],
+ }],
+ });
+ const map = locate(parsed, 2, [{
+ sourceSegmentId: "line",
+ startSec: 0,
+ endSec: 2,
+ words: ["Keep", "this", "hidden", "phrase", "visible"].map((text, index) => ({
+ text,
+ startSec: index * 0.3,
+ endSec: index * 0.3 + 0.2,
+ })),
+ chars: [],
+ }]);
+
+ const projection = temporalizeCaptionPlan(display, correspondence, map, program, plan);
+ assert.equal(plan.runs[0]!.cues[0]!.atomIds.length, display.atoms.length);
+ assert.deepEqual(projection.cues[0]!.atoms.map((atom) => atom.atomId),
+ display.atoms.filter((atom) => !atom.wordIds.some((wordId) => mutedWordIds.includes(wordId)))
+ .map((atom) => atom.id));
+ assert.equal(projection.cues[0]!.startSec, 0);
+ assert.equal(projection.cues[0]!.endSec, 1.4);
+});
+
+test("caption:Program lowers explicit Mute word subsets without a temporal mask", async () => {
+ const parsed = parseScript("mute-surface.svml", "<line>Keep this private phrase hidden.</line>");
+ const display = captionDisplaySequence(parsed, "story.caption");
+ const hidden: CaptionDisplayWordSubset = {
+ contract: "svml.caption-display-word-subset@1",
+ id: "private",
+ sequenceId: display.id,
+ wordIds: display.words.slice(2, 4).map((word) => word.id),
+ };
+ const defaultStyle = style("normal");
+ const resolved = <T,>(path: string, type: TypeRef, value: T): SurfaceResolvedReference => {
+ const stored = { kind: "inline", value: canonicalize(value) } satisfies StoredValue;
+ return {
+ path,
+ ref: { kind: "record", id: path },
+ type,
+ record: {
+ id: path,
+ type,
+ value: stored,
+ digest: recordDigest(type, stored),
+ conformance: "exact",
+ origin: {
+ kind: "authored",
+ sourceDigest: digestOf("caption:mute-surface-source"),
+ frontendClosureDigest: digestOf("caption:mute-surface-frontend"),
+ sourceName: "main.svml",
+ },
+ },
+ };
+ };
+ const references = new Map<string, SurfaceResolvedReference>([
+ ["story.caption", resolved("story.caption", narrativeTypes.captionDisplay, display)],
+ ["story.caption.selection.private", resolved(
+ "story.caption.selection.private",
+ narrativeTypes.captionDisplayWordSubset,
+ hidden,
+ )],
+ ["normal", resolved("normal", captionTypes.style, defaultStyle)],
+ ]);
+ const element: StructuredElement = {
+ kind: "element",
+ name: "caption:Program",
+ attributes: {
+ id: "captions",
+ display: { kind: "reference", path: "story.caption" },
+ default: { kind: "reference", path: "normal" },
+ },
+ children: [{
+ kind: "element",
+ name: "caption:Mute",
+ attributes: { words: { kind: "reference", path: "story.caption.selection.private" } },
+ children: [],
+ range: { start: 10, end: 40 },
+ }],
+ range: { start: 0, end: 50 },
+ };
+ const output = await decodeCaptionProgramSurface({
+ sourceName: "main.svml",
+ element,
+ resolveReference: (path) => references.get(path),
+ resolveAsset: () => { throw new Error("Caption Program does not resolve assets"); },
+ });
+ const value = output.records[0]!.value;
+ assert.equal(value.kind, "inline");
+ assert.deepEqual(value.kind === "inline"
+ ? (value.value as unknown as { mutedWordIds: readonly string[] }).mutedWordIds
+ : [], hidden.wordIds);
+});
+
test("Caption Plan partitions Atoms and assigns independent fields to display Words", () => {
const parsed = parseScript("plan.svml", "<line>one two three four.</line>");
const display = captionDisplaySequence(parsed, "story.caption");
diff --git a/packages/film/README.md b/packages/film/README.md
index 877568f4..647b2f4f 100644
--- a/packages/film/README.md
+++ b/packages/film/README.md
@@ -16,6 +16,9 @@ remains order-independent because the public contract canonicalizes Tracks and v
belongs to each Present's absolute stacking key.
The official Structured Surface validates an imported generic SVS Recipe into a nominal
-`FilmProgram`, type-checks each `<film:Track source={...}/>` reference and generates the finite fold.
+`FilmProgram`, receives CanvasSpace and ProgramSpace through separate explicit edges, type-checks
+each `<film:Track source={...}/>` reference and generates the finite fold. CanvasSpace is the only
+dimension truth, ProgramSpace is the only frame-rate truth, and FilmProgram owns only assembly
+identity and clear color.
Child order is organizational: Track and Present identity, timing and absolute stacking remain in
their own typed values. Final rendering is a separate author package and capability.
diff --git a/packages/film/package.json b/packages/film/package.json
index ede50381..d6b3f8c9 100644
--- a/packages/film/package.json
+++ b/packages/film/package.json
@@ -15,6 +15,7 @@
"@narratage/elaborator": "workspace:*",
"@narratage/program-space": "workspace:*",
"@narratage/protocol": "workspace:*",
+ "@narratage/spatial": "workspace:*",
"@narratage/svs": "workspace:*",
"@narratage/text": "workspace:*"
},
diff --git a/packages/film/src/component.ts b/packages/film/src/component.ts
index b4d2a7f4..c36c7c44 100644
--- a/packages/film/src/component.ts
+++ b/packages/film/src/component.ts
@@ -1,5 +1,6 @@
import type { ComponentPackage } from "@narratage/component-kit";
import type { ProgramSpace } from "@narratage/program-space";
+import type { CanvasSpace } from "@narratage/spatial";
import type { AudioTrack, VisualTrack } from "@narratage/composition";
import type { StoredValue } from "@narratage/protocol";
import { canonicalize } from "@narratage/protocol";
@@ -63,6 +64,7 @@ export const filmComponent = {
handler: ({ inputs }) => ({
outputs: { composition: { kind: "inline", value: canonicalize(compileFilmComposition(
inline<FilmProgram>(inputs.program?.value, "FilmProgram"),
+ inline<CanvasSpace>(inputs.canvas?.value, "CanvasSpace"),
inline<ProgramSpace>(inputs.space?.value, "ProgramSpace"),
inline<FilmTrackSet>(inputs.set?.value, "FilmTrackSet"),
)) } },
diff --git a/packages/film/src/fragment.ts b/packages/film/src/fragment.ts
index 7a7df742..c5e0e3ff 100644
--- a/packages/film/src/fragment.ts
+++ b/packages/film/src/fragment.ts
@@ -1,4 +1,5 @@
import { programSpaceTypes } from "@narratage/program-space";
+import { spatialTypes } from "@narratage/spatial";
import { compositionTypes } from "@narratage/composition";
import type { Track } from "@narratage/composition";
import { sealGraphFragment } from "@narratage/elaborator";
@@ -11,7 +12,7 @@ const input = (name: string) => ({ kind: "fragment-input" as const, name });
const operation = (id: string) => ({ kind: "fragment-operation" as const, operation: id });
function assertTrackInputs(tracks: readonly FilmTrackInput[]): FilmTrackInput[] {
- const names = new Set(["program", "space"]);
+ const names = new Set(["program", "canvas", "space"]);
return [...tracks]
.map((track) => ({ name: track.name.trim(), kind: track.kind }))
.sort((left, right) => left.name.localeCompare(right.name))
@@ -50,14 +51,20 @@ export function createFilmAssemblyFragment(options: FilmAssemblyFragmentOptions)
operations.push({
id: "film:composition",
producer: filmProducers.compileComposition,
- inputs: { program: input("program"), space: input("space"), set: operation(current) },
+ inputs: {
+ program: input("program"),
+ canvas: input("canvas"),
+ space: input("space"),
+ set: operation(current),
+ },
result: { kind: "output" as const, name: "composition" },
});
- const semanticInputs = ["program", "space", ...tracks.map((track) => track.name)];
+ const semanticInputs = ["program", "canvas", "space", ...tracks.map((track) => track.name)];
return sealGraphFragment({
name: options.name?.trim() || "@narratage/film/assembly@1",
inputs: [
{ name: "program", type: filmTypes.program },
+ { name: "canvas", type: spatialTypes.canvas },
{ name: "space", type: programSpaceTypes.programSpace },
...tracks.map((track) => ({
name: track.name,
diff --git a/packages/film/src/manifest.ts b/packages/film/src/manifest.ts
index d689976c..8859d5c0 100644
--- a/packages/film/src/manifest.ts
+++ b/packages/film/src/manifest.ts
@@ -2,6 +2,7 @@ import { programSpaceDependency, programSpaceTypes } from "@narratage/program-sp
import { audioTrackSchema, compositionDependency, compositionTypes, visualTrackSchema } from "@narratage/composition";
import { digestOf } from "@narratage/protocol";
import type { ModuleManifest, ProducerRef, TypeRef, ValueSchema } from "@narratage/protocol";
+import { spatialDependency, spatialTypes } from "@narratage/spatial";
import { svsManifest, svsModuleRef } from "@narratage/svs";
import {
@@ -25,27 +26,15 @@ export const filmProducers = {
} satisfies Record<string, ProducerRef>;
const string = { kind: "string", minLength: 1 } as const;
-const integer = { kind: "number", integer: true, minimum: 1 } as const;
const object = (fields: Readonly<Record<string, { readonly schema: ValueSchema; readonly optional?: boolean }>>): ValueSchema => ({
kind: "object",
fields,
});
-const canvasSchema = object({
- width: { schema: integer },
- height: { schema: integer },
- clearColor: { schema: string },
-});
-const frameRateSchema = object({
- numerator: { schema: integer },
- denominator: { schema: integer },
-});
-
export const filmProgramSchema: ValueSchema = object({
contract: { schema: { kind: "literal", value: "svml.film-program@1" } },
id: { schema: string },
- frameRate: { schema: frameRateSchema },
- canvas: { schema: canvasSchema },
+ clearColor: { schema: string },
});
export const filmTrackSetSchema: ValueSchema = object({
@@ -64,6 +53,7 @@ export const filmManifest: ModuleManifest = {
version: filmModuleRef.version,
dependencies: [
programSpaceDependency,
+ spatialDependency,
compositionDependency,
{ module: svsModuleRef, digest: digestOf(svsManifest) },
],
@@ -129,6 +119,7 @@ export const filmManifest: ModuleManifest = {
name: filmProducers.compileComposition.name,
inputs: [
{ name: "program", type: filmTypes.program },
+ { name: "canvas", type: spatialTypes.canvas },
{ name: "space", type: programSpaceTypes.programSpace },
{ name: "set", type: filmTypes.trackSet },
],
diff --git a/packages/film/src/program.ts b/packages/film/src/program.ts
index 92bb7270..e687c22b 100644
--- a/packages/film/src/program.ts
+++ b/packages/film/src/program.ts
@@ -1,5 +1,7 @@
import { assertProgramSpaceIdentity } from "@narratage/program-space";
import type { ProgramSpace } from "@narratage/program-space";
+import { assertCanvasSpace } from "@narratage/spatial";
+import type { CanvasSpace } from "@narratage/spatial";
import { assertAudioTrackIdentity, assertCompositionIdentity, assertVisualTrackIdentity, sealComposition } from "@narratage/composition";
import type { AudioTrack, Composition, Track, VisualTrack } from "@narratage/composition";
import { digestOf } from "@narratage/protocol";
@@ -23,8 +25,7 @@ function filmProgramContent(value: FilmProgram): FilmProgram {
return {
contract: "svml.film-program@1",
id: value.id,
- frameRate: { ...value.frameRate },
- canvas: { ...value.canvas },
+ clearColor: value.clearColor,
};
}
@@ -44,22 +45,8 @@ export function sealFilmProgram(value: FilmProgram): FilmProgram {
export function assertFilmProgramIdentity(program: FilmProgram): void {
if (program.contract !== "svml.film-program@1") throw new Error("Unsupported FilmProgram contract.");
assertNonEmpty(program.id, "FilmProgram id");
- if (
- !Number.isSafeInteger(program.frameRate.numerator)
- || program.frameRate.numerator <= 0
- || !Number.isSafeInteger(program.frameRate.denominator)
- || program.frameRate.denominator <= 0
- ) {
- throw new Error("FilmProgram frame rate is invalid.");
- }
- if (
- !Number.isSafeInteger(program.canvas.width)
- || program.canvas.width <= 0
- || !Number.isSafeInteger(program.canvas.height)
- || program.canvas.height <= 0
- || !/^#[0-9a-f]{6}(?:[0-9a-f]{2})?$/iu.test(program.canvas.clearColor)
- ) {
- throw new Error("FilmProgram canvas is invalid.");
+ if (!/^#[0-9a-f]{6}(?:[0-9a-f]{2})?$/iu.test(program.clearColor)) {
+ throw new Error("FilmProgram clear color is invalid.");
}
}
@@ -107,20 +94,24 @@ export function appendFilmAudioTrack(set: FilmTrackSet, programSpace: ProgramSpa
return appendTrack(set, programSpace, track);
}
-export function compileFilmComposition(program: FilmProgram, programSpace: ProgramSpace, set: FilmTrackSet): Composition {
+export function compileFilmComposition(
+ program: FilmProgram,
+ canvas: CanvasSpace,
+ programSpace: ProgramSpace,
+ set: FilmTrackSet,
+): Composition {
assertFilmProgramIdentity(program);
+ assertCanvasSpace(canvas);
assertProgramSpaceIdentity(programSpace);
assertFilmTrackSetIdentity(set);
- if (
- program.frameRate.numerator !== programSpace.frameRate.numerator
- || program.frameRate.denominator !== programSpace.frameRate.denominator
- ) {
- throw new Error("FilmProgram and FilmTrackSet use different frame rates.");
- }
const composition = sealComposition({
contract: "svml.composition@1",
id: program.id,
- canvas: program.canvas,
+ canvas: {
+ width: canvas.widthPx,
+ height: canvas.heightPx,
+ clearColor: program.clearColor,
+ },
tracks: set.tracks,
});
assertCompositionIdentity(composition, programSpace);
diff --git a/packages/film/src/surface.ts b/packages/film/src/surface.ts
index 0f2bee19..b81be1ae 100644
--- a/packages/film/src/surface.ts
+++ b/packages/film/src/surface.ts
@@ -1,5 +1,6 @@
import { programSpaceTypes } from "@narratage/program-space";
import type { ProgramSpace } from "@narratage/program-space";
+import { spatialTypes } from "@narratage/spatial";
import { compositionTypes } from "@narratage/composition";
import type { AudioTrack, Track, VisualTrack } from "@narratage/composition";
import { digestOf } from "@narratage/protocol";
@@ -71,14 +72,6 @@ function recipe(reference: SurfaceResolvedReference, label: string): SvsRecipe {
return value.value as SvsRecipe;
}
-function numberProperty(value: SvsRecipe, name: string): number {
- const property = value.properties[name];
- if (typeof property !== "number" || !Number.isSafeInteger(property) || property <= 0) {
- throw new Error(`Film Recipe ${name} must be a positive integer`);
- }
- return property;
-}
-
function colorProperty(value: SvsRecipe, name: string): string {
const property = value.properties[name];
if (typeof property !== "string" || !/^#[0-9a-f]{6}(?:[0-9a-f]{2})?$/iu.test(property)) {
@@ -109,15 +102,19 @@ function trackKind(reference: SurfaceResolvedReference): "visual" | "audio" {
}
export const decodeFilmSurface: StructuredSurfaceHandler = ({ element, resolveReference }) => {
- exactAttributes(element, ["id", "space", "appearance"]);
+ exactAttributes(element, ["id", "canvas", "space", "appearance"]);
const id = stringAttribute(element, "id");
+ const canvas = requiredReference(element, "canvas", resolveReference);
+ if (!sameType(canvas.type, spatialTypes.canvas)) {
+ throw new Error(`${element.name}.canvas must reference CanvasSpace`);
+ }
const space = requiredReference(element, "space", resolveReference);
if (!sameType(space.type, programSpaceTypes.programSpace)) {
throw new Error(`${element.name}.space must reference ProgramSpace`);
}
const appearanceReference = requiredReference(element, "appearance", resolveReference);
const appearance = recipe(appearanceReference, `${element.name}.appearance`);
- const expectedProperties = ["background", "frame-rate", "height", "width"];
+ const expectedProperties = ["background"];
const actualProperties = Object.keys(appearance.properties).sort();
if (actualProperties.join("\u0000") !== expectedProperties.join("\u0000")) {
throw new Error(`Film Recipe requires exactly ${expectedProperties.join(", ")}`);
@@ -127,12 +124,7 @@ export const decodeFilmSurface: StructuredSurfaceHandler = ({ element, resolveRe
const program = sealFilmProgram({
contract: "svml.film-program@1",
id,
- frameRate: { numerator: numberProperty(appearance, "frame-rate"), denominator: 1 },
- canvas: {
- width: numberProperty(appearance, "width"),
- height: numberProperty(appearance, "height"),
- clearColor: colorProperty(appearance, "background"),
- },
+ clearColor: colorProperty(appearance, "background"),
});
const tracks = trackChildren(element).map((child) => {
@@ -157,6 +149,7 @@ export const decodeFilmSurface: StructuredSurfaceHandler = ({ element, resolveRe
fragment: fragment.id,
inputs: {
program: { kind: "record", id: programId },
+ canvas: canvas.ref,
space: space.ref,
...Object.fromEntries(tracks.map((track) => [track.name, track.source.ref])),
},
diff --git a/packages/film/src/types.ts b/packages/film/src/types.ts
index 86f1c887..850a3861 100644
--- a/packages/film/src/types.ts
+++ b/packages/film/src/types.ts
@@ -4,15 +4,7 @@ import type { Track } from "@narratage/composition";
export type FilmProgram = {
readonly contract: "svml.film-program@1";
readonly id: string;
- readonly frameRate: {
- readonly numerator: number;
- readonly denominator: number;
- };
- readonly canvas: {
- readonly width: number;
- readonly height: number;
- readonly clearColor: string;
- };
+ readonly clearColor: string;
};
/**
diff --git a/packages/film/test/film.test.ts b/packages/film/test/film.test.ts
index a42da2f5..6ed63ff8 100644
--- a/packages/film/test/film.test.ts
+++ b/packages/film/test/film.test.ts
@@ -1,8 +1,9 @@
-import { compositionComponent, videoContractManifests } from "../../test-support/video-domain.js";
+import { compositionComponent, spatialComponent, videoContractManifests } from "../../test-support/video-domain.js";
import { registerTypeValidatorFacets } from "@narratage/component-kit";
import { programSpaceTypes, sealProgramSpace } from "@narratage/program-space";
import { compositionTypes, sealAudioTrack, sealVisualTrack } from "@narratage/composition";
import type { Composition, Track } from "@narratage/composition";
+import { sealCanvasSpace, spatialTypes } from "@narratage/spatial";
import assert from "node:assert/strict";
import test from "node:test";
@@ -67,13 +68,22 @@ const space = sealProgramSpace({
function validatorRegistry(): TypeValidatorRegistry {
const registry = new TypeValidatorRegistry();
registerTypeValidatorFacets(registry, compositionComponent.validators);
+ registerTypeValidatorFacets(registry, spatialComponent.validators);
return registry;
}
+const canvas = sealCanvasSpace({
+ contract: "svml.canvas-space@1",
+ widthPx: 1080,
+ heightPx: 1920,
+ origin: "top-left",
+ xDirection: "right",
+ yDirection: "down",
+ pixelAspect: "square",
+});
const filmProgram = sealFilmProgram({
contract: "svml.film-program@1",
id: "main-film",
- frameRate: space.frameRate,
- canvas: { width: 1080, height: 1920, clearColor: "#000000" },
+ clearColor: "#000000",
});
const textProgram = sealTextTrackProgram({
contract: "svml.text-track-program@1",
@@ -84,7 +94,7 @@ const textProgram = sealTextTrackProgram({
span: { startFrame: 10, endFrameExclusive: 100 },
z: 60,
tieBreak: "title",
- box: { xPercent: 8, yPercent: 10, widthPercent: 84, heightPercent: 20 },
+ frame: { contract: "svml.spatial-frame@1", xPx: 86.4, yPx: 192, widthPx: 907.2, heightPx: 384 },
appearance: { color: "#ffffff", fontSizePx: 56, fontWeight: 800 },
}],
});
@@ -129,6 +139,7 @@ const origin = {
};
const records = await Promise.all([
sealRecord({ id: "space", type: programSpaceTypes.programSpace, value: stored(space), conformance: "exact", origin }),
+ sealRecord({ id: "canvas", type: spatialTypes.canvas, value: stored(canvas), conformance: "exact", origin }),
sealRecord({ id: "film-program", type: filmTypes.program, value: stored(filmProgram), conformance: "exact", origin }),
sealRecord({ id: "text-program", type: textTrackTypes.program, value: stored(textProgram), conformance: "exact", origin }),
sealRecord({ id: "background", type: compositionTypes.visualTrack, value: stored(background), conformance: "exact", origin }),
@@ -159,6 +170,7 @@ const filmInstance = elaborateGraphFragment(linked, filmFragment, {
fragment: filmFragment.id,
inputs: {
program: { kind: "record", id: "film-program" },
+ canvas: { kind: "record", id: "canvas" },
space: { kind: "record", id: "space" },
title: { kind: "logical-output", id: "title.track" },
background: { kind: "record", id: "background" },
@@ -246,6 +258,7 @@ test("the Driver folds peer Tracks, then independently compiles the Composition"
registry.registerProducer(filmProducers.compileComposition, compileFilmCompositionImplementationDigest, ({ inputs }) => ({
outputs: { composition: stored(compileFilmComposition(
inline(inputs.program) as never,
+ inline(inputs.canvas) as typeof canvas,
inline(inputs.space) as typeof space,
inline(inputs.set) as never,
)) },
diff --git a/packages/film/test/surface.test.ts b/packages/film/test/surface.test.ts
index 834be39c..6cacf75f 100644
--- a/packages/film/test/surface.test.ts
+++ b/packages/film/test/surface.test.ts
@@ -1,4 +1,4 @@
-import { compositionComponent, videoContractManifests } from "../../test-support/video-domain.js";
+import { compositionComponent, spatialComponent, videoContractManifests } from "../../test-support/video-domain.js";
import { registerTypeValidatorFacets } from "@narratage/component-kit";
import { programSpaceDependency, programSpaceTypes, sealProgramSpace } from "@narratage/program-space";
import { compositionDependency, compositionTypes, sealAudioTrack, sealVisualTrack } from "@narratage/composition";
@@ -23,6 +23,12 @@ import {
} from "@narratage/film";
import type { ModuleManifest } from "@narratage/protocol";
import { svsFrontend, svsManifest } from "@narratage/svs";
+import {
+ decodeCanvasSurface,
+ spatialManifest,
+ spatialModuleRef,
+ spatialSurfaceDigests,
+} from "@narratage/spatial";
import {
TextSurfaceRegistry,
createTextAuthorFrontend,
@@ -91,14 +97,12 @@ function source(id: string, text: string): AuthorSourceUnit {
function validatorRegistry(): TypeValidatorRegistry {
const registry = new TypeValidatorRegistry();
registerTypeValidatorFacets(registry, compositionComponent.validators);
+ registerTypeValidatorFacets(registry, spatialComponent.validators);
return registry;
}
const validStyles = `<sheet version="1">
film.vertical {
- width: 1080;
- height: 1920;
- frame-rate: 30;
background: #09090B;
}
</sheet>`;
@@ -120,11 +124,19 @@ async function compileFilm(options: { readonly reverse?: boolean; readonly style
filmSurfaceImplementationDigest,
decodeFilmSurface,
);
+ surfaces.registerStructured(
+ spatialModuleRef,
+ "canvas",
+ spatialSurfaceDigests.canvas,
+ decodeCanvasSurface,
+ );
const frontends = new AuthorFrontendRegistry();
frontends.register(createTextAuthorFrontend({
registry: surfaces,
resolveModule(request) {
- return request.from.startsWith("@narratage/film") ? filmModuleRef : fixtureModule;
+ if (request.from.startsWith("@narratage/film")) return filmModuleRef;
+ if (request.from.startsWith("@narratage/spatial")) return spatialModuleRef;
+ return fixtureModule;
},
}));
frontends.register(svsFrontend);
@@ -136,9 +148,11 @@ async function compileFilm(options: { readonly reverse?: boolean; readonly style
entry: source("/project/main.svml", `<svml>
<import as="fixture" from="example.film-fixture@1"/>
<import as="film" from="@narratage/film@1"/>
+ <import as="space" from="@narratage/spatial@1"/>
<import as="studio" source="./studio.svs"/>
<fixture:Inputs/>
- <film:Film id="main" space={space} appearance={studio.film.vertical}>${tracks}</film:Film>
+ <space:Canvas id="vertical" width="1080" height="1920"/>
+ <film:Film id="main" canvas={vertical} space={space} appearance={studio.film.vertical}>${tracks}</film:Film>
</svml>`),
closure,
frontends,
@@ -155,8 +169,7 @@ test("the official Film Surface validates SVS and lowers dynamic peer Tracks", a
assert.deepEqual(program?.value.kind === "inline" ? program.value.value : undefined, {
contract: "svml.film-program@1",
id: "main",
- frameRate: { numerator: 30, denominator: 1 },
- canvas: { width: 1080, height: 1920, clearColor: "#09090B" },
+ clearColor: "#09090B",
});
const target = resolveCompiledSourceExport(compiled, "main.composition", compositionTypes.composition);
assert.equal(target.ref.kind, "logical-output");
diff --git a/packages/spatial/README.md b/packages/spatial/README.md
new file mode 100644
index 00000000..4c9c61c1
--- /dev/null
+++ b/packages/spatial/README.md
@@ -0,0 +1,9 @@
+# `@narratage/spatial`
+
+Shared video-domain geometry: explicit Canvas coordinates, Points, Frames, Paths, intrinsic extents
+and deterministic two-frame content fitting. It owns no timing, Paint, motion, media decoding,
+renderer, Provider or Core behavior.
+
+The package exposes self-described `Canvas`, `Frame`, `AnchoredFrame` and `AspectFrame` author
+Surfaces plus pure geometry functions and fixed-port Producers. See
+[`../../spec/spatial-layout.md`](../../spec/spatial-layout.md).
diff --git a/packages/spatial/package.json b/packages/spatial/package.json
new file mode 100644
index 00000000..e47c63ad
--- /dev/null
+++ b/packages/spatial/package.json
@@ -0,0 +1,19 @@
+{
+ "name": "@narratage/spatial",
+ "version": "0.0.0-dev",
+ "private": true,
+ "type": "module",
+ "exports": {
+ ".": "./src/index.ts"
+ },
+ "svml": {
+ "activation": "./src/activation.ts"
+ },
+ "dependencies": {
+ "@narratage/component-kit": "workspace:*",
+ "@narratage/elaborator": "workspace:*",
+ "@narratage/protocol": "workspace:*",
+ "@narratage/text": "workspace:*",
+ "@narratage/validation": "workspace:*"
+ }
+}
diff --git a/packages/spatial/src/activation.ts b/packages/spatial/src/activation.ts
new file mode 100644
index 00000000..69d69fba
--- /dev/null
+++ b/packages/spatial/src/activation.ts
@@ -0,0 +1,28 @@
+import { createTextSurfaceHostFacet } from "@narratage/text";
+
+import {
+ decodeAnchoredFrameSurface,
+ decodeAspectFrameSurface,
+ decodeCanvasSurface,
+ decodeFrameSurface,
+} from "./surface.js";
+import {
+ spatialManifest,
+ spatialModuleRef,
+ spatialSurfaceDigests,
+} from "./manifest.js";
+import { spatialComponent } from "./component.js";
+
+export const svmlPackage = {
+ format: "svml.node-package@1" as const,
+ name: "@narratage/spatial",
+ modules: [{ manifest: spatialManifest, specifiers: ["@narratage/spatial", "@narratage/spatial@1"] }],
+ components: [spatialComponent],
+ hostFacets: [
+ createTextSurfaceHostFacet({ module: spatialModuleRef, surface: "canvas", mode: "structured", implementationDigest: spatialSurfaceDigests.canvas, handler: decodeCanvasSurface }),
+ createTextSurfaceHostFacet({ module: spatialModuleRef, surface: "frame", mode: "structured", implementationDigest: spatialSurfaceDigests.frame, handler: decodeFrameSurface }),
+ createTextSurfaceHostFacet({ module: spatialModuleRef, surface: "anchored-frame", mode: "structured", implementationDigest: spatialSurfaceDigests.anchoredFrame, handler: decodeAnchoredFrameSurface }),
+ createTextSurfaceHostFacet({ module: spatialModuleRef, surface: "aspect-frame", mode: "structured", implementationDigest: spatialSurfaceDigests.aspectFrame, handler: decodeAspectFrameSurface }),
+ ],
+};
+export default svmlPackage;
diff --git a/packages/spatial/src/component.ts b/packages/spatial/src/component.ts
new file mode 100644
index 00000000..a9b5114d
--- /dev/null
+++ b/packages/spatial/src/component.ts
@@ -0,0 +1,59 @@
+import type { ComponentPackage } from "@narratage/component-kit";
+import { canonicalize } from "@narratage/protocol";
+import type { StoredValue } from "@narratage/protocol";
+
+import {
+ anchoredFrame,
+ aspectFrame,
+ assertCanvasSpace,
+ assertContentFit,
+ assertFittedContent,
+ assertIntrinsicExtent,
+ assertSpatialFrame,
+ assertSpatialPath,
+ assertSpatialPoint,
+ canvasFrame,
+ fitContent,
+ frameFromEdges,
+ spatialImplementationDigests,
+ spatialValidatorDigests,
+} from "./geometry.js";
+import { spatialProducers, spatialTypes } from "./manifest.js";
+import type {
+ AnchoredFrameProgram,
+ AspectFrameProgram,
+ CanvasSpace,
+ ContentFit,
+ FittedContent,
+ FrameEdgesProgram,
+ IntrinsicExtent,
+ SpatialFrame,
+ SpatialPath,
+ SpatialPoint,
+} from "./types.js";
+
+function inline<T>(value: StoredValue | undefined, label: string): T {
+ if (value?.kind !== "inline") throw new Error(`${label} must be inline.`);
+ return value.value as unknown as T;
+}
+const output = (value: unknown) => ({ kind: "inline" as const, value: canonicalize(value) });
+
+export const spatialComponent = {
+ name: "@narratage/spatial",
+ producers: [
+ { producer: spatialProducers.canvasFrame, implementationDigest: spatialImplementationDigests.canvasFrame, handler: ({ inputs }) => ({ outputs: { frame: output(canvasFrame(inline<CanvasSpace>(inputs.canvas?.value, "CanvasSpace"))) }, needs: {} }) },
+ { producer: spatialProducers.frameEdges, implementationDigest: spatialImplementationDigests.frameEdges, handler: ({ inputs }) => ({ outputs: { frame: output(frameFromEdges(inline<SpatialFrame>(inputs.parent?.value, "SpatialFrame"), inline<FrameEdgesProgram>(inputs.program?.value, "FrameEdgesProgram"))) }, needs: {} }) },
+ { producer: spatialProducers.anchoredFrame, implementationDigest: spatialImplementationDigests.anchoredFrame, handler: ({ inputs }) => ({ outputs: { frame: output(anchoredFrame(inline<SpatialFrame>(inputs.parent?.value, "SpatialFrame"), inline<AnchoredFrameProgram>(inputs.program?.value, "AnchoredFrameProgram"))) }, needs: {} }) },
+ { producer: spatialProducers.aspectFrame, implementationDigest: spatialImplementationDigests.aspectFrame, handler: ({ inputs }) => ({ outputs: { frame: output(aspectFrame(inline<SpatialFrame>(inputs.parent?.value, "SpatialFrame"), inline<IntrinsicExtent>(inputs.extent?.value, "IntrinsicExtent"), inline<AspectFrameProgram>(inputs.program?.value, "AspectFrameProgram"))) }, needs: {} }) },
+ { producer: spatialProducers.fitContent, implementationDigest: spatialImplementationDigests.fitContent, handler: ({ inputs }) => ({ outputs: { fitted: output(fitContent(inline<SpatialFrame>(inputs.frame?.value, "SpatialFrame"), inline<IntrinsicExtent>(inputs.extent?.value, "IntrinsicExtent"), inline<ContentFit>(inputs.fit?.value, "ContentFit"))) }, needs: {} }) },
+ ],
+ validators: [
+ { type: spatialTypes.canvas, implementationDigest: spatialValidatorDigests.canvas, handler: ({ value }) => assertCanvasSpace(inline<CanvasSpace>(value, "CanvasSpace")) },
+ { type: spatialTypes.point, implementationDigest: spatialValidatorDigests.point, handler: ({ value }) => assertSpatialPoint(inline<SpatialPoint>(value, "SpatialPoint")) },
+ { type: spatialTypes.frame, implementationDigest: spatialValidatorDigests.frame, handler: ({ value }) => assertSpatialFrame(inline<SpatialFrame>(value, "SpatialFrame")) },
+ { type: spatialTypes.path, implementationDigest: spatialValidatorDigests.path, handler: ({ value }) => assertSpatialPath(inline<SpatialPath>(value, "SpatialPath")) },
+ { type: spatialTypes.extent, implementationDigest: spatialValidatorDigests.extent, handler: ({ value }) => assertIntrinsicExtent(inline<IntrinsicExtent>(value, "IntrinsicExtent")) },
+ { type: spatialTypes.fit, implementationDigest: spatialValidatorDigests.fit, handler: ({ value }) => assertContentFit(inline<ContentFit>(value, "ContentFit")) },
+ { type: spatialTypes.fitted, implementationDigest: spatialValidatorDigests.fitted, handler: ({ value }) => assertFittedContent(inline<FittedContent>(value, "FittedContent")) },
+ ],
+} satisfies ComponentPackage;
diff --git a/packages/spatial/src/fragment.ts b/packages/spatial/src/fragment.ts
new file mode 100644
index 00000000..55d60176
--- /dev/null
+++ b/packages/spatial/src/fragment.ts
@@ -0,0 +1,41 @@
+import { sealGraphFragment } from "@narratage/elaborator";
+
+import { spatialProducers, spatialTypes } from "./manifest.js";
+
+const input = (name: string) => ({ kind: "fragment-input" as const, name });
+const operation = (name: string) => ({ kind: "fragment-operation" as const, operation: name });
+
+export const canvasFrameFragment = sealGraphFragment({
+ name: "@narratage/spatial/canvas-frame@1",
+ inputs: [{ name: "canvas", type: spatialTypes.canvas }],
+ operations: [{ id: "resolve", producer: spatialProducers.canvasFrame, inputs: { canvas: input("canvas") }, result: { kind: "output", name: "frame" } }],
+ exports: [{ name: "frame", type: spatialTypes.frame, root: operation("resolve"), semanticInputs: ["canvas"], fidelity: "exact" }],
+});
+
+export const frameEdgesFragment = sealGraphFragment({
+ name: "@narratage/spatial/frame-edges@1",
+ inputs: [{ name: "parent", type: spatialTypes.frame }, { name: "program", type: spatialTypes.frameEdgesProgram }],
+ operations: [{ id: "resolve", producer: spatialProducers.frameEdges, inputs: { parent: input("parent"), program: input("program") }, result: { kind: "output", name: "frame" } }],
+ exports: [{ name: "frame", type: spatialTypes.frame, root: operation("resolve"), semanticInputs: ["parent", "program"], fidelity: "exact" }],
+});
+
+export const anchoredFrameFragment = sealGraphFragment({
+ name: "@narratage/spatial/anchored-frame@1",
+ inputs: [{ name: "parent", type: spatialTypes.frame }, { name: "program", type: spatialTypes.anchoredFrameProgram }],
+ operations: [{ id: "resolve", producer: spatialProducers.anchoredFrame, inputs: { parent: input("parent"), program: input("program") }, result: { kind: "output", name: "frame" } }],
+ exports: [{ name: "frame", type: spatialTypes.frame, root: operation("resolve"), semanticInputs: ["parent", "program"], fidelity: "exact" }],
+});
+
+export const aspectFrameFragment = sealGraphFragment({
+ name: "@narratage/spatial/aspect-frame@1",
+ inputs: [{ name: "parent", type: spatialTypes.frame }, { name: "extent", type: spatialTypes.extent }, { name: "program", type: spatialTypes.aspectFrameProgram }],
+ operations: [{ id: "resolve", producer: spatialProducers.aspectFrame, inputs: { parent: input("parent"), extent: input("extent"), program: input("program") }, result: { kind: "output", name: "frame" } }],
+ exports: [{ name: "frame", type: spatialTypes.frame, root: operation("resolve"), semanticInputs: ["parent", "extent", "program"], fidelity: "exact" }],
+});
+
+export const fitContentFragment = sealGraphFragment({
+ name: "@narratage/spatial/fit-content@1",
+ inputs: [{ name: "frame", type: spatialTypes.frame }, { name: "extent", type: spatialTypes.extent }, { name: "fit", type: spatialTypes.fit }],
+ operations: [{ id: "resolve", producer: spatialProducers.fitContent, inputs: { frame: input("frame"), extent: input("extent"), fit: input("fit") }, result: { kind: "output", name: "fitted" } }],
+ exports: [{ name: "fitted", type: spatialTypes.fitted, root: operation("resolve"), semanticInputs: ["frame", "extent", "fit"], fidelity: "exact" }],
+});
diff --git a/packages/spatial/src/geometry.ts b/packages/spatial/src/geometry.ts
new file mode 100644
index 00000000..b9e71bfe
--- /dev/null
+++ b/packages/spatial/src/geometry.ts
@@ -0,0 +1,248 @@
+import { digestOf } from "@narratage/protocol";
+
+import type {
+ AnchoredFrameProgram,
+ AspectFrameProgram,
+ CanvasSpace,
+ ContentFit,
+ FittedContent,
+ FrameEdgesProgram,
+ IntrinsicExtent,
+ SpatialAnchor,
+ SpatialFrame,
+ SpatialLength,
+ SpatialPath,
+ SpatialPoint,
+} from "./types.js";
+
+export const spatialImplementationDigests = {
+ canvasFrame: digestOf("@narratage/spatial/canvas-frame@1"),
+ frameEdges: digestOf("@narratage/spatial/frame-edges@1"),
+ anchoredFrame: digestOf("@narratage/spatial/anchored-frame@1"),
+ aspectFrame: digestOf("@narratage/spatial/aspect-frame@1"),
+ fitContent: digestOf("@narratage/spatial/fit-content@1"),
+} as const;
+
+export const spatialValidatorDigests = {
+ canvas: digestOf("@narratage/spatial/validate-canvas@1"),
+ point: digestOf("@narratage/spatial/validate-point@1"),
+ frame: digestOf("@narratage/spatial/validate-frame@1"),
+ path: digestOf("@narratage/spatial/validate-path@1"),
+ extent: digestOf("@narratage/spatial/validate-extent@1"),
+ fit: digestOf("@narratage/spatial/validate-fit@1"),
+ fitted: digestOf("@narratage/spatial/validate-fitted@1"),
+} as const;
+
+function finite(value: number, label: string): void {
+ if (!Number.isFinite(value)) throw new Error(`${label} must be finite.`);
+}
+
+function positive(value: number, label: string): void {
+ finite(value, label);
+ if (value <= 0) throw new Error(`${label} must be positive.`);
+}
+
+export function assertCanvasSpace(value: CanvasSpace): void {
+ if (value.contract !== "svml.canvas-space@1"
+ || !Number.isSafeInteger(value.widthPx) || value.widthPx <= 0
+ || !Number.isSafeInteger(value.heightPx) || value.heightPx <= 0
+ || value.origin !== "top-left" || value.xDirection !== "right"
+ || value.yDirection !== "down" || value.pixelAspect !== "square") {
+ throw new Error("CanvasSpace is invalid.");
+ }
+}
+
+export function assertSpatialPoint(value: SpatialPoint): void {
+ if (value.contract !== "svml.spatial-point@1") throw new Error("Unsupported SpatialPoint contract.");
+ finite(value.xPx, "SpatialPoint.xPx");
+ finite(value.yPx, "SpatialPoint.yPx");
+}
+
+export function assertSpatialFrame(value: SpatialFrame): void {
+ if (value.contract !== "svml.spatial-frame@1") throw new Error("Unsupported SpatialFrame contract.");
+ finite(value.xPx, "SpatialFrame.xPx");
+ finite(value.yPx, "SpatialFrame.yPx");
+ positive(value.widthPx, "SpatialFrame.widthPx");
+ positive(value.heightPx, "SpatialFrame.heightPx");
+}
+
+export function assertIntrinsicExtent(value: IntrinsicExtent): void {
+ if (value.contract !== "svml.intrinsic-extent@1") throw new Error("Unsupported IntrinsicExtent contract.");
+ positive(value.widthPx, "IntrinsicExtent.widthPx");
+ positive(value.heightPx, "IntrinsicExtent.heightPx");
+}
+
+function assertNormalizedPoint(value: { readonly x: number; readonly y: number }, label: string): void {
+ finite(value.x, `${label}.x`);
+ finite(value.y, `${label}.y`);
+ if (value.x < 0 || value.x > 1 || value.y < 0 || value.y > 1) {
+ throw new Error(`${label} must lie inside [0, 1].`);
+ }
+}
+
+export function assertContentFit(value: ContentFit): void {
+ if (value.contract !== "svml.content-fit@1") throw new Error("Unsupported ContentFit contract.");
+ if (!["contain", "cover", "fit-width", "fit-height", "native", "scale-down", "stretch"].includes(value.sizing)) {
+ throw new Error("ContentFit.sizing is invalid.");
+ }
+ assertNormalizedPoint(value.framePoint, "ContentFit.framePoint");
+ assertNormalizedPoint(value.contentPoint, "ContentFit.contentPoint");
+ finite(value.offsetPx.x, "ContentFit.offsetPx.x");
+ finite(value.offsetPx.y, "ContentFit.offsetPx.y");
+ if (value.constraint !== "bounded" && value.constraint !== "free") throw new Error("ContentFit.constraint is invalid.");
+}
+
+export function assertFittedContent(value: FittedContent): void {
+ if (value.contract !== "svml.fitted-content@1") throw new Error("Unsupported FittedContent contract.");
+ assertSpatialFrame(value.contentFrame);
+}
+
+function commandNumbers(command: SpatialPath["commands"][number]): readonly number[] {
+ switch (command.kind) {
+ case "move":
+ case "line": return [command.xPx, command.yPx];
+ case "quadratic": return [command.controlX, command.controlY, command.xPx, command.yPx];
+ case "cubic": return [command.control1X, command.control1Y, command.control2X, command.control2Y, command.xPx, command.yPx];
+ case "close": return [];
+ }
+}
+
+export function assertSpatialPath(value: SpatialPath): void {
+ if (value.contract !== "svml.spatial-path@1" || value.commands.length < 2 || value.commands[0]?.kind !== "move") {
+ throw new Error("SpatialPath must begin with move and contain drawable commands.");
+ }
+ let open = true;
+ let drawable = false;
+ for (const [index, command] of value.commands.entries()) {
+ for (const coordinate of commandNumbers(command)) finite(coordinate, `SpatialPath command ${index}`);
+ if (command.kind === "move") {
+ open = true;
+ } else if (command.kind === "close") {
+ if (!open) throw new Error("SpatialPath cannot close an already closed subpath.");
+ open = false;
+ } else {
+ if (!open) throw new Error("SpatialPath requires move after a closed subpath.");
+ drawable = true;
+ }
+ }
+ if (!drawable) throw new Error("SpatialPath contains no drawable segment.");
+}
+
+function length(value: SpatialLength, dimension: number, label: string): number {
+ finite(value.value, label);
+ if (value.unit === "px") return value.value;
+ if (value.unit === "percent") return dimension * value.value / 100;
+ throw new Error(`${label} uses an unsupported unit.`);
+}
+
+function anchorPoint(anchor: SpatialAnchor): { readonly x: number; readonly y: number } {
+ const [vertical, horizontal] = anchor === "center" ? ["middle", "center"] : anchor.split("-");
+ const x = horizontal === "left" ? 0 : horizontal === "center" ? 0.5 : horizontal === "right" ? 1 : undefined;
+ const y = vertical === "top" ? 0 : vertical === "middle" ? 0.5 : vertical === "bottom" ? 1 : undefined;
+ if (x === undefined || y === undefined) throw new Error(`Spatial anchor ${anchor} is invalid.`);
+ return { x, y };
+}
+
+function sealFrame(value: Omit<SpatialFrame, "contract">): SpatialFrame {
+ const frame = { contract: "svml.spatial-frame@1" as const, ...value };
+ assertSpatialFrame(frame);
+ return frame;
+}
+
+export function canvasFrame(canvas: CanvasSpace): SpatialFrame {
+ assertCanvasSpace(canvas);
+ return sealFrame({ xPx: 0, yPx: 0, widthPx: canvas.widthPx, heightPx: canvas.heightPx });
+}
+
+export function frameFromEdges(parent: SpatialFrame, program: FrameEdgesProgram): SpatialFrame {
+ assertSpatialFrame(parent);
+ if (program.contract !== "svml.frame-edges-program@1") throw new Error("Unsupported FrameEdgesProgram contract.");
+ const left = parent.xPx + length(program.left, parent.widthPx, "Frame left");
+ const right = parent.xPx + length(program.right, parent.widthPx, "Frame right");
+ const top = parent.yPx + length(program.top, parent.heightPx, "Frame top");
+ const bottom = parent.yPx + length(program.bottom, parent.heightPx, "Frame bottom");
+ return sealFrame({ xPx: left, yPx: top, widthPx: right - left, heightPx: bottom - top });
+}
+
+export function anchoredFrame(parent: SpatialFrame, program: AnchoredFrameProgram): SpatialFrame {
+ assertSpatialFrame(parent);
+ if (program.contract !== "svml.anchored-frame-program@1") throw new Error("Unsupported AnchoredFrameProgram contract.");
+ const widthPx = length(program.width, parent.widthPx, "AnchoredFrame width");
+ const heightPx = length(program.height, parent.heightPx, "AnchoredFrame height");
+ positive(widthPx, "AnchoredFrame width");
+ positive(heightPx, "AnchoredFrame height");
+ const targetX = parent.xPx + length(program.x, parent.widthPx, "AnchoredFrame x");
+ const targetY = parent.yPx + length(program.y, parent.heightPx, "AnchoredFrame y");
+ finite(program.offsetPx.x, "AnchoredFrame offset x");
+ finite(program.offsetPx.y, "AnchoredFrame offset y");
+ const anchor = anchorPoint(program.anchor);
+ return sealFrame({
+ xPx: targetX - widthPx * anchor.x + program.offsetPx.x,
+ yPx: targetY - heightPx * anchor.y + program.offsetPx.y,
+ widthPx,
+ heightPx,
+ });
+}
+
+export function aspectFrame(parent: SpatialFrame, extent: IntrinsicExtent, program: AspectFrameProgram): SpatialFrame {
+ assertSpatialFrame(parent);
+ assertIntrinsicExtent(extent);
+ if (program.contract !== "svml.aspect-frame-program@1") throw new Error("Unsupported AspectFrameProgram contract.");
+ const primary = length(program.size, program.primary === "width" ? parent.widthPx : parent.heightPx, "AspectFrame size");
+ positive(primary, "AspectFrame size");
+ const widthPx = program.primary === "width" ? primary : primary * extent.widthPx / extent.heightPx;
+ const heightPx = program.primary === "height" ? primary : primary * extent.heightPx / extent.widthPx;
+ return anchoredFrame(parent, {
+ contract: "svml.anchored-frame-program@1",
+ x: program.x,
+ y: program.y,
+ width: { unit: "px", value: widthPx },
+ height: { unit: "px", value: heightPx },
+ anchor: program.anchor,
+ offsetPx: program.offsetPx,
+ });
+}
+
+function boundedCoordinate(position: number, contentSize: number, frameStart: number, frameSize: number): number {
+ const first = frameStart;
+ const second = frameStart + frameSize - contentSize;
+ const low = Math.min(first, second);
+ const high = Math.max(first, second);
+ return Math.min(high, Math.max(low, position));
+}
+
+export function fitContent(frame: SpatialFrame, extent: IntrinsicExtent, fit: ContentFit): FittedContent {
+ assertSpatialFrame(frame);
+ assertIntrinsicExtent(extent);
+ assertContentFit(fit);
+ const containScale = Math.min(frame.widthPx / extent.widthPx, frame.heightPx / extent.heightPx);
+ const scale = fit.sizing === "contain" ? containScale
+ : fit.sizing === "cover" ? Math.max(frame.widthPx / extent.widthPx, frame.heightPx / extent.heightPx)
+ : fit.sizing === "fit-width" ? frame.widthPx / extent.widthPx
+ : fit.sizing === "fit-height" ? frame.heightPx / extent.heightPx
+ : fit.sizing === "native" ? 1
+ : fit.sizing === "scale-down" ? Math.min(1, containScale)
+ : undefined;
+ const widthPx = fit.sizing === "stretch" ? frame.widthPx : extent.widthPx * (scale ?? 1);
+ const heightPx = fit.sizing === "stretch" ? frame.heightPx : extent.heightPx * (scale ?? 1);
+ let xPx = frame.xPx + frame.widthPx * fit.framePoint.x - widthPx * fit.contentPoint.x + fit.offsetPx.x;
+ let yPx = frame.yPx + frame.heightPx * fit.framePoint.y - heightPx * fit.contentPoint.y + fit.offsetPx.y;
+ if (fit.constraint === "bounded") {
+ xPx = boundedCoordinate(xPx, widthPx, frame.xPx, frame.widthPx);
+ yPx = boundedCoordinate(yPx, heightPx, frame.yPx, frame.heightPx);
+ }
+ const result: FittedContent = {
+ contract: "svml.fitted-content@1",
+ contentFrame: sealFrame({ xPx, yPx, widthPx, heightPx }),
+ };
+ assertFittedContent(result);
+ return result;
+}
+
+export function sealCanvasSpace(value: CanvasSpace): CanvasSpace { assertCanvasSpace(value); return structuredClone(value); }
+export function sealSpatialPoint(value: SpatialPoint): SpatialPoint { assertSpatialPoint(value); return structuredClone(value); }
+export function sealSpatialFrame(value: SpatialFrame): SpatialFrame { assertSpatialFrame(value); return structuredClone(value); }
+export function sealSpatialPath(value: SpatialPath): SpatialPath { assertSpatialPath(value); return structuredClone(value); }
+export function sealIntrinsicExtent(value: IntrinsicExtent): IntrinsicExtent { assertIntrinsicExtent(value); return structuredClone(value); }
+export function sealContentFit(value: ContentFit): ContentFit { assertContentFit(value); return structuredClone(value); }
+export function sealFittedContent(value: FittedContent): FittedContent { assertFittedContent(value); return structuredClone(value); }
diff --git a/packages/spatial/src/index.ts b/packages/spatial/src/index.ts
new file mode 100644
index 00000000..18ad5f0f
--- /dev/null
+++ b/packages/spatial/src/index.ts
@@ -0,0 +1,26 @@
+export { spatialComponent } from "./component.js";
+export {
+ anchoredFrameFragment,
+ aspectFrameFragment,
+ canvasFrameFragment,
+ fitContentFragment,
+ frameEdgesFragment,
+} from "./fragment.js";
+export * from "./geometry.js";
+export {
+ spatialDependency,
+ spatialManifest,
+ spatialManifestDigest,
+ spatialModuleRef,
+ spatialProducers,
+ spatialSurfaceDigests,
+ spatialTypes,
+} from "./manifest.js";
+export { spatialFrameSchema } from "./schema.js";
+export {
+ decodeAnchoredFrameSurface,
+ decodeAspectFrameSurface,
+ decodeCanvasSurface,
+ decodeFrameSurface,
+} from "./surface.js";
+export type * from "./types.js";
diff --git a/packages/spatial/src/manifest.ts b/packages/spatial/src/manifest.ts
new file mode 100644
index 00000000..8af8465b
--- /dev/null
+++ b/packages/spatial/src/manifest.ts
@@ -0,0 +1,83 @@
+import { digestOf } from "@narratage/protocol";
+import type { ModuleManifest, ProducerRef, TypeRef } from "@narratage/protocol";
+
+import { spatialImplementationDigests, spatialValidatorDigests } from "./geometry.js";
+import {
+ anchoredFrameProgramSchema,
+ aspectFrameProgramSchema,
+ canvasSpaceSchema,
+ contentFitSchema,
+ fittedContentSchema,
+ frameEdgesProgramSchema,
+ intrinsicExtentSchema,
+ spatialFrameSchema,
+ spatialPathSchema,
+ spatialPointSchema,
+} from "./schema.js";
+
+export const spatialModuleRef = { name: "@narratage/spatial", version: "0.0.0-dev" } as const;
+export const spatialSurfaceDigests = {
+ canvas: digestOf("@narratage/spatial/canvas-surface@1"),
+ frame: digestOf("@narratage/spatial/frame-surface@1"),
+ anchoredFrame: digestOf("@narratage/spatial/anchored-frame-surface@1"),
+ aspectFrame: digestOf("@narratage/spatial/aspect-frame-surface@1"),
+} as const;
+export const spatialTypes = {
+ canvas: { module: spatialModuleRef, name: "CanvasSpace" },
+ point: { module: spatialModuleRef, name: "SpatialPoint" },
+ frame: { module: spatialModuleRef, name: "SpatialFrame" },
+ path: { module: spatialModuleRef, name: "SpatialPath" },
+ extent: { module: spatialModuleRef, name: "IntrinsicExtent" },
+ fit: { module: spatialModuleRef, name: "ContentFit" },
+ fitted: { module: spatialModuleRef, name: "FittedContent" },
+ frameEdgesProgram: { module: spatialModuleRef, name: "FrameEdgesProgram" },
+ anchoredFrameProgram: { module: spatialModuleRef, name: "AnchoredFrameProgram" },
+ aspectFrameProgram: { module: spatialModuleRef, name: "AspectFrameProgram" },
+} satisfies Record<string, TypeRef>;
+export const spatialProducers = {
+ canvasFrame: { module: spatialModuleRef, name: "canvas-frame" },
+ frameEdges: { module: spatialModuleRef, name: "frame-edges" },
+ anchoredFrame: { module: spatialModuleRef, name: "anchored-frame" },
+ aspectFrame: { module: spatialModuleRef, name: "aspect-frame" },
+ fitContent: { module: spatialModuleRef, name: "fit-content" },
+} satisfies Record<string, ProducerRef>;
+
+const validator = (locator: string, digest: ReturnType<typeof digestOf>) => ({
+ abi: "svml.type-validator@1" as const,
+ implementation: { kind: "registered" as const, locator, digest },
+});
+
+export const spatialManifest: ModuleManifest = {
+ format: "svml.module@1",
+ name: spatialModuleRef.name,
+ version: spatialModuleRef.version,
+ dependencies: [],
+ types: [
+ { name: spatialTypes.canvas.name, schema: canvasSpaceSchema, validator: validator("@narratage/spatial/validate-canvas", spatialValidatorDigests.canvas) },
+ { name: spatialTypes.point.name, schema: spatialPointSchema, validator: validator("@narratage/spatial/validate-point", spatialValidatorDigests.point) },
+ { name: spatialTypes.frame.name, schema: spatialFrameSchema, validator: validator("@narratage/spatial/validate-frame", spatialValidatorDigests.frame) },
+ { name: spatialTypes.path.name, schema: spatialPathSchema, validator: validator("@narratage/spatial/validate-path", spatialValidatorDigests.path) },
+ { name: spatialTypes.extent.name, schema: intrinsicExtentSchema, validator: validator("@narratage/spatial/validate-extent", spatialValidatorDigests.extent) },
+ { name: spatialTypes.fit.name, schema: contentFitSchema, validator: validator("@narratage/spatial/validate-fit", spatialValidatorDigests.fit) },
+ { name: spatialTypes.fitted.name, schema: fittedContentSchema, validator: validator("@narratage/spatial/validate-fitted", spatialValidatorDigests.fitted) },
+ { name: spatialTypes.frameEdgesProgram.name, schema: frameEdgesProgramSchema },
+ { name: spatialTypes.anchoredFrameProgram.name, schema: anchoredFrameProgramSchema },
+ { name: spatialTypes.aspectFrameProgram.name, schema: aspectFrameProgramSchema },
+ ],
+ capabilities: [],
+ surfaces: [
+ { name: "canvas", tag: "Canvas", mode: "structured", outputs: [spatialTypes.canvas], implementation: { kind: "trusted-frontend-surface", locator: "@narratage/spatial/canvas-surface", digest: spatialSurfaceDigests.canvas } },
+ { name: "frame", tag: "Frame", mode: "structured", outputs: [spatialTypes.frame, spatialTypes.frameEdgesProgram], implementation: { kind: "trusted-frontend-surface", locator: "@narratage/spatial/frame-surface", digest: spatialSurfaceDigests.frame } },
+ { name: "anchored-frame", tag: "AnchoredFrame", mode: "structured", outputs: [spatialTypes.frame, spatialTypes.anchoredFrameProgram], implementation: { kind: "trusted-frontend-surface", locator: "@narratage/spatial/anchored-frame-surface", digest: spatialSurfaceDigests.anchoredFrame } },
+ { name: "aspect-frame", tag: "AspectFrame", mode: "structured", outputs: [spatialTypes.frame, spatialTypes.extent, spatialTypes.aspectFrameProgram], implementation: { kind: "trusted-frontend-surface", locator: "@narratage/spatial/aspect-frame-surface", digest: spatialSurfaceDigests.aspectFrame } },
+ ],
+ producers: [
+ { name: spatialProducers.canvasFrame.name, inputs: [{ name: "canvas", type: spatialTypes.canvas }], outputs: [{ name: "frame", type: spatialTypes.frame }], needs: [], implementation: { kind: "registered", locator: "@narratage/spatial/canvas-frame", digest: spatialImplementationDigests.canvasFrame } },
+ { name: spatialProducers.frameEdges.name, inputs: [{ name: "parent", type: spatialTypes.frame }, { name: "program", type: spatialTypes.frameEdgesProgram }], outputs: [{ name: "frame", type: spatialTypes.frame }], needs: [], implementation: { kind: "registered", locator: "@narratage/spatial/frame-edges", digest: spatialImplementationDigests.frameEdges } },
+ { name: spatialProducers.anchoredFrame.name, inputs: [{ name: "parent", type: spatialTypes.frame }, { name: "program", type: spatialTypes.anchoredFrameProgram }], outputs: [{ name: "frame", type: spatialTypes.frame }], needs: [], implementation: { kind: "registered", locator: "@narratage/spatial/anchored-frame", digest: spatialImplementationDigests.anchoredFrame } },
+ { name: spatialProducers.aspectFrame.name, inputs: [{ name: "parent", type: spatialTypes.frame }, { name: "extent", type: spatialTypes.extent }, { name: "program", type: spatialTypes.aspectFrameProgram }], outputs: [{ name: "frame", type: spatialTypes.frame }], needs: [], implementation: { kind: "registered", locator: "@narratage/spatial/aspect-frame", digest: spatialImplementationDigests.aspectFrame } },
+ { name: spatialProducers.fitContent.name, inputs: [{ name: "frame", type: spatialTypes.frame }, { name: "extent", type: spatialTypes.extent }, { name: "fit", type: spatialTypes.fit }], outputs: [{ name: "fitted", type: spatialTypes.fitted }], needs: [], implementation: { kind: "registered", locator: "@narratage/spatial/fit-content", digest: spatialImplementationDigests.fitContent } },
+ ],
+};
+export const spatialManifestDigest = digestOf(spatialManifest);
+export const spatialDependency = { module: spatialModuleRef, digest: spatialManifestDigest } as const;
diff --git a/packages/spatial/src/schema.ts b/packages/spatial/src/schema.ts
new file mode 100644
index 00000000..8ada7289
--- /dev/null
+++ b/packages/spatial/src/schema.ts
@@ -0,0 +1,39 @@
+import type { ValueSchema } from "@narratage/protocol";
+
+const number = { kind: "number" } as const;
+const positiveInteger = { kind: "number", integer: true, minimum: 1 } as const;
+const object = (fields: Readonly<Record<string, { readonly schema: ValueSchema; readonly optional?: boolean }>>): ValueSchema => ({ kind: "object", fields });
+const point = object({ x: { schema: { kind: "number", minimum: 0, maximum: 1 } }, y: { schema: { kind: "number", minimum: 0, maximum: 1 } } });
+const pixelPoint = object({ x: { schema: number }, y: { schema: number } });
+const length = object({ unit: { schema: { kind: "string", enum: ["px", "percent"] } }, value: { schema: number } });
+
+export const canvasSpaceSchema = object({
+ contract: { schema: { kind: "literal", value: "svml.canvas-space@1" } },
+ widthPx: { schema: positiveInteger }, heightPx: { schema: positiveInteger },
+ origin: { schema: { kind: "literal", value: "top-left" } },
+ xDirection: { schema: { kind: "literal", value: "right" } },
+ yDirection: { schema: { kind: "literal", value: "down" } },
+ pixelAspect: { schema: { kind: "literal", value: "square" } },
+});
+export const spatialPointSchema = object({ contract: { schema: { kind: "literal", value: "svml.spatial-point@1" } }, xPx: { schema: number }, yPx: { schema: number } });
+export const spatialFrameSchema = object({ contract: { schema: { kind: "literal", value: "svml.spatial-frame@1" } }, xPx: { schema: number }, yPx: { schema: number }, widthPx: { schema: number }, heightPx: { schema: number } });
+const pathCommand: ValueSchema = { kind: "oneOf", variants: [
+ object({ kind: { schema: { kind: "literal", value: "move" } }, xPx: { schema: number }, yPx: { schema: number } }),
+ object({ kind: { schema: { kind: "literal", value: "line" } }, xPx: { schema: number }, yPx: { schema: number } }),
+ object({ kind: { schema: { kind: "literal", value: "quadratic" } }, controlX: { schema: number }, controlY: { schema: number }, xPx: { schema: number }, yPx: { schema: number } }),
+ object({ kind: { schema: { kind: "literal", value: "cubic" } }, control1X: { schema: number }, control1Y: { schema: number }, control2X: { schema: number }, control2Y: { schema: number }, xPx: { schema: number }, yPx: { schema: number } }),
+ object({ kind: { schema: { kind: "literal", value: "close" } } }),
+] };
+export const spatialPathSchema = object({ contract: { schema: { kind: "literal", value: "svml.spatial-path@1" } }, commands: { schema: { kind: "array", minItems: 2, items: pathCommand } } });
+export const intrinsicExtentSchema = object({ contract: { schema: { kind: "literal", value: "svml.intrinsic-extent@1" } }, widthPx: { schema: number }, heightPx: { schema: number } });
+export const contentFitSchema = object({
+ contract: { schema: { kind: "literal", value: "svml.content-fit@1" } },
+ sizing: { schema: { kind: "string", enum: ["contain", "cover", "fit-width", "fit-height", "native", "scale-down", "stretch"] } },
+ framePoint: { schema: point }, contentPoint: { schema: point }, offsetPx: { schema: pixelPoint },
+ constraint: { schema: { kind: "string", enum: ["bounded", "free"] } },
+});
+export const fittedContentSchema = object({ contract: { schema: { kind: "literal", value: "svml.fitted-content@1" } }, contentFrame: { schema: spatialFrameSchema } });
+export const frameEdgesProgramSchema = object({ contract: { schema: { kind: "literal", value: "svml.frame-edges-program@1" } }, left: { schema: length }, top: { schema: length }, right: { schema: length }, bottom: { schema: length } });
+const anchor = { kind: "string", enum: ["top-left", "top-center", "top-right", "middle-left", "center", "middle-right", "bottom-left", "bottom-center", "bottom-right"] } as const;
+export const anchoredFrameProgramSchema = object({ contract: { schema: { kind: "literal", value: "svml.anchored-frame-program@1" } }, x: { schema: length }, y: { schema: length }, width: { schema: length }, height: { schema: length }, anchor: { schema: anchor }, offsetPx: { schema: pixelPoint } });
+export const aspectFrameProgramSchema = object({ contract: { schema: { kind: "literal", value: "svml.aspect-frame-program@1" } }, x: { schema: length }, y: { schema: length }, primary: { schema: { kind: "string", enum: ["width", "height"] } }, size: { schema: length }, anchor: { schema: anchor }, offsetPx: { schema: pixelPoint } });
diff --git a/packages/spatial/src/surface.ts b/packages/spatial/src/surface.ts
new file mode 100644
index 00000000..e7b0f909
--- /dev/null
+++ b/packages/spatial/src/surface.ts
@@ -0,0 +1,209 @@
+import type { AuthorValueRef, GraphFragment } from "@narratage/elaborator";
+import type { CanonicalValue } from "@narratage/protocol";
+import type {
+ SurfaceComponentDraft,
+ StructuredElement,
+ StructuredSurfaceHandler,
+ SurfaceResolvedReference,
+ TextAttributeValue,
+} from "@narratage/text";
+
+import {
+ anchoredFrameFragment,
+ aspectFrameFragment,
+ canvasFrameFragment,
+ frameEdgesFragment,
+} from "./fragment.js";
+import { spatialTypes } from "./manifest.js";
+import { sealCanvasSpace, sealIntrinsicExtent } from "./geometry.js";
+import type {
+ AnchoredFrameProgram,
+ AspectFrameProgram,
+ FrameEdgesProgram,
+ SpatialAnchor,
+ SpatialLength,
+} from "./types.js";
+
+function sameType(left: SurfaceResolvedReference["type"], right: SurfaceResolvedReference["type"]): boolean {
+ return left.module.name === right.module.name && left.module.version === right.module.version && left.name === right.name;
+}
+
+function exact(element: StructuredElement, allowed: readonly string[], required: readonly string[]): void {
+ const unknown = Object.keys(element.attributes).filter((name) => !allowed.includes(name));
+ const missing = required.filter((name) => element.attributes[name] === undefined);
+ if (unknown.length > 0) throw new Error(`${element.name} does not accept ${unknown[0]}.`);
+ if (missing.length > 0) throw new Error(`${element.name} requires ${missing.join(", ")}.`);
+ for (const child of element.children) {
+ if (child.kind === "element" || child.value.trim().length > 0) throw new Error(`${element.name} must be empty.`);
+ }
+}
+
+function text(element: StructuredElement, name: string): string {
+ const value = element.attributes[name];
+ if (typeof value !== "string" || value.trim().length === 0) throw new Error(`${element.name}.${name} must be text.`);
+ return value.trim();
+}
+
+function number(element: StructuredElement, name: string, fallback?: number): number {
+ if (element.attributes[name] === undefined && fallback !== undefined) return fallback;
+ const value = Number(text(element, name));
+ if (!Number.isFinite(value)) throw new Error(`${element.name}.${name} must be finite.`);
+ return value;
+}
+
+function positiveInteger(element: StructuredElement, name: string): number {
+ const value = number(element, name);
+ if (!Number.isSafeInteger(value) || value <= 0) throw new Error(`${element.name}.${name} must be a positive integer.`);
+ return value;
+}
+
+function length(element: StructuredElement, name: string): SpatialLength {
+ const source = text(element, name);
+ const match = /^([+-]?(?:\d+(?:\.\d+)?|\.\d+))(px|%)$/u.exec(source);
+ if (match === null) throw new Error(`${element.name}.${name} must use px or %.`);
+ const value = Number(match[1]);
+ if (!Number.isFinite(value)) throw new Error(`${element.name}.${name} must be finite.`);
+ return { unit: match[2] === "%" ? "percent" : "px", value };
+}
+
+function anchor(element: StructuredElement): SpatialAnchor {
+ const value = text(element, "anchor") as SpatialAnchor;
+ if (!["top-left", "top-center", "top-right", "middle-left", "center", "middle-right", "bottom-left", "bottom-center", "bottom-right"].includes(value)) {
+ throw new Error(`${element.name}.anchor is invalid.`);
+ }
+ return value;
+}
+
+function reference(
+ element: StructuredElement,
+ name: string,
+ resolve: (path: string) => SurfaceResolvedReference | undefined,
+): SurfaceResolvedReference {
+ const value: TextAttributeValue | undefined = element.attributes[name];
+ if (typeof value !== "object" || value.kind !== "reference") throw new Error(`${element.name}.${name} must be a reference.`);
+ const result = resolve(value.path);
+ if (result === undefined) throw new Error(`${element.name}.${name} cannot resolve ${value.path}.`);
+ return result;
+}
+
+type ParentFrame = {
+ readonly ref: AuthorValueRef;
+ readonly components: readonly SurfaceComponentDraft[];
+ readonly fragments: readonly GraphFragment[];
+};
+
+function parentFrame(
+ id: string,
+ element: StructuredElement,
+ parent: SurfaceResolvedReference,
+): ParentFrame {
+ if (sameType(parent.type, spatialTypes.frame)) return { ref: parent.ref, components: [], fragments: [] };
+ if (!sameType(parent.type, spatialTypes.canvas)) throw new Error(`${element.name}.within must reference CanvasSpace or SpatialFrame.`);
+ const output = `${id}.__canvas-frame`;
+ const component = `${id}.__canvas-frame-component`;
+ return {
+ ref: { kind: "component-output", component, output: "frame" },
+ components: [{
+ id: component, fragment: canvasFrameFragment.id,
+ inputs: { canvas: parent.ref }, outputs: { frame: output }, range: element.range,
+ }],
+ fragments: [canvasFrameFragment],
+ };
+}
+
+export const decodeCanvasSurface: StructuredSurfaceHandler = ({ element }) => {
+ exact(element, ["id", "width", "height"], ["id", "width", "height"]);
+ const id = text(element, "id");
+ const canvas = sealCanvasSpace({
+ contract: "svml.canvas-space@1",
+ widthPx: positiveInteger(element, "width"), heightPx: positiveInteger(element, "height"),
+ origin: "top-left", xDirection: "right", yDirection: "down", pixelAspect: "square",
+ });
+ return { records: [{ id, type: spatialTypes.canvas, value: { kind: "inline", value: canvas as unknown as CanonicalValue }, range: element.range }], components: [], fragments: [] };
+};
+
+function frameSurface(
+ element: StructuredElement,
+ resolveReference: (path: string) => SurfaceResolvedReference | undefined,
+ program: FrameEdgesProgram | AnchoredFrameProgram,
+ programType: SurfaceResolvedReference["type"],
+ fragment: typeof frameEdgesFragment | typeof anchoredFrameFragment,
+) {
+ const id = text(element, "id");
+ const parent = parentFrame(id, element, reference(element, "within", resolveReference));
+ const programId = `${id}.__program`;
+ return {
+ records: [{ id: programId, type: programType, value: { kind: "inline" as const, value: program as unknown as CanonicalValue }, range: element.range }],
+ components: [
+ ...parent.components,
+ { id, fragment: fragment.id, inputs: { parent: parent.ref, program: { kind: "record" as const, id: programId } }, outputs: { frame: id }, range: element.range },
+ ],
+ fragments: [...parent.fragments, fragment],
+ };
+}
+
+export const decodeFrameSurface: StructuredSurfaceHandler = ({ element, resolveReference }) => {
+ exact(element, ["id", "within", "left", "top", "right", "bottom"], ["id", "within", "left", "top", "right", "bottom"]);
+ return frameSurface(element, resolveReference, {
+ contract: "svml.frame-edges-program@1",
+ left: length(element, "left"), top: length(element, "top"),
+ right: length(element, "right"), bottom: length(element, "bottom"),
+ }, spatialTypes.frameEdgesProgram, frameEdgesFragment);
+};
+
+export const decodeAnchoredFrameSurface: StructuredSurfaceHandler = ({ element, resolveReference }) => {
+ exact(element, ["id", "within", "x", "y", "width", "height", "anchor", "offset-x", "offset-y"], ["id", "within", "x", "y", "width", "height", "anchor"]);
+ return frameSurface(element, resolveReference, {
+ contract: "svml.anchored-frame-program@1",
+ x: length(element, "x"), y: length(element, "y"),
+ width: length(element, "width"), height: length(element, "height"), anchor: anchor(element),
+ offsetPx: { x: number(element, "offset-x", 0), y: number(element, "offset-y", 0) },
+ }, spatialTypes.anchoredFrameProgram, anchoredFrameFragment);
+};
+
+function aspectExtent(
+ id: string,
+ element: StructuredElement,
+ resolveReference: (path: string) => SurfaceResolvedReference | undefined,
+): { readonly ref: AuthorValueRef; readonly records: readonly { readonly id: string; readonly type: typeof spatialTypes.extent; readonly value: { readonly kind: "inline"; readonly value: CanonicalValue }; readonly range: StructuredElement["range"] }[] } {
+ const raw = element.attributes.aspect;
+ if (typeof raw === "object" && raw.kind === "reference") {
+ const resolved = resolveReference(raw.path);
+ if (resolved === undefined || !sameType(resolved.type, spatialTypes.extent)) throw new Error(`${element.name}.aspect must reference IntrinsicExtent.`);
+ return { ref: resolved.ref, records: [] };
+ }
+ const source = text(element, "aspect");
+ const match = /^(\d+(?:\.\d+)?)\s*\/\s*(\d+(?:\.\d+)?)$/u.exec(source);
+ if (match === null) throw new Error(`${element.name}.aspect must be IntrinsicExtent or width/height.`);
+ const extent = sealIntrinsicExtent({ contract: "svml.intrinsic-extent@1", widthPx: Number(match[1]), heightPx: Number(match[2]) });
+ const extentId = `${id}.__extent`;
+ return { ref: { kind: "record", id: extentId }, records: [{ id: extentId, type: spatialTypes.extent, value: { kind: "inline", value: extent as unknown as CanonicalValue }, range: element.range }] };
+}
+
+export const decodeAspectFrameSurface: StructuredSurfaceHandler = ({ element, resolveReference }) => {
+ exact(element, ["id", "within", "x", "y", "width", "height", "aspect", "anchor", "offset-x", "offset-y"], ["id", "within", "x", "y", "aspect", "anchor"]);
+ const hasWidth = element.attributes.width !== undefined;
+ const hasHeight = element.attributes.height !== undefined;
+ if (hasWidth === hasHeight) throw new Error(`${element.name} requires exactly one of width or height.`);
+ const id = text(element, "id");
+ const parent = parentFrame(id, element, reference(element, "within", resolveReference));
+ const extent = aspectExtent(id, element, resolveReference);
+ const program: AspectFrameProgram = {
+ contract: "svml.aspect-frame-program@1",
+ x: length(element, "x"), y: length(element, "y"),
+ primary: hasWidth ? "width" : "height", size: length(element, hasWidth ? "width" : "height"),
+ anchor: anchor(element), offsetPx: { x: number(element, "offset-x", 0), y: number(element, "offset-y", 0) },
+ };
+ const programId = `${id}.__program`;
+ return {
+ records: [
+ ...extent.records,
+ { id: programId, type: spatialTypes.aspectFrameProgram, value: { kind: "inline" as const, value: program as unknown as CanonicalValue }, range: element.range },
+ ],
+ components: [
+ ...parent.components,
+ { id, fragment: aspectFrameFragment.id, inputs: { parent: parent.ref, extent: extent.ref, program: { kind: "record" as const, id: programId } }, outputs: { frame: id }, range: element.range },
+ ],
+ fragments: [...parent.fragments, aspectFrameFragment],
+ };
+};
diff --git a/packages/spatial/src/types.ts b/packages/spatial/src/types.ts
new file mode 100644
index 00000000..3efd22b5
--- /dev/null
+++ b/packages/spatial/src/types.ts
@@ -0,0 +1,98 @@
+export type CanvasSpace = {
+ readonly contract: "svml.canvas-space@1";
+ readonly widthPx: number;
+ readonly heightPx: number;
+ readonly origin: "top-left";
+ readonly xDirection: "right";
+ readonly yDirection: "down";
+ readonly pixelAspect: "square";
+};
+
+export type SpatialPoint = {
+ readonly contract: "svml.spatial-point@1";
+ readonly xPx: number;
+ readonly yPx: number;
+};
+
+export type SpatialFrame = {
+ readonly contract: "svml.spatial-frame@1";
+ readonly xPx: number;
+ readonly yPx: number;
+ readonly widthPx: number;
+ readonly heightPx: number;
+};
+
+export type SpatialPathCommand =
+ | { readonly kind: "move"; readonly xPx: number; readonly yPx: number }
+ | { readonly kind: "line"; readonly xPx: number; readonly yPx: number }
+ | { readonly kind: "quadratic"; readonly controlX: number; readonly controlY: number; readonly xPx: number; readonly yPx: number }
+ | { readonly kind: "cubic"; readonly control1X: number; readonly control1Y: number; readonly control2X: number; readonly control2Y: number; readonly xPx: number; readonly yPx: number }
+ | { readonly kind: "close" };
+
+export type SpatialPath = {
+ readonly contract: "svml.spatial-path@1";
+ readonly commands: readonly SpatialPathCommand[];
+};
+
+export type IntrinsicExtent = {
+ readonly contract: "svml.intrinsic-extent@1";
+ readonly widthPx: number;
+ readonly heightPx: number;
+};
+
+export type NormalizedPoint = {
+ readonly x: number;
+ readonly y: number;
+};
+
+export type ContentFit = {
+ readonly contract: "svml.content-fit@1";
+ readonly sizing: "contain" | "cover" | "fit-width" | "fit-height" | "native" | "scale-down" | "stretch";
+ readonly framePoint: NormalizedPoint;
+ readonly contentPoint: NormalizedPoint;
+ readonly offsetPx: { readonly x: number; readonly y: number };
+ readonly constraint: "bounded" | "free";
+};
+
+export type FittedContent = {
+ readonly contract: "svml.fitted-content@1";
+ readonly contentFrame: SpatialFrame;
+};
+
+export type SpatialLength = {
+ readonly unit: "px" | "percent";
+ readonly value: number;
+};
+
+export type FrameEdgesProgram = {
+ readonly contract: "svml.frame-edges-program@1";
+ readonly left: SpatialLength;
+ readonly top: SpatialLength;
+ readonly right: SpatialLength;
+ readonly bottom: SpatialLength;
+};
+
+export type SpatialAnchor =
+ | "top-left" | "top-center" | "top-right"
+ | "middle-left" | "center" | "middle-right"
+ | "bottom-left" | "bottom-center" | "bottom-right";
+
+export type AnchoredFrameProgram = {
+ readonly contract: "svml.anchored-frame-program@1";
+ readonly x: SpatialLength;
+ readonly y: SpatialLength;
+ readonly width: SpatialLength;
+ readonly height: SpatialLength;
+ readonly anchor: SpatialAnchor;
+ readonly offsetPx: { readonly x: number; readonly y: number };
+};
+
+export type AspectFrameProgram = {
+ readonly contract: "svml.aspect-frame-program@1";
+ readonly x: SpatialLength;
+ readonly y: SpatialLength;
+ readonly primary: "width" | "height";
+ readonly size: SpatialLength;
+ readonly anchor: SpatialAnchor;
+ readonly offsetPx: { readonly x: number; readonly y: number };
+};
diff --git a/packages/spatial/test/spatial.test.ts b/packages/spatial/test/spatial.test.ts
new file mode 100644
index 00000000..ba81941a
--- /dev/null
+++ b/packages/spatial/test/spatial.test.ts
@@ -0,0 +1,173 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { registerTypeValidatorFacets } from "@narratage/component-kit";
+import { createResolvedClosure, sealBuildRequest, start } from "@narratage/core";
+import { AuthorFrontendRegistry, compileSourceClosure, resolveCompiledSourceExport } from "@narratage/elaborator";
+import type { AuthorSourceUnit } from "@narratage/elaborator";
+import {
+ TextSurfaceRegistry,
+ createTextAuthorFrontend,
+} from "@narratage/text";
+import { createRecordAdmitter, TypeValidatorRegistry } from "@narratage/validation";
+
+import {
+ anchoredFrame,
+ aspectFrame,
+ decodeAnchoredFrameSurface,
+ decodeAspectFrameSurface,
+ decodeCanvasSurface,
+ decodeFrameSurface,
+ fitContent,
+ frameFromEdges,
+ sealSpatialPath,
+ spatialComponent,
+ spatialManifest,
+ spatialModuleRef,
+ spatialProducers,
+ spatialSurfaceDigests,
+ spatialTypes,
+} from "../src/index.js";
+import type { ContentFit, IntrinsicExtent, SpatialAnchor, SpatialFrame } from "../src/index.js";
+
+const parent: SpatialFrame = { contract: "svml.spatial-frame@1", xPx: 100, yPx: 200, widthPx: 800, heightPx: 1200 };
+const portrait: IntrinsicExtent = { contract: "svml.intrinsic-extent@1", widthPx: 600, heightPx: 1000 };
+const landscape: IntrinsicExtent = { contract: "svml.intrinsic-extent@1", widthPx: 1600, heightPx: 900 };
+const centered = (sizing: ContentFit["sizing"], constraint: ContentFit["constraint"] = "bounded"): ContentFit => ({
+ contract: "svml.content-fit@1", sizing,
+ framePoint: { x: 0.5, y: 0.5 }, contentPoint: { x: 0.5, y: 0.5 },
+ offsetPx: { x: 0, y: 0 }, constraint,
+});
+
+test("Frame edges and anchored Frames resolve percentages against the explicit parent", () => {
+ assert.deepEqual(frameFromEdges(parent, {
+ contract: "svml.frame-edges-program@1",
+ left: { unit: "percent", value: 10 }, top: { unit: "percent", value: 5 },
+ right: { unit: "percent", value: 90 }, bottom: { unit: "percent", value: 95 },
+ }), { contract: "svml.spatial-frame@1", xPx: 180, yPx: 260, widthPx: 640, heightPx: 1080 });
+ assert.deepEqual(anchoredFrame(parent, {
+ contract: "svml.anchored-frame-program@1",
+ x: { unit: "percent", value: 50 }, y: { unit: "percent", value: 75 },
+ width: { unit: "percent", value: 50 }, height: { unit: "px", value: 300 },
+ anchor: "center", offsetPx: { x: 10, y: -20 },
+ }), { contract: "svml.spatial-frame@1", xPx: 310, yPx: 930, widthPx: 400, heightPx: 300 });
+});
+
+test("all nine anchors are one point-attachment equation", () => {
+ const expected: Record<SpatialAnchor, readonly [number, number]> = {
+ "top-left": [500, 800], "top-center": [400, 800], "top-right": [300, 800],
+ "middle-left": [500, 750], center: [400, 750], "middle-right": [300, 750],
+ "bottom-left": [500, 700], "bottom-center": [400, 700], "bottom-right": [300, 700],
+ };
+ for (const [anchor, [xPx, yPx]] of Object.entries(expected) as [SpatialAnchor, readonly [number, number]][]) {
+ const frame = anchoredFrame(parent, {
+ contract: "svml.anchored-frame-program@1",
+ x: { unit: "percent", value: 50 }, y: { unit: "percent", value: 50 },
+ width: { unit: "px", value: 200 }, height: { unit: "px", value: 100 },
+ anchor, offsetPx: { x: 0, y: 0 },
+ });
+ assert.deepEqual([frame.xPx, frame.yPx], [xPx, yPx], anchor);
+ }
+});
+
+test("AspectFrame preserves explicit or connected aspect without becoming Media", () => {
+ assert.deepEqual(aspectFrame(parent, portrait, {
+ contract: "svml.aspect-frame-program@1",
+ x: { unit: "percent", value: 100 }, y: { unit: "percent", value: 100 },
+ primary: "width", size: { unit: "percent", value: 30 }, anchor: "bottom-right",
+ offsetPx: { x: 0, y: 0 },
+ }), { contract: "svml.spatial-frame@1", xPx: 660, yPx: 1000, widthPx: 240, heightPx: 400 });
+});
+
+test("every ContentFit sizing mode resolves the independent Content Frame", () => {
+ const frame: SpatialFrame = { contract: "svml.spatial-frame@1", xPx: 0, yPx: 0, widthPx: 400, heightPx: 400 };
+ assert.deepEqual(fitContent(frame, landscape, centered("contain")).contentFrame,
+ { contract: "svml.spatial-frame@1", xPx: 0, yPx: 87.5, widthPx: 400, heightPx: 225 });
+ assert.deepEqual(fitContent(frame, landscape, centered("cover")).contentFrame,
+ { contract: "svml.spatial-frame@1", xPx: -155.55555555555554, yPx: 0, widthPx: 711.1111111111111, heightPx: 400 });
+ assert.equal(fitContent(frame, portrait, centered("fit-width")).contentFrame.heightPx, 666.6666666666666);
+ assert.equal(fitContent(frame, portrait, centered("fit-height")).contentFrame.widthPx, 240);
+ assert.deepEqual(fitContent(frame, portrait, centered("native")).contentFrame,
+ { contract: "svml.spatial-frame@1", xPx: -100, yPx: -300, widthPx: 600, heightPx: 1000 });
+ assert.deepEqual(fitContent({ ...frame, widthPx: 800, heightPx: 1200 }, portrait, centered("scale-down")).contentFrame,
+ { contract: "svml.spatial-frame@1", xPx: 100, yPx: 100, widthPx: 600, heightPx: 1000 });
+ assert.deepEqual(fitContent(frame, portrait, centered("stretch")).contentFrame, frame);
+});
+
+test("unequal focal points and bounded/free policies remain explicit", () => {
+ const frame: SpatialFrame = { contract: "svml.spatial-frame@1", xPx: 10, yPx: 20, widthPx: 400, heightPx: 300 };
+ const fit: ContentFit = {
+ contract: "svml.content-fit@1", sizing: "cover",
+ framePoint: { x: 0.5, y: 0.5 }, contentPoint: { x: 0.8, y: 0.35 },
+ offsetPx: { x: 20, y: -10 }, constraint: "free",
+ };
+ const free = fitContent(frame, landscape, fit).contentFrame;
+ const bounded = fitContent(frame, landscape, { ...fit, constraint: "bounded" }).contentFrame;
+ assert.ok(Math.abs(free.xPx - (-196.66666666666666)) < 1e-9);
+ assert.ok(Math.abs(free.widthPx - 533.3333333333333) < 1e-9);
+ assert.deepEqual([free.yPx, free.heightPx], [55, 300]);
+ assert.ok(Math.abs(bounded.xPx - (-123.33333333333333)) < 1e-9);
+ assert.ok(Math.abs(bounded.widthPx - 533.3333333333333) < 1e-9);
+ assert.deepEqual([bounded.yPx, bounded.heightPx], [20, 300]);
+});
+
+test("Frames may deliberately remain partially or fully off Canvas", () => {
+ const frame = anchoredFrame(parent, {
+ contract: "svml.anchored-frame-program@1",
+ x: { unit: "percent", value: 50 }, y: { unit: "percent", value: 100 },
+ width: { unit: "px", value: 300 }, height: { unit: "px", value: 200 },
+ anchor: "top-center", offsetPx: { x: 0, y: 500 },
+ });
+ assert.equal(frame.yPx, 1900);
+});
+
+test("SpatialPath is typed geometry and rejects an empty or stateful command stream", () => {
+ assert.deepEqual(sealSpatialPath({
+ contract: "svml.spatial-path@1",
+ commands: [{ kind: "move", xPx: 0, yPx: 0 }, { kind: "line", xPx: 100, yPx: 100 }],
+ }).commands.length, 2);
+ assert.throws(() => sealSpatialPath({ contract: "svml.spatial-path@1", commands: [{ kind: "move", xPx: 0, yPx: 0 }, { kind: "close" }] }), /no drawable/u);
+});
+
+function source(text: string): AuthorSourceUnit {
+ return { id: "/project/main.svml", name: "main.svml", text: `<?svml using="@narratage/text@1"?>\n${text}` };
+}
+
+test("self-described Spatial Surfaces produce an explicit Canvas edge and finite Frame graph", async () => {
+ const closure = createResolvedClosure([spatialManifest]);
+ const surfaces = new TextSurfaceRegistry();
+ surfaces.registerStructured(spatialModuleRef, "canvas", spatialSurfaceDigests.canvas, decodeCanvasSurface);
+ surfaces.registerStructured(spatialModuleRef, "frame", spatialSurfaceDigests.frame, decodeFrameSurface);
+ surfaces.registerStructured(spatialModuleRef, "anchored-frame", spatialSurfaceDigests.anchoredFrame, decodeAnchoredFrameSurface);
+ surfaces.registerStructured(spatialModuleRef, "aspect-frame", spatialSurfaceDigests.aspectFrame, decodeAspectFrameSurface);
+ const frontends = new AuthorFrontendRegistry();
+ frontends.register(createTextAuthorFrontend({ registry: surfaces, resolveModule: () => spatialModuleRef }));
+ const validators = new TypeValidatorRegistry();
+ registerTypeValidatorFacets(validators, spatialComponent.validators ?? []);
+ const compiled = await compileSourceClosure({
+ entry: source(`<svml>
+ <import as="space" from="@narratage/spatial@1"/>
+ <space:Canvas id="vertical" width="1080" height="1920"/>
+ <space:Frame id="safe" within={vertical} left="6%" top="4%" right="94%" bottom="96%"/>
+ <space:AnchoredFrame id="card" within={safe} x="50%" y="78%" width="82%" height="28%" anchor="center"/>
+ <space:AspectFrame id="sticker" within={safe} x="100%" y="100%" width="32%" aspect="9/16" anchor="bottom-right"/>
+ </svml>`),
+ closure,
+ frontends,
+ admitRecord: createRecordAdmitter(validators),
+ resolveSource() { throw new Error("Spatial fixture has no source imports."); },
+ });
+ assert.equal(resolveCompiledSourceExport(compiled, "vertical", spatialTypes.canvas).ref.kind, "record");
+ const sticker = resolveCompiledSourceExport(compiled, "sticker", spatialTypes.frame);
+ assert.equal(sticker.ref.kind, "logical-output");
+ const build = start(compiled.program, compiled.elaboration.graph, sealBuildRequest({
+ graph: compiled.elaboration.graph.id,
+ targets: [{ output: sticker.ref.kind === "logical-output" ? sticker.ref.id : "", accepts: "exact" }],
+ satisfactions: [],
+ }));
+ assert.deepEqual(build.plan.steps.map((step) => step.producer.name), [
+ spatialProducers.canvasFrame.name,
+ spatialProducers.frameEdges.name,
+ spatialProducers.aspectFrame.name,
+ ]);
+});
diff --git a/packages/svs/test/source-closure.test.ts b/packages/svs/test/source-closure.test.ts
index b804b56c..8f97714b 100644
--- a/packages/svs/test/source-closure.test.ts
+++ b/packages/svs/test/source-closure.test.ts
@@ -391,7 +391,7 @@ test("the golden studio.svs parses as generic Recipes without video knowledge",
const parsed = parseSvs("studio.svs", maskSourceHeader(source, parseSourceHeader("studio.svs", source)));
assert.equal(parsed.recipes.length, 10);
assert.equal(parsed.recipes.find((recipe) => recipe.value.path === "caption.short-cues")?.value.properties.model, "gemini-2.5-flash");
- assert.equal(parsed.recipes.find((recipe) => recipe.value.path === "film.vertical")?.value.properties.width, 1080);
+ assert.equal(parsed.recipes.find((recipe) => recipe.value.path === "film.vertical")?.value.properties.background, "#09090B");
});
test("SVS rejects duplicate public recipes", () => {
diff --git a/packages/temporal/README.md b/packages/temporal/README.md
new file mode 100644
index 00000000..2c1735d1
--- /dev/null
+++ b/packages/temporal/README.md
@@ -0,0 +1,10 @@
+# `@narratage/temporal`
+
+Focused video-domain temporal projection. It locates authored Selection/Moment occurrences through
+`@narratage/semantic-map`, expands strict `one`/`each` cardinality, evaluates exact rational point
+expressions, intersects them with ProgramSpace and returns validated half-open frame spans.
+
+The package also provides pure sibling-window validation and triggered-stage scheduling. It defines
+no Core branch, renderer behavior, media playback policy, Provider or authoring super-program.
+
+The normative design is [`../../spec/track-authoring.md`](../../spec/track-authoring.md).
diff --git a/packages/temporal/package.json b/packages/temporal/package.json
new file mode 100644
index 00000000..aff3d211
--- /dev/null
+++ b/packages/temporal/package.json
@@ -0,0 +1,18 @@
+{
+ "name": "@narratage/temporal",
+ "version": "0.0.0-dev",
+ "private": true,
+ "type": "module",
+ "exports": {
+ ".": "./src/index.ts"
+ },
+ "svml": {
+ "activation": "./src/activation.ts"
+ },
+ "dependencies": {
+ "@narratage/narrative": "workspace:*",
+ "@narratage/program-space": "workspace:*",
+ "@narratage/protocol": "workspace:*",
+ "@narratage/semantic-map": "workspace:*"
+ }
+}
diff --git a/packages/temporal/src/activation.ts b/packages/temporal/src/activation.ts
new file mode 100644
index 00000000..81c708a7
--- /dev/null
+++ b/packages/temporal/src/activation.ts
@@ -0,0 +1,8 @@
+import { temporalManifest } from "./index.js";
+
+export const svmlPackage = {
+ format: "svml.node-package@1" as const,
+ name: "@narratage/temporal",
+ modules: [{ manifest: temporalManifest }],
+};
+export default svmlPackage;
diff --git a/packages/temporal/src/index.ts b/packages/temporal/src/index.ts
new file mode 100644
index 00000000..9ddccd93
--- /dev/null
+++ b/packages/temporal/src/index.ts
@@ -0,0 +1,21 @@
+import { digestOf } from "@narratage/protocol";
+import type { ModuleManifest } from "@narratage/protocol";
+
+export * from "./location.js";
+export * from "./projection.js";
+export * from "./schedule.js";
+export type * from "./types.js";
+
+export const temporalModuleRef = { name: "@narratage/temporal", version: "0.0.0-dev" } as const;
+export const temporalManifest: ModuleManifest = {
+ format: "svml.module@1",
+ name: temporalModuleRef.name,
+ version: temporalModuleRef.version,
+ dependencies: [],
+ types: [],
+ capabilities: [],
+ surfaces: [],
+ producers: [],
+};
+export const temporalManifestDigest = digestOf(temporalManifest);
+export const temporalDependency = { module: temporalModuleRef, digest: temporalManifestDigest } as const;
diff --git a/packages/temporal/src/location.ts b/packages/temporal/src/location.ts
new file mode 100644
index 00000000..8bd5c01c
--- /dev/null
+++ b/packages/temporal/src/location.ts
@@ -0,0 +1,81 @@
+import type { NarrativeMomentRef, NarrativeSelectionRef } from "@narratage/narrative";
+import { assertProgramSpaceIdentity, programSpaceFrameCount } from "@narratage/program-space";
+import type { ProgramSpace } from "@narratage/program-space";
+import { momentFrames, selectionFrameSpans } from "@narratage/semantic-map";
+import type { CompleteSemanticMap } from "@narratage/semantic-map";
+
+import type {
+ LocatedMomentOccurrence,
+ LocatedProgramOccurrence,
+ LocatedSelectionOccurrence,
+} from "./types.js";
+
+function occurrenceIdentity(owner: string, occurrence: number, seen: Set<number>): string {
+ if (!Number.isSafeInteger(occurrence) || occurrence < 0) {
+ throw new Error(`${owner} contains an invalid occurrence identity.`);
+ }
+ if (seen.has(occurrence)) throw new Error(`${owner} contains duplicate occurrence ${occurrence}.`);
+ seen.add(occurrence);
+ return `${owner}#${occurrence}`;
+}
+
+function assertLocatedFrame(frame: number, totalFrames: number, label: string): void {
+ if (!Number.isSafeInteger(frame) || frame < 0 || frame > totalFrames) {
+ throw new Error(`${label} is outside ProgramSpace.`);
+ }
+}
+
+export function locateSelectionOccurrences(
+ map: CompleteSemanticMap,
+ selection: NarrativeSelectionRef,
+ space: ProgramSpace,
+): readonly LocatedSelectionOccurrence[] {
+ assertProgramSpaceIdentity(space);
+ const totalFrames = programSpaceFrameCount(space);
+ const spans = selectionFrameSpans(map, selection, space);
+ if (spans.length !== selection.occurrences.length) {
+ throw new Error(`NarrativeSelection ${selection.id} location cardinality changed.`);
+ }
+ const seen = new Set<number>();
+ return spans.map((span, index) => {
+ const occurrence = selection.occurrences[index];
+ if (occurrence === undefined) throw new Error(`NarrativeSelection ${selection.id} occurrence is missing.`);
+ assertLocatedFrame(span.startFrame, totalFrames, `NarrativeSelection ${selection.id} start`);
+ assertLocatedFrame(span.endFrameExclusive, totalFrames, `NarrativeSelection ${selection.id} end`);
+ return {
+ id: occurrenceIdentity(selection.id, occurrence.occurrence, seen),
+ occurrence: occurrence.occurrence,
+ start: { frame: span.startFrame },
+ end: { frame: span.endFrameExclusive },
+ };
+ });
+}
+
+export function locateMomentOccurrences(
+ map: CompleteSemanticMap,
+ moment: NarrativeMomentRef,
+ space: ProgramSpace,
+): readonly LocatedMomentOccurrence[] {
+ assertProgramSpaceIdentity(space);
+ const totalFrames = programSpaceFrameCount(space);
+ const frames = momentFrames(map, moment, space);
+ if (frames.length !== moment.occurrences.length) {
+ throw new Error(`NarrativeMoment ${moment.id} location cardinality changed.`);
+ }
+ const seen = new Set<number>();
+ return frames.map((frame, index) => {
+ const occurrence = moment.occurrences[index];
+ if (occurrence === undefined) throw new Error(`NarrativeMoment ${moment.id} occurrence is missing.`);
+ assertLocatedFrame(frame, totalFrames, `NarrativeMoment ${moment.id} cue`);
+ return {
+ id: occurrenceIdentity(moment.id, occurrence.occurrence, seen),
+ occurrence: occurrence.occurrence,
+ cue: { frame },
+ };
+ });
+}
+
+export function locateProgramOccurrence(space: ProgramSpace): LocatedProgramOccurrence {
+ assertProgramSpaceIdentity(space);
+ return { id: "program", start: { frame: 0 }, end: { frame: programSpaceFrameCount(space) } };
+}
diff --git a/packages/temporal/src/projection.ts b/packages/temporal/src/projection.ts
new file mode 100644
index 00000000..59b780e8
--- /dev/null
+++ b/packages/temporal/src/projection.ts
@@ -0,0 +1,204 @@
+import type { NarrativeMomentRef, NarrativeSelectionRef } from "@narratage/narrative";
+import { assertProgramSpaceIdentity, programSpaceFrameCount } from "@narratage/program-space";
+import type { ProgramSpace } from "@narratage/program-space";
+import type { CompleteSemanticMap } from "@narratage/semantic-map";
+
+import { locateMomentOccurrences, locateProgramOccurrence, locateSelectionOccurrences } from "./location.js";
+import {
+ add,
+ compare,
+ durationInFrames,
+ maximum,
+ minimum,
+ quantizeBoundary,
+ rational,
+} from "./rational.js";
+import type { Rational } from "./rational.js";
+import type {
+ FrameSpan,
+ LocatedMomentOccurrence,
+ LocatedProgramOccurrence,
+ LocatedSelectionOccurrence,
+ OccurrenceExpansion,
+ ProjectedOccurrence,
+ TemporalPointExpression,
+ TemporalWindowProjection,
+ WindowRelation,
+} from "./types.js";
+
+type PointEnvironment = {
+ readonly program: LocatedProgramOccurrence;
+ readonly selection?: LocatedSelectionOccurrence;
+ readonly moment?: LocatedMomentOccurrence;
+};
+
+function usesLocalPoint(expression: TemporalPointExpression, source: "selection" | "moment"): boolean {
+ return source === "selection"
+ ? expression.ref === "selection.start" || expression.ref === "selection.end"
+ : expression.ref === "moment.cue";
+}
+
+function selectOccurrences<T extends { readonly id: string }>(
+ occurrences: readonly T[],
+ expansion: OccurrenceExpansion,
+ projection: TemporalWindowProjection,
+ source: "selection" | "moment",
+ owner: string,
+): readonly T[] {
+ if (expansion.kind === "one") {
+ if (occurrences.length !== 1) {
+ throw new Error(`${owner} requires exactly one occurrence; received ${occurrences.length}.`);
+ }
+ return occurrences;
+ }
+ if (occurrences.length === 0) throw new Error(`${owner} requires at least one occurrence.`);
+ if (
+ occurrences.length > 1
+ && !usesLocalPoint(projection.start, source)
+ && !usesLocalPoint(projection.end, source)
+ ) {
+ throw new Error(`${owner} cannot expand an occurrence-invariant projection with each.`);
+ }
+ return occurrences;
+}
+
+function evaluatePoint(
+ expression: TemporalPointExpression,
+ environment: PointEnvironment,
+ space: ProgramSpace,
+): Rational {
+ if (expression.ref === "absolute") return durationInFrames(expression.at, space);
+ let base: number;
+ switch (expression.ref) {
+ case "program.start": base = environment.program.start.frame; break;
+ case "program.end": base = environment.program.end.frame; break;
+ case "selection.start": {
+ if (environment.selection === undefined) throw new Error("selection.start requires a Selection occurrence.");
+ base = environment.selection.start.frame;
+ break;
+ }
+ case "selection.end": {
+ if (environment.selection === undefined) throw new Error("selection.end requires a Selection occurrence.");
+ base = environment.selection.end.frame;
+ break;
+ }
+ case "moment.cue": {
+ if (environment.moment === undefined) throw new Error("moment.cue requires a Moment occurrence.");
+ base = environment.moment.cue.frame;
+ break;
+ }
+ }
+ return expression.offset === undefined
+ ? rational(BigInt(base))
+ : add(rational(BigInt(base)), durationInFrames(expression.offset, space));
+}
+
+export function projectTemporalWindow(
+ projection: TemporalWindowProjection,
+ environment: PointEnvironment,
+ space: ProgramSpace,
+): FrameSpan {
+ assertProgramSpaceIdentity(space);
+ const totalFrames = programSpaceFrameCount(space);
+ const rawStart = evaluatePoint(projection.start, environment, space);
+ const rawEnd = evaluatePoint(projection.end, environment, space);
+ if (compare(rawEnd, rawStart) < 0) throw new Error("Temporal projection produces a reversed raw window.");
+ if (compare(rawEnd, rawStart) === 0) throw new Error("Temporal projection produces a zero raw window.");
+ const lower = rational(0n);
+ const upper = rational(BigInt(totalFrames));
+ const clippedStart = maximum(rawStart, lower);
+ const clippedEnd = minimum(rawEnd, upper);
+ if (compare(clippedEnd, clippedStart) <= 0) {
+ throw new Error("Temporal projection does not intersect ProgramSpace.");
+ }
+ const startFrame = quantizeBoundary(clippedStart);
+ const endFrameExclusive = quantizeBoundary(clippedEnd);
+ if (startFrame < 0 || endFrameExclusive > totalFrames || endFrameExclusive <= startFrame) {
+ throw new Error("Temporal projection is shorter than one frame after quantization.");
+ }
+ return { startFrame, endFrameExclusive };
+}
+
+function projectedId(itemId: string, sourceOccurrenceId: string): string {
+ if (itemId.length === 0) throw new Error("Projected item id must not be empty.");
+ return `${itemId}::${sourceOccurrenceId}`;
+}
+
+export function projectSelectionWindows(input: {
+ readonly itemId: string;
+ readonly map: CompleteSemanticMap;
+ readonly selection: NarrativeSelectionRef;
+ readonly space: ProgramSpace;
+ readonly expansion: OccurrenceExpansion;
+ readonly projection: TemporalWindowProjection;
+}): readonly ProjectedOccurrence[] {
+ const program = locateProgramOccurrence(input.space);
+ const occurrences = selectOccurrences(
+ locateSelectionOccurrences(input.map, input.selection, input.space),
+ input.expansion,
+ input.projection,
+ "selection",
+ `Temporal item ${input.itemId}`,
+ );
+ return occurrences.map((occurrence) => ({
+ id: projectedId(input.itemId, occurrence.id),
+ sourceOccurrenceId: occurrence.id,
+ span: projectTemporalWindow(input.projection, { program, selection: occurrence }, input.space),
+ }));
+}
+
+export function projectMomentWindows(input: {
+ readonly itemId: string;
+ readonly map: CompleteSemanticMap;
+ readonly moment: NarrativeMomentRef;
+ readonly space: ProgramSpace;
+ readonly expansion: OccurrenceExpansion;
+ readonly projection: TemporalWindowProjection;
+}): readonly ProjectedOccurrence[] {
+ const program = locateProgramOccurrence(input.space);
+ const occurrences = selectOccurrences(
+ locateMomentOccurrences(input.map, input.moment, input.space),
+ input.expansion,
+ input.projection,
+ "moment",
+ `Temporal item ${input.itemId}`,
+ );
+ return occurrences.map((occurrence) => ({
+ id: projectedId(input.itemId, occurrence.id),
+ sourceOccurrenceId: occurrence.id,
+ span: projectTemporalWindow(input.projection, { program, moment: occurrence }, input.space),
+ }));
+}
+
+export function projectProgramWindow(input: {
+ readonly itemId: string;
+ readonly space: ProgramSpace;
+ readonly projection: TemporalWindowProjection;
+}): ProjectedOccurrence {
+ const program = locateProgramOccurrence(input.space);
+ return {
+ id: projectedId(input.itemId, program.id),
+ sourceOccurrenceId: program.id,
+ span: projectTemporalWindow(input.projection, { program }, input.space),
+ };
+}
+
+export function assertWindowRelation(
+ occurrences: readonly ProjectedOccurrence[],
+ relation: WindowRelation,
+): readonly ProjectedOccurrence[] {
+ if (relation === "independent") return occurrences;
+ const ordered = [...occurrences].sort((left, right) =>
+ left.span.startFrame - right.span.startFrame
+ || left.span.endFrameExclusive - right.span.endFrameExclusive
+ || left.id.localeCompare(right.id));
+ for (let index = 1; index < ordered.length; index += 1) {
+ const previous = ordered[index - 1];
+ const current = ordered[index];
+ if (previous !== undefined && current !== undefined
+ && current.span.startFrame < previous.span.endFrameExclusive) {
+ throw new Error(`Temporal windows ${previous.id} and ${current.id} overlap under disjoint policy.`);
+ }
+ }
+ return occurrences;
+}
diff --git a/packages/temporal/src/rational.ts b/packages/temporal/src/rational.ts
new file mode 100644
index 00000000..27bd0748
--- /dev/null
+++ b/packages/temporal/src/rational.ts
@@ -0,0 +1,80 @@
+import type { ProgramSpace } from "@narratage/program-space";
+
+import type { TemporalDuration } from "./types.js";
+
+export type Rational = {
+ readonly numerator: bigint;
+ readonly denominator: bigint;
+};
+
+function divisor(left: bigint, right: bigint): bigint {
+ let a = left < 0n ? -left : left;
+ let b = right < 0n ? -right : right;
+ while (b !== 0n) [a, b] = [b, a % b];
+ return a;
+}
+
+export function rational(numerator: bigint, denominator = 1n): Rational {
+ if (denominator === 0n) throw new Error("Temporal rational denominator must not be zero.");
+ const sign = denominator < 0n ? -1n : 1n;
+ const normalizedNumerator = numerator * sign;
+ const normalizedDenominator = denominator * sign;
+ const gcd = divisor(normalizedNumerator, normalizedDenominator);
+ return {
+ numerator: normalizedNumerator / gcd,
+ denominator: normalizedDenominator / gcd,
+ };
+}
+
+export function add(left: Rational, right: Rational): Rational {
+ return rational(
+ left.numerator * right.denominator + right.numerator * left.denominator,
+ left.denominator * right.denominator,
+ );
+}
+
+export function compare(left: Rational, right: Rational): number {
+ const difference = left.numerator * right.denominator - right.numerator * left.denominator;
+ return difference < 0n ? -1 : difference > 0n ? 1 : 0;
+}
+
+export function maximum(left: Rational, right: Rational): Rational {
+ return compare(left, right) >= 0 ? left : right;
+}
+
+export function minimum(left: Rational, right: Rational): Rational {
+ return compare(left, right) <= 0 ? left : right;
+}
+
+function safeInteger(value: number, label: string): bigint {
+ if (!Number.isSafeInteger(value)) throw new Error(`${label} must be a safe integer.`);
+ return BigInt(value);
+}
+
+export function durationInFrames(duration: TemporalDuration, space: ProgramSpace): Rational {
+ const frameNumerator = safeInteger(space.frameRate.numerator, "ProgramSpace frame-rate numerator");
+ const frameDenominator = safeInteger(space.frameRate.denominator, "ProgramSpace frame-rate denominator");
+ switch (duration.unit) {
+ case "frames":
+ return rational(safeInteger(duration.value, "Frame duration"));
+ case "milliseconds":
+ return rational(
+ safeInteger(duration.value, "Millisecond duration") * frameNumerator,
+ 1000n * frameDenominator,
+ );
+ case "seconds": {
+ const numerator = safeInteger(duration.numerator, "Second duration numerator");
+ const denominator = safeInteger(duration.denominator, "Second duration denominator");
+ if (denominator <= 0n) throw new Error("Second duration denominator must be positive.");
+ return rational(numerator * frameNumerator, denominator * frameDenominator);
+ }
+ }
+}
+
+/** Nearest frame boundary; an exact half lands on the later boundary. Input must be non-negative. */
+export function quantizeBoundary(value: Rational): number {
+ if (value.numerator < 0n) throw new Error("Cannot quantize a negative clipped frame boundary.");
+ const rounded = (value.numerator * 2n + value.denominator) / (value.denominator * 2n);
+ if (rounded > BigInt(Number.MAX_SAFE_INTEGER)) throw new Error("Temporal boundary exceeds safe frame arithmetic.");
+ return Number(rounded);
+}
diff --git a/packages/temporal/src/schedule.ts b/packages/temporal/src/schedule.ts
new file mode 100644
index 00000000..146b99ac
--- /dev/null
+++ b/packages/temporal/src/schedule.ts
@@ -0,0 +1,60 @@
+import type { FrameSpan, TriggerPoint, TriggeredSchedule } from "./types.js";
+
+function assertFrame(frame: number, label: string): void {
+ if (!Number.isSafeInteger(frame) || frame < 0) throw new Error(`${label} must be a non-negative frame.`);
+}
+
+function assertSpan(span: FrameSpan): void {
+ assertFrame(span.startFrame, "Triggered schedule outer start");
+ assertFrame(span.endFrameExclusive, "Triggered schedule outer end");
+ if (span.endFrameExclusive <= span.startFrame) throw new Error("Triggered schedule outer window is empty.");
+}
+
+export function resolveTriggeredSchedule(input: {
+ readonly outer: FrameSpan;
+ readonly terminalFrame: number;
+ readonly triggers: readonly TriggerPoint[];
+}): TriggeredSchedule {
+ assertSpan(input.outer);
+ assertFrame(input.terminalFrame, "Triggered schedule terminal");
+ if (input.triggers.length === 0) throw new Error("Triggered schedule requires at least one trigger.");
+ if (input.terminalFrame > input.outer.endFrameExclusive) {
+ throw new Error("Triggered schedule terminal is after the outer window.");
+ }
+ const ids = new Set<string>();
+ let previousFrame: number | undefined;
+ for (const trigger of input.triggers) {
+ if (trigger.id.length === 0 || ids.has(trigger.id)) throw new Error("Triggered schedule ids must be non-empty and unique.");
+ ids.add(trigger.id);
+ assertFrame(trigger.frame, `Triggered schedule ${trigger.id}`);
+ if (trigger.frame < input.outer.startFrame || trigger.frame >= input.terminalFrame) {
+ throw new Error(`Triggered schedule ${trigger.id} is outside [outer.start, terminal).`);
+ }
+ if (previousFrame !== undefined && trigger.frame <= previousFrame) {
+ throw new Error("Triggered schedule points must be strictly increasing in authored order.");
+ }
+ previousFrame = trigger.frame;
+ }
+ const cumulative = input.triggers.map((trigger) => ({
+ id: `cumulative::${trigger.id}`,
+ triggerId: trigger.id,
+ span: { startFrame: trigger.frame, endFrameExclusive: input.outer.endFrameExclusive },
+ }));
+ const exclusive = input.triggers.map((trigger, index) => ({
+ id: `exclusive::${trigger.id}`,
+ triggerId: trigger.id,
+ span: {
+ startFrame: trigger.frame,
+ endFrameExclusive: input.triggers[index + 1]?.frame ?? input.terminalFrame,
+ },
+ }));
+ return {
+ outer: { ...input.outer },
+ terminalFrame: input.terminalFrame,
+ cumulative,
+ exclusive,
+ ...(input.terminalFrame < input.outer.endFrameExclusive
+ ? { settledSuffix: { startFrame: input.terminalFrame, endFrameExclusive: input.outer.endFrameExclusive } }
+ : {}),
+ };
+}
diff --git a/packages/temporal/src/types.ts b/packages/temporal/src/types.ts
new file mode 100644
index 00000000..ff703888
--- /dev/null
+++ b/packages/temporal/src/types.ts
@@ -0,0 +1,77 @@
+export type FramePoint = {
+ readonly frame: number;
+};
+
+export type LocatedSelectionOccurrence = {
+ readonly id: string;
+ readonly occurrence: number;
+ readonly start: FramePoint;
+ readonly end: FramePoint;
+};
+
+export type LocatedMomentOccurrence = {
+ readonly id: string;
+ readonly occurrence: number;
+ readonly cue: FramePoint;
+};
+
+export type LocatedProgramOccurrence = {
+ readonly id: "program";
+ readonly start: FramePoint;
+ readonly end: FramePoint;
+};
+
+/** Exact author duration. Decimal source spelling is reduced before reaching this value. */
+export type TemporalDuration =
+ | { readonly unit: "frames"; readonly value: number }
+ | { readonly unit: "milliseconds"; readonly value: number }
+ | { readonly unit: "seconds"; readonly numerator: number; readonly denominator: number };
+
+export type TemporalPointExpression =
+ | { readonly ref: "program.start"; readonly offset?: TemporalDuration }
+ | { readonly ref: "program.end"; readonly offset?: TemporalDuration }
+ | { readonly ref: "selection.start"; readonly offset?: TemporalDuration }
+ | { readonly ref: "selection.end"; readonly offset?: TemporalDuration }
+ | { readonly ref: "moment.cue"; readonly offset?: TemporalDuration }
+ | { readonly ref: "absolute"; readonly at: TemporalDuration };
+
+export type TemporalWindowProjection = {
+ readonly start: TemporalPointExpression;
+ readonly end: TemporalPointExpression;
+};
+
+export type OccurrenceExpansion =
+ | { readonly kind: "one" }
+ | { readonly kind: "each" };
+
+export type FrameSpan = {
+ readonly startFrame: number;
+ readonly endFrameExclusive: number;
+};
+
+export type ProjectedOccurrence = {
+ readonly id: string;
+ readonly sourceOccurrenceId: string;
+ readonly span: FrameSpan;
+};
+
+export type WindowRelation = "independent" | "disjoint";
+
+export type TriggerPoint = {
+ readonly id: string;
+ readonly frame: number;
+};
+
+export type TriggeredStage = {
+ readonly id: string;
+ readonly triggerId: string;
+ readonly span: FrameSpan;
+};
+
+export type TriggeredSchedule = {
+ readonly outer: FrameSpan;
+ readonly terminalFrame: number;
+ readonly cumulative: readonly TriggeredStage[];
+ readonly exclusive: readonly TriggeredStage[];
+ readonly settledSuffix?: FrameSpan;
+};
diff --git a/packages/temporal/test/temporal.test.ts b/packages/temporal/test/temporal.test.ts
new file mode 100644
index 00000000..40722eeb
--- /dev/null
+++ b/packages/temporal/test/temporal.test.ts
@@ -0,0 +1,197 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import type { NarrativeMomentRef, NarrativeSelectionRef } from "@narratage/narrative";
+import type { ProgramSpace } from "@narratage/program-space";
+import type { CompleteSemanticMap } from "@narratage/semantic-map";
+
+import {
+ assertWindowRelation,
+ locateSelectionOccurrences,
+ projectMomentWindows,
+ projectProgramWindow,
+ projectSelectionWindows,
+ resolveTriggeredSchedule,
+} from "../src/index.js";
+
+const space: ProgramSpace = {
+ contract: "svml.program-space@1",
+ durationSec: 10,
+ frameRate: { numerator: 30, denominator: 1 },
+};
+
+const map: CompleteSemanticMap = {
+ contract: "svml.complete-semantic-map@1",
+ tokens: [],
+ anchors: [
+ { identity: "a", timeSec: 1, frame: 30 },
+ { identity: "b", timeSec: 2, frame: 60 },
+ { identity: "c", timeSec: 3, frame: 90 },
+ { identity: "d", timeSec: 4, frame: 120 },
+ { identity: "late", timeSec: 8, frame: 240 },
+ ],
+};
+
+const selection = (id: string, occurrences: NarrativeSelectionRef["occurrences"]): NarrativeSelectionRef => ({
+ contract: "svml.narrative-selection@1", id, occurrences,
+});
+const moment = (id: string, occurrences: NarrativeMomentRef["occurrences"]): NarrativeMomentRef => ({
+ contract: "svml.narrative-moment@1", id, occurrences,
+});
+const frames = (value: number) => ({ unit: "frames" as const, value });
+const seconds = (numerator: number, denominator = 1) => ({ unit: "seconds" as const, numerator, denominator });
+
+test("one Selection projects exact local points and stable occurrence identity", () => {
+ const result = projectSelectionWindows({
+ itemId: "card",
+ map,
+ selection: selection("proof", [{ occurrence: 7, startAnchorId: "a", endAnchorId: "b" }]),
+ space,
+ expansion: { kind: "one" },
+ projection: { start: { ref: "selection.start" }, end: { ref: "selection.end" } },
+ });
+ assert.deepEqual(result, [{
+ id: "card::proof#7",
+ sourceOccurrenceId: "proof#7",
+ span: { startFrame: 30, endFrameExclusive: 60 },
+ }]);
+});
+
+test("each preserves source order, even when physical time is reversed between occurrences", () => {
+ const result = projectSelectionWindows({
+ itemId: "repeat",
+ map,
+ selection: selection("mentions", [
+ { occurrence: 4, startAnchorId: "c", endAnchorId: "d" },
+ { occurrence: 9, startAnchorId: "a", endAnchorId: "b" },
+ ]),
+ space,
+ expansion: { kind: "each" },
+ projection: { start: { ref: "selection.start" }, end: { ref: "selection.end" } },
+ });
+ assert.deepEqual(result.map((item) => item.sourceOccurrenceId), ["mentions#4", "mentions#9"]);
+ assert.deepEqual(result.map((item) => item.span.startFrame), [90, 30]);
+});
+
+test("strict cardinality and occurrence-invariant each fail instead of choosing or duplicating", () => {
+ const repeated = selection("many", [
+ { occurrence: 0, startAnchorId: "a", endAnchorId: "b" },
+ { occurrence: 1, startAnchorId: "c", endAnchorId: "d" },
+ ]);
+ assert.throws(() => projectSelectionWindows({
+ itemId: "one", map, selection: repeated, space, expansion: { kind: "one" },
+ projection: { start: { ref: "selection.start" }, end: { ref: "selection.end" } },
+ }), /exactly one occurrence/u);
+ assert.throws(() => projectSelectionWindows({
+ itemId: "each", map, selection: repeated, space, expansion: { kind: "each" },
+ projection: { start: { ref: "program.start" }, end: { ref: "program.end" } },
+ }), /occurrence-invariant/u);
+});
+
+test("negative intermediate points clip before nearest half-later frame quantization", () => {
+ const result = projectMomentWindows({
+ itemId: "lead",
+ map,
+ moment: moment("cue", [{ occurrence: 0, anchorId: "a" }]),
+ space,
+ expansion: { kind: "one" },
+ projection: {
+ start: { ref: "moment.cue", offset: seconds(-2) },
+ end: { ref: "moment.cue", offset: { unit: "milliseconds", value: 550 } },
+ },
+ });
+ assert.deepEqual(result[0]?.span, { startFrame: 0, endFrameExclusive: 47 });
+});
+
+test("program and absolute projections use exact rational frame-rate arithmetic", () => {
+ const ntsc: ProgramSpace = {
+ contract: "svml.program-space@1",
+ durationSec: 1.001,
+ frameRate: { numerator: 30_000, denominator: 1_001 },
+ };
+ const result = projectProgramWindow({
+ itemId: "absolute",
+ space: ntsc,
+ projection: {
+ start: { ref: "absolute", at: { unit: "milliseconds", value: 500 } },
+ end: { ref: "absolute", at: seconds(1) },
+ },
+ });
+ assert.deepEqual(result.span, { startFrame: 15, endFrameExclusive: 30 });
+});
+
+test("crossed source anchors are allowed until a projection actually consumes the reversal", () => {
+ const crossed = selection("crossed", [{ occurrence: 0, startAnchorId: "d", endAnchorId: "a" }]);
+ assert.deepEqual(locateSelectionOccurrences(map, crossed, space)[0], {
+ id: "crossed#0", occurrence: 0, start: { frame: 120 }, end: { frame: 30 },
+ });
+ assert.throws(() => projectSelectionWindows({
+ itemId: "identity", map, selection: crossed, space, expansion: { kind: "one" },
+ projection: { start: { ref: "selection.start" }, end: { ref: "selection.end" } },
+ }), /reversed raw window/u);
+ assert.deepEqual(projectSelectionWindows({
+ itemId: "persist", map, selection: crossed, space, expansion: { kind: "one" },
+ projection: { start: { ref: "selection.start" }, end: { ref: "program.end" } },
+ })[0]?.span, { startFrame: 120, endFrameExclusive: 300 });
+});
+
+test("zero, fully outside and sub-frame windows fail atomically", () => {
+ assert.throws(() => projectProgramWindow({
+ itemId: "zero", space,
+ projection: { start: { ref: "program.start" }, end: { ref: "program.start" } },
+ }), /zero raw window/u);
+ assert.throws(() => projectProgramWindow({
+ itemId: "outside", space,
+ projection: { start: { ref: "program.end", offset: frames(1) }, end: { ref: "program.end", offset: frames(2) } },
+ }), /does not intersect/u);
+ assert.throws(() => projectProgramWindow({
+ itemId: "tiny", space,
+ projection: {
+ start: { ref: "absolute", at: seconds(1, 100) },
+ end: { ref: "absolute", at: seconds(7, 500) },
+ },
+ }), /shorter than one frame/u);
+});
+
+test("disjoint validation checks every physical overlap without reordering the result", () => {
+ const occurrences = projectMomentWindows({
+ itemId: "popup", map,
+ moment: moment("hits", [{ occurrence: 9, anchorId: "c" }, { occurrence: 4, anchorId: "a" }]),
+ space, expansion: { kind: "each" },
+ projection: { start: { ref: "moment.cue" }, end: { ref: "moment.cue", offset: seconds(3) } },
+ });
+ assert.equal(assertWindowRelation(occurrences, "independent"), occurrences);
+ assert.throws(() => assertWindowRelation(occurrences, "disjoint"), /overlap under disjoint/u);
+});
+
+test("triggered schedule derives cumulative, exclusive and settled windows from authored order", () => {
+ const result = resolveTriggeredSchedule({
+ outer: { startFrame: 0, endFrameExclusive: 300 },
+ terminalFrame: 240,
+ triggers: [{ id: "one", frame: 30 }, { id: "two", frame: 90 }, { id: "three", frame: 150 }],
+ });
+ assert.deepEqual(result.cumulative.map((item) => item.span), [
+ { startFrame: 30, endFrameExclusive: 300 },
+ { startFrame: 90, endFrameExclusive: 300 },
+ { startFrame: 150, endFrameExclusive: 300 },
+ ]);
+ assert.deepEqual(result.exclusive.map((item) => item.span), [
+ { startFrame: 30, endFrameExclusive: 90 },
+ { startFrame: 90, endFrameExclusive: 150 },
+ { startFrame: 150, endFrameExclusive: 240 },
+ ]);
+ assert.deepEqual(result.settledSuffix, { startFrame: 240, endFrameExclusive: 300 });
+});
+
+test("triggered schedule rejects equal, reversed and out-of-bound points", () => {
+ const outer = { startFrame: 20, endFrameExclusive: 200 };
+ assert.throws(() => resolveTriggeredSchedule({
+ outer, terminalFrame: 180, triggers: [{ id: "a", frame: 40 }, { id: "b", frame: 40 }],
+ }), /strictly increasing/u);
+ assert.throws(() => resolveTriggeredSchedule({
+ outer, terminalFrame: 180, triggers: [{ id: "a", frame: 40 }, { id: "b", frame: 30 }],
+ }), /strictly increasing/u);
+ assert.throws(() => resolveTriggeredSchedule({
+ outer, terminalFrame: 180, triggers: [{ id: "a", frame: 180 }],
+ }), /outside/u);
+});
diff --git a/packages/test-support/video-domain.ts b/packages/test-support/video-domain.ts
index 769319c4..014eaeab 100644
--- a/packages/test-support/video-domain.ts
+++ b/packages/test-support/video-domain.ts
@@ -4,6 +4,7 @@ import { mediaComponent, mediaManifest } from "@narratage/media";
import { narrativeManifest } from "@narratage/narrative";
import { programSpaceManifest } from "@narratage/program-space";
import { semanticMapManifest } from "@narratage/semantic-map";
+import { spatialComponent, spatialManifest } from "@narratage/spatial";
import { speechManifest } from "@narratage/speech";
import { speechEvidenceManifest } from "@narratage/speech-evidence";
import { visualIrManifest } from "@narratage/visual-ir";
@@ -17,8 +18,9 @@ export const videoContractManifests = [
speechManifest,
speechEvidenceManifest,
semanticMapManifest,
+ spatialManifest,
visualIrManifest,
compositionManifest,
] as const;
-export { compositionComponent, mediaComponent };
+export { compositionComponent, mediaComponent, spatialComponent };
diff --git a/packages/text-track/README.md b/packages/text-track/README.md
index 4b0fee6c..b50a6654 100644
--- a/packages/text-track/README.md
+++ b/packages/text-track/README.md
@@ -8,10 +8,12 @@ Text authoring protocol. It proves package-to-IR lowering but does not yet repro
three-box layout, exact-font and layered-decoration capability gate.
An item spanning the complete ProgramSpace is a persistent overlay; a shorter item is timed. They
-are not different Track kinds. The package exposes semantic typography and box parameters rather
-than a rendering callback, arbitrary CSS or cross-Track access.
+are not different Track kinds. Timing is projected through `@narratage/temporal`, and placement is
+an explicit `SpatialFrame` input from `@narratage/spatial`; neither is hidden in the appearance
+Recipe. The package exposes semantic typography rather than a rendering callback, arbitrary CSS or
+cross-Track access.
-The provider-free `<text:Track>` Surface now validates `.svs` Recipes, compiles `during="full"`
-against an explicitly connected ProgramSpace and produces the same TextTrackProgram without
-changing Core, Film, Composition or HyperFrames. Timed semantic windows and exact FontArtifact
-lowering remain pre-freeze work.
+The provider-free `<text:Track>` Surface validates `.svs` Recipes, accepts explicit full or
+Selection timing plus a `SpatialFrame` edge for every Item, and produces the same TextTrackProgram
+without changing Core, Film, Composition or HyperFrames. Exact FontArtifact lowering and the full
+Point/Area/Path Text model remain pre-freeze work.
diff --git a/packages/text-track/package.json b/packages/text-track/package.json
index 9884905e..5c055d64 100644
--- a/packages/text-track/package.json
+++ b/packages/text-track/package.json
@@ -17,7 +17,9 @@
"@narratage/program-space": "workspace:*",
"@narratage/protocol": "workspace:*",
"@narratage/semantic-map": "workspace:*",
+ "@narratage/spatial": "workspace:*",
"@narratage/svs": "workspace:*",
+ "@narratage/temporal": "workspace:*",
"@narratage/text": "workspace:*"
},
"devDependencies": {
diff --git a/packages/text-track/src/component.ts b/packages/text-track/src/component.ts
index 59c9063d..d4dc58a6 100644
--- a/packages/text-track/src/component.ts
+++ b/packages/text-track/src/component.ts
@@ -2,6 +2,7 @@ import type { ComponentPackage } from "@narratage/component-kit";
import type { NarrativeSelection, NarrativeSelectionRef } from "@narratage/narrative";
import type { ProgramSpace } from "@narratage/program-space";
import type { CompleteSemanticMap } from "@narratage/semantic-map";
+import type { SpatialFrame } from "@narratage/spatial";
import type { StoredValue } from "@narratage/protocol";
import { canonicalize } from "@narratage/protocol";
@@ -49,6 +50,7 @@ export const textTrackComponent = {
inline<TextTrackSet>(inputs.set?.value, "TextTrackSet"),
inline<TextTrackHeader>(inputs.header?.value, "TextTrackHeader"),
inline<ProgramSpace>(inputs.space?.value, "ProgramSpace"),
+ inline<SpatialFrame>(inputs.frame?.value, "SpatialFrame"),
inline<TextItemSpec>(inputs.spec?.value, "TextItemSpec"),
)) } }, needs: {},
}),
@@ -62,6 +64,7 @@ export const textTrackComponent = {
inline<CompleteSemanticMap>(inputs.map?.value, "CompleteSemanticMap"),
inline<NarrativeSelectionRef>(inputs.selection?.value, "NarrativeSelection"),
inline<ProgramSpace>(inputs.space?.value, "ProgramSpace"),
+ inline<SpatialFrame>(inputs.frame?.value, "SpatialFrame"),
inline<TextItemSpec>(inputs.spec?.value, "TextItemSpec"),
)) } }, needs: {},
}),
diff --git a/packages/text-track/src/manifest.ts b/packages/text-track/src/manifest.ts
index 50badc96..0fab46d9 100644
--- a/packages/text-track/src/manifest.ts
+++ b/packages/text-track/src/manifest.ts
@@ -2,6 +2,7 @@ import { narrativeDependency, narrativeTypes } from "@narratage/narrative";
import { programSpaceDependency, programSpaceTypes } from "@narratage/program-space";
import { semanticMapDependency, semanticMapTypes } from "@narratage/semantic-map";
import { compositionDependency, compositionTypes } from "@narratage/composition";
+import { spatialDependency, spatialTypes, spatialFrameSchema } from "@narratage/spatial";
import type { Track } from "@narratage/composition";
import { digestOf } from "@narratage/protocol";
import type { ModuleManifest, ProducerRef, TypeRef, ValueSchema } from "@narratage/protocol";
@@ -65,12 +66,7 @@ const textItemSchema = object({
}) },
z: { schema: signedInteger },
tieBreak: { schema: string },
- box: { schema: object({
- xPercent: { schema: number },
- yPercent: { schema: number },
- widthPercent: { schema: positiveNumber },
- heightPercent: { schema: positiveNumber },
- }) },
+ frame: { schema: spatialFrameSchema },
appearance: { schema: textAppearanceSchema },
});
@@ -88,10 +84,7 @@ export const textTrackSpecSchema: ValueSchema = object({
text: { schema: string },
during: { schema: { kind: "literal", value: "full" } },
z: { schema: signedInteger },
- box: { schema: object({
- xPercent: { schema: number }, yPercent: { schema: number },
- widthPercent: { schema: positiveNumber }, heightPercent: { schema: positiveNumber },
- }) },
+ frame: { schema: spatialFrameSchema },
appearance: { schema: textAppearanceSchema },
}) } },
});
@@ -106,10 +99,6 @@ const textItemSpecSchema: ValueSchema = object({
id: { schema: string },
text: { schema: string },
z: { schema: signedInteger },
- box: { schema: object({
- xPercent: { schema: number }, yPercent: { schema: number },
- widthPercent: { schema: positiveNumber }, heightPercent: { schema: positiveNumber },
- }) },
appearance: { schema: textAppearanceSchema },
});
@@ -128,6 +117,7 @@ export const textTrackManifest: ModuleManifest = {
programSpaceDependency,
narrativeDependency,
semanticMapDependency,
+ spatialDependency,
compositionDependency,
],
types: [
@@ -156,6 +146,7 @@ export const textTrackManifest: ModuleManifest = {
{ name: "set", type: textTrackTypes.set },
{ name: "header", type: textTrackTypes.header },
{ name: "space", type: programSpaceTypes.programSpace },
+ { name: "frame", type: spatialTypes.frame },
{ name: "spec", type: textTrackTypes.itemSpec },
],
outputs: [{ name: "set", type: textTrackTypes.set }],
@@ -169,6 +160,7 @@ export const textTrackManifest: ModuleManifest = {
{ name: "map", type: semanticMapTypes.complete },
{ name: "selection", type: narrativeTypes.selection },
{ name: "space", type: programSpaceTypes.programSpace },
+ { name: "frame", type: spatialTypes.frame },
{ name: "spec", type: textTrackTypes.itemSpec },
],
outputs: [{ name: "set", type: textTrackTypes.set }],
diff --git a/packages/text-track/src/program.ts b/packages/text-track/src/program.ts
index f4b40fe7..c7129126 100644
--- a/packages/text-track/src/program.ts
+++ b/packages/text-track/src/program.ts
@@ -1,8 +1,15 @@
import type { NarrativeSelectionRef } from "@narratage/narrative";
import { assertProgramSpaceIdentity, programSpaceFrameCount } from "@narratage/program-space";
import type { ProgramSpace } from "@narratage/program-space";
-import { assertCompleteSemanticMapIdentity, assertNarrativeSelectionIdentity, selectionFrameSpans } from "@narratage/semantic-map";
+import { assertCompleteSemanticMapIdentity, assertNarrativeSelectionIdentity } from "@narratage/semantic-map";
import type { CompleteSemanticMap } from "@narratage/semantic-map";
+import { assertSpatialFrame } from "@narratage/spatial";
+import type { SpatialFrame } from "@narratage/spatial";
+import {
+ assertWindowRelation,
+ projectProgramWindow,
+ projectSelectionWindows,
+} from "@narratage/temporal";
import { assertVisualTrackIdentity, sealVisualTrack } from "@narratage/composition";
import type { VisualStyleDeclaration, VisualTrack } from "@narratage/composition";
import { canonicalize, digestOf } from "@narratage/protocol";
@@ -39,7 +46,7 @@ function normalizeItem(item: TextItem): TextItem {
span: { ...item.span },
z: item.z,
tieBreak: item.tieBreak,
- box: { ...item.box },
+ frame: { ...item.frame },
appearance: { ...item.appearance },
};
}
@@ -112,10 +119,7 @@ export function assertTextTrackProgramIdentity(program: TextTrackProgram, progra
}
if (!Number.isSafeInteger(item.z)) throw new Error(`${item.id} z must be a safe integer.`);
assertNonEmpty(item.tieBreak, `${item.id} tieBreak`);
- for (const [name, value] of Object.entries(item.box)) assertFinite(value, `${item.id} box.${name}`);
- if (item.box.widthPercent <= 0 || item.box.heightPercent <= 0) {
- throw new Error(`${item.id} box width and height must be positive.`);
- }
+ assertSpatialFrame(item.frame);
assertAppearance(item.appearance, `${item.id} appearance`);
}
}
@@ -124,10 +128,10 @@ function rootStyle(item: TextItem): VisualStyleDeclaration[] {
const vertical = item.appearance.verticalAlign ?? "center";
return [
{ name: "position", value: "absolute" },
- { name: "left", value: `${item.box.xPercent}%` },
- { name: "top", value: `${item.box.yPercent}%` },
- { name: "width", value: `${item.box.widthPercent}%` },
- { name: "height", value: `${item.box.heightPercent}%` },
+ { name: "left", value: `${item.frame.xPx}px` },
+ { name: "top", value: `${item.frame.yPx}px` },
+ { name: "width", value: `${item.frame.widthPx}px` },
+ { name: "height", value: `${item.frame.heightPx}px` },
{ name: "box-sizing", value: "border-box" },
{ name: "display", value: "flex" },
{ name: "align-items", value: vertical === "top" ? "flex-start" : vertical === "bottom" ? "flex-end" : "center" },
@@ -171,7 +175,7 @@ function canonicalSpec(value: TextTrackSpec): TextTrackSpec {
text: item.text,
during: "full",
z: item.z,
- box: { ...item.box },
+ frame: { ...item.frame },
appearance: { ...item.appearance },
})),
};
@@ -187,7 +191,7 @@ export function assertTextTrackSpec(spec: TextTrackSpec): void {
throw new Error("TextTrackSpec contains an invalid item.");
}
ids.add(item.id);
- for (const value of Object.values(item.box)) assertFinite(value, `${item.id} box`);
+ assertSpatialFrame(item.frame);
assertAppearance(item.appearance, `${item.id} appearance`);
}
}
@@ -204,7 +208,7 @@ export function compileTextTrackProgram(programSpace: ProgramSpace, spec: TextTr
span: { startFrame: 0, endFrameExclusive: programSpaceFrameCount(programSpace) },
z: item.z,
tieBreak: `${spec.id}:${item.id}`,
- box: item.box,
+ frame: item.frame,
appearance: item.appearance,
})),
});
@@ -256,8 +260,6 @@ export function assertTextItemSpec(value: TextItemSpec): void {
|| value.text.length === 0
|| !Number.isSafeInteger(value.z)
) throw new Error("TextItemSpec is invalid");
- for (const [name, number] of Object.entries(value.box)) assertFinite(number, `${value.id} box.${name}`);
- if (value.box.widthPercent <= 0 || value.box.heightPercent <= 0) throw new Error("TextItemSpec box is invalid");
assertAppearance(value.appearance, `${value.id} appearance`);
}
@@ -292,14 +294,21 @@ function appendItems(
};
}
-function itemFromSpec(spec: TextItemSpec, id: string, span: TextItem["span"], tieBreak: string): TextItem {
+function itemFromSpec(
+ spec: TextItemSpec,
+ frame: SpatialFrame,
+ id: string,
+ span: TextItem["span"],
+ tieBreak: string,
+): TextItem {
+ assertSpatialFrame(frame);
return {
id,
text: spec.text,
span,
z: spec.z,
tieBreak,
- box: spec.box,
+ frame,
appearance: spec.appearance,
};
}
@@ -308,15 +317,22 @@ export function appendFullTextItem(
set: TextTrackSet,
header: TextTrackHeader,
space: ProgramSpace,
+ frame: SpatialFrame,
spec: TextItemSpec,
): TextTrackSet {
assertTextTrackSet(set);
assertTextTrackHeader(header);
assertProgramSpaceIdentity(space);
+ const projected = projectProgramWindow({
+ itemId: spec.id,
+ space,
+ projection: { start: { ref: "program.start" }, end: { ref: "program.end" } },
+ });
return appendItems(set, spec, [itemFromSpec(
spec,
+ frame,
spec.id,
- { startFrame: 0, endFrameExclusive: programSpaceFrameCount(space) },
+ projected.span,
`${header.id}:${spec.id}:1`,
)]);
}
@@ -327,6 +343,7 @@ export function appendSelectedTextItem(
map: CompleteSemanticMap,
selection: NarrativeSelectionRef,
space: ProgramSpace,
+ frame: SpatialFrame,
spec: TextItemSpec,
): TextTrackSet {
assertTextTrackSet(set);
@@ -334,11 +351,19 @@ export function appendSelectedTextItem(
assertCompleteSemanticMapIdentity(map);
assertNarrativeSelectionIdentity(selection);
assertProgramSpaceIdentity(space);
- const spans = selectionFrameSpans(map, selection, space);
- return appendItems(set, spec, spans.map((span, index) => itemFromSpec(
+ const occurrences = assertWindowRelation(projectSelectionWindows({
+ itemId: spec.id,
+ map,
+ selection,
+ space,
+ expansion: { kind: "each" },
+ projection: { start: { ref: "selection.start" }, end: { ref: "selection.end" } },
+ }), "disjoint");
+ return appendItems(set, spec, occurrences.map((occurrence, index) => itemFromSpec(
spec,
- spans.length === 1 ? spec.id : `${spec.id}:${index + 1}`,
- span,
+ frame,
+ occurrences.length === 1 ? spec.id : occurrence.id,
+ occurrence.span,
`${header.id}:${spec.id}:${index + 1}`,
)));
}
diff --git a/packages/text-track/src/surface.ts b/packages/text-track/src/surface.ts
index 6481f59e..e7d56efd 100644
--- a/packages/text-track/src/surface.ts
+++ b/packages/text-track/src/surface.ts
@@ -3,6 +3,7 @@ import type { NarrativeSelection } from "@narratage/narrative";
import { programSpaceTypes } from "@narratage/program-space";
import { semanticMapTypes } from "@narratage/semantic-map";
import { compositionTypes } from "@narratage/composition";
+import { spatialTypes } from "@narratage/spatial";
import { sealGraphFragment } from "@narratage/elaborator";
import type { FragmentOperation } from "@narratage/elaborator";
import { svsRecipeType } from "@narratage/svs";
@@ -19,6 +20,7 @@ const operation = (id: string) => ({ kind: "fragment-operation" as const, operat
type SurfaceItem = {
readonly suffix: string;
readonly specName: string;
+ readonly frameName: string;
readonly selectionName?: string;
};
@@ -36,7 +38,10 @@ function createTextTrackSurfaceFragment(id: string, items: readonly SurfaceItem[
operations.push(item.selectionName === undefined ? {
id: operationId,
producer: textTrackProducers.appendFull,
- inputs: { set: operation(current), header: input("header"), space: input("space"), spec: input(item.specName) },
+ inputs: {
+ set: operation(current), header: input("header"), space: input("space"),
+ frame: input(item.frameName), spec: input(item.specName),
+ },
result: { kind: "output", name: "set" },
} : {
id: operationId,
@@ -47,6 +52,7 @@ function createTextTrackSurfaceFragment(id: string, items: readonly SurfaceItem[
map: input("map"),
selection: input(item.selectionName),
space: input("space"),
+ frame: input(item.frameName),
spec: input(item.specName),
},
result: { kind: "output", name: "set" },
@@ -58,7 +64,8 @@ function createTextTrackSurfaceFragment(id: string, items: readonly SurfaceItem[
{ id: "text:render", producer: textTrackProducers.render, inputs: { space: input("space"), program: operation("text:finalize") }, result: { kind: "output", name: "track" } },
);
const semanticInputs = ["space", "header", ...(selected.length === 0 ? [] : ["map"]),
- ...items.flatMap((item) => [item.specName, ...(item.selectionName === undefined ? [] : [item.selectionName])])];
+ ...items.flatMap((item) => [item.frameName, item.specName,
+ ...(item.selectionName === undefined ? [] : [item.selectionName])])];
return sealGraphFragment({
name: `@narratage/text-track/surface/${id}@1`,
inputs: [
@@ -66,6 +73,7 @@ function createTextTrackSurfaceFragment(id: string, items: readonly SurfaceItem[
{ name: "header", type: textTrackTypes.header },
...(selected.length === 0 ? [] : [{ name: "map", type: semanticMapTypes.complete }]),
...items.flatMap((item) => [
+ { name: item.frameName, type: spatialTypes.frame },
{ name: item.specName, type: textTrackTypes.itemSpec },
...(item.selectionName === undefined ? [] : [{ name: item.selectionName, type: narrativeTypes.selection }]),
]),
@@ -134,7 +142,7 @@ export const decodeTextTrackSurface: StructuredSurfaceHandler = ({ element, reso
}
if (!child.name.endsWith(":Item") && child.name !== "Item") throw new Error(`${element.name} accepts only Item children`);
itemIndex += 1;
- exact(child, ["text", "during", "appearance"]);
+ exact(child, ["text", "during", "frame", "appearance"]);
const rawDuring = child.attributes.during;
const selection = typeof rawDuring === "string"
? (() => {
@@ -143,7 +151,8 @@ export const decodeTextTrackSurface: StructuredSurfaceHandler = ({ element, reso
})()
: ref(child, "during", narrativeTypes.selection, resolveReference);
const appearance = recipe(ref(child, "appearance", svsRecipeType, resolveReference));
- const expected = ["align", "fill", "font", "height", "size", "stack-order", "tracking", "weight", "width", "x", "y"];
+ const frame = ref(child, "frame", spatialTypes.frame, resolveReference);
+ const expected = ["align", "fill", "font", "size", "stack-order", "tracking", "weight"];
if (Object.keys(appearance.properties).sort().join("\0") !== expected.sort().join("\0")) throw new Error(`Text Recipe requires exactly ${expected.join(", ")}`);
const align = propString(appearance, "align");
if (align !== "left" && align !== "center" && align !== "right") throw new Error("Text Recipe align is invalid");
@@ -155,10 +164,6 @@ export const decodeTextTrackSurface: StructuredSurfaceHandler = ({ element, reso
id: `item-${suffix}`,
text: text(child, "text"),
z: propNumber(appearance, "stack-order"),
- box: {
- xPercent: propNumber(appearance, "x") * 100, yPercent: propNumber(appearance, "y") * 100,
- widthPercent: propNumber(appearance, "width") * 100, heightPercent: propNumber(appearance, "height") * 100,
- },
appearance: {
color: propString(appearance, "fill"), fontSizePx: propNumber(appearance, "size"),
fontFamily: propString(appearance, "font"), fontWeight: propNumber(appearance, "weight"),
@@ -170,6 +175,8 @@ export const decodeTextTrackSurface: StructuredSurfaceHandler = ({ element, reso
suffix,
specId,
specName: `item-${suffix}-spec`,
+ frame,
+ frameName: `item-${suffix}-frame`,
...(selection === undefined ? {} : { selection, selectionName: `item-${suffix}-selection` }),
}];
});
@@ -184,6 +191,7 @@ export const decodeTextTrackSurface: StructuredSurfaceHandler = ({ element, reso
const fragmentItems: SurfaceItem[] = items.map((item) => ({
suffix: item.suffix,
specName: item.specName,
+ frameName: item.frameName,
...(item.selectionName === undefined ? {} : { selectionName: item.selectionName }),
}));
const fragment = createTextTrackSurfaceFragment(id, fragmentItems);
@@ -197,6 +205,7 @@ export const decodeTextTrackSurface: StructuredSurfaceHandler = ({ element, reso
header: { kind: "record", id: headerId },
...(map === undefined ? {} : { map: map.ref }),
...Object.fromEntries(items.flatMap((item) => [
+ [item.frameName, item.frame.ref],
[item.specName, { kind: "record" as const, id: item.specId }],
...(item.selection === undefined ? [] : [[item.selectionName!, item.selection.ref] as const]),
])),
diff --git a/packages/text-track/src/types.ts b/packages/text-track/src/types.ts
index 978d5fb7..4a9a93bd 100644
--- a/packages/text-track/src/types.ts
+++ b/packages/text-track/src/types.ts
@@ -1,11 +1,5 @@
import type { FrameSpan, Track } from "@narratage/composition";
-
-export type TextBox = {
- readonly xPercent: number;
- readonly yPercent: number;
- readonly widthPercent: number;
- readonly heightPercent: number;
-};
+import type { SpatialFrame } from "@narratage/spatial";
export type TextAppearance = {
readonly color: string;
@@ -27,7 +21,7 @@ export type TextItem = {
readonly span: FrameSpan;
readonly z: number;
readonly tieBreak: string;
- readonly box: TextBox;
+ readonly frame: SpatialFrame;
readonly appearance: TextAppearance;
};
@@ -46,7 +40,7 @@ export type TextTrackSpec = {
readonly text: string;
readonly during: "full";
readonly z: number;
- readonly box: TextBox;
+ readonly frame: SpatialFrame;
readonly appearance: TextAppearance;
}[];
};
@@ -57,13 +51,12 @@ export type TextTrackHeader = {
readonly id: string;
};
-/** Appearance and content are authored here; timing remains an explicit graph input. */
+/** Appearance and content are authored here; timing and placement remain explicit graph inputs. */
export type TextItemSpec = {
readonly contract: "svml.text-item-spec@1";
readonly id: string;
readonly text: string;
readonly z: number;
- readonly box: TextBox;
readonly appearance: TextAppearance;
};
diff --git a/packages/text-track/test/text-track.test.ts b/packages/text-track/test/text-track.test.ts
index 20c380d5..1b998423 100644
--- a/packages/text-track/test/text-track.test.ts
+++ b/packages/text-track/test/text-track.test.ts
@@ -36,7 +36,7 @@ test("persistent and timed text are ordinary Presents in one VisualTrack", () =>
span: { startFrame: 0, endFrameExclusive: 150 },
z: 90,
tieBreak: "watermark",
- box: { xPercent: 70, yPercent: 4, widthPercent: 25, heightPercent: 8 },
+ frame: { contract: "svml.spatial-frame@1", xPx: 756, yPx: 76.8, widthPx: 270, heightPx: 153.6 },
appearance: { color: "#ffffff", fontSizePx: 32, fontWeight: 700, align: "right" },
},
{
@@ -45,7 +45,7 @@ test("persistent and timed text are ordinary Presents in one VisualTrack", () =>
span: { startFrame: 30, endFrameExclusive: 90 },
z: 55,
tieBreak: "callout",
- box: { xPercent: 10, yPercent: 65, widthPercent: 80, heightPercent: 12 },
+ frame: { contract: "svml.spatial-frame@1", xPx: 108, yPx: 1248, widthPx: 864, heightPx: 230.4 },
appearance: {
color: "#111111",
fontSizePx: 48,
@@ -96,7 +96,7 @@ test("TextTrackProgram rejects a frame span outside its ProgramSpace", () => {
span: { startFrame: 149, endFrameExclusive: 151 },
z: 1,
tieBreak: "late",
- box: { xPercent: 0, yPercent: 0, widthPercent: 100, heightPercent: 10 },
+ frame: { contract: "svml.spatial-frame@1", xPx: 0, yPx: 0, widthPx: 1080, heightPx: 192 },
appearance: { color: "#ffffff", fontSizePx: 24 },
}],
});
@@ -139,7 +139,6 @@ test("a selected Text Item is located only through explicit Selection and Semant
id: "meaning",
text: "MEANING",
z: 80,
- box: { xPercent: 10, yPercent: 10, widthPercent: 80, heightPercent: 10 },
appearance: { color: "#ffffff", fontSizePx: 48 },
});
const program = finalizeTextTrack(header, appendSelectedTextItem(
@@ -148,6 +147,7 @@ test("a selected Text Item is located only through explicit Selection and Semant
map,
selection,
space,
+ { contract: "svml.spatial-frame@1", xPx: 108, yPx: 192, widthPx: 864, heightPx: 192 },
spec,
));
assert.deepEqual(program.items.map((item) => item.span), [{ startFrame: 30, endFrameExclusive: 60 }]);
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 2f6746e0..8903bcb6 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -104,6 +104,9 @@ importers:
'@narratage/semantic-map':
specifier: workspace:*
version: link:packages/semantic-map
+ '@narratage/spatial':
+ specifier: workspace:*
+ version: link:packages/spatial
'@narratage/speech':
specifier: workspace:*
version: link:packages/speech
@@ -122,6 +125,9 @@ importers:
'@narratage/svs':
specifier: workspace:*
version: link:packages/svs
+ '@narratage/temporal':
+ specifier: workspace:*
+ version: link:packages/temporal
'@narratage/text-track':
specifier: workspace:*
version: link:packages/text-track
@@ -588,6 +594,9 @@ importers:
'@narratage/protocol':
specifier: workspace:*
version: link:../protocol
+ '@narratage/spatial':
+ specifier: workspace:*
+ version: link:../spatial
'@narratage/svs':
specifier: workspace:*
version: link:../svs
@@ -1824,6 +1833,24 @@ importers:
packages/source: {}
+ packages/spatial:
+ dependencies:
+ '@narratage/component-kit':
+ specifier: workspace:*
+ version: link:../component-kit
+ '@narratage/elaborator':
+ specifier: workspace:*
+ version: link:../elaborator
+ '@narratage/protocol':
+ specifier: workspace:*
+ version: link:../protocol
+ '@narratage/text':
+ specifier: workspace:*
+ version: link:../text
+ '@narratage/validation':
+ specifier: workspace:*
+ version: link:../validation
+
packages/speech:
dependencies:
'@narratage/media':
@@ -2005,6 +2032,21 @@ importers:
specifier: workspace:*
version: link:../text
+ packages/temporal:
+ dependencies:
+ '@narratage/narrative':
+ specifier: workspace:*
+ version: link:../narrative
+ '@narratage/program-space':
+ specifier: workspace:*
+ version: link:../program-space
+ '@narratage/protocol':
+ specifier: workspace:*
+ version: link:../protocol
+ '@narratage/semantic-map':
+ specifier: workspace:*
+ version: link:../semantic-map
+
packages/text:
dependencies:
'@narratage/core':
diff --git a/spec/audio-track.md b/spec/audio-track.md
new file mode 100644
index 00000000..1324ec82
--- /dev/null
+++ b/spec/audio-track.md
@@ -0,0 +1,251 @@
+# SVML Audio Track Authoring
+
+Status: design authority for the generic official Audio Track package. It is not implemented by an
+author Surface yet and is not a frozen public ABI.
+
+## Purpose
+
+`@narratage/audio-track` lets an author place already selected and normalized audio material into
+ProgramSpace. Music, sound effects, additional voice-over and source audio are ordinary peers. The
+package owns no privileged base lane and Composition mixes its result through the existing
+[`AudioTrack`](./track-composition.md) terminal contract.
+
+This is a video-domain author package, not a Core primitive, Runtime service or Provider. The
+separation is:
+
+```text
+explicit media source ─> inspect/select/normalize ─> SynchronizedMedia
+ │
+Narrative points / ProgramSpace ─> temporal window ─────┼─> Audio Track Program
+source trim ─> occupancy ─> level/fades ────────────────┘ │
+ ▼
+ AudioTrack
+ │
+ ▼
+ audio plan -> Provider
+```
+
+Core sees fixed graph inputs and one output Record. It does not know clips, buses, music, speech,
+looping, fading or mixing.
+
+## 1. Input truth
+
+Every audio item receives its material through an explicit graph edge. A first implementation
+should consume `SynchronizedMedia` from `@narratage/media` and require its normalized audio member:
+
+- 48 kHz;
+- stereo;
+- signed 16-bit PCM WAV;
+- exact sample-frame count;
+- preserved source level.
+
+An MP4 merely containing AAC is not an audio item. The author graph must explicitly inspect the
+container, select an audio stream and normalize it. Likewise, a generated speech file does not
+become `SpeechAudioBasis` merely because it contains a voice.
+
+The Audio Track lowerer may derive the terminal Artifact duration from the normalized sample-frame
+count. It must not copy source identities, Narrative digests, provider names or other lineage into
+the clip. Those relations remain graph edges and Derivations.
+
+Do not introduce a new public `AudioMaterial` Type merely to shorten one edge. If several unrelated
+packages later need a first-class canonical-audio value, that focused intrinsic Type belongs in
+`@narratage/media`; it still does not belong in Core or an umbrella contracts package.
+
+## 2. Author Program
+
+The package owns an arbitrary-length collection of independent items. Conceptually each item has:
+
+```ts
+type AudioItemProgram = {
+ readonly id: string;
+ readonly source: SynchronizedMediaInput;
+ readonly temporal: TemporalBinding;
+ readonly trim?: AudioSourceTrim;
+ readonly occupancy: AudioOccupancy;
+ readonly mix: AudioItemMix;
+};
+```
+
+These are package-level concerns. They are not new fields on Core Operations or the terminal
+`AudioTrack` contract.
+
+An illustrative author Surface may remain compact:
+
+```xml
+<audio:Track id="mix">
+ <audio:Clip
+ source={music.media}
+ during={program}
+ playback="loop"
+ gain={0.28}
+ fade-in="800ms"
+ fade-out="1200ms"
+ />
+
+ <audio:Clip
+ source={impact.media}
+ at={story.moment.reveal}
+ for="420ms"
+ playback="once"
+ />
+</audio:Track>
+```
+
+This spelling is illustrative rather than a frozen Surface. `during`, `at` and `for` must lower to
+the shared point-expression and window-projection algebra; they cannot create a second timing
+engine.
+
+## 3. Temporal placement
+
+Audio uses the same rules as [`track-authoring.md`](./track-authoring.md):
+
+1. locate Selection, Moment or Program points;
+2. expand `one` or `each` occurrences;
+3. project a directed candidate window;
+4. intersect and validate it against ProgramSpace;
+5. apply audio source trim and occupancy;
+6. lower the result to frame-exact target spans and exact source samples.
+
+Audio items are independent. Overlapping projected windows mix; they are never clipped according
+to authoring order, auto-stitched, deduplicated or treated as competing alternatives. Several Audio
+Track values behave the same as several overlapping items in one Audio Track.
+
+ProgramSpace frame boundaries are converted to 48 kHz sample boundaries by the one deterministic
+rule already owned by the media pipeline. The author package must not implement another seconds-to-
+samples rounding path.
+
+## 4. Source trim
+
+Source trim defines the effective intrinsic interval before occupancy. It is an explicit head and
+optional tail within the exact normalized sample domain. Author-facing seconds or frames are
+quantized once into sample boundaries.
+
+The lowerer rejects:
+
+- a negative or out-of-source boundary;
+- an end not greater than the start;
+- an empty effective interval;
+- an unavailable audio member;
+- a second, package-private interpretation of source duration.
+
+Source trim is not target timing. Moving a target window never silently changes which source region
+was authored, except where the selected occupancy policy explicitly aligns or retimes it.
+
+## 5. Audio occupancy
+
+Audio has its own truthful occupancy vocabulary. It must not reuse the visual fiction of holding one
+sample forever.
+
+```ts
+type AudioOccupancy =
+ | { readonly mode: "once"; readonly align: "start" | "end" }
+ | { readonly mode: "loop"; readonly align: "start" | "end" }
+ | {
+ readonly mode: "stretch";
+ readonly minRate: number;
+ readonly maxRate: number;
+ readonly pitch: "preserve";
+ };
+```
+
+The laws are:
+
+| Policy | Effective source shorter than window | Effective source longer than window |
+|---|---|---|
+| `once/start` | play at the start, then silence | play the source head and truncate at the window end |
+| `once/end` | silence first, then play to the end | play the source tail and end at the window end |
+| `loop/start` | repeat from the source-head phase | play the source head and truncate |
+| `loop/end` | choose phase so the source tail meets the window end | play the source tail |
+| `stretch` | slow into the complete window | accelerate into the complete window |
+
+`once` replaces the old ambiguous `native` / `finish` behavior. End alignment is not reverse
+playback. `loop/end` changes loop phase; it does not reverse samples. `stretch` is pitch-preserving,
+must stay inside the authored rate bounds and fails rather than silently applying a faster rate and
+then truncating. The old `fit_base` rule—speed up by at most 1.1x and silently cut the rest—is
+retired.
+
+Explicit silence is represented by the absence of a clip over that interval. Padding a file with
+silence is a separate media transformation when the padded bytes themselves matter.
+
+## 6. Level and fades
+
+The first author contract needs only three orthogonal controls:
+
+- non-negative linear `gain`;
+- `fadeIn` over the audible rendered interval;
+- `fadeOut` over the audible rendered interval.
+
+Zero gain is explicit silence. A UI or recipe may expose decibels, but conversion to terminal linear
+gain is deterministic and package-owned. Fade durations must be non-negative, cannot exceed the
+audible interval and cannot secretly expand the target window.
+
+There is no implicit loudness normalization, limiter, compressor, sidechain ducking, crossfade or
+automatic music-bed behavior. Those are legitimate future audio-processing or mix Programs, but
+they must consume explicit inputs and make their behavior author-visible. A runtime or Provider may
+not add them as an environment preference.
+
+The current terminal `bus: speech | music | sfx | source` field is copied into the audio plan but
+does not affect rendering. The official author package must not attach hidden behavior to this dead
+label. Before the public Track freeze it should either be removed, or be replaced by an explicit
+mix-routing contract that has a real downstream consumer. Merely naming a clip `music` cannot cause
+ducking.
+
+## 7. Lowering and execution
+
+The deterministic author package lowers every realized item to an ordinary terminal `AudioClip`:
+
+- target `span` from temporal projection;
+- canonical WAV Artifact from the normalized input;
+- exact source offset and playback rate from trim/occupancy;
+- linear gain and fades from presentation.
+
+Composition validates the Audio Track against an explicitly connected ProgramSpace. The media
+pipeline then compiles all peer Audio Tracks into one content-addressed `AudioProgramPlan`. Local
+FFmpeg, Lambda or another Provider executes that same plan; Provider placement cannot reinterpret
+the mix.
+
+The package emits one `AudioTrack` even when it owns many clips. That is an author-component output,
+not a privileged lane. A package that naturally owns one visual hit and one sound hit may emit peer
+`VisualTrack` and `AudioTrack` outputs from one Fragment, while Film receives both through ordinary
+edges.
+
+## 8. Twinit migration audit
+
+Retain:
+
+- arbitrary audio inputs;
+- Program-full, Selection, Moment and absolute placement;
+- overlapping music/SFX/voice contributions;
+- per-item gain and fades;
+- one-shot, loop and bounded pitch-preserving stretch;
+- explicit source trim and start/end alignment.
+
+Retire:
+
+- dynamic numbered ports as the saved author truth;
+- `z_index` on audio;
+- implicit full timing hidden in a node executor;
+- config-row priority clipping;
+- `fit_base` and its silent speed-then-truncate behavior;
+- `fill: freeze` for audio;
+- automatic extraction of whatever audio happens to be inside a video;
+- inert bus labels and hidden mastering.
+
+## 9. Implementation and acceptance
+
+Implementation should wait for the shared `@narratage/temporal` package, then proceed without a
+Core, Composition or Provider change:
+
+1. add the `@narratage/audio-track` author package and self-described Surface;
+2. consume explicit normalized `SynchronizedMedia` inputs;
+3. implement sample-exact trim and every occupancy law;
+4. lower to the existing terminal `AudioTrack`;
+5. add graph tests for arbitrary item counts and Selection/Moment `one` / `each`;
+6. add sample-level tests for shorter/equal/longer sources, both alignments, loops, stretch bounds
+ and fades;
+7. prove two overlapping items and two peer Audio Tracks produce the same planned mix facts;
+8. prove a different local/remote media Provider receives the identical `AudioProgramPlan`.
+
+The migration is incomplete if adding this package requires a Core branch, a Film audio family, a
+new queue, a Provider name in SVML or a hidden Base-audio rule.
+
diff --git a/spec/caption-program.md b/spec/caption-program.md
index 7f2fec2b..7f10ebe1 100644
--- a/spec/caption-program.md
+++ b/spec/caption-program.md
@@ -89,6 +89,7 @@ Authors do not need a fake `@whole` Selection or a complement.
<caption:Program id="captions" display={story.caption} default={plain}>
<caption:Use role="ALICE" style={alice}/>
<caption:Use words={story.caption.selection.special} style={impact}/>
+ <caption:Mute words={story.caption.selection.private}/>
</caption:Program>
```
@@ -97,6 +98,21 @@ the display-sequence identity and ordered Word-id runs, not copied text. A run n
Segment or Turn boundary. All runs are disjoint and partition the display Words exactly once, and
no run may split an Atom.
+`Mute` consumes the same Caption-specific whole-Atom word subset as `Use`. Multiple `Mute`
+children form one ordered union, so one Program can hide any number of disconnected authored
+ranges. `Mute` is post-planning visibility intent: muted Atoms remain in the immutable display
+universe and `CaptionPlan`, never enter the planner prompt as an instruction, and never cause Cue
+replanning. The common timing join removes muted Atoms from the already-planned timed Cue while
+preserving that Cue's identity and original time span; a Cue with no visible Atom is absent from the
+timed visual projection. Style-family renderers therefore share this behavior without each
+inventing their own mask semantics. The common package also exports the same idempotent operation
+for defensive direct renderer calls.
+
+This is deliberately not a generic temporal mask. Script has already projected the author's
+Selection into the exact display-word subset, so Caption need not convert words to time and then
+guess them back from overlapping windows. A `Mute` selecting only part of a multiword Dual Text
+Atom is rejected by the same indivisibility rule as a Style application.
+
`display={story.caption}` is a real graph edge. Planner, timing and rendering declare their own
edges to the same value only when they need it.
@@ -162,6 +178,7 @@ Caption v1 does not define:
- implicit model or Provider routing;
- automatic cache reuse;
- estimated display-word timing;
+- planner-visible or Core-owned Caption mute semantics;
- a global Caption layer in Composition;
- field-specific semantics in Core.
diff --git a/spec/deck-track.md b/spec/deck-track.md
new file mode 100644
index 00000000..e6d4f74b
--- /dev/null
+++ b/spec/deck-track.md
@@ -0,0 +1,279 @@
+# SVML Depth-Stack Deck Track
+
+Status: design authority for the official depth-stack Deck migration. It records the behavior used
+by the old Deck implementation, but it is not a frozen public ABI and does not define a universal
+Deck protocol.
+
+## 1. Conclusion
+
+A Deck is not a Media Item mode and is not the third primitive of Media Track. It is a higher-order
+visual component whose members happen to use media material.
+
+The first official implementation is provisionally `@narratage/deck-track`. Its honest author
+meaning is a **depth-stack Deck**:
+
+```text
+ordered Cards
+semantic activation points
+current Card
+visible previous/future neighborhood
+relative-depth layout
+whole-collection state transition
+ordinary VisualTrack output
+```
+
+It is a peer of Media Track, Text, Caption and Ranking:
+
+```text
+Media Item / Sequence ─┐
+Depth-Stack Deck ──────┤
+Text ──────────────────┼─> ordinary VisualTrack values ─> Composition
+Caption ───────────────┤
+Ranking ───────────────┘
+```
+
+Core, Film, Composition and HyperFrames do not know that a contribution came from a Deck.
+
+## 2. Why Deck is outside Media Track
+
+A Media Item answers how one material appears. A Media Sequence answers how members replace one
+another on one shared surface. A depth-stack Deck answers a different question: how an entire
+ordered collection changes pose when its current member changes.
+
+At one frame a Deck may simultaneously show:
+
+- the current Card;
+- several retained historical Cards;
+- several future preview Cards;
+- different offsets, scales, rotations, opacity and tone by relative depth;
+- a transition in which every retained Card moves from its old pose to its new pose.
+
+That is collection state, not source sampling, fitting or an outgoing/incoming pair handoff. Keeping
+it inside Media Track would make one historical presentation model look like a universal media
+primitive.
+
+## 3. No universal Deck contract yet
+
+“Deck” is currently a design family, not a shared public Type. Other useful models may have
+fundamentally different topology:
+
+- horizontal or circular Carousel;
+- fan layout;
+- Cover Flow;
+- grid with a distinguished current member;
+- freeform collage;
+- time-axis history;
+- a Ranking board whose board and entries evolve together.
+
+Those packages may define different author Surfaces, validation and lowering. They need only emit
+the terminal `VisualTrack` contract. We should extract a shared Deck library only after multiple
+real implementations prove a smaller common law. Merely sharing the noun “Deck” is not evidence for
+a central protocol.
+
+Consequently the first package should expose an honest component name such as `DepthStack`, rather
+than claiming that its fields describe every possible Deck.
+
+## 4. Package boundary
+
+The intended relationship is:
+
+```text
+@narratage/temporal point location and exact trigger schedule
+@narratage/spatial Canvas, Placement Frame and fitted geometry
+@narratage/media normalized still/timed/Surface material
+@narratage/media-track focused reusable media-layer lowering implementation
+@narratage/deck-track DepthStack author Program, state and reflow lowering
+@narratage/composition terminal VisualTrack waist
+```
+
+`@narratage/deck-track` may reuse focused implementation functions from Media Track or a later
+implementation-only media-lowering library. That code reuse does not make Deck a Media Track
+component and does not expose a universal `MediaProgram` or `DeckProgram` through Core.
+
+The package does not:
+
+- generate Card images or videos;
+- select Providers or credentials;
+- infer Cards from URLs, directories or media metadata;
+- inspect another Track or the accumulated lower composite;
+- reserve a global stacking band;
+- add Deck meaning to Core, Film, Composition or HyperFrames.
+
+Every Card source, label, trigger and sound dependency is an explicit graph reference.
+
+## 5. Illustrative author Surface
+
+The syntax is not frozen, but package ownership should be visible:
+
+```xml
+<deck:DepthStack
+ id="proof-stack"
+ map={timing.map}
+ space={speech.space}
+ canvas={vertical}
+ frame={layout.lower-proof-stack}
+ until={story.selection.proof.end}
+ appearance={studio.deck.proof}
+>
+ <deck:Card id="proof-1" source={proof1.image} at={story.moment.proof1}/>
+ <deck:Card id="proof-2" source={proof2.image} at={story.moment.proof2}/>
+ <deck:Card id="proof-3" source={proof3.video} at={story.moment.proof3}/>
+</deck:DepthStack>
+```
+
+The component itself produces an ordinary `VisualTrack`. It is not nested in `<media:Track>` and it
+is not selected through `mode="deck"`.
+
+SVML owns topology: ordered Card membership, source edges, trigger references, terminal point,
+Frame and optional label inputs. SVS owns reusable parameters: visible neighborhood, depth poses,
+frame Paint and reflow motion. SVS cannot create Cards, hide source edges or choose a Provider.
+
+## 6. Exact state model
+
+Let authored Card activation frames be:
+
+```text
+p1 < p2 < ... < pN < T
+```
+
+where `T` is the explicit terminal point. At frame `f`:
+
+```text
+current(f) = greatest i such that pi <= f
+```
+
+Before `p1`, the component is outside its active state unless an explicit initial-state policy says
+otherwise. At and after `T`, it is outside the active state except for its explicitly authored exit
+motion.
+
+The package validates authored occurrence order. It never sorts equal, reversed or missing trigger
+points into a seemingly valid presentation.
+
+Visibility is an explicit package parameter:
+
+```ts
+type DepthStackVisibility = {
+ readonly previous: number;
+ readonly next: number;
+ readonly wrap: boolean;
+};
+```
+
+Every visible Card receives an integer relative depth around `current(f)`. A pure layout function
+maps that depth to its pose:
+
+```ts
+type DepthStackPose = {
+ readonly x: number;
+ readonly y: number;
+ readonly scale: number;
+ readonly rotationDeg: number;
+ readonly opacity: number;
+ readonly stacking: number;
+ readonly tone?: DeckCardTone;
+};
+```
+
+The public author model should expose named pose/visibility Recipes, not require authors to repeat
+the complete table inline.
+
+## 7. Reflow is a collection transition
+
+When Card `i` becomes current, every Card visible in either the old or new state obtains an old pose
+and a new pose. The reflow transition interpolates between those poses with one exact duration and
+one easing law.
+
+This differs from a Media Sequence handoff:
+
+```text
+Sequence transition coordinates outgoing member + incoming member
+Deck reflow coordinates the union of old-visible + new-visible Cards
+```
+
+They must not share one `transitionStyle` union. A Card may additionally have owned current-card
+emphasis, but it cannot mutate pixels belonging to another Track.
+
+The renderer evaluates state and pose as pure functions of the absolute frame. It does not retain
+mutable “previous frame” state. Therefore arbitrary-frame rendering, chunked Lambda rendering and
+out-of-order frame evaluation remain deterministic.
+
+## 8. Card material and playback
+
+Each Card may reuse the same explicit layer, Content Fit, clipping and frame-Paint laws as a Media
+Item. That is implementation reuse, not author-model inheritance.
+
+Timed Card sources must define how they sample while not current:
+
+```text
+future preview hold source head, or sample an explicitly selected visible clock
+current Card sample according to its authored active-phase occupancy
+past trail hold source tail, continue, or hide according to explicit policy
+```
+
+Still material needs no playback policy. A video must never silently finish while it is only a
+future preview.
+
+Card labels are optional explicit Text inputs. The Deck package may reuse typography lowering, but
+it cannot derive Text truth from filenames, URLs or hidden image metadata.
+
+The initial DepthStack is visual-only. If a later Deck component exposes source audio, it must do so
+as a separate explicit `AudioTrack` projection with an authored current-member/handoff law; audio
+must never become audible merely because a Card's container contains a stream.
+
+## 9. Stacking
+
+Deck Track has no track-level z-index and creates no stacking context. The board/background and
+individual Cards may lower to separate absolute-stack Presents when peer Tracks need to interleave
+between them.
+
+Relative depth determines only ordering among owned Cards. Temporary ordering during reflow exists
+only inside that explicit relationship. It does not allocate a global z band.
+
+## 10. Migration from Twinit
+
+Retain from the old Deck implementation:
+
+- explicit authored Card order;
+- semantic trigger-driven current state;
+- configurable previous/future visibility;
+- finite or explicit wrapping behavior;
+- depth offset, scale, alternating rotation, opacity and tone;
+- whole-group entry, sustain and exit motion;
+- full-group interpolated reflow;
+- frame Paint, padding, radius, border and shadow;
+- deterministic frame-local evaluation.
+
+Retire:
+
+- treating Deck as a B-roll or Media mode;
+- implicit `linkNext` topology;
+- placement semantics hidden behind “usually below the face”;
+- automatic labels from source metadata;
+- lower-composite transitions;
+- lane-global sound defaults;
+- any registry entry in Core, Film, Composition or HyperFrames.
+
+## 11. Implementation and acceptance order
+
+1. implement the shared Temporal and Spatial slices;
+2. expose `DepthStack` and explicit ordered Cards;
+3. resolve exact trigger state and finite visibility;
+4. reuse focused media-layer lowering for Card contents;
+5. add pure relative-depth pose resolution;
+6. add collection reflow and whole-group lifecycle motion;
+7. prove still and timed inactive-playback behavior;
+8. migrate one real old-system Deck and freeze only after the acceptance matrix passes.
+
+Required evidence includes:
+
+- previous-only, next-only and mixed neighborhoods;
+- zero, one and many visible neighbors;
+- finite boundaries and explicit wrapping;
+- missing, equal and reversed trigger rejection;
+- depth pose, alternating rotation, opacity and tone;
+- cut and interpolated whole-collection reflow;
+- still and timed Card sampling laws;
+- optional exact-font labels;
+- whole-group entry/sustain/exit without overwriting Card poses;
+- byte-identical frames under sequential, partitioned and out-of-order rendering;
+- installation of another Deck package without changing Core or the first DepthStack package.
diff --git a/spec/media-track.md b/spec/media-track.md
new file mode 100644
index 00000000..f762db35
--- /dev/null
+++ b/spec/media-track.md
@@ -0,0 +1,665 @@
+# SVML Media Track Authoring
+
+Status: design authority for the unified official Media Track migration. It supersedes the intended
+author model of the current executable `@narratage/broll` vertical slice, but is not implemented or
+a frozen public ABI.
+
+## 1. Conclusion
+
+Full-canvas cutaways, lower evidence cards, corner images, transparent stickers, animated images,
+short videos and ordinary replacement sequences are not different terminal Track families. They are
+different compositions of the same media concerns:
+
+```text
+source material
+target time / trigger schedule
+source-time occupancy
+Placement Frame
+ordered local layers and Content Fits
+clip and frame Paint
+entry / sustain / exit motion
+per-layer sampling motion
+absolute stacking
+optional owned pairwise replacement relationship
+optional explicit audio projection
+```
+
+They belong in one video-domain package, provisionally `@narratage/media-track`, and all lower to
+ordinary peer `VisualTrack` and, only when explicitly authored, `AudioTrack` values.
+
+One package does not mean one conditional super-component. The author Surface exposes two
+components with different meanings:
+
+```text
+Media Item one independent presentation with one projected window
+Media Sequence ordered members replace one another on one shared surface
+```
+
+`Item` and `Sequence` share focused value families and lowering code. They are separate components
+because they have different topology, validation and ports. There is no `mode="broll | sequence |
+overlay"` field and no step where choosing a mode causes a different hidden component to appear.
+
+A depth-stack Deck is deliberately outside this package. It is a higher-order collection-state
+component, not a media primitive. The official migration model is specified independently in
+[`deck-track.md`](./deck-track.md); future Carousel, Fan, Grid or other Deck packages need not adopt
+that model.
+
+“B-roll” remains a useful editorial description or Recipe name. It is not a public data Type.
+
+## 2. Boundary
+
+The unified package is an author package and deterministic compiler:
+
+```text
+@narratage/media intrinsic media facts and normalized sources
+@narratage/temporal points, occurrences, windows and trigger schedules
+@narratage/spatial Canvas, Placement Frame, Content Fit and fitted geometry
+@narratage/media-track Item / Sequence author Programs and lowering
+@narratage/deck-track independent depth-stack Deck authoring and lowering
+@narratage/composition terminal VisualTrack / AudioTrack waist
+```
+
+It does not:
+
+- generate images or videos;
+- choose a model or Provider;
+- inspect credentials, URLs or local executables;
+- infer which container stream is primary;
+- own the Program clock or Canvas;
+- read a sibling Track or the accumulated lower composite;
+- add a B-roll, Sequence, Deck or Speech branch to Core, Film, Composition or HyperFrames.
+
+Core sees fixed graph Operations, Records and edges. Runtime executes any explicit media
+inspection/normalization or Surface-materialization Needs. Providers do not reinterpret placement,
+motion, transitions or audio policy.
+
+## 3. Source truth
+
+Every visual sample enters through an explicit graph edge and already has intrinsic media truth.
+The first complete implementation needs to consume:
+
+- still image material with a content-addressed Artifact and exact display-oriented extent;
+- normalized timed visual material with exact frame rate, frame count and extent;
+- typed `CompositableSurface` material with exact still/frame timing and alpha mode.
+
+The intrinsic owner remains `@narratage/media`. The Media Track package may use a package-local
+resolved union internally, but it must not create another universal media Type or copy provider,
+source path, Narrative digest or upstream lineage into every item.
+
+Filename inference is invalid. In particular:
+
+- an animated GIF or animated WebP cannot remain a browser-timed `<img>` because frame `n` must be
+ independently renderable during parallel rendering;
+- it must be normalized into exact frame-timed visual material or a typed animated Surface;
+- a still image remains durationless even when its file format also supports animation;
+- an MP4 containing audio does not make that audio audible;
+- alpha-bearing visual material must retain an explicit alpha contract.
+
+Several layers may reference the same Artifact. The graph and Artifact collector deduplicate bytes;
+the renderer still evaluates every authored sample independently.
+
+## 4. The orthogonal item model
+
+Conceptually, one independent Item owns:
+
+```ts
+type MediaItemProgram = {
+ readonly id: string;
+ readonly temporal: TemporalBinding;
+ readonly frame: SpatialFrameInput;
+ readonly framePresentation: MediaFramePresentation;
+ readonly layers: readonly MediaLayerProgram[];
+ readonly motion: MediaLifecycleMotion;
+ readonly stacking: AbsoluteStackingIntent;
+ readonly sourceAudio?: MediaSourceAudioProjection;
+};
+```
+
+The axes are:
+
+| Axis | Owns | Does not own |
+|---|---|---|
+| source | exact still/timed/Surface material | Provider or source discovery |
+| temporal | occurrence expansion and item window | source playback |
+| frame | Placement Frame | visible Paint or content aspect |
+| layers | ordered Paint/media samples | Track-relative z context |
+| content fit | one Content Frame per sample | zoom/pan or playback |
+| occupancy | source trim and source-time mapping | target window |
+| frame presentation | clip, radius, border, shadow, padding | geometry construction |
+| lifecycle motion | entry, sustain and exit of owned pixels | member-to-member handoff |
+| sampling motion | pan/zoom/rotation inside one media layer | Placement Frame motion |
+| stacking | absolute Present position | Track family priority |
+| source audio | explicit projection of one selected layer's audio | automatic container audio |
+
+These are package Program facts. They do not become fields on Core or the terminal Track contract.
+
+## 5. Illustrative author Surface
+
+The final Surface must favor named Frames and SVS Recipes over large inline bags. One possible
+shape is:
+
+```xml
+<media:Track id="editorial-media" map={timing.map} space={speech.space} canvas={vertical}>
+ <media:Item
+ id="full-cutaway"
+ source={demo.video}
+ during={story.selection.demo}
+ frame={vertical}
+ appearance={studio.media.full-cutaway}
+ />
+
+ <media:Item
+ id="corner-loop"
+ source={reaction.surface}
+ at={story.moment.reaction}
+ for="2s"
+ frame={layout.top-right-sticker}
+ appearance={studio.media.corner-loop}
+ />
+
+ <media:Sequence
+ id="steps"
+ frame={layout.lower-card}
+ appearance={studio.media.evidence-sequence}
+ until={story.selection.explanation.end}
+ >
+ <media:Member id="step-1" source={step1.image} at={story.moment.step1}/>
+ <media:Member id="step-2" source={step2.image} at={story.moment.step2}/>
+ <media:Member id="step-3" source={step3.video} at={story.moment.step3}/>
+ <media:Handoff from="step-1" transition={studio.media.transitions.push-left}/>
+ <media:Handoff from="step-2" transition={studio.media.transitions.crossfade}/>
+ </media:Sequence>
+
+</media:Track>
+```
+
+This syntax is illustrative. The normative points are:
+
+- declarations and reusable appearance stay outside usage sites;
+- every source, Frame, Selection and Moment is an explicit reference;
+- `Item` and `Sequence` are visibly different author meanings;
+- shorthand such as `during`, `at`, `for` and `until` lowers to the one shared Temporal algebra;
+- no runtime chooses whether something is a cutaway, card or sticker.
+
+### SVML structure and SVS parameter bundles
+
+SVML owns topology: sources, Frames, timing references, Item/Sequence membership, Handoff edges,
+labels and sound inputs. SVS owns named reusable parameter bundles: Content Fits, frame Paint,
+clipping, motion parameters and transition appearance.
+
+An SVS Recipe cannot hide a source edge, create a member, select a Provider or cause two independent
+Items to become a Sequence. Applying one transition Recipe to a whole Sequence materializes that
+choice on every authored Handoff in the resolved Program. Thus Recipes stay concise without
+becoming a second graph language.
+
+### Small framed inset with a smooth rise
+
+A small box is not another component. It is one ordinary Item whose explicit Placement Frame is
+smaller than Canvas. Structure remains readable at the use site:
+
+```svml
+<space:AnchoredFrame id="product-inset" within={safe}
+ x="50%" y="78%" width="82%" height="28%" anchor="center"/>
+
+<media:Track id="proof" map={timing.map} space={speech.space} canvas={vertical}>
+ <media:Item
+ id="product-proof"
+ source={product.video}
+ during={story.selection.proof}
+ frame={product-inset}
+ appearance={studio.media.fuzzy-card}
+ motion={studio.motion.smooth-rise}
+ />
+</media:Track>
+```
+
+The referenced Recipes conceptually resolve independent parameters such as:
+
+```text
+media.fuzzy-card
+ content fit contain or cover
+ frame fill explicit color/gradient/transparent Paint
+ content padding exact pixels
+ frame clip rounded rectangle or owned shape
+ edge treatment border/shadow, or an explicit rough-edge layer
+
+motion.smooth-rise
+ enter operator translate
+ from below the Canvas or an exact positive y offset
+ to resolved Placement Frame pose
+ duration exact frames
+ easing ease-out, or a package-compiled custom frame curve
+```
+
+“Below” must be unambiguous. `below-canvas` derives an off-canvas starting pose from Canvas and the
+resolved Item extent; `offset-y: 120px` starts below the final Frame without necessarily leaving the
+picture. Both lower to frame-exact local transforms and neither changes the final Spatial Frame.
+
+A normal soft or glowing edge lowers to an owned border plus box shadow/drop shadow. A genuinely
+irregular furry, torn-paper or noisy edge is not a magic `border-style`: it is an explicit local
+layer, such as a transparent frame Artifact or a deterministic `CompositableSurface`. Because that
+layer affects graph topology and Artifact collection, its source must be connected in SVML (for
+example as `<media:Layer source={fuzzyFrame.surface}/>`); SVS may style it but cannot hide the source
+edge. The outer lifecycle wrapper moves the frame Paint, edge layer and content together.
+
+Built-in easing names may lower directly to Visual IR. A richer Bézier or spring Recipe remains a
+Media-package concern and may be deterministically sampled into frame-addressed keyframes; it does
+not require Core, Composition or Runtime to learn a new motion type.
+
+## 6. Independent Item timing
+
+An Item uses the common pipeline from [`track-authoring.md`](./track-authoring.md):
+
+1. locate Selection, Moment or Program points;
+2. expand `one` or `each` occurrences;
+3. project one target window per occurrence;
+4. intersect and validate against ProgramSpace;
+5. evaluate every layer's source trim and occupancy inside that item window;
+6. evaluate lifecycle and sampling motion;
+7. emit self-contained Presents.
+
+Independent Items remain independent. Their windows may overlap, and they compose by their explicit
+absolute stacking keys. Program order does not make them exclusive, clip a lower-priority item,
+auto-stitch gaps or infer a Sequence.
+
+A full-screen B-roll is simply an Item whose Placement Frame equals Canvas and whose foreground
+layer commonly uses `cover`. A small image, GIF or video is the same Item against a smaller Frame.
+“Do not cover the face” is not a Media mode: the author consumes a suitable named Frame, or an
+upstream subject-aware layout component explicitly produces one.
+
+## 7. Ordered local layers
+
+One Item owns an ordered list of local layers inside one Placement Frame:
+
+```ts
+type MediaLayerProgram =
+ | MediaFramePaintLayer
+ | MediaSampleLayer;
+
+type MediaSampleLayer = {
+ readonly id: string;
+ readonly source: MediaSourceInput;
+ readonly fit: ContentFit;
+ readonly trim?: VisualSourceTrim;
+ readonly occupancy: VisualOccupancy;
+ readonly appearance: MediaSampleAppearance;
+ readonly samplingMotion?: MediaSamplingMotion;
+};
+```
+
+The complete backing cases from [`spatial-layout.md`](./spatial-layout.md) are ordinary layer lists:
+
+- transparent: no backing layer;
+- solid or gradient: one frame-Paint layer;
+- self blur: the same source enters one cover/blur layer and one foreground layer;
+- alternate backing: a different explicit source supplies the backing layer;
+- decorated card: Paint, border/shadow/padding and one or more media layers.
+
+Every media layer derives its own Content Frame from its own intrinsic extent and `ContentFit`.
+There is no special foreground/background pair and no one shared inner box.
+
+Frame-level clipping is explicit: none, Placement Frame or an owned shape. Radius, border, shadow,
+padding and frame Paint are presentation. They cannot mutate Spatial geometry or sample another
+Track.
+
+## 8. Source-time occupancy
+
+Static material has no intrinsic playback duration and paints for the complete interval in which
+its layer is active. A timed video, animated image or animated Surface uses explicit trim followed
+by the common visual occupancy law:
+
+```text
+once/start play from the source head, then disappear or truncate
+once/end align the source tail to the window end
+hold/start play from the head, then hold the last visual frame
+hold/end hold the first visual frame, then play to the end
+loop/start loop from source-head phase
+loop/end choose phase so the source tail meets the window end
+stretch map the complete effective source interval onto the window
+```
+
+There is no `auto`, `native`, `finish`, `freeze` or `phased` author enum. Images do not receive a
+fake playback mode. Source trim executes before occupancy. Spatial contain/cover and temporal
+stretch remain unrelated.
+
+The Item target window remains valid even when one `once` layer ends early. Other Paint or media
+layers may continue. An author who wants the complete item to remain visible chooses `hold`, supplies
+a persistent layer or authors a shorter target window; the compiler never shrinks the Item by
+guessing which layer is primary.
+
+## 9. Media motion has four separate channels
+
+Old B-roll behavior becomes four explicitly separated package-owned channels:
+
+```ts
+type MediaLifecycleMotion = {
+ readonly enter?: MediaEdgeMotion;
+ readonly sustain?: readonly MediaSustainMotion[];
+ readonly exit?: MediaEdgeMotion;
+};
+
+type MediaSamplingMotion = {
+ readonly keyframes: readonly MediaSamplingKeyframe[];
+};
+```
+
+### Entry motion
+
+Operates on all pixels owned by one Item or Group at the beginning of its visible envelope.
+Reasonable typed Recipes include fade, directional slide, scale, pop, bounce, local blur reveal,
+wipe, flip and spin.
+
+### Sustain motion
+
+Operates during the visible envelope. Float, breathe, pulse, wobble, shake and drift are reasonable
+operators. The authored ordered list is evaluated deterministically; multiple transforms cannot
+silently overwrite one another.
+
+### Exit motion
+
+Operates on all owned pixels at the end of the envelope. It uses its own operator and duration; it
+is not automatically the reverse of entry.
+
+### Sampling motion
+
+Operates on one media layer's already fitted Content Frame. Normalized keyframes may animate zoom,
+source/content-point displacement and rotation. Ken Burns is a sampling-motion Recipe, not a Base
+effect and not an occupancy mode.
+
+Entry plus exit durations that overlap are rejected unless one explicit component defines the
+combined behavior. The compiler does not proportionally shorten both as Twinit's renderer did.
+
+The transform stack is fixed so channels cannot overwrite one another:
+
+```text
+absolute Present stacking
+└─ fixed Placement Frame
+ └─ group/item entry + exit wrapper
+ └─ ordered sustain wrappers
+ └─ member handoff wrapper (Sequence only)
+ └─ frame Paint and clip
+ └─ base fitted Content Frame
+ └─ layer sampling motion
+ └─ media pixels
+```
+
+The lowerer may algebraically compose matrices or emit nested Visual IR elements, but the order and
+pixels must be identical. These are Media package contracts, not a generic public `effects` bag.
+
+## 10. Sequence: explicit member replacement
+
+A Sequence owns two or more nested Members that share one Placement Frame and one outer lifecycle.
+It is created explicitly; nearby Items, overlapping windows or a transition Recipe never imply
+membership.
+
+Each Member has:
+
+- a stable author identity;
+- explicit media layers and per-layer fit/occupancy/sampling motion;
+- exactly one activation point derived from a Moment or one Selection boundary;
+- no independent outer entry or exit motion.
+
+The Sequence has one explicit terminal point. For activation frames `p1..pN` and terminal `T`:
+
+```text
+p1 < p2 < ... < pN < T
+
+logical member 1 phase [p1, p2)
+logical member 2 phase [p2, p3)
+...
+logical member N phase [pN, T)
+```
+
+Source occurrence order is authoritative. The compiler never sorts by physical time. Missing,
+equal-frame, reversed or out-of-program activations fail the complete Sequence atomically.
+
+Every adjacent pair owns one explicit Handoff. No transition default exists only in an editor or
+Runtime; “apply to all” materializes the same chosen transition on every edge.
+
+### Pair transition
+
+The official initial set remains:
+
+- cut;
+- crossfade;
+- push;
+- wipe;
+- cover;
+- page turn.
+
+One transition owns operator identity, exact duration, typed parameters and a boundary-position
+ratio `r` in `[0,1]`. At logical boundary `p` and duration `d`:
+
+```text
+handoff.start = p - r × d
+handoff.end = p + (1-r) × d
+```
+
+Frame quantization preserves the exact total transition length. Adjacent handoff windows may not
+overlap; invalid duration fails instead of creating an implicit three-source transition.
+
+During a handoff, outgoing and incoming Member surfaces are both owned by the Sequence. Their media
+samples run continuously across their expanded visual spans. The transition changes neither
+ProgramSpace nor upstream Selection/Moment points.
+
+Sequence handoffs may operate only inside their shared Placement Frame. This makes cut, crossfade,
+push, wipe, cover and page turn honest local relationships. An outer handoff against
+`composite_below` is deliberately retired: it would read and mutate unrelated lower Tracks.
+
+The Sequence itself may use an ordinary entry/exit motion. A full-screen fade over a lower Track is
+valid because only the Sequence opacity changes; pushing or page-turning the lower Track is not.
+
+## 11. Audio is explicit and projected separately
+
+Visual material remains muted unless the author explicitly selects source audio from exactly one
+named media layer. This is item-level so a foreground and its self-blurred copy cannot accidentally
+mix the same source twice.
+
+```ts
+type MediaSourceAudioProjection = {
+ readonly fromLayer: string;
+ readonly gain: number;
+};
+```
+
+The audio projection reuses the selected layer's exact trim, playback mapping and resolved schedule.
+Each Sequence edge separately owns its audio relationship:
+
+- `cut` switches audibility at the logical activation point even when visual surfaces overlap;
+- `crossfade` uses the explicitly authored audio handoff window;
+- visual transitions never silently choose an audio transition.
+
+Entry/exit or handoff SFX are explicit audio Artifact inputs with explicit gain. They are lowered at
+the exact resolved entry, exit or boundary point. They are not package-global filenames, mutable
+sound-library defaults or hidden lane SFX.
+
+The compiler does not return one atomic `MediaProduct` containing both terminal Tracks. It resolves
+one package-owned Media Program and provides separate deterministic projection Operations:
+
+```text
+Resolved Media Program ─┬─> project visual ─> VisualTrack
+ └─> project audio ─> AudioTrack
+```
+
+Consequently either terminal output may be targeted, replaced or satisfied independently by the
+Run Graph. When both are demanded, they still share the same resolved schedule through an explicit
+graph edge rather than duplicated timing metadata.
+
+A visual-only Item does not demand audio normalization or rendering merely because its source
+container has an audio stream.
+
+## 12. Stacking and flat Tracks
+
+The Media Track itself has no z-index. Every resolved top-level Item or Sequence surface and any
+separately interleavable member/layer emits absolute Present stacking keys.
+
+Frame Paint and tightly coupled media samples may remain in one Present-local element tree. When a
+peer Track must be able to appear between a board, card, icon or layer, the package emits separate
+Presents with separate absolute keys. Track ownership never creates a stacking context.
+
+Temporary ordering inside a Sequence handoff is package-owned and exists only for that relation's
+frames. It does not reserve a global z band.
+
+## 13. Speech Spine's restricted Media projection
+
+Speech Spine should stop maintaining a second ad-hoc media renderer. Its visual projection uses the
+same Media lowering implementation with a deliberately restricted generated Program:
+
+```text
+one normalized visual take per speech Segment
+exact already-established Segment frame span
+Canvas Placement Frame
+one foreground layer
+explicit contain/cover fit chosen by the speech package
+muted visual
+cut between contiguous takes
+no entry, sustain or exit motion
+no Sequence state
+no source-audio projection
+```
+
+Speech audio remains the separate canonical `SpeechAudioBasis -> AudioTrack` projection. The visual
+projection does not inspect or extract audio from generated MP4 containers.
+
+This can be a code dependency on focused Media lowering helpers. It does not require exposing a
+public `MediaProgram` graph Type when no external component consumes that intermediate value. If a
+real graph consumer appears later, the package may expose its own versioned resolved Type; Core
+still does not register Media meaning.
+
+The author imports Speech Spine, whose manifest declares its package dependency. Authors do not
+need to import a second parser merely because the implementation reuses Media lowering.
+
+## 14. Twinit audit: retained and retired
+
+Retain:
+
+- full-frame cutaways, split-screen and corner overlays through one Item model;
+- still images, GIF-like animation and videos;
+- independent overlapping media presentations;
+- explicit contain/cover/focal sampling and foreground/self-blur backings;
+- source trim and once/hold/loop/stretch occupancy;
+- entry, exit, continuous outer motion and inner sampling motion;
+- explicit Sequence membership and shared-surface pair transitions;
+- cue-position ratio and continuous visual sampling across transition windows;
+- explicit source audio and transition/edge SFX;
+- stable author identities and deterministic authored order.
+
+Retire:
+
+- a separate B-roll terminal family;
+- a `mode` that changes valid ports or settings;
+- URL-extension guesses for image/video/GIF behavior;
+- track-level z-index and implicit item priority;
+- `auto` playback, `finish`, `freeze`, `phased` and renderer repair;
+- automatic sequencing or `linkNext` inference;
+- one `focalX/focalY` used for both source and destination points;
+- fixed foreground/background fields instead of ordered local layers;
+- one CSS transform slot that lets motion channels overwrite each other;
+- proportional shortening of overlapping entry/exit durations;
+- lane-global SFX and automatically selected audio;
+- outer `composite_below` transitions and every Base FX dependency;
+- one bundled B-roll Product that couples VisualTrack and AudioTrack satisfaction.
+
+The old Deck behavior migrates independently under [`deck-track.md`](./deck-track.md); removing it
+from Media Track does not remove that capability.
+
+## 15. Package and implementation shape
+
+The intended package relationships are:
+
+```text
+@narratage/media-track
+├─ author Surfaces: Track, Item, Sequence, Member, Handoff
+├─ package-owned Program validators
+├─ pure Item window/layer/motion lowering
+├─ pure Sequence schedule + pair transition lowering
+├─ VisualTrack projection
+└─ AudioTrack projection
+
+depends on
+├─ @narratage/media
+├─ @narratage/temporal
+├─ @narratage/spatial
+├─ @narratage/svs
+└─ @narratage/composition
+```
+
+The package may use internal focused files or future implementation-only libraries. It must not
+create one umbrella authoring library shared by Text, Caption, Ranking and Media, and it must not
+require a release of Core when a new media Recipe, motion operator or component package is added.
+
+The existing `@narratage/broll` package remains an executable regression witness until the new path
+passes. Because the project is pre-release, the migration may replace it rather than preserving a
+public compatibility layer. Source assets and generated files remain untouched.
+
+## 16. Implementation order
+
+Implement only after the shared Temporal and Spatial slices exist:
+
+1. introduce `@narratage/media-track` with one still-image Item;
+2. add timed source trim and every occupancy/alignment policy;
+3. add ordered Paint/media layers, clipping and the two-frame fit model;
+4. add lifecycle and sampling motion with the fixed transform stack;
+5. add explicit Sequence scheduling and pair transitions;
+6. add separate source-audio and SFX projection;
+7. route Speech Spine visual projection through the restricted lowerer;
+8. migrate real B-roll examples and then retire the old package;
+9. freeze only after the complete acceptance matrix passes.
+
+No step requires a Core, Runtime, queue or Provider change. Surface materialization may use an
+existing explicitly registered Provider capability, but ordinary Item/Sequence lowering is
+deterministic local compilation.
+
+## 17. Acceptance matrix
+
+### Material
+
+- opaque and alpha still images;
+- portrait, landscape and square images;
+- normalized video with and without a selected audio stream;
+- animated GIF/WebP normalized to exact frame timing;
+- still and animated Compositable Surfaces;
+- repeated use of one Artifact without duplicated storage or duplicated source audio.
+
+### Item
+
+- Selection, Moment, Program and absolute windows under `one` and `each`;
+- independent overlapping Items at unrelated absolute stacking keys;
+- every source trim and shorter/equal/longer occupancy case;
+- full Canvas, split, lower card, corner and off-canvas Frames;
+- transparent, solid, gradient, self-blur and alternate-source backing layers;
+- every Content Fit and unequal content/frame focal point;
+- entry, sustain, exit and sampling motion separately and in combination;
+- explicit failure for overlapping entry/exit durations.
+
+### Sequence
+
+- image-image, video-video, image-video and alpha-Surface handoffs;
+- strict authored activation order and stable member identity;
+- cut, crossfade, push, wipe, cover and page turn;
+- start/center/end boundary-position ratios;
+- continuous source sampling across handoff overlap;
+- transition duration at, below and above available separation;
+- missing, repeated, reversed and same-frame activation failure;
+- no implicit three-member overlap and no lower-composite input;
+- group entry/exit operating only on owned pixels.
+
+### Audio and execution
+
+- visual-only source does not demand audio work;
+- exactly one explicitly selected source layer contributes audio;
+- hard and crossfaded Sequence audio handoffs;
+- simultaneous exit/entry SFX mix at one boundary;
+- independent BGM remains unchanged;
+- targeting/replacing visual and audio projections independently;
+- identical Visual Track/Audio Track plans under local and remote execution;
+- arbitrary frame partitioning renders byte-identical deterministic frames.
+
+### Architecture
+
+- installing another Media component changes no Core, Film, Composition or HyperFrames family
+ registry;
+- all source, temporal, spatial, sound and label dependencies are graph edges;
+- no Track contains provider, path, Narrative digest or source-family metadata;
+- no operation samples the accumulated lower composite;
+- the Speech Spine restricted projection and ordinary Item use the same lowering laws.
diff --git a/spec/ranking-track.md b/spec/ranking-track.md
new file mode 100644
index 00000000..ca728130
--- /dev/null
+++ b/spec/ranking-track.md
@@ -0,0 +1,297 @@
+# SVML Ranking Track Migration
+
+Status: normative design for the official Ranking migration. It records the author model and
+lowering laws to implement after the shared temporal projection package. It is not a compatibility
+promise for the historical Twinit node format or a frozen public ABI.
+
+## 1. What Ranking means
+
+Ranking is a video-domain author component that presents one ordered collection as a progressive
+visual state. It is not a Core concept, a generic Track mode, a Provider or a renderer feature.
+
+The old system placed four materially different behaviors behind one `ranking_track` node and a
+`rankingType` switch. The new system uses one physical package, `@narratage/ranking@1`, but exposes
+four independent author components:
+
+- `ranking:TierBoard` — place revealed items into named tier rows;
+- `ranking:Column` — show one current item on a stage, then settle it into a numbered column;
+- `ranking:TopThree` — progressively reveal up to three items and accent the current item;
+- `ranking:TypewriterList` — type ordered text rows onto a persistent paper/list surface.
+
+One package is the right unit for shared validation, schedule construction, layout utilities and
+paint primitives. Four components are the right unit for author meaning. There is no public
+`rankingType`, mode-selection input, dynamic-port registry or Runtime renderer registry.
+
+A third party can publish another Ranking package without registering a type in Core or modifying
+this package. Installing and importing that package contributes its own Surface, Types, validators
+and fragment compiler through the ordinary module mechanism.
+
+## 2. Evidence from the old implementation
+
+The reviewed old-project inventory contains 21 migrated Ranking nodes:
+
+| Historical variant | Reviewed uses | Item counts seen |
+|---|---:|---|
+| Tier | 10 | 5–6 |
+| Typewriter | 5 | 5 |
+| Column | 3 | 4–5 |
+| Top Three | 3 | 3 |
+
+The inventory proves that all four meanings are real, but not that their old representation should
+survive. The old implementation had these structural problems:
+
+1. one UI/node identity changed meaning by switching a mode and disconnecting its dynamic ports;
+2. the same item `start/end` pair meant visibility, animation phase, successor handoff or nothing,
+ depending on the renderer;
+3. Top Three ignored item end times, while Typewriter used their union only to decide whether the
+ paper was mounted;
+4. renderers inspected all sibling segments, sorted or counted them, and manufactured group state
+ after the generic Track Program had already lost that meaning;
+5. one global z-index prevented the board and individual icons from interleaving with peer Tracks;
+6. raw URLs, environment font names, Remotion component ids and three mirrored registries leaked
+ environment/renderer details into the component;
+7. short windows could silently suppress motion sound instead of rejecting an impossible schedule.
+
+Migration preserves the useful visual capabilities, not these accidental semantics.
+
+## 3. Author-facing shape
+
+The exact XML spelling will be fixed with the temporal Surface parser. The intended shape is:
+
+```svml
+<import as="ranking" from="@narratage/ranking@1"/>
+<import as="fonts" from="@narratage/fonts-open@1"/>
+<import as="studio" source="./studio.svs"/>
+
+<fonts:Stack id="ranking-fonts" family="inter" weight="700"/>
+
+<ranking:ColumnStyle id="column-style"
+ recipe={studio.ranking.column}
+ font={ranking-fonts}/>
+
+<ranking:Column id="tools"
+ space={speech.space}
+ map={timing.map}
+ during={story.selection.ranking-board}
+ triggers={story.moment.next-rank}
+ terminal={story.moment.ranking-complete}
+ style={column-style}>
+ <ranking:ColumnItem label="Fourth" icon={fourth.image}/>
+ <ranking:ColumnItem label="Third" icon={third.image}/>
+ <ranking:ColumnItem label="Second" icon={second.image}/>
+ <ranking:ColumnItem label="First" icon={first.image}/>
+</ranking:Column>
+```
+
+`during` supplies the explicit outer window. `triggers` supplies an ordered Moment occurrence set.
+`terminal` is the explicit end of the final active stage; it may precede the outer end so the fully
+settled result remains visible. The component requires the number of trigger occurrences to equal
+the number of child items and zips them in authored order.
+
+The outer Selection and terminal Moment each use strict `one` semantics. The trigger Moment uses
+strict `each` semantics. Zero or multiple outer/terminal occurrences, zero triggers and any
+trigger/item cardinality mismatch are compile errors; the component never selects a convenient
+occurrence.
+
+This positional zip is declared by these four components. It is not generic Core behavior. An
+alternative third-party Surface may give each item its own Moment edge and lower to the same
+package facts.
+
+Style declarations remain separate from use. SVS supplies named generic Recipe data; each
+variant-specific `*Style` component owns the allowed keys and compiles the Recipe plus explicit font
+edges into a typed package-owned Style. Semantic item values such as tier row, label, icon and entry
+behavior are not paint properties and do not belong in SVS.
+
+## 4. The group sees siblings; rendered Tracks do not
+
+A progressive ranking cannot be compiled by treating every child as an isolated Track item. Row
+placement, successor handoff, active-item state and the settled prefix depend on the ordered group.
+That does not mean items inspect one another at render time.
+
+The author component first compiles the complete child list and trigger set into one package-private
+schedule:
+
+```ts
+type RankingSchedule = {
+ readonly outer: FrameSpan;
+ readonly terminalFrame: number;
+ readonly entries: readonly {
+ readonly itemId: string;
+ readonly triggerOccurrenceId: string;
+ readonly triggerFrame: number;
+ readonly stage: FrameSpan;
+ readonly cumulative: FrameSpan;
+ }[];
+};
+```
+
+This is an explicit Graph value between deterministic Operations, not metadata smuggled through an
+image, Track or media Artifact. It is owned and versioned by the Ranking package and is not added to
+Core, Composition or the shared Track waist.
+
+```text
+Moment set + SemanticMap + ProgramSpace + outer/terminal projection + ordered item ids
+ │
+ ▼
+ RankingSchedule
+ │ │
+ Style + content ───┘ └── SFX clips + gains
+ │ │
+ ▼ ▼
+ VisualTrack AudioTrack
+```
+
+The schedule Operation preserves source order and stable occurrence identities. It never sorts by
+physical time. After frame quantization it requires:
+
+```text
+outer.start <= p1 < p2 < ... < pN < terminal <= outer.end
+```
+
+Every invalid or equal-frame sequence fails atomically. The visual and optional audio lowerers
+consume the same schedule, so motion and sound cannot drift while remaining independently
+demandable branches of the Run Graph.
+
+## 5. Common phase model
+
+For outer window `[B, O)`, triggers `p1 ... pN` and terminal `T`, entry `i` receives:
+
+```text
+active stage [p_i, p_(i+1)) or [p_N, T)
+cumulative life [p_i, O)
+settled life [stage.end, O)
+```
+
+`[B, p1)` may show an explicitly authored empty board, but has no implicit active item. `[T, O)` is
+the optional fully-settled suffix with no active item. These facts are package-owned sibling
+sequencing built on the shared temporal projection algebra in
+[`track-authoring.md`](./track-authoring.md); they are not a new `Stage` contract.
+
+### TierBoard
+
+- the board occupies `[B, O)`;
+- every item is visible cumulatively from its trigger to `O`;
+- `entry="direct"` animates directly into its final tier cell after the trigger;
+- `entry="stage"` appears at the shared stage point, remains there for its active stage, moves into
+ the final cell before the stage ends and then stays settled;
+- the item owns a required image and tier-row id; source order within a row determines its cell;
+- impossible appear/move durations are compile errors, never silently shortened or omitted.
+
+### Column
+
+- the numbered board occupies `[B, O)`;
+- exactly one item occupies the large stage during each active stage;
+- when its stage ends, that item becomes part of the settled column until `O`;
+- label is required, image is optional, and rank is the authored item order;
+- overlapping current items are structurally impossible after a valid schedule.
+
+### TopThree
+
+- at most three items are accepted;
+- each item is revealed cumulatively from its trigger to `O`;
+- only the item for the current active stage receives the active ring/accent motion;
+- `[T, O)` shows all revealed items without an active accent;
+- label is required, image is optional, and slot is the authored item order.
+
+### TypewriterList
+
+- the paper occupies `[B, O)` and blank rows may be structurally reserved before their trigger;
+- row `i` begins typing at `p_i` and remains visible until `O`;
+- typing duration is derived deterministically from Unicode grapheme count and the Style's speed;
+- typing and an optional winner mark must fit inside the item's active stage or compilation fails;
+- title, optional explicit emphasis span and row strings are author content, not LLM fields.
+
+Typewriter is retained in the Ranking package because its author meaning is an ordered progressive
+ranking, despite its heavy use of text layout. It may share low-level exact-font/layout utilities
+with the future Text implementation, but it must not depend on or masquerade as a generic Text
+Track Program.
+
+## 6. Spatial layout and stacking
+
+Each component owns one outer placement box and its internal layout algorithm. A Tier cell, Column
+row or Top Three slot is not a generic per-item spatial locator. Allowing arbitrary spatial inputs
+on those children would destroy the component's meaning.
+
+Placement and stacking remain independent:
+
+- the outer box determines the coordinate system for board, stage and items;
+- the Style resolves an absolute board stack order and defaults for stage/items;
+- every child may explicitly override its own absolute item stack order;
+- board, stage decoration and each item lower to separate `VisualPresent` values where independent
+ interleaving is required;
+- one resulting `VisualTrack` is not a stacking context, so a peer Track Present may appear between
+ the board and any icon.
+
+No package must emit multiple Tracks merely to obtain multiple z positions. Stable `tieBreak`
+values derive from authored component/item identity, never evaluation order.
+
+All normalized geometry is relative to the explicit outer box. Required variant dimensions include:
+
+- Tier: row definitions/colors, board/label widths, stage point, cell gaps, icon fit/radius and
+ appear/move durations;
+- Column: board box, row height/gap, stage point/size, cell/icon geometry, rank palette and
+ appear/move durations;
+- Top Three: center/width, label line, icon size, ring width/palette and reveal/accent motion;
+- Typewriter: paper theme/paint, padding, row gap, title/item typography, rotation, typing speed and
+ winner-marker paint/motion.
+
+Paint, geometry and motion parameters are validated by the owning `*Style` component. Unknown
+Recipe properties fail. There is no arbitrary CSS escape hatch.
+
+## 7. Media, fonts and sound
+
+Images and sounds enter through explicit `MediaArtifactRef` edges. Fonts enter through explicit,
+content-addressed font stack edges. Ranking never stores a URL, asks the Runtime to choose a font,
+or names a renderer component.
+
+Optional sound effects are ordinary authored inputs:
+
+- appear sound starts at the item's trigger;
+- move sound is derived from the same scheduled move phase used by the visual lowerer;
+- gain and clip choice live in the Style/explicit sound inputs;
+- configured sound produces a peer `AudioTrack`; no sound produces no demanded audio branch;
+- sound playback never enters Hyperframes or a visual Track.
+
+Ranking itself is deterministic and has no Need, Provider, queue, credential or environment
+adapter. If an input image is generated, that upstream generation remains another Graph component.
+
+## 8. Run-Graph behavior
+
+The author graph exports ordinary logical `visual` and, when authored, `audio` results. Targets,
+Candidates and replacement are governed by the same Run Graph laws as every other component.
+Ranking adds no cache, pin or preview primitive.
+
+Replacing the visual result does not mutate the audio result. Replacing both outputs with one
+multi-output Candidate is also possible through ordinary explicit output mapping. Once every
+demanded original output is satisfied by selected Candidates, demand analysis prunes the original
+Ranking branch and its temporal/media ancestors. No special Ranking execution rule is required.
+
+## 9. Migration order and acceptance
+
+Implementation order:
+
+1. implement the shared temporal projection and triggered-schedule laws;
+2. create `@narratage/ranking@1` with four separate Programs/Styles and one private schedule utility;
+3. lower TierBoard and Column first, because together they prove cumulative and exclusive stage
+ semantics plus independent stacking;
+4. lower TopThree;
+5. lower TypewriterList using exact font/layout primitives;
+6. add optional AudioTrack lowering from the same schedule;
+7. add real-browser visual witnesses and one author-Surface graph check per component.
+
+Acceptance requires:
+
+- trigger/item cardinality, stable identities and all boundary failures are tested;
+- `T < O` visibly proves a final settled suffix;
+- short stages reject impossible animation rather than repairing it;
+- board and per-item Presents interleave with a peer Track at unrelated absolute z positions;
+- visual and sound event frames agree exactly;
+- missing optional images work only for variants that declare them optional;
+- fonts and media are content-addressed dependencies;
+- each component can revise its own Program without changing Core, Runtime, Composition,
+ Hyperframes or another Ranking component;
+- installing a fifth component package requires no central family registry change.
+
+The migration intentionally does not preserve historical node JSON, mode switching, old dynamic
+ports, renderer ids or Remotion components. Historical projects are evidence and visual references,
+not a compatibility obligation for an unreleased language.
diff --git a/spec/screen-overlay.md b/spec/screen-overlay.md
new file mode 100644
index 00000000..158e059b
--- /dev/null
+++ b/spec/screen-overlay.md
@@ -0,0 +1,234 @@
+# SVML Screen Overlay Authoring
+
+Status: design authority for the optional official Screen Overlay package. It is not implemented by
+an author Surface yet and is not a frozen public ABI.
+
+## Purpose
+
+`@narratage/screen-overlay` contributes self-contained, usually full-canvas pixels over an authored
+time window. A flash, vignette, scan-line veil or deterministic light leak is an ordinary
+`VisualTrack`, exactly like Text, Caption, Media or Ranking.
+
+It is not an adjustment layer, a privileged post-composition hook, a transition engine or a way to
+read the pixels of lower Tracks.
+
+```text
+Moment / Selection / Program ─> shared temporal projection ─┐
+CanvasSpace ────────────────────────────────────────────────┼─> Overlay Program
+effect parameters / explicit owned assets ─────────────────┘ │
+ ▼
+ Visual IR elements or owned Surface
+ │
+ ▼
+ VisualTrack
+```
+
+Core, Runtime and Composition do not know Screen Overlay. Composition only validates and orders its
+self-contained Presents.
+
+## 1. The self-contained-pixel law
+
+Every overlay item must be renderable from:
+
+- its own authored parameters;
+- the explicitly connected CanvasSpace and ProgramSpace;
+- zero or more explicit assets owned by that item;
+- its deterministic local frame number.
+
+It must not sample:
+
+- the accumulated Composition below it;
+- a sibling Track;
+- a hidden Base Track;
+- the previous or next scene;
+- a browser backdrop or environment texture.
+
+Normal source-over alpha compositing is allowed: that is how every alpha-bearing Track reaches the
+canvas. Blend modes or filters whose result depends on unknown lower pixels are not self-contained.
+
+This law means the old source-free `backdrop-filter` implementations of Gaussian Blur, Color
+Adjust and Zoom Blur are not Screen Overlays. To preserve those effects honestly, a media-effect
+component must receive the exact media or compositable Surface to transform through a graph edge,
+then output its own transformed material or Track. If a future component explicitly rasterizes a
+selected group of Tracks into a Surface, consuming that Surface is also explicit; Screen Overlay
+never gains a secret “current frame” input.
+
+## 2. Author package, not operator registry
+
+The official package may expose several readable author components under one namespace:
+
+```xml
+<screen:Track id="screen-paint">
+ <screen:Flash at={story.moment.hit} for="240ms" color="#ffffff" intensity={0.9}/>
+ <screen:Vignette during={program} opacity={0.28}/>
+ <screen:Grain during={program} amount={0.12} seed={23}/>
+</screen:Track>
+```
+
+This is illustrative Surface syntax. The compiled Program contains explicit component identity,
+parameters and temporal binding; it is not one stringly typed `effect="..."` switch owned by Core.
+
+One package is convenient for the small official collection, but it is not a central registry. A
+third party may publish another self-described package that lowers a new component to the same
+Visual Track waist. Adding an overlay must not require changing Core, Film, Composition or
+HyperFrames when existing Visual IR or a typed Surface can express it.
+
+Appearance defaults and named combinations belong in `.svs` recipes. The package owns parameter
+validation and deterministic lowering. Runtime Profiles and Providers do not choose a visual
+effect.
+
+## 3. Program axes
+
+Every overlay item has four independent author concerns:
+
+```ts
+type ScreenOverlayItemProgram = {
+ readonly id: string;
+ readonly content: ScreenOverlayComponent;
+ readonly temporal: TemporalBinding;
+ readonly presentation: ScreenOverlayPresentation;
+ readonly stacking: AbsoluteStackingIntent;
+};
+```
+
+- `content` identifies the actual visual component and its typed parameters;
+- `temporal` uses the shared Selection/Moment/Program projection algebra;
+- `presentation` describes the item's within-window envelope or local motion;
+- `stacking` resolves to an ordinary absolute Present stacking key.
+
+Canvas geometry is not an author-selected Spatial Frame here. A Screen Overlay intentionally owns
+the complete connected CanvasSpace. A partial-frame light, image, card or blur is a normal Media,
+Text or component Track and uses [`spatial-layout.md`](./spatial-layout.md).
+
+Items are independent by default. Overlap is valid and produces multiple ordinary Presents. There
+is no singleton Screen Overlay lane and no global merge step.
+
+## 4. Timing and local envelopes
+
+Selection, Moment, Program and absolute timing lower through
+[`track-authoring.md`](./track-authoring.md). Screen Overlay does not have `from`, `until`, `manual`
+or phrase-matching timing laws of its own.
+
+The projected window answers only where the item exists. Its within-window envelope is component
+presentation. For example, a Flash may define attack, peak and decay; a Directional Matte may move
+an edge from one side to another; Grain may remain steady. The old universal triangle that peaked
+at 30% of every effect's duration is retired as hidden presentation policy.
+
+Recipe defaults may supply an envelope, but the resolved Program must contain the exact parameters.
+An effect cannot expand its projected window to fit an animation. Invalid or zero-length windows
+fail through the common temporal validator.
+
+## 5. Portable official component set
+
+The useful old effects divide into two honest lowering groups.
+
+### Direct Visual IR candidates
+
+These can normally lower to full-canvas boxes, gradients and local keyframes:
+
+- `Flash` — solid color with an explicit opacity envelope;
+- `ColorWash` — source-over color veil; no hidden lower-pixel blend mode;
+- `Vignette` — authored center, radius, softness, roundness, color and opacity;
+- `ScanLines` — spacing, thickness, angle, opacity and local motion;
+- `DirectionalMatte` — angle, coverage, feather, color, opacity and progress;
+- `WhipVeil` — direction, width, softness, travel and opacity;
+- `GlitchVeil` — deterministic owned color bars/washes, not displacement of lower pixels.
+
+### Owned Surface candidates
+
+These may be easier or more exact as deterministic alpha-bearing `CompositableSurface` values:
+
+- `Grain` — amount, grain size, monochrome/color, motion rate and required seed;
+- `LightLeak` — colors, angle, softness, travel, intensity and seed when stochastic;
+- `Bokeh` — amount, size range, color/warmth, drift and required seed;
+- `TVStatic` — amount, noise size, scan-line contribution, motion rate and required seed.
+
+Choosing Visual IR or Surface is a lowerer implementation decision only when both produce the exact
+declared pixels. It cannot depend on which Runtime happens to execute the Build. A materializing
+implementation may issue an ordinary Provider Need, but the Need returns a typed owned Surface and
+does not receive the lower composite.
+
+All stochastic behavior requires an explicit resolved seed. `Math.random()`, wall time, GPU noise
+or renderer-dependent entropy is invalid.
+
+## 6. Explicitly excluded effects
+
+The following old names are excluded from the source-free package:
+
+| Old effect | Why excluded | Honest replacement |
+|---|---|---|
+| `gaussian_blur` | must read pixels being blurred | media/surface filter with explicit input |
+| `color_adjust` | exposure/contrast/saturation/hue alter input pixels | media/surface color transform with explicit input |
+| `zoom_blur` | a real radial blur requires the visual being sampled | media/surface effect with explicit input |
+| screen/multiply/overlay blend wash | result depends on lower pixels | source-over alpha approximation, or explicit-input materialization |
+
+This does not delete the visual result. It rejects the old privilege by which a supposedly ordinary
+Track could mutate everything beneath it.
+
+Screen Overlay also cannot:
+
+- change Program duration or playback rate;
+- own the cut between adjacent media items;
+- transition two sibling Tracks;
+- reserve a topmost z-index;
+- hide a sound effect inside a visual item.
+
+A visually masked hard cut remains two independent facts: the Media package owns the cut and the
+Screen Overlay happens to cover some of the same frames. A combined authored `Impact` Fragment may
+produce one Visual Track and one Audio Track from the same Moment, but both outputs remain explicit
+peer edges into Film.
+
+## 7. Stacking
+
+The old fixed `z_index: 200` rule is retired. “Screen” describes full-canvas geometry, not a magical
+render phase. Every Present receives an explicit absolute stacking intent and Composition flattens
+it with all other Presents.
+
+An author can intentionally put a vignette below captions, a flash above captions or grain between
+two graphic layers. Package recipes may provide convenient stacking defaults, but Film and
+Composition never switch on the package family and never force it to the top.
+
+If one overlay package emits multiple Presents at different stacking positions, peer Tracks may
+interleave between them exactly as required by the flat Track law.
+
+## 8. Twinit migration audit
+
+Retain:
+
+- short Moment hits and long Program overlays;
+- Selection, Moment and absolute temporal placement;
+- full-canvas flash, veil, vignette, light leak, grain, scan lines, bokeh and static visuals;
+- deterministic effect-specific parameters and local envelopes;
+- several simultaneous effects;
+- optional explicit owned textures or materialized alpha Surfaces.
+
+Retire:
+
+- singleton slot semantics;
+- fixed topmost z-index and special post-caption render phase;
+- one central string operator registry as system truth;
+- the universal 30%-peak envelope;
+- hidden `backdrop-filter` access;
+- `mix-blend-mode` across Tracks;
+- pretending screen hits are scene transitions;
+- hidden lane-level enter/exit SFX;
+- any Base FX counterpart or placeholder.
+
+## 9. Lowering and acceptance
+
+Implementation should follow the shared Temporal and existing Visual Track contracts:
+
+1. add the self-described `@narratage/screen-overlay` author package;
+2. implement separate typed author components rather than one unvalidated parameter bag;
+3. lower simple components to `svml.visual-ir@1` and complex ones to typed owned Surfaces;
+4. use the connected CanvasSpace and ProgramSpace, never Film globals;
+5. emit ordinary absolute-stack Presents;
+6. add deterministic frame tests for every component and envelope;
+7. prove identical pixels across local and parallel frame rendering;
+8. prove multiple overlay Tracks interleave with Text/Caption/Media by stacking key;
+9. add negative tests rejecting any lower-composite, sibling-Track, backdrop-filter or hidden audio
+ dependency.
+
+The design fails if installing a new overlay requires a Core branch, a Composition family, a
+HyperFrames component switch or an implicit snapshot of already composed pixels.
+
diff --git a/spec/spatial-layout.md b/spec/spatial-layout.md
new file mode 100644
index 00000000..9921101b
--- /dev/null
+++ b/spec/spatial-layout.md
@@ -0,0 +1,460 @@
+# Shared Spatial Layout
+
+Status: executable foundational authority for shared Spatial geometry. `@narratage/spatial`
+implements CanvasSpace, Frame/Point/Path, IntrinsicExtent, ContentFit and pure fitting; Film now
+consumes the same explicit CanvasSpace as Track layout. Text, Media and Ranking migration witnesses
+and the public ABI freeze remain incomplete.
+
+## 1. Conclusion
+
+The shared spatial system owns coordinate geometry, not Text, Media or CSS. Its stable vocabulary is:
+
+```text
+CanvasSpace exact output coordinate system
+SpatialPoint one point in that system
+SpatialFrame one positive rectangular region
+SpatialPath one explicit vector path
+IntrinsicExtent one content item's natural two-dimensional size/aspect
+ContentFit how an extent is sized and aligned against a Frame
+FittedContent the deterministic result of that fit
+```
+
+When a visual component consumes a `SpatialFrame`, that frame plays the role of its
+**Placement Frame**: where the component is placed and where frame-level Paint may exist. Every
+actual text/media sample then derives its own **Content Frame** from its intrinsic dimensions and a
+`ContentFit`.
+
+These are the two frames. They are not always nested:
+
+```text
+contain cover
+
+Placement Frame Content Frame
+┌──────────────┐ ┌──────────────────┐
+│ ┌────────┐ │ │ ┌────────────┐ │
+│ │Content │ │ │ │ Placement │ │
+│ │ Frame │ │ │ │ Frame │ │
+│ └────────┘ │ │ └────────────┘ │
+└──────────────┘ └──────────────────┘
+```
+
+Calling the second one an "inner box" is therefore incorrect. Under `cover`, zoom or local motion,
+the Content Frame may exceed the Placement Frame.
+
+One Placement Frame may contain several explicit samples. A solid backing has no Content Frame. A
+blurred sample and a foreground sample each have their own Content Frame, even when they reference
+the same Artifact. There is no single global "inner frame" shared by every layer.
+
+## 2. Boundary
+
+The focused video-domain package is provisionally named `@narratage/spatial`. It owns pure types,
+validators, author Surfaces for reusable geometry and deterministic geometry Producers. It does not
+own:
+
+- temporal windows or intrinsic media playback;
+- text wrapping or glyph measurement;
+- media decoding, stream selection or container rotation;
+- backgrounds, blur, opacity, color, borders or shadows;
+- z-order, transitions or local motion;
+- Composition, Runtime, Provider or Core behavior.
+
+Those facts meet Spatial only through graph edges. For example, Media Inspection selects one visual
+stream and produces its display-oriented extent; a Media package explicitly converts that extent
+into `IntrinsicExtent` and gives it to Spatial fitting. Spatial never opens an MP4 or guesses which
+stream is primary.
+
+Installing or revising this package must not change Core. The Core sees ordinary typed Records and
+Operations.
+
+## 3. CanvasSpace
+
+`CanvasSpace` establishes the exact coordinate system before any Track is authored:
+
+```ts
+type CanvasSpace = {
+ readonly contract: "svml.canvas-space@1";
+ readonly widthPx: number;
+ readonly heightPx: number;
+ readonly origin: "top-left";
+ readonly xDirection: "right";
+ readonly yDirection: "down";
+ readonly pixelAspect: "square";
+};
+```
+
+Width and height are positive integers. Color, clear Paint, frame rate and duration are not spatial
+facts and remain outside this value.
+
+The Canvas must be declared before Tracks and later connected to Film/Composition as the same graph
+value. The current Film Surface hides width and height inside the final Film declaration, which is
+too late for exact Text and Media layout. Its rewrite must separate Canvas declaration from final
+Track assembly rather than copying width/height into every Track Recipe.
+
+An intended source shape is:
+
+```svml
+<space:Canvas id="vertical" width="1080" height="1920"/>
+
+<!-- Track declarations consume vertical or Frames derived from it. -->
+
+<film:Film id="main" canvas={vertical} space={program} appearance={studio.film.main}>
+ ...
+</film:Film>
+```
+
+The exact Surface spelling remains pre-freeze. The one-value dataflow is normative.
+
+## 4. SpatialFrame construction
+
+A resolved `SpatialFrame` is a finite rectangle in Canvas pixel coordinates:
+
+```ts
+type SpatialFrame = {
+ readonly contract: "svml.spatial-frame@1";
+ readonly xPx: number;
+ readonly yPx: number;
+ readonly widthPx: number;
+ readonly heightPx: number;
+};
+```
+
+Width and height must be positive. `xPx` and `yPx` may be negative or extend beyond Canvas. An
+off-canvas Frame is useful for entry/exit motion and must not be silently clamped, intersected or
+rejected. Canvas rasterization determines which pixels are visible. Clamping is always an explicit
+projection choice.
+
+Author inputs may use Canvas-relative percentages or pixels. They compile into this one resolved
+form before a consumer lays out its content. Percentages are relative to the explicitly connected
+parent Frame's width/height, not to whichever DOM container a renderer happens to create.
+
+Three author components cover the normal construction meanings without a mode field:
+
+1. `Frame`: four explicit edges inside a parent Canvas/Frame;
+2. `AnchoredFrame`: one target point, one width/height and one of nine self anchors;
+3. `AspectFrame`: one target point, one primary size and one explicit or connected aspect ratio.
+
+Conceptually:
+
+```svml
+<space:Frame id="safe" within={vertical}
+ left="6%" top="4%" right="94%" bottom="96%"/>
+
+<space:AnchoredFrame id="card" within={safe}
+ x="50%" y="78%" width="82%" height="28%" anchor="center"/>
+
+<space:AspectFrame id="sticker" within={safe}
+ x="100%" y="100%" width="32%" aspect={portrait.extent} anchor="bottom-right"/>
+```
+
+`Frame` does not mean a visible box. It produces geometry only. `AspectFrame` may consume a generic
+`IntrinsicExtent` edge; it does not depend on Media.
+
+The nine canonical anchor names are:
+
+```text
+top-left top-center top-right
+middle-left center middle-right
+bottom-left bottom-center bottom-right
+```
+
+The compiled math is point attachment, not nine hard-coded layout algorithms:
+
+```text
+frame.x = target.x - frame.width × selfAnchor.x + offset.x
+frame.y = target.y - frame.height × selfAnchor.y + offset.y
+```
+
+Each named anchor is merely a readable `(0 | 0.5 | 1, 0 | 0.5 | 1)` pair. An advanced Surface may
+expose arbitrary normalized anchor points without changing the compiled contract.
+
+Safe area, left column, title region and product region are ordinary named Frames derived from a
+Canvas or parent Frame. They are not reserved global tokens.
+
+## 5. IntrinsicExtent
+
+`IntrinsicExtent` is the minimal generic fact needed to preserve content shape:
+
+```ts
+type IntrinsicExtent = {
+ readonly contract: "svml.intrinsic-extent@1";
+ readonly widthPx: number;
+ readonly heightPx: number;
+};
+```
+
+The values are the content's positive display-oriented natural pixel extent. Their ratio is all that
+`contain`, `cover`, `fit-width`, `fit-height` and `stretch` need; `native` and `scale-down` also use
+their absolute relation to Canvas pixels. Media may derive them after applying container rotation
+and sample-aspect information. Text may derive them from exact font shaping. A vector component
+must choose an explicit nominal raster extent rather than pretending arbitrary view-box units are
+Canvas pixels. None stores the source Artifact, font, component family or upstream digest inside
+`IntrinsicExtent`; those relationships remain visible on graph edges and Derivations.
+
+## 6. ContentFit and the two-frame equations
+
+`ContentFit` chooses sizing, alignment and an optional alignment constraint:
+
+```ts
+type ContentFit = {
+ readonly contract: "svml.content-fit@1";
+ readonly sizing:
+ | "contain"
+ | "cover"
+ | "fit-width"
+ | "fit-height"
+ | "native"
+ | "scale-down"
+ | "stretch";
+ readonly framePoint: { readonly x: number; readonly y: number };
+ readonly contentPoint: { readonly x: number; readonly y: number };
+ readonly offsetPx: { readonly x: number; readonly y: number };
+ readonly constraint: "bounded" | "free";
+};
+```
+
+Points are normalized in their own Frames. `framePoint` says where in the Placement Frame the
+chosen content point wants to land. `contentPoint` says which intrinsic source point is important.
+This is more expressive than the old single `focalX/focalY`, which silently used the same coordinate
+on both sides. Both point coordinates must lie in `[0,1]`; deliberate displacement beyond those
+bounds uses `offsetPx` and, when it must remain out of bounds, `constraint="free"`.
+
+Given Placement Frame `(Vx, Vy, Vw, Vh)` and intrinsic extent `(Sw, Sh)`, the aspect-preserving
+base scales are:
+
+```text
+contain min(Vw / Sw, Vh / Sh)
+cover max(Vw / Sw, Vh / Sh)
+fit-width Vw / Sw
+fit-height Vh / Sh
+native 1
+scale-down min(1, contain-scale)
+```
+
+For these modes:
+
+```text
+Cw = Sw × scale
+Ch = Sh × scale
+```
+
+`stretch` deliberately abandons source aspect and produces `(Cw, Ch) = (Vw, Vh)`. It is explicit
+because mature editors permit distortion; no other sizing mode may distort.
+
+Before constraint:
+
+```text
+Cx = Vx + Vw × framePoint.x - Cw × contentPoint.x + offset.x
+Cy = Vy + Vh × framePoint.y - Ch × contentPoint.y + offset.y
+```
+
+For `free`, these coordinates are final. For `bounded`, each axis is minimally clamped by one law:
+
+- when content is smaller, keep the complete Content Frame inside the Placement Frame;
+- when content is larger, keep the complete Placement Frame covered by the Content Frame.
+
+For the horizontal axis this means:
+
+```text
+Cw <= Vw: clamp Cx to [Vx, Vx + Vw - Cw]
+Cw >= Vw: clamp Cx to [Vx + Vw - Cw, Vx ]
+```
+
+The vertical law is identical. This supports true focal placement such as “source point `(0.8,
+0.35)` should appear at the center of the Frame” without permitting an accidental uncovered strip.
+
+The usual nine alignments are shorthand where `framePoint === contentPoint`. Centered contain and
+centered cover are both `(0.5, 0.5)` on each side. `top-left` is `(0,0)` on each side. An author who
+needs the content deliberately outside or the Placement Frame deliberately uncovered chooses
+`free`; the Runtime never makes that creative decision.
+
+`FittedContent` contains the derived Content Frame and no duplicated upstream lineage:
+
+```ts
+type FittedContent = {
+ readonly contract: "svml.fitted-content@1";
+ readonly contentFrame: SpatialFrame;
+};
+```
+
+When clipping to the Placement Frame, the corresponding source sampling window is mechanically
+derived from the intersection of Placement and Content Frames. It is not a third authored box. A
+post-fit rotation or perspective transform may make the sampling boundary non-rectangular and is
+therefore applied after this base layout.
+
+## 7. Fit is not motion and not occupancy
+
+A fit calculation produces the base Content Frame. Zoom, pan, rotation, perspective and entrance
+motion transform that result later. They do not mutate the `ContentFit` or source aspect.
+
+This prevents the old ambiguity where `zoom` was embedded inside `contain`/`cover` and could quietly
+invalidate the claimed fit. If a Ken Burns motion zooms a contained image until it crops, the base
+fit remains `contain` and the later transform explicitly creates the crop.
+
+Spatial sizing is also unrelated to intrinsic temporal occupancy. A video may be `contain` in space
+while it plays once, loops or stretches in time. The same image has no intrinsic temporal playback
+mode merely because it has an intrinsic spatial extent.
+
+## 8. Clipping and frame shape
+
+Spatial geometry never decides whether pixels outside a Placement Frame are visible. The consuming
+component owns an explicit clip policy:
+
+```text
+none owned content may paint outside the Placement Frame
+placement-frame rectangular or rounded Frame clip
+owned-shape explicit shape/path owned by the same component
+```
+
+Corner radius, ellipse/path masks, border and shadow are presentation, not coordinates. A Text
+glow may legitimately overflow its Placement Frame; a Media card normally clips every local sample
+to the same rounded Placement Frame. No default is inferred from content type by Runtime.
+
+An owned shape may clip only elements in the same component contribution. It cannot mask or sample
+a sibling Track.
+
+## 9. Transparent, solid, blurred and alternate backings
+
+The area of a Placement Frame not painted by a Content Frame is not itself spatial meaning.
+Media/Text presentation supplies an ordered list of explicit owned layers.
+
+### Transparent
+
+No backing layer is emitted. Transparent pixels naturally reveal lower Tracks during Composition.
+This is not cross-Track sampling: the Track contributes no pixel there.
+
+### Solid or gradient
+
+A frame Paint layer fills the Placement Frame. It has no source input, IntrinsicExtent or Content
+Frame.
+
+### Blurred copy of the same source
+
+The source is connected explicitly a second time as another local sample:
+
+```text
+same source Artifact ─┬─> cover ContentFit -> blur/tone -> backing layer
+ └─> contain ContentFit -> foreground layer
+```
+
+Both samples share one Placement Frame but have independent Content Frames and effects. Artifact
+collection deduplicates identical bytes; rendering still performs two explicit samples. The blur
+implementation must edge-extend/overscan before clipping so the Gaussian kernel cannot create an
+unintended transparent or dark border.
+
+### Another image or video
+
+The alternate source enters on its own graph edge and receives its own Inspection, IntrinsicExtent,
+ContentFit and, for timed media, occupancy. It is not a string path hidden in a Style Recipe.
+
+The general Media author model is therefore ordered local layers rather than special
+`foreground/background` fields:
+
+```svml
+<media:Item id="portrait-card" frame={card} clip={rounded-card}>
+ <media:Paint recipe={studio.media.card-base}/>
+ <media:Layer source={portrait} fit={cover} effects={blurred}/>
+ <media:Layer source={portrait} fit={contain}/>
+</media:Item>
+```
+
+Changing the second source to another image expresses an alternate backing. Removing the first two
+children expresses transparent backing. Each layer may lower to its own absolute-stack Present when
+peer Track interleaving is required; an authoring Track never becomes an implicit stacking context.
+
+The complete Item/Sequence author model is specified in [`media-track.md`](./media-track.md). The
+independent depth-stack collection model is specified in [`deck-track.md`](./deck-track.md). Both
+reuse the explicit layer and edge laws without making Deck a Media mode.
+
+### What remains forbidden
+
+`backdrop-filter` over the already accumulated Composition is not one of these cases. It would make
+the result depend on arbitrary lower Tracks. To blur another visual, the component must receive
+that visual/media explicitly. To blur a completed lower composite, a higher-order component must
+explicitly own and materialize that composite first.
+
+## 10. Text, Ranking and Caption use
+
+Spatial provides common geometry without forcing one layout model:
+
+- Point Text consumes a `SpatialPoint` and derives its Content Frame from exact text extent;
+- Area Text consumes a Placement Frame, then performs package-owned paragraph flow inside it;
+- Path Text consumes an explicit `SpatialPath`;
+- Media consumes a Placement Frame and derives one Content Frame per sample;
+- Ranking consumes Frames/Points for its board, slots and staging areas, then owns sibling layout;
+- Comment Sticker consumes a Placement Frame and owns its avatar/text/internal layout;
+- Caption may consume a Placement Frame, but Cue/Atom wrapping remains Caption-owned.
+
+Text's layout box and Media's Content Frame are not the same semantic Type merely because both are
+rectangles. They may use the same pure geometry helpers while remaining package-owned resolved
+facts.
+
+## 11. Graph dataflow and no metadata propagation
+
+```text
+CanvasSpace + Frame Projection
+ │
+ ▼
+ SpatialFrame ───────────────────────────────┐
+ │
+Media Inspection -> display extent -> IntrinsicExtent│
+ ├─> fit -> FittedContent
+authored ContentFit ─────────────────────────────────┘ │
+ ▼
+ package Paint/motion/clip -> VisualTrack
+```
+
+Every dependency is a graph edge. `MediaArtifactRef` does not gain placement fields. `SpatialFrame`
+does not gain source, role, timing or Artifact digests. `VisualTrack` does not gain `focal`, B-roll
+or Text fields. Affinity is validated by the multi-input fitting/lowering Operation rather than by
+copying lineage metadata through every value.
+
+## 12. Twinit findings retained and retired
+
+Retained:
+
+- normalized author placement and source-aspect-aware anchored placement;
+- independent source fitting and temporal occupancy;
+- contain, cover, fit-width and fit-height equations;
+- independent foreground and backing sampling;
+- source focal alignment and explicit attachment points;
+- optional transparent, solid and self-blurred backings;
+- local motion over sampling/placement.
+
+Retired:
+
+- `SpaceLocator` as a union mixing regions, VLM inference, avoidance, path signals and fixed boxes;
+- nine-grid codes as separate algorithms;
+- one `focalX/focalY` reused as both source and target point;
+- `MediaBoxStyle` treating exactly one foreground and one special backing as the universal model;
+- embedding zoom into fit;
+- renderer-specific CSS and FFmpeg formulas as two sources of truth;
+- hidden `object-fit`, `object-position` or `backdrop-filter` defaults.
+
+## 13. Implementation and acceptance order
+
+1. **Implemented:** add the focused `@narratage/spatial` package with `CanvasSpace`, Frame/Point/Path,
+ `IntrinsicExtent`, `ContentFit` and pure fit validation;
+2. **Implemented:** split Canvas declaration from Film assembly and connect the same Canvas value to Track layout and
+ Composition;
+3. migrate one simple Text Point/Area and one simple Media image through shared geometry;
+4. add exact browser tests for every fit and alignment law;
+5. prove ordered transparent/color/self-blur/alternate-source Media layers;
+6. migrate Ranking and Comment Sticker geometry;
+7. only then freeze the Spatial Types and related Visual IR behavior.
+
+The test matrix must include:
+
+- portrait, landscape and square intrinsic extents against portrait, landscape and square Frames;
+- every sizing mode, including explicit distortion and scale-down;
+- all nine equal-point alignments plus unequal source/frame focal points;
+- bounded versus free alignment;
+- negative/partially/fully off-canvas Placement and Content Frames;
+- parent Frame percentages and pixel offsets;
+- source rotation/sample-aspect normalized before Spatial;
+- transparent, solid, same-source blur and alternate image/video layers;
+- independent backing and foreground Content Frames;
+- rounding/raster behavior locked by the selected renderer implementation;
+- no Core, Runtime, Film-family, Text-family or Media-family discriminator in the shared Types.
+
+Until those witnesses pass, percentages embedded independently in Text, B-roll and Caption remain
+migration scaffolding rather than the shared spatial system.
diff --git a/spec/text-track.md b/spec/text-track.md
new file mode 100644
index 00000000..ac277665
--- /dev/null
+++ b/spec/text-track.md
@@ -0,0 +1,497 @@
+# Text Track Authoring and Expressiveness
+
+Status: design authority for the official two-dimensional Text migration. The current
+`@narratage/text-track` package is an executable vertical slice, not an implementation of this
+complete model. The terminal Visual IR changes identified here remain pre-freeze work.
+
+## 1. Conclusion
+
+The complete Text model is not a larger `TextAppearance` object. It is the orthogonal product of:
+
+```text
+authored document
+× temporal binding
+× spatial form
+× text flow
+× exact typography
+× ordered Paint layers
+× deterministic local motion
+```
+
+An ordinary transparent title, one background around the complete phrase, one background per
+rendered line, isolated word Pills, connected highlighter geometry and a per-grapheme typewriter are
+different values in this model. They are not different renderer components and do not require Core,
+Film or Composition branches.
+
+"Complete" does not mean putting every effect ever made into one flat object. It means:
+
+1. every ordinary two-dimensional editor Text behavior has a typed place in this model;
+2. new Styles and Recipes do not change shared protocols;
+3. capabilities with genuinely different inputs or physics use explicit sibling components;
+4. any self-contained visual that exceeds the terminal element language can materialize a typed
+ compositable Surface without changing Core.
+
+The official Text package owns this author meaning. SVS only provides named immutable Recipe
+parameters. Visual IR remains the shared terminal video language. HyperFrames is one renderer of
+that language, not the definition of Text.
+
+## 2. Audit evidence
+
+### 2.1 Current Narratage slice
+
+The current `packages/text-track` implementation has one fixed rectangular box, one plain string
+and one `TextAppearance` containing color, size, family, weight, line height, horizontal/vertical
+alignment, one background, radius, padding and tracking. Its Surface accepts exactly `text`,
+`during` and `appearance`; its Recipe requires exactly eleven scalar properties.
+
+It currently cannot represent:
+
+- paragraphs, explicit line breaks or differently styled inline runs;
+- exact font Artifact inputs on the author Surface;
+- point text, intrinsic sizing or path text;
+- independent frame/content/paragraph/line/run/word/grapheme Paint targets;
+- gradients, repeated strokes, repeated shadows, glow or underline layers;
+- Unicode-aware word/grapheme behavior, bidirectional runs or vertical text policy;
+- item, line, word or grapheme animation;
+- text masks or materialized advanced text.
+
+This is a useful end-to-end witness only. Extending `TextAppearance` field by field would preserve
+the wrong model.
+
+### 2.2 Twinit evidence
+
+Twinit's later `TextLayoutV2` discovered several correct separations:
+
+- inline/block `hug | fixed` sizing;
+- independent padding and inline/block alignment;
+- no-wrap, word-wrap and character-wrap;
+- visible, clip, ellipsis and shrink overflow;
+- LTR/RTL and horizontal/vertical writing;
+- frame/content/line/word background targets;
+- line-box, cap-height and ink-bound metrics.
+
+Its renderer also implemented solid/gradient glyph fill, outside stroke, shadow, glow, callout
+tails, whole-item entry/loop motion, typewriter reveal and line/word backgrounds. Those are valuable
+behavioral witnesses.
+
+The implementation also exposes why it must not be copied as the new contract:
+
+- one `TextFields` bag mixes content, layout, Paint, motion and decoration;
+- gradient fill and background both compete for the CSS `background` property;
+- word backgrounds split on a whitespace regular expression and therefore do not define Unicode
+ word behavior;
+- typewriter slices JavaScript code units rather than grapheme clusters;
+- outside stroke is an implicit duplicated-glyph renderer trick;
+- line fragments, shrink-to-fit and cap/ink trimming depend on browser behavior not represented in
+ the authored value;
+- a pointer silently creates a background and several defaults are renderer inventions;
+- there is no rich-run, path-text or repeated Paint-layer model.
+
+An audited historical export contained 32 Text Tracks and 53 Text items. The most frequently used
+properties were alignment, font family/size, color, weight, background, radius and padding. Stroke,
+uppercase, no-wrap, full-width background, tracking and shadow were also used. The sample contained
+no Text animation usage. This proves the ordinary delivery baseline; it does not justify excluding
+the broader, well-established editor capabilities below.
+
+### 2.3 External editor attack matrix
+
+The design was checked against official product documentation rather than inferred from UI labels:
+
+| Capability family | Established examples | Required Narratage expression |
+|---|---|---|
+| advanced typography | tracking, kerning, leading, baseline shift, tabs, caps, super/subscript, underline and Tsume | typed typography and per-run overrides |
+| layered appearance | solid/gradient fill, inner/center/outer and repeated strokes, repeated shadows, glow | ordered, repeatable Paint layers |
+| geometric text boxes | point titles, area paragraphs, responsive alignment, rolls/crawls | separate Point and Area forms plus motion |
+| fragment styling | character/word/line styling and animation | deterministic units and selectors |
+| sequential animation | per-character delay, range/follower selectors, direction, spread and loops | selector plus property-animation stack |
+| path text | text following and animating along open/closed paths | explicit Path Text form |
+| text masks | text revealing explicitly owned media or graphics | sibling component with an explicit media input |
+| real 3D text | extrusion, bevel, materials, lighting and per-character 3D | materialized 3D component, not fake 2D fields |
+
+Reference documentation:
+
+- Adobe Premiere: [Text Styles](https://helpx.adobe.com/uk/premiere/desktop/add-text-images/stylize-text/create-text-styles.html)
+ and [Text Style Parameters](https://helpx.adobe.com/ca/premiere/desktop/add-text-images/stylize-text/style-parameters-when-applying-from-style-browser.html)
+- Adobe After Effects: [Animating Text](https://helpx.adobe.com/uk/after-effects/desktop/animating-text/text-animation/animating-text.html)
+- Apple Final Cut Pro: [Adjust Titles](https://support.apple.com/en-qa/guide/final-cut-pro/ver4e32ca5/mac)
+- Apple Motion: [Sequence Text Behavior](https://support.apple.com/en-lamr/guide/motion/motn1607c46e/mac)
+- Blackmagic Design: [DaVinci Resolve 20 Visual Effects Guide](https://documents.blackmagicdesign.com/UserManuals/DaVinci-Resolve-20-Fusion-Visual-Effects.pdf?_v=1757574011000)
+
+This is an expressiveness attack set, not a request to reproduce every product's UI or preset list.
+
+## 3. Ownership and package boundary
+
+The ordinary two-dimensional package remains one package:
+
+```text
+@narratage/text-track
+ Point Text
+ Area Text
+ Path Text
+ Text Style / Inline Style declarations
+ Text Program validation
+ temporal/spatial resolution adapters
+ VisualTrack lowering
+```
+
+Point, Area and Path are separate author components because they assert different geometry. They
+are not a `mode` field which makes ports appear and disappear. They may still lower into one tagged
+`TextItemProgram` union and coexist as peer items in one Text Track.
+
+Two capabilities have materially different inputs and stay out of ordinary Text:
+
+- a Text Mask component must explicitly consume both the text shape and the media/graphic it masks;
+ it may not sample whichever Track happens to be below it;
+- true 3D Text owns extrusion, material, light and camera semantics and normally materializes an
+ alpha-bearing Surface.
+
+Those may be separate packages or separately imported components in a later official distribution.
+Package count is a distribution decision; their graph contracts must remain separate. Neither case
+adds a branch to Core.
+
+## 4. Authored Text Document
+
+A Text item consumes a bounded rich document rather than an HTML fragment or arbitrary tree:
+
+```ts
+type TextDocument = {
+ readonly paragraphs: readonly TextParagraph[];
+};
+
+type TextParagraph = {
+ readonly id: string;
+ readonly runs: readonly TextInline[];
+ readonly style?: TextParagraphStyleRef;
+};
+
+type TextInline =
+ | { readonly kind: "text"; readonly text: string; readonly style?: TextInlineStyleRef;
+ readonly language?: string; readonly direction?: "auto" | "ltr" | "rtl" }
+ | { readonly kind: "break" };
+```
+
+The exact public names may change during implementation, but the laws do not:
+
+1. text, whitespace, punctuation and explicit breaks preserve author order exactly;
+2. a plain string is shorthand for one paragraph with one run;
+3. a Span changes only explicitly inheritable typography/Paint, never timing or item placement;
+4. source text is segmented only when a selected layout/Paint/motion operation needs units;
+5. segmentation is Unicode- and locale-aware and implementation-bound;
+6. no Text package uses an LLM to rewrite, split or decorate authored content;
+7. `uppercase`, small caps and similar transformations are presentation and never mutate the
+ authored document value.
+
+The deterministic unit hierarchy is:
+
+```text
+document > paragraph > explicit run > rendered line > Unicode word > grapheme cluster
+```
+
+`rendered line` exists only after exact fonts and final geometry are known. A grapheme cluster is
+the smallest ordinary author-visible animation/decoration unit. A shaped glyph is not always in
+one-to-one correspondence with a Unicode character or grapheme, so the public author model must not
+pretend otherwise.
+
+## 5. Three spatial forms
+
+Temporal source and window projection remain governed by
+[`track-authoring.md`](./track-authoring.md). Text does not invent `full`, `from`, `until` or another
+timing system.
+
+Spatial placement is independent from Text flow. The shared model in
+[`spatial-layout.md`](./spatial-layout.md) provides resolved point/frame/path geometry; Text then
+interprets that geometry through one of three forms.
+
+### 5.1 Point Text
+
+Point Text is intrinsic text anchored at a resolved point. It normally hugs its content, does not
+soft-wrap and uses an explicit inline/block anchor. Manual paragraph breaks remain valid. Ordinary
+titles, labels and stickers are Point Text.
+
+### 5.2 Area Text
+
+Area Text flows inside a resolved frame. It explicitly chooses:
+
+- inline and block sizing: `hug | fixed` where meaningful;
+- padding on four logical edges;
+- inline alignment: `start | center | end | justify`;
+- block alignment: `start | center | end`;
+- wrap: `none | word | grapheme`;
+- overflow: `visible | clip | ellipsis | shrink`;
+- optional maximum lines for the truncating/shrinking policies;
+- writing direction and writing mode;
+- optional columns and column gap;
+- clipping to the placement frame;
+- metric edge: line box, cap height or ink bounds.
+
+Overflow is honest author intent. `ellipsis` may omit visible authored text and therefore must be
+explicit. `shrink` must declare a minimum scale and fail if the complete text still cannot fit; it
+must not silently cross that bound. This differs from Caption, which must never clip or discard the
+author's display Atoms.
+
+### 5.3 Path Text
+
+Path Text consumes an explicit owned vector path plus Text Document and Style. It owns path side,
+orientation, start/end margins, alignment, reversal and overflow. Animating a margin moves text
+along the path; animating the path changes the path. It never discovers or samples a shape in
+another Track.
+
+Path Text requires either a generic vector/path terminal primitive or an owned materialized
+Surface. It cannot be claimed by serializing an untyped SVG/HTML string.
+
+## 6. Typography
+
+Typography is separate from Paint and layout but participates in layout measurement. It includes:
+
+- an exact ordered `FontStackRef`, with environment family names only as an explicit prototype path;
+- size, weight and normal/italic/oblique style;
+- variable-font axes;
+- OpenType feature choices and font synthesis policy;
+- kerning, tracking, word spacing and line height;
+- language, direction and writing mode;
+- baseline shift, tab width, indentation and paragraph spacing;
+- underline/overline/strike geometry where it follows glyph metrics;
+- text transform, small caps, superscript and subscript presentation;
+- CJK-specific spacing/compression controls when supported by the selected layout implementation.
+
+Exact font bytes remain explicit author graph inputs. They are not names hidden in a Recipe and are
+not selected by the Runtime. Font shaping/layout implementation identity is bound by the accepting
+derivation/render receipt; Core still knows nothing about fonts.
+
+## 7. Ordered Paint model
+
+Paint is an ordered list, not one mutually exclusive set of CSS shortcuts. The Text Program owns
+typed layers such as:
+
+```ts
+type TextPaintLayer =
+ | { readonly kind: "fill"; readonly paint: ColorPaint }
+ | { readonly kind: "stroke"; readonly paint: ColorPaint; readonly widthPx: number;
+ readonly placement: "inside" | "center" | "outside" }
+ | { readonly kind: "shadow"; readonly paint: ColorPaint; readonly offset: Vector;
+ readonly blurPx: number; readonly spreadPx: number }
+ | { readonly kind: "glow"; readonly paint: ColorPaint; readonly blurPx: number;
+ readonly spreadPx: number }
+ | { readonly kind: "box"; readonly target: TextPaintTarget;
+ readonly continuity: "isolated" | "joined"; readonly decoration: BoxDecoration };
+```
+
+`ColorPaint` supports solid, linear-gradient and radial-gradient Paint with an ordered list of color
+and opacity stops. Repeating a Stroke or Shadow is legal and order remains semantic. A renderer may
+lower an outside stroke through duplicated glyph layers, but that is implementation, not an author
+flag whose meaning changes by browser.
+
+Box Paint has these targets:
+
+```text
+frame | content | paragraph | line | run | word | grapheme
+```
+
+Its decoration independently owns fill, border, padding, corner radii and shadows. `isolated`
+creates one decorated unit per target. `joined` unions adjacent selected fragments within each
+rendered line and gives the line fragment honest end caps. Invalid combinations, such as continuity
+on `frame`, fail during Text validation.
+
+This one rule expresses the common cases:
+
+| Look | Paint value |
+|---|---|
+| ordinary transparent text | no Box Paint layer |
+| one phrase capsule | `target=content` |
+| full placement panel | `target=frame` |
+| one box per rendered line | `target=line, continuity=isolated` |
+| one Pill per word | `target=word, continuity=isolated` |
+| connected marker/highlighter | `target=word, continuity=joined` |
+| letter tiles | `target=grapheme, continuity=isolated` |
+
+A callout tail is an explicitly authored attachment to one Box Paint layer, with side, offset, size
+and its own Paint. It does not silently force a background. Frosted glass is not ordinary Box
+Paint because it samples pixels behind the Track; it requires an explicitly owned media input or a
+materialized self-contained component.
+
+## 8. Motion and sequence selectors
+
+Motion is independent from Style so the same look can enter, loop and exit differently. One item
+may have:
+
+1. item-level finite keyframes over position, scale, rotation, skew, opacity, blur and clipping;
+2. path-margin animation for Path Text;
+3. one or more sequence animators over text units.
+
+A sequence animator is the product of:
+
+```text
+unit selector × selected property channels × keyframes × stagger/order
+```
+
+The unit selector may target paragraph, line, run, word or grapheme. It explicitly chooses range,
+forward/reverse order, delay/spread, number of cycles and any deterministic random seed. Property
+channels include local transform, opacity, blur and glyph Paint values. Typewriter is a grapheme
+reveal preset over this model, not string slicing. Rolls and crawls are ordinary item-level motion
+over Area Text.
+
+No motion name is a hidden callback. Presets such as `pop`, `spring`, `slide` or `wobble` compile to
+finite or analytically bounded package-owned motion values before terminal rendering. Two motion
+channels compose through separate owned wrappers or an explicit transform composition order; the
+last one does not overwrite the previous one.
+
+## 9. Style declaration, SVS and readable authoring
+
+Declaration and use remain separate. SVS stays a generic scalar Recipe language; it must not learn
+Text Paint arrays or become a second renderer. A Text Style Surface reads named Recipes, exact Font
+references and repeated structured layer declarations, validates them, then emits one complete
+package-owned `TextStyle` Record.
+
+The intended author shape is:
+
+```svml
+<text:Style id="plain" recipe={studio.text.plain} font={fonts.inter}/>
+
+<text:Style id="word-pills" recipe={studio.text.word-pills} font={fonts.inter}>
+ <text:Box target="word" continuity="isolated" recipe={studio.text.word-pill}/>
+</text:Style>
+
+<text:Style id="poster" recipe={studio.text.poster} font={fonts.inter}>
+ <text:Stroke recipe={studio.text.poster-outline}/>
+ <text:Stroke recipe={studio.text.poster-keyline}/>
+ <text:Shadow recipe={studio.text.poster-shadow}/>
+</text:Style>
+
+<text:Track id="titles" space={film.space}>
+ <text:Point id="hook" style={poster} timing={hook-time} placement={hook-point}>
+ Nothing hidden in the Runtime.
+ </text:Point>
+
+ <text:Area id="explanation" style={word-pills} timing={body-time} placement={body-frame}>
+ <text:P>Every <text:Span style={plain}>visible word</text:Span> stays authored.</text:P>
+ </text:Area>
+</text:Track>
+```
+
+This spelling is illustrative until shared temporal/spatial Surface syntax is fixed. Its important
+properties are already final:
+
+- the author imports and selects the Text package;
+- Styles are declared before use and are ordinary authored Records;
+- simple Style values remain compact;
+- repeated layers are repeated declarations, not numbered fields or encoded strings;
+- the Text Surface, not SVS, interprets the Recipe vocabulary;
+- exact fonts and timing/placement facts travel on explicit graph edges;
+- the resulting Text Program contains no unresolved Recipe and no Runtime/provider choice.
+
+## 10. Compiled pipeline and data gates
+
+```text
+Text Surface
+ authored document + named Style + temporal binding + spatial binding
+ │
+ ▼
+Text Program package-owned author truth
+ │
+ ├── located temporal points ──> projected frame windows
+ └── resolved spatial geometry
+ │
+ ▼
+Resolved Text Layout
+ exact fonts + shaping + wrapping + fragment geometry + motion schedule
+ │
+ ▼
+VisualTrack
+ code-free terminal elements/keyframes or typed owned Surface
+ │
+ ▼
+Composition -> selected final renderer
+```
+
+Graph edges carry every external dependency. Text values contain only intrinsic Text meaning. No
+upstream Record gains text, role, source, style, font or layout metadata merely because a later Text
+consumer needs it.
+
+The layout implementation may use a locked browser, HarfBuzz/Skia/Pango or another exact engine.
+It must bind the actual implementation and font bytes. Browser line boxes are not propagated as
+generic graph metadata; they are either deterministic terminal layout owned by the renderer receipt
+or package-owned resolved geometry used to materialize a Surface.
+
+## 11. Terminal Visual IR findings
+
+The current `svml.visual-ir@1` candidate can already carry simple nested boxes, exact fonts, local
+style keyframes and duplicated glyph layers. It is not yet sufficient to honestly freeze the Text
+model:
+
+- one `text` element is one escaped leaf string, so interleaved rich runs and paragraph structure
+ have no first-class terminal representation;
+- there is no vector path/text-path primitive;
+- local masks are not represented;
+- keyframes can animate only opacity, transform, filter and clip-path, not sequenced glyph Paint;
+- the closed style vocabulary lacks several typography controls;
+- repeated Paint layers and their ordering are only implicit renderer tricks.
+
+These are video-terminal issues, never Core issues. Before Visual IR freezes, implementation must
+choose and prove the smallest renderer-neutral additions for rich text flow, typed local masking,
+path geometry and unit-local animation. A capability that still cannot be expressed uses the
+existing typed `CompositableSurface` path.
+
+The requirement is not to expose HTML, CSS, SVG or renderer scripts. It is to add only generic
+code-free visual primitives with at least Text and one independent witness where practical.
+
+## 12. Feedback into Fine Caption
+
+Text and Caption share typography implementation problems, not author truth.
+
+The following may be shared through a focused video-domain implementation library, provisionally
+`@narratage/typography`, with no Author Surface and no graph Type unless a real cross-package edge
+later requires one:
+
+- Unicode grapheme/word/bidi segmentation;
+- exact font-stack loading and shaping;
+- gradient stops, ordered strokes/shadows/glows and box decoration geometry;
+- line-fragment and joined-Pill geometry;
+- grapheme-safe typewriter and deterministic selector evaluation;
+- terminal rich-text lowering helpers.
+
+This does not create a universal Text Program. Caption keeps `CaptionDisplaySequence`, Cue, Atom,
+speech correspondence and karaoke timing. Text keeps paragraphs, rich runs, point/area/path layout
+and arbitrary sequence selectors.
+
+Concrete Caption improvements discovered by this audit are:
+
+1. allow repeated ordered Stroke/Shadow/Glow layers instead of the current one-of-each ceiling;
+2. allow arbitrary gradient stops and radial as well as two-stop linear gradients;
+3. reuse explicit inner/center/outer Stroke semantics rather than renderer-dependent outline
+ behavior;
+4. reuse grapheme-safe text transform/reveal and exact shaping;
+5. keep joined active-Pill geometry on the shared line-fragment implementation.
+
+Caption must **not** inherit Text ellipsis, clipping, shrink-to-fit, path flow, arbitrary rich-run
+timing or selector-generated speech timing. It always displays the author's complete immutable
+Atoms and activates only from proven Atom windows.
+
+## 13. Migration order and acceptance gates
+
+Implementation should replace the current slice rather than accrete compatibility fields:
+
+1. define Text Document, Point/Area tagged geometry, Text Style and ordered Paint values;
+2. implement exact fonts, plain/phrase/line/word/grapheme Box Paint and rich-run static lowering;
+3. route every item through shared Temporal Window Projection and the specified shared Spatial
+ source;
+4. add deterministic overflow, direction/writing mode and browser pixel evidence;
+5. add item motion and Unicode-aware sequence selectors;
+6. add Path Text and typed local mask support or materialized witnesses;
+7. prove the `CompositableSurface` escape route with one 3D or otherwise non-native Text package;
+8. only then decide the smallest Visual IR revision and freeze it.
+
+Acceptance requires browser/render evidence for at least:
+
+- transparent Point Text and fixed Area Text;
+- content, frame, multiline line, isolated word, joined word and grapheme boxes;
+- nested run styles across wrapping boundaries;
+- Latin, CJK, RTL, combining marks and color Emoji with exact fonts;
+- repeated outside/inside strokes, multiple shadows, linear/radial gradients and glow;
+- visible/clip/ellipsis/bounded-shrink overflow;
+- item enter/exit/loop and forward/reverse grapheme/word/line sequencing;
+- Path Text;
+- explicit Text Mask ownership and one materialized advanced fallback;
+- no modification to Core, Runtime, Film or an unrelated Track package.
+
+Until those gates pass, the current Text package proves the graph path only and must not be
+described as a complete or frozen Text system.
diff --git a/spec/track-authoring.md b/spec/track-authoring.md
new file mode 100644
index 00000000..95cae35f
--- /dev/null
+++ b/spec/track-authoring.md
@@ -0,0 +1,467 @@
+# SVML Video Track Authoring Model
+
+Status: executable temporal authority for the next official Track-package migration. The focused
+`@narratage/temporal` package implements strict occurrence expansion, exact rational window
+projection and triggered sibling schedules. Shared Spatial, Text, Ranking, Media,
+Audio and Screen Overlay are now specified in [`spatial-layout.md`](./spatial-layout.md),
+[`text-track.md`](./text-track.md), [`ranking-track.md`](./ranking-track.md),
+[`media-track.md`](./media-track.md), [`deck-track.md`](./deck-track.md),
+[`audio-track.md`](./audio-track.md) and
+[`screen-overlay.md`](./screen-overlay.md). Comment Sticker remains independent future work and
+does not block the packages already specified here. This is deliberately not a compatibility
+promise for a released public ABI.
+
+## Purpose
+
+Official video packages need one shared discipline without one universal Track Program. Text,
+Media, Ranking and Comment Sticker own different author meanings, but they must not independently
+invent incompatible ways to answer the same temporal questions.
+
+This document governs package Programs and their deterministic lowering. It does not add video
+meaning to Core, Runtime, Composition or a Provider. The public terminal waist remains
+[`VisualTrack` and `AudioTrack`](./track-composition.md).
+
+The complete package-authoring separation is:
+
+```text
+content
+temporal source
+occurrence expansion
+window projection
+optional sibling sequencing
+intrinsic-material occupancy
+spatial source and layout
+presentation
+```
+
+These are independent authoring concerns, not mandatory fields in every package and not fields on
+the public Track contract.
+
+## 1. Temporal pipeline
+
+```text
+Narrative Selection ──> { start, end } occurrences ─┐
+Narrative Moment ─────> { cue } occurrences ────────┼─> occurrence expansion
+Program singleton ────> { program.start/end } ──────┘
+ │
+ ▼
+ Temporal Window Projection
+ │
+ ▼
+ raw directed candidate windows
+ │
+ ▼
+ ProgramSpace intersection + validation
+ │
+ ▼
+ frame-exact projected windows
+ │
+ ▼
+ optional package-owned sibling sequencing
+ │
+ ▼
+ final allowed windows
+ │
+ ▼
+ intrinsic-material occupancy / playback
+ │
+ ▼
+ render intervals + source-time sampling
+```
+
+The layers answer different questions:
+
+| Layer | Question |
+|---|---|
+| anchor location | At which physical frame is an authored anchor? |
+| occurrence expansion | Does one authored item consume exactly one occurrence or every occurrence? |
+| window projection | Which ProgramSpace interval may this occurrence occupy? |
+| sibling sequencing | How do related items hand off, overlap or close one another? |
+| occupancy | How does a product with intrinsic duration sample itself inside its final window? |
+
+No `full`, `fixed`, `relative`, `from`, `until`, `fill` or `fit` union may collapse these layers
+again. An author Surface may offer readable shorthand, but it must lower to the separated model.
+
+## 2. Temporal sources provide points, not renderable windows
+
+A Selection occurrence contributes an ordered pair of located points:
+
+```ts
+type LocatedSelectionOccurrence = {
+ readonly id: string;
+ readonly start: FramePoint;
+ readonly end: FramePoint;
+};
+```
+
+A Moment occurrence contributes one located point:
+
+```ts
+type LocatedMomentOccurrence = {
+ readonly id: string;
+ readonly cue: FramePoint;
+};
+```
+
+A Program source is a singleton occurrence. Every projection environment also has the two exact
+ProgramSpace boundaries `program.start` and `program.end`.
+
+Selection location must preserve Script occurrence order and the two authored anchor identities. It
+must not sort, merge, clip, exchange or take the absolute difference of the points. A located
+Selection whose `end` precedes its `start` remains valid point evidence. Only a consumer creates a
+window and therefore only the projection layer can decide whether the points it actually consumes
+form a valid interval.
+
+A component-owned exact time product, such as an already timed Caption Cue, may enter the later
+frame-window stages directly. It does not need to pretend that its own timing came from a Narrative
+Selection.
+
+## 3. Point expressions and Temporal Window Projection
+
+The shared projection algebra is conceptually:
+
+```ts
+type TemporalPointExpression =
+ | { readonly ref: "program.start"; readonly offset?: Duration }
+ | { readonly ref: "program.end"; readonly offset?: Duration }
+ | { readonly ref: "selection.start"; readonly offset?: Duration }
+ | { readonly ref: "selection.end"; readonly offset?: Duration }
+ | { readonly ref: "moment.cue"; readonly offset?: Duration }
+ | { readonly ref: "absolute"; readonly at: Duration };
+
+type TemporalWindowProjection = {
+ readonly start: TemporalPointExpression;
+ readonly end: TemporalPointExpression;
+};
+```
+
+The serialized contract will use explicit units for durations. Seconds, milliseconds and integral
+frames are distinct author inputs; conversion to a rational ProgramSpace must have one deterministic
+boundary-quantization rule. `base_start` and `base_end` are retired names because the current
+architecture has no privileged Base Track.
+
+Common author meanings are ordinary expressions:
+
+| Meaning | Projection |
+|---|---|
+| complete Program | `[program.start, program.end]` |
+| identity Selection | `[selection.start, selection.end]` |
+| three seconds from Selection start | `[selection.start, selection.start + 3s]` |
+| three seconds after Selection | `[selection.end, selection.end + 3s]` |
+| persist from Selection start | `[selection.start, program.end]` |
+| lead two seconds into Selection start | `[selection.start - 2s, selection.start]` |
+| three seconds after a Moment | `[moment.cue, moment.cue + 3s]` |
+| first three seconds | `[program.start, program.start + 3s]` |
+| absolute advanced window | `[absolute(2.5s), absolute(6s)]` |
+
+`full`, `manual`, `fixed` and `relative` may remain presentation words in an authoring UI, but they
+are not distinct compiled timing laws.
+
+### Semantic binding may deliberately ignore local coordinates
+
+An author may bind an item to a Selection over the opening words while projecting it to
+`[program.start, program.start + 3s]`. The Selection still contributes author meaning, occurrence
+identity, cardinality and dependency truth even though its located start/end coordinates are not
+used by that projection.
+
+This is valid with `one`. It is deliberately restricted with `each`, as defined below, because
+repeating an occurrence-invariant projection would otherwise manufacture identical windows.
+
+## 4. Occurrence expansion is strict and precedes projection
+
+The old shape `{ kind: "single", cardinality: "exactly_one" }` repeats one fact twice. The new
+contract should have two non-overlapping choices, provisionally named:
+
+```ts
+type OccurrenceExpansion =
+ | { readonly kind: "one" }
+ | { readonly kind: "each" };
+```
+
+`each` means compile-time expansion, not media looping. The final author spelling may use
+`for-each` if that avoids confusion with playback terminology.
+
+### `one`
+
+`one` has the following exact law:
+
+1. locate the complete source occurrence set;
+2. require its cardinality to equal one before evaluating the projection;
+3. reject zero or more than one occurrence;
+4. never choose `first`, `last`, `best`, nearest or earliest;
+5. project that one occurrence exactly once.
+
+A projection that ignores Selection/Moment coordinates is normally paired with `one`. Program-only
+timing uses the intrinsic singleton Program source and therefore also lowers as `one` without an
+author-visible cardinality setting.
+
+### `each`
+
+`each` has the following exact law:
+
+1. require one or more located source occurrences;
+2. preserve source occurrence identity and source order;
+3. instantiate exactly one projected occurrence for every source occurrence;
+4. evaluate the same projection independently in each occurrence's local point environment;
+5. derive stable result identity from the authored item id and occurrence id, never an incidental
+ sorted index;
+6. never merge, deduplicate, sort by time, pick a winner or silently discard an occurrence;
+7. fail the whole deterministic Operation when any occurrence cannot produce a valid window.
+
+For more than one source occurrence, at least one projection boundary must reference a local point
+(`selection.start`, `selection.end` or `moment.cue`). A projection using only Program or absolute
+points is occurrence-invariant and is rejected under `each`: it would create several semantically
+different instances with the same physical window and no temporal distinction. The author should
+use `one`, bind the Program singleton, or author separate explicit items.
+
+Projection is one-to-one. One occurrence cannot fan out into several windows. An author who wants
+two windows from one Selection or Moment writes two items or uses a package-owned component that
+explicitly constructs those two items.
+
+Set aggregation is not a third generic expansion mode. A visibility mask or another genuinely
+set-valued component may define a package-owned set consumer, but ordinary visual items must not use
+that exception to regain hidden merge, union or deduplication behavior.
+
+Caption `Mute` is one concrete package-owned example. It unions explicitly referenced
+`CaptionDisplayWordSubset` values inside `CaptionProgram`; it does not alter generic occurrence
+expansion, manufacture projected windows, or enter Core.
+
+### Cardinality does not decide overlap
+
+`each` says only how an occurrence set expands. It does not say whether the resulting windows may
+overlap, whether adjacent windows should join, or whether one item closes at the next item's cue.
+Those questions cannot be answered before projection and may also depend on package semantics.
+
+After projection, a consuming package must choose and validate one explicit relation appropriate to
+its component, for example:
+
+- `independent`: overlapping windows are meaningful and remain independent;
+- `disjoint`: any overlap between occurrences of the same authored item is an error;
+- a package-owned Sequence or Deck policy that derives final sibling windows and handoffs.
+
+This relation is not part of `OccurrenceExpansion` and is not owned by Core. Official simple Text,
+Comment Sticker and similar repeated items should normally require disjoint projected windows.
+Media groups and Ranking components may own stronger, explicit sibling rules. No package receives a
+hidden global auto-stitch behavior.
+
+### Triggered stages are sibling sequencing, not another temporal source
+
+Ranking, Tier, slides and other progressive components often have only an ordered set of trigger
+Moments. Reaching trigger `i` enters state `i`; reaching trigger `i + 1` hands off to the next state.
+This case uses the same point location and window projection. It does not justify a `Stage` Type in
+Core or another Script marker.
+
+`N` trigger points alone cannot bound `N` finite stages: the last stage still needs one terminal
+boundary. A triggered component therefore owns an explicit outer window `[B, O)` and an explicit
+stage-terminal point `T`. `T` may reference `O`, but the package must not silently assume that it
+does. Keeping them separate lets a Ranking component finish its last item at `T` and leave the
+fully-settled board visible until `O`. Given located and frame-quantized trigger points
+`p1 ... pN`, the package may derive:
+
+```text
+stage 1 [p1, p2)
+stage 2 [p2, p3)
+...
+stage N [pN, T)
+settled suffix [T, O) (when T < O)
+```
+
+The interval before `p1` is inactive, not an implicit stage zero. If a design needs an initial
+visible state from the enclosing start to `p1`, that state must be explicit and produces `N + 1`
+stages. A renderer must never infer it from the presence of a board or background.
+
+This pattern has two related but distinct package-owned lowerings:
+
+```text
+outer component [B, O)
+cumulative item 1 [p1, O)
+cumulative item 2 [p2, O)
+cumulative item 3 [p3, O)
+
+exclusive stage 1 [p1, p2)
+exclusive stage 2 [p2, p3)
+exclusive stage 3 [p3, T)
+settled suffix [T, O) when T < O
+```
+
+The cumulative form is ordinary `each` projection of `[moment.cue, outer.end]` with an explicit
+overlap policy. It naturally implements a Tier board: after `p2`, both item 1 and item 2 are active;
+the visible prefix itself is the current logical state. No materialized board snapshot is required.
+
+The exclusive form starts from the same candidates and applies a successor-handoff policy: each
+candidate's final end becomes the next candidate's start, while the last ends at `T`. This can drive
+a Ranking staging area that shows exactly one current item while already-settled items remain as a
+separate cumulative prefix. When `T < O`, the suffix has no current item and shows the completed
+state. The package may lower both views into independent Presents in one peer `VisualTrack`.
+
+Triggered sequencing has the following exact law:
+
+1. preserve authored/source occurrence order and stable occurrence identity;
+2. never sort triggers by physical time;
+3. require at least one trigger, one explicit outer window and one explicit stage-terminal point;
+4. after frame quantization, require `B <= p1 < p2 < ... < pN < T <= O`;
+5. reject reversed triggers, equal-frame collisions, triggers outside the outer window and a last
+ trigger at or beyond `T` atomically;
+6. zip an ordered item list to trigger occurrences only when the component contract explicitly says
+ so and requires equal cardinality;
+7. derive item/stage identities from authored item and occurrence identities, never array indexes;
+8. keep cumulative overlap or successor handoff as declared package semantics, never Runtime choice.
+
+A package may instead give every child item its own single-occurrence Moment edge. Both author
+surfaces lower to the same ordered sibling candidates; positional zipping is not an implicit global
+behavior. Triggered stages are internal deterministic lowering facts unless another component has a
+real need to consume them. Composition still receives only ordinary Presents.
+
+## 5. Projection validation and negative intervals
+
+For each expanded occurrence, projection executes in this order:
+
+1. evaluate raw start and raw end in the exact rational ProgramSpace;
+2. reject missing, non-finite or type-invalid point expressions;
+3. if raw end precedes raw start, reject a reversed window before clipping;
+4. if raw end equals raw start, reject a zero-length render window;
+5. intersect the forward raw window with `[program.start, program.end)`;
+6. deterministically quantize it to a half-open integer frame span;
+7. reject an empty result or a result shorter than one frame;
+8. return only `{ startFrame, endFrameExclusive }` values wholly inside ProgramSpace.
+
+Clipping to ProgramSpace is the mathematical intersection with the only observable render domain,
+not guessed timing. A negative intermediate point is therefore allowed:
+
+```text
+cue = 1s
+[cue - 3s, cue + 2s] = [-2s, 3s]
+intersection [0s, 3s]
+```
+
+A raw reversed interval must never be hidden by clipping, sorting or absolute value. An interval
+entirely outside ProgramSpace becomes empty and fails; it is not silently omitted. Renderers receive
+only already validated frame spans and perform no temporal repair.
+
+A crossed Selection anchor pair is not by itself a projection failure. Identity projection
+`[selection.start, selection.end]` fails when it produces a reversed window, while
+`[selection.start, program.end]` may remain valid because it does not consume the crossed end point.
+
+## 6. Intrinsic duration and occupancy
+
+Every presented product either has a verified intrinsic duration or it does not. Unknown duration
+must not masquerade as either case; media inspection must establish it before an intrinsic-duration
+occupancy policy can execute.
+
+Durationless products such as Text, static images, Comment Stickers and ordinary Ranking UI occupy
+their complete final projected window. Local enter, exit and loop animation is presentation inside
+that window, not synthetic material duration.
+
+An intrinsic-duration product receives a final allowed window and an explicit playback policy. The
+conceptual visual policies are:
+
+```ts
+type IntrinsicPlayback =
+ | { readonly mode: "once"; readonly align: "start" | "end" }
+ | { readonly mode: "hold"; readonly align: "start" | "end" }
+ | { readonly mode: "loop"; readonly align: "start" | "end" }
+ | { readonly mode: "stretch" };
+```
+
+`once` replaces the ambiguous old word `finish`. End alignment never means reverse playback. It
+means the forward-playing source ends at the projected window's end. If the source is longer than
+the window, start alignment selects the source head and end alignment selects the source tail.
+
+| Policy | Source shorter than window | Source longer than window |
+|---|---|---|
+| `once/start` | play from window start, then disappear | play source head until window end |
+| `once/end` | appear late and end at window end | play source tail and end at window end |
+| `hold/start` | play, then hold last frame | play source head until window end |
+| `hold/end` | hold first frame, then play to window end | play source tail to window end |
+| `loop/start` | repeat from source head phase | clip after as many loops as fit |
+| `loop/end` | choose loop phase so source tail meets window end | same tail-phase law |
+| `stretch` | slow all source time into the window | accelerate all source time into the window |
+
+Audio must define its own truthful vocabulary over the same schedule. It cannot hold one PCM sample
+as if it were a video frame. Outside one-shot audio is silence, padding is explicit, looping is
+looping and stretching must enforce authored speed bounds. Static images and durationless UI do not
+accept meaningless intrinsic playback modes.
+
+Source trim and source in/out points, when added, operate before occupancy to define the effective
+intrinsic source interval. Spatial contain/cover and Text flow/shrink operate after temporal
+occupancy and are unrelated.
+
+## 7. Package ownership
+
+The former umbrella `contracts` package is intentionally absent. Nominal shared meanings are owned
+by focused modules such as Narrative, ProgramSpace, Media and Composition; Core has no registry of
+video-domain unions.
+
+The temporal algebra in this document should therefore become a focused video-domain package,
+provisionally `@narratage/temporal`. It should own the projection types, validators and pure
+frame-window projection. It may consume Narrative point references, SemanticMap location and
+ProgramSpace, but it must not know Text, Media Track, Ranking, Comment Sticker, Film, HyperFrames,
+Runtime or a Provider.
+
+Official packages then use the same implementation:
+
+```text
+Text ───────────────┐
+Media Track ────────┤
+Deck Track ─────────┤
+Ranking ────────────┼─> @narratage/temporal ─> frame windows
+Comment Sticker ────┤
+Screen Overlay ─────┤
+Audio Track ─────────┘
+```
+
+Caption's component-owned timed Cue projection may enter the final frame-window stage directly.
+Speech Spine establishes ProgramSpace and contiguous speech takes rather than pretending those
+structural cuts are Narrative Selection consumption.
+
+## 8. Migration consequences
+
+The current `text-track` and `broll` author Surfaces support only `during="full"` or an identity
+Selection mapping. They must not independently grow another timing enum. Their rewrites should
+consume the shared temporal package.
+
+The first implementation batch must include tests for:
+
+- Selection and Moment `one` success and cardinality failure;
+- Selection and Moment `each`, stable occurrence identity and source-order preservation;
+- rejection of occurrence-invariant `each` projections with multiple occurrences;
+- all common point-expression combinations, including Program boundaries and absolute time;
+- crossed source anchors consumed and ignored by different projections;
+- negative offsets, ProgramSpace intersection, entirely out-of-range windows, reversed windows,
+ zero windows and the one-frame minimum;
+- rational frame rates and deterministic half-open frame quantization;
+- atomic failure when one of several `each` occurrences is invalid;
+- package-owned disjoint, independent and sequence relations remaining separate from expansion;
+- cumulative and successor-handoff trigger sequences, including explicit terminal boundaries,
+ equal-frame collisions, non-monotonic source order, stable identities and optional explicit
+ initial state;
+- durationless products and shorter/equal/longer intrinsic products under every supported playback
+ and alignment policy;
+- explicit audio behavior rather than reuse of visual `hold` semantics.
+
+## 9. Ranking specialization
+
+The complete Ranking audit, component split, group schedule and migration plan are specified in
+[`ranking-track.md`](./ranking-track.md). Ranking validates that the common temporal algebra can
+support cumulative state, exclusive current stages and a final settled suffix without adding
+Ranking or `Stage` meaning to Core or the public Track contract.
+
+## 10. Remaining design and implementation work
+
+The following work remains, but it does not block rewriting packages whose own specifications and
+shared dependencies are complete:
+
+1. design Comment Sticker content/layout/presentation independently when a real migration starts;
+2. implement the existing acceptance matrix proving all packages lower to peer
+ VisualTrack/AudioTrack values without changing Core or Composition.
+
+Generic Audio Track and self-contained Screen Overlay are now specified separately in
+[`audio-track.md`](./audio-track.md) and [`screen-overlay.md`](./screen-overlay.md). Audio reuses the
+same temporal algebra but has truthful sample occupancy rather than visual hold semantics. Screen
+Overlay is a full-canvas peer contribution, not a cross-Track adjustment layer.
+
+Unified Item/Sequence Media authoring, all motion channels, internal handoffs, explicit audio
+projection and Speech Spine's restricted reuse are now specified in
+[`media-track.md`](./media-track.md). The old depth-stack Deck is an independent higher-order Track
+component specified in [`deck-track.md`](./deck-track.md). B-roll is an editorial Recipe/usage
+rather than another public Track family.
diff --git a/spec/track-expressiveness.md b/spec/track-expressiveness.md
index d6a24085..3f39f89a 100644
--- a/spec/track-expressiveness.md
+++ b/spec/track-expressiveness.md
@@ -16,7 +16,8 @@ This gate answers one question:
Passing this gate does not make one universal `TrackProgram`. The six Track Program axes—content,
temporal source, window projection, spatial source, occupancy and presentation—remain a separation
-discipline for package authors, not six mandatory public fields.
+discipline for package authors, not six mandatory public fields. The shared authoring laws and the
+current temporal design are specified in [`track-authoring.md`](./track-authoring.md).
## Three levels that must not collapse
@@ -57,10 +58,11 @@ A Caption package must be able to lower a hard range boundary, a cue-level align
container, shrink-wrapped rows and independently styled or animated words. Dual-font and per-word
paint are package facts. Composition sees only ordinary elements and Presents.
-### E3 — Media two-box lowering
+### E3 — Media two-frame lowering
-A media package must be able to lower one resolved content box containing two independent samples
-of the same Artifact:
+A media package must be able to lower one resolved Placement Frame containing two independent
+samples of the same Artifact. Each sample derives its own Content Frame according to
+[`spatial-layout.md`](./spatial-layout.md):
- a backdrop sample with its own cover/zoom/blur/tone treatment;
- a foreground sample with its own contain/cover/fit-height and focal alignment.
@@ -81,6 +83,12 @@ Frame-exact opacity, transform, filter and clip animation may operate on element
Present. A package that owns both materials in a handoff may lower complementary Presents. No
ordinary Track may sample the accumulated pixels below it or mutate a sibling Track.
+The Media package must additionally prove that entry, sustain, exit, per-layer sampling motion and
+Sequence pair handoffs remain separate channels with a fixed composition order. The independent
+Depth-Stack Deck package must prove that its collection-state reflow composes with Card-local motion
+without adding Deck meaning to the terminal Track. The complete models are specified in
+[`media-track.md`](./media-track.md) and [`deck-track.md`](./deck-track.md).
+
### E6 — Materialized visual fallback
A component whose deterministic visual result cannot be represented by the reference element tree
@@ -89,6 +97,23 @@ interleaving, the final public contract must bind enough surface information to
compositable alpha-bearing visual from an opaque video. Merely naming a `.webm` Artifact does not
prove this property.
+### E7 — Generic audio lowering
+
+The official Audio package must lower arbitrary explicit normalized sources, source trim, one-shot,
+loop, bounded pitch-preserving stretch, start/end alignment, gain and fades into the same peer
+`AudioTrack` waist. Overlapping clips mix without priority clipping or a privileged Base lane.
+Container stream selection, loudness processing and Provider placement remain explicit upstream or
+downstream graph work. The complete boundary is specified in
+[`audio-track.md`](./audio-track.md).
+
+### E8 — Self-contained screen overlay
+
+A full-canvas effect must lower to ordinary absolute-stack Presents made from owned Visual IR
+elements or an owned alpha-bearing Surface. It cannot read the accumulated lower composite, reserve
+the highest z-index or introduce a post-composition phase. Source-free blur, color-adjust and real
+zoom-blur therefore fail closed; their honest form consumes explicit media or Surface input outside
+the Screen Overlay package. See [`screen-overlay.md`](./screen-overlay.md).
+
## Old-system attack matrix
| Historical behavior | Package-owned truth | Required terminal witness |
@@ -99,9 +124,15 @@ prove this property.
| dual fonts, CJK, emoji and writing direction | Text/Caption Program | text elements plus locked font/layout dependencies |
| media content box plus foreground/backdrop sampling | media package | sibling media elements referencing one Artifact |
| focal crop and fit-height | media package | deterministic sampling/placement result |
+| full-frame B-roll, corner GIF and lower media card | Media Item + Recipes | the same Item lowering against different Frames |
+| explicit media replacement group | Media Sequence | coordinated owned outgoing/incoming Presents |
+| visible card history and depth reflow | Depth-Stack Deck Track | package-owned collection state over ordinary Presents |
| Ranking board and icons at unrelated z | Ranking Program | several absolute-stack Presents |
| B-roll enter/exit and pair transition | B-roll Program | local frame-exact keyframes over owned Presents |
| arbitrary self-contained visual | component/provider | materialized compositable Surface Artifact |
+| music/SFX/additional voice placement | Audio Program | ordinary frame-exact AudioTrack clips |
+| flash/vignette/grain/veil | Screen Overlay Program | owned full-canvas Presents or alpha Surface |
+| blur/color transform of a picture | explicit-input media effect | transformed owned material, never backdrop sampling |
## Current executable evidence
@@ -141,7 +172,7 @@ facts must stay generic; they must not be patched with Caption-, Text- or B-roll
Track v1 may be called a stable public waist only when all of the following hold:
-1. E1–E5 have executable structural and HTML-lowering witnesses;
+1. E1–E8 have executable structural, HTML-lowering and audio-plan witnesses;
2. official Text/Caption lowerers either bind exact font Artifacts or explicitly materialize their
glyph result, and the renderer implementation used for layout is receipt-bound;
3. E6 has a typed compositable-Surface path whose Runtime validates the declared media facts and
diff --git a/tsconfig.json b/tsconfig.json
index a637e9a6..5d9570a6 100644
--- a/tsconfig.json
+++ b/tsconfig.json
@@ -33,6 +33,12 @@
"@narratage/program-space": [
"packages/program-space/src/index.ts"
],
+ "@narratage/temporal": [
+ "packages/temporal/src/index.ts"
+ ],
+ "@narratage/spatial": [
+ "packages/spatial/src/index.ts"
+ ],
"@narratage/speech": [
"packages/speech/src/index.ts"
],