@seatlayer/core 0.10.1 → 0.11.0

package/dist/index.d.cts

@@ -383,6 +383,13 @@ interface RendererCallbacks {
     onDeckTap?: (floorId: string) => void;
     /** Fired after any pan/zoom/resize settles — re-anchor screen-space overlays. */
     onViewChange?: () => void;
+    /**
+     * Organizer manage-mode only (`manageMode` + `marqueeSelect`): fired on
+     * pointer-UP after a rubber-band marquee drag, or a ⌘A/Escape bulk shortcut,
+     * with the FULL current selection (selectable seats only). The host toolbar
+     * reads this to drive bulk block/unblock. Never fires when manageMode is off.
+     */
+    onMarquee?: (seats: ExpandedSeat[]) => void;
 }
 /** Far-zoom level-of-detail rung: whole zones → section blocks → individual seats. */
 type LodRung = 'zones' | 'sections' | 'seats';
@@ -402,6 +409,21 @@ interface RendererOptions extends RendererCallbacks {
     /** ISO 4217 currency for on-map prices ("FROM …"); defaults to money.DEFAULT_CURRENCY.
      *  Locale for grouping/symbol placement comes from the active i18n locale. */
     currency?: string;
+    /**
+     * Organizer manage surface (SDK SeatManager). Opt-in — enables the manage-mode
+     * gestures (marquee, ⌘A/Escape) and the bulk-selection helpers. Buyer pan /
+     * pinch / tap and every existing code path are byte-identical when this is
+     * false (every manage branch is gated on it). Default false.
+     */
+    manageMode?: boolean;
+    /**
+     * When `manageMode` is on, a mouse/pen primary-button drag at the seats rung
+     * draws a rubber-band marquee that bulk-selects the seats it covers (emitting
+     * `onMarquee` on pointer-up) instead of panning. Touch keeps single-finger
+     * pan (pinch to zoom); a middle-button drag pans with a mouse. Disabled below
+     * the seats rung (zoom in first). No effect unless `manageMode` is also set.
+     */
+    marqueeSelect?: boolean;
 }
 interface ISeatmapRenderer {
     /** Replace the chart. Resets selection and statuses, zooms to fit.
@@ -411,9 +433,32 @@ interface ISeatmapRenderer {
     }): void;
     /** Bulk status update; re-renders affected seats only. */
     setStatus(seatIds: string[], status: SeatStatus): void;
+    /**
+     * SYNCHRONOUS repaint that bypasses requestAnimationFrame. Konva's batchDraw()
+     * (used by setStatus and friends) schedules the actual paint on the next rAF
+     * tick, which Chrome throttles/pauses on hidden, backgrounded, or occluded
+     * tabs — so a seat-status delta updates the scene graph but the pixels never
+     * change until the tab is foregrounded again. forceDraw() paints the affected
+     * layers immediately (Layer.draw() is synchronous) and flushes any pending
+     * cache-debounce, so a caller (visibilitychange catch-up, or an opted-in
+     * always-live board) can guarantee the canvas reflects current state
+     * regardless of tab visibility. No-op difference in the foreground.
+     */
+    forceDraw(): void;
     getStatus(seatId: string): SeatStatus;
     getSelection(): ExpandedSeat[];
     clearSelection(): void;
+    /**
+     * Manage-mode bulk selection helpers (no-op / empty unless `manageMode`).
+     * They select the matching SELECTABLE seats (respecting `selectableStatuses`
+     * + closed sections), union with the current selection, and return the seats
+     * they added — the SDK SeatManager expands category/row/section picks to
+     * labels and drives one batched block/unblock from them.
+     */
+    selectAllSelectable?(): ExpandedSeat[];
+    selectByLabels?(labels: string[]): ExpandedSeat[];
+    /** Selectable seats belonging to a section OR zone id (no selection side-effect). */
+    getSelectableInSection?(sectionId: string): ExpandedSeat[];
     /** Programmatic deselect of specific seats (e.g. chip × in the cart). */
     deselect(seatIds: string[]): void;
     /**
@@ -794,6 +839,13 @@ declare class SeatmapRenderer implements ISeatmapRenderer {
     private panLast;
     /** Cumulative gesture movement in px — clicks are suppressed after a real pan/pinch. */
     private moved;
+    /**
+     * Manage-mode rubber-band marquee (option-gated). `start`/`cur` are WORLD-space
+     * points (overlayLayer rides the stage transform); `rect` is the on-canvas
+     * selection band. Null except during an active manage-mode drag.
+     */
+    private marquee;
+    private marqueeCur;
     constructor(container: HTMLDivElement, options?: RendererOptions);
     setChart(doc: ChartDoc, opts?: {
         floorId?: string;
@@ -818,6 +870,30 @@ declare class SeatmapRenderer implements ISeatmapRenderer {
     getSelection(): ExpandedSeat[];
     clearSelection(): void;
     deselect(seatIds: string[]): void;
+    /** Select every selectable seat on the chart (⌘A). Returns the added seats. */
+    selectAllSelectable(): ExpandedSeat[];
+    /** Select the selectable seats matching these public labels (category/row/
+     *  section bulk resolves to labels host-side). Returns the newly added seats. */
+    selectByLabels(labels: string[]): ExpandedSeat[];
+    /** Selectable seats in a section OR zone id — pure read (no selection change). */
+    getSelectableInSection(sectionId: string): ExpandedSeat[];
+    /**
+     * Union `ids` into the selection in one batched pass. Beyond MARQUEE_RING_CAP
+     * total selected we skip the per-seat ring nodes (fill paint still marks the
+     * seats) so a whole-arena select doesn't spawn thousands of Konva shapes.
+     * Returns the full current selection.
+     */
+    private selectMany;
+    private beginMarquee;
+    private updateMarquee;
+    private cancelMarquee;
+    /**
+     * Pointer-up: hit-test the marquee world-rect against the in-memory seat
+     * centres (NOT the Konva hit-graph — that's a cached bitmap when zoomed and
+     * far slower), keep only SELECTABLE seats, union them into the selection and
+     * fire `onMarquee`. A near-zero drag reads as a click: clear the selection.
+     */
+    private finishMarquee;
     flashSeat(seatId: string, color?: string): void;
     private onKeyDown;
     /** Nearest seat from `fromId` in a cardinal direction (aligned + close wins). */
@@ -1109,7 +1185,22 @@ declare class SeatmapRenderer implements ISeatmapRenderer {
     /** rAF-coalesced `onViewChange` — at most one host callback per animation frame. */
     private scheduleViewChange;
     private updateLOD;
+    /** Rebuild the seat-layer bitmap synchronously (no paint). Shared by the
+     *  debounced cacheSeatLayer() and the synchronous forceDraw() catch-up. */
+    private rebuildSeatCache;
     private cacheSeatLayer;
+    /**
+     * SYNCHRONOUS repaint that bypasses requestAnimationFrame — see the
+     * ISeatmapRenderer.forceDraw() contract. Chrome pauses rAF (and therefore
+     * Konva's batchDraw) on hidden/backgrounded/occluded tabs, so seat-status
+     * deltas applied via setStatus() mutate the scene graph but never reach the
+     * canvas until the tab is foregrounded. This flushes the cache-debounce and
+     * paints every layer setStatus() can touch, immediately.
+     *
+     * Additive: the foreground path never calls this, so foreground behaviour is
+     * byte-identical.
+     */
+    forceDraw(): void;
     private updateLabels;
     private handleResize;
     private startFpsLoop;
@@ -1280,6 +1371,18 @@ interface PickerOptions extends PickerCallbacks {
     flashOnLiveChange?: boolean;
     /** Start in colorblind-safe rendering (Okabe-Ito hues + hollow booked seats). */
     colorblindSafe?: boolean;
+    /**
+     * Keep painting seat-status deltas even while the tab is hidden/backgrounded.
+     *
+     * Default FALSE — the buyer widget stays efficient: it lets rAF stay paused
+     * while hidden and does a single synchronous catch-up repaint on regain (the
+     * visibilitychange handler resnapshots + forceDraw()s). Set TRUE only for an
+     * always-live surface — the future organizer control-room board — where a
+     * backgrounded monitor must keep repainting; then each delta calls
+     * renderer.forceDraw() when the tab is hidden. Purely a paint hint; enforcement
+     * and the WS protocol are identical either way.
+     */
+    keepLiveWhileHidden?: boolean;
 }
 declare class PickerController {
     private readonly opts;
@@ -1305,6 +1408,10 @@ 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;
     private hold_;
     private liveStatuses;
     private currency;
@@ -1498,6 +1605,19 @@ declare class PickerController {
     private applySeatsMap;
     private clearBookedHoldIfSettled;
     private resnapshot;
+    /**
+     * 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.
+     *
+     * Attached once per mount; guarded against double-attach and non-DOM
+     * environments; detached in destroy() (no leaks).
+     */
+    private attachVisibilityListener;
+    private detachVisibilityListener;
     private connect;
     private scheduleReconnect;
 }

package/dist/index.d.ts

@@ -383,6 +383,13 @@ interface RendererCallbacks {
     onDeckTap?: (floorId: string) => void;
     /** Fired after any pan/zoom/resize settles — re-anchor screen-space overlays. */
     onViewChange?: () => void;
+    /**
+     * Organizer manage-mode only (`manageMode` + `marqueeSelect`): fired on
+     * pointer-UP after a rubber-band marquee drag, or a ⌘A/Escape bulk shortcut,
+     * with the FULL current selection (selectable seats only). The host toolbar
+     * reads this to drive bulk block/unblock. Never fires when manageMode is off.
+     */
+    onMarquee?: (seats: ExpandedSeat[]) => void;
 }
 /** Far-zoom level-of-detail rung: whole zones → section blocks → individual seats. */
 type LodRung = 'zones' | 'sections' | 'seats';
@@ -402,6 +409,21 @@ interface RendererOptions extends RendererCallbacks {
     /** ISO 4217 currency for on-map prices ("FROM …"); defaults to money.DEFAULT_CURRENCY.
      *  Locale for grouping/symbol placement comes from the active i18n locale. */
     currency?: string;
+    /**
+     * Organizer manage surface (SDK SeatManager). Opt-in — enables the manage-mode
+     * gestures (marquee, ⌘A/Escape) and the bulk-selection helpers. Buyer pan /
+     * pinch / tap and every existing code path are byte-identical when this is
+     * false (every manage branch is gated on it). Default false.
+     */
+    manageMode?: boolean;
+    /**
+     * When `manageMode` is on, a mouse/pen primary-button drag at the seats rung
+     * draws a rubber-band marquee that bulk-selects the seats it covers (emitting
+     * `onMarquee` on pointer-up) instead of panning. Touch keeps single-finger
+     * pan (pinch to zoom); a middle-button drag pans with a mouse. Disabled below
+     * the seats rung (zoom in first). No effect unless `manageMode` is also set.
+     */
+    marqueeSelect?: boolean;
 }
 interface ISeatmapRenderer {
     /** Replace the chart. Resets selection and statuses, zooms to fit.
@@ -411,9 +433,32 @@ interface ISeatmapRenderer {
     }): void;
     /** Bulk status update; re-renders affected seats only. */
     setStatus(seatIds: string[], status: SeatStatus): void;
+    /**
+     * SYNCHRONOUS repaint that bypasses requestAnimationFrame. Konva's batchDraw()
+     * (used by setStatus and friends) schedules the actual paint on the next rAF
+     * tick, which Chrome throttles/pauses on hidden, backgrounded, or occluded
+     * tabs — so a seat-status delta updates the scene graph but the pixels never
+     * change until the tab is foregrounded again. forceDraw() paints the affected
+     * layers immediately (Layer.draw() is synchronous) and flushes any pending
+     * cache-debounce, so a caller (visibilitychange catch-up, or an opted-in
+     * always-live board) can guarantee the canvas reflects current state
+     * regardless of tab visibility. No-op difference in the foreground.
+     */
+    forceDraw(): void;
     getStatus(seatId: string): SeatStatus;
     getSelection(): ExpandedSeat[];
     clearSelection(): void;
+    /**
+     * Manage-mode bulk selection helpers (no-op / empty unless `manageMode`).
+     * They select the matching SELECTABLE seats (respecting `selectableStatuses`
+     * + closed sections), union with the current selection, and return the seats
+     * they added — the SDK SeatManager expands category/row/section picks to
+     * labels and drives one batched block/unblock from them.
+     */
+    selectAllSelectable?(): ExpandedSeat[];
+    selectByLabels?(labels: string[]): ExpandedSeat[];
+    /** Selectable seats belonging to a section OR zone id (no selection side-effect). */
+    getSelectableInSection?(sectionId: string): ExpandedSeat[];
     /** Programmatic deselect of specific seats (e.g. chip × in the cart). */
     deselect(seatIds: string[]): void;
     /**
@@ -794,6 +839,13 @@ declare class SeatmapRenderer implements ISeatmapRenderer {
     private panLast;
     /** Cumulative gesture movement in px — clicks are suppressed after a real pan/pinch. */
     private moved;
+    /**
+     * Manage-mode rubber-band marquee (option-gated). `start`/`cur` are WORLD-space
+     * points (overlayLayer rides the stage transform); `rect` is the on-canvas
+     * selection band. Null except during an active manage-mode drag.
+     */
+    private marquee;
+    private marqueeCur;
     constructor(container: HTMLDivElement, options?: RendererOptions);
     setChart(doc: ChartDoc, opts?: {
         floorId?: string;
@@ -818,6 +870,30 @@ declare class SeatmapRenderer implements ISeatmapRenderer {
     getSelection(): ExpandedSeat[];
     clearSelection(): void;
     deselect(seatIds: string[]): void;
+    /** Select every selectable seat on the chart (⌘A). Returns the added seats. */
+    selectAllSelectable(): ExpandedSeat[];
+    /** Select the selectable seats matching these public labels (category/row/
+     *  section bulk resolves to labels host-side). Returns the newly added seats. */
+    selectByLabels(labels: string[]): ExpandedSeat[];
+    /** Selectable seats in a section OR zone id — pure read (no selection change). */
+    getSelectableInSection(sectionId: string): ExpandedSeat[];
+    /**
+     * Union `ids` into the selection in one batched pass. Beyond MARQUEE_RING_CAP
+     * total selected we skip the per-seat ring nodes (fill paint still marks the
+     * seats) so a whole-arena select doesn't spawn thousands of Konva shapes.
+     * Returns the full current selection.
+     */
+    private selectMany;
+    private beginMarquee;
+    private updateMarquee;
+    private cancelMarquee;
+    /**
+     * Pointer-up: hit-test the marquee world-rect against the in-memory seat
+     * centres (NOT the Konva hit-graph — that's a cached bitmap when zoomed and
+     * far slower), keep only SELECTABLE seats, union them into the selection and
+     * fire `onMarquee`. A near-zero drag reads as a click: clear the selection.
+     */
+    private finishMarquee;
     flashSeat(seatId: string, color?: string): void;
     private onKeyDown;
     /** Nearest seat from `fromId` in a cardinal direction (aligned + close wins). */
@@ -1109,7 +1185,22 @@ declare class SeatmapRenderer implements ISeatmapRenderer {
     /** rAF-coalesced `onViewChange` — at most one host callback per animation frame. */
     private scheduleViewChange;
     private updateLOD;
+    /** Rebuild the seat-layer bitmap synchronously (no paint). Shared by the
+     *  debounced cacheSeatLayer() and the synchronous forceDraw() catch-up. */
+    private rebuildSeatCache;
     private cacheSeatLayer;
+    /**
+     * SYNCHRONOUS repaint that bypasses requestAnimationFrame — see the
+     * ISeatmapRenderer.forceDraw() contract. Chrome pauses rAF (and therefore
+     * Konva's batchDraw) on hidden/backgrounded/occluded tabs, so seat-status
+     * deltas applied via setStatus() mutate the scene graph but never reach the
+     * canvas until the tab is foregrounded. This flushes the cache-debounce and
+     * paints every layer setStatus() can touch, immediately.
+     *
+     * Additive: the foreground path never calls this, so foreground behaviour is
+     * byte-identical.
+     */
+    forceDraw(): void;
     private updateLabels;
     private handleResize;
     private startFpsLoop;
@@ -1280,6 +1371,18 @@ interface PickerOptions extends PickerCallbacks {
     flashOnLiveChange?: boolean;
     /** Start in colorblind-safe rendering (Okabe-Ito hues + hollow booked seats). */
     colorblindSafe?: boolean;
+    /**
+     * Keep painting seat-status deltas even while the tab is hidden/backgrounded.
+     *
+     * Default FALSE — the buyer widget stays efficient: it lets rAF stay paused
+     * while hidden and does a single synchronous catch-up repaint on regain (the
+     * visibilitychange handler resnapshots + forceDraw()s). Set TRUE only for an
+     * always-live surface — the future organizer control-room board — where a
+     * backgrounded monitor must keep repainting; then each delta calls
+     * renderer.forceDraw() when the tab is hidden. Purely a paint hint; enforcement
+     * and the WS protocol are identical either way.
+     */
+    keepLiveWhileHidden?: boolean;
 }
 declare class PickerController {
     private readonly opts;
@@ -1305,6 +1408,10 @@ 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;
     private hold_;
     private liveStatuses;
     private currency;
@@ -1498,6 +1605,19 @@ declare class PickerController {
     private applySeatsMap;
     private clearBookedHoldIfSettled;
     private resnapshot;
+    /**
+     * 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.
+     *
+     * Attached once per mount; guarded against double-attach and non-DOM
+     * environments; detached in destroy() (no leaks).
+     */
+    private attachVisibilityListener;
+    private detachVisibilityListener;
     private connect;
     private scheduleReconnect;
 }