@seatlayer/js 0.28.4 → 0.30.0

package/README.md

@@ -1,12 +1,24 @@
 # @seatlayer/js
 
-The framework-agnostic [SeatLayer](https://seatlayer.io) embed SDK. Render an
-interactive seat map, let buyers select and **hold** seats in the browser, then
-**book** them from your server. Full docs: <https://docs.seatlayer.io>
+[![npm](https://img.shields.io/npm/v/@seatlayer/js)](https://www.npmjs.com/package/@seatlayer/js)
+[![npm downloads](https://img.shields.io/npm/dm/@seatlayer/js)](https://www.npmjs.com/package/@seatlayer/js)
+[![License: MIT](https://img.shields.io/badge/license-MIT-111827.svg)](../../LICENSE)
+
+The framework-agnostic SeatLayer embed SDK. Render the complete buyer picker or
+a headless interactive chart, let buyers select and **hold** inventory in the
+browser, then **book** it from your trusted server.
+
+[Package on npm](https://www.npmjs.com/package/@seatlayer/js) ·
+[Install guide](https://docs.seatlayer.io/buyer-sdk/install/) ·
+[Live demo](https://app.seatlayer.io/demo/play) ·
+[Website](https://seatlayer.io/developers/) ·
+[AI Toolkit](https://github.com/seatlayer/seatlayer-ai-toolkit)
 
 Works in plain HTML and any framework (React, Vue, Svelte, Angular…). For React,
 prefer the [`@seatlayer/react`](https://www.npmjs.com/package/@seatlayer/react) wrapper.
 
+## Install
+
 ```bash
 npm install @seatlayer/js
 ```
@@ -186,5 +198,20 @@ The full `SeatPicker` automatically restores an active hold after same-tab
 checkout navigation and lets the buyer remove individual held tickets. Set
 `restoreHold: false` and pass `initialHoldId` when your host owns persistence.
 
-The browser **holds**; your **server books** with a secret key. See the
-[integration guide](https://docs.seatlayer.io/getting-started/how-it-works/).
+The browser **holds**; your **server books** with a secret key. See
+[how the integration works](https://docs.seatlayer.io/start/how-it-works/).
+
+## Related resources
+
+- [Buyer SDK documentation](https://docs.seatlayer.io/buyer-sdk/install/)
+- [SeatingChart reference](https://docs.seatlayer.io/buyer-sdk/seating-chart/)
+- [Holds and checkout](https://docs.seatlayer.io/buyer-sdk/holds-and-checkout/)
+- [Complete checkout example](https://docs.seatlayer.io/examples/complete-checkout/)
+- [`@seatlayer/react`](https://www.npmjs.com/package/@seatlayer/react)
+- [iOS SDK](https://github.com/seatlayer/seatlayer-ios)
+- [Flutter package](https://pub.dev/packages/seatlayer)
+- [Agent-readable documentation](https://docs.seatlayer.io/llms.txt)
+
+## License
+
+MIT © SeatLayer

package/dist/index.cjs

@@ -1,7 +1,9 @@
 "use strict";
+var __create = Object.create;
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
 var __export = (target, all) => {
   for (var name in all)
@@ -15,6 +17,14 @@ var __copyProps = (to, from, except, desc) => {
   }
   return to;
 };
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
 // src/index.ts
@@ -194,6 +204,7 @@ var SeatingChart = class {
       this.rendered = false;
       return this;
     }
+    this.controller.setViewMode(this.opts.initialView ?? "flat");
     this.mode_ = info.mode === "test" ? "test" : "live";
     if (this.opts.seatTooltip !== false) {
       const tip = document.createElement("div");
@@ -374,7 +385,14 @@ var SeatingChart = class {
   /** @internal Throwing variant of {@link bestAvailable} for the native host adapter. See {@link holdOrThrow}. */
   async bestAvailableOrThrow(qty, categoryKey, options = {}) {
     const h = await this.controller.bestAvailable(qty, categoryKey, options);
-    return h ? { holdId: h.holdId, expiresAt: h.expiresAt, labels: h.labels, seats: h.seats, items: h.items } : null;
+    return h ? {
+      holdId: h.holdId,
+      expiresAt: h.expiresAt,
+      labels: h.labels,
+      seats: h.seats,
+      items: h.items,
+      ...options.zoneId ? { zoneId: options.zoneId } : {}
+    } : null;
   }
   /**
    * Choose a ticket tier for a selected seat (e.g. Adult → Child). The seat's
@@ -406,6 +424,17 @@ var SeatingChart = class {
   setColorblindSafe(on) {
     this.controller.setColorblindSafe(on);
   }
+  /** 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) {
+    this.controller.setViewMode(mode);
+  }
+  /** Current canvas projection. */
+  getViewMode() {
+    return this.controller.getViewMode();
+  }
   /** Zoom in one step (same increment as the wheel/pinch gesture). */
   zoomIn() {
     this.controller.zoomIn();
@@ -1074,6 +1103,7 @@ var EmbeddedDesigner = class {
 
 // src/SeatPicker.ts
 var import_core2 = require("@seatlayer/core");
+var import_meta = {};
 var DEFAULT_API_BASE2 = "https://api.seatlayer.io";
 var DEFAULT_MAX_SELECTION2 = 10;
 var EXTEND_PROMPT_MS = 6e4;
@@ -1105,6 +1135,41 @@ function escapeOption(value) {
     "'": "'"
   })[character]);
 }
+var SEATLAYER_MODULE_URL = (() => {
+  if (typeof document !== "undefined" && document.currentScript instanceof HTMLScriptElement && document.currentScript.src) {
+    return document.currentScript.src;
+  }
+  try {
+    const u = import_meta.url;
+    if (typeof u === "string" && u) return u;
+  } catch {
+  }
+  return void 0;
+})();
+var _webgl2Cache = null;
+function hasWebGL2() {
+  if (_webgl2Cache !== null) return _webgl2Cache;
+  try {
+    if (typeof document === "undefined") return _webgl2Cache = false;
+    const canvas = document.createElement("canvas");
+    _webgl2Cache = !!canvas.getContext("webgl2");
+  } catch {
+    _webgl2Cache = false;
+  }
+  return _webgl2Cache;
+}
+async function loadVenue3d() {
+  if (typeof __SEATLAYER_CDN__ !== "undefined" && __SEATLAYER_CDN__) {
+    const base = SEATLAYER_MODULE_URL ?? (typeof location !== "undefined" ? location.href : void 0);
+    if (!base) throw new Error("seatlayer: cannot resolve the 3D view chunk URL");
+    const url = new URL("./seatlayer-view3d.mjs", base).href;
+    return import(
+      /* @vite-ignore */
+      url
+    );
+  }
+  return import("@seatlayer/core/view3d");
+}
 var STYLE_ID = "seatlayer-picker-style";
 var CSS = `
 .sl-picker{position:relative;display:flex;flex-direction:column;width:100%;height:100%;min-height:420px;overflow:hidden;
@@ -1636,6 +1701,45 @@ var CSS = `
 .sl-projection button.on{background:var(--sl-accent);color:var(--sl-accent-ink)}
 .sl-picker[data-layout="narrow"] .sl-projection button{min-width:38px;min-height:32px;padding:5px 8px;font-size:9.5px}
 
+/* 3D venue overlay \u2014 mounts over the (paused) Konva stage inside the map host.
+   Carries its own gradient so it paints instantly before the scene builds, and
+   cross-fades on enter/exit via a compositor-only opacity transition. Sits below
+   the anchored chrome (z-index:5) and the confirm card (z-index:10) so the
+   Map|3D toggle and the seat confirm both stay usable over it. */
+.sl-view3d{position:absolute;inset:0;z-index:4;opacity:0;touch-action:none;
+  transition:opacity .3s ease;background:radial-gradient(120% 120% at 50% 0%,#191f28 0%,#0d1014 70%)}
+.sl-view3d canvas{display:block;width:100%;height:100%}
+[data-view3d=on] .sl-chips,[data-view3d=on] .sl-rungs{display:none}
+.sl-view3d-back{position:absolute;top:12px;left:12px;z-index:2;display:inline-flex;align-items:center;gap:6px;
+  padding:7px 13px 7px 9px;border-radius:999px;font-size:11px;font-weight:800;letter-spacing:.03em;
+  color:#e6edf3;background:rgba(10,14,20,.62);border:1px solid rgba(255,255,255,.22);backdrop-filter:blur(6px)}
+.sl-view3d-back:hover,.sl-view3d-back:focus-visible{background:rgba(16,22,30,.82);border-color:rgba(255,255,255,.4)}
+.sl-view3d-back svg{width:15px;height:15px;stroke:currentColor;stroke-width:2.4;fill:none;stroke-linecap:round;stroke-linejoin:round}
+/* While immersed, the 2D-only chrome is meaningless \u2014 hide it, keep Map|3D. */
+.sl-picker[data-view3d="on"] .sl-rungs,
+.sl-picker[data-view3d="on"] .sl-floors,
+.sl-picker[data-view3d="on"] .sl-zoom,
+.sl-picker[data-view3d="on"] .sl-seccard,
+.sl-picker[data-view3d="on"] .sl-minimap{display:none!important}
+/* The confirm card bottom-sheets over 3D (no 2D screen anchor to track). */
+.sl-picker[data-view3d="on"] .sl-confirm{left:50%!important;top:auto!important;bottom:16px;
+  transform:translateX(-50%);width:min(342px,calc(100% - 24px))}
+.sl-picker[data-view3d="on"] .sl-confirm[data-placement]{transform:translateX(-50%)}
+
+/* Plain "View from here" action shown when no real photo exists (the synthetic
+   thumb is suppressed at card size \u2014 full-screen is where it earns its keep). */
+.sl-confirm-viewbtn{width:100%;margin-top:9px;padding:8px;border-radius:8px;border:1px solid var(--sl-line);
+  display:flex;align-items:center;justify-content:center;gap:7px;font-size:12px;font-weight:800;
+  color:var(--sl-text);background:transparent;transition:border-color .15s,background .15s}
+.sl-confirm-viewbtn:hover,.sl-confirm-viewbtn:focus-visible{border-color:var(--sl-accent);background:color-mix(in srgb,var(--sl-accent) 10%,transparent)}
+/* confirm-card "See it in 3D" / "View from this seat" action \u2014 the purchase-
+   moment bridge into the cinematic. Styled like the view-from-seat button. */
+.sl-confirm-3d{width:100%;margin-top:9px;padding:8px;border-radius:8px;border:1px solid var(--sl-line);
+  display:flex;align-items:center;justify-content:center;gap:7px;font-size:12px;font-weight:800;
+  color:var(--sl-text);background:color-mix(in srgb,var(--sl-accent) 12%,transparent);transition:border-color .15s,background .15s}
+.sl-confirm-3d:hover,.sl-confirm-3d:focus-visible{border-color:var(--sl-accent);background:color-mix(in srgb,var(--sl-accent) 20%,transparent)}
+.sl-confirm-3d svg{width:15px;height:15px;stroke:currentColor;stroke-width:1.9;fill:none;stroke-linecap:round;stroke-linejoin:round}
+
 /* multi-floor switcher (flows within the left-rail region) */
 .sl-floors{display:none;flex-direction:column;gap:6px;max-width:100%}
 .sl-floors.on{display:flex}
@@ -1863,6 +1967,15 @@ var SeatPicker = class _SeatPicker {
     // arena / multi-floor / seat-view chrome
     this.rungsEl = null;
     this.projectionEl = null;
+    // --- 3D venue view (Map | 3D) ---
+    this.buyerView = "map";
+    this.view3dEl = null;
+    this.view3dHandle = null;
+    /** Monotonic token so a stale async mount (buyer left before OGL finished
+     *  loading) never installs its handle over a newer state. */
+    this.view3dGen = 0;
+    /** Seat whose 2D confirm card launched "See it in 3D"; re-shown on return. */
+    this.view3dReturnSeat = null;
     this.floorsEl = null;
     this.secCardEl = null;
     this.viewEl = null;
@@ -1913,6 +2026,9 @@ var SeatPicker = class _SeatPicker {
     this.lastAvailFloorId = "";
     this.availQuietUntil = 0;
     this.liveTimer = null;
+    /** `perspective` (2.5D) is retired from the buyer surface — accept it for
+     *  source compatibility but coerce to `flat` with a one-time deprecation warn. */
+    this.perspectiveWarned = false;
     if (!options || typeof options !== "object") throw new Error("seatmap: options object is required");
     if (!options.event || typeof options.event !== "string") throw new Error("seatmap: `event` key is required");
     if (!options.container) throw new Error("seatmap: `container` is required (or use SeatPicker.open())");
@@ -1931,12 +2047,14 @@ var SeatPicker = class _SeatPicker {
       onSelectionChange: () => {
         this.syncTray();
         if (this.committedSelection().length) this.collapseSectionCard();
+        this.syncSelectionTo3d();
       },
       onStatusChange: () => {
         this.syncPrices();
         this.evictTakenSelections();
         this.detectBooked();
         this.refreshMinimap();
+        this.pushAvailabilityTo3d();
       },
       onHoldExpired: () => {
         this.hold = null;
@@ -2025,19 +2143,26 @@ var SeatPicker = class _SeatPicker {
     const realPhoto = seat.viewUrl ?? "";
     const hasStage = this.chartHasStage();
     if (!realPhoto && !hasStage) return "";
-    let url = realPhoto;
     let distance = null;
-    if (!url) {
+    if (!realPhoto) {
       try {
         const thumb = (0, import_core2.generateSeatThumb)(seat, seat.focalPoint ?? doc.focalPoint);
-        url = thumb.url;
         distance = thumb.distanceM ?? null;
       } catch {
         return "";
       }
     }
     const sightHtml = hasStage ? `<div class="sl-confirm-sight"><span aria-hidden="true">\u2713</span>${distance != null ? (0, import_core2.t)("picker.sightline", { m: distance }) : this.tf("picker.sightlineClear", "Clear sightline")}</div>` : "";
-    return `<button type="button" class="sl-confirm-view sl-confirm-thumbwrap" aria-label="${(0, import_core2.t)("picker.viewFromSeat", { label: seat.label })}"><img class="sl-confirm-thumb" src="${url}" alt="" /><span class="sl-confirm-thumb-badge">\u{1F52D} ${this.tf("picker.viewFromHere", "View from here")}</span></button>` + sightHtml;
+    const viewBtn = realPhoto ? `<button type="button" class="sl-confirm-view sl-confirm-thumbwrap" aria-label="${(0, import_core2.t)("picker.viewFromSeat", { label: seat.label })}"><img class="sl-confirm-thumb" src="${realPhoto}" alt="" /><span class="sl-confirm-thumb-badge">\u{1F52D} ${this.tf("picker.viewFromHere", "View from here")}</span></button>` : `<button type="button" class="sl-confirm-view sl-confirm-viewbtn" aria-label="${(0, import_core2.t)("picker.viewFromSeat", { label: seat.label })}"><span aria-hidden="true">\u{1F52D}</span><span>${this.tf("picker.viewFromHere", "View from here")}</span></button>`;
+    return viewBtn + sightHtml;
+  }
+  /** "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. */
+  see3dConfirmHtml() {
+    if (!this.canOffer3d()) return "";
+    const label = this.buyerView === "venue3d" ? this.tf("picker.viewFromThisSeat", "View from this seat") : this.tf("picker.seeItIn3d", "See it in 3D");
+    return `<button type="button" class="sl-confirm-3d" aria-label="${label}"><svg viewBox="0 0 24 24" aria-hidden="true"><path d="M12 2l9 5v10l-9 5-9-5V7z"/><path d="M12 12l9-5M12 12v10M12 12L3 7"/></svg><span>${label}</span></button>`;
   }
   /** Minimal HTML/attribute escaper for buyer-authored commercial text (notes). */
   escCx(value) {
@@ -2454,7 +2579,7 @@ var SeatPicker = class _SeatPicker {
     }
     this.els.boot.remove();
     this.salesClosed = !!info.salesClosed;
-    this.controller.setViewMode(this.opts.initialView ?? "flat");
+    this.controller.setViewMode(this.normalizeInitialView(this.opts.initialView));
     this.buildRegions();
     this.regions["bottom-right"].appendChild(this.els.zoom);
     this.regions["bottom-center"].appendChild(this.els.toast);
@@ -3138,15 +3263,15 @@ var SeatPicker = class _SeatPicker {
     const doc = this.controller.doc;
     if (!doc || !this.els.map) return;
     const hasSections = doc.objects.some((o) => o.type === "section") || (doc.floors ?? []).some((f) => f.objects.some((o) => o.type === "section"));
-    if (hasSections) {
+    if (this.canOffer3d()) {
       const projection = document.createElement("div");
       projection.className = "sl-projection";
       projection.setAttribute("role", "group");
-      projection.setAttribute("aria-label", "Map projection");
-      projection.innerHTML = '<button type="button" data-projection="flat" aria-pressed="false" title="Flat 2D map">2D</button><button type="button" data-projection="perspective" aria-pressed="false" title="Perspective 2.5D map">2.5D</button>';
+      projection.setAttribute("aria-label", "Venue view");
+      projection.innerHTML = '<button type="button" data-view="map" aria-pressed="true" title="Flat 2D map">Map</button><button type="button" data-view="venue3d" aria-pressed="false" title="Interactive 3D venue view">3D</button>';
       projection.querySelectorAll("button").forEach((button) => {
         button.addEventListener("click", () => {
-          this.setViewMode(button.dataset.projection);
+          this.setBuyerView(button.dataset.view);
         });
       });
       this.regions["top-right"].appendChild(projection);
@@ -3216,13 +3341,17 @@ var SeatPicker = class _SeatPicker {
   }
   syncProjection() {
     if (!this.projectionEl) return;
-    const active = this.controller.getViewMode();
     this.projectionEl.querySelectorAll("button").forEach((button) => {
-      const on = button.dataset.projection === active;
+      const on = button.dataset.view === this.buyerView;
       button.classList.toggle("on", on);
       button.setAttribute("aria-pressed", String(on));
     });
   }
+  /** Can this picker offer the 3D venue view? Requires the option (default on)
+   *  and WebGL2, and a chart to render. */
+  canOffer3d() {
+    return this.opts.enable3D !== false && hasWebGL2() && !!this.controller.doc;
+  }
   /** Reflect the active floor onto the switcher rail. */
   syncFloors() {
     if (!this.floorsEl) return;
@@ -3527,17 +3656,27 @@ var SeatPicker = class _SeatPicker {
     el.setAttribute("aria-modal", "true");
     el.setAttribute("aria-label", `Confirm seat ${seat.label}`);
     el.style.setProperty("--sl-cat", cat?.color ?? "#6e7bff");
-    el.innerHTML = `<div class="sl-confirm-grid">` + identityFields + `</div><div class="sl-confirm-cat"><span class="sl-dot" style="background:${cat?.color ?? "#6e7bff"}"></span><span class="sl-confirm-cat-name">${safe(details?.categoryLabel ?? cat?.label ?? seat.categoryKey)}</span>` + (price != null ? `<span class="sl-confirm-price">${this.money(price)}</span>` : "") + `</div><div class="sl-confirm-body">` + this.wheelchairConfirmHtml(details?.wheelchairSpaceType) + this.commercialConfirmHtml(seat.commercial) + (this.seatViewEnabled() ? this.confirmThumbHtml(seat) : "") + `<div class="sl-confirm-row"><button type="button" class="sl-confirm-cancel">Cancel</button><button type="button" class="sl-confirm-add"><svg viewBox="0 0 24 24" aria-hidden="true"><path d="M5 12.5l4 4L19 7"/></svg>Select</button></div></div>`;
+    el.innerHTML = `<div class="sl-confirm-grid">` + identityFields + `</div><div class="sl-confirm-cat"><span class="sl-dot" style="background:${cat?.color ?? "#6e7bff"}"></span><span class="sl-confirm-cat-name">${safe(details?.categoryLabel ?? cat?.label ?? seat.categoryKey)}</span>` + (price != null ? `<span class="sl-confirm-price">${this.money(price)}</span>` : "") + `</div><div class="sl-confirm-body">` + this.wheelchairConfirmHtml(details?.wheelchairSpaceType) + this.commercialConfirmHtml(seat.commercial) + (this.seatViewEnabled() ? this.confirmThumbHtml(seat) : "") + this.see3dConfirmHtml() + `<div class="sl-confirm-row"><button type="button" class="sl-confirm-cancel">Cancel</button><button type="button" class="sl-confirm-add"><svg viewBox="0 0 24 24" aria-hidden="true"><path d="M5 12.5l4 4L19 7"/></svg>Select</button></div></div>`;
     this.els.map.appendChild(el);
     this.confirmEl = el;
     this.reanchorConfirm();
     el.querySelector(".sl-confirm-view")?.addEventListener("click", () => this.openSeatView(seat));
+    el.querySelector(".sl-confirm-3d")?.addEventListener("click", () => {
+      if (this.buyerView === "venue3d") {
+        void this.view3dHandle?.flyToSeat(seat.id);
+      } else {
+        this.view3dReturnSeat = seat;
+        this.dismissConfirm();
+        void this.enter3d(seat.id);
+      }
+    });
     el.querySelector(".sl-confirm-add").addEventListener("click", () => this.commitConfirm());
     el.querySelector(".sl-confirm-cancel").addEventListener("click", () => this.cancelConfirm());
     requestAnimationFrame(() => el.querySelector(".sl-confirm-add")?.focus());
   }
   reanchorConfirm() {
     if (!this.confirmEl || !this.confirmSeat) return;
+    if (this.root?.dataset.view3d === "on") return;
     const p = this.controller.worldToScreen({ x: this.confirmSeat.x, y: this.confirmSeat.y });
     if (this.root?.dataset.layout === "narrow") return;
     const mapWidth = this.els.map.clientWidth;
@@ -3620,16 +3759,21 @@ var SeatPicker = class _SeatPicker {
     this.viewEl = el;
     const pano = el.querySelector(".sl-view-pano");
     pano.style.backgroundImage = `url("${panoUrl}")`;
-    let zoom = 1.2;
-    let posX = 0;
+    const VFOV_DEG = 70;
+    const MAX_PITCH_DEG = 35;
+    let zoom = 1;
+    const vh0 = pano.clientHeight || 1;
+    const vw0 = pano.clientWidth || 1;
+    let posX = -(vh0 * (180 / VFOV_DEG) * 2 / 2 - vw0 / 2);
     let posY = 0;
     const apply = () => {
       const h = pano.clientHeight || 1;
-      const bgH = h * zoom;
+      const bgH = h * (180 / VFOV_DEG) * zoom;
       const overV = Math.max(0, bgH - h);
-      posY = Math.min(overV / 2, Math.max(-overV / 2, posY));
+      const pitchLimit = Math.min(overV / 2, MAX_PITCH_DEG / 180 * bgH);
+      posY = Math.min(pitchLimit, Math.max(-pitchLimit, posY));
       pano.style.backgroundSize = `auto ${bgH}px`;
-      pano.style.backgroundPosition = `${posX}px ${posY + overV / 2}px`;
+      pano.style.backgroundPosition = `${posX}px ${posY - overV / 2}px`;
     };
     apply();
     let dragging = false;
@@ -4384,9 +4528,10 @@ var SeatPicker = class _SeatPicker {
     this.controller.setColorblindSafe(on);
     writeStoredColorblind(on);
   }
-  /** 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) {
-    this.controller.setViewMode(mode);
+    this.controller.setViewMode(this.normalizeInitialView(mode));
     this.syncProjection();
     this.dismissConfirm();
   }
@@ -4394,6 +4539,208 @@ var SeatPicker = class _SeatPicker {
   getViewMode() {
     return this.controller.getViewMode();
   }
+  normalizeInitialView(mode) {
+    if (mode === "perspective") {
+      if (!this.perspectiveWarned) {
+        this.perspectiveWarned = true;
+        console.warn(
+          "[seatlayer] initialView:'perspective' (2.5D) is deprecated for the buyer picker and was coerced to 'flat'. Use the Map | 3D control for the immersive view."
+        );
+      }
+      return "flat";
+    }
+    return mode ?? "flat";
+  }
+  // ---- 3D venue view ---------------------------------------------------------
+  /** Current buyer view: the flat map, or the interactive 3D venue. */
+  getBuyerView() {
+    return this.buyerView;
+  }
+  /**
+   * 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, opts) {
+    if (view === "map") {
+      this.exit3d();
+      return;
+    }
+    const flyToSeatId = opts?.flyToSeatId;
+    if (this.buyerView === "venue3d") {
+      if (flyToSeatId) void this.view3dHandle?.flyToSeat(flyToSeatId);
+      return;
+    }
+    void this.enter3d(flyToSeatId);
+  }
+  /** SeatStatus → the view3d palette state. Selection is layered separately. */
+  seatState3dFor(id) {
+    switch (this.controller.getStatus(id)) {
+      case "held":
+        return "held";
+      case "booked":
+        return "sold";
+      case "not_for_sale":
+        return "dimmed";
+      default:
+        return "available";
+    }
+  }
+  /** Push the full live availability snapshot into the 3D handle (selection is
+   *  preserved inside the module). Cheap enough per status delta. */
+  pushAvailabilityTo3d() {
+    if (!this.view3dHandle) return;
+    const updates = this.allSeats().map((s) => ({ seatId: s.id, state: this.seatState3dFor(s.id) }));
+    this.view3dHandle.setAvailability(updates);
+  }
+  /** Mirror the authoritative widget selection into the 3D handle. */
+  syncSelectionTo3d() {
+    if (!this.view3dHandle) return;
+    this.view3dHandle.setSelection(this.controller.getSelection().map((s) => s.id));
+  }
+  /** Build the view-from-seat panorama the cinematic dissolves into — reuses the
+   *  exact input path as the 2D `openSeatView` (organizer photo, else generated). */
+  seatViewFor3d(seatId) {
+    const seat = this.allSeats().find((s) => s.id === seatId);
+    if (!seat) return null;
+    if (seat.viewUrl) return { url: seat.viewUrl };
+    const doc = this.controller.doc;
+    if (!doc) return null;
+    const activeId = this.controller.getActiveFloorId();
+    const focal = seat.focalPoint ?? doc.floors?.find((f) => f.id === activeId)?.focalPoint ?? doc.focalPoint ?? { x: 0, y: 0 };
+    try {
+      return { url: (0, import_core2.generateSeatPanorama)(seat, focal, this.allSeats()).url };
+    } catch {
+      return null;
+    }
+  }
+  /** Route the module's decoupled analytics into the host callback, tagged buyer. */
+  emit3dAnalytics(event, props) {
+    try {
+      this.opts.onAnalytics?.(event, { ...props, surface: "buyer" });
+    } catch {
+    }
+  }
+  /** 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). */
+  onView3dSeatPick(seatId) {
+    if (this.salesClosed) {
+      this.toast(this.tf("picker.salesClosedToast", "Sales are closed for this event."), "warning");
+      this.syncSelectionTo3d();
+      return;
+    }
+    const seat = this.allSeats().find((s) => s.id === seatId);
+    if (!seat) return;
+    const already = this.committedSelection().some((s) => s.id === seatId);
+    if (already) {
+      this.controller.deselect([seatId]);
+      this.dismissConfirm();
+      return;
+    }
+    this.flashPickedSeat(seatId);
+    this.controller.select([seatId]);
+    if (this.opts.confirmSelection !== false) this.showConfirm(seat);
+    else this.syncTray();
+  }
+  async enter3d(flySeatId) {
+    if (this.view3dEl || !this.canOffer3d() || !this.els.map) return;
+    const doc = this.controller.doc;
+    if (!doc) return;
+    this.buyerView = "venue3d";
+    this.root?.setAttribute("data-view3d", "on");
+    this.dismissConfirm();
+    this.syncProjection();
+    const overlay = document.createElement("div");
+    overlay.className = "sl-view3d";
+    overlay.setAttribute("role", "group");
+    overlay.setAttribute("aria-label", "Interactive 3D venue view");
+    const back = document.createElement("button");
+    back.type = "button";
+    back.className = "sl-view3d-back";
+    back.innerHTML = `<svg viewBox="0 0 24 24" aria-hidden="true"><path d="M15 18l-6-6 6-6"/></svg><span>${this.tf("picker.backToMap", "Back to map")}</span>`;
+    back.addEventListener("click", () => this.exit3d());
+    overlay.appendChild(back);
+    this.els.map.appendChild(overlay);
+    this.view3dEl = overlay;
+    requestAnimationFrame(() => {
+      overlay.style.opacity = "1";
+    });
+    const gen = ++this.view3dGen;
+    try {
+      const seats = (0, import_core2.expandChart)(doc);
+      const mod = await loadVenue3d();
+      if (gen !== this.view3dGen || this.buyerView !== "venue3d" || this.view3dEl !== overlay) return;
+      const handle = mod.mountVenue3D(overlay, { doc, seats }, {
+        onSeatPick: (id) => this.onView3dSeatPick(id),
+        // Deferred off the tap gesture: generateSeatPanorama walks every seat
+        // (O(n) on a 13k chart), and the module prefetches at pick — by the
+        // time the flight lands (~2.5s) the idle render has long finished. A
+        // null view REJECTS so the module's no-panorama path keeps the buyer
+        // in orbit instead of dissolving into an empty overlay.
+        getSeatView: (id) => new Promise((resolve, reject) => {
+          const run = () => {
+            const view = this.seatViewFor3d(id);
+            if (view) resolve(view);
+            else reject(new Error("seat_view_unavailable"));
+          };
+          const ric = globalThis.requestIdleCallback;
+          if (typeof ric === "function") ric(run, { timeout: 1500 });
+          else setTimeout(run, 50);
+        }),
+        onAnalytics: (event, props) => this.emit3dAnalytics(event, props)
+      });
+      this.view3dHandle = handle;
+      this.pushAvailabilityTo3d();
+      this.syncSelectionTo3d();
+      if (flySeatId) void handle.flyToSeat(flySeatId);
+    } catch (err) {
+      this.opts.onError?.(err);
+      this.exit3d();
+    }
+  }
+  exit3d() {
+    if (this.buyerView !== "venue3d" && !this.view3dEl) return;
+    this.view3dGen++;
+    this.buyerView = "map";
+    this.root?.removeAttribute("data-view3d");
+    try {
+      this.view3dHandle?.dispose();
+    } catch {
+    }
+    this.view3dHandle = null;
+    const overlay = this.view3dEl;
+    this.view3dEl = null;
+    if (overlay) {
+      overlay.style.opacity = "0";
+      setTimeout(() => overlay.remove(), 320);
+    }
+    this.syncProjection();
+    const seat = this.view3dReturnSeat;
+    this.view3dReturnSeat = null;
+    if (seat && this.committedSelection().some((s) => s.id === seat.id) && this.opts.confirmSelection !== false) {
+      this.showConfirm(seat);
+    }
+  }
   /** Current active/restored hold reflected in the tray. */
   getCurrentHold() {
     return this.hold;
@@ -4485,6 +4832,7 @@ var SeatPicker = class _SeatPicker {
     this.closeConfirm();
     this.dismissTableDialog(false);
     this.closeSeatView();
+    this.exit3d();
     this.stopHoldTimer();
     if (this.toastTimer) clearTimeout(this.toastTimer);
     if (this.liveTimer) clearTimeout(this.liveTimer);
@@ -6136,7 +6484,7 @@ var SeatManager = class {
     const category = this.doc?.categories.find((item) => item.key === seat.categoryKey);
     const sectionMetric = this.controlRoomSnapshot?.revenue.bySection.find((row) => row.sectionId === sectionId);
     const object = this.doc?.objects.find((item) => item.id === seat.rowId);
-    const location = object?.type === "row" ? { label: "Row", value: object.label } : object?.type === "table" ? { label: "Table", value: object.label } : seat.kind === "booth" ? { label: "Type", value: "Booth" } : null;
+    const location2 = object?.type === "row" ? { label: "Row", value: object.label } : object?.type === "table" ? { label: "Table", value: object.label } : seat.kind === "booth" ? { label: "Type", value: "Booth" } : null;
     const itemKind = seat.kind === "booth" ? "Booth" : "Seat";
     this.els.rail.innerHTML = `
       <p class="slm-eyebrow">${itemKind} details</p>
@@ -6146,7 +6494,7 @@ var SeatManager = class {
         <div class="slm-inspect-grid">
           <div><span>Status</span><b>${statusLabel[status]}</b></div>
           <div><span>Section</span><b>${esc(sectionLabel)}</b></div>
-          ${location ? `<div><span>${location.label}</span><b>${esc(location.value)}</b></div>` : ""}
+          ${location2 ? `<div><span>${location2.label}</span><b>${esc(location2.value)}</b></div>` : ""}
           <div><span>Category</span><b>${esc(category?.label ?? seat.categoryKey)}</b></div>
           <div><span>Sold in section</span><b>${sectionMetric ? `${sectionMetric.booked} of ${sectionMetric.total}` : "\u2014"}</b></div>
           <div><span>Section revenue</span><b>${sectionMetric && this.controlRoomSnapshot ? fmtMoney(sectionMetric.bookedRevenue, this.controlRoomSnapshot.currency) : "\u2014"}</b></div>