dsh-drawai 0.3.4 → 0.4.1

package/lib/motion/mgstyles/upstream/prompts/20-pixel.md

@@ -0,0 +1,96 @@
+# 像素风 Pixel Art / 8-bit
+
+**原片**：PIXEL QUEST 像素冒险 · 1920×1080 · 30 fps · 10 秒 · AI 评审终评 8.07 / 10
+
+**源码**：[demos/20-pixel/](../demos/20-pixel/)
+
+## 怎么用
+
+1. 新建一个空文件夹，在里面打开一个能写代码、能执行命令的 AI 助手（例如 Claude Code）。本机需要能跑网页渲染（Node + Chrome）和 ffmpeg。
+2. 把下面「提示词」整段复制进去发送。
+3. 想换成自己的内容：改 `Creative seed` 里的故事、品牌名、文案和配色，或者改 `Output` 里的尺寸（比如竖屏 1080×1920）。不要删 `Signature features` 那一段，它是这种风格被一眼认出来的依据。
+4. 想再提高：成片出来后，另开一个 AI 用 [rubric.md](../rubric.md) 评审，把评审意见贴回给制作的 AI 再改一轮。原片就是这样改了两轮。
+
+## 提示词
+
+```text
+You are the director, motion designer, engineer and sound designer of ONE 10-second motion-design film.
+The goal is the most classic, yet most stunning form of this style — award-shortlist / high-end commercial quality. A clean,
+template-looking result is a fail. Benchmarks: Buck, ManvsMachine, Ordinary Folk, Giant Ant, Territory Studio, Apple keynote
+motion, Pentagram motion identities, top Behance/Motionographer features, top 抖音/B站 designer accounts.
+
+# Style
+像素风 Pixel Art / 8-bit
+
+# Output (fixed)
+- 1920×1080, 30 fps, exactly 10.000 s (300 frames), H.264 MP4 with stereo AAC audio (48 kHz), mastered to −14 LUFS
+  integrated, true peak ≤ −1 dBTP. Final file: video.mp4.
+
+# Suggested technical route
+HTML Canvas at 320×180 internal resolution, integer-scaled ×6 with nearest-neighbour; sprites authored as pixel arrays in code; limited palette
+(You may choose a better route if it clearly raises quality; say why.)
+
+# Creative seed
+「像素冒险 PIXEL QUEST」A retro side-scroller title/attract sequence.
+- Internal 320×180, ×6 nearest-neighbour; limited palette (PICO-8-like 16–32 colours) with dithered sky gradient; 3–4 parallax layers (sky, far mountains, mid forest/city, near ground tiles) moving by whole pixels.
+- Hero sprite (hand-authored 16×16–24×24, 6–8 frame run cycle at ~10–12 fps) runs, jumps, collects coins (sparkle), bops a slime; the palette shifts day → sunset; a treasure chest opens with a light burst.
+- Dialogue box with pixel CJK font typing 「欢迎来到像素世界！」; chunky pixel logo "PIXEL QUEST" drops in with shine sweep; optional CRT pass (scanlines, slight barrel, phosphor glow) that doesn't blur pixels into mush.
+- Strictly: nearest-neighbour, integer pixel positions, stepped timing (no smooth easing on sprites).
+Sound: chiptune (pulse lead, triangle bass, noise drums) + jump/coin/chest SFX.
+
+You are the director: you may change the concept, copy, story beats and brand names if you find a stronger idea, but the result must remain the CANONICAL, instantly-recognisable form of this style and must hit its signature features below.
+
+# Signature features and key techniques (the result is judged against these)
+低分辨率大颗粒像素 + 有限色板 + 低帧率精灵动画的复古游戏美学，在 B 站游戏区（MC、泰拉瑞亚、独立游戏）、8-bit 音乐 MV 和品牌怀旧营销中常见；Aseprite 教程在 B 站有 10 万+ 播放的稳定学习生态。
+视觉特征 大颗粒像素与硬边缘, 有限色板(8~32色), 8~12fps 精灵帧动画, 抖动渐变 dithering, CRT 扫描线滤镜
+关键技法 Aseprite 绘制精灵表（sprite sheet）+ 序列帧循环（走路 6~8 帧、呼吸 2~4 帧）
+缩放必须最近邻插值（CSS image-rendering: pixelated），杜绝抗锯齿糊边
+动画用 steps() 阶梯时序而非平滑缓动，保持逐帧感
+视差卷轴背景：远中近三层不同速度整像素平移
+可选 CRT 后处理：扫描线+桶形畸变+磷光辉光
+
+# How to work
+1. Treatment. Write down one clear idea: a hook in the first 0.5 s (never open on more than 0.3 s of empty or black), an
+   escalation, one unmistakable hero moment at ~60–75 % of the runtime, and a composed end frame held ~0.8–1.2 s with living
+   micro-motion. Map every signature feature above to a moment. Keep one cue sheet (beats and hit times) that both the
+   picture and the sound read from.
+2. Key frames before motion. Build the look, render stills at 6–10 key times and actually look at them. Each still should be
+   poster-worthy: composition, hierarchy, negative space, type set properly (kerning, line-height, weight contrast, CJK
+   punctuation, ~5 % safe margins). Iterate until nothing looks default, generic, cramped or "AI-template".
+3. Motion. Build the choreography and preview at low resolution. Step through the fastest moves frame by frame: spacing,
+   easing, arcs, overlap, anticipation and follow-through, motion blur. No unintended dead spans; the energy follows the music.
+4. Sound. Write genre-correct music and sound design locked to the cue sheet. Check that visual hits land on audio onsets.
+   Master to the output spec.
+5. Final. Render at full resolution (motion blur where apt), then check: exactly 10.00 s, resolution, fps, audio present and at
+   the right loudness, no black frames, no fallback fonts or tofu, no clipped elements at the frame edges, no shimmer on thin
+   lines, no gradient banding. Fix and repeat until you would submit it to a festival.
+6. Write an honest self-critique: what is strongest, what is weakest, what you would do with more time.
+
+# Rules
+- Rendering must be deterministic: every frame is a pure function of time t. Seeded randomness only; physics and particles
+  precomputed or closed-form; no real-time clocks; no state-triggered CSS transitions. A reliable route: a web page that can
+  draw any time t on request, captured frame by frame with a headless browser and encoded with ffmpeg (or a Blender script
+  that renders a PNG sequence).
+- Assets: only CC0 / public domain / OFL / Apache / free-for-commercial-use. Record each source and licence in CREDITS.md.
+  No real brand trademarks; invent brand names.
+- On-screen text must be correct and natural: idiomatic Chinese, proper CJK punctuation, no typos.
+
+# Craft checklist (what a jury looks for)
+- Style authenticity: an expert names the style in one second; every signature technique is present and executed correctly.
+- Motion craft: purposeful easing (no linear unless mechanical by design), overlap and stagger, anticipation and
+  follow-through, arcs, squash and stretch where the style allows, consistent physics, motion blur where apt; transitions
+  carried by elements, not crossfades.
+- Rhythm: hits locked to the music; contrast between busy and calm; no monotony.
+- Design: strong composition, grid, typographic hierarchy, controlled palette; texture and finishing (grain, glow, vignette)
+  only where the style wants it; nothing looks accidental.
+- Technical polish: no jitter (unless intended), no popping, no aliasing, no banding, no fallback fonts, no half-loaded images.
+- Sound: genre-correct, musical, synced, mastered.
+
+# Before you deliver, score yourself honestly
+1–10 on style fidelity, concept wow, motion craft, design & typography, finish & texture, sound & sync, technical
+(6 = template-level, 8 = high-end agency, 9 = award shortlist). Aim for 9; fix whatever scores lowest first.
+
+# Deliver
+video.mp4, plus a short report: the concept in two sentences; a beat sheet with timecodes; how each signature feature is
+realised; the tech route; check numbers (duration, resolution, fps, loudness, true peak); your honest top-3 weaknesses.
+```

package/lib/motion/mgstyles/upstream/prompts/22-hud.md

@@ -0,0 +1,95 @@
+# 赛博朋克 HUD / FUI Cyberpunk HUD / FUI (Fictional UI)
+
+**原片**：隼眼-9 · 目标锁定 KESTREL-9 TARGET ACQUIRED · 1920×1080 · 30 fps · 10 秒 · AI 评审终评 7.93 / 10
+
+**源码**：[demos/22-hud/](../demos/22-hud/)
+
+## 怎么用
+
+1. 新建一个空文件夹，在里面打开一个能写代码、能执行命令的 AI 助手（例如 Claude Code）。本机需要能跑网页渲染（Node + Chrome）和 ffmpeg。
+2. 把下面「提示词」整段复制进去发送。
+3. 想换成自己的内容：改 `Creative seed` 里的故事、品牌名、文案和配色，或者改 `Output` 里的尺寸（比如竖屏 1080×1920）。不要删 `Signature features` 那一段，它是这种风格被一眼认出来的依据。
+4. 想再提高：成片出来后，另开一个 AI 用 [rubric.md](../rubric.md) 评审，把评审意见贴回给制作的 AI 再改一轮。原片就是这样改了两轮。
+
+## 提示词
+
+```text
+You are the director, motion designer, engineer and sound designer of ONE 10-second motion-design film.
+The goal is the most classic, yet most stunning form of this style — award-shortlist / high-end commercial quality. A clean,
+template-looking result is a fail. Benchmarks: Buck, ManvsMachine, Ordinary Folk, Giant Ant, Territory Studio, Apple keynote
+motion, Pentagram motion identities, top Behance/Motionographer features, top 抖音/B站 designer accounts.
+
+# Style
+赛博朋克 HUD / FUI Cyberpunk HUD / FUI (Fictional UI)
+
+# Output (fixed)
+- 1920×1080, 30 fps, exactly 10.000 s (300 frames), H.264 MP4 with stereo AAC audio (48 kHz), mastered to −14 LUFS
+  integrated, true peak ≤ −1 dBTP. Final file: video.mp4.
+
+# Suggested technical route
+HTML: SVG/Canvas FUI layers + Three.js wireframe hologram; seeded random data; glow/scanline post pass
+(You may choose a better route if it clearly raises quality; say why.)
+
+# Creative seed
+「目标锁定 TARGET ACQUIRED」Cyberpunk HUD / FUI, film-UI grade (Territory Studio-level density & restraint).
+- Deep teal-black; cyan #00E5FF linework with orange/red #FF6A00 alert state; hex grid, concentric rotating rings with ticks, radar sweep (conic) with blips, data columns (monospace numbers rolling 3–5 frames then settling), typewriter status lines with cursor, sparkline graphs, a central Three.js wireframe hologram (globe or drone) with scanlines.
+- Layered build-up: lines draw on in hierarchical staggered order → data comes alive → a target is found → lock brackets snap 1.4 → 1.0 (fast-out slow-in) → everything flips to alert orange with 'TARGET LOCKED / 目标锁定', coordinates "N31°14′ E121°29′".
+- Glow, slight chromatic aberration, scanlines, restrained micro-glitches.
+Sound: darksynth pulse + HUD beeps, scan sweeps, ascending lock-on tone, alarm on lock.
+
+You are the director: you may change the concept, copy, story beats and brand names if you find a stronger idea, but the result must remain the CANONICAL, instantly-recognisable form of this style and must hit its signature features below.
+
+# Signature features and key techniques (the result is judged against these)
+模拟科幻电影/游戏界面的抬头显示包装：青橙霓虹线框、目标锁定框、雷达扫描、数据流小字。在科技数码测评、游戏剪辑（赛博朋克2077、EVA 二创）、军事航天科普和 AI 产品演示中作为『科技感』的默认皮肤，B 站 AE HUD 案例教程播放量达 20 万。
+视觉特征 青色/橙色霓虹线框, 目标锁定框与十字准星, 雷达/环形扫描 loop, 等宽小字数据流与打字机文字, 六边形网格与辉光
+关键技法 线框生长：SVG stroke-dasharray/dashoffset 描边动画，元素按层级错帧展开
+环形雷达：conic-gradient 扫描扇区旋转 loop + 目标点闪烁
+数字滚动：随机数快速跳变 3~5 帧后落定真实值；文字打字机 + 光标闪烁
+锁定框：四角括号从大到小收缩吸附目标（scale 1.4→1.0 + 快出缓入）
+全局外发光（glow）+ 轻微色差 + 扫描线叠加统一质感
+
+# How to work
+1. Treatment. Write down one clear idea: a hook in the first 0.5 s (never open on more than 0.3 s of empty or black), an
+   escalation, one unmistakable hero moment at ~60–75 % of the runtime, and a composed end frame held ~0.8–1.2 s with living
+   micro-motion. Map every signature feature above to a moment. Keep one cue sheet (beats and hit times) that both the
+   picture and the sound read from.
+2. Key frames before motion. Build the look, render stills at 6–10 key times and actually look at them. Each still should be
+   poster-worthy: composition, hierarchy, negative space, type set properly (kerning, line-height, weight contrast, CJK
+   punctuation, ~5 % safe margins). Iterate until nothing looks default, generic, cramped or "AI-template".
+3. Motion. Build the choreography and preview at low resolution. Step through the fastest moves frame by frame: spacing,
+   easing, arcs, overlap, anticipation and follow-through, motion blur. No unintended dead spans; the energy follows the music.
+4. Sound. Write genre-correct music and sound design locked to the cue sheet. Check that visual hits land on audio onsets.
+   Master to the output spec.
+5. Final. Render at full resolution (motion blur where apt), then check: exactly 10.00 s, resolution, fps, audio present and at
+   the right loudness, no black frames, no fallback fonts or tofu, no clipped elements at the frame edges, no shimmer on thin
+   lines, no gradient banding. Fix and repeat until you would submit it to a festival.
+6. Write an honest self-critique: what is strongest, what is weakest, what you would do with more time.
+
+# Rules
+- Rendering must be deterministic: every frame is a pure function of time t. Seeded randomness only; physics and particles
+  precomputed or closed-form; no real-time clocks; no state-triggered CSS transitions. A reliable route: a web page that can
+  draw any time t on request, captured frame by frame with a headless browser and encoded with ffmpeg (or a Blender script
+  that renders a PNG sequence).
+- Assets: only CC0 / public domain / OFL / Apache / free-for-commercial-use. Record each source and licence in CREDITS.md.
+  No real brand trademarks; invent brand names.
+- On-screen text must be correct and natural: idiomatic Chinese, proper CJK punctuation, no typos.
+
+# Craft checklist (what a jury looks for)
+- Style authenticity: an expert names the style in one second; every signature technique is present and executed correctly.
+- Motion craft: purposeful easing (no linear unless mechanical by design), overlap and stagger, anticipation and
+  follow-through, arcs, squash and stretch where the style allows, consistent physics, motion blur where apt; transitions
+  carried by elements, not crossfades.
+- Rhythm: hits locked to the music; contrast between busy and calm; no monotony.
+- Design: strong composition, grid, typographic hierarchy, controlled palette; texture and finishing (grain, glow, vignette)
+  only where the style wants it; nothing looks accidental.
+- Technical polish: no jitter (unless intended), no popping, no aliasing, no banding, no fallback fonts, no half-loaded images.
+- Sound: genre-correct, musical, synced, mastered.
+
+# Before you deliver, score yourself honestly
+1–10 on style fidelity, concept wow, motion craft, design & typography, finish & texture, sound & sync, technical
+(6 = template-level, 8 = high-end agency, 9 = award shortlist). Aim for 9; fix whatever scores lowest first.
+
+# Deliver
+video.mp4, plus a short report: the concept in two sentences; a beat sheet with timecodes; how each signature feature is
+realised; the tech route; check numbers (duration, resolution, fps, loudness, true peak); your honest top-3 weaknesses.
+```

package/lib/motion/mgstyles/upstream/rubric.md

@@ -0,0 +1,51 @@
+# 评审提示词：让另一个 AI 当评委，再拿评审意见改一轮
+
+原片都是这样迭代出来的：制作 → 独立评审 → 按评审修改 → 再评审。下面两段提示词可以直接用。
+
+## 第一步：评审（另开一个 AI 会话，把成片路径告诉它）
+
+```text
+You are a senior motion-design jury member (think: Motionographer editor, Buck/ManvsMachine creative director, a 抖音/B站
+top design-account lead for the Chinese styles). You did NOT make this film. Judge it harshly and precisely so it can reach
+award-level / high-end commercial quality. Kindness is useless here; specificity is everything.
+
+The film: <path to video.mp4>. The prompt it was made from: <paste the style prompt, or at least its Style, Output and
+Signature features sections>.
+
+1. Look at the film properly: extract a contact sheet (a frame every 0.5 s), filmstrips around the fastest and most
+   important moves and the hero moment, and full-resolution frames at 5–8 key times. Look at small details at full
+   resolution: edges, type setting, aliasing, banding, texture, clipping.
+2. Check the spec: exactly 10.00 s, resolution and fps as specified, audio present, loudness ≈ −14 LUFS (±1), true peak
+   ≤ −1 dBTP, no black frames except intended, no unintended static spans, visual hits aligned with audio onsets.
+3. Score 1–10 on each dimension (5 = competent student work; 6 = decent template level; 7 = solid professional; 8 = high-end
+   agency work; 9 = award shortlist; 10 = best in the world). Most first renders deserve 5–7. Do not inflate.
+   - style_fidelity: instantly recognisable canonical form; every signature feature and technique present and correct
+   - concept_wow: a clear idea, a hook in the first 0.5 s, an unmistakable hero moment, a satisfying end frame
+   - motion_craft: easing, spacing, overlap, anticipation and follow-through, arcs, transitions, motion blur; no dead or
+     jittery motion
+   - design_typography: composition, hierarchy, grid, type setting (CJK too), palette, negative space
+   - finish_texture: lighting, texture, grain, glow and detail appropriate to the style; no banding, aliasing or artifacts
+   - sound_sync: musicality, genre-correctness, sound design, sync to picture, mix and master
+   - technical: spec compliance, fonts loaded, no glitches, clipping or popping
+4. Give 5–10 fixes ordered by impact on the final impression. Each: timecode(s), what is wrong (observable), why it matters,
+   and a concrete how-to (technique and numbers: easing curve, frame counts, px, colours, font, layout change). Prefer a few
+   big upgrades over many nitpicks. At least one fix must raise the wow factor, not just polish.
+5. Flag as critical: anything that reads as generic or AI-template, unnatural Chinese copy, fallback fonts or tofu, and any
+   spec failure.
+Return: the score table, the critical issues, and the fix list.
+```
+
+## 第二步：修改（回到制作的那个 AI 会话，把评审结果贴进去）
+
+```text
+An independent jury reviewed your film. Here is the full review:
+<paste the review>
+
+Raise the film to award level (target ≥ 9 in every dimension):
+- First keep a copy of the current video and source as version N.
+- Implement every critical issue and every high-impact fix. You may substitute a better solution for a listed fix if you are
+  confident; say why. Go beyond the list where you see a bigger upgrade, especially for the wow factor. Do not regress
+  anything the jury listed as a strength.
+- Re-render at full resolution, re-check the spec and look at the frames until the fixes have truly landed.
+- Report which fixes you applied or skipped, and why.
+```

package/lib/motion/mgstyles/upstream/template.md

@@ -0,0 +1,36 @@
+# 写一种新风格的提示词
+
+每份风格提示词都由「通用部分」和「风格专属部分」组成。通用部分（开头的角色设定，以及 How to work / Rules / Craft checklist /
+自评 / Deliver）所有风格都一样，可以直接从任意一份 `prompts/*.md` 里复制。要写一种新风格，只需要填下面四段：
+
+```text
+# Style
+<中文风格名 English style name>
+
+# Output (fixed)
+- <宽>×<高>, <帧率> fps, exactly 10.000 s, H.264 MP4 with stereo AAC audio (48 kHz), mastered to −14 LUFS integrated,
+  true peak ≤ −1 dBTP. Final file: video.mp4.
+
+# Suggested technical route
+<用什么做最合适：SVG/Canvas/WebGL/Three.js/Blender……以及关键实现手段。>
+(You may choose a better route if it clearly raises quality; say why.)
+
+# Creative seed
+<「一句话片名」+ 这种风格最经典又最惊艳的读法：
+ - 0–X s 发生什么（钩子 → 升级 → 高潮 → 结尾画面），
+ - 配色（3–6 个具体色值），字体气质，
+ - Sound: 音乐风格 + 关键音效。>
+
+You are the director: you may change the concept, copy, story beats and brand names if you find a stronger idea, but the
+result must remain the CANONICAL, instantly-recognisable form of this style and must hit its signature features below.
+
+# Signature features and key techniques (the result is judged against these)
+<这种风格的来源和用途（一两句）>
+视觉特征 <逗号分隔的标志特征>
+关键技法 <可执行的技法，越具体越好：曲线参数、帧数、层结构……每条一行>
+```
+
+写好的关键：
+- **Signature features 要可检验**。写「弹性缓动 overshoot 用 cubic-bezier(0.34,1.56,0.64,1)，错峰 2–4 帧」，而不是「动效要有弹性」。
+- **Creative seed 要有节拍**。按秒写出钩子、升级、高潮和结尾，AI 才不会做成平铺直叙的模板。
+- **品牌名和文案用虚构的**，避免商标问题。

package/lib/motion/pixelqa.js

@@ -0,0 +1,198 @@
+// 像素级画质检查：色带、抗锯齿、字体注册。
+//
+// 为什么要有：帧检（qa.js）看的是「有没有黑场 / 静止 / 越界」，回答不了
+// 「这张脸是不是糊的」。而画质退化的两种最典型形态恰好都在像素层面：
+//   1. 柔和渐变在 8bit 量化后裂成一级级的色带（淡紫底最容易中招）；
+//   2. 斜边没有抗锯齿，等轴场景的 30°/60° 边全成了台阶。
+// 两者都要 1:1 的像素才能判，所以这里直接从成片里抠原始灰度字节来算，
+// 不引入 sharp/jimp 之类的依赖（插件只有 ffmpeg）。
+
+import { existsSync, readFileSync, readdirSync } from 'node:fs'
+import { join, extname } from 'node:path'
+import { runFfmpeg } from './ffmpeg.js'
+
+const clampInt = (value, low, high) => Math.min(Math.max(Math.round(Number(value) || 0), low), high)
+
+async function rawGray({ source, work, time, crop, name, timeoutMs }) {
+  const out = join(work, name + '.raw')
+  const filter = 'crop=' + crop.w + ':' + crop.h + ':' + crop.x + ':' + crop.y + ',format=gray'
+  await runFfmpeg(['-ss', String(Math.max(0, time)), '-i', source, '-frames:v', '1', '-vf', filter, '-f', 'rawvideo', out],
+    { cwd: work, log: name + '.log', timeoutMs: timeoutMs || 120000 })
+  if (!existsSync(out)) throw new Error('取不到像素：' + name)
+  return readFileSync(out)
+}
+
+// 色带：把一行像素切成「等值段」，再看是否出现连续多段、每段都不短、
+// 且相邻段只差 1–2 级的「阶梯」。平涂色块是单段，真实渐变是长段少级差
+// （有抖动时会被打碎），只有量化后的渐变才会长成 8px 以上、连十几段的梯子。
+function staircase(row) {
+  const runs = []
+  for (let i = 0; i < row.length;) {
+    let end = i + 1
+    while (end < row.length && row[end] === row[i]) end += 1
+    runs.push({ value: row[i], length: end - i })
+    i = end
+  }
+  let longest = 0
+  let steps = 0
+  let current = 0
+  for (let index = 1; index < runs.length; index += 1) {
+    const previous = runs[index - 1]
+    const here = runs[index]
+    const delta = Math.abs(here.value - previous.value)
+    const flatEnough = previous.length >= 6 && previous.length <= 400 && here.length >= 6 && here.length <= 400
+    if (delta >= 1 && delta <= 2 && flatEnough) {
+      current = current ? current + 1 : 2
+      longest = Math.max(longest, current)
+      steps += 1
+    } else current = 0
+  }
+  return { longest, steps, runs: runs.length }
+}
+
+function sobelRatio(bytes, width, height) {
+  let mid = 0
+  let strong = 0
+  for (let y = 1; y < height - 1; y += 1) {
+    for (let x = 1; x < width - 1; x += 1) {
+      const i = y * width + x
+      const gx = -bytes[i - width - 1] - 2 * bytes[i - 1] - bytes[i + width - 1]
+        + bytes[i - width + 1] + 2 * bytes[i + 1] + bytes[i + width + 1]
+      const gy = -bytes[i - width - 1] - 2 * bytes[i - width] - bytes[i - width + 1]
+        + bytes[i + width - 1] + 2 * bytes[i + width] + bytes[i + width + 1]
+      const magnitude = (Math.abs(gx) + Math.abs(gy)) / 4
+      if (magnitude > 60) strong += 1
+      else if (magnitude > 8) mid += 1
+    }
+  }
+  const edge = mid + strong
+  return edge ? mid / edge : null
+}
+
+const GENERIC_FAMILIES = new Set(['serif', 'sans-serif', 'monospace', 'system-ui', 'ui-serif', 'ui-sans-serif',
+  'ui-monospace', 'cursive', 'fantasy', 'emoji', 'math', 'fangsong', 'inherit', 'initial', 'unset', 'revert'])
+const SOURCE_EXT = new Set(['.tsx', '.ts', '.jsx', '.js', '.css'])
+
+function readSources(dir, depth = 0) {
+  const out = []
+  if (depth > 3) return out
+  let entries = []
+  try { entries = readdirSync(dir, { withFileTypes: true }) } catch { return out }
+  for (const entry of entries) {
+    if (entry.name === 'node_modules' || entry.name === '.out' || entry.name === 'assets') continue
+    const full = join(dir, entry.name)
+    if (entry.isDirectory()) { out.push(...readSources(full, depth + 1)); continue }
+    if (!SOURCE_EXT.has(extname(entry.name))) continue
+    try {
+      const text = readFileSync(full, 'utf8')
+      if (text.length < 400000) out.push({ file: full, text })
+    } catch { /* 读不了就跳过 */ }
+  }
+  return out
+}
+
+// 字体：场景里 declare 了一个字体，但工程没有 @font-face / loadFont / 字体文件，
+// 浏览器就悄悄退回系统字体 —— 排版、字宽、甚至换行全变，这是最贵的降级。
+// 给风格门禁用：把工程源码拼成一段文本，扫「有没有真的做后处理/累积」。
+export function sourceText(dir, limit = 800000) {
+  let text = ''
+  for (const source of readSources(dir)) {
+    text += '\n/* ' + source.file + ' */\n' + source.text
+    if (text.length > limit) break
+  }
+  return text
+}
+
+export function checkFonts(dir) {
+  const sources = readSources(dir)
+  const familyPattern = /(?:fontFamily|font-family)\s*[:=]\s*['"`]([^'"`]+)['"`]|(?:loadFont|FontFace)\(\s*['"`]([^'"`]+)['"`]/g
+  const declared = new Set()
+  const registered = new Set()
+  const facePattern = /@font-face\s*\{([\s\S]*?)\}/g
+  const faceFamily = /font-family\s*:\s*['"]?([^'";}]+)/i
+  for (const { text } of sources) {
+    for (const match of text.matchAll(facePattern)) {
+      const family = faceFamily.exec(match[1])
+      if (family) registered.add(family[1].trim().toLowerCase())
+    }
+    for (const match of text.matchAll(/(?:loadFont|FontFace)\(\s*['"`]([^'"`]+)['"`]/g)) registered.add(match[1].trim().toLowerCase())
+  }
+  // 字体文件也可以直接说明「这个 family 是有的」：按去符号后的名字做包含匹配。
+  let fontFiles = []
+  const walk = (base, depth) => {
+    if (depth > 2) return
+    let entries = []
+    try { entries = readdirSync(base, { withFileTypes: true }) } catch { return }
+    for (const entry of entries) {
+      const full = join(base, entry.name)
+      if (entry.isDirectory()) { walk(full, depth + 1); continue }
+      if (/\.(ttf|otf|woff2?|TTF|OTF|WOFF2?)$/.test(entry.name)) fontFiles.push(entry.name.toLowerCase())
+    }
+  }
+  walk(join(dir, 'assets'), 0)
+  walk(dir, 0)
+  const normalize = (value) => value.toLowerCase().replace(/[^a-z0-9]/g, '')
+
+  for (const { file, text } of sources) {
+    for (const match of text.matchAll(familyPattern)) {
+      const family = (match[1] || match[2] || '').trim()
+      if (!family) continue
+      for (const single of family.split(',')) {
+        const name = single.trim().replace(/^['"`]|['"`]$/g, '').trim()
+        if (!name) continue
+        // 模板字面量（`${FAMILY}`）、CSS 变量、继承关键字都不是字体名：
+        // 把它们当"没注册的字体"会让字体门禁误拒，实测踩过。
+        if (/[${}()]/.test(name) || /^(?:inherit|initial|unset|revert|var|ui-)\b/i.test(name)) continue
+        const lower = name.toLowerCase()
+        if (GENERIC_FAMILIES.has(lower)) continue
+        declared.add(JSON.stringify({ name, file }))
+      }
+    }
+  }
+  const missing = []
+  const families = []
+  for (const entry of declared) {
+    const { name, file } = JSON.parse(entry)
+    const lower = name.toLowerCase()
+    if (families.includes(lower)) continue
+    families.push(lower)
+    const known = registered.has(lower) || fontFiles.some((font) => normalize(font).includes(normalize(name)) || normalize(name).includes(normalize(font.replace(/\.[a-z0-9]+$/, ''))))
+    if (!known) missing.push({ family: name, file })
+  }
+  return { families, missing, fontFiles, registered: [...registered] }
+}
+
+export async function pixelQuality({ source, work, timeline, dir, samples = 3, timeoutMs }) {
+  const width = Number(timeline?.width) || 1920
+  const height = Number(timeline?.height) || 1080
+  const fps = Number(timeline?.fps) || 30
+  const total = Number(timeline?.durationInFrames) || 300
+  const points = []
+  for (let index = 0; index < Math.max(1, samples); index += 1) {
+    const fraction = samples <= 1 ? 0.5 : 0.2 + (0.65 * index) / (samples - 1)
+    points.push(Math.min(total - 1, Math.max(0, Math.floor(total * fraction))) / fps)
+  }
+  const banding = []
+  for (const [index, time] of points.entries()) {
+    for (const fraction of [0.18, 0.5, 0.82]) {
+      const y = clampInt(height * fraction, 0, height - 1)
+      const row = await rawGray({ source, work, time, crop: { x: 0, y, w: width, h: 1 }, name: 'band-' + index + '-' + Math.round(fraction * 100), timeoutMs })
+      banding.push({ time: Math.round(time * 100) / 100, y, ...staircase(row) })
+    }
+  }
+  const bandingWorst = banding.reduce((worst, item) => (item.longest > (worst?.longest || 0) ? item : worst), null)
+  const aa = []
+  for (const [index, time] of points.entries()) {
+    const size = Math.min(480, width, height)
+    const crop = { x: clampInt((width - size) / 2, 0, width - size), y: clampInt((height - size) / 2, 0, height - size), w: size, h: size }
+    const bytes = await rawGray({ source, work, time, crop, name: 'aa-' + index, timeoutMs })
+    aa.push({ time: Math.round(time * 100) / 100, midRatio: sobelRatio(bytes, crop.w, crop.h) })
+  }
+  const ratios = aa.map((item) => item.midRatio).filter((value) => value !== null)
+  const aaAverage = ratios.length ? ratios.reduce((sum, value) => sum + value, 0) / ratios.length : null
+  return {
+    banding: { samples: banding, worst: bandingWorst },
+    aa: { samples: aa, average: aaAverage === null ? null : Math.round(aaAverage * 1000) / 1000 },
+    fonts: dir ? checkFonts(dir) : { families: [], missing: [], fontFiles: [] },
+  }
+}

package/lib/motion/preview.js

@@ -0,0 +1,97 @@
+// 预览：把"某几帧长什么样"变成一张能直接看见的拼图。
+//
+// 这是整个改造里最重要的一条：以前 image_view 只返回路径，模型看不见图，
+// 于是要花一整轮工具调用来"取图"，34 次就是 34 个回合。现在预览工具
+// 直接返回 {type:'image', attachment}，同一轮就能判断画面对不对。
+
+import { existsSync, mkdirSync, readdirSync, copyFileSync, rmSync, statSync } from 'node:fs'
+import { join } from 'node:path'
+import { createHash } from 'node:crypto'
+import { execFile } from 'node:child_process'
+import { promisify } from 'node:util'
+import { ensureFfmpeg } from '../ffmpeg-manager.js'
+import { renderProject, outputPath } from './render.js'
+import { readTimeline } from './project.js'
+
+const exec = promisify(execFile)
+
+export function previewDir(dir) {
+  return join(dir, '.out', 'preview')
+}
+
+// 把已经渲染好的 PNG 拼成一张图。用 ffmpeg 的 tile，避免引入新依赖。
+export async function contactSheet(images, options = {}) {
+  if (!images.length) throw new Error('没有可拼的帧')
+  const cols = Math.max(1, Math.min(4, Math.round(Number(options.cols) || 3)))
+  const rows = Math.ceil(images.length / cols)
+  const work = dirnameOf(images[0]) + '\\.sheet-' + createHash('sha1').update(images.join('|')).digest('hex').slice(0, 10)
+  mkdirSync(work, { recursive: true })
+  try {
+    images.forEach((file, index) => copyFileSync(file, join(work, 'frame-' + (index + 1) + '.png')))
+    const output = join(work, 'sheet.png')
+    // width:0 = 不缩放。1:1 看锯齿/色带时必须关掉缩放，否则锯齿先被重采样抹平了。
+    const width = options.width === undefined ? 640 : Number(options.width)
+    const filter = (width > 0 ? 'scale=' + width + ':-2:flags=lanczos,' : '')
+      + 'tile=' + cols + 'x' + rows + ':padding=8:margin=8:color=0x101010'
+    const binary = await ensureFfmpeg()
+    await exec(binary, ['-hide_banner', '-loglevel', 'error', '-y', '-i', join(work, 'frame-%d.png'),
+      '-frames:v', '1', '-vf', filter, output],
+      { windowsHide: true, timeout: 60000 })
+    if (!existsSync(output)) throw new Error('拼图失败')
+    return output
+  } finally {
+    for (const file of readdirSync(work)) if (file !== 'sheet.png') rmSync(join(work, file), { force: true })
+  }
+}
+
+function dirnameOf(file) {
+  const index = Math.max(file.lastIndexOf('\\'), file.lastIndexOf('/'))
+  return index > 0 ? file.slice(0, index) : '.'
+}
+
+async function cropFile(file, crop) {
+  const out = file.replace(/\.png$/i, '-crop.png')
+  const binary = await ensureFfmpeg()
+  await exec(binary, ['-hide_banner', '-loglevel', 'error', '-y', '-i', file,
+    '-vf', 'crop=' + crop.w + ':' + crop.h + ':' + crop.x + ':' + crop.y, out], { windowsHide: true, timeout: 60000 })
+  return existsSync(out) ? out : file
+}
+
+// 裁切参数归一化：给的中心点/宽高可能越界，先按工程尺寸夹住。
+// 只给中心点（cx/cy）也行，默认取画面 1/3 大小 —— 局部的默认值就该够看细节。
+export function normalizeCrop(crop, timeline) {
+  if (!crop || typeof crop !== 'object') return null
+  const width = Number(timeline?.width) || 1920
+  const height = Number(timeline?.height) || 1080
+  const clamp = (value, low, high) => Math.min(Math.max(Math.round(Number(value) || 0), low), high)
+  const w = clamp(crop.w || width / 3, 16, width)
+  const h = clamp(crop.h || height / 3, 16, height)
+  const x = clamp(crop.x !== undefined ? crop.x : (Number(crop.cx) || width / 2) - w / 2, 0, width - w)
+  const y = clamp(crop.y !== undefined ? crop.y : (Number(crop.cy) || height / 2) - h / 2, 0, height - h)
+  return { x, y, w, h }
+}
+
+// 渲染 + 拼图 + 转附件，一次做完。
+// 返回的 attachment 由调用方的 render() 拼成 {type:'image', attachment} 内容块。
+export async function previewProject(dir, options = {}) {
+  const frames = options.frames
+  if (!Array.isArray(frames) || !frames.length) throw new Error('frames 必填，例如 [0, 60, 120]')
+  const result = await renderProject(dir, { operation: 'still', frames, onProgress: options.onProgress }).promise
+  let rendered = (result.frames || []).map((item) => item.filename ? join(dir, '.out', 'qa', item.filename) : null).filter(Boolean)
+  if (!rendered.length) throw new Error('没有渲染出可预览的帧')
+  const crop = normalizeCrop(options.crop, readTimeline(dir))
+  if (crop) rendered = await Promise.all(rendered.map((file) => cropFile(file, crop)))
+  const sheet = await contactSheet(rendered, { cols: options.cols, width: crop ? 0 : 640 })
+  const bytes = await import('node:fs').then((fs) => fs.readFileSync(sheet))
+  const attachments = options.attachments
+  const attachment = attachments?.saveImage
+    ? await attachments.saveImage({ data: bytes, mediaType: 'image/png', name: 'preview-' + Date.now() + '.png' })
+    : undefined
+  return {
+    frames: rendered.map((file, index) => ({ frame: Number(frames[index]), file, bytes: statSync(file).size })),
+    sheet,
+    crop,
+    attachment,
+    output: outputPath(dir, 'preview.png'),
+  }
+}