pagyra-js 0.0.1

package/src/pdf/stacking/resolve-paint-order.ts

@@ -0,0 +1,157 @@
+import type { RenderBox } from "../types.js";
+import { buildStackingContexts, getStackingFlags } from "./build-stacking-contexts.js";
+import type { PaintStep, StackingContextId, StackingContextNode } from "./types.js";
+
+/**
+ * Resolve a global paint order from the RenderBox tree using stacking contexts.
+ *
+ * Scope (step 1):
+ * - Support numeric z-index on positioned elements (absolute/fixed/etc.) vs auto.
+ * - Respect DOM order for ties.
+ * - Treat each box as an atomic paint unit (background+border+content together).
+ * - Keep API simple: return ordered RenderBox list.
+ */
+export function resolvePaintOrder(root: RenderBox): RenderBox[] {
+  const { rootContextId, contexts } = buildStackingContexts(root);
+  const steps: PaintStep[] = [];
+
+  resolveContextPaintOrder(rootContextId, contexts, steps);
+  return steps.map((s) => s.box);
+}
+
+/**
+ * Compute paint order within a stacking context and append PaintSteps.
+ *
+ * Simplified rules (sufficient for our current constraints):
+ * For a given context:
+ *   1. Paint the context root box itself.
+ *   2. Paint descendants with negative z-index (positioned).
+ *   3. Paint normal-flow descendants (z-index: auto).
+ *   4. Paint positioned descendants with z-index >= 0 in ascending z-index.
+ *
+ * DOM order is preserved within each group as tie-breaker.
+ * Nested stacking contexts are treated as atomic units via recursion.
+ */
+function resolveContextPaintOrder(
+  contextId: StackingContextId,
+  contexts: Map<StackingContextId, StackingContextNode>,
+  out: PaintStep[],
+): void {
+  const context = contexts.get(contextId);
+  if (!context) return;
+
+  const rootBox = context.box;
+
+  // 1. Paint the context root box as an atomic unit.
+  out.push({ box: rootBox });
+
+  // Collect direct descendants belonging to this context (non-root boxes).
+  const descendants: RenderBox[] = [];
+  collectDescendantsInContext(rootBox, contextId, contexts, descendants);
+
+  const negativeZ: RenderBox[] = [];
+  const normalFlowAutoZ: RenderBox[] = [];
+  const positionedNonNegative: RenderBox[] = [];
+
+  for (const box of descendants) {
+    const flags = getStackingFlags(box);
+
+    if (flags.isPositioned && flags.zIndex !== "auto") {
+      const z = flags.zIndex as number;
+      if (z < 0) {
+        negativeZ.push(box);
+      } else {
+        positionedNonNegative.push(box);
+      }
+    } else {
+      // Non-positioned or auto z-index participate in the auto flow group.
+      normalFlowAutoZ.push(box);
+    }
+  }
+
+  // 2. Negative z-index positioned descendants (ascending z, DOM order for ties).
+  negativeZ.sort((a, b) => {
+    const az = (getStackingFlags(a).zIndex as number) ?? 0;
+    const bz = (getStackingFlags(b).zIndex as number) ?? 0;
+    if (az !== bz) return az - bz;
+    return 0; // DOM order already in descendants list.
+  });
+  for (const box of negativeZ) {
+    appendBoxOrContext(box, contextId, contexts, out);
+  }
+
+  // 3. Normal flow / auto z-index descendants (DOM order).
+  for (const box of normalFlowAutoZ) {
+    appendBoxOrContext(box, contextId, contexts, out);
+  }
+
+  // 4. Positioned non-negative z-index descendants (ascending z, DOM order ties).
+  positionedNonNegative.sort((a, b) => {
+    const az = (getStackingFlags(a).zIndex as number) ?? 0;
+    const bz = (getStackingFlags(b).zIndex as number) ?? 0;
+    if (az !== bz) return az - bz;
+    return 0;
+  });
+  for (const box of positionedNonNegative) {
+    appendBoxOrContext(box, contextId, contexts, out);
+  }
+}
+
+/**
+ * Append either a nested stacking context or a regular box.
+ * Nested contexts are treated as atomic units: we delegate to resolveContextPaintOrder.
+ */
+function appendBoxOrContext(
+  box: RenderBox,
+  parentContextId: StackingContextId,
+  contexts: Map<StackingContextId, StackingContextNode>,
+  out: PaintStep[],
+): void {
+  const nested = findContextByBox(box, parentContextId, contexts);
+  if (nested) {
+    resolveContextPaintOrder(nested.id, contexts, out);
+  } else {
+    out.push({ box });
+  }
+}
+
+/**
+ * Collect descendants that belong to the given context (i.e. do not start
+ * their own stacking context), in DOM order.
+ */
+function collectDescendantsInContext(
+  box: RenderBox,
+  contextId: StackingContextId,
+  contexts: Map<StackingContextId, StackingContextNode>,
+  out: RenderBox[],
+): void {
+  for (const child of box.children) {
+    const childCtx = findContextByBox(child, null, contexts);
+    if (childCtx && childCtx.id !== contextId) {
+      // Child begins its own stacking context; treat that context atomically later.
+      // Do not inline its descendants here.
+      out.push(child);
+      continue;
+    }
+
+    out.push(child);
+    collectDescendantsInContext(child, contextId, contexts, out);
+  }
+}
+
+/**
+ * Find a stacking context node anchored at the given box.
+ * If parentContextId is provided, only match contexts whose parentId equals it.
+ */
+function findContextByBox(
+  box: RenderBox,
+  parentContextId: StackingContextId | null,
+  contexts: Map<StackingContextId, StackingContextNode>,
+): StackingContextNode | undefined {
+  for (const ctx of contexts.values()) {
+    if (ctx.box === box && (parentContextId === null || ctx.parentId === parentContextId)) {
+      return ctx;
+    }
+  }
+  return undefined;
+}

package/src/pdf/stacking/types.ts

@@ -0,0 +1,40 @@
+import type { RenderBox } from "../types.js";
+
+export type StackingContextId = string;
+
+/**
+ * Represents a stacking context anchored at a particular RenderBox.
+ * This structure is intentionally minimal and purely declarative:
+ * it does not encode paint-order algorithms.
+ */
+export interface StackingContextNode {
+  /** Unique id for this stacking context. */
+  id: StackingContextId;
+  /** The box that establishes this stacking context. */
+  box: RenderBox;
+  /** Parent stacking context id (null for root). */
+  parentId: StackingContextId | null;
+  /** Child stacking contexts nested inside this one. */
+  childContextIds: StackingContextId[];
+}
+
+/**
+ * Lightweight view of stacking-relevant flags for a RenderBox.
+ * This mirrors CSS concepts but stays implementation-agnostic.
+ */
+export interface StackingFlags {
+  /** Whether the element is positioned (absolute, fixed, sticky, etc.). */
+  isPositioned: boolean;
+  /** Numeric z-index value or "auto" when not explicitly set. */
+  zIndex: number | "auto";
+  /** Whether this element establishes a new stacking context. */
+  establishesContext: boolean;
+}
+
+/**
+ * Describes a resolved paint step for a single box.
+ * Higher-level algorithms will generate ordered sequences of these entries.
+ */
+export interface PaintStep {
+  box: RenderBox;
+}

package/src/pdf/svg/aspect-ratio.ts

@@ -0,0 +1,81 @@
+export type AspectAlign =
+  | "none"
+  | "xMinYMin"
+  | "xMidYMin"
+  | "xMaxYMin"
+  | "xMinYMid"
+  | "xMidYMid"
+  | "xMaxYMid"
+  | "xMinYMax"
+  | "xMidYMax"
+  | "xMaxYMax";
+
+export interface PreserveAspectRatioConfig {
+  align: AspectAlign;
+  meetOrSlice: "meet" | "slice";
+}
+
+export function parsePreserveAspectRatio(raw: string | undefined): PreserveAspectRatioConfig {
+  const defaultValue: PreserveAspectRatioConfig = { align: "xMidYMid", meetOrSlice: "meet" };
+  if (!raw) {
+    return defaultValue;
+  }
+  const tokens = raw.trim().split(/[\s,]+/).filter(Boolean);
+  if (tokens.length === 0) {
+    return defaultValue;
+  }
+
+  const validAlignments: Record<string, AspectAlign> = {
+    none: "none",
+    xminymin: "xMinYMin",
+    xmidymin: "xMidYMin",
+    xmaxymin: "xMaxYMin",
+    xminymid: "xMinYMid",
+    xmidymid: "xMidYMid",
+    xmaxymid: "xMaxYMid",
+    xminymax: "xMinYMax",
+    xmidymax: "xMidYMax",
+    xmaxymax: "xMaxYMax",
+  };
+
+  let index = 0;
+  let alignToken = tokens[index]?.toLowerCase() ?? "";
+  if (alignToken === "defer") {
+    index += 1;
+    alignToken = tokens[index]?.toLowerCase() ?? "";
+  }
+  index += 1;
+
+  let align = validAlignments[alignToken] ?? defaultValue.align;
+  if (align === "none") {
+    return { align: "none", meetOrSlice: "meet" };
+  }
+
+  let meetOrSlice: "meet" | "slice" = "meet";
+  for (; index < tokens.length; index += 1) {
+    const token = tokens[index]?.toLowerCase();
+    if (token === "meet") {
+      meetOrSlice = "meet";
+      break;
+    }
+    if (token === "slice") {
+      meetOrSlice = "slice";
+      break;
+    }
+  }
+
+  if (!validAlignments[alignToken]) {
+    align = defaultValue.align;
+  }
+
+  return { align, meetOrSlice };
+}
+
+export function getAlignFactors(align: AspectAlign): { x: number; y: number } {
+  if (align === "none") {
+    return { x: 0, y: 0 };
+  }
+  const horizontal = align.includes("xMid") ? 0.5 : align.includes("xMax") ? 1 : 0;
+  const vertical = align.includes("YMid") ? 0.5 : align.includes("YMax") ? 1 : 0;
+  return { x: horizontal, y: vertical };
+}

package/src/pdf/svg/coordinate-mapper.ts

@@ -0,0 +1,81 @@
+import type { SvgPoint } from "../../svg/types.js";
+import type { NormalizedPathCommand } from "../../svg/path-data.js";
+import type { PathCommand } from "../renderers/shape-renderer.js";
+import type { SvgRenderContext } from "./render-svg.js";
+import { applyMatrixToPoint } from "../../geometry/matrix.js";
+
+export function mapPoints(points: readonly SvgPoint[], context: SvgRenderContext): { x: number; y: number }[] {
+  const result: { x: number; y: number }[] = [];
+  for (const point of points) {
+    const mapped = mapSvgPoint(point.x, point.y, context);
+    if (!mapped) {
+      return [];
+    }
+    result.push(mapped);
+  }
+  return result;
+}
+
+export function mapPathSegments(segments: readonly NormalizedPathCommand[], context: SvgRenderContext): PathCommand[] | null {
+  const commands: PathCommand[] = [];
+  for (const segment of segments) {
+    switch (segment.type) {
+      case "M": {
+        const point = mapSvgPoint(segment.x, segment.y, context);
+        if (!point) {
+          return null;
+        }
+        commands.push({ type: "moveTo", x: point.x, y: point.y });
+        break;
+      }
+      case "L": {
+        const point = mapSvgPoint(segment.x, segment.y, context);
+        if (!point) {
+          return null;
+        }
+        commands.push({ type: "lineTo", x: point.x, y: point.y });
+        break;
+      }
+      case "C": {
+        const cp1 = mapSvgPoint(segment.x1, segment.y1, context);
+        const cp2 = mapSvgPoint(segment.x2, segment.y2, context);
+        const end = mapSvgPoint(segment.x, segment.y, context);
+        if (!cp1 || !cp2 || !end) {
+          return null;
+        }
+        commands.push({
+          type: "curveTo",
+          x1: cp1.x,
+          y1: cp1.y,
+          x2: cp2.x,
+          y2: cp2.y,
+          x: end.x,
+          y: end.y,
+        });
+        break;
+      }
+      case "Z":
+        commands.push({ type: "closePath" });
+        break;
+      default:
+        return null;
+    }
+  }
+  return commands;
+}
+
+export function mapSvgPoint(x: number, y: number, context: SvgRenderContext): { x: number; y: number } | null {
+  if (!Number.isFinite(x) || !Number.isFinite(y)) {
+    return null;
+  }
+  const mapped = mapPointToViewport(context, x, y);
+  if (!Number.isFinite(mapped.x) || !Number.isFinite(mapped.y)) {
+    return null;
+  }
+  return mapped;
+}
+
+function mapPointToViewport(context: SvgRenderContext, x: number, y: number): { x: number; y: number } {
+  const local = applyMatrixToPoint(context.transform, x, y);
+  return applyMatrixToPoint(context.viewportMatrix, local.x, local.y);
+}

package/src/pdf/svg/geometry-builder.ts

@@ -0,0 +1,45 @@
+import type { NormalizedPathCommand } from "../../svg/path-data.js";
+
+const CIRCLE_KAPPA = 0.5522847498307936;
+
+export function buildRectSegments(x: number, y: number, width: number, height: number): NormalizedPathCommand[] {
+  return [
+    { type: "M", x, y },
+    { type: "L", x: x + width, y },
+    { type: "L", x: x + width, y: y + height },
+    { type: "L", x, y: y + height },
+    { type: "Z" },
+  ];
+}
+
+export function buildRoundedRectSegments(x: number, y: number, width: number, height: number, rx: number, ry: number): NormalizedPathCommand[] {
+  const right = x + width;
+  const bottom = y + height;
+  const kx = rx * CIRCLE_KAPPA;
+  const ky = ry * CIRCLE_KAPPA;
+  return [
+    { type: "M", x: x + rx, y },
+    { type: "L", x: right - rx, y },
+    { type: "C", x1: right - rx + kx, y1: y, x2: right, y2: y + ry - ky, x: right, y: y + ry },
+    { type: "L", x: right, y: bottom - ry },
+    { type: "C", x1: right, y1: bottom - ry + ky, x2: right - rx + kx, y2: bottom, x: right - rx, y: bottom },
+    { type: "L", x: x + rx, y: bottom },
+    { type: "C", x1: x + rx - kx, y1: bottom, x2: x, y2: bottom - ry + ky, x: x, y: bottom - ry },
+    { type: "L", x, y: y + ry },
+    { type: "C", x1: x, y1: y + ry - ky, x2: x + rx - kx, y2: y, x: x + rx, y },
+    { type: "Z" },
+  ];
+}
+
+export function buildEllipseSegments(cx: number, cy: number, rx: number, ry: number): NormalizedPathCommand[] {
+  const mx = rx * CIRCLE_KAPPA;
+  const my = ry * CIRCLE_KAPPA;
+  return [
+    { type: "M", x: cx, y: cy - ry },
+    { type: "C", x1: cx + mx, y1: cy - ry, x2: cx + rx, y2: cy - my, x: cx + rx, y: cy },
+    { type: "C", x1: cx + rx, y1: cy + my, x2: cx + mx, y2: cy + ry, x: cx, y: cy + ry },
+    { type: "C", x1: cx - mx, y1: cy + ry, x2: cx - rx, y2: cy + my, x: cx - rx, y: cy },
+    { type: "C", x1: cx - rx, y1: cy - my, x2: cx - mx, y2: cy - ry, x: cx, y: cy - ry },
+    { type: "Z" },
+  ];
+}

package/src/pdf/svg/render-svg.ts

@@ -0,0 +1,296 @@
+import type { PagePainter } from "../page-painter.js";
+import type { RenderBox } from "../types.js";
+import type { SvgNode, SvgRootNode, SvgImageNode } from "../../svg/types.js";
+import {
+  renderCircle,
+  renderEllipse,
+  renderLine,
+  renderPath,
+  renderPolygon,
+  renderPolyline,
+  renderRect,
+  renderText,
+} from "./shape-renderer.js";
+import { createDefaultStyle, deriveStyle, type SvgStyle } from "./style-computer.js";
+import { computeStrokeScale, identityMatrix, multiplyMatrices, type Matrix } from "../../geometry/matrix.js";
+import { parseTransform } from "../../transform/css-parser.js";
+import { mapSvgPoint } from "./coordinate-mapper.js";
+import { ImageService } from "../../image/image-service.js";
+import { getAlignFactors, parsePreserveAspectRatio } from "./aspect-ratio.js";
+import { decodeBase64ToUint8Array } from "../../utils/base64.js";
+import type { Environment } from "../../environment/environment.js";
+
+interface SvgCustomData {
+  root: SvgRootNode;
+  intrinsicWidth: number;
+  intrinsicHeight: number;
+  resourceBaseDir?: string;
+  assetRootDir?: string;
+}
+
+export interface SvgRenderContext {
+  painter: PagePainter;
+  viewportMatrix: Matrix;
+  transform: Matrix;
+  strokeScale: number;
+  // optional resource roots propagated from HTML conversion
+  resourceBaseDir?: string;
+  assetRootDir?: string;
+  environment?: Environment;
+}
+
+// Map of defs by id (gradients, clipPaths, etc.) built once per svg render
+export type SvgDefsMap = Map<string, any>;
+
+export async function renderSvgBox(painter: PagePainter, box: RenderBox, environment?: Environment): Promise<void> {
+  const svgData = extractSvgCustomData(box);
+  if (!svgData) {
+    return;
+  }
+
+  const { root } = svgData;
+  const content = box.contentBox;
+  const widthPx = Math.max(content.width, 0);
+  const heightPx = Math.max(content.height, 0);
+  if (widthPx <= 0 || heightPx <= 0) {
+    return;
+  }
+
+  const sourceWidth = resolvePositive(root.viewBox?.width ?? svgData.intrinsicWidth ?? widthPx);
+  const sourceHeight = resolvePositive(root.viewBox?.height ?? svgData.intrinsicHeight ?? heightPx);
+  const minX = root.viewBox?.minX ?? 0;
+  const minY = root.viewBox?.minY ?? 0;
+
+  const preserveAttr = root.attributes?.preserveAspectRatio ?? root.attributes?.preserveaspectratio;
+  const preserve = parsePreserveAspectRatio(typeof preserveAttr === "string" ? preserveAttr : undefined);
+
+  const baseScaleX = safeScale(widthPx / sourceWidth);
+  const baseScaleY = safeScale(heightPx / sourceHeight);
+
+  let scaleX = baseScaleX;
+  let scaleY = baseScaleY;
+  let offsetX = 0;
+  let offsetY = 0;
+
+  if (preserve.align !== "none") {
+    const uniformScale = preserve.meetOrSlice === "slice" ? Math.max(baseScaleX, baseScaleY) : Math.min(baseScaleX, baseScaleY);
+    scaleX = uniformScale;
+    scaleY = uniformScale;
+    const scaledWidth = sourceWidth * scaleX;
+    const scaledHeight = sourceHeight * scaleY;
+    const extraWidth = widthPx - scaledWidth;
+    const extraHeight = heightPx - scaledHeight;
+    const factors = getAlignFactors(preserve.align);
+    offsetX = extraWidth * factors.x;
+    offsetY = extraHeight * factors.y;
+  }
+
+  const viewportMatrix: Matrix = {
+    a: scaleX,
+    b: 0,
+    c: 0,
+    d: scaleY,
+    e: content.x + offsetX - minX * scaleX,
+    f: content.y + offsetY - minY * scaleY,
+  };
+
+  const initialTransform = identityMatrix();
+  const strokeScale = computeStrokeScale(viewportMatrix, initialTransform);
+
+  const context: SvgRenderContext = {
+    painter,
+    viewportMatrix,
+    transform: initialTransform,
+    strokeScale,
+    environment,
+    // resource roots will be set below from the box customData if available
+  };
+
+  // Build defs map (id -> node) so paint servers like gradients can be resolved during rendering
+  const defs = new Map<string, any>();
+  collectDefs(root, defs);
+  // Attach to context for downstream use
+  (context as any).defs = defs;
+
+  // If convertDomNode attached resource roots into the customData for this SVG, copy them to context
+  if ((svgData as any).resourceBaseDir) {
+    context.resourceBaseDir = (svgData as any).resourceBaseDir as string;
+  }
+  if ((svgData as any).assetRootDir) {
+    context.assetRootDir = (svgData as any).assetRootDir as string;
+  }
+
+  const baseStyle = createDefaultStyle();
+  await renderNode(root, baseStyle, context);
+}
+
+function collectDefs(node: SvgNode, map: Map<string, any>): void {
+  if (!node) return;
+  // If node has an id, register it
+  const id = (node as any).id;
+  if (id && typeof id === "string") {
+    map.set(id, node);
+  }
+  // Recurse into children for container nodes
+  if ((node as any).children && Array.isArray((node as any).children)) {
+    for (const child of (node as any).children) {
+      collectDefs(child, map);
+    }
+  }
+}
+
+function extractSvgCustomData(box: RenderBox): SvgCustomData | null {
+  const raw = box.customData?.svg;
+  if (!raw || typeof raw !== "object") {
+    return null;
+  }
+  const candidate = raw as Partial<SvgCustomData>;
+  if (!candidate.root) {
+    return null;
+  }
+  return {
+    root: candidate.root,
+    intrinsicWidth: resolvePositive(candidate.intrinsicWidth ?? 0),
+    intrinsicHeight: resolvePositive(candidate.intrinsicHeight ?? 0),
+    resourceBaseDir: candidate.resourceBaseDir,
+    assetRootDir: candidate.assetRootDir,
+  };
+}
+
+async function renderNode(node: SvgNode, style: SvgStyle, context: SvgRenderContext): Promise<void> {
+  let workingContext = context;
+  const nodeTransform = parseTransform(node.transform);
+  if (nodeTransform) {
+    const combined = multiplyMatrices(context.transform, nodeTransform);
+    workingContext = {
+      painter: context.painter,
+      viewportMatrix: context.viewportMatrix,
+      transform: combined,
+      strokeScale: computeStrokeScale(context.viewportMatrix, combined),
+    };
+  }
+
+  switch (node.type) {
+    case "svg":
+    case "g": {
+      const nextStyle = deriveStyle(style, node);
+      for (const child of node.children) {
+        await renderNode(child, nextStyle, workingContext);
+      }
+      return;
+    }
+    case "rect":
+      return renderRect(node, deriveStyle(style, node), workingContext);
+    case "circle":
+      return renderCircle(node, deriveStyle(style, node), workingContext);
+    case "ellipse":
+      return renderEllipse(node, deriveStyle(style, node), workingContext);
+    case "polygon":
+      return renderPolygon(node, deriveStyle(style, node), workingContext);
+    case "polyline":
+      return renderPolyline(node, deriveStyle(style, node), workingContext);
+    case "line":
+      return renderLine(node, deriveStyle(style, node), workingContext);
+    case "text":
+      return renderText(node, deriveStyle(style, node), workingContext);
+    case "image":
+      // Render SVG <image> elements by loading the referenced image and drawing it
+      return await renderImage(node as SvgImageNode, deriveStyle(style, node), workingContext);
+    case "path":
+      return renderPath(node, deriveStyle(style, node), workingContext);
+    default:
+      return;
+  }
+}
+
+function safeScale(value: number): number {
+  if (!Number.isFinite(value) || value === 0) {
+    return 1;
+  }
+  return value;
+}
+
+function resolvePositive(value: number): number {
+  if (!Number.isFinite(value) || value <= 0) {
+    return 1;
+  }
+  return value;
+}
+
+async function renderImage(node: SvgImageNode, _style: SvgStyle, context: SvgRenderContext): Promise<void> {
+  const hrefAttr = node.href ?? node.attributes?.href ?? node.attributes?.["xlink:href"];
+  if (!hrefAttr || typeof hrefAttr !== "string") {
+    return;
+  }
+
+  let imageInfo;
+  const imageService = ImageService.getInstance(context.environment);
+  try {
+    if (hrefAttr.startsWith("data:")) {
+      // data URI
+      const comma = hrefAttr.indexOf(",");
+      if (comma < 0) return;
+      const meta = hrefAttr.substring(5, comma);
+      const isBase64 = meta.endsWith(";base64");
+      const payload = hrefAttr.substring(comma + 1);
+      const bytes = isBase64 ? decodeBase64ToUint8Array(payload) : new TextEncoder().encode(decodeURIComponent(payload));
+      const copy = bytes.slice();
+      imageInfo = await imageService.decodeImage(copy.buffer);
+    } else if (/^https?:\/\//i.test(hrefAttr)) {
+      // Remote images not supported in this offline renderer
+      console.debug("Skipping remote image in SVG:", hrefAttr);
+      return;
+    } else {
+      // Local file reference. Resolve using assetRootDir for absolute (/images/...) or resourceBaseDir for relative
+      const hasProcess = typeof process !== "undefined" && !!process.versions?.node;
+      if (!hasProcess) {
+        console.debug("Skipping local SVG image in non-Node environment:", hrefAttr);
+        return;
+      }
+      const resolver = context.environment?.resolveLocal;
+      if (!resolver) {
+        console.debug("Skipping local SVG image (no resolver in environment):", hrefAttr);
+        return;
+      }
+      // Choose base: assetRootDir for paths starting with /, resourceBaseDir for relative paths
+      const base = hrefAttr.startsWith('/')
+        ? (context.assetRootDir ?? context.resourceBaseDir)
+        : (context.resourceBaseDir ?? context.assetRootDir);
+      const resolved = resolver(hrefAttr, base);
+      imageInfo = await imageService.loadImage(resolved);
+      (node as any)._resolvedHref = resolved;
+    }
+  } catch (err) {
+    console.debug("Failed to load SVG image", hrefAttr, err instanceof Error ? err.message : err);
+    return;
+  }
+
+  if (!imageInfo) return;
+
+  const drawWidth = Number.isFinite(node.width as number) ? (node.width as number) : imageInfo.width;
+  const drawHeight = Number.isFinite(node.height as number) ? (node.height as number) : imageInfo.height;
+
+  const p1 = mapSvgPoint(Number(node.x ?? 0), Number(node.y ?? 0), context);
+  const p2 = mapSvgPoint(Number(node.x ?? 0) + drawWidth, Number(node.y ?? 0) + drawHeight, context);
+  if (!p1 || !p2) {
+    return;
+  }
+
+  const rect = { x: p1.x, y: p1.y, width: p2.x - p1.x, height: p2.y - p1.y };
+
+  const imageRef = {
+    src: (node as any)._resolvedHref ?? hrefAttr,
+    width: imageInfo.width,
+    height: imageInfo.height,
+    format: imageInfo.format,
+    channels: imageInfo.channels,
+    bitsPerComponent: imageInfo.bitsPerChannel,
+    data: imageInfo.data,
+  } as const;
+
+  try {
+    context.painter.drawImage(imageRef as any, rect);
+  } catch (err) {
+    console.debug("Failed to draw image in SVG", hrefAttr, err instanceof Error ? err.message : err);
+  }
+}