@seatlayer/core 0.71.4 → 0.72.0

package/dist/index.d.ts

@@ -1,15 +1,15 @@
-import { C as ChartDoc, F as FloorLabelStyle, P as Point, A as AccessibilityType, i as CategoryTier, S as SeatCommercialAttributes, w as ChartDeliveryPerformance } from './types-0yruRsAj.js';
-export { x as ACCESSIBILITY_RING_COLOR, y as ACCESSIBILITY_TYPES, z as AccessibilityMeta, D as AuthoringObjectState, B as BoothObject, p as Category, E as ChartLayoutConstraint, a as ChartObject, o as ChartReferenceImage, H as ChartTheme, I as ConfidenceEvidenceScope, u as CubicPath, J as DecorImageObject, l as Floor, G as GAAreaObject, h as GAInventorySegment, K as LABEL_STYLE_MAX_SIZE, M as LABEL_STYLE_MIN_SIZE, N as LabelPresentation, L as LabelStyle, O as ObjectEditorState, Q as Physical3dEvidence, U as RadialClearanceLayoutConstraint, n as RectTableSeatCounts, k as RectTableSide, V as ReferenceAccessibilitySource, W as ReferenceCalibration, X as ReferenceCategorySource, Y as ReferenceDerivedScale, Z as ReferenceEnrichmentStatus, _ as ReferenceExtractEmptyReason, $ as ReferenceExtractEnrichment, a0 as ReferenceExtractInput, a1 as ReferenceExtractProposal, a2 as ReferenceExtractRegionSeats, a3 as ReferenceInventoryExclusionSource, a4 as ReferenceInventorySource, a5 as ReferenceMatchReport, a6 as ReferenceScanProposal, a7 as ReferenceScanRowProposal, a8 as ReferenceScanSectionProposal, a9 as ReferenceSeatSeed, aa as ReferenceSectionTraceBatchInput, ab as ReferenceSectionTraceBatchProposal, ac as ReferenceSectionTraceInput, ad as ReferenceSectionTraceProposal, c as ResolvedSeatConfidenceEvidence, R as RowObject, ae as SEAT_COMMERCIAL_MARKS, af as SURROUNDINGS_SHAPE_ROLES, ag as SeatCommercialMark, ah as SeatCommercialMeta, ai as SeatConfidenceCoverage, aj as SeatConfidenceEvidence, ak as SeatConfidenceModelLevel, al as SeatConfidenceModeledTarget, am as SeatConfidenceRealityLevel, d as SeatGlyphKind, j as SeatOverride, e as SeatViewCoverage, b as SeatViewMetadata, an as SeatViewVariant, m as SectionObject, f as SectionOutlinePath, g as SectionPathSegment, ao as SelectionLayer, q as ShapeLineCap, r as ShapeLineEnding, s as ShapeLineJoin, t as ShapeObject, T as TableObject, ap as TextAlignment, aq as TextBackground, v as TextObject, ar as TicketTierApplicability, as as TicketTierEvidence, at as TicketTierRestriction, au as Venue3DMaterialPalette, av as VenueSurveyRegistrationEvidence, aw as ZoneDef, ax as accessibilityMeta, ay as accessibilityRingColor, az as layerOf, aA as seatCommercialMeta } from './types-0yruRsAj.js';
-import { E as EventConfigurationRef, a as EventConfigurationVersion } from './eventConfigurations-0OC43JJY.js';
-export { b as EVENT_CONFIGURATION_EXPORT_SCHEMA, c as EVENT_CONFIGURATION_SCHEMA, d as EventConfigurationBaseVenue, e as EventConfigurationCompatibilityIssue, f as EventConfigurationCompatibilityIssueCode, g as EventConfigurationCompatibilityResult, h as EventConfigurationExportEnvelope, i as EventConfigurationLifecycleStatus, j as EventConfigurationOcclusion, k as EventConfigurationOverlay, l as EventConfigurationParseIssue, m as EventConfigurationParseIssueCode, n as EventConfigurationParseResult, o as EventConfigurationProductionElement, p as EventConfigurationProductionElementKind, q as EventConfigurationVenueSnapshot, r as EventConfigurationVersionParseResult, s as EventConfigurationVersionSummary, L as LegacyEventConfigurationMigrationResult, t as canTransitionEventConfiguration, u as canonicalEventConfigurationJson, v as inspectEventConfigurationCompatibility, w as migrateLegacyEventConfigurations, x as parseEventConfigurationExport, y as parseEventConfigurationVersion, z as resolveEventConfigurationRollback } from './eventConfigurations-0OC43JJY.js';
-export { C as ChartBoundsOptions, E as ExpandChartOptions, F as FLOOR_STACK_GAP_RATIO, a as FLOOR_STACK_MIN_SURFACE_PX, b as FloorStackOptions, c as FloorStackPlacement, R as RowSeatSlot, T as TABLE_SEAT_OFFSET, d as TableSeatSlot, e as allObjects, f as chartBounds, g as expandBooth, h as expandChart, i as expandRow, j as expandRowSlots, k as expandTable, l as expandTableSlots, m as floorObjects, n as floorStackPlacements, o as floorsOf, p as initialFloorMode, q as layoutFloorStack, r as mainFloorId, s as objectCenter, t as owningSectionForObject, u as pointInPolygon, v as pointInPolygonWithHoles, w as polygonLabelPoint, x as rowInventoryCount, y as rowSeatPositions, z as stackFloors, A as tableInventoryCount, B as tableSeatCountsBySide, D as translateObject } from './layout-DkDRcXvu.js';
-import { c as TicketSelectionIssue } from './ticketRestrictions-dvlNTwem.js';
-export { M as MAX_EVENT_INVENTORY, a as MAX_GA_CAPACITY, g as gaAreasOf, h as gaInventorySegments, i as gaUnitLabel, j as gaUnitLabels, k as growJoinedGAInventory, l as isGaUnitLabel, v as validGAInventorySegments } from './ticketRestrictions-dvlNTwem.js';
-export { A as AvailabilityRule, S as SectionNode, T as TIER_HEIGHT_M, U as UNGROUPED_ID, a as applyHidden, c as computeSections, h as hiddenObjectIds, i as isSectionHidden, s as sectionGeometry } from './sections-CrX4vq-m.js';
-export { R as RENDERED_QUALITY_REPORT_VERSION, a as RenderedEvidenceState, b as RenderedQualityFinding, c as RenderedQualityFindingCode, d as RenderedQualityReport, e as RenderedQualitySample, i as inspectRenderedQualityEvidence } from './renderedQuality-BwwrqYzX.js';
-import { I as ISeatmapRenderer, b as RendererOptions, S as SeatStatus, c as SeatMark, E as ExpandedSeat, G as GAAreaState, d as RendererViewMode, e as RendererMinimapSnapshot, L as LodRung, R as RendererQualityEvidence, f as RendererCallbacks } from './renderer-BNicx5sw.js';
-export { C as CHART_STORAGE_KEY, g as RenderedBookableLabelEvidence, a as RenderedFreeTextEvidence, h as RenderedGAAreaEvidence, i as RenderedHierarchyLabelEvidence, j as RenderedLabelHiddenReason, k as RenderedRowLabelEvidence, l as RendererHoverDetails, m as RendererMinimapSeat, n as RendererMinimapSection, o as SeatMarkKind } from './renderer-BNicx5sw.js';
-import './segmentedRowModel-BOO8w9Ng.js';
+import { C as ChartDoc, F as FloorLabelStyle, P as Point, A as AccessibilityType, i as CategoryTier, S as SeatCommercialAttributes, w as ChartDeliveryPerformance } from './types-D6-wLa-m.js';
+export { x as ACCESSIBILITY_RING_COLOR, y as ACCESSIBILITY_TYPES, z as AccessibilityMeta, D as AuthoringObjectState, B as BoothObject, p as Category, E as ChartLayoutConstraint, a as ChartObject, o as ChartReferenceImage, H as ChartTheme, I as ConfidenceEvidenceScope, u as CubicPath, J as DecorImageObject, l as Floor, G as GAAreaObject, h as GAInventorySegment, K as LABEL_STYLE_MAX_SIZE, M as LABEL_STYLE_MIN_SIZE, N as LabelPresentation, L as LabelStyle, O as ObjectEditorState, Q as Physical3dEvidence, U as RadialClearanceLayoutConstraint, n as RectTableSeatCounts, k as RectTableSide, V as ReferenceAccessibilitySource, W as ReferenceCalibration, X as ReferenceCategorySource, Y as ReferenceDerivedScale, Z as ReferenceDirectAnnotationSource, _ as ReferenceDirectLandmarkCandidate, $ as ReferenceDirectLandmarkDisposition, a0 as ReferenceDirectLandmarkRole, a1 as ReferenceDirectSeatGroup, a2 as ReferenceDirectSeatImportSource, a3 as ReferenceDirectSeatPlan, a4 as ReferenceEnrichmentStatus, a5 as ReferenceExtractEmptyReason, a6 as ReferenceExtractEnrichment, a7 as ReferenceExtractInput, a8 as ReferenceExtractProposal, a9 as ReferenceExtractRegionSeats, aa as ReferenceInventoryExclusionSource, ab as ReferenceInventorySource, ac as ReferenceMatchReport, ad as ReferenceScanProposal, ae as ReferenceScanRowProposal, af as ReferenceScanSectionProposal, ag as ReferenceSeatSeed, ah as ReferenceSectionTraceBatchInput, ai as ReferenceSectionTraceBatchProposal, aj as ReferenceSectionTraceInput, ak as ReferenceSectionTraceProposal, c as ResolvedSeatConfidenceEvidence, R as RowObject, al as SEAT_COMMERCIAL_MARKS, am as STAGE_LABEL_STYLE_MAX_SIZE, an as SURROUNDINGS_SHAPE_ROLES, ao as SeatCommercialMark, ap as SeatCommercialMeta, aq as SeatConfidenceCoverage, ar as SeatConfidenceEvidence, as as SeatConfidenceModelLevel, at as SeatConfidenceModeledTarget, au as SeatConfidenceRealityLevel, d as SeatGlyphKind, j as SeatOverride, e as SeatViewCoverage, b as SeatViewMetadata, av as SeatViewVariant, m as SectionObject, f as SectionOutlinePath, g as SectionPathSegment, aw as SelectionLayer, q as ShapeLineCap, r as ShapeLineEnding, s as ShapeLineJoin, t as ShapeObject, ax as StageLabelStyle, T as TableObject, ay as TextAlignment, az as TextBackground, v as TextObject, aA as TicketTierApplicability, aB as TicketTierEvidence, aC as TicketTierRestriction, aD as Venue3DMaterialPalette, aE as VenueSurveyRegistrationEvidence, aF as ZoneDef, aG as accessibilityMeta, aH as accessibilityRingColor, aI as layerOf, aJ as seatCommercialMeta } from './types-D6-wLa-m.js';
+import { E as EventConfigurationRef, a as EventConfigurationVersion } from './eventConfigurations-DfVUGyCg.js';
+export { b as EVENT_CONFIGURATION_EXPORT_SCHEMA, c as EVENT_CONFIGURATION_SCHEMA, d as EventConfigurationBaseVenue, e as EventConfigurationCompatibilityIssue, f as EventConfigurationCompatibilityIssueCode, g as EventConfigurationCompatibilityResult, h as EventConfigurationExportEnvelope, i as EventConfigurationLifecycleStatus, j as EventConfigurationOcclusion, k as EventConfigurationOverlay, l as EventConfigurationParseIssue, m as EventConfigurationParseIssueCode, n as EventConfigurationParseResult, o as EventConfigurationProductionElement, p as EventConfigurationProductionElementKind, q as EventConfigurationVenueSnapshot, r as EventConfigurationVersionParseResult, s as EventConfigurationVersionSummary, L as LegacyEventConfigurationMigrationResult, t as canTransitionEventConfiguration, u as canonicalEventConfigurationJson, v as inspectEventConfigurationCompatibility, w as migrateLegacyEventConfigurations, x as parseEventConfigurationExport, y as parseEventConfigurationVersion, z as resolveEventConfigurationRollback } from './eventConfigurations-DfVUGyCg.js';
+export { C as ChartBoundsOptions, E as ExpandChartOptions, F as FLOOR_STACK_GAP_RATIO, a as FLOOR_STACK_MIN_SURFACE_PX, b as FloorStackOptions, c as FloorStackPlacement, R as RowSeatSlot, T as TABLE_SEAT_OFFSET, d as TableSeatSlot, e as allObjects, f as chartBounds, g as expandBooth, h as expandChart, i as expandRow, j as expandRowSlots, k as expandTable, l as expandTableSlots, m as floorObjects, n as floorStackPlacements, o as floorsOf, p as initialFloorMode, q as layoutFloorStack, r as mainFloorId, s as objectCenter, t as owningSectionForObject, u as pointInPolygon, v as pointInPolygonWithHoles, w as polygonLabelPoint, x as rowInventoryCount, y as rowSeatPositions, z as stackFloors, A as tableInventoryCount, B as tableSeatCountsBySide, D as translateObject } from './layout-B7URbtDR.js';
+import { c as TicketSelectionIssue } from './ticketRestrictions-CvS2oQ8v.js';
+export { M as MAX_EVENT_INVENTORY, a as MAX_GA_CAPACITY, g as gaAreasOf, h as gaInventorySegments, i as gaUnitLabel, j as gaUnitLabels, k as growJoinedGAInventory, l as isGaUnitLabel, v as validGAInventorySegments } from './ticketRestrictions-CvS2oQ8v.js';
+export { A as AvailabilityRule, S as SectionNode, T as TIER_HEIGHT_M, U as UNGROUPED_ID, a as applyHidden, c as computeSections, h as hiddenObjectIds, i as isSectionHidden, s as sectionGeometry } from './sections-Cn_sk1Sx.js';
+export { R as RENDERED_QUALITY_REPORT_VERSION, a as RenderedEvidenceState, b as RenderedQualityFinding, c as RenderedQualityFindingCode, d as RenderedQualityReport, e as RenderedQualitySample, i as inspectRenderedQualityEvidence } from './renderedQuality-C5dQiq97.js';
+import { I as ISeatmapRenderer, b as RendererOptions, S as SeatStatus, c as SeatMark, E as ExpandedSeat, G as GAAreaState, d as RendererViewMode, e as RendererMinimapSnapshot, L as LodRung, R as RendererQualityEvidence, f as RendererCallbacks } from './renderer-6sFRupj0.js';
+export { C as CHART_STORAGE_KEY, g as RenderedBookableLabelEvidence, a as RenderedFreeTextEvidence, h as RenderedGAAreaEvidence, i as RenderedHierarchyLabelEvidence, j as RenderedLabelHiddenReason, k as RenderedRowLabelEvidence, l as RendererHoverDetails, m as RendererMinimapSeat, n as RendererMinimapSection, o as SeatMarkKind } from './renderer-6sFRupj0.js';
+import './segmentedRowModel-DbP7pWUk.js';
 
 /**
  * Host chrome over the canvas, and the box that leaves for camera framing.
@@ -987,6 +987,173 @@ declare function createRenderer(container: HTMLDivElement, opts?: RendererOption
  */
 declare function compactRowLabel(rowLabel: string, sectionLabel: string | undefined): string;
 
+/**
+ * The access needs THIS chart actually offers, with live free counts.
+ *
+ * The accessibility sheet used to render the whole twelve-key taxonomy on
+ * every event, so a buyer at a venue with nothing but wheelchair bays was
+ * offered "CART live-caption view" and "Sign-language view" — chips that
+ * filter to an empty map. Offering a provision that does not exist is worse
+ * than a short list: it reads as a venue that has it and has sold out of it.
+ *
+ * So the list is derived from the seats the chart authored. A key appears
+ * because at least one seat carries it — including a key whose seats are all
+ * gone, which is shown at zero and disabled rather than dropped, so the
+ * difference between "this venue has none" and "this venue's are taken" stays
+ * visible.
+ *
+ * `count` is FREE seats only, and is counted exactly the way
+ * `sectionAccessibleFreeCount` counts them (status `free`, then the seat's own
+ * accommodation set) — one definition of "available accessible seating" across
+ * the overview blocks, the section card and this list.
+ */
+
+/** One provision the event offers, and how many of it are still free. */
+interface PickerAccessNeed {
+    key: AccessibilityType;
+    /** Free seats carrying this accommodation right now. May be 0. */
+    count: number;
+}
+/**
+ * The provisions on this chart, in the taxonomy's own order.
+ *
+ * Taxonomy order rather than count order on purpose: the sheet is a stable
+ * control, and a list that reshuffles itself as other buyers take seats is one
+ * the returning buyer has to re-read every time.
+ */
+declare function accessNeedsFor(seats: Iterable<ExpandedSeat>, statusOf: (seatId: string) => string): PickerAccessNeed[];
+
+/**
+ * What an availability refresh means for the buyer who is looking at the map.
+ *
+ * A refresh re-reads OTHER buyers' inventory. It is not a chance to re-decide
+ * what this buyer has: his selection stays selected, his hold keeps its
+ * countdown, his cart total does not move, and the camera never travels. The
+ * only thing a refresh may take away is something that was never his.
+ *
+ * That distinction is the whole reason this is a module rather than three
+ * lines inside `applySeatsMap`. The authoritative snapshot reports a seat the
+ * buyer is holding as `held` — held BY HIM — and a naive reader would mark it
+ * unavailable and drop it out of his own cart on every resume. So the hold's
+ * labels are subtracted first, and only what is left can be lost.
+ *
+ * WHAT ENDS A HOLD IS THE CLOCK, NOT THE SEAT STATUS. `held` on the wire says
+ * nothing about WHO holds it, so it can never prove a hold is still ours — and
+ * reading it as proof is how a buyer kept a DEAD hold with a LIVE countdown and
+ * only found out when checkout failed. The hold carries its own `expiresAt`;
+ * that is authoritative and needs no ownership information at all. Once it has
+ * passed (or the server has told us the session's hold is gone), the hold IS
+ * lapsed whatever the seats read, and availability only decides which of those
+ * seats can be taken back.
+ *
+ * Kept pure (labels and a status lookup, no renderer, no controller) so both
+ * buyer surfaces — the native bridge picker and the web widget — reconcile
+ * through the SAME code and cannot drift into two answers.
+ */
+/** What a refresh changed for this buyer, and what he can do about it. */
+interface AvailabilityRefreshOutcome {
+    /**
+     * Labels the buyer had SELECTED but never held, which somebody else has
+     * since taken. The caller deselects these and surfaces them through whatever
+     * lost-seat path it already has.
+     */
+    lost: string[];
+    /** The buyer's own hold is gone server-side — it lapsed while he was away. */
+    holdLapsed: boolean;
+    /** The labels that lapsed hold covered. Empty unless {@link holdLapsed}. */
+    lapsedLabels: string[];
+    /**
+     * The lapsed labels that are STILL free — the exact seats a "select them
+     * again" offer may re-take. Always a subset of {@link lapsedLabels}, and
+     * always read from the just-refreshed statuses rather than local memory.
+     */
+    recoverable: string[];
+}
+interface AvailabilityRefreshInput {
+    /** Public labels currently selected on the map. */
+    selection: readonly string[];
+    /** Public labels the buyer's OWN hold covers (empty when he holds nothing). */
+    holdLabels: readonly string[];
+    /** Whether a hold is open locally. `false` short-circuits every hold answer. */
+    holdActive: boolean;
+    /** Live status of one label after the refresh has been applied. */
+    statusOf: (label: string) => string;
+    /**
+     * Epoch ms at which the buyer's OWN hold expires — the authoritative end of
+     * it. Once `now` is past this (plus {@link HOLD_CLOCK_SKEW_MS}) the hold has
+     * lapsed no matter what the seats read. `null`/omitted only when a caller
+     * genuinely has no expiry, and then the clock decides nothing.
+     */
+    holdExpiresAt?: number | null;
+    /**
+     * The server's own answer to "is this session's hold still open?", for the
+     * surfaces that have one (a snapshot carrying hold ownership, or a 404/410
+     * on the hold id). `false` lapses the hold on its own; `undefined` means
+     * nobody asked, which is not the same as `true`.
+     */
+    serverHoldActive?: boolean;
+    /** Injectable clock. Defaults to `Date.now()`. */
+    now?: number;
+}
+/**
+ * How far past `expiresAt` a hold is still given the benefit of the doubt.
+ *
+ * The buyer's device clock is not the server's. A few seconds of skew must not
+ * turn a hold the server still honours into a lapse notice, and a few seconds
+ * of delay costs a returning buyer nothing — the notice is about a hold that
+ * ended minutes ago in every real case.
+ */
+declare const HOLD_CLOCK_SKEW_MS = 5000;
+declare const EMPTY_AVAILABILITY_REFRESH: AvailabilityRefreshOutcome;
+/**
+ * Has the buyer's own hold ended? Answered WITHOUT looking at seat status.
+ *
+ * Three sufficient signals, in the order they can be trusted:
+ *
+ *  1. The hold's own expiry has passed (plus {@link HOLD_CLOCK_SKEW_MS}). This
+ *     needs no ownership information and is the one that closes the hole: a
+ *     lapsed hold whose seats another buyer grabbed reads `held` on every one
+ *     of its labels, which used to be read as "still ours".
+ *  2. The server says the session has no open hold.
+ *  3. NOT ONE of its labels still reads `held`. Kept because it is genuinely
+ *     right — nobody at all is holding these seats, so neither are we — and it
+ *     catches a hold released server-side before its expiry.
+ *
+ * The conservatism that survives is the one that was always correct: while the
+ * expiry has NOT passed and the server has not said otherwise, a label reading
+ * `held` never declares a lapse, because that `held` is most likely us.
+ */
+declare function holdHasLapsed(input: AvailabilityRefreshInput): boolean;
+/**
+ * Read a freshly applied status map on the buyer's behalf.
+ *
+ * Whether the hold ended is {@link holdHasLapsed}'s answer, and it is decided
+ * before a single status is consulted. Availability then only sorts the lapsed
+ * seats: `recoverable` is what is free NOW and can honestly be offered back,
+ * and everything else — booked, or `held` by whoever took it — is simply gone,
+ * which is exactly the "could not be recovered" count the copy reports.
+ */
+declare function reconcileAvailability(input: AvailabilityRefreshInput): AvailabilityRefreshOutcome;
+/** Did anything at all change for this buyer? */
+declare function refreshChangedSomething(outcome: AvailabilityRefreshOutcome): boolean;
+/** How a lapsed hold's seats came back — what the buyer is told, in one word. */
+type HoldRecoveryShape = 'all' | 'partial' | 'none';
+declare function holdRecoveryShape(outcome: AvailabilityRefreshOutcome): HoldRecoveryShape;
+/**
+ * Should an expiry poll wait another beat before declaring the hold over?
+ *
+ * `PickerController.expireActiveHold` fires AT the hold's expiry and re-reads
+ * the authoritative snapshot. It used to keep polling for as long as any of
+ * the hold's labels still read `held`, on the same "held without saying by
+ * whom" reasoning — which meant a hold whose seats another buyer took the
+ * instant they were released polled FOREVER, and the countdown never ended.
+ *
+ * Past the expiry, `held` proves nothing and stops earning a delay. All that
+ * is left is {@link HOLD_CLOCK_SKEW_MS} of benefit of the doubt for a device
+ * clock that runs ahead of the server's.
+ */
+declare function shouldWaitForHoldExpiry(expiresAt: number, anyStillHeld: boolean, now?: number): boolean;
+
 /**
  * Public host contracts for the framework-agnostic buyer picker.
  *
@@ -1334,6 +1501,15 @@ interface PickerCallbacks extends RendererCallbacks {
     onBook?: (bookingRef: string) => void;
     /** Any live seat-status change arrived (delta or snapshot) — e.g. to recount "N left". */
     onStatusChange?: () => void;
+    /**
+     * An availability refresh finished — what it changed for THIS buyer.
+     *
+     * Fires after {@link PickerController.refreshAvailability} has already
+     * deselected anything lost and cleared a lapsed hold, so a host reads it to
+     * decide what to SAY, never to reconcile state itself. The outcome is empty
+     * on the common path where nothing of the buyer's changed.
+     */
+    onAvailabilityRefresh?: (outcome: AvailabilityRefreshOutcome) => void;
     /**
      * Mouse hover moved onto a seat (null on hover-out) — the seat enriched with
      * category label/color, resolved price and live status, ready for a tooltip.
@@ -1535,10 +1711,8 @@ declare class PickerController {
     private reconnectTimer;
     private attempt;
     private closed;
-    /** Bound visibilitychange listener (buyer catch-up on tab regain). Kept on the
-     *  instance so destroy() can detach it; null when not attached (guards double
-     *  mounts / non-DOM environments). */
-    private onVisibilityChange;
+    /** Detach for the tab-regain catch-up listener; null when not attached. */
+    private detachVisibility;
     private hold_;
     private liveStatuses;
     /**
@@ -1730,19 +1904,12 @@ declare class PickerController {
      *  flag — gates the buyer widget's "★ Best seats" premium quick-pick (chip is
      *  present-only, exactly like the accessibility filter chips). */
     hasPremiumSeats(): boolean;
-    /** Zones which still own visible buyer inventory, in authored order. */
+    /** Zones which still own visible buyer inventory — ./pickerPremiumBlock. */
     getBestAvailableZones(): Array<{
         id: string;
         label: string;
     }>;
-    /**
-     * Client-side premium pre-pass: find the best contiguous block of `qty`
-     * PREMIUM-flagged free seats (orphan-avoiding, closest to the focal point)
-     * using the local seat geometry + live availability, mirroring the server's
-     * held-back exclusion via the visible (hidden-stripped) chart and current
-     * seat status. Returns a FULL premium block of `qty`, or null when none
-     * exists (the caller then falls back to the normal server pick).
-     */
+    /** Client-side premium pre-pass — see ./pickerPremiumBlock. */
     private pickPremiumBlock;
     /**
      * Server-picks `qty` best free seats and holds them atomically. Throws on
@@ -1990,18 +2157,31 @@ declare class PickerController {
      */
     refresh(): Promise<void>;
     /**
-     * Buyer catch-up on tab regain. While a tab is hidden Chrome pauses rAF, so
-     * seat-status deltas that arrived over the WS mutated the scene graph but the
-     * canvas colors never repainted. When the tab becomes visible again we (1)
-     * resnapshot to pull authoritative state for anything the socket may have
-     * missed while backgrounded, then (2) forceDraw() a synchronous repaint so the
-     * seat colors are correct immediately rather than on the next incidental draw.
+     * Re-read OTHER buyers' inventory, without disturbing this buyer's own.
      *
-     * Attached once per mount; guarded against double-attach and non-DOM
-     * environments; detached in destroy() (no leaks).
+     * The refresh a returning buyer gets: seats sold or held by someone else
+     * while he was on the checkout screen stop looking free, so he cannot tap
+     * one that is already gone. What is HIS is untouched — selection, hold
+     * countdown, cart total, camera and rung all stay. His own held seats read
+     * `held` on the wire because HE holds them — so whether HIS hold ended is
+     * decided by its own `expiresAt`, never by a status. See ./availabilityRefresh.
+     *
+     * Coalesced rather than forced: it joins an availability read already in
+     * flight, so every re-entry point a host has (app resume, route resume, tab
+     * regain) can call it without multiplying requests.
      */
-    private attachVisibilityListener;
-    private detachVisibilityListener;
+    refreshAvailability(): Promise<AvailabilityRefreshOutcome>;
+    /** Access needs this chart offers, with live free counts — ./accessNeeds. */
+    getAccessNeeds(): PickerAccessNeed[];
+    /**
+     * Buyer catch-up on tab regain — see ./pickerVisibility for the listener and
+     * why the order (authoritative statuses, then a synchronous draw) matters.
+     *
+     * It goes through {@link refreshAvailability}, not a bare resnapshot, so a
+     * seat another buyer took while the tab was hidden leaves this buyer's
+     * selection rather than repainting under it. Attached once, detached in destroy().
+     */
+    private attachVisibility;
     /**
      * The sink a transport-owned v1 client pushes into.
      *
@@ -2024,6 +2204,29 @@ declare class PickerController {
     private scheduleReconnect;
 }
 
+/**
+ * Tab-regain catch-up, as a listener the controller owns but does not contain.
+ *
+ * While a tab is hidden Chrome pauses rAF, so seat-status deltas that arrived
+ * over the socket mutated the scene graph while the canvas never repainted.
+ * Coming back visible therefore needs two things in order: authoritative
+ * statuses for whatever the socket missed, then a synchronous draw so the
+ * colours are right immediately rather than at the next incidental paint.
+ *
+ * Extracted from `PickerController` (2026-08-28) so the same attach/detach
+ * discipline can be reused by the web widget's wider "regained attention"
+ * wiring — visibility AND window focus — without a second copy of the
+ * double-attach and non-DOM guards.
+ */
+/**
+ * Call `onVisible` each time the document becomes visible again.
+ *
+ * Returns the detach function. In a non-DOM environment (tests, SSR, a native
+ * WebView shim without `document`) nothing is attached and the returned
+ * function is a no-op, so callers need no environment check of their own.
+ */
+declare function attachVisibilityCatchUp(onVisible: () => void): () => void;
+
 /**
  * Synthetic view-from-seat panorama, generated from chart geometry alone.
  *
@@ -2270,4 +2473,4 @@ declare function formatMinor(minor: number, currency?: string, locale?: string):
 /** Bare symbol for input adornments ("€", "$", "₹"). */
 declare function currencySymbol(currency?: string): string;
 
-export { AccessibilityType, CURRENCY_CHOICES, CategoryTier, ChartDeliveryPerformance, ChartDoc, DEFAULT_CURRENCY, type Dict, type Direction, EventConfigurationRef, EventConfigurationVersion, ExpandedSeat, FloorLabelStyle, GAAreaState, type HoldConflict, type HoldInfo, type HoldSelectionRequest, type HoldServerItem, ISeatmapRenderer, LOCALE_NAMES, type Locale, LodRung, type MoneyFormatOptions, type PanoramaResult, type PickerCallbacks, PickerController, type PickerGAArea, type PickerMapTheme, type PickerOptions, type PickerRealtimeConnection, type PickerRealtimeSink, type PickerRenderPerformanceProfile, type PickerSeat, PickerSelectionError, type PickerSelectionValidator, type PickerSelectionValidity, type PickerSelectionViolation, type PickerStatusChange, type PickerTransport, Point, RendererCallbacks, RendererMinimapSnapshot, RendererOptions, RendererQualityEvidence, RendererViewMode, SUPPORTED_LOCALES, SeatCommercialAttributes, type SeatHoverDetails, SeatMark, SeatStatus, SeatmapRenderer, type SectionCategory, type SectionSummary, TRANSLATED_LOCALES, type TableSelectionDetails, compactRowLabel, createRenderer, currencyExponent, currencySymbol, formatDate, formatMinor, formatMoney, fromMinorUnits, generateSeatPanorama, generateSeatThumb, getLocale, isLocaleLoaded, loadLocale, localeDirection, resolveLocale, setLocale, setMoneyLocale, setStringOverrides, t, tCount };
+export { AccessibilityType, type AvailabilityRefreshInput, type AvailabilityRefreshOutcome, CURRENCY_CHOICES, CategoryTier, ChartDeliveryPerformance, ChartDoc, DEFAULT_CURRENCY, type Dict, type Direction, EMPTY_AVAILABILITY_REFRESH, EventConfigurationRef, EventConfigurationVersion, ExpandedSeat, FloorLabelStyle, GAAreaState, HOLD_CLOCK_SKEW_MS, type HoldConflict, type HoldInfo, type HoldRecoveryShape, type HoldSelectionRequest, type HoldServerItem, ISeatmapRenderer, LOCALE_NAMES, type Locale, LodRung, type MoneyFormatOptions, type PanoramaResult, type PickerAccessNeed, type PickerCallbacks, PickerController, type PickerGAArea, type PickerMapTheme, type PickerOptions, type PickerRealtimeConnection, type PickerRealtimeSink, type PickerRenderPerformanceProfile, type PickerSeat, PickerSelectionError, type PickerSelectionValidator, type PickerSelectionValidity, type PickerSelectionViolation, type PickerStatusChange, type PickerTransport, Point, RendererCallbacks, RendererMinimapSnapshot, RendererOptions, RendererQualityEvidence, RendererViewMode, SUPPORTED_LOCALES, SeatCommercialAttributes, type SeatHoverDetails, SeatMark, SeatStatus, SeatmapRenderer, type SectionCategory, type SectionSummary, TRANSLATED_LOCALES, type TableSelectionDetails, accessNeedsFor, attachVisibilityCatchUp, compactRowLabel, createRenderer, currencyExponent, currencySymbol, formatDate, formatMinor, formatMoney, fromMinorUnits, generateSeatPanorama, generateSeatThumb, getLocale, holdHasLapsed, holdRecoveryShape, isLocaleLoaded, loadLocale, localeDirection, reconcileAvailability, refreshChangedSomething, resolveLocale, setLocale, setMoneyLocale, setStringOverrides, shouldWaitForHoldExpiry, t, tCount };