nodality 1.3.17 → 1.3.19

package/lib/check-page.js

@@ -1,5 +1,5 @@
 /*!
- * nodality v1.3.17
+ * nodality v1.3.19
  * (c) 2026 Filip Vabrousek
  * License: MIT
  */
@@ -274,6 +274,53 @@ const IN_PAGE = () => {
             }
         }
     }
+
+    // A shop product's loading state against its loaded state. Until the
+    // shop answers, a product shows its static copy (`-static` ids) in the
+    // placeholder; then Shopify stamps the <template> and hides the copy. A
+    // page can look right in both and still jump between them — or, as on
+    // the suitcase site before 1.3.18, be wrong only while loading (price
+    // and options run into one line). Nothing above measures that, because
+    // nothing overflows. So the stamp is done here, the way Shopify does it,
+    // each live element is measured against its static copy, and the stamp
+    // is undone. The shop script itself is blocked (see checkPage), so this
+    // is deterministic and needs no store.
+    for (const ctx of document.querySelectorAll("shopify-context")) {
+        const tpl = [...ctx.children].find((c) => c.tagName === "TEMPLATE");
+        const ph = [...ctx.children].find((c) => c.hasAttribute("shopify-loading-placeholder"));
+        if (!tpl || !ph || ph.hidden || !ph.getClientRects) continue;
+        const box = ctx.getBoundingClientRect();
+        const at = (el) => {
+            const r = el.getBoundingClientRect();
+            return { x: r.left - box.left, y: r.top - box.top, w: r.width, h: r.height };
+        };
+        const before = new Map();
+        for (const el of ph.querySelectorAll("[id$='-static']")) {
+            if (el.getClientRects().length) before.set(el.id.replace(/-static$/, ""), at(el));
+        }
+        const stamped = [...tpl.content.cloneNode(true).childNodes];
+        stamped.forEach((n) => ctx.appendChild(n));
+        ph.hidden = true;
+        const prev = ph.style.display;
+        ph.style.display = "none";
+        let worst = null;
+        for (const [id, a] of before) {
+            const live = ctx.querySelector(`[id="${CSS.escape(id)}"]`);
+            if (!live || !live.getClientRects().length) continue;
+            const b = at(live);
+            const move = Math.max(Math.abs(a.x - b.x), Math.abs(a.y - b.y));
+            const resize = Math.max(Math.abs(a.w - b.w), Math.abs(a.h - b.h));
+            const d = Math.max(move, resize);
+            if (d > 8 && (!worst || d > worst.d)) worst = { id, d: Math.round(d), move: Math.round(move), resize: Math.round(resize) };
+        }
+        stamped.forEach((n) => n.parentNode && n.parentNode.removeChild(n));
+        ph.style.display = prev;
+        ph.hidden = false;
+        if (worst) {
+            add("LOADING_LAYOUT_SHIFT", ctx, `#${worst.id}: ${worst.d}px`,
+                `the loading copy and the loaded element differ by ${worst.move}px in position and ${worst.resize}px in size — the product jumps when the shop answers, and reads differently until it does`);
+        }
+    }
     return out;
 };
 
@@ -335,6 +382,11 @@ const REPAIRS = {
         suggestions: [`maxWidth: "100%" on whichever element the other findings name`],
         valid: ["the document may not be wider than the viewport"],
     },
+    LOADING_LAYOUT_SHIFT: {
+        suggestions: [`give the static copy the same text and layout keys as the live element`,
+                      `upgrade nodality: since 1.3.18 the placeholder lays out in the product's own grid`],
+        valid: ["a product's loading copy sits where its loaded element will, within 8px"],
+    },
     CONTENT_CLIPPED: {
         suggestions: [`height: "auto"`, `overflow: "visible"`],
         valid: ["a box with `overflow: hidden` must be tall enough for its text"],
@@ -385,6 +437,11 @@ export async function checkPage(html, opts = {}) {
         for (const vp of viewports) {
             const page = await browser.newPage({ viewport: { width: vp.width, height: vp.height } });
             try {
+                // The shop script never loads here: a product is checked in
+                // the state every visitor sees first, the same on every run
+                // and without a store. LOADING_LAYOUT_SHIFT compares it with
+                // the loaded state by stamping the template itself.
+                await page.route(/cdn\.shopify\.com\/storefront\//, (r) => r.abort());
                 await page.setContent(doc, { waitUntil });
                 const found = await page.evaluate(IN_PAGE);
                 for (const f of found) {

package/lib/codegen.js

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

package/lib/data.js

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

package/lib/designer.js

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

package/lib/element-mapper.js

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

package/lib/element-params.generated.js

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

package/lib/grid-geometry.js

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

package/lib/keyframe-animation.js

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

package/lib/known-inert.js

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

package/lib/link-getter.js

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

package/lib/morph-node.js

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

package/lib/normalize-spec.js

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

package/lib/parse-html.js

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

package/lib/raster-inspect.js

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

package/lib/raster-ops.js

@@ -1,5 +1,5 @@
 /*!
- * nodality v1.3.17
+ * nodality v1.3.19
  * (c) 2026 Filip Vabrousek
  * License: MIT
  */
@@ -21,8 +21,12 @@
 //   snapshot (default) — XMLSerializer -> SVG foreignObject -> Image ->
 //     texture. Works in every browser. Nodality output is inline-styled,
 //     so fidelity is high. Static: recaptured on resize (or via
-//     handle.refresh()). External images / webfonts do not load inside
-//     the SVG image context — system fonts and data: URIs only.
+//     handle.refresh()). External images do not load inside the SVG
+//     image context (data: URIs do). Web fonts DO arrive: the faces the
+//     subtree uses are fetched and embedded as data: URIs (see "Web fonts
+//     inside the snapshot"); only a font host that refuses CORS falls back
+//     to a local typeface. (This line said web fonts never load until
+//     October 2026, long after embedding shipped.)
 //   live (the DEFAULT where it applies; opt OUT with `live: false` on any
 //     node) — the emerging HTML-in-Canvas API (WICG, Chrome origin trial):
 //     the mount subtree moves inside the effect <canvas layoutsubtree> and
@@ -108,12 +112,26 @@ const DRIVERS = {
 };
 const DRIVER_NAMES = Object.keys(DRIVERS);
 
+// What each driver does, for describeOps(). The resting behaviour is the part
+// an agent cannot infer from a name: whether the effect is visible before
+// anyone interacts, which decides whether a page looks the same at rest.
+const DRIVER_DOCS = {
+    static: "The element's centre at full strength, always on. The default for ops that need a focus.",
+    mouse: "Follows the pointer at full strength, and stays on where the pointer last was — visible at rest.",
+    hover: "Follows the pointer, faded in and out with hover — nothing shows at rest or without a pointer (a phone).",
+    scroll: "A band that travels up the element as it crosses the viewport, at full strength.",
+    time: "Hands-free: the focus drifts on a Lissajous path, always on.",
+};
+
 const REGISTRY = {
     hexalize: {
         doc: {
             summary: "Hexagonal cell grid. Snaps sampling to a hex lattice and "
                 + "draws cell borders; with `lift`, cells near the driver swell "
-                + "toward the viewer and their content magnifies to match.",
+                + "toward the viewer and their content magnifies to match. Away "
+                + "from the focus a lifted chain is untouched — no magnification, "
+                + "no border — so with `by: \"hover\"` the element is "
+                + "pixel-identical at rest and the cells appear only under the pointer.",
             params: {
                 size: { default: 24, unit: "px", summary: "lattice pitch — the width of one cell" },
                 lift: {
@@ -442,6 +460,10 @@ ${NB.map(([x, y]) => probe(x, y)).join("")}
             },
         },
         stage: "color",
+        // It colours `edge`, which only a cell-stage op writes. Declared so the
+        // validator can say so (INERT_RASTER_OP) instead of the chain
+        // validating clean and drawing nothing.
+        needs: "cell",
         decl: (p) => `uniform vec3 ${p}color; uniform float ${p}strength;`,
         code: (p) => `
         {
@@ -4094,11 +4116,26 @@ function applyRasterPipeline(el, rasterNodes, opts) {
 
     if (live) {
         canvas.addEventListener("paint", onPaint);
-        setTimeout(() => {
+        // The 1500ms is a budget for a page someone is looking at. A hidden
+        // document — a tab opened in the background — paints nothing at all,
+        // so timing it from load sent every background-opened page to the
+        // snapshot for good, even in a browser with the live API. The clock
+        // starts when the page is first shown.
+        const startPaintClock = () => setTimeout(() => {
             if (!destroyed && mode === "live" && !textureReady) {
                 fallbackToSnapshot("no paint event within 1500ms");
             }
         }, 1500);
+        if (typeof document !== "undefined" && document.visibilityState === "hidden") {
+            const onShown = () => {
+                if (document.visibilityState === "hidden") return;
+                document.removeEventListener("visibilitychange", onShown);
+                if (!destroyed) startPaintClock();
+            };
+            document.addEventListener("visibilitychange", onShown);
+        } else {
+            startPaintClock();
+        }
     }
 
     // Pointer -> u_mouse (listen on the host so the overlay stays
@@ -4963,7 +5000,7 @@ function applyRasterPipeline(el, rasterNodes, opts) {
 
 export {
     applyRasterPipeline, registerRasterOp, RASTER_OP_NAMES,
-    isHTMLInCanvasAvailable, DRIVER_NAMES,
+    isHTMLInCanvasAvailable, DRIVER_NAMES, DRIVER_DOCS,
     // Phase H3. The registry is already effectively public — registerRasterOp
     // mutates it — and a dev tool needs to read an op's stage and params to
     // show them. `isStructuralChange` is exported so the inspector can label

package/lib/raster-presets.js

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

package/lib/resolve-refs.js

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

package/lib/scroll-video.js

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

package/lib/seo.js

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

package/lib/stacker.js

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

package/lib/suggest.js

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

package/lib/theme.js

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

package/lib/transform-anim.js

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

package/lib/transition.js

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

package/lib/validate-nodes.js

@@ -1,5 +1,5 @@
 /*!
- * nodality v1.3.17
+ * nodality v1.3.19
  * (c) 2026 Filip Vabrousek
  * License: MIT
  */
@@ -26,7 +26,7 @@
  */
 
 import {
-    REGISTRY, RASTER_OP_NAMES, DRIVER_NAMES, RASTER_UNITS,
+    REGISTRY, RASTER_OP_NAMES, DRIVER_NAMES, DRIVER_DOCS, RASTER_UNITS,
     FRAMEWORK_DOC, EASING_NAMES,
 } from "./raster-ops.js";
 import { presetNames, presetInfo } from "./raster-presets.js";
@@ -1026,6 +1026,28 @@ export function validateNodes(nodes, elements, defs) {
         }
     });
 
+    // An op that only colours what an earlier stage produced draws nothing
+    // without it: `edges` reads the cell borders a cell op (hexalize) writes.
+    // The chain is per target — raster nodes on one element compile into one
+    // pass, in array order — so the producer must come earlier on the same
+    // target. Declared on the op (`needs`), not listed here.
+    const stagesOf = (d) => [].concat((d && d.stage) || []);
+    const seen = new Map(); // target key -> stages written so far
+    nodes.forEach((node, i) => {
+        if (!node || typeof node.op !== "string") return;
+        const d = REGISTRY[node.op];
+        if (!d) return;
+        const key = Array.isArray(node.target) ? node.target.map((t) => String(t).replace(/^#/, "")).sort().join(",") : "";
+        const have = seen.get(key) || new Set();
+        if (d.needs && !have.has(d.needs)) {
+            const producers = RASTER_OP_NAMES.filter((n) => stagesOf(REGISTRY[n]).includes(d.needs));
+            warn("INERT_RASTER_OP", `nodes[${i}].op`, node.op, producers, producers,
+                `"${node.op}" draws nothing unless a ${d.needs}-stage op (${producers.join(", ")}) comes before it on the same target.`);
+        }
+        stagesOf(d).forEach((s) => have.add(s));
+        seen.set(key, have);
+    });
+
     return { ok: errors.length === 0, errors, warnings };
 }
 
@@ -1043,6 +1065,8 @@ export function describeOps() {
             op: name,
             stage: Array.isArray(def.stage) ? def.stage : [def.stage].filter(Boolean),
             summary: doc.summary || "",
+            // What must come before it on the same target for it to draw.
+            ...(def.needs ? { needs: def.needs } : {}),
             params: Object.keys(params).map((p) => ({
                 name: p,
                 default: params[p].default,
@@ -1071,6 +1095,9 @@ export function describeOps() {
             summary: FRAMEWORK_DOC[k].summary || "",
         })),
         drivers: DRIVER_NAMES,
+        // Names stay a plain list above for existing readers; this says what
+        // each does, including whether anything shows at rest.
+        driverDocs: DRIVER_NAMES.map((name) => ({ name, summary: DRIVER_DOCS[name] || "" })),
         easings: EASING_NAMES,
         units: RASTER_UNITS,
     };

package/lib/webmcp-adapter.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nodality",
-  "version": "1.3.17",
+  "version": "1.3.19",
   "description": "A lightweight library for declarative UI elements.",
   "main": "dist/index.cjs.js",
   "module": "dist/index.esm.js",