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
ci: run check, test and docs on every push, and fix Chinese line breaks
rpone02c2b162caa5
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.ymlnew file mode 100644index 00000000..df8a411d--- /dev/null+++ b/.github/workflows/ci.yml@@ -0,0 +1,42 @@+name: CI++on:+ push:+ branches: [main]+ pull_request:+ workflow_dispatch:++concurrency:+ group: ci-${{ github.ref }}+ cancel-in-progress: true++jobs:+ check:+ runs-on: ubuntu-latest+ steps:+ - name: Checkout+ uses: actions/checkout@v4++ - name: Set up pnpm+ uses: pnpm/action-setup@v4++ - name: Set up Node.js+ uses: actions/setup-node@v4+ with:+ node-version: 22+ cache: pnpm++ - name: Install dependencies+ run: pnpm install --frozen-lockfile++ - name: Type check+ run: pnpm check++ - name: Test+ run: pnpm test++ - name: Repository hygiene+ run: pnpm test:release++ - name: Build documentation+ run: pnpm docs:builddiff --git a/README.md b/README.mdindex fa18f9e2..054615f4 100644--- a/README.md+++ b/README.md@@ -9,7 +9,7 @@</p><p align="center">- <a href="https://github.com/hypit-ai/narratage/actions/workflows/deploy-pages.yml"><img alt="Docs" src="https://img.shields.io/github/actions/workflow/status/hypit-ai/narratage/deploy-pages.yml?branch=main&label=Docs"></a>+ <a href="https://github.com/hypit-ai/narratage/actions/workflows/ci.yml"><img alt="CI" src="https://img.shields.io/github/actions/workflow/status/hypit-ai/narratage/ci.yml?branch=main&label=CI"></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>diff --git a/README.zh-CN.md b/README.zh-CN.mdindex 5ee2d341..6bf71162 100644--- a/README.zh-CN.md+++ b/README.zh-CN.md@@ -9,38 +9,30 @@</p><p align="center">- <a href="https://github.com/hypit-ai/narratage/actions/workflows/deploy-pages.yml"><img alt="Docs" src="https://img.shields.io/github/actions/workflow/status/hypit-ai/narratage/deploy-pages.yml?branch=main&label=Docs"></a>+ <a href="https://github.com/hypit-ai/narratage/actions/workflows/ci.yml"><img alt="CI" src="https://img.shields.io/github/actions/workflow/status/hypit-ai/narratage/ci.yml?branch=main&label=CI"></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 视频创作的语义化、图原生系统。你写下故事,选择模型与视觉组件,声明想要哪些-输出;Narratage 把这份意图变成一张有限的执行计划,只运行结果真正依赖的工作,并把每一个已接受的输出-保留下来,供后续 Run 使用。+Narratage 是一套面向 AI 视频创作的语义化、图原生系统。你写下故事,选择模型与视觉组件,声明想要哪些输出;Narratage 把这份意图变成一张有限的执行计划,只运行结果真正依赖的工作,并把每一个已接受的输出保留下来,供后续 Run 使用。SVML 是创作语言,Narratage 是围绕它的编译器、运行时与包生态。## 名字的由来-1933 年《*New York Times*》对电影《*The Power and the Glory*》的一篇影评造出了 **narratage** 这个-词,用来描述当时的一种新兴手法:旁白加蒙太奇——声音推动故事前进,画面组接出与之呼应的段落。+1933 年《*New York Times*》对电影《*The Power and the Glory*》的一篇影评造出了 **narratage** 这个词,用来描述当时的一种新兴手法:旁白加蒙太奇——声音推动故事前进,画面组接出与之呼应的段落。-这套系统做的正是这件事。作者写下带有语义锚点的口播 Script,编译器把生成的视频、字幕、B-roll、文字-与音频组装成一部完成的影片。+这套系统做的正是这件事。作者写下带有语义锚点的口播 Script,编译器把生成的视频、字幕、B-roll、文字与音频组装成一部完成的影片。## 为什么用图-AI 生成慢、贵、不确定,而且每一步的输出往往就是下一步的输入。Narratage 把由此产生的选择呈现为两张-平级的图:Author Graph 表达工作本身,Run Graph 为一次 Build 选择 Target 与 Candidate。Core 只负责-解析、校验并推进由此得到的状态机,因此视频领域的概念都留在可独立安装的包里——Core 不硬编码任何模型、-Track 或 Provider。+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 把观众看到的文字与说话者-念出的内容分开,Selection 与 Moment 为语义区间和时间点命名——全程不引入时间码。+Script 始终是可读的散文。Segment 组织故事,Role Cue 指明谁在说话,Dual Text 把观众看到的文字与说话者念出的内容分开,Selection 与 Moment 为语义区间和时间点命名——全程不引入时间码。```xml<script id="story">@@ -104,9 +96,7 @@ Script 始终是可读的散文。Segment 组织故事,Role Cue 指明谁在| `\@midnight` | 字面量 `@midnight` || `<!-- ... -->` | 注释,不会进入任何输出文字 |-标记名本身不带行为:`@silence` 不会让音频静音,必须由 Audio、Caption 或 Track 组件显式消费这个-Selection。完整词汇见 [Script](https://narratage.hypit.ai/zh/quickstart/script);完整且可检查的源码见-[`talking-film-graph-check`](./examples/talking-film-graph-check/main.svml)。+标记名本身不带行为:`@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 也能试@@ -125,21 +115,15 @@ node --run narratage -- plan examples/talking-film-graph-check/build.svrun \--package-lock examples/talking-film-graph-check/svml.packages.lock```-`check` 校验 Author Source 并打印它的类型化输出。`plan` 展示被真正需要的子图,以及一次真实 Build 会-用到的每一项外部能力,但不会启动其中任何一项。+`check` 校验 Author Source 并打印它的类型化输出。`plan` 展示被真正需要的子图,以及一次真实 Build 会用到的每一项外部能力,但不会启动其中任何一项。## 接下来去哪- [快速开始](https://narratage.hypit.ai/zh/quickstart) —— 你掌控的文件、命令,以及第一次真实 Build。-- [开发](https://narratage.hypit.ai/zh/guide/develop) —— 包架构、添加 Author 包或 Provider,以及全部- 规范文档。+- [开发](https://narratage.hypit.ai/zh/guide/develop) —— 包架构、添加 Author 包或 Provider,以及全部规范文档。## 许可-Narratage 以 [Narratage 开源许可](./LICENSE) 发布,基于 Apache 2.0 并附加额外条款。你可以在自己的-基础设施上运行它,包括用于所在组织的商业工作;也可以 fork、修改并以相同条款公开源码。将 Narratage-作为多租户或托管服务运营,以及为商业利益向第三方提供它,都需要商业授权。你用 Narratage 产出的内容-归你所有。+Narratage 以 [Narratage 开源许可](./LICENSE) 发布,基于 Apache 2.0 并附加额外条款。你可以在自己的基础设施上运行它,包括用于所在组织的商业工作;也可以 fork、修改并以相同条款公开源码。将 Narratage作为多租户或托管服务运营,以及为商业利益向第三方提供它,都需要商业授权。你用 Narratage 产出的内容归你所有。-以英文 [`LICENSE`](./LICENSE) 文本为准。商业授权请联系-[[email protected]](mailto:[email protected]?subject=%5BGitHub%5DNarratage%20Commercial%20License%20Inquiry)。+以英文 [`LICENSE`](./LICENSE) 文本为准。商业授权请联系[[email protected]](mailto:[email protected]?subject=%5BGitHub%5DNarratage%20Commercial%20License%20Inquiry)。diff --git a/docs/zh/guide/spec/audio-track.md b/docs/zh/guide/spec/audio-track.mdindex a03901a3..37b6888f 100644--- a/docs/zh/guide/spec/audio-track.md+++ b/docs/zh/guide/spec/audio-track.md@@ -5,13 +5,11 @@ description: 通用官方 Audio Track 包的已实现预发布合同,含自描# SVML Audio Track 作者面-状态:通用官方 Audio Track 包的已实现预发布合同,包含它的自描述作者 Surface、精确的采样域 lowering,以及-本地 / 远端执行见证。它还不是冻结的公开 ABI。+状态:通用官方 Audio Track 包的已实现预发布合同,包含它的自描述作者 Surface、精确的采样域 lowering,以及本地 / 远端执行见证。它还不是冻结的公开 ABI。## 目的-`@narratage/audio-track` 让作者把已经选定并归一化的音频素材放入 ProgramSpace。音乐、音效、额外口播和源-音频都是普通的同级项。这个包不拥有任何有特权的基础泳道,Composition 通过既有的+`@narratage/audio-track` 让作者把已经选定并归一化的音频素材放入 ProgramSpace。音乐、音效、额外口播和源音频都是普通的同级项。这个包不拥有任何有特权的基础泳道,Composition 通过既有的[`AudioTrack`](./track-composition.md) 终端合同来混合它的结果。这是一个视频领域的作者包,不是 Core 原语、Runtime 服务或 Provider。分工如下:@@ -32,8 +30,7 @@ Core 看到的是固定的图输入和一个输出 Record。它不知道 clip、## 1. 输入的事实-每个音频条目都通过显式的图边获得素材。第一个实现应当消费来自 `@narratage/media` 的 `SynchronizedMedia`,-并要求它归一化后的音频成员:+每个音频条目都通过显式的图边获得素材。第一个实现应当消费来自 `@narratage/media` 的 `SynchronizedMedia`,并要求它归一化后的音频成员:- 48 kHz;- 立体声;@@ -41,15 +38,12 @@ Core 看到的是固定的图输入和一个输出 Record。它不知道 clip、- 精确的采样帧数;- 保留原始电平。-仅仅含有 AAC 的 MP4 不是音频条目。作者图必须显式地检视容器、选择一条音频流并做归一化。同理,一个生成出来-的语音文件不会仅因为里面有人声就变成 `SpeechAudioBasis`。+仅仅含有 AAC 的 MP4 不是音频条目。作者图必须显式地检视容器、选择一条音频流并做归一化。同理,一个生成出来的语音文件不会仅因为里面有人声就变成 `SpeechAudioBasis`。Audio Track 的 lowerer 可以从归一化后的采样帧数推导终端 Artifact 的时长。它不得把源身份、Narrative 摘要、provider 名称或其他血缘信息拷贝进 clip。这些关系仍然由图边和 Derivation 承载。-不要仅仅为了缩短一条边就引入新的公开 `AudioMaterial` Type。如果将来确有多个互不相关的包需要一个一等的-规范音频值,那个聚焦的 intrinsic Type 应当放在 `@narratage/media`;它仍然不属于 Core,也不属于某个大杂烩-式的 contracts 包。+不要仅仅为了缩短一条边就引入新的公开 `AudioMaterial` Type。如果将来确有多个互不相关的包需要一个一等的规范音频值,那个聚焦的 intrinsic Type 应当放在 `@narratage/media`;它仍然不属于 Core,也不属于某个大杂烩式的 contracts 包。## 2. 作者 Program@@ -90,8 +84,7 @@ type AudioItemProgram = {</audio:Track>```-这种写法只是示意,不是冻结的 Surface。`during`、`at` 和 `for` 必须 lower 到共享的点表达式与窗口投影代数;-它们不能创建第二套时间引擎。+这种写法只是示意,不是冻结的 Surface。`during`、`at` 和 `for` 必须 lower 到共享的点表达式与窗口投影代数;它们不能创建第二套时间引擎。## 3. 时间放置@@ -104,16 +97,13 @@ type AudioItemProgram = {5. 应用音频的源 trim 与 occupancy;6. 把目标放置与源采样一起 lower 到精确的 48 kHz 采样域。-音频条目相互独立。重叠的投影窗口会混合;它们绝不会按书写顺序被裁剪、被自动拼接、被去重,也不会被当成互斥的-备选方案。多个 Audio Track 值的行为,与一个 Audio Track 里多个重叠条目完全相同。+音频条目相互独立。重叠的投影窗口会混合;它们绝不会按书写顺序被裁剪、被自动拼接、被去重,也不会被当成互斥的备选方案。多个 Audio Track 值的行为,与一个 Audio Track 里多个重叠条目完全相同。-ProgramSpace 的帧边界由媒体管线已经拥有的那一条确定性规则转换为 48 kHz 采样边界。作者包不得再实现另一条-秒到采样的取整路径。+ProgramSpace 的帧边界由媒体管线已经拥有的那一条确定性规则转换为 48 kHz 采样边界。作者包不得再实现另一条秒到采样的取整路径。## 4. 源 trim-源 trim 定义 occupancy 之前的有效固有区间。它是精确归一化采样域内的一个显式起点和可选终点。面向作者的秒或-帧只被量化一次到采样边界。+源 trim 定义 occupancy 之前的有效固有区间。它是精确归一化采样域内的一个显式起点和可选终点。面向作者的秒或帧只被量化一次到采样边界。lowerer 拒绝:@@ -123,8 +113,7 @@ lowerer 拒绝:- 不可用的音频成员;- 对源时长的第二种包内私有解释。-源 trim 不是目标时间。移动目标窗口绝不会悄悄改变作者声明的是哪一段源区域,除非所选的 occupancy 策略显式地-对它做了对齐或重定时。+源 trim 不是目标时间。移动目标窗口绝不会悄悄改变作者声明的是哪一段源区域,除非所选的 occupancy 策略显式地对它做了对齐或重定时。## 5. 音频 occupancy@@ -152,8 +141,7 @@ type AudioOccupancy =| `loop/end` | 选择相位使源尾部与窗口结束对齐 | 播放源尾部 || `stretch` | 放慢以铺满整个窗口 | 加快以铺满整个窗口 |-`once` 取代了旧的含混的 `native` / `finish` 行为。尾部对齐不是倒放。`loop/end` 改变的是循环相位,它不会反转-采样。`stretch` 保持音高,必须停留在作者声明的速率界限内,并且宁可失败也不会悄悄用更快的速率再截断。旧的+`once` 取代了旧的含混的 `native` / `finish` 行为。尾部对齐不是倒放。`loop/end` 改变的是循环相位,它不会反转采样。`stretch` 保持音高,必须停留在作者声明的速率界限内,并且宁可失败也不会悄悄用更快的速率再截断。旧的`fit_base` 规则——最多加速 1.1 倍然后把剩下的悄悄切掉——被废弃。显式的静音由该区间上不存在 clip 来表示。当被填充的静音字节本身有意义时,给文件补静音是一次独立的媒体变换。@@ -166,15 +154,11 @@ type AudioOccupancy =- 在可听的已渲染区间上生效的 `fadeIn`;- 在可听的已渲染区间上生效的 `fadeOut`。-零增益就是显式的静音。UI 或 recipe 可以暴露分贝,但换算到终端线性增益是确定性的,并且由包拥有。淡变时长-必须非负,不能超过可听区间,也不能偷偷扩张目标窗口。+零增益就是显式的静音。UI 或 recipe 可以暴露分贝,但换算到终端线性增益是确定性的,并且由包拥有。淡变时长必须非负,不能超过可听区间,也不能偷偷扩张目标窗口。-不存在任何隐式的响度归一化、限幅器、压缩器、sidechain 闪避、交叉淡变或自动铺底音乐行为。这些都是合理的-未来音频处理或混音 Program,但它们必须消费显式输入,并让自己的行为对作者可见。Runtime 或 Provider 不得把-它们当作环境偏好加进来。+不存在任何隐式的响度归一化、限幅器、压缩器、sidechain 闪避、交叉淡变或自动铺底音乐行为。这些都是合理的未来音频处理或混音 Program,但它们必须消费显式输入,并让自己的行为对作者可见。Runtime 或 Provider 不得把它们当作环境偏好加进来。-原来的终端 `bus: speech | music | sfx | source` 标签已被移除。它对渲染没有任何影响,因此也不承载任何诚实的-含义。将来的混音路由合同必须有明确的消费者和图行为;仅仅把一个 clip 命名为 `music` 不能导致闪避。+原来的终端 `bus: speech | music | sfx | source` 标签已被移除。它对渲染没有任何影响,因此也不承载任何诚实的含义。将来的混音路由合同必须有明确的消费者和图行为;仅仅把一个 clip 命名为 `music` 不能导致闪避。## 7. Lowering 与执行@@ -185,12 +169,9 @@ type AudioOccupancy =- 来自 trim / occupancy 的精确源采样区间、循环相位和播放速率;- 来自呈现的保持音高意图、线性增益和精确的采样级淡变。-Composition 会针对显式连接的 ProgramSpace 校验 Audio Track。随后媒体管线把所有同级 Audio Track 编译成一份-内容寻址的 `AudioProgramPlan`。本地 FFmpeg、Lambda 或另一个 Provider 执行的是同一份 plan;Provider 的部署-位置不能重新解释这次混音。+Composition 会针对显式连接的 ProgramSpace 校验 Audio Track。随后媒体管线把所有同级 Audio Track 编译成一份内容寻址的 `AudioProgramPlan`。本地 FFmpeg、Lambda 或另一个 Provider 执行的是同一份 plan;Provider 的部署位置不能重新解释这次混音。-即使包内拥有很多 clip,它也只发出一个 `AudioTrack`。那是一个作者组件的输出,不是有特权的泳道。天然同时拥有-一次视觉命中和一次声音命中的包,可以从一个 Fragment 发出同级的 `VisualTrack` 和 `AudioTrack` 输出,而 Film+即使包内拥有很多 clip,它也只发出一个 `AudioTrack`。那是一个作者组件的输出,不是有特权的泳道。天然同时拥有一次视觉命中和一次声音命中的包,可以从一个 Fragment 发出同级的 `VisualTrack` 和 `AudioTrack` 输出,而 Film通过普通的边接收两者。## 8. 旧系统迁移审计@@ -230,5 +211,4 @@ Film 泳道:8. **已实现:** 本地 FFmpeg 与远端 Lambda Provider 收到完全相同的内容寻址 `AudioProgramPlan`;真实 FFmpeg见证还会逐采样检查精确的循环相位。-如果加入这个包需要 Core 分支、Film 音频家族、新队列、SVML 中出现 Provider 名称或一条隐藏的 Base 音频规则,-那么这次迁移就是不完整的。+如果加入这个包需要 Core 分支、Film 音频家族、新队列、SVML 中出现 Provider 名称或一条隐藏的 Base 音频规则,那么这次迁移就是不完整的。diff --git a/docs/zh/guide/spec/author-surface-binding.md b/docs/zh/guide/spec/author-surface-binding.mdindex 888c9a9a..c60c4fe9 100644--- a/docs/zh/guide/spec/author-surface-binding.md+++ b/docs/zh/guide/spec/author-surface-binding.md@@ -46,12 +46,9 @@ type exact nominal TypeRefrecord? defensively copied TypedRecord when the public export is already an authored Record```-组件输出没有编译期 Record,因此省略 `record`。如果某个 Surface 需要检查值本身(例如 Recipe 解码器),-它必须要求一份作者 Record,并在引用无法解析、Type 不对或此时还没有值时,于 `check` 阶段失败。+组件输出没有编译期 Record,因此省略 `record`。如果某个 Surface 需要检查值本身(例如 Recipe 解码器),它必须要求一份作者 Record,并在引用无法解析、Type 不对或此时还没有值时,于 `check` 阶段失败。-只有被 import 的 SourceUnit 的公开 record export 会被暴露出来。私有的子 record 不属于 resolver 的范围。-每一份返回的 Record 都是防御性的规范化副本,因此 Surface 代码无法改写已经编译完成的子 SourceUnit 或此前-的声明。+只有被 import 的 SourceUnit 的公开 record export 会被暴露出来。私有的子 record 不属于 resolver 的范围。每一份返回的 Record 都是防御性的规范化副本,因此 Surface 代码无法改写已经编译完成的子 SourceUnit 或此前的声明。## 4. 包的归属@@ -85,8 +82,7 @@ Coresees only typed Records, LogicalOutputs, Candidates and Operations```-不存在一张通用属性表。另一个包完全可以通过另一个被显式 import 的 Surface 来解释同一份通用 Recipe,并-产出不同的名义 Program。Surface 永远不由 Recipe 的形状来选中;是作者写下带命名空间的组件时选中它的。+不存在一张通用属性表。另一个包完全可以通过另一个被显式 import 的 Surface 来解释同一份通用 Recipe,并产出不同的名义 Program。Surface 永远不由 Recipe 的形状来选中;是作者写下带命名空间的组件时选中它的。## 5. Surface 输出法则@@ -101,8 +97,7 @@ Frontend 用源码与 Frontend Closure 身份为作者 Record 的来源封印,Host 的准入闸门。Surface 不能注入未声明 Type 的 Record。由 Recipe 推导出的带类型 Program,应当包含其所属包做语义校验所需的任何源码摘要。它的作者来源已经绑定了-Surface 实现摘要和递归编译得到的 Source Closure。别名写法与文件系统位置的变化可能改变源码身份,但不会-改变带类型的 Program 值,也不会改变最终 Graph 的含义。+Surface 实现摘要和递归编译得到的 Source Closure。别名写法与文件系统位置的变化可能改变源码身份,但不会改变带类型的 Program 值,也不会改变最终 Graph 的含义。## 6. 前向引用法则@@ -126,8 +121,7 @@ Surface Binding 不是:- 全局 SVS 解码器;- 读取凭据、文件、网络或 Store 的许可。-当前的 Host 只执行显式注册的受信任 Surface 实现。要让任意社区 Surface 代码可以执行,必须先具备按字节锁定-的代码、权限强制和隔离。+当前的 Host 只执行显式注册的受信任 Surface 实现。要让任意社区 Surface 代码可以执行,必须先具备按字节锁定的代码、权限强制和隔离。## 8. 可执行的证明diff --git a/docs/zh/guide/spec/caption-fine.md b/docs/zh/guide/spec/caption-fine.mdindex ab355448..db141901 100644--- a/docs/zh/guide/spec/caption-fine.md+++ b/docs/zh/guide/spec/caption-fine.md@@ -9,9 +9,7 @@ description: 已实现的预发布 Style 族,所声明的表面均有完整的## 目的与边界-`@narratage/caption-fine` 是官方的、无字段的细粒度 Caption Style 族。这里的 “Fine” 指的是:不可变的-显示 Atom 被规划成短的语义 Cue,再经由一套确定性视觉系统渲染。它**不**表示 `important`、语义强调分类-或逐词的随机样式。+`@narratage/caption-fine` 是官方的、无字段的细粒度 Caption Style 族。这里的 “Fine” 指的是:不可变的显示 Atom 被规划成短的语义 Cue,再经由一套确定性视觉系统渲染。它**不**表示 `important`、语义强调分类或逐词的随机样式。这个包消费三份已经存在的事实:@@ -19,8 +17,7 @@ description: 已实现的预发布 Style 族,所声明的表面均有完整的2. `TimedCaptionProjection`,它给每个 Cue 和每个完整 Atom 一个已证实的时间窗口;3. `CaptionDisplaySequence`,它保留作者精确的可见文字与标点。-它输出一条普通的对等 `VisualTrack`。它绝不修改文字、绝不调用模型、绝不推断 Dual Text Atom 内部的时间,-也绝不往其他合同里塞 Caption 元数据。+它输出一条普通的对等 `VisualTrack`。它绝不修改文字、绝不调用模型、绝不推断 Dual Text Atom 内部的时间,也绝不往其他合同里塞 Caption 元数据。| 归属 | 职责 ||---|---|@@ -35,17 +32,14 @@ Media、Composition、Visual IR 或 Core。## 完整的正交表面-Fine 拥有一棵单字体的 Cue/Atom layout 树。它的各个维度互相独立:一份 Recipe 可以同时组合渐变字形、-当前词盒子、拖尾文字、下划线和局部 motion,而不必换一个渲染器。只有当某种外观改变了 layout 树、或者-需要 planner 字段时——例如双字体的编排式排版——才有理由新开一个包;仅仅增加 Paint 或局部 motion 不算。+Fine 拥有一棵单字体的 Cue/Atom layout 树。它的各个维度互相独立:一份 Recipe 可以同时组合渐变字形、当前词盒子、拖尾文字、下划线和局部 motion,而不必换一个渲染器。只有当某种外观改变了 layout 树、或者需要 planner 字段时——例如双字体的编排式排版——才有理由新开一个包;仅仅增加 Paint 或局部 motion 不算。### 1. Cue 规划- `cue-min-words`- `cue-max-words`-planner 只能在完整 Atom 之间切分。不可分割的作者 Atom 可以超过偏好的最大值;绝不会为了凑数字而把它-拆开。+planner 只能在完整 Atom 之间切分。不可分割的作者 Atom 可以超过偏好的最大值;绝不会为了凑数字而把它拆开。### 2. 放置与布局@@ -57,21 +51,16 @@ planner 只能在完整 Atom 之间切分。不可分割的作者 Atom 可以超- `line-height`、`letter-spacing`、`word-gap`- 绝对的 `stack-order`-Cue 只会在 Atom 之间自然换行。同一个 Atom 内的 Word 绝不会被拆到不同行。Fine 没有 `max-lines` 属性:-硬性行数限制要么丢弃作者文字,要么把浏览器测量偷偷带进确定性 lowering。Fine 绝不裁剪、绝不截断。作者-通过 Cue 词数边界、宽度和字号来控制密度。如果确实需要一条硬性布局断言,它必须是一个单独连接的组件,-其失败在图中是显式的。+Cue 只会在 Atom 之间自然换行。同一个 Atom 内的 Word 绝不会被拆到不同行。Fine 没有 `max-lines` 属性:硬性行数限制要么丢弃作者文字,要么把浏览器测量偷偷带进确定性 lowering。Fine 绝不裁剪、绝不截断。作者通过 Cue 词数边界、宽度和字号来控制密度。如果确实需要一条硬性布局断言,它必须是一个单独连接的组件,其失败在图中是显式的。### 3. 排版- Recipe:`size`- `text-transform: none | uppercase | lowercase`-text transform 只是终端呈现。它绝不改变 `CaptionDisplaySequence`、planner 输入、Word/Atom 身份、语音-对应或时间。+text transform 只是终端呈现。它绝不改变 `CaptionDisplaySequence`、planner 输入、Word/Atom 身份、语音对应或时间。-family、weight 和 style 被刻意排除在 Recipe 之外。每个 Style 都必须从 `@narratage/fonts-open` 引入-精确的已安装字面,或用 `<media:Font>` 声明自定义/品牌字节。`font=` 接受一个精确字面加上有序的、+family、weight 和 style 被刻意排除在 Recipe 之外。每个 Style 都必须从 `@narratage/fonts-open` 引入精确的已安装字面,或用 `<media:Font>` 声明自定义/品牌字节。`font=` 接受一个精确字面加上有序的、Style 所属的 Fallback 子节点,或者一个可复用的通用 `FontStackRef`。开放字体的紧凑写法是:```svml@@ -82,15 +71,10 @@ Style 所属的 Fallback 子节点,或者一个可复用的通用 `FontStackRe```字体这条边是 family、weight 和 style 的唯一真相来源。fallback 保留它自己诚实的字面元数据——例如 700-字重的拉丁主字面可以搭配 400 字重的符号 fallback。完全重复的字面会被拒绝。一个逻辑字面可以包含多个-按内容寻址的 Unicode-range 源,已安装的中日韩与 Emoji 字体就是如此。Fine 把 `FontStackRef` 展开成-同样有序的精确字面,并且只把它们放在自己的终端文本 element 上;Caption、Core 以及无关的图值保持不变。-省略 `font=` 是非法的,因此结果里不会混入任何 Runtime 或机器字体选择策略。+字重的拉丁主字面可以搭配 400 字重的符号 fallback。完全重复的字面会被拒绝。一个逻辑字面可以包含多个按内容寻址的 Unicode-range 源,已安装的中日韩与 Emoji 字体就是如此。Fine 把 `FontStackRef` 展开成同样有序的精确字面,并且只把它们放在自己的终端文本 element 上;Caption、Core 以及无关的图值保持不变。省略 `font=` 是非法的,因此结果里不会混入任何 Runtime 或机器字体选择策略。-中日韩口播可以直接书写。纯显示的 emoji 仍然需要显式的语音对应,例如 `<🌐 | globe>`;Script 会正确地-拒绝为一个孤立符号发明口播 token。同时具有文字与 Emoji 呈现形态的字符,使用作者书写的精确 Unicode-序列(例如带 VS16 的 `☎️`);没有任何 lowerer 会为了强制上色而改写显示文字。这是时间与文字真相问题,-不是字体能力问题。+中日韩口播可以直接书写。纯显示的 emoji 仍然需要显式的语音对应,例如 `<🌐 | globe>`;Script 会正确地拒绝为一个孤立符号发明口播 token。同时具有文字与 Emoji 呈现形态的字符,使用作者书写的精确 Unicode+序列(例如带 VS16 的 `☎️`);没有任何 lowerer 会为了强制上色而改写显示文字。这是时间与文字真相问题,不是字体能力问题。### 4. 基础字形与激活字形的 Paint@@ -107,9 +91,7 @@ Style 所属的 Fallback 子节点,或者一个可复用的通用 `FontStackRe每个激活态 Paint 名字都带 `active-` 前缀。例如 `active-gradient-from`、`active-long-shadow-distance`和 `active-glow-blur` 描述的是激活字形,不改变基础字形。-基础 Paint 与激活 Paint 形状相同。渐变替换该层的纯色填充;它不替换激活叠加层,也不替换卡拉 OK 过渡。-投影、长阴影和辉光是互相独立的作者贡献,会被 lower 成一条确定性的 `text-shadow` 声明。长阴影的展开有-实现上的上界,因此一份 Recipe 不可能造出无限膨胀的 CSS 负载。任意多层阴影、纹理、斜面和自由挤出仍在+基础 Paint 与激活 Paint 形状相同。渐变替换该层的纯色填充;它不替换激活叠加层,也不替换卡拉 OK 过渡。投影、长阴影和辉光是互相独立的作者贡献,会被 lower 成一条确定性的 `text-shadow` 声明。长阴影的展开有实现上的上界,因此一份 Recipe 不可能造出无限膨胀的 CSS 负载。任意多层阴影、纹理、斜面和自由挤出仍在Fine 之外。### 5. Cue 盒子 Paint@@ -132,17 +114,12 @@ Fine 之外。- 激活下划线状态:`active-underline: off | current | trail`,以及颜色、粗细和偏移激活状态与装饰几何被刻意分开。`current` 只激活其实测窗口包含当前帧的那个 Atom。`trail` 让每个已激活的-Atom 一直保留到 Cue 结束。`step` 整体切换激活字形层;`wipe` 在该 Atom 的实测窗口内逐步揭示它。RTL 会-反转 wipe 方向。字形、盒子和下划线可以各自选择不同的状态策略,因此历史上保留的那种行为——拖尾文字配-仅当前的 pill——可以直接表达。+Atom 一直保留到 Cue 结束。`step` 整体切换激活字形层;`wipe` 在该 Atom 的实测窗口内逐步揭示它。RTL 会反转 wipe 方向。字形、盒子和下划线可以各自选择不同的状态策略,因此历史上保留的那种行为——拖尾文字配仅当前的 pill——可以直接表达。-isolated 盒子为每个已激活的 Atom 各画一个盒子。joined 拖尾把有序的已激活前缀画成连续的行内片段:同一-渲染行上的 atom 共享一个背景,而每个折行的行各自获得自己的端帽。决定这些片段的是浏览器的行布局,而不是-上游元数据。Fine 绝不把实测行盒子传播到图里。+isolated 盒子为每个已激活的 Atom 各画一个盒子。joined 拖尾把有序的已激活前缀画成连续的行内片段:同一渲染行上的 atom 共享一个背景,而每个折行的行各自获得自己的端帽。决定这些片段的是浏览器的行布局,而不是上游元数据。Fine 绝不把实测行盒子传播到图里。卡拉 OK 刻意是 Atom 粒度的。在普通文字里,一个 Atom 通常就是一个可见 Word。在 `<45% | forty five percent>`-中,作者书写的可见 `45%` 是一个 Atom,作为一个整体激活。在多词显示 Atom 中,整个作者 Atom 一起激活。-下游任何包都不会发明作者与音频证据从未提供过的内部 Word 时间戳。+中,作者书写的可见 `45%` 是一个 Atom,作为一个整体激活。在多词显示 Atom 中,整个作者 Atom 一起激活。下游任何包都不会发明作者与音频证据从未提供过的内部 Word 时间戳。### 7. 分层的局部 motion@@ -160,9 +137,7 @@ isolated 盒子为每个已激活的 Atom 各画一个盒子。joined 拖尾把`active-response-frames`、`active-scale`;`slide-distance`;以及 `loop`、`loop-target`、`loop-period-frames`、`loop-intensity`。-Cue、Atom 生命周期、激活响应和循环各自拥有独立的包裹层,因此它们的 transform 是叠加组合而不是互相-覆盖。typewriter 在一个完整 Atom 内逐个揭示作者书写的显示字素;它是视觉插值,不代表字符级时间戳,-也绝不改变 Atom 边界。连续 motion 是有界的确定性帧函数,不含任何随机输入。任意路径运动和随机变化仍在+Cue、Atom 生命周期、激活响应和循环各自拥有独立的包裹层,因此它们的 transform 是叠加组合而不是互相覆盖。typewriter 在一个完整 Atom 内逐个揭示作者书写的显示字素;它是视觉插值,不代表字符级时间戳,也绝不改变 Atom 边界。连续 motion 是有界的确定性帧函数,不含任何随机输入。任意路径运动和随机变化仍在Fine 之外;它们属于通用 Typography 或独立的特效包,而不属于 Caption 的预设词汇。## 一个渲染器,一棵 layout 树@@ -181,14 +156,12 @@ placement└── active glyph/underline overlay```-装饰底层只重复那份为了获得诚实的浏览器行片段所必需的、同样的透明字形几何。它不会制造出第二份文字真相。-激活叠加层复用同一份 Atom 几何。每个动画都会在 HyperFrames 看到它之前,lower 成有限的、按帧寻址的+装饰底层只重复那份为了获得诚实的浏览器行片段所必需的、同样的透明字形几何。它不会制造出第二份文字真相。激活叠加层复用同一份 Atom 几何。每个动画都会在 HyperFrames 看到它之前,lower 成有限的、按帧寻址的`VisualTrack` keyframe。## 默认值与兼容性-最初那十五个基线属性仍然是必填的,因此最小的 Recipe 也会对规划、几何、排版和可见盒子给出显式说明。-新增维度是可选的,并解析成一个完整的不可变参数对象:+最初那十五个基线属性仍然是必填的,因此最小的 Recipe 也会对规划、几何、排版和可见盒子给出显式说明。新增维度是可选的,并解析成一个完整的不可变参数对象:- 左上锚点、LTR、normal 字体、零字距,以及四分之一 em 的词间距;- 无描边、无阴影、无长阴影、无辉光、无下划线、无边框;@@ -213,5 +186,4 @@ placement长阴影、text transform、分层的一次性 motion、typewriter 揭示与确定性循环,各自都有终端 IR 见证;joined 几何另外还有真实折行的浏览器/像素见证。-没有任何一道门改动 Core 或公共 Caption。精确的字体选择是 Media Font Surface 与 Fine Style Surface 之间-一条显式的作者图引用,而不是沿着 Caption 流水线传播的元数据。+没有任何一道门改动 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.mdindex ade12de3..235a676a 100644--- a/docs/zh/guide/spec/caption-program.md+++ b/docs/zh/guide/spec/caption-program.md@@ -35,15 +35,13 @@ Script 输出一份 `CaptionDisplaySequence`,它带两个有序视图:`45%`、`back-and-forth`、`damn!`、`300,000`、`don't` 和 `U.S.A.` 原样穿过这条边。官方 Script reader以英文优先,把作者书写的空白当作正常的显示词边界;其他作者包可以发布另一套策略,只要产出同样的公开合同。-对普通文字,一个显示 Word 通常就是一个 Atom。显式的 Dual Text 永远是一个完整 Atom,即使两侧恰好含有-相同的词:+对普通文字,一个显示 Word 通常就是一个 Atom。显式的 Dual Text 永远是一个完整 Atom,即使两侧恰好含有相同的词:```svml<New York City | new york city>```-该显示序列包含一个 Atom、三个 Word:`New`、`York`、`City`。它并不声称其中任何一个显示 Word 对应任何-一个口播 token。隐藏的 Dual Text(`< | um>`)不产生任何显示 Atom。+该显示序列包含一个 Atom、三个 Word:`New`、`York`、`City`。它并不声称其中任何一个显示 Word 对应任何一个口播 token。隐藏的 Dual Text(`< | um>`)不产生任何显示 Atom。这是刻意的信息纪律:Script 只使用作者显式给出的对应关系,绝不发明作者没有给出的对应关系。@@ -52,12 +50,9 @@ Script 输出一份 `CaptionDisplaySequence`,它带两个有序视图:`CaptionCorrespondence` 把每个显示 Atom 映射到一个或多个作者书写的口播 token 身份。它与`CaptionDisplaySequence` 相互独立;显示侧的消费者不必携带自己用不上的语音血缘。-对普通文字,每个 Atom 映射到该显示表面在结构上拥有的那些口播 token。对 Dual Text,整个显示 Atom 映射-到整段右侧口播区间。不存在公开的“显示 Word 到口播 Word”的映射,也不存在猜出来的内部时间。+对普通文字,每个 Atom 映射到该显示表面在结构上拥有的那些口播 token。对 Dual Text,整个显示 Atom 映射到整段右侧口播区间。不存在公开的“显示 Word 到口播 Word”的映射,也不存在猜出来的内部时间。-Script 还会为显式的 Selection 输出 `CaptionDisplayWordSubset` 值。Role 选择器是同一份显示序列之上的-作者面语法糖。子集是有序的,可以选中零个或多个完整 Atom;只选中一个多词 Atom 的一部分属于作者错误。-这些值不是时间性的 `NarrativeSelection` 值,也不会引入第二套 `when` 语言。+Script 还会为显式的 Selection 输出 `CaptionDisplayWordSubset` 值。Role 选择器是同一份显示序列之上的作者面语法糖。子集是有序的,可以选中零个或多个完整 Atom;只选中一个多词 Atom 的一部分属于作者错误。这些值不是时间性的 `NarrativeSelection` 值,也不会引入第二套 `when` 语言。## 4. 完整的 Style 意图@@ -66,12 +61,9 @@ Script 还会为显式的 Selection 输出 `CaptionDisplayWordSubset` 值。Role- 通用的规划要求:偏好的 Cue 词数上下界,以及零个或多个带类型的 per-Word 字段声明;- 一个渲染族身份,以及该族经 Recipe 解析后的完整参数。-公共 Caption 包只拥有 Cue 与字段的数据形状,不拥有字体、盒子、颜色、动画,也不定义字段 id 的含义。-一个 Style 族可以不声明任何字段。布尔、枚举和有界数值字段对其他族同样可用;一个 Word 可以携带零个、-一个或多个互相独立的字段。+公共 Caption 包只拥有 Cue 与字段的数据形状,不拥有字体、盒子、颜色、动画,也不定义字段 id 的含义。一个 Style 族可以不声明任何字段。布尔、枚举和有界数值字段对其他族同样可用;一个 Word 可以携带零个、一个或多个互相独立的字段。-SVS 存放具名的 Recipe 数据。Style 包解释这份 Recipe 并输出一份完整的 Style。应用另一个 Style 会整体-替换原 Style;规划与渲染的零散片段绝不会被隐式合并。+SVS 存放具名的 Recipe 数据。Style 包解释这份 Recipe 并输出一份完整的 Style。应用另一个 Style 会整体替换原 Style;规划与渲染的零散片段绝不会被隐式合并。## 5. 全覆盖赋值与有序替换@@ -87,22 +79,16 @@ Selection,也不必写补集。```Use 按源码顺序生效,最后一个命中的整体 Style 替换获胜。Program 存的是显示序列身份和有序的 Word id-区段,而不是复制出来的文字。一个区段绝不跨越 Segment 或 Turn 边界。所有区段互不相交,对显示 Word 恰好-划分一次,且任何区段都不得把一个 Atom 拆开。+区段,而不是复制出来的文字。一个区段绝不跨越 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 族的渲染器共享这一-行为,不必各自发明自己的遮罩语义。公共包还导出同一个幂等操作,供直接调用渲染器时做防御性处理。+`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 和渲染只在自己需要时,各自声明指向同一个-值的边。+`display={story.caption}` 是一条真实的图边。planner、timing 和渲染只在自己需要时,各自声明指向同一个值的边。## 6. planner 合同@@ -111,8 +97,7 @@ planner 接收已解析的区段。对每个区段,它只能:1. 把连续的完整 Atom 编组成有序的 Cue;2. 给每个 Cue 内的 Word 赋予已声明的字段。-Cue 必须对每个区段恰好划分一次。偏好的 Cue 最小/最大词数只是对 planner 的引导,不能让作者文字失效;-单个多词 Atom 可以超过最大值,并且必须保持完整。响应中不包含任何替换文字、发音、时间戳或 Style。+Cue 必须对每个区段恰好划分一次。偏好的 Cue 最小/最大词数只是对 planner 的引导,不能让作者文字失效;单个多词 Atom 可以超过最大值,并且必须保持完整。响应中不包含任何替换文字、发音、时间戳或 Style。Gemini planner 只发送一次可读形式:@@ -126,8 +111,7 @@ Gemini planner 只发送一次可读形式:}```-外层数组是 Cue 的可切分全集。每个内层数组是一个不可分割的 Atom。其中的字符串是不可变的字段作用目标。-稳定 id 留在包内部。响应通过 `atom_count` 消费 Atom;字段在其 Cue 内使用从 1 开始的 `atom_number` 和+外层数组是 Cue 的可切分全集。每个内层数组是一个不可分割的 Atom。其中的字符串是不可变的字段作用目标。稳定 id 留在包内部。响应通过 `atom_count` 消费 Atom;字段在其 Cue 内使用从 1 开始的 `atom_number` 和`word_number`。## 7. 时间投影@@ -136,14 +120,11 @@ Gemini planner 只发送一次可读形式:Atom 的显式口播 token 区间,并给整个 Atom 一个实测窗口。一个 Cue 从它的第一个 Atom 开始,到它的最后一个Atom 结束。-因此 `TimedCaptionProjection` 只包含定时的 Cue 和定时的 Atom。它不包含 per-display-Word 的时间戳,-没有 `estimated` 质量标签,也没有按字符比例的切分。对于多词的 Dual Text Atom,下游渲染器可以自行决定-如何排布或动画其内部 Word,但不得声称拥有编造出来的词级时间。任何内容都不会写回 SemanticMap。+因此 `TimedCaptionProjection` 只包含定时的 Cue 和定时的 Atom。它不包含 per-display-Word 的时间戳,没有 `estimated` 质量标签,也没有按字符比例的切分。对于多词的 Dual Text Atom,下游渲染器可以自行决定如何排布或动画其内部 Word,但不得声称拥有编造出来的词级时间。任何内容都不会写回 SemanticMap。## 8. 渲染与合成-每个定时 Cue 选出其解析后 Style 的完整渲染负载。一个 Style 族渲染器返回一条普通的 `VisualTrack`。在首版-合同中,一个 Program 内的所有 Style 使用同一个渲染族。+每个定时 Cue 选出其解析后 Style 的完整渲染负载。一个 Style 族渲染器返回一条普通的 `VisualTrack`。在首版合同中,一个 Program 内的所有 Style 使用同一个渲染族。`@narratage/caption-fine` 是第一个官方族。它不声明任何字段,拥有一套正交的单字体 layout/Paint/motion系统,包括互相独立的整 Atom 字形、下划线和 Pill 激活。其他包可以定义不同的 layout 树或依赖字段的diff --git a/docs/zh/guide/spec/core-kernel.md b/docs/zh/guide/spec/core-kernel.mdindex 7dda1406..5259954c 100644--- a/docs/zh/guide/spec/core-kernel.md+++ b/docs/zh/guide/spec/core-kernel.md@@ -7,8 +7,7 @@ description: 当前可执行合同:持久化 Graph、BuildRequest、Plan 与 B状态:当前可执行合同。持久化的 Graph、BuildRequest、Plan 与 BuildState wire 格式都是 `@1`。-Core 是与领域无关的图 Demand 编译器,以及一台经过校验的 Build 状态机。它不解析源码、不加载包、-不执行实现、不选择 Endpoint、不访问凭据、不持久化 Artifact,也不认识任何视频词汇。+Core 是与领域无关的图 Demand 编译器,以及一台经过校验的 Build 状态机。它不解析源码、不加载包、不执行实现、不选择 Endpoint、不访问凭据、不持久化 Artifact,也不认识任何视频词汇。## 输入@@ -65,11 +64,8 @@ Core 只接受不可变的、已经完成链接的数据:## 边界-`@narratage/protocol` 持有 wire 数据与身份。`@narratage/core` 持有校验、Demand 编译和状态转移。编译器-包持有源码与图的构造。Runtime 持有调度、持久化与放置。Endpoint 包履约确切的 Capability。领域包持有共享-词汇与 validator。+`@narratage/protocol` 持有 wire 数据与身份。`@narratage/core` 持有校验、Demand 编译和状态转移。编译器包持有源码与图的构造。Runtime 持有调度、持久化与放置。Endpoint 包履约确切的 Capability。领域包持有共享词汇与 validator。-文件后缀、包名和 TypeScript class 都不授予 Kernel 特权。在 Core 之后发布的领域包,可以只通过 manifest、-名义 Type 和普通 Operation 参与进来,不需要重新发布 Core。+文件后缀、包名和 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.mdindex 546f5187..cb423b3c 100644--- a/docs/zh/guide/spec/deck-track.md+++ b/docs/zh/guide/spec/deck-track.md@@ -5,13 +5,11 @@ description: 官方深度栈 Deck 迁移的已实现可执行权威,记录旧# SVML 深度栈 Deck Track-状态:官方深度栈 Deck 迁移的已实现可执行权威。它记录了旧 Deck 实现所使用的行为,但它不是冻结的-公开 ABI,也不定义通用的 Deck 协议。+状态:官方深度栈 Deck 迁移的已实现可执行权威。它记录了旧 Deck 实现所使用的行为,但它不是冻结的公开 ABI,也不定义通用的 Deck 协议。## 1. 结论-Deck 不是 Media Item 的一种模式,也不是 Media Track 的第三个原语。它是更高阶的视觉组件,只是它的-成员恰好使用了媒体素材。+Deck 不是 Media Item 的一种模式,也不是 Media Track 的第三个原语。它是更高阶的视觉组件,只是它的成员恰好使用了媒体素材。第一个官方实现是 `@narratage/deck-track`。它诚实的作者含义是一个**深度栈 Deck**:@@ -39,8 +37,7 @@ Core、Film、Composition 和 HyperFrames 都不知道某个贡献来自 Deck。## 2. 为什么 Deck 在 Media Track 之外-Media Item 回答的是单个素材如何呈现。Media Sequence 回答的是成员如何在同一个共享表面上相互替换。-深度栈 Deck 回答的是另一个问题:当当前成员改变时,整个有序集合如何改变姿态。+Media Item 回答的是单个素材如何呈现。Media Sequence 回答的是成员如何在同一个共享表面上相互替换。深度栈 Deck 回答的是另一个问题:当当前成员改变时,整个有序集合如何改变姿态。在同一帧上,一个 Deck 可能同时显示:@@ -50,8 +47,7 @@ Media Item 回答的是单个素材如何呈现。Media Sequence 回答的是成- 按相对深度区分的不同偏移、缩放、旋转、不透明度和色调;- 一次让每个保留 Card 从旧姿态移动到新姿态的转场。-这是集合状态,而不是源采样、适配或“出场 / 入场”成对交接。把它留在 Media Track 里,会让一个历史遗留-的呈现模型看起来像通用的媒体原语。+这是集合状态,而不是源采样、适配或“出场 / 入场”成对交接。把它留在 Media Track 里,会让一个历史遗留的呈现模型看起来像通用的媒体原语。## 3. 目前还没有通用的 Deck 合同@@ -65,9 +61,7 @@ Media Item 回答的是单个素材如何呈现。Media Sequence 回答的是成- 时间轴历史;- 看板与条目一同演化的 Ranking 板。-这些包可以定义不同的作者 Surface、校验与 lowering,它们只需要发出终端 `VisualTrack` 合同即可。只有当-多个真实实现证明存在一条更小的共同法则之后,我们才应该抽出共享的 Deck 库。仅仅共用“Deck”这个名词,-不构成设立中心协议的证据。+这些包可以定义不同的作者 Surface、校验与 lowering,它们只需要发出终端 `VisualTrack` 合同即可。只有当多个真实实现证明存在一条更小的共同法则之后,我们才应该抽出共享的 Deck 库。仅仅共用“Deck”这个名词,不构成设立中心协议的证据。因此第一个包应该暴露一个诚实的组件名,例如 `DepthStack`,而不是声称它的字段描述了所有可能的 Deck。@@ -84,8 +78,7 @@ Media Item 回答的是单个素材如何呈现。Media Sequence 回答的是成@narratage/composition terminal VisualTrack waist```-`@narratage/deck-track` 可以复用 Media Track 中聚焦的实现函数,或者后续某个纯实现层的媒体 lowering 库。-这种代码复用并不会让 Deck 变成 Media Track 组件,也不会通过 Core 暴露通用的 `MediaProgram` 或+`@narratage/deck-track` 可以复用 Media Track 中聚焦的实现函数,或者后续某个纯实现层的媒体 lowering 库。这种代码复用并不会让 Deck 变成 Media Track 组件,也不会通过 Core 暴露通用的 `MediaProgram` 或`DeckProgram`。这个包不做以下事情:@@ -122,8 +115,7 @@ Media Item 回答的是单个素材如何呈现。Media Sequence 回答的是成组件本身产出一个普通的 `VisualTrack`。它不嵌套在 `<media:Track>` 里,也不通过 `mode="deck"` 选择。SVML 拥有拓扑:有序的 Card 成员关系、source 边、trigger 引用、终止点、Frame 以及可选的标签输入。SVS-拥有可复用参数:可见邻域、深度姿态、frame Paint 和 reflow 运动。SVS 不能创建 Card、隐藏 source 边或-选择 Provider。+拥有可复用参数:可见邻域、深度姿态、frame Paint 和 reflow 运动。SVS 不能创建 Card、隐藏 source 边或选择 Provider。## 6. 精确的状态模型@@ -139,8 +131,7 @@ p1 < p2 < ... < pN < Tcurrent(f) = greatest i such that pi <= f```-在 `p1` 之前,除非有显式的初始状态策略另行规定,组件处于非激活状态。在 `T` 及其之后,除了作者显式声明-的退场运动之外,组件同样处于非激活状态。+在 `p1` 之前,除非有显式的初始状态策略另行规定,组件处于非激活状态。在 `T` 及其之后,除了作者显式声明的退场运动之外,组件同样处于非激活状态。包会校验作者声明的出现顺序。它绝不会把相等、逆序或缺失的 trigger 点整理成一份看似合法的呈现。@@ -182,16 +173,13 @@ Sequence transition coordinates outgoing member + incoming memberDeck reflow coordinates the union of old-visible + new-visible Cards```-它们不得共用同一个 `transitionStyle` 联合类型。Card 还可以拥有自己的当前项强调效果,但它不能改动属于-另一个 Track 的像素。+它们不得共用同一个 `transitionStyle` 联合类型。Card 还可以拥有自己的当前项强调效果,但它不能改动属于另一个 Track 的像素。-渲染器把状态和姿态求值为绝对帧号的纯函数,不保留可变的“上一帧”状态。因此任意帧渲染、分块 Lambda 渲染-和乱序帧求值都保持确定性。+渲染器把状态和姿态求值为绝对帧号的纯函数,不保留可变的“上一帧”状态。因此任意帧渲染、分块 Lambda 渲染和乱序帧求值都保持确定性。## 8. Card 素材与播放-每个 Card 都可以复用与 Media Item 相同的显式 layer、Content Fit、裁剪和 frame Paint 法则。这属于实现-复用,不是作者模型的继承。+每个 Card 都可以复用与 Media Item 相同的显式 layer、Content Fit、裁剪和 frame Paint 法则。这属于实现复用,不是作者模型的继承。带时间的 Card 源必须定义它在非当前项时如何采样:@@ -203,16 +191,13 @@ past trail hold source tail, continue, or hide according to explicit polic静态素材不需要播放策略。视频绝不能在仅作为未来预览时悄悄播完。-Card 标签是可选的显式 Text 输入。Deck 包可以复用 typography lowering,但它不能从文件名、URL 或隐藏的-图像元数据推导 Text 事实。+Card 标签是可选的显式 Text 输入。Deck 包可以复用 typography lowering,但它不能从文件名、URL 或隐藏的图像元数据推导 Text 事实。-初版 DepthStack 只有视觉。如果后续某个 Deck 组件要暴露源音频,它必须以独立且显式的 `AudioTrack` 投影-提供,并带有作者声明的当前成员 / 交接法则;音频绝不能仅仅因为某个 Card 的容器里含有音频流就变得可闻。+初版 DepthStack 只有视觉。如果后续某个 Deck 组件要暴露源音频,它必须以独立且显式的 `AudioTrack` 投影提供,并带有作者声明的当前成员 / 交接法则;音频绝不能仅仅因为某个 Card 的容器里含有音频流就变得可闻。## 9. Stacking-Deck Track 没有 Track 级 z-index,也不创建 stacking context。当同级 Track 需要插入其间时,看板 / 背景与-各个 Card 可以 lower 成各自独立的绝对 stack Present。+Deck Track 没有 Track 级 z-index,也不创建 stacking context。当同级 Track 需要插入其间时,看板 / 背景与各个 Card 可以 lower 成各自独立的绝对 stack Present。相对深度只决定自有 Card 之间的顺序。reflow 期间的临时顺序也只存在于这一显式关系内部,它不会分配全局 z 段。@@ -251,10 +236,7 @@ Deck Track 没有 Track 级 z-index,也不创建 stacking context。当同级7. 证明静态与带时间素材的非激活播放行为;8. 迁移一个真实的旧系统 Deck,并且只有在验收矩阵通过之后才冻结。-第 1–8 步在 `@narratage/deck-track` 中执行。包测试覆盖下文列出的每一种状态、校验、播放、标签和扩展场景。-真实的 HyperFrames 见证会渲染一个旧风格的三 Card 深度栈两次——一次单 worker、一次三个分区 worker——并-逐字节比较每一帧解码结果,同时证明每个作者声明的当前状态都被绘制出来。这完成了 Deck 包的验收矩阵,独立-的通用 E1–E8 终端 VisualTrack / Visual IR 关卡现在也已通过。+第 1–8 步在 `@narratage/deck-track` 中执行。包测试覆盖下文列出的每一种状态、校验、播放、标签和扩展场景。真实的 HyperFrames 见证会渲染一个旧风格的三 Card 深度栈两次——一次单 worker、一次三个分区 worker——并逐字节比较每一帧解码结果,同时证明每个作者声明的当前状态都被绘制出来。这完成了 Deck 包的验收矩阵,独立的通用 E1–E8 终端 VisualTrack / Visual IR 关卡现在也已通过。要求的证据包括:diff --git a/docs/zh/guide/spec/media-track.md b/docs/zh/guide/spec/media-track.mdindex 61a5b55b..059a3c5a 100644--- a/docs/zh/guide/spec/media-track.md+++ b/docs/zh/guide/spec/media-track.md@@ -5,14 +5,12 @@ description: 统一官方 Media Track 的可执行预发布权威文档。Item/S# SVML Media Track 创作-状态:统一官方 Media Track 的可执行预发布权威文档。Item/Sequence 两个 Surface、定时素材、-有序 Layer、运动、Handoff、独立的音频投影以及受限的 Speech 投影均已实现。原先的+状态:统一官方 Media Track 的可执行预发布权威文档。Item/Sequence 两个 Surface、定时素材、有序 Layer、运动、Handoff、独立的音频投影以及受限的 Speech 投影均已实现。原先的`@narratage/broll` 垂直切片已被移除,而不是作为兼容层保留。本合同尚不是冻结的公开 ABI。## 1. Conclusion-全画幅插叙、下方证据卡、角落图片、透明贴纸、动图、短视频以及普通的替换序列,并不是各不相同的-终端 Track family。它们只是同一组媒体关注点的不同组合:+全画幅插叙、下方证据卡、角落图片、透明贴纸、动图、短视频以及普通的替换序列,并不是各不相同的终端 Track family。它们只是同一组媒体关注点的不同组合:```textsource material@@ -28,8 +26,7 @@ optional owned pairwise replacement relationshipoptional explicit audio projection```-它们属于同一个视频领域包 `@narratage/media-track`,并且全部下降为普通的对等 `VisualTrack`;-只有在作者显式声明时,才会同时下降为 `AudioTrack` 值。+它们属于同一个视频领域包 `@narratage/media-track`,并且全部下降为普通的对等 `VisualTrack`;只有在作者显式声明时,才会同时下降为 `AudioTrack` 值。一个包不等于一个带条件分支的超级组件。作者 Surface 暴露两个语义不同的组件:@@ -38,13 +35,10 @@ Media Item one independent presentation with one projected windowMedia Sequence ordered members replace one another on one shared surface```-`Item` 和 `Sequence` 共享聚焦的值族和下降代码。它们之所以是两个独立组件,是因为拓扑、校验和端口-都不同。不存在 `mode="broll | sequence | overlay"` 这样的字段,也不存在“选了某个 mode 就冒出另一个-隐藏组件”的步骤。+`Item` 和 `Sequence` 共享聚焦的值族和下降代码。它们之所以是两个独立组件,是因为拓扑、校验和端口都不同。不存在 `mode="broll | sequence | overlay"` 这样的字段,也不存在“选了某个 mode 就冒出另一个隐藏组件”的步骤。深度堆叠的 Deck 被刻意排除在本包之外。它是更高阶的集合状态组件,而不是媒体原语。官方的迁移模型在-[`deck-track.md`](./deck-track.md) 中独立规定;未来的 Carousel、Fan、Grid 或其他 Deck 包并不必须采用-那套模型。+[`deck-track.md`](./deck-track.md) 中独立规定;未来的 Carousel、Fan、Grid 或其他 Deck 包并不必须采用那套模型。“B-roll” 仍是有用的剪辑术语或 Recipe 名称,但它不是公开的数据 Type。@@ -85,8 +79,7 @@ Surface 物化 Need。Provider 不会重新解释 placement、motion、transitio- 已归一化的定时视觉素材,带精确帧率、帧数和尺寸;- 带类型的 `CompositableSurface` 素材,带精确的静态/逐帧时序和 alpha 模式。-固有事实的所有者仍然是 `@narratage/media`。Media Track 包内部可以使用包内的已解析联合类型,但不得-再造一个通用媒体 Type,也不得把 provider、源路径、Narrative 摘要或上游血缘复制进每一个 item。+固有事实的所有者仍然是 `@narratage/media`。Media Track 包内部可以使用包内的已解析联合类型,但不得再造一个通用媒体 Type,也不得把 provider、源路径、Narrative 摘要或上游血缘复制进每一个 item。按文件名推断是非法的。具体来说:@@ -97,8 +90,7 @@ Surface 物化 Need。Provider 不会重新解释 placement、motion、transitio- 含音频的 MP4 不会因此就让那段音频可听;- 带 alpha 的视觉素材必须保留显式的 alpha 合同。-多个 Layer 可以引用同一个 Artifact。图和 Artifact 收集器会对字节做去重;渲染器仍然独立求值每一个-被声明的 sample。+多个 Layer 可以引用同一个 Artifact。图和 Artifact 收集器会对字节做去重;渲染器仍然独立求值每一个被声明的 sample。## 4. The orthogonal item model@@ -189,14 +181,11 @@ type MediaItemProgram = {SVML 拥有拓扑:source、Frame、时间引用、Item/Sequence 成员关系、Handoff 边、标签和声音输入。SVS 拥有具名的可复用参数包:Content Fit、frame Paint、裁剪、运动参数和转场外观。-SVS Recipe 不能隐藏一条 source 边,不能创建 member,不能选择 Provider,也不能让两个独立的 Item 变成-一个 Sequence。把一个转场 Recipe 应用到整个 Sequence,会在解析后的 Program 里把这个选择物化到每一条-被声明的 Handoff 上。因此 Recipe 既保持简洁,又不会退化成第二套图语言。+SVS Recipe 不能隐藏一条 source 边,不能创建 member,不能选择 Provider,也不能让两个独立的 Item 变成一个 Sequence。把一个转场 Recipe 应用到整个 Sequence,会在解析后的 Program 里把这个选择物化到每一条被声明的 Handoff 上。因此 Recipe 既保持简洁,又不会退化成第二套图语言。### Small framed inset with a smooth rise-小画框不是另一个组件。它就是一个普通 Item,只不过它显式的 Placement Frame 比 Canvas 小。使用点的-结构依然可读:+小画框不是另一个组件。它就是一个普通 Item,只不过它显式的 Placement Frame 比 Canvas 小。使用点的结构依然可读:```svml<space:AnchoredFrame id="product-inset" within={safe}@@ -233,17 +222,13 @@ motion.smooth-rise```“下方”必须无歧义。`below-canvas` 由 Canvas 和解析后的 Item 尺寸推导出一个画布外的起始位姿;-`offset-y: 120px` 则从最终 Frame 的下方开始,未必要离开画面。两者都下降为逐帧精确的局部变换,并且-都不改变最终的 Spatial Frame。+`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+普通的柔边或发光边缘下降为自有的 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 学会一种新的运动类型。+内置的缓动名称可以直接下降到 Visual IR。更复杂的贝塞尔或弹簧 Recipe 仍归 Media 包管,可以被确定性地采样为按帧寻址的关键帧;这不需要 Core、Composition 或 Runtime 学会一种新的运动类型。## 6. Independent Item timing@@ -257,12 +242,9 @@ Item 使用 [`track-authoring.md`](./track-authoring.md) 中的通用流水线6. 求值生命周期运动与采样运动;7. 产出自包含的 Present。-独立的 Item 保持独立。它们的窗口可以重叠,并按各自显式的绝对 stacking key 合成。Program 顺序不会让-它们互斥,不会裁掉优先级更低的 item,不会自动缝合空隙,也不会推断出一个 Sequence。+独立的 Item 保持独立。它们的窗口可以重叠,并按各自显式的绝对 stacking key 合成。Program 顺序不会让它们互斥,不会裁掉优先级更低的 item,不会自动缝合空隙,也不会推断出一个 Sequence。-全屏 B-roll 不过是一个 Placement Frame 等于 Canvas、前景 Layer 通常用 `cover` 的 Item。小图、GIF 或-视频只是同一个 Item 配上更小的 Frame。“不要挡住人脸”不是 Media 的某个 mode:作者要么消费一个合适的-具名 Frame,要么由上游具备主体感知能力的布局组件显式产出一个。+全屏 B-roll 不过是一个 Placement Frame 等于 Canvas、前景 Layer 通常用 `cover` 的 Item。小图、GIF 或视频只是同一个 Item 配上更小的 Frame。“不要挡住人脸”不是 Media 的某个 mode:作者要么消费一个合适的具名 Frame,要么由上游具备主体感知能力的布局组件显式产出一个。## 7. Ordered local layers@@ -292,8 +274,7 @@ type MediaSampleLayer = {- 替代衬底:由另一个显式 source 提供衬底 Layer;- 装饰卡片:Paint、border/阴影/内边距,再加一个或多个媒体 Layer。-每个媒体 Layer 都由自己的固有尺寸和 `ContentFit` 推导出自己的 Content Frame。不存在特殊的-前景/背景配对,也不存在唯一的共享内框。+每个媒体 Layer 都由自己的固有尺寸和 `ContentFit` 推导出自己的 Content Frame。不存在特殊的前景/背景配对,也不存在唯一的共享内框。Frame 级裁剪是显式的:不裁、裁到 Placement Frame,或裁到自有形状。圆角、border、阴影、内边距和frame Paint 都属于表现层。它们不能改变 Spatial 几何,也不能采样另一个 Track。@@ -313,12 +294,9 @@ loop/end choose phase so the source tail meets the window endstretch map the complete effective source interval onto the window```-不存在 `auto`、`native`、`finish`、`freeze` 或 `phased` 这类作者枚举值。图像不会被塞一个假的播放模式。-源 trim 在 occupancy 之前执行。空间上的 contain/cover 与时间上的 stretch 互不相干。+不存在 `auto`、`native`、`finish`、`freeze` 或 `phased` 这类作者枚举值。图像不会被塞一个假的播放模式。源 trim 在 occupancy 之前执行。空间上的 contain/cover 与时间上的 stretch 互不相干。-即使某个 `once` Layer 提前结束,Item 的目标窗口依然有效。其他 Paint 或媒体 Layer 可以继续存在。若作者-希望整个 item 保持可见,就选 `hold`、补一个常驻 Layer,或者直接写一个更短的目标窗口;编译器绝不会靠-猜哪个 Layer 是主 Layer 来收缩 Item。+即使某个 `once` Layer 提前结束,Item 的目标窗口依然有效。其他 Paint 或媒体 Layer 可以继续存在。若作者希望整个 item 保持可见,就选 `hold`、补一个常驻 Layer,或者直接写一个更短的目标窗口;编译器绝不会靠猜哪个 Layer 是主 Layer 来收缩 Item。## 9. Media motion has four separate channels@@ -338,13 +316,11 @@ type MediaSamplingMotion = {### Entry motion-作用于一个 Item 或 Group 在其可见包络起始处所拥有的全部像素。合理的带类型 Recipe 包括淡入、方向滑入、-缩放、弹出、回弹、局部模糊显现、擦除、翻转和旋转。+作用于一个 Item 或 Group 在其可见包络起始处所拥有的全部像素。合理的带类型 Recipe 包括淡入、方向滑入、缩放、弹出、回弹、局部模糊显现、擦除、翻转和旋转。### Sustain motion-作用于可见包络期间。漂浮、呼吸、脉冲、摇摆、抖动和漂移都是合理的算子。被声明的有序列表按确定性方式-求值;多个变换不会悄悄互相覆盖。+作用于可见包络期间。漂浮、呼吸、脉冲、摇摆、抖动和漂移都是合理的算子。被声明的有序列表按确定性方式求值;多个变换不会悄悄互相覆盖。### Exit motion@@ -355,9 +331,7 @@ type MediaSamplingMotion = {作用于某一个媒体 Layer 已完成 fit 的 Content Frame。归一化关键帧可以驱动缩放、源点/内容点位移和旋转。Ken Burns 是一个采样运动 Recipe,既不是 Base 特效,也不是 occupancy 模式。-即使 entry 与 exit 重叠,它们各自被声明的时长也保持不变。包在每一帧同时求值两者,并确定性地合成它们-彼此独立的 opacity、transform、filter 和 clip 通道。它绝不会按比例压缩任何一侧,也绝不会把 Item 跑两遍。-可见的 Item 窗口仍然是最终的裁剪边界。+即使 entry 与 exit 重叠,它们各自被声明的时长也保持不变。包在每一帧同时求值两者,并确定性地合成它们彼此独立的 opacity、transform、filter 和 clip 通道。它绝不会按比例压缩任何一侧,也绝不会把 Item 跑两遍。可见的 Item 窗口仍然是最终的裁剪边界。变换栈是固定的,因此各通道不会互相覆盖:@@ -378,8 +352,7 @@ absolute Present stacking## 10. Sequence: explicit member replacement-一个 Sequence 拥有两个或更多嵌套的 Member,它们共享一个 Placement Frame 和一个外层生命周期。它必须被-显式创建;相邻的 Item、重叠的窗口或某个转场 Recipe 都不会隐含成员关系。+一个 Sequence 拥有两个或更多嵌套的 Member,它们共享一个 Placement Frame 和一个外层生命周期。它必须被显式创建;相邻的 Item、重叠的窗口或某个转场 Recipe 都不会隐含成员关系。每个 Member 拥有:@@ -399,11 +372,9 @@ logical member 2 phase [p2, p3)logical member N phase [pN, T)```-源码中的 occurrence 顺序具有权威性。编译器绝不按物理时间排序。缺失、同帧、逆序或超出 Program 范围的-激活点,会让整个 Sequence 原子性失败。+源码中的 occurrence 顺序具有权威性。编译器绝不按物理时间排序。缺失、同帧、逆序或超出 Program 范围的激活点,会让整个 Sequence 原子性失败。-每一对相邻成员都拥有一条显式的 Handoff。不存在只活在编辑器或 Runtime 里的转场默认值;“应用到全部”-会把同一个被选中的转场物化到每一条边上。+每一对相邻成员都拥有一条显式的 Handoff。不存在只活在编辑器或 Runtime 里的转场默认值;“应用到全部”会把同一个被选中的转场物化到每一条边上。### Pair transition@@ -424,23 +395,19 @@ handoff.start = p - r × dhandoff.end = p + (1-r) × d```-帧量化保持转场总长度精确不变。相邻的 handoff 窗口不得重叠;非法时长直接失败,而不是造出一个隐式的-三源转场。+帧量化保持转场总长度精确不变。相邻的 handoff 窗口不得重叠;非法时长直接失败,而不是造出一个隐式的三源转场。-在 handoff 期间,退出与进入的 Member surface 都由该 Sequence 拥有。它们的媒体 sample 在各自被展开的-视觉跨度上连续播放。转场既不改变 ProgramSpace,也不改变上游的 Selection/Moment 点。+在 handoff 期间,退出与进入的 Member surface 都由该 Sequence 拥有。它们的媒体 sample 在各自被展开的视觉跨度上连续播放。转场既不改变 ProgramSpace,也不改变上游的 Selection/Moment 点。Sequence 的 handoff 只能在其共享的 Placement Frame 内部工作。这让 cut、crossfade、push、wipe、cover 和-page turn 都成为诚实的局部关系。针对 `composite_below` 的外层 handoff 被刻意废弃:它会读取并改动无关的-下层 Track。+page turn 都成为诚实的局部关系。针对 `composite_below` 的外层 handoff 被刻意废弃:它会读取并改动无关的下层 Track。Sequence 自身可以使用普通的 entry/exit 运动。在下层 Track 之上做全屏淡出是合法的,因为改变的只是Sequence 的不透明度;而把下层 Track 推走或翻页则不合法。## 11. Audio is explicit and projected separately-视觉素材默认静音,除非作者显式地从恰好一个具名媒体 Layer 中选取源音频。这是 item 级别的,因此前景与-它自身的模糊副本不会意外地把同一个源混两遍。+视觉素材默认静音,除非作者显式地从恰好一个具名媒体 Layer 中选取源音频。这是 item 级别的,因此前景与它自身的模糊副本不会意外地把同一个源混两遍。```tstype MediaSourceAudioProjection = {@@ -455,19 +422,16 @@ type MediaSourceAudioProjection = {- `crossfade` 使用显式声明的音频 handoff 窗口;- 视觉转场绝不会悄悄替你选一个音频转场。-entry/exit 或 handoff 的音效是显式的音频 Artifact 输入,带显式增益。它们在解析出的精确 entry、exit 或-边界点上下降。它们不是包级全局文件名、不是可变的音效库默认值,也不是隐藏的通道音效。+entry/exit 或 handoff 的音效是显式的音频 Artifact 输入,带显式增益。它们在解析出的精确 entry、exit 或边界点上下降。它们不是包级全局文件名、不是可变的音效库默认值,也不是隐藏的通道音效。-编译器不会返回一个同时包含两个终端 Track 的原子 `MediaProduct`。它解析出一个包自有的 Media Program,-并提供彼此独立的确定性投影 Operation:+编译器不会返回一个同时包含两个终端 Track 的原子 `MediaProduct`。它解析出一个包自有的 Media Program,并提供彼此独立的确定性投影 Operation:```textResolved Media Program ─┬─> project visual ─> VisualTrack└─> project audio ─> AudioTrack```-因此,任一终端输出都可以被 Run Graph 独立地定向、替换或满足。当两者同时被需求时,它们仍通过一条显式的-图边共享同一份已解析调度,而不是复制两份时序元数据。+因此,任一终端输出都可以被 Run Graph 独立地定向、替换或满足。当两者同时被需求时,它们仍通过一条显式的图边共享同一份已解析调度,而不是复制两份时序元数据。一个纯视觉 Item 不会仅因为它的源容器里带音频流,就去要求音频归一化或渲染。@@ -476,8 +440,7 @@ Resolved Media Program ─┬─> project visual ─> VisualTrackMedia Track 自身没有 z-index。每一个解析出的顶层 Item 或 Sequence surface,以及任何可被单独穿插的member/Layer,都会产出绝对的 Present stacking key。-frame Paint 与紧耦合的媒体 sample 可以留在同一棵 Present 局部元素树里。当对等 Track 必须能出现在某块-板、卡片、图标或 Layer 之间时,包会产出带独立绝对 key 的独立 Present。Track 归属关系绝不创建 stacking+frame Paint 与紧耦合的媒体 sample 可以留在同一棵 Present 局部元素树里。当对等 Track 必须能出现在某块板、卡片、图标或 Layer 之间时,包会产出带独立绝对 key 的独立 Present。Track 归属关系绝不创建 stacking上下文。Sequence handoff 内部的临时顺序由包自有,且只在该关系的那些帧内存在。它不会预留一条全局 z 带。@@ -500,22 +463,15 @@ no Sequence stateno source-audio projection```-Speech 的作者 Surface 接受原始 `video=`,并在装配前展开同一套通用的检查与归一化图,按 Spine 显式的-帧率选取主运动视频加默认音频。原始 `audio=` 展开为音频权威的归一化图,不贡献任何视觉 Present;它绝不-凭空造出黑场素材。已准备好的 `media=` 仍是直接的精确输入。视觉 Take 继承 Spine 显式的 `visual-frame`、-`visual-appearance` 和 `visual-z`,并可在这几个受限的轴上做逐 Take 覆盖。装配之后,Speech 音频仍走独立的-规范路径 `SpeechAudioBasis -> AudioTrack` 投影;受限的视觉下降器本身保持静音,不会去重新发现容器音频。+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 语义。+这可以是对聚焦的 Media 下降辅助函数的代码依赖。当没有任何外部组件消费那个中间值时,它并不需要暴露一个公开的 `MediaProgram` 图 Type。若日后真的出现图消费者,包可以暴露自己的带版本已解析 Type;Core 仍然不会注册 Media 语义。-作者导入的是 Speech Spine,其 manifest 声明了自身的包依赖。作者不需要仅仅因为实现复用了 Media 下降,-就再导入第二个解析器。+作者导入的是 Speech Spine,其 manifest 声明了自身的包依赖。作者不需要仅仅因为实现复用了 Media 下降,就再导入第二个解析器。普通 Media Item 可以直接消费 `during={story.segment.answer}`。这不是隐式 Selection:Temporal 解析的是-Segment 早已存在的结构性起止锚点。当作者的真实意图是 Selection 和 Moment 时,同一个 Item 仍然可以消费-它们。+Segment 早已存在的结构性起止锚点。当作者的真实意图是 Selection 和 Moment 时,同一个 Item 仍然可以消费它们。## 14. Legacy audit: retained and retired@@ -548,8 +504,7 @@ Segment 早已存在的结构性起止锚点。当作者的真实意图是 Selec- 外层 `composite_below` 转场以及一切 Base FX 依赖;- 把 VisualTrack 与 AudioTrack 的满足耦合在一起的打包式 B-roll Product。-旧的 Deck 行为在 [`deck-track.md`](./deck-track.md) 中独立迁移;把它从 Media Track 移除并不等于删掉这项-能力。+旧的 Deck 行为在 [`deck-track.md`](./deck-track.md) 中独立迁移;把它从 Media Track 移除并不等于删掉这项能力。## 15. Package and implementation shape@@ -575,9 +530,7 @@ depends on包内部可以使用聚焦的文件划分,或未来仅供实现使用的库。但它不得造出一个被 Text、Caption、Ranking 和Media 共用的大一统创作库,也不得在新增一个媒体 Recipe、运动算子或组件包时要求 Core 发版。-原先的 `@narratage/broll` 包在迁移期间用作回归见证,现已废弃。由于项目处于预发布阶段,不保留任何兼容包。-“B-roll” 仍是描述某个 Item 或 Sequence 的有用剪辑术语,而不是终端 Type 或作者包。源素材与生成文件保持-原样,不受影响。+原先的 `@narratage/broll` 包在迁移期间用作回归见证,现已废弃。由于项目处于预发布阶段,不保留任何兼容包。“B-roll” 仍是描述某个 Item 或 Sequence 的有用剪辑术语,而不是终端 Type 或作者包。源素材与生成文件保持原样,不受影响。## 16. Implementation orderdiff --git a/docs/zh/guide/spec/ranking-track.md b/docs/zh/guide/spec/ranking-track.mdindex bc482e2d..57bd697b 100644--- a/docs/zh/guide/spec/ranking-track.md+++ b/docs/zh/guide/spec/ranking-track.md@@ -6,16 +6,14 @@ description: 官方 Ranking 迁移的已实现可执行权威,包含全部四# SVML Ranking Track 迁移状态:官方 Ranking 迁移的已实现可执行权威。四个作者组件、它们共享的触发式调度、可选的同级 AudioTrack-lowering、作者 Surface 以及真实浏览器证据都在 `@narratage/ranking` 中执行。它不是对历史 node 格式的兼容-承诺,也不是冻结的公开 ABI。+lowering、作者 Surface 以及真实浏览器证据都在 `@narratage/ranking` 中执行。它不是对历史 node 格式的兼容承诺,也不是冻结的公开 ABI。## 1. Ranking 的含义Ranking 是一个视频领域的作者组件,它把一个有序集合呈现为渐进的视觉状态。它不是 Core 概念、不是通用的Track 模式、不是 Provider,也不是渲染器特性。-旧系统把四种本质不同的行为塞在同一个 `ranking_track` 节点和一个 `rankingType` 开关背后。新系统使用一个-物理包 `@narratage/ranking@1`,但暴露四个互相独立的作者组件:+旧系统把四种本质不同的行为塞在同一个 `ranking_track` 节点和一个 `rankingType` 开关背后。新系统使用一个物理包 `@narratage/ranking@1`,但暴露四个互相独立的作者组件:- `ranking:TierBoard` —— 把已揭示的条目放入具名的 tier 行;- `ranking:Column` —— 在舞台上展示一个当前条目,然后让它落位到带编号的列中;@@ -25,8 +23,7 @@ Track 模式、不是 Provider,也不是渲染器特性。一个包是共享校验、调度构造、布局工具和绘制原语的正确单位。四个组件是作者语义的正确单位。不存在公开的`rankingType`、模式选择输入、动态端口注册表或 Runtime 渲染器注册表。-第三方可以发布另一个 Ranking 包,无需在 Core 注册类型,也无需修改本包。安装并 import 该包后,它会通过-普通的模块机制贡献自己的 Surface、Type、validator 和 fragment 编译器。+第三方可以发布另一个 Ranking 包,无需在 Core 注册类型,也无需修改本包。安装并 import 该包后,它会通过普通的模块机制贡献自己的 Surface、Type、validator 和 fragment 编译器。## 2. 来自旧实现的证据@@ -81,25 +78,19 @@ Track 模式、不是 Provider,也不是渲染器特性。</ranking:Column>```-`during` 提供显式的外层窗口。`triggers` 提供一个有序的 Moment occurrence 集合。`terminal` 是最后一个活动-阶段的显式终点;它可以早于外层终点,从而让完全落位后的结果继续可见。组件要求 trigger occurrence 的数量-等于子条目的数量,并按作者书写顺序一一对应。+`during` 提供显式的外层窗口。`triggers` 提供一个有序的 Moment occurrence 集合。`terminal` 是最后一个活动阶段的显式终点;它可以早于外层终点,从而让完全落位后的结果继续可见。组件要求 trigger occurrence 的数量等于子条目的数量,并按作者书写顺序一一对应。外层 Selection 与 terminal Moment 都使用严格的 `one` 语义。trigger Moment 使用严格的 `each` 语义。外层 /-terminal 出现零次或多次、trigger 出现零次,以及任何 trigger 与条目的基数不匹配,都是编译错误;组件绝不会-自己挑一个方便的 occurrence。+terminal 出现零次或多次、trigger 出现零次,以及任何 trigger 与条目的基数不匹配,都是编译错误;组件绝不会自己挑一个方便的 occurrence。这种按位置配对由这四个组件声明,不是通用的 Core 行为。另一种第三方 Surface 可以给每个条目单独的 Moment边,并 lower 到同一套包内事实。-Style 声明与使用保持分离。SVS 提供具名的通用 Recipe 数据;每个变体专属的 `*Style` 组件拥有各自允许的-键,并把 Recipe 加上显式的字体边编译成一个带类型、由包拥有的 Style。诸如 tier 行、标签、图标和入场行为-这类语义化的条目值不是绘制属性,不属于 SVS。+Style 声明与使用保持分离。SVS 提供具名的通用 Recipe 数据;每个变体专属的 `*Style` 组件拥有各自允许的键,并把 Recipe 加上显式的字体边编译成一个带类型、由包拥有的 Style。诸如 tier 行、标签、图标和入场行为这类语义化的条目值不是绘制属性,不属于 SVS。## 4. 组能看到兄弟,渲染出的 Track 不能-渐进式 ranking 不能通过把每个子项当作孤立的 Track item 来编译。行位置、后继交接、活动条目状态和已落位的-前缀都依赖这个有序的组。但这不意味着条目在渲染时互相检视。+渐进式 ranking 不能通过把每个子项当作孤立的 Track item 来编译。行位置、后继交接、活动条目状态和已落位的前缀都依赖这个有序的组。但这不意味着条目在渲染时互相检视。作者组件首先把完整的子项列表和 trigger 集合编译成一份包内私有的调度:@@ -138,8 +129,7 @@ Moment set + SemanticMap + ProgramSpace + outer/terminal projection + ordered itouter.start <= p1 < p2 < ... < pN < terminal <= outer.end```-任何非法或帧相等的序列都会整体失败。视觉与可选音频的 lowerer 消费同一份调度,因此运动与声音不会漂移,-同时它们仍然是 Run Graph 中可以各自独立被 demand 的分支。+任何非法或帧相等的序列都会整体失败。视觉与可选音频的 lowerer 消费同一份调度,因此运动与声音不会漂移,同时它们仍然是 Run Graph 中可以各自独立被 demand 的分支。## 5. 共同的阶段模型@@ -151,9 +141,7 @@ cumulative life [p_i, O)settled life [stage.end, O)```-`[B, p1)` 可以显示作者显式声明的空看板,但没有隐含的活动条目。`[T, O)` 是可选的完全落位后缀,没有活动-条目。这些事实是由包拥有的兄弟排序,建立在 [`track-authoring.md`](./track-authoring.md) 的共享时间投影-代数之上;它们不是一个新的 `Stage` 合同。+`[B, p1)` 可以显示作者显式声明的空看板,但没有隐含的活动条目。`[T, O)` 是可选的完全落位后缀,没有活动条目。这些事实是由包拥有的兄弟排序,建立在 [`track-authoring.md`](./track-authoring.md) 的共享时间投影代数之上;它们不是一个新的 `Stage` 合同。### TierBoard@@ -190,13 +178,11 @@ settled life [stage.end, O)- 标题、可选的显式强调区间和各行字符串都是作者内容,不是 LLM 字段。Typewriter 之所以留在 Ranking 包里,是因为尽管它大量使用文本排版,它的作者语义仍然是一个有序的渐进-ranking。它可以与未来的 Text 实现共享底层的精确字体 / 排版工具,但不得依赖通用 Text Track Program,也不得-冒充成它。+ranking。它可以与未来的 Text 实现共享底层的精确字体 / 排版工具,但不得依赖通用 Text Track Program,也不得冒充成它。## 6. 空间布局与 stacking-每个组件拥有一个外层放置框和它自己的内部布局算法。Tier 单元格、Column 行或 Top Three 槽位不是通用的-逐条目空间定位器。允许在这些子项上传入任意空间输入会摧毁组件的语义。+每个组件拥有一个外层放置框和它自己的内部布局算法。Tier 单元格、Column 行或 Top Three 槽位不是通用的逐条目空间定位器。允许在这些子项上传入任意空间输入会摧毁组件的语义。放置与 stacking 保持独立:@@ -207,8 +193,7 @@ ranking。它可以与未来的 Text 实现共享底层的精确字体 / 排版- 产出的那一个 `VisualTrack` 不是 stacking context,因此同级 Track 的 Present 可以出现在看板与任意图标之间。-任何包都不应仅仅为了获得多个 z 位置而发出多个 Track。稳定的 `tieBreak` 值来自作者声明的组件 / 条目身份,-绝不来自求值顺序。+任何包都不应仅仅为了获得多个 z 位置而发出多个 Track。稳定的 `tieBreak` 值来自作者声明的组件 / 条目身份,绝不来自求值顺序。所有归一化几何都相对于显式的外层框。各变体必需的尺寸参数包括:@@ -217,8 +202,7 @@ ranking。它可以与未来的 Text 实现共享底层的精确字体 / 排版- Top Three:中心 / 宽度、标签行、图标尺寸、光环宽度 / 配色以及揭示 / 强调运动;- Typewriter:纸张主题 / 绘制、内边距、行距、标题 / 条目排印、旋转、打字速度以及获胜标记的绘制 / 运动。-绘制、几何和运动参数由拥有它们的 `*Style` 组件校验。未知的 Recipe 属性一律失败。不存在任意的 CSS 逃生-出口。+绘制、几何和运动参数由拥有它们的 `*Style` 组件校验。未知的 Recipe 属性一律失败。不存在任意的 CSS 逃生出口。## 7. 媒体、字体与声音@@ -233,16 +217,13 @@ URL、不要求 Runtime 挑选字体,也不指名某个渲染器组件。- 配置了声音就产出同级的 `AudioTrack`;没有声音就不产生被 demand 的音频分支;- 声音播放绝不进入 Hyperframes 或某个视觉 Track。-Ranking 自身是确定性的,没有 Need、Provider、队列、凭据或环境适配器。如果输入图像是生成出来的,那次上游-生成仍然是另一个 Graph 组件。+Ranking 自身是确定性的,没有 Need、Provider、队列、凭据或环境适配器。如果输入图像是生成出来的,那次上游生成仍然是另一个 Graph 组件。## 8. Run Graph 行为-作者图导出普通的逻辑 `visual` 结果,以及在作者声明时导出 `audio` 结果。Target、Candidate 和替换受与其他-所有组件相同的 Run Graph 法则约束。Ranking 不新增任何缓存、pin 或预览原语。+作者图导出普通的逻辑 `visual` 结果,以及在作者声明时导出 `audio` 结果。Target、Candidate 和替换受与其他所有组件相同的 Run Graph 法则约束。Ranking 不新增任何缓存、pin 或预览原语。-替换视觉结果不会改动音频结果。通过普通的显式输出映射,也可以用一个多输出 Candidate 同时替换两个输出。-一旦每个被 demand 的原始输出都由选定的 Candidate 满足,demand 分析就会剪掉原来的 Ranking 分支及其时间 /+替换视觉结果不会改动音频结果。通过普通的显式输出映射,也可以用一个多输出 Candidate 同时替换两个输出。一旦每个被 demand 的原始输出都由选定的 Candidate 满足,demand 分析就会剪掉原来的 Ranking 分支及其时间 /媒体祖先。不需要任何特殊的 Ranking 执行规则。## 9. 迁移顺序与验收@@ -271,9 +252,6 @@ Ranking 自身是确定性的,没有 Need、Provider、队列、凭据或环Program;- 安装第五个组件包不需要改动任何中心家族注册表。-本次迁移有意不保留历史 node JSON、模式切换、旧的动态端口、渲染器 id 或 Remotion 组件。历史项目是证据和-视觉参考,不是一门尚未发布的语言的兼容义务。+本次迁移有意不保留历史 node JSON、模式切换、旧的动态端口、渲染器 id 或 Remotion 组件。历史项目是证据和视觉参考,不是一门尚未发布的语言的兼容义务。-包的测试矩阵覆盖上述每一条验收项。可选启用的 Chromium 见证会用单 worker 与分区 worker 分别求值全部四个-组件,证明可见的 trigger 推进和最终的落位后缀,并且只对跨进程边缘抗锯齿的微观噪声设定容差。逻辑帧状态、-几何、stacking、事件帧和作者声明的图边都保持精确。+包的测试矩阵覆盖上述每一条验收项。可选启用的 Chromium 见证会用单 worker 与分区 worker 分别求值全部四个组件,证明可见的 trigger 推进和最终的落位后缀,并且只对跨进程边缘抗锯齿的微观噪声设定容差。逻辑帧状态、几何、stacking、事件帧和作者声明的图边都保持精确。diff --git a/docs/zh/guide/spec/screen-overlay.md b/docs/zh/guide/spec/screen-overlay.mdindex fa29ee38..c7b47547 100644--- a/docs/zh/guide/spec/screen-overlay.md+++ b/docs/zh/guide/spec/screen-overlay.md@@ -10,8 +10,7 @@ description: 可选官方 Screen Overlay 包的已实现预发布合同及其自## 目的-`@narratage/screen-overlay` 在作者声明的时间窗口内贡献自包含的、通常是全画布的像素。一次 Flash、暗角、-扫描线薄纱或确定性漏光,都只是普通的 `VisualTrack`,与 Text、Caption、Media 或 Ranking 完全一样。+`@narratage/screen-overlay` 在作者声明的时间窗口内贡献自包含的、通常是全画布的像素。一次 Flash、暗角、扫描线薄纱或确定性漏光,都只是普通的 `VisualTrack`,与 Text、Caption、Media 或 Ranking 完全一样。它不是调整图层、不是有特权的后合成钩子、不是转场引擎,也不是读取下层 Track 像素的手段。@@ -45,13 +44,9 @@ Core、Runtime 和 Composition 都不认识 Screen Overlay。Composition 只校- 上一个或下一个场景;- 浏览器 backdrop 或环境纹理。-普通的 source-over alpha 合成是允许的:每个带 alpha 的 Track 都是这样抵达画布的。凡是结果依赖未知下层像素-的混合模式或滤镜,都不是自包含的。+普通的 source-over alpha 合成是允许的:每个带 alpha 的 Track 都是这样抵达画布的。凡是结果依赖未知下层像素的混合模式或滤镜,都不是自包含的。-这条法则意味着旧的、无源的 `backdrop-filter` 版高斯模糊、Color Adjust 和 Zoom Blur 都不是 Screen Overlay。-若要诚实地保留这些效果,媒体效果组件必须通过图边接收要变换的精确媒体或可合成 Surface,然后输出它自己-变换后的素材或 Track。如果将来某个组件显式地把一组选定的 Track 光栅化成一个 Surface,消费那个 Surface 同样-是显式的;Screen Overlay 永远不会获得一个隐秘的“当前帧”输入。+这条法则意味着旧的、无源的 `backdrop-filter` 版高斯模糊、Color Adjust 和 Zoom Blur 都不是 Screen Overlay。若要诚实地保留这些效果,媒体效果组件必须通过图边接收要变换的精确媒体或可合成 Surface,然后输出它自己变换后的素材或 Track。如果将来某个组件显式地把一组选定的 Track 光栅化成一个 Surface,消费那个 Surface 同样是显式的;Screen Overlay 永远不会获得一个隐秘的“当前帧”输入。## 2. 作者包,不是算子注册表@@ -69,15 +64,13 @@ Core、Runtime 和 Composition 都不认识 Screen Overlay。Composition 只校</screen:Track>```-这只是示意性的 Surface 语法。编译出的 Program 包含显式的组件身份、参数和时间绑定;它不是一个由 Core 拥有-的、字符串化的 `effect="..."` 开关。+这只是示意性的 Surface 语法。编译出的 Program 包含显式的组件身份、参数和时间绑定;它不是一个由 Core 拥有的、字符串化的 `effect="..."` 开关。对这个小规模的官方集合来说,一个包很方便,但它不是中心注册表。第三方可以发布另一个自描述的包,把新组件lower 到同一个 Visual Track 窄腰。只要现有的 Visual IR 或一个带类型的 Surface 能表达出来,新增一个 overlay就不得要求改动 Core、Film、Composition 或 HyperFrames。-外观默认值和具名组合属于 `.svs` recipe。包拥有参数校验和确定性 lowering。Runtime Profile 与 Provider 不-选择视觉效果。+外观默认值和具名组合属于 `.svs` recipe。包拥有参数校验和确定性 lowering。Runtime Profile 与 Provider 不选择视觉效果。## 3. Program 的各个轴@@ -98,12 +91,10 @@ type ScreenOverlayItemSpec = {- `projection` 与 `expansion` 使用共享的 Selection / Moment / Program 代数;- `stackingOrder` 结合稳定的作者身份解析为一个普通的绝对 Present 键。-画布几何在这里不是作者选择的 Spatial Frame。Screen Overlay 有意拥有整个连接进来的 CanvasSpace。局部画面的-光效、图像、卡片或模糊属于普通的 Media、Text 或组件 Track,使用+画布几何在这里不是作者选择的 Spatial Frame。Screen Overlay 有意拥有整个连接进来的 CanvasSpace。局部画面的光效、图像、卡片或模糊属于普通的 Media、Text 或组件 Track,使用[`spatial-layout.md`](./spatial-layout.md)。-条目默认相互独立。重叠是合法的,会产生多个普通 Present。不存在单例的 Screen Overlay 泳道,也没有全局的-合并步骤。+条目默认相互独立。重叠是合法的,会产生多个普通 Present。不存在单例的 Screen Overlay 泳道,也没有全局的合并步骤。## 4. 时间与局部包络@@ -111,12 +102,9 @@ Selection、Moment、Program 和绝对时间都通过 [`track-authoring.md`](./t没有自己的 `from`、`until`、`manual` 或短语匹配式的时间法则。投影出的窗口只回答条目在哪里存在。窗口内的包络属于组件呈现。例如 Flash 可以定义 attack、峰值和 decay;-Directional Matte 可以把一条边从一侧移到另一侧;Grain 可以保持稳定。旧的那个在每个效果时长 30% 处达到峰值-的通用三角包络,作为隐藏的呈现策略被废弃。+Directional Matte 可以把一条边从一侧移到另一侧;Grain 可以保持稳定。旧的那个在每个效果时长 30% 处达到峰值的通用三角包络,作为隐藏的呈现策略被废弃。-Recipe 默认值可以提供包络,但解析后的 Program 必须包含精确的参数。效果不能为了容纳动画而扩张自己投影出的-窗口。作者写得更长的包络只会被该窗口裁剪;它不会被拒绝,也不会被偷偷加速。非法或零长度的窗口仍然通过公共-时间 validator 失败。+Recipe 默认值可以提供包络,但解析后的 Program 必须包含精确的参数。效果不能为了容纳动画而扩张自己投影出的窗口。作者写得更长的包络只会被该窗口裁剪;它不会被拒绝,也不会被偷偷加速。非法或零长度的窗口仍然通过公共时间 validator 失败。## 5. 可移植的官方组件集@@ -136,17 +124,14 @@ Recipe 默认值可以提供包络,但解析后的 Program 必须包含精确### 自有 Surface 的候选-把它们做成确定性的、带 alpha 的 `CompositableSurface` 值可能更容易或更精确,但当前的官方实现正好能完全-落在封闭的、无代码的 Visual IR 里:+把它们做成确定性的、带 alpha 的 `CompositableSurface` 值可能更容易或更精确,但当前的官方实现正好能完全落在封闭的、无代码的 Visual IR 里:- `Grain` —— 数量、颗粒尺寸、单色 / 彩色、运动速率和必需的 seed;- `LightLeak` —— 颜色、角度、柔和度、行程、强度,以及随机时必需的 seed;- `Bokeh` —— 数量、尺寸范围、颜色 / 色温、漂移和必需的 seed;- `TVStatic` —— 数量、噪点尺寸、扫描线贡献、运动速率和必需的 seed。-只有当两种方式都产出完全相同的声明像素时,选择 Visual IR 还是 Surface 才是 lowerer 的实现决策。它不能取决-于恰好由哪个 Runtime 执行这次 Build。做实体化的实现可以发出一次普通的 Provider Need,但该 Need 返回的是带-类型的自有 Surface,而不会收到下层合成结果。+只有当两种方式都产出完全相同的声明像素时,选择 Visual IR 还是 Surface 才是 lowerer 的实现决策。它不能取决于恰好由哪个 Runtime 执行这次 Build。做实体化的实现可以发出一次普通的 Provider Need,但该 Need 返回的是带类型的自有 Surface,而不会收到下层合成结果。一切随机行为都要求一个显式解析出的 seed。`Math.random()`、墙上时钟、GPU 噪声或依赖渲染器的熵都是非法的。@@ -171,20 +156,15 @@ Screen Overlay 同样不能:- 预留最顶层的 z-index;- 把音效藏在视觉条目内部。-被视觉遮盖的硬切仍然是两个独立事实:Media 包拥有那个切点,而 Screen Overlay 恰好覆盖了其中一些帧。作者-组合出的 `Impact` Fragment 可以从同一个 Moment 产出一个 Visual Track 和一个 Audio Track,但两个输出仍然是-进入 Film 的显式同级边。+被视觉遮盖的硬切仍然是两个独立事实:Media 包拥有那个切点,而 Screen Overlay 恰好覆盖了其中一些帧。作者组合出的 `Impact` Fragment 可以从同一个 Moment 产出一个 Visual Track 和一个 Audio Track,但两个输出仍然是进入 Film 的显式同级边。## 7. Stacking-旧的固定 `z_index: 200` 规则被废弃。“Screen”描述的是全画布几何,不是某个魔法渲染阶段。每个 Present 都获得-一个显式的绝对 stacking 意图,Composition 把它与其他所有 Present 一同展平。+旧的固定 `z_index: 200` 规则被废弃。“Screen”描述的是全画布几何,不是某个魔法渲染阶段。每个 Present 都获得一个显式的绝对 stacking 意图,Composition 把它与其他所有 Present 一同展平。-作者可以有意把暗角放在字幕之下、把闪光放在字幕之上,或者把颗粒放在两个图形层之间。包的 recipe 可以提供-方便的 stacking 默认值,但 Film 和 Composition 绝不会按包的家族做分支,也绝不会强行把它顶到最上层。+作者可以有意把暗角放在字幕之下、把闪光放在字幕之上,或者把颗粒放在两个图形层之间。包的 recipe 可以提供方便的 stacking 默认值,但 Film 和 Composition 绝不会按包的家族做分支,也绝不会强行把它顶到最上层。-如果某个 overlay 包在不同的 stacking 位置发出多个 Present,同级 Track 可以按照扁平 Track 法则的要求在它们-之间交错。+如果某个 overlay 包在不同的 stacking 位置发出多个 Present,同级 Track 可以按照扁平 Track 法则的要求在它们之间交错。## 8. 旧系统迁移审计@@ -224,5 +204,4 @@ Screen Overlay 同样不能:8. **已实现:** 多个 Overlay Track 按 stacking 键与同级 Track 交错;9. **已实现:** 拒绝任何下层合成结果、兄弟 Track、backdrop-filter 或隐藏音频依赖的反例测试。-如果新增一个 overlay 需要在 Core 里加分支、在 Composition 里加家族、在 HyperFrames 里加组件开关,或者需要-对已合成像素做隐式快照,那么这个设计就是失败的。+如果新增一个 overlay 需要在 Core 里加分支、在 Composition 里加家族、在 HyperFrames 里加组件开关,或者需要对已合成像素做隐式快照,那么这个设计就是失败的。diff --git a/docs/zh/guide/spec/script-surface.md b/docs/zh/guide/spec/script-surface.mdindex cd38a9d2..c0e0fc9c 100644--- a/docs/zh/guide/spec/script-surface.md+++ b/docs/zh/guide/spec/script-surface.md@@ -12,10 +12,7 @@ description: Script 作者面的规范性合同:Segment、Role Cue、Dual Text> parser、projection、source-map 和 temporal golden fixtures 后,才可声称> 支持 SVML v1。-SVML 是语义视频源语言,不是像素渲染格式。本文只定义它最高频、最需要保持-可读性的稿子区 `<script>`;画布、节点、样式、生成参数和其他 Program 区域的-外层文档结构另行设计。v1 发布后,新增语义应首先组合本文已有构造;确需改变-正文语法时再发布新版本,不能因为早期原型行为而削弱当前 v1。+SVML 是语义视频源语言,不是像素渲染格式。本文只定义它最高频、最需要保持可读性的稿子区 `<script>`;画布、节点、样式、生成参数和其他 Program 区域的外层文档结构另行设计。v1 发布后,新增语义应首先组合本文已有构造;确需改变正文语法时再发布新版本,不能因为早期原型行为而削弱当前 v1。## 一页合同@@ -30,14 +27,11 @@ SVML 是语义视频源语言,不是像素渲染格式。本文只定义它最| `Moment` | 一个或多个显式完整的语义时刻 | 半截区间、持续时间 || `Slot` | 注入运行时文字值 | 注入 SVML 语法或任意 AST |-注释是 trivia,不是第七种语义构造。任何字幕样式、B-roll、Ranking、Deck、-音效、静音、生成提示、节点端口和消费策略都在 `<script>` 外引用-Selection 或 Moment。消费者不归属于某个 Segment;一个消费者可有多个-端口,每个端口可接一个或多个 Selection/Moment。Selection 可以跨 Segment+注释是 trivia,不是第七种语义构造。任何字幕样式、B-roll、Ranking、Deck、音效、静音、生成提示、节点端口和消费策略都在 `<script>` 外引用+Selection 或 Moment。消费者不归属于某个 Segment;一个消费者可有多个端口,每个端口可接一个或多个 Selection/Moment。Selection 可以跨 Segment或由非连通区间组成,Moment 也可以有多个 occurrence。-Script 编译必须先生成保留源码映射的 Narrative IR,再从同一份 IR 投影三种-文本。禁止先生成三个互不相关的字符串,再猜它们之间的对应关系。+Script 编译必须先生成保留源码映射的 Narrative IR,再从同一份 IR 投影三种文本。禁止先生成三个互不相关的字符串,再猜它们之间的对应关系。| 投影 | 内容 | 典型消费者 ||---|---|---|@@ -67,8 +61,7 @@ Script 编译必须先生成保留源码映射的 Narrative IR,再从同一份</script>```-若 `product = "SVML"`、`product_pronunciation = "ess vee em ell"`,三个文本投影-分别是:+若 `product = "SVML"`、`product_pronunciation = "ess vee em ell"`,三个文本投影分别是:```textdialogue@@ -86,14 +79,12 @@ Meet SVML.`silence` 只是 Selection 的名字,不会自动让音频静音。它完整选择了空Segment 的两个独立结构端点;真正的静音或素材行为由外部 Program 决定。-`pop` 是一个默认吸右的 Moment,解析到 `laughed` 的起音;它同样不进入-任何文本投影。+`pop` 是一个默认吸右的 Moment,解析到 `laughed` 的起音;它同样不进入任何文本投影。## 1. 文档与 Segment在官方 Markup Frontend 中,一个 `<script>` Surface 实例产生一份 Narrative;-`<script>` 外壳由 Text 根据导入后的 Surface Registry 分派,Script Parser 接收的-只是它的 raw body。Script body 的 Segment 形式只有具名块和具名空块:+`<script>` 外壳由 Text 根据导入后的 Surface Registry 分派,Script Parser 接收的只是它的 raw body。Script body 的 Segment 形式只有具名块和具名空块:```svml<intro>@@ -136,8 +127,7 @@ Segment 的两个独立结构端点;真正的静音或素材行为由外部 Pr## 2. Role Cue-Role Cue 只在 Parser 已进入某个 Segment body 后出现,并开启一个 spoken turn。-它的识别由解析状态决定,与逻辑行首和物理换行无关:+Role Cue 只在 Parser 已进入某个 Segment body 后出现,并开启一个 spoken turn。它的识别由解析状态决定,与逻辑行首和物理换行无关:```svml<dialogue>@@ -162,8 +152,7 @@ B: It’s 8:30.在 `speech` 和 `caption` 投影中,`<A>`、`<B>` 都被移除。Role Cue 不是speaker 数据模型,不建立人物实体,不选择音色,也不对字幕隐式分组。外部-Program 可以显式写 `role="A"` 查询这些 spoken turn。Caption Program 将这类-查询直接降低为 `CaptionDisplayWordSubset`;它不是时间 Selection,也不伪造 Selection+Program 可以显式写 `role="A"` 查询这些 spoken turn。Caption Program 将这类查询直接降低为 `CaptionDisplayWordSubset`;它不是时间 Selection,也不伪造 SelectionRecord。仅有 `<A>` 本身不触发任何样式、人物、音色或素材行为。为消除歧义:@@ -219,11 +208,9 @@ Dual Text 是一个不可嵌套的原子对应单元,而不是简单的字符<lmao | laughed my @middle ass out @/middle>```-`middle` 可以供 B-roll 或音效使用;若它被用作该 `lmao` 的局部字幕替换区,-则必须报错。作者可通过拆分原子提供明确映射。+`middle` 可以供 B-roll 或音效使用;若它被用作该 `lmao` 的局部字幕替换区,则必须报错。作者可通过拆分原子提供明确映射。-Dual Text 只表达“实际说了什么”。IPA、SSML、重音、语速、语种、情绪、-音色和厂商专用发音字典不是第四种正文文本层,应由外部生成/语音 Program+Dual Text 只表达“实际说了什么”。IPA、SSML、重音、语速、语种、情绪、音色和厂商专用发音字典不是第四种正文文本层,应由外部生成/语音 Program引用 Selection 或词典资源表达。## 4. Selection@@ -236,10 +223,7 @@ Selection 是由作者显式闭合的语义区间声明:```每个开始标记都必须有同 id 的结束标记。Script 的公开值为每个 occurrence-输出已经解析好的 `startAnchorId` 与 `endAnchorId`;不存在 start-only 对象、-消费者默认补尾或“信息传了一半”的状态。左右 affinity、token 下标和源码范围-属于 Parser/Source Map,不泄漏到公开 Selection。需要物理时间的下游必须把这-两个身份与显式连接的 `CompleteSemanticMap` 投影为区间。+输出已经解析好的 `startAnchorId` 与 `endAnchorId`;不存在 start-only 对象、消费者默认补尾或“信息传了一半”的状态。左右 affinity、token 下标和源码范围属于 Parser/Source Map,不泄漏到公开 Selection。需要物理时间的下游必须把这两个身份与显式连接的 `CompleteSemanticMap` 投影为区间。“闭合”指源码的两个端点都被明确声明。物理运行时使用半开`[startFrame, endFrameExclusive)` Frame Span。@@ -292,8 +276,7 @@ before ~@x hello @/x~ after@a one @b two @/a three @/b```-规范要求解析器按 id 管理开放状态,而不是使用一条全局栈。以下情况必须-失败:+规范要求解析器按 id 管理开放状态,而不是使用一条全局栈。以下情况必须失败:- 未闭合、孤立 close 或 open/close id 不一致;- 同一个 id 尚未闭合就再次 open;@@ -305,8 +288,7 @@ SelectionSet 以及同一集合的不同 occurrence 可以在物理时间上重### 4.3 可选时间边界-Slot 绑定、Dual Text speech 投影和 NFC 归一化之后,v1 使用规范定义的-确定性 `speech-tokenizer-v1`:+Slot 绑定、Dual Text speech 投影和 NFC 归一化之后,v1 使用规范定义的确定性 `speech-tokenizer-v1`:- 东亚表意文字和假名单字符成 token;- 其他受支持文字/数字脚本形成最大连续 run;@@ -314,8 +296,7 @@ Slot 绑定、Dual Text speech 投影和 NFC 归一化之后,v1 使用规范- 空白、标点、emoji 和其他分隔字符不产生词法 token。因此标点本身不可被计时,Selection/Moment 也不可切入单个 token。v1-编译器在移除零宽标记后再 tokenization,所以未来若需要字素、音节或音素-边界,可以在新的 timing profile / Script Surface 版本中复用相同的+编译器在移除零宽标记后再 tokenization,所以未来若需要字素、音节或音素边界,可以在新的 timing profile / Script Surface 版本中复用相同的Selection/Moment 类型;v1 不应为尚不存在的精度引入新正文符号。若 Script 有 `N` 个 Segment,第 `k` 个 Segment 有 `mₖ` 个 speech token,且@@ -338,8 +319,7 @@ segment[k].end```Program 起点和终点属于 ProgramBasis,不额外进入 Semantic Anchor Index。空-Segment 仍有独立 start/end,即使二者最终重合;任意不同 identity 即使最终-落到同一帧也不能合并。+Segment 仍有独立 start/end,即使二者最终重合;任意不同 identity 即使最终落到同一帧也不能合并。Locator 必须提交覆盖全部 `2M + 2N` identity 的总映射:@@ -351,11 +331,7 @@ SemanticAnchorIdentity → ProgramPoint(ProgramSpace)切点在此完全平等:段首标记左吸附取该 Segment 自己的起始切点,绝不越到前一个Segment 的词尾。下游拿到的是 anchor 身份,不再自行做下标推算。-定位是全覆盖的:每个 Segment 的每个 token 都带有窗口,无论它被测得、由相邻-字符推得,还是因为转写从未触及而由插值补出。窗口倒序、越出所属 Segment 或-与邻居重叠,都按测得原样报出;那是关于录音的事实,如何解释属于把它投影到-时间轴的那一方。定位只在 Script、音频与转写不是同一组三件事时失败,绝不因为-一个时间戳而失败。+定位是全覆盖的:每个 Segment 的每个 token 都带有窗口,无论它被测得、由相邻字符推得,还是因为转写从未触及而由插值补出。窗口倒序、越出所属 Segment 或与邻居重叠,都按测得原样报出;那是关于录音的事实,如何解释属于把它投影到时间轴的那一方。定位只在 Script、音频与转写不是同一组三件事时失败,绝不因为一个时间戳而失败。每个点都必须存在。消费者不得补点、移动点或从相邻 occurrence 借点。每个 Segment内部必须非降序:@@ -371,8 +347,7 @@ A.start ≤ B.startA.end ≤ B.end```-这允许硬切、重叠与留白,同时禁止一个 Locator 把后写的整个 Segment 静默排到-前写 Segment 之前:+这允许硬切、重叠与留白,同时禁止一个 Locator 把后写的整个 Segment 静默排到前写 Segment 之前:```texthard cut A.end == B.start@@ -383,14 +358,10 @@ gap B.start > A.end若未来需要真正重排或并行 speech,应发布显式的非线性叙事模型;v1 不让普通Range 在不同 Locator 下反向或消失。-同一份 Selection 在不同 fulfillment 产生的 `CompleteSemanticMap` 上可得到-预览或成片区间。Map 使用相同 identity。Script 本身不含秒数、帧号或采样点。-Script Surface 不绑定帧率、采样率或渲染器。后端一旦选择物理时钟,必须只-量化一次并让所有消费者复用同一整数边界;后端时钟变化不改变本语言表面。+同一份 Selection 在不同 fulfillment 产生的 `CompleteSemanticMap` 上可得到预览或成片区间。Map 使用相同 identity。Script 本身不含秒数、帧号或采样点。+Script Surface 不绑定帧率、采样率或渲染器。后端一旦选择物理时钟,必须只量化一次并让所有消费者复用同一整数边界;后端时钟变化不改变本语言表面。-对齐、结构端点、projection 或帧量化可能使某个 occurrence 最终成为零长或-反向区间。实现必须产生明确诊断,不能静默丢弃、移动 Selection 端点、借用-相邻 occurrence 或替作者补范围。+对齐、结构端点、projection 或帧量化可能使某个 occurrence 最终成为零长或反向区间。实现必须产生明确诊断,不能静默丢弃、移动 Selection 端点、借用相邻 occurrence 或替作者补范围。## 5. Moment@@ -458,8 +429,7 @@ at="phrase.start" <!-- SelectionSet 的各 range 起点投影 -->at="phrase.end" <!-- SelectionSet 的各 range 终点投影 -->```-`at="phrase"` 不得默认猜成 start,`during="pop"` 也必须类型报错。一个-消费者若同时需要窗口和触发点,必须使用两个字段/端口,而不是构造+`at="phrase"` 不得默认猜成 start,`during="pop"` 也必须类型报错。一个消费者若同时需要窗口和触发点,必须使用两个字段/端口,而不是构造`Range | Point | mixed[]` 的多态 TemporalRef。端口需要 `one` 还是 `each`属于消费者 cardinality 契约,不改变 Script 的单/多 occurrence 语法。@@ -476,9 +446,7 @@ ${product}<${product} | ${product_pronunciation}>```-Slot id 经 NFC 后必须由 1–64 个字符组成:首字符为 Unicode Letter 或 `_`,-其余字符可为 Unicode Letter、Mark、Decimal Number、`_` 或 `-`。绑定值是-单行 Unicode 纯文本,不能含 CR/LF 或控制字符。+Slot id 经 NFC 后必须由 1–64 个字符组成:首字符为 Unicode Letter 或 `_`,其余字符可为 Unicode Letter、Mark、Decimal Number、`_` 或 `-`。绑定值是单行 Unicode 纯文本,不能含 CR/LF 或控制字符。关键安全规则:@@ -531,16 +499,12 @@ temporal name namespace。三者的 id 均满足:边界保留必要分隔并规范化布局空白;字幕 cue 切分与硬换行由外部 CaptionProgram 决定。-结构标签和注释不依靠独占一行才被解析。规范 formatter 把结构标签和注释-各自放在独立行,使用两空格缩进 Segment、四空格缩进 Segment 内的 spoken+结构标签和注释不依靠独占一行才被解析。规范 formatter 把结构标签和注释各自放在独立行,使用两空格缩进 Segment、四空格缩进 Segment 内的 spokencontent,并在 Segment 之间留一空行。formatter 前后重新解析所得 NarrativeIR 的语义内容必须相同;允许变化的只有 source range 和 source hash。注释使用 `<!-- ... -->`,可以跨行但不能嵌套,也不能写进 Dual Text、Slot、-temporal marker、Role Cue 或结构标签内部。注释可出现在 atom 之间允许布局-空白的位置,并按布局空白处理;规范 formatter 将其独占一行。注释不进入-任何投影、token、Selection、Moment 或 hash 的语义内容;需要可复现源码-身份时可以另算 source hash。+temporal marker、Role Cue 或结构标签内部。注释可出现在 atom 之间允许布局空白的位置,并按布局空白处理;规范 formatter 将其独占一行。注释不进入任何投影、token、Selection、Moment 或 hash 的语义内容;需要可复现源码身份时可以另算 source hash。## 8. Narrative IR 与消费者合同@@ -560,12 +524,10 @@ temporal marker、Role Cue 或结构标签内部。注释可出现在 atom 之- 完整有序的 `CaptionDisplaySequence`、独立的 `CaptionCorrespondence`,以及每个显式Selection 对应的 `CaptionDisplayWordSubset`。字幕无需也不得从公开 Selection 反推词下标。-外部 Program 的 `role="label"` selector 可以从上述词全集投影自己的词子集;-同一 label 的多次 Turn 是多个有序、互不相邻的命中。它是 Caption author surface+外部 Program 的 `role="label"` selector 可以从上述词全集投影自己的词子集;同一 label 的多次 Turn 是多个有序、互不相邻的命中。它是 Caption author surface内部的显式查询,不是 Role Cue 的隐式字幕行为,也不建立 speaker entity。-SelectionSet/MomentSet 是消费者边界,不是 Segment 的子对象。典型外部-关系是:+SelectionSet/MomentSet 是消费者边界,不是 Segment 的子对象。典型外部关系是:```textScript ──compile──> Narrative IR ──project──> dialogue / speech@@ -581,13 +543,10 @@ CaptionDisplayWordSubset C ──words──> caption.Program一个 Ranking、B-roll 或其他节点可以有多个动态端口,各端口接受不同Selection/Moment;同一集合也可以被多个消费者复用。未来 Graph-语法可以把这些类型边写成 `during=` / `at=`,但它们必须引用已解析的名字-或端点投影,不能接受模糊自然语言 locator。+语法可以把这些类型边写成 `during=` / `at=`,但它们必须引用已解析的名字或端点投影,不能接受模糊自然语言 locator。Caption 的多样式、region、cue segmentation、annotation、mute 和 layout-都属于 Caption Program。Caption consumer 若要求互斥 token ownership,重叠必须作为该消费者的-编译错误;这不是 Script 禁止 Selection 重叠。未来 Caption 若支持 overlay,-只扩展 Caption Program,不扩展正文语法。+都属于 Caption Program。Caption consumer 若要求互斥 token ownership,重叠必须作为该消费者的编译错误;这不是 Script 禁止 Selection 重叠。未来 Caption 若支持 overlay,只扩展 Caption Program,不扩展正文语法。当前 Caption Program 使用一个覆盖全部可见词的默认 Style,再按源码顺序应用 Role或显式 Selection 的整 Style 替换,最后命中的规则获胜。无 Role 的 Turn 自动保留默认@@ -610,8 +569,7 @@ Style;修改一个局部区间不要求作者书写它的补集。完整规则| 语气、情绪、音色、重音、语速、SSML | Speech/Generation Program || Consumer、节点、端口、DAG 接线 | `<script>` 外的 SVML 区域 |-这些边界保证 Script 保持“可直接阅读的稿子”,同时不阻止完整 SVML 最终-确定性编译 DAG 和时间线。+这些边界保证 Script 保持“可直接阅读的稿子”,同时不阻止完整 SVML 最终确定性编译 DAG 和时间线。## 10. 完备性与扩展判定@@ -625,9 +583,7 @@ Style;修改一个局部区间不要求作者书写它的补集。完整规则6. 运行时文字输入不同:Slot。7. 字幕、画面、音频、生成或消费行为不同:Script 外的 Program。-只要需求能落入这七项,就不得发明新的 inline delimiter。若七项都不能-无损表达,应先证明它属于稿子语义而不是 Program,再以新版本提案处理;-不得让现有解析器“顺便支持”。+只要需求能落入这七项,就不得发明新的 inline delimiter。若七项都不能无损表达,应先证明它属于稿子语义而不是 Program,再以新版本提案处理;不得让现有解析器“顺便支持”。## 11. 实现验收diff --git a/docs/zh/guide/spec/spatial-layout.md b/docs/zh/guide/spec/spatial-layout.mdindex 90669c82..3a4d59fe 100644--- a/docs/zh/guide/spec/spatial-layout.md+++ b/docs/zh/guide/spec/spatial-layout.md@@ -24,9 +24,7 @@ ContentFit how an extent is sized and aligned against a FrameFittedContent the deterministic result of that fit```-当一个可视组件消费某个 `SpatialFrame` 时,该 frame 扮演的角色是它的 **Placement Frame**:组件被摆放-在哪里,以及 frame 级别的 Paint 可以存在于哪里。随后每一个实际的 text/media 样本都会依据自身的固有尺寸和-一个 `ContentFit` 推导出各自的 **Content Frame**。+当一个可视组件消费某个 `SpatialFrame` 时,该 frame 扮演的角色是它的 **Placement Frame**:组件被摆放在哪里,以及 frame 级别的 Paint 可以存在于哪里。随后每一个实际的 text/media 样本都会依据自身的固有尺寸和一个 `ContentFit` 推导出各自的 **Content Frame**。这就是那两个 frame。它们并不总是嵌套关系:@@ -45,13 +43,11 @@ Placement Frame Content Frame因此把第二个称作“内框”是错误的。在 `cover`、缩放或局部运动之下,Content Frame 可能超出 PlacementFrame。-一个 Placement Frame 可以包含若干个显式样本。纯色底衬没有 Content Frame。一个模糊样本和一个前景样本各自-拥有独立的 Content Frame,即使它们引用同一个 Artifact。不存在被所有图层共享的那种全局唯一“内框”。+一个 Placement Frame 可以包含若干个显式样本。纯色底衬没有 Content Frame。一个模糊样本和一个前景样本各自拥有独立的 Content Frame,即使它们引用同一个 Artifact。不存在被所有图层共享的那种全局唯一“内框”。## 2. 边界-聚焦的视频领域包是 `@narratage/spatial`。它拥有纯类型、validator、面向可复用几何的作者 Surface 以及确定性-的几何 Producer。它不拥有:+聚焦的视频领域包是 `@narratage/spatial`。它拥有纯类型、validator、面向可复用几何的作者 Surface 以及确定性的几何 Producer。它不拥有:- 时间窗口或媒体的固有播放行为;- 文字折行或字形测量;@@ -60,9 +56,7 @@ Frame。- z-order、转场或局部运动;- Composition、Runtime、Provider 或 Core 的行为。-这些事实只通过图的边与 Spatial 相遇。例如,Media Inspection 选定一路可视流并产出其面向显示的 extent;-某个 Media 包再显式地把该 extent 转换成 `IntrinsicExtent`,交给 Spatial 做 fitting。Spatial 永远不会打开-一个 MP4,也不会猜测哪一路流是主流。+这些事实只通过图的边与 Spatial 相遇。例如,Media Inspection 选定一路可视流并产出其面向显示的 extent;某个 Media 包再显式地把该 extent 转换成 `IntrinsicExtent`,交给 Spatial 做 fitting。Spatial 永远不会打开一个 MP4,也不会猜测哪一路流是主流。安装或修订这个包不得改变 Core。Core 看到的只是普通的带类型 Record 和 Operation。@@ -84,8 +78,7 @@ type CanvasSpace = {宽和高是正整数。颜色、clear Paint、帧率和时长不是空间事实,都留在这个值之外。-Canvas 必须先于 Track 声明,随后作为同一个图上的值连接到 Film/Composition。当前的 Film Surface 把宽高藏在-最终的 Film 声明内部,这对精确的 Text 和 Media 布局来说太晚了。它的重写必须把 Canvas 声明与最终的 Track+Canvas 必须先于 Track 声明,随后作为同一个图上的值连接到 Film/Composition。当前的 Film Surface 把宽高藏在最终的 Film 声明内部,这对精确的 Text 和 Media 布局来说太晚了。它的重写必须把 Canvas 声明与最终的 Track装配分开,而不是把宽高复制进每一份 Track Recipe。预期的源码形态是:@@ -116,11 +109,9 @@ type SpatialFrame = {};```-宽和高必须为正。`xPx` 与 `yPx` 可以为负,也可以延伸到 Canvas 之外。画布外的 Frame 对进出场运动很有用,-不得被悄悄 clamp、求交或拒绝。哪些像素可见由 Canvas 光栅化决定。Clamp 永远是一次显式的投影选择。+宽和高必须为正。`xPx` 与 `yPx` 可以为负,也可以延伸到 Canvas 之外。画布外的 Frame 对进出场运动很有用,不得被悄悄 clamp、求交或拒绝。哪些像素可见由 Canvas 光栅化决定。Clamp 永远是一次显式的投影选择。-作者输入可以使用相对 Canvas 的百分比或像素。它们会在消费者布局其内容之前编译成这一种已解析形式。百分比相对-的是显式连接的父 Frame 的宽/高,而不是渲染器碰巧创建的某个 DOM 容器。+作者输入可以使用相对 Canvas 的百分比或像素。它们会在消费者布局其内容之前编译成这一种已解析形式。百分比相对的是显式连接的父 Frame 的宽/高,而不是渲染器碰巧创建的某个 DOM 容器。三个作者组件在不需要 mode 字段的前提下覆盖了常见的构造语义:@@ -141,8 +132,7 @@ type SpatialFrame = {x="100%" y="100%" width="32%" aspect={portrait.extent} anchor="bottom-right"/>```-`Frame` 不代表一个可见的盒子。它只产出几何。`AspectFrame` 可以消费一条通用的 `IntrinsicExtent` 边;它不-依赖 Media。+`Frame` 不代表一个可见的盒子。它只产出几何。`AspectFrame` 可以消费一条通用的 `IntrinsicExtent` 边;它不依赖 Media。九个规范锚点名是:@@ -159,8 +149,7 @@ frame.x = target.x - frame.width × selfAnchor.x + offset.xframe.y = target.y - frame.height × selfAnchor.y + offset.y```-每个具名锚点不过是一对可读的 `(0 | 0.5 | 1, 0 | 0.5 | 1)`。更高级的 Surface 可以暴露任意归一化锚点,而不必-改变编译后的合同。+每个具名锚点不过是一对可读的 `(0 | 0.5 | 1, 0 | 0.5 | 1)`。更高级的 Surface 可以暴露任意归一化锚点,而不必改变编译后的合同。安全区、左栏、标题区和商品区都是从 Canvas 或父 Frame 派生出来的普通具名 Frame。它们不是保留的全局 token。@@ -177,10 +166,7 @@ type IntrinsicExtent = {```这两个值是内容面向显示的、为正的自然像素 extent。`contain`、`cover`、`fit-width`、`fit-height` 和-`stretch` 只需要它们的比值;`native` 和 `scale-down` 还会用到它们与 Canvas 像素的绝对关系。Media 可以在应用-容器旋转和 sample aspect 信息之后推导它们。Text 可以从精确的字体排版推导它们。矢量组件必须选择一个显式的-标称光栅 extent,而不是假装任意的 view-box 单位就是 Canvas 像素。它们都不会把源 Artifact、字体、组件族或-上游摘要存进 `IntrinsicExtent`;这些关系仍然显现在图的边与 Derivation 上。+`stretch` 只需要它们的比值;`native` 和 `scale-down` 还会用到它们与 Canvas 像素的绝对关系。Media 可以在应用容器旋转和 sample aspect 信息之后推导它们。Text 可以从精确的字体排版推导它们。矢量组件必须选择一个显式的标称光栅 extent,而不是假装任意的 view-box 单位就是 Canvas 像素。它们都不会把源 Artifact、字体、组件族或上游摘要存进 `IntrinsicExtent`;这些关系仍然显现在图的边与 Derivation 上。## 6. ContentFit 与两个 frame 的方程@@ -205,9 +191,7 @@ type ContentFit = {```两个点都在各自的 Frame 内归一化。`framePoint` 说明所选的内容点想落在 Placement Frame 的哪个位置。-`contentPoint` 说明源上的哪个固有点是重要的。这比旧的单一 `focalX/focalY` 更有表达力 —— 后者在两边悄悄用了-同一个坐标。两个点的坐标都必须落在 `[0,1]`;有意超出该范围的位移使用 `offsetPx`,当结果必须留在范围之外-时使用 `constraint="free"`。+`contentPoint` 说明源上的哪个固有点是重要的。这比旧的单一 `focalX/focalY` 更有表达力 —— 后者在两边悄悄用了同一个坐标。两个点的坐标都必须落在 `[0,1]`;有意超出该范围的位移使用 `offsetPx`,当结果必须留在范围之外时使用 `constraint="free"`。给定 Placement Frame `(Vx, Vy, Vw, Vh)` 和固有 extent `(Sw, Sh)`,保持宽高比的基础缩放为:@@ -227,8 +211,7 @@ Cw = Sw × scaleCh = Sh × scale```-`stretch` 有意放弃源宽高比,产出 `(Cw, Ch) = (Vw, Vh)`。它之所以是显式的,是因为成熟的编辑器允许形变;其他-任何尺寸模式都不得形变。+`stretch` 有意放弃源宽高比,产出 `(Cw, Ch) = (Vw, Vh)`。它之所以是显式的,是因为成熟的编辑器允许形变;其他任何尺寸模式都不得形变。约束之前:@@ -249,8 +232,7 @@ Cw <= Vw: clamp Cx to [Vx, Vx + Vw - Cw]Cw >= Vw: clamp Cx to [Vx + Vw - Cw, Vx ]```-垂直方向的法则完全相同。这支持了真正的焦点摆放,比如“源上的 `(0.8, 0.35)` 这个点应当出现在 Frame 的中心”,-同时不会允许意外露出未被覆盖的边条。+垂直方向的法则完全相同。这支持了真正的焦点摆放,比如“源上的 `(0.8, 0.35)` 这个点应当出现在 Frame 的中心”,同时不会允许意外露出未被覆盖的边条。常见的九种对齐只是 `framePoint === contentPoint` 时的简写。居中 contain 和居中 cover 两边都是 `(0.5, 0.5)`。`top-left` 两边都是 `(0,0)`。如果作者刻意要让内容跑到外面,或者刻意让 Placement Frame 不被完全覆盖,就选择@@ -265,20 +247,16 @@ type FittedContent = {};```-当需要裁剪到 Placement Frame 时,对应的源采样窗口是由 Placement Frame 与 Content Frame 的交集机械推导出来-的。它不是第三个由作者撰写的盒子。fit 之后的旋转或透视变换可能让采样边界不再是矩形,因此要放在这层基础布局-之后应用。+当需要裁剪到 Placement Frame 时,对应的源采样窗口是由 Placement Frame 与 Content Frame 的交集机械推导出来的。它不是第三个由作者撰写的盒子。fit 之后的旋转或透视变换可能让采样边界不再是矩形,因此要放在这层基础布局之后应用。## 7. Fit 不是运动,也不是占用-一次 fit 计算产出的是基础 Content Frame。缩放、平移、旋转、透视和入场运动会在之后对该结果做变换。它们不会-改动 `ContentFit`,也不会改动源宽高比。+一次 fit 计算产出的是基础 Content Frame。缩放、平移、旋转、透视和入场运动会在之后对该结果做变换。它们不会改动 `ContentFit`,也不会改动源宽高比。这避免了旧有的歧义:`zoom` 被塞进 `contain`/`cover` 里,从而可能悄悄让所声明的 fit 不再成立。如果一段 KenBurns 运动把一张 contain 的图片缩放到发生裁切,基础 fit 仍然是 `contain`,裁切是由之后的变换显式造成的。-Spatial 的尺寸策略与固有时间占用也毫无关系。一段视频可以在空间上是 `contain`,同时在时间上播放一次、循环或-拉伸。一张图片并不会仅仅因为它有固有的空间 extent 就获得某种固有的时间播放模式。+Spatial 的尺寸策略与固有时间占用也毫无关系。一段视频可以在空间上是 `contain`,同时在时间上播放一次、循环或拉伸。一张图片并不会仅仅因为它有固有的空间 extent 就获得某种固有的时间播放模式。## 8. 裁剪与 frame 形状@@ -291,20 +269,17 @@ owned-shape explicit shape/path owned by the same component```圆角半径、椭圆/路径蒙版、描边和阴影属于表现,不属于坐标。Text 的辉光完全可以合理地溢出它的 Placement-Frame;Media 卡片通常会把每个局部样本都裁剪到同一个圆角 Placement Frame。Runtime 不会根据内容类型推断出任何-默认值。+Frame;Media 卡片通常会把每个局部样本都裁剪到同一个圆角 Placement Frame。Runtime 不会根据内容类型推断出任何默认值。自有形状只能裁剪同一个组件贡献内的元素。它不能蒙版或采样另一个同级 Track。## 9. 透明、纯色、模糊与替代底衬-Placement Frame 中未被 Content Frame 绘制的区域本身不具备空间语义。Media/Text 的表现层提供的是一组有序的、-显式自有图层。+Placement Frame 中未被 Content Frame 绘制的区域本身不具备空间语义。Media/Text 的表现层提供的是一组有序的、显式自有图层。### 透明-不产出任何底衬图层。透明像素会在 Composition 时自然露出更低的 Track。这不是跨 Track 采样:该 Track 在那里-根本没有贡献像素。+不产出任何底衬图层。透明像素会在 Composition 时自然露出更低的 Track。这不是跨 Track 采样:该 Track 在那里根本没有贡献像素。### 纯色或渐变@@ -319,14 +294,11 @@ same source Artifact ─┬─> cover ContentFit -> blur/tone -> backing layer└─> contain ContentFit -> foreground layer```-两个样本共享同一个 Placement Frame,但拥有各自独立的 Content Frame 和效果。Artifact 收集会对完全相同的字节-去重;渲染仍然执行两次显式采样。模糊实现必须在裁剪之前做边缘扩展/超采,以免高斯核造出非预期的透明或发暗-边框。+两个样本共享同一个 Placement Frame,但拥有各自独立的 Content Frame 和效果。Artifact 收集会对完全相同的字节去重;渲染仍然执行两次显式采样。模糊实现必须在裁剪之前做边缘扩展/超采,以免高斯核造出非预期的透明或发暗边框。### 另一张图片或另一段视频-替代源通过自己的图边进入,并获得属于自己的 Inspection、IntrinsicExtent、ContentFit,对于有时长的媒体还包括-占用策略。它不是藏在某个 Style Recipe 里的字符串路径。+替代源通过自己的图边进入,并获得属于自己的 Inspection、IntrinsicExtent、ContentFit,对于有时长的媒体还包括占用策略。它不是藏在某个 Style Recipe 里的字符串路径。因此通用的 Media 作者模型是有序的局部图层,而不是特殊的 `foreground/background` 字段:@@ -347,8 +319,7 @@ same source Artifact ─┬─> cover ContentFit -> blur/tone -> backing layer### 仍然被禁止的做法对已经累积出来的 Composition 施加 `backdrop-filter` 不属于上述任何一种情形。那会让结果依赖于任意的下层-Track。要模糊另一个视觉物,组件必须显式接收那个视觉/媒体。要模糊一个已完成的下层合成,必须由更高阶的组件先-显式拥有并物化那个合成。+Track。要模糊另一个视觉物,组件必须显式接收那个视觉/媒体。要模糊一个已完成的下层合成,必须由更高阶的组件先显式拥有并物化那个合成。## 10. Text、Ranking 与 Caption 的用法@@ -362,8 +333,7 @@ Spatial 提供公共几何,同时不强加单一布局模型:- Comment Sticker 消费一个 Placement Frame,并拥有自己的头像/文字/内部布局;- Caption 可以消费一个 Placement Frame,但 Cue/Atom 的折行仍归 Caption 所有。-Text 的布局盒和 Media 的 Content Frame 并不会仅仅因为都是矩形就成为同一个语义 Type。它们可以使用同样的纯几何-辅助函数,同时各自仍然是包自有的已解析事实。+Text 的布局盒和 Media 的 Content Frame 并不会仅仅因为都是矩形就成为同一个语义 Type。它们可以使用同样的纯几何辅助函数,同时各自仍然是包自有的已解析事实。## 11. 图数据流与不传播元数据@@ -431,8 +401,6 @@ Operation 校验,而不是靠把血缘元数据复制到每一个值上。- 由所选渲染器实现锁定的取整/光栅行为;- 共享 Type 中不存在 Core、Runtime、Film 族、Text 族或 Media 族的判别字段。-纯几何矩阵与真实 Chromium witness 现已覆盖每一种尺寸模式、全部九种等点对齐、不相等的 bounded/free 焦点,-以及部分/完全越出 Canvas 的 Frame。Media 归一化还会在推导 `IntrinsicExtent` 之前,把容器旋转和非方形 sample+纯几何矩阵与真实 Chromium witness 现已覆盖每一种尺寸模式、全部九种等点对齐、不相等的 bounded/free 焦点,以及部分/完全越出 Canvas 的 Frame。Media 归一化还会在推导 `IntrinsicExtent` 之前,把容器旋转和非方形 sampleaspect 物化成方形像素的视觉。Ranking 现在消费同样的显式 Frame 几何,且没有增加族判别字段。最终的 Visual IR-兼容性审查现已通过;Spatial 自己的作者 Surface 仍处于预发布状态,在此期间不应再生长出任何包内局部的百分比-词汇。+兼容性审查现已通过;Spatial 自己的作者 Surface 仍处于预发布状态,在此期间不应再生长出任何包内局部的百分比词汇。diff --git a/docs/zh/guide/spec/track-authoring.md b/docs/zh/guide/spec/track-authoring.mdindex e186b6c3..e59bf5eb 100644--- a/docs/zh/guide/spec/track-authoring.md+++ b/docs/zh/guide/spec/track-authoring.md@@ -5,23 +5,20 @@ description: 官方 Track 包共享的可执行时间权威。聚焦的。# SVML 视频 Track 作者模型-状态:官方 Track 包共享的可执行时间权威。聚焦的 `@narratage/temporal` 包实现了严格的 occurrence 展开、-精确的有理数窗口投影,以及触发式的同级排程。共享的 Spatial、Text、Ranking、Media、Audio 和 Screen Overlay+状态:官方 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 的兼容承诺。+`@narratage/comment-sticker` 包现在使用同一套 Temporal 与 Spatial 基础,并下降为一个同级 VisualTrack。这里刻意不构成对已发布公开 ABI 的兼容承诺。## 目的官方视频包需要一套共享的纪律,但不需要一个万能的 Track Program。Text、Media、Ranking 和 Comment Sticker拥有各不相同的作者语义,但它们不得各自发明互不兼容的方式来回答同样的时间问题。-本文管辖的是包级 Program 及其确定性下降。它不会给 Core、Runtime、Composition 或某个 Provider 增加视频语义。-公开的终端窄腰仍然是 [`VisualTrack` 和 `AudioTrack`](./track-composition.md)。+本文管辖的是包级 Program 及其确定性下降。它不会给 Core、Runtime、Composition 或某个 Provider 增加视频语义。公开的终端窄腰仍然是 [`VisualTrack` 和 `AudioTrack`](./track-composition.md)。完整的包作者关注点分离是:@@ -107,12 +104,9 @@ type LocatedMomentOccurrence = {Program source 是一个单例 occurrence。每个投影环境还拥有 `program.start` 和 `program.end` 这两个精确的ProgramSpace 边界。-Selection 的定位必须保持 Script 中的 occurrence 顺序,以及两个作者锚点各自的身份。它不得对这些点排序、-合并、裁剪、互换或取绝对差值。一个 `end` 早于 `start` 的已定位 Selection 仍然是有效的点证据。只有消费者才会-创建窗口,因此只有投影层才能判定它实际消费的那些点是否构成有效区间。+Selection 的定位必须保持 Script 中的 occurrence 顺序,以及两个作者锚点各自的身份。它不得对这些点排序、合并、裁剪、互换或取绝对差值。一个 `end` 早于 `start` 的已定位 Selection 仍然是有效的点证据。只有消费者才会创建窗口,因此只有投影层才能判定它实际消费的那些点是否构成有效区间。-组件自有的精确时间产物,比如已经定好时间的 Caption Cue,可以直接进入后面的帧窗口阶段。它不需要假装自己的-时间来自某个 Narrative Selection。+组件自有的精确时间产物,比如已经定好时间的 Caption Cue,可以直接进入后面的帧窗口阶段。它不需要假装自己的时间来自某个 Narrative Selection。## 3. 点表达式与 Temporal Window Projection@@ -133,8 +127,7 @@ type TemporalWindowProjection = {};```-序列化合同将为时长使用显式单位。秒、毫秒和整数帧是三种不同的作者输入;换算到有理数 ProgramSpace 必须有唯一的-确定性边界量化规则。`base_start` 和 `base_end` 是被废弃的名字,因为当前架构没有享有特权的 Base Track。+序列化合同将为时长使用显式单位。秒、毫秒和整数帧是三种不同的作者输入;换算到有理数 ProgramSpace 必须有唯一的确定性边界量化规则。`base_start` 和 `base_end` 是被废弃的名字,因为当前架构没有享有特权的 Base Track。常见的作者语义都只是普通表达式:@@ -154,17 +147,13 @@ type TemporalWindowProjection = {### 语义绑定可以刻意忽略局部坐标-作者可以把一个项绑定到覆盖开场几个词的 Selection,同时把它投影到 `[program.start, program.start + 3s]`。-即使该投影没有用到 Selection 已定位的 start/end 坐标,这个 Selection 仍然贡献了作者语义、occurrence 身份、-基数和依赖真相。+作者可以把一个项绑定到覆盖开场几个词的 Selection,同时把它投影到 `[program.start, program.start + 3s]`。即使该投影没有用到 Selection 已定位的 start/end 坐标,这个 Selection 仍然贡献了作者语义、occurrence 身份、基数和依赖真相。-这在 `one` 之下是合法的。如下文所定义,它在 `each` 之下被刻意限制,因为重复一个与 occurrence 无关的投影只会-制造出一模一样的窗口。+这在 `one` 之下是合法的。如下文所定义,它在 `each` 之下被刻意限制,因为重复一个与 occurrence 无关的投影只会制造出一模一样的窗口。## 4. Occurrence 展开是严格的,且先于投影-旧的形态 `{ kind: "single", cardinality: "exactly_one" }` 把同一个事实说了两遍。可执行的合同只有两个互不重叠-的选项:+旧的形态 `{ kind: "single", cardinality: "exactly_one" }` 把同一个事实说了两遍。可执行的合同只有两个互不重叠的选项:```tstype OccurrenceExpansion =@@ -184,8 +173,7 @@ type OccurrenceExpansion =4. 绝不选择 `first`、`last`、`best`、最近或最早者;5. 把那唯一的 occurrence 恰好投影一次。-忽略 Selection/Moment 坐标的投影通常与 `one` 搭配。仅依赖 Program 的时间使用固有的单例 Program source,因此-同样下降为 `one`,且不需要作者可见的基数设置。+忽略 Selection/Moment 坐标的投影通常与 `one` 搭配。仅依赖 Program 的时间使用固有的单例 Program source,因此同样下降为 `one`,且不需要作者可见的基数设置。### `each`@@ -200,23 +188,18 @@ type OccurrenceExpansion =7. 只要有任何一个 occurrence 无法产出有效窗口,就让整个确定性 Operation 失败。当源 occurrence 多于一个时,投影的两个边界中至少有一个必须引用局部点(`selection.start`、`selection.end`-或 `moment.cue`)。只使用 Program 点或绝对点的投影与 occurrence 无关,在 `each` 之下会被拒绝:它会造出若干-语义不同、物理窗口却完全相同、彼此毫无时间区分的实例。作者应当改用 `one`、绑定 Program 单例,或分别写出显式-的多个项。+或 `moment.cue`)。只使用 Program 点或绝对点的投影与 occurrence 无关,在 `each` 之下会被拒绝:它会造出若干语义不同、物理窗口却完全相同、彼此毫无时间区分的实例。作者应当改用 `one`、绑定 Program 单例,或分别写出显式的多个项。-投影是一对一的。一个 occurrence 不能扇出成多个窗口。想从一个 Selection 或 Moment 得到两个窗口的作者,要么写-两个项,要么使用一个显式构造这两个项的包自有组件。+投影是一对一的。一个 occurrence 不能扇出成多个窗口。想从一个 Selection 或 Moment 得到两个窗口的作者,要么写两个项,要么使用一个显式构造这两个项的包自有组件。-集合聚合不是第三种通用展开模式。可见性掩码或另一个确实以集合为值的组件,可以定义包自有的集合消费者,但普通的-可视项不得借这个例外找回隐式的合并、并集或去重行为。+集合聚合不是第三种通用展开模式。可见性掩码或另一个确实以集合为值的组件,可以定义包自有的集合消费者,但普通的可视项不得借这个例外找回隐式的合并、并集或去重行为。Caption 的 `Mute` 是一个具体的包自有例子。它在 `CaptionProgram` 内部对显式引用的`CaptionDisplayWordSubset` 取并集;它不改变通用的 occurrence 展开,不制造投影窗口,也不进入 Core。### 基数不决定重叠-`each` 只说明一个 occurrence 集合如何展开。它不说明产生的窗口是否可以重叠、相邻窗口是否应当合并,也不说明-某个项是否应当在下一个项的 cue 处关闭。这些问题在投影之前无法回答,而且还可能取决于包的语义。+`each` 只说明一个 occurrence 集合如何展开。它不说明产生的窗口是否可以重叠、相邻窗口是否应当合并,也不说明某个项是否应当在下一个项的 cue 处关闭。这些问题在投影之前无法回答,而且还可能取决于包的语义。投影之后,消费方的包必须为自己的组件选择并校验一种显式关系,例如:@@ -224,18 +207,14 @@ Caption 的 `Mute` 是一个具体的包自有例子。它在 `CaptionProgram`- `disjoint`:同一个作者项的各 occurrence 之间出现任何重叠都是错误;- 由包自有的 Sequence 或 Deck 策略推导最终的同级窗口与交接。-这种关系不属于 `OccurrenceExpansion`,也不由 Core 拥有。官方的简单 Text、Comment Sticker 以及类似的重复项,-通常应当要求投影窗口互不相交。Media 组、Ranking 组件可以拥有更强的显式同级规则。任何包都不会获得隐藏的全局-自动拼接行为。+这种关系不属于 `OccurrenceExpansion`,也不由 Core 拥有。官方的简单 Text、Comment Sticker 以及类似的重复项,通常应当要求投影窗口互不相交。Media 组、Ranking 组件可以拥有更强的显式同级规则。任何包都不会获得隐藏的全局自动拼接行为。### 触发式阶段属于同级排序,不是另一种 temporal source-Ranking、Tier、幻灯片以及其他渐进式组件,往往只有一组有序的触发 Moment。到达触发点 `i` 就进入状态 `i`;-到达触发点 `i + 1` 就交接给下一个状态。这种情况使用的是同一套点定位与窗口投影。它不构成在 Core 里引入 `Stage`+Ranking、Tier、幻灯片以及其他渐进式组件,往往只有一组有序的触发 Moment。到达触发点 `i` 就进入状态 `i`;到达触发点 `i + 1` 就交接给下一个状态。这种情况使用的是同一套点定位与窗口投影。它不构成在 Core 里引入 `Stage`Type 或再加一种 Script 标记的理由。-仅有 `N` 个触发点无法界定 `N` 个有限阶段:最后一个阶段仍然需要一个终止边界。因此触发式组件拥有一个显式的外层-窗口 `[B, O)` 和一个显式的阶段终止点 `T`。`T` 可以引用 `O`,但包不得默认它一定如此。把两者分开,可以让 Ranking+仅有 `N` 个触发点无法界定 `N` 个有限阶段:最后一个阶段仍然需要一个终止边界。因此触发式组件拥有一个显式的外层窗口 `[B, O)` 和一个显式的阶段终止点 `T`。`T` 可以引用 `O`,但包不得默认它一定如此。把两者分开,可以让 Ranking组件在 `T` 处结束最后一项,并让完全落定的 board 一直可见到 `O`。给定已定位并已量化到帧的触发点`p1 ... pN`,包可以推导出:@@ -247,8 +226,7 @@ stage N [pN, T)settled suffix [T, O) (when T < O)```-`p1` 之前的区间是非活动的,而不是隐式的第零阶段。如果某个设计需要一个从外层起点到 `p1` 的初始可见状态,那个-状态必须显式写出,并会产生 `N + 1` 个阶段。渲染器绝不能因为存在 board 或背景就推断出它。+`p1` 之前的区间是非活动的,而不是隐式的第零阶段。如果某个设计需要一个从外层起点到 `p1` 的初始可见状态,那个状态必须显式写出,并会产生 `N + 1` 个阶段。渲染器绝不能因为存在 board 或背景就推断出它。这个模式有两种相关但不同的包自有下降方式:@@ -268,8 +246,7 @@ settled suffix [T, O) when T < Oboard:`p2` 之后,第 1 项和第 2 项同时处于活动状态;可见的前缀本身就是当前的逻辑状态。不需要物化任何 board快照。-互斥形态从同样的候选出发,再施加一条后继交接策略:每个候选的最终结束成为下一个候选的开始,最后一个在 `T` 处-结束。这可以驱动一个 Ranking 暂存区,让它恰好展示一个当前项,同时已落定的项作为独立的累积前缀保留。当+互斥形态从同样的候选出发,再施加一条后继交接策略:每个候选的最终结束成为下一个候选的开始,最后一个在 `T` 处结束。这可以驱动一个 Ranking 暂存区,让它恰好展示一个当前项,同时已落定的项作为独立的累积前缀保留。当`T < O` 时,后缀没有当前项,展示的是完成状态。包可以把这两个视图下降为同一个同级 `VisualTrack` 中相互独立的Present。@@ -284,9 +261,7 @@ Present。7. 由作者项身份与 occurrence 身份推导项/阶段身份,绝不使用数组下标;8. 把累积重叠或后继交接保持为已声明的包语义,绝不交给 Runtime 选择。-包也可以为每个子项各配一条单 occurrence 的 Moment 边。两种作者写法都下降为同样的有序同级候选;按位置对齐不是-隐式的全局行为。除非另有组件确实需要消费它们,触发式阶段只是内部的确定性下降事实。Composition 收到的仍然只是-普通的 Present。+包也可以为每个子项各配一条单 occurrence 的 Moment 边。两种作者写法都下降为同样的有序同级候选;按位置对齐不是隐式的全局行为。除非另有组件确实需要消费它们,触发式阶段只是内部的确定性下降事实。Composition 收到的仍然只是普通的 Present。## 5. 投影校验与负区间@@ -309,19 +284,15 @@ cue = 1sintersection [0s, 3s]```-原始的逆序区间绝不能被裁剪、排序或取绝对值掩盖过去。完全落在 ProgramSpace 之外的区间会变成空并失败;它不会-被悄悄略过。渲染器只收到已经校验过的帧跨度,不做任何时间修补。+原始的逆序区间绝不能被裁剪、排序或取绝对值掩盖过去。完全落在 ProgramSpace 之外的区间会变成空并失败;它不会被悄悄略过。渲染器只收到已经校验过的帧跨度,不做任何时间修补。-Selection 的一对交叉锚点本身并不构成投影失败。恒等投影 `[selection.start, selection.end]` 在产出逆序窗口时-失败,而 `[selection.start, program.end]` 可以依然有效,因为它并不消费那个交叉的结束点。+Selection 的一对交叉锚点本身并不构成投影失败。恒等投影 `[selection.start, selection.end]` 在产出逆序窗口时失败,而 `[selection.start, program.end]` 可以依然有效,因为它并不消费那个交叉的结束点。## 6. 固有时长与占用-每一个被呈现的产物,要么拥有已验证的固有时长,要么没有。未知时长不得冒充其中任何一种;媒体检查必须先确定它,-基于固有时长的占用策略才能执行。+每一个被呈现的产物,要么拥有已验证的固有时长,要么没有。未知时长不得冒充其中任何一种;媒体检查必须先确定它,基于固有时长的占用策略才能执行。-无时长产物 —— 例如 Text、静态图片、Comment Sticker 和普通的 Ranking UI —— 占满自己最终投影出的整个窗口。-局部的入场、出场和循环动画属于该窗口内部的表现,不是合成出来的素材时长。+无时长产物 —— 例如 Text、静态图片、Comment Sticker 和普通的 Ranking UI —— 占满自己最终投影出的整个窗口。局部的入场、出场和循环动画属于该窗口内部的表现,不是合成出来的素材时长。带固有时长的产物会收到一个最终允许窗口和一条显式播放策略。概念上的可视策略是:@@ -333,8 +304,7 @@ type IntrinsicPlayback =| { readonly mode: "stretch" };```-`once` 取代了含义含糊的旧词 `finish`。end 对齐绝不表示倒放。它表示正向播放的源在投影窗口的结束处结束。如果源-比窗口长,start 对齐取源的头部,end 对齐取源的尾部。+`once` 取代了含义含糊的旧词 `finish`。end 对齐绝不表示倒放。它表示正向播放的源在投影窗口的结束处结束。如果源比窗口长,start 对齐取源的头部,end 对齐取源的尾部。| 策略 | 源短于窗口 | 源长于窗口 ||---|---|---|@@ -346,8 +316,7 @@ type IntrinsicPlayback =| `loop/end` | 选择使源尾部落在窗口结束处的循环相位 | 同样的尾部相位法则 || `stretch` | 把源的全部时间放慢塞进窗口 | 把源的全部时间加快塞进窗口 |-Audio 必须在同一套排程之上定义自己如实的词汇。它不能像视频帧那样把一个 PCM 采样保持住。一次性音频之外是静音,-补齐必须显式,循环就是循环,拉伸必须遵守作者声明的速度上下限。静态图片和无时长 UI 不接受无意义的固有播放模式。+Audio 必须在同一套排程之上定义自己如实的词汇。它不能像视频帧那样把一个 PCM 采样保持住。一次性音频之外是静音,补齐必须显式,循环就是循环,拉伸必须遵守作者声明的速度上下限。静态图片和无时长 UI 不接受无意义的固有播放模式。源的 trim 与源入/出点在被加入后,作用于占用之前,用来定义有效的固有源区间。Spatial 的 contain/cover 和 Text的 flow/shrink 作用于时间占用之后,与之无关。@@ -357,8 +326,7 @@ Audio 必须在同一套排程之上定义自己如实的词汇。它不能像原先那个大一统的 `contracts` 包被有意取消。名义上的共享语义由 Narrative、ProgramSpace、Media 和 Composition等聚焦模块各自拥有;Core 没有任何视频领域联合体的注册表。-本文中的时间代数由聚焦的视频领域包 `@narratage/temporal` 实现。它拥有投影类型、validator 以及纯粹的帧窗口-投影。它可以消费 Narrative 的点引用、SemanticMap 定位和 ProgramSpace,但它不得知道 Text、Media Track、+本文中的时间代数由聚焦的视频领域包 `@narratage/temporal` 实现。它拥有投影类型、validator 以及纯粹的帧窗口投影。它可以消费 Narrative 的点引用、SemanticMap 定位和 ProgramSpace,但它不得知道 Text、Media Track、Ranking、Comment Sticker、Film、HyperFrames、Runtime 或某个 Provider。官方包随后都使用同一份实现:@@ -398,8 +366,7 @@ take。其他 Track 可以通过两个结构锚点直接寻址整个 Narrative S## 9. Ranking 的特化-完整的 Ranking 审查、组件拆分、组排程和可执行迁移见 [`ranking-track.md`](./ranking-track.md)。Ranking 现已-验证:通用的时间代数足以支撑累积状态、互斥的当前阶段以及最终的落定后缀,而无需向 Core 或公开 Track 合同引入+完整的 Ranking 审查、组件拆分、组排程和可执行迁移见 [`ranking-track.md`](./ranking-track.md)。Ranking 现已验证:通用的时间代数足以支撑累积状态、互斥的当前阶段以及最终的落定后缀,而无需向 Core 或公开 Track 合同引入Ranking 或 `Stage` 语义。## 10. 迁移状态@@ -412,8 +379,7 @@ Comment Sticker 的内容、布局与表现已作为独立的作者包实现;Core 或 Composition。通用 Audio Track 和自包含的 Screen Overlay 现已分别在 [`audio-track.md`](./audio-track.md) 和-[`screen-overlay.md`](./screen-overlay.md) 中单独规范。Audio 复用同一套时间代数,但拥有如实的采样占用语义,-而不是视觉上的 hold 语义。Screen Overlay 是一份满画布的同级贡献,不是跨 Track 的调整图层。+[`screen-overlay.md`](./screen-overlay.md) 中单独规范。Audio 复用同一套时间代数,但拥有如实的采样占用语义,而不是视觉上的 hold 语义。Screen Overlay 是一份满画布的同级贡献,不是跨 Track 的调整图层。统一的 Item/Sequence Media 创作、全部运动通道、内部交接、显式音频投影以及 Speech Spine 受限的复用,现已在[`media-track.md`](./media-track.md) 中规范。旧的深度堆叠 Deck 是一个独立的高阶 Track 组件,见diff --git a/docs/zh/guide/spec/track-composition.md b/docs/zh/guide/spec/track-composition.mdindex 3cfef70e..34343ee1 100644--- a/docs/zh/guide/spec/track-composition.md+++ b/docs/zh/guide/spec/track-composition.md@@ -5,13 +5,11 @@ description: 可执行的仓库内部 `@1` 兼容窄腰;所有门禁均已通# SVML Track 与 Composition-状态:可执行的仓库内部 `@1` 兼容窄腰;[`track-expressiveness.md`](./track-expressiveness.md) 中的所有门禁-均已通过,公开发布仍然是另一件事。+状态:可执行的仓库内部 `@1` 兼容窄腰;[`track-expressiveness.md`](./track-expressiveness.md) 中的所有门禁均已通过,公开发布仍然是另一件事。## 法则-除了共享的 ProgramSpace 与画布几何之外,进入 Composition 的每一份视听贡献都是同级 Track。Composition 负责-校验、排序和合并 Track。它不认识 Caption、Speech、Media、Text、Seedance 或任何作者包家族。+除了共享的 ProgramSpace 与画布几何之外,进入 Composition 的每一份视听贡献都是同级 Track。Composition 负责校验、排序和合并 Track。它不认识 Caption、Speech、Media、Text、Seedance 或任何作者包家族。```textSpeech visual ───────────────> VisualTrack ─┐@@ -24,9 +22,7 @@ Speech audio / BGM / SFX ────> AudioTrack ──┘## ProgramSpace-ProgramSpace 拥有时长和精确的有理数帧率。它的时长必须结束在整数帧边界上。Track 不会把 ProgramSpace 的摘要-复制进每一个值。在两者关系需要被校验的地方,图会显式连接 Track 与 ProgramSpace;validator 会拒绝落在所提供-空间之外的帧窗口。+ProgramSpace 拥有时长和精确的有理数帧率。它的时长必须结束在整数帧边界上。Track 不会把 ProgramSpace 的摘要复制进每一个值。在两者关系需要被校验的地方,图会显式连接 Track 与 ProgramSpace;validator 会拒绝落在所提供空间之外的帧窗口。画布宽度、高度和 clear color 是 Composition 的结构性事实。任何视频 Track 都不定义时长,也不会成为享有特权的Base。@@ -35,18 +31,14 @@ Base。一个 VisualTrack 是由某个作者包拥有的、自包含的渲染贡献。它显式绑定[`svml.visual-ir@1`](./visual-ir.md) 终端语言,并拥有零个或多个帧精确的 `VisualPresent` 值;每个 Present-拥有自己的绝对 `(order, tieBreak)` 堆叠键,以及一棵自包含、不含代码的元素树,其素材来自 box、text、普通媒体-和带类型的可合成 Surface 原语。父引用是 Present 局部的。媒体和精确字体通过内容寻址的 Artifact 引用进入,而不是-通过 CSS URL 或环境字体名。每一个终端文本元素都带有非空的精确 Font 栈。-它与 ProgramSpace 的身份关系是内在的,因为没有时钟就无法解释这个 Track。是哪些 Record 产生了它,属于+拥有自己的绝对 `(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+每个元素都可以可选地携带帧精确的局部关键帧,作用于 opacity、transform、filter 或 clip-path。这些关键帧只作用于该 Present 的元素树。Media 包可以把一次成对转场下降为它自己两个 Present 上互补的动画,而不必让 Composition知道这个转场的名字或语义。VisualTrack 刻意不具备:@@ -57,20 +49,16 @@ VisualTrack 刻意不具备:- 采样下层 Track 的 backdrop 滤镜或混合模式;- 跨 Track 的蒙版、求交或转场输入。-当一个局部滤镜、裁切、变换、动画或转场只作用于该作者包显式拥有的素材,并下降为自包含的 Present 时,它就是-合法的。需要两份原始素材的效果,必须在最终下降为 Track 之前显式收到这两份素材。任何 Present 都不得采样已经-累积出来的下层合成。+当一个局部滤镜、裁切、变换、动画或转场只作用于该作者包显式拥有的素材,并下降为自包含的 Present 时,它就是合法的。需要两份原始素材的效果,必须在最终下降为 Track 之前显式收到这两份素材。任何 Present 都不得采样已经累积出来的下层合成。## AudioTrack-一个 AudioTrack 拥有精确的 48 kHz 采样域片段、带类型的规范 WAV Artifact、源区间、循环相位、保持音高的播放-速率、目标区间、增益,以及采样精确的淡入淡出。它没有视觉堆叠键,没有无实际作用的总线标签,也与 Speech Track+一个 AudioTrack 拥有精确的 48 kHz 采样域片段、带类型的规范 WAV Artifact、源区间、循环相位、保持音高的播放速率、目标区间、增益,以及采样精确的淡入淡出。它没有视觉堆叠键,没有无实际作用的总线标签,也与 Speech Track没有任何特殊关系。语音音频、音乐、源声和音效使用同一份合同。## Composition-Composition 包含一个画布和一组 VisualTrack/AudioTrack 值。ProgramSpace 是通往 Film 和最终渲染 Operation 的-一条同级输入边,而不是被反复复制的血缘元数据。Composition:+Composition 包含一个画布和一组 VisualTrack/AudioTrack 值。ProgramSpace 是通往 Film 和最终渲染 Operation 的一条同级输入边,而不是被反复复制的血缘元数据。Composition:1. 依据由显式图边提供的 ProgramSpace 校验每一个 Track;2. 拒绝重复的 Track 身份和重复的视觉堆叠键;@@ -78,8 +66,7 @@ Composition 包含一个画布和一组 VisualTrack/AudioTrack 值。ProgramSpac4. 在 ProgramSpace 中混合 AudioTrack 片段;5. 为一个被显式选定的最终渲染包产出与渲染器无关的输入。-Composition 不得按作者领域的家族做分支,也不得授予某个 Track 访问已累积下层像素的特权。因此全局 shatter、-调整图层、Base FX 通道或 B-roll 垫底转场都不属于这个版本。也不会为 Base FX 保留任何专用占位。+Composition 不得按作者领域的家族做分支,也不得授予某个 Track 访问已累积下层像素的特权。因此全局 shatter、调整图层、Base FX 通道或 B-roll 垫底转场都不属于这个版本。也不会为 Base FX 保留任何专用占位。TimedCaptionProjection 仍然是一个中间语义值。Caption 的分组、样式和 cue 下降必须在字幕作为普通 VisualTrack进入 Composition 之前完成。@@ -87,32 +74,19 @@ TimedCaptionProjection 仍然是一个中间语义值。Caption 的分组、样## 最终渲染边界`@narratage/hyperframes` 是当前面向 Composition 及其唯一带版本 SVML Visual IR 的参考编译器。它绝不按 Speech、-Caption、Media 或作者包身份做分支。它确定性地产出一份内容寻址的 `HyperframesDocument`,其 HTML 按绝对堆叠键-交错排布各个 VisualPresent。它不得把一个创作层的 Track 挂载成一个孤立的视觉包装层。AudioTrack 的编译与最终+Caption、Media 或作者包身份做分支。它确定性地产出一份内容寻址的 `HyperframesDocument`,其 HTML 按绝对堆叠键交错排布各个 VisualPresent。它不得把一个创作层的 Track 挂载成一个孤立的视觉包装层。AudioTrack 的编译与最终mux 是同一个 ProgramSpace 之上相互独立的媒体操作;HyperFrames 是一个无声的可视目标。这不是一条排他的边界。未来的 `render-remotion` 或基于 API 的渲染包,可以消费同样的 Composition 与-ProgramSpace,编译出另一份不可变的渲染器文档,并返回同一份媒体合同。Author Source 通过导入相应的包来选择这条-路径;Core 和 Runtime 不会猜测渲染器。当前的示例显式选择 `render-hyperframes`。+ProgramSpace,编译出另一份不可变的渲染器文档,并返回同一份媒体合同。Author Source 通过导入相应的包来选择这条路径;Core 和 Runtime 不会猜测渲染器。当前的示例显式选择 `render-hyperframes`。该文档必须(MUST)绑定精确的有理数帧率、为正整数的帧数、画布尺寸、Artifact 集合以及生成的 HTML。与-ProgramSpace 的关系仍然显现在该 Producer 的输入边与 Derivation 上,而不是被复制进文档内容。它完整的视觉帧域是-半开区间 `[0, frameCount)`。渲染第 `n` 帧必须只依赖这份不可变文档、它精确的 Artifact、被锁定的渲染器实现-以及 `n`;它不得要求顺序求值第 `0..n-1` 帧。因此带状态的作者效果必须在进入这条边界之前物化成带类型的 Surface。+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 依赖累积出来的同级像素。+`[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.mdindex af528e7a..d8f8bb55 100644--- a/docs/zh/guide/spec/track-expressiveness.md+++ b/docs/zh/guide/spec/track-expressiveness.md@@ -10,17 +10,14 @@ description: E1–E8 全部门均可执行;仓库内部的 `svml.visual-track@## 目的一份公开的 Track 合同必须解决最终的视听合成问题,同时不假装所有作者包都共用同一套创作模型。Text、-Caption、Media、Ranking 以及未来的包各自拥有自己的 Program,并且可以各自独立地修订这些 Program。-它们只有在把包内专有含义 lower 成自包含、帧精确的贡献之后,才能进入 Composition。+Caption、Media、Ranking 以及未来的包各自拥有自己的 Program,并且可以各自独立地修订这些 Program。它们只有在把包内专有含义 lower 成自包含、帧精确的贡献之后,才能进入 Composition。这道门只回答一个问题:> 生产中实际使用的文字、媒体盒、字幕、层叠与局部特效行为,能否在不向 Track、Composition 或 Core> 添加包族专有字段的前提下,lower 进同一条 Track 窄腰?-通过这道门并不会产生一个统一的 `TrackProgram`。Track Program 的六条轴——内容、时间源、窗口投影、-空间源、占位与呈现——仍然是给包作者的分离纪律,而不是六个强制的公开字段。共享的创作法则和当前的-时间设计在 [`track-authoring.md`](./track-authoring.md) 中定义。+通过这道门并不会产生一个统一的 `TrackProgram`。Track Program 的六条轴——内容、时间源、窗口投影、空间源、占位与呈现——仍然是给包作者的分离纪律,而不是六个强制的公开字段。共享的创作法则和当前的时间设计在 [`track-authoring.md`](./track-authoring.md) 中定义。## 三个绝不能塌陷的层级@@ -36,8 +33,7 @@ semantic/spatial locator final placement self-containedPackage Program 是可编辑的作者真相。Resolved package facts 是编译器证据。公开 Track 是终端的视听贡献。Composition 绝不能从第三层反推出前两层。-“扁平 Track”意味着不存在 Track 嵌套,也不存在隐式的 Track 层叠上下文。一个 Present 仍然可以拥有自己-内部的 element 树。一条创作 Track 可以在互不相关的绝对层叠位置上输出多个 Present,从而让对等 Track+“扁平 Track”意味着不存在 Track 嵌套,也不存在隐式的 Track 层叠上下文。一个 Present 仍然可以拥有自己内部的 element 树。一条创作 Track 可以在互不相关的绝对层叠位置上输出多个 Present,从而让对等 Track能够穿插在它们之间。## 必需的见证@@ -56,13 +52,11 @@ Composition 绝不能从第三层反推出前两层。### E2 —— Caption range/cue/content lowering-Caption 包必须能够 lower 出一个硬性的区间边界、一个 cue 级的对齐/动画容器、收缩包裹的行,以及可以-独立设置样式或动画的词。双字体和逐词 paint 都是包内事实。Composition 只看到普通的 element 与 Present。+Caption 包必须能够 lower 出一个硬性的区间边界、一个 cue 级的对齐/动画容器、收缩包裹的行,以及可以独立设置样式或动画的词。双字体和逐词 paint 都是包内事实。Composition 只看到普通的 element 与 Present。### E3 —— Media 双帧 lowering-media 包必须能够 lower 出一个已解析的 Placement Frame,其中包含同一个 Artifact 的两次独立采样。每次-采样按 [`spatial-layout.md`](./spatial-layout.md) 推导自己的 Content Frame:+media 包必须能够 lower 出一个已解析的 Placement Frame,其中包含同一个 Artifact 的两次独立采样。每次采样按 [`spatial-layout.md`](./spatial-layout.md) 推导自己的 Content Frame:- 一个背景采样,带自己的 cover/zoom/blur/tone 处理;- 一个前景采样,带自己的 contain/cover/fit-height 与焦点对齐。@@ -72,17 +66,13 @@ media 包必须能够 lower 出一个已解析的 Placement Frame,其中包含### E4 —— 独立的绝对层叠一个包可以在某个绝对层叠位置输出一块 board,同时在其他位置输出图标或标签。来自另一条 Track 的 Present-必须能够出现在它们之间。Track 身份只是把一份自包含的渲染贡献归组;来源信息存在于 Graph/Derivation 中,-而 Track 永远不构成渲染层叠上下文。+必须能够出现在它们之间。Track 身份只是把一份自包含的渲染贡献归组;来源信息存在于 Graph/Derivation 中,而 Track 永远不构成渲染层叠上下文。### E5 —— 局部 motion 与交接-帧精确的 opacity、transform、filter 与 clip 动画,可以作用在某一个 Present 所拥有的 element 上。同时-拥有交接双方素材的包,可以 lower 出互补的 Present。任何普通 Track 都不得采样其下方已累积的像素,也不得-修改同级 Track。+帧精确的 opacity、transform、filter 与 clip 动画,可以作用在某一个 Present 所拥有的 element 上。同时拥有交接双方素材的包,可以 lower 出互补的 Present。任何普通 Track 都不得采样其下方已累积的像素,也不得修改同级 Track。-Media 包还必须额外证明:进入、维持、退出、逐层采样 motion 与 Sequence 配对交接,始终是分离的通道并具有-固定的合成顺序。独立的 Depth-Stack Deck 包必须证明其集合状态的重排能与 Card 局部 motion 组合,且不会把+Media 包还必须额外证明:进入、维持、退出、逐层采样 motion 与 Sequence 配对交接,始终是分离的通道并具有固定的合成顺序。独立的 Depth-Stack Deck 包必须证明其集合状态的重排能与 Card 局部 motion 组合,且不会把Deck 含义带进终端 Track。完整模型在 [`media-track.md`](./media-track.md) 和[`deck-track.md`](./deck-track.md) 中定义。@@ -94,16 +84,13 @@ Surface 贡献出来。为了实现透明穿插,最终的公开合同必须绑### E7 —— 通用音频 lowering-官方 Audio 包必须能把任意显式的归一化源、源裁切、一次性播放、循环、有界的保持音高拉伸、起止对齐、增益-与淡入淡出,全部 lower 进同一条对等的 `AudioTrack` 窄腰。重叠的 clip 混合时不做优先级裁剪,也没有特权-的 Base 声道。容器流选择、响度处理与 Provider 放置仍然是上游或下游图中显式的工作。完整边界在+官方 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 构成。它不能读取已累积的下层合成结果,不能预留最高 z-index,也不能引入合成后阶段。因此无源的模糊、调色和真实的 zoom-blur 都会 fail closed;它们诚实的形态是在 Screen Overlay 包之外消费显式的媒体或Surface 输入。参见 [`screen-overlay.md`](./screen-overlay.md)。## 旧系统攻击矩阵@@ -128,12 +115,10 @@ Surface 输入。参见 [`screen-overlay.md`](./screen-overlay.md)。## 当前的可执行证据-`packages/hyperframes/test/track-expressiveness.test.ts` 构造的是包内私有的 lowering 见证,而不是往公开-合同里加 Text、Caption、Media 或 Ranking 字段。已有的包测试另外证明了普通的 Text、Caption 与 Media+`packages/hyperframes/test/track-expressiveness.test.ts` 构造的是包内私有的 lowering 见证,而不是往公开合同里加 Text、Caption、Media 或 Ranking 字段。已有的包测试另外证明了普通的 Text、Caption 与 MediaProgram 都经由同一条 Track 与 Composition 路径 lower。-当前的 `VisualTrack / VisualPresent / VisualElement` 候选显式绑定 `svml.visual-ir@1`,能够编码结构性的-三盒、两盒、词级局部和绝对层叠等情形。有两条通用的终端事实现在是可执行的,而不是包族补丁:+当前的 `VisualTrack / VisualPresent / VisualElement` 候选显式绑定 `svml.visual-ir@1`,能够编码结构性的三盒、两盒、词级局部和绝对层叠等情形。有两条通用的终端事实现在是可执行的,而不是包族补丁:1. `FontArtifactRef` 把每个精确的 fallback 字面、weight 和 style 绑定到一个或多个 Blob 源。Unicode-range 分片仍然算一个逻辑字面;精确的文本 lowering 会为每个源输出按内容寻址的@@ -141,24 +126,13 @@ Program 都经由同一条 Track 与 Composition 路径 lower。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 会拒绝携带+`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`+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 并集之上的纯绝对帧集合重排,同时复用了@@ -179,5 +153,4 @@ Card 局部的 Media lowering。`@narratage/ranking` 提供了真正的 E4 见6. 一个包可以修订自己的 Program schema,同时只需保持或版本化自己的 lowerer;7. 不受支持的跨 Track 采样 fail closed。-因此该实现对后续的仓库包工作已经冻结。公开的 npm 发布、非受信代码隔离与最终的发布版本号仍然是独立的-发布门;它们不会重新打开这条窄腰的视频含义。+因此该实现对后续的仓库包工作已经冻结。公开的 npm 发布、非受信代码隔离与最终的发布版本号仍然是独立的发布门;它们不会重新打开这条窄腰的视频含义。diff --git a/docs/zh/guide/spec/typography-track.md b/docs/zh/guide/spec/typography-track.mdindex 867af8ae..25a64b89 100644--- a/docs/zh/guide/spec/typography-track.md+++ b/docs/zh/guide/spec/typography-track.md@@ -22,8 +22,7 @@ authored document× deterministic local motion```-一个普通的透明标题、整句话外面套一个背景、每一行渲染行各套一个背景、孤立的词 Pill、连成一体的荧光笔-几何,以及逐字素簇的打字机效果,都是这个模型中的不同取值。它们不是不同的渲染器组件,也不需要在 Core、+一个普通的透明标题、整句话外面套一个背景、每一行渲染行各套一个背景、孤立的词 Pill、连成一体的荧光笔几何,以及逐字素簇的打字机效果,都是这个模型中的不同取值。它们不是不同的渲染器组件,也不需要在 Core、Film 或 Composition 里开分支。“完整”不等于把有史以来所有特效都塞进一个扁平对象。它的意思是:@@ -41,8 +40,7 @@ HyperFrames 只是这门语言的一个渲染器,而不是 Text 的定义。### 2.1 Current Narratage slice-当前 `packages/typography-track` 的实现只有一个固定矩形框、一个纯字符串,以及一个包含颜色、字号、字族、-字重、行高、水平/垂直对齐、单一背景、圆角、内边距和字距的 `TextAppearance`。它的 Surface 恰好只接受+当前 `packages/typography-track` 的实现只有一个固定矩形框、一个纯字符串,以及一个包含颜色、字号、字族、字重、行高、水平/垂直对齐、单一背景、圆角、内边距和字距的 `TextAppearance`。它的 Surface 恰好只接受`text`、`during` 和 `appearance`;它的 Recipe 恰好要求十一个标量属性。它目前无法表达:@@ -70,8 +68,7 @@ HyperFrames 只是这门语言的一个渲染器,而不是 Text 的定义。- frame/content/line/word 背景目标;- line box、cap height 和 ink bound 三种度量。-它的渲染器还实现了纯色/渐变字形填充、外描边、阴影、辉光、气泡尾巴、整个 item 的入场/循环运动、打字机-显现以及行/词背景。这些都是有价值的行为见证。+它的渲染器还实现了纯色/渐变字形填充、外描边、阴影、辉光、气泡尾巴、整个 item 的入场/循环运动、打字机显现以及行/词背景。这些都是有价值的行为见证。这份实现同样暴露了它为什么不能被照搬成新合同:@@ -84,8 +81,7 @@ HyperFrames 只是这门语言的一个渲染器,而不是 Text 的定义。- 一个指针会悄悄创建出背景,而且好几个默认值是渲染器自己发明的;- 完全没有富 run、路径文字或可重复 Paint Layer 的模型。-一份经过审计的历史导出包含 32 个 Text Track 和 53 个 Text item。使用频率最高的属性是对齐、字族/字号、-颜色、字重、背景、圆角和内边距。描边、大写、不换行、全宽背景、字距和阴影也有使用。该样本中没有任何+一份经过审计的历史导出包含 32 个 Text Track 和 53 个 Text item。使用频率最高的属性是对齐、字族/字号、颜色、字重、背景、圆角和内边距。描边、大写、不换行、全宽背景、字距和阴影也有使用。该样本中没有任何Text 动画使用记录。这证明了常规交付的基线;但它不足以成为排除下文那些成熟编辑器能力的理由。### 2.3 External editor attack matrix@@ -129,8 +125,7 @@ Text 动画使用记录。这证明了常规交付的基线;但它不足以成VisualTrack lowering```-Point、Area 和 Path 之所以是三个独立的作者组件,是因为它们断言的几何不同。它们不是那种会让端口忽隐忽现-的 `mode` 字段。它们仍然可以下降到同一个带标签的 `TextItemProgram` 联合类型,并作为对等 item 共存于同一个+Point、Area 和 Path 之所以是三个独立的作者组件,是因为它们断言的几何不同。它们不是那种会让端口忽隐忽现的 `mode` 字段。它们仍然可以下降到同一个带标签的 `TextItemProgram` 联合类型,并作为对等 item 共存于同一个Text Track 中。有两项能力的输入实质不同,因此留在常规 Text 之外:@@ -138,12 +133,9 @@ Text Track 中。- Text Mask 组件必须显式消费文字形状和它所遮罩的媒体/图形;它不得去采样恰好位于其下方的那个 Track;- 真正的 3D Text 拥有挤出、材质、灯光和相机语义,通常物化为带 alpha 的 Surface。-在后续的官方发行版中,它们可以是独立的包,也可以是需要单独导入的组件。包的数量是发行决策;但它们的图-合同必须保持分离。两种情况都不会给 Core 增加分支。+在后续的官方发行版中,它们可以是独立的包,也可以是需要单独导入的组件。包的数量是发行决策;但它们的图合同必须保持分离。两种情况都不会给 Core 增加分支。-官方的本地 Text Mask 见证刻意只接受一个精确的单行 Area Text 形状和一个显式的静态 `CompositableSurface`。-富 run、多行/Path 排布、序列动画和定时素材都会 fail closed,并走与 3D Text 相同的“物化 Surface”逃生路线。-这条边界避免了假装浏览器 `foreignObject` 遮罩是可移植且精确的。+官方的本地 Text Mask 见证刻意只接受一个精确的单行 Area Text 形状和一个显式的静态 `CompositableSurface`。富 run、多行/Path 排布、序列动画和定时素材都会 fail closed,并走与 3D Text 相同的“物化 Surface”逃生路线。这条边界避免了假装浏览器 `foreignObject` 遮罩是可移植且精确的。## 4. Authored Text Document@@ -182,8 +174,7 @@ type TextInline =document > paragraph > explicit run > rendered line > Unicode word > grapheme cluster```-`rendered line` 只有在确定了精确字体和最终几何之后才存在。字素簇是常规情况下作者可见的最小动画/装饰单元。-一个 shaped glyph 未必与某个 Unicode 字符或字素簇一一对应,因此公开的作者模型不得假装它们一一对应。+`rendered line` 只有在确定了精确字体和最终几何之后才存在。字素簇是常规情况下作者可见的最小动画/装饰单元。一个 shaped glyph 未必与某个 Unicode 字符或字素簇一一对应,因此公开的作者模型不得假装它们一一对应。## 5. Three spatial forms@@ -195,8 +186,7 @@ point/frame/path 几何;Text 随后用三种形态之一去解释这份几何### 5.1 Point Text-Point Text 是锚定在某个解析点上的固有尺寸文字。它通常紧贴内容、不做软换行,并使用显式的内联/块级锚点。-手动分段仍然有效。常规的标题、标签和贴纸都是 Point Text。+Point Text 是锚定在某个解析点上的固有尺寸文字。它通常紧贴内容、不做软换行,并使用显式的内联/块级锚点。手动分段仍然有效。常规的标题、标签和贴纸都是 Point Text。### 5.2 Area Text@@ -214,14 +204,11 @@ Area Text 在解析出的 frame 内排布。它显式选择:- 是否裁剪到摆放 frame;- 度量边:line box、cap height 或 ink bounds。-溢出是诚实的作者意图。`ellipsis` 可能省略掉可见的被声明文字,因此必须显式写出。`shrink` 必须声明最小-缩放比例,并在完整文字仍放不下时失败;它不得悄悄越过那个下限。这一点与 Caption 不同——Caption 绝不能裁剪-或丢弃作者的显示 Atom。+溢出是诚实的作者意图。`ellipsis` 可能省略掉可见的被声明文字,因此必须显式写出。`shrink` 必须声明最小缩放比例,并在完整文字仍放不下时失败;它不得悄悄越过那个下限。这一点与 Caption 不同——Caption 绝不能裁剪或丢弃作者的显示 Atom。### 5.3 Path Text-Path Text 消费一条显式自有的矢量路径,外加 Text Document 和 Style。它拥有路径侧、朝向、起止边距、对齐、-反向和溢出。给边距做动画会让文字沿路径移动;给路径做动画则改变路径本身。它绝不会去发现或采样另一个+Path Text 消费一条显式自有的矢量路径,外加 Text Document 和 Style。它拥有路径侧、朝向、起止边距、对齐、反向和溢出。给边距做动画会让文字沿路径移动;给路径做动画则改变路径本身。它绝不会去发现或采样另一个Track 中的形状。Path Text 需要一个通用的矢量/路径终端原语,或者一个自有的物化 Surface。它不能靠序列化一段无类型的@@ -242,8 +229,7 @@ Typography 与 Paint、布局相互分离,但参与布局度量。它包括:- 文字变换、小型大写字母、上标与下标的呈现;- 所选布局实现支持时的 CJK 专用间距/压缩控制。-精确的字体字节仍是显式的作者图输入。它们不是藏在 Recipe 里的名字,也不由 Runtime 挑选。字体 shaping/布局-实现的身份由被接受的推导/渲染 receipt 绑定;Core 仍然对字体一无所知。+精确的字体字节仍是显式的作者图输入。它们不是藏在 Recipe 里的名字,也不由 Runtime 挑选。字体 shaping/布局实现的身份由被接受的推导/渲染 receipt 绑定;Core 仍然对字体一无所知。## 7. Ordered Paint model@@ -263,8 +249,7 @@ type TextPaintLayer =````ColorPaint` 支持纯色、线性渐变和径向渐变,带一份有序的颜色与不透明度 stop 列表。重复使用 Stroke 或-Shadow 是合法的,顺序具有语义。渲染器可以用复制字形 Layer 的方式来下降外描边,但那是实现细节,而不是-一个含义随浏览器而变的作者开关。+Shadow 是合法的,顺序具有语义。渲染器可以用复制字形 Layer 的方式来下降外描边,但那是实现细节,而不是一个含义随浏览器而变的作者开关。Box Paint 有这些目标:@@ -273,8 +258,7 @@ frame | content | paragraph | line | run | word | grapheme```它的装饰独立拥有填充、border、内边距、各角圆角和阴影。`isolated` 为每个目标创建一个独立的装饰单元。-`joined` 在每一条渲染行内把相邻的被选片段合并,并给该行片段一个诚实的端头。非法组合(例如在 `frame` 上-使用 continuity)会在 Text 校验期失败。+`joined` 在每一条渲染行内把相邻的被选片段合并,并给该行片段一个诚实的端头。非法组合(例如在 `frame` 上使用 continuity)会在 Text 校验期失败。这一条规则就表达了常见的全部情形:@@ -288,9 +272,7 @@ frame | content | paragraph | line | run | word | grapheme| 连成一体的马克笔/荧光笔 | `target=word, continuity=joined` || 字母块 | `target=grapheme, continuity=isolated` |-气泡尾巴是显式声明、附着在某个 Box Paint Layer 上的部件,带有方位、偏移、尺寸和自己的 Paint。它不会悄悄-强制生成一个背景。毛玻璃不属于普通 Box Paint,因为它要采样 Track 背后的像素;它需要一个显式自有的媒体-输入,或者一个物化的自包含组件。+气泡尾巴是显式声明、附着在某个 Box Paint Layer 上的部件,带有方位、偏移、尺寸和自己的 Paint。它不会悄悄强制生成一个背景。毛玻璃不属于普通 Box Paint,因为它要采样 Track 背后的像素;它需要一个显式自有的媒体输入,或者一个物化的自包含组件。## 8. Motion and sequence selectors@@ -306,24 +288,16 @@ frame | content | paragraph | line | run | word | graphemeunit selector × selected property channels × keyframes × stagger/order```-单元选择器可以指向 paragraph、line、run、word 或 grapheme。它显式选择范围、正向/反向顺序、延迟/扩散、-循环次数以及任何确定性随机种子。属性通道包括局部变换、不透明度、模糊和字形 Paint 值。打字机是这个模型上-的一个字素簇显现预设,而不是字符串切片。滚动字幕和横向滚动只是 Area Text 上普通的 item 级运动。+单元选择器可以指向 paragraph、line、run、word 或 grapheme。它显式选择范围、正向/反向顺序、延迟/扩散、循环次数以及任何确定性随机种子。属性通道包括局部变换、不透明度、模糊和字形 Paint 值。打字机是这个模型上的一个字素簇显现预设,而不是字符串切片。滚动字幕和横向滚动只是 Area Text 上普通的 item 级运动。-任何运动名称都不是隐藏的回调。`pop`、`spring`、`slide` 或 `wobble` 这类预设,会在终端渲染之前编译成有限的-或在解析上有界的、由包自有的运动值。两条运动通道通过各自独立的包裹器或显式的变换合成顺序进行合成;后者-不会覆盖前者。+任何运动名称都不是隐藏的回调。`pop`、`spring`、`slide` 或 `wobble` 这类预设,会在终端渲染之前编译成有限的或在解析上有界的、由包自有的运动值。两条运动通道通过各自独立的包裹器或显式的变换合成顺序进行合成;后者不会覆盖前者。-动画的生命期与 Item 的可见性相互独立。一段运动可以在 Item 窗口结束前就完成,此时它最终被声明的状态一直-保持到 Item 消失。一段运动也可以超出窗口,此时 Item 窗口只是裁剪它,而不改写它的时序。序列运动和 Path-Text 运动遵循同样的规则。这既避免了仅仅因为标题一直可见就拒绝一段完全合理的快速标题动画,也避免了为了-塞进短窗口而悄悄给慢速动画重新计时。+动画的生命期与 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。+声明与使用保持分离。SVS 仍是通用的标量 Recipe 语言;它不得学会 Text 的 Paint 数组,也不得变成第二个渲染器。Text Style Surface 读取具名 Recipe、精确的 Font 引用和重复的结构化 Layer 声明,校验它们,然后产出一份完整的、由包自有的 `TextStyle` Record。预期的作者写法是:@@ -362,9 +336,7 @@ item 也可以改为消费一个普通的图 `Text` 值:</text:Track>```-`content={Text}` 与内联正文内容互斥。前者从精确的图值物化出一段纯文本文档 run;后者拥有有界的富文档,-并可使用 `P`、`Span` 和 `Break`。这既阻止了 Frontend 把运行时 Text 复制进隐藏的被声明状态,又让富排版-明确归本包所有。+`content={Text}` 与内联正文内容互斥。前者从精确的图值物化出一段纯文本文档 run;后者拥有有界的富文档,并可使用 `P`、`Span` 和 `Break`。这既阻止了 Frontend 把运行时 Text 复制进隐藏的被声明状态,又让富排版明确归本包所有。这套写法在当前共享的时间/空间 Surface 语法上可执行。它的重要性质是:@@ -403,9 +375,7 @@ Composition -> selected final renderer每一项外部依赖都由图边承载。Text 值只包含固有的 Text 语义。任何上游 Record 都不会仅仅因为后面某个 Text消费者需要,就凭空长出 text、role、source、style、font 或 layout 元数据。-布局实现可以使用被锁定的浏览器、HarfBuzz/Skia/Pango 或其他精确引擎。它必须绑定实际的实现和字体字节。-浏览器的 line box 不会作为通用图元数据向外传播;它要么是渲染器 receipt 所拥有的确定性终端布局,要么是包-自有的、用于物化 Surface 的已解析几何。+布局实现可以使用被锁定的浏览器、HarfBuzz/Skia/Pango 或其他精确引擎。它必须绑定实际的实现和字体字节。浏览器的 line box 不会作为通用图元数据向外传播;它要么是渲染器 receipt 所拥有的确定性终端布局,要么是包自有的、用于物化 Surface 的已解析几何。## 11. Terminal Visual IR findings@@ -417,19 +387,15 @@ Composition -> selected final renderer- 有序可重复的 Paint 与 Unicode 单元动画始终是序列化数据,绝不是回调;- 精确的字体 Artifact 和带类型的 `CompositableSurface` 值走普通的 Artifact 边界。-HyperFrames 参考编译器实现了这些原语,同时不向作者包暴露 HTML、CSS、SVG 或渲染器脚本。一个单独安装的-非原生 Text fixture 证明了挤出/材质/灯光/相机语义可以留在窄腰之外,只贡献一个带类型的 alpha Surface。-不受支持的富遮罩走同一条路径。+HyperFrames 参考编译器实现了这些原语,同时不向作者包暴露 HTML、CSS、SVG 或渲染器脚本。一个单独安装的非原生 Text fixture 证明了挤出/材质/灯光/相机语义可以留在窄腰之外,只贡献一个带类型的 alpha Surface。不受支持的富遮罩走同一条路径。-这些始终是视频终端的事实,绝不是 Core 的事实。渲染器 receipt、Surface 字节校验、Deck/Ranking 见证以及最终的-兼容性审计,如今都在不向共享窄腰添加 Text 语义的前提下通过。+这些始终是视频终端的事实,绝不是 Core 的事实。渲染器 receipt、Surface 字节校验、Deck/Ranking 见证以及最终的兼容性审计,如今都在不向共享窄腰添加 Text 语义的前提下通过。## 12. Feedback into Fine CaptionText 与 Caption 共享的是排版实现难题,而不是作者语义。-下列内容可以通过一个聚焦的视频领域实现库共享(暂定为 `@narratage/typography`);在真正出现跨包边之前,-它没有 Author Surface,也没有图 Type:+下列内容可以通过一个聚焦的视频领域实现库共享(暂定为 `@narratage/typography`);在真正出现跨包边之前,它没有 Author Surface,也没有图 Type:- Unicode 字素簇/词/双向切分;- 精确的字体栈加载与 shaping;@@ -438,8 +404,7 @@ Text 与 Caption 共享的是排版实现难题,而不是作者语义。- 字素簇安全的打字机效果与确定性的选择器求值;- 终端富文本下降辅助函数。-这并不会造出一个通用的 Text Program。Caption 仍保留 `CaptionDisplaySequence`、Cue、Atom、语音对应关系和-卡拉 OK 时序。Text 仍保留段落、富 run、point/area/path 布局和任意序列选择器。+这并不会造出一个通用的 Text Program。Caption 仍保留 `CaptionDisplaySequence`、Cue、Atom、语音对应关系和卡拉 OK 时序。Text 仍保留段落、富 run、point/area/path 布局和任意序列选择器。本次审计发现的、可落到 Caption 上的具体改进是:@@ -449,8 +414,7 @@ Text 与 Caption 共享的是排版实现难题,而不是作者语义。4. 复用字素簇安全的文字变换/显现以及精确 shaping;5. 把 joined 的活动 Pill 几何保留在共享的行片段实现上。-Caption **不得**继承 Text 的 ellipsis、裁剪、缩放适配、路径排布、任意富 run 时序或选择器生成的语音时序。-它始终展示作者完整的不可变 Atom,并且只从已证明的 Atom 窗口激活。+Caption **不得**继承 Text 的 ellipsis、裁剪、缩放适配、路径排布、任意富 run 时序或选择器生成的语音时序。它始终展示作者完整的不可变 Atom,并且只从已证明的 Atom 窗口激活。## 13. Migration order and acceptance gatesdiff --git a/docs/zh/guide/spec/visual-ir.md b/docs/zh/guide/spec/visual-ir.mdindex 2a5020e1..76989c50 100644--- a/docs/zh/guide/spec/visual-ir.md+++ b/docs/zh/guide/spec/visual-ir.md@@ -18,8 +18,7 @@ description: 已实现的仓库内部 `@1` 兼容窄腰;尚未作为 npm ABIText、Caption、Media、Ranking 以及第三方视觉包可以各自持有互不相干的作者 Program。但在进入`Composition` 之前,每个包都必须把自己解析后的结果下降为一个显式指明本 IR 的 `VisualTrack`。渲染器-adapter 校验并编译这门共同语言;它永远不需要知道来源是哪个组件家族。`@narratage/hyperframes` 是第一个-参考 adapter,而不是协议的持有者。+adapter 校验并编译这门共同语言;它永远不需要知道来源是哪个组件家族。`@narratage/hyperframes` 是第一个参考 adapter,而不是协议的持有者。```textauthor Program shared terminal protocol final-render route@@ -30,8 +29,7 @@ custom visual producer ───> typed CompositableSurface ───┤└─> future render API```-把它称作组件“方言”是一种误导。当前视频栈只有一个官方目标协议。一个组件不可能引入另一套 CSS 语义,同时-还声称自己产出的是同一份 IR。+把它称作组件“方言”是一种误导。当前视频栈只有一个官方目标协议。一个组件不可能引入另一套 CSS 语义,同时还声称自己产出的是同一份 IR。## 合同@@ -53,14 +51,12 @@ visualIr = svml.visual-ir@1- 按帧寻址、作用于 opacity、transform、filter 与 clip 的局部 keyframe;- 安全的 data/ARIA 属性。-它不包含组件家族、作者 recipe、provider 名称、选择器、脚本、外部 URL、运行时凭据、同级 Track 引用,也-不包含累积合成输入。+它不包含组件家族、作者 recipe、provider 名称、选择器、脚本、外部 URL、运行时凭据、同级 Track 引用,也不包含累积合成输入。## 封闭的渲染词汇实现导出 `VISUAL_STYLE_NAMES_V1`。不在该清单内的声明一律非法,即使某个特定的 Chromium 构建恰好能理解它。-`position`、`display`、`overflow`、`object-fit`、direction 和 writing mode 这类关键的枚举型事实,还额外-使用封闭值集。+`position`、`display`、`overflow`、`object-fit`、direction 和 writing mode 这类关键的枚举型事实,还额外使用封闭值集。以下情况一律失败关闭:@@ -84,8 +80,7 @@ visualIr = svml.visual-ir@1血缘字段;4. 被选中的本地或托管渲染 Endpoint 锁定实际的渲染器实现,并校验产出的媒体事实。-Core 内不含任何视频专用分支。它的通用准入通路会调用已安装的 Type 持有者 validator,来校验内在的树、样式-与 Artifact 事实。涉及另一个值的关系性校验,仍然是普通的多输入 Producer 检查。+Core 内不含任何视频专用分支。它的通用准入通路会调用已安装的 Type 持有者 validator,来校验内在的树、样式与 Artifact 事实。涉及另一个值的关系性校验,仍然是普通的多输入 Producer 检查。## 扩展法则@@ -94,8 +89,7 @@ Core 内不含任何视频专用分支。它的通用准入通路会调用已安1. 把自己的 Program 下降为已有的元素与样式;或者2. 把它所持有的视觉物化为一个带类型的 `CompositableSurface`,并贡献该 Surface。-只有当某项能力既具备广泛复用价值,又无法通过上述两条路径表达时,才有理由改动 `svml.visual-ir@1` 合同。-在 Narratage 处于预发布阶段期间,标识符保持为 `@1`,确切的实现身份由摘要和 package lock 承载。新增一种+只有当某项能力既具备广泛复用价值,又无法通过上述两条路径表达时,才有理由改动 `svml.visual-ir@1` 合同。在 Narratage 处于预发布阶段期间,标识符保持为 `@1`,确切的实现身份由摘要和 package lock 承载。新增一种Text 样式、Caption 模式、Media recipe、转场或 Provider,本身永远不构成理由。因此,旧系统的 Text 三盒模型、Caption 的 range/cue/content 模型和 Media 的内容帧采样模型,都属于包自有的@@ -103,8 +97,7 @@ Program 与下降证据。它们是本 IR 表达力的见证,而不是被加## 冻结证据-标识符与封闭词汇都是可执行的。精确的 Text 字体、多行装饰、Path/Mask/overflow、Media 焦点采样和 alpha 现在-都有真实的浏览器证据;一个单独安装的非原生 Text 包可以穿过带类型的 Surface 窄腰,而不改动 Core、Film 或+标识符与封闭词汇都是可执行的。精确的 Text 字体、多行装饰、Path/Mask/overflow、Media 焦点采样和 alpha 现在都有真实的浏览器证据;一个单独安装的非原生 Text 包可以穿过带类型的 Surface 窄腰,而不改动 Core、Film 或HyperFrames。仓库内部的 `@1` 窄腰之所以被冻结,是因为以下四道彼此独立的闸门现在都能真正执行:1. 通用的 Need Receipt 绑定被锁定的 Endpoint 实现/配置/Runtime closure,同时 HyperFrames 那份被 receipt@@ -115,5 +108,4 @@ HyperFrames。仓库内部的 `@1` 窄腰之所以被冻结,是因为以下四4. 全仓库的边界审查证明 Composition 中不含任何包家族/provider 判别字段,且终端编译器中不存在隐藏的跨 Track采样通路。-这为本仓库后续的包开发冻结了该协议。它并不意味着 npm 包已经发布、每个作者 Surface 都已冻结,也不意味着未来-的公开发布可以跳过分发与安全审查。+这为本仓库后续的包开发冻结了该协议。它并不意味着 npm 包已经发布、每个作者 Surface 都已冻结,也不意味着未来的公开发布可以跳过分发与安全审查。