nodality 1.2.9 → 1.2.11

package/lib/element-mapper.js

@@ -1,5 +1,5 @@
 /*!
- * nodality v1.2.9
+ * nodality v1.2.11
  * (c) 2026 Filip Vabrousek
  * License: MIT
  */
@@ -83,6 +83,16 @@ const ELEMENT_TYPES = [
     "simple", "copy", "wrap", "circle", "polygon", "code", "table", "ulist",
 ];
 
+// A nav entry is {title, link}. A bare string is accepted as the title: that
+// is the shape callers were already passing while `items` was ignored, and
+// 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.
+const navEntry = (i) =>
+    (typeof i === "string" || typeof i === "number")
+        ? { title: String(i), link: "#e" }
+        : { ...i, title: String(i?.title ?? ""), link: i?.link ?? "#e" };
+
 class ElementMapper { // 22:09:58 04/11/2024
    static mapType(obj) {
   // console.log("LOBJ");
@@ -172,12 +182,19 @@ class ElementMapper { // 22:09:58 04/11/2024
 
          let el = obj.el;
 
-    return new Table()
-        .add([
+    // Phase S4. A table's rows are DATA, not element specs, so `items` takes
+    // row objects and the columns follow from their keys. Without items the
+    // three placeholder rows are emitted exactly as before — the same
+    // non-breaking rule as cards and row.
+    const rows = Array.isArray(el.items) && el.items.length
+        ? el.items
+        : [
             { abbr: "AUIUI/AK9PT", name: "Pokročilé mobilní technologie", grade: "A", date: "09.01.2024" },
             { abbr: "AUIUI/AK9PT", name: "Pokročilé mobilní technologie", grade: "A", date: "09.01.2024" },
             { abbr: "AUIUI/AK9PT", name: "Pokročilé mobilní technologie", grade: "A", date: "09.01.2024" }
-          ])
+          ];
+    return new Table()
+        .add(rows)
           .set({
               cellPadding: "0.3em",
               cellAlign: "center",
@@ -231,6 +248,13 @@ class ElementMapper { // 22:09:58 04/11/2024
                 raster: this.filteroRaster(el.id, obj.customOptions),
         }).items([
 
+// Phase S4. `children` come from the element, mapped like any other
+// subtree — the fix mapWrap got in P3 and mapGrid in S1. Absent, the
+// three placeholders below are emitted exactly as before, so every
+// existing page is unaffected.
+...(Array.isArray(el.children) && el.children.length
+    ? el.children.map((child) => this.mapType({ ...obj, el: child }))
+    : [
 new Text("This").set({
     size: "S3"
 }), 
@@ -244,7 +268,7 @@ new Text("row.").set({
     size: "S3",
     text: "Hello"
 })
-    
+    ])
 ])
         
 
@@ -675,12 +699,29 @@ alert("PP")
        // console.log(ft);
 
 
-        let items = [
+        // Phase S4. Nav entries are DATA — {title, link} — so `items`
+        // carries them. Absent, the three placeholders are used exactly as
+        // before, which is what every existing page renders today.
+        let items = Array.isArray(obj.el?.items) && obj.el.items.length
+            ? obj.el.items.map(navEntry)
+            : [
             {title: "Fire", link: "@e"},
             {title: "and", link: "@e"},
             {title: "smoke", link: "@e"}
         ];
 
+        // The `links` built below feed the UINavBar block that is commented
+        // out further down, so they are not what a page renders. The live nav
+        // is the Switcher: two views, each carrying its own hardcoded link
+        // list. `navItems` is what drives those. It is null when the caller
+        // supplied nothing, which leaves the literals - and therefore every
+        // existing page - exactly as they were.
+        const navItems = Array.isArray(obj.el?.items) && obj.el.items.length
+            ? obj.el.items.map(navEntry)
+            : null;
+        const navLinks = () => navItems.map((i) =>
+            new Link().set({ text: i.title, url: i.link }));
+
         let links = items.map((i, o) => new Link(`"${i.title}"`)
         .set({
             fluidc: "S6",
@@ -844,7 +885,9 @@ if (obj.el.dropdown){
                           radius: "1rem",
                        }).add([
 
-                       new Link().set({text: "About", url: "#a"}),//.render()
+                       ...(navItems
+                           ? navLinks()
+                           : [new Link().set({text: "About", url: "#a"})]),//.render()
                      
 
 
@@ -901,8 +944,13 @@ if (obj.el.dropdown){
 
 
 
+                       // Supplied entries are emitted above, ahead of the dropdown, so
+                       // these two trailing placeholders drop out rather than appending
+                       // themselves to the end of the caller's nav.
+                       ...(navItems ? [] : [
                        new Link("B").set({text: "About", url: "#b"}),//.render()
                        new Link("C").set({text: "Contact", url: "https://www.abcnews.com"})//.render()
+                       ])
                        ])//.addNavItem(new Link("C").set({}).render())
                    },
    
@@ -1013,9 +1061,11 @@ new Wrapper().set({
 
 
 
+                       ...(navItems ? navLinks() : [
                        new Link().set({ text: "About", url: "#a"}),//.render()
                        new Link().set({ text: "Services", url: "#a"}),//.render()
                        new Link().set({ text: "Contact", url: "#a"})//.render()
+                       ]),
                     //   new Link("C").set({})//.render()
                        ])
                            /*.addNavItem(
@@ -1062,7 +1112,11 @@ new Wrapper().set({
 
 
 
-        let items = [
+        // Phase S4, as protoNav above: `items` carries {title, link}; absent,
+        // the placeholders are used exactly as before.
+        let items = Array.isArray(obj.el?.items) && obj.el.items.length
+            ? obj.el.items.map(navEntry)
+            : [
             {title: "Home", link: "@e"},
             {title: "Projects", link: "@e"},
             {title: "Services", link: "@e"}
@@ -1246,10 +1300,17 @@ if (obj.el.dropdown){
                  //  pad: {sides: ["all"], value: "1rem"}
                 }),
 
-            obj.el.animation ? animatedLinks[0] : links[0],
-            obj.el.animation ? animatedLinks[1] : links[1],
-            obj.el.animation ? animatedLinks[2] : links[2],
-            (obj.el.animation && obj.el.dropdown) ? animatedLinks[3] : new Text("").set({}).excludeFromCode(),
+            // Phase S4. These were three fixed slots, which assumed exactly
+            // three nav entries. Once `items` could supply any number,
+            // links[1] and links[2] were `undefined` and Wrapper.add called
+            // toCode() on them — a throw, not a silent no-op. One slot per
+            // item instead; with the default three the emitted list is
+            // unchanged, and the dropdown slot after it still indexes the
+            // entry the pushes above appended.
+            ...(obj.el.animation ? animatedLinks : links).slice(0, items.length).filter(Boolean),
+            (obj.el.animation && obj.el.dropdown)
+                ? animatedLinks[items.length]
+                : new Text("").set({}).excludeFromCode(),
 
             new Text("Company, 2025")
             .set({ // no ID, no animation
@@ -1690,15 +1751,111 @@ const blast    = this.filtero("blast", el.id, obj.customOptions);
       }
     })
     .items(
-      [
+      ${this.gridItemsSource(obj, cardTemplate)}
+    )
+    `;
+    }
+
+    /**
+     * The `.items(...)` argument for a `cards` grid.
+     *
+     * Phase S1. Until now this was a hardcoded array of three space cards
+     * inside a template literal, so `{type:"cards"}` rendered the same
+     * Starship/Saturn V/Shuttle grid whatever the caller declared — an
+     * element type with no way to carry content. `items` supplies it.
+     *
+     * Three shapes, chosen per entry so a mixed array works:
+     *
+     *   absent            the three placeholder cards, EXACTLY as before.
+     *                     This path emits a byte-identical string to the
+     *                     pre-S1 mapper and is covered by a regression test;
+     *                     the change ships behind no flag because nothing
+     *                     that works today can observe it.
+     *
+     *   {img,title,link}  shorthand. The same card template as before, over
+     *                     the caller's data instead of the placeholders.
+     *                     Kept because it is what the published benchmark
+     *                     and Table 3 of the PeerJ submission already write.
+     *
+     *   [ {type:…}, … ]   nested specs: a card whose children are ordinary
+     *                     element descriptors, mapped through `mapType` like
+     *                     any other subtree and emitted with `toCode()`.
+     *                     This is the shape that makes the format TOTAL —
+     *                     any element can appear inside a card without a new
+     *                     schema per composite.
+     *
+     * Data in, code out: every branch still emits `new Card().set({...})`
+     * source the developer owns. The template became parameterised; it did
+     * not become an interpreter.
+     */
+    static gridItemsSource(obj, cardTemplate) {
+        const items = obj.el.items;
+
+        // No items: the pre-S1 string, character for character.
+        if (!Array.isArray(items) || items.length === 0) {
+            return `[
         { img: "https://upload.wikimedia.org/wikipedia/commons/3/3a/Starship_S20.jpg", title: "Starship", link: "#ship" },
         { img: "https://upload.wikimedia.org/wikipedia/commons/1/16/Apollo_11_Launch_-_GPN-2000-000630.jpg", title: "Saturn V", link: "#saturn" },
         { img: "https://upload.wikimedia.org/wikipedia/commons/d/d6/STS120LaunchHiRes-edit1.jpg", title: "Shuttle", link: "#shuttle" }
       ].map(item => 
         ${cardTemplate}
-      )
-    )
-    `;
+      )`;
+        }
+
+        const isSpecList = (it) => Array.isArray(it);
+        const shorthand = items.filter((it) => !isSpecList(it));
+        const specLists = items.filter(isSpecList);
+
+        // 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}
+      )`;
+        }
+
+        // At least one entry is a spec list, so the cards differ and a single
+        // template cannot serve them. Emit each card explicitly.
+        const cards = items.map((it) => isSpecList(it)
+            ? this.cardFromSpecs(obj, it)
+            : this.cardFromShorthand(it));
+        return `[
+        ${cards.join(",\n        ")}
+      ]`;
+    }
+
+    /** A card whose children are element specs, mapped like any other subtree. */
+    static cardFromSpecs(obj, specs) {
+        const kids = specs.map((child) => {
+            const mapped = this.mapType({ ...obj, el: child });
+            // mapType returns an instance for most types and SOURCE for the
+            // few that emit source themselves (grid, copy, wrap-as-source).
+            // A string is already code; an instance knows how to become code.
+            if (typeof mapped === "string") return mapped.trim();
+            const code = mapped && typeof mapped.toCode === "function"
+                ? [].concat(mapped.toCode()).join("")
+                : "";
+            return code.trim();
+        }).filter(Boolean);
+
+        return `new Card()
+            .set({ width: "300px", height: "700px", radius: "0.7rem", mar: { sides: ["all"], value: "0.8rem" } })
+            .items([
+              ${kids.join(",\n              ")}
+            ])`;
+    }
+
+    /** A card built from {img, title, link} shorthand, matching the template. */
+    static cardFromShorthand(item) {
+        const s = (v) => JSON.stringify(v ?? "");
+        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" })
+            ])`;
     }
 
 

package/lib/element-params.generated.js

@@ -0,0 +1,11 @@
+/*!
+ * nodality v1.2.11
+ * (c) 2026 Filip Vabrousek
+ * License: MIT
+ */
+
+// GENERATED by scripts/generate-schema.mjs — do not edit.
+// 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"];

package/lib/keyframe-animation.js

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

package/lib/link-getter.js

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

package/lib/morph-node.js

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

package/lib/parse-html.js

@@ -0,0 +1,151 @@
+/*!
+ * nodality v1.2.11
+ * (c) 2026 Filip Vabrousek
+ * License: MIT
+ */
+
+/**
+ * Stage 5 of AGENTIC-FIRST-PLAN.md — the round-trip.
+ *
+ *     parse(html) -> spec        such that   render(parse(html)) === html
+ *
+ * The plan expected this to be partial at first, and measurement decided
+ * exactly where the partial line falls.
+ *
+ * WHAT THE MEASUREMENT SAID. Rendering all 35 declared types in isolation and
+ * comparing their DOM signatures: 13 of them — `cards`, `nav`, `sideNav`,
+ * `row`, `dropdown`, `radio`, `labelInput`, `filePicker`, `checkbox`, `wrap`,
+ * `circle`, `polygon`, `table` — produce a bare `<div>` with no class and no
+ * attributes. Nothing in the output says which one produced it. Looking two
+ * levels deeper separates 24 of 30, but only for the placeholder renders it
+ * was calibrated on: a `row` holding an `h2` and a `wrap` holding an `h2` are
+ * the same shape, so a signature table built from empty composites does not
+ * match a page with content in it. Structural recognition of a composite is
+ * therefore guesswork, and a parser that guesses wrong hands an agent a spec
+ * that renders a different page.
+ *
+ * SO THERE ARE TWO TIERS, and they are not presented as one.
+ *
+ *   exact        The page carries its own spec: `set({annotate: true})` writes
+ *                each element's descriptor onto the node it produced. parse
+ *                reads it back. Round-trip is exact for every type, including
+ *                every style option, because nothing is being inferred.
+ *
+ *   structural   No annotation: recover what the tag alone determines —
+ *                headings, paragraphs, links, images, lists. These are the
+ *                leaf types, which is the case the paper measures, and their
+ *                tag is not shared with anything ambiguous.
+ *
+ * Annotation is OPT-IN and off by default. It writes attributes into the
+ * output, and the whole project rests on existing pages rendering byte for
+ * byte as they always did.
+ *
+ * The 1:1 correspondence between descriptors and mounted children that
+ * `annotate` relies on is not a new assumption: morph nodes already resolve
+ * `from`/`to` against the rendered children by position, for the same reason
+ * (components do not all carry their id into the DOM). It was re-measured for
+ * 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. */
+export const SPEC_ATTR = "data-nod";
+
+/**
+ * Write each descriptor onto the child it produced. Returns how many were
+ * written, which is what the caller needs to know if the two ever diverge.
+ */
+export function annotateRoundTrip(host, elements) {
+    if (!host || !Array.isArray(elements)) return 0;
+    const kids = Array.from(host.children || []);
+    let written = 0;
+    for (let i = 0; i < kids.length && i < elements.length; i++) {
+        try {
+            kids[i].setAttribute(SPEC_ATTR, JSON.stringify(elements[i]));
+            written++;
+        } catch (e) { /* a node that refuses attributes is skipped, not fatal */ }
+    }
+    return written;
+}
+
+/**
+ * Recover what the tag alone determines. Deliberately narrow: returning a
+ * confident guess for a composite would be worse than returning nothing,
+ * because the caller re-renders whatever comes back.
+ */
+export function inferNode(node) {
+    const tag = (node.tagName || "").toLowerCase();
+    if (HEADINGS.has(tag)) return { type: tag, text: node.textContent };
+    if (tag === "p") return { type: "p", text: node.textContent };
+    if (tag === "a") {
+        return { type: "a", text: node.textContent, url: node.getAttribute("href") || "" };
+    }
+    if (tag === "img") return { type: "img", url: node.getAttribute("src") || "" };
+    if (tag === "ul") {
+        return { type: "ulist", items: Array.from(node.children).map((c) => c.textContent) };
+    }
+    return null;
+}
+
+/** One node to one descriptor: the carried spec if there is one, else inference. */
+export function parseNode(node) {
+    if (!node || node.nodeType !== 1) return null;
+    const carried = node.getAttribute && node.getAttribute(SPEC_ATTR);
+    if (carried) {
+        try { return JSON.parse(carried); }
+        catch (e) { /* a corrupted attribute falls through to inference */ }
+    }
+    return inferNode(node);
+}
+
+/**
+ * parse(html) -> spec. `doc` is only needed off-browser, where the caller
+ * supplies a document; the library's own globals are shadowed by the bridge,
+ * so this builds its container through createElement rather than a
+ * constructor.
+ */
+export function parseHTML(html, doc) {
+    const d = doc || (typeof document !== "undefined" ? document : null);
+    if (!d) throw new Error("[nodality] parseHTML needs a document");
+    const box = d.createElement("div");
+    box.innerHTML = String(html == null ? "" : html);
+    return Array.from(box.children).map(parseNode).filter(Boolean);
+}
+
+/**
+ * What parse could NOT recover, so a caller can tell a partial read from a
+ * complete one instead of discovering it at render time.
+ */
+export function parseReport(html, doc) {
+    const d = doc || (typeof document !== "undefined" ? document : null);
+    if (!d) throw new Error("[nodality] parseReport needs a document");
+    const box = d.createElement("div");
+    box.innerHTML = String(html == null ? "" : html);
+    const kids = Array.from(box.children);
+    const spec = [], unrecovered = [];
+    kids.forEach((node, i) => {
+        const one = parseNode(node);
+        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 && 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.9
+ * nodality v1.2.11
  * (c) 2026 Filip Vabrousek
  * License: MIT
  */

package/lib/raster-ops.js

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

package/lib/raster-presets.js

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

package/lib/scroll-video.js

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

package/lib/seo.js

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

package/lib/stacker.js

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

package/lib/suggest.js

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

package/lib/theme.js

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

package/lib/transform-anim.js

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

package/lib/transition.js

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