@snowcone-app/canvas 0.36.7 → 0.37.0

package/dist/api/embed.d.ts

@@ -51,6 +51,9 @@ export { validateEmbed, collectEmbedIssues } from '../components/embed-realtime/
 export type { ValidateEmbedInput, EmbedIssue } from '../components/embed-realtime/validateEmbed.js';
 export { productToRenderConfig } from '../design/product-config.js';
 export type { ProductRenderConfig, ProductRenderConfigOptions } from '../design/product-config.js';
+export { bundleToRenderConfig, isBundleProduct, bundleVariantToken, splitRoleKey } from '../design/bundle-config.js';
+export type { BundleRenderConfig, BundleRenderConfigOptions, BundleRoleConfig, BundlePlacementConfig, BundleVariantChoice, CatalogBundleProduct, CatalogBundleBlock, CatalogBundleMember, CatalogBundleAlternative, } from '../design/bundle-config.js';
+export { isBundleRenderProduct } from '../components/embed-realtime/validateEmbed.js';
 export { design, DesignBuilder, isLayerToken, isColorToken } from '../design/design-builder.js';
 export type { Anchor, ShapeKind, DesignArtboard, StateArtboard, FromStateOptions, AnyDesign, LayerKind, LayerToken, ColorToken, } from '../design/design-builder.js';
 export { useEditor } from '../contexts/EditorContext.js';

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

@@ -34,6 +34,16 @@ export interface EmbedIssue {
     /** Two layers share a name — name-bound hooks bind the FIRST match,
      *  so a control may edit the wrong layer. */
      | 'duplicate-layer-names'
+    /** BUNDLE session (ADR-0099): a design artboard is a bare label
+     *  (`"Front"`) instead of a role-scoped key (`"top.front"`), or a bare
+     *  `variantId` is set — the server refuses both
+     *  (`E_BUNDLE_ROLE_REQUIRED`): two members can both have a "Front". */
+     | 'bundle-role-required'
+    /** BUNDLE session (ADR-0099): a role has no entry in
+     *  `product.variants` — the server keys the render on the per-role
+     *  variant set, so every role needs one (`bundleToRenderConfig` fills
+     *  defaults; hand-written configs must too). */
+     | 'bundle-variant-required'
     /** Runtime (not mount-time): a render has been in flight past
      *  `SLOW_RENDER_HINT_MS` with no mockup and no error — the silent-hang
      *  class. The render may still arrive; this is a heads-up. */
@@ -49,6 +59,9 @@ export interface EmbedIssue {
  * which entries are auto-filled colors, but without a variant none are.
  */
 export declare function requiredPlacementLabels(product: RenderProduct): string[];
+/** True when the product is wired as a BUNDLE session (ADR-0099): it
+ *  carries per-role `picks` and/or `variants`. */
+export declare function isBundleRenderProduct(product: RenderProduct): boolean;
 /** Find every wiring problem. Pure — no logging, no throwing. */
 export declare function collectEmbedIssues({ shop, product, design, hasGrant }: ValidateEmbedInput): EmbedIssue[];
 /** Legacy advisory API: log everything, never throw. (`placement-mismatch`

package/dist/design/bundle-config.d.ts

@@ -0,0 +1,127 @@
+import { CatalogProduct, RenderProduct } from '@snowcone-app/sdk';
+/** The `bundle` block of a catalog product (ADR-0099). */
+export type CatalogBundleBlock = NonNullable<CatalogProduct['bundle']>;
+/** One slot of a bundle. */
+export type CatalogBundleMember = CatalogBundleBlock['members'][number];
+/** One alternative product of a slot. */
+export type CatalogBundleAlternative = CatalogBundleMember['products'][number];
+/** A catalog product that IS a bundle — `bundle.members` is present and non-empty. */
+export type CatalogBundleProduct = CatalogProduct & {
+    bundle: CatalogBundleBlock;
+};
+/** True when the catalog product carries a non-empty `bundle` block. */
+export declare function isBundleProduct(product: CatalogProduct): product is CatalogBundleProduct;
+export interface BundleRenderConfigOptions {
+    /** Which alternative fills each slot, `role → member product code`.
+     *  Omitted roles take the slot's first alternative. Unknown roles throw
+     *  `E_BUNDLE_ROLE_NOT_FOUND`; a product outside the slot throws
+     *  `E_BUNDLE_PICK_NOT_FOUND` (both list the valid values). */
+    picks?: Record<string, string>;
+    /** The variant per slot, `role → gvid`. Omitted roles take the picked
+     *  alternative's `defaultGvid` (else its first variant). A gvid outside the
+     *  alternative's variant list throws `E_BUNDLE_VARIANT_NOT_FOUND`. */
+    variants?: Record<string, string>;
+    /** Role-scoped placement KEY to edit first (e.g. `"top.front"`). Defaults
+     *  to the first renderable placement of the picked alternatives. A bare
+     *  label (`"Front"`) throws `E_BUNDLE_ROLE_REQUIRED`; an unknown key throws
+     *  `E_PRODUCT_NOT_RENDERABLE` — both list the valid keys. */
+    placement?: string;
+    /** Render width passthrough (`product.width`). */
+    width?: number;
+}
+/** Geometry of one role-scoped placement of the picked alternatives. */
+export interface BundlePlacementConfig {
+    /** The role-scoped wire key — the artboard NAME and the `renderState`
+     *  placement on a bundle (`"top.front"`). */
+    key: string;
+    role: string;
+    /** The member's own placement label (`"Front"`) — display only, never an
+     *  identity on a bundle. */
+    label: string;
+    /** The member product this placement belongs to (the slot's pick). */
+    memberProductId: string;
+    width: number;
+    height: number;
+    aspectRatio: number;
+}
+/** One selectable variant of a slot's picked alternative. */
+export interface BundleVariantChoice {
+    gvid: string;
+    /** Human label from the alternative's `options.combinations` row (e.g.
+     *  `"Size M"`); falls back to the gvid when the row is unknown. */
+    label: string;
+}
+/** One slot of the bundle, resolved for the current picks + variants. */
+export interface BundleRoleConfig {
+    role: string;
+    required: boolean;
+    /** The alternatives' product codes, in catalog order (first = default). */
+    alternatives: string[];
+    /** The alternative currently filling the slot. */
+    pick: string;
+    /** The variant the slot renders (`variants[role]`). */
+    variantId: string;
+    /** Every variant the picked alternative accepts for `variants[role]`. */
+    variantChoices: BundleVariantChoice[];
+    /** The slot's renderable placements for the pick, in catalog order. */
+    placements: BundlePlacementConfig[];
+}
+export interface BundleRenderConfig {
+    /** Discriminant — a bundle config is never confusable with a
+     *  `ProductRenderConfig`. */
+    kind: 'bundle';
+    /** Ready for `<Editor.Root product={…}>`: `picks` + `variants` set,
+     *  `variantId` absent, `placements` / `requiredPlacements` carry the
+     *  role-scoped KEYS (the placement names the server demands). */
+    product: RenderProduct;
+    /** The resolved pick per role — every role present. */
+    picks: Record<string, string>;
+    /** The resolved variant per role — every role present. */
+    variants: Record<string, string>;
+    /** `role:renderGvid,…` sorted by role — the bundle scene identity the
+     *  catalog publishes as a bundle mockup's `gvids` entry and the server keys
+     *  the composite on. */
+    variantToken: string;
+    /** Every slot, resolved. */
+    roles: BundleRoleConfig[];
+    /** The placement being edited first — seed `design({ name: key, width, height })`. */
+    placement: BundlePlacementConfig;
+    /** Every renderable placement of the picked alternatives, in catalog order. */
+    placements: BundlePlacementConfig[];
+    /** `placements.map(p => p.key)` — the artboard names / renderState placements. */
+    placementKeys: string[];
+    /** The bundle's roles in catalog order. */
+    roleNames: string[];
+    /** First scene that photographs the picked alternatives — the default
+     *  `<Editor.Preview mockupId>`. */
+    primaryMockupId: string;
+}
+/** `role:renderGvid,…` sorted by role — deterministic, matches the box and the catalog. */
+export declare function bundleVariantToken(variantByRole: Record<string, string>): string;
+/** Split a role-scoped key (`"top.front"`) into `{ role, key }`; `null` when it carries no role. */
+export declare function splitRoleKey(name: string): {
+    role: string;
+    key: string;
+} | null;
+/**
+ * Derive the full bundle embed wiring from one `getProduct()` payload.
+ *
+ * ```ts
+ * const config = bundleToRenderConfig(await getProduct('V9NNNH'), { width: 2000 });
+ * const seed = design({ name: config.placement.key, ...config.placement })
+ *   .image(artworkUrl, { anchor: 'center' });     // ONE artboard → broadcast to every member
+ *
+ * <Editor.Root shop={SHOP} product={config.product} design={seed} grantUrl="/api/realtime-grant">
+ *
+ * // A pick or variant change is a NEW config: rebuild and pass the new product.
+ * const next = bundleToRenderConfig(product, { picks: { top: 'TANKXA' }, variants: config.variants });
+ * ```
+ *
+ * @throws EditorError `E_NOT_A_BUNDLE` — the product has no `bundle` block.
+ * @throws EditorError `E_BUNDLE_ROLE_NOT_FOUND` — `picks` / `variants` name an unknown role.
+ * @throws EditorError `E_BUNDLE_PICK_NOT_FOUND` — a pick is not one of the slot's alternatives.
+ * @throws EditorError `E_BUNDLE_VARIANT_NOT_FOUND` — a variant is not one of the pick's gvids, or the pick has none.
+ * @throws EditorError `E_BUNDLE_ROLE_REQUIRED` — `options.placement` is a bare label, not `<role>.<key>`.
+ * @throws EditorError `E_PRODUCT_NOT_RENDERABLE` — no renderable placement / scene, or an unknown placement key.
+ */
+export declare function bundleToRenderConfig(catalogProduct: CatalogProduct, options?: BundleRenderConfigOptions): BundleRenderConfig;

package/dist/design/product-config.d.ts

@@ -54,5 +54,8 @@ export interface ProductRenderConfig {
  * @throws EditorError `E_PRODUCT_NOT_RENDERABLE` when the product has no
  *   renderable image placement, no mockup scenes, or `options.placement`
  *   names a placement that doesn't exist (`data.validNames` lists the real ones).
+ * @throws EditorError `E_BUNDLE_CONFIG_REQUIRED` when the product is a BUNDLE
+ *   (ADR-0099: a `bundle` block) — it has no single variantId and role-scoped
+ *   placements, so this adapter cannot describe it; use `bundleToRenderConfig()`.
  */
 export declare function productToRenderConfig(catalogProduct: CatalogProduct, options?: ProductRenderConfigOptions): ProductRenderConfig;