sbuilder-mcp 0.1.0

package/dist/tools/page.js

@@ -0,0 +1,383 @@
+import { z } from 'zod';
+import { text } from '../mcp/response.js';
+import { loadSource, saveSource } from '../transport/pages.js';
+import { PageDoc } from '../domains/site/document.js';
+import { addSubtree, setKeys, moveNode, removeNode, duplicateNode, } from '../domains/site/builder.js';
+import { request } from '../transport/http.js';
+import { siteToken } from './credentialpick.js';
+import { validateForSave } from '../domains/site/validate.js';
+import { reviewDesign, REVIEW_NOTICE } from '../domains/site/review.js';
+import { globalWarning, RESPONSIVE_NOTICE } from '../domains/site/traps.js';
+import { ELEMENTS, TRAIT_WRITES } from '../catalog/elements.generated.js';
+/**
+ * Findings, in the shape every surface returns them.
+ *
+ * Spread rather than repeated: three tools attach this, and three hand-written
+ * copies of a directive is how one of them quietly loses it.
+ */
+function reviewField(doc) {
+    const findings = reviewDesign(doc);
+    return findings.length > 0 ? { findings, findings_notice: REVIEW_NOTICE } : {};
+}
+/**
+ * The one open page.
+ *
+ * The write tools share it rather than each re-fetching: a fetch per edit would
+ * discard local work on every call, and would turn one hero section into forty
+ * round trips.
+ */
+export class PageSession {
+    ctx;
+    doc = null;
+    siteId = '';
+    pageId = '';
+    live = null;
+    stale = null;
+    boxes = [];
+    constructor(ctx) {
+        this.ctx = ctx;
+    }
+    attachLive(live) {
+        this.live = live;
+    }
+    location() {
+        this.current();
+        return { siteId: this.siteId, pageId: this.pageId };
+    }
+    /** Remember where each node landed, so the presence cursor can be honest. */
+    noteBoxes(boxes) {
+        this.boxes = boxes;
+    }
+    /**
+     * Apply MY patches and, when joined to a room, put them on the wire.
+     *
+     * ONE method rather than two calls at every site, because "applied locally and
+     * forgot to publish" is invisible: this session's document is right, the save
+     * is right, and only the humans watching see nothing happen.
+     */
+    applyAndPublish(patches) {
+        const d = this.current();
+        d.apply(patches);
+        this.live?.publish(patches);
+        // Move the cursor to what was just touched, but ONLY when a real
+        // measurement exists. Presence with a made-up coordinate is theatre;
+        // presence with a measured one is information.
+        const touched = String(patches[0]?.path[1] ?? '');
+        const box = this.boxes.find((b) => b.id === touched);
+        if (box && this.live) {
+            this.live.select(touched);
+            this.live.cursor(box.x + box.w / 2, box.y + box.h / 2);
+        }
+    }
+    applyRemote(patches) {
+        this.doc?.apply(patches);
+    }
+    /** The yield rule's local half: the next save re-pulls instead of overwriting. */
+    markStale(reason) {
+        this.stale = reason;
+    }
+    async open(siteId, pageId) {
+        const src = await loadSource(this.ctx, siteId, pageId);
+        this.doc = PageDoc.from(src.document);
+        this.siteId = siteId;
+        this.pageId = pageId;
+        return this.doc.outline();
+    }
+    current() {
+        if (!this.doc)
+            throw new Error('sbuilder: no page is open — call sb_page_open first');
+        return this.doc;
+    }
+    /**
+     * Validate, then save.
+     *
+     * The validation is not belt-and-braces. The platform refuses a band-order
+     * violation or a broken tree on EVERY save, and learning that from a 409 one
+     * autosave later means the agent has spent the interval editing a tree nobody
+     * will ever store.
+     */
+    async save() {
+        if (this.stale) {
+            // THE YIELD RULE. The room moved in a way this client cannot reconcile, so
+            // it must not write its copy over whatever is there now. Re-pull, and make
+            // the caller redo the intent against the current tree — loudly, because a
+            // silently dropped edit is the outcome this whole rule exists to prevent.
+            const reason = this.stale;
+            this.stale = null;
+            await this.open(this.siteId, this.pageId);
+            throw new Error(`sbuilder: the page changed under this session (${reason}). It has been re-loaded from ` +
+                'the server; re-read it with sb_outline and reapply your change.');
+        }
+        const d = this.current();
+        const problems = validateForSave(d);
+        if (problems.length > 0) {
+            throw new Error(`sbuilder: refusing to save — ${problems.join(' ')}`);
+        }
+        await saveSource(this.ctx, this.siteId, this.pageId, d.doc);
+    }
+}
+/**
+ * What one inspector control writes.
+ *
+ * 83 of the 372 controls declare it in the platform's trait registry. The rest
+ * live inside a Vue widget's prop closure, which is not machine-readable — so
+ * they come back named but undescribed, with the honest reason. Saying nothing
+ * would read as "this control writes nothing".
+ */
+function describeControl(key) {
+    const d = TRAIT_WRITES[key];
+    if (!d) {
+        return {
+            writes: null,
+            note: 'The platform does not declare what this control writes (its widget builds the ' +
+                'binding in Vue). Read a node that already uses it with sb_node_read, or set the ' +
+                'CSS property directly — style is open.',
+        };
+    }
+    return { label: d.label, writes: d.writes, ...(d.defaults ? { defaults: d.defaults } : {}) };
+}
+const STYLE_NOTE = 'The `style` namespace is OPEN CSS: any camelCase key becomes a CSS property ' +
+    '(schema/src/satelliteCss.ts camelToKebab), so you can set anything CSS can express, ' +
+    'whether or not a control exists for it. `config` and `specials` are NOT open — they are ' +
+    "per-element, and this element's `defaults` name the keys it actually uses.";
+const specSchema = z.lazy(() => z.object({
+    type: z.string(),
+    name: z.string().optional(),
+    style: z.record(z.unknown()).optional(),
+    config: z.record(z.unknown()).optional(),
+    specials: z.record(z.unknown()).optional(),
+    children: z.array(specSchema).optional(),
+}));
+export function registerPageTools(server, ctx) {
+    const session = new PageSession(ctx);
+    server.tool('sb_page_open', '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".', { site_id: z.string(), page_id: z.string() }, async ({ site_id, page_id }) => {
+        const outline = await session.open(site_id, page_id);
+        return text({ outline, ...reviewField(session.current()) });
+    });
+    server.tool('sb_outline', 'The open page as a compressed tree — id, type, name, child count, band, and whether a ' +
+        'node is a shared global or a site overlay. Never the raw document: a real page is ' +
+        'hundreds of KB of JSON.', { depth: z.number().int().min(1).max(6).optional() }, async ({ depth }) => text(session.current().outline({ depth })));
+    server.tool('sb_node_read', 'One node in full — style, config, specials, per-breakpoint overrides, bindings.', { id: z.string() }, async ({ id }) => {
+        const d = session.current();
+        const node = d.node(id);
+        const warn = globalWarning(d.doc, id);
+        return text({ node, ...(warn ? { warning: warn } : {}) });
+    });
+    server.tool('sb_catalog_search', "Find an element type by what you want it to do. Searches the platform's own AI hints — " +
+        'when to use each element, when not to, and what content suits it.', { query: z.string(), limit: z.number().int().min(1).max(30).optional() }, async ({ query, limit }) => {
+        const terms = query.toLowerCase().split(/[^a-z0-9]+/).filter(Boolean);
+        const scored = Object.values(ELEMENTS)
+            .map((el) => {
+            const hay = [el.type, el.label, el.category, el.description, ...el.semantics, ...el.useWhen]
+                .join(' ')
+                .toLowerCase();
+            return { el, score: terms.filter((t) => hay.includes(t)).length };
+        })
+            .filter((s) => s.score > 0)
+            .sort((a, b) => b.score - a.score || a.el.type.localeCompare(b.el.type))
+            .slice(0, limit ?? 10);
+        return text(scored.map(({ el }) => ({
+            type: el.type,
+            label: el.label,
+            category: el.category,
+            isContainer: el.isContainer,
+            isRootOnly: el.isRootOnly,
+            description: el.description,
+            useWhen: el.useWhen,
+            avoidWhen: el.avoidWhen,
+            contentTips: el.contentTips,
+        })));
+    });
+    server.tool('sb_traits_for', "This element's INSPECTOR, exactly as a person sees it: tabs, groups, and every control " +
+        'in them — with what each control writes when the platform declares it. Read this ' +
+        'before styling an element; it is the difference between designing it and guessing at it.', {
+        type: z.string(),
+        control: z.string().optional().describe('Narrow to one control, e.g. "font_size"'),
+    }, async ({ type, control }) => {
+        const el = ELEMENTS[type];
+        if (!el)
+            throw new Error(`sbuilder: unknown element "${type}" — use sb_catalog_search`);
+        if (control) {
+            if (!el.controls.includes(control)) {
+                throw new Error(`sbuilder: ${type} has no control "${control}". It has: ${el.controls.join(', ')}.`);
+            }
+            return text({ type, control, ...describeControl(control) });
+        }
+        return text({
+            type: el.type,
+            inspector: el.inspector.map((t) => ({
+                tab: t.tab,
+                groups: t.groups.map((g) => ({
+                    group: g.label,
+                    controls: g.controls.map((c) => ({ control: c, ...describeControl(c) })),
+                })),
+            })),
+            // The keys this element actually seeds. For `config` and `specials` —
+            // which, unlike `style`, are NOT open — this is the machine-readable
+            // answer to "what does this element store", and often the only one.
+            defaults: el.defaults,
+            isContainer: el.isContainer,
+            isRootOnly: el.isRootOnly,
+            childAllows: el.childAllows,
+            contentTips: el.contentTips,
+            style_is_open_css: STYLE_NOTE,
+        });
+    });
+    server.tool('sb_add', 'Add an element — or a whole NESTED subtree — under a parent. One call builds a complete ' +
+        'section: pass children rather than calling this once per node.', {
+        parent_id: z.string(),
+        spec: specSchema,
+        index: z.number().int().min(0).optional(),
+        dry_run: z.boolean().optional(),
+    }, async ({ parent_id, spec, index, dry_run }) => {
+        const d = session.current();
+        const { patches, ids } = addSubtree(d, parent_id, spec, index);
+        if (dry_run !== false) {
+            return text({ dry_run: true, would_add: ids.length, patches: patches.length });
+        }
+        session.applyAndPublish(patches);
+        await session.save();
+        return text({ added: ids, rev: d.rev });
+    });
+    server.tool('sb_set', 'Write style, config or specials keys on a node. Style and config are written PER ' +
+        'BREAKPOINT by default — a visual quantity written at base vanishes on publish.', {
+        id: z.string(),
+        namespace: z.enum(['style', 'config', 'specials']),
+        keys: z.record(z.unknown()),
+        breakpoint: z.enum(['desktop', 'laptop', 'tablet', 'mobile']).optional(),
+        base: z.boolean().optional(),
+        state: z.string().optional().describe('An interaction state, e.g. "hover"'),
+        dry_run: z.boolean().optional(),
+    }, async ({ id, namespace, keys, breakpoint, base, state, dry_run }) => {
+        const d = session.current();
+        const patches = setKeys(d, id, keys, {
+            namespace,
+            breakpoint: breakpoint,
+            base,
+            state,
+        });
+        if (dry_run !== false)
+            return text({ dry_run: true, patches, note: RESPONSIVE_NOTICE });
+        session.applyAndPublish(patches);
+        await session.save();
+        const warn = globalWarning(d.doc, id);
+        return text({ set: Object.keys(keys), rev: d.rev, ...(warn ? { warning: warn } : {}) });
+    });
+    server.tool('sb_move', 'Move a node to another parent at an index.', {
+        id: z.string(),
+        parent_id: z.string(),
+        index: z.number().int().min(0),
+        dry_run: z.boolean().optional(),
+    }, async ({ id, parent_id, index, dry_run }) => {
+        const d = session.current();
+        const patches = moveNode(d, id, parent_id, index);
+        if (dry_run !== false)
+            return text({ dry_run: true, patches });
+        session.applyAndPublish(patches);
+        await session.save();
+        return text({ moved: id, rev: d.rev });
+    });
+    server.tool('sb_remove', 'Remove a node and its whole subtree.', { id: z.string(), dry_run: z.boolean().optional() }, async ({ id, dry_run }) => {
+        const d = session.current();
+        const patches = removeNode(d, id);
+        if (dry_run !== false)
+            return text({ dry_run: true, removing: patches.length });
+        session.applyAndPublish(patches);
+        await session.save();
+        return text({ removed: id, rev: d.rev });
+    });
+    server.tool('sb_review', 'Everything wrong with the open page that a VISITOR would see — a blank band, a ' +
+        'placeholder sentence the author never replaced, an image with no source, a binding ' +
+        'that will never resolve. Distinct from whether the page saves: a perfectly storable ' +
+        'document can publish as an empty box. Run it before you call a page finished.', {}, async () => {
+        const findings = reviewDesign(session.current());
+        return text(findings.length === 0
+            ? { findings: [], verdict: 'Nothing a visitor would notice.' }
+            : { findings, findings_notice: REVIEW_NOTICE });
+    });
+    server.tool('sb_duplicate', 'Copy a node and everything under it, under fresh ids, right after the original. The ' +
+        'move a designer makes constantly — build one card, duplicate it twice.', { id: z.string(), dry_run: z.boolean().optional() }, async ({ id, dry_run }) => {
+        const d = session.current();
+        const { patches, ids } = duplicateNode(d, id);
+        if (dry_run !== false)
+            return text({ dry_run: true, would_copy: ids.length });
+        session.applyAndPublish(patches);
+        await session.save();
+        return text({ duplicated: id, into: ids[0], nodes: ids.length, rev: d.rev });
+    });
+    server.tool('sb_templates', "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.', { site_id: z.string() }, async ({ site_id }) => text(await request({
+        base: ctx.base,
+        method: 'GET',
+        path: `/api/sites/${encodeURIComponent(site_id)}/section-templates`,
+        token: siteToken(ctx),
+        fetchImpl: ctx.fetchImpl,
+    })));
+    server.tool('sb_template_use', '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.', {
+        site_id: z.string(),
+        template_id: z.string(),
+        page_id: z.string(),
+        dry_run: z.boolean().optional(),
+    }, async ({ site_id, template_id, page_id, dry_run }) => {
+        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 } });
+        }
+        const out = await request({
+            base: ctx.base,
+            method: 'POST',
+            path,
+            token: siteToken(ctx),
+            body: { pageId: page_id },
+            fetchImpl: ctx.fetchImpl,
+        });
+        return text({
+            instantiated: template_id,
+            into: page_id,
+            result: out,
+            note: 'Re-open the page with sb_page_open — this session still holds the old tree.',
+        });
+    });
+    server.tool('sb_page_list', "Every page on the site, with its slug and whether it is live.", { site_id: z.string() }, async ({ site_id }) => text(await request({
+        base: ctx.base,
+        method: 'GET',
+        path: `/api/sites/${encodeURIComponent(site_id)}/pages`,
+        token: siteToken(ctx),
+        fetchImpl: ctx.fetchImpl,
+    })));
+    server.tool('sb_page_create', 'Create a page. It arrives empty; sb_page_open seeds its ROOT so you can build into it.', {
+        site_id: z.string(),
+        name: z.string(),
+        settings: z.record(z.unknown()).optional(),
+        dry_run: z.boolean().optional(),
+    }, async ({ site_id, name, settings, dry_run }) => {
+        const path = `/api/sites/${encodeURIComponent(site_id)}/pages`;
+        if (dry_run !== false)
+            return text({ dry_run: true, would_post: path, body: { name, settings } });
+        return text(await request({
+            base: ctx.base,
+            method: 'POST',
+            path,
+            token: siteToken(ctx),
+            body: { name, ...(settings ? { settings } : {}) },
+            fetchImpl: ctx.fetchImpl,
+        }));
+    });
+    server.tool('sb_publish', '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.', { site_id: z.string(), page_id: z.string(), dry_run: z.boolean().optional() }, async ({ site_id, page_id, dry_run }) => {
+        const path = `/api/sites/${encodeURIComponent(site_id)}/pages/${encodeURIComponent(page_id)}/publish`;
+        if (dry_run !== false)
+            return text({ dry_run: true, would_post: path });
+        return text(await request({
+            base: ctx.base,
+            method: 'POST',
+            path,
+            token: siteToken(ctx),
+            fetchImpl: ctx.fetchImpl,
+        }));
+    });
+    return session;
+}

package/dist/tools/session.js

@@ -0,0 +1,72 @@
+import { z } from 'zod';
+import { request } from '../transport/http.js';
+import { text } from '../mcp/response.js';
+import { API_OPERATIONS } from '../catalog/api.generated.js';
+/**
+ * Log in and report what this server can actually reach.
+ *
+ * A missing API key is REPORTED, not thrown. The session half of the surface —
+ * pages, menus, theme, overlays, forms, settings — works without one, and
+ * failing the whole connect over it would hide that from a caller who does not
+ * need /api/v1 at all.
+ */
+export async function connect(ctx, args) {
+    const email = args.email ?? process.env.SB_EMAIL;
+    const password = args.password ?? process.env.SB_PASSWORD;
+    // KEY-ONLY MODE. An API key from the site's Agent app opens both surfaces on
+    // its own, which is the whole point of the connect button: one env var, no
+    // password anywhere. There is no login to do and no site list to fetch — a key
+    // belongs to exactly one store, and `GET /api/sites` means "this human's
+    // account", which a key deliberately cannot answer.
+    if (ctx.apiKey && (!email || !password)) {
+        return {
+            user: 'api key',
+            sites: [],
+            api_key: 'present',
+            operations: API_OPERATIONS.length,
+            note: 'Connected with an API key alone. It is bound to one site, so there is no site list — ' +
+                'pass that site id to sb_page_open. Set SB_EMAIL and SB_PASSWORD as well if you want ' +
+                'account-level calls (listing sites, members, roles), which a key cannot make.',
+        };
+    }
+    if (!email || !password) {
+        throw new Error('sbuilder: set SB_TOKEN to an API key from the site\'s Agent app, or set SB_EMAIL and ' +
+            'SB_PASSWORD for a full account session.');
+    }
+    await ctx.session.login(email, password);
+    const listed = (await request({
+        base: ctx.base,
+        method: 'GET',
+        path: '/api/sites',
+        token: ctx.session.token(),
+        fetchImpl: ctx.fetchImpl,
+    }));
+    const result = {
+        user: ctx.session.userName,
+        // The key is absent when the account owns no sites; a nil slice would have
+        // marshalled to null, which is why the platform's own list contract exists.
+        sites: (listed?.sites ?? []).map((s) => ({ id: s.id, name: s.name })),
+        api_key: ctx.apiKey ? 'present' : 'missing',
+        operations: API_OPERATIONS.length,
+    };
+    if (!ctx.apiKey) {
+        result.note =
+            'SB_TOKEN is not set, so /api/v1 operations (products, orders, customers, media, blog, ' +
+                'webhooks) will be refused with api_key_required. The private site API is unaffected.';
+    }
+    return result;
+}
+export function registerSessionTools(server, ctx) {
+    server.tool('sb_connect', 'Log in and list the sites this account can operate. Call this first. Reads SB_EMAIL and ' +
+        'SB_PASSWORD from the environment unless you pass them.', {
+        email: z.string().optional(),
+        password: z.string().optional(),
+    }, async (args) => text(await connect(ctx, args)));
+    server.tool('sb_site_list', 'List the sites this account can operate.', {}, async () => text(await request({
+        base: ctx.base,
+        method: 'GET',
+        path: '/api/sites',
+        token: ctx.session.token(),
+        fetchImpl: ctx.fetchImpl,
+    })));
+}

package/dist/transport/auth.js

@@ -0,0 +1,61 @@
+import { request } from './http.js';
+/**
+ * A user session against the platform's private API.
+ *
+ * `token()` is a GETTER, deliberately, and every consumer must call it per use
+ * rather than capture its result. The access token lives ~15 minutes and rotates
+ * on refresh; a client holding the string it was built with replays an expired
+ * token forever, and the failure is SILENT — a rejected socket auth still fires
+ * onopen, so there is no error event and nothing in any UI. The editor shipped
+ * exactly that bug and documents the fix on its own socket (MF1). Phase 3's
+ * socket takes `() => session.token()`, which is why the getter exists now
+ * rather than when it is first needed.
+ */
+export class Session {
+    base;
+    fetchImpl;
+    access = null;
+    refreshToken = null;
+    name = '';
+    constructor(base, fetchImpl) {
+        this.base = base;
+        this.fetchImpl = fetchImpl;
+    }
+    get userName() {
+        return this.name;
+    }
+    token() {
+        if (!this.access)
+            throw new Error('sbuilder: not logged in — call sb_connect first');
+        return this.access;
+    }
+    loggedIn() {
+        return this.access !== null;
+    }
+    async login(email, password) {
+        const out = (await request({
+            base: this.base,
+            method: 'POST',
+            path: '/api/auth/login',
+            body: { email, password },
+            fetchImpl: this.fetchImpl,
+        }));
+        this.access = out.tokens.accessToken;
+        this.refreshToken = out.tokens.refreshToken;
+        this.name = out.user?.name ?? '';
+    }
+    /** Rotate. The platform issues a NEW refresh token each time; keep that one. */
+    async refresh() {
+        if (!this.refreshToken)
+            throw new Error('sbuilder: no refresh token — log in first');
+        const out = (await request({
+            base: this.base,
+            method: 'POST',
+            path: '/api/auth/refresh',
+            body: { refreshToken: this.refreshToken },
+            fetchImpl: this.fetchImpl,
+        }));
+        this.access = out.tokens.accessToken;
+        this.refreshToken = out.tokens.refreshToken;
+    }
+}

package/dist/transport/credential.js

@@ -0,0 +1,7 @@
+export function credentialFor(path) {
+    if (path.startsWith('/api/auth/'))
+        return 'none';
+    if (path === '/api/v1' || path.startsWith('/api/v1/'))
+        return 'apiKey';
+    return 'siteScoped';
+}

package/dist/transport/http.js

@@ -0,0 +1,77 @@
+export class ApiError extends Error {
+    status;
+    code;
+    constructor(status, code, message) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.name = 'ApiError';
+    }
+}
+/** Keys whose value is a credential wherever it appears. */
+const SECRET_KEYS = /^(authorization|token|access_?token|refresh_?token|password|secret|api_?key)$/i;
+/**
+ * Replace credential-shaped values with a marker, recursively.
+ *
+ * Every dry-run preview goes through this, so it is the only thing standing
+ * between a `dry_run` result and a bearer token sitting in a transcript. It keys
+ * off the FIELD NAME rather than the value's shape on purpose: a token format
+ * can change tomorrow, while the field name is what this repo controls.
+ */
+export function redact(value) {
+    if (Array.isArray(value))
+        return value.map(redact);
+    if (value && typeof value === 'object') {
+        const out = {};
+        for (const [k, v] of Object.entries(value)) {
+            out[k] = SECRET_KEYS.test(k) ? '[redacted]' : redact(v);
+        }
+        return out;
+    }
+    return value;
+}
+export function buildUrl(base, path, query) {
+    const url = base.replace(/\/$/, '') + path;
+    if (!query)
+        return url;
+    const qs = new URLSearchParams();
+    for (const [k, v] of Object.entries(query)) {
+        if (v !== undefined)
+            qs.set(k, String(v));
+    }
+    const s = qs.toString();
+    return s ? `${url}?${s}` : url;
+}
+export async function request(opts) {
+    const doFetch = opts.fetchImpl ?? fetch;
+    const headers = { Accept: 'application/json' };
+    if (opts.token)
+        headers.Authorization = `Bearer ${opts.token}`;
+    if (opts.body !== undefined)
+        headers['Content-Type'] = 'application/json';
+    const res = await doFetch(buildUrl(opts.base, opts.path, opts.query), {
+        method: opts.method,
+        headers,
+        body: opts.body === undefined ? undefined : JSON.stringify(opts.body),
+    });
+    const raw = await res.text();
+    let parsed = undefined;
+    if (raw) {
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch {
+            // A non-JSON body from this platform means something UPSTREAM of the app
+            // answered — a proxy, a 502 page. Say exactly that rather than guessing a
+            // code the platform never wrote.
+            if (!res.ok)
+                throw new ApiError(res.status, 'non_json_response', raw.slice(0, 400));
+            return raw;
+        }
+    }
+    if (!res.ok) {
+        const env = (parsed ?? {});
+        throw new ApiError(res.status, env.code ?? 'unknown', env.error ?? `HTTP ${res.status}`);
+    }
+    return parsed;
+}

package/dist/transport/pages.js

@@ -0,0 +1,51 @@
+import { request } from './http.js';
+import { siteToken } from '../tools/credentialpick.js';
+function sourcePath(siteId, pageId) {
+    return `/api/sites/${encodeURIComponent(siteId)}/pages/${encodeURIComponent(pageId)}/source`;
+}
+/**
+ * Read a page's DRAFT document.
+ *
+ * The response is enveloped under `source` (httpx.WriteItem), and `warnings`,
+ * `globals` and `overlays` are omitted rather than nulled when empty — so a
+ * caller must treat absence as "none" and never dereference them.
+ *
+ * What comes back is COMPOSED: global sections and site overlays have been
+ * merged onto ROOT. That is the tree to edit; the server strips the overlays
+ * back out on write.
+ */
+export async function loadSource(ctx, siteId, pageId) {
+    const out = (await request({
+        base: ctx.base,
+        method: 'GET',
+        path: sourcePath(siteId, pageId),
+        token: siteToken(ctx),
+        fetchImpl: ctx.fetchImpl,
+    }));
+    return out.source;
+}
+/**
+ * Save a page's draft document.
+ *
+ * The body is `{ document, schemaVersion }`, copied from the editor's own
+ * `saveSource` (editor/src/features/pages/api.ts:114) rather than inferred: the
+ * OpenAPI document declares NO body for this route at all, so there is nothing
+ * to derive it from and a guess would have sent `{ document }` alone.
+ * `schema_version ?? 1` mirrors the editor's fallback exactly.
+ *
+ * A rejection here is the platform refusing the TREE, not the transport failing
+ * — `band_order` is the common one — and `ApiError.code` carries which. That is
+ * why nothing is swallowed: the code is the only thing that tells an agent what
+ * to fix.
+ */
+export async function saveSource(ctx, siteId, pageId, document) {
+    const out = (await request({
+        base: ctx.base,
+        method: 'PUT',
+        path: sourcePath(siteId, pageId),
+        token: siteToken(ctx),
+        body: { document, schemaVersion: document.schema_version ?? 1 },
+        fetchImpl: ctx.fetchImpl,
+    }));
+    return out.source;
+}