sbuilder-mcp 0.76.4 → 0.78.0

package/dist/domains/site/review.js

@@ -4,7 +4,9 @@ import { bandOf } from './traps.js';
 import { HOVER_STATE, hoverHome } from './hover.js';
 import { ELEMENTS, BINDING_SOURCES, BOUND_SPECIALS, FIRST_CHILD_ONLY, SATELLITE_RULES, ELEMENT_SEEDS } from '../../catalog/elements.generated.js';
 import { fill } from './findings.js';
-import { deadNavigation } from './navhref.js';
+import { formFieldFindings } from './formdoc.js';
+import { deadNavigation, liveEventTable, PAYLOAD_NEEDS } from './navhref.js';
+import { unknownValueNote, unknownWriteNote, vocabularyFor, vocabularyForWrite } from './vocabulary.js';
 /**
  * A defect somebody looking at the page would see.
  *
@@ -34,7 +36,8 @@ export const REVIEW_NOTICE = 'FIX THESE. Each one is a defect a visitor will see
     'finding names, then review again until the list is empty. Do not report the page as done ' +
     'while findings stand; if you believe one is a false positive, say which and why. ' +
     'A finding marked overlay:true is in the cart drawer or a pop-up — fix it the same way ' +
-    '(sb_set lands there), but it is SITE-WIDE, so fix it once rather than once per page.';
+    '(sb_set lands there), but it is SITE-WIDE, so fix it once rather than once per page. ' +
+    '`advice` lists what works but is hard to edit — never a blocker.';
 /** The specials keys an element seeds that hold its visible content. */
 function contentKeys(type) {
     const seeded = ELEMENTS[type]?.defaults.specials ?? {};
@@ -126,6 +129,72 @@ const LINK_SPECIALS = new Set(['boundHref', 'boundHrefLabel', 'boundProductURL']
 function drawsItsOwnContent(type) {
     return (BOUND_SPECIALS[type] ?? []).some((k) => !LINK_SPECIALS.has(k));
 }
+/** Binding-source prefixes that name a RECORD (not `site.*`, which every page has). */
+const RECORD_ENTITIES = new Set(['product', 'category', 'course', 'article', 'blogCategory']);
+/**
+ * Which records a page TYPE supplies outside any repeater — read off the
+ * platform's own seeds (STORE_PAGE_SEEDS bind exactly these at top level).
+ */
+const PAGE_ENTITIES = {
+    product: ['product'],
+    category: ['category'],
+    course: ['course'],
+    post: ['article'],
+    blog: ['blogCategory', 'category'],
+};
+/** Does this node or an ancestor PIN a record (`bindings[0].target.id`)? */
+function pinnedAbove(d, id) {
+    for (let x = id; x && d.nodes[x]; x = d.nodes[x].data.parent) {
+        const b0 = d.nodes[x].bindings?.[0];
+        if (b0?.target?.id)
+            return true;
+    }
+    return false;
+}
+/**
+ * The native element a custom-code snippet re-implements, or null.
+ *
+ * Judged on the MARKUP left once every <script>, <style> and comment is
+ * stripped — so an analytics tag, a chat widget's mount div, or HTML built
+ * inside a script is never flagged — and only when that markup outweighs the
+ * script (mostly markup). An iframe counts only for the three hosts a native
+ * embed exists for; any other iframe is a third-party embed and stays.
+ * ponytail: tag-presence heuristic, not a parser — tighten if it cries wolf.
+ */
+function nativeFor(code) {
+    const scripts = code.match(/<script\b[\s\S]*?(<\/script>|$)/gi) ?? [];
+    const markup = code
+        .replace(/<script\b[\s\S]*?(<\/script>|$)/gi, '')
+        .replace(/<style\b[\s\S]*?(<\/style>|$)/gi, '')
+        .replace(/<!--[\s\S]*?-->/g, '');
+    if (markup.trim().length < scripts.join('').length)
+        return null;
+    // A form POSTING TO ANOTHER HOST (a Mailchimp / Klaviyo embed) is a
+    // third-party integration, not hand-built markup: a native form submits to
+    // this platform only, so there is nothing native to swap it for.
+    if (/<form\b[^>]*\baction\s*=\s*["']?(https?:)?\/\//i.test(markup))
+        return null;
+    const iframe = /<iframe\b[^>]*\bsrc\s*=\s*["']?([^"'\s>]+)/i.exec(markup)?.[1] ?? '';
+    if (/youtube(-nocookie)?\.com|youtu\.be/i.test(iframe))
+        return 'youtube';
+    if (/vimeo\.com/i.test(iframe))
+        return 'vimeo';
+    if (/google\.[a-z.]+\/maps|maps\.google\./i.test(iframe))
+        return 'google-map';
+    if (/<form\b/i.test(markup))
+        return 'form';
+    if (/<(nav|ul|ol)\b/i.test(markup) && (markup.match(/<a\b/gi) ?? []).length >= 2)
+        return 'menu';
+    if (/<h[1-6]\b/i.test(markup))
+        return 'heading';
+    if (/<video\b/i.test(markup))
+        return 'video';
+    if (/<img\b/i.test(markup))
+        return 'image';
+    if (/<button\b/i.test(markup))
+        return 'button';
+    return null;
+}
 /**
  * Everything wrong with this page that a person would notice.
  *
@@ -322,6 +391,113 @@ opts = {}) {
                 ...(inOverlay.has(id) ? { overlay: true } : {}),
             });
         }
+        // AN EVENT THE ELEMENT CANNOT FIRE, OR ONE WITH NOWHERE TO GO. `sb_event`
+        // refuses both at write time; a document gets here by other roads (an
+        // import, a template, a hand-built sb_api_call). Same table setEvent reads
+        // (`liveEventTable` in tools/live.ts): bindingEvents once a purchase binds.
+        const events = n.events ?? [];
+        if (events.length) {
+            const table = liveEventTable(d.nodes, id);
+            for (const ev of events) {
+                const trigger = String(ev?.name ?? '');
+                const action = String(ev?.action ?? '');
+                if (!table?.[trigger]?.includes(action)) {
+                    out.push({
+                        code: 'invalid_action',
+                        nodeId: id,
+                        type,
+                        problem: `"${action}" on ${trigger || '(no trigger)'} is not an action a ${type} offers` +
+                            (table?.[trigger] ? ` there (${table[trigger].join(', ')})` : '') +
+                            ' — it is stored and never fires.',
+                        key: trigger,
+                        fix: fill('invalid_action', { id, key: trigger }),
+                    });
+                    continue;
+                }
+                // The same table `sb_event` refuses by — one list, so the two cannot drift.
+                const need = PAYLOAD_NEEDS[action]?.key;
+                const v = (ev.payload ?? {})[need ?? ''];
+                if (need && (typeof v !== 'string' || v.trim() === '')) {
+                    out.push({
+                        code: 'action_missing_target',
+                        nodeId: id,
+                        type,
+                        problem: `Its ${trigger} "${action}" carries no payload.${need}, so the click does nothing.`,
+                        key: action,
+                        fix: fill('action_missing_target', { id, key: action }),
+                    });
+                }
+            }
+        }
+        // A RECORD-BOUND ELEMENT WITH NO RECORD. Inside a repeater the row supplies
+        // one; on an entity page (product, category, post…) the page does; a pin
+        // (`bindings[0].target.id`, render/html.go pinnedEntityID) does for its
+        // subtree. Anywhere else the binding resolves to nothing and the element
+        // renders its seeded placeholder for ever — saved, published, no warning.
+        // Overlays are skipped: one drawer serves every page type.
+        if (opts.pageType !== undefined && !inRepeater.get(id) && !inOverlay.has(id)) {
+            const entities = PAGE_ENTITIES[opts.pageType] ?? [];
+            const missing = (n.bindings ?? [])
+                .map((b) => String(b?.source ?? '').split('.')[0])
+                .find((e) => RECORD_ENTITIES.has(e) && !entities.includes(e));
+            if (missing && !pinnedAbove(d, id)) {
+                out.push({
+                    code: 'no_data_context',
+                    nodeId: id,
+                    type,
+                    problem: `Bound to a ${missing} record, but it sits in no repeater and a "${opts.pageType}" ` +
+                        'page supplies none — it renders its placeholder on the published page.',
+                    key: missing,
+                    fix: fill('no_data_context', { id, key: missing }),
+                });
+            }
+        }
+        // A STORED VALUE NO RENDERER READS. The same vocabulary `sb_set` warns from
+        // (`unknownWriteNote` / `unknownValueNote`), asked of what the document
+        // already holds — base and every breakpoint — because an import or a write
+        // made before the warning existed is still publishing the fallback.
+        {
+            const layered = n;
+            const layers = [
+                ['config', layered.config],
+                ['specials', n.specials],
+                ...Object.values(layered.responsive ?? {}).flatMap((r) => [['config', r?.config], ['specials', r?.specials]]),
+            ];
+            const said = new Set();
+            for (const [ns, slot] of layers) {
+                for (const [k, v] of Object.entries(slot ?? {})) {
+                    const unread = unknownWriteNote(type, ns, k, v) ?? (ns === 'config' ? unknownValueNote(k, v) : null);
+                    if (!unread || said.has(`${ns}.${k}=${String(v)}`))
+                        continue;
+                    said.add(`${ns}.${k}=${String(v)}`);
+                    const legal = (vocabularyForWrite(type, ns, k) ?? (ns === 'config' ? vocabularyFor(k) : null))?.values ?? [];
+                    out.push({
+                        code: 'unread_value',
+                        nodeId: id,
+                        type,
+                        problem: `${ns}.${k} = ${JSON.stringify(v)} is not a value the renderer reads; it publishes ` +
+                            `as its fallback with no error. Legal: ${legal.map((x) => x || '""').join(', ')}.`,
+                        key: `${ns}.${k}`,
+                        fix: fill('unread_value', { id, type }),
+                    });
+                }
+            }
+        }
+        if (type === 'custom-code') {
+            const native = nativeFor(String((n.specials ?? {}).code ?? ''));
+            if (native) {
+                out.push({
+                    code: 'custom_code_native',
+                    nodeId: id,
+                    type,
+                    severity: 'maintenance',
+                    problem: `Hand-written markup a native ${native} covers. It works, but no inspector can edit ` +
+                        'it, it ignores the theme, and sb_review cannot see inside it.',
+                    key: native,
+                    fix: fill('custom_code_native', { id, key: native }),
+                });
+            }
+        }
         // PINNING FAILS WITH NOTHING ON SCREEN AND NOTHING IN THE LOG — both halves
         // of it — which is exactly what a review is for. `sb_set` refuses the second
         // case at write time, but a document reaches here by other roads: an import,
@@ -364,10 +540,11 @@ opts = {}) {
         // read 0 because the cart it was summing has just been emptied. Nothing
         // errors, and the shopper cannot tell a completed order from a failed one.
         //
-        // Checked on the FORM NODE rather than on the form record, because the
-        // record's own `afterSubmit: "redirect"` is stored by the API and carried
-        // nowhere (`forms/pagesource.go`) — reading it would report a page as fine
-        // on the strength of a setting the platform ignores.
+        // The FORM NODE's event, or the RECORD's own `afterSubmit: "redirect"` —
+        // carried since web_builder fcfde38ac (`forms/pagesource.go` stamps
+        // `sentRedirect`; the runtime follows it after the `form:success` chain).
+        // A `pageId` target that is unpublished falls back to the message; that is
+        // the page's own defect (readiness reports unpublished pages), not this one.
         if (type === 'form') {
             const events = n.events ?? [];
             const navigates = events.some((e) => e.name === 'form:success' &&
@@ -385,7 +562,8 @@ opts = {}) {
             const sellsFromCart = walkOrder.some((x) => !inOverlay.has(x) && d.nodes[x]?.data.type === 'cart-total');
             const formType = opts.formTypes?.[String(n.specials?.formId ?? '')];
             const isOrder = formType ? formType === 'order' : sellsFromCart;
-            if (!navigates && isOrder && !inOverlay.has(id)) {
+            const redirects = opts.formRedirects?.has(String(n.specials?.formId ?? '')) ?? false;
+            if (!navigates && !redirects && isOrder && !inOverlay.has(id)) {
                 out.push({
                     code: 'order_goes_nowhere',
                     nodeId: id,
@@ -749,5 +927,8 @@ opts = {}) {
             });
         }
     }
+    // A FORM DOCUMENT's fields that store fine and can never be answered.
+    for (const f of formFieldFindings(d, opts.formDocType))
+        out.push({ ...f, fix: fill(f.code, { id: f.nodeId }) });
     return out;
 }

package/dist/domains/site/validate.js

@@ -1,5 +1,6 @@
 import { subtreeIds, childrenOf, SPEC_GLOBAL_ID, SPEC_OVERLAY_ID, } from '../../core/tree.js';
 import { checkBandOrder } from './traps.js';
+import { formClashes } from './formdoc.js';
 /**
  * Everything that would make the platform refuse this document on save.
  *
@@ -16,6 +17,8 @@ export function validateForSave(doc) {
     const band = checkBandOrder(d);
     if (band)
         problems.push(band);
+    // A FORM document's field-uniqueness rule (DeriveSchema → 409 on save). Empty for a page.
+    problems.push(...formClashes(d));
     // COMPOSITION STAMPS: only a DIRECT child of ROOT may carry one, and never the
     // same id twice.
     //

package/dist/domains/site/writecheck.js

@@ -0,0 +1,309 @@
+import { BASE_ONLY_CONFIG, BOUND_SPECIALS, CONFIG_VALUES, ELEMENT_VALUES, ELEMENTS, HOVER_HOMES, SATELLITE_RULES, TRAIT_WRITES, WRITE_PRECONDITIONS, } from '../../catalog/elements.generated.js';
+import { FIELD_SKIN_BY_NODE } from '../../catalog/fieldskin.generated.js';
+import { FORM_RULE_VOCAB } from '../../catalog/formrules.generated.js';
+import { fill } from './findings.js';
+import { collectsValue, formFieldFindings, formFields, nameFromLabel } from './formdoc.js';
+import { animationNote, deadKeyNote, preconditionNotes, unknownValueNote, unknownWriteNote, unsupportedSettingNote, } from './vocabulary.js';
+/**
+ * Keys any node may carry, read by shared helpers rather than one element:
+ * visibility and reveal (`display` trait), the entrance animation, the pinned
+ * state's trigger, the style preset, the parent-hover host, custom class/CSS,
+ * the projected link, and the two STORED references (the composed stamps are
+ * refused by their own guards, so they are not listed).
+ */
+const UNIVERSAL = {
+    config: ['hidden', 'revealOnHover', 'animation', 'stuckAfter'],
+    specials: ['stylePreset', 'hoverHostDepth', 'className', 'customCss', 'href', 'target', 'globalRef', 'appBlockRef', 'appBlockValues'],
+};
+/**
+ * Inspector rows that are a WIDGET rather than a trait, so `TRAIT_WRITES` does
+ * not describe what they write — the key sits in the widget's props
+ * (`editor/src/trait/widgets.ts`: `specialKey: 'icon'` on `button_icon`) or in
+ * the component it mounts (`text_global_style` → `StylePresetRow`, which
+ * stores the picked site text style as `config.textGlobalStyle`, the key
+ * `schema/src/theme.ts` names for every text-bearing element). Keyed by the
+ * GENERATED control name, so a key is known only where the element offers the row.
+ *
+ * ponytail: hand-read, and only the rows the platform's own seeds exercise
+ * (test/seed-sweep.test.ts). Upgrade: have codegen read every widget's
+ * `specialKey`/`configKey` into the catalog — blocked on a catalog regenerate.
+ */
+const WIDGET_WRITES = {
+    button_icon: ['specials', 'icon'],
+    breadcrumb_icon: ['specials', 'icon'],
+    divider_icon: ['specials', 'iconName'],
+    text_global_style: ['config', 'textGlobalStyle'],
+};
+const known = new Map();
+function keysOf(type) {
+    const el = ELEMENTS[type];
+    if (!el)
+        return null;
+    const hit = known.get(type);
+    if (hit)
+        return hit;
+    const out = { config: new Set(UNIVERSAL.config), specials: new Set(UNIVERSAL.specials) };
+    const add = (ns, keys) => {
+        if (ns !== 'config' && ns !== 'specials')
+            return;
+        for (const k of keys ?? [])
+            out[ns].add(k);
+    };
+    const d = el.defaults;
+    add('config', Object.keys(d.config ?? {}));
+    add('specials', Object.keys(d.specials ?? {}));
+    for (const layer of [d.responsive, d.states]) {
+        for (const slot of Object.values(layer ?? {})) {
+            for (const ns of ['config', 'specials'])
+                add(ns, Object.keys((slot?.[ns] ?? {})));
+        }
+    }
+    for (const c of el.controls)
+        for (const w of TRAIT_WRITES[c]?.writes ?? [])
+            add(w.target, [w.writeKey]);
+    for (const c of el.controls)
+        if (WIDGET_WRITES[c])
+            add(WIDGET_WRITES[c][0], [WIDGET_WRITES[c][1]]);
+    // A control the trait registry does not describe is often an inspector row
+    // named after the key it writes (`{ key: 'quickviewId', visible: false }` on
+    // list-dataset), so its NAME counts as a key in either namespace.
+    add('config', el.controls);
+    add('specials', el.controls);
+    for (const v of [...Object.values(ELEMENT_VALUES[type] ?? {}), ...Object.values(ELEMENT_VALUES['*'] ?? {})]) {
+        add(v.target, [v.writeKey]);
+    }
+    add('config', Object.keys(CONFIG_VALUES));
+    add('config', BASE_ONLY_CONFIG);
+    add('config', (SATELLITE_RULES[type] ?? []).map((r) => r.configKey));
+    add('config', FIELD_SKIN_BY_NODE[type]);
+    if (HOVER_HOMES[type]?.home === 'legacy')
+        add('config', ['stateHover']);
+    add('specials', BOUND_SPECIALS[type]);
+    // The binding fields the element is BORN with name specials keys too
+    // (`boundProductId` is one no html.go reads, and it is still correct).
+    for (const b of bindingFields(type))
+        add('specials', [b]);
+    for (const p of WRITE_PRECONDITIONS) {
+        if (p.types.includes(type))
+            add('specials', [p.key, ...p.requires.map((r) => r.key)]);
+    }
+    known.set(type, out);
+    return out;
+}
+/** Every `specials.<key>` this element's generated bindings write, key only. */
+export function bindingFields(type) {
+    const el = ELEMENTS[type];
+    const rows = [...(el?.defaults.bindings ?? []), ...Object.values(el?.bindingsFor ?? {}).flat()];
+    return [...new Set(rows.map((b) => b.field ?? '').filter((f) => f.startsWith('specials.')).map((f) => f.slice(9)))];
+}
+/**
+ * The `specials.<key>` fields `sb_bind` accepts on this element, and the list
+ * `sb_traits_for` reports as `bindable` — one function so the two cannot drift.
+ * What the renderer paints (`BOUND_SPECIALS`) plus the element's own generated
+ * binding fields (`boundProductId` is read by the runtime, not html.go). Empty
+ * when the catalog knows no bound special for the type: `sb_bind` then does not
+ * restrict the field.
+ */
+export function bindableFields(type) {
+    const painted = BOUND_SPECIALS[type] ?? [];
+    return painted.length ? [...new Set([...painted, ...bindingFields(type)])] : [];
+}
+/**
+ * Check one write. `specials` is the node's specials AS THEY WILL BE after the
+ * write, for the precondition question (a pair is legal or not together).
+ */
+export function writeCheck(type, namespace, keys, opts = {}) {
+    const out = [];
+    const push = (once, code, key, problem, fix) => out.push({ once, note: { code, ...(opts.id ? { id: opts.id } : {}), key: `${namespace}.${key}`, problem, fix } });
+    if (namespace !== 'config' && namespace !== 'specials')
+        return out;
+    const ks = keysOf(type);
+    for (const [k, v] of Object.entries(keys)) {
+        const dead = deadKeyNote(namespace, k);
+        if (dead) {
+            push(`dead-key:${namespace}.${k}`, 'dead_key', k, dead, 'Drop the key — no value for it does anything.');
+            continue;
+        }
+        if (ks && !ks[namespace].has(k)) {
+            const other = namespace === 'config' ? 'specials' : 'config';
+            push(`unknown-key:${type}.${namespace}.${k}`, 'unknown_key', k, `${namespace}.${k} is not a key ${type} is known to read — not in its seeded defaults, its ` +
+                'declared controls or any generated vocabulary. It is stored as written; if nothing reads ' +
+                'it, the write changes nothing on the page.', ks[other].has(k)
+                ? `${type} reads ${other}.${k} — write it in namespace "${other}".`
+                : `Check the spelling against sb_traits_for "${type}"; a CSS property belongs in namespace ` +
+                    '"style". Ignore this if the key is newer than this catalog.');
+            continue;
+        }
+        const vn = type ? unknownWriteNote(type, namespace, k, v) : null;
+        if (vn) {
+            push(`value:${type}.${namespace}.${k}=${JSON.stringify(v)}`, 'unknown_value', k, vn, 'Write one of the listed values.');
+        }
+        if (namespace === 'config') {
+            const cn = k === 'animation' ? animationNote(v) : unknownValueNote(k, v);
+            if (cn) {
+                push(`config-value:${k}=${JSON.stringify(v)}`, k === 'animation' ? 'animation' : 'unknown_value', k, cn, k === 'animation'
+                    ? 'Write an object: { active: true, type: "fade_in", … } — sb_traits_for lists the vocabulary.'
+                    : 'Write one of the listed values.');
+            }
+        }
+        if (namespace === 'specials') {
+            const un = unsupportedSettingNote(type, k, v);
+            if (un)
+                push(`unsupported:${type}.${k}=${JSON.stringify(v)}`, 'unsupported_setting', k, un, `Unset specials.${k}; ${type} never reads it.`);
+        }
+    }
+    if (namespace === 'specials' && type === 'form' && 'formRules' in keys && opts.doc) {
+        for (const r of formRuleChecks(opts.doc, keys.formRules)) {
+            push(`form-rule:${r.problem}`, 'form_rule', 'formRules', r.problem, r.fix);
+        }
+    }
+    if (namespace === 'specials') {
+        for (const n of preconditionNotes(type, opts.specials ?? keys)) {
+            const key = n.slice('specials.'.length, n.indexOf(' ='));
+            push(`precondition:${type}:${n.slice(0, 60)}`, 'precondition', key, n, 'Set the neighbouring keys named above, or unset this one.');
+        }
+    }
+    return out;
+}
+/**
+ * `specials.formRules` on a form root, judged against the open form document.
+ *
+ * EVERY READER DROPS A BAD RULE IN SILENCE — `readFormRules` (schema) and
+ * `ReadFormRules` (server/internal/forms/rules.go) skip an entry with no id or
+ * an unknown join/op/action, one at a time — so the save succeeds and the field
+ * it governs never changes. A rule is keyed by each field's POSTED NAME,
+ * `specials.name` trimmed, falling back to the node id only when there is none
+ * (the editor's `ruleNameOf`, DeriveSchema's rule) — so a named field's node id
+ * is NOT a key. Warnings only: the platform stores the document either way.
+ */
+export function formRuleChecks(doc, raw) {
+    const out = [];
+    const add = (problem, fix) => out.push({ problem, fix });
+    let list = raw;
+    if (typeof raw === 'string') {
+        if (!raw.trim())
+            return out;
+        try {
+            list = JSON.parse(raw);
+        }
+        catch {
+            add('specials.formRules is not valid JSON, so the platform reads NO rules at all.', 'Write JSON.stringify(rules) of an array of rules.');
+            return out;
+        }
+    }
+    if (!Array.isArray(list)) {
+        add('specials.formRules must be a JSON array of rules; anything else is read as no rules.', 'Wrap the rule in [ … ].');
+        return out;
+    }
+    // ponytail: names from every node, not only answering fields — a rule naming
+    // a title is missed rather than a real field being flagged.
+    const names = new Set(Object.values(doc.nodes)
+        .filter((n) => n.id !== doc.root_node_id)
+        .map((n) => (typeof n.specials?.name === 'string' && n.specials.name.trim()) || n.id));
+    const v = FORM_RULE_VOCAB;
+    const dropped = 'and every reader drops the whole rule';
+    list.forEach((r, i) => {
+        const at = `rule ${i + 1}${r && typeof r.id === 'string' && r.id ? ` (${r.id})` : ''}`;
+        if (!r || typeof r !== 'object')
+            return add(`${at} is not an object, ${dropped}.`, 'Remove it.');
+        if (typeof r.id !== 'string' || !r.id.trim())
+            add(`${at} has no id, ${dropped}.`, 'Give it a unique string id, e.g. "rule_1".');
+        if (!v.joins.includes(r.join))
+            add(`${at} has join ${JSON.stringify(r.join)}, ${dropped}.`, `Use one of: ${v.joins.join(', ')}.`);
+        const conds = Array.isArray(r.conditions) ? r.conditions : null;
+        const targets = Array.isArray(r.targets) ? r.targets : null;
+        if (!conds || !targets)
+            return add(`${at} needs conditions[] and targets[] arrays, ${dropped}.`, 'Add both arrays.');
+        if (conds.length === 0)
+            add(`${at} has no conditions, so it never fires.`, 'Add at least one { field, op, value }.');
+        const fieldNote = (f, role) => {
+            if (typeof f !== 'string' || !names.has(f)) {
+                add(`${at} ${role} ${JSON.stringify(f)}, which names no field in this form — a rule is keyed by a field's specials.name (its node id only when it has none).`, `Use one of: ${[...names].join(', ')}.`);
+            }
+        };
+        for (const c of conds) {
+            if (!v.ops.includes(c?.op))
+                add(`${at} has op ${JSON.stringify(c?.op)}, ${dropped}.`, `Use one of: ${v.ops.join(', ')}.`);
+            if (typeof c?.value !== 'string')
+                add(`${at} has a non-string condition value, ${dropped}.`, 'Write value as a string ("" for filled/empty).');
+            fieldNote(c?.field, 'conditions on');
+        }
+        const sources = new Set(conds.map((c) => c?.field));
+        for (const t of targets) {
+            if (!v.actions.includes(t?.action))
+                add(`${at} has action ${JSON.stringify(t?.action)}, ${dropped}.`, `Use one of: ${v.actions.join(', ')}.`);
+            fieldNote(t?.field, 'targets');
+            if (sources.has(t?.field)) {
+                add(`${at} targets ${JSON.stringify(t?.field)}, which it also conditions on — hiding a field blanks its answer, so the rule flips itself.`, 'Target a different field.');
+            }
+        }
+    });
+    return out;
+}
+/**
+ * A write into an open FORM document, judged on the document it LEAVES: a field
+ * it makes unanswerable (no options, a dead time slot, a third date on a
+ * booking form), and a field it ADDS with no `specials.name`.
+ *
+ * The unnamed one is a note, not a defect: the editor leaves a new field's name
+ * empty too (FieldNameRow.vue — "the node id is the honest resting value"), and
+ * the platform posts the answer under the node id. But that id is what the
+ * submissions table, the notification mail and every form rule then show, so
+ * an agent that can name the field should. Only what this write introduced is
+ * said; a page answers nothing.
+ */
+export function formDocChecks(before, after, formType) {
+    const out = [];
+    const had = new Set(formFieldFindings(before, formType).map((f) => `${f.code}:${f.nodeId}`));
+    for (const f of formFieldFindings(after, formType)) {
+        if (had.has(`${f.code}:${f.nodeId}`))
+            continue;
+        out.push({
+            once: `form-field:${f.code}:${f.nodeId}`,
+            note: { code: 'form_field', id: f.nodeId, key: `specials.${f.key}`, problem: f.problem, fix: fill(f.code, { id: f.nodeId }) },
+        });
+    }
+    for (const n of formFields(after)) {
+        if (before.nodes[n.id] || !collectsValue(n.data.type))
+            continue;
+        const name = n.specials?.name;
+        if (typeof name === 'string' && name.trim())
+            continue;
+        const label = typeof n.specials?.label === 'string' ? nameFromLabel(n.specials.label) : '';
+        const suggest = label && label !== 'label' ? label : 'a_short_key';
+        out.push({
+            once: `form-field:unnamed:${n.id}`,
+            note: {
+                code: 'form_field',
+                id: n.id,
+                key: 'specials.name',
+                problem: `${n.data.type} ${n.id} has no specials.name, so its answer posts under the node id "${n.id}" — ` +
+                    'which is what the submissions table, the notification mail and every form rule then show.',
+                fix: `sb_set id "${n.id}", namespace specials, keys { "name": "${suggest}" } — unique within the form.`,
+            },
+        });
+    }
+    return out;
+}
+/** The same, for every node of a nested `sb_add` spec, as each will be born. */
+export function specCheck(spec) {
+    const out = [];
+    const walk = (s) => {
+        const born = ELEMENTS[s.type]?.defaults.specials ?? {};
+        if (s.config)
+            out.push(...writeCheck(s.type, 'config', s.config));
+        if (s.specials)
+            out.push(...writeCheck(s.type, 'specials', s.specials, { specials: { ...born, ...s.specials } }));
+        for (const c of s.children ?? [])
+            walk(c);
+    };
+    walk(spec);
+    return out;
+}
+/** The notes `say` has not said yet, deduped within the call too. */
+export function sayChecks(checked, say) {
+    const seen = new Set();
+    return checked
+        .filter((c) => !seen.has(c.once) && (seen.add(c.once), say(c.once, c.note.problem) !== undefined))
+        .map((c) => c.note);
+}

package/dist/mcp/notices.js

@@ -15,6 +15,14 @@ export class Notices {
         this.said.add(key);
         return body;
     }
+    /**
+     * What `once` WOULD return, without spending it. A dry run uses this: it
+     * must show the same warnings as the real call, and the real call must
+     * still have them to show.
+     */
+    peek(key, body) {
+        return this.said.has(key) ? undefined : body;
+    }
     reset() {
         this.said.clear();
     }

package/dist/server.js

@@ -22,13 +22,13 @@ import { registerThemeTools } from './tools/theme.js';
  */
 const INSTRUCTIONS = `Store Builder. Call sb_connect first.
 
-API: sb_api_find query → one line per operation (${SWAGGER_SOURCE.operations} reachable); sb_api_find id → its call sheet; sb_api_call runs it. /api/v1 paths take the API key, every other path the session; the platform refuses each on the other's surface. If the sheet says the body is undescribed, read the matching GET and send back a modified copy.
+API: sb_api_find query → one line per operation (${SWAGGER_SOURCE.operations} reachable); sb_api_find id → its call sheet; sb_api_call runs it. /api/v1 paths take the API key, every other path the session; each is refused on the other's surface. Undescribed body: send back a modified copy of the matching GET.
 
-Design: sb_page_open → sb_catalog_search (${ELEMENT_SOURCE.count} elements) → sb_traits_for the one you chose → sb_add with a NESTED spec (one call per section) → sb_set → sb_look → sb_review.
+Design, native first: sb_page_open → sb_catalog_search (${ELEMENT_SOURCE.count} elements) → sb_traits_for → sb_add one NESTED native spec per section → sb_bind/sb_event → sb_look + sb_review. custom-code only for a gap you can name that no element covers.
 - Writes and API calls default to dry_run:true; pass dry_run:false to act.
-- sb_set writes per breakpoint by default; base is the cascade's fallback layer, fine for values that should not vary.
-- Outline flags: global = shared master, an edit lands on every page; overlay = not this page; app = an app block, not editable inside.
-- sb_live_join shows edits live in an open editor (needs SB_EMAIL/SB_PASSWORD). sb_bind puts real store data in the page.`;
+- sb_set writes per breakpoint by default; base is the cascade's fallback layer, for values that should not vary.
+- Outline flags: global = shared master, an edit lands on every page; overlay = not this page; app = app block, not editable inside.
+- sb_live_join shows edits live in an open editor (needs SB_EMAIL/SB_PASSWORD).`;
 /**
  * The published version, read from package.json at runtime so serverInfo never
  * drifts from what npm shipped. package.json sits one level above both dist/ and
@@ -73,6 +73,6 @@ export function createServer(ctx = buildContext()) {
     registerStoreTools(server, ctx, pageSession);
     registerThemeTools(server, ctx);
     registerImportTools(server, ctx, pageSession);
-    registerUndoTools(server, ctx);
+    registerUndoTools(server, ctx, pageSession);
     return server;
 }

package/dist/tools/importpage.js

@@ -519,7 +519,7 @@ export function registerImportTools(server, ctx, session) {
         // per page would give the first page element defaults and every later page
         // the defaults of the blank page before it — rule 0 failing on every page
         // at once. The open page if there is one, the site's home page otherwise.
-        let tokenDoc = session.peek();
+        let tokenDoc = session.page() ? session.peek() : null;
         if (!tokenDoc && home && typeof home.id === 'string') {
             try {
                 tokenDoc = PageDoc.from((await loadSource(ctx, siteId, home.id)).document);