@snowcone-app/canvas 0.11.0 → 0.12.0

package/dist/advanced.mjs

@@ -1,11 +1,11 @@
-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";
-import { A as br, B as yr, I as vr, P as wr, R as Sr, S as Cr, T as Tr, h as Er, a as $r, b as kr, i as Ar, d as Fr, e as Pr, f as Nr, j as Rr, k as Br, l as Mr, m as Dr, n as zr, o as Ir, p as Or, q as Lr, s as Wr, t as Kr, v as _r, w as Gr, x as Ur } from "./HybridHistoryManager-DANuzx7G.js";
-import { I as me } from "./ImportManager-NCtkY5Z0.js";
-import { i as Jr, a as qr, b as Vr, c as Xr, d as Yr } from "./ImportManager-NCtkY5Z0.js";
+import { D as te, I as q, r as re, v as ne, i as oe, e as ae } from "./validation-BpmNOvuY.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-BpmNOvuY.js";
+import { u as V } from "./ThemeContext-Cl1JPVLZ.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-Cl1JPVLZ.js";
+import { c as se, G as ie, F as le, g as ce, r as de, u as ue } from "./HybridHistoryManager-NL3zyEl4.js";
+import { A as br, B as yr, I as vr, P as wr, R as Sr, S as Cr, T as Tr, h as Er, a as $r, b as kr, i as Ar, d as Fr, e as Pr, f as Nr, j as Rr, k as Br, l as Mr, m as Dr, n as zr, o as Ir, p as Or, q as Lr, s as Wr, t as Kr, v as _r, w as Gr, x as Ur } from "./HybridHistoryManager-NL3zyEl4.js";
+import { I as me } from "./ImportManager-eotl7r5d.js";
+import { i as Jr, a as qr, b as Vr, c as Xr, d as Yr } from "./ImportManager-eotl7r5d.js";
 import { useState as A, useCallback as y, useEffect as X, useMemo as Y, useRef as B, memo as fe } from "react";
 import { jsxs as b, jsx as s, Fragment as he } from "react/jsx-runtime";
 import { Tooltip as M, TooltipTrigger as D, Button as pe, TooltipContent as z, Popover as ge, PopoverTrigger as xe, PopoverContent as be } from "@snowcone-app/ui";

package/dist/api/embed.d.ts

@@ -50,9 +50,11 @@ 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 { useFontBinding } from '../hooks/useFontBinding.js';
+export type { FontBindingResult } from '../hooks/useFontBinding.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 type { TemplateField, TemplateTextField, TemplateImageField, TemplateColorField, TemplateSelectField, } 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

@@ -32,6 +32,8 @@ 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 { useFontBinding } from '../hooks/useFontBinding.js';
+export type { FontBindingResult } from '../hooks/useFontBinding.js';
 export { useElementByName } from '../hooks/useElementByName.js';
 export { useContentReady } from '../hooks/useContentReady.js';
 export type { UseContentReadyOptions } from '../hooks/useContentReady.js';
@@ -51,5 +53,5 @@ 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 { TemplateField, TemplateTextField, TemplateImageField, TemplateColorField, TemplateSelectField, } from '../design/template-fields.js';
 export type { CanvasStateV1, SerializedArtboard, SerializedElement, DeserializeResult, ValidationResult, } from '../state/index.js';

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/components/embed-realtime/context.d.ts

@@ -1,5 +1,6 @@
 import { RenderSession, RenderProduct, RenderState, MockupResult } from '@snowcone-app/sdk';
 import { DesignBuilder } from '../../design/design-builder.js';
+import { PieceGuidesConfig } from '../embed/SnowconeCanvas.js';
 export interface EmbedContextValue {
     /** The single session the editor pushes renders to. `null` if the session
      *  failed to construct (a config fail-fast, surfaced via `error`). Escape
@@ -21,6 +22,14 @@ export interface EmbedContextValue {
     error: string | null;
     /** Default edit→render throttle (ms). */
     throttleMs: number;
+    /**
+     * The product's printable-area guides (dead zones, safe areas) — fetched by
+     * `<RealtimeEmbed>` and already gated on the design's artboard matching the
+     * print-file frame they were authored in. `null` when the product has none,
+     * the fetch failed, or the dims don't line up. `<RealtimeCanvas>` forwards
+     * this to the editor so embedders get the same overlay snowcone.app shows.
+     */
+    pieceGuides: PieceGuidesConfig | null;
     /** Dispatch a server render for the embed's placement. Sets `isRendering`. */
     pushRender: (state: RenderState, throttleMs?: number) => void;
 }

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

@@ -0,0 +1,48 @@
+import { PieceGuidesConfig } from '../embed/SnowconeCanvas.js';
+import { PieceGuide, PieceGuideRendererStyle } from '../../rendering/PieceGuideRenderer.js';
+/** Backend base hosting `GET /printables/by-gvid/:gvid/piece-guides`. */
+export declare const PIECE_GUIDES_API_BASE = "https://api.snowcone.app";
+/** Wire shape of the piece-guides endpoint (the consumer-safe subset). */
+interface RawPieceGuidesResponse {
+    artboardWidth: number;
+    artboardHeight: number;
+    /** Inches→px conversion factor for `safeAreaInsetInches`. */
+    templateDpi: number;
+    pieces: Array<{
+        id: string;
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+        rotation?: number;
+        safeAreaInsetInches?: number;
+    }>;
+    pieceGuides?: Record<string, PieceGuide>;
+    pieceGuidesStyle?: PieceGuideRendererStyle;
+}
+/** A fetched bundle: the overlay config plus the artboard frame it was authored in. */
+export interface PieceGuideBundle {
+    /** The print-file frame the piece coords live in. */
+    artboardWidth: number;
+    artboardHeight: number;
+    config: PieceGuidesConfig;
+}
+/** Convert the wire response into a renderer-ready bundle (inches → px, etc.). */
+export declare function transformPieceGuides(raw: RawPieceGuidesResponse): PieceGuideBundle;
+/**
+ * Gate the bundle on the design's artboard matching the print-file frame the
+ * guides were authored in — the same gate snowcone.app's editor applies. A
+ * design authored at other dims would render the overlay misaligned, so it's
+ * skipped (with a dev hint, since the fix — author at the placement's dims —
+ * is on the embedder's side).
+ */
+export declare function pieceGuidesForArtboard(bundle: PieceGuideBundle, artboard: {
+    width: number;
+    height: number;
+} | undefined): PieceGuidesConfig | undefined;
+/**
+ * Fetch the piece-guide bundle for a variant (gvid). Returns null while
+ * loading, when `gvid` is undefined, and on any error (silent degrade).
+ */
+export declare function usePieceGuideBundle(gvid: string | undefined, apiBase?: string): PieceGuideBundle | null;
+export {};

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

@@ -8,6 +8,14 @@ export interface TemplateTextField {
     label: string;
     /** Placeholder text for the input. */
     placeholder?: string;
+    /**
+     * Designer's length limit for the buyer's text — long names overflow fixed
+     * layouts. Intent, not enforcement: your control applies it (an input's
+     * `maxLength`); the canvas itself doesn't truncate.
+     */
+    maxLength?: number;
+    /** Optional grouping label — consecutive fields sharing a group render together. */
+    group?: string;
 }
 /** A buyer-swappable image slot, bound to elements by their `name` property. */
 export interface TemplateImageField {
@@ -20,6 +28,8 @@ export interface TemplateImageField {
     placeholder?: string;
     /** How the buyer's image fits the original element bounds. Default: "cover". */
     fit?: ImageFitMode;
+    /** Optional grouping label — consecutive fields sharing a group render together. */
+    group?: string;
 }
 /** A buyer-editable color, matched by value across all elements that use it. */
 export interface TemplateColorField {
@@ -28,9 +38,37 @@ export interface TemplateColorField {
     color: string;
     /** Label shown to the buyer (e.g. "Accent color"). */
     label: string;
+    /** Optional grouping label — consecutive fields sharing a group render together. */
+    group?: string;
+}
+/**
+ * A pick-one choice over designer-authored options — "one of these 3 badges",
+ * a curated font list, preset text variants. Binds to elements by `name` and
+ * swaps ONE property on them, chosen by `property`:
+ *
+ * - `'text'`       → apply via `useTextBinding(name).setText(value)`
+ * - `'imageUrl'`   → apply via `useImageBinding(name).setImageUrl(value)`
+ * - `'fontFamily'` → apply via `useFontBinding(name).setFontFamily(value)`
+ *   (values must be Google Fonts families)
+ */
+export interface TemplateSelectField {
+    type: 'select';
+    /** Element name (matches canvas layer `name` property). */
+    name: string;
+    /** Label shown to the buyer (e.g. "Badge"). */
+    label: string;
+    /** Which property of the bound element(s) the chosen value sets. */
+    property: 'text' | 'imageUrl' | 'fontFamily';
+    /** The designer-authored choices, in display order. */
+    options: Array<{
+        label: string;
+        value: string;
+    }>;
+    /** Optional grouping label — consecutive fields sharing a group render together. */
+    group?: string;
 }
 /** One buyer-editable aspect of a template. */
-export type TemplateField = TemplateTextField | TemplateImageField | TemplateColorField;
+export type TemplateField = TemplateTextField | TemplateImageField | TemplateColorField | TemplateSelectField;
 /**
  * The key template fields are stored under on the state document.
  * Kept as `personalization` for compatibility with designs saved on snowcone.app.

package/dist/embed.mjs

@@ -1,189 +1,270 @@
-import { a as K, e as z } from "./validation-C857Ptxn.js";
-import { b as pe, d as ve, f as be } from "./validation-C857Ptxn.js";
-import { y as T } from "./HybridHistoryManager-DANuzx7G.js";
-import { jsx as b, Fragment as J } from "react/jsx-runtime";
-import { createContext as W, useContext as H, useMemo as E, useRef as C, useState as q, useEffect as M } from "react";
-import { assertVariantSelected as Y, RenderSession as Q } from "@snowcone-app/sdk";
-import { S as X, s as Z } from "./template-fields-C8Tj67ek.js";
-import { D as Ee, T as $e, d as Se, r as ke, a as Re, e as Te, f as we, g as xe, w as Ie } from "./template-fields-C8Tj67ek.js";
-const V = W(void 0);
-function B() {
-  const e = H(V);
+import { a as z, e as J } from "./validation-BpmNOvuY.js";
+import { b as Re, d as Te, f as xe } from "./validation-BpmNOvuY.js";
+import { y } from "./HybridHistoryManager-NL3zyEl4.js";
+import { jsx as $, Fragment as Y } from "react/jsx-runtime";
+import { createContext as Q, useContext as X, useState as x, useEffect as U, useMemo as I, useRef as M } from "react";
+import { assertVariantSelected as Z, RenderSession as ee } from "@snowcone-app/sdk";
+import { S as te, s as ne } from "./template-fields-IgDV7PRY.js";
+import { D as Me, T as Ae, d as Ce, r as Ge, a as Ne, e as Be, f as Pe, g as _e, h as Oe, w as qe } from "./template-fields-IgDV7PRY.js";
+const L = Q(void 0);
+function P() {
+  const e = X(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, i;
-  if ((a = e == null ? void 0 : e.requiredPlacements) != null && a.length)
-    return e.requiredPlacements.filter((t) => !t.autoFilledByVariant).map((t) => t.label);
-  const n = new Set(
-    (((i = e == null ? void 0 : e.options) == null ? void 0 : i.combinations) ?? []).map((t) => t.variantId).filter((t) => typeof t == "string" && t !== "")
+const re = "https://api.snowcone.app";
+function se(e) {
+  const t = e.pieces.map((n) => ({
+    id: n.id,
+    x: n.x,
+    y: n.y,
+    width: n.width,
+    height: n.height,
+    rotation: typeof n.rotation == "number" ? n.rotation : void 0,
+    safeAreaInsetPx: typeof n.safeAreaInsetInches == "number" && n.safeAreaInsetInches > 0 ? n.safeAreaInsetInches * e.templateDpi : void 0
+  }));
+  return {
+    artboardWidth: e.artboardWidth,
+    artboardHeight: e.artboardHeight,
+    config: {
+      pieces: t,
+      guides: e.pieceGuides ?? {},
+      style: e.pieceGuidesStyle
+    }
+  };
+}
+function ie(e, t) {
+  var n;
+  if (t) {
+    if (t.width !== e.artboardWidth || t.height !== e.artboardHeight) {
+      typeof y < "u" && ((n = y.env) == null ? void 0 : n.NODE_ENV) !== "production" && console.warn(
+        `[RealtimeEmbed] This product has printable-area guides (authored at ${e.artboardWidth}×${e.artboardHeight}), but the design's artboard is ${t.width}×${t.height} — the dead-zone overlay is skipped because the coordinates wouldn't line up. Author the design at the placement's dimensions to get it.`
+      );
+      return;
+    }
+    return e.config;
+  }
+}
+function oe(e, t = re) {
+  const [n, s] = x(null);
+  return U(() => {
+    if (!e) {
+      s(null);
+      return;
+    }
+    let i = !1;
+    return fetch(`${t}/printables/by-gvid/${encodeURIComponent(e)}/piece-guides`).then(async (r) => {
+      if (!r.ok) throw new Error(`status ${r.status}`);
+      return await r.json();
+    }).then((r) => {
+      i || s(se(r));
+    }).catch(() => {
+      i || s(null);
+    }), () => {
+      i = !0;
+    };
+  }, [e, t]), n;
+}
+const E = "[RealtimeEmbed]";
+function ae(e) {
+  var s, i;
+  if ((s = e == null ? void 0 : e.requiredPlacements) != null && s.length)
+    return e.requiredPlacements.filter((r) => !r.autoFilledByVariant).map((r) => r.label);
+  const t = new Set(
+    (((i = e == null ? void 0 : e.options) == null ? void 0 : i.combinations) ?? []).map((r) => r.variantId).filter((r) => typeof r == "string" && r !== "")
   );
-  return !!(e != null && e.variantId) || n.size > 1 ? [] : (e == null ? void 0 : e.placements) ?? [];
+  return !!(e != null && e.variantId) || t.size > 1 ? [] : (e == null ? void 0 : e.placements) ?? [];
 }
-function ne({ shop: e, product: n, design: s, hasGrant: a }) {
-  var v, o;
-  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"].`
-  ), n != null && n.options)
+function ce({ shop: e, product: t, design: n, hasGrant: s }) {
+  var l, a;
+  if (e || console.error(`${E} \`shop\` is required (your publishable shop id).`), s || console.error(
+    `${E} no grant source — pass \`grantUrl\` (a proxy to mintRealtimeGrant) or \`grant\`. Without it the session can never authorize and no mockup renders.`
+  ), (l = t == null ? void 0 : t.mockupIds) != null && l.length || console.error(
+    `${E} product.mockupIds is empty — pass the catalog scene codes (product.mockups[].id) you want rendered, e.g. ["FV1qjO"].`
+  ), t != null && t.options)
     try {
-      Y(n);
-    } catch (r) {
-      console.error(`${p} ${r instanceof Error ? r.message : String(r)}`);
+      Z(t);
+    } catch (o) {
+      console.error(`${E} ${o instanceof Error ? o.message : String(o)}`);
     }
-  const i = s.toJSON(), t = i.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.`
-  ), (o = n == null ? void 0 : n.placements) != null && o.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 i = n.toJSON(), r = i.activeArtboard, h = ae(t);
+  h.length > 1 && console.error(
+    `${E} product ${t.productId} requires placements [${h.join(", ")}] but <RealtimeEmbed> renders a single placement ("${r}"). The render will time out waiting for the others. This product needs the eject path — see https://developers.snowcone.app/embed-mode#eject.`
+  ), (a = t == null ? void 0 : t.placements) != null && a.length && !t.placements.includes(r) && console.warn(
+    `${E} the design's placement "${r}" is not in product.placements [${t.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 = i.elements.map((r) => r.name).filter((r) => !!r), h = c.filter((r, l) => c.indexOf(r) !== l);
-  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.`
+  const c = i.elements.map((o) => o.name).filter((o) => !!o), g = c.filter((o, p) => c.indexOf(o) !== p);
+  g.length && console.warn(
+    `${E} duplicate layer name(s) [${[...new Set(g)].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 ue(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 t = e.grant;
+  return typeof t == "function" ? { getToken: t } : { getToken: () => Promise.resolve(t) };
 }
-const _ = 8e3;
-function re(e) {
-  return `[RealtimeEmbed] No mockup after ${Math.round(_ / 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 le(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: i = 200, onMockups: t, onRenderError: d, wsUrl: c, services: h, children: v } = e, o = E(() => a.toJSON().activeArtboard, [a]), r = C(t), l = C(d);
-  r.current = t, l.current = d;
-  const [N, D] = q([]), [$, y] = q(!0), [j, S] = q(null), w = !!("grantUrl" in e && e.grantUrl || "grant" in e && e.grant), x = te(e), L = "grantUrl" in x ? x.grantUrl : "getToken", I = `${s.productId}|${s.mockupIds.join(",")}|${s.variantId ?? ""}`, k = E(
+function Ee(e) {
+  const { shop: t, product: n, design: s, throttleMs: i = 200, onMockups: r, onRenderError: h, wsUrl: c, services: g, children: l } = e, a = I(() => s.toJSON().activeArtboard, [s]), o = oe(n.variantId ?? n.defaultGvid), p = I(() => {
+    if (!o) return null;
+    const u = s.toJSON().artboards[0];
+    return ie(o, u) ?? null;
+  }, [o, s]), v = M(r), d = M(h);
+  v.current = r, d.current = h;
+  const [_, W] = x([]), [S, w] = x(!0), [O, k] = x(null), A = !!("grantUrl" in e && e.grantUrl || "grant" in e && e.grant), C = ue(e), H = "grantUrl" in C ? C.grantUrl : "getToken", G = `${n.productId}|${n.mockupIds.join(",")}|${n.variantId ?? ""}`, R = I(
     () => {
       try {
-        return { session: new Q({ shop: n, product: s, wsUrl: c, ...x }) };
-      } catch (m) {
-        return { error: m instanceof Error ? m.message : String(m) };
+        return { session: new ee({ shop: t, product: n, wsUrl: c, ...C }) };
+      } catch (u) {
+        return { error: u instanceof Error ? u.message : String(u) };
       }
     },
     // eslint-disable-next-line react-hooks/exhaustive-deps
-    [n, I, o, c, L]
-  ), g = "session" in k ? k.session : null, R = "error" in k ? k.error : null, P = C(null);
-  M(() => {
-    var m;
-    if (typeof T < "u" && ((m = T.env) == null ? void 0 : m.NODE_ENV) !== "production") {
-      const u = `${n}|${I}|${o}|${w}`;
-      if (P.current === u) return;
-      P.current = u, ne({ shop: n, product: s, design: a, hasGrant: w });
+    [t, G, a, c, H]
+  ), f = "session" in R ? R.session : null, T = "error" in R ? R.error : null, q = M(null);
+  U(() => {
+    var u;
+    if (typeof y < "u" && ((u = y.env) == null ? void 0 : u.NODE_ENV) !== "production") {
+      const m = `${t}|${G}|${a}|${A}`;
+      if (q.current === m) return;
+      q.current = m, ce({ shop: t, product: n, design: s, hasGrant: A });
     }
-  }, [n, I, o, w]);
-  const U = E(() => (m, u = i) => {
-    g && (S(null), y(!0), g.renderState(o, m, u).catch((f) => {
-      var A;
-      const O = f instanceof Error ? f.message : String(f);
-      S(O), y(!1), (A = l.current) == null || A.call(l, O);
+  }, [t, G, a, A]);
+  const N = I(() => (u, m = i) => {
+    f && (k(null), w(!0), f.renderState(a, u, m).catch((b) => {
+      var F;
+      const j = b instanceof Error ? b.message : String(b);
+      k(j), w(!1), (F = d.current) == null || F.call(d, j);
     }));
-  }, [g, o, i]);
-  M(() => {
-    var m;
-    if (R) {
-      S(R), y(!1), (m = l.current) == null || m.call(l, R);
+  }, [f, a, i]);
+  U(() => {
+    var u;
+    if (T) {
+      k(T), w(!1), (u = d.current) == null || u.call(d, T);
       return;
     }
-    if (g)
-      return g.onMockups((u) => {
-        var f;
-        D(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);
-      }), U(a.toServerRequest()), () => g.close();
-  }, [g, R]), M(() => {
-    var u;
-    if (!$ || typeof T > "u" || ((u = T.env) == null ? void 0 : u.NODE_ENV) === "production") return;
-    const m = setTimeout(() => console.warn(re(o)), _);
-    return () => clearTimeout(m);
-  }, [$, o]);
-  const G = E(
+    if (f)
+      return f.onMockups((m) => {
+        var b;
+        W(m), w(!1), (b = v.current) == null || b.call(v, m);
+      }), f.onError((m) => {
+        var b;
+        k(m), w(!1), (b = d.current) == null || b.call(d, m);
+      }), N(s.toServerRequest()), () => f.close();
+  }, [f, T]), U(() => {
+    var m;
+    if (!S || typeof y > "u" || ((m = y.env) == null ? void 0 : m.NODE_ENV) === "production") return;
+    const u = setTimeout(() => console.warn(le(a)), V);
+    return () => clearTimeout(u);
+  }, [S, a]);
+  const K = I(
     () => ({
-      session: g,
-      design: a,
-      placement: o,
-      product: s,
-      mockups: N,
-      isRendering: $,
-      error: j,
+      session: f,
+      design: s,
+      placement: a,
+      product: n,
+      mockups: _,
+      isRendering: S,
+      error: O,
       throttleMs: i,
-      pushRender: U
+      pieceGuides: p,
+      pushRender: N
     }),
-    [g, a, o, s, N, $, j, i, U]
-  ), F = /* @__PURE__ */ b(V.Provider, { value: G, children: v });
-  return h ? /* @__PURE__ */ b(K, { services: h, children: F }) : F;
+    [f, s, a, n, _, S, O, i, p, N]
+  ), D = /* @__PURE__ */ $(L.Provider, { value: K, children: l });
+  return g ? /* @__PURE__ */ $(z, { services: g, children: D }) : D;
 }
-function ue({
+function Ie({
   children: e,
-  kit: n = "embed-only",
-  inheritTheme: s = !0,
-  maxHeight: a,
+  kit: t = "embed-only",
+  inheritTheme: n = !0,
+  maxHeight: s,
   services: i,
-  className: t,
-  style: d
+  className: r,
+  style: h
 }) {
-  const { design: c, placement: h, throttleMs: v, pushRender: o } = B(), r = E(() => c.toJSON(), [c]);
-  return /* @__PURE__ */ b("div", { className: `app-modern${t ? ` ${t}` : ""}`, style: d, children: /* @__PURE__ */ b(
-    X,
+  const { design: c, placement: g, throttleMs: l, pieceGuides: a, pushRender: o } = P(), p = I(() => c.toJSON(), [c]);
+  return /* @__PURE__ */ $("div", { className: `app-modern${r ? ` ${r}` : ""}`, style: h, children: /* @__PURE__ */ $(
+    te,
     {
-      kit: n,
-      inheritTheme: s,
+      kit: t,
+      inheritTheme: n,
       services: i,
-      artboards: r.artboards,
-      activeArtboard: h,
-      initialElements: r.elements,
-      layoutConfig: a ? { maxHeight: a } : void 0,
+      artboards: p.artboards,
+      activeArtboard: g,
+      initialElements: p.elements,
+      layoutConfig: s ? { maxHeight: s } : void 0,
       overlay: e,
-      onChange: (l) => o(Z(l), v)
+      pieceGuides: a ?? void 0,
+      onChange: (v) => o(ne(v), l)
     }
   ) });
 }
-function de({
+const de = 1.2, B = [1200, 1400, 1600, 1800, 2e3, 2500, 3e3, 4e3];
+function me(e) {
+  for (const t of B)
+    if (t >= e) return t;
+  return B[B.length - 1];
+}
+function he(e, t) {
+  if (!(e > 0) || !(t > 0) || t <= e * de) return null;
+  const n = me(t);
+  return `[RealtimeMockup] mockup rendered at ${e}px but displayed at ~${t} device px — the preview will look soft. Pass \`product.width\` (e.g. ${n}) on <RealtimeEmbed> for a crisp preview.`;
+}
+function $e({
   mockupId: e,
-  fallback: n = null,
-  alt: s = "Live product mockup",
-  className: a,
+  fallback: t = null,
+  alt: n = "Live product mockup",
+  className: s,
   style: i
 }) {
-  const { mockups: t } = B(), d = e ? t.find((c) => c.mockupId === e && c.imageUrl) : t.find((c) => c.imageUrl);
-  return d != null && d.imageUrl ? (
+  const { mockups: r } = P(), h = M(/* @__PURE__ */ new Set()), c = e ? r.find((l) => l.mockupId === e && l.imageUrl) : r.find((l) => l.imageUrl);
+  if (!(c != null && c.imageUrl))
+    return /* @__PURE__ */ $(Y, { children: t });
+  const g = (l) => {
+    var d;
+    if (typeof y > "u" || ((d = y.env) == null ? void 0 : d.NODE_ENV) === "production" || typeof window > "u" || h.current.has(c.mockupId)) return;
+    const a = l.currentTarget, o = a.getBoundingClientRect().width;
+    if (o <= 0) return;
+    const p = Math.round(o * (window.devicePixelRatio || 1)), v = he(a.naturalWidth, p);
+    v && (h.current.add(c.mockupId), console.warn(v));
+  };
+  return (
     // eslint-disable-next-line @next/next/no-img-element
-    /* @__PURE__ */ b("img", { src: d.imageUrl, alt: s, className: a, style: i })
-  ) : /* @__PURE__ */ b(J, { children: n });
+    /* @__PURE__ */ $("img", { src: c.imageUrl, alt: n, className: s, style: i, onLoad: g })
+  );
 }
-function ge() {
-  const { mockups: e, isRendering: n, error: s } = B();
-  return { mockups: e, isRendering: n, error: s };
+function we() {
+  const { mockups: e, isRendering: t, error: n } = P();
+  return { mockups: e, isRendering: t, error: n };
 }
-z();
+J();
 export {
-  K as CanvasServicesProvider,
-  Ee as DesignBuilder,
-  ue as RealtimeCanvas,
-  me as RealtimeEmbed,
-  de as RealtimeMockup,
-  $e as TEMPLATE_FIELDS_KEY,
-  pe as createProxyGenerate,
-  ve as createProxyImageSearch,
-  Se as design,
-  ke as readTemplateFields,
-  be as useCanvasServices,
-  Re as useColorBinding,
-  Te as useElementByName,
-  we as useImageBinding,
-  ge as useRealtimeMockups,
-  xe as useTextBinding,
-  ne as validateEmbed,
-  Ie as withTemplateFields
+  z as CanvasServicesProvider,
+  Me as DesignBuilder,
+  Ie as RealtimeCanvas,
+  Ee as RealtimeEmbed,
+  $e as RealtimeMockup,
+  Ae as TEMPLATE_FIELDS_KEY,
+  Re as createProxyGenerate,
+  Te as createProxyImageSearch,
+  Ce as design,
+  Ge as readTemplateFields,
+  xe as useCanvasServices,
+  Ne as useColorBinding,
+  Be as useElementByName,
+  Pe as useFontBinding,
+  _e as useImageBinding,
+  we as useRealtimeMockups,
+  Oe as useTextBinding,
+  ce as validateEmbed,
+  qe as withTemplateFields
 };
 //# sourceMappingURL=embed.mjs.map