@usethrottle/builder-react 0.3.1 → 0.4.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.cts CHANGED
@@ -1,5 +1,5 @@
1
1
  import { ReactNode, ComponentType, CSSProperties, Context } from 'react';
2
- import { TemplateAst, WidgetNode, SettingValue, WidgetDefinition, DataSourceDescriptor, PageDocument, FrozenAsset, WidgetRegistry, CustomWidgetSnapshot, SettingField, DataBinding } from '@usethrottle/builder-schema';
2
+ import { TemplateAst, WidgetNode, SettingValue, WidgetDefinition, DataSourceDescriptor, PageDocument, FrozenAsset, SavedSectionsAnswer, CodeRuntimeAnswer, WidgetRegistry, CustomWidgetSnapshot, CodeWidgetSnapshotLive, AnyCustomWidgetSnapshot, SettingField, DataBinding, SavedSectionRefNode } from '@usethrottle/builder-schema';
3
3
  import { BuilderClient } from '@usethrottle/builder';
4
4
  export { BuilderNotFoundError, BuilderUnavailableError } from '@usethrottle/builder';
5
5
 
@@ -38,6 +38,13 @@ type WidgetRenderProps = {
38
38
  /** Resolved data by the widget's named inputs. Absent until a perShopper source has resolved in the browser. */
39
39
  data: Record<string, unknown>;
40
40
  editMode: boolean;
41
+ /** False in the editor's edit mode: draw the widget static (no ticking, no script). Absent means true. */
42
+ interactive?: boolean | undefined;
43
+ /** Set inside a per-device copy of a section: a nested renderer continues the parent's id scope (composites). */
44
+ idScope?: {
45
+ vpath: string;
46
+ dupe: boolean;
47
+ } | undefined;
41
48
  locale: string;
42
49
  /** The only origin a media `src` may be on; pass it to `AssetImage`. */
43
50
  mediaOrigin: string;
@@ -109,6 +116,10 @@ type LoadedPage = {
109
116
  initialData: DataMap;
110
117
  /** The page's other fields as the read API sent them (seo, description, ...). */
111
118
  meta: Record<string, unknown>;
119
+ /** The published saved sections the page references. */
120
+ savedSections?: SavedSectionsAnswer | undefined;
121
+ /** Whether the store runs code widgets and where their scripts come from. */
122
+ code?: CodeRuntimeAnswer | undefined;
112
123
  };
113
124
  type LoadedRedirect = {
114
125
  kind: 'redirect';
@@ -119,6 +130,10 @@ type LoadedPart = {
119
130
  document: PageDocument;
120
131
  assets: PageAssets;
121
132
  initialData: DataMap;
133
+ /** The published saved sections the document references. */
134
+ savedSections?: SavedSectionsAnswer | undefined;
135
+ /** Whether the store runs code widgets and where their scripts come from. */
136
+ code?: CodeRuntimeAnswer | undefined;
122
137
  };
123
138
  /**
124
139
  * The store's site design, read once per request. `unavailable` means the
@@ -142,6 +157,49 @@ type LoadedSite = {
142
157
  locale: string;
143
158
  };
144
159
 
160
+ /**
161
+ * The containment every custom widget sits in. The CSS sanitiser allows
162
+ * `transform`, `translate`, `scale` and negative margins (spec §10.3), so
163
+ * without a box a widget could paint over, and take clicks from, a store's own
164
+ * button. `contain: paint` and `overflow: clip` stop anything it draws at its
165
+ * edge, and `isolation: isolate` keeps its stacking inside. Widget CSS is
166
+ * scoped to descendants of the wrapper (`[data-b-w] .x`), so it can never
167
+ * restyle the wrapper itself; the declarations are also inline, which beats any
168
+ * stylesheet.
169
+ */
170
+ declare const CUSTOM_WIDGET_CONTAINMENT: CSSProperties;
171
+ type NodePart = 'section' | 'column' | 'widget';
172
+ type NodeWrapperProps = {
173
+ id: string;
174
+ part: NodePart;
175
+ /** The widget type; sections and columns have none. */
176
+ type?: string;
177
+ as?: 'div' | 'section';
178
+ className: string;
179
+ anchor?: string | undefined;
180
+ /** The anchor name of a per-device copy: `data-b-anchor`, which the runtime scrolls to when `#name` points at a hidden copy. */
181
+ copyAnchor?: string | undefined;
182
+ /** A custom widget: it gets the containment box and `data-b-w`, the scope of its CSS. */
183
+ custom?: boolean;
184
+ missing?: boolean;
185
+ /** Extra `data-b-*` attributes of the element (a code widget's `data-b-code`). */
186
+ attributes?: Record<`data-b-${string}`, string> | undefined;
187
+ /** Hooks of the editor canvas, or undefined on a store. */
188
+ edit?: EditModeHooks | undefined;
189
+ /** Entrance animation (agent v2): `data-b-entrance` and the delay, animated by the interactions runtime. */
190
+ entrance?: {
191
+ name: string;
192
+ delayMs: number;
193
+ } | undefined;
194
+ children?: ReactNode;
195
+ };
196
+ /**
197
+ * One element per node: it carries `data-b-id` (what the compiled CSS is scoped
198
+ * by) and `data-throttle-part`, and in the editor the select and hover hooks.
199
+ * Links inside it are inert in the editor.
200
+ */
201
+ declare function NodeWrapper(props: NodeWrapperProps): ReactNode;
202
+
145
203
  /**
146
204
  * The definitions of the schema registry plus what only the renderer has: the
147
205
  * component of each widget and the resolver of each data source.
@@ -151,7 +209,7 @@ interface RendererRegistry extends WidgetRegistry {
151
209
  component(node: WidgetNode): ComponentType<WidgetRenderProps> | undefined;
152
210
  resolver(sourceId: string): DataSourceResolver | undefined;
153
211
  /** The same registry with a published document's frozen custom widgets added. */
154
- withCustom(snapshots: readonly CustomWidgetSnapshot[]): RendererRegistry;
212
+ withCustom(snapshots: readonly (CustomWidgetSnapshot | CodeWidgetSnapshotLive)[]): RendererRegistry;
155
213
  }
156
214
  /**
157
215
  * Builds the component for one frozen custom widget (Task 14: template and
@@ -165,6 +223,47 @@ type RendererRegistryOptions = {
165
223
  /** Builds the registry the renderer reads. The built-in packs come first; a pack cannot replace a built-in type. */
166
224
  declare function createRendererRegistry(packs: readonly WidgetPack[], options?: RendererRegistryOptions): RendererRegistry;
167
225
 
226
+ /** What a render needs to decide whether a code widget runs: the store's code switch and the page it is on. */
227
+ type CodeRender = {
228
+ /** The store's code runtime (`code` of the read answer). Absent: no code. */
229
+ runtime?: CodeRuntimeAnswer | undefined;
230
+ /** The path being rendered. Absent: no code. */
231
+ pathname?: string | undefined;
232
+ routes: {
233
+ page: string;
234
+ catalog?: readonly string[] | undefined;
235
+ };
236
+ /** A preview page (`mode: 'preview'` provider): the widget is drawn, never run. */
237
+ preview?: boolean | undefined;
238
+ };
239
+ /** `https://<origin>/v1/code/<site>/<hash>.js` when the runtime is on and well-formed, else null. */
240
+ declare function codeScriptUrl(runtime: CodeRuntimeAnswer | undefined, jsHash: string): string | null;
241
+ /** JSON for the text of a `<script type="application/json">`: nothing in it can close the element or end a line. */
242
+ declare function jsonForScript(value: unknown): string;
243
+ type CodeWidgetProps = Pick<WidgetRenderProps, 'props' | 'data' | 'locale' | 'mediaOrigin'> & {
244
+ node: WidgetNode;
245
+ /** The frozen snapshot of the node's widget, as the document holds it. */
246
+ snapshot: AnyCustomWidgetSnapshot;
247
+ registry: RendererRegistry;
248
+ edit?: EditModeHooks | undefined;
249
+ code?: CodeRender | undefined;
250
+ /** False draws the widget and never runs it, whatever else says it may run. */
251
+ interactive?: boolean | undefined;
252
+ /** The anchor (`id`) of the node, when the page gave it one. */
253
+ anchor?: string | undefined;
254
+ /** The anchor of a per-device copy other than the first (the entrance and anchor rules of `NodeWrapper`). */
255
+ copyAnchor?: string | undefined;
256
+ entrance?: NodeWrapperProps['entrance'];
257
+ };
258
+ /**
259
+ * A code widget (v2 spec): its markup and CSS are drawn like a template widget's (re-validated here), and on a live
260
+ * store page where code is on and the route allows it, the widget also carries its input (`props`, `data`) and one
261
+ * `<script async src>` for its own script. Anywhere else (a checkout, a preview, the editor, the code switch off) only
262
+ * the markup and CSS are drawn, marked `data-b-code-inert`, and the editor and preview add a "Runs on your store"
263
+ * badge. A disabled widget renders nothing.
264
+ */
265
+ declare function CodeWidget(props: CodeWidgetProps): ReactNode;
266
+
168
267
  type BuilderRendererProps = {
169
268
  document: PageDocument;
170
269
  registry: RendererRegistry;
@@ -182,6 +281,22 @@ type BuilderRendererProps = {
182
281
  kind: string;
183
282
  [key: string]: unknown;
184
283
  }) => string | null) | undefined;
284
+ /**
285
+ * False in the editor's edit mode: tabs, accordions, carousels and toggles then draw every column as a
286
+ * plain row (all panels visible), and entrance animation and the countdown tick are off. Default true.
287
+ */
288
+ interactive?: boolean | undefined;
289
+ /** Mark the root with `data-b-root`, the scope of the site's custom CSS (`BuilderProvider` passes it when the site has some). */
290
+ scopeCustomCss?: boolean | undefined;
291
+ /** A nested renderer (a composite's body) inside a per-device copy continues its parent's id scope. */
292
+ idScope?: {
293
+ vpath: string;
294
+ dupe: boolean;
295
+ } | undefined;
296
+ /** The published saved sections the document references (`savedSections` of the read answer). */
297
+ savedSections?: SavedSectionsAnswer | undefined;
298
+ /** What a code widget needs to decide whether it runs: the store's code runtime and the page's route. Absent: none runs. */
299
+ code?: CodeRender | undefined;
185
300
  };
186
301
  /** The text of a localized map for a locale: the locale, its language, `en`, then any. */
187
302
  declare function pickLocale(value: Record<string, unknown>, locale: string): string;
@@ -220,40 +335,6 @@ declare function cssValue(control: SettingField['control'], value: unknown): str
220
335
  */
221
336
  declare function compileResponsiveCss(doc: PageDocument, registry: RendererRegistry, assets?: Record<string, FrozenAsset> | undefined, mediaOrigin?: string): string;
222
337
 
223
- /**
224
- * The containment every custom widget sits in. The CSS sanitiser allows
225
- * `transform`, `translate`, `scale` and negative margins (spec §10.3), so
226
- * without a box a widget could paint over, and take clicks from, a store's own
227
- * button. `contain: paint` and `overflow: clip` stop anything it draws at its
228
- * edge, and `isolation: isolate` keeps its stacking inside. Widget CSS is
229
- * scoped to descendants of the wrapper (`[data-b-w] .x`), so it can never
230
- * restyle the wrapper itself; the declarations are also inline, which beats any
231
- * stylesheet.
232
- */
233
- declare const CUSTOM_WIDGET_CONTAINMENT: CSSProperties;
234
- type NodePart = 'section' | 'column' | 'widget';
235
- type NodeWrapperProps = {
236
- id: string;
237
- part: NodePart;
238
- /** The widget type; sections and columns have none. */
239
- type?: string;
240
- as?: 'div' | 'section';
241
- className: string;
242
- anchor?: string | undefined;
243
- /** A custom widget: it gets the containment box and `data-b-w`, the scope of its CSS. */
244
- custom?: boolean;
245
- missing?: boolean;
246
- /** Hooks of the editor canvas, or undefined on a store. */
247
- edit?: EditModeHooks | undefined;
248
- children?: ReactNode;
249
- };
250
- /**
251
- * One element per node: it carries `data-b-id` (what the compiled CSS is scoped
252
- * by) and `data-throttle-part`, and in the editor the select and hover hooks.
253
- * Links inside it are inert in the editor.
254
- */
255
- declare function NodeWrapper(props: NodeWrapperProps): ReactNode;
256
-
257
338
  /** A frozen asset as the renderer hands it to a widget in place of a media asset id. */
258
339
  declare function isFrozenAsset(value: unknown): value is FrozenAsset;
259
340
  type AssetImageProps = {
@@ -304,6 +385,20 @@ type BuilderProviderProps = {
304
385
  onError?: (error: unknown, info: {
305
386
  part: string;
306
387
  }) => void;
388
+ /**
389
+ * False in the editor's edit mode: tabs, accordions, carousels and toggles show every panel and nothing
390
+ * animates or ticks. Default true.
391
+ */
392
+ interactive?: boolean;
393
+ /**
394
+ * The path being rendered (`usePathname()`). Code widgets run only where it is on the route allow-list, so
395
+ * without it none runs. Never a checkout, cart-payment, account or sign-in path, whatever is passed.
396
+ */
397
+ pathname?: string;
398
+ /** The catalog route templates code widgets may also run on (`{handle}` is one segment). Default: `/p/{handle}`, `/c/{handle}`, `/collections/{handle}`, `/tags/{tag}`, `/search`, `/shop`. */
399
+ catalogRoutes?: string[];
400
+ /** `preview` is the Builder's own preview page: code widgets are drawn there with a badge and never run. */
401
+ mode?: 'live' | 'preview';
307
402
  children: ReactNode;
308
403
  };
309
404
  /**
@@ -320,7 +415,7 @@ type BuilderProviderProps = {
320
415
  * With a site the Builder could not answer (`status: 'unavailable'`) it fills
321
416
  * nothing, so the catalog's own design shows and every part renders nothing.
322
417
  */
323
- declare function BuilderProvider({ builderKey, client, packs, site, onError, children }: BuilderProviderProps): ReactNode;
418
+ declare function BuilderProvider({ builderKey, client, packs, site, onError, interactive, pathname, catalogRoutes, mode, children }: BuilderProviderProps): ReactNode;
324
419
 
325
420
  type BuilderContextValue = {
326
421
  client: BuilderClient | null;
@@ -336,6 +431,19 @@ type BuilderContextValue = {
336
431
  kind: string;
337
432
  [key: string]: unknown;
338
433
  }) => string | null;
434
+ /** False in the editor's edit mode: every panel expanded, nothing animated or ticking. */
435
+ interactive: boolean;
436
+ /** The site's sanitised custom CSS (scoped under `[data-b-root]`), or ''. */
437
+ customCss: string;
438
+ /** `preview` is a page the Builder editor draws: code widgets are drawn there, never run. */
439
+ mode: 'live' | 'preview';
440
+ /** The path being rendered (`usePathname()` of the store); without it no code widget runs. */
441
+ pathname: string | undefined;
442
+ /** The site's page template and the catalog templates code may run on (`isCodeRoute`). */
443
+ codeRoutes: {
444
+ page: string;
445
+ catalog?: readonly string[] | undefined;
446
+ };
339
447
  };
340
448
  /**
341
449
  * `react` has no `createContext` in a React Server Components build, and the server entries share this module's chunk
@@ -401,6 +509,60 @@ declare function resolveBindings(bindings: ReadonlyMap<string, DataBinding>, reg
401
509
  include: 'static' | 'shopper' | 'all';
402
510
  }): Promise<DataMap>;
403
511
 
512
+ /**
513
+ * Where a code widget may run (v2 spec, code widgets). The allow-list lives here, in the renderer, and is not a
514
+ * merchant setting: no switch in the dashboard can put a script on a checkout, cart-payment, account or sign-in page.
515
+ */
516
+ /**
517
+ * A path segment that never runs code (checkout, cart, account, sign-in and their common synonyms, and the pages after a purchase or a quote: `confirm*`, `thank*`, `receipt*`, `invoice*`, `quote*`, `order-*`). `isCodeRoute`
518
+ * tests every segment of the path with it, and the deny wins over every allow rule.
519
+ */
520
+ declare const CODE_ROUTE_DENY: RegExp;
521
+ /** The catalog templates a store has unless it passes its own (`{name}` is one path segment). */
522
+ declare const DEFAULT_CATALOG_ROUTES: readonly string[];
523
+ /**
524
+ * Whether code widgets may run on this path. False when the path is unknown; false on the deny list; otherwise true
525
+ * only on `/`, the site's page template and the catalog templates. A segment of the deny list anywhere in the path refuses it
526
+ * (`/fr/checkout`, `/de/account/orders`), whatever the page template is.
527
+ */
528
+ declare function isCodeRoute(pathname: string | undefined, routes: {
529
+ page: string;
530
+ catalog?: readonly string[];
531
+ }): boolean;
532
+
533
+ /**
534
+ * Saved sections (agent v2): a `saved-section` root node names a document by id, and the read answer carries the
535
+ * published section of every document the page uses. The renderer draws that section where the reference stands.
536
+ *
537
+ * Every id inside it is written as `<refNodeId>-<innerId>`, so the CSS (scoped by `data-b-id`) of two references to
538
+ * the same saved section on one page never collides. A reference the answer has no usable section for draws nothing
539
+ * but an empty `data-b-missing` box (and warns once in development).
540
+ */
541
+ /** What stands where a root node of the page was: a section of the page, or a reference and the section it became. */
542
+ type RootSlot = {
543
+ kind: 'section';
544
+ id: string;
545
+ } | {
546
+ kind: 'ref';
547
+ ref: SavedSectionRefNode;
548
+ sectionId: string | null;
549
+ };
550
+ type Expansion = {
551
+ /** The document with every reference replaced by its (id-prefixed) section; missing ones are gone. */
552
+ doc: PageDocument;
553
+ /** The roots in page order, for rendering. Null when the document holds no reference at all. */
554
+ roots: RootSlot[] | null;
555
+ };
556
+ /**
557
+ * The document with its saved-section references replaced, built once per document and answer. A document with no
558
+ * reference is returned as it is (the same object), so a page without saved sections renders exactly as before.
559
+ */
560
+ declare function expandSavedSections(source: PageDocument, answer: SavedSectionsAnswer | undefined): Expansion;
561
+ /** The box a reference without a usable section leaves: nothing visible, `data-b-missing`. */
562
+ declare function MissingSavedSection({ node }: {
563
+ node: SavedSectionRefNode;
564
+ }): ReactNode;
565
+
404
566
  type VideoRef = {
405
567
  provider: 'youtube' | 'vimeo';
406
568
  id: string;
@@ -464,4 +626,4 @@ declare function CompositeWidget(props: CompositeWidgetProps): ReactNode;
464
626
  */
465
627
  declare const customWidgetFactory: CustomWidgetFactory;
466
628
 
467
- export { AssetImage, BASE_CSS, BASIC_COMPONENTS, BuilderContext, type BuilderContextValue, BuilderFooter, BuilderHeader, BuilderPage, BuilderPageView, BuilderProvider, type BuilderProviderProps, BuilderRenderer, type BuilderRendererProps, BuilderSlot, CUSTOM_WIDGET_CONTAINMENT, CompositeWidget, type CompositeWidgetProps, type CustomWidgetFactory, type DataMap, type DataSourceResolver, type EditModeHooks, type LinkTargetProvider, type LoadedPage, type LoadedPart, type LoadedRedirect, type LoadedSite, MAX_RENDERED_NODES, NodeWrapper, type PackDataSource, type PackWidget, RenderBudget, type RenderWarning, type RendererRegistry, type RendererRegistryOptions, type ResolveContext, RichText, type SlotPoint, TemplateWidget, type TemplateWidgetProps, type WidgetPack, type WidgetRenderProps, WidgetStyle, basicPack, bindingKey, bindingsOf, collectBindings, compileResponsiveCss, createRendererRegistry, cssValue, customWidgetFactory, embedSrc, fitsBudget, isFrozenAsset, parseRichText, parseVideoUrl, pickLocale, resolveBindings, useBuilder, validateRender };
629
+ export { AssetImage, BASE_CSS, BASIC_COMPONENTS, BuilderContext, type BuilderContextValue, BuilderFooter, BuilderHeader, BuilderPage, BuilderPageView, BuilderProvider, type BuilderProviderProps, BuilderRenderer, type BuilderRendererProps, BuilderSlot, CODE_ROUTE_DENY, CUSTOM_WIDGET_CONTAINMENT, type CodeRender, CodeWidget, type CodeWidgetProps, CompositeWidget, type CompositeWidgetProps, type CustomWidgetFactory, DEFAULT_CATALOG_ROUTES, type DataMap, type DataSourceResolver, type EditModeHooks, type LinkTargetProvider, type LoadedPage, type LoadedPart, type LoadedRedirect, type LoadedSite, MAX_RENDERED_NODES, MissingSavedSection, NodeWrapper, type PackDataSource, type PackWidget, RenderBudget, type RenderWarning, type RendererRegistry, type RendererRegistryOptions, type ResolveContext, RichText, type SlotPoint, TemplateWidget, type TemplateWidgetProps, type WidgetPack, type WidgetRenderProps, WidgetStyle, basicPack, bindingKey, bindingsOf, codeScriptUrl, collectBindings, compileResponsiveCss, createRendererRegistry, cssValue, customWidgetFactory, embedSrc, expandSavedSections, fitsBudget, isCodeRoute, isFrozenAsset, jsonForScript, parseRichText, parseVideoUrl, pickLocale, resolveBindings, useBuilder, validateRender };
package/dist/index.d.ts CHANGED
@@ -1,5 +1,5 @@
1
1
  import { ReactNode, ComponentType, CSSProperties, Context } from 'react';
2
- import { TemplateAst, WidgetNode, SettingValue, WidgetDefinition, DataSourceDescriptor, PageDocument, FrozenAsset, WidgetRegistry, CustomWidgetSnapshot, SettingField, DataBinding } from '@usethrottle/builder-schema';
2
+ import { TemplateAst, WidgetNode, SettingValue, WidgetDefinition, DataSourceDescriptor, PageDocument, FrozenAsset, SavedSectionsAnswer, CodeRuntimeAnswer, WidgetRegistry, CustomWidgetSnapshot, CodeWidgetSnapshotLive, AnyCustomWidgetSnapshot, SettingField, DataBinding, SavedSectionRefNode } from '@usethrottle/builder-schema';
3
3
  import { BuilderClient } from '@usethrottle/builder';
4
4
  export { BuilderNotFoundError, BuilderUnavailableError } from '@usethrottle/builder';
5
5
 
@@ -38,6 +38,13 @@ type WidgetRenderProps = {
38
38
  /** Resolved data by the widget's named inputs. Absent until a perShopper source has resolved in the browser. */
39
39
  data: Record<string, unknown>;
40
40
  editMode: boolean;
41
+ /** False in the editor's edit mode: draw the widget static (no ticking, no script). Absent means true. */
42
+ interactive?: boolean | undefined;
43
+ /** Set inside a per-device copy of a section: a nested renderer continues the parent's id scope (composites). */
44
+ idScope?: {
45
+ vpath: string;
46
+ dupe: boolean;
47
+ } | undefined;
41
48
  locale: string;
42
49
  /** The only origin a media `src` may be on; pass it to `AssetImage`. */
43
50
  mediaOrigin: string;
@@ -109,6 +116,10 @@ type LoadedPage = {
109
116
  initialData: DataMap;
110
117
  /** The page's other fields as the read API sent them (seo, description, ...). */
111
118
  meta: Record<string, unknown>;
119
+ /** The published saved sections the page references. */
120
+ savedSections?: SavedSectionsAnswer | undefined;
121
+ /** Whether the store runs code widgets and where their scripts come from. */
122
+ code?: CodeRuntimeAnswer | undefined;
112
123
  };
113
124
  type LoadedRedirect = {
114
125
  kind: 'redirect';
@@ -119,6 +130,10 @@ type LoadedPart = {
119
130
  document: PageDocument;
120
131
  assets: PageAssets;
121
132
  initialData: DataMap;
133
+ /** The published saved sections the document references. */
134
+ savedSections?: SavedSectionsAnswer | undefined;
135
+ /** Whether the store runs code widgets and where their scripts come from. */
136
+ code?: CodeRuntimeAnswer | undefined;
122
137
  };
123
138
  /**
124
139
  * The store's site design, read once per request. `unavailable` means the
@@ -142,6 +157,49 @@ type LoadedSite = {
142
157
  locale: string;
143
158
  };
144
159
 
160
+ /**
161
+ * The containment every custom widget sits in. The CSS sanitiser allows
162
+ * `transform`, `translate`, `scale` and negative margins (spec §10.3), so
163
+ * without a box a widget could paint over, and take clicks from, a store's own
164
+ * button. `contain: paint` and `overflow: clip` stop anything it draws at its
165
+ * edge, and `isolation: isolate` keeps its stacking inside. Widget CSS is
166
+ * scoped to descendants of the wrapper (`[data-b-w] .x`), so it can never
167
+ * restyle the wrapper itself; the declarations are also inline, which beats any
168
+ * stylesheet.
169
+ */
170
+ declare const CUSTOM_WIDGET_CONTAINMENT: CSSProperties;
171
+ type NodePart = 'section' | 'column' | 'widget';
172
+ type NodeWrapperProps = {
173
+ id: string;
174
+ part: NodePart;
175
+ /** The widget type; sections and columns have none. */
176
+ type?: string;
177
+ as?: 'div' | 'section';
178
+ className: string;
179
+ anchor?: string | undefined;
180
+ /** The anchor name of a per-device copy: `data-b-anchor`, which the runtime scrolls to when `#name` points at a hidden copy. */
181
+ copyAnchor?: string | undefined;
182
+ /** A custom widget: it gets the containment box and `data-b-w`, the scope of its CSS. */
183
+ custom?: boolean;
184
+ missing?: boolean;
185
+ /** Extra `data-b-*` attributes of the element (a code widget's `data-b-code`). */
186
+ attributes?: Record<`data-b-${string}`, string> | undefined;
187
+ /** Hooks of the editor canvas, or undefined on a store. */
188
+ edit?: EditModeHooks | undefined;
189
+ /** Entrance animation (agent v2): `data-b-entrance` and the delay, animated by the interactions runtime. */
190
+ entrance?: {
191
+ name: string;
192
+ delayMs: number;
193
+ } | undefined;
194
+ children?: ReactNode;
195
+ };
196
+ /**
197
+ * One element per node: it carries `data-b-id` (what the compiled CSS is scoped
198
+ * by) and `data-throttle-part`, and in the editor the select and hover hooks.
199
+ * Links inside it are inert in the editor.
200
+ */
201
+ declare function NodeWrapper(props: NodeWrapperProps): ReactNode;
202
+
145
203
  /**
146
204
  * The definitions of the schema registry plus what only the renderer has: the
147
205
  * component of each widget and the resolver of each data source.
@@ -151,7 +209,7 @@ interface RendererRegistry extends WidgetRegistry {
151
209
  component(node: WidgetNode): ComponentType<WidgetRenderProps> | undefined;
152
210
  resolver(sourceId: string): DataSourceResolver | undefined;
153
211
  /** The same registry with a published document's frozen custom widgets added. */
154
- withCustom(snapshots: readonly CustomWidgetSnapshot[]): RendererRegistry;
212
+ withCustom(snapshots: readonly (CustomWidgetSnapshot | CodeWidgetSnapshotLive)[]): RendererRegistry;
155
213
  }
156
214
  /**
157
215
  * Builds the component for one frozen custom widget (Task 14: template and
@@ -165,6 +223,47 @@ type RendererRegistryOptions = {
165
223
  /** Builds the registry the renderer reads. The built-in packs come first; a pack cannot replace a built-in type. */
166
224
  declare function createRendererRegistry(packs: readonly WidgetPack[], options?: RendererRegistryOptions): RendererRegistry;
167
225
 
226
+ /** What a render needs to decide whether a code widget runs: the store's code switch and the page it is on. */
227
+ type CodeRender = {
228
+ /** The store's code runtime (`code` of the read answer). Absent: no code. */
229
+ runtime?: CodeRuntimeAnswer | undefined;
230
+ /** The path being rendered. Absent: no code. */
231
+ pathname?: string | undefined;
232
+ routes: {
233
+ page: string;
234
+ catalog?: readonly string[] | undefined;
235
+ };
236
+ /** A preview page (`mode: 'preview'` provider): the widget is drawn, never run. */
237
+ preview?: boolean | undefined;
238
+ };
239
+ /** `https://<origin>/v1/code/<site>/<hash>.js` when the runtime is on and well-formed, else null. */
240
+ declare function codeScriptUrl(runtime: CodeRuntimeAnswer | undefined, jsHash: string): string | null;
241
+ /** JSON for the text of a `<script type="application/json">`: nothing in it can close the element or end a line. */
242
+ declare function jsonForScript(value: unknown): string;
243
+ type CodeWidgetProps = Pick<WidgetRenderProps, 'props' | 'data' | 'locale' | 'mediaOrigin'> & {
244
+ node: WidgetNode;
245
+ /** The frozen snapshot of the node's widget, as the document holds it. */
246
+ snapshot: AnyCustomWidgetSnapshot;
247
+ registry: RendererRegistry;
248
+ edit?: EditModeHooks | undefined;
249
+ code?: CodeRender | undefined;
250
+ /** False draws the widget and never runs it, whatever else says it may run. */
251
+ interactive?: boolean | undefined;
252
+ /** The anchor (`id`) of the node, when the page gave it one. */
253
+ anchor?: string | undefined;
254
+ /** The anchor of a per-device copy other than the first (the entrance and anchor rules of `NodeWrapper`). */
255
+ copyAnchor?: string | undefined;
256
+ entrance?: NodeWrapperProps['entrance'];
257
+ };
258
+ /**
259
+ * A code widget (v2 spec): its markup and CSS are drawn like a template widget's (re-validated here), and on a live
260
+ * store page where code is on and the route allows it, the widget also carries its input (`props`, `data`) and one
261
+ * `<script async src>` for its own script. Anywhere else (a checkout, a preview, the editor, the code switch off) only
262
+ * the markup and CSS are drawn, marked `data-b-code-inert`, and the editor and preview add a "Runs on your store"
263
+ * badge. A disabled widget renders nothing.
264
+ */
265
+ declare function CodeWidget(props: CodeWidgetProps): ReactNode;
266
+
168
267
  type BuilderRendererProps = {
169
268
  document: PageDocument;
170
269
  registry: RendererRegistry;
@@ -182,6 +281,22 @@ type BuilderRendererProps = {
182
281
  kind: string;
183
282
  [key: string]: unknown;
184
283
  }) => string | null) | undefined;
284
+ /**
285
+ * False in the editor's edit mode: tabs, accordions, carousels and toggles then draw every column as a
286
+ * plain row (all panels visible), and entrance animation and the countdown tick are off. Default true.
287
+ */
288
+ interactive?: boolean | undefined;
289
+ /** Mark the root with `data-b-root`, the scope of the site's custom CSS (`BuilderProvider` passes it when the site has some). */
290
+ scopeCustomCss?: boolean | undefined;
291
+ /** A nested renderer (a composite's body) inside a per-device copy continues its parent's id scope. */
292
+ idScope?: {
293
+ vpath: string;
294
+ dupe: boolean;
295
+ } | undefined;
296
+ /** The published saved sections the document references (`savedSections` of the read answer). */
297
+ savedSections?: SavedSectionsAnswer | undefined;
298
+ /** What a code widget needs to decide whether it runs: the store's code runtime and the page's route. Absent: none runs. */
299
+ code?: CodeRender | undefined;
185
300
  };
186
301
  /** The text of a localized map for a locale: the locale, its language, `en`, then any. */
187
302
  declare function pickLocale(value: Record<string, unknown>, locale: string): string;
@@ -220,40 +335,6 @@ declare function cssValue(control: SettingField['control'], value: unknown): str
220
335
  */
221
336
  declare function compileResponsiveCss(doc: PageDocument, registry: RendererRegistry, assets?: Record<string, FrozenAsset> | undefined, mediaOrigin?: string): string;
222
337
 
223
- /**
224
- * The containment every custom widget sits in. The CSS sanitiser allows
225
- * `transform`, `translate`, `scale` and negative margins (spec §10.3), so
226
- * without a box a widget could paint over, and take clicks from, a store's own
227
- * button. `contain: paint` and `overflow: clip` stop anything it draws at its
228
- * edge, and `isolation: isolate` keeps its stacking inside. Widget CSS is
229
- * scoped to descendants of the wrapper (`[data-b-w] .x`), so it can never
230
- * restyle the wrapper itself; the declarations are also inline, which beats any
231
- * stylesheet.
232
- */
233
- declare const CUSTOM_WIDGET_CONTAINMENT: CSSProperties;
234
- type NodePart = 'section' | 'column' | 'widget';
235
- type NodeWrapperProps = {
236
- id: string;
237
- part: NodePart;
238
- /** The widget type; sections and columns have none. */
239
- type?: string;
240
- as?: 'div' | 'section';
241
- className: string;
242
- anchor?: string | undefined;
243
- /** A custom widget: it gets the containment box and `data-b-w`, the scope of its CSS. */
244
- custom?: boolean;
245
- missing?: boolean;
246
- /** Hooks of the editor canvas, or undefined on a store. */
247
- edit?: EditModeHooks | undefined;
248
- children?: ReactNode;
249
- };
250
- /**
251
- * One element per node: it carries `data-b-id` (what the compiled CSS is scoped
252
- * by) and `data-throttle-part`, and in the editor the select and hover hooks.
253
- * Links inside it are inert in the editor.
254
- */
255
- declare function NodeWrapper(props: NodeWrapperProps): ReactNode;
256
-
257
338
  /** A frozen asset as the renderer hands it to a widget in place of a media asset id. */
258
339
  declare function isFrozenAsset(value: unknown): value is FrozenAsset;
259
340
  type AssetImageProps = {
@@ -304,6 +385,20 @@ type BuilderProviderProps = {
304
385
  onError?: (error: unknown, info: {
305
386
  part: string;
306
387
  }) => void;
388
+ /**
389
+ * False in the editor's edit mode: tabs, accordions, carousels and toggles show every panel and nothing
390
+ * animates or ticks. Default true.
391
+ */
392
+ interactive?: boolean;
393
+ /**
394
+ * The path being rendered (`usePathname()`). Code widgets run only where it is on the route allow-list, so
395
+ * without it none runs. Never a checkout, cart-payment, account or sign-in path, whatever is passed.
396
+ */
397
+ pathname?: string;
398
+ /** The catalog route templates code widgets may also run on (`{handle}` is one segment). Default: `/p/{handle}`, `/c/{handle}`, `/collections/{handle}`, `/tags/{tag}`, `/search`, `/shop`. */
399
+ catalogRoutes?: string[];
400
+ /** `preview` is the Builder's own preview page: code widgets are drawn there with a badge and never run. */
401
+ mode?: 'live' | 'preview';
307
402
  children: ReactNode;
308
403
  };
309
404
  /**
@@ -320,7 +415,7 @@ type BuilderProviderProps = {
320
415
  * With a site the Builder could not answer (`status: 'unavailable'`) it fills
321
416
  * nothing, so the catalog's own design shows and every part renders nothing.
322
417
  */
323
- declare function BuilderProvider({ builderKey, client, packs, site, onError, children }: BuilderProviderProps): ReactNode;
418
+ declare function BuilderProvider({ builderKey, client, packs, site, onError, interactive, pathname, catalogRoutes, mode, children }: BuilderProviderProps): ReactNode;
324
419
 
325
420
  type BuilderContextValue = {
326
421
  client: BuilderClient | null;
@@ -336,6 +431,19 @@ type BuilderContextValue = {
336
431
  kind: string;
337
432
  [key: string]: unknown;
338
433
  }) => string | null;
434
+ /** False in the editor's edit mode: every panel expanded, nothing animated or ticking. */
435
+ interactive: boolean;
436
+ /** The site's sanitised custom CSS (scoped under `[data-b-root]`), or ''. */
437
+ customCss: string;
438
+ /** `preview` is a page the Builder editor draws: code widgets are drawn there, never run. */
439
+ mode: 'live' | 'preview';
440
+ /** The path being rendered (`usePathname()` of the store); without it no code widget runs. */
441
+ pathname: string | undefined;
442
+ /** The site's page template and the catalog templates code may run on (`isCodeRoute`). */
443
+ codeRoutes: {
444
+ page: string;
445
+ catalog?: readonly string[] | undefined;
446
+ };
339
447
  };
340
448
  /**
341
449
  * `react` has no `createContext` in a React Server Components build, and the server entries share this module's chunk
@@ -401,6 +509,60 @@ declare function resolveBindings(bindings: ReadonlyMap<string, DataBinding>, reg
401
509
  include: 'static' | 'shopper' | 'all';
402
510
  }): Promise<DataMap>;
403
511
 
512
+ /**
513
+ * Where a code widget may run (v2 spec, code widgets). The allow-list lives here, in the renderer, and is not a
514
+ * merchant setting: no switch in the dashboard can put a script on a checkout, cart-payment, account or sign-in page.
515
+ */
516
+ /**
517
+ * A path segment that never runs code (checkout, cart, account, sign-in and their common synonyms, and the pages after a purchase or a quote: `confirm*`, `thank*`, `receipt*`, `invoice*`, `quote*`, `order-*`). `isCodeRoute`
518
+ * tests every segment of the path with it, and the deny wins over every allow rule.
519
+ */
520
+ declare const CODE_ROUTE_DENY: RegExp;
521
+ /** The catalog templates a store has unless it passes its own (`{name}` is one path segment). */
522
+ declare const DEFAULT_CATALOG_ROUTES: readonly string[];
523
+ /**
524
+ * Whether code widgets may run on this path. False when the path is unknown; false on the deny list; otherwise true
525
+ * only on `/`, the site's page template and the catalog templates. A segment of the deny list anywhere in the path refuses it
526
+ * (`/fr/checkout`, `/de/account/orders`), whatever the page template is.
527
+ */
528
+ declare function isCodeRoute(pathname: string | undefined, routes: {
529
+ page: string;
530
+ catalog?: readonly string[];
531
+ }): boolean;
532
+
533
+ /**
534
+ * Saved sections (agent v2): a `saved-section` root node names a document by id, and the read answer carries the
535
+ * published section of every document the page uses. The renderer draws that section where the reference stands.
536
+ *
537
+ * Every id inside it is written as `<refNodeId>-<innerId>`, so the CSS (scoped by `data-b-id`) of two references to
538
+ * the same saved section on one page never collides. A reference the answer has no usable section for draws nothing
539
+ * but an empty `data-b-missing` box (and warns once in development).
540
+ */
541
+ /** What stands where a root node of the page was: a section of the page, or a reference and the section it became. */
542
+ type RootSlot = {
543
+ kind: 'section';
544
+ id: string;
545
+ } | {
546
+ kind: 'ref';
547
+ ref: SavedSectionRefNode;
548
+ sectionId: string | null;
549
+ };
550
+ type Expansion = {
551
+ /** The document with every reference replaced by its (id-prefixed) section; missing ones are gone. */
552
+ doc: PageDocument;
553
+ /** The roots in page order, for rendering. Null when the document holds no reference at all. */
554
+ roots: RootSlot[] | null;
555
+ };
556
+ /**
557
+ * The document with its saved-section references replaced, built once per document and answer. A document with no
558
+ * reference is returned as it is (the same object), so a page without saved sections renders exactly as before.
559
+ */
560
+ declare function expandSavedSections(source: PageDocument, answer: SavedSectionsAnswer | undefined): Expansion;
561
+ /** The box a reference without a usable section leaves: nothing visible, `data-b-missing`. */
562
+ declare function MissingSavedSection({ node }: {
563
+ node: SavedSectionRefNode;
564
+ }): ReactNode;
565
+
404
566
  type VideoRef = {
405
567
  provider: 'youtube' | 'vimeo';
406
568
  id: string;
@@ -464,4 +626,4 @@ declare function CompositeWidget(props: CompositeWidgetProps): ReactNode;
464
626
  */
465
627
  declare const customWidgetFactory: CustomWidgetFactory;
466
628
 
467
- export { AssetImage, BASE_CSS, BASIC_COMPONENTS, BuilderContext, type BuilderContextValue, BuilderFooter, BuilderHeader, BuilderPage, BuilderPageView, BuilderProvider, type BuilderProviderProps, BuilderRenderer, type BuilderRendererProps, BuilderSlot, CUSTOM_WIDGET_CONTAINMENT, CompositeWidget, type CompositeWidgetProps, type CustomWidgetFactory, type DataMap, type DataSourceResolver, type EditModeHooks, type LinkTargetProvider, type LoadedPage, type LoadedPart, type LoadedRedirect, type LoadedSite, MAX_RENDERED_NODES, NodeWrapper, type PackDataSource, type PackWidget, RenderBudget, type RenderWarning, type RendererRegistry, type RendererRegistryOptions, type ResolveContext, RichText, type SlotPoint, TemplateWidget, type TemplateWidgetProps, type WidgetPack, type WidgetRenderProps, WidgetStyle, basicPack, bindingKey, bindingsOf, collectBindings, compileResponsiveCss, createRendererRegistry, cssValue, customWidgetFactory, embedSrc, fitsBudget, isFrozenAsset, parseRichText, parseVideoUrl, pickLocale, resolveBindings, useBuilder, validateRender };
629
+ export { AssetImage, BASE_CSS, BASIC_COMPONENTS, BuilderContext, type BuilderContextValue, BuilderFooter, BuilderHeader, BuilderPage, BuilderPageView, BuilderProvider, type BuilderProviderProps, BuilderRenderer, type BuilderRendererProps, BuilderSlot, CODE_ROUTE_DENY, CUSTOM_WIDGET_CONTAINMENT, type CodeRender, CodeWidget, type CodeWidgetProps, CompositeWidget, type CompositeWidgetProps, type CustomWidgetFactory, DEFAULT_CATALOG_ROUTES, type DataMap, type DataSourceResolver, type EditModeHooks, type LinkTargetProvider, type LoadedPage, type LoadedPart, type LoadedRedirect, type LoadedSite, MAX_RENDERED_NODES, MissingSavedSection, NodeWrapper, type PackDataSource, type PackWidget, RenderBudget, type RenderWarning, type RendererRegistry, type RendererRegistryOptions, type ResolveContext, RichText, type SlotPoint, TemplateWidget, type TemplateWidgetProps, type WidgetPack, type WidgetRenderProps, WidgetStyle, basicPack, bindingKey, bindingsOf, codeScriptUrl, collectBindings, compileResponsiveCss, createRendererRegistry, cssValue, customWidgetFactory, embedSrc, expandSavedSections, fitsBudget, isCodeRoute, isFrozenAsset, jsonForScript, parseRichText, parseVideoUrl, pickLocale, resolveBindings, useBuilder, validateRender };