dsh-drawai 0.3.4 → 0.4.0

package/lib/motion/style-frames.js

@@ -0,0 +1,268 @@
+/*
+ * 取「整片风格」上游 demo 的参考帧。
+ *
+ * brief 能写清色板与判据，但写不清动效：转场怎么擦、冲击有没有环、相机有没有抖、
+ * 颗粒是逐像素还是几百个点 —— 这些只有看帧才知道。这里用上游自带的服务端 + Chrome
+ * 打开 demos/<slug>/index.html，按 cues.json 的时间点调 renderAt(t) 截帧，交给模型当
+ * 对照物。缺字体/纸纹时用占位资源兜底，并记在 notes 里，不假装素材齐全。
+ */
+import {openBrowser} from '@remotion/renderer'
+import {existsSync,mkdirSync,readFileSync,statSync,writeFileSync} from 'node:fs'
+import {createServer} from 'node:http'
+import {extname,join,normalize,resolve,sep} from 'node:path'
+import {tmpdir} from 'node:os'
+import {fileURLToPath} from 'node:url'
+import {fontsDir, mediaLibraryRoot} from './asset-pack.js'
+import {fontFaces} from './fonts.js'
+
+const UPSTREAM = fileURLToPath(new URL('./mgstyles/upstream', import.meta.url))
+const DEMO_FONT_ALIASES = {
+  '/demos/03-isometric/assets/fonts/Unbounded-800-static.ttf': 'Unbounded',
+  '/demos/07-liquid/assets/Fraunces-Liquid-72-900-Soft.ttf': 'Fraunces',
+  '/demos/08-morph/assets/fonts/Outfit-SemiBold.ttf': 'Outfit',
+  '/demos/10-synthwave/assets/fonts/MrDafoe-Regular.ttf': 'Mr Dafoe',
+}
+// 上游 demo 的 importmap 指向 /node_modules/three/...、/node_modules/opentype.js/...，
+// 但这些包只在插件根目录的 node_modules 里。旧版只服务 upstream 目录，于是模块 404、
+// window.__ready 永不置真，最后报了句"没有在 120 秒内就绪"——错误信息指向了完全错误的地方。
+const MODULES = fileURLToPath(new URL('../../node_modules', import.meta.url))
+
+const MIME = {
+  '.html': 'text/html; charset=utf-8', '.js': 'text/javascript', '.mjs': 'text/javascript',
+  '.css': 'text/css', '.json': 'application/json', '.png': 'image/png', '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg', '.webp': 'image/webp', '.svg': 'image/svg+xml', '.ttf': 'font/ttf',
+  '.otf': 'font/otf', '.woff': 'font/woff', '.woff2': 'font/woff2', '.wav': 'audio/wav',
+  '.mp3': 'audio/mpeg', '.mp4': 'video/mp4', '.wasm': 'application/wasm', '.glb': 'model/gltf-binary',
+}
+
+// 1×1 透明 PNG：纸纹/贴图没 vendored 时先让页面能 decode 通过，画面里那块会是平的，notes 会写明。
+const PLACEHOLDER_PNG = Buffer.from(
+  'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8BQDwAEhQGAhKmMIQAAAABJRU5ErkJggg==',
+  'base64',
+)
+
+// 字体没 vendored 时用系统字体顶上：document.fonts.load() 才不会 reject（字形本来就从 glyphs.json 来，
+// 参考帧里字的形状可能略有出入，但不会整页 init 失败）。
+const SYSTEM_FONT = [
+  ...(fontsDir() ? [join(fontsDir(), 'NotoSansSC-VF.ttf')] : []),
+  'C:/Windows/Fonts/segoeui.ttf',
+  'C:/Windows/Fonts/arial.ttf',
+  'C:/Windows/Fonts/msyh.ttc',
+].find((path) => existsSync(path))
+
+/** 素材库贴图目录：素材包没装好时返回 null。 */
+function texturesDir() {
+  const root = mediaLibraryRoot()
+  return root ? join(root, 'assets', 'textures') : null
+}
+
+function flattenNumbers(value, out) {
+  if (typeof value === 'number' && Number.isFinite(value)) out.push(value)
+  else if (Array.isArray(value)) for (const item of value) flattenNumbers(item, out)
+  else if (value && typeof value === 'object') for (const item of Object.values(value)) flattenNumbers(item, out)
+}
+
+function cueTimes(slug, duration) {
+  const file = join(UPSTREAM, 'demos', slug, 'cues.json')
+  if (!existsSync(file)) return []
+  try {
+    const raw = JSON.parse(readFileSync(file, 'utf8'))
+    const out = []
+    // bpm/fps 是参数不是时间点；loop 是几何；它们混进来会截到片尾之外的空帧。
+    for (const [key, value] of Object.entries(raw)) {
+      if (/^(bpm|fps|loop)$/i.test(key)) continue
+      flattenNumbers(value, out)
+    }
+    const limit = Number.isFinite(duration) && duration > 0 ? duration - 0.04 : 60
+    return [...new Set(out.filter((t) => t >= 0.05 && t <= limit).map((t) => Math.round(t * 100) / 100))].sort((a, b) => a - b)
+  } catch {
+    return []
+  }
+}
+
+function pickTimes(slug, count, explicit, duration) {
+  if (Array.isArray(explicit) && explicit.length) {
+    const limit = Number.isFinite(duration) && duration > 0 ? duration : Infinity
+    return explicit.map(Number).filter((t) => Number.isFinite(t) && t >= 0 && t <= limit).slice(0, 24)
+  }
+  const cues = cueTimes(slug, duration)
+  const wanted = Math.max(1, Math.min(24, Math.floor(Number(count) || 8)))
+  if (cues.length >= wanted) {
+    // 均匀覆盖全片，同时尽量落在 cue 上（动作发生的那几帧信息量最大）
+    const min = cues[0], max = cues[cues.length - 1]
+    return Array.from({ length: wanted }, (_, i) => {
+      const target = min + ((max - min) * i) / Math.max(1, wanted - 1)
+      return cues.reduce((best, t) => (Math.abs(t - target) < Math.abs(best - target) ? t : best), cues[0])
+    })
+  }
+  const max = Number.isFinite(duration) && duration > 0 ? duration : 10
+  return Array.from({ length: wanted }, (_, i) => Math.round(((max * i) / Math.max(1, wanted - 1)) * 1000) / 1000)
+}
+
+// demo 的 importmap 指向 /node_modules/*，只有真装在本机的包才服务得出来。
+// 缺包时页面会静默卡在模块加载阶段，等到超时也只会说"没就绪"—— 这里提前查，几十毫秒就报清缺什么。
+function missingModules(slug) {
+  const html = join(UPSTREAM, 'demos', slug, 'index.html')
+  let text = ''
+  try { text = readFileSync(html, 'utf8') } catch { return [] }
+  const refs = [...text.matchAll(/["'](\/node_modules\/[^"']+)["']/g)].map((match) => match[1])
+  return [...new Set(refs)].filter((ref) => !existsSync(join(MODULES, ref.slice('/node_modules/'.length))))
+}
+
+function startStaticServer(misses) {
+  const roots = {vendor: resolve(MODULES), upstream: resolve(UPSTREAM)}
+  return new Promise((done) => {
+    const server = createServer((req, res) => {
+      try {
+        const pathname = decodeURIComponent(new URL(req.url, 'http://x').pathname)
+        if (pathname === '/assets/fonts/fonts.css') {
+          misses.push('/assets/fonts/fonts.css（使用 DrawAI 内置字体，部分上游字体或字重可能不同）')
+          res.writeHead(200, {'Content-Type': 'text/css; charset=utf-8'})
+          return res.end(fontFaces().map(face => '@font-face{font-family:' + JSON.stringify(face.family) + ';src:url(' + JSON.stringify('/__drawai-fonts/' + face.file) + ');font-weight:' + face.weight + ';font-style:' + face.style + ';font-display:block}').join('\n'))
+        }
+        if (pathname.startsWith('/__drawai-fonts/') && fontFaces().some(face => pathname === '/__drawai-fonts/' + face.file)) {
+          const file = join(fontsDir() || '', pathname.split('/').at(-1))
+          if (!existsSync(file)) { res.writeHead(404); return res.end('missing bundled font') }
+          res.writeHead(200, {'Content-Type': 'font/ttf'})
+          return res.end(readFileSync(file))
+        }
+        if (DEMO_FONT_ALIASES[pathname]) {
+          const face = fontFaces().find(item => item.family === DEMO_FONT_ALIASES[pathname] && item.style === 'normal')
+          if (face && existsSync(join(fontsDir() || '', face.file))) {
+            if (face.weight.includes(' ')) misses.push(pathname + '（使用同字体族可变字体，字重或轴值可能不同）')
+            res.writeHead(200, {'Content-Type': 'font/ttf'})
+            return res.end(readFileSync(join(fontsDir() || '', face.file)))
+          }
+        }
+        const vendor = pathname.startsWith('/node_modules/')
+        // 两条挂载点：/node_modules/* → 插件 node_modules；其余 → upstream。各自限制在自己目录内。
+        const root = vendor ? roots.vendor : roots.upstream
+        const relative = vendor ? pathname.slice('/node_modules'.length) : pathname
+        let file = resolve(join(root, normalize(relative)))
+        if (file !== root && !file.startsWith(root + sep)) { res.writeHead(403); return res.end('403') }
+        if (existsSync(file) && statSync(file).isDirectory()) file = join(file, 'index.html')
+        // Shared upstream textures are packaged separately from the text-only demo tree.
+        if (!vendor && !existsSync(file) && pathname.startsWith('/assets/textures/')) {
+          const tdir = texturesDir()
+          const texture = tdir ? resolve(tdir, pathname.slice('/assets/textures/'.length)) : ''
+          if (tdir && texture.startsWith(resolve(tdir) + sep) && existsSync(texture)) file = texture
+        }
+        if (!existsSync(file)) {
+          misses.push(pathname)
+          // 模块缺失不能给占位：给个假的 three.module.js 只会让页面以更难懂的方式失败。
+          if (vendor) { res.writeHead(404); return res.end('404 ' + pathname) }
+          // 字体/纸纹/贴图没 vendor：CSS 给空表，图片给 1px 占位，其余 404（页面会走 fallback）
+          if (/\.css$/i.test(pathname)) { res.writeHead(200, {'Content-Type': 'text/css'}); return res.end('/* placeholder */') }
+          if (/\.(png|jpe?g|webp)$/i.test(pathname)) { res.writeHead(200, {'Content-Type': MIME[extname(file).toLowerCase()] || 'image/png'}); return res.end(PLACEHOLDER_PNG) }
+          if (/\.(ttf|otf|woff2?)$/i.test(pathname) && SYSTEM_FONT) {
+            res.writeHead(200, {'Content-Type': 'font/ttf'})
+            return res.end(readFileSync(SYSTEM_FONT))
+          }
+          res.writeHead(404); return res.end('404 ' + pathname)
+        }
+        res.writeHead(200, {'Content-Type': MIME[extname(file).toLowerCase()] || 'application/octet-stream', 'Cache-Control': 'no-store'})
+        res.end(readFileSync(file))
+      } catch (error) {
+        res.writeHead(500); res.end(String(error))
+      }
+    })
+    server.listen(0, '127.0.0.1', () => done(server))
+  })
+}
+
+function findChrome(browserExecutable) {
+  return [browserExecutable, process.env.DRAWAI_CHROME_PATH,
+    'C:/Program Files/Google/Chrome/Application/chrome.exe',
+    'C:/Program Files (x86)/Google/Chrome/Application/chrome.exe',
+    'C:/Program Files (x86)/Microsoft/Edge/Application/msedge.exe'].find((path) => path && existsSync(path))
+}
+
+export async function captureStyleFrames({slug, times: explicitTimes, count = 8, browserExecutable, directory, signal} = {}) {
+  if (typeof slug !== 'string' || !/^[a-z0-9][a-z0-9-]*$/i.test(slug)) throw new Error('slug 无效：' + slug)
+  const demo = join(UPSTREAM, 'demos', slug)
+  if (!existsSync(join(demo, 'index.html'))) throw new Error('这个风格没有可截帧的上游 demo：' + slug + '（只有说明、没有 index.html）')
+  const missing = missingModules(slug)
+  if (missing.length) {
+    throw new Error('这个 demo 的依赖没装在本机（' + missing.join(', ') + '），页面加载不到模块，截不了帧。'
+      + '三条路：① 改用 action:"source" 读 demos/' + slug + '/ 下的源码与 cues.json 反推动效（多数情况够用）；'
+      + '② 在插件目录跑 `npm i --no-save opentype.js simplex-noise topojson-client d3` 后重试（这几个包只为截参考帧，不进 package.json）；'
+      + '③ 换一个不依赖它们的 demo。')
+  }
+
+  const misses = []
+  const server = await startStaticServer(misses)
+  const port = server.address().port
+  const executable = findChrome(browserExecutable)
+  signal?.throwIfAborted()
+  const browser = await openBrowser('chrome', {browserExecutable: executable, logLevel: 'error'})
+  try {
+    const page = await browser.newPage({context: () => null, logLevel: 'error', indent: false, pageIndex: 0, onBrowserLog: null, onLog: () => {}})
+    await page.setViewport({width: 1920, height: 1080, deviceScaleFactor: 1})
+    await page.goto({url: 'http://127.0.0.1:' + port + '/demos/' + slug + '/index.html', timeout: 60000})
+    // 就绪等待 30 秒：实测最慢的能截的 demo 8.4 秒就绪；真出问题的页面不会在第 31 秒突然变好。
+    // 超时要把"缺了哪些资源"一起报出来，并分清是缺 npm 包还是上游素材没 vendored——两者的处理办法不一样。
+    try {
+      await page.evaluate(() => new Promise((resolve, reject) => {
+        const started = Date.now()
+        const tick = () => {
+          if (window.__ready === true) return resolve(true)
+          if (Date.now() - started > 30000) return reject(new Error('__timeout__'))
+          setTimeout(tick, 100)
+        }
+        tick()
+      }))
+    } catch {
+      const lost = [...new Set(misses)]
+      const modules = lost.filter((path) => path.startsWith('/node_modules/')).slice(0, 4)
+      const assets = lost.filter((path) => !path.startsWith('/node_modules/') && !/favicon|fonts\.css/.test(path)).slice(0, 4)
+      throw new Error('上游 demo 没有就绪（30 秒）'
+        + (modules.length ? '；缺 npm 包：' + modules.join(', ') : '')
+        + (assets.length ? '；缺上游素材：' + assets.join(', ') + '（这些没有 vendored，不是配置问题）' : '')
+        + (modules.length || assets.length ? '' : '；模块可能抛错')
+        + '。改用 action:"source" 读 demos/' + slug + '/ 下的源码与 cues.json 反推动效，通常比等截帧更省事。')
+    }
+    const meta = await page.evaluate(() => ({
+      width: window.DEMO?.width || 1920,
+      height: window.DEMO?.height || 1080,
+      fps: window.DEMO?.fps || 30,
+      duration: window.DEMO?.duration || 10,
+      hasRenderAt: typeof window.renderAt === 'function',
+    }))
+    if (!meta.hasRenderAt) throw new Error('这个 demo 没有 window.renderAt(t)，无法按时间取帧；改用 action:"source" 读源码')
+    const width = Math.max(320, Math.min(2560, Math.round(meta.width)))
+    const height = Math.max(240, Math.min(1440, Math.round(meta.height)))
+    const fps = Math.max(1, Math.round(meta.fps || 30))
+    await page.setViewport({width, height, deviceScaleFactor: 1})
+    const times = pickTimes(slug, count, explicitTimes, Number(meta.duration) || 10)
+    if (!times.length) throw new Error('没有可用的时间点（cues.json 里的时间都超出片长）')
+
+    const dir = directory || join(tmpdir(), 'dsh-drawai', 'style-frames', slug)
+    mkdirSync(dir, {recursive: true})
+    const files = []
+    for (const [index, t] of times.entries()) {
+      signal?.throwIfAborted()
+      await page.evaluate(async (time, fpsValue) => {
+        await window.renderAt?.(time)
+        // 两帧 rAF：让画面里基于 frame 的绘制与 CSS/WAAPI 都落到同一时刻
+        await new Promise((resolve) => requestAnimationFrame(() => requestAnimationFrame(() => setTimeout(resolve, 30))))
+        void fpsValue
+      }, t, fps)
+      const result = await page._client().send('Page.captureScreenshot', {
+        format: 'png', captureBeyondViewport: false,
+        clip: {x: 0, y: 0, width, height, scale: 1},
+      })
+      const data = Buffer.from((result.value || result).data, 'base64')
+      if (data.length > 12 * 1024 * 1024) throw new Error('参考帧体积过大：' + t + 's')
+      const file = join(dir, 'frame-' + String(index).padStart(2, '0') + '-' + t.toFixed(2) + 's.png')
+      writeFileSync(file, data)
+      files.push({time: t, frame: Math.round(t * fps), path: file, bytes: data.length})
+    }
+    const notes = []
+    if (misses.length) notes.push('缺上游资源（已用占位兜底，画面里的字体/纸纹可能与原片不同）：' + [...new Set(misses)].slice(0, 8).join(', '))
+    notes.push('这些是参考帧：写场景前逐张看，按 STYLE.md 的效果配方逐项对照（转场/冲击/相机/颗粒/二次运动），别只对"形"。')
+    return {slug, width, height, fps, duration: meta.duration, times, directory: dir, files, notes}
+  } finally {
+    await browser.close({silent: true}).catch(() => {})
+    await new Promise((done) => server.close(done))
+  }
+}

package/lib/motion/sync.js

@@ -0,0 +1,214 @@
+// One source of truth: source-music seconds -> edit events -> source SFX peaks.
+import { createHash } from 'node:crypto'
+import { existsSync, readFileSync, mkdirSync, writeFileSync, readdirSync, unlinkSync } from 'node:fs'
+import { join, resolve, relative, isAbsolute } from 'node:path'
+import { decodePcm } from './beats.js'
+import { runFfmpeg } from './ffmpeg.js'
+import { parseProjectJson } from './json.js'
+
+const number = (value, name) => {
+  if (typeof value !== 'number' || !Number.isFinite(value)) throw new Error(name + ' 必须是有限数字')
+  return value
+}
+export function assetPath(dir, file) {
+  const root = resolve(dir, 'assets'), path = resolve(root, file || '')
+  const rel = relative(root, path)
+  if (!rel || isAbsolute(rel) || rel === '..' || rel.startsWith('..' + (process.platform === 'win32' ? '\\' : '/'))) throw new Error('同步音频必须位于工程 assets 内')
+  return path
+}
+export const syncKey = (timeline) => createHash('sha256').update(JSON.stringify(timeline)).digest('hex')
+export function syncRevision(dir, timeline) {
+  const music = timeline.audio?.find((cue) => cue.id === timeline.sync?.musicCueId)
+  if (timeline.sync?.analysisSourceHash && (!music || timeline.sync.analysisSourceHash !== filmHash(assetPath(dir, music.file)))) throw new Error('音乐文件已变更，请重新 motion_sync bind 分析后绑定')
+  const hash = createHash('sha256').update(syncKey(timeline))
+  for (const shot of timeline.shots) {
+    const file = join(dir, shot.file || '')
+    if (shot.file && existsSync(file)) hash.update(readFileSync(file))
+  }
+  for (const cue of timeline.audio || []) hash.update(readFileSync(assetPath(dir, cue.file)))
+  const walk = (path) => {
+    if (!existsSync(path)) return
+    for (const entry of readdirSync(path, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+      const file = join(path, entry.name)
+      if (entry.isDirectory()) walk(file)
+      else if (entry.isFile()) hash.update(entry.name).update(readFileSync(file))
+    }
+  }
+  walk(join(dir, 'components'))
+  walk(join(dir, 'assets'))
+  for (const entry of readdirSync(dir).sort()) if (/\.(tsx?|jsx?)$/.test(entry) && !/^index\./.test(entry)) hash.update(entry).update(readFileSync(join(dir, entry)))
+  return hash.digest('hex')
+}
+export const filmHash = (file) => createHash('sha256').update(readFileSync(file)).digest('hex')
+
+export function resolveSync(input) {
+  const timeline = structuredClone(input), sync = timeline.sync
+  if (!sync) return timeline
+  const fps = number(timeline.fps, 'fps')
+  if (sync.toleranceFrames !== undefined && (number(sync.toleranceFrames, 'toleranceFrames') < 0 || sync.toleranceFrames > 3)) throw new Error('toleranceFrames 必须在0–3内')
+  if (fps <= 0 || !Array.isArray(sync.anchors) || !sync.anchors.length || sync.anchors.length > 200) throw new Error('sync 需要 1–200 个 anchors')
+  const music = timeline.audio?.find((cue) => cue.id === sync.musicCueId)
+  if (!music || music.loop) throw new Error('sync.musicCueId 必须指向不循环的音乐轨')
+  const offset = sync.outputOffsetSeconds === undefined ? 0 : number(sync.outputOffsetSeconds, 'outputOffsetSeconds')
+  if (Math.abs(offset) > 1) throw new Error('输出偏移超出 ±1 秒')
+  const ids = new Set(), targets = new Set(), cueIds = new Set()
+  const rows = sync.anchors.map((anchor) => {
+    if (typeof anchor.id !== 'string' || !anchor.id || ids.has(anchor.id)) throw new Error('anchor.id 必须唯一')
+    ids.add(anchor.id)
+    if (anchor.visual) visualPeak(Buffer.alloc(0), 1, 1, 0, anchor.visual)
+    if (anchor.sfx !== undefined && !Array.isArray(anchor.sfx)) throw new Error('sfx 必须是绑定数组')
+    if (!['cut', 'action'].includes(anchor.type)) throw new Error('anchor.type 必须是 cut/action')
+    const shot = timeline.shots.find((item) => item.id === anchor.shotId)
+    if (!shot) throw new Error('锚点引用了不存在的镜头：' + anchor.shotId)
+    const targetKey = anchor.type + ':' + anchor.shotId + ':' + (anchor.type === 'action' ? anchor.name : '')
+    if (targets.has(targetKey)) throw new Error('同一个切镜或动作不能重复绑定')
+    targets.add(targetKey)
+    if (anchor.type === 'action' && (typeof anchor.name !== 'string' || !anchor.name)) throw new Error('动作锚点需要 name')
+    if ((anchor.at === undefined) === (anchor.beat === undefined)) throw new Error('锚点必须且只能给 at（源音乐秒）或 beat（0 起拍号）')
+    let sourceSeconds
+    if (anchor.at !== undefined) sourceSeconds = number(anchor.at, 'at')
+    else {
+      const grid = sync.analysis?.grid
+      if (!grid || ![grid.t0, grid.periodMs, grid.residualMs, grid.coverage].every(Number.isFinite) || grid.periodMs <= 0 || grid.residualMs > 15 || grid.coverage < 0.45) throw new Error('按拍号绑定需要通过验收的音乐网格；否则使用 at 实测瞬态')
+      const beat = number(anchor.beat, 'beat')
+      if (beat < 0) throw new Error('beat 必须从0起')
+      sourceSeconds = grid.t0 + beat * grid.periodMs / 1000
+    }
+    const musicLocal = sourceSeconds - (music.trimStart || 0)
+    if (musicLocal < 0 || musicLocal * fps >= music.durationInFrames) throw new Error('拍点超出音乐播放窗口：' + anchor.id)
+    const seconds = music.from / fps + musicLocal + offset
+    const frame = Math.round(seconds * fps)
+    if (frame < 0 || frame >= timeline.durationInFrames) throw new Error('锚点超出影片范围：' + anchor.id)
+    if (anchor.type === 'cut') shot.startFrame = frame
+    return { ...anchor, sourceSeconds, seconds, frame, quantizationMs: (frame / fps - seconds) * 1000 }
+  })
+  for (let i = 0; i < timeline.shots.length; i++) {
+    const shot = timeline.shots[i], end = timeline.shots[i + 1]?.startFrame ?? timeline.durationInFrames
+    if (shot.startFrame < 0 || end <= shot.startFrame) throw new Error('切镜绑定导致镜头倒序或长度为零')
+    shot.durationFrames = end - shot.startFrame
+    shot.anchors = Object.create(null)
+  }
+  for (const row of rows) {
+    const shot = timeline.shots.find((item) => item.id === row.shotId)
+    if (row.frame < shot.startFrame || row.frame >= shot.startFrame + shot.durationFrames) throw new Error('动作锚点不在所属镜头内：' + row.id)
+    if (row.type === 'action') shot.anchors[row.name] = row.frame - shot.startFrame
+    for (const sfx of row.sfx || []) {
+      if (cueIds.has(sfx.cueId) || sfx.cueId === music.id) throw new Error('音效轨不能重复绑定或绑定音乐自身')
+      cueIds.add(sfx.cueId)
+      const cue = timeline.audio.find((item) => item.id === sfx.cueId)
+      if (!cue || cue.loop) throw new Error('音效绑定需要存在且不循环的 cueId')
+      const lag = number(sfx.peakSeconds, 'peakSeconds') - (cue.trimStart || 0)
+      if (lag < 0 || lag * fps >= cue.durationInFrames) throw new Error('音效峰值超出裁剪窗口')
+      const from = Math.round(row.frame - (lag + offset) * fps)
+      if (from < 0 || from + cue.durationInFrames > timeline.durationInFrames) throw new Error('音效绑定超出影片范围，不会静默截断')
+      cue.from = from
+    }
+  }
+  sync.resolved = rows
+  return timeline
+}
+
+// Normalized waveform matching around an expected transient. Low/ambiguous
+// matches remain unverified; absence of evidence must never become a pass.
+export function matchTransient(source, output, sourceAt, expectedAt, sampleRate, searchSeconds = 0.2) {
+  const radius = Math.round(sampleRate * 0.025), center = Math.round(sourceAt * sampleRate)
+  const step = 4, template = []
+  for (let i = -radius; i <= radius; i += step) template.push(source[center + i] || 0)
+  const norm = Math.sqrt(template.reduce((sum, x) => sum + x * x, 0))
+  if (!norm) return null
+  let best = { score: -1, at: 0 }, second = -1
+  const scores = []
+  const start = Math.max(radius, Math.round((expectedAt - searchSeconds) * sampleRate)), end = Math.min(output.length - radius - 1, Math.round((expectedAt + searchSeconds) * sampleRate))
+  for (let at = start; at <= end; at++) {
+    let dot = 0, energy = 0
+    for (let i = 0; i < template.length; i++) { const x = output[at - radius + i * step]; dot += template[i] * x; energy += x * x }
+    const score = energy ? dot / (norm * Math.sqrt(energy)) : 0
+    scores.push({ at, score })
+    if (score > best.score) best = { at, score }
+  }
+  for (const candidate of scores) if (Math.abs(candidate.at - best.at) > sampleRate * 0.01) second = Math.max(second, candidate.score)
+  return best.score >= 0.45 && best.score - second >= 0.05 ? { at: best.at / sampleRate, confidence: best.score } : null
+}
+function samples(decoded) {
+  return Float64Array.from({ length: decoded.pcm.length / 2 }, (_, i) => decoded.pcm.readInt16LE(i * 2) / 32768)
+}
+
+export function visualPeak(bytes, width, height, firstFrame, visual = {}) {
+  if (visual.metric !== undefined && !['change', 'brightness'].includes(visual.metric)) throw new Error('visual.metric 必须为 change/brightness')
+  if (visual.minSignal !== undefined && (number(visual.minSignal, 'minSignal') <= 0 || visual.minSignal > 255)) throw new Error('minSignal 必须在0–255内')
+  const size = width * height, count = Math.floor(bytes.length / size), scores = []
+  const roi = visual.roi || { x: 0, y: 0, w: 1, h: 1 }
+  for (const key of ['x', 'y', 'w', 'h']) number(roi[key], 'visual.roi.' + key)
+  if (roi.x < 0 || roi.y < 0 || roi.w <= 0 || roi.h <= 0 || roi.x + roi.w > 1 || roi.y + roi.h > 1) throw new Error('ROI 必须在 0–1 内')
+  for (let f = 1; f < count; f++) {
+    let sum = 0, n = 0
+    for (let y = Math.floor(roi.y * height); y < Math.ceil((roi.y + roi.h) * height); y++) for (let x = Math.floor(roi.x * width); x < Math.ceil((roi.x + roi.w) * width); x++) {
+      const i = y * width + x
+      sum += visual.metric === 'brightness' ? bytes[f * size + i] : Math.abs(bytes[f * size + i] - bytes[(f - 1) * size + i]); n++
+    }
+    scores.push({ frame: firstFrame + f, score: sum / n })
+  }
+  scores.sort((a, b) => b.score - a.score)
+  const best = scores[0], other = scores.find((item) => Math.abs(item.frame - best?.frame) > 1)
+  return best && best.score >= (visual.minSignal ?? 8) && (!other || best.score > other.score * 1.15) ? best : null
+}
+
+export async function verifySync(dir, film, input) {
+  const timeline = resolveSync(input), sync = timeline.sync
+  if (!sync?.resolved?.length) throw new Error('尚未绑定锚点，先 motion_sync bind')
+  const revision = syncRevision(dir, timeline)
+  const receiptPath = film + '.sync.json'
+  const receipt = existsSync(receiptPath) ? parseProjectJson(readFileSync(receiptPath, 'utf8')) : null
+  if (receipt && receipt.revision !== revision) throw new Error('成片与当前绑定或场景版本不一致，请重新渲染后验收')
+  if (receipt && receipt.filmHash !== filmHash(film)) throw new Error('成片文件与渲染回执不一致，请重新渲染')
+  const out = join(dir, '.out', 'qa', 'sync'); mkdirSync(out, { recursive: true })
+  const decoded = await decodePcm(film), output = samples(decoded), rate = decoded.sampleRate
+  const cache = new Map()
+  const load = async (cue) => {
+    const path = assetPath(dir, cue.file)
+    if (!cache.has(path)) cache.set(path, samples(await decodePcm(path)))
+    return cache.get(path)
+  }
+  const music = timeline.audio.find((cue) => cue.id === sync.musicCueId), musicSource = await load(music)
+  const rows = [], offsets = []
+  for (const [index, anchor] of sync.resolved.entries()) {
+    const heard = matchTransient(musicSource, output, anchor.sourceSeconds, anchor.seconds, rate)
+    if (heard) offsets.push(heard.at - (music.from / timeline.fps + anchor.sourceSeconds - (music.trimStart || 0)))
+    let visual = null
+    // A cut is an observable frame difference. Continuous actions need an
+    // explicitly selected metric/ROI; do not infer their semantic peak.
+    if (anchor.type === 'cut' || anchor.visual) {
+      const first = Math.max(0, anchor.frame - 6), last = Math.min(timeline.durationInFrames - 1, anchor.frame + 6)
+      const path = join(out, 'anchor-' + index + '.gray')
+      try {
+        await runFfmpeg(['-loglevel', 'error', '-i', film, '-vf', 'select=between(n\\,' + first + '\\,' + last + '),scale=96:54,format=gray', '-vsync', '0', '-f', 'rawvideo', path], { cwd: dir, log: join(out, 'visual.log') })
+        visual = visualPeak(readFileSync(path), 96, 54, first, anchor.visual)
+        unlinkSync(join(out, 'visual.log'))
+      } finally {
+        if (existsSync(path)) unlinkSync(path)
+      }
+    }
+    const sfxRows = []
+    for (const binding of anchor.sfx || []) {
+      const cue = timeline.audio.find((item) => item.id === binding.cueId)
+      const match = await load(cue).then((source) => matchTransient(source, output, binding.peakSeconds, anchor.frame / timeline.fps, rate))
+      sfxRows.push({ cueId: cue.id, measuredSeconds: match?.at ?? null, confidence: match?.confidence ?? null,
+        errorFrames: match && heard ? (match.at - heard.at) * timeline.fps : null })
+    }
+    const error = heard && visual ? visual.frame - heard.at * timeline.fps : null
+    const tolerance = sync.toleranceFrames ?? 2
+    const status = error === null || sfxRows.some((item) => item.errorFrames === null) ? 'unverified'
+      : Math.abs(error) > tolerance || sfxRows.some((item) => Math.abs(item.errorFrames) > tolerance) ? 'fail' : 'pass'
+    rows.push({ id: anchor.id, type: anchor.type, plannedFrame: anchor.frame, quantizationMs: anchor.quantizationMs,
+      measuredMusicSeconds: heard?.at ?? null, musicConfidence: heard?.confidence ?? null, measuredVisualFrame: visual?.frame ?? null,
+      audiovisualErrorFrames: error, sfx: sfxRows, status })
+  }
+  offsets.sort((a, b) => a - b)
+  const report = { version: 1, film, timelineKey: revision, renderReceipt: !!receipt, fps: timeline.fps, generatedAt: new Date().toISOString(),
+    status: rows.some((row) => row.status === 'fail') ? 'fail' : rows.some((row) => row.status === 'unverified') ? 'unverified' : 'pass',
+    measuredOutputOffsetSeconds: offsets.length >= 3 && offsets.at(-1) - offsets[0] < 0.015 ? offsets[Math.floor(offsets.length / 2)] : null,
+    rows }
+  if (!receipt) report.status = report.status === 'fail' ? 'fail' : 'unverified'
+  writeFileSync(join(out, 'report.json'), JSON.stringify(report, null, 2))
+  return report
+}

package/lib/motion/theme.js

@@ -0,0 +1,121 @@
+// 主题：把"一套配色"变成一个可以 import 的 theme.ts。
+//
+// 上游 template/src/themes 里有 8 套 palettes（page/surface/field/text/muted/
+// accent/border），但工程模板从来不引用它们——每条片子都从素骨架开始，配色
+// 只能靠场景代码里手写十六进制。这里把那条线接上：
+//
+//   createProject(dir, { theme: 'vintage-kraft' })  → 生成 theme.ts
+//   scene-*.tsx 里 import { PAPER, INK, STAMP } from './theme'
+//
+// theme.ts 是普通源码，agent 照样可以改；theme.json 只记"这条片子用的哪套"。
+
+import { existsSync, readFileSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { parseProjectJson } from './json.js'
+
+const PALETTES = new URL('./shotcraft/upstream/template/src/themes/palettes.json', import.meta.url)
+
+// 兜底：注册表读不到时也能建工程。这套就是本片用的纸墨色。
+const FALLBACK = {
+  'paper-ink': { page: '#EDE8DE', surface: '#F5F1E8', field: '#E4DED2', text: '#2A2724', muted: '#8C8375', accent: '#B23A2E', border: '#CFC7B8' },
+}
+
+export function paletteTable() {
+  try {
+    const table = JSON.parse(readFileSync(PALETTES, 'utf8'))
+    if (table && typeof table === 'object' && !Array.isArray(table)) return { ...FALLBACK, ...table }
+  } catch {
+    /* 读不到就用兜底 */
+  }
+  return { ...FALLBACK }
+}
+
+export function listThemes() {
+  return Object.entries(paletteTable()).map(([name, tokens]) => ({ name, page: tokens.page, accent: tokens.accent }))
+}
+
+const HEX = /^#[0-9a-fA-F]{3,8}$/
+
+// 也接受直接给一套色（对象），方便"这条片子就想要这个纸色"的一次性需求。
+export function resolveTheme(input) {
+  if (input && typeof input === 'object' && !Array.isArray(input)) {
+    const tokens = normalizeTokens(input)
+    return { name: String(input.name || 'custom'), tokens, custom: true }
+  }
+  const name = String(input || '').trim()
+  if (!name) return null
+  const table = paletteTable()
+  const tokens = table[name]
+  if (!tokens) throw new Error('没有这套主题：' + name + '。可选：' + Object.keys(table).join('、'))
+  return { name, tokens: normalizeTokens(tokens) }
+}
+
+function normalizeTokens(input) {
+  const pick = (keys, fallback) => {
+    for (const key of keys) if (typeof input[key] === 'string' && HEX.test(input[key].trim())) return input[key].trim()
+    return fallback
+  }
+  return {
+    page: pick(['page', 'paper', 'background', 'bg'], FALLBACK['paper-ink'].page),
+    surface: pick(['surface', 'card'], FALLBACK['paper-ink'].surface),
+    field: pick(['field', 'panel'], FALLBACK['paper-ink'].field),
+    text: pick(['text', 'ink', 'foreground', 'fg'], FALLBACK['paper-ink'].text),
+    muted: pick(['muted', 'dust', 'secondary'], FALLBACK['paper-ink'].muted),
+    accent: pick(['accent', 'stamp', 'highlight'], FALLBACK['paper-ink'].accent),
+    border: pick(['border', 'rule', 'line'], FALLBACK['paper-ink'].border),
+  }
+}
+
+export const DEFAULT_FONTS = {
+  serif: '"Noto Serif SC", "Songti SC", "Source Han Serif SC", serif',
+  sans: '"Noto Sans SC", "PingFang SC", "Microsoft YaHei", sans-serif',
+  mono: '"JetBrains Mono", monospace',
+}
+
+// 场景文件只认这几个名字：PAPER / INK / DUST / STAMP / SURFACE / FIELD / BORDER。
+export function themeSource(theme, fonts = {}) {
+  const t = theme.tokens
+  const f = { ...DEFAULT_FONTS, ...fonts }
+  const fallback = (value, family, generic) => {
+    const text = String(value || DEFAULT_FONTS[generic === 'serif' ? 'serif' : 'sans'])
+    if (text.includes(family)) return text
+    return text.replace(/,?\s*(sans-serif|serif)\s*$/i, '') + ', "' + family + '", ' + generic
+  }
+  f.serif = fallback(f.serif, 'Noto Serif SC', 'serif')
+  f.sans = fallback(f.sans, 'Noto Sans SC', 'sans-serif')
+  const q = (value) => "'" + String(value).replace(/\\/g, '\\\\').replace(/'/g, "\\'") + "'"
+  return [
+    '// 主题：' + theme.name + '（由 motion_project 的 theme 参数生成，可以手改）',
+    'export const THEME_NAME = ' + q(theme.name),
+    'export const PAPER = ' + q(t.page) + '   // 纸',
+    'export const SURFACE = ' + q(t.surface),
+    'export const FIELD = ' + q(t.field),
+    'export const INK = ' + q(t.text) + '     // 墨',
+    'export const DUST = ' + q(t.muted) + '    // 次级文字',
+    'export const STAMP = ' + q(t.accent) + '   // 唯一的强调色',
+    'export const BORDER = ' + q(t.border),
+    '',
+    'export const SERIF = ' + q(f.serif),
+    'export const SANS = ' + q(f.sans),
+    'export const MONO = ' + q(f.mono),
+    '',
+    'export const TOKENS = ' + JSON.stringify(t, null, 2) + ' as const',
+    '',
+  ].join('\n')
+}
+
+export function writeTheme(dir, theme, fonts) {
+  writeFileSync(join(dir, 'theme.ts'), themeSource(theme, fonts), 'utf8')
+  writeFileSync(join(dir, 'theme.json'), JSON.stringify({ name: theme.name, tokens: theme.tokens, at: new Date().toISOString() }, null, 2) + '\n', 'utf8')
+  return { file: join(dir, 'theme.ts'), name: theme.name, tokens: theme.tokens }
+}
+
+export function readTheme(dir) {
+  const file = join(dir, 'theme.json')
+  if (!existsSync(file)) return null
+  try {
+    return parseProjectJson(readFileSync(file, 'utf8'))
+  } catch {
+    return null
+  }
+}