Developers / Throttle Builder

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.

Install
npm install @usethrottle/builder-schema

The page document

A 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.

NodeHoldsNotes
section1 to 6 columnsProps: width (boxed or full), contentWidth (600 to 1600), gap, paddingX, paddingY, minHeight, verticalAlign, background, stackOrder, hidden, anchor.
columnWidgets and inner sectionsProps: width (a percent from 10 to 100, at most 2 decimals), verticalAlign, padding, background, hidden, anchor. Desktop widths add up to 100.
saved-sectionNothing (a reference)Root only: ref is the ULID of a saved-section document. See Saved sections.
inner-section1 to 6 inner columns of widgetsGoes inside a top-level column only, never inside another inner section.
widgetNothingtype (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:name or #rrggbb (or with alpha). Spacing is a token (none xs s m l xl 2xl) or a number of pixels.
  • An anchor starts 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

Validate
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

applyOps
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
OperationFields
insertparentId (root or a node id), index, node
removeid
moveid, parentId, index
setPropsid, props
setResponsiveid, device (tablet or phone), props
setColumnssectionId, widths, device?, moveChildrenTo?, newIds?
setDataid, name, binding (or null to remove)
upgradeNodeid, 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

LimitValue
Document size512 KB
Nodes in a document2,000
Sections in a document (a saved-section reference counts as one)200
Saved sections in a site200
Code widget script / markup / CSS64 KB / 20 KB / 10 KB
Columns in a section1 to 6
Children in a column100
Text in one value20,000 characters
Pages in a site500
Slots in a site20
Named menusheader and footer, plus up to 10 more
Menu depth / items in a menu3 / 60
Versions kept per document100
Operations in one agent batch500

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

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, editorial or bold); while customized is 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. radius is 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 optional startsAt and endsAt.
  • seo: the title template ({page} and {store}), the default description and the default share image.
  • routes.page is 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; see pagePath in the rendering docs).
  • locales, strings (wording per locale), connections.throttlePublishableKey and storeUrl.

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.

A reference node
{ "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.

PropApplies toValues and default
interactionSection, inner sectionnone (default), tabs, accordion, carousel, toggle
carouselAutoplaySection, inner sectionfalse
carouselIntervalMsSection, inner section3000 to 15000, default 5000
carouselLoopSection, inner sectiontrue
accordionMultipleSection, inner sectionfalse
accordionOpenFirstSection, inner sectiontrue
toggleLabelOpen / toggleLabelClosedSection, inner sectionTranslatable, 120 characters at most each
toggleStartOpenSection, inner sectionfalse
panelTitleColumnTranslatable, 120 characters at most: the tab or accordion title
entranceSection, inner section, column, widgetnone (default), fade, slide-up, slide-left, zoom
entranceDelayMsSection, inner section, column, widget0 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

AreaExports
DocumentpageDocumentSchema, savedSectionDocumentSchema, emptyDocument, walkNodes, upgradeDocument, upgradeNodes, CURRENT_SCHEMA_VERSION, newNodeId, NODE_ID_RE, validateDocument
Limits and issuesLIMITS, checkLimits, zodIssues, Issue, ISSUE_CODES
ResponsiveresolveResponsive, resolveColumnWidths, wrapColumnRows
SitesiteSettingsSchema, defaultSiteSettings, SITE_FONTS, SITE_STRING_KEYS, SITE_ASSET_PATHS, THROTTLE_PK_RE
WidgetscreateRegistry, BASIC_WIDGET_DEFINITIONS, COMMON_WIDGET_SETTINGS, validateSettingValue, validateWidgetProps, widgetDefinitionSchema
OperationsdocOpSchema, agentDocOpSchema, agentDocOpsSchema, AGENT_MAX_OPS, applyOps, invertOps, canPlace
Custom widgetsvalidateCustomWidget, parseTemplate, validateTemplate, sanitizeWidgetCss, sanitizeThemeCss, safeUrl
Interactions and answersINTERACTION_DEFAULTS, ENTRANCE_DEFAULTS, resolveInteraction, resolveEntrance, interactionWarnings, SavedSectionsAnswer, CodeRuntimeAnswer
Where this is used
@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.