@seatlayer/js 0.28.4 → 0.30.0

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { PickerSeat, SeatHoverDetails, PickerTransport, RendererViewMode, ChartDoc, AvailabilityRule, ChartTheme, ExpandedSeat } from '@seatlayer/core';
+import { PickerSeat, RendererViewMode, SeatHoverDetails, PickerTransport, ChartDoc, AvailabilityRule, ChartTheme, ExpandedSeat } from '@seatlayer/core';
 export { ExpandedSeat, SeatHoverDetails } from '@seatlayer/core';
 
 /**
@@ -53,6 +53,7 @@ interface BestAvailableResult {
     labels: string[];
     seats?: PickerSeat[];
     items?: HoldResult['items'];
+    zoneId?: string;
 }
 
 /**
@@ -75,6 +76,9 @@ interface GAAreaAvailability {
     categoryKey: string;
     price: number;
     currency: string;
+    /** Buyer-facing copy authored separately from stable inventory identity. */
+    displayLabel?: string;
+    displayType?: string;
     tiers?: Array<{
         id: string;
         name: string;
@@ -111,6 +115,11 @@ interface SeatingChartOptions {
      * Toggleable later with setColorblindSafe().
      */
     colorblindSafe?: boolean;
+    /** Initial canvas projection.
+     * @deprecated `'isometric'` and `'perspective'` are retired in favour of the
+     * real 3D venue view (`setBuyerView('venue3d')`); they remain accepted for
+     * source compatibility and will be removed in the next major. Use `'flat'`. */
+    initialView?: RendererViewMode;
     /**
      * Built-in seat tooltip on mouse hover (seat · category · price · status).
      * Rendered inside the widget so every host gets it; default true. Turn off
@@ -259,6 +268,13 @@ declare class SeatingChart {
     setFloor(floorId: string): void;
     /** Toggle colorblind-safe rendering at runtime (see options.colorblindSafe). */
     setColorblindSafe(on: boolean): void;
+    /** Switch the 2D canvas projection.
+     * @deprecated `'isometric'` and `'perspective'` are retired in favour of the
+     * real 3D venue view (`setBuyerView('venue3d')`); accepted for source
+     * compatibility until the next major. */
+    setViewMode(mode: RendererViewMode): void;
+    /** Current canvas projection. */
+    getViewMode(): RendererViewMode;
     /** Zoom in one step (same increment as the wheel/pinch gesture). */
     zoomIn(): void;
     /** Zoom out one step. */
@@ -638,9 +654,26 @@ interface SeatPickerOptions {
     currency?: string;
     /** Colorblind-safe rendering (Okabe-Ito palette, hollow booked seats). */
     colorblindSafe?: boolean;
-    /** Initial map projection. `perspective` is the exact-seat projected 2.5D
-     * buyer view; all authoring and inventory identities remain unchanged. */
+    /** Initial map projection. Buyers now toggle **Map (flat 2D) + 3D** only; the
+     * legacy `perspective` (2.5D) value is still ACCEPTED for source compatibility
+     * but is deprecated — it is coerced to `flat` with a one-time console warning.
+     * The 3D venue view is entered from the Map/3D control, not this option. */
     initialView?: RendererViewMode;
+    /**
+     * Offer the interactive 3D venue view (Map | 3D toggle + a "See it in 3D"
+     * action on the seat-confirm card). Default true. The 3D button is shown only
+     * when this is not false AND the browser exposes WebGL2; there are ZERO GL
+     * bytes on the wire until the buyer actually opens 3D (the OGL chunk is
+     * dynamically imported on first use). Set false for embed hosts that must
+     * stay strictly 2D. */
+    enable3D?: boolean;
+    /**
+     * Optional analytics sink for the widget's own journey events. Currently emits
+     * the 3D venue-view journey (`3d_opened`, `3d_orbit_engaged`, `3d_seat_picked`,
+     * `3d_cinematic_played`/`_skipped`/`_cancelled`, `3d_panorama_opened`/`_closed`)
+     * with `{ surface: 'buyer' }` merged into the props. A throwing sink never
+     * breaks the widget. Route it to your product analytics (e.g. PostHog). */
+    onAnalytics?: (event: string, props: Record<string, unknown>) => void;
     /**
      * Hide the "Powered by SeatLayer" attribution badge in the side panel foot.
      * The chart theme's own `hideBadge` flag (paid orgs) also hides it — the badge
@@ -770,6 +803,14 @@ declare class SeatPicker {
     private cbSafe;
     private rungsEl;
     private projectionEl;
+    private buyerView;
+    private view3dEl;
+    private view3dHandle;
+    /** Monotonic token so a stale async mount (buyer left before OGL finished
+     *  loading) never installs its handle over a newer state. */
+    private view3dGen;
+    /** Seat whose 2D confirm card launched "See it in 3D"; re-shown on return. */
+    private view3dReturnSeat;
     private floorsEl;
     private secCardEl;
     private viewEl;
@@ -819,6 +860,10 @@ declare class SeatPicker {
      * (OV-52)
      */
     private confirmThumbHtml;
+    /** "See it in 3D" (2D) / "View from this seat" (already in 3D) action for the
+     *  confirm card. Only when 3D is available — the purchase-moment bridge into
+     *  the cinematic that reaches buyers who never press the Map | 3D toggle. */
+    private see3dConfirmHtml;
     /** Minimal HTML/attribute escaper for buyer-authored commercial text (notes). */
     private escCx;
     /** Localized "Restricted view" / "Obstructed view" label for a seat's flags,
@@ -1001,6 +1046,9 @@ declare class SeatPicker {
     /** Reflect the engine's current LOD rung onto the pill group. */
     private syncRung;
     private syncProjection;
+    /** Can this picker offer the 3D venue view? Requires the option (default on)
+     *  and WebGL2, and a chart to render. */
+    private canOffer3d;
     /** Reflect the active floor onto the switcher rail. */
     private syncFloors;
     /** Show (or clear, on null) the tapped-section summary card. */
@@ -1118,10 +1166,62 @@ declare class SeatPicker {
      *  cross-surface preference, and the in-widget button's pressed state together
      *  so the two controls never diverge. */
     setColorblindSafe(on: boolean): void;
-    /** Switch the buyer canvas between flat, isometric and Perspective 2.5D. */
+    /** Switch the underlying 2D renderer projection (flat / isometric). The buyer
+     *  UI no longer exposes `perspective`; it is coerced to `flat`. */
     setViewMode(mode: RendererViewMode): void;
     /** Current buyer canvas projection. */
     getViewMode(): RendererViewMode;
+    /** `perspective` (2.5D) is retired from the buyer surface — accept it for
+     *  source compatibility but coerce to `flat` with a one-time deprecation warn. */
+    private perspectiveWarned;
+    private normalizeInitialView;
+    /** Current buyer view: the flat map, or the interactive 3D venue. */
+    getBuyerView(): 'map' | 'venue3d';
+    /**
+     * Switch between the flat seat **Map** and the interactive **3D venue** view —
+     * the same control the buyer's on-widget `Map | 3D` toggle drives.
+     *
+     * Entering `'venue3d'` with `opts.flyToSeatId` runs the cinematic tour: the
+     * camera flies to the seat and holds in the live scene (a chip offers the
+     * 360° view-from-seat) —
+     * the widget enters 3D and auto-flies the camera to that seat, dissolving into
+     * its view-from-seat panorama (the same chain as tapping "See the view from
+     * here" on a seat's confirm card). When the widget is **already** in the 3D
+     * view, the camera simply flies to the requested seat — the GL scene is not
+     * torn down or rebuilt, so there is no flash or re-entry.
+     *
+     * No-op when the view is unchanged and no `flyToSeatId` is given, or when 3D is
+     * unavailable for this chart.
+     *
+     * @param view              `'map'` for the flat picker, `'venue3d'` for the 3D venue.
+     * @param opts.flyToSeatId  When entering (or already in) `'venue3d'`, the seat
+     *                          id to fly the camera to — cinematic → panorama.
+     *                          Ignored when `view` is `'map'`.
+     *
+     * @example
+     * // Public 3D tour entry — enter 3D and fly straight to the buyer's seat:
+     * picker.setBuyerView('venue3d', { flyToSeatId: 'A-12' });
+     */
+    setBuyerView(view: 'map' | 'venue3d', opts?: {
+        flyToSeatId?: string;
+    }): void;
+    /** SeatStatus → the view3d palette state. Selection is layered separately. */
+    private seatState3dFor;
+    /** Push the full live availability snapshot into the 3D handle (selection is
+     *  preserved inside the module). Cheap enough per status delta. */
+    private pushAvailabilityTo3d;
+    /** Mirror the authoritative widget selection into the 3D handle. */
+    private syncSelectionTo3d;
+    /** Build the view-from-seat panorama the cinematic dissolves into — reuses the
+     *  exact input path as the 2D `openSeatView` (organizer photo, else generated). */
+    private seatViewFor3d;
+    /** Route the module's decoupled analytics into the host callback, tagged buyer. */
+    private emit3dAnalytics;
+    /** A 3D seat tap runs the SAME selection path as a 2D tap: toggle through the
+     *  controller, then raise the shared confirm card (bottom-sheeted in 3D). */
+    private onView3dSeatPick;
+    private enter3d;
+    private exit3d;
     /** Current active/restored hold reflected in the tray. */
     getCurrentHold(): HoldResult | null;
     /** Explicit host-driven hold restore (automatic session restore is on by default). */

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { PickerSeat, SeatHoverDetails, PickerTransport, RendererViewMode, ChartDoc, AvailabilityRule, ChartTheme, ExpandedSeat } from '@seatlayer/core';
+import { PickerSeat, RendererViewMode, SeatHoverDetails, PickerTransport, ChartDoc, AvailabilityRule, ChartTheme, ExpandedSeat } from '@seatlayer/core';
 export { ExpandedSeat, SeatHoverDetails } from '@seatlayer/core';
 
 /**
@@ -53,6 +53,7 @@ interface BestAvailableResult {
     labels: string[];
     seats?: PickerSeat[];
     items?: HoldResult['items'];
+    zoneId?: string;
 }
 
 /**
@@ -75,6 +76,9 @@ interface GAAreaAvailability {
     categoryKey: string;
     price: number;
     currency: string;
+    /** Buyer-facing copy authored separately from stable inventory identity. */
+    displayLabel?: string;
+    displayType?: string;
     tiers?: Array<{
         id: string;
         name: string;
@@ -111,6 +115,11 @@ interface SeatingChartOptions {
      * Toggleable later with setColorblindSafe().
      */
     colorblindSafe?: boolean;
+    /** Initial canvas projection.
+     * @deprecated `'isometric'` and `'perspective'` are retired in favour of the
+     * real 3D venue view (`setBuyerView('venue3d')`); they remain accepted for
+     * source compatibility and will be removed in the next major. Use `'flat'`. */
+    initialView?: RendererViewMode;
     /**
      * Built-in seat tooltip on mouse hover (seat · category · price · status).
      * Rendered inside the widget so every host gets it; default true. Turn off
@@ -259,6 +268,13 @@ declare class SeatingChart {
     setFloor(floorId: string): void;
     /** Toggle colorblind-safe rendering at runtime (see options.colorblindSafe). */
     setColorblindSafe(on: boolean): void;
+    /** Switch the 2D canvas projection.
+     * @deprecated `'isometric'` and `'perspective'` are retired in favour of the
+     * real 3D venue view (`setBuyerView('venue3d')`); accepted for source
+     * compatibility until the next major. */
+    setViewMode(mode: RendererViewMode): void;
+    /** Current canvas projection. */
+    getViewMode(): RendererViewMode;
     /** Zoom in one step (same increment as the wheel/pinch gesture). */
     zoomIn(): void;
     /** Zoom out one step. */
@@ -638,9 +654,26 @@ interface SeatPickerOptions {
     currency?: string;
     /** Colorblind-safe rendering (Okabe-Ito palette, hollow booked seats). */
     colorblindSafe?: boolean;
-    /** Initial map projection. `perspective` is the exact-seat projected 2.5D
-     * buyer view; all authoring and inventory identities remain unchanged. */
+    /** Initial map projection. Buyers now toggle **Map (flat 2D) + 3D** only; the
+     * legacy `perspective` (2.5D) value is still ACCEPTED for source compatibility
+     * but is deprecated — it is coerced to `flat` with a one-time console warning.
+     * The 3D venue view is entered from the Map/3D control, not this option. */
     initialView?: RendererViewMode;
+    /**
+     * Offer the interactive 3D venue view (Map | 3D toggle + a "See it in 3D"
+     * action on the seat-confirm card). Default true. The 3D button is shown only
+     * when this is not false AND the browser exposes WebGL2; there are ZERO GL
+     * bytes on the wire until the buyer actually opens 3D (the OGL chunk is
+     * dynamically imported on first use). Set false for embed hosts that must
+     * stay strictly 2D. */
+    enable3D?: boolean;
+    /**
+     * Optional analytics sink for the widget's own journey events. Currently emits
+     * the 3D venue-view journey (`3d_opened`, `3d_orbit_engaged`, `3d_seat_picked`,
+     * `3d_cinematic_played`/`_skipped`/`_cancelled`, `3d_panorama_opened`/`_closed`)
+     * with `{ surface: 'buyer' }` merged into the props. A throwing sink never
+     * breaks the widget. Route it to your product analytics (e.g. PostHog). */
+    onAnalytics?: (event: string, props: Record<string, unknown>) => void;
     /**
      * Hide the "Powered by SeatLayer" attribution badge in the side panel foot.
      * The chart theme's own `hideBadge` flag (paid orgs) also hides it — the badge
@@ -770,6 +803,14 @@ declare class SeatPicker {
     private cbSafe;
     private rungsEl;
     private projectionEl;
+    private buyerView;
+    private view3dEl;
+    private view3dHandle;
+    /** Monotonic token so a stale async mount (buyer left before OGL finished
+     *  loading) never installs its handle over a newer state. */
+    private view3dGen;
+    /** Seat whose 2D confirm card launched "See it in 3D"; re-shown on return. */
+    private view3dReturnSeat;
     private floorsEl;
     private secCardEl;
     private viewEl;
@@ -819,6 +860,10 @@ declare class SeatPicker {
      * (OV-52)
      */
     private confirmThumbHtml;
+    /** "See it in 3D" (2D) / "View from this seat" (already in 3D) action for the
+     *  confirm card. Only when 3D is available — the purchase-moment bridge into
+     *  the cinematic that reaches buyers who never press the Map | 3D toggle. */
+    private see3dConfirmHtml;
     /** Minimal HTML/attribute escaper for buyer-authored commercial text (notes). */
     private escCx;
     /** Localized "Restricted view" / "Obstructed view" label for a seat's flags,
@@ -1001,6 +1046,9 @@ declare class SeatPicker {
     /** Reflect the engine's current LOD rung onto the pill group. */
     private syncRung;
     private syncProjection;
+    /** Can this picker offer the 3D venue view? Requires the option (default on)
+     *  and WebGL2, and a chart to render. */
+    private canOffer3d;
     /** Reflect the active floor onto the switcher rail. */
     private syncFloors;
     /** Show (or clear, on null) the tapped-section summary card. */
@@ -1118,10 +1166,62 @@ declare class SeatPicker {
      *  cross-surface preference, and the in-widget button's pressed state together
      *  so the two controls never diverge. */
     setColorblindSafe(on: boolean): void;
-    /** Switch the buyer canvas between flat, isometric and Perspective 2.5D. */
+    /** Switch the underlying 2D renderer projection (flat / isometric). The buyer
+     *  UI no longer exposes `perspective`; it is coerced to `flat`. */
     setViewMode(mode: RendererViewMode): void;
     /** Current buyer canvas projection. */
     getViewMode(): RendererViewMode;
+    /** `perspective` (2.5D) is retired from the buyer surface — accept it for
+     *  source compatibility but coerce to `flat` with a one-time deprecation warn. */
+    private perspectiveWarned;
+    private normalizeInitialView;
+    /** Current buyer view: the flat map, or the interactive 3D venue. */
+    getBuyerView(): 'map' | 'venue3d';
+    /**
+     * Switch between the flat seat **Map** and the interactive **3D venue** view —
+     * the same control the buyer's on-widget `Map | 3D` toggle drives.
+     *
+     * Entering `'venue3d'` with `opts.flyToSeatId` runs the cinematic tour: the
+     * camera flies to the seat and holds in the live scene (a chip offers the
+     * 360° view-from-seat) —
+     * the widget enters 3D and auto-flies the camera to that seat, dissolving into
+     * its view-from-seat panorama (the same chain as tapping "See the view from
+     * here" on a seat's confirm card). When the widget is **already** in the 3D
+     * view, the camera simply flies to the requested seat — the GL scene is not
+     * torn down or rebuilt, so there is no flash or re-entry.
+     *
+     * No-op when the view is unchanged and no `flyToSeatId` is given, or when 3D is
+     * unavailable for this chart.
+     *
+     * @param view              `'map'` for the flat picker, `'venue3d'` for the 3D venue.
+     * @param opts.flyToSeatId  When entering (or already in) `'venue3d'`, the seat
+     *                          id to fly the camera to — cinematic → panorama.
+     *                          Ignored when `view` is `'map'`.
+     *
+     * @example
+     * // Public 3D tour entry — enter 3D and fly straight to the buyer's seat:
+     * picker.setBuyerView('venue3d', { flyToSeatId: 'A-12' });
+     */
+    setBuyerView(view: 'map' | 'venue3d', opts?: {
+        flyToSeatId?: string;
+    }): void;
+    /** SeatStatus → the view3d palette state. Selection is layered separately. */
+    private seatState3dFor;
+    /** Push the full live availability snapshot into the 3D handle (selection is
+     *  preserved inside the module). Cheap enough per status delta. */
+    private pushAvailabilityTo3d;
+    /** Mirror the authoritative widget selection into the 3D handle. */
+    private syncSelectionTo3d;
+    /** Build the view-from-seat panorama the cinematic dissolves into — reuses the
+     *  exact input path as the 2D `openSeatView` (organizer photo, else generated). */
+    private seatViewFor3d;
+    /** Route the module's decoupled analytics into the host callback, tagged buyer. */
+    private emit3dAnalytics;
+    /** A 3D seat tap runs the SAME selection path as a 2D tap: toggle through the
+     *  controller, then raise the shared confirm card (bottom-sheeted in 3D). */
+    private onView3dSeatPick;
+    private enter3d;
+    private exit3d;
     /** Current active/restored hold reflected in the tray. */
     getCurrentHold(): HoldResult | null;
     /** Explicit host-driven hold restore (automatic session restore is on by default). */