@biunow/agent-biuart 0.0.0-stage → 0.1.1

package/engine/clips/y4_storytime.js

@@ -0,0 +1,194 @@
+// 片段 · 故事型角色（y4，storytime）：一个角色（AI 生成的帧库）在小房间里对镜头讲，姿势快切（0.1s）后定住，笑点靠反应特写和插入镜头。
+// 镜头不慢推、不手持漂、角色不呼吸：定住就是定住，变化靠快切、跳近（反应特写砸进来）和插入镜头。
+// data.character（必填）：帧库——render.py 里写一个目录（文件名去扩展名 = 姿势名），或 {frames: {rest, talk, point, shrug, type, stiff, react, back, <姿势>_open: 路径}}。
+//                 代码画的小人（'neutral' / 'bun' / 'author' / 造型对象）已停用：不给帧库就启动失败。
+//                   至少要有 rest 或 talk；缺的姿势退到 talk → rest；<姿势>_open 是张嘴帧（说话时一拍二换）；react 是反应特写，back 是插入镜头前景的后脑勺。
+//                   帧图要透明底、角色脚底在图片底边中间，画出来高 ≈ 3.15 个头半径。没有 back 帧时插入镜头不画前景后脑勺。
+// cues：point | title（角色说一句：at 这一帧气泡弹出、开始张嘴；嘴按 text 的字数说 ≈6.5 字/秒；data.pose 指定姿势 talk/point/shrug/type）
+//         气泡里写什么：有 sub 就写 sub（≤12 字的短句最好），没有才写 text——口播原文交给管线的字幕，气泡别和字幕重复一遍
+//       highlight（「？」「！」弹出＋摊手担心：data.mark 默认「？」）
+//       react（反应镜头：at 这一帧跳到大特写，贴 react 帧（没有就退到 talk / rest）＋汗滴，一言不发；dur 默认到下一个 cue）
+//       insert（插入镜头：at 这一帧切到桌上那台电脑的屏幕特写——sub = 角色打的那一行（打字、发送），之后 AI 的回复像代码墙一样越滚越快，
+//               text = 砸出来的大字（如「3000行」），在 data.hit（绝对秒，默认 at+1.3，没有 sub 时 at+0.4）砸出、屏幕一震；
+//               data.count + data.unit 让右上角计数器在砸出那一刻停在这个数；dur 默认到下一个 cue）
+// 房间里有桌上的电脑（插入镜头切进去的就是它的屏幕）、马克杯、墙上的书架和绿植，右边不再是空墙。
+// 没有口播包络时，口型由字数和时间合成（一拍二，0/1/2 三张嘴）；有包络就把 window.VO_ENV 交给管线（TOON.mouth 自动读）。
+// safe：气泡、插入镜头的大字排在 top..H−bottom 之间。alpha：不画房间，角色和气泡照画（气泡本来就是白底黑字）；插入镜头只画显示器和后脑勺，四周透明。
+// spec.theme（全片色板 ctx.pal）：墙 bg、地面和桌子是 bg 往 ink / sub 调的明暗，书、杯子、绿植 accent / accent2，气泡 surface 底 ink 字，
+//   屏幕是深色（ink 或 bg 压暗），代码色块、计数器、砸出的大字只用 accent / accent2 和它们的明暗。
+CLIPS.y4_storytime = (() => {
+const { clamp, lerp, rng } = U;
+// 代码墙色块（屏幕上的语法高亮）：不放紫、紫蓝
+const COLS = ['#E06C75', '#5FB3A1', '#C3E88D', '#F78C6C', '#89DDFF', '#FFCB6B', '#8A9199'];
+const C0 = { wall: '#DCE9EC', floor: '#E8DCC8', desk: '#E2C29B', deskSide: '#CDA97F', line: '#5B6470', sky: '#BFE3F5', screen: '#20222D', cloud: '#fff', shelf: '#D9C3A0',
+  books: ['#8FB3C9', '#E7A37B', '#B9C98F', '#C9B28F'], pot: '#E7A37B', leaf: '#8DBF8B', stand: '#9AA0AC', bezel: '#2B2D36', mug: '#F26B4F', codes: COLS,
+  insertBg: '#15161C', gutter: '#4A4F66', bubble: '#2F3342', sent: '#3B82F6', sentInk: '#fff', bar: '#2A2D3A', dots: ['#FF5F57', '#FEBC2E', '#28C840'], appText: '#9AA3B8', hot: '#FFCB6B',
+  slamDim: '10,10,16', fast: '32,34,45', sayBg: '#fff', sayInk: '#1B1B1F', type: '#fff' };
+// 全片色板 → 房间和屏幕的一整套色（只从 6 个键派生）
+const fromPal = p => { const dk = PAL.dark(p), light = dk ? p.ink : p.surface, screen = dk ? PAL.mix(p.bg, '#000000', 0.35) : PAL.mix(p.ink, p.bg, 0.08);
+  return { wall: p.bg, floor: PAL.mix(p.bg, p.ink, 0.07), desk: PAL.mix(p.bg, p.sub, 0.25), deskSide: PAL.mix(p.bg, p.sub, 0.4), line: dk ? PAL.mix(p.sub, p.bg, 0.2) : p.sub,
+    sky: PAL.mix(p.bg, p.accent2, 0.3), screen, cloud: PAL.mix(light, PAL.mix(p.bg, p.accent2, 0.3), 0.3), shelf: PAL.mix(p.bg, p.sub, 0.3),
+    books: [p.accent, p.accent2, PAL.mix(p.accent, p.bg, 0.45), PAL.mix(p.accent2, p.bg, 0.45)], pot: p.accent, leaf: p.accent2, stand: PAL.mix(p.sub, p.bg, 0.3), bezel: PAL.mix(screen, light, 0.12), mug: p.accent,
+    codes: [p.accent, PAL.mix(p.accent2, light, 0.4), PAL.mix(light, p.accent, 0.3), PAL.mix(p.accent2, light, 0.65), PAL.mix(light, screen, 0.45), PAL.mix(p.accent, light, 0.5), PAL.mix(light, screen, 0.65)],   // 深屏上看得见：accent2 往亮色提
+    insertBg: dk ? PAL.mix(p.bg, '#000000', 0.55) : PAL.mix(p.ink, '#000000', 0.25), gutter: PAL.mix(screen, light, 0.25), bubble: PAL.mix(screen, light, 0.15), sent: p.accent2,
+    sentInk: PAL.on(p.accent2, [p.surface, p.ink, p.bg]), bar: PAL.mix(screen, light, 0.08), dots: [p.accent, PAL.mix(light, screen, 0.5), p.accent2], appText: PAL.mix(light, screen, 0.4), hot: p.accent,
+    slamDim: PAL.rgb(screen).join(','), fast: PAL.rgb(screen).join(','), sayBg: p.surface, sayInk: p.ink, type: light }; };
+const LINES = (() => { const r = rng(42), out = []; let ind = 0;   // 色块存色号（第几个），画的时候按 C.codes 取色
+  for (let i = 0; i < 400; i++) { if (r() < 0.18) ind = Math.min(4, ind + 1); else if (r() < 0.2) ind = Math.max(0, ind - 1);
+    const toks = []; let x = ind * 34; const n = 1 + (r() * 4 | 0); for (let k = 0; k < n; k++) { const w = 30 + r() * 150; toks.push([x, w, (r() * COLS.length) | 0]); x += w + 14; } out.push(toks); } return out; })();
+const NEED_FRAMES = 'y4 需要角色帧库 data.character.frames（AI 生帧，见 references/10-角色.md）；代码画的小人已停用。没有生图能力就别用 y4：用 y2/y5 或 scenes 里用手、物件、背影讲故事。';
+let keys, says, L, shots, FR, C = C0;
+return {
+  fonts: ['PuHui-Bold', 'PuHui-Black'],
+  safe: true,
+  init(ctx) {
+    const { W, H, u } = ctx, ch = ctx.data.character;
+    C = ctx.pal ? fromPal(ctx.pal) : C0;
+    // 角色只认帧库（对象带 frames；帧图已由 clip.js 加载，缺图在启动时就失败）。没有帧库 / 写预设名 → 启动失败
+    if (!ch || typeof ch !== 'object' || !ch.frames || typeof ch.frames !== 'object') throw new Error(NEED_FRAMES + (ch != null ? `（收到的 data.character = ${JSON.stringify(ch)}）` : '（spec 里没写 data.character）'));
+    FR = Object.fromEntries(Object.entries(ch.frames).map(([k, v]) => [k, ctx.IMG[v]]));
+    if (!FR.rest && !FR.talk) throw new Error('y4 data.character.frames 至少要有 rest 或 talk 一张（现有：' + Object.keys(FR).join(' ') + '）');
+    L = { cx: ctx.portrait ? W * 0.42 : W * 0.3, fy: ctx.portrait ? H * 0.8 : H * 1.02, R: (ctx.portrait ? 230 : 215) * u };
+    L.dy = L.fy - L.R * 0.55;                                             // 桌面高度
+    L.mon = ctx.portrait ? { x: W * 0.66, w: 330 * u, h: 240 * u } : { x: W * 0.6, w: 520 * u, h: 340 * u };   // 桌上的电脑（屏幕左上角 x、宽高）
+    says = ctx.of('point', 'title').map(q => ({ q, end: q.at + Math.max(0.6, [...(q.text || '')].length / 6.5) }));
+    keys = [[0, 'rest', 'happy']]; let n = 0;
+    for (const q of ctx.cues) {
+      if (q.kind === 'point' || q.kind === 'title') keys.push([q.at, (q.data && q.data.pose) || (n++ % 2 ? 'point' : 'talk'), 'talk']);
+      if (q.kind === 'highlight') keys.push([q.at, 'shrug', 'worry']);
+      if (q.kind === 'react' || q.kind === 'insert') keys.push([q.at, 'stiff', 'blank']);
+    }
+    // 特写镜头（react / insert）占的时间段
+    shots = ctx.of('react', 'insert').map(q => { const nx = ctx.cues.find(z => z.at > q.at + 1e-6); const end = q.dur ? q.at + q.dur : nx ? nx.at : ctx.dur + 1;
+      const hit = q.kind === 'insert' ? (q.data && q.data.hit != null ? +q.data.hit : q.at + (q.sub ? 1.3 : 0.4)) : 0; return { q, end, hit }; });
+  },
+  draw(c, t, ctx) {
+    const { W, H, u } = ctx, ts = MO.step(t, 24);                         // 角色 24fps，镜头 60fps
+    const shot = shots.find(s => t >= s.q.at - 1e-6 && t < s.end);
+    if (shot && shot.q.kind === 'insert') return insert(c, t, ctx, shot);
+    const inReact = !!shot;
+    // 镜头：中景定住；反应＝同机位跳到 1.9 倍大特写（砸镜：前 0.3s 从 2.2 弹回，之后定住）
+    let z = 1, cy = L.fy - L.R * 1.6;
+    if (inReact) { const l = t - shot.q.at; z = 1.9 * (1 + 0.15 * Math.max(0, 1 - MO.springHz(l, 3, 11))); cy = L.fy - L.R * 2.2; }
+    if (!ctx.alpha) { c.fillStyle = C.wall; c.fillRect(0, 0, W, H); }
+    CAM.with(c, { x: inReact ? L.cx : W / 2, y: inReact ? cy : H / 2, z }, g => {
+      if (!ctx.alpha) room(g, t, ctx);
+      const st = TOON.poseAt(keys, ts), say = says.find(s => t >= s.q.at - 1e-6 && t < s.end);
+      const mouth = window.VO_ENV ? TOON.mouth(t) : say ? [1, 2, 1, 0, 2, 1][Math.floor(MO.step(t - say.q.at + 1e-6, 12) * 12) % 6] : 0;
+      const info = frameChar(g, ts, st, inReact, mouth);
+      if (!ctx.alpha) desk(g, t, ctx);
+      if (inReact) { const sw = clamp((t - shot.q.at - 0.3) / 0.9); if (sw > 0) TOON.sweat(g, L.cx + L.R * 0.88, info.head[1] - L.R * 0.1, 30 * u, MO.expoOut(sw) * 0.6 + sw * 0.4); }
+      for (const h of ctx.of('highlight')) { const l = ctx.lt(t, h.at); if (l <= 0) continue;
+        g.save(); g.translate(info.head[0] + L.R * 1.35, info.head[1] - L.R * 0.6); g.rotate(0.14 + MO.settle(l, 0.12, 3, 6)); TOON.mark(g, (h.data && h.data.mark) || '？', 0, 0, clamp(l / 0.26), 130 * u, C === C0 ? undefined : ctx.pal.accent); g.restore(); }
+    });
+    // 对话气泡（屏幕空间，不跟镜头）：at 这一帧弹出，说完 0.6s 后收起；特写切回来后，特写之前的那句不再出现
+    if (!inReact) for (const s of says) {
+      const l = ctx.lt(t, s.q.at), out = clamp((t - s.end - 0.6) / 0.2); if (l <= 0 || out >= 1) continue;
+      const nx = says[says.indexOf(s) + 1]; if (nx && t >= nx.q.at - 1e-6) continue;
+      if (shots.some(sh => sh.q.at > s.q.at && sh.q.at <= t)) continue;
+      const txt = s.q.sub || s.q.text || '';
+      const bw0 = ctx.portrait ? W * 0.84 : W * 0.42, f = TY.fit(c, txt, bw0 - 80 * u, (ctx.portrait ? 64 : 62) * u, 'PuHui-Bold', { maxLines: 2, min: 0.72, balance: true });
+      c.font = `${f.size}px "PuHui-Bold"`; const bw = Math.min(bw0, Math.max(...f.lines.map(x => c.measureText(x).width)) + 80 * u);
+      const bh = f.lines.length * f.size * 1.3 + 56 * u, bx = ctx.portrait ? (W - bw) / 2 : W * 0.5, by = ctx.safe.top + (ctx.portrait ? H * 0.06 : H * 0.09);
+      const sc = MO.backOut(clamp(l / 0.25), 2.2) * (1 - out);
+      c.save(); c.translate(bx + 60 * u, by + bh); c.scale(sc, sc); c.translate(-(bx + 60 * u), -(by + bh));
+      c.fillStyle = C.sayBg; c.strokeStyle = C.sayInk; c.lineWidth = 6 * u; c.lineJoin = 'round';
+      c.beginPath(); c.roundRect(bx, by, bw, bh, 40 * u); c.moveTo(bx + 70 * u, by + bh); c.lineTo(bx + (ctx.portrait ? 40 : 10) * u, by + bh + 60 * u); c.lineTo(bx + 130 * u, by + bh); c.fill(); c.stroke();
+      c.fillStyle = C.sayBg; c.fillRect(bx + 76 * u, by + bh - 8 * u, 50 * u, 12 * u);
+      c.fillStyle = C.sayInk; c.textBaseline = 'alphabetic';
+      f.lines.forEach((ln, i) => c.fillText(ln, bx + 40 * u, by + 26 * u + (i + 1) * f.size * 1.2));
+      c.restore();
+    }
+  },
+};
+// 帧库角色：按当前姿势名取帧（缺的退到 talk → rest），说话时一拍二换 <姿势>_open；换姿势那一下沿用 poseAt 的挤压回弹
+function frameChar(g, ts, st, inReact, mouth) {
+  let name = 'rest'; for (const k of keys) if (ts >= k[0]) name = k[1];
+  if (inReact) name = 'react';
+  const pick = n => FR[n] || FR.talk || FR.rest;
+  const im = (!inReact && mouth && FR[name + '_open']) || pick(name), [iw, ih] = MD.size(im), h = L.R * 3.15, w = iw * h / ih;
+  g.save(); g.translate(L.cx, L.fy); g.scale(1 / Math.sqrt(st.squash), st.squash); g.drawImage(im, -w / 2, -h, w, h); g.restore();
+  return { head: [L.cx, L.fy - h * 0.78], hl: [L.cx - w * 0.4, L.fy - h * 0.45], hr: [L.cx + w * 0.4, L.fy - h * 0.45] };
+}
+// 房间：墙、地、窗（慢飘的云）、书架、画框。只画一次的东西不缓存——片段短，画得起
+function room(g, t, ctx) {
+  const { W, H, u } = ctx, X0 = -W, Y0 = -H, fy = L.fy;
+  g.fillStyle = C.wall; g.fillRect(X0, Y0, W * 3, H * 3);
+  g.fillStyle = C.floor; g.fillRect(X0, fy + 10 * u, W * 3, H * 2);
+  g.lineWidth = 3 * u; g.strokeStyle = C.line; g.lineJoin = 'round'; g.beginPath(); g.moveTo(X0, fy + 10 * u); g.lineTo(X0 + W * 3, fy + 10 * u); g.stroke();
+  // 窗：天空＋慢飘的云
+  const wx = ctx.portrait ? W * 0.08 : W * 0.05, wy = ctx.portrait ? H * 0.2 : H * 0.12, ww = ctx.portrait ? W * 0.3 : W * 0.17, wh = ww * 0.7;
+  g.save(); g.beginPath(); g.roundRect(wx, wy, ww, wh, 12 * u); g.clip(); g.fillStyle = C.sky; g.fillRect(wx, wy, ww, wh);
+  for (const [k, r, sp] of [[0.2, 46, 18], [0.7, 34, 12]]) { const x = wx - 60 * u + ((k * ww + t * sp * u) % (ww + 120 * u)), y = wy + wh * (0.35 + k * 0.3); g.fillStyle = C.cloud; g.beginPath(); g.arc(x, y, r * u, 0, 7); g.arc(x + r * 0.9 * u, y + 6 * u, r * 0.75 * u, 0, 7); g.arc(x - r * 0.9 * u, y + 8 * u, r * 0.65 * u, 0, 7); g.fill(); }
+  g.restore(); g.strokeStyle = C.line; g.beginPath(); g.roundRect(wx, wy, ww, wh, 12 * u); g.moveTo(wx + ww / 2, wy); g.lineTo(wx + ww / 2, wy + wh); g.moveTo(wx, wy + wh / 2); g.lineTo(wx + ww, wy + wh / 2); g.stroke();
+  // 墙上：横屏右边一块书架；竖屏书架在窗下方右侧
+  const r = rng(9), sx = ctx.portrait ? W * 0.62 : W * 0.68, sy = ctx.portrait ? H * 0.3 : H * 0.36, sw = ctx.portrait ? W * 0.3 : W * 0.22;
+  g.fillStyle = C.shelf; g.fillRect(sx, sy, sw, 16 * u); g.strokeRect(sx, sy, sw, 16 * u);
+  let x = sx + 16 * u; while (x < sx + sw * 0.7) { const w = (22 + r() * 22) * u, h = (70 + r() * 40) * u; g.fillStyle = C.books[(r() * 4) | 0]; g.fillRect(x, sy - h, w, h); g.strokeRect(x, sy - h, w, h); x += w + 5 * u; }
+  g.fillStyle = C.pot; const px = sx + sw * 0.83; g.beginPath(); g.moveTo(px - 30 * u, sy); g.lineTo(px - 38 * u, sy - 56 * u); g.lineTo(px + 38 * u, sy - 56 * u); g.lineTo(px + 30 * u, sy); g.closePath(); g.fill(); g.stroke();
+  g.fillStyle = C.leaf; for (const [dx, a] of [[-18, -0.5], [0, 0], [18, 0.5]]) { g.beginPath(); g.ellipse(px + dx * u, sy - 100 * u, 16 * u, 46 * u, a, 0, 7); g.fill(); g.stroke(); }
+}
+// 桌子挡在腰前（角色线最黑最粗，背景线细而灰）；桌上的电脑、马克杯
+function desk(g, t, ctx) {
+  const { W, H, u } = ctx, X0 = -W, dy = L.dy; g.lineWidth = 3 * u; g.strokeStyle = C.line;
+  // 电脑：屏幕微微发光，上面是滚动的代码色块（插入镜头切进去就是它）
+  const M = L.mon, mx = M.x, my = dy - M.h - 60 * u;
+  g.fillStyle = C.stand; g.fillRect(mx + M.w / 2 - 18 * u, dy - 62 * u, 36 * u, 62 * u); g.strokeRect(mx + M.w / 2 - 18 * u, dy - 62 * u, 36 * u, 62 * u);
+  g.beginPath(); g.ellipse(mx + M.w / 2, dy, 90 * u, 10 * u, 0, 0, 7); g.fill(); g.stroke();
+  g.fillStyle = C.bezel; g.beginPath(); g.roundRect(mx, my, M.w, M.h, 16 * u); g.fill(); g.stroke();
+  g.save(); g.beginPath(); g.roundRect(mx + 14 * u, my + 14 * u, M.w - 28 * u, M.h - 28 * u, 6 * u); g.clip(); g.fillStyle = C.screen; g.fillRect(mx, my, M.w, M.h);
+  const lh = 22 * u, off = (t * 30 * u) % lh; for (let i = 0; i < 20; i++) { const y = my + 30 * u + i * lh - off; for (const [x, w, col] of LINES[i % LINES.length]) { g.fillStyle = C.codes[col % C.codes.length]; g.globalAlpha = 0.75; g.fillRect(mx + 26 * u + x * 0.3 * u, y, w * 0.3 * u, 8 * u); } }
+  g.restore(); g.globalAlpha = 1;
+  g.fillStyle = C.desk; g.fillRect(X0, dy, W * 3, 40 * u); g.strokeRect(X0, dy, W * 3, 40 * u);
+  g.fillStyle = C.deskSide; g.fillRect(X0, dy + 40 * u, W * 3, H); g.strokeRect(X0, dy + 40 * u, W * 3, H);
+  // 马克杯
+  const cx = ctx.portrait ? W * 0.1 : L.cx - L.R * 1.9; g.fillStyle = C.mug; g.beginPath(); g.roundRect(cx, dy - 92 * u, 70 * u, 92 * u, 10 * u); g.fill(); g.stroke();
+  g.beginPath(); g.arc(cx + 78 * u, dy - 52 * u, 22 * u, -1.2, 1.2); g.lineWidth = 9 * u; g.stroke(); g.lineWidth = 3 * u;
+}
+// 插入镜头：电脑屏幕特写（过肩），打字→发送→代码墙加速滚→大字砸出＋屏幕一震（和示范片 s2_screen 同一套）
+function insert(c, t, ctx, shot) {
+  const { W, H, u, safe } = ctx, q = shot.q, d = q.data || {}, t0 = q.at, msg = q.sub || '', T_SEND = t0 + (msg ? 0.1 + Math.min(0.9, [...msg].length / 14) + 0.1 : 0.05), T_HIT = Math.max(shot.hit, T_SEND + 0.2);
+  const lt = t - t0, slam = t - T_HIT;
+  const scrollAt = tt => { const k = Math.max(0, tt - T_SEND - 0.15), span = Math.max(0.3, T_HIT - T_SEND - 0.15); return 46 * u * (k * 6 + Math.pow(k / span * 1.8, 3) * 6); };
+  const shake = slam > 0 && slam < 0.3 ? MO.settle(slam, 14 * u, 9, 14) : 0;
+  const zoom = 1.06 - 0.06 * MO.expoOut(clamp(lt / 0.25)) + (slam > 0 ? 0.04 * MO.expoOut(clamp(slam / 0.12)) : 0);   // 切进来：1.06 落到 1（像推过去的一下）；大字砸出时再推一档，之后定住
+  if (!ctx.alpha) { c.fillStyle = C.insertBg; c.fillRect(0, 0, W, H); }   // 透明模式：只留显示器和后脑勺，口播画面从四周透出来
+  const bx = W * 0.06, by = safe.top + H * 0.05, bw = W * 0.88, bh = H - safe.bottom - by - H * (ctx.portrait ? 0.2 : 0.06);
+  CAM.with(c, { x: W / 2 + shake, y: H / 2 - shake * 0.5, z: zoom }, c => {
+    c.fillStyle = C.bezel; c.beginPath(); c.roundRect(bx, by, bw, bh, 34 * u); c.fill();
+    const sx = bx + 40 * u, sy = by + 40 * u, sw = bw - 80 * u, sh = bh - 80 * u;
+    c.save(); c.beginPath(); c.roundRect(sx, sy, sw, sh, 14 * u); c.clip(); c.fillStyle = C.screen; c.fillRect(sx, sy, sw, sh);
+    const scr = scrollAt(t), top = sy + 64 * u;
+    // 我那一行：右侧气泡，打字（光标闪），发送后变蓝
+    if (msg) { const bubY = top + 110 * u - Math.min(scr, 600 * u), p = clamp((t - t0 - 0.1) / Math.max(0.2, T_SEND - t0 - 0.2));
+      const mf = TY.fit(c, msg, sw * 0.7 - 60 * u, (ctx.portrait ? 44 : 40) * u, 'PuHui-Bold', { maxLines: 3, min: 0.75, balance: true }), fs = mf.size, lh = fs * 1.3;   // 长句折行（最多 3 行），气泡往下长
+      const bwid = Math.max(...mf.lines.map(l => TY.width(c, l, fs, 'PuHui-Bold'))) + 60 * u, bht = 78 * u + (mf.lines.length - 1) * lh;
+      if (bubY > sy) { c.fillStyle = t >= T_SEND ? C.sent : C.bubble; c.beginPath(); c.roundRect(sx + sw - 30 * u - bwid, bubY - 52 * u, bwid, bht, 24 * u); c.fill();
+        let left = Math.round(p * mf.lines.reduce((a, l) => a + [...l].length, 0));   // 逐行打出来，光标跟在最后打到的那一行
+        const ns = mf.lines.map(ln => { const n = Math.min(left, [...ln].length); left -= n; return n; }), curK = Math.max(0, ns.findLastIndex(n => n > 0)), blink = t < T_SEND && Math.floor(t * 4) % 2;
+        mf.lines.forEach((ln, k) => { if (k > curK) return;
+          TY.text(c, [...ln].slice(0, ns[k]).join('') + (blink && k === curK ? '|' : ''), sx + sw - 30 * u - bwid + 30 * u, bubY + 2 * u + k * lh, { size: fs, fam: 'PuHui-Bold', color: t >= T_SEND ? C.sentInk : C.type, align: 'left' }); }); } }
+    // AI 的回复：代码墙，越滚越快
+    if (t > T_SEND + 0.05) { const lh = 46 * u, y0 = top + (msg ? 220 : 40) * u - scr;
+      for (let i = Math.max(0, Math.floor((top - y0) / lh)); ; i++) { const y = y0 + i * lh; if (y > sy + sh) break; if (y < top) continue;
+        const shown = clamp((t - T_SEND - 0.05 - Math.min(i, 12) * 0.03) / 0.05); if (shown <= 0) continue;
+        c.fillStyle = C.gutter; c.fillRect(sx + 30 * u, y - 12 * u, 44 * u, 16 * u);
+        for (const [x, w, col] of LINES[i % LINES.length]) { c.fillStyle = C.codes[col % C.codes.length]; c.globalAlpha = 0.9; c.beginPath(); c.roundRect(sx + 110 * u + x * u, y - 14 * u, w * u * shown, 20 * u, 10 * u); c.fill(); } c.globalAlpha = 1; }
+      const v = (scrollAt(t + 1 / 60) - scr) * 60; if (v > 1500 * u) { c.fillStyle = `rgba(${C.fast},${clamp((v - 1500 * u) / (6000 * u)) * 0.5})`; c.fillRect(sx, top, sw, sh); } }
+    // 顶栏：三个圆点、标题、计数器（砸出那一刻停在 data.count）
+    c.fillStyle = C.bar; c.fillRect(sx, sy, sw, 64 * u);
+    C.dots.forEach((col, i) => { c.fillStyle = col; c.beginPath(); c.arc(sx + 42 * u + i * 34 * u, sy + 32 * u, 10 * u, 0, 7); c.fill(); });
+    TY.text(c, d.app || 'AI助手', sx + sw / 2, sy + 44 * u, { size: 30 * u, fam: 'PuHui-Bold', color: C.appText });
+    if (d.count != null && t > T_SEND + 0.1) { const N = +d.count, k = slam >= 0 ? N : Math.min(N - 1, Math.floor(Math.pow(clamp((t - T_SEND - 0.15) / Math.max(0.2, T_HIT - T_SEND - 0.15)), 2.4) * (N - 1)));
+      TY.text(c, `${k}${d.unit || ''}`, sx + sw - 30 * u, sy + 44 * u, { size: 32 * u, fam: 'PuHui-Bold', color: slam >= 0 ? C.hot : C.appText, align: 'right' }); }
+    // 大字砸出（backOut 过冲）＋压暗
+    if (slam > 0 && q.text) { c.fillStyle = `rgba(${C.slamDim},${0.6 * MO.expoOut(clamp(slam / 0.15))})`; c.fillRect(sx, sy, sw, sh);
+      const fs = TY.fit(c, q.text, sw * 0.86, (ctx.portrait ? 200 : 230) * u, 'PuHui-Black', { maxLines: 2, min: 0.4, balance: true });
+      fs.lines.forEach((ln, i) => TY.pop(c, ln, sx + sw / 2, sy + sh / 2 + fs.size * 0.35 + (i - (fs.lines.length - 1) / 2) * fs.size * 1.1, clamp(slam / 0.24), { size: fs.size, fam: 'PuHui-Black', color: C.hot, over: 3.5, stroke: C.insertBg, strokeW: 18 * u })); }
+    c.restore();
+  });
+  // 前景：帧库给了 back 就贴角色的后脑勺（过肩），定住；砸出时往后一缩。没有 back 帧就不画（不再用代码画后脑勺）
+  const hx = W * (ctx.portrait ? 0.2 : 0.17), hy = by + bh - 60 * u + (slam > 0 ? -MO.settle(slam, 18 * u, 4, 7) : 0), s = (ctx.portrait ? 0.8 : 0.75) * u;
+  if (FR.back) { const [iw, ih] = MD.size(FR.back), h = 560 * s, w = iw * h / ih; c.drawImage(FR.back, hx - w / 2, hy + 500 * s - h, w, h); }
+}
+})();

package/engine/clips/y5_kinetic_type.js

@@ -0,0 +1,134 @@
+// 片段 · 动态文字（y5）：字就是演员。一个 cue 一页：主词在 at 这一帧砸进来（弹簧过冲 ≈8%），辅句从槽里升起；
+// 换页是色带擦除，新页面露出来的那一帧＝at（擦除在 at 之前 0.3s 开始）。
+// cues：title | point（一页：text 主词（太长自动缩字号、最多两行），sub 辅句，data.label 左上小标签如「01」）
+//       number（一页大数字：data {value, prefix, suffix, decimals}，at = 数字落定的时刻，页面提前 0.7s 出现开始滚）
+//       highlight（当前页里 data.word 这个词刷荧光笔＋放大一下；不给 word 就刷整个主词）
+//       sub 里的关键词：data.key 写辅句里的一个词，那个词用强调色（示范片「下一行」那样）
+//       number 的说明写 text 或 sub 都行（clip.js 已统一）；data.label 照样有
+// 两个以上的 point 页 = 一份清单：画进度轨（01/02/03，告诉观众第几个、一共几个；横屏右上、竖屏在下方）和背景巨型序号（低对比、斜向慢漂，data.num 可指定）。
+// data.palette = [[底色, 字色], ...] 换配色（写了就优先，盖过 spec.theme）。alpha 模式不画底，字白色带深色描边。safe：主词块在 top..H−bottom 之间居中，进度轨也在这一带里。
+// spec.theme（全片色板 ctx.pal）：页面轮换 [bg 底 ink 字] → [accent 底] → [ink 底 bg 字] → [accent2 底]（强调色页的字取 surface/ink/bg 里最清楚的那个）；
+//   荧光笔、辅句关键词、换页色带都只从 bg / ink / accent / accent2 里挑和当前页底色不同的。
+CLIPS.y5_kinetic_type = (() => {
+const { clamp, lerp } = U;
+const PAGES0 = [['#FFD23F', '#111111'], ['#FF5A36', '#FFFFFF'], ['#14213D', '#FFD23F'], ['#F4EFE6', '#111111']];
+let pages, LIST, TP = null;                                                // TP：全片色板（没写 data.palette 时才用）
+const same = (a, b) => String(a).toLowerCase() === String(b).toLowerCase();
+// 在候选色里挑一个和页底、字色都不同、压在页底上最清楚的
+const pick = (bg, fg, cands) => { const ok = cands.filter(x => !same(x, bg) && !same(x, fg)); return ok.length ? PAL.on(bg, ok) : cands[0]; };
+const accentOf = col => TP ? pick(col[0], col[1], [TP.accent, TP.accent2]) : col[0] === '#FFD23F' || col[0] === '#F4EFE6' || col[1] === '#FFD23F' ? '#FF5A36' : '#FFD23F';   // 字本身是黄的（深蓝页）就用橙，不然着色看不出来
+const fromPal = p => { const txt = bg => PAL.on(bg, [p.surface, p.ink, p.bg]); return [[p.bg, p.ink], [p.accent, txt(p.accent)], [p.ink, p.bg], [p.accent2, txt(p.accent2)]]; };
+return {
+  fonts: ['PuHui-Black', 'PuHui-Heavy', 'PuHui-Bold'],
+  safe: true,
+  init(ctx) {
+    TP = ctx.data.palette ? null : ctx.pal;
+    const { W, u } = ctx, pal = ctx.data.palette || (TP ? fromPal(TP) : PAGES0), g = document.createElement('canvas').getContext('2d');
+    pages = ctx.of('title', 'point', 'number').map((q, i) => {
+      const num = q.kind === 'number', nd = q.data || {};
+      const text = num ? (nd.prefix || '') + TY.fmt(nd.value || 0, nd.decimals ?? 0) + (nd.suffix || '') : (q.text || '');
+      const S0 = (ctx.portrait ? 380 : 300) * u;
+      let f = TY.fit(g, text, W * 0.86, S0, 'PuHui-Black', { maxLines: 1, min: 0.55, soft: true });   // 先缩字号放一行，再不行折两行；单个长英文词再缩也要放得下
+      if (!f.ok) f = num ? TY.fit(g, text, W * 0.86, S0, 'PuHui-Black', { maxLines: 1 })   // 数字不折行（滚动时逐字变宽，折开会跳）：只缩字号
+                     : TY.fit(g, text, W * 0.86, S0, 'PuHui-Black', { maxLines: 2, min: 0.3, balance: true });
+      const sf = q.sub ? TY.fit(g, q.sub, W * 0.86, (ctx.portrait ? 64 : 80) * u, 'PuHui-Heavy', { maxLines: 2, min: 0.6, balance: true }) : null;   // 辅句：放不下先缩、再折两行
+      const show = num ? q.at - 0.7 : q.at;
+      return { q, i, num, nd, text, f, sf, show, col: pal[i % pal.length] };
+    });
+    const pts = pages.filter(p => p.q.kind === 'point'); pts.forEach((p, k) => { p.ord = k + 1; });
+    LIST = pts.length >= 2 ? pts : null;
+    // 高亮的词不在页上：只告警（以前什么都不发生）
+    for (const h of ctx.of('highlight')) { const w = h.data && h.data.word; if (!w) continue; const pg = [...pages].reverse().find(p => p.show <= h.at + 1e-6);
+      if (pg && !pg.f.lines.some(l => l.includes(w))) console.warn(`y5 highlight at=${h.at}：主词里没有「${w}」（主词「${pg.text}」；荧光笔只刷主词，辅句里的词用 data.key 着色），这一下什么都不做`); }
+  },
+  draw(c, t, ctx) {
+    const { W, H, u } = ctx;
+    let k = -1; pages.forEach((p, i) => { if (t >= p.show - 1e-6) k = i; });
+    const P = pages[Math.max(0, k)]; if (!P) return;
+    const page = (p, c2) => drawPage(c2, p, t, ctx);
+    // 底＋点阵
+    if (!ctx.alpha) { c.fillStyle = P.col[0]; c.fillRect(0, 0, W, H); dots(c, t, P.col[1], 0.07, u, W, H); }
+    if (k >= 0) {
+      // 拍点微冲：每个 cue 落下时整屏放大 1.5%，0.15s 衰减
+      let bump = 1; for (const q of ctx.cues) { const l = t - q.at; if (l >= 0 && l < 0.4) bump += 0.015 * Math.exp(-l * 22); }
+      // 镜头不漂不晃：落定就停，运动只在拍点上（上面的微冲、主词砸入、换页色带）
+      CAM.with(c, { x: W / 2, y: H / 2, z: bump }, cc => { ghost(cc, P, t, ctx); page(P, cc); });
+      track(c, P, t, ctx);
+    }
+    // 换页：两条色带从左扫到右，最后一条后面露出新页（露出那一帧＝新页的 show 时刻）
+    const N = pages[k + 1];
+    if (N && !ctx.alpha) {
+      const p = (t - (N.show - 0.3)) / 0.36; if (p > 0 && p < 1) {
+        const mid = (TP ? [TP.accent, TP.accent2, TP.ink, TP.bg] : ['#FFD23F', '#FF5A36', '#14213D', '#3A86FF']).find(x => !same(x, P.col[0]) && !same(x, N.col[0])), cols = [mid, N.col[0]], sk = H * 0.35;   // 两条：一条和前后底色都不同的强调色＋新底色（以前第一条是字色，白字页前会整屏闪一帧白）
+        const edge = q => lerp(-sk - 40, W + sk + 40, MO.expoInOut(clamp(q)));
+        cols.forEach((col, i) => { const x = edge((p - i * 0.12) / 0.76); c.save(); c.beginPath(); c.moveTo(-sk - 60, 0); c.lineTo(x + sk, 0); c.lineTo(x, H); c.lineTo(-sk - 60, H); c.closePath(); c.clip(); c.fillStyle = col; c.fillRect(0, 0, W, H); c.restore(); });
+      }
+    }
+  },
+};
+function dots(c, t, col, a, u, W, H) { const g = 64 * u, ox = (t * 36 * u) % g, oy = (t * 18 * u) % g; c.save(); c.globalAlpha = a; c.fillStyle = col; for (let y = -g; y < H + g; y += g) for (let x = -g; x < W + g; x += g) { c.beginPath(); c.arc(x + ox, y + oy, 4 * u, 0, Math.PI * 2); c.fill(); } c.restore(); }
+function drawPage(c, P, t, ctx) {
+  const { W, H, u } = ctx, q = P.q, fg = ctx.alpha ? '#FFFFFF' : P.col[1], lt = ctx.lt(t, P.num ? P.show : q.at);
+  const stroke = ctx.alpha ? { stroke: '#111', strokeW: P.f.size * 0.06 } : {};
+  const lines = P.num ? [P.text] : P.f.lines, size = P.f.size, lh = size * 1.08;
+  const sub = q.sub, subSz = P.sf ? P.sf.size : 0, subL = P.sf ? P.sf.lines : [];
+  const by0 = ctx.safe.top, by1 = H - ctx.safe.bottom - (ctx.portrait && LIST ? 220 * u : 0), cyB = ctx.portrait ? by0 + (by1 - by0) * 0.44 : (by0 + by1) / 2;
+  const blockH = lines.length * lh + (sub ? subSz * (0.6 + subL.length * 1.15) : 0), y0 = cyB - blockH / 2 + size * 0.82;
+  // 标签（左上）
+  let label = q.data && q.data.label;
+  if (label) { const lf = TY.fitFloor(c, label, W * (ctx.portrait ? 0.84 : 0.5) - (ctx.portrait ? 80 : 140) * u, (ctx.portrait ? 56 : 52) * u, 'PuHui-Bold', { maxLines: 1, floor: 34 * u }); label = lf.lines[0] || ''; }
+  if (label) TY.rise(c, label, (ctx.portrait ? 80 : 140) * u, ctx.safe.top + (ctx.portrait ? 260 : 210) * u, MO.at(lt, 0, 0.3), { size: (ctx.portrait ? 56 : 52) * u, fam: 'PuHui-Bold', color: fg, track: 6 * u, ...(ctx.alpha ? { stroke: '#111', strokeW: 6 * u } : {}) });
+  // 高亮（画在字后面）
+  const hq = ctx.of('highlight').filter(h => h.at >= (P.num ? P.show : q.at) - 1e-6).find(h => { const nx = ctx.of('title', 'point', 'number').find(z => z.at > q.at); return !nx || h.at < nx.at; });
+  let hiScale = 1, knock = null;
+  if (hq) {
+    const hl = ctx.lt(t, hq.at), wd = hq.data && hq.data.word, found = !wd || lines.some(l => l.includes(wd));
+    hiScale = hl > 0 && found ? 1 + 0.06 * MO.settle(hl, 1, 2.5, 6) : 1;                     // 词不在主词里：不刷也不放大（init 里已告警）
+    if (hl > 0) lines.forEach((ln, i) => {
+      const word = wd || ln, at = ln.indexOf(word); if (at < 0) return;
+      const wPre = TY.width(c, ln.slice(0, at), size), wW = TY.width(c, word, size), wl = TY.width(c, ln, size), x = W / 2 - wl / 2 + wPre, y = y0 + i * lh;
+      const mc = ctx.alpha ? (TP ? TP.accent : '#FF5A36') : TP ? (same(P.col[0], TP.accent) ? TP.accent2 : TP.accent) : (P.col[0] === '#FFD23F' ? '#FF5A36' : '#FFD23F'), mr = [x - 12 * u, y - size * 0.86, wW + 24 * u, size * 1.0, MO.at(hl, 0, 0.3)];
+      TY.marker(c, ...mr, mc);
+      if (mc.toLowerCase() === fg.toLowerCase()) (knock = knock || []).push({ i, mr });   // 荧光笔和字同色（深蓝页黄字）：笔下面的字反白成底色，不然整个词被涂没
+    });
+  }
+  // 主词：每行在 at（+0.08s/行）砸进来；数字页从 0 滚到落定
+  lines.forEach((ln, i) => {
+    let s = ln; if (P.num) { const k = MO.expoOut(clamp(lt / 0.7)); s = (P.nd.prefix || '') + TY.fmt((P.nd.value || 0) * k, P.nd.decimals ?? 0) + (P.nd.suffix || ''); }
+    const w = TY.width(c, s, size), x = W / 2 - w / 2, y = y0 + i * lh;
+    TY.slam(c, s, x, y, lt - i * 0.08, { size, color: fg, scale: hiScale, ox: W / 2, oy: y - size * 0.36, ...stroke });
+    for (const k of (knock || []).filter(k => k.i === i)) {             // 只在荧光笔那块平行四边形里，用底色再砸一遍同一行（和 TY.marker 同一形状）
+      const [mx, my, mw, mh, mp] = k.mr, ww = mw * MO.expoOut(clamp(mp)), sk = mh * 0.18;
+      c.save(); c.beginPath(); c.moveTo(mx + sk, my); c.lineTo(mx + ww + sk, my); c.lineTo(mx + ww, my + mh); c.lineTo(mx, my + mh); c.closePath(); c.clip();
+      TY.slam(c, s, x, y, lt - i * 0.08, { size, color: P.col[0], scale: hiScale, ox: W / 2, oy: y - size * 0.36 }); c.restore();
+    }
+  });
+  if (sub) subL.forEach((ln, k) => {                                      // 辅句（可两行）；data.key 那个词用强调色
+    const sw = TY.width(c, ln, subSz, 'PuHui-Heavy'), sy = y0 + (lines.length - 1) * lh + subSz * (1.7 + k * 1.15), sp = MO.at(lt, 0.35 + k * 0.08, 0.35), so = { size: subSz, fam: 'PuHui-Heavy', color: fg, ...(ctx.alpha ? { stroke: '#111', strokeW: subSz * 0.08 } : {}) };
+    const key = q.data && q.data.key, ki = key ? ln.indexOf(key) : -1, x0 = W / 2 - sw / 2;
+    if (ki < 0) return TY.rise(c, ln, x0, sy, sp, so);
+    const pre = ln.slice(0, ki), post = ln.slice(ki + key.length), wp = TY.width(c, pre, subSz, 'PuHui-Heavy'), wk = TY.width(c, key, subSz, 'PuHui-Heavy');
+    if (pre) TY.rise(c, pre, x0, sy, sp, so); TY.rise(c, key, x0 + wp, sy, sp, { ...so, color: ctx.alpha ? (TP ? TP.accent : '#FFD23F') : accentOf(P.col) }); if (post) TY.rise(c, post, x0 + wp + wk, sy, sp, so);
+  });
+}
+// 背景巨型序号：清单页右下角（竖屏落在下半屏），低对比、弹簧落位后斜向慢漂；不和主词抢（字色 12% 透明度）
+function ghost(c, P, t, ctx) {
+  if (!LIST || !P.ord || ctx.alpha) return;
+  const { W, H, u } = ctx, lt = t - P.show, k = MO.springHz(lt, 2.0, 8), sc = lerp(1.35, 1, k), s = String((P.q.data && P.q.data.num) ?? P.ord);
+  const size = (ctx.portrait ? 1000 : 900) * u, x = W - (ctx.portrait ? 40 : 60) * u + lt * 14 * u, y = H - ctx.safe.bottom + (ctx.portrait ? -120 : 70) * u - lt * 10 * u;
+  TY.text(c, s, x, y, { size, fam: 'PuHui-Black', align: 'right', color: P.col[1], alpha: 0.12 * clamp(lt / 0.08), scale: sc, ox: x - size * 0.28, oy: y - size * 0.36 });
+}
+// 进度轨：01/02/03 三格（几个 point 页就几格），当前页那一格在换页露出那一帧点亮；画在相机外，不跟页面晃
+function track(c, P, t, ctx) {
+  if (!LIST) return;
+  const { W, H, u } = ctx, n = LIST.length, k = LIST.filter(p => p.show <= t + 1e-6).length; if (k === 0) return;
+  const fg = ctx.alpha ? '#FFFFFF' : P.col[1], gap = 18 * u, seg = Math.min((ctx.portrait ? 150 : 110) * u, ((ctx.portrait ? W * 0.86 : W * 0.4) - (n - 1) * gap) / n), tot = n * seg + (n - 1) * gap;   // 要点多时每格变窄，不出画
+  const x0 = ctx.portrait ? (W - tot) / 2 : W - (ctx.portrait ? 80 : 140) * u - tot, y = ctx.portrait ? H - ctx.safe.bottom - 130 * u : ctx.safe.top + 120 * u;
+  const a = MO.expoOut(clamp((t - LIST[0].show) / 0.3));
+  c.save(); c.globalAlpha = a;
+  for (let i = 0; i < n; i++) { const x = x0 + i * (seg + gap), on = i < k, fill = on ? MO.expoOut(clamp((t - LIST[i].show) / 0.3)) : 0;
+    c.fillStyle = fg; c.globalAlpha = a * 0.25; c.fillRect(x, y, seg, 10 * u); c.globalAlpha = a; c.fillRect(x, y, seg * fill, 10 * u);
+    TY.text(c, String(i + 1).padStart(2, '0'), x, y - 20 * u, { size: (ctx.portrait ? 40 : 32) * u, fam: 'PuHui-Bold', color: fg, align: 'left', alpha: on ? 1 : 0.4, track: 2 * u, ...(ctx.alpha ? { stroke: '#111', strokeW: 5 * u } : {}) }); }
+  c.restore();
+}
+})();

package/engine/compare.py

@@ -0,0 +1,19 @@
+#!/usr/bin/env python3
+"""原片 vs 复刻 逐帧并排：给一组时刻，各抽一帧，左原片右复刻，拼成一张图。
+python3 compare.py --a 原片.mp4 --b 复刻.mp4 --times 1.5,1.6 --out 对比.jpg [--w 640]"""
+import argparse, subprocess, io
+from PIL import Image, ImageDraw
+ap = argparse.ArgumentParser(); ap.add_argument('--a'); ap.add_argument('--b'); ap.add_argument('--times'); ap.add_argument('--out'); ap.add_argument('--w', type=int, default=640); ap.add_argument('--cols', type=int, default=2)
+a = ap.parse_args()
+def grab(v, t):
+    png = subprocess.run(['ffmpeg', '-v', 'error', '-ss', str(t), '-i', v, '-frames:v', '1', '-f', 'image2pipe', '-c:v', 'png', '-'], capture_output=True).stdout
+    return Image.open(io.BytesIO(png)).convert('RGB').resize((a.w, a.w * 9 // 16))
+ts = [float(x) for x in a.times.split(',')]
+w, h = a.w, a.w * 9 // 16
+cols = a.cols; rows = (len(ts) + cols - 1) // cols
+S = Image.new('RGB', (cols * 2 * w + (cols - 1) * 12, rows * (h + 18)), 'white'); d = ImageDraw.Draw(S)
+for i, t in enumerate(ts):
+    x = (i % cols) * (2 * w + 12); y = (i // cols) * (h + 18)
+    S.paste(grab(a.a, t), (x, y + 18)); S.paste(grab(a.b, t), (x + w, y + 18))
+    d.text((x + 3, y + 3), f'{t:.3f}s  原片 | 复刻', fill='black')
+S.save(a.out, quality=85); print(a.out)

package/engine/demos/_shared/hero.js

@@ -0,0 +1,96 @@
+// y1/y2/y3 三支示范片里的花叔形象。window.HERO_MODE = 'C'（默认）| 'A' | 'rig'。
+//   C 各片原生（示范片采用）：每种风格单独用 gpt-image 生一版设定图（Kurzgesagt 扁平无描边 / Vox 复用 Kurzgesagt 那张转灰度当剪报贴纸 /
+//     白板马克笔线稿），放在 demos/_shared/hero/。这是「纯代码绘制」主线的明确例外——角色是贴图，画面其余全是代码。
+//   A 极简几何：纯代码画的 Q 版（大圆头＋白渔夫帽＋圆眼镜），每片按该片画法上色/描线。不想用贴图时切到它。
+//   rig 旧骨架：lib/rig_huashu.js 的 FK 角色（各片里的回退分支）。
+// （实验时还有方向 B「G2 绘本帧库」，需要 24 张帧图，没收进 skill。）
+(() => {
+const { clamp, lerp } = U;
+const H = window.HERO = {};
+const MODE = () => window.HERO_MODE || 'C';
+H.mode = MODE;
+const PNG = n => `demos/_shared/hero/${n}.png`;
+window.EXTRA_ASSETS = (window.EXTRA_ASSETS || []).concat(['c1_0', 'c1_1', 'c1_2', 'c3_line'].map(PNG));
+const img = p => window.IMG[p];
+
+// 把一张图按「脚底中心」放到 (x, y)，高 h；face=-1 水平翻转
+const place = (c, im, x, y, h, face = 1, anchorY = 0.97) => {
+  const w = im.width * h / im.height; c.save(); c.translate(x, y); if (face < 0) c.scale(-1, 1); c.drawImage(im, -w / 2, -h * anchorY, w, h); c.restore();
+};
+
+// ---------- A：极简几何 Q 版 ----------
+// 原点 = 两脚之间地面；单位高 1 ≈ 全身高；opt.style: 'flat'（无描边，同色深一档做阴影）| 'line'（白底黑线）| 'print'（平涂＋细黑线）
+H.geo = (c, x, y, h, { face = 1, t = 0, style = 'flat', point = true, ink = '#1d1b19' } = {}) => {
+  const s = h / 100; c.save(); c.translate(x, y); c.scale(face * s, s);
+  const bob = Math.sin(t * 6.5) * 0.8;
+  const line = style !== 'flat', lw = style === 'line' ? 2.2 : 1.4;
+  const P = { skin: '#ffd8bd', skinSh: '#f2b493', hat: '#ffffff', hatSh: '#dfe3ef', tee: '#ffffff', teeSh: '#e3e6f0', shorts: '#d8c7a6', shortsSh: '#bfa982', shoe: '#ffffff', hair: '#1f1b2e', glass: '#1f1b2e', cheek: 'rgba(255,128,120,.45)' };
+  if (style === 'line') Object.assign(P, { skin: '#fbfbf8', skinSh: '#fbfbf8', hatSh: '#fbfbf8', tee: '#fbfbf8', teeSh: '#fbfbf8', shorts: '#fbfbf8', shortsSh: '#fbfbf8', cheek: 'rgba(239,114,38,.35)' });
+  // 扁平分面：先铺深一档，再把本色往左上挪 2.5 单位盖回去，右下留一条阴影带（和 Y1 的 flat 同一招）
+  const shape = (path, fill, sh) => { if (sh && sh !== fill) { c.save(); c.clip(path); c.fillStyle = sh; c.fill(path); c.translate(-2.5, -2); c.fillStyle = fill; c.fill(path); c.restore(); } else { c.fillStyle = fill; c.fill(path); } if (line) { c.strokeStyle = ink; c.lineWidth = lw; c.stroke(path); } };
+  const rr = (x0, y0, w, hh, r) => { const p = new Path2D(); p.roundRect(x0, y0, w, hh, r); return p; };
+  const el = (cx, cy, rx, ry) => { const p = new Path2D(); p.ellipse(cx, cy, rx, ry, 0, 0, Math.PI * 2); return p; };
+  c.lineJoin = 'round'; c.lineCap = 'round';
+  // 腿＋洞洞鞋
+  for (const lx of [-7, 7]) { shape(rr(lx - 3, -14, 6, 12, 3), P.skin, P.skinSh); shape(el(lx + 2.5, -2, 7.5, 4), P.shoe, P.hatSh); }
+  c.fillStyle = ink; for (const lx of [-7, 7]) for (const [dx, dy] of [[-1, -3], [2, -3.5], [5, -2.5]]) { c.beginPath(); c.arc(lx + 2.5 + dx, -2 + dy + 1, 0.8, 0, 7); c.fill(); }
+  c.translate(0, bob);
+  shape(rr(-12, -26, 24, 13, 4), P.shorts, P.shortsSh);                      // 短裤
+  // 远侧手臂（自然下垂，手表）
+  shape(rr(-15, -42, 6, 16, 3), P.skin, P.skinSh); c.fillStyle = ink; c.fillRect(-15.5, -30, 7, 3);
+  shape(rr(-14, -46, 28, 22, 7), P.tee, P.teeSh);                            // T 恤
+  // 近侧手臂：指向前方（point）或下垂
+  if (point) { c.save(); c.translate(10, -42); c.rotate(-1.35 + Math.sin(t * 3.4) * 0.06); shape(rr(-3.2, 0, 6.4, 20, 3.2), P.skin, P.skinSh); shape(el(0, 21, 3.6, 3.6), P.skin); c.restore(); }
+  else shape(rr(9, -42, 6, 16, 3), P.skin, P.skinSh);
+  // 头：正面大圆脸（头身比约 1:1.2）。正面比侧面好画、也更好认：帽檐下一圈刘海、两只耳朵、圆眼镜居中
+  c.translate(0, -66); c.rotate(Math.sin(t * 2.1) * 0.03);
+  for (const ex of [-19, 19]) shape(el(ex, 4, 3.6, 4.6), P.skin, P.skinSh);   // 耳
+  shape(el(0, 2, 19, 18.5), P.skin, P.skinSh);                               // 脸
+  const crown = new Path2D(); crown.moveTo(-17, -9); crown.bezierCurveTo(-17, -33, 17, -33, 17, -9); crown.closePath();
+  const brim = new Path2D(); brim.ellipse(0, -9, 29, 7, 0, 0, Math.PI * 2);
+  shape(brim, P.hat, P.hatSh); shape(crown, P.hat, P.hatSh);
+  // 刘海＋鬓角：画在帽檐之后，从帽檐下沿露出一排黑发（光头感就是少了这一排）
+  c.fillStyle = P.hair; c.beginPath(); c.moveTo(-19.5, -4); c.lineTo(19.5, -4); c.lineTo(19, 5); c.lineTo(16.5, 1); c.lineTo(13, -0.5); c.lineTo(9, 1.5); c.lineTo(5, -1); c.lineTo(0, 1); c.lineTo(-5, -1.5); c.lineTo(-9, 1); c.lineTo(-13, -1); c.lineTo(-16.5, 1.5); c.lineTo(-19, 5); c.closePath(); c.fill();
+  shape(brim, P.hat, P.hatSh);
+  if (!line) { c.fillStyle = P.hatSh; c.beginPath(); c.ellipse(0, -9.5, 17, 2.2, 0, 0, Math.PI * 2); c.fill(); }   // 帽身与帽檐交界的一道暗线（色块，不是描边）
+  // 圆眼镜＋眼睛（眨眼 0.12s/3.2s）
+  const blink = (t % 3.2) > 3.08;
+  c.strokeStyle = P.glass; c.lineWidth = 1.8; for (const ex of [-7.5, 7.5]) { c.beginPath(); c.arc(ex, 3, 6, 0, 7); c.stroke(); }
+  c.beginPath(); c.moveTo(-1.5, 3); c.lineTo(1.5, 3); c.stroke();
+  c.fillStyle = P.glass; for (const ex of [-7.5, 7.5]) { if (blink) c.fillRect(ex - 2.2, 3, 4.4, 1.1); else { c.beginPath(); c.ellipse(ex, 3.4, 1.8, 2.3, 0, 0, 7); c.fill(); } }
+  c.fillStyle = P.cheek; for (const ex of [-11, 11]) { c.beginPath(); c.ellipse(ex, 10.5, 3.2, 1.9, 0, 0, 7); c.fill(); }
+  const m = 0.4 + 0.6 * Math.max(0, Math.sin(t * 9));                       // 嘴：说话时开合
+  c.fillStyle = '#c4473f'; c.beginPath(); c.ellipse(0, 12.5, 2.8, 0.9 + 1.7 * m, 0, 0, 7); c.fill();
+  c.restore();
+};
+
+// ---------- 每片的接入点 ----------
+// Y1 镜 3：花叔站在草坡左侧指向黑猫（脚底 (470,900)，全身约 440px）
+H.y1 = (g, ft, flatFn) => {
+  const m = MODE();
+  if (m === 'A') return H.geo(g, 470, 900, 440, { face: 1, t: ft, style: 'flat' });
+  if (m === 'C') {
+    // 一张设定稿里的三个姿势当三个关键帧：拉出时挥手 → 扫描时指向黑猫 → 标签弹出后举手欢呼。
+    // 换姿势那一下给 0.12s 的挤压回弹（Kurzgesagt 弹出的 108% 过冲），站着时以脚底为轴呼吸。
+    const l = ft - Y1.SHOTS.s3[0], k = l < 1.25 ? 1 : l < 2.3 ? 0 : 2, t0 = [0, 1.25, 2.3][[1, 0, 2].indexOf(k)];
+    const pop = l - t0 < 0.14 && t0 > 0 ? 1 + 0.06 * Math.sin((l - t0) / 0.14 * Math.PI) : 1;
+    const br = 1 + 0.012 * Math.sin(ft * 5.2);
+    g.save(); g.translate(470, 905); g.scale(1 / Math.sqrt(br * pop), br * pop); place(g, img(PNG('c1_' + k)), 0, 0, 450, 1); g.restore(); return;
+  }
+  return false;
+};
+// Y2 镜 3：剪纸贴纸，画进 sp（之后统一垫白边、阴影），脚底 (1500,1040)，面朝左
+H.y2 = (g, st) => {
+  const m = MODE();
+  if (m === 'A') return H.geo(g, 1500, 1040, 560, { face: -1, t: st, style: 'print', ink: '#171716' }), true;
+  if (m === 'C') { const k = Math.floor(st * 12); g.save(); g.translate(1500, 1015); g.rotate(((k * 7919) % 13 - 6) * 0.0012); g.filter = 'grayscale(1) contrast(1.25) brightness(1.04)'; place(g, img(PNG('c1_0')), 20, 8, 520, -1); g.restore(); return true; }   // 卡通帧转灰度当剪报贴纸：按 12fps 微抖（定格感）
+  return false;
+};
+// Y3 镜 3：被之字形笔触揭开的那张画（世界坐标，脚底 (fx, fy)，高 hh）
+H.y3 = (g, fx, fy, hh, ft) => {
+  const m = MODE();
+  if (m === 'A') return H.geo(g, fx, fy, hh, { face: 1, t: ft, style: 'line', ink: '#0A0503' }), true;
+  if (m === 'C') { g.save(); g.globalCompositeOperation = 'multiply'; place(g, img(PNG('c3_line')), fx, fy + 4, hh * 1.08, 1); g.restore(); return true; }
+  return false;
+};
+})();

package/engine/demos/long_scroll/eras.js

@@ -0,0 +1,23 @@
+// 示范 · 长卷穿越片：一条横向长画卷，几个「世界段」首尾相接，主角从左走到右，跨过边界时画风跟着换。
+// 这里只收了 3 段（埃及壁画 → 莫奈《日本桥》→ 8-bit 像素），完整片子是 24 段，做法见 references/11-长卷穿越片.md。
+//   预览 index.html?film=demos/long_scroll   渲染 render.py --film demos/long_scroll --out long_scroll.mp4
+// 骨架 lib/world.js 管时间轴、主角行进、只进不退的相机、按边界裁开的主角、角标；每段一个文件 segments/<id>.js，调用 WORLD.add({...})。
+(() => {
+  window.__bootErrors = window.__bootErrors || [];
+  const base = 'demos/long_scroll/';
+  const load = url => { const x = new XMLHttpRequest(); x.open('GET', url, false); x.send(); if (x.status !== 200) { __bootErrors.push(`${url} 不存在 (HTTP ${x.status})`); return; }
+    try { (0, eval)(x.responseText + `\n//# sourceURL=${url}`); } catch (e) { __bootErrors.push(`${url} 执行出错 ${e && e.stack || e}`); } };
+  load(base + 'lib/crossing.js');                 // XING：角色帧库、笔触材质、莫奈世界
+  load(base + 'lib/acts.js');                     // ACT：打水漂的石子轨迹等小剧本工具
+  load(base + 'lib/world.js');                    // WORLD：长卷骨架
+  // 片子顺序：改顺序、加段只改这里（加段 = 往 segments/ 放一个文件，再把 id 写进来）
+  window.FILM_ORDER = ['02_egypt', '28_monet', '14_8bit'];
+  for (const id of window.FILM_ORDER) { const n = WORLD.segs.length; load(`${base}segments/${id}.js`);
+    if (WORLD.segs.length === n || WORLD.segs[WORLD.segs.length - 1].id !== id) __bootErrors.push(`segments/${id}.js 没有 WORLD.add({ id: '${id}', ... })`); }
+  // 每段用到的帧库（hero.walk、acts[].key、sprites）一次性登记成资源，引擎启动前全部加载
+  const sprites = new Set(); WORLD.segs.forEach(s => { if (s.hero && s.hero.walk) sprites.add(s.hero.walk); (s.acts || []).forEach(a => a.key && sprites.add(a.key)); (s.sprites || []).forEach(k => sprites.add(k)); });
+  try { window.EXTRA_ASSETS = (window.EXTRA_ASSETS || []).concat(XING.sprites([...sprites])); } catch (e) { __bootErrors.push('帧库缺失：' + e.message); }
+  WORLD.layout();
+  window.PUNCH = 0;
+  window.ERAS = [{ id: 'film', dur: WORLD.total, draw: (c, lt, t) => WORLD.draw(c, t) }];
+})();

package/engine/demos/long_scroll/frames/8bit_act/meta.json

@@ -0,0 +1,69 @@
+{
+ "frames": [
+  {
+   "file": "01.png",
+   "ax": 120.0,
+   "ay": 374.0,
+   "w": 239,
+   "h": 375,
+   "air": 0
+  },
+  {
+   "file": "02.png",
+   "ax": 118.5,
+   "ay": 323.0,
+   "w": 239,
+   "h": 324,
+   "air": 0
+  },
+  {
+   "file": "03.png",
+   "ax": 116.5,
+   "ay": 396.0,
+   "w": 255,
+   "h": 367,
+   "air": 30
+  },
+  {
+   "file": "04.png",
+   "ax": 127.0,
+   "ay": 420.0,
+   "w": 246,
+   "h": 372,
+   "air": 49
+  },
+  {
+   "file": "05.png",
+   "ax": 136.0,
+   "ay": 395.0,
+   "w": 257,
+   "h": 381,
+   "air": 15
+  },
+  {
+   "file": "06.png",
+   "ax": 125.0,
+   "ay": 316.0,
+   "w": 247,
+   "h": 317,
+   "air": 0
+  },
+  {
+   "file": "07.png",
+   "ax": 106.5,
+   "ay": 369.0,
+   "w": 214,
+   "h": 370,
+   "air": 0
+  },
+  {
+   "file": "08.png",
+   "ax": 128.5,
+   "ay": 397.0,
+   "w": 267,
+   "h": 373,
+   "air": 25
+  }
+ ],
+ "ref_h": 371.0
+}