@biunow/agent-biuart 0.0.0-stage → 0.1.1

package/engine/lib/fonts/LICENSES.md

@@ -0,0 +1,40 @@
+# 字体许可 · Font licenses
+
+本目录的字体都不属于本仓库的 MIT 授权，各自沿用原许可。全部是 SIL Open Font License 1.1（全文见同目录 `OFL.txt`），可以随软件再分发、可商用，但不能单独售卖字体文件。部分文件是按 GB2312 或按用字抽出的子集（`scripts/font_subset.py`），转成了 woff。
+
+The fonts in this directory are NOT covered by the repository's MIT license. Each keeps its own license; all of them are SIL Open Font License 1.1 (full text in `OFL.txt`). Some files are subsets converted to WOFF.
+
+| 文件 | 字体 | 版权 | 来源 |
+|---|---|---|---|
+| `AlfaSlabOne-400.woff` | Alfa Slab One | © 2016 The Alfa Slab One Project Authors，Reserved Font Name "Alfa Slab" | Google Fonts |
+| `Anton-400.woff` | Anton | © 2020 The Anton Project Authors | Google Fonts |
+| `ArchivoBlack-400.woff` | Archivo Black | © 2017 The Archivo Black Project Authors | Google Fonts |
+| `Bangers-400.woff` | Bangers | © 2010 The Bangers Project Authors | Google Fonts |
+| `Caveat-600.woff` | Caveat | © 2014 The Caveat Project Authors | Google Fonts |
+| `Cinzel-400.woff` `Cinzel-700.woff` | Cinzel | © 2020 The Cinzel Project Authors | Google Fonts |
+| `CormorantGaramond-500.woff` `-500i` `-700` | Cormorant Garamond | © 2015 The Cormorant Project Authors | Google Fonts |
+| `EBGaramond-400.woff` `-400i` `-600` | EB Garamond | © 2017 The EB Garamond Project Authors | Google Fonts |
+| `Exo2-800i.woff` | Exo 2 | © 2013 The Exo 2 Project Authors | Google Fonts |
+| `GochiHand-400.woff` | Gochi Hand | © 2011 Huerta Tipográfica，Reserved Font Names "Gochi" and "Gochi Hand" | Google Fonts |
+| `IMFellEnglish-400.woff` `-400i` | IM FELL English | © 2007 Igino Marini，Reserved Font Names "IM FELL English Roman/Italic" | Google Fonts |
+| `Inter-var.woff` | Inter | © 2016 The Inter Project Authors | github.com/rsms/inter |
+| `JosefinSans-700.woff` | Josefin Sans | © 2010 The Josefin Sans Project Authors，Reserved Font Name "Josefin Sans" | Google Fonts |
+| `Kalam-700.woff` | Kalam | © 2014 Indian Type Foundry | Google Fonts |
+| `LibreBaskerville-400.woff` `-700` | Libre Baskerville | © 2012 The Libre Baskerville Project Authors | Google Fonts |
+| `LilitaOne-400.woff` | Lilita One | © 2011 Juan Montoreano，Reserved Font Name "Lilita One" | Google Fonts |
+| `Marcellus-400.woff` | Marcellus | © 2012 Brian J. Bonislawsky (Astigmatic)，Reserved Font Name "Marcellus" | Google Fonts |
+| `PlayfairDisplay-400i.woff` `-700` `-700i` | Playfair Display | © 2017 The Playfair Display Project Authors，Reserved Font Name "Playfair Display" | Google Fonts |
+| `Poppins-600.woff` `-700` `-800` | Poppins | © 2020 The Poppins Project Authors | Google Fonts |
+| `PressStart2P-400.woff` | Press Start 2P | © 2012 The Press Start 2P Project Authors，Reserved Font Name "Press Start 2P" | Google Fonts |
+| `Righteous-400.woff` | Righteous | © 2011 Brian J. Bonislawsky (Astigmatic)，Reserved Font Name "Righteous" | Google Fonts |
+| `RobotoCondensed-var.woff` | Roboto Condensed | © 2011 The Roboto Project Authors | Google Fonts |
+| `Rye-400.woff` | Rye | © 2010 Sorkin Type Co，Reserved Font Name "Rye" | Google Fonts |
+| `UnifrakturMaguntia-400.woff` | UnifrakturMaguntia | © 2010 j. 'mach' wust，© 2009 Peter Wiegel，Reserved Font Name "UnifrakturMaguntia" | Google Fonts |
+| `cmunrm.woff` `cmunti.woff` | CMU Serif（Computer Modern Unicode） | Andrey V. Panov，部分字形来自 AMS Blue Sky fonts | CTAN cm-unicode |
+| `LXGWWenKai-500.woff` | 霞鹜文楷 LXGW WenKai（子集） | © 2021-2025 LXGW；© 2020 The Klee Project Authors | github.com/lxgw/LxgwWenKai |
+| `NotoSansSC-500/700/800/900.woff` | 思源黑体 Noto Sans SC（按字重实例化后的 GB2312 子集；代码里 family 名叫 `PuHui-*`） | © 2014-2021 Adobe，Reserved Font Name "Source" | Google Fonts |
+| `NotoSansSC-sub.woff` | 思源黑体 Noto Sans SC（按用字子集） | © 2014-2021 Adobe，Reserved Font Name "Source" | Google Fonts |
+| `NotoSerifSC-sub.woff` | 思源宋体 Noto Serif SC（按用字子集） | © 2017-2024 Adobe | Google Fonts |
+| `NotoSerifJP-600.woff` | Noto Serif JP | © 2017-2024 Adobe | Google Fonts |
+
+带 Reserved Font Name 的字体，改动过的版本不能沿用保留名。本目录里带保留名的这几款（拉丁字体）内部字体名都是原名（按 Google Fonts 发行的 woff 使用）；如果你要对它们抽子集或改字形，请同时改掉 family 名。

package/engine/lib/fonts/OFL.txt

@@ -0,0 +1,94 @@
+Copyright notices for each font file in this directory are listed in LICENSES.md
+(and are embedded in each font's name table).
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+http://scripts.sil.org/OFL
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded, 
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

package/engine/lib/fonts/index.json

@@ -0,0 +1 @@
+[["Cinzel-400.woff", "Cinzel", "normal", "400"], ["Cinzel-700.woff", "Cinzel", "normal", "700"], ["CormorantGaramond-500i.woff", "Cormorant Garamond", "italic", "500"], ["CormorantGaramond-500.woff", "Cormorant Garamond", "normal", "500"], ["CormorantGaramond-700.woff", "Cormorant Garamond", "normal", "700"], ["EBGaramond-400i.woff", "EB Garamond", "italic", "400"], ["EBGaramond-400.woff", "EB Garamond", "normal", "400"], ["EBGaramond-600.woff", "EB Garamond", "normal", "600"], ["IMFellEnglish-400i.woff", "IM Fell English", "italic", "400"], ["IMFellEnglish-400.woff", "IM Fell English", "normal", "400"], ["PlayfairDisplay-400i.woff", "Playfair Display", "italic", "400"], ["PlayfairDisplay-700i.woff", "Playfair Display", "italic", "700"], ["PlayfairDisplay-700.woff", "Playfair Display", "normal", "700"], ["PressStart2P-400.woff", "Press Start 2P", "normal", "400"], ["Poppins-600.woff", "Poppins", "normal", "600"], ["Poppins-700.woff", "Poppins", "normal", "700"], ["Poppins-800.woff", "Poppins", "normal", "800"], ["JosefinSans-700.woff", "Josefin Sans", "normal", "700"], ["Bangers-400.woff", "Bangers", "normal", "400"], ["GochiHand-400.woff", "Gochi Hand", "normal", "400"], ["Caveat-600.woff", "Caveat", "normal", "600"], ["LilitaOne-400.woff", "Lilita One", "normal", "400"], ["NotoSerifJP-600.woff", "Noto Serif JP", "normal", "600"], ["Exo2-800i.woff", "Exo 2", "italic", "800"], ["ArchivoBlack-400.woff", "Archivo Black", "normal", "400"], ["Kalam-700.woff", "Kalam", "normal", "700"], ["UnifrakturMaguntia-400.woff", "UnifrakturMaguntia", "normal", "400"], ["Marcellus-400.woff", "Marcellus", "normal", "400"], ["Righteous-400.woff", "Righteous", "normal", "400"], ["Anton-400.woff", "Anton", "normal", "400"], ["AlfaSlabOne-400.woff", "Alfa Slab One", "normal", "400"], ["Rye-400.woff", "Rye", "normal", "400"], ["LibreBaskerville-400.woff", "Libre Baskerville", "normal", "400"], ["LibreBaskerville-700.woff", "Libre Baskerville", "normal", "700"]]

package/engine/lib/fonts.js

@@ -0,0 +1,56 @@
+// 每个字体文件注册成独立 family（文件名去扩展名），用法：ctx.font = '96px "Cinzel-700"'
+window.FONT_FACES = [
+  {family:'Cinzel-400', url:'lib/fonts/Cinzel-400.woff'},
+  {family:'Cinzel-700', url:'lib/fonts/Cinzel-700.woff'},
+  {family:'CormorantGaramond-500i', url:'lib/fonts/CormorantGaramond-500i.woff'},
+  {family:'CormorantGaramond-500', url:'lib/fonts/CormorantGaramond-500.woff'},
+  {family:'CormorantGaramond-700', url:'lib/fonts/CormorantGaramond-700.woff'},
+  {family:'EBGaramond-400i', url:'lib/fonts/EBGaramond-400i.woff'},
+  {family:'EBGaramond-400', url:'lib/fonts/EBGaramond-400.woff'},
+  {family:'EBGaramond-600', url:'lib/fonts/EBGaramond-600.woff'},
+  {family:'IMFellEnglish-400i', url:'lib/fonts/IMFellEnglish-400i.woff'},
+  {family:'IMFellEnglish-400', url:'lib/fonts/IMFellEnglish-400.woff'},
+  {family:'PlayfairDisplay-400i', url:'lib/fonts/PlayfairDisplay-400i.woff'},
+  {family:'PlayfairDisplay-700i', url:'lib/fonts/PlayfairDisplay-700i.woff'},
+  {family:'PlayfairDisplay-700', url:'lib/fonts/PlayfairDisplay-700.woff'},
+  {family:'PressStart2P-400', url:'lib/fonts/PressStart2P-400.woff'},
+  {family:'Poppins-600', url:'lib/fonts/Poppins-600.woff'},
+  {family:'Poppins-700', url:'lib/fonts/Poppins-700.woff'},
+  {family:'Poppins-800', url:'lib/fonts/Poppins-800.woff'},
+  {family:'JosefinSans-700', url:'lib/fonts/JosefinSans-700.woff'},
+  {family:'Bangers-400', url:'lib/fonts/Bangers-400.woff'},
+  {family:'GochiHand-400', url:'lib/fonts/GochiHand-400.woff'},
+  {family:'Caveat-600', url:'lib/fonts/Caveat-600.woff'},
+  {family:'LilitaOne-400', url:'lib/fonts/LilitaOne-400.woff'},
+  {family:'NotoSerifJP-600', url:'lib/fonts/NotoSerifJP-600.woff'},
+  {family:'Exo2-800i', url:'lib/fonts/Exo2-800i.woff'},
+  {family:'ArchivoBlack-400', url:'lib/fonts/ArchivoBlack-400.woff'},
+  {family:'Kalam-700', url:'lib/fonts/Kalam-700.woff'},
+  {family:'UnifrakturMaguntia-400', url:'lib/fonts/UnifrakturMaguntia-400.woff'},
+  {family:'Marcellus-400', url:'lib/fonts/Marcellus-400.woff'},
+  {family:'Righteous-400', url:'lib/fonts/Righteous-400.woff'},
+  {family:'Anton-400', url:'lib/fonts/Anton-400.woff'},
+  {family:'AlfaSlabOne-400', url:'lib/fonts/AlfaSlabOne-400.woff'},
+  {family:'Rye-400', url:'lib/fonts/Rye-400.woff'},
+  {family:'LibreBaskerville-400', url:'lib/fonts/LibreBaskerville-400.woff'},
+  {family:'LibreBaskerville-700', url:'lib/fonts/LibreBaskerville-700.woff'},
+  // 中文：霞鹜文楷 Medium 子集（OFL 1.1）。GB2312 全部汉字＋预置字＋skill 里用到的字（font_subset.py --gb2312），生僻字用 scripts/font_subset.py --text 补；NotoSerifJP 是日文子集，简体字不全（「戏」「蓝」都没有）
+  {family:'LXGWWenKai-500', url:'lib/fonts/LXGWWenKai-500.woff'},
+  // ---- YouTube 解说语法（references/09）----
+  // 中文黑体：family 名沿用 PuHui-*（代码里 97 处引用不用改），开源版文件是思源黑体 Noto Sans SC（OFL 1.1）500/700/800/900 四个字重的 GB2312 子集
+  // （scripts/font_subset.py --gb2312，单字重约 1.4MB）。作者原用阿里巴巴普惠体 3.0，其许可不允许转换、拆分后再分发，所以不随仓库附带；
+  // 你自己装了普惠体想换回去：按 font_subset.py 说明生成 PuHui-*.woff，把下面四行的 url 改回去即可。
+  {family:'PuHui-Medium', url:'lib/fonts/NotoSansSC-500.woff'},
+  {family:'PuHui-Bold', url:'lib/fonts/NotoSansSC-700.woff'},
+  {family:'PuHui-Heavy', url:'lib/fonts/NotoSansSC-800.woff'},
+  {family:'PuHui-Black', url:'lib/fonts/NotoSansSC-900.woff'},
+  // 3b1b 公式：CMU（LaTeX Computer Modern）正体/斜体
+  {family:'CMU-rm', url:'lib/fonts/cmunrm.woff'},
+  {family:'CMU-it', url:'lib/fonts/cmunti.woff'},
+  // 发布会 Inter（SF Pro 最接近的开源字）、财经 Roboto Condensed：可变字重，用 '600 220px "Inter"' 选字重
+  {family:'Inter', url:'lib/fonts/Inter-var.woff', desc:{weight:'100 900'}},
+  {family:'RobotoCondensed', url:'lib/fonts/RobotoCondensed-var.woff', desc:{weight:'100 900'}},
+  // 思源黑/宋（可变字重）：只含 3b1b/发布会/财经三支示范片用到的字（源文件未随仓库附带，换题目缺字时改用 PuHui-*，或下 Google Fonts 的 NotoSansSC[wght].ttf 重做子集）
+  {family:'NotoSansSC', url:'lib/fonts/NotoSansSC-sub.woff', desc:{weight:'100 900'}},
+  {family:'NotoSerifSC', url:'lib/fonts/NotoSerifSC-sub.woff', desc:{weight:'200 900'}},
+];

package/engine/lib/kit.js

@@ -0,0 +1,91 @@
+// 跨场景共用的小工具：点列加密/等弧长重采样、可变线宽路径 ribbon、整幅行/列扭曲、手绘不规则圆、全片连续编舞、近侧手臂补盖、角标。
+// 渲染器在 lib/brush.js（笔与水）、lib/render.js（网点/点彩/赛璐珞/光影/皮影）、lib/post.js（VHS/胶片/泛光/纹理叠角色）。
+(() => {
+let W = 1920, H = 1080; U.onStage((w, h) => { W = w; H = h; });   // 画布尺寸跟 U.setStage 走（默认 1920×1080）
+const { clamp, lerp, rng } = U;
+const K = window.KIT = {};
+
+// Catmull-Rom 加密点列（开放）
+K.densify = (pts, per = 6) => {
+  const out = [], n = pts.length, P_ = i => pts[Math.max(0, Math.min(n - 1, i))];
+  for (let i = 0; i < n - 1; i++) {
+    const p0 = P_(i - 1), p1 = P_(i), p2 = P_(i + 1), p3 = P_(i + 2);
+    for (let k = 0; k < per; k++) {
+      const t = k / per, t2 = t * t, t3 = t2 * t;
+      out.push([0.5 * (2 * p1[0] + (-p0[0] + p2[0]) * t + (2 * p0[0] - 5 * p1[0] + 4 * p2[0] - p3[0]) * t2 + (-p0[0] + 3 * p1[0] - 3 * p2[0] + p3[0]) * t3),
+                0.5 * (2 * p1[1] + (-p0[1] + p2[1]) * t + (2 * p0[1] - 5 * p1[1] + 4 * p2[1] - p3[1]) * t2 + (-p0[1] + 3 * p1[1] - 3 * p2[1] + p3[1]) * t3)]);
+    }
+  }
+  out.push(pts[n - 1]); return out;
+};
+// 按弧长等距重采样（让噪声、飞白、行波的频率与笔画长短无关）
+K.resample = (pts, step = 4) => {
+  const out = [pts[0]]; let acc = 0;
+  for (let i = 1; i < pts.length; i++) { const a = pts[i - 1], b = pts[i], L = Math.hypot(b[0] - a[0], b[1] - a[1]); let d = step - acc;
+    while (d <= L) { const q = d / L; out.push([a[0] + (b[0] - a[0]) * q, a[1] + (b[1] - a[1]) * q]); d += step; } acc = L - (d - step); }
+  out.push(pts[pts.length - 1]); return out;
+};
+// 可变线宽路径：点列两侧按 w(q) 偏移成闭合多边形（书法线、飘带、表现主义长笔）
+K.ribbon = (pts, w) => {
+  const n = pts.length, L = [], R = [];
+  for (let i = 0; i < n; i++) {
+    const a = pts[Math.max(0, i - 1)], b = pts[Math.min(n - 1, i + 1)];
+    let dx = b[0] - a[0], dy = b[1] - a[1]; const d = Math.hypot(dx, dy) || 1; dx /= d; dy /= d;
+    const hw = (typeof w === 'function' ? w(i / (n - 1), i) : w) / 2;
+    L.push([pts[i][0] - dy * hw, pts[i][1] + dx * hw]); R.push([pts[i][0] + dy * hw, pts[i][1] - dx * hw]);
+  }
+  const p = new Path2D(); L.forEach((q, i) => i ? p.lineTo(q[0], q[1]) : p.moveTo(q[0], q[1]));
+  for (let i = n - 1; i >= 0; i--) p.lineTo(R[i][0], R[i][1]); p.closePath(); return p;
+};
+// 少女部件按画序列出（远→近），给「不调 drawGirl、自己逐部件上色」的风格用
+K.girlOrder = ['farSleeve', 'farHand', 'farCuff', 'hairDown', 'skirt', 'shoe', 'torso', 'neck', 'hairBack', 'bun', 'face', 'bangs', 'upperArm', 'foreArm', 'cuff', 'hand'];   // 完整画序（含五官、杯、钩子插槽名）见 RIG.GIRL_ORDER
+
+// 把 src 按「水平条带位移」画到 dst：fx(y) 返回该行的 x 位移（蒙克式整个世界在流动）
+// margin：每行横向多拉伸 2·margin 像素，位移后左右不露缝（margin ≥ 最大位移）
+K.warpRows = (dst, src, fx, band = 6, margin = 0) => {
+  for (let y = 0; y < H; y += band) { const dx = fx(y + band / 2); dst.drawImage(src, 0, y, W, band, dx - margin, y, W + 2 * margin, band); }
+};
+K.warpCols = (dst, src, fy, band = 6, margin = 0) => {
+  for (let x = 0; x < W; x += band) { const dy = fy(x + band / 2); dst.drawImage(src, x, 0, band, H, x, dy - margin, band, H + 2 * margin); }
+};
+
+// n 角星（剪纸星、爆炸框、闪光）：外半径 r0、内半径 r1
+K.star = (cx, cy, r0, r1, n, rot = 0) => { const pts = []; for (let i = 0; i < n * 2; i++) { const a = rot + i / (n * 2) * Math.PI * 2 - Math.PI / 2, r = i % 2 ? r1 : r0; pts.push([cx + Math.cos(a) * r, cy + Math.sin(a) * r]); } return U.poly(pts); };
+// 手绘不规则圆（草间的点不是完美圆）：n 个顶点、半径按种子起伏
+K.blob = (c, x, y, r, seed, wob = 0.08, n = 14) => {
+  const rr = rng(seed); const off = []; for (let i = 0; i < n; i++) off.push(1 + (rr() - .5) * 2 * wob);
+  const pts = []; for (let i = 0; i < n; i++) { const a = i / n * Math.PI * 2; pts.push([x + Math.cos(a) * r * off[i], y + Math.sin(a) * r * off[i]]); }
+  c.moveTo((pts[0][0] + pts[n - 1][0]) / 2, (pts[0][1] + pts[n - 1][1]) / 2);
+  for (let i = 0; i < n; i++) { const p = pts[i], q = pts[(i + 1) % n]; c.quadraticCurveTo(p[0], p[1], (p[0] + q[0]) / 2, (p[1] + q[1]) / 2); }
+  c.closePath();
+};
+
+// 全片连续的编舞：端杯按全局时间走（周期 = 两段 = 2.34s，在嘴边和桌上各停一会儿），
+// 换风格时姿势不重置——速通看的是「同一瞬间换了画风」，而不是每段重喝一次。转场正好落在杯子停住的时刻。
+K.choreo = (lt, t) => {
+  const ch = PAINT.choreo(lt, t), k = 0.5 - 0.5 * Math.cos(2 * Math.PI * t / 2.34375);
+  let q = clamp((k - 0.15) / 0.7); q = q * q * (3 - 2 * q);
+  ch.cup = q; ch.sip = Math.max(0, Math.sin(t * 6)) * 0.15 * q; return ch;
+};
+// drawGirl(mode:'line') 会把被近侧手臂挡住的躯干线画穿：线稿画完后，把近侧手臂、袖口、手、杯重新盖一遍
+K.nearArm = (c, G, { fill, line = '#111', lw = 3, skin, cuff, cupBody, cupRim, pattern } = {}) => {
+  const arm = new Path2D(); arm.addPath(G.upperArm); arm.addPath(G.foreArm);
+  c.save(); c.lineJoin = 'round'; c.fillStyle = fill; c.fill(arm); if (pattern) { c.save(); c.clip(arm); pattern(c); c.restore(); }
+  c.strokeStyle = line; c.lineWidth = lw; c.stroke(G.upperArm); c.stroke(G.foreArm);
+  if (cuff) { c.fillStyle = cuff; c.fill(G.cuff); c.stroke(G.cuff); }
+  c.fillStyle = skin; c.fill(G.hand); c.lineWidth = lw * 0.8; c.stroke(G.hand);
+  RIG.drawCup(c, G.cup, { body: cupBody, rim: cupRim, line, lw: lw * 0.8, hw: 7 });
+  c.fillStyle = skin; c.beginPath(); c.arc(G.thumb[0], G.thumb[1], 7, 0, Math.PI * 2); c.fill(); c.lineWidth = lw * 0.7; c.stroke();
+  c.restore();
+};
+// 右上角角标：标题（中文）＋副标题；入场 0.18s 由各风格的 reveal(c,p) 决定怎么出现
+K.label = (c, { title, sub, tFont, sFont, tCol, sCol, x = 1866, y = 128, sy = 182, shadow, before, after, spacing = 0 }) => {
+  c.save(); c.textAlign = 'right'; c.textBaseline = 'alphabetic';
+  if (before) before(c);
+  if (shadow) { c.shadowColor = shadow.color; c.shadowOffsetX = shadow.x || 0; c.shadowOffsetY = shadow.y || 0; c.shadowBlur = shadow.blur || 0; }
+  c.font = tFont; c.fillStyle = tCol; if (spacing) c.letterSpacing = spacing + 'px'; c.fillText(title, x, y); c.letterSpacing = '0px';
+  if (sub) { c.font = sFont; c.fillStyle = sCol || tCol; c.fillText(sub, x, sy); }
+  if (after) after(c);
+  c.restore();
+};
+})();

package/engine/lib/media.js

@@ -0,0 +1,118 @@
+// 真实素材 MD：把截图、照片、录像帧放进画面当主体。解说片里有真实素材就让它满幅当主画面，代码负责解释、标注和运镜。
+// 出处：两支被认可的片子——一支把照片满幅铺开、口播点到细节时推近（cover），一支把照片冲印成带白边的件摆在调查桌上、配黑底撕边标签。
+// 满幅一镜一张图时，镜头唯一能做的就是往里推，整片很容易变成一镜一推：只在那一处在当前景别读不清时才推，实拍录像本身在动就停住；
+// 要在几件素材之间走，把它们摆进同一张世界画布（MD.print 调查桌）用横移，见 references/镜头语言.md「真实素材满幅时」。
+// 约定：素材缺失一律报错（throw → render.py / qa.py 判失败），不静默画空白；所有参数由调用方用时间算好传进来，本库不读时钟。
+//
+//   MD.size(src)                                  素材的像素尺寸 [w, h]（图片 / 视频帧 / canvas 都行）；缺失或没加载完 → throw
+//   MD.cover(c, src, o) → geo                     满幅铺开：等比放大到盖满框（裁掉多出的边），按焦点裁、按 z 推近
+//       o = { x=0, y=0, w=画宽, h=画高（框）, fx=.5, fy=.5（焦点，0..1 相对素材：裁切和推近都绕它）, z=1（推近倍数，≥1）,
+//             crop:[sx,sy,sw,sh]（先取素材的这一块，0..1）, fit:'cover'|'contain'（contain = 整张放进框里、不裁，留边）, clip=true }
+//       返回 geo = { x, y, w, h（素材在画面上的矩形）, s（缩放）, box }，配 MD.toScreen 把素材上的点/框换算到画面
+//   MD.toScreen(geo, r)                           素材上 0..1 的点 [u,v] 或框 [u,v,w,h] → 画面坐标（[x,y] 或 {x,y,w,h}）
+//   MD.focusFor(rect) → {fx, fy}                  框 [u,v,w,h] 的中心当焦点
+//   MD.zoomFor(rect, iw, ih, bw, bh, fill=.6, fit='cover') → z    要让素材上的框 rect 占框宽/高的 fill，cover 之上还要推几倍（≥1）
+//   MD.print(c, src, w, h, o)                     冲印件：白边＋旧纸色＋投影＋胶带，原点在冲印件中心（调用方先 translate/rotate）
+//       o = { border=16·u, crop, fx, fy（按焦点 cover 进 w×h）, tape=true, caption（白边下方小字）, polaroid=false（底边加宽、caption 写在底边里）,
+//             shadow=true, key（给了 key 且素材是静态图就缓存成位图）}
+//   MD.label(c, text, x, y, o)                    黑底撕边标签：o = { size=48·u, maxW(限宽，超了先缩后截断), fam='PuHui-Heavy', bg='#191817', fg='#f3efe6', align='left'|'center'|'right',
+//             t, at（at 这一帧出现：先 1.12 倍一拍再落定，字按 rate 字/秒、12fps 打出；不给 t 就直接画完整的）, rate=14, r（旋转）}
+//       返回 {w, h}
+//   MD.frameAt(frames, lt, fps=30, loop=false)    帧序列（图片数组）在片内时间 lt 的那一帧；缺帧 → throw
+(() => {
+let W = 1920, H = 1080; U.onStage((w, h) => { W = w; H = h; });   // 画布尺寸跟 U.setStage 走（默认 1920×1080）
+const { clamp } = U;
+const MD = window.MD = {};
+const u0 = () => Math.min(W, H) / 1080;
+
+MD.size = src => {
+  if (!src) throw new Error('MD：素材缺失（图片没加载或路径写错）——不画空白帧');
+  const w = src.videoWidth || src.naturalWidth || src.width, h = src.videoHeight || src.naturalHeight || src.height;
+  if (!(w > 0 && h > 0)) throw new Error(`MD：素材尺寸是 0（还没加载完或解不开）：${src.src || src.currentSrc || src}`);
+  return [w, h];
+};
+
+MD.cover = (c, src, o = {}) => {
+  const [iw0, ih0] = MD.size(src);
+  const bx = o.x ?? 0, by = o.y ?? 0, bw = o.w ?? W, bh = o.h ?? H, fx = o.fx ?? 0.5, fy = o.fy ?? 0.5, z = Math.max(1e-3, o.z ?? 1);
+  const cr = o.crop || [0, 0, 1, 1], sx = cr[0] * iw0, sy = cr[1] * ih0, iw = cr[2] * iw0, ih = cr[3] * ih0;
+  const s0 = (o.fit === 'contain' ? Math.min : Math.max)(bw / iw, bh / ih), s = s0 * z, w = iw * s, h = ih * s;
+  // 焦点：cover 时让焦点尽量落在框的同一相对位置（不露边）；推近绕焦点
+  const ax = bx + bw * fx, ay = by + bh * fy;
+  let x = ax - w * fx, y = ay - h * fy;
+  if (o.fit !== 'contain') { x = Math.min(bx, Math.max(bx + bw - w, x)); y = Math.min(by, Math.max(by + bh - h, y)); }
+  else if (z <= 1) { x = bx + (bw - w) / 2; y = by + (bh - h) / 2; }
+  c.save();
+  if (o.clip !== false) { c.beginPath(); c.rect(bx, by, bw, bh); c.clip(); }
+  c.drawImage(src, sx, sy, iw, ih, x, y, w, h);
+  c.restore();
+  return { x, y, w, h, s, box: { x: bx, y: by, w: bw, h: bh } };
+};
+
+MD.toScreen = (geo, r) => r.length === 2 ? [geo.x + r[0] * geo.w, geo.y + r[1] * geo.h]
+  : { x: geo.x + r[0] * geo.w, y: geo.y + r[1] * geo.h, w: r[2] * geo.w, h: r[3] * geo.h };
+MD.focusFor = r => ({ fx: r[0] + r[2] / 2, fy: r[1] + r[3] / 2 });
+MD.zoomFor = (rect, iw, ih, bw = W, bh = H, fill = 0.6, fit = 'cover') => {
+  const s0 = (fit === 'contain' ? Math.min : Math.max)(bw / iw, bh / ih), rw = rect[2] * iw * s0, rh = rect[3] * ih * s0;
+  return Math.max(1, Math.min(bw * fill / rw, bh * fill / rh));
+};
+
+const printCache = {};
+MD.print = (c, src, w, h, o = {}) => {
+  const u = u0(), b = o.border ?? 16 * u, bot = o.polaroid ? Math.max(b * 4, h * 0.2) : b, PW = w + 2 * b, PH = h + b + bot;
+  const paint = g => {
+    g.fillStyle = '#f7f5ef'; g.fillRect(0, 0, PW, PH);
+    const f = o.crop ? null : MD.focusFor([o.fx ?? 0.5, o.fy ?? 0.5, 0, 0]);
+    MD.cover(g, src, { x: b, y: b, w, h, crop: o.crop, fx: f ? f.fx : 0.5, fy: f ? f.fy : 0.5 });
+    g.save(); g.globalCompositeOperation = 'multiply'; g.fillStyle = 'rgba(214,205,185,.16)'; g.fillRect(0, 0, PW, PH); g.restore();   // 印在纸上：压一层旧纸色
+    if (o.polaroid && o.caption) { g.save(); g.fillStyle = '#2b2925'; g.font = `${Math.min(bot * 0.42, 40 * u)}px "LXGWWenKai-500", "PuHui-Medium"`; g.textBaseline = 'middle'; g.fillText(o.caption, b * 1.2, b + h + bot / 2); g.restore(); }
+  };
+  MD.size(src);
+  let sp;
+  if (o.key && !(src instanceof HTMLVideoElement)) { const k = `${o.key}|${Math.round(PW)}x${Math.round(PH)}`; sp = printCache[k] || (printCache[k] = (() => { const cv = document.createElement('canvas'); cv.width = Math.ceil(PW); cv.height = Math.ceil(PH); paint(cv.getContext('2d')); return cv; })()); }
+  c.save();
+  if (o.shadow !== false) { c.shadowColor = 'rgba(30,22,10,.32)'; c.shadowBlur = 14 * u; c.shadowOffsetX = 3 * u; c.shadowOffsetY = 8 * u; }
+  if (sp) c.drawImage(sp, -PW / 2, -PH / 2);
+  else { c.translate(-PW / 2, -PH / 2); c.fillStyle = '#f7f5ef'; c.fillRect(0, 0, PW, PH); c.shadowColor = 'transparent'; paint(c); }
+  c.restore();
+  if (o.tape !== false && window.CL) { CL.tape(c, -w / 2 + 30 * u, -PH / 2 + 6 * u, -0.6, 110 * u); CL.tape(c, w / 2 - 30 * u, -PH / 2 + 6 * u, 0.55, 110 * u); }
+  if (o.caption && !o.polaroid) { c.save(); c.font = `${22 * u}px "PuHui-Medium"`; c.fillStyle = 'rgba(40,36,30,.78)'; c.textBaseline = 'top'; c.fillText(o.caption, -PW / 2, PH / 2 + 10 * u); c.restore(); }
+  return { w: PW, h: PH };
+};
+
+const labCache = {};
+MD.label = (c, text, x, y, o = {}) => {
+  text = String(text ?? ''); if (!text) return { w: 0, h: 0 };
+  const u = u0(), fam = o.fam || 'PuHui-Heavy', bg = o.bg || '#191817', fg = o.fg || '#f3efe6';
+  let size = o.size ?? 48 * u;
+  if (o.t != null && o.at != null && o.t < o.at) return { w: 0, h: 0 };
+  c.save(); c.font = `${size}px "${fam}"`;
+  if (o.maxW) {                                  // 限宽：先把字缩到 62% 为止，还放不下就截断加「…」，标签不许比画面宽
+    const full = c.measureText(text).width + size * 0.84;
+    if (full > o.maxW) { size = Math.max(size * 0.62, size * o.maxW / full); c.font = `${size}px "${fam}"`;
+      const cs = [...text]; while (cs.length > 1 && c.measureText(cs.join('')).width + size * 0.84 > o.maxW) cs.pop();
+      if (cs.length < [...text].length) text = cs.join('').trimEnd() + '…'; }
+  }
+  const tw = c.measureText(text).width, padX = size * 0.42, w = Math.round(tw + padX * 2), h = Math.round(size * 1.5);
+  const key = `${text}|${size}|${fam}|${bg}`;
+  const sp = labCache[key] || (labCache[key] = (() => { const cv = document.createElement('canvas'); cv.width = w; cv.height = h; const g = cv.getContext('2d');
+    if (window.CL) CL.tornRect(g, w, h, [...text].length * 7 + Math.round(size), 3 * u); else { g.beginPath(); g.rect(0, 0, w, h); }
+    g.fillStyle = bg; g.fill(); return cv; })());
+  const k = o.t != null && o.at != null ? MO.step(o.t - o.at + 1e-6, 12) : 1e9;     // 一拍二：从 at 起算，at 这一帧就是第一帧
+  const pop = k < 1 / 12 ? 1.12 : 1, ox = o.align === 'center' ? -w / 2 : o.align === 'right' ? -w : 0;
+  c.translate(x, y); if (o.r) c.rotate(o.r); c.scale(pop, pop);
+  c.drawImage(sp, ox, -h / 2);
+  const n = o.t != null && o.at != null ? Math.ceil((k + 1 / 12) * (o.rate || 14)) : 1e9;
+  c.fillStyle = fg; c.textBaseline = 'middle'; c.textAlign = 'left';
+  c.fillText([...text].slice(0, n).join(''), ox + padX, size * 0.04);
+  c.restore();
+  return { w, h };
+};
+
+MD.frameAt = (frames, lt, fps = 30, loop = false) => {
+  if (!frames || !frames.length) throw new Error('MD.frameAt：帧序列是空的');
+  let i = Math.floor(Math.max(0, lt) * fps + 1e-6);
+  i = loop ? i % frames.length : Math.min(frames.length - 1, i);
+  const im = frames[i]; MD.size(im); return im;
+};
+})();