nodality 1.2.6 → 1.2.8

package/layout/side-bar.js

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

package/layout/side-nav-bar.js

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

package/layout/simple-bar.js

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

package/layout/slider-2025.js

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

package/layout/spacer.js

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

package/layout/stack.js

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

package/layout/svg.js

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

package/layout/switcher.js

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

package/layout/table.js

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

package/layout/text-field.js

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

package/layout/text.js

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

package/layout/ulist.js

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

package/layout/video.js

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

package/layout/wrap.js

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

package/layout/zoom-card.js

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

package/lib/agent-surface.js

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

package/lib/card-getter.js

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

package/lib/codegen.js

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

package/lib/data.js

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

package/lib/designer.js

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

package/lib/element-mapper.js

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

package/lib/keyframe-animation.js

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

package/lib/link-getter.js

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

package/lib/morph-node.js

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

package/lib/raster-inspect.js

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

package/lib/raster-ops.js

@@ -1,5 +1,5 @@
 /*!
- * nodality v1.2.6
+ * nodality v1.2.8
  * (c) 2026 Filip Vabrousek
  * License: MIT
  */
@@ -839,7 +839,9 @@ ${NB.map(([x, y]) => probe(x, y)).join("")}
                 count: {
                     default: 5, unit: "count", structural: true,
                     summary: "stamps arranged in a ring around the focus. The loop is "
-                        + "unrolled at compile time, so this rebuilds — not something to animate.",
+                        + "unrolled at compile time, so this rebuilds — not something to animate. "
+                        + "This default is the shader's; the DOM path that an element of type "
+                        + "\"copy\" takes uses 3 instead.",
                 },
                 points: {
                     default: null, unit: "point", structural: true,
@@ -851,6 +853,21 @@ ${NB.map(([x, y]) => probe(x, y)).join("")}
                 rotate: { default: 0, unit: "deg", summary: "rotation applied per copy" },
                 fade: { default: 1, unit: "ratio", summary: "opacity falloff across the set" },
                 amount: { default: 1, unit: "ratio", summary: "overall blend of the copies over the original" },
+                animation: {
+                    default: false, unit: "bool",
+                    // Read by ElementMapper.mapCopy, not by this file. The
+                    // doc-consistency check scans raster-ops.js for
+                    // `node.<key>` and would otherwise call this a param that
+                    // nothing reads; naming the reader moves that check to the
+                    // right source instead of switching it off.
+                    readBy: "element-mapper",
+                    summary: "DOM path only. An element of type \"copy\" is built by the "
+                        + "mapper rather than by the shader, and this asks that mapper for "
+                        + "animated copies; the shader path ignores it. Declared because "
+                        + "the mapper has always read it and the docs have always taught "
+                        + "it, while the registry did not list it – so the validator "
+                        + "reported a documented, working node as an unknown parameter.",
+                },
             },
         },
         // `count`/`points` unroll the stamp loop at compile time.

package/lib/raster-presets.js

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

package/lib/scroll-video.js

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

package/lib/seo.js

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

package/lib/stacker.js

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

package/lib/suggest.js

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

package/lib/theme.js

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

package/lib/transform-anim.js

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

package/lib/transition.js

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

package/lib/validate-nodes.js

@@ -1,5 +1,5 @@
 /*!
- * nodality v1.2.6
+ * nodality v1.2.8
  * (c) 2026 Filip Vabrousek
  * License: MIT
  */
@@ -59,6 +59,59 @@ const EDGE_FIELDS = [
  */
 const AGENT_SURFACE_FIELDS = ["op", "name", "forms", "exclude"];
 
+/**
+ * Design ops that may be written as a BARE STRING, `{ op: "gradient" }`,
+ * and are expanded against a table of defaults by `Des.add`. This list is
+ * that table's key set (`ops` in designer.js) and must track it: a string
+ * outside it is never expanded, so it reaches the renderer as a node
+ * nothing matches and does nothing at all.
+ *
+ * None of these collide with a raster op name, which is what makes the
+ * two string families separable at all.
+ */
+const BARE_DESIGN_OPS = [
+    "blast", "gradient", "shadow", "filter", "animation", "transform", "span",
+];
+
+/**
+ * Design ops written in object form, `{ op: { name: "gradient", … } }`.
+ *
+ * Assembled from the dispatch sites rather than from the documentation,
+ * because the two disagree: the reference calls one of these "LinkStyle"
+ * while the runtime matches `"link-style"`. Deliberately generous — a
+ * name missing from this list produces a false UNKNOWN_DESIGN_OP on a
+ * node that works, and `preview` refuses to render an invalid pair, so
+ * over-reporting costs more than under-reporting.
+ */
+const DESIGN_OP_NAMES = [
+    "animation", "background", "blast", "card-style", "filter", "gradient",
+    "layout", "link-style", "margin", "navStyle", "shadow", "slayout",
+    "span", "transform",
+];
+
+/**
+ * Every top-level key a design node reads.
+ *
+ * Both forms read `op`, `target`, `range`, and — from the loop that runs
+ * over every node, not just the expanded ones — `style` and `duration`.
+ * Anything else on the object form is ignored in silence, which is
+ * precisely how the README's `colors: [...]` survived.
+ *
+ * The bare-string form reads four more, because its expansion lifts them
+ * INTO the op it substitutes: that is how
+ * `{ op: "gradient", gradient: "linear-gradient(…)" }` customises the
+ * default, and it is documented, so the two forms cannot share one list.
+ *
+ * Assembled by reading every `customOptions[i].x` and `protoOptions[i].x`
+ * in designer.js, then swept against the e2e fixtures — which is how
+ * `style` and `duration` were caught. Guessing this list produces false
+ * positives on working pages, and `preview` refuses an invalid pair.
+ */
+const DESIGN_FIELDS = ["op", "target", "range", "style", "duration"];
+const BARE_DESIGN_FIELDS = [
+    ...DESIGN_FIELDS, "filter", "gradient", "color", "width",
+];
+
 /** Node families, told apart exactly the way the runtime tells them apart. */
 const familyOf = (node) => {
     if (!node || typeof node !== "object") return "invalid";
@@ -66,6 +119,12 @@ const familyOf = (node) => {
     if (typeof op === "string") {
         if (op === "morph") return "morph";
         if (op === "agent-surface") return "agent-surface";
+        // Checked BEFORE falling through to raster. A bare-string design
+        // op is not a raster op, and reporting it as an unknown one was a
+        // false positive on documented usage: `{ op: "gradient" }` is on
+        // the gradient page, renders the default gradient, and validated
+        // as UNKNOWN_OP suggesting a raster op that would not do it.
+        if (BARE_DESIGN_OPS.includes(op)) return "design";
         return "raster";
     }
     if (op && typeof op === "object" && typeof op.name === "string") return "design";
@@ -174,7 +233,53 @@ export function validateNodes(nodes, elements) {
 
         checkTargets(node.target, `${path}.target`);
 
-        if (family === "design") return;   // design nodes carry their own vocabulary
+        if (family === "design") {
+            // Was `return` — "design nodes carry their own vocabulary", which
+            // was true and yet left the whole family unchecked. The cost was
+            // paid in the reference: a design option written in the wrong
+            // place is not a no-op with a warning, it is a no-op in silence,
+            // and the gradient one made the target INVISIBLE. Checked here at
+            // the two levels the runtime actually reads.
+            const bare = typeof node.op === "string";
+            const name = bare ? node.op : node.op.name;
+
+            if (!bare && !DESIGN_OP_NAMES.includes(name)) {
+                push("UNKNOWN_DESIGN_OP", `${path}.op.name`, name,
+                    suggest(name, DESIGN_OP_NAMES), DESIGN_OP_NAMES);
+            }
+
+            // Top-level keys. The object form reads three; the bare-string
+            // form reads four more because its expansion lifts them into the
+            // op it substitutes.
+            const allowed = bare ? BARE_DESIGN_FIELDS : DESIGN_FIELDS;
+            for (const key in node) {
+                if (allowed.includes(key)) continue;
+                // A near miss of a real top-level field is a typo and gets
+                // the usual suggestion. Anything else, on the object form,
+                // is almost always an option written one level too high —
+                // design options live INSIDE `op` — so say where it goes
+                // rather than only listing what may sit out here. That is
+                // the whole of the README's `colors` mistake.
+                const near = suggest(key, allowed);
+                const hint = near.length || bare ? near : [`op.${key}`];
+                push("UNKNOWN_PARAM", `${path}.${key}`, key, hint, allowed);
+            }
+
+            // A gradient with nothing to paint. `op.gradient` is the CSS
+            // string and `op.direction: "radial"` substitutes a built-in
+            // one; with neither, the node names an effect that cannot
+            // happen. It renders as nothing since 1.2.7 and rendered as an
+            // invisible element before that, so it is worth a report either
+            // way. The bare-string form is exempt: its whole purpose is to
+            // take the default.
+            if (!bare && name === "gradient" &&
+                node.op.gradient === undefined && node.op.direction === undefined) {
+                push("MISSING_FIELD", `${path}.op.gradient`, undefined, [],
+                    ["a CSS gradient, e.g. \"linear-gradient(#1d6fe0, #7fd1ff)\"",
+                     "or direction: \"radial\" to take the built-in one"]);
+            }
+            return;
+        }
 
         if (family === "agent-surface") {
             // The ids this node names must exist, for the usual reason:

package/lib/webmcp-adapter.js

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

package/package.json

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

package/skills/nodality/SKILL.md

@@ -68,11 +68,19 @@ Told apart by the shape of `op`:
 
 | Family | Shape | Example |
 |---|---|---|
-| Design | `op` is an object | `{ op: { name: "shadow" }, target: ["card"] }` |
-| Raster | `op` is a string | `{ op: "dither", target: ["hero"], levels: 6 }` |
+| Design | `op` is an object, or one of seven shorthand strings | `{ op: { name: "shadow" }, target: ["card"] }` |
+| Raster | `op` is any other string | `{ op: "dither", target: ["hero"], levels: 6 }` |
 | Morph | `op: "morph"` | one transition, or a whole graph via `chain` |
 | Agent surface | `op: "agent-surface"` | exposes the page to AI agents as tools |
 
+**The design family has two shapes.** The object form takes its options
+inside `op`. The seven shorthand names – `blast`, `gradient`, `shadow`,
+`filter`, `animation`, `transform`, `span` – expand against a table of
+defaults, so `{ op: "gradient" }` is a whole valid node. Only the
+shorthand accepts `gradient`, `filter`, `color` and `width` as top-level
+keys, because its expansion lifts them into the op it substitutes. Any
+other string is a raster op.
+
 Rules that are not obvious from the schema:
 
 - **Raster ops compose.** Several raster nodes aimed at the same element
@@ -111,14 +119,17 @@ A complete navigation graph is one node:
 - **Every element that a node targets needs an `id`.** Short and stable
   (`"hero"`, `"topnav"`); ids are the joint between the two arrays and
   appear in generated code.
-- **Do not invent options.** An unknown option is silently ignored, not
-  an error. If `list_ops` does not name it, it does not exist. And know
-  where options live: raster-op options sit on the node (`levels: 6`),
-  but design-node options sit INSIDE the `op` object
-  (`op: { name: "gradient", gradient: "linear-gradient(...)" }`). As of
-  1.2.5 the validator checks raster options, targets and element types
-  but NOT design-node options, so a misplaced design option fails
-  silently – the gradient renders its target invisible, for instance.
+- **Know where options live.** Raster-op options sit on the node
+  (`levels: 6`); design-node options sit INSIDE the `op` object
+  (`op: { name: "gradient", gradient: "linear-gradient(...)" }`).
+  Putting a design option at the top level is the single most common
+  mistake with this library – the project's own README shipped
+  `colors: [...]` there and rendered its headline invisible. Since 1.2.7
+  `validate_nodes` reports it and tells you where it belongs, so run the
+  validator rather than trusting the shape by eye.
+- **Do not invent options.** An option that no op declares is ignored in
+  silence rather than reported. If `list_ops` does not name it, it does
+  not exist.
 - **Codegen:** the on-page panel showing the imperative equivalent of
   the pair is on by default; pass `code: false` (and `elements: false`)
   to `.set()` to hide it on a production page. From the CLI,