nodality 1.2.11 → 1.3.1

package/lib/element-mapper.js

@@ -1,5 +1,5 @@
 /*!
- * nodality v1.2.11
+ * nodality v1.3.1
  * (c) 2026 Filip Vabrousek
  * License: MIT
  */
@@ -88,6 +88,17 @@ const ELEMENT_TYPES = [
 // ignoring it was the defect Stage 4 fixes - throwing on it would be a worse
 // one. Missing fields are filled rather than left undefined, because the
 // mapper derives an id from the title and a missing title threw.
+// One id, however it was spelled. `#hero` and `hero` name the same element,
+// and until now which one worked depended on the subsystem: raster targeting
+// matched by exact string, morph-node stripped the hash, and chainReact
+// required it. Both spellings are accepted everywhere now, and neither is made
+// canonical — normalising only at the point of comparison means every existing
+// page keeps working whichever it used.
+const sameId = (a, b) => {
+    const bare = (v) => typeof v === "string" && v.charAt(0) === "#" ? v.slice(1) : v;
+    return bare(a) === bare(b);
+};
+
 const navEntry = (i) =>
     (typeof i === "string" || typeof i === "number")
         ? { title: String(i), link: "#e" }
@@ -202,8 +213,12 @@ class ElementMapper { // 22:09:58 04/11/2024
                   font: "Arial"
               },
               headStyle: {
+                  // White on #ff6d22 measured 2.81:1 against a 4.5:1
+                  // requirement — a header that reads as styled and is not
+                  // legible. #c2410c is 5.18:1, and is where the card title
+                  // moved to, so the palette stays one palette.
                   color: "white",
-                  background: "#ff6d22"
+                  background: "#c2410c"
               },
               border: "2px solid black",
               center: true,
@@ -546,6 +561,21 @@ animation: {
         return this.attachRaster(new FloatingInput()
           .set({
                   type: el.inputType ?? "input",
+                  // FloatingInput calls it `title`; every generator and every
+                  // UI kit calls it `label`, and both solvers in the eval
+                  // wrote `label`. The field it produced then had no
+                  // accessible name at all — a placeholder is not one, since
+                  // it disappears the moment anyone types.
+                  //
+                  // `text` joined them after Tier 7. A model wrote
+                  // `{type:"labelInput", text:"Name"}` and the field rendered
+                  // the literal string "undefined" as its label, its
+                  // placeholder and its accessible name, while validate_nodes
+                  // reported ok — the worst available outcome for a spelling
+                  // this natural. Tier 6's rule applies: take what the world
+                  // already writes. `title` still wins, then `label`.
+                  ...(el.title === undefined && (el.label !== undefined || el.text !== undefined)
+                      ? { title: el.label !== undefined ? el.label : el.text } : {}),
                   ...this.elOpts(el),
               }), el, obj.customOptions);
       }
@@ -578,6 +608,13 @@ animation: {
 
 
     static dropdown(obj){
+        // A label for the trigger, which is what makes every declared option
+        // selectable. Without one the first item becomes the label and is
+        // spent — `items: ["CZE","POL","DEU"]` offered two. `label` is the
+        // name a generator reaches for (it is what <select> and every UI kit
+        // call it); `title` is what the component calls it, so both are taken.
+        const ddLabel = obj.el.label ?? obj.el.title;
+
         if (!obj.el.items){
             obj.el.items = ["Flower", "Car", "Maseratti"];
         }
@@ -604,6 +641,9 @@ animation: {
         // `raster:` option here would be silently dropped.
         const dd = new Dropdown()
         .set({
+          // Supplied only when there is one, so a dropdown without a label
+          // keeps the shape it always had, byte for byte.
+          ...(ddLabel === undefined ? {} : { title: ddLabel }),
           behaviour: "click", // click otherwise
           //width: "120px",
         
@@ -623,7 +663,7 @@ animation: {
           new Text("Option 3"),*/
       
           
-          new Text(obj.el.items[0]).set({
+          ...(ddLabel !== undefined ? [] : [new Text(obj.el.items[0]).set({
             font: "Arial",
             fluidc: "S6",
           weight: "bold",
@@ -635,10 +675,12 @@ animation: {
             },
           pad: [{l: 10, r: 10}],
        
-          }),
+          })]),
       
           new Wrapper().set({border: "1px solid green", background: "#1abc9c", radius: "0.7rem", socenter: true})
-          .add(items.slice(1)
+          // Every item is an option when the trigger carries its own label;
+         // otherwise the first is spent on the label, as before.
+         .add(ddLabel === undefined ? items.slice(1) : items
 
          /* new Text("Option 1o").set({font: "Arial",  pad: [{a: 10}],}),
           new Text("Option 2").set({font: "Arial",  pad: [{a: 10}],}),
@@ -719,8 +761,10 @@ alert("PP")
         const navItems = Array.isArray(obj.el?.items) && obj.el.items.length
             ? obj.el.items.map(navEntry)
             : null;
+        // `pad` gives the link a hit area: unpadded these measured 43x18,
+        // under the 24px WCAG 2.2 minimum in the direction a thumb needs.
         const navLinks = () => navItems.map((i) =>
-            new Link().set({ text: i.title, url: i.link }));
+            new Link().set({ text: i.title, url: i.link, pad: [{ tb: 8, lr: 4 }] }));
 
         let links = items.map((i, o) => new Link(`"${i.title}"`)
         .set({
@@ -1114,6 +1158,12 @@ new Wrapper().set({
 
         // Phase S4, as protoNav above: `items` carries {title, link}; absent,
         // the placeholders are used exactly as before.
+        // Whether the caller supplied anything, kept separate from `items`
+        // itself: the placeholders carry a `link` of their own that was never
+        // rendered, so honouring it now would change output that has to stay
+        // byte-identical. Supplied entries use their link; placeholders keep
+        // the hardcoded url they have always rendered.
+        const suppliedNav = Array.isArray(obj.el?.items) && obj.el.items.length > 0;
         let items = Array.isArray(obj.el?.items) && obj.el.items.length
             ? obj.el.items.map(navEntry)
             : [
@@ -1139,7 +1189,11 @@ new Wrapper().set({
             text: i.title,
             link: i.link,
             isNavA: true,
-            url: "#e",
+            // The caller's link, not a hardcoded one. `link:` is not read by
+            // Link — `url` is what becomes the href — so declaring a link here
+            // used to render a fixed value regardless, which is the silent
+            // no-op this whole plan exists to remove.
+            url: suppliedNav ? (i.link || "#e") : "#e",
             id: "#" + i.title.toLowerCase(),
             font: "Arial",
             pad: [{a:20}], 
@@ -1240,7 +1294,11 @@ new Wrapper().set({
             text: i.title,
             link: i.link,
             isNavA: true,
-            url: "#myURL",
+            // The caller's link, not a hardcoded one. `link:` is not read by
+            // Link — `url` is what becomes the href — so declaring a link here
+            // used to render a fixed value regardless, which is the silent
+            // no-op this whole plan exists to remove.
+            url: suppliedNav ? (i.link || "#myURL") : "#myURL",
             id: "#" + i.title.toLowerCase(),
             font: "Arial",
             pad: [{a:20}], 
@@ -1347,7 +1405,11 @@ if (obj.el.dropdown){
             radius: "1rem",
             isSide: true,
             background: "#ecf0f1",
-            hamColour: {opened: "#1abc9c", closed: "#e67e22"},
+            // Both hamburger states measured under 3:1 on white at 26px:
+            // #e67e22 was 2.48:1 and #1abc9c 2.16:1. Same hues, dark enough
+            // to be seen — and #c2410c is the orange the cards and the table
+            // header moved to, so one palette rather than three.
+            hamColour: {opened: "#0f766e", closed: "#c2410c"},
             mobileSize: "1.2em",
             fixed: true,
             tags: {open: "sidebar:open", close: "sidebar:closed"}
@@ -1518,6 +1580,12 @@ let elo = new Polygon({ id: "hex" })
                 class: el.class,
                 color: el.color,
                 size: this.getElType(el.type), // update 23/07/2025
+                //@ tag: Heading level to render, independent of the type's size.
+                // Without this the option exists on the component and is not
+                // reachable from a spec, which for a data-first format means it
+                // does not exist. The card template uses it; an author writing
+                // {type:"h5", tag:"h2"} must get the same lever.
+                tag: el.tag,
                 font: el.font ?? "Arial",
                // index: obj.i + "",
                // keySet: {key: "border", value: "3px solid green"},
@@ -1678,15 +1746,12 @@ const blast    = this.filtero("blast", el.id, obj.customOptions);
             })
             .items([
                 new Image(item.img).set({isFull: true, url: item.img}),
-                // #f97316 rather than the CSS keyword orange (rgb 255,165,0), a legacy
-                // value that reads yellow beside modern palettes. No backticks here:
-                // this block lives inside a template literal and is evaluated as
-                // source, so module scope is not visible either.
-                new Text(item.title).set({ size: "S5", color: "#f97316" }),
+                // #c2410c is 5.18:1 on white; h2 keeps the outline intact.
+                new Text(item.title).set({ size: "S5", tag: "h2", color: "#c2410c" }),
                 new Link("Link").set({
                     text: item.title, 
                     url: item.link, 
-                    background: "#3498db", 
+                    background: "#1d6fe0", 
                     pad: [{ lr: "0.5rem", tb: "1rem" }], 
                     radius: "0.4rem", 
                     color: "white",
@@ -1694,6 +1759,28 @@ const blast    = this.filtero("blast", el.id, obj.customOptions);
                 })
             ])`;
 
+    // WHY THE CARD'S COLOURS AND HEADING LEVEL ARE WHAT THEY ARE.
+    //
+    // Kept OUT of the template above on purpose. Everything inside that string
+    // is source the developer receives, so a paragraph of rationale there is a
+    // paragraph in every generated page: fourteen lines of commentary about
+    // contrast ratios added 700 characters to the emitted output before this
+    // was noticed. Moving it here — and taking the older four-line note with
+    // it — left the emission 235 characters SMALLER than before this work.
+    //
+    // The title was #f97316, chosen over the CSS keyword orange because that
+    // reads yellow beside modern palettes. A considered choice that measured
+    // 2.80:1 on white against a 3:1 requirement and missed it by a margin
+    // nobody catches by looking. #c2410c is 5.18:1 and clears both the large-
+    // and small-text thresholds whatever size the title renders at. The link
+    // background moved from #3498db (white on it: 3.15:1) to #1d6fe0 (4.77:1),
+    // already this library's blue elsewhere.
+    //
+    // The tag option decouples the document outline from the type scale: the
+    // title stays S5-sized and stops being an h5, which made every page with
+    // an h1 above a card grid skip h2, h3 and h4 at once. h2, because a card
+    // grid is normally a section of a page rather than a subsection of one;
+    // pass tag to nest it deeper.
     // zoom card block (string template)
     const zoomCard = `
         new ZoomCard()
@@ -1705,11 +1792,11 @@ const blast    = this.filtero("blast", el.id, obj.customOptions);
                 useBrightness: true
             })
             .items([
-                new Text(item.title).set({ fluidc: "S6", color: "#f97316" }),
+                new Text(item.title).set({ fluidc: "S6", tag: "h2", color: "#c2410c" }),
                 new Link("Link").set({
                     text: item.title, 
                     url: item.link, 
-                    background: "#3498db", 
+                    background: "#1d6fe0", 
                     pad: [{ lr: "0.5rem", tb: "1rem" }], 
                     radius: "0.4rem", 
                     color: "white"
@@ -1806,12 +1893,23 @@ const blast    = this.filtero("blast", el.id, obj.customOptions);
         const shorthand = items.filter((it) => !isSpecList(it));
         const specLists = items.filter(isSpecList);
 
+        // Alt text, forwarded only when some entry carries it. The template
+        // is emitted SOURCE, so anything added here is paid by every generated
+        // page — including the no-items path, whose output is pinned byte for
+        // byte. Widening the template only when the data needs it keeps that
+        // pin intact and still lets the terse form describe its images, which
+        // matters because the terse form is the one a generator reaches for.
+        const altTemplate = (tpl) =>
+            shorthand.some((it) => it && it.alt !== undefined)
+                ? tpl.replace("url: item.img}", "url: item.img, alt: item.alt}")
+                : tpl;
+
         // Every entry is shorthand: keep the `.map()` form, so the emitted
         // code stays as compact as the hand-written equivalent and the
         // template is still paid once.
         if (specLists.length === 0) {
             return `${JSON.stringify(shorthand, null, 2).split("\n").map((l, i) => i === 0 ? l : "      " + l).join("\n")}.map(item => 
-        ${cardTemplate}
+        ${altTemplate(cardTemplate)}
       )`;
         }
 
@@ -1852,9 +1950,9 @@ const blast    = this.filtero("blast", el.id, obj.customOptions);
         return `new Card()
             .set({ width: "300px", height: "700px", radius: "0.7rem", mar: { sides: ["all"], value: "0.8rem" } })
             .items([
-              new Image(${s(item.img)}).set({isFull: true, url: ${s(item.img)}}),
-              new Text(${s(item.title)}).set({ size: "S5", color: "#f97316" }),
-              new Link("Link").set({ text: ${s(item.title)}, url: ${s(item.link)}, background: "#3498db", pad: [{ lr: "0.5rem", tb: "1rem" }], radius: "0.4rem", color: "white" })
+              new Image(${s(item.img)}).set({isFull: true, url: ${s(item.img)}${item.alt === undefined ? "" : `, alt: ${s(item.alt)}`}}),
+              new Text(${s(item.title)}).set({ size: "S5", tag: "h2", color: "#c2410c" }),
+              new Link("Link").set({ text: ${s(item.title)}, url: ${s(item.link)}, background: "#1d6fe0", pad: [{ lr: "0.5rem", tb: "1rem" }], radius: "0.4rem", color: "white" })
             ])`;
     }
 
@@ -2065,7 +2163,7 @@ static form(obj){
             .filter(l => l.op.name === name)
             .filter(l => {
                 if (l.target) {
-                    return l.target.includes(id)
+                    return l.target.some((t) => sameId(t, id));
                 } else {
                     return true;
                 }
@@ -2116,7 +2214,7 @@ static form(obj){
     static filteroRaster(id, customOptions) {
         const list = (customOptions || []).filter((l) =>
             l && typeof l.op === "string" && RASTER_OP_NAMES.includes(l.op) &&
-            (!l.target || (id && l.target.includes(id))));
+            (!l.target || (id && l.target.some((t) => sameId(t, id)))));
         return list.length > 0 ? list : undefined;
     }
 }

package/lib/element-params.generated.js

@@ -1,5 +1,5 @@
 /*!
- * nodality v1.2.11
+ * nodality v1.3.1
  * (c) 2026 Filip Vabrousek
  * License: MIT
  */
@@ -8,4 +8,4 @@
 // Every parameter name any element type reads, recovered from source.
 // Used for near-miss typo detection in validate-nodes.js. A drift test
 // regenerates this and fails if it differs, so it cannot rot silently.
-export const ELEMENT_PARAM_NAMES = ["absolute","accept","action","align","alignIts","animate","animation","area","arrayMargin","arrayPadding","at","auto","backTo","background","backgroundCard","backgroundColor","backgroundOp","behaviour","blast","blastData","block","bold","border","borderObj","borderObja","borderRadius","brand","breakWord","breakpoints","cellAlign","cellPadding","center","centerColumn","centered","checkedBackgroundColor","children","clampc","class","clipPath","code","color","column","contentWidth","cursor","customAlign","customJustify","customStyle","data","diameter","disp","dropdown","em","exact","filter","filtera","fixMobileTap","fixed","flex","flexCenter","flexDir","fluid","fluidc","font","frame","ga","gap","gpos","gradient","hamColour","hamburgerColour","headStyle","height","hideField","hover","icon","id","img","index","initLetter","inline","inpad","inputType","isFull","isHidden","isNavA","italic","items","keySet","kind","label","layout","left","length","link","map","mar","margin","marginOp","maxHeight","maxWidth","mboth","method","mobile","multiple","name","new","nowrap","offcanvas","okayColor","onScroll","onTap","opacity","overflow","pad","padding","placeholder","position","positions","preffersId","radius","ranges","raster","react","removeDecoration","required","resmar","respad","responsive","resprop","rounded","scale","sequence","shadow","sides","simpleBorder","simpleCenter","size","span","sticky","stretch","stroke","style","svg","tags","templateCols","text","theme","tint","title","top","transform","transition","type","url","useBrightness","value","vtn","weight","width","x","y","zIndex"];
+export const ELEMENT_PARAM_NAMES = ["absolute","accept","action","align","alignIts","alignTo","aligns","alt","animate","animation","area","arrayMargin","arrayPadding","as","at","auto","backTo","background","backgroundCard","backgroundColor","backgroundOp","behaviour","blast","blastData","block","bold","border","borderObj","borderObja","borderRadius","brand","breakWord","breakpoints","cellAlign","cellPadding","center","centerColumn","centerSelf","centered","checkedBackgroundColor","child","children","clampc","class","clipPath","code","colat","color","column","contentWidth","cursor","customAlign","customJustify","customStyle","data","decoding","diameter","disp","dropdown","em","exact","fetchPriority","filter","filtera","fitContent","fixMobileTap","fixed","flex","flexCenter","flexDir","fluid","fluidc","font","frame","ga","gap","gpos","gradient","hamColour","hamburgerColour","headStyle","height","hideField","hideOverflow","hover","icon","id","img","index","initLetter","inline","inpad","inputType","isBackground","isFull","isHidden","isLink","isNavA","italic","items","justifo","justify","keySet","kind","label","layout","left","length","link","loading","map","mar","margin","marginOp","maxHeight","maxWidth","mboth","method","minHeight","mobile","multiple","name","new","nowrap","objectFit","objectPosition","offcanvas","okayColor","onScroll","onTap","opacity","overflow","owrap","pad","padding","placeholder","position","positions","preffersId","radius","ranges","raster","react","removeDecoration","required","resmar","respad","responsive","resprop","rounded","scale","sequence","shadow","sides","simpleBorder","simpleCenter","size","sizes","span","srcset","sticky","stretch","stroke","style","stype","svg","tag","tags","templateCols","text","theme","tint","title","toColumn","top","transform","transition","type","url","useBrightness","value","vtn","weight","width","wrap","x","y","zIndex"];

package/lib/keyframe-animation.js

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

package/lib/link-getter.js

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

package/lib/morph-node.js

@@ -1,5 +1,5 @@
 /*!
- * nodality v1.2.11
+ * nodality v1.3.1
  * (c) 2026 Filip Vabrousek
  * License: MIT
  */
@@ -142,6 +142,13 @@ const norm = (t) => String(t || "").replace(/\s+/g, " ").trim().toLowerCase();
 const bareId = (id) =>
     typeof id === "string" && id.startsWith("#") ? id.slice(1) : id;
 
+// The DOM id a component actually carries, which is not always the bare one:
+// nav and sideNav emit `id="#docs"`, hash included, because animator.js used
+// to require the hash to match. Both spellings are now accepted on both sides,
+// and this is the lookup half — an element is found whether its id was written
+// with the hash or without.
+export const idMatches = (a, b) => bareId(a) === bareId(b);
+
 /**
  * A morph node, in one shape: a list of EDGES.
  *

package/lib/normalize-spec.js

@@ -0,0 +1,134 @@
+/*!
+ * nodality v1.3.1
+ * (c) 2026 Filip Vabrousek
+ * License: MIT
+ */
+
+/**
+ * Tier 6 of AGENTIC-FIRST-PLAN.md §10 — accept what the world already writes.
+ *
+ * MEASURED FIRST. Running claude-sonnet-5 over the 24-brief eval scored 17/24
+ * against 23/24 for a hand-written solver, and **four of the seven failures
+ * were one mistake wearing different clothes**: the model reached for the name
+ * HTML uses and the library wanted another.
+ *
+ *     src      ->  url      an <img> has src. Two briefs lost to this.
+ *     href     ->  url      an <a> has href.
+ *     options  ->  items    a <select> has options.
+ *
+ * These are not typos, so the did-you-mean built in Stage 3 cannot reach them:
+ * `src` is three edits from `url`. And a model writing `src` for an image is
+ * not confused — it is applying the most widely attested convention there is.
+ * The divergence bought nothing and cost three briefs in twenty-four.
+ *
+ * The same measurement found one more failure of the same shape rather than
+ * the same name: a table's rows written as arrays, header row first, which is
+ * how every CSV and every markdown table on earth is laid out. That is handled
+ * here too — see `normalizeShapes`.
+ *
+ * Purely additive. A spec that uses the canonical names and shapes is
+ * untouched, so no existing page can observe this. Where both are present the canonical name
+ * wins and the collision is REPORTED rather than silently resolved, because
+ * quietly dropping a key the author wrote is the exact failure this project
+ * has spent every stage removing.
+ */
+
+/** alias -> canonical. Deliberately short: each entry has to earn its place by
+ *  being what a generator actually writes, not by being plausible. */
+export const ALIASES = Object.freeze({
+    src: "url",
+    href: "url",
+    options: "items",
+});
+
+const CANONICAL = new Set(Object.values(ALIASES));
+
+/** Walk children and items as well, so nested specs get the same treatment. */
+const walk = (node, fn) => {
+    if (Array.isArray(node)) return node.map((n) => walk(n, fn));
+    if (!node || typeof node !== "object") return node;
+    const out = fn({ ...node });
+    for (const key of ["children", "items"]) {
+        if (out[key] !== undefined) out[key] = walk(out[key], fn);
+    }
+    return out;
+};
+
+/** Rewrite every alias to its canonical name. */
+export function normalizeAliases(elements) {
+    return walk(elements, (node) => {
+        for (const [alias, canonical] of Object.entries(ALIASES)) {
+            if (!Object.prototype.hasOwnProperty.call(node, alias)) continue;
+            // Canonical wins. `aliasConflicts` is what tells the author.
+            if (!Object.prototype.hasOwnProperty.call(node, canonical)) {
+                node[canonical] = node[alias];
+            }
+            delete node[alias];
+        }
+        return node;
+    });
+}
+
+/**
+ * Places where an alias and its canonical name are both present with
+ * DIFFERENT values — one of them is going to be ignored, and the author should
+ * hear it from the validator rather than discover it in the page.
+ */
+export function aliasConflicts(elements, at = "elements") {
+    const found = [];
+    const visit = (node, path) => {
+        if (Array.isArray(node)) return node.forEach((n, i) => visit(n, `${path}[${i}]`));
+        if (!node || typeof node !== "object") return;
+        for (const [alias, canonical] of Object.entries(ALIASES)) {
+            if (Object.prototype.hasOwnProperty.call(node, alias) &&
+                Object.prototype.hasOwnProperty.call(node, canonical) &&
+                JSON.stringify(node[alias]) !== JSON.stringify(node[canonical])) {
+                found.push({ path: `${path}.${alias}`, alias, canonical });
+            }
+        }
+        for (const key of ["children", "items"]) {
+            if (node[key] !== undefined) visit(node[key], `${path}.${key}`);
+        }
+    };
+    visit(elements, at);
+    return found;
+}
+
+/** Every name this module accepts, for the validator's vocabulary. */
+export const ALIAS_NAMES = Object.freeze(Object.keys(ALIASES));
+export const isCanonical = (name) => CANONICAL.has(name);
+
+
+/**
+ * Shapes that are not the library's but are what everyone writes.
+ *
+ * A table's rows as ARRAYS, header row first:
+ *
+ *     items: [["date","race"], ["29/08","Krusnoman"]]
+ *       ->   items: [{ date: "29/08", race: "Krusnoman" }]
+ *
+ * The model in the Tier 2b run wrote exactly this, and it is the layout of
+ * every CSV and every markdown table there is. Header-first is not a guess:
+ * a table whose first row is data has no column names at all, and the mapper
+ * needs them to build the head.
+ *
+ * Narrow on purpose — `table` only, and only when EVERY entry is an array.
+ * A mixed list is left alone rather than half-converted.
+ */
+export function normalizeShapes(elements) {
+    return walk(elements, (node) => {
+        if (node.type !== "table" || !Array.isArray(node.items) || node.items.length < 2) return node;
+        if (!node.items.every((r) => Array.isArray(r))) return node;
+
+        const [head, ...rows] = node.items;
+        if (!head.every((h) => typeof h === "string" || typeof h === "number")) return node;
+        node.items = rows.map((row) =>
+            Object.fromEntries(head.map((key, i) => [String(key), row[i]])));
+        return node;
+    });
+}
+
+/** Both passes, in the order the caller wants: names first, then shapes. */
+export function normalizeSpec(elements) {
+    return normalizeShapes(normalizeAliases(elements));
+}

package/lib/parse-html.js

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

package/lib/raster-inspect.js

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

package/lib/raster-ops.js

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

package/lib/raster-presets.js

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

package/lib/resolve-refs.js

@@ -0,0 +1,121 @@
+/*!
+ * nodality v1.3.1
+ * (c) 2026 Filip Vabrousek
+ * License: MIT
+ */
+
+/**
+ * Tier 3 of AGENTIC-FIRST-PLAN.md §10 — declare shared structure once.
+ *
+ * MEASURED FIRST, as the plan asked. Chrome taken from a real site: a nav and
+ * a footer are 184 tokens, and **61% of every token in that site is the same
+ * nav and footer**. Referencing rather than repeating them is 1.98x at ten
+ * pages and 2.10x at twenty — and a NET LOSS at one page, which is why this is
+ * opt-in and why nothing changes for a caller who never uses it.
+ *
+ * The reason it is needed is not that the data format is verbose. The site
+ * used for that measurement does not repeat itself: it imports `renderNav`
+ * from a shared module and calls it. That is the imperative layer, where reuse
+ * is just a function. An element array cannot call a function, so an agent
+ * authoring as data pays for the chrome once per page, and the only way out is
+ * to drop into code — which is what property 1, "total", exists to prevent.
+ * A human never feels this and an agent always does.
+ *
+ *     new Des()
+ *       .defs({ nav: { type: "nav", items: [...] } })
+ *       .add([{ $ref: "nav" }, { type: "h1", text: "Page" }])
+ *
+ * The definitions are ordinary data, so they serialise, ship in one file, and
+ * are imported by every page's entry — the sharing is a plain import of a
+ * plain object, not a new authoring mode.
+ */
+
+/** The key that marks a reference. `$`-prefixed so it cannot collide with a
+ *  parameter name: the schema's vocabulary is all bare identifiers. */
+export const REF_KEY = "$ref";
+
+/** True for `{ $ref: "name" }` and nothing else. */
+export const isRef = (v) =>
+    !!v && typeof v === "object" && !Array.isArray(v) && typeof v[REF_KEY] === "string";
+
+/** Every name referenced anywhere in a spec, with the path that reached it. */
+export function collectRefs(elements, at = "elements") {
+    const found = [];
+    const walk = (node, path) => {
+        if (Array.isArray(node)) return node.forEach((n, i) => walk(n, `${path}[${i}]`));
+        if (!node || typeof node !== "object") return;
+        if (isRef(node)) { found.push({ name: node[REF_KEY], path }); return; }
+        for (const key of ["children", "items"]) {
+            if (node[key] !== undefined) walk(node[key], `${path}.${key}`);
+        }
+    };
+    walk(elements, at);
+    return found;
+}
+
+/**
+ * Replace every `{ $ref: name }` with a deep copy of `defs[name]`.
+ *
+ * A copy, not the definition itself: two pages referencing one nav must not
+ * share an object the mapper then mutates — rendering an `a` already adds
+ * `font` and `pad` to the descriptor it is given, so a shared definition would
+ * accumulate the leavings of every page that used it.
+ *
+ * An unresolvable reference is left in place rather than dropped or guessed.
+ * The validator reports it as DANGLING_REF with a did-you-mean; silently
+ * removing it would make a missing nav look like a page that never had one.
+ */
+export function resolveRefs(elements, defs, seen = new Set()) {
+    if (!defs || typeof defs !== "object") return elements;
+
+    const expand = (node) => {
+        if (Array.isArray(node)) return node.map(expand);
+        if (!node || typeof node !== "object") return node;
+
+        if (isRef(node)) {
+            const name = node[REF_KEY];
+            if (!Object.prototype.hasOwnProperty.call(defs, name)) return node;
+            if (seen.has(name)) {
+                // A definition that reaches itself. Returning the ref rather
+                // than recursing means a cycle is a reported error instead of
+                // a stack overflow at render time.
+                return node;
+            }
+            const next = new Set(seen).add(name);
+            const base = resolveRefs([defs[name]], defs, next)[0];
+
+            // Keys written BESIDE the reference override the definition.
+            //
+            // Without this they were silently dropped — `{ $ref: "nav", id:
+            // "topnav" }` expanded to the bare definition and the id went
+            // nowhere, which is precisely the declared-but-ignored failure
+            // this project spent six stages removing. Having built a new one,
+            // the choice was to reject the shape or to honour it; honouring it
+            // is what makes a shared fragment reusable at all, since the whole
+            // point of sharing a nav is that each page marks a different entry.
+            //
+            // Shallow, deliberately: a deep merge would make it unclear
+            // whether `items` replaces the definition's or extends it. It
+            // replaces.
+            const { [REF_KEY]: _drop, ...overrides } = node;
+            return Object.keys(overrides).length
+                ? { ...(base && typeof base === "object" ? base : {}), ...overrides }
+                : base;
+        }
+
+        const out = { ...node };
+        for (const key of ["children", "items"]) {
+            if (out[key] !== undefined) out[key] = expand(out[key]);
+        }
+        return out;
+    };
+
+    return Array.isArray(elements) ? elements.map(expand) : elements;
+}
+
+/** Names defined but never referenced — dead weight in a shared file. */
+export function unusedDefs(elements, defs) {
+    if (!defs) return [];
+    const used = new Set(collectRefs(elements).map((r) => r.name));
+    return Object.keys(defs).filter((n) => !used.has(n));
+}

package/lib/scroll-video.js

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