@snowcone-app/canvas 0.8.1 → 0.11.1

package/dist/advanced.mjs

@@ -1,5 +1,5 @@
-import { D as te, I as q, r as re, v as ne, h as oe, e as ae } from "./validation-CZ4CZV5B.js";
-import { i as it, j as lt, k as ct, B as dt, l as ut, m as mt, n as ft, o as ht, p as pt, q as gt, s as xt, t as bt, w as yt, x as vt, F as wt, y as St, G as Ct, z as Tt, H as Et, J as $t, K as kt, L as At, N as Ft, O as Pt, Q as Nt, R as Rt, S as Bt, T as Mt, U as Dt, V as zt, W as It, X as Ot, Y as Lt, Z as Wt, _ as Kt, $ as _t, a0 as Gt, a1 as Ut, a2 as jt, a3 as Jt, a4 as qt, a5 as Vt, a6 as Xt, a7 as Yt, a8 as Zt, a9 as Ht, aa as Qt, ab as er, ac as tr, ad as rr, ae as nr } from "./validation-CZ4CZV5B.js";
+import { D as te, I as q, r as re, v as ne, i as oe, e as ae } from "./validation-C857Ptxn.js";
+import { j as it, k as lt, l as ct, B as dt, m as ut, n as mt, o as ft, p as ht, q as pt, s as gt, t as xt, w as bt, x as yt, y as vt, F as wt, z as St, G as Ct, H as Tt, J as Et, K as $t, L as kt, N as At, O as Ft, Q as Pt, R as Nt, S as Rt, T as Bt, U as Mt, V as Dt, W as zt, X as It, Y as Ot, Z as Lt, _ as Wt, $ as Kt, a0 as _t, a1 as Gt, a2 as Ut, a3 as jt, a4 as Jt, a5 as qt, a6 as Vt, a7 as Xt, a8 as Yt, a9 as Zt, aa as Ht, ab as Qt, ac as er, ad as tr, ae as rr, af as nr } from "./validation-C857Ptxn.js";
 import { u as V } from "./ThemeContext-U-VDtIiS.js";
 import { E as ar, P as sr, T as ir, p as lr, s as cr, b as dr, c as ur, d as mr, e as fr, f as hr, g as pr, a as gr } from "./ThemeContext-U-VDtIiS.js";
 import { c as se, G as ie, F as le, g as ce, r as de, u as ue } from "./HybridHistoryManager-DANuzx7G.js";

package/dist/api/embed.d.ts

@@ -48,7 +48,11 @@ export { design, DesignBuilder } from '../design/design-builder.js';
 export type { Anchor, ShapeKind, DesignArtboard } from '../design/design-builder.js';
 export { useTextBinding } from '../hooks/useTextBinding.js';
 export { useImageBinding } from '../hooks/useImageBinding.js';
+export { useColorBinding } from '../hooks/useColorBinding.js';
+export type { ColorBindingResult } from '../hooks/useColorBinding.js';
 export { useElementByName } from '../hooks/useElementByName.js';
+export { readTemplateFields, withTemplateFields, TEMPLATE_FIELDS_KEY, } from '../design/template-fields.js';
+export type { TemplateField, TemplateTextField, TemplateImageField, TemplateColorField, } from '../design/template-fields.js';
 export { CanvasServicesProvider, useCanvasServices } from '../contexts/CanvasServicesContext.js';
 export type { CanvasServices, ResolvedCanvasServices } from '../contexts/CanvasServicesContext.js';
 export { createProxyImageSearch, createProxyGenerate } from '../services/imageSearch.js';

package/dist/api/stable.d.ts

@@ -10,8 +10,8 @@ export { SnowconeCanvas, SnowconeCanvas as default } from '../components/embed/S
 export type { SnowconeCanvasProps, SnowconeCanvasHandle, ArtboardConfig, CanvasState, ClipShape, AlignmentPoint, ExportStatusEvent, ExportConfig, ImageConfig, LayoutConfig, CanvasCutoutShape } from '../components/embed/SnowconeCanvas.js';
 export { CanvasServicesProvider, useCanvasServices } from '../contexts/CanvasServicesContext.js';
 export type { CanvasServices, ResolvedCanvasServices, VectorSearchProvider, VectorSearchResult, } 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 { createProxyImageSearch, createProxyGenerate, createProxyBgRemove } from '../services/imageSearch.js';
+export type { ImageSearchProvider, ImageSearchResult, ImageSearchResponse, ImageSearchParams, GenerateProvider, GenerateParams, GenerateResponse, BgRemoveProvider, } from '../services/imageSearch.js';
 export { useEditor } from '../contexts/EditorContext.js';
 export type { EditorContextValue, EditorProviderProps } from '../contexts/EditorContext.js';
 export { useArtboards } from '../hooks/useArtboards.js';
@@ -30,6 +30,8 @@ export { useTextBinding } from '../hooks/useTextBinding.js';
 export type { TextBindingResult } from '../hooks/useTextBinding.js';
 export { useImageBinding } from '../hooks/useImageBinding.js';
 export type { ImageBindingResult, ImageBindingOptions, ImageFitMode } from '../hooks/useImageBinding.js';
+export { useColorBinding } from '../hooks/useColorBinding.js';
+export type { ColorBindingResult } from '../hooks/useColorBinding.js';
 export { useElementByName } from '../hooks/useElementByName.js';
 export { useContentReady } from '../hooks/useContentReady.js';
 export type { UseContentReadyOptions } from '../hooks/useContentReady.js';
@@ -48,4 +50,6 @@ export { serializeStateForServer, CANVAS_STATE_SCHEMA_VERSION, } from '../render
 export type { ServerRenderRequest } from '../rendering/serialize-for-server.js';
 export { design, DesignBuilder } from '../design/design-builder.js';
 export type { Anchor, ShapeKind, DesignArtboard, BackgroundOptions, ImageOptions, TextOptions, ShapeOptions, } from '../design/design-builder.js';
+export { readTemplateFields, withTemplateFields, TEMPLATE_FIELDS_KEY, } from '../design/template-fields.js';
+export type { TemplateField, TemplateTextField, TemplateImageField, TemplateColorField, } from '../design/template-fields.js';
 export type { CanvasStateV1, SerializedArtboard, SerializedElement, DeserializeResult, ValidationResult, } from '../state/index.js';

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

@@ -33,6 +33,14 @@ export interface ArtboardConfig {
     clipShape?: ClipShape;
     /** Optional background color */
     backgroundColor?: string;
+    /**
+     * Whether the background color is part of the design — painted in exports
+     * and server renders (realtime mockups), not just in the editor. Defaults to
+     * `true` when `backgroundColor` is explicitly set (and not 'transparent'),
+     * `false` otherwise: an author who sets a background expects the mockup to
+     * match the editor.
+     */
+    exportBackground?: boolean;
     /** Scale mode for initial image: "cover" fills area (may crop), "contain" fits inside (may have space). Default: "cover" */
     scaleMode?: 'cover' | 'contain';
     /** Top margin in pixels for contain mode (reduces available area) */

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

@@ -11,4 +11,24 @@ export interface RealtimeMockupProps {
     className?: string;
     style?: CSSProperties;
 }
+/**
+ * How far the displayed device-pixel width may exceed the delivered mockup's
+ * natural width before {@link resolutionMismatchHint} fires. Renders default to
+ * 1000px wide, so a 1000px image inside a ~1100 device-px slot is fine (browser
+ * downscale slack), but stretched across 2000 device px it looks soft and the
+ * developer deserves to hear why.
+ */
+export declare const RESOLUTION_MISMATCH_RATIO = 1.2;
+/** Rounds a device-pixel width up to the next {@link SUGGESTED_WIDTHS} step
+ *  (capped at the top step). */
+export declare function suggestRenderWidth(devicePx: number): number;
+/**
+ * Builds the dev-console warning shown when a delivered mockup's natural width
+ * is meaningfully below the width it's displayed at in DEVICE pixels (CSS width
+ * × `devicePixelRatio`) — the "my preview looks soft and nothing says why"
+ * trap: renders default to 1000px wide, which blurs on a large or high-density
+ * display. Returns `null` when the resolution is adequate (within
+ * {@link RESOLUTION_MISMATCH_RATIO}) or either measurement is unusable.
+ */
+export declare function resolutionMismatchHint(naturalWidth: number, devicePx: number): string | null;
 export declare function RealtimeMockup({ mockupId, fallback, alt, className, style, }: RealtimeMockupProps): React.ReactElement;

package/dist/contexts/CanvasServicesContext.d.ts

@@ -58,8 +58,15 @@ export interface CanvasServices {
     /** Vector/icon search provider (dev playground only — no wire contract yet). */
     vectors?: VectorSearchProvider;
     /**
-     * Background removal: given an image URL (or data URL), resolve to the
-     * processed image URL/data URL. Dev playground only — no wire contract yet.
+     * URL of your background-removal proxy route (`POST { imageUrl }` →
+     * `{ imageUrl }`; see `createProxyBgRemove` for the wire contract). Host this
+     * URL on your server; your bg-remove vendor key lives there.
+     */
+    bgRemoveUrl?: string;
+    /**
+     * Advanced override: full background-removal provider. Given an image URL
+     * (or data URL), resolve to the processed image URL/data URL. Wins over
+     * `bgRemoveUrl`.
      */
     removeBackground?: (imageUrl: string) => Promise<string>;
 }

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

@@ -11,7 +11,8 @@ export interface DesignArtboard {
     name?: string;
     width: number;
     height: number;
-    /** Optional solid background fill behind all elements. */
+    /** Optional solid background fill behind all elements. Rendered everywhere
+     *  the design is — editor, exports, and server renders (realtime mockups). */
     backgroundColor?: string;
 }
 /** A stable layer name. Set it so you can bind the layer in an interactive
@@ -77,6 +78,26 @@ export declare class DesignBuilder {
     private readonly els;
     private idCounter;
     constructor(artboard: DesignArtboard);
+    /**
+     * Seed a builder from a previously saved canvas state — the editor shape
+     * `<SnowconeCanvas onChange>` emits (and `toJSON()` produces).
+     *
+     * This is how a saved editable template re-enters the turnkey embed path:
+     * load the template's state JSON, lift it back into a `DesignBuilder`, and
+     * hand it to `<RealtimeEmbed design={…}>`. The active artboard becomes the
+     * builder's artboard; elements tagged for other artboards are skipped
+     * (untagged elements are assumed to belong to the active one).
+     */
+    static fromState(state: {
+        elements: AnyElementConfig[];
+        artboards: Array<{
+            name: string;
+            width: number;
+            height: number;
+            backgroundColor?: string;
+        }>;
+        activeArtboard: string;
+    }): DesignBuilder;
     private nextId;
     /** Full-bleed background image (fills the whole artboard). Cover-fit (no
      *  distortion) when `aspectRatio` is supplied. Inserted at the bottom of the
@@ -100,6 +121,7 @@ export declare class DesignBuilder {
             width: number;
             height: number;
             backgroundColor?: string;
+            exportBackground?: boolean;
         }>;
         activeArtboard: string;
     };

package/dist/design/template-fields.d.ts

@@ -0,0 +1,59 @@
+import { ImageFitMode } from '../hooks/useImageBinding.js';
+/** A buyer-editable text slot, bound to elements by their `name` property. */
+export interface TemplateTextField {
+    type: 'text';
+    /** Element name (matches canvas layer `name` property). */
+    name: string;
+    /** Label shown to the buyer (e.g. "Your name"). */
+    label: string;
+    /** Placeholder text for the input. */
+    placeholder?: string;
+}
+/** A buyer-swappable image slot, bound to elements by their `name` property. */
+export interface TemplateImageField {
+    type: 'image';
+    /** Element name (matches canvas layer `name` property). */
+    name: string;
+    /** Label shown to the buyer (e.g. "Upload your logo"). */
+    label: string;
+    /** Placeholder text for the input. */
+    placeholder?: string;
+    /** How the buyer's image fits the original element bounds. Default: "cover". */
+    fit?: ImageFitMode;
+}
+/** A buyer-editable color, matched by value across all elements that use it. */
+export interface TemplateColorField {
+    type: 'color';
+    /** Original hex color to match (e.g. "#FF0000"). */
+    color: string;
+    /** Label shown to the buyer (e.g. "Accent color"). */
+    label: string;
+}
+/** One buyer-editable aspect of a template. */
+export type TemplateField = TemplateTextField | TemplateImageField | TemplateColorField;
+/**
+ * The key template fields are stored under on the state document.
+ * Kept as `personalization` for compatibility with designs saved on snowcone.app.
+ */
+export declare const TEMPLATE_FIELDS_KEY = "personalization";
+/**
+ * Read the template fields off a parsed state document.
+ *
+ * Accepts any JSON value — a `CanvasState` from `onChange`, a `CanvasStateV1`
+ * document, or a raw `JSON.parse` of a stored state file. Legacy fields with
+ * no `type` are normalized to text fields; malformed entries are dropped.
+ * Returns `[]` when the document carries no fields (a plain, non-template design).
+ */
+export declare function readTemplateFields(state: unknown): TemplateField[];
+/**
+ * Attach template fields to a state document before persisting it.
+ *
+ * ```ts
+ * onChange={(state) => setDraft(state)}
+ * // …on save:
+ * save(JSON.stringify(withTemplateFields(draft, fields)));
+ * ```
+ */
+export declare function withTemplateFields<T extends object>(state: T, fields: TemplateField[]): T & {
+    [TEMPLATE_FIELDS_KEY]: TemplateField[];
+};

package/dist/embed.mjs

@@ -1,185 +1,210 @@
-import { a as L, e as z } from "./validation-CZ4CZV5B.js";
-import { c as pe, b as ve, d as be } from "./validation-CZ4CZV5B.js";
-import { y as x } from "./HybridHistoryManager-DANuzx7G.js";
-import { jsx as b, Fragment as J } from "react/jsx-runtime";
-import { createContext as W, useContext as H, useMemo as $, useRef as q, useState as C, useEffect as M } from "react";
+import { a as W, e as H } from "./validation-C857Ptxn.js";
+import { b as we, d as ye, f as Se } from "./validation-C857Ptxn.js";
+import { y as b } from "./HybridHistoryManager-DANuzx7G.js";
+import { jsx as E, Fragment as z } from "react/jsx-runtime";
+import { createContext as J, useContext as Y, useMemo as S, useRef as x, useState as q, useEffect as B } from "react";
 import { assertVariantSelected as Q, RenderSession as X } from "@snowcone-app/sdk";
-import { S as Y, s as Z } from "./design-builder-CM5wSK5w.js";
-import { D as $e, d as ke, c as Se, e as Ee, f as Re } from "./design-builder-CM5wSK5w.js";
-const F = W(void 0);
-function N() {
-  const e = H(F);
+import { S as Z, s as ee } from "./template-fields-C8Tj67ek.js";
+import { D as $e, T as Re, d as Te, r as Ie, a as xe, e as Me, f as Ue, g as Ce, w as Ne } from "./template-fields-C8Tj67ek.js";
+const L = J(void 0);
+function _() {
+  const e = Y(L);
   if (!e)
     throw new Error(
       "useRealtimeMockups / <RealtimeCanvas> / <RealtimeMockup> must be rendered inside <RealtimeEmbed>. Wrap them: <RealtimeEmbed shop=… product=… design=… grantUrl=…>…</RealtimeEmbed>"
     );
   return e;
 }
-const p = "[RealtimeEmbed]";
-function ee(e) {
-  var a, o;
-  if ((a = e == null ? void 0 : e.requiredPlacements) != null && a.length)
+const v = "[RealtimeEmbed]";
+function ne(e) {
+  var o, l;
+  if ((o = e == null ? void 0 : e.requiredPlacements) != null && o.length)
     return e.requiredPlacements.filter((t) => !t.autoFilledByVariant).map((t) => t.label);
   const n = new Set(
-    (((o = e == null ? void 0 : e.options) == null ? void 0 : o.combinations) ?? []).map((t) => t.variantId).filter((t) => typeof t == "string" && t !== "")
+    (((l = e == null ? void 0 : e.options) == null ? void 0 : l.combinations) ?? []).map((t) => t.variantId).filter((t) => typeof t == "string" && t !== "")
   );
   return !!(e != null && e.variantId) || n.size > 1 ? [] : (e == null ? void 0 : e.placements) ?? [];
 }
-function ne({ shop: e, product: n, design: s, hasGrant: a }) {
-  var v, i;
-  if (e || console.error(`${p} \`shop\` is required (your publishable shop id).`), a || console.error(
-    `${p} no grant source — pass \`grantUrl\` (a proxy to mintRealtimeGrant) or \`grant\`. Without it the session can never authorize and no mockup renders.`
-  ), (v = n == null ? void 0 : n.mockupIds) != null && v.length || console.error(
-    `${p} product.mockupIds is empty — pass the catalog scene codes (product.mockups[].id) you want rendered, e.g. ["FV1qjO"].`
+function te({ shop: e, product: n, design: s, hasGrant: o }) {
+  var u, a;
+  if (e || console.error(`${v} \`shop\` is required (your publishable shop id).`), o || console.error(
+    `${v} no grant source — pass \`grantUrl\` (a proxy to mintRealtimeGrant) or \`grant\`. Without it the session can never authorize and no mockup renders.`
+  ), (u = n == null ? void 0 : n.mockupIds) != null && u.length || console.error(
+    `${v} product.mockupIds is empty — pass the catalog scene codes (product.mockups[].id) you want rendered, e.g. ["FV1qjO"].`
   ), n != null && n.options)
     try {
       Q(n);
     } catch (r) {
-      console.error(`${p} ${r instanceof Error ? r.message : String(r)}`);
+      console.error(`${v} ${r instanceof Error ? r.message : String(r)}`);
     }
-  const o = s.toJSON(), t = o.activeArtboard, d = ee(n);
-  d.length > 1 && console.error(
-    `${p} product ${n.productId} requires placements [${d.join(", ")}] but <RealtimeEmbed> renders a single placement ("${t}"). The render will time out waiting for the others. This product needs the eject path — see https://developers.snowcone.app/embed-mode#eject.`
-  ), (i = n == null ? void 0 : n.placements) != null && i.length && !n.placements.includes(t) && console.warn(
-    `${p} the design's placement "${t}" is not in product.placements [${n.placements.join(", ")}]. The canvas artboard name and renderState placement must equal a real product placement label, or the server renders a blank mockup. Fix the \`name\` passed to design({ name }).`
+  const l = s.toJSON(), t = l.activeArtboard, f = ne(n);
+  f.length > 1 && console.error(
+    `${v} product ${n.productId} requires placements [${f.join(", ")}] but <RealtimeEmbed> renders a single placement ("${t}"). The render will time out waiting for the others. This product needs the eject path — see https://developers.snowcone.app/embed-mode#eject.`
+  ), (a = n == null ? void 0 : n.placements) != null && a.length && !n.placements.includes(t) && console.warn(
+    `${v} the design's placement "${t}" is not in product.placements [${n.placements.join(", ")}]. The canvas artboard name and renderState placement must equal a real product placement label, or the server renders a blank mockup. Fix the \`name\` passed to design({ name }).`
   );
-  const c = o.elements.map((r) => r.name).filter((r) => !!r), h = c.filter((r, l) => c.indexOf(r) !== l);
+  const c = l.elements.map((r) => r.name).filter((r) => !!r), h = c.filter((r, i) => c.indexOf(r) !== i);
   h.length && console.warn(
-    `${p} duplicate layer name(s) [${[...new Set(h)].join(", ")}] — useTextBinding(name) / useImageBinding(name) bind to the FIRST match, so a duplicate name makes a control edit the wrong layer. Keep names unique.`
+    `${v} duplicate layer name(s) [${[...new Set(h)].join(", ")}] — useTextBinding(name) / useImageBinding(name) bind to the FIRST match, so a duplicate name makes a control edit the wrong layer. Keep names unique.`
   );
 }
-function te(e) {
+function re(e) {
   if ("grantUrl" in e && e.grantUrl)
     return { grantUrl: e.grantUrl };
   const n = e.grant;
   return typeof n == "function" ? { getToken: n } : { getToken: () => Promise.resolve(n) };
 }
-const D = 8e3;
-function re(e) {
-  return `[RealtimeEmbed] No mockup after ${Math.round(D / 1e3)}s. Common causes: a variant product missing \`variantId\` (pass \`product.options\` so the embed can flag it up front), a multi-placement product (the server waits for every required placement but <RealtimeEmbed> sends only "${e}" — pass \`product.requiredPlacements\` so this is flagged at mount; such products need the eject path), an unreachable or non-public asset URL in the design, or the placement "${e}" not existing on the product. The render may still arrive — this is a heads-up, not a failure.`;
+const V = 8e3;
+function se(e) {
+  return `[RealtimeEmbed] No mockup after ${Math.round(V / 1e3)}s. Common causes: a variant product missing \`variantId\` (pass \`product.options\` so the embed can flag it up front), a multi-placement product (the server waits for every required placement but <RealtimeEmbed> sends only "${e}" — pass \`product.requiredPlacements\` so this is flagged at mount; such products need the eject path), an unreachable or non-public asset URL in the design, or the placement "${e}" not existing on the product. The render may still arrive — this is a heads-up, not a failure.`;
 }
-function me(e) {
-  const { shop: n, product: s, design: a, throttleMs: o = 200, onMockups: t, onRenderError: d, wsUrl: c, services: h, children: v } = e, i = $(() => a.toJSON().activeArtboard, [a]), r = q(t), l = q(d);
-  r.current = t, l.current = d;
-  const [j, G] = C([]), [k, y] = C(!0), [B, S] = C(null), w = !!("grantUrl" in e && e.grantUrl || "grant" in e && e.grant), I = te(e), _ = "grantUrl" in I ? I.grantUrl : "getToken", U = `${s.productId}|${s.mockupIds.join(",")}|${s.variantId ?? ""}`, E = $(
+function ge(e) {
+  const { shop: n, product: s, design: o, throttleMs: l = 200, onMockups: t, onRenderError: f, wsUrl: c, services: h, children: u } = e, a = S(() => o.toJSON().activeArtboard, [o]), r = x(t), i = x(f);
+  r.current = t, i.current = f;
+  const [w, k] = q([]), [$, y] = q(!0), [j, R] = q(null), M = !!("grantUrl" in e && e.grantUrl || "grant" in e && e.grant), U = re(e), G = "grantUrl" in U ? U.grantUrl : "getToken", C = `${s.productId}|${s.mockupIds.join(",")}|${s.variantId ?? ""}`, T = S(
     () => {
       try {
-        return { session: new X({ shop: n, product: s, wsUrl: c, ...I }) };
+        return { session: new X({ shop: n, product: s, wsUrl: c, ...U }) };
       } catch (m) {
         return { error: m instanceof Error ? m.message : String(m) };
       }
     },
     // eslint-disable-next-line react-hooks/exhaustive-deps
-    [n, U, i, c, _]
-  ), g = "session" in E ? E.session : null, R = "error" in E ? E.error : null, P = q(null);
-  M(() => {
+    [n, C, a, c, G]
+  ), g = "session" in T ? T.session : null, I = "error" in T ? T.error : null, P = x(null);
+  B(() => {
     var m;
-    if (typeof x < "u" && ((m = x.env) == null ? void 0 : m.NODE_ENV) !== "production") {
-      const u = `${n}|${U}|${i}|${w}`;
-      if (P.current === u) return;
-      P.current = u, ne({ shop: n, product: s, design: a, hasGrant: w });
+    if (typeof b < "u" && ((m = b.env) == null ? void 0 : m.NODE_ENV) !== "production") {
+      const d = `${n}|${C}|${a}|${M}`;
+      if (P.current === d) return;
+      P.current = d, te({ shop: n, product: s, design: o, hasGrant: M });
     }
-  }, [n, U, i, w]);
-  const T = $(() => (m, u = o) => {
-    g && (S(null), y(!0), g.renderState(i, m, u).catch((f) => {
-      var A;
-      const V = f instanceof Error ? f.message : String(f);
-      S(V), y(!1), (A = l.current) == null || A.call(l, V);
+  }, [n, C, a, M]);
+  const N = S(() => (m, d = l) => {
+    g && (R(null), y(!0), g.renderState(a, m, d).catch((p) => {
+      var F;
+      const D = p instanceof Error ? p.message : String(p);
+      R(D), y(!1), (F = i.current) == null || F.call(i, D);
     }));
-  }, [g, i, o]);
-  M(() => {
+  }, [g, a, l]);
+  B(() => {
     var m;
-    if (R) {
-      S(R), y(!1), (m = l.current) == null || m.call(l, R);
+    if (I) {
+      R(I), y(!1), (m = i.current) == null || m.call(i, I);
       return;
     }
     if (g)
-      return g.onMockups((u) => {
-        var f;
-        G(u), y(!1), (f = r.current) == null || f.call(r, u);
-      }), g.onError((u) => {
-        var f;
-        S(u), y(!1), (f = l.current) == null || f.call(l, u);
-      }), T(a.toServerRequest()), () => g.close();
-  }, [g, R]), M(() => {
-    var u;
-    if (!k || typeof x > "u" || ((u = x.env) == null ? void 0 : u.NODE_ENV) === "production") return;
-    const m = setTimeout(() => console.warn(re(i)), D);
+      return g.onMockups((d) => {
+        var p;
+        k(d), y(!1), (p = r.current) == null || p.call(r, d);
+      }), g.onError((d) => {
+        var p;
+        R(d), y(!1), (p = i.current) == null || p.call(i, d);
+      }), N(o.toServerRequest()), () => g.close();
+  }, [g, I]), B(() => {
+    var d;
+    if (!$ || typeof b > "u" || ((d = b.env) == null ? void 0 : d.NODE_ENV) === "production") return;
+    const m = setTimeout(() => console.warn(se(a)), V);
     return () => clearTimeout(m);
-  }, [k, i]);
-  const K = $(
+  }, [$, a]);
+  const K = S(
     () => ({
       session: g,
-      design: a,
-      placement: i,
+      design: o,
+      placement: a,
       product: s,
-      mockups: j,
-      isRendering: k,
-      error: B,
-      throttleMs: o,
-      pushRender: T
+      mockups: w,
+      isRendering: $,
+      error: j,
+      throttleMs: l,
+      pushRender: N
     }),
-    [g, a, i, s, j, k, B, o, T]
-  ), O = /* @__PURE__ */ b(F.Provider, { value: K, children: v });
-  return h ? /* @__PURE__ */ b(L, { services: h, children: O }) : O;
+    [g, o, a, s, w, $, j, l, N]
+  ), A = /* @__PURE__ */ E(L.Provider, { value: K, children: u });
+  return h ? /* @__PURE__ */ E(W, { services: h, children: A }) : A;
 }
-function ue({
+function he({
   children: e,
   kit: n = "embed-only",
   inheritTheme: s = !0,
-  maxHeight: a,
-  services: o,
+  maxHeight: o,
+  services: l,
   className: t,
-  style: d
+  style: f
 }) {
-  const { design: c, placement: h, throttleMs: v, pushRender: i } = N(), r = $(() => c.toJSON(), [c]);
-  return /* @__PURE__ */ b("div", { className: `app-modern${t ? ` ${t}` : ""}`, style: d, children: /* @__PURE__ */ b(
-    Y,
+  const { design: c, placement: h, throttleMs: u, pushRender: a } = _(), r = S(() => c.toJSON(), [c]);
+  return /* @__PURE__ */ E("div", { className: `app-modern${t ? ` ${t}` : ""}`, style: f, children: /* @__PURE__ */ E(
+    Z,
     {
       kit: n,
       inheritTheme: s,
-      services: o,
+      services: l,
       artboards: r.artboards,
       activeArtboard: h,
       initialElements: r.elements,
-      layoutConfig: a ? { maxHeight: a } : void 0,
+      layoutConfig: o ? { maxHeight: o } : void 0,
       overlay: e,
-      onChange: (l) => i(Z(l), v)
+      onChange: (i) => a(ee(i), u)
     }
   ) });
 }
-function de({
+const ae = 1.2, O = [1200, 1400, 1600, 1800, 2e3, 2500, 3e3, 4e3];
+function oe(e) {
+  for (const n of O)
+    if (n >= e) return n;
+  return O[O.length - 1];
+}
+function ie(e, n) {
+  if (!(e > 0) || !(n > 0) || n <= e * ae) return null;
+  const s = oe(n);
+  return `[RealtimeMockup] mockup rendered at ${e}px but displayed at ~${n} device px — the preview will look soft. Pass \`product.width\` (e.g. ${s}) on <RealtimeEmbed> for a crisp preview.`;
+}
+function pe({
   mockupId: e,
   fallback: n = null,
   alt: s = "Live product mockup",
-  className: a,
-  style: o
+  className: o,
+  style: l
 }) {
-  const { mockups: t } = N(), d = e ? t.find((c) => c.mockupId === e && c.imageUrl) : t.find((c) => c.imageUrl);
-  return d != null && d.imageUrl ? (
+  const { mockups: t } = _(), f = x(/* @__PURE__ */ new Set()), c = e ? t.find((u) => u.mockupId === e && u.imageUrl) : t.find((u) => u.imageUrl);
+  if (!(c != null && c.imageUrl))
+    return /* @__PURE__ */ E(z, { children: n });
+  const h = (u) => {
+    var k;
+    if (typeof b > "u" || ((k = b.env) == null ? void 0 : k.NODE_ENV) === "production" || typeof window > "u" || f.current.has(c.mockupId)) return;
+    const a = u.currentTarget, r = a.getBoundingClientRect().width;
+    if (r <= 0) return;
+    const i = Math.round(r * (window.devicePixelRatio || 1)), w = ie(a.naturalWidth, i);
+    w && (f.current.add(c.mockupId), console.warn(w));
+  };
+  return (
     // eslint-disable-next-line @next/next/no-img-element
-    /* @__PURE__ */ b("img", { src: d.imageUrl, alt: s, className: a, style: o })
-  ) : /* @__PURE__ */ b(J, { children: n });
+    /* @__PURE__ */ E("img", { src: c.imageUrl, alt: s, className: o, style: l, onLoad: h })
+  );
 }
-function ge() {
-  const { mockups: e, isRendering: n, error: s } = N();
+function ve() {
+  const { mockups: e, isRendering: n, error: s } = _();
   return { mockups: e, isRendering: n, error: s };
 }
-z();
+H();
 export {
-  L as CanvasServicesProvider,
+  W as CanvasServicesProvider,
   $e as DesignBuilder,
-  ue as RealtimeCanvas,
-  me as RealtimeEmbed,
-  de as RealtimeMockup,
-  pe as createProxyGenerate,
-  ve as createProxyImageSearch,
-  ke as design,
-  be as useCanvasServices,
-  Se as useElementByName,
-  Ee as useImageBinding,
-  ge as useRealtimeMockups,
-  Re as useTextBinding,
-  ne as validateEmbed
+  he as RealtimeCanvas,
+  ge as RealtimeEmbed,
+  pe as RealtimeMockup,
+  Re as TEMPLATE_FIELDS_KEY,
+  we as createProxyGenerate,
+  ye as createProxyImageSearch,
+  Te as design,
+  Ie as readTemplateFields,
+  Se as useCanvasServices,
+  xe as useColorBinding,
+  Me as useElementByName,
+  Ue as useImageBinding,
+  ve as useRealtimeMockups,
+  Ce as useTextBinding,
+  te as validateEmbed,
+  Ne as withTemplateFields
 };
 //# sourceMappingURL=embed.mjs.map