sbuilder-mcp 0.1.0

package/dist/catalog/search.js

@@ -0,0 +1,87 @@
+import { API_OPERATIONS, API_DEFINITIONS } from './api.generated.js';
+/**
+ * Term-hit scoring, weighted by field, and deliberately NOT fuzzy.
+ *
+ * The caller is a language model that can re-query with better words, so an
+ * empty list is a cheap, recoverable answer. A fuzzy ranker's failure mode is
+ * the expensive one: it returns a confident wrong operation, and the model then
+ * calls it. Ties break by id so the same query always returns the same order —
+ * a ranker whose output shuffles between calls is one nobody can debug.
+ */
+const WEIGHT = { tag: 5, path: 3, summary: 2 };
+export function searchOperations(query, opts = {}) {
+    const limit = opts.limit ?? 12;
+    const terms = query.toLowerCase().split(/[^a-z0-9]+/).filter(Boolean);
+    let pool = API_OPERATIONS;
+    if (opts.tag)
+        pool = pool.filter((o) => o.tags.includes(opts.tag));
+    if (terms.length === 0)
+        return pool.slice(0, limit);
+    const scored = [];
+    for (const op of pool) {
+        const tags = op.tags.join(' ').toLowerCase();
+        const path = op.path.toLowerCase();
+        const summary = op.summary.toLowerCase();
+        let score = 0;
+        for (const t of terms) {
+            if (tags.includes(t))
+                score += WEIGHT.tag;
+            if (path.includes(t))
+                score += WEIGHT.path;
+            if (summary.includes(t))
+                score += WEIGHT.summary;
+        }
+        if (score > 0)
+            scored.push({ op, score });
+    }
+    scored.sort((a, b) => b.score - a.score || a.op.id.localeCompare(b.op.id));
+    return scored.slice(0, limit).map((s) => s.op);
+}
+/**
+ * The full call sheet for one operation — including, deliberately, what is NOT
+ * known about it.
+ *
+ * The source document under-describes bodies in TWO different ways, and telling
+ * them apart matters because the right recovery differs:
+ *
+ *  - 58 of the 140 body-carrying operations declare a body with no `$ref`, so
+ *    the shape is unknown but its EXISTENCE is certain.
+ *  - 60 of the 137 write operations declare no body parameter at all. Some
+ *    genuinely take none (`POST /api/orgs/{id}/leave` is an action, not a
+ *    payload). Others are simply un-annotated: `PUT /pages/{id}/source` carries
+ *    a whole page document and the document says nothing about it, and
+ *    `POST /_wb/account/login` obviously takes credentials.
+ *
+ * Saying "no body" for the second group would be the silent failure — the model
+ * would send an empty PUT and wipe a page. So the two get different words.
+ */
+export function describeOperation(op) {
+    const out = {
+        id: op.id,
+        method: op.method,
+        path: op.path,
+        summary: op.summary,
+        tags: op.tags,
+        credential: op.credential,
+        params: op.params.filter((p) => p.in !== 'body'),
+    };
+    const hasBody = op.params.some((p) => p.in === 'body');
+    const isWrite = op.method === 'POST' || op.method === 'PUT' || op.method === 'PATCH';
+    if (hasBody && op.bodyDescribed && op.bodyRef) {
+        out.body_schema = API_DEFINITIONS[op.bodyRef];
+    }
+    else if (hasBody) {
+        out.body_warning =
+            'This operation takes a body, but the OpenAPI document does not describe its shape ' +
+                '(no $ref). Do NOT guess one: read an existing item with the matching GET first and ' +
+                'send back a modified copy.';
+    }
+    else if (isWrite) {
+        out.body_note =
+            'The document declares NO request body for this write operation. That may be true ' +
+                '(some endpoints are pure actions, e.g. POST /api/orgs/{id}/leave), or the annotation ' +
+                'may simply be missing — PUT /pages/{id}/source takes a whole page document and is ' +
+                'documented exactly like this. Confirm with the matching GET before sending an empty body.';
+    }
+    return out;
+}

package/dist/catalog/types.js

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

package/dist/core/patch.js

@@ -0,0 +1,110 @@
+/** Segments that must never appear in a path we apply or send. */
+const FORBIDDEN = new Set(['__proto__', 'constructor', 'prototype']);
+/**
+ * Is this path part of the shared DOCUMENT?
+ *
+ * An allowlist, not a denylist, and three rules rather than one — each closing a
+ * real door:
+ *
+ *  - `path.length < 2` also rejects the bare `['nodes']`. A write there does not
+ *    touch one node, it REPLACES THE ENTIRE MAP. No legitimate edit produces it
+ *    (every real one is `nodes.<id>.…`, at least three segments), so refusing it
+ *    costs nothing and closes a one-frame whole-document takeover.
+ *  - The path must start at `nodes`. Everything else in a store is per-viewer
+ *    state or local bookkeeping — syncing a selection would yank every peer's
+ *    cursor about.
+ *  - Segments are compared AFTER stringifying. A segment shaped `['__proto__']`
+ *    stringifies to `'__proto__'` — a one-element array becomes its single
+ *    element — so a `typeof seg === 'string'` guard lets it through and it lands
+ *    on Object.prototype anyway.
+ */
+export function isSyncablePath(path) {
+    if (!Array.isArray(path) || path.length < 2 || path[0] !== 'nodes')
+        return false;
+    return path.every((seg) => !FORBIDDEN.has(`${seg}`));
+}
+/**
+ * Is this whole patch admissible — path and, for a splice, its index?
+ *
+ * The index rule exists because a NEGATIVE index splices from the END: `remove`
+ * at -1 deletes the last child of an array the sender never named, and `insert`
+ * at -1 lands one slot in from the end of somebody else's parent. A fractional
+ * index is the same class — splice truncates it, so the write addresses a
+ * different element than the one described.
+ *
+ * An index PAST the end is deliberately allowed: splice clamps it, an append is
+ * a legitimate thing to describe, and a remove past the end removes nothing.
+ */
+export function isSyncablePatch(p) {
+    if (!isSyncablePath(p.path))
+        return false;
+    if (p.op !== 'insert' && p.op !== 'remove')
+        return true;
+    return Number.isInteger(p.index) && p.index >= 0;
+}
+/**
+ * Keep only the patches that belong on the wire.
+ *
+ * FILTERS rather than throws, unlike applyPatches below, and the asymmetry is
+ * deliberate: a peer must never be able to halt this process by sending one bad
+ * frame, while a patch WE built that fails admission is a bug in our own builder
+ * and must be loud.
+ */
+export function syncable(patches) {
+    return patches.filter(isSyncablePatch);
+}
+function parentOf(state, path) {
+    let cur = state;
+    for (let i = 0; i < path.length - 1; i++) {
+        const k = `${path[i]}`;
+        if (FORBIDDEN.has(k))
+            throw new Error(`patch: inadmissible segment "${k}"`);
+        const next = cur[k];
+        if (next === undefined || next === null || typeof next !== 'object') {
+            cur[k] = {};
+        }
+        cur = cur[k];
+    }
+    const key = `${path[path.length - 1]}`;
+    if (FORBIDDEN.has(key))
+        throw new Error(`patch: inadmissible segment "${key}"`);
+    return { holder: cur, key };
+}
+/**
+ * Apply patches left to right, in place.
+ *
+ * An inadmissible patch THROWS rather than being skipped. Skipping is right for
+ * the wire (see `syncable`), but locally a silent skip would leave the document
+ * half-edited with nothing anywhere to say so — which is the exact failure shape
+ * this whole repo exists to rule out.
+ */
+export function applyPatches(state, patches) {
+    for (const p of patches) {
+        if (!isSyncablePatch(p)) {
+            throw new Error(`patch: inadmissible patch ${JSON.stringify(p)}`);
+        }
+        const { holder, key } = parentOf(state, p.path);
+        switch (p.op) {
+            case 'set':
+                holder[key] = p.value;
+                break;
+            case 'unset':
+                delete holder[key];
+                break;
+            case 'insert': {
+                const arr = holder[key];
+                if (!Array.isArray(arr))
+                    break;
+                arr.splice(p.index, 0, p.value);
+                break;
+            }
+            case 'remove': {
+                const arr = holder[key];
+                if (!Array.isArray(arr))
+                    break;
+                arr.splice(p.index, 1);
+                break;
+            }
+        }
+    }
+}

package/dist/core/tree.js

@@ -0,0 +1,69 @@
+/** The specials stamp a composed site overlay carries. */
+export const SPEC_OVERLAY_ID = 'overlayId';
+/** The specials stamps a composed global section carries. */
+export const SPEC_GLOBAL_ID = 'globalId';
+export const SPEC_GLOBAL_KIND = 'globalKind';
+export const SPEC_GLOBAL_REF = 'globalRef';
+export function childrenOf(doc, id) {
+    return doc.nodes[id]?.data.nodes ?? [];
+}
+/**
+ * Is this node a composed SITE OVERLAY — the cart drawer, a pop-up?
+ *
+ * Two conditions, and the second is load-bearing: the node must carry the
+ * `overlayId` stamp AND be a DIRECT child of ROOT. The platform enforces exactly
+ * that on write, and it is what keeps overlays out of repeater rows, out of
+ * global sections, and out of each other — a stamp found deeper in the tree
+ * would otherwise be stored inside whatever contains it.
+ */
+export function isOverlay(doc, id) {
+    const n = doc.nodes[id];
+    if (!n || n.specials?.[SPEC_OVERLAY_ID] === undefined)
+        return false;
+    return childrenOf(doc, doc.root_node_id).includes(id);
+}
+/**
+ * ROOT's children WITHOUT the overlays — the walk every ROOT-level rule must use.
+ *
+ * A separate function from `childrenOf` on purpose. An overlay is composed onto
+ * ROOT on read and stripped on write, so it is not part of the page document at
+ * all: the band rule, drag clamping and the save check all have to skip it. A
+ * caller who writes the obvious `childrenOf(doc, doc.root_node_id)` gets that
+ * wrong SILENTLY, so the correct walk is the one with the shorter name.
+ */
+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. */
+export function walk(doc, id, visit) {
+    const seen = new Set();
+    const go = (cur) => {
+        if (seen.has(cur))
+            return;
+        seen.add(cur);
+        const n = doc.nodes[cur];
+        if (!n)
+            return;
+        visit(n);
+        for (const k of n.data.nodes)
+            go(k);
+    };
+    go(id);
+}
+export function subtreeIds(doc, id) {
+    const out = [];
+    walk(doc, id, (n) => out.push(n.id));
+    return out;
+}
+/** Ids from this node's parent up to ROOT. Cycle-safe for the same reason. */
+export function ancestors(doc, id) {
+    const out = [];
+    const seen = new Set([id]);
+    let cur = doc.nodes[id]?.data.parent ?? null;
+    while (cur && !seen.has(cur)) {
+        seen.add(cur);
+        out.push(cur);
+        cur = doc.nodes[cur]?.data.parent ?? null;
+    }
+    return out;
+}

package/dist/domains/site/builder.js

@@ -0,0 +1,224 @@
+import { isOverlay, subtreeIds, ancestors } from '../../core/tree.js';
+import { ELEMENTS } from '../../catalog/elements.generated.js';
+import { createNode } from './node.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. */
+const APPEND = Number.MAX_SAFE_INTEGER;
+function requireContainer(parentType, parentId) {
+    if (!ELEMENTS[parentType]?.isContainer) {
+        throw new Error(`sbuilder: ${parentId} is a ${parentType}, which is not a container — it cannot hold children.`);
+    }
+}
+function requireAllowed(parentType, childType) {
+    const child = ELEMENTS[childType];
+    if (!child) {
+        throw new Error(`sbuilder: unknown element "${childType}". Use sb_catalog_search to find a real one.`);
+    }
+    if (child.isRootOnly && parentType !== 'root') {
+        throw new Error(`sbuilder: ${childType} is root-only — it may only be a direct child of ROOT, not of a ${parentType}.`);
+    }
+    const allows = ELEMENTS[parentType]?.childAllows ?? [];
+    if (allows.length > 0 && !allows.includes(childType)) {
+        throw new Error(`sbuilder: a ${parentType} accepts only [${allows.join(', ')}], not ${childType}.`);
+    }
+}
+function refuseOverlay(doc, id, verb) {
+    if (!isOverlay(doc.doc, id))
+        return;
+    throw new Error(`sbuilder: ${id} is a SITE OVERLAY (the cart drawer or a pop-up). It is composed onto ROOT ` +
+        `on read and stripped out on write, so it is not part of this page document — ${verb} it ` +
+        'here would do nothing on save. Use the overlays API instead.');
+}
+/**
+ * Add a whole subtree under `parentId`, as ONE batch of patches.
+ *
+ * Nested rather than one-node-per-call because a hero section is a section, a
+ * heading, a paragraph and a button — four round trips to describe one idea, and
+ * four separate op batches for anyone watching the room. The spec is a tree; the
+ * patches come out flat in CREATION ORDER, so a peer applying them left to right
+ * never sees a child referenced before the node exists.
+ */
+export function addSubtree(doc, parentId, spec, index) {
+    const parent = doc.node(parentId);
+    requireContainer(parent.data.type, parentId);
+    requireAllowed(parent.data.type, spec.type);
+    const patches = [];
+    const ids = [];
+    const build = (s, parentNodeId) => {
+        const n = createNode(s.type, {
+            name: s.name,
+            parent: parentNodeId,
+            style: s.style,
+            config: s.config,
+            specials: s.specials,
+        });
+        patches.push({ op: 'set', path: ['nodes', n.id], value: n });
+        ids.push(n.id);
+        for (const child of s.children ?? []) {
+            requireContainer(s.type, n.id);
+            requireAllowed(s.type, child.type);
+            const childId = build(child, n.id);
+            patches.push({ op: 'insert', path: ['nodes', n.id, 'data', 'nodes'], index: APPEND, value: childId });
+        }
+        return n.id;
+    };
+    const rootId = build(spec, parentId);
+    const at = index ?? parent.data.nodes.length;
+    patches.push({ op: 'insert', path: ['nodes', parentId, 'data', 'nodes'], index: at, value: rootId });
+    return { patches, ids };
+}
+/**
+ * Write keys into a namespace.
+ *
+ * PER BREAKPOINT BY DEFAULT, and that default is the whole point. The platform's
+ * rule is that any key which CAN be responsive MUST be: a visual quantity
+ * written at base renders correctly on the canvas and then VANISHES on publish,
+ * because the published cascade has no base layer under it. An agent writing
+ * styles would otherwise ship that bug on every element it touches.
+ *
+ * `specials` needs no flag and takes no breakpoint: it is content and identity,
+ * base-only by definition.
+ */
+export function setKeys(doc, id, keys, opts) {
+    doc.node(id); // throws naming the id if it is not there
+    const { namespace } = opts;
+    if (namespace === 'specials') {
+        return Object.entries(keys).map(([k, v]) => ({
+            op: 'set',
+            path: ['nodes', id, 'specials', k],
+            value: v,
+        }));
+    }
+    if (opts.base) {
+        // Base IS legitimate, and this used to throw for anything that was not an
+        // identity key — a refusal built on a misread of the platform's responsive
+        // mandate.
+        //
+        // That mandate is about ELEMENT IMPLEMENTATION: an element whose Go renderer
+        // reads `n.Config[...]` directly (nodes.ConfigInt in html.go, an SVG width=
+        // attribute) bypasses the cascade, so a per-breakpoint value the author sets
+        // renders on the canvas and never reaches publish. It is not a rule about
+        // documents.
+        //
+        // The cascade proves it: style/cascade.go's MergeNamespace resolves a key
+        // "current slot, then wider slots, then BASE, then narrower slots" — base is
+        // the fallback layer, and it is exactly where every element's own
+        // meta.defaults.style is seeded. Refusing to write there refused a namespace
+        // the platform itself fills on every node it creates.
+        //
+        // Per-breakpoint remains the DEFAULT, because a design should respond. Base
+        // is for a value that genuinely should not vary.
+        return Object.entries(keys).map(([k, v]) => ({
+            op: 'set',
+            path: ['nodes', id, namespace, k],
+            value: v,
+        }));
+    }
+    const bp = opts.breakpoint ?? 'desktop';
+    if (opts.state) {
+        return Object.entries(keys).map(([k, v]) => ({
+            op: 'set',
+            path: ['nodes', id, 'states', opts.state, bp, namespace, k],
+            value: v,
+        }));
+    }
+    return Object.entries(keys).map(([k, v]) => ({
+        op: 'set',
+        path: ['nodes', id, 'responsive', bp, namespace, k],
+        value: v,
+    }));
+}
+/**
+ * Copy a node and everything under it, under fresh ids, beside the original.
+ *
+ * The move a designer makes constantly — build one card, duplicate it twice —
+ * and without it an agent rebuilds the subtree by hand and gets it subtly
+ * different. Ids are re-minted rather than reused: two nodes sharing an id is a
+ * document the renderer draws once and the editor cannot select.
+ *
+ * Refuses ROOT (there is nothing to put a second one beside) and an overlay
+ * (not part of this document at all).
+ */
+export function duplicateNode(doc, id) {
+    const n = doc.node(id);
+    if (id === doc.doc.root_node_id)
+        throw new Error('sbuilder: cannot duplicate ROOT');
+    refuseOverlay(doc, id, 'duplicating');
+    const parentId = n.data.parent;
+    if (!parentId || !doc.has(parentId)) {
+        throw new Error(`sbuilder: ${id} has no parent to be duplicated beside`);
+    }
+    const patches = [];
+    const ids = [];
+    // One pass, parent-first, so a child's `parent` always names an id already
+    // emitted — the same ordering rule addSubtree follows.
+    const copy = (srcId, newParent) => {
+        const src = doc.node(srcId);
+        const clone = JSON.parse(JSON.stringify(src));
+        clone.id = genId(src.data.type);
+        clone.data = { ...clone.data, parent: newParent, nodes: [] };
+        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 });
+        }
+        return clone.id;
+    };
+    const rootId = copy(id, parentId);
+    const at = doc.node(parentId).data.nodes.indexOf(id);
+    patches.push({
+        op: 'insert',
+        path: ['nodes', parentId, 'data', 'nodes'],
+        index: at < 0 ? APPEND : at + 1,
+        value: rootId,
+    });
+    return { patches, ids };
+}
+export function moveNode(doc, id, newParentId, index) {
+    const n = doc.node(id);
+    refuseOverlay(doc, id, 'moving');
+    const newParent = doc.node(newParentId);
+    // The STRUCTURAL check runs first, before the type rules, and the order is not
+    // arbitrary: a node moved inside its own subtree detaches that subtree from the
+    // document with nothing to report it — the nodes still sit in the map,
+    // reachable from nobody, and the page silently loses a section. Running the
+    // type rules first would report "flex-section is root-only" for a caller whose
+    // actual mistake was moving a node into itself, which sends them to fix the
+    // wrong thing.
+    if (newParentId === id || subtreeIds(doc.doc, id).includes(newParentId) || ancestors(doc.doc, newParentId).includes(id)) {
+        throw new Error(`sbuilder: cannot move ${id} into its own descendant ${newParentId}`);
+    }
+    requireContainer(newParent.data.type, newParentId);
+    requireAllowed(newParent.data.type, n.data.type);
+    const patches = [];
+    const oldParentId = n.data.parent;
+    if (oldParentId && doc.has(oldParentId)) {
+        const at = doc.node(oldParentId).data.nodes.indexOf(id);
+        if (at >= 0)
+            patches.push({ op: 'remove', path: ['nodes', oldParentId, 'data', 'nodes'], index: at });
+    }
+    patches.push({ op: 'insert', path: ['nodes', newParentId, 'data', 'nodes'], index, value: id });
+    patches.push({ op: 'set', path: ['nodes', id, 'data', 'parent'], value: newParentId });
+    return patches;
+}
+export function removeNode(doc, id) {
+    const n = doc.node(id);
+    if (id === doc.doc.root_node_id)
+        throw new Error('sbuilder: cannot remove ROOT');
+    refuseOverlay(doc, id, 'removing');
+    const patches = [];
+    const parentId = n.data.parent;
+    if (parentId && doc.has(parentId)) {
+        const at = doc.node(parentId).data.nodes.indexOf(id);
+        if (at >= 0)
+            patches.push({ op: 'remove', path: ['nodes', parentId, 'data', 'nodes'], index: at });
+    }
+    // Unset the whole subtree — a node left behind is an orphan the save check
+    // would reject, and the agent would never guess why.
+    for (const sub of subtreeIds(doc.doc, id)) {
+        patches.push({ op: 'unset', path: ['nodes', sub] });
+    }
+    return patches;
+}

package/dist/domains/site/document.js

@@ -0,0 +1,112 @@
+import { applyPatches } from '../../core/patch.js';
+import { childrenOf, isOverlay } from '../../core/tree.js';
+import { bandOf, isGlobal } from './traps.js';
+/**
+ * One page's document, in memory.
+ *
+ * Owns a DEEP COPY of what it was handed. The caller's object is very often a
+ * parsed HTTP response that something else still holds a reference to, and an
+ * in-place mutation there is the kind of bug that only ever shows up as "the
+ * second save wrote the first save's tree".
+ */
+export class PageDoc {
+    doc;
+    revision;
+    constructor(doc, revision = 0) {
+        this.doc = doc;
+        this.revision = revision;
+    }
+    static from(raw) {
+        if (!raw || typeof raw !== 'object' || !raw.nodes) {
+            throw new Error('sbuilder: not a page document — expected { schema_version, root_node_id, nodes }');
+        }
+        const d = JSON.parse(JSON.stringify(raw));
+        // A BRAND-NEW page comes back as {"schema_version":1,"root_node_id":"","nodes":{}}
+        // — the server's `emptyDocument`, because it treats the document as opaque
+        // JSONB and will not synthesize node shapes. Seed the same ROOT the editor's
+        // own `seedRoot` does, id and all.
+        //
+        // This used to throw, on the reasoning that healing here would race the
+        // editor's hydrate path. Running it against a live server showed the cost:
+        // an agent that had just CREATED a page could not open it, which is the
+        // first thing anyone connecting an agent does. And there is no race to lose
+        // — an empty document has nothing to disagree with, and whichever side seeds
+        // first is the tree the other then loads.
+        //
+        // The genuinely broken case is still refused below: a document that HAS
+        // nodes but whose root_node_id names none of them is damage, not emptiness,
+        // and inventing a root there would strand every existing node as an orphan.
+        if (!d.root_node_id && Object.keys(d.nodes).length === 0) {
+            d.root_node_id = 'ROOT';
+            d.nodes.ROOT = {
+                id: 'ROOT',
+                data: { type: 'root', parent: null, nodes: [] },
+                specials: {},
+                // The remaining namespaces the platform's own makeRoot writes. Spread
+                // through an index signature because NodeLike models only what the tree
+                // walk reads — the document carries more, and a node missing them is a
+                // node the renderer cannot draw.
+                ...{ style: {}, config: {}, responsive: {}, events: [], bindings: [] },
+            };
+            if (!d.schema_version)
+                d.schema_version = 2;
+        }
+        if (!d.root_node_id || !d.nodes[d.root_node_id]) {
+            throw new Error(`sbuilder: document is damaged — root_node_id=${JSON.stringify(d.root_node_id)} names no ` +
+                `node, but ${Object.keys(d.nodes).length} nodes are present. Open the page in the ` +
+                'editor once; its hydrate path repairs this.');
+        }
+        return new PageDoc(d);
+    }
+    get rev() {
+        return this.revision;
+    }
+    has(id) {
+        return this.doc.nodes[id] !== undefined;
+    }
+    node(id) {
+        const n = this.doc.nodes[id];
+        if (!n)
+            throw new Error(`sbuilder: no node "${id}" in this page`);
+        return n;
+    }
+    apply(patches) {
+        applyPatches(this.doc, patches);
+        this.revision += 1;
+    }
+    /**
+     * A compressed tree — id, type, name, child count, and the flags that change
+     * what a caller may safely do with a node.
+     *
+     * Never the document itself. A real page is hundreds of KB of JSON, and a tool
+     * that returns it burns the context the agent needs for the actual design
+     * work. Depth 1 (the default) is ROOT's children; deeper levels nest in `kids`.
+     *
+     * Overlays ARE listed, unlike in `pageChildren`: the agent needs to know the
+     * cart drawer is there. `pageChildren` is for the RULES; this is for the
+     * reader, and the `overlay: true` flag is how the two stay distinguishable.
+     */
+    outline(opts = {}) {
+        const depth = opts.depth ?? 1;
+        const line = (id, level) => {
+            const n = this.node(id);
+            const kidIds = childrenOf(this.doc, id);
+            const out = { id, type: n.data.type, children: kidIds.length };
+            if (n.data.name)
+                out.name = n.data.name;
+            if (level === 0) {
+                if (isOverlay(this.doc, id))
+                    out.overlay = true;
+                else
+                    out.band = bandOf(this.doc, id);
+            }
+            if (isGlobal(this.doc, id))
+                out.global = true;
+            if (level + 1 < depth && kidIds.length > 0) {
+                out.kids = kidIds.map((k) => line(k, level + 1));
+            }
+            return out;
+        };
+        return childrenOf(this.doc, this.doc.root_node_id).map((id) => line(id, 0));
+    }
+}

package/dist/domains/site/ids.js

@@ -0,0 +1,27 @@
+import { randomBytes } from 'node:crypto';
+/**
+ * Id prefixes, mirrored from schema/src/node.ts.
+ *
+ * Purely cosmetic — an id only has to be unique — but a document this server
+ * builds should be indistinguishable from one a human built, and the prefix is
+ * the first thing anyone reading a document sees. The tab family is listed
+ * explicitly because the generic two-letter fallback collapses all three to 'ta'.
+ */
+const PREFIXES = {
+    root: 'rt',
+    'flex-section': 'fs',
+    'flex-block': 'fb',
+    heading: 'he',
+    text: 'tx',
+    button: 'bt',
+    image: 'im',
+    icon: 'ic',
+    spacer: 'sp',
+    tab: 'tb',
+    'tab-content': 'tc',
+    'tab-item': 'ti',
+};
+export function genId(type) {
+    const prefix = PREFIXES[type] ?? (type.replace(/[^a-z]/g, '').slice(0, 2) || 'nd');
+    return `${prefix}_${randomBytes(4).toString('hex')}`;
+}

package/dist/domains/site/node.js

@@ -0,0 +1,43 @@
+import { ELEMENTS } 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. */
+function copy(v) {
+    return JSON.parse(JSON.stringify(v));
+}
+/**
+ * Mint a node seeded from its element's catalog defaults.
+ *
+ * `states` is spread in ONLY when the element declares defaults for it. A node
+ * that declares none must not carry the key at all: the platform's Go side marks
+ * it `omitempty`, so an empty object here would change the stored bytes of every
+ * document this server touches — and the render contract is byte-identical.
+ */
+export function createNode(type, opts = {}) {
+    const meta = ELEMENTS[type];
+    if (!meta) {
+        throw new Error(`sbuilder: unknown element "${type}". Use sb_catalog_search to find a real one — ` +
+            'guessing a type produces a node nothing can render.');
+    }
+    const d = meta.defaults;
+    const states = d.states;
+    return {
+        id: genId(type),
+        data: {
+            type,
+            ...(opts.name !== undefined ? { name: opts.name } : {}),
+            parent: opts.parent ?? null,
+            nodes: [],
+            isCanvas: meta.isContainer,
+            hidden: false,
+            custom: {},
+        },
+        style: { ...copy(d.style ?? {}), ...(opts.style ?? {}) },
+        config: { ...copy(d.config ?? {}), ...(opts.config ?? {}) },
+        specials: { ...copy(d.specials ?? {}), ...(opts.specials ?? {}) },
+        responsive: copy(d.responsive ?? {}),
+        ...(states ? { states: copy(states) } : {}),
+        events: [],
+        bindings: [],
+    };
+}