nodality 1.2.10 → 1.3.0

package/lib/designer.js

@@ -1,5 +1,5 @@
 /*!
- * nodality v1.2.10
+ * nodality v1.3.0
  * (c) 2026 Filip Vabrousek
  * License: MIT
  */
@@ -13,6 +13,8 @@ import { ElementMapper } from "../lib/element-mapper.js";
 import { applyMorphNodes } from "../lib/morph-node.js";
 import { installAgentSurface } from "../lib/webmcp-adapter.js";
 import { annotateRoundTrip } from "../lib/parse-html.js";
+import { resolveRefs, collectRefs } from "../lib/resolve-refs.js";
+import { normalizeSpec } from "../lib/normalize-spec.js";
 import { Animator } from "../layout/animator.js";
 import { Base } from "../layout/base.js";
 import { Text } from "../layout/text.js";
@@ -435,7 +437,33 @@ new Text("row.").set({
         // Kept for phase T: a morph node resolves `from`/`to` ids against
         // the rendered children BY POSITION, so it needs the descriptor
         // order — components do not all carry their id into the DOM.
-        this._elements = Array.isArray(arr) ? arr : [];
+        // Tier 3: `{ $ref: "name" }` is expanded here, so everything
+        // downstream — the mapper, morph nodes resolving by position, the
+        // agent surface, annotation — sees ordinary elements and needs no
+        // knowledge of references at all. No defs, no change: `resolveRefs`
+        // returns its input untouched.
+        arr = resolveRefs(Array.isArray(arr) ? arr : [], this._defs);
+
+        // Tier 6: `src`/`href` mean `url`, `options` means `items`. Rewritten
+        // once, here, so the mapper and every component below it only ever see
+        // the canonical names and none of them needs to know an alias exists.
+        // Additive — a spec using the canonical names comes through unchanged.
+        arr = normalizeSpec(arr);
+
+        // A name with no definition is refused here, naming what is defined.
+        // Left alone it reaches the mapper as an element with no `type` and
+        // fails as `Unknown element type "undefined"`, which sends the reader
+        // looking for a typo in a type rather than a missing definition.
+        {
+            const dangling = collectRefs(arr).filter(
+                (r) => !this._defs || !Object.prototype.hasOwnProperty.call(this._defs, r.name));
+            if (dangling.length) {
+                const defined = Object.keys(this._defs || {});
+                throw new Error(
+                    `[nodality] no definition for $ref "${dangling[0].name}" at ` +
+                    `${dangling[0].path}. Defined: ${defined.length ? defined.join(", ") : "(none)"}`);
+            }
+        }
 
         this.css = [];
         this.elCSS = [];
@@ -466,6 +494,15 @@ customOptions.forEach(item => {
           ...arr.filter((e) => !e || (e.type !== "nav" && e.type !== "sideNav")),
         ];
 
+        // Recorded AFTER the lift, not before. Everything that consumes
+        // `_elements` matches it against rendered children BY POSITION —
+        // morph resolving `from`/`to`, and the round-trip writing each
+        // descriptor onto the node it produced. The array was being stored in
+        // the author's order while the page rendered in this one, so any spec
+        // with a nav after another element mapped descriptors to the wrong
+        // nodes. Found while wiring Tier 3, which needed the same array.
+        this._elements = arr;
+
         for (var i = 0; i < arr.length; i++) {
             let el = arr[i];
             let ela = null;
@@ -1339,6 +1376,31 @@ new Slider(texts, null, { tintColor: "#e74c3c", inactiveColor: "#ccc" })
         return this;
     }
 
+    /**
+     * Shared fragments, referenced from E as `{ $ref: "name" }`.
+     *
+     * Ordinary data: one object, imported by every page's entry, so the
+     * sharing is a plain import rather than a new authoring mode. Worth it
+     * from two pages up — at one page a reference costs more than inlining,
+     * which is why nothing here is automatic.
+     *
+     * MUST be called before `add`. `add` renders as it goes, so definitions
+     * arriving afterwards are simply too late — and the failure was
+     * "Unknown element type undefined" from deep in the mapper, which says
+     * nothing about the real mistake. The wrong order is now refused where it
+     * happens, in the words of the thing the caller did.
+     */
+    defs(map) {
+        if (this._elements !== undefined) {
+            throw new Error(
+                '[nodality] .defs() must come before .add(): add() renders as it ' +
+                'goes, so definitions given afterwards cannot be used. Chain it as ' +
+                'new Des().defs({ ... }).nodes(N).add(E)');
+        }
+        this._defs = (map && typeof map === "object" && !Array.isArray(map)) ? map : {};
+        return this;
+    }
+
     set(obj) {
         // Emit-only mode: invoked from `nodality compile`. Capture the
         // imperative code array (the same content the `code: true` on-page

package/lib/element-mapper.js

@@ -1,5 +1,5 @@
 /*!
- * nodality v1.2.10
+ * nodality v1.3.0
  * (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,13 @@ 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.
+                  ...(el.label !== undefined && el.title === undefined
+                      ? { title: el.label } : {}),
                   ...this.elOpts(el),
               }), el, obj.customOptions);
       }
@@ -578,6 +600,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 +633,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 +655,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 +667,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 +753,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 +1150,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 +1181,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 +1286,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 +1397,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 +1572,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 +1738,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 +1751,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 +1784,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 +1885,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 +1942,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 +2155,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 +2206,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.10
+ * nodality v1.3.0
  * (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","alt","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","tag","tags","templateCols","text","theme","tint","title","top","transform","transition","type","url","useBrightness","value","vtn","weight","width","x","y","zIndex"];

package/lib/keyframe-animation.js

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

package/lib/link-getter.js

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

package/lib/morph-node.js

@@ -1,5 +1,5 @@
 /*!
- * nodality v1.2.10
+ * nodality v1.3.0
  * (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.0
+ * (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.10
+ * nodality v1.3.0
  * (c) 2026 Filip Vabrousek
  * License: MIT
  */
@@ -47,6 +47,8 @@
  * this stage across mixed leaf-and-composite specs.
  */
 
+import { validateNodes } from "./validate-nodes.js";
+
 const HEADINGS = new Set(["h1", "h2", "h3", "h4", "h5", "h6"]);
 
 /** The attribute a page uses to carry its own descriptors. */
@@ -129,11 +131,21 @@ export function parseReport(html, doc) {
         if (one) spec.push(one);
         else unrecovered.push({ index: i, tag: (node.tagName || "").toLowerCase() });
     });
+    // What parse returns is UNTRUSTED. A `data-nod` attribute is just text in
+    // a document: hand-edited, served by someone else, or written by a version
+    // of the library that is not this one. The caller's next move is to render
+    // it, so the recovered spec is checked here rather than after it has
+    // already become a page. This is also the first place Stage 3 and Stage 5
+    // compose — the validator that makes a spec repairable is the one that
+    // makes a parsed spec safe.
+    const check = validateNodes([], spec);
+
     return {
-        ok: unrecovered.length === 0,
+        ok: unrecovered.length === 0 && check.ok,
         exact: kids.every((n) => n.getAttribute && n.getAttribute(SPEC_ATTR)),
         total: kids.length,
         spec,
         unrecovered,
+        errors: check.errors,
     };
 }

package/lib/raster-inspect.js

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

package/lib/raster-ops.js

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

package/lib/raster-presets.js

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