@snowcone-app/canvas 0.23.0 → 0.27.0

package/dist/embed.mjs

@@ -1,46 +1,54 @@
-import { C as a, a as r, b as o, u as t, d as i, f as d, g as n } from "./UnifiedFontService-CC3CSmH5.js";
-import { E as m, R as l, a as E, b as c, S as p, c as g, f, p as S, d as x, e as T, v } from "./embed-DxsaqZJF.js";
-import { g as b, i as B, u as y } from "./editorErrors-B2mb1sVN.js";
-import { D as R, d as D, a as k, i as F } from "./design-builder-2VUjfmdt.js";
-import { D as L, T as w, r as M, u as h, a as A, b as _, c as z, d as G, e as K, f as N, w as Y } from "./template-fields-CQ6n2P4V.js";
-import { s as q } from "./CanvasStateV1-DmZ1Qvvn.js";
+import { C as a, a as r, b as t, u as i, d as o, f as n, g as d } from "./UnifiedFontService-CHVYDBDW.js";
+import { E as l, R as u, a as E, b as c, S as p, c as g, d as S, f, p as x, e as T, g as v, h as C, v as P } from "./embed-CJswRZte.js";
+import { g as B, i as h, u as y } from "./editorErrors-BhrZ_nwj.js";
+import { D as k, d as D, a as I, i as F } from "./design-builder-cZY958Rw.js";
+import { D as w, T as M, h as A, i as G, j as K, k as _, l as j, m as z, r as N, u as Y, a as q, b as H, c as J, d as O, e as Q, f as U, w as V } from "./template-fields-BXl29sgh.js";
+import { s as X } from "./CanvasStateV1-BTbCD_xC.js";
 export {
   a as CanvasServicesProvider,
-  R as DesignBuilder,
-  L as DesignStateStore,
-  m as Editor,
-  b as EditorError,
-  l as RealtimeCanvas,
+  k as DesignBuilder,
+  w as DesignStateStore,
+  l as Editor,
+  B as EditorError,
+  u as RealtimeCanvas,
   E as RealtimeEmbed,
   c as RealtimeMockup,
   p as SnowconeEditor,
-  w as TEMPLATE_FIELDS_KEY,
-  g as collectEmbedIssues,
+  M as TEMPLATE_FIELDS_KEY,
+  g as auditEditor,
+  S as collectEmbedIssues,
   r as createProxyGenerate,
-  o as createProxyImageSearch,
+  t as createProxyImageSearch,
   D as design,
+  A as editorElementKind,
   f as formatBuyPrice,
-  k as isColorToken,
-  B as isEditorError,
+  I as isColorToken,
+  h as isEditorError,
+  G as isGroupElement,
+  K as isImageElement,
   F as isLayerToken,
-  S as productToRenderConfig,
-  M as readTemplateFields,
-  q as serializeState,
-  t as useArtboards,
-  i as useCanvasServices,
-  h as useColorBinding,
-  A as useCommands,
+  _ as isPathElement,
+  j as isShapeElement,
+  z as isTextElement,
+  x as productToRenderConfig,
+  N as readTemplateFields,
+  X as serializeState,
+  i as useArtboards,
+  o as useCanvasServices,
+  Y as useColorBinding,
+  q as useCommands,
   y as useEditor,
-  _ as useElementByName,
-  d as useExport,
-  z as useFontBinding,
-  G as useImageBinding,
-  n as useLayers,
-  x as useProductSelection,
-  T as useRealtimeMockups,
-  K as useSelectedElement,
-  N as useTextBinding,
-  v as validateEmbed,
-  Y as withTemplateFields
+  H as useElementByName,
+  n as useExport,
+  J as useFontBinding,
+  O as useImageBinding,
+  d as useLayers,
+  T as usePlacements,
+  v as useProductSelection,
+  C as useRealtimeMockups,
+  Q as useSelectedElement,
+  U as useTextBinding,
+  P as validateEmbed,
+  V as withTemplateFields
 };
 //# sourceMappingURL=embed.mjs.map

package/dist/errors/editorError.d.ts

@@ -36,6 +36,12 @@ export type EditorErrorCode =
 /** `productToRenderConfig`: the catalog product has no renderable image
  *  placement / no mockup scenes, or the requested placement doesn't exist. */
  | 'E_PRODUCT_NOT_RENDERABLE'
+/** `design().artboard()`: an artboard with this label already exists in the
+ *  design (artboard names are placement labels — unique by contract). */
+ | 'E_DUPLICATE_ARTBOARD'
+/** `usePlacements().select()`: the label names no artboard in the design
+ *  (ADR-0088). Lists the valid placement labels. */
+ | 'E_UNKNOWN_PLACEMENT'
 /** `select()` named an option key/choice that doesn't exist on the product
  *  (Buy-owned selection, ADR-0085 §2 / P2). */
  | 'E_UNKNOWN_OPTION'
@@ -49,6 +55,25 @@ export type EditorErrorCode =
 /** `design.color(name)`: no color role with this name — lists the design's
  *  declared roles. */
  | 'E_COLOR_ROLE_NOT_FOUND'
+/** `Editor.Preview loadingOverlay` got `false`/an unknown value. A mockup
+ *  preview ALWAYS has a render-in-flight treatment (a server render takes
+ *  real time, and the loader paints OVER the still-visible previous
+ *  mockup) — keep the default, pass a variant/custom element, or declare
+ *  `"host-owned"` with your own indicator. Silence-then-pop-in is a
+ *  composition mistake, not a preference. */
+ | 'E_PREVIEW_NO_LOADER'
+/** `updateElement(target, patch)`: a patch key doesn't apply to the target
+ *  element's kind (e.g. `fontSize` on a shape), or a value is out of range
+ *  (opacity outside 0..1, fontSize/width/height <= 0, non-finite number,
+ *  wrong primitive type). The message names the element kind and lists the
+ *  valid keys for it. Dev AND prod. */
+ | 'E_INVALID_PATCH'
+/** `addElement(spec)`: there is no active artboard to add the element to.
+ *  Create or select an artboard first (`<Editor.Root>` seeds one
+ *  automatically; with a raw `EditorProvider` use `executeCreateArtboard`).
+ *  Replaces the old `handleAddElement` window.alert — agents read throws,
+ *  not dialogs. */
+ | 'E_NO_ACTIVE_ARTBOARD'
 /** `assertRenders`: the shop's asset-origin allowlist denied a design asset
  *  (translated from the server's 403 — F4). */
  | 'E_ASSET_FORBIDDEN'
@@ -59,7 +84,10 @@ export type EditorErrorCode =
  | 'E_BINDING_INERT'
 /** `assertRenders`: the design has no named text layer to mutate and no
  *  `mutate` override was given (F4). */
- | 'E_NO_MUTABLE_BINDING';
+ | 'E_NO_MUTABLE_BINDING'
+/** `auditEditor()` called with no `<Editor.Root>` mounted — the imperative
+ *  audit reads the most-recent mounted Root's registry (#10). */
+ | 'E_AUDIT_NO_ROOT';
 export interface EditorErrorData {
     code: EditorErrorCode;
     /** Slug under https://developers.snowcone.app/ for the violated contract. */

package/dist/{guards-8rkFAMBs.js → guards-DIX8aXWM.js}

@@ -1,4 +1,4 @@
-import { G as n, I as t, P as a, S as s, T as i } from "./FontAnalyzer-CwIpgTGd.js";
+import { G as n, I as t, P as a, S as s, T as i } from "./FontAnalyzer-EF3gLPr8.js";
 function r(e) {
   return e instanceof i;
 }
@@ -21,4 +21,4 @@ export {
   r as d,
   u as i
 };
-//# sourceMappingURL=guards-8rkFAMBs.js.map
+//# sourceMappingURL=guards-DIX8aXWM.js.map

package/dist/{guards-8rkFAMBs.js.map → guards-DIX8aXWM.js.map}

@@ -1 +1 @@
-{"version":3,"file":"guards-8rkFAMBs.js","sources":["../src/types/guards.ts"],"sourcesContent":["/**\n * Type guards for EditorElement discrimination\n *\n * These guards use instanceof checks against the concrete element classes,\n * matching the pattern established in EditorContext.tsx. They accept\n * BaseElement | EditorElement | undefined | null for maximum flexibility\n * at call sites.\n */\n\nimport { BaseElement } from '../core/BaseElement.js';\nimport { TextElement } from '../core/TextElement.js';\nimport { ImageElement } from '../core/ImageElement.js';\nimport { GroupElement } from '../core/GroupElement.js';\nimport { ShapeElement } from '../core/ShapeElement.js';\nimport { PathElement } from '../core/PathElement.js';\n\ntype Narrowable = BaseElement | TextElement | ImageElement | GroupElement | ShapeElement | PathElement | undefined | null;\n\n/**\n * Type guard: checks if an element is a TextElement (or any text-based transform subclass).\n *\n * TextElement is the base class for all text transforms (custom, circle, arch, wave, etc.),\n * so this returns true for any text-based element regardless of its specific transformType.\n */\nexport function isTextElement(element: Narrowable): element is TextElement {\n  return element instanceof TextElement;\n}\n\n/**\n * Type guard: checks if an element is an ImageElement.\n */\nexport function isImageElement(element: Narrowable): element is ImageElement {\n  return element instanceof ImageElement;\n}\n\n/**\n * Type guard: checks if an element is a GroupElement.\n */\nexport function isGroupElement(element: Narrowable): element is GroupElement {\n  return element instanceof GroupElement;\n}\n\n/**\n * Type guard: checks if an element is a ShapeElement.\n */\nexport function isShapeElement(element: Narrowable): element is ShapeElement {\n  return element instanceof ShapeElement;\n}\n\n/**\n * Type guard: checks if an element is a PathElement.\n */\nexport function isPathElement(element: Narrowable): element is PathElement {\n  return element instanceof PathElement;\n}\n"],"names":["isTextElement","element","TextElement","isImageElement","ImageElement","isGroupElement","GroupElement","isShapeElement","ShapeElement","isPathElement","PathElement"],"mappings":";AAwBO,SAASA,EAAcC,GAA6C;AACzE,SAAOA,aAAmBC;AAC5B;AAKO,SAASC,EAAeF,GAA8C;AAC3E,SAAOA,aAAmBG;AAC5B;AAKO,SAASC,EAAeJ,GAA8C;AAC3E,SAAOA,aAAmBK;AAC5B;AAKO,SAASC,EAAeN,GAA8C;AAC3E,SAAOA,aAAmBO;AAC5B;AAKO,SAASC,EAAcR,GAA6C;AACzE,SAAOA,aAAmBS;AAC5B;"}
+{"version":3,"file":"guards-DIX8aXWM.js","sources":["../src/types/guards.ts"],"sourcesContent":["/**\n * Type guards for EditorElement discrimination\n *\n * These guards use instanceof checks against the concrete element classes,\n * matching the pattern established in EditorContext.tsx. They accept\n * BaseElement | EditorElement | undefined | null for maximum flexibility\n * at call sites.\n */\n\nimport { BaseElement } from '../core/BaseElement.js';\nimport { TextElement } from '../core/TextElement.js';\nimport { ImageElement } from '../core/ImageElement.js';\nimport { GroupElement } from '../core/GroupElement.js';\nimport { ShapeElement } from '../core/ShapeElement.js';\nimport { PathElement } from '../core/PathElement.js';\n\ntype Narrowable = BaseElement | TextElement | ImageElement | GroupElement | ShapeElement | PathElement | undefined | null;\n\n/**\n * Type guard: checks if an element is a TextElement (or any text-based transform subclass).\n *\n * TextElement is the base class for all text transforms (custom, circle, arch, wave, etc.),\n * so this returns true for any text-based element regardless of its specific transformType.\n */\nexport function isTextElement(element: Narrowable): element is TextElement {\n  return element instanceof TextElement;\n}\n\n/**\n * Type guard: checks if an element is an ImageElement.\n */\nexport function isImageElement(element: Narrowable): element is ImageElement {\n  return element instanceof ImageElement;\n}\n\n/**\n * Type guard: checks if an element is a GroupElement.\n */\nexport function isGroupElement(element: Narrowable): element is GroupElement {\n  return element instanceof GroupElement;\n}\n\n/**\n * Type guard: checks if an element is a ShapeElement.\n */\nexport function isShapeElement(element: Narrowable): element is ShapeElement {\n  return element instanceof ShapeElement;\n}\n\n/**\n * Type guard: checks if an element is a PathElement.\n */\nexport function isPathElement(element: Narrowable): element is PathElement {\n  return element instanceof PathElement;\n}\n"],"names":["isTextElement","element","TextElement","isImageElement","ImageElement","isGroupElement","GroupElement","isShapeElement","ShapeElement","isPathElement","PathElement"],"mappings":";AAwBO,SAASA,EAAcC,GAA6C;AACzE,SAAOA,aAAmBC;AAC5B;AAKO,SAASC,EAAeF,GAA8C;AAC3E,SAAOA,aAAmBG;AAC5B;AAKO,SAASC,EAAeJ,GAA8C;AAC3E,SAAOA,aAAmBK;AAC5B;AAKO,SAASC,EAAeN,GAA8C;AAC3E,SAAOA,aAAmBO;AAC5B;AAKO,SAASC,EAAcR,GAA6C;AACzE,SAAOA,aAAmBS;AAC5B;"}

package/dist/hooks/elementPatch.d.ts

@@ -0,0 +1,96 @@
+import { LayerToken } from '../design/design-builder.js';
+import { EditorElementKind } from '../core/elementGuards.js';
+import { ElementStore } from '../core/ElementStore.js';
+import { EditorElement } from '../contexts/EditorContext.js';
+import { TextAlign } from '../types/index.js';
+/**
+ * A serializable element patch for {@link UseCommandsReturn.updateElement}.
+ *
+ * Keys are validated against the TARGET element's kind at call time — a key
+ * that doesn't apply (e.g. `fontSize` on a shape) throws `E_INVALID_PATCH`
+ * naming the kind and listing its valid keys, dev AND prod.
+ *
+ * | keys | applies to |
+ * |---|---|
+ * | `x`, `y`, `rotation`, `opacity`, `name`, `visible`, `locked` | every kind |
+ * | `text`, `fontSize`, `color`, `fontFamily`, `bold`, `italic`, `textAlign` | text |
+ * | `fillColor`, `width`, `height` | shape |
+ * | `imageUrl`, `width`, `height` | image |
+ */
+export interface ElementPatch {
+    /** Center x in artboard coordinates. Any kind. */
+    x?: number;
+    /** Center y in artboard coordinates. Any kind. */
+    y?: number;
+    /** Rotation in degrees. Any kind. */
+    rotation?: number;
+    /** 0..1. Any kind. Out of range throws `E_INVALID_PATCH`. */
+    opacity?: number;
+    /** Layer name (renaming a bound layer throws `E_BOUND_LAYER_MUTATION`). Any kind. */
+    name?: string;
+    /** Layer visibility. Any kind. */
+    visible?: boolean;
+    /** Layer lock. Any kind. */
+    locked?: boolean;
+    /** Text content. Text elements only. */
+    text?: string;
+    /** Font size (> 0; clamped to the editor's min/max). Text elements only. */
+    fontSize?: number;
+    /** Ink color (CSS color). Text elements only. */
+    color?: string;
+    /** Font family name. Text elements only. */
+    fontFamily?: string;
+    /** Bold. Text elements only. */
+    bold?: boolean;
+    /** Italic. Text elements only. */
+    italic?: boolean;
+    /** Text alignment. Text elements only. */
+    textAlign?: TextAlign;
+    /** Fill color (CSS color). Shape elements only. */
+    fillColor?: string;
+    /** Frame width (> 0). Shape and image elements only. */
+    width?: number;
+    /** Frame height (> 0). Shape and image elements only. */
+    height?: number;
+    /** Image source URL — swaps the image and reloads it. Image elements only.
+     *  Combined with explicit `width`/`height` the frame is preserved;
+     *  otherwise the frame height re-fits the loaded aspect ratio. */
+    imageUrl?: string;
+}
+/** Options for {@link UseCommandsReturn.updateElement}. */
+export interface UpdateElementOptions {
+    /**
+     * Coalesce with the immediately-preceding coalesced `updateElement` to the
+     * SAME element: consecutive calls land as ONE history entry, so one
+     * `undo()` returns to the state before the run (finding #16 — host
+     * inspectors that commit per keystroke stop flooding history). Any other
+     * command in between, or an undo/redo, breaks the run.
+     */
+    coalesce?: boolean;
+}
+/** Patchable keys per element kind — the validation source of truth. */
+export declare const PATCH_KEYS_BY_KIND: Record<EditorElementKind, readonly string[]>;
+/**
+ * Resolve an `updateElement` target — an element id, a layer name, or a
+ * `design.layer()` token — to an element in the store. Unknown targets throw
+ * the existing `E_LAYER_NOT_FOUND` listing the valid ids and layer names.
+ * When several elements share a layer name, the first (render order) wins.
+ */
+export declare function resolveElementTarget(elementStore: ElementStore, target: string | LayerToken): EditorElement;
+/**
+ * Validate a patch against the element's kind. Throws `E_INVALID_PATCH`
+ * (dev AND prod) for: a key that doesn't apply to the kind (message names the
+ * kind and lists its valid keys), opacity outside 0..1, fontSize/width/height
+ * <= 0, non-finite numbers, or wrong primitive types.
+ */
+export declare function validateElementPatch(el: EditorElement, patch: ElementPatch): EditorElementKind;
+/**
+ * Apply a VALIDATED patch onto a clone (mutates `clone` in place). Uses the
+ * element's own normalizing setters where they exist (`setText`,
+ * `setFontSize` clamps, `setColor` keeps rich-text spans in sync).
+ * Image-source swaps need a post-command `loadImage` — signalled by the
+ * return value so `updateElement` can run the load path.
+ */
+export declare function applyElementPatch(clone: EditorElement, patch: ElementPatch): {
+    needsImageLoad: boolean;
+};

package/dist/hooks/useCommands.d.ts

@@ -1,4 +1,6 @@
 import { useEditor } from '../contexts/EditorContext.js';
+import { ElementPatch, UpdateElementOptions } from './elementPatch.js';
+import { LayerToken } from '../design/design-builder.js';
 export interface UseCommandsReturn {
     undo: () => void;
     redo: () => void;
@@ -6,6 +8,24 @@ export interface UseCommandsReturn {
     canRedo: boolean;
     clearHistory: () => void;
     clearArtboardHistory: (artboardId: string) => void;
+    /**
+     * Declarative, validated, undoable element mutation — the agent write path.
+     * `target` is an element id, a layer name, or a `design.layer()` token
+     * (unknown targets throw `E_LAYER_NOT_FOUND` listing the valid names).
+     * The patch is validated against the element's kind and applied as ONE
+     * history entry; invalid keys/values throw `E_INVALID_PATCH` naming the
+     * kind and its valid keys — dev AND prod.
+     *
+     * `{ coalesce: true }`: consecutive coalesced calls to the SAME element
+     * fold into one history entry (one `undo()` returns to the pre-run state).
+     */
+    updateElement: (target: string | LayerToken, patch: ElementPatch, opts?: UpdateElementOptions) => void;
+    /**
+     * Create an element and get `{ id, name }` back; the element arrives
+     * selected. Throws `E_NO_ACTIVE_ARTBOARD` when there is no artboard.
+     * (Also available on `useEditor()`.)
+     */
+    addElement: ReturnType<typeof useEditor>['addElement'];
     executeElementUpdate: ReturnType<typeof useEditor>['executeElementUpdate'];
     executeAddElement: ReturnType<typeof useEditor>['executeAddElement'];
     executeRemoveElement: ReturnType<typeof useEditor>['executeRemoveElement'];

package/dist/index.mjs

@@ -1,12 +1,12 @@
-import { e as u } from "./UnifiedFontService-CC3CSmH5.js";
-import { C as l, c as x, a as I, b as v, u as A, d as T, f as g, g as B } from "./UnifiedFontService-CC3CSmH5.js";
-import { E as _, S as y, S as L, u as O, a as M } from "./SnowconeCanvas-D1sLcIja.js";
-import { u as d, a as m } from "./editorErrors-B2mb1sVN.js";
-import { T as z, r as w, u as F, a as D, b as K, c as N, d as V, e as b, f as h, w as U } from "./template-fields-CQ6n2P4V.js";
-import { A as Z, C as G, E as H, M as j, P as k, r as q, v as J } from "./validation-C9Fe9ahK.js";
-import { C as W, D as X, d as $, s as ee } from "./design-builder-2VUjfmdt.js";
+import { e as u } from "./UnifiedFontService-CHVYDBDW.js";
+import { C as l, c as x, a as I, b as v, u as A, d as T, f as g, g as B } from "./UnifiedFontService-CHVYDBDW.js";
+import { E as _, S as y, S as L, u as O, a as M } from "./SnowconeCanvas-DuWALOAt.js";
+import { u as d, a as m } from "./editorErrors-BhrZ_nwj.js";
+import { T as z, r as w, u as F, a as D, b as K, c as N, d as V, e as b, f as h, w as U } from "./template-fields-BXl29sgh.js";
+import { A as Z, C as G, E as H, M as j, P as k, r as q, v as J } from "./validation-DGXAQmUC.js";
+import { C as W, D as X, d as $, s as ee } from "./design-builder-cZY958Rw.js";
 import { c as se, e as te } from "./compose-DtQL_oit.js";
-import { d as oe, m as ie, s as ne, v as ue } from "./CanvasStateV1-DmZ1Qvvn.js";
+import { d as oe, m as ie, s as ne, v as ue } from "./CanvasStateV1-BTbCD_xC.js";
 function C() {
   const { isCanvasReady: e } = d();
   return e;

package/dist/internals.mjs

@@ -1,8 +1,8 @@
-import { A as w, a as b, C as I, I as R, R as W, S as A, T as E } from "./CanvasRenderer-6_HhR4-q.js";
-import { r as p } from "./ExportManager-DoU4VK6h.js";
-import { D as O, E as F, I as L, W as X, a as z, b as K, c as Y, d as B, e as _, f as J, h as N, i as V, j as U, k as j, l as q, m as Q, n as Z, o as $, p as m, q as G, s as x, t as D, u as rr, v as or, w as sr, x as ir, y as er, z as ar, A as nr, B as tr, C as hr } from "./ExportManager-DoU4VK6h.js";
-import { D as cr, E as fr, H as pr, J as gr, K as lr, L as ur, M as Tr, N as kr, O as Mr, Q as yr, W as Cr, U as vr, V as Sr, X as Pr, c as wr, Y as br, Z as Ir, _ as Rr, $ as Wr, a0 as Ar } from "./FontAnalyzer-CwIpgTGd.js";
-import { A as Hr, e as Or, C as Fr, S as Lr } from "./CanvasStateV1-DmZ1Qvvn.js";
+import { A as w, a as b, C as I, I as R, R as W, S as A, T as E } from "./CanvasRenderer-yszzrDfo.js";
+import { r as p } from "./ExportManager-BTcyj4cf.js";
+import { D as O, E as F, I as L, W as X, a as z, b as K, c as Y, d as B, e as _, f as J, h as N, i as V, j, k as q, l as Q, m as U, n as Z, o as $, p as m, q as G, s as x, t as D, u as rr, v as or, w as sr, x as ir, y as er, z as ar, A as nr, B as tr, C as hr } from "./ExportManager-BTcyj4cf.js";
+import { D as cr, E as fr, H as pr, J as gr, K as lr, L as ur, M as Tr, N as kr, O as Mr, Q as yr, W as Cr, V as vr, X as Sr, Y as Pr, c as wr, Z as br, _ as Ir, $ as Rr, a0 as Wr, a1 as Ar } from "./FontAnalyzer-EF3gLPr8.js";
+import { A as Hr, e as Or, C as Fr, S as Lr } from "./CanvasStateV1-BTbCD_xC.js";
 function y(r, o) {
   return !r.needsCropPixelConversion || r.cropWidth === void 0 ? r : {
     ...r,
@@ -198,10 +198,10 @@ export {
   N as createCirclePath,
   V as createImagePath,
   wr as createLogger,
-  U as createRectPath,
-  j as createTextPath,
-  q as getFontMetrics,
-  Q as getSharedWorkerExportManager,
+  j as createRectPath,
+  q as createTextPath,
+  Q as getFontMetrics,
+  U as getSharedWorkerExportManager,
   br as hitTestCircle,
   Ir as hitTestRect,
   Z as invalidateMaskCache,