sbuilder-mcp 0.76.3 → 0.77.0

package/dist/domains/site/review.js

@@ -4,7 +4,8 @@ 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 { 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 +35,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 +128,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 +390,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,

package/dist/domains/site/writecheck.js

@@ -0,0 +1,262 @@
+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 { 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;
+}
+/** 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);

package/dist/tools/live.js

@@ -2,6 +2,7 @@ import { randomBytes } from 'node:crypto';
 import { z } from 'zod';
 import { text, images } from '../mcp/response.js';
 import { BINDING_SOURCES, ELEMENTS } from '../catalog/elements.generated.js';
+import { bindableFields } from '../domains/site/writecheck.js';
 import { previewUrl } from '../vision/preview.js';
 import { uploadMedia } from '../transport/media.js';
 import { request } from '../transport/http.js';
@@ -26,7 +27,7 @@ import { RealtimeSocket } from '../transport/socket.js';
 import { LiveSession } from '../live/session.js';
 import { refuseAppBlockInterior } from '../domains/site/builder.js';
 import { soft } from '../domains/site/guard.js';
-import { hrefPatches, hasPurchaseBinding, PRODUCT_ACTION_BINDING_ID, } from '../domains/site/navhref.js';
+import { hrefPatches, hasPurchaseBinding, liveEventTable, PAYLOAD_NEEDS, PRODUCT_ACTION_BINDING_ID, } from '../domains/site/navhref.js';
 import { offscreenNodes, offscreenRootOf } from '../domains/site/offscreen.js';
 import { siteToken } from './credentialpick.js';
 import { searchStock, SearchUnavailable, NO_SEARCH_NEXT } from '../transport/stock.js';
@@ -70,6 +71,24 @@ export function bindNode(doc, id, source, field, action, guard) {
         throw new Error(`sbuilder: a binding field must be "specials.<key>", not "${field}". The renderer ignores ` +
             'every other namespace, so the binding would be stored and never applied.');
     }
+    // A FIELD THE ELEMENT NEVER PAINTS. `BOUND_SPECIALS` is read off each
+    // element's html.go, so a `specials.boundImage` binding on a text-dataset is
+    // stored, saved, published and rendered as placeholder text forever. Soft:
+    // the list is the catalog's copy of the renderer. The element's own generated
+    // binding fields count too — `boundProductId` is read by the runtime, not
+    // html.go, and every default product binding carries it.
+    const type = node.data?.type ?? '';
+    const key = field.slice(dot + 1);
+    const allowed = bindableFields(type);
+    if (action === undefined && allowed.length) {
+        if (!allowed.includes(key)) {
+            soft(guard, () => {
+                throw new Error(`sbuilder: a ${type} renders a binding only into ${allowed.map((k) => `specials.${k}`).join(', ')} ` +
+                    `— "${field}" would be stored and never painted. Allowed fields: ${allowed.join(', ')}. ` +
+                    'Bind one of those, or swap to an element that shows this value (sb_catalog_search).');
+            });
+        }
+    }
     // A PURCHASE BINDING, which is what makes a button add to the cart.
     //
     // It is not an ordinary binding and cannot be written as one: the renderer
@@ -109,23 +128,6 @@ export function bindNode(doc, id, source, field, action, guard) {
         },
     ];
 }
-/**
- * The click-action allow-list that is LIVE for this node.
- *
- * `activeEvents` in the platform, whose whole rule is one line in
- * `ActionTrait.vue`: `return action ? def.binding_events : def.events`. A
- * purchase control is a different kind of control — an unbound button navigates,
- * a bound one hands off to the cart or the checkout — and the two sets are
- * mutually exclusive, because "add this product, then go to an arbitrary URL" is
- * not a thing the cart runtime can express.
- */
-function liveEventTable(type, node) {
-    const meta = ELEMENTS[type];
-    if (!meta?.events)
-        return undefined;
-    const bound = (node.bindings ?? []).some((b) => b?.id === PRODUCT_ACTION_BINDING_ID);
-    return (bound && meta.bindingEvents) || meta.events;
-}
 /**
  * Put a click action on a node, or take one off.
  *
@@ -172,7 +174,7 @@ export function setEvent(doc, id, trigger, action, payload, guard) {
             ...project(next),
         ];
     }
-    const table = liveEventTable(node.data.type, node);
+    const table = liveEventTable(doc.doc.nodes, id);
     if (!table) {
         throw new Error(`sbuilder: a ${node.data.type} declares no click actions, so an event on it would be ` +
             'stored and never fired. Elements that do: ' +
@@ -192,6 +194,21 @@ export function setEvent(doc, id, trigger, action, payload, guard) {
                 : '') +
             `Allowed: ${allowed.join(', ')}.`);
     }
+    // A NAVIGATION WITH NOWHERE TO GO. The renderer turns a sole go_to_url /
+    // open_page click into `<a href>` from `payload.url` ALONE (navhref.ts) — an
+    // `open_page` with only a page id projects nothing, since neither renderer
+    // can resolve one — and a `popup` with no `payload.id` publishes a call with
+    // no target that opens nothing. All three store, save and publish clean.
+    const need = PAYLOAD_NEEDS[action];
+    if (need) {
+        const v = (payload ?? {})[need.key];
+        if (typeof v !== 'string' || v === '') {
+            soft(guard, () => {
+                throw new Error(`sbuilder: "${action}" needs payload.${need.key} — without it the click ${need.why}. ` +
+                    `Expected payload: ${need.shape}.`);
+            });
+        }
+    }
     const value = { id: `ev_${action}`, name: trigger, action, payload: payload ?? {} };
     if (at >= 0) {
         const next = events.map((e, i) => (i === at ? value : e));
@@ -258,7 +275,7 @@ export function joinRoom(ctx, session, siteId) {
     const socket = new RealtimeSocket(`${wsBase}/api/realtime/ws?site=${encodeURIComponent(siteId)}`, tokenFn);
     const live = new LiveSession(socket, {
         onRemote: (patches) => session.applyRemote(patches),
-        onDesync: (reason) => session.markStale(reason),
+        onDesync: (reason) => session.roomDesync(reason),
         onSource: (pageId, rev, peerId) => session.sourceSaved(pageId, rev, peerId),
         onMaster: (kind, id, op, rev) => session.masterSaved(kind, id, op, rev),
     });
@@ -366,7 +383,7 @@ export function registerLiveTools(server, ctx, session) {
         // and judging its geometry produced thirteen false off-canvas findings
         // per page on a site whose pages were correct.
         const skip = offscreenNodes(doc);
-        const visual = node_id ? [] : measure(shots, skip);
+        const visual = node_id ? [] : measure(shots, skip, doc);
         const layout = compactFindings(visual);
         const layoutNotice = visual.length > 0 ? ctx.notices.once('measure', MEASURE_NOTICE) : undefined;
         // The legend rides with the first look only; the shape does not change after.
@@ -661,8 +678,10 @@ export function registerLiveTools(server, ctx, session) {
         const guard = { force, forced: [] };
         const patches = setEvent(d, id, trigger ?? 'click', action, payload, guard);
         const forced = guard.forced.length ? { forced: guard.forced } : {};
-        if (dry_run !== false)
-            return text({ dry_run: true, patches, ...forced });
+        if (dry_run !== false) {
+            const refuse = session.wouldRefuse(patches);
+            return text({ dry_run: true, patches, ...(refuse ? { would_refuse: refuse } : {}), ...forced });
+        }
         await session.applyAndSave(patches);
         return text({ node: id, trigger: trigger ?? 'click', action, rev: d.rev, ...forced });
     });
@@ -692,8 +711,10 @@ export function registerLiveTools(server, ctx, session) {
         const guard = { force, forced: [] };
         const patches = bindNode(d, id, source, field, action, guard);
         const forced = guard.forced.length ? { forced: guard.forced } : {};
-        if (dry_run !== false)
-            return text({ dry_run: true, patches, ...forced });
+        if (dry_run !== false) {
+            const refuse = session.wouldRefuse(patches);
+            return text({ dry_run: true, patches, ...(refuse ? { would_refuse: refuse } : {}), ...forced });
+        }
         await session.applyAndSave(patches);
         return text({ bound: id, source, field, ...(action ? { action } : {}), rev: d.rev, ...forced });
     });