@50arms/ui 0.0.0-stage → 35.2.0

package/dist/lib/reads/slots.js

@@ -0,0 +1,215 @@
+import { devWarn as H } from "../dev-warn.js";
+import { subscribeToKey as R, retainKeys as v, readState as O, isBaseTombstoned as M } from "../records/store.js";
+import { subscriptionKey as j, subscribeToRealtimeEvents as z } from "../realtime/registry.js";
+const y = Object.freeze({
+  items: Object.freeze([]),
+  pending: Object.freeze([]),
+  pendingCount: 0,
+  meta: void 0,
+  keys: Object.freeze([])
+});
+function W() {
+  return y;
+}
+const c = /* @__PURE__ */ new Map();
+let h = 0;
+function Y() {
+  return h;
+}
+const u = /* @__PURE__ */ new Map();
+let f = null;
+function C() {
+  f || (f = z((t) => {
+    t.isCreate && P(t);
+  }));
+}
+function B() {
+  c.size > 0 || !f || (f(), f = null);
+}
+function _(t, e) {
+  const n = x(e.type, e.createdScope);
+  let s = c.get(t);
+  s || (s = {
+    id: t,
+    type: e.type,
+    tag: e.tag,
+    created: n,
+    keys: [],
+    pending: [],
+    optimisticHead: [],
+    optimisticTail: [],
+    awaitingSettle: [],
+    held: /* @__PURE__ */ new Set(),
+    answered: /* @__PURE__ */ new Map(),
+    meta: void 0,
+    refs: 0,
+    memberReleases: [],
+    retainRelease: null,
+    snapshot: null,
+    dirty: !0
+  }, c.set(t, s)), s.type = e.type, s.tag = e.tag, s.created = n, s.refs += 1, C();
+  let a = !1;
+  return () => {
+    if (a) return;
+    a = !0;
+    const i = c.get(t);
+    if (i && (i.refs -= 1, !(i.refs > 0))) {
+      for (const r of i.memberReleases) r();
+      i.memberReleases = [], i.retainRelease?.(), i.retainRelease = null, c.delete(t), B();
+    }
+  };
+}
+function D(t, e, n, s = [], a = h) {
+  const i = c.get(t);
+  if (!i) return;
+  const r = new Set(e), o = /* @__PURE__ */ new Set();
+  if (i.optimisticHead.length > 0 || i.optimisticTail.length > 0) {
+    const l = new Set(i.keys.filter((d) => !i.held.has(d)));
+    for (const d of r) !l.has(d) && !i.pending.includes(d) && o.add(d);
+  }
+  const m = [], b = [];
+  for (const [l, d] of i.answered)
+    r.has(l) || (d.at > a ? (d.head ? m : b).push(l) : i.answered.delete(l));
+  i.keys = [...m.reverse(), ...e, ...b], i.held = o;
+  const S = /* @__PURE__ */ new Set([...i.keys, ...s]);
+  i.pending = i.pending.filter((l) => !S.has(l)), i.awaitingSettle = i.awaitingSettle.filter((l) => !S.has(l)), i.meta = n, g(i), p(i);
+}
+function F(t) {
+  const e = c.get(t);
+  !e || e.meta === void 0 || (e.meta = void 0, p(e));
+}
+function G(t) {
+  return c.get(t)?.pending ?? y.keys;
+}
+function P(t) {
+  const e = t.key;
+  if (e) {
+    for (const n of c.values())
+      if (!(n.type !== t.type || !$(n, t)) && !(n.keys.includes(e) || n.pending.includes(e) || n.awaitingSettle.includes(e))) {
+        if (n.optimisticHead.length > 0 || n.optimisticTail.length > 0) {
+          n.awaitingSettle = [...n.awaitingSettle, e];
+          continue;
+        }
+        n.pending = [...n.pending, e], g(n), p(n);
+      }
+  }
+}
+function $(t, e) {
+  const n = t.created;
+  return n ? n.scope.kind === "all" ? !0 : n.scope.kind === "ids" ? n.scope.ids.includes(String(e.payload.id)) : e.subscriptions === void 0 ? (H(
+    "realtime",
+    `a "${e.event}" for ${e.type} carried no subscription attribution, so a list filtered by ${n.key} cannot tell which subscription it was sent for, and does not count it. The transport needs \`subscriptionsOf\`, and the server has to name the subscriptions an event satisfied.`
+  ), !1) : e.subscriptions.includes(n.key) : !1;
+}
+function x(t, e) {
+  return e === void 0 ? null : { scope: e, key: j(t, e) };
+}
+function g(t) {
+  for (const n of t.memberReleases) n();
+  const e = w(t);
+  t.memberReleases = e.map((n) => R(n, () => A(t))), t.retainRelease?.(), t.retainRelease = v(e);
+}
+function A(t) {
+  c.has(t.id) && (E(t), p(t));
+}
+function E(t) {
+  const e = (o) => M(o), n = t.keys.filter((o) => !e(o)), s = t.pending.filter((o) => !e(o)), a = t.awaitingSettle.filter((o) => !e(o)), i = [...t.held].filter((o) => !e(o)), r = [...t.answered].filter(([o]) => !e(o));
+  n.length === t.keys.length && s.length === t.pending.length && a.length === t.awaitingSettle.length || (t.keys = n, t.pending = s, t.awaitingSettle = a, t.held = new Set(i), t.answered = new Map(r), g(t));
+}
+function p(t) {
+  t.dirty = !0;
+  const e = u.get(t.id);
+  if (e)
+    for (const n of [...e]) n();
+}
+function J(t, e, n, s) {
+  const a = [];
+  for (const i of c.values()) {
+    if (i.type !== e) continue;
+    const r = { id: i.id, type: i.type, tag: i.tag };
+    n && !n(r) || (s === "start" ? i.optimisticHead = [t, ...i.optimisticHead] : i.optimisticTail = [...i.optimisticTail, t], g(i), p(i), a.push(r));
+  }
+  return a;
+}
+function Q(t, e) {
+  for (const n of c.values()) {
+    const s = n.optimisticHead.includes(t), a = n.optimisticTail.includes(t);
+    if (!(!s && !a)) {
+      if (n.optimisticHead = n.optimisticHead.filter((i) => i !== t), n.optimisticTail = n.optimisticTail.filter((i) => i !== t), e !== null && (n.pending = n.pending.filter((i) => i !== e), n.awaitingSettle = n.awaitingSettle.filter((i) => i !== e), n.held.delete(e), n.keys.includes(e) || (n.keys = s ? [e, ...n.keys] : [...n.keys, e]), h += 1, n.answered.set(e, { at: h, head: s })), n.optimisticHead.length === 0 && n.optimisticTail.length === 0) {
+        n.held = /* @__PURE__ */ new Set();
+        const i = n.awaitingSettle;
+        n.awaitingSettle = [];
+        for (const r of i)
+          !n.keys.includes(r) && !n.pending.includes(r) && (n.pending = [...n.pending, r]);
+      }
+      g(n), p(n);
+    }
+  }
+}
+function w(t) {
+  return [...t.optimisticHead, ...t.keys, ...t.optimisticTail, ...t.pending, ...t.awaitingSettle];
+}
+function U(t, e) {
+  let n = u.get(t);
+  return n || (n = /* @__PURE__ */ new Set(), u.set(t, n)), n.add(e), () => {
+    const s = u.get(t);
+    s && (s.delete(e), s.size === 0 && u.delete(t));
+  };
+}
+function V(t) {
+  const e = c.get(t);
+  return e ? w(e) : y.keys;
+}
+function X(t) {
+  const e = c.get(t);
+  if (!e) return y;
+  if (!e.dirty && e.snapshot) return e.snapshot;
+  const n = e.keys.filter((m) => !e.held.has(m)), s = k([...e.optimisticHead, ...n, ...e.optimisticTail], e.tag), a = k(e.pending, e.tag), i = w(e), r = e.snapshot;
+  if (e.dirty = !1, r && T(r.items, s) && T(r.pending, a) && r.pendingCount === e.pending.length && r.meta === e.meta && I(r.keys, i))
+    return r;
+  const o = Object.freeze({
+    items: Object.freeze(s),
+    pending: Object.freeze(a),
+    pendingCount: e.pending.length,
+    meta: e.meta,
+    keys: Object.freeze(i)
+  });
+  return e.snapshot = o, o;
+}
+function k(t, e) {
+  const n = [];
+  for (const s of t) {
+    const a = O(s, e);
+    a.status === "present" && n.push(a.record);
+  }
+  return n;
+}
+function T(t, e) {
+  return t.length === e.length && t.every((n, s) => n === e[s]);
+}
+function I(t, e) {
+  return t.length === e.length && t.every((n, s) => n === e[s]);
+}
+function Z() {
+  for (const t of c.values()) {
+    for (const e of t.memberReleases) e();
+    t.retainRelease?.();
+  }
+  c.clear(), u.clear(), f?.(), f = null;
+}
+export {
+  _ as acquireSlot,
+  J as addOptimisticMember,
+  P as appendCreated,
+  F as clearSlotMeta,
+  W as emptySlotSnapshot,
+  X as readSlot,
+  Z as resetSlots,
+  Q as settleOptimisticMember,
+  Y as slotAnswerMark,
+  V as slotKeys,
+  G as slotPendingKeys,
+  U as subscribeToSlot,
+  D as writeSlot
+};
+//# sourceMappingURL=slots.js.map

package/dist/lib/reads/slots.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"slots.js","sources":["../../../src/lib/reads/slots.ts"],"sourcesContent":["import { devWarn } from \"../dev-warn\";\nimport { readState, retainKeys, subscribeToKey } from \"../records\";\nimport { isBaseTombstoned } from \"../records/store\";\nimport { subscribeToRealtimeEvents, subscriptionKey } from \"../realtime\";\nimport type { RealtimeEvent, RealtimeScope } from \"../realtime\";\n\n/* ============================================================================\n   LIST SLOTS — the root-query cache a normalized store cannot do without.\n\n   THE OMISSION THIS CLOSES. Normalization gives an identity map; every design\n   this one is modelled on ALSO keeps a record of which keys answered which\n   query, and leaving that out is how a `created` broadcast writes a record into\n   the store where it is INVISIBLE, because no list holds its key. A slot is\n   that record: `{keys, meta, tag}`, keyed by the query's serialized form.\n\n   WRITTEN ONLY BY A FETCH. Sort position and page boundary are the server's to\n   decide, so the ordered key list can only come from an answer the server gave.\n\n   IT IS ALSO WHERE `meta` LIVES — totals, per-page, cursors. Those carry no\n   `__type` and no `id`, so they can never be records, and a store with nowhere\n   to put them leaves a screen unable to render its own page count.\n\n   AND IT IS AN EVICTION ROOT. A key is retained if it is REACHABLE from a root,\n   and a live slot is the root most easily missed: miss it and the sweep evicts\n   the twenty-five records the list is rendering right now.\n\n   TWO EVENTS CHANGE MEMBERSHIP WITHOUT A FETCH, and only two (an optimistic create's answer is\n   the reader's own write, covered under `settleOptimisticMember`):\n\n     - A TOMBSTONE removes the key from EVERY slot, immediately. That is\n       mechanically what \"the row is gone everywhere\" means, and it is the one\n       case where a broadcast is authoritative about membership.\n     - A `created` event APPENDS with position unknown. It never guesses a\n       position, because guessing is the lie the rule exists to prevent. And it\n       appends only to a slot that DECLARED the scope the record entered\n       (`createdScope`), because the channel is per type per tenant: an event\n       arrives whenever ANY subscription on the tenant matched, so arrival\n       alone says nothing about which list the record belongs to.\n\n   A FETCH SETTLES WHAT WAS PENDING WHEN IT WAS ISSUED. A key it placed on this\n   page stops being pending because the page holds it; a key it did NOT place\n   stops too, because the server has answered for it — it sorted onto another\n   page, or no longer matches. Only a key that arrived after the request went\n   out stays pending, because that answer may predate it.\n\n   A FETCH CANNOT TELL THE READER'S OWN ROW FROM ANOTHER'S WHILE A CREATE IS OUT (DXUI-82). An\n   optimistic create shows a pending row under a temporary key; the server's copy of it carries a\n   real key sharing nothing with that one. So while a create in this slot is unanswered, a page\n   row the slot was not already showing is HELD: kept in `keys`, at the position the server gave\n   it, but not rendered, until the create settles. The other way round, a read issued before a\n   create's answer may land after it, without the row: the answer is remembered in `answered`\n   under a rising counter, and only a read issued after it can remove the row.\n   ========================================================================= */\n\nexport interface SlotSnapshot<T = unknown, TMeta = unknown> {\n  readonly items: readonly T[];\n  readonly pending: readonly T[];\n  readonly pendingCount: number;\n  readonly meta: TMeta | undefined;\n  /** Every key the slot holds, fetched and pending. The refetch roots. */\n  readonly keys: readonly string[];\n}\n\nconst EMPTY_SNAPSHOT: SlotSnapshot = Object.freeze({\n  items: Object.freeze([]),\n  pending: Object.freeze([]),\n  pendingCount: 0,\n  meta: undefined,\n  keys: Object.freeze([]),\n});\n\n/** `getServerSnapshot`, and the answer for a slot nothing has written yet. */\nexport function emptySlotSnapshot(): SlotSnapshot {\n  return EMPTY_SNAPSHOT;\n}\n\n/** The scope whose `created` events enter a slot, and its registry key. */\ninterface CreatedMembership {\n  readonly scope: RealtimeScope;\n  /** `subscriptionKey(type, scope)` — what `RealtimeEvent.subscriptions` names. */\n  readonly key: string;\n}\n\ninterface Slot {\n  readonly id: string;\n  type: string;\n  tag: string;\n  /** `null` — the slot never takes a `created` event. */\n  created: CreatedMembership | null;\n  /** The fetched page, in the server's order. */\n  keys: string[];\n  /** Appended by a `created` event. Position unknown, deliberately. */\n  pending: string[];\n  /** Optimistic creates shown ABOVE the fetched page — see `addOptimisticMember`. */\n  optimisticHead: string[];\n  /** Optimistic creates shown BELOW the fetched page. */\n  optimisticTail: string[];\n  /**\n   * Page keys held out of `items` while a create is unanswered (DXUI-82). Always members of\n   * `keys`: they keep the server's position and stay retained, subscribed and refetch roots.\n   */\n  held: Set<string>;\n  /**\n   * Real keys of optimistic creates answered in this slot: the answer's place in the module-level\n   * counter, and whether the row was shown at the head. A read issued before `at` may not remove\n   * the row; one issued at or after it is the server's word.\n   */\n  answered: Map<string, { at: number; head: boolean }>;\n  /**\n   * `created` events held back because an optimistic create of this slot's type was still\n   * outstanding when they arrived — see `appendCreated`'s own docblock (SG-982).\n   */\n  awaitingSettle: string[];\n  meta: unknown;\n  refs: number;\n  memberReleases: (() => void)[];\n  retainRelease: (() => void) | null;\n  snapshot: SlotSnapshot | null;\n  dirty: boolean;\n}\n\nconst slots = new Map<string, Slot>();\n\n/**\n * Orders answers against reads. Module-level, never per slot: StrictMode drops and re-creates a\n * slot while a read is out, and that read's mark must still compare against later answers.\n */\nlet answerCounter = 0;\n\n/** The mark a read takes BEFORE its request goes out; `writeSlot` receives it with the page. */\nexport function slotAnswerMark(): number {\n  return answerCounter;\n}\n\n/**\n * Listeners live OUTSIDE the slot, keyed by id.\n *\n * Because `useSyncExternalStore` subscribes at its own hook position, which can\n * be before the effect that claims the slot: a listener set that only existed\n * once the slot did would silently drop that subscription, and the list would\n * render once and then never again. Nothing about that failure is visible.\n */\nconst slotListeners = new Map<string, Set<() => void>>();\n\n/* --- The created-event bridge ---------------------------------------------- */\n\nlet createdBridge: (() => void) | null = null;\n\n/**\n * Listen for `created` broadcasts, lazily.\n *\n * INSTALLED ON THE FIRST SLOT, NOT ON IMPORT, and removed with the last one. A\n * module that wires itself up because somebody imported it does so in every\n * consumer, including the ones that never render a list.\n */\nfunction ensureCreatedBridge(): void {\n  if (createdBridge) return;\n  createdBridge = subscribeToRealtimeEvents((event) => {\n    if (!event.isCreate) return;\n    appendCreated(event);\n  });\n}\n\nfunction releaseCreatedBridgeIfIdle(): void {\n  if (slots.size > 0 || !createdBridge) return;\n  createdBridge();\n  createdBridge = null;\n}\n\n/* --- Lifecycle -------------------------------------------------------------- */\n\n/**\n * Claim a slot for the duration of the returned release.\n *\n * REFCOUNTED AND IDEMPOTENT, which is what makes StrictMode's mount / unmount /\n * mount leave the slot — and its retained keys — exactly as it found them.\n */\nexport function acquireSlot(\n  id: string,\n  options: { type: string; tag: string; createdScope?: RealtimeScope },\n): () => void {\n  const created = membershipOf(options.type, options.createdScope);\n  let slot = slots.get(id);\n  if (!slot) {\n    slot = {\n      id,\n      type: options.type,\n      tag: options.tag,\n      created,\n      keys: [],\n      pending: [],\n      optimisticHead: [],\n      optimisticTail: [],\n      awaitingSettle: [],\n      held: new Set(),\n      answered: new Map(),\n      meta: undefined,\n      refs: 0,\n      memberReleases: [],\n      retainRelease: null,\n      snapshot: null,\n      dirty: true,\n    };\n    slots.set(id, slot);\n  }\n  slot.type = options.type;\n  slot.tag = options.tag;\n  slot.created = created;\n  slot.refs += 1;\n  ensureCreatedBridge();\n\n  let released = false;\n  return () => {\n    if (released) return;\n    released = true;\n    const current = slots.get(id);\n    if (!current) return;\n    current.refs -= 1;\n    if (current.refs > 0) return;\n    for (const release of current.memberReleases) release();\n    current.memberReleases = [];\n    current.retainRelease?.();\n    current.retainRelease = null;\n    slots.delete(id);\n    releaseCreatedBridgeIfIdle();\n  };\n}\n\n/* --- Writing ---------------------------------------------------------------- */\n\n/**\n * Replace a slot's membership with a fetch's answer.\n *\n * A key that arrived through a `created` event and is now in the fetched page\n * stops being pending — the fetch has placed it, which is the only thing that\n * ever could.\n *\n * @param settled  the keys that were pending when this fetch was ISSUED\n *   (`slotPendingKeys`, read before the request). The answer covers them even\n *   when it does not hold them: a row that sorted onto another page is not\n *   \"new\" any more, it is placed — elsewhere. Without this a counted row that\n *   lands on page 2 stays \"1 new\" after Show, forever. A key appended after\n *   the request went out is not in this list, and stays pending.\n * @param mark  `slotAnswerMark()` read before the request went out. An optimistic create answered\n *   after it keeps its row though this page lacks it; a call without a mark counts as current.\n */\nexport function writeSlot(\n  id: string,\n  keys: readonly string[],\n  meta: unknown,\n  settled: readonly string[] = [],\n  mark: number = answerCounter,\n): void {\n  const slot = slots.get(id);\n  if (!slot) return;\n\n  const page = new Set(keys);\n  /* HELD (DXUI-82): while a create here is unanswered, a page row the slot was not already showing\n     may be the reader's own, under a key the slot cannot match to the pending row. It keeps the\n     server's place in `keys` and stays out of `items` until the create settles. */\n  const held = new Set<string>();\n  if (slot.optimisticHead.length > 0 || slot.optimisticTail.length > 0) {\n    const showing = new Set(slot.keys.filter((key) => !slot.held.has(key)));\n    for (const key of page) if (!showing.has(key) && !slot.pending.includes(key)) held.add(key);\n  }\n\n  /* ANSWERED CREATES: a read issued before an answer may not remove its row; one issued at or after\n     it is the server's word, and a row it leaves out leaves the slot for good. */\n  const restoredHead: string[] = [];\n  const restoredTail: string[] = [];\n  for (const [key, entry] of slot.answered) {\n    if (page.has(key)) continue;\n    if (entry.at > mark) (entry.head ? restoredHead : restoredTail).push(key);\n    else slot.answered.delete(key);\n  }\n\n  slot.keys = [...restoredHead.reverse(), ...keys, ...restoredTail];\n  slot.held = held;\n  const answered = new Set([...slot.keys, ...settled]);\n  slot.pending = slot.pending.filter((key) => !answered.has(key));\n  // A key a fetch just placed leaves the queue (SG-982): the page holds its place now. While a\n  // create is unanswered it may be that create's own row, so `held` above keeps it out of the render.\n  slot.awaitingSettle = slot.awaitingSettle.filter((key) => !answered.has(key));\n  slot.meta = meta;\n  resubscribeMembers(slot);\n  invalidate(slot);\n}\n\n/**\n * Forget what a slot's last answer said about the set (DXUI-87): its `meta`. A team switch empties\n * the store but not the slot, and a reader that takes `meta` as \"this query was answered\" would\n * otherwise draw the old team's totals, or an empty state, over a new team whose read failed.\n */\nexport function clearSlotMeta(id: string): void {\n  const slot = slots.get(id);\n  if (!slot || slot.meta === undefined) return;\n  slot.meta = undefined;\n  invalidate(slot);\n}\n\n/** The keys a slot is holding as pending right now — what a fetch issued now will settle. */\nexport function slotPendingKeys(id: string): readonly string[] {\n  return slots.get(id)?.pending ?? EMPTY_SNAPSHOT.keys;\n}\n\n/**\n * Append a record that entered the set elsewhere, to every slot it belongs to.\n *\n * WITH NO POSITION. The server owns sort order and page boundary; a client that\n * inserts at a guessed index renders a list that is subtly, confidently wrong.\n *\n * AND ONLY WHERE IT BELONGS — see `belongsTo`.\n *\n * ==== HELD BACK WHILE AN OPTIMISTIC CREATE OF THIS TYPE IS OUTSTANDING (SG-982) ====\n *\n * A row the reader just created optimistically has a TEMPORARY key here — the request that will\n * tell this slot the real one is still in flight. If the server's own `created` broadcast for\n * that same row reaches this client before that request answers (observed: the broadcast can\n * easily win the race against the reader's own round trip), it names the REAL key, which this\n * function cannot recognise as \"the row already shown\" — the two keys share no characters. Adding\n * it to `pending` right away would render it as a second row beside the optimistic one for\n * however long the request takes to settle, which is exactly the transient duplicate this guards\n * against.\n *\n * So while ANY optimistic create for this slot's type is outstanding (`optimisticHead` /\n * `optimisticTail` non-empty), an incoming `created` key is parked in `awaitingSettle` instead —\n * neither rendered nor counted — and `settleOptimisticMember` flushes it into `pending` the\n * instant the slot has no outstanding optimistic create left. If the parked key turns out to BE\n * the reader's own row, `settleOptimisticMember` already removes it before the flush ever runs\n * (see its own doc); if it turns out to be someone else's genuinely new row, it reaches `pending`\n * moments later, no worse than it would have anyway.\n *\n * This never suppresses a `created` broadcast outright, and it applies only during a real,\n * in-progress race — not a guess about which rows might collide, and not a fixed delay.\n */\nexport function appendCreated(event: RealtimeEvent): void {\n  const key = event.key;\n  if (!key) return;\n  for (const slot of slots.values()) {\n    if (slot.type !== event.type || !belongsTo(slot, event)) continue;\n    if (slot.keys.includes(key) || slot.pending.includes(key) || slot.awaitingSettle.includes(key)) continue;\n    if (slot.optimisticHead.length > 0 || slot.optimisticTail.length > 0) {\n      slot.awaitingSettle = [...slot.awaitingSettle, key];\n      continue;\n    }\n    slot.pending = [...slot.pending, key];\n    resubscribeMembers(slot);\n    invalidate(slot);\n  }\n}\n\n/**\n * Did this `created` record enter the set this slot lists?\n *\n * VERIFIED HERE WHEREVER THE CLIENT CAN, and taken from the server's\n * attribution only where it cannot:\n *\n *   - `all`    — every record of the type is in the set, by definition.\n *   - `ids`    — the record's id is in the list, or it is not.\n *   - `filter` — a predicate only the server evaluates. The CHANNEL cannot\n *     answer it: an event arrives when ANY subscription on the tenant matched,\n *     so a queue filtered to schema A hears schema B's demands whenever a\n *     teammate has an unfiltered list open (observed). Only\n *     `event.subscriptions` naming THIS scope answers it.\n *\n * An unattributed event on a filtered slot is NOT appended — the library cannot\n * verify membership, and a count it cannot verify is the defect this exists to\n * remove — and the development build says why, once.\n */\nfunction belongsTo(slot: Slot, event: RealtimeEvent): boolean {\n  const created = slot.created;\n  if (!created) return false;\n  if (created.scope.kind === \"all\") return true;\n  if (created.scope.kind === \"ids\") return created.scope.ids.includes(String(event.payload.id));\n  if (event.subscriptions === undefined) {\n    devWarn(\n      \"realtime\",\n      `a \"${event.event}\" for ${event.type} carried no subscription attribution, so a list filtered by ` +\n        `${created.key} cannot tell which subscription it was sent for, and does not count it. ` +\n        \"The transport needs `subscriptionsOf`, and the server has to name the subscriptions an event satisfied.\",\n    );\n    return false;\n  }\n  return event.subscriptions.includes(created.key);\n}\n\nfunction membershipOf(type: string, scope: RealtimeScope | undefined): CreatedMembership | null {\n  if (scope === undefined) return null;\n  return { scope, key: subscriptionKey(type, scope) };\n}\n\n/**\n * Every member key gets a subscription, and every member key is retained.\n *\n * THE SUBSCRIPTION IS HOW A TOMBSTONE REACHES THE SLOT — nothing else tells a\n * list that one of its rows is gone. It also covers the reverse case, which is\n * the one that fails silently: a key the slot holds but the store has NOT got a\n * record for yet still gets a listener, so the row appears the moment it\n * arrives rather than at the next unrelated re-render.\n */\nfunction resubscribeMembers(slot: Slot): void {\n  for (const release of slot.memberReleases) release();\n  const all = allKeys(slot);\n  slot.memberReleases = all.map((key) => subscribeToKey(key, () => onMemberChanged(slot)));\n  slot.retainRelease?.();\n  slot.retainRelease = retainKeys(all);\n}\n\nfunction onMemberChanged(slot: Slot): void {\n  if (!slots.has(slot.id)) return;\n  pruneTombstoned(slot);\n  invalidate(slot);\n}\n\n/** A tombstone removes the key from the slot itself, not only from the render. */\nfunction pruneTombstoned(slot: Slot): void {\n  /* The BASE tombstone, never an optimistic one: an optimistic delete hides the row through the\n     projection below, and must leave the key here so a rollback has a list to come back into. */\n  const gone = (key: string) => isBaseTombstoned(key);\n  const keys = slot.keys.filter((key) => !gone(key));\n  const pending = slot.pending.filter((key) => !gone(key));\n  const awaitingSettle = slot.awaitingSettle.filter((key) => !gone(key));\n  const held = [...slot.held].filter((key) => !gone(key));\n  const answered = [...slot.answered].filter(([key]) => !gone(key));\n  if (\n    keys.length === slot.keys.length &&\n    pending.length === slot.pending.length &&\n    awaitingSettle.length === slot.awaitingSettle.length\n  )\n    return;\n  slot.keys = keys;\n  slot.pending = pending;\n  slot.awaitingSettle = awaitingSettle;\n  slot.held = new Set(held);\n  slot.answered = new Map(answered);\n  resubscribeMembers(slot);\n}\n\nfunction invalidate(slot: Slot): void {\n  slot.dirty = true;\n  const listeners = slotListeners.get(slot.id);\n  if (!listeners) return;\n  for (const listener of [...listeners]) listener();\n}\n\n/* --- Optimistic creates ------------------------------------------------------- */\n\n/** What a create's `lists` predicate is shown about each live slot. */\nexport interface SlotDescriptor {\n  /** The list read's own `key`. */\n  readonly id: string;\n  readonly type: string;\n  readonly tag: string;\n}\n\n/**\n * Show an optimistic create in every slot that should list it, before the server has answered.\n *\n * AN OPTIMISTIC CREATE IS NOT A `created` EVENT, and it does not go into `pending`. `pending` is\n * the server telling a list \"this entered your set, position unknown\" and a screen may render it\n * as a \"1 new\" affordance; a create is the reader's OWN action, shown inline as a row the moment\n * it is made. It sits beside the fetched page — above it by default, where a new row is looked\n * for — in its own list, so a fetch landing while the create is in flight rewrites the page and\n * leaves the pending row standing. A page row the slot was not already showing is held out of the\n * render until the create settles (`writeSlot`), since it may be this create's own row.\n *\n * WHICH SLOTS is the caller's to say when it can: the library cannot evaluate a server-side\n * filter, so the default is every live slot of the record's type, and `lists` narrows it.\n *\n * @returns the slots the key joined — their tags are what the server's answer must satisfy for\n *   the real row to render in them.\n */\nexport function addOptimisticMember(\n  key: string,\n  type: string,\n  lists: ((slot: SlotDescriptor) => boolean) | undefined,\n  position: \"start\" | \"end\",\n): SlotDescriptor[] {\n  const joined: SlotDescriptor[] = [];\n  for (const slot of slots.values()) {\n    if (slot.type !== type) continue;\n    const descriptor: SlotDescriptor = { id: slot.id, type: slot.type, tag: slot.tag };\n    if (lists && !lists(descriptor)) continue;\n    if (position === \"start\") slot.optimisticHead = [key, ...slot.optimisticHead];\n    else slot.optimisticTail = [...slot.optimisticTail, key];\n    resubscribeMembers(slot);\n    invalidate(slot);\n    joined.push(descriptor);\n  }\n  return joined;\n}\n\n/**\n * An optimistic create has settled. With `realKey` (the server answered), the real row takes\n * the pending row's place — in the fetched page, so it stays put until the server next orders\n * the list. With `null` (the create failed), the pending row simply goes.\n *\n * THE ANSWER IS REMEMBERED (DXUI-82): `answered` keeps `realKey`, so a read issued before this\n * answer and landing after it cannot take the row away; and `held` page rows show once no create\n * here is unanswered, whether this one succeeded or failed.\n *\n * ALSO THE FLUSH POINT FOR `awaitingSettle` (SG-982): once this slot has no outstanding\n * optimistic create left, any `created` broadcasts `appendCreated` held back while this one was\n * in flight are released into `pending` — the race they were parked for is over. `realKey` itself\n * is removed from that queue first: if it is the reader's own echo, it has just been folded\n * straight into `keys` above and must never also reach `pending` as a second copy.\n */\nexport function settleOptimisticMember(tempKey: string, realKey: string | null): void {\n  for (const slot of slots.values()) {\n    const inHead = slot.optimisticHead.includes(tempKey);\n    const inTail = slot.optimisticTail.includes(tempKey);\n    if (!inHead && !inTail) continue;\n    slot.optimisticHead = slot.optimisticHead.filter((key) => key !== tempKey);\n    slot.optimisticTail = slot.optimisticTail.filter((key) => key !== tempKey);\n    if (realKey !== null) {\n      /* A `created` broadcast may have got here first and parked the row in `pending`; the\n         reader's own create answers for it now, so it moves into the page. */\n      slot.pending = slot.pending.filter((key) => key !== realKey);\n      slot.awaitingSettle = slot.awaitingSettle.filter((key) => key !== realKey);\n      slot.held.delete(realKey);\n      if (!slot.keys.includes(realKey)) slot.keys = inHead ? [realKey, ...slot.keys] : [...slot.keys, realKey];\n      /* Recorded also when a read already placed the row: an older read can still land without it. */\n      answerCounter += 1;\n      slot.answered.set(realKey, { at: answerCounter, head: inHead });\n    }\n    if (slot.optimisticHead.length === 0 && slot.optimisticTail.length === 0) {\n      /* The race is over: everything a page held back shows, after a failed create too. */\n      slot.held = new Set();\n      const deferred = slot.awaitingSettle;\n      slot.awaitingSettle = [];\n      for (const key of deferred) {\n        if (!slot.keys.includes(key) && !slot.pending.includes(key)) slot.pending = [...slot.pending, key];\n      }\n    }\n    resubscribeMembers(slot);\n    invalidate(slot);\n  }\n}\n\nfunction allKeys(slot: Slot): string[] {\n  return [...slot.optimisticHead, ...slot.keys, ...slot.optimisticTail, ...slot.pending, ...slot.awaitingSettle];\n}\n\n/* --- Reading ---------------------------------------------------------------- */\n\nexport function subscribeToSlot(id: string, listener: () => void): () => void {\n  let listeners = slotListeners.get(id);\n  if (!listeners) {\n    listeners = new Set();\n    slotListeners.set(id, listeners);\n  }\n  listeners.add(listener);\n  return () => {\n    const current = slotListeners.get(id);\n    if (!current) return;\n    current.delete(listener);\n    if (current.size === 0) slotListeners.delete(id);\n  };\n}\n\n/** The keys a slot holds right now — the roots a targeted refetch matches on. */\nexport function slotKeys(id: string): readonly string[] {\n  const slot = slots.get(id);\n  if (!slot) return EMPTY_SNAPSHOT.keys;\n  return allKeys(slot);\n}\n\n/**\n * The slot's projection, memoized to a stable reference.\n *\n * IT RECOMPUTES AND THEN COMPARES rather than trusting its dirty flag, because\n * a member notification does not always change what this slot renders — a\n * record whose field-set tag is still unsatisfied moves nothing here — and\n * handing back a fresh array for an unchanged list re-renders every consumer\n * for nothing. The elements themselves are the store's own reference-stable\n * snapshots, so comparing them is one identity check each.\n */\nexport function readSlot(id: string): SlotSnapshot {\n  const slot = slots.get(id);\n  if (!slot) return EMPTY_SNAPSHOT;\n  if (!slot.dirty && slot.snapshot) return slot.snapshot;\n\n  const shown = slot.keys.filter((key) => !slot.held.has(key));\n  const items = project([...slot.optimisticHead, ...shown, ...slot.optimisticTail], slot.tag);\n  const pending = project(slot.pending, slot.tag);\n  const keys = allKeys(slot);\n  const previous = slot.snapshot;\n  slot.dirty = false;\n\n  if (\n    previous &&\n    sameRefs(previous.items, items) &&\n    sameRefs(previous.pending, pending) &&\n    previous.pendingCount === slot.pending.length &&\n    previous.meta === slot.meta &&\n    sameStrings(previous.keys, keys)\n  ) {\n    return previous;\n  }\n\n  const next: SlotSnapshot = Object.freeze({\n    items: Object.freeze(items),\n    pending: Object.freeze(pending),\n    pendingCount: slot.pending.length,\n    meta: slot.meta,\n    keys: Object.freeze(keys),\n  });\n  slot.snapshot = next;\n  return next;\n}\n\n/**\n * Hydrate the members that are actually renderable.\n *\n * A KEY WITHOUT A SATISFIED TAG IS HELD BUT NOT RENDERED, and both halves\n * matter: dropping the key would lose a row the server told us about, while\n * rendering an unsatisfied record would hand a projection function a partial it\n * would misread as empty.\n */\nfunction project(keys: readonly string[], tag: string): unknown[] {\n  const out: unknown[] = [];\n  for (const key of keys) {\n    const state = readState(key, tag);\n    if (state.status === \"present\") out.push(state.record);\n  }\n  return out;\n}\n\nfunction sameRefs(a: readonly unknown[], b: readonly unknown[]): boolean {\n  return a.length === b.length && a.every((value, index) => value === b[index]);\n}\n\nfunction sameStrings(a: readonly string[], b: readonly string[]): boolean {\n  return a.length === b.length && a.every((value, index) => value === b[index]);\n}\n\n/** Test seam. Nothing in the library calls this. */\nexport function resetSlots(): void {\n  for (const slot of slots.values()) {\n    for (const release of slot.memberReleases) release();\n    slot.retainRelease?.();\n  }\n  slots.clear();\n  slotListeners.clear();\n  createdBridge?.();\n  createdBridge = null;\n}\n"],"names":["EMPTY_SNAPSHOT","emptySlotSnapshot","slots","answerCounter","slotAnswerMark","slotListeners","createdBridge","ensureCreatedBridge","subscribeToRealtimeEvents","event","appendCreated","releaseCreatedBridgeIfIdle","acquireSlot","id","options","created","membershipOf","slot","released","current","release","writeSlot","keys","meta","settled","mark","page","held","showing","key","restoredHead","restoredTail","entry","answered","resubscribeMembers","invalidate","clearSlotMeta","slotPendingKeys","belongsTo","devWarn","type","scope","subscriptionKey","all","allKeys","subscribeToKey","onMemberChanged","retainKeys","pruneTombstoned","gone","isBaseTombstoned","pending","awaitingSettle","listeners","listener","addOptimisticMember","lists","position","joined","descriptor","settleOptimisticMember","tempKey","realKey","inHead","inTail","deferred","subscribeToSlot","slotKeys","readSlot","shown","items","project","previous","sameRefs","sameStrings","next","tag","out","state","readState","a","b","value","index","resetSlots"],"mappings":"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"}

package/dist/lib/realtime/hooks.js

@@ -0,0 +1,40 @@
+import { useRef as f, useEffect as m, useSyncExternalStore as a, useCallback as i } from "react";
+import { useRealtimeRegistry as p } from "./provider.js";
+import { scopeKey as h, normalizeScope as b, subscribeToRealtimeEpoch as l, readRealtimeEpoch as E } from "./registry.js";
+function y(e, t, r) {
+  const o = p(), s = h(b(t)), c = [...r].sort().join(","), n = f({ scope: t, events: r });
+  n.current = { scope: t, events: r }, m(() => {
+    if (o)
+      return o.acquire(e.type, n.current.scope, n.current.events);
+  }, [o, e.type, s, c]);
+}
+const u = Object.freeze({
+  status: "unconfigured",
+  connection: "disconnected",
+  subscriptions: Object.freeze([]),
+  epoch: 0,
+  lastError: void 0
+});
+function d() {
+  const e = p(), t = i(
+    (s) => {
+      if (!e) return () => {
+      };
+      const c = e.subscribeToHealth(s), n = l(s);
+      return () => {
+        c(), n();
+      };
+    },
+    [e]
+  ), r = i(() => e ? e.readHealth() : u, [e]), o = i(() => u, []);
+  return a(t, r, o);
+}
+function H() {
+  return a(l, E, () => 0);
+}
+export {
+  y as useRealtime,
+  H as useRealtimeEpoch,
+  d as useRealtimeHealth
+};
+//# sourceMappingURL=hooks.js.map

package/dist/lib/realtime/hooks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hooks.js","sources":["../../../src/lib/realtime/hooks.ts"],"sourcesContent":["import { useCallback, useEffect, useRef, useSyncExternalStore } from \"react\";\nimport type { RecordTypeToken } from \"../records\";\nimport { useRealtimeRegistry } from \"./provider\";\nimport { normalizeScope, readRealtimeEpoch, scopeKey, subscribeToRealtimeEpoch } from \"./registry\";\nimport type { RealtimeHealth, RealtimeScopeInput } from \"./types\";\n\n/* ============================================================================\n   THE REALTIME HOOKS.\n\n   ONE SIGNATURE — `useRealtime(Token, scope, events)`. It took three attempts\n   to get here and each rejected version had the same shape of defect:\n\n     - `useChannel(channel, id, events)` conflated the socket channel with the\n       subscription. The channel is per type per tenant, so an `id` there is a\n       component joining another tenant's channel.\n     - a per-COMPONENT subscription would have a list of twenty-five rows\n       declaring twenty-five of them. Subscription belongs to the record SET,\n       not to the component, so the registry coalesces by (type, scope).\n     - the `events` axis was dropped from the signature while the very next\n       sentence required binding the union of them.\n\n   THE TOKEN RATHER THAN A STRING, so the type name and the tenancy both come\n   from registration and cannot drift from the record store's own key.\n   ========================================================================= */\n\n/**\n * Declare that this component is looking at these records and wants these\n * events.\n *\n * COALESCED. Twenty-five components asking for the same scope produce ONE\n * server-side registration, and the union of everyone's event names is bound —\n * never the first caller's only, which is the live defect this module was\n * written against.\n *\n * NO-OP WITHOUT A PROVIDER. An application with realtime switched off keeps\n * fetching and keeps rendering; nothing here throws.\n *\n * @param token   the record type, from `defineRecordType`\n * @param scope   `\"all\"`, an id list, or `{filter}` the server evaluates\n * @param events  event names to bind, e.g. `[\"created\", \"updated\", \"deleted\"]`\n */\nexport function useRealtime<T>(\n  token: RecordTypeToken<T>,\n  scope: RealtimeScopeInput,\n  events: readonly string[],\n): void {\n  const registry = useRealtimeRegistry();\n\n  /* Both are derived to STRINGS rather than depended on by identity, because\n     the natural call site builds a fresh array on every render — `ids.map(…)`,\n     `[\"created\",\"updated\"]` — and depending on identity would tear the\n     subscription down and rebuild it on every render, which for a subscription\n     whose teardown is deliberately a no-op means a resubscribe storm. */\n  const scopeSignature = scopeKey(normalizeScope(scope));\n  const eventSignature = [...events].sort().join(\",\");\n\n  /* The effect closes over the CURRENT `scope` and `events` while depending on\n     their signatures, which is the point: an equal-but-fresh array re-renders\n     and changes nothing here. */\n  const latest = useRef({ scope, events });\n  latest.current = { scope, events };\n\n  useEffect(() => {\n    if (!registry) return;\n    return registry.acquire(token.type, latest.current.scope, latest.current.events);\n  }, [registry, token.type, scopeSignature, eventSignature]);\n}\n\nconst IDLE_HEALTH: RealtimeHealth = Object.freeze({\n  status: \"unconfigured\" as const,\n  connection: \"disconnected\" as const,\n  subscriptions: Object.freeze([]),\n  epoch: 0,\n  lastError: undefined,\n});\n\n/**\n * The renderable liveness state.\n *\n * IT IS RENDERABLE ON PURPOSE. A dead subscription is indistinguishable from a\n * quiet one, and the prior art's answer — a console panel behind a keyboard\n * shortcut — is why two real bugs in it went unnoticed for years. This is the\n * equivalent of `refreshing`: a word the reader can see, not a log line.\n */\nexport function useRealtimeHealth(): RealtimeHealth {\n  const registry = useRealtimeRegistry();\n\n  const subscribe = useCallback(\n    (listener: () => void) => {\n      if (!registry) return () => {};\n      const stopHealth = registry.subscribeToHealth(listener);\n      /* The epoch lives module-side so the read binding can consume it without\n         a provider; health renders it, so it has to hear about both. */\n      const stopEpoch = subscribeToRealtimeEpoch(listener);\n      return () => {\n        stopHealth();\n        stopEpoch();\n      };\n    },\n    [registry],\n  );\n\n  const getSnapshot = useCallback(() => (registry ? registry.readHealth() : IDLE_HEALTH), [registry]);\n  const getServerSnapshot = useCallback(() => IDLE_HEALTH, []);\n\n  return useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);\n}\n\n/**\n * The \"you may have missed events\" counter, for a consumer that wants to fold\n * it into its own invalidation rather than use the read binding.\n *\n * IT IS A REVISION, NEVER A READ KEY. A key change blanks the screen to a\n * skeleton; a revision keeps the answer on screen and marks it refreshing. This\n * signal exists because a subscription went dead and came back — recovering\n * from that by blanking the screen is a worse experience than the staleness.\n */\nexport function useRealtimeEpoch(): number {\n  return useSyncExternalStore(subscribeToRealtimeEpoch, readRealtimeEpoch, () => 0);\n}\n"],"names":["useRealtime","token","scope","events","registry","useRealtimeRegistry","scopeSignature","scopeKey","normalizeScope","eventSignature","latest","useRef","useEffect","IDLE_HEALTH","useRealtimeHealth","subscribe","useCallback","listener","stopHealth","stopEpoch","subscribeToRealtimeEpoch","getSnapshot","getServerSnapshot","useSyncExternalStore","useRealtimeEpoch","readRealtimeEpoch"],"mappings":";;;AAyCO,SAASA,EACdC,GACAC,GACAC,GACM;AACN,QAAMC,IAAWC,EAAA,GAOXC,IAAiBC,EAASC,EAAeN,CAAK,CAAC,GAC/CO,IAAiB,CAAC,GAAGN,CAAM,EAAE,KAAA,EAAO,KAAK,GAAG,GAK5CO,IAASC,EAAO,EAAE,OAAAT,GAAO,QAAAC,GAAQ;AACvC,EAAAO,EAAO,UAAU,EAAE,OAAAR,GAAO,QAAAC,EAAA,GAE1BS,EAAU,MAAM;AACd,QAAKR;AACL,aAAOA,EAAS,QAAQH,EAAM,MAAMS,EAAO,QAAQ,OAAOA,EAAO,QAAQ,MAAM;AAAA,EACjF,GAAG,CAACN,GAAUH,EAAM,MAAMK,GAAgBG,CAAc,CAAC;AAC3D;AAEA,MAAMI,IAA8B,OAAO,OAAO;AAAA,EAChD,QAAQ;AAAA,EACR,YAAY;AAAA,EACZ,eAAe,OAAO,OAAO,EAAE;AAAA,EAC/B,OAAO;AAAA,EACP,WAAW;AACb,CAAC;AAUM,SAASC,IAAoC;AAClD,QAAMV,IAAWC,EAAA,GAEXU,IAAYC;AAAA,IAChB,CAACC,MAAyB;AACxB,UAAI,CAACb,EAAU,QAAO,MAAM;AAAA,MAAC;AAC7B,YAAMc,IAAad,EAAS,kBAAkBa,CAAQ,GAGhDE,IAAYC,EAAyBH,CAAQ;AACnD,aAAO,MAAM;AACX,QAAAC,EAAA,GACAC,EAAA;AAAA,MACF;AAAA,IACF;AAAA,IACA,CAACf,CAAQ;AAAA,EAAA,GAGLiB,IAAcL,EAAY,MAAOZ,IAAWA,EAAS,eAAeS,GAAc,CAACT,CAAQ,CAAC,GAC5FkB,IAAoBN,EAAY,MAAMH,GAAa,CAAA,CAAE;AAE3D,SAAOU,EAAqBR,GAAWM,GAAaC,CAAiB;AACvE;AAWO,SAASE,IAA2B;AACzC,SAAOD,EAAqBH,GAA0BK,GAAmB,MAAM,CAAC;AAClF;"}

package/dist/lib/realtime/provider.js

@@ -0,0 +1,25 @@
+import { jsx as m } from "react/jsx-runtime";
+import { useState as n, useRef as p, useEffect as i, useContext as l, createContext as R } from "react";
+import { SubscriptionRegistry as x } from "./registry.js";
+import { setRecordStoreTenant as a } from "../records/store.js";
+const s = R(null);
+function C({
+  transport: u,
+  tenant: e,
+  ownsStoreTenant: t = !0,
+  children: c,
+  ...f
+}) {
+  const [r] = n(() => new x({ transport: u, tenant: e, ...f })), o = p(e);
+  return i(() => (r.start(), () => r.stop()), [r]), i(() => {
+    o.current !== e && (o.current = e, r.setTenant(e)), t && a(e);
+  }, [r, e, t]), /* @__PURE__ */ m(s.Provider, { value: r, children: c });
+}
+function P() {
+  return l(s);
+}
+export {
+  C as RealtimeProvider,
+  P as useRealtimeRegistry
+};
+//# sourceMappingURL=provider.js.map

package/dist/lib/realtime/provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.js","sources":["../../../src/lib/realtime/provider.tsx"],"sourcesContent":["import { createContext, useContext, useEffect, useRef, useState, type ReactNode } from \"react\";\nimport { setRecordStoreTenant } from \"../records\";\nimport { SubscriptionRegistry, type RegistryOptions } from \"./registry\";\n\n/* ============================================================================\n   THE PROVIDER — where the injected transport and the tenant enter.\n\n   TENANCY IS THE PROVIDER'S, NEVER THE CALLER'S. The socket channel is\n   `Type.{tenant}` and is authorized as a tenant, so a component passing an id\n   of its own would join another tenant's channel — a hook signature that lets a\n   caller supply the wrong id is a tenancy bug with a convenient API. Here the\n   caller names a TYPE and a SCOPE; the tenant comes from one place.\n\n   THE STORE'S TENANT IS SET HERE TOO, because the two must move together. The\n   store keys records `Type:id` with no tenant in them, so team B's demand #7\n   would merge onto team A's — clearing the store handles what is already\n   written, and the `tenant` stamped on each write handles what is still in the\n   air. Setting one without the other leaves exactly half the guard.\n   ========================================================================= */\n\nconst RealtimeContext = createContext<SubscriptionRegistry | null>(null);\n\nexport interface RealtimeProviderProps\n  extends Omit<RegistryOptions, \"transport\" | \"tenant\" | \"now\"> {\n  /**\n   * Everything environment-specific in one object: socket, endpoints,\n   * connection observer. INJECTED, never imported — see `types.ts` for why, and\n   * for the one constraint on its implementation that a type cannot express.\n   */\n  readonly transport: RegistryOptions[\"transport\"];\n\n  /**\n   * The team, org or account these records belong to.\n   *\n   * CHANGING IT IS A REAL EVENT, not a re-render: every server-side\n   * registration is dropped, every channel is left, the record store is\n   * cleared, and everything still mounted re-subscribes under the new tenant.\n   */\n  readonly tenant?: string | number;\n\n  /**\n   * Whether this provider owns the record store's tenant. Default `true`.\n   *\n   * Set it false only when something else already calls\n   * `setRecordStoreTenant` — two writers of one value is how they disagree.\n   */\n  readonly ownsStoreTenant?: boolean;\n\n  readonly children: ReactNode;\n}\n\nexport function RealtimeProvider({\n  transport,\n  tenant,\n  ownsStoreTenant = true,\n  children,\n  ...options\n}: RealtimeProviderProps) {\n  const [registry] = useState(() => new SubscriptionRegistry({ transport, tenant, ...options }));\n  const appliedTenant = useRef<string | number | undefined>(tenant);\n\n  useEffect(() => {\n    registry.start();\n    /* `stop`, deliberately, NOT `dispose`: StrictMode's mount / unmount / mount\n       must leave exactly one subscription, and disposing here would drop live\n       registrations and re-issue them on the remount. */\n    return () => registry.stop();\n  }, [registry]);\n\n  useEffect(() => {\n    /* ORDER IS LOAD-BEARING. Tear the old registrations down first, then clear\n       the store: clearing first would leave a window where the old channel's\n       payloads write into a store that already claims to be the new tenant.\n\n       NOT DURING RENDER, and not in a layout effect either — both would run\n       before a child's own mount effect on the very first commit, but neither\n       is needed for correctness: a fetch stamps the tenant it read at REQUEST\n       time and resolves asynchronously, long after this has run. Mutating a\n       module store during render is the thing that reliably breaks later. */\n    if (appliedTenant.current !== tenant) {\n      appliedTenant.current = tenant;\n      registry.setTenant(tenant);\n    }\n    if (ownsStoreTenant) setRecordStoreTenant(tenant);\n  }, [registry, tenant, ownsStoreTenant]);\n\n  return <RealtimeContext.Provider value={registry}>{children}</RealtimeContext.Provider>;\n}\n\n/**\n * The registry, or `null` when no provider is mounted.\n *\n * THIS PACKAGE'S USUAL CONVENTION IS INVERTED HERE, DELIBERATELY. Every other\n * provider in this library throws when its hook is used outside it, and that is\n * right for a capability a component cannot work without. Realtime is not one:\n * an application with no transport configured must degrade to plain fetching,\n * never crash. A design system that hard-fails because an OPTIONAL capability\n * is absent is not offering an optional capability.\n */\nexport function useRealtimeRegistry(): SubscriptionRegistry | null {\n  return useContext(RealtimeContext);\n}\n"],"names":["RealtimeContext","createContext","RealtimeProvider","transport","tenant","ownsStoreTenant","children","options","registry","useState","SubscriptionRegistry","appliedTenant","useRef","useEffect","useRealtimeRegistry","useContext"],"mappings":";;;;AAoBA,MAAMA,IAAkBC,EAA2C,IAAI;AA+BhE,SAASC,EAAiB;AAAA,EAC/B,WAAAC;AAAA,EACA,QAAAC;AAAA,EACA,iBAAAC,IAAkB;AAAA,EAClB,UAAAC;AAAA,EACA,GAAGC;AACL,GAA0B;AACxB,QAAM,CAACC,CAAQ,IAAIC,EAAS,MAAM,IAAIC,EAAqB,EAAE,WAAAP,GAAW,QAAAC,GAAQ,GAAGG,EAAA,CAAS,CAAC,GACvFI,IAAgBC,EAAoCR,CAAM;AAEhE,SAAAS,EAAU,OACRL,EAAS,MAAA,GAIF,MAAMA,EAAS,KAAA,IACrB,CAACA,CAAQ,CAAC,GAEbK,EAAU,MAAM;AAUd,IAAIF,EAAc,YAAYP,MAC5BO,EAAc,UAAUP,GACxBI,EAAS,UAAUJ,CAAM,IAEvBC,OAAsCD,CAAM;AAAA,EAClD,GAAG,CAACI,GAAUJ,GAAQC,CAAe,CAAC,qBAE9BL,EAAgB,UAAhB,EAAyB,OAAOQ,GAAW,UAAAF,GAAS;AAC9D;AAYO,SAASQ,IAAmD;AACjE,SAAOC,EAAWf,CAAe;AACnC;"}