@snowcone-app/canvas 0.26.0 → 0.28.0

package/dist/embed.mjs

@@ -1,48 +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-Bx2MxFfy.js";
-import { E as m, R as l, a as E, b as c, S as g, c as p, d as f, f as S, p as x, e as T, g as v, h as C, v as b } from "./embed-DXGydZOT.js";
-import { g as P, i as y, u as R } from "./editorErrors-B2mb1sVN.js";
-import { D as k, d as F, a as I, i as L } from "./design-builder-U7Su9MMC.js";
-import { D as w, T as M, r as A, u as _, a as z, b as G, c as K, d as N, e as Y, f as j, w as q } from "./template-fields-DJ157D3E.js";
-import { s as J } 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-BJzoqfBF.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-L3oRIgsj.js";
+import { g as B, i as h, u as y } from "./editorErrors-8uDRMhow.js";
+import { D as k, d as D, a as I, i as F } from "./design-builder-bquxIHct.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-ai7vnW8g.js";
+import { s as X } from "./CanvasStateV1-kL09wsAn.js";
 export {
   a as CanvasServicesProvider,
   k as DesignBuilder,
   w as DesignStateStore,
-  m as Editor,
-  P as EditorError,
-  l as RealtimeCanvas,
+  l as Editor,
+  B as EditorError,
+  u as RealtimeCanvas,
   E as RealtimeEmbed,
   c as RealtimeMockup,
-  g as SnowconeEditor,
+  p as SnowconeEditor,
   M as TEMPLATE_FIELDS_KEY,
-  p as auditEditor,
-  f as collectEmbedIssues,
+  g as auditEditor,
+  S as collectEmbedIssues,
   r as createProxyGenerate,
-  o as createProxyImageSearch,
-  F as design,
-  S as formatBuyPrice,
+  t as createProxyImageSearch,
+  D as design,
+  A as editorElementKind,
+  f as formatBuyPrice,
   I as isColorToken,
-  y as isEditorError,
-  L as isLayerToken,
+  h as isEditorError,
+  G as isGroupElement,
+  K as isImageElement,
+  F as isLayerToken,
+  _ as isPathElement,
+  j as isShapeElement,
+  z as isTextElement,
   x as productToRenderConfig,
-  A as readTemplateFields,
-  J as serializeState,
-  t as useArtboards,
-  i as useCanvasServices,
-  _ as useColorBinding,
-  z as useCommands,
-  R as useEditor,
-  G as useElementByName,
-  d as useExport,
-  K as useFontBinding,
-  N as useImageBinding,
-  n as useLayers,
+  N as readTemplateFields,
+  X as serializeState,
+  i as useArtboards,
+  o as useCanvasServices,
+  Y as useColorBinding,
+  q as useCommands,
+  y as useEditor,
+  H as useElementByName,
+  n as useExport,
+  J as useFontBinding,
+  O as useImageBinding,
+  d as useLayers,
   T as usePlacements,
   v as useProductSelection,
   C as useRealtimeMockups,
-  Y as useSelectedElement,
-  j as useTextBinding,
-  b as validateEmbed,
-  q as withTemplateFields
+  Q as useSelectedElement,
+  U as useTextBinding,
+  P as validateEmbed,
+  V as withTemplateFields
 };
 //# sourceMappingURL=embed.mjs.map

package/dist/errors/editorError.d.ts

@@ -62,6 +62,18 @@ export type EditorErrorCode =
  *  `"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'
@@ -75,7 +87,13 @@ export type EditorErrorCode =
  | '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';
+ | 'E_AUDIT_NO_ROOT'
+/** `computeDistribute()` called with fewer than 3 movable elements —
+ *  distributing needs something between the two ends. Gate the action on
+ *  `useAlignDistribute().canDistribute` instead of calling below the
+ *  threshold (the toolbar hides its distribute buttons for exactly this
+ *  reason). */
+ | 'E_DISTRIBUTE_MIN_THREE';
 export interface EditorErrorData {
     code: EditorErrorCode;
     /** Slug under https://developers.snowcone.app/ for the violated contract. */

package/dist/{guards-8rkFAMBs.js → guards-BlbhM5MX.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-PE6nysqE.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-BlbhM5MX.js.map

package/dist/{guards-8rkFAMBs.js.map → guards-BlbhM5MX.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-BlbhM5MX.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/index.d.ts

@@ -40,3 +40,5 @@ export { useCanvasEvents } from './useCanvasEvents';
 export { useCommandHistory } from './useCommandHistory';
 export { useKeyboardShortcuts } from './useKeyboardShortcuts';
 export { useElementProperties } from './useElementProperties';
+export { useAlignDistribute } from './useAlignDistribute';
+export type { UseAlignDistributeResult, AlignMode, DistributeMode } from './useAlignDistribute';

package/dist/hooks/useAlignDistribute.d.ts

@@ -0,0 +1,19 @@
+import { AlignMode, DistributeMode } from '../utils/alignDistribute.js';
+export type { AlignMode, DistributeMode } from '../utils/alignDistribute.js';
+export interface UseAlignDistributeResult {
+    /** Number of movable (selected, unlocked) elements. */
+    movableCount: number;
+    /** True when align commands have something to act on. */
+    canAlign: boolean;
+    /** True when distribute commands are available (≥3 movable elements).
+     *  UI must gate rendering of distribute affordances on this. */
+    canDistribute: boolean;
+    /** Align the movable selection. ≥2 elements: relative to the selection's
+     *  combined bbox; exactly 1: relative to the active artboard. */
+    align: (mode: AlignMode) => void;
+    /** Distribute the movable selection with equal gaps between bbox edges.
+     *  Throws `E_DISTRIBUTE_MIN_THREE` when `canDistribute` is false. */
+    distribute: (mode: DistributeMode) => void;
+}
+export declare function useAlignDistribute(): UseAlignDistributeResult;
+export default useAlignDistribute;

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-Bx2MxFfy.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-Bx2MxFfy.js";
-import { E as _, S as y, S as L, u as O, a as M } from "./SnowconeCanvas-4ef4a61J.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-DJ157D3E.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-DnAkXdUg.js";
-import { C as W, D as X, d as $, s as ee } from "./design-builder-U7Su9MMC.js";
+import { e as u } from "./UnifiedFontService-BJzoqfBF.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-BJzoqfBF.js";
+import { E as _, S as y, S as L, u as O, a as M } from "./SnowconeCanvas-CQiFVR0X.js";
+import { u as d, a as m } from "./editorErrors-8uDRMhow.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-ai7vnW8g.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-B8kIYutI.js";
+import { C as W, D as X, d as $, s as ee } from "./design-builder-bquxIHct.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-kL09wsAn.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-B_3GISlW.js";
+import { r as p } from "./ExportManager-J2xK86uq.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-J2xK86uq.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-PE6nysqE.js";
+import { A as Hr, e as Or, C as Fr, S as Lr } from "./CanvasStateV1-kL09wsAn.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,