nodality 1.1.15 → 1.2.0

package/lib/keyframe-animation.js

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

package/lib/link-getter.js

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

package/lib/morph-node.js

@@ -1,5 +1,5 @@
 /*!
- * nodality v1.1.15
+ * nodality v1.2.0
  * (c) 2026 Filip Vabrousek
  * License: MIT
  */
@@ -837,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()) {
@@ -847,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.15
+ * nodality v1.2.0
  * (c) 2026 Filip Vabrousek
  * License: MIT
  */

package/lib/raster-ops.js

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

package/lib/raster-presets.js

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

package/lib/scroll-video.js

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

package/lib/seo.js

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

package/lib/stacker.js

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

package/lib/suggest.js

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

package/lib/theme.js

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

package/lib/transform-anim.js

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

package/lib/transition.js

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

package/lib/validate-nodes.js

@@ -1,5 +1,5 @@
 /*!
- * nodality v1.1.15
+ * nodality v1.2.0
  * (c) 2026 Filip Vabrousek
  * License: MIT
  */
@@ -50,11 +50,22 @@ 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";
 };
@@ -135,6 +146,72 @@ export function validateNodes(nodes, elements) {
 
         if (family === "design") return;   // design nodes carry their own vocabulary
 
+        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"]);
+            }
+
+            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;
+                }
+                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);
+            }
+            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

package/lib/webmcp-adapter.js

@@ -0,0 +1,307 @@
+/*!
+ * nodality v1.2.0
+ * (c) 2026 Filip Vabrousek
+ * License: MIT
+ */
+
+/*!
+ * webmcp-adapter.js — the derived surface, made callable.
+ *
+ * Everything protocol-shaped in this library lives HERE, in one file,
+ * on purpose. WebMCP is six months old, is a Draft Community Group
+ * Report rather than a standard, is available only in an origin trial,
+ * and has ALREADY moved its entry point once (`navigator.modelContext`
+ * → `document.modelContext`). A library that scattered those facts
+ * through the designer and the prerenderer would need archaeology every
+ * time the draft moved; here the next move is one file and a failing
+ * test.
+ *
+ * The registration itself is a REQUEST, not a guarantee — exactly the
+ * posture the live raster backend takes toward HTML-in-Canvas. Where
+ * the API is absent (every stock browser today, and jsdom at build
+ * time) nothing registers, nothing warns, and the page behaves
+ * identically. What still happens everywhere is the DECLARATION: the
+ * manifest is written into the document as data, so a crawler, an
+ * indexer, or an agent deciding whether to visit at all can read the
+ * site's capabilities without executing anything and without the API
+ * existing. That half needs no browser support and no standard.
+ */
+
+import { deriveSurface } from "./agent-surface.js";
+
+/**
+ * The draft this adapter is written against. Asserted in ONE place so
+ * that a spec move is a single-file change with a failing test, and so
+ * that every emitted manifest records what it was derived against
+ * rather than implying a stability the spec does not yet have.
+ */
+export const SPEC_DRAFT = "2026-07-21";
+
+/** Where the declaration lives in the document, JSON-LD style. */
+export const MANIFEST_ID = "nodality-agent-manifest";
+
+/**
+ * The registry, wherever this browser currently keeps it.
+ *
+ * Both spellings are accepted because the trial spans the rename: the
+ * draft moved to `document.modelContext`, Chrome 150 deprecated the
+ * older location, and pages served to both are the normal case for the
+ * length of an origin trial.
+ */
+function registry() {
+    if (typeof document !== "undefined" && document.modelContext) return document.modelContext;
+    if (typeof navigator !== "undefined" && navigator.modelContext) return navigator.modelContext;
+    return null;
+}
+
+/**
+ * `CSS.escape`, or a serviceable stand-in.
+ *
+ * jsdom has no `CSS` global, and the build-time pass runs there — the
+ * unguarded call threw, was swallowed by the designer's try/catch, and
+ * every prerendered page silently shipped without its declaration. The
+ * fallback escapes what an id may legally contain and a selector may
+ * not; ids here come from descriptors the author wrote, not from user
+ * input, so this is about correctness on ordinary hyphens and dots
+ * rather than about hostile strings.
+ */
+const esc = (s) => {
+    const str = String(s);
+    if (typeof CSS !== "undefined" && typeof CSS.escape === "function") return CSS.escape(str);
+    return str.replace(/([^a-zA-Z0-9_-])/g, "\\$1");
+};
+
+/** Text an agent can read, from the subtree that is actually on screen. */
+function readSubtree(root) {
+    if (!root) return { text: "", actions: [] };
+    const visible = (el) => {
+        const r = el.getBoundingClientRect();
+        if (!(r.width > 0 && r.height > 0)) return false;
+        const cs = getComputedStyle(el);
+        return cs.visibility !== "hidden" && cs.display !== "none" && cs.opacity !== "0";
+    };
+    const lines = [];
+    for (const el of root.querySelectorAll("h1,h2,h3,h4,h5,h6,p,li")) {
+        if (!visible(el)) continue;
+        const t = (el.textContent || "").replace(/\s+/g, " ").trim();
+        if (!t) continue;
+        const tag = el.tagName.toLowerCase();
+        lines.push(/^h[1-6]$/.test(tag) ? `${"#".repeat(+tag[1])} ${t}` : t);
+    }
+    const actions = [];
+    for (const el of root.querySelectorAll("a,button,[role=button]")) {
+        if (!visible(el)) continue;
+        const t = (el.textContent || "").replace(/\s+/g, " ").trim();
+        if (t && !actions.includes(t)) actions.push(t);
+    }
+    return { text: lines.join("\n"), actions };
+}
+
+/** A structured refusal, in the shape every other report in this library uses. */
+const refuse = (code, got, valid) => ({ ok: false, code, got, valid });
+
+/**
+ * Give a derived surface its handlers and offer it to the browser.
+ *
+ * @param {object} args
+ * @param {Element} args.mount     the rendered mount
+ * @param {Array}  args.elements   E
+ * @param {Array}  args.nodes      N
+ * @param {Array}  args.morphs     handles returned by applyMorphNodes
+ * @returns {{manifest: object, tools: object[], registered: boolean,
+ *   destroy: function}|null}
+ */
+export function installAgentSurface({ mount, elements, nodes, morphs }) {
+    const derived = deriveSurface(elements, nodes, { specDraft: SPEC_DRAFT });
+    if (!derived) return null;           // opt-in: no node, no surface
+
+    const { tools, manifest } = derived;
+    const handles = Array.isArray(morphs) ? morphs.filter(Boolean) : [];
+    const graphFor = (id) => handles.find((h) => h.states && h.states.has(id)) || null;
+
+    /**
+     * The rendered form a descriptor id names, wherever it currently is.
+     *
+     * A morph state that has not been visited is DETACHED — held by the
+     * controller, absent from the document — so a form inside one cannot
+     * be found by querying the mount. It is reachable through the state
+     * elements the controller holds, and stamping or filling it there
+     * works exactly as well: the attributes and values travel with the
+     * element when the transition inserts it.
+     */
+    const findForm = (formId) => {
+        const dig = (root) => {
+            if (!root || typeof root.querySelector !== "function") return null;
+            if (root.id === formId) {
+                return root.tagName === "FORM" ? root : root.querySelector("form");
+            }
+            const host = root.querySelector(`#${esc(formId)}`);
+            if (!host) return null;
+            return host.tagName === "FORM" ? host : host.querySelector("form");
+        };
+        const here = dig(mount);
+        if (here) return here;
+        for (const h of handles) {
+            if (!h.states) continue;
+            for (const el of h.states.values()) {
+                const found = dig(el);
+                if (found) return found;
+            }
+        }
+        return null;
+    };
+
+    // ── the declaration, written wherever we are ─────────────────────
+    //
+    // In jsdom this ends up inside the prerendered HTML, which is the
+    // whole point: the static declaration exists because the same code
+    // ran at build time, not because a second emitter was written for
+    // it. In a browser it is simply inert data in the page.
+    if (typeof document !== "undefined") {
+        const prev = document.getElementById(MANIFEST_ID);
+        if (prev) prev.remove();
+        const tag = document.createElement("script");
+        tag.type = "application/json";
+        tag.id = MANIFEST_ID;
+        tag.textContent = JSON.stringify(manifest, null, 2);
+        (document.body || document.documentElement).appendChild(tag);
+    }
+
+    // ── the spec's own form annotations ──────────────────────────────
+    //
+    // Emitted rather than resisted. The draft's declarative path derives
+    // a tool from `toolname`/`tooldescription` on a form, and Lighthouse
+    // already audits for them; stamping the SAME forms we derive from
+    // means the annotated surface and the derived surface describe one
+    // thing by construction, and a browser that only implements the
+    // declarative path still gets the form.
+    for (const t of tools) {
+        if (t.kind !== "submit" || !mount) continue;
+        const el = findForm(t.formId);
+        if (!el) continue;
+        el.setAttribute("toolname", t.name);
+        el.setAttribute("tooldescription", t.description);
+    }
+
+    // ── handlers ─────────────────────────────────────────────────────
+    //
+    // Traversals are SERIALISED, and this is an agent-specific hazard
+    // rather than a controller bug: a human cannot click twice inside
+    // one tick, so the controller's interrupt handling has never had to
+    // survive two transitions starting before either has built its
+    // pipeline. An agent does it trivially — two executeTool calls, no
+    // await — and the observed result was an interface with NOTHING on
+    // screen. Queuing here means the second call runs from the state the
+    // first actually landed in, which may make it unreachable; that
+    // returns a constructive refusal, which is a coherent answer. The
+    // controller is left exactly as it is, because for its own callers
+    // it is exactly right.
+    let queue = Promise.resolve();
+    const serial = (fn) => {
+        const run = queue.then(fn, fn);
+        queue = run.then(() => {}, () => {});
+        return run;
+    };
+
+    const execute = {
+        navigate: ({ destination } = {}) => serial(async () => {
+            const h = graphFor(destination);
+            if (!h) {
+                return refuse("UNKNOWN_VIEW", destination,
+                    handles.flatMap((x) => [...x.states.keys()]));
+            }
+            // Reachability is a property of WHERE THE GRAPH IS, not of
+            // the schema, so it is answered here and not by the enum: a
+            // destination valid from `work` is invalid from `home`, and
+            // the honest answer names what is reachable right now.
+            const from = h.current;
+            await h.goToState(destination);
+            if (h.current !== destination) {
+                const edge = [...h.states.keys()];
+                return refuse("UNREACHABLE_FROM_HERE", destination,
+                    edge.filter((id) => id !== from));
+            }
+            return { ok: true, view: h.current, ...readSubtree(h.stage || mount) };
+        }),
+
+        back: () => serial(async () => {
+            const h = handles.find((x) => x.history && x.history.length);
+            if (!h) return refuse("NO_HISTORY", null, []);
+            await h.goBack();
+            return { ok: true, view: h.current, ...readSubtree(h.stage || mount) };
+        }),
+
+        read: async () => ({ ok: true, ...readSubtree(mount) }),
+
+        submit: async (args = {}, tool) => {
+            const form = findForm(tool.formId);
+            if (!form) return refuse("NO_FORM", tool.formId, []);
+
+            const props = (tool.inputSchema && tool.inputSchema.properties) || {};
+            const required = (tool.inputSchema && tool.inputSchema.required) || [];
+            const missing = required.filter(
+                (k) => args[k] === undefined || args[k] === "" || args[k] === null);
+            if (missing.length) {
+                // The constraint, not a boolean. A generator repairs from
+                // this in one turn; "false" costs it a guess.
+                return refuse("MISSING_REQUIRED", missing, Object.keys(props));
+            }
+
+            const filled = [];
+            for (const key of Object.keys(props)) {
+                if (args[key] === undefined) continue;
+                const field = form.querySelector(
+                    `[name="${key}"], #${CSS.escape(key)}`);
+                if (!field) continue;
+                if (field.type === "checkbox") field.checked = !!args[key];
+                else field.value = String(args[key]);
+                // Both, because component state may listen for either.
+                field.dispatchEvent(new Event("input", { bubbles: true }));
+                field.dispatchEvent(new Event("change", { bubbles: true }));
+                filled.push(key);
+            }
+
+            // Submitted through the form's OWN path, so its listeners,
+            // its validation attributes and the browser's constraint
+            // checking all apply. An agent submit is a user submit.
+            if (typeof form.requestSubmit === "function") form.requestSubmit();
+            else form.submit();
+            return { ok: true, submitted: tool.formId, filled };
+        },
+    };
+
+    // ── registration, if this browser has anywhere to register ───────
+    const reg = registry();
+    let registered = false;
+    if (reg && typeof reg.registerTool === "function") {
+        for (const t of tools) {
+            try {
+                reg.registerTool({
+                    name: t.name,
+                    description: t.description,
+                    inputSchema: t.inputSchema,
+                    execute: (args) => execute[t.kind](args, t),
+                });
+                registered = true;
+            } catch (e) {
+                // A failed registration must never take the page down.
+                console.warn("[nodality] agent surface: tool rejected", t.name, e);
+            }
+        }
+    }
+
+    return {
+        manifest, tools, registered,
+        destroy() {
+            if (reg && typeof reg.unregisterTool === "function") {
+                for (const t of tools) {
+                    try { reg.unregisterTool(t.name); } catch (e) { /* already gone */ }
+                }
+            }
+            if (typeof document !== "undefined") {
+                const tag = document.getElementById(MANIFEST_ID);
+                if (tag) tag.remove();
+            }
+        },
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nodality",
-  "version": "1.1.15",
+  "version": "1.2.0",
   "description": "A lightweight library for declarative UI elements.",
   "main": "dist/index.cjs.js",
   "module": "dist/index.esm.js",