nodality 1.3.5 → 1.3.7

package/lib/element-mapper.js

@@ -1,5 +1,5 @@
 /*!
- * nodality v1.3.5
+ * nodality v1.3.7
  * (c) 2026 Filip Vabrousek
  * License: MIT
  */
@@ -125,9 +125,35 @@ const navEntry = (i) =>
 // The failure this guards is silent: a composite handed content in the slot it
 // does not read emits its placeholder template, so the page renders, nothing
 // throws, and the content is simply gone.
+// Kept byte-equal to `CONTENT_SLOT` in lib/validate-nodes.js, which cannot be
+// imported here: this file pulls in every layout component and therefore a DOM,
+// and the validator has to run in a bare Node process. Two copies is the price
+// of that, and they had already drifted -- `stack` was declared here and not
+// there -- so a unit test now pins them equal rather than trusting the comment.
+//
+// The per-type descriptions below are read by scripts/generate-schema.mjs. They
+// live here because the mapper is what decides how a slot is read; before they
+// existed the generator keyed descriptions by parameter NAME across every file
+// it scanned, first writer winning, so the picker's `items` documentation was
+// served for `cards`, `nav`, `sideNav`, `table` and `ulist` as well.
+// Names whose meaning is decided by the element type, not by whichever file
+// happened to document them first. See the SCOPED note in generate-schema.mjs.
+//@scoped items
+//@scoped type
+//@scoped id
+//@ type: The element type, which selects the mapper that builds it -- "h1", "cards", "form", and so on.
+//@ id: This element's DOM id. Also what a design node's `target` names, and what `parse` recovers an element by.
+//@ cards.items: The cards. Each entry is either a data object -- { title, link, img } -- or an ARRAY of element specs, which renders as one card containing them.
+//@ nav.items: The links, each `{ title, link }` -- or a plain string.
+//@ sideNav.items: The links, each `{ title, link }` -- or a plain string.
+//@ table.items: The rows. Each entry is a `{ title, link }` or `{ text, url }` data object, a `[value, text]` pair, or an element spec.
+//@ ulist.items: The list entries, each an element spec -- `{ type, ... }` -- or a plain string.
+//@ dropdown.items: The choices, each a `[value, text]` pair -- or a plain string used as both.
+//@ radio.items: The choices, each a plain string.
 const CONTENT_SLOT = Object.freeze({
     cards: "items", table: "items", ulist: "items",
     nav: "items", sideNav: "items",
+    dropdown: "items", picker: "items", radio: "items",
     row: "children", form: "children", stack: "children", wrap: "children",
 });
 
@@ -295,6 +321,17 @@ class ElementMapper { // 22:09:58 04/11/2024
        // return new Text("Hello").set({size: "S3"});
 
         return new FlexRow().set({
+                         // Everything the author declared. Without it a row's
+                         // options were the node lookups alone, every one of
+                         // them `undefined` when no node targets this element,
+                         // so FlexRow.toCode() -- which correctly strips
+                         // undefined -- emitted `.set({})` and the emitted
+                         // source carried nothing. The empty object was the
+                         // symptom; this is the cause.
+                         ...this.elOpts(el, [
+                             "stroke", "gradient", "animation", "shadow", "span",
+                             "backgroundOp", "marginOp", "transform", "filtera", "raster",
+                         ]),
                          stroke: this.filtero("blast", el.id, obj.customOptions),
                          gradient: this.filtero("gradient", el.id, obj.customOptions),
                          animation: this.filtero("animation", el.id, obj.customOptions),
@@ -1624,6 +1661,27 @@ let elo = new Polygon({ id: "hex" })
 
         return new Text(el.text || el.value)
             .set({
+                // Everything the author declared, first, so that every option
+                // Text reads is reachable from a spec. Hand-listing the
+                // forwards left 36 of this type's 56 documented options
+                // settable only on the emitted component -- `background`,
+                // `align`, `width`, `opacity`, `radius` among them -- so a
+                // page could declare one, validate clean, and render without
+                // it. The note on `tag` below was one instance of that gap,
+                // closed one option at a time; this closes the rest.
+                //
+                // The spread comes FIRST and every assignment below overrides
+                // it, so nothing the mapper computes can be displaced by a
+                // field of the same name. The drop list is the keys this
+                // method derives from the NODE array: they belong to N, they
+                // are resolved by `filtero` below, and letting E supply them
+                // would both cross the two halves of the format and let an
+                // empty lookup overwrite an author's value with `undefined`.
+                ...this.elOpts(el, [
+                    "value",                                   // constructor argument, above
+                    "stroke", "gradient", "animation", "shadow", "span",
+                    "backgroundOp", "marginOp", "transform", "filtera", "raster",
+                ]),
                 id: el.id,
                 class: el.class,
                 color: el.color,
@@ -1662,7 +1720,14 @@ let elo = new Polygon({ id: "hex" })
 
         return new Image(el.url)
         .set({
-            ...el,
+            // elOpts rather than a raw `...el`: the raw spread put `type`,
+                // `children` and `items` into the component's OPTIONS, where
+                // they mean nothing, and -- now that toCode() serialises
+                // options -- writes them into the emitted source as well. The
+                // artefact is meant to be code a developer reads and owns, so
+                // it should not carry the specification's own bookkeeping.
+                ...this.elOpts(el),
+            url: el.url,          // skipped by elOpts; the raw spread carried it
             isFull:el.isFull,
          //   index: obj.i + "",
             animation: this.filtero("animation", el.id, obj.customOptions),
@@ -1857,12 +1922,28 @@ const blast    = this.filtero("blast", el.id, obj.customOptions);
   
 
 
+    // The author's own options, serialised into the emitted source. This
+    // mapper returns SOURCE rather than an instance, so there is nothing to
+    // spread onto -- the equivalent of `...elOpts(el)` here is to write the
+    // entries into the `.set({...})` literal being generated.
+    //
+    // They come AFTER the four template defaults and BEFORE the node ops, and
+    // that order is the contract: a default is a starting point an author may
+    // overrule, so `{type:"cards", gap:"2rem"}` wins over `gap:"1rem"`; a node
+    // is the N half of the format addressing this element by id, so it wins
+    // over E. Before this, every one of these keys was accepted by the
+    // validator, advertised by the schema, and silently dropped on the floor.
+    const authored = Object.entries(this.elOpts(obj.el, [
+      "backgroundCard",                          // consumed above, to pick the template
+      "gradient", "animation", "shadow", "marginOp", "filtera", "blast", "raster",
+    ])).map(([k, v]) => `,\n      ${JSON.stringify(k)}: ${JSON.stringify(v)}`).join("");
+
     return ` new FlexGrid()
     .set({
       colat: "700px",
       wrap: true,
       align: "center",
-      gap: "1rem"
+      gap: "1rem"${authored}
        ${
         gradient !== undefined ? `,\n      gradient: ${JSON.stringify(gradient)}` : ""
       }${
@@ -2118,7 +2199,13 @@ static form(obj){
         // slice on a word. A caller-supplied `size` still passes through.
         const wrapper = new Wrapper(kind)
             .set({
-                ...el,
+                // elOpts rather than a raw `...el`: the raw spread put `type`,
+                // `children` and `items` into the component's OPTIONS, where
+                // they mean nothing, and -- now that toCode() serialises
+                // options -- writes them into the emitted source as well. The
+                // artefact is meant to be code a developer reads and owns, so
+                // it should not carry the specification's own bookkeeping.
+                ...this.elOpts(el),
                 font: el.font ?? "Arial",
                 stroke: this.filtero("blast", el.id, obj.customOptions),
                 gradient: this.filtero("gradient", el.id, obj.customOptions),
@@ -2158,7 +2245,13 @@ static form(obj){
         // output of getElType on a non-heading type.
         const list = new UList(kind)
             .set({
-                ...el,
+                // elOpts rather than a raw `...el`: the raw spread put `type`,
+                // `children` and `items` into the component's OPTIONS, where
+                // they mean nothing, and -- now that toCode() serialises
+                // options -- writes them into the emitted source as well. The
+                // artefact is meant to be code a developer reads and owns, so
+                // it should not carry the specification's own bookkeeping.
+                ...this.elOpts(el),
                 font: el.font ?? "Arial",
                 stroke: this.filtero("blast", el.id, obj.customOptions),
                 gradient: this.filtero("gradient", el.id, obj.customOptions),

package/lib/element-params.generated.js

@@ -1,5 +1,5 @@
 /*!
- * nodality v1.3.5
+ * nodality v1.3.7
  * (c) 2026 Filip Vabrousek
  * License: MIT
  */

package/lib/keyframe-animation.js

@@ -1,5 +1,5 @@
 /*!
- * nodality v1.3.5
+ * nodality v1.3.7
  * (c) 2026 Filip Vabrousek
  * License: MIT
  */

package/lib/link-getter.js

@@ -1,5 +1,5 @@
 /*!
- * nodality v1.3.5
+ * nodality v1.3.7
  * (c) 2026 Filip Vabrousek
  * License: MIT
  */

package/lib/morph-node.js

@@ -1,5 +1,5 @@
 /*!
- * nodality v1.3.5
+ * nodality v1.3.7
  * (c) 2026 Filip Vabrousek
  * License: MIT
  */

package/lib/normalize-spec.js

@@ -1,5 +1,5 @@
 /*!
- * nodality v1.3.5
+ * nodality v1.3.7
  * (c) 2026 Filip Vabrousek
  * License: MIT
  */

package/lib/parse-html.js

@@ -1,5 +1,5 @@
 /*!
- * nodality v1.3.5
+ * nodality v1.3.7
  * (c) 2026 Filip Vabrousek
  * License: MIT
  */

package/lib/raster-inspect.js

@@ -1,5 +1,5 @@
 /*!
- * nodality v1.3.5
+ * nodality v1.3.7
  * (c) 2026 Filip Vabrousek
  * License: MIT
  */

package/lib/raster-ops.js

@@ -1,5 +1,5 @@
 /*!
- * nodality v1.3.5
+ * nodality v1.3.7
  * (c) 2026 Filip Vabrousek
  * License: MIT
  */
@@ -2526,6 +2526,11 @@ ${defaultSeam}
 // computes, on a clone, so the snapshot matches the live layout.
 const VIEWPORT_UNIT = /\d(?:vw|vh|vmin|vmax|dvw|dvh|svw|svh|lvw|lvh)\b/i;
 
+// Text metrics that must reach the snapshot as pixels. Anything relative here
+// gives the foreignObject a chance to resolve it against its own box instead of
+// the page — see part 1b of freezeStyles.
+const FROZEN_LENGTHS = ["font-size", "line-height", "letter-spacing", "word-spacing"];
+
 // Inheritable text properties. A foreignObject rendered from a data: URI
 // carries NO page stylesheet, and a clone carries only inline styles — so
 // anything a rule or an ancestor supplied is gone. Nodality's own
@@ -2570,8 +2575,8 @@ function freezeStyles(original, clone) {
         //    5vw)` renders at a different size than it does on the page.
         //    The glyphs then sit somewhere the DOM text does not, which
         //    is what makes a selection highlight look offset.
+        let computed = null;
         if (inline.length > 0) {
-            let computed = null;
             // Iterate a snapshot of the names: writing to style mutates the list.
             for (const prop of Array.from(inline)) {
                 if (!VIEWPORT_UNIT.test(inline.getPropertyValue(prop))) continue;
@@ -2581,6 +2586,28 @@ function freezeStyles(original, clone) {
             }
         }
 
+        // 1b. Text lengths are frozen to pixels ALWAYS, whatever unit they were
+        //     written in and whether or not they were set inline.
+        //
+        //     The sweep above only rewrites a declaration whose own inline text
+        //     matches VIEWPORT_UNIT. That misses every other way a length can
+        //     resolve differently inside the foreignObject: `rem` against a root
+        //     that is not the page's root, `em` down an ancestor chain the clone
+        //     no longer has, and — the case that prompted this — a `clamp()` whose
+        //     chosen branch depends on a viewport the SVG does not share. A
+        //     headline written `clamp(2.4rem, 4.6vw, 3.4rem)` came out at a
+        //     fraction of its size on a phone while looking correct in desktop
+        //     device emulation, because the two resolve that clamp differently.
+        //
+        //     Computed values are already absolute pixels, so this cannot change
+        //     what the page shows; it only removes the chance for the SVG to
+        //     recompute something the page had already decided.
+        for (const prop of FROZEN_LENGTHS) {
+            computed = computed || window.getComputedStyle(origs[i]);
+            const px = computed.getPropertyValue(prop);
+            if (px && px !== "normal") inline.setProperty(prop, px);
+        }
+
         // 2. Inherited text styling, which the clone would otherwise lose.
         const cs = window.getComputedStyle(origs[i]);
         const parent = origs[i].parentElement;
@@ -2721,17 +2748,200 @@ function fitImageToBox(img, w, h, dpr) {
     return c;
 }
 
+// ── Web fonts inside the snapshot ────────────────────────────────────
+//
+// A foreignObject rendered from a data: URI fetches NO subresources. An
+// @font-face whose src is a URL therefore never loads inside the capture, and
+// the text draws in whatever family the SVG can resolve locally — the page's
+// own web font is simply not among them. Recapturing on document.fonts.ready
+// does not help: the font is ready on the PAGE, never inside the snapshot.
+//
+// The only way the real typeface reaches the capture is to carry the bytes in
+// with it, so the faces the subtree actually uses are fetched once, base64'd,
+// and emitted as an inline <style> ahead of the serialized markup.
+//
+// Everything here degrades to "no embedded font" rather than failing the
+// capture: a cross-origin stylesheet that refuses CORS, a font host that does
+// the same, an offline reload — each ends with the previous behaviour, which is
+// a fallback typeface, not a broken image.
+
+/** Absolute font URL -> `data:` URI, or null when it could not be fetched. */
+const FONT_DATA_CACHE = new Map();
+
+/** Parsed @font-face rules for the document, resolved once. */
+let FACE_RULES = null;
+
+const FACE_BLOCK = /@font-face\s*{[^}]*}/gi;
+const FACE_FAMILY = /font-family\s*:\s*(['"]?)([^;'"]+)\1/i;
+const FACE_WEIGHT = /font-weight\s*:\s*([^;]+)/i;
+const FACE_STYLE = /font-style\s*:\s*([^;]+)/i;
+const FACE_SRC_URL = /url\((['"]?)([^)'"]+)\1\)/gi;
+const FACE_RANGE = /unicode-range\s*:\s*([^;}]+)/i;
+
+/**
+ * Does this face cover any character the capture actually contains?
+ *
+ * A provider splits one family into a subset per script — Google ships seven for
+ * Inter — so embedding every subset for every weight in use put well over half a
+ * megabyte of base64 into a single snapshot. Only the subsets the text actually
+ * lands in are worth carrying. A face that declares no range covers everything
+ * and is always kept.
+ */
+function faceCoversText(range, text) {
+    if (!range) return true;
+    const spans = [];
+    for (const part of range.split(",")) {
+        const m = /U\+([0-9a-fA-F?]+)(?:-([0-9a-fA-F]+))?/.exec(part.trim());
+        if (!m) continue;
+        if (m[1].indexOf("?") !== -1) {
+            spans.push([parseInt(m[1].replace(/\?/g, "0"), 16),
+                        parseInt(m[1].replace(/\?/g, "F"), 16)]);
+        } else {
+            const lo = parseInt(m[1], 16);
+            spans.push([lo, m[2] ? parseInt(m[2], 16) : lo]);
+        }
+    }
+    if (!spans.length) return true;
+    for (const ch of text) {
+        const cp = ch.codePointAt(0);
+        for (let i = 0; i < spans.length; i++) {
+            if (cp >= spans[i][0] && cp <= spans[i][1]) return true;
+        }
+    }
+    return false;
+}
+
+function parseFaces(cssText, baseUrl) {
+    const out = [];
+    for (const block of cssText.match(FACE_BLOCK) || []) {
+        const fam = FACE_FAMILY.exec(block);
+        if (!fam) continue;
+        const urls = [];
+        let m;
+        FACE_SRC_URL.lastIndex = 0;
+        while ((m = FACE_SRC_URL.exec(block))) {
+            try { urls.push(new URL(m[2], baseUrl).href); } catch (e) { /* skip */ }
+        }
+        if (!urls.length) continue;
+        out.push({
+            family: fam[2].trim().toLowerCase(),
+            weight: (FACE_WEIGHT.exec(block) || [, "400"])[1].trim(),
+            style: (FACE_STYLE.exec(block) || [, "normal"])[1].trim(),
+            range: (FACE_RANGE.exec(block) || [, ""])[1].trim(),
+            block,
+            urls,
+        });
+    }
+    return out;
+}
+
+async function collectFaceRules() {
+    if (FACE_RULES) return FACE_RULES;
+    const faces = [];
+    for (const sheet of Array.from(document.styleSheets || [])) {
+        // Same-origin sheets can be read directly. A cross-origin one throws on
+        // cssRules, so it is fetched instead — Google Fonts and the like serve
+        // their CSS with permissive CORS, and anything that does not simply
+        // contributes no faces.
+        let rules = null;
+        try { rules = sheet.cssRules; } catch (e) { rules = null; }
+        if (rules) {
+            for (const rule of Array.from(rules)) {
+                if (rule.constructor && rule.constructor.name === "CSSFontFaceRule") {
+                    faces.push(...parseFaces(rule.cssText, sheet.href || location.href));
+                }
+            }
+        } else if (sheet.href) {
+            try {
+                const res = await fetch(sheet.href, { mode: "cors" });
+                if (res.ok) faces.push(...parseFaces(await res.text(), sheet.href));
+            } catch (e) { /* no faces from this sheet */ }
+        }
+    }
+    FACE_RULES = faces;
+    return faces;
+}
+
+async function asDataUri(url) {
+    if (FONT_DATA_CACHE.has(url)) return FONT_DATA_CACHE.get(url);
+    let uri = null;
+    try {
+        const res = await fetch(url, { mode: "cors" });
+        if (res.ok) {
+            const buf = new Uint8Array(await res.arrayBuffer());
+            let bin = "";
+            for (let i = 0; i < buf.length; i++) bin += String.fromCharCode(buf[i]);
+            const type = url.endsWith(".woff2") ? "font/woff2"
+                : url.endsWith(".woff") ? "font/woff" : "font/ttf";
+            uri = `data:${type};base64,${btoa(bin)}`;
+        }
+    } catch (e) { uri = null; }
+    FONT_DATA_CACHE.set(url, uri);
+    return uri;
+}
+
+/** The (family, weight, style) triples this subtree actually renders in. */
+function usedFaces(el) {
+    const seen = new Map();
+    for (const node of [el, ...el.querySelectorAll("*")]) {
+        const cs = window.getComputedStyle(node);
+        const first = (cs.fontFamily || "").split(",")[0].trim().replace(/^['"]|['"]$/g, "");
+        if (!first) continue;
+        const key = `${first.toLowerCase()}|${cs.fontWeight}|${cs.fontStyle}`;
+        if (!seen.has(key)) {
+            seen.set(key, { family: first.toLowerCase(), weight: cs.fontWeight, style: cs.fontStyle });
+        }
+    }
+    return Array.from(seen.values());
+}
+
+async function embeddedFontCss(el) {
+    let faces;
+    try { faces = await collectFaceRules(); } catch (e) { return ""; }
+    if (!faces.length) return "";
+
+    const wanted = usedFaces(el);
+    const text = el.textContent || "";
+    const chosen = faces.filter((f) => faceCoversText(f.range, text) && wanted.some((u) =>
+        u.family === f.family &&
+        (f.style === u.style || f.style === "normal") &&
+        // Google emits one face per weight; a variable face states a range and
+        // is kept for every weight that asks for the family.
+        (f.weight === String(u.weight) || /\s/.test(f.weight))));
+    if (!chosen.length) return "";
+
+    const parts = [];
+    for (const face of chosen) {
+        // First url that actually comes back — the list is a preference order.
+        let uri = null;
+        for (const u of face.urls) {
+            uri = await asDataUri(u);
+            if (uri) break;
+        }
+        if (!uri) continue;
+        parts.push(
+            `@font-face{font-family:'${face.family}';font-style:${face.style};` +
+            `font-weight:${face.weight};src:url(${uri});}`);
+    }
+    return parts.join("");
+}
+
 function snapshotToImage(el, w, h, dpr) {
     const direct = soleImageOf(el);
     if (direct) return Promise.resolve(fitImageToBox(direct, w, h, dpr));
 
-    return new Promise((resolve, reject) => {
+    // The font CSS is resolved before serialising. It is cached after the first
+    // capture, so only the very first snapshot on a page pays for the fetch, and
+    // a failure returns "" and leaves the previous fallback behaviour intact.
+    return embeddedFontCss(el).catch(() => "").then((fontCss) => new Promise((resolve, reject) => {
         const serialized = new XMLSerializer()
             .serializeToString(freezeStyles(el, el.cloneNode(true)));
         const svg =
             `<svg xmlns="http://www.w3.org/2000/svg" width="${w * dpr}" height="${h * dpr}" viewBox="0 0 ${w} ${h}">` +
             `<foreignObject width="100%" height="100%">` +
-            `<div xmlns="http://www.w3.org/1999/xhtml">${serialized}</div>` +
+            `<div xmlns="http://www.w3.org/1999/xhtml">` +
+            (fontCss ? `<style>${fontCss}</style>` : "") +
+            `${serialized}</div>` +
             `</foreignObject></svg>`;
         // createElement, NOT `new Image()` — this library exports a
         // component named `Image`, and consumers publish the exports onto
@@ -2741,7 +2951,7 @@ function snapshotToImage(el, w, h, dpr) {
         img.onload = () => resolve(img);
         img.onerror = reject;
         img.src = "data:image/svg+xml;charset=utf-8," + encodeURIComponent(svg);
-    });
+    }));
 }
 
 // ── switch: pick a sub-chain by condition ────────────────────────────

package/lib/raster-presets.js

@@ -1,5 +1,5 @@
 /*!
- * nodality v1.3.5
+ * nodality v1.3.7
  * (c) 2026 Filip Vabrousek
  * License: MIT
  */

package/lib/resolve-refs.js

@@ -1,5 +1,5 @@
 /*!
- * nodality v1.3.5
+ * nodality v1.3.7
  * (c) 2026 Filip Vabrousek
  * License: MIT
  */

package/lib/scroll-video.js

@@ -1,5 +1,5 @@
 /*!
- * nodality v1.3.5
+ * nodality v1.3.7
  * (c) 2026 Filip Vabrousek
  * License: MIT
  */

package/lib/seo.js

@@ -1,5 +1,5 @@
 /*!
- * nodality v1.3.5
+ * nodality v1.3.7
  * (c) 2026 Filip Vabrousek
  * License: MIT
  */

package/lib/stacker.js

@@ -1,5 +1,5 @@
 /*!
- * nodality v1.3.5
+ * nodality v1.3.7
  * (c) 2026 Filip Vabrousek
  * License: MIT
  */

package/lib/suggest.js

@@ -1,5 +1,5 @@
 /*!
- * nodality v1.3.5
+ * nodality v1.3.7
  * (c) 2026 Filip Vabrousek
  * License: MIT
  */

package/lib/theme.js

@@ -1,5 +1,5 @@
 /*!
- * nodality v1.3.5
+ * nodality v1.3.7
  * (c) 2026 Filip Vabrousek
  * License: MIT
  */

package/lib/transform-anim.js

@@ -1,5 +1,5 @@
 /*!
- * nodality v1.3.5
+ * nodality v1.3.7
  * (c) 2026 Filip Vabrousek
  * License: MIT
  */

package/lib/transition.js

@@ -1,5 +1,5 @@
 /*!
- * nodality v1.3.5
+ * nodality v1.3.7
  * (c) 2026 Filip Vabrousek
  * License: MIT
  */