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.
TypeScript agentic-aiaiai-agentsai-videocompilerdslffmpeggenerative-aillmmarkup-languagemonorepoplugin-systemprogramming-languagetext-to-videotypescriptvideovideo-automationvideo-clonevideo-editingvideo-generation
feat: establish shared track authoring foundations
kashorin4d714877aa44
diff --git a/docs/README.md b/docs/README.mdindex 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.mdindex 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, andComposition. 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 VisualTrand 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 onappearance={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 onfill: #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.mdindex 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 StylesheetsSVS (`.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 estimationparameters, generation settings, and typography choices. SVS values are called **Recipes** — they areimmutable 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.```svsfilm.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.```svstext.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.mdindex 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.mdindex 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 pagecovers 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=` consumesthe Caption-specific projection of a Script Selection; the public time Selection remains only apair 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, ora 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.mdindex 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 轴排序完全由每个 Tappearance={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 轴排序完全由每个 Tfill: #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.mdindex 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。```svsfilm.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` 图边提供。```svstext.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.mdindex 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.mdindex 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.svmlindex 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:Itemtext="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.svsindex 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.svmlindex 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.svsindex 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.lockindex 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.svmlindex 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:Itemtext="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.svsindex 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.lockindex 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.svmlindex 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.svsindex 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.lockindex 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.jsonindex 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.tsindex 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.tsindex 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.tsindex 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.mdindex 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-wordsubset, not a second time-range language.diff --git a/packages/caption/src/index.ts b/packages/caption/src/index.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.mdindex 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 vbelongs 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 intheir own typed values. Final rendering is a separate author package and capability.diff --git a/packages/film/package.json b/packages/film/package.jsonindex 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.tsindex 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.tsindex 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.tsindex 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-spimport { 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.tsindex 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: ProgramSpareturn 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.tsindex 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, resolveReconst 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, resolveRefragment: 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.tsindex 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.tsindex 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.tsindex 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 stylefilmSurfaceImplementationDigest,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 styleentry: 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", aassert.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.mdnew file mode 100644index 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.jsonnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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.mdnew file mode 100644index 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.jsonnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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.mdindex 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 reprothree-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.jsonindex 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.tsindex 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.tsindex 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.tsindex 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: TextTrspan: { 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.tsindex 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, operattype 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, resoid: `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, resosuffix,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, resoconst 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, resoheader: { 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.tsindex 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.tsindex 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 Semantid: "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 Semantmap,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.yamlindex 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.mdnew file mode 100644index 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.mdindex 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 nSegment or Turn boundary. All runs are disjoint and partition the display Words exactly once, andno 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 ownedges 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdindex 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 aligncontainer, shrink-wrapped rows and independently styled or animated words. Dual-font and per-wordpaint 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 elementPresent. A package that owns both materials in a handoff may lower complementary Presents. Noordinary 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 fallbackA 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 tocompositable alpha-bearing visual from an opaque video. Merely naming a `.webm` Artifact does notprove 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-rollTrack 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 theirglyph 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 anddiff --git a/tsconfig.json b/tsconfig.jsonindex 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"],