@seatlayer/js 0.38.0 → 0.39.0

package/dist/index.js

@@ -6165,6 +6165,8 @@ import {
   SeatmapRenderer,
   expandChart as expandChart2,
   computeSections,
+  gaAreasOf,
+  gaUnitLabels,
   UNGROUPED_ID
 } from "@seatlayer/core";
 
@@ -9160,13 +9162,39 @@ var SeatManager = class {
     this.labelToId = /* @__PURE__ */ new Map();
     this.labelToSeat = /* @__PURE__ */ new Map();
     this.allIds = [];
+    /**
+     * GA inventory units — real sellable labels the server counts, with NO seat
+     * geometry and therefore no renderer binding. They live here rather than in
+     * `labelToId`/`allIds` so every paint path keeps addressing paintable nodes
+     * only, while the tally denominator finally covers the same universe the
+     * numerator does. Without them a GA sale hit `booked` but not `total`:
+     * Free under-reported by GA capacity and SOLD% could exceed 100%.
+     */
+    this.gaUnitLabelSet = /* @__PURE__ */ new Set();
     this.status = /* @__PURE__ */ new Map();
+    /** Live non-free counters, moved by each delta rather than re-walked. */
+    this.counts = { held: 0, booked: 0, blocked: 0 };
+    /** Bumped whenever the seat model is replaced wholesale (a full snapshot). */
+    this.modelVersion = 0;
     this.currency = "USD";
     this.authoritativeGrossRevenue = 0;
     this.revenueStatus = "loading";
     this.revenueRequest = 0;
-    this.revenueRefreshTimer = null;
     this.controlRoomSnapshot = null;
+    /**
+     * The server's own totals, pinned to the client model they were read against.
+     * Display = server baseline + (client now − client then), so the authoritative
+     * numbers land exactly on arrival and deltas still move them between reads.
+     * A wholesale model replacement invalidates the pairing (`model`), and the
+     * client tallies — themselves a fresh authenticated read — take over.
+     */
+    this.serverBaseline = null;
+    /** Latest presence frame, held whether or not a snapshot has landed yet. */
+    this.livePresence = null;
+    /** Latest cumulative booked gross pushed on a delta frame. */
+    this.liveGross = null;
+    /** Coalesces a burst of deltas into one KPI/rail repaint. */
+    this.paintHandle = null;
     this.trendWindowMinutes = 15;
     this.heatEnabled = false;
     this.lastKpiValues = /* @__PURE__ */ new Map();
@@ -9264,12 +9292,7 @@ var SeatManager = class {
       const res = await this.api.chart(this.key);
       this.doc = res.doc;
       this.currency = res.event.currency ?? this.opts.currency ?? this.currency;
-      const seats = expandChart2(res.doc);
-      for (const s of seats) {
-        this.labelToId.set(s.label, s.id);
-        this.labelToSeat.set(s.label, s);
-        this.allIds.push(s.id);
-      }
+      this.buildUnitUniverse(res.doc);
       this.buildRenderer();
       this.buildSectionOptions();
       const [, controlRoom] = await Promise.all([
@@ -9630,7 +9653,10 @@ var SeatManager = class {
     if (this.followLiveTimer) clearTimeout(this.followLiveTimer);
     if (this.followSeatTimer) clearTimeout(this.followSeatTimer);
     if (this.unblockAllConfirmTimer) clearTimeout(this.unblockAllConfirmTimer);
-    if (this.revenueRefreshTimer) clearTimeout(this.revenueRefreshTimer);
+    if (this.paintHandle !== null && typeof cancelAnimationFrame === "function") {
+      cancelAnimationFrame(this.paintHandle);
+    }
+    this.paintHandle = null;
     this.channels?.destroy();
     this.channels = null;
     if (this.tokenRefreshTimer) clearTimeout(this.tokenRefreshTimer);
@@ -9713,6 +9739,37 @@ var SeatManager = class {
     }
     this.syncSelection();
   }
+  /**
+   * Build the client's inventory universe from the chart.
+   *
+   * `expandChart` yields SEATS — it has no output for a GA area, whose capacity
+   * is sold as N synthetic unit labels. The server's seat map keys, its deltas
+   * and its `totals` all speak those labels, so a client that only knows seats
+   * counts GA sales in the numerator (every key of the snapshot is written into
+   * `status`) while leaving them out of the denominator. Registering the GA
+   * units here — labels only, never a render binding — is what makes the two
+   * agree.
+   */
+  buildUnitUniverse(doc) {
+    for (const seat of expandChart2(doc)) {
+      this.labelToId.set(seat.label, seat.id);
+      this.labelToSeat.set(seat.label, seat);
+      this.allIds.push(seat.id);
+    }
+    for (const area of gaAreasOf(doc)) {
+      for (const label of gaUnitLabels(area)) {
+        if (!this.labelToId.has(label)) this.gaUnitLabelSet.add(label);
+      }
+    }
+  }
+  /** Every sellable unit the client knows: seats + GA capacity. */
+  unitTotal() {
+    return this.allIds.length + this.gaUnitLabelSet.size;
+  }
+  /** Every label the client models, whether or not it can be painted. */
+  knownLabels() {
+    return [...this.labelToId.keys(), ...this.gaUnitLabelSet];
+  }
   repaintAll() {
     const r = this.renderer;
     if (!r) return;
@@ -9762,7 +9819,7 @@ var SeatManager = class {
     ws.onopen = () => {
       this.attempt = 0;
       this.setLive(true);
-      void this.resnapshot().then(() => this.scheduleRevenueRefresh(0));
+      void this.resnapshot().then(() => this.refreshControlRoom()).catch((err) => this.opts.onError?.(err));
       void this.refreshAvailability();
     };
     ws.onmessage = (e) => this.onMessage(e);
@@ -9800,15 +9857,18 @@ var SeatManager = class {
       this.updateEffectiveAvailability(m.hidden, m.closed);
     }
     if (m.type === "presence") {
-      if (this.controlRoomSnapshot && typeof m.shoppingSessions === "number" && typeof m.activeHolds === "number") {
-        this.controlRoomSnapshot = {
-          ...this.controlRoomSnapshot,
-          presence: { shoppingSessions: m.shoppingSessions, activeHolds: m.activeHolds }
+      if (typeof m.shoppingSessions === "number" && typeof m.activeHolds === "number") {
+        this.livePresence = {
+          at: Date.now(),
+          value: { shoppingSessions: m.shoppingSessions, activeHolds: m.activeHolds }
         };
+        if (this.controlRoomSnapshot) {
+          this.controlRoomSnapshot = { ...this.controlRoomSnapshot, presence: this.livePresence.value };
+          this.opts.onControlRoom?.(this.controlRoomSnapshot);
+        }
         this.lastSyncedAt = Date.now();
         this.recomputeTallies();
         this.paintMonitorInsights();
-        this.opts.onControlRoom?.(this.controlRoomSnapshot);
       }
       return;
     }
@@ -9822,7 +9882,7 @@ var SeatManager = class {
         const st = ["free", "held", "booked", "blocked"].includes(ch.status) ? ch.status : "free";
         const prev = this.status.get(ch.label) ?? "free";
         if (prev === st) continue;
-        this.status.set(ch.label, st);
+        this.setStatusLabel(ch.label, st, prev);
         const id = this.labelToId.get(ch.label);
         if (id) {
           this.renderer?.setStatus([id], toRenderStatus(st));
@@ -9842,10 +9902,38 @@ var SeatManager = class {
         this.lastSyncedAt = Date.now();
         this.afterPaint();
       }
+      if (typeof m.revenue?.gross === "number" && Number.isFinite(m.revenue.gross)) {
+        this.applyLiveGross(m.revenue.gross);
+      }
       this.recomputeTallies();
-      if (ids.length) this.scheduleRevenueRefresh();
     }
   }
+  /**
+   * Adopt the cumulative booked gross a delta frame carried.
+   *
+   * Stashed with its arrival time so an in-flight control-room read can decide
+   * whether it is holding the newer number: a frame that landed after the
+   * request started is newer than the response, one that landed before is not.
+   */
+  applyLiveGross(gross) {
+    this.liveGross = { at: Date.now(), value: gross };
+    this.authoritativeGrossRevenue = gross;
+    this.revenueStatus = "current";
+    if (this.controlRoomSnapshot) {
+      this.controlRoomSnapshot = {
+        ...this.controlRoomSnapshot,
+        revenue: { ...this.controlRoomSnapshot.revenue, gross }
+      };
+      this.opts.onControlRoom?.(this.controlRoomSnapshot);
+    }
+  }
+  /** The single writer for a label's status, so the counters never drift. */
+  setStatusLabel(label, next, prev = this.status.get(label) ?? "free") {
+    this.status.set(label, next);
+    if (prev === next) return;
+    if (prev !== "free") this.counts[prev] -= 1;
+    if (next !== "free") this.counts[next] += 1;
+  }
   async resnapshot() {
     try {
       const objs = await this.api.objects(this.key);
@@ -9868,23 +9956,31 @@ var SeatManager = class {
     const next = /* @__PURE__ */ new Map();
     if (fallback !== void 0) {
       const base = known(fallback);
-      for (const label of this.labelToId.keys()) next.set(label, base);
+      for (const label of this.knownLabels()) next.set(label, base);
     }
     for (const [label, st] of Object.entries(seats)) {
       next.set(label, known(st));
     }
     this.status = next;
+    this.modelVersion += 1;
+    this.recountAll();
     this.lastSyncedAt = Date.now();
     this.repaintAll();
     this.afterPaint();
     this.recomputeTallies();
   }
+  /** The one O(n) walk left: a wholesale model replacement re-bases the counters. */
+  recountAll() {
+    const counts = { held: 0, booked: 0, blocked: 0 };
+    for (const st of this.status.values()) if (st !== "free") counts[st] += 1;
+    this.counts = counts;
+  }
   /** Optimistic local write shared by organizer actions. Paint and tally once,
    * even when an arena-sized operation changes hundreds of seats. */
   setSeatsLocal(labels, st) {
     const ids = [];
     for (const label of labels) {
-      this.status.set(label, st);
+      this.setStatusLabel(label, st);
       const id = this.labelToId.get(label);
       if (id) ids.push(id);
     }
@@ -10010,12 +10106,33 @@ var SeatManager = class {
     this.revenueStatus = "current";
     this.recomputeTallies();
   }
+  /**
+   * Read the server's own control-room projection.
+   *
+   * Called on mount, on every socket (re)connect and after an organizer action —
+   * never on a timer and never per delta frame. Presence and gross that arrived
+   * on the socket AFTER this request started are newer than the response, so
+   * they survive it; anything older defers to the read.
+   */
   async refreshControlRoom() {
     const request = ++this.revenueRequest;
+    const requestedAt = Date.now();
     try {
-      const snapshot = await this.api.controlRoom(this.key, this.trendWindowMinutes);
+      const fetched = await this.api.controlRoom(this.key, this.trendWindowMinutes);
+      let snapshot = fetched;
       if (request === this.revenueRequest) {
+        if (this.livePresence && this.livePresence.at >= requestedAt) {
+          snapshot = { ...snapshot, presence: this.livePresence.value };
+        } else {
+          this.livePresence = null;
+        }
+        if (this.liveGross && this.liveGross.at >= requestedAt) {
+          snapshot = { ...snapshot, revenue: { ...snapshot.revenue, gross: this.liveGross.value } };
+        } else {
+          this.liveGross = null;
+        }
         this.controlRoomSnapshot = snapshot;
+        this.rebaseServerTotals(snapshot);
         this.lastSyncedAt = Date.now();
         this.authoritativeGrossRevenue = snapshot.revenue.gross;
         this.currency = snapshot.currency;
@@ -10034,37 +10151,80 @@ var SeatManager = class {
       throw err;
     }
   }
-  scheduleRevenueRefresh(delay = 140) {
-    this.revenueStatus = "stale";
-    this.recomputeTallies();
-    if (this.revenueRefreshTimer) clearTimeout(this.revenueRefreshTimer);
-    this.revenueRefreshTimer = setTimeout(() => {
-      this.revenueRefreshTimer = null;
-      void this.refreshControlRoom().catch((err) => this.opts.onError?.(err));
-    }, delay);
+  /** Pin the server's totals to the client model they were read against. */
+  rebaseServerTotals(snapshot) {
+    const totals = snapshot.totals;
+    if (!totals || ["free", "held", "booked", "blocked"].some(
+      (key) => !Number.isFinite(totals[key])
+    )) {
+      this.serverBaseline = null;
+      return;
+    }
+    this.serverBaseline = {
+      model: this.modelVersion,
+      server: { free: totals.free, held: totals.held, booked: totals.booked, blocked: totals.blocked },
+      client: this.clientTallies()
+    };
   }
-  recomputeTallies() {
+  /** What the client's own model says — GA units included since `render()`. */
+  clientTallies() {
+    const { held, booked, blocked } = this.counts;
+    return { held, booked, blocked, free: Math.max(0, this.unitTotal() - held - booked - blocked) };
+  }
+  /**
+   * The numbers the KPI bar and rail render.
+   *
+   * The server is the authority: its totals land exactly as read, and the
+   * delta-driven client model carries them forward until the next read. Before
+   * the first snapshot — and after a wholesale model replacement invalidates the
+   * pairing — the client model stands alone.
+   */
+  buildTallies() {
+    const client = this.clientTallies();
+    const baseline = this.serverBaseline?.model === this.modelVersion ? this.serverBaseline : null;
+    const of = (key) => baseline ? Math.max(0, baseline.server[key] + (client[key] - baseline.client[key])) : client[key];
+    const seatTotal = this.controlRoomSnapshot?.event?.seatTotal;
     const t3 = {
-      free: 0,
-      held: 0,
-      booked: 0,
-      blocked: 0,
-      total: this.allIds.length,
+      free: of("free"),
+      held: of("held"),
+      booked: of("booked"),
+      blocked: of("blocked"),
+      total: Number.isFinite(seatTotal) ? seatTotal : this.unitTotal(),
       capacityPct: 0,
       sellThroughPct: 0,
       grossRevenue: this.authoritativeGrossRevenue,
       revenueStatus: this.revenueStatus,
       currency: this.currency
     };
-    let nonFree = 0;
-    for (const st of this.status.values()) {
-      t3[st] += 1;
-      if (st !== "free") nonFree += 1;
-    }
-    t3.free = Math.max(0, t3.total - nonFree);
     t3.capacityPct = t3.total ? Math.round(t3.booked / t3.total * 100) : 0;
     const sellable = t3.total - t3.blocked;
     t3.sellThroughPct = sellable > 0 ? Math.round(t3.booked / sellable * 100) : 0;
+    return t3;
+  }
+  /**
+   * Queue one KPI/rail repaint for this burst of changes.
+   *
+   * A delta frame can carry hundreds of seats and `paintKpis` rebuilds eight
+   * nodes from scratch, so painting per change is what made an arena-sized
+   * frame expensive. Coalescing on a frame keeps the burst to a single rebuild;
+   * without `requestAnimationFrame` (SSR, an older test env) it paints inline
+   * rather than dropping the update.
+   */
+  recomputeTallies() {
+    if (this.closed) return;
+    if (typeof requestAnimationFrame !== "function") {
+      this.flushTallies();
+      return;
+    }
+    if (this.paintHandle !== null) return;
+    this.paintHandle = requestAnimationFrame(() => {
+      this.paintHandle = null;
+      this.flushTallies();
+    });
+  }
+  flushTallies() {
+    if (this.closed) return;
+    const t3 = this.buildTallies();
     this.paintKpis(t3);
     if (this.mode === "view") {
       this.paintLegend(t3);
@@ -10351,16 +10511,16 @@ var SeatManager = class {
   paintKpis(t3) {
     if (!this.els.kpis) return;
     const rev = t3.revenueStatus === "current" ? fmtMoney(t3.grossRevenue, t3.currency) : "\u2014";
-    const presence = this.controlRoomSnapshot?.presence;
+    const presence = this.presenceCounts();
     const items = [
-      { key: "sold-seats", raw: t3.booked, n: t3.booked.toLocaleString(), l: "Sold seats", dot: "#22a06b" },
-      { key: "held-seats", raw: t3.held, n: t3.held.toLocaleString(), l: "Held seats", dot: "#f4b740" },
-      { key: "buyers", raw: presence?.shoppingSessions ?? null, n: presence ? presence.shoppingSessions.toLocaleString() : "\u2014", l: "Buyers" },
-      { key: "active-holds", raw: presence?.activeHolds ?? null, n: presence ? presence.activeHolds.toLocaleString() : "\u2014", l: "Active holds" },
-      { key: "free-seats", raw: t3.free, n: t3.free.toLocaleString(), l: "Free seats", dot: "#6e7bff" },
-      { key: "blocked", raw: t3.blocked, n: t3.blocked.toLocaleString(), l: "Blocked", dot: "#8b94ac" },
-      { key: "sold-pct", raw: t3.capacityPct, n: `${t3.capacityPct}%`, l: "Sold" },
-      { key: "gross-sales", raw: t3.revenueStatus === "current" ? t3.grossRevenue : null, n: rev, l: "Gross sales" }
+      { key: "sold-seats", raw: t3.booked, n: t3.booked.toLocaleString(), l: "Sold seats", dot: "#22a06b", title: "Seats booked" },
+      { key: "held-seats", raw: t3.held, n: t3.held.toLocaleString(), l: "Held seats", dot: "#f4b740", title: "Seats held in a checkout right now" },
+      { key: "free-seats", raw: t3.free, n: t3.free.toLocaleString(), l: "Free seats", dot: "#6e7bff", title: "Seats on sale and unsold" },
+      { key: "blocked", raw: t3.blocked, n: t3.blocked.toLocaleString(), l: "Blocked", dot: "#8b94ac", title: "Seats withheld from sale" },
+      { key: "buyers", raw: presence?.shoppingSessions ?? null, n: presence ? presence.shoppingSessions.toLocaleString() : "\u2014", l: "Buyers", title: "People on the map right now" },
+      { key: "carts", raw: presence?.activeHolds ?? null, n: presence ? presence.activeHolds.toLocaleString() : "\u2014", l: "Carts", title: "Checkouts holding seats right now \u2014 sessions, not seats" },
+      { key: "sold-pct", raw: t3.capacityPct, n: `${t3.capacityPct}%`, l: "Sold", title: "Sold seats as a share of the whole event" },
+      { key: "gross-sales", raw: t3.revenueStatus === "current" ? t3.grossRevenue : null, n: rev, l: "Gross sales", title: "Exact booked gross" }
     ];
     let hasChanges = false;
     this.els.kpis.innerHTML = items.map((item) => {
@@ -10376,7 +10536,7 @@ var SeatManager = class {
       }
       if (item.raw != null) this.lastKpiValues.set(item.key, item.raw);
       const activeDelta = this.activeKpiDeltas.get(item.key);
-      return `<div class="slm-kpi${activeDelta ? " changed" : ""}" data-kpi="${item.key}">
+      return `<div class="slm-kpi${activeDelta ? " changed" : ""}" data-kpi="${item.key}" title="${esc2(item.title)}">
         <b>${item.dot ? `<span class="dot" style="background:${item.dot}"></span>` : ""}${item.n}</b><span>${item.l}</span>
         ${activeDelta ? `<span class="slm-kpidelta${activeDelta.down ? " down" : ""}">${activeDelta.text}</span>` : ""}
       </div>`;
@@ -10434,15 +10594,21 @@ var SeatManager = class {
     this.paintMomentumHelp();
     this.paintFeed();
   }
+  /** Live presence wins over the snapshot's copy — it is the fresher channel,
+   *  and it exists from the first frame rather than the first fetch. */
+  presenceCounts() {
+    return this.livePresence?.value ?? this.controlRoomSnapshot?.presence ?? null;
+  }
   paintMonitorInsights() {
     if (this.mode !== "view") return;
     const snapshot = this.controlRoomSnapshot;
     if (this.els.presence) {
       const connected = this.root?.classList.contains("live");
       const sync = this.lastSyncedAt ? relTime(this.lastSyncedAt, Date.now()) : "waiting";
+      const presence = this.presenceCounts();
       this.els.presence.innerHTML = `
-        <div class="slm-healthitem"><b>${snapshot ? snapshot.presence.shoppingSessions.toLocaleString() : "\u2014"}</b><span>Buyer sessions</span></div>
-        <div class="slm-healthitem"><b>${snapshot ? snapshot.presence.activeHolds.toLocaleString() : "\u2014"}</b><span>Active holds</span></div>
+        <div class="slm-healthitem" title="People on the map right now"><b>${presence ? presence.shoppingSessions.toLocaleString() : "\u2014"}</b><span>Buyers</span></div>
+        <div class="slm-healthitem" title="Checkouts holding seats right now \u2014 sessions, not seats"><b>${presence ? presence.activeHolds.toLocaleString() : "\u2014"}</b><span>Carts</span></div>
         <div class="slm-healthitem"><b>${connected ? "Healthy" : "Reconnecting"}</b><span>Live connection</span></div>
         <div class="slm-healthitem"><b>${sync}</b><span>Last sync</span></div>`;
     }
@@ -11053,7 +11219,7 @@ var SeatManager = class {
       const activity = action === "block" ? this.pushActivity(labels, "blocked", "blocked") : action === "unblock" || action === "unblockAll" ? this.pushActivity(labels, "unblocked", "free") : action === "cancelBooking" ? this.pushActivity(labels, "cancelled", "free") : null;
       if (activity) this.paintSpatialActivity(activity);
     }
-    if (action !== "setHoldTtl") this.scheduleRevenueRefresh(0);
+    if (action !== "setHoldTtl") void this.refreshControlRoom().catch((err) => this.opts.onError?.(err));
     this.opts.onActionComplete?.({ action, labels, count: labels.length });
   }
   toastOk(msg) {