@snowcone-app/sdk 0.1.14 → 0.1.15

package/README.md

@@ -2,7 +2,11 @@
 
 **JavaScript/TypeScript SDK for product mockups and print-on-demand**
 
-Merch provides a simple SDK for fetching product data and generating real-time merchandise mockups. Use it to visualize artwork on t-shirts, posters, mugs, and more.
+A small, isomorphic SDK for fetching product data and building real-time
+merchandise mockup URLs. Use it to visualize artwork on t-shirts, posters, mugs,
+and more — in the browser or on the server.
+
+📖 **Full documentation: [developers.snowcone.app/sdk](https://developers.snowcone.app/sdk)**
 
 ## Installation
 
@@ -33,9 +37,9 @@ const url = getMockupUrl('hoodie-black', {
 // <img src={url} />
 ```
 
-> The `key` is your **publishable** token — public and safe to expose (like
-> Cloudinary's cloud name). It defaults to your `shop.id`. See the security
-> ladder below if you want to lock things down.
+> The `shop` ID is your **publishable** token — public and safe to expose (like
+> Cloudinary's cloud name). It defaults to your `shop.id`. See [Public or
+> signed](#public-or-signed) below if you want to lock things down.
 
 ## Core Functions
 
@@ -94,7 +98,7 @@ const url = getMockupUrl(productCode: string, opts: {
   asset?: string;         // Single default-placement image (get-started shorthand)
   design?: Design;        // Multi-placement: { [placementKey]: Fill } — takes precedence over `asset`
   options?: Record<string, string>; // Variant picks: { size: "m" } → opt.size=m
-  secret?: string;        // Optional: per-shop secret → appends an L3 &signature (server only)
+  secret?: string;        // Optional: per-shop secret → appends a signed &signature (server only)
   base?: string;          // Optional: override the host (default img.snowcone.app)
   width?: number;         // Optional: display width
   view?: string;          // Optional: camera view / mockup scene (alias: `mockup`)
@@ -140,18 +144,16 @@ const cap = getMockupUrl('RQNU68', {
 > accepted (it builds the same URL as `getMockupUrl(productCode, { asset, … })`).
 > Prefer the code-first form above for new code.
 
-### Security ladder
+### Public or signed
 
-The default is open and frictionless; climb only as far as you need:
+The default is open and frictionless. There's one decision to make up front:
 
-| Level | Control | Effect |
-|---|---|---|
-| **L0** (default) | none | public token, any domain, any asset |
-| **L1** | domain allowlist | token only renders from your domains |
-| **L2** | asset allowlist | restrict which asset sources composite |
-| **L3** | signed URLs | URL must carry a valid `&s` (HMAC of a per-shop secret) |
+- **Public** — the Shop ID alone, safe to expose. Lock it to your **asset
+  origins** so a stolen ID can only re-render your own catalog.
+- **Signed** — your server appends an `&signature` (HMAC of a per-shop secret),
+  so only you can mint valid URLs. The secret stays server-side.
 
-For **L3**, pass `secret` (server-side only) and `getMockupUrl` appends the
+To sign, pass `secret` (server-side only) and `getMockupUrl` appends the
 verified `&signature`:
 
 ```typescript
@@ -163,6 +165,8 @@ const url = getMockupUrl('hoodie-black', {
 });
 ```
 
+See [Public or signed](https://developers.snowcone.app/get-started) for the full picture.
+
 ### React Hooks (Optional)
 
 For React applications, use the React-specific exports:
@@ -211,14 +215,14 @@ See: [@snowcone-app/ui on npm](https://www.npmjs.com/package/@snowcone-app/ui)
 
 ## Examples
 
-- [Next.js Example](https://github.com/snowcone-app/ui-components/tree/main/examples/next-ecommerce)
-- [Basic Product Display](https://github.com/snowcone-app/ui-components/tree/main/examples/next-ecommerce/app/demos)
+- [Getting started](https://developers.snowcone.app/get-started)
+- [Mockup URLs reference](https://developers.snowcone.app/mockups)
+- [Live playground](https://developers.snowcone.app/playground)
 
 ## Support
 
-- **Issues:** [GitHub Issues](https://github.com/snowcone-app/ui-components/issues)
-- **Discussions:** [GitHub Discussions](https://github.com/snowcone-app/ui-components/discussions)
-- **Docs:** [developers.snowcone.app](https://developers.snowcone.app)
+- **Docs:** [developers.snowcone.app/sdk](https://developers.snowcone.app/sdk)
+- **Issues:** [GitHub Issues](https://github.com/snowcone-app/snowcone-monorepo/issues)
 
 ## License
 

package/dist/{chunk-6MV7TDTM.js → chunk-RPA3B6I3.js}

@@ -1,6 +1,9 @@
+// src/realtime/constants.ts
+var REALTIME_WS_URL = "wss://cdn.snowcone.app/realtime";
+
 // src/realtime/websocket.ts
 var RealtimeMockupService = class {
-  constructor(wsUrl = "wss://WS_URL_NOT_CONFIGURED.invalid/realtime") {
+  constructor(wsUrl = REALTIME_WS_URL) {
     this.wsUrl = wsUrl;
   }
   ws = null;
@@ -649,5 +652,6 @@ ${versionToSend}
 };
 
 export {
+  REALTIME_WS_URL,
   RealtimeMockupService
 };

package/dist/index.cjs

@@ -38,6 +38,7 @@ __export(index_exports, {
   DEFAULT_ARTWORK_URL: () => DEFAULT_ARTWORK_URL,
   DEFAULT_ASPECT_RATIO: () => DEFAULT_ASPECT_RATIO,
   DEFAULT_COLOR: () => DEFAULT_COLOR,
+  DEFAULT_GRANT_BASE: () => DEFAULT_GRANT_BASE,
   DEFAULT_MOCKUP_BASE: () => DEFAULT_MOCKUP_BASE,
   DEFAULT_PLACEMENT_DIMENSIONS: () => DEFAULT_PLACEMENT_DIMENSIONS,
   Elements: () => Elements,
@@ -51,7 +52,9 @@ __export(index_exports, {
   ProductLoader: () => ProductLoader,
   ProductProps: () => ProductProps,
   PropertyManager: () => PropertyManager,
+  REALTIME_WS_URL: () => REALTIME_WS_URL,
   RealtimeMockupService: () => RealtimeMockupService,
+  RenderSession: () => RenderSession,
   StandardComponents: () => StandardComponents,
   StandardEvents: () => StandardEvents,
   StateManager: () => StateManager,
@@ -95,6 +98,7 @@ __export(index_exports, {
   describeProductPrice: () => describeProductPrice,
   describeProductTitle: () => describeProductTitle,
   extractProductId: () => extractProductId,
+  fetchRealtimeGrant: () => fetchRealtimeGrant,
   filterImagePlacements: () => filterImagePlacements,
   findBestCombination: () => findBestCombination,
   findClosestSnapPoint: () => findClosestSnapPoint,
@@ -118,6 +122,7 @@ __export(index_exports, {
   isValidAlignment: () => isValidAlignment,
   isValidTileCount: () => isValidTileCount,
   listProducts: () => listProducts,
+  mintRealtimeGrant: () => mintRealtimeGrant,
   mockupUrl: () => mockupUrl,
   normalizeChoice: () => normalizeChoice,
   prepareOptionRenderData: () => prepareOptionRenderData,
@@ -4797,9 +4802,12 @@ function createSvelteComponent(descriptor, svelte) {
   };
 }
 
+// src/realtime/constants.ts
+var REALTIME_WS_URL = "wss://cdn.snowcone.app/realtime";
+
 // src/realtime/websocket.ts
 var RealtimeMockupService = class {
-  constructor(wsUrl = "wss://WS_URL_NOT_CONFIGURED.invalid/realtime") {
+  constructor(wsUrl = REALTIME_WS_URL) {
     this.wsUrl = wsUrl;
   }
   ws = null;
@@ -5447,6 +5455,154 @@ ${versionToSend}
   }
 };
 
+// src/realtime/grant.ts
+var DEFAULT_GRANT_BASE = "https://api.snowcone.app";
+async function mintRealtimeGrant(opts) {
+  const f = opts.fetch ?? globalThis.fetch;
+  const res = await f(`${opts.base ?? DEFAULT_GRANT_BASE}/realtime/grant`, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      Authorization: `Bearer ${opts.apiKey}`
+    },
+    body: JSON.stringify({ shop: opts.shop })
+  });
+  if (!res.ok) {
+    const detail = await res.text().catch(() => "");
+    throw new Error(`realtime grant failed: ${res.status}${detail ? ` ${detail}` : ""}`);
+  }
+  return await res.json();
+}
+async function fetchRealtimeGrant(grantUrl, shop, fetchImpl) {
+  const f = fetchImpl ?? globalThis.fetch;
+  const res = await f(grantUrl, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ shop })
+  });
+  if (!res.ok) throw new Error(`realtime grant failed: ${res.status}`);
+  return await res.json();
+}
+
+// src/realtime/session.ts
+var RenderSession = class {
+  svc;
+  opts;
+  product;
+  mockupCb = null;
+  errorCb = null;
+  ready = null;
+  constructor(opts) {
+    if (!opts.shop) throw new Error("RenderSession: `shop` is required");
+    if (!opts.getToken && !opts.grantUrl) {
+      throw new Error("RenderSession: provide `grantUrl` or `getToken` to authorize the session");
+    }
+    this.opts = opts;
+    this.product = opts.product ?? null;
+    this.svc = new RealtimeMockupService(opts.wsUrl ?? REALTIME_WS_URL);
+    const getToken = opts.getToken ?? (() => fetchRealtimeGrant(opts.grantUrl, opts.shop, opts.fetch));
+    this.svc.setTokenProvider(getToken);
+  }
+  /** Register a callback fired whenever rendered mockup URLs update. */
+  onMockups(cb) {
+    this.mockupCb = cb;
+    return this;
+  }
+  /** Register an error callback (server/transport errors). */
+  onError(cb) {
+    this.errorCb = cb;
+    return this;
+  }
+  /** Set or update the product. Sends config immediately if already connected. */
+  setProduct(product) {
+    this.product = product;
+    this.svc.sendConfig(this.toConfig(product));
+  }
+  /**
+   * Connect, authorize, and configure. Resolves once the session is ready to
+   * accept {@link RenderSession.renderState}. Idempotent.
+   */
+  connect() {
+    if (this.ready) return this.ready;
+    if (!this.product) {
+      return Promise.reject(
+        new Error("RenderSession: set a product (via options.product or setProduct) before connect()")
+      );
+    }
+    const product = this.product;
+    this.ready = new Promise((resolve, reject) => {
+      let settled = false;
+      this.svc.setCallbacks({
+        onConnected: () => {
+          this.svc.sendConfig(this.toConfig(product));
+        },
+        onConfigReceived: () => {
+          if (!settled) {
+            settled = true;
+            resolve();
+          }
+        },
+        onMockupRendered: () => {
+          this.mockupCb?.(this.svc.getState().mockupResults);
+        },
+        onAllMockupsRendered: (results) => {
+          this.mockupCb?.(results);
+        },
+        onError: (error) => {
+          this.errorCb?.(error);
+          if (!settled) {
+            settled = true;
+            reject(new Error(error));
+          }
+        }
+      });
+      this.svc.sendConfig(this.toConfig(product));
+      this.svc.connect();
+    });
+    return this.ready;
+  }
+  /**
+   * Render a canvas state for a placement. The server rasterizes it and fetches
+   * the assets referenced inside — no pixels are uploaded. Results arrive via
+   * {@link RenderSession.onMockups}. Safe to call repeatedly (e.g. on every
+   * canvas edit); pass `throttleMs` to debounce during live dragging.
+   */
+  async renderState(placement, state, throttleMs = 0) {
+    await this.connect();
+    this.svc.sendCanvasState(placement, state, this.product?.mockupIds.length ?? 1, throttleMs);
+  }
+  /** Update only the mockup ids to render (reuses the current state). */
+  updateMockupIds(mockupIds) {
+    if (this.product) this.product = { ...this.product, mockupIds };
+    this.svc.updateMockupIds(mockupIds);
+  }
+  /** Current rendered results. */
+  getMockups() {
+    return this.svc.getState().mockupResults;
+  }
+  /** Close the WebSocket and stop auto-renew. */
+  close() {
+    this.svc.disconnect();
+    this.ready = null;
+  }
+  /** Escape hatch: the underlying low-level service. */
+  get service() {
+    return this.svc;
+  }
+  toConfig(product) {
+    return {
+      productId: product.productId,
+      mockupIds: product.mockupIds,
+      // shop comes from the grant token server-side; sent for completeness.
+      shop: this.opts.shop,
+      // WebSocketConfig requires these; the server treats empty variant as "none".
+      variantId: product.variantId ?? "",
+      width: product.width ?? 1e3,
+      ...product.placementSettings ? { placementSettings: product.placementSettings } : {}
+    };
+  }
+};
+
 // src/index.ts
 function getFetcher(config) {
   return config?.fetcher || globalThis.fetch.bind(globalThis);
@@ -5534,6 +5690,7 @@ function createClient(config) {
   DEFAULT_ARTWORK_URL,
   DEFAULT_ASPECT_RATIO,
   DEFAULT_COLOR,
+  DEFAULT_GRANT_BASE,
   DEFAULT_MOCKUP_BASE,
   DEFAULT_PLACEMENT_DIMENSIONS,
   Elements,
@@ -5547,7 +5704,9 @@ function createClient(config) {
   ProductLoader,
   ProductProps,
   PropertyManager,
+  REALTIME_WS_URL,
   RealtimeMockupService,
+  RenderSession,
   StandardComponents,
   StandardEvents,
   StateManager,
@@ -5591,6 +5750,7 @@ function createClient(config) {
   describeProductPrice,
   describeProductTitle,
   extractProductId,
+  fetchRealtimeGrant,
   filterImagePlacements,
   findBestCombination,
   findClosestSnapPoint,
@@ -5614,6 +5774,7 @@ function createClient(config) {
   isValidAlignment,
   isValidTileCount,
   listProducts,
+  mintRealtimeGrant,
   mockupUrl,
   normalizeChoice,
   prepareOptionRenderData,

package/dist/index.d.cts

@@ -1,7 +1,7 @@
 export { createDevFetcher } from './dev-fetcher.cjs';
 import { PublicDesign, PublicFill, PublicOptions } from '@snowcone-app/mockup-url';
-import { O as OptionAttribute, a as OptionSelection, C as Combination, F as FrameworkAdapter, b as ComponentProps, c as ComponentDescriptor, d as ComponentState, e as ComponentContext, f as ComponentLifecycleHooks, E as EventHandler, g as FrameworkUtilities } from './websocket-Dum3OooZ.cjs';
-export { A as AdapterRegistry, M as MockupResult, P as ProductComponentContext, R as RealtimeMockupCallbacks, h as RealtimeMockupService, i as RealtimeMockupState, j as RenderResult, W as WebSocketConfig, k as WebSocketMessage, l as adapterRegistry, m as computeDisabledChoices, n as createComponent, o as defineComponent, p as deriveDefaultSelection, q as findBestCombination, r as getPricePreview, s as isOptionAvailable, t as resolveBestCombination } from './websocket-Dum3OooZ.cjs';
+import { O as OptionAttribute, a as OptionSelection, C as Combination, F as FrameworkAdapter, b as ComponentProps, c as ComponentDescriptor, d as ComponentState, e as ComponentContext, f as ComponentLifecycleHooks, E as EventHandler, g as FrameworkUtilities, P as PlacementSettings, M as MockupResult, R as RealtimeMockupService } from './websocket-BQH1HYJp.cjs';
+export { A as AdapterRegistry, h as ProductComponentContext, i as RealtimeMockupCallbacks, j as RealtimeMockupState, k as RenderResult, W as WebSocketConfig, l as WebSocketMessage, m as adapterRegistry, n as computeDisabledChoices, o as createComponent, p as defineComponent, q as deriveDefaultSelection, r as findBestCombination, s as getPricePreview, t as isOptionAvailable, u as resolveBestCombination } from './websocket-BQH1HYJp.cjs';
 
 interface CatalogProduct$2 {
     id: string;
@@ -2481,6 +2481,169 @@ declare class SvelteAdapter implements FrameworkAdapter<ComponentProps> {
  */
 declare function createSvelteComponent(descriptor: ComponentDescriptor, svelte: any): any;
 
+/**
+ * Production realtime render WebSocket endpoint (the rendercenter edge).
+ *
+ * This is the value to connect to for server-side canvas rendering — open
+ * `${REALTIME_WS_URL}?token=<grant>`. Replaces the old un-discoverable
+ * `wss://WS_URL_NOT_CONFIGURED.invalid/realtime` placeholder so a 3rd party
+ * can find the endpoint from the package alone (ADR-0079, Phase 2).
+ */
+declare const REALTIME_WS_URL = "wss://cdn.snowcone.app/realtime";
+
+/**
+ * Realtime grant helpers (ADR-0079, Phase 2).
+ *
+ * A realtime render session is authorized by a short-lived (60s) grant token.
+ * There are two ways to obtain one, mirroring Stripe's pk_/sk_ split:
+ *
+ *  - {@link mintRealtimeGrant} — SERVER-SIDE, with a secret API key (sk_).
+ *  - {@link fetchRealtimeGrant} — BROWSER, from your own proxy endpoint.
+ *
+ * The browser then opens `${REALTIME_WS_URL}?token=<token>` (RenderSession does
+ * this for you).
+ */
+/** A short-lived realtime session grant. */
+interface RealtimeGrant {
+    /** Opaque session token to put on the WS URL as `?token=`. */
+    token: string;
+    /** Expiry, epoch seconds. Renew before this (RenderSession auto-renews). */
+    expiresAt: number;
+}
+/** Default backend base URL hosting `POST /realtime/grant`. */
+declare const DEFAULT_GRANT_BASE = "https://api.snowcone.app";
+/**
+ * SERVER-SIDE: mint a realtime grant with a secret API key (sk_). Call this
+ * from YOUR backend — never the browser; the API key must stay secret. The key
+ * needs the `mockups:realtime` (or `mockups`) scope and its organization must
+ * own the target `shop`. Returns a 60s grant your browser code opens the WS
+ * with (hand it down via your own endpoint + {@link fetchRealtimeGrant}).
+ *
+ * @example
+ * // your backend route: POST /api/realtime/grant
+ * const grant = await mintRealtimeGrant({ apiKey: process.env.SNOWCONE_API_KEY!, shop });
+ * return Response.json(grant);
+ */
+declare function mintRealtimeGrant(opts: {
+    /** Secret API key (sk_) with the `mockups:realtime` or `mockups` scope. */
+    apiKey: string;
+    /** Target shop id (= shop.id). Must belong to the key's organization. */
+    shop: string;
+    /** Backend base URL. Defaults to {@link DEFAULT_GRANT_BASE}. */
+    base?: string;
+    /** Override fetch (e.g. in tests / non-global-fetch runtimes). */
+    fetch?: typeof fetch;
+}): Promise<RealtimeGrant>;
+/**
+ * BROWSER: fetch a grant from your own proxy endpoint, which calls
+ * {@link mintRealtimeGrant} server-side (so the secret key never reaches the
+ * browser). The proxy receives `POST { shop }` and returns `{ token, expiresAt }`.
+ * This is the default token provider {@link RenderSession} uses when given a
+ * `grantUrl`.
+ */
+declare function fetchRealtimeGrant(grantUrl: string, shop: string, fetchImpl?: typeof fetch): Promise<RealtimeGrant>;
+
+/**
+ * RenderSession — a high-level facade over {@link RealtimeMockupService} for the
+ * server-side canvas render flow (ADR-0079, Phase 2).
+ *
+ * It hides the connect → grant → config → renew → canvas_state choreography so a
+ * 3rd party can do what the www PDP does in a few calls, without holding the
+ * artwork bytes or rendering each placement client-side:
+ *
+ * @example
+ * const session = new RenderSession({
+ *   shop: 'YOUR_SHOP_ID',
+ *   grantUrl: '/api/realtime/grant', // your proxy → mintRealtimeGrant (server)
+ *   product: { productId: 'BEEB77', mockupIds: ['front'] },
+ * });
+ * session.onMockups((results) => { img.src = results[0].imageUrl; });
+ * await session.connect();
+ * session.renderState('Front', serializeStateForServer(canvasState));
+ *
+ * For the low-level escape hatch, use {@link RealtimeMockupService} directly.
+ */
+
+/**
+ * The server-render canvas state — the JSON produced by `serializeStateForServer()`
+ * in `@snowcone-app/canvas` (its `ServerRenderRequest`). Typed structurally here
+ * so the SDK stays dependency-free; if you have `@snowcone-app/canvas`, its
+ * `ServerRenderRequest` is assignable to this. `schemaVersion` is the wire
+ * contract version (`CANVAS_STATE_SCHEMA_VERSION`); a missing value is treated
+ * as `1` by the renderer.
+ */
+interface RenderState {
+    schemaVersion?: number;
+    artboards?: Array<Record<string, unknown>>;
+    elements?: Array<Record<string, unknown>>;
+    [key: string]: unknown;
+}
+/** Product the session renders against (Snowcone catalog ids). */
+interface RenderProduct {
+    productId: string;
+    mockupIds: string[];
+    /** Optional variant (gvid). Omit if the product has no variant axis. */
+    variantId?: string;
+    /** Render width in px (default 1000). */
+    width?: number;
+    /** Per-placement settings (tiling, scale mode). */
+    placementSettings?: Record<string, PlacementSettings>;
+}
+interface RenderSessionOptions {
+    /** Publishable shop id (= shop.id, like Stripe pk_). */
+    shop: string;
+    /** Product config. Can also be set later via {@link RenderSession.setProduct}. */
+    product?: RenderProduct;
+    /** Realtime WS endpoint. Defaults to {@link REALTIME_WS_URL}. */
+    wsUrl?: string;
+    /**
+     * How to authorize the session. Provide exactly one:
+     *  - `grantUrl`: your endpoint that returns `{ token, expiresAt }` for
+     *    `POST { shop }` (recommended — a same-origin proxy to `mintRealtimeGrant`).
+     *  - `getToken`: full control over fetching the grant.
+     */
+    grantUrl?: string;
+    getToken?: () => Promise<RealtimeGrant>;
+    /** Override fetch (used with `grantUrl`). */
+    fetch?: typeof fetch;
+}
+declare class RenderSession {
+    private readonly svc;
+    private readonly opts;
+    private product;
+    private mockupCb;
+    private errorCb;
+    private ready;
+    constructor(opts: RenderSessionOptions);
+    /** Register a callback fired whenever rendered mockup URLs update. */
+    onMockups(cb: (results: MockupResult[]) => void): this;
+    /** Register an error callback (server/transport errors). */
+    onError(cb: (error: string) => void): this;
+    /** Set or update the product. Sends config immediately if already connected. */
+    setProduct(product: RenderProduct): void;
+    /**
+     * Connect, authorize, and configure. Resolves once the session is ready to
+     * accept {@link RenderSession.renderState}. Idempotent.
+     */
+    connect(): Promise<void>;
+    /**
+     * Render a canvas state for a placement. The server rasterizes it and fetches
+     * the assets referenced inside — no pixels are uploaded. Results arrive via
+     * {@link RenderSession.onMockups}. Safe to call repeatedly (e.g. on every
+     * canvas edit); pass `throttleMs` to debounce during live dragging.
+     */
+    renderState(placement: string, state: RenderState, throttleMs?: number): Promise<void>;
+    /** Update only the mockup ids to render (reuses the current state). */
+    updateMockupIds(mockupIds: string[]): void;
+    /** Current rendered results. */
+    getMockups(): MockupResult[];
+    /** Close the WebSocket and stop auto-renew. */
+    close(): void;
+    /** Escape hatch: the underlying low-level service. */
+    get service(): RealtimeMockupService;
+    private toConfig;
+}
+
 interface ProductPlacement {
     label: string;
     x: number;
@@ -2535,4 +2698,4 @@ declare function getProduct(idOrSlug: string, config?: Partial<SdkConfig>): Prom
  */
 declare function createClient(config: SdkConfig): SnowconeClient;
 
-export { AbstractTemplateRenderer, type AddToCartOptions, Animations, type ArtSelectorContext, type ArtSelectorDescriptor, type ArtSelectorOptions, type ArtworkData, type AspectRatio, Attributes, type BaseDescriptor, type BlendConfig, type BuildMockupUrlConfig, type CartDetail, type CatalogListResponse, type CatalogProduct$2 as CatalogProduct, ClassNames, type ColorDesignElement, ColorPickerUtils, Combination, CommonProps, ComponentContext, type ComponentDefinition, ComponentDescriptor, ComponentEventManager, ComponentFactory, ComponentLifecycle, ComponentLifecycleHooks, type ComponentMetadata, ComponentProps, ComponentRegistry, ComponentState, type ComponentTemplate, ComponentTemplates, type ContainerDescriptor, ContextBridge, type ContextComparator, type ContextConsumer, ContextInjector, type ContextProviderConfig, type ContextSubscriber, ContextSynchronizer, DEFAULT_ARTWORK_URL, DEFAULT_ASPECT_RATIO, DEFAULT_COLOR, DEFAULT_MOCKUP_BASE, DEFAULT_PLACEMENT_DIMENSIONS, type Descriptor, type Design, type DesignElement, type DesignGenerationContext, type Effects, Elements, type ErrorContext, type ErrorHandler, ErrorManager, type EventDefinition, EventDelegator, EventEmitter, EventHandler, type EventListener, type EventPayload, type Fill, Focus, FrameworkAdapter, FrameworkUtilities, type GetMockupUrlOptions, type ImageAlignment, type ImageDesignElement, type LifecycleHook, LifecycleManager, type LifecyclePhase, type LifecycleTransition, LitAdapter, type MaskOverride, type MockupGenerationOptions, type MockupService, type MockupServiceConfig, OptionAttribute, type OptionChoice, type OptionChoiceRenderData, type OptionRenderData, OptionSelection, type Placement, type PlacementDesign, type ProductArtAlignmentContext, type ProductArtAlignmentDescriptor, type ProductArtAlignmentOptions, type ProductContext, type ProductContextEvents, ProductContextManager, type ProductData, type ProductFetcher, type ProductImageDescriptor, type ProductImageOptions, ProductLoader, type ProductMockupData, type ProductOptionChoice, type ProductOptionData, type ProductOptionsDescriptor, type ProductOptionsOptions, type ProductPlacement, type ProductPriceDescriptor, type ProductPriceOptions, ProductProps, type ProductSpec, type ProductTitleDescriptor, type ProductTitleOptions, type ProductVariant, type PropDefinition, type PropSchema, type PropType, PropertyManager, type RateLimitState, type RegularArtwork, type SdkConfig, type SeamlessPattern, type SignedUrlResponse, type SnowconeClient, StandardComponents, StandardEvents, StateManager, type StateManagerOptions, type StateMiddleware, type StateSelector, type StateSubscriber, type StateUpdater, Styles, SvelteAdapter, SwatchUtils, type TagName, TemplateBuilder, type TemplateNode, type TemplateNodeType, type TemplateRenderer, type TextDescriptor, type TileCount, UniversalContextProvider, type UserSelection, type ValidationError, type ValidationResult, VueAdapter, autoRegister, buildMockupUrl, componentRegistry, createAddToCartEvent, createAddToCartHandler, createCartDetail, createClient, createContextProvider, createDesignForPlacements, createErrorHandler, createEventManager, createLifecycle, createLitComponent, createProductContext, createProductLoader, createPropertyManager, createStateHook, createStateStore, createSvelteComponent, createUniversalProvider, createVueComponent, describeArtSelector, describeProductArtAlignment, describeProductImage, describeProductOptions, describeProductPrice, describeProductTitle, extractProductId, filterImagePlacements, findClosestSnapPoint, findVariantForSelection, formatPrice, formatValidationErrors, getDefaultVariantId, getEffectiveAlignment, getIncompleteSelectionMessage, getMissingSelections, getMockupUrl, getOptionRenderType, getProduct, getSelectionDisplayText, getSnapPoints, getVariant, handleOptionChange, isSelectionComplete, isValidAlignment, isValidTileCount, listProducts, mockupUrl, normalizeChoice, prepareOptionRenderData, registerStandardComponents, resolveMockupId, resolveVariantId, retryOperation, simulateCartOperation, toCombinations, toOptionAttributes, useFrameworkAdapter as useVueAdapter, validateAlignment, validateDesignElement, validateEffects, validateImageUrl, validateMockupOptions, validateProductSelection, validateProductSpec, validateRequiredOptions, validateTileCount, withContext, withErrorHandling, withSyncErrorHandling };
+export { AbstractTemplateRenderer, type AddToCartOptions, Animations, type ArtSelectorContext, type ArtSelectorDescriptor, type ArtSelectorOptions, type ArtworkData, type AspectRatio, Attributes, type BaseDescriptor, type BlendConfig, type BuildMockupUrlConfig, type CartDetail, type CatalogListResponse, type CatalogProduct$2 as CatalogProduct, ClassNames, type ColorDesignElement, ColorPickerUtils, Combination, CommonProps, ComponentContext, type ComponentDefinition, ComponentDescriptor, ComponentEventManager, ComponentFactory, ComponentLifecycle, ComponentLifecycleHooks, type ComponentMetadata, ComponentProps, ComponentRegistry, ComponentState, type ComponentTemplate, ComponentTemplates, type ContainerDescriptor, ContextBridge, type ContextComparator, type ContextConsumer, ContextInjector, type ContextProviderConfig, type ContextSubscriber, ContextSynchronizer, DEFAULT_ARTWORK_URL, DEFAULT_ASPECT_RATIO, DEFAULT_COLOR, DEFAULT_GRANT_BASE, DEFAULT_MOCKUP_BASE, DEFAULT_PLACEMENT_DIMENSIONS, type Descriptor, type Design, type DesignElement, type DesignGenerationContext, type Effects, Elements, type ErrorContext, type ErrorHandler, ErrorManager, type EventDefinition, EventDelegator, EventEmitter, EventHandler, type EventListener, type EventPayload, type Fill, Focus, FrameworkAdapter, FrameworkUtilities, type GetMockupUrlOptions, type ImageAlignment, type ImageDesignElement, type LifecycleHook, LifecycleManager, type LifecyclePhase, type LifecycleTransition, LitAdapter, type MaskOverride, type MockupGenerationOptions, MockupResult, type MockupService, type MockupServiceConfig, OptionAttribute, type OptionChoice, type OptionChoiceRenderData, type OptionRenderData, OptionSelection, type Placement, type PlacementDesign, PlacementSettings, type ProductArtAlignmentContext, type ProductArtAlignmentDescriptor, type ProductArtAlignmentOptions, type ProductContext, type ProductContextEvents, ProductContextManager, type ProductData, type ProductFetcher, type ProductImageDescriptor, type ProductImageOptions, ProductLoader, type ProductMockupData, type ProductOptionChoice, type ProductOptionData, type ProductOptionsDescriptor, type ProductOptionsOptions, type ProductPlacement, type ProductPriceDescriptor, type ProductPriceOptions, ProductProps, type ProductSpec, type ProductTitleDescriptor, type ProductTitleOptions, type ProductVariant, type PropDefinition, type PropSchema, type PropType, PropertyManager, REALTIME_WS_URL, type RateLimitState, type RealtimeGrant, RealtimeMockupService, type RegularArtwork, type RenderProduct, RenderSession, type RenderSessionOptions, type RenderState, type SdkConfig, type SeamlessPattern, type SignedUrlResponse, type SnowconeClient, StandardComponents, StandardEvents, StateManager, type StateManagerOptions, type StateMiddleware, type StateSelector, type StateSubscriber, type StateUpdater, Styles, SvelteAdapter, SwatchUtils, type TagName, TemplateBuilder, type TemplateNode, type TemplateNodeType, type TemplateRenderer, type TextDescriptor, type TileCount, UniversalContextProvider, type UserSelection, type ValidationError, type ValidationResult, VueAdapter, autoRegister, buildMockupUrl, componentRegistry, createAddToCartEvent, createAddToCartHandler, createCartDetail, createClient, createContextProvider, createDesignForPlacements, createErrorHandler, createEventManager, createLifecycle, createLitComponent, createProductContext, createProductLoader, createPropertyManager, createStateHook, createStateStore, createSvelteComponent, createUniversalProvider, createVueComponent, describeArtSelector, describeProductArtAlignment, describeProductImage, describeProductOptions, describeProductPrice, describeProductTitle, extractProductId, fetchRealtimeGrant, filterImagePlacements, findClosestSnapPoint, findVariantForSelection, formatPrice, formatValidationErrors, getDefaultVariantId, getEffectiveAlignment, getIncompleteSelectionMessage, getMissingSelections, getMockupUrl, getOptionRenderType, getProduct, getSelectionDisplayText, getSnapPoints, getVariant, handleOptionChange, isSelectionComplete, isValidAlignment, isValidTileCount, listProducts, mintRealtimeGrant, mockupUrl, normalizeChoice, prepareOptionRenderData, registerStandardComponents, resolveMockupId, resolveVariantId, retryOperation, simulateCartOperation, toCombinations, toOptionAttributes, useFrameworkAdapter as useVueAdapter, validateAlignment, validateDesignElement, validateEffects, validateImageUrl, validateMockupOptions, validateProductSelection, validateProductSpec, validateRequiredOptions, validateTileCount, withContext, withErrorHandling, withSyncErrorHandling };

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 export { createDevFetcher } from './dev-fetcher.js';
 import { PublicDesign, PublicFill, PublicOptions } from '@snowcone-app/mockup-url';
-import { O as OptionAttribute, a as OptionSelection, C as Combination, F as FrameworkAdapter, b as ComponentProps, c as ComponentDescriptor, d as ComponentState, e as ComponentContext, f as ComponentLifecycleHooks, E as EventHandler, g as FrameworkUtilities } from './websocket-Dum3OooZ.js';
-export { A as AdapterRegistry, M as MockupResult, P as ProductComponentContext, R as RealtimeMockupCallbacks, h as RealtimeMockupService, i as RealtimeMockupState, j as RenderResult, W as WebSocketConfig, k as WebSocketMessage, l as adapterRegistry, m as computeDisabledChoices, n as createComponent, o as defineComponent, p as deriveDefaultSelection, q as findBestCombination, r as getPricePreview, s as isOptionAvailable, t as resolveBestCombination } from './websocket-Dum3OooZ.js';
+import { O as OptionAttribute, a as OptionSelection, C as Combination, F as FrameworkAdapter, b as ComponentProps, c as ComponentDescriptor, d as ComponentState, e as ComponentContext, f as ComponentLifecycleHooks, E as EventHandler, g as FrameworkUtilities, P as PlacementSettings, M as MockupResult, R as RealtimeMockupService } from './websocket-BQH1HYJp.js';
+export { A as AdapterRegistry, h as ProductComponentContext, i as RealtimeMockupCallbacks, j as RealtimeMockupState, k as RenderResult, W as WebSocketConfig, l as WebSocketMessage, m as adapterRegistry, n as computeDisabledChoices, o as createComponent, p as defineComponent, q as deriveDefaultSelection, r as findBestCombination, s as getPricePreview, t as isOptionAvailable, u as resolveBestCombination } from './websocket-BQH1HYJp.js';
 
 interface CatalogProduct$2 {
     id: string;
@@ -2481,6 +2481,169 @@ declare class SvelteAdapter implements FrameworkAdapter<ComponentProps> {
  */
 declare function createSvelteComponent(descriptor: ComponentDescriptor, svelte: any): any;
 
+/**
+ * Production realtime render WebSocket endpoint (the rendercenter edge).
+ *
+ * This is the value to connect to for server-side canvas rendering — open
+ * `${REALTIME_WS_URL}?token=<grant>`. Replaces the old un-discoverable
+ * `wss://WS_URL_NOT_CONFIGURED.invalid/realtime` placeholder so a 3rd party
+ * can find the endpoint from the package alone (ADR-0079, Phase 2).
+ */
+declare const REALTIME_WS_URL = "wss://cdn.snowcone.app/realtime";
+
+/**
+ * Realtime grant helpers (ADR-0079, Phase 2).
+ *
+ * A realtime render session is authorized by a short-lived (60s) grant token.
+ * There are two ways to obtain one, mirroring Stripe's pk_/sk_ split:
+ *
+ *  - {@link mintRealtimeGrant} — SERVER-SIDE, with a secret API key (sk_).
+ *  - {@link fetchRealtimeGrant} — BROWSER, from your own proxy endpoint.
+ *
+ * The browser then opens `${REALTIME_WS_URL}?token=<token>` (RenderSession does
+ * this for you).
+ */
+/** A short-lived realtime session grant. */
+interface RealtimeGrant {
+    /** Opaque session token to put on the WS URL as `?token=`. */
+    token: string;
+    /** Expiry, epoch seconds. Renew before this (RenderSession auto-renews). */
+    expiresAt: number;
+}
+/** Default backend base URL hosting `POST /realtime/grant`. */
+declare const DEFAULT_GRANT_BASE = "https://api.snowcone.app";
+/**
+ * SERVER-SIDE: mint a realtime grant with a secret API key (sk_). Call this
+ * from YOUR backend — never the browser; the API key must stay secret. The key
+ * needs the `mockups:realtime` (or `mockups`) scope and its organization must
+ * own the target `shop`. Returns a 60s grant your browser code opens the WS
+ * with (hand it down via your own endpoint + {@link fetchRealtimeGrant}).
+ *
+ * @example
+ * // your backend route: POST /api/realtime/grant
+ * const grant = await mintRealtimeGrant({ apiKey: process.env.SNOWCONE_API_KEY!, shop });
+ * return Response.json(grant);
+ */
+declare function mintRealtimeGrant(opts: {
+    /** Secret API key (sk_) with the `mockups:realtime` or `mockups` scope. */
+    apiKey: string;
+    /** Target shop id (= shop.id). Must belong to the key's organization. */
+    shop: string;
+    /** Backend base URL. Defaults to {@link DEFAULT_GRANT_BASE}. */
+    base?: string;
+    /** Override fetch (e.g. in tests / non-global-fetch runtimes). */
+    fetch?: typeof fetch;
+}): Promise<RealtimeGrant>;
+/**
+ * BROWSER: fetch a grant from your own proxy endpoint, which calls
+ * {@link mintRealtimeGrant} server-side (so the secret key never reaches the
+ * browser). The proxy receives `POST { shop }` and returns `{ token, expiresAt }`.
+ * This is the default token provider {@link RenderSession} uses when given a
+ * `grantUrl`.
+ */
+declare function fetchRealtimeGrant(grantUrl: string, shop: string, fetchImpl?: typeof fetch): Promise<RealtimeGrant>;
+
+/**
+ * RenderSession — a high-level facade over {@link RealtimeMockupService} for the
+ * server-side canvas render flow (ADR-0079, Phase 2).
+ *
+ * It hides the connect → grant → config → renew → canvas_state choreography so a
+ * 3rd party can do what the www PDP does in a few calls, without holding the
+ * artwork bytes or rendering each placement client-side:
+ *
+ * @example
+ * const session = new RenderSession({
+ *   shop: 'YOUR_SHOP_ID',
+ *   grantUrl: '/api/realtime/grant', // your proxy → mintRealtimeGrant (server)
+ *   product: { productId: 'BEEB77', mockupIds: ['front'] },
+ * });
+ * session.onMockups((results) => { img.src = results[0].imageUrl; });
+ * await session.connect();
+ * session.renderState('Front', serializeStateForServer(canvasState));
+ *
+ * For the low-level escape hatch, use {@link RealtimeMockupService} directly.
+ */
+
+/**
+ * The server-render canvas state — the JSON produced by `serializeStateForServer()`
+ * in `@snowcone-app/canvas` (its `ServerRenderRequest`). Typed structurally here
+ * so the SDK stays dependency-free; if you have `@snowcone-app/canvas`, its
+ * `ServerRenderRequest` is assignable to this. `schemaVersion` is the wire
+ * contract version (`CANVAS_STATE_SCHEMA_VERSION`); a missing value is treated
+ * as `1` by the renderer.
+ */
+interface RenderState {
+    schemaVersion?: number;
+    artboards?: Array<Record<string, unknown>>;
+    elements?: Array<Record<string, unknown>>;
+    [key: string]: unknown;
+}
+/** Product the session renders against (Snowcone catalog ids). */
+interface RenderProduct {
+    productId: string;
+    mockupIds: string[];
+    /** Optional variant (gvid). Omit if the product has no variant axis. */
+    variantId?: string;
+    /** Render width in px (default 1000). */
+    width?: number;
+    /** Per-placement settings (tiling, scale mode). */
+    placementSettings?: Record<string, PlacementSettings>;
+}
+interface RenderSessionOptions {
+    /** Publishable shop id (= shop.id, like Stripe pk_). */
+    shop: string;
+    /** Product config. Can also be set later via {@link RenderSession.setProduct}. */
+    product?: RenderProduct;
+    /** Realtime WS endpoint. Defaults to {@link REALTIME_WS_URL}. */
+    wsUrl?: string;
+    /**
+     * How to authorize the session. Provide exactly one:
+     *  - `grantUrl`: your endpoint that returns `{ token, expiresAt }` for
+     *    `POST { shop }` (recommended — a same-origin proxy to `mintRealtimeGrant`).
+     *  - `getToken`: full control over fetching the grant.
+     */
+    grantUrl?: string;
+    getToken?: () => Promise<RealtimeGrant>;
+    /** Override fetch (used with `grantUrl`). */
+    fetch?: typeof fetch;
+}
+declare class RenderSession {
+    private readonly svc;
+    private readonly opts;
+    private product;
+    private mockupCb;
+    private errorCb;
+    private ready;
+    constructor(opts: RenderSessionOptions);
+    /** Register a callback fired whenever rendered mockup URLs update. */
+    onMockups(cb: (results: MockupResult[]) => void): this;
+    /** Register an error callback (server/transport errors). */
+    onError(cb: (error: string) => void): this;
+    /** Set or update the product. Sends config immediately if already connected. */
+    setProduct(product: RenderProduct): void;
+    /**
+     * Connect, authorize, and configure. Resolves once the session is ready to
+     * accept {@link RenderSession.renderState}. Idempotent.
+     */
+    connect(): Promise<void>;
+    /**
+     * Render a canvas state for a placement. The server rasterizes it and fetches
+     * the assets referenced inside — no pixels are uploaded. Results arrive via
+     * {@link RenderSession.onMockups}. Safe to call repeatedly (e.g. on every
+     * canvas edit); pass `throttleMs` to debounce during live dragging.
+     */
+    renderState(placement: string, state: RenderState, throttleMs?: number): Promise<void>;
+    /** Update only the mockup ids to render (reuses the current state). */
+    updateMockupIds(mockupIds: string[]): void;
+    /** Current rendered results. */
+    getMockups(): MockupResult[];
+    /** Close the WebSocket and stop auto-renew. */
+    close(): void;
+    /** Escape hatch: the underlying low-level service. */
+    get service(): RealtimeMockupService;
+    private toConfig;
+}
+
 interface ProductPlacement {
     label: string;
     x: number;
@@ -2535,4 +2698,4 @@ declare function getProduct(idOrSlug: string, config?: Partial<SdkConfig>): Prom
  */
 declare function createClient(config: SdkConfig): SnowconeClient;
 
-export { AbstractTemplateRenderer, type AddToCartOptions, Animations, type ArtSelectorContext, type ArtSelectorDescriptor, type ArtSelectorOptions, type ArtworkData, type AspectRatio, Attributes, type BaseDescriptor, type BlendConfig, type BuildMockupUrlConfig, type CartDetail, type CatalogListResponse, type CatalogProduct$2 as CatalogProduct, ClassNames, type ColorDesignElement, ColorPickerUtils, Combination, CommonProps, ComponentContext, type ComponentDefinition, ComponentDescriptor, ComponentEventManager, ComponentFactory, ComponentLifecycle, ComponentLifecycleHooks, type ComponentMetadata, ComponentProps, ComponentRegistry, ComponentState, type ComponentTemplate, ComponentTemplates, type ContainerDescriptor, ContextBridge, type ContextComparator, type ContextConsumer, ContextInjector, type ContextProviderConfig, type ContextSubscriber, ContextSynchronizer, DEFAULT_ARTWORK_URL, DEFAULT_ASPECT_RATIO, DEFAULT_COLOR, DEFAULT_MOCKUP_BASE, DEFAULT_PLACEMENT_DIMENSIONS, type Descriptor, type Design, type DesignElement, type DesignGenerationContext, type Effects, Elements, type ErrorContext, type ErrorHandler, ErrorManager, type EventDefinition, EventDelegator, EventEmitter, EventHandler, type EventListener, type EventPayload, type Fill, Focus, FrameworkAdapter, FrameworkUtilities, type GetMockupUrlOptions, type ImageAlignment, type ImageDesignElement, type LifecycleHook, LifecycleManager, type LifecyclePhase, type LifecycleTransition, LitAdapter, type MaskOverride, type MockupGenerationOptions, type MockupService, type MockupServiceConfig, OptionAttribute, type OptionChoice, type OptionChoiceRenderData, type OptionRenderData, OptionSelection, type Placement, type PlacementDesign, type ProductArtAlignmentContext, type ProductArtAlignmentDescriptor, type ProductArtAlignmentOptions, type ProductContext, type ProductContextEvents, ProductContextManager, type ProductData, type ProductFetcher, type ProductImageDescriptor, type ProductImageOptions, ProductLoader, type ProductMockupData, type ProductOptionChoice, type ProductOptionData, type ProductOptionsDescriptor, type ProductOptionsOptions, type ProductPlacement, type ProductPriceDescriptor, type ProductPriceOptions, ProductProps, type ProductSpec, type ProductTitleDescriptor, type ProductTitleOptions, type ProductVariant, type PropDefinition, type PropSchema, type PropType, PropertyManager, type RateLimitState, type RegularArtwork, type SdkConfig, type SeamlessPattern, type SignedUrlResponse, type SnowconeClient, StandardComponents, StandardEvents, StateManager, type StateManagerOptions, type StateMiddleware, type StateSelector, type StateSubscriber, type StateUpdater, Styles, SvelteAdapter, SwatchUtils, type TagName, TemplateBuilder, type TemplateNode, type TemplateNodeType, type TemplateRenderer, type TextDescriptor, type TileCount, UniversalContextProvider, type UserSelection, type ValidationError, type ValidationResult, VueAdapter, autoRegister, buildMockupUrl, componentRegistry, createAddToCartEvent, createAddToCartHandler, createCartDetail, createClient, createContextProvider, createDesignForPlacements, createErrorHandler, createEventManager, createLifecycle, createLitComponent, createProductContext, createProductLoader, createPropertyManager, createStateHook, createStateStore, createSvelteComponent, createUniversalProvider, createVueComponent, describeArtSelector, describeProductArtAlignment, describeProductImage, describeProductOptions, describeProductPrice, describeProductTitle, extractProductId, filterImagePlacements, findClosestSnapPoint, findVariantForSelection, formatPrice, formatValidationErrors, getDefaultVariantId, getEffectiveAlignment, getIncompleteSelectionMessage, getMissingSelections, getMockupUrl, getOptionRenderType, getProduct, getSelectionDisplayText, getSnapPoints, getVariant, handleOptionChange, isSelectionComplete, isValidAlignment, isValidTileCount, listProducts, mockupUrl, normalizeChoice, prepareOptionRenderData, registerStandardComponents, resolveMockupId, resolveVariantId, retryOperation, simulateCartOperation, toCombinations, toOptionAttributes, useFrameworkAdapter as useVueAdapter, validateAlignment, validateDesignElement, validateEffects, validateImageUrl, validateMockupOptions, validateProductSelection, validateProductSpec, validateRequiredOptions, validateTileCount, withContext, withErrorHandling, withSyncErrorHandling };
+export { AbstractTemplateRenderer, type AddToCartOptions, Animations, type ArtSelectorContext, type ArtSelectorDescriptor, type ArtSelectorOptions, type ArtworkData, type AspectRatio, Attributes, type BaseDescriptor, type BlendConfig, type BuildMockupUrlConfig, type CartDetail, type CatalogListResponse, type CatalogProduct$2 as CatalogProduct, ClassNames, type ColorDesignElement, ColorPickerUtils, Combination, CommonProps, ComponentContext, type ComponentDefinition, ComponentDescriptor, ComponentEventManager, ComponentFactory, ComponentLifecycle, ComponentLifecycleHooks, type ComponentMetadata, ComponentProps, ComponentRegistry, ComponentState, type ComponentTemplate, ComponentTemplates, type ContainerDescriptor, ContextBridge, type ContextComparator, type ContextConsumer, ContextInjector, type ContextProviderConfig, type ContextSubscriber, ContextSynchronizer, DEFAULT_ARTWORK_URL, DEFAULT_ASPECT_RATIO, DEFAULT_COLOR, DEFAULT_GRANT_BASE, DEFAULT_MOCKUP_BASE, DEFAULT_PLACEMENT_DIMENSIONS, type Descriptor, type Design, type DesignElement, type DesignGenerationContext, type Effects, Elements, type ErrorContext, type ErrorHandler, ErrorManager, type EventDefinition, EventDelegator, EventEmitter, EventHandler, type EventListener, type EventPayload, type Fill, Focus, FrameworkAdapter, FrameworkUtilities, type GetMockupUrlOptions, type ImageAlignment, type ImageDesignElement, type LifecycleHook, LifecycleManager, type LifecyclePhase, type LifecycleTransition, LitAdapter, type MaskOverride, type MockupGenerationOptions, MockupResult, type MockupService, type MockupServiceConfig, OptionAttribute, type OptionChoice, type OptionChoiceRenderData, type OptionRenderData, OptionSelection, type Placement, type PlacementDesign, PlacementSettings, type ProductArtAlignmentContext, type ProductArtAlignmentDescriptor, type ProductArtAlignmentOptions, type ProductContext, type ProductContextEvents, ProductContextManager, type ProductData, type ProductFetcher, type ProductImageDescriptor, type ProductImageOptions, ProductLoader, type ProductMockupData, type ProductOptionChoice, type ProductOptionData, type ProductOptionsDescriptor, type ProductOptionsOptions, type ProductPlacement, type ProductPriceDescriptor, type ProductPriceOptions, ProductProps, type ProductSpec, type ProductTitleDescriptor, type ProductTitleOptions, type ProductVariant, type PropDefinition, type PropSchema, type PropType, PropertyManager, REALTIME_WS_URL, type RateLimitState, type RealtimeGrant, RealtimeMockupService, type RegularArtwork, type RenderProduct, RenderSession, type RenderSessionOptions, type RenderState, type SdkConfig, type SeamlessPattern, type SignedUrlResponse, type SnowconeClient, StandardComponents, StandardEvents, StateManager, type StateManagerOptions, type StateMiddleware, type StateSelector, type StateSubscriber, type StateUpdater, Styles, SvelteAdapter, SwatchUtils, type TagName, TemplateBuilder, type TemplateNode, type TemplateNodeType, type TemplateRenderer, type TextDescriptor, type TileCount, UniversalContextProvider, type UserSelection, type ValidationError, type ValidationResult, VueAdapter, autoRegister, buildMockupUrl, componentRegistry, createAddToCartEvent, createAddToCartHandler, createCartDetail, createClient, createContextProvider, createDesignForPlacements, createErrorHandler, createEventManager, createLifecycle, createLitComponent, createProductContext, createProductLoader, createPropertyManager, createStateHook, createStateStore, createSvelteComponent, createUniversalProvider, createVueComponent, describeArtSelector, describeProductArtAlignment, describeProductImage, describeProductOptions, describeProductPrice, describeProductTitle, extractProductId, fetchRealtimeGrant, filterImagePlacements, findClosestSnapPoint, findVariantForSelection, formatPrice, formatValidationErrors, getDefaultVariantId, getEffectiveAlignment, getIncompleteSelectionMessage, getMissingSelections, getMockupUrl, getOptionRenderType, getProduct, getSelectionDisplayText, getSnapPoints, getVariant, handleOptionChange, isSelectionComplete, isValidAlignment, isValidTileCount, listProducts, mintRealtimeGrant, mockupUrl, normalizeChoice, prepareOptionRenderData, registerStandardComponents, resolveMockupId, resolveVariantId, retryOperation, simulateCartOperation, toCombinations, toOptionAttributes, useFrameworkAdapter as useVueAdapter, validateAlignment, validateDesignElement, validateEffects, validateImageUrl, validateMockupOptions, validateProductSelection, validateProductSpec, validateRequiredOptions, validateTileCount, withContext, withErrorHandling, withSyncErrorHandling };

package/dist/index.js

@@ -2,8 +2,9 @@ import {
   createDevFetcher
 } from "./chunk-7VO4EL2V.js";
 import {
+  REALTIME_WS_URL,
   RealtimeMockupService
-} from "./chunk-6MV7TDTM.js";
+} from "./chunk-RPA3B6I3.js";
 
 // src/validation.ts
 import { z } from "zod";
@@ -4648,6 +4649,154 @@ function createSvelteComponent(descriptor, svelte) {
   };
 }
 
+// src/realtime/grant.ts
+var DEFAULT_GRANT_BASE = "https://api.snowcone.app";
+async function mintRealtimeGrant(opts) {
+  const f = opts.fetch ?? globalThis.fetch;
+  const res = await f(`${opts.base ?? DEFAULT_GRANT_BASE}/realtime/grant`, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      Authorization: `Bearer ${opts.apiKey}`
+    },
+    body: JSON.stringify({ shop: opts.shop })
+  });
+  if (!res.ok) {
+    const detail = await res.text().catch(() => "");
+    throw new Error(`realtime grant failed: ${res.status}${detail ? ` ${detail}` : ""}`);
+  }
+  return await res.json();
+}
+async function fetchRealtimeGrant(grantUrl, shop, fetchImpl) {
+  const f = fetchImpl ?? globalThis.fetch;
+  const res = await f(grantUrl, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ shop })
+  });
+  if (!res.ok) throw new Error(`realtime grant failed: ${res.status}`);
+  return await res.json();
+}
+
+// src/realtime/session.ts
+var RenderSession = class {
+  svc;
+  opts;
+  product;
+  mockupCb = null;
+  errorCb = null;
+  ready = null;
+  constructor(opts) {
+    if (!opts.shop) throw new Error("RenderSession: `shop` is required");
+    if (!opts.getToken && !opts.grantUrl) {
+      throw new Error("RenderSession: provide `grantUrl` or `getToken` to authorize the session");
+    }
+    this.opts = opts;
+    this.product = opts.product ?? null;
+    this.svc = new RealtimeMockupService(opts.wsUrl ?? REALTIME_WS_URL);
+    const getToken = opts.getToken ?? (() => fetchRealtimeGrant(opts.grantUrl, opts.shop, opts.fetch));
+    this.svc.setTokenProvider(getToken);
+  }
+  /** Register a callback fired whenever rendered mockup URLs update. */
+  onMockups(cb) {
+    this.mockupCb = cb;
+    return this;
+  }
+  /** Register an error callback (server/transport errors). */
+  onError(cb) {
+    this.errorCb = cb;
+    return this;
+  }
+  /** Set or update the product. Sends config immediately if already connected. */
+  setProduct(product) {
+    this.product = product;
+    this.svc.sendConfig(this.toConfig(product));
+  }
+  /**
+   * Connect, authorize, and configure. Resolves once the session is ready to
+   * accept {@link RenderSession.renderState}. Idempotent.
+   */
+  connect() {
+    if (this.ready) return this.ready;
+    if (!this.product) {
+      return Promise.reject(
+        new Error("RenderSession: set a product (via options.product or setProduct) before connect()")
+      );
+    }
+    const product = this.product;
+    this.ready = new Promise((resolve, reject) => {
+      let settled = false;
+      this.svc.setCallbacks({
+        onConnected: () => {
+          this.svc.sendConfig(this.toConfig(product));
+        },
+        onConfigReceived: () => {
+          if (!settled) {
+            settled = true;
+            resolve();
+          }
+        },
+        onMockupRendered: () => {
+          this.mockupCb?.(this.svc.getState().mockupResults);
+        },
+        onAllMockupsRendered: (results) => {
+          this.mockupCb?.(results);
+        },
+        onError: (error) => {
+          this.errorCb?.(error);
+          if (!settled) {
+            settled = true;
+            reject(new Error(error));
+          }
+        }
+      });
+      this.svc.sendConfig(this.toConfig(product));
+      this.svc.connect();
+    });
+    return this.ready;
+  }
+  /**
+   * Render a canvas state for a placement. The server rasterizes it and fetches
+   * the assets referenced inside — no pixels are uploaded. Results arrive via
+   * {@link RenderSession.onMockups}. Safe to call repeatedly (e.g. on every
+   * canvas edit); pass `throttleMs` to debounce during live dragging.
+   */
+  async renderState(placement, state, throttleMs = 0) {
+    await this.connect();
+    this.svc.sendCanvasState(placement, state, this.product?.mockupIds.length ?? 1, throttleMs);
+  }
+  /** Update only the mockup ids to render (reuses the current state). */
+  updateMockupIds(mockupIds) {
+    if (this.product) this.product = { ...this.product, mockupIds };
+    this.svc.updateMockupIds(mockupIds);
+  }
+  /** Current rendered results. */
+  getMockups() {
+    return this.svc.getState().mockupResults;
+  }
+  /** Close the WebSocket and stop auto-renew. */
+  close() {
+    this.svc.disconnect();
+    this.ready = null;
+  }
+  /** Escape hatch: the underlying low-level service. */
+  get service() {
+    return this.svc;
+  }
+  toConfig(product) {
+    return {
+      productId: product.productId,
+      mockupIds: product.mockupIds,
+      // shop comes from the grant token server-side; sent for completeness.
+      shop: this.opts.shop,
+      // WebSocketConfig requires these; the server treats empty variant as "none".
+      variantId: product.variantId ?? "",
+      width: product.width ?? 1e3,
+      ...product.placementSettings ? { placementSettings: product.placementSettings } : {}
+    };
+  }
+};
+
 // src/index.ts
 function getFetcher(config) {
   return config?.fetcher || globalThis.fetch.bind(globalThis);
@@ -4734,6 +4883,7 @@ export {
   DEFAULT_ARTWORK_URL,
   DEFAULT_ASPECT_RATIO,
   DEFAULT_COLOR,
+  DEFAULT_GRANT_BASE,
   DEFAULT_MOCKUP_BASE,
   DEFAULT_PLACEMENT_DIMENSIONS,
   Elements,
@@ -4747,7 +4897,9 @@ export {
   ProductLoader,
   ProductProps,
   PropertyManager,
+  REALTIME_WS_URL,
   RealtimeMockupService,
+  RenderSession,
   StandardComponents,
   StandardEvents,
   StateManager,
@@ -4791,6 +4943,7 @@ export {
   describeProductPrice,
   describeProductTitle,
   extractProductId,
+  fetchRealtimeGrant,
   filterImagePlacements,
   findBestCombination,
   findClosestSnapPoint,
@@ -4814,6 +4967,7 @@ export {
   isValidAlignment,
   isValidTileCount,
   listProducts,
+  mintRealtimeGrant,
   mockupUrl,
   normalizeChoice,
   prepareOptionRenderData,

package/dist/react.cjs

@@ -30,9 +30,12 @@ module.exports = __toCommonJS(react_exports);
 // src/realtime/react.ts
 var import_react = require("react");
 
+// src/realtime/constants.ts
+var REALTIME_WS_URL = "wss://cdn.snowcone.app/realtime";
+
 // src/realtime/websocket.ts
 var RealtimeMockupService = class {
-  constructor(wsUrl = "wss://WS_URL_NOT_CONFIGURED.invalid/realtime") {
+  constructor(wsUrl = REALTIME_WS_URL) {
     this.wsUrl = wsUrl;
   }
   ws = null;

package/dist/react.d.cts

@@ -1,4 +1,4 @@
-import { M as MockupResult, W as WebSocketConfig, u as PlacementSettings, F as FrameworkAdapter, b as ComponentProps, d as ComponentState, e as ComponentContext, f as ComponentLifecycleHooks, E as EventHandler, c as ComponentDescriptor, g as FrameworkUtilities } from './websocket-Dum3OooZ.cjs';
+import { M as MockupResult, W as WebSocketConfig, P as PlacementSettings, F as FrameworkAdapter, b as ComponentProps, d as ComponentState, e as ComponentContext, f as ComponentLifecycleHooks, E as EventHandler, c as ComponentDescriptor, g as FrameworkUtilities } from './websocket-BQH1HYJp.cjs';
 
 interface UseRealtimeMockupOptions {
     wsUrl?: string;

package/dist/react.d.ts

@@ -1,4 +1,4 @@
-import { M as MockupResult, W as WebSocketConfig, u as PlacementSettings, F as FrameworkAdapter, b as ComponentProps, d as ComponentState, e as ComponentContext, f as ComponentLifecycleHooks, E as EventHandler, c as ComponentDescriptor, g as FrameworkUtilities } from './websocket-Dum3OooZ.js';
+import { M as MockupResult, W as WebSocketConfig, P as PlacementSettings, F as FrameworkAdapter, b as ComponentProps, d as ComponentState, e as ComponentContext, f as ComponentLifecycleHooks, E as EventHandler, c as ComponentDescriptor, g as FrameworkUtilities } from './websocket-BQH1HYJp.js';
 
 interface UseRealtimeMockupOptions {
     wsUrl?: string;

package/dist/react.js

@@ -1,6 +1,6 @@
 import {
   RealtimeMockupService
-} from "./chunk-6MV7TDTM.js";
+} from "./chunk-RPA3B6I3.js";
 
 // src/realtime/react.ts
 import { useCallback, useEffect, useRef, useState } from "react";

package/dist/{websocket-Dum3OooZ.d.cts → websocket-BQH1HYJp.d.cts}

@@ -385,4 +385,4 @@ declare class RealtimeMockupService {
     clearMockups(): void;
 }
 
-export { AdapterRegistry as A, type Combination as C, type EventHandler as E, type FrameworkAdapter as F, type MockupResult as M, type OptionAttribute as O, type ProductComponentContext as P, type RealtimeMockupCallbacks as R, type WebSocketConfig as W, type OptionSelection as a, type ComponentProps as b, type ComponentDescriptor as c, type ComponentState as d, type ComponentContext as e, type ComponentLifecycleHooks as f, type FrameworkUtilities as g, RealtimeMockupService as h, type RealtimeMockupState as i, type RenderResult as j, type WebSocketMessage as k, adapterRegistry as l, computeDisabledChoices as m, createComponent as n, defineComponent as o, deriveDefaultSelection as p, findBestCombination as q, getPricePreview as r, isOptionAvailable as s, resolveBestCombination as t, type PlacementSettings as u };
+export { AdapterRegistry as A, type Combination as C, type EventHandler as E, type FrameworkAdapter as F, type MockupResult as M, type OptionAttribute as O, type PlacementSettings as P, RealtimeMockupService as R, type WebSocketConfig as W, type OptionSelection as a, type ComponentProps as b, type ComponentDescriptor as c, type ComponentState as d, type ComponentContext as e, type ComponentLifecycleHooks as f, type FrameworkUtilities as g, type ProductComponentContext as h, type RealtimeMockupCallbacks as i, type RealtimeMockupState as j, type RenderResult as k, type WebSocketMessage as l, adapterRegistry as m, computeDisabledChoices as n, createComponent as o, defineComponent as p, deriveDefaultSelection as q, findBestCombination as r, getPricePreview as s, isOptionAvailable as t, resolveBestCombination as u };

package/dist/{websocket-Dum3OooZ.d.ts → websocket-BQH1HYJp.d.ts}

@@ -385,4 +385,4 @@ declare class RealtimeMockupService {
     clearMockups(): void;
 }
 
-export { AdapterRegistry as A, type Combination as C, type EventHandler as E, type FrameworkAdapter as F, type MockupResult as M, type OptionAttribute as O, type ProductComponentContext as P, type RealtimeMockupCallbacks as R, type WebSocketConfig as W, type OptionSelection as a, type ComponentProps as b, type ComponentDescriptor as c, type ComponentState as d, type ComponentContext as e, type ComponentLifecycleHooks as f, type FrameworkUtilities as g, RealtimeMockupService as h, type RealtimeMockupState as i, type RenderResult as j, type WebSocketMessage as k, adapterRegistry as l, computeDisabledChoices as m, createComponent as n, defineComponent as o, deriveDefaultSelection as p, findBestCombination as q, getPricePreview as r, isOptionAvailable as s, resolveBestCombination as t, type PlacementSettings as u };
+export { AdapterRegistry as A, type Combination as C, type EventHandler as E, type FrameworkAdapter as F, type MockupResult as M, type OptionAttribute as O, type PlacementSettings as P, RealtimeMockupService as R, type WebSocketConfig as W, type OptionSelection as a, type ComponentProps as b, type ComponentDescriptor as c, type ComponentState as d, type ComponentContext as e, type ComponentLifecycleHooks as f, type FrameworkUtilities as g, type ProductComponentContext as h, type RealtimeMockupCallbacks as i, type RealtimeMockupState as j, type RenderResult as k, type WebSocketMessage as l, adapterRegistry as m, computeDisabledChoices as n, createComponent as o, defineComponent as p, deriveDefaultSelection as q, findBestCombination as r, getPricePreview as s, isOptionAvailable as t, resolveBestCombination as u };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@snowcone-app/sdk",
-  "version": "0.1.14",
-  "description": "Merch Javascript SDK for product mockups and print-on-demand",
+  "version": "0.1.15",
+  "description": "Snowcone SDK for product mockups and print-on-demand",
   "keywords": [
     "merch",
     "mockup",
@@ -14,10 +14,13 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/snowcone-app/ui-components.git",
+    "url": "https://github.com/snowcone-app/snowcone-monorepo.git",
     "directory": "packages/sdk"
   },
-  "homepage": "https://snowcone.app",
+  "bugs": {
+    "url": "https://github.com/snowcone-app/snowcone-monorepo/issues"
+  },
+  "homepage": "https://developers.snowcone.app/sdk",
   "private": false,
   "type": "module",
   "main": "dist/index.cjs",