nodality 1.3.0 → 1.3.2

package/lib/check-page.js

@@ -1,5 +1,5 @@
 /*!
- * nodality v1.3.0
+ * nodality v1.3.2
  * (c) 2026 Filip Vabrousek
  * License: MIT
  */
@@ -45,18 +45,85 @@ export const DEFAULT_VIEWPORTS = [
  */
 const IN_PAGE = () => {
     const out = [];
-    const add = (code, path, got, detail) => out.push({ code, path, got, detail });
 
-    /** A short, stable selector for a node, so a report can be acted on. */
+    /**
+     * A PAGE-UNIQUE selector, so a report can be acted on.
+     *
+     * The first version was parent-relative and returned `input` for any input
+     * that was the only one under its own div. A form with three unlabelled
+     * fields produced the string "input" three times, the merge at the bottom
+     * of this file keyed on it, and three findings collapsed into one row
+     * reading `viewport: "mobile, mobile, mobile"`. The agent was told neither
+     * which control nor that there were three — Tier 7 watched a model fail to
+     * repair exactly that. A path walks to the nearest id, or to the body.
+     */
     const sel = (el) => {
         if (!el || !el.tagName) return "?";
-        if (el.id) return `#${CSS.escape(el.id)}`;
-        const tag = el.tagName.toLowerCase();
-        const cls = (el.getAttribute("class") || "").trim().split(/\s+/).filter(Boolean)[0];
-        const base = cls ? `${tag}.${CSS.escape(cls)}` : tag;
-        const sibs = el.parentElement
-            ? [...el.parentElement.children].filter((n) => n.tagName === el.tagName) : [];
-        return sibs.length > 1 ? `${base}:nth-of-type(${sibs.indexOf(el) + 1})` : base;
+        const seg = (n) => {
+            const tag = n.tagName.toLowerCase();
+            const sibs = n.parentElement
+                ? [...n.parentElement.children].filter((x) => x.tagName === n.tagName) : [];
+            return sibs.length > 1 ? `${tag}:nth-of-type(${sibs.indexOf(n) + 1})` : tag;
+        };
+        const parts = [];
+        for (let n = el; n && n !== document.body; n = n.parentElement) {
+            if (n.id) { parts.unshift(`#${CSS.escape(n.id)}`); break; }
+            parts.unshift(seg(n));
+        }
+        return parts.join(" > ") || el.tagName.toLowerCase();
+    };
+
+    /**
+     * The SPEC node an element came from, when the page carries annotation.
+     * A selector says where in the DOM; this says which descriptor to edit,
+     * which is the thing an agent repairing a spec actually needs. Free when
+     * the annotation is there, null when it is not — it is opt-in, and the
+     * attribute name is spelled out here because this function crosses into
+     * the browser as a string and cannot import `SPEC_ATTR`. A test pins the
+     * two together.
+     */
+    const nod = (el) => {
+        for (let n = el; n && n !== document.body; n = n.parentElement) {
+            const v = n.getAttribute && n.getAttribute("data-nod");
+            if (v) return v;
+        }
+        return null;
+    };
+
+    // `target` is the element itself, so a finding can carry both. A string is
+    // passed for findings about the document rather than about an element.
+    const add = (code, target, got, detail) => {
+        const isEl = !!(target && target.tagName);
+        out.push({
+            code, path: isEl ? sel(target) : String(target), got, detail,
+            nod: isEl ? nod(target) : null,
+        });
+    };
+
+    /**
+     * A name assistive technology can announce.
+     *
+     * Was `aria-label` alone, which is only one of the four ways to give one
+     * and the least used. A control correctly labelled by a `<label for>` —
+     * the ordinary HTML way — was reported as unnamed, and a false finding
+     * sends a repair at something that was never broken, which this file
+     * argues elsewhere is worse than a miss.
+     */
+    const hasName = (el) => {
+        if ((el.getAttribute("aria-label") || "").trim()) return true;
+        if ((el.getAttribute("title") || "").trim()) return true;
+        const by = (el.getAttribute("aria-labelledby") || "").trim();
+        if (by && by.split(/\s+/).some((id) => {
+            const t = document.getElementById(id);
+            return t && (t.textContent || "").trim();
+        })) return true;
+        if (el.id) {
+            const l = document.querySelector(`label[for="${CSS.escape(el.id)}"]`);
+            if (l && (l.textContent || "").trim()) return true;
+        }
+        const wrap = el.closest && el.closest("label");
+        if (wrap && (wrap.textContent || "").trim()) return true;
+        return false;
     };
 
     const all = [...document.body.querySelectorAll("*")];
@@ -78,7 +145,7 @@ const IN_PAGE = () => {
         // 2. An element sticking out past the right edge. Left/top are not
         //    checked: off-canvas menus and slide-in panels park there legitimately.
         if (r.right > vw + 1 && cs.position !== "fixed") {
-            add("ELEMENT_OVERFLOWS_VIEWPORT", sel(el), Math.round(r.right),
+            add("ELEMENT_OVERFLOWS_VIEWPORT", el, Math.round(r.right),
                 `extends ${Math.round(r.right - vw)}px past the ${vw}px viewport`);
         }
 
@@ -87,7 +154,7 @@ const IN_PAGE = () => {
         if ((cs.overflow === "hidden" || cs.overflowY === "hidden") &&
             el.scrollHeight > el.clientHeight + 2 && el.clientHeight > 0 &&
             (el.textContent || "").trim().length > 0) {
-            add("CONTENT_CLIPPED", sel(el), el.scrollHeight,
+            add("CONTENT_CLIPPED", el, el.scrollHeight,
                 `content is ${el.scrollHeight}px in a ${el.clientHeight}px box with overflow hidden`);
         }
 
@@ -95,24 +162,38 @@ const IN_PAGE = () => {
         //    too, which is what this library's cards emit.
         const tag = el.tagName.toLowerCase();
         if (tag === "img" && !el.hasAttribute("alt")) {
-            add("IMAGE_WITHOUT_ALT", sel(el), el.getAttribute("src") || "", "no alt attribute");
+            add("IMAGE_WITHOUT_ALT", el, el.getAttribute("src") || "", "no alt attribute");
         }
         if (el.getAttribute("role") === "img" && !el.getAttribute("aria-label")) {
-            add("IMAGE_WITHOUT_ALT", sel(el), "role=img", "role=img with no aria-label");
+            add("IMAGE_WITHOUT_ALT", el, "role=img", "role=img with no aria-label");
         }
 
         // 5. A target too small to hit. 24px is the WCAG 2.2 AA minimum.
+        //
+        // `select` and `textarea` were both missing from this set, so neither
+        // check below ever ran on one. A picker could not be given an
+        // accessible name at all — `label` reached the component and nothing
+        // read it — and no report said so, because the checker was not
+        // looking. Two blind spots that hid each other.
         const interactive = tag === "a" || tag === "button" ||
-            (tag === "input" && el.type !== "hidden") || el.getAttribute("role") === "button";
+            (tag === "input" && el.type !== "hidden") ||
+            tag === "select" || tag === "textarea" ||
+            el.getAttribute("role") === "button";
         if (interactive && r.width > 0 && (r.width < 24 || r.height < 24)) {
-            add("TAP_TARGET_TOO_SMALL", sel(el), `${Math.round(r.width)}x${Math.round(r.height)}`,
+            add("TAP_TARGET_TOO_SMALL", el, `${Math.round(r.width)}x${Math.round(r.height)}`,
                 "below the 24x24 minimum");
         }
 
         // 6. A control with nothing to announce.
-        if (interactive && !(el.textContent || "").trim() &&
-            !el.getAttribute("aria-label") && !el.querySelector("img[alt]:not([alt=''])")) {
-            add("CONTROL_WITHOUT_LABEL", sel(el), tag, "no text and no accessible name");
+        //
+        // A <select>'s own text is its OPTIONS and a <textarea>'s is its
+        // VALUE. Neither names the control, so the textContent shortcut that
+        // clears a button by its caption must not clear these.
+        const ownText = (tag === "select" || tag === "textarea")
+            ? "" : (el.textContent || "").trim();
+        if (interactive && !ownText && !hasName(el) &&
+            !el.querySelector("img[alt]:not([alt=''])")) {
+            add("CONTROL_WITHOUT_LABEL", el, tag, "no text and no accessible name");
         }
     }
 
@@ -123,7 +204,7 @@ const IN_PAGE = () => {
     for (const h of heads) {
         const lvl = Number(h.tagName[1]);
         if (prev && lvl > prev + 1) {
-            add("HEADING_LEVEL_SKIPPED", sel(h), h.tagName,
+            add("HEADING_LEVEL_SKIPPED", h, h.tagName,
                 `h${prev} is followed by ${h.tagName.toLowerCase()}`);
         }
         prev = lvl;
@@ -163,19 +244,83 @@ const IN_PAGE = () => {
         const large = size >= 24 || (size >= 18.66 && Number(cs.fontWeight) >= 700);
         const need = large ? 3 : 4.5;
         if (ratio < need) {
-            add("LOW_CONTRAST", sel(el), `${ratio.toFixed(2)}:1`,
+            add("LOW_CONTRAST", el, `${ratio.toFixed(2)}:1`,
                 `needs ${need}:1 at ${Math.round(size)}px`);
         }
     }
     return out;
 };
 
+/**
+ * How to repair each finding, in THIS library's vocabulary.
+ *
+ * `suggestions` and `valid` are in the finding shape because `validate_nodes`
+ * puts repairs there, and check_page left both empty on every finding it has
+ * ever emitted — a field that is always blank is a field an agent learns to
+ * ignore. Tier 7 measured the cost. Told only "54x23, below the 24x24
+ * minimum", the strong model guessed `keySet: {key, value}` and was right, the
+ * weaker one invented `keySet: {"--tap-target-size": "44px"}` and was wrong,
+ * and the page stayed broken through the repair turn. Naming the element was
+ * not enough; the report has to name the edit.
+ *
+ * Kept deliberately short. These are the repair that fits the overwhelming
+ * majority of cases, not a treatment of every way a page can be wrong — an
+ * agent that needs more has `npx nodality schema <type>`.
+ */
+const REPAIRS = {
+    TAP_TARGET_TOO_SMALL: {
+        suggestions: [`keySet: { key: "min-height", value: "44px" }`,
+                      `keySet: { key: "min-width", value: "44px" }`,
+                      `pad: [{ a: 12 }]`],
+        valid: ["at least 24x24 CSS pixels, per WCAG 2.2 AA target size (minimum)"],
+    },
+    CONTROL_WITHOUT_LABEL: {
+        suggestions: [`label: "<what the field is for>"  (input, labelInput, picker)`,
+                      `text: "<what the control does>"  (button, a)`],
+        valid: ["every control needs a name assistive technology can announce; " +
+                "a placeholder is not one"],
+    },
+    IMAGE_WITHOUT_ALT: {
+        suggestions: [`alt: "<what the image shows>"`,
+                      `alt: ""  if it is decorative and repeats nearby text`],
+        valid: ["img takes `alt`; a background image takes it too and becomes aria-label"],
+    },
+    LOW_CONTRAST: {
+        suggestions: [`color: "<a darker or lighter text colour>"`,
+                      `background: "<a background with more separation>"`],
+        valid: ["4.5:1 for body text, 3:1 at 24px or at 18.66px bold"],
+    },
+    HEADING_LEVEL_SKIPPED: {
+        suggestions: [`tag: "h<the next level down>"`],
+        valid: ["`tag` sets the heading level independently of the size scale, " +
+                "so the outline can be correct without changing the design"],
+    },
+    ELEMENT_OVERFLOWS_VIEWPORT: {
+        suggestions: [`maxWidth: "100%"`, `width: "100%"`, `breakWord: true`],
+        valid: ["nothing may extend past the right edge of the viewport"],
+    },
+    HORIZONTAL_OVERFLOW: {
+        suggestions: [`maxWidth: "100%" on whichever element the other findings name`],
+        valid: ["the document may not be wider than the viewport"],
+    },
+    CONTENT_CLIPPED: {
+        suggestions: [`height: "auto"`, `overflow: "visible"`],
+        valid: ["a box with `overflow: hidden` must be tall enough for its text"],
+    },
+};
+
 /**
  * Check rendered HTML and return a report in the shape everything else here
  * returns. `html` is a full document or a fragment; a fragment is wrapped.
  */
 export async function checkPage(html, opts = {}) {
     const viewports = opts.viewports || DEFAULT_VIEWPORTS;
+    // `load` is right for a self-contained page, which is what this library
+    // emits. A page whose styling arrives over the network — a CDN stylesheet,
+    // a webfont — has not been laid out yet at `load`, and measuring it there
+    // reports the unstyled document. Callers checking such a page pass
+    // "networkidle".
+    const waitUntil = opts.waitUntil || "load";
     let chromium;
     try {
         ({ chromium } = await import("playwright"));
@@ -208,16 +353,20 @@ export async function checkPage(html, opts = {}) {
         for (const vp of viewports) {
             const page = await browser.newPage({ viewport: { width: vp.width, height: vp.height } });
             try {
-                await page.setContent(doc, { waitUntil: "load" });
+                await page.setContent(doc, { waitUntil });
                 const found = await page.evaluate(IN_PAGE);
                 for (const f of found) {
                     errors.push({
                         code: f.code,
                         path: f.path,
                         got: f.got,
-                        suggestions: [],
-                        valid: [],
+                        suggestions: REPAIRS[f.code]?.suggestions ?? [],
+                        valid: REPAIRS[f.code]?.valid ?? [],
                         detail: f.detail,
+                        // The spec node, when the page was annotated. Null
+                        // otherwise, rather than absent, so the field's
+                        // meaning does not depend on whether it is there.
+                        nod: f.nod ?? null,
                         viewport: vp.name,
                     });
                 }

package/lib/codegen.js

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

package/lib/data.js

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

package/lib/designer.js

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

package/lib/element-mapper.js

@@ -1,5 +1,5 @@
 /*!
- * nodality v1.3.0
+ * nodality v1.3.2
  * (c) 2026 Filip Vabrousek
  * License: MIT
  */
@@ -566,8 +566,16 @@ animation: {
                   // wrote `label`. The field it produced then had no
                   // accessible name at all — a placeholder is not one, since
                   // it disappears the moment anyone types.
-                  ...(el.label !== undefined && el.title === undefined
-                      ? { title: el.label } : {}),
+                  //
+                  // `text` joined them after Tier 7. A model wrote
+                  // `{type:"labelInput", text:"Name"}` and the field rendered
+                  // the literal string "undefined" as its label, its
+                  // placeholder and its accessible name, while validate_nodes
+                  // reported ok — the worst available outcome for a spelling
+                  // this natural. Tier 6's rule applies: take what the world
+                  // already writes. `title` still wins, then `label`.
+                  ...(el.title === undefined && (el.label !== undefined || el.text !== undefined)
+                      ? { title: el.label !== undefined ? el.label : el.text } : {}),
                   ...this.elOpts(el),
               }), el, obj.customOptions);
       }

package/lib/element-params.generated.js

@@ -1,5 +1,5 @@
 /*!
- * nodality v1.3.0
+ * nodality v1.3.2
  * (c) 2026 Filip Vabrousek
  * License: MIT
  */
@@ -8,4 +8,4 @@
 // 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","alt","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","tag","tags","templateCols","text","theme","tint","title","top","transform","transition","type","url","useBrightness","value","vtn","weight","width","x","y","zIndex"];
+export const ELEMENT_PARAM_NAMES = ["absolute","accept","action","align","alignIts","alignTo","aligns","alt","animate","animation","area","arrayMargin","arrayPadding","as","at","auto","backTo","background","backgroundCard","backgroundColor","backgroundOp","behaviour","blast","blastData","block","bold","border","borderObj","borderObja","borderRadius","brand","breakWord","breakpoints","cellAlign","cellPadding","center","centerColumn","centerSelf","centered","checkedBackgroundColor","child","children","clampc","class","clipPath","code","colat","color","column","contentWidth","cursor","customAlign","customJustify","customStyle","data","decoding","diameter","disp","dropdown","em","exact","fetchPriority","filter","filtera","fitContent","fixMobileTap","fixed","flex","flexCenter","flexDir","fluid","fluidc","font","frame","ga","gap","gpos","gradient","hamColour","hamburgerColour","headStyle","height","hideField","hideOverflow","hover","icon","id","img","index","initLetter","inline","inpad","inputType","isBackground","isFull","isHidden","isLink","isNavA","italic","items","justifo","justify","keySet","kind","label","layout","left","length","link","loading","map","mar","margin","marginOp","maxHeight","maxWidth","mboth","method","minHeight","mobile","multiple","name","new","nowrap","objectFit","objectPosition","offcanvas","okayColor","onScroll","onTap","opacity","overflow","owrap","pad","padding","placeholder","position","positions","preffersId","radius","ranges","raster","react","removeDecoration","required","resmar","respad","responsive","resprop","rounded","scale","sequence","shadow","sides","simpleBorder","simpleCenter","size","sizes","span","srcset","sticky","stretch","stroke","style","stype","svg","tag","tags","templateCols","text","theme","tint","title","toColumn","top","transform","transition","type","url","useBrightness","value","vtn","weight","width","wrap","x","y","zIndex"];

package/lib/keyframe-animation.js

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

package/lib/link-getter.js

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

package/lib/morph-node.js

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

package/lib/normalize-spec.js

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

package/lib/parse-html.js

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

package/lib/raster-inspect.js

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

package/lib/raster-ops.js

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

package/lib/raster-presets.js

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

package/lib/resolve-refs.js

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

package/lib/scroll-video.js

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

package/lib/seo.js

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

package/lib/stacker.js

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

package/lib/suggest.js

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

package/lib/theme.js

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

package/lib/transform-anim.js

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

package/lib/transition.js

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

package/lib/validate-nodes.js

@@ -1,5 +1,5 @@
 /*!
- * nodality v1.3.0
+ * nodality v1.3.2
  * (c) 2026 Filip Vabrousek
  * License: MIT
  */
@@ -163,6 +163,15 @@ export const CONTENT_SLOT = {
     row: "children", form: "children", wrap: "children",
 };
 
+// Of the types that read `items`, which read the entries as ELEMENT SPECS
+// rather than as data. `ulist` maps every object entry through the mapper;
+// `cards`, `nav`, `sideNav` and `table` read theirs as data — nav entries are
+// `{title, link}`, table entries are rows — and walking those as elements
+// would report every correct page. Pinned against the mapper by a test rather
+// than trusted, because a hand-kept table beside a mapper is exactly what
+// drifted before 1.2.8.
+export const SPEC_ITEMS = new Set(["ulist"]);
+
 export function validateNodes(nodes, elements, defs) {
     const errors = [];
     const push = (code, path, got, suggestions, valid) => {
@@ -382,6 +391,48 @@ export function validateNodes(nodes, elements, defs) {
                         if (Array.isArray(entry)) walkEls(entry, `${p}.items[${k}]`);
                     });
                 }
+
+                // Phase S7: an object entry with no `type`, in a slot whose
+                // entries ARE elements. `{type:"ulist", items:[{text:"Fast"}]}`
+                // validated clean and then threw from deep in the mapper —
+                // `Unknown element type "undefined"` — which is the Stage 3
+                // contract exactly inverted: validate-then-render handed the
+                // agent a stack trace in the one place the tool exists to
+                // prevent it.
+                //
+                // Tier 7 measured what that cost. The throw names every valid
+                // type and not one word about WHICH entry, so it is the same
+                // string for every fault of this shape on any page; the weaker
+                // of the two models repaired none of them and returned a
+                // byte-identical spec. The suggestion below therefore hands
+                // back the replacement rather than describing it.
+                //
+                // A string entry is the shorthand and stays valid.
+                if (SPEC_ITEMS.has(el.type) && Array.isArray(el.items)) {
+                    el.items.forEach((entry, k) => {
+                        const at = `${p}.items[${k}]`;
+                        if (typeof entry === "string" || typeof entry === "number") return;
+                        if (Array.isArray(entry)) return;
+                        if (!entry || typeof entry !== "object") {
+                            push("BAD_ELEMENT", at, entry, [],
+                                ["a string, or { type: \"<element type>\", ... }"]);
+                            return;
+                        }
+                        if (isRef(entry)) return;
+                        if (typeof entry.type !== "string") {
+                            const text = ["text", "title", "label"]
+                                .map((k2) => entry[k2]).find((v) => typeof v === "string");
+                            push("MISSING_FIELD", `${at}.type`, entry.type,
+                                text === undefined ? []
+                                    : [JSON.stringify(text),
+                                       `{ "type": "p", "text": ${JSON.stringify(text)} }`],
+                                [`"${el.type}" reads each item as an element; a plain string is the shorthand`]);
+                        } else if (!ELEMENT_TYPES.includes(entry.type)) {
+                            push("UNKNOWN_ELEMENT_TYPE", `${at}.type`, entry.type,
+                                suggest(entry.type, ELEMENT_TYPES), ELEMENT_TYPES);
+                        }
+                    });
+                }
             });
         };
         walkEls(toWalk, "elements");