dsh-drawai 0.2.7 → 0.3.1

package/lib/video-export-worker.js

@@ -0,0 +1,58 @@
+/* 由 tools/build.mjs 生成 —— 请勿直接编辑；改 src/ 下的源文件。 */
+import { parentPort, workerData } from 'node:worker_threads'
+import { readFileSync, writeFileSync, realpathSync, statSync } from 'node:fs'
+import { resolve, relative, isAbsolute, join } from 'node:path'
+import { Resvg } from '@resvg/resvg-js'
+import { MAX_FRAME_SVG_CHARS } from './media.js'
+
+// Rendering must not acquire filesystem/network resources referenced by SVGs.
+export function validateExportSvg(svg) {
+  if (svg.length > MAX_FRAME_SVG_CHARS || !/<svg\b/i.test(svg)) throw new Error('导出帧不是有效尺寸的 SVG')
+  if (/<!DOCTYPE|<!ENTITY|<\?xml-stylesheet|@import|<foreignObject\b/i.test(svg)) throw new Error('导出帧包含不支持的外部资源或 foreignObject')
+  for (const match of svg.matchAll(/(?:\b(?:xlink:)?href)\s*=\s*(["'])(.*?)\1/gis)) {
+    if (!/^(?:#|data:image\/(?:png|jpe?g|gif|webp);base64,)/i.test(match[2].trim())) throw new Error('导出帧不能引用外部图片或文件')
+  }
+  for (const match of svg.matchAll(/url\(\s*(["']?)(.*?)\1\s*\)/gis)) {
+    if (!match[2].trim().startsWith('#')) throw new Error('导出帧不能引用外部 CSS 资源')
+  }
+}
+
+export function renderExportFrame(svg, width, height) {
+  validateExportSvg(svg)
+  // Parse the actual document first: an invalid nested SVG image would
+  // otherwise be silently omitted by the outer viewport wrapper.
+  const normalized = new Resvg(svg, { font: { loadSystemFonts: /<text\b/i.test(svg) } }).toString()
+  // Match drawImage(..., w, h): stretch the intrinsic SVG viewport to the
+  // manifest dimensions, retaining its own viewBox/clip behavior inside it.
+  const wrapper = '<svg xmlns="http://www.w3.org/2000/svg" width="' + width + '" height="' + height + '">' +
+    '<image width="100%" height="100%" preserveAspectRatio="none" href="data:image/svg+xml;base64,' +
+    Buffer.from(normalized).toString('base64') + '"/></svg>'
+  const image = new Resvg(wrapper, { background: 'white', font: { loadSystemFonts: false } }).render()
+  if (image.width !== width || image.height !== height) throw new Error('宿主渲染尺寸与视频不一致')
+  return image.asPng()
+}
+
+if (parentPort) {
+  try {
+    const root = realpathSync(workerData.dir)
+    let bytes = 0, last = 0
+    for (let index = 0; index < workerData.frames.length; index++) {
+      const file = workerData.frames[index].file
+      if (typeof file !== 'string' || isAbsolute(file)) throw new Error('导出帧路径无效')
+      const absolute = realpathSync(resolve(root, file))
+      const rel = relative(root, absolute)
+      if (isAbsolute(rel) || rel === '..' || rel.startsWith('../') || rel.startsWith('..\\')) throw new Error('导出帧路径超出媒体包')
+      if (statSync(absolute).size > MAX_FRAME_SVG_CHARS * 4) throw new Error('导出帧 SVG 过大')
+      const begin = performance.now()
+      const png = renderExportFrame(readFileSync(absolute, 'utf8'), workerData.w, workerData.h)
+      writeFileSync(join(workerData.temp, 'frame-' + String(index).padStart(8, '0') + '.png'), png)
+      bytes += png.length
+      parentPort.postMessage({ type: 'timing', ms: performance.now() - begin })
+      if (Date.now() - last > 100 || index + 1 === workerData.frames.length) {
+        parentPort.postMessage({ type: 'progress', rendered: index + 1, bytes }); last = Date.now()
+      }
+    }
+    parentPort.postMessage({ type: 'done', rendered: workerData.frames.length, bytes })
+  } catch (error) { parentPort.postMessage({ type: 'error', error: String(error.message || error) }) }
+  parentPort.close()
+}

package/lib/video-export.js

@@ -0,0 +1,304 @@
+/* 由 tools/build.mjs 生成 —— 请勿直接编辑；改 src/ 下的源文件。 */
+/** Offline export: frame index, not wall-clock time, determines each timestamp. */
+import { spawn } from 'node:child_process'
+import { randomUUID } from 'node:crypto'
+import { Worker } from 'node:worker_threads'
+import { copyFile } from 'node:fs/promises'
+import { existsSync, mkdirSync, mkdtempSync, rmSync, renameSync, statSync, openSync, readSync, closeSync, realpathSync, readFileSync, writeFileSync, readdirSync } from 'node:fs'
+import { join, relative, isAbsolute, extname, dirname, basename } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { clipDirFor, readManifest, findSourceFile, sanitizeClipId } from './media.js'
+import { createPerformanceLog } from './performance-log.js'
+
+function runFfmpeg(binary, args, signal, progress) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(binary, args, { windowsHide: true, shell: false, stdio: ['ignore', 'pipe', 'pipe'] })
+    let errorText = '', line = ''
+    const abort = () => child.kill()
+    signal.addEventListener('abort', abort, { once: true })
+    if (signal.aborted) abort()
+    child.stdout.on('data', (bytes) => {
+      line += bytes.toString()
+      const lines = line.split(/\r?\n/); line = lines.pop()
+      for (const entry of lines) if (entry.startsWith('frame=')) progress?.(Number(entry.slice(6)))
+    })
+    child.stderr.on('data', (bytes) => { errorText = (errorText + bytes.toString()).slice(-8000) })
+    child.on('error', (error) => {
+      signal.removeEventListener('abort', abort)
+      reject(new Error(error.code === 'ENOENT' ? '未找到 FFmpeg，请安装到 PATH，或设置 DRAWAI_FFMPEG_PATH 为可执行文件路径' : error.message))
+    })
+    child.on('close', (code) => {
+      signal.removeEventListener('abort', abort)
+      if (signal.aborted) reject(new Error('已取消视频导出'))
+      else if (code !== 0) reject(new Error('FFmpeg 编码失败：' + errorText.trim()))
+      else resolve()
+    })
+  })
+}
+
+export function ffmpegBinary() {
+  if (process.env.DRAWAI_FFMPEG_PATH) return process.env.DRAWAI_FFMPEG_PATH
+  // Development checkout only; published packages use the configured binary or PATH.
+  const local = fileURLToPath(new URL('../_local/bin/' + (process.platform === 'win32' ? 'ffmpeg.exe' : 'ffmpeg'), import.meta.url))
+  return existsSync(local) ? local : 'ffmpeg'
+}
+
+export function createVideoExportManager(options = {}) {
+  const jobs = new Map()
+  let closed = false
+  const binary = options.ffmpegPath || ffmpegBinary()
+  const historyRoot = (path) => join(dirname(path), '.drawai-cache', 'video-export-history')
+  const ended = (job) => ['done', 'error', 'interrupted'].includes(job.status)
+  function persist(job) {
+    const root = historyRoot(job.drawioAbs); mkdirSync(root, { recursive: true })
+    const record = Object.fromEntries(['sessionId', 'drawioAbs', 'clip', 'token', 'status', 'time', 'next', 'encoded', 'format', 'kind', 'w', 'h', 'fps', 'count', 'bytes', 'savedPath', 'error'].map((key) => [key, job[key]]))
+    const file = join(root, job.token + '.json')
+    writeFileSync(file + '.tmp', JSON.stringify(record)); renameSync(file + '.tmp', file)
+  }
+  function load(scope) {
+    const root = historyRoot(scope.drawioAbs)
+    if (!existsSync(root)) return
+    for (const name of readdirSync(root)) if (/^[a-f0-9-]{36}\.json$/.test(name) && !jobs.has(name.slice(0, -5))) {
+      try {
+        const data = JSON.parse(readFileSync(join(root, name), 'utf8'))
+        if (data.token + '.json' !== name || data.sessionId !== scope.sessionId || data.drawioAbs !== scope.drawioAbs || !sanitizeClipId(data.clip) || !['mp4', 'webm', 'gif'].includes(data.format)) continue
+        const expected = join(dirname(scope.drawioAbs), basename(scope.drawioAbs).replace(/\.drawio$/i, '') + '-' + data.clip + '-' + data.token + '.' + data.format)
+        if (data.status === 'done' && (data.savedPath !== expected || !existsSync(expected) ||
+            isAbsolute(relative(realpathSync(dirname(scope.drawioAbs)), realpathSync(expected))) || relative(realpathSync(dirname(scope.drawioAbs)), realpathSync(expected)).startsWith('..'))) {
+          data.status = 'error'; data.error = '已导出的文件已移动或删除'; data.savedPath = null
+        }
+        if (!ended(data)) { data.status = 'interrupted'; data.error = '宿主曾停止，可选择重新导出；编码进度不能直接续传' }
+        const job = { ...data, output: data.savedPath, control: new AbortController(),
+          temp: join(dirname(scope.drawioAbs), '.drawai-cache', 'video-exports', 'restored-' + data.token),
+          perf: createPerformanceLog(dirname(scope.drawioAbs), 'video-export', {}, { enabled: false }) }
+        jobs.set(job.token, job); persist(job)
+      } catch { /* Ignore damaged history without hiding healthy tasks. */ }
+    }
+  }
+  function view(job) {
+    return { token: job.token, status: job.status, count: job.count, received: job.next, encoded: job.encoded,
+      clip: job.clip, fps: job.fps, w: job.w, h: job.h, bytes: job.bytes || 0, error: job.error || '', format: job.format,
+      background: true, path: job.savedPath || null,
+      performanceEnabled: job.perf.enabled, performanceId: job.perf.id }
+  }
+  function owned(scope, token) {
+    load(scope)
+    const job = jobs.get(token)
+    if (!job || job.sessionId !== scope.sessionId || job.drawioAbs !== scope.drawioAbs || job.clip !== scope.clip) throw new Error('视频导出任务已失效或不属于当前画布')
+    job.time = Date.now()
+    return job
+  }
+  async function remove(job) {
+    jobs.delete(job.token)
+    job.control.abort()
+    if (job.preflight) await job.preflight.catch(() => {})
+    if (job.promise) await job.promise.catch(() => {})
+    job.perf.finish(job.status === 'done' ? 'done' : job.status === 'error' ? 'failed' : 'cancelled')
+    rmSync(job.temp, { recursive: true, force: true })
+    rmSync(join(historyRoot(job.drawioAbs), job.token + '.json'), { force: true })
+  }
+  function renderFrames(job) {
+    return new Promise((resolve, reject) => {
+      const worker = new Worker(options.workerUrl || new URL('./video-export-worker.js', import.meta.url), {
+        workerData: { dir: job.dir, frames: job.frames, temp: job.temp, w: job.w, h: job.h },
+      })
+      let settled = false
+      const abort = () => finish(new Error('已取消视频导出'))
+      const finish = (error) => {
+        if (settled) return
+        settled = true; job.control.signal.removeEventListener('abort', abort)
+        // Wait for native rendering to exit before removing its directory.
+        worker.terminate().then(() => error ? reject(error) : resolve(), reject)
+      }
+      worker.on('message', (message) => {
+        if (settled) return
+        if (message.type === 'timing') job.perf.add('hostSvgRender', message.ms)
+        if (message.type === 'progress' || message.type === 'done') {
+          job.next = message.rendered; job.tempBytes = (job.source ? statSync(job.source).size : 0) + message.bytes
+          job.perf.peak('tempInputBytes', job.tempBytes)
+        }
+        if (message.type === 'done') finish()
+        if (message.type === 'error') finish(new Error(message.error))
+      })
+      worker.on('error', finish)
+      worker.on('exit', (code) => { if (!settled) finish(new Error('导出渲染线程意外退出（' + code + '）')) })
+      job.control.signal.addEventListener('abort', abort, { once: true })
+      if (job.control.signal.aborted) abort()
+    })
+  }
+  async function runJob(job) {
+    let release
+    try {
+      release = await options.slots?.acquire(job.control.signal)
+      job.status = 'rendering'
+      persist(job)
+      if (job.kind === 'svg') {
+        await renderFrames(job)
+        job.perf.count('renderedFrames', job.next)
+      }
+      if (job.control.signal.aborted) throw new Error('已取消视频导出')
+      job.status = 'encoding'
+      persist(job)
+      await encode(job)
+      if (job.status === 'error') throw new Error(job.error)
+      if (job.control.signal.aborted) throw new Error('已取消视频导出')
+      // Persist independently of the browser's progress polling or download.
+      const name = basename(job.drawioAbs).replace(/\.drawio$/i, '') + '-' + job.clip + '-' + job.token + '.' + job.format
+      const path = join(dirname(job.drawioAbs), name)
+      renameSync(job.output, path)
+      job.output = path; job.savedPath = path; job.status = 'done'; job.time = Date.now()
+      persist(job)
+      job.perf.finish('done')
+    } catch (error) {
+      job.status = closed ? 'interrupted' : 'error'; job.error = String(error.message || error); job.time = Date.now()
+      persist(job)
+      job.perf.finish(job.control.signal.aborted ? 'cancelled' : 'failed')
+    } finally { release?.(); rmSync(job.temp, { recursive: true, force: true }) }
+  }
+  async function encode(job) {
+    const gifWhite = '[0:v:0]split[foreground][background];[background]lutrgb=r=255:g=255:b=255,format=rgb24[white];' +
+      '[white][foreground]overlay=shortest=1:format=rgb[opaque];'
+    const args = ['-hide_banner', '-nostdin', '-loglevel', 'error', '-y']
+    if (job.kind === 'svg') args.push('-framerate', String(job.fps), '-start_number', '0', '-i', join(job.temp, 'frame-%08d.png'))
+    else args.push('-protocol_whitelist', 'file,pipe', '-i', job.source)
+    if (job.kind === 'svg' && job.source) args.push('-ss', String(job.offset), '-protocol_whitelist', 'file,pipe', '-i', job.source)
+    if (job.format === 'gif') {
+      args.push('-i', join(job.temp, 'palette.png'), '-filter_complex',
+        gifWhite + '[opaque][1:v:0]paletteuse=dither=sierra2_4a:diff_mode=rectangle[gif]',
+        '-map', '[gif]', '-an', '-fps_mode', 'cfr', '-r', String(job.fps))
+    } else {
+      args.push('-map', '0:v:0')
+      if (job.source) args.push('-map', job.kind === 'svg' ? '1:a:0?' : '0:a:0?')
+      // PNGs are painted over white by the client. Pad odd dimensions for yuv420p.
+      args.push('-vf', 'pad=ceil(iw/2)*2:ceil(ih/2)*2:0:0:color=white,format=yuv420p', '-fps_mode', 'cfr')
+    }
+    if (job.kind === 'svg') {
+      args.push('-r', String(job.fps), '-t', String(job.count / job.fps))
+      if (job.source) args.push('-af', 'apad')
+    }
+    if (job.format === 'mp4') args.push('-c:v', 'libx264', '-preset', 'medium', '-crf', '18', '-c:a', 'aac', '-b:a', '192k', '-movflags', '+faststart')
+    else if (job.format === 'webm') args.push('-c:v', 'libvpx-vp9', '-crf', '28', '-b:v', '0', '-row-mt', '1', '-c:a', 'libopus', '-b:a', '128k')
+    else args.push('-c:v', 'gif', '-loop', '0')
+    args.push('-threads', '4', '-progress', 'pipe:1', job.output)
+    try {
+      if (job.format === 'gif') {
+        // Two passes keep a single stable palette without buffering the full
+        // video in a split/framesync filter graph. Input frames already live on disk.
+        const paletteArgs = ['-hide_banner', '-nostdin', '-loglevel', 'error', '-y']
+        if (job.kind === 'svg') paletteArgs.push('-framerate', String(job.fps), '-start_number', '0', '-i', join(job.temp, 'frame-%08d.png'))
+        else paletteArgs.push('-protocol_whitelist', 'file,pipe', '-i', job.source)
+        paletteArgs.push('-filter_complex', gifWhite + '[opaque]palettegen=max_colors=256:reserve_transparent=0:stats_mode=full[palette]', '-map', '[palette]',
+          '-frames:v', '1', '-threads', '1', '-update', '1', join(job.temp, 'palette.png'))
+        const paletteDone = job.perf.start('gifPaletteGenerate')
+        try { await runFfmpeg(binary, paletteArgs, job.control.signal) }
+        finally { paletteDone() }
+      }
+      const encodeDone = job.perf.start('ffmpegEncode')
+      try { await runFfmpeg(binary, args, job.control.signal, (frame) => { job.encoded = frame }) }
+      finally { encodeDone() }
+      if (job.kind === 'svg' && job.encoded !== job.count) throw new Error('输出帧数不完整：预期 ' + job.count + '，实际 ' + job.encoded)
+      job.bytes = statSync(job.output).size
+      if (!job.bytes) throw new Error('视频编码结果为空')
+      job.status = 'done'
+      job.perf.peak('tempTotalBytes', (job.tempBytes || (job.source ? statSync(job.source).size : 0)) + job.bytes);
+      job.perf.count('outputBytes', job.bytes); job.perf.count('encodedFrames', job.encoded)
+    } catch (error) { job.status = 'error'; job.error = error.message || String(error) }
+  }
+  return {
+    async start(scope, format) {
+      if (closed) throw new Error('视频导出服务已关闭')
+      load(scope)
+      if (!sanitizeClipId(scope.clip) || !['mp4', 'webm', 'gif'].includes(format)) throw new Error('无效视频导出参数')
+      for (const job of jobs.values()) if (['done', 'error'].includes(job.status) && Date.now() - job.time > 24 * 60 * 60 * 1000) await remove(job)
+      if ([...jobs.values()].filter((job) => !ended(job)).length >= 4) throw new Error('视频导出任务过多，请稍后重试')
+      const history = [...jobs.values()].filter(ended)
+      while (history.length >= 16) await remove(history.shift())
+      const dir = clipDirFor(scope.drawioAbs, scope.clip), manifest = readManifest(dir)
+      if (manifest.kind !== 'raster' && !manifest.frames.length) throw new Error('没有 SVG 帧可编码')
+      if (manifest.width * manifest.height > 16000000 || Math.max(manifest.width, manifest.height) > 16384 || !(manifest.fps > 0)) throw new Error('视频尺寸或帧率无效')
+      // GIF has no audio. SVG exports only need their rendered frames, even
+      // when the original audio source has since been removed.
+      const original = manifest.kind === 'raster' || format !== 'gif' ? findSourceFile(dir, manifest) : null
+      if (manifest.kind === 'raster' && !original) throw new Error('源视频缺失')
+      if (format !== 'gif' && manifest.source && !original) throw new Error('原片段音频来源缺失，无法保留音频')
+      if (original) {
+        const rel = relative(realpathSync(dir), realpathSync(original.abs))
+        if (rel.startsWith('..') || isAbsolute(rel)) throw new Error('音频或视频来源不在媒体包内')
+      }
+      // Child processes may lack write access to the OS temp directory on Windows.
+      // Keep transient files beside the writable canvas, outside its media package.
+      const cache = options.tempRoot || join(dirname(scope.drawioAbs), '.drawai-cache', 'video-exports')
+      mkdirSync(cache, { recursive: true })
+      const temp = mkdtempSync(join(cache, 'export-'))
+      const perf = createPerformanceLog(dirname(scope.drawioAbs), 'video-export', { ...options.metadata, format, kind: manifest.kind, fps: manifest.fps,
+        width: manifest.width, height: manifest.height, count: manifest.frames.length, encoderThreads: 4 }, { enabled: options.profile })
+      let job
+      try {
+        const sourceDone = perf.start('sourceSnapshot')
+        const source = original ? join(temp, 'source' + extname(original.abs)) : null
+        if (source) await copyFile(original.abs, source)
+        let inputDir = dir, frames = manifest.frames
+        if (manifest.kind === 'svg') {
+          inputDir = join(temp, 'input'); mkdirSync(inputDir)
+          frames = []
+          for (let index = 0; index < manifest.frames.length; index++) {
+            const frame = manifest.frames[index], file = join(dir, frame.file)
+            const rel = relative(realpathSync(dir), realpathSync(file))
+            if (isAbsolute(rel) || rel.startsWith('..')) throw new Error('SVG 帧路径超出媒体包')
+            const name = index + '.svg'; await copyFile(file, join(inputDir, name))
+            frames.push({ ...frame, file: name })
+          }
+        }
+        sourceDone()
+        if (closed) throw new Error('视频导出服务已关闭')
+        job = { ...scope, dir: inputDir, frames, perf, token: randomUUID(), temp, source, format, kind: manifest.kind, fps: manifest.fps,
+          w: manifest.width, h: manifest.height, count: manifest.kind === 'raster' ? 0 : manifest.frames.length, offset: manifest.sourceOffset || 0,
+          next: 0, received: 0, encoded: 0, status: 'queued', time: Date.now(), control: new AbortController(), output: join(temp, 'output.' + format) }
+        jobs.set(job.token, job)
+        persist(job)
+        // Probe the actual output path and encoder before uploading any large frames.
+        job.preflight = runFfmpeg(binary, ['-hide_banner', '-nostdin', '-loglevel', 'error', '-y', '-f', 'lavfi', '-i', 'color=white:s=2x2:r=1',
+          '-frames:v', '1', '-c:v', format === 'mp4' ? 'libx264' : format === 'gif' ? 'gif' : 'libvpx-vp9', '-threads', '1', job.output], job.control.signal)
+        const probeDone = perf.start('encoderPreflight')
+        try { await job.preflight }
+        catch (error) { throw new Error('导出预检查失败（目录：' + temp + '）：' + error.message) }
+        finally { probeDone() }
+        if (closed || job.control.signal.aborted) throw new Error('视频导出服务已关闭')
+        job.promise = runJob(job)
+        return view(job)
+      } catch (error) {
+        perf.finish('failed')
+        if (job) jobs.delete(job.token)
+        if (job) rmSync(join(historyRoot(job.drawioAbs), job.token + '.json'), { force: true })
+        rmSync(temp, { recursive: true, force: true })
+        throw error
+      }
+    },
+    // Compatibility endpoint: the task already runs after start, without a client finish call.
+    finish(scope, token) { return view(owned(scope, token)) },
+    list(scope) { load(scope); return [...jobs.values()].filter((job) => job.sessionId === scope.sessionId && job.drawioAbs === scope.drawioAbs).map(view) },
+    status(scope, token) { return view(owned(scope, token)) },
+    read(scope, token, offset) {
+      const job = owned(scope, token)
+      if (job.status !== 'done' || !Number.isSafeInteger(offset) || offset < 0 || offset >= job.bytes) throw new Error('导出文件未完成或读取位置无效')
+      if (statSync(job.output).size !== job.bytes) throw new Error('导出文件已被修改，请重新导出')
+      const bytes = Buffer.alloc(Math.min(1024 * 1024, job.bytes - offset)), fd = openSync(job.output, 'r')
+      const readDone = job.perf.start('outputReadAndBase64Encode')
+      try { readSync(fd, bytes, 0, bytes.length, offset) } finally { closeSync(fd) }
+      const base64 = bytes.toString('base64')
+      readDone(); job.perf.count('downloadedBytes', bytes.length)
+      return { ok: true, offset, bytes: bytes.length, base64, total: job.bytes }
+    },
+    async discard(scope, token, performance) { const job = owned(scope, token); job.perf.merge('browser.', performance); await remove(job); return { ok: true } },
+    leases(drawioAbs) { return [...jobs.values()].filter((job) => job.drawioAbs === drawioAbs && !['done', 'error'].includes(job.status)).map((job) => job.clip) },
+    async dispose() {
+      closed = true
+      for (const job of jobs.values()) job.control.abort()
+      await Promise.allSettled([...jobs.values()].flatMap((job) => [job.preflight, job.promise]))
+      for (const job of jobs.values()) {
+        if (!ended(job)) { job.status = 'interrupted'; persist(job) }
+        rmSync(job.temp, { recursive: true, force: true })
+      }
+    },
+  }
+}

package/lib/video-trace-pool.js

@@ -0,0 +1,129 @@
+/* 由 tools/build.mjs 生成 —— 请勿直接编辑；改 src/ 下的源文件。 */
+/**
+ * 视频复刻常驻 Worker 池：复用线程，按任务令牌取消排队/在算任务。
+ */
+import { Worker } from 'node:worker_threads'
+import { cpus } from 'node:os'
+
+export function createVideoTracePool(options = {}) {
+  const size = options.size ?? Math.max(1, Math.min(4, Math.max(1, (cpus()?.length || 2) - 1)))
+  const workerUrl = options.workerUrl ?? new URL('./video-trace-worker.js', import.meta.url)
+  let nextId = 1
+  let closed = false
+  const idle = []
+  const queue = []
+  const busy = new Map()
+
+  function spawn() {
+    const worker = new Worker(workerUrl)
+    worker.on('message', (message) => finish(worker, message))
+    worker.on('error', (error) => fail(worker, error))
+    worker.on('exit', (code) => {
+      if (busy.has(worker)) fail(worker, new Error('复刻线程已停止（' + code + '）'))
+      const at = idle.indexOf(worker)
+      if (at >= 0) idle.splice(at, 1)
+    })
+    // 空闲时不拖住进程退出（测试与短命脚本）；接任务时再 ref。
+    if (typeof worker.unref === 'function') worker.unref()
+    return worker
+  }
+
+  function ensure() {
+    while (!closed && idle.length + busy.size < size) idle.push(spawn())
+  }
+
+  function pump() {
+    if (closed) return
+    ensure()
+    while (idle.length && queue.length) {
+      const worker = idle.pop()
+      const item = queue.shift()
+      const id = nextId++
+      const dispatched = performance.now()
+      if (typeof worker.ref === 'function') worker.ref()
+      busy.set(worker, { id, item, dispatched, queueWaitMs: dispatched - item.queuedAt })
+      try {
+        worker.postMessage({ id, png: item.png, raster: item.raster, options: item.options }, item.transfer || [])
+      } catch (error) {
+        busy.delete(worker)
+        if (typeof worker.unref === 'function') worker.unref()
+        idle.push(worker)
+        item.reject(error)
+      }
+    }
+  }
+
+  function finish(worker, message) {
+    const active = busy.get(worker)
+    if (!active) return
+    if (message && message.id !== active.id) return
+    busy.delete(worker)
+    if (!closed) {
+      if (typeof worker.unref === 'function') worker.unref()
+      idle.push(worker)
+    } else worker.terminate().catch(() => {})
+    if (!message || message.ok !== true) active.item.reject(new Error((message && message.error) || '复刻失败'))
+    else active.item.resolve({ ...message, queueWaitMs: active.queueWaitMs, workerRoundTripMs: performance.now() - active.dispatched })
+    pump()
+  }
+
+  function fail(worker, error) {
+    const active = busy.get(worker)
+    busy.delete(worker)
+    if (active) active.item.reject(error instanceof Error ? error : new Error(String(error)))
+    worker.terminate().catch(() => {})
+    if (!closed) pump()
+  }
+
+  function run(png, traceOptions, meta = {}) {
+    if (closed) return Promise.reject(new Error('复刻线程池已关闭'))
+    return new Promise((resolve, reject) => {
+      queue.push({ png, options: traceOptions, resolve, reject, token: meta.token, queuedAt: performance.now() })
+      pump()
+    })
+  }
+
+  function cancelToken(token) {
+    if (token === undefined || token === null) return
+    const kept = []
+    for (const item of queue) {
+      if (item.token === token) item.reject(new Error('已取消复刻'))
+      else kept.push(item)
+    }
+    queue.length = 0
+    for (const item of kept) queue.push(item)
+    for (const [worker, active] of Array.from(busy.entries())) {
+      if (active.item.token !== token) continue
+      busy.delete(worker)
+      active.item.reject(new Error('已取消复刻'))
+      worker.terminate().catch(() => {})
+    }
+    if (!closed) pump()
+  }
+
+  function close() {
+    if (closed) return
+    closed = true
+    for (const item of queue) item.reject(new Error('复刻线程池已关闭'))
+    queue.length = 0
+    for (const [worker, active] of busy) {
+      active.item.reject(new Error('复刻线程池已关闭'))
+      worker.terminate().catch(() => {})
+    }
+    busy.clear()
+    for (const worker of idle) worker.terminate().catch(() => {})
+    idle.length = 0
+  }
+
+  function runRaster(raster, traceOptions, meta = {}) {
+    if (closed) return Promise.reject(new Error('复刻线程池已关闭'))
+    // Copy into an owned allocation; never transfer a Node Buffer pool slab.
+    const pixels = new Uint8Array(raster.data.length); pixels.set(raster.data)
+    return new Promise((resolve, reject) => {
+      queue.push({ raster: { width: raster.width, height: raster.height, data: pixels }, transfer: [pixels.buffer], options: traceOptions,
+        resolve, reject, token: meta.token, queuedAt: performance.now() })
+      pump()
+    })
+  }
+  return { run, runRaster, cancelToken, close, get size() { return size } }
+}

package/lib/video-trace-reuse.js

@@ -0,0 +1,49 @@
+/* 由 tools/build.mjs 生成 —— 请勿直接编辑；改 src/ 下的源文件。 */
+import { createHash } from 'node:crypto'
+import { TRACE_DEFAULTS, TRACE_FRAGMENT_LEVELS, TRACE_PRESET_NAMES } from './trace-image.js'
+
+// Normalize/validate before an exact-cache lookup: a hit must not bypass validation.
+export function videoTraceOptions(raw, manifest, maxBytes) {
+  const level = raw.level === undefined ? 'medium' : raw.level
+  const preset = raw.preset === undefined ? 'default' : raw.preset
+  const colors = raw.colors === undefined ? TRACE_DEFAULTS.colors : Number(raw.colors)
+  if (!Object.prototype.hasOwnProperty.call(TRACE_FRAGMENT_LEVELS, level)) throw new Error('未知碎片程度')
+  if (!TRACE_PRESET_NAMES.includes(preset)) throw new Error('未知复刻画风')
+  if (!Number.isInteger(colors) || colors < 2 || colors > 24) throw new Error('颜色数须在 2–24 之间')
+  if (typeof raw.removeBg !== 'boolean') throw new Error('removeBg 必须为 true 或 false')
+  return { width: manifest.width, height: manifest.height, level, preset, colors, removeBg: raw.removeBg, maxBytes }
+}
+
+export function exactVideoFrameKey(png, optionsKey) {
+  // Equal uploaded PNG bytes guarantee equal decoded pixels. Different PNG encodings
+  // may miss this conservative cache; they always go through normal decoding.
+  return createHash('sha256').update(png).update('\0').update(optionsKey).digest('hex')
+}
+
+export function checkVideoPalette(work, foreground, palette) {
+  if (!Array.isArray(palette) || palette.length < 2 || palette.length > 24 ||
+      !palette.every((rgb) => Array.isArray(rgb) && rgb.length === 3 && rgb.every((c) => Number.isInteger(c) && c >= 0 && c <= 255))) {
+    return { accepted: false, reason: 'invalid-palette' }
+  }
+  // Check actual composited/downsampled foreground, not a global gray average.
+  // Any new bright/color detail can reject reuse, regardless of its area.
+  const seen = new Set()
+  for (const pixel of foreground) {
+    const at = pixel * 4, r = work[at], g = work[at + 1], b = work[at + 2]
+    const key = (r << 16) | (g << 8) | b
+    if (seen.has(key)) continue
+    let nearest = null, best = Infinity
+    for (const rgb of palette) {
+      const dr = r - rgb[0], dg = g - rgb[1], db = b - rgb[2]
+      const distance = dr * dr + dg * dg + db * db
+      if (distance < best) { best = distance; nearest = rgb }
+    }
+    const dr = r - nearest[0], dg = g - nearest[1], db = b - nearest[2]
+    const lumaError = Math.abs(0.299 * dr + 0.587 * dg + 0.114 * db)
+    if (lumaError > 8) return { accepted: false, reason: 'brightness-mismatch' }
+    if (Math.max(Math.abs(dr), Math.abs(dg), Math.abs(db)) > 12) return { accepted: false, reason: 'color-mismatch' }
+    // Bounded exact RGB memoization speeds up flat animation without sampling away details.
+    if (seen.size < 4096) seen.add(key)
+  }
+  return { accepted: true, reason: 'fits-foreground' }
+}

package/lib/video-trace-worker.js

@@ -0,0 +1,61 @@
+/* 由 tools/build.mjs 生成 —— 请勿直接编辑；改 src/ 下的源文件。 */
+// 单帧复刻在独立线程计算；支持常驻消息循环（池）与一次性 workerData（兼容）。
+import { parentPort, workerData } from 'node:worker_threads'
+import { decodeRaster } from './raster.js'
+import { traceRasterForToolbar, traceRasterToSvg } from './trace-image.js'
+import { createPerformanceMetrics } from './performance-metrics.js'
+import { checkVideoPalette } from './video-trace-reuse.js'
+
+async function tracePng(png, rawOptions, rawRaster) {
+  const timing = rawOptions.profile === true ? createPerformanceMetrics() : null
+  const decodeDone = timing?.start('pngDecode')
+  const raster = rawRaster || await decodeRaster(Buffer.from(png))
+  decodeDone?.()
+  if (raster.width * raster.height > 16000000) throw new Error('图片超过 1600 万像素，请先缩小图片')
+  if (raster.data.length !== raster.width * raster.height * 4) throw new Error('原始像素长度无效')
+  if (rawOptions.mode === 'raw-image') return { ok: true, ...traceRasterToSvg(raster, rawOptions) }
+  if (rawOptions.mode === 'image') {
+    const result = traceRasterForToolbar(raster, { ...rawOptions, includeDrawing: true,
+      onTiming: timing ? (name, ms) => timing.add(name, ms) : undefined })
+    return { ok: true, ...result, rasterSize: { width: raster.width, height: raster.height },
+      ...(timing ? { performance: timing.snapshot() } : {}) }
+  }
+  const { width, height, ...options } = rawOptions
+  if (raster.width !== width || raster.height !== height) throw new Error('帧尺寸与任务不一致')
+  let paletteCheck = null
+  const result = traceRasterForToolbar(raster, { ...options, allowEmpty: true, onlySelectedLevel: true,
+    paletteValidator: (work, foreground, palette) => {
+      const checked = timing?.start('paletteValidation')
+      paletteCheck = checkVideoPalette(work, foreground, palette)
+      checked?.()
+      return paletteCheck.accepted
+    },
+    onTiming: timing ? (name, ms) => timing.add(name, ms) : undefined,
+    maxLongSide: Math.max(width, height) })
+  const hexes = Array.isArray(result.metrics.palette) ? result.metrics.palette : []
+  const used = options.removeBg ? hexes.slice(1) : hexes
+  const palette = used.map((hex) => {
+    const h = String(hex).replace('#', '')
+    return [parseInt(h.slice(0, 2), 16), parseInt(h.slice(2, 4), 16), parseInt(h.slice(4, 6), 16)]
+  }).filter((rgb) => rgb.length === 3 && rgb.every((n) => Number.isInteger(n)))
+  return { ok: true, svg: result.svg, detailReduced: result.metrics.detailReduced, work: result.metrics.work, palette,
+    paletteShared: paletteCheck?.accepted === true, paletteReuseReason: paletteCheck?.reason || 'fresh-palette',
+    ...(timing ? { performance: timing.snapshot() } : {}) }
+}
+
+async function handle(message) {
+  try {
+    const result = await tracePng(message.png, message.options, message.raster)
+    parentPort.postMessage(Object.assign({ id: message.id }, result))
+  } catch (error) {
+    parentPort.postMessage({ id: message.id, ok: false, error: error.message || String(error) })
+  }
+}
+
+if (workerData && workerData.png) {
+  handle({ id: 0, png: workerData.png, options: workerData.options }).catch((error) => {
+    parentPort.postMessage({ id: 0, ok: false, error: error.message || String(error) })
+  })
+} else {
+  parentPort.on('message', (message) => { handle(message) })
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-drawai",
-  "version": "0.2.7",
+  "version": "0.3.1",
   "type": "module",
   "description": "DSH 右侧栏的可编辑画布 + AI 语义绘图工具（diagram_apply / diagram_read），直接读写原生 .drawio 文件",
   "license": "MIT",
@@ -14,7 +14,8 @@
     "build": "node tools/build.mjs",
     "watch": "node tools/watch.mjs",
     "check": "node tools/check-package.mjs",
-    "test": "node tools/check-mxfile.mjs && node tools/check-route-preview.mjs && node tools/check-host.mjs && node tools/check-render.mjs && node tools/check-component.mjs && node tools/check-trace.mjs"
+    "test": "node tools/check-adaptive-palette.mjs && node tools/check-auto-save.mjs && node tools/check-drawing-queue.mjs && node tools/check-background-tasks.mjs && node tools/check-background-ui.mjs && node tools/check-trace-optimization.mjs && node tools/check-performance.mjs && node tools/check-mxfile.mjs && node tools/check-route-preview.mjs && node tools/check-host.mjs && node tools/check-render.mjs && node tools/check-component.mjs && node tools/check-text-copy.mjs && node tools/check-image-export.mjs && node tools/check-canvas-sessions.mjs && node tools/check-trace.mjs && node tools/check-media.mjs && node tools/check-video-player.mjs && node tools/check-image-trace.mjs && node tools/check-video-trace.mjs && node tools/check-video-reuse.mjs && node tools/check-video-audio.mjs && node tools/check-video-export.mjs && node tools/check-video-import.mjs && node tools/check-node-labels.mjs",
+    "bench:performance": "node tools/benchmark-performance.mjs"
   },
   "exports": {
     ".": "./lib/index.js",
@@ -38,6 +39,9 @@
   "engines": {
     "node": ">=20"
   },
+  "dependencies": {
+    "@resvg/resvg-js": "^2.6.2"
+  },
   "peerDependencies": {
     "@deepseek-ai/dsh-tools": ">=0.1.0-rc.1 <0.1.0 || >=0.1.5-rc.1 <0.2.0-0 || >=0.2.0-rc.1 <0.3.0-0"
   },