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
docs: publish the specifications and make the README an introduction
rponeaa72b412a6c5
diff --git a/README.md b/README.mdindex 2ec1400a..f86226cc 100644--- a/README.md+++ b/README.md@@ -5,11 +5,13 @@<p align="center"><em>“First, there was narration. Then, there were montages.”</em></p><p align="center">- <a href="https://narratage.hypit.ai/quickstart">Quickstart</a>- - <a href="https://narratage.hypit.ai/guide/develop">Develop</a>- - <a href="./README.zh-CN.md">简体中文</a>+ <a href="https://narratage.hypit.ai/quickstart">Quickstart</a> <a href="https://narratage.hypit.ai/guide/develop">Develop</a> <a href="./README.zh-CN.md">简体中文</a>+</p>++<p align="center">+ <a href="https://github.com/hypit-ai/narratage/actions/workflows/deploy-pages.yml"><img alt="Documentation" src="https://github.com/hypit-ai/narratage/actions/workflows/deploy-pages.yml/badge.svg"></a>+ <a href="./LICENSE"><img alt="License" src="https://img.shields.io/badge/license-Apache--2.0%20with%20conditions-blue.svg"></a>+ <a href="https://github.com/hypit-ai/narratage/stargazers"><img alt="Stars" src="https://img.shields.io/github/stars/hypit-ai/narratage?style=flat"></a></p>Narratage is a semantic, graph-native system for making AI video. You write the story, choose the@@ -19,11 +21,31 @@ available for later Runs.SVML is the authoring language. Narratage is the compiler, runtime and package ecosystem around it.+## Where the name comes from++A 1933 *New York Times* review of *The Power and the Glory* coined **narratage** for a then-new+technique: narration plus montage, a narrator's voice carrying the story while the screen assembles+scenes to match.++That is what this system does. The author writes a narrated Script with semantic anchors, and the+compiler assembles generated video, captions, B-roll, text and audio into a finished film.++## Why a graph++AI generation is slow, costly and non-deterministic, and each output tends to become the next+step's input. Narratage keeps the resulting choices visible as two peer graphs: the Author Graph+expresses the work, the Run Graph selects Targets and Candidates for one Build. Core only resolves,+verifies and advances the resulting state machine, so video concepts stay in independently+installable packages — Core hard-codes no model, Track or Provider.++The normative laws are in the+[Core Kernel specification](https://narratage.hypit.ai/guide/spec/core-kernel).+## What it feels like-The Script remains readable prose. Segments organize the story; Role Cues say who speaks; Dual Text-separates what viewers read from what the speaker says; Selections and Moments name semantic ranges-and points without introducing timecodes.+The Script stays readable prose. Segments organize the story, Role Cues say who speaks, Dual Text+separates what viewers read from what the speaker says, and Selections and Moments name semantic+ranges and points without introducing timecodes.```xml<script id="story">@@ -72,39 +94,29 @@ and points without introducing timecodes.frame={card-frame}/>```-The Script excerpt shows the complete marker vocabulary:+Every marker in that Script:| Form | Meaning ||---|---|-| `<opening>...</opening>` / `<pause/>` | spoken and empty Segments |-| `<MARA>` | a Role Cue; it continues until the next cue or Segment end |-| `<2:13 A.M. \| two thirteen in the morning>` | display text on the left, spoken text on the right |-| `< \| only>` | spoken filler deliberately absent from captions |-| `@mystery ... @/mystery` | Selection whose boundaries absorb inward |-| `~@proof ... @/proof~` | Selection whose boundaries absorb outward |-| repeated `@beat ... @/beat` | one non-contiguous Selection with multiple occurrences |-| `@flash!` / `~@cut!` | Moments attached to the next word start / previous word end |-| `\@midnight` | a literal `@midnight`, not a marker |-| `<!-- ... -->` | a source comment; it enters no text projection |--`@whole` crosses Segment boundaries; `@claim` and `proof` demonstrate that Selections may cross-instead of nesting. `tagline` shows that a Segment may be roleless. Repeating the same Selection id-creates multiple non-contiguous occurrences.-Marker names carry no built-in behavior: `@silence` does not mute audio; an Audio, Caption or Track-component must explicitly consume that Selection. The complete escape set and Slot parser contract-are documented in [Script](https://narratage.hypit.ai/quickstart/script). Slot binding is not yet-exposed by the author-facing `<script>` Surface.--The outer component lines are deliberately an excerpt: they show how generated media, alignment and-Tracks consume Script projections. See the complete, checkable-[`talking-film-graph-check`](./examples/talking-film-graph-check/main.svml) source for imports,-layout, captions, Film and rendering. Namespaced components come from packages; Core does not-hard-code Seedance, WhisperX, Caption or Film.+| `<opening>...</opening>` / `<pause/>` | a spoken Segment, and an empty one |+| `<MARA>` | a Role Cue, in force until the next cue or the end of the Segment |+| `<2:13 A.M. \| two thirteen in the morning>` | left is displayed, right is spoken |+| `< \| only>` | spoken, never captioned |+| `@mystery ... @/mystery` | a Selection covering exactly the words between the markers |+| `~@proof ... @/proof~` | the same, but reaching out to take in the neighbouring word on each side |+| repeated `@beat ... @/beat` | one Selection that appears in more than one place |+| `@flash!` / `~@cut!` | a Moment on the next word's start / the previous word's end |+| `\@midnight` | the literal text `@midnight` |+| `<!-- ... -->` | a comment; it never reaches any output text |++A marker name carries no behaviour of its own: `@silence` does not mute audio, and an Audio,+Caption or Track component must explicitly consume that Selection. The full vocabulary is in+[Script](https://narratage.hypit.ai/quickstart/script); the complete checkable source is+[`talking-film-graph-check`](./examples/talking-film-graph-check/main.svml).## Try it without API keys-You need Node.js 22+ and pnpm 10.33.x. These commands install the source workspace and compile a-complete video graph without starting a Provider or making a paid request:+Node.js 22+ and pnpm 10.33.x:```bashgit clone https://github.com/hypit-ai/narratage.git@@ -120,112 +132,14 @@ node --run narratage -- plan examples/talking-film-graph-check/build.svrun \````check` verifies the Author Source and prints its typed outputs. `plan` shows the exact demanded-subgraph and every external capability a real Build would need. Planning never starts external work.--See the [Quickstart](https://narratage.hypit.ai/quickstart) if Corepack is unavailable or you want to run local media,-WhisperX, OpenCV or HyperFrames.--## The files you control--| File | Purpose |-|---|---|-| `main.svml` | The video: Script, chosen models, Tracks and Composition |-| `studio.svs` | Optional reusable visual and prompt Recipes imported by the Author Source |-| `build.svrun` | The outputs required for one Run, including explicit reuse or alternate Candidates |-| `svml.runtime.json` | The machine environment: stores, endpoints, credentials and concurrency |-| `svml.packages.lock` | Generated lock for author and compute packages |-| `svml.runtime-packages.lock` | Generated lock for Runtime and Provider packages |--- SVML says what the author means and explicitly chooses model families where that choice matters.-- SVRUN says what this Run should produce and which compatible results should satisfy its outputs.-- The Runtime Profile says where those operations execute.-- Providers translate exact capability requests into local programs or remote APIs. They do not- reinterpret the author's creative choice.--## From source to output--```text-main.svml + studio.svs- │- ▼- Author Graph ◀──── build.svrun selects Targets and Candidates- │- ▼- frozen BuildPlan no external work has started yet- │- ▼- Runtime Profile ─────── Worker, Stores and exact Provider Endpoints- │- ▼- accepted Records ────── inspect, reuse, or materialize with `get`-```--There is no privileged “final video” root. A Run can target a generated image, a transcript map, a-Track, or the completed video. The compiler follows dependencies backward from those Targets and-does not schedule unrelated work.--## Run a real project--Keep video projects outside the Narratage checkout. During source development, call the checkout's-lightweight launcher from the project directory:+subgraph and every external capability a real Build would need, without starting any of it.-```bash-cd /path/to/my-video--# Setup once, then repeat only after imports or Runtime package choices change.-/path/to/narratage/narratage packages sync build.svrun \- --runtime svml.runtime.json--# See the exact work selected by this Run.-/path/to/narratage/narratage plan build.svrun \- --runtime svml.runtime.json--/path/to/narratage/narratage build build.svrun \- --runtime svml.runtime.json \- --build-id my-video-001 \- --follow--/path/to/narratage/narratage get my-video-001 \- --runtime svml.runtime.json \- --name final.video \- --to output/final.mp4-```--`build` submits durable work and ensures the selected Worker is available. `--follow` only observes-that Build; closing the observer does not cancel it. Use `status`, `queue`, `operations` and-`inspect` to see what is happening. `check` is useful while editing source; `doctor` diagnoses the-whole deployment when setting up or troubleshooting it. Neither is a ritual before every Build.--Read [Run Source & Builds](https://narratage.hypit.ai/quickstart/run) before the first paid Build. It covers Runtime-Profiles, credentials, concurrency, cancellation and explicit reuse of previous outputs.--## Why a graph language+## Where to go next-AI generation is slow, costly, fallible and non-deterministic. Its outputs often become the next-step's inputs. A linear script or hidden workflow runner cannot clearly answer all of these questions:--- What did the author request?-- Which result is required right now?-- Which implementation and Provider will produce it?-- Which earlier image or video should be reused deliberately?-- What can run in parallel, and what is waiting on an upstream result?-- What actually produced the accepted output?--Narratage makes those choices visible as two peer graphs: the Author Graph expresses the work, and-the Run Graph selects Targets and realizations for one Build. Core only resolves, verifies and-advances the resulting state machine; video concepts remain in independently installable packages.--For the small normative laws, read the [Core Kernel specification](./spec/core-kernel.md).--## Development--The commands below are for changing Narratage itself, not for making a video:--```bash-pnpm check-pnpm test-pnpm docs:build-```+- [Quickstart](https://narratage.hypit.ai/quickstart) — the files you control, the commands, and+ your first real Build.+- [Develop](https://narratage.hypit.ai/guide/develop) — package architecture, adding an author+ package or a Provider, and the normative specifications.## Licensediff --git a/README.zh-CN.md b/README.zh-CN.mdindex e564bcfc..16097fa1 100644--- a/README.zh-CN.md+++ b/README.zh-CN.md@@ -5,11 +5,13 @@<p align="center"><em>“First, there was narration. Then, there were montages.”</em></p><p align="center">- <a href="https://narratage.hypit.ai/zh/quickstart">快速开始</a>- - <a href="https://narratage.hypit.ai/zh/guide/develop">开发</a>- - <a href="./README.md">English</a>+ <a href="https://narratage.hypit.ai/zh/quickstart">快速开始</a> <a href="https://narratage.hypit.ai/zh/guide/develop">开发</a> <a href="./README.md">English</a>+</p>++<p align="center">+ <a href="https://github.com/hypit-ai/narratage/actions/workflows/deploy-pages.yml"><img alt="Documentation" src="https://github.com/hypit-ai/narratage/actions/workflows/deploy-pages.yml/badge.svg"></a>+ <a href="./LICENSE"><img alt="License" src="https://img.shields.io/badge/license-Apache--2.0%20with%20conditions-blue.svg"></a>+ <a href="https://github.com/hypit-ai/narratage/stargazers"><img alt="Stars" src="https://img.shields.io/github/stars/hypit-ai/narratage?style=flat"></a></p>Narratage 是一套面向 AI 视频创作的语义化、图原生系统。你写下故事,选择模型与视觉组件,声明想要哪些@@ -18,6 +20,23 @@ Narratage 是一套面向 AI 视频创作的语义化、图原生系统。你写SVML 是创作语言,Narratage 是围绕它的编译器、运行时与包生态。+## 名字的由来++1933 年《*New York Times*》对电影《*The Power and the Glory*》的一篇影评造出了 **narratage** 这个+词,用来描述当时的一种新兴手法:旁白加蒙太奇——声音推动故事前进,画面组接出与之呼应的段落。++这套系统做的正是这件事。作者写下带有语义锚点的口播 Script,编译器把生成的视频、字幕、B-roll、文字+与音频组装成一部完成的影片。++## 为什么用图++AI 生成慢、贵、不确定,而且每一步的输出往往就是下一步的输入。Narratage 把由此产生的选择呈现为两张+平级的图:Author Graph 表达工作本身,Run Graph 为一次 Build 选择 Target 与 Candidate。Core 只负责+解析、校验并推进由此得到的状态机,因此视频领域的概念都留在可独立安装的包里——Core 不硬编码任何模型、+Track 或 Provider。++规范性法则见 [Core Kernel 规范](https://narratage.hypit.ai/zh/guide/spec/core-kernel)。+## 它写起来是什么样Script 始终是可读的散文。Segment 组织故事,Role Cue 指明谁在说话,Dual Text 把观众看到的文字与说话者@@ -70,35 +89,28 @@ Script 始终是可读的散文。Segment 组织故事,Role Cue 指明谁在frame={card-frame}/>```-这段 Script 展示了完整的标记词汇:+上面这段 Script 里的每一个标记:| 写法 | 含义 ||---|---|-| `<opening>...</opening>` / `<pause/>` | 有台词的 Segment 与空 Segment |-| `<MARA>` | Role Cue,持续到下一个 Cue 或 Segment 结束 |-| `<2:13 A.M. \| two thirteen in the morning>` | 左侧为显示文字,右侧为念出的文字 |-| `< \| only>` | 只念不显示的口语衬词 |-| `@mystery ... @/mystery` | 边界向内吸收的 Selection |-| `~@proof ... @/proof~` | 边界向外吸收的 Selection |-| 重复的 `@beat ... @/beat` | 一个 Selection 的多次不连续出现 |-| `@flash!` / `~@cut!` | 附着在下一个词开头 / 上一个词结尾的 Moment |-| `\@midnight` | 字面量 `@midnight`,不是标记 |-| `<!-- ... -->` | 源码注释,不进入任何文字投影 |--`@whole` 跨越了 Segment 边界;`@claim` 与 `proof` 表明 Selection 可以交叉而非只能嵌套;`tagline`-说明 Segment 可以没有角色。重复同一个 Selection id 会产生多次不连续的出现。-标记名本身不带行为:`@silence` 不会让音频静音,必须由 Audio、Caption 或 Track 组件显式消费这个-Selection。完整的转义规则与 Slot 解析契约见 [Script](https://narratage.hypit.ai/zh/quickstart/script)。-面向作者的 `<script>` Surface 目前尚未暴露 Slot 绑定。+| `<opening>...</opening>` / `<pause/>` | 一个有台词的 Segment,和一个空的 |+| `<MARA>` | Role Cue,一直生效到下一个 Cue 或本 Segment 结束 |+| `<2:13 A.M. \| two thirteen in the morning>` | 左边显示,右边念出 |+| `< \| only>` | 只念,不进字幕 |+| `@mystery ... @/mystery` | Selection,恰好覆盖两个标记之间的词 |+| `~@proof ... @/proof~` | 同上,但两端各向外多吃掉相邻的一个词 |+| 重复的 `@beat ... @/beat` | 同一个 Selection 出现在多个位置 |+| `@flash!` / `~@cut!` | Moment,落在下一个词的词首/上一个词的词尾 |+| `\@midnight` | 字面量 `@midnight` |+| `<!-- ... -->` | 注释,不会进入任何输出文字 |-外层的组件行是刻意节选的,用来展示生成媒体、对齐与 Track 如何消费 Script 的投影。完整且可检查的源码-见 [`talking-film-graph-check`](./examples/talking-film-graph-check/main.svml),其中包含 import、-布局、字幕、Film 与渲染。带命名空间的组件都来自包,Core 不硬编码 Seedance、WhisperX、Caption 或 Film。+标记名本身不带行为:`@silence` 不会让音频静音,必须由 Audio、Caption 或 Track 组件显式消费这个+Selection。完整词汇见 [Script](https://narratage.hypit.ai/zh/quickstart/script);完整且可检查的源码见+[`talking-film-graph-check`](./examples/talking-film-graph-check/main.svml)。## 不需要 API Key 也能试-需要 Node.js 22+ 与 pnpm 10.33.x。下面的命令会安装源码工作区,并在不启动任何 Provider、不产生任何-付费请求的前提下编译出一张完整的视频图:+需要 Node.js 22+ 与 pnpm 10.33.x:```bashgit clone https://github.com/hypit-ai/narratage.git@@ -114,108 +126,13 @@ node --run narratage -- plan examples/talking-film-graph-check/build.svrun \````check` 校验 Author Source 并打印它的类型化输出。`plan` 展示被真正需要的子图,以及一次真实 Build 会-用到的每一项外部能力。Plan 阶段永远不会启动外部工作。--如果 Corepack 不可用,或者你想运行本地 media、WhisperX、OpenCV 或 HyperFrames,请看-[快速开始](https://narratage.hypit.ai/zh/quickstart)。--## 你掌控的文件--| 文件 | 用途 |-|---|---|-| `main.svml` | 这支视频:Script、所选模型、Track 与 Composition |-| `studio.svs` | 可选。由 Author Source 导入的可复用视觉与提示词 Recipe |-| `build.svrun` | 一次 Run 需要的输出,包括显式复用或替换的 Candidate |-| `svml.runtime.json` | 机器环境:Store、Endpoint、凭据与并发 |-| `svml.packages.lock` | 生成的 Author 与计算包 lock |-| `svml.runtime-packages.lock` | 生成的 Runtime 与 Provider 包 lock |--- SVML 表达作者的意图,并在模型族的选择会影响结果时显式作出选择。-- SVRUN 表达这次 Run 要产出什么,以及哪些既有结果可以满足这些输出。-- Runtime Profile 表达这些 Operation 在哪里执行。-- Provider 把精确的能力请求翻译成本地程序或远程 API,不会重新解释作者的创作选择。--## 从源码到成品--```text-main.svml + studio.svs- │- ▼- Author Graph ◀──── build.svrun 选择 Target 与 Candidate- │- ▼- 冻结的 BuildPlan 此时尚未启动任何外部工作- │- ▼- Runtime Profile ─────── Worker、Store 与确切的 Provider Endpoint- │- ▼- 已接受的 Record ────── 可检查、可复用,或用 `get` 取出-```--不存在特权化的“最终视频”根节点。一次 Run 的 Target 可以是一张生成的图片、一份转写映射、一条 Track,-也可以是完成的成片。编译器从这些 Target 反向追溯依赖,不调度无关的工作。--## 跑一个真实项目+用到的每一项外部能力,但不会启动其中任何一项。-把视频项目放在 Narratage 仓库之外。源码开发阶段,从项目目录调用仓库里的轻量启动器:+## 接下来去哪-```bash-cd /path/to/my-video--# 一次性配置,之后只在 import 或 Runtime 包选择变化后重复。-/path/to/narratage/narratage packages sync build.svrun \- --runtime svml.runtime.json--# 看清这次 Run 选中的确切工作。-/path/to/narratage/narratage plan build.svrun \- --runtime svml.runtime.json--/path/to/narratage/narratage build build.svrun \- --runtime svml.runtime.json \- --build-id my-video-001 \- --follow--/path/to/narratage/narratage get my-video-001 \- --runtime svml.runtime.json \- --name final.video \- --to output/final.mp4-```--`build` 提交持久化的工作,并确保选定的 Worker 可用。`--follow` 只是观察这次 Build,关闭观察端不会取消-它。用 `status`、`queue`、`operations` 与 `inspect` 查看正在发生什么。`check` 用于编辑源码,-`doctor` 用于配置和排查部署——它们都不是每次 Build 前必须重复的仪式。--第一次付费 Build 之前,请先读-[Run Source 与 Build](https://narratage.hypit.ai/zh/quickstart/run),其中涵盖 Runtime Profile、-凭据、并发、取消,以及对既有输出的显式复用。--## 为什么用图语言--AI 生成慢、贵、易错,而且不确定;它的输出常常又是下一步的输入。线性脚本或隐藏的工作流执行器无法清楚-回答下面这些问题:--- 作者到底请求了什么?-- 此刻真正需要哪个结果?-- 由哪个实现、哪个 Provider 产出?-- 哪张既有图片或视频应当被有意复用?-- 什么可以并行,什么在等待上游结果?-- 最终被接受的输出究竟由什么产生?--Narratage 把这些选择呈现为两张平级的图:Author Graph 表达工作本身,Run Graph 为一次 Build 选择-Target 与实现。Core 只负责解析、校验并推进由此得到的状态机;视频领域的概念都留在可独立安装的包里。--规范性的最小法则见 [Core Kernel 规范](./spec/core-kernel.md)。--## 开发--下面的命令用于修改 Narratage 本身,不是用来做视频的:--```bash-pnpm check-pnpm test-pnpm docs:build-```+- [快速开始](https://narratage.hypit.ai/zh/quickstart) —— 你掌控的文件、命令,以及第一次真实 Build。+- [开发](https://narratage.hypit.ai/zh/guide/develop) —— 包架构、添加 Author 包或 Provider,以及全部+ 规范文档。## 许可diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.tsindex e3022442..92b1c333 100644--- a/docs/.vitepress/config.ts+++ b/docs/.vitepress/config.ts@@ -161,6 +161,28 @@ const enTheme = {{ text: "Conventions", link: "/guide/conventions" },],},+ {+ text: "Specifications",+ collapsed: true,+ items: [+ { text: "Core Kernel", link: "/guide/spec/core-kernel" },+ { text: "Author Surface Binding", link: "/guide/spec/author-surface-binding" },+ { text: "Script Surface", link: "/guide/spec/script-surface" },+ { text: "Shared Spatial Layout", link: "/guide/spec/spatial-layout" },+ { text: "Track Authoring Model", link: "/guide/spec/track-authoring" },+ { text: "Track and Composition", link: "/guide/spec/track-composition" },+ { text: "Visual IR", link: "/guide/spec/visual-ir" },+ { text: "Track Expressiveness Gate", link: "/guide/spec/track-expressiveness" },+ { text: "Caption Program", link: "/guide/spec/caption-program" },+ { text: "Fine Caption Style", link: "/guide/spec/caption-fine" },+ { text: "Media Track", link: "/guide/spec/media-track" },+ { text: "Typography Track", link: "/guide/spec/typography-track" },+ { text: "Audio Track", link: "/guide/spec/audio-track" },+ { text: "Deck Track", link: "/guide/spec/deck-track" },+ { text: "Ranking Track", link: "/guide/spec/ranking-track" },+ { text: "Screen Overlay", link: "/guide/spec/screen-overlay" },+ ],+ },],},outline: { level: [2, 3] as [number, number], label: "On this page" },@@ -204,6 +226,28 @@ const zhTheme = {{ text: "代码规范", link: "/zh/guide/conventions" },],},+ {+ text: "规范",+ collapsed: true,+ items: [+ { text: "Core Kernel", link: "/zh/guide/spec/core-kernel" },+ { text: "Author Surface 绑定", link: "/zh/guide/spec/author-surface-binding" },+ { text: "Script Surface", link: "/zh/guide/spec/script-surface" },+ { text: "共享空间布局", link: "/zh/guide/spec/spatial-layout" },+ { text: "Track 创作模型", link: "/zh/guide/spec/track-authoring" },+ { text: "Track 与 Composition", link: "/zh/guide/spec/track-composition" },+ { text: "Visual IR", link: "/zh/guide/spec/visual-ir" },+ { text: "Track 表现力门槛", link: "/zh/guide/spec/track-expressiveness" },+ { text: "Caption Program", link: "/zh/guide/spec/caption-program" },+ { text: "Fine Caption 样式族", link: "/zh/guide/spec/caption-fine" },+ { text: "Media Track", link: "/zh/guide/spec/media-track" },+ { text: "Typography Track", link: "/zh/guide/spec/typography-track" },+ { text: "Audio Track", link: "/zh/guide/spec/audio-track" },+ { text: "Deck Track", link: "/zh/guide/spec/deck-track" },+ { text: "Ranking Track", link: "/zh/guide/spec/ranking-track" },+ { text: "Screen Overlay", link: "/zh/guide/spec/screen-overlay" },+ ],+ },],},outline: { level: [2, 3] as [number, number], label: "本页目录" },diff --git a/spec/audio-track.md b/docs/guide/spec/audio-track.mdsimilarity index 98%rename from spec/audio-track.mdrename to docs/guide/spec/audio-track.mdindex d9e00658..338dce0c 100644--- a/spec/audio-track.md+++ b/docs/guide/spec/audio-track.md@@ -1,3 +1,8 @@+---+title: SVML Audio Track Authoring+description: implemented pre-release contract for the generic official Audio Track package, including.+---+# SVML Audio Track AuthoringStatus: implemented pre-release contract for the generic official Audio Track package, includingdiff --git a/spec/author-surface-binding.md b/docs/guide/spec/author-surface-binding.mdsimilarity index 97%rename from spec/author-surface-binding.mdrename to docs/guide/spec/author-surface-binding.mdindex cb27a623..5c99f92a 100644--- a/spec/author-surface-binding.md+++ b/docs/guide/spec/author-surface-binding.md@@ -1,3 +1,8 @@+---+title: Author Surface Binding+description: implemented compiler contract for trusted package-owned Surfaces; third-party isolation is.+---+# Author Surface BindingStatus: implemented compiler contract for trusted package-owned Surfaces; third-party isolation isdiff --git a/spec/caption-fine.md b/docs/guide/spec/caption-fine.mdsimilarity index 98%rename from spec/caption-fine.mdrename to docs/guide/spec/caption-fine.mdindex f5df0748..ded082d1 100644--- a/spec/caption-fine.md+++ b/docs/guide/spec/caption-fine.md@@ -1,3 +1,8 @@+---+title: Fine Caption Style Family+description: implemented pre-release Style family with complete browser evidence for the declared surface.+---+# Fine Caption Style FamilyStatus: implemented pre-release Style family with complete browser evidence for the declared surface.diff --git a/spec/caption-program.md b/docs/guide/spec/caption-program.mdsimilarity index 97%rename from spec/caption-program.mdrename to docs/guide/spec/caption-program.mdindex 7f10ebe1..7c9fcda4 100644--- a/spec/caption-program.md+++ b/docs/guide/spec/caption-program.md@@ -1,3 +1,8 @@+---+title: Caption Program+description: pre-release executable contract.+---+# Caption ProgramStatus: pre-release executable contract.@@ -6,7 +11,7 @@ Status: pre-release executable contract.Caption is an ordinary video component family. It turns immutable authored display text into oneself-contained `VisualTrack`. It has no authority over Script wording, pronunciation, speech-alignment, Provider selection, Runtime realization or Composition order.+alignment, Provider selection, Runtime execution or Composition order.Its two independent graph branches are:@@ -182,5 +187,5 @@ Caption v1 does not define:- a global Caption layer in Composition;- field-specific semantics in Core.-Targets, Candidates and realizations remain external run intent. They do not change Caption data or+Targets and Candidates remain external run intent. They do not change Caption data orplanner semantics.diff --git a/spec/core-kernel.md b/docs/guide/spec/core-kernel.mdsimilarity index 96%rename from spec/core-kernel.mdrename to docs/guide/spec/core-kernel.mdindex fbde85e7..0061681a 100644--- a/spec/core-kernel.md+++ b/docs/guide/spec/core-kernel.md@@ -1,3 +1,8 @@+---+title: Narratage Core Kernel+description: current executable contract. Persisted Graph, BuildRequest, Plan and BuildState wire.+---+# Narratage Core KernelStatus: current executable contract. Persisted Graph, BuildRequest, Plan and BuildState wirediff --git a/spec/deck-track.md b/docs/guide/spec/deck-track.mdsimilarity index 98%rename from spec/deck-track.mdrename to docs/guide/spec/deck-track.mdindex 3b08a9d6..41a577b4 100644--- a/spec/deck-track.md+++ b/docs/guide/spec/deck-track.md@@ -1,3 +1,8 @@+---+title: SVML Depth-Stack Deck Track+description: implemented executable authority for the official depth-stack Deck migration. It records.+---+# SVML Depth-Stack Deck TrackStatus: implemented executable authority for the official depth-stack Deck migration. It recordsdiff --git a/spec/media-track.md b/docs/guide/spec/media-track.mdsimilarity index 99%rename from spec/media-track.mdrename to docs/guide/spec/media-track.mdindex c068c564..457c34ad 100644--- a/spec/media-track.md+++ b/docs/guide/spec/media-track.md@@ -1,3 +1,8 @@+---+title: SVML Media Track Authoring+description: executable pre-release authority for the unified official Media Track. Item/Sequence.+---+# SVML Media Track AuthoringStatus: executable pre-release authority for the unified official Media Track. Item/Sequencediff --git a/spec/ranking-track.md b/docs/guide/spec/ranking-track.mdsimilarity index 98%rename from spec/ranking-track.mdrename to docs/guide/spec/ranking-track.mdindex af50845a..1f217830 100644--- a/spec/ranking-track.md+++ b/docs/guide/spec/ranking-track.md@@ -1,3 +1,8 @@+---+title: SVML Ranking Track Migration+description: implemented executable authority for the official Ranking migration. All four author.+---+# SVML Ranking Track MigrationStatus: implemented executable authority for the official Ranking migration. All four author@@ -65,7 +70,7 @@ The executable author Surface is:<import as="fonts" from="@narratage/fonts-open@1"/><import as="studio" source="./studio.svs"/>-<fonts:Stack id="ranking-fonts" family="inter" weight="700"/>+<fonts:Stack id="ranking-fonts" family="inter" weight="700" style="normal"/><ranking:ColumnStyle id="column-style"recipe={studio.ranking.column}diff --git a/spec/screen-overlay.md b/docs/guide/spec/screen-overlay.mdsimilarity index 98%rename from spec/screen-overlay.mdrename to docs/guide/spec/screen-overlay.mdindex 42eba046..7a67486d 100644--- a/spec/screen-overlay.md+++ b/docs/guide/spec/screen-overlay.md@@ -1,3 +1,8 @@+---+title: SVML Screen Overlay Authoring+description: implemented pre-release contract for the optional official Screen Overlay package. Its.+---+# SVML Screen Overlay AuthoringStatus: implemented pre-release contract for the optional official Screen Overlay package. Itsdiff --git a/docs/guide/spec/script-surface.md b/docs/guide/spec/script-surface.mdnew file mode 100644index 00000000..d1e6fbcd--- /dev/null+++ b/docs/guide/spec/script-surface.md@@ -0,0 +1,696 @@+---+title: SVML Script Surface+description: "Normative contract for the SVML script body: Segment, Role Cue, Dual Text, Selection, Moment and Slot."+---++# SVML Script Surface++> **Draft; not frozen.**+>+> SVML has not been publicly released, so there is no legacy language version to remain+> compatible with. This document directly defines the first public target, Script Surface+> v1; the early prototypes in this repository are not the normative contract. An+> implementation may claim SVML v1 support only after it passes the parser, projection,+> source-map and temporal golden fixtures in this document.++SVML is a semantic video source language, not a pixel rendering format. This document+defines only its most frequent and most readability-critical script region, `<script>`; the+outer document structure for canvas, nodes, styles, generation parameters and the other+Program regions is designed separately. After v1 ships, new semantics should first be+composed out of the constructs already in this document; only when the body syntax genuinely+must change should a new version be published, and early prototype behaviour must never be+used to weaken the current v1.++## One-page contract++Apart from natural language, the body has only six semantic constructs:++| Construct | Owns only | Does not own |+|---|---|---|+| `Segment` | Ordered media/spoken blocks and independent structural endpoints | Automatic Selection, duration, silence |+| `Role Cue` | The "who said what" text prefix in the `dialogue` projection | speaker entities, voice timbre, field routing |+| `Dual Text` | Display text that differs from the actual pronunciation | TTS vendor parameters, styling, motion |+| `Selection` | One or more explicitly closed semantic time intervals | Consumer declarations, absolute seconds |+| `Moment` | One or more explicitly complete semantic instants | Half intervals, durations |+| `Slot` | Injecting runtime text values | Injecting SVML syntax or arbitrary AST |++Comments are trivia, not a seventh semantic construct. Every caption style, B-roll, Ranking,+Deck, sound effect, silence, generation prompt, node port and consumption policy references a+Selection or Moment from outside `<script>`. A consumer does not belong to any one Segment;+one consumer may have several ports, and each port may take one or more Selections/Moments. A+Selection may cross Segments or consist of disconnected intervals, and a Moment may likewise+have several occurrences.++Script compilation MUST first produce a Narrative IR that preserves source mapping, and then+project the three texts from that same IR. Producing three unrelated strings first and then+guessing the correspondence between them is forbidden.++| Projection | Content | Typical consumers |+|---|---|---|+| `dialogue` | Role Cue + actual pronunciation | Dialogue/video generation such as Seedance |+| `speech` | Actual pronunciation only | Estimate, TTS, Speech Reference, alignment |+| `caption` | Display text only | Captions and text display |++## Worked example++```svml+<script>+ @whole++ <hook>+ <A> I just @laugh @pop! <lmao | laughed my @punch ass out @/punch> @/laugh.+ </hook>++ @silence+ <pause/>+ @/silence++ <close>+ <B> Meet <${product} | ${product_pronunciation}>.+ </close>++ @/whole~+</script>+```++If `product = "SVML"` and `product_pronunciation = "ess vee em ell"`, the three text+projections are:++```text+dialogue+A: I just laughed my ass out.+B: Meet ess vee em ell.++speech+I just laughed my ass out.+Meet ess vee em ell.++caption+I just lmao.+Meet SVML.+```++`silence` is only the name of a Selection; it does not automatically mute the audio. It+completely selects the two independent structural endpoints of the empty Segment; actual+silence or footage behaviour is decided by the outer Program. `pop` is a Moment with the+default right affinity, resolved to the onset of `laughed`; it likewise enters no text+projection.++## 1. Document and Segment++In the official Markup Frontend, one `<script>` Surface instance produces one Narrative; the+`<script>` shell is dispatched by Text according to the post-import Surface Registry, and the+Script Parser receives only its raw body. A Script body has only two Segment forms, the named+block and the named empty block:++```svml+<intro>+ Hello.+</intro>++<pause/>+```++Normative rules:++- A Script contains one or more Segments in source order.+- A Segment's tag name is its id; the id is unique within the current Script, and Segments+ MUST NOT nest.+- A Segment opening accepts no attributes; `script` is the reserved name of the outer raw+ Surface and MUST NOT be used as a Segment id.+- Natural language may appear only inside a Segment; between Segments only whitespace,+ Selection/Moment markers and comments are allowed.+- An empty Segment uses the self-closing form. It has structural start/end cut points, but no+ lexical anchor.+- An empty Segment implies neither silence nor any default duration. Its physical duration+ comes from media, from a generation result, or from a Program outside `<script>`.+- A Segment does not automatically declare a Selection of the same name. Selecting one, three+ or any number of Segments MUST be written as an explicit closed Selection.+- Every Segment independently owns two stable identities, `start` and `end`; adjacent+ Segments do not share structural endpoint identity. The two identities may land on the same+ ProgramPoint at a hard cut, or on different points because of overlap or gap, but they MUST+ NOT be merged into one identity.++For example, selecting three consecutive Segments:++```svml+@chapter+<one>+ One.+</one>+<pause/>+<two>+ Two.+</two>+@/chapter+```++## 2. Role Cue++A Role Cue appears only after the parser has entered some Segment body, and it opens a spoken+turn. Its recognition is determined by parse state, independent of logical line starts and+physical newlines:++```svml+<dialogue>+ <A> What time+ is it?+ <B> It’s 8:30.+</dialogue>+```++The following compact form has exactly the same Narrative semantics:++```svml+<dialogue><A> What time is it?<B> It’s 8:30.</dialogue>+```++In the `dialogue` projection the canonical serializer emits it as:++```text+A: What time is it?+B: It’s 8:30.+```++In the `speech` and `caption` projections, both `<A>` and `<B>` are removed. A Role Cue is not+a speaker data model: it creates no character entity, selects no voice, and does not implicitly+group captions. An outer Program may explicitly write `role="A"` to query those spoken turns.+The Caption Program lowers such a query directly into a `CaptionDisplayWordSubset`; it is not a+temporal Selection and does not fabricate a Selection Record. `<A>` on its own triggers no+styling, character, voice or footage behaviour.++To remove ambiguity:++- In Segment body state, a bare angle-bracket construct that contains no unescaped `|`, has no+ attribute and no `/`, and satisfies the Role label character constraints is recognized as a+ Role Cue; it MUST be followed by non-empty spoken content before the next Role Cue or the end+ of the Segment.+- A colon in the body is always body text; the parser never guesses a speaker from `A:`.+- A single non-empty Segment either has no Role Cue at all, or its first spoken atom MUST be+ opened by a Role Cue. Temporal markers, comments and layout whitespace do not count as spoken+ atoms; a Segment that has already begun with cue-less body text MUST NOT switch to cued mode+ partway through.+- A Role Cue's turn continues until the next Role Cue or the end of the Segment. Physical+ newlines inside a turn are layout whitespace only: they do not end the turn, and they do not+ require the Role Cue to be repeated.+- A Role Cue is not a container tag and has no close syntax; forms such as `</A>` and `</B>`+ MUST fail as unknown angle-bracket constructs, and the formatter never emits them.+- A Role label is readable text of 1–32 Unicode characters after NFC; it may consist of Unicode+ Letter, Mark, Number, interior spaces, `_`, `-` and `.`, and MUST NOT have leading or trailing+ whitespace. Quotes, `=`, `/`, newlines, `<`, `>`, `|` and `:` are all illegal, so an unknown+ structural tag carrying attributes is never swallowed as a Role Cue.+- In the `dialogue` projection, the canonical serializer emits a Role Cue boundary as one+ newline plus a `label: ` prefix; in `speech` and `caption` only the cue is removed, and the+ necessary separation between adjacent atoms is preserved. Re-wrapping the source MUST NOT+ change the semantic content of the Narrative IR or of any text projection; the only things+ allowed to change are the source range and the source hash.++## 3. Dual Text++Dual Text writes out the display text and the actual pronunciation at the same time:++```svml+<lmao | laughed my ass out>+```++The left side enters `caption`; the right side enters `dialogue` and `speech`. Ordinary body+text is shorthand for `<text | text>` and needs no markup.++Dual Text is an atomic, non-nestable correspondence unit, not a simple string substitution:++- Either side may be an arbitrary N:M text mapping; the word counts need not be equal.+- After layout whitespace is removed, the right side MUST be non-empty; text that is only+ displayed and never spoken does not belong to Script and should be expressed by an outer+ Text/Deck/Caption Program.+- The left side may be empty: for example `< | um>` means the filler is actually spoken but+ not displayed in captions.+- Slots may be used on both sides; Selections/Moments may appear only on the speech side, and+ only at its lexical token boundaries.+- The entire display side inherits the time span of the entire speech side. If a display word+ needs independent timing, selection or styling, the author MUST split it into several Dual+ Text atoms.+- An ordinary temporal consumer may select part of the tokens on a Dual Text speech side; but+ if a caption ownership/style consumer covers only part of the speech span of a Dual Text+ atom, compilation MUST fail with `partial dual atom` rather than guess how to cut the+ left-side display text.++For example, a legal fine-grained temporal selection:++```svml+<lmao | laughed my @middle ass out @/middle>+```++`middle` may be used by B-roll or a sound effect; if it is used as a local caption replacement+region for that `lmao`, it MUST be an error. The author can provide an explicit mapping by+splitting the atom.++Dual Text expresses only "what was actually said". IPA, SSML, stress, rate, language, emotion,+timbre and vendor-specific pronunciation dictionaries are not a fourth body text layer; they+should be expressed by an outer generation/speech Program that references a Selection or a+lexicon resource.++## 4. Selection++A Selection is a semantic interval declaration that the author closes explicitly:++```svml+@id ... @/id+~@id ... @/id~+```++Every start marker MUST have an end marker with the same id. Script's public value emits, for+every occurrence, an already-resolved `startAnchorId` and `endAnchorId`; there is no start-only+object, no consumer-side default tail completion, and no "half the information was transmitted"+state. Left/right affinity, token indices and source ranges belong to the Parser/Source Map and+do not leak into the public Selection. A downstream that needs physical time MUST project those+two identities together with an explicitly connected `CompleteSemanticMap` into an interval.++"Closed" means both source endpoints are explicitly declared. The physical runtime uses half-open+`[startFrame, endFrameExclusive)` Frame Spans.++### 4.1 Left and right affinity++The marker itself is zero-width and enters no text projection. It sits between two optional+semantic boundaries, one on each side:++| Endpoint form | Affinity | Typical meaning |+|---|---|---|+| `@id` | Right | Start at the word start on the right or the structural endpoint on the right |+| `~@id` | Left | Expand outward to the word end on the left or the structural endpoint on the left |+| `@/id` | Left | End at the word end on the left or the structural endpoint on the left |+| `@/id~` | Right | Expand outward to the word start on the right or the structural endpoint on the right |++Examples:++```svml+before @x hello @/x after+```++`x` runs by default from the word start of `hello` to the word end of `hello`.++```svml+before ~@x hello @/x~ after+```++`x` expands outward on both sides, taking the nearest optional boundary to the left of `~@x`+and to the right of `@/x~` respectively.++```svml+@pause+<empty/>+@/pause+```++The start of `pause` attaches to the start cut point of the empty Segment, and its end to that+Segment's end cut point. A Selection may lie entirely outside a Segment, and may also span any+number of Segments.++### 4.2 Closure, crossing and disconnection++The same id may appear in sequence several times, compiling into one disconnected Selection+holding several independent anchor pairs:++```svml+@beat one @/beat ... @beat three @/beat+```++Different ids may cross freely; XML-style nesting is not required:++```svml+@a one @b two @/a three @/b+```++The specification requires the parser to manage open state per id rather than with a single+global stack. The following MUST fail:++- an unclosed marker, an orphan close, or mismatched open/close ids;+- re-opening an id that has not yet been closed;+- a Selection marker cutting into a v1 speech token;+- relying on a consumer default span to complete a missing endpoint.++Multiple occurrences of the same id keep source order and stable occurrence identity. Different+SelectionSets, and different occurrences of the same set, may overlap in physical time.++### 4.3 Optional temporal boundaries++After Slot binding, Dual Text speech projection and NFC normalization, v1 uses the deterministic,+normatively defined `speech-tokenizer-v1`:++- East Asian ideographs and kana form single-character tokens;+- other supported script/digit characters form maximal contiguous runs;+- `'` or `’` is kept only when it sits between two run characters;+- whitespace, punctuation, emoji and other separator characters produce no lexical token.++Punctuation therefore cannot be timed on its own, and a Selection/Moment cannot cut into a+single token. The v1 compiler tokenizes after removing the zero-width markers, so if grapheme,+syllable or phoneme boundaries are ever needed, the same Selection/Moment types can be reused in+a new timing profile / Script Surface version; v1 should not introduce new body symbols for a+precision that does not yet exist.++If a Script has `N` Segments, the `k`-th Segment has `mₖ` speech tokens, and `M = Σmₖ`, the+Semantic Anchor Index has exactly:++```text+Σ(2mₖ + 2) = 2M + 2N+```++stable identities. The local order inside each Segment is:++```text+segment[k].start+token[k,1].start+token[k,1].end+...+token[k,mₖ].start+token[k,mₖ].end+segment[k].end+```++The Program start and end belong to the ProgramBasis and do not additionally enter the Semantic+Anchor Index. An empty Segment still has an independent start/end even when the two ultimately+coincide; any two distinct identities MUST NOT be merged even if they end up on the same frame.++The Locator MUST commit a total mapping covering all `2M + 2N` identities:++```text+SemanticAnchorIdentity → ProgramPoint(ProgramSpace)+```++A marker's left/right affinity is resolved to exactly one anchor at Script parse time. Token cut+points and Segment cut points are entirely equal here: a left-affine marker at the head of a+Segment takes that Segment's own start cut point and never reaches back to the word end of the+previous Segment. Downstream receives anchor identities and no longer performs index arithmetic+of its own.++Location is total: every token of every Segment carries a window, whether it was measured,+inferred from adjacent characters, or interpolated because the transcript never touched it.+Reversed windows, windows outside their owning Segment, and windows overlapping their neighbours+are all reported exactly as measured; that is a fact about the recording, and interpreting it+belongs to whoever projects it onto a timeline. Location fails only when the Script, the audio+and the transcript are not the same set of three things, never because of a single timestamp.++Every point MUST exist. A consumer MUST NOT invent points, move points, or borrow points from an+adjacent occurrence. Inside each Segment the order MUST be non-decreasing:++```text+segment.start ≤ token₁.start ≤ token₁.end ≤ ... ≤ segment.end+```++Segments `A` and `B` that are adjacent in source MUST additionally preserve:++```text+A.start ≤ B.start+A.end ≤ B.end+```++This permits hard cuts, overlaps and gaps, while forbidding a Locator from silently ordering an+entire later-written Segment before an earlier-written one:++```text+hard cut A.end == B.start+overlap B.start < A.end+gap B.start > A.end+```++If genuine reordering or parallel speech is ever needed, an explicit non-linear narrative model+should be published; v1 does not let an ordinary Range reverse or vanish under a different+Locator.++The same Selection yields preview or final-cut intervals on the `CompleteSemanticMap` produced by+different fulfillments. The Map uses the same identities. Script itself contains no seconds, frame+numbers or sample points. Script Surface is not bound to a frame rate, sample rate or renderer.+Once a backend has chosen a physical clock it MUST quantize exactly once and let every consumer+reuse the same integer boundaries; a change of backend clock does not change this language surface.++Alignment, structural endpoints, projection or frame quantization may make some occurrence end up+as a zero-length or reversed interval. An implementation MUST produce an explicit diagnostic and+MUST NOT silently drop it, move Selection endpoints, borrow an adjacent occurrence, or complete+the range on the author's behalf.++## 5. Moment++A Moment is a complete point declaration, not a Selection with its close omitted:++```svml+@id!+~@id!+```++`!` explicitly marks the type of this name as Moment. It neither needs nor allows a close:++| Form | Affinity | Typical meaning |+|---|---|---|+| `@id!` | Right | Word start on the right or structural endpoint on the right |+| `~@id!` | Left | Word end on the left or structural endpoint on the left |++The default right affinity covers the frequent "starts together with some word" case:++```svml+I just @pop! laughed my ass out.+```++`pop` resolves to the onset of `laughed`. Explicit left affinity is written as:++```svml+I laughed ~@pop! and left.+```++`pop` resolves to the release of `laughed`. When it sits between two Segments, the left candidate+is the previous Segment's `end` and the right candidate is the following Segment's `start`; the+two may be the same point, or different points because of overlap or gap.++Normative rules:++- `@id!` / `~@id!` with the same id may repeat and compile in source order into one Moment; the+ public value of each occurrence is a single resolved `anchorId`.+- Selection and Moment share the temporal name namespace. One id MUST NOT declare both types;+ `@x! ... @/x` MUST fail with a type conflict.+- A lone `@x` is always an unclosed Selection open and MUST be an error; the parser MUST NOT+ guess it to be a Moment just because it found no `@/x`.+- `@id!~` is a redundant and illegal right-affine form; right affinity is written only in the+ canonical form `@id!`.+- The syntax accepts only ASCII `!`. An unescaped `@id!` (fullwidth exclamation mark) is+ malformed temporal syntax and MUST NOT degrade to body text.+- Moment and Selection markers may appear in the same positions, including between Segments and+ on the speech side of Dual Text, but neither may cut into a v1 speech token.+- A Moment only selects one candidate point already present in the Semantic Anchor Index; it adds+ no anchor identity, so the exact count `2M + 2N` does not change with the number of Moments.+- Moment and Selection reuse the same CompleteSemanticMap and the same one-time frame+ quantization; the only difference is that the final carrier is `Point[]` rather than `Range[]`.++The consumer side keeps two types that never mix:++```text+NarrativeSelection = { startAnchorId, endAnchorId }[]+NarrativeMoment = { anchorId }[]+```++The recommended explicit usage relationships are:++```svml+during="phrase" <!-- accepts a SelectionSet only -->+at="pop" <!-- accepts a MomentSet only -->+at="phrase.start" <!-- start-point projection of each range of a SelectionSet -->+at="phrase.end" <!-- end-point projection of each range of a SelectionSet -->+```++`at="phrase"` MUST NOT default to guessing start, and `during="pop"` MUST also be a type error. A+consumer that needs both a window and a trigger point MUST use two fields/ports rather than build+a polymorphic `Range | Point | mixed[]` TemporalRef. Whether a port needs `one` or `each` belongs+to the consumer's cardinality contract and does not change Script's single/multiple occurrence+syntax.++## 6. Slot++Current implementation status: `parseScript` already implements the parse-first, literal-only+binding contract below, but the official `<script>` Author Surface does not yet expose a bindings+input. An unbound Slot currently fails in `main.svml` with `SCRIPT_SLOT_UNBOUND`; public usage+examples MUST NOT claim that Slot is directly usable before the Surface completes the binding edge.++A Slot is a first-class AST atom recognized by the parser:++```svml+${product}+<${product} | ${product_pronunciation}>+```++A Slot id after NFC MUST consist of 1–64 characters: the first character is a Unicode Letter or+`_`, and the remaining characters may be Unicode Letter, Mark, Decimal Number, `_` or `-`. A bound+value is single-line Unicode plain text and MUST NOT contain CR/LF or control characters.++Key safety rules:++- Parse the Script first, then bind Slots; string substitution before parsing is forbidden.+- A bound value always enters an already existing atom as literal text and MUST NOT inject a+ Segment, Role Cue, Dual Text, Selection, Moment, Slot, comment or escape sequence.+- An unbound Slot may remain in the structured editing IR, but anything that produces the three+ texts, computes tokens or compiles a timeline MUST fail closed.+- An SVML v1 writer emits only `${variable}`; an unescaped `[variable]` is just ordinary body text.++## 7. Lexical reservation, escaping and canonical formatting++The source uniformly converts CRLF/CR to LF and applies Unicode NFC. Unescaped `<`, `@` and `${`+in the source language are reserved syntax starts. Malformed reserved syntax MUST be an error and+MUST NOT degrade to spoken text.++Body escapes:++```svml+\@openai+\<not-a-role>+\${literal}+\\+```++Inside Dual Text there are additionally:++```svml+\|+\>+```++An unknown backslash escape MUST be an error. Parse priority is fixed as:++1. comments, temporal markers and named Segment opens in Script body state;+2. the current Segment's close in Segment body state;+3. an inline `<display | speech>` containing one unescaped separating `|` in a Segment body;+4. a bare `<Role>` in a Segment body satisfying the Role label contract;+5. any other angle-bracket construct is an error.++Segment names and temporal names use independent namespaces; Selection and Moment share the+temporal name namespace. All three kinds of id satisfy:++```text+[a-z][a-z0-9_-]{0,63}+```++Source indentation, newlines and runs of whitespace are all authoring layout: they take no part+in recognizing a Segment, a Role Cue or a turn, and they are not caption line-break or pause+instructions. The compiled projections preserve the necessary separation at atom boundaries and+normalize layout whitespace; caption cue segmentation and hard line breaks are decided by the+outer Caption Program.++Structural tags and comments do not depend on occupying a line of their own to be parsed. The+canonical formatter puts each structural tag and each comment on its own line, indents Segments+by two spaces and spoken content inside a Segment by four spaces, and leaves one blank line+between Segments. The Narrative IR obtained by re-parsing before and after formatting MUST have+identical semantic content; the only things allowed to change are the source range and the source+hash.++Comments use `<!-- ... -->`. They may span lines but MUST NOT nest, and MUST NOT be written inside+Dual Text, a Slot, a temporal marker, a Role Cue or a structural tag. A comment may appear wherever+layout whitespace is allowed between atoms and is treated as layout whitespace; the canonical+formatter gives it its own line. A comment enters the semantic content of no projection, token,+Selection, Moment or hash; a separate source hash may be computed when a reproducible source+identity is needed.++## 8. Narrative IR and the consumer contract++The parse result preserves at least:++- Segment order, ids and independent start/end identities;+- each Segment's ordered spoken turns, together with each turn's stable identity, optional Role+ Cue, token range and source range;+- plain / Dual Text / Slot atoms and their source ranges;+- Caption display Atoms, their internal ordered display Words, and the independent explicit+ mapping from an Atom to one or more speech tokens;+- one or more ordered occurrences per Selection, and each occurrence's resolved+ `startAnchorId` / `endAnchorId`;+- one or more ordered occurrences per Moment, and each occurrence's resolved `anchorId`;+- the Parser/Source Map separately preserves affinity and token/source ranges; public values do+ not carry them;+- the complete ordered `CaptionDisplaySequence`, an independent `CaptionCorrespondence`, and a+ `CaptionDisplayWordSubset` for every explicit Selection. Captions need not, and MUST NOT,+ reverse-engineer word indices from public Selections.++An outer Program's `role="label"` selector may project its own word subset out of the full word+set above; several Turns with the same label are several ordered, mutually non-adjacent hits. It+is an explicit query internal to the Caption author surface, not an implicit caption behaviour of+Role Cue, and it establishes no speaker entity.++SelectionSet/MomentSet are consumer boundaries, not sub-objects of a Segment. The typical external+relationships are:++```text+Script ──compile──> Narrative IR ──project──> dialogue / speech+ ├──resolve──> NarrativeSelection[] / NarrativeMoment[]+ └──project──> CaptionDisplaySequence+ + CaptionCorrespondence+ + CaptionDisplayWordSubset[]++NarrativeSelection A ──during──> consumer.port_1+NarrativeMoment P ──at──────> consumer.port_2+CaptionDisplayWordSubset C ──words──> caption.Program+```++One Ranking, B-roll or other node may have several dynamic ports, each accepting different+Selections/Moments; the same set may also be reused by several consumers. A future Graph syntax+may write these typed edges as `during=` / `at=`, but they MUST reference resolved names or+endpoint projections and MUST NOT accept vague natural-language locators.++Caption multi-style, region, cue segmentation, annotation, mute and layout all belong to the+Caption Program. If a Caption consumer requires mutually exclusive token ownership, an overlap+MUST be a compile error for that consumer; this is not Script forbidding Selections to overlap.+If Caption ever supports overlay, only the Caption Program is extended, not the body syntax.++The current Caption Program uses one default Style covering every visible word, then applies whole+Style replacements from Roles or explicit Selections in source order, with the last matching rule+winning. A Turn without a Role automatically keeps the default Style; modifying one local interval+does not require the author to write its complement. The complete rules are in+[`caption-program.md`](./caption-program.md).++## 9. What v1 explicitly does not express in Script++The following capabilities are not a missing seventh inline marker:++| Requirement | v1 owner |+|---|---|+| Absolute seconds, frame numbers, sample points, arbitrary sub-frame positions | Runtime/Program outside Script |+| Phoneme- or grapheme-level cut points inside a token, punctuation-specific timing | A later timing profile or a new version |+| Preview duration of an empty Segment | Media, a generator or an explicit Program |+| Simultaneous overlapping speech | Multi-track media/generation Program; the Base Script remains a sequential semantic axis |+| Laughter, coughing, ambience, SFX, beeps | Audio/generation/SFX Program |+| Pure display text with no speech timing basis | Text, Deck or Caption Program |+| Caption styling, manual line breaks, motion, on-screen action | The corresponding Program referencing a Selection |+| Tone, emotion, timbre, stress, rate, SSML | Speech/Generation Program |+| Consumers, nodes, ports, DAG wiring | SVML regions outside `<script>` |++These boundaries keep Script a "script you can read directly", while not preventing full SVML from+ultimately compiling a deterministic DAG and timeline.++## 10. Completeness and the extension test++Classify a new requirement in the following order:++1. The display text differs from the actual pronunciation: Dual Text.+2. The speaker prefix of the dialogue export differs: Role Cue.+3. The semantic time range differs: Selection.+4. The semantic instant differs: Moment.+5. The sequential media/spoken block differs: Segment.+6. The runtime text input differs: Slot.+7. The caption, picture, audio, generation or consumption behaviour differs: a Program outside+ Script.++As long as a requirement falls into one of these seven, no new inline delimiter may be invented.+If none of the seven can express it losslessly, first prove that it is script semantics rather+than a Program, then handle it as a new version proposal; an existing parser MUST NOT be made to+"support it along the way".++## 11. Implementation acceptance++An implementation may declare Script Surface v1 support only when it satisfies all of the+following evidence at once:++1. every positive example, negative example, projection and source-map golden fixture in this+ document;+2. parser, formatter, Narrative IR and the three projections depend on no provider and no+ renderer;+3. SelectionSet supports closure, crossing, disconnected occurrences and left/right affinity;+4. MomentSet supports `@id!` / `~@id!`, single/multiple occurrences and the `at` type gate;+5. Dual Text keeps one auditable source map across speech, caption and temporal mapping;+6. Slot uses parse-first, literal-only binding and cannot inject syntax;+7. unknown versions, unknown reserved syntax, mixed temporal types and partial dual atoms all+ fail closed.+8. the canonical serialization, digest, complete Map and adjacent-Segment double monotonicity+ constraint for the `2M + 2N` identities all have golden fixtures; hard cut, overlap, gap,+ empty Segment and coincident endpoints are all covered.diff --git a/spec/spatial-layout.md b/docs/guide/spec/spatial-layout.mdsimilarity index 98%rename from spec/spatial-layout.mdrename to docs/guide/spec/spatial-layout.mdindex cced73b1..5607c0fb 100644--- a/spec/spatial-layout.md+++ b/docs/guide/spec/spatial-layout.md@@ -1,3 +1,8 @@+---+title: Shared Spatial Layout+description: executable foundational authority for shared Spatial geometry. `@narratage/spatial`.+---+# Shared Spatial LayoutStatus: executable foundational authority for shared Spatial geometry. `@narratage/spatial`@@ -381,7 +386,7 @@ Spatial provides common geometry without forcing one layout model:- 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;+- Ranking consumes one Placement Frame and owns board, slot and staging-area layout inside it;- 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.diff --git a/spec/track-authoring.md b/docs/guide/spec/track-authoring.mdsimilarity index 99%rename from spec/track-authoring.mdrename to docs/guide/spec/track-authoring.mdindex a11ed8d4..c4327116 100644--- a/spec/track-authoring.md+++ b/docs/guide/spec/track-authoring.md@@ -1,3 +1,8 @@+---+title: SVML Video Track Authoring Model+description: executable temporal authority shared by the official Track packages. The focused.+---+# SVML Video Track Authoring ModelStatus: executable temporal authority shared by the official Track packages. The focuseddiff --git a/spec/track-composition.md b/docs/guide/spec/track-composition.mdsimilarity index 98%rename from spec/track-composition.mdrename to docs/guide/spec/track-composition.mdindex b7c95c7c..cdb72bc4 100644--- a/spec/track-composition.md+++ b/docs/guide/spec/track-composition.md@@ -1,3 +1,8 @@+---+title: SVML Track and Composition+description: executable repository-internal `@1` compatibility waist; all gates in.+---+# SVML Track and CompositionStatus: executable repository-internal `@1` compatibility waist; all gates indiff --git a/spec/track-expressiveness.md b/docs/guide/spec/track-expressiveness.mdsimilarity index 98%rename from spec/track-expressiveness.mdrename to docs/guide/spec/track-expressiveness.mdindex 608c7c6b..c800b496 100644--- a/spec/track-expressiveness.md+++ b/docs/guide/spec/track-expressiveness.md@@ -1,3 +1,8 @@+---+title: SVML Track Expressiveness Gate+description: all E1–E8 gates execute; repository-internal `svml.visual-track@1` waist frozen pre-publication.+---+# SVML Track Expressiveness GateStatus: all E1–E8 gates execute; repository-internal `svml.visual-track@1` waist frozen pre-publication.diff --git a/spec/typography-track.md b/docs/guide/spec/typography-track.mdsimilarity index 99%rename from spec/typography-track.mdrename to docs/guide/spec/typography-track.mdindex cae9ea42..abbf03d3 100644--- a/spec/typography-track.md+++ b/docs/guide/spec/typography-track.md@@ -1,3 +1,8 @@+---+title: Typography Track Authoring and Expressiveness+description: implemented pre-release authority for the official two-dimensional Text package. The.+---+# Typography Track Authoring and ExpressivenessStatus: implemented pre-release authority for the official two-dimensional Text package. Thediff --git a/spec/visual-ir.md b/docs/guide/spec/visual-ir.mdsimilarity index 97%rename from spec/visual-ir.mdrename to docs/guide/spec/visual-ir.mdindex 675ac121..92bb9da9 100644--- a/spec/visual-ir.md+++ b/docs/guide/spec/visual-ir.md@@ -1,3 +1,8 @@+---+title: SVML Visual IR+description: implemented repository-internal `@1` compatibility waist; not yet published as an npm ABI.+---+# SVML Visual IRStatus: implemented repository-internal `@1` compatibility waist; not yet published as an npm ABI.diff --git a/docs/zh/guide/spec/audio-track.md b/docs/zh/guide/spec/audio-track.mdnew file mode 100644index 00000000..a03901a3--- /dev/null+++ b/docs/zh/guide/spec/audio-track.md@@ -0,0 +1,234 @@+---+title: SVML Audio Track 作者面+description: 通用官方 Audio Track 包的已实现预发布合同,含自描述作者 Surface 与精确采样域 lowering。+---++# SVML Audio Track 作者面++状态:通用官方 Audio Track 包的已实现预发布合同,包含它的自描述作者 Surface、精确的采样域 lowering,以及+本地 / 远端执行见证。它还不是冻结的公开 ABI。++## 目的++`@narratage/audio-track` 让作者把已经选定并归一化的音频素材放入 ProgramSpace。音乐、音效、额外口播和源+音频都是普通的同级项。这个包不拥有任何有特权的基础泳道,Composition 通过既有的+[`AudioTrack`](./track-composition.md) 终端合同来混合它的结果。++这是一个视频领域的作者包,不是 Core 原语、Runtime 服务或 Provider。分工如下:++```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 看到的是固定的图输入和一个输出 Record。它不知道 clip、bus、音乐、语音、循环、淡变或混音。++## 1. 输入的事实++每个音频条目都通过显式的图边获得素材。第一个实现应当消费来自 `@narratage/media` 的 `SynchronizedMedia`,+并要求它归一化后的音频成员:++- 48 kHz;+- 立体声;+- 有符号 16 位 PCM WAV;+- 精确的采样帧数;+- 保留原始电平。++仅仅含有 AAC 的 MP4 不是音频条目。作者图必须显式地检视容器、选择一条音频流并做归一化。同理,一个生成出来+的语音文件不会仅因为里面有人声就变成 `SpeechAudioBasis`。++Audio Track 的 lowerer 可以从归一化后的采样帧数推导终端 Artifact 的时长。它不得把源身份、Narrative 摘要、+provider 名称或其他血缘信息拷贝进 clip。这些关系仍然由图边和 Derivation 承载。++不要仅仅为了缩短一条边就引入新的公开 `AudioMaterial` Type。如果将来确有多个互不相关的包需要一个一等的+规范音频值,那个聚焦的 intrinsic Type 应当放在 `@narratage/media`;它仍然不属于 Core,也不属于某个大杂烩+式的 contracts 包。++## 2. 作者 Program++这个包拥有一个任意长度的独立条目集合。在概念上每个条目具有:++```ts+type AudioItemProgram = {+ readonly id: string;+ readonly source: SynchronizedMediaInput;+ readonly temporal: TemporalBinding;+ readonly trim?: AudioSourceTrim;+ readonly occupancy: AudioOccupancy;+ readonly mix: AudioItemMix;+};+```++这些都是包级别的关注点。它们不是 Core Operation 或终端 `AudioTrack` 合同上的新字段。++示意性的作者 Surface 可以保持紧凑:++```xml+<audio:Track id="mix" space={speech.space}>+ <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>+```++这种写法只是示意,不是冻结的 Surface。`during`、`at` 和 `for` 必须 lower 到共享的点表达式与窗口投影代数;+它们不能创建第二套时间引擎。++## 3. 时间放置++音频使用与 [`track-authoring.md`](./track-authoring.md) 相同的规则:++1. 定位 Selection、Moment 或 Program 点;+2. 展开 `one` 或 `each` occurrence;+3. 投影出一个有方向的候选窗口;+4. 与 ProgramSpace 求交并校验;+5. 应用音频的源 trim 与 occupancy;+6. 把目标放置与源采样一起 lower 到精确的 48 kHz 采样域。++音频条目相互独立。重叠的投影窗口会混合;它们绝不会按书写顺序被裁剪、被自动拼接、被去重,也不会被当成互斥的+备选方案。多个 Audio Track 值的行为,与一个 Audio Track 里多个重叠条目完全相同。++ProgramSpace 的帧边界由媒体管线已经拥有的那一条确定性规则转换为 48 kHz 采样边界。作者包不得再实现另一条+秒到采样的取整路径。++## 4. 源 trim++源 trim 定义 occupancy 之前的有效固有区间。它是精确归一化采样域内的一个显式起点和可选终点。面向作者的秒或+帧只被量化一次到采样边界。++lowerer 拒绝:++- 负值或越出源范围的边界;+- 不大于起点的终点;+- 空的有效区间;+- 不可用的音频成员;+- 对源时长的第二种包内私有解释。++源 trim 不是目标时间。移动目标窗口绝不会悄悄改变作者声明的是哪一段源区域,除非所选的 occupancy 策略显式地+对它做了对齐或重定时。++## 5. 音频 occupancy++音频有它自己诚实的 occupancy 词汇。它不得复用视觉领域那种“把一个采样永远保持住”的虚构。++```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";+ };+```++法则如下:++| 策略 | 有效源短于窗口 | 有效源长于窗口 |+|---|---|---|+| `once/start` | 在开头播放,随后静音 | 播放源头部并在窗口结束处截断 |+| `once/end` | 先静音,然后播放到结尾 | 播放源尾部并在窗口结束处结束 |+| `loop/start` | 从源头部相位开始重复 | 播放源头部并截断 |+| `loop/end` | 选择相位使源尾部与窗口结束对齐 | 播放源尾部 |+| `stretch` | 放慢以铺满整个窗口 | 加快以铺满整个窗口 |++`once` 取代了旧的含混的 `native` / `finish` 行为。尾部对齐不是倒放。`loop/end` 改变的是循环相位,它不会反转+采样。`stretch` 保持音高,必须停留在作者声明的速率界限内,并且宁可失败也不会悄悄用更快的速率再截断。旧的+`fit_base` 规则——最多加速 1.1 倍然后把剩下的悄悄切掉——被废弃。++显式的静音由该区间上不存在 clip 来表示。当被填充的静音字节本身有意义时,给文件补静音是一次独立的媒体变换。++## 6. 电平与淡变++第一版作者合同只需要三个正交控制:++- 非负的线性 `gain`;+- 在可听的已渲染区间上生效的 `fadeIn`;+- 在可听的已渲染区间上生效的 `fadeOut`。++零增益就是显式的静音。UI 或 recipe 可以暴露分贝,但换算到终端线性增益是确定性的,并且由包拥有。淡变时长+必须非负,不能超过可听区间,也不能偷偷扩张目标窗口。++不存在任何隐式的响度归一化、限幅器、压缩器、sidechain 闪避、交叉淡变或自动铺底音乐行为。这些都是合理的+未来音频处理或混音 Program,但它们必须消费显式输入,并让自己的行为对作者可见。Runtime 或 Provider 不得把+它们当作环境偏好加进来。++原来的终端 `bus: speech | music | sfx | source` 标签已被移除。它对渲染没有任何影响,因此也不承载任何诚实的+含义。将来的混音路由合同必须有明确的消费者和图行为;仅仅把一个 clip 命名为 `music` 不能导致闪避。++## 7. Lowering 与执行++确定性的作者包把每个实现出来的条目 lower 成一个普通的终端 `AudioClip`:++- 来自时间投影的精确目标 `{ startSample, endSampleExclusive }`;+- 来自归一化输入的规范 WAV Artifact;+- 来自 trim / occupancy 的精确源采样区间、循环相位和播放速率;+- 来自呈现的保持音高意图、线性增益和精确的采样级淡变。++Composition 会针对显式连接的 ProgramSpace 校验 Audio Track。随后媒体管线把所有同级 Audio Track 编译成一份+内容寻址的 `AudioProgramPlan`。本地 FFmpeg、Lambda 或另一个 Provider 执行的是同一份 plan;Provider 的部署+位置不能重新解释这次混音。++即使包内拥有很多 clip,它也只发出一个 `AudioTrack`。那是一个作者组件的输出,不是有特权的泳道。天然同时拥有+一次视觉命中和一次声音命中的包,可以从一个 Fragment 发出同级的 `VisualTrack` 和 `AudioTrack` 输出,而 Film+通过普通的边接收两者。++## 8. 旧系统迁移审计++保留:++- 任意音频输入;+- Program 全长、Selection、Moment 和绝对放置;+- 重叠的音乐 / 音效 / 人声贡献;+- 逐条目的增益与淡变;+- 单次播放、循环,以及有界的保持音高拉伸;+- 显式的源 trim 和起点 / 终点对齐。++废弃:++- 把动态编号端口当作保存下来的作者事实;+- 音频上的 `z_index`;+- 藏在节点执行器里的隐式全长时间;+- 按配置行优先级做的裁剪;+- `fit_base` 及其“先加速再静默截断”的行为;+- 音频的 `fill: freeze`;+- 自动提取视频里恰好含有的任何音频;+- 无实际作用的 bus 标签和隐藏的母带处理。++## 9. 实现与验收++共享的 Temporal 包和冻结前的终端 Audio 候选实现现已完成,且没有引入 Core 分支、Provider 家族分支或有特权的+Film 泳道:++1. **已实现:** 加入 `@narratage/audio-track` 作者包和自描述 Surface;+2. **已实现:** 消费显式归一化的 `SynchronizedMedia` 输入;+3. **已实现:** 采样级精确的 trim 和全部 occupancy 法则;+4. **已实现:** lower 到同级的终端 `AudioTrack`;+5. **已实现:** 针对任意条目数量以及 Selection / Moment 的 `one` / `each` 的图测试;+6. **已实现:** 针对更短 / 相等 / 更长的源、两种对齐、循环、拉伸界限和淡变的采样级测试;+7. **已实现:** 两个重叠条目与两个同级 Audio Track 产出相同的计划混音事实;+8. **已实现:** 本地 FFmpeg 与远端 Lambda Provider 收到完全相同的内容寻址 `AudioProgramPlan`;真实 FFmpeg+ 见证还会逐采样检查精确的循环相位。++如果加入这个包需要 Core 分支、Film 音频家族、新队列、SVML 中出现 Provider 名称或一条隐藏的 Base 音频规则,+那么这次迁移就是不完整的。diff --git a/docs/zh/guide/spec/author-surface-binding.md b/docs/zh/guide/spec/author-surface-binding.mdnew file mode 100644index 00000000..888c9a9a--- /dev/null+++ b/docs/zh/guide/spec/author-surface-binding.md@@ -0,0 +1,144 @@+---+title: Author Surface Binding+description: 已实现的编译器合同,覆盖受信任的包自有 Surface;第三方隔离尚未实现。+---++# Author Surface Binding++状态:已实现的编译器合同,覆盖受信任的包自有 Surface;第三方隔离尚未实现。++## 1. 目的++通用的 Markup Frontend 持有元素语法。包自有的 Surface 持有某个被 import 的标签*具体是什么意思*。SVS+只持有自己的样式表语法,并产出通用的不可变 Recipe record。Markup、SVS 和 Core 都不持有 Caption、Media、+Film 或其他任何包的属性词汇。++两者之间的桥是编译期引用检查:像 Caption 这样的 Surface 必须能够读取一个被显式引用的公开 Recipe,并在+Core 图构建之前把它下降为名义的 `CaptionProgram`。++本文定义这座桥,同时不引入全局 Recipe 注册表,也不引入 Runtime 步骤。++## 2. 有序的编译边界++一个 Source Closure 按以下顺序编译:++```text+recursive imported SourceUnits+ -> admitted public Records and symbolic component exports+ -> current document generic syntax+ -> package-owned Surface compilation+ -> typed authored Records + AuthorComponents + locked GraphFragments+ -> parser-independent Author linking+ -> Core CompiledGraph+```++因此,被 import 的 `.svs` SourceUnit 一定先于消费它的 `.svml` SourceUnit 完成编译。消费方的 Surface+拿到的是结构化的元素,以及一个只针对该元素中显式书写的引用的 resolver。++## 3. 引用解析结果++一个已解析的 Surface 引用包含:++```text+path source spelling used by the element+ref hygienic AuthorValueRef+type exact nominal TypeRef+record? defensively copied TypedRecord when the public export is already an authored Record+```++组件输出没有编译期 Record,因此省略 `record`。如果某个 Surface 需要检查值本身(例如 Recipe 解码器),+它必须要求一份作者 Record,并在引用无法解析、Type 不对或此时还没有值时,于 `check` 阶段失败。++只有被 import 的 SourceUnit 的公开 record export 会被暴露出来。私有的子 record 不属于 resolver 的范围。+每一份返回的 Record 都是防御性的规范化副本,因此 Surface 代码无法改写已经编译完成的子 SourceUnit 或此前+的声明。++## 4. 包的归属++对于这段源码:++```svml+<caption-fine:Style recipe={studio.caption.dialogue}/>+```++各方职责如下:++```text+@narratage/svs+ parses studio.svs+ produces generic @narratage/svs#Recipe++@narratage/markup+ parses the element and the whole-value reference+ resolves only the public imported binding++@narratage/caption Surface+ requires @narratage/svs#Recipe+ validates Caption-owned properties+ emits nominal @narratage/caption#CaptionTrackProgram+ emits the AuthorComponent and locked GraphFragment++Author compiler+ resolves symbolic component dependencies and types++Core+ sees only typed Records, LogicalOutputs, Candidates and Operations+```++不存在一张通用属性表。另一个包完全可以通过另一个被显式 import 的 Surface 来解释同一份通用 Recipe,并+产出不同的名义 Program。Surface 永远不由 Recipe 的形状来选中;是作者写下带命名空间的组件时选中它的。++## 5. Surface 输出法则++一个 Surface 只能产出:++1. 精确 Type 出现在其锁定 Manifest `outputs` allowlist 中的作者 Record;+2. Fragment 摘要由该次解码结果贡献的 AuthorComponent;+3. 不可变的 GraphFragment;+4. 非语义的 source-map 事实。++Frontend 用源码与 Frontend Closure 身份为作者 Record 的来源封印,校验其结构 Type,并在链接前让它通过+Host 的准入闸门。Surface 不能注入未声明 Type 的 Record。++由 Recipe 推导出的带类型 Program,应当包含其所属包做语义校验所需的任何源码摘要。它的作者来源已经绑定了+Surface 实现摘要和递归编译得到的 Source Closure。别名写法与文件系统位置的变化可能改变源码身份,但不会+改变带类型的 Program 值,也不会改变最终 Graph 的含义。++## 6. 前向引用法则++两种情况被有意区别对待:++- 图依赖可以保持为符号化的 `component.output` 引用,在整份文档收集完毕之后再解析,因此普通组件的前向+ 引用依然有效。+- 编译期的值检查要求 Record 已经完成作者编译。被 import 的源码总是可用的;而同一文档内的值定义,必须+ 出现在检查它的 Surface 之前。++这不是某种 parser 模式或 Runtime 模式,而是取决于编译此刻是否需要那个值,还是稍后只需要一条带类型的图边。++## 7. 它不是什么++Surface Binding 不是:++- Core 的 Type 注册表;+- 隐式转换搜索;+- Runtime Producer 或付费 Operation;+- Provider 能力;+- 全局 SVS 解码器;+- 读取凭据、文件、网络或 Store 的许可。++当前的 Host 只执行显式注册的受信任 Surface 实现。要让任意社区 Surface 代码可以执行,必须先具备按字节锁定+的代码、权限强制和隔离。++## 8. 可执行的证明++与视频无关的 `example.recipe-card` fixture 证明了这条边界:++1. SVS 产出通用 Recipe;+2. Card Surface 只读取自己显式写下的公开引用;+3. Card 在作者编译期校验 `fill` 与 `padding`;+4. Card 产出名义的 `CardAppearance` Record;+5. 运行时 Producer 消费的是 `CardAppearance`,不是 `SVS Recipe`;+6. 非法颜色在 BuildPlan 或任何外部操作出现之前就失败;+7. 只改源码 import 别名时,Program Record 与 Graph 身份保持不变。++视频相关的包必须使用同一套机制,而不是另开一条视频专用的编译器通路。diff --git a/docs/zh/guide/spec/caption-fine.md b/docs/zh/guide/spec/caption-fine.mdnew file mode 100644index 00000000..ab355448--- /dev/null+++ b/docs/zh/guide/spec/caption-fine.md@@ -0,0 +1,217 @@+---+title: Fine Caption Style 族+description: 已实现的预发布 Style 族,所声明的表面均有完整的浏览器证据。+---++# Fine Caption Style 族++状态:已实现的预发布 Style 族,所声明的表面均有完整的浏览器证据。++## 目的与边界++`@narratage/caption-fine` 是官方的、无字段的细粒度 Caption Style 族。这里的 “Fine” 指的是:不可变的+显示 Atom 被规划成短的语义 Cue,再经由一套确定性视觉系统渲染。它**不**表示 `important`、语义强调分类+或逐词的随机样式。++这个包消费三份已经存在的事实:++1. `CaptionProgram`,它给每个显示 Word 指派一份完整的 Style;+2. `TimedCaptionProjection`,它给每个 Cue 和每个完整 Atom 一个已证实的时间窗口;+3. `CaptionDisplaySequence`,它保留作者精确的可见文字与标点。++它输出一条普通的对等 `VisualTrack`。它绝不修改文字、绝不调用模型、绝不推断 Dual Text Atom 内部的时间,+也绝不往其他合同里塞 Caption 元数据。++| 归属 | 职责 |+|---|---|+| `@narratage/caption` | 通用 Style 外壳、Cue/字段 Plan 法则、全覆盖 Style 赋值与 Atom 时间 join |+| `@narratage/caption-fine` | Fine Recipe schema、layout、Paint、局部 motion 与 VisualTrack lowering |+| `@narratage/media` | `FontArtifactRef` 这类精确可复用的字节,绝不涉及 Fine 的排版策略 |+| `@narratage/visual-ir` | 封闭的、无代码的终端 element/style/keyframe 词汇 |+| Core | 只负责图的 demand、校验、派生和执行;不含任何 Caption 含义 |++只要现有公开合同还能表达结果,改动 Fine 的阴影、锚点、卡拉 OK 模式或 Cue 盒子,就不得修改 Caption、+Media、Composition、Visual IR 或 Core。++## 完整的正交表面++Fine 拥有一棵单字体的 Cue/Atom layout 树。它的各个维度互相独立:一份 Recipe 可以同时组合渐变字形、+当前词盒子、拖尾文字、下划线和局部 motion,而不必换一个渲染器。只有当某种外观改变了 layout 树、或者+需要 planner 字段时——例如双字体的编排式排版——才有理由新开一个包;仅仅增加 Paint 或局部 motion 不算。++### 1. Cue 规划++- `cue-min-words`+- `cue-max-words`++planner 只能在完整 Atom 之间切分。不可分割的作者 Atom 可以超过偏好的最大值;绝不会为了凑数字而把它+拆开。++### 2. 放置与布局++- 归一化的 `x`、`y`、`width`+- `anchor-x: left | center | right`+- `anchor-y: top | center | bottom`+- `align: left | center | right`+- `direction: ltr | rtl`+- `line-height`、`letter-spacing`、`word-gap`+- 绝对的 `stack-order`++Cue 只会在 Atom 之间自然换行。同一个 Atom 内的 Word 绝不会被拆到不同行。Fine 没有 `max-lines` 属性:+硬性行数限制要么丢弃作者文字,要么把浏览器测量偷偷带进确定性 lowering。Fine 绝不裁剪、绝不截断。作者+通过 Cue 词数边界、宽度和字号来控制密度。如果确实需要一条硬性布局断言,它必须是一个单独连接的组件,+其失败在图中是显式的。++### 3. 排版++- Recipe:`size`+- `text-transform: none | uppercase | lowercase`++text transform 只是终端呈现。它绝不改变 `CaptionDisplaySequence`、planner 输入、Word/Atom 身份、语音+对应或时间。++family、weight 和 style 被刻意排除在 Recipe 之外。每个 Style 都必须从 `@narratage/fonts-open` 引入+精确的已安装字面,或用 `<media:Font>` 声明自定义/品牌字节。`font=` 接受一个精确字面加上有序的、+Style 所属的 Fallback 子节点,或者一个可复用的通用 `FontStackRef`。开放字体的紧凑写法是:++```svml+<fonts:Stack id="caption-fonts" family="inter" weight="700" style="normal" emoji="color">+ <fonts:Fallback family="noto-sans-sc" weight="700" style="normal"/>+</fonts:Stack>+<caption-fine:Style id="primary" recipe={studio.caption.primary} font={caption-fonts}/>+```++字体这条边是 family、weight 和 style 的唯一真相来源。fallback 保留它自己诚实的字面元数据——例如 700+字重的拉丁主字面可以搭配 400 字重的符号 fallback。完全重复的字面会被拒绝。一个逻辑字面可以包含多个+按内容寻址的 Unicode-range 源,已安装的中日韩与 Emoji 字体就是如此。Fine 把 `FontStackRef` 展开成+同样有序的精确字面,并且只把它们放在自己的终端文本 element 上;Caption、Core 以及无关的图值保持不变。+省略 `font=` 是非法的,因此结果里不会混入任何 Runtime 或机器字体选择策略。++中日韩口播可以直接书写。纯显示的 emoji 仍然需要显式的语音对应,例如 `<🌐 | globe>`;Script 会正确地+拒绝为一个孤立符号发明口播 token。同时具有文字与 Emoji 呈现形态的字符,使用作者书写的精确 Unicode+序列(例如带 VS16 的 `☎️`);没有任何 lowerer 会为了强制上色而改写显示文字。这是时间与文字真相问题,+不是字体能力问题。++### 4. 基础字形与激活字形的 Paint++- 纯色 `fill`,或 `gradient-from`、`gradient-to`、`gradient-angle`+- `opacity`+- 一层描边:`stroke-color`、`stroke-width`+- 一层阴影:`shadow-color`、`shadow-opacity`、`shadow-x`、`shadow-y`、`shadow-blur`+- 一层有界的方向性长阴影:`long-shadow-color`、`long-shadow-opacity`、+ `long-shadow-distance`、`long-shadow-angle`+- 一层辉光:`glow-color`、`glow-opacity`、`glow-blur`+- 一层基础下划线:`underline: off | always`、`underline-color`、`underline-thickness`、+ `underline-offset`++每个激活态 Paint 名字都带 `active-` 前缀。例如 `active-gradient-from`、`active-long-shadow-distance`+和 `active-glow-blur` 描述的是激活字形,不改变基础字形。++基础 Paint 与激活 Paint 形状相同。渐变替换该层的纯色填充;它不替换激活叠加层,也不替换卡拉 OK 过渡。+投影、长阴影和辉光是互相独立的作者贡献,会被 lower 成一条确定性的 `text-shadow` 声明。长阴影的展开有+实现上的上界,因此一份 Recipe 不可能造出无限膨胀的 CSS 负载。任意多层阴影、纹理、斜面和自由挤出仍在+Fine 之外。++### 5. Cue 盒子 Paint++- 纯色 `background`+- `border-color`、`border-width`+- 水平/垂直 `padding`+- `radius`++禁止背景采样,因为那会让这条 Track 去窥视另一条 Track 的像素。++### 6. 激活通道、卡拉 OK Paint 与时间++- 激活字形状态:`karaoke: off | current | trail`+- 激活字形过渡:`karaoke-transition: step | wipe`+- 激活盒子状态:`active-box: off | current | trail`+- 激活盒子连续性:`active-box-continuity: isolated | joined`+- 激活盒子 Paint:`active-box-background`、border、padding 和 radius+- 激活盒子 motion:`active-box-enter`、`active-box-exit`、`active-box-transition-frames`+- 激活下划线状态:`active-underline: off | current | trail`,以及颜色、粗细和偏移++激活状态与装饰几何被刻意分开。`current` 只激活其实测窗口包含当前帧的那个 Atom。`trail` 让每个已激活的+Atom 一直保留到 Cue 结束。`step` 整体切换激活字形层;`wipe` 在该 Atom 的实测窗口内逐步揭示它。RTL 会+反转 wipe 方向。字形、盒子和下划线可以各自选择不同的状态策略,因此历史上保留的那种行为——拖尾文字配+仅当前的 pill——可以直接表达。++isolated 盒子为每个已激活的 Atom 各画一个盒子。joined 拖尾把有序的已激活前缀画成连续的行内片段:同一+渲染行上的 atom 共享一个背景,而每个折行的行各自获得自己的端帽。决定这些片段的是浏览器的行布局,而不是+上游元数据。Fine 绝不把实测行盒子传播到图里。++卡拉 OK 刻意是 Atom 粒度的。在普通文字里,一个 Atom 通常就是一个可见 Word。在 `<45% | forty five percent>`+中,作者书写的可见 `45%` 是一个 Atom,作为一个整体激活。在多词显示 Atom 中,整个作者 Atom 一起激活。+下游任何包都不会发明作者与音频证据从未提供过的内部 Word 时间戳。++### 7. 分层的局部 motion++- Cue 进入/退出:`none | fade | pop | scale | spring | bounce | elastic | stamp | tilt |+ zoom-blur | flip-x | flip-y | spin | squash | stretch | slide-left | slide-right | slide-up |+ slide-down | blur-in | wipe-left | wipe-right | wipe-up | wipe-down`+- Atom 进入与退出:同一套一次性词汇,时长独立+- Atom 揭示:`all | on-start | typewriter`+- 激活响应与激活盒子的进入/退出:同一套一次性词汇+- 连续的局部循环:`none | shake | wobble | glow-pulse | breathe | float | pulse | flicker`,+ 作用于 Cue 或激活 Atom++扁平的 Recipe 名字是 `cue-enter`、`cue-exit` 及其各自独立的 `*-frames`;`atom-enter`、+`atom-enter-frames`、`atom-exit`、`atom-exit-frames`、`atom-reveal`;`active-response`、+`active-response-frames`、`active-scale`;+`slide-distance`;以及 `loop`、`loop-target`、`loop-period-frames`、`loop-intensity`。++Cue、Atom 生命周期、激活响应和循环各自拥有独立的包裹层,因此它们的 transform 是叠加组合而不是互相+覆盖。typewriter 在一个完整 Atom 内逐个揭示作者书写的显示字素;它是视觉插值,不代表字符级时间戳,+也绝不改变 Atom 边界。连续 motion 是有界的确定性帧函数,不含任何随机输入。任意路径运动和随机变化仍在+Fine 之外;它们属于通用 Typography 或独立的特效包,而不属于 Caption 的预设词汇。++## 一个渲染器,一棵 layout 树++静态输出与卡拉 OK 输出共享这套结构:++```text+placement+└── cue motion+ └── cue box+ ├── joined/isolated decoration underlay+ └── cue loop+ └── atom entry+ └── active response+ ├── base words+ └── active glyph/underline overlay+```++装饰底层只重复那份为了获得诚实的浏览器行片段所必需的、同样的透明字形几何。它不会制造出第二份文字真相。+激活叠加层复用同一份 Atom 几何。每个动画都会在 HyperFrames 看到它之前,lower 成有限的、按帧寻址的+`VisualTrack` keyframe。++## 默认值与兼容性++最初那十五个基线属性仍然是必填的,因此最小的 Recipe 也会对规划、几何、排版和可见盒子给出显式说明。+新增维度是可选的,并解析成一个完整的不可变参数对象:++- 左上锚点、LTR、normal 字体、零字距,以及四分之一 em 的词间距;+- 无描边、无阴影、无长阴影、无辉光、无下划线、无边框;+- 纯色填充,text transform 为 none;+- 激活字形、激活盒子和激活下划线均关闭;+- Cue/Atom/盒子的 motion 与循环均关闭,所有 Atom 可见;启用激活响应通道时,其 scale 默认为 1.08;+- 启用卡拉 OK 但未指定其他激活 Paint 时,激活填充默认为 `#FFD54A`,其余激活 Paint 维度继承基础 Paint。++未知属性一律拒绝。默认值属于包的实现策略,因此被其实现摘要覆盖;它们不是隐藏的 Runtime 行为。++## 已完成的证据门++完整设计是渐进交付的,而不是拆成互不兼容的版本:++1. **已解析模型与静态 lowering** —— 完整参数、锚点、布局、基础/激活 Paint、Cue 盒子与严格校验。+2. **定时 lowering** —— current/trail、step/wipe、Cue 淡入淡出、Atom 揭示和激活 scale,全部只使用已+ 证实的整 Atom 时间。+3. **可复现性证据** —— 有序的精确 Font Artifact 栈、中日韩、emoji/符号 fallback、多行折行、描边、阴影、+ 辉光以及全部四种字形卡拉 OK 模式,都有真实的浏览器/像素见证。`max-lines` 是被刻意拒绝,而不是被+ 推迟。+4. **表现力 Paint 与 motion 证据** —— 仅当前盒子与拖尾盒子、isolated 与 joined 几何、渐变、下划线、+ 长阴影、text transform、分层的一次性 motion、typewriter 揭示与确定性循环,各自都有终端 IR 见证;+ joined 几何另外还有真实折行的浏览器/像素见证。++没有任何一道门改动 Core 或公共 Caption。精确的字体选择是 Media Font Surface 与 Fine Style Surface 之间+一条显式的作者图引用,而不是沿着 Caption 流水线传播的元数据。diff --git a/docs/zh/guide/spec/caption-program.md b/docs/zh/guide/spec/caption-program.mdnew file mode 100644index 00000000..ade12de3--- /dev/null+++ b/docs/zh/guide/spec/caption-program.md@@ -0,0 +1,168 @@+---+title: Caption Program+description: 预发布的可执行合同。+---++# Caption Program++状态:预发布的可执行合同。++## 1. 范围++Caption 是一个普通的视频组件族。它把不可变的作者显示文字变成一条自包含的 `VisualTrack`。它对+Script 的措辞、发音、语音对齐、Provider 选择、Runtime 执行和 Composition 顺序都没有任何话语权。++它的两条独立图分支是:++```text+CaptionDisplaySequence + CaptionProgram ── planner ─────────── CaptionPlan+speech audio ────────────────────────────── evidence/locator ── CompleteSemanticMap++Display + Correspondence + Plan + Program + Map ── timing ─── TimedCaptionProjection+TimedCaptionProjection + Display + Program ─────── renderer ── VisualTrack+```++planner 永远拿不到时间戳。对齐永远不做 Cue 或 Style 判断。两条分支只在显式的 timing 组件处汇合。++## 2. 显示真相:Atom 与 Word++Script 输出一份 `CaptionDisplaySequence`,它带两个有序视图:++- `Atom` 是 planner 可以整体放进一个 Cue 的最小单位,也是能够承载已证实语音时间的最小显示单位;+- `Word` 是可选的 Style 所属字段的最小作用目标。++每个 Word 恰好属于一个 Atom。Atom 对 Word 的划分恰好覆盖一次并保持顺序。文字与标点始终是作者真相:+`45%`、`back-and-forth`、`damn!`、`300,000`、`don't` 和 `U.S.A.` 原样穿过这条边。官方 Script reader+以英文优先,把作者书写的空白当作正常的显示词边界;其他作者包可以发布另一套策略,只要产出同样的公开合同。++对普通文字,一个显示 Word 通常就是一个 Atom。显式的 Dual Text 永远是一个完整 Atom,即使两侧恰好含有+相同的词:++```svml+<New York City | new york city>+```++该显示序列包含一个 Atom、三个 Word:`New`、`York`、`City`。它并不声称其中任何一个显示 Word 对应任何+一个口播 token。隐藏的 Dual Text(`< | um>`)不产生任何显示 Atom。++这是刻意的信息纪律:Script 只使用作者显式给出的对应关系,绝不发明作者没有给出的对应关系。++## 3. 语音对应是一条独立的边++`CaptionCorrespondence` 把每个显示 Atom 映射到一个或多个作者书写的口播 token 身份。它与+`CaptionDisplaySequence` 相互独立;显示侧的消费者不必携带自己用不上的语音血缘。++对普通文字,每个 Atom 映射到该显示表面在结构上拥有的那些口播 token。对 Dual Text,整个显示 Atom 映射+到整段右侧口播区间。不存在公开的“显示 Word 到口播 Word”的映射,也不存在猜出来的内部时间。++Script 还会为显式的 Selection 输出 `CaptionDisplayWordSubset` 值。Role 选择器是同一份显示序列之上的+作者面语法糖。子集是有序的,可以选中零个或多个完整 Atom;只选中一个多词 Atom 的一部分属于作者错误。+这些值不是时间性的 `NarrativeSelection` 值,也不会引入第二套 `when` 语言。++## 4. 完整的 Style 意图++一个 `CaptionStyle` 是一份完整的作者声明,包含:++- 通用的规划要求:偏好的 Cue 词数上下界,以及零个或多个带类型的 per-Word 字段声明;+- 一个渲染族身份,以及该族经 Recipe 解析后的完整参数。++公共 Caption 包只拥有 Cue 与字段的数据形状,不拥有字体、盒子、颜色、动画,也不定义字段 id 的含义。+一个 Style 族可以不声明任何字段。布尔、枚举和有界数值字段对其他族同样可用;一个 Word 可以携带零个、+一个或多个互相独立的字段。++SVS 存放具名的 Recipe 数据。Style 包解释这份 Recipe 并输出一份完整的 Style。应用另一个 Style 会整体+替换原 Style;规划与渲染的零散片段绝不会被隐式合并。++## 5. 全覆盖赋值与有序替换++每个 `CaptionProgram` 都有一个显式的 default Style,覆盖完整的显示全集。作者无需伪造 `@whole`+Selection,也不必写补集。++```xml+<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>+```++Use 按源码顺序生效,最后一个命中的整体 Style 替换获胜。Program 存的是显示序列身份和有序的 Word id+区段,而不是复制出来的文字。一个区段绝不跨越 Segment 或 Turn 边界。所有区段互不相交,对显示 Word 恰好+划分一次,且任何区段都不得把一个 Atom 拆开。++`Mute` 消费的是与 `Use` 相同的、Caption 专有的整 Atom 词子集。多个 `Mute` 子节点构成一个有序并集,+因此一个 Program 可以隐藏任意多段互不相连的作者区间。`Mute` 是规划之后的可见性意图:被 mute 的 Atom+仍然留在不可变的显示全集和 `CaptionPlan` 中,绝不会作为指令进入 planner 提示词,也绝不触发 Cue 重新+规划。公共的 timing join 会把被 mute 的 Atom 从已经规划好的定时 Cue 中移除,同时保留该 Cue 的身份和+原有时间跨度;一个没有任何可见 Atom 的 Cue 不出现在定时视觉投影中。因此各 Style 族的渲染器共享这一+行为,不必各自发明自己的遮罩语义。公共包还导出同一个幂等操作,供直接调用渲染器时做防御性处理。++这刻意不是一个通用的时间遮罩。Script 已经把作者的 Selection 投影成了精确的显示词子集,因此 Caption+无需把词换算成时间、再从重叠窗口里把词猜回来。只选中多词 Dual Text Atom 一部分的 `Mute`,会被与+Style 应用相同的不可分割规则拒绝。++`display={story.caption}` 是一条真实的图边。planner、timing 和渲染只在自己需要时,各自声明指向同一个+值的边。++## 6. planner 合同++planner 接收已解析的区段。对每个区段,它只能:++1. 把连续的完整 Atom 编组成有序的 Cue;+2. 给每个 Cue 内的 Word 赋予已声明的字段。++Cue 必须对每个区段恰好划分一次。偏好的 Cue 最小/最大词数只是对 planner 的引导,不能让作者文字失效;+单个多词 Atom 可以超过最大值,并且必须保持完整。响应中不包含任何替换文字、发音、时间戳或 Style。++Gemini planner 只发送一次可读形式:++```json+{+ "atoms": [+ ["new"],+ ["york"],+ ["city", "is", "beautiful"]+ ]+}+```++外层数组是 Cue 的可切分全集。每个内层数组是一个不可分割的 Atom。其中的字符串是不可变的字段作用目标。+稳定 id 留在包内部。响应通过 `atom_count` 消费 Atom;字段在其 Cue 内使用从 1 开始的 `atom_number` 和+`word_number`。++## 7. 时间投影++`CompleteSemanticMap` 仍然是唯一的全局语音时间真相。timing 组件通过 `CaptionCorrespondence` 解析出每个+Atom 的显式口播 token 区间,并给整个 Atom 一个实测窗口。一个 Cue 从它的第一个 Atom 开始,到它的最后一个+Atom 结束。++因此 `TimedCaptionProjection` 只包含定时的 Cue 和定时的 Atom。它不包含 per-display-Word 的时间戳,+没有 `estimated` 质量标签,也没有按字符比例的切分。对于多词的 Dual Text Atom,下游渲染器可以自行决定+如何排布或动画其内部 Word,但不得声称拥有编造出来的词级时间。任何内容都不会写回 SemanticMap。++## 8. 渲染与合成++每个定时 Cue 选出其解析后 Style 的完整渲染负载。一个 Style 族渲染器返回一条普通的 `VisualTrack`。在首版+合同中,一个 Program 内的所有 Style 使用同一个渲染族。++`@narratage/caption-fine` 是第一个官方族。它不声明任何字段,拥有一套正交的单字体 layout/Paint/motion+系统,包括互相独立的整 Atom 字形、下划线和 Pill 激活。其他包可以定义不同的 layout 树或依赖字段的+Paint,而无需改动 Script、Caption、Composition 或 Core。++Film 不对 Caption 做特殊识别。它把产出的对等 Track 与 Speech、B-roll、Text 以及第三方 Track 并排折叠。++## 9. 显式的非目标++Caption v1 不定义:++- Script 纠错或替代措辞;+- 推断出来的 Dual Text 词级对应;+- 说话人分离或说话人身份;+- 隐式的模型或 Provider 路由;+- 自动的缓存复用;+- 估算出来的显示词时间;+- planner 可见或由 Core 拥有的 Caption mute 语义;+- Composition 中的全局 Caption 图层;+- Core 中的字段专有语义。++Target 与 Candidate 仍然是外部的运行意图。它们不改变 Caption 数据,也不改变 planner 语义。diff --git a/docs/zh/guide/spec/core-kernel.md b/docs/zh/guide/spec/core-kernel.mdnew file mode 100644index 00000000..7dda1406--- /dev/null+++ b/docs/zh/guide/spec/core-kernel.md@@ -0,0 +1,75 @@+---+title: Narratage Core Kernel+description: 当前可执行合同:持久化 Graph、BuildRequest、Plan 与 BuildState 的 wire 格式。+---++# Narratage Core Kernel++状态:当前可执行合同。持久化的 Graph、BuildRequest、Plan 与 BuildState wire 格式都是 `@1`。++Core 是与领域无关的图 Demand 编译器,以及一台经过校验的 Build 状态机。它不解析源码、不加载包、+不执行实现、不选择 Endpoint、不访问凭据、不持久化 Artifact,也不认识任何视频词汇。++## 输入++Core 只接受不可变的、已经完成链接的数据:++- 一份已解析的 module closure 与带类型的作者 Record;+- 一份完整的 `svml.graph@1`,其中包含来自 Author Graph 与 Run Graph 的 Logical Output、彼此独立的+ Candidate 和原子 Operation;+- 一份包含 Target 的 `svml.build-request@1`。++图的构造、源码解析、包解析、Fragment 展开和 Run Graph 的编写都发生在 Core 之外。Core 在推导 plan+之前先校验这些数据。++## 图中的值++1. 一个 `LogicalOutput` 是稳定的、作者可见的承诺:身份、名义 Type 和 Primary Candidate。+2. 一个 `Candidate` 是一份独立的带类型供给。它的根要么是一个不可变的 Provided Value,要么是一个原子+ Operation 的结果。它不隶属于任何 output。+3. Run 编译器逐条应用显式的 `Satisfaction`:在不可变的 realized graph 中,把对应 Candidate 设为该+ output 的 Primary Candidate。Core 不接受第二个选择来源。+4. 一个 `Target` 指名本次 Build 所需要的一个 output。+5. 一个 `Operation` 具有稳定的实例身份、已声明的带类型输入,以及恰好一个原子结果。多结果组件先产出+ 一个 Product,再接确定性的 Projection Operation。++## 编译法则++1. Core 从所有 Target 出发,沿被选中的 Candidate 和 Operation 输入反向推导 Demand。+2. 选择结果已经冻结在图中;只有可达性决定要做哪些工作。+3. 被多条边引用的同一个 Operation 实例只纳入一次。不同实例之间绝不做内容去重,即使实现、参数或输入+ Record 完全一致。+4. Provided-Value Candidate 没有输入边,遍历自然终止。Core 没有 Pin、预览、缓存或历史结果分支。+5. 一个 Candidate 必须产出使用它的那个 Logical Output 所要求的、完全一致的名义 Type。+6. 环、悬空引用、未声明端口、重复身份和不兼容 Type 都在执行之前失败。+7. 产出的 `svml.plan@1` 是有限的、确定的,并按内容绑定到已校验的 Graph 和 BuildRequest。++## 执行法则++1. Core 从冻结的 BuildPlan 发出 Command。Driver 与 Runtime 无法改变 Candidate 选择、依赖拓扑或 Target+ 的含义。+2. Record、Need、Command、Event、Receipt 和 Derivation 都是不可变的、按内容绑定的事实。+3. 一份 Derivation 绑定实现身份、输入与输出摘要、Need 请求摘要,以及被接受的 Event 摘要。+4. 一份外部 Receipt 绑定确切的 Need、请求摘要、履约实现、输出摘要和被接受的 Event。+5. 序列化的未完成 Command 不可信。Resume 会校验已接受的状态,丢弃旧 Command,并确定性地重新生成下一批+ Command。+6. 只有当每一个 Target Record 都存在时,Build 才算完成。++## 类型法则++1. Type 由 module 按名义持有,不在某个中心化的 Core union 里注册。+2. Core 对每一条被准入的 Record 校验锁定的结构 Schema。+3. Type 的持有者可以锁定一个语义 validator 摘要。一旦存在,该 Type 的每一条 Record 都需要一份 receipt,+ 绑定到确切的 Type、值摘要和 validator 实现。+4. Graph 持有依赖关系,Derivation 持有确定性血缘,Receipt 持有外部履约来源。++## 边界++`@narratage/protocol` 持有 wire 数据与身份。`@narratage/core` 持有校验、Demand 编译和状态转移。编译器+包持有源码与图的构造。Runtime 持有调度、持久化与放置。Endpoint 包履约确切的 Capability。领域包持有共享+词汇与 validator。++文件后缀、包名和 TypeScript class 都不授予 Kernel 特权。在 Core 之后发布的领域包,可以只通过 manifest、+名义 Type 和普通 Operation 参与进来,不需要重新发布 Core。++Kernel 没有特权终端输出,没有 Film 根节点,没有视频流水线方向,也没有单 Target 限制。diff --git a/docs/zh/guide/spec/deck-track.md b/docs/zh/guide/spec/deck-track.mdnew file mode 100644index 00000000..546f5187--- /dev/null+++ b/docs/zh/guide/spec/deck-track.md@@ -0,0 +1,271 @@+---+title: SVML 深度栈 Deck Track+description: 官方深度栈 Deck 迁移的已实现可执行权威,记录旧 Deck 实现的行为。+---++# SVML 深度栈 Deck Track++状态:官方深度栈 Deck 迁移的已实现可执行权威。它记录了旧 Deck 实现所使用的行为,但它不是冻结的+公开 ABI,也不定义通用的 Deck 协议。++## 1. 结论++Deck 不是 Media Item 的一种模式,也不是 Media Track 的第三个原语。它是更高阶的视觉组件,只是它的+成员恰好使用了媒体素材。++第一个官方实现是 `@narratage/deck-track`。它诚实的作者含义是一个**深度栈 Deck**:++```text+ordered Cards+semantic activation points+current Card+visible previous/future neighborhood+relative-depth layout+whole-collection state transition+ordinary VisualTrack output+```++它与 Media Track、Text、Caption 和 Ranking 是同级关系:++```text+Media Item / Sequence ─┐+Depth-Stack Deck ──────┤+Text ──────────────────┼─> ordinary VisualTrack values ─> Composition+Caption ───────────────┤+Ranking ───────────────┘+```++Core、Film、Composition 和 HyperFrames 都不知道某个贡献来自 Deck。++## 2. 为什么 Deck 在 Media Track 之外++Media Item 回答的是单个素材如何呈现。Media Sequence 回答的是成员如何在同一个共享表面上相互替换。+深度栈 Deck 回答的是另一个问题:当当前成员改变时,整个有序集合如何改变姿态。++在同一帧上,一个 Deck 可能同时显示:++- 当前 Card;+- 若干保留下来的历史 Card;+- 若干未来的预览 Card;+- 按相对深度区分的不同偏移、缩放、旋转、不透明度和色调;+- 一次让每个保留 Card 从旧姿态移动到新姿态的转场。++这是集合状态,而不是源采样、适配或“出场 / 入场”成对交接。把它留在 Media Track 里,会让一个历史遗留+的呈现模型看起来像通用的媒体原语。++## 3. 目前还没有通用的 Deck 合同++“Deck”当前是一个设计家族,不是共享的公开 Type。其他有价值的模型可能具有本质不同的拓扑:++- 水平或环形 Carousel;+- 扇形布局;+- Cover Flow;+- 带有一个特殊当前成员的网格;+- 自由拼贴;+- 时间轴历史;+- 看板与条目一同演化的 Ranking 板。++这些包可以定义不同的作者 Surface、校验与 lowering,它们只需要发出终端 `VisualTrack` 合同即可。只有当+多个真实实现证明存在一条更小的共同法则之后,我们才应该抽出共享的 Deck 库。仅仅共用“Deck”这个名词,+不构成设立中心协议的证据。++因此第一个包应该暴露一个诚实的组件名,例如 `DepthStack`,而不是声称它的字段描述了所有可能的 Deck。++## 4. 包边界++预期的关系是:++```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` 可以复用 Media Track 中聚焦的实现函数,或者后续某个纯实现层的媒体 lowering 库。+这种代码复用并不会让 Deck 变成 Media Track 组件,也不会通过 Core 暴露通用的 `MediaProgram` 或+`DeckProgram`。++这个包不做以下事情:++- 生成 Card 的图像或视频;+- 选择 Provider 或凭据;+- 从 URL、目录或媒体元数据推断 Card;+- 检视另一个 Track 或已累积的下层合成结果;+- 预留全局的 stacking 区段;+- 向 Core、Film、Composition 或 HyperFrames 添加 Deck 语义。++每个 Card 的来源、标签、触发点和声音依赖都是显式的图引用。++## 5. 示意性的作者 Surface++语法尚未冻结,但包的归属应当可见:++```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>+```++组件本身产出一个普通的 `VisualTrack`。它不嵌套在 `<media:Track>` 里,也不通过 `mode="deck"` 选择。++SVML 拥有拓扑:有序的 Card 成员关系、source 边、trigger 引用、终止点、Frame 以及可选的标签输入。SVS+拥有可复用参数:可见邻域、深度姿态、frame Paint 和 reflow 运动。SVS 不能创建 Card、隐藏 source 边或+选择 Provider。++## 6. 精确的状态模型++设作者声明的 Card 激活帧为:++```text+p1 < p2 < ... < pN < T+```++其中 `T` 是显式的终止点。在帧 `f` 上:++```text+current(f) = greatest i such that pi <= f+```++在 `p1` 之前,除非有显式的初始状态策略另行规定,组件处于非激活状态。在 `T` 及其之后,除了作者显式声明+的退场运动之外,组件同样处于非激活状态。++包会校验作者声明的出现顺序。它绝不会把相等、逆序或缺失的 trigger 点整理成一份看似合法的呈现。++可见性是显式的包参数:++```ts+type DepthStackVisibility = {+ readonly previous: number;+ readonly next: number;+ readonly wrap: boolean;+};+```++每个可见 Card 都会围绕 `current(f)` 得到一个整数相对深度。一个纯函数把该深度映射为它的姿态:++```ts+type DepthStackPose = {+ readonly x: number;+ readonly y: number;+ readonly scale: number;+ readonly rotationDeg: number;+ readonly opacity: number;+ readonly stacking: number;+ readonly tone?: DeckCardTone;+};+```++公开的作者模型应当暴露具名的 pose / visibility Recipe,而不是要求作者把整张表内联重复一遍。++## 7. Reflow 是集合级的状态转换++当 Card `i` 成为当前项时,在旧状态或新状态中可见的每一个 Card 都会得到一个旧姿态和一个新姿态。reflow+转场以一个精确时长和一条缓动法则在这两个姿态之间插值。++这与 Media Sequence 的交接不同:++```text+Sequence transition coordinates outgoing member + incoming member+Deck reflow coordinates the union of old-visible + new-visible Cards+```++它们不得共用同一个 `transitionStyle` 联合类型。Card 还可以拥有自己的当前项强调效果,但它不能改动属于+另一个 Track 的像素。++渲染器把状态和姿态求值为绝对帧号的纯函数,不保留可变的“上一帧”状态。因此任意帧渲染、分块 Lambda 渲染+和乱序帧求值都保持确定性。++## 8. Card 素材与播放++每个 Card 都可以复用与 Media Item 相同的显式 layer、Content Fit、裁剪和 frame Paint 法则。这属于实现+复用,不是作者模型的继承。++带时间的 Card 源必须定义它在非当前项时如何采样:++```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+```++静态素材不需要播放策略。视频绝不能在仅作为未来预览时悄悄播完。++Card 标签是可选的显式 Text 输入。Deck 包可以复用 typography lowering,但它不能从文件名、URL 或隐藏的+图像元数据推导 Text 事实。++初版 DepthStack 只有视觉。如果后续某个 Deck 组件要暴露源音频,它必须以独立且显式的 `AudioTrack` 投影+提供,并带有作者声明的当前成员 / 交接法则;音频绝不能仅仅因为某个 Card 的容器里含有音频流就变得可闻。++## 9. Stacking++Deck Track 没有 Track 级 z-index,也不创建 stacking context。当同级 Track 需要插入其间时,看板 / 背景与+各个 Card 可以 lower 成各自独立的绝对 stack Present。++相对深度只决定自有 Card 之间的顺序。reflow 期间的临时顺序也只存在于这一显式关系内部,它不会分配全局 z 段。++## 10. 从旧实现迁移++从旧 Deck 实现中保留:++- 作者显式声明的 Card 顺序;+- 由语义 trigger 驱动的当前状态;+- 可配置的 previous / future 可见性;+- 有限或显式的环绕行为;+- 深度偏移、缩放、交替旋转、不透明度和色调;+- 整组的入场、持续与退场运动;+- 全组插值 reflow;+- frame Paint、内边距、圆角、描边和阴影;+- 确定性的帧内局部求值。++废弃:++- 把 Deck 当作 B-roll 或 Media 的一种模式;+- 隐式的 `linkNext` 拓扑;+- 藏在“一般位于人脸下方”背后的放置语义;+- 从源元数据自动生成标签;+- 下层合成结果参与的转场;+- 泳道级的全局声音默认值;+- 在 Core、Film、Composition 或 HyperFrames 中的任何注册表条目。++## 11. 实现与验收顺序++1. 实现共享的 Temporal 与 Spatial 切片;+2. 暴露 `DepthStack` 和显式的有序 Card;+3. 求解精确的 trigger 状态与有限可见性;+4. 为 Card 内容复用聚焦的媒体层 lowering;+5. 加入纯粹的相对深度姿态求解;+6. 加入集合 reflow 与整组生命周期运动;+7. 证明静态与带时间素材的非激活播放行为;+8. 迁移一个真实的旧系统 Deck,并且只有在验收矩阵通过之后才冻结。++第 1–8 步在 `@narratage/deck-track` 中执行。包测试覆盖下文列出的每一种状态、校验、播放、标签和扩展场景。+真实的 HyperFrames 见证会渲染一个旧风格的三 Card 深度栈两次——一次单 worker、一次三个分区 worker——并+逐字节比较每一帧解码结果,同时证明每个作者声明的当前状态都被绘制出来。这完成了 Deck 包的验收矩阵,独立+的通用 E1–E8 终端 VisualTrack / Visual IR 关卡现在也已通过。++要求的证据包括:++- 只有 previous、只有 next 以及混合的邻域;+- 零个、一个和多个可见邻居;+- 有限边界与显式环绕;+- 缺失、相等和逆序 trigger 的拒绝;+- 深度姿态、交替旋转、不透明度和色调;+- 硬切与插值两种全集合 reflow;+- 静态与带时间 Card 的采样法则;+- 可选的精确字体标签;+- 整组入场 / 持续 / 退场且不覆盖 Card 姿态;+- 顺序、分区和乱序渲染下逐字节一致的帧;+- 安装另一个 Deck 包时,无需改动 Core 或第一个 DepthStack 包。diff --git a/docs/zh/guide/spec/media-track.md b/docs/zh/guide/spec/media-track.mdnew file mode 100644index 00000000..61a5b55b--- /dev/null+++ b/docs/zh/guide/spec/media-track.md@@ -0,0 +1,679 @@+---+title: SVML Media Track 创作+description: 统一官方 Media Track 的可执行预发布权威文档。Item/Sequence。+---++# SVML Media Track 创作++状态:统一官方 Media Track 的可执行预发布权威文档。Item/Sequence 两个 Surface、定时素材、+有序 Layer、运动、Handoff、独立的音频投影以及受限的 Speech 投影均已实现。原先的+`@narratage/broll` 垂直切片已被移除,而不是作为兼容层保留。本合同尚不是冻结的公开 ABI。++## 1. Conclusion++全画幅插叙、下方证据卡、角落图片、透明贴纸、动图、短视频以及普通的替换序列,并不是各不相同的+终端 Track family。它们只是同一组媒体关注点的不同组合:++```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+```++它们属于同一个视频领域包 `@narratage/media-track`,并且全部下降为普通的对等 `VisualTrack`;+只有在作者显式声明时,才会同时下降为 `AudioTrack` 值。++一个包不等于一个带条件分支的超级组件。作者 Surface 暴露两个语义不同的组件:++```text+Media Item one independent presentation with one projected window+Media Sequence ordered members replace one another on one shared surface+```++`Item` 和 `Sequence` 共享聚焦的值族和下降代码。它们之所以是两个独立组件,是因为拓扑、校验和端口+都不同。不存在 `mode="broll | sequence | overlay"` 这样的字段,也不存在“选了某个 mode 就冒出另一个+隐藏组件”的步骤。++深度堆叠的 Deck 被刻意排除在本包之外。它是更高阶的集合状态组件,而不是媒体原语。官方的迁移模型在+[`deck-track.md`](./deck-track.md) 中独立规定;未来的 Carousel、Fan、Grid 或其他 Deck 包并不必须采用+那套模型。++“B-roll” 仍是有用的剪辑术语或 Recipe 名称,但它不是公开的数据 Type。++## 2. Boundary++统一后的包是一个作者包,同时也是确定性编译器:++```text+@narratage/media intrinsic media facts and normalized sources+@narratage/media-pipeline inspection, stream selection and normalization vocabulary+@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+```++它不做这些事:++- 生成图像或视频;+- 挑选模型或 Provider;+- 检查凭据、URL 或本地可执行文件;+- 让 Runtime 或 Provider 自行发明流选择策略;+- 拥有 Program 时钟或 Canvas;+- 读取兄弟 Track 或已累积的下层合成结果;+- 往 Core、Film、Composition 或 HyperFrames 里添加 B-roll、Sequence、Deck 或 Speech 分支。++Core 只看到固定的图 Operation、Record 和边。Runtime 执行任何显式的媒体检查/归一化 Need,或+Surface 物化 Need。Provider 不会重新解释 placement、motion、transition 或音频策略。++## 3. Source truth++每一个可见 sample 都通过显式的图边进入。作者 Surface 区分四种形态,而不是从单一 Blob 类型去猜:++- 静态图像素材,带内容寻址的 Artifact 和精确的显示方向尺寸;+- 生成的/原始视频素材,使用 Track 的 ProgramSpace 帧率,通过通用 Media Pipeline 下降,并带显式的+ 纯视觉或 A/V 策略;+- 已归一化的定时视觉素材,带精确帧率、帧数和尺寸;+- 带类型的 `CompositableSurface` 素材,带精确的静态/逐帧时序和 alpha 模式。++固有事实的所有者仍然是 `@narratage/media`。Media Track 包内部可以使用包内的已解析联合类型,但不得+再造一个通用媒体 Type,也不得把 provider、源路径、Narrative 摘要或上游血缘复制进每一个 item。++按文件名推断是非法的。具体来说:++- 动图 GIF 或动图 WebP 不能继续作为由浏览器计时的 `<img>` 存在,因为并行渲染时第 `n` 帧必须能独立+ 渲染;+- 它必须被归一化为精确逐帧计时的视觉素材,或者带类型的动画 Surface;+- 静态图像即使其文件格式也支持动画,仍然没有时长;+- 含音频的 MP4 不会因此就让那段音频可听;+- 带 alpha 的视觉素材必须保留显式的 alpha 合同。++多个 Layer 可以引用同一个 Artifact。图和 Artifact 收集器会对字节做去重;渲染器仍然独立求值每一个+被声明的 sample。++## 4. The orthogonal item model++从概念上说,一个独立 Item 拥有:++```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;+};+```++各个正交轴是:++| 轴 | 负责 | 不负责 |+|---|---|---|+| source | 精确的静态/定时/Surface 素材 | Provider 或素材发现 |+| temporal | occurrence 展开与 item 窗口 | 素材播放 |+| frame | Placement Frame | 可见 Paint 或内容宽高比 |+| layers | 有序的 Paint/媒体 sample | Track 相对的 z 上下文 |+| content fit | 每个 sample 一个 Content Frame | zoom/pan 或播放 |+| occupancy | 源裁剪与源时间映射 | 目标窗口 |+| frame presentation | 裁剪、圆角、描边、阴影、内边距 | 几何构造 |+| lifecycle motion | 自有像素的进入、持续与退出 | member 之间的 handoff |+| sampling motion | 单个媒体 Layer 内部的 pan/zoom/旋转 | Placement Frame 的运动 |+| stacking | 绝对 Present 位置 | Track family 优先级 |+| source audio | 显式投影某一个被选中 Layer 的音频 | 自动的容器音频 |++这些都是包内的 Program 事实。它们不会变成 Core 或终端 Track 合同上的字段。++## 5. Illustrative author Surface++最终的 Surface 必须优先使用具名 Frame 和 SVS Recipe,而不是大段内联参数堆。一种可能的写法是:++```xml+<media:Track id="editorial-media" map={timing.map} space={speech.space} canvas={vertical}>+ <media:Item+ id="full-cutaway"+ video={demo.video}+ during={story.selection.demo}+ frame={vertical}+ appearance={studio.media.full-cutaway}+ />++ <media:Item+ id="corner-loop"+ surface={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" image={step1.image} extent={step1.extent} at={story.moment.step1}/>+ <media:Member id="step-2" image={step2.image} extent={step2.extent} at={story.moment.step2}/>+ <media:Member id="step-3" video={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>+```++这段语法只是示意。规范性的要点是:++- 声明与可复用外观留在使用点之外;+- 每一个 source、Frame、Selection 和 Moment 都是显式引用;+- `image`、`video`、`media` 和 `surface` 表示互斥的 source 形态;绝不会去猜一个通用 Blob 到底是静态还是+ 动态素材;+- `Item` 与 `Sequence` 在作者视角下是明显不同的语义;+- `during`、`at`、`for`、`until` 这类简写全部下降到同一套 Temporal 代数;+- 任何 Runtime 都不参与决定某个东西是插叙、卡片还是贴纸。++### SVML structure and SVS parameter bundles++SVML 拥有拓扑:source、Frame、时间引用、Item/Sequence 成员关系、Handoff 边、标签和声音输入。+SVS 拥有具名的可复用参数包:Content Fit、frame Paint、裁剪、运动参数和转场外观。++SVS Recipe 不能隐藏一条 source 边,不能创建 member,不能选择 Provider,也不能让两个独立的 Item 变成+一个 Sequence。把一个转场 Recipe 应用到整个 Sequence,会在解析后的 Program 里把这个选择物化到每一条+被声明的 Handoff 上。因此 Recipe 既保持简洁,又不会退化成第二套图语言。++### Small framed inset with a smooth rise++小画框不是另一个组件。它就是一个普通 Item,只不过它显式的 Placement Frame 比 Canvas 小。使用点的+结构依然可读:++```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"+ video={product.video}+ during={story.selection.proof}+ frame={product-inset}+ appearance={studio.media.fuzzy-card}+ motion={studio.motion.smooth-rise}+ />+</media:Track>+```++被引用的 Recipe 在概念上解析出彼此独立的参数,例如:++```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-canvas` 由 Canvas 和解析后的 Item 尺寸推导出一个画布外的起始位姿;+`offset-y: 120px` 则从最终 Frame 的下方开始,未必要离开画面。两者都下降为逐帧精确的局部变换,并且+都不改变最终的 Spatial Frame。++普通的柔边或发光边缘下降为自有的 border 加 box shadow/drop shadow。真正不规则的毛边、撕纸边或噪点边+不是什么魔法 `border-style`:它是一个显式的局部 Layer,比如一张透明边框 Artifact 或一个确定性的+`CompositableSurface`。由于该 Layer 会影响图拓扑和 Artifact 收集,它的 source 必须在 SVML 里接上+(例如写成 `<media:Layer surface={fuzzyFrame.surface}/>`);SVS 可以给它上样式,但不能隐藏这条 source+边。外层的生命周期包裹器会带着 frame Paint、边缘 Layer 和内容一起运动。++内置的缓动名称可以直接下降到 Visual IR。更复杂的贝塞尔或弹簧 Recipe 仍归 Media 包管,可以被确定性地+采样为按帧寻址的关键帧;这不需要 Core、Composition 或 Runtime 学会一种新的运动类型。++## 6. Independent Item timing++Item 使用 [`track-authoring.md`](./track-authoring.md) 中的通用流水线:++1. 定位 Selection、Moment 或 Program 点;+2. 展开 `one` 或 `each` occurrence;+3. 为每个 occurrence 投影一个目标窗口;+4. 与 ProgramSpace 求交并校验;+5. 在该 item 窗口内求值每一个 Layer 的源裁剪与 occupancy;+6. 求值生命周期运动与采样运动;+7. 产出自包含的 Present。++独立的 Item 保持独立。它们的窗口可以重叠,并按各自显式的绝对 stacking key 合成。Program 顺序不会让+它们互斥,不会裁掉优先级更低的 item,不会自动缝合空隙,也不会推断出一个 Sequence。++全屏 B-roll 不过是一个 Placement Frame 等于 Canvas、前景 Layer 通常用 `cover` 的 Item。小图、GIF 或+视频只是同一个 Item 配上更小的 Frame。“不要挡住人脸”不是 Media 的某个 mode:作者要么消费一个合适的+具名 Frame,要么由上游具备主体感知能力的布局组件显式产出一个。++## 7. Ordered local layers++一个 Item 在一个 Placement Frame 内拥有一份有序的局部 Layer 列表:++```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;+};+```++[`spatial-layout.md`](./spatial-layout.md) 中列出的全部衬底情形,都只是普通的 Layer 列表:++- 透明:没有衬底 Layer;+- 纯色或渐变:一个 frame Paint Layer;+- 自身模糊:同一个 source 进入一个 cover/模糊 Layer 和一个前景 Layer;+- 替代衬底:由另一个显式 source 提供衬底 Layer;+- 装饰卡片:Paint、border/阴影/内边距,再加一个或多个媒体 Layer。++每个媒体 Layer 都由自己的固有尺寸和 `ContentFit` 推导出自己的 Content Frame。不存在特殊的+前景/背景配对,也不存在唯一的共享内框。++Frame 级裁剪是显式的:不裁、裁到 Placement Frame,或裁到自有形状。圆角、border、阴影、内边距和+frame Paint 都属于表现层。它们不能改变 Spatial 几何,也不能采样另一个 Track。++## 8. Source-time occupancy++静态素材没有固有播放时长,在其 Layer 处于活动状态的整个区间内持续绘制。定时视频、动图或动画 Surface+先执行显式 trim,再套用通用的视觉 occupancy 法则:++```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+```++不存在 `auto`、`native`、`finish`、`freeze` 或 `phased` 这类作者枚举值。图像不会被塞一个假的播放模式。+源 trim 在 occupancy 之前执行。空间上的 contain/cover 与时间上的 stretch 互不相干。++即使某个 `once` Layer 提前结束,Item 的目标窗口依然有效。其他 Paint 或媒体 Layer 可以继续存在。若作者+希望整个 item 保持可见,就选 `hold`、补一个常驻 Layer,或者直接写一个更短的目标窗口;编译器绝不会靠+猜哪个 Layer 是主 Layer 来收缩 Item。++## 9. Media motion has four separate channels++旧的 B-roll 行为拆成四条由包自有、彼此显式分离的通道:++```ts+type MediaLifecycleMotion = {+ readonly enter?: MediaEdgeMotion;+ readonly sustain?: readonly MediaSustainMotion[];+ readonly exit?: MediaEdgeMotion;+};++type MediaSamplingMotion = {+ readonly keyframes: readonly MediaSamplingKeyframe[];+};+```++### Entry motion++作用于一个 Item 或 Group 在其可见包络起始处所拥有的全部像素。合理的带类型 Recipe 包括淡入、方向滑入、+缩放、弹出、回弹、局部模糊显现、擦除、翻转和旋转。++### Sustain motion++作用于可见包络期间。漂浮、呼吸、脉冲、摇摆、抖动和漂移都是合理的算子。被声明的有序列表按确定性方式+求值;多个变换不会悄悄互相覆盖。++### Exit motion++作用于包络结束处的全部自有像素。它有自己的算子和时长;它不会自动成为 entry 的逆过程。++### Sampling motion++作用于某一个媒体 Layer 已完成 fit 的 Content Frame。归一化关键帧可以驱动缩放、源点/内容点位移和旋转。+Ken Burns 是一个采样运动 Recipe,既不是 Base 特效,也不是 occupancy 模式。++即使 entry 与 exit 重叠,它们各自被声明的时长也保持不变。包在每一帧同时求值两者,并确定性地合成它们+彼此独立的 opacity、transform、filter 和 clip 通道。它绝不会按比例压缩任何一侧,也绝不会把 Item 跑两遍。+可见的 Item 窗口仍然是最终的裁剪边界。++变换栈是固定的,因此各通道不会互相覆盖:++```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+```++下降器可以在代数上合并矩阵,也可以产出嵌套的 Visual IR 元素,但顺序和像素必须完全一致。这些是 Media+包的合同,不是某个通用的公开 `effects` 参数袋。++## 10. Sequence: explicit member replacement++一个 Sequence 拥有两个或更多嵌套的 Member,它们共享一个 Placement Frame 和一个外层生命周期。它必须被+显式创建;相邻的 Item、重叠的窗口或某个转场 Recipe 都不会隐含成员关系。++每个 Member 拥有:++- 稳定的作者身份;+- 显式的媒体 Layer 以及逐 Layer 的 fit/occupancy/采样运动;+- 恰好一个由 Moment 或某个 Selection 边界推导出的激活点;+- 没有独立的外层 entry 或 exit 运动。++Sequence 有一个显式的终止点。对于激活帧 `p1..pN` 和终止点 `T`:++```text+p1 < p2 < ... < pN < T++logical member 1 phase [p1, p2)+logical member 2 phase [p2, p3)+...+logical member N phase [pN, T)+```++源码中的 occurrence 顺序具有权威性。编译器绝不按物理时间排序。缺失、同帧、逆序或超出 Program 范围的+激活点,会让整个 Sequence 原子性失败。++每一对相邻成员都拥有一条显式的 Handoff。不存在只活在编辑器或 Runtime 里的转场默认值;“应用到全部”+会把同一个被选中的转场物化到每一条边上。++### Pair transition++官方的初始集合是:++- cut;+- crossfade;+- push;+- wipe;+- cover;+- page turn。++一个转场拥有算子身份、精确时长、带类型的参数,以及位于 `[0,1]` 的边界位置比例 `r`。给定逻辑边界 `p`+和时长 `d`:++```text+handoff.start = p - r × d+handoff.end = p + (1-r) × d+```++帧量化保持转场总长度精确不变。相邻的 handoff 窗口不得重叠;非法时长直接失败,而不是造出一个隐式的+三源转场。++在 handoff 期间,退出与进入的 Member surface 都由该 Sequence 拥有。它们的媒体 sample 在各自被展开的+视觉跨度上连续播放。转场既不改变 ProgramSpace,也不改变上游的 Selection/Moment 点。++Sequence 的 handoff 只能在其共享的 Placement Frame 内部工作。这让 cut、crossfade、push、wipe、cover 和+page turn 都成为诚实的局部关系。针对 `composite_below` 的外层 handoff 被刻意废弃:它会读取并改动无关的+下层 Track。++Sequence 自身可以使用普通的 entry/exit 运动。在下层 Track 之上做全屏淡出是合法的,因为改变的只是+Sequence 的不透明度;而把下层 Track 推走或翻页则不合法。++## 11. Audio is explicit and projected separately++视觉素材默认静音,除非作者显式地从恰好一个具名媒体 Layer 中选取源音频。这是 item 级别的,因此前景与+它自身的模糊副本不会意外地把同一个源混两遍。++```ts+type MediaSourceAudioProjection = {+ readonly fromLayer: string;+ readonly gain: number;+};+```++音频投影复用被选中 Layer 的精确 trim、播放映射和已解析的调度。Sequence 的每条边各自拥有自己的音频关系:++- `cut` 在逻辑激活点切换可听性,即使视觉 surface 存在重叠;+- `crossfade` 使用显式声明的音频 handoff 窗口;+- 视觉转场绝不会悄悄替你选一个音频转场。++entry/exit 或 handoff 的音效是显式的音频 Artifact 输入,带显式增益。它们在解析出的精确 entry、exit 或+边界点上下降。它们不是包级全局文件名、不是可变的音效库默认值,也不是隐藏的通道音效。++编译器不会返回一个同时包含两个终端 Track 的原子 `MediaProduct`。它解析出一个包自有的 Media Program,+并提供彼此独立的确定性投影 Operation:++```text+Resolved Media Program ─┬─> project visual ─> VisualTrack+ └─> project audio ─> AudioTrack+```++因此,任一终端输出都可以被 Run Graph 独立地定向、替换或满足。当两者同时被需求时,它们仍通过一条显式的+图边共享同一份已解析调度,而不是复制两份时序元数据。++一个纯视觉 Item 不会仅因为它的源容器里带音频流,就去要求音频归一化或渲染。++## 12. Stacking and flat Tracks++Media Track 自身没有 z-index。每一个解析出的顶层 Item 或 Sequence surface,以及任何可被单独穿插的+member/Layer,都会产出绝对的 Present stacking key。++frame Paint 与紧耦合的媒体 sample 可以留在同一棵 Present 局部元素树里。当对等 Track 必须能出现在某块+板、卡片、图标或 Layer 之间时,包会产出带独立绝对 key 的独立 Present。Track 归属关系绝不创建 stacking+上下文。++Sequence handoff 内部的临时顺序由包自有,且只在该关系的那些帧内存在。它不会预留一条全局 z 带。++## 13. Speech Spine's restricted Media projection++Speech Spine 不应再维护第二套临时的媒体渲染器。它的视觉投影使用同一套 Media 下降实现,只是生成的+Program 被刻意限制:++```text+one normalized speech-bearing Take per Segment; its visual stream is optional+exact already-established Segment frame span+explicit authored Spatial Frame+one foreground layer+explicit fit and absolute stacking order chosen by the author+muted visual+cut between contiguous takes+no entry, sustain or exit motion+no Sequence state+no source-audio projection+```++Speech 的作者 Surface 接受原始 `video=`,并在装配前展开同一套通用的检查与归一化图,按 Spine 显式的+帧率选取主运动视频加默认音频。原始 `audio=` 展开为音频权威的归一化图,不贡献任何视觉 Present;它绝不+凭空造出黑场素材。已准备好的 `media=` 仍是直接的精确输入。视觉 Take 继承 Spine 显式的 `visual-frame`、+`visual-appearance` 和 `visual-z`,并可在这几个受限的轴上做逐 Take 覆盖。装配之后,Speech 音频仍走独立的+规范路径 `SpeechAudioBasis -> AudioTrack` 投影;受限的视觉下降器本身保持静音,不会去重新发现容器音频。++这可以是对聚焦的 Media 下降辅助函数的代码依赖。当没有任何外部组件消费那个中间值时,它并不需要暴露+一个公开的 `MediaProgram` 图 Type。若日后真的出现图消费者,包可以暴露自己的带版本已解析 Type;Core 仍然+不会注册 Media 语义。++作者导入的是 Speech Spine,其 manifest 声明了自身的包依赖。作者不需要仅仅因为实现复用了 Media 下降,+就再导入第二个解析器。++普通 Media Item 可以直接消费 `during={story.segment.answer}`。这不是隐式 Selection:Temporal 解析的是+Segment 早已存在的结构性起止锚点。当作者的真实意图是 Selection 和 Moment 时,同一个 Item 仍然可以消费+它们。++## 14. Legacy audit: retained and retired++保留:++- 通过统一的 Item 模型表达全画幅插叙、分屏和角落叠加;+- 静态图像、类 GIF 动画和视频;+- 彼此独立且可重叠的媒体呈现;+- 显式的 contain/cover/焦点采样,以及前景/自身模糊衬底;+- 源 trim 与 once/hold/loop/stretch occupancy;+- entry、exit、持续的外层运动和内部采样运动;+- 显式的 Sequence 成员关系与共享 surface 的成对转场;+- 提示位置比例,以及跨转场窗口的连续视觉采样;+- 显式的源音频与转场/边缘音效;+- 稳定的作者身份与确定性的声明顺序。++废弃:++- 独立的 B-roll 终端 family;+- 会改变合法端口或设置的 `mode`;+- 用 URL 扩展名猜测 image/video/GIF 行为;+- Track 级 z-index 与隐式 item 优先级;+- `auto` 播放、`finish`、`freeze`、`phased` 以及渲染器兜底修复;+- 自动排序或 `linkNext` 推断;+- 用同一组 `focalX/focalY` 同时表示源点和目标点;+- 用固定的前景/背景字段取代有序的局部 Layer;+- 用一个 CSS transform 槽位让各运动通道互相覆盖;+- 对重叠的 entry/exit 时长按比例压缩;+- 通道级全局音效与自动选中的音频;+- 外层 `composite_below` 转场以及一切 Base FX 依赖;+- 把 VisualTrack 与 AudioTrack 的满足耦合在一起的打包式 B-roll Product。++旧的 Deck 行为在 [`deck-track.md`](./deck-track.md) 中独立迁移;把它从 Media Track 移除并不等于删掉这项+能力。++## 15. Package and implementation shape++预期的包关系是:++```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+```++包内部可以使用聚焦的文件划分,或未来仅供实现使用的库。但它不得造出一个被 Text、Caption、Ranking 和+Media 共用的大一统创作库,也不得在新增一个媒体 Recipe、运动算子或组件包时要求 Core 发版。++原先的 `@narratage/broll` 包在迁移期间用作回归见证,现已废弃。由于项目处于预发布阶段,不保留任何兼容包。+“B-roll” 仍是描述某个 Item 或 Sequence 的有用剪辑术语,而不是终端 Type 或作者包。源素材与生成文件保持+原样,不受影响。++## 16. Implementation order++只有在共享的 Temporal 与 Spatial 切片就位之后才实现:++1. **已实现:** 引入 `@narratage/media-track`,先支持一个静态图像 Item,其 BlobArtifact、+ IntrinsicExtent、SpatialFrame、ContentFit 和 ProgramSpace 是彼此独立的语义输入;+2. **已实现:** 加入定时素材的源 trim 以及全部 occupancy/对齐策略;+3. **已实现:** 加入有序的 Paint/媒体 Layer、裁剪和双 Frame 的 fit 模型;+4. **已实现:** 加入生命周期运动与采样运动,并固定变换栈;+5. **已实现:** 加入显式的 Sequence 调度与成对转场;+6. **已实现:** 加入独立的源音频与音效投影;+7. **已实现:** 把 Speech Spine 的视觉投影接到受限下降器上;+8. **已实现:** 迁移仓库中已签入的 B-roll 示例并废弃旧包;+9. **已实现:** 用结构性证据、真实媒体证据和分区浏览器证据闭合包内验收矩阵。+ [`track-expressiveness.md`](./track-expressiveness.md) 中独立的共享 Track/Visual IR 关卡同样通过。+10. **已实现:** 让 `video=` 按已连接的 ProgramSpace 帧率下降到共享的 Media Pipeline,同时保留显式的+ `media=` 作为“已准备素材”的逃生口。++其中没有任何一步需要改动 Core、Runtime、队列或 Provider。Surface 物化可以使用某个已显式注册的 Provider+能力,但普通的 Item/Sequence 下降是确定性的本地编译。++## 17. Acceptance matrix++### Material++- 不透明与带 alpha 的静态图像;+- 竖版、横版和正方形图像;+- 生成的/原始视频,在有和没有显式选中音频两种情况下自动归一化;+- 已显式准备好的归一化视频直接接入,不再做第二次归一化;+- 动图 GIF/WebP 归一化为精确逐帧计时;+- 静态与动画的 Compositable Surface;+- 重复使用同一个 Artifact,不产生重复存储或重复源音频。++### Item++- `one` 下的 Program/绝对窗口,以及 `one` 和 `each` 下的 Selection/Moment 窗口;+- 位于互不相关的绝对 stacking key 上、彼此独立且重叠的 Item;+- 全部源 trim 情形,以及更短/相等/更长的 occupancy 情形;+- 全 Canvas、分屏、下方卡片、角落和画布外 Frame;+- 透明、纯色、渐变、自身模糊和替代 source 的衬底 Layer;+- 每一种 Content Fit,以及内容焦点与 frame 焦点不一致的情形;+- entry、sustain、exit 与采样运动,分别使用以及组合使用;+- 对重叠的 entry/exit 时长做确定性合成,不做隐藏的重新计时。++### Sequence++- 图-图、视频-视频、图-视频以及 alpha Surface 之间的 handoff;+- 严格的声明激活顺序与稳定的 member 身份;+- cut、crossfade、push、wipe、cover 和 page turn;+- start/center/end 三种边界位置比例;+- 跨 handoff 重叠区间的连续源采样;+- 转场时长小于、等于和大于相邻逻辑相位间距的情形,前提是显式 Sequence 包络与“无三源”法则仍然成立;+ 非法的包络/重叠必须失败;+- 缺失、重复、逆序和同帧激活的失败情形;+- 不存在隐式的三成员重叠,也不存在下层合成输入;+- 组的 entry/exit 只作用于自有像素。++### Audio and execution++- 纯视觉 source 不产生任何音频工作需求;+- 恰好一个被显式选中的 source Layer 贡献音频;+- 硬切与交叉淡化两种 Sequence 音频 handoff;+- 同一边界上同时发生的 exit/entry 音效混合;+- 独立的 BGM 保持不变;+- 独立地定向/替换视觉与音频投影;+- 本地与远程执行下产出完全一致的 Visual Track/Audio Track 计划;+- 任意帧分区渲染出字节级一致的确定性帧。++### Architecture++- 安装另一个 Media 组件不会改动 Core、Film、Composition 或 HyperFrames 的任何 family 注册表;+- 所有 source、时间、空间、声音和标签依赖都是图边;+- 任何 Track 都不包含 provider、路径、Narrative 摘要或 source family 元数据;+- 没有任何 operation 采样已累积的下层合成结果;+- Speech Spine 的受限投影与普通 Item 遵循同一套下降法则。++### Executable evidence++上面的矩阵由可执行证据闭合,而不是靠包状态的文字描述:++- `packages/media-track/test/media-track.test.ts` 覆盖每一种 Item 绑定、严格的 occurrence 展开、全部+ 已记录的 Frame 与 Content Fit、有序的 Paint/sample/衬底 Layer、trim 与 occupancy、生命周期/sustain/采样+ 运动、每一个 Handoff 算子与比例、精确的源音频/音效投影、非法 Sequence 的拒绝,以及显式的作者图边;+- `packages/provider-media-local/test/provider.test.ts` 对带音频和不带音频的运动视频、附带图片、源 A/V+ 偏移、动图 GIF、动图 WebP、精确音频渲染和最终混流跑真实的 FFmpeg 检查与归一化;+- `packages/media-execution/test/webp.test.ts` 单独证明本地与 Lambda 执行共用的动图 WebP 直通 alpha 混合与+ dispose 行为;+- `packages/provider-media-aws-lambda/test/provider.test.ts` 证明远程执行收到的是完全相同的+ `AudioProgramPlan`;本地与 Lambda 媒体环境都执行 `@narratage/media-execution`,而不是各自拥有另一套+ 媒体语义;+- `packages/speech-spine/test/surface.test.ts` 和 `packages/speech-basis/test/product.test.ts` 证明受限的+ Speech 投影、单一共享的生成 Product,以及视觉/音频 Candidate 的独立满足;+- `packages/hyperframes/test/browser-visual.test.ts` 通过真实 Chromium 渲染不透明图像、直通 alpha Surface、+ 双 Frame fit、局部运动和一次 Sequence handoff,然后跨不同 worker 分区比对每一帧解码后的 RGBA;+- 包 manifest 中不含任何 Media family 注册表,公开的值类型中也不含隐藏血缘或 Provider 元数据。++因此,本地包作为构建于冻结的仓库内部 `svml.visual-track@1` / `svml.visual-ir@1` 窄腰之上的预发布 Media+实现已经完整。这并不意味着 Media 作者 Surface 已被发布或被单独冻结。diff --git a/docs/zh/guide/spec/ranking-track.md b/docs/zh/guide/spec/ranking-track.mdnew file mode 100644index 00000000..bc482e2d--- /dev/null+++ b/docs/zh/guide/spec/ranking-track.md@@ -0,0 +1,279 @@+---+title: SVML Ranking Track 迁移+description: 官方 Ranking 迁移的已实现可执行权威,包含全部四个作者组件。+---++# SVML Ranking Track 迁移++状态:官方 Ranking 迁移的已实现可执行权威。四个作者组件、它们共享的触发式调度、可选的同级 AudioTrack+lowering、作者 Surface 以及真实浏览器证据都在 `@narratage/ranking` 中执行。它不是对历史 node 格式的兼容+承诺,也不是冻结的公开 ABI。++## 1. Ranking 的含义++Ranking 是一个视频领域的作者组件,它把一个有序集合呈现为渐进的视觉状态。它不是 Core 概念、不是通用的+Track 模式、不是 Provider,也不是渲染器特性。++旧系统把四种本质不同的行为塞在同一个 `ranking_track` 节点和一个 `rankingType` 开关背后。新系统使用一个+物理包 `@narratage/ranking@1`,但暴露四个互相独立的作者组件:++- `ranking:TierBoard` —— 把已揭示的条目放入具名的 tier 行;+- `ranking:Column` —— 在舞台上展示一个当前条目,然后让它落位到带编号的列中;+- `ranking:TopThree` —— 渐进揭示最多三个条目,并强调当前条目;+- `ranking:TypewriterList` —— 在常驻的纸张 / 列表表面上逐字打出有序文本行。++一个包是共享校验、调度构造、布局工具和绘制原语的正确单位。四个组件是作者语义的正确单位。不存在公开的+`rankingType`、模式选择输入、动态端口注册表或 Runtime 渲染器注册表。++第三方可以发布另一个 Ranking 包,无需在 Core 注册类型,也无需修改本包。安装并 import 该包后,它会通过+普通的模块机制贡献自己的 Surface、Type、validator 和 fragment 编译器。++## 2. 来自旧实现的证据++被审阅的旧项目清单中包含 21 个已迁移的 Ranking 节点:++| 历史变体 | 审阅到的用例数 | 观察到的条目数 |+|---|---:|---|+| Tier | 10 | 5–6 |+| Typewriter | 5 | 5 |+| Column | 3 | 4–5 |+| Top Three | 3 | 3 |++这份清单证明了四种语义都真实存在,但并不证明它们的旧表示应当延续。旧实现存在如下结构性问题:++1. 同一个 UI / node 身份通过切换模式并断开其动态端口来改变语义;+2. 同一对条目 `start/end` 在不同渲染器下分别意味着可见性、动画阶段、后继交接,或者什么也不意味着;+3. Top Three 忽略条目结束时间,而 Typewriter 只用它们的并集来判断纸张是否已挂载;+4. 渲染器检视所有兄弟片段、对其排序或计数,并在通用 Track Program 已经丢失这些语义之后又把组状态制造+ 出来;+5. 一个全局 z-index 使看板与各个图标无法与同级 Track 交错;+6. 裸 URL、环境字体名、Remotion 组件 id 以及三份互为镜像的注册表把环境 / 渲染器细节泄漏进组件;+7. 过短的窗口可能悄悄压掉运动音效,而不是把视觉与声音阶段一起适配到同一份有限的共享调度中。++迁移保留的是有用的视觉能力,而不是这些偶然形成的语义。++## 3. 面向作者的形态++可执行的作者 Surface 是:++```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" style="normal"/>++<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` 提供显式的外层窗口。`triggers` 提供一个有序的 Moment occurrence 集合。`terminal` 是最后一个活动+阶段的显式终点;它可以早于外层终点,从而让完全落位后的结果继续可见。组件要求 trigger occurrence 的数量+等于子条目的数量,并按作者书写顺序一一对应。++外层 Selection 与 terminal Moment 都使用严格的 `one` 语义。trigger Moment 使用严格的 `each` 语义。外层 /+terminal 出现零次或多次、trigger 出现零次,以及任何 trigger 与条目的基数不匹配,都是编译错误;组件绝不会+自己挑一个方便的 occurrence。++这种按位置配对由这四个组件声明,不是通用的 Core 行为。另一种第三方 Surface 可以给每个条目单独的 Moment+边,并 lower 到同一套包内事实。++Style 声明与使用保持分离。SVS 提供具名的通用 Recipe 数据;每个变体专属的 `*Style` 组件拥有各自允许的+键,并把 Recipe 加上显式的字体边编译成一个带类型、由包拥有的 Style。诸如 tier 行、标签、图标和入场行为+这类语义化的条目值不是绘制属性,不属于 SVS。++## 4. 组能看到兄弟,渲染出的 Track 不能++渐进式 ranking 不能通过把每个子项当作孤立的 Track item 来编译。行位置、后继交接、活动条目状态和已落位的+前缀都依赖这个有序的组。但这不意味着条目在渲染时互相检视。++作者组件首先把完整的子项列表和 trigger 集合编译成一份包内私有的调度:++```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;+ }[];+};+```++这是确定性 Operation 之间一个显式的 Graph 值,不是夹带在图像、Track 或媒体 Artifact 里的元数据。它由+Ranking 包拥有并版本化,不会加入 Core、Composition 或共享的 Track 窄腰。++```text+Moment set + SemanticMap + ProgramSpace + outer/terminal projection + ordered item ids+ │+ ▼+ RankingSchedule+ │ │+ Style + content ───┘ └── SFX clips + gains+ │ │+ ▼ ▼+ VisualTrack AudioTrack+```++调度 Operation 保留源顺序和稳定的 occurrence 身份,绝不按物理时间排序。帧量化之后它要求:++```text+outer.start <= p1 < p2 < ... < pN < terminal <= outer.end+```++任何非法或帧相等的序列都会整体失败。视觉与可选音频的 lowerer 消费同一份调度,因此运动与声音不会漂移,+同时它们仍然是 Run Graph 中可以各自独立被 demand 的分支。++## 5. 共同的阶段模型++对外层窗口 `[B, O)`、trigger `p1 ... pN` 和 terminal `T`,条目 `i` 得到:++```text+active stage [p_i, p_(i+1)) or [p_N, T)+cumulative life [p_i, O)+settled life [stage.end, O)+```++`[B, p1)` 可以显示作者显式声明的空看板,但没有隐含的活动条目。`[T, O)` 是可选的完全落位后缀,没有活动+条目。这些事实是由包拥有的兄弟排序,建立在 [`track-authoring.md`](./track-authoring.md) 的共享时间投影+代数之上;它们不是一个新的 `Stage` 合同。++### TierBoard++- 看板占据 `[B, O)`;+- 每个条目从它的 trigger 起累积可见直到 `O`;+- `entry="direct"` 在 trigger 之后直接动画进入它最终的 tier 单元格;+- `entry="stage"` 在共享的 stage 点出现,在其活动阶段内停留于此,并在该阶段结束前移动到最终单元格,之后+ 保持落位状态;+- 条目拥有必填的图像和 tier 行 id;行内的源顺序决定它的单元格;+- 不可能完成的出现 / 移动时长是编译错误,绝不会被悄悄缩短或省略。++### Column++- 带编号的看板占据 `[B, O)`;+- 每个活动阶段内恰好有一个条目占据大舞台;+- 该阶段结束时,这个条目成为已落位列的一部分,直到 `O`;+- 标签必填,图像可选,名次即作者书写的条目顺序;+- 在一份合法的调度之后,当前条目重叠在结构上不可能发生。++### TopThree++- 最多接受三个条目;+- 每个条目从它的 trigger 起累积揭示直到 `O`;+- 只有对应当前活动阶段的条目会得到活动光环 / 强调运动;+- `[T, O)` 展示所有已揭示条目且没有活动强调;+- 标签必填,图像可选,槽位即作者书写的条目顺序。++### TypewriterList++- 纸张占据 `[B, O)`,空白行可以在其 trigger 之前就在结构上预留;+- 第 `i` 行在 `p_i` 开始打字,并保持可见直到 `O`;+- 打字时长由 Unicode 字素簇数量和 Style 的速度确定性地推导;+- 打字以及可选的获胜标记必须放得进该条目的活动阶段,否则编译失败;+- 标题、可选的显式强调区间和各行字符串都是作者内容,不是 LLM 字段。++Typewriter 之所以留在 Ranking 包里,是因为尽管它大量使用文本排版,它的作者语义仍然是一个有序的渐进+ranking。它可以与未来的 Text 实现共享底层的精确字体 / 排版工具,但不得依赖通用 Text Track Program,也不得+冒充成它。++## 6. 空间布局与 stacking++每个组件拥有一个外层放置框和它自己的内部布局算法。Tier 单元格、Column 行或 Top Three 槽位不是通用的+逐条目空间定位器。允许在这些子项上传入任意空间输入会摧毁组件的语义。++放置与 stacking 保持独立:++- 外层框决定看板、舞台和条目的坐标系;+- Style 解析出看板的绝对 stack 顺序,以及舞台 / 条目的默认值;+- 每个子项都可以显式覆盖自己的绝对条目 stack 顺序;+- 在需要独立交错时,看板、舞台装饰和每个条目会 lower 成各自独立的 `VisualPresent` 值;+- 产出的那一个 `VisualTrack` 不是 stacking context,因此同级 Track 的 Present 可以出现在看板与任意图标+ 之间。++任何包都不应仅仅为了获得多个 z 位置而发出多个 Track。稳定的 `tieBreak` 值来自作者声明的组件 / 条目身份,+绝不来自求值顺序。++所有归一化几何都相对于显式的外层框。各变体必需的尺寸参数包括:++- Tier:行定义 / 颜色、看板与标签宽度、stage 点、单元格间距、图标 fit / 圆角以及出现 / 移动时长;+- Column:看板框、行高 / 行距、stage 点与尺寸、单元格 / 图标几何、名次配色以及出现 / 移动时长;+- Top Three:中心 / 宽度、标签行、图标尺寸、光环宽度 / 配色以及揭示 / 强调运动;+- Typewriter:纸张主题 / 绘制、内边距、行距、标题 / 条目排印、旋转、打字速度以及获胜标记的绘制 / 运动。++绘制、几何和运动参数由拥有它们的 `*Style` 组件校验。未知的 Recipe 属性一律失败。不存在任意的 CSS 逃生+出口。++## 7. 媒体、字体与声音++图像和声音通过显式的 `BlobArtifact` 边进入。字体通过显式的、内容寻址的字体栈边进入。Ranking 绝不存储+URL、不要求 Runtime 挑选字体,也不指名某个渲染器组件。++可选音效是普通的作者输入:++- 出现音在条目的 trigger 处开始;+- 移动音来自视觉 lowerer 所用的同一段已调度的移动阶段;+- 增益与素材选择位于 Style / 显式声音输入中;+- 配置了声音就产出同级的 `AudioTrack`;没有声音就不产生被 demand 的音频分支;+- 声音播放绝不进入 Hyperframes 或某个视觉 Track。++Ranking 自身是确定性的,没有 Need、Provider、队列、凭据或环境适配器。如果输入图像是生成出来的,那次上游+生成仍然是另一个 Graph 组件。++## 8. Run Graph 行为++作者图导出普通的逻辑 `visual` 结果,以及在作者声明时导出 `audio` 结果。Target、Candidate 和替换受与其他+所有组件相同的 Run Graph 法则约束。Ranking 不新增任何缓存、pin 或预览原语。++替换视觉结果不会改动音频结果。通过普通的显式输出映射,也可以用一个多输出 Candidate 同时替换两个输出。+一旦每个被 demand 的原始输出都由选定的 Candidate 满足,demand 分析就会剪掉原来的 Ranking 分支及其时间 /+媒体祖先。不需要任何特殊的 Ranking 执行规则。++## 9. 迁移顺序与验收++按以下顺序实现:++1. **已实现:** 共享的时间投影与触发式调度法则;+2. **已实现:** `@narratage/ranking@1`,包含四个相互独立的 Program / Style 和一个私有调度工具;+3. **已实现:** TierBoard 与 Column,两者共同证明累积语义、独占舞台语义以及独立 stacking;+4. **已实现:** TopThree;+5. **已实现:** 使用精确字体 / 排版原语的 TypewriterList;+6. **已实现:** 从同一份调度产出可选的 AudioTrack lowering;+7. **已实现:** 真实浏览器的渐进状态见证,以及每个组件一份作者 Surface 图检查。++验收要求:++- trigger 与条目基数、稳定身份以及所有边界失败都有测试覆盖;+- `T < O` 在画面上可见地证明存在最终的落位后缀;+- 短阶段在不改变阶段边界的前提下确定性地容纳其局部动画与声音阶段;极短的 Typewriter 阶段可以在同一帧+ 揭示多个字素簇;+- 看板与逐条目 Present 能在互不相关的绝对 z 位置上与同级 Track 交错;+- 视觉与声音的事件帧完全一致;+- 只有声明图像可选的变体才允许缺失可选图像;+- 字体与媒体都是内容寻址的依赖;+- 每个组件都能在不改动 Core、Runtime、Composition、Hyperframes 或另一个 Ranking 组件的情况下修改自己的+ Program;+- 安装第五个组件包不需要改动任何中心家族注册表。++本次迁移有意不保留历史 node JSON、模式切换、旧的动态端口、渲染器 id 或 Remotion 组件。历史项目是证据和+视觉参考,不是一门尚未发布的语言的兼容义务。++包的测试矩阵覆盖上述每一条验收项。可选启用的 Chromium 见证会用单 worker 与分区 worker 分别求值全部四个+组件,证明可见的 trigger 推进和最终的落位后缀,并且只对跨进程边缘抗锯齿的微观噪声设定容差。逻辑帧状态、+几何、stacking、事件帧和作者声明的图边都保持精确。diff --git a/docs/zh/guide/spec/screen-overlay.md b/docs/zh/guide/spec/screen-overlay.mdnew file mode 100644index 00000000..fa29ee38--- /dev/null+++ b/docs/zh/guide/spec/screen-overlay.md@@ -0,0 +1,228 @@+---+title: SVML Screen Overlay 作者面+description: 可选官方 Screen Overlay 包的已实现预发布合同及其自描述 Surface。+---++# SVML Screen Overlay 作者面++状态:可选官方 Screen Overlay 包的已实现预发布合同。它的自描述 Surface、十一个带类型的组件以及顺序 /+并行浏览器证据均可执行;它还不是冻结的公开 ABI。++## 目的++`@narratage/screen-overlay` 在作者声明的时间窗口内贡献自包含的、通常是全画布的像素。一次 Flash、暗角、+扫描线薄纱或确定性漏光,都只是普通的 `VisualTrack`,与 Text、Caption、Media 或 Ranking 完全一样。++它不是调整图层、不是有特权的后合成钩子、不是转场引擎,也不是读取下层 Track 像素的手段。++```text+Moment / Selection / Program ─> shared temporal projection ─┐+CanvasSpace ────────────────────────────────────────────────┼─> Overlay Program+effect parameters / explicit owned assets ─────────────────┘ │+ ▼+ Visual IR elements or owned Surface+ │+ ▼+ VisualTrack+```++Core、Runtime 和 Composition 都不认识 Screen Overlay。Composition 只校验并排列它那些自包含的 Present。++## 1. 自包含像素法则++每个 overlay 条目都必须仅凭以下内容就能渲染:++- 它自己作者声明的参数;+- 显式连接的 CanvasSpace 与 ProgramSpace;+- 该条目拥有的零个或多个显式资产;+- 它确定性的局部帧号。++它不得采样:++- 位于其下方的累积 Composition;+- 兄弟 Track;+- 隐藏的 Base Track;+- 上一个或下一个场景;+- 浏览器 backdrop 或环境纹理。++普通的 source-over alpha 合成是允许的:每个带 alpha 的 Track 都是这样抵达画布的。凡是结果依赖未知下层像素+的混合模式或滤镜,都不是自包含的。++这条法则意味着旧的、无源的 `backdrop-filter` 版高斯模糊、Color Adjust 和 Zoom Blur 都不是 Screen Overlay。+若要诚实地保留这些效果,媒体效果组件必须通过图边接收要变换的精确媒体或可合成 Surface,然后输出它自己+变换后的素材或 Track。如果将来某个组件显式地把一组选定的 Track 光栅化成一个 Surface,消费那个 Surface 同样+是显式的;Screen Overlay 永远不会获得一个隐秘的“当前帧”输入。++## 2. 作者包,不是算子注册表++官方包可以在同一个命名空间下暴露若干可读的作者组件:++```xml+<screen:Track id="screen-paint" canvas={vertical} space={speech.space}>+ <screen:Flash at={story.moment.hit} map={timing.map} for="240ms" z="90"+ color="#ffffff" intensity="0.9" attack="2" hold="3" decay="5"/>+ <screen:Vignette during="program" z="20"+ center-x="0.5" center-y="0.5" radius-x="0.82" radius-y="0.68"+ softness="0.3" color="#000000" opacity="0.28"/>+ <screen:Grain during="program" z="70"+ amount="0.12" size="3" chroma="monochrome" motion-rate="0.5" seed="23"/>+</screen:Track>+```++这只是示意性的 Surface 语法。编译出的 Program 包含显式的组件身份、参数和时间绑定;它不是一个由 Core 拥有+的、字符串化的 `effect="..."` 开关。++对这个小规模的官方集合来说,一个包很方便,但它不是中心注册表。第三方可以发布另一个自描述的包,把新组件+lower 到同一个 Visual Track 窄腰。只要现有的 Visual IR 或一个带类型的 Surface 能表达出来,新增一个 overlay+就不得要求改动 Core、Film、Composition 或 HyperFrames。++外观默认值和具名组合属于 `.svs` recipe。包拥有参数校验和确定性 lowering。Runtime Profile 与 Provider 不+选择视觉效果。++## 3. Program 的各个轴++每个 overlay 条目都有四个相互独立的作者关注点:++```ts+type ScreenOverlayItemSpec = {+ readonly id: string;+ readonly content: ScreenOverlayComponent;+ readonly projection: TemporalWindowProjection;+ readonly expansion: OccurrenceExpansion;+ readonly stackingOrder: number;+};+```++- `content` 标识实际的视觉组件及其带类型的参数;+- 组件自有的包络与局部运动参数留在那个带类型的组件内部,而不是塞进一个通用的呈现口袋;+- `projection` 与 `expansion` 使用共享的 Selection / Moment / Program 代数;+- `stackingOrder` 结合稳定的作者身份解析为一个普通的绝对 Present 键。++画布几何在这里不是作者选择的 Spatial Frame。Screen Overlay 有意拥有整个连接进来的 CanvasSpace。局部画面的+光效、图像、卡片或模糊属于普通的 Media、Text 或组件 Track,使用+[`spatial-layout.md`](./spatial-layout.md)。++条目默认相互独立。重叠是合法的,会产生多个普通 Present。不存在单例的 Screen Overlay 泳道,也没有全局的+合并步骤。++## 4. 时间与局部包络++Selection、Moment、Program 和绝对时间都通过 [`track-authoring.md`](./track-authoring.md) 下沉。Screen Overlay+没有自己的 `from`、`until`、`manual` 或短语匹配式的时间法则。++投影出的窗口只回答条目在哪里存在。窗口内的包络属于组件呈现。例如 Flash 可以定义 attack、峰值和 decay;+Directional Matte 可以把一条边从一侧移到另一侧;Grain 可以保持稳定。旧的那个在每个效果时长 30% 处达到峰值+的通用三角包络,作为隐藏的呈现策略被废弃。++Recipe 默认值可以提供包络,但解析后的 Program 必须包含精确的参数。效果不能为了容纳动画而扩张自己投影出的+窗口。作者写得更长的包络只会被该窗口裁剪;它不会被拒绝,也不会被偷偷加速。非法或零长度的窗口仍然通过公共+时间 validator 失败。++## 5. 可移植的官方组件集++有用的旧效果按两种诚实的 lowering 方式分为两组。++### 直接由 Visual IR 承载的候选++它们通常可以 lower 成全画布的矩形、渐变和局部关键帧:++- `Flash` —— 带显式不透明度包络的纯色;+- `ColorWash` —— source-over 的色彩薄纱;没有依赖下层像素的隐藏混合模式;+- `Vignette` —— 作者声明的中心、半径、柔和度、圆度、颜色和不透明度;+- `ScanLines` —— 间距、粗细、角度、不透明度和局部运动;+- `DirectionalMatte` —— 角度、覆盖范围、羽化、颜色、不透明度和进度;+- `WhipVeil` —— 方向、宽度、柔和度、行程和不透明度;+- `GlitchVeil` —— 确定性的、自有的色带 / 色块,而不是对下层像素的位移。++### 自有 Surface 的候选++把它们做成确定性的、带 alpha 的 `CompositableSurface` 值可能更容易或更精确,但当前的官方实现正好能完全+落在封闭的、无代码的 Visual IR 里:++- `Grain` —— 数量、颗粒尺寸、单色 / 彩色、运动速率和必需的 seed;+- `LightLeak` —— 颜色、角度、柔和度、行程、强度,以及随机时必需的 seed;+- `Bokeh` —— 数量、尺寸范围、颜色 / 色温、漂移和必需的 seed;+- `TVStatic` —— 数量、噪点尺寸、扫描线贡献、运动速率和必需的 seed。++只有当两种方式都产出完全相同的声明像素时,选择 Visual IR 还是 Surface 才是 lowerer 的实现决策。它不能取决+于恰好由哪个 Runtime 执行这次 Build。做实体化的实现可以发出一次普通的 Provider Need,但该 Need 返回的是带+类型的自有 Surface,而不会收到下层合成结果。++一切随机行为都要求一个显式解析出的 seed。`Math.random()`、墙上时钟、GPU 噪声或依赖渲染器的熵都是非法的。++## 6. 明确排除的效果++以下旧名称被排除在这个无源包之外:++| 旧效果 | 排除原因 | 诚实的替代方案 |+|---|---|---|+| `gaussian_blur` | 必须读取被模糊的像素 | 带显式输入的媒体 / surface 滤镜 |+| `color_adjust` | 曝光 / 对比 / 饱和 / 色相会改变输入像素 | 带显式输入的媒体 / surface 色彩变换 |+| `zoom_blur` | 真正的径向模糊需要被采样的画面 | 带显式输入的媒体 / surface 效果 |+| screen / multiply / overlay 混合薄纱 | 结果依赖下层像素 | source-over alpha 近似,或带显式输入的实体化 |++这并不删除视觉效果本身。它拒绝的是旧有的那种特权:一个号称普通的 Track 竟能改动它下方的一切。++Screen Overlay 同样不能:++- 改变 Program 时长或播放速率;+- 拥有相邻媒体条目之间的切点;+- 为两个兄弟 Track 做转场;+- 预留最顶层的 z-index;+- 把音效藏在视觉条目内部。++被视觉遮盖的硬切仍然是两个独立事实:Media 包拥有那个切点,而 Screen Overlay 恰好覆盖了其中一些帧。作者+组合出的 `Impact` Fragment 可以从同一个 Moment 产出一个 Visual Track 和一个 Audio Track,但两个输出仍然是+进入 Film 的显式同级边。++## 7. Stacking++旧的固定 `z_index: 200` 规则被废弃。“Screen”描述的是全画布几何,不是某个魔法渲染阶段。每个 Present 都获得+一个显式的绝对 stacking 意图,Composition 把它与其他所有 Present 一同展平。++作者可以有意把暗角放在字幕之下、把闪光放在字幕之上,或者把颗粒放在两个图形层之间。包的 recipe 可以提供+方便的 stacking 默认值,但 Film 和 Composition 绝不会按包的家族做分支,也绝不会强行把它顶到最上层。++如果某个 overlay 包在不同的 stacking 位置发出多个 Present,同级 Track 可以按照扁平 Track 法则的要求在它们+之间交错。++## 8. 旧系统迁移审计++保留:++- 短促的 Moment 命中与长时段的 Program overlay;+- Selection、Moment 和绝对时间放置;+- 全画布的闪光、薄纱、暗角、漏光、颗粒、扫描线、散景和雪花视觉;+- 确定性的效果专属参数与局部包络;+- 多个效果同时存在;+- 可选的显式自有纹理或实体化的 alpha Surface。++废弃:++- 单例槽位语义;+- 固定的最顶层 z-index 和字幕之后的特殊渲染阶段;+- 把一个中心字符串算子注册表当作系统事实;+- 通用的 30% 峰值包络;+- 隐藏的 `backdrop-filter` 访问;+- 跨 Track 的 `mix-blend-mode`;+- 把屏幕命中假装成场景转场;+- 隐藏的泳道级进出音效;+- 任何 Base FX 对应物或占位实现。++## 9. Lowering 与验收++实现遵循共享的 Temporal 合同和既有的 Visual Track 合同:++1. **已实现:** 自描述的 `@narratage/screen-overlay` 作者包;+2. **已实现:** 十一个相互独立的带类型作者组件,而不是一个不做校验的口袋;+3. **已实现:** 精确的、无代码的 `svml.visual-ir@1` lowering;当未来某个组件无法被精确表达时,通用的带类型+ 自有 Surface 逃生口仍然可用;+4. **已实现:** 使用连接进来的 CanvasSpace 与 ProgramSpace,绝不使用 Film 全局量;+5. **已实现:** 普通的绝对 stack Present;+6. **已实现:** 每个组件与每种包络的确定性结构 / 帧测试;+7. **已实现:** 单 worker 与三 worker 的真实 Chromium 渲染产出完全相同的像素;+8. **已实现:** 多个 Overlay Track 按 stacking 键与同级 Track 交错;+9. **已实现:** 拒绝任何下层合成结果、兄弟 Track、backdrop-filter 或隐藏音频依赖的反例测试。++如果新增一个 overlay 需要在 Core 里加分支、在 Composition 里加家族、在 HyperFrames 里加组件开关,或者需要+对已合成像素做隐式快照,那么这个设计就是失败的。diff --git a/spec/script-surface.md b/docs/zh/guide/spec/script-surface.mdsimilarity index 99%rename from spec/script-surface.mdrename to docs/zh/guide/spec/script-surface.mdindex 602c86d5..cd38a9d2 100644--- a/spec/script-surface.md+++ b/docs/zh/guide/spec/script-surface.md@@ -1,3 +1,8 @@+---+title: SVML Script Surface+description: Script 作者面的规范性合同:Segment、Role Cue、Dual Text、Selection、Moment 与 Slot。+---+# SVML Script Surface> **Draft; not frozen.**diff --git a/docs/zh/guide/spec/spatial-layout.md b/docs/zh/guide/spec/spatial-layout.mdnew file mode 100644index 00000000..90669c82--- /dev/null+++ b/docs/zh/guide/spec/spatial-layout.md@@ -0,0 +1,438 @@+---+title: 共享 Spatial 布局+description: 共享 Spatial 几何的可执行基础权威。`@narratage/spatial`。+---++# 共享 Spatial 布局++状态:共享 Spatial 几何的可执行基础权威。`@narratage/spatial` 实现了 CanvasSpace、Frame/Point/Path、+IntrinsicExtent、ContentFit 以及纯粹的 fitting;Film 现在消费与 Track 布局完全相同的显式 CanvasSpace。+Text、Media 以及四个 Ranking witness 均可执行,仓库内部的 Visual IR 兼容性审查已通过。公开的包 ABI+发布仍然是另一件事。++## 1. 结论++共享 spatial 系统拥有的是坐标几何,而不是 Text、Media 或 CSS。它的稳定词汇是:++```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+```++当一个可视组件消费某个 `SpatialFrame` 时,该 frame 扮演的角色是它的 **Placement Frame**:组件被摆放+在哪里,以及 frame 级别的 Paint 可以存在于哪里。随后每一个实际的 text/media 样本都会依据自身的固有尺寸和+一个 `ContentFit` 推导出各自的 **Content Frame**。++这就是那两个 frame。它们并不总是嵌套关系:++```text+contain cover++Placement Frame Content Frame+┌──────────────┐ ┌──────────────────┐+│ ┌────────┐ │ │ ┌────────────┐ │+│ │Content │ │ │ │ Placement │ │+│ │ Frame │ │ │ │ Frame │ │+│ └────────┘ │ │ └────────────┘ │+└──────────────┘ └──────────────────┘+```++因此把第二个称作“内框”是错误的。在 `cover`、缩放或局部运动之下,Content Frame 可能超出 Placement+Frame。++一个 Placement Frame 可以包含若干个显式样本。纯色底衬没有 Content Frame。一个模糊样本和一个前景样本各自+拥有独立的 Content Frame,即使它们引用同一个 Artifact。不存在被所有图层共享的那种全局唯一“内框”。++## 2. 边界++聚焦的视频领域包是 `@narratage/spatial`。它拥有纯类型、validator、面向可复用几何的作者 Surface 以及确定性+的几何 Producer。它不拥有:++- 时间窗口或媒体的固有播放行为;+- 文字折行或字形测量;+- 媒体解码、流选择或容器旋转;+- 背景、模糊、不透明度、颜色、描边或阴影;+- z-order、转场或局部运动;+- Composition、Runtime、Provider 或 Core 的行为。++这些事实只通过图的边与 Spatial 相遇。例如,Media Inspection 选定一路可视流并产出其面向显示的 extent;+某个 Media 包再显式地把该 extent 转换成 `IntrinsicExtent`,交给 Spatial 做 fitting。Spatial 永远不会打开+一个 MP4,也不会猜测哪一路流是主流。++安装或修订这个包不得改变 Core。Core 看到的只是普通的带类型 Record 和 Operation。++## 3. CanvasSpace++`CanvasSpace` 在任何 Track 被撰写之前就确立了精确的坐标系:++```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";+};+```++宽和高是正整数。颜色、clear Paint、帧率和时长不是空间事实,都留在这个值之外。++Canvas 必须先于 Track 声明,随后作为同一个图上的值连接到 Film/Composition。当前的 Film Surface 把宽高藏在+最终的 Film 声明内部,这对精确的 Text 和 Media 布局来说太晚了。它的重写必须把 Canvas 声明与最终的 Track+装配分开,而不是把宽高复制进每一份 Track Recipe。++预期的源码形态是:++```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>+```++精确的 Surface 写法仍处于冻结前状态。单值数据流是规范性的。++## 4. SpatialFrame 的构造++一个已解析的 `SpatialFrame` 是 Canvas 像素坐标系中的有限矩形:++```ts+type SpatialFrame = {+ readonly contract: "svml.spatial-frame@1";+ readonly xPx: number;+ readonly yPx: number;+ readonly widthPx: number;+ readonly heightPx: number;+};+```++宽和高必须为正。`xPx` 与 `yPx` 可以为负,也可以延伸到 Canvas 之外。画布外的 Frame 对进出场运动很有用,+不得被悄悄 clamp、求交或拒绝。哪些像素可见由 Canvas 光栅化决定。Clamp 永远是一次显式的投影选择。++作者输入可以使用相对 Canvas 的百分比或像素。它们会在消费者布局其内容之前编译成这一种已解析形式。百分比相对+的是显式连接的父 Frame 的宽/高,而不是渲染器碰巧创建的某个 DOM 容器。++三个作者组件在不需要 mode 字段的前提下覆盖了常见的构造语义:++1. `Frame`:在父 Canvas/Frame 内部的四条显式边;+2. `AnchoredFrame`:一个目标点、一组宽/高,以及九个自身锚点之一;+3. `AspectFrame`:一个目标点、一个主尺寸,以及一个显式给出或连接进来的宽高比。++概念上:++```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` 不代表一个可见的盒子。它只产出几何。`AspectFrame` 可以消费一条通用的 `IntrinsicExtent` 边;它不+依赖 Media。++九个规范锚点名是:++```text+top-left top-center top-right+middle-left center middle-right+bottom-left bottom-center bottom-right+```++编译后的数学是点吸附,而不是九套硬编码的布局算法:++```text+frame.x = target.x - frame.width × selfAnchor.x + offset.x+frame.y = target.y - frame.height × selfAnchor.y + offset.y+```++每个具名锚点不过是一对可读的 `(0 | 0.5 | 1, 0 | 0.5 | 1)`。更高级的 Surface 可以暴露任意归一化锚点,而不必+改变编译后的合同。++安全区、左栏、标题区和商品区都是从 Canvas 或父 Frame 派生出来的普通具名 Frame。它们不是保留的全局 token。++## 5. IntrinsicExtent++`IntrinsicExtent` 是保持内容形状所需的最小通用事实:++```ts+type IntrinsicExtent = {+ readonly contract: "svml.intrinsic-extent@1";+ readonly widthPx: number;+ readonly heightPx: number;+};+```++这两个值是内容面向显示的、为正的自然像素 extent。`contain`、`cover`、`fit-width`、`fit-height` 和+`stretch` 只需要它们的比值;`native` 和 `scale-down` 还会用到它们与 Canvas 像素的绝对关系。Media 可以在应用+容器旋转和 sample aspect 信息之后推导它们。Text 可以从精确的字体排版推导它们。矢量组件必须选择一个显式的+标称光栅 extent,而不是假装任意的 view-box 单位就是 Canvas 像素。它们都不会把源 Artifact、字体、组件族或+上游摘要存进 `IntrinsicExtent`;这些关系仍然显现在图的边与 Derivation 上。++## 6. ContentFit 与两个 frame 的方程++`ContentFit` 选择尺寸策略、对齐方式,以及一个可选的对齐约束:++```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";+};+```++两个点都在各自的 Frame 内归一化。`framePoint` 说明所选的内容点想落在 Placement Frame 的哪个位置。+`contentPoint` 说明源上的哪个固有点是重要的。这比旧的单一 `focalX/focalY` 更有表达力 —— 后者在两边悄悄用了+同一个坐标。两个点的坐标都必须落在 `[0,1]`;有意超出该范围的位移使用 `offsetPx`,当结果必须留在范围之外+时使用 `constraint="free"`。++给定 Placement Frame `(Vx, Vy, Vw, Vh)` 和固有 extent `(Sw, Sh)`,保持宽高比的基础缩放为:++```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)+```++对这些模式:++```text+Cw = Sw × scale+Ch = Sh × scale+```++`stretch` 有意放弃源宽高比,产出 `(Cw, Ch) = (Vw, Vh)`。它之所以是显式的,是因为成熟的编辑器允许形变;其他+任何尺寸模式都不得形变。++约束之前:++```text+Cx = Vx + Vw × framePoint.x - Cw × contentPoint.x + offset.x+Cy = Vy + Vh × framePoint.y - Ch × contentPoint.y + offset.y+```++对 `free` 而言,这些坐标就是最终结果。对 `bounded` 而言,每条轴按同一条法则做最小限度的 clamp:++- 内容较小时,让完整的 Content Frame 留在 Placement Frame 内部;+- 内容较大时,让完整的 Placement Frame 被 Content Frame 覆盖。++对水平轴来说这意味着:++```text+Cw <= Vw: clamp Cx to [Vx, Vx + Vw - Cw]+Cw >= Vw: clamp Cx to [Vx + Vw - Cw, Vx ]+```++垂直方向的法则完全相同。这支持了真正的焦点摆放,比如“源上的 `(0.8, 0.35)` 这个点应当出现在 Frame 的中心”,+同时不会允许意外露出未被覆盖的边条。++常见的九种对齐只是 `framePoint === contentPoint` 时的简写。居中 contain 和居中 cover 两边都是 `(0.5, 0.5)`。+`top-left` 两边都是 `(0,0)`。如果作者刻意要让内容跑到外面,或者刻意让 Placement Frame 不被完全覆盖,就选择+`free`;Runtime 绝不替他做这个创作决定。++`FittedContent` 只包含推导出的 Content Frame,不重复上游血缘:++```ts+type FittedContent = {+ readonly contract: "svml.fitted-content@1";+ readonly contentFrame: SpatialFrame;+};+```++当需要裁剪到 Placement Frame 时,对应的源采样窗口是由 Placement Frame 与 Content Frame 的交集机械推导出来+的。它不是第三个由作者撰写的盒子。fit 之后的旋转或透视变换可能让采样边界不再是矩形,因此要放在这层基础布局+之后应用。++## 7. Fit 不是运动,也不是占用++一次 fit 计算产出的是基础 Content Frame。缩放、平移、旋转、透视和入场运动会在之后对该结果做变换。它们不会+改动 `ContentFit`,也不会改动源宽高比。++这避免了旧有的歧义:`zoom` 被塞进 `contain`/`cover` 里,从而可能悄悄让所声明的 fit 不再成立。如果一段 Ken+Burns 运动把一张 contain 的图片缩放到发生裁切,基础 fit 仍然是 `contain`,裁切是由之后的变换显式造成的。++Spatial 的尺寸策略与固有时间占用也毫无关系。一段视频可以在空间上是 `contain`,同时在时间上播放一次、循环或+拉伸。一张图片并不会仅仅因为它有固有的空间 extent 就获得某种固有的时间播放模式。++## 8. 裁剪与 frame 形状++Spatial 几何从不决定 Placement Frame 之外的像素是否可见。消费该几何的组件拥有显式的裁剪策略:++```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+```++圆角半径、椭圆/路径蒙版、描边和阴影属于表现,不属于坐标。Text 的辉光完全可以合理地溢出它的 Placement+Frame;Media 卡片通常会把每个局部样本都裁剪到同一个圆角 Placement Frame。Runtime 不会根据内容类型推断出任何+默认值。++自有形状只能裁剪同一个组件贡献内的元素。它不能蒙版或采样另一个同级 Track。++## 9. 透明、纯色、模糊与替代底衬++Placement Frame 中未被 Content Frame 绘制的区域本身不具备空间语义。Media/Text 的表现层提供的是一组有序的、+显式自有图层。++### 透明++不产出任何底衬图层。透明像素会在 Composition 时自然露出更低的 Track。这不是跨 Track 采样:该 Track 在那里+根本没有贡献像素。++### 纯色或渐变++一个 frame Paint 图层填满 Placement Frame。它没有源输入、没有 IntrinsicExtent、也没有 Content Frame。++### 同源的模糊副本++同一个源被显式地第二次连接进来,成为另一个局部样本:++```text+same source Artifact ─┬─> cover ContentFit -> blur/tone -> backing layer+ └─> contain ContentFit -> foreground layer+```++两个样本共享同一个 Placement Frame,但拥有各自独立的 Content Frame 和效果。Artifact 收集会对完全相同的字节+去重;渲染仍然执行两次显式采样。模糊实现必须在裁剪之前做边缘扩展/超采,以免高斯核造出非预期的透明或发暗+边框。++### 另一张图片或另一段视频++替代源通过自己的图边进入,并获得属于自己的 Inspection、IntrinsicExtent、ContentFit,对于有时长的媒体还包括+占用策略。它不是藏在某个 Style Recipe 里的字符串路径。++因此通用的 Media 作者模型是有序的局部图层,而不是特殊的 `foreground/background` 字段:++```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>+```++把第二个源换成另一张图片,表达的就是替代底衬。删掉前两个子节点,表达的就是透明底衬。当需要与同级 Track+交错时,每个图层都可以下降为自己的绝对堆叠 Present;作者层的 Track 绝不会变成隐式的堆叠上下文。++完整的 Item/Sequence 作者模型见 [`media-track.md`](./media-track.md)。独立的深度堆叠集合模型见+[`deck-track.md`](./deck-track.md)。两者都复用显式图层与边的法则,而不会把 Deck 变成 Media 的一种模式。++### 仍然被禁止的做法++对已经累积出来的 Composition 施加 `backdrop-filter` 不属于上述任何一种情形。那会让结果依赖于任意的下层+Track。要模糊另一个视觉物,组件必须显式接收那个视觉/媒体。要模糊一个已完成的下层合成,必须由更高阶的组件先+显式拥有并物化那个合成。++## 10. Text、Ranking 与 Caption 的用法++Spatial 提供公共几何,同时不强加单一布局模型:++- Point Text 消费一个 `SpatialPoint`,并从精确的文字 extent 推导其 Content Frame;+- Area Text 消费一个 Placement Frame,然后在其内部执行包自有的段落排流;+- Path Text 消费一条显式的 `SpatialPath`;+- Media 消费一个 Placement Frame,并为每个样本推导一个 Content Frame;+- Ranking 消费一个 Placement Frame,并在其内部拥有 board、slot 和暂存区布局;+- Comment Sticker 消费一个 Placement Frame,并拥有自己的头像/文字/内部布局;+- Caption 可以消费一个 Placement Frame,但 Cue/Atom 的折行仍归 Caption 所有。++Text 的布局盒和 Media 的 Content Frame 并不会仅仅因为都是矩形就成为同一个语义 Type。它们可以使用同样的纯几何+辅助函数,同时各自仍然是包自有的已解析事实。++## 11. 图数据流与不传播元数据++```text+CanvasSpace + Frame Projection+ │+ ▼+ SpatialFrame ───────────────────────────────┐+ │+Media Inspection -> display extent -> IntrinsicExtent│+ ├─> fit -> FittedContent+authored ContentFit ─────────────────────────────────┘ │+ ▼+ package Paint/motion/clip -> VisualTrack+```++每一条依赖都是图上的一条边。`BlobArtifact` 不会长出摆放字段。`SpatialFrame` 不会长出源、角色、时间或+Artifact 摘要。`VisualTrack` 不会长出 `focal`、B-roll 或 Text 字段。亲和性由多输入的 fitting/lowering+Operation 校验,而不是靠把血缘元数据复制到每一个值上。++## 12. 保留与废弃的历史结论++保留:++- 归一化的作者摆放,以及感知源宽高比的锚定摆放;+- 相互独立的源 fitting 与时间占用;+- contain、cover、fit-width 和 fit-height 的方程;+- 相互独立的前景采样与底衬采样;+- 源焦点对齐与显式吸附点;+- 可选的透明、纯色和自身模糊底衬;+- 叠加在采样/摆放之上的局部运动。++废弃:++- 把区域、VLM 推断、避让、路径信号和固定盒子混在一起的联合体 `SpaceLocator`;+- 把九宫格代号当作彼此独立的算法;+- 用同一份 `focalX/focalY` 同时充当源点和目标点;+- `MediaBoxStyle` 把“恰好一个前景加一个特殊底衬”当成通用模型;+- 把 zoom 嵌进 fit;+- 把渲染器专属的 CSS 与 FFmpeg 公式当成两份真相来源;+- 隐式的 `object-fit`、`object-position` 或 `backdrop-filter` 默认值。++## 13. 实现与验收顺序++1. **已实现:** 新增聚焦的 `@narratage/spatial` 包,含 `CanvasSpace`、Frame/Point/Path、+ `IntrinsicExtent`、`ContentFit` 以及纯粹的 fit 校验;+2. **已实现:** 把 Canvas 声明从 Film 装配中拆出,并把同一个 Canvas 值连接到 Track 布局与 Composition;+3. **已实现:** 让一个简单的 Text Area 和一张简单的 Media 静态图片走通共享几何;+4. **已实现:** 为每一条 fit 与对齐法则补上精确的浏览器测试;+5. **已实现:** 验证有序的 透明/纯色/自身模糊/替代源 Media 图层;+6. **已实现:** 让四个 Ranking 组件全部走显式的共享 Frame;Comment Sticker 在拥有自己的设计之前继续搁置;+7. 只有到这时才冻结 Spatial 的 Type 以及相关的 Visual IR 行为。++测试矩阵必须包含:++- 竖版、横版和方形的固有 extent,分别对上竖版、横版和方形的 Frame;+- 每一种尺寸模式,包括显式形变与 scale-down;+- 全部九种等点对齐,外加源/frame 焦点不相等的情形;+- bounded 与 free 对齐的对比;+- 为负的、部分越界的以及完全在画布之外的 Placement Frame 与 Content Frame;+- 父 Frame 百分比与像素偏移;+- 在进入 Spatial 之前已归一化的源旋转/sample aspect;+- 透明、纯色、同源模糊,以及替代图片/视频图层;+- 相互独立的底衬 Content Frame 与前景 Content Frame;+- 由所选渲染器实现锁定的取整/光栅行为;+- 共享 Type 中不存在 Core、Runtime、Film 族、Text 族或 Media 族的判别字段。++纯几何矩阵与真实 Chromium witness 现已覆盖每一种尺寸模式、全部九种等点对齐、不相等的 bounded/free 焦点,+以及部分/完全越出 Canvas 的 Frame。Media 归一化还会在推导 `IntrinsicExtent` 之前,把容器旋转和非方形 sample+aspect 物化成方形像素的视觉。Ranking 现在消费同样的显式 Frame 几何,且没有增加族判别字段。最终的 Visual IR+兼容性审查现已通过;Spatial 自己的作者 Surface 仍处于预发布状态,在此期间不应再生长出任何包内局部的百分比+词汇。diff --git a/docs/zh/guide/spec/track-authoring.md b/docs/zh/guide/spec/track-authoring.mdnew file mode 100644index 00000000..e186b6c3--- /dev/null+++ b/docs/zh/guide/spec/track-authoring.md@@ -0,0 +1,420 @@+---+title: SVML 视频 Track 作者模型+description: 官方 Track 包共享的可执行时间权威。聚焦的。+---++# SVML 视频 Track 作者模型++状态:官方 Track 包共享的可执行时间权威。聚焦的 `@narratage/temporal` 包实现了严格的 occurrence 展开、+精确的有理数窗口投影,以及触发式的同级排程。共享的 Spatial、Text、Ranking、Media、Audio 和 Screen Overlay+现已分别在 [`spatial-layout.md`](./spatial-layout.md)、+[`typography-track.md`](./typography-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) 和+[`screen-overlay.md`](./screen-overlay.md) 中给出规范。独立设计的+`@narratage/comment-sticker` 包现在使用同一套 Temporal 与 Spatial 基础,并下降为一个同级 VisualTrack。+这里刻意不构成对已发布公开 ABI 的兼容承诺。++## 目的++官方视频包需要一套共享的纪律,但不需要一个万能的 Track Program。Text、Media、Ranking 和 Comment Sticker+拥有各不相同的作者语义,但它们不得各自发明互不兼容的方式来回答同样的时间问题。++本文管辖的是包级 Program 及其确定性下降。它不会给 Core、Runtime、Composition 或某个 Provider 增加视频语义。+公开的终端窄腰仍然是 [`VisualTrack` 和 `AudioTrack`](./track-composition.md)。++完整的包作者关注点分离是:++```text+content+temporal source+occurrence expansion+window projection+optional sibling sequencing+intrinsic-material occupancy+spatial source and layout+presentation+```++这些是相互独立的作者关注点,不是每个包都必须填写的字段,也不是公开 Track 合同上的字段。++## 1. 时间流水线++```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+```++各层回答的是不同的问题:++| 层 | 问题 |+|---|---|+| anchor location | 某个作者写下的锚点位于哪一个物理帧? |+| occurrence expansion | 一个作者项恰好消费一个 occurrence,还是消费每一个 occurrence? |+| window projection | 这个 occurrence 可以占用哪一段 ProgramSpace 区间? |+| sibling sequencing | 相关的项之间如何交接、重叠或彼此关闭? |+| occupancy | 一个带固有时长的产物如何在自己的最终窗口内对自身采样? |++任何 `full`、`fixed`、`relative`、`from`、`until`、`fill` 或 `fit` 联合体都不得再次把这些层压平。作者+Surface 可以提供可读的简写,但它必须下降到这个分离后的模型。++## 2. Temporal source 提供的是点,不是可渲染的窗口++一个 Selection occurrence 贡献一对有序的已定位点:++```ts+type LocatedSelectionOccurrence = {+ readonly id: string;+ readonly start: FramePoint;+ readonly end: FramePoint;+};+```++一个 Moment occurrence 贡献一个已定位点:++```ts+type LocatedMomentOccurrence = {+ readonly id: string;+ readonly cue: FramePoint;+};+```++Program source 是一个单例 occurrence。每个投影环境还拥有 `program.start` 和 `program.end` 这两个精确的+ProgramSpace 边界。++Selection 的定位必须保持 Script 中的 occurrence 顺序,以及两个作者锚点各自的身份。它不得对这些点排序、+合并、裁剪、互换或取绝对差值。一个 `end` 早于 `start` 的已定位 Selection 仍然是有效的点证据。只有消费者才会+创建窗口,因此只有投影层才能判定它实际消费的那些点是否构成有效区间。++组件自有的精确时间产物,比如已经定好时间的 Caption Cue,可以直接进入后面的帧窗口阶段。它不需要假装自己的+时间来自某个 Narrative Selection。++## 3. 点表达式与 Temporal Window Projection++共享的投影代数在概念上是:++```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;+};+```++序列化合同将为时长使用显式单位。秒、毫秒和整数帧是三种不同的作者输入;换算到有理数 ProgramSpace 必须有唯一的+确定性边界量化规则。`base_start` 和 `base_end` 是被废弃的名字,因为当前架构没有享有特权的 Base Track。++常见的作者语义都只是普通表达式:++| 语义 | 投影 |+|---|---|+| 整个 Program | `[program.start, program.end]` |+| 恒等 Selection | `[selection.start, selection.end]` |+| 从 Selection 开始起三秒 | `[selection.start, selection.start + 3s]` |+| Selection 结束之后三秒 | `[selection.end, selection.end + 3s]` |+| 从 Selection 开始一直持续 | `[selection.start, program.end]` |+| 提前两秒引入到 Selection 开始 | `[selection.start - 2s, selection.start]` |+| 某个 Moment 之后三秒 | `[moment.cue, moment.cue + 3s]` |+| 最开始的三秒 | `[program.start, program.start + 3s]` |+| 绝对时间的高级窗口 | `[absolute(2.5s), absolute(6s)]` |++`full`、`manual`、`fixed` 和 `relative` 可以继续作为创作 UI 里的表现用词,但它们不是彼此不同的编译期时间法则。++### 语义绑定可以刻意忽略局部坐标++作者可以把一个项绑定到覆盖开场几个词的 Selection,同时把它投影到 `[program.start, program.start + 3s]`。+即使该投影没有用到 Selection 已定位的 start/end 坐标,这个 Selection 仍然贡献了作者语义、occurrence 身份、+基数和依赖真相。++这在 `one` 之下是合法的。如下文所定义,它在 `each` 之下被刻意限制,因为重复一个与 occurrence 无关的投影只会+制造出一模一样的窗口。++## 4. Occurrence 展开是严格的,且先于投影++旧的形态 `{ kind: "single", cardinality: "exactly_one" }` 把同一个事实说了两遍。可执行的合同只有两个互不重叠+的选项:++```ts+type OccurrenceExpansion =+ | { readonly kind: "one" }+ | { readonly kind: "each" };+```++`each` 指的是编译期展开,不是媒体循环。作者 Surface 通过各自显式的 occurrence 设置暴露它,并下降为这个精确的值。++### `one`++`one` 遵循如下精确法则:++1. 定位完整的源 occurrence 集合;+2. 在求值投影之前,要求其基数恰好等于一;+3. 拒绝零个或多于一个的 occurrence;+4. 绝不选择 `first`、`last`、`best`、最近或最早者;+5. 把那唯一的 occurrence 恰好投影一次。++忽略 Selection/Moment 坐标的投影通常与 `one` 搭配。仅依赖 Program 的时间使用固有的单例 Program source,因此+同样下降为 `one`,且不需要作者可见的基数设置。++### `each`++`each` 遵循如下精确法则:++1. 要求至少有一个已定位的源 occurrence;+2. 保持源 occurrence 的身份与源顺序;+3. 为每一个源 occurrence 恰好实例化一个投影后的 occurrence;+4. 在每个 occurrence 各自的局部点环境中独立求值同一个投影;+5. 由作者项 id 与 occurrence id 推导稳定的结果身份,绝不使用偶然的排序下标;+6. 绝不合并、去重、按时间排序、挑选优胜者或悄悄丢弃某个 occurrence;+7. 只要有任何一个 occurrence 无法产出有效窗口,就让整个确定性 Operation 失败。++当源 occurrence 多于一个时,投影的两个边界中至少有一个必须引用局部点(`selection.start`、`selection.end`+或 `moment.cue`)。只使用 Program 点或绝对点的投影与 occurrence 无关,在 `each` 之下会被拒绝:它会造出若干+语义不同、物理窗口却完全相同、彼此毫无时间区分的实例。作者应当改用 `one`、绑定 Program 单例,或分别写出显式+的多个项。++投影是一对一的。一个 occurrence 不能扇出成多个窗口。想从一个 Selection 或 Moment 得到两个窗口的作者,要么写+两个项,要么使用一个显式构造这两个项的包自有组件。++集合聚合不是第三种通用展开模式。可见性掩码或另一个确实以集合为值的组件,可以定义包自有的集合消费者,但普通的+可视项不得借这个例外找回隐式的合并、并集或去重行为。++Caption 的 `Mute` 是一个具体的包自有例子。它在 `CaptionProgram` 内部对显式引用的+`CaptionDisplayWordSubset` 取并集;它不改变通用的 occurrence 展开,不制造投影窗口,也不进入 Core。++### 基数不决定重叠++`each` 只说明一个 occurrence 集合如何展开。它不说明产生的窗口是否可以重叠、相邻窗口是否应当合并,也不说明+某个项是否应当在下一个项的 cue 处关闭。这些问题在投影之前无法回答,而且还可能取决于包的语义。++投影之后,消费方的包必须为自己的组件选择并校验一种显式关系,例如:++- `independent`:重叠的窗口是有意义的,彼此保持独立;+- `disjoint`:同一个作者项的各 occurrence 之间出现任何重叠都是错误;+- 由包自有的 Sequence 或 Deck 策略推导最终的同级窗口与交接。++这种关系不属于 `OccurrenceExpansion`,也不由 Core 拥有。官方的简单 Text、Comment Sticker 以及类似的重复项,+通常应当要求投影窗口互不相交。Media 组、Ranking 组件可以拥有更强的显式同级规则。任何包都不会获得隐藏的全局+自动拼接行为。++### 触发式阶段属于同级排序,不是另一种 temporal source++Ranking、Tier、幻灯片以及其他渐进式组件,往往只有一组有序的触发 Moment。到达触发点 `i` 就进入状态 `i`;+到达触发点 `i + 1` 就交接给下一个状态。这种情况使用的是同一套点定位与窗口投影。它不构成在 Core 里引入 `Stage`+Type 或再加一种 Script 标记的理由。++仅有 `N` 个触发点无法界定 `N` 个有限阶段:最后一个阶段仍然需要一个终止边界。因此触发式组件拥有一个显式的外层+窗口 `[B, O)` 和一个显式的阶段终止点 `T`。`T` 可以引用 `O`,但包不得默认它一定如此。把两者分开,可以让 Ranking+组件在 `T` 处结束最后一项,并让完全落定的 board 一直可见到 `O`。给定已定位并已量化到帧的触发点+`p1 ... pN`,包可以推导出:++```text+stage 1 [p1, p2)+stage 2 [p2, p3)+...+stage N [pN, T)+settled suffix [T, O) (when T < O)+```++`p1` 之前的区间是非活动的,而不是隐式的第零阶段。如果某个设计需要一个从外层起点到 `p1` 的初始可见状态,那个+状态必须显式写出,并会产生 `N + 1` 个阶段。渲染器绝不能因为存在 board 或背景就推断出它。++这个模式有两种相关但不同的包自有下降方式:++```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+```++累积形态就是对 `[moment.cue, outer.end]` 做普通的 `each` 投影,外加一条显式的重叠策略。它天然实现了 Tier+board:`p2` 之后,第 1 项和第 2 项同时处于活动状态;可见的前缀本身就是当前的逻辑状态。不需要物化任何 board+快照。++互斥形态从同样的候选出发,再施加一条后继交接策略:每个候选的最终结束成为下一个候选的开始,最后一个在 `T` 处+结束。这可以驱动一个 Ranking 暂存区,让它恰好展示一个当前项,同时已落定的项作为独立的累积前缀保留。当+`T < O` 时,后缀没有当前项,展示的是完成状态。包可以把这两个视图下降为同一个同级 `VisualTrack` 中相互独立的+Present。++触发式排序遵循如下精确法则:++1. 保持作者/源的 occurrence 顺序与稳定的 occurrence 身份;+2. 绝不按物理时间对触发点排序;+3. 要求至少一个触发点、一个显式外层窗口和一个显式阶段终止点;+4. 在帧量化之后,要求 `B <= p1 < p2 < ... < pN < T <= O`;+5. 原子性地拒绝逆序触发点、同帧碰撞、落在外层窗口之外的触发点,以及位于 `T` 处或其之后的最后一个触发点;+6. 只有当组件合同明确这样规定并要求基数相等时,才把有序的项列表与触发 occurrence 逐一对齐;+7. 由作者项身份与 occurrence 身份推导项/阶段身份,绝不使用数组下标;+8. 把累积重叠或后继交接保持为已声明的包语义,绝不交给 Runtime 选择。++包也可以为每个子项各配一条单 occurrence 的 Moment 边。两种作者写法都下降为同样的有序同级候选;按位置对齐不是+隐式的全局行为。除非另有组件确实需要消费它们,触发式阶段只是内部的确定性下降事实。Composition 收到的仍然只是+普通的 Present。++## 5. 投影校验与负区间++对每一个展开后的 occurrence,投影按如下顺序执行:++1. 在精确的有理数 ProgramSpace 中求值原始 start 和原始 end;+2. 拒绝缺失、非有限或类型非法的点表达式;+3. 若原始 end 早于原始 start,在裁剪之前就拒绝这个逆序窗口;+4. 若原始 end 等于原始 start,拒绝这个零长度渲染窗口;+5. 把方向正确的原始窗口与 `[program.start, program.end)` 求交;+6. 确定性地把它量化为半开的整数帧跨度;+7. 拒绝空结果或短于一帧的结果;+8. 只返回完全落在 ProgramSpace 之内的 `{ startFrame, endFrameExclusive }` 值。++裁剪到 ProgramSpace 是与唯一可观测渲染域求数学交集,而不是猜测时间。因此中间出现负值的点是允许的:++```text+cue = 1s+[cue - 3s, cue + 2s] = [-2s, 3s]+intersection [0s, 3s]+```++原始的逆序区间绝不能被裁剪、排序或取绝对值掩盖过去。完全落在 ProgramSpace 之外的区间会变成空并失败;它不会+被悄悄略过。渲染器只收到已经校验过的帧跨度,不做任何时间修补。++Selection 的一对交叉锚点本身并不构成投影失败。恒等投影 `[selection.start, selection.end]` 在产出逆序窗口时+失败,而 `[selection.start, program.end]` 可以依然有效,因为它并不消费那个交叉的结束点。++## 6. 固有时长与占用++每一个被呈现的产物,要么拥有已验证的固有时长,要么没有。未知时长不得冒充其中任何一种;媒体检查必须先确定它,+基于固有时长的占用策略才能执行。++无时长产物 —— 例如 Text、静态图片、Comment Sticker 和普通的 Ranking UI —— 占满自己最终投影出的整个窗口。+局部的入场、出场和循环动画属于该窗口内部的表现,不是合成出来的素材时长。++带固有时长的产物会收到一个最终允许窗口和一条显式播放策略。概念上的可视策略是:++```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` 取代了含义含糊的旧词 `finish`。end 对齐绝不表示倒放。它表示正向播放的源在投影窗口的结束处结束。如果源+比窗口长,start 对齐取源的头部,end 对齐取源的尾部。++| 策略 | 源短于窗口 | 源长于窗口 |+|---|---|---|+| `once/start` | 从窗口开始播放,随后消失 | 播放源的头部直到窗口结束 |+| `once/end` | 延迟出现,并在窗口结束处结束 | 播放源的尾部,并在窗口结束处结束 |+| `hold/start` | 播放完后保持最后一帧 | 播放源的头部直到窗口结束 |+| `hold/end` | 先保持第一帧,再播放到窗口结束 | 播放源的尾部直到窗口结束 |+| `loop/start` | 从源头部相位开始重复 | 循环到放不下时裁掉 |+| `loop/end` | 选择使源尾部落在窗口结束处的循环相位 | 同样的尾部相位法则 |+| `stretch` | 把源的全部时间放慢塞进窗口 | 把源的全部时间加快塞进窗口 |++Audio 必须在同一套排程之上定义自己如实的词汇。它不能像视频帧那样把一个 PCM 采样保持住。一次性音频之外是静音,+补齐必须显式,循环就是循环,拉伸必须遵守作者声明的速度上下限。静态图片和无时长 UI 不接受无意义的固有播放模式。++源的 trim 与源入/出点在被加入后,作用于占用之前,用来定义有效的固有源区间。Spatial 的 contain/cover 和 Text+的 flow/shrink 作用于时间占用之后,与之无关。++## 7. 包的归属++原先那个大一统的 `contracts` 包被有意取消。名义上的共享语义由 Narrative、ProgramSpace、Media 和 Composition+等聚焦模块各自拥有;Core 没有任何视频领域联合体的注册表。++本文中的时间代数由聚焦的视频领域包 `@narratage/temporal` 实现。它拥有投影类型、validator 以及纯粹的帧窗口+投影。它可以消费 Narrative 的点引用、SemanticMap 定位和 ProgramSpace,但它不得知道 Text、Media Track、+Ranking、Comment Sticker、Film、HyperFrames、Runtime 或某个 Provider。++官方包随后都使用同一份实现:++```text+Text ───────────────┐+Media Track ────────┤+Deck Track ─────────┤+Ranking ────────────┼─> @narratage/temporal ─> frame windows+Comment Sticker ────┤+Screen Overlay ─────┤+Audio Track ─────────┘+```++Caption 那份组件自有的定时 Cue 投影可以直接进入最终的帧窗口阶段。Speech Spine 确立 ProgramSpace 和连续的语音+take。其他 Track 可以通过两个结构锚点直接寻址整个 Narrative Segment,而不必假装它是一个作者写下的 Selection。++## 8. 迁移影响++当前的 `typography-track` Surface 使用共享时间包来处理 Program、Selection 和 Moment 绑定、显式点表达式,以及+`one`/`each` 展开。它不再维护第二套时间枚举。Media Track 用同一个包处理 Item 与 Sequence 的时间。++可执行的验收覆盖包括:++- Selection 与 Moment 的 `one` 成功用例及基数失败用例;+- Selection 与 Moment 的 `each`、稳定的 occurrence 身份以及源顺序的保持;+- 拒绝在多 occurrence 情况下使用与 occurrence 无关的 `each` 投影;+- 所有常见的点表达式组合,包括 Program 边界和绝对时间;+- 交叉的源锚点在不同投影下分别被消费和被忽略;+- 负偏移、ProgramSpace 求交、完全越界的窗口、逆序窗口、零长度窗口以及一帧的最小长度;+- 有理数帧率与确定性的半开帧量化;+- 多个 `each` occurrence 中有一个非法时的原子失败;+- 包自有的 disjoint、independent 和 sequence 关系与展开保持相互独立;+- 累积式与后继交接式的触发序列,包括显式终止边界、同帧碰撞、非单调的源顺序、稳定身份以及可选的显式初始状态;+- 无时长产物,以及在每一种受支持的播放与对齐策略下更短/相等/更长的固有时长产物;+- 显式的音频行为,而不是复用视觉的 `hold` 语义。++## 9. Ranking 的特化++完整的 Ranking 审查、组件拆分、组排程和可执行迁移见 [`ranking-track.md`](./ranking-track.md)。Ranking 现已+验证:通用的时间代数足以支撑累积状态、互斥的当前阶段以及最终的落定后缀,而无需向 Core 或公开 Track 合同引入+Ranking 或 `Stage` 语义。++## 10. 迁移状态++Comment Sticker 的内容、布局与表现已作为独立的作者包实现;它只共享通用的 Temporal、Spatial 和终端 VisualTrack+词汇。目前已规范的 Track 家族中,没有任何一个仍被这套通用作者模型卡住。++对目前已规范的每一个官方 Track 包,已实现的验收矩阵证明 Text、Caption、Media、Deck、Ranking 和 Screen Overlay+都下降为同级 VisualTrack 值,而通用 Audio 以及可选的 Media/Ranking 声音都下降为同级 AudioTrack 值,且不改动+Core 或 Composition。++通用 Audio Track 和自包含的 Screen Overlay 现已分别在 [`audio-track.md`](./audio-track.md) 和+[`screen-overlay.md`](./screen-overlay.md) 中单独规范。Audio 复用同一套时间代数,但拥有如实的采样占用语义,+而不是视觉上的 hold 语义。Screen Overlay 是一份满画布的同级贡献,不是跨 Track 的调整图层。++统一的 Item/Sequence Media 创作、全部运动通道、内部交接、显式音频投影以及 Speech Spine 受限的复用,现已在+[`media-track.md`](./media-track.md) 中规范。旧的深度堆叠 Deck 是一个独立的高阶 Track 组件,见+[`deck-track.md`](./deck-track.md)。B-roll 是一种剪辑用的 Recipe/用法,而不是另一个公开的 Track 家族。diff --git a/docs/zh/guide/spec/track-composition.md b/docs/zh/guide/spec/track-composition.mdnew file mode 100644index 00000000..3cfef70e--- /dev/null+++ b/docs/zh/guide/spec/track-composition.md@@ -0,0 +1,118 @@+---+title: SVML Track 与 Composition+description: 可执行的仓库内部 `@1` 兼容窄腰;所有门禁均已通过。+---++# SVML Track 与 Composition++状态:可执行的仓库内部 `@1` 兼容窄腰;[`track-expressiveness.md`](./track-expressiveness.md) 中的所有门禁+均已通过,公开发布仍然是另一件事。++## 法则++除了共享的 ProgramSpace 与画布几何之外,进入 Composition 的每一份视听贡献都是同级 Track。Composition 负责+校验、排序和合并 Track。它不认识 Caption、Speech、Media、Text、Seedance 或任何作者包家族。++```text+Speech visual ───────────────> VisualTrack ─┐+Media ───────────────────────> VisualTrack ─┤+TimedCaption + style/cues ───> VisualTrack ─┤+Text + style ────────────────> VisualTrack ─┼─> Composition+Vignette / overlay ──────────> VisualTrack ─┤+Speech audio / BGM / SFX ────> AudioTrack ──┘+```++## ProgramSpace++ProgramSpace 拥有时长和精确的有理数帧率。它的时长必须结束在整数帧边界上。Track 不会把 ProgramSpace 的摘要+复制进每一个值。在两者关系需要被校验的地方,图会显式连接 Track 与 ProgramSpace;validator 会拒绝落在所提供+空间之外的帧窗口。++画布宽度、高度和 clear color 是 Composition 的结构性事实。任何视频 Track 都不定义时长,也不会成为享有特权的+Base。++## VisualTrack++一个 VisualTrack 是由某个作者包拥有的、自包含的渲染贡献。它显式绑定+[`svml.visual-ir@1`](./visual-ir.md) 终端语言,并拥有零个或多个帧精确的 `VisualPresent` 值;每个 Present+拥有自己的绝对 `(order, tieBreak)` 堆叠键,以及一棵自包含、不含代码的元素树,其素材来自 box、text、普通媒体+和带类型的可合成 Surface 原语。父引用是 Present 局部的。媒体和精确字体通过内容寻址的 Artifact 引用进入,而不是+通过 CSS URL 或环境字体名。每一个终端文本元素都带有非空的精确 Font 栈。+它与 ProgramSpace 的身份关系是内在的,因为没有时钟就无法解释这个 Track。是哪些 Record 产生了它,属于+Graph/Derivation 真相,被刻意排除在 Track 之外。++Composition 会先把所有 Track 的 Present 拍平,再对它们排序。因此一个 Media 包可以在 z=30 拥有一块 board、在+z=80 拥有一个图标,而来自另一个 Track 的 Text Present 位于 z=50。z 随时间变化由两个互不重叠、堆叠键不同的+Present 表示。Track 的归属关系绝不会创建渲染堆叠上下文或来源链。++每个元素都可以可选地携带帧精确的局部关键帧,作用于 opacity、transform、filter 或 clip-path。这些关键帧只作用+于该 Present 的元素树。Media 包可以把一次成对转场下降为它自己两个 Present 上互补的动画,而不必让 Composition+知道这个转场的名字或语义。++VisualTrack 刻意不具备:++- 家族或来源种类字段;+- 对同级 Track 或 Present 的引用;+- 任意脚本或全局 CSS 选择器;+- 采样下层 Track 的 backdrop 滤镜或混合模式;+- 跨 Track 的蒙版、求交或转场输入。++当一个局部滤镜、裁切、变换、动画或转场只作用于该作者包显式拥有的素材,并下降为自包含的 Present 时,它就是+合法的。需要两份原始素材的效果,必须在最终下降为 Track 之前显式收到这两份素材。任何 Present 都不得采样已经+累积出来的下层合成。++## AudioTrack++一个 AudioTrack 拥有精确的 48 kHz 采样域片段、带类型的规范 WAV Artifact、源区间、循环相位、保持音高的播放+速率、目标区间、增益,以及采样精确的淡入淡出。它没有视觉堆叠键,没有无实际作用的总线标签,也与 Speech Track+没有任何特殊关系。语音音频、音乐、源声和音效使用同一份合同。++## Composition++Composition 包含一个画布和一组 VisualTrack/AudioTrack 值。ProgramSpace 是通往 Film 和最终渲染 Operation 的+一条同级输入边,而不是被反复复制的血缘元数据。Composition:++1. 依据由显式图边提供的 ProgramSpace 校验每一个 Track;+2. 拒绝重复的 Track 身份和重复的视觉堆叠键;+3. 拍平每一个 VisualPresent,并按绝对 `(order, tieBreak)` 挂载;+4. 在 ProgramSpace 中混合 AudioTrack 片段;+5. 为一个被显式选定的最终渲染包产出与渲染器无关的输入。++Composition 不得按作者领域的家族做分支,也不得授予某个 Track 访问已累积下层像素的特权。因此全局 shatter、+调整图层、Base FX 通道或 B-roll 垫底转场都不属于这个版本。也不会为 Base FX 保留任何专用占位。++TimedCaptionProjection 仍然是一个中间语义值。Caption 的分组、样式和 cue 下降必须在字幕作为普通 VisualTrack+进入 Composition 之前完成。++## 最终渲染边界++`@narratage/hyperframes` 是当前面向 Composition 及其唯一带版本 SVML Visual IR 的参考编译器。它绝不按 Speech、+Caption、Media 或作者包身份做分支。它确定性地产出一份内容寻址的 `HyperframesDocument`,其 HTML 按绝对堆叠键+交错排布各个 VisualPresent。它不得把一个创作层的 Track 挂载成一个孤立的视觉包装层。AudioTrack 的编译与最终+mux 是同一个 ProgramSpace 之上相互独立的媒体操作;HyperFrames 是一个无声的可视目标。++这不是一条排他的边界。未来的 `render-remotion` 或基于 API 的渲染包,可以消费同样的 Composition 与+ProgramSpace,编译出另一份不可变的渲染器文档,并返回同一份媒体合同。Author Source 通过导入相应的包来选择这条+路径;Core 和 Runtime 不会猜测渲染器。当前的示例显式选择 `render-hyperframes`。++该文档必须(MUST)绑定精确的有理数帧率、为正整数的帧数、画布尺寸、Artifact 集合以及生成的 HTML。与+ProgramSpace 的关系仍然显现在该 Producer 的输入边与 Derivation 上,而不是被复制进文档内容。它完整的视觉帧域是+半开区间 `[0, frameCount)`。渲染第 `n` 帧必须只依赖这份不可变文档、它精确的 Artifact、被锁定的渲染器实现+以及 `n`;它不得要求顺序求值第 `0..n-1` 帧。因此带状态的作者效果必须在进入这条边界之前物化成带类型的 Surface。++帧分区属于 Runtime 策略。合规的 Endpoint 可以把该域切分成任意一组互不重叠的半开跨度,只要它们按序并起来等于+`[0, frameCount)`,并在本地或远程求值这些跨度、对单个跨度重试,最后一次性拼装可视分块并 mux 音频。这些跨度不是+作者声明、不是 Core Operation,也不是 Track 身份。已履约的渲染 Product 必须重复完全相同的 文档/帧域/画布+绑定;亲和性会拒绝为另一个域拼装出来的结果。++编译出的文档中包含的是 `svml-artifact://` 占位符,不是本地路径、API URL 或签名 URL。解析这些占位符是渲染前一刻+的 Runtime/Provider 动作。因此同一份编译好的文档既能本地渲染也能远程渲染,而不改变作者意图或它的编译身份。+精确文字会变成生成的 `@font-face` 规则,并禁用字体合成。带类型的 Surface 在同一条 Artifact 边界上保持所声明的+尺寸、色彩空间、alpha 模式以及静帧/逐帧时间;它们不会从文件扩展名推断。渲染器会在暂存之前校验这些字节事实,+否则拒收该文档。它的通用 Need Receipt 绑定被锁定的 Endpoint 实现,而 receipt 覆盖的元数据中那份渲染器专属证据,+绑定实际用于布局的精确浏览器或不可变的远程部署。++`@narratage/film` 把包级的任意元数装配实现为一次有限不可变的 TrackSet 折叠,随后是普通的 Composition。渲染是+一个单独的、显式导入的下游 Fragment。Core 只收到定端口、单结果的 Operation,而以某个中间 Track 或 Composition+为 Target 并不要求渲染器。Film Surface 必须下降到已实现的那个 Fragment,既不向 Core 增加 Track 家族,也不让+某个 Track 依赖累积出来的同级像素。diff --git a/docs/zh/guide/spec/track-expressiveness.md b/docs/zh/guide/spec/track-expressiveness.mdnew file mode 100644index 00000000..af528e7a--- /dev/null+++ b/docs/zh/guide/spec/track-expressiveness.md@@ -0,0 +1,183 @@+---+title: SVML Track 表现力门+description: E1–E8 全部门均可执行;仓库内部的 `svml.visual-track@1` 窄腰在公开发布前冻结。+---++# SVML Track 表现力门++状态:E1–E8 全部门均可执行;仓库内部的 `svml.visual-track@1` 窄腰在公开发布前冻结。++## 目的++一份公开的 Track 合同必须解决最终的视听合成问题,同时不假装所有作者包都共用同一套创作模型。Text、+Caption、Media、Ranking 以及未来的包各自拥有自己的 Program,并且可以各自独立地修订这些 Program。+它们只有在把包内专有含义 lower 成自包含、帧精确的贡献之后,才能进入 Composition。++这道门只回答一个问题:++> 生产中实际使用的文字、媒体盒、字幕、层叠与局部特效行为,能否在不向 Track、Composition 或 Core+> 添加包族专有字段的前提下,lower 进同一条 Track 窄腰?++通过这道门并不会产生一个统一的 `TrackProgram`。Track Program 的六条轴——内容、时间源、窗口投影、+空间源、占位与呈现——仍然是给包作者的分离纪律,而不是六个强制的公开字段。共享的创作法则和当前的+时间设计在 [`track-authoring.md`](./track-authoring.md) 中定义。++## 三个绝不能塌陷的层级++```text+Package Program Resolved package facts Public Track+─────────────────────── ──────────────────────────── ─────────────────────+TextLayout / CaptionMode boxes, glyph runs, windows Presents+Media sampling policy -> source-time and crop mapping -> exact frame spans+effect recipe local animations absolute stacking+semantic/spatial locator final placement self-contained elements+```++Package Program 是可编辑的作者真相。Resolved package facts 是编译器证据。公开 Track 是终端的视听贡献。+Composition 绝不能从第三层反推出前两层。++“扁平 Track”意味着不存在 Track 嵌套,也不存在隐式的 Track 层叠上下文。一个 Present 仍然可以拥有自己+内部的 element 树。一条创作 Track 可以在互不相关的绝对层叠位置上输出多个 Present,从而让对等 Track+能够穿插在它们之间。++## 必需的见证++### E1 —— Text 三盒 lowering++官方面向浏览器的参考 lowering 必须能够独立表达:++1. 一个外层 placement frame;+2. 一个控制折行、对齐、方向和溢出的内层 layout box;+3. 面向完整 frame、收缩包裹的内容、每一行或每一个词的 paint 目标。++辉光或阴影这类 paint 溢出,不能仅仅因为它可见于内容盒之外,就变成行测量的输入。包可以通过把 paint+挂到自己拥有的另一个 element 上来 lower 一个 paint 目标;公开 Track 绝不能因此获得+`textBackgroundTarget` 字段。++### E2 —— Caption range/cue/content lowering++Caption 包必须能够 lower 出一个硬性的区间边界、一个 cue 级的对齐/动画容器、收缩包裹的行,以及可以+独立设置样式或动画的词。双字体和逐词 paint 都是包内事实。Composition 只看到普通的 element 与 Present。++### E3 —— Media 双帧 lowering++media 包必须能够 lower 出一个已解析的 Placement Frame,其中包含同一个 Artifact 的两次独立采样。每次+采样按 [`spatial-layout.md`](./spatial-layout.md) 推导自己的 Content Frame:++- 一个背景采样,带自己的 cover/zoom/blur/tone 处理;+- 一个前景采样,带自己的 contain/cover/fit-height 与焦点对齐。++公开 Track 绝不能因此获得 B-roll、焦点预设或模糊背景字段。Artifact 依赖收集必须对共享的内容摘要去重。++### E4 —— 独立的绝对层叠++一个包可以在某个绝对层叠位置输出一块 board,同时在其他位置输出图标或标签。来自另一条 Track 的 Present+必须能够出现在它们之间。Track 身份只是把一份自包含的渲染贡献归组;来源信息存在于 Graph/Derivation 中,+而 Track 永远不构成渲染层叠上下文。++### E5 —— 局部 motion 与交接++帧精确的 opacity、transform、filter 与 clip 动画,可以作用在某一个 Present 所拥有的 element 上。同时+拥有交接双方素材的包,可以 lower 出互补的 Present。任何普通 Track 都不得采样其下方已累积的像素,也不得+修改同级 Track。++Media 包还必须额外证明:进入、维持、退出、逐层采样 motion 与 Sequence 配对交接,始终是分离的通道并具有+固定的合成顺序。独立的 Depth-Stack Deck 包必须证明其集合状态的重排能与 Card 局部 motion 组合,且不会把+Deck 含义带进终端 Track。完整模型在 [`media-track.md`](./media-track.md) 和+[`deck-track.md`](./deck-track.md) 中定义。++### E6 —— 物化的视觉兜底++如果某个组件的确定性视觉结果无法用参考 element 树表达,它必须能够把自己拥有的结果物化,并作为带类型的+Surface 贡献出来。为了实现透明穿插,最终的公开合同必须绑定足够的 surface 信息,以区分可合成的带 alpha+视觉与不透明视频。仅仅命名一个 `.webm` Artifact 并不能证明这一性质。++### E7 —— 通用音频 lowering++官方 Audio 包必须能把任意显式的归一化源、源裁切、一次性播放、循环、有界的保持音高拉伸、起止对齐、增益+与淡入淡出,全部 lower 进同一条对等的 `AudioTrack` 窄腰。重叠的 clip 混合时不做优先级裁剪,也没有特权+的 Base 声道。容器流选择、响度处理与 Provider 放置仍然是上游或下游图中显式的工作。完整边界在+[`audio-track.md`](./audio-track.md) 中定义。++### E8 —— 自包含的屏幕叠加++全画布特效必须 lower 成普通的绝对层叠 Present,由自己拥有的 Visual IR element 或自己拥有的带 alpha+Surface 构成。它不能读取已累积的下层合成结果,不能预留最高 z-index,也不能引入合成后阶段。因此无源的+模糊、调色和真实的 zoom-blur 都会 fail closed;它们诚实的形态是在 Screen Overlay 包之外消费显式的媒体或+Surface 输入。参见 [`screen-overlay.md`](./screen-overlay.md)。++## 旧系统攻击矩阵++| 历史行为 | 包所拥有的真相 | 必需的终端见证 |+|---|---|---|+| Text 的 placement/layout/paint 盒 | Text Program | 自己拥有的嵌套 element |+| frame/content/line/word 背景 | Text Program | paint 挂在所选的自有层级上 |+| caption 的 range/cue/content 盒 | Caption Program | 自己拥有的嵌套 element 与词级局部动画 |+| 双字体、中日韩、emoji 与书写方向 | Text/Caption Program | 文本 element 加锁定的字体/布局依赖 |+| 媒体内容盒加前景/背景采样 | media 包 | 引用同一个 Artifact 的同级媒体 element |+| 焦点裁切与 fit-height | media 包 | 确定性的采样/放置结果 |+| 全画幅 B-roll、角落 GIF 与下方媒体卡 | Media Item + Recipe | 同一个 Item 对不同 Frame 的 lowering |+| 显式的媒体替换组 | Media Sequence | 协同的自有 outgoing/incoming Present |+| 可见的卡片历史与深度重排 | Depth-Stack Deck Track | 建立在普通 Present 之上的包内集合状态 |+| 处在互不相关 z 值上的 Ranking board 与图标 | Ranking Program | 多个绝对层叠 Present |+| Media 的进入/退出与配对转场 | Media Program | 覆盖自有 Present 的局部帧精确 keyframe |+| 任意的自包含视觉 | component/provider | 物化的可合成 Surface Artifact |+| 音乐/音效/额外人声的放置 | Audio Program | 普通的帧精确 AudioTrack clip |+| 闪白/暗角/颗粒/蒙层 | Screen Overlay Program | 自有的全画布 Present 或 alpha Surface |+| 对一张画面做模糊/调色 | 显式输入的媒体特效 | 变换后的自有素材,绝不是背景采样 |++## 当前的可执行证据++`packages/hyperframes/test/track-expressiveness.test.ts` 构造的是包内私有的 lowering 见证,而不是往公开+合同里加 Text、Caption、Media 或 Ranking 字段。已有的包测试另外证明了普通的 Text、Caption 与 Media+Program 都经由同一条 Track 与 Composition 路径 lower。++当前的 `VisualTrack / VisualPresent / VisualElement` 候选显式绑定 `svml.visual-ir@1`,能够编码结构性的+三盒、两盒、词级局部和绝对层叠等情形。有两条通用的终端事实现在是可执行的,而不是包族补丁:++1. `FontArtifactRef` 把每个精确的 fallback 字面、weight 和 style 绑定到一个或多个 Blob 源。+ Unicode-range 分片仍然算一个逻辑字面;精确的文本 lowering 会为每个源输出按内容寻址的+ `@font-face` 规则,并禁用字体合成;+2. `CompositableSurfaceRef` 把尺寸、sRGB 色彩空间、不透明/直通 alpha 语义以及静帧/逐帧时间绑定到 Blob+ 字节。带动画的 Surface 必须与所在 Present 的帧数和 ProgramSpace 速率完全一致。++`packages/hyperframes/test/browser-visual.test.ts` 还会驱动真实的 Hyperframes 浏览器帧:已安装的按内容+寻址开放字体通过有序的 fallback 栈绘制拉丁、中日韩与 emoji/符号字形;Text 证明了 Point/Area/Path 布局、+全部 Box 目标、富文本 run、水平/垂直排版流、clip/ellipsis/有界收缩、有序 Paint、局部 Mask 以及正/反向的+选择器时钟;Fine Caption 证明了多行折行、完整字形 Paint、每一种字形卡拉 OK 模式以及 joined 拖尾 Pill 的+行几何;DepthStack Deck 证明了显式的新旧集合状态重排、精确标签以及单 worker 与分区渲染逐字节一致的帧;+全部十一个官方 Screen Overlay 组件在顺序渲染与并行帧渲染下保持完全相同的像素;一张 50% 直通 alpha 的+PNG 在蓝色 Track 上合成,得到预期的像素值。这个 opt-in 的宿主测试通过 `SVML_BROWSER_TESTS=1` 运行;+它证明的是当前本地渲染器路径,而不是未来所有的托管 Runtime。++IR 的 style 词汇是封闭的,而不是任意 CSS:组件无法在不改变协议版本的前提下加入未知属性、依赖环境的值+或另一种浏览器语言。现在每个终端文本 element 都携带非空的精确 Font Artifact 栈;系统字体兜底和原型字族+都是非法的。Runtime 在通用 Receipt 中绑定其锁定的实现。HyperFrames 还会把精确的本地浏览器摘要,或所+配置的远程渲染器部署摘要,记录在受 receipt 覆盖的元数据中。共享的、基于 ffprobe 的 Surface 字节校验,+会在本地暂存之前证明所声明的尺寸、时间、SDR/sRGB 与 alpha 事实;不具备这一能力的 Endpoint 会拒绝携带+Surface 的文档。++E1–E5、E7 和 E8 现在都有各自的官方包见证。`@narratage/typography-track` 在不引入公开 Text 字段的前提下+证明了完整的三盒/Text 终端模型;Caption 和 Media 证明了它们各自独立的包模型。`@narratage/audio-track`+证明了精确的 48 kHz 源/目标映射、重叠法则、有界拉伸以及一份共享的本地/远程 `AudioProgramPlan`;+`@narratage/screen-overlay` 证明了只使用自包含的自有像素、显式种子、扁平层叠,以及对下层合成类特效的+fail-closed 拒绝;`@narratage/deck-track` 证明了在新旧可见 Card 并集之上的纯绝对帧集合重排,同时复用了+Card 局部的 Media lowering。`@narratage/ranking` 提供了真正的 E4 见证:board、stage 与独立层叠的 Item+与一条无关的对等 Track 相互穿插,同时四个 Ranking 组件在分区浏览器渲染下都保持帧纯净的渐进状态。E6+则通过带类型的路径、独立安装的非原生 Text 见证、字节校验器以及 fail-closed 的 Endpoint 能力检查得以完成。++## 冻结标准++仓库内部的 Track v1 窄腰满足以下全部条件:++1. E1–E8 都具备可执行的结构、HTML lowering 与音频 plan 见证;+2. 官方的 Text/Caption lowerer 要么绑定精确的字体 Artifact,要么显式物化其字形结果,并且用于布局的+ 渲染器实现是受 receipt 绑定的;+3. E6 具备一条带类型的可合成 Surface 路径,其 Runtime 会校验所声明的媒体事实并记录渲染器实现;+4. 安装一个新的 Track 包,不需要改动 Core、Film、Composition 或族注册表;+5. 公开的 Track 数据中不含任何 Caption、Text、Media、Ranking 或 provider 判别字段;+6. 一个包可以修订自己的 Program schema,同时只需保持或版本化自己的 lowerer;+7. 不受支持的跨 Track 采样 fail closed。++因此该实现对后续的仓库包工作已经冻结。公开的 npm 发布、非受信代码隔离与最终的发布版本号仍然是独立的+发布门;它们不会重新打开这条窄腰的视频含义。diff --git a/docs/zh/guide/spec/typography-track.md b/docs/zh/guide/spec/typography-track.mdnew file mode 100644index 00000000..867af8ae--- /dev/null+++ b/docs/zh/guide/spec/typography-track.md@@ -0,0 +1,482 @@+---+title: Typography Track 创作与表达力+description: 官方二维 Text 包的已实现预发布权威文档。+---++# Typography Track 创作与表达力++状态:官方二维 Text 包的已实现预发布权威文档。完整声明的模型与浏览器证据都通过冻结的仓库内部+Track/Visual IR 窄腰执行;作者 Surface 本身尚不是已发布的 ABI。++## 1. Conclusion++完整的 Text 模型不是一个更大的 `TextAppearance` 对象。它是下列各维度的正交乘积:++```text+authored document+× temporal binding+× spatial form+× text flow+× exact typography+× ordered Paint layers+× deterministic local motion+```++一个普通的透明标题、整句话外面套一个背景、每一行渲染行各套一个背景、孤立的词 Pill、连成一体的荧光笔+几何,以及逐字素簇的打字机效果,都是这个模型中的不同取值。它们不是不同的渲染器组件,也不需要在 Core、+Film 或 Composition 里开分支。++“完整”不等于把有史以来所有特效都塞进一个扁平对象。它的意思是:++1. 每一种常见的二维编辑器 Text 行为,在这个模型里都有带类型的落点;+2. 新增 Style 和 Recipe 不会改动共享协议;+3. 输入或物理规律确实不同的能力,使用显式的兄弟组件;+4. 任何超出终端元素语言表达范围的自包含视觉效果,都可以物化为带类型的 compositable Surface,而无需改动+ Core。++官方 Text 包拥有这套作者语义。SVS 只提供具名的不可变 Recipe 参数。Visual IR 仍是共享的终端视频语言。+HyperFrames 只是这门语言的一个渲染器,而不是 Text 的定义。++## 2. Audit evidence++### 2.1 Current Narratage slice++当前 `packages/typography-track` 的实现只有一个固定矩形框、一个纯字符串,以及一个包含颜色、字号、字族、+字重、行高、水平/垂直对齐、单一背景、圆角、内边距和字距的 `TextAppearance`。它的 Surface 恰好只接受+`text`、`during` 和 `appearance`;它的 Recipe 恰好要求十一个标量属性。++它目前无法表达:++- 段落、显式换行或样式不同的内联 run;+- 作者 Surface 上的精确字体 Artifact 输入;+- point text、固有尺寸或路径文字;+- 相互独立的 frame/content/paragraph/line/run/word/grapheme Paint 目标;+- 渐变、可重复的描边、可重复的阴影、辉光或下划线 Layer;+- 具备 Unicode 意识的词/字素簇行为、双向 run 或竖排文字策略;+- item、行、词或字素簇级别的动画;+- 文字遮罩或物化的高级文字效果。++这只是一个有用的端到端见证。一个字段一个字段地扩展 `TextAppearance`,只会把错误的模型固化下来。++### 2.2 Legacy evidence++遗留的 `TextLayoutV2` 发现了几组正确的分离:++- 内联/块级 `hug | fixed` 尺寸;+- 相互独立的内边距与内联/块级对齐;+- 不换行、按词换行和按字符换行;+- visible、clip、ellipsis 和 shrink 四种溢出处理;+- LTR/RTL 与横排/竖排;+- frame/content/line/word 背景目标;+- line box、cap height 和 ink bound 三种度量。++它的渲染器还实现了纯色/渐变字形填充、外描边、阴影、辉光、气泡尾巴、整个 item 的入场/循环运动、打字机+显现以及行/词背景。这些都是有价值的行为见证。++这份实现同样暴露了它为什么不能被照搬成新合同:++- 一个 `TextFields` 参数袋把内容、布局、Paint、运动和装饰混在一起;+- 渐变填充与背景都在抢 CSS 的 `background` 属性;+- 词背景按空白字符正则切分,因此根本没有定义 Unicode 的词行为;+- 打字机切的是 JavaScript code unit,而不是字素簇;+- 外描边是靠复制字形实现的隐式渲染器把戏;+- 行片段、缩放适配以及 cap/ink 裁切依赖浏览器行为,而这些行为并未体现在被声明的值里;+- 一个指针会悄悄创建出背景,而且好几个默认值是渲染器自己发明的;+- 完全没有富 run、路径文字或可重复 Paint Layer 的模型。++一份经过审计的历史导出包含 32 个 Text Track 和 53 个 Text item。使用频率最高的属性是对齐、字族/字号、+颜色、字重、背景、圆角和内边距。描边、大写、不换行、全宽背景、字距和阴影也有使用。该样本中没有任何+Text 动画使用记录。这证明了常规交付的基线;但它不足以成为排除下文那些成熟编辑器能力的理由。++### 2.3 External editor attack matrix++本设计是对照官方产品文档核对的,而不是从 UI 标签反推的:++| 能力族 | 成熟产品的例子 | Narratage 中要求的表达 |+|---|---|---|+| advanced typography | 字距、字偶距、行距、基线偏移、制表位、大写、上/下标、下划线与 Tsume | 带类型的 typography 与逐 run 覆盖 |+| layered appearance | 纯色/渐变填充、内/中/外描边与可重复描边、可重复阴影、辉光 | 有序、可重复的 Paint Layer |+| geometric text boxes | point 标题、area 段落、响应式对齐、滚动字幕/横向滚动 | 分离的 Point 与 Area 形态,外加运动 |+| fragment styling | 字符/词/行级样式与动画 | 确定性单元与选择器 |+| sequential animation | 逐字符延迟、range/follower 选择器、方向、扩散与循环 | 选择器加属性动画栈 |+| path text | 文字沿开放/闭合路径排布并动画 | 显式的 Path Text 形态 |+| text masks | 用文字显现显式自有的媒体或图形 | 带显式媒体输入的兄弟组件 |+| real 3D text | 挤出、倒角、材质、灯光与逐字符 3D | 物化的 3D 组件,而不是伪造的 2D 字段 |++参考文档:++- Adobe Premiere:[Text Styles](https://helpx.adobe.com/uk/premiere/desktop/add-text-images/stylize-text/create-text-styles.html)+ 与 [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)++这是一组表达力攻击集,而不是要求复刻每个产品的 UI 或预设列表。++## 3. Ownership and package boundary++常规二维能力仍然只用一个包:++```text+@narratage/typography-track+ Point Text+ Area Text+ Path Text+ Text Style / Inline Style declarations+ Text Program validation+ temporal/spatial resolution adapters+ VisualTrack lowering+```++Point、Area 和 Path 之所以是三个独立的作者组件,是因为它们断言的几何不同。它们不是那种会让端口忽隐忽现+的 `mode` 字段。它们仍然可以下降到同一个带标签的 `TextItemProgram` 联合类型,并作为对等 item 共存于同一个+Text Track 中。++有两项能力的输入实质不同,因此留在常规 Text 之外:++- Text Mask 组件必须显式消费文字形状和它所遮罩的媒体/图形;它不得去采样恰好位于其下方的那个 Track;+- 真正的 3D Text 拥有挤出、材质、灯光和相机语义,通常物化为带 alpha 的 Surface。++在后续的官方发行版中,它们可以是独立的包,也可以是需要单独导入的组件。包的数量是发行决策;但它们的图+合同必须保持分离。两种情况都不会给 Core 增加分支。++官方的本地 Text Mask 见证刻意只接受一个精确的单行 Area Text 形状和一个显式的静态 `CompositableSurface`。+富 run、多行/Path 排布、序列动画和定时素材都会 fail closed,并走与 3D Text 相同的“物化 Surface”逃生路线。+这条边界避免了假装浏览器 `foreignObject` 遮罩是可移植且精确的。++## 4. Authored Text Document++Text item 消费的是一份有界的富文档,而不是 HTML 片段或任意树:++```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" };+```++具体的公开名称在实现过程中可能改变,但下列法则不会变:++1. 文字、空白、标点和显式换行完全保持作者顺序;+2. 一个纯字符串是“一个段落、一个 run”的简写;+3. Span 只改变可显式继承的 typography/Paint,绝不改变时序或 item 摆放;+4. 只有当被选用的布局/Paint/运动操作确实需要单元时,源文字才会被切分;+5. 切分具备 Unicode 与 locale 意识,并绑定到具体实现;+6. 任何 Text 包都不得用 LLM 去改写、拆分或装饰作者内容;+7. `uppercase`、小型大写字母及类似变换属于表现层,绝不改变被声明的文档值。++确定性的单元层级是:++```text+document > paragraph > explicit run > rendered line > Unicode word > grapheme cluster+```++`rendered line` 只有在确定了精确字体和最终几何之后才存在。字素簇是常规情况下作者可见的最小动画/装饰单元。+一个 shaped glyph 未必与某个 Unicode 字符或字素簇一一对应,因此公开的作者模型不得假装它们一一对应。++## 5. Three spatial forms++时间源与窗口投影仍由 [`track-authoring.md`](./track-authoring.md) 规定。Text 不会发明 `full`、`from`、+`until` 或另一套时序系统。++空间摆放与 Text 排布相互独立。[`spatial-layout.md`](./spatial-layout.md) 中的共享模型提供解析后的+point/frame/path 几何;Text 随后用三种形态之一去解释这份几何。++### 5.1 Point Text++Point Text 是锚定在某个解析点上的固有尺寸文字。它通常紧贴内容、不做软换行,并使用显式的内联/块级锚点。+手动分段仍然有效。常规的标题、标签和贴纸都是 Point Text。++### 5.2 Area Text++Area Text 在解析出的 frame 内排布。它显式选择:++- 内联与块级尺寸:在有意义处使用 `hug | fixed`;+- 四条逻辑边的内边距;+- 内联对齐:`start | center | end | justify`;+- 块级对齐:`start | center | end`;+- 换行:`none | word | grapheme`;+- 溢出:`visible | clip | ellipsis | shrink`;+- 截断/缩放策略下可选的最大行数;+- 书写方向与书写模式;+- 可选的分栏数与栏间距;+- 是否裁剪到摆放 frame;+- 度量边:line box、cap height 或 ink bounds。++溢出是诚实的作者意图。`ellipsis` 可能省略掉可见的被声明文字,因此必须显式写出。`shrink` 必须声明最小+缩放比例,并在完整文字仍放不下时失败;它不得悄悄越过那个下限。这一点与 Caption 不同——Caption 绝不能裁剪+或丢弃作者的显示 Atom。++### 5.3 Path Text++Path Text 消费一条显式自有的矢量路径,外加 Text Document 和 Style。它拥有路径侧、朝向、起止边距、对齐、+反向和溢出。给边距做动画会让文字沿路径移动;给路径做动画则改变路径本身。它绝不会去发现或采样另一个+Track 中的形状。++Path Text 需要一个通用的矢量/路径终端原语,或者一个自有的物化 Surface。它不能靠序列化一段无类型的+SVG/HTML 字符串来声称已实现。++## 6. Typography++Typography 与 Paint、布局相互分离,但参与布局度量。它包括:++- 精确的有序 `FontStackRef`,环境字族名称仅作为显式的原型路径;+- 字号、字重与 normal/italic/oblique 字形;+- 可变字体轴;+- OpenType 特性选择与字体合成策略;+- 字偶距、字距、词间距与行高;+- 语言、方向与书写模式;+- 基线偏移、制表宽度、缩进与段间距;+- 跟随字形度量的下划线/上划线/删除线几何;+- 文字变换、小型大写字母、上标与下标的呈现;+- 所选布局实现支持时的 CJK 专用间距/压缩控制。++精确的字体字节仍是显式的作者图输入。它们不是藏在 Recipe 里的名字,也不由 Runtime 挑选。字体 shaping/布局+实现的身份由被接受的推导/渲染 receipt 绑定;Core 仍然对字体一无所知。++## 7. Ordered Paint model++Paint 是一个有序列表,而不是一组互斥的 CSS 简写。Text Program 拥有这些带类型的 Layer:++```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` 支持纯色、线性渐变和径向渐变,带一份有序的颜色与不透明度 stop 列表。重复使用 Stroke 或+Shadow 是合法的,顺序具有语义。渲染器可以用复制字形 Layer 的方式来下降外描边,但那是实现细节,而不是+一个含义随浏览器而变的作者开关。++Box Paint 有这些目标:++```text+frame | content | paragraph | line | run | word | grapheme+```++它的装饰独立拥有填充、border、内边距、各角圆角和阴影。`isolated` 为每个目标创建一个独立的装饰单元。+`joined` 在每一条渲染行内把相邻的被选片段合并,并给该行片段一个诚实的端头。非法组合(例如在 `frame` 上+使用 continuity)会在 Text 校验期失败。++这一条规则就表达了常见的全部情形:++| 外观 | Paint 取值 |+|---|---|+| 普通透明文字 | 不加 Box Paint Layer |+| 整句话一个胶囊 | `target=content` |+| 整个摆放面板 | `target=frame` |+| 每条渲染行一个框 | `target=line, continuity=isolated` |+| 每个词一个 Pill | `target=word, continuity=isolated` |+| 连成一体的马克笔/荧光笔 | `target=word, continuity=joined` |+| 字母块 | `target=grapheme, continuity=isolated` |++气泡尾巴是显式声明、附着在某个 Box Paint Layer 上的部件,带有方位、偏移、尺寸和自己的 Paint。它不会悄悄+强制生成一个背景。毛玻璃不属于普通 Box Paint,因为它要采样 Track 背后的像素;它需要一个显式自有的媒体+输入,或者一个物化的自包含组件。++## 8. Motion and sequence selectors++运动与 Style 相互独立,因此同一套外观可以有不同的入场、循环和退场。一个 item 可以拥有:++1. item 级的有限关键帧,覆盖位置、缩放、旋转、斜切、不透明度、模糊和裁剪;+2. Path Text 的路径边距动画;+3. 一个或多个作用于文字单元的序列动画器。++一个序列动画器是下列各项的乘积:++```text+unit selector × selected property channels × keyframes × stagger/order+```++单元选择器可以指向 paragraph、line、run、word 或 grapheme。它显式选择范围、正向/反向顺序、延迟/扩散、+循环次数以及任何确定性随机种子。属性通道包括局部变换、不透明度、模糊和字形 Paint 值。打字机是这个模型上+的一个字素簇显现预设,而不是字符串切片。滚动字幕和横向滚动只是 Area Text 上普通的 item 级运动。++任何运动名称都不是隐藏的回调。`pop`、`spring`、`slide` 或 `wobble` 这类预设,会在终端渲染之前编译成有限的+或在解析上有界的、由包自有的运动值。两条运动通道通过各自独立的包裹器或显式的变换合成顺序进行合成;后者+不会覆盖前者。++动画的生命期与 Item 的可见性相互独立。一段运动可以在 Item 窗口结束前就完成,此时它最终被声明的状态一直+保持到 Item 消失。一段运动也可以超出窗口,此时 Item 窗口只是裁剪它,而不改写它的时序。序列运动和 Path+Text 运动遵循同样的规则。这既避免了仅仅因为标题一直可见就拒绝一段完全合理的快速标题动画,也避免了为了+塞进短窗口而悄悄给慢速动画重新计时。++## 9. Style declaration, SVS and readable authoring++声明与使用保持分离。SVS 仍是通用的标量 Recipe 语言;它不得学会 Text 的 Paint 数组,也不得变成第二个+渲染器。Text Style Surface 读取具名 Recipe、精确的 Font 引用和重复的结构化 Layer 声明,校验它们,然后产出+一份完整的、由包自有的 `TextStyle` Record。++预期的作者写法是:++```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} during={story.selection.hook} placement={hook-point}>+ Nothing hidden in the Runtime.+ </text:Point>++ <text:Area id="explanation" style={word-pills} during={story.selection.body} placement={body-frame}>+ <text:P>Every <text:Span style={plain}>visible word</text:Span> stays authored.</text:P>+ </text:Area>+</text:Track>+```++item 也可以改为消费一个普通的图 `Text` 值:++```svml+<copy:Value id="headline">Nothing hidden in the Runtime.</copy:Value>++<text:Track id="titles" space={film.space}>+ <text:Point id="hook" content={headline}+ style={poster} during="program" placement={hook-point}/>+</text:Track>+```++`content={Text}` 与内联正文内容互斥。前者从精确的图值物化出一段纯文本文档 run;后者拥有有界的富文档,+并可使用 `P`、`Span` 和 `Break`。这既阻止了 Frontend 把运行时 Text 复制进隐藏的被声明状态,又让富排版+明确归本包所有。++这套写法在当前共享的时间/空间 Surface 语法上可执行。它的重要性质是:++- 作者导入并选择 Typography 包;+- Style 先声明后使用,并且就是普通的被声明 Record;+- 简单的 Style 值仍然紧凑;+- 重复的 Layer 就是重复的声明,而不是编号字段或编码字符串;+- 解释 Recipe 词汇的是 Markup Surface,不是 SVS;+- 精确字体以及时序/摆放事实都走显式的图边;+- 最终得到的 Text Program 里没有未解析的 Recipe,也没有 Runtime/provider 选择。++## 10. Compiled pipeline and data gates++```text+Markup Surface+ (authored rich document | graph Text input) + 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+```++每一项外部依赖都由图边承载。Text 值只包含固有的 Text 语义。任何上游 Record 都不会仅仅因为后面某个 Text+消费者需要,就凭空长出 text、role、source、style、font 或 layout 元数据。++布局实现可以使用被锁定的浏览器、HarfBuzz/Skia/Pango 或其他精确引擎。它必须绑定实际的实现和字体字节。+浏览器的 line box 不会作为通用图元数据向外传播;它要么是渲染器 receipt 所拥有的确定性终端布局,要么是包+自有的、用于物化 Surface 的已解析几何。++## 11. Terminal Visual IR findings++冻结的仓库内部 `svml.visual-ir@1` 只承载本次迁移所证明的最小增量:++- `text-flow` 拥有有界富文档、精确 typography、有序 Paint 和序列值;+- `path-text` 拥有带类型的矢量命令和精确的路径排布事实;+- 本地 `mask` 原语恰好拥有一个终端遮罩源和一个内容根;+- 有序可重复的 Paint 与 Unicode 单元动画始终是序列化数据,绝不是回调;+- 精确的字体 Artifact 和带类型的 `CompositableSurface` 值走普通的 Artifact 边界。++HyperFrames 参考编译器实现了这些原语,同时不向作者包暴露 HTML、CSS、SVG 或渲染器脚本。一个单独安装的+非原生 Text fixture 证明了挤出/材质/灯光/相机语义可以留在窄腰之外,只贡献一个带类型的 alpha Surface。+不受支持的富遮罩走同一条路径。++这些始终是视频终端的事实,绝不是 Core 的事实。渲染器 receipt、Surface 字节校验、Deck/Ranking 见证以及最终的+兼容性审计,如今都在不向共享窄腰添加 Text 语义的前提下通过。++## 12. Feedback into Fine Caption++Text 与 Caption 共享的是排版实现难题,而不是作者语义。++下列内容可以通过一个聚焦的视频领域实现库共享(暂定为 `@narratage/typography`);在真正出现跨包边之前,+它没有 Author Surface,也没有图 Type:++- Unicode 字素簇/词/双向切分;+- 精确的字体栈加载与 shaping;+- 渐变 stop、有序的描边/阴影/辉光以及 box 装饰几何;+- 行片段与 joined Pill 几何;+- 字素簇安全的打字机效果与确定性的选择器求值;+- 终端富文本下降辅助函数。++这并不会造出一个通用的 Text Program。Caption 仍保留 `CaptionDisplaySequence`、Cue、Atom、语音对应关系和+卡拉 OK 时序。Text 仍保留段落、富 run、point/area/path 布局和任意序列选择器。++本次审计发现的、可落到 Caption 上的具体改进是:++1. 允许有序且可重复的 Stroke/Shadow/Glow Layer,取代当前“每种只能一个”的上限;+2. 允许任意渐变 stop,并支持径向渐变而不只是两个 stop 的线性渐变;+3. 复用显式的内/中/外 Stroke 语义,而不是依赖渲染器的描边行为;+4. 复用字素簇安全的文字变换/显现以及精确 shaping;+5. 把 joined 的活动 Pill 几何保留在共享的行片段实现上。++Caption **不得**继承 Text 的 ellipsis、裁剪、缩放适配、路径排布、任意富 run 时序或选择器生成的语音时序。+它始终展示作者完整的不可变 Atom,并且只从已证明的 Atom 窗口激活。++## 13. Migration order and acceptance gates++实现是替换掉早期切片,而不是不断堆砌兼容字段:++1. **已实现:** Text Document、Point/Area 带标签几何、Text Style 和有序 Paint 值;+2. **已实现:** 精确字体、frame/content/paragraph/line/run/word/grapheme 的 Box Paint,以及富 run 静态下降;+3. **已实现:** 共享的 Temporal Window Projection 和显式的 Point/Frame/Path 空间输入;+4. **已实现:** 确定性溢出、方向/书写模式以及浏览器像素证据;+5. **已实现:** item 运动与具备 Unicode 意识的序列选择器;+6. **已实现:** Path Text,外加一个精确有界的本地 Text Mask 和 fail-closed 的物化边界;+7. **已实现:** `CompositableSurface` 逃生路线,以及一个单独安装的非原生 Text 包见证;+8. **已实现:** 在全仓库所有关卡通过之后冻结仓库内部的 Visual IR。++验收至少要求下列各项的浏览器/渲染证据:++- 透明 Point Text 与固定尺寸 Area Text;+- content、frame、多行的 line、孤立 word、joined word 和 grapheme 各种框;+- 跨换行边界的嵌套 run 样式;+- 使用精确字体的拉丁文、CJK、RTL、组合符号和彩色 Emoji;+- 可重复的外/内描边、多重阴影、线性/径向渐变以及辉光;+- visible/clip/ellipsis/有界 shrink 四种溢出;+- item 的入场/退场/循环,以及正向/反向的 grapheme/word/line 序列化;+- Path Text;+- 显式的 Text Mask 归属,以及一个物化的高级效果兜底;+- 不修改 Core、Runtime、Film 或任何无关的 Track 包。++已声明的 Text 包关卡现已全部通过。这确立了一个构建在冻结的仓库内部 Track/Visual IR 窄腰之上的完整预发布+Text 包;npm 发布以及 Text 作者 Surface 自身的公开版本承诺仍是另外的事情。diff --git a/docs/zh/guide/spec/visual-ir.md b/docs/zh/guide/spec/visual-ir.mdnew file mode 100644index 00000000..2a5020e1--- /dev/null+++ b/docs/zh/guide/spec/visual-ir.md@@ -0,0 +1,119 @@+---+title: SVML Visual IR+description: 已实现的仓库内部 `@1` 兼容窄腰;尚未作为 npm ABI 发布。+---++# SVML Visual IR++状态:已实现的仓库内部 `@1` 兼容窄腰;尚未作为 npm ABI 发布。++## 定位++`svml.visual-ir@1` 是官方 SVML 视频栈共享的唯一一种无代码的终端视觉语言。它是:++- 一份公开的视频领域协议;+- 不是作者组件;+- 不是 Provider API;+- 不属于领域无关的 Core。++Text、Caption、Media、Ranking 以及第三方视觉包可以各自持有互不相干的作者 Program。但在进入+`Composition` 之前,每个包都必须把自己解析后的结果下降为一个显式指明本 IR 的 `VisualTrack`。渲染器+adapter 校验并编译这门共同语言;它永远不需要知道来源是哪个组件家族。`@narratage/hyperframes` 是第一个+参考 adapter,而不是协议的持有者。++```text+author Program shared terminal protocol final-render route+───────────────────── ───────────────────────── ─────────────────────+Text / Caption / Media ───> SVML Visual IR in Track ───┬─> HyperFrames+custom visual producer ───> typed CompositableSurface ───┤+ ├─> future Remotion+ └─> future render API+```++把它称作组件“方言”是一种误导。当前视频栈只有一个官方目标协议。一个组件不可能引入另一套 CSS 语义,同时+还声称自己产出的是同一份 IR。++## 合同++每一份 `svml.visual-track@1` 都携带:++```text+visualIr = svml.visual-ir@1+```++这个值先被携带该 Track 的 Record 覆盖,再经由 Composition 与所选渲染器文档的 Record 传递覆盖。Runtime+不能用另一种视觉语言去重新解释一份已经编译完成的 Track。++该 IR 只包含:++- 带绝对堆叠键、帧级精确的 Present;+- 每个 Present 局部的一棵由 `box`、`text`、`image`、`video` 或 `surface` 元素构成的树;+- 内容寻址的媒体、字体与 Surface 引用;+- 一份封闭的、面向浏览器的样式声明清单;+- 按帧寻址、作用于 opacity、transform、filter 与 clip 的局部 keyframe;+- 安全的 data/ARIA 属性。++它不包含组件家族、作者 recipe、provider 名称、选择器、脚本、外部 URL、运行时凭据、同级 Track 引用,也+不包含累积合成输入。++## 封闭的渲染词汇++实现导出 `VISUAL_STYLE_NAMES_V1`。不在该清单内的声明一律非法,即使某个特定的 Chromium 构建恰好能理解它。+`position`、`display`、`overflow`、`object-fit`、direction 和 writing mode 这类关键的枚举型事实,还额外+使用封闭值集。++以下情况一律失败关闭:++- 未知的 CSS 属性;+- `position: fixed` 与滚动布局;+- `backdrop-filter` 或 `mix-blend-mode` 的跨 Track 采样;+- 用 CSS `url(...)` 代替带类型的 Artifact 引用;+- `var(...)`、`env(...)` 或 `attr(...)` 这类依赖环境的值;+- 会破坏声明结构的标点;+- 对局部动画集合之外属性的动画。++这有意不是“把任意 CSS 塞进 JSON”。这种 CSS 形状的表示,仅仅是被锁定浏览器目标的序列化指令词汇。++## 校验归属++校验有四个彼此独立的持有者:++1. `@narratage/visual-ir` 持有封闭词汇与身份;+2. `@narratage/composition` 持有 Track schema 与内在自包含性校验;+3. Film 与最终渲染 Producer 通过显式图边接收 ProgramSpace,校验关系型的帧域事实,而不往 Track 值里添加+ 血缘字段;+4. 被选中的本地或托管渲染 Endpoint 锁定实际的渲染器实现,并校验产出的媒体事实。++Core 内不含任何视频专用分支。它的通用准入通路会调用已安装的 Type 持有者 validator,来校验内在的树、样式+与 Artifact 事实。涉及另一个值的关系性校验,仍然是普通的多输入 Producer 检查。++## 扩展法则++安装一个新的视觉组件不得修改本协议。该组件只能二选一:++1. 把自己的 Program 下降为已有的元素与样式;或者+2. 把它所持有的视觉物化为一个带类型的 `CompositableSurface`,并贡献该 Surface。++只有当某项能力既具备广泛复用价值,又无法通过上述两条路径表达时,才有理由改动 `svml.visual-ir@1` 合同。+在 Narratage 处于预发布阶段期间,标识符保持为 `@1`,确切的实现身份由摘要和 package lock 承载。新增一种+Text 样式、Caption 模式、Media recipe、转场或 Provider,本身永远不构成理由。++因此,旧系统的 Text 三盒模型、Caption 的 range/cue/content 模型和 Media 的内容帧采样模型,都属于包自有的+Program 与下降证据。它们是本 IR 表达力的见证,而不是被加进 IR 的字段。++## 冻结证据++标识符与封闭词汇都是可执行的。精确的 Text 字体、多行装饰、Path/Mask/overflow、Media 焦点采样和 alpha 现在+都有真实的浏览器证据;一个单独安装的非原生 Text 包可以穿过带类型的 Surface 窄腰,而不改动 Core、Film 或+HyperFrames。仓库内部的 `@1` 窄腰之所以被冻结,是因为以下四道彼此独立的闸门现在都能真正执行:++1. 通用的 Need Receipt 绑定被锁定的 Endpoint 实现/配置/Runtime closure,同时 HyperFrames 那份被 receipt+ 覆盖的 attestation,在本地绑定确切的浏览器字节,在远端绑定显式配置的不可变渲染器部署摘要;+2. 共享的媒体执行器在本地渲染之前解码 Surface 字节,并证明尺寸、帧时序、SDR/sRGB 兼容性以及+ opaque/straight-alpha 事实;不具备该 verifier 的渲染器 Endpoint 必须拒绝携带 Surface 的文档;+3. Deck 与 Ranking 提供其余的包自有 Track 表达力见证;+4. 全仓库的边界审查证明 Composition 中不含任何包家族/provider 判别字段,且终端编译器中不存在隐藏的跨 Track+ 采样通路。++这为本仓库后续的包开发冻结了该协议。它并不意味着 npm 包已经发布、每个作者 Surface 都已冻结,也不意味着未来+的公开发布可以跳过分发与安全审查。diff --git a/packages/caption-fine/README.md b/packages/caption-fine/README.mdindex 8e55cd0d..597e72e1 100644--- a/packages/caption-fine/README.md+++ b/packages/caption-fine/README.md@@ -63,4 +63,4 @@ the compact `fonts:Stack` above. Family, weight and style exist only on those exthe Recipe owns size and appearance. Fallbacks keep their own honest face metadata. Omitting the stack is invalid rather than an environment-fontprototype path. Fine never clips author text and intentionally has no `max-lines`.Common Caption, Composition and Core know none of Fine's Recipe fields or layout policy. See-`spec/caption-fine.md` for the full parameter surface, defaults and non-goals.+[Fine Caption Style](https://narratage.hypit.ai/guide/spec/caption-fine) for the full parameter surface, defaults and non-goals.diff --git a/packages/core/README.md b/packages/core/README.mdindex 5c3299c1..e3f78e17 100644--- a/packages/core/README.md+++ b/packages/core/README.md@@ -26,7 +26,7 @@ It generically verifies Surface declarations in the same immutable module closurparses or dispatches one. It does not parse source, resolve package locations, executeimplementations, access artifact bytes, select Provider endpoints or discover undeclared graphstructure. Those responsibilities remain outside Core. The normative laws are in-[`../../spec/core-kernel.md`](../../spec/core-kernel.md).+[Core Kernel](https://narratage.hypit.ai/guide/spec/core-kernel).For a non-video domain, the irreducible reusable base is only `@narratage/protocol` plus `@narratage/core`.Most source languages will also use `@narratage/elaborator` to turn modular component declarations into adiff --git a/packages/media-track/README.md b/packages/media-track/README.mdindex 27f11dbe..bf651bec 100644--- a/packages/media-track/README.md+++ b/packages/media-track/README.md@@ -21,4 +21,4 @@ The automatic lowering is Surface behavior, not a privileged Runtime route: it pordinary Media Pipeline Operations that an author can write explicitly through`@narratage/media-pipeline`. The package does not add Media, B-roll or Provider meaning to Core,Film, Composition or HyperFrames. “B-roll” is an editorial use of an ordinary Item or Sequence. The-complete pre-release contract and acceptance matrix live in `spec/media-track.md`.+complete pre-release contract and acceptance matrix live in [Media Track](https://narratage.hypit.ai/guide/spec/media-track).diff --git a/packages/ranking/README.md b/packages/ranking/README.mdindex fd7d0453..cb662d04 100644--- a/packages/ranking/README.md+++ b/packages/ranking/README.md@@ -35,4 +35,4 @@ they define the board vocabulary rather than dynamic item copy.</ranking:Column>```-See [`../../spec/ranking-track.md`](../../spec/ranking-track.md) for the normative pre-release model.+See [Ranking Track](https://narratage.hypit.ai/guide/spec/ranking-track) for the normative pre-release model.diff --git a/packages/spatial/README.md b/packages/spatial/README.mdindex aef6b0bf..44a97c9c 100644--- a/packages/spatial/README.md+++ b/packages/spatial/README.md@@ -6,4 +6,4 @@ renderer, Provider or Core behavior.The package exposes self-described `Canvas`, `Point`, `Path`, `Extent`, `Frame`, `AnchoredFrame` and`AspectFrame` author Surfaces plus pure geometry functions and fixed-port Producers. See-[`../../spec/spatial-layout.md`](../../spec/spatial-layout.md).+[Shared Spatial Layout](https://narratage.hypit.ai/guide/spec/spatial-layout).diff --git a/packages/temporal/README.md b/packages/temporal/README.mdindex 2c1735d1..c33670c8 100644--- a/packages/temporal/README.md+++ b/packages/temporal/README.md@@ -7,4 +7,4 @@ expressions, intersects them with ProgramSpace and returns validated half-open fThe package also provides pure sibling-window validation and triggered-stage scheduling. It definesno Core branch, renderer behavior, media playback policy, Provider or authoring super-program.-The normative design is [`../../spec/track-authoring.md`](../../spec/track-authoring.md).+The normative design is [Track Authoring Model](https://narratage.hypit.ai/guide/spec/track-authoring).