@seatlayer/js 0.73.0 → 0.75.1

package/dist/index.d.ts

@@ -249,7 +249,8 @@ declare function createBuyerAccessContext(options: {
  *  - compact `{default, exceptions}` snapshot reconstruction;
  *  - `sv.<n>` resume, handling BOTH outcomes (a `resumed` delta or a full
  *    snapshot) on every reconnect;
- *  - close code 4401 as a typed access-revoked state, never a reconnect loop;
+ *  - close code 4401 distinguishes an expired session (refresh/reconnect) from
+ *    a genuinely revoked one (typed terminal state, never a reconnect loop);
  *  - liveness by ping/pong only. Silence is normal and carries no information
  *    (protocol doc §5) — a quiet socket is never treated as a dead one.
  */
@@ -306,7 +307,7 @@ interface BuyerRealtimeOptions {
     /** Mint a one-use ticket for THIS connection attempt. Returns null for the
      *  anonymous public case (no ticket needed). Throwing stops the client. */
     mintTicket?: () => Promise<SubscribeTicket | null>;
-    /** Typed access states. 4401 arrives here as `revoked`. */
+    /** Typed terminal access states. A 4401 `access_expired` close reconnects. */
     onAccessUnavailable?: (event: BuyerAccessUnavailableEvent) => void;
     /** Test seam. Defaults to the global WebSocket. */
     socketFactory?: (url: string, protocols: string[]) => WebSocket;
@@ -1095,7 +1096,10 @@ interface SeatPickerOptions {
      * same live fact. The picker remains fully functional when it is omitted.
      */
     onOfferAvailabilityChange?: (availability: TicketOfferAvailability | null) => void;
-    /** Hold TTL in ms passed to hold(); server clamps to its own limits. */
+    /**
+     * Fallback hold TTL in ms. An explicit event-dashboard duration takes
+     * priority; otherwise the server uses this request, then its 15-minute default.
+     */
     holdTtlMs?: number;
     /**
      * An opaque hold id supplied by the host to restore after navigation. It is
@@ -1339,7 +1343,22 @@ interface SeatingChartPickerState {
             label: string;
             color: string;
             price: number;
+            /** Remaining count, ZERO when the answer is not known yet. Kept for the
+             *  hosts that already read it; `free` below is the honest form. */
             available: number;
+            /**
+             * Remaining seats in this category — the number the confirm card's band
+             * prints as "N left", from the same `categoryAvailability()` the legend
+             * reads. `capability: category-availability-v1`.
+             *
+             * PRESENT-ONLY, and that is the whole reason it exists beside
+             * `available`. Availability lands after first paint, so `available: 0`
+             * cannot be told apart from "sold out" by a host that arrived early —
+             * and a shell that renders "0 left" on a category the buyer can still
+             * book has lied about the event. An absent `free` means "not known
+             * yet"; a `free: 0` means gone.
+             */
+            free?: number;
             tiers: Array<{
                 id: string;
                 name: string;
@@ -1416,7 +1435,11 @@ interface SeatingChartPickerState {
         accessNeeds: PickerAccessNeed[];
     };
     selection: {
-        seats: SelectedSeat[];
+        /**
+         * The selected seats, each carrying where it currently IS on screen when
+         * the renderer can say — see {@link SeatScreenPoint}.
+         */
+        seats: Array<SelectedSeat & SeatScreenPoint>;
         validity: PickerSelectionValidity | null;
         maxSelection: number;
     };
@@ -1426,6 +1449,26 @@ interface SeatingChartPickerState {
         reason?: string;
     };
 }
+/**
+ * Where a seat is on screen, for a shell drawing its OWN card over the map.
+ *
+ * `capability: seat-screen-point-v1`. The point is the seat's position in the
+ * map container's CSS pixels — the same value `reanchorConfirm` anchors the
+ * web confirm card to, read from the same `worldToScreen`, so a native card
+ * and the web one cannot disagree about where the seat is. Origin is the map
+ * container's top-left, not the page's.
+ *
+ * OPTIONAL, and a host must treat it that way: it exists only once a renderer
+ * is attached and only for a seat whose geometry the chart actually carries.
+ * A snapshot taken before first paint has none, and a shell that assumed it
+ * would place its card at (0, 0).
+ */
+interface SeatScreenPoint {
+    screenPoint?: {
+        x: number;
+        y: number;
+    };
+}
 
 /**
  * SeatingChart — the embeddable buyer picker.
@@ -1685,6 +1728,16 @@ declare class SeatingChart {
     private interactionEnabled_;
     /** The organizer's language for this event, learned when the chart resolves. */
     private eventLocale;
+    /**
+     * Fences competing dictionary loads. Several can be in flight at once — the
+     * boot fetch, the event's own language arriving with the chart, a buyer using
+     * the switcher — and they resolve in whatever order the network chooses.
+     * Without the fence the LAST to ARRIVE wins rather than the last to be ASKED
+     * for, which is how someone who picks French ends up reading German.
+     */
+    private localeGeneration;
+    /** The switcher, kept in step with a language change made from anywhere else. */
+    private languageSelect;
     private rendered;
     private mode_;
     private eventInfo;
@@ -1768,6 +1821,18 @@ declare class SeatingChart {
      * it does at first render.
      */
     setLocale(next: string | null | undefined): Promise<string>;
+    /**
+     * Re-say everything already on screen in the now-active locale.
+     *
+     * Split out of {@link setLocale} because two paths reach it: an explicit
+     * language change, and the boot dictionary landing after first paint — the
+     * second being the reason `render()` no longer waits for a locale fetch.
+     *
+     * `generation` fences out a stale winner; see {@link localeGeneration}.
+     * `refreshMapCopy` is a no-op before the renderer is mounted, so a dictionary
+     * that lands mid-chart-fetch costs nothing and the map is built translated.
+     */
+    private applyActiveLocale;
     getMode(): 'live' | 'test' | null;
     /** Atomic, token-free display state for native-owned picker chrome. */
     getPickerState(): SeatingChartPickerState;
@@ -1845,8 +1910,9 @@ declare class SeatingChart {
     }): Promise<HoldResult | null>;
     /**
      * 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.
+     * `options.ttlMs` requests the fallback hold window exactly like {@link hold}.
+     * An event-dashboard duration wins; otherwise the server uses this value,
+     * then its own default.
      */
     bestAvailable(qty: number, categoryKey?: string, options?: {
         zoneId?: string;
@@ -2639,6 +2705,18 @@ declare class SeatPicker implements GaPromptPicker {
     private handedOff;
     /** Guards single onBooked + single success overlay per hold. */
     private bookedShown;
+    /**
+     * The last hold attempt lost its seats.
+     *
+     * THE INTERLOCK. "Seat A12 was just taken by another buyer" and "You're all
+     * set — 1 ticket confirmed" were rendering together, because `detectBooked`
+     * reads a cleared controller hold as a completed booking — and a hold that
+     * was TAKEN clears exactly the same way one that was PAID clears. This flag
+     * is the difference the controller cannot express: set when an attempt
+     * conflicts, cleared the moment a hold succeeds, and checked before anything
+     * is allowed to congratulate the buyer.
+     */
+    private holdConflicted;
     /**
      * `'hosted'` only when the host asked for it AND the widget owns its own
      * transport. Resolved once in the constructor so every later read is a field
@@ -2739,6 +2817,20 @@ declare class SeatPicker implements GaPromptPicker {
     /** Supersedes an older authored-view byte request when another seat is opened. */
     private seatViewGen;
     private allSeatsCache;
+    /** The 3D "Back to map"/"Back to venue" control while 3D is on. It lives in
+     *  the top-left chrome region rather than in the 3D overlay, so it outlives
+     *  the overlay's own teardown and must be removed explicitly. */
+    private view3dBack;
+    /** The levels/areas rail while 3D is on. Region chrome for the same reason
+     *  the back control is (it shared twelve pixels with the ♿ menu), so like
+     *  the back control it outlives the overlay and is removed by hand. */
+    private view3dNav;
+    /** Which chips the price rail last drew, so a repaint that changes them can
+     *  send the scroller back to the start without stealing a buyer's own scroll. */
+    private lastRailSignature;
+    /** The panel's price-band <select>, so the rail's reset chip can keep it in
+     *  step. Null when the chart has fewer than two bands and none was built. */
+    private priceSelect;
     private minimap;
     private pickerLayoutSize;
     private priceBandKeys;
@@ -2990,7 +3082,27 @@ declare class SeatPicker implements GaPromptPicker {
     /** Held tickets and standing quantities consume the same order-wide cap. */
     private updateSelectionCapacity;
     private syncCta;
+    /**
+     * Narrate the money path.
+     *
+     * THE PHASE BELONGS TO THE PROMISE, NOT TO A CLOCK. `checkout` used to clear
+     * itself after a fixed 1,100ms whatever the unawaited hold or handoff was
+     * doing — so the button re-armed while the request was still in flight, and a
+     * buyer could press it again into a hold that had already failed. The phase
+     * now ends where the work ends: `runCheckoutHandoff` returns it to idle when
+     * the handoff settles, and `handleCta`'s catch returns it on failure.
+     */
     private setCtaPhase;
+    /**
+     * Hand the buyer to checkout and hold the "Opening secure checkout…" state
+     * for exactly as long as that takes.
+     *
+     * The default `onCheckout` is usually synchronous and usually navigates; the
+     * hosted path is a real promise. Awaiting both means the one visible signal
+     * that money is moving cannot expire early, and cannot outlive the work
+     * either.
+     */
+    private runCheckoutHandoff;
     /** Session-scoped capability key: isolated by API origin and event. */
     private holdStorageKey;
     private rememberedHoldId;
@@ -3000,8 +3112,22 @@ declare class SeatPicker implements GaPromptPicker {
     private restoreRememberedHold;
     /** Section-bearing objects on the active floor (single-floor → doc.objects). */
     private activeFloorObjects;
-    /** Attach the F3 overview minimap into the bottom-left chrome region. */
+    /**
+     * Attach the F3 overview minimap into the bottom-left chrome region — on a
+     * layout that has room for it.
+     *
+     * A PHONE NEVER GETS ONE (owner call 2026-09-02). At 375px the overview was
+     * a 114×89 thumbnail of a venue behind a toggle, sitting on top of the map
+     * it was meant to explain, and the drag-the-viewport gesture it exists for
+     * competes with the pan gesture directly underneath it. It is not hidden —
+     * it is not built, so it costs no canvas, no redraw on every pan, and no
+     * button in the tab order. `syncMinimapForLayout` builds and disposes it
+     * across a rotation, and every call site was already optional-chained.
+     */
     private buildMinimap;
+    /** Bring the overview into line with the current breakpoint after a resize
+     *  or a rotation. Wide gains one if it has none; narrow loses the one it has. */
+    private syncMinimapForLayout;
     /** Effective category summary price. Object-specific channel prices are added to the range below. */
     /** @internal */ catPrice(c: PricedCategory): number | undefined;
     /** @internal */ catPriceRange(c: PricedCategory): {
@@ -3011,6 +3137,15 @@ declare class SeatPicker implements GaPromptPicker {
     /** Build the compact price selector in the panel header. Choosing a band both
      *  filters availability and smoothly frames the matching seats on the map. */
     private buildPriceFilter;
+    /**
+     * Narrow the map to a price band, or clear it.
+     *
+     * Extracted from the select's change handler because the phone rail's
+     * leading "All prices" chip has to perform the SAME reset. Two copies of
+     * this would be two ways for the map, the legend, the floors and the 3D
+     * snapshot to end up disagreeing about what is filtered.
+     */
+    private applyPriceBand;
     /** Build projection, rung and floor controls for arena-scale charts. */
     private buildArenaChrome;
     /** Reflect the engine's current LOD rung onto the pill group. */
@@ -3060,8 +3195,55 @@ declare class SeatPicker implements GaPromptPicker {
     private cancelTableDialog;
     private dismissTableDialog;
     /** @internal */ showConfirm(seat: ExpandedSeat): void;
+    /**
+     * Ask for the press, once, until someone answers.
+     *
+     * The confirm card arrives with two buttons and nothing saying which one
+     * carries the decision. So the commit button shimmers shortly after the card
+     * lands and then breathes — and stops at the first sign of a person touching
+     * the card at all, not after a fixed count. An invitation that keeps being
+     * made after it has been received is nagging, which is why the stop is bound
+     * to three different first-contacts rather than to a timer.
+     *
+     * Nothing here runs under reduced motion: the class is never added, so the
+     * button is simply a button. (pickerMotion also stands the class down, for a
+     * caller that is not this one.)
+     */
+    private inviteCommit;
+    /**
+     * What the confirm card's commit button says.
+     *
+     * "Select" named the mechanism, not the act — on a card already showing Row,
+     * Seat and a price, the one control that decides the purchase was the least
+     * specific thing on it. It names the act instead.
+     *
+     * NO PRICE ON THE BUTTON (owner call 2026-09-02). "Add seat · $180" was tried
+     * and wrapped the button to two lines beside a one-line Cancel on a 310px
+     * phone card. The amount is already the largest thing in the band directly
+     * above, so putting it on the button bought a second copy of a fact the
+     * buyer is looking at and cost the row its shape.
+     *
+     * A seat only. A booth, a table or a general-admission line keeps the
+     * existing wording rather than being told it is adding a "seat" — those
+     * surfaces have their own nouns (the table dialog says "Select whole table"),
+     * and a wrong noun is worse than a general verb.
+     */
+    private addSeatLabel;
     private reanchorConfirm;
     private dismissConfirm;
+    /**
+     * Commit the candidate — and let the press be seen.
+     *
+     * STATE FIRST, ALWAYS. The cart, the totals and the 3D snapshot update on the
+     * same tick as the click; nothing below defers a fact. What IS sequenced is
+     * the card's departure: the button sweeps its accent left to right while the
+     * tick draws and the label turns to "Added", and only then does the card
+     * leave and the seat fly to the tray. Dismissing on the click cut that sweep
+     * off after about one frame — the widget was animating a moment nobody could
+     * see, which is worse than not animating it.
+     *
+     * Reduced motion takes the old path exactly: no sweep, no wait.
+     */
     private commitConfirm;
     private cancelConfirm;
     private closeConfirm;
@@ -3160,7 +3342,18 @@ declare class SeatPicker implements GaPromptPicker {
      * on a different path, which nulls this.hold first).
      */
     private detectBooked;
+    /**
+     * Say that the seats were lost, and make sure nothing says otherwise.
+     *
+     * Every conflict path funnels through here rather than calling `toast`
+     * directly, so the flag and the message can never disagree — and so a
+     * success overlay that somehow got up is taken down with the same gesture
+     * that reports the failure.
+     */
+    private raiseHoldConflict;
     private showBooked;
+    /** Take the confirmation down and give the map back. The booking stands. */
+    private dismissBooked;
     /**
      * A Performance Group hold settled, told to us by the WRAPPER rather than by
      * a socket (§8: this surface has no realtime feed). `detectBooked` waits for
@@ -3210,6 +3403,24 @@ declare class SeatPicker implements GaPromptPicker {
         label: string;
         onClick: () => void;
     }): void;
+    /**
+     * Keep the toast off the confirm card's buttons.
+     *
+     * Both live at the bottom of the map, so a message raised while a card is
+     * open painted straight over Cancel/Add for its full 4.2 seconds — measured
+     * with the toast at [94,677,187,71] across a card at [32,536,310,212]. The
+     * buyer was told a seat had gone by something sitting on the two controls
+     * they needed to answer with.
+     *
+     * The toast rides ABOVE the card's own top edge instead, and only while a
+     * card is up: with no card it belongs where it has always been, at the
+     * bottom of the map. It is the whole bottom-center region that moves,
+     * because the "need more time?" prompt shares it and would collide the same
+     * way.
+     */
+    private liftToastOverConfirm;
+    /** Re-run the lift once the browser has laid the card out. */
+    private liftToastOverConfirmSoon;
     /** Loading silhouette → real venue. The sequence lives in pickerBootReveal. */
     private dismissSkeleton;
     private placeTooltip;
@@ -3481,6 +3692,19 @@ declare class SeatPicker implements GaPromptPicker {
     private openView3dComparison;
     private closeView3dComparison;
     private enter3d;
+    /**
+     * Publish how much room the picker's own top-left chrome takes, as
+     * `--sl-3d-top-inset` on the widget root.
+     *
+     * The 3D layer draws its "Live seat-eye view · …" caption in the same twelve
+     * pixels. That caption is engine surface with its position written inline, so
+     * the widget cannot move it; publishing the measurement is the seam the
+     * engine needs to read one day, and it costs nothing until it does. The
+     * widget's own rules already use it, which is why it is measured rather than
+     * assumed: the region wraps, and a chart with an accessibility flag beside
+     * the back button is two rows tall.
+     */
+    private publish3dTopInset;
     private exit3d;
     /** Current active/restored hold reflected in the tray. */
     getCurrentHold(): HoldResult | null;