nodality 1.2.10 → 1.3.0

package/lib/resolve-refs.js

@@ -0,0 +1,121 @@
+/*!
+ * nodality v1.3.0
+ * (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.10
+ * nodality v1.3.0
  * (c) 2026 Filip Vabrousek
  * License: MIT
  */

package/lib/seo.js

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

package/lib/stacker.js

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

package/lib/suggest.js

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

package/lib/theme.js

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

package/lib/transform-anim.js

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

package/lib/transition.js

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

package/lib/validate-nodes.js

@@ -1,5 +1,5 @@
 /*!
- * nodality v1.2.10
+ * nodality v1.3.0
  * (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";
@@ -141,7 +143,27 @@ const familyOf = (node) => {
  *   which is the other half of the "silent no-op" problem: a correctly
  *   spelled op aimed at an element that is not there does nothing at all.
  */
-export function validateNodes(nodes, elements) {
+// Which key actually carries a composite's content.
+//
+// GROUND TRUTH, DERIVED BY RENDERING, not by reading the source. A static scan
+// got this wrong: `mapRow` appears to read `items` because a helper it calls
+// does, and that helper's `items` belongs to a different element entirely. So
+// each type was rendered with a distinctive payload in `items` and again in
+// `children`, and only the slot the output actually followed is recorded here.
+// `__tests__/unit/content-slots.test.mjs` re-derives it the same way and fails
+// if this table drifts, which is the arrangement Stage 2 established for the
+// schema.
+//
+// ONLY types with positive evidence appear. A type whose content slot could not
+// be demonstrated is absent, and absent means silent: reporting a slot that
+// might work would stop `preview` rendering a page that renders, which 1.2.7
+// established is the costlier direction to be wrong in.
+export const CONTENT_SLOT = {
+    cards: "items", nav: "items", sideNav: "items", table: "items", ulist: "items",
+    row: "children", form: "children", wrap: "children",
+};
+
+export function validateNodes(nodes, elements, defs) {
     const errors = [];
     const push = (code, path, got, suggestions, valid) => {
         errors.push({
@@ -199,6 +221,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;
@@ -219,6 +277,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\""]);
@@ -226,6 +290,38 @@ export function validateNodes(nodes, elements) {
                     push("UNKNOWN_ELEMENT_TYPE", `${p}.type`, el.type,
                         suggest(el.type, ELEMENT_TYPES), ELEMENT_TYPES);
                 }
+                // Content declared in the slot this type does not read.
+                // `{type:"table", children:[...]}` validated clean and then
+                // rendered its placeholders — the exact silent no-op Stage 1
+                // 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;
+                    // All-strings is the pre-S1 gesture and already gets its own
+                    // diagnostic from the walk below; do not report it twice.
+                    const allStrings = Array.isArray(el[other])
+                        && el[other].every((x) => typeof x === "string");
+                    if (filled(el[other]) && !filled(el[wants]) && !allStrings) {
+                        push("WRONG_CONTENT_SLOT", `${p}.${other}`, other, [wants],
+                            [`"${el.type}" carries its content in \`${wants}\``]);
+                    }
+                }
+
                 walkEls(el.children, `${p}.children`);
 
                 // Phase S3: a misspelled element parameter. `{type:"cards",
@@ -288,7 +384,7 @@ export function validateNodes(nodes, elements) {
                 }
             });
         };
-        walkEls(elements, "elements");
+        walkEls(toWalk, "elements");
     }
 
     nodes.forEach((node, i) => {

package/lib/webmcp-adapter.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nodality",
-  "version": "1.2.10",
+  "version": "1.3.0",
   "description": "A lightweight library for declarative UI elements.",
   "main": "dist/index.cjs.js",
   "module": "dist/index.esm.js",
@@ -14,7 +14,9 @@
     "bin/",
     "API.md",
     "examples/",
-    "skills/"
+    "skills/",
+    "schema.json",
+    "scripts/generate-schema.mjs"
   ],
   "exports": {
     ".": {
@@ -31,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",