sbuilder-mcp 0.2.0 → 0.2.2

package/dist/core/tree.js

@@ -1,3 +1,4 @@
+import { SATELLITE_RULES } from '../catalog/elements.generated.js';
 /** The specials stamp a composed site overlay carries. */
 export const SPEC_OVERLAY_ID = 'overlayId';
 /** The specials stamps a composed global section carries. */
@@ -37,7 +38,26 @@ export function isOverlay(doc, id) {
 export function pageChildren(doc) {
     return childrenOf(doc, doc.root_node_id).filter((id) => !isOverlay(doc, id));
 }
-/** Depth-first walk. Cycle-safe: a malformed document must not hang a save. */
+/**
+ * Depth-first walk, children AND satellites. Cycle-safe: a malformed document
+ * must not hang a save.
+ *
+ * A satellite is a real node referenced from `config[configKey]` rather than
+ * from `data.nodes`, so a walk that follows child lists alone cannot see it. The
+ * platform states the requirement in as many words
+ * (`server/render/generated/schema_gen.go:245`): "Anything that asks 'what is
+ * inside this node?' (subtree collection, copy, delete) must consult this table
+ * as well, exactly as the editor's `subtreeIds` does."
+ *
+ * Satellite-aware is the DEFAULT, and the name stays short, for the same reason
+ * `pageChildren` has the short name and `childrenOf` the explicit one: a caller
+ * who writes the obvious thing must not be silently wrong. Copying an accordion
+ * with the child-only walk gave the copy a pointer to the ORIGINAL's skin.
+ *
+ * A `configKey` naming a node that is not in the document is skipped rather than
+ * reported here — a walk is not a validator, and a trimmed subtree is a real
+ * shape the editor handles the same way (`stores/node.ts:408-411`).
+ */
 export function walk(doc, id, visit) {
     const seen = new Set();
     const go = (cur) => {
@@ -50,6 +70,11 @@ export function walk(doc, id, visit) {
         visit(n);
         for (const k of n.data.nodes)
             go(k);
+        for (const rule of SATELLITE_RULES[n.data.type] ?? []) {
+            const sat = n.config?.[rule.configKey];
+            if (typeof sat === 'string' && sat && doc.nodes[sat])
+                go(sat);
+        }
     };
     go(id);
 }

package/dist/domains/site/builder.js

@@ -1,6 +1,7 @@
-import { isOverlay, subtreeIds, ancestors, appBlockRoot } from '../../core/tree.js';
-import { ELEMENTS } from '../../catalog/elements.generated.js';
-import { createNode } from './node.js';
+import { isOverlay, subtreeIds, ancestors, appBlockRoot, SPEC_GLOBAL_ID, SPEC_GLOBAL_KIND, SPEC_GLOBAL_REF, } from '../../core/tree.js';
+import { ELEMENTS, ELEMENT_SEEDS, SATELLITE_RULES } from '../../catalog/elements.generated.js';
+import { createNode, mintSatellites } from './node.js';
+import { refuseSecondTemplate } from './traps.js';
 import { genId } from './ids.js';
 /** Append sentinel: splice clamps a too-large index, and `isSyncablePatch`
  *  deliberately allows one — an append is a legitimate thing to describe. */
@@ -78,6 +79,7 @@ export function addSubtree(doc, parentId, spec, index) {
     refuseAppBlockParent(doc, parentId, 'adding');
     requireContainer(parent.data.type, parentId);
     requireAllowed(parent.data.type, spec.type);
+    refuseSecondTemplate(doc.doc, parentId, 'Adding');
     const patches = [];
     const ids = [];
     const build = (s, parentNodeId) => {
@@ -89,9 +91,22 @@ export function addSubtree(doc, parentId, spec, index) {
             config: s.config,
             specials: s.specials,
         });
+        // Before the owner is handed to a patch: minting rewrites its `config`.
+        const sats = mintSatellites(n);
         patches.push({ op: 'set', path: ['nodes', n.id], value: n });
         ids.push(n.id);
-        for (const child of s.children ?? []) {
+        for (const sat of sats) {
+            patches.push({ op: 'set', path: ['nodes', sat.id], value: sat });
+            ids.push(sat.id);
+        }
+        // SEEDED CONTENT, when the caller brought none of its own.
+        //
+        // `ELEMENT_SEEDS` is the content an element "is not USABLE without": a
+        // dropdown with no trigger and no panel is a bare relative box, and a select
+        // renders INTO those two nodes and draws an empty box without them. A caller
+        // who passed children has expressed an intent and is never overridden.
+        const children = s.children?.length ? s.children : (ELEMENT_SEEDS[s.type] ?? []);
+        for (const child of children) {
             requireContainer(s.type, n.id);
             requireAllowed(s.type, child.type);
             const childId = build(child, n.id);
@@ -114,6 +129,14 @@ export function addSubtree(doc, parentId, spec, index) {
  * whole subtree, and every page carrying it goes blank. That is not a
  * hypothetical — it took four pages down before this check existed.
  */
+/**
+ * The composition stamps a DUPLICATE must not inherit.
+ *
+ * `globalRev` is the fence the editor writes against a shared master
+ * (`features/globalsections/api.ts:65`); a local copy has no master and so no
+ * revision to be stale against.
+ */
+const COPY_STRIPPED_SPECIALS = [SPEC_GLOBAL_ID, SPEC_GLOBAL_REF, SPEC_GLOBAL_KIND, 'globalRev'];
 const COMPOSED_STAMPS = {
     globalId: 'globalRef',
     appBlockId: 'appBlockRef',
@@ -272,6 +295,11 @@ export function duplicateNode(doc, id) {
     if (!parentId || !doc.has(parentId)) {
         throw new Error(`sbuilder: ${id} has no parent to be duplicated beside`);
     }
+    // A copy lands BESIDE the original, so duplicating a repeater's template makes
+    // the second child the renderer will never draw. sb_add and sb_move already
+    // refuse that; duplicate is the likeliest way to reach for it, since
+    // "duplicate the card" is the move a designer makes constantly.
+    refuseSecondTemplate(doc.doc, parentId, 'Duplicating into');
     const patches = [];
     const ids = [];
     // One pass, parent-first, so a child's `parent` always names an id already
@@ -281,12 +309,44 @@ export function duplicateNode(doc, id) {
         const clone = JSON.parse(JSON.stringify(src));
         clone.id = genId(src.data.type);
         clone.data = { ...clone.data, parent: newParent, nodes: [] };
+        // A COPY IS NOT THE SHARED MASTER.
+        //
+        // The stamps came over verbatim, so duplicating a global header produced two
+        // ROOT children carrying one globalId — ErrDuplicateGlobal
+        // (server/internal/page/decompose.go:293), refused on a LATER save, by which
+        // time the agent has kept editing and reads it as a transport error. Strip
+        // rather than refuse: unlike an overlay or an app block, whose copies the
+        // SERVER would destroy, a stripped global copy is a perfectly valid
+        // document, and it is what a designer means by duplicating a header to make
+        // a variant.
+        for (const stamp of COPY_STRIPPED_SPECIALS)
+            delete clone.specials?.[stamp];
         patches.push({ op: 'set', path: ['nodes', clone.id], value: clone });
         ids.push(clone.id);
         for (const kid of src.data.nodes) {
             const kidId = copy(kid, clone.id);
             patches.push({ op: 'insert', path: ['nodes', clone.id, 'data', 'nodes'], index: APPEND, value: kidId });
         }
+        // SATELLITES, deep-copied with the owner's pointer rewritten — the editor's
+        // copyNode does exactly this (`editor/src/stores/node.ts:373,403`). Without
+        // it the copy pointed at the ORIGINAL's skin: editing one changed both, and
+        // removing the original deleted the skin out from under the copy.
+        //
+        // Written as an explicit patch rather than by mutating `clone` after it has
+        // been handed to one, so the emitted patch list says what it does.
+        for (const rule of SATELLITE_RULES[src.data.type] ?? []) {
+            const satId = src.config?.[rule.configKey];
+            const path = ['nodes', clone.id, 'config', rule.configKey];
+            if (typeof satId === 'string' && satId && doc.has(satId)) {
+                patches.push({ op: 'set', path, value: copy(satId, clone.id) });
+            }
+            else if (satId !== undefined) {
+                // A satellite id that resolves to nothing is a trimmed subtree, which the
+                // editor handles the same way (`stores/node.ts:408-411`). Carrying the
+                // pointer would aim the copy at a node it does not own.
+                patches.push({ op: 'unset', path });
+            }
+        }
         return clone.id;
     };
     const rootId = copy(id, parentId);
@@ -317,6 +377,10 @@ export function moveNode(doc, id, newParentId, index) {
     }
     requireContainer(newParent.data.type, newParentId);
     requireAllowed(newParent.data.type, n.data.type);
+    // Not for a REORDER: a node already in this parent is not a second template,
+    // and refusing it would block the one move that is always safe.
+    if (n.data.parent !== newParentId)
+        refuseSecondTemplate(doc.doc, newParentId, 'Moving');
     const patches = [];
     const oldParentId = n.data.parent;
     if (oldParentId && doc.has(oldParentId)) {

package/dist/domains/site/findings.js

@@ -25,6 +25,13 @@ export const FIX = {
         'sb_remove id "<id>". Setting "<key>" on this one would show the same value in every row.',
     unbound_dataset_element: 'Bind it: sb_bind id "<id>", field "specials.<key>", and the source that names the record ' +
         'field you want (sb_bind refuses an unknown source and lists every valid one).',
+    unlinked_form: 'Point it at a real form: sb_set id "<id>", namespace specials, keys ' +
+        '{ "formId": "<a form id from sb_api_find \'list forms\'>" }.',
+    dead_menu_link: 'Write the entries the renderer actually reads: sb_set id "<id>", namespace specials, keys ' +
+        '{ "menuItems": [{ "id": "mi-1", "label": "Shop", "href": "/shop" }] }. Setting menuId alone ' +
+        'publishes an empty nav — the Go renderer never reads it.',
+    extra_repeater_child: 'Keep one template: sb_remove the extra children of "<id>", or sb_move them out. Design the ' +
+        'single remaining child — it is what every record is drawn with.',
     dead_binding_source: `Rebind with sb_bind using one of: ${BINDING_SOURCES.join(', ')}.`,
     // "<key>" here is documentation, not a placeholder: this template is never
     // filled with a key, so the reader sees the form a field must take.
@@ -58,3 +65,54 @@ export function compactFindings(items) {
     });
     return { findings, fixes };
 }
+/**
+ * What a COMPOSE WARNING means for the document now in hand.
+ *
+ * These ride on `GET .../source` beside the page. The client typed the field and
+ * read it nowhere, which mattered most for the one that is destructive:
+ * `globalMissing` means the server could not find the master and DELETED the
+ * reference node from the tree it handed back (`compose.go:118,127`), so the
+ * page opens with the section already gone and the next save stores that loss
+ * permanently — with no error at any step.
+ */
+export const COMPOSE_WARNINGS = {
+    globalMissing: 'The shared section is GONE from the tree you just opened — the server could not find its ' +
+        'master and removed the reference. Saving from here makes that permanent. Re-add the section, ' +
+        'or restore the master, before you save.',
+    globalStale: 'A shared section was edited elsewhere while this copy was held; the master write was refused.',
+    overlayStale: 'The overlay master was edited elsewhere while this copy was held; that write was refused. ' +
+        'The page edits in the same request were kept.',
+    appBlockMissing: 'An app block on this page no longer resolves; its subtree composed as nothing.',
+    appBlockEdited: 'An edit inside an app block was reduced back to its reference on save, and is stored nowhere.',
+    formMissing: 'A form placement names a form that no longer exists, so it publishes as an EMPTY BOX rather ' +
+        'than an error.',
+};
+/**
+ * Turn the server's warnings into something a reader can act on.
+ *
+ * The two id fields are separate on the wire on purpose — they name rows in
+ * different tables, and one field holding "an id of whichever kind the code
+ * implies" is the shape that makes a client resolve it against the wrong store.
+ * An unknown code is passed through rather than dropped: a warning this build
+ * has never heard of is still the platform telling the caller something.
+ */
+export function composeWarnings(raw) {
+    if (!raw?.length)
+        return [];
+    const out = [];
+    for (const w of raw) {
+        if (!w || typeof w !== 'object')
+            continue;
+        const { code, globalId, overlayId, name } = w;
+        if (typeof code !== 'string' || !code)
+            continue;
+        const id = typeof overlayId === 'string' && overlayId ? overlayId : globalId;
+        out.push({
+            code,
+            ...(typeof id === 'string' && id ? { id } : {}),
+            ...(typeof name === 'string' && name ? { name } : {}),
+            effect: COMPOSE_WARNINGS[code] ?? 'The platform reported this about the page it composed.',
+        });
+    }
+    return out;
+}

package/dist/domains/site/node.js

@@ -1,4 +1,4 @@
-import { ELEMENTS } from '../../catalog/elements.generated.js';
+import { ELEMENTS, SATELLITE_RULES } from '../../catalog/elements.generated.js';
 import { genId } from './ids.js';
 /** Structured clone via JSON — the defaults are plain data, and this is what
  *  stops two nodes of the same type sharing one nested object. */
@@ -57,3 +57,92 @@ export function createNode(type, opts = {}) {
         bindings: copy(d.bindings ?? []),
     };
 }
+/**
+ * Mint the SATELLITES a freshly created node owns, and point it at them.
+ *
+ * A satellite is a real node in the document's node map referenced from
+ * `config[configKey]` instead of `data.nodes` — a style-holder like the tab's
+ * shared button skin. The editor's node store mints them the moment an element
+ * is added (`editor/src/element/seeds.ts:5-7`, `stores/node.ts` addDetachedNode)
+ * and this server did not, so an accordion it created carried no
+ * `accordionItemId` at all. A missing satellite "simply resolves to nothing at
+ * assemble time and the renderer takes its degrade path"
+ * (`server/render/scope/capture.go:98-105`) — for a repeater that means ghost
+ * cards shown to a shopper, which the platform's own meta calls a lie.
+ *
+ * MUTATES `owner.config`, so call it before the owner is handed to a patch, and
+ * only on a node this process just created.
+ *
+ * An `optional` rule is skipped deliberately: `list-loading` is the one opt-in
+ * satellite in the platform, because a list with no loading design shows a
+ * silhouette of its own cards, which is the better answer for almost every site.
+ * A `configKey` the caller already filled is left alone — an explicit id beats a
+ * minted one.
+ */
+export function mintSatellites(owner, seen = new Set()) {
+    // A type is expanded once per call chain. No element owns itself today, and a
+    // future one that did would otherwise mint until the stack ran out.
+    if (seen.has(owner.data.type))
+        return [];
+    seen.add(owner.data.type);
+    const out = [];
+    for (const rule of SATELLITE_RULES[owner.data.type] ?? []) {
+        if (rule.optional)
+            continue;
+        const existing = owner.config[rule.configKey];
+        if (typeof existing === 'string' && existing)
+            continue;
+        // A satellite is usually one bare skin node, but the three list-empty
+        // owners are born as a SUBTREE — the editor calls addDetachedTree for them,
+        // and a bare list-empty is blank space where it shows a glyph, a headline
+        // and a line of body.
+        const seed = seedFor(rule, owner);
+        const born = seed
+            ? buildFromSeed(seed, owner.id, seen)
+            : [createNode(rule.type, { parent: owner.id })];
+        owner.config[rule.configKey] = born[0].id;
+        out.push(...born, ...(seed ? [] : mintSatellites(born[0], seen)));
+    }
+    return out;
+}
+/**
+ * Which seed subtree this satellite is born as, if any.
+ *
+ * A repeater's empty state says "No products yet" or "No posts yet" depending on
+ * what it lists, so the table is keyed by the owner's `config.datasetSource`.
+ * An unknown source falls back to `product`, exactly as the editor's `copyFor`
+ * does — a list whose source this build does not know still gets a designed
+ * empty state rather than a blank one.
+ */
+function seedFor(rule, owner) {
+    if (rule.seed)
+        return rule.seed;
+    if (!rule.seedBySource)
+        return undefined;
+    const src = owner.config.datasetSource;
+    const key = typeof src === 'string' ? src : 'product';
+    return rule.seedBySource[key] ?? rule.seedBySource.product;
+}
+/**
+ * Mint a whole seeded subtree, ROOT FIRST.
+ *
+ * Root-first matters to every caller: the owner points `config[configKey]` at
+ * `[0]`, and `addSubtree` links a child by the same index. Each node is created
+ * through `createNode`, so it still gets its element's own defaults and
+ * bindings; the seed carries only what the seed decided.
+ */
+export function buildFromSeed(seed, parent, seen) {
+    const n = createNode(seed.type, {
+        parent,
+        style: seed.style,
+        config: seed.config,
+        specials: seed.specials,
+    });
+    const out = [n, ...mintSatellites(n, seen ? new Set(seen) : undefined)];
+    for (const child of seed.children ?? []) {
+        const kids = buildFromSeed(child, n.id, seen);
+        n.data.nodes.push(kids[0].id);
+        out.push(...kids);
+    }
+    return out;
+}

package/dist/domains/site/review.js

@@ -1,5 +1,5 @@
 import { childrenOf, isOverlay, pageChildren, appBlockRoot } from '../../core/tree.js';
-import { ELEMENTS, BINDING_SOURCES, BOUND_SPECIALS } from '../../catalog/elements.generated.js';
+import { ELEMENTS, BINDING_SOURCES, BOUND_SPECIALS, FIRST_CHILD_ONLY } from '../../catalog/elements.generated.js';
 import { fill } from './findings.js';
 /**
  * Shipped with every non-empty finding list.
@@ -175,6 +175,72 @@ export function reviewDesign(doc) {
                 });
             }
         }
+        // A FORM NOBODY LINKED publishes as an empty box, and the platform stays
+        // deliberately quiet about it: form.go:221 skips an empty formId with the
+        // comment that reporting it "would cry wolf on every page mid-edit". True
+        // for a human mid-drag, wrong for an agent that has finished — and since the
+        // element seeds `formId: ""` and forms compose on the RENDER path only, the
+        // canvas looks identical either way. An unlinked form is the DEFAULT.
+        if (type === 'form') {
+            const formId = (n.specials ?? {}).formId;
+            if (typeof formId !== 'string' || formId.trim() === '') {
+                out.push({
+                    code: 'unlinked_form',
+                    nodeId: id,
+                    type,
+                    problem: 'This form names no form, so it composes nothing and publishes as an empty box — ' +
+                        'and the platform reports no warning for it.',
+                    key: 'formId',
+                    fix: fill('unlinked_form', { id, key: 'formId' }),
+                });
+            }
+        }
+        // A MENU ENTRY WITH NO HREF is a link that goes nowhere. The Go renderer
+        // reads specials.menuItems and never menuId, so picking a menu by id
+        // publishes an empty nav, and the element's own seed ships one entry
+        // ("Home") whose href is "". Resolution from a menu id to real addresses is
+        // client-side (editor/src/features/menus/snapshot.ts), so nothing fills it
+        // in on the way to publish.
+        if (type === 'menu') {
+            const items = (n.specials ?? {}).menuItems;
+            const rows = Array.isArray(items) ? items : [];
+            const dead = rows.filter((r) => {
+                const row = (r ?? {});
+                const href = row.href;
+                const panel = row.panelId;
+                return ((typeof href !== 'string' || href.trim() === '') &&
+                    (typeof panel !== 'string' || panel.trim() === ''));
+            });
+            if (rows.length === 0 || dead.length > 0) {
+                out.push({
+                    code: 'dead_menu_link',
+                    nodeId: id,
+                    type,
+                    problem: rows.length === 0
+                        ? 'This menu has no entries, so it publishes as an empty nav. The renderer reads ' +
+                            'specials.menuItems and never menuId.'
+                        : `${dead.length} of ${rows.length} entries have no href, so those links go ` +
+                            'nowhere. The renderer reads specials.menuItems and never menuId.',
+                    key: 'menuItems',
+                    fix: fill('dead_menu_link', { id, key: 'menuItems' }),
+                });
+            }
+        }
+        // A REPEATER RENDERS ITS FIRST CHILD AND DROPS THE REST. `templateID`
+        // returns Data.Nodes[0], and list-dataset is the only renderer that does —
+        // which is why the list is generated rather than derived from the obvious
+        // "is a dataset container" predicate, since dataset-block renders all of
+        // its children.
+        if (FIRST_CHILD_ONLY.includes(type) && n.data.nodes.length > 1) {
+            out.push({
+                code: 'extra_repeater_child',
+                nodeId: id,
+                type,
+                problem: `"${type}" clones only its FIRST child per record, so the other ` +
+                    `${n.data.nodes.length - 1} never appear on the published page.`,
+                fix: fill('extra_repeater_child', { id }),
+            });
+        }
         // A dataset element with NO binding at all is the same silence from the other
         // direction: its renderer is waiting for a bound special that nothing writes,
         // so it falls back to whatever the document authored — once, for every record.

package/dist/domains/site/traps.js

@@ -1,3 +1,4 @@
+import { FIRST_CHILD_ONLY } from '../../catalog/elements.generated.js';
 import { pageChildren, isOverlay, SPEC_GLOBAL_ID, SPEC_GLOBAL_KIND, } from '../../core/tree.js';
 /**
  * Which band a direct child of ROOT belongs to.
@@ -95,4 +96,27 @@ export const RESPONSIVE_NOTICE = 'Written per breakpoint, which is the default b
     'legitimate too — it is the cascade\'s fallback layer, below every breakpoint slot, and ' +
     'where an element\'s own defaults live. Use base for a value that genuinely should not ' +
     'vary; use a breakpoint for anything a narrower screen should change.';
+/**
+ * Refuse a child a repeater would never render.
+ *
+ * `list-dataset` clones `Data.Nodes[0]` per record and ignores every sibling
+ * after it (`server/render/nodes/list-dataset/html.go:60`). A second child is a
+ * perfectly valid document: it stores, it publishes, and it simply never appears
+ * — so the agent designs a card nobody will ever see and nothing says why.
+ *
+ * The list is GENERATED from the renderers. `dataset-block` is a dataset
+ * container too and renders all of its children, so the obvious
+ * `isContainer && category === 'dataset'` predicate would have restricted the
+ * wrong element.
+ */
+export function refuseSecondTemplate(doc, parentId, verb) {
+    const parent = doc.nodes[parentId];
+    if (!parent || !FIRST_CHILD_ONLY.includes(parent.data.type))
+        return;
+    if (parent.data.nodes.length === 0)
+        return;
+    throw new Error(`sbuilder: "${parent.data.type}" (${parentId}) renders only its FIRST child, once per ` +
+        `record — Data.Nodes[0] is the template. ${verb} a second one stores fine and never ` +
+        'appears on the published page. Design the existing template, or sb_remove it first.');
+}
 export { isOverlay };

package/dist/domains/site/validate.js

@@ -1,4 +1,4 @@
-import { subtreeIds } from '../../core/tree.js';
+import { subtreeIds, childrenOf, SPEC_GLOBAL_ID, SPEC_OVERLAY_ID, } from '../../core/tree.js';
 import { checkBandOrder } from './traps.js';
 /**
  * Everything that would make the platform refuse this document on save.
@@ -16,6 +16,36 @@ export function validateForSave(doc) {
     const band = checkBandOrder(d);
     if (band)
         problems.push(band);
+    // COMPOSITION STAMPS: only a DIRECT child of ROOT may carry one, and never the
+    // same id twice.
+    //
+    // The platform refuses both — ErrGlobalNested / ErrDuplicateGlobal
+    // (server/internal/page/decompose.go:256,293) and their overlay twins
+    // (overlay.go:46-55). It refuses them LATE, though: the agent keeps editing
+    // and one autosave later gets a bare `duplicate_global`, which reads like a
+    // transport error rather than something it did. The overlay pair is worse
+    // still — it has no mapped error code and falls through to writeErr's default.
+    const rootKids = new Set(childrenOf(d, d.root_node_id));
+    for (const stamp of [SPEC_GLOBAL_ID, SPEC_OVERLAY_ID]) {
+        const seen = new Map();
+        for (const [id, n] of Object.entries(d.nodes)) {
+            const value = n.specials?.[stamp];
+            if (typeof value !== 'string' || !value)
+                continue;
+            if (!rootKids.has(id)) {
+                problems.push(`Node ${id} carries ${stamp} "${value}" but is not a direct child of ROOT. ` +
+                    'The platform refuses the save; move it to ROOT or remove the stamp.');
+                continue;
+            }
+            const first = seen.get(value);
+            if (first) {
+                problems.push(`Nodes ${first} and ${id} both carry ${stamp} "${value}". One page may reference ` +
+                    'it only once — remove one, or drop the stamp to make it a plain local section.');
+                continue;
+            }
+            seen.set(value, id);
+        }
+    }
     // Dangling child ids: a parent naming a node that is not in the map. The
     // renderer walks children by id, so this is a hole in the rendered page.
     for (const [id, n] of Object.entries(d.nodes)) {

package/dist/smoke.js

@@ -98,6 +98,35 @@ export async function runSmoke() {
     doc.apply(add2(doc, 'rt', { type: 'flex-section', children: [{ type: 'text' }] }).patches);
     const codes = reviewDesign(doc).map((f) => f.code);
     check('an unfilled placeholder IS reported', codes.includes('placeholder_content'));
+    // A REPEATER ARRIVES WITH ITS EMPTY STATE.
+    //
+    // On its OWN document, because a repeater with no card template is a genuinely
+    // empty container and would answer the review check below with a finding it is
+    // right to make.
+    //
+    // The satellite hangs off `config.emptyStateId`, not the child list, so every
+    // walk that follows children only reports this document as correct while the
+    // renderer takes its degrade path and ships ghost cards to a shopper.
+    const satDoc = PageDoc.from({
+        schema_version: 2,
+        root_node_id: 'rt',
+        nodes: {
+            rt: {
+                id: 'rt',
+                data: { type: 'root', parent: null, nodes: [], isCanvas: true, hidden: false, custom: {} },
+                style: {}, config: {}, specials: {}, responsive: {}, events: [], bindings: [],
+            },
+        },
+    });
+    const satSection = addSubtree(satDoc, 'rt', { type: 'flex-section' });
+    satDoc.apply(satSection.patches);
+    const listed = addSubtree(satDoc, satSection.ids[0], { type: 'list-dataset' });
+    satDoc.apply(listed.patches);
+    const list = satDoc.node(listed.ids[0]);
+    const emptyId = list.config.emptyStateId;
+    check('a repeater is minted with its empty state', typeof emptyId === 'string' && satDoc.has(emptyId) && satDoc.node(emptyId).data.type === 'list-empty');
+    check('the empty state carries its design, not a blank box', satDoc.node(String(emptyId)).data.nodes.length === 3);
+    check('a document carrying satellites still stores', validateForSave(satDoc).length === 0);
     console.error('ALL GOOD');
 }
 runSmoke().catch((err) => {

package/dist/tools/live.js

@@ -60,30 +60,45 @@ export function bindNode(doc, id, source, field) {
     ];
 }
 /**
- * The live socket takes a session JWT only.
+ * The credential that opens the live-edit room.
  *
- * `server/internal/server/realtime.go:38` refuses API keys, and a rejected
- * socket auth still fires `onopen` — so without this check an API-key-only
- * agent would "join", publish every edit into the void, and never learn why
- * nobody saw them. Every other tool works with the key; this one says so.
+ * AN AGENT KEY NOW WORKS. `server/internal/server/realtime.go:44` gives a `wbk_`
+ * bearer "the same door as a session", decided from the token's own shape, and
+ * gates it on member.read through the key's DELEGATED principal — so the key
+ * sees the room only if the member who minted it may, and only on the site the
+ * key belongs to. This function used to refuse a key-only context outright,
+ * which was true before agent keys landed and now turns away a working setup.
+ *
+ * The peer that appears on the canvas is then the KEY, not a person: the
+ * platform returns `key.ID` and `key.Name` rather than the minter's name,
+ * deliberately — an avatar borrowing a human's name would tell the room a person
+ * is editing when a machine is. So the merchant sees the label they chose for
+ * the key moving around the page.
+ *
+ * Still a GETTER, read per attempt: a session access token lives ~15 minutes and
+ * rotates, and a captured string replays an expired token forever on every
+ * reconnect — silently, because a rejected socket auth still fires `onopen`.
  */
-export function requireSessionForLive(ctx) {
-    if (!ctx.session.loggedIn()) {
-        throw new Error('sbuilder: the live-edit room takes a session token only — an API key cannot join. Set ' +
-            'SB_EMAIL and SB_PASSWORD and call sb_connect, then sb_live_join. Every other tool ' +
-            'works with the key alone.');
+export function liveTokenFor(ctx) {
+    if (!ctx.session.loggedIn() && !ctx.apiKey) {
+        throw new Error('sbuilder: the live-edit room needs a credential. Set SB_TOKEN, or SB_EMAIL and ' +
+            'SB_PASSWORD, and call sb_connect before sb_live_join.');
     }
-    return () => ctx.session.token();
+    // Prefer the key, for the reason `tokenFor` prefers it everywhere: a key is
+    // narrower — one site, its own scopes, revocable on its own — while a session
+    // carries the whole account.
+    return () => (ctx.apiKey ? ctx.apiKey : ctx.session.token());
 }
 export function registerLiveTools(server, ctx, session) {
     server.registerTool('sb_live_join', {
         description: "Join the site's live-edit room as a visible peer: every write then appears in any open " +
-            'editor as it happens. Always yields, so it is safe beside a human. Needs ' +
-            'SB_EMAIL / SB_PASSWORD; the socket refuses API keys.',
+            'editor as it happens, with the agent shown by the API key\'s own name rather than a ' +
+            "person's. Always yields, so it is safe beside a human. Works with SB_TOKEN or with " +
+            'SB_EMAIL / SB_PASSWORD.',
         inputSchema: { site_id: z.string() },
         annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true },
     }, async ({ site_id }) => {
-        const tokenFn = requireSessionForLive(ctx);
+        const tokenFn = liveTokenFor(ctx);
         const wsBase = ctx.base.replace(/^http/, 'ws').replace(/\/$/, '');
         const socket = new RealtimeSocket(`${wsBase}/api/realtime/ws?site=${encodeURIComponent(site_id)}`, tokenFn);
         const live = new LiveSession(socket, {