Document schema
@usethrottle/builder-schema is the one definition of what a Builder page is. The Worker, the editor, the MCP tools and the renderer all validate with it. It is pure TypeScript plus zod 4:
no React, no I/O, no Node imports.
npm install @usethrottle/builder-schema The page document
{
"schemaVersion": 1,
"sections": [
{
"id": "sec00000001",
"type": "section",
"props": { "width": "boxed", "paddingY": "l", "background": { "color": "token:surface" } },
"responsive": { "phone": { "paddingY": "m" } },
"columns": [
{
"id": "col00000001",
"type": "column",
"props": { "width": 60 },
"responsive": { "phone": { "width": 100 } },
"children": [
{ "id": "wid00000001", "type": "basic.heading", "v": 1,
"props": { "text": { "en": "New arrivals" }, "level": "h2" } },
{ "id": "wid00000002", "type": "catalog.product-grid", "v": 1,
"props": { "columnsDesktop": 4 },
"responsive": { "phone": { "columnsMobile": 2 } },
"data": { "products": { "source": "catalog.products", "params": { "source": "newest", "limit": 8 } } } }
]
},
{
"id": "col00000002",
"type": "column",
"props": { "width": 40 },
"responsive": { "phone": { "width": 100 } },
"children": [
{ "id": "wid00000003", "type": "basic.button", "v": 1,
"props": { "label": { "en": "Shop all" }, "link": { "kind": "url", "href": "/shop" } } }
]
}
]
}
]
}
A document is { schemaVersion: 1, sections, customWidgets?, assets? } (a section in sections may be a saved-section reference). The last two appear only in a published snapshot: the frozen custom widgets and the frozen media assets the page uses.
The header, the footer and each slot are documents of the same shape.
| Node | Holds | Notes |
|---|---|---|
section | 1 to 6 columns | Props: width (boxed or full), contentWidth (600 to 1600), gap, paddingX, paddingY, minHeight, verticalAlign, background, stackOrder, hidden, anchor. |
column | Widgets and inner sections | Props: width (a percent from 10 to 100, at most 2 decimals), verticalAlign, padding, background, hidden, anchor. Desktop widths add up to 100. |
saved-section | Nothing (a reference) | Root only: ref is the ULID of a saved-section document. See Saved sections. |
inner-section | 1 to 6 inner columns of widgets | Goes inside a top-level column only, never inside another inner section. |
| widget | Nothing | type (basic., catalog., commerce. or custom.), v, props, optional responsive and data. |
- A node id is 8 to 24 lower-case letters and digits, unique in the document.
- Every object is
strict: an unknown key is an error, and prototype names (__proto__,constructor,prototype) are refused anywhere in props, params or overrides. - A colour is
token:nameor#rrggbb(or with alpha). Spacing is a token (none xs s m l xl 2xl) or a number of pixels. - An
anchorstarts with a letter and uses letters, digits,-and_(64 at most). - A setting value is a string, number, boolean, null, a list or a map of those. A translatable text is a map of locale tag to text.
Responsive overrides
A node's props are the desktop values. responsive.tablet and responsive.phone hold sparse overrides. Desktop is 1025 pixels and wider, tablet 768 to 1024, phone 767 and narrower.
Tablet inherits desktop, and phone inherits tablet. In an override, null means no override here: inherit again. A setting can therefore never be overridden to null.
A tablet or phone width override must set every column of its section, or none.
Data bindings
A widget's data maps each input name to a binding: { source: "catalog.products", params } for a source, or { source: "context.product" } (no params) for what the slot it sits in knows.
An unknown source is SOURCE_NOT_ENABLED, and a source whose result type the input does not accept is RESULT_TYPE_MISMATCH. Money in a source's answer is { amount, currency, display }; show display.
Validating and upgrading
import { pageDocumentSchema, checkLimits, upgradeDocument, CURRENT_SCHEMA_VERSION } from '@usethrottle/builder-schema';
const parsed = pageDocumentSchema.safeParse(input); // shape, ids, column widths
if (!parsed.success) return parsed.error.issues;
const over = checkLimits(parsed.data); // size, nodes, sections, text length
const older = upgradeDocument(olderDocument); // { ok: true, doc } | { ok: false, issues }
An issue is { path, code, message } (at most 50 per answer). CURRENT_SCHEMA_VERSION is 1. A client upgrades an older document and refuses a newer one. validateDocument checks a document against a widget registry (createRegistry), which is how the Worker knows a widget, its settings and its sources exist.
Edit operations
import { agentDocOpsSchema, applyOps, AGENT_MAX_OPS } from '@usethrottle/builder-schema';
const ops = agentDocOpsSchema.parse([
{ op: 'setProps', id: 'wid00000001', props: { level: 'h3' } },
{ op: 'setResponsive', id: 'wid00000002', device: 'phone', props: { columnsMobile: 1 } },
]);
const result = applyOps(document, ops, context); // atomic: every op applies, or nothing changes and issues says why | Operation | Fields |
|---|---|
insert | parentId (root or a node id), index, node |
remove | id |
move | id, parentId, index |
setProps | id, props |
setResponsive | id, device (tablet or phone), props |
setColumns | sectionId, widths, device?, moveChildrenTo?, newIds? |
setData | id, name, binding (or null to remove) |
upgradeNode | id, toV |
The MCP apply_ops tool takes exactly these (agentDocOpsSchema, 1 to 500 operations, atomic). The editor's own schema also allows replaceDocument and the restore form of upgradeNode; both are refused for an agent, and an agent upgrades forward only. invertOps returns the batch that undoes one. The undo contract is deep equality, not byte equality.
Limits
| Limit | Value |
|---|---|
| Document size | 512 KB |
| Nodes in a document | 2,000 |
| Sections in a document (a saved-section reference counts as one) | 200 |
| Saved sections in a site | 200 |
| Code widget script / markup / CSS | 64 KB / 20 KB / 10 KB |
| Columns in a section | 1 to 6 |
| Children in a column | 100 |
| Text in one value | 20,000 characters |
| Pages in a site | 500 |
| Slots in a site | 20 |
| Named menus | header and footer, plus up to 10 more |
| Menu depth / items in a menu | 3 / 60 |
| Versions kept per document | 100 |
| Operations in one agent batch | 500 |
An editor autosaves after 800 ms of quiet and at least every 3 seconds. A preview link lasts one hour. The widget limits are on the Widget API page.
Site settings
{
"schemaVersion": 1,
"brand": { "storeName": "Meridian", "logo": { "light": "<asset id>", "dark": null }, "favicon": null },
"theme": { "preset": "clean", "customized": false, "radius": 8, "spacingScale": "comfortable", "colorScheme": "auto" },
"menus": { "header": [], "footer": [] },
"announcement": { "enabled": false, "message": {}, "target": null, "startsAt": null, "endsAt": null },
"seo": { "titleTemplate": "{page} – {store}", "defaultDescription": {}, "shareImage": null },
"routes": { "page": "/pages/{handle}", "home": "/" },
"locales": { "default": "en", "list": ["en"] },
"storeUrl": null
} brand: store name, light and dark logo and favicon, as media asset ids.-
theme: a preset (clean,editorialorbold); whilecustomizedis false the preset's tokens apply, and when true the store's own light and dark palettes do. Fonts for heading, body and mono come from a fixed list.radiusis 0 to 32, and the spacing scale is compact, comfortable or roomy. menus: named menus of items (a label per locale and a target: a page, a URL, or a catalog category, collection, product or search).announcement: the bar, with an on/off switch and an optionalstartsAtandendsAt.seo: the title template ({page}and{store}), the default description and the default share image.routes.pageis where Builder pages live in the store (/pages/{handle}by default). The Builder calls its home page/, and the store decides where to serve it (by default/pages/home; seepagePathin the rendering docs).locales,strings(wording per locale),connections.throttlePublishableKeyandstoreUrl.
The read API answers settings resolved for one locale, so a localized value is a string there, not a map.
Saved sections
A saved section is a document of its own, so many pages can share one section. A page uses it through a reference node, which is allowed at the root of a document only and counts as one section.
A reference inside a column is SAVED_SECTION_ROOT_ONLY.
{ "id": "promo0000000001", "type": "saved-section", "ref": "01HZX3K8Q9T5V7W2N4M6P8R0AB", "props": { "hidden": false, "anchor": "promo" } } ref is the ULID of the saved-section document. That document is a page document with exactly one section and no reference (savedSectionDocumentSchema;
anything else is SAVED_SECTION_ONE_SECTION). A site holds up to 200 saved sections (LIMITS.savedSectionsPerSite). insert, remove,
move and setProps (hidden and anchor only) work on a reference like on a section, and it is never wrapped.
The Worker answers the renderer with SavedSectionsAnswer, and CodeRuntimeAnswer says whether the store runs code widgets.
Interactions and entrance animation
A section or inner section can turn its columns (1 to 6) into panels. Set interaction to none (the default), tabs, accordion,
carousel or toggle. Like every section prop it can differ per device, and resolves phone, then tablet, then desktop.
| Prop | Applies to | Values and default |
|---|---|---|
interaction | Section, inner section | none (default), tabs, accordion, carousel, toggle |
carouselAutoplay | Section, inner section | false |
carouselIntervalMs | Section, inner section | 3000 to 15000, default 5000 |
carouselLoop | Section, inner section | true |
accordionMultiple | Section, inner section | false |
accordionOpenFirst | Section, inner section | true |
toggleLabelOpen / toggleLabelClosed | Section, inner section | Translatable, 120 characters at most each |
toggleStartOpen | Section, inner section | false |
panelTitle | Column | Translatable, 120 characters at most: the tab or accordion title |
entrance | Section, inner section, column, widget | none (default), fade, slide-up, slide-left, zoom |
entranceDelayMs | Section, inner section, column, widget | 0 to 2000, default 0 |
A tabs or accordion column without a panelTitle is valid; the renderer falls back to its number. interactionWarnings(doc) returns a PANEL_TITLE_MISSING issue for each one.
The package exports the defaults (INTERACTION_DEFAULTS, ENTRANCE_DEFAULTS) and resolveInteraction and resolveEntrance for a device.
The widget-level entrance props are accepted on every widget; widget definitions list them once the renderer draws them.
Countdown
basic.countdown (COUNTDOWN_WIDGET_DEFINITION) counts down to target, a new datetime setting control that takes an ISO 8601 instant with an offset, such as 2026-12-24T18:00:00+01:00.
Its settings are showDays, showHours, showMinutes and showSeconds (all true), translatable labelDays to labelSeconds,
a translatable expiredText, expiredBehavior (text or hide), align, size and color.
It joins BASIC_WIDGET_DEFINITIONS in a later release, together with the renderer that draws it.
Custom CSS and code widgets
theme.customCss is the store's own CSS: a string of at most 20,000 characters, empty by default, so older settings parse unchanged. It goes through the same CSS sanitizer as a custom widget's CSS
(no url(, no @import, only allow-listed properties), and the renderer scopes it under [data-b-root] (sanitizeThemeCss).
A custom widget of kind: "code" carries html (20 KB at most, the template markup allow-list: no script element and no on* attribute),
css (10 KB, the CSS sanitizer) and js (64 KB). A field over its limit is CODE_TOO_LARGE. The package does not parse the script: the Worker checks its syntax.
A published snapshot never holds the script: it keeps jsHash, the sha256 of the script in hex, and a code widget that is switched off is { kind, type, v, disabled: true }.
Stores only run code widgets when the merchant has switched code on for the site.
What the package exports
| Area | Exports |
|---|---|
| Document | pageDocumentSchema, savedSectionDocumentSchema, emptyDocument, walkNodes, upgradeDocument, upgradeNodes, CURRENT_SCHEMA_VERSION, newNodeId, NODE_ID_RE, validateDocument |
| Limits and issues | LIMITS, checkLimits, zodIssues, Issue, ISSUE_CODES |
| Responsive | resolveResponsive, resolveColumnWidths, wrapColumnRows |
| Site | siteSettingsSchema, defaultSiteSettings, SITE_FONTS, SITE_STRING_KEYS, SITE_ASSET_PATHS, THROTTLE_PK_RE |
| Widgets | createRegistry, BASIC_WIDGET_DEFINITIONS, COMMON_WIDGET_SETTINGS, validateSettingValue, validateWidgetProps, widgetDefinitionSchema |
| Operations | docOpSchema, agentDocOpSchema, agentDocOpsSchema, AGENT_MAX_OPS, applyOps, invertOps, canPlace |
| Custom widgets | validateCustomWidget, parseTemplate, validateTemplate, sanitizeWidgetCss, sanitizeThemeCss, safeUrl |
| Interactions and answers | INTERACTION_DEFAULTS, ENTRANCE_DEFAULTS, resolveInteraction, resolveEntrance, interactionWarnings, SavedSectionsAnswer, CodeRuntimeAnswer |
@usethrottle/builder reads documents with it, @usethrottle/builder-react renders them, and the Builder's MCP and Widget API check every write with it. See the Builder overview.