nodality 1.3.7 → 1.3.9

package/lib/grid-geometry.js

@@ -0,0 +1,137 @@
+/*!
+ * nodality v1.3.9
+ * (c) 2026 Filip Vabrousek
+ * License: MIT
+ */
+
+// grid-geometry.js — the arithmetic behind GridOverlay.
+//
+// One pure function turns a box size and a grid description into the pixel
+// position of every line and every intersection. It lives apart from the
+// component for two reasons:
+//
+//   • It is testable in bare Node. No DOM, no window, nothing at import.
+//   • Anything that must land ON the grid needs the same numbers. The
+//     overlay draws the lines; a layout component that places content in
+//     the cells has to agree with it to the pixel, and two copies of this
+//     maths would drift.
+//
+// Conventions
+//   columns / rows  count CELLS, not lines. N cells → N+1 lines. 0 → no
+//                on that axis (and therefore no intersections).
+//   inset        distance of the outermost lines from the box edge, in px.
+//                A number applies to both axes; { x, y } sets them apart.
+//   lineWidth    used only to snap positions so 1px lines land on a pixel
+//                boundary and stay sharp instead of smearing over two.
+
+const clampCount = (n) => {
+	const v = Math.floor(Number(n));
+	return Number.isFinite(v) && v > 0 ? v : 0;
+};
+
+const toInset = (inset) => {
+	if (inset && typeof inset === "object") {
+		return { x: Math.max(0, Number(inset.x) || 0), y: Math.max(0, Number(inset.y) || 0) };
+	}
+	const v = Math.max(0, Number(inset) || 0);
+	return { x: v, y: v };
+};
+
+// Odd stroke widths centre on a half pixel; even ones on a whole pixel.
+const snap = (v, lineWidth) => {
+	const w = Math.max(1, Math.round(Number(lineWidth) || 1));
+	return w % 2 === 1 ? Math.round(v - 0.5) + 0.5 : Math.round(v);
+};
+
+// Positions of `count + 1` lines spread evenly from `start` to `end`.
+const linePositions = (count, start, end, lineWidth) => {
+	if (count === 0 || end <= start) return [];
+	const step = (end - start) / count;
+	const out = [];
+	for (let i = 0; i <= count; i++) out.push(snap(start + step * i, lineWidth));
+	return out;
+};
+
+function gridGeometry({ width = 0, height = 0, columns = 4, rows = 2, inset = 0, lineWidth = 1 } = {}) {
+	const w = Math.max(0, Number(width) || 0);
+	const h = Math.max(0, Number(height) || 0);
+	const c = clampCount(columns);
+	const r = clampCount(rows);
+	const pad = toInset(inset);
+
+	// An inset larger than half the box leaves no room for a grid.
+	const left = Math.min(pad.x, w / 2);
+	const top = Math.min(pad.y, h / 2);
+
+	const x = linePositions(c, left, w - left, lineWidth);
+	const y = linePositions(r, top, h - top, lineWidth);
+
+	const intersections = [];
+	for (let row = 0; row < y.length; row++) {
+		for (let col = 0; col < x.length; col++) {
+			intersections.push({ col, row, x: x[col], y: y[row] });
+		}
+	}
+
+	return {
+		width: w,
+		height: h,
+		columns: c,
+		rows: r,
+		inset: { x: left, y: top },
+		cell: {
+			width: c ? (w - 2 * left) / c : 0,
+			height: r ? (h - 2 * top) / r : 0,
+		},
+		x,
+		y,
+		intersections,
+	};
+}
+
+// Options for the current viewport. Below `breakpoint` the keys in `mobile`
+// replace their desktop counterparts; everything else carries over.
+function resolveGridOptions(options = {}, viewportWidth = Infinity) {
+	const { mobile, ...base } = options || {};
+	const breakpoint = Number(base.breakpoint) || 768;
+	if (mobile && typeof mobile === "object" && viewportWidth < breakpoint) {
+		return { ...base, ...mobile };
+	}
+	return base;
+}
+
+// Where a label sits relative to an intersection. `anchor` names the
+// quadrant: "br" below-right (default), "bl", "tr", "tl".
+//
+// Pass `box` and the anchor becomes a preference rather than an order: a
+// label that would land outside the box flips to the opposite side. Without
+// it, any readout on the last column or bottom row is clipped by the host's
+// overflow — which is what the outermost intersections are FOR, so the
+// default must not punish using them.
+function readoutPosition(point, anchor = "br", gap = 8, box = null) {
+	const a = ["tl", "tr", "bl", "br"].includes(anchor) ? anchor : "br";
+	let right = a[1] === "r";
+	let below = a[0] === "b";
+
+	if (box) {
+		const w = Number(box.width) || 0;
+		const h = Number(box.height) || 0;
+		// Room for a short label on the side the anchor asks for. The exact
+		// text width is a render-time measurement; this only has to catch the
+		// case where the intersection sits ON the edge.
+		const room = gap + 24;
+		if (right && point.x + room > w) right = false;
+		else if (!right && point.x - room < 0) right = true;
+		if (below && point.y + room > h) below = false;
+		else if (!below && point.y - room < 0) below = true;
+	}
+
+	return {
+		x: point.x + (right ? gap : -gap),
+		y: point.y + (below ? gap : -gap),
+		textAnchor: right ? "start" : "end",
+		baseline: below ? "hanging" : "alphabetic",
+	};
+}
+
+export { gridGeometry, resolveGridOptions, readoutPosition };

package/lib/keyframe-animation.js

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

package/lib/link-getter.js

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

package/lib/morph-node.js

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

package/lib/normalize-spec.js

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

package/lib/parse-html.js

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

package/lib/raster-inspect.js

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

package/lib/raster-ops.js

@@ -1,5 +1,5 @@
 /*!
- * nodality v1.3.7
+ * nodality v1.3.9
  * (c) 2026 Filip Vabrousek
  * License: MIT
  */
@@ -2936,8 +2936,24 @@ function snapshotToImage(el, w, h, dpr) {
     return embeddedFontCss(el).catch(() => "").then((fontCss) => new Promise((resolve, reject) => {
         const serialized = new XMLSerializer()
             .serializeToString(freezeStyles(el, el.cloneNode(true)));
+        // The SVG carries NO scaling at all — it is emitted at CSS size, 1:1.
+        //
+        // Engines do not agree about scaling foreignObject content: mobile Chrome and
+        // Safari apply neither a viewBox ratio nor an ancestor transform to the HTML
+        // subtree, so content laid out at `w x h` stayed `w x h` in the top-left of a
+        // `w*dpr` canvas. Reading the uploaded texture back off the GPU on a dpr-3
+        // phone showed exactly that: a 1101x369 texture with its ink confined to the
+        // first 367x123. The same SVG looked correct in an <img> sized to 367 CSS px,
+        // because there the unscaled content happened to fill the box — which is what
+        // made this look like a compositing bug for so long.
+        //
+        // So the SVG is rasterised at the size its contents are laid out for, and the
+        // dpr upscale is done by drawImage below, where the destination rectangle is
+        // stated outright and no engine has an opinion. High-dpr output is a touch
+        // softer than a native-resolution rasterisation would be; correct everywhere
+        // beats crisp on the machines that happened to agree with us.
         const svg =
-            `<svg xmlns="http://www.w3.org/2000/svg" width="${w * dpr}" height="${h * dpr}" viewBox="0 0 ${w} ${h}">` +
+            `<svg xmlns="http://www.w3.org/2000/svg" width="${w}" height="${h}" viewBox="0 0 ${w} ${h}">` +
             `<foreignObject width="100%" height="100%">` +
             `<div xmlns="http://www.w3.org/1999/xhtml">` +
             (fontCss ? `<style>${fontCss}</style>` : "") +
@@ -2948,7 +2964,30 @@ function snapshotToImage(el, w, h, dpr) {
         // globalThis. Where they do, the DOM constructor is gone and this
         // promise never settles: the snapshot backend hangs with no error.
         const img = document.createElement("img");
-        img.onload = () => resolve(img);
+        img.onload = () => {
+            // Rasterise into a canvas of exactly the size we asked for, and hand
+            // THAT to the caller.
+            //
+            // texImage2D takes an image's INTRINSIC size, and engines disagree about
+            // what that is for an SVG: desktop Chrome honours the width/height
+            // attributes (w*dpr), while mobile Chrome and Safari take it from the
+            // viewBox (w). On a phone the texture therefore arrived at 1/dpr scale
+            // and the effect painted its content into the top-left corner of its own
+            // canvas — the headline came out about a third of its size, while every
+            // measurement of the box, the SVG and the CSS looked perfectly correct.
+            //
+            // Drawing with an explicit destination rectangle makes the size ours
+            // instead of theirs, so the texture matches the backing store on every
+            // engine. This mirrors what fitImageToBox already does for the
+            // sole-image fast path.
+            const c = document.createElement("canvas");
+            c.width = Math.max(1, Math.round(w * dpr));
+            c.height = Math.max(1, Math.round(h * dpr));
+            const ctx = c.getContext("2d");
+            if (!ctx) { resolve(img); return; }
+            ctx.drawImage(img, 0, 0, c.width, c.height);
+            resolve(c);
+        };
         img.onerror = reject;
         img.src = "data:image/svg+xml;charset=utf-8," + encodeURIComponent(svg);
     }));

package/lib/raster-presets.js

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

package/lib/resolve-refs.js

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

package/lib/scroll-video.js

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

package/lib/seo.js

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

package/lib/stacker.js

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

package/lib/suggest.js

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

package/lib/theme.js

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

package/lib/transform-anim.js

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

package/lib/transition.js

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

package/lib/validate-nodes.js

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

package/lib/webmcp-adapter.js

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

package/package.json

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

package/schema.json

@@ -4593,16 +4593,85 @@
         "Set"
       ],
       "params": [
+        {
+          "name": "aspectRatio",
+          "description": "Box proportion held before the video loads, e.g. \"16 / 9\". Prevents the page shifting when the first frame arrives."
+        },
+        {
+          "name": "autoplay",
+          "description": "Start on its own. Implies muted and playsinline, pauses off screen and in a hidden tab, and is cancelled by prefers-reduced-motion (the poster stays)."
+        },
+        {
+          "name": "background",
+          "description": "CSS background behind the frame — visible while the poster loads."
+        },
+        {
+          "name": "controls",
+          "description": "Show the browser's playback controls. Default true — pass false for an ambient loop."
+        },
+        {
+          "name": "decorative",
+          "description": "Hide from assistive technology. For an ambient loop that repeats what the page already says in text."
+        },
+        {
+          "name": "height",
+          "description": "CSS height of the element."
+        },
         {
           "name": "id",
           "description": "This element's DOM id. Also what a design node's `target` names, and what `parse` recovers an element by."
         },
         {
-          "name": "opacity"
+          "name": "label",
+          "description": "Accessible name, for a clip that carries meaning."
+        },
+        {
+          "name": "lazy",
+          "description": "Only play while on screen. On by default whenever `autoplay` is set; pass false to keep an autoplaying clip running off screen."
+        },
+        {
+          "name": "loop",
+          "description": "Restart when the clip ends."
+        },
+        {
+          "name": "maxWidth",
+          "description": "CSS max-width of the element."
+        },
+        {
+          "name": "muted",
+          "description": "Mute the audio track. Forced on by `autoplay`, because browsers block an unmuted autoplay; pass false only if you mean to accept that."
+        },
+        {
+          "name": "objectFit",
+          "description": "How the frame fills the element box: \"cover\", \"contain\", \"fill\", \"none\"."
+        },
+        {
+          "name": "opacity",
+          "description": "0–1."
+        },
+        {
+          "name": "playsinline",
+          "description": "Play in place on iPhone instead of taking over the screen. Implied by `autoplay`; there is no reason to refuse it on a background loop."
+        },
+        {
+          "name": "poster",
+          "description": "Image shown before the first frame decodes. Give one on any autoplaying clip: it is what holds the layout still and what reduced-motion visitors see instead of the video."
+        },
+        {
+          "name": "preload",
+          "description": "\"none\", \"metadata\" (a good default for a loop) or \"auto\"."
         },
         {
           "name": "radius",
-          "description": "Corner radius in pixels. A bare number, not a CSS length."
+          "description": "Corner radius. A CSS length; a bare number is read as pixels."
+        },
+        {
+          "name": "raster",
+          "description": "Raster op nodes to run over this element."
+        },
+        {
+          "name": "sources",
+          "description": "Several encodings of the same clip: [{url, type}] or plain url strings. The browser picks the first it can play, so order best-first (AV1, then HEVC, then H.264). `type` is inferred from the extension when omitted."
         },
         {
           "name": "type",
@@ -4612,7 +4681,8 @@
           "name": "url"
         },
         {
-          "name": "width"
+          "name": "width",
+          "description": "CSS width of the element."
         }
       ]
     },
@@ -6285,11 +6355,100 @@
           "name": "width"
         }
       ]
+    },
+    "gridOverlay": {
+      "resolved": true,
+      "mapper": "mapGridOverlay",
+      "components": [
+        "GridOverlay"
+      ],
+      "params": [
+        {
+          "name": "breakpoint",
+          "description": "Viewport width in px below which `mobile` applies. Default 768."
+        },
+        {
+          "name": "color",
+          "description": "Colour of lines, marks and readouts (drawn with currentColor). Falls back to the Theme text colour."
+        },
+        {
+          "name": "columns",
+          "description": "Columns, counted as cells (N cells draw N+1 lines). 0 draws no vertical lines. Default 4. Named `columns`, not `cols`: the library's shared `cols` means grid-template-columns verbatim."
+        },
+        {
+          "name": "font",
+          "description": "Font family of the readouts. Default a monospace stack."
+        },
+        {
+          "name": "fontSize",
+          "description": "Readout font size in px. Default 11."
+        },
+        {
+          "name": "id",
+          "description": "This element's DOM id. Also what a design node's `target` names, and what `parse` recovers an element by."
+        },
+        {
+          "name": "inset",
+          "description": "Distance of the outermost lines from the edge in px. A number, or {x, y}. Default 16."
+        },
+        {
+          "name": "letterSpacing",
+          "description": "Readout letter spacing, any CSS length. Default \"0.04em\"."
+        },
+        {
+          "name": "lineOpacity",
+          "description": "Opacity of the lines only; marks and readouts stay opaque. 0–1, default 0.35."
+        },
+        {
+          "name": "lineWidth",
+          "description": "Stroke width of the grid lines in px. Default 1."
+        },
+        {
+          "name": "markSize",
+          "description": "Size of each registration mark in px. Default 8."
+        },
+        {
+          "name": "marks",
+          "description": "Registration mark at each intersection: \"square\" (default), \"cross\" or \"none\"."
+        },
+        {
+          "name": "mobile",
+          "description": "Options that replace their desktop values below `breakpoint`, e.g. {columns: 1, rows: 4}."
+        },
+        {
+          "name": "position",
+          "description": "\"fixed\" (default) pins the grid to the viewport; \"absolute\" fills the nearest positioned ancestor."
+        },
+        {
+          "name": "raster",
+          "description": "Raster op nodes for the overlay, e.g. an offset driven by hover to bend the lines near the cursor."
+        },
+        {
+          "name": "readouts",
+          "description": "Labels beside intersections: [{id, col, row, text, anchor}]. col/row index lines from 0; anchor \"br\" (default), \"bl\", \"tr\" or \"tl\", flipped automatically when the label would fall outside. Decorative — say the same thing in real page text."
+        },
+        {
+          "name": "rows",
+          "description": "Rows across the overlay's height, counted as cells. 0 draws no horizontal lines. Default 2."
+        },
+        {
+          "name": "type",
+          "description": "The element type, which selects the mapper that builds it -- \"h1\", \"cards\", \"form\", and so on."
+        },
+        {
+          "name": "uppercase",
+          "description": "Uppercase the readout text. Default true."
+        },
+        {
+          "name": "zIndex",
+          "description": "Stacking order of the overlay. Default 2 — keep navigation above it."
+        }
+      ]
     }
   },
   "summary": {
-    "types": 35,
-    "resolved": 35,
+    "types": 36,
+    "resolved": 36,
     "unresolved": 0
   }
 }