dsh-drawai 0.2.4 → 0.2.6

package/lib/trace-image.js

@@ -5,11 +5,12 @@
  * 这里只有**像素进、SVG 出**，不碰文件系统、不碰 ctx：宿主工具与命令行脚本共用同一份。
  *
  * 管线（每一步都能在返回的 metrics 里看到数字）：
- *   ① 四边泛洪判背景（近白 / 近灰 / 全透明）→ 不画截图底色
- *   ② k-means 定调色板（K 个前景色 + 背景单独占第 0 号）
- *   ③ 3× 超采样逐样本归类 → 3×3 众数滤波 → 降回原分辨率 → <minArea 的碎块并入邻色
- *   ④ 每色按连通域取闭合轮廓：像素**格边**上的有向图 + 左转跟随（区域恒在左侧）
- *   ⑤ RDP 简化 + 相对增量编码 → 每色一条 <path fill-rule="nonzero">
+ *   ① 工作图尺寸 = src/scale，再套 grid（宽）/ gridH（高）上限；透明像素合成到 bgColor
+ *   ② 四边泛洪判背景（近白 / 近灰 / 全透明）→ 不画截图底色
+ *   ③ 分层 k-means（colorsDark 暗色 + colorsFill 填充）定调色板；暗像素进保护区
+ *   ④ 3× 超采样归类 → 条件众数（高对比跳过）→ despeckle / minRegionArea（保护区不并）
+ *   ⑤ 每色按连通域取闭合轮廓：像素**格边**上的有向图 + 左转跟随（区域恒在左侧）
+ *   ⑥ RDP + 预算阶梯（受保护环不因 minLoopArea 丢弃）→ 每色一条 <path fill-rule="nonzero">
  *
  * 为什么是"格边跟随"而不是 marching squares：标签图在鞍点（对角相接）处 marching squares
  * 要人为定连通性，而格边有向图本身就无歧义 —— 每条边只属于一个区域，走完一圈恰好回到起点。
@@ -21,6 +22,11 @@ function clamp(v, lo, hi) {
   return v < lo ? lo : v > hi ? hi : v
 }
 
+/** 相对亮度（0..255），用于线稿/保护区与众数对比。 */
+function lumaRgb(r, g, b) {
+  return 0.299 * r + 0.587 * g + 0.114 * b
+}
+
 /* ────────────────────────── ① 背景 ────────────────────────── */
 
 /**
@@ -305,12 +311,21 @@ function traceLoops(comp, width, height, regionCount) {
  *   · 并进**颜色最接近**的邻色，而不是"面积最多的"—— 边缘的过渡色应该并回它看起来最像的那一侧；
  *   · **不连锁**：一轮里对固定快照判一次，避免小块并进小块滚雪球。
  */
-function despeckle(labels, width, height, palette, minArea) {
+/**
+ * 按颜色分块合并碎块。
+ * @param {Uint8Array|null} protectMask 非空时：块内受保护像素过半，或该 label 本身是保护色 → 不合并
+ * @param {Uint8Array|null} protectLabels 长度为 palette.length；1 = 该色永不被合并
+ */
+function despeckle(labels, width, height, palette, minArea, protectMask, protectLabels) {
+  if (!(minArea > 0)) {
+    return { mergedPixels: 0, blocksMerged: 0, blocks: 0, protectedSkipped: 0 }
+  }
   const colorCount = palette.length
   const comp = new Int32Array(width * height).fill(-1)
   const stack = []
   let mergedPixels = 0
   let blocksMerged = 0
+  let protectedSkipped = 0
 
   // 先把每块 4 连通区域找出来（一次，不随合并改变）
   const blocks = []
@@ -353,6 +368,18 @@ function despeckle(labels, width, height, palette, minArea) {
     if (block.pixels.length >= minArea) continue
     // 背景（label 0）不参与：它是"没画东西的地方"，并它等于把图啃出洞
     if (palette[block.label] === undefined) continue
+    if (protectLabels !== null && protectLabels !== undefined && protectLabels[block.label] === 1) {
+      protectedSkipped += 1
+      continue
+    }
+    if (protectMask !== null && protectMask !== undefined) {
+      let prot = 0
+      for (let k = 0; k < block.pixels.length; k += 1) if (protectMask[block.pixels[k]] === 1) prot += 1
+      if (prot * 2 >= block.pixels.length) {
+        protectedSkipped += 1
+        continue
+      }
+    }
     hist.fill(0)
     for (let k = 0; k < block.pixels.length; k += 1) {
       const p = block.pixels[k]
@@ -392,7 +419,109 @@ function despeckle(labels, width, height, palette, minArea) {
     mergedPixels += pixels.length
     blocksMerged += 1
   }
-  return { mergedPixels: mergedPixels, blocksMerged: blocksMerged, blocks: blocks.length }
+  return {
+    mergedPixels: mergedPixels,
+    blocksMerged: blocksMerged,
+    blocks: blocks.length,
+    protectedSkipped: protectedSkipped,
+  }
+}
+
+/**
+ * 分层调色板：暗像素单独 k-means（colorsDark），其余走 colorsFill。
+ * colorsDark=0 时退回单次 k-means（与旧行为一致）。
+ */
+function buildPalette(work, fgIndex, colors, colorsDark, colorsFill, protectLuma, seeds) {
+  const darkK = Math.max(0, Math.min(colors - 1, colorsDark))
+  const fillK = Math.max(1, colors - darkK)
+  // 显式 colorsFill 时以它为准（仍保证总和 = colors）
+  const useFill = colorsFill > 0 ? Math.max(1, Math.min(colors, colorsFill)) : fillK
+  const useDark = colorsFill > 0 ? Math.max(0, colors - useFill) : darkK
+
+  if (useDark === 0 || !(protectLuma > 0)) {
+    const samples = new Float64Array(fgIndex.length * 3)
+    for (let i = 0; i < fgIndex.length; i += 1) {
+      const o = fgIndex[i] * 4
+      samples[i * 3] = work[o]
+      samples[i * 3 + 1] = work[o + 1]
+      samples[i * 3 + 2] = work[o + 2]
+    }
+    let best = null
+    for (let s = 1; s <= seeds; s += 1) {
+      const got = kmeans(samples, colors, 24, s * 2654435761)
+      if (best === null || got.inertia < best.inertia) best = got
+    }
+    return {
+      cents: best.cent,
+      colorsDark: 0,
+      colorsFill: colors,
+      darkSamples: 0,
+      fillSamples: fgIndex.length,
+    }
+  }
+
+  const darkIdx = []
+  const fillIdx = []
+  for (let i = 0; i < fgIndex.length; i += 1) {
+    const p = fgIndex[i]
+    const o = p * 4
+    if (lumaRgb(work[o], work[o + 1], work[o + 2]) <= protectLuma) darkIdx.push(p)
+    else fillIdx.push(p)
+  }
+
+  // 某一侧为空时，把配额并给另一侧，避免空簇
+  let kDark = useDark
+  let kFill = useFill
+  if (darkIdx.length === 0) {
+    kFill = colors
+    kDark = 0
+  } else if (fillIdx.length === 0) {
+    kDark = colors
+    kFill = 0
+  }
+
+  const cents = []
+  function runK(indexes, k, seedBase) {
+    if (k <= 0 || indexes.length === 0) return
+    const samples = new Float64Array(indexes.length * 3)
+    for (let i = 0; i < indexes.length; i += 1) {
+      const o = indexes[i] * 4
+      samples[i * 3] = work[o]
+      samples[i * 3 + 1] = work[o + 1]
+      samples[i * 3 + 2] = work[o + 2]
+    }
+    const kk = Math.min(k, indexes.length)
+    let best = null
+    for (let s = 1; s <= seeds; s += 1) {
+      const got = kmeans(samples, kk, 24, seedBase + s * 2654435761)
+      if (best === null || got.inertia < best.inertia) best = got
+    }
+    for (let c = 0; c < best.cent.length; c += 1) cents.push(best.cent[c])
+  }
+  runK(darkIdx, kDark, 1)
+  runK(fillIdx, kFill, 100)
+  // 极端情况下簇数不足：用全体像素补满
+  if (cents.length < colors) {
+    const samples = new Float64Array(fgIndex.length * 3)
+    for (let i = 0; i < fgIndex.length; i += 1) {
+      const o = fgIndex[i] * 4
+      samples[i * 3] = work[o]
+      samples[i * 3 + 1] = work[o + 1]
+      samples[i * 3 + 2] = work[o + 2]
+    }
+    const need = colors - cents.length
+    const got = kmeans(samples, Math.min(colors, fgIndex.length), 24, 999 * 2654435761)
+    for (let c = 0; c < got.cent.length && cents.length < colors; c += 1) cents.push(got.cent[c])
+    void need
+  }
+
+  return {
+    cents: cents.slice(0, colors),
+    colorsDark: kDark,
+    colorsFill: kFill,
+    darkSamples: darkIdx.length,
+    fillSamples: fillIdx.length,
+  }
 }
 
 /* ────────────────────────── ⑤ 简化与编码 ────────────────────────── */
@@ -525,50 +654,249 @@ function encodeLoop(points, precision) {
 
 /* ────────────────────────── 门面 ────────────────────────── */
 
+/** 把 bgColor 规范成 [r,g,b]（数组或 #rrggbb；认不出就白）。 */
+function parseBgColor(raw) {
+  if (Array.isArray(raw) && raw.length >= 3) {
+    return [
+      clamp(Math.round(Number(raw[0])), 0, 255),
+      clamp(Math.round(Number(raw[1])), 0, 255),
+      clamp(Math.round(Number(raw[2])), 0, 255),
+    ]
+  }
+  if (typeof raw === 'string') {
+    const m = /^#?([0-9a-fA-F]{6})$/.exec(raw.trim())
+    if (m) {
+      const n = parseInt(m[1], 16)
+      return [(n >> 16) & 255, (n >> 8) & 255, n & 255]
+    }
+  }
+  return [255, 255, 255]
+}
+
+/**
+ * 工作图尺寸：先按 scale 降，再用 grid（宽）/ gridH（高，0=不限）做上限；超限等比压。
+ * @returns {{width:number,height:number,scaleRequested:number,scaleApplied:number,grid:number,gridH:number,sizeNotes:string}}
+ */
+function resolveWorkSize(srcWidth, srcHeight, options) {
+  const scaleRequested = Number(options.scale)
+  const scaleRounded = Math.round(scaleRequested)
+  const scaleApplied = scaleRounded >= 1 ? scaleRounded : 1
+  const grid = Math.max(16, Math.round(Number(options.grid)))
+  const gridHRaw = Number(options.gridH)
+  const gridH = gridHRaw > 0 ? Math.max(16, Math.round(gridHRaw)) : 0
+
+  const notes = []
+  if (!(scaleRequested >= 1) || scaleRounded !== scaleApplied) {
+    notes.push('scale clamped to ' + scaleApplied + ' (requested ' + scaleRequested + ')')
+  }
+
+  let width = Math.max(1, Math.round(srcWidth / scaleApplied))
+  let height = Math.max(1, Math.round(srcHeight / scaleApplied))
+  if (scaleApplied > 1) notes.push('scaleApplied ' + scaleApplied)
+
+  const capH = gridH > 0 ? gridH : Infinity
+  if (width > grid || height > capH) {
+    const factor = Math.min(grid / width, capH / height)
+    const nextW = Math.max(16, Math.round(width * factor))
+    const nextH = Math.max(16, Math.round(height * factor))
+    const parts = []
+    if (width > grid) parts.push('width')
+    if (height > capH) parts.push('height')
+    notes.push('grid capped ' + parts.join('+') + ' (' + width + '×' + height + ' → ' + nextW + '×' + nextH + ')')
+    width = nextW
+    height = nextH
+  }
+
+  return {
+    width: width,
+    height: height,
+    scaleRequested: scaleRequested,
+    scaleApplied: scaleApplied,
+    grid: grid,
+    gridH: gridH,
+    sizeNotes: notes.join('; '),
+  }
+}
+
 /** 矢量化的默认参数（宿主工具与命令行共用）。 */
 export const TRACE_DEFAULTS = {
-  colors: 12, // 前景调色板色数（背景另占 1 色）
-  grid: 499, // 按这个宽度做；高度按原图比例算，够大就原尺寸
-  scale: 1, // 先按 scale×scale 面积平均降采样，再做管线（=1 表示不降）
+  preset: 'default', // 命名预设，见 TRACE_PRESETS；显式字段覆盖预设
+  colors: 12, // 前景调色板色数（背景另占 1 色）= colorsDark + colorsFill（auto）
+  colorsDark: 3, // 暗色配额（线稿）；0 = 不分层，全体一次 k-means
+  colorsFill: 0, // 填充色配额；0 = 自动 colors - colorsDark
+  grid: 499, // 工作图宽度上限（px）；与 gridH 一起做等比封顶
+  gridH: 0, // 工作图高度上限（px）；0 = 不限高（只卡宽，兼容旧行为）
+  scale: 1, // 真降采样因子：work ≈ src/scale，再套 grid/gridH（=1 表示不按 scale 降）
   epsilon: 2.0, // RDP 简化容差（像素）
   precision: 1, // 坐标小数位
-  minArea: 10, // 小于这个面积（像素²）的碎块并进邻色
+  minArea: 10, // despeckle：小于这个面积（像素²）的碎块并进邻色；0 = 关
+  minRegionArea: 0, // despeckle 之后再按面积并区域；0 = 关（与 minArea 分开调）
+  protectLuma: 110, // 亮度 ≤ 此值的前景像素受保护（不 despeckle / 不 ladder 丢环）；0 = 关
+  majorityContrast: 40, // 局部亮度差 ≥ 此值则跳过众数滤波（保线稿）；0 = 全图滤波（旧行为）
   bgBright: 238, // 判"近白"的亮度下限
   bgTol: 10, // 判"近灰"的通道差上限
+  bgColor: [255, 255, 255], // 透明/半透明像素合成底色（再进泛洪与 k-means）
   seeds: 3, // k-means 重启次数（取 inertia 最小）
-  maxBytes: 50000, // SVG 上限（drawio style 里的 data URI 要塞得下；60000 是硬上限，留余量）
+  // SVG 上限（换算成 drawio style 里的 data URI 要塞得下）。宿主的硬上限是 250000 字符，
+  // 且它自己会再留 2000 的余量 —— 所以这里直接对齐到 248000：整图的精细度就由这个预算决定
+  // （预算越小，管线越要抬 epsilon、丢小环）。命令行想更省字符可显式传 --budget。
+  maxBytes: 248000,
   includeLabels: false, // 额外返回"去碎块后"的标签图（调试/比对用；会额外占 width*height 字节的 base64）
 }
 
+/**
+ * 命名预设：AI 先选场景，再按需覆盖单个字段。
+ * 合并顺序：TRACE_DEFAULTS ← preset ← 显式字段。
+ */
+export const TRACE_PRESETS = {
+  default: {},
+  /** 插画 / 线稿：多留暗色、严保细线、轮廓更细 */
+  lineart: {
+    colorsDark: 4,
+    protectLuma: 130,
+    majorityContrast: 32,
+    minArea: 4,
+    epsilon: 1.5,
+    precision: 2,
+  },
+  /** 照片 / 渐变：少暗色配额、碎块并多一点、轮廓可粗 */
+  photo: {
+    colors: 14,
+    colorsDark: 1,
+    protectLuma: 80,
+    majorityContrast: 55,
+    minArea: 16,
+    epsilon: 2.5,
+  },
+  /** 图标 / 简单截图：少色 + 降采样，压字符数 */
+  simple: {
+    colors: 6,
+    colorsDark: 2,
+    scale: 2,
+    grid: 320,
+    epsilon: 3,
+    minArea: 20,
+    protectLuma: 100,
+  },
+}
+
+/** 合法预设名列表（给报错 / 提示用）。 */
+export const TRACE_PRESET_NAMES = Object.keys(TRACE_PRESETS)
+
+/**
+ * 合并默认值 + 预设 + 显式覆盖。未知 preset 抛错（让 AI 立刻改，而不是静默当 default）。
+ * @returns {{options:object, preset:string}}
+ */
+export function resolveTraceOptions(rawOptions) {
+  const raw = rawOptions === undefined || rawOptions === null ? {} : rawOptions
+  const presetName = typeof raw.preset === 'string' && raw.preset.length > 0 ? raw.preset : 'default'
+  if (TRACE_PRESETS[presetName] === undefined) {
+    throw new Error(
+      '未知 trace preset "' + presetName + '"；可用：' + TRACE_PRESET_NAMES.join(', '),
+    )
+  }
+  const options = Object.assign({}, TRACE_DEFAULTS, TRACE_PRESETS[presetName], raw, { preset: presetName })
+  return { options: options, preset: presetName }
+}
+
+/**
+ * 根据 metrics 生成一句调参建议（给 AI 读，不是给用户的长文）。
+ */
+export function hintTraceTune(metrics) {
+  if (metrics === undefined || metrics === null) return ''
+  const hints = []
+  const budget = Number(metrics.budget) || TRACE_DEFAULTS.maxBytes
+  const chars = Number(metrics.svgChars) || 0
+  if (chars > budget * 0.9 || Number(metrics.attempts) > 1) {
+    hints.push('字符紧/触发预算阶梯 → 试 scale:2、加大 epsilon、减小 colors/grid，或 preset:"simple"')
+  }
+  if (Number(metrics.protectPixels) === 0 && metrics.preset !== 'photo') {
+    hints.push('无暗像素保护区 → 插画线稿可试 preset:"lineart" 或提高 protectLuma')
+  }
+  if (Number(metrics.colorsDark) === 0 && Number(metrics.darkSamples) === 0 && metrics.preset === 'lineart') {
+    hints.push('lineart 但没分到暗样本 → 提高 protectLuma 或检查原图对比度')
+  }
+  if (Number(metrics.majoritySkipped) === 0 && Number(metrics.majorityContrast) > 0) {
+    hints.push('众数未跳过任何像素 → 图对比偏低，可减小 majorityContrast 或改 preset')
+  }
+  if (chars < budget * 0.35 && Number(metrics.scaleApplied) >= 2) {
+    hints.push('字符很富余且已降采样 → 可 scale:1 或减小 epsilon 换保真')
+  }
+  if (hints.length === 0) {
+    hints.push('指标正常；线稿糊/断可试 preset:"lineart"；要更省字符用 preset:"simple"')
+  }
+  return hints.join('；')
+}
+
+/**
+ * 压缩给 AI 的结构化调参回执（diagram_apply.trace[]）。
+ */
+export function summarizeTraceForAi(metrics, extra) {
+  const base = {
+    preset: metrics.preset,
+    image: extra && extra.image !== undefined ? extra.image : undefined,
+    nodeId: extra && extra.nodeId !== undefined ? extra.nodeId : undefined,
+    // 只描了原图的一块时才有：那块在原图里的位置与尺寸（像素）——
+    // 模型据此知道"这次只覆盖了局部"，以及该按原图坐标把它摆到哪。
+    crop: metrics.crop,
+    source: metrics.source,
+    work: metrics.work,
+    scaleApplied: metrics.scaleApplied,
+    sizeNotes: metrics.sizeNotes,
+    colors: metrics.colors,
+    colorsDark: metrics.colorsDark,
+    colorsFill: metrics.colorsFill,
+    protectPixels: metrics.protectPixels,
+    majoritySkipped: metrics.majoritySkipped,
+    paths: metrics.paths,
+    loopsKept: metrics.loopsKept,
+    loopsProtectedKept: metrics.loopsProtectedKept,
+    regionsProtected: metrics.regionsProtected,
+    svgChars: metrics.svgChars,
+    budget: metrics.budget,
+    attempts: metrics.attempts,
+    exactPixelCoverage: metrics.exactPixelCoverage,
+    options: metrics.optionsApplied,
+    hint: metrics.tuneHint,
+  }
+  return base
+}
+
 /**
  * 位图 → SVG 标记。
  *
  * @param {{width:number,height:number,data:Buffer|Uint8Array}} raster RGBA8
- * @param {object} [rawOptions] 见 TRACE_DEFAULTS
+ * @param {object} [rawOptions] 见 TRACE_DEFAULTS / TRACE_PRESETS（可用 preset）
  * @returns {{svg:string, metrics:object}}
  */
 export function traceRasterToSvg(raster, rawOptions) {
-  const options = Object.assign({}, TRACE_DEFAULTS, rawOptions === undefined || rawOptions === null ? {} : rawOptions)
+  const resolved = resolveTraceOptions(rawOptions)
+  const options = resolved.options
+  const preset = resolved.preset
   const colors = Math.max(2, Math.min(24, Math.round(options.colors)))
-  const grid = Math.max(16, Math.round(options.grid))
-  const scale = Math.max(1, Math.round(options.scale))
-  const minArea = Math.max(1, Math.round(options.minArea))
+  const colorsDark = Math.max(0, Math.min(colors, Math.round(options.colorsDark)))
+  const colorsFillOpt = Math.max(0, Math.min(colors, Math.round(options.colorsFill)))
+  const minArea = Math.max(0, Math.round(options.minArea))
+  const minRegionArea = Math.max(0, Math.round(options.minRegionArea))
+  const protectLuma = Math.max(0, Number(options.protectLuma))
+  const majorityContrast = Math.max(0, Number(options.majorityContrast))
   const seeds = Math.max(1, Math.round(options.seeds))
+  const bgColor = parseBgColor(options.bgColor)
 
   const srcWidth = raster.width
   const srcHeight = raster.height
   const rgba = raster.data
 
-  // 目标尺寸：宽度向 grid 靠（够大就原尺寸），高度按比例（至少 16px）
-  let width = srcWidth
-  let height = srcHeight
-  if (grid < srcWidth) {
-    width = grid
-    height = Math.max(16, Math.round((srcHeight * grid) / srcWidth))
-  }
+  const sized = resolveWorkSize(srcWidth, srcHeight, options)
+  const width = sized.width
+  const height = sized.height
+  const scale = sized.scaleApplied
 
-  // 降采样（面积平均）+ 缩放：一次写完，后面只认 width×height 的工作图
+  // 降采样（面积平均）+ 把每个源像素先合成到 bgColor：一次写完，后面只认不透明的 width×height 工作图
   const work = new Uint8Array(width * height * 4)
+  const bgR = bgColor[0]
+  const bgG = bgColor[1]
+  const bgB = bgColor[2]
   for (let y = 0; y < height; y += 1) {
     const y0 = Math.floor((y * srcHeight) / height)
     const y1 = Math.max(y0 + 1, Math.floor(((y + 1) * srcHeight) / height))
@@ -583,10 +911,14 @@ export function traceRasterToSvg(raster, rawOptions) {
       for (let yy = y0; yy < y1; yy += 1) {
         for (let xx = x0; xx < x1; xx += 1) {
           const o = (yy * srcWidth + xx) * 4
-          r += rgba[o]
-          g += rgba[o + 1]
-          b += rgba[o + 2]
-          a += rgba[o + 3]
+          const srcA = rgba[o + 3]
+          const af = srcA / 255
+          const inv = 1 - af
+          // RGB 先合成到 bgColor，避免半透明边缘带着脏 RGB；alpha 原样平均留给 nearWhite(a<16)
+          r += rgba[o] * af + bgR * inv
+          g += rgba[o + 1] * af + bgG * inv
+          b += rgba[o + 2] * af + bgB * inv
+          a += srcA
           n += 1
         }
       }
@@ -622,31 +954,47 @@ export function traceRasterToSvg(raster, rawOptions) {
   for (let i = 0; i < width * height; i += 1) if (isBg[i] === 0) fgIndex.push(i)
   if (fgIndex.length === 0) throw new Error('这张图整幅都是背景色（近白/近灰），没有可画的像素')
 
-  let best = null
-  {
-    const samples = new Float64Array(fgIndex.length * 3)
+  // 保护区：暗前景像素（线稿）—— despeckle / ladder 都不动它们
+  const protectMask = new Uint8Array(width * height)
+  let protectPixels = 0
+  if (protectLuma > 0) {
     for (let i = 0; i < fgIndex.length; i += 1) {
-      const o = fgIndex[i] * 4
-      samples[i * 3] = work[o]
-      samples[i * 3 + 1] = work[o + 1]
-      samples[i * 3 + 2] = work[o + 2]
-    }
-    for (let s = 1; s <= seeds; s += 1) {
-      const got = kmeans(samples, colors, 24, s * 2654435761)
-      if (best === null || got.inertia < best.inertia) best = got
+      const p = fgIndex[i]
+      const o = p * 4
+      if (lumaRgb(work[o], work[o + 1], work[o + 2]) <= protectLuma) {
+        protectMask[p] = 1
+        protectPixels += 1
+      }
     }
   }
+
+  const built = buildPalette(work, fgIndex, colors, colorsDark, colorsFillOpt, protectLuma, seeds)
   const palette = [bgMean]
-  for (let c = 0; c < best.cent.length; c += 1) {
-    palette.push([clamp(Math.round(best.cent[c][0]), 0, 255), clamp(Math.round(best.cent[c][1]), 0, 255), clamp(Math.round(best.cent[c][2]), 0, 255)])
+  for (let c = 0; c < built.cents.length; c += 1) {
+    palette.push([
+      clamp(Math.round(built.cents[c][0]), 0, 255),
+      clamp(Math.round(built.cents[c][1]), 0, 255),
+      clamp(Math.round(built.cents[c][2]), 0, 255),
+    ])
   }
   const colorCount = palette.length
+  const protectLabels = new Uint8Array(colorCount)
+  if (protectLuma > 0) {
+    for (let c = 1; c < colorCount; c += 1) {
+      const p = palette[c]
+      if (lumaRgb(p[0], p[1], p[2]) <= protectLuma) protectLabels[c] = 1
+    }
+  }
 
-  // ③ 超采样归类（双线性）→ 众数滤波 → 降回原分辨率
+  // ③ 超采样归类（双线性）→ 条件众数滤波 → 降回原分辨率
   const ss = 3
   const sw = width * ss
   const sh = height * ss
   const gridLabels = new Uint8Array(sw * sh)
+  const paletteLuma = new Float64Array(colorCount)
+  for (let c = 0; c < colorCount; c += 1) {
+    paletteLuma[c] = lumaRgb(palette[c][0], palette[c][1], palette[c][2])
+  }
   const px = [0, 0, 0]
   for (let y = 0; y < sh; y += 1) {
     const fy = (y + 0.5) / ss - 0.5
@@ -687,8 +1035,32 @@ export function traceRasterToSvg(raster, rawOptions) {
 
   const scratch = new Uint8Array(gridLabels.length)
   const hist = new Int32Array(colorCount + 1)
+  let majoritySkipped = 0
+  let majorityApplied = 0
   for (let y = 0; y < sh; y += 1) {
     for (let x = 0; x < sw; x += 1) {
+      const self = gridLabels[y * sw + x]
+      // 局部对比高（线稿边缘）→ 跳过众数，避免细线被邻色吃掉
+      if (majorityContrast > 0) {
+        let minL = paletteLuma[self]
+        let maxL = minL
+        for (let dy = -1; dy <= 1; dy += 1) {
+          const yy = y + dy
+          if (yy < 0 || yy >= sh) continue
+          for (let dx = -1; dx <= 1; dx += 1) {
+            const xx = x + dx
+            if (xx < 0 || xx >= sw) continue
+            const L = paletteLuma[gridLabels[yy * sw + xx]]
+            if (L < minL) minL = L
+            if (L > maxL) maxL = L
+          }
+        }
+        if (maxL - minL >= majorityContrast) {
+          scratch[y * sw + x] = self
+          majoritySkipped += 1
+          continue
+        }
+      }
       hist.fill(0)
       for (let dy = -1; dy <= 1; dy += 1) {
         const yy = y + dy
@@ -699,7 +1071,7 @@ export function traceRasterToSvg(raster, rawOptions) {
           hist[gridLabels[yy * sw + xx]] += 1
         }
       }
-      let bi = gridLabels[y * sw + x]
+      let bi = self
       let bc = 0
       for (let c = 0; c < colorCount; c += 1) {
         if (hist[c] > bc) {
@@ -708,6 +1080,7 @@ export function traceRasterToSvg(raster, rawOptions) {
         }
       }
       scratch[y * sw + x] = bi
+      majorityApplied += 1
     }
   }
   gridLabels.set(scratch)
@@ -732,7 +1105,40 @@ export function traceRasterToSvg(raster, rawOptions) {
     }
   }
 
-  const speckle = despeckle(labels, width, height, palette, minArea)
+  // 背景色（label 0）只给泛洪底色用，且最终不画 path。
+  // 白衣白底时，角色内部的白也会被最近邻归到 palette[0] —— 若不改回前景色，
+  // 跳过绘制 label 0 就会把裙子/头发抠成透明洞。
+  let fgRelabeledFromBg = 0
+  let bgForced = 0
+  for (let i = 0; i < width * height; i += 1) {
+    if (isBg[i] === 1) {
+      if (labels[i] !== 0) bgForced += 1
+      labels[i] = 0
+      continue
+    }
+    if (labels[i] !== 0) continue
+    const o = i * 4
+    let bi = 1
+    let bd = Infinity
+    for (let c = 1; c < colorCount; c += 1) {
+      const p = palette[c]
+      const dr = work[o] - p[0]
+      const dg = work[o + 1] - p[1]
+      const db = work[o + 2] - p[2]
+      const d = dr * dr + dg * dg + db * db
+      if (d < bd) {
+        bd = d
+        bi = c
+      }
+    }
+    labels[i] = bi
+    fgRelabeledFromBg += 1
+  }
+
+  const maskOrNull = protectPixels > 0 ? protectMask : null
+  const labelsOrNull = protectLuma > 0 ? protectLabels : null
+  const speckle = despeckle(labels, width, height, palette, minArea, maskOrNull, labelsOrNull)
+  const regionMerge = despeckle(labels, width, height, palette, minRegionArea, maskOrNull, labelsOrNull)
   const labelDump = options.includeLabels === true
     ? {
         width: width, height: height, colors: colorCount,
@@ -741,21 +1147,24 @@ export function traceRasterToSvg(raster, rawOptions) {
       }
     : null
 
-  // ④ 连通域 + 轮廓
+  // ④ 连通域 + 轮廓（记下区域是否受保护，供 ladder 保留细环）
   const comp = new Int32Array(width * height).fill(-1)
   const regionLabel = []
   const regionArea = []
+  const regionProtected = []
   const stack = []
   for (let i = 0; i < width * height; i += 1) {
     if (comp[i] !== -1) continue
     const label = labels[i]
     const id = regionLabel.length
     let area = 0
+    let prot = protectLabels[label] === 1 ? 1 : 0
     comp[i] = id
     stack.push(i)
     while (stack.length > 0) {
       const p = stack.pop()
       area += 1
+      if (protectMask[p] === 1) prot = 1
       const x = p % width
       const y = (p - x) / width
       for (let dy = -1; dy <= 1; dy += 1) {
@@ -774,19 +1183,26 @@ export function traceRasterToSvg(raster, rawOptions) {
     }
     regionLabel.push(label)
     regionArea.push(area)
+    regionProtected.push(prot)
   }
 
   const loopsByRegion = traceLoops(comp, width, height, regionLabel.length)
 
-  // ⑤ 每色一条 path：外环（面积<0，顺时针）+ 洞（>0，反向）
+  // ⑤ 每色一条 path：外环（面积<0，顺时针）+ 洞（>0，反向）；环带 protected 标记
   const byColor = []
   for (let c = 0; c < colorCount; c += 1) byColor.push({ outer: [], hole: [], area: 0 })
   loopsByRegion.forEach(function (loops, id) {
     const label = regionLabel[id]
     const bucket = byColor[label]
+    const protectedLoop = regionProtected[id] === 1
     for (let i = 0; i < loops.length; i += 1) {
-      if (loops[i].area < 0) bucket.outer.push(loops[i])
-      else bucket.hole.push(loops[i])
+      const tagged = {
+        points: loops[i].points,
+        area: loops[i].area,
+        protected: protectedLoop,
+      }
+      if (loops[i].area < 0) bucket.outer.push(tagged)
+      else bucket.hole.push(tagged)
     }
     bucket.area += regionArea[id]
   })
@@ -806,8 +1222,9 @@ export function traceRasterToSvg(raster, rawOptions) {
   let attempts = 0
   let pathCount = 0
   let loopCount = 0
+  let loopsProtectedKept = 0
   let svg = ''
-  // 超预算就逐步收紧：先抬 RDP 容差，再丢小洞
+  // 超预算就逐步收紧：先抬 RDP 容差，再丢小洞（受保护环永不因 minLoopArea 丢弃）
   const ladder = [
     { epsilon: options.epsilon, minLoopArea: 4 },
     { epsilon: Math.max(options.epsilon, 2.5), minLoopArea: 4 },
@@ -821,19 +1238,25 @@ export function traceRasterToSvg(raster, rawOptions) {
     let body = ''
     pathCount = 0
     loopCount = 0
+    loopsProtectedKept = 0
     for (let k = 0; k < order.length; k += 1) {
+      // label 0 = 泛洪标出的截图底色：不画（SVG 该处透明）。
+      // 若画成 path，角色左右两块互不连通的底色会进同一条 nonzero path，
+      // 绕向抵消时会出现"一侧透明、一侧实心白"的假背景（插画发丝顶天立地时必现）。
+      if (order[k] === 0) continue
       const bucket = byColor[order[k]]
       let d = ''
       const all = bucket.outer.concat(bucket.hole)
       for (let i = 0; i < all.length; i += 1) {
         const loop = all[i]
-        if (Math.abs(loop.area) < plan.minLoopArea) continue
+        if (!loop.protected && Math.abs(loop.area) < plan.minLoopArea) continue
         // 洞反向 → nonzero 里挖空
         const points = loop.area > 0 ? loop.points.slice().reverse() : loop.points
         const seg = encodeLoop(simplifyClosed(points, plan.epsilon), options.precision)
         if (seg === null) continue
         d += seg
         loopCount += 1
+        if (loop.protected) loopsProtectedKept += 1
       }
       if (d === '') continue
       body += "<path fill='" + hex(palette[order[k]]) + "' fill-rule='nonzero' d='" + d + "'/>"
@@ -854,33 +1277,74 @@ export function traceRasterToSvg(raster, rawOptions) {
   let paletteArea = 0
   for (let c = 0; c < colorCount; c += 1) paletteArea += byColor[c].area
 
+  const optionsApplied = {
+    preset: preset,
+    colors: colors,
+    colorsDark: colorsDark,
+    colorsFill: colorsFillOpt,
+    grid: sized.grid,
+    gridH: sized.gridH,
+    scale: scale,
+    epsilon: options.epsilon,
+    precision: options.precision,
+    minArea: minArea,
+    minRegionArea: minRegionArea,
+    protectLuma: protectLuma,
+    majorityContrast: majorityContrast,
+  }
+
+  const metrics = {
+    preset: preset,
+    source: { width: srcWidth, height: srcHeight },
+    work: { width: width, height: height, scale: scale },
+    scaleRequested: sized.scaleRequested,
+    scaleApplied: sized.scaleApplied,
+    grid: sized.grid,
+    gridH: sized.gridH,
+    bgColor: bgColor.slice(),
+    sizeNotes: sized.sizeNotes,
+    colors: colorCount - 1,
+    colorsDark: built.colorsDark,
+    colorsFill: built.colorsFill,
+    darkSamples: built.darkSamples,
+    fillSamples: built.fillSamples,
+    protectLuma: protectLuma,
+    protectPixels: protectPixels,
+    fgRelabeledFromBg: fgRelabeledFromBg,
+    bgForced: bgForced,
+    majorityContrast: majorityContrast,
+    majoritySkipped: majoritySkipped,
+    majorityApplied: majorityApplied,
+    palette: palette.map(hex),
+    backgroundPixels: (function () {
+      let n = 0
+      for (let i = 0; i < width * height; i += 1) if (isBg[i] === 1) n += 1
+      return n
+    })(),
+    foregroundPixels: fgIndex.length,
+    despeckle: speckle,
+    regionMerge: regionMerge,
+    regions: regionLabel.length,
+    regionsProtected: regionProtected.reduce(function (n, v) { return n + v }, 0),
+    loops: loopsTotal.value,
+    paths: pathCount,
+    loopsKept: loopCount,
+    loopsProtectedKept: loopsProtectedKept,
+    drawnPixels: covered,
+    totalPixels: width * height,
+    exactPixelCoverage: covered === width * height,
+    svgChars: svg.length,
+    budget: options.maxBytes,
+    attempts: attempts,
+    paletteAreaSum: paletteArea,
+    optionsApplied: optionsApplied,
+  }
+  metrics.tuneHint = hintTraceTune(metrics)
+
   return {
     svg: svg,
     labels: labelDump,
-    metrics: {
-      source: { width: srcWidth, height: srcHeight },
-      work: { width: width, height: height, scale: scale },
-      colors: colorCount - 1,
-      palette: palette.map(hex),
-      backgroundPixels: (function () {
-        let n = 0
-        for (let i = 0; i < width * height; i += 1) if (isBg[i] === 1) n += 1
-        return n
-      })(),
-      foregroundPixels: fgIndex.length,
-      despeckle: speckle,
-      regions: regionLabel.length,
-      loops: loopsTotal.value,
-      paths: pathCount,
-      loopsKept: loopCount,
-      drawnPixels: covered,
-      totalPixels: width * height,
-      exactPixelCoverage: covered === width * height,
-      svgChars: svg.length,
-      budget: options.maxBytes,
-      attempts: attempts,
-      paletteAreaSum: paletteArea,
-    },
+    metrics: metrics,
   }
 }