@snowcone-app/canvas 0.17.1 → 0.17.3

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

@@ -0,0 +1,114 @@
+import { default as React } from 'react';
+import { CanvasError, AnyElementConfig } from '../../types/index.js';
+import { AlignmentPoint, ArtboardConfig, CanvasState, ExportStatusEvent, PieceGuidesConfig, SnowconeCanvasHandle } from './SnowconeCanvas.js';
+export type ImageLoadingState = 'idle' | 'loading' | 'success' | 'error';
+/**
+ * Calculate the effective export scale for an artboard.
+ * If the scaled dimensions would exceed maxSize, reduces the scale to cap at maxSize.
+ *
+ * @param width - Artboard width in pixels
+ * @param height - Artboard height in pixels
+ * @param requestedScale - The requested export scale multiplier
+ * @param maxSize - Maximum dimension (largest side) for exported image
+ * @returns The effective scale to use (may be lower than requestedScale)
+ */
+export declare function calculateEffectiveScale(width: number, height: number, requestedScale: number, maxSize: number): number;
+/**
+ * Error channel: structured `onError` emission + the CanvasRenderer static
+ * render-error wire + the ErrorBoundary handler.
+ */
+export declare function useCanvasErrorChannel(onError: ((error: CanvasError) => void) | undefined): {
+    emitError: (error: CanvasError) => void;
+    handleBoundaryError: (error: Error) => void;
+};
+export interface ArtboardKernelOptions {
+    artboardConfigs: ArtboardConfig[] | undefined;
+    width: number;
+    height: number;
+    pieceGuides: PieceGuidesConfig | undefined;
+    controlledActiveArtboard: string | undefined;
+    onArtboardChange: ((name: string) => void) | undefined;
+    /**
+     * Rebuild the editor document from scratch on mount (clear artboards +
+     * elements first). Used by `Editor.Canvas`: with the P1 inversion the
+     * editor document lives at `Editor.Root` and OUTLIVES Canvas mounts, so a
+     * remount must reflect the live seed instead of accreting onto the previous
+     * mount's artboards/elements (the D8 soak cycles exactly this).
+     * @internal
+     */
+    resetDocumentOnMount?: boolean;
+}
+/**
+ * Artboard init + controlled `activeArtboard` sync + `onArtboardChange`.
+ */
+export declare function useArtboardKernel(opts: ArtboardKernelOptions): void;
+export interface InitialElementsKernelOptions {
+    initialElements: AnyElementConfig[] | undefined;
+    emitError: (error: CanvasError) => void;
+}
+/**
+ * Restore saved state (`initialElements`) onto the named artboards, then
+ * best-effort load the referenced fonts and force one repaint.
+ */
+export declare function useInitialElementsKernel(opts: InitialElementsKernelOptions): {
+    initialElementsLoadedState: boolean;
+};
+export interface InitialImageKernelOptions {
+    initialImage: string | undefined;
+    initialImageAlignment: AlignmentPoint;
+    initialImageScale: number;
+    initialImageScaleMode: 'cover' | 'contain';
+    artboardConfigs: ArtboardConfig[] | undefined;
+    onImageLoad: ((src: string) => void) | undefined;
+    onImageError: ((src: string, error: Error) => void) | undefined;
+    emitError: (error: CanvasError) => void;
+}
+/**
+ * Load `initialImage` into every artboard with cover/contain placement.
+ */
+export declare function useInitialImageKernel(opts: InitialImageKernelOptions): {
+    imageLoadingState: ImageLoadingState;
+    imageError: Error | null;
+};
+export interface ChangeCallbacksKernelOptions {
+    onChange: ((state: CanvasState) => void) | undefined;
+    onSelectionChange: ((elementId: string | null) => void) | undefined;
+}
+/**
+ * `onChange` / `onSelectionChange` emission. Both fire through latest-refs so
+ * an inline callback (a fresh closure identity on every host render) can't
+ * re-trigger the effects — the component must not require consumers to
+ * memoize their callbacks. Depending on the callback identity turns "callback
+ * updates host state" into an infinite render loop; depending only on the
+ * DATA fires exactly when the canvas actually changes. Pinned by
+ * SnowconeCanvas.onChange-loop.test.tsx.
+ */
+export declare function useChangeCallbacksKernel(opts: ChangeCallbacksKernelOptions): void;
+export interface ExportKernelOptions {
+    autoExportInterval: number | undefined;
+    autoExportConfig: {
+        enabled?: boolean;
+        debounceMs?: number;
+        maxWaitMs?: number;
+    } | undefined;
+    autoExportFormat: 'dataUrl' | 'blob';
+    autoExportAll: boolean;
+    exportScale: number;
+    maxExportSize: number;
+    exportImageFormat: 'png' | 'jpg' | 'jpeg' | 'webp';
+    exportImageQuality: number;
+    onExport: ((exports: Record<string, string | Blob>) => void) | undefined;
+    onExportScheduled: (() => void) | undefined;
+    onExportStatus: ((event: ExportStatusEvent) => void) | undefined;
+    onExportReady: ((exportFn: () => Promise<Record<string, string | Blob>>) => void) | undefined;
+    onReady: (() => void) | undefined;
+    hasInitialElements: boolean;
+    initialElementsLoaded: boolean;
+    emitError: (error: CanvasError) => void;
+}
+/**
+ * Export kernel: the imperative `exportArtboards` handle, `onExportReady`,
+ * smart auto-export (debounced, change-detected), content readiness, the
+ * `onReady` signal, and the canvas-ready gate.
+ */
+export declare function useExportKernel(opts: ExportKernelOptions, ref: React.ForwardedRef<SnowconeCanvasHandle>): void;

package/dist/contexts/BoundLayerGuardContext.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Bound-layer mutation guard (ADR-0085 §3, enforced in P1).
+ *
+ * While an `Editor.TextField` is registered for layer N, renaming or deleting
+ * layer N must be impossible: the editor UI suppresses the affordances, and
+ * the programmatic command path throws `E_BOUND_LAYER_MUTATION` naming the
+ * bound part — so an end-user gesture can never detonate the prod error card
+ * (the invalid state is unreachable from the UI), while agent/host code gets
+ * a loud structured throw.
+ *
+ * `Editor.Root` provides its parts registry through this context ABOVE
+ * `EditorProvider`, so the command layer (`useCommandHistory`) and the chrome
+ * (LayersPanel, keyboard shortcuts) can consult it. Without a Root (legacy
+ * standalone `SnowconeCanvas`) the context is null and nothing changes.
+ *
+ * This module is deliberately dependency-free: it sits in the always-mounted
+ * Editor.Root graph (renderer-free, CI-gated) and is imported by both the
+ * contexts layer and the editor parts.
+ */
+export interface BoundLayerGuard {
+    /** Subscribe to registry changes (TextFields mount/unmount). */
+    subscribe(listener: () => void): () => void;
+    /** Monotonic version for `useSyncExternalStore`. */
+    getVersion(): number;
+    /** The part bound to a layer name, or null when the layer is unbound. */
+    getBoundLayer(name: string): {
+        part: string;
+    } | null;
+}
+export declare const BoundLayerGuardContext: import('react').Context<BoundLayerGuard | null>;
+/**
+ * Reactive bound-layer test for UI suppression: re-renders when TextFields
+ * mount/unmount, so rename/delete affordances appear the moment a layer
+ * stops being bound. Always returns false outside an `<Editor.Root>`.
+ */
+export declare function useIsLayerBound(): (name: string | undefined) => boolean;

package/dist/core/GroupElement.d.ts

@@ -59,11 +59,6 @@ export declare class GroupElement extends BaseElement {
      * Elements with isClipping=true clip all elements below them in the group
      */
     render(ctx: CanvasRenderingContext2D, isSelected?: boolean, isHovered?: boolean): void;
-    /**
-     * Render group with clipping masks
-     * Elements with isClipping=true clip all elements below them
-     */
-    private _renderWithClipping;
     /**
      * Render dashed outline around group
      * Uses an oriented bounding box that doesn't change size during rotation

package/dist/core/TextElement.d.ts

@@ -20,10 +20,15 @@ export declare class TextElement extends BaseElement {
      */
     getBoundingBox(): BoundingBox;
     /**
-     * Render the element
-     * Must be implemented by subclasses
+     * Render the element.
+     *
+     * Paints through the paint registry (P1 element/renderer split): the shared
+     * paint function for this transformType is registered by the rendering
+     * engine (`src/rendering/element-painters.ts`), so the element model never
+     * statically imports the paint pipeline. Selection and hover visuals are
+     * handled by SelectionRenderer and HoverRenderer.
      */
-    render(_ctx: CanvasRenderingContext2D, _isSelected?: boolean, _isHovered?: boolean): void;
+    render(ctx: CanvasRenderingContext2D, _isSelected?: boolean, _isHovered?: boolean): void;
     /**
      * Serialize to JSON
      */

package/dist/core/paint-registry.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Paint registry — the dependency-inversion seam between the element MODEL
+ * and the rendering engine (ADR-0085 / D9, the P1 element/renderer split).
+ *
+ * The element classes (TextElement subclasses, GroupElement) are STATE: they
+ * mount with `Editor.Root` in every composition, including the no-canvas
+ * personalization widget, so their static import graph must stay renderer-free
+ * (CI-gated by scripts/check-import-graph.mjs). Their `render()` methods used
+ * to statically import the shared paint functions from `src/rendering/*`,
+ * dragging the whole paint pipeline into the always-mounted graph.
+ *
+ * Inversion: the model looks paint functions up HERE at paint time; the heavy
+ * side (`src/rendering/element-painters.ts`, inside `Editor.Canvas`'s lazy
+ * chunk) registers them at module evaluation. Every module that DRIVES element
+ * painting (CanvasRenderer, ExportManager, ElementPreviewRenderer) imports the
+ * painters module, so by the time any `element.render()` runs the registry is
+ * populated — a miss is an internal wiring bug, not a user-reachable state,
+ * and throws with the fix in the message.
+ */
+/** Paints one serialized text-transform element. The serialized shape is the
+ *  element's `toJSON()` output; the heavy side narrows it to its concrete
+ *  Serialized*Element type. */
+export type TextTransformPainter = (ctx: CanvasRenderingContext2D, serialized: object) => void;
+/** The subset of an element the group-clipping compositor needs — structural
+ *  on purpose so this module never imports an element class. */
+export interface PaintableChild {
+    isClipping?: boolean;
+    transformType: string;
+    render(ctx: CanvasRenderingContext2D, isSelected?: boolean, isHovered?: boolean): void;
+    getBoundingBox(): {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+}
+/** Composites a group's children honoring `isClipping` masks. */
+export type GroupClippingPainter = (ctx: CanvasRenderingContext2D, children: PaintableChild[]) => void;
+export declare function registerTextTransformPainter(type: string, painter: TextTransformPainter): void;
+export declare function getTextTransformPainter(type: string): TextTransformPainter;
+export declare function registerGroupClippingPainter(painter: GroupClippingPainter): void;
+export declare function getGroupClippingPainter(): GroupClippingPainter;

package/dist/core/rich-text-layout.d.ts

@@ -0,0 +1,28 @@
+import { CharacterStyle, RichText } from '../types/index.js';
+/**
+ * Wrap rich text spans to fit within a given width, preserving character-level formatting
+ *
+ * This function handles character-level formatting correctly by:
+ * 1. First merging consecutive spans with the same style
+ * 2. Finding word boundaries (spaces) across spans
+ * 3. Wrapping at word boundaries, not at span boundaries
+ */
+export declare function wrapRichTextSpans(spans: Array<{
+    text: string;
+    style: CharacterStyle;
+}>, maxWidth: number, element: {
+    fontSize: number;
+    fontFamily: string;
+    bold?: boolean;
+    italic?: boolean;
+}): Array<{
+    text: string;
+    style: CharacterStyle;
+}[]>;
+/**
+ * Split rich text into lines by explicit newlines, preserving span formatting
+ */
+export declare function splitRichTextIntoLines(richText: RichText): Array<{
+    text: string;
+    style: CharacterStyle;
+}[]>;

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

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

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

@@ -1 +1 @@
-{"version":3,"file":"editorErrors-DbIEtCTt.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-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;"}