@seatlayer/js 0.77.2 → 0.78.0

package/dist/index.d.cts

@@ -287,7 +287,9 @@ interface RealtimeSink {
      *  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), and the sink cannot take a whole projection. */
-    resync(): void | Promise<void>;
+    resync(opts?: {
+        reason?: 'connect' | 'frame';
+    }): void | Promise<void>;
     /** Section availability changed (channel-agnostic; identical for every scope). */
     onSections?(hidden: string[], closed: string[]): void;
     /** Scope-projected presence counters. */
@@ -395,13 +397,47 @@ interface PickerControllerLike {
         label: string;
     }>;
     deselect(ids: string[]): void;
+    /** FORCED re-read. Reserved for "I just changed something, tell me the truth". */
     refresh(): Promise<void>;
+    /**
+     * COALESCED re-read, and the one a socket should use.
+     *
+     * `refresh()` was this sink's only option, and it is the forced call: every
+     * connect and every section frame bypassed the controller's snapshot
+     * coalescer and issued its own `/objects?compact=1`. On the measured DesiPass
+     * open that was two redundant full snapshots landing ~1.5 s after the map was
+     * already painted from the bootstrap bundle.
+     *
+     * Optional so a host pinning an older `@seatlayer/core` still works — that
+     * engine simply keeps the forced behaviour it always had.
+     */
+    resync?(opts?: {
+        reason?: 'connect' | 'frame';
+    }): Promise<void>;
+    /**
+     * Paint a whole authoritative projection with no round trip at all.
+     *
+     * Optional for the same reason: where the engine can take one, the socket's
+     * own connect frame IS the snapshot and the HTTP resync never happens.
+     */
+    applyProjection?(projection: {
+        default: string;
+        exceptions: Record<string, string>;
+    }): 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;
+    /**
+     * Labels the buyer is holding RIGHT NOW — the hold request is in flight and
+     * `currentHold()` is still null. The server broadcasts `held` before the
+     * hold response lands, so without this the buyer's own echo reads as
+     * "someone else took your seat", the selection is evicted, and the winning
+     * hold is left with nobody attached to it.
+     */
+    ownLabels?: () => Iterable<string>;
     /** Section availability changed and the chart itself needs rebuilding. */
     onSections?: (hidden: string[], closed: string[]) => void;
     onStatusChange?: () => void;
@@ -1815,6 +1851,8 @@ declare class SeatingChart {
     private readonly buyerAssetUrls;
     private readonly immersive;
     private realtime;
+    /** Labels whose hold request is in flight — see ControllerSinkOptions.ownLabels. */
+    private holdingLabels;
     constructor(options: SeatingChartOptions);
     /**
      * Camera x/y/scale is renderer-local and deliberately absent from the native
@@ -2535,6 +2573,46 @@ declare class EmbeddedDesigner {
     private handleMessage;
 }
 
+/**
+ * pickerConfirmCard — the card that stands between a tapped seat and the cart.
+ *
+ * It is one seat's whole story in one anchored popover: who the seat is (the
+ * identity grid), what it costs (the category band), what can be seen from it
+ * (the view thumbnail and the sightline line), and the two buttons that decide
+ * the matter. Raising it, placing it against the seat, wiring its six controls,
+ * committing it and taking it down are all here.
+ *
+ * Extracted from SeatPicker.ts (2026-09-03) so the widget has room to grow
+ * under the app's file-size ratchet, which pins the vendored mirror. Bodies are
+ * verbatim; the only edits are mechanical — the card's own two pieces of state
+ * (`el`, `seat`) live on this class, and every other value the code read off
+ * `this` now comes through {@link ConfirmCardHost}.
+ *
+ * THE HOST IS DELIBERATELY LATE-BOUND. Every member of it is a function the
+ * widget implements by calling its own method, never a captured value: the
+ * picker's tests replace `dismissConfirm`, `reducedMotion`, `scheduleMotion`,
+ * `syncTray`, `canOffer3d`, `enter3d` and `buyerAssetUrls` on the instance, and
+ * a card holding a bound reference from construction time would quietly ignore
+ * all of them. That seam is the same one `SectionCard` keeps for
+ * `sectionNeighbours`.
+ */
+
+/**
+ * The two questions this one card asks.
+ *
+ * `add` is the original: a seat the buyer has tapped but not yet taken.
+ * `remove` is the same card about a seat already in their cart, raised by a
+ * SECOND tap on it — which used to drop the seat silently, with no card and no
+ * notice (client report, 2026-09-04). Same layout, same identity, same price;
+ * only the primary button changes, and Cancel keeps the seat rather than
+ * dropping it.
+ *
+ * Deliberately not a separate card. A buyer taps a seat and expects the thing
+ * that seat's tap always produces; two popovers for one gesture is a second
+ * thing to learn for no gain.
+ */
+type ConfirmCardMode = 'add' | 'remove';
+
 /** What the saved-seat comparison chip needs from the widget around it. */
 interface CompareChipHost {
     /** The live 3D overlay the chip mounts into, or null when 3D is down. */
@@ -2740,6 +2818,10 @@ declare class SeatPicker implements GaPromptPicker {
     private ro;
     private holdTimer;
     private toastTimer;
+    /** The availability read every other caller joins. See refreshOfferAvailability. */
+    private offerReadInFlight;
+    /** When the last SUCCESSFUL availability read landed (0 = never). */
+    private offerReadSettledAt;
     private offerRefreshTimer;
     /** Armed only when the offer schedule has a known future transition (or as a
      * bounded retry after a failed read) — never a fixed-cadence poll. */
@@ -2970,6 +3052,32 @@ declare class SeatPicker implements GaPromptPicker {
     private reportFramedHeight;
     /** Full screen via the native API, falling back to a fixed-position overlay (iOS Safari). */
     private toggleFullscreen;
+    /**
+     * Is the picker already as big as the screen it is on?
+     *
+     * Measured, not inferred. A host that opens the widget inside its own
+     * full-height modal — DesiPass does exactly this on a phone — hands us a
+     * root whose rect IS the viewport, and there is nothing left for "Full
+     * screen" to give. The tolerance absorbs a hairline of host chrome, a
+     * fractional device pixel ratio and a rubber-banding iOS toolbar; anything
+     * larger than that is a real embed with page around it.
+     */
+    private fillsViewport;
+    /**
+     * Show the "Full screen" pill only where pressing it can change something.
+     *
+     * On a phone inside a host's full-height modal the pill was a dead control
+     * (client report on DesiPass, 2026-09-04): iOS Safari has no element
+     * fullscreen, so the tap fell through to the fixed-position fallback — which
+     * pins the widget to a viewport it was already filling. Nothing moved, and
+     * an affordance that does nothing is worse than one that is not there.
+     *
+     * Narrow only. A desktop embed that happens to be viewport-sized is still
+     * surrounded by browser chrome that native fullscreen removes, so the pill
+     * has something to do there. And an ACTIVE fullscreen always keeps its pill:
+     * that is the only way back out.
+     */
+    private syncFullscreenAffordance;
     private syncFullscreenButtons;
     /**
      * Native element-fullscreen was unavailable or rejected. When framed, a CSS
@@ -3247,7 +3355,6 @@ declare class SeatPicker implements GaPromptPicker {
     private renderSectionCard;
     private collapseSectionCard;
     private sectionCardOnView;
-    private fitSectionStripCount;
     /**
      * Open sections next to the focused one, in authored order.
      *
@@ -3280,7 +3387,7 @@ declare class SeatPicker implements GaPromptPicker {
      * `buyerAssetUrls` on the INSTANCE, and the card has to see those.
      */
     private get confirmCard();
-    /** @internal */ showConfirm(seat: ExpandedSeat): void;
+    /** @internal */ showConfirm(seat: ExpandedSeat, mode?: ConfirmCardMode): void;
     private reanchorConfirm;
     private dismissConfirm;
     /** @internal The card's own button calls the card; this is the seam the
@@ -3319,7 +3426,32 @@ declare class SeatPicker implements GaPromptPicker {
      * visibilitychange handler owns catching that tab up.
      */
     private scheduleOfferBoundary;
-    /** Debounce the no-store offer read behind a burst of seat-status frames. */
+    /**
+     * Is the answer we hold current enough that asking again would learn nothing?
+     *
+     * True while a read is in flight (its answer is on its way) or while one that
+     * just settled is inside the quiet window.
+     */
+    private offerReadIsCurrent;
+    /**
+     * Debounce the no-store offer read behind a burst of seat-status frames.
+     *
+     * THE SKIP IS DECIDED HERE, WHEN THE REFRESH IS ASKED FOR — not 180 ms later
+     * when the timer fires. Deciding at fire time made the dedupe a race between
+     * this debounce and the quiet window, with 250 − 180 = 70 ms of margin: if
+     * the timer ran even that little late, the window had lapsed and a second,
+     * identical availability read went out. Seventy milliseconds of scheduler
+     * jitter is nothing on a loaded machine, and this optimisation exists for
+     * mid-range phones, where it is nothing on a good day.
+     *
+     * (Caught by the app's test/pickerOpenPathConcurrency.test.ts failing once in
+     * a 462-file parallel run and passing in isolation — the flake was real, and
+     * it was here rather than in the test.)
+     *
+     * The rule is unchanged, only the instant it is evaluated at: a refresh asked
+     * for while the answer is still current is answered by the read that just
+     * happened. A batch arriving past the window still schedules and still reads.
+     */
     private scheduleOfferRefresh;
     /**
      * Pull the server's resolved answer. A failed refresh keeps the last truthful
@@ -3327,6 +3459,8 @@ declare class SeatPicker implements GaPromptPicker {
      * offer is worse than a temporarily stale remaining count.
      */
     private refreshOfferAvailability;
+    /** The read itself. Never rejects — see the catch. */
+    private readOfferAvailability;
     private offerPrice;
     private applyChannelPricing;
     private syncOffer;

package/dist/index.d.ts

@@ -287,7 +287,9 @@ interface RealtimeSink {
      *  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), and the sink cannot take a whole projection. */
-    resync(): void | Promise<void>;
+    resync(opts?: {
+        reason?: 'connect' | 'frame';
+    }): void | Promise<void>;
     /** Section availability changed (channel-agnostic; identical for every scope). */
     onSections?(hidden: string[], closed: string[]): void;
     /** Scope-projected presence counters. */
@@ -395,13 +397,47 @@ interface PickerControllerLike {
         label: string;
     }>;
     deselect(ids: string[]): void;
+    /** FORCED re-read. Reserved for "I just changed something, tell me the truth". */
     refresh(): Promise<void>;
+    /**
+     * COALESCED re-read, and the one a socket should use.
+     *
+     * `refresh()` was this sink's only option, and it is the forced call: every
+     * connect and every section frame bypassed the controller's snapshot
+     * coalescer and issued its own `/objects?compact=1`. On the measured DesiPass
+     * open that was two redundant full snapshots landing ~1.5 s after the map was
+     * already painted from the bootstrap bundle.
+     *
+     * Optional so a host pinning an older `@seatlayer/core` still works — that
+     * engine simply keeps the forced behaviour it always had.
+     */
+    resync?(opts?: {
+        reason?: 'connect' | 'frame';
+    }): Promise<void>;
+    /**
+     * Paint a whole authoritative projection with no round trip at all.
+     *
+     * Optional for the same reason: where the engine can take one, the socket's
+     * own connect frame IS the snapshot and the HTTP resync never happens.
+     */
+    applyProjection?(projection: {
+        default: string;
+        exceptions: Record<string, string>;
+    }): 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;
+    /**
+     * Labels the buyer is holding RIGHT NOW — the hold request is in flight and
+     * `currentHold()` is still null. The server broadcasts `held` before the
+     * hold response lands, so without this the buyer's own echo reads as
+     * "someone else took your seat", the selection is evicted, and the winning
+     * hold is left with nobody attached to it.
+     */
+    ownLabels?: () => Iterable<string>;
     /** Section availability changed and the chart itself needs rebuilding. */
     onSections?: (hidden: string[], closed: string[]) => void;
     onStatusChange?: () => void;
@@ -1815,6 +1851,8 @@ declare class SeatingChart {
     private readonly buyerAssetUrls;
     private readonly immersive;
     private realtime;
+    /** Labels whose hold request is in flight — see ControllerSinkOptions.ownLabels. */
+    private holdingLabels;
     constructor(options: SeatingChartOptions);
     /**
      * Camera x/y/scale is renderer-local and deliberately absent from the native
@@ -2535,6 +2573,46 @@ declare class EmbeddedDesigner {
     private handleMessage;
 }
 
+/**
+ * pickerConfirmCard — the card that stands between a tapped seat and the cart.
+ *
+ * It is one seat's whole story in one anchored popover: who the seat is (the
+ * identity grid), what it costs (the category band), what can be seen from it
+ * (the view thumbnail and the sightline line), and the two buttons that decide
+ * the matter. Raising it, placing it against the seat, wiring its six controls,
+ * committing it and taking it down are all here.
+ *
+ * Extracted from SeatPicker.ts (2026-09-03) so the widget has room to grow
+ * under the app's file-size ratchet, which pins the vendored mirror. Bodies are
+ * verbatim; the only edits are mechanical — the card's own two pieces of state
+ * (`el`, `seat`) live on this class, and every other value the code read off
+ * `this` now comes through {@link ConfirmCardHost}.
+ *
+ * THE HOST IS DELIBERATELY LATE-BOUND. Every member of it is a function the
+ * widget implements by calling its own method, never a captured value: the
+ * picker's tests replace `dismissConfirm`, `reducedMotion`, `scheduleMotion`,
+ * `syncTray`, `canOffer3d`, `enter3d` and `buyerAssetUrls` on the instance, and
+ * a card holding a bound reference from construction time would quietly ignore
+ * all of them. That seam is the same one `SectionCard` keeps for
+ * `sectionNeighbours`.
+ */
+
+/**
+ * The two questions this one card asks.
+ *
+ * `add` is the original: a seat the buyer has tapped but not yet taken.
+ * `remove` is the same card about a seat already in their cart, raised by a
+ * SECOND tap on it — which used to drop the seat silently, with no card and no
+ * notice (client report, 2026-09-04). Same layout, same identity, same price;
+ * only the primary button changes, and Cancel keeps the seat rather than
+ * dropping it.
+ *
+ * Deliberately not a separate card. A buyer taps a seat and expects the thing
+ * that seat's tap always produces; two popovers for one gesture is a second
+ * thing to learn for no gain.
+ */
+type ConfirmCardMode = 'add' | 'remove';
+
 /** What the saved-seat comparison chip needs from the widget around it. */
 interface CompareChipHost {
     /** The live 3D overlay the chip mounts into, or null when 3D is down. */
@@ -2740,6 +2818,10 @@ declare class SeatPicker implements GaPromptPicker {
     private ro;
     private holdTimer;
     private toastTimer;
+    /** The availability read every other caller joins. See refreshOfferAvailability. */
+    private offerReadInFlight;
+    /** When the last SUCCESSFUL availability read landed (0 = never). */
+    private offerReadSettledAt;
     private offerRefreshTimer;
     /** Armed only when the offer schedule has a known future transition (or as a
      * bounded retry after a failed read) — never a fixed-cadence poll. */
@@ -2970,6 +3052,32 @@ declare class SeatPicker implements GaPromptPicker {
     private reportFramedHeight;
     /** Full screen via the native API, falling back to a fixed-position overlay (iOS Safari). */
     private toggleFullscreen;
+    /**
+     * Is the picker already as big as the screen it is on?
+     *
+     * Measured, not inferred. A host that opens the widget inside its own
+     * full-height modal — DesiPass does exactly this on a phone — hands us a
+     * root whose rect IS the viewport, and there is nothing left for "Full
+     * screen" to give. The tolerance absorbs a hairline of host chrome, a
+     * fractional device pixel ratio and a rubber-banding iOS toolbar; anything
+     * larger than that is a real embed with page around it.
+     */
+    private fillsViewport;
+    /**
+     * Show the "Full screen" pill only where pressing it can change something.
+     *
+     * On a phone inside a host's full-height modal the pill was a dead control
+     * (client report on DesiPass, 2026-09-04): iOS Safari has no element
+     * fullscreen, so the tap fell through to the fixed-position fallback — which
+     * pins the widget to a viewport it was already filling. Nothing moved, and
+     * an affordance that does nothing is worse than one that is not there.
+     *
+     * Narrow only. A desktop embed that happens to be viewport-sized is still
+     * surrounded by browser chrome that native fullscreen removes, so the pill
+     * has something to do there. And an ACTIVE fullscreen always keeps its pill:
+     * that is the only way back out.
+     */
+    private syncFullscreenAffordance;
     private syncFullscreenButtons;
     /**
      * Native element-fullscreen was unavailable or rejected. When framed, a CSS
@@ -3247,7 +3355,6 @@ declare class SeatPicker implements GaPromptPicker {
     private renderSectionCard;
     private collapseSectionCard;
     private sectionCardOnView;
-    private fitSectionStripCount;
     /**
      * Open sections next to the focused one, in authored order.
      *
@@ -3280,7 +3387,7 @@ declare class SeatPicker implements GaPromptPicker {
      * `buyerAssetUrls` on the INSTANCE, and the card has to see those.
      */
     private get confirmCard();
-    /** @internal */ showConfirm(seat: ExpandedSeat): void;
+    /** @internal */ showConfirm(seat: ExpandedSeat, mode?: ConfirmCardMode): void;
     private reanchorConfirm;
     private dismissConfirm;
     /** @internal The card's own button calls the card; this is the seam the
@@ -3319,7 +3426,32 @@ declare class SeatPicker implements GaPromptPicker {
      * visibilitychange handler owns catching that tab up.
      */
     private scheduleOfferBoundary;
-    /** Debounce the no-store offer read behind a burst of seat-status frames. */
+    /**
+     * Is the answer we hold current enough that asking again would learn nothing?
+     *
+     * True while a read is in flight (its answer is on its way) or while one that
+     * just settled is inside the quiet window.
+     */
+    private offerReadIsCurrent;
+    /**
+     * Debounce the no-store offer read behind a burst of seat-status frames.
+     *
+     * THE SKIP IS DECIDED HERE, WHEN THE REFRESH IS ASKED FOR — not 180 ms later
+     * when the timer fires. Deciding at fire time made the dedupe a race between
+     * this debounce and the quiet window, with 250 − 180 = 70 ms of margin: if
+     * the timer ran even that little late, the window had lapsed and a second,
+     * identical availability read went out. Seventy milliseconds of scheduler
+     * jitter is nothing on a loaded machine, and this optimisation exists for
+     * mid-range phones, where it is nothing on a good day.
+     *
+     * (Caught by the app's test/pickerOpenPathConcurrency.test.ts failing once in
+     * a 462-file parallel run and passing in isolation — the flake was real, and
+     * it was here rather than in the test.)
+     *
+     * The rule is unchanged, only the instant it is evaluated at: a refresh asked
+     * for while the answer is still current is answered by the read that just
+     * happened. A batch arriving past the window still schedules and still reads.
+     */
     private scheduleOfferRefresh;
     /**
      * Pull the server's resolved answer. A failed refresh keeps the last truthful
@@ -3327,6 +3459,8 @@ declare class SeatPicker implements GaPromptPicker {
      * offer is worse than a temporarily stale remaining count.
      */
     private refreshOfferAvailability;
+    /** The read itself. Never rejects — see the catch. */
+    private readOfferAvailability;
     private offerPrice;
     private applyChannelPricing;
     private syncOffer;