svg-writer.ts

/**
 * SVG Writer.
 * Maps IR nodes to SVG elements and produces a standalone SVG document string.
 */
import type { FontAssetCollection, FontAssetMode } from "../font-assets.js";
import type { ClipQuad, PathSubpath, Point, Quad, SourceMetadata, Style, Writer } from "../types.js";
import { roundedQuadPath } from "../geometry.js";
import { normalizeWhitespaceAwareText, preservesWhitespace } from "../shared/text-whitespace.js";
import { getVisibleCssColorString, parseCssColor, type ParsedCssColor } from "./shared/css-color.js";
import { getPointBounds, getQuadBounds, parseClipPathShape, type ClipPathBounds, type ClipPathShape } from "./shared/clip-path.js";
import { buildEmbeddedFontDataUrl, buildFontFaceCss, choosePreferredWebFontSource, normalizeFontBasePath } from "./shared/font-assets.js";
import {
  expandRepeatingGradientStops,
  extractAllGradients,
  normalizeGradientStopOffsets,
  parseGradientAst,
  type GradientStopAst,
  type ParsedGradientAst,
} from "./shared/gradient-utils.js";
import { getSvgBlendModeStyle } from "./shared/filter-effects.js";
import { formatWriterNumber as n, getVisibleStroke, isAxisAlignedRect, parseMinDimensionBorderRadius as parseBorderRadius } from "./shared/writer-utils.js";

// ── Color helpers ───────────────────────────────────────────────────

/** Escape text for use inside XML/SVG elements.
 *  Encodes XML special characters and non-BMP Unicode characters as numeric
 *  character references so the output is safe for any XML parser.
 */
function escXml(s: string): string {
  let out = "";
  for (const ch of s) {
    const code = ch.codePointAt(0)!;
    switch (ch) {
      case "&": out += "&"; break;
      case "<": out += "&lt;"; break;
      case ">": out += "&gt;"; break;
      case '"': out += "&quot;"; break;
      case "'": out += "&#39;"; break;
      default:
        if (code < 0x20 && code !== 0x9 && code !== 0xA && code !== 0xD) {
          // Invalid XML control character — skip
        } else if (code > 0x7E) {
          // Non-ASCII — encode as numeric reference for encoding safety
          out += `&#x${code.toString(16).toUpperCase()};`;
        } else {
          out += ch;
        }
        break;
    }
  }
  return out;
}

function buildSourceDataAttributes(source: SourceMetadata | undefined): string[] {
  if (!source) return [];

  const attrs = [
    `data-source-xpath="${escXml(source.xpath)}"`,
    `data-source-original-type="${escXml(source.originalType)}"`,
  ];
  if (source.id) {
    attrs.push(`data-source-id="${escXml(source.id)}"`);
  }
  return attrs;
}

function injectOpeningTagAttributes(xml: string, attributes: string[]): string {
  if (attributes.length === 0) return xml;

  return xml.replace(/^<([^\s>/]+)([^>]*?)(\s*\/?)>/, (_match, tagName: string, rest: string, closing: string) => {
    const trimmedRest = rest.trimEnd();
    return `<${tagName}${trimmedRest ? ` ${trimmedRest}` : ""} ${attributes.join(" ")}${closing}>`;
  });
}

function getSvgEffectStyle(style: Style): string | undefined {
  const declarations: string[] = [];
  if (style.filter && style.filter !== "none") {
    declarations.push(`filter:${style.filter}`);
  }

  const blendMode = getSvgBlendModeStyle(style.mixBlendMode);
  if (blendMode) {
    declarations.push(`mix-blend-mode:${blendMode}`);
  }

  return declarations.length > 0 ? declarations.join(";") : undefined;
}

function pointsToPath(points: Point[], closed: boolean): string {
  return points.map((point, index) => `${index === 0 ? "M" : "L"}${n(point.x)},${n(point.y)}`).join(" ") + (closed ? " Z" : "");
}

function subpathsToPath(subpaths: PathSubpath[]): string {
  return subpaths
    .filter((subpath) => subpath.points.length > 0)
    .map((subpath) => pointsToPath(subpath.points, subpath.closed))
    .join(" ");
}

function normalizeFontFamily(fontFamily: string | undefined, fallback: string): string {
  const normalized = fontFamily?.trim();
  return normalized && normalized.length > 0 ? normalized : fallback;
}

type RenderedOutline = {
  color: string;
  width: number;
  style: string;
  offset: number;
};

type QuadTransform = {
  width: number;
  height: number;
  a: number;
  b: number;
  c: number;
  d: number;
  e: number;
  f: number;
};

function getQuadTransform(points: Quad): QuadTransform | null {
  const dx = points[1].x - points[0].x;
  const dy = points[1].y - points[0].y;
  const ldx = points[3].x - points[0].x;
  const ldy = points[3].y - points[0].y;
  const width = Math.hypot(dx, dy);
  const height = Math.hypot(ldx, ldy);
  if (width <= 0 || height <= 0) return null;

  return {
    width,
    height,
    a: dx / width,
    b: dy / width,
    c: ldx / height,
    d: ldy / height,
    e: points[0].x,
    f: points[0].y,
  };
}

function getVisibleOutline(style: Style): RenderedOutline | null {
  if (!style.outlineWidth) return null;
  const width = parseFloat(style.outlineWidth);
  if (!Number.isFinite(width) || width <= 0) return null;

  const outlineStyle = style.outlineStyle === "auto" ? "solid" : style.outlineStyle;
  if (!outlineStyle || outlineStyle === "none") return null;

  const color = getVisibleCssColorString(style.outlineColor ?? style.color ?? style.stroke ?? style.fill);
  if (!color) return null;

  const offsetValue = style.outlineOffset ? parseFloat(style.outlineOffset) : 0;
  return {
    color,
    width,
    style: outlineStyle,
    offset: Number.isFinite(offsetValue) ? offsetValue : 0,
  };
}

function getOutlineDasharray(outline: RenderedOutline): string | undefined {
  switch (outline.style) {
    case "dashed": {
      const dash = Math.max(outline.width * 3, 1);
      return `${n(dash)} ${n(dash)}`;
    }
    case "dotted": {
      const gap = Math.max(outline.width * 1.5, 1);
      return `${n(outline.width)} ${n(gap)}`;
    }
    default:
      return undefined;
  }
}

function roundedQuadToPath(points: Quad, radius: number, cornerShapes?: [number, number, number, number]): string {
  const segments = roundedQuadPath(points, radius, cornerShapes);
  return segments.map((segment) => {
    switch (segment.type) {
      case "M": return `M${n(segment.x)},${n(segment.y)}`;
      case "L": return `L${n(segment.x)},${n(segment.y)}`;
      case "Q": return `Q${n(segment.cx)},${n(segment.cy)} ${n(segment.x)},${n(segment.y)}`;
    }
  }).join(" ") + " Z";
}

function roundedRectPathData(x: number, y: number, w: number, h: number, r: number): string {
  const radius = Math.min(Math.max(r, 0), w / 2, h / 2);
  if (radius <= 0) {
    return `M${n(x)},${n(y)} H${n(x + w)} V${n(y + h)} H${n(x)} Z`;
  }

  return [
    `M${n(x + radius)},${n(y)}`,
    `H${n(x + w - radius)}`,
    `A${n(radius)},${n(radius)} 0 0 1 ${n(x + w)},${n(y + radius)}`,
    `V${n(y + h - radius)}`,
    `A${n(radius)},${n(radius)} 0 0 1 ${n(x + w - radius)},${n(y + h)}`,
    `H${n(x + radius)}`,
    `A${n(radius)},${n(radius)} 0 0 1 ${n(x)},${n(y + h - radius)}`,
    `V${n(y + radius)}`,
    `A${n(radius)},${n(radius)} 0 0 1 ${n(x + radius)},${n(y)}`,
    "Z",
  ].join(" ");
}

// ── Gradient parsing (subset of png-writer logic) ───────────────────

interface GradientStop { offset: number; color: string; }
interface LinearGradient { type: "linear"; angleDeg: number; stops: GradientStop[]; repeating: boolean; }
interface RadialGradient { type: "radial"; stops: GradientStop[]; repeating: boolean; }
interface ConicGradient { type: "conic"; fromAngleDeg: number; stops: GradientStop[]; repeating: boolean; }
type ParsedGradient = LinearGradient | RadialGradient | ConicGradient;

const CONIC_GRADIENT_SEGMENTS = 120;

function formatCssColor(color: ParsedCssColor): string {
  if (color.a >= 0.999) return `rgb(${color.r}, ${color.g}, ${color.b})`;
  return `rgba(${color.r}, ${color.g}, ${color.b}, ${Number(color.a.toFixed(3))})`;
}

function interpolateConicColor(t: number, stops: GradientStop[], repeating = false): string {
  if (stops.length === 0) return "transparent";

  const parsedStops = stops
    .map((stop) => ({ ...stop, parsed: parseCssColor(stop.color) }))
    .filter((stop): stop is GradientStop & { parsed: ParsedCssColor } => !!stop.parsed)
    .sort((left, right) => left.offset - right.offset);

  if (parsedStops.length === 0) return stops[0].color;
  const maxOffset = parsedStops[parsedStops.length - 1].offset;
  if (repeating && maxOffset > 0 && maxOffset < 0.999999) {
    t = ((t % maxOffset) + maxOffset) % maxOffset;
  }
  if (parsedStops.length === 1) return formatCssColor(parsedStops[0].parsed);
  if (t <= parsedStops[0].offset) return formatCssColor(parsedStops[0].parsed);
  if (t >= parsedStops[parsedStops.length - 1].offset) return formatCssColor(parsedStops[parsedStops.length - 1].parsed);

  for (let i = 0; i < parsedStops.length - 1; i++) {
    const start = parsedStops[i];
    const end = parsedStops[i + 1];
    if (t < start.offset || t > end.offset) continue;

    const range = end.offset - start.offset;
    const fraction = range > 0 ? (t - start.offset) / range : 0;
    return formatCssColor({
      r: Math.round(start.parsed.r + (end.parsed.r - start.parsed.r) * fraction),
      g: Math.round(start.parsed.g + (end.parsed.g - start.parsed.g) * fraction),
      b: Math.round(start.parsed.b + (end.parsed.b - start.parsed.b) * fraction),
      a: start.parsed.a + (end.parsed.a - start.parsed.a) * fraction,
    });
  }

  return formatCssColor(parsedStops[parsedStops.length - 1].parsed);
}

function resolveGradientStops(stopsAst: GradientStopAst<string>[]): GradientStop[] {
  const stops = stopsAst.map((stop) => ({
    color: stop.color,
    offset: stop.unit === "auto" ? -1 : stop.offset,
  }));

  if (stops.length === 0) return stops;
  if (stopsAst.some((stop) => stop.unit === "px")) {
    if (stops[0].offset < 0) stops[0].offset = 0;
    return stops;
  }

  return normalizeGradientStopOffsets(stops);
}

function toSvgGradient(gradient: ParsedGradientAst<string>): ParsedGradient {
  const stops = resolveGradientStops(gradient.stops);
  if (gradient.type === "linear") return { ...gradient, stops };
  if (gradient.type === "radial") return { ...gradient, stops };
  return { ...gradient, stops };
}

// ── Box Shadow parsing ──────────────────────────────────────────────

interface ParsedBoxShadow {
  inset: boolean;
  offsetX: number;
  offsetY: number;
  blur: number;
  spread: number;
  color: string;
}

function parseBoxShadow(boxShadow: string | undefined): ParsedBoxShadow[] {
  if (!boxShadow || boxShadow === "none") return [];
  const shadows: ParsedBoxShadow[] = [];
  const parts: string[] = [];
  let depth = 0, current = "";
  for (const ch of boxShadow) {
    if (ch === "(") depth++; else if (ch === ")") depth--;
    else if (ch === "," && depth === 0) { parts.push(current.trim()); current = ""; continue; }
    current += ch;
  }
  if (current.trim()) parts.push(current.trim());

  for (const part of parts) {
    const inset = /\binset\b/i.test(part);
    const cleaned = part.replace(/\binset\b/gi, "").trim();
    let color = "rgba(0,0,0,0.5)";
    let numericPart = cleaned;
    const rgbaMatch = cleaned.match(/rgba?\([^)]+\)/);
    if (rgbaMatch) { color = rgbaMatch[0]; numericPart = cleaned.replace(rgbaMatch[0], "").trim(); }
    else {
      const hexMatch = cleaned.match(/#[0-9a-fA-F]{3,8}/);
      if (hexMatch) { color = hexMatch[0]; numericPart = cleaned.replace(hexMatch[0], "").trim(); }
    }
    const nums = numericPart.match(/-?[\d.]+px/g)?.map(s => parseFloat(s)) ?? [];
    if (nums.length >= 2) {
      shadows.push({ inset, offsetX: nums[0], offsetY: nums[1], blur: nums[2] ?? 0, spread: nums[3] ?? 0, color });
    }
  }
  return shadows;
}

// ── SVG Writer ──────────────────────────────────────────────────────

/** Options for the SVG writer. */
export type SVGWriterOptions = {
  /** Viewport width in pixels. */
  width: number;
  /** Viewport height in pixels. */
  height: number;
  /** Downloaded @font-face assets used by extracted text. */
  fontAssets?: FontAssetCollection;
  /** How downloadable fonts are emitted in the SVG output. */
  fontMode?: FontAssetMode;
  /** Scale factor applied to width and height. */
  zoom?: number;
};

export class SVGWriter implements Writer<string> {
  private width: number;
  private height: number;
  private fontAssets?: FontAssetCollection;
  private fontMode: FontAssetMode;
  private fontCounter = 0;
  private elements: string[] = [];
  private defs: string[] = [];
  private defIdCounter = 0;
  private clipCache = new Map<string, string>(); // clipKey → clip-path id
  private imageCache = new Map<string, string>(); // dataUrl → symbol def id

  /**
   * Font files referenced by the SVG output.
   * Maps relative file paths to raw font bytes.
   * Only populated when `fontMode` is `{ type: "external" }`.
   */
  fontFiles = new Map<string, Uint8Array>();

  /**
   * @param optionsOrWidth Options object, or viewport width in pixels (positional form).
   * @param height Viewport height in pixels (positional form).
   * @param zoom Scale factor applied to width and height (positional form).
   */
  constructor(optionsOrWidth: SVGWriterOptions | number, height?: number, zoom?: number) {
    if (typeof optionsOrWidth === "object") {
      const z = optionsOrWidth.zoom ?? 1;
      this.width = optionsOrWidth.width * z;
      this.height = optionsOrWidth.height * z;
      this.fontAssets = optionsOrWidth.fontAssets;
      this.fontMode = optionsOrWidth.fontMode ?? { type: "none" };
    } else {
      const z = zoom ?? 1;
      this.width = optionsOrWidth * z;
      this.height = (height ?? 0) * z;
      this.fontMode = { type: "none" };
    }
  }

  async begin(): Promise<void> {
    this.elements = [];
    this.defs = [];
    this.fontCounter = 0;
    this.defIdCounter = 0;
    this.clipCache.clear();
    this.imageCache.clear();
    this.fontFiles.clear();
  }

  private getFontFilename(source: NonNullable<ReturnType<typeof choosePreferredWebFontSource>>): string {
    const idx = ++this.fontCounter;
    const fileName = `font${idx}.${source.format}`;
    const basePath = this.fontMode.type === "external" ? normalizeFontBasePath(this.fontMode.basePath) : "";
    const relativePath = basePath ? `${basePath}/${fileName}` : fileName;
    this.fontFiles.set(relativePath, source.data);
    return relativePath;
  }

  private buildFontCss(): string {
    if (!this.fontAssets || this.fontAssets.faces.length === 0 || this.fontMode.type === "none") {
      return "";
    }

    const rules: string[] = [];
    for (const face of this.fontAssets.faces) {
      const source = choosePreferredWebFontSource(face);
      if (!source) continue;

      const sourceUrl = this.fontMode.type === "inline"
        ? buildEmbeddedFontDataUrl(source)
        : this.getFontFilename(source);
      rules.push(buildFontFaceCss(face, sourceUrl, source.format));
    }

    return rules.join("\n");
  }

  private getCachedClipId(key: string, buildDef: (id: string) => string): string {
    const cached = this.clipCache.get(key);
    if (cached) return cached;

    const id = `clip${++this.defIdCounter}`;
    this.defs.push(buildDef(id));
    this.clipCache.set(key, id);
    return id;
  }

  /** Create a clipPath def for clipBounds and return its id, reusing identical clip paths. */
  private getRectClipId(style: Style): string | null {
    const clip = style.clipBounds;
    if (!clip) return null;

    const r = clip.radius > 0 ? Math.min(clip.radius, clip.w / 2, clip.h / 2) : 0;
    const key = `rect:${n(clip.x)},${n(clip.y)},${n(clip.w)},${n(clip.h)},${n(r)}`;
    return this.getCachedClipId(key, (id) => {
      if (r > 0) {
        return `<clipPath id="${id}" clipPathUnits="userSpaceOnUse"><rect x="${n(clip.x)}" y="${n(clip.y)}" width="${n(clip.w)}" height="${n(clip.h)}" rx="${n(r)}" ry="${n(r)}"/></clipPath>`;
      }
      return `<clipPath id="${id}" clipPathUnits="userSpaceOnUse"><rect x="${n(clip.x)}" y="${n(clip.y)}" width="${n(clip.w)}" height="${n(clip.h)}"/></clipPath>`;
    });
  }

  private buildClipShapeElement(shape: ClipPathShape): string {
    switch (shape.kind) {
      case "inset": {
        const radiusAttrs = shape.rx > 0 || shape.ry > 0
          ? ` rx="${n(shape.rx)}" ry="${n(shape.ry)}"`
          : "";
        return `<rect x="${n(shape.x)}" y="${n(shape.y)}" width="${n(shape.w)}" height="${n(shape.h)}"${radiusAttrs}/>`;
      }
      case "ellipse":
        if (Math.abs(shape.rx - shape.ry) < 0.0001) {
          return `<circle cx="${n(shape.cx)}" cy="${n(shape.cy)}" r="${n(shape.rx)}"/>`;
        }
        return `<ellipse cx="${n(shape.cx)}" cy="${n(shape.cy)}" rx="${n(shape.rx)}" ry="${n(shape.ry)}"/>`;
      case "polygon": {
        const d = shape.points.map((point, index) => `${index === 0 ? "M" : "L"}${n(point.x)},${n(point.y)}`).join(" ") + " Z";
        const clipRule = shape.fillRule === "evenodd" ? ' clip-rule="evenodd"' : "";
        return `<path d="${d}"${clipRule}/>`;
      }
      case "path": {
        const clipRule = shape.fillRule === "evenodd" ? ' clip-rule="evenodd"' : "";
        return `<path d="${subpathsToPath(shape.subpaths)}"${clipRule}/>`;
      }
    }
  }

  private getShapeClipId(style: Style, bounds?: ClipPathBounds): string | null {
    if (!bounds) return null;

    const shape = parseClipPathShape(style.clipPath, bounds);
    if (!shape) return null;

    const key = `shape:${style.clipPath}|${n(bounds.x)},${n(bounds.y)},${n(bounds.w)},${n(bounds.h)}`;
    return this.getCachedClipId(key, (id) => `<clipPath id="${id}" clipPathUnits="userSpaceOnUse">${this.buildClipShapeElement(shape)}</clipPath>`);
  }

  private buildClipQuadElement(clipQuad: ClipQuad): string {
    if (clipQuad.radius > 0) {
      return `<path d="${roundedQuadToPath(clipQuad.points, clipQuad.radius)}"/>`;
    }

    const path = clipQuad.points.map((point, index) => `${index === 0 ? "M" : "L"}${n(point.x)},${n(point.y)}`).join(" ") + " Z";
    return `<path d="${path}"/>`;
  }

  private getQuadClipIds(style: Style): string[] {
    const clipQuads = style.clipQuads;
    if (!clipQuads?.length) return [];

    return clipQuads.map((clipQuad) => {
      const key = `quad:${n(clipQuad.radius)}:${clipQuad.points.map((point) => `${n(point.x)},${n(point.y)}`).join("|")}`;
      return this.getCachedClipId(
        key,
        (id) => `<clipPath id="${id}" clipPathUnits="userSpaceOnUse">${this.buildClipQuadElement(clipQuad)}</clipPath>`,
      );
    });
  }

  private getBorderRadiusClipId(points: Quad, style: Style): string | null {
    const topEdge = Math.hypot(points[1].x - points[0].x, points[1].y - points[0].y);
    const leftEdge = Math.hypot(points[3].x - points[0].x, points[3].y - points[0].y);
    const radius = parseBorderRadius(style.borderRadius, topEdge, leftEdge);
    if (radius <= 0) return null;

    const clipQuad: ClipQuad = {
      points,
      radius: Math.min(radius, topEdge / 2, leftEdge / 2),
    };
    const key = `radius:${n(clipQuad.radius)}:${clipQuad.points.map((point) => `${n(point.x)},${n(point.y)}`).join("|")}`;
    return this.getCachedClipId(
      key,
      (id) => `<clipPath id="${id}" clipPathUnits="userSpaceOnUse">${this.buildClipQuadElement(clipQuad)}</clipPath>`,
    );
  }

  private buildOutlineElement(points: Quad, style: Style, outline: RenderedOutline, opacity: number | undefined): string {
    const dasharray = getOutlineDasharray(outline);
    const attrs = [
      ` fill="none"`,
      ` stroke="${escXml(outline.color)}"`,
      ` stroke-width="${n(outline.width)}"`,
    ];
    if (dasharray) attrs.push(` stroke-dasharray="${dasharray}"`);
    if (outline.style === "dotted") attrs.push(` stroke-linecap="round"`);
    if (opacity !== undefined) attrs.push(` opacity="${n(opacity)}"`);

    if (isAxisAlignedRect(points) && !style.cornerShapes) {
      const x = Math.min(points[0].x, points[1].x, points[2].x, points[3].x);
      const y = Math.min(points[0].y, points[1].y, points[2].y, points[3].y);
      const width = Math.max(points[0].x, points[1].x, points[2].x, points[3].x) - x;
      const height = Math.max(points[0].y, points[1].y, points[2].y, points[3].y) - y;
      const padding = outline.offset + outline.width / 2;
      const radius = parseBorderRadius(style.borderRadius, width, height);
      const outlineRadius = Math.min(Math.max(radius + padding, 0), (width + padding * 2) / 2, (height + padding * 2) / 2);
      return `<rect x="${n(x - padding)}" y="${n(y - padding)}" width="${n(width + padding * 2)}" height="${n(height + padding * 2)}" rx="${n(outlineRadius)}" ry="${n(outlineRadius)}"${attrs.join("")}/>`;
    }

    const topEdge = Math.hypot(points[1].x - points[0].x, points[1].y - points[0].y);
    const leftEdge = Math.hypot(points[3].x - points[0].x, points[3].y - points[0].y);
    const radius = parseBorderRadius(style.borderRadius, topEdge, leftEdge);
    const path = radius > 0 && (!isAxisAlignedRect(points) || style.cornerShapes)
      ? roundedQuadToPath(points, radius, style.cornerShapes)
      : `${points.map((point, index) => `${index === 0 ? "M" : "L"}${n(point.x)},${n(point.y)}`).join(" ")} Z`;
    return `<path d="${path}"${attrs.join("")}/>`;
  }

  /** Push an element, wrapping it in clip groups when clipBounds or clip-path are set. */
  private pushElement(element: string, style: Style, bounds?: ClipPathBounds, source?: SourceMetadata): void {
    let wrapped = injectOpeningTagAttributes(element, buildSourceDataAttributes(source));

    const effectStyle = getSvgEffectStyle(style);
    if (effectStyle) {
      wrapped = `<g style="${escXml(effectStyle)}">${wrapped}</g>`;
    }

    for (const quadClipId of this.getQuadClipIds(style)) {
      wrapped = `<g clip-path="url(#${quadClipId})">${wrapped}</g>`;
    }

    const shapeClipId = this.getShapeClipId(style, bounds);
    if (shapeClipId) {
      wrapped = `<g clip-path="url(#${shapeClipId})">${wrapped}</g>`;
    }

    const rectClipId = this.getRectClipId(style);
    if (rectClipId) {
      wrapped = `<g clip-path="url(#${rectClipId})">${wrapped}</g>`;
    }

    this.elements.push(wrapped);
  }

  /** Check if borders have different colors/widths/styles per side (skip if borderRadius). */
  private hasMixedBorders(style: Style): boolean {
    if (style.borderRadius && style.borderRadius !== "0px" && style.borderRadius !== "0%") return false;
    const sides = [
      { c: style.borderTopColor, w: style.borderTopWidth, s: style.borderTopStyle },
      { c: style.borderRightColor, w: style.borderRightWidth, s: style.borderRightStyle },
      { c: style.borderBottomColor, w: style.borderBottomWidth, s: style.borderBottomStyle },
      { c: style.borderLeftColor, w: style.borderLeftWidth, s: style.borderLeftStyle },
    ];
    if (!sides[0].s) return false;
    if (sides.some(s => s.s === "double")) return true;
    const ref = sides[0];
    return sides.some(s => s.c !== ref.c || s.w !== ref.w || s.s !== ref.s);
  }

  /** Draw each border side independently as an SVG line. */
  private drawPerSideBorders(points: Quad, style: Style): void {
    const sides: Array<{
      from: Point; to: Point;
      color?: string; width?: string; borderStyle?: string;
    }> = [
      { from: points[0], to: points[1], color: style.borderTopColor, width: style.borderTopWidth, borderStyle: style.borderTopStyle },
      { from: points[1], to: points[2], color: style.borderRightColor, width: style.borderRightWidth, borderStyle: style.borderRightStyle },
      { from: points[2], to: points[3], color: style.borderBottomColor, width: style.borderBottomWidth, borderStyle: style.borderBottomStyle },
      { from: points[3], to: points[0], color: style.borderLeftColor, width: style.borderLeftWidth, borderStyle: style.borderLeftStyle },
    ];

    for (const side of sides) {
      const color = getVisibleCssColorString(side.color);
      const w = side.width ? parseFloat(side.width) : 0;
      if (!color || w <= 0 || !side.borderStyle || side.borderStyle === "none" || side.borderStyle === "hidden") continue;

      const x1 = n(side.from.x), y1 = n(side.from.y);
      const x2 = n(side.to.x), y2 = n(side.to.y);

      if (side.borderStyle === "double" && w >= 3) {
        const lineW = Math.max(1, w / 3);
        const dx = side.to.x - side.from.x;
        const dy = side.to.y - side.from.y;
        const len = Math.sqrt(dx * dx + dy * dy);
        if (len <= 0) continue;
        const nx = -dy / len;
        const ny = dx / len;
        const off = w / 3;

        // Outer line
        this.elements.push(`<line x1="${n(side.from.x - nx * off)}" y1="${n(side.from.y - ny * off)}" x2="${n(side.to.x - nx * off)}" y2="${n(side.to.y - ny * off)}" stroke="${escXml(color)}" stroke-width="${n(lineW)}"/>`);
        // Inner line
        this.elements.push(`<line x1="${n(side.from.x + nx * off)}" y1="${n(side.from.y + ny * off)}" x2="${n(side.to.x + nx * off)}" y2="${n(side.to.y + ny * off)}" stroke="${escXml(color)}" stroke-width="${n(lineW)}"/>`);
      } else {
        const attrs: string[] = [
          `x1="${x1}"`, `y1="${y1}"`, `x2="${x2}"`, `y2="${y2}"`,
          `stroke="${escXml(color)}"`, `stroke-width="${n(w)}"`,
        ];
        if (side.borderStyle === "dashed") {
          attrs.push(`stroke-dasharray="${n(w * 3)} ${n(w * 3)}"`);
        } else if (side.borderStyle === "dotted") {
          attrs.push(`stroke-dasharray="${n(w)} ${n(w)}"`, `stroke-linecap="round"`);
        }
        this.elements.push(`<line ${attrs.join(" ")}/>`);
      }
    }
  }

  async drawPolygon(points: Quad, style: Style, source?: SourceMetadata): Promise<void> {
    const fill = getVisibleCssColorString(style.fill);
    const stroke = getVisibleStroke(style, getVisibleCssColorString);
    const outline = getVisibleOutline(style);
    const mixedBorders = this.hasMixedBorders(style);
    if (!fill && !stroke && !outline && !style.boxShadow && !mixedBorders) return;

    const w = Math.abs(points[1].x - points[0].x);
    const h = Math.abs(points[3].y - points[0].y);
    const radius = parseBorderRadius(style.borderRadius, w, h);

    // Outer box shadows (drop shadows via SVG filter)
    const shadows = parseBoxShadow(style.boxShadow);
    const outerShadows = shadows.filter(s => !s.inset);
    let filterId: string | undefined;
    if (outerShadows.length > 0) {
      filterId = this.addDropShadowFilter(outerShadows);
    }

    const opacity = (style.opacity !== undefined && style.opacity < 1) ? style.opacity : undefined;

    if (isAxisAlignedRect(points) && !style.cornerShapes) {
      const x = Math.min(points[0].x, points[1].x, points[2].x, points[3].x);
      const y = Math.min(points[0].y, points[1].y, points[2].y, points[3].y);
      const r = radius > 0 ? Math.min(radius, w / 2, h / 2) : 0;

      const gradientIds = this.addGradientDefs(style.backgroundImage, x, y, w, h);
      const strokeGradientId = this.addGradientDef(style.strokeImage, x, y, w, h);
      const baseElement = this.buildLayeredShape(
        (attrs) => `<rect x="${n(x)}" y="${n(y)}" width="${n(w)}" height="${n(h)}" rx="${n(r)}" ry="${n(r)}"${attrs}/>` ,
        fill,
        mixedBorders ? null : stroke,
        style,
        gradientIds,
        strokeGradientId,
        undefined,
        undefined,
      );
      const layers = [baseElement];
      if (outline) {
        layers.push(this.buildOutlineElement(points, style, outline, undefined));
      }
      const groupAttrs: string[] = [];
      if (filterId) groupAttrs.push(`filter="url(#${filterId})"`);
      if (opacity !== undefined) groupAttrs.push(`opacity="${n(opacity)}"`);
      const element = layers.length === 1 && groupAttrs.length === 0
        ? layers[0]
        : `<g${groupAttrs.length > 0 ? ` ${groupAttrs.join(" ")}` : ""}>${layers.join("")}</g>`;
      this.pushElement(element, style, getQuadBounds(points), source);
      if (mixedBorders) this.drawPerSideBorders(points, style);

      // Inset shadows as clipped overlays
      this.addInsetShadows(shadows.filter(s => s.inset), x, y, w, h, r);
      return;
    }

    const d = points.map((p, i) => `${i === 0 ? "M" : "L"}${n(p.x)},${n(p.y)}`).join(" ") + " Z";
    const x = Math.min(...points.map(p => p.x));
    const y = Math.min(...points.map(p => p.y));

    // For non-axis-aligned quads with border-radius, use rounded path
    const edgeW = Math.sqrt((points[1].x - points[0].x) ** 2 + (points[1].y - points[0].y) ** 2);
    const edgeH = Math.sqrt((points[3].x - points[0].x) ** 2 + (points[3].y - points[0].y) ** 2);
    const nonAlignedRadius = parseBorderRadius(style.borderRadius, edgeW, edgeH);
    let pathD: string;
    if (nonAlignedRadius > 0 && (!isAxisAlignedRect(points) || style.cornerShapes)) {
      const segs = roundedQuadPath(points, nonAlignedRadius, style.cornerShapes);
      pathD = roundedQuadToPath(points, nonAlignedRadius, style.cornerShapes);
    } else {
      pathD = d;
    }

    const gradientIds = this.addGradientDefs(style.backgroundImage, x, y, w || 1, h || 1);
    const strokeGradientId = this.addGradientDef(style.strokeImage, x, y, w || 1, h || 1);
    const baseElement = this.buildLayeredShape(
      (attrs) => `<path d="${pathD}"${attrs}/>` ,
      fill,
      mixedBorders ? null : stroke,
      style,
      gradientIds,
      strokeGradientId,
      undefined,
      undefined,
    );
    const layers = [baseElement];
    if (outline) {
      layers.push(this.buildOutlineElement(points, style, outline, undefined));
    }
    const groupAttrs: string[] = [];
    if (filterId) groupAttrs.push(`filter="url(#${filterId})"`);
    if (opacity !== undefined) groupAttrs.push(`opacity="${n(opacity)}"`);
    const element = layers.length === 1 && groupAttrs.length === 0
      ? layers[0]
      : `<g${groupAttrs.length > 0 ? ` ${groupAttrs.join(" ")}` : ""}>${layers.join("")}</g>`;
    this.pushElement(element, style, getQuadBounds(points), source);
    if (mixedBorders) this.drawPerSideBorders(points, style);

    if (isAxisAlignedRect(points)) {
      this.addInsetShadows(shadows.filter(s => s.inset), x, y, w, h, 0);
    }
  }

  async drawPolyline(points: Point[], closed: boolean, style: Style, source?: SourceMetadata): Promise<void> {
    if (points.length < 2) return;
    const fill = getVisibleCssColorString(style.fill);
    const stroke = getVisibleStroke(style, getVisibleCssColorString);
    if (!fill && !stroke) return;

    const opacity = (style.opacity !== undefined && style.opacity < 1) ? style.opacity : undefined;

    // Compute bounding box for gradient
    let minX = Infinity, minY = Infinity, maxX = -Infinity, maxY = -Infinity;
    for (const p of points) {
      if (p.x < minX) minX = p.x;
      if (p.y < minY) minY = p.y;
      if (p.x > maxX) maxX = p.x;
      if (p.y > maxY) maxY = p.y;
    }
    const d = style.pathSubpaths?.length ? subpathsToPath(style.pathSubpaths) : pointsToPath(points, closed);
    const gradientIds = this.addGradientDefs(style.backgroundImage, minX, minY, maxX - minX || 1, maxY - minY || 1);
    const strokeGradientId = this.addGradientDef(style.strokeImage, minX, minY, maxX - minX || 1, maxY - minY || 1);
    const canFillPath = closed || !!style.pathSubpaths?.length;
    const element = this.buildLayeredShape(
      (attrs) => `<path d="${d}"${style.fillRule === "evenodd" ? ' fill-rule="evenodd"' : ""}${attrs}/>` ,
      canFillPath ? fill : null,
      stroke,
      style,
      gradientIds,
      strokeGradientId,
      undefined,
      opacity,
    );
    this.pushElement(element, style, getPointBounds(points), source);
  }

  async drawText(quad: Quad, text: string, style: Style, source?: SourceMetadata): Promise<void> {
    const preserveWhitespace = preservesWhitespace(style);
    const sanitized = normalizeWhitespaceAwareText(text, style);
    if (sanitized.length === 0) return;

    const opacity = (style.opacity !== undefined && style.opacity < 1) ? style.opacity : undefined;
    const transform = getQuadTransform(quad);
    if (!transform) return;
    const transformed = !isAxisAlignedRect(quad);
    const usesVerticalWriting = !!style.writingMode && style.writingMode !== "horizontal-tb";

    // Compute font metrics
    const quadHeight = Math.sqrt((quad[3].x - quad[0].x) ** 2 + (quad[3].y - quad[0].y) ** 2);
    const styleFontSize = style.fontSize ? parseFloat(style.fontSize) : 12;
    const fontSize = quadHeight > 0 ? Math.min(styleFontSize, quadHeight) : styleFontSize;

    const fontWeight = style.fontWeight ?? "normal";
    const fontStyle = style.fontStyle ?? "normal";
    const fontFamily = normalizeFontFamily(style.fontFamily, "sans-serif");

    const textColor = getVisibleCssColorString(style.color) ?? getVisibleCssColorString(style.fill) ?? "#000000";

    const halfLeading = Math.max(0, (quadHeight - fontSize) / 2);
    const x = transformed ? 0 : quad[0].x;
    const y = transformed
      ? (usesVerticalWriting ? 0 : halfLeading)
      : quad[0].y + (quadHeight > 0 ? (quad[3].y - quad[0].y) * (halfLeading / quadHeight) : 0);

    const attrs: string[] = [];
    attrs.push(`x="${n(x)}" y="${n(y)}"`);
    attrs.push(`fill="${escXml(textColor)}"`);
    attrs.push(`dominant-baseline="text-before-edge"`);

    const fontParts: string[] = [];
    if (fontStyle !== "normal") fontParts.push(`font-style="${fontStyle}"`);
    if (fontWeight !== "normal" && fontWeight !== "400") fontParts.push(`font-weight="${fontWeight}"`);
    fontParts.push(`font-size="${n(fontSize)}px"`);
    fontParts.push(`font-family="${escXml(fontFamily)}"`);
    attrs.push(...fontParts);

    if (style.letterSpacing && style.letterSpacing !== "normal") {
      attrs.push(`letter-spacing="${escXml(style.letterSpacing)}"`);
    }
    if (style.wordSpacing && style.wordSpacing !== "normal" && style.wordSpacing !== "0px") {
      attrs.push(`word-spacing="${escXml(style.wordSpacing)}"`);
    }

    if (transformed) {
      attrs.push(`transform="matrix(${n(transform.a)},${n(transform.b)},${n(transform.c)},${n(transform.d)},${n(transform.e)},${n(transform.f)})"`);
    }
    if (opacity !== undefined) {
      attrs.push(`opacity="${n(opacity)}"`);
    }
    if (preserveWhitespace) {
      attrs.push(`xml:space="preserve"`);
    }
    if (style.direction && style.direction !== "ltr") {
      attrs.push(`direction="${escXml(style.direction)}"`);
      attrs.push(`unicode-bidi="embed"`);
    }
    if (style.writingMode && style.writingMode !== "horizontal-tb") {
      attrs.push(`writing-mode="${escXml(style.writingMode)}"`);
    }

    // Text shadow
    let shadowFilterId: string | undefined;
    if (style.textShadow && style.textShadow !== "none") {
      shadowFilterId = this.addTextShadowFilter(style.textShadow);
      if (shadowFilterId) attrs.push(`filter="url(#${shadowFilterId})"`);
    }

    // Text decoration
    let decoration: string | undefined;
    if (style.textDecoration) {
      if (style.textDecoration.includes("underline")) decoration = "underline";
      else if (style.textDecoration.includes("line-through")) decoration = "line-through";
      else if (style.textDecoration.includes("overline")) decoration = "overline";
      if (decoration) attrs.push(`text-decoration="${decoration}"`);
    }

    // Justified text: use textLength to stretch text to match the original quad width
    if (style.textAlign === "justify") {
      const quadWidth = transform.width;
      if (quadWidth > 0) {
        attrs.push(`textLength="${n(quadWidth)}" lengthAdjust="spacing"`);
      }
    }

    this.pushElement(`<text ${attrs.join(" ")}>${escXml(sanitized)}</text>`, style, getQuadBounds(quad), source);
  }

  async drawImage(quad: Quad, dataUrl: string, width: number, height: number, style: Style, _rgbData?: number[], source?: SourceMetadata): Promise<void> {
    const dx = quad[1].x - quad[0].x;
    const dy = quad[1].y - quad[0].y;
    const topEdge = Math.sqrt(dx * dx + dy * dy);
    const ldx = quad[3].x - quad[0].x;
    const ldy = quad[3].y - quad[0].y;
    const leftEdge = Math.sqrt(ldx * ldx + ldy * ldy);
    if (topEdge <= 0 || leftEdge <= 0) return;

    const angle = Math.atan2(dy, dx);
    const angleDeg = angle * (180 / Math.PI);
    const opacity = (style.opacity !== undefined && style.opacity < 1) ? style.opacity : undefined;

    // Check if this image data has been seen before (dedup via <symbol> + <use>)
    let symbolId = this.imageCache.get(dataUrl);
    if (!symbolId) {
      symbolId = this.nextId("imgSym");
      this.imageCache.set(dataUrl, symbolId);
      this.defs.push(`<symbol id="${symbolId}" viewBox="0 0 1 1" preserveAspectRatio="none"><image href="${escXml(dataUrl)}" width="1" height="1" preserveAspectRatio="none"/></symbol>`);
    }

    const attrs: string[] = [];
    if (Math.abs(angleDeg) > 0.5) {
      attrs.push(`transform="translate(${n(quad[0].x)},${n(quad[0].y)}) rotate(${n(angleDeg)})"`);
      attrs.push(`x="0" y="0"`);
    } else {
      attrs.push(`x="${n(quad[0].x)}" y="${n(quad[0].y)}"`);
    }
    attrs.push(`width="${n(topEdge)}" height="${n(leftEdge)}"`);
    if (opacity !== undefined) attrs.push(`opacity="${n(opacity)}"`);
    const ir = style.imageRendering;
    if (ir === "pixelated" || ir === "crisp-edges" || ir === "-moz-crisp-edges") {
      attrs.push(`image-rendering="pixelated"`);
    }

    let imageElement = `<use href="#${symbolId}" ${attrs.join(" ")}/>`;
    const borderRadiusClipId = this.getBorderRadiusClipId(quad, style);
    if (borderRadiusClipId) {
      imageElement = `<g clip-path="url(#${borderRadiusClipId})">${imageElement}</g>`;
    }

    const outline = getVisibleOutline(style);
    const layers = [imageElement];
    if (outline) {
      layers.push(this.buildOutlineElement(quad, style, outline, undefined));
    }
    const element = layers.length === 1 && opacity === undefined
      ? layers[0]
      : `<g${opacity !== undefined ? ` opacity="${n(opacity)}"` : ""}>${layers.join("")}</g>`;

    this.pushElement(element, style, getQuadBounds(quad), source);
  }

  async end(): Promise<string> {
    const fontCss = this.buildFontCss();
    const styleBlock = fontCss ? `<style>${escXml(fontCss)}</style>\n` : "";
    const defsBlock = this.defs.length > 0 ? `<defs>\n${this.defs.join("\n")}\n</defs>\n` : "";
    return `<?xml version="1.0" encoding="UTF-8"?>\n<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="${n(this.width)}" height="${n(this.height)}" viewBox="0 0 ${n(this.width)} ${n(this.height)}">\n${styleBlock}${defsBlock}${this.elements.join("\n")}\n</svg>`;
  }

  // ── Private helpers ─────────────────────────────────────────────

  private nextId(prefix: string): string {
    return `${prefix}${++this.defIdCounter}`;
  }

  private buildShapeAttrs(
    fill: string | null,
    stroke: { color: string; width: number } | null,
    style: Style,
    gradId: string | undefined,
    filterId: string | undefined,
    opacity: number | undefined,
  ): string {
    const parts: string[] = [];
    if (gradId) {
      parts.push(` fill="url(#${gradId})"`);
    } else if (fill) {
      parts.push(` fill="${escXml(fill)}"`);
    } else {
      parts.push(` fill="none"`);
    }
    if (stroke) {
      parts.push(` stroke="${escXml(stroke.color)}" stroke-width="${n(stroke.width)}"`);
    }
    if (style.strokeDasharray && style.strokeDasharray !== "none") {
      parts.push(` stroke-dasharray="${escXml(style.strokeDasharray)}"`);
    }
    if (filterId) parts.push(` filter="url(#${filterId})"`);
    if (opacity !== undefined) parts.push(` opacity="${n(opacity)}"`);
    return parts.join("");
  }

  private buildPolylineAttrs(
    fill: string | null,
    stroke: { color: string; width: number } | null,
    style: Style,
    gradId: string | undefined,
    opacity: number | undefined,
    closed: boolean,
  ): string {
    const parts: string[] = [];
    if (fill && closed) {
      if (gradId) {
        parts.push(` fill="url(#${gradId})"`);
      } else {
        parts.push(` fill="${escXml(fill)}"`);
      }
    } else if (fill && !closed) {
      // SVG fills open paths from first to last point
      if (gradId) {
        parts.push(` fill="url(#${gradId})"`);
      } else {
        parts.push(` fill="${escXml(fill)}"`);
      }
    } else {
      parts.push(` fill="none"`);
    }
    if (stroke) {
      parts.push(` stroke="${escXml(stroke.color)}" stroke-width="${n(stroke.width)}"`);
    } else if (!fill) {
      // Neither fill nor stroke visible — shouldn't reach here, but safety
      parts.push(` stroke="none"`);
    }
    if (style.strokeDasharray && style.strokeDasharray !== "none") {
      parts.push(` stroke-dasharray="${escXml(style.strokeDasharray)}"`);
    }
    if (opacity !== undefined) parts.push(` opacity="${n(opacity)}"`);
    return parts.join("");
  }

  private addGradientDefs(
    backgroundImage: string | undefined,
    x: number,
    y: number,
    w: number,
    h: number,
  ): string[] {
    if (!backgroundImage || backgroundImage === "none") return [];

    const ids: string[] = [];
    for (const gradientString of extractAllGradients(backgroundImage)) {
      const id = this.addGradientDef(gradientString, x, y, w, h);
      if (id) ids.push(id);
    }
    return ids;
  }

  private buildLayeredShape(
    createShape: (attrs: string) => string,
    fill: string | null,
    stroke: { color: string; width: number } | null,
    style: Style,
    gradientIds: string[],
    strokeGradientId: string | undefined,
    filterId: string | undefined,
    opacity: number | undefined,
  ): string {
    const layers: string[] = [];

    if (fill) {
      layers.push(createShape(` fill="${escXml(fill)}"`));
    }
    for (let index = gradientIds.length - 1; index >= 0; index--) {
      layers.push(createShape(` fill="url(#${gradientIds[index]})"`));
    }
    if (stroke) {
      const strokePaint = strokeGradientId ? `url(#${strokeGradientId})` : escXml(stroke.color);
      const strokeParts = [` fill="none"`, ` stroke="${strokePaint}"`, ` stroke-width="${n(stroke.width)}"`];
      if (style.strokeDasharray && style.strokeDasharray !== "none") {
        strokeParts.push(` stroke-dasharray="${escXml(style.strokeDasharray)}"`);
      }
      layers.push(createShape(strokeParts.join("")));
    }

    if (layers.length === 0) return createShape(` fill="none"`);

    const groupParts: string[] = [];
    if (filterId) groupParts.push(`filter="url(#${filterId})"`);
    if (opacity !== undefined) groupParts.push(`opacity="${n(opacity)}"`);
    if (layers.length === 1 && groupParts.length === 0) return layers[0];
    return `<g${groupParts.length > 0 ? ` ${groupParts.join(" ")}` : ""}>${layers.join("")}</g>`;
  }

  /** Add an SVG gradient definition and return its id, or undefined if no gradient. */
  private addGradientDef(
    backgroundImage: string | undefined,
    x: number, y: number, w: number, h: number,
  ): string | undefined {
    const gradientAst = parseGradientAst(backgroundImage);
    if (!gradientAst) return undefined;
    const gradient = toSvgGradient(gradientAst);

    const cx = x + w / 2;
    const cy = y + h / 2;

    if (gradient.type === "linear") {
      const id = this.nextId("lg");
      const angleRad = ((gradient.angleDeg - 90) * Math.PI) / 180;
      const cos = Math.cos(angleRad);
      const sin = Math.sin(angleRad);
      const halfDiag = Math.abs(w * cos) / 2 + Math.abs(h * sin) / 2;
      const totalLength = halfDiag * 2;

      let stops = gradient.stops;
      const maxOffset = Math.max(...stops.map(s => s.offset));
      let gx1: number, gy1: number, gx2: number, gy2: number;
      let spreadAttr = "";

      if (gradient.repeating && maxOffset > 1 && totalLength > 0) {
        // Repeating gradient with px stops: scale to one period and repeat
        const patternLength = maxOffset;
        stops = stops.map(s => ({ color: s.color, offset: patternLength > 0 ? s.offset / patternLength : s.offset }));
        gx1 = cx - cos * halfDiag;
        gy1 = cy - sin * halfDiag;
        gx2 = gx1 + cos * patternLength;
        gy2 = gy1 + sin * patternLength;
        spreadAttr = ` spreadMethod="repeat"`;
      } else if (maxOffset > 1 && totalLength > 0) {
        // Non-repeating with px stops: normalize to total gradient length
        stops = stops.map(s => ({ color: s.color, offset: Math.min(1, s.offset / totalLength) }));
        gx1 = cx - cos * halfDiag;
        gy1 = cy - sin * halfDiag;
        gx2 = cx + cos * halfDiag;
        gy2 = cy + sin * halfDiag;
      } else {
        gx1 = cx - cos * halfDiag;
        gy1 = cy - sin * halfDiag;
        gx2 = cx + cos * halfDiag;
        gy2 = cy + sin * halfDiag;
      }

      const stopsStr = stops.map(s =>
        `<stop offset="${n(Math.max(0, Math.min(1, s.offset)) * 100)}%" stop-color="${escXml(s.color)}"/>`
      ).join("");
      this.defs.push(`<linearGradient id="${id}" x1="${n(gx1)}" y1="${n(gy1)}" x2="${n(gx2)}" y2="${n(gy2)}" gradientUnits="userSpaceOnUse"${spreadAttr}>${stopsStr}</linearGradient>`);
      return id;
    }

    if (gradient.type === "radial") {
      const id = this.nextId("rg");
      const r = Math.max(w, h) / 2;

      let stops = gradient.stops;
      const maxOffset = Math.max(...stops.map(s => s.offset));
      let spreadAttr = "";

      if (gradient.repeating && maxOffset > 1 && r > 0) {
        const patternR = maxOffset;
        stops = stops.map(s => ({ color: s.color, offset: patternR > 0 ? s.offset / patternR : s.offset }));
        spreadAttr = ` spreadMethod="repeat"`;
      } else if (maxOffset > 1 && r > 0) {
        stops = stops.map(s => ({ color: s.color, offset: Math.min(1, s.offset / r) }));
      }

      const stopsStr = stops.map(s =>
        `<stop offset="${n(Math.max(0, Math.min(1, s.offset)) * 100)}%" stop-color="${escXml(s.color)}"/>`
      ).join("");
      this.defs.push(`<radialGradient id="${id}" cx="${n(cx)}" cy="${n(cy)}" r="${n(r)}" gradientUnits="userSpaceOnUse"${spreadAttr}>${stopsStr}</radialGradient>`);
      return id;
    }

    const id = this.nextId("cg");
    const radius = Math.sqrt(w * w + h * h) / 2 + 1;
    const startAngle = ((gradient.fromAngleDeg - 90) * Math.PI) / 180;
    const angleStep = (Math.PI * 2) / CONIC_GRADIENT_SEGMENTS;
    const segments: string[] = [];
    const stops = gradient.repeating
      ? expandRepeatingGradientStops(gradient.stops, (sortedStops) => ({
        offset: 1,
        color: interpolateConicColor(1, [...sortedStops], true),
      }))
      : gradient.stops;
    const localCx = w / 2;
    const localCy = h / 2;

    for (let i = 0; i < CONIC_GRADIENT_SEGMENTS; i++) {
      const angle0 = startAngle + i * angleStep;
      const angle1 = startAngle + (i + 1) * angleStep;
      const t = (i + 0.5) / CONIC_GRADIENT_SEGMENTS;
      const color = interpolateConicColor(t, stops, gradient.repeating);
      const x0 = localCx + Math.cos(angle0) * radius;
      const y0 = localCy + Math.sin(angle0) * radius;
      const x1 = localCx + Math.cos(angle1) * radius;
      const y1 = localCy + Math.sin(angle1) * radius;
      segments.push(
        `<path d="M${n(localCx)},${n(localCy)} L${n(x0)},${n(y0)} A${n(radius)},${n(radius)} 0 0 1 ${n(x1)},${n(y1)} Z" fill="${escXml(color)}"/>`
      );
    }

    this.defs.push(
      `<pattern id="${id}" patternUnits="userSpaceOnUse" patternContentUnits="userSpaceOnUse" x="${n(x)}" y="${n(y)}" width="${n(w)}" height="${n(h)}" viewBox="0 0 ${n(w)} ${n(h)}" overflow="visible">${segments.join("")}</pattern>`
    );
    return id;
  }

  /** Add a drop shadow SVG filter and return its id. */
  private addDropShadowFilter(shadows: ParsedBoxShadow[]): string {
    const id = this.nextId("ds");
    const filterParts: string[] = [];
    // Use the first outer shadow for simplicity; combine multiple if needed
    for (let i = 0; i < shadows.length; i++) {
      const s = shadows[i];
      const resultId = `s${i}`;
      filterParts.push(
        `<feDropShadow dx="${n(s.offsetX)}" dy="${n(s.offsetY)}" stdDeviation="${n(s.blur / 2)}" flood-color="${escXml(s.color)}" result="${resultId}"/>`
      );
    }
    // Pad the filter region to avoid clipping
    this.defs.push(`<filter id="${id}" x="-50%" y="-50%" width="200%" height="200%">${filterParts.join("")}</filter>`);
    return id;
  }

  /** Add inset shadow overlays. */
  private addInsetShadows(
    shadows: ParsedBoxShadow[],
    x: number, y: number, w: number, h: number, r: number,
  ): void {
    for (const s of shadows) {
      if (!s.inset) continue;
      const clipId = this.nextId("ic");
      if (r > 0) {
        this.defs.push(`<clipPath id="${clipId}"><rect x="${n(x)}" y="${n(y)}" width="${n(w)}" height="${n(h)}" rx="${n(r)}" ry="${n(r)}"/></clipPath>`);
      } else {
        this.defs.push(`<clipPath id="${clipId}"><rect x="${n(x)}" y="${n(y)}" width="${n(w)}" height="${n(h)}"/></clipPath>`);
      }

      let filterAttr = "";
      if (s.blur > 0) {
        const filterId = this.nextId("is");
        this.defs.push(
          `<filter id="${filterId}" x="-50%" y="-50%" width="200%" height="200%">` +
          `<feGaussianBlur stdDeviation="${n(s.blur / 2)}"/>` +
          `</filter>`
        );
        filterAttr = ` filter="url(#${filterId})"`;
      }

      const pad = Math.max(s.blur, 50) + Math.abs(s.spread) + Math.max(Math.abs(s.offsetX), Math.abs(s.offsetY)) + 100;
      const innerX = x + s.spread + s.offsetX;
      const innerY = y + s.spread + s.offsetY;
      const innerW = w - s.spread * 2;
      const innerH = h - s.spread * 2;
      const innerR = Math.min(r, Math.max(innerW, 0) / 2, Math.max(innerH, 0) / 2);
      const outerPath = roundedRectPathData(x - pad, y - pad, w + pad * 2, h + pad * 2, 0);
      const innerPath = innerW > 0 && innerH > 0
        ? ` ${roundedRectPathData(innerX, innerY, innerW, innerH, innerR)}`
        : "";

      this.elements.push(
        `<path d="${outerPath}${innerPath}" fill="${escXml(s.color)}" fill-rule="evenodd" clip-path="url(#${clipId})"${filterAttr}/>`
      );
    }
  }

  /** Add a text shadow filter and return its id. */
  private addTextShadowFilter(textShadow: string): string | undefined {
    let color = "rgba(0,0,0,0.3)";
    let numericPart = textShadow;
    const rgbaMatch = textShadow.match(/rgba?\([^)]+\)/);
    if (rgbaMatch) { color = rgbaMatch[0]; numericPart = textShadow.replace(rgbaMatch[0], "").trim(); }
    else {
      const hexMatch = textShadow.match(/#[0-9a-fA-F]{3,8}/);
      if (hexMatch) { color = hexMatch[0]; numericPart = textShadow.replace(hexMatch[0], "").trim(); }
    }
    const nums = numericPart.match(/-?[\d.]+px/g)?.map(s => parseFloat(s)) ?? [];
    if (nums.length < 2) return undefined;

    const id = this.nextId("ts");
    const dx = nums[0], dy = nums[1], blur = nums[2] ?? 0;
    this.defs.push(
      `<filter id="${id}" x="-50%" y="-50%" width="200%" height="200%">` +
      `<feDropShadow dx="${n(dx)}" dy="${n(dy)}" stdDeviation="${n(blur / 2)}" flood-color="${escXml(color)}"/>` +
      `</filter>`
    );
    return id;
  }
}