@snowcone-app/canvas 0.19.1 → 0.21.0

package/dist/advanced.mjs

@@ -1,20 +1,20 @@
-import { D as te, T as M, h as D, B as re, I as q, i as I, j as ne, e as se } from "./MenuButton-CeoEAtzP.js";
-import { k as at, L as it, M as ct, l as lt, S as dt, m as ut, s as mt, n as ft } from "./MenuButton-CeoEAtzP.js";
-import { r as oe, v as ae } from "./validation-0IscSfRb.js";
-import { a as pt, b as xt, c as gt, d as bt, D as yt, e as vt, f as wt, G as St, I as Ct, K as Tt, g as Et, L as $t, S as kt, T as At, Z as Ft, h as Pt, i as Nt, j as Rt, k as Bt, l as Mt, m as Dt, n as It, u as zt, o as Ot, p as Lt } from "./validation-0IscSfRb.js";
-import { P as ie, a as ce, b as le } from "./ContextualToolbars-CkLjHNPn.js";
-import { A as Kt, B as Gt, c as _t, C as Ut, d as jt, e as Jt, F as qt, f as Zt, I as Vt, g as Xt, M as Yt, h as Ht, S as Qt, T as er, i as tr, j as rr, k as nr, U as sr, l as or, u as ar, m as ir } from "./ContextualToolbars-CkLjHNPn.js";
-import { u as Z } from "./EditorContext-5QpqAhjh.js";
-import { E as lr, P as dr, p as ur, s as mr, b as fr, c as hr, d as pr, e as xr, f as gr, a as br } from "./EditorContext-5QpqAhjh.js";
+import { D as te, T as M, h as D, B as re, I as q, i as I, j as ne, e as se } from "./UnifiedFontService-B1PGVu8O.js";
+import { k as at, L as it, M as ct, l as lt, S as dt, m as ut, s as mt, n as ft } from "./UnifiedFontService-B1PGVu8O.js";
+import { r as oe, v as ae } from "./validation-3YEMnKLB.js";
+import { a as pt, b as xt, c as gt, d as bt, D as yt, e as vt, f as wt, G as St, I as Ct, K as Tt, g as Et, L as $t, S as kt, T as At, Z as Ft, h as Pt, i as Nt, j as Rt, k as Bt, l as Mt, m as Dt, n as It, u as zt, o as Ot, p as Lt } from "./validation-3YEMnKLB.js";
+import { P as ie, a as ce, b as le } from "./ContextualToolbars--vTtorNg.js";
+import { A as Kt, B as Gt, c as _t, C as Ut, d as jt, e as Jt, F as qt, f as Zt, I as Vt, g as Xt, M as Yt, h as Ht, S as Qt, T as er, i as tr, j as rr, k as nr, U as sr, l as or, u as ar, m as ir } from "./ContextualToolbars--vTtorNg.js";
+import { u as Z } from "./editorErrors-CK1RISFa.js";
+import { E as lr, P as dr, p as ur, s as mr, b as fr, c as hr, d as pr, e as xr, f as gr, a as br } from "./editorErrors-CK1RISFa.js";
 import { T as vr, u as wr } from "./ThemeContext-Rjz25x9X.js";
-import { c as de, G as ue, F as me, g as fe, r as he, u as pe } from "./FontAnalyzer-DIlqmyuf.js";
-import { A as Cr, B as Tr, I as Er, P as $r, R as kr, S as Ar, T as Fr, h as Pr, a as Nr, b as Rr, i as Br, d as Mr, e as Dr, f as Ir, j as zr, k as Or, l as Lr, m as Wr, n as Kr, o as Gr, p as _r, q as Ur, s as jr, t as Jr, v as qr, w as Zr, x as Vr } from "./FontAnalyzer-DIlqmyuf.js";
-import { i as Yr, a as Hr, b as Qr, c as en, d as tn } from "./CanvasRenderer-DUc-MOeR.js";
+import { c as de, G as ue, F as me, g as fe, r as he, u as pe } from "./FontAnalyzer-BpsTYowD.js";
+import { A as Cr, B as Tr, I as Er, P as $r, R as kr, S as Ar, T as Fr, h as Pr, a as Nr, b as Rr, i as Br, d as Mr, e as Dr, f as Ir, j as zr, k as Or, l as Lr, m as Wr, n as Kr, o as Gr, p as _r, q as Ur, s as jr, t as Jr, v as qr, w as Zr, x as Vr } from "./FontAnalyzer-BpsTYowD.js";
+import { i as Yr, a as Hr, b as Qr, c as en, d as tn } from "./CanvasRenderer-CwiYq8qg.js";
 import { useState as A, useCallback as y, useEffect as V, useMemo as X, useRef as B, memo as xe } from "react";
-import { I as ge } from "./ImportManager-D--7JnvW.js";
+import { I as ge } from "./ExportManager-DK7CdI-G.js";
 import { e as be, c as ye } from "./compose-DtQL_oit.js";
 import { jsxs as b, jsx as a, Fragment as ve } from "react/jsx-runtime";
-import { P as nn, p as sn, u as on } from "./usePieceGuideBundle-DVOISsB1.js";
+import { P as nn, p as sn, u as on } from "./usePieceGuideBundle-Ctnu5k2D.js";
 const ze = ({
   title: e,
   icon: t,

package/dist/api/embed.d.ts

@@ -50,7 +50,7 @@ export type { UseRealtimeMockupsResult } from '../components/embed-realtime/useR
 export { validateEmbed, collectEmbedIssues } from '../components/embed-realtime/validateEmbed.js';
 export type { ValidateEmbedInput, EmbedIssue } from '../components/embed-realtime/validateEmbed.js';
 export { design, DesignBuilder, isLayerToken } from '../design/design-builder.js';
-export type { Anchor, ShapeKind, DesignArtboard, AnyDesign, LayerKind, LayerToken, } from '../design/design-builder.js';
+export type { Anchor, ShapeKind, DesignArtboard, StateArtboard, FromStateOptions, AnyDesign, LayerKind, LayerToken, } from '../design/design-builder.js';
 export { useEditor } from '../contexts/EditorContext.js';
 export type { EditorContextValue, EditorProviderProps } from '../contexts/EditorContext.js';
 export { useLayers } from '../hooks/useLayers.js';
@@ -78,3 +78,5 @@ export type { CanvasServices, ResolvedCanvasServices } from '../contexts/CanvasS
 export { createProxyImageSearch, createProxyGenerate } from '../services/imageSearch.js';
 export type { ImageSearchProvider, ImageSearchResult, ImageSearchResponse, ImageSearchParams, GenerateProvider, GenerateParams, GenerateResponse, } from '../services/imageSearch.js';
 export type { RenderProduct, RenderProductOptions, RenderProductCombination, RenderProductRequiredPlacement, MockupResult, RealtimeGrant, } from '@snowcone-app/sdk';
+export { SnowconeEditor, formatBuyPrice } from '../default-editor/SnowconeEditor.js';
+export type { SnowconeEditorProps } from '../default-editor/SnowconeEditor.js';

package/dist/api/stable.d.ts

@@ -44,14 +44,14 @@ export { COMPACT_CUSTOMIZER, PRO_STUDIO, EMBED_ONLY } from '../kits/presets.js';
 export type { KitDefinition, KitPresetId, RuntimeTheme, KitValidationResult } from '../kits/index.js';
 export { ALL_CAPABILITIES, MINIMAL_CAPABILITIES } from '../types/capabilities.js';
 export type { EditorCapabilities, ElementType, EffectType, PanelType, ToolType } from '../types/capabilities.js';
-export type { ArtboardConfig as ArtboardElementConfig, TransformType, AnyElementConfig, TextAlign, BlendMode, BoundingBox, Point, CanvasError, CanvasErrorCategory, } from '../types/index.js';
+export type { ArtboardConfig as ArtboardElementConfig, ArtboardRole, TransformType, AnyElementConfig, TextAlign, BlendMode, BoundingBox, Point, CanvasError, CanvasErrorCategory, } from '../types/index.js';
 export { ErrorBoundary } from '../components/embed/ErrorBoundary.js';
 export type { ErrorBoundaryProps } from '../components/embed/ErrorBoundary.js';
 export { serializeState, deserializeState, validateState, migrateState, } from '../state/index.js';
 export { serializeStateForServer, CANVAS_STATE_SCHEMA_VERSION, } from '../rendering/serialize-for-server.js';
 export type { ServerRenderRequest } from '../rendering/serialize-for-server.js';
 export { design, DesignBuilder } from '../design/design-builder.js';
-export type { Anchor, ShapeKind, DesignArtboard, BackgroundOptions, ImageOptions, TextOptions, ShapeOptions, } from '../design/design-builder.js';
+export type { Anchor, ShapeKind, DesignArtboard, StateArtboard, FromStateOptions, BackgroundOptions, ImageOptions, TextOptions, ShapeOptions, } from '../design/design-builder.js';
 export { readTemplateFields, withTemplateFields, TEMPLATE_FIELDS_KEY, } from '../design/template-fields.js';
 export type { TemplateField, TemplateTextField, TemplateImageField, TemplateColorField, TemplateSelectField, } from '../design/template-fields.js';
 export type { CanvasStateV1, SerializedArtboard, SerializedElement, DeserializeResult, ValidationResult, } from '../state/index.js';

package/dist/components/editor/EditorAdd.d.ts

@@ -6,6 +6,7 @@ export interface EditorAddProps {
 /**
  * The ⊕ add-element menu.
  *
- * @experimental ADR-0085; subject to change until the P4 gate.
+ * Stable since ADR-0085 P4 (the default editor is rebuilt from this public
+ * surface, CI-gated); additive-only from here.
  */
 export declare function EditorAdd({ className, style }: EditorAddProps): React.ReactElement;

package/dist/components/editor/EditorBuy.d.ts

@@ -55,6 +55,7 @@ export declare function evaluateBuyCompleteness(input: {
 /**
  * The add-to-cart button, completeness-gated and payload-assembling.
  *
- * @experimental ADR-0085; subject to change until the P4 gate.
+ * Stable since ADR-0085 P4 (the default editor is rebuilt from this public
+ * surface, CI-gated); additive-only from here.
  */
 export declare function EditorBuy(props: EditorBuyProps): React.ReactElement;

package/dist/components/editor/EditorCanvas.d.ts

@@ -24,7 +24,8 @@ export interface EditorCanvasProps {
  * (`E_DUPLICATE_CANVAS`); mount none for the no-canvas personalization
  * composition.
  *
- * @experimental ADR-0085; subject to change until the P4 gate.
+ * Stable since ADR-0085 P4 (the default editor is rebuilt from this public
+ * surface, CI-gated); additive-only from here.
  */
 export declare const EditorCanvas: React.ForwardRefExoticComponent<EditorCanvasProps & React.RefAttributes<SnowconeCanvasHandle>>;
 export type { EditorCanvasImplProps };

package/dist/components/editor/EditorControls.d.ts

@@ -9,6 +9,7 @@ export interface EditorControlsProps {
 /**
  * The contextual controls zone.
  *
- * @experimental ADR-0085; subject to change until the P4 gate.
+ * Stable since ADR-0085 P4 (the default editor is rebuilt from this public
+ * surface, CI-gated); additive-only from here.
  */
 export declare function EditorControls({ placement, className, style, }: EditorControlsProps): React.ReactElement | null;

package/dist/components/editor/EditorHistory.d.ts

@@ -6,6 +6,7 @@ export interface EditorHistoryProps {
 /**
  * Undo/redo for the editor document.
  *
- * @experimental ADR-0085; subject to change until the P4 gate.
+ * Stable since ADR-0085 P4 (the default editor is rebuilt from this public
+ * surface, CI-gated); additive-only from here.
  */
 export declare function EditorHistory({ className, style }: EditorHistoryProps): React.ReactElement;

package/dist/components/editor/EditorLayers.d.ts

@@ -11,6 +11,7 @@ export interface EditorLayersProps {
  * layers read-only); with a mounted `Editor.Canvas` it is the live document
  * panel.
  *
- * @experimental ADR-0085; subject to change until the P4 gate.
+ * Stable since ADR-0085 P4 (the default editor is rebuilt from this public
+ * surface, CI-gated); additive-only from here.
  */
 export declare function EditorLayers({ direction, className, style, }: EditorLayersProps): React.ReactElement;

package/dist/components/editor/EditorMenu.d.ts

@@ -6,6 +6,7 @@ export interface EditorMenuProps {
 /**
  * The editor's overflow menu.
  *
- * @experimental ADR-0085; subject to change until the P4 gate.
+ * Stable since ADR-0085 P4 (the default editor is rebuilt from this public
+ * surface, CI-gated); additive-only from here.
  */
 export declare function EditorMenu({ className, style }: EditorMenuProps): React.ReactElement;

package/dist/components/editor/EditorPreview.d.ts

@@ -34,6 +34,7 @@ export declare function resolutionMismatchHint(naturalWidth: number, devicePx: n
 /**
  * The live product mockup. Mount as many as you need under one Root.
  *
- * @experimental ADR-0085; subject to change until the P4 gate.
+ * Stable since ADR-0085 P4 (the default editor is rebuilt from this public
+ * surface, CI-gated); additive-only from here.
  */
 export declare function EditorPreview({ mockupId, fallback, alt, className, style, }: EditorPreviewProps): React.ReactElement;

package/dist/components/editor/EditorRoot.d.ts

@@ -81,6 +81,7 @@ export declare function slowRenderHint(placement: string): string;
  * model; see `RealtimeEmbed` for the legacy turnkey wrapper this was
  * extracted from.
  *
- * @experimental ADR-0085; subject to change until the P4 gate.
+ * Stable since ADR-0085 P4 (the default editor is rebuilt from this public
+ * surface, CI-gated); additive-only from here.
  */
 export declare function EditorRoot(props: EditorRootProps): React.ReactElement;

package/dist/components/editor/EditorTextField.d.ts

@@ -17,6 +17,7 @@ export interface EditorTextFieldProps {
  * A text input bound to a design layer. Works with or without a mounted
  * `Editor.Canvas`.
  *
- * @experimental ADR-0085; subject to change until the P4 gate.
+ * Stable since ADR-0085 P4 (the default editor is rebuilt from this public
+ * surface, CI-gated); additive-only from here.
  */
 export declare function EditorTextField(props: EditorTextFieldProps): React.ReactElement;

package/dist/components/editor/useProductSelection.d.ts

@@ -34,6 +34,7 @@ export interface ProductSelectionApi {
 /**
  * Read/write the Buy-owned product selection under this `Editor.Root`.
  *
- * @experimental ADR-0085; subject to change until the P4 gate.
+ * Stable since ADR-0085 P4 (the default editor is rebuilt from this public
+ * surface, CI-gated); additive-only from here.
  */
 export declare function useProductSelection(): ProductSelectionApi;

package/dist/components/embed/SnowconeCanvas.d.ts

@@ -1,9 +1,9 @@
 import { default as React } from 'react';
 import { CanvasServices } from '../../contexts/CanvasServicesContext.js';
-import { CanvasError, ClipShape, AnyElementConfig } from '../../types/index.js';
+import { CanvasError, ArtboardRole, ClipShape, AnyElementConfig } from '../../types/index.js';
 import { KitPresetId, KitDefinition } from '../../kits/types.js';
 import { PieceGuide, PieceGuideRendererPiece, PieceGuideRendererStyle, PieceGuideVisibility } from '../../rendering/PieceGuideRenderer.js';
-export type { ClipShape } from '../../types/index.js';
+export type { ClipShape, ArtboardRole } from '../../types/index.js';
 /** 9-point alignment grid values */
 export type AlignmentPoint = 'tl' | 't' | 'tr' | 'l' | 'c' | 'r' | 'bl' | 'b' | 'br' | 'center' | 'top' | 'bottom' | 'left' | 'right';
 /** Events emitted during the export lifecycle */
@@ -41,6 +41,14 @@ export interface ArtboardConfig {
      * match the editor.
      */
     exportBackground?: boolean;
+    /**
+     * Pacing role in a multi-page template (ADR-0086 albums):
+     * `'cover' | 'front-matter' | 'repeating' | 'back-matter'`. Template
+     * metadata only — auto-fill clones `repeating` spreads as the page count
+     * grows. Round-trips through saved states and `onChange`; never sent on
+     * the server render wire (`serializeStateForServer` strips it).
+     */
+    role?: ArtboardRole;
     /** Scale mode for initial image: "cover" fills area (may crop), "contain" fits inside (may have space). Default: "cover" */
     scaleMode?: 'cover' | 'contain';
     /** Top margin in pixels for contain mode (reduces available area) */

package/dist/components/embed-realtime/context.d.ts

@@ -39,7 +39,7 @@ export interface EmbedContextValue {
      * write, last-write-wins. Commerce parts read THIS, never the seed. Stable
      * identity; subscribe for updates (`useSyncExternalStore`-shaped).
      *
-     * @experimental ADR-0085; subject to change until the P4 gate.
+     * Stable since ADR-0085 P4; additive-only from here.
      */
     stateStore: DesignStateStore;
 }

package/dist/contexts/EditorContext.d.ts

@@ -191,7 +191,7 @@ export declare const EditorProvider: React.FC<EditorProviderProps>;
  * - **Undo/redo**: `undo`, `redo`, `canUndo`, `canRedo`
  *
  * Everything else on the returned value is `@experimental` and may change in
- * minors until the P4 gate (the default editor rebuilt from public parts).
+ * minors — the stable subset above is the documented headless contract.
  *
  * Must be called inside an `EditorProvider`. For focused access, prefer the
  * sub-context hooks which expose smaller slices of state and cause fewer re-renders:

package/dist/core/ArtboardElement.d.ts

@@ -1,7 +1,7 @@
 import { TextElement } from './TextElement.js';
 import { ImageElement } from './ImageElement.js';
 import { GroupElement } from './GroupElement.js';
-import { BoundingBox, Point, ArtboardConfig, ArtboardBackgroundType, ArtboardDistressTexture, ArtboardImageMask, ClipShape } from '../types/index.js';
+import { BoundingBox, Point, ArtboardConfig, ArtboardBackgroundType, ArtboardDistressTexture, ArtboardImageMask, ArtboardRole, ClipShape } from '../types/index.js';
 export declare class ArtboardElement {
     id: string;
     name: string;
@@ -16,6 +16,7 @@ export declare class ArtboardElement {
     transformType: 'artboard';
     clipShape?: ClipShape;
     previewBackgroundColor?: string;
+    role?: ArtboardRole;
     distressTexture?: ArtboardDistressTexture;
     imageMask?: ArtboardImageMask;
     private elementIds;

package/dist/default-editor/SnowconeEditor.d.ts

@@ -0,0 +1,40 @@
+import { default as React, CSSProperties } from 'react';
+import { EditorRootBaseProps, EditorBuyPayload, GrantSource } from '../api/embed.js';
+export type SnowconeEditorProps = GrantSource & Omit<EditorRootBaseProps, 'children' | '__validation'> & {
+    /** The final submit — your one line. Variant/quantity/completeness and
+     *  payload assembly are `Editor.Buy`'s job. */
+    onAddToCart: (payload: EditorBuyPayload) => void | Promise<void>;
+    /** Seeds the Buy-owned quantity once on mount (default 1). */
+    defaultQuantity?: number;
+    /** Header title. Default "Editor". */
+    title?: string;
+    /** Embedded-card height (px or CSS length). Fullscreen ignores it. */
+    height?: number | string;
+    className?: string;
+    style?: CSSProperties;
+};
+/** Price label for the Buy pill — catalog prices are cents. Whole dollars
+ *  render without cents ("$24"), like the PDP. */
+export declare function formatBuyPrice(cents: number): string;
+/**
+ * The turnkey Snowcone editor — the same public parts, our arrangement.
+ *
+ * ```tsx
+ * import { SnowconeEditor, design } from '@snowcone-app/canvas/embed';
+ *
+ * <SnowconeEditor
+ *   shop={SHOP_KEY}
+ *   product={{ productId: 'BEEB77', mockupIds: ['FV1qjO'], variantId: 'Pv1sLC', placements: ['Front'] }}
+ *   design={design({ name: 'Front', width: 1480, height: 2328 }).text('hello', { name: 'headline' })}
+ *   grantUrl="/api/realtime/grant"
+ *   onAddToCart={(payload) => persist(payload.designState)}
+ * />
+ * ```
+ *
+ * Customizing beyond the props means composing `Editor.*` yourself — this
+ * component is ~300 lines of public-surface composition you can copy and own.
+ *
+ * Stable since ADR-0085 P4 (this component IS the gate artifact — composed
+ * only from the public embed entry); additive-only from here.
+ */
+export declare function SnowconeEditor(props: SnowconeEditorProps): React.ReactElement;

package/dist/design/design-builder.d.ts

@@ -1,4 +1,4 @@
-import { AnyElementConfig } from '../types/index.js';
+import { AnyElementConfig, ArtboardRole } from '../types/index.js';
 import { ServerRenderRequest } from '../rendering/serialize-for-server.js';
 /** A nine-point anchor: where the element sits relative to the artboard. */
 export type Anchor = 'top-left' | 'top' | 'top-right' | 'left' | 'center' | 'right' | 'bottom-left' | 'bottom' | 'bottom-right';
@@ -14,6 +14,32 @@ export interface DesignArtboard {
     /** Optional solid background fill behind all elements. Rendered everywhere
      *  the design is — editor, exports, and server renders (realtime mockups). */
     backgroundColor?: string;
+    /** Pacing role in a multi-page template (ADR-0086 albums). Template
+     *  metadata only — never sent on the server render wire. */
+    role?: ArtboardRole;
+}
+/** One artboard of a saved multi-artboard state, as {@link DesignBuilder.fromState}
+ *  accepts and `toJSON()` emits. */
+export interface StateArtboard {
+    name: string;
+    width: number;
+    height: number;
+    backgroundColor?: string;
+    exportBackground?: boolean;
+    /** Pacing role in a multi-page template (ADR-0086 albums). */
+    role?: ArtboardRole;
+}
+export interface FromStateOptions {
+    /**
+     * Which artboards to load:
+     * - `'active'` (default) — today's behavior: the active artboard becomes the
+     *   builder's artboard; elements tagged for other artboards are skipped.
+     * - `'all'` — multi-page templates (ADR-0086): every artboard and its
+     *   elements are kept, with `artboard` membership tags preserved, so
+     *   `toJSON()` / `toServerRequest()` stay multi-artboard. Template fields
+     *   scope per page via `TemplateField.artboard`.
+     */
+    artboards?: 'active' | 'all';
 }
 /** A stable layer name. Set it so you can bind the layer in an interactive
  *  `<SnowconeCanvas/>` editor — `useImageBinding(name)` / `useTextBinding(name)`
@@ -85,7 +111,8 @@ declare const LAYER_TOKEN_BRAND: unique symbol;
  * accepts — bare strings are rejected (`E_LAYER_TOKEN_REQUIRED`). Mint with
  * {@link DesignBuilder.layer}; not constructible by hand (branded).
  *
- * @experimental ADR-0085; subject to change until the P4 gate.
+ * Stable since ADR-0085 P4 (the default editor is rebuilt from this public
+ * surface, CI-gated); additive-only from here.
  */
 export interface LayerToken<K extends LayerKind = LayerKind, N extends string = string> {
     readonly kind: K;
@@ -118,6 +145,9 @@ export declare class DesignBuilder<out TText extends string = string, out TImage
     private readonly artboard;
     private readonly els;
     private idCounter;
+    /** Every artboard of a multi-page state (fromState `{ artboards: 'all' }`);
+     *  unset for single-artboard builders. */
+    private allArtboards?;
     constructor(artboard: DesignArtboard);
     /**
      * Seed a builder from a previously saved canvas state — the editor shape
@@ -125,20 +155,20 @@ export declare class DesignBuilder<out TText extends string = string, out TImage
      *
      * This is how a saved editable template re-enters the turnkey embed path:
      * load the template's state JSON, lift it back into a `DesignBuilder`, and
-     * hand it to `<RealtimeEmbed design={…}>`. The active artboard becomes the
-     * builder's artboard; elements tagged for other artboards are skipped
-     * (untagged elements are assumed to belong to the active one).
+     * hand it to `<RealtimeEmbed design={…}>`. By default the active artboard
+     * becomes the builder's artboard; elements tagged for other artboards are
+     * skipped (untagged elements are assumed to belong to the active one).
+     *
+     * Pass `{ artboards: 'all' }` to load a multi-page template (ADR-0086)
+     * whole: every artboard (with its pacing `role`) and every element are
+     * kept, membership tags preserved, so `toJSON()` / `toServerRequest()`
+     * emit all pages and `TemplateField.artboard` can scope fields per page.
      */
     static fromState(state: {
         elements: AnyElementConfig[];
-        artboards: Array<{
-            name: string;
-            width: number;
-            height: number;
-            backgroundColor?: string;
-        }>;
+        artboards: StateArtboard[];
         activeArtboard: string;
-    }): DesignBuilder;
+    }, options?: FromStateOptions): DesignBuilder;
     private nextId;
     /** Full-bleed background image (fills the whole artboard). Cover-fit (no
      *  distortion) when `aspectRatio` is supplied. Inserted at the bottom of the
@@ -172,7 +202,6 @@ export declare class DesignBuilder<out TText extends string = string, out TImage
      *   the valid names per kind.
      * @throws EditorError `E_LAYER_WRONG_KIND` — the name matches a layer that
      *   is not bindable (shape/group/path).
-     * @experimental ADR-0085; subject to change until the P4 gate.
      */
     layer<N extends TText | TImage>(name: N): LayerToken<InferKind<N, TText, TImage>, N>;
     /** Names of bindable layers of one kind, in stack order. @internal */
@@ -182,16 +211,12 @@ export declare class DesignBuilder<out TText extends string = string, out TImage
     /** The composed elements, in render order (background first). Editor shape. */
     get elements(): AnyElementConfig[];
     /** Editor-shape canvas state for `<SnowconeCanvas initialElements=… />` and
-     *  `serializeStateForServer`. `activeArtboard` is the artboard name. */
+     *  `serializeStateForServer`. `activeArtboard` is the artboard name. A
+     *  builder loaded with `fromState(…, { artboards: 'all' })` emits every
+     *  page (artboard `role`s and element membership tags included). */
     toJSON(): {
         elements: AnyElementConfig[];
-        artboards: Array<{
-            name: string;
-            width: number;
-            height: number;
-            backgroundColor?: string;
-            exportBackground?: boolean;
-        }>;
+        artboards: StateArtboard[];
         activeArtboard: string;
     };
     /** Server-render payload for `RenderSession.renderState(placement, …)`.

package/dist/design/template-fields.d.ts

@@ -14,6 +14,14 @@ export interface TemplateTextField {
      * `maxLength`); the canvas itself doesn't truncate.
      */
     maxLength?: number;
+    /**
+     * Artboard (page) this field is scoped to, by artboard NAME — the same
+     * convention as the element `artboard` membership tag. In a multi-page
+     * template (ADR-0086) the same element name can repeat on every page;
+     * scoping disambiguates which page's element the field binds. Absent =
+     * whole-design (legacy behavior: binds across all artboards).
+     */
+    artboard?: string;
     /** Optional grouping label — consecutive fields sharing a group render together. */
     group?: string;
 }
@@ -28,6 +36,14 @@ export interface TemplateImageField {
     placeholder?: string;
     /** How the buyer's image fits the original element bounds. Default: "cover". */
     fit?: ImageFitMode;
+    /**
+     * Artboard (page) this field is scoped to, by artboard NAME — the same
+     * convention as the element `artboard` membership tag. In a multi-page
+     * template (ADR-0086) the same element name can repeat on every page;
+     * scoping disambiguates which page's element the field binds. Absent =
+     * whole-design (legacy behavior: binds across all artboards).
+     */
+    artboard?: string;
     /** Optional grouping label — consecutive fields sharing a group render together. */
     group?: string;
 }
@@ -38,6 +54,14 @@ export interface TemplateColorField {
     color: string;
     /** Label shown to the buyer (e.g. "Accent color"). */
     label: string;
+    /**
+     * Artboard (page) this field is scoped to, by artboard NAME — the same
+     * convention as the element `artboard` membership tag. In a multi-page
+     * template (ADR-0086) the same element name can repeat on every page;
+     * scoping disambiguates which page's element the field binds. Absent =
+     * whole-design (legacy behavior: binds across all artboards).
+     */
+    artboard?: string;
     /** Optional grouping label — consecutive fields sharing a group render together. */
     group?: string;
 }
@@ -64,6 +88,14 @@ export interface TemplateSelectField {
         label: string;
         value: string;
     }>;
+    /**
+     * Artboard (page) this field is scoped to, by artboard NAME — the same
+     * convention as the element `artboard` membership tag. In a multi-page
+     * template (ADR-0086) the same element name can repeat on every page;
+     * scoping disambiguates which page's element the field binds. Absent =
+     * whole-design (legacy behavior: binds across all artboards).
+     */
+    artboard?: string;
     /** Optional grouping label — consecutive fields sharing a group render together. */
     group?: string;
 }