@leviosa-ai/detail-page-editor 0.1.0

package/lib/detail-page-canvas/export/pdf/geometry.ts

@@ -0,0 +1,309 @@
+import { fmt } from "./writer";
+
+/**
+ * Geometry for the PDF (.ai) exporter: SVG path data and the primitive shapes
+ * our documents use, lowered onto the four path operators PDF actually has
+ * (``m``, ``l``, ``c``, ``h``).
+ *
+ * Everything else — quadratics, arcs, smooth-curve shorthands, circles,
+ * rounded rects — is converted to cubic Béziers here, because PDF has no
+ * ellipse or arc operator at all.
+ */
+
+/** Max error of a circular arc approximated by one cubic Bézier (< 0.02%). */
+const KAPPA = 0.5522847498307936;
+
+/** Emit ``m``/``l``/``c``/``h`` operators for a rectangle, optionally rounded. */
+export function rectPath(x: number, y: number, w: number, h: number, r = 0): string[] {
+  const radius = Math.max(0, Math.min(r, w / 2, h / 2));
+  if (!radius) return [`${fmt(x)} ${fmt(y)} ${fmt(w)} ${fmt(h)} re`];
+  const k = radius * KAPPA;
+  const [x1, y1, x2, y2] = [x + radius, y + radius, x + w - radius, y + h - radius];
+  return [
+    `${fmt(x1)} ${fmt(y)} m`,
+    `${fmt(x2)} ${fmt(y)} l`,
+    `${fmt(x2 + k)} ${fmt(y)} ${fmt(x + w)} ${fmt(y1 - k)} ${fmt(x + w)} ${fmt(y1)} c`,
+    `${fmt(x + w)} ${fmt(y2)} l`,
+    `${fmt(x + w)} ${fmt(y2 + k)} ${fmt(x2 + k)} ${fmt(y + h)} ${fmt(x2)} ${fmt(y + h)} c`,
+    `${fmt(x1)} ${fmt(y + h)} l`,
+    `${fmt(x1 - k)} ${fmt(y + h)} ${fmt(x)} ${fmt(y2 + k)} ${fmt(x)} ${fmt(y2)} c`,
+    `${fmt(x)} ${fmt(y1)} l`,
+    `${fmt(x)} ${fmt(y1 - k)} ${fmt(x1 - k)} ${fmt(y)} ${fmt(x1)} ${fmt(y)} c`,
+    "h",
+  ];
+}
+
+/** Ellipse inscribed in the box, as four cubic Béziers. */
+export function ellipsePath(cx: number, cy: number, rx: number, ry: number): string[] {
+  const kx = rx * KAPPA;
+  const ky = ry * KAPPA;
+  return [
+    `${fmt(cx + rx)} ${fmt(cy)} m`,
+    `${fmt(cx + rx)} ${fmt(cy + ky)} ${fmt(cx + kx)} ${fmt(cy + ry)} ${fmt(cx)} ${fmt(cy + ry)} c`,
+    `${fmt(cx - kx)} ${fmt(cy + ry)} ${fmt(cx - rx)} ${fmt(cy + ky)} ${fmt(cx - rx)} ${fmt(cy)} c`,
+    `${fmt(cx - rx)} ${fmt(cy - ky)} ${fmt(cx - kx)} ${fmt(cy - ry)} ${fmt(cx)} ${fmt(cy - ry)} c`,
+    `${fmt(cx + kx)} ${fmt(cy - ry)} ${fmt(cx + rx)} ${fmt(cy - ky)} ${fmt(cx + rx)} ${fmt(cy)} c`,
+    "h",
+  ];
+}
+
+export function polygonPath(points: number[], close: boolean): string[] {
+  const ops: string[] = [];
+  for (let i = 0; i + 1 < points.length; i += 2) {
+    ops.push(`${fmt(points[i])} ${fmt(points[i + 1])} ${i === 0 ? "m" : "l"}`);
+  }
+  if (close && ops.length) ops.push("h");
+  return ops;
+}
+
+/** Parse an SVG ``points`` list ("1,2 3,4" / "1 2 3 4"). */
+export function parsePoints(value: string): number[] {
+  return (value.match(/-?\d*\.?\d+(?:e[-+]?\d+)?/gi) ?? []).map(Number);
+}
+
+type Cursor = { x: number; y: number; startX: number; startY: number };
+
+/**
+ * Elliptical arc → cubic Béziers (SVG implementation notes, F.6.5): the arc is
+ * un-rotated into a unit circle to recover the center and sweep, then split
+ * into ≤90° segments that a single cubic can hold.
+ */
+function arcToCurves(
+  x1: number,
+  y1: number,
+  rx: number,
+  ry: number,
+  angleDeg: number,
+  largeArc: boolean,
+  sweep: boolean,
+  x2: number,
+  y2: number,
+): number[][] {
+  if (rx === 0 || ry === 0) return [[x2, y2, x2, y2, x2, y2]];
+  const phi = (angleDeg * Math.PI) / 180;
+  const cos = Math.cos(phi);
+  const sin = Math.sin(phi);
+  const dx = (x1 - x2) / 2;
+  const dy = (y1 - y2) / 2;
+  const x1p = cos * dx + sin * dy;
+  const y1p = -sin * dx + cos * dy;
+  let arx = Math.abs(rx);
+  let ary = Math.abs(ry);
+  // Radii too small to reach the endpoint are scaled up (SVG F.6.6).
+  const lambda = (x1p * x1p) / (arx * arx) + (y1p * y1p) / (ary * ary);
+  if (lambda > 1) {
+    const s = Math.sqrt(lambda);
+    arx *= s;
+    ary *= s;
+  }
+  const sign = largeArc === sweep ? -1 : 1;
+  const num =
+    arx * arx * ary * ary - arx * arx * y1p * y1p - ary * ary * x1p * x1p;
+  const den = arx * arx * y1p * y1p + ary * ary * x1p * x1p;
+  const co = sign * Math.sqrt(Math.max(0, num / den));
+  const cxp = (co * (arx * y1p)) / ary;
+  const cyp = (co * -(ary * x1p)) / arx;
+  const cx = cos * cxp - sin * cyp + (x1 + x2) / 2;
+  const cy = sin * cxp + cos * cyp + (y1 + y2) / 2;
+
+  const angle = (ux: number, uy: number, vx: number, vy: number) => {
+    const dot = ux * vx + uy * vy;
+    const len = Math.sqrt((ux * ux + uy * uy) * (vx * vx + vy * vy));
+    const a = Math.acos(Math.min(1, Math.max(-1, dot / (len || 1))));
+    return ux * vy - uy * vx < 0 ? -a : a;
+  };
+  const theta = angle(1, 0, (x1p - cxp) / arx, (y1p - cyp) / ary);
+  let delta = angle(
+    (x1p - cxp) / arx,
+    (y1p - cyp) / ary,
+    (-x1p - cxp) / arx,
+    (-y1p - cyp) / ary,
+  );
+  if (!sweep && delta > 0) delta -= 2 * Math.PI;
+  else if (sweep && delta < 0) delta += 2 * Math.PI;
+
+  const segments = Math.max(1, Math.ceil(Math.abs(delta / (Math.PI / 2))));
+  const step = delta / segments;
+  // Bézier handle length for a `step`-radian circular arc.
+  const t = ((4 / 3) * Math.tan(step / 4));
+  const curves: number[][] = [];
+  for (let i = 0; i < segments; i++) {
+    const a0 = theta + i * step;
+    const a1 = a0 + step;
+    const cosA0 = Math.cos(a0);
+    const sinA0 = Math.sin(a0);
+    const cosA1 = Math.cos(a1);
+    const sinA1 = Math.sin(a1);
+    const map = (px: number, py: number): [number, number] => [
+      cos * arx * px - sin * ary * py + cx,
+      sin * arx * px + cos * ary * py + cy,
+    ];
+    const [c1x, c1y] = map(cosA0 - t * sinA0, sinA0 + t * cosA0);
+    const [c2x, c2y] = map(cosA1 + t * sinA1, sinA1 - t * cosA1);
+    const [ex, ey] = map(cosA1, sinA1);
+    curves.push([c1x, c1y, c2x, c2y, ex, ey]);
+  }
+  return curves;
+}
+
+/**
+ * SVG path data → PDF path operators.
+ *
+ * Supports the full command set our decomposer emits (M m L l H h V v C c
+ * S s Q q A a Z z) — arcs alone account for the rounded corners of every
+ * speech bubble, so "just handle lines and curves" is not an option.
+ */
+export function svgPathToPdf(d: string): string[] {
+  const tokens = d.match(/[a-zA-Z]|-?\d*\.?\d+(?:e[-+]?\d+)?/gi) ?? [];
+  const ops: string[] = [];
+  const cur: Cursor = { x: 0, y: 0, startX: 0, startY: 0 };
+  let lastControl: [number, number] | null = null;
+  let command = "";
+  let i = 0;
+
+  const next = () => Number(tokens[i++]);
+  const moveTo = (x: number, y: number) => {
+    ops.push(`${fmt(x)} ${fmt(y)} m`);
+    cur.x = cur.startX = x;
+    cur.y = cur.startY = y;
+  };
+  const lineTo = (x: number, y: number) => {
+    ops.push(`${fmt(x)} ${fmt(y)} l`);
+    cur.x = x;
+    cur.y = y;
+  };
+  const curveTo = (
+    c1x: number,
+    c1y: number,
+    c2x: number,
+    c2y: number,
+    x: number,
+    y: number,
+  ) => {
+    ops.push(
+      `${fmt(c1x)} ${fmt(c1y)} ${fmt(c2x)} ${fmt(c2y)} ${fmt(x)} ${fmt(y)} c`,
+    );
+    cur.x = x;
+    cur.y = y;
+  };
+
+  while (i < tokens.length) {
+    const token = tokens[i];
+    if (/[a-zA-Z]/.test(token)) {
+      command = token;
+      i++;
+      // A bare Z carries no arguments.
+      if (command === "Z" || command === "z") {
+        ops.push("h");
+        cur.x = cur.startX;
+        cur.y = cur.startY;
+        lastControl = null;
+        continue;
+      }
+    } else if (!command) {
+      break; // numbers before any command: malformed
+    } else if (command === "M") {
+      command = "L"; // repeated pairs after M are implicit lineTos
+    } else if (command === "m") {
+      command = "l";
+    }
+
+    const rel = command === command.toLowerCase();
+    const ox = rel ? cur.x : 0;
+    const oy = rel ? cur.y : 0;
+
+    switch (command.toUpperCase()) {
+      case "M":
+        moveTo(next() + ox, next() + oy);
+        lastControl = null;
+        break;
+      case "L":
+        lineTo(next() + ox, next() + oy);
+        lastControl = null;
+        break;
+      case "H":
+        lineTo(next() + ox, cur.y);
+        lastControl = null;
+        break;
+      case "V":
+        lineTo(cur.x, next() + oy);
+        lastControl = null;
+        break;
+      case "C": {
+        const c1x = next() + ox;
+        const c1y = next() + oy;
+        const c2x = next() + ox;
+        const c2y = next() + oy;
+        curveTo(c1x, c1y, c2x, c2y, next() + ox, next() + oy);
+        lastControl = [c2x, c2y];
+        break;
+      }
+      case "S": {
+        // Smooth cubic: first control point mirrors the previous one.
+        const [rx, ry] = lastControl
+          ? [2 * cur.x - lastControl[0], 2 * cur.y - lastControl[1]]
+          : [cur.x, cur.y];
+        const c2x = next() + ox;
+        const c2y = next() + oy;
+        curveTo(rx, ry, c2x, c2y, next() + ox, next() + oy);
+        lastControl = [c2x, c2y];
+        break;
+      }
+      case "Q": {
+        // PDF has no quadratic operator — raise it to a cubic.
+        const qx = next() + ox;
+        const qy = next() + oy;
+        const x = next() + ox;
+        const y = next() + oy;
+        curveTo(
+          cur.x + (2 / 3) * (qx - cur.x),
+          cur.y + (2 / 3) * (qy - cur.y),
+          x + (2 / 3) * (qx - x),
+          y + (2 / 3) * (qy - y),
+          x,
+          y,
+        );
+        lastControl = [qx, qy];
+        break;
+      }
+      case "T": {
+        // Annotated because `lastControl` is re-assigned from these below —
+        // inferring both at once would be circular.
+        const qx: number = lastControl ? 2 * cur.x - lastControl[0] : cur.x;
+        const qy: number = lastControl ? 2 * cur.y - lastControl[1] : cur.y;
+        const x = next() + ox;
+        const y = next() + oy;
+        const sx = cur.x;
+        const sy = cur.y;
+        curveTo(
+          sx + (2 / 3) * (qx - sx),
+          sy + (2 / 3) * (qy - sy),
+          x + (2 / 3) * (qx - x),
+          y + (2 / 3) * (qy - y),
+          x,
+          y,
+        );
+        lastControl = [qx, qy];
+        break;
+      }
+      case "A": {
+        const rx = next();
+        const ry = next();
+        const rot = next();
+        const largeArc = next() !== 0;
+        const sweep = next() !== 0;
+        const x = next() + ox;
+        const y = next() + oy;
+        for (const c of arcToCurves(cur.x, cur.y, rx, ry, rot, largeArc, sweep, x, y)) {
+          curveTo(c[0], c[1], c[2], c[3], c[4], c[5]);
+        }
+        lastControl = null;
+        break;
+      }
+      default:
+        i++; // unknown command: skip a token rather than spin
+        break;
+    }
+  }
+  return ops;
+}

package/lib/detail-page-canvas/export/pdf/inline-svg.ts

@@ -0,0 +1,399 @@
+import type { ExportElement } from "../document-model";
+import {
+  ellipsePath,
+  parsePoints,
+  polygonPath,
+  rectPath,
+  svgPathToPdf,
+} from "./geometry";
+import {
+  parsePaint,
+  rgbOps,
+  type ResourcePool,
+  type RgbColor,
+  type ShadingStop,
+} from "./resources";
+import { showTextOps } from "./text-ops";
+import { fmt } from "./writer";
+
+/**
+ * Inline SVG (``svg``-type elements: decomposer icons, speech bubbles, charts,
+ * badges) → PDF vector operators.
+ *
+ * These carry a real share of every detail page, so rasterizing them would
+ * hand Illustrator a flat picture instead of editable artwork. The vocabulary
+ * the decomposer emits is small and closed — path, circle, rect, line,
+ * polyline, polygon, ellipse, g, text, and linear/radial gradients — which is
+ * exactly what this covers. Anything else (patterns, <use>) is skipped rather
+ * than drawn wrong.
+ */
+
+export type InlineSvgEnv = {
+  pool: ResourcePool;
+  /** Same measurement hook the text exporters use, for ``<text>`` inside icons. */
+  measure: (el: ExportElement, text: string) => number;
+};
+
+type Style = Record<string, string>;
+
+const INHERITED = [
+  "fill",
+  "stroke",
+  "stroke-width",
+  "stroke-linecap",
+  "stroke-linejoin",
+  "stroke-dasharray",
+  "fill-rule",
+  "fill-opacity",
+  "stroke-opacity",
+  "opacity",
+  "font-family",
+  "font-size",
+  "font-weight",
+  "font-style",
+  "letter-spacing",
+  "text-anchor",
+];
+
+function readStyle(el: Element, parent: Style): Style {
+  const style: Style = { ...parent };
+  for (const key of INHERITED) {
+    const value = el.getAttribute(key);
+    if (value) style[key] = value;
+  }
+  // A `style` attribute wins over presentation attributes.
+  for (const rule of (el.getAttribute("style") ?? "").split(";")) {
+    const [key, value] = rule.split(":");
+    if (key && value) style[key.trim()] = value.trim();
+  }
+  return style;
+}
+
+const num = (value: string | null, fallback = 0): number => {
+  const n = parseFloat(value ?? "");
+  return Number.isFinite(n) ? n : fallback;
+};
+
+const rgb = (value: string): RgbColor | null => parsePaint(value)?.color ?? null;
+
+/** Bounding box of emitted path ops. Curve control points inflate it slightly —
+ * good enough for mapping an objectBoundingBox gradient, its only use. */
+function opsBounds(ops: string[]): { x: number; y: number; w: number; h: number } {
+  let minX = Infinity;
+  let minY = Infinity;
+  let maxX = -Infinity;
+  let maxY = -Infinity;
+  for (const op of ops) {
+    const numbers = (op.match(/-?\d*\.?\d+/g) ?? []).map(Number);
+    // `re` carries (x, y, w, h); every other op carries coordinate pairs.
+    if (op.endsWith("re") && numbers.length === 4) {
+      minX = Math.min(minX, numbers[0]);
+      minY = Math.min(minY, numbers[1]);
+      maxX = Math.max(maxX, numbers[0] + numbers[2]);
+      maxY = Math.max(maxY, numbers[1] + numbers[3]);
+      continue;
+    }
+    for (let i = 0; i + 1 < numbers.length; i += 2) {
+      minX = Math.min(minX, numbers[i]);
+      maxX = Math.max(maxX, numbers[i]);
+      minY = Math.min(minY, numbers[i + 1]);
+      maxY = Math.max(maxY, numbers[i + 1]);
+    }
+  }
+  if (!Number.isFinite(minX)) return { x: 0, y: 0, w: 0, h: 0 };
+  return { x: minX, y: minY, w: maxX - minX, h: maxY - minY };
+}
+
+function gradientStops(node: Element): ShadingStop[] {
+  const stops: ShadingStop[] = [];
+  for (const stop of Array.from(node.querySelectorAll("stop"))) {
+    const color = rgb(stop.getAttribute("stop-color") ?? "#000");
+    if (!color) continue;
+    const offsetAttr = stop.getAttribute("offset") ?? "0";
+    const offset = offsetAttr.endsWith("%")
+      ? parseFloat(offsetAttr) / 100
+      : parseFloat(offsetAttr);
+    stops.push({ offset: Number.isFinite(offset) ? offset : 0, color });
+  }
+  return stops;
+}
+
+/**
+ * Resolve a ``url(#id)`` paint to a shading resource, mapping an
+ * objectBoundingBox gradient onto the shape's own box.
+ */
+function shadingFor(
+  paint: string,
+  root: Element,
+  bounds: { x: number; y: number; w: number; h: number },
+  env: InlineSvgEnv,
+): string | null {
+  const id = paint.match(/^url\(#([^)]+)\)$/)?.[1];
+  if (!id) return null;
+  const node = root.querySelector(`#${CSS.escape(id)}`);
+  if (!node) return null;
+  const stops = gradientStops(node);
+  if (!stops.length) return null;
+  const userSpace = node.getAttribute("gradientUnits") === "userSpaceOnUse";
+  const mapX = (v: number) => (userSpace ? v : bounds.x + v * bounds.w);
+  const mapY = (v: number) => (userSpace ? v : bounds.y + v * bounds.h);
+
+  if (node.tagName.toLowerCase() === "radialgradient") {
+    const cx = mapX(num(node.getAttribute("cx"), userSpace ? 0 : 0.5));
+    const cy = mapY(num(node.getAttribute("cy"), userSpace ? 0 : 0.5));
+    const r = num(node.getAttribute("r"), userSpace ? 0 : 0.5);
+    const radius = userSpace ? r : r * Math.max(bounds.w, bounds.h);
+    return env.pool.shading({ kind: "radial", cx, cy, r: radius, stops });
+  }
+  return env.pool.shading({
+    kind: "axial",
+    x0: mapX(num(node.getAttribute("x1"), 0)),
+    y0: mapY(num(node.getAttribute("y1"), 0)),
+    x1: mapX(num(node.getAttribute("x2"), userSpace ? 0 : 1)),
+    y1: mapY(num(node.getAttribute("y2"), 0)),
+    stops,
+  });
+}
+
+/** Paint a built path with the resolved fill/stroke of the current style. */
+function paintOps(
+  path: string[],
+  style: Style,
+  root: Element,
+  env: InlineSvgEnv,
+): string[] {
+  if (!path.length) return [];
+  const fill = style.fill ?? "#000"; // SVG's initial fill really is black
+  const stroke = style.stroke ?? "none";
+  const strokeWidth = num(style["stroke-width"], 1);
+  const strokePaint = stroke !== "none" && strokeWidth > 0 ? parsePaint(stroke) : null;
+  const hasStroke = strokePaint !== null;
+  const fillPaint = fill !== "none" && !fill.startsWith("url(") ? parsePaint(fill) : null;
+  const hasFill = fill !== "none" && (fillPaint !== null || fill.startsWith("url("));
+  if (!hasFill && !hasStroke) return [];
+
+  const evenOdd = style["fill-rule"] === "evenodd";
+  const ops: string[] = ["q"];
+
+  const opacity = num(style.opacity, 1);
+  const fillAlpha = opacity * num(style["fill-opacity"], 1) * (fillPaint?.alpha ?? 1);
+  const strokeAlpha = opacity * num(style["stroke-opacity"], 1) * (strokePaint?.alpha ?? 1);
+  if (fillAlpha < 1 || strokeAlpha < 1) {
+    ops.push(`/${env.pool.alpha(fillAlpha, strokeAlpha)} gs`);
+  }
+
+  if (strokePaint) {
+    ops.push(`${rgbOps(strokePaint.color)} RG`, `${fmt(strokeWidth)} w`);
+    const cap = { butt: 0, round: 1, square: 2 }[style["stroke-linecap"] ?? "butt"] ?? 0;
+    const join = { miter: 0, round: 1, bevel: 2 }[style["stroke-linejoin"] ?? "miter"] ?? 0;
+    ops.push(`${cap} J`, `${join} j`);
+    const dash = style["stroke-dasharray"];
+    if (dash && dash !== "none") {
+      ops.push(`[${parsePoints(dash).map(fmt).join(" ")}] 0 d`);
+    }
+  }
+
+  // A gradient fill has no colour operator: clip to the path and run the shading.
+  const gradient = fill.startsWith("url(")
+    ? shadingFor(fill, root, opsBounds(path), env)
+    : null;
+  if (gradient) {
+    ops.push("q", ...path, evenOdd ? "W* n" : "W n", `/${gradient} sh`, "Q");
+    if (strokePaint) ops.push(...path, "S");
+    ops.push("Q");
+    return ops;
+  }
+
+  if (fillPaint) ops.push(`${rgbOps(fillPaint.color)} rg`);
+  ops.push(...path);
+  ops.push(
+    fillPaint && strokePaint
+      ? evenOdd
+        ? "B*"
+        : "B"
+      : fillPaint
+        ? evenOdd
+          ? "f*"
+          : "f"
+        : "S",
+    "Q",
+  );
+  return ops;
+}
+
+function textOps(node: Element, style: Style, env: InlineSvgEnv): string[] {
+  const text = (node.textContent ?? "").trim();
+  if (!text) return [];
+  const fontSize = num(style["font-size"], 16);
+  const weight = /bold/i.test(style["font-weight"] ?? "")
+    ? 700
+    : num(style["font-weight"], 400);
+  const letterSpacing = num(style["letter-spacing"], 0);
+  const synthetic: ExportElement = {
+    fontFamily: (style["font-family"] ?? "Pretendard").split(",")[0].replace(/['"]/g, "").trim(),
+    fontSize,
+    fontWeight: weight,
+    fontStyle: style["font-style"],
+    // The measurement hook takes letterSpacing in em, like Canvas does.
+    letterSpacing: fontSize ? letterSpacing / fontSize : 0,
+  };
+  const width = env.measure(synthetic, text);
+  const anchor = style["text-anchor"];
+  let x = num(node.getAttribute("x"), 0);
+  if (anchor === "middle") x -= width / 2;
+  else if (anchor === "end") x -= width;
+
+  const color = rgb(style.fill ?? "#000") ?? [0, 0, 0];
+  return [
+    "q",
+    `${rgbOps(color)} rg`,
+    ...showTextOps({
+      fontRes: env.pool.font({
+        family: synthetic.fontFamily ?? "Pretendard",
+        weight,
+        italic: /italic/i.test(style["font-style"] ?? ""),
+      }),
+      fontSize,
+      x,
+      baseline: num(node.getAttribute("y"), 0),
+      text,
+      measure: (t) => env.measure(synthetic, t),
+    }),
+    "Q",
+  ];
+}
+
+function nodeOps(node: Element, parent: Style, root: Element, env: InlineSvgEnv): string[] {
+  const style = readStyle(node, parent);
+  const tag = node.tagName.toLowerCase();
+
+  switch (tag) {
+    case "g": {
+      const ops: string[] = ["q"];
+      const opacity = num(node.getAttribute("opacity"), 1);
+      if (opacity < 1) ops.push(`/${env.pool.alpha(opacity)} gs`);
+      for (const child of Array.from(node.children)) {
+        ops.push(...nodeOps(child, style, root, env));
+      }
+      ops.push("Q");
+      return ops;
+    }
+    case "path":
+      return paintOps(svgPathToPdf(node.getAttribute("d") ?? ""), style, root, env);
+    case "rect":
+      return paintOps(
+        rectPath(
+          num(node.getAttribute("x")),
+          num(node.getAttribute("y")),
+          num(node.getAttribute("width")),
+          num(node.getAttribute("height")),
+          num(node.getAttribute("rx")) || num(node.getAttribute("ry")),
+        ),
+        style,
+        root,
+        env,
+      );
+    case "circle": {
+      const r = num(node.getAttribute("r"));
+      return paintOps(
+        ellipsePath(num(node.getAttribute("cx")), num(node.getAttribute("cy")), r, r),
+        style,
+        root,
+        env,
+      );
+    }
+    case "ellipse":
+      return paintOps(
+        ellipsePath(
+          num(node.getAttribute("cx")),
+          num(node.getAttribute("cy")),
+          num(node.getAttribute("rx")),
+          num(node.getAttribute("ry")),
+        ),
+        style,
+        root,
+        env,
+      );
+    case "line":
+      return paintOps(
+        polygonPath(
+          [
+            num(node.getAttribute("x1")),
+            num(node.getAttribute("y1")),
+            num(node.getAttribute("x2")),
+            num(node.getAttribute("y2")),
+          ],
+          false,
+        ),
+        // A line has no interior; a stray inherited fill would paint a triangle.
+        { ...style, fill: "none" },
+        root,
+        env,
+      );
+    case "polyline":
+    case "polygon":
+      return paintOps(
+        polygonPath(parsePoints(node.getAttribute("points") ?? ""), tag === "polygon"),
+        tag === "polyline" ? { ...style, fill: style.fill ?? "none" } : style,
+        root,
+        env,
+      );
+    case "text":
+      return textOps(node, style, env);
+    case "defs":
+    case "lineargradient":
+    case "radialgradient":
+      return []; // referenced on demand, never drawn in place
+    default:
+      return [];
+  }
+}
+
+/**
+ * Place an inline SVG inside its element box: viewBox → box mapping (the
+ * ``preserveAspectRatio`` our exporters use), then the drawing operators.
+ * Returns null when the markup is not usable, so the caller can fall back to
+ * embedding the icon as a bitmap.
+ */
+export function inlineSvgOps(
+  markup: string,
+  box: { x: number; y: number; width: number; height: number },
+  fit: string,
+  env: InlineSvgEnv,
+): string[] | null {
+  if (typeof DOMParser === "undefined") return null;
+  const parsed = new DOMParser().parseFromString(markup, "image/svg+xml");
+  const root = parsed.documentElement;
+  if (!root || root.tagName.toLowerCase() !== "svg") return null;
+
+  const viewBox = parsePoints(root.getAttribute("viewBox") ?? "");
+  const [vx, vy, vw, vh] =
+    viewBox.length === 4
+      ? viewBox
+      : [0, 0, num(root.getAttribute("width")), num(root.getAttribute("height"))];
+  if (!(vw > 0) || !(vh > 0)) return null;
+
+  const sx = box.width / vw;
+  const sy = box.height / vh;
+  const scale =
+    fit === "fill" ? null : fit === "cover" ? Math.max(sx, sy) : Math.min(sx, sy);
+  const [scaleX, scaleY] = scale === null ? [sx, sy] : [scale, scale];
+  // Centered, like the SVG exporter's xMidYMid.
+  const tx = box.x + (box.width - vw * scaleX) / 2 - vx * scaleX;
+  const ty = box.y + (box.height - vh * scaleY) / 2 - vy * scaleY;
+
+  const ops: string[] = [
+    "q",
+    // `cover` can overflow the box, exactly as it does on the canvas.
+    ...(fit === "cover"
+      ? [`${fmt(box.x)} ${fmt(box.y)} ${fmt(box.width)} ${fmt(box.height)} re`, "W n"]
+      : []),
+    `${fmt(scaleX)} 0 0 ${fmt(scaleY)} ${fmt(tx)} ${fmt(ty)} cm`,
+  ];
+  const baseStyle = readStyle(root, {});
+  for (const child of Array.from(root.children)) {
+    ops.push(...nodeOps(child, baseStyle, root, env));
+  }
+  ops.push("Q");
+  return ops;
+}