@gitruck/cli 1.3.4 → 1.3.6

package/assets/composite-kit/kit.js

@@ -0,0 +1,246 @@
+/* 合成颗粒工具箱 composite-kit@1（html@1 引擎）——`gtrk composite build` 构建时内联进每颗颗粒，颗粒自包含、不外链。
+ * 随 @gitruck/cli 分发（assets/composite-kit/）；改行为即升版本号（颗粒 <meta name="generator"> 与 CP.VERSION 记着它）。
+ *
+ * 场景脚本只写一件事：`CP.render = (t) => { ... }`（t = 局部秒）。其余由这里负责：
+ * - 宿主协议：hello → meta；init → 帧率 / 锚点 / 图层 / 字幕；apply(frame) → 画这一帧并回报槽位几何；lint → 排版自检；
+ * - 分层：舞台缺省属 back，`data-layer="front"` 的子树属 front（visibility 继承）；
+ * - 槽位几何：`[data-slot]` 的包围盒 + data-z / data-fit / data-shape / data-radius / data-filter / data-crop（上右下左）；
+ * - 装饰跟随：`data-for="<槽位>"` 的元素与槽位同框（data-pad 外扩），用于边框、阴影、角标；
+ * - 字幕：接管字幕后由颗粒自己排（`CP.caption`），文字来自 init.texts；
+ * - 逐句换画面与版式切换：`at` / `mix` / `seq` / `place`；
+ * - 排版自检 `lint`：下层画面的 front 描边压上层画面、front 线条穿过画面、画面越出舞台。
+ * 纯函数：同一帧号永远画出同一画面；不用 Date / Math.random / requestAnimationFrame / setInterval。
+ */
+(() => {
+  "use strict";
+  const META = JSON.parse(document.querySelector("script[data-gtrk-composite]").textContent);
+  const W = META.stage.width, H = META.stage.height;
+  const stage = document.getElementById("stage");
+  let FPS = (META.resolved && META.resolved.video_rate) || 60;
+  let ANCHORS = (META.resolved && META.resolved.anchors_f) || {};
+  let LAYER = "all";
+  let TEXTS = {};
+
+  const clamp = (x, a = 0, b = 1) => Math.min(b, Math.max(a, x));
+  const lerp = (a, b, p) => a + (b - a) * p;
+  const ease = {
+    out: (x) => 1 - Math.pow(1 - x, 3),
+    inOut: (x) => (x < 0.5 ? 4 * x * x * x : 1 - Math.pow(-2 * x + 2, 3) / 2),
+    back: (x) => { const c = 1.4; return 1 + (c + 1) * Math.pow(x - 1, 3) + c * Math.pow(x - 1, 2); },
+    lin: (x) => x,
+  };
+  const prog = (t, t0, dur, e = ease.out) => e(clamp((t - t0) / Math.max(dur, 1e-6)));
+  /** 窗口内出现：t0 前 0，淡入 fi 秒到 1，t1 起淡出 fo 秒到 0。 */
+  const span = (t, t0, t1, fi = 0.5, fo = 0.4) => Math.min(prog(t, t0, fi), 1 - prog(t, t1, fo, ease.inOut));
+  const $ = (id) => document.getElementById(id);
+  const A = (key) => {
+    if (!(key in ANCHORS)) throw new Error("锚点「" + key + "」未解析");
+    return ANCHORS[key] / FPS;
+  };
+
+  function box(el, x, y, w, h) {
+    if (typeof el === "string") el = $(el);
+    el.style.left = x + "px"; el.style.top = y + "px"; el.style.width = w + "px"; el.style.height = h + "px";
+    return el;
+  }
+  /** 透明度 + 位移 / 缩放（不旋转——槽位与其装饰不得旋转）。 */
+  function look(el, o = 1, dx = 0, dy = 0, s = 1) {
+    if (typeof el === "string") el = $(el);
+    el.style.opacity = String(clamp(o));
+    el.style.transform = dx || dy || s !== 1 ? "translate(" + dx + "px," + dy + "px) scale(" + s + ")" : "";
+    return el;
+  }
+  /** 槽位与跟随它的装饰一起定框；o 同时作用于两者。 */
+  function slot(id, x, y, w, h, o = 1) {
+    const el = document.querySelector('[data-slot="' + id + '"]');
+    box(el, x, y, w, h); el.style.opacity = String(clamp(o));
+    for (const d of document.querySelectorAll('[data-for="' + id + '"]')) {
+      const p = Number(d.dataset.pad || 0);
+      box(d, x - p, y - p, w + 2 * p, h + 2 * p); d.style.opacity = String(clamp(o));
+    }
+  }
+  /** 槽位按矩形 [x, y, w, h] 定框（slot 的数组写法）。 */
+  const at = (id, r, o = 1) => slot(id, r[0], r[1], r[2], r[3], o);
+  /** 两个矩形之间插值（版式切换：单画 → 并排）。 */
+  const mix = (a, b, p) => a.map((v, i) => lerp(v, b[i], p));
+  /**
+   * 逐句换画面的透明度：在 a 前 fade 秒淡入、a 时刻已全显；到 b（下一张已全显）之后直接关掉。
+   * 同一位置叠放的几张画面按 data-z 递增排，下一张盖住上一张再关上一张——任一时刻最多两张在解码。
+   */
+  const seq = (t, a, b = null, fade = 0.3) => prog(t, a - fade, fade) * (b == null || t < b + 0.02 ? 1 : 0);
+  /** 把元素放到 (x, y) 并给透明度（标签、角标跟随画面用）。 */
+  function place(el, x, y, o = 1) {
+    if (typeof el === "string") el = $(el);
+    el.style.left = x + "px"; el.style.top = y + "px"; el.style.opacity = String(clamp(o));
+    return el;
+  }
+  /** 逐字显现（p ∈ [0,1]）：未显现的字留占位但透明，排版不跳。 */
+  function typeOn(el, text, p) {
+    if (typeof el === "string") el = $(el);
+    const n = Math.round(clamp(p) * text.length);
+    const key = text + "|" + n;
+    if (el.dataset.typed === key) return;
+    el.dataset.typed = key;
+    el.innerHTML = "";
+    const a = document.createElement("span"); a.textContent = text.slice(0, n);
+    const b = document.createElement("span"); b.textContent = text.slice(n); b.style.opacity = "0";
+    el.append(a, b);
+  }
+  /** 字幕：取文本输入 slot 在第 f 帧的那一条；highlight 里的词加强调色。 */
+  function cueAt(slotId, t) {
+    const f = Math.floor(t * FPS + 1e-6);
+    const list = TEXTS[slotId] || [];
+    for (const c of list) if (f >= c.f0 && f < c.f1) return c;
+    return null;
+  }
+  /** 显现：淡入 + 上浮（p ∈ [0,1]）。 */
+  const reveal = (el, p, dy = 26) => look(el, p, 0, dy * (1 - p));
+  /** 从左往右擦出。 */
+  function wipe(el, p) {
+    if (typeof el === "string") el = $(el);
+    el.style.clipPath = "inset(-20% " + (100 - clamp(p) * 100).toFixed(2) + "% -20% 0)";
+    el.style.opacity = p > 0 ? "1" : "0";
+  }
+  /** SVG 路径描边动画。 */
+  function draw(el, p) {
+    if (typeof el === "string") el = $(el);
+    const L = el.getTotalLength();
+    el.style.strokeDasharray = String(L);
+    el.style.strokeDashoffset = String(L * (1 - clamp(p)));
+  }
+  /** 字幕；hide = [[t0, t1], …] 时段内不显示（屏上排版已经写着同一句话时用）。 */
+  function caption(el, slotId, t, highlight = [], hide = []) {
+    if (typeof el === "string") el = $(el);
+    if (hide.some(([a, b]) => t >= a && t < b)) { el.style.opacity = "0"; return null; }
+    const c = cueAt(slotId, t);
+    const text = c ? c.text : "";
+    const key = text + "|" + highlight.join(",");
+    if (el.dataset.cue !== key) {
+      el.dataset.cue = key;
+      el.innerHTML = "";
+      let rest = text;
+      while (rest) {
+        let hit = null, at = -1;
+        for (const w of highlight) {
+          const i = rest.indexOf(w);
+          if (i >= 0 && (at < 0 || i < at)) { at = i; hit = w; }
+        }
+        if (!hit) { el.append(document.createTextNode(rest)); break; }
+        if (at > 0) el.append(document.createTextNode(rest.slice(0, at)));
+        const b = document.createElement("b"); b.textContent = hit; el.append(b);
+        rest = rest.slice(at + hit.length);
+      }
+    }
+    const age = c ? t - c.f0 / FPS : 0;
+    el.style.opacity = c ? String(prog(age, 0, 0.12)) : "0";
+    return c;
+  }
+
+  function applyLayer() {
+    stage.style.visibility = LAYER === "front" ? "hidden" : "visible";
+    for (const el of stage.querySelectorAll("[data-layer]")) {
+      el.style.visibility = LAYER === "all" || el.dataset.layer === LAYER ? "visible" : "hidden";
+    }
+  }
+
+  function measure() {
+    const s = stage.getBoundingClientRect(), k = s.width / W;
+    const out = [];
+    for (const el of stage.querySelectorAll("[data-slot]")) {
+      const r = el.getBoundingClientRect();
+      const opacity = parseFloat(getComputedStyle(el).opacity);
+      const crop = (el.dataset.crop || "0,0,0,0").split(",").map(Number);
+      out.push({
+        id: el.dataset.slot, z: Number(el.dataset.z || 0),
+        x: (r.left - s.left) / k, y: (r.top - s.top) / k, w: r.width / k, h: r.height / k,
+        opacity, visible: opacity > 0.001 && r.width > 0.5 && r.height > 0.5,
+        shape: el.dataset.shape || "rect", radius: Number(el.dataset.radius || 0),
+        fit: el.dataset.fit || "cover", filter: el.dataset.filter || "",
+        crop: crop.length === 4 && crop.every((c) => c >= 0 && c < 1) ? crop : [0, 0, 0, 0],
+      });
+    }
+    return out.sort((a, b) => a.z - b.z);
+  }
+
+  /**
+   * 排版自检（只给出片台 / 构建工具用，宿主协议不依赖它）。查三类：
+   * 1. 两张可见画面重叠，而下面那张有 front 层描边 —— 宿主先画全部画面、再画 front 镜像，
+   *    下面那张的边框会压在上面那张画面上（同框交替淡入时两框重合，不算）；
+   * 2. front 层的线条（path / line / polyline，按已画出的长度取点）穿过某张可见画面；
+   * 3. 画面越出舞台（铺满舞台的底图除外）。
+   */
+  function lint() {
+    const s = stage.getBoundingClientRect(), k = s.width / W;
+    const op = (el) => { let o = 1; for (let e = el; e && e !== stage; e = e.parentElement) o *= parseFloat(getComputedStyle(e).opacity); return o; };
+    // 铺满舞台的画面是底图，压在它上面的任何东西都是有意叠加，不算穿模
+    const slots = measure().filter((g) => g.visible && !(g.x <= 1 && g.y <= 1 && g.x + g.w >= W - 1 && g.y + g.h >= H - 1));
+    const same = (a, b) => ["x", "y", "w", "h"].every((q) => Math.abs(a[q] - b[q]) < 2);
+    const meet = (a, b) => Math.min(a.x + a.w, b.x + b.w) - Math.max(a.x, b.x) > 2 && Math.min(a.y + a.h, b.y + b.h) - Math.max(a.y, b.y) > 2;
+    const deco = (id) => [...stage.querySelectorAll('[data-for="' + id + '"][data-layer="front"]')].some((d) => op(d) > 0.01);
+    const issues = [];
+    for (const g of measure().filter((g) => g.visible)) {
+      if (g.x < -1 || g.y < -1 || g.x + g.w > W + 1 || g.y + g.h > H + 1) {
+        const full = g.x <= 1 && g.y <= 1 && g.x + g.w >= W - 1 && g.y + g.h >= H - 1;
+        if (!full) issues.push({ kind: "slot-out-of-stage", slot: g.id });
+      }
+    }
+    for (let i = 0; i < slots.length; i++) {
+      for (let j = i + 1; j < slots.length; j++) {
+        const a = slots[i], b = slots[j];
+        if (!meet(a, b) || same(a, b)) continue;
+        if (deco(a.id)) issues.push({ kind: "border-over-slot", lower: a.id, upper: b.id });
+        else if (a.z === b.z && deco(b.id)) issues.push({ kind: "same-z-overlap", a: a.id, b: b.id });
+      }
+    }
+    const inside = (g, x, y) => {
+      if (g.shape === "circle") { const dx = (x - g.x - g.w / 2) / (g.w / 2), dy = (y - g.y - g.h / 2) / (g.h / 2); return dx * dx + dy * dy < 0.96; }
+      return x > g.x + 3 && x < g.x + g.w - 3 && y > g.y + 3 && y < g.y + g.h - 3;
+    };
+    for (const p of stage.querySelectorAll('[data-layer="front"] path, [data-layer="front"] line, [data-layer="front"] polyline')) {
+      if (op(p) < 0.01 || !p.getTotalLength) continue;
+      const L = p.getTotalLength();
+      const cs = getComputedStyle(p);
+      const drawn = cs.strokeDasharray && cs.strokeDasharray !== "none" ? L - (parseFloat(cs.strokeDashoffset) || 0) : L;
+      const m = p.getScreenCTM();
+      const hit = new Set();
+      for (let d = 0; d <= drawn; d += 6) {
+        const q = new DOMPoint(p.getPointAtLength(d).x, p.getPointAtLength(d).y).matrixTransform(m);
+        const x = (q.x - s.left) / k, y = (q.y - s.top) / k;
+        for (const g of slots) if (!hit.has(g.id) && inside(g, x, y)) hit.add(g.id);
+      }
+      for (const id of hit) issues.push({ kind: "stroke-through-slot", stroke: p.id || p.tagName, slot: id });
+    }
+    return issues;
+  }
+
+  function fitStage() { stage.style.transform = "scale(" + innerWidth / W + ")"; }
+  addEventListener("resize", fitStage); fitStage();
+
+  const CP = (window.CP = {
+    VERSION: "composite-kit@1",
+    META, W, H, $, A, has: (k) => k in ANCHORS, clamp, lerp, ease, prog, span, box, look, slot, at, mix, seq, place, typeOn, cueAt, caption,
+    reveal, wipe, draw, cues: (slotId) => TEXTS[slotId] || [], fps: () => FPS,
+    render: () => {},
+    /** init 之后调用一次（字幕等输入已就位）：按输入建一次性的 DOM。必须幂等。 */
+    setup: () => {},
+  });
+
+  addEventListener("message", (ev) => {
+    const m = ev.data;
+    if (!m || m.ch !== "gtrk-composite") return;
+    const reply = (x) => parent.postMessage(Object.assign({ ch: "gtrk-composite" }, x), "*");
+    try {
+      if (m.type === "hello") reply({ type: "meta", meta: META });
+      else if (m.type === "init") {
+        FPS = m.fps || FPS; ANCHORS = m.anchors || ANCHORS; LAYER = m.layer || "all"; TEXTS = m.texts || {};
+        CP.setup(); applyLayer(); reply({ type: "ready", layer: LAYER });
+      } else if (m.type === "apply") {
+        CP.render(m.frame / FPS);
+        reply({ type: "frame", seq: m.seq, frame: m.frame, slots: measure(), layer: LAYER });
+      } else if (m.type === "lint") {
+        // 回包类型不能也叫 lint：颗粒作为顶层页面跑（gtrk composite lint）时回包会回到自己的监听里，同名就会无限往返
+        reply({ type: "lint-result", seq: m.seq, issues: lint() });
+      }
+    } catch (e) { reply({ type: "error", seq: m.seq, message: String((e && e.message) || e) }); }
+  });
+})();

package/assets/composite-kit/stage.html

@@ -0,0 +1,282 @@
+<!doctype html>
+<html lang="zh">
+<head>
+<meta charset="utf-8">
+<title>合成颗粒出片台</title>
+<style>
+  html, body { margin: 0; width: 1920px; height: 1080px; overflow: hidden; background: #000; }
+  .layer { position: absolute; left: 0; top: 0; width: 1920px; height: 1080px; border: 0; }
+</style>
+</head>
+<body>
+<iframe id="back" class="layer" title="back"></iframe>
+<canvas id="slots" class="layer" width="1920" height="1080"></canvas>
+<iframe id="front" class="layer" title="front"></iframe>
+<script>
+/* 合成颗粒出片台（composite-kit@1；`gtrk composite lint --stills` 与 `gtrk composite bake` 共用）：与客户端预览同一套规则——
+ * 两层图形 iframe（back / front）夹一块槽位画布。颗粒走宿主协议（init / apply → frame）。
+ *
+ * 槽位取帧（与客户端 `composite-slot-frames.ts` 的 `resolveSlotSource` 同口径）：
+ *   ref      = 片段在时间线该时刻的画面（之前首帧、之后末帧），源时刻 = clip_st + (T − track_st) × speed；
+ *   ref-lane = 按 lane_clip_id 找轨，空档定格前一段末帧，窗口前无片段取后一段首帧；
+ *   own      = 入点 + (f − starts_at_f) 帧。
+ * 取到的源时刻按「时间戳区间覆盖该时刻的那一帧」取帧（与客户端 VideoCache 同规则）：
+ *   - 给了中间文件（`segs`：素材 → [{url, off, ed, pts, tag, eof}]）时，按中间文件实测的帧时间戳表找覆盖帧、定位到帧中点
+ *     （不假设首帧时间戳为 0，也不靠帧率推算——可变帧率同样成立）；画完读回中间文件底部的帧号条，核对确是那一帧
+ *     （`seeked` 之后新帧未必已可画：满载时会画出上一帧或空帧），不对就等、必要时重新定位，始终不对则报错；
+ *   - 没给时直接定位原素材（lint 静帧）。
+ * 绘制：先把视频帧 1:1 拷进一张画布，再从画布缩放画进槽位——与客户端同一种绘制源（客户端画的是 VideoCache 的 RGB 画布）。
+ * 每个槽位一个 <video>（同源取帧不共用解码，见客户端 R15）；图片素材用 <img>。
+ *
+ * 用法：stageInit({ fps, entries, materials, images?, segs?, tracks }) → renderAt(时间线秒)。全部经 file:// 读本地文件。
+ * `window.SETTLE`：画完后等多少毫秒（缺省 60，lint 静帧用）；烘焙置 -1（截帧由 beginFrame / 截图本身推进合成器）。 */
+let FPS = 60, entries = [], matUrl = new Map(), imageIds = new Set(), segsOf = new Map(), byClip = new Map();
+const back = document.getElementById("back"), front = document.getElementById("front");
+const canvas = document.getElementById("slots"), ctx = canvas.getContext("2d");
+
+window.stageInit = (data) => {
+  FPS = data.fps; entries = data.entries;
+  matUrl = new Map(Object.entries(data.materials));
+  imageIds = new Set(data.images || []);
+  segsOf = new Map(Object.entries(data.segs || {}));
+  byClip = new Map();
+  for (const t of data.tracks) {
+    const clips = t.clips.filter((c) => c.material).sort((a, b) => a.track_st - b.track_st);
+    for (const c of clips) byClip.set(c.clip_id, { clip: c, clips });
+  }
+  return true;
+};
+
+let current = null;
+const waiters = new Map();
+addEventListener("message", (ev) => {
+  const m = ev.data;
+  if (!m || m.ch !== "gtrk-composite") return;
+  const layer = ev.source === back.contentWindow ? "back" : ev.source === front.contentWindow ? "front" : null;
+  if (!layer) return;
+  if (m.type === "error") { console.error("[composite]", layer, m.message); window.__scriptErrors = (window.__scriptErrors || []).concat(m.message); }
+  const key = layer + ":" + (m.type === "frame" ? "frame:" + m.seq : m.type);
+  const w = waiters.get(key);
+  if (w) { waiters.delete(key); w(m); }
+});
+const waitFor = (key, ms = 15000) => new Promise((res, rej) => {
+  waiters.set(key, res);
+  setTimeout(() => { if (waiters.delete(key)) rej(new Error("超时：" + key)); }, ms);
+});
+const load = (frame, src) => new Promise((res) => { frame.onload = () => res(); frame.src = src; });
+async function mount(entry) {
+  if (current && current.entry.id === entry.id) return current.ready;
+  const ready = (async () => {
+    await Promise.all([load(back, entry.url), load(front, entry.url)]);
+    for (const [frame, layer] of [[back, "back"], [front, "front"]]) {
+      const p = waitFor(layer + ":ready");
+      frame.contentWindow.postMessage({ ch: "gtrk-composite", type: "init", layer, fps: FPS, anchors: entry.anchors_f, texts: entry.texts }, "*");
+      await p;
+    }
+  })();
+  current = { entry, ready };
+  return ready;
+}
+
+const pool = new Map();
+function videoFor(key, url) {
+  let v = pool.get(key);
+  if (!v || v.dataset.url !== url) {
+    v = document.createElement("video");
+    v.muted = true; v.preload = "auto"; v.dataset.url = url; v.src = url;
+    pool.set(key, v);
+  }
+  return v;
+}
+const images = new Map();
+function imageFor(url) {
+  let p = images.get(url);
+  if (!p) {
+    p = new Promise((res) => { const i = new Image(); i.onload = () => res(i); i.onerror = () => res(null); i.src = url; });
+    images.set(url, p);
+  }
+  return p;
+}
+const once = (el, ev) => new Promise((res) => el.addEventListener(ev, res, { once: true }));
+async function seek(v, sec, force = false) {
+  if (v.readyState < 1) await once(v, "loadedmetadata");
+  const target = Math.min(Math.max(sec, 0), Math.max(v.duration - 0.001, 0));
+  // 强制重定位：先挪到同一帧内略早的位置再回来（目标是帧中点，±2 毫秒仍在该帧内），逼解码器重出这一帧
+  if (force) { const d = once(v, "seeked"); v.currentTime = Math.max(target - 0.002, 0); await d; }
+  if (force || Math.abs(v.currentTime - target) > 1e-4 || v.readyState < 2) {
+    const done = once(v, "seeked");
+    v.currentTime = target;
+    await done;
+  }
+  if (v.readyState < 2) await once(v, "loadeddata");
+  return v;
+}
+
+/** 有序帧时间戳表里「≤ t 的最后一帧」的下标（二分）。 */
+function coverIndex(pts, t) {
+  let lo = 0, hi = pts.length - 1;
+  if (t < pts[0]) return 0;
+  while (lo < hi) { const mid = (lo + hi + 1) >> 1; if (pts[mid] <= t + 1e-6) lo = mid; else hi = mid - 1; }
+  return lo;
+}
+/** 源时刻 → { url, at（定位目标）, srcFrame（该帧对应的源时刻，供核对）}。 */
+function locate(materialId, sec) {
+  const segs = segsOf.get(materialId);
+  if (segs) {
+    // eof：中间文件转到了素材结尾，更晚的源时刻（片段出点超出素材长度）取它的末帧
+    const s = segs.find((x) => sec >= x.off - 1e-6 && (sec < x.ed || x.eof)) || null;
+    if (s) {
+      const local = s.pts[0] + (sec - s.off);
+      const i = coverIndex(s.pts, local);
+      const next = i + 1 < s.pts.length ? s.pts[i + 1] : s.pts[i] + (i > 0 ? s.pts[i] - s.pts[i - 1] : 1 / FPS);
+      return { url: s.url, at: (s.pts[i] + next) / 2, srcFrame: s.off + (s.pts[i] - s.pts[0]), viaSeg: true, idx: i, tag: s.tag || 0 };
+    }
+  }
+  return { url: matUrl.get(materialId), at: sec, srcFrame: sec, viaSeg: false, idx: -1, tag: 0 };
+}
+
+const speedOf = (c) => (typeof c.speed === "number" && c.speed > 0 ? c.speed : 1);
+const clipSrc = (c, T) => c.clip_st + (T - c.track_st) * speedOf(c);
+const lastFrameT = (c) => c.track_ed - 1 / FPS;
+function sourceFor(b, T, f) {
+  if (b.kind === "ref") {
+    const hit = byClip.get(b.clip_id); if (!hit) return null;
+    const c = hit.clip;
+    const tt = Math.min(Math.max(T, c.track_st), lastFrameT(c));
+    // slip_ms：源时钟上整体前后挪取帧（add-composite-slot-user-overrides）；超过素材末尾由 locate 的 eof 段取末帧
+    return { material: c.material, sec: Math.max(0, clipSrc(c, tt) + (b.slip_ms || 0) / 1000) };
+  }
+  if (b.kind === "ref-lane") {
+    const hit = byClip.get(b.lane_clip_id); if (!hit) return null;
+    const act = hit.clips.find((c) => T >= c.track_st && T < c.track_ed);
+    if (act) return { material: act.material, sec: clipSrc(act, T) };
+    const prev = hit.clips.filter((c) => c.track_ed <= T).pop();
+    if (prev) return { material: prev.material, sec: clipSrc(prev, lastFrameT(prev)) };
+    const next = hit.clips.find((c) => c.track_st > T);
+    return next ? { material: next.material, sec: next.clip_st } : null;
+  }
+  if (b.kind === "own") {
+    const k = Math.min(Math.max(f - b.starts_at_f, 0), b.dur_f - 1);
+    return { material: b.material, sec: b.src_in_ms / 1000 + k / FPS };
+  }
+  return null;
+}
+/**
+ * 用户覆盖套到颗粒回报的几何上（add-composite-slot-user-overrides，与客户端 `applySlotOverrides` 逐值相同）：
+ * box = 以槽位中心缩放 scale_pm/1000 倍、中心位移舞台宽高的 dx_pm / dy_pm 千分比，圆角同乘缩放；
+ * crop = 替换颗粒的 data-crop（[上, 右, 下, 左] 比例）。
+ */
+function applySlotOverrides(g, b) {
+  let out = g;
+  if (b.box) {
+    const s = b.box.scale_pm / 1000, w = g.w * s, h = g.h * s;
+    const cx = g.x + g.w / 2 + (b.box.dx_pm / 1000) * 1920, cy = g.y + g.h / 2 + (b.box.dy_pm / 1000) * 1080;
+    out = { ...out, x: cx - w / 2, y: cy - h / 2, w, h, radius: (g.radius || 0) * s };
+  }
+  if (b.crop) out = { ...out, crop: [b.crop.t_pm / 1000, b.crop.r_pm / 1000, b.crop.b_pm / 1000, b.crop.l_pm / 1000] };
+  return out;
+}
+/** fit / framing / crop 合成的绘制矩形（与客户端 `slotDrawRect` 逐值相同；源或槽位尺寸为 0 时返回 null，不画）。 */
+function drawRect(g, sw0, sh0, fit, framing) {
+  const [top, right, bottom, left] = g.crop;
+  const sx = sw0 * left, sy = sh0 * top, sw = sw0 * (1 - left - right), sh = sh0 * (1 - top - bottom);
+  if (!(sw > 0 && sh > 0 && g.w > 0 && g.h > 0)) return null;
+  const base = fit === "contain" ? Math.min(g.w / sw, g.h / sh) : Math.max(g.w / sw, g.h / sh);
+  const scale = base * (Math.max((framing && framing.scale_pm) || 1000, 1000) / 1000);
+  const dw = sw * scale, dh = sh * scale;
+  const cx = g.x + g.w / 2 + ((framing && framing.x_pm) || 0) / 1000 * g.w;
+  const cy = g.y + g.h / 2 + ((framing && framing.y_pm) || 0) / 1000 * g.h;
+  return [sx, sy, sw, sh, cx - dw / 2, cy - dh / 2, dw, dh];
+}
+function shape(g) {
+  ctx.beginPath();
+  if (g.shape === "circle") ctx.ellipse(g.x + g.w / 2, g.y + g.h / 2, g.w / 2, g.h / 2, 0, 0, Math.PI * 2);
+  else if (g.shape === "roundrect" && g.radius > 0) ctx.roundRect(g.x, g.y, g.w, g.h, Math.min(g.radius, g.w / 2, g.h / 2));
+  else ctx.rect(g.x, g.y, g.w, g.h);
+}
+/** 视频帧 1:1 拷进的中转画布（每个 <video> 一张，复用）。 */
+const relay = new Map();
+function relayOf(v) {
+  let k = relay.get(v);
+  if (!k) { k = document.createElement("canvas"); relay.set(v, k); }
+  if (k.width !== v.videoWidth || k.height !== v.videoHeight) { k.width = v.videoWidth; k.height = v.videoHeight; }
+  const c = k.getContext("2d", { willReadFrequently: true });
+  c.clearRect(0, 0, k.width, k.height);
+  c.drawImage(v, 0, 0);
+  return k;
+}
+/** 读中转画布底部帧号条：16 位黑白块（块宽 floor(宽/32)*2，与 CLI 的 drawbox 同式）；没画上（透明）返回 -1。 */
+function readTag(k, tag) {
+  const bw = Math.floor(k.width / 32) * 2;
+  const row = k.getContext("2d", { willReadFrequently: true }).getImageData(0, k.height - Math.ceil(tag / 2), k.width, 1).data;
+  let n = 0;
+  for (let b = 0; b < 16; b++) {
+    const o = (b * bw + (bw >> 1)) * 4;
+    if (row[o + 3] < 255) return -1;
+    if (row[o] > 128) n |= 1 << b;
+  }
+  return n;
+}
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/** 画到中转画布并核对帧号；不对就等新帧到位，每 40 次重新定位一次，约 3 秒仍不对即报错（该段会被重试）。 */
+async function drawVerified(v, at) {
+  for (let i = 0; ; i++) {
+    const k = relayOf(v);
+    const got = readTag(k, at.tag);
+    if (got === (at.idx & 0xffff)) return { k, waits: i };
+    if (i >= 400) throw new Error("取帧校验失败：要第 " + at.idx + " 帧，画出的是 " + got + "（" + at.url + "）");
+    if (i % 40 === 39) await seek(v, at.at, true);
+    else await sleep(i < 20 ? 2 : 8);
+  }
+}
+
+let seq = 0;
+window.renderAt = async (T) => {
+  const F = Math.round(T * FPS);
+  const entry = entries.find((p) => F >= p.window_f[0] && F < p.window_f[1]);
+  if (!entry) throw new Error("该时刻没有合成颗粒：" + T);
+  await mount(entry);
+  const f = Math.min(Math.max(F - entry.window_f[0], 0), entry.window_f[1] - entry.window_f[0] - 1);
+  const s = ++seq;
+  const pf = waitFor("front:frame:" + s), pb = waitFor("back:frame:" + s);
+  for (const fr of [back, front]) fr.contentWindow.postMessage({ ch: "gtrk-composite", type: "apply", seq: s, frame: f }, "*");
+  const [geo] = await Promise.all([pf, pb]);
+  const Tf = (entry.window_f[0] + f) / FPS;
+  const used = [];
+  const jobs = geo.slots.filter((g) => g.visible).map(async (g) => {
+    const b = entry.bindings[g.id];
+    if (!b || b.kind === "text") return null;
+    const src = sourceFor(b, Tf, f);
+    if (!src || !matUrl.has(src.material)) return null;
+    if (imageIds.has(src.material)) {
+      const img = await imageFor(matUrl.get(src.material));
+      used.push({ slot: g.id, material: src.material, sec: 0 });
+      return img ? { g, b, img } : null;
+    }
+    const at = locate(src.material, src.sec);
+    const v = await seek(videoFor(g.id + "|" + at.url, at.url), at.at);
+    const ver = at.tag ? await drawVerified(v, at) : { k: relayOf(v), waits: 0 };
+    used.push({ slot: g.id, material: src.material, sec: src.sec, srcFrame: at.srcFrame, viaSeg: at.viaSeg, waits: ver.waits });
+    return { g, b, v, k: ver.k, tag: at.tag };
+  });
+  const ready = (await Promise.all(jobs)).filter(Boolean);
+  ctx.clearRect(0, 0, 1920, 1080);
+  for (const { g: g0, b, v, k, tag, img } of ready) {
+    const g = applySlotOverrides(g0, b);
+    // 中间文件底部的帧号条不进画面：源高度按去掉条带算
+    const r = img ? drawRect(g, img.naturalWidth, img.naturalHeight, b.fit || g.fit, b.framing) : drawRect(g, v.videoWidth, v.videoHeight - (tag || 0), b.fit || g.fit, b.framing);
+    if (!r) continue;
+    ctx.save();
+    shape(g); ctx.clip();
+    ctx.globalAlpha = g.opacity;
+    if (g.filter) ctx.filter = g.filter;
+    ctx.drawImage(img || k, ...r);
+    ctx.restore();
+  }
+  const settle = window.SETTLE ?? 60;
+  if (settle > 0) await new Promise((r) => setTimeout(r, settle));
+  return { id: entry.id, f, used };
+};
+</script>
+</body>
+</html>

package/assets/readme/wordmark.svg

@@ -1,6 +1,6 @@
-<svg xmlns="http://www.w3.org/2000/svg" width="560" height="170" viewBox="0 0 560 170" role="img" aria-labelledby="title">
-  <title id="title">gtrk CLI</title>
-  <text x="84" y="128" fill="#f43b48" font-family="Segoe UI, Helvetica, Arial, sans-serif" font-size="150" font-weight="750" letter-spacing="-9">gtrk</text>
-  <path d="M403 63v61" stroke="#f43b48" stroke-opacity=".3" stroke-width="2"/>
-  <text x="425" y="106" fill="#888888" font-family="Consolas, monospace" font-size="28" letter-spacing="3">CLI</text>
-</svg>
+<svg xmlns="http://www.w3.org/2000/svg" width="560" height="170" viewBox="0 0 560 170" role="img" aria-labelledby="title">
+  <title id="title">gtrk CLI</title>
+  <text x="84" y="128" fill="#f43b48" font-family="Segoe UI, Helvetica, Arial, sans-serif" font-size="150" font-weight="750" letter-spacing="-9">gtrk</text>
+  <path d="M403 63v61" stroke="#f43b48" stroke-opacity=".3" stroke-width="2"/>
+  <text x="425" y="106" fill="#888888" font-family="Consolas, monospace" font-size="28" letter-spacing="3">CLI</text>
+</svg>

package/contracts/README.md

@@ -1,16 +1,16 @@
-# 框架契约库（handoff contracts）
-
-同合云管线的 handoff 契约**正本**，随 `@gitruck/cli` npm 包分发。创作 skill 以「契约名 + 版本」引用（如 `gsap-emit v1`）；`handoff-contracts.json` 是「handoff 类型 → 契约」映射表，消费方查表、不硬编码。
-
-## 收录双轴边界（handoff-contract-library spec，扩项须走 change 过审）
-
-- **轴一（管线性，审美零预设）**：契约只约束**机器可判定的管线消费属性**（封装/注册/确定性/依赖可达/产物格式）。**不得**规定颜色、字体、构图、红点数量等任何视觉取值或栏目词表词条；凡涉视觉取值处一律参数化/中性占位。「全片最多一个红点」这类审美铁律属栏目 skill 侧，**不入库**。
-- **轴二（脱敏）**：只收**自有管线**的合规契约——渲染引擎合规、`.gtrk` 契约、派单格式（封闭列举）。外部供应商/外部平台适配内容（AI 视频平台差异、文生图平台参数等）**永不收录**，那属于用户自己的 skill。
-
-## 现有契约
-
-| 契约 | 版本 | 适用 handoff | 文档 |
-|---|---|---|---|
-| gsap-emit（HTML 动画颗粒逐帧 seek 合规） | v1 | MG（去品牌化前 RRV_MG，消费方查表前归一） | [gsap-emit-v1.md](gsap-emit-v1.md) |
-
-维护者证据附录：[`gsap-emit-v1-evidence.md`](gsap-emit-v1-evidence.md)。该文件不属于 agent 执行时的必读契约。
+# 框架契约库（handoff contracts）
+
+同合云管线的 handoff 契约**正本**，随 `@gitruck/cli` npm 包分发。创作 skill 以「契约名 + 版本」引用（如 `gsap-emit v1`）；`handoff-contracts.json` 是「handoff 类型 → 契约」映射表，消费方查表、不硬编码。
+
+## 收录双轴边界（handoff-contract-library spec，扩项须走 change 过审）
+
+- **轴一（管线性，审美零预设）**：契约只约束**机器可判定的管线消费属性**（封装/注册/确定性/依赖可达/产物格式）。**不得**规定颜色、字体、构图、红点数量等任何视觉取值或栏目词表词条；凡涉视觉取值处一律参数化/中性占位。「全片最多一个红点」这类审美铁律属栏目 skill 侧，**不入库**。
+- **轴二（脱敏）**：只收**自有管线**的合规契约——渲染引擎合规、`.gtrk` 契约、派单格式（封闭列举）。外部供应商/外部平台适配内容（AI 视频平台差异、文生图平台参数等）**永不收录**，那属于用户自己的 skill。
+
+## 现有契约
+
+| 契约 | 版本 | 适用 handoff | 文档 |
+|---|---|---|---|
+| gsap-emit（HTML 动画颗粒逐帧 seek 合规） | v1 | MG（去品牌化前 RRV_MG，消费方查表前归一） | [gsap-emit-v1.md](gsap-emit-v1.md) |
+
+维护者证据附录：[`gsap-emit-v1-evidence.md`](gsap-emit-v1-evidence.md)。该文件不属于 agent 执行时的必读契约。