domotion-svg 0.1.1

package/src/index.ts

@@ -0,0 +1,12 @@
+export { captureElementTree, captureElementTreeWithWarnings, elementTreeToSvg, wrapSvg, rootSvgColorSchemeAttr, transparentRootBgRect, getLastCaptureWarnings, logCaptureWarnings, embedRemoteImages, embedResizedDataUri } from "./dom-to-svg.js";
+export { resizeEmbeddedImages } from "./resize-embedded-images.js";
+export type { ResizeEmbeddedImagesOptions } from "./resize-embedded-images.js";
+export type { CapturedElement, CaptureWarning } from "./dom-to-svg.js";
+export { generateAnimatedSvg } from "./animator.js";
+export type { AnimationConfig, AnimationFrame, Overlay, TypingOverlay, TapOverlay, SvgOverlay, IntraFrameAnimation } from "./animator.js";
+export type { CursorOverlay, CursorEvent, CursorMoveEvent, CursorClickEvent, CursorShowEvent, CursorHideEvent, CursorStyle, SelectorResolver } from "./cursor-overlay.js";
+export { DemoRecorder, launchChromium } from "./capture.js";
+export type { CaptureOptions } from "./capture.js";
+export { optimizeSvg } from "./optimize.js";
+export { getGlyphDefs, clearGlyphDefs, registerWebfont, clearWebfonts } from "./text-to-path.js";
+export { discoverAndRegisterWebfonts, attachWebfontTracker } from "./capture.js";

package/src/kerf-jsx-augmentation.d.ts

@@ -0,0 +1,36 @@
+// kerfjs 0.5.0 ships a typed JSX `IntrinsicElements` table, but the bundled
+// type declarations have a self-referential interface bug at
+// `node_modules/kerfjs/dist/jsx-runtime.d.ts:784`:
+//
+//   declare namespace JSX {
+//     interface IntrinsicElements extends IntrinsicElements {}
+//   }
+//
+// The `extends IntrinsicElements` resolves to the local (just-being-declared)
+// JSX.IntrinsicElements, not the module-scope one with the typed tag table.
+// Result: `JSX.IntrinsicElements` is empty and every `<div>`, `<span>`, etc.
+// fails to type-check with `Property 'div' does not exist on type
+// 'JSX.IntrinsicElements'`.
+//
+// This declaration merging adds a permissive index signature that accepts
+// any tag with any props — restoring the pre-0.5.0 catch-all behaviour. We
+// lose 0.5.0's typed-tag benefit (typos like `<dvi>` no longer fail to
+// compile), but the runtime is unaffected and we unblock the upgrade.
+//
+// Remove this file when kerfjs publishes a fix (rename the outer interface
+// so the JSX namespace's `extends` resolves correctly, or drop the
+// `extends` and explicitly list the tag table inside the namespace).
+
+// Importing from the module first registers it for augmentation. Without
+// this, the `declare module` block is treated as a NEW module declaration
+// and clobbers the original `kerfjs/jsx-runtime` exports (TS2305: 'SafeHtml'
+// has no exported member).
+import "kerfjs/jsx-runtime";
+
+declare module "kerfjs/jsx-runtime" {
+  namespace JSX {
+    interface IntrinsicElements {
+      [tag: string]: any;
+    }
+  }
+}

package/src/kerfjs-imports.test.tsx

@@ -0,0 +1,45 @@
+import { describe, expect, it } from "vitest";
+import { Fragment, raw, SafeHtml } from "kerfjs";
+import { SafeHtml as RuntimeSafeHtml } from "kerfjs/jsx-runtime";
+
+// Regression test for DM-533: kerfjs <= 0.1.2 shipped two independent
+// `SafeHtml` class definitions — one in the `"kerfjs"` barrel and one in
+// `"kerfjs/jsx-runtime"`. The auto JSX runtime resolves <jsx> calls via the
+// jsx-runtime entry, so a `raw()` value imported from the barrel failed the
+// `instanceof SafeHtml` check inside `renderChildren` and the renderer threw.
+//
+// 0.2.0 fixes this by emitting a shared chunk; both entries re-export the same
+// class. These tests guard that contract — if a future kerfjs upgrade
+// regresses the duplication, JSX rendering breaks across all of Domotion's
+// .tsx files (tests/, site/) and these tests will fail loudly here instead.
+
+describe("kerfjs barrel and jsx-runtime share SafeHtml", () => {
+  it("exports the same SafeHtml class from both entry points", () => {
+    expect(SafeHtml).toBe(RuntimeSafeHtml);
+  });
+
+  it("renders raw() imported from the barrel inside JSX without throwing", () => {
+    const html = (<div>{raw("<b>hi</b>")}</div>).toString();
+    expect(html).toBe("<div><b>hi</b></div>");
+  });
+
+  it("auto-escapes string children", () => {
+    const html = (<p>{"<script>x</script>"}</p>).toString();
+    expect(html).toBe("<p>&lt;script&gt;x&lt;/script&gt;</p>");
+  });
+
+  // Regression test for DM-534: kerfjs 0.2.0's `"kerfjs"` barrel re-exported
+  // `SafeHtml`/`isSafeHtml`/`raw` from the shared chunk but omitted `Fragment`,
+  // so `<Fragment>…</Fragment>` rendered as `<undefined>…</undefined>`. Fixed
+  // upstream in 0.2.1 by adding `Fragment` to the barrel re-export.
+  it("exports Fragment from the barrel and renders it as a transparent wrapper", () => {
+    expect(Fragment).toBeDefined();
+    const html = (
+      <Fragment>
+        <span>a</span>
+        <span>b</span>
+      </Fragment>
+    ).toString();
+    expect(html).toBe("<span>a</span><span>b</span>");
+  });
+});

package/src/mask.test.ts

@@ -0,0 +1,274 @@
+import { describe, expect, it } from "vitest";
+import { buildMaskDef, positionFragmentMaskDef, rewriteFragmentMaskDef } from "./dom-to-svg.js";
+
+// Locks the SVG <mask> emission for the cases exercised by the html-test
+// suite's 23-mask.html fixture (DM-395).
+
+describe("buildMaskDef — single-layer gradient masks (DM-395)", () => {
+  it("linear-gradient mask renders as mask-type=alpha with absolute-coord gradient", () => {
+    const r = buildMaskDef("m", "linear-gradient(to right, black, transparent)",
+      0, 0, 180, 120, "match-source", "auto", "0% 0%", "repeat", "add");
+    expect(r.def).toContain('mask-type="alpha"');
+    // userSpaceOnUse so the gradient angle isn't distorted by the box aspect
+    // ratio on non-square elements (DM-395).
+    expect(r.def).toContain('gradientUnits="userSpaceOnUse"');
+    expect(r.def).toContain("<linearGradient");
+    expect(r.def).toContain('width="180"');
+    expect(r.def).toContain('height="120"');
+  });
+
+  it("45deg gradient on a non-square box uses real-px endpoints (DM-395)", () => {
+    // CSS spec: gradient line length L = |W·sin α| + |H·cos α| with endpoints
+    // at center ± L/2 along the angle. For 45° on a 180×120 box: L ≈ 212.13,
+    // start at (15, 135), end at (165, -15) relative to the box's top-left.
+    // Element offset elX=elY=0 here, so absolute coords are the same.
+    const r = buildMaskDef("m", "linear-gradient(45deg, black, transparent)",
+      0, 0, 180, 120, "match-source", "auto", "0% 0%", "repeat", "add");
+    expect(r.def).toContain('x1="15"');
+    expect(r.def).toContain('y1="135"');
+    expect(r.def).toContain('x2="165"');
+    expect(r.def).toContain('y2="-15"');
+  });
+
+  it("radial-gradient mask centers correctly when sized + positioned", () => {
+    // mask-image: radial-gradient(circle, black 40%, transparent 40%);
+    // mask-size: 80px; mask-position: 25% 25%
+    // Element at (680, 240); mask should be at gx=680+25, gy=240+10, 80x80.
+    const r = buildMaskDef("m", "radial-gradient(circle, black 40%, transparent 40%)",
+      680, 240, 180, 120, "match-source", "80px", "25% 25%", "no-repeat", "add");
+    expect(r.def).toContain('x="705"');
+    expect(r.def).toContain('y="250"');
+    expect(r.def).toContain('width="80"');
+    expect(r.def).toContain('height="80"');
+    // Center of the 80x80 mask box: cx=745, cy=290.
+    expect(r.def).toMatch(/cx="745"/);
+    expect(r.def).toMatch(/cy="290"/);
+    // farthest-corner radius = sqrt(40^2 + 40^2) ≈ 56.5685.
+    expect(r.def).toMatch(/r="56\.5685"/);
+  });
+
+  it("mask-mode: alpha emits mask-type='alpha'", () => {
+    const r = buildMaskDef("m", "linear-gradient(45deg, black, transparent)",
+      0, 0, 180, 120, "alpha", "auto", "0% 0%", "repeat", "add");
+    expect(r.def).toContain('mask-type="alpha"');
+  });
+
+  it("mask-mode: luminance emits mask-type='luminance'", () => {
+    const r = buildMaskDef("m", "linear-gradient(45deg, white, black)",
+      0, 0, 180, 120, "luminance", "auto", "0% 0%", "repeat", "add");
+    expect(r.def).toContain('mask-type="luminance"');
+  });
+
+  it("match-source resolves to alpha for gradient sources (the common case)", () => {
+    // Per the buildMaskDef comment block: 'match-source' is alpha for
+    // gradients and bitmap-sourced url() masks. Only explicit 'luminance'
+    // opts into luminance interpretation.
+    const r = buildMaskDef("m", "radial-gradient(circle, black, transparent)",
+      0, 0, 100, 100, "match-source", "auto", "0% 0%", "no-repeat", "add");
+    expect(r.def).toContain('mask-type="alpha"');
+  });
+});
+
+describe("buildMaskDef — composite (DM-395)", () => {
+  it("composite=add (default) flattens layers into one <mask>", () => {
+    const r = buildMaskDef("m",
+      "linear-gradient(to right, black, transparent), radial-gradient(circle, black, transparent)",
+      0, 0, 180, 120, "match-source", "auto", "0% 0%", "no-repeat", "add");
+    // One <mask> with two gradient defs + two filled rects (additive).
+    expect((r.def.match(/<mask\s/g) ?? []).length).toBe(1);
+    expect((r.def.match(/<linearGradient/g) ?? []).length).toBe(1);
+    expect((r.def.match(/<radialGradient/g) ?? []).length).toBe(1);
+  });
+
+  it("composite=intersect chains layers via mask=url(#inner) refs", () => {
+    // Mirrors the 'composite: intersect' fixture case:
+    // mask-image: linear-gradient(to right, black, transparent), radial-gradient(circle, black 50%, transparent 50%);
+    // mask-composite: intersect, intersect;
+    // mask-size: auto, 100px;
+    // mask-position: 0 0, center;
+    const r = buildMaskDef("m",
+      "linear-gradient(to right, black, transparent), radial-gradient(circle, black 50%, transparent 50%)",
+      0, 0, 180, 120, "match-source", "auto, 100px", "0px 0px, 50% 50%",
+      "no-repeat, no-repeat", "intersect, intersect");
+    // Two distinct mask elements: outer 'm' + inner 'm i1'.
+    expect((r.def.match(/<mask\s/g) ?? []).length).toBe(2);
+    expect(r.def).toContain('id="m"');
+    expect(r.def).toContain('id="mi1"');
+    // The outer mask's painted rect should reference the inner mask.
+    expect(r.def).toMatch(/fill="url\(#mg0\)"\s*mask="url\(#mi1\)"/);
+  });
+});
+
+describe("rewriteFragmentMaskDef — DM-493 same-document mask fragment refs", () => {
+  it("rewrites the outer mask id to the requested output id", () => {
+    const out = rewriteFragmentMaskDef(
+      `<mask id="m1"><rect width="50" height="50" fill="white"/></mask>`,
+      "f0-mkfrag0",
+      "f0-",
+    );
+    expect(out).toContain('id="f0-mkfrag0"');
+    expect(out).not.toContain('id="m1"');
+  });
+
+  it("rewrites nested ids with the idPrefix to keep them unique across captures", () => {
+    const out = rewriteFragmentMaskDef(
+      `<mask id="m1"><linearGradient id="g1"><stop offset="0" stop-color="white"/><stop offset="1" stop-color="black"/></linearGradient><rect fill="url(#g1)" width="50" height="50"/></mask>`,
+      "f0-mkfrag0",
+      "f0-",
+    );
+    expect(out).toContain('id="f0-mkfrag0"');
+    expect(out).toContain('id="f0-fragid-g1"');
+    expect(out).toContain('fill="url(#f0-fragid-g1)"');
+    expect(out).not.toContain('id="g1"');
+    expect(out).not.toContain("url(#g1)");
+  });
+
+  it("rewrites href / xlink:href fragment refs (transitive <use> targets)", () => {
+    const out = rewriteFragmentMaskDef(
+      `<mask id="m1"><defs><circle id="dot" r="10"/></defs><use href="#dot" x="20" y="20"/></mask>`,
+      "f1-mkfrag2",
+      "f1-",
+    );
+    expect(out).toContain('id="f1-mkfrag2"');
+    expect(out).toContain('id="f1-fragid-dot"');
+    expect(out).toContain('href="#f1-fragid-dot"');
+    expect(out).not.toContain("#dot\"");
+  });
+
+  it("does not touch fragment refs that point at ids outside the captured subtree", () => {
+    // External-to-mask url(#somethingElse) should pass through unchanged so
+    // the renderer doesn't accidentally rewrite refs we didn't define.
+    const out = rewriteFragmentMaskDef(
+      `<mask id="m1"><rect fill="url(#externalGrad)" width="50" height="50"/></mask>`,
+      "f0-mkfrag0",
+      "f0-",
+    );
+    expect(out).toContain("url(#externalGrad)");
+  });
+
+  it("multiple references to the same captured fragment share a single output id (deduped)", () => {
+    // Sanity check the rewrite is stable: invoking twice with the same
+    // outputId yields identical markup. Stable mapping is what lets the
+    // renderer dedupe when many elements reference the same fragment.
+    const a = rewriteFragmentMaskDef(`<mask id="m1"><rect width="10" height="10" fill="white"/></mask>`, "f-mkfrag0", "f-");
+    const b = rewriteFragmentMaskDef(`<mask id="m1"><rect width="10" height="10" fill="white"/></mask>`, "f-mkfrag0", "f-");
+    expect(a).toBe(b);
+  });
+});
+
+describe("positionFragmentMaskDef — DM-493 per-element mask placement", () => {
+  it("translates the mask content into the masked element's user-space", () => {
+    // CSS mask-image positions the mask source at the masked element's
+    // content-box origin. The captured <mask> has its content in its own
+    // local coordinates; we wrap the children in a translate(elX, elY) and
+    // rewrite the mask's own bounds to match the masked element's box.
+    const out = positionFragmentMaskDef(
+      `<mask id="mkfrag0" maskUnits="userSpaceOnUse" x="0" y="0" width="100" height="100"><rect x="0" y="0" width="100" height="100" fill="white"/></mask>`,
+      236, 20, 200, 120,
+    );
+    expect(out).toContain('x="236"');
+    expect(out).toContain('y="20"');
+    expect(out).toContain('width="200"');
+    expect(out).toContain('height="120"');
+    expect(out).toContain("transform=\"translate(236, 20)\"");
+    // Original captured bounds (x=0/y=0/width=100/height=100) should not
+    // remain on the outer mask — those were the source-mask bounds, not the
+    // target element's.
+    expect(out).not.toMatch(/<mask[^>]*\sx="0"/);
+  });
+
+  it("forces maskUnits=userSpaceOnUse so the rewritten coords are interpreted absolutely", () => {
+    const out = positionFragmentMaskDef(
+      `<mask id="m" maskUnits="objectBoundingBox" x="0" y="0" width="1" height="1"><rect x="0.1" y="0.1" width="0.8" height="0.8" fill="white"/></mask>`,
+      0, 0, 200, 120,
+    );
+    expect(out).toContain('maskUnits="userSpaceOnUse"');
+    expect(out).not.toContain('maskUnits="objectBoundingBox"');
+  });
+});
+
+describe("buildMaskDef — url() sources (DM-395)", () => {
+  it("SVG url() mask emits an empty mask (forceHide), matching Chrome's observed behavior", () => {
+    // Chrome's SVG mask source resolves to luminance and most icon SVGs
+    // compute near-zero luminance over the tile, so the element is hidden.
+    // We deliberately emit an empty mask to reproduce that.
+    const r = buildMaskDef("m", 'url("assets/img-orange.svg")',
+      0, 0, 180, 120, "match-source", "contain", "50% 50%", "no-repeat", "add");
+    expect(r.def).toMatch(/<mask[^>]*><\/mask>/);
+    // Mask exists (so the element gets force-hidden).
+    expect(r.def).not.toBe("");
+  });
+});
+
+describe("buildMaskDef — element() paint refs (DM-494)", () => {
+  function makeRaster(id: string, w = 64, h = 64) {
+    return new Map([[id, {
+      id, rid: "mr0", width: w, height: h,
+      dataUri: "data:image/png;base64,iVBORw0KGgo=",
+      rect: { x: 0, y: 0, width: w, height: h },
+    }]]);
+  }
+
+  it("element() ref emits an <image> inside the <mask> with mask-type=luminance under match-source", () => {
+    // CSS Masking spec: mask-mode: match-source resolves to luminance for
+    // element() paint references — the painted RGB drives mask alpha.
+    const rasters = makeRaster("src", 200, 100);
+    const r = buildMaskDef("m", "element(#src)",
+      0, 0, 200, 100, "match-source", "auto", "0% 0%", "no-repeat", "add", rasters);
+    expect(r.def).toContain('mask-type="luminance"');
+    expect(r.def).toContain('<image href="data:image/png;base64,iVBORw0KGgo="');
+    expect(r.def).toContain('width="200"');
+    expect(r.def).toContain('height="100"');
+  });
+
+  it("element() with explicit mask-mode: alpha respects the author override", () => {
+    const rasters = makeRaster("src", 200, 100);
+    const r = buildMaskDef("m", "element(#src)",
+      0, 0, 200, 100, "alpha", "auto", "0% 0%", "no-repeat", "add", rasters);
+    expect(r.def).toContain('mask-type="alpha"');
+  });
+
+  it("element() with mask-size: contain fits inside the consumer box (preserveAspectRatio meet)", () => {
+    // raster intrinsic 200x100; consumer 100x100. contain → fits = 100x50.
+    const rasters = makeRaster("src", 200, 100);
+    const r = buildMaskDef("m", "element(#src)",
+      0, 0, 100, 100, "match-source", "contain", "0% 0%", "no-repeat", "add", rasters);
+    expect(r.def).toContain('width="100"');
+    expect(r.def).toContain('height="50"');
+    expect(r.def).toContain('preserveAspectRatio="xMidYMid meet"');
+  });
+
+  it("element() with mask-size: cover fills the consumer (preserveAspectRatio slice)", () => {
+    // raster 100x200; consumer 100x100. cover → 100x200 (height fills).
+    const rasters = makeRaster("src", 100, 200);
+    const r = buildMaskDef("m", "element(#src)",
+      0, 0, 100, 100, "match-source", "cover", "0% 0%", "no-repeat", "add", rasters);
+    expect(r.def).toContain('preserveAspectRatio="xMidYMid slice"');
+  });
+
+  it("element() with no resolved raster (no dataUri) skips emission", () => {
+    const empty = new Map<string, import("./dom-to-svg.js").MaskRasterRef>();
+    const r = buildMaskDef("m", "element(#src)",
+      0, 0, 200, 100, "match-source", "auto", "0% 0%", "no-repeat", "add", empty);
+    expect(r.def).toBe("");
+  });
+
+  it("element() ref with elementRasters undefined skips emission (legacy callers)", () => {
+    const r = buildMaskDef("m", "element(#src)",
+      0, 0, 200, 100, "match-source", "auto", "0% 0%", "no-repeat", "add");
+    expect(r.def).toBe("");
+  });
+
+  it("mixed gradient + element() layers — luminance wins under match-source", () => {
+    const rasters = makeRaster("src", 64, 64);
+    const r = buildMaskDef("m",
+      "linear-gradient(black, transparent), element(#src)",
+      0, 0, 200, 100, "match-source", "auto, auto", "0% 0%, 0% 0%", "no-repeat, no-repeat", "add",
+      rasters);
+    // Any element() layer in match-source mode → mask-type=luminance.
+    expect(r.def).toContain('mask-type="luminance"');
+    // Both layers contribute content.
+    expect(r.def).toContain("<linearGradient");
+    expect(r.def).toContain('<image href="data:image/png');
+  });
+});

package/src/optimize.ts

@@ -0,0 +1,34 @@
+/**
+ * SVG Post-Processing Optimizer
+ *
+ * Uses SVGO to optimize path data and transforms without altering structure.
+ * Particularly effective for path-mode text (shortens glyph coordinates, converts
+ * to relative commands, reduces decimal precision).
+ */
+
+import { optimize, type PluginConfig } from "svgo";
+
+/**
+ * Optimize an SVG string. Safe for all rendering modes — only compresses
+ * path data, transforms, and whitespace. Does not remove elements or IDs.
+ */
+export function optimizeSvg(svg: string): string {
+  // svgo 4.x's PluginConfig discriminated union is too narrow for
+  // `makeArcs: false` (the type expects a {threshold, tolerance} object even
+  // though svgo accepts `false` at runtime to disable arc conversion).
+  // Cast the convertPathData entry so the rest of the plugin list still
+  // type-checks.
+  const plugins: PluginConfig[] = [
+    { name: "convertPathData", params: {
+      floatPrecision: 1,
+      transformPrecision: 3,
+      makeArcs: false,
+    } } as PluginConfig,
+    "convertTransform",
+    "minifyStyles",
+    "removeComments",
+    "removeEmptyAttrs",
+  ];
+  const result = optimize(svg, { multipass: true, plugins });
+  return result.data;
+}

package/src/preserve-aspect-ratio.test.ts

@@ -0,0 +1,49 @@
+import { describe, expect, it } from "vitest";
+import { preserveAspectRatioFor } from "./dom-to-svg.js";
+
+describe("preserveAspectRatioFor — CSS object-fit/object-position → SVG preserveAspectRatio (DM-472)", () => {
+  it("object-fit:fill → none (stretch both axes)", () => {
+    expect(preserveAspectRatioFor("fill", "50% 50%")).toBe("none");
+  });
+
+  it("object-fit defaulted to fill when undefined → none", () => {
+    expect(preserveAspectRatioFor(undefined, undefined)).toBe("none");
+  });
+
+  it("object-fit:none → none (renderer special-cases via intrinsic-size path)", () => {
+    expect(preserveAspectRatioFor("none", "50% 50%")).toBe("none");
+  });
+
+  it("object-fit:contain default position → xMidYMid meet", () => {
+    expect(preserveAspectRatioFor("contain", "50% 50%")).toBe("xMidYMid meet");
+  });
+
+  it("object-fit:cover default position → xMidYMid slice", () => {
+    expect(preserveAspectRatioFor("cover", "50% 50%")).toBe("xMidYMid slice");
+  });
+
+  it("object-fit:scale-down treated as contain", () => {
+    expect(preserveAspectRatioFor("scale-down", "50% 50%")).toBe("xMidYMid meet");
+  });
+
+  it("object-position:left top → xMinYMin alignment", () => {
+    expect(preserveAspectRatioFor("contain", "left top")).toBe("xMinYMin meet");
+    expect(preserveAspectRatioFor("cover", "left top")).toBe("xMinYMin slice");
+  });
+
+  it("object-position:right bottom → xMaxYMax alignment", () => {
+    expect(preserveAspectRatioFor("contain", "right bottom")).toBe("xMaxYMax meet");
+  });
+
+  it("object-position:0% 0% → xMin alignment (same as left top)", () => {
+    expect(preserveAspectRatioFor("contain", "0% 0%")).toBe("xMinYMin meet");
+  });
+
+  it("object-position:100% 100% → xMax alignment", () => {
+    expect(preserveAspectRatioFor("cover", "100% 100%")).toBe("xMaxYMax slice");
+  });
+
+  it("undefined object-position defaults to center (xMidYMid)", () => {
+    expect(preserveAspectRatioFor("contain", undefined)).toBe("xMidYMid meet");
+  });
+});