@seatlayer/js 0.38.0 → 0.40.0

package/dist/index.d.ts

@@ -185,6 +185,176 @@ declare function createBuyerAccessContext(options: {
     buyerAccessToken?: string | BuyerAccessToken;
 }, hooks?: Pick<BuyerAccessContextOptions, 'onExpired' | 'onUnavailable'>): BuyerAccessContext | null;
 
+/**
+ * BuyerRealtimeClient — the client half of `docs/realtime-protocol-2026-08-01.md`.
+ *
+ * Why this exists as a separate socket rather than inside PickerController:
+ * a private scope authenticates with a one-use **subscribe ticket** carried in
+ * `Sec-WebSocket-Protocol`, and a browser can only set that at construction —
+ * `new WebSocket(url, protocols)`. The controller's socket is built from a URL
+ * alone (`PickerTransport.socketUrl`), and a bearer must never travel in a URL
+ * because URLs are routinely logged. So an access-scoped picker asks the
+ * transport for an empty `socketUrl()` (the controller then skips its own
+ * connection entirely) and this client owns the wire instead.
+ *
+ * A tokenless public picker never reaches this file. It keeps the controller's
+ * original socket, offers no subprotocol, and therefore receives byte-for-byte
+ * the frames it received before this module existed (protocol doc §1).
+ *
+ * What it implements:
+ *  - protocol negotiation: offer `seatlayer.v1`, believe the 101 echo, and fall
+ *    back to legacy frame handling when the server (or a proxy) does not echo;
+ *  - the ticket exchange, one mint per connection attempt, ticket in the
+ *    subprotocol list and never in the URL;
+ *  - 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;
+ *  - 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.
+ */
+
+/** The projected status of one unit, as the server words it on the wire. */
+type WireStatus = string;
+/** A scope's projection: one default plus the units that differ from it. */
+interface Projection {
+    default: WireStatus;
+    exceptions: Record<string, WireStatus>;
+}
+interface StatusChange {
+    label: string;
+    status: WireStatus;
+}
+/** Where reconstructed inventory goes. Implemented over PickerController. */
+interface RealtimeSink {
+    /** Apply a batch of label→status changes. Implementations must paint this as
+     *  ONE pass, not one pass per label (motion system §4 rule 2). */
+    applyStatuses(changes: StatusChange[]): void;
+    /** Re-pull authoritative state over the scoped HTTP route. Used when a frame
+     *  cannot be diffed against what we hold (first snapshot, or the scope's
+     *  default itself changed, which redefines every unit we were never told
+     *  about). */
+    resync(): void | Promise<void>;
+    /** Section availability changed (channel-agnostic; identical for every scope). */
+    onSections?(hidden: string[], closed: string[]): void;
+    /** Scope-projected presence counters. */
+    onPresence?(counts: {
+        shoppingSessions: number;
+        activeHolds: number;
+    }): void;
+}
+interface SubscribeTicket$1 {
+    ticket?: string;
+    /** Exactly what to hand `new WebSocket(url, protocols)`, per protocol doc §3. */
+    protocols?: string[];
+}
+interface BuyerRealtimeOptions {
+    /** The subscribe URL. Must never carry a credential — asserted below. */
+    url: string;
+    sink: RealtimeSink;
+    /** 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$1 | null>;
+    /** Typed access states. 4401 arrives here as `revoked`. */
+    onAccessUnavailable?: (event: BuyerAccessUnavailableEvent) => void;
+    /** Test seam. Defaults to the global WebSocket. */
+    socketFactory?: (url: string, protocols: string[]) => WebSocket;
+    /** Test seam for the keepalive/backoff timers. */
+    now?: () => number;
+}
+declare class BuyerRealtimeClient {
+    private readonly opts;
+    private ws;
+    private stopped;
+    private attempt;
+    private reconnectTimer;
+    private pingTimer;
+    private pongTimer;
+    private resumeTimer;
+    /** Our model of this scope's projection. Null until the first snapshot. */
+    private projection;
+    /** Last `snapshotVersion` seen on any frame that carried one — the resume point. */
+    private version;
+    /** True once the 101 echoed `seatlayer.v1`. */
+    private v1;
+    /** Set when we offered v1 and the handshake came back without it — a proxy
+     *  most likely stripped the header, so the next attempt selects the v1 frame
+     *  format with the `?pv=1` marker instead (protocol doc §1). The marker
+     *  selects a format and can never carry a credential or widen a scope. */
+    private useQueryMarker;
+    private hidden;
+    private closedSections;
+    constructor(options: BuyerRealtimeOptions);
+    /** Negotiated protocol, for tests and diagnostics. */
+    get protocol(): 'v1' | 'legacy' | null;
+    get snapshotVersion(): number | null;
+    start(): void;
+    /** Stop for good (destroy, or a revocation). Safe to call twice. */
+    stop(): void;
+    /** Restart after the host re-authorized a revoked buyer (`refreshAccess()`). */
+    restart(): void;
+    private connect;
+    private handleFrame;
+    /** The server answered our resume; cancel the fallback resync. */
+    private answered;
+    private reportIfAccessError;
+    /**
+     * Liveness is ping/pong, and only ping/pong. A socket that receives nothing
+     * for minutes is the normal, correct state for a narrowly-scoped buyer on a
+     * busy event (protocol doc §5), so quiet time never triggers a reconnect.
+     */
+    private startKeepalive;
+    /**
+     * FULL jitter, not plain exponential backoff.
+     *
+     * A deterministic `2**attempt` schedule makes every browser that lost the same
+     * socket — a worker redeploy, a DO eviction, a flaky edge PoP — come back in
+     * the same millisecond, and an on-sale crowd reconnecting in lockstep is the
+     * thing that turns one blip into a self-sustaining thundering herd. Full
+     * jitter (`random() * ceiling`) spreads the same crowd across the whole
+     * window; the ceiling still doubles, so a persistent outage still backs off.
+     *
+     * `Math.random` is correct here: this is client code choosing a delay, not a
+     * Workflow step that has to replay deterministically.
+     */
+    private scheduleReconnect;
+    private clearPongTimer;
+    private clearTimers;
+}
+/**
+ * The slice of PickerController this module drives. Structural on purpose — it
+ * keeps this file free of an `@seatlayer/core` import, and every member here is
+ * public controller API, so nothing in the engine mirror has to change.
+ */
+interface PickerControllerLike {
+    idForLabel(label: string): string | undefined;
+    tableSelection(seatIdOrLabel: string): {
+        physicalSeatIds: string[];
+    } | null;
+    setStatus(ids: string[], status: 'free' | 'held' | 'booked' | 'not_for_sale'): void;
+    getStatus(id: string): string | undefined;
+    flashSeat(id: string, color?: string): void;
+    currentHold(): {
+        labels: string[];
+    } | null;
+    getSelection(): Array<{
+        id: string;
+        label: string;
+    }>;
+    deselect(ids: string[]): void;
+    refresh(): Promise<void>;
+}
+interface ControllerSinkOptions {
+    /** Pulse seats other buyers take, as the controller's own socket does. */
+    flashOnLiveChange?: boolean;
+    /** Selected-but-unheld units that stopped being selectable. */
+    onSelectedObjectUnavailable?: (labels: string[], reason: 'ineligible' | 'taken') => void;
+    /** Section availability changed and the chart itself needs rebuilding. */
+    onSections?: (hidden: string[], closed: string[]) => void;
+    onStatusChange?: () => void;
+}
+declare function createControllerSink(controller: PickerControllerLike, options?: ControllerSinkOptions): RealtimeSink;
+
 /**
  * Minimal client for the public embed surface of workers/api (the `/pub/*`
  * routes). Deliberately self-contained — it does NOT reuse src/lib/api.ts,
@@ -217,7 +387,15 @@ declare class ApiError extends Error {
     conflicts?: HoldConflict[];
     /** Present when best-available 409s ('not_enough_together' | 'sold_out'). */
     reason?: string;
-    constructor(status: number, message: string, code?: string, conflicts?: HoldConflict[], reason?: string);
+    /**
+     * Seconds the server asked the caller to wait, off a 429's `Retry-After`.
+     *
+     * Present ONLY on a rate-limit error, and it is the server's number — never a
+     * guess. A widget that catches this can say "try again in N seconds" instead
+     * of rendering the blank map a swallowed 429 used to produce.
+     */
+    retryAfterS?: number;
+    constructor(status: number, message: string, code?: string, conflicts?: HoldConflict[], reason?: string, retryAfterS?: number);
 }
 interface HoldResult {
     holdId: string;
@@ -593,163 +771,6 @@ declare class SeatingChart {
     destroy(): void;
 }
 
-/**
- * BuyerRealtimeClient — the client half of `docs/realtime-protocol-2026-08-01.md`.
- *
- * Why this exists as a separate socket rather than inside PickerController:
- * a private scope authenticates with a one-use **subscribe ticket** carried in
- * `Sec-WebSocket-Protocol`, and a browser can only set that at construction —
- * `new WebSocket(url, protocols)`. The controller's socket is built from a URL
- * alone (`PickerTransport.socketUrl`), and a bearer must never travel in a URL
- * because URLs are routinely logged. So an access-scoped picker asks the
- * transport for an empty `socketUrl()` (the controller then skips its own
- * connection entirely) and this client owns the wire instead.
- *
- * A tokenless public picker never reaches this file. It keeps the controller's
- * original socket, offers no subprotocol, and therefore receives byte-for-byte
- * the frames it received before this module existed (protocol doc §1).
- *
- * What it implements:
- *  - protocol negotiation: offer `seatlayer.v1`, believe the 101 echo, and fall
- *    back to legacy frame handling when the server (or a proxy) does not echo;
- *  - the ticket exchange, one mint per connection attempt, ticket in the
- *    subprotocol list and never in the URL;
- *  - 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;
- *  - 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.
- */
-
-/** The projected status of one unit, as the server words it on the wire. */
-type WireStatus = string;
-/** A scope's projection: one default plus the units that differ from it. */
-interface Projection {
-    default: WireStatus;
-    exceptions: Record<string, WireStatus>;
-}
-interface StatusChange {
-    label: string;
-    status: WireStatus;
-}
-/** Where reconstructed inventory goes. Implemented over PickerController. */
-interface RealtimeSink {
-    /** Apply a batch of label→status changes. Implementations must paint this as
-     *  ONE pass, not one pass per label (motion system §4 rule 2). */
-    applyStatuses(changes: StatusChange[]): void;
-    /** Re-pull authoritative state over the scoped HTTP route. Used when a frame
-     *  cannot be diffed against what we hold (first snapshot, or the scope's
-     *  default itself changed, which redefines every unit we were never told
-     *  about). */
-    resync(): void | Promise<void>;
-    /** Section availability changed (channel-agnostic; identical for every scope). */
-    onSections?(hidden: string[], closed: string[]): void;
-    /** Scope-projected presence counters. */
-    onPresence?(counts: {
-        shoppingSessions: number;
-        activeHolds: number;
-    }): void;
-}
-interface SubscribeTicket$1 {
-    ticket?: string;
-    /** Exactly what to hand `new WebSocket(url, protocols)`, per protocol doc §3. */
-    protocols?: string[];
-}
-interface BuyerRealtimeOptions {
-    /** The subscribe URL. Must never carry a credential — asserted below. */
-    url: string;
-    sink: RealtimeSink;
-    /** 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$1 | null>;
-    /** Typed access states. 4401 arrives here as `revoked`. */
-    onAccessUnavailable?: (event: BuyerAccessUnavailableEvent) => void;
-    /** Test seam. Defaults to the global WebSocket. */
-    socketFactory?: (url: string, protocols: string[]) => WebSocket;
-    /** Test seam for the keepalive/backoff timers. */
-    now?: () => number;
-}
-declare class BuyerRealtimeClient {
-    private readonly opts;
-    private ws;
-    private stopped;
-    private attempt;
-    private reconnectTimer;
-    private pingTimer;
-    private pongTimer;
-    private resumeTimer;
-    /** Our model of this scope's projection. Null until the first snapshot. */
-    private projection;
-    /** Last `snapshotVersion` seen on any frame that carried one — the resume point. */
-    private version;
-    /** True once the 101 echoed `seatlayer.v1`. */
-    private v1;
-    /** Set when we offered v1 and the handshake came back without it — a proxy
-     *  most likely stripped the header, so the next attempt selects the v1 frame
-     *  format with the `?pv=1` marker instead (protocol doc §1). The marker
-     *  selects a format and can never carry a credential or widen a scope. */
-    private useQueryMarker;
-    private hidden;
-    private closedSections;
-    constructor(options: BuyerRealtimeOptions);
-    /** Negotiated protocol, for tests and diagnostics. */
-    get protocol(): 'v1' | 'legacy' | null;
-    get snapshotVersion(): number | null;
-    start(): void;
-    /** Stop for good (destroy, or a revocation). Safe to call twice. */
-    stop(): void;
-    /** Restart after the host re-authorized a revoked buyer (`refreshAccess()`). */
-    restart(): void;
-    private connect;
-    private handleFrame;
-    /** The server answered our resume; cancel the fallback resync. */
-    private answered;
-    private reportIfAccessError;
-    /**
-     * Liveness is ping/pong, and only ping/pong. A socket that receives nothing
-     * for minutes is the normal, correct state for a narrowly-scoped buyer on a
-     * busy event (protocol doc §5), so quiet time never triggers a reconnect.
-     */
-    private startKeepalive;
-    private scheduleReconnect;
-    private clearPongTimer;
-    private clearTimers;
-}
-/**
- * The slice of PickerController this module drives. Structural on purpose — it
- * keeps this file free of an `@seatlayer/core` import, and every member here is
- * public controller API, so nothing in the engine mirror has to change.
- */
-interface PickerControllerLike {
-    idForLabel(label: string): string | undefined;
-    tableSelection(seatIdOrLabel: string): {
-        physicalSeatIds: string[];
-    } | null;
-    setStatus(ids: string[], status: 'free' | 'held' | 'booked' | 'not_for_sale'): void;
-    getStatus(id: string): string | undefined;
-    flashSeat(id: string, color?: string): void;
-    currentHold(): {
-        labels: string[];
-    } | null;
-    getSelection(): Array<{
-        id: string;
-        label: string;
-    }>;
-    deselect(ids: string[]): void;
-    refresh(): Promise<void>;
-}
-interface ControllerSinkOptions {
-    /** Pulse seats other buyers take, as the controller's own socket does. */
-    flashOnLiveChange?: boolean;
-    /** Selected-but-unheld units that stopped being selectable. */
-    onSelectedObjectUnavailable?: (labels: string[], reason: 'ineligible' | 'taken') => void;
-    /** Section availability changed and the chart itself needs rebuilding. */
-    onSections?: (hidden: string[], closed: string[]) => void;
-    onStatusChange?: () => void;
-}
-declare function createControllerSink(controller: PickerControllerLike, options?: ControllerSinkOptions): RealtimeSink;
-
 /**
  * A secure, framework-neutral host for the SeatLayer chart Designer.
  *
@@ -2946,13 +2967,39 @@ declare class SeatManager {
     private labelToId;
     private labelToSeat;
     private allIds;
+    /**
+     * GA inventory units — real sellable labels the server counts, with NO seat
+     * geometry and therefore no renderer binding. They live here rather than in
+     * `labelToId`/`allIds` so every paint path keeps addressing paintable nodes
+     * only, while the tally denominator finally covers the same universe the
+     * numerator does. Without them a GA sale hit `booked` but not `total`:
+     * Free under-reported by GA capacity and SOLD% could exceed 100%.
+     */
+    private gaUnitLabelSet;
     private status;
+    /** Live non-free counters, moved by each delta rather than re-walked. */
+    private counts;
+    /** Bumped whenever the seat model is replaced wholesale (a full snapshot). */
+    private modelVersion;
     private currency;
     private authoritativeGrossRevenue;
     private revenueStatus;
     private revenueRequest;
-    private revenueRefreshTimer;
     private controlRoomSnapshot;
+    /**
+     * The server's own totals, pinned to the client model they were read against.
+     * Display = server baseline + (client now − client then), so the authoritative
+     * numbers land exactly on arrival and deltas still move them between reads.
+     * A wholesale model replacement invalidates the pairing (`model`), and the
+     * client tallies — themselves a fresh authenticated read — take over.
+     */
+    private serverBaseline;
+    /** Latest presence frame, held whether or not a snapshot has landed yet. */
+    private livePresence;
+    /** Latest cumulative booked gross pushed on a delta frame. */
+    private liveGross;
+    /** Coalesces a burst of deltas into one KPI/rail repaint. */
+    private paintHandle;
     private trendWindowMinutes;
     private heatEnabled;
     private followLive;
@@ -3082,6 +3129,22 @@ declare class SeatManager {
     private selectableStatuses;
     private updateRendererInteraction;
     private handleSeatSelect;
+    /**
+     * Build the client's inventory universe from the chart.
+     *
+     * `expandChart` yields SEATS — it has no output for a GA area, whose capacity
+     * is sold as N synthetic unit labels. The server's seat map keys, its deltas
+     * and its `totals` all speak those labels, so a client that only knows seats
+     * counts GA sales in the numerator (every key of the snapshot is written into
+     * `status`) while leaving them out of the denominator. Registering the GA
+     * units here — labels only, never a render binding — is what makes the two
+     * agree.
+     */
+    private buildUnitUniverse;
+    /** Every sellable unit the client knows: seats + GA capacity. */
+    private unitTotal;
+    /** Every label the client models, whether or not it can be painted. */
+    private knownLabels;
     private repaintAll;
     /**
      * Open the cockpit's realtime socket AS THE ORGANIZER.
@@ -3101,6 +3164,16 @@ declare class SeatManager {
     private connect;
     private scheduleReconnect;
     private onMessage;
+    /**
+     * Adopt the cumulative booked gross a delta frame carried.
+     *
+     * Stashed with its arrival time so an in-flight control-room read can decide
+     * whether it is holding the newer number: a frame that landed after the
+     * request started is newer than the response, one that landed before is not.
+     */
+    private applyLiveGross;
+    /** The single writer for a label's status, so the counters never drift. */
+    private setStatusLabel;
     private resnapshot;
     /**
      * Replace the whole seat model.
@@ -3111,6 +3184,8 @@ declare class SeatManager {
      * the mode really is free, wrong the moment it is not.
      */
     private applySnapshot;
+    /** The one O(n) walk left: a wholesale model replacement re-bases the counters. */
+    private recountAll;
     /** Optimistic local write shared by organizer actions. Paint and tally once,
      * even when an arena-sized operation changes hundreds of seats. */
     private setSeatsLocal;
@@ -3125,9 +3200,39 @@ declare class SeatManager {
     private locateActivity;
     private showLiveEvent;
     private applyReportRevenue;
+    /**
+     * Read the server's own control-room projection.
+     *
+     * Called on mount, on every socket (re)connect and after an organizer action —
+     * never on a timer and never per delta frame. Presence and gross that arrived
+     * on the socket AFTER this request started are newer than the response, so
+     * they survive it; anything older defers to the read.
+     */
     private refreshControlRoom;
-    private scheduleRevenueRefresh;
+    /** Pin the server's totals to the client model they were read against. */
+    private rebaseServerTotals;
+    /** What the client's own model says — GA units included since `render()`. */
+    private clientTallies;
+    /**
+     * The numbers the KPI bar and rail render.
+     *
+     * The server is the authority: its totals land exactly as read, and the
+     * delta-driven client model carries them forward until the next read. Before
+     * the first snapshot — and after a wholesale model replacement invalidates the
+     * pairing — the client model stands alone.
+     */
+    private buildTallies;
+    /**
+     * Queue one KPI/rail repaint for this burst of changes.
+     *
+     * A delta frame can carry hundreds of seats and `paintKpis` rebuilds eight
+     * nodes from scratch, so painting per change is what made an arena-sized
+     * frame expensive. Coalescing on a frame keeps the burst to a single rebuild;
+     * without `requestAnimationFrame` (SSR, an older test env) it paints inline
+     * rather than dropping the update.
+     */
     private recomputeTallies;
+    private flushTallies;
     private verbFor;
     private pushActivity;
     private seedFeed;
@@ -3150,6 +3255,9 @@ declare class SeatManager {
     private paintKpis;
     private paintRail;
     private renderViewRail;
+    /** Live presence wins over the snapshot's copy — it is the fresher channel,
+     *  and it exists from the first frame rather than the first fetch. */
+    private presenceCounts;
     private paintMonitorInsights;
     private applyHeatOverlay;
     private renderInspectRail;