nodality 1.2.11 → 1.3.1

package/lib/seo.js

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

package/lib/stacker.js

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

package/lib/suggest.js

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

package/lib/theme.js

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

package/lib/transform-anim.js

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

package/lib/transition.js

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

package/lib/validate-nodes.js

@@ -1,5 +1,5 @@
 /*!
- * nodality v1.2.11
+ * nodality v1.3.1
  * (c) 2026 Filip Vabrousek
  * License: MIT
  */
@@ -30,6 +30,8 @@ import {
     FRAMEWORK_DOC, EASING_NAMES,
 } from "./raster-ops.js";
 import { presetNames, presetInfo } from "./raster-presets.js";
+import { collectRefs, isRef, resolveRefs } from "./resolve-refs.js";
+import { normalizeSpec, aliasConflicts, ALIASES } from "./normalize-spec.js";
 import { ELEMENT_TYPES } from "./element-mapper.js";
 import { ELEMENT_PARAM_NAMES } from "./element-params.generated.js";
 import { didYouMean, suggest, levenshtein } from "./suggest.js";
@@ -161,7 +163,16 @@ export const CONTENT_SLOT = {
     row: "children", form: "children", wrap: "children",
 };
 
-export function validateNodes(nodes, elements) {
+// Of the types that read `items`, which read the entries as ELEMENT SPECS
+// rather than as data. `ulist` maps every object entry through the mapper;
+// `cards`, `nav`, `sideNav` and `table` read theirs as data — nav entries are
+// `{title, link}`, table entries are rows — and walking those as elements
+// would report every correct page. Pinned against the mapper by a test rather
+// than trusted, because a hand-kept table beside a mapper is exactly what
+// drifted before 1.2.8.
+export const SPEC_ITEMS = new Set(["ulist"]);
+
+export function validateNodes(nodes, elements, defs) {
     const errors = [];
     const push = (code, path, got, suggestions, valid) => {
         errors.push({
@@ -219,6 +230,42 @@ export function validateNodes(nodes, elements) {
     // element whose `type` names nothing is not a silent no-op but a THROW
     // from the mapper at render time, which reaches a generator as a stack
     // trace rather than as a report it can repair from.
+    // Tier 3: a reference with no definition. Reported here as well as
+    // refused at render, because a report is repairable in one turn and a
+    // throw is not — the Stage 3 contract applied to the newest way of being
+    // wrong. `defs` is optional: without it references are left alone rather
+    // than all reported missing, since a caller may validate a page before
+    // deciding what to share.
+    if (defs && typeof defs === "object" && Array.isArray(elements)) {
+        const defined = Object.keys(defs);
+        for (const { name, path } of collectRefs(elements)) {
+            if (!Object.prototype.hasOwnProperty.call(defs, name)) {
+                push("DANGLING_REF", path, name, suggest(name, defined), defined);
+            }
+        }
+    }
+
+    // Walk the RESOLVED tree when definitions are available. A reference
+    // with keys beside it is a real element once merged, and only the merged
+    // form can be checked: `{ $ref: "nav", itms: [] }` is a typo in an
+    // override, and validating the unexpanded reference would miss it —
+    // a silent no-op inside the mechanism built to remove silent no-ops.
+    let toWalk = (defs && typeof defs === "object" && Array.isArray(elements))
+        ? resolveRefs(elements, defs)
+        : elements;
+
+    // An alias and its canonical name both present, disagreeing: one of them
+    // is going to be ignored. The author hears it here rather than finding it
+    // in the page.
+    for (const c of aliasConflicts(Array.isArray(elements) ? elements : [])) {
+        push("CONFLICTING_ALIAS", c.path, c.alias, [c.canonical],
+            [`"${c.alias}" is accepted as "${c.canonical}"; give one of them, not both`]);
+    }
+
+    // Walk the normalised tree, so `{type:"img", src:"..."}` is checked as the
+    // element it actually becomes rather than reported as an unknown parameter.
+    if (Array.isArray(toWalk)) toWalk = normalizeSpec(toWalk);
+
     if (idsKnown) {
         const walkEls = (list, at) => {
             if (!Array.isArray(list)) return;
@@ -239,6 +286,12 @@ export function validateNodes(nodes, elements) {
                     push("BAD_ELEMENT", p, el, [], ["{ type: \"<element type>\", ... }"]);
                     return;
                 }
+                // A reference is not an element and has no `type` by design.
+                // Its validity is whether the name resolves, which the
+                // DANGLING_REF pass above decides; reporting MISSING_FIELD
+                // here rejected every correct `$ref` there is.
+                if (isRef(el)) return;
+
                 if (typeof el.type !== "string") {
                     push("MISSING_FIELD", `${p}.type`, el.type, [],
                         ["an element type, e.g. \"h1\", \"wrap\", \"nav\""]);
@@ -252,6 +305,19 @@ export function validateNodes(nodes, elements) {
                 // removed for `cards`, surviving one slot over. It is not a
                 // typo, so near-miss detection cannot reach it.
                 const wants = CONTENT_SLOT[el.type];
+                if (wants) {
+                    // A content slot that is present but not a list. The
+                    // mapper tests `Array.isArray(...) && length`, so
+                    // `items: {…}` and `items: "x"` fall through to the
+                    // placeholders — content declared, content ignored, no
+                    // error. Same family as WRONG_CONTENT_SLOT: the key is
+                    // right and the value cannot carry anything.
+                    const given = el[wants];
+                    if (given !== undefined && given !== null && !Array.isArray(given)) {
+                        push("BAD_CONTENT_SHAPE", `${p}.${wants}`, given, [],
+                            [`an array — "${el.type}" reads \`${wants}\` as a list`]);
+                    }
+                }
                 if (wants) {
                     const other = wants === "items" ? "children" : "items";
                     const filled = (v) => Array.isArray(v) ? v.length > 0 : v != null;
@@ -325,9 +391,51 @@ export function validateNodes(nodes, elements) {
                         if (Array.isArray(entry)) walkEls(entry, `${p}.items[${k}]`);
                     });
                 }
+
+                // Phase S7: an object entry with no `type`, in a slot whose
+                // entries ARE elements. `{type:"ulist", items:[{text:"Fast"}]}`
+                // validated clean and then threw from deep in the mapper —
+                // `Unknown element type "undefined"` — which is the Stage 3
+                // contract exactly inverted: validate-then-render handed the
+                // agent a stack trace in the one place the tool exists to
+                // prevent it.
+                //
+                // Tier 7 measured what that cost. The throw names every valid
+                // type and not one word about WHICH entry, so it is the same
+                // string for every fault of this shape on any page; the weaker
+                // of the two models repaired none of them and returned a
+                // byte-identical spec. The suggestion below therefore hands
+                // back the replacement rather than describing it.
+                //
+                // A string entry is the shorthand and stays valid.
+                if (SPEC_ITEMS.has(el.type) && Array.isArray(el.items)) {
+                    el.items.forEach((entry, k) => {
+                        const at = `${p}.items[${k}]`;
+                        if (typeof entry === "string" || typeof entry === "number") return;
+                        if (Array.isArray(entry)) return;
+                        if (!entry || typeof entry !== "object") {
+                            push("BAD_ELEMENT", at, entry, [],
+                                ["a string, or { type: \"<element type>\", ... }"]);
+                            return;
+                        }
+                        if (isRef(entry)) return;
+                        if (typeof entry.type !== "string") {
+                            const text = ["text", "title", "label"]
+                                .map((k2) => entry[k2]).find((v) => typeof v === "string");
+                            push("MISSING_FIELD", `${at}.type`, entry.type,
+                                text === undefined ? []
+                                    : [JSON.stringify(text),
+                                       `{ "type": "p", "text": ${JSON.stringify(text)} }`],
+                                [`"${el.type}" reads each item as an element; a plain string is the shorthand`]);
+                        } else if (!ELEMENT_TYPES.includes(entry.type)) {
+                            push("UNKNOWN_ELEMENT_TYPE", `${at}.type`, entry.type,
+                                suggest(entry.type, ELEMENT_TYPES), ELEMENT_TYPES);
+                        }
+                    });
+                }
             });
         };
-        walkEls(elements, "elements");
+        walkEls(toWalk, "elements");
     }
 
     nodes.forEach((node, i) => {

package/lib/webmcp-adapter.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nodality",
-  "version": "1.2.11",
+  "version": "1.3.1",
   "description": "A lightweight library for declarative UI elements.",
   "main": "dist/index.cjs.js",
   "module": "dist/index.esm.js",
@@ -33,6 +33,8 @@
     "./raster": "./lib/raster-ops.js",
     "./validate": "./lib/validate-nodes.js",
     "./parse": "./lib/parse-html.js",
+    "./refs": "./lib/resolve-refs.js",
+    "./normalize": "./lib/normalize-spec.js",
     "./inspect": "./lib/raster-inspect.js",
     "./examples/*": "./examples/*.js",
     "./transition": "./lib/transition.js",