@snowcone-app/sdk 0.1.14 → 0.2.0

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-Poy8LZNA.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-Poy8LZNA.cjs';
 
 interface CatalogProduct$2 {
     id: string;
@@ -16,7 +16,6 @@ interface CatalogProduct$2 {
     highestPrice?: number;
     mockups?: {
         id: string;
-        ar: number;
         gvids: string[];
     }[];
     options?: {
@@ -2481,6 +2480,236 @@ 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;
+    /**
+     * The mockup scenes to render — opaque catalog codes (the product's
+     * `mockups[].id`, e.g. `'FV1qjO'`). These are a DIFFERENT namespace from the
+     * `placement` you pass to {@link RenderSession.renderState} (a print-area name
+     * like `'Front'`). Don't pass a placement name here.
+     */
+    mockupIds: string[];
+    /**
+     * Optional variant (gvid). Omit if the product has no variant axis. Required
+     * for products with a color option — it auto-fills the color placement; without
+     * it the render waits for a color blob that never comes.
+     */
+    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.
+     *
+     * `placement` is the print-area NAME (e.g. `'Front'`, the product's
+     * `placements[].label`) — a different id from the product's `mockupIds`, and it
+     * must match an artboard in `state`. The server renders only once it has a state
+     * for EVERY required placement, so on a multi-placement product call this once
+     * per placement; a missing one surfaces as an `incomplete_canvas_placements`
+     * error on {@link RenderSession.onError}.
+     *
+     * `state` is the flattened `serializeStateForServer()` shape — NOT the
+     * un-flattened shape `createDesignState` takes.
+     */
+    renderState(placement: string, state: RenderState, throttleMs?: number): Promise<void>;
+    /**
+     * Render a SAVED canvas by reference (ADR-0079 Phase 4). The server resolves
+     * the `stateId`, fetches the referenced assets, and renders — no pixels are
+     * uploaded and you don't need to hold the canvas JSON. Ideal for re-rendering
+     * a stored design (fulfillment, agents, server-to-server). Results arrive via
+     * {@link RenderSession.onMockups}.
+     */
+    renderSavedState(placement: string, stateId: string): 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 CreateDesignStateInput {
+    /** Catalog product code the design targets. */
+    productId: string;
+    /**
+     * The canvas state to persist — the **raw, un-flattened** stored shape:
+     * top-level `elements` with `transformType` + nested `transformData`, plus
+     * bare `artboards` metadata. The server flattens this at render time
+     * (`normalizeCanvasState`).
+     *
+     * ⚠️ This is NOT the `serializeStateForServer()` output you pass to
+     * `RenderSession.renderState` — that shape is already flattened and will
+     * mis-render if stored here. Persist the raw canvas state (e.g. `toJSON()`
+     * from the editor), not the server-render payload.
+     */
+    state: RenderState | Record<string, unknown>;
+    /**
+     * Preview thumbnail as a base64 PNG/JPEG (no data: prefix). Optional —
+     * defaults to a 1×1 transparent PNG, which is fine for render-only use.
+     */
+    previewBase64?: string;
+    /** Backend base URL. Defaults to {@link DEFAULT_GRANT_BASE}. */
+    base?: string;
+    /** Override fetch (tests / non-global-fetch runtimes). */
+    fetch?: typeof fetch;
+}
+interface CreatedDesignState {
+    /** The id to pass to `renderSavedState(placement, stateId)`. */
+    stateId: string;
+    /** Content-addressed URL of the persisted state JSON. */
+    stateUrl: string;
+    /** Content-addressed URL of the preview image. */
+    previewUrl: string;
+}
+/**
+ * Persist a canvas state and return its `stateId` (+ URLs). Pair with
+ * `RenderSession.renderSavedState(placement, stateId)`.
+ */
+declare function createDesignState(input: CreateDesignStateInput): Promise<CreatedDesignState>;
+
 interface ProductPlacement {
     label: string;
     x: number;
@@ -2535,4 +2764,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, type CreateDesignStateInput, type CreatedDesignState, 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, createDesignState, 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-Poy8LZNA.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-Poy8LZNA.js';
 
 interface CatalogProduct$2 {
     id: string;
@@ -16,7 +16,6 @@ interface CatalogProduct$2 {
     highestPrice?: number;
     mockups?: {
         id: string;
-        ar: number;
         gvids: string[];
     }[];
     options?: {
@@ -2481,6 +2480,236 @@ 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;
+    /**
+     * The mockup scenes to render — opaque catalog codes (the product's
+     * `mockups[].id`, e.g. `'FV1qjO'`). These are a DIFFERENT namespace from the
+     * `placement` you pass to {@link RenderSession.renderState} (a print-area name
+     * like `'Front'`). Don't pass a placement name here.
+     */
+    mockupIds: string[];
+    /**
+     * Optional variant (gvid). Omit if the product has no variant axis. Required
+     * for products with a color option — it auto-fills the color placement; without
+     * it the render waits for a color blob that never comes.
+     */
+    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.
+     *
+     * `placement` is the print-area NAME (e.g. `'Front'`, the product's
+     * `placements[].label`) — a different id from the product's `mockupIds`, and it
+     * must match an artboard in `state`. The server renders only once it has a state
+     * for EVERY required placement, so on a multi-placement product call this once
+     * per placement; a missing one surfaces as an `incomplete_canvas_placements`
+     * error on {@link RenderSession.onError}.
+     *
+     * `state` is the flattened `serializeStateForServer()` shape — NOT the
+     * un-flattened shape `createDesignState` takes.
+     */
+    renderState(placement: string, state: RenderState, throttleMs?: number): Promise<void>;
+    /**
+     * Render a SAVED canvas by reference (ADR-0079 Phase 4). The server resolves
+     * the `stateId`, fetches the referenced assets, and renders — no pixels are
+     * uploaded and you don't need to hold the canvas JSON. Ideal for re-rendering
+     * a stored design (fulfillment, agents, server-to-server). Results arrive via
+     * {@link RenderSession.onMockups}.
+     */
+    renderSavedState(placement: string, stateId: string): 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 CreateDesignStateInput {
+    /** Catalog product code the design targets. */
+    productId: string;
+    /**
+     * The canvas state to persist — the **raw, un-flattened** stored shape:
+     * top-level `elements` with `transformType` + nested `transformData`, plus
+     * bare `artboards` metadata. The server flattens this at render time
+     * (`normalizeCanvasState`).
+     *
+     * ⚠️ This is NOT the `serializeStateForServer()` output you pass to
+     * `RenderSession.renderState` — that shape is already flattened and will
+     * mis-render if stored here. Persist the raw canvas state (e.g. `toJSON()`
+     * from the editor), not the server-render payload.
+     */
+    state: RenderState | Record<string, unknown>;
+    /**
+     * Preview thumbnail as a base64 PNG/JPEG (no data: prefix). Optional —
+     * defaults to a 1×1 transparent PNG, which is fine for render-only use.
+     */
+    previewBase64?: string;
+    /** Backend base URL. Defaults to {@link DEFAULT_GRANT_BASE}. */
+    base?: string;
+    /** Override fetch (tests / non-global-fetch runtimes). */
+    fetch?: typeof fetch;
+}
+interface CreatedDesignState {
+    /** The id to pass to `renderSavedState(placement, stateId)`. */
+    stateId: string;
+    /** Content-addressed URL of the persisted state JSON. */
+    stateUrl: string;
+    /** Content-addressed URL of the preview image. */
+    previewUrl: string;
+}
+/**
+ * Persist a canvas state and return its `stateId` (+ URLs). Pair with
+ * `RenderSession.renderSavedState(placement, stateId)`.
+ */
+declare function createDesignState(input: CreateDesignStateInput): Promise<CreatedDesignState>;
+
 interface ProductPlacement {
     label: string;
     x: number;
@@ -2535,4 +2764,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, type CreateDesignStateInput, type CreatedDesignState, 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, createDesignState, 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 };