sbuilder-mcp 0.2.2 → 0.3.0

package/dist/domains/site/review.js

@@ -38,6 +38,21 @@ const BOUND_TYPES = Object.keys(BOUND_SPECIALS).sort();
 function canShowARecord(type) {
     return (BOUND_SPECIALS[type] ?? []).length > 0;
 }
+/**
+ * Bound specials that carry NAVIGATION rather than what a visitor reads.
+ *
+ * The distinction decides whether an empty container is a defect. A
+ * `dataset-block` binds only these — it is a card that still needs the fields
+ * put inside it, so an empty one really is an empty card. A `media-dataset`
+ * binds `boundImage` / `boundImages` and DRAWS the record itself, children or
+ * not: a bound one with no children publishes a product photo, and calling that
+ * "an empty band" is the false positive that teaches a reader to skip the list.
+ */
+const LINK_SPECIALS = new Set(['boundHref', 'boundHrefLabel', 'boundProductURL']);
+/** Whether this element's own renderer paints the record, so it needs no children. */
+function drawsItsOwnContent(type) {
+    return (BOUND_SPECIALS[type] ?? []).some((k) => !LINK_SPECIALS.has(k));
+}
 /**
  * Everything wrong with this page that a person would notice.
  *
@@ -99,9 +114,16 @@ export function reviewDesign(doc) {
             });
             continue;
         }
+        const bindings = n.bindings ?? [];
         // A container with nothing in it is a band of empty space. The commonest way
         // to ship one is to add the section and then get distracted.
-        if (meta.isContainer && childrenOf(d, id).length === 0) {
+        //
+        // Unless the element paints the record ITSELF: a bound `media-dataset` with
+        // no children publishes the product's photo and its thumbnail strip, which
+        // this rule reported as an empty band on a page that rendered correctly.
+        if (meta.isContainer &&
+            childrenOf(d, id).length === 0 &&
+            !(bindings.length > 0 && drawsItsOwnContent(type))) {
             out.push({
                 code: 'empty_container',
                 nodeId: id,
@@ -110,7 +132,6 @@ export function reviewDesign(doc) {
                 fix: fill('empty_container', { id }),
             });
         }
-        const bindings = n.bindings ?? [];
         const repeater = inRepeater.get(id);
         const boundFields = new Set(bindings.map((b) => b.field));
         /**

package/dist/domains/site/traps.js

@@ -1,5 +1,5 @@
 import { FIRST_CHILD_ONLY } from '../../catalog/elements.generated.js';
-import { pageChildren, isOverlay, SPEC_GLOBAL_ID, SPEC_GLOBAL_KIND, } from '../../core/tree.js';
+import { pageChildren, isOverlay, SPEC_GLOBAL_ID, SPEC_GLOBAL_KIND, SPEC_GLOBAL_REV, SPEC_OVERLAY_ID, SPEC_OVERLAY_REV, } from '../../core/tree.js';
 /**
  * Which band a direct child of ROOT belongs to.
  *
@@ -120,3 +120,40 @@ export function refuseSecondTemplate(doc, parentId, verb) {
         'appears on the published page. Design the existing template, or sb_remove it first.');
 }
 export { isOverlay };
+/**
+ * Re-stamp the composed masters with the revisions the save just reported.
+ *
+ * THE FENCE MOVES ON EVERY SAVE. Compose stamps `specials.globalRev` /
+ * `specials.overlayRev` onto the node it materialises; the save sends that back
+ * as `expectRev`; the platform refuses a stale one — and refuses it with a
+ * WARNING and a 200, not an error. So the first edit to a shared header or to
+ * the cart drawer lands, the fence advances on the server, and every edit after
+ * it in the same session is dropped while the tool reports success.
+ *
+ * Measured: two `sb_remove` calls in one session against the cart drawer. The
+ * first removed its subtree; the second answered `{"removed": …}` and changed
+ * nothing, and the drawer kept rendering the node in the browser.
+ *
+ * A master the report does not mention is left alone — it was not part of this
+ * save, and inventing a revision for it is how a fence stops being one.
+ */
+export function restampPatches(doc, report) {
+    const wanted = new Map();
+    for (const g of report.globals ?? [])
+        wanted.set(g.id, { key: SPEC_GLOBAL_REV, rev: g.rev });
+    for (const o of report.overlays ?? [])
+        wanted.set(o.id, { key: SPEC_OVERLAY_REV, rev: o.rev });
+    if (wanted.size === 0)
+        return [];
+    const out = [];
+    for (const [id, n] of Object.entries(doc.nodes)) {
+        const masterId = n.specials?.[SPEC_GLOBAL_ID] ?? n.specials?.[SPEC_OVERLAY_ID];
+        if (typeof masterId !== 'string')
+            continue;
+        const next = wanted.get(masterId);
+        if (!next || n.specials?.[next.key] === next.rev)
+            continue;
+        out.push({ op: 'set', path: ['nodes', id, 'specials', next.key], value: next.rev });
+    }
+    return out;
+}

package/dist/install/index.js

@@ -2,12 +2,34 @@ import { targets, detected } from './paths.js';
 import { mergeInto } from './write.js';
 /** The name the server appears under in every client. */
 export const SERVER_NAME = 'sbuilder';
+/**
+ * Every flag the CLI understands.
+ *
+ * NAMED, so an unknown one can be refused. `--site` and `--site-name` were typed
+ * at a real install, read by nothing, and reported as success — the caller then
+ * spent the session wondering why the site was not selected. A flag that is
+ * silently dropped is worse than one that does not exist.
+ */
+const FLAGS = [
+    '--token',
+    '--api',
+    '--site',
+    '--email',
+    '--password',
+    '--client',
+    '--dry-run',
+];
 export function buildEntry(opts, pkg = 'sbuilder-mcp') {
     const env = {};
     if (opts.api)
         env.SB_API = opts.api;
     if (opts.token)
         env.SB_TOKEN = opts.token;
+    // The site the agent works on. A key belongs to exactly one, so writing it
+    // here spares every tool call an id the install already knew — and spares the
+    // model the guess it otherwise makes from a page list.
+    if (opts.site)
+        env.SB_SITE = opts.site;
     // Only when a key is absent: a key opens everything the agent does day to day,
     // and writing an account password into six config files to buy the handful of
     // account-level calls it adds is a bad trade the installer should not make for
@@ -66,9 +88,27 @@ export function runInstallCli(argv) {
         const i = argv.indexOf(flag);
         return i >= 0 ? argv[i + 1] : undefined;
     };
+    // REFUSE what we cannot act on. Anything that looks like a flag and is not one
+    // is a typo or a flag from another version, and either way the caller believes
+    // it took effect.
+    const taken = new Set();
+    for (const f of FLAGS) {
+        const i = argv.indexOf(f);
+        if (i >= 0) {
+            taken.add(i);
+            if (f !== '--dry-run')
+                taken.add(i + 1);
+        }
+    }
+    const unknown = argv.filter((a, i) => a.startsWith('--') && !taken.has(i));
+    if (unknown.length) {
+        console.error(`sbuilder: unknown option(s) ${unknown.join(', ')}. Known: ${FLAGS.join(', ')}.`);
+        return 1;
+    }
     const opts = {
         token: get('--token') ?? process.env.SB_TOKEN,
         api: get('--api') ?? process.env.SB_API,
+        site: get('--site') ?? process.env.SB_SITE,
         email: get('--email') ?? process.env.SB_EMAIL,
         password: get('--password') ?? process.env.SB_PASSWORD,
         clients: get('--client')?.split(','),

package/dist/server.js

@@ -41,7 +41,13 @@ export function pkgVersion() {
 }
 export function buildContext() {
     const base = process.env.SB_API ?? 'http://localhost:8080';
-    return { base, session: new Session(base), apiKey: process.env.SB_TOKEN, notices: new Notices() };
+    return {
+        base,
+        session: new Session(base),
+        apiKey: process.env.SB_TOKEN,
+        siteId: process.env.SB_SITE,
+        notices: new Notices(),
+    };
 }
 export function createServer(ctx = buildContext()) {
     const server = new McpServer({ name: 'sbuilder', version: pkgVersion(), title: 'Store Builder' }, { instructions: INSTRUCTIONS });

package/dist/tools/api.js

@@ -173,7 +173,14 @@ export async function callOperation(ctx, args) {
         const name = m[1];
         const value = args.path_params?.[name];
         if (value === undefined) {
-            throw new Error(`sbuilder: operation ${op.id} needs path param "${name}"`);
+            // NAME THE ARGUMENT, not just the parameter. The call sheet lists these
+            // under `params` while the call takes them in `path_params`, and a caller
+            // who reads the sheet and passes `params` is told only that the param is
+            // missing — which is exactly the value they just supplied. Two words of
+            // "in path_params" is the difference between one round trip and a loop.
+            throw new Error(`sbuilder: operation ${op.id} needs path param "${name}" — pass it in path_params, ` +
+                `e.g. path_params: { "${name}": "…" }. The call sheet lists it under "params"; ` +
+                'query values go in `query`.');
         }
         path = path.replace(`{${name}}`, encodeURIComponent(value));
     }
@@ -206,6 +213,13 @@ export async function callOperation(ctx, args) {
         body: args.body,
         fetchImpl: ctx.fetchImpl,
     });
+    // A 204 HAS NO BODY, and `null` is not an answer a caller can read: a DELETE
+    // that worked and a DELETE that returned nothing looked identical, so sixteen
+    // page deletes in a row reported `null` sixteen times and the only way to know
+    // they had happened was to list the pages again. Say what the operation did.
+    if (raw === null || raw === undefined) {
+        return { ok: true, method: op.method, path, note: 'The platform answered with no content.' };
+    }
     return shapeResponse(raw, { pick: args.pick, max_items: args.max_items });
 }
 export function registerApiTools(server, ctx) {

package/dist/tools/context.js

@@ -1 +1,18 @@
-export {};
+/**
+ * The site a call is about: the one it names, or the one the install did.
+ *
+ * An API key belongs to exactly ONE site, so on a key-only install the id is a
+ * constant the environment already holds — and requiring it on every call made
+ * the model carry a 32-character string through a whole session, which it can
+ * only get by listing pages and reading one back. `SB_SITE` makes it optional
+ * without making it implicit: an explicit argument always wins, so a
+ * two-site session still works by naming each one.
+ */
+export function siteFor(ctx, given) {
+    const id = given ?? ctx.siteId;
+    if (!id) {
+        throw new Error('sbuilder: no site. Pass site_id, or set SB_SITE to the site this install works on ' +
+            '(sbuilder-mcp install --site site_…).');
+    }
+    return id;
+}

package/dist/tools/live.js

@@ -1,7 +1,7 @@
 import { randomBytes } from 'node:crypto';
 import { z } from 'zod';
 import { text, images } from '../mcp/response.js';
-import { BINDING_SOURCES } from '../catalog/elements.generated.js';
+import { BINDING_SOURCES, ELEMENTS } from '../catalog/elements.generated.js';
 import { previewUrl } from '../vision/preview.js';
 import { uploadMedia } from '../transport/media.js';
 import { request } from '../transport/http.js';
@@ -24,8 +24,24 @@ const DATASET_TYPES = new Set([
 import { RealtimeSocket } from '../transport/socket.js';
 import { LiveSession } from '../live/session.js';
 import { refuseAppBlockInterior } from '../domains/site/builder.js';
+import { childrenOf, isOverlay, subtreeIds } from '../core/tree.js';
 import { siteToken } from './credentialpick.js';
+import { siteFor } from './context.js';
 import { projectList, MEDIA_FIELDS } from './project.js';
+/**
+ * The reserved binding id a PURCHASE control carries, and the vocabulary its
+ * target speaks — `schema/src/elements/datasetBindings.ts:845-852`.
+ *
+ * The id is reserved so authoring and the editor's own healing never collide,
+ * and `buy_now` is stored as builderx's `dynamic_checkout`: the picker's word
+ * and the document's word are deliberately different, and hand-mapping either
+ * one is how the two drift.
+ */
+const PRODUCT_ACTION_BINDING_ID = 'bind-product-action';
+const PURCHASE_TARGETS = {
+    add_to_cart: 'add_to_cart',
+    buy_now: 'dynamic_checkout',
+};
 /**
  * Bind a node's content to real store data.
  *
@@ -38,7 +54,7 @@ import { projectList, MEDIA_FIELDS } from './project.js';
  *    reads the namespace off the field and `continue`s on anything else — so a
  *    `style.color` binding is stored, saved, published, and ignored forever.
  */
-export function bindNode(doc, id, source, field) {
+export function bindNode(doc, id, source, field, action) {
     const node = doc.node(id);
     refuseAppBlockInterior(doc, id, 'binding');
     if (!BINDING_SOURCES.includes(source)) {
@@ -50,6 +66,36 @@ export function bindNode(doc, id, source, field) {
         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 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
+    // reads `target.action` (`server/render/nodes/helpers.go:1166`) and nothing
+    // else, `sb_set` writes only style/config/specials, and this tool's plain path
+    // writes no target at all — so before this branch a store built entirely
+    // through these tools had no way to author an Add-to-cart button, while
+    // `sb_review` reported the gap and named no fix that worked. The one control
+    // a shop cannot do without was the one the tools could not make.
+    if (action !== undefined) {
+        const mapped = PURCHASE_TARGETS[action];
+        if (!mapped) {
+            throw new Error(`sbuilder: "${action}" is not a purchase action. Use "add_to_cart" or "buy_now" — ` +
+                'those are the two the renderer draws a purchase control for.');
+        }
+        const value = {
+            id: PRODUCT_ACTION_BINDING_ID,
+            source,
+            field,
+            target: { type: 'product', id: '', action: mapped },
+        };
+        // RESERVED ID, so a second call re-points the control instead of leaving two
+        // purchase bindings on one button for the runtime to choose between.
+        const at = node.bindings.findIndex((b) => b?.id === PRODUCT_ACTION_BINDING_ID);
+        if (at >= 0)
+            return [{ op: 'set', path: ['nodes', id, 'bindings', String(at)], value }];
+        return [
+            { op: 'insert', path: ['nodes', id, 'bindings'], index: node.bindings.length, value },
+        ];
+    }
     return [
         {
             op: 'insert',
@@ -59,6 +105,77 @@ export function bindNode(doc, id, source, field) {
         },
     ];
 }
+/**
+ * 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.
+ *
+ * THE ONE THING NO TOOL COULD DO. `NodeSpec` carries no `events`, `sb_set`
+ * writes only style/config/specials, and `createNode` always minted `events: []`
+ * — so `open_cart` could not be authored, and a site built from scratch had no
+ * way to open its own cart drawer. `sb_review` reported that gap
+ * (`cartTrigger`) and named a fix nothing could apply, which is the same shape
+ * the purchase binding had before `sb_bind` grew `action`.
+ *
+ * A purchase is NOT here. `add_to_cart` and `buy_now` are absent from every
+ * element's allow-list, and the button meta says why in as many words: neither
+ * is a click action. The intent is the BINDING — `sb_bind` with `action` — and
+ * the event is what happens alongside it.
+ *
+ * ONE ACTION PER TRIGGER, replaced in place. The platform stores a list, but a
+ * second `click` on one node is two answers to one question, and picking between
+ * them at runtime is the platform's business rather than an authoring choice.
+ */
+export function setEvent(doc, id, trigger, action, payload) {
+    const node = doc.node(id);
+    refuseAppBlockInterior(doc, id, 'setting an event on');
+    const events = node.events ?? [];
+    const at = events.findIndex((e) => e?.name === trigger);
+    if (action === 'none') {
+        if (at < 0)
+            return [];
+        return [{ op: 'remove', path: ['nodes', id, 'events'], index: at }];
+    }
+    const table = liveEventTable(node.data.type, node);
+    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: ' +
+            Object.keys(ELEMENTS).filter((t) => ELEMENTS[t]?.events).join(', ') + '.');
+    }
+    const allowed = table[trigger];
+    if (!allowed) {
+        throw new Error(`sbuilder: a ${node.data.type} offers no "${trigger}" trigger. It offers: ` +
+            `${Object.keys(table).join(', ')}.`);
+    }
+    if (!allowed.includes(action)) {
+        const purchase = action === 'add_to_cart' || action === 'buy_now';
+        throw new Error(`sbuilder: "${action}" is not an action a ${node.data.type} offers on ${trigger}. ` +
+            (purchase
+                ? 'A purchase is a BINDING, not a click action — use sb_bind with action:"' +
+                    action + '". '
+                : '') +
+            `Allowed: ${allowed.join(', ')}.`);
+    }
+    const value = { id: `ev_${action}`, name: trigger, action, payload: payload ?? {} };
+    if (at >= 0)
+        return [{ op: 'set', path: ['nodes', id, 'events', String(at)], value }];
+    return [{ op: 'insert', path: ['nodes', id, 'events'], index: events.length, value }];
+}
 /**
  * The credential that opens the live-edit room.
  *
@@ -95,9 +212,10 @@ export function registerLiveTools(server, ctx, session) {
             '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() },
+        inputSchema: { site_id: z.string().optional() },
         annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true },
-    }, async ({ site_id }) => {
+    }, async ({ site_id: given }) => {
+        const site_id = siteFor(ctx, given);
         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);
@@ -166,7 +284,16 @@ export function registerLiveTools(server, ctx, session) {
         const review = reviewField(ctx, session.current());
         // Measured on the render, not read off the document — a card that spills
         // at 390px is invisible to every check that only reads the tree.
-        const visual = node_id ? [] : measure(shots);
+        // The overlay subtree, read off the OPEN DOCUMENT — the boxes come from
+        // the render and carry no idea which node is a drawer.
+        const doc = session.current().doc;
+        const skip = new Set();
+        for (const id of childrenOf(doc, doc.root_node_id)) {
+            if (isOverlay(doc, id))
+                for (const n of subtreeIds(doc, id))
+                    skip.add(n);
+        }
+        const visual = node_id ? [] : measure(shots, skip);
         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.
@@ -204,17 +331,17 @@ export function registerLiveTools(server, ctx, session) {
         description: "The site's media library. Reuse an image before adding another; search by name, filter " +
             'by type, page with limit/offset.',
         inputSchema: {
-            site_id: z.string(),
+            site_id: z.string().optional(),
             search: z.string().optional(),
             media_type: z.string().optional().describe('e.g. "image"'),
             limit: z.number().int().min(1).max(200).optional(),
             offset: z.number().int().min(0).optional(),
         },
         annotations: { readOnlyHint: true },
-    }, async ({ site_id, search, media_type, limit, offset }) => text(projectList(await request({
+    }, async ({ site_id: given, search, media_type, limit, offset }) => text(projectList(await request({
         base: ctx.base,
         method: 'GET',
-        path: `/api/sites/${encodeURIComponent(site_id)}/media`,
+        path: `/api/sites/${encodeURIComponent(siteFor(ctx, given))}/media`,
         token: siteToken(ctx),
         query: { search, mediaType: media_type, limit, offset },
         fetchImpl: ctx.fetchImpl,
@@ -224,7 +351,7 @@ export function registerLiveTools(server, ctx, session) {
             'local file path or a URL to fetch. This is the ONLY way to add an image: the upload ' +
             'is multipart, which sb_api_call cannot send.',
         inputSchema: {
-            site_id: z.string(),
+            site_id: z.string().optional(),
             path: z.string().optional().describe('A file on this machine'),
             url: z.string().optional().describe('Fetched, then uploaded'),
             name: z.string().optional(),
@@ -232,7 +359,8 @@ export function registerLiveTools(server, ctx, session) {
             dry_run: z.boolean().optional(),
         },
         annotations: { readOnlyHint: false, destructiveHint: false },
-    }, async ({ site_id, path, url, name, folder_id, dry_run }) => {
+    }, async ({ site_id: given, path, url, name, folder_id, dry_run }) => {
+        const site_id = siteFor(ctx, given);
         if (!path && !url)
             throw new Error('sbuilder: give sb_media_upload either a path or a url');
         if (dry_run !== false) {
@@ -251,9 +379,31 @@ export function registerLiveTools(server, ctx, session) {
                 : 'Uploaded, but the server returned no url — read it back with sb_media_list.',
         });
     });
+    server.registerTool('sb_event', {
+        description: 'Give a node a click action — open the cart, go to a page, open a pop-up. A purchase ' +
+            'is not one: use sb_bind action.',
+        inputSchema: {
+            id: z.string(),
+            action: z
+                .string()
+                .describe('An action this element allows, or "none" to clear. A wrong one is refused with the list'),
+            trigger: z.string().optional().describe('Default "click"'),
+            payload: z.record(z.unknown()).optional(),
+            dry_run: z.boolean().optional(),
+        },
+        annotations: { readOnlyHint: false, destructiveHint: false },
+    }, async ({ id, action, trigger, payload, dry_run }) => {
+        const d = session.current();
+        const patches = setEvent(d, id, trigger ?? 'click', action, payload);
+        if (dry_run !== false)
+            return text({ dry_run: true, patches });
+        session.applyAndPublish(patches);
+        await session.save();
+        return text({ node: id, trigger: trigger ?? 'click', action, rev: d.rev });
+    });
     server.registerTool('sb_bind', {
-        description: "Bind a node's content to real store data, so the page shows actual products rather than " +
-            'placeholder text.',
+        description: 'Bind a node to real store data so the page shows actual products, not placeholder ' +
+            'text. action makes a button a purchase control.',
         inputSchema: {
             id: z.string(),
             source: z
@@ -264,16 +414,20 @@ export function registerLiveTools(server, ctx, session) {
             // unknown one costs one round trip and the schema stays small.
             `e.g. ${BINDING_SOURCES.slice(0, 4).join(', ')}; ${BINDING_SOURCES.length} in all, and a wrong one is refused with the list`),
             field: z.string().describe('Where the value lands, always "specials.<key>"'),
+            action: z
+                .enum(['add_to_cart', 'buy_now'])
+                .optional()
+                .describe('Pass product.id + specials.boundProductId'),
             dry_run: z.boolean().optional(),
         },
         annotations: { readOnlyHint: false, destructiveHint: false },
-    }, async ({ id, source, field, dry_run }) => {
+    }, async ({ id, source, field, action, dry_run }) => {
         const d = session.current();
-        const patches = bindNode(d, id, source, field);
+        const patches = bindNode(d, id, source, field, action);
         if (dry_run !== false)
             return text({ dry_run: true, patches });
         session.applyAndPublish(patches);
         await session.save();
-        return text({ bound: id, source, field, rev: d.rev });
+        return text({ bound: id, source, field, ...(action ? { action } : {}), rev: d.rev });
     });
 }

package/dist/tools/page.js

@@ -11,8 +11,9 @@ import { reviewDesign, REVIEW_NOTICE } from '../domains/site/review.js';
 import { compactFindings } from '../domains/site/findings.js';
 import { readinessGaps, READINESS_NOTICE } from '../domains/site/readiness.js';
 import { gatherReadiness } from '../domains/site/readiness-fetch.js';
-import { globalWarning, RESPONSIVE_NOTICE } from '../domains/site/traps.js';
+import { globalWarning, restampPatches, RESPONSIVE_NOTICE } from '../domains/site/traps.js';
 import { catalogMatches, traitsFor } from '../catalog/element-search.js';
+import { siteFor } from './context.js';
 import { projectList, PAGE_FIELDS, TEMPLATE_FIELDS } from './project.js';
 /**
  * Findings, in the shape every surface returns them.
@@ -131,7 +132,15 @@ export class PageSession {
         if (problems.length > 0) {
             throw new Error(`sbuilder: refusing to save — ${problems.join(' ')}`);
         }
-        await saveSource(this.ctx, this.siteId, this.pageId, d.doc);
+        const saved = await saveSource(this.ctx, this.siteId, this.pageId, d.doc);
+        // RE-STAMP THE FENCE, or lose every edit after this one.
+        //
+        // The save reports each shared master's new revision precisely so the client
+        // can carry it into the next save; the platform refuses a stale `expectRev`
+        // with a warning and a 200. Applied locally rather than published: these are
+        // the server's own numbers coming back, not an edit anybody made, and a peer
+        // in the room gets them from its own save.
+        d.apply(restampPatches(d.doc, { globals: saved.globals, overlays: saved.overlays }));
     }
 }
 const specSchema = z.lazy(() => z.object({
@@ -147,10 +156,10 @@ export function registerPageTools(server, ctx) {
     server.registerTool('sb_page_open', {
         description: 'Open a page for editing and return its outline. Call before any sb_add / sb_set / ' +
             'sb_move / sb_remove. Find page ids with sb_api_find "list pages".',
-        inputSchema: { site_id: z.string(), page_id: z.string() },
+        inputSchema: { site_id: z.string().optional(), page_id: z.string() },
         annotations: { readOnlyHint: true },
-    }, async ({ site_id, page_id }) => {
-        const outline = await session.open(site_id, page_id);
+    }, async ({ site_id: given, page_id }) => {
+        const outline = await session.open(siteFor(ctx, given), page_id);
         const doc = session.current();
         // A page whose stored document named its root under the app-block key
         // renders as an empty <body> and says nothing about why. Nobody else can
@@ -356,12 +365,12 @@ export function registerPageTools(server, ctx) {
     server.registerTool('sb_templates', {
         description: "The store's saved section templates — designed sections a person starts from rather " +
             'than assembling one. Use sb_template_use to drop one into the open page.',
-        inputSchema: { site_id: z.string() },
+        inputSchema: { site_id: z.string().optional() },
         annotations: { readOnlyHint: true },
-    }, async ({ site_id }) => text(projectList(await request({
+    }, async ({ site_id: given }) => text(projectList(await request({
         base: ctx.base,
         method: 'GET',
-        path: `/api/sites/${encodeURIComponent(site_id)}/section-templates`,
+        path: `/api/sites/${encodeURIComponent(siteFor(ctx, given))}/section-templates`,
         token: siteToken(ctx),
         fetchImpl: ctx.fetchImpl,
     }), 'sectionTemplates', TEMPLATE_FIELDS)));
@@ -369,13 +378,14 @@ export function registerPageTools(server, ctx) {
         description: 'Instantiate a saved section template into a page. The server does the copy, so the ' +
             'section arrives exactly as it was designed — then re-open the page to see it.',
         inputSchema: {
-            site_id: z.string(),
+            site_id: z.string().optional(),
             template_id: z.string(),
             page_id: z.string(),
             dry_run: z.boolean().optional(),
         },
         annotations: { readOnlyHint: false, destructiveHint: false },
-    }, async ({ site_id, template_id, page_id, dry_run }) => {
+    }, async ({ site_id: given, template_id, page_id, dry_run }) => {
+        const site_id = siteFor(ctx, given);
         const path = `/api/sites/${encodeURIComponent(site_id)}/section-templates/${encodeURIComponent(template_id)}/instantiate`;
         if (dry_run !== false) {
             return text({ dry_run: true, would_post: path, body: { pageId: page_id } });
@@ -397,12 +407,12 @@ export function registerPageTools(server, ctx) {
     });
     server.registerTool('sb_page_list', {
         description: "Every page on the site, with its slug and whether it is live.",
-        inputSchema: { site_id: z.string() },
+        inputSchema: { site_id: z.string().optional() },
         annotations: { readOnlyHint: true },
-    }, async ({ site_id }) => text(projectList(await request({
+    }, async ({ site_id: given }) => text(projectList(await request({
         base: ctx.base,
         method: 'GET',
-        path: `/api/sites/${encodeURIComponent(site_id)}/pages`,
+        path: `/api/sites/${encodeURIComponent(siteFor(ctx, given))}/pages`,
         token: siteToken(ctx),
         fetchImpl: ctx.fetchImpl,
     }), 'pages', PAGE_FIELDS)));
@@ -411,7 +421,7 @@ export function registerPageTools(server, ctx) {
             'checkout, product, category, post and course: /checkout and /products/{slug} need a ' +
             'PUBLISHED page of that type or they 404.',
         inputSchema: {
-            site_id: z.string(),
+            site_id: z.string().optional(),
             name: z.string(),
             type: z.string().optional().describe('page (default), checkout, product, category, post, course'),
             slug: z.string().optional(),
@@ -420,7 +430,8 @@ export function registerPageTools(server, ctx) {
             dry_run: z.boolean().optional(),
         },
         annotations: { readOnlyHint: false, destructiveHint: false },
-    }, async ({ site_id, name, type, slug, is_homepage, settings, dry_run }) => {
+    }, async ({ site_id: given, name, type, slug, is_homepage, settings, dry_run }) => {
+        const site_id = siteFor(ctx, given);
         const path = `/api/sites/${encodeURIComponent(site_id)}/pages`;
         // TYPE IS THE ROUTE for several kinds of page: /checkout and
         // /products/{slug} resolve to the site's PUBLISHED page of that type and
@@ -470,9 +481,10 @@ export function registerPageTools(server, ctx) {
         description: 'Compile the draft into the live page. PUBLISH CASCADES: a page sharing a global ' +
             'section with others republishes them too, because a header edited once must not go ' +
             'live on one page and stay stale on the rest.',
-        inputSchema: { site_id: z.string(), page_id: z.string(), dry_run: z.boolean().optional() },
+        inputSchema: { site_id: z.string().optional(), page_id: z.string(), dry_run: z.boolean().optional() },
         annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true },
-    }, async ({ site_id, page_id, dry_run }) => {
+    }, async ({ site_id: given, page_id, dry_run }) => {
+        const site_id = siteFor(ctx, given);
         // PUBLISH IS A SITE-LEVEL CALL that NAMES pages, not a page-level route.
         // This used to POST /pages/{id}/publish, which the platform answers 404 —
         // it mounts "publish" as its own resource beside "pages"