castle-web-cli 0.4.123 → 0.4.124

package/kits/physics-2d/engine/svgImport.js

@@ -0,0 +1,1056 @@
+// Browser-safe SVG → stacked path-layer import.
+// Convert an LLM-emitted SVG into shapes + baked grid. See scripts/svg-emission-guide.md.
+
+import {
+  AGENT_PALETTE_16,
+  allocatePaletteKeys,
+  fromCells,
+  normalizeHex,
+  quantizeToPalette,
+  KEY_ALPHABET,
+} from './pxart.js';
+import {
+  bakePathCell,
+  pointsEqual,
+  roundCoord,
+  subpathPoints,
+  subpathVertexCount,
+  translatePathData,
+} from './pxartPath.js';
+
+const KAPPA = 0.5522847498;
+const STROKE_PHASE_NUDGE = 0.05;
+
+const NAMED_COLORS = {
+  black: '#000000',
+  white: '#ffffff',
+  red: '#ff0000',
+  green: '#008000',
+  blue: '#0000ff',
+  yellow: '#ffff00',
+  cyan: '#00ffff',
+  magenta: '#ff00ff',
+  orange: '#ffa500',
+  gray: '#808080',
+  grey: '#808080',
+  silver: '#c0c0c0',
+  maroon: '#800000',
+  purple: '#800080',
+  teal: '#008080',
+  navy: '#000080',
+  lime: '#00ff00',
+  aqua: '#00ffff',
+  fuchsia: '#ff00ff',
+  none: null,
+  transparent: null,
+};
+
+const VOIDISH = new Set([
+  'path',
+  'polygon',
+  'polyline',
+  'rect',
+  'circle',
+  'ellipse',
+  'line',
+  'image',
+  'stop',
+]);
+
+function parseAttrs(raw) {
+  const attrs = {};
+  const re = /([:\w-]+)\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s"'=<>`]+))/g;
+  let m;
+  while ((m = re.exec(raw))) {
+    attrs[m[1].toLowerCase()] = m[2] ?? m[3] ?? m[4] ?? '';
+  }
+  return attrs;
+}
+
+function parseStyle(style) {
+  const out = {};
+  if (!style) return out;
+  for (const part of String(style).split(';')) {
+    const i = part.indexOf(':');
+    if (i < 0) continue;
+    const k = part.slice(0, i).trim().toLowerCase();
+    const v = part.slice(i + 1).trim();
+    if (k) out[k] = v;
+  }
+  return out;
+}
+
+function walkElements(svgText) {
+  const re = /<!--[\s\S]*?-->|<!\[CDATA\[[\s\S]*?\]\]>|<\/?([A-Za-z][\w:-]*)\b([^>]*)>/g;
+  const stack = [];
+  const roots = [];
+  let m;
+  while ((m = re.exec(svgText))) {
+    const full = m[0];
+    if (full.startsWith('<!--') || full.startsWith('<![CDATA')) continue;
+    const name = m[1].toLowerCase();
+    const attrRaw = m[2] ?? '';
+    if (full.startsWith('</')) {
+      while (stack.length) {
+        const top = stack.pop();
+        if (top.name === name) break;
+      }
+      continue;
+    }
+    const selfClose = /\/>$/.test(full);
+    const el = { name, attrs: parseAttrs(attrRaw), children: [] };
+    if (stack.length) stack[stack.length - 1].children.push(el);
+    else roots.push(el);
+    if (!selfClose && !VOIDISH.has(name)) stack.push(el);
+  }
+  return roots;
+}
+
+function findSvgRoot(nodes) {
+  for (const n of nodes) {
+    if (n.name === 'svg') return n;
+    const inner = findSvgRoot(n.children);
+    if (inner) return inner;
+  }
+  return null;
+}
+
+function parseViewBox(attrs) {
+  if (attrs.viewbox) {
+    const parts = attrs.viewbox
+      .trim()
+      .split(/[\s,]+/)
+      .map(Number);
+    if (parts.length === 4 && parts.every((n) => Number.isFinite(n))) {
+      return { minX: parts[0], minY: parts[1], width: parts[2], height: parts[3] };
+    }
+  }
+  const w = parseFloat(attrs.width);
+  const h = parseFloat(attrs.height);
+  if (Number.isFinite(w) && Number.isFinite(h) && w > 0 && h > 0) {
+    return { minX: 0, minY: 0, width: w, height: h };
+  }
+  return { minX: 0, minY: 0, width: 16, height: 16 };
+}
+
+function makeTransform(vb, size) {
+  const s = Math.min(size / vb.width, size / vb.height);
+  const ox = (size - vb.width * s) / 2 - vb.minX * s;
+  const oy = (size - vb.height * s) / 2 - vb.minY * s;
+  return {
+    scale: s,
+    xf: (x, y) => [x * s + ox, y * s + oy],
+  };
+}
+
+function resolveColor(raw, diagnostics, where) {
+  if (raw == null) return undefined;
+  const s = String(raw).trim().toLowerCase();
+  if (!s) return undefined;
+  if (s === 'none' || s === 'transparent') return null;
+  if (s.startsWith('url(')) {
+    diagnostics.rejected.push(`${where}: gradient/url paint (${raw})`);
+    return undefined;
+  }
+  const hex = normalizeHex(s);
+  if (hex) return hex.length === 9 ? hex.slice(0, 7) : hex;
+  if (Object.prototype.hasOwnProperty.call(NAMED_COLORS, s)) return NAMED_COLORS[s];
+  diagnostics.rejected.push(`${where}: unresolved color "${raw}"`);
+  return undefined;
+}
+
+function isEvenOddFillRule(attrs) {
+  const raw = attrs['fill-rule'] ?? attrs.fillRule ?? '';
+  return String(raw).toLowerCase() === 'evenodd';
+}
+
+function warnFillRuleIfNeeded(subpaths, attrs, tag, diagnostics) {
+  const closed = (subpaths ?? []).filter((s) => s.closed).length;
+  if (closed >= 2 && !isEvenOddFillRule(attrs)) {
+    diagnostics.notes.push(
+      `<${tag}>: ${closed} closed subpaths with default nonzero fill-rule; Castle renders even-odd`,
+    );
+  }
+}
+
+function presentation(attrs) {
+  const style = parseStyle(attrs.style);
+  return {
+    fill: style.fill ?? attrs.fill,
+    stroke: style.stroke ?? attrs.stroke,
+  };
+}
+
+function tokenizePathD(d) {
+  const tokens = [];
+  const re = /([A-Za-z])|([+-]?(?:\d*\.\d+|\d+)(?:[eE][+-]?\d+)?)/g;
+  let m;
+  while ((m = re.exec(d))) {
+    if (m[1]) tokens.push({ type: 'cmd', v: m[1] });
+    else tokens.push({ type: 'num', v: Number(m[2]) });
+  }
+  return tokens;
+}
+
+function lerp2(a, b, t) {
+  return [a[0] + (b[0] - a[0]) * t, a[1] + (b[1] - a[1]) * t];
+}
+
+function splitCubicAt(p0, c1, c2, p1, t) {
+  const p01 = lerp2(p0, c1, t);
+  const p12 = lerp2(c1, c2, t);
+  const p23 = lerp2(c2, p1, t);
+  const p012 = lerp2(p01, p12, t);
+  const p123 = lerp2(p12, p23, t);
+  const p0123 = lerp2(p012, p123, t);
+  return [
+    { p0, c1: p01, c2: p012, p1: p0123 },
+    { p0: p0123, c1: p123, c2: p23, p1 },
+  ];
+}
+
+function cubicInflectionTs(p0, c1, c2, p1) {
+  const steps = 64;
+  let prevSign = 0;
+  let prevT = 0;
+  let prevCross = 0;
+  const ts = [];
+  for (let i = 0; i <= steps; i++) {
+    const t = i / steps;
+    const mt = 1 - t;
+    const d1x = mt * mt * (c1[0] - p0[0]) + 2 * mt * t * (c2[0] - c1[0]) + t * t * (p1[0] - c2[0]);
+    const d1y = mt * mt * (c1[1] - p0[1]) + 2 * mt * t * (c2[1] - c1[1]) + t * t * (p1[1] - c2[1]);
+    const d2x = mt * (c2[0] - 2 * c1[0] + p0[0]) + t * (p1[0] - 2 * c2[0] + c1[0]);
+    const d2y = mt * (c2[1] - 2 * c1[1] + p0[1]) + t * (p1[1] - 2 * c2[1] + c1[1]);
+    const cross = d1x * d2y - d1y * d2x;
+    const sign = Math.sign(cross);
+    if (sign === 0 && t > 1e-3 && t < 1 - 1e-3) {
+      ts.push(t);
+      prevSign = 0;
+    } else if (prevSign !== 0 && sign !== 0 && sign !== prevSign) {
+      const frac = Math.abs(prevCross) / (Math.abs(prevCross) + Math.abs(cross));
+      const ti = prevT + frac * (t - prevT);
+      if (ti > 1e-3 && ti < 1 - 1e-3) ts.push(ti);
+      prevSign = sign;
+    } else if (sign !== 0) {
+      prevSign = sign;
+    }
+    prevT = t;
+    prevCross = cross;
+  }
+  return ts;
+}
+
+function splitCubicAtInflections(p0, c1, c2, p1) {
+  const ts = cubicInflectionTs(p0, c1, c2, p1);
+  if (!ts.length) return [{ p0, c1, c2, p1 }];
+  const pieces = [];
+  let cur = { p0, c1, c2, p1 };
+  let offset = 0;
+  for (const absT of ts) {
+    const localT = (absT - offset) / (1 - offset);
+    if (!(localT > 1e-3 && localT < 1 - 1e-3)) continue;
+    const [left, right] = splitCubicAt(cur.p0, cur.c1, cur.c2, cur.p1, localT);
+    pieces.push(left);
+    cur = right;
+    offset = absT;
+  }
+  pieces.push(cur);
+  return pieces;
+}
+
+/** Emit absolute cubic pieces for one SVG elliptical arc. */
+function arcToCubicSegments(x1, y1, rx, ry, phiDeg, largeArc, sweep, x2, y2) {
+  const out = [];
+  if (!Number.isFinite(rx) || !Number.isFinite(ry) || (rx === 0 && ry === 0)) {
+    out.push({ kind: 'L', x: x2, y: y2 });
+    return out;
+  }
+  if (x1 === x2 && y1 === y2) return out;
+
+  const phi = (phiDeg * Math.PI) / 180;
+  const cosPhi = Math.cos(phi);
+  const sinPhi = Math.sin(phi);
+  const dx = (x1 - x2) / 2;
+  const dy = (y1 - y2) / 2;
+  const x1p = cosPhi * dx + sinPhi * dy;
+  const y1p = -sinPhi * dx + cosPhi * dy;
+  let RX = Math.abs(rx);
+  let RY = Math.abs(ry);
+  const lam = (x1p * x1p) / (RX * RX) + (y1p * y1p) / (RY * RY);
+  if (lam > 1) {
+    const s = Math.sqrt(lam);
+    RX *= s;
+    RY *= s;
+  }
+  const RX2 = RX * RX;
+  const RY2 = RY * RY;
+  const x1p2 = x1p * x1p;
+  const y1p2 = y1p * y1p;
+  const num = RX2 * RY2 - RX2 * y1p2 - RY2 * x1p2;
+  const den = RX2 * y1p2 + RY2 * x1p2;
+  let cq = den === 0 ? 0 : Math.sqrt(Math.max(0, num / den));
+  if (largeArc === sweep) cq = -cq;
+  const cxp = (cq * (RX * y1p)) / RY;
+  const cyp = (cq * (-RY * x1p)) / RX;
+  const cx = cosPhi * cxp - sinPhi * cyp + (x1 + x2) / 2;
+  const cy = sinPhi * cxp + cosPhi * cyp + (y1 + y2) / 2;
+
+  function unitAngle(ux, uy, vx, vy) {
+    const sign = ux * vy - uy * vx < 0 ? -1 : 1;
+    const dot = ux * vx + uy * vy;
+    const ul = Math.hypot(ux, uy);
+    const vl = Math.hypot(vx, vy);
+    const c = Math.min(1, Math.max(-1, dot / (ul * vl || 1)));
+    return sign * Math.acos(c);
+  }
+
+  const v1x = (x1p - cxp) / RX;
+  const v1y = (y1p - cyp) / RY;
+  const v2x = (-x1p - cxp) / RX;
+  const v2y = (-y1p - cyp) / RY;
+  let theta1 = unitAngle(1, 0, v1x, v1y);
+  let dTheta = unitAngle(v1x, v1y, v2x, v2y);
+  if (!sweep && dTheta > 0) dTheta -= 2 * Math.PI;
+  if (sweep && dTheta < 0) dTheta += 2 * Math.PI;
+
+  function pointAt(theta) {
+    const cosT = Math.cos(theta);
+    const sinT = Math.sin(theta);
+    return [
+      cosPhi * RX * cosT - sinPhi * RY * sinT + cx,
+      sinPhi * RX * cosT + cosPhi * RY * sinT + cy,
+    ];
+  }
+
+  function tangentAt(theta) {
+    const tx = -RX * Math.sin(theta);
+    const ty = RY * Math.cos(theta);
+    return [cosPhi * tx - sinPhi * ty, sinPhi * tx + cosPhi * ty];
+  }
+
+  const maxStep = Math.PI / 2;
+  const n = Math.max(1, Math.ceil(Math.abs(dTheta) / maxStep - 1e-12));
+  const step = dTheta / n;
+  let t0 = theta1;
+  for (let i = 1; i <= n; i++) {
+    const t1 = theta1 + step * i;
+    const p0 = pointAt(t0);
+    const p1 = pointAt(t1);
+    const T0 = tangentAt(t0);
+    const T1 = tangentAt(t1);
+    const k = (4 / 3) * Math.tan(Math.abs(step) / 4);
+    const c1 = [p0[0] + k * T0[0], p0[1] + k * T0[1]];
+    const c2 = [p1[0] - k * T1[0], p1[1] - k * T1[1]];
+    out.push({ kind: 'C', x1: c1[0], y1: c1[1], x2: c2[0], y2: c2[1], x: p1[0], y: p1[1] });
+    t0 = t1;
+  }
+  return out;
+}
+
+const PATH_CMDS = new Set([
+  'M', 'm', 'L', 'l', 'H', 'h', 'V', 'v', 'C', 'c', 'S', 's', 'Q', 'q', 'T', 't', 'A', 'a', 'Z', 'z',
+]);
+
+function parsePathD(d, diagnostics) {
+  const tokens = tokenizePathD(d);
+  let i = 0;
+  const subpaths = [];
+  let cx = 0;
+  let cy = 0;
+  let startX = 0;
+  let startY = 0;
+  let lastCtrl = null;
+  let lastCmd = null;
+  let reflectCmd = null;
+  let current = null;
+
+  function num() {
+    if (i >= tokens.length || tokens[i].type !== 'num') return null;
+    return tokens[i++].v;
+  }
+
+  function ensureSub() {
+    if (!current) {
+      current = { closed: false, segs: [], start: [cx, cy] };
+      subpaths.push(current);
+    }
+  }
+
+  while (i < tokens.length) {
+    let cmd;
+    if (tokens[i].type === 'cmd') {
+      cmd = tokens[i++].v;
+      if (!PATH_CMDS.has(cmd)) {
+        if (diagnostics) diagnostics.rejected.push(`path d: unknown command '${cmd}'`);
+        break;
+      }
+      lastCmd = cmd;
+    } else if (!lastCmd) break;
+    else cmd = lastCmd;
+    const rel = cmd === cmd.toLowerCase();
+    const c = cmd.toUpperCase();
+
+    if (c === 'A') {
+      while (i < tokens.length && tokens[i].type === 'num') {
+        const rx = num();
+        const ry = num();
+        const phi = num();
+        const large = num();
+        const sweep = num();
+        const x = num();
+        const y = num();
+        if ([rx, ry, phi, large, sweep, x, y].some((v) => v == null)) break;
+        const nx = rel ? cx + x : x;
+        const ny = rel ? cy + y : y;
+        ensureSub();
+        for (const piece of arcToCubicSegments(cx, cy, rx, ry, phi, !!large, !!sweep, nx, ny)) {
+          current.segs.push(piece);
+        }
+        cx = nx;
+        cy = ny;
+        lastCtrl = null;
+        reflectCmd = null;
+      }
+      continue;
+    }
+
+    if (c === 'M') {
+      const x0 = num();
+      const y0 = num();
+      if (x0 == null || y0 == null) break;
+      cx = rel ? cx + x0 : x0;
+      cy = rel ? cy + y0 : y0;
+      startX = cx;
+      startY = cy;
+      current = { closed: false, segs: [], start: [cx, cy] };
+      subpaths.push(current);
+      lastCtrl = null;
+      reflectCmd = null;
+      while (i < tokens.length && tokens[i].type === 'num') {
+        const x = num();
+        const y = num();
+        if (x == null || y == null) break;
+        const nx = rel ? cx + x : x;
+        const ny = rel ? cy + y : y;
+        current.segs.push({ kind: 'L', x: nx, y: ny });
+        cx = nx;
+        cy = ny;
+        lastCtrl = null;
+        reflectCmd = null;
+      }
+      lastCmd = rel ? 'l' : 'L';
+      continue;
+    }
+
+    if (c === 'Z') {
+      if (current) {
+        current.closed = true;
+        if (cx !== startX || cy !== startY) {
+          current.segs.push({ kind: 'L', x: startX, y: startY });
+        }
+        cx = startX;
+        cy = startY;
+      }
+      current = null;
+      lastCtrl = null;
+      reflectCmd = null;
+      continue;
+    }
+
+    ensureSub();
+
+    if (c === 'L') {
+      while (i < tokens.length && tokens[i].type === 'num') {
+        const x = num();
+        const y = num();
+        if (x == null || y == null) break;
+        const nx = rel ? cx + x : x;
+        const ny = rel ? cy + y : y;
+        current.segs.push({ kind: 'L', x: nx, y: ny });
+        cx = nx;
+        cy = ny;
+        lastCtrl = null;
+        reflectCmd = null;
+      }
+      continue;
+    }
+
+    if (c === 'H') {
+      while (i < tokens.length && tokens[i].type === 'num') {
+        const x = num();
+        if (x == null) break;
+        const nx = rel ? cx + x : x;
+        current.segs.push({ kind: 'L', x: nx, y: cy });
+        cx = nx;
+        lastCtrl = null;
+        reflectCmd = null;
+      }
+      continue;
+    }
+
+    if (c === 'V') {
+      while (i < tokens.length && tokens[i].type === 'num') {
+        const y = num();
+        if (y == null) break;
+        const ny = rel ? cy + y : y;
+        current.segs.push({ kind: 'L', x: cx, y: ny });
+        cy = ny;
+        lastCtrl = null;
+        reflectCmd = null;
+      }
+      continue;
+    }
+
+    if (c === 'C') {
+      while (i < tokens.length && tokens[i].type === 'num') {
+        const x1 = num();
+        const y1 = num();
+        const x2 = num();
+        const y2 = num();
+        const x = num();
+        const y = num();
+        if ([x1, y1, x2, y2, x, y].some((v) => v == null)) break;
+        const ax1 = rel ? cx + x1 : x1;
+        const ay1 = rel ? cy + y1 : y1;
+        const ax2 = rel ? cx + x2 : x2;
+        const ay2 = rel ? cy + y2 : y2;
+        const nx = rel ? cx + x : x;
+        const ny = rel ? cy + y : y;
+        current.segs.push({ kind: 'C', x1: ax1, y1: ay1, x2: ax2, y2: ay2, x: nx, y: ny });
+        lastCtrl = [ax2, ay2];
+        cx = nx;
+        cy = ny;
+        reflectCmd = rel ? 'c' : 'C';
+      }
+      continue;
+    }
+
+    if (c === 'S') {
+      while (i < tokens.length && tokens[i].type === 'num') {
+        const x2 = num();
+        const y2 = num();
+        const x = num();
+        const y = num();
+        if ([x2, y2, x, y].some((v) => v == null)) break;
+        const smooth =
+          lastCtrl &&
+          reflectCmd &&
+          (reflectCmd === 'C' || reflectCmd === 'c' || reflectCmd === 'S' || reflectCmd === 's');
+        const ax1 = smooth ? 2 * cx - lastCtrl[0] : cx;
+        const ay1 = smooth ? 2 * cy - lastCtrl[1] : cy;
+        const ax2 = rel ? cx + x2 : x2;
+        const ay2 = rel ? cy + y2 : y2;
+        const nx = rel ? cx + x : x;
+        const ny = rel ? cy + y : y;
+        current.segs.push({ kind: 'C', x1: ax1, y1: ay1, x2: ax2, y2: ay2, x: nx, y: ny });
+        lastCtrl = [ax2, ay2];
+        cx = nx;
+        cy = ny;
+        reflectCmd = rel ? 's' : 'S';
+      }
+      continue;
+    }
+
+    if (c === 'Q') {
+      while (i < tokens.length && tokens[i].type === 'num') {
+        const x1 = num();
+        const y1 = num();
+        const x = num();
+        const y = num();
+        if ([x1, y1, x, y].some((v) => v == null)) break;
+        const ax1 = rel ? cx + x1 : x1;
+        const ay1 = rel ? cy + y1 : y1;
+        const nx = rel ? cx + x : x;
+        const ny = rel ? cy + y : y;
+        current.segs.push({ kind: 'Q', x1: ax1, y1: ay1, x: nx, y: ny });
+        lastCtrl = [ax1, ay1];
+        cx = nx;
+        cy = ny;
+        reflectCmd = rel ? 'q' : 'Q';
+      }
+      continue;
+    }
+
+    if (c === 'T') {
+      while (i < tokens.length && tokens[i].type === 'num') {
+        const x = num();
+        const y = num();
+        if (x == null || y == null) break;
+        const smooth =
+          lastCtrl &&
+          reflectCmd &&
+          (reflectCmd === 'Q' || reflectCmd === 'q' || reflectCmd === 'T' || reflectCmd === 't');
+        const ax1 = smooth ? 2 * cx - lastCtrl[0] : cx;
+        const ay1 = smooth ? 2 * cy - lastCtrl[1] : cy;
+        const nx = rel ? cx + x : x;
+        const ny = rel ? cy + y : y;
+        current.segs.push({ kind: 'Q', x1: ax1, y1: ay1, x: nx, y: ny });
+        lastCtrl = [ax1, ay1];
+        cx = nx;
+        cy = ny;
+        reflectCmd = rel ? 't' : 'T';
+      }
+      continue;
+    }
+
+    break;
+  }
+
+  return { subpaths };
+}
+
+function parsePoints(pointsAttr) {
+  const nums = String(pointsAttr)
+    .trim()
+    .split(/[\s,]+/)
+    .map(Number)
+    .filter((n) => Number.isFinite(n));
+  const pts = [];
+  for (let i = 0; i + 1 < nums.length; i += 2) pts.push([nums[i], nums[i + 1]]);
+  return pts;
+}
+
+/** Absolute cubic control points → relative segment `{ to, c1?, c2? }`. */
+function toRelativeSegment(from, to, c1Abs, c2Abs) {
+  const seg = { to: [to[0], to[1]] };
+  if (c1Abs) {
+    const d1 = [c1Abs[0] - from[0], c1Abs[1] - from[1]];
+    if (Math.hypot(d1[0], d1[1]) >= 1e-12) seg.c1 = d1;
+  }
+  if (c2Abs) {
+    const d2 = [c2Abs[0] - to[0], c2Abs[1] - to[1]];
+    if (Math.hypot(d2[0], d2[1]) >= 1e-12) seg.c2 = d2;
+  }
+  return seg;
+}
+
+/** Four kappa cubics tracing an ellipse/circle in design space. */
+function ellipseToSubpath(cx, cy, rx, ry) {
+  const kx = KAPPA * rx;
+  const ky = KAPPA * ry;
+  const start = [cx + rx, cy];
+  const right = [cx, cy + ry];
+  const left = [cx - rx, cy];
+  const top = [cx, cy - ry];
+  const segs = [
+    toRelativeSegment(start, right, [cx + rx, cy + ky], [cx + kx, cy + ry]),
+    toRelativeSegment(right, left, [cx - kx, cy + ry], [cx - rx, cy + ky]),
+    toRelativeSegment(left, top, [cx - rx, cy - ky], [cx - kx, cy - ry]),
+    toRelativeSegment(top, start, [cx + kx, cy - ry], [cx + rx, cy - ky]),
+  ];
+  return { closed: true, start, segs };
+}
+
+function circleToSubpath(cx, cy, rx, ry) {
+  return { closed: true, ellipse: { cx, cy, rx, ry }, start: [cx + rx, cy], segs: [] };
+}
+
+function materializeEllipseSubpath(e, xf) {
+  const [cx, cy] = xf(e.cx, e.cy);
+  const [ex] = xf(e.cx + e.rx, e.cy);
+  const [, fy] = xf(e.cx, e.cy + e.ry);
+  const rx = Math.abs(ex - cx);
+  const ry = Math.abs(fy - cy);
+  return ellipseToSubpath(cx, cy, rx, ry);
+}
+
+function convertElement(el, diagnostics, inherited = {}) {
+  const tag = el.name;
+  if (tag === 'defs' || tag === 'clippath' || tag === 'mask') {
+    diagnostics.rejected.push(`<${tag}>: skipped container`);
+    return [];
+  }
+  if (tag === 'lineargradient' || tag === 'radialgradient') {
+    diagnostics.rejected.push(`<${tag}>: gradients not supported`);
+    return [];
+  }
+  if (tag === 'text' || tag === 'tspan' || tag === 'image' || tag === 'use' || tag === 'foreignobject') {
+    diagnostics.rejected.push(`<${tag}>: not supported`);
+    return [];
+  }
+  if (tag === 'line') {
+    diagnostics.rejected.push('<line>: not in v1 subset (use path/polyline)');
+    return [];
+  }
+  if (tag === 'title' || tag === 'desc' || tag === 'metadata' || tag === 'style') return [];
+  if (el.attrs.transform) {
+    diagnostics.rejected.push(`<${tag}>: transform attribute rejected`);
+    return [];
+  }
+
+  const pres = presentation(el.attrs);
+  const nextInherited = {
+    fill: pres.fill !== undefined ? pres.fill : inherited.fill,
+    stroke: pres.stroke !== undefined ? pres.stroke : inherited.stroke,
+  };
+
+  if (tag === 'g' || tag === 'svg') {
+    const out = [];
+    for (const child of el.children) out.push(...convertElement(child, diagnostics, nextInherited));
+    return out;
+  }
+
+  const filledTags = new Set(['path', 'polygon', 'rect', 'circle', 'ellipse']);
+  const defaultFill = filledTags.has(tag) ? '#000000' : 'none';
+  const fillRaw = nextInherited.fill !== undefined ? nextInherited.fill : defaultFill;
+  const strokeRaw = nextInherited.stroke !== undefined ? nextInherited.stroke : 'none';
+  const fill = resolveColor(fillRaw, diagnostics, `<${tag}> fill`);
+  const stroke = resolveColor(strokeRaw, diagnostics, `<${tag}> stroke`);
+  const fillHex = fill === undefined ? null : fill;
+  const strokeHex = stroke === undefined ? null : stroke;
+
+  if (tag === 'path') {
+    if (!el.attrs.d) {
+      diagnostics.rejected.push('<path>: missing d');
+      return [];
+    }
+    const parsed = parsePathD(el.attrs.d, diagnostics);
+    if (!parsed.subpaths.length) {
+      diagnostics.rejected.push('<path>: empty/unparsed d');
+      return [];
+    }
+    diagnostics.parsed.push('path');
+    if (fillHex) warnFillRuleIfNeeded(parsed.subpaths, el.attrs, 'path', diagnostics);
+    return [{ fill: fillHex, stroke: strokeHex, subpaths: parsed.subpaths }];
+  }
+
+  if (tag === 'polygon' || tag === 'polyline') {
+    const pts = parsePoints(el.attrs.points ?? '');
+    if (pts.length < 2) {
+      diagnostics.rejected.push(`<${tag}>: need ≥2 points`);
+      return [];
+    }
+    const segs = [];
+    for (let i = 1; i < pts.length; i++) segs.push({ kind: 'L', x: pts[i][0], y: pts[i][1] });
+    diagnostics.parsed.push(tag);
+    return [{ fill: fillHex, stroke: strokeHex, subpaths: [{ closed: tag === 'polygon', segs, start: pts[0] }] }];
+  }
+
+  if (tag === 'rect') {
+    const x = parseFloat(el.attrs.x ?? '0');
+    const y = parseFloat(el.attrs.y ?? '0');
+    const w = parseFloat(el.attrs.width ?? '0');
+    const h = parseFloat(el.attrs.height ?? '0');
+    if (!(w > 0 && h > 0)) {
+      diagnostics.rejected.push('<rect>: non-positive size');
+      return [];
+    }
+    diagnostics.parsed.push('rect');
+    return [
+      {
+        fill: fillHex,
+        stroke: strokeHex,
+        subpaths: [
+          {
+            closed: true,
+            segs: [
+              { kind: 'L', x: x + w, y },
+              { kind: 'L', x: x + w, y: y + h },
+              { kind: 'L', x, y: y + h },
+            ],
+            start: [x, y],
+          },
+        ],
+      },
+    ];
+  }
+
+  if (tag === 'circle') {
+    const cx = parseFloat(el.attrs.cx ?? '0');
+    const cy = parseFloat(el.attrs.cy ?? '0');
+    const r = parseFloat(el.attrs.r ?? '0');
+    if (!(r > 0)) {
+      diagnostics.rejected.push('<circle>: non-positive r');
+      return [];
+    }
+    diagnostics.parsed.push('circle');
+    return [{ fill: fillHex, stroke: strokeHex, subpaths: [circleToSubpath(cx, cy, r, r)] }];
+  }
+
+  if (tag === 'ellipse') {
+    const cx = parseFloat(el.attrs.cx ?? '0');
+    const cy = parseFloat(el.attrs.cy ?? '0');
+    const rx = parseFloat(el.attrs.rx ?? '0');
+    const ry = parseFloat(el.attrs.ry ?? '0');
+    if (!(rx > 0 && ry > 0)) {
+      diagnostics.rejected.push('<ellipse>: non-positive rx/ry');
+      return [];
+    }
+    diagnostics.parsed.push('ellipse');
+    return [{ fill: fillHex, stroke: strokeHex, subpaths: [circleToSubpath(cx, cy, rx, ry)] }];
+  }
+
+  diagnostics.rejected.push(`<${tag}>: not supported`);
+  return [];
+}
+
+/**
+ * Transform a raw parsed subpath into design-space cubic segments with relative
+ * handles. Closed Z closing segments that duplicate start are dropped later.
+ */
+function materializeSubpath(sub, xf) {
+  const start = xf(sub.start[0], sub.start[1]);
+  const segs = [];
+  let from = start;
+
+  for (const seg of sub.segs) {
+    if (seg.kind === 'L') {
+      const to = xf(seg.x, seg.y);
+      if (Math.hypot(to[0] - from[0], to[1] - from[1]) < 1e-12) continue;
+      segs.push({ to });
+      from = to;
+    } else if (seg.kind === 'C') {
+      const c1 = xf(seg.x1, seg.y1);
+      const c2 = xf(seg.x2, seg.y2);
+      const to = xf(seg.x, seg.y);
+      const pieces = splitCubicAtInflections(from, c1, c2, to);
+      for (const piece of pieces) {
+        if (Math.hypot(piece.p1[0] - from[0], piece.p1[1] - from[1]) < 1e-12) continue;
+        segs.push(toRelativeSegment(from, piece.p1, piece.c1, piece.c2));
+        from = piece.p1;
+      }
+    } else if (seg.kind === 'Q') {
+      const q = xf(seg.x1, seg.y1);
+      const to = xf(seg.x, seg.y);
+      const c1 = [from[0] + (2 / 3) * (q[0] - from[0]), from[1] + (2 / 3) * (q[1] - from[1])];
+      const c2 = [to[0] + (2 / 3) * (q[0] - to[0]), to[1] + (2 / 3) * (q[1] - to[1])];
+      const pieces = splitCubicAtInflections(from, c1, c2, to);
+      for (const piece of pieces) {
+        if (Math.hypot(piece.p1[0] - from[0], piece.p1[1] - from[1]) < 1e-12) continue;
+        segs.push(toRelativeSegment(from, piece.p1, piece.c1, piece.c2));
+        from = piece.p1;
+      }
+    }
+  }
+
+  return { closed: !!sub.closed, start, segs };
+}
+
+function roundSegment(seg) {
+  const out = { to: [roundCoord(seg.to[0]), roundCoord(seg.to[1])] };
+  if (seg.c1) out.c1 = [roundCoord(seg.c1[0]), roundCoord(seg.c1[1])];
+  if (seg.c2) out.c2 = [roundCoord(seg.c2[0]), roundCoord(seg.c2[1])];
+  return out;
+}
+
+function subpathHasCurvature(sub) {
+  return (sub.segs ?? []).some((seg) => seg.c1 || seg.c2);
+}
+
+/**
+ * Clean up a materialized subpath: round coords, drop degenerate segments,
+ * omit duplicate closing vertex, demote degenerate closed loops.
+ */
+function finalizeSubpath(sub) {
+  let closed = !!sub.closed;
+  const start = [roundCoord(sub.start[0]), roundCoord(sub.start[1])];
+  const segs = [];
+  let from = start;
+
+  for (const raw of sub.segs ?? []) {
+    const seg = roundSegment(raw);
+    const to = seg.to;
+    if (Math.hypot(to[0] - from[0], to[1] - from[1]) < 1e-12) continue;
+    if (!seg.c1 && !seg.c2) {
+      segs.push({ to });
+    } else {
+      const out = { to };
+      if (seg.c1 && Math.hypot(seg.c1[0], seg.c1[1]) >= 1e-12) out.c1 = seg.c1;
+      if (seg.c2 && Math.hypot(seg.c2[0], seg.c2[1]) >= 1e-12) out.c2 = seg.c2;
+      segs.push(out);
+    }
+    from = to;
+  }
+
+  // Canonical closure: the edge back to `start` is implied, so a straight
+  // closing segment is dropped. A curved one is kept — it carries geometry that
+  // an implied close can't express, e.g. the second arc of a lens.
+  const closer = segs[segs.length - 1];
+  if (closed && closer && !closer.c1 && !closer.c2 && pointsEqual(closer.to, start)) {
+    segs.pop();
+  }
+
+  const vertCount =
+    closed && segs.length > 0 && pointsEqual(segs[segs.length - 1].to, start)
+      ? segs.length
+      : 1 + segs.length;
+
+  if (closed && (vertCount < 2 || (vertCount === 2 && !subpathHasCurvature({ segs })))) {
+    closed = false;
+  }
+
+  return { closed, start, segs };
+}
+
+function isIntegerPhase(n) {
+  return Math.abs(n - Math.round(n)) < 1e-9;
+}
+
+function shapeHasIntegerPhase(subpaths) {
+  for (const sub of subpaths) {
+    for (const [x, y] of subpathPoints(sub)) {
+      if (isIntegerPhase(x) || isIntegerPhase(y)) return true;
+    }
+  }
+  return false;
+}
+
+function applyStrokePhaseNudge(shape) {
+  const nudged = translatePathData({ shapes: [shape] }, STROKE_PHASE_NUDGE, STROKE_PHASE_NUDGE).shapes[0];
+  return {
+    ...nudged,
+    subpaths: nudged.subpaths.map((sub) => finalizeSubpath(sub)),
+  };
+}
+
+/**
+ * Import SVG → stacked layer model.
+ * Returns { size, shapes, palette, keyOf, hexOf, diagnostics, refShapes }
+ * where refShapes are pre-nudge design-space shapes (palette keys) for scoring.
+ */
+export function importStackedSvg(svgText, size = 16, quantPalette = AGENT_PALETTE_16) {
+  const diagnostics = { parsed: [], rejected: [], notes: [] };
+  const roots = walkElements(svgText);
+  const svg = findSvgRoot(roots);
+  if (!svg) throw new Error('No <svg> root found');
+  if (svg.attrs.transform) diagnostics.rejected.push('<svg>: transform attribute rejected');
+
+  const vb = parseViewBox(svg.attrs);
+  const { xf } = makeTransform(vb, size);
+
+  const rawShapes = [];
+  for (const child of svg.children) {
+    if (child.name === 'g' && child.attrs.transform) {
+      diagnostics.rejected.push('<g>: transform attribute rejected (children skipped)');
+      continue;
+    }
+    rawShapes.push(...convertElement(child, diagnostics));
+  }
+
+  const paletteDrift = [];
+  const preNudge = [];
+  for (const shape of rawShapes) {
+    const strokeQ = shape.stroke ? quantizeToPalette(shape.stroke, quantPalette) : null;
+    const fillQ = shape.fill ? quantizeToPalette(shape.fill, quantPalette) : null;
+    if (shape.stroke && strokeQ) {
+      const from = normalizeHex(shape.stroke)?.slice(0, 7) ?? shape.stroke;
+      if (from !== strokeQ) paletteDrift.push({ role: 'stroke', from, to: strokeQ });
+    }
+    if (shape.fill && fillQ) {
+      const from = normalizeHex(shape.fill)?.slice(0, 7) ?? shape.fill;
+      if (from !== fillQ) paletteDrift.push({ role: 'fill', from, to: fillQ });
+    }
+    const subs = shape.subpaths.map((sub) =>
+      finalizeSubpath(
+        sub.ellipse ? materializeEllipseSubpath(sub.ellipse, xf) : materializeSubpath(sub, xf),
+      ),
+    );
+    preNudge.push({ fillHex: fillQ, strokeHex: strokeQ, subpaths: subs });
+  }
+
+  const usedHexes = [];
+  for (const s of preNudge) {
+    if (s.fillHex) usedHexes.push(s.fillHex);
+    if (s.strokeHex) usedHexes.push(s.strokeHex);
+  }
+  const { palette: paletteMap, keyOf } = allocatePaletteKeys(usedHexes);
+
+  const shapes = [];
+  let anchorsBefore = 0;
+  let anchorsAfter = 0;
+  for (const s of preNudge) {
+    let shapeObj = {
+      fill: s.fillHex ? keyOf.get(s.fillHex) : null,
+      stroke: s.strokeHex ? keyOf.get(s.strokeHex) : null,
+      subpaths: s.subpaths,
+    };
+    for (const sub of s.subpaths) anchorsBefore += subpathVertexCount(sub);
+
+    if (s.strokeHex && shapeHasIntegerPhase(s.subpaths)) {
+      shapeObj = applyStrokePhaseNudge(shapeObj);
+    }
+
+    for (const sub of shapeObj.subpaths) anchorsAfter += subpathVertexCount(sub);
+    shapes.push(shapeObj);
+  }
+
+  const refShapes = preNudge.map((s) => ({
+    fill: s.fillHex ? keyOf.get(s.fillHex) : null,
+    stroke: s.strokeHex ? keyOf.get(s.strokeHex) : null,
+    subpaths: s.subpaths,
+  }));
+
+  diagnostics.notes.push(
+    'stacked import: one shape per SVG element, painter order, cubic segments, uniform stroke nudge when integer-phase',
+  );
+  diagnostics.paletteDrift = paletteDrift;
+  diagnostics.anchorsBefore = anchorsBefore;
+  diagnostics.anchorsAfter = anchorsAfter;
+  diagnostics.shapeCount = shapes.length;
+
+  return {
+    size,
+    shapes,
+    refShapes,
+    palette: paletteMap,
+    keyOf,
+    diagnostics,
+  };
+}
+
+/** Public importer API used by tests / validation. */
+export function importSvg(svgText, size = 16, quantPalette = AGENT_PALETTE_16) {
+  const imported = importStackedSvg(svgText, size, quantPalette);
+  const { shapes, refShapes, palette, diagnostics } = imported;
+  const pathData = { shapes };
+  const grid = bakePathCell(pathData, size, size);
+
+  const paletteArr = [];
+  for (const ch of KEY_ALPHABET) {
+    if (palette[ch]) paletteArr.push({ key: ch, hex: palette[ch] });
+  }
+
+  const sprite = {
+    resolution: { width: size, height: size },
+    palette: paletteArr,
+    frames: [{}],
+    defaultDurationMs: 100,
+    tags: [],
+    layers: [
+      {
+        id: 'layer-0',
+        name: 'Path',
+        visible: true,
+        opacity: 1,
+        blendMode: 'normal',
+        kind: 'path',
+        cells: [{ grid, path: pathData }],
+      },
+    ],
+  };
+
+  return {
+    sprite,
+    pathData,
+    shapes,
+    refShapes,
+    grid,
+    diagnostics: {
+      ...diagnostics,
+      shapeCount: shapes.length,
+    },
+  };
+}
+
+/** Bake imported SVG to a compact pixel-only sprite (no path source). */
+export function importSvgToPixel(svgText, size = 16, quantPalette = AGENT_PALETTE_16) {
+  const { shapes, palette, diagnostics } = importStackedSvg(svgText, size, quantPalette);
+  const grid = bakePathCell({ shapes }, size, size);
+  const cells = grid.map((row) => row.split(''));
+  const paletteObj = {};
+  for (const [key, hex] of Object.entries(palette)) paletteObj[key] = hex;
+  const art = fromCells(paletteObj, cells);
+  return { art, grid, diagnostics };
+}
+