aip-composition 是面向 AI Producer 插件的合成与编辑器契约说明，来源为 opus-pro/ai-producer-plugin。它只描述编辑器与导出两条渲染路径共同读取的接口，不规定画面内容、动画方式、字幕位置等创作决策，这些由作者自行决定。
用途与定位：该页面用于在 AI Producer 项目中以 HTML 方式编写视频合成。核心理念是“HTML 就是视频”：一个合成是带有 data-* 时间属性的 HTML 元素，加一条暂停的 GSAP 时间线，由播放器驱动。AI Producer 编辑器用自己的播放器播放该 HTML，导出则使用 AI Producer 固定版本的 HyperFrames 渲染，两者是独立程序，遵循各自的播放与编辑契约。
项目结构：项目位于 render-engine/ 下，包含 index.html、compositions/*.html 以及 public/ 下的素材。AI Producer 会暂存 public/source.mp4（录制画面）和 public/source.mp3（其音频），并将 GSAP 放在 public/vendor/gsap.min.js，合成需从该路径加载 GSAP。项目外部的脚本会被拒绝，因此合成逻辑必须内联。
主要能力与约定：
- 渲染分工：文字、标签、卡片、计数器等用户可能想改文字或改样式的元素应做成由 GSAP 动画的 DOM 元素，并用 CSS 3D（perspective、3D 旋转、translateZ 堆叠）赋予真实景深；3D 物体、着色器表面或 DOM 难以承载的密集数据则用 canvas 绘制（3D 用 Three.js）。编辑器把 canvas 当作单个叶子节点，用户无法选中或改样式，故可编辑内容应保留在 DOM 中。
- 根舞台：<div id="stage" data-composition-id="finecut-root" ...> 需直接放在 body 中，不能放进 <template>。id 固定，编辑器通过 window.__timelines["finecut-root"] 寻找根时间线。
- 说话人：视频 speaker 静音，source.mp3 为可听主音轨；剪切后使用多组音视频对，每组有 class="clip speaker-clip"、唯一 id 及时间属性，DOM 顺序即输出顺序。
- 视觉时刻：每个时刻用一个带 data-composition-src 的 visual-host div 承载，是独立图层，下方画面不可见；需要与下方叠加的混合效果应写在宿主 div 上。宿主可携带字幕策略属性（data-hide-captions、data-caption-position、data-caption-ink）。
- 字幕：字幕时刻为普通视觉时刻，id 为 captions-<n>；narrator-captions 是服务写入的字幕层，作者不得写入或复用其 id。
- 画中画：属于可编辑视觉时刻的说话人座位或 PIP 放在该时刻内部，使用 speaker-pip-frame 与 data-pip-src，其 data-start 取宿主全局开始时间。
- 外来片段：用户或库存片段默认写为 index.html 中独立轨道上的根视频片段，或嵌套在时刻合成内；根片段用户可在时间线上移动，嵌套片段随时刻移动。
- 缩放与滤镜：使用空的宿主 div，data-aip-effect="zoom" 或 "filter"，配合 data-effect-scale、data-effect-origin、data-effect-filter、data-effect-in/out 等属性；需在根脚本后加载 public/vendor/speaker-effects.js，该文件由服务在首次加载的提交中写入，不要自行上传。
- 运动效果：使用 data-aip-effect="motion" 的宿主与内联 <script data-aip-motion> 定义 frame 函数，参数需声明为用户可调项，且脚本中不得读取 Math.random、Date、performance 等非确定性来源。
- 子合成文件：使用 <template> 包裹内容，内部 div 的 data-composition-id 与宿主一致，通过 [data-composition-id="<id>"] 绑定根，并通过后代查询访问元素；时间线 0 对应宿主 data-start，播放器只 seek 不播放。
使用方式：按上述结构在 render-engine/ 下编写 index.html、compositions/*.html 与素材，加载指定路径的 GSAP 与 speaker-effects.js，并在 index.html 内联注册各时间线。上传与限制遵循 AI Producer 工作区格式；外部脚本被拒绝。
适用场景：为 AI Producer 插件制作可编辑的 HTML 视频合成，包括标题卡片、字幕、画中画、镜头缩放/滤镜、震动、闪白、甩镜、推镜等镜头处理，以及混合 canvas 与 DOM 的场景。
限制：本地动画样例通过或上传被接受，并不代表编辑器或导出正确；canvas 内容无法被用户编辑；字幕层只能由服务写入；缩放与滤镜、运动效果有轨道与参数上限；外部脚本被拒；字幕文件需内联 WORDS 数组等。