domotion-svg 0.3.3 → 0.4.2

package/dist/animation/animator.d.ts

@@ -56,7 +56,18 @@ export interface TypingOverlay {
     speed?: number;
     /** Background color to mask placeholder text */
     bgColor?: string;
+    /**
+     * Field width in px. When set, the typed text WRAPS to this width like a
+     * browser textarea — breaking on spaces (char-breaking over-long words),
+     * advancing one line-height per wrapped line — instead of running off the
+     * right edge on a single line (DM-840). Omit for unbounded single-line text.
+     */
     bgWidth?: number;
+    /**
+     * Field height in px (used to size the placeholder mask). The mask grows
+     * beyond this if the wrapped text needs more lines, so the typed text always
+     * sits on a clean background.
+     */
     bgHeight?: number;
 }
 export interface TapOverlay {
@@ -155,6 +166,13 @@ export interface AnimationConfig {
      * them in every frame's local defs.
      */
     sharedDefs?: string;
+    /**
+     * DM-839: embedded-font `@font-face` rules collected once across all frames
+     * (the caller renders each frame with `includeEmbeddedFontCss=false` and
+     * passes the accumulated `getEmbeddedFontFaceCss()` here). Injected into the
+     * top-level `<style>` so the base64 font bytes appear once, not per frame.
+     */
+    fontFaceCss?: string;
     /**
      * Optional cursor / click overlay (DM-277). Renders a macOS-style cursor
      * moving along the script timeline with QuickTime-style click pulses.

package/dist/animation/animator.js

@@ -222,7 +222,7 @@ export function generateAnimatedSvg(config) {
     <clipPath id="viewport-clip"><rect width="${width}" height="${height}" /></clipPath>${sharedDefsMarkup}
   </defs>
   <style>
-    :root { --scene-dur: ${totalSec.toFixed(2)}s; }
+${config.fontFaceCss != null && config.fontFaceCss !== "" ? config.fontFaceCss + "\n" : ""}    :root { --scene-dur: ${totalSec.toFixed(2)}s; }
     .f { opacity: 0; visibility: hidden; }
     ${keyframes.join("\n")}${animationCss}${cullCss === "" ? "" : "\n" + cullCss}
   </style>
@@ -245,45 +245,119 @@ function transitionDuration(f) {
         return 0;
     return f.transition.duration;
 }
+/**
+ * Wrap `text` into lines no wider than `maxChars` monospace cells, the way a
+ * browser textarea does: break on spaces, char-break a word longer than the
+ * field, and honor explicit newlines. `maxChars === Infinity` → no wrap (one
+ * line per explicit-newline paragraph), preserving the pre-DM-840 behavior for
+ * overlays with no `bgWidth`. DM-840.
+ */
+function wrapTypingText(text, maxChars) {
+    const lines = [];
+    for (const paragraph of text.split("\n")) {
+        if (maxChars === Infinity) {
+            lines.push(paragraph);
+            continue;
+        }
+        if (paragraph === "") {
+            lines.push("");
+            continue;
+        }
+        let cur = "";
+        for (let word of paragraph.split(" ")) {
+            // A single word wider than the line char-breaks across lines.
+            while (word.length > maxChars) {
+                if (cur !== "") {
+                    lines.push(cur);
+                    cur = "";
+                }
+                lines.push(word.slice(0, maxChars));
+                word = word.slice(maxChars);
+            }
+            if (cur === "")
+                cur = word;
+            else if ((cur + " " + word).length <= maxChars)
+                cur += " " + word;
+            else {
+                lines.push(cur);
+                cur = word;
+            }
+        }
+        lines.push(cur);
+    }
+    return lines;
+}
 function renderTypingOverlay(overlay, frameIdx, frameStart, frameEnd, totalDuration, totalSec) {
     const delay = overlay.delay ?? 300;
     const speed = overlay.speed ?? 60;
     const fontSize = overlay.fontSize ?? 14;
-    const charWidth = fontSize * 0.6;
+    const charWidth = fontSize * 0.6; // monospace cell (overlay font is monospace)
+    const lineHeight = Math.round(fontSize * 1.35);
     const color = overlay.color ?? "#e6edf3";
     const typeStartMs = frameStart + delay;
+    const id = `t${frameIdx}`;
+    // DM-840: wrap to bgWidth so typed text behaves like a browser field
+    // (textarea) — wrapping to the next line instead of running off the right
+    // edge. Text starts at overlay.x and the bg rect starts at overlay.x-2 with
+    // width bgWidth, so the usable text width is bgWidth-4. With no bgWidth we
+    // keep the original single-line behavior (maxChars = Infinity).
+    const maxLineWidth = overlay.bgWidth != null ? overlay.bgWidth - 4 : Infinity;
+    const maxChars = maxLineWidth === Infinity ? Infinity : Math.max(1, Math.floor(maxLineWidth / charWidth));
+    const lines = wrapTypingText(overlay.text, maxChars);
+    const visibleChars = Math.max(1, lines.reduce((n, l) => n + l.length, 0));
+    const longestLineChars = lines.reduce((m, l) => Math.max(m, l.length), 0);
     const parts = [];
     const cssRules = [];
-    const id = `t${frameIdx}`;
-    // Background mask
+    // ── Timeline — all stops clamped to the frame so the overlay can't leak
+    // across the cut into the next frame. `naturalEnd` is when typing finishes
+    // at the requested speed; if that runs past the frame we compress the reveal
+    // to fit. The fully-typed text then HOLDS until just before the frame ends
+    // (the old hard 3 s cap cut long text off mid-type), then fades out.
+    const disappearGap = 150;
+    const naturalEndMs = typeStartMs + visibleChars * speed;
+    const textEndMs = Math.min(naturalEndMs, Math.max(typeStartMs + 1, frameEnd - disappearGap));
+    const effTypeDur = Math.max(1, textEndMs - typeStartMs);
+    const holdEndMs = Math.max(textEndMs, frameEnd - disappearGap);
+    const disappearMs = Math.min(frameEnd, holdEndMs + 100);
+    const textHeight = fontSize + 4;
+    const holdEndPct = pct(holdEndMs, totalDuration);
+    const disappearPct = pct(disappearMs, totalDuration);
+    // Background mask — grown to cover every wrapped line so the typed text
+    // always lands on a clean field instead of the captured placeholder.
     if (overlay.bgColor != null) {
-        const bgW = overlay.bgWidth ?? overlay.text.length * charWidth + 8;
-        const bgH = overlay.bgHeight ?? fontSize + 6;
+        const bgW = overlay.bgWidth ?? longestLineChars * charWidth + 8;
+        const bgH = Math.max(overlay.bgHeight ?? fontSize + 6, lines.length * lineHeight + 6);
         const bgStartPct = pct(typeStartMs, totalDuration);
-        const bgEndPct = pct(frameStart + overlay.text.length * speed + delay + 500, totalDuration);
         parts.push(`  <rect class="${id}-bg" x="${overlay.x - 2}" y="${overlay.y - fontSize + 2}" width="${bgW}" height="${bgH}" fill="${overlay.bgColor}" rx="2" />`);
         cssRules.push(`
-    @keyframes ${id}-bg { 0%, ${bgStartPct} { opacity: 0; } ${pct(typeStartMs + 50, totalDuration)} { opacity: 1; } ${bgEndPct}, 100% { opacity: 0; } }
+    @keyframes ${id}-bg { 0%, ${bgStartPct} { opacity: 0; } ${pct(typeStartMs + 50, totalDuration)} { opacity: 1; } ${holdEndPct} { opacity: 1; } ${disappearPct}, 100% { opacity: 0; } }
     .${id}-bg { animation: ${id}-bg ${totalSec.toFixed(2)}s infinite; }`);
     }
-    // Render full text with an animated clip that reveals characters one-by-one.
-    // The overlay must disappear by the time the frame ends — otherwise it'll
-    // leak across the cut boundary and overlap the next frame's content.
-    const textEndMs = typeStartMs + overlay.text.length * speed;
-    const holdEndMs = Math.min(frameStart + 3000, frameEnd);
-    const fullTextWidth = overlay.text.length * charWidth + 4;
-    const textHeight = fontSize + 4;
-    const clipId = `${id}-clip`;
-    // Clip rect animation: width grows from 0 to full text width
-    parts.push(`  <defs><clipPath id="${clipId}"><rect class="${id}-reveal" x="${overlay.x}" y="${overlay.y - fontSize}" width="0" height="${textHeight}" /></clipPath></defs>`);
-    parts.push(`  <text class="${id}-text" x="${overlay.x}" y="${overlay.y}" fill="${color}" font-size="${fontSize}" font-family="'SF Mono', Menlo, Monaco, monospace" clip-path="url(#${clipId})">${escapeXml(overlay.text)}</text>`);
+    // Typewriter reveal: one <text> per wrapped line, each unveiled by a
+    // width-growing clip during the slice of the type timeline when that line's
+    // characters are typed (line N starts after line N-1 finishes), so the caret
+    // advances down the field exactly as it would in the browser.
+    let cumChars = 0;
+    lines.forEach((line, li) => {
+        const lineY = overlay.y + li * lineHeight;
+        // +1 cell of slack so the last glyph never clips: the real monospace
+        // advance is slightly wider than the 0.6em estimate, and the trailing cell
+        // is where the caret would sit just after the typed character anyway.
+        const lineWidth = line.length * charWidth + charWidth;
+        const clipId = `${id}-clip${li}`;
+        const lineStartPct = pct(typeStartMs + (cumChars / visibleChars) * effTypeDur, totalDuration);
+        const lineEndPct = pct(typeStartMs + ((cumChars + line.length) / visibleChars) * effTypeDur, totalDuration);
+        cumChars += line.length;
+        parts.push(`  <defs><clipPath id="${clipId}"><rect class="${id}-rev${li}" x="${overlay.x}" y="${lineY - fontSize}" width="0" height="${textHeight}" /></clipPath></defs>`);
+        parts.push(`  <text class="${id}-text" x="${overlay.x}" y="${lineY}" fill="${color}" font-size="${fontSize}" font-family="'SF Mono', Menlo, Monaco, monospace" clip-path="url(#${clipId})">${escapeXml(line)}</text>`);
+        cssRules.push(`
+    @keyframes ${id}-rev${li} { 0%, ${lineStartPct} { width: 0; } ${lineEndPct} { width: ${lineWidth}px; } ${holdEndPct} { width: ${lineWidth}px; } ${disappearPct}, 100% { width: 0; } }
+    .${id}-rev${li} { animation: ${id}-rev${li} ${totalSec.toFixed(2)}s infinite; }`);
+    });
+    // Whole-overlay visibility — shared by every line's <text>.
     const typeStartPct = pct(typeStartMs, totalDuration);
-    const typeEndPct = pct(textEndMs, totalDuration);
-    const holdEndPct = pct(holdEndMs, totalDuration);
     cssRules.push(`
-    @keyframes ${id}-reveal { 0%, ${typeStartPct} { width: 0; } ${typeEndPct} { width: ${fullTextWidth}px; } ${holdEndPct} { width: ${fullTextWidth}px; } ${pct(holdEndMs + 100, totalDuration)}, 100% { width: 0; } }
-    .${id}-reveal { animation: ${id}-reveal ${totalSec.toFixed(2)}s infinite; }
-    @keyframes ${id}-vis { 0%, ${typeStartPct} { opacity: 0; } ${pct(typeStartMs + 30, totalDuration)} { opacity: 1; } ${holdEndPct} { opacity: 1; } ${pct(holdEndMs + 100, totalDuration)}, 100% { opacity: 0; } }
+    @keyframes ${id}-vis { 0%, ${typeStartPct} { opacity: 0; } ${pct(typeStartMs + 30, totalDuration)} { opacity: 1; } ${holdEndPct} { opacity: 1; } ${disappearPct}, 100% { opacity: 0; } }
     .${id}-text { animation: ${id}-vis ${totalSec.toFixed(2)}s infinite; }`);
     return { svgMarkup: parts.join("\n"), css: cssRules.join("") };
 }
@@ -444,7 +518,7 @@ function composeMergedSvg(config, frameTiming, totalSec) {
     <clipPath id="viewport-clip"><rect width="${width}" height="${height}" /></clipPath>${sharedDefsMarkup}
   </defs>
   <style>
-    :root { --scene-dur: ${totalSec.toFixed(2)}s; }
+${config.fontFaceCss != null && config.fontFaceCss !== "" ? config.fontFaceCss + "\n" : ""}    :root { --scene-dur: ${totalSec.toFixed(2)}s; }
 ${css}${animationCss}${cullCss === "" ? "" : "\n" + cullCss}
   </style>
   <g clip-path="url(#viewport-clip)">

package/dist/animation/animator.test.js

@@ -287,4 +287,60 @@ describe("animator", () => {
         // 50.000% boundary — frame 0 fades out and frame 1 fades in at the same instant.
         expect(svg).toMatch(/50\.000%/);
     });
+    // DM-840: a typing overlay over a bgWidth-constrained field must wrap like a
+    // browser textarea instead of running the text off the right edge.
+    describe("typing overlay text wrapping (DM-840)", () => {
+        const longText = "The quick brown fox jumps over the lazy dog repeatedly";
+        function typedSvg(opts) {
+            return generateAnimatedSvg({
+                width: 400, height: 200,
+                frames: [{
+                        svgContent: `<rect width="400" height="200" fill="#fff"/>`,
+                        duration: 4000,
+                        overlays: [{
+                                kind: "typing", text: longText, x: 20, y: 40,
+                                fontSize: 14, bgColor: "#fff", bgWidth: opts.bgWidth, bgHeight: 24,
+                            }],
+                    }],
+            });
+        }
+        // Pull the text content out of every `<text class="t0-text" …>…</text>`.
+        function typedLines(svg) {
+            return [...svg.matchAll(/<text class="t0-text"[^>]*>([^<]*)<\/text>/g)].map((m) => m[1]);
+        }
+        it("wraps the typed text into multiple lines bounded by bgWidth", () => {
+            const svg = typedSvg({ bgWidth: 120 });
+            const lines = typedLines(svg);
+            expect(lines.length).toBeGreaterThan(1);
+            // bgWidth 120, charWidth = 14*0.6 = 8.4 → usable (120-4)/8.4 ≈ 13 chars/line.
+            const maxChars = Math.floor((120 - 4) / (14 * 0.6));
+            for (const line of lines)
+                expect(line.length).toBeLessThanOrEqual(maxChars);
+            // No glyph escapes the field: each line's right edge stays within the bg.
+            expect(lines.join("")).not.toContain("  "); // wrap consumed the break spaces
+        });
+        it("advances y by a line-height per wrapped line", () => {
+            const svg = typedSvg({ bgWidth: 120 });
+            const ys = [...svg.matchAll(/<text class="t0-text" x="20" y="([\d.]+)"/g)].map((m) => Number(m[1]));
+            expect(ys.length).toBeGreaterThan(1);
+            // Strictly increasing baselines, ~lineHeight (round(14*1.35)=19) apart.
+            for (let i = 1; i < ys.length; i++) {
+                expect(ys[i]).toBeGreaterThan(ys[i - 1]);
+                expect(ys[i] - ys[i - 1]).toBe(19);
+            }
+        });
+        it("keeps single-line behavior when no bgWidth is given (backward compatible)", () => {
+            const svg = typedSvg({});
+            const lines = typedLines(svg);
+            expect(lines.length).toBe(1);
+            expect(lines[0]).toBe(longText);
+        });
+        it("grows the bg mask to cover all wrapped lines", () => {
+            const svg = typedSvg({ bgWidth: 120 });
+            const bg = /<rect class="t0-bg"[^>]*height="([\d.]+)"/.exec(svg);
+            expect(bg).not.toBeNull();
+            // More than the single-line bgHeight (24) since the text wraps to several lines.
+            expect(Number(bg[1])).toBeGreaterThan(24);
+        });
+    });
 });

package/dist/capture/index.js

@@ -10,7 +10,7 @@ import { elementTreeToSvg } from "../render/element-tree-to-svg.js";
 import { embedRemoteImages } from "./embed.js";
 import { resizeEmbeddedImages } from "../tree-ops/resize-embedded-images.js";
 import { rasterizeConicGradients } from "../render/conic-raster.js";
-import { registerLocalFontAlias, registerWebfont } from "../render/text-to-path.js";
+import { clearEmbeddedFonts, registerLocalFontAlias, registerWebfont } from "../render/text-to-path.js";
 import { CAPTURE_SCRIPT } from "./script.generated.js";
 import { rasterizeBitmapGlyphs } from "./emoji.js";
 import { _resetLastCaptureWarnings } from "./warnings.js";
@@ -141,6 +141,10 @@ export class DemoRecorder {
         // tree contains no conic content; otherwise the renderer (DM-550) emits
         // <pattern><image href="data:..."/></pattern> instead of dropping the layer.
         await rasterizeConicGradients(tree, { hiDPIFactor: this.embedRemoteImagesHiDPIFactor });
+        // DM-839: reset the embedded-font builder so this capture's `@font-face`
+        // block contains only its own fonts (the renderer repopulates it during
+        // elementTreeToSvg, which emits the CSS into this frame's <defs>).
+        clearEmbeddedFonts();
         return elementTreeToSvg(tree, this.width, this.height, idPrefix, true, this.embedRemoteImagesHiDPIFactor ?? 2);
     }
     /**
@@ -165,6 +169,7 @@ export class DemoRecorder {
         }
         // DM-549: rasterize conic-gradient layers — see captureCurrent above.
         await rasterizeConicGradients(tree, { hiDPIFactor: this.embedRemoteImagesHiDPIFactor });
+        clearEmbeddedFonts(); // DM-839: see captureCurrent
         const svgContent = elementTreeToSvg(tree, this.width, pageHeight, idPrefix, true, this.embedRemoteImagesHiDPIFactor ?? 2);
         return { svgContent, pageHeight };
     }

package/dist/cli/animate.js

@@ -8,7 +8,7 @@
 import { existsSync, readFileSync } from "node:fs";
 import { dirname, resolve } from "node:path";
 import { parseArgs } from "node:util";
-import { captureElementTree, clearWebfonts, composeScrollSvg, cullElementsOutsideViewBox, elementTreeToSvg, executeScrollPattern, generateAnimatedSvg, launchChromium, optimizeSvg, parseScrollPattern, } from "../index.js";
+import { captureElementTree, clearEmbeddedFonts, clearWebfonts, composeScrollSvg, cullElementsOutsideViewBox, elementTreeToSvg, executeScrollPattern, generateAnimatedSvg, getEmbeddedFontFaceCss, launchChromium, optimizeSvg, parseScrollPattern, } from "../index.js";
 import { attachWebfontTracker, discoverAndRegisterWebfonts } from "../capture/index.js";
 import { applyReadyWaits, isSvgzPath, loadInputIntoPage, makeLogger, resolveOutputPath, timed, writeOutput, } from "./common.js";
 export async function runAnimate(args, help) {
@@ -61,6 +61,11 @@ export async function runAnimate(args, help) {
         // same registry. Multiple frames declaring the same family register
         // multiple variants and the resolver picks the closest weight/style.
         clearWebfonts();
+        // DM-839: embedded-font is the default render mode. Reset the builder once
+        // here; each frame renders with includeEmbeddedFontCss=false (below) and we
+        // collect the deduped @font-face block once into the animator's top-level
+        // <style> after the loop — so the base64 font bytes appear once, not per frame.
+        clearEmbeddedFonts();
         // One tracker for the whole animate run — fonts fetched by any frame
         // get accumulated, and we deduplicate URLs inside discoverAndRegister.
         const tracker = attachWebfontTracker(page);
@@ -156,7 +161,7 @@ export async function runAnimate(args, help) {
                 const totalDurationMs = cfg.frames.reduce((sum, f) => sum + f.duration + (f.transition?.type === "cut" ? 0 : (f.transition?.duration ?? 300)), 0);
                 const result = cullElementsOutsideViewBox(tree, cfg.width, cfg.height, resolvedAnimations, frameStartMs, totalDurationMs);
                 frameCullCss = result.css;
-                svgContent = elementTreeToSvg(tree, cfg.width, cfg.height, `f${i}-`);
+                svgContent = elementTreeToSvg(tree, cfg.width, cfg.height, `f${i}-`, true, 2, false);
             }
             // Resolve SVG-kind overlays: read each `src` from disk, namespace its
             // ids, and replace with `innerSvg`. Other overlay kinds pass through
@@ -172,7 +177,10 @@ export async function runAnimate(args, help) {
             });
         }
         tracker.detach();
-        let svg = await timed(log, `Composed animated SVG (${cfg.frames.length} frames)`, () => Promise.resolve(generateAnimatedSvg({ width: cfg.width, height: cfg.height, frames })));
+        // DM-839: collect the embedded-font @font-face rules accumulated across all
+        // frames once, for the animator's top-level <style>.
+        const fontFaceCss = getEmbeddedFontFaceCss();
+        let svg = await timed(log, `Composed animated SVG (${cfg.frames.length} frames)`, () => Promise.resolve(generateAnimatedSvg({ width: cfg.width, height: cfg.height, frames, fontFaceCss })));
         // svgz is auto-detected from the output filename; implies --optimize
         // unless --no-optimize was passed.
         const outputArg = values.output ?? cfg.output;

package/dist/cli/capture.js

@@ -6,7 +6,7 @@
  * scroll machinery.
  */
 import { parseArgs } from "node:util";
-import { captureElementTree, clearWebfonts, composeScrollSvg, cullElementsOutsideViewBox, elementTreeToSvg, executeScrollPattern, launchChromium, logCaptureWarnings, optimizeSvg, parseScrollPattern, wrapSvg, } from "../index.js";
+import { captureElementTree, clearEmbeddedFonts, clearWebfonts, composeScrollSvg, cullElementsOutsideViewBox, elementTreeToSvg, executeScrollPattern, launchChromium, logCaptureWarnings, optimizeSvg, parseScrollPattern, wrapSvg, } from "../index.js";
 import { attachWebfontTracker, discoverAndRegisterWebfonts } from "../capture/index.js";
 import { applyReadyWaits, isSvgzPath, loadInputIntoPage, makeLogger, parseColorScheme, parseIntFlag, parseTuple, resolveOutputPath, timed, writeOutput, } from "./common.js";
 export async function runCapture(args, help) {
@@ -139,6 +139,7 @@ export async function runCapture(args, help) {
             // so this is a defense-in-depth pass for the position:fixed-descendant
             // escape cases where an off-viewport ancestor still gets captured.
             cullElementsOutsideViewBox(tree, clip[2], clip[3], undefined, 0, 1);
+            clearEmbeddedFonts(); // DM-839: reset embedded-font builder before this single-frame render
             const inner = elementTreeToSvg(tree, clip[2], clip[3]);
             svg = wrapSvg(inner, clip[2], clip[3]);
         }

package/dist/render/element-tree-to-svg.d.ts

@@ -67,7 +67,17 @@ includeGlyphDefs?: boolean,
  * `resizeEmbeddedImages` for the same tree, or the lookup misses and
  * the renderer falls back to the source-resolution data URI. Default 2.
  */
-hiDPIFactor?: number): string;
+hiDPIFactor?: number, 
+/**
+ * DM-839: when true, emit the embedded-font `@font-face` rules
+ * (`getEmbeddedFontFaceCss()`) as a `<style>` inside this frame's `<defs>`.
+ * Defaults to `includeGlyphDefs` — single-frame standalone producers
+ * (capture, CLI, the test harness) own their top-level defs and so should
+ * carry their font CSS here. Multi-frame producers (animator, scroll
+ * composer) pass `false` and collect the CSS once at the top level instead,
+ * so the (potentially large) base64 font bytes aren't duplicated per frame.
+ */
+includeEmbeddedFontCss?: boolean): string;
 /**
  * Rewrite a captured `<mask>` element's `outerHTML` so it can be safely
  * inlined in the output SVG's `<defs>`. The mask's own `id` becomes

package/dist/render/element-tree-to-svg.js

@@ -4,7 +4,7 @@
  * Uses Playwright to inspect DOM elements and recreate them as native SVG.
  */
 import { renderSingleLineText, renderMultiSegmentText, renderMultiLineText, renderInputText } from "./text.js";
-import { getGlyphDefs, measureLastGlyphRsb } from "./text-to-path.js";
+import { getEmbeddedFontFaceCss, getGlyphDefs, measureLastGlyphRsb } from "./text-to-path.js";
 import { renderFormControl } from "./form-controls.js";
 import { r, esc, stopFmt } from "./format.js";
 import { parseColor, colorStr, sameColor } from "./colors.js";
@@ -104,7 +104,17 @@ includeGlyphDefs = true,
  * `resizeEmbeddedImages` for the same tree, or the lookup misses and
  * the renderer falls back to the source-resolution data URI. Default 2.
  */
-hiDPIFactor = 2) {
+hiDPIFactor = 2, 
+/**
+ * DM-839: when true, emit the embedded-font `@font-face` rules
+ * (`getEmbeddedFontFaceCss()`) as a `<style>` inside this frame's `<defs>`.
+ * Defaults to `includeGlyphDefs` — single-frame standalone producers
+ * (capture, CLI, the test harness) own their top-level defs and so should
+ * carry their font CSS here. Multi-frame producers (animator, scroll
+ * composer) pass `false` and collect the CSS once at the top level instead,
+ * so the (potentially large) base64 font bytes aren't duplicated per frame.
+ */
+includeEmbeddedFontCss = includeGlyphDefs) {
     setActiveHiDPIFactor(hiDPIFactor);
     const svgParts = [];
     const defsParts = [];
@@ -2956,7 +2966,13 @@ hiDPIFactor = 2) {
     // `getEmbeddedFontFaceCss()` themselves once at the top level (see how
     // `composeScrollSvg` injects it into the outer <style>).
     const glyphDefsMarkup = includeGlyphDefs ? getGlyphDefs() : "";
-    const allDefs = defsParts.join("") + glyphDefsMarkup;
+    // DM-839: embedded-font `@font-face` rules for the text runs rendered above
+    // (empty in paths mode, or when no run was embeddable). A `<style>` inside
+    // `<defs>` is valid SVG. Single-frame producers emit it here; multi-frame
+    // producers pass includeEmbeddedFontCss=false and inject once at the top.
+    const embeddedFontCss = includeEmbeddedFontCss ? getEmbeddedFontFaceCss() : "";
+    const fontStyleMarkup = embeddedFontCss !== "" ? `<style>${embeddedFontCss}</style>` : "";
+    const allDefs = defsParts.join("") + glyphDefsMarkup + fontStyleMarkup;
     const defs = allDefs !== "" ? `  <defs>${allDefs}</defs>\n` : "";
     return defs + svgParts.join("\n");
 }

package/dist/render/index.d.ts

@@ -1,2 +1,2 @@
 export { elementTreeToSvg, wrapSvg, } from "./element-tree-to-svg.js";
-export { getGlyphDefs, clearGlyphDefs, registerWebfont, clearWebfonts, } from "./text-to-path.js";
+export { getGlyphDefs, clearGlyphDefs, registerWebfont, clearWebfonts, setRenderTextMode, getRenderTextMode, clearEmbeddedFonts, getEmbeddedFontFaceCss, type RenderTextMode, } from "./text-to-path.js";

package/dist/render/index.js

@@ -1,4 +1,8 @@
 // Render-side public surface. Pure functions that take a captured element
 // tree (or fragments of one) and emit SVG markup.
 export { elementTreeToSvg, wrapSvg, } from "./element-tree-to-svg.js";
-export { getGlyphDefs, clearGlyphDefs, registerWebfont, clearWebfonts, } from "./text-to-path.js";
+export { getGlyphDefs, clearGlyphDefs, registerWebfont, clearWebfonts, 
+// DM-839: embedded-font is the default render mode; expose the controls so
+// consumers can opt back into per-pixel-faithful `paths` mode and manage the
+// embedded-font lifecycle.
+setRenderTextMode, getRenderTextMode, clearEmbeddedFonts, getEmbeddedFontFaceCss, } from "./text-to-path.js";

package/dist/render/text-to-path.d.ts

@@ -109,6 +109,12 @@ export declare function __pickWebfontVariantMetaForCodepointForTest(family: stri
 /** Drop all registered webfonts. Call at the start of a fresh capture run. */
 export declare function clearWebfonts(): void;
 export declare function registerLocalFontAlias(family: string, resolvedKey: string, weight?: number, italic?: boolean): void;
+/** Test-only window into the platform path resolver (DM-258). */
+export declare function __resolveFontSpecForTest(key: string): {
+    path: string;
+    postscriptName?: string;
+    extractor?: string;
+} | null;
 /**
  * Ordered list of fallback font keys to try when the primary font lacks a
  * glyph for `codepoint`. Caller iterates the chain and picks the first font
@@ -139,7 +145,27 @@ export declare function registerLocalFontAlias(family: string, resolvedKey: stri
  *   "ja" / "ja-JP"    → hiragino-jp (PingFang has no JP subfont on macOS)
  */
 export declare function pingfangKeyForLang(lang: string | undefined): string | null;
+/**
+ * Linux fallback chain (DM-259) — calibrated to what Chromium-on-Linux paints
+ * in the Playwright `*-noble` CI image, measured via CDP
+ * `CSS.getPlatformFontsForNode` (tools/probe-fallbacks-linux.mjs). Returns
+ * logical keys that `LINUX_FONT_PATHS` maps to the image's real faces
+ * (Liberation / WenQuanYi / FreeFont / Loma / IPAGothic). As on macOS, the
+ * caller has already tried the primary font, so what reaches here is the
+ * residue the primary lacks. The comment after each branch names the face the
+ * probe showed Chromium using for that block.
+ */
+export declare function linuxFallbackChain(codepoint: number, primaryKey?: string, _lang?: string): string[];
 export declare function fallbackFontChain(codepoint: number, primaryKey?: string, lang?: string): string[];
+/**
+ * macOS (CoreText) fallback chain — reverse-engineered from Chromium-on-macOS
+ * painted widths (DM-241 / DM-256 / DM-257 / …). Exported so the macOS-
+ * calibration unit tests assert it directly: the suite runs on Linux in CI,
+ * where `fallbackFontChain` dispatches to `linuxFallbackChain`, so those tests
+ * must call this function (not `fallbackFontChain`) to validate macOS routing
+ * regardless of the host platform (DM-842).
+ */
+export declare function darwinFallbackChain(codepoint: number, primaryKey?: string, lang?: string): string[];
 /** @deprecated Single-key wrapper for back-compat — prefer `fallbackFontChain`. */
 export declare function fallbackFontKey(codepoint: number): string | null;
 export declare function resolveFontKey(fontFamily: string): string;