@1agh/maude 1.0.7 → 1.0.8

package/apps/studio/exporters/capture-core.ts

@@ -18,12 +18,20 @@
 // with zero shims. Loaded as a side-effect module: assigns
 // `window.__maudeCaptureCore` so the shim can reach it without an importmap.
 
+import { applyCaptureChrome, CAPTURE_HIDDEN_SELECTORS } from './capture-chrome.ts';
+
 /** The subset of dom-to-svg the capture uses (IIFE `window.domToSvg` in the
  * shim host; `await import('dom-to-svg')` through the importmap in the canvas
  * runtime host). */
 export interface DomToSvgApi {
   elementToSVG(el: Element): XMLDocument;
-  inlineResources(el: Element): Promise<void>;
+  /**
+   * Present on the module but NOT used — dom-to-svg 0.12.2's own inlining is
+   * broken for images (it writes `xlink:href`, reads `href.baseVal`). Kept in
+   * the type so the shape of the injected module still documents itself; the
+   * working implementation is {@link inlineCaptureResources}.
+   */
+  inlineResources?(el: Element): Promise<void>;
 }
 
 // Raster ceilings — mirrored from bin/_png-playwright.mjs (feature-2-print-
@@ -163,9 +171,572 @@ function effectiveBg(node: Element): string | null {
   return null;
 }
 
+// ── paint polyfills for dom-to-svg ──────────────────────────────────────────
+//
+// dom-to-svg reconstructs CSS paint as SVG primitives and has no equivalent for
+// two things design systems lean on for signature decoration: a
+// `repeating-linear-gradient` (it matches `linear-gradient` only) and a
+// `clip-path: polygon()` (it opens a stacking context and drops the clip). The
+// alligators "Sash" — a diagonal yellow stripe band, clipped to a corner
+// triangle — is both at once, and vanished from every dom-to-svg lane (SVG
+// everywhere, browser PNG, PPTX deck) while the screenshot lanes kept it.
+//
+// SVG has exact analogues: <linearGradient spreadMethod="repeat"> and
+// <clipPath>. So for a LEAF decorative element (no element children — the only
+// shape where substituting the paint cannot re-layout anything) we insert an
+// equivalent inline <svg> for the duration of elementToSVG — dom-to-svg copies
+// inline SVG verbatim — and restore the element right after. Synchronous,
+// bracketing a synchronous call: the live canvas never paints the substitute.
+
+interface ParsedStop {
+  color: string;
+  px: number;
+}
+interface ParsedRepeatingGradient {
+  angleDeg: number;
+  stops: ParsedStop[];
+}
+
+/** Split on top-level commas (colors carry commas inside `rgb(...)`). */
+function splitTopLevel(s: string): string[] {
+  const out: string[] = [];
+  let depth = 0;
+  let cur = '';
+  for (const ch of s) {
+    if (ch === '(') depth += 1;
+    if (ch === ')') depth -= 1;
+    if (ch === ',' && depth === 0) {
+      out.push(cur.trim());
+      cur = '';
+    } else cur += ch;
+  }
+  if (cur.trim()) out.push(cur.trim());
+  return out;
+}
+
+/** Parse a COMPUTED `repeating-linear-gradient(...)` (stops already expanded
+ * to `<color> <px|%>` pairs by the engine). `null` for anything else. */
+function parseRepeatingLinearGradient(
+  value: string,
+  w: number,
+  h: number
+): ParsedRepeatingGradient | null {
+  const m = /^repeating-linear-gradient\((.*)\)$/.exec(value.trim());
+  if (!m) return null;
+  const parts = splitTopLevel(m[1] ?? '');
+  if (!parts.length) return null;
+  let angleDeg = 180;
+  let first = parts[0] ?? '';
+  const angle = /^(-?[\d.]+)deg$/.exec(first);
+  const corner = Math.atan2(w, h) * (180 / Math.PI);
+  const keyword: Record<string, number> = {
+    'to top': 0,
+    'to right': 90,
+    'to bottom': 180,
+    'to left': 270,
+    'to top right': corner,
+    'to right top': corner,
+    'to top left': 360 - corner,
+    'to left top': 360 - corner,
+    'to bottom right': 180 - corner,
+    'to right bottom': 180 - corner,
+    'to bottom left': 180 + corner,
+    'to left bottom': 180 + corner,
+  };
+  if (angle) {
+    angleDeg = Number.parseFloat(angle[1] ?? '180');
+    parts.shift();
+  } else if (first in keyword) {
+    angleDeg = keyword[first] as number;
+    parts.shift();
+  }
+  first = '';
+  // Gradient-line length per CSS Images: |w·sin a| + |h·cos a|.
+  const rad = (angleDeg * Math.PI) / 180;
+  const lineLen = Math.abs(w * Math.sin(rad)) + Math.abs(h * Math.cos(rad));
+  const stops: ParsedStop[] = [];
+  for (const part of parts) {
+    const sm = /^(.*?)\s+(-?[\d.]+)(px|%)$/.exec(part);
+    if (!sm) return null; // a stop without a position — not the computed form
+    const px =
+      sm[3] === '%'
+        ? (Number.parseFloat(sm[2] ?? '0') / 100) * lineLen
+        : Number.parseFloat(sm[2] ?? '0');
+    stops.push({ color: (sm[1] ?? '').trim(), px });
+  }
+  if (stops.length < 2) return null;
+  return { angleDeg, stops };
+}
+
+/** `polygon(...)` of a computed clip-path → absolute points in the box. */
+function parsePolygonClip(value: string, w: number, h: number): string | null {
+  const m = /^polygon\((.*)\)$/.exec(value.trim());
+  if (!m) return null;
+  const pts: string[] = [];
+  for (const pair of splitTopLevel(m[1] ?? '')) {
+    const [xs, ys] = pair.split(/\s+/);
+    if (!xs || !ys) return null;
+    const len = (v: string, ref: number) =>
+      v.endsWith('%') ? (Number.parseFloat(v) / 100) * ref : Number.parseFloat(v);
+    const x = len(xs, w);
+    const y = len(ys, h);
+    if (!Number.isFinite(x) || !Number.isFinite(y)) return null;
+    pts.push(`${x},${y}`);
+  }
+  return pts.length >= 3 ? pts.join(' ') : null;
+}
+
+let polyfillSeq = 0;
+
+/**
+ * Substitute unsupported paint on leaf elements under `target` with inline
+ * SVG; returns the undo. Call immediately before `elementToSVG`, undo
+ * immediately after.
+ */
+export function applyPaintPolyfills(target: Element): () => void {
+  const undos: Array<() => void> = [];
+  const NS = 'http://www.w3.org/2000/svg';
+  const candidates: HTMLElement[] = [];
+  const consider = (el: Element) => {
+    if (!(el instanceof HTMLElement)) return;
+    if (el.children.length > 0) return; // leaf only
+    const cs = getComputedStyle(el);
+    const hasRepeating = cs.backgroundImage.startsWith('repeating-linear-gradient(');
+    const hasPolygon = cs.clipPath.startsWith('polygon(');
+    if (hasRepeating || hasPolygon) candidates.push(el);
+  };
+  consider(target);
+  for (const el of target.querySelectorAll('*')) consider(el);
+
+  for (const el of candidates) {
+    const cs = getComputedStyle(el);
+    const w = el.clientWidth;
+    const h = el.clientHeight;
+    if (!w || !h) continue;
+    polyfillSeq += 1;
+    const uid = `maude-pp-${polyfillSeq}`;
+    const svg = document.createElementNS(NS, 'svg');
+    svg.setAttribute('width', String(w));
+    svg.setAttribute('height', String(h));
+    svg.setAttribute('viewBox', `0 0 ${w} ${h}`);
+    svg.setAttribute('aria-hidden', 'true');
+    svg.setAttribute('data-maude-paint-polyfill', '1');
+    svg.style.cssText =
+      'position:absolute;left:0;top:0;width:100%;height:100%;pointer-events:none;display:block';
+    const defs = document.createElementNS(NS, 'defs');
+    svg.appendChild(defs);
+
+    let fill: string | null = null;
+    let paintNode: Element | null = null;
+    const grad = parseRepeatingLinearGradient(cs.backgroundImage, w, h);
+    if (grad) {
+      const rad = (grad.angleDeg * Math.PI) / 180;
+      const dx = Math.sin(rad);
+      const dy = -Math.cos(rad);
+      const lineLen = Math.abs(w * dx) + Math.abs(h * Math.cos(rad));
+      const cx = w / 2;
+      const cy = h / 2;
+      const sx = cx - (dx * lineLen) / 2;
+      const sy = cy - (dy * lineLen) / 2;
+      const firstPx = grad.stops[0]?.px ?? 0;
+      const lastPx = grad.stops[grad.stops.length - 1]?.px ?? firstPx + 1;
+      const period = Math.max(0.01, lastPx - firstPx);
+      const lg = document.createElementNS(NS, 'linearGradient');
+      lg.setAttribute('id', `${uid}-g`);
+      lg.setAttribute('gradientUnits', 'userSpaceOnUse');
+      lg.setAttribute('spreadMethod', 'repeat');
+      lg.setAttribute('x1', String(sx + dx * firstPx));
+      lg.setAttribute('y1', String(sy + dy * firstPx));
+      lg.setAttribute('x2', String(sx + dx * lastPx));
+      lg.setAttribute('y2', String(sy + dy * lastPx));
+      for (const st of grad.stops) {
+        const stop = document.createElementNS(NS, 'stop');
+        stop.setAttribute('offset', String((st.px - firstPx) / period));
+        stop.setAttribute('stop-color', st.color);
+        lg.appendChild(stop);
+      }
+      defs.appendChild(lg);
+      fill = `url(#${uid}-g)`;
+    } else if (isOpaque(cs.backgroundColor) && cs.backgroundImage === 'none') {
+      fill = cs.backgroundColor;
+    }
+    const bgUrl = /^url\(["']?([^"')]+)["']?\)$/.exec(cs.backgroundImage)?.[1];
+    if (!fill && bgUrl) {
+      // A clipped background IMAGE (the camo corner): <image> with the cover
+      // mapping; the inliner embeds it like every other <image>.
+      const im = document.createElementNS(NS, 'image');
+      im.setAttribute('href', bgUrl);
+      im.setAttribute('xlink:href', bgUrl);
+      im.setAttribute('x', '0');
+      im.setAttribute('y', '0');
+      im.setAttribute('width', String(w));
+      im.setAttribute('height', String(h));
+      im.setAttribute(
+        'preserveAspectRatio',
+        cs.backgroundSize === 'cover'
+          ? 'xMidYMid slice'
+          : cs.backgroundSize === 'contain'
+            ? 'xMidYMid meet'
+            : 'none'
+      );
+      paintNode = im;
+    } else if (fill) {
+      const rect = document.createElementNS(NS, 'rect');
+      rect.setAttribute('x', '0');
+      rect.setAttribute('y', '0');
+      rect.setAttribute('width', String(w));
+      rect.setAttribute('height', String(h));
+      rect.setAttribute('fill', fill);
+      paintNode = rect;
+    }
+    if (!paintNode) continue;
+
+    const poly = parsePolygonClip(cs.clipPath, w, h);
+    if (poly) {
+      const cp = document.createElementNS(NS, 'clipPath');
+      cp.setAttribute('id', `${uid}-c`);
+      cp.setAttribute('clipPathUnits', 'userSpaceOnUse');
+      const pg = document.createElementNS(NS, 'polygon');
+      pg.setAttribute('points', poly);
+      cp.appendChild(pg);
+      defs.appendChild(cp);
+      paintNode.setAttribute('clip-path', `url(#${uid}-c)`);
+    }
+    svg.appendChild(paintNode);
+
+    // Swap: hide the CSS paint dom-to-svg would mis-render, mount the SVG.
+    const prev = {
+      backgroundImage: el.style.backgroundImage,
+      backgroundColor: el.style.backgroundColor,
+      position: el.style.position,
+    };
+    el.style.backgroundImage = 'none';
+    if (fill && fill === cs.backgroundColor) el.style.backgroundColor = 'transparent';
+    if (cs.position === 'static') el.style.position = 'relative';
+    el.appendChild(svg);
+    undos.push(() => {
+      svg.remove();
+      el.style.backgroundImage = prev.backgroundImage;
+      el.style.backgroundColor = prev.backgroundColor;
+      el.style.position = prev.position;
+    });
+  }
+  return () => {
+    for (const u of undos.reverse()) u();
+  };
+}
+
 export interface SvgCaptureOptions {
   /** Capture the enclosing `[data-dc-screen]` rather than the element itself. */
   widenToArtboard?: boolean;
+  /**
+   * Ceiling on the pre-capture asset wait AND on each resource inline, in ms.
+   * A stalled asset must delay a capture, never hang it.
+   */
+  assetTimeoutMs?: number;
+}
+
+const DEFAULT_ASSET_TIMEOUT_MS = 10_000;
+
+const withTimeout = <T>(p: Promise<T>, ms: number, fallback: T): Promise<T> =>
+  Promise.race([p, new Promise<T>((r) => setTimeout(() => r(fallback), ms))]);
+
+/** Resolve once an `<img>` has finished loading — successfully or not. */
+function imageSettled(img: HTMLImageElement): Promise<void> {
+  if (img.complete) return img.decode().catch(() => {});
+  return new Promise<void>((resolve) => {
+    const done = () => {
+      img.removeEventListener('load', done);
+      img.removeEventListener('error', done);
+      resolve();
+    };
+    img.addEventListener('load', done);
+    img.addEventListener('error', done);
+  }).then(() => img.decode().catch(() => {}));
+}
+
+/**
+ * Wait for the things a capture silently drops if it races them: webfonts, and
+ * every `<img>` inside the target.
+ *
+ * The playwright hosts get this for free — they navigate and wait for `load`
+ * before evaluating. The browser lane captures a LIVE canvas whose images may
+ * still be in flight ("musí se počkat na obrázky a assety"), so the wait has to
+ * live in the shared spine instead of in one host's navigation options.
+ *
+ * Bounded: a broken or hanging asset costs `timeoutMs` and then the capture
+ * proceeds without it. A late image beats no export.
+ */
+export async function waitForCaptureAssets(
+  target: Element,
+  timeoutMs: number = DEFAULT_ASSET_TIMEOUT_MS
+): Promise<void> {
+  const doc = target.ownerDocument ?? document;
+  const waits: Promise<unknown>[] = [];
+  const fonts = (doc as Document & { fonts?: FontFaceSet }).fonts;
+  if (fonts?.ready) waits.push(fonts.ready.catch(() => {}));
+  const imgs: HTMLImageElement[] = [];
+  if (target instanceof HTMLImageElement) imgs.push(target);
+  for (const img of target.querySelectorAll('img')) imgs.push(img);
+  for (const img of imgs) waits.push(imageSettled(img));
+  await withTimeout(
+    Promise.all(waits).then(() => undefined),
+    timeoutMs,
+    undefined
+  );
+}
+
+/**
+ * Drop the serialized remains of hidden editor chrome.
+ *
+ * `applyCaptureChrome` makes the chrome render nothing, but dom-to-svg still
+ * emits an (empty) `<g>` for a `display:none` element, carrying its class and
+ * `aria-label` — so the artboard's title text survived into the file as
+ * metadata even once it stopped painting. Nothing downstream wants it: it is
+ * an editor affordance, not design content.
+ */
+export function stripChromeNodes(root: Element): void {
+  const removedIds = new Set<string>();
+  for (const selector of CAPTURE_HIDDEN_SELECTORS) {
+    // ids are rewritten during serialization — class/attribute selectors are
+    // the ones that survive, and they cover every entry that can appear here.
+    if (selector.startsWith('#')) continue;
+    for (const node of Array.from(root.querySelectorAll(selector))) {
+      const id = node.getAttribute('id');
+      if (id) removedIds.add(id);
+      node.remove();
+    }
+  }
+  if (!removedIds.size) return;
+  // dom-to-svg mirrors the DOM's accessibility tree onto the output, so the
+  // artboard still points at the label it no longer contains. Leave no dangling
+  // idref: it is invalid ARIA, and it is how the label's name survived the
+  // node's removal.
+  for (const owner of Array.from(root.querySelectorAll('[aria-owns]'))) {
+    const kept = (owner.getAttribute('aria-owns') ?? '')
+      .split(/\s+/)
+      .filter((id) => id && !removedIds.has(id));
+    if (kept.length) owner.setAttribute('aria-owns', kept.join(' '));
+    else owner.removeAttribute('aria-owns');
+  }
+}
+
+/**
+ * Remove any `<image>` element still pointing at a remote `http(s)` URL after
+ * inlining — a beacon the capture CSP blocked from embedding but that would
+ * fire on open. Data URIs and in-document `#fragment` refs are kept.
+ */
+export function dropRemoteRefs(root: Element): void {
+  for (const node of Array.from(root.querySelectorAll('image'))) {
+    const href = node.getAttribute('xlink:href') ?? node.getAttribute('href') ?? '';
+    if (/^\s*https?:/i.test(href)) node.remove();
+  }
+}
+
+const isEmbeddable = (href: string | null): href is string =>
+  !!href && !href.startsWith('data:') && !href.startsWith('#');
+
+/** Read whichever href attribute dom-to-svg happened to write. */
+function readHref(el: Element): string | null {
+  return el.getAttribute('xlink:href') ?? el.getAttribute('href');
+}
+
+/** Write BOTH, so every downstream consumer sees the embedded bytes. */
+function writeHref(el: Element, value: string): void {
+  el.setAttribute('xlink:href', value);
+  el.setAttribute('href', value);
+}
+
+function blobToDataUrl(blob: Blob): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const reader = new FileReader();
+    reader.onerror = () => reject(new Error('failed to read resource blob'));
+    reader.onload = () => resolve(String(reader.result));
+    reader.readAsDataURL(blob);
+  });
+}
+
+/** Fetch a resource and return it as a `data:` URI — original bytes, original
+ * MIME (so an SVG logo stays vector). Same-origin by construction for canvas
+ * assets, so the browser attaches whatever credential the live `<img>` used. */
+async function dataUrlByFetch(url: string, timeoutMs: number): Promise<string | null> {
+  try {
+    const res = await withTimeout(fetch(url), timeoutMs, null as Response | null);
+    if (!res?.ok) return null;
+    return await blobToDataUrl(await res.blob());
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Last-resort inline: repaint an ALREADY-DECODED `<img>` through a canvas.
+ * No network, so it survives a resource the capture context may not re-fetch
+ * (a credentialed URL, an opaque-origin document, a revoked object URL). A
+ * cross-origin bitmap without CORS taints the canvas and `toDataURL` throws —
+ * caught, and the ref is left remote rather than emitting a wrong picture.
+ */
+function dataUrlFromDecodedImage(img: HTMLImageElement, filter?: string): string | null {
+  if (!img.naturalWidth || !img.naturalHeight) return null;
+  try {
+    const canvas = document.createElement('canvas');
+    canvas.width = img.naturalWidth;
+    canvas.height = img.naturalHeight;
+    const ctx = canvas.getContext('2d');
+    if (!ctx) return null;
+    if (filter) {
+      // Bake the element's CSS `filter` into the bitmap. Canvas 2D accepts the
+      // same grammar as CSS — including `url(#id)` against an SVG filter in
+      // THIS document — so a duotone/posterize treatment survives into the
+      // artifact. An engine that doesn't support it leaves `ctx.filter` at
+      // 'none'; detect that and report failure so the caller falls back to
+      // the unfiltered bytes rather than silently shipping a wrong picture.
+      ctx.filter = filter;
+      if (ctx.filter !== filter) return null;
+    }
+    ctx.drawImage(img, 0, 0);
+    return canvas.toDataURL('image/png');
+  } catch {
+    return null;
+  }
+}
+
+/** The element's computed CSS `filter`, or null when it paints unfiltered. */
+function imageFilterOf(img: HTMLImageElement): string | null {
+  const f = getComputedStyle(img).filter;
+  return f && f !== 'none' ? f : null;
+}
+
+/**
+ * The SVG `preserveAspectRatio` equivalent of an <img>'s `object-fit` +
+ * `object-position`, or null for the default (`contain`-like `meet` at centre).
+ * `object-position` maps to the nine alignment keywords by thirds — exact for
+ * the keyword/percentage values designs use, approximate for arbitrary lengths.
+ */
+function preserveAspectRatioFor(img: HTMLImageElement): string | null {
+  const cs = getComputedStyle(img);
+  const fit = cs.objectFit;
+  if (fit === 'fill') return 'none';
+  const align = (pos: string, size: number): 'Min' | 'Mid' | 'Max' => {
+    const n = pos.endsWith('%') ? Number.parseFloat(pos) : (Number.parseFloat(pos) / size) * 100;
+    if (!Number.isFinite(n)) return 'Mid';
+    return n < 33.4 ? 'Min' : n > 66.6 ? 'Max' : 'Mid';
+  };
+  const [px = '50%', py = '50%'] = cs.objectPosition.split(/\s+/);
+  const x = align(px, img.clientWidth || 1);
+  const y = align(py, img.clientHeight || 1);
+  if (fit === 'cover') return `x${x}Y${y} slice`;
+  if (fit === 'contain' || fit === 'scale-down') return `x${x}Y${y} meet`;
+  return null; // `none` — no scaling; SVG has no exact analogue, keep default
+}
+
+/** Index the live `<img>` elements by the URL they actually loaded. */
+function liveImagesByUrl(target: Element): Map<string, HTMLImageElement> {
+  const map = new Map<string, HTMLImageElement>();
+  const add = (img: HTMLImageElement) => {
+    for (const u of [img.currentSrc, img.src]) if (u) map.set(u, img);
+  };
+  if (target instanceof HTMLImageElement) add(target);
+  for (const img of target.querySelectorAll('img')) add(img);
+  return map;
+}
+
+/**
+ * Embed every external resource the serialized SVG still points at.
+ *
+ * WHY THIS EXISTS INSTEAD OF `domToSvg.inlineResources` (the DDR-231 Phase 2
+ * root cause): dom-to-svg 0.12.2 WRITES image URLs to `xlink:href` but READS
+ * them back as `element.href.baseVal`, which reflects the SVG2 `href`
+ * attribute. In a document built with `createElementNS` that is `''`, so its
+ * own `assert(url, 'No URL passed')` throws for every image — and it catches
+ * its own error and `console.error`s it. The result was an export whose
+ * `<image>` refs all stayed remote, with zero `data:` URIs and no thrown error
+ * anywhere: broken pictures in the SVG, and NOTHING in the PNG, because an
+ * SVG-as-image loads no external resources at all. It never worked; the desktop
+ * looked fine only because its PNG comes from a real screenshot, not this path.
+ *
+ * Order is deliberate — `fetch` first (keeps the original bytes and MIME, so a
+ * vector logo stays vector), decoded-`<img>` repaint second (no network, so it
+ * still works where the fetch is refused).
+ */
+export async function inlineCaptureResources(
+  root: Element,
+  target: Element,
+  timeoutMs: number = DEFAULT_ASSET_TIMEOUT_MS
+): Promise<void> {
+  const live = liveImagesByUrl(target);
+  const cache = new Map<string, string | null>();
+  const resolve = async (url: string): Promise<string | null> => {
+    const hit = cache.get(url);
+    if (hit !== undefined) return hit;
+    const img = live.get(url);
+    // A FILTERED image (CSS `filter:` — a brand duotone, a posterize via an
+    // in-page SVG filter) must be baked, not fetched: dom-to-svg carries no
+    // `filter` onto its <image>, so the original bytes would render flat.
+    // DDR-232 follow-up — the cloud PNG/SVG/PPTX lost the photo treatment
+    // the desktop screenshot kept. Unfiltered images stay fetch-first (the
+    // original bytes and MIME; a vector logo stays vector).
+    const filter = img ? imageFilterOf(img) : null;
+    let out: string | null = null;
+    if (img && filter) out = dataUrlFromDecodedImage(img, filter);
+    if (!out) out = await dataUrlByFetch(url, timeoutMs);
+    if (!out && img) out = dataUrlFromDecodedImage(img);
+    cache.set(url, out);
+    return out;
+  };
+
+  const images = Array.from(root.querySelectorAll('image'));
+  await Promise.all(
+    images.map(async (node) => {
+      const href = readHref(node);
+      if (!isEmbeddable(href)) return;
+      const abs = new URL(href, document.baseURI).href;
+      // dom-to-svg writes an <img> as <image x y width height> and nothing
+      // else — `object-fit: cover` (every hero photo) therefore rendered
+      // LETTERBOXED under SVG's default `xMidYMid meet`. Carry the fit over.
+      const img = live.get(abs);
+      if (img && !node.hasAttribute('preserveAspectRatio')) {
+        const par = preserveAspectRatioFor(img);
+        if (par) node.setAttribute('preserveAspectRatio', par);
+      }
+      const dataUrl = await resolve(abs);
+      if (dataUrl) writeHref(node, dataUrl);
+    })
+  );
+
+  // `@font-face` (and any other `url()`) inside the emitted <style> blocks —
+  // dom-to-svg puts the captured stylesheet there. Without this the SVG falls
+  // back to a system font the moment it leaves the serving origin, which is
+  // the classic silent fidelity killer.
+  appendInlineFontFaces(root);
+  await Promise.all(
+    Array.from(root.querySelectorAll('style')).map(async (styleEl) => {
+      const css = styleEl.textContent ?? '';
+      const urls = new Set<string>();
+      for (const m of css.matchAll(/url\(\s*(['"]?)([^)'"]+)\1\s*\)/g)) {
+        const raw = m[2]?.trim();
+        if (isEmbeddable(raw ?? null)) urls.add(raw as string);
+      }
+      if (!urls.size) return;
+      const pairs = await Promise.all(
+        Array.from(urls, async (u) => {
+          let abs: string;
+          try {
+            abs = new URL(u, document.baseURI).href;
+          } catch {
+            return [u, null] as const;
+          }
+          return [u, await resolve(abs)] as const;
+        })
+      );
+      let next = css;
+      for (const [original, dataUrl] of pairs) {
+        if (!dataUrl) continue;
+        next = next.split(original).join(dataUrl);
+      }
+      styleEl.textContent = next;
+    })
+  );
 }
 
 /**
@@ -181,11 +752,38 @@ export async function svgForElement(
   opts: SvgCaptureOptions = {}
 ): Promise<string> {
   const target = opts.widenToArtboard ? (el.closest('[data-dc-screen]') ?? el) : el;
+  const timeoutMs = opts.assetTimeoutMs ?? DEFAULT_ASSET_TIMEOUT_MS;
+  // Editor chrome OFF before anything is measured: the shim host gets this from
+  // `?hide-chrome=1`, the live-canvas host has no navigation to carry it, and
+  // hiding the artboard's `.dc-artboard-label` header also reflows the body
+  // into its space — so it must precede getComputedStyle, not follow it.
+  const releaseChrome = applyCaptureChrome(target.ownerDocument ?? document);
+  try {
+    return await serializeCapture(target, api, timeoutMs);
+  } finally {
+    releaseChrome();
+  }
+}
+
+async function serializeCapture(
+  target: Element,
+  api: DomToSvgApi,
+  timeoutMs: number
+): Promise<string> {
   const toSrgb = makeToSrgb();
+  await waitForCaptureAssets(target, timeoutMs);
 
   const bg = effectiveBg(target);
   const fillColor = bg ? toSrgb(bg) : null;
-  const svgDoc = api.elementToSVG(target);
+  // Bracket the synchronous serialization ONLY — the substitute paint must
+  // never be on screen across an await.
+  const undoPaint = applyPaintPolyfills(target);
+  let svgDoc: XMLDocument;
+  try {
+    svgDoc = api.elementToSVG(target);
+  } finally {
+    undoPaint();
+  }
   const root = svgDoc.documentElement;
   if (fillColor) {
     const NS = 'http://www.w3.org/2000/svg';
@@ -208,16 +806,68 @@ export async function svgForElement(
   // base64-embeds fonts + images so the SVG is portable outside the serving
   // origin — and, for the raster path, so the <img> decode is self-contained
   // (an SVG-as-image loads NO external resources; a data: font/image does).
+  // `api.inlineResources` is deliberately NOT used — see inlineCaptureResources.
+  void api;
+  stripChromeNodes(root);
   try {
-    await api.inlineResources(root);
+    await inlineCaptureResources(root, target, timeoutMs);
   } catch {
     /* best-effort — a missing resource beats a missing primitive */
   }
+  // BOUNDARY, not a fixture assertion (security review F5): any `<image>` whose
+  // href is STILL remote after inlining — a tenant `background:url(http://
+  // attacker/beacon)` the capture CSP refused to fetch — would fire when a
+  // DIFFERENT user opens the delivered file (outside any CSP). Drop it so the
+  // artifact carries no phone-home. A data:/#-fragment ref is fine.
+  dropRemoteRefs(root);
   let out = new XMLSerializer().serializeToString(svgDoc);
   out = out.replace(/(?:oklch|oklab|lch|lab|color)\([^)]*\)/gi, (m) => toSrgb(m) || m);
   return out;
 }
 
+/**
+ * Carry over `@font-face` rules dom-to-svg drops.
+ *
+ * dom-to-svg copies `@font-face` into the output ONLY from stylesheets that
+ * have an `href` (it needs one to absolutize relative `src` URLs) — a rule
+ * declared in an inline `<style>` is skipped outright, so a canvas whose font
+ * arrives that way renders in a fallback face everywhere but the live page.
+ * Append those rules, `src` made absolute against the document, so the
+ * `url()` inliner below treats them like every other font.
+ */
+function appendInlineFontFaces(root: Element): void {
+  const doc = root.ownerDocument;
+  const styleEl = root.querySelector('style');
+  if (!styleEl) return;
+  const extra: string[] = [];
+  for (const sheet of Array.from(document.styleSheets)) {
+    if (sheet.href) continue; // dom-to-svg already copied these
+    let rules: CSSRuleList;
+    try {
+      rules = sheet.cssRules;
+    } catch {
+      continue; // cross-origin sheet — unreadable, and not ours to embed
+    }
+    for (const rule of Array.from(rules)) {
+      if (rule.type !== CSSRule.FONT_FACE_RULE) continue;
+      const text = rule.cssText.replace(
+        /url\(\s*(['"]?)([^)'"]+)\1\s*\)/g,
+        (_m, q: string, u: string) => {
+          try {
+            return `url(${q}${new URL(u, document.baseURI).href}${q})`;
+          } catch {
+            return _m;
+          }
+        }
+      );
+      extra.push(text);
+    }
+  }
+  if (!extra.length) return;
+  void doc;
+  styleEl.textContent = `${styleEl.textContent ?? ''}\n${extra.join('\n')}`;
+}
+
 /** Parse the root viewBox (or width/height) out of a serialized SVG. */
 export function svgDimensions(svg: string): { width: number; height: number } | null {
   const doc = new DOMParser().parseFromString(svg, 'image/svg+xml');
@@ -280,6 +930,12 @@ const core = {
   svgForElement,
   svgDimensions,
   rasterizeSvg,
+  waitForCaptureAssets,
+  inlineCaptureResources,
+  stripChromeNodes,
+  applyPaintPolyfills,
+  dropRemoteRefs,
+  CAPTURE_HIDDEN_SELECTORS,
 };
 
 export type CaptureCore = typeof core;