@snowcone-app/canvas 0.21.3 → 0.23.0

package/dist/api/embed.d.ts

@@ -49,8 +49,10 @@ export { useRealtimeMockups } from '../components/embed-realtime/useRealtimeMock
 export type { UseRealtimeMockupsResult } from '../components/embed-realtime/useRealtimeMockups.js';
 export { validateEmbed, collectEmbedIssues } from '../components/embed-realtime/validateEmbed.js';
 export type { ValidateEmbedInput, EmbedIssue } from '../components/embed-realtime/validateEmbed.js';
-export { design, DesignBuilder, isLayerToken } from '../design/design-builder.js';
-export type { Anchor, ShapeKind, DesignArtboard, StateArtboard, FromStateOptions, AnyDesign, LayerKind, LayerToken, } from '../design/design-builder.js';
+export { productToRenderConfig } from '../design/product-config.js';
+export type { ProductRenderConfig, ProductRenderConfigOptions } from '../design/product-config.js';
+export { design, DesignBuilder, isLayerToken, isColorToken } from '../design/design-builder.js';
+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 { useLayers } from '../hooks/useLayers.js';
@@ -77,6 +79,6 @@ export { CanvasServicesProvider, useCanvasServices } from '../contexts/CanvasSer
 export type { CanvasServices, ResolvedCanvasServices } from '../contexts/CanvasServicesContext.js';
 export { createProxyImageSearch, createProxyGenerate } from '../services/imageSearch.js';
 export type { ImageSearchProvider, ImageSearchResult, ImageSearchResponse, ImageSearchParams, GenerateProvider, GenerateParams, GenerateResponse, } from '../services/imageSearch.js';
-export type { RenderProduct, RenderProductOptions, RenderProductCombination, RenderProductRequiredPlacement, MockupResult, RealtimeGrant, } from '@snowcone-app/sdk';
+export type { CatalogProduct, RenderProduct, RenderProductOptions, RenderProductCombination, RenderProductRequiredPlacement, MockupResult, RealtimeGrant, } from '@snowcone-app/sdk';
 export { SnowconeEditor, formatBuyPrice } from '../default-editor/SnowconeEditor.js';
 export type { SnowconeEditorProps } from '../default-editor/SnowconeEditor.js';

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

@@ -16,6 +16,15 @@ export interface EditorCanvasProps {
     children?: ReactNode;
     /** Cap the canvas height in px. */
     maxHeight?: number;
+    /**
+     * The canvas's built-in selection-anchored floating toolbar (default
+     * `true`). Pass `false` when your composition owns the contextual zone —
+     * e.g. a conditionally-rendered `<Editor.Controls placement="docked"/>` —
+     * so suppression is declared HERE, in the type surface, rather than implied
+     * by whether a docked Controls happens to be mounted this frame (a mounted
+     * docked Controls still suppresses it either way, ADR-0085 §5).
+     */
+    floatingToolbar?: boolean;
     className?: string;
     style?: CSSProperties;
 }

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

@@ -2,6 +2,7 @@ import { default as React, ReactNode } from 'react';
 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';
 /**
  * How the session authorizes. Provide exactly one — the discriminated union makes
  * "I forgot the grant" a compile error rather than a silent runtime hang.
@@ -41,6 +42,16 @@ export type EditorRootBaseProps = {
     onMockups?: (results: MockupResult[]) => void;
     /** Called on a render/timeout error. */
     onRenderError?: (message: string) => void;
+    /**
+     * The machine-readable advisory channel (F3's other half): every non-fatal
+     * issue — warn-severity wiring problems at mount, the runtime `slow-render`
+     * stall — is delivered here, in dev AND prod. Console output is as
+     * invisible to a headless agent as it is to production telemetry; assert on
+     * this callback instead of scraping logs. (Error-severity wiring issues
+     * don't arrive here — they throw `EditorError E_EMBED_CONFIG` into Root's
+     * boundary.)
+     */
+    onIssue?: (issue: EmbedIssue) => void;
     /** Override the realtime WS endpoint (defaults to the SDK's prod URL). */
     wsUrl?: string;
     /**

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

@@ -6,13 +6,19 @@ export interface ValidateEmbedInput {
     design: AnyDesign;
     hasGrant: boolean;
 }
-/** One wiring problem found at mount. `error`-severity issues break the embed
- *  (no render will ever arrive / it targets the wrong thing); `warn`-severity
- *  issues are advisory. */
+/** One wiring problem found at mount, or a runtime stall. `error`-severity
+ *  issues break the embed (no render will ever arrive / it targets the wrong
+ *  thing); `warn`-severity issues are advisory. Every issue also reaches the
+ *  host through `Editor.Root`'s `onIssue` — the machine-readable channel
+ *  (console.warn is as invisible to a headless agent as console.error). */
 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: 'missing-shop' | 'missing-grant' | 'empty-mockup-ids' | 'variant-required' | 'multi-placement' | 'placement-mismatch' | '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. */
+     | 'slow-render';
     message: string;
 }
 /** Find every wiring problem. Pure — no logging, no throwing. */

package/dist/design/design-builder.d.ts

@@ -12,8 +12,18 @@ export interface DesignArtboard {
     width: number;
     height: number;
     /** Optional solid background fill behind all elements. Rendered everywhere
-     *  the design is — editor, exports, and server renders (realtime mockups). */
-    backgroundColor?: string;
+     *  the design is — editor, exports, and server renders (realtime mockups).
+     *  NOTE: the background is not an element, so it is NOT repaintable by
+     *  `useColorBinding` — designs that want a rebindable backdrop paint a
+     *  full-bleed `shape('rectangle', { fill: … })` instead. */
+    backgroundColor?: string | ColorToken;
+    /** Named color ROLES for value-matched rebinding (`useColorBinding`).
+     *  Mint tokens with `design.color('role')`; use them as `fill`/`color`
+     *  values so role and element can never drift. Validated at mint:
+     *  duplicate values across roles throw `E_COLOR_ROLE_COLLISION` (a
+     *  value-matched binding can't tell colliding roles apart), non-hex
+     *  values throw `E_COLOR_ROLE_INVALID`. */
+    colors?: Record<string, string>;
     /** Pacing role in a multi-page template (ADR-0086 albums). Template
      *  metadata only — never sent on the server render wire. */
     role?: ArtboardRole;
@@ -71,7 +81,8 @@ export interface TextOptions extends NamedOption {
     anchor?: Anchor;
     fontSize?: number;
     fontFamily?: string;
-    color?: string;
+    /** Hex string, or a `design.color('role')` token (resolved at build). */
+    color?: string | ColorToken;
     /** Horizontal text alignment. Named `textAlign` to match the canvas editor's
      *  element field (not `align`), so the builder and the editor read the same. */
     textAlign?: 'left' | 'center' | 'right';
@@ -87,7 +98,8 @@ export interface ShapeOptions extends NamedOption {
         width: number;
         height: number;
     };
-    fill?: string;
+    /** Hex string, or a `design.color('role')` token (resolved at build). */
+    fill?: string | ColorToken;
     rotation?: number;
     opacity?: number;
     /** star points / polygon sides. */
@@ -122,6 +134,30 @@ export interface LayerToken<K extends LayerKind = LayerKind, N extends string =
 }
 /** Runtime check used by parts before trusting a `layer` prop. */
 export declare function isLayerToken(value: unknown): value is LayerToken;
+declare const COLOR_TOKEN_BRAND: unique symbol;
+/**
+ * A validated claim that color role `N` exists in the design that minted it,
+ * carrying the role's (normalized) hex value. `useColorBinding` accepts it in
+ * place of a bare hex, so the chip and the painted elements can never drift —
+ * and `design({ colors })` rejects role-value collisions at mint time, which a
+ * value-matched binding cannot survive (one role's repaint would capture the
+ * other role's elements). Mint with {@link DesignBuilder.color}; not
+ * constructible by hand (branded).
+ */
+export interface ColorToken<N extends string = string> {
+    readonly name: N;
+    /** Normalized uppercase `#RRGGBB`. */
+    readonly value: string;
+    /** @internal */
+    readonly [COLOR_TOKEN_BRAND]: true;
+}
+/** Runtime check used by `useColorBinding` (and the builder's value slots)
+ *  before trusting a color value. */
+export declare function isColorToken(value: unknown): value is ColorToken;
+/** Normalize `#RGB`/`#RRGGBB` (any case) to uppercase `#RRGGBB` — the same
+ *  normalization `useColorBinding` matches with. Returns null when the value
+ *  is not a parsable hex color. */
+export declare function normalizeRoleHex(color: string): string | null;
 /** The token kind inferred for name `N` against the builder's accumulated
  *  per-kind name unions. A dynamically-loaded design (both unions degraded to
  *  `string`) yields the full `'text' | 'image'` union — typing degrades, the
@@ -141,9 +177,11 @@ type InferKind<N extends string, TText extends string, TImage extends string> =
  * API, runtime-validated instead (the degradation is deliberate and LOUD in
  * docs; never block the dynamic case).
  */
-export declare class DesignBuilder<out TText extends string = string, out TImage extends string = string> {
+export declare class DesignBuilder<out TText extends string = string, out TImage extends string = string, out TColor extends string = string> {
     private readonly artboard;
     private readonly els;
+    /** Declared color roles, name → normalized uppercase `#RRGGBB`. */
+    private readonly colorRoles;
     private idCounter;
     /** Every artboard of a multi-page state (fromState `{ artboards: 'all' }`);
      *  unset for single-artboard builders. */
@@ -177,19 +215,19 @@ export declare class DesignBuilder<out TText extends string = string, out TImage
      *  not one union with text — ADR-0085 §1). */
     background<const N extends string>(imageUrl: string, opts: BackgroundOptions & {
         name: N;
-    }): DesignBuilder<TText, TImage | N>;
-    background(imageUrl: string, opts?: BackgroundOptions): DesignBuilder<TText, TImage | 'Background'>;
+    }): DesignBuilder<TText, TImage | N, TColor>;
+    background(imageUrl: string, opts?: BackgroundOptions): DesignBuilder<TText, TImage | 'Background', TColor>;
     /** An anchored image element (not full-bleed). */
     image<const N extends string>(imageUrl: string, opts: ImageOptions & {
         name: N;
-    }): DesignBuilder<TText, TImage | N>;
-    image(imageUrl: string, opts?: ImageOptions): DesignBuilder<TText, TImage>;
+    }): DesignBuilder<TText, TImage | N, TColor>;
+    image(imageUrl: string, opts?: ImageOptions): DesignBuilder<TText, TImage, TColor>;
     /** An anchored text layer. Horizontal centring is exact (textAlign); vertical
      *  anchoring uses the font size as the line-height estimate. */
     text<const N extends string>(text: string, opts: TextOptions & {
         name: N;
-    }): DesignBuilder<TText | N, TImage>;
-    text(text: string, opts?: TextOptions): DesignBuilder<TText, TImage>;
+    }): DesignBuilder<TText | N, TImage, TColor>;
+    text(text: string, opts?: TextOptions): DesignBuilder<TText, TImage, TColor>;
     /**
      * Mint a {@link LayerToken} for a named layer — the only currency
      * `Editor.TextField` accepts (ADR-0085 §1). Compile time: `name` is
@@ -204,6 +242,20 @@ export declare class DesignBuilder<out TText extends string = string, out TImage
      *   is not bindable (shape/group/path).
      */
     layer<N extends TText | TImage>(name: N): LayerToken<InferKind<N, TText, TImage>, N>;
+    /**
+     * Mint a {@link ColorToken} for a declared color role. Compile time: `name`
+     * is constrained to the roles declared in `design({ colors })`. Runtime:
+     * validated against the declared roles (CMS/JSON-built designs degrade to
+     * `string` typing and rely on this throw).
+     *
+     * Use the token wherever the design paints the role (`fill`, `color`) AND
+     * as the `useColorBinding` argument — one source of truth, no hand-synced
+     * hex pairs.
+     *
+     * @throws EditorError `E_COLOR_ROLE_NOT_FOUND` — no role with this name;
+     *   lists the declared roles.
+     */
+    color<N extends TColor>(name: N): ColorToken<N>;
     /** Names of bindable layers of one kind, in stack order. @internal */
     layerNamesOfKind(kind: LayerKind): string[];
     /** An anchored vector shape. */
@@ -236,7 +288,10 @@ export declare class DesignBuilder<out TText extends string = string, out TImage
  * // …or hand d.toJSON() to <SnowconeCanvas/> for interactive editing — the
  * // `name`s let you bind layers with useImageBinding('art') / useTextBinding('headline').
  */
-export declare function design(artboard: DesignArtboard): DesignBuilder<never, never>;
+export declare function design<const C extends Record<string, string>>(artboard: DesignArtboard & {
+    colors: C;
+}): DesignBuilder<never, never, Extract<keyof C, string>>;
+export declare function design(artboard: DesignArtboard): DesignBuilder<never, never, never>;
 /**
  * Resolve a layer's kind against a live element/config list — the mount-time
  * revalidation `Editor.TextField` runs (the token is a validated claim; the

package/dist/design/product-config.d.ts

@@ -0,0 +1,48 @@
+import { CatalogProduct, RenderProduct } from '@snowcone-app/sdk';
+export interface ProductRenderConfigOptions {
+    /** Placement label to edit (e.g. "Back"). Defaults to the product's first
+     *  renderable image placement. Unknown labels throw with `validNames`. */
+    placement?: string;
+    /** Render width passthrough (`product.width`) — bump to ~2000 for a crisp
+     *  full-bleed preview. `Editor.Preview` hints in dev when it's too low. */
+    width?: number;
+}
+export interface ProductRenderConfig {
+    /** Ready for `<Editor.Root product={…}>` — advisory fields included so
+     *  wiring mistakes fail loud at mount. */
+    product: RenderProduct;
+    /** The placement being edited — seed `design({ name: label, width, height })`
+     *  from exactly these values. */
+    placement: {
+        label: string;
+        /** Artboard pixel dimensions (the placement's print-file geometry). */
+        width: number;
+        height: number;
+        /** width / height — for sizing the host's canvas stage. */
+        aspectRatio: number;
+    };
+    /** Every editable (non-color) placement label — placement pickers. */
+    placementLabels: string[];
+    /** First mockup scene that photographs the rendered variant — the default
+     *  `<Editor.Preview mockupId>`. */
+    primaryMockupId: string;
+    /** The variant the config renders against (`undefined` when no color axis
+     *  gates rendering). Already set on `product`. */
+    variantId: string | undefined;
+}
+/**
+ * Derive the full embed wiring from one `getProduct()` payload.
+ *
+ * ```ts
+ * const config = productToRenderConfig(await getProduct('BEEB77'));
+ * const seed = design({ name: config.placement.label, ...config.placement })
+ *   .text('hello', { anchor: 'center', name: 'headline' });
+ *
+ * <Editor.Root shop={SHOP} product={config.product} design={seed} grantUrl="/api/realtime-grant">
+ * ```
+ *
+ * @throws EditorError `E_PRODUCT_NOT_RENDERABLE` when the product has no
+ *   renderable image placement, no mockup scenes, or `options.placement`
+ *   names a placement that doesn't exist (`data.validNames` lists the real ones).
+ */
+export declare function productToRenderConfig(catalogProduct: CatalogProduct, options?: ProductRenderConfigOptions): ProductRenderConfig;