Realtime rendering

// YOUR backend — e.g. a Next.js route handler at POST /api/realtime/grant.
// The secret API key (sk_…) never reaches the browser.
import { mintRealtimeGrant } from '@snowcone-app/sdk';

export async function POST(req: Request) {
  const { shop } = await req.json();
  const grant = await mintRealtimeGrant({
    apiKey: process.env.SNOWCONE_API_KEY!, // sk_… with the mockups:realtime scope
    shop,                                  // = shop.id (publishable, like Stripe pk_)
  });
  return Response.json(grant); // { token, expiresAt } — 60s, auto-renewed client-side
}

// SANDBOX path — no API key. The publishable shop.id alone authorizes the
// grant; the SDK omits the Authorization header when you pass no apiKey
// (shipped in @snowcone-app/sdk — the keyless publishable grant path).
// NOTE: the scsec_… "shop secret" from POST /shops/sandbox is for SIGNING
// image URLs — it is NOT an sk_ key and does NOT go here.
import { mintRealtimeGrant } from '@snowcone-app/sdk';

export async function POST(req: Request) {
  const { shop } = await req.json();
  const grant = await mintRealtimeGrant({ shop }); // shop.id only — no apiKey
  return Response.json(grant); // { token, expiresAt }
}

// SIGNED rung — drop-in. @snowcone-app/sdk/server signs the grant request
// with your scsec_… shop secret server-side, so you never compute the HMAC by
// hand. Same POST { shop } → { token, expiresAt } contract as the mints above.
import { createRealtimeGrantHandler } from '@snowcone-app/sdk/server';

export const POST = createRealtimeGrantHandler({
  secret: process.env.SNOWCONE_SHOP_SECRET!, // scsec_… (server-only)
  shop: process.env.SNOWCONE_SHOP_ID!,       // = shop.id
  // gate: async (req) => isLoggedIn(req), // optional auth / rate-limit
});

import { RenderSession } from '@snowcone-app/sdk';
import { design } from '@snowcone-app/canvas';

const session = new RenderSession({
  shop: 'YOUR_SHOP_ID',            // publishable
  grantUrl: '/api/realtime/grant', // your proxy → mintRealtimeGrant (above)
  // mockupIds are catalog scene codes (product.mockups[].id), NOT placement names.
  product: { productId: 'BC43BE', mockupIds: ['yoALRE'] }, // iPhone 17 Pro Max Case
});
session.onMockups((results) => { img.src = results[0].imageUrl; });
session.onError((message: string) => console.error('render error:', message));

// Compose by INTENT — never raw coordinates. A full-bleed background can't land
// in a corner; anchored text/shapes place themselves. The artboard size is the
// placement's pixel dimensions (from getProduct(productId).placements[]).
const d = design({ name: 'Front', width: 1480, height: 2328 })
  .background('https://dqMwU8Jct3.storage.snowcone.app/demo/sunset.avif', {
    aspectRatio: 1480 / 2328,      // fills the case, centre-cropped — no distortion
  })
  .text('YOUR NAME', { anchor: 'top' })
  .shape('star', { anchor: 'bottom-left', fill: '#000' });

// renderDesign(placement, design, throttleMs?) ==
//   renderState(placement, design.toServerRequest(), throttleMs).
// No hand-built canvas_state, no centre-coordinate math.
await session.renderDesign('Front', d, 200);

import { RenderSession, getProduct } from '@snowcone-app/sdk';
import { serializeStateForServer } from '@snowcone-app/canvas';

const product = await getProduct('BEEB77');
const mockupId = product.mockups?.[0]?.id ?? 'FV1qjO';
const variantId = product.options?.combinations?.find((c) => c.variantId)?.variantId;

const session = new RenderSession({
  shop: 'YOUR_SHOP_ID',            // publishable
  grantUrl: '/api/realtime/grant', // your proxy → mintRealtimeGrant (above)
  // mockupIds are opaque catalog scene codes (the product's mockups[].id) —
  // NOT placement names. (BEEB77 = Framed Canvas; FV1qjO is one of its mockups.)
  // variantId is REQUIRED for any product with a color/variant option. Read it
  // from the live catalog and pass options so the SDK can validate immediately.
  product: { productId: product.id, mockupIds: [mockupId], variantId, options: product.options },
});

// Rendered mockup URLs arrive here — repaint your <img> on every update.
session.onMockups((results) => { img.src = results[0].imageUrl; });
// onError receives a STRING message (not an Error object).
session.onError((message: string) => console.error('render error:', message));

// First arg is the PLACEMENT (print-area name, e.g. 'Front') — a different id
// from mockupIds, and it must match an artboard in the state. Read the exact
// label from getProduct('BEEB77').placements[].label. The server fetches the
// artwork referenced inside; you never upload a pixel. Safe on every edit.
await session.renderState('Front', serializeStateForServer(canvasState), 200);

// app/api/realtime/grant/route.ts — your same-origin grant proxy.
// Sandbox path: the publishable shop.id alone authorizes the grant, so
// mintRealtimeGrant takes NO apiKey (apiKey is optional: apiKey?: string | null).
import { mintRealtimeGrant } from '@snowcone-app/sdk';

export async function POST(req: Request) {
  const { shop } = await req.json();
  const grant = await mintRealtimeGrant({ shop }); // no apiKey → keyless sandbox
  return Response.json(grant); // { token, expiresAt }
}

// app/page.tsx — a thin Client Component entry that lazy-loads the
// browser-only editor. It must be a Client Component: next/dynamic with
// { ssr: false } is not allowed in a Server Component (Next 15/16 throws
// "ssr: false is not allowed with next/dynamic in Server Components").
// (Importing PURE helpers like serializeStateForServer from
// @snowcone-app/canvas is still server-safe — only the interactive
// <SnowconeCanvas/> editor must stay client-side.)
'use client';
import dynamic from 'next/dynamic';

const Editor = dynamic(() => import('./Editor'), { ssr: false });

export default function Page() {
  return <Editor />;
}

// app/Editor.tsx — the client editor wired to a RenderSession.
'use client';
import { useEffect, useMemo, useState } from 'react';
import { SnowconeCanvas, serializeStateForServer, type AnyElementConfig } from '@snowcone-app/canvas';
import { RenderSession } from '@snowcone-app/sdk';
import '@snowcone-app/canvas/style.css';

// A CORS-clean placeholder hosted on a Snowcone demo shop bucket.
const SEED_ASSET = 'https://dqMwU8Jct3.storage.snowcone.app/demo/demo-008.jpg';
const ARTBOARD = { name: 'Front', width: 1200, height: 1200 };
const INITIAL_ELEMENTS: AnyElementConfig[] = [{
  id: 'headline',
  transformType: 'custom',
  name: 'headline',
  text: 'SNOWCONE',
  x: 600,
  y: 360,
  fontSize: 96,
  fontFamily: 'Arial',
  color: '#111111',
  textAlign: 'center',
  bold: true,
}];

export default function Editor() {
  const [mockup, setMockup] = useState<string>();
  const session = useMemo(() => {
    const s = new RenderSession({
      shop: 'YOUR_SHOP_ID',            // your publishable shop.id
      grantUrl: '/api/realtime/grant', // the proxy above
      // BEEB77 has a Frame color option → variantId is REQUIRED. In a complete
      // PDP, read this from getProduct('BEEB77').options.combinations[].
      product: { productId: 'BEEB77', mockupIds: ['FV1qjO'], variantId: 'Pv1sLC' },
    });
    s.onMockups((r) => setMockup(r[0]?.imageUrl));
    s.onError((message: string) => console.error('render error:', message));
    return s;
  }, []);

  useEffect(() => {
    // PDPs need a mockup before the shopper edits. Do this explicitly instead
    // of waiting for SnowconeCanvas.onChange to fire.
    void session.renderState('Front', serializeStateForServer({
      artboards: [ARTBOARD],
      elements: INITIAL_ELEMENTS,
    }));
    // Tear the session down on unmount so the WebSocket is closed and the
    // grant-renewal timer stops. The teardown method is close() — NOT
    // disconnect().
    return () => session.close();
  }, [session]);

  return (
    // No wrapper class needed — the canvas scopes its own styles.
    <>
      <SnowconeCanvas
        // artboard name === placement === catalog placements[].label ('Front').
        artboards={[ARTBOARD]}
        initialElements={INITIAL_ELEMENTS}
        // A Snowcone-hosted, CORS-clean seed asset (your-shop bucket origins are
        // CORS-enabled by default). Swap for your own shop bucket art.
        imageConfig={{ src: SEED_ASSET, scaleMode: 'contain' }}
        // renderState connects lazily on first call — no explicit connect() needed.
        onChange={(state) =>
          session.renderState('Front', serializeStateForServer(state), 200)
        }
      />
      {mockup && <img src={mockup} alt="live mockup" />}
    </>
  );
}

import { RenderSession } from '@snowcone-app/sdk';
import { serializeStateForServer } from '@snowcone-app/canvas';

// A multi-placement product. The Cotton Women's Tee (KMYKUK) has FIVE print
// areas — its catalog placements[].label values: 'Front', 'Back', 'Left sleeve',
// 'Right sleeve', 'Collar' — and one mockup scene (mockups[].id = '3jnLNX').
// Read them from getProduct('KMYKUK'): placements[].label (and the renderer's
// own contract, requiredPlacements[].label) are the EXACT strings to pass.
const session = new RenderSession({
  shop: 'YOUR_SHOP_ID',
  grantUrl: '/api/realtime/grant',
  product: {
    productId: 'KMYKUK',
    mockupIds: ['3jnLNX'],
    // KMYKUK has a Size variant — pass the variantId for the chosen variant so
    // the renderer auto-fills that variant's color/placement geometry. Omit a
    // required variantId on a color/variant product and the SDK fails fast.
    variantId: 'qsFaIZ', // the 'S' Size variant (from options.combinations[].variantId)
  },
});
session.onMockups((results) => { img.src = results[0].imageUrl; });

// THE PER-PLACEMENT MODEL: call renderState ONCE PER required placement. The
// server holds them and renders only once it has a state for EVERY placement
// the product requires — a missing one surfaces as an
// incomplete_canvas_placements error on onError. Each placement arg must equal
// an artboard.name in that placement's state AND the catalog placements[].label.
await session.renderState('Front', serializeStateForServer(frontState));
await session.renderState('Back', serializeStateForServer(backState));
await session.renderState('Left sleeve', serializeStateForServer(leftState));
await session.renderState('Right sleeve', serializeStateForServer(rightState));
await session.renderState('Collar', serializeStateForServer(collarState));

'use client';
import { RenderSession } from '@snowcone-app/sdk';
import { SnowconeCanvas, serializeStateForServer } from '@snowcone-app/canvas';

// FROM A LIVE EDITOR: one multi-artboard <SnowconeCanvas> hosts every print
// area (artboard name === catalog placements[].label), and onChange's
// CanvasState tags each element with the artboard it lives on
// (element.artboard). serializeStateForServer therefore emits EVERY artboard,
// each holding its own elements — slice it per placement instead of
// hand-authoring frontState/backState:
const session = new RenderSession({
  shop: 'YOUR_SHOP_ID',
  grantUrl: '/api/realtime/grant',
  product: { productId: 'KMYKUK', mockupIds: ['3jnLNX'], variantId: 'qsFaIZ' },
});
session.onMockups((results) => { img.src = results[0].imageUrl; });

export function Customizer() {
  return (
    <SnowconeCanvas
      // One artboard per required placement — labels/sizes from
      // getProduct('KMYKUK').placements[].
      artboards={[
        { name: 'Front', width: 1713, height: 2318 },
        { name: 'Back', width: 1713, height: 2367 },
        { name: 'Left sleeve', width: 1359, height: 803 },
        { name: 'Right sleeve', width: 1359, height: 803 },
        { name: 'Collar', width: 600, height: 300 },
      ]}
      onChange={(state) => {
        // One render state PER placement, derived from the one editor.
        const wire = serializeStateForServer(state);
        for (const ab of wire.artboards) {
          void session.renderState(ab.name, {
            schemaVersion: wire.schemaVersion,
            artboards: [ab],
          }, 200);
        }
        // Save/reload: persist the RAW onChange state. Handing state.elements
        // back via initialElements restores each element onto its named
        // artboard (elements saved before the artboard tag existed land on
        // the first artboard, as before).
        saveDraft(state);
      }}
    />
  );
}

import { createDesignState, RenderSession } from '@snowcone-app/sdk';

// 1. Persist a canvas state once and get back an opaque stateId.
//    (Public endpoint — no key needed. Skip this if you already have one.)
//    NOTE: createDesignState takes the RAW editor state (onChange / toJSON()) —
//    NOT the serializeStateForServer() payload used by renderState above;
//    don't cross them.
const { stateId } = await createDesignState({
  productId: 'BEEB77',
  state: rawCanvasState,
});

// 2. Render it by reference — no canvas JSON in hand at render time. Ideal for
//    fulfillment, re-renders, or an agent that only carries a stateId.
const session = new RenderSession({
  shop: 'YOUR_SHOP_ID',
  grantUrl: '/api/realtime/grant',
  // mockupIds = catalog scene codes (mockups[].id), not a placement. BEEB77 has a
  // Frame color option, so variantId (options.combinations[].variantId) is required.
  product: { productId: 'BEEB77', mockupIds: ['FV1qjO'], variantId: 'Pv1sLC' },
});
session.onMockups((results) => { img.src = results[0].imageUrl; });

await session.renderSavedState('Front', stateId);

'use client';
import { useRealtimeMockup } from '@snowcone-app/sdk/react';

function LivePreview({ shop, state }: { shop: string; state: object }) {
  const { mockupResults, sendCanvasState } = useRealtimeMockup({
    // Same grant proxy — the hook opens the WS with the returned token.
    getToken: () =>
      fetch('/api/realtime/grant', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ shop }),
      }).then((r) => r.json()),
  });

  // Call sendCanvasState('Front', state) after connecting + sending config.
  // RenderSession (above) wraps this choreography — prefer it unless you need
  // the lower-level handle.
  return <img src={mockupResults[0]?.imageUrl} alt="mockup" />;
}