@snowcone-app/canvas 0.23.0 → 0.27.0

package/dist/advanced.mjs

@@ -1,21 +1,21 @@
-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-CC3CSmH5.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-CC3CSmH5.js";
-import { r as oe, v as ae } from "./validation-C9Fe9ahK.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, K as Ct, g as Tt, L as Et, S as $t, T as kt, Z as At, h as Ft, i as Pt, j as Nt, k as Rt, l as Bt, m as Mt, n as Dt, u as It, o as zt, p as Ot } from "./validation-C9Fe9ahK.js";
-import { ImagePanel as Wt } from "./ImagePanel-BwqFDKvW.js";
-import { P as ie, a as ce, b as le } from "./ContextualToolbars-BDEt9ND0.js";
-import { A as Gt, B as _t, c as Ut, C as jt, d as Jt, e as qt, F as Zt, f as Vt, I as Xt, g as Yt, M as Ht, h as Qt, S as er, T as tr, i as rr, j as nr, k as sr, U as or, l as ar, u as ir, m as cr } from "./ContextualToolbars-BDEt9ND0.js";
-import { u as Z } from "./editorErrors-B2mb1sVN.js";
-import { E as dr, P as ur, p as mr, s as fr, b as hr, c as pr, d as xr, e as gr, f as br, a as yr } from "./editorErrors-B2mb1sVN.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-CHVYDBDW.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-CHVYDBDW.js";
+import { r as oe, v as ae } from "./validation-DGXAQmUC.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, K as Ct, g as Tt, L as Et, S as $t, T as kt, Z as At, h as Ft, i as Pt, j as Nt, k as Rt, l as Bt, m as Mt, n as Dt, u as It, o as zt, p as Ot } from "./validation-DGXAQmUC.js";
+import { ImagePanel as Wt } from "./ImagePanel-CIk6z41z.js";
+import { P as ie, a as ce, b as le } from "./ContextualToolbars-BHjYsril.js";
+import { A as Gt, B as _t, c as Ut, C as jt, d as Jt, e as qt, F as Zt, f as Vt, I as Xt, g as Yt, M as Ht, h as Qt, S as er, T as tr, i as rr, j as nr, k as sr, U as or, l as ar, u as ir, m as cr } from "./ContextualToolbars-BHjYsril.js";
+import { u as Z } from "./editorErrors-BhrZ_nwj.js";
+import { E as dr, P as ur, p as mr, s as fr, b as hr, c as pr, d as xr, e as gr, f as br, a as yr } from "./editorErrors-BhrZ_nwj.js";
 import { T as wr, u as Sr } 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-CwIpgTGd.js";
-import { A as Tr, B as Er, I as $r, P as kr, R as Ar, S as Fr, T as Pr, h as Nr, a as Rr, b as Br, i as Mr, d as Dr, e as Ir, f as zr, j as Or, k as Lr, l as Wr, m as Kr, n as Gr, o as _r, p as Ur, q as jr, s as Jr, t as qr, v as Zr, w as Vr, x as Xr } from "./FontAnalyzer-CwIpgTGd.js";
-import { i as Hr, a as Qr, b as en, c as tn, d as rn } from "./guards-8rkFAMBs.js";
+import { c as de, G as ue, F as me, g as fe, r as he, u as pe } from "./FontAnalyzer-EF3gLPr8.js";
+import { A as Tr, B as Er, I as $r, P as kr, R as Ar, S as Fr, T as Pr, h as Nr, a as Rr, b as Br, i as Mr, d as Dr, e as Ir, f as zr, j as Or, k as Lr, l as Wr, m as Kr, n as Gr, o as _r, p as Ur, q as jr, s as Jr, t as qr, v as Zr, w as Vr, x as Xr } from "./FontAnalyzer-EF3gLPr8.js";
+import { i as Hr, a as Qr, b as en, c as tn, d as rn } from "./guards-DIX8aXWM.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 "./ExportManager-DoU4VK6h.js";
+import { I as ge } from "./ExportManager-BTcyj4cf.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 sn, p as on, u as an } from "./usePieceGuideBundle-CbJJg66S.js";
+import { P as sn, p as on, u as an } from "./usePieceGuideBundle-DE21DQGZ.js";
 const ze = ({
   title: e,
   icon: t,

package/dist/api/embed.d.ts

@@ -34,8 +34,8 @@
  *
  * @packageDocumentation
  */
-export { Editor, DesignStateStore, useProductSelection } from '../components/editor/index.js';
-export type { EditorRootProps, EditorRootBaseProps, EditorCanvasProps, EditorPreviewProps, EditorTextFieldProps, EditorBuyProps, EditorBuyPayload, BuyMissingReason, DesignState, EditorLayersProps, EditorControlsProps, EditorHistoryProps, EditorMenuProps, EditorAddProps, ProductSelectionApi, ProductOptionChoice, ProductSelectionAttribute, } from '../components/editor/index.js';
+export { Editor, DesignStateStore, useProductSelection, usePlacements, auditEditor } from '../components/editor/index.js';
+export type { EditorAuditReport, EditorAuditFinding, EditorAuditFindingCode, EditorRootProps, EditorRootBaseProps, EditorCanvasProps, EditorPlacementsProps, PlacementInfo, UsePlacementsReturn, EditorPreviewProps, EditorLoadingOverlayProps, EditorTextFieldProps, EditorBuyProps, EditorBuyPayload, BuyMissingReason, DesignState, EditorLayersProps, EditorControlsProps, EditorHistoryProps, EditorMenuProps, EditorAddProps, ProductSelectionApi, ProductOptionChoice, ProductSelectionAttribute, } from '../components/editor/index.js';
 export { EditorError, isEditorError } from '../errors/editorError.js';
 export type { EditorErrorCode, EditorErrorData } from '../errors/editorError.js';
 export { RealtimeEmbed } from '../components/embed-realtime/RealtimeEmbed.js';
@@ -55,10 +55,14 @@ export { design, DesignBuilder, isLayerToken, isColorToken } from '../design/des
 export type { Anchor, ShapeKind, DesignArtboard, StateArtboard, FromStateOptions, AnyDesign, LayerKind, LayerToken, ColorToken, } from '../design/design-builder.js';
 export { useEditor } from '../contexts/EditorContext.js';
 export type { EditorContextValue, EditorProviderProps } from '../contexts/EditorContext.js';
+export type { EditorElement, AddElementSpec, ElementHandle } from '../contexts/EditorContext.js';
+export { isTextElement, isImageElement, isShapeElement, isGroupElement, isPathElement, editorElementKind, } from '../core/elementGuards.js';
+export type { EditorElementKind } from '../core/elementGuards.js';
 export { useLayers } from '../hooks/useLayers.js';
 export type { LayerInfo, UseLayersOptions, UseLayersReturn } from '../hooks/useLayers.js';
 export { useCommands } from '../hooks/useCommands.js';
 export type { UseCommandsReturn } from '../hooks/useCommands.js';
+export type { ElementPatch, UpdateElementOptions } from '../hooks/elementPatch.js';
 export { useArtboards } from '../hooks/useArtboards.js';
 export type { ArtboardInfo, UseArtboardsReturn } from '../hooks/useArtboards.js';
 export { useExport } from '../hooks/useExport.js';

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

@@ -0,0 +1,12 @@
+import { default as React, CSSProperties } from 'react';
+export interface EditorLoadingOverlayProps {
+    /** "dark" (default): screen-blended neon bands for image/dark surfaces.
+     *  "light": multiply-blended candy bands for light cards. */
+    variant?: 'dark' | 'light';
+    className?: string;
+    style?: CSSProperties;
+}
+/**
+ * Stable since ADR-0085 P4 (additive); part name: `loading-overlay`.
+ */
+export declare function EditorLoadingOverlay({ variant, className, style, }: EditorLoadingOverlayProps): React.ReactElement | null;

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

@@ -0,0 +1,14 @@
+import { default as React, CSSProperties } from 'react';
+export interface EditorPlacementsProps {
+    className?: string;
+    style?: CSSProperties;
+}
+/**
+ * Placement tabs for a multi-placement design.
+ *
+ * Styling contract: `data-sc-part="placements"` on the row,
+ * `data-sc-part="placements-item"` + `data-sc-active="true|false"` +
+ * `aria-pressed` per tab — restyle via those hooks and the `.sc-root` tokens;
+ * the built-in styling is deliberately minimal.
+ */
+export declare function EditorPlacements({ className, style }: EditorPlacementsProps): React.ReactElement | null;

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

@@ -1,4 +1,4 @@
-import { default as React, CSSProperties, ReactNode } from 'react';
+import { default as React, CSSProperties, ReactElement, ReactNode } from 'react';
 export interface EditorPreviewProps {
     /** Which mockup scene to show (a `product.mockupIds` entry). Defaults to the
      *  first mockup that has rendered. */
@@ -8,6 +8,36 @@ export interface EditorPreviewProps {
     fallback?: ReactNode;
     /** Alt text for the rendered image. */
     alt?: string;
+    /**
+     * The render-in-flight loading treatment. A mockup preview ALWAYS has one:
+     * a server render takes real time, and the loader paints OVER the
+     * still-visible previous mockup — it never blanks or replaces it.
+     *
+     * **Defaults to `"dark"`** — the snowcone rainbow (the www PDP's prism
+     * loader): screen-blended neon bands shimmering over the previous mockup,
+     * with a 200ms show-delay (cached/instant renders never flash it) and a
+     * 400ms post-render linger. `"light"`: multiply-blended candy bands on an
+     * opaque light plate, for previews on light cards. Pass a custom
+     * `ReactElement` to render your own indicator instead — it mounts inside
+     * the frame (absolutely positioned over the image) with the same
+     * show-delay/linger choreography.
+     *
+     * In all of the above the part is a positioned stage:
+     * `data-sc-part="preview"` is a `.sc-preview-frame` div (which receives
+     * `className`/`style`), the `<img>` inside is
+     * `data-sc-part="preview-image"`, and the loading layer is
+     * `data-sc-part="preview-loading"`.
+     *
+     * `"host-owned"` reverts to the bare `<img>` DOM with no overlay — pass it
+     * ONLY when the host renders its own indicator, via the styling contract
+     * (`data-sc-preview-state="rendering"`) or the standalone
+     * `<Editor.LoadingOverlay>` part.
+     *
+     * Anything else (`false`, `"none"`, …) throws `E_PREVIEW_NO_LOADER`, dev
+     * AND prod: a mockup surface with no loading affordance is a composition
+     * mistake (silent emptiness, then pop-in), not a preference.
+     */
+    loadingOverlay?: true | 'dark' | 'light' | 'host-owned' | ReactElement;
     className?: string;
     style?: CSSProperties;
 }
@@ -31,10 +61,4 @@ export declare function suggestRenderWidth(devicePx: number): number;
  * {@link RESOLUTION_MISMATCH_RATIO}) or either measurement is unusable.
  */
 export declare function resolutionMismatchHint(naturalWidth: number, devicePx: number): string | null;
-/**
- * The live product mockup. Mount as many as you need under one Root.
- *
- * 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;
+export declare function EditorPreview({ mockupId, fallback, alt, loadingOverlay, className, style, }: EditorPreviewProps): React.ReactElement;

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

@@ -3,6 +3,7 @@ import { RenderProduct, MockupResult, RealtimeGrant } from '@snowcone-app/sdk';
 import { AnyDesign } from '../../design/design-builder.js';
 import { CanvasServices } from '../../contexts/CanvasServicesContext.js';
 import { EmbedIssue } from '../embed-realtime/validateEmbed.js';
+import { EditorAuditReport } from './editorAudit.js';
 /**
  * How the session authorizes. Provide exactly one — the discriminated union makes
  * "I forgot the grant" a compile error rather than a silent runtime hang.
@@ -52,6 +53,17 @@ export type EditorRootBaseProps = {
      * boundary.)
      */
     onIssue?: (issue: EmbedIssue) => void;
+    /**
+     * The composition-audit channel (`Editor.audit()`, agentic-DX #10): fires
+     * ONCE after mount settles (every part's layout-effect registration is in,
+     * the design store holds its first snapshot), dev AND prod — like
+     * `onIssue`, a machine-readable callback, never console output. The report
+     * lists structured findings (stable `A_*` codes, each with the fix) plus a
+     * census of mounted parts. It fires even when a composition mistake throws
+     * into Root's boundary, carrying the registry state the throw saw. For a
+     * fresh report after interacting, call `auditEditor()`.
+     */
+    onAudit?: (report: EditorAuditReport) => void;
     /** Override the realtime WS endpoint (defaults to the SDK's prod URL). */
     wsUrl?: string;
     /**

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

@@ -0,0 +1,23 @@
+import { default as React } from 'react';
+export interface PreviewPrismOverlayProps {
+    /** When false, fade out then call onExited (use it to unmount). */
+    visible?: boolean;
+    onExited?: () => void;
+    /** "dark" (default): screen-blended neon bands for image/dark stages.
+     *  "light": multiply-blended candy bands on an opaque light plate. */
+    variant?: 'dark' | 'light';
+}
+export declare const PreviewPrismOverlay: React.NamedExoticComponent<PreviewPrismOverlayProps>;
+/**
+ * Show/hide choreography for a render-in-flight overlay: show-delayed mount
+ * (fast renders never flash it), post-render linger, fade-out unmount.
+ * Mirrors @snowcone-app/ui's `useLoadingOverlay` + the PDP hero's linger.
+ */
+export declare function useRenderLoadingOverlay(isLoading: boolean): {
+    /** Mount the overlay? */
+    showOverlay: boolean;
+    /** The overlay's `visible` prop (false starts the fade-out). */
+    overlayVisible: boolean;
+    /** Pass as `onExited` — unmounts after the fade. */
+    handleExited: () => void;
+};

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

@@ -14,11 +14,24 @@ export interface TextFieldRegistration {
     name: string;
     optional: boolean;
 }
+/** Audit-relevant facts a part declares alongside its census registration
+ *  (`Editor.audit()`, #10). Every key is optional — most parts have none. */
+export interface EditorPartMeta {
+    /** `Editor.Preview`: the pinned mockup scene, when the prop was given. */
+    mockupId?: string;
+    /** `Editor.Canvas`: the `floatingToolbar` prop value (default `true`). */
+    floatingToolbar?: boolean;
+}
+export interface EditorPartRegistration {
+    name: string;
+    meta: EditorPartMeta;
+}
 export declare class EditorPartsRegistry {
     private canvasIds;
     private requirements;
     private textFields;
     private controls;
+    private parts;
     private bridge;
     private listeners;
     private version;
@@ -51,6 +64,15 @@ export declare class EditorPartsRegistry {
      *  suppressing (it declares today's default explicitly). */
     registerControls(instanceId: string, placement: 'docked' | 'floating'): () => void;
     hasDockedControls(): boolean;
+    /** Census registration (`Editor.audit()`, #10): every mounted part records
+     *  its public name + audit-relevant meta. Purely observational — nothing
+     *  validates through this map. */
+    registerPart(instanceId: string, name: string, meta?: EditorPartMeta): () => void;
+    /** Every mounted part's census entry (audit input). */
+    getParts(): EditorPartRegistration[];
+    /** Unique public names of mounted parts that declared a canvas requirement
+     *  (audit input — same data `validate()` throws `E_REQUIRES_CANVAS` from). */
+    requiresCanvasPartNames(): string[];
     registerCanvasBridge(bridge: CanvasBridge): () => void;
     getCanvasBridge(): CanvasBridge | null;
     private bump;
@@ -89,6 +111,15 @@ export declare function useEditorRootInternals(partName: string): EditorRootInte
  * `E_REQUIRES_CANVAS`, validated race-free by Root once per commit).
  */
 export declare function useRequiresCanvas(partName: string): void;
+/**
+ * Census registration for the composition audit (`Editor.audit()`, #10):
+ * every `Editor.*` part calls this with its public name (+ audit-relevant
+ * meta) so the audit report can list what is mounted. Deliberately TOLERANT
+ * of a missing Root (no `E_OUTSIDE_ROOT` here): the parts that require a Root
+ * already enforce it through their own hooks, and `Editor.Preview` stays
+ * mountable under the legacy wrappers without a new throw path.
+ */
+export declare function useRegisterEditorPart(partName: string, meta?: EditorPartMeta): void;
 /** Shared impl of the invariant channel. @internal */
 export declare function makeInvariantReporter(routeToErrorState: (error: EditorError) => void): {
     reportInvariant: (error: EditorError) => void;

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

@@ -0,0 +1,66 @@
+import { RenderProduct } from '@snowcone-app/sdk';
+import { DesignStateStore } from './designStateStore.js';
+import { EditorPartsRegistry } from './RootInternals.js';
+/** Stable audit finding codes — the test/agent contract. */
+export type EditorAuditFindingCode = 
+/** Requires-canvas parts (Controls/History/Menu/Add) are mounted with no
+ *  `Editor.Canvas` — the same composition `E_REQUIRES_CANVAS` throws on. */
+'A_REQUIRES_CANVAS'
+/** A docked `Editor.Controls` is mounted while `Editor.Canvas` still has
+ *  `floatingToolbar` true (the default) — contextual-zone ownership is
+ *  implied by mount order (spooky), not declared in the type surface. */
+ | 'A_CONTROLS_INERT'
+/** `Editor.Preview` without `mockupId` while the product renders more than
+ *  one mockup scene — which scene the preview shows is ambiguous. */
+ | 'A_PREVIEW_AMBIGUOUS'
+/** `Editor.TextField` parts are mounted but no `Editor.Buy` — there is no
+ *  commerce gate enforcing completeness before checkout. */
+ | 'A_NO_BUY'
+/** A mounted `Editor.TextField`'s layer matches zero elements in the
+ *  CURRENT design snapshot — the binding is dead; writes will fail. */
+ | 'A_LAYER_UNMATCHED'
+/** Every required (non-`optional`) `Editor.TextField` still equals its
+ *  seed value — Buy's completeness rule C3 gates checkout until edited. */
+ | 'A_TEXT_AT_SEED'
+/** Zero renderable elements in the design — every mockup renders blank. */
+ | 'A_EMPTY_DESIGN';
+export interface EditorAuditFinding {
+    code: EditorAuditFindingCode;
+    severity: 'error' | 'warn' | 'info';
+    /** What is wrong, with the facts (part names, layer names, scene ids). */
+    message: string;
+    /** The exact prop/part change that resolves the finding. */
+    fix: string;
+}
+export interface EditorAuditReport {
+    findings: EditorAuditFinding[];
+    /** Census of mounted parts, e.g. `{ name: 'Editor.Preview', count: 2 }`.
+     *  Sorted by name for determinism. */
+    parts: Array<{
+        name: string;
+        count: number;
+    }>;
+}
+/** @internal */
+export interface EditorAuditInput {
+    registry: EditorPartsRegistry;
+    store: DesignStateStore;
+    product: RenderProduct;
+}
+/** Compute the audit report from a Root's live registry + design state.
+ *  Pure — no logging, no throwing. @internal */
+export declare function computeEditorAudit({ registry, store, product }: EditorAuditInput): EditorAuditReport;
+interface RootAuditEntry {
+    compute: () => EditorAuditReport;
+}
+/** Register a mounted Root as an audit target (most-recent wins). @internal */
+export declare function registerRootForAudit(entry: RootAuditEntry): () => void;
+/**
+ * Audit the most-recent mounted `<Editor.Root>`'s composition NOW — a fresh
+ * report from the live part registry + design state, so it reflects whatever
+ * has happened since mount (fields edited, parts mounted/unmounted).
+ *
+ * Throws `E_AUDIT_NO_ROOT` when no Root is mounted.
+ */
+export declare function auditEditor(): EditorAuditReport;
+export {};

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

@@ -1,4 +1,5 @@
 import { EditorRoot } from './EditorRoot.js';
+import { EditorPlacements } from './EditorPlacements.js';
 import { EditorPreview } from './EditorPreview.js';
 import { EditorTextField } from './EditorTextField.js';
 import { EditorBuy } from './EditorBuy.js';
@@ -7,6 +8,7 @@ import { EditorControls } from './EditorControls.js';
 import { EditorHistory } from './EditorHistory.js';
 import { EditorMenu } from './EditorMenu.js';
 import { EditorAdd } from './EditorAdd.js';
+import { EditorLoadingOverlay } from './EditorLoadingOverlay.js';
 export declare const Editor: {
     /** The one provider boundary — session, design, live state, error boundary. */
     readonly Root: typeof EditorRoot;
@@ -14,6 +16,9 @@ export declare const Editor: {
     readonly Canvas: import('react').ForwardRefExoticComponent<import('./EditorCanvas.js').EditorCanvasProps & import('react').RefAttributes<import('./EditorCanvasImpl.js').SnowconeCanvasHandle>>;
     /** Live product mockup. ×N under one Root is valid. */
     readonly Preview: typeof EditorPreview;
+    /** Placement switcher tabs (ADR-0088). Renders nothing for a
+     *  single-placement design; headless floor = usePlacements(). */
+    readonly Placements: typeof EditorPlacements;
     /** Form input bound to a design text layer by typed token (T1). */
     readonly TextField: typeof EditorTextField;
     /** Smart commerce part: completeness + payload assembly; submit = host callback. */
@@ -28,10 +33,17 @@ export declare const Editor: {
     readonly Menu: typeof EditorMenu;
     /** The ⊕ add-element menu. Requires Editor.Canvas. */
     readonly Add: typeof EditorAdd;
+    /** Standalone render-in-flight rainbow for host-owned preview surfaces.
+     *  Fills its positioned parent; rides the session (canvas-free). */
+    readonly LoadingOverlay: typeof EditorLoadingOverlay;
 };
 export type { EditorRootProps, EditorRootBaseProps, GrantSource } from './EditorRoot.js';
 export type { EditorCanvasProps } from './EditorCanvas.js';
+export type { EditorPlacementsProps } from './EditorPlacements.js';
+export { usePlacements } from './usePlacements.js';
+export type { PlacementInfo, UsePlacementsReturn } from './usePlacements.js';
 export type { EditorPreviewProps } from './EditorPreview.js';
+export type { EditorLoadingOverlayProps } from './EditorLoadingOverlay.js';
 export type { EditorTextFieldProps } from './EditorTextField.js';
 export type { EditorBuyProps, EditorBuyPayload, BuyMissingReason } from './EditorBuy.js';
 export type { DesignState } from './designStateStore.js';
@@ -40,6 +52,8 @@ export { useProductSelection } from './useProductSelection.js';
 export type { ProductSelectionApi } from './useProductSelection.js';
 export { CommerceStateStore } from './commerceStore.js';
 export type { ProductOptionChoice, ProductSelectionAttribute } from './commerceStore.js';
+export { auditEditor } from './editorAudit.js';
+export type { EditorAuditReport, EditorAuditFinding, EditorAuditFindingCode } from './editorAudit.js';
 export type { EditorLayersProps } from './EditorLayers.js';
 export type { EditorControlsProps } from './EditorControls.js';
 export type { EditorHistoryProps } from './EditorHistory.js';

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

@@ -0,0 +1,14 @@
+export interface PlacementInfo {
+    /** The placement label (= the design artboard name, e.g. 'Front'). */
+    label: string;
+    active: boolean;
+}
+export interface UsePlacementsReturn {
+    /** Every placement in the design, in author order. */
+    placements: PlacementInfo[];
+    activePlacement: string;
+    /** Switch the active placement. Throws `EditorError E_UNKNOWN_PLACEMENT`
+     *  for a label that names no design artboard. */
+    select: (label: string) => void;
+}
+export declare function usePlacements(): UsePlacementsReturn;

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

@@ -10,9 +10,18 @@ export interface EmbedContextValue {
     /** The design the embed was seeded with — single source of truth for both the
      *  canvas seed and the seed render. */
     design: AnyDesign;
-    /** The placement name (= the design's artboard name). Both the canvas artboard
-     *  and every `renderState` call use this; derived once so it can't drift. */
+    /** The ACTIVE placement name (= the design's currently-edited artboard).
+     *  The canvas follows it as its controlled artboard. Initially the design's
+     *  active artboard; moved by {@link selectPlacement} (ADR-0088). For a
+     *  single-placement design this never changes — the pre-0088 behavior. */
     placement: string;
+    /** Every placement (artboard name) in the design, in author order. A
+     *  single-placement design has exactly one entry (ADR-0088). */
+    placements: string[];
+    /** Switch the active placement. Throws `EditorError E_UNKNOWN_PLACEMENT`
+     *  for a label that names no design artboard (ADR-0088). Costs zero session
+     *  work — renders already target every artboard per placement. */
+    selectPlacement: (label: string) => void;
     /** The product being rendered against. */
     product: RenderProduct;
     /** Latest mockups from the session. Reactive — updates re-render consumers. */

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

@@ -14,7 +14,26 @@ export interface ValidateEmbedInput {
 export interface EmbedIssue {
     severity: 'error' | 'warn';
     /** Stable issue key, carried into `EditorError.data.issue` in throw mode. */
-    issue: 'missing-shop' | 'missing-grant' | 'empty-mockup-ids' | 'variant-required' | 'multi-placement' | 'placement-mismatch' | 'duplicate-layer-names'
+    issue: 
+    /** No `shop` (the publishable shop id) was passed. */
+    'missing-shop'
+    /** No grant source (`grantUrl`/`grant`) — the session can never
+     *  authorize, so no mockup ever renders. */
+     | 'missing-grant'
+    /** `product.mockupIds` is empty — nothing to render. */
+     | 'empty-mockup-ids'
+    /** The product has a variant axis but no `variantId` — the render
+     *  would hang ~30s waiting on a color blob that never comes. */
+     | 'variant-required'
+    /** The product requires several placements but this embed renders ONE —
+     *  the server times out waiting on the rest (needs the eject path). */
+     | 'multi-placement'
+    /** The design's placement isn't one of the product's placements —
+     *  the server renders a blank mockup. */
+     | 'placement-mismatch'
+    /** Two layers share a name — name-bound hooks bind the FIRST match,
+     *  so a control may edit the wrong layer. */
+     | 'duplicate-layer-names'
     /** Runtime (not mount-time): a render has been in flight past
      *  `SLOW_RENDER_HINT_MS` with no mockup and no error — the silent-hang
      *  class. The render may still arrive; this is a heads-up. */

package/dist/contexts/EditorContext.d.ts

@@ -13,6 +13,29 @@ import { TextAlign, ShapeType } from '../types/index.js';
 export type { PanOffset } from './ViewportContext.js';
 export type { ExpandedPanelType } from './ToolStateContext.js';
 export type EditorElement = TextElement | ImageElement | GroupElement | ShapeElement | PathElement;
+/**
+ * Spec for {@link EditorContextValue.addElement}. `name` makes the created
+ * element addressable afterwards (bindings, `updateElement`, layer tokens).
+ */
+export interface AddElementSpec {
+    /** What to create. Text seeds editable "New Text"; image without `src` gets a placeholder. */
+    type: 'text' | 'shape' | 'image';
+    /** Shape variant (default `'rectangle'`). Shape type only. */
+    shapeType?: ShapeType;
+    /** Image source URL — the element loads it and sizes to the real aspect ratio. Image type only. */
+    src?: string;
+    /** Layer name for the new element, so it can be targeted afterwards. */
+    name?: string;
+}
+/**
+ * Handle to an element created by {@link EditorContextValue.addElement}:
+ * the generated `id` plus the layer `name` it answers to (empty string when
+ * no `name` was given). The new element arrives selected.
+ */
+export interface ElementHandle {
+    id: string;
+    name: string;
+}
 /**
  * Full value exposed by EditorContext.
  *
@@ -69,6 +92,17 @@ export interface EditorContextValue {
     handleSelectionChange: (id: string | null) => void;
     handleActiveChildChange: (child: EditorElement | null) => void;
     handleElementUpdate: (updatedElement: EditorElement) => void;
+    /**
+     * Create an element on the active artboard and get a handle back. The new
+     * element arrives SELECTED. Throws `E_NO_ACTIVE_ARTBOARD` (an
+     * {@link EditorError}, dev AND prod) when there is no artboard to add to.
+     */
+    addElement: (spec: AddElementSpec) => Promise<ElementHandle>;
+    /**
+     * @deprecated Use {@link addElement} — it returns an `ElementHandle`,
+     * accepts a `name`, and throws `E_NO_ACTIVE_ARTBOARD` instead of the old
+     * `window.alert`. This wrapper now propagates that throw too.
+     */
     handleAddElement: (elementType: string, opts?: {
         shapeType?: ShapeType;
         src?: string;

package/dist/core/HybridHistoryManager.d.ts

@@ -41,6 +41,13 @@ export declare class HybridHistoryManager {
      * Execute a command on a specific artboard
      */
     executeOnArtboard(artboardId: string, command: Command): void;
+    /**
+     * Peek at the command currently on top of an artboard's history (the entry
+     * the next `undoArtboard` would undo), or null. Used by `updateElement`'s
+     * coalescing to verify its last command is still the live tip before
+     * folding a new patch into it.
+     */
+    peekArtboard(artboardId: string): Command | null;
     /**
      * Smart undo - determines which history to use
      */

package/dist/core/elementGuards.d.ts

@@ -0,0 +1,19 @@
+import { TextElement } from './TextElement.js';
+import { ImageElement } from './ImageElement.js';
+import { ShapeElement } from './ShapeElement.js';
+import { GroupElement } from './GroupElement.js';
+import { PathElement } from './PathElement.js';
+/** The element kinds an {@link EditorElement} can be. */
+export type EditorElementKind = 'text' | 'image' | 'shape' | 'group' | 'path';
+/** Narrow to a text element (`text`, `fontSize`, `color`, `fontFamily`, …). */
+export declare function isTextElement(el: unknown): el is TextElement;
+/** Narrow to an image element (`imageUrl`, crop state, `transformData.width/height`). */
+export declare function isImageElement(el: unknown): el is ImageElement;
+/** Narrow to a shape element (`transformData.shapeType/fillColor/width/height`). */
+export declare function isShapeElement(el: unknown): el is ShapeElement;
+/** Narrow to a group element (`children`). */
+export declare function isGroupElement(el: unknown): el is GroupElement;
+/** Narrow to a path element (pen-tool vector paths). */
+export declare function isPathElement(el: unknown): el is PathElement;
+/** The kind discriminant for an element, or `null` for non-elements. */
+export declare function editorElementKind(el: unknown): EditorElementKind | null;

package/dist/{custom-icons-BW6hqmkL.js → custom-icons-CcLMyybv.js}

@@ -1,6 +1,6 @@
 import { jsx as i, jsxs as h } from "react/jsx-runtime";
 import * as c from "react";
-import { n as T, y, N as w } from "./UnifiedFontService-CC3CSmH5.js";
+import { n as T, z as y, O as w } from "./UnifiedFontService-CHVYDBDW.js";
 import * as R from "@radix-ui/react-label";
 import { cva as S } from "class-variance-authority";
 import * as g from "@radix-ui/react-tabs";
@@ -55,8 +55,8 @@ const E = c.forwardRef(
 E.displayName = "Input";
 const C = S(
   "sc:block sc:text-sm sc:leading-none sc:text-foreground sc:peer-disabled:cursor-not-allowed sc:peer-disabled:opacity-70 sc:font-label"
-), j = c.forwardRef(({ className: s, ...e }, a) => /* @__PURE__ */ i(R.Root, { ref: a, className: y(C(), s), ...e }));
-j.displayName = R.Root.displayName;
+), O = c.forwardRef(({ className: s, ...e }, a) => /* @__PURE__ */ i(R.Root, { ref: a, className: y(C(), s), ...e }));
+O.displayName = R.Root.displayName;
 const L = c.forwardRef(
   ({ value: s, onValueChange: e, ...a }, t) => /* @__PURE__ */ i(g.Root, { ref: t, value: s, onValueChange: e, ...a })
 );
@@ -170,10 +170,10 @@ const I = c.forwardRef(
   ({ className: s, ...e }, a) => /* @__PURE__ */ i("div", { ref: a, className: s, ...e })
 );
 I.displayName = "TabsListContainer";
-const O = x, B = N, P = () => null, q = L, z = Object.assign(q, {
+const j = x, B = N, P = () => null, q = L, z = Object.assign(q, {
   List: k,
   ListContainer: I,
-  Tab: O,
+  Tab: j,
   Trigger: x,
   Panel: B,
   Content: N,
@@ -227,10 +227,10 @@ const D = ({ className: s, size: e = 24 }) => /* @__PURE__ */ h(
 );
 export {
   E as I,
-  j as L,
+  O as L,
   D as R,
   W as S,
   z as T,
   A as a
 };
-//# sourceMappingURL=custom-icons-BW6hqmkL.js.map
+//# sourceMappingURL=custom-icons-CcLMyybv.js.map