dsh-drawai 0.2.6 → 0.3.0

package/lib/trace-image.js

@@ -6,7 +6,7 @@
  *
  * 管线（每一步都能在返回的 metrics 里看到数字）：
  *   ① 工作图尺寸 = src/scale，再套 grid（宽）/ gridH（高）上限；透明像素合成到 bgColor
- *   ② 四边泛洪判背景（近白 / 近灰 / 全透明）→ 不画截图底色
+ *   ② 去背景：由调用方显式传 removeBg true/false（无 auto）。true 时先识纯色底再泛洪，识不到走近白回退
  *   ③ 分层 k-means（colorsDark 暗色 + colorsFill 填充）定调色板；暗像素进保护区
  *   ④ 3× 超采样归类 → 条件众数（高对比跳过）→ despeckle / minRegionArea（保护区不并）
  *   ⑤ 每色按连通域取闭合轮廓：像素**格边**上的有向图 + 左转跟随（区域恒在左侧）
@@ -29,35 +29,158 @@ function lumaRgb(r, g, b) {
 
 /* ────────────────────────── ① 背景 ────────────────────────── */
 
+/** 收集四边像素下标（角不重复）。 */
+function borderIndices(width, height) {
+  const out = []
+  if (width <= 0 || height <= 0) return out
+  for (let x = 0; x < width; x += 1) {
+    out.push(x)
+    if (height > 1) out.push((height - 1) * width + x)
+  }
+  for (let y = 1; y < height - 1; y += 1) {
+    out.push(y * width)
+    if (width > 1) out.push(y * width + (width - 1))
+  }
+  return out
+}
+
+/**
+ * 识图：四边是否被同一种颜色（或透明）主导 = 有纯色背景。
+ *
+ * 返回 null = 没有纯色底（风景/照片边缘杂色）→ 调用方应保留背景、不抠。
+ * 返回对象 = 有纯色底，随后用 markBackground 按该色泛洪。
+ */
+function detectSolidBackground(rgba, width, height, options) {
+  const solidTol = Math.max(0, Math.round(Number(options.bgSolidTol)))
+  const minRatio = clamp(Number(options.bgSolidBorderRatio), 0, 1)
+  const border = borderIndices(width, height)
+  const n = border.length
+  if (n === 0) return null
+
+  let transparent = 0
+  const opaque = []
+  for (let bi = 0; bi < n; bi += 1) {
+    const i = border[bi]
+    const o = i * 4
+    if (rgba[o + 3] < 16) {
+      transparent += 1
+      continue
+    }
+    opaque.push(rgba[o], rgba[o + 1], rgba[o + 2])
+  }
+
+  if (transparent / n >= minRatio) {
+    return { kind: 'transparent', matchRatio: transparent / n, color: null }
+  }
+  if (opaque.length === 0) {
+    return { kind: 'transparent', matchRatio: 1, color: null }
+  }
+
+  // 粗分箱找众数色（箱宽 ≈ solidTol），再按箱心做一次精确匹配计数
+  const bin = Math.max(1, solidTol)
+  const hist = new Map()
+  for (let p = 0; p < opaque.length; p += 3) {
+    const key =
+      Math.round(opaque[p] / bin) * bin +
+      ',' +
+      Math.round(opaque[p + 1] / bin) * bin +
+      ',' +
+      Math.round(opaque[p + 2] / bin) * bin
+    hist.set(key, (hist.get(key) || 0) + 1)
+  }
+  let bestKey = null
+  let bestCount = 0
+  for (const entry of hist) {
+    if (entry[1] > bestCount) {
+      bestKey = entry[0]
+      bestCount = entry[1]
+    }
+  }
+  const mode = bestKey.split(',').map(Number)
+  // 众数箱内像素的均值当代表色（比箱角更稳）
+  let sr = 0
+  let sg = 0
+  let sb = 0
+  let sn = 0
+  for (let p = 0; p < opaque.length; p += 3) {
+    if (
+      Math.abs(opaque[p] - mode[0]) <= bin &&
+      Math.abs(opaque[p + 1] - mode[1]) <= bin &&
+      Math.abs(opaque[p + 2] - mode[2]) <= bin
+    ) {
+      sr += opaque[p]
+      sg += opaque[p + 1]
+      sb += opaque[p + 2]
+      sn += 1
+    }
+  }
+  const color = sn > 0
+    ? [Math.round(sr / sn), Math.round(sg / sn), Math.round(sb / sn)]
+    : mode
+
+  let match = transparent
+  for (let p = 0; p < opaque.length; p += 3) {
+    if (
+      Math.abs(opaque[p] - color[0]) <= solidTol &&
+      Math.abs(opaque[p + 1] - color[1]) <= solidTol &&
+      Math.abs(opaque[p + 2] - color[2]) <= solidTol
+    ) {
+      match += 1
+    }
+  }
+  const matchRatio = match / n
+  if (matchRatio < minRatio) return null
+  return { kind: 'color', matchRatio: matchRatio, color: color }
+}
+
 /**
  * 从四边泛洪标出背景。
  *
- * 判据是"近白/近灰"而不是"等于纯白"：截图和导出图的白底常带一点点色偏（#fdfdfc 这种），
- * 用纯白判会漏掉大片底色。泛洪（而不是全局阈值）保证只吃掉**与边界连通**的那一片 ——
- * 角色内部的白围裙不连边界，不会被误删。
+ * solid 描述要抠的底：
+ *   · legacy-nearwhite —— 旧行为：近白/近灰/透明（removeBg:true 强制）
+ *   · transparent —— 透明主导的边，顺带吃近白（常见 PNG 导出）
+ *   · color —— 与代表色在 solidTol 内（或透明）
+ *
+ * 泛洪（而不是全局阈值）只吃掉**与边界连通**的那一片 —— 角色内部的白围裙不连边界，不会被误删。
  */
-function markBackground(rgba, width, height, options) {
-  const bright = options.bgBright
-  const tol = options.bgTol
+function markBackground(rgba, width, height, options, solid) {
   const isBg = new Uint8Array(width * height)
+  if (solid === null || solid === undefined) return isBg
+
+  const bright = options.bgBright
+  const chromaTol = options.bgTol
+  const solidTol = Math.max(0, Math.round(Number(options.bgSolidTol)))
   const stack = []
+  const target = solid.color
 
   function nearWhite(i) {
     const o = i * 4
     const a = rgba[o + 3]
-    if (a < 16) return true // 全透明也算底色
+    if (a < 16) return true
     const r = rgba[o]
     const g = rgba[o + 1]
     const b = rgba[o + 2]
     const mx = r > g ? (r > b ? r : b) : g > b ? g : b
     const mn = r < g ? (r < b ? r : b) : g < b ? g : b
-    return mx >= bright && mx - mn <= tol
+    return mx >= bright && mx - mn <= chromaTol
+  }
+  function matches(i) {
+    const o = i * 4
+    const a = rgba[o + 3]
+    if (a < 16) return true
+    if (solid.kind === 'legacy-nearwhite' || solid.kind === 'transparent') return nearWhite(i)
+    if (target === null || target === undefined) return false
+    return (
+      Math.abs(rgba[o] - target[0]) <= solidTol &&
+      Math.abs(rgba[o + 1] - target[1]) <= solidTol &&
+      Math.abs(rgba[o + 2] - target[2]) <= solidTol
+    )
   }
   function push(x, y) {
     if (x < 0 || y < 0 || x >= width || y >= height) return
     const i = y * width + x
     if (isBg[i] === 1) return
-    if (!nearWhite(i)) return
+    if (!matches(i)) return
     isBg[i] = 1
     stack.push(i)
   }
@@ -81,6 +204,19 @@ function markBackground(rgba, width, height, options) {
   return isBg
 }
 
+/**
+ * 解析 removeBg：必须由调用方显式传入 true|always（抠）/ false|never（保留）。
+ * 不再支持 auto（是否抠由 AI/调用方判断，不由管线猜）。
+ * @returns {'always'|'never'}
+ */
+function normalizeRemoveBg(raw) {
+  if (raw === true || raw === 'always' || raw === 'true' || raw === 1 || raw === '1') return 'always'
+  if (raw === false || raw === 'never' || raw === 'false' || raw === 0 || raw === '0') return 'never'
+  throw new Error(
+    'removeBg 必填：true（抠背景）或 false（保留背景）；不再支持 auto / 省略',
+  )
+}
+
 /* ────────────────────────── ② 调色板 ────────────────────────── */
 
 /** 线性同余随机数（自带，避免依赖 Math.random 的可重复性问题）。 */
@@ -136,7 +272,20 @@ function kmeans(samples, k, iterations, seed) {
   const sum = new Float64Array(k * 3)
   const count = new Int32Array(k)
   let inertia = 0
+  const seen = []
   for (let iter = 0; iter < iterations; iter += 1) {
+    // Empty clusters can alternate between identical states instead of converging.
+    // Skip only complete, exactly repeated cycles, always executing the final
+    // iteration so assign/inertia retain the original fixed-iteration semantics.
+    const values = cent.flat()
+    for (let at = seen.length - 1; at >= 0; at--) {
+      const previous = seen[at]
+      if (!values.every((value, index) => value === previous.values[index])) continue
+      const period = iter - previous.iteration
+      iter += Math.floor((iterations - iter - 1) / period) * period
+      break
+    }
+    seen.push({ iteration: iter, values })
     sum.fill(0)
     count.fill(0)
     inertia = 0
@@ -163,7 +312,9 @@ function kmeans(samples, k, iterations, seed) {
       sum[best * 3 + 2] += b
       count[best] += 1
     }
+    let unchanged = true
     for (let c = 0; c < k; c += 1) {
+      const previous = cent[c]
       if (count[c] === 0) {
         let far = 0
         let farD = -1
@@ -181,7 +332,11 @@ function kmeans(samples, k, iterations, seed) {
       } else {
         cent[c] = [sum[c * 3] / count[c], sum[c * 3 + 1] / count[c], sum[c * 3 + 2] / count[c]]
       }
+      if (cent[c][0] !== previous[0] || cent[c][1] !== previous[1] || cent[c][2] !== previous[2]) unchanged = false
     }
+    // An exact fixed point (including empty-cluster reseeding) repeats identically.
+    // Keep the original arithmetic/order/seeds; no tolerance-based approximation.
+    if (unchanged) break
   }
   return { cent: cent, assign: assign, inertia: inertia }
 }
@@ -197,6 +352,9 @@ function kmeans(samples, k, iterations, seed) {
  *
  * 边的方向是**区域恒在左侧**：右边界朝上、下边界朝左。方向给错的话整张图的入度就不等于
  * 出度，走一步就断在空气里（这个坑真实踩过：外环整圈变成一堆 3~4 个点的碎片）。
+ *
+ * 邻接只扫右/下时，右框与底框会因"邻 = 画外(-1)"自动出现；左框与顶框必须另补，
+ * 否则贴左边/顶边的连通域外环不闭合（照片左侧透出画布网格就是这个）。
  */
 function traceLoops(comp, width, height, regionCount) {
   const stride = width + 1
@@ -217,6 +375,9 @@ function traceLoops(comp, width, height, regionCount) {
   for (let y = 0; y < height; y += 1) {
     for (let x = 0; x < width; x += 1) {
       const id = comp[y * width + x]
+      // 只查右 / 下邻：与"邻 = 画外(-1)"合在一起，已经覆盖了右框与底框。
+      // 左框与顶框没有对应的"从画外指进来"的邻接扫描，必须单独补，否则贴左边 /
+      // 顶边的连通域轮廓不闭合——复杂照片左侧会出现大块透明缺口（画布网格露出来）。
       const right = at(x + 1, y)
       if (right !== id) {
         if (id >= 0) addEdge(x + 1, y + 1, 0, -1, id)
@@ -229,6 +390,15 @@ function traceLoops(comp, width, height, regionCount) {
       }
     }
   }
+  // 补左框（x=0）与顶框（y=0）：区域在东 / 南侧 → 走下 / 走左 时区域在左手边。
+  for (let y = 0; y < height; y += 1) {
+    const id = comp[y * width]
+    if (id >= 0) addEdge(0, y, 0, 1, id)
+  }
+  for (let x = 0; x < width; x += 1) {
+    const id = comp[x]
+    if (id >= 0) addEdge(x + 1, 0, -1, 0, id)
+  }
 
   // 左转优先：向上→左、向左→下、向下→右、向右→上（区域始终在左手边）
   function turnOrder(dx, dy) {
@@ -254,13 +424,14 @@ function traceLoops(comp, width, height, regionCount) {
         cx += edge.dx
         cy += edge.dy
         const key = cy * stride + cx
-        const list = outMap.get(key)
-        if (list === undefined || list.length === 0) {
+        // 回到起点即闭合。不能再用 list.indexOf(first)：first 已从起点弹出，
+        // 引用永远不在 list 里，外环与洞在共用角点处会被串成一条错环。
+        if (key === startKey && points.length > 1) {
           edge = null
           break
         }
-        if (key === startKey && list.indexOf(first) >= 0) {
-          list.splice(list.indexOf(first), 1)
+        const list = outMap.get(key)
+        if (list === undefined || list.length === 0) {
           edge = null
           break
         }
@@ -316,7 +487,7 @@ function traceLoops(comp, width, height, regionCount) {
  * @param {Uint8Array|null} protectMask 非空时：块内受保护像素过半，或该 label 本身是保护色 → 不合并
  * @param {Uint8Array|null} protectLabels 长度为 palette.length；1 = 该色永不被合并
  */
-function despeckle(labels, width, height, palette, minArea, protectMask, protectLabels) {
+function despeckle(labels, width, height, palette, minArea, protectMask, protectLabels, backgroundLabel) {
   if (!(minArea > 0)) {
     return { mergedPixels: 0, blocksMerged: 0, blocks: 0, protectedSkipped: 0 }
   }
@@ -366,8 +537,8 @@ function despeckle(labels, width, height, palette, minArea, protectMask, protect
   for (let b = 0; b < blocks.length; b += 1) {
     const block = blocks[b]
     if (block.pixels.length >= minArea) continue
-    // 背景（label 0）不参与：它是"没画东西的地方"，并它等于把图啃出洞
-    if (palette[block.label] === undefined) continue
+    // 仅抠底模式的专用背景标签不参与；保留背景时 label 0 也是普通颜色。
+    if (block.label === backgroundLabel || palette[block.label] === undefined) continue
     if (protectLabels !== null && protectLabels !== undefined && protectLabels[block.label] === 1) {
       protectedSkipped += 1
       continue
@@ -401,7 +572,7 @@ function despeckle(labels, width, height, palette, minArea, protectMask, protect
     let bestScore = null
     const src = palette[block.label]
     for (let l = 0; l < colorCount; l += 1) {
-      if (hist[l] === 0 || l === 0 || l === block.label) continue
+      if (hist[l] === 0 || l === backgroundLabel || l === block.label) continue
       const p = palette[l]
       const d = (src[0] - p[0]) ** 2 + (src[1] - p[1]) ** 2 + (src[2] - p[2]) ** 2
       const score = d - Math.min(hist[l], 60) // 出现得多算一点加成，但不至于压过颜色差异
@@ -431,7 +602,7 @@ function despeckle(labels, width, height, palette, minArea, protectMask, protect
  * 分层调色板：暗像素单独 k-means（colorsDark），其余走 colorsFill。
  * colorsDark=0 时退回单次 k-means（与旧行为一致）。
  */
-function buildPalette(work, fgIndex, colors, colorsDark, colorsFill, protectLuma, seeds) {
+function buildPalette(work, fgIndex, colors, colorsDark, colorsFill, protectLuma, seeds, adaptive) {
   const darkK = Math.max(0, Math.min(colors - 1, colorsDark))
   const fillK = Math.max(1, colors - darkK)
   // 显式 colorsFill 时以它为准（仍保证总和 = colors）
@@ -472,6 +643,36 @@ function buildPalette(work, fgIndex, colors, colorsDark, colorsFill, protectLuma
   // 某一侧为空时，把配额并给另一侧，避免空簇
   let kDark = useDark
   let kFill = useFill
+  if (adaptive && darkIdx.length > 0 && fillIdx.length > 0) {
+    // Coarse RGB bins suppress single-pixel noise. Effective diversity gives
+    // small but distinct hues a voice without letting pixel area decide alone.
+    const richness = (indexes) => {
+      const bins = new Uint32Array(512)
+      for (const p of indexes) {
+        const o = p * 4
+        bins[(work[o] >> 5) * 64 + (work[o + 1] >> 5) * 8 + (work[o + 2] >> 5)]++
+      }
+      const minimum = Math.max(1, Math.floor(indexes.length * 0.0005))
+      let roots = 0
+      let count = 0
+      for (const n of bins) if (n >= minimum) { roots += Math.sqrt(n); count += n }
+      return Math.max(1, roots * roots / Math.max(1, count))
+    }
+    const darkRichness = richness(darkIdx)
+    const fillRichness = richness(fillIdx)
+    const darkWeight = darkRichness * Math.cbrt(darkIdx.length / fgIndex.length)
+    const fillWeight = fillRichness * Math.cbrt(fillIdx.length / fgIndex.length)
+    kDark = Math.max(1, Math.min(colors - 1, Math.round(colors * darkWeight / (darkWeight + fillWeight))))
+    // A flat region needs one slot, regardless of how large it is.
+    if (Math.ceil(darkRichness) + Math.ceil(fillRichness) >= colors) {
+      kDark = Math.min(kDark, Math.ceil(darkRichness))
+      kDark = Math.max(kDark, colors - Math.ceil(fillRichness))
+    }
+    if (darkRichness < 1.000001) kDark = 1
+    else if (fillRichness < 1.000001) kDark = colors - 1
+    kDark = Math.max(1, Math.min(colors - 1, kDark))
+    kFill = colors - kDark
+  }
   if (darkIdx.length === 0) {
     kFill = colors
     kDark = 0
@@ -557,6 +758,31 @@ function simplifyClosed(points, epsilon) {
   return simplifyOpen(segA, epsilon).slice(0, -1).concat(simplifyOpen(segB, epsilon).slice(0, -1))
 }
 
+/** 仅删除直线上的中间点才算几何无损；指标相对量化标签图，不代表原图保真。 */
+function sameLoopGeometry(original, simplified) {
+  if (simplified.length < 3) return false
+  const start = original.findIndex((p) => p[0] === simplified[0][0] && p[1] === simplified[0][1])
+  if (start < 0) return false
+  let cursor = start
+  let walked = 0
+  for (let i = 0; i < simplified.length; i += 1) {
+    const a = simplified[i]
+    const b = simplified[(i + 1) % simplified.length]
+    const dx = b[0] - a[0]
+    const dy = b[1] - a[1]
+    do {
+      cursor = (cursor + 1) % original.length
+      walked += 1
+      if (walked > original.length) return false
+      const p = original[cursor]
+      const px = p[0] - a[0]
+      const py = p[1] - a[1]
+      if (px * dy !== py * dx || px * dx + py * dy < 0 || px * dx + py * dy > dx * dx + dy * dy) return false
+    } while (original[cursor][0] !== b[0] || original[cursor][1] !== b[1])
+  }
+  return walked === original.length
+}
+
 function simplifyOpen(points, epsilon) {
   if (points.length < 3) return points.slice()
   const keep = new Uint8Array(points.length)
@@ -697,8 +923,8 @@ function resolveWorkSize(srcWidth, srcHeight, options) {
   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 nextW = Math.max(1, Math.round(width * factor))
+    const nextH = Math.max(1, Math.round(height * factor))
     const parts = []
     if (width > grid) parts.push('width')
     if (height > capH) parts.push('height')
@@ -722,7 +948,7 @@ function resolveWorkSize(srcWidth, srcHeight, options) {
 export const TRACE_DEFAULTS = {
   preset: 'default', // 命名预设，见 TRACE_PRESETS；显式字段覆盖预设
   colors: 12, // 前景调色板色数（背景另占 1 色）= colorsDark + colorsFill（auto）
-  colorsDark: 3, // 暗色配额（线稿）；0 = 不分层，全体一次 k-means
+  colorsDark: 3, // 固定分配的默认配额；未显式传入配额时按丰富度自适应。0 = 不分层
   colorsFill: 0, // 填充色配额；0 = 自动 colors - colorsDark
   grid: 499, // 工作图宽度上限（px）；与 gridH 一起做等比封顶
   gridH: 0, // 工作图高度上限（px）；0 = 不限高（只卡宽，兼容旧行为）
@@ -733,9 +959,13 @@ export const TRACE_DEFAULTS = {
   minRegionArea: 0, // despeckle 之后再按面积并区域；0 = 关（与 minArea 分开调）
   protectLuma: 110, // 亮度 ≤ 此值的前景像素受保护（不 despeckle / 不 ladder 丢环）；0 = 关
   majorityContrast: 40, // 局部亮度差 ≥ 此值则跳过众数滤波（保线稿）；0 = 全图滤波（旧行为）
-  bgBright: 238, // 判"近白"的亮度下限
+  bgBright: 238, // 判"近白"的亮度下限（removeBg:true 且未检出纯色底时的回退）
   bgTol: 10, // 判"近灰"的通道差上限
   bgColor: [255, 255, 255], // 透明/半透明像素合成底色（再进泛洪与 k-means）
+  // 去背景：无默认。调用方必须显式传 removeBg:true|false（或 always|never）。
+  // true = 抠（先识纯色底，否则近白泛洪）；false = 整图保留。
+  bgSolidTol: 22, // 纯色判定：与众数色的每通道容差
+  bgSolidBorderRatio: 0.88, // 四边像素至少这么大比例同色/透明才算有纯色底
   seeds: 3, // k-means 重启次数（取 inertia 最小）
   // SVG 上限（换算成 drawio style 里的 data URI 要塞得下）。宿主的硬上限是 250000 字符，
   // 且它自己会再留 2000 的余量 —— 所以这里直接对齐到 248000：整图的精细度就由这个预算决定
@@ -783,6 +1013,117 @@ export const TRACE_PRESETS = {
 /** 合法预设名列表（给报错 / 提示用）。 */
 export const TRACE_PRESET_NAMES = Object.keys(TRACE_PRESETS)
 
+/** 按用户参考图校准：保持同一棱角化色块管线，主要以采样密度区分三档。 */
+export const TRACE_FRAGMENT_LEVELS = Object.freeze({
+  low: Object.freeze({ resolutionRatio: 320 / 499, tolerance: 0.1 }),
+  medium: Object.freeze({ resolutionRatio: 400 / 499, tolerance: 0.08 }),
+  high: Object.freeze({ resolutionRatio: 1, tolerance: 0.04 }),
+})
+
+export function traceRasterForToolbar(raster, raw = {}) {
+  const maxBytes = raw.maxBytes === undefined ? TRACE_DEFAULTS.maxBytes : Number(raw.maxBytes)
+  if (!Number.isInteger(maxBytes) || maxBytes < 2000 || maxBytes > TRACE_DEFAULTS.maxBytes) throw new Error('无效 SVG 字符预算')
+  const level = raw.level === undefined ? 'medium' : raw.level
+  if (!Object.prototype.hasOwnProperty.call(TRACE_FRAGMENT_LEVELS, level)) throw new Error('未知碎片程度')
+  if (typeof raw.removeBg !== 'boolean') throw new Error('removeBg 必须为 true 或 false')
+  const colors = raw.colors === undefined ? TRACE_DEFAULTS.colors : Number(raw.colors)
+  if (!Number.isInteger(colors) || colors < 2 || colors > 24) throw new Error('颜色数须在 2–24 之间')
+  const preset = raw.preset === undefined ? 'default' : raw.preset
+  const styleFactors = { default: 1, lineart: 0.8, photo: 1.2, simple: 1.5 }
+  if (!Object.prototype.hasOwnProperty.call(styleFactors, preset)) throw new Error('未知复刻画风')
+  const sourceLong = Math.max(raster.width, raster.height)
+  const maxLongSide = raw.maxLongSide === undefined ? 887 : Number(raw.maxLongSide)
+  if (!Number.isInteger(maxLongSide) || maxLongSide < 1 || maxLongSide > 16384) throw new Error('无效采样长边')
+  // 参考图高档工作图为 499×887；其它宽高比按长边等比适配，不把小图虚增到该尺寸。
+  const baseLong = Math.min(maxLongSide, sourceLong)
+  const baseScale = baseLong / sourceLong
+  const baseArea = (baseLong / 887) ** 2
+  const profileMinArea = TRACE_PRESETS[preset].minArea ?? TRACE_DEFAULTS.minArea
+  for (let attempt = 0; attempt < 5; attempt += 1) {
+    const retryScale = 0.8 ** attempt
+    const makeOptions = (ratio) => {
+      const grid = Math.max(1, Math.round(raster.width * baseScale * ratio * retryScale))
+      const gridH = Math.max(1, Math.ceil(raster.height * baseScale * ratio * retryScale))
+      const options = { preset, removeBg: raw.removeBg, colors, maxBytes,
+        adaptiveDarkColors: raw.adaptiveDarkColors,
+        onTiming: raw.onTiming,
+        paletteValidator: raw.paletteValidator,
+        includeDrawing: raw.includeDrawing === true,
+        grid, gridH, scale: 1, minRegionArea: 0,
+        minArea: Math.round(profileMinArea * baseArea * retryScale ** 2),
+      }
+      if (raw.colorsDark !== undefined) options.colorsDark = raw.colorsDark
+      if (raw.colorsFill !== undefined) options.colorsFill = raw.colorsFill
+      if (Array.isArray(raw.paletteOverride) && raw.paletteOverride.length >= 2) options.paletteOverride = raw.paletteOverride
+      const sized = resolveWorkSize(raster.width, raster.height, options)
+      // RDP operates on pixel-grid contours: subpixel tolerances preserve stair steps.
+      // Keep the calibrated angular style in work pixels, including small images and budget retries.
+      options.epsilon = Math.min(2 * styleFactors[preset],
+        Math.min(sized.width, sized.height) * 0.45)
+      return options
+    }
+    const emptyResult = () => {
+      const svg = '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 ' + raster.width + ' ' + raster.height + '"></svg>'
+      return { svg, metrics: { foregroundPixels: 0, fragments: 0, paths: 0, colors: 0, svgChars: svg.length,
+        budget: maxBytes, fragmentLevel: level, detailReduced: false } }
+    }
+    if (raw.onlySelectedLevel === true) {
+      let result
+      try { result = traceRasterToSvg(raster, makeOptions(TRACE_FRAGMENT_LEVELS[level].resolutionRatio)) }
+      catch (error) {
+        if (raw.allowEmpty === true && error.code === 'EMPTY_FOREGROUND') return emptyResult()
+        throw error
+      }
+      if (result.svg.length > maxBytes || result.metrics.paths === 0) continue
+      result.metrics.fragmentLevel = level
+      result.metrics.resolutionRetries = attempt
+      result.metrics.detailReduced = attempt > 0 || result.metrics.attempts > 1
+      return result
+    }
+    let reference
+    try { reference = traceRasterToSvg(raster, makeOptions(1)) }
+    catch (error) {
+      if (raw.allowEmpty !== true || error.code !== 'EMPTY_FOREGROUND') throw error
+      // 视频的空白帧仍占时间，不能丢帧或替换为上一帧。
+      return emptyResult()
+    }
+    const results = { high: reference }
+    const referencePalette = reference.metrics.palette.slice(raw.removeBg ? 1 : 0).map((hex) => [1, 3, 5].map((offset) => parseInt(hex.slice(offset, offset + 2), 16)))
+    for (const name of ['low', 'medium']) {
+      const options = makeOptions(TRACE_FRAGMENT_LEVELS[name].resolutionRatio)
+      let traced = traceRasterToSvg(raster, options)
+      // 极少色图片降采样后会产生过渡色；避免重新聚类把低档变成更多细碎色圈。
+      if (traced.metrics.fragments > reference.metrics.fragments) {
+        traced = traceRasterToSvg(raster, Object.assign({}, options, { paletteOverride: referencePalette }))
+      }
+      results[name] = traced
+    }
+    const result = results[level]
+    if (result.svg.length > maxBytes || (result.metrics.paths === 0 && !(raw.allowEmpty === true && result.metrics.foregroundPixels === 0))) continue
+    const normalizedArea = reference.metrics.foregroundPixels * (887 / Math.max(reference.metrics.work.width, reference.metrics.work.height)) ** 2
+    const richness = clamp(Math.sqrt(reference.metrics.fragments / Math.max(1, normalizedArea) * 32), 0, 1)
+    const thresholds = {}
+    for (const [name, profile] of Object.entries(TRACE_FRAGMENT_LEVELS)) {
+      // 使用本图实际测得的各档数量给出参考区间，不再为了追赶预测值改变画风。
+      const target = Math.max(1, results[name].metrics.fragments)
+      const tolerance = profile.tolerance * (0.8 + richness * 0.2)
+      thresholds[name] = { min: Math.max(1, Math.ceil(target * (1 - tolerance))),
+        max: Math.max(1, Math.floor(target * (1 + tolerance))), target }
+    }
+    const desired = thresholds[level]
+    result.metrics.fragmentLevel = level
+    result.metrics.fragmentThresholds = thresholds
+    result.metrics.targetFragments = desired
+    result.metrics.targetReached = result.metrics.fragments >= desired.min && result.metrics.fragments <= desired.max
+    result.metrics.imageAnalysis = { sourcePixels: raster.width * raster.height,
+      workPixels: result.metrics.totalPixels, referenceFragments: reference.metrics.fragments, richness }
+    result.metrics.resolutionRetries = attempt
+    result.metrics.detailReduced = attempt > 0 || result.metrics.attempts > 1
+    return result
+  }
+  throw new Error('此图像过于复杂，无法生成有效结果，请降低碎片程度或减少颜色数')
+}
+
 /**
  * 合并默认值 + 预设 + 显式覆盖。未知 preset 抛错（让 AI 立刻改，而不是静默当 default）。
  * @returns {{options:object, preset:string}}
@@ -796,6 +1137,10 @@ export function resolveTraceOptions(rawOptions) {
     )
   }
   const options = Object.assign({}, TRACE_DEFAULTS, TRACE_PRESETS[presetName], raw, { preset: presetName })
+  options.adaptiveDarkColors = raw.adaptiveDarkColors !== false && raw.colorsDark === undefined && !(raw.colorsFill > 0)
+  if (raw.colorsDark === undefined) options.colorsDark = TRACE_PRESETS[presetName].colorsDark ?? TRACE_DEFAULTS.colorsDark
+  if (raw.colorsFill === undefined) options.colorsFill = TRACE_DEFAULTS.colorsFill
+  options.removeBg = normalizeRemoveBg(options.removeBg)
   return { options: options, preset: presetName }
 }
 
@@ -822,23 +1167,61 @@ export function hintTraceTune(metrics) {
   if (chars < budget * 0.35 && Number(metrics.scaleApplied) >= 2) {
     hints.push('字符很富余且已降采样 → 可 scale:1 或减小 epsilon 换保真')
   }
+  if (
+    metrics.bgRemoved === false &&
+    metrics.optionsApplied &&
+    metrics.optionsApplied.removeBg === 'never'
+  ) {
+    hints.push('当前 removeBg:false 保留了背景；白底/纯色底图标可改 removeBg:true 再描')
+  }
   if (hints.length === 0) {
     hints.push('指标正常；线稿糊/断可试 preset:"lineart"；要更省字符用 preset:"simple"')
   }
   return hints.join('；')
 }
 
+/**
+ * 把普通 JSON 数据收成 DSH 工具返回值能过关的"无损 JSON"：
+ *   · 丢掉值为 undefined 的自有属性（`{crop:undefined}` 会被 isJsonValue 判死刑，
+ *     而 JSON.stringify 却会默默省略 —— 这正是 traceImage 回执曾触发
+ *     `tool "diagram_apply" returned invalid output: value is not lossless JSON` 的根因）
+ *   · 把 -0 收成 0（DSH 的 walkJsonValue 同样拒 -0）
+ *   · 非有限数字 → 0（宁可变钝，也不让整次工具调用被宿主打回）
+ */
+export function toLosslessJson(value) {
+  if (value === null) return null
+  const t = typeof value
+  if (t === 'boolean' || t === 'string') return value
+  if (t === 'number') {
+    if (!Number.isFinite(value) || Object.is(value, -0)) return 0
+    return value
+  }
+  if (t !== 'object') return null
+  if (Array.isArray(value)) {
+    const out = []
+    for (let i = 0; i < value.length; i += 1) out.push(toLosslessJson(value[i]))
+    return out
+  }
+  const out = {}
+  const keys = Object.keys(value)
+  for (let i = 0; i < keys.length; i += 1) {
+    const key = keys[i]
+    const child = value[key]
+    if (child === undefined) continue
+    out[key] = toLosslessJson(child)
+  }
+  return out
+}
+
 /**
  * 压缩给 AI 的结构化调参回执（diagram_apply.trace[]）。
+ *
+ * 可选字段（image / nodeId / crop）**缺就不要挂键** —— 宿主对工具输出走
+ * lossless JSON 校验，自有属性值为 undefined 会整次失败。
  */
 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,
@@ -856,10 +1239,22 @@ export function summarizeTraceForAi(metrics, extra) {
     budget: metrics.budget,
     attempts: metrics.attempts,
     exactPixelCoverage: metrics.exactPixelCoverage,
+    labelPartitionComplete: metrics.labelPartitionComplete,
+    coverageBasis: 'quantized-label-map',
+    loopsDropped: metrics.loopsDropped,
+    budgetExceeded: metrics.budgetExceeded,
+    appliedEpsilon: metrics.appliedEpsilon,
+    bgRemoved: metrics.bgRemoved,
+    bgDetect: metrics.bgDetect,
     options: metrics.optionsApplied,
     hint: metrics.tuneHint,
   }
-  return base
+  if (extra && typeof extra.image === 'string') base.image = extra.image
+  if (extra && typeof extra.nodeId === 'string') base.nodeId = extra.nodeId
+  // 只描了原图的一块时才有：那块在原图里的位置与尺寸（像素）——
+  // 模型据此知道"这次只覆盖了局部"，以及该按原图坐标把它摆到哪。
+  if (metrics.crop !== undefined && metrics.crop !== null) base.crop = metrics.crop
+  return toLosslessJson(base)
 }
 
 /**
@@ -870,6 +1265,12 @@ export function summarizeTraceForAi(metrics, extra) {
  * @returns {{svg:string, metrics:object}}
  */
 export function traceRasterToSvg(raster, rawOptions) {
+  let stageAt = typeof rawOptions?.onTiming === 'function' ? performance.now() : 0
+  const mark = (name) => {
+    if (!stageAt) return
+    const now = performance.now()
+    rawOptions.onTiming(name, now - stageAt); stageAt = now
+  }
   const resolved = resolveTraceOptions(rawOptions)
   const options = resolved.options
   const preset = resolved.preset
@@ -930,8 +1331,30 @@ export function traceRasterToSvg(raster, rawOptions) {
     }
   }
 
-  // ② 背景 + 调色板
-  const isBg = markBackground(work, width, height, options)
+  // ② 去背景：removeBg 已由 resolveTraceOptions 规范化为 always|never（无 auto）
+  const removeMode = normalizeRemoveBg(options.removeBg)
+  let solid = null
+  let bgDetect = { hasSolid: false, mode: removeMode, matchRatio: 0, kind: null, color: null }
+  if (removeMode === 'never') {
+    solid = null
+  } else {
+    // true：先识纯色/透明底再泛洪；识不到则近白回退（旧 always 行为）
+    solid = detectSolidBackground(work, width, height, options)
+    if (solid !== null) {
+      bgDetect = {
+        hasSolid: true,
+        mode: removeMode,
+        matchRatio: solid.matchRatio,
+        kind: solid.kind,
+        color: solid.color === null || solid.color === undefined ? null : solid.color.slice(),
+      }
+    } else {
+      solid = { kind: 'legacy-nearwhite', matchRatio: 1, color: null }
+      bgDetect = { hasSolid: false, mode: removeMode, matchRatio: 1, kind: 'legacy-nearwhite', color: null }
+    }
+  }
+  const keepBackground = solid === null
+  const isBg = markBackground(work, width, height, options, solid)
   const bgMean = [255, 255, 255]
   {
     let n = 0
@@ -952,7 +1375,11 @@ export function traceRasterToSvg(raster, rawOptions) {
 
   const fgIndex = []
   for (let i = 0; i < width * height; i += 1) if (isBg[i] === 0) fgIndex.push(i)
-  if (fgIndex.length === 0) throw new Error('这张图整幅都是背景色（近白/近灰），没有可画的像素')
+  if (fgIndex.length === 0) {
+    const error = new Error('这张图整幅都是背景色，没有可画的像素')
+    error.code = 'EMPTY_FOREGROUND'
+    throw error
+  }
 
   // 保护区：暗前景像素（线稿）—— despeckle / ladder 都不动它们
   const protectMask = new Uint8Array(width * height)
@@ -968,8 +1395,17 @@ export function traceRasterToSvg(raster, rawOptions) {
     }
   }
 
-  const built = buildPalette(work, fgIndex, colors, colorsDark, colorsFillOpt, protectLuma, seeds)
-  const palette = [bgMean]
+  mark('pixelProcessing')
+  const candidate = options.paletteOverride
+  const override = Array.isArray(candidate) && typeof options.paletteValidator === 'function' &&
+    !options.paletteValidator(work, fgIndex, candidate) ? null : candidate
+  const overrideDark = Array.isArray(override) ? override.filter((p) => lumaRgb(p[0], p[1], p[2]) <= protectLuma).length : 0
+  const built = Array.isArray(override) && override.length > 0
+    ? { cents: override, colorsDark: overrideDark, colorsFill: override.length - overrideDark,
+        darkSamples: protectPixels, fillSamples: fgIndex.length - protectPixels }
+    : buildPalette(work, fgIndex, colors, colorsDark, colorsFillOpt, protectLuma, seeds, options.adaptiveDarkColors)
+  // 保留背景时不预留"不画的 label 0"：所有 k-means 色都画出来，否则白/浅色区域会被强行重映射。
+  const palette = keepBackground ? [] : [bgMean]
   for (let c = 0; c < built.cents.length; c += 1) {
     palette.push([
       clamp(Math.round(built.cents[c][0]), 0, 255),
@@ -977,10 +1413,11 @@ export function traceRasterToSvg(raster, rawOptions) {
       clamp(Math.round(built.cents[c][2]), 0, 255),
     ])
   }
+  mark('paletteQuantization')
   const colorCount = palette.length
   const protectLabels = new Uint8Array(colorCount)
   if (protectLuma > 0) {
-    for (let c = 1; c < colorCount; c += 1) {
+    for (let c = keepBackground ? 0 : 1; c < colorCount; c += 1) {
       const p = palette[c]
       if (lumaRgb(p[0], p[1], p[2]) <= protectLuma) protectLabels[c] = 1
     }
@@ -996,6 +1433,7 @@ export function traceRasterToSvg(raster, rawOptions) {
     paletteLuma[c] = lumaRgb(palette[c][0], palette[c][1], palette[c][2])
   }
   const px = [0, 0, 0]
+  let lastR = NaN, lastG = NaN, lastB = NaN, lastLabel = 0
   for (let y = 0; y < sh; y += 1) {
     const fy = (y + 0.5) / ss - 0.5
     for (let x = 0; x < sw; x += 1) {
@@ -1016,18 +1454,23 @@ export function traceRasterToSvg(raster, rawOptions) {
         const v11 = work[(y1 * width + x1) * 4 + c]
         px[c] = (v00 * (1 - tx) + v10 * tx) * (1 - ty) + (v01 * (1 - tx) + v11 * tx) * ty
       }
-      let bi = 0
-      let bd = Infinity
-      for (let c = 0; c < colorCount; c += 1) {
-        const p = palette[c]
-        const dr = px[0] - p[0]
-        const dg = px[1] - p[1]
-        const db = px[2] - p[2]
-        const d = dr * dr + dg * dg + db * db
-        if (d < bd) {
-          bd = d
-          bi = c
+      let bi = lastLabel
+      // Reuse only the exact floating-point sample, without rounding/cache growth.
+      if (px[0] !== lastR || px[1] !== lastG || px[2] !== lastB) {
+        bi = 0
+        let bd = Infinity
+        for (let c = 0; c < colorCount; c += 1) {
+          const p = palette[c]
+          const dr = px[0] - p[0]
+          const dg = px[1] - p[1]
+          const db = px[2] - p[2]
+          const d = dr * dr + dg * dg + db * db
+          if (d < bd) {
+            bd = d
+            bi = c
+          }
         }
+        lastR = px[0]; lastG = px[1]; lastB = px[2]; lastLabel = bi
       }
       gridLabels[y * sw + x] = bi
     }
@@ -1040,37 +1483,28 @@ export function traceRasterToSvg(raster, rawOptions) {
   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)
+      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
-          hist[gridLabels[yy * sw + xx]] += 1
+          const label = gridLabels[yy * sw + xx]
+          hist[label] += 1
+          const L = paletteLuma[label]
+          if (L < minL) minL = L
+          if (L > maxL) maxL = L
         }
       }
+      if (majorityContrast > 0 && maxL - minL >= majorityContrast) {
+        scratch[y * sw + x] = self
+        majoritySkipped += 1
+        continue
+      }
       let bi = self
       let bc = 0
       for (let c = 0; c < colorCount; c += 1) {
@@ -1105,40 +1539,44 @@ export function traceRasterToSvg(raster, rawOptions) {
     }
   }
 
-  // 背景色（label 0）只给泛洪底色用，且最终不画 path。
+  // 抠底时：label 0 = 泛洪底色，最终不画 path。
   // 白衣白底时，角色内部的白也会被最近邻归到 palette[0] —— 若不改回前景色，
   // 跳过绘制 label 0 就会把裙子/头发抠成透明洞。
+  // 保留背景时没有专用 bg 槽，跳过这段重映射。
   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
+  if (keepBackground === false) {
+    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
     }
-    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 backgroundLabel = keepBackground ? -1 : 0
+  const speckle = despeckle(labels, width, height, palette, minArea, maskOrNull, labelsOrNull, backgroundLabel)
+  const regionMerge = despeckle(labels, width, height, palette, minRegionArea, maskOrNull, labelsOrNull, backgroundLabel)
   const labelDump = options.includeLabels === true
     ? {
         width: width, height: height, colors: colorCount,
@@ -1147,6 +1585,7 @@ export function traceRasterToSvg(raster, rawOptions) {
       }
     : null
 
+  mark('labelProcessing')
   // ④ 连通域 + 轮廓（记下区域是否受保护，供 ladder 保留细环）
   const comp = new Int32Array(width * height).fill(-1)
   const regionLabel = []
@@ -1200,6 +1639,7 @@ export function traceRasterToSvg(raster, rawOptions) {
         points: loops[i].points,
         area: loops[i].area,
         protected: protectedLoop,
+        region: id,
       }
       if (loops[i].area < 0) bucket.outer.push(tagged)
       else bucket.hole.push(tagged)
@@ -1219,14 +1659,20 @@ export function traceRasterToSvg(raster, rawOptions) {
     return byColor[b].area - byColor[a].area
   })
 
+  mark('contours')
   let attempts = 0
   let pathCount = 0
   let loopCount = 0
   let loopsProtectedKept = 0
+  let fragments = 0
+  let loopsDropped = 0
+  let geometryPreserved = true
+  let appliedEpsilon = options.epsilon
   let svg = ''
+  let drawingLayers = []
   // 超预算就逐步收紧：先抬 RDP 容差，再丢小洞（受保护环永不因 minLoopArea 丢弃）
   const ladder = [
-    { epsilon: options.epsilon, minLoopArea: 4 },
+    { epsilon: options.epsilon, minLoopArea: 0 },
     { epsilon: Math.max(options.epsilon, 2.5), minLoopArea: 4 },
     { epsilon: Math.max(options.epsilon, 3), minLoopArea: 9 },
     { epsilon: Math.max(options.epsilon, 3.5), minLoopArea: 25 },
@@ -1236,37 +1682,61 @@ export function traceRasterToSvg(raster, rawOptions) {
     attempts = step + 1
     const plan = ladder[step]
     let body = ''
+    drawingLayers = []
     pathCount = 0
     loopCount = 0
     loopsProtectedKept = 0
+    fragments = 0
+    loopsDropped = 0
+    geometryPreserved = true
+    appliedEpsilon = plan.epsilon
     for (let k = 0; k < order.length; k += 1) {
-      // label 0 = 泛洪标出的截图底色：不画（SVG 该处透明）。
+      // 抠底时 label 0 = 泛洪底色：不画（SVG 该处透明）。
       // 若画成 path，角色左右两块互不连通的底色会进同一条 nonzero path，
       // 绕向抵消时会出现"一侧透明、一侧实心白"的假背景（插画发丝顶天立地时必现）。
-      if (order[k] === 0) continue
+      // 保留背景时没有专用 bg 槽，label 0 也是正常色，照画。
+      if (keepBackground === false && order[k] === 0) continue
       const bucket = byColor[order[k]]
       let d = ''
+      const drawingRegions = options.includeDrawing === true ? new Map() : null
       const all = bucket.outer.concat(bucket.hole)
       for (let i = 0; i < all.length; i += 1) {
         const loop = all[i]
-        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
+        if (!loop.protected && Math.abs(loop.area) < plan.minLoopArea) {
+          loopsDropped += 1
+          geometryPreserved = false
+          continue
+        }
+        // 格边跟随已保证外环与洞绕向相反，保留绕向才能用 nonzero 挖空。
+        const points = simplifyClosed(loop.points, plan.epsilon)
+        const seg = encodeLoop(points, options.precision)
+        if (seg === null) {
+          loopsDropped += 1
+          geometryPreserved = false
+          continue
+        }
+        if (!sameLoopGeometry(loop.points, points)) geometryPreserved = false
         d += seg
+        if (drawingRegions !== null) {
+          const region = drawingRegions.get(loop.region) || { d: '', area: regionArea[loop.region] }
+          region.d += seg
+          drawingRegions.set(loop.region, region)
+        }
         loopCount += 1
+        if (loop.area < 0) fragments += 1
         if (loop.protected) loopsProtectedKept += 1
       }
       if (d === '') continue
       body += "<path fill='" + hex(palette[order[k]]) + "' fill-rule='nonzero' d='" + d + "'/>"
+      if (drawingRegions !== null) drawingLayers.push({ fill: hex(palette[order[k]]), regions: Array.from(drawingRegions.values()) })
       pathCount += 1
     }
     svg = "<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 " + width + " " + height + "'>" + body + '</svg>'
     if (svg.length <= options.maxBytes) break
   }
 
-  // 精确性度量：各色层覆盖的像素数之和 vs 图像总像素（格边轮廓下两者应当完全一致）
+  mark('svgSerialization')
+  // 标签分区完整性与输出轮廓无损性分开；面积累加不能证明最终 SVG 正确。
   let covered = 0
   for (let c = 0; c < colorCount; c += 1) covered += byColor[c].area
   const loopsTotal = { value: 0 }
@@ -1280,8 +1750,8 @@ export function traceRasterToSvg(raster, rawOptions) {
   const optionsApplied = {
     preset: preset,
     colors: colors,
-    colorsDark: colorsDark,
-    colorsFill: colorsFillOpt,
+    colorsDark: options.adaptiveDarkColors ? built.colorsDark : colorsDark,
+    colorsFill: options.adaptiveDarkColors ? built.colorsFill : colorsFillOpt,
     grid: sized.grid,
     gridH: sized.gridH,
     scale: scale,
@@ -1291,6 +1761,9 @@ export function traceRasterToSvg(raster, rawOptions) {
     minRegionArea: minRegionArea,
     protectLuma: protectLuma,
     majorityContrast: majorityContrast,
+    removeBg: removeMode,
+    bgSolidTol: options.bgSolidTol,
+    bgSolidBorderRatio: options.bgSolidBorderRatio,
   }
 
   const metrics = {
@@ -1303,7 +1776,7 @@ export function traceRasterToSvg(raster, rawOptions) {
     gridH: sized.gridH,
     bgColor: bgColor.slice(),
     sizeNotes: sized.sizeNotes,
-    colors: colorCount - 1,
+    colors: keepBackground ? colorCount : colorCount - 1,
     colorsDark: built.colorsDark,
     colorsFill: built.colorsFill,
     darkSamples: built.darkSamples,
@@ -1312,6 +1785,8 @@ export function traceRasterToSvg(raster, rawOptions) {
     protectPixels: protectPixels,
     fgRelabeledFromBg: fgRelabeledFromBg,
     bgForced: bgForced,
+    bgRemoved: keepBackground === false,
+    bgDetect: bgDetect,
     majorityContrast: majorityContrast,
     majoritySkipped: majoritySkipped,
     majorityApplied: majorityApplied,
@@ -1329,10 +1804,16 @@ export function traceRasterToSvg(raster, rawOptions) {
     loops: loopsTotal.value,
     paths: pathCount,
     loopsKept: loopCount,
+    fragments: fragments,
     loopsProtectedKept: loopsProtectedKept,
-    drawnPixels: covered,
+    drawnPixels: geometryPreserved ? (keepBackground ? covered : fgIndex.length) : null,
     totalPixels: width * height,
-    exactPixelCoverage: covered === width * height,
+    exactPixelCoverage: covered === width * height && geometryPreserved,
+    labelPartitionComplete: covered === width * height,
+    coverageBasis: 'quantized-label-map',
+    loopsDropped: loopsDropped,
+    budgetExceeded: svg.length > options.maxBytes,
+    appliedEpsilon: appliedEpsilon,
     svgChars: svg.length,
     budget: options.maxBytes,
     attempts: attempts,
@@ -1340,9 +1821,17 @@ export function traceRasterToSvg(raster, rawOptions) {
     optionsApplied: optionsApplied,
   }
   metrics.tuneHint = hintTraceTune(metrics)
+  mark('metrics')
 
   return {
     svg: svg,
+    ...(options.includeDrawing === true ? { drawing: {
+      viewBox: [0, 0, width, height],
+      fills: drawingLayers.map((layer) => layer.fill),
+      // Keep each region's outer contour and holes together; reveal large areas before fine details.
+      steps: drawingLayers.flatMap((layer, index) => layer.regions.map((region) => ({ layer: index, d: region.d, area: region.area })))
+        .sort((a, b) => b.area - a.area),
+    } } : {}),
     labels: labelDump,
     metrics: metrics,
   }