@snowcone-app/canvas 0.17.2 → 0.18.0

package/dist/api/embed.d.ts

@@ -35,7 +35,7 @@
  * @packageDocumentation
  */
 export { Editor, DesignStateStore } from '../components/editor/index.js';
-export type { EditorRootProps, EditorRootBaseProps, EditorCanvasProps, EditorPreviewProps, EditorTextFieldProps, EditorBuyProps, EditorBuyPayload, BuyMissingReason, DesignState, } from '../components/editor/index.js';
+export type { EditorRootProps, EditorRootBaseProps, EditorCanvasProps, EditorPreviewProps, EditorTextFieldProps, EditorBuyProps, EditorBuyPayload, BuyMissingReason, DesignState, EditorLayersProps, EditorControlsProps, EditorHistoryProps, EditorMenuProps, EditorAddProps, } 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';

package/dist/components/ContextualToolbars.d.ts

@@ -155,6 +155,14 @@ export interface ContextualToolbarsProps {
      * this and the ambient context applies; passing it explicitly wins either way.
      */
     services?: CanvasServices;
+    /**
+     * `data-sc-part` value for the toolbar root (the Editor.* parts contract,
+     * ADR-0085 §5 — the class-3 floating toolbar is themable and selectable via
+     * `data-sc-part` even though the host doesn't position it). Set by the
+     * canvas's built-in floating mount; omitted everywhere else.
+     * @internal
+     */
+    partAttr?: string;
 }
 export declare const ContextualToolbars: React.FC<ContextualToolbarsProps>;
 export default ContextualToolbars;

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

@@ -0,0 +1,11 @@
+import { default as React, CSSProperties } from 'react';
+export interface EditorAddProps {
+    className?: string;
+    style?: CSSProperties;
+}
+/**
+ * The ⊕ add-element menu.
+ *
+ * @experimental ADR-0085; subject to change until the P4 gate.
+ */
+export declare function EditorAdd({ className, style }: EditorAddProps): React.ReactElement;

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

@@ -26,6 +26,12 @@ export interface EditorCanvasImplProps {
     selfScope?: boolean;
     /** `data-sc-part` value for the wrapping div (the parts contract). */
     partAttr?: string;
+    /** Mount the built-in floating contextual toolbar (ADR-0085 §5: with no
+     *  `Editor.Controls` mounted, `Editor.Canvas` defaults to the floating
+     *  toolbar; a registered DOCKED Controls suppresses it). Set by
+     *  `Editor.Canvas` only — the legacy `<RealtimeCanvas>` wrapper keeps
+     *  today's chrome-less behavior. @internal */
+    builtinControls?: boolean;
     className?: string;
     style?: CSSProperties;
 }

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

@@ -0,0 +1,14 @@
+import { default as React, CSSProperties } from 'react';
+export interface EditorControlsProps {
+    /** Where the contextual zone lives (ADR-0085 §5). The host docks the part
+     *  by where it renders it — there is deliberately no "bottom"/"top" value. */
+    placement?: 'docked' | 'floating';
+    className?: string;
+    style?: CSSProperties;
+}
+/**
+ * The contextual controls zone.
+ *
+ * @experimental ADR-0085; subject to change until the P4 gate.
+ */
+export declare function EditorControls({ placement, className, style, }: EditorControlsProps): React.ReactElement | null;

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

@@ -0,0 +1,11 @@
+import { default as React, CSSProperties } from 'react';
+export interface EditorHistoryProps {
+    className?: string;
+    style?: CSSProperties;
+}
+/**
+ * Undo/redo for the editor document.
+ *
+ * @experimental ADR-0085; subject to change until the P4 gate.
+ */
+export declare function EditorHistory({ className, style }: EditorHistoryProps): React.ReactElement;

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

@@ -0,0 +1,16 @@
+import { default as React, CSSProperties } from 'react';
+export interface EditorLayersProps {
+    /** Flow direction of the canvas-free list (the wrapped document panel is a
+     *  vertical column). Default `'vertical'`. */
+    direction?: 'vertical' | 'horizontal';
+    className?: string;
+    style?: CSSProperties;
+}
+/**
+ * Layer list. Canvas-free (the no-canvas composition shows the design's
+ * layers read-only); with a mounted `Editor.Canvas` it is the live document
+ * panel.
+ *
+ * @experimental ADR-0085; subject to change until the P4 gate.
+ */
+export declare function EditorLayers({ direction, className, style, }: EditorLayersProps): React.ReactElement;

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

@@ -0,0 +1,11 @@
+import { default as React, CSSProperties } from 'react';
+export interface EditorMenuProps {
+    className?: string;
+    style?: CSSProperties;
+}
+/**
+ * The editor's overflow menu.
+ *
+ * @experimental ADR-0085; subject to change until the P4 gate.
+ */
+export declare function EditorMenu({ className, style }: EditorMenuProps): React.ReactElement;

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

@@ -17,6 +17,7 @@ export declare class EditorPartsRegistry {
     private canvasIds;
     private requirements;
     private textFields;
+    private controls;
     private bridge;
     private listeners;
     private version;
@@ -43,6 +44,12 @@ export declare class EditorPartsRegistry {
     getBoundLayer(name: string): {
         part: string;
     } | null;
+    /** `Editor.Controls` registration (ADR-0085 §5): a mounted DOCKED Controls
+     *  suppresses the canvas's built-in floating contextual toolbar — one
+     *  contextual zone at a time. `placement="floating"` registers without
+     *  suppressing (it declares today's default explicitly). */
+    registerControls(instanceId: string, placement: 'docked' | 'floating'): () => void;
+    hasDockedControls(): boolean;
     registerCanvasBridge(bridge: CanvasBridge): () => void;
     getCanvasBridge(): CanvasBridge | null;
     private bump;

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

@@ -2,6 +2,11 @@ import { EditorRoot } from './EditorRoot.js';
 import { EditorPreview } from './EditorPreview.js';
 import { EditorTextField } from './EditorTextField.js';
 import { EditorBuy } from './EditorBuy.js';
+import { EditorLayers } from './EditorLayers.js';
+import { EditorControls } from './EditorControls.js';
+import { EditorHistory } from './EditorHistory.js';
+import { EditorMenu } from './EditorMenu.js';
+import { EditorAdd } from './EditorAdd.js';
 export declare const Editor: {
     /** The one provider boundary — session, design, live state, error boundary. */
     readonly Root: typeof EditorRoot;
@@ -13,6 +18,16 @@ export declare const Editor: {
     readonly TextField: typeof EditorTextField;
     /** Smart commerce part: completeness + payload assembly; submit = host callback. */
     readonly Buy: typeof EditorBuy;
+    /** Layer list. The one editor part that works canvas-free (ADR-0085 §4). */
+    readonly Layers: typeof EditorLayers;
+    /** Morphing contextual zone — ONE coarse part; placement docked|floating (§5). */
+    readonly Controls: typeof EditorControls;
+    /** Undo/redo controls. Requires Editor.Canvas. */
+    readonly History: typeof EditorHistory;
+    /** The one ⋯ overflow menu. Requires Editor.Canvas. */
+    readonly Menu: typeof EditorMenu;
+    /** The ⊕ add-element menu. Requires Editor.Canvas. */
+    readonly Add: typeof EditorAdd;
 };
 export type { EditorRootProps, EditorRootBaseProps, GrantSource } from './EditorRoot.js';
 export type { EditorCanvasProps } from './EditorCanvas.js';
@@ -21,3 +36,8 @@ export type { EditorTextFieldProps } from './EditorTextField.js';
 export type { EditorBuyProps, EditorBuyPayload, BuyMissingReason } from './EditorBuy.js';
 export type { DesignState } from './designStateStore.js';
 export { DesignStateStore } from './designStateStore.js';
+export type { EditorLayersProps } from './EditorLayers.js';
+export type { EditorControlsProps } from './EditorControls.js';
+export type { EditorHistoryProps } from './EditorHistory.js';
+export type { EditorMenuProps } from './EditorMenu.js';
+export type { EditorAddProps } from './EditorAdd.js';

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

@@ -0,0 +1,9 @@
+import { default as React } from 'react';
+export interface AddElementType {
+    /** The element type passed to `handleAddElement` ('shape' opens the
+     *  shape-type drawer first instead of defaulting to a rectangle). */
+    type: string;
+    label: string;
+    icon: React.ReactNode;
+}
+export declare const ADD_ELEMENT_TYPES: AddElementType[];

package/dist/contexts/EditorContext.d.ts

@@ -106,6 +106,28 @@ export interface EditorContextValue {
     isCanvasReady: boolean;
     setCanvasReady: (ready: boolean) => void;
 }
+/**
+ * Stable lazy access to the latest {@link EditorContextValue} — re-render
+ * containment for chrome that needs editor state only inside EVENT HANDLERS
+ * (save, export, add-element), never at render time (ADR-0085 / D3:
+ * subscribing to the fat context re-renders on every editor change, including
+ * each keystroke routed through the command path).
+ *
+ * The provided object's identity NEVER changes; `get()` returns the value as
+ * of the provider's latest render. Do not render from it — anything read at
+ * render time will go stale without a re-render. For reactive reads use the
+ * narrow sub-context hooks instead.
+ */
+export interface EditorHandles {
+    /** The latest full editor context value (lazy — call inside handlers). */
+    get(): EditorContextValue;
+}
+/**
+ * Read the stable editor handles. Same provider requirement as `useEditor()`.
+ *
+ * @throws {Error} If called outside of an `EditorProvider`
+ */
+export declare const useEditorHandles: () => EditorHandles;
 /** Props for {@link EditorProvider}. */
 export interface EditorProviderProps {
     children: ReactNode;
@@ -155,6 +177,22 @@ export declare const EditorProvider: React.FC<EditorProviderProps>;
 /**
  * Access the full editor context: elements, selection, artboards, history, and operations.
  *
+ * ## Stability contract (ADR-0085)
+ *
+ * `useEditor()` is the headless floor of the `Editor.*` primitives. Its v1
+ * STABLE subset — pinned by the type-level snapshot in
+ * `components/editor/__tests__/useEditorStableSubset.test.ts` — is:
+ *
+ * - **Elements**: `elements`, `elementStore`, `getElementById`
+ * - **Selection**: `selectedId`, `multiSelection`, `selectedElement`,
+ *   `setSelectedId`, `setMultiSelection`, `handleSelectionChange`
+ * - **Command execution**: `executeElementUpdate`, `executeAddElement`,
+ *   `executeRemoveElement`, `executeReorderElement`, `executeCommandBatch`
+ * - **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).
+ *
  * 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/preview-registry.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Layer-preview registry — the dependency-inversion seam between the layer
+ * panels (always-mountable chrome: `Editor.Layers` / `embed/LayersPanel`) and
+ * the rendering engine, extending the P1 element/renderer split
+ * (`core/paint-registry.ts`).
+ *
+ * `useLayers` / `useLayerPreview` used to statically import
+ * `utils/ElementPreviewRenderer`, dragging the whole paint pipeline into any
+ * graph that shows a layers panel — which would put the renderer in
+ * `Editor.Layers`' always-mounted graph (CI-gated renderer-free by
+ * scripts/check-import-graph.mjs). Inversion: the panels look the preview
+ * painter up HERE at preview time; the heavy side
+ * (`src/rendering/element-painters.ts`, inside `Editor.Canvas`'s lazy chunk)
+ * registers it at module evaluation.
+ *
+ * Contract difference from the paint registry: a MISS here is a legitimate
+ * state, not a wiring bug. Thumbnails are an enhancement that needs the
+ * rendering engine — a canvas-free composition (no `Editor.Canvas` mounted)
+ * has no painter and the panels fall back to their icon placeholder. So the
+ * getter returns `null` instead of throwing.
+ */
+export interface ElementPreviewOptions {
+    width?: number;
+    height?: number;
+    padding?: number;
+    backgroundColor?: string;
+}
+/** Renders a thumbnail data-URL for one live editor element. Structural
+ *  `object` on purpose so this module never imports an element class. */
+export type ElementPreviewPainter = (element: object, options?: ElementPreviewOptions) => string;
+export declare function registerElementPreviewPainter(painter: ElementPreviewPainter): void;
+/** The registered preview painter, or `null` while the rendering engine is
+ *  not loaded (the canvas-free fallback — render the icon placeholder). */
+export declare function getElementPreviewPainter(): ElementPreviewPainter | null;

package/dist/{editorErrors-BY4Pdg7a.js → editorErrors-DXNfVXtD.js}

@@ -1,4 +1,4 @@
-import { h as n, i as t } from "./EditorContext-CGkfmbgo.js";
+import { h as n, i as t } from "./EditorContext-5QpqAhjh.js";
 const r = [];
 function i(e) {
   t() && r.push(e);
@@ -26,4 +26,4 @@ export {
   d as g,
   i as r
 };
-//# sourceMappingURL=editorErrors-BY4Pdg7a.js.map
+//# sourceMappingURL=editorErrors-DXNfVXtD.js.map

package/dist/{editorErrors-BY4Pdg7a.js.map → editorErrors-DXNfVXtD.js.map}

@@ -1 +1 @@
-{"version":3,"file":"editorErrors-BY4Pdg7a.js","sources":["../src/testing/editorErrors.ts"],"sourcesContent":["/**\n * Test-side hooks into the `Editor.*` error contract (ADR-0085 / D11).\n *\n * Containment is a PROD feature: under `NODE_ENV=test`, Root's boundary\n * rethrows render-time composition errors, so a broken composition fails the\n * test naturally. The remaining blind spot is the NON-throwing channel —\n * runtime failures routed straight to the error card (e.g. the lazy renderer\n * chunk failing to load, `E_CHUNK_LOAD_FAILED`) and prod-routed handler\n * invariants. Those are recorded here in test envs so\n * {@link expectNoEditorErrors} can fail a green-looking test that actually\n * rendered an error card.\n *\n * ```ts\n * import { expectNoEditorErrors } from '@snowcone-app/canvas/testing';\n *\n * afterEach(() => expectNoEditorErrors());\n * ```\n */\n\nimport { isEditorError, isDevOrTest } from '../errors/editorError.js';\n\nconst recorded: Error[] = [];\n\n/** Record a contained editor error (test/dev envs only). @internal */\nexport function recordContainedEditorError(error: Error): void {\n  if (isDevOrTest()) recorded.push(error);\n}\n\n/** Errors contained since the last drain, without draining. */\nexport function getContainedEditorErrors(): readonly Error[] {\n  return [...recorded];\n}\n\n/** Drop all recorded errors (e.g. after asserting an EXPECTED failure). */\nexport function resetContainedEditorErrors(): void {\n  recorded.length = 0;\n}\n\n/**\n * Assert that no editor error was contained (rendered as an error card)\n * since the last reset/call. Drains the record either way so one leaked\n * error doesn't fail every later test in the file.\n */\nexport function expectNoEditorErrors(): void {\n  if (recorded.length === 0) return;\n  const summary = recorded\n    .map((e) => (isEditorError(e) ? `${e.code}: ${e.message}` : `${e.name}: ${e.message}`))\n    .join('\\n  - ');\n  recorded.length = 0;\n  throw new Error(\n    `expectNoEditorErrors: ${summary.includes('\\n') ? 'errors were' : 'an error was'} contained by ` +\n      `<Editor.Root>'s boundary during this test:\\n  - ${summary}\\n` +\n      'A contained error renders an error card in prod — this composition is broken even if the test rendered \"successfully\".',\n  );\n}\n"],"names":["recorded","recordContainedEditorError","error","isDevOrTest","getContainedEditorErrors","resetContainedEditorErrors","expectNoEditorErrors","summary","e","isEditorError"],"mappings":";AAqBA,MAAMA,IAAoB,CAAA;AAGnB,SAASC,EAA2BC,GAAoB;AAC7D,EAAIC,EAAA,KAAeH,EAAS,KAAKE,CAAK;AACxC;AAGO,SAASE,IAA6C;AAC3D,SAAO,CAAC,GAAGJ,CAAQ;AACrB;AAGO,SAASK,IAAmC;AACjD,EAAAL,EAAS,SAAS;AACpB;AAOO,SAASM,IAA6B;AAC3C,MAAIN,EAAS,WAAW,EAAG;AAC3B,QAAMO,IAAUP,EACb,IAAI,CAACQ,MAAOC,EAAcD,CAAC,IAAI,GAAGA,EAAE,IAAI,KAAKA,EAAE,OAAO,KAAK,GAAGA,EAAE,IAAI,KAAKA,EAAE,OAAO,EAAG,EACrF,KAAK;AAAA,KAAQ;AAChB,QAAAR,EAAS,SAAS,GACZ,IAAI;AAAA,IACR,yBAAyBO,EAAQ,SAAS;AAAA,CAAI,IAAI,gBAAgB,cAAc;AAAA,MAC3BA,CAAO;AAAA;AAAA,EAAA;AAGhE;"}
+{"version":3,"file":"editorErrors-DXNfVXtD.js","sources":["../src/testing/editorErrors.ts"],"sourcesContent":["/**\n * Test-side hooks into the `Editor.*` error contract (ADR-0085 / D11).\n *\n * Containment is a PROD feature: under `NODE_ENV=test`, Root's boundary\n * rethrows render-time composition errors, so a broken composition fails the\n * test naturally. The remaining blind spot is the NON-throwing channel —\n * runtime failures routed straight to the error card (e.g. the lazy renderer\n * chunk failing to load, `E_CHUNK_LOAD_FAILED`) and prod-routed handler\n * invariants. Those are recorded here in test envs so\n * {@link expectNoEditorErrors} can fail a green-looking test that actually\n * rendered an error card.\n *\n * ```ts\n * import { expectNoEditorErrors } from '@snowcone-app/canvas/testing';\n *\n * afterEach(() => expectNoEditorErrors());\n * ```\n */\n\nimport { isEditorError, isDevOrTest } from '../errors/editorError.js';\n\nconst recorded: Error[] = [];\n\n/** Record a contained editor error (test/dev envs only). @internal */\nexport function recordContainedEditorError(error: Error): void {\n  if (isDevOrTest()) recorded.push(error);\n}\n\n/** Errors contained since the last drain, without draining. */\nexport function getContainedEditorErrors(): readonly Error[] {\n  return [...recorded];\n}\n\n/** Drop all recorded errors (e.g. after asserting an EXPECTED failure). */\nexport function resetContainedEditorErrors(): void {\n  recorded.length = 0;\n}\n\n/**\n * Assert that no editor error was contained (rendered as an error card)\n * since the last reset/call. Drains the record either way so one leaked\n * error doesn't fail every later test in the file.\n */\nexport function expectNoEditorErrors(): void {\n  if (recorded.length === 0) return;\n  const summary = recorded\n    .map((e) => (isEditorError(e) ? `${e.code}: ${e.message}` : `${e.name}: ${e.message}`))\n    .join('\\n  - ');\n  recorded.length = 0;\n  throw new Error(\n    `expectNoEditorErrors: ${summary.includes('\\n') ? 'errors were' : 'an error was'} contained by ` +\n      `<Editor.Root>'s boundary during this test:\\n  - ${summary}\\n` +\n      'A contained error renders an error card in prod — this composition is broken even if the test rendered \"successfully\".',\n  );\n}\n"],"names":["recorded","recordContainedEditorError","error","isDevOrTest","getContainedEditorErrors","resetContainedEditorErrors","expectNoEditorErrors","summary","e","isEditorError"],"mappings":";AAqBA,MAAMA,IAAoB,CAAA;AAGnB,SAASC,EAA2BC,GAAoB;AAC7D,EAAIC,EAAA,KAAeH,EAAS,KAAKE,CAAK;AACxC;AAGO,SAASE,IAA6C;AAC3D,SAAO,CAAC,GAAGJ,CAAQ;AACrB;AAGO,SAASK,IAAmC;AACjD,EAAAL,EAAS,SAAS;AACpB;AAOO,SAASM,IAA6B;AAC3C,MAAIN,EAAS,WAAW,EAAG;AAC3B,QAAMO,IAAUP,EACb,IAAI,CAACQ,MAAOC,EAAcD,CAAC,IAAI,GAAGA,EAAE,IAAI,KAAKA,EAAE,OAAO,KAAK,GAAGA,EAAE,IAAI,KAAKA,EAAE,OAAO,EAAG,EACrF,KAAK;AAAA,KAAQ;AAChB,QAAAR,EAAS,SAAS,GACZ,IAAI;AAAA,IACR,yBAAyBO,EAAQ,SAAS;AAAA,CAAI,IAAI,gBAAgB,cAAc;AAAA,MAC3BA,CAAO;AAAA;AAAA,EAAA;AAGhE;"}