@gitruck/cli 1.3.4 → 1.3.5

package/assets/composite-kit/stage.html

@@ -0,0 +1,265 @@
+<!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));
+    return { material: c.material, sec: clipSrc(c, tt) };
+  }
+  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;
+}
+/** 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, b, v, k, tag, img } of ready) {
+    // 中间文件底部的帧号条不进画面：源高度按去掉条带算
+    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 执行时的必读契约。