@seatlayer/js 0.28.3 → 0.29.0

package/dist/index.js

@@ -1,5 +1,10 @@
 // src/SeatingChart.ts
-import { PickerController, loadLocale, setStringOverrides, t } from "@seatlayer/core";
+import {
+  PickerController,
+  loadLocale,
+  setStringOverrides,
+  t
+} from "@seatlayer/core";
 
 // src/api.ts
 var ApiError = class extends Error {
@@ -52,10 +57,13 @@ var PubApi = class {
       body: { selections, ...ttlMs ? { ttlMs } : {}, ...replaceHoldId ? { replaceHoldId } : {} }
     });
   }
-  bestAvailable(key, qty, categoryKey) {
+  // `zoneId` scopes the pick to one zone and `ttlMs` carries the host's checkout
+  // window — both are part of the route contract, and dropping either here made
+  // the SDK quietly pick venue-wide and hold for the server default instead.
+  bestAvailable(key, qty, categoryKey, zoneId, ttlMs) {
     return request(this.base, `/pub/events/${encodeURIComponent(key)}/best-available`, {
       method: "POST",
-      body: { qty, ...categoryKey ? { categoryKey } : {} }
+      body: { qty, ...categoryKey ? { categoryKey } : {}, ...zoneId ? { zoneId } : {}, ...ttlMs ? { ttlMs } : {} }
     });
   }
   resume(key, holdId) {
@@ -158,6 +166,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");
@@ -322,19 +331,30 @@ var SeatingChart = class {
     const h = await this.controller.holdGA(areaId, qty, options);
     return h ? { holdId: h.holdId, expiresAt: h.expiresAt, seats: h.seats, items: h.items } : null;
   }
-  /** Ask the server for the `qty` best free seats and hold them atomically. */
-  async bestAvailable(qty, categoryKey) {
+  /**
+   * Ask the server for the `qty` best free seats and hold them atomically.
+   * `options.ttlMs` sets the checkout window exactly like {@link hold}; omit it
+   * and the server falls back to the event setting, then its own default.
+   */
+  async bestAvailable(qty, categoryKey, options = {}) {
     try {
-      return await this.bestAvailableOrThrow(qty, categoryKey);
+      return await this.bestAvailableOrThrow(qty, categoryKey, options);
     } catch (err) {
       this.opts.onError?.(err);
       return null;
     }
   }
   /** @internal Throwing variant of {@link bestAvailable} for the native host adapter. See {@link holdOrThrow}. */
-  async bestAvailableOrThrow(qty, categoryKey) {
-    const h = await this.controller.bestAvailable(qty, categoryKey);
-    return h ? { holdId: h.holdId, expiresAt: h.expiresAt, labels: h.labels, seats: h.seats, items: h.items } : null;
+  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,
+      ...options.zoneId ? { zoneId: options.zoneId } : {}
+    } : null;
   }
   /**
    * Choose a ticket tier for a selected seat (e.g. Adult → Child). The seat's
@@ -366,6 +386,14 @@ var SeatingChart = class {
   setColorblindSafe(on) {
     this.controller.setColorblindSafe(on);
   }
+  /** Switch between flat, isometric and exact-seat Perspective 2.5D views. */
+  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();
@@ -1075,6 +1103,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;
@@ -1606,6 +1669,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}
@@ -1833,6 +1935,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;
@@ -1883,6 +1994,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())");
@@ -1901,12 +2015,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;
@@ -1995,19 +2111,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 = 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 ? t2("picker.sightline", { m: distance }) : this.tf("picker.sightlineClear", "Clear sightline")}</div>` : "";
-    return `<button type="button" class="sl-confirm-view sl-confirm-thumbwrap" aria-label="${t2("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="${t2("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="${t2("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) {
@@ -2424,7 +2547,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);
@@ -3108,15 +3231,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);
@@ -3186,13 +3309,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;
@@ -3409,7 +3536,7 @@ var SeatPicker = class _SeatPicker {
     }
     if (held) {
       try {
-        const updated = await this.controller.replaceTableQuantity(table.label, table.quantity);
+        const updated = await this.controller.replaceTableQuantity(table.label, table.quantity, this.opts.holdTtlMs);
         if (!updated) {
           this.toast("That guest count could not be secured. Your current table hold is unchanged.", "warning");
           this.renderTableDialogState();
@@ -3497,17 +3624,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;
@@ -3590,16 +3727,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;
@@ -4354,9 +4496,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();
   }
@@ -4364,6 +4507,178 @@ 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;
+  }
+  /** Toggle between the flat Map and the 3D venue view. No-op when unchanged or
+   *  when 3D is unavailable. */
+  setBuyerView(view) {
+    if (view === this.buyerView) return;
+    if (view === "venue3d") void this.enter3d();
+    else this.exit3d();
+  }
+  /** 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: 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 = 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;
@@ -4388,7 +4703,7 @@ var SeatPicker = class _SeatPicker {
       button.innerHTML = '<span class="sl-ba-spin" aria-hidden="true"></span>Finding\u2026';
     }
     try {
-      const h = await this.controller.bestAvailable(qty, categoryKey, opts);
+      const h = await this.controller.bestAvailable(qty, categoryKey, { ...opts, ttlMs: this.opts.holdTtlMs });
       if (h) {
         this.hold = { holdId: h.holdId, expiresAt: h.expiresAt, seats: h.seats, items: h.items };
         this.handedOff = false;
@@ -4455,6 +4770,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);
@@ -6111,7 +6427,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>
@@ -6121,7 +6437,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>