sbuilder-mcp 0.1.0

package/dist/live/session.js

@@ -0,0 +1,164 @@
+import { randomBytes } from 'node:crypto';
+import { syncable, isSyncablePatch } from '../core/patch.js';
+/**
+ * The agent's seat in the live-edit room.
+ *
+ * THE YIELD RULE governs everything here: this client never answers `snapreq`,
+ * never publishes a checkpoint of its own, and re-pulls on any evidence of
+ * divergence. That is what lets it skip the editor's outbox deferral, inbox
+ * arbitration and "who pulls" tie-break — roughly a thousand lines whose entire
+ * purpose is arbitrating between two EQUALLY authoritative editors. This one is
+ * not one of those, deliberately.
+ */
+export class LiveSession {
+    socket;
+    opts;
+    selfId = '';
+    pageId = '';
+    roster = new Map();
+    pending = new Map();
+    seq = 0;
+    constructor(socket, opts) {
+        this.socket = socket;
+        this.opts = opts;
+        this.socket.on((e) => this.receive(e));
+    }
+    get peers() {
+        return [...this.roster.values()];
+    }
+    /** Is anyone else here? The yield rule only costs anything when someone is. */
+    get humanPresent() {
+        return this.roster.size > 0;
+    }
+    get maxSeq() {
+        return this.seq;
+    }
+    get pendingAcks() {
+        return this.pending.size;
+    }
+    start(pageId) {
+        this.pageId = pageId;
+        // The welcome may already have arrived, or may not — the order depends on
+        // how fast the server answers. Announce now if we know who we are;
+        // otherwise `receive` does it when the welcome lands.
+        if (this.selfId)
+            this.announcePage();
+    }
+    announcePage() {
+        if (!this.pageId)
+            return;
+        this.socket.send({ t: 'page', pageId: this.pageId });
+    }
+    /**
+     * Put a batch of my own patches on the wire.
+     *
+     * Filtered through `syncable` first, and an EMPTY result is not sent at all:
+     * the server drops an ops frame with no ops silently (a bare `continue` in
+     * readPump), so sending one is indistinguishable from success while achieving
+     * nothing at all.
+     */
+    publish(patches) {
+        if (!this.pageId)
+            return;
+        const ops = syncable(patches);
+        if (ops.length === 0)
+            return;
+        const opId = randomBytes(8).toString('hex');
+        this.pending.set(opId, Date.now());
+        this.socket.send({ t: 'ops', pageId: this.pageId, ops, opId });
+    }
+    /** Presence only — never document state. */
+    cursor(x, y) {
+        if (!this.pageId)
+            return;
+        this.socket.send({ t: 'cursor', pageId: this.pageId, x, y });
+    }
+    select(nodeId) {
+        if (!this.pageId)
+            return;
+        this.socket.send({ t: 'select', pageId: this.pageId, nodeId });
+    }
+    receive(e) {
+        switch (e.t) {
+            case 'welcome': {
+                this.selfId = String(e.peerId ?? '');
+                this.roster.clear();
+                for (const p of e.peers ?? [])
+                    this.roster.set(p.id, p);
+                this.announcePage();
+                break;
+            }
+            case 'join': {
+                const p = e.peer;
+                if (p?.id && p.id !== this.selfId)
+                    this.roster.set(p.id, p);
+                break;
+            }
+            case 'leave': {
+                this.roster.delete(String(e.peerId ?? ''));
+                break;
+            }
+            case 'page': {
+                const p = this.roster.get(String(e.peerId ?? ''));
+                if (p)
+                    p.pageId = String(e.pageId ?? '');
+                break;
+            }
+            case 'ack': {
+                this.pending.delete(String(e.opId ?? ''));
+                const s = Number(e.seq ?? 0);
+                if (s > this.seq)
+                    this.seq = s;
+                break;
+            }
+            case 'ops': {
+                if (e.pageId !== this.pageId)
+                    return;
+                const s = Number(e.seq ?? 0);
+                // A GAP means frames this client never received. Nothing local can
+                // repair that, so it goes straight to the caller as a re-pull.
+                if (this.seq > 0 && s > this.seq + 1) {
+                    this.opts.onDesync(`gap in seq: expected ${this.seq + 1}, received ${s}`);
+                }
+                if (s > this.seq)
+                    this.seq = s;
+                // My own batch, echoed to the room. It was applied locally when it was
+                // made; re-applying is harmless for a set and WRONG for a splice.
+                if (e.peerId === this.selfId)
+                    return;
+                const raw = e.ops ?? [];
+                // Admission is checked on the RECEIVING side too. This is the only guard
+                // that exists against a peer not running our code.
+                const ok = raw.filter((p) => isSyncablePatch(p));
+                if (ok.length > 0)
+                    this.opts.onRemote(ok);
+                break;
+            }
+            case 'snapreq':
+                // THE YIELD RULE. Never answered. Sending a snapshot would make this
+                // client an authority on the document — exactly the position it declines
+                // to hold, and the reason the rest of this class can stay this small.
+                break;
+            case 'ckpt': {
+                if (e.pageId !== this.pageId)
+                    return;
+                // Compared only at the SAME seq: two documents at different points in
+                // the order are supposed to differ.
+                //
+                // This client computes no digest of its own, so it cannot tell a real
+                // mismatch from a peer simply publishing. It treats a same-seq
+                // checkpoint arriving while idle as reason enough to re-pull, which is
+                // the CONSERVATIVE direction for a client whose repair is a cheap HTTP
+                // GET rather than a document exchange. If this proves noisy in practice
+                // the fix is to compute a digest and compare it — not to delete the
+                // branch and go back to trusting a tree nobody verified.
+                if (Number(e.seq ?? 0) === this.seq && this.pending.size === 0) {
+                    this.opts.onDesync(`checkpoint published at seq ${this.seq}; re-pulling to be sure`);
+                }
+                break;
+            }
+            default:
+                break;
+        }
+    }
+}

package/dist/mcp/response.js

@@ -0,0 +1,40 @@
+/**
+ * The one way a tool answers.
+ *
+ * Every tool returns through here so the content shape is decided in a single
+ * place — a hand-built content array is the shape that drifts, and a drifted one
+ * fails inside the client rather than here.
+ */
+export function text(value) {
+    const body = typeof value === 'string' ? value : JSON.stringify(value, null, 2);
+    return { content: [{ type: 'text', text: body }] };
+}
+/** A base64 image, optionally followed by a note the model should read. */
+export function image(dataBase64, mimeType = 'image/png', note) {
+    const content = [{ type: 'image', data: dataBase64, mimeType }];
+    if (note !== undefined) {
+        content.push({
+            type: 'text',
+            text: typeof note === 'string' ? note : JSON.stringify(note, null, 2),
+        });
+    }
+    return { content };
+}
+/**
+ * Several images (one per breakpoint, say), optionally followed by a note.
+ * Separate blocks rather than one tiled sheet so each is seen at a readable size.
+ */
+export function images(items, note) {
+    const content = items.map((it) => ({
+        type: 'image',
+        data: it.dataBase64,
+        mimeType: it.mimeType ?? 'image/png',
+    }));
+    if (note !== undefined) {
+        content.push({
+            type: 'text',
+            text: typeof note === 'string' ? note : JSON.stringify(note, null, 2),
+        });
+    }
+    return { content };
+}

package/dist/server.js

@@ -0,0 +1,59 @@
+import { readFileSync } from 'node:fs';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { Session } from './transport/auth.js';
+import { registerApiTools } from './tools/api.js';
+import { registerSessionTools } from './tools/session.js';
+import { registerPageTools } from './tools/page.js';
+import { registerLiveTools } from './tools/live.js';
+const INSTRUCTIONS = `Design and operate a Store Builder site.
+
+Call sb_connect first. Then:
+- sb_api_find describes what the platform can do; sb_api_call executes it. Between them
+  they reach all 310 API operations, so most merchant work needs no other tool.
+- Mutating calls default to dry_run:true and send NOTHING. Pass dry_run:false to act.
+- /api/v1 paths need SB_TOKEN; every other path uses the session from sb_connect. The
+  platform refuses each credential on the other's surface, so this is not interchangeable.
+- When sb_api_find returns body_warning or body_note, do not invent a request body. Read
+  the matching GET first and send back a modified copy.
+
+To DESIGN a page: sb_page_open, then sb_catalog_search to pick element types, then sb_add
+with a NESTED spec (one call per section, not per node), then sb_set for styling.
+- Writes default to dry_run:true and change nothing. Pass dry_run:false to act.
+- sb_set writes PER BREAKPOINT. A visual quantity written at base renders on the canvas and
+  vanishes on publish; pass base:true only for identity or content.
+- sb_outline, never a raw document dump. Read one node with sb_node_read.
+- A node flagged global is a SHARED master: editing it changes every page that carries it.
+  A node flagged overlay is not part of the page at all.
+
+- sb_live_join makes the agent VISIBLE: edits then appear in anyone's open editor as they
+  happen, with a cursor that moves to the node being changed.
+- sb_look saves, renders through the platform's own renderer, and hands back screenshots
+  plus measured node boxes. Judge the design from those; do not guess at it.
+- sb_bind puts real store data in the page instead of placeholder text.`;
+/**
+ * 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
+ * src/, so the same relative URL resolves in a build and in a source checkout.
+ * Never blocks startup over a version string.
+ */
+export function pkgVersion() {
+    try {
+        const pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+        return typeof pkg.version === 'string' && pkg.version ? pkg.version : '0.0.0';
+    }
+    catch {
+        return '0.0.0';
+    }
+}
+export function buildContext() {
+    const base = process.env.SB_API ?? 'http://localhost:8080';
+    return { base, session: new Session(base), apiKey: process.env.SB_TOKEN };
+}
+export function createServer(ctx = buildContext()) {
+    const server = new McpServer({ name: 'sbuilder', version: pkgVersion(), title: 'Store Builder' }, { instructions: INSTRUCTIONS });
+    registerSessionTools(server, ctx);
+    registerApiTools(server, ctx);
+    const pageSession = registerPageTools(server, ctx);
+    registerLiveTools(server, ctx, pageSession);
+    return server;
+}

package/dist/smoke.js

@@ -0,0 +1,106 @@
+/**
+ * Offline self-test. No network, no MCP transport — just the pure logic, so a
+ * broken build fails before anything is published. Must end with ALL GOOD.
+ */
+import { text } from './mcp/response.js';
+import { createServer, pkgVersion } from './server.js';
+import { API_OPERATIONS } from './catalog/api.generated.js';
+import { searchOperations, describeOperation } from './catalog/search.js';
+import { credentialFor } from './transport/credential.js';
+function check(label, ok) {
+    if (!ok) {
+        console.error(`FAIL: ${label}`);
+        process.exit(1);
+    }
+    console.error(`ok: ${label}`);
+}
+export async function runSmoke() {
+    check('text() wraps a string', text('x').content[0].text === 'x');
+    check('pkgVersion() is not empty', pkgVersion().length > 0);
+    check('createServer() builds', createServer() !== null);
+    check('API index has 300+ operations', API_OPERATIONS.length > 300);
+    check('every operation has a credential', API_OPERATIONS.every((o) => ['apiKey', 'siteScoped', 'none'].includes(o.credential)));
+    check('every credential matches the routing rule', API_OPERATIONS.every((o) => o.credential === credentialFor(o.path)));
+    check('search finds menu operations', searchOperations('menu').length > 0);
+    check('search returns nothing for nonsense', searchOperations('zzzzqqqq').length === 0);
+    check('no operation reports both body verdicts at once', API_OPERATIONS.every((o) => {
+        const d = describeOperation(o);
+        return !(d.body_warning !== undefined && d.body_note !== undefined);
+    }));
+    const { ELEMENTS, ELEMENT_SOURCE } = await import('./catalog/elements.generated.js');
+    check('element catalog is populated', Object.keys(ELEMENTS).length === ELEMENT_SOURCE.count);
+    check('every element carries AI hints', Object.values(ELEMENTS).every((e) => e.description.length > 0));
+    // An end-to-end pass through the document core: build a section with a child,
+    // and assert the result is something the platform would actually store.
+    const { PageDoc } = await import('./domains/site/document.js');
+    const { addSubtree, setKeys } = await import('./domains/site/builder.js');
+    const { validateForSave } = await import('./domains/site/validate.js');
+    const doc = 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 built = addSubtree(doc, 'rt', { type: 'flex-section', children: [{ type: 'heading' }] });
+    doc.apply(built.patches);
+    check('builder linked the subtree', doc.outline({ depth: 2 })[0].kids?.length === 1);
+    check('builder produces a storable document', validateForSave(doc).length === 0);
+    doc.apply(setKeys(doc, built.ids[0], { gap: '24px' }, { namespace: 'style' }));
+    const section = doc.node(built.ids[0]);
+    check('sb_set writes per breakpoint, not at base', section.responsive.desktop?.style?.gap === '24px' && section.style.gap === undefined);
+    doc.apply(setKeys(doc, built.ids[0], { maxWidth: '1200px' }, { namespace: 'style', base: true }));
+    const seeded = doc.node(built.ids[0]);
+    check('a base style is written, not refused', seeded.style.maxWidth === '1200px');
+    const { BINDING_SOURCES } = await import('./catalog/elements.generated.js');
+    check('binding sources are populated', BINDING_SOURCES.length > 15);
+    const { bindNode } = await import('./tools/live.js');
+    const bd = PageDoc.from({
+        schema_version: 2,
+        root_node_id: 'rt',
+        nodes: {
+            rt: {
+                id: 'rt',
+                data: { type: 'root', parent: null, nodes: ['he_1'], isCanvas: true, hidden: false, custom: {} },
+                style: {}, config: {}, specials: {}, responsive: {}, events: [], bindings: [],
+            },
+            he_1: {
+                id: 'he_1',
+                data: { type: 'heading', parent: 'rt', nodes: [], isCanvas: false, hidden: false, custom: {} },
+                style: {}, config: {}, specials: {}, responsive: {}, events: [], bindings: [],
+            },
+        },
+    });
+    bd.apply(bindNode(bd, 'he_1', 'product.title', 'specials.text'));
+    check('a valid binding lands', bd.node('he_1').bindings.length === 1);
+    let bindRefused = false;
+    try {
+        bindNode(bd, 'he_1', 'product.title', 'style.color');
+    }
+    catch {
+        bindRefused = true;
+    }
+    check('a non-specials binding field is REFUSED', bindRefused);
+    const { reviewDesign } = await import('./domains/site/review.js');
+    // Fill the heading before claiming the section is finished. The first version
+    // of this check asserted the section built above was clean; it was not — the
+    // heading still carried the placeholder the element ships with, and the
+    // reviewer said so. The check was wrong, not the reviewer.
+    doc.apply(setKeys(doc, built.ids[1], { text: 'Autumn sale' }, { namespace: 'specials' }));
+    check('a finished section reviews clean', reviewDesign(doc).length === 0);
+    // ...and an unfilled one must. A reviewer that never fires is indistinguishable
+    // from one that is not wired up.
+    const { addSubtree: add2 } = await import('./domains/site/builder.js');
+    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'));
+    console.error('ALL GOOD');
+}
+runSmoke().catch((err) => {
+    console.error('smoke threw:', err);
+    process.exit(1);
+});

package/dist/tools/api.js

@@ -0,0 +1,96 @@
+import { z } from 'zod';
+import { API_OPERATIONS } from '../catalog/api.generated.js';
+import { searchOperations, describeOperation } from '../catalog/search.js';
+import { request, redact } from '../transport/http.js';
+import { text } from '../mcp/response.js';
+/**
+ * Pick the credential a path needs.
+ *
+ * `siteScoped` PREFERS the API key. Both open the private surface, and the key
+ * is the narrower of the two: revocable on its own, bounded by its scopes
+ * intersected with its minter's live role, and bound to one store — while a
+ * session carries the whole account. Preferring it is also what lets a merchant
+ * connect an agent with one env var and no password.
+ */
+export function tokenFor(ctx, credential) {
+    if (credential === 'apiKey') {
+        // Naming the env var matters: the alternative is a 401 api_key_required
+        // from the platform, which reads like a permissions problem rather than an
+        // unset variable.
+        if (!ctx.apiKey) {
+            throw new Error('sbuilder: SB_TOKEN is not set — /api/v1 operations need an API key');
+        }
+        return ctx.apiKey;
+    }
+    if (credential === 'siteScoped') {
+        if (ctx.apiKey)
+            return ctx.apiKey;
+        if (ctx.session.loggedIn())
+            return ctx.session.token();
+        throw new Error('sbuilder: no credential for this site. Set SB_TOKEN to an API key from the site\'s ' +
+            'Agent app, or call sb_connect with SB_EMAIL and SB_PASSWORD.');
+    }
+    return undefined;
+}
+export async function callOperation(ctx, args) {
+    const op = API_OPERATIONS.find((o) => o.id === args.id);
+    if (!op)
+        throw new Error(`sbuilder: unknown operation "${args.id}" — use sb_api_find first`);
+    // Substitute {name} placeholders. A missing one would otherwise be sent
+    // literally, and a path containing a brace 404s with nothing to explain it.
+    let path = op.path;
+    for (const m of op.path.matchAll(/\{([^}]+)\}/g)) {
+        const name = m[1];
+        const value = args.path_params?.[name];
+        if (value === undefined) {
+            throw new Error(`sbuilder: operation ${op.id} needs path param "${name}"`);
+        }
+        path = path.replace(`{${name}}`, encodeURIComponent(value));
+    }
+    const token = tokenFor(ctx, op.credential);
+    const dryRun = args.dry_run !== false;
+    if (dryRun) {
+        return {
+            dry_run: true,
+            would_send: redact({
+                method: op.method,
+                url: ctx.base.replace(/\/$/, '') + path,
+                query: args.query,
+                Authorization: token ? `Bearer ${token}` : undefined,
+                body: args.body,
+            }),
+            note: 'Nothing was sent. Re-call with dry_run:false to execute.',
+        };
+    }
+    return request({
+        base: ctx.base,
+        method: op.method,
+        path,
+        token,
+        query: args.query,
+        body: args.body,
+        fetchImpl: ctx.fetchImpl,
+    });
+}
+export function registerApiTools(server, ctx) {
+    server.tool('sb_api_find', 'Find platform API operations by intent. Returns each match with its real parameter ' +
+        'schema, which credential it needs, and an explicit note when the document fails to ' +
+        'describe the request body. Use this before sb_api_call: the tool list is short, but ' +
+        'this index reaches all 310 operations.', {
+        query: z
+            .string()
+            .describe('What you want to do, in words: "create a menu", "list orders", "upload media"'),
+        tag: z.string().optional().describe('Narrow to one tag, e.g. "menus", "products", "theme"'),
+        limit: z.number().int().min(1).max(50).optional(),
+    }, async ({ query, tag, limit }) => text(searchOperations(query, { tag, limit }).map(describeOperation)));
+    server.tool('sb_api_call', 'Execute one operation found by sb_api_find. Defaults to a dry run that sends nothing ' +
+        'and shows the request it would have made.', {
+        id: z
+            .string()
+            .describe('Operation id from sb_api_find, e.g. "get:/api/sites/{siteID}/menus"'),
+        path_params: z.record(z.string()).optional(),
+        query: z.record(z.string()).optional(),
+        body: z.unknown().optional(),
+        dry_run: z.boolean().optional().describe('Defaults to true. Pass false to actually send.'),
+    }, async (args) => text(await callOperation(ctx, args)));
+}

package/dist/tools/context.js

@@ -0,0 +1 @@
+export {};

package/dist/tools/credentialpick.js

@@ -0,0 +1,11 @@
+import { tokenFor } from './api.js';
+/**
+ * The credential for a private, site-scoped call.
+ *
+ * A one-line re-export so `transport/` does not reach into `tools/api.ts` for
+ * the rule and quietly grow a second copy of it. There is exactly one answer to
+ * "which token opens /api/sites", and it lives in `tokenFor`.
+ */
+export function siteToken(ctx) {
+    return tokenFor(ctx, 'siteScoped');
+}

package/dist/tools/live.js

@@ -0,0 +1,104 @@
+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 { previewUrl } from '../vision/preview.js';
+import { shoot, DEFAULT_WIDTHS } from '../vision/shoot.js';
+import { RealtimeSocket } from '../transport/socket.js';
+import { LiveSession } from '../live/session.js';
+import { siteToken } from './credentialpick.js';
+import { reviewDesign, REVIEW_NOTICE } from '../domains/site/review.js';
+/**
+ * Bind a node's content to real store data.
+ *
+ * Two validations, and both close a SILENT no-op:
+ *
+ *  - the `source` must be one the renderer's scope actually provides. An unknown
+ *    one resolves to nothing and the element renders its own placeholder, which
+ *    looks exactly like "the data has not loaded yet".
+ *  - the `field` must live under `specials`. `applyBindings` (schema/src/binding.ts)
+ *    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) {
+    const node = doc.node(id);
+    if (!BINDING_SOURCES.includes(source)) {
+        throw new Error(`sbuilder: "${source}" is not a binding source the renderer provides, so the binding ` +
+            `would render as a placeholder forever. Valid sources: ${BINDING_SOURCES.join(', ')}.`);
+    }
+    const dot = field.indexOf('.');
+    if (dot < 0 || field.slice(0, dot) !== 'specials' || !field.slice(dot + 1)) {
+        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.');
+    }
+    return [
+        {
+            op: 'insert',
+            path: ['nodes', id, 'bindings'],
+            index: node.bindings.length,
+            value: { id: randomBytes(6).toString('hex'), source, field },
+        },
+    ];
+}
+export function registerLiveTools(server, ctx, session) {
+    server.tool('sb_live_join', "Join the editor's live-edit room for this site, as a visible peer. Once joined, every " +
+        'sb_add / sb_set / sb_move / sb_remove / sb_bind also goes out as a live op, so anyone ' +
+        'with the editor open watches the page assemble. Safe alongside a human: this client ' +
+        'always yields — it never answers a snapshot request and re-pulls on any divergence.', { site_id: z.string() }, async ({ site_id }) => {
+        const wsBase = ctx.base.replace(/^http/, 'ws').replace(/\/$/, '');
+        const socket = new RealtimeSocket(`${wsBase}/api/realtime/ws?site=${encodeURIComponent(site_id)}`, () => siteToken(ctx));
+        const live = new LiveSession(socket, {
+            onRemote: (patches) => session.applyRemote(patches),
+            onDesync: (reason) => session.markStale(reason),
+        });
+        socket.connect();
+        session.attachLive(live);
+        return text({
+            joined: site_id,
+            note: 'Edits now publish to the room as they are made. Call sb_page_open next.',
+        });
+    });
+    server.tool('sb_look', "Save the open page, render it through the platform's own renderer, and return " +
+        'screenshots at desktop, tablet and mobile widths — plus the measured bounding box of ' +
+        'every node. Pass node_id to frame ONE element instead of the whole page. Judge your ' +
+        'own work from these rather than guessing.', {
+        widths: z.array(z.number().int().min(320).max(2560)).optional(),
+        with_boxes: z.boolean().optional(),
+        node_id: z
+            .string()
+            .optional()
+            .describe('Frame just this node instead of the whole page — how a designer looks at one card'),
+    }, async ({ widths, with_boxes, node_id }) => {
+        await session.save();
+        const { siteId, pageId } = session.location();
+        const url = await previewUrl(ctx, siteId, pageId);
+        const shots = await shoot(url, { widths: widths ?? DEFAULT_WIDTHS, node: node_id });
+        // The boxes feed the presence cursor as well as the agent's own reading.
+        session.noteBoxes(shots[0]?.boxes ?? []);
+        // The findings ride WITH the picture. Judging a page by eye and judging it
+        // by rule are the same act, and separating them is how the second one gets
+        // skipped.
+        const findings = reviewDesign(session.current());
+        return images(shots.map((s) => ({ dataBase64: s.pngBase64 })), {
+            widths: shots.map((s) => s.width),
+            ...(node_id ? { framed: node_id } : {}),
+            ...(with_boxes === false ? {} : { boxes: shots[0]?.boxes ?? [] }),
+            ...(findings.length > 0 ? { findings, findings_notice: REVIEW_NOTICE } : {}),
+        });
+    });
+    server.tool('sb_bind', "Bind a node's content to real store data, so the page shows actual products rather than " +
+        'placeholder text.', {
+        id: z.string(),
+        source: z.string().describe(`One of: ${BINDING_SOURCES.join(', ')}`),
+        field: z.string().describe('Where the value lands, always "specials.<key>"'),
+        dry_run: z.boolean().optional(),
+    }, async ({ id, source, field, dry_run }) => {
+        const d = session.current();
+        const patches = bindNode(d, id, source, field);
+        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 });
+    });
+}