nodality 1.1.14 → 1.2.0

package/lib/keyframe-animation.js

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

package/lib/link-getter.js

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

package/lib/morph-node.js

@@ -1,5 +1,5 @@
 /*!
- * nodality v1.1.14
+ * nodality v1.2.0
  * (c) 2026 Filip Vabrousek
  * License: MIT
  */
@@ -123,6 +123,25 @@ const chainFor = (effect) => {
 
 const norm = (t) => String(t || "").replace(/\s+/g, " ").trim().toLowerCase();
 
+/**
+ * An id as written, reduced to the id itself.
+ *
+ * A node may name a state bare (`"home"`) or in selector form
+ * (`"#home"`). Both are accepted and both mean the same thing, because
+ * this is an element IDENTIFIER rather than a selector: the lookup is
+ * `getElementById`, plus a positional fallback against `E`, so `"#home"`
+ * would otherwise match nothing and the morph would fail with a console
+ * warning and no visible effect.
+ *
+ * Normalised HERE, once, rather than at the point of lookup: the states
+ * are keyed by this string, so a chain whose first edge writes `"#home"`
+ * and whose second writes `"home"` must arrive at ONE key. Stripping at
+ * lookup time would resolve both to the same element while keeping two
+ * entries in the map, and the second edge would then be unreachable.
+ */
+const bareId = (id) =>
+    typeof id === "string" && id.startsWith("#") ? id.slice(1) : id;
+
 /**
  * A morph node, in one shape: a list of EDGES.
  *
@@ -170,19 +189,22 @@ const normalizeEdges = (m) => {
         // Labels are what the user is actually reading and clicking.
         const byLabel = e.to && !Array.isArray(e.to) && typeof e.to === "object"
             ? e.to : null;
+        // Deduplicated on the label side only. The array form is POSITIONAL
+        // — `toIds[triggers.indexOf(a)]` below — so collapsing a repeated
+        // id there would shift every later link onto the wrong destination.
         const toIds = byLabel
-            ? [...new Set(Object.values(e.to))]
-            : (Array.isArray(e.to) ? e.to : [e.to]);
+            ? [...new Set(Object.values(e.to))].map(bareId)
+            : (Array.isArray(e.to) ? e.to : [e.to]).map(bareId);
 
         const labelToId = new Map();
         if (byLabel) {
             for (const [label, id] of Object.entries(e.to)) {
-                labelToId.set(norm(label), id);
+                labelToId.set(norm(label), bareId(id));
             }
         }
 
         return {
-            from: e.from, byLabel, toIds, labelToId,
+            from: bareId(e.from), byLabel, toIds, labelToId,
             effect: opt("effect"),
             duration: opt("duration", 900),
             // Written as `!== false` rather than a truthy test: the
@@ -212,9 +234,13 @@ function applyMorphNodes(mount, elements, nodes) {
     // page. Position is what Des actually guarantees.
     const rendered = [...mount.children];
     const resolve = (id) => {
-        const byId = document.getElementById(id);
+        // `bareId` again, and not only for symmetry: the descriptor in E
+        // may itself be written with a leading "#", so both sides are
+        // reduced before they are compared.
+        const want = bareId(id);
+        const byId = document.getElementById(want);
         if (byId && mount.contains(byId)) return byId;
-        const i = (elements || []).findIndex((e) => e && e.id === id);
+        const i = (elements || []).findIndex((e) => e && bareId(e.id) === want);
         return i >= 0 ? rendered[i] : null;
     };
 
@@ -811,6 +837,13 @@ function setUpMorph(mount, m, resolve) {
         get active() { return active; },
         goTo, goToState,
         back() { if (tl) tl.to(0); },
+        // The control's own entry point, published for the agent surface.
+        // `back()` above reverses a RUNNING timeline and does nothing at
+        // rest; `goBack` is what the back button calls — queued, one
+        // press one level, reusing the live pipeline or rebuilding it.
+        // A derived go_back tool has to be the same action as the button
+        // or the two would unwind differently from the same state.
+        goBack,
         destroy() {
             if (tl) tl.destroy();
             for (const p of activeRasterPipelines()) {
@@ -821,4 +854,10 @@ function setUpMorph(mount, m, resolve) {
     };
 }
 
-export { applyMorphNodes };
+// `normalizeEdges` is exported for DERIVATION, not for use: the agent
+// surface reads the same edge list the controller runs, so the two can
+// never describe different graphs. Reimplementing the normalisation
+// there would have drifted the first time either side changed — which
+// is precisely how the validator came to accept a `#id` the runtime
+// refused to resolve.
+export { applyMorphNodes, normalizeEdges };

package/lib/raster-inspect.js

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

package/lib/raster-ops.js

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

package/lib/raster-presets.js

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

package/lib/scroll-video.js

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

package/lib/seo.js

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

package/lib/stacker.js

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

package/lib/suggest.js

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

package/lib/theme.js

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

package/lib/transform-anim.js

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

package/lib/transition.js

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

package/lib/validate-nodes.js

@@ -1,5 +1,5 @@
 /*!
- * nodality v1.1.14
+ * nodality v1.2.0
  * (c) 2026 Filip Vabrousek
  * License: MIT
  */
@@ -36,15 +36,36 @@ import { didYouMean, suggest } from "./suggest.js";
  * the runtime, which is why it has to be reported here.
  */
 const MORPH_FIELDS = [
-    "op", "target", "from", "to",
+    "op", "target", "from", "to", "chain",
     "effect", "duration", "back", "live", "fade",
 ];
 
+/**
+ * Every key an entry in `chain` reads. `from` and `to` make the edge; the
+ * rest are the node's own settings, overridable per edge — which is why
+ * this list is MORPH_FIELDS without `op`, `target` or `chain`, an edge
+ * being able to carry neither an op nor a nested chain of its own.
+ */
+const EDGE_FIELDS = [
+    "from", "to", "effect", "duration", "back", "live", "fade",
+];
+
+/**
+ * Every key an `agent-surface` node reads. The node is small on purpose:
+ * what it exposes is DERIVED, so there is nothing here to describe the
+ * tools with — only which parts of the page may be reached.
+ */
+const AGENT_SURFACE_FIELDS = ["op", "name", "forms", "exclude"];
+
 /** Node families, told apart exactly the way the runtime tells them apart. */
 const familyOf = (node) => {
     if (!node || typeof node !== "object") return "invalid";
     const op = node.op;
-    if (typeof op === "string") return op === "morph" ? "morph" : "raster";
+    if (typeof op === "string") {
+        if (op === "morph") return "morph";
+        if (op === "agent-surface") return "agent-surface";
+        return "raster";
+    }
     if (op && typeof op === "object" && typeof op.name === "string") return "design";
     return "invalid";
 };
@@ -96,8 +117,13 @@ export function validateNodes(nodes, elements) {
                 push("BAD_TARGET", at, t, [], ["an element id"]);
                 return;
             }
-            // Ids are written bare in E and may be written with a leading
-            // "#" in a node; accept both rather than inventing a rule.
+            // An id may be written bare ("home") or in selector form
+            // ("#home"). Both are accepted here because both are accepted
+            // by the runtime — `bareId` in morph-node.js reduces them to
+            // one key before anything is resolved. The two must agree: for
+            // a while this check tolerated "#home" while the runtime did
+            // not, so the validator passed a node that silently never
+            // morphed, which is the exact failure it exists to prevent.
             const bare = t.startsWith("#") ? t.slice(1) : t;
             if (idsKnown && !ids.includes(bare)) {
                 push("UNKNOWN_TARGET", at, t, suggest(bare, ids), ids);
@@ -120,38 +146,176 @@ export function validateNodes(nodes, elements) {
 
         if (family === "design") return;   // design nodes carry their own vocabulary
 
-        if (family === "morph") {
-            // The morph node's own contract. `from` and `to` are what make
-            // it a morph; without them the node is inert.
-            if (typeof node.from !== "string") {
-                push("MISSING_FIELD", `${path}.from`, node.from, [],
-                    ["the id of the element that morphs"]);
-            } else {
-                checkTargets(node.from, `${path}.from`);
+        if (family === "agent-surface") {
+            // The ids this node names must exist, for the usual reason:
+            // a surface that silently exposes nothing is the agentic
+            // form of the silent no-op, and an agent has no way to see
+            // that the tool it expected was never registered.
+            const formIds = [];
+            const walkForms = (list) => {
+                if (!Array.isArray(list)) return;
+                for (const el of list) {
+                    if (!el || typeof el !== "object") continue;
+                    if (el.type === "form" && typeof el.id === "string") formIds.push(el.id);
+                    walkForms(el.children);
+                }
+            };
+            if (idsKnown) walkForms(elements);
+
+            if (node.name !== undefined && typeof node.name !== "string") {
+                push("BAD_FIELD", `${path}.name`, node.name, [],
+                    ["a string used to prefix every derived tool name"]);
             }
-            if (node.to === undefined) {
-                push("MISSING_FIELD", `${path}.to`, undefined, [],
-                    ["[\"id\", ...]", "{ \"Link label\": \"id\" }"]);
-            } else if (Array.isArray(node.to)) {
-                checkTargets(node.to, `${path}.to`);
-            } else if (node.to && typeof node.to === "object") {
-                for (const label in node.to) {
-                    checkTargets(node.to[label], `${path}.to.${label}`);
+
+            for (const key of ["forms", "exclude"]) {
+                if (node[key] === undefined) continue;
+                if (!Array.isArray(node[key])) {
+                    push("BAD_FIELD", `${path}.${key}`, node[key], [], ["an array of ids"]);
+                    continue;
                 }
-            } else {
-                push("BAD_FIELD", `${path}.to`, node.to, [],
-                    ["an array of ids, or a map of link label to id"]);
+                node[key].forEach((v, k) => {
+                    const at = `${path}.${key}[${k}]`;
+                    if (typeof v !== "string") {
+                        push("BAD_TARGET", at, v, [], ["an element id"]);
+                        return;
+                    }
+                    const bare = v.startsWith("#") ? v.slice(1) : v;
+                    if (key === "forms") {
+                        // Checked against FORMS, not against every id: a
+                        // node naming a heading would otherwise pass here
+                        // and derive no tool at all.
+                        if (idsKnown && !formIds.includes(bare)) {
+                            push("UNKNOWN_FORM", at, v, suggest(bare, formIds), formIds);
+                        }
+                    } else if (idsKnown && !ids.includes(bare)) {
+                        push("UNKNOWN_STATE", at, v, suggest(bare, ids), ids);
+                    }
+                });
+            }
+
+            // A surface with no graph and no forms still derives
+            // `read_view`, which is legitimate — a page can be worth
+            // reading and nothing else. Reported so that a node written
+            // in the expectation of more says so.
+            const hasChain = nodes.some((n) => n && n.op === "morph");
+            const hasForms = Array.isArray(node.forms) && node.forms.length > 0;
+            if (!hasChain && !hasForms) {
+                push("EMPTY_SURFACE", path, node, [],
+                    ["add a { op: \"morph\" } node, or name a form in `forms`"]);
+            }
+
+            for (const key in node) {
+                if (AGENT_SURFACE_FIELDS.includes(key)) continue;
+                push("UNKNOWN_PARAM", `${path}.${key}`, key,
+                    suggest(key, AGENT_SURFACE_FIELDS), AGENT_SURFACE_FIELDS);
             }
-            if (node.duration !== undefined &&
-                (typeof node.duration !== "number" || !(node.duration > 0))) {
-                push("BAD_VALUE", `${path}.duration`, node.duration, [],
-                    ["a positive number of milliseconds"]);
+            return;
+        }
+
+        if (family === "morph") {
+            // `from` and `to` are what make a hop; without them it is
+            // inert. Factored out because a chain edge has exactly the
+            // same two ends as a single-hop node, and the diagnostics
+            // should not differ by where the edge was written.
+            const checkEnds = (o, at) => {
+                if (typeof o.from !== "string") {
+                    push("MISSING_FIELD", `${at}.from`, o.from, [],
+                        ["the id of the element that morphs"]);
+                } else {
+                    checkTargets(o.from, `${at}.from`);
+                }
+                if (o.to === undefined) {
+                    push("MISSING_FIELD", `${at}.to`, undefined, [],
+                        ["[\"id\", ...]", "{ \"Link label\": \"id\" }"]);
+                } else if (Array.isArray(o.to)) {
+                    checkTargets(o.to, `${at}.to`);
+                } else if (o.to && typeof o.to === "object") {
+                    for (const label in o.to) {
+                        checkTargets(o.to[label], `${at}.to.${label}`);
+                    }
+                } else {
+                    push("BAD_FIELD", `${at}.to`, o.to, [],
+                        ["an array of ids, or a map of link label to id"]);
+                }
+            };
+
+            // The settings, which are hoisted defaults on the node and
+            // overrides on an edge, so both are checked the same way.
+            // `back` and `live` are compared against `false`/`true` by
+            // identity in the runtime, which makes a STRING the dangerous
+            // mistake: `live: "true"` is not `=== true`, so the live
+            // backend silently stays off and the page still works, on the
+            // other backend, looking as though the flag took.
+            const checkOpts = (o, at) => {
+                if (o.duration !== undefined &&
+                    (typeof o.duration !== "number" || !(o.duration > 0))) {
+                    push("BAD_VALUE", `${at}.duration`, o.duration, [],
+                        ["a positive number of milliseconds"]);
+                }
+                if (o.effect !== undefined &&
+                    typeof o.effect !== "string" && !Array.isArray(o.effect)) {
+                    push("BAD_FIELD", `${at}.effect`, o.effect, [],
+                        ["a preset name, or an inline array of raster nodes"]);
+                }
+                for (const flag of ["back", "live"]) {
+                    if (o[flag] !== undefined && typeof o[flag] !== "boolean") {
+                        push("BAD_VALUE", `${at}.${flag}`, o[flag], [],
+                            ["true", "false"]);
+                    }
+                }
+                if (o.fade !== undefined && typeof o.fade !== "string") {
+                    push("BAD_FIELD", `${at}.fade`, o.fade, [],
+                        ["a fade mode, as a string"]);
+                }
+            };
+
+            // A node is either one hop or a chain, and the runtime decides
+            // by looking at `chain` FIRST: `normalizeEdges` takes a
+            // non-empty chain and never reads node-level `from`/`to`. The
+            // check mirrors that order, so what passes here is what runs.
+            const chained = Array.isArray(node.chain) && node.chain.length > 0;
+
+            if (node.chain !== undefined && !Array.isArray(node.chain)) {
+                push("BAD_FIELD", `${path}.chain`, node.chain, [],
+                    ["an array of edges: [{ from, to }, ...]"]);
+            } else if (Array.isArray(node.chain) && !node.chain.length) {
+                // The runtime does not reject this — it falls back to the
+                // single-hop fields — but it is never what was meant.
+                push("BAD_VALUE", `${path}.chain`, node.chain, [],
+                    ["at least one edge, or no `chain` key at all"]);
             }
-            if (node.effect !== undefined &&
-                typeof node.effect !== "string" && !Array.isArray(node.effect)) {
-                push("BAD_FIELD", `${path}.effect`, node.effect, [],
-                    ["a preset name, or an inline array of raster nodes"]);
+
+            checkOpts(node, path);
+
+            if (chained) {
+                // `from`/`to` written BESIDE a chain are dead, not merged.
+                // Worth reporting precisely because the page still works,
+                // using the chain, so the ignored pair looks as though it
+                // took effect.
+                for (const key of ["from", "to"]) {
+                    if (node[key] !== undefined) {
+                        push("IGNORED_FIELD", `${path}.${key}`, node[key], [],
+                            ["remove it, or drop `chain` and keep the single hop"]);
+                    }
+                }
+                node.chain.forEach((edge, j) => {
+                    const at = `${path}.chain[${j}]`;
+                    if (!edge || typeof edge !== "object" || Array.isArray(edge)) {
+                        push("BAD_FIELD", at, edge, [], ["{ from, to }"]);
+                        return;
+                    }
+                    checkEnds(edge, at);
+                    checkOpts(edge, at);
+                    for (const key in edge) {
+                        if (EDGE_FIELDS.includes(key)) continue;
+                        push("UNKNOWN_PARAM", `${at}.${key}`, key,
+                            suggest(key, EDGE_FIELDS), EDGE_FIELDS);
+                    }
+                });
+            } else {
+                checkEnds(node, path);
             }
+
             // Unknown keys, checked here for the same reason they are
             // checked on a raster node: a morph silently ignores what it
             // does not recognise, so `duraton: 900` produces a transition