dsh-drawai 0.3.3 → 0.4.0

package/lib/motion/shotcraft/upstream/template/src/workbench.ts

@@ -0,0 +1,213 @@
+// Workbench manifest — how the film decomposes into editable clips.
+//
+// The shotcraft workbench (../../workbench, `node scripts/open.mjs <this project>`)
+// reads `WORKBENCH` and rebuilds the film as tracks: shots / transitions / captions
+// / SFX, each unit exactly where its <Sequence> sits in aifl/Main.tsx. Every table here is
+// imported from Main.tsx, so editing the timeline there moves the workbench too —
+// there is no second copy of the timing to drift.
+//
+// Editable properties per unit come from `schema` (text / colour / number / select /
+// boolean fields; see workbench/src/cards/types.ts PropField). Each scene exports its
+// `*_DEFAULTS` (copy, sizes, palette) and reads them as props with defaults, so the
+// schema defaults below are the same object the scene renders with — the inspector
+// shows exactly what is on screen, and an untouched import renders the original film.
+// Motion timing (cues, eases, camera keys) is deliberately NOT exposed.
+import { createElement, type FC } from 'react';
+import { withThemes } from './themes/manifest';
+import {
+  AIFL_SHOTS, AIFL_TOTAL, AiflMain, CAPTIONS, FLASH_CUTS, SFX, TITLE_CARDS, parseWords, sfxDuration,
+} from './aifl/Main';
+import { SceneOpen, SCENE_OPEN_DEFAULTS } from './aifl/live/SceneOpen';
+import { SceneFlyIn, SCENE_FLYIN_DEFAULTS } from './aifl/live/SceneFlyIn';
+import { SceneDetail, SCENE_DETAIL_DEFAULTS } from './aifl/live/SceneDetail';
+import { ScenePapers, SCENE_PAPERS_DEFAULTS } from './aifl/live/ScenePapers';
+import { SceneWbr, SCENE_WBR_DEFAULTS } from './aifl/live/SceneWbr';
+import { SceneOutroLive, SCENE_OUTRO_DEFAULTS } from './aifl/live/SceneOutroLive';
+import { PaperTitleCard, TITLE_CARD_DEFAULTS } from './aifl/PaperTitleCard';
+import { Caption, CAPTION_DEFAULTS } from './aifl/Caption';
+import { FlashCut } from './aifl/FlashCut';
+
+// —— schema field helpers (plain data; shape = workbench PropField) ——
+type Field = Record<string, unknown> & { type: string; key: string; label: string; default: unknown };
+const text = (key: string, label: string, def: string): Field => ({ type: 'text', key, label, default: def });
+const textarea = (key: string, label: string, def: string): Field => ({ type: 'textarea', key, label, default: def });
+const color = (key: string, label: string, def: string): Field => ({ type: 'color', key, label, default: def });
+const size = (key: string, label: string, def: number, min: number, max: number): Field => ({
+  type: 'slider', key, label, default: def, min, max, step: 1, unit: 'px',
+});
+
+// —— adapters: prop-driven wrappers so the workbench can edit copy without touching the scenes ——
+type TitleProps = Partial<typeof TITLE_CARD_DEFAULTS> & { text?: string; sub?: string; subDigits?: string; duration?: number };
+export const TitleCardUnit: FC<TitleProps> = ({ text = '', sub = '', subDigits = '', duration = 55, ...style }) =>
+  createElement(PaperTitleCard, {
+    duration,
+    words: parseWords(text),
+    sub: sub || undefined,
+    subDigits: subDigits || undefined,
+    ...style,
+  });
+TitleCardUnit.displayName = 'PaperTitleCard';
+
+type CaptionProps = Partial<typeof CAPTION_DEFAULTS> & { text?: string; bottom?: number; duration?: number };
+export const CaptionUnit: FC<CaptionProps> = ({ text = '', bottom = 72, duration = 40, ...style }) =>
+  createElement(Caption, { text, bottom, duration, ...style });
+CaptionUnit.displayName = 'Caption';
+
+export const FlashUnit: FC<{ duration?: number }> = ({ duration = 10 }) => createElement(FlashCut, { duration });
+FlashUnit.displayName = 'FlashCut';
+
+// —— schemas: one per parametrized component; defaults come straight from the *_DEFAULTS objects ——
+const D = {
+  open: SCENE_OPEN_DEFAULTS,
+  flyin: SCENE_FLYIN_DEFAULTS,
+  detail: SCENE_DETAIL_DEFAULTS,
+  papers: SCENE_PAPERS_DEFAULTS,
+  wbr: SCENE_WBR_DEFAULTS,
+  outro: SCENE_OUTRO_DEFAULTS,
+  title: TITLE_CARD_DEFAULTS,
+  caption: CAPTION_DEFAULTS,
+};
+
+const SCHEMAS = {
+  open: [
+    text('wordmark', '字标', D.open.wordmark),
+    size('wordmarkSize', '字标字号', D.open.wordmarkSize, 60, 200),
+    text('kicker', '眉题（打字机）', D.open.kicker),
+    size('kickerSize', '眉题字号', D.open.kickerSize, 14, 48),
+    text('noteLine1', '悬浮批注 · 上行', D.open.noteLine1),
+    text('noteLine2', '悬浮批注 · 下行（斜体+高亮）', D.open.noteLine2),
+    size('noteSize', '批注字号', D.open.noteSize, 20, 64),
+    color('ink', '墨色', D.open.ink),
+    color('amber', '琥珀强调色', D.open.amber),
+    color('muted', '灰墨（眉题）', D.open.muted),
+    color('paper', '纸底', D.open.paper),
+  ],
+  flyin: [
+    text('query', '搜索框输入的词', D.flyin.query),
+    color('accent', '琥珀强调色（光标 / 点击涟漪 / 选中框）', D.flyin.accent),
+  ],
+  detail: [color('accent', '嵌入接缝色', D.detail.accent)],
+  papers: [
+    text('title', '右上角标题', D.papers.title),
+    text('subtitle', '右上角副标', D.papers.subtitle),
+    size('counterSize', '计数器字号', D.papers.counterSize, 48, 160),
+    color('amber', '琥珀强调色', D.papers.amber),
+    color('muted', '灰墨', D.papers.muted),
+  ],
+  wbr: [
+    text('kicker', '右上角眉题', D.wbr.kicker),
+    size('kickerSize', '眉题字号', D.wbr.kickerSize, 14, 48),
+    textarea('pastWeeks', '左栏往期周报（每行：周|日期|标题）', D.wbr.pastWeeks),
+    color('amber', '琥珀强调色', D.wbr.amber),
+    color('muted', '灰墨', D.wbr.muted),
+  ],
+  outro: [
+    text('wordmark', '字标', D.outro.wordmark),
+    size('wordmarkSize', '字标字号', D.outro.wordmarkSize, 60, 220),
+    text('tagline', '副标', D.outro.tagline),
+    size('taglineSize', '副标字号', D.outro.taglineSize, 14, 48),
+    color('ink', '墨色', D.outro.ink),
+    color('amber', '琥珀强调色', D.outro.amber),
+    color('muted', '灰墨', D.outro.muted),
+  ],
+  title: [
+    textarea('text', '文案（*词* = 琥珀强调）', ''),
+    text('sub', '副标（等宽小字）', ''),
+    text('subDigits', '副标滚动数字', ''),
+    size('fontSize', '字号', D.title.fontSize, 60, 160),
+    color('ink', '墨色', D.title.ink),
+    color('accent', '强调色', D.title.accent),
+    color('muted', '副标灰墨', D.title.muted),
+    color('paper', '纸底', D.title.paper),
+  ],
+  caption: [
+    text('text', '解说文案', ''),
+    { type: 'slider', key: 'bottom', label: '底距', default: 72, min: 20, max: 400, step: 2, unit: 'px' } as Field,
+    size('fontSize', '字号', D.caption.fontSize, 14, 48),
+    color('color', '文字色', D.caption.color),
+    color('accent', '方点色', D.caption.accent),
+  ],
+};
+
+type ShotKey = keyof typeof AIFL_SHOTS;
+const scene = <T extends Record<string, unknown>>(
+  key: ShotKey, label: string, component: FC<Partial<T>>, defaults: T, schema: Field[],
+) => ({
+  id: key,
+  label,
+  from: AIFL_SHOTS[key].from,
+  duration: AIFL_SHOTS[key].duration,
+  component: component as FC<Record<string, unknown>>,
+  props: { ...defaults },
+  schema,
+});
+const title = (key: keyof typeof TITLE_CARDS, label: string) => {
+  const t = TITLE_CARDS[key] as { text: string; sub?: string; subDigits?: string };
+  return {
+    id: key,
+    label,
+    from: AIFL_SHOTS[key].from,
+    duration: AIFL_SHOTS[key].duration,
+    component: TitleCardUnit as FC<Record<string, unknown>>,
+    props: { text: t.text, sub: t.sub ?? '', subDigits: t.subDigits ?? '', ...D.title },
+    schema: SCHEMAS.title,
+    durationProp: 'duration',
+    cardId: 'title-card',
+    cardName: '字卡 · Ink Press',
+    accent: '#b5651d',
+  };
+};
+
+const PAPER_WORKBENCH = {
+  name: 'Ink Press · AIFL promo',
+  fps: 30,
+  width: 1920,
+  height: 1080,
+  total: AIFL_TOTAL,
+  background: '#f2eee6',
+  shots: [
+    scene('morning', 'S1 墨线开场 → 全景 → 主角卡', SceneOpen, D.open, SCHEMAS.open),
+    title('card1', '字卡① one place'),
+    scene('table', 'S3 牌堆 → 发牌 → 搜索筛选', SceneFlyIn, D.flyin, SCHEMAS.flyin),
+    scene('macro', 'S4 详情页宏观特写', SceneDetail, D.detail, SCHEMAS.detail),
+    title('card2', '字卡② Paper Radar'),
+    scene('chart', 'S6 论文雷达堆叠', ScenePapers, D.papers, SCHEMAS.papers),
+    title('cardWbr', '字卡③ weekly report'),
+    scene('wbr', 'S8 周报自己写自己', SceneWbr, D.wbr, SCHEMAS.wbr),
+    title('card3', '字卡④ same page'),
+    scene('outro', 'S10 合影组装 → 铅印字标', SceneOutroLive, D.outro, SCHEMAS.outro),
+  ],
+  transitions: FLASH_CUTS.map((cut, i) => ({
+    id: `flash-${i + 1}`,
+    label: `闪白 @${cut}f`,
+    from: cut - 5,
+    duration: 10,
+    component: FlashUnit as FC<Record<string, unknown>>,
+    durationProp: 'duration',
+    cardId: 'flash-cut',
+    cardName: '暖白闪转场',
+  })),
+  captions: CAPTIONS.map((c, i) => ({
+    id: `caption-${i + 1}`,
+    label: c.text,
+    from: c.from,
+    duration: c.duration,
+    component: CaptionUnit as FC<Record<string, unknown>>,
+    props: { text: c.text, ...D.caption },
+    schema: SCHEMAS.caption,
+    durationProp: 'duration',
+    cardId: 'caption',
+    cardName: '解说字幕条',
+  })),
+  sfx: SFX.map((s) => ({
+    from: s.from,
+    duration: sfxDuration(s),
+    src: `audio/${s.src}`,
+    volume: s.volume,
+  })),
+  // z-order of the overlay layers, top → bottom (flash cuts sit above the captions in Main.tsx)
+  order: ['transitions', 'captions', 'overlays'] as const,
+  // the untouched film, registered in the workbench Studio as `ProjOriginal` for frame-by-frame comparison
+  original: AiflMain as FC<Record<string, unknown>>,
+};
+export const WORKBENCH = withThemes(PAPER_WORKBENCH);

package/lib/motion/shotcraft/upstream/template/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "jsx": "react-jsx",
+    "strict": true,
+    "skipLibCheck": true,
+    "esModuleInterop": true,
+    "resolveJsonModule": true,
+    "noEmit": true,
+    "lib": ["DOM", "ES2022"]
+  },
+  "include": ["src"]
+}

package/lib/motion/spec.js

@@ -0,0 +1,113 @@
+// 视频节点的唯一数据契约。
+//
+// 这里只描述"一条视频是什么"，不描述"怎么渲染"。
+// 所有工具（motion_project / motion_preview / motion_render / motion_task）
+// 都从这里取默认值和校验，避免每个入口各写一套规则。
+
+export const MODES = ['api', 'animation']
+export const REF_ROLES = ['shot-card', 'image', 'audio']
+export const REF_EFFECTS = ['design-only', 'in-frame', 'in-track']
+
+// role 决定 effect 的默认值：镜头卡只是设计参考，图片进画面，音频进轨道。
+export const EFFECT_OF_ROLE = { 'shot-card': 'design-only', image: 'in-frame', audio: 'in-track' }
+
+export const LIMITS = {
+  width: [256, 1920],
+  height: [256, 1920],
+  fps: [12, 30],
+  duration: [2, 60],
+}
+
+export const DEFAULT_SPEC = { width: 1920, height: 1080, fps: 30, duration: 15 }
+
+const clampInt = (value, fallback, [min, max]) => {
+  const number = Math.round(Number(value))
+  if (!Number.isFinite(number)) return fallback
+  return Math.min(max, Math.max(min, number))
+}
+
+// 时长是唯一允许小数的规格（9.3 秒这种要原样保留，不能四舍五入成 9）。
+const clampSeconds = (value, fallback, [min, max]) => {
+  const number = Number(value)
+  if (!Number.isFinite(number)) return fallback
+  return Math.round(Math.min(max, Math.max(min, number)) * 100) / 100
+}
+
+function positiveInt(value, fallback) {
+  const number = Math.round(Number(value))
+  return Number.isFinite(number) && number > 0 ? number : fallback
+}
+
+// 节点里存的 motion 字段历史上是"设置 + 运行快照"混在一起。
+// 这里只把它读成一个干净的 spec，不改节点。
+export function readSpec(motion = {}) {
+  const width = clampInt(motion.width, DEFAULT_SPEC.width, LIMITS.width)
+  const height = clampInt(motion.height, DEFAULT_SPEC.height, LIMITS.height)
+  const fps = clampInt(motion.fps, DEFAULT_SPEC.fps, LIMITS.fps)
+  const duration = clampSeconds(motion.duration, DEFAULT_SPEC.duration, LIMITS.duration)
+  return {
+    mode: MODES.includes(motion.mode) ? motion.mode : 'animation',
+    width,
+    height,
+    fps,
+    duration,
+    totalFrames: Math.max(1, Math.round(fps * duration)),
+  }
+}
+
+export function normalizeRef(ref) {
+  if (!ref || typeof ref !== 'object') throw new Error('参考项必须是对象')
+  const role = REF_ROLES.includes(ref.role) ? ref.role : 'image'
+  return {
+    id: String(ref.id || ''),
+    role,
+    effect: REF_EFFECTS.includes(ref.effect) ? ref.effect : EFFECT_OF_ROLE[role],
+    assetId: ref.assetId ? String(ref.assetId) : undefined,
+    cardId: ref.cardId ? String(ref.cardId) : undefined,
+    note: ref.note ? String(ref.note) : undefined,
+  }
+}
+
+export function readClips(motion = {}) {
+  const clips = Array.isArray(motion.clips) ? motion.clips : []
+  return clips
+    .filter((clip) => clip && typeof clip === 'object')
+    .map((clip, index) => ({
+      id: String(clip.id || 'clip-' + (index + 1)),
+      kind: ['api-shot', 'scene', 'asset'].includes(clip.kind) ? clip.kind : 'scene',
+      from: positiveInt(clip.from, 0),
+      durationFrames: positiveInt(clip.durationFrames, 1),
+    }))
+}
+
+export function readRefs(motion = {}) {
+  const refs = Array.isArray(motion.refs) ? motion.refs : []
+  return refs.map(normalizeRef).filter((ref) => ref.id)
+}
+
+// 校验返回**错误列表**而不是抛异常：工具层要一次把问题全列给模型。
+export function validateSpec(spec) {
+  const errors = []
+  if (!MODES.includes(spec.mode)) errors.push('mode 必须是 api 或 animation')
+  for (const key of ['width', 'height']) {
+    const value = Number(spec[key])
+    if (!Number.isInteger(value) || value < LIMITS[key][0] || value > LIMITS[key][1]) errors.push(key + ' 超出 ' + LIMITS[key].join('–'))
+    else if (value % 2) errors.push(key + ' 必须是偶数')
+  }
+  if (!Number.isInteger(spec.fps) || spec.fps < LIMITS.fps[0] || spec.fps > LIMITS.fps[1]) errors.push('fps 超出 ' + LIMITS.fps.join('–'))
+  if (!Number.isFinite(spec.duration) || spec.duration < LIMITS.duration[0] || spec.duration > LIMITS.duration[1]) errors.push('duration 超出 ' + LIMITS.duration.join('–') + ' 秒')
+  return errors
+}
+
+// 把 spec 变成一条可渲染的镜头表：一场景一文件，首尾相接，不重叠。
+export function layoutShots(spec, durations) {
+  const total = spec.totalFrames
+  const list = Array.isArray(durations) && durations.length ? durations : [total]
+  let cursor = 0
+  return list.map((frames, index) => {
+    const durationFrames = Math.max(1, Math.round(frames))
+    const shot = { id: 'shot-' + (index + 1), index, startFrame: cursor, durationFrames }
+    cursor += durationFrames
+    return shot
+  })
+}

package/lib/motion/style-engine.js

@@ -0,0 +1,153 @@
+/**
+ * 整片风格的「引擎契约」：上游那支片用什么引擎，移植就得用什么引擎。
+ *
+ * 为什么要有这个模块：风格最容易糊弄的地方不是配色，是「像不像那个引擎」——
+ * three.js 的等轴城市用 CSS 3D 摆几个 div 也能骗过静帧，WebGL2 的流体用
+ * Canvas2D 画几个渐变圆也能骗过一帧，但一动就露。所以：
+ *   1. 建工程时把引擎写进 STYLE.md（硬规定 + 上游证据文件）；
+ *   2. 渲染前扫工程源码，重引擎（three / webgl2 / webgl）缺了直接拒绝渲染；
+ *   3. 确实要换实现，必须在 STYLE.md 留一行「偏离：引擎 …」，渲染照过但带 warning。
+ */
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs'
+import { extname, join } from 'node:path'
+import { checkFonts, sourceText } from './pixelqa.js'
+
+export const ENGINE_LABEL = {
+  three: 'three.js（WebGL）',
+  webgl2: '原生 WebGL2',
+  webgl: '原生 WebGL',
+  canvas2d: 'Canvas 2D',
+  dom: 'DOM / CSS',
+}
+
+export const ENGINE_GUIDANCE = {
+  three: '在 <canvas> 里用 three 或 @remotion/three 真渲染：自建 WebGLRenderer、场景与相机，按 useCurrentFrame() 驱动 renderAt，后处理用 three/addons（UnrealBloomPass 等）。',
+  webgl2: '起 canvas.getContext("webgl2")，把上游 GLSL（如 js/shaders.js）原样编译，按帧传 uniform；不要用 Canvas2D 渐变/模糊替代。',
+  webgl: '起 canvas.getContext("webgl")，把上游 shader 原样编译，按帧传 uniform；不要用 Canvas2D 替代。',
+  canvas2d: '用 canvas 2D 逐帧绘制（路径 / 贴图 / 像素读写），不要用 DOM 拼贴替代逐帧绘制。',
+  dom: '用真实 DOM/CSS 合成（如多层 backdrop-filter 景深），不要用画布贴图或纯色块替代。',
+}
+
+/** 只在渲染前硬拦这三类：它们是「一眼能假、一动就露」的重引擎。 */
+export const GATED_ENGINES = new Set(['three', 'webgl2', 'webgl'])
+
+const SIGNALS = [
+  ['three', /(?:from\s*|require\(\s*)['"]three(?:\/addons[^'"]*)?['"]|@remotion\/three/],
+  ['webgl2', /getContext\(\s*['"]webgl2['"]|WebGL2RenderingContext/],
+  ['webgl', /getContext\(\s*['"]webgl['"]/],
+  ['canvas2d', /getContext\(\s*['"]2d['"]/],
+  ['dom', /backdrop-filter|filter:\s*blur\(/],
+]
+const PRIORITY = SIGNALS.map(([engine]) => engine)
+const TEXT_EXT = new Set(['.tsx', '.ts', '.jsx', '.js', '.mjs', '.cjs', '.css', '.html', '.glsl', '.vert', '.frag', '.wgsl'])
+const SKIP_DIR = new Set(['.out', 'node_modules', '.git'])
+
+/** 单个文件文本里出现的引擎（按优先级）。 */
+export function enginesOfText(text) {
+  return PRIORITY.filter((engine) => SIGNALS.find(([name]) => name === engine)[1].test(text))
+}
+
+/** 扫整个工程（不含 .out / node_modules），返回用到的引擎与证据文件。 */
+export function scanProjectEngines(dir) {
+  const files = new Map()
+  const walk = (base, prefix) => {
+    for (const entry of readdirSync(base, { withFileTypes: true })) {
+      if (SKIP_DIR.has(entry.name)) continue
+      const rel = prefix ? prefix + '/' + entry.name : entry.name
+      const full = join(base, entry.name)
+      if (entry.isDirectory()) { walk(full, rel); continue }
+      if (!TEXT_EXT.has(extname(entry.name).toLowerCase())) continue
+      if (statSync(full).size > 512 * 1024) continue
+      const found = enginesOfText(readFileSync(full, 'utf8'))
+      for (const engine of found) {
+        if (!files.has(engine)) files.set(engine, [])
+        if (!files.get(engine).includes(rel)) files.get(engine).push(rel)
+      }
+    }
+  }
+  walk(dir, '')
+  return { engines: PRIORITY.filter((engine) => files.has(engine)), files }
+}
+
+/** STYLE.md 里显式记录的偏离行（playbook 的「偏离：X 改为 Y，因为 Z」同一套写法）。 */
+export function engineDeviation(dir) {
+  const file = join(dir, 'STYLE.md')
+  if (!existsSync(file)) return null
+  const line = readFileSync(file, 'utf8').split('\n').find((text) => /偏离：引擎/.test(text))
+  return line ? line.trim().replace(/^[-*\s]+/, '') : null
+}
+
+function deviationLine(dir, pattern) {
+  const file = join(dir, 'STYLE.md')
+  if (!existsSync(file)) return null
+  const line = readFileSync(file, 'utf8').split('\n').find((text) => pattern.test(text))
+  return line ? line.trim().replace(/^[-*\s]+/, '') : null
+}
+
+// 「有没有真的做」而不是「有没有写」：字体没注册、three 风格没有后处理链，
+// 这两件事在源码里是有证据的，所以这里可以直接查，而不是再写一遍散文要求。
+const POST_EVIDENCE = /SSAOPass|UnrealBloomPass|EffectComposer|@react-three\/postprocessing|BloomPass|GTAOPass|N8AO/
+const ACCUM_EVIDENCE = /samples|shutter|jitter\(|halton\(|HalfFloatType/
+
+/**
+ * 渲染前的质量门禁：能拦的拦（字体），该喊的喊（后处理/累积缺席）。
+ * 返回 {fonts, warnings}；字体缺失且没有偏离行 → 抛错。
+ */
+export function assertQualityEvidence(dir, style, options = {}) {
+  const warnings = []
+  const details = { warnings }
+  const fonts = checkFonts(dir)
+  details.fonts = { families: fonts.families, missing: fonts.missing, files: fonts.fontFiles }
+  if (fonts.missing.length && options.fonts !== false) {
+    const deviation = deviationLine(dir, /偏离：字体/)
+    const preview = fonts.missing.slice(0, 6).map((item) => '  - ' + item.family + '（' + item.file + '）').join('\n')
+    if (!deviation) {
+      throw new Error('字体没注册，拒绝渲染：工程里声明了 ' + fonts.missing.length + ' 个字体，但没有对应的 @font-face / loadFont / 字体文件，\n'
+        + '浏览器会悄悄退回系统字体，排版和字宽全变（这是最贵的降级，且不报错）。\n' + preview + '\n'
+        + '修：把 OFL 字体放进 assets/ 并在场景里 loadFont()，或用 theme.ts 里已经注册的字体。\n'
+        + '确实要用系统字体：在 STYLE.md 写一行「偏离：字体 …，因为 …」。')
+    }
+    warnings.push('字体未注册：' + fonts.missing.map((item) => item.family).join('、') + '；STYLE.md 已记录偏离：' + deviation.replace(/^偏离：/, ''))
+  }
+  const required = style && (Array.isArray(style.engines) && style.engines.length ? style.engines : [style.engine]).filter(Boolean)
+  if (required && required.includes('three') && options.evidence !== false) {
+    const text = sourceText(dir)
+    if (!POST_EVIDENCE.test(text)) {
+      const deviation = deviationLine(dir, /偏离：后处理/)
+      if (deviation) warnings.push('three 风格没有后处理链；STYLE.md 已记录偏离：' + deviation.replace(/^偏离：/, ''))
+      else warnings.push('three 风格里没检测到后处理（EffectComposer / SSAOPass / UnrealBloomPass）：斜边与接触阴影只能靠几何自带的明暗，'
+        + '上游的 SSAO 与 bloom 溢出会缺席。要么接上，要么在 STYLE.md 写「偏离：后处理 …」')
+    }
+    if (!ACCUM_EVIDENCE.test(text)) {
+      warnings.push('场景里没读到 samples / shutter / jitter：等轴斜边在 1× 下必然有阶梯，先按 render.samples 做同帧累积（scene-kit/look.tsx 里已有 SSAA）')
+    }
+  }
+  return details
+}
+
+/**
+ * 渲染前调用。返回 {gated, required, detected, missing, deviation, warning}；
+ * 重引擎缺失且没有偏离记录 → 直接抛错（不渲染）。
+ */
+export function assertEngineFidelity(dir, style) {
+  const required = style && (Array.isArray(style.engines) && style.engines.length ? style.engines : [style.engine]).filter(Boolean)
+  if (!required || !required.length) return { gated: false, required: [], detected: [], missing: [], deviation: null, warning: '' }
+  const heavy = required.filter((engine) => GATED_ENGINES.has(engine))
+  if (!heavy.length) return { gated: false, required, detected: [], missing: [], deviation: null, warning: '' }
+  const scan = scanProjectEngines(dir)
+  const missing = heavy.filter((engine) => !scan.engines.includes(engine))
+  const label = (engine) => ENGINE_LABEL[engine] || engine
+  if (!missing.length) return { gated: true, required, detected: scan.engines, missing, deviation: null, warning: '' }
+  const deviation = engineDeviation(dir)
+  if (deviation) {
+    return { gated: true, required, detected: scan.engines, missing,
+      warning: '这个风格上游用 ' + heavy.map(label).join(' + ') + '，工程里没检测到 ' + missing.map(label).join(' + ') + '；STYLE.md 已记录偏离：' + deviation.replace(/^偏离：/, '') }
+  }
+  const evidence = (style.engineFiles || []).slice(0, 5).map((path) => '  - ' + path).join('\n')
+  throw new Error('引擎不符合风格要求，拒绝渲染：' + (style.name || style.slug || '') + '（' + (style.slug || '?') + '）上游用 '
+    + heavy.map(label).join(' + ') + '，但工程源码里没检测到 ' + missing.map(label).join(' + ') + '。\n'
+    + '不要用 CSS 3D / div 层叠 / Canvas2D 渐变「简化」重引擎 —— 那正是这个风格的判据。\n'
+    + heavy.map((engine) => '- ' + label(engine) + '：' + ENGINE_GUIDANCE[engine]).join('\n') + '\n'
+    + (evidence ? '上游实现（用 mg_style action:"source" 读正文）：\n' + evidence + '\n' : '')
+    + '确实要换实现：先在 STYLE.md 写一行「偏离：引擎 ' + heavy[0] + ' 改为 …，因为 …」，再渲染（会带 warning 通过）。')
+}