@gitruck/cli 0.2.17 → 0.2.19

package/contracts/gsap-emit-v1.md

@@ -1,233 +1,301 @@
-# GSAP-emit 契约 v1 · HTML 动画颗粒的逐帧 seek 渲染合规
-
-> **契约版本**：gsap-emit v1（2026-07-10；2026-07-24 增补铁律 7「占满坑位 + 终态驻留」，主理人硬性规定；同日铁律 6 增补字体注册表命中规则，对齐 gitruck-infra change `align-render-font-contract`；**2026-07-26 增补「回调与 seek 语义」一节**——补此前留白，首次对**渲染引擎侧**提出 MUST 条款，对齐 change `define-seek-suppress-events-contract`；**同日该节核实状态转「已核实（行为层）」**——真渲染引擎（`@hyperframes/producer@0.6.101`）三帧实测回调可达、结论绑定该引擎版本；
-> **2026-07-26 铁律 4 按真机实测改写**——实心底 MUST 下沉为根下第一个全幅子层、根元素 MUST 保持零视觉、overlay 颗粒 MUST 在根显式写 `background:transparent`，
-> 附证据锚并消歧铁律编号，对齐 change `align-particle-solid-backdrop-contract`；**同日增补铁律 8「重复图元合并」**——把整组同步驱动的重复图元合并成单元素，以规避一类真渲染横带、纵向重复叠印与逐帧闪烁缺陷；触发轴未知，本条只按零成本写法成文、不设数字门槛，对齐 change `add-particle-primitive-merge-law`）。产 HTML 动画颗粒、经同合云渲染管线（html_animate_render）逐帧 seek 合成的 skill/工具，其产物 MUST 满足本契约。
-> **边界**：本契约只约束**机器可判定的管线消费属性**（封装/注册/确定性/自包含/依赖可达/禁 var()/字体名命中注册表）。画面长什么样——颜色、字体取值、构图、节奏——**一律由调用方按其栏目自身规则决定**，本契约不点名任何具体字体/颜色；文中示例取值均为中性占位。
-
-## 原理（为什么不能用 CSS animation）
-
-渲染引擎逐帧渲染时，靠调用每个子合成在 `window.__timelines` 注册的 GSAP 时间线的 `.seek(t)` 把画面定格到第 t 秒。GSAP `paused` 时间线 = 可被外部 seek 的虚拟时钟 → 逐帧正确；纯 CSS `animation-delay` 动画不在 `window.__timelines` 里，引擎 seek 不到 → 画面冻结（实测）。
-
-## 回调与 seek 语义（2026-07-26 增补 · 补此前留白）
-
-> **一句话**：颗粒**可以**用时间线回调（`onUpdate` 等）驱动画面；**保证这些回调在定帧时被触发是渲染引擎侧的义务**，不是颗粒作者的义务。
-> 本节是该主题的**唯一口径来源**——契约引用（`skills/gtrk-style-maker/references/contracts-ref.md`）与消费侧检查（`gtrk mg lint`）的文案都指向这里，不得各自表述。
-
-### 一、GSAP 3.13.0 实测事实（写死在此，免后来者重测）
-
-复现方式：拉铁律⑤指定 CDN 的 `gsap.min.js` 到本地，Node `vm` 里造 `paused` timeline + proxy 对象 + 计数回调，**每种定位方式各新建一条 timeline 单独跑**（回调计数互不串）。
-
-**样本一**——10s、`ease:"none"` 的单条 tween（`{v:0}` → `{v:100}`），分别 seek 到 t=5（中途）与 t=10（末端）：
-
-| 定位方式 | `onUpdate` / `onStart` | `onComplete` | 补间目标属性 |
-|---|---|---|---|
-| `tl.seek(t)`（默认，`suppressEvents` 缺省为 `true`） | **不触发** | **不触发**——连 `seek(10)`（到末端）也不触发 | 已更新（t=5 → `v=50.00`；t=10 → `v=100.00`） |
-| `tl.seek(t, true)` | 不触发 | 不触发 | 已更新 |
-| `tl.seek(t, false)` | 触发 | `seek(10,false)` 触发；`seek(5,false)` 不触发 | 已更新 |
-| `tl.time(t)` / `tl.progress(p)` / `tl.totalTime(t)` | 触发 | 同上（按是否到末端） | 已更新 |
-
-⚠️ **`onComplete` 那两行必须分清**：默认 seek 下它**到末端也不触发**，这才是「被抑制」的证据；而 `false` 模式下 `seek(5,false)` 的 `onComplete` 不触发，只是「补间尚未走完」的正常语义。混为一谈，后来者会拿后者误判成「垫片无效」。
-
-**样本二（含真实 DOM 写入 · 引擎侧条款的直接依据）**——同一 t=1.0 定帧点，补间在 t=1.0 处的目标属性期望值 75.0，`onUpdate` 体内做一次真实 DOM 写入：
-
-| 定位方式（同一 t=1.0 定帧点） | `onUpdate` 触发次数 | 补间目标属性 | 回调内的 DOM 写入 |
-|---|---|---|---|
-| `tl.seek(1.0)`（默认） | **0 次** | 已更新为 **75.0** | **未执行** |
-| `tl.seek(1.0, false)` | 1 次 | 75.0 | 正常 |
-| `tl.time(1.0)` | 1 次 | 75.0 | 正常 |
-| `tl.progress(0.5)` | 1 次 | 75.0 | 正常 |
-
-要害是**「值更新了、回调没跑」**：补间目标对象的属性照常插值，但写在 `onUpdate` 里的 DOM 写入一次都不执行。所以这种翻车**不是黑屏，是画面定在初始态**——本地播放器与客户端预览都完全正常，比黑屏更难发现。
-
-样本二同时给出条款一的**可行性依据**：三种「不抑制」写法（`seek(t,false)` / `time(t)` / `progress(p)`）行为**完全一致**，故对引擎侧的要求**可实现且不挑实现**——引擎爱用哪种用哪种，只要不是裸 `seek(t)`。
-
-### 二、条款
-
-1. **引擎侧（MUST）**：渲染引擎定帧时 **MUST 保证 GSAP 时间线回调可达**——MUST 用 `seek(t, false)` 或 `time(t)` / `progress(p)` / `totalTime(t)`，**MUST NOT 用默认的 `seek(t)`**。违反后果：补间目标属性照常更新、回调内的 DOM 写入不执行 → 画面**定在初始态而非黑屏**，本地播放器与客户端预览均看不出异常。
-2. **颗粒侧（合规声明）**：颗粒**可以**用时间线回调（`onUpdate` / `onStart` / `onComplete` / `onRepeat`）写 DOM / 属性来驱动画面——这是**合规**写法（相机推进、数值读数这类效果用纯属性补间难以表达）。其可达性由条款 1 承担；契约 **MUST NOT** 反过来要求颗粒作者自行保证。
-3. **颗粒侧（不应）**：颗粒**不应**在运行时覆写引擎所调用的 API——重新赋值 `tl.seek`、或把 `window.__timelines[…]` 换成包装对象。两条实测理由：① 覆写会推翻引擎**显式**传入的 `seek(t, true)`（实测：打上垫片后 `seek(5)` 与 `seek(6, true)` 两次调用回调都触发），颗粒无权静默否决引擎的意图；② 垫片只作用于 `seek`，引擎改走 `time()` / `progress()` 时**完全失效**，而作者不会知道。
-   已存在的垫片属**过渡态**：**新颗粒不应再加**。**2026-07-26 更新**——条款 1 的前提已经真引擎核实（见下「三」），垫片赖以存在的「真空期」已结束，故已存在的垫片**可择期清理**（清理是**可做**、不是 MUST 做；删后须重跑 lint 并**重渲复验**）。垫片留着也无害：实测引擎既然本就不抑制回调，垫片对画面结果无影响，只会被 lint 记一条非致命的 `x-engine-api-override`。
-4. **作者侧应知（这不是甩锅）**：作者 MUST 知晓——回调可达性的保证方是**引擎侧**，且该保证当前的核实状态见下「三」（2026-07-26 起为**已核实（行为层）· 绑定引擎 0.6.101**）。`gtrk mg lint` 会对「回调驱动画面且无任何兜底」的颗粒给一条**非致命**提醒，那是**哨兵**（引擎换实现或失守时有人喊一声），**不是**「请作者自行保证 seek 下回调可达」——**核实之后哨兵照留**，因为结论绑死引擎版本，换版即须重测。
-
-### 三、核实状态：**已核实（行为层）· 2026-07-26 · 绑定引擎 `@hyperframes/producer@0.6.101`**
-
-**把某条引擎行为写成 MUST，MUST NOT 被当作它已被核实**——二者在本节分别成文。本小节记的是**核实到了什么、以及没核实到什么**。
-
-**结论：真渲染引擎在定帧时 `onUpdate` 回调可达，条款 1 的前提成立。** 结论**绑定上述引擎版本**，换版即失效、须重测。
-
-- **核实方式（真引擎，非本地无头模拟）**：造一颗最小颗粒 `seekcb-probe`，**不打任何 seek 垫片**，画面正中的大号数字**只**由一条 tween 的 `onUpdate` 写入（proxy `{v:0}` → `480`，`ease:"none"`，16s），初值静态写死 `CB 000`；同屏并排一组**纯属性补间**对照物（方块横移 + 进度条拉长，均无回调），刻度尺与回调数字**同单位 0..480**，故单帧之内即可比对「应该是多少」与「实际是多少」。该颗粒先过 `gtrk mg lint`（`lint.ok=true`，`opaque=true`，只出 `x-callback-driven` 哨兵、无 `x-engine-api-override`），排除「因不合规才没渲」。走生产同款装配（`CompositionRender` 整轨路径 / 同底轨 `bed.mp4` / 1920×1080 / fps=60 / 15.97s / 958 帧分片 13 chunk）。
-- **实测结果（三帧，肉眼判读整帧 PNG）**：
-
-  | 抽帧时刻 | 回调驱动的数字（onUpdate 唯一驱动） | 纯属性补间对照物 | 期望值 |
-  |---|---|---|---|
-  | t=2s | **CB 060** | 进度条/方块 @ 60 | 060 |
-  | t=8s | **CB 240** | 进度条/方块 @ 240 | 240 |
-  | t=14s | **CB 420** | 进度条/方块 @ 420 | 420 |
-
-  三帧数字**各不相同**、**无一帧停在初值 `CB 000`**，且**逐帧与同单位对照物精确重合**——即回调不仅被触发，还是在**当前帧对应的时间点**上触发的（不是滞后一帧的陈值）。对照物同时移动，排除「整颗没渲/时间线没被定位」这一混淆解释。
-- **证据留档**：帧 `D:/file/ops/_seekcb/SEEKCB-t2.png` / `-t8.png` / `-t14.png`；成片 r69 `/opt/gitruck/tmp/backdrop-ab-2026-07-26/SEEKCB.mp4`；颗粒 `D:/file/ops/_seekcb/P-seekcb.html`；渲染脚本 `_seekcb_render.py`。引擎版本取自渲染日志自报的 `"producerVersion":"0.6.101"`。
-- **⚠️ 本次核实的边界（MUST NOT 越界引用）**：核实的是**可观测行为**（回调可达），**不是调用形态**。引擎仍是无源码第三方包，本轮**没有**读到定帧调用点，故**无法区分**它走的是 `seek(t,false)` / `time(t)` / `progress(p)`，还是压根不经 GSAP 定位 API 的自有推进方式。条款 1 里那串 API 白名单仍是**应然的实现约束**，只有「回调 MUST 可达」这个**结果**被真机背书。调用形态的核实仍由 gitruck-infra 侧联动 change `link-guarantee-seek-callback-reachability` 承接（读调用点 + 把「纯回调驱动无垫片颗粒渲两帧、像素 MUST 不同」挂进引擎版本变更门禁）。
-- **旁证（本轮之前的间接证据，保留备查）**：gitruck-infra 自家 9 个 music_visualizer 模板 **9/9** 把整块画面挂在单条 tween 的 `onUpdate` 上、且 **0/9** 带任何垫片，走的正是同一渲染内核，而 `gtrk music-visualizer` 是**已上线**能力——若引擎默认抑制回调，这 9 个模板早该渲成静止首帧。本仓 exemplar b06/b07/b08 同理。本轮直接核实**与旁证同向**。
-- **假设失效的后果（哨兵为何 MUST 留）**：结论绑定 `0.6.101`；引擎升版换调用方式 → 全部回调驱动型颗粒（MG 与 music_visualizer 模板）**一起静默冻结**，lint 全绿、退出码 0、无任何告警。故 `gtrk mg lint` 的 `x-callback-driven` 哨兵（条款 4）**MUST NOT 因本次核实而撤**——它防的正是「换版后无人喊一声」。
-
-### 四、连带风险：回调可达 = 逐帧反复触发
-
-条款 1 的另一面：逐帧 scrub 时 `onComplete` / `onStart` / `onRepeat` 会**反复触发**（每帧一次）。故颗粒 **MUST NOT** 把「只跑一次」的逻辑写进回调——累加计数、`push` 进数组、一次性 DOM 插入、抽样。那会把「静默冻结」换成「静默错乱」。
-
-**2026-07-26 起这条从「假设的另一面」变成「已确证的现实风险」**：上「三」已实测该引擎**确实**在逐帧定位时触发回调，故本条不是防患于未然，而是**当下就在生效**的约束。
-
-**推荐写法**：回调做成**幂等**的——每次都从补间状态**重算**整个画面，不依赖上一次的结果（真机与 exemplar 的 `render()` / `apply()` / `paint()` 均如此）。
-
-### 五、优先级
-
-**本节口径优先于任何栏目指南的招式建议。** 栏目指南若与本节冲突，以本节为准。（当前二者同向：栏目指南推荐的 `onUpdate` 驱动写法在本节下**合规**，作坊侧**无需修订**——本节不向作坊侧派发任何待办。此条照写不误，它防的是将来的分歧。）
-
-## 八条铁律（违反任一条 → 整片渲染失败 / 颗粒冻结 / 全黑 / 坑位内突兀消失 / 画面被切成横带、内容纵向重复叠印并逐帧闪烁）
-
-1. **`<template>` 包裹根元素**：`<template><div data-composition-id="<id>" data-width="1920" data-height="1080">…</div></template>`。编译器取的是 `<template>` 内容；裸 `<div>` 会被判 "empty or could not be parsed" 整片失败。（1920×1080 为**当前引擎版本约束**，分辨率参数化预留——升版时以本契约新版为准。）
-2. **GSAP `paused` 时间线 + 注册**：`var tl = gsap.timeline({paused:true}); … window.__timelines = window.__timelines || {}; window.__timelines["<id>"] = tl;`。`<id>` 必须等于根的 `data-composition-id`。
-3. **确定性**：禁用 `Math.random` / `Date.now` / 无参 `new Date()`（过不了引擎 StaticGuard）。要"随机感"用固定种子/解析式/递归生成（见「确定性配方」）。
-4. **自包含 + 实心底下沉子层 + 透明度显式声明**（**2026-07-26 按真机实测改写**；原文「全屏颗粒给根设明确 `background`；透明颗粒根不设 background」**已作废**，见下方证据锚）：颗粒不依赖外部文件（除脚本 CDN）。底色的**取值**由调用方按其栏目规则决定，本契约只管**摆在哪个元素上**。
-   - **① 实心底 MUST 下沉为根下第一个全幅子层**（`position:absolute;inset:0` 或等价的 `top/left/width/height` 铺满），**MUST NOT 写在根元素的 `style` 上**。理由是实测事实：**根元素的绘制属性在子合成挂载时被丢弃**，写在根上的实心底**一个像素都不落地**——成片里表现为「浮空面板」（前景照常渲出、底没了、底轨透出来），本地播放器与客户端预览都看不出。
-   - **② 根元素 MUST 保持零视觉**：根 `style` MUST NOT 出现任何会绘制像素的属性（实心 `background` / `border` / `box-shadow` / `outline` …）。写了不报错，但**不生效**，只会误导后来者以为底已经有了。
-   - **③ 透明与否 MUST 显式声明**：`background` 声明 MUST 至少出现一处——**满屏（不透明）颗粒**写在 ① 的全幅子层上；**透明叠加（overlay）颗粒** MUST 在**根**显式写 `background:transparent`，MUST NOT 靠「不写」表达透明。根上的 `transparent` 虽然同样不落成像素（它本就不绘制），但它是**给人和机器读的意图声明**——缺了它，作者与 `gtrk mg lint` 都无从区分「想透明」与「忘了想」。
-   - **④ 消费侧同源**：`gtrk mg lint` 的 `opaque` 推导面 = 「根 `style` ∪ 根下首个全幅子层 `style`」，与本条 ①③ 同源；两处皆无 `background` 声明才报 `4-bg-explicit`，满屏颗粒把实心底写在根上另报非致命 `4-bg-on-root`。
-5. **脚本用渲染机可达的 CDN（编译期内联）**：`<script src="https://lib.baomitu.com/gsap/3.13.0/gsap.min.js"></script>` 或由渲染管线 vendor 本地。⚠️ jsdelivr 在渲染服务器不稳（实测 compile 期 `fetch failed` → GSAP 未加载 → 整片全黑）。编译器**只内联 http(s) CDN、不内联相对本地路径**（写 `src="gsap.min.js"` 运行时 404）。
-6. **颜色/字体用字面值，禁 CSS `var()` 自定义变量；字体名 MUST 命中服务端注册字体表**：编译器/挂载不可靠地解析 var()（字体映射把 `var(--font-body)` 当字面字体名；颜色 var() 不应用 → 整片全黑，实测）。直接写字面值（如 `#RRGGBB` / `'某字体名'`）；SVG 属性里同样禁 var()。栏目级换色/换主题 = **生成期**替换字面值（查调用方自己的词表/token 注入），不是运行时变量。**字体名规则（2026-07-24 增补）**：font-family 的每个具名家族 MUST 逐字符命中渲染服务端注册字体表（gitruck-infra 仓 `utils/assets/text/classic_template/font_manifest.json`，中英别名等价），并 SHOULD 以 `sans-serif`/`serif` 通用族收尾兜底；表外名字渲染不失败但**字形不保证**（服务端 fail-open 系统回退，2026-07-24 真机实锤：错名导致宋体被渲成回退黑体）。具体选哪款仍由调用方栏目规则决定，本契约不点名。
-7. **占满坑位 + 终态驻留（2026-07-24 主理人硬性规定；2026-07-26 增补无限循环定性）**：颗粒时间线总长 MUST ≥ 它在成片中的**坑位时长**（落轨 clip 的实际时长，通常 = 派单槽位包络 `track_ed − track_st`，**不是** `duration_hint`）；动画主叙事播完后，颗粒 MUST 以「**定格保持**」或「**有限次循环**」驻留到坑位末尾。**禁用无限循环 `repeat:-1`（2026-07-26 增补，补此前留白）**：无限循环让时间线总长为 `Infinity`，本条「总长 ≥ 坑位」就**变得不可验证**（机器与人都无从判断它是否真按坑位算过），且掩盖「作者根本没算坑位」这件事。循环次数 MUST **按坑位算死**——`repeat = ceil((坑位时长 − 循环起点) / 单圈时长) − 1`，宁可多算一两圈（末尾被 clip 裁掉无害），也不许写 `-1` 蒙混——坑位内任意时刻（含最后一帧）核心内容必须可见。**禁止**「整体渐隐到空 / 全局退场 / 清空画面」类收尾：渐隐会与剪辑层转场冲突，淡出与否由剪辑/装配层决定，不在颗粒内做。局部元素可按叙事退场（黯淡/让位），但画面在坑位内不得归零；**定格不动是完全合法的终态**（不必为凑动作密度在尾段硬加动画）。违反表现 = 观感上「动画一过完整个颗粒突兀消失」（2026-07-24 回声定位真机实测）。
-8. **重复图元合并（2026-07-26 增补 · 规避条款，根治在渲染侧）**：同一批**重复图元**——同色、同 `stroke` / `fill`、**整组同步驱动**（只有组级动画或完全静态）的网格、排线、刻度、点阵——**MUST 合并成单个元素**（SVG 用一条 `<path>` 的多子路径 `M…H…V…`；同色分档时可按档合成若干条），**MUST NOT** 用「每条线 / 每个格子一个 `<element>`」的批量构建，无论它写成字面标签还是由 `createElementNS` 循环生成。合并前后画面**逐像素相同**，故本条不涉任何视觉取值。
-   - **豁免**：需要**逐元素动画**（stagger / 逐条画入 / 逐个变色）的批次不在本条范围内——元素身份是该批动画所必需的。此类批次若同时是满幅大面积绘制，MUST 以真渲染出片抽帧验收；这是保守兜底，**不是**「满幅即危险」的风险判据，反向的「不满幅即安全」同样不成立。
-   - **违反表现**：画幅被切成等高横带、相邻带内容互相纵向重复叠印（同一元素在 `y` 与 `y±带高` 各画一次，或被顶部裁半）并逐帧闪烁；该表现与动画逻辑无关，同帧里零动画的静态元素也会重复。DOM 元素数与 `getBoundingClientRect` 均正常，本地播放器与客户端预览看不出。
-   - **这是规避，不是根治**：缺陷出在渲染侧已由真机行为确证——颗粒的 DOM 元素数与布局值正常，不是颗粒写错。机制层面**推断**为渲染侧按等高带做局部栅格刷新时失效区域算错，**属推断、未经渲染侧确认**；**真实触发轴至今未知**，「图元总数」「同页累积负载」「同父同类聚簇」均已被跨颗粒真渲反例否证。本条 MUST NOT 被读成「图元少 / 负载低就安全」。
-   - **根治登记**：根治方 = 渲染管线侧；当前状态 = **未立项（2026-07-26；决策角色 = 本 change 实施者，按 proposal 的跨仓授权边界不代提；是否立项仍待主理人另行授权）**。
-   - **根治后处置预案**：待渲染管线侧根治上线且经真机确认缺陷不再复现后，本条由 **MUST 降为 SHOULD**，并保留「本条曾于 2026-07-26、本证据锚所载引擎版本口径下作为规避所必需」的历史记录。
-
-> **⚠️ 铁律编号的唯一定义在本文件。** 本契约的**铁律 7 = 「占满坑位 + 终态驻留」**，这是框架侧对该条号的**唯一**定义。
-> 创作侧（栏目 skill / 作坊）的模板与 references **MUST NOT 另立同号铁律**——引用请写「gsap-emit v1 铁律 7」并指回本文件，
-> 自己的栏目约束请用**栏目注记**或另起独立编号空间。
-> **已知撞号（2026-07-26 记录，收口中）**：某栏目 references 曾把「根元素零视觉」编为其「铁律 7」、同一条在其模板里又编为「铁律③」——
-> 该约束现已**升为本契约的铁律 4**（见上），栏目侧的两个同名条号 SHALL 改为引用铁律 4，不再另立。
-
-### 铁律 4「实心底下沉子层」的真机证据锚（2026-07-26）
-
-本条断言的是**渲染引擎行为**（「根元素的绘制属性在挂载时被丢弃」），故按契约库要求附可追溯证据锚：
-
-- **结论**：根 `style` 的 `background` **不落成像素**；同一颗粒把同一底色改写到根下首个全幅子层则**满屏落地并盖住底轨**。
-- **实验日期 / 机器**：2026-07-26 · r69（真渲，非本地无头模拟）。
-- **引擎版本口径**：hyperframes CLI `0.6.101` · `@hyperframes/producer` `0.6.101` · chrome-headless-shell `linux-131.0.6778.85`。
-- **设计**：同颗粒母本造两个变体，**唯一变量 = 实心底摆在根 `style` 还是根下首个全幅子层**，其余逐字节相同；
-  底色临时取高饱和标志色以便与「根合成兜底黑」区分；底轨用一段有明显画面、非黑的真人镜头；抽同一时间点 `t=8.0s` 的帧，
-  取四角 `crop=40:40` 于 `(20,20) (1860,20) (20,1020) (1860,1020)` 后 `scale=1:1` 读像素。
-- **观测**（整轨拆分渲染路径，两格同素材同引擎同批）。
-  ⚠️ 下表的六位数字是**抽帧读出的 RGB 像素读数**（实验观测），**不是本契约规定的任何底色**——
-  轴一边界照旧：契约不点名任何色值，底色取值永远由调用方栏目决定：
-
-  | 变体 | 四角像素 | 判读 |
-  |---|---|---|
-  | 实心底写**根 `style`** | `dfdad4 / fafcfb / 4e4f52 / f9fbfb` | ≈ 底轨基线 → **底丢失、底轨透出** |
-  | 实心底写**根下首个全幅子层** | `01ff81 / 00fe80 / 01fd80 / 01fd80` | ≈ 标志色 → **底存活、满屏盖住底轨** |
-  | 底轨本身（阴性对照） | `e0dbd4 / fbfdfc / 4f5052 / fbfdfd` | 四角始终高亮非黑，对照有效 |
-
-- **阳性对照（关键，排除平凡解）**：「写根」那格的整帧里颗粒**前景元素完整渲出**（标题文字、网格、连线、色块都在）——
-  所以它**不是「颗粒没渲上」，而是「颗粒渲上了、根 `background` 被丢掉」**。缺这一步，两种情况在像素上同解。
-- **复现方式**：造上述两变体 → 同一批走整轨拆分渲染 → `ffmpeg -ss 8.0 -i <out>.mp4 -frames:v 1 -vf "crop=40:40:<x>:<y>,scale=1:1" -f rawvideo -pix_fmt rgb24 - | xxd -p` 读四角。
-- **历史**：本条现象最早由创作侧于 **2026-07-15** 记载（一颗满屏颗粒的根 `background` 丢帧、成片只剩浮空面板），
-  当时未进框架契约，框架正本反而长期要求「写在根上」——2026-07-26 的实验复现并坐实了该记载，本条据此改写。
-- **相关跨仓 change**：`gitruck-cli` / `align-particle-solid-backdrop-contract`（本条的来源）；
-  `gitruck-infra` / `add-html-animate-opaque-fullscreen-cover`（**另一个独立问题**：渲染侧要不要按 `opaque` 位替颗粒兜一层黑底）。
-  ⚠️ 两者**互不依赖**：上表的观测正是在后者**未 apply** 时取得的——即**本条的修法（下沉子层）当场生效，不需要渲染侧任何配合**。
-
-### 铁律 8「重复图元合并」的真机证据锚（2026-07-26）
-
-本条断言的是一条**作者侧规避写法**及其在真渲染中的效果，不断言已知触发轴。证据锚如下：
-
-- **结论**：同一故障样本把 37 条满幅 `<line>` 合为一条 `<path>` 多子路径后，目标画面逐像素不变，横带重复率由 **65%～68% 降至 2%**；规避当场有效，但合并同时改变了图元数、DOM 结构与栅格化路径，故本实验**不能证明是哪一个变量生效**。
-- **实验日期 / 机器**：2026-07-26 · r69（真渲，非本地无头模拟）。
-- **引擎版本口径**：渲染引擎 CLI 与 producer 同版 `0.6.101` · 无头浏览器内核 `131.x`。
-- **二分设计**：以同一颗粒为母本逐项只改一个构建块，每个变体各做一次真渲；每格抽取 168 帧，按等高横带间的重复像素统计复现率。装配路径、分辨率、帧率、底轨与其余颗粒代码保持一致。
-- **范围限定（硬约束）**：下表全部是**同一颗粒内部**的二分结果，**MUST NOT 跨颗粒外推**；它只能说明这些改动在该颗粒内与复现率同向变化，不能推出「元素数少就安全」或任何数字门槛。
-
-  | 同一颗粒内的变体 | 重复率 | 限定读法 |
-  |---|---:|---|
-  | 原件：背景网格为 37 条满幅 `<line>` | **65%～68%**（复跑一致） | 故障基线 |
-  | 37 条 `<line>` 合为一条 `<path>` 多子路径 | **2%** | 本条规避正例；目标画面逐像素不变 |
-  | 整块删除背景网格 | **2%** | 与合并同档；只说明该块在本颗粒内参与复现 |
-  | 删除两个静态术语文本块 | **0%～1%** | 删除任一块负载都退烧；作用域仅限本颗粒，机制未知 |
-  | 删除三行静态标签文本块 | **0%～1%** | 同上 |
-  | 换字体族 / 去斜体 / 关闭 3D 加速 / 改入场位移 / 把文字改为 SVG `<text>` / 给根加变换提示 / 把网格改静态 | **仍为 65%+** | 均无效 |
-  | 增加满屏失效脉冲层 | **14%** | 作者侧强制全幅失效仍不能根治 |
-  | 极简结构（20 个静态 `<div>` + 1 个网格） | **0%** | 空载变体不复现；不得外推为通用预算 |
-
-- **阳性对照（排除平凡解）**：合并版仍完整绘制与原件相同的整张网格，逐像素对拍一致；它不是「把内容删没了所以不重复」。同一颗粒内另有 24 条局部短线在合并版中继续保留，故 24 与 37 也 **MUST NOT** 被写成安全 / 故障分界。
-- **跨颗粒反证（同批全量体检）**：同装配、同引擎、同机完成 **21 颗粒 + 六 beat 同页聚合，共 24 次渲染 / 约 22,000 帧**。这些结果专门限制上表的外推范围：
-
-  | 样本 | 真渲结果 | 可否证的候选轴 |
-  |---|---:|---|
-  | 另一密阵样本：884 条短划、全颗共 921 个绘制图元 | **0.0% 脏帧** | 图元总数、同父同类聚簇 |
-  | 六 beat 同页聚合：约 1,400 个绘制图元 | **0.0% 脏帧** | 同页累积负载 |
-  | 当前修复版样本（回归 / 阴性对照） | **0.0% 脏帧** | 规避在整轨分片路径下仍稳 |
-  | 未修版样本（阳性对照） | **70.3% 脏帧** | 缺陷仍活且可稳定复现 |
-
-  **真实触发轴至今未知**；当前已否证的候选轴 = **图元总数 / 同页累积负载 / 同父同类聚簇**。上表中「921 个图元干净」与「较少图元的阳性对照中招」同时成立，因此数字方向不存在可据此写入契约的安全门槛。
-- **复现方式**：从同一母本生成上述单变量变体 → 走生产同款整轨分片渲染 → 对每格 168 帧计算等高横带间的重复率并抽取高分帧肉眼复核；再以同一口径跑 21 颗全量语料、六 beat 同页聚合、修复版阴性对照与未修版阳性对照。复现件的本地路径与文件名不进入分发契约。
-- **相关 change / 根治状态**：本仓 `add-particle-primitive-merge-law` 收录作者侧规避；渲染管线侧根治**未立项（2026-07-26，本 change 实施会话按非目标不代提；待主理人另行决定）**。根治上线并经真机确认后，按铁律 8 的预案把 MUST 降为 SHOULD。
-
-## 颗粒骨架（中性模板）
-
-```html
-<template id="p">
-<!-- 铁律4:根 MUST 零视觉。这里的 background 恒为 transparent(显式声明,不是省略),实心底一律下沉到下面的 .bgfill 子层 -->
-<div data-composition-id="<id>" data-width="1920" data-height="1080"
-     style="position:absolute;inset:0;background:transparent;overflow:hidden;font-family:'<你的字体·须命中服务端 font_manifest.json>',sans-serif;">
-  <!-- 铁律4①:实心底 MUST 是根下第一个全幅子层。满屏颗粒填你栏目的底色;透明叠加(overlay)颗粒把整行删掉 -->
-  <div class="bgfill" style="position:absolute;inset:0;background:<你的底色>;z-index:0;"></div>
-  <style> [data-composition-id="<id>"] .xxx{ … } </style>   <!-- 样式用属性选择器作用域，防跨颗粒污染 -->
-  <svg viewBox="0 0 1920 1080" preserveAspectRatio="xMidYMid meet" style="position:absolute;inset:0;width:100%;height:100%;">…</svg>
-  <script src="https://lib.baomitu.com/gsap/3.13.0/gsap.min.js"></script>
-  <script>(function(){
-    var ROOT='[data-composition-id="<id>"]';
-    /* 1) 确定性构建静态结构 */
-    /* 2) gsap.set 初始态 */
-    /* 3) var tl = gsap.timeline({paused:true}); … 编排 … */
-    window.__timelines = window.__timelines || {};
-    window.__timelines["<id>"] = tl;
-  })();</script>
-</div>
-</template>
-```
-
-> **骨架里 `.bgfill` 那一行的三个要点**：① 它 MUST 是**根下第一个**子元素（后续前景层自然压在它之上，不必给前景排 z-index）；
-> ② 它 MUST **全幅**（`position:absolute;inset:0`，或等价的 `top/left/width/height` 铺满）——不铺满就不是「实心底」；
-> ③ 类名 `bgfill` 只是**惯例**，其底色写在**行内 style** 上（不靠 `<style>` 里的类规则），故不受「样式作用域」那条专属坑影响；
-> 换名字不违约，但 `gtrk mg lint` 认的是「根下首个全幅子层的 `background`」这个**结构**，不认类名。
-
-缓动可用 CustomEase 精确还原你栏目自己的 cubic-bezier（缺插件时给近似回退）——bezier 数值属于栏目审美，本契约不规定。
-
-## 确定性配方（替代 random）
-
-- 递归结构：固定角度、比例、深度参数 → 完全确定。
-- "噪声感"：`Math.sin(i*0.18 + j*0.2)` 类解析式伪随机。
-- 打散：用 index 派生（如 `i*137.5°` 黄金角），不要 `Math.random()`。
-
-## 验证（交付前必做）
-
-墙钟截图类工具驱动不了 paused 时间线（只看到 t=0），**不能**用来验收。必须真渲染引擎 seek 验证：
-1. 颗粒放进最小 composition（root `index.html` 用 `data-composition-src` 引它）；
-2. 走渲染管线（html_animate_render）渲染；
-3. 抽不同时间点的帧**比对应当不同**（相同=冻结=铁律没守住）。客观自检：根有 `<template>`、`window.__timelines["<id>"]` 已注册且 id 匹配、无 random/Date、tl 总长 ≥ 颗粒时长。
-> ⚠️ 不要用「本地等价 seek 脚本 / Node 无头模拟」替代真引擎渲染——它不经真编译+挂载，测不出 var()-不解析、CDN-内联失败、StaticGuard 这类只在真引擎暴露的问题（实测教训：本地等价测试报 OK，真引擎全黑）。
->
-> ⚠️ **客户端预览对「底色 / 透明度」类问题结构性失明，MUST NOT 用作这类验收的判据**（2026-07-26 增补）。
-> 客户端预览会按 clip 登记的 `opaque` 位**给颗粒根盒强行打底**（`!important`，恒胜过颗粒自身的设计期底色）——
-> 于是无论根 `background` 有没有被丢弃、有没有实心底子层，**预览看到的都是「按登记值应该长的样子」**。
-> 铁律 4 的证据锚正是靠**真渲染出片抽帧**取得的，不是靠预览。预览截图只作对照留档，不入判据。
-
-## 专属坑
-
-- **样式作用域**：颗粒与其他颗粒/根同处一个文档，全局类会撞——用 `[data-composition-id="<id>"] .xxx` 属性选择器作用域。
-- **`<template>` 内的 `<script>` 默认不执行**——引擎把 template 内容克隆进文档后才执行；本地直接开浏览器不会跑，必须经引擎/player。
-- **transform-origin（SVG）**：缩放 `<g>` 用 GSAP `svgOrigin:"x y"`（SVG 用户坐标），别用 CSS transform-origin。
-- **时间线总长 ≥ 坑位时长**：颗粒 tl 总时长 ≥ 落轨 clip 时长（坑位包络），否则 seek 越界（已升格为铁律 7，含终态驻留要求）。
-- **整组同步驱动的重复图元必须合并**：网格、排线、刻度、点阵用单元素表达，SVG 以一条 `<path>` 的多子路径合成；逐元素动画批次豁免。详见 gsap-emit v1 铁律 8。
-- **别用 `requestAnimationFrame`/`setInterval` 驱动画面**——不被 seek，等于冻结。所有视觉变化必须挂在 tl 上。（与「回调与 seek 语义」一节同源：任何**不经 tl** 的自有时钟都不被定帧驱动；而挂在 tl 上的回调是否被触发，则由该节的引擎侧条款保证。`gtrk mg lint` 对本条给**非致命**项 `x-raf-interval`——静态正则分不清「驱动画面」与其它用途，故只提醒不拦。）
+# GSAP-emit 契约 v1 · HTML 动画颗粒的逐帧 seek 渲染合规
+
+> **契约版本**：gsap-emit v1（2026-07-10；2026-07-24 增补铁律 7「占满坑位 + 终态驻留」，主理人硬性规定；同日铁律 6 增补字体注册表命中规则，对齐 gitruck-infra change `align-render-font-contract`；**2026-07-26 增补「回调与 seek 语义」一节**——补此前留白，首次对**渲染引擎侧**提出 MUST 条款，对齐 change `define-seek-suppress-events-contract`；**同日该节核实状态转「已核实（行为层）」**——真渲染引擎（producer `0.6.101`）三帧实测回调可达、结论绑定该引擎版本；
+> **2026-07-26 铁律 4 按真机实测改写**——实心底 MUST 下沉为根下第一个全幅子层、根元素 MUST 保持零视觉、overlay 颗粒 MUST 在根显式写 `background:transparent`，
+> 附证据锚并消歧铁律编号，对齐 change `align-particle-solid-backdrop-contract`；**同日增补铁律 8「重复图元合并」**——把整组同步驱动的重复图元合并成单元素，以规避一类真渲染横带、纵向重复叠印与逐帧闪烁缺陷；触发轴未知，本条只按零成本写法成文、不设数字门槛，对齐 change `add-particle-primitive-merge-law`）。产 HTML 动画颗粒、经同合云渲染管线（html_animate_render）逐帧 seek 合成的 skill/工具，其产物 MUST 满足本契约。
+> **边界**：本契约只约束**机器可判定的管线消费属性**（封装/注册/确定性/自包含/依赖可达/禁 var()/字体名命中注册表）。画面长什么样——颜色、字体取值、构图、节奏——**一律由调用方按其栏目自身规则决定**，本契约不点名任何具体字体/颜色；文中示例取值均为中性占位。
+
+## 原理（为什么不能用 CSS animation）
+
+渲染引擎逐帧渲染时，靠调用每个子合成在 `window.__timelines` 注册的 GSAP 时间线的 `.seek(t)` 把画面定格到第 t 秒。GSAP `paused` 时间线 = 可被外部 seek 的虚拟时钟 → 逐帧正确；纯 CSS `animation-delay` 动画不在 `window.__timelines` 里，引擎 seek 不到 → 画面冻结（实测）。
+
+## 回调与 seek 语义（2026-07-26 增补 · 补此前留白）
+
+> **一句话**：颗粒**可以**用时间线回调（`onUpdate` 等）驱动画面；**保证这些回调在定帧时被触发是渲染引擎侧的义务**，不是颗粒作者的义务。
+> 本节是该主题的**唯一口径来源**——契约引用（`skills/gtrk-style-maker/references/contracts-ref.md`）与消费侧检查（`gtrk mg lint`）的文案都指向这里，不得各自表述。
+
+### 一、GSAP 3.13.0 实测事实（写死在此，免后来者重测）
+
+复现方式：拉铁律⑤指定 CDN 的 `gsap.min.js` 到本地，Node `vm` 里造 `paused` timeline + proxy 对象 + 计数回调，**每种定位方式各新建一条 timeline 单独跑**（回调计数互不串）。
+
+**样本一**——10s、`ease:"none"` 的单条 tween（`{v:0}` → `{v:100}`），分别 seek 到 t=5（中途）与 t=10（末端）：
+
+| 定位方式 | `onUpdate` / `onStart` | `onComplete` | 补间目标属性 |
+|---|---|---|---|
+| `tl.seek(t)`（默认，`suppressEvents` 缺省为 `true`） | **不触发** | **不触发**——连 `seek(10)`（到末端）也不触发 | 已更新（t=5 → `v=50.00`；t=10 → `v=100.00`） |
+| `tl.seek(t, true)` | 不触发 | 不触发 | 已更新 |
+| `tl.seek(t, false)` | 触发 | `seek(10,false)` 触发；`seek(5,false)` 不触发 | 已更新 |
+| `tl.time(t)` / `tl.progress(p)` / `tl.totalTime(t)` | 触发 | 同上（按是否到末端） | 已更新 |
+
+⚠️ **`onComplete` 那两行必须分清**：默认 seek 下它**到末端也不触发**，这才是「被抑制」的证据；而 `false` 模式下 `seek(5,false)` 的 `onComplete` 不触发，只是「补间尚未走完」的正常语义。混为一谈，后来者会拿后者误判成「垫片无效」。
+
+**样本二（含真实 DOM 写入 · 引擎侧条款的直接依据）**——同一 t=1.0 定帧点，补间在 t=1.0 处的目标属性期望值 75.0，`onUpdate` 体内做一次真实 DOM 写入：
+
+| 定位方式（同一 t=1.0 定帧点） | `onUpdate` 触发次数 | 补间目标属性 | 回调内的 DOM 写入 |
+|---|---|---|---|
+| `tl.seek(1.0)`（默认） | **0 次** | 已更新为 **75.0** | **未执行** |
+| `tl.seek(1.0, false)` | 1 次 | 75.0 | 正常 |
+| `tl.time(1.0)` | 1 次 | 75.0 | 正常 |
+| `tl.progress(0.5)` | 1 次 | 75.0 | 正常 |
+
+要害是**「值更新了、回调没跑」**：补间目标对象的属性照常插值，但写在 `onUpdate` 里的 DOM 写入一次都不执行。所以这种翻车**不是黑屏，是画面定在初始态**——本地播放器与客户端预览都完全正常，比黑屏更难发现。
+
+样本二同时给出条款一的**可行性依据**：三种「不抑制」写法（`seek(t,false)` / `time(t)` / `progress(p)`）行为**完全一致**，故对引擎侧的要求**可实现且不挑实现**——引擎爱用哪种用哪种，只要不是裸 `seek(t)`。
+
+### 二、条款
+
+1. **引擎侧（MUST）**：渲染引擎定帧时 **MUST 保证 GSAP 时间线回调可达**——MUST 用 `seek(t, false)` 或 `time(t)` / `progress(p)` / `totalTime(t)`，**MUST NOT 用默认的 `seek(t)`**。违反后果：补间目标属性照常更新、回调内的 DOM 写入不执行 → 画面**定在初始态而非黑屏**，本地播放器与客户端预览均看不出异常。
+2. **颗粒侧（合规声明）**：颗粒**可以**用时间线回调（`onUpdate` / `onStart` / `onComplete` / `onRepeat`）写 DOM / 属性来驱动画面——这是**合规**写法（相机推进、数值读数这类效果用纯属性补间难以表达）。其可达性由条款 1 承担；契约 **MUST NOT** 反过来要求颗粒作者自行保证。
+3. **颗粒侧（不应）**：颗粒**不应**在运行时覆写引擎所调用的 API——重新赋值 `tl.seek`、或把 `window.__timelines[…]` 换成包装对象。两条实测理由：① 覆写会推翻引擎**显式**传入的 `seek(t, true)`（实测：打上垫片后 `seek(5)` 与 `seek(6, true)` 两次调用回调都触发），颗粒无权静默否决引擎的意图；② 垫片只作用于 `seek`，引擎改走 `time()` / `progress()` 时**完全失效**，而作者不会知道。
+   已存在的垫片属**过渡态**：**新颗粒不应再加**。**2026-07-26 更新**——条款 1 的前提已经真引擎核实（见下「三」），垫片赖以存在的「真空期」已结束，故已存在的垫片**可择期清理**（清理是**可做**、不是 MUST 做；删后须重跑 lint 并**重渲复验**）。垫片留着也无害：实测引擎既然本就不抑制回调，垫片对画面结果无影响，只会被 lint 记一条非致命的 `x-engine-api-override`。
+4. **作者侧应知（这不是甩锅）**：作者 MUST 知晓——回调可达性的保证方是**引擎侧**，且该保证当前的核实状态见下「三」（2026-07-26 起为**已核实（行为层）· 绑定引擎 0.6.101**）。`gtrk mg lint` 会对「回调驱动画面且无任何兜底」的颗粒给一条**非致命**提醒，那是**哨兵**（引擎换实现或失守时有人喊一声），**不是**「请作者自行保证 seek 下回调可达」——**核实之后哨兵照留**，因为结论绑死引擎版本，换版即须重测。
+
+### 三、核实状态：**已核实（行为层）· 2026-07-26 · 绑定渲染引擎 producer `0.6.101`**
+
+**把某条引擎行为写成 MUST，MUST NOT 被当作它已被核实**——二者在本节分别成文。本小节记的是**核实到了什么、以及没核实到什么**。
+
+**结论：真渲染引擎在定帧时 `onUpdate` 回调可达，条款 1 的前提成立。** 结论**绑定上述引擎版本**，换版即失效、须重测。
+
+- **核实方式（真引擎，非本地无头模拟）**：造一颗最小颗粒 `seekcb-probe`，**不打任何 seek 垫片**，画面正中的大号数字**只**由一条 tween 的 `onUpdate` 写入（proxy `{v:0}` → `480`，`ease:"none"`，16s），初值静态写死 `CB 000`；同屏并排一组**纯属性补间**对照物（方块横移 + 进度条拉长，均无回调），刻度尺与回调数字**同单位 0..480**，故单帧之内即可比对「应该是多少」与「实际是多少」。该颗粒先过 `gtrk mg lint`（`lint.ok=true`，`opaque=true`，只出 `x-callback-driven` 哨兵、无 `x-engine-api-override`），排除「因不合规才没渲」。走生产同款装配（`CompositionRender` 整轨路径 / 同底轨 `bed.mp4` / 1920×1080 / fps=60 / 15.97s / 958 帧分片 13 chunk）。
+- **实测结果（三帧，肉眼判读整帧 PNG）**：
+
+  | 抽帧时刻 | 回调驱动的数字（onUpdate 唯一驱动） | 纯属性补间对照物 | 期望值 |
+  |---|---|---|---|
+  | t=2s | **CB 060** | 进度条/方块 @ 60 | 060 |
+  | t=8s | **CB 240** | 进度条/方块 @ 240 | 240 |
+  | t=14s | **CB 420** | 进度条/方块 @ 420 | 420 |
+
+  三帧数字**各不相同**、**无一帧停在初值 `CB 000`**，且**逐帧与同单位对照物精确重合**——即回调不仅被触发，还是在**当前帧对应的时间点**上触发的（不是滞后一帧的陈值）。对照物同时移动，排除「整颗没渲/时间线没被定位」这一混淆解释。
+- **证据留档**：三帧整帧 PNG、成片、颗粒与渲染脚本一并留档，落点见本仓 change `define-seek-suppress-events-contract` 的工件（复现件的本地路径与文件名不进入分发契约）。引擎版本取自渲染日志自报的 producer `0.6.101`。
+- **⚠️ 本次核实的边界（MUST NOT 越界引用）**：核实的是**可观测行为**（回调可达），**不是调用形态**。引擎仍是无源码第三方包，本轮**没有**读到定帧调用点，故**无法区分**它走的是 `seek(t,false)` / `time(t)` / `progress(p)`，还是压根不经 GSAP 定位 API 的自有推进方式。条款 1 里那串 API 白名单仍是**应然的实现约束**，只有「回调 MUST 可达」这个**结果**被真机背书。调用形态的核实仍由 gitruck-infra 侧联动 change `link-guarantee-seek-callback-reachability` 承接（读调用点 + 把「纯回调驱动无垫片颗粒渲两帧、像素 MUST 不同」挂进引擎版本变更门禁）。
+- **旁证（本轮之前的间接证据，保留备查）**：gitruck-infra 自家 9 个 music_visualizer 模板 **9/9** 把整块画面挂在单条 tween 的 `onUpdate` 上、且 **0/9** 带任何垫片，走的正是同一渲染内核，而 `gtrk music-visualizer` 是**已上线**能力——若引擎默认抑制回调，这 9 个模板早该渲成静止首帧。本仓 exemplar b06/b07/b08 同理。本轮直接核实**与旁证同向**。
+- **假设失效的后果（哨兵为何 MUST 留）**：结论绑定 `0.6.101`；引擎升版换调用方式 → 全部回调驱动型颗粒（MG 与 music_visualizer 模板）**一起静默冻结**，lint 全绿、退出码 0、无任何告警。故 `gtrk mg lint` 的 `x-callback-driven` 哨兵（条款 4）**MUST NOT 因本次核实而撤**——它防的正是「换版后无人喊一声」。
+
+### 四、连带风险：回调可达 = 逐帧反复触发
+
+条款 1 的另一面：逐帧 scrub 时 `onComplete` / `onStart` / `onRepeat` 会**反复触发**（每帧一次）。故颗粒 **MUST NOT** 把「只跑一次」的逻辑写进回调——累加计数、`push` 进数组、一次性 DOM 插入、抽样。那会把「静默冻结」换成「静默错乱」。
+
+**2026-07-26 起这条从「假设的另一面」变成「已确证的现实风险」**：上「三」已实测该引擎**确实**在逐帧定位时触发回调，故本条不是防患于未然，而是**当下就在生效**的约束。
+
+**推荐写法**：回调做成**幂等**的——每次都从补间状态**重算**整个画面，不依赖上一次的结果（真机与 exemplar 的 `render()` / `apply()` / `paint()` 均如此）。
+
+### 五、优先级
+
+**本节口径优先于任何栏目指南的招式建议。** 栏目指南若与本节冲突，以本节为准。（当前二者同向：栏目指南推荐的 `onUpdate` 驱动写法在本节下**合规**，作坊侧**无需修订**——本节不向作坊侧派发任何待办。此条照写不误，它防的是将来的分歧。）
+
+## 八条铁律（违反任一条 → 整片渲染失败 / 颗粒冻结 / 全黑 / 坑位内突兀消失 / 画面被切成横带、内容纵向重复叠印并逐帧闪烁）
+
+1. **`<template>` 包裹根元素**：`<template><div data-composition-id="<id>" data-width="1920" data-height="1080">…</div></template>`。编译器取的是 `<template>` 内容；裸 `<div>` 会被判 "empty or could not be parsed" 整片失败。（1920×1080 为**当前引擎版本约束**，分辨率参数化预留——升版时以本契约新版为准。）
+2. **GSAP `paused` 时间线 + 注册**：`var tl = gsap.timeline({paused:true}); … window.__timelines = window.__timelines || {}; window.__timelines["<id>"] = tl;`。`<id>` 必须等于根的 `data-composition-id`。
+3. **确定性**：禁用 `Math.random` / `Date.now` / 无参 `new Date()`（过不了引擎 StaticGuard）。要"随机感"用固定种子/解析式/递归生成（见「确定性配方」）。
+4. **自包含 + 实心底下沉子层 + 透明度显式声明**（**2026-07-26 按真机实测改写**；原文「全屏颗粒给根设明确 `background`；透明颗粒根不设 background」**已作废**，见下方证据锚）：颗粒不依赖外部文件（除脚本 CDN）。底色的**取值**由调用方按其栏目规则决定，本契约只管**摆在哪个元素上**。
+   - **① 实心底 MUST 下沉为根下第一个全幅子层**（`position:absolute;inset:0` 或等价的 `top/left/width/height` 铺满），**MUST NOT 写在根元素的 `style` 上**。理由是实测事实：**根元素的绘制属性在子合成挂载时被丢弃**，写在根上的实心底**一个像素都不落地**——成片里表现为「浮空面板」（前景照常渲出、底没了、底轨透出来），本地播放器与客户端预览都看不出。
+   - **② 根元素 MUST 保持零视觉**：根 `style` MUST NOT 出现任何会绘制像素的属性（实心 `background` / `border` / `box-shadow` / `outline` …）。写了不报错，但**不生效**，只会误导后来者以为底已经有了。
+   - **③ 透明与否 MUST 显式声明**：`background` 声明 MUST 至少出现一处——**满屏（不透明）颗粒**写在 ① 的全幅子层上；**透明叠加（overlay）颗粒** MUST 在**根**显式写 `background:transparent`，MUST NOT 靠「不写」表达透明。根上的 `transparent` 虽然同样不落成像素（它本就不绘制），但它是**给人和机器读的意图声明**——缺了它，作者与 `gtrk mg lint` 都无从区分「想透明」与「忘了想」。
+   - **④ 消费侧同源**：`gtrk mg lint` 的 `opaque` 推导面 = 「根 `style` ∪ 根下首个全幅子层 `style`」，与本条 ①③ 同源；两处皆无 `background` 声明才报 `4-bg-explicit`，满屏颗粒把实心底写在根上另报非致命 `4-bg-on-root`。
+5. **脚本用渲染机可达的 CDN（编译期内联）**：`<script src="https://lib.baomitu.com/gsap/3.13.0/gsap.min.js"></script>` 或由渲染管线 vendor 本地。⚠️ jsdelivr 在渲染服务器不稳（实测 compile 期 `fetch failed` → GSAP 未加载 → 整片全黑）。编译器**只内联 http(s) CDN、不内联相对本地路径**（写 `src="gsap.min.js"` 运行时 404）。
+6. **颜色/字体用字面值，禁 CSS `var()` 自定义变量；字体名 MUST 命中服务端注册字体表**：编译器/挂载不可靠地解析 var()（字体映射把 `var(--font-body)` 当字面字体名；颜色 var() 不应用 → 整片全黑，实测）。直接写字面值（如 `#RRGGBB` / `'某字体名'`）；SVG 属性里同样禁 var()。栏目级换色/换主题 = **生成期**替换字面值（查调用方自己的词表/token 注入），不是运行时变量。**字体名规则（2026-07-24 增补）**：font-family 的每个具名家族 MUST 逐字符命中渲染服务端注册字体表（gitruck-infra 仓 `utils/assets/text/classic_template/font_manifest.json`，中英别名等价），并 SHOULD 以 `sans-serif`/`serif` 通用族收尾兜底；表外名字渲染不失败但**字形不保证**（服务端 fail-open 系统回退，2026-07-24 真机实锤：错名导致目标字形被回退成另一款系统字形）。具体选哪款仍由调用方栏目规则决定，本契约不点名。
+7. **占满坑位 + 终态驻留（2026-07-24 主理人硬性规定；2026-07-26 增补无限循环定性）**：颗粒时间线总长 MUST ≥ 它在成片中的**坑位时长**（落轨 clip 的实际时长，通常 = 派单槽位包络 `track_ed − track_st`，**不是** `duration_hint`）；动画主叙事播完后，颗粒 MUST 以「**定格保持**」或「**有限次循环**」驻留到坑位末尾。**禁用无限循环 `repeat:-1`（2026-07-26 增补，补此前留白）**：无限循环让时间线总长为 `Infinity`，本条「总长 ≥ 坑位」就**变得不可验证**（机器与人都无从判断它是否真按坑位算过），且掩盖「作者根本没算坑位」这件事。循环次数 MUST **按坑位算死**——`repeat = ceil((坑位时长 − 循环起点) / 单圈时长) − 1`，宁可多算一两圈（末尾被 clip 裁掉无害），也不许写 `-1` 蒙混——坑位内任意时刻（含最后一帧）核心内容必须可见。**禁止**「整体渐隐到空 / 全局退场 / 清空画面」类收尾：渐隐会与剪辑层转场冲突，淡出与否由剪辑/装配层决定，不在颗粒内做。局部元素可按叙事退场（黯淡/让位），但画面在坑位内不得归零；**定格不动是完全合法的终态**（不必为凑动作密度在尾段硬加动画）。违反表现 = 观感上「动画一过完整个颗粒突兀消失」（2026-07-24 真机实测，事故工程见本仓 change `fix-mg-clip-fill-slot`）。
+8. **重复图元合并（2026-07-26 增补 · 规避条款，根治在渲染侧）**：同一批**重复图元**——同色、同 `stroke` / `fill`、**整组同步驱动**（只有组级动画或完全静态）的网格、排线、刻度、点阵——**MUST 合并成单个元素**（SVG 用一条 `<path>` 的多子路径 `M…H…V…`；同色分档时可按档合成若干条），**MUST NOT** 用「每条线 / 每个格子一个 `<element>`」的批量构建，无论它写成字面标签还是由 `createElementNS` 循环生成。合并前后画面**逐像素相同**，故本条不涉任何视觉取值。
+   - **豁免**：需要**逐元素动画**（stagger / 逐条画入 / 逐个变色）的批次不在本条范围内——元素身份是该批动画所必需的。此类批次若同时是满幅大面积绘制，MUST 以真渲染出片抽帧验收；这是保守兜底，**不是**「满幅即危险」的风险判据，反向的「不满幅即安全」同样不成立。
+   - **违反表现**：画幅被切成等高横带、相邻带内容互相纵向重复叠印（同一元素在 `y` 与 `y±带高` 各画一次，或被顶部裁半）并逐帧闪烁；该表现与动画逻辑无关，同帧里零动画的静态元素也会重复。DOM 元素数与 `getBoundingClientRect` 均正常，本地播放器与客户端预览看不出。
+   - **这是规避，不是根治**：缺陷出在渲染侧已由真机行为确证——颗粒的 DOM 元素数与布局值正常，不是颗粒写错。机制层面**推断**为渲染侧按等高带做局部栅格刷新时失效区域算错，**属推断、未经渲染侧确认**；**真实触发轴至今未知**，「图元总数」「同页累积负载」「同父同类聚簇」均已被跨颗粒真渲反例否证。本条 MUST NOT 被读成「图元少 / 负载低就安全」。
+   - **根治登记**：根治方 = 渲染管线侧；当前状态 = **未立项（2026-07-26；决策角色 = 本 change 实施者，按 proposal 的跨仓授权边界不代提；是否立项仍待主理人另行授权）**。
+   - **根治后处置预案**：待渲染管线侧根治上线且经真机确认缺陷不再复现后，本条由 **MUST 降为 SHOULD**，并保留「本条曾于 2026-07-26、本证据锚所载引擎版本口径下作为规避所必需」的历史记录。
+
+> **⚠️ 铁律编号的唯一定义在本文件。** 本契约的**铁律 7 = 「占满坑位 + 终态驻留」**，这是框架侧对该条号的**唯一**定义。
+> 创作侧（栏目 skill / 作坊）的模板与 references **MUST NOT 另立同号铁律**——引用请写「gsap-emit v1 铁律 7」并指回本文件，
+> 自己的栏目约束请用**栏目注记**或另起独立编号空间。
+> **已知撞号（2026-07-26 记录，收口中）**：某栏目 references 曾把「根元素零视觉」编为其「铁律 7」、同一条在其模板里又编为「铁律③」——
+> 该约束现已**升为本契约的铁律 4**（见上），栏目侧的两个同名条号 SHALL 改为引用铁律 4，不再另立。
+
+### 铁律 4「实心底下沉子层」的真机证据锚（2026-07-26）
+
+本条断言的是**渲染引擎行为**（「根元素的绘制属性在挂载时被丢弃」），故按契约库要求附可追溯证据锚：
+
+- **结论**：根 `style` 的 `background` **不落成像素**；同一颗粒把同一底色改写到根下首个全幅子层则**满屏落地并盖住底轨**。
+- **实验日期 / 机器**：2026-07-26 · 真机（生产同款渲染主机；真渲，非本地无头模拟）。
+- **引擎版本口径**：渲染引擎 CLI 与 producer 同版 `0.6.101` · 无头浏览器内核 `131.x`。
+- **设计**：同颗粒母本造两个变体，**唯一变量 = 实心底摆在根 `style` 还是根下首个全幅子层**，其余逐字节相同；
+  底色临时取高饱和标志色以便与「根合成兜底黑」区分；底轨用一段有明显画面、非黑的真人镜头；抽同一时间点 `t=8.0s` 的帧，
+  取四角 `crop=40:40` 于 `(20,20) (1860,20) (20,1020) (1860,1020)` 后 `scale=1:1` 读像素。
+- **观测**（整轨拆分渲染路径，两格同素材同引擎同批）。
+  ⚠️ 下表的六位数字是**抽帧读出的 RGB 像素读数**（实验观测），**不是本契约规定的任何底色**——
+  轴一边界照旧：契约不点名任何色值，底色取值永远由调用方栏目决定：
+
+  | 变体 | 四角像素 | 判读 |
+  |---|---|---|
+  | 实心底写**根 `style`** | `dfdad4 / fafcfb / 4e4f52 / f9fbfb` | ≈ 底轨基线 → **底丢失、底轨透出** |
+  | 实心底写**根下首个全幅子层** | `01ff81 / 00fe80 / 01fd80 / 01fd80` | ≈ 标志色 → **底存活、满屏盖住底轨** |
+  | 底轨本身（阴性对照） | `e0dbd4 / fbfdfc / 4f5052 / fbfdfd` | 四角始终高亮非黑，对照有效 |
+
+- **阳性对照（关键，排除平凡解）**：「写根」那格的整帧里颗粒**前景元素完整渲出**（标题文字、网格、连线、色块都在）——
+  所以它**不是「颗粒没渲上」，而是「颗粒渲上了、根 `background` 被丢掉」**。缺这一步，两种情况在像素上同解。
+- **复现方式**：造上述两变体 → 同一批走整轨拆分渲染 → 按上「设计」段的抽帧与四角取样口径（`t=8.0s` 单帧 / `crop=40:40` / `scale=1:1`）取样，
+  再以 RGB24 原始字节读出四角的十六进制像素值。取样工具与复现件的本地路径不进入分发契约（同铁律 8 证据锚口径）。
+- **历史**：本条现象最早由创作侧于 **2026-07-15** 记载（一颗满屏颗粒的根 `background` 丢帧、成片只剩浮空面板），
+  当时未进框架契约，框架正本反而长期要求「写在根上」——2026-07-26 的实验复现并坐实了该记载，本条据此改写。
+- **相关跨仓 change**：`gitruck-cli` / `align-particle-solid-backdrop-contract`（本条的来源）；
+  `gitruck-infra` / `add-html-animate-opaque-fullscreen-cover`（**另一个独立问题**：渲染侧要不要按 `opaque` 位替颗粒兜一层黑底）。
+  ⚠️ 两者**互不依赖**：上表的观测正是在后者**未 apply** 时取得的——即**本条的修法（下沉子层）当场生效，不需要渲染侧任何配合**。
+
+### 铁律 8「重复图元合并」的真机证据锚（2026-07-26）
+
+本条断言的是一条**作者侧规避写法**及其在真渲染中的效果，不断言已知触发轴。证据锚如下：
+
+- **结论**：同一故障样本把 37 条满幅 `<line>` 合为一条 `<path>` 多子路径后，目标画面逐像素不变，横带重复率由 **65%～68% 降至 2%**；规避当场有效，但合并同时改变了图元数、DOM 结构与栅格化路径，故本实验**不能证明是哪一个变量生效**。
+- **实验日期 / 机器**：2026-07-26 · 真机（生产同款渲染主机；真渲，非本地无头模拟）。
+- **引擎版本口径**：渲染引擎 CLI 与 producer 同版 `0.6.101` · 无头浏览器内核 `131.x`。
+- **二分设计**：以同一颗粒为母本逐项只改一个构建块，每个变体各做一次真渲；每格抽取 168 帧，按等高横带间的重复像素统计复现率。装配路径、分辨率、帧率、底轨与其余颗粒代码保持一致。
+- **范围限定（硬约束）**：下表全部是**同一颗粒内部**的二分结果，**MUST NOT 跨颗粒外推**；它只能说明这些改动在该颗粒内与复现率同向变化，不能推出「元素数少就安全」或任何数字门槛。
+
+  | 同一颗粒内的变体 | 重复率 | 限定读法 |
+  |---|---:|---|
+  | 原件：背景网格为 37 条满幅 `<line>` | **65%～68%**（复跑一致） | 故障基线 |
+  | 37 条 `<line>` 合为一条 `<path>` 多子路径 | **2%** | 本条规避正例；目标画面逐像素不变 |
+  | 整块删除背景网格 | **2%** | 与合并同档；只说明该块在本颗粒内参与复现 |
+  | 删除两个静态术语文本块 | **0%～1%** | 删除任一块负载都退烧；作用域仅限本颗粒，机制未知 |
+  | 删除三行静态标签文本块 | **0%～1%** | 同上 |
+  | 换字体族 / 去斜体 / 关闭 3D 加速 / 改入场位移 / 把文字改为 SVG `<text>` / 给根加变换提示 / 把网格改静态 | **仍为 65%+** | 均无效 |
+  | 增加满屏失效脉冲层 | **14%** | 作者侧强制全幅失效仍不能根治 |
+  | 极简结构（20 个静态 `<div>` + 1 个网格） | **0%** | 空载变体不复现；不得外推为通用预算 |
+
+- **阳性对照（排除平凡解）**：合并版仍完整绘制与原件相同的整张网格，逐像素对拍一致；它不是「把内容删没了所以不重复」。同一颗粒内另有 24 条局部短线在合并版中继续保留，故 24 与 37 也 **MUST NOT** 被写成安全 / 故障分界。
+- **跨颗粒反证（同批全量体检）**：同装配、同引擎、同机完成 **21 颗粒 + 六 beat 同页聚合，共 24 次渲染 / 约 22,000 帧**。这些结果专门限制上表的外推范围：
+
+  | 样本 | 真渲结果 | 可否证的候选轴 |
+  |---|---:|---|
+  | 另一密阵样本：884 条短划、全颗共 921 个绘制图元 | **0.0% 脏帧** | 图元总数、同父同类聚簇 |
+  | 六 beat 同页聚合：约 1,400 个绘制图元 | **0.0% 脏帧** | 同页累积负载 |
+  | 当前修复版样本（回归 / 阴性对照） | **0.0% 脏帧** | 规避在整轨分片路径下仍稳 |
+  | 未修版样本（阳性对照） | **70.3% 脏帧** | 缺陷仍活且可稳定复现 |
+
+  **真实触发轴至今未知**；当前已否证的候选轴 = **图元总数 / 同页累积负载 / 同父同类聚簇**。上表中「921 个图元干净」与「较少图元的阳性对照中招」同时成立，因此数字方向不存在可据此写入契约的安全门槛。
+- **复现方式**：从同一母本生成上述单变量变体 → 走生产同款整轨分片渲染 → 对每格 168 帧计算等高横带间的重复率并抽取高分帧肉眼复核；再以同一口径跑 21 颗全量语料、六 beat 同页聚合、修复版阴性对照与未修版阳性对照。复现件的本地路径与文件名不进入分发契约。
+- **相关 change / 根治状态**：本仓 `add-particle-primitive-merge-law` 收录作者侧规避；渲染管线侧根治**未立项（2026-07-26，本 change 实施会话按非目标不代提；待主理人另行决定）**。根治上线并经真机确认后，按铁律 8 的预案把 MUST 降为 SHOULD。
+
+## 渲染成本：真卷积滤镜（2026-07-30 增补）
+
+> **本节不是铁律**（铁律仍是**八条**，编号空间不动）。铁律管的是**正确性失效**（渲不出 / 冻结 / 全黑 / 突兀消失 / 横带叠印）；
+> 本节管的是**每帧成本**——命中本节的颗粒**画面是对的，只是贵**。故本节用 MUST NOT / SHOULD 约束写法，
+> 但**不进「违反即废片」的铁律清单**。
+
+### 射程（本节说的「真卷积滤镜」精确指这三类）
+
+| 进射程（真卷积） | 射程外（本节不管、消费侧也不报） |
+|---|---|
+| CSS `filter` / `-webkit-filter` / `backdrop-filter` 的值里含 `blur(<非零>)` 或 `drop-shadow(… <非零模糊半径> …)` | `filter: blur(0)` / `blur(0px)`、`drop-shadow(x y)`（模糊半径缺省 = 0）、`filter: none` |
+| SVG `<feGaussianBlur stdDeviation="<非零>">`、`<feDropShadow>`（含经 `filter="url(#id)"` 引用者） | **任何 `box-shadow`** |
+| 上述两类出现在 `<style>` 规则、元素内联 `style`、或时间线补间属性对象里的任一位置 | `opacity` / `transform` / `mix-blend-mode` / `border-radius` |
+
+- **`box-shadow` 整族豁免、不报警**——包括 `box-shadow: 0 0 0 Npx <color>` 这类零卷积的纯 spread 描边/光圈写法
+  （脉冲扩散的标准句式，现网大量在用），**也包括 blur-radius > 0 的写法**。后者**确实是卷积**，
+  这一点如实记录在此；但把 `box-shadow` 纳入射程需要正确解析它的多值语法（`inset`、多组逗号、颜色可前可后、长度 2~4 个），
+  误报率高而现网收益为零，故整族排除。⚠️ 这是**已定的射程边界**，**不是**「待纳入 / 下版收编」；
+  要改变它，先证明存在受益的现网用法。
+- **与铁律 4② 的语义分工（两条正交，不冲突）**：铁律 4② 把 `box-shadow` 列进「根元素 MUST 保持零视觉」的**绘制属性清单**，
+  管的是「绘制属性摆在根上不生效」；**本节管的是每帧卷积成本**。同一个属性名出现在两处不是口径打架——
+  一处论**位置**，一处论**成本**。
+
+### 条文
+
+- **成本模型**：真卷积滤镜的每帧代价 ∝ **被覆盖面积 × 模糊半径 × 帧数**。逐帧渲染要把每一帧都算一遍，
+  所以它与「本地播放器里看着很流畅」毫无关系。
+- **MUST NOT 用时间线补间驱动 `filter` 属性**（也包括补间驱动被引用 SVG 滤镜的 `stdDeviation`）：
+  滤镜值一变，上一帧的卷积结果**当场失效**，缓存彻底失灵，这是本节里最贵的形态。
+  同一叙事动作请改用 `opacity` / `transform`（`scale` / 位移）表达；确需滤镜就做成**静态两态切换**，别让它随时间连续变。
+- **整幅静态滤镜 SHOULD 缩小被滤元素的几何覆盖面积**：把滤镜收到它真正需要的那块矩形上。
+  面积一项**同时**压掉「卷积」与「整幅逐帧合成」两笔成本，故它是首选改法。
+- **MUST NOT 把「预烘成图」写成一律解法**：整幅静态滤镜的每帧成本由**两项**构成——① 卷积本身；② 整幅逐帧合成。
+  预烘只消得掉 ①，② **照样每帧付**，故预烘的收益**存在上限、必有残差**；而且把活颗粒烤死会牺牲「全程可拖可调」这一产品前提。
+  预烘是**次选**，不是缺省答案。
+- **确要预烘时 MUST 用 RGBA PNG**，**MUST NOT** 用 JPEG 或任何无 alpha 格式：透明叠加颗粒的 alpha 是成片合成的**必需通道**，
+  丢了 alpha 的图在成片里会塌成一块不透明色块（前景盖住底轨）。
+- **判断权在作者**：去不去某个滤镜属**视觉取值**，本契约不规定视觉取值——本节只给成本机制与改法。
+
+### 证据锚（只收有出处的数；每条带测量日期 + 语料标注）
+
+- **测量日期**：2026-07-30。**版本口径**：渲染引擎 CLI 与 producer 同版 `0.7.82` · 无头浏览器内核 `152.x`。
+  测量在真机（生产同款渲染主机）取得，非本地无头模拟。
+- **现网既有栏目语料（21 颗生产颗粒）**：去掉真卷积滤镜的可省墙钟 **0~3.1%**——即**本节对现有语料近似零收益**，
+  它立在这里是**前置门**（防止大批带滤镜的新语料进渲染管线后整批返工），**不是**提速手段。
+- **单次误用的止损量级（同一颗粒内对照）**：**1.3~3.3×**。
+- **滤镜重语料（技法颗粒，单颗 646 帧）**：**7.0×**（339.6s → 48.3s）。
+  ⚠️ 该数**只对该语料成立**，MUST NOT 外推成通用提速承诺。
+- **消费侧沉默不等于便宜**：`gtrk mg lint` 的三个成本项（`c-filter-animated` / `c-filter-static-fullbleed` /
+  `c-filter-indeterminate`）是**形态提示**，**当期一律非致命、不拦铺轨**；没报**不代表**这颗渲得快——
+  真判据永远是**真渲染出片计时**。
+- **致命性的升级触发器（登记在此，免得日后凭印象改）**：把 `c-filter-animated` 提为**致命**
+  SHALL 另走一个独立 change，且 SHALL 同时满足两项前提——① 「滤镜重语料批量进渲染管线」那条路线**已立项**；
+  ② 提级前对现网生产语料**全量复扫且零命中**（复扫在生产颗粒上命中 > 0 即 MUST NOT 提级）。
+  触发一次评估的时机 = 上述路线立项 **或** 本节首次改版，以先到者为准。
+  **MUST NOT** 以「规范就该严」为由径直提级，也 **MUST NOT** 把致命性做成可现场翻转的运行期开关。
+
+### 根治登记
+
+- **① 这是降本规范、不是缺陷规避**：命中项的画面本身是对的，逐帧也正确，只是每帧贵。
+- **② 成本的根在渲染管线侧**：逐帧路径走**软件光栅**（无图形硬件加速），卷积按面积×半径吃 CPU。
+- **③ 根治状态 = 明确不立项（2026-07-30）**：改走图形硬件加速路径会破坏「逐帧确定性」与「产出端版本对齐」这两项前提
+  （异构机器还会破坏分片与单次的产物等价），渲染侧调研已把它列为**已排除项**。故本节以作者侧写法收敛，不等渲染侧。
+- **④ 根治后的处置预案**：若渲染侧将来换掉光栅路径并经真机复测确认成本塌陷，本节由 MUST NOT/SHOULD **降为提示**，
+  并保留「本节曾于 2026-07-30、本证据锚所载版本口径下作为降本规范所必需」的历史记录。
+
+## 颗粒骨架（中性模板）
+
+```html
+<template id="p">
+<!-- 铁律4:根 MUST 零视觉。这里的 background 恒为 transparent(显式声明,不是省略),实心底一律下沉到下面的 .bgfill 子层 -->
+<div data-composition-id="<id>" data-width="1920" data-height="1080"
+     style="position:absolute;inset:0;background:transparent;overflow:hidden;font-family:'<你的字体·须命中服务端 font_manifest.json>',sans-serif;">
+  <!-- 铁律4①:实心底 MUST 是根下第一个全幅子层。满屏颗粒填你栏目的底色;透明叠加(overlay)颗粒把整行删掉 -->
+  <div class="bgfill" style="position:absolute;inset:0;background:<你的底色>;z-index:0;"></div>
+  <style> [data-composition-id="<id>"] .xxx{ … } </style>   <!-- 样式用属性选择器作用域，防跨颗粒污染 -->
+  <svg viewBox="0 0 1920 1080" preserveAspectRatio="xMidYMid meet" style="position:absolute;inset:0;width:100%;height:100%;">…</svg>
+  <script src="https://lib.baomitu.com/gsap/3.13.0/gsap.min.js"></script>
+  <script>(function(){
+    var ROOT='[data-composition-id="<id>"]';
+    /* 1) 确定性构建静态结构 */
+    /* 2) gsap.set 初始态 */
+    /* 3) var tl = gsap.timeline({paused:true}); … 编排 … */
+    window.__timelines = window.__timelines || {};
+    window.__timelines["<id>"] = tl;
+  })();</script>
+</div>
+</template>
+```
+
+> **骨架里 `.bgfill` 那一行的三个要点**：① 它 MUST 是**根下第一个**子元素（后续前景层自然压在它之上，不必给前景排 z-index）；
+> ② 它 MUST **全幅**（`position:absolute;inset:0`，或等价的 `top/left/width/height` 铺满）——不铺满就不是「实心底」；
+> ③ 类名 `bgfill` 只是**惯例**，其底色写在**行内 style** 上（不靠 `<style>` 里的类规则），故不受「样式作用域」那条专属坑影响；
+> 换名字不违约，但 `gtrk mg lint` 认的是「根下首个全幅子层的 `background`」这个**结构**，不认类名。
+
+缓动可用 CustomEase 精确还原你栏目自己的 cubic-bezier（缺插件时给近似回退）——bezier 数值属于栏目审美，本契约不规定。
+
+## 确定性配方（替代 random）
+
+- 递归结构：固定角度、比例、深度参数 → 完全确定。
+- "噪声感"：`Math.sin(i*0.18 + j*0.2)` 类解析式伪随机。
+- 打散：用 index 派生（如 `i*137.5°` 黄金角），不要 `Math.random()`。
+
+## 验证（交付前必做）
+
+墙钟截图类工具驱动不了 paused 时间线（只看到 t=0），**不能**用来验收。必须真渲染引擎 seek 验证：
+1. 颗粒放进最小 composition（root `index.html` 用 `data-composition-src` 引它）；
+2. 走渲染管线（html_animate_render）渲染；
+3. 抽不同时间点的帧**比对应当不同**（相同=冻结=铁律没守住）。客观自检：根有 `<template>`、`window.__timelines["<id>"]` 已注册且 id 匹配、无 random/Date、tl 总长 ≥ 颗粒时长。
+> ⚠️ 不要用「本地等价 seek 脚本 / Node 无头模拟」替代真引擎渲染——它不经真编译+挂载，测不出 var()-不解析、CDN-内联失败、StaticGuard 这类只在真引擎暴露的问题（实测教训：本地等价测试报 OK，真引擎全黑）。
+>
+> ⚠️ **客户端预览对「底色 / 透明度」类问题结构性失明，MUST NOT 用作这类验收的判据**（2026-07-26 增补）。
+> 客户端预览会按 clip 登记的 `opaque` 位**给颗粒根盒强行打底**（`!important`，恒胜过颗粒自身的设计期底色）——
+> 于是无论根 `background` 有没有被丢弃、有没有实心底子层，**预览看到的都是「按登记值应该长的样子」**。
+> 铁律 4 的证据锚正是靠**真渲染出片抽帧**取得的，不是靠预览。预览截图只作对照留档，不入判据。
+
+## 专属坑
+
+- **样式作用域**：颗粒与其他颗粒/根同处一个文档，全局类会撞——用 `[data-composition-id="<id>"] .xxx` 属性选择器作用域。
+- **`<template>` 内的 `<script>` 默认不执行**——引擎把 template 内容克隆进文档后才执行；本地直接开浏览器不会跑，必须经引擎/player。
+- **transform-origin（SVG）**：缩放 `<g>` 用 GSAP `svgOrigin:"x y"`（SVG 用户坐标），别用 CSS transform-origin。
+- **时间线总长 ≥ 坑位时长**：颗粒 tl 总时长 ≥ 落轨 clip 时长（坑位包络），否则 seek 越界（已升格为铁律 7，含终态驻留要求）。
+- **整组同步驱动的重复图元必须合并**：网格、排线、刻度、点阵用单元素表达，SVG 以一条 `<path>` 的多子路径合成；逐元素动画批次豁免。详见 gsap-emit v1 铁律 8。
+- **真卷积滤镜别用补间驱动、整幅静态滤镜先缩面积**：`blur()` / `drop-shadow()` / `feGaussianBlur` 按「面积 × 半径 × 帧数」吃每帧墙钟；预烘是次选且必须 RGBA PNG。`box-shadow` 整族不在射程内。详见本文件「渲染成本：真卷积滤镜」一节。
+- **别用 `requestAnimationFrame`/`setInterval` 驱动画面**——不被 seek，等于冻结。所有视觉变化必须挂在 tl 上。（与「回调与 seek 语义」一节同源：任何**不经 tl** 的自有时钟都不被定帧驱动；而挂在 tl 上的回调是否被触发，则由该节的引擎侧条款保证。`gtrk mg lint` 对本条给**非致命**项 `x-raf-interval`——静态正则分不清「驱动画面」与其它用途，故只提醒不拦。）