@seatlayer/core 0.10.0 → 0.10.2

package/dist/index.d.cts

@@ -411,6 +411,18 @@ 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;
@@ -1035,6 +1047,32 @@ declare class SeatmapRenderer implements ISeatmapRenderer {
      */
     private resolveSelectionColor;
     private setSelected;
+    /**
+     * The stage scale `focusRegion(id)` would settle at — i.e. the zoom that
+     * frames this section in the current viewport. Used to decide whether
+     * redirecting a seat tap to section-focus would actually zoom in FURTHER, or
+     * whether the section already fills the viewport (small container) so the tap
+     * must fall through and pick.
+     */
+    private sectionFrameScale;
+    /**
+     * Resolve a seat tap: honour the 3D deck-drill and the AXS seat-pick gate,
+     * then toggle. The gate (§4) redirects small on-screen seats to section-focus
+     * to avoid blind mis-picks at overview scales — but ONLY when focusing would
+     * zoom the seat up to a safe size. If we're already focused on the section, or
+     * the section already fills the viewport (a narrow — OR even a wide — container
+     * frames a big section BELOW LABEL_SCALE), redirecting is a no-op that would
+     * leave the seat permanently unpickable (§5 `picking-gate-unreachable`), so we
+     * fall through and PICK. This is the invariant: seats are never unpickable.
+     */
+    private handleSeatTap;
+    /**
+     * Nearest SELECTABLE seat whose centre is within `slopPx` (screen space) of a
+     * seat circle edge, or null. Enlarges the effective tap target for small seats
+     * so a near-miss on mobile still lands on the intended seat, without ever
+     * hijacking a clean tap on empty space beyond the slop.
+     */
+    private nearestSeatToScreen;
     private wireInteraction;
     /**
      * Which deck (floor) a screen tap landed on in the 3D stacked overview. The
@@ -1083,7 +1121,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;
@@ -1254,6 +1307,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;
@@ -1279,6 +1344,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;
@@ -1472,6 +1541,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

@@ -411,6 +411,18 @@ 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;
@@ -1035,6 +1047,32 @@ declare class SeatmapRenderer implements ISeatmapRenderer {
      */
     private resolveSelectionColor;
     private setSelected;
+    /**
+     * The stage scale `focusRegion(id)` would settle at — i.e. the zoom that
+     * frames this section in the current viewport. Used to decide whether
+     * redirecting a seat tap to section-focus would actually zoom in FURTHER, or
+     * whether the section already fills the viewport (small container) so the tap
+     * must fall through and pick.
+     */
+    private sectionFrameScale;
+    /**
+     * Resolve a seat tap: honour the 3D deck-drill and the AXS seat-pick gate,
+     * then toggle. The gate (§4) redirects small on-screen seats to section-focus
+     * to avoid blind mis-picks at overview scales — but ONLY when focusing would
+     * zoom the seat up to a safe size. If we're already focused on the section, or
+     * the section already fills the viewport (a narrow — OR even a wide — container
+     * frames a big section BELOW LABEL_SCALE), redirecting is a no-op that would
+     * leave the seat permanently unpickable (§5 `picking-gate-unreachable`), so we
+     * fall through and PICK. This is the invariant: seats are never unpickable.
+     */
+    private handleSeatTap;
+    /**
+     * Nearest SELECTABLE seat whose centre is within `slopPx` (screen space) of a
+     * seat circle edge, or null. Enlarges the effective tap target for small seats
+     * so a near-miss on mobile still lands on the intended seat, without ever
+     * hijacking a clean tap on empty space beyond the slop.
+     */
+    private nearestSeatToScreen;
     private wireInteraction;
     /**
      * Which deck (floor) a screen tap landed on in the 3D stacked overview. The
@@ -1083,7 +1121,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;
@@ -1254,6 +1307,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;
@@ -1279,6 +1344,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;
@@ -1472,6 +1541,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.js

@@ -632,6 +632,7 @@ var SEAT_RADIUS = 9;
 var SEAT_LEGIBLE_SCALE = 0.9;
 var CACHE_THRESHOLD = 0.55 * SEAT_LEGIBLE_SCALE;
 var LABEL_SCALE = 1;
+var SEAT_TAP_SLOP_PX = 14;
 var SECTION_PROMINENT_SCALE = 0.45 * SEAT_LEGIBLE_SCALE;
 var BLOCK_MELT_TOP = 0.9 * SEAT_LEGIBLE_SCALE;
 var ZONE_PROMINENT_SCALE = 0.55 * SECTION_PROMINENT_SCALE;
@@ -2533,27 +2534,84 @@ var _SeatmapRenderer = class _SeatmapRenderer {
     }
   }
   // ---- interaction ----------------------------------------------------------
-  wireInteraction() {
-    this.seatLayer.on("click tap", (e) => {
-      if (this.moved > 8) return;
-      const id = seatIdOf(e.target);
-      if (!id) return;
-      if (this.stacked && this.opts.onDeckTap) {
-        const floorId = this.objectFloor.get(this.seatById.get(id)?.rowId ?? "");
-        if (floorId) {
-          this.opts.onDeckTap(floorId);
-          return;
-        }
+  /**
+   * The stage scale `focusRegion(id)` would settle at — i.e. the zoom that
+   * frames this section in the current viewport. Used to decide whether
+   * redirecting a seat tap to section-focus would actually zoom in FURTHER, or
+   * whether the section already fills the viewport (small container) so the tap
+   * must fall through and pick.
+   */
+  sectionFrameScale(id) {
+    const sec = this.sections.find((s) => s.id === id);
+    if (!sec) return this.stage.scaleX();
+    const b = polyBounds(sec.outline);
+    const w = this.stage.width();
+    const h = this.stage.height();
+    const { min, max } = this.zoomBounds();
+    const margin = 1.12;
+    if (b.width <= 0 || b.height <= 0) return this.stage.scaleX();
+    return clamp(Math.min(w / (b.width * margin), h / (b.height * margin)), min, max);
+  }
+  /**
+   * Resolve a seat tap: honour the 3D deck-drill and the AXS seat-pick gate,
+   * then toggle. The gate (§4) redirects small on-screen seats to section-focus
+   * to avoid blind mis-picks at overview scales — but ONLY when focusing would
+   * zoom the seat up to a safe size. If we're already focused on the section, or
+   * the section already fills the viewport (a narrow — OR even a wide — container
+   * frames a big section BELOW LABEL_SCALE), redirecting is a no-op that would
+   * leave the seat permanently unpickable (§5 `picking-gate-unreachable`), so we
+   * fall through and PICK. This is the invariant: seats are never unpickable.
+   */
+  handleSeatTap(id) {
+    if (this.stacked && this.opts.onDeckTap) {
+      const floorId = this.objectFloor.get(this.seatById.get(id)?.rowId ?? "");
+      if (floorId) {
+        this.opts.onDeckTap(floorId);
+        return;
       }
-      if (this.effScale() < LABEL_SCALE && this.sections.length) {
-        const sec = this.seatSection.get(id);
-        if (sec) {
+    }
+    if (this.effScale() < LABEL_SCALE && this.sections.length) {
+      const sec = this.seatSection.get(id);
+      if (sec) {
+        const alreadyFocused = this.focusedSectionId === sec.id;
+        const canZoomInFurther = this.sectionFrameScale(sec.id) > this.stage.scaleX() * 1.02;
+        if (!alreadyFocused && canZoomInFurther) {
           if (this.opts.onSectionTap) this.opts.onSectionTap(sec.id);
           else this.focusSection(sec.id);
           return;
         }
       }
-      this.toggleSeat(id);
+    }
+    this.toggleSeat(id);
+  }
+  /**
+   * Nearest SELECTABLE seat whose centre is within `slopPx` (screen space) of a
+   * seat circle edge, or null. Enlarges the effective tap target for small seats
+   * so a near-miss on mobile still lands on the intended seat, without ever
+   * hijacking a clean tap on empty space beyond the slop.
+   */
+  nearestSeatToScreen(screen, slopPx) {
+    const s = this.stage.scaleX() || 1;
+    const reachWorld = this.seatR + slopPx / s;
+    const world = this.screenToWorld(screen);
+    let best = null;
+    let bestD = reachWorld;
+    for (const seat of this.seats) {
+      if (!this.selection.has(seat.id) && !this.isSelectable(seat.id)) continue;
+      const d = Math.hypot(seat.x - world.x, seat.y - world.y);
+      if (d < bestD) {
+        bestD = d;
+        best = seat.id;
+      }
+    }
+    return best;
+  }
+  wireInteraction() {
+    this.seatLayer.on("click tap", (e) => {
+      if (this.moved > 8) return;
+      const id = seatIdOf(e.target);
+      if (!id) return;
+      this.handleSeatTap(id);
     });
     this.seatLayer.on("mouseover", (e) => {
       const id = seatIdOf(e.target);
@@ -2579,10 +2637,16 @@ var _SeatmapRenderer = class _SeatmapRenderer {
       const factor = Math.exp(-e.evt.deltaY * 2e-3);
       this.zoomAbout(this.stage.scaleX() * clamp(factor, 0.5, 2), pointer);
     });
-    this.stage.on("click tap", () => {
-      if (!this.cached || this.moved > 8) return;
+    this.stage.on("click tap", (e) => {
+      if (this.moved > 8) return;
       const pointer = this.stage.getPointerPosition();
       if (!pointer) return;
+      if (!this.cached) {
+        if (seatIdOf(e.target)) return;
+        const near = this.nearestSeatToScreen(pointer, SEAT_TAP_SLOP_PX);
+        if (near) this.handleSeatTap(near);
+        return;
+      }
       if (this.stacked && this.opts.onDeckTap) {
         const floorId = this.deckFloorAt();
         if (floorId) {
@@ -2785,14 +2849,40 @@ var _SeatmapRenderer = class _SeatmapRenderer {
       this.seatLayer.batchDraw();
     }
   }
-  cacheSeatLayer() {
+  /** Rebuild the seat-layer bitmap synchronously (no paint). Shared by the
+   *  debounced cacheSeatLayer() and the synchronous forceDraw() catch-up. */
+  rebuildSeatCache() {
     const pr = clamp(this.stage.scaleX() * this.dpr, 0.15, 2);
     this.seatLayer.clearCache();
     this.seatLayer.cache({ pixelRatio: pr });
     this.seatLayer.listening(false);
     this.cached = true;
+  }
+  cacheSeatLayer() {
+    this.rebuildSeatCache();
     this.seatLayer.batchDraw();
   }
+  /**
+   * 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() {
+    if (this.recacheTimer) {
+      clearTimeout(this.recacheTimer);
+      this.recacheTimer = null;
+      this.rebuildSeatCache();
+    }
+    this.bgLayer.draw();
+    this.seatLayer.draw();
+    this.overlayLayer.draw();
+  }
   updateLabels() {
     const show = this.effScale() > LABEL_SCALE;
     this.labelGroup.destroyChildren();
@@ -2928,6 +3018,10 @@ var PickerController = class {
     this.reconnectTimer = null;
     this.attempt = 0;
     this.closed = false;
+    /** 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). */
+    this.onVisibilityChange = null;
     // hold state
     this.hold_ = null;
     this.liveStatuses = /* @__PURE__ */ new Map();
@@ -3053,6 +3147,7 @@ var PickerController = class {
     this.closedSections = new Set(closedIds);
     if (closedIds.length) renderer.setClosedSections?.(closedIds);
     if (seats) this.applySeatsMap(seats);
+    this.attachVisibilityListener();
     this.connect();
     return {
       doc: res.doc,
@@ -3479,6 +3574,7 @@ var PickerController = class {
   }
   destroy() {
     this.closed = true;
+    this.detachVisibilityListener();
     if (this.reconnectTimer) {
       clearTimeout(this.reconnectTimer);
       this.reconnectTimer = null;
@@ -3675,6 +3771,37 @@ var PickerController = class {
     }
   }
   // ---- realtime socket ------------------------------------------------------
+  /**
+   * 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).
+   */
+  attachVisibilityListener() {
+    if (this.onVisibilityChange) return;
+    if (typeof document === "undefined" || typeof document.addEventListener !== "function") return;
+    const handler = () => {
+      if (this.closed) return;
+      if (document.visibilityState !== "visible") return;
+      void this.resnapshot().then(() => {
+        if (!this.closed) this.renderer?.forceDraw();
+      });
+    };
+    this.onVisibilityChange = handler;
+    document.addEventListener("visibilitychange", handler);
+  }
+  detachVisibilityListener() {
+    if (!this.onVisibilityChange) return;
+    if (typeof document !== "undefined" && typeof document.removeEventListener === "function") {
+      document.removeEventListener("visibilitychange", this.onVisibilityChange);
+    }
+    this.onVisibilityChange = null;
+  }
   connect() {
     if (this.closed) return;
     let ws;
@@ -3720,6 +3847,9 @@ var PickerController = class {
           }
           r.setStatus([id], next);
         }
+        if (this.opts.keepLiveWhileHidden && typeof document !== "undefined" && document.visibilityState === "hidden") {
+          r.forceDraw();
+        }
         this.clearBookedHoldIfSettled();
         this.opts.onStatusChange?.();
       }