nodality 1.2.11 → 1.3.1

package/scripts/generate-schema.mjs

@@ -122,7 +122,15 @@ function paramsOf(file) {
   const found = new Set();
   for (const line of liveLines(text)) {
     for (const m of line.matchAll(/\bobj\.([a-zA-Z][a-zA-Z0-9]*)/g)) found.add(m[1]);
-    for (const m of line.matchAll(/\bthis\.options\.([a-zA-Z][a-zA-Z0-9]*)/g)) found.add(m[1]);
+    // A bare `options.` too, not just `this.options.`. Several components
+    // name the argument of `set()` `options` rather than `obj` — image.js,
+    // link.js, container.js, the two flex layouts — and every read in them
+    // was invisible to this scan. The cost was concrete and in the
+    // accessibility path: `alt` was missing from `img`, so the per-type
+    // vocabulary an agent is pointed at by `npx nodality schema img` did not
+    // mention the parameter that makes an image describable, while the
+    // renderer read it perfectly well.
+    for (const m of line.matchAll(/\boptions\.([a-zA-Z][a-zA-Z0-9]*)/g)) found.add(m[1]);
   }
   for (const junk of ["options", "el", "customOptions", "storage", "i"]) found.delete(junk);
   paramCache.set(file, found);

package/skills/nodality/SKILL.md

@@ -68,6 +68,20 @@ Skipping step 3 is the classic failure: a misspelled op renders
 *nothing* rather than erroring, so the page looks plausible and is
 silently missing its effects.
 
+## HTML's names are accepted
+
+`src` and `href` both mean `url`; `options` means `items`. Write either — the
+canonical names are `url` and `items`, and that is what `get_schema` reports.
+Giving both with **different** values is reported as `CONFLICTING_ALIAS`,
+because one of them would be ignored.
+
+A table's rows may also be written as arrays with the header row first, the way
+a CSV is:
+
+```js
+{ type: "table", items: [["date", "race"], ["29/08", "Krusnoman"]] }
+```
+
 ## Composites carry their content in a slot
 
 A composite is not empty scaffolding – you give it content, and **which
@@ -195,6 +209,42 @@ One naming caution: `Text` and `Image` collide with DOM constructor
 names. Always use the module import; on a page using the CDN globals,
 never assume `window.Text` / `window.Image` are still the DOM's own.
 
+## Building more than one page
+
+Declare shared chrome once and reference it. **`.defs()` must come before
+`.add()`** — `add` renders as it goes, so definitions arriving later cannot be
+used, and the wrong order is refused with a message saying so.
+
+```js
+const shared = {                      // one file, imported by every page
+  nav:    { type: "nav", items: [{ title: "Home", link: "/" }] },
+  footer: { type: "wrap", children: [{ type: "p", text: "Acme" }] },
+};
+
+new Des().defs(shared).nodes(N)
+  .add([{ $ref: "nav" }, { type: "h1", text: "Pricing" }, { $ref: "footer" }])
+  .set({ mount: "#mount" });
+```
+
+Keys written beside a reference **override** the definition, which is how one
+nav serves every page:
+
+```js
+{ $ref: "nav", id: "topnav" }                       // adds an id
+{ $ref: "nav", items: [{ title: "Docs", link: "/d" }] }   // replaces the list
+```
+
+The merge is shallow: an override replaces a slot, it does not extend it.
+
+Worth it from **two pages up**: on a single page a reference costs more than
+writing the thing, so do not reach for it before then. On a real site's nav and
+footer it is 1.7x at four pages and about 2x at ten — measured, because 61% of
+every token in that site was the same chrome repeated.
+
+A name with no definition is refused at render and reported by
+`validate_nodes` as `DANGLING_REF` with a did-you-mean, so pass `defs` as the
+third argument when you validate a page that uses references.
+
 ## Editing a page that already exists
 
 Editing is the common case in production, and it does not mean