@seatlayer/js 0.39.0 → 0.41.0

package/dist/index.cjs

@@ -436,796 +436,875 @@ module.exports = __toCommonJS(index_exports);
 // src/SeatingChart.ts
 var import_core = require("@seatlayer/core");
 
-// src/api.ts
-var ApiError = class extends Error {
-  constructor(status, message, code, conflicts, reason) {
-    super(message);
-    this.name = "ApiError";
-    this.status = status;
-    this.code = code;
-    this.conflicts = conflicts;
-    this.reason = reason;
-  }
-};
-var OBJECT_UNAVAILABLE_CODES = {
-  seat_conflict: "taken",
-  conflict: "taken",
-  channel_assignment_conflict: "ineligible",
-  allocation_exhausted: "exhausted"
-};
-var PubApi = class {
-  constructor(base, options = {}) {
-    this.base = base;
-    this.viewerId = typeof crypto !== "undefined" && typeof crypto.randomUUID === "function" ? crypto.randomUUID() : `viewer_${Math.random().toString(36).slice(2)}${Date.now().toString(36)}`;
-    this.access = options.access;
-    this.onObjectUnavailable = options.onObjectUnavailable;
-  }
-  /** True when this client is bound to a buyer access session. */
-  get accessScoped() {
-    return !!this.access?.configured;
-  }
-  async request(path, init = {}, retried = false) {
-    const method = init.method ?? "GET";
-    const headers = {};
-    let body;
-    if (init.body !== void 0) {
-      headers["Content-Type"] = "application/json";
-      body = JSON.stringify(init.body);
-    }
-    const authorization = await this.access?.authorization(retried ? "unauthorized" : "initial");
-    if (authorization) headers.Authorization = authorization;
-    const res = await fetch(`${this.base}${path}`, { method, headers, body, credentials: "omit" });
-    const isJson = (res.headers.get("content-type") ?? "").includes("application/json");
-    const data = isJson ? await res.json().catch(() => null) : null;
-    if (!res.ok) {
-      const err = data;
-      const code = err?.code ?? err?.error;
-      if (this.access?.configured && (res.status === 401 || res.status === 403 || res.status === 422)) {
-        const refreshed = await this.access.handleFailure(res.status, code);
-        if (refreshed && !retried) return this.request(path, init, true);
-      }
-      if (res.status === 409) {
-        const reason = code ? OBJECT_UNAVAILABLE_CODES[code] : void 0;
-        const labels = err?.conflicts?.map((c) => c.label) ?? init.labels ?? [];
-        if (reason) this.onObjectUnavailable?.({ labels, reason, code });
-      }
-      throw new ApiError(
-        res.status,
-        err?.error ?? `request_failed_${res.status}`,
-        code,
-        err?.conflicts,
-        err?.reason
-      );
+// src/buyerRealtime.ts
+var SEATLAYER_V1 = "seatlayer.v1";
+var SEP = "\0";
+var CLOSE_ACCESS_REVOKED = 4401;
+var MAX_BACKOFF_MS = 15e3;
+var PING_INTERVAL_MS = 25e3;
+var PONG_GRACE_MS = 1e4;
+var RESUME_ANSWER_GRACE_MS = 5e3;
+function projectionFromSnapshot(frame) {
+  const fallback = typeof frame.default === "string" ? frame.default : "free";
+  const exceptions = {};
+  if (frame.seats && typeof frame.seats === "object") {
+    for (const [label, status] of Object.entries(frame.seats)) {
+      if (typeof status === "string" && status !== fallback) exceptions[label] = status;
     }
-    return data;
-  }
-  chart(key) {
-    return this.request(`/pub/events/${encodeURIComponent(key)}/chart`);
-  }
-  objects(key) {
-    return this.request(`/pub/events/${encodeURIComponent(key)}/objects`);
   }
-  hold(key, selections, ttlMs, replaceHoldId) {
-    return this.request(`/pub/events/${encodeURIComponent(key)}/hold`, {
-      method: "POST",
-      body: { selections, ...ttlMs ? { ttlMs } : {}, ...replaceHoldId ? { replaceHoldId } : {} },
-      labels: selections.map((s) => s.label)
-    });
+  return { default: fallback, exceptions };
+}
+function diffProjections(prev, next) {
+  if (!prev || prev.default !== next.default) return null;
+  const changes = [];
+  for (const [label, status] of Object.entries(next.exceptions)) {
+    if (prev.exceptions[label] !== status) changes.push({ label, status });
   }
-  // `zoneId` scopes the pick to one zone and `ttlMs` carries the host's checkout
-  // window — both are part of the route contract, and dropping either here made
-  // the SDK quietly pick venue-wide and hold for the server default instead.
-  bestAvailable(key, qty, categoryKey, zoneId, ttlMs) {
-    return this.request(`/pub/events/${encodeURIComponent(key)}/best-available`, {
-      method: "POST",
-      body: { qty, ...categoryKey ? { categoryKey } : {}, ...zoneId ? { zoneId } : {}, ...ttlMs ? { ttlMs } : {} }
-    });
+  for (const label of Object.keys(prev.exceptions)) {
+    if (!(label in next.exceptions)) changes.push({ label, status: next.default });
   }
-  resume(key, holdId) {
-    return this.request(`/pub/events/${encodeURIComponent(key)}/hold/resume`, {
-      method: "POST",
-      body: { holdId }
-    });
+  return changes;
+}
+function applyChanges(projection, changes) {
+  for (const change of changes) {
+    if (change.status === projection.default) delete projection.exceptions[change.label];
+    else projection.exceptions[change.label] = change.status;
   }
-  release(key, labels, holdId) {
-    return this.request(`/pub/events/${encodeURIComponent(key)}/release`, {
-      method: "POST",
-      body: { labels, holdId }
-    });
+}
+function assertCredentialFreeUrl(url) {
+  if (/(?:^|[?&#])(?:token|access_token|bearer|authorization|ticket|tkt|bse)=/i.test(url)) {
+    throw new Error("seatlayer: refusing to open a socket with a credential in the URL");
   }
-  /** P4 "need more time?": push an active hold's expiry out. Throws ApiError 409
-   *  (reason: expired | extend_limit | not_found | not_active) if it can't. */
-  extend(key, holdId, ttlMs) {
-    return this.request(`/pub/events/${encodeURIComponent(key)}/extend`, {
-      method: "POST",
-      body: { holdId, ...ttlMs ? { ttlMs } : {} }
-    });
+  if (/\bbse_[A-Za-z0-9._-]+/.test(url)) {
+    throw new Error("seatlayer: refusing to open a socket with a credential in the URL");
   }
-  /**
-   * Which gateways this event can actually take money through — the question
-   * `checkout: 'hosted'` has to answer BEFORE it shows a buyer a Pay button, so
-   * the answer is never discovered by failing a payment.
-   *
-   * Anonymous, and it discloses no account, key, mode or currency for a gateway
-   * that did not match.
-   */
-  paymentOptions(key) {
-    return this.request(`/pub/events/${encodeURIComponent(key)}/payment-options`);
+}
+var BuyerRealtimeClient = class {
+  constructor(options) {
+    this.ws = null;
+    this.stopped = true;
+    this.attempt = 0;
+    this.reconnectTimer = null;
+    this.pingTimer = null;
+    this.pongTimer = null;
+    this.resumeTimer = null;
+    /** Our model of this scope's projection. Null until the first snapshot. */
+    this.projection = null;
+    /** Last `snapshotVersion` seen on any frame that carried one — the resume point. */
+    this.version = null;
+    /** True once the 101 echoed `seatlayer.v1`. */
+    this.v1 = false;
+    /** Set when we offered v1 and the handshake came back without it — a proxy
+     *  most likely stripped the header, so the next attempt selects the v1 frame
+     *  format with the `?pv=1` marker instead (protocol doc §1). The marker
+     *  selects a format and can never carry a credential or widen a scope. */
+    this.useQueryMarker = false;
+    this.hidden = null;
+    this.closedSections = null;
+    this.opts = options;
+    assertCredentialFreeUrl(options.url);
   }
-  /**
-   * Turn a live hold into an order and start a payment.
-   *
-   * The amount is NOT sent: the server recomputes it from the hold's own items,
-   * which is the only reason a browser cannot alter what it pays. Nor is the
-   * PROVIDER — the event row decides which gateway charges, and a `provider` in
-   * the body is checked rather than obeyed (409 `provider_mismatch`). Omitting
-   * it is the shape that cannot disagree.
-   */
-  startCheckout(key, input) {
-    return this.request(`/pub/events/${encodeURIComponent(key)}/checkout`, {
-      method: "POST",
-      body: input
-    });
+  /** Negotiated protocol, for tests and diagnostics. */
+  get protocol() {
+    return this.ws ? this.v1 ? "v1" : "legacy" : null;
   }
-  /**
-   * Poll an order while its gateway webhook lands. The order id is an
-   * unguessable token the buyer already holds, so it acts as the capability —
-   * which is also why a buyer returning from a gateway page can be told what
-   * happened with nothing but the id in the return URL.
-   */
-  orderStatus(orderId) {
-    return this.request(`/pub/orders/${encodeURIComponent(orderId)}/status`);
+  get snapshotVersion() {
+    return this.version;
   }
-  /**
-   * Mint a one-use subscribe ticket for the next socket attempt (protocol doc
-   * §3). The bearer travels here, over ordinary HTTPS where CORS and Origin
-   * already apply; the socket then carries only the short-lived ticket, in its
-   * subprotocol list. TTL ≤ 30s, single redemption — mint one per attempt.
-   */
-  subscribeTicket(key) {
-    return this.request(`/pub/events/${encodeURIComponent(key)}/subscribe-tickets`, {
-      method: "POST",
-      body: {}
-    });
+  start() {
+    if (!this.stopped) return;
+    this.stopped = false;
+    void this.connect();
   }
-  /**
-   * The subscribe URL. Never carries a credential — not the bearer, not the
-   * ticket. Query parameters are diagnostics only.
-   */
-  subscribeUrl(key) {
-    const wsBase = this.base.replace(/^http/, "ws");
-    const params = new URLSearchParams({ surface: "picker", viewerId: this.viewerId });
-    return `${wsBase}/pub/events/${encodeURIComponent(key)}/subscribe?${params}`;
+  /** Stop for good (destroy, or a revocation). Safe to call twice. */
+  stop() {
+    this.stopped = true;
+    this.clearTimers();
+    const ws = this.ws;
+    this.ws = null;
+    if (ws) {
+      ws.onopen = null;
+      ws.onmessage = null;
+      ws.onclose = null;
+      ws.onerror = null;
+      try {
+        ws.close();
+      } catch {
+      }
+    }
   }
-  /**
-   * What PickerController opens its own socket with.
-   *
-   * Empty for an access-scoped client: a private scope authenticates with a
-   * subprotocol ticket, which a URL-only constructor cannot carry, so the SDK's
-   * BuyerRealtimeClient owns that socket instead and the controller skips its
-   * own (an empty URL is its documented "no live feed" contract). A tokenless
-   * public client returns exactly the URL it always has, so nothing about the
-   * public picker's realtime path changes.
-   */
-  socketUrl(key) {
-    return this.accessScoped ? "" : this.subscribeUrl(key);
+  /** Restart after the host re-authorized a revoked buyer (`refreshAccess()`). */
+  restart() {
+    this.stop();
+    this.projection = null;
+    this.version = null;
+    this.attempt = 0;
+    this.start();
   }
-};
-
-// src/buyerAccess.ts
-var BuyerAccessUnavailableError = class extends Error {
-  constructor(event) {
-    super(`buyer_access_unavailable:${event.reason}`);
-    this.name = "BuyerAccessUnavailableError";
-    this.reason = event.reason;
-    this.code = event.code;
-    this.status = event.status;
-  }
-};
-var EXPIRED_CODES = /* @__PURE__ */ new Set(["buyer_access_expired"]);
-var RECOVERABLE = /* @__PURE__ */ new Set([
-  "paused",
-  "provider_failed",
-  "channel_denied"
-]);
-function classifyAccessFailure(status, code) {
-  switch (code) {
-    case "buyer_access_invalid":
-      return "invalid";
-    case "buyer_access_revoked":
-      return "revoked";
-    case "buyer_access_origin_mismatch":
-      return "origin_mismatch";
-    case "buyer_access_event_mismatch":
-      return "event_mismatch";
-    case "buyer_access_mode_mismatch":
-      return "mode_mismatch";
-    case "channel_access_denied":
-      return "channel_denied";
-    case "channel_paused":
-      return "paused";
-    case "invalid_channel_scope":
-      return "invalid_scope";
-    default:
-      break;
-  }
-  if (status === 401) return "invalid";
-  return null;
-}
-function isAccessExpiry(status, code) {
-  return status === 401 && !!code && EXPIRED_CODES.has(code);
-}
-var DEFAULT_SKEW_MS = 3e4;
-var _token, _expiresAt, _provider, _skewMs, _inflight, _terminal, _lastFailure, _onExpired, _onUnavailable, _configured, _BuyerAccessContext_instances, accept_fn, renew_fn, fail_fn;
-var BuyerAccessContext = class {
-  constructor(options) {
-    __privateAdd(this, _BuyerAccessContext_instances);
-    /** Private field: not enumerable, not spreadable, not serializable. */
-    __privateAdd(this, _token, null);
-    __privateAdd(this, _expiresAt, 0);
-    __privateAdd(this, _provider);
-    __privateAdd(this, _skewMs);
-    __privateAdd(this, _inflight, null);
-    __privateAdd(this, _terminal, null);
-    /** The most recent failure, terminal or not — so one cause reports once. */
-    __privateAdd(this, _lastFailure, null);
-    __privateAdd(this, _onExpired);
-    __privateAdd(this, _onUnavailable);
-    /** Decided once, at construction. See the `configured` getter. */
-    __privateAdd(this, _configured, false);
-    __privateSet(this, _provider, options.provider);
-    __privateSet(this, _skewMs, options.skewMs ?? DEFAULT_SKEW_MS);
-    __privateSet(this, _onExpired, options.onExpired);
-    __privateSet(this, _onUnavailable, options.onUnavailable);
-    if (options.token) {
-      const seed = typeof options.token === "string" ? { token: options.token } : options.token;
-      __privateMethod(this, _BuyerAccessContext_instances, accept_fn).call(this, seed);
+  // ---- connection -----------------------------------------------------------
+  async connect() {
+    if (this.stopped) return;
+    let protocols = [SEATLAYER_V1];
+    if (this.opts.mintTicket) {
+      let minted;
+      try {
+        minted = await this.opts.mintTicket();
+      } catch (err) {
+        this.reportIfAccessError(err);
+        this.scheduleReconnect();
+        return;
+      }
+      if (this.stopped) return;
+      if (minted?.protocols?.length) {
+        protocols = [...minted.protocols];
+        if (!protocols.includes(SEATLAYER_V1)) protocols.unshift(SEATLAYER_V1);
+      } else if (minted?.ticket) {
+        protocols = [SEATLAYER_V1, `tkt.${minted.ticket}`];
+      }
     }
-    __privateSet(this, _configured, !!__privateGet(this, _provider) || !!__privateGet(this, _token));
+    const offeredResume = this.version !== null;
+    if (offeredResume) protocols.push(`sv.${this.version}`);
+    const url = this.useQueryMarker ? `${this.opts.url}${this.opts.url.includes("?") ? "&" : "?"}pv=1` : this.opts.url;
+    assertCredentialFreeUrl(url);
+    let ws;
+    try {
+      const make = this.opts.socketFactory ?? ((u, p) => new WebSocket(u, p));
+      ws = make(url, protocols);
+    } catch {
+      this.scheduleReconnect();
+      return;
+    }
+    this.ws = ws;
+    ws.onopen = () => {
+      if (this.ws !== ws) return;
+      this.attempt = 0;
+      this.v1 = ws.protocol === SEATLAYER_V1;
+      if (!this.v1) this.useQueryMarker = true;
+      this.startKeepalive(ws);
+      if (offeredResume) {
+        this.resumeTimer = setTimeout(() => {
+          this.resumeTimer = null;
+          void this.opts.sink.resync();
+        }, RESUME_ANSWER_GRACE_MS);
+      } else {
+        void this.opts.sink.resync();
+      }
+    };
+    ws.onmessage = (event) => {
+      if (this.ws !== ws) return;
+      let parsed;
+      try {
+        parsed = JSON.parse(typeof event.data === "string" ? event.data : "");
+      } catch {
+        return;
+      }
+      if (!parsed || typeof parsed !== "object") return;
+      this.handleFrame(parsed);
+    };
+    ws.onclose = (event) => {
+      if (this.ws !== ws) return;
+      this.ws = null;
+      this.clearTimers();
+      if (event?.code === CLOSE_ACCESS_REVOKED) {
+        this.stopped = true;
+        this.opts.onAccessUnavailable?.({
+          reason: "revoked",
+          code: "access_revoked",
+          retryable: false
+        });
+        return;
+      }
+      this.scheduleReconnect();
+    };
+    ws.onerror = () => {
+      try {
+        ws.close();
+      } catch {
+      }
+    };
   }
-  /**
-   * True when this picker is access-scoped at all. A false here is the
-   * tokenless public picker, which must behave exactly as it always has.
-   *
-   * Answered from what the HOST asked for, never from live token state. It used
-   * to be `!!#provider || !!#token`, which quietly inverted this file's central
-   * rule for a one-shot `buyerAccessToken` host: `#fail()` clears `#token`, so
-   * the first refusal turned a configured context into an "unconfigured" one,
-   * `authorization()` then returned null instead of throwing, and the very next
-   * call went out with no bearer — the anonymous Public sale fallback this
-   * module exists to prevent. A provider host never saw it, because `#provider`
-   * held `configured` true. Found against a live worker in the M9 pass.
-   */
-  get configured() {
-    return __privateGet(this, _configured);
+  handleFrame(frame) {
+    const type = typeof frame.type === "string" ? frame.type : "";
+    if (frame.protocol === 1) this.v1 = true;
+    if (typeof frame.snapshotVersion === "number") this.version = frame.snapshotVersion;
+    if (type === "pong") {
+      this.clearPongTimer();
+      return;
+    }
+    if (Array.isArray(frame.hidden) || Array.isArray(frame.closed)) {
+      const hidden = Array.isArray(frame.hidden) ? frame.hidden : [];
+      const closed = Array.isArray(frame.closed) ? frame.closed : [];
+      const hKey = hidden.join(SEP);
+      const cKey = closed.join(SEP);
+      if (hKey !== this.hidden || cKey !== this.closedSections) {
+        this.hidden = hKey;
+        this.closedSections = cKey;
+        this.opts.sink.onSections?.(hidden, closed);
+      }
+    }
+    if (type === "hidden") return;
+    if (type === "presence") {
+      this.opts.sink.onPresence?.({
+        shoppingSessions: Number(frame.shoppingSessions) || 0,
+        activeHolds: Number(frame.activeHolds) || 0
+      });
+      return;
+    }
+    if (type === "allocation") {
+      return;
+    }
+    if (type === "snapshot" || !type && frame.seats) {
+      this.answered();
+      const next = projectionFromSnapshot(frame);
+      const changes = diffProjections(this.projection, next);
+      this.projection = next;
+      if (changes === null) void this.opts.sink.resync();
+      else if (changes.length) this.opts.sink.applyStatuses(changes);
+      return;
+    }
+    if (type === "delta" && Array.isArray(frame.changes)) {
+      this.answered();
+      const changes = frame.changes.filter((c) => typeof c?.label === "string" && typeof c?.status === "string").map((c) => ({ label: c.label, status: c.status }));
+      if (!changes.length) return;
+      if (this.projection) applyChanges(this.projection, changes);
+      this.opts.sink.applyStatuses(changes);
+    }
   }
-  /** Set once a state arrives that refreshing cannot clear. */
-  get unavailable() {
-    return __privateGet(this, _terminal);
+  /** The server answered our resume; cancel the fallback resync. */
+  answered() {
+    if (!this.resumeTimer) return;
+    clearTimeout(this.resumeTimer);
+    this.resumeTimer = null;
   }
-  /** True while a usable bearer is held (ignores skew). */
-  get hasToken() {
-    return !!__privateGet(this, _token) && (__privateGet(this, _expiresAt) === 0 || __privateGet(this, _expiresAt) > Date.now());
+  reportIfAccessError(err) {
+    const reason = err?.reason;
+    if (err?.name !== "BuyerAccessUnavailableError") return;
+    this.stopped = true;
+    this.opts.onAccessUnavailable?.({
+      reason: reason ?? "invalid",
+      code: err.code,
+      status: err.status,
+      retryable: reason === "paused"
+    });
   }
-  /** Epoch ms the current token expires, or 0 when the host didn't say. */
-  get expiresAt() {
-    return __privateGet(this, _expiresAt);
+  // ---- keepalive & backoff --------------------------------------------------
+  /**
+   * Liveness is ping/pong, and only ping/pong. A socket that receives nothing
+   * for minutes is the normal, correct state for a narrowly-scoped buyer on a
+   * busy event (protocol doc §5), so quiet time never triggers a reconnect.
+   */
+  startKeepalive(ws) {
+    this.pingTimer = setInterval(() => {
+      if (this.ws !== ws) return;
+      try {
+        ws.send(JSON.stringify({ type: "ping" }));
+      } catch {
+        return;
+      }
+      this.clearPongTimer();
+      this.pongTimer = setTimeout(() => {
+        this.pongTimer = null;
+        try {
+          ws.close();
+        } catch {
+        }
+      }, PONG_GRACE_MS);
+    }, PING_INTERVAL_MS);
   }
   /**
-   * The `Authorization` header value for a scoped operation.
+   * FULL jitter, not plain exponential backoff.
    *
-   * Returns null only when this context is not configured at all (the ordinary
-   * anonymous public picker). A configured context either returns a bearer or
-   * throws `BuyerAccessUnavailableError` — it never returns null, because a
-   * null here would send the request as anonymous Public sale.
-   */
-  async authorization(reason = "initial") {
-    if (!this.configured) return null;
-    if (__privateGet(this, _terminal)) throw new BuyerAccessUnavailableError(__privateGet(this, _terminal));
-    const now = Date.now();
-    const stale = !__privateGet(this, _token) || __privateGet(this, _expiresAt) > 0 && __privateGet(this, _expiresAt) - __privateGet(this, _skewMs) <= now;
-    if (stale) {
-      const expired = !!__privateGet(this, _token) && __privateGet(this, _expiresAt) > 0 && __privateGet(this, _expiresAt) <= now;
-      const why = __privateGet(this, _token) ? expired ? "expired" : "expiring" : reason;
-      const token = await __privateMethod(this, _BuyerAccessContext_instances, renew_fn).call(this, why);
-      if (!token) {
-        throw new BuyerAccessUnavailableError(
-          __privateGet(this, _terminal) ?? __privateGet(this, _lastFailure) ?? __privateMethod(this, _BuyerAccessContext_instances, fail_fn).call(this, "provider_failed")
-        );
-      }
-      return `Bearer ${token}`;
-    }
-    return `Bearer ${__privateGet(this, _token)}`;
-  }
-  /**
-   * Handle a 401/403 from a scoped call. Returns true when the caller should
-   * retry the same request once with the refreshed bearer.
+   * A deterministic `2**attempt` schedule makes every browser that lost the same
+   * socket — a worker redeploy, a DO eviction, a flaky edge PoP — come back in
+   * the same millisecond, and an on-sale crowd reconnecting in lockstep is the
+   * thing that turns one blip into a self-sustaining thundering herd. Full
+   * jitter (`random() * ceiling`) spreads the same crowd across the whole
+   * window; the ceiling still doubles, so a persistent outage still backs off.
+   *
+   * `Math.random` is correct here: this is client code choosing a delay, not a
+   * Workflow step that has to replay deterministically.
    */
-  async handleFailure(status, code) {
-    var _a;
-    if (!this.configured) return false;
-    if (isAccessExpiry(status, code)) {
-      __privateSet(this, _token, null);
-      __privateSet(this, _expiresAt, 0);
-      const token = await __privateMethod(this, _BuyerAccessContext_instances, renew_fn).call(this, "unauthorized", code);
-      (_a = __privateGet(this, _onExpired)) == null ? void 0 : _a.call(this, { reason: "unauthorized", code, refreshed: !!token });
-      return !!token;
-    }
-    const reason = classifyAccessFailure(status, code);
-    if (reason) {
-      __privateMethod(this, _BuyerAccessContext_instances, fail_fn).call(this, reason, code, status);
-      return false;
-    }
-    return false;
-  }
-  /** Host-driven re-acquisition (after the buyer signs in again, say). */
-  async refresh(reason = "manual") {
-    __privateSet(this, _terminal, null);
-    __privateSet(this, _lastFailure, null);
-    __privateSet(this, _token, null);
-    __privateSet(this, _expiresAt, 0);
-    return !!await __privateMethod(this, _BuyerAccessContext_instances, renew_fn).call(this, reason);
-  }
-  /** Drop the bearer. Called on destroy so nothing outlives the widget. */
-  clear() {
-    __privateSet(this, _token, null);
-    __privateSet(this, _expiresAt, 0);
-    __privateSet(this, _inflight, null);
+  scheduleReconnect() {
+    if (this.stopped || this.reconnectTimer) return;
+    const attempt = Math.min(this.attempt++, 5);
+    const ceiling = Math.min(1e3 * 2 ** attempt, MAX_BACKOFF_MS);
+    const delay = Math.random() * ceiling;
+    this.reconnectTimer = setTimeout(() => {
+      this.reconnectTimer = null;
+      void this.connect();
+    }, delay);
   }
-  /** Redaction: the bearer must not survive a stringify or an interpolation. */
-  toJSON() {
-    return { configured: this.configured, hasToken: this.hasToken };
+  clearPongTimer() {
+    if (!this.pongTimer) return;
+    clearTimeout(this.pongTimer);
+    this.pongTimer = null;
   }
-  toString() {
-    return "[BuyerAccessContext redacted]";
+  clearTimers() {
+    if (this.pingTimer) clearInterval(this.pingTimer);
+    this.pingTimer = null;
+    this.clearPongTimer();
+    if (this.reconnectTimer) clearTimeout(this.reconnectTimer);
+    this.reconnectTimer = null;
+    if (this.resumeTimer) clearTimeout(this.resumeTimer);
+    this.resumeTimer = null;
   }
 };
-_token = new WeakMap();
-_expiresAt = new WeakMap();
-_provider = new WeakMap();
-_skewMs = new WeakMap();
-_inflight = new WeakMap();
-_terminal = new WeakMap();
-_lastFailure = new WeakMap();
-_onExpired = new WeakMap();
-_onUnavailable = new WeakMap();
-_configured = new WeakMap();
-_BuyerAccessContext_instances = new WeakSet();
-// ---- internals ------------------------------------------------------------
-accept_fn = function(next) {
-  if (!next || typeof next.token !== "string" || !next.token) return null;
-  __privateSet(this, _token, next.token);
-  __privateSet(this, _expiresAt, typeof next.expiresAt === "number" ? next.expiresAt : 0);
-  return __privateGet(this, _token);
-};
-/**
- * One provider call at a time. Several operations racing an expiry (chart +
- * objects + a socket ticket) must not mint several sessions — the guide's
- * rotate-on-retry rule would revoke the ones they didn't observe.
- */
-renew_fn = function(reason, code) {
-  if (__privateGet(this, _inflight)) return __privateGet(this, _inflight);
-  const provider = __privateGet(this, _provider);
-  if (!provider) {
-    __privateMethod(this, _BuyerAccessContext_instances, fail_fn).call(this, "no_token", code);
-    return Promise.resolve(null);
-  }
-  const run = (async () => {
-    try {
-      const next = await provider({ reason });
-      const token = __privateMethod(this, _BuyerAccessContext_instances, accept_fn).call(this, next);
-      if (!token) {
-        __privateMethod(this, _BuyerAccessContext_instances, fail_fn).call(this, "provider_failed", code);
-        return null;
+function rendererStatus(wire) {
+  if (wire === "blocked") return "not_for_sale";
+  if (wire === "held" || wire === "booked" || wire === "free" || wire === "not_for_sale") return wire;
+  return "free";
+}
+function createControllerSink(controller, options = {}) {
+  const idsForLabel = (label) => {
+    const table = controller.tableSelection(label);
+    if (table) return table.physicalSeatIds;
+    const id = controller.idForLabel(label);
+    return id ? [id] : [];
+  };
+  return {
+    applyStatuses(changes) {
+      const held = controller.currentHold()?.labels ?? [];
+      const buckets = {
+        free: [],
+        held: [],
+        booked: [],
+        not_for_sale: []
+      };
+      const flashes = [];
+      const lost = [];
+      const selected = new Map(controller.getSelection().map((s) => [s.label, s.id]));
+      for (const change of changes) {
+        const ids = idsForLabel(change.label);
+        if (!ids.length) continue;
+        const next = rendererStatus(change.status);
+        buckets[next].push(...ids);
+        if (options.flashOnLiveChange && next !== "free" && !held.includes(change.label) && ids.some((id) => controller.getStatus(id) === "free")) {
+          const color = next === "held" ? "#f4b740" : "#f43f5e";
+          for (const id of ids) flashes.push({ id, color });
+        }
+        if (next !== "free" && !held.includes(change.label) && selected.has(change.label)) {
+          lost.push(change.label);
+        }
       }
-      return token;
-    } catch {
-      __privateMethod(this, _BuyerAccessContext_instances, fail_fn).call(this, "provider_failed", code);
-      return null;
-    } finally {
-      __privateSet(this, _inflight, null);
+      for (const status of ["free", "held", "booked", "not_for_sale"]) {
+        if (buckets[status].length) controller.setStatus(buckets[status], status);
+      }
+      for (const flash of flashes) controller.flashSeat(flash.id, flash.color);
+      if (lost.length) {
+        const ids = lost.flatMap((label) => idsForLabel(label));
+        if (ids.length) controller.deselect(ids);
+        const ineligible = changes.some(
+          (c) => c.status === "blocked" && lost.includes(c.label)
+        );
+        options.onSelectedObjectUnavailable?.(lost, ineligible ? "ineligible" : "taken");
+      }
+      options.onStatusChange?.();
+    },
+    async resync() {
+      await controller.refresh();
+    },
+    /**
+     * Section availability moved. Statuses are re-pulled so the map repaints.
+     *
+     * Known limit: rebuilding the chart when a section is newly HIDDEN (its
+     * seats are stripped, not greyed) lives inside PickerController's own
+     * socket handler and has no public entry point, so an access-scoped picker
+     * repaints statuses but does not restructure the chart until its next
+     * mount. Closing/opening a section — the common mid-sale move — is a
+     * status-level change and is handled here in full.
+     */
+    onSections(hidden, closed) {
+      void controller.refresh();
+      options.onSections?.(hidden, closed);
     }
-  })();
-  __privateSet(this, _inflight, run);
-  return run;
-};
-fail_fn = function(reason, code, status) {
-  var _a;
-  const event = {
-    reason,
-    code,
-    status,
-    // Unchanged: `retryable` means "the SAME request may succeed later".
-    // `provider_failed` is recoverable but not retryable — the host must fix
-    // its mint endpoint first — so the two sets are deliberately different.
-    retryable: reason === "paused" || reason === "channel_denied"
   };
-  __privateSet(this, _lastFailure, event);
-  if (!RECOVERABLE.has(reason)) {
-    __privateSet(this, _terminal, event);
-    __privateSet(this, _token, null);
-    __privateSet(this, _expiresAt, 0);
-  }
-  (_a = __privateGet(this, _onUnavailable)) == null ? void 0 : _a.call(this, event);
-  return event;
-};
-function createBuyerAccessContext(options, hooks = {}) {
-  if (!options.buyerAccessTokenProvider && !options.buyerAccessToken) return null;
-  return new BuyerAccessContext({
-    provider: options.buyerAccessTokenProvider,
-    token: options.buyerAccessToken,
-    ...hooks
-  });
 }
 
-// src/buyerRealtime.ts
-var SEATLAYER_V1 = "seatlayer.v1";
-var SEP = "\0";
-var CLOSE_ACCESS_REVOKED = 4401;
-var MAX_BACKOFF_MS = 15e3;
-var PING_INTERVAL_MS = 25e3;
-var PONG_GRACE_MS = 1e4;
-var RESUME_ANSWER_GRACE_MS = 5e3;
-function projectionFromSnapshot(frame) {
-  const fallback = typeof frame.default === "string" ? frame.default : "free";
-  const exceptions = {};
-  if (frame.seats && typeof frame.seats === "object") {
-    for (const [label, status] of Object.entries(frame.seats)) {
-      if (typeof status === "string" && status !== fallback) exceptions[label] = status;
-    }
-  }
-  return { default: fallback, exceptions };
-}
-function diffProjections(prev, next) {
-  if (!prev || prev.default !== next.default) return null;
-  const changes = [];
-  for (const [label, status] of Object.entries(next.exceptions)) {
-    if (prev.exceptions[label] !== status) changes.push({ label, status });
+// src/api.ts
+var ApiError = class extends Error {
+  constructor(status, message, code, conflicts, reason, retryAfterS) {
+    super(message);
+    this.name = "ApiError";
+    this.status = status;
+    this.code = code;
+    this.conflicts = conflicts;
+    this.reason = reason;
+    this.retryAfterS = retryAfterS;
   }
-  for (const label of Object.keys(prev.exceptions)) {
-    if (!(label in next.exceptions)) changes.push({ label, status: next.default });
+};
+var MAX_RATE_LIMIT_WAIT_S = 10;
+var DEFAULT_RATE_LIMIT_WAIT_S = 1;
+function parseRetryAfter(header, bodyValue) {
+  const raw = (header ?? "").trim();
+  if (raw) {
+    const seconds = Number(raw);
+    if (Number.isFinite(seconds) && seconds >= 0) return Math.ceil(seconds);
+    const at = Date.parse(raw);
+    if (Number.isFinite(at)) return Math.max(0, Math.ceil((at - Date.now()) / 1e3));
+  }
+  if (typeof bodyValue === "number" && Number.isFinite(bodyValue) && bodyValue >= 0) {
+    return Math.ceil(bodyValue);
   }
-  return changes;
+  return void 0;
 }
-function applyChanges(projection, changes) {
-  for (const change of changes) {
-    if (change.status === projection.default) delete projection.exceptions[change.label];
-    else projection.exceptions[change.label] = change.status;
+var OBJECT_UNAVAILABLE_CODES = {
+  seat_conflict: "taken",
+  conflict: "taken",
+  channel_assignment_conflict: "ineligible",
+  allocation_exhausted: "exhausted"
+};
+var PubApi = class {
+  constructor(base, options = {}) {
+    this.base = base;
+    this.viewerId = typeof crypto !== "undefined" && typeof crypto.randomUUID === "function" ? crypto.randomUUID() : `viewer_${Math.random().toString(36).slice(2)}${Date.now().toString(36)}`;
+    this.access = options.access;
+    this.onObjectUnavailable = options.onObjectUnavailable;
   }
-}
-function assertCredentialFreeUrl(url) {
-  if (/(?:^|[?&#])(?:token|access_token|bearer|authorization|ticket|tkt|bse)=/i.test(url)) {
-    throw new Error("seatlayer: refusing to open a socket with a credential in the URL");
+  /** True when this client is bound to a buyer access session. */
+  get accessScoped() {
+    return !!this.access?.configured;
   }
-  if (/\bbse_[A-Za-z0-9._-]+/.test(url)) {
-    throw new Error("seatlayer: refusing to open a socket with a credential in the URL");
+  async request(path, init = {}, retried = {}) {
+    const method = init.method ?? "GET";
+    const headers = {};
+    let body;
+    if (init.body !== void 0) {
+      headers["Content-Type"] = "application/json";
+      body = JSON.stringify(init.body);
+    }
+    const authorization = await this.access?.authorization(retried.auth ? "unauthorized" : "initial");
+    if (authorization) headers.Authorization = authorization;
+    const res = await fetch(`${this.base}${path}`, { method, headers, body, credentials: "omit" });
+    const isJson = (res.headers.get("content-type") ?? "").includes("application/json");
+    const data = isJson ? await res.json().catch(() => null) : null;
+    if (!res.ok) {
+      const err = data;
+      const code = err?.code ?? err?.error;
+      if (this.access?.configured && (res.status === 401 || res.status === 403 || res.status === 422)) {
+        const refreshed = await this.access.handleFailure(res.status, code);
+        if (refreshed && !retried.auth) return this.request(path, init, { ...retried, auth: true });
+      }
+      if (res.status === 409) {
+        const reason = code ? OBJECT_UNAVAILABLE_CODES[code] : void 0;
+        const labels = err?.conflicts?.map((c) => c.label) ?? init.labels ?? [];
+        if (reason) this.onObjectUnavailable?.({ labels, reason, code });
+      }
+      let retryAfterS;
+      if (res.status === 429) {
+        retryAfterS = parseRetryAfter(res.headers.get("Retry-After"), err?.retryAfterSeconds) ?? DEFAULT_RATE_LIMIT_WAIT_S;
+        if (method === "GET" && !retried.rateLimit && retryAfterS <= MAX_RATE_LIMIT_WAIT_S) {
+          await new Promise((resolve) => setTimeout(resolve, retryAfterS * 1e3));
+          return this.request(path, init, { ...retried, rateLimit: true });
+        }
+      }
+      throw new ApiError(
+        res.status,
+        err?.error ?? `request_failed_${res.status}`,
+        code,
+        err?.conflicts,
+        err?.reason,
+        retryAfterS
+      );
+    }
+    return data;
   }
-}
-var BuyerRealtimeClient = class {
-  constructor(options) {
-    this.ws = null;
-    this.stopped = true;
-    this.attempt = 0;
-    this.reconnectTimer = null;
-    this.pingTimer = null;
-    this.pongTimer = null;
-    this.resumeTimer = null;
-    /** Our model of this scope's projection. Null until the first snapshot. */
-    this.projection = null;
-    /** Last `snapshotVersion` seen on any frame that carried one — the resume point. */
-    this.version = null;
-    /** True once the 101 echoed `seatlayer.v1`. */
-    this.v1 = false;
-    /** Set when we offered v1 and the handshake came back without it — a proxy
-     *  most likely stripped the header, so the next attempt selects the v1 frame
-     *  format with the `?pv=1` marker instead (protocol doc §1). The marker
-     *  selects a format and can never carry a credential or widen a scope. */
-    this.useQueryMarker = false;
-    this.hidden = null;
-    this.closedSections = null;
-    this.opts = options;
-    assertCredentialFreeUrl(options.url);
+  chart(key) {
+    return this.request(`/pub/events/${encodeURIComponent(key)}/chart`);
   }
-  /** Negotiated protocol, for tests and diagnostics. */
-  get protocol() {
-    return this.ws ? this.v1 ? "v1" : "legacy" : null;
+  objects(key) {
+    return this.request(`/pub/events/${encodeURIComponent(key)}/objects`);
   }
-  get snapshotVersion() {
-    return this.version;
+  hold(key, selections, ttlMs, replaceHoldId) {
+    return this.request(`/pub/events/${encodeURIComponent(key)}/hold`, {
+      method: "POST",
+      body: { selections, ...ttlMs ? { ttlMs } : {}, ...replaceHoldId ? { replaceHoldId } : {} },
+      labels: selections.map((s) => s.label)
+    });
   }
-  start() {
-    if (!this.stopped) return;
-    this.stopped = false;
-    void this.connect();
+  // `zoneId` scopes the pick to one zone and `ttlMs` carries the host's checkout
+  // window — both are part of the route contract, and dropping either here made
+  // the SDK quietly pick venue-wide and hold for the server default instead.
+  bestAvailable(key, qty, categoryKey, zoneId, ttlMs) {
+    return this.request(`/pub/events/${encodeURIComponent(key)}/best-available`, {
+      method: "POST",
+      body: { qty, ...categoryKey ? { categoryKey } : {}, ...zoneId ? { zoneId } : {}, ...ttlMs ? { ttlMs } : {} }
+    });
   }
-  /** Stop for good (destroy, or a revocation). Safe to call twice. */
-  stop() {
-    this.stopped = true;
-    this.clearTimers();
-    const ws = this.ws;
-    this.ws = null;
-    if (ws) {
-      ws.onopen = null;
-      ws.onmessage = null;
-      ws.onclose = null;
-      ws.onerror = null;
-      try {
-        ws.close();
-      } catch {
-      }
-    }
+  resume(key, holdId) {
+    return this.request(`/pub/events/${encodeURIComponent(key)}/hold/resume`, {
+      method: "POST",
+      body: { holdId }
+    });
   }
-  /** Restart after the host re-authorized a revoked buyer (`refreshAccess()`). */
-  restart() {
-    this.stop();
-    this.projection = null;
-    this.version = null;
-    this.attempt = 0;
-    this.start();
+  release(key, labels, holdId) {
+    return this.request(`/pub/events/${encodeURIComponent(key)}/release`, {
+      method: "POST",
+      body: { labels, holdId }
+    });
   }
-  // ---- connection -----------------------------------------------------------
-  async connect() {
-    if (this.stopped) return;
-    let protocols = [SEATLAYER_V1];
-    if (this.opts.mintTicket) {
-      let minted;
-      try {
-        minted = await this.opts.mintTicket();
-      } catch (err) {
-        this.reportIfAccessError(err);
-        this.scheduleReconnect();
-        return;
-      }
-      if (this.stopped) return;
-      if (minted?.protocols?.length) {
-        protocols = [...minted.protocols];
-        if (!protocols.includes(SEATLAYER_V1)) protocols.unshift(SEATLAYER_V1);
-      } else if (minted?.ticket) {
-        protocols = [SEATLAYER_V1, `tkt.${minted.ticket}`];
-      }
-    }
-    const offeredResume = this.version !== null;
-    if (offeredResume) protocols.push(`sv.${this.version}`);
-    const url = this.useQueryMarker ? `${this.opts.url}${this.opts.url.includes("?") ? "&" : "?"}pv=1` : this.opts.url;
-    assertCredentialFreeUrl(url);
-    let ws;
-    try {
-      const make = this.opts.socketFactory ?? ((u, p) => new WebSocket(u, p));
-      ws = make(url, protocols);
-    } catch {
-      this.scheduleReconnect();
-      return;
-    }
-    this.ws = ws;
-    ws.onopen = () => {
-      if (this.ws !== ws) return;
-      this.attempt = 0;
-      this.v1 = ws.protocol === SEATLAYER_V1;
-      if (!this.v1) this.useQueryMarker = true;
-      this.startKeepalive(ws);
-      if (offeredResume) {
-        this.resumeTimer = setTimeout(() => {
-          this.resumeTimer = null;
-          void this.opts.sink.resync();
-        }, RESUME_ANSWER_GRACE_MS);
-      } else {
-        void this.opts.sink.resync();
-      }
-    };
-    ws.onmessage = (event) => {
-      if (this.ws !== ws) return;
-      let parsed;
-      try {
-        parsed = JSON.parse(typeof event.data === "string" ? event.data : "");
-      } catch {
-        return;
-      }
-      if (!parsed || typeof parsed !== "object") return;
-      this.handleFrame(parsed);
-    };
-    ws.onclose = (event) => {
-      if (this.ws !== ws) return;
-      this.ws = null;
-      this.clearTimers();
-      if (event?.code === CLOSE_ACCESS_REVOKED) {
-        this.stopped = true;
-        this.opts.onAccessUnavailable?.({
-          reason: "revoked",
-          code: "access_revoked",
-          retryable: false
-        });
-        return;
-      }
-      this.scheduleReconnect();
-    };
-    ws.onerror = () => {
-      try {
-        ws.close();
-      } catch {
-      }
-    };
+  /** P4 "need more time?": push an active hold's expiry out. Throws ApiError 409
+   *  (reason: expired | extend_limit | not_found | not_active) if it can't. */
+  extend(key, holdId, ttlMs) {
+    return this.request(`/pub/events/${encodeURIComponent(key)}/extend`, {
+      method: "POST",
+      body: { holdId, ...ttlMs ? { ttlMs } : {} }
+    });
   }
-  handleFrame(frame) {
-    const type = typeof frame.type === "string" ? frame.type : "";
-    if (frame.protocol === 1) this.v1 = true;
-    if (typeof frame.snapshotVersion === "number") this.version = frame.snapshotVersion;
-    if (type === "pong") {
-      this.clearPongTimer();
-      return;
-    }
-    if (Array.isArray(frame.hidden) || Array.isArray(frame.closed)) {
-      const hidden = Array.isArray(frame.hidden) ? frame.hidden : [];
-      const closed = Array.isArray(frame.closed) ? frame.closed : [];
-      const hKey = hidden.join(SEP);
-      const cKey = closed.join(SEP);
-      if (hKey !== this.hidden || cKey !== this.closedSections) {
-        this.hidden = hKey;
-        this.closedSections = cKey;
-        this.opts.sink.onSections?.(hidden, closed);
-      }
-    }
-    if (type === "hidden") return;
-    if (type === "presence") {
-      this.opts.sink.onPresence?.({
-        shoppingSessions: Number(frame.shoppingSessions) || 0,
-        activeHolds: Number(frame.activeHolds) || 0
-      });
-      return;
-    }
-    if (type === "allocation") {
-      return;
-    }
-    if (type === "snapshot" || !type && frame.seats) {
-      this.answered();
-      const next = projectionFromSnapshot(frame);
-      const changes = diffProjections(this.projection, next);
-      this.projection = next;
-      if (changes === null) void this.opts.sink.resync();
-      else if (changes.length) this.opts.sink.applyStatuses(changes);
-      return;
-    }
-    if (type === "delta" && Array.isArray(frame.changes)) {
-      this.answered();
-      const changes = frame.changes.filter((c) => typeof c?.label === "string" && typeof c?.status === "string").map((c) => ({ label: c.label, status: c.status }));
-      if (!changes.length) return;
-      if (this.projection) applyChanges(this.projection, changes);
-      this.opts.sink.applyStatuses(changes);
-    }
+  /**
+   * Which gateways this event can actually take money through — the question
+   * `checkout: 'hosted'` has to answer BEFORE it shows a buyer a Pay button, so
+   * the answer is never discovered by failing a payment.
+   *
+   * Anonymous, and it discloses no account, key, mode or currency for a gateway
+   * that did not match.
+   */
+  paymentOptions(key) {
+    return this.request(`/pub/events/${encodeURIComponent(key)}/payment-options`);
   }
-  /** The server answered our resume; cancel the fallback resync. */
-  answered() {
-    if (!this.resumeTimer) return;
-    clearTimeout(this.resumeTimer);
-    this.resumeTimer = null;
+  /**
+   * Turn a live hold into an order and start a payment.
+   *
+   * The amount is NOT sent: the server recomputes it from the hold's own items,
+   * which is the only reason a browser cannot alter what it pays. Nor is the
+   * PROVIDER — the event row decides which gateway charges, and a `provider` in
+   * the body is checked rather than obeyed (409 `provider_mismatch`). Omitting
+   * it is the shape that cannot disagree.
+   */
+  startCheckout(key, input) {
+    return this.request(`/pub/events/${encodeURIComponent(key)}/checkout`, {
+      method: "POST",
+      body: input
+    });
   }
-  reportIfAccessError(err) {
-    const reason = err?.reason;
-    if (err?.name !== "BuyerAccessUnavailableError") return;
-    this.stopped = true;
-    this.opts.onAccessUnavailable?.({
-      reason: reason ?? "invalid",
-      code: err.code,
-      status: err.status,
-      retryable: reason === "paused"
+  /**
+   * Poll an order while its gateway webhook lands. The order id is an
+   * unguessable token the buyer already holds, so it acts as the capability —
+   * which is also why a buyer returning from a gateway page can be told what
+   * happened with nothing but the id in the return URL.
+   */
+  orderStatus(orderId) {
+    return this.request(`/pub/orders/${encodeURIComponent(orderId)}/status`);
+  }
+  /**
+   * Mint a one-use subscribe ticket for the next socket attempt (protocol doc
+   * §3). The bearer travels here, over ordinary HTTPS where CORS and Origin
+   * already apply; the socket then carries only the short-lived ticket, in its
+   * subprotocol list. TTL ≤ 30s, single redemption — mint one per attempt.
+   */
+  subscribeTicket(key) {
+    return this.request(`/pub/events/${encodeURIComponent(key)}/subscribe-tickets`, {
+      method: "POST",
+      body: {}
     });
   }
-  // ---- keepalive & backoff --------------------------------------------------
   /**
-   * Liveness is ping/pong, and only ping/pong. A socket that receives nothing
-   * for minutes is the normal, correct state for a narrowly-scoped buyer on a
-   * busy event (protocol doc §5), so quiet time never triggers a reconnect.
+   * The subscribe URL. Never carries a credential — not the bearer, not the
+   * ticket. Query parameters are diagnostics only.
+   */
+  subscribeUrl(key) {
+    const wsBase = this.base.replace(/^http/, "ws");
+    const params = new URLSearchParams({ surface: "picker", viewerId: this.viewerId });
+    return `${wsBase}/pub/events/${encodeURIComponent(key)}/subscribe?${params}`;
+  }
+  /**
+   * What PickerController opens its own socket with.
+   *
+   * Empty for an access-scoped client: a private scope authenticates with a
+   * subprotocol ticket, which a URL-only constructor cannot carry, so the SDK's
+   * BuyerRealtimeClient owns that socket instead and the controller skips its
+   * own (an empty URL is its documented "no live feed" contract). A tokenless
+   * public client returns exactly the URL it always has, so nothing about the
+   * public picker's realtime path changes.
+   */
+  socketUrl(key) {
+    return this.accessScoped ? "" : this.subscribeUrl(key);
+  }
+  /**
+   * The subprotocol list a PLAIN `new WebSocket(url, protocols)` must offer for
+   * this transport — `PickerTransport.socketProtocols`, which PickerController
+   * calls optionally and which nothing implemented until now.
+   *
+   * Offering `seatlayer.v1` is the whole point: without it the DO answers an
+   * anonymous socket with the LEGACY verbose frame — every unit of a 10k-seat
+   * event, on connect and on every reconnect — instead of the compact
+   * `{default, exceptions}` form. Empty for an access-scoped client, which
+   * authenticates with a one-use ticket a URL-only constructor cannot carry and
+   * whose socket BuyerRealtimeClient owns instead (see `socketUrl`).
+   *
+   * `createRealtime` below is the preferred path and supersedes this for any
+   * host that can use it; this stays the correct answer for a host that builds
+   * the socket itself from the transport contract.
+   */
+  socketProtocols(key) {
+    void key;
+    return this.accessScoped ? [] : [SEATLAYER_V1];
+  }
+  /**
+   * Hand PickerController the v1 realtime client instead of letting it open a
+   * bare socket — `PickerTransport.createRealtime`.
+   *
+   * This is what puts an ANONYMOUS buyer (the on-sale case) on the same wire as
+   * a private-channel one: compact snapshots, `sv.<n>` resume so a reconnect
+   * inside the ring costs a delta rather than a full re-snapshot, ping/pong
+   * liveness, and one jittered backoff implementation shared by both. The
+   * anonymous case simply passes no `mintTicket` — the `/pub/events/:key/
+   * subscribe` upgrade requires no ticket, and the DO resolves a ticketless
+   * socket to the public scope.
+   *
+   * Null when access-scoped: that socket is owned by the widget's own
+   * BuyerRealtimeClient (with the ticket exchange), and `socketUrl()` already
+   * returns '' so the controller opens nothing.
+   */
+  createRealtime(key, sink) {
+    if (this.accessScoped) return null;
+    return new BuyerRealtimeClient({ url: this.subscribeUrl(key), sink });
+  }
+};
+
+// src/buyerAccess.ts
+var BuyerAccessUnavailableError = class extends Error {
+  constructor(event) {
+    super(`buyer_access_unavailable:${event.reason}`);
+    this.name = "BuyerAccessUnavailableError";
+    this.reason = event.reason;
+    this.code = event.code;
+    this.status = event.status;
+  }
+};
+var EXPIRED_CODES = /* @__PURE__ */ new Set(["buyer_access_expired"]);
+var RECOVERABLE = /* @__PURE__ */ new Set([
+  "paused",
+  "provider_failed",
+  "channel_denied"
+]);
+function classifyAccessFailure(status, code) {
+  switch (code) {
+    case "buyer_access_invalid":
+      return "invalid";
+    case "buyer_access_revoked":
+      return "revoked";
+    case "buyer_access_origin_mismatch":
+      return "origin_mismatch";
+    case "buyer_access_event_mismatch":
+      return "event_mismatch";
+    case "buyer_access_mode_mismatch":
+      return "mode_mismatch";
+    case "channel_access_denied":
+      return "channel_denied";
+    case "channel_paused":
+      return "paused";
+    case "invalid_channel_scope":
+      return "invalid_scope";
+    default:
+      break;
+  }
+  if (status === 401) return "invalid";
+  return null;
+}
+function isAccessExpiry(status, code) {
+  return status === 401 && !!code && EXPIRED_CODES.has(code);
+}
+var DEFAULT_SKEW_MS = 3e4;
+var _token, _expiresAt, _provider, _skewMs, _inflight, _terminal, _lastFailure, _onExpired, _onUnavailable, _configured, _BuyerAccessContext_instances, accept_fn, renew_fn, fail_fn;
+var BuyerAccessContext = class {
+  constructor(options) {
+    __privateAdd(this, _BuyerAccessContext_instances);
+    /** Private field: not enumerable, not spreadable, not serializable. */
+    __privateAdd(this, _token, null);
+    __privateAdd(this, _expiresAt, 0);
+    __privateAdd(this, _provider);
+    __privateAdd(this, _skewMs);
+    __privateAdd(this, _inflight, null);
+    __privateAdd(this, _terminal, null);
+    /** The most recent failure, terminal or not — so one cause reports once. */
+    __privateAdd(this, _lastFailure, null);
+    __privateAdd(this, _onExpired);
+    __privateAdd(this, _onUnavailable);
+    /** Decided once, at construction. See the `configured` getter. */
+    __privateAdd(this, _configured, false);
+    __privateSet(this, _provider, options.provider);
+    __privateSet(this, _skewMs, options.skewMs ?? DEFAULT_SKEW_MS);
+    __privateSet(this, _onExpired, options.onExpired);
+    __privateSet(this, _onUnavailable, options.onUnavailable);
+    if (options.token) {
+      const seed = typeof options.token === "string" ? { token: options.token } : options.token;
+      __privateMethod(this, _BuyerAccessContext_instances, accept_fn).call(this, seed);
+    }
+    __privateSet(this, _configured, !!__privateGet(this, _provider) || !!__privateGet(this, _token));
+  }
+  /**
+   * True when this picker is access-scoped at all. A false here is the
+   * tokenless public picker, which must behave exactly as it always has.
+   *
+   * Answered from what the HOST asked for, never from live token state. It used
+   * to be `!!#provider || !!#token`, which quietly inverted this file's central
+   * rule for a one-shot `buyerAccessToken` host: `#fail()` clears `#token`, so
+   * the first refusal turned a configured context into an "unconfigured" one,
+   * `authorization()` then returned null instead of throwing, and the very next
+   * call went out with no bearer — the anonymous Public sale fallback this
+   * module exists to prevent. A provider host never saw it, because `#provider`
+   * held `configured` true. Found against a live worker in the M9 pass.
+   */
+  get configured() {
+    return __privateGet(this, _configured);
+  }
+  /** Set once a state arrives that refreshing cannot clear. */
+  get unavailable() {
+    return __privateGet(this, _terminal);
+  }
+  /** True while a usable bearer is held (ignores skew). */
+  get hasToken() {
+    return !!__privateGet(this, _token) && (__privateGet(this, _expiresAt) === 0 || __privateGet(this, _expiresAt) > Date.now());
+  }
+  /** Epoch ms the current token expires, or 0 when the host didn't say. */
+  get expiresAt() {
+    return __privateGet(this, _expiresAt);
+  }
+  /**
+   * The `Authorization` header value for a scoped operation.
+   *
+   * Returns null only when this context is not configured at all (the ordinary
+   * anonymous public picker). A configured context either returns a bearer or
+   * throws `BuyerAccessUnavailableError` — it never returns null, because a
+   * null here would send the request as anonymous Public sale.
    */
-  startKeepalive(ws) {
-    this.pingTimer = setInterval(() => {
-      if (this.ws !== ws) return;
-      try {
-        ws.send(JSON.stringify({ type: "ping" }));
-      } catch {
-        return;
+  async authorization(reason = "initial") {
+    if (!this.configured) return null;
+    if (__privateGet(this, _terminal)) throw new BuyerAccessUnavailableError(__privateGet(this, _terminal));
+    const now = Date.now();
+    const stale = !__privateGet(this, _token) || __privateGet(this, _expiresAt) > 0 && __privateGet(this, _expiresAt) - __privateGet(this, _skewMs) <= now;
+    if (stale) {
+      const expired = !!__privateGet(this, _token) && __privateGet(this, _expiresAt) > 0 && __privateGet(this, _expiresAt) <= now;
+      const why = __privateGet(this, _token) ? expired ? "expired" : "expiring" : reason;
+      const token = await __privateMethod(this, _BuyerAccessContext_instances, renew_fn).call(this, why);
+      if (!token) {
+        throw new BuyerAccessUnavailableError(
+          __privateGet(this, _terminal) ?? __privateGet(this, _lastFailure) ?? __privateMethod(this, _BuyerAccessContext_instances, fail_fn).call(this, "provider_failed")
+        );
       }
-      this.clearPongTimer();
-      this.pongTimer = setTimeout(() => {
-        this.pongTimer = null;
-        try {
-          ws.close();
-        } catch {
-        }
-      }, PONG_GRACE_MS);
-    }, PING_INTERVAL_MS);
+      return `Bearer ${token}`;
+    }
+    return `Bearer ${__privateGet(this, _token)}`;
   }
-  scheduleReconnect() {
-    if (this.stopped || this.reconnectTimer) return;
-    const attempt = Math.min(this.attempt++, 5);
-    const delay = Math.min(1e3 * 2 ** attempt, MAX_BACKOFF_MS);
-    this.reconnectTimer = setTimeout(() => {
-      this.reconnectTimer = null;
-      void this.connect();
-    }, delay);
+  /**
+   * Handle a 401/403 from a scoped call. Returns true when the caller should
+   * retry the same request once with the refreshed bearer.
+   */
+  async handleFailure(status, code) {
+    var _a;
+    if (!this.configured) return false;
+    if (isAccessExpiry(status, code)) {
+      __privateSet(this, _token, null);
+      __privateSet(this, _expiresAt, 0);
+      const token = await __privateMethod(this, _BuyerAccessContext_instances, renew_fn).call(this, "unauthorized", code);
+      (_a = __privateGet(this, _onExpired)) == null ? void 0 : _a.call(this, { reason: "unauthorized", code, refreshed: !!token });
+      return !!token;
+    }
+    const reason = classifyAccessFailure(status, code);
+    if (reason) {
+      __privateMethod(this, _BuyerAccessContext_instances, fail_fn).call(this, reason, code, status);
+      return false;
+    }
+    return false;
   }
-  clearPongTimer() {
-    if (!this.pongTimer) return;
-    clearTimeout(this.pongTimer);
-    this.pongTimer = null;
+  /** Host-driven re-acquisition (after the buyer signs in again, say). */
+  async refresh(reason = "manual") {
+    __privateSet(this, _terminal, null);
+    __privateSet(this, _lastFailure, null);
+    __privateSet(this, _token, null);
+    __privateSet(this, _expiresAt, 0);
+    return !!await __privateMethod(this, _BuyerAccessContext_instances, renew_fn).call(this, reason);
   }
-  clearTimers() {
-    if (this.pingTimer) clearInterval(this.pingTimer);
-    this.pingTimer = null;
-    this.clearPongTimer();
-    if (this.reconnectTimer) clearTimeout(this.reconnectTimer);
-    this.reconnectTimer = null;
-    if (this.resumeTimer) clearTimeout(this.resumeTimer);
-    this.resumeTimer = null;
+  /** Drop the bearer. Called on destroy so nothing outlives the widget. */
+  clear() {
+    __privateSet(this, _token, null);
+    __privateSet(this, _expiresAt, 0);
+    __privateSet(this, _inflight, null);
+  }
+  /** Redaction: the bearer must not survive a stringify or an interpolation. */
+  toJSON() {
+    return { configured: this.configured, hasToken: this.hasToken };
+  }
+  toString() {
+    return "[BuyerAccessContext redacted]";
   }
 };
-function rendererStatus(wire) {
-  if (wire === "blocked") return "not_for_sale";
-  if (wire === "held" || wire === "booked" || wire === "free" || wire === "not_for_sale") return wire;
-  return "free";
-}
-function createControllerSink(controller, options = {}) {
-  const idsForLabel = (label) => {
-    const table = controller.tableSelection(label);
-    if (table) return table.physicalSeatIds;
-    const id = controller.idForLabel(label);
-    return id ? [id] : [];
-  };
-  return {
-    applyStatuses(changes) {
-      const held = controller.currentHold()?.labels ?? [];
-      const buckets = {
-        free: [],
-        held: [],
-        booked: [],
-        not_for_sale: []
-      };
-      const flashes = [];
-      const lost = [];
-      const selected = new Map(controller.getSelection().map((s) => [s.label, s.id]));
-      for (const change of changes) {
-        const ids = idsForLabel(change.label);
-        if (!ids.length) continue;
-        const next = rendererStatus(change.status);
-        buckets[next].push(...ids);
-        if (options.flashOnLiveChange && next !== "free" && !held.includes(change.label) && ids.some((id) => controller.getStatus(id) === "free")) {
-          const color = next === "held" ? "#f4b740" : "#f43f5e";
-          for (const id of ids) flashes.push({ id, color });
-        }
-        if (next !== "free" && !held.includes(change.label) && selected.has(change.label)) {
-          lost.push(change.label);
-        }
-      }
-      for (const status of ["free", "held", "booked", "not_for_sale"]) {
-        if (buckets[status].length) controller.setStatus(buckets[status], status);
-      }
-      for (const flash of flashes) controller.flashSeat(flash.id, flash.color);
-      if (lost.length) {
-        const ids = lost.flatMap((label) => idsForLabel(label));
-        if (ids.length) controller.deselect(ids);
-        const ineligible = changes.some(
-          (c) => c.status === "blocked" && lost.includes(c.label)
-        );
-        options.onSelectedObjectUnavailable?.(lost, ineligible ? "ineligible" : "taken");
+_token = new WeakMap();
+_expiresAt = new WeakMap();
+_provider = new WeakMap();
+_skewMs = new WeakMap();
+_inflight = new WeakMap();
+_terminal = new WeakMap();
+_lastFailure = new WeakMap();
+_onExpired = new WeakMap();
+_onUnavailable = new WeakMap();
+_configured = new WeakMap();
+_BuyerAccessContext_instances = new WeakSet();
+// ---- internals ------------------------------------------------------------
+accept_fn = function(next) {
+  if (!next || typeof next.token !== "string" || !next.token) return null;
+  __privateSet(this, _token, next.token);
+  __privateSet(this, _expiresAt, typeof next.expiresAt === "number" ? next.expiresAt : 0);
+  return __privateGet(this, _token);
+};
+/**
+ * One provider call at a time. Several operations racing an expiry (chart +
+ * objects + a socket ticket) must not mint several sessions — the guide's
+ * rotate-on-retry rule would revoke the ones they didn't observe.
+ */
+renew_fn = function(reason, code) {
+  if (__privateGet(this, _inflight)) return __privateGet(this, _inflight);
+  const provider = __privateGet(this, _provider);
+  if (!provider) {
+    __privateMethod(this, _BuyerAccessContext_instances, fail_fn).call(this, "no_token", code);
+    return Promise.resolve(null);
+  }
+  const run = (async () => {
+    try {
+      const next = await provider({ reason });
+      const token = __privateMethod(this, _BuyerAccessContext_instances, accept_fn).call(this, next);
+      if (!token) {
+        __privateMethod(this, _BuyerAccessContext_instances, fail_fn).call(this, "provider_failed", code);
+        return null;
       }
-      options.onStatusChange?.();
-    },
-    async resync() {
-      await controller.refresh();
-    },
-    /**
-     * Section availability moved. Statuses are re-pulled so the map repaints.
-     *
-     * Known limit: rebuilding the chart when a section is newly HIDDEN (its
-     * seats are stripped, not greyed) lives inside PickerController's own
-     * socket handler and has no public entry point, so an access-scoped picker
-     * repaints statuses but does not restructure the chart until its next
-     * mount. Closing/opening a section — the common mid-sale move — is a
-     * status-level change and is handled here in full.
-     */
-    onSections(hidden, closed) {
-      void controller.refresh();
-      options.onSections?.(hidden, closed);
+      return token;
+    } catch {
+      __privateMethod(this, _BuyerAccessContext_instances, fail_fn).call(this, "provider_failed", code);
+      return null;
+    } finally {
+      __privateSet(this, _inflight, null);
     }
+  })();
+  __privateSet(this, _inflight, run);
+  return run;
+};
+fail_fn = function(reason, code, status) {
+  var _a;
+  const event = {
+    reason,
+    code,
+    status,
+    // Unchanged: `retryable` means "the SAME request may succeed later".
+    // `provider_failed` is recoverable but not retryable — the host must fix
+    // its mint endpoint first — so the two sets are deliberately different.
+    retryable: reason === "paused" || reason === "channel_denied"
   };
+  __privateSet(this, _lastFailure, event);
+  if (!RECOVERABLE.has(reason)) {
+    __privateSet(this, _terminal, event);
+    __privateSet(this, _token, null);
+    __privateSet(this, _expiresAt, 0);
+  }
+  (_a = __privateGet(this, _onUnavailable)) == null ? void 0 : _a.call(this, event);
+  return event;
+};
+function createBuyerAccessContext(options, hooks = {}) {
+  if (!options.buyerAccessTokenProvider && !options.buyerAccessToken) return null;
+  return new BuyerAccessContext({
+    provider: options.buyerAccessTokenProvider,
+    token: options.buyerAccessToken,
+    ...hooks
+  });
 }
 
 // src/seatLayerBrand.ts
@@ -1250,6 +1329,7 @@ var SeatingChart = class {
     this.mount = null;
     this.hostEl = null;
     this.rendered = false;
+    this.retryBtn = null;
     this.mode_ = null;
     this.tipEl = null;
     this.tipPos = { x: 0, y: 0 };
@@ -1311,6 +1391,7 @@ var SeatingChart = class {
     const info = await this.controller.render(host);
     if (!info) {
       this.rendered = false;
+      if (this.opts.errorDisplay !== "none") this.showLoadFailure(host);
       return this;
     }
     this.controller.setViewMode(this.opts.initialView ?? "flat");
@@ -1601,10 +1682,36 @@ var SeatingChart = class {
     }
     return ok;
   }
+  /**
+   * The visible failure state. Deliberately inline-styled and dependency-free:
+   * this renders on a stranger's website, where our stylesheet may not have
+   * loaded (the chart fetch just failed) and where inheriting the host's own
+   * styles is likelier to produce something unreadable than something on-brand.
+   */
+  showLoadFailure(host) {
+    const box = document.createElement("div");
+    box.setAttribute("role", "status");
+    box.style.cssText = 'display:flex;flex-direction:column;align-items:center;justify-content:center;gap:12px;width:100%;height:100%;min-height:180px;box-sizing:border-box;padding:24px;text-align:center;font:500 14px/1.5 -apple-system,BlinkMacSystemFont,"Segoe UI",sans-serif;color:#3b4256;';
+    const text = document.createElement("div");
+    text.textContent = "The seat map didn\u2019t load.";
+    box.appendChild(text);
+    const btn = document.createElement("button");
+    btn.type = "button";
+    btn.textContent = "Try again";
+    btn.style.cssText = "appearance:none;border:1px solid #c9cede;background:#fff;color:#10162a;border-radius:8px;padding:8px 16px;font:600 13px/1 inherit;cursor:pointer;";
+    btn.addEventListener("click", () => {
+      this.destroy();
+      void this.render().catch((err) => this.opts.onError?.(err));
+    });
+    box.appendChild(btn);
+    this.retryBtn = btn;
+    host.appendChild(box);
+  }
   destroy() {
     this.realtime?.stop();
     this.realtime = null;
     this.access?.clear();
+    this.retryBtn = null;
     if (this.hostEl && this.onTipMove) this.hostEl.removeEventListener("mousemove", this.onTipMove);
     this.tipEl = null;
     this.onTipMove = null;
@@ -5783,7 +5890,15 @@ var SeatPicker = class _SeatPicker {
     this.checkoutPanel = mountCheckout2({
       root: this.root,
       state,
-      startSession: (input) => this.pubApi.startCheckout(this.opts.event, input),
+      // `returnUrl` rides along so a redirecting gateway can come back to the
+      // HOST's page. The server validates its origin against the organizer's
+      // declared embed domains and silently falls back to our own buyer page
+      // when it does not match, so passing one can never redirect a paid buyer
+      // somewhere the organizer did not sanction.
+      startSession: (input) => this.pubApi.startCheckout(this.opts.event, {
+        ...input,
+        ...this.opts.returnUrl ? { returnUrl: this.opts.returnUrl } : {}
+      }),
       orderStatus: (orderId) => this.pubApi.orderStatus(orderId),
       onCancel: () => {
         this.checkoutPanel = null;