@aglyn/tenant-feature-instance 1.0.0-beta.217 → 1.0.0-beta.219

package/src/lib/hooks/firebase/firestore-multitab-wedge.js

@@ -0,0 +1,325 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ import { _ as _extends } from "@swc/helpers/_/_extends";
+/**
+ * A MULTI-TAB CACHE THAT ANOTHER TAB HAS LOCKED, AND THE WAY OUT (AGL-3428).
+ *
+ * ## The wedge the network cycle cannot clear
+ *
+ * `firestore-stall-recovery.ts` recovers a lapsed primary lease by cycling the
+ * network, which runs the lease election at once (AGL-3373). That needs the
+ * election's IndexedDB transaction to run. Measured against
+ * `@firebase/firestore` 4.17.2: `IndexedDbPersistence.runTransaction` opens
+ * EVERY transaction over EVERY object store (`getObjectStores(schemaVersion)`),
+ * so one tab that stops partway through a readwrite transaction — frozen or
+ * discarded by the browser while it runs — holds every store for every tab on
+ * the origin. Behind it, in every other tab:
+ *
+ * - the lease election waits, so the lease row is never renewed by anyone;
+ * - cache reads wait, so pages sit on their spinners;
+ * - the mutation-queue write waits, so a save never reaches the network;
+ * - a freshly opened tab's persistence `start()` waits, so a new tab hangs too;
+ * - `disableNetwork`, `enableNetwork` and `terminate` are queued on the same
+ *   AsyncQueue behind the stuck operation, so none of them ever runs.
+ *
+ * On 2026-09-30 production (beta.218) did exactly this three times in two
+ * hours: every console tab stopped, and the `owner` row named a background
+ * tab that had stopped renewing it.
+ *
+ * ## How it is told apart from a slow read
+ *
+ * Only after the network cycle, and only from a visible tab on a browser that
+ * reports a network. Such a tab wins a lapsed lease within one 4-second
+ * election tick, and the cycle has just forced one. So, after a short settle,
+ * the tab reads the `owner` row itself:
+ *
+ * - **the read cannot complete in time** — the store is locked by another
+ *   tab's open transaction; or
+ * - **the lease is older than {@link STALE_PRIMARY_LEASE_MS}** — no tab,
+ *   including this one, is completing an election.
+ *
+ * Either is the wedge. A fresh lease — this tab's or another's — is a healthy
+ * cache and a merely slow server, and nothing more happens.
+ *
+ * ## The way out
+ *
+ * The tab records a {@link MemoryCacheFallback} in `sessionStorage` and
+ * reloads. `firestoreCacheClassFor` reads it at startup and gives this tab the
+ * memory cache, which shares nothing with other tabs, so the locked database
+ * cannot reach it. `sessionStorage` is per tab: other tabs keep the durable
+ * cache, and the fallback leaves when this tab closes or after
+ * {@link MEMORY_CACHE_FALLBACK_TTL_MS}.
+ *
+ * A reload, not an in-place swap, because nothing in place can work: the
+ * wedged instance's `terminate()` is queued behind the stuck operation, a
+ * second instance for the same app throws until the first is gone, and
+ * hundreds of readers hold the instance from context and from closures.
+ * Nothing that could be saved is lost — the wedge had already stopped every
+ * write in the tab from leaving it.
+ */ /** `sessionStorage` key of this tab's memory-cache fallback. */ export const MEMORY_CACHE_FALLBACK_KEY = 'aglyn:firestore-memory-cache-fallback';
+/**
+ * How long a tab keeps the memory cache after falling back. The SDK's own
+ * inactivity horizon (`MAX_CLIENT_AGE_MS`), after which a tab that is still
+ * stuck no longer counts as a client; past it, a reload tries the durable
+ * cache again, and falls back again if it has to.
+ */ export const MEMORY_CACHE_FALLBACK_TTL_MS = 30 * 60 * 1000;
+/**
+ * A lease older than this, read from a visible online tab right after a
+ * forced election, means no election is completing. The SDK treats a lease as
+ * lapsed at 5 s (`MAX_PRIMARY_ELIGIBLE_AGE_MS`) and runs the election every
+ * 4 s; this is three times the first, so an election that is merely late is
+ * never mistaken for one that cannot run.
+ */ export const STALE_PRIMARY_LEASE_MS = 15000;
+/**
+ * How long the lease read may take before the store is judged locked. The
+ * SDK's own transactions take milliseconds.
+ */ export const LEASE_PROBE_TIMEOUT_MS = 4000;
+/**
+ * How long after the network cycle the lease is read, so the election the
+ * cycle queued has run.
+ */ export const LEASE_SETTLE_MS = 3000;
+/** The SDK's lease store and its single row's key (`DbPrimaryClientStore`, `DbPrimaryClientKey`). */ const OWNER_STORE = 'owner';
+const OWNER_KEY = 'owner';
+/**
+ * Reads the SDK's `owner` row from `databaseName`.
+ *
+ * Opens only a database that already exists, at whatever version it has (the
+ * same rule as `readHeartbeatClientIds`): `open(name)` on a missing database
+ * would create it at version 1 under the SDK. The connection serves one
+ * read-only request and is closed — also on `versionchange`, so it never
+ * holds up the SDK's own upgrade, and also when the read lands after the
+ * timeout.
+ */ export async function probePrimaryLease(factory, databaseName, { timeoutMs = LEASE_PROBE_TIMEOUT_MS, now = Date.now } = {}) {
+    if (!factory || typeof factory.databases !== 'function') return {
+        state: 'unknown'
+    };
+    try {
+        const databases = await factory.databases();
+        if (!databases.some((database)=>database.name === databaseName)) {
+            return {
+                state: 'unknown'
+            };
+        }
+    } catch (unused) {
+        return {
+            state: 'unknown'
+        };
+    }
+    return new Promise((resolve)=>{
+        let settled = false;
+        let database;
+        const settle = (probe)=>{
+            if (settled) return;
+            settled = true;
+            clearTimeout(timer);
+            resolve(probe);
+        };
+        const close = ()=>{
+            try {
+                database == null ? void 0 : database.close();
+            } catch (unused) {
+            // Already closed.
+            }
+        };
+        // Only a lock can hold a read-only request this long; the connection is
+        // closed when the request finally lands.
+        const timer = setTimeout(()=>settle({
+                state: 'locked'
+            }), timeoutMs);
+        let request;
+        try {
+            request = factory.open(databaseName);
+        } catch (unused) {
+            settle({
+                state: 'unknown'
+            });
+            return;
+        }
+        // The database was deleted between `databases()` and `open()`: abort the
+        // creation rather than leave the SDK an empty version-1 database.
+        request.onupgradeneeded = ()=>{
+            var _request_transaction;
+            return (_request_transaction = request.transaction) == null ? void 0 : _request_transaction.abort();
+        };
+        request.onerror = ()=>settle({
+                state: 'unknown'
+            });
+        request.onsuccess = ()=>{
+            database = request.result;
+            database.onversionchange = close;
+            if (settled || !database.objectStoreNames.contains(OWNER_STORE)) {
+                close();
+                settle({
+                    state: 'unknown'
+                });
+                return;
+            }
+            try {
+                const read = database.transaction(OWNER_STORE, 'readonly').objectStore(OWNER_STORE).get(OWNER_KEY);
+                read.onsuccess = ()=>{
+                    close();
+                    const row = read.result;
+                    if (!row || typeof row.ownerId !== 'string' || typeof row.leaseTimestampMs !== 'number') {
+                        settle({
+                            state: 'vacant'
+                        });
+                        return;
+                    }
+                    settle({
+                        state: 'leased',
+                        ownerId: row.ownerId,
+                        ageMs: now() - row.leaseTimestampMs
+                    });
+                };
+                read.onerror = ()=>{
+                    close();
+                    settle({
+                        state: 'unknown'
+                    });
+                };
+            } catch (unused) {
+                close();
+                settle({
+                    state: 'unknown'
+                });
+            }
+        };
+    });
+}
+/**
+ * Whether a lease read taken right after a forced election, from a visible
+ * online tab, shows the wedge. Anything that could be a healthy cache —
+ * a fresh lease, no lease row, an unreadable one — is not evidence.
+ */ export function wedgeEvidenceFrom(probe, staleMs = STALE_PRIMARY_LEASE_MS) {
+    if (probe.state === 'locked') return {
+        reason: 'lease-locked'
+    };
+    if (probe.state === 'leased' && probe.ageMs >= staleMs) {
+        return {
+            reason: 'lease-stale',
+            ownerId: probe.ownerId,
+            ageMs: probe.ageMs
+        };
+    }
+    return undefined;
+}
+/**
+ * This tab's fallback, or `undefined` when there is none, it has expired, or
+ * it does not parse.
+ */ export function readMemoryCacheFallback(storage, now, ttlMs = MEMORY_CACHE_FALLBACK_TTL_MS) {
+    let raw;
+    try {
+        var _ref;
+        raw = (_ref = storage == null ? void 0 : storage.getItem(MEMORY_CACHE_FALLBACK_KEY)) != null ? _ref : null;
+    } catch (unused) {
+        return undefined;
+    }
+    if (raw === null) return undefined;
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    } catch (unused) {
+        return undefined;
+    }
+    if (typeof parsed !== 'object' || parsed === null) return undefined;
+    const record = parsed;
+    if (typeof record.at !== 'number' || !Number.isFinite(record.at)) return undefined;
+    if (now - record.at >= ttlMs || record.at > now) return undefined;
+    return record;
+}
+const browserSessionStorage = ()=>{
+    try {
+        return typeof window === 'undefined' ? undefined : window.sessionStorage;
+    } catch (unused) {
+        // Site data blocked: reading `window.sessionStorage` throws.
+        return undefined;
+    }
+};
+/** Whether this browser tab is running on its memory-cache fallback. */ export function memoryCacheFallbackActive(now = Date.now()) {
+    return readMemoryCacheFallback(browserSessionStorage(), now) !== undefined;
+}
+const browserOnline = ()=>typeof navigator === 'undefined' || navigator.onLine !== false;
+const documentVisible = ()=>typeof document === 'undefined' || document.visibilityState !== 'hidden';
+/**
+ * The step `createStallRecovery` runs after its network cycle for a
+ * multi-tab client. Resolves `true` when it has moved the tab to the fallback.
+ * Never rejects.
+ */ export function createWedgeEscalation(deps) {
+    const { probe, fallBack, isFallbackActive = ()=>memoryCacheFallbackActive(), isOnline = browserOnline, isVisible = documentVisible, wait = (ms)=>new Promise((resolve)=>setTimeout(resolve, ms)), settleMs = LEASE_SETTLE_MS } = deps;
+    return async ()=>{
+        try {
+            if (isFallbackActive()) return false;
+            await wait(settleMs);
+            // Both guards again: the reader may have gone, or the network with it.
+            if (!isOnline() || !isVisible()) return false;
+            const evidence = wedgeEvidenceFrom(await probe());
+            if (!evidence) return false;
+            fallBack(evidence);
+            return true;
+        } catch (unused) {
+            return false;
+        }
+    };
+}
+/**
+ * Records the fallback for this tab and reloads it onto the memory cache.
+ * When the record cannot be written it does not reload: without it, the
+ * reloaded tab would open the same locked database and hang again.
+ */ export function fallBackToMemoryCache(evidence, { storage = browserSessionStorage(), reload = ()=>window.location.reload(), now = Date.now } = {}) {
+    if (!storage) return;
+    const record = _extends({}, evidence, {
+        at: now()
+    });
+    try {
+        storage.setItem(MEMORY_CACHE_FALLBACK_KEY, JSON.stringify(record));
+    } catch (unused) {
+        return;
+    }
+    console.warn('[firestore] The multi-tab cache is locked by another tab; reloading this tab on the memory cache (AGL-3428).', record);
+    reload();
+}
+/** The IndexedDB database of each client running the durable multi-tab cache. */ const multiTabDatabases = new WeakMap();
+/**
+ * Registers `firestore` as running the durable multi-tab cache under
+ * `databaseName` (`<persistence prefix>main`). Only a registered client ever
+ * escalates past the network cycle.
+ */ export function markMultiTabFirestore(firestore, databaseName) {
+    if (firestore && typeof firestore === 'object') {
+        multiTabDatabases.set(firestore, databaseName);
+    }
+}
+/**
+ * The browser escalation for `firestore`, or `undefined` when it does not run
+ * the durable multi-tab cache (the emulator configuration, an ephemeral
+ * origin, a tab already on the fallback).
+ */ export function browserWedgeEscalationFor(firestore) {
+    const databaseName = multiTabDatabases.get(firestore);
+    if (databaseName === undefined) return undefined;
+    return createWedgeEscalation({
+        probe: ()=>{
+            let factory;
+            try {
+                factory = typeof window === 'undefined' ? undefined : window.indexedDB;
+            } catch (unused) {
+                factory = undefined;
+            }
+            return probePrimaryLease(factory, databaseName);
+        },
+        fallBack: (evidence)=>fallBackToMemoryCache(evidence)
+    });
+}
+
+//# sourceMappingURL=firestore-multitab-wedge.js.map

package/src/lib/hooks/firebase/firestore-multitab-wedge.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../../../libs/tenant/feature/instance/src/lib/hooks/firebase/firestore-multitab-wedge.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport { type Firestore } from 'firebase/firestore'\n\n/**\n * A MULTI-TAB CACHE THAT ANOTHER TAB HAS LOCKED, AND THE WAY OUT (AGL-3428).\n *\n * ## The wedge the network cycle cannot clear\n *\n * `firestore-stall-recovery.ts` recovers a lapsed primary lease by cycling the\n * network, which runs the lease election at once (AGL-3373). That needs the\n * election's IndexedDB transaction to run. Measured against\n * `@firebase/firestore` 4.17.2: `IndexedDbPersistence.runTransaction` opens\n * EVERY transaction over EVERY object store (`getObjectStores(schemaVersion)`),\n * so one tab that stops partway through a readwrite transaction — frozen or\n * discarded by the browser while it runs — holds every store for every tab on\n * the origin. Behind it, in every other tab:\n *\n * - the lease election waits, so the lease row is never renewed by anyone;\n * - cache reads wait, so pages sit on their spinners;\n * - the mutation-queue write waits, so a save never reaches the network;\n * - a freshly opened tab's persistence `start()` waits, so a new tab hangs too;\n * - `disableNetwork`, `enableNetwork` and `terminate` are queued on the same\n *   AsyncQueue behind the stuck operation, so none of them ever runs.\n *\n * On 2026-09-30 production (beta.218) did exactly this three times in two\n * hours: every console tab stopped, and the `owner` row named a background\n * tab that had stopped renewing it.\n *\n * ## How it is told apart from a slow read\n *\n * Only after the network cycle, and only from a visible tab on a browser that\n * reports a network. Such a tab wins a lapsed lease within one 4-second\n * election tick, and the cycle has just forced one. So, after a short settle,\n * the tab reads the `owner` row itself:\n *\n * - **the read cannot complete in time** — the store is locked by another\n *   tab's open transaction; or\n * - **the lease is older than {@link STALE_PRIMARY_LEASE_MS}** — no tab,\n *   including this one, is completing an election.\n *\n * Either is the wedge. A fresh lease — this tab's or another's — is a healthy\n * cache and a merely slow server, and nothing more happens.\n *\n * ## The way out\n *\n * The tab records a {@link MemoryCacheFallback} in `sessionStorage` and\n * reloads. `firestoreCacheClassFor` reads it at startup and gives this tab the\n * memory cache, which shares nothing with other tabs, so the locked database\n * cannot reach it. `sessionStorage` is per tab: other tabs keep the durable\n * cache, and the fallback leaves when this tab closes or after\n * {@link MEMORY_CACHE_FALLBACK_TTL_MS}.\n *\n * A reload, not an in-place swap, because nothing in place can work: the\n * wedged instance's `terminate()` is queued behind the stuck operation, a\n * second instance for the same app throws until the first is gone, and\n * hundreds of readers hold the instance from context and from closures.\n * Nothing that could be saved is lost — the wedge had already stopped every\n * write in the tab from leaving it.\n */\n\n/** `sessionStorage` key of this tab's memory-cache fallback. */\nexport const MEMORY_CACHE_FALLBACK_KEY = 'aglyn:firestore-memory-cache-fallback'\n\n/**\n * How long a tab keeps the memory cache after falling back. The SDK's own\n * inactivity horizon (`MAX_CLIENT_AGE_MS`), after which a tab that is still\n * stuck no longer counts as a client; past it, a reload tries the durable\n * cache again, and falls back again if it has to.\n */\nexport const MEMORY_CACHE_FALLBACK_TTL_MS = 30 * 60 * 1000\n\n/**\n * A lease older than this, read from a visible online tab right after a\n * forced election, means no election is completing. The SDK treats a lease as\n * lapsed at 5 s (`MAX_PRIMARY_ELIGIBLE_AGE_MS`) and runs the election every\n * 4 s; this is three times the first, so an election that is merely late is\n * never mistaken for one that cannot run.\n */\nexport const STALE_PRIMARY_LEASE_MS = 15_000\n\n/**\n * How long the lease read may take before the store is judged locked. The\n * SDK's own transactions take milliseconds.\n */\nexport const LEASE_PROBE_TIMEOUT_MS = 4_000\n\n/**\n * How long after the network cycle the lease is read, so the election the\n * cycle queued has run.\n */\nexport const LEASE_SETTLE_MS = 3_000\n\n/** The SDK's lease store and its single row's key (`DbPrimaryClientStore`, `DbPrimaryClientKey`). */\nconst OWNER_STORE = 'owner'\nconst OWNER_KEY = 'owner'\n\n/** What reading the lease found. */\nexport type PrimaryLeaseProbe =\n  /** The read did not complete in time: another tab's transaction holds the store. */\n  | { state: 'locked' }\n  /** The lease row: who holds it and how long ago it was renewed. */\n  | { state: 'leased'; ownerId: string; ageMs: number }\n  /** There is no lease row. */\n  | { state: 'vacant' }\n  /** The lease could not be read: no IndexedDB, no database, no store, an error. */\n  | { state: 'unknown' }\n\n/** Why a tab concluded the multi-tab cache is wedged. */\nexport type WedgeEvidence =\n  | { reason: 'lease-locked' }\n  | { reason: 'lease-stale'; ownerId: string; ageMs: number }\n\n/** The fallback this tab recorded, and why. */\nexport type MemoryCacheFallback = WedgeEvidence & { at: number }\n\n/**\n * Reads the SDK's `owner` row from `databaseName`.\n *\n * Opens only a database that already exists, at whatever version it has (the\n * same rule as `readHeartbeatClientIds`): `open(name)` on a missing database\n * would create it at version 1 under the SDK. The connection serves one\n * read-only request and is closed — also on `versionchange`, so it never\n * holds up the SDK's own upgrade, and also when the read lands after the\n * timeout.\n */\nexport async function probePrimaryLease(\n  factory: IDBFactory | undefined,\n  databaseName: string,\n  {\n    timeoutMs = LEASE_PROBE_TIMEOUT_MS,\n    now = Date.now,\n  }: { timeoutMs?: number; now?: () => number } = {},\n): Promise<PrimaryLeaseProbe> {\n  if (!factory || typeof factory.databases !== 'function') return { state: 'unknown' }\n  try {\n    const databases = await factory.databases()\n    if (!databases.some((database) => database.name === databaseName)) {\n      return { state: 'unknown' }\n    }\n  } catch {\n    return { state: 'unknown' }\n  }\n\n  return new Promise((resolve) => {\n    let settled = false\n    let database: IDBDatabase | undefined\n    const settle = (probe: PrimaryLeaseProbe) => {\n      if (settled) return\n      settled = true\n      clearTimeout(timer)\n      resolve(probe)\n    }\n    const close = () => {\n      try {\n        database?.close()\n      } catch {\n        // Already closed.\n      }\n    }\n    // Only a lock can hold a read-only request this long; the connection is\n    // closed when the request finally lands.\n    const timer = setTimeout(() => settle({ state: 'locked' }), timeoutMs)\n\n    let request: IDBOpenDBRequest\n    try {\n      request = factory.open(databaseName)\n    } catch {\n      settle({ state: 'unknown' })\n      return\n    }\n    // The database was deleted between `databases()` and `open()`: abort the\n    // creation rather than leave the SDK an empty version-1 database.\n    request.onupgradeneeded = () => request.transaction?.abort()\n    request.onerror = () => settle({ state: 'unknown' })\n    request.onsuccess = () => {\n      database = request.result\n      database.onversionchange = close\n      if (settled || !database.objectStoreNames.contains(OWNER_STORE)) {\n        close()\n        settle({ state: 'unknown' })\n        return\n      }\n      try {\n        const read = database\n          .transaction(OWNER_STORE, 'readonly')\n          .objectStore(OWNER_STORE)\n          .get(OWNER_KEY)\n        read.onsuccess = () => {\n          close()\n          const row = read.result as\n            | { ownerId?: unknown; leaseTimestampMs?: unknown }\n            | undefined\n          if (\n            !row ||\n            typeof row.ownerId !== 'string' ||\n            typeof row.leaseTimestampMs !== 'number'\n          ) {\n            settle({ state: 'vacant' })\n            return\n          }\n          settle({\n            state: 'leased',\n            ownerId: row.ownerId,\n            ageMs: now() - row.leaseTimestampMs,\n          })\n        }\n        read.onerror = () => {\n          close()\n          settle({ state: 'unknown' })\n        }\n      } catch {\n        close()\n        settle({ state: 'unknown' })\n      }\n    }\n  })\n}\n\n/**\n * Whether a lease read taken right after a forced election, from a visible\n * online tab, shows the wedge. Anything that could be a healthy cache —\n * a fresh lease, no lease row, an unreadable one — is not evidence.\n */\nexport function wedgeEvidenceFrom(\n  probe: PrimaryLeaseProbe,\n  staleMs = STALE_PRIMARY_LEASE_MS,\n): WedgeEvidence | undefined {\n  if (probe.state === 'locked') return { reason: 'lease-locked' }\n  if (probe.state === 'leased' && probe.ageMs >= staleMs) {\n    return { reason: 'lease-stale', ownerId: probe.ownerId, ageMs: probe.ageMs }\n  }\n  return undefined\n}\n\n/**\n * This tab's fallback, or `undefined` when there is none, it has expired, or\n * it does not parse.\n */\nexport function readMemoryCacheFallback(\n  storage: Pick<Storage, 'getItem'> | undefined,\n  now: number,\n  ttlMs = MEMORY_CACHE_FALLBACK_TTL_MS,\n): MemoryCacheFallback | undefined {\n  let raw: string | null\n  try {\n    raw = storage?.getItem(MEMORY_CACHE_FALLBACK_KEY) ?? null\n  } catch {\n    return undefined\n  }\n  if (raw === null) return undefined\n  let parsed: unknown\n  try {\n    parsed = JSON.parse(raw)\n  } catch {\n    return undefined\n  }\n  if (typeof parsed !== 'object' || parsed === null) return undefined\n  const record = parsed as Partial<MemoryCacheFallback>\n  if (typeof record.at !== 'number' || !Number.isFinite(record.at)) return undefined\n  if (now - record.at >= ttlMs || record.at > now) return undefined\n  return record as MemoryCacheFallback\n}\n\nconst browserSessionStorage = (): Storage | undefined => {\n  try {\n    return typeof window === 'undefined' ? undefined : window.sessionStorage\n  } catch {\n    // Site data blocked: reading `window.sessionStorage` throws.\n    return undefined\n  }\n}\n\n/** Whether this browser tab is running on its memory-cache fallback. */\nexport function memoryCacheFallbackActive(now = Date.now()): boolean {\n  return readMemoryCacheFallback(browserSessionStorage(), now) !== undefined\n}\n\nexport interface WedgeEscalationDeps {\n  /** Reads the lease. */\n  probe: () => Promise<PrimaryLeaseProbe>\n  /** Moves this tab off the shared cache. */\n  fallBack: (evidence: WedgeEvidence) => void\n  /** Whether this tab is already on the fallback — it then never escalates. */\n  isFallbackActive?: () => boolean\n  isOnline?: () => boolean\n  isVisible?: () => boolean\n  /** Waits `ms`; the settle before the lease read. */\n  wait?: (ms: number) => Promise<void>\n  settleMs?: number\n}\n\nconst browserOnline = () =>\n  typeof navigator === 'undefined' || navigator.onLine !== false\n\nconst documentVisible = () =>\n  typeof document === 'undefined' || document.visibilityState !== 'hidden'\n\n/**\n * The step `createStallRecovery` runs after its network cycle for a\n * multi-tab client. Resolves `true` when it has moved the tab to the fallback.\n * Never rejects.\n */\nexport function createWedgeEscalation(\n  deps: WedgeEscalationDeps,\n): () => Promise<boolean> {\n  const {\n    probe,\n    fallBack,\n    isFallbackActive = () => memoryCacheFallbackActive(),\n    isOnline = browserOnline,\n    isVisible = documentVisible,\n    wait = (ms) => new Promise<void>((resolve) => setTimeout(resolve, ms)),\n    settleMs = LEASE_SETTLE_MS,\n  } = deps\n  return async () => {\n    try {\n      if (isFallbackActive()) return false\n      await wait(settleMs)\n      // Both guards again: the reader may have gone, or the network with it.\n      if (!isOnline() || !isVisible()) return false\n      const evidence = wedgeEvidenceFrom(await probe())\n      if (!evidence) return false\n      fallBack(evidence)\n      return true\n    } catch {\n      return false\n    }\n  }\n}\n\n/**\n * Records the fallback for this tab and reloads it onto the memory cache.\n * When the record cannot be written it does not reload: without it, the\n * reloaded tab would open the same locked database and hang again.\n */\nexport function fallBackToMemoryCache(\n  evidence: WedgeEvidence,\n  {\n    storage = browserSessionStorage(),\n    reload = () => window.location.reload(),\n    now = Date.now,\n  }: {\n    storage?: Pick<Storage, 'setItem'>\n    reload?: () => void\n    now?: () => number\n  } = {},\n): void {\n  if (!storage) return\n  const record: MemoryCacheFallback = { ...evidence, at: now() }\n  try {\n    storage.setItem(MEMORY_CACHE_FALLBACK_KEY, JSON.stringify(record))\n  } catch {\n    return\n  }\n  console.warn(\n    '[firestore] The multi-tab cache is locked by another tab; reloading this tab on the memory cache (AGL-3428).',\n    record,\n  )\n  reload()\n}\n\n/** The IndexedDB database of each client running the durable multi-tab cache. */\nconst multiTabDatabases = new WeakMap<Firestore, string>()\n\n/**\n * Registers `firestore` as running the durable multi-tab cache under\n * `databaseName` (`<persistence prefix>main`). Only a registered client ever\n * escalates past the network cycle.\n */\nexport function markMultiTabFirestore(firestore: Firestore, databaseName: string): void {\n  if (firestore && typeof firestore === 'object') {\n    multiTabDatabases.set(firestore, databaseName)\n  }\n}\n\n/**\n * The browser escalation for `firestore`, or `undefined` when it does not run\n * the durable multi-tab cache (the emulator configuration, an ephemeral\n * origin, a tab already on the fallback).\n */\nexport function browserWedgeEscalationFor(\n  firestore: Firestore,\n): (() => Promise<boolean>) | undefined {\n  const databaseName = multiTabDatabases.get(firestore)\n  if (databaseName === undefined) return undefined\n  return createWedgeEscalation({\n    probe: () => {\n      let factory: IDBFactory | undefined\n      try {\n        factory = typeof window === 'undefined' ? undefined : window.indexedDB\n      } catch {\n        factory = undefined\n      }\n      return probePrimaryLease(factory, databaseName)\n    },\n    fallBack: (evidence) => fallBackToMemoryCache(evidence),\n  })\n}\n"],"names":["MEMORY_CACHE_FALLBACK_KEY","MEMORY_CACHE_FALLBACK_TTL_MS","STALE_PRIMARY_LEASE_MS","LEASE_PROBE_TIMEOUT_MS","LEASE_SETTLE_MS","OWNER_STORE","OWNER_KEY","probePrimaryLease","factory","databaseName","timeoutMs","now","Date","databases","state","some","database","name","Promise","resolve","settled","settle","probe","clearTimeout","timer","close","setTimeout","request","open","onupgradeneeded","transaction","abort","onerror","onsuccess","result","onversionchange","objectStoreNames","contains","read","objectStore","get","row","ownerId","leaseTimestampMs","ageMs","wedgeEvidenceFrom","staleMs","reason","undefined","readMemoryCacheFallback","storage","ttlMs","raw","getItem","parsed","JSON","parse","record","at","Number","isFinite","browserSessionStorage","window","sessionStorage","memoryCacheFallbackActive","browserOnline","navigator","onLine","documentVisible","document","visibilityState","createWedgeEscalation","deps","fallBack","isFallbackActive","isOnline","isVisible","wait","ms","settleMs","evidence","fallBackToMemoryCache","reload","location","setItem","stringify","console","warn","multiTabDatabases","WeakMap","markMultiTabFirestore","firestore","set","browserWedgeEscalationFor","indexedDB"],"mappings":"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"}

package/src/lib/hooks/firebase/firestore-stall-recovery.d.ts

@@ -83,6 +83,19 @@ import { type Firestore } from 'firebase/firestore';
  *   a page stalls together, and one cycle serves them all. A concurrent
  *   request shares the cycle already running.
  * - **The network is always re-enabled**, including when disabling fails.
+ * - **Each step is bounded by {@link NETWORK_STEP_TIMEOUT_MS}.** Both calls are
+ *   queued on the client's AsyncQueue, and when another tab has locked the
+ *   shared IndexedDB they queue behind an operation that never finishes
+ *   (AGL-3428). Unbounded, the first such cycle never settled, and every
+ *   later recovery request shared it forever.
+ *
+ * ## When the cycle is not enough (AGL-3428)
+ *
+ * A tab frozen partway through an IndexedDB transaction holds every store the
+ * SDK uses, and the election the cycle forces cannot run. For a client on the
+ * durable multi-tab cache the cycle is followed by the lease check in
+ * `firestore-multitab-wedge.ts`, which moves the tab to a memory cache when
+ * the lease shows the wedge.
  */
 /**
  * How long a server read or a listener's first server-confirmed snapshot may
@@ -93,6 +106,11 @@ import { type Firestore } from 'firebase/firestore';
 export declare const FIRESTORE_STALL_MS = 8000;
 /** The least time between two recoveries of the same client. */
 export declare const STALL_RECOVERY_COOLDOWN_MS = 30000;
+/**
+ * The longest `disableNetwork` or `enableNetwork` may take. Both finish in
+ * milliseconds on a client whose queue is moving.
+ */
+export declare const NETWORK_STEP_TIMEOUT_MS = 5000;
 /** What a recovery request did. */
 export type StallRecoveryOutcome = 
 /** The browser reports no network: the cache is the right answer. */
@@ -103,8 +121,10 @@ export type StallRecoveryOutcome =
  | 'cooling'
 /** The network was cycled. */
  | 'recovered'
-/** The cycle threw; the network was still re-enabled if at all possible. */
- | 'failed';
+/** The cycle threw or timed out; the network was still re-enabled if at all possible. */
+ | 'failed'
+/** The multi-tab cache was wedged and this tab is moving to the memory cache. */
+ | 'fell-back';
 export interface StallRecoveryDeps {
     /** Take the client off the network. */
     disable: () => Promise<void>;
@@ -116,6 +136,13 @@ export interface StallRecoveryDeps {
     isVisible?: () => boolean;
     now?: () => number;
     cooldownMs?: number;
+    /** The bound on each of `disable` and `enable`. */
+    stepTimeoutMs?: number;
+    /**
+     * Runs after every cycle; resolves `true` when it has moved the tab off
+     * the shared cache. Only a multi-tab client has one.
+     */
+    afterCycle?: () => Promise<boolean>;
 }
 export interface StallRecovery {
     recover: () => Promise<StallRecoveryOutcome>;

package/src/lib/hooks/firebase/firestore-stall-recovery.js

@@ -14,6 +14,7 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */ import { disableNetwork, enableNetwork } from "firebase/firestore";
+import { browserWedgeEscalationFor } from "./firestore-multitab-wedge.js";
 /**
  * RECOVERING A FIRESTORE CLIENT THAT HAS STOPPED SYNCING (AGL-3373).
  *
@@ -82,6 +83,19 @@
  *   a page stalls together, and one cycle serves them all. A concurrent
  *   request shares the cycle already running.
  * - **The network is always re-enabled**, including when disabling fails.
+ * - **Each step is bounded by {@link NETWORK_STEP_TIMEOUT_MS}.** Both calls are
+ *   queued on the client's AsyncQueue, and when another tab has locked the
+ *   shared IndexedDB they queue behind an operation that never finishes
+ *   (AGL-3428). Unbounded, the first such cycle never settled, and every
+ *   later recovery request shared it forever.
+ *
+ * ## When the cycle is not enough (AGL-3428)
+ *
+ * A tab frozen partway through an IndexedDB transaction holds every store the
+ * SDK uses, and the election the cycle forces cannot run. For a client on the
+ * durable multi-tab cache the cycle is followed by the lease check in
+ * `firestore-multitab-wedge.ts`, which moves the tab to a memory cache when
+ * the lease shows the wedge.
  */ /**
  * How long a server read or a listener's first server-confirmed snapshot may
  * take before the client is treated as stalled. A healthy console answers
@@ -89,23 +103,38 @@
  * leaving a reader on a spinner for long.
  */ export const FIRESTORE_STALL_MS = 8000;
 /** The least time between two recoveries of the same client. */ export const STALL_RECOVERY_COOLDOWN_MS = 30000;
+/**
+ * The longest `disableNetwork` or `enableNetwork` may take. Both finish in
+ * milliseconds on a client whose queue is moving.
+ */ export const NETWORK_STEP_TIMEOUT_MS = 5000;
 const browserOnline = ()=>typeof navigator === 'undefined' || navigator.onLine !== false;
 const documentVisible = ()=>typeof document === 'undefined' || document.visibilityState !== 'hidden';
 /** The recovery for one client, with its guards. Pure over `deps`. */ export function createStallRecovery(deps) {
-    const { disable, enable, isOnline = browserOnline, isVisible = documentVisible, now = Date.now, cooldownMs = STALL_RECOVERY_COOLDOWN_MS } = deps;
+    const { disable, enable, isOnline = browserOnline, isVisible = documentVisible, now = Date.now, cooldownMs = STALL_RECOVERY_COOLDOWN_MS, stepTimeoutMs = NETWORK_STEP_TIMEOUT_MS, afterCycle } = deps;
     let lastStartedAt;
     let running;
+    /** Whether `step` settled successfully within `stepTimeoutMs`. */ const bounded = (step)=>new Promise((resolve)=>{
+            const timer = setTimeout(()=>resolve(false), stepTimeoutMs);
+            const done = (ok)=>{
+                clearTimeout(timer);
+                resolve(ok);
+            };
+            try {
+                step().then(()=>done(true), ()=>done(false));
+            } catch (unused) {
+                done(false);
+            }
+        });
     const cycle = async ()=>{
         let outcome = 'recovered';
-        try {
-            await disable();
-        } catch (unused) {
-            outcome = 'failed';
-        }
-        try {
-            await enable();
-        } catch (unused) {
-            outcome = 'failed';
+        if (!await bounded(disable)) outcome = 'failed';
+        if (!await bounded(enable)) outcome = 'failed';
+        if (afterCycle) {
+            try {
+                if (await afterCycle()) return 'fell-back';
+            } catch (unused) {
+            // The escalation is best effort; the cycle's own outcome stands.
+            }
         }
         return outcome;
     };
@@ -139,7 +168,8 @@ const recoveries = new WeakMap();
     if (!recovery) {
         recovery = createStallRecovery({
             disable: ()=>disableNetwork(firestore),
-            enable: ()=>enableNetwork(firestore)
+            enable: ()=>enableNetwork(firestore),
+            afterCycle: browserWedgeEscalationFor(firestore)
         });
         recoveries.set(firestore, recovery);
     }

package/src/lib/hooks/firebase/firestore-stall-recovery.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../../../../../../../libs/tenant/feature/instance/src/lib/hooks/firebase/firestore-stall-recovery.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport {\n  disableNetwork,\n  enableNetwork,\n  type Firestore,\n} from 'firebase/firestore'\n\n/**\n * RECOVERING A FIRESTORE CLIENT THAT HAS STOPPED SYNCING (AGL-3373).\n *\n * ## The wedge\n *\n * The console runs the persistent cache with `persistentMultipleTabManager`\n * (`firestore-cache.ts`). Only the PRIMARY tab talks to the backend; every\n * other tab reads the shared IndexedDB cache and takes its online state from\n * a `localStorage` record the primary writes. A secondary that believes the\n * client is online answers a `getDocs` only once the primary has synced the\n * query, and raises no first snapshot for a listener whose cache is empty.\n *\n * When the primary dies without handing over — a crashed, discarded or\n * frozen tab — its \"Online\" record outlives it, and until some tab runs the\n * lease election and wins, nothing syncs. The election runs on a 4-second\n * timer inside each tab, which the browser throttles to about once a minute\n * in a hidden tab. On 2026-09-28 no live tab synced for about ten minutes:\n * the notifications page never left its loading state and a staff page sat\n * on its splash until a fresh tab (which wins the election on start) was\n * opened.\n *\n * ## The recovery, and why it is this one\n *\n * `disableNetwork` then `enableNetwork`, from the tab that noticed. Both are\n * public API, and in the multi-tab client each one calls\n * `setNetworkEnabled`, which schedules the lease election for IMMEDIATE\n * execution instead of the next (possibly throttled) timer tick. A visible\n * tab that finds the lease lapsed takes it, starts its own streams and\n * writes its own online state, which replaces the dead tab's. A tab that was\n * already primary with a silently dead stream gets fresh streams.\n *\n * Nothing is lost. Writes made meanwhile sit in the mutation queue (in\n * IndexedDB, under the persistent cache) and are sent when the network comes\n * back; the SDK's own contract for `disableNetwork` is that writes queue.\n *\n * The rejected alternatives:\n *\n * - **Clearing the persistence cache** (`terminate` + `clearIndexedDbPersistence`).\n *   It deletes the mutation queue, so pending writes are lost, and\n *   `waitForPendingWrites` cannot drain them first because draining is the\n *   very thing that is stuck. It also refuses to run while any other tab\n *   holds the database, which in a multi-tab wedge is always. And\n *   `terminate` invalidates the one `Firestore` instance every hook in the\n *   console holds.\n * - **Pruning the dead tab's online-state record at startup**, beside the\n *   AGL-2845 prune. The SDK already ignores an online-state record at\n *   startup unless its writer is an active, non-zombie client\n *   (`WebStorageSharedClientState.handleOnlineStateEvent`), and a freshly\n *   started tab wins the election anyway — which is why a fresh tab fixed\n *   the incident. The tabs that stayed stuck were the ones ALREADY running,\n *   which a startup prune never reaches.\n * - **`persistentSingleTabManager`.** It removes cross-tab dependency, but\n *   every tab after the first falls back to a memory cache, so writes made\n *   offline in those tabs are lost when they close. And a tab still on the\n *   multi-tab build that meets a single-tab lease holder fails its queue\n *   with `failed-precondition` until reloaded, so the rollout itself would\n *   wedge the tabs left open across it.\n *\n * ## Guards\n *\n * - **Online only.** A browser that reports no network is correctly offline,\n *   and the cache answering is the cache doing its job.\n * - **Visible only.** A hidden tab's timers are throttled and its reader is\n *   not waiting; if it is stalled, it recovers the moment it is looked at.\n * - **Once per {@link STALL_RECOVERY_COOLDOWN_MS} per client.** Every list on\n *   a page stalls together, and one cycle serves them all. A concurrent\n *   request shares the cycle already running.\n * - **The network is always re-enabled**, including when disabling fails.\n */\n\n/**\n * How long a server read or a listener's first server-confirmed snapshot may\n * take before the client is treated as stalled. A healthy console answers\n * in well under two seconds; this leaves room for a slow network without\n * leaving a reader on a spinner for long.\n */\nexport const FIRESTORE_STALL_MS = 8_000\n\n/** The least time between two recoveries of the same client. */\nexport const STALL_RECOVERY_COOLDOWN_MS = 30_000\n\n/** What a recovery request did. */\nexport type StallRecoveryOutcome =\n  /** The browser reports no network: the cache is the right answer. */\n  | 'offline'\n  /** The tab is hidden: nobody is waiting on it. */\n  | 'hidden'\n  /** A recovery ran moments ago; this request rode on it. */\n  | 'cooling'\n  /** The network was cycled. */\n  | 'recovered'\n  /** The cycle threw; the network was still re-enabled if at all possible. */\n  | 'failed'\n\nexport interface StallRecoveryDeps {\n  /** Take the client off the network. */\n  disable: () => Promise<void>\n  /** Put it back. */\n  enable: () => Promise<void>\n  /** `navigator.onLine`, or `true` where there is no navigator. */\n  isOnline?: () => boolean\n  /** Whether the document is visible, or `true` where there is none. */\n  isVisible?: () => boolean\n  now?: () => number\n  cooldownMs?: number\n}\n\nexport interface StallRecovery {\n  recover: () => Promise<StallRecoveryOutcome>\n}\n\nconst browserOnline = () =>\n  typeof navigator === 'undefined' || navigator.onLine !== false\n\nconst documentVisible = () =>\n  typeof document === 'undefined' || document.visibilityState !== 'hidden'\n\n/** The recovery for one client, with its guards. Pure over `deps`. */\nexport function createStallRecovery(deps: StallRecoveryDeps): StallRecovery {\n  const {\n    disable,\n    enable,\n    isOnline = browserOnline,\n    isVisible = documentVisible,\n    now = Date.now,\n    cooldownMs = STALL_RECOVERY_COOLDOWN_MS,\n  } = deps\n  let lastStartedAt: number | undefined\n  let running: Promise<StallRecoveryOutcome> | undefined\n\n  const cycle = async (): Promise<StallRecoveryOutcome> => {\n    let outcome: StallRecoveryOutcome = 'recovered'\n    try {\n      await disable()\n    } catch {\n      outcome = 'failed'\n    }\n    try {\n      await enable()\n    } catch {\n      outcome = 'failed'\n    }\n    return outcome\n  }\n\n  return {\n    recover: () => {\n      if (running) return running\n      if (!isOnline()) return Promise.resolve('offline')\n      if (!isVisible()) return Promise.resolve('hidden')\n      const at = now()\n      if (lastStartedAt !== undefined && at - lastStartedAt < cooldownMs) {\n        return Promise.resolve('cooling')\n      }\n      lastStartedAt = at\n      running = cycle().finally(() => {\n        running = undefined\n      })\n      return running\n    },\n  }\n}\n\nconst recoveries = new WeakMap<Firestore, StallRecovery>()\n\n/**\n * Recovers `firestore` if it has stalled. Safe to call from every reader\n * that notices: the guards above collapse the calls into at most one network\n * cycle per cooldown. Never rejects.\n */\nexport function recoverStalledFirestore(\n  firestore: Firestore | null | undefined,\n): Promise<StallRecoveryOutcome> {\n  if (!firestore || typeof firestore !== 'object') {\n    return Promise.resolve('failed')\n  }\n  let recovery = recoveries.get(firestore)\n  if (!recovery) {\n    recovery = createStallRecovery({\n      disable: () => disableNetwork(firestore),\n      enable: () => enableNetwork(firestore),\n    })\n    recoveries.set(firestore, recovery)\n  }\n  return recovery.recover().catch(() => 'failed' as const)\n}\n\n/**\n * Arms a stall timer for one read or listen. If `disarm` has not been called\n * within `stallMs`, `onStall` runs (by default, {@link recoverStalledFirestore}).\n * A tab that is hidden when the timer fires waits until it is shown, since\n * that is when a reader is waiting again.\n *\n * Returns `disarm`, which is idempotent.\n */\nexport function armFirestoreStallWatch(\n  firestore: Firestore | null | undefined,\n  options: { stallMs?: number; onStall?: () => void } = {},\n): () => void {\n  const { stallMs = FIRESTORE_STALL_MS } = options\n  const onStall =\n    options.onStall ?? (() => void recoverStalledFirestore(firestore))\n  let done = false\n  let onVisible: (() => void) | undefined\n  const fire = () => {\n    if (done) return\n    if (!documentVisible() && typeof document !== 'undefined') {\n      onVisible = () => {\n        if (!documentVisible()) return\n        document.removeEventListener('visibilitychange', onVisible!)\n        onVisible = undefined\n        fire()\n      }\n      document.addEventListener('visibilitychange', onVisible)\n      return\n    }\n    done = true\n    onStall()\n  }\n  const timer = setTimeout(fire, stallMs)\n  return () => {\n    if (done) return\n    done = true\n    clearTimeout(timer)\n    if (onVisible && typeof document !== 'undefined') {\n      document.removeEventListener('visibilitychange', onVisible)\n    }\n  }\n}\n"],"names":["disableNetwork","enableNetwork","FIRESTORE_STALL_MS","STALL_RECOVERY_COOLDOWN_MS","browserOnline","navigator","onLine","documentVisible","document","visibilityState","createStallRecovery","deps","disable","enable","isOnline","isVisible","now","Date","cooldownMs","lastStartedAt","running","cycle","outcome","recover","Promise","resolve","at","undefined","finally","recoveries","WeakMap","recoverStalledFirestore","firestore","recovery","get","set","catch","armFirestoreStallWatch","options","stallMs","onStall","done","onVisible","fire","removeEventListener","addEventListener","timer","setTimeout","clearTimeout"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED,SACEA,cAAc,EACdC,aAAa,QAER,qBAAoB;AAE3B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAoEC,GAED;;;;;CAKC,GACD,OAAO,MAAMC,qBAAqB,KAAK;AAEvC,8DAA8D,GAC9D,OAAO,MAAMC,6BAA6B,MAAM;AAgChD,MAAMC,gBAAgB,IACpB,OAAOC,cAAc,eAAeA,UAAUC,MAAM,KAAK;AAE3D,MAAMC,kBAAkB,IACtB,OAAOC,aAAa,eAAeA,SAASC,eAAe,KAAK;AAElE,oEAAoE,GACpE,OAAO,SAASC,oBAAoBC,IAAuB;IACzD,MAAM,EACJC,OAAO,EACPC,MAAM,EACNC,WAAWV,aAAa,EACxBW,YAAYR,eAAe,EAC3BS,MAAMC,KAAKD,GAAG,EACdE,aAAaf,0BAA0B,EACxC,GAAGQ;IACJ,IAAIQ;IACJ,IAAIC;IAEJ,MAAMC,QAAQ;QACZ,IAAIC,UAAgC;QACpC,IAAI;YACF,MAAMV;QACR,EAAE,eAAM;YACNU,UAAU;QACZ;QACA,IAAI;YACF,MAAMT;QACR,EAAE,eAAM;YACNS,UAAU;QACZ;QACA,OAAOA;IACT;IAEA,OAAO;QACLC,SAAS;YACP,IAAIH,SAAS,OAAOA;YACpB,IAAI,CAACN,YAAY,OAAOU,QAAQC,OAAO,CAAC;YACxC,IAAI,CAACV,aAAa,OAAOS,QAAQC,OAAO,CAAC;YACzC,MAAMC,KAAKV;YACX,IAAIG,kBAAkBQ,aAAaD,KAAKP,gBAAgBD,YAAY;gBAClE,OAAOM,QAAQC,OAAO,CAAC;YACzB;YACAN,gBAAgBO;YAChBN,UAAUC,QAAQO,OAAO,CAAC;gBACxBR,UAAUO;YACZ;YACA,OAAOP;QACT;IACF;AACF;AAEA,MAAMS,aAAa,IAAIC;AAEvB;;;;CAIC,GACD,OAAO,SAASC,wBACdC,SAAuC;IAEvC,IAAI,CAACA,aAAa,OAAOA,cAAc,UAAU;QAC/C,OAAOR,QAAQC,OAAO,CAAC;IACzB;IACA,IAAIQ,WAAWJ,WAAWK,GAAG,CAACF;IAC9B,IAAI,CAACC,UAAU;QACbA,WAAWvB,oBAAoB;YAC7BE,SAAS,IAAMZ,eAAegC;YAC9BnB,QAAQ,IAAMZ,cAAc+B;QAC9B;QACAH,WAAWM,GAAG,CAACH,WAAWC;IAC5B;IACA,OAAOA,SAASV,OAAO,GAAGa,KAAK,CAAC,IAAM;AACxC;AAEA;;;;;;;CAOC,GACD,OAAO,SAASC,uBACdL,SAAuC,EACvCM,UAAsD,CAAC,CAAC;QAItDA;IAFF,MAAM,EAAEC,UAAUrC,kBAAkB,EAAE,GAAGoC;IACzC,MAAME,WACJF,mBAAAA,QAAQE,OAAO,YAAfF,mBAAoB,IAAM,KAAKP,wBAAwBC;IACzD,IAAIS,OAAO;IACX,IAAIC;IACJ,MAAMC,OAAO;QACX,IAAIF,MAAM;QACV,IAAI,CAAClC,qBAAqB,OAAOC,aAAa,aAAa;YACzDkC,YAAY;gBACV,IAAI,CAACnC,mBAAmB;gBACxBC,SAASoC,mBAAmB,CAAC,oBAAoBF;gBACjDA,YAAYf;gBACZgB;YACF;YACAnC,SAASqC,gBAAgB,CAAC,oBAAoBH;YAC9C;QACF;QACAD,OAAO;QACPD;IACF;IACA,MAAMM,QAAQC,WAAWJ,MAAMJ;IAC/B,OAAO;QACL,IAAIE,MAAM;QACVA,OAAO;QACPO,aAAaF;QACb,IAAIJ,aAAa,OAAOlC,aAAa,aAAa;YAChDA,SAASoC,mBAAmB,CAAC,oBAAoBF;QACnD;IACF;AACF"}
+{"version":3,"sources":["../../../../../../../../../libs/tenant/feature/instance/src/lib/hooks/firebase/firestore-stall-recovery.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport {\n  disableNetwork,\n  enableNetwork,\n  type Firestore,\n} from 'firebase/firestore'\n\nimport { browserWedgeEscalationFor } from './firestore-multitab-wedge'\n\n/**\n * RECOVERING A FIRESTORE CLIENT THAT HAS STOPPED SYNCING (AGL-3373).\n *\n * ## The wedge\n *\n * The console runs the persistent cache with `persistentMultipleTabManager`\n * (`firestore-cache.ts`). Only the PRIMARY tab talks to the backend; every\n * other tab reads the shared IndexedDB cache and takes its online state from\n * a `localStorage` record the primary writes. A secondary that believes the\n * client is online answers a `getDocs` only once the primary has synced the\n * query, and raises no first snapshot for a listener whose cache is empty.\n *\n * When the primary dies without handing over — a crashed, discarded or\n * frozen tab — its \"Online\" record outlives it, and until some tab runs the\n * lease election and wins, nothing syncs. The election runs on a 4-second\n * timer inside each tab, which the browser throttles to about once a minute\n * in a hidden tab. On 2026-09-28 no live tab synced for about ten minutes:\n * the notifications page never left its loading state and a staff page sat\n * on its splash until a fresh tab (which wins the election on start) was\n * opened.\n *\n * ## The recovery, and why it is this one\n *\n * `disableNetwork` then `enableNetwork`, from the tab that noticed. Both are\n * public API, and in the multi-tab client each one calls\n * `setNetworkEnabled`, which schedules the lease election for IMMEDIATE\n * execution instead of the next (possibly throttled) timer tick. A visible\n * tab that finds the lease lapsed takes it, starts its own streams and\n * writes its own online state, which replaces the dead tab's. A tab that was\n * already primary with a silently dead stream gets fresh streams.\n *\n * Nothing is lost. Writes made meanwhile sit in the mutation queue (in\n * IndexedDB, under the persistent cache) and are sent when the network comes\n * back; the SDK's own contract for `disableNetwork` is that writes queue.\n *\n * The rejected alternatives:\n *\n * - **Clearing the persistence cache** (`terminate` + `clearIndexedDbPersistence`).\n *   It deletes the mutation queue, so pending writes are lost, and\n *   `waitForPendingWrites` cannot drain them first because draining is the\n *   very thing that is stuck. It also refuses to run while any other tab\n *   holds the database, which in a multi-tab wedge is always. And\n *   `terminate` invalidates the one `Firestore` instance every hook in the\n *   console holds.\n * - **Pruning the dead tab's online-state record at startup**, beside the\n *   AGL-2845 prune. The SDK already ignores an online-state record at\n *   startup unless its writer is an active, non-zombie client\n *   (`WebStorageSharedClientState.handleOnlineStateEvent`), and a freshly\n *   started tab wins the election anyway — which is why a fresh tab fixed\n *   the incident. The tabs that stayed stuck were the ones ALREADY running,\n *   which a startup prune never reaches.\n * - **`persistentSingleTabManager`.** It removes cross-tab dependency, but\n *   every tab after the first falls back to a memory cache, so writes made\n *   offline in those tabs are lost when they close. And a tab still on the\n *   multi-tab build that meets a single-tab lease holder fails its queue\n *   with `failed-precondition` until reloaded, so the rollout itself would\n *   wedge the tabs left open across it.\n *\n * ## Guards\n *\n * - **Online only.** A browser that reports no network is correctly offline,\n *   and the cache answering is the cache doing its job.\n * - **Visible only.** A hidden tab's timers are throttled and its reader is\n *   not waiting; if it is stalled, it recovers the moment it is looked at.\n * - **Once per {@link STALL_RECOVERY_COOLDOWN_MS} per client.** Every list on\n *   a page stalls together, and one cycle serves them all. A concurrent\n *   request shares the cycle already running.\n * - **The network is always re-enabled**, including when disabling fails.\n * - **Each step is bounded by {@link NETWORK_STEP_TIMEOUT_MS}.** Both calls are\n *   queued on the client's AsyncQueue, and when another tab has locked the\n *   shared IndexedDB they queue behind an operation that never finishes\n *   (AGL-3428). Unbounded, the first such cycle never settled, and every\n *   later recovery request shared it forever.\n *\n * ## When the cycle is not enough (AGL-3428)\n *\n * A tab frozen partway through an IndexedDB transaction holds every store the\n * SDK uses, and the election the cycle forces cannot run. For a client on the\n * durable multi-tab cache the cycle is followed by the lease check in\n * `firestore-multitab-wedge.ts`, which moves the tab to a memory cache when\n * the lease shows the wedge.\n */\n\n/**\n * How long a server read or a listener's first server-confirmed snapshot may\n * take before the client is treated as stalled. A healthy console answers\n * in well under two seconds; this leaves room for a slow network without\n * leaving a reader on a spinner for long.\n */\nexport const FIRESTORE_STALL_MS = 8_000\n\n/** The least time between two recoveries of the same client. */\nexport const STALL_RECOVERY_COOLDOWN_MS = 30_000\n\n/**\n * The longest `disableNetwork` or `enableNetwork` may take. Both finish in\n * milliseconds on a client whose queue is moving.\n */\nexport const NETWORK_STEP_TIMEOUT_MS = 5_000\n\n/** What a recovery request did. */\nexport type StallRecoveryOutcome =\n  /** The browser reports no network: the cache is the right answer. */\n  | 'offline'\n  /** The tab is hidden: nobody is waiting on it. */\n  | 'hidden'\n  /** A recovery ran moments ago; this request rode on it. */\n  | 'cooling'\n  /** The network was cycled. */\n  | 'recovered'\n  /** The cycle threw or timed out; the network was still re-enabled if at all possible. */\n  | 'failed'\n  /** The multi-tab cache was wedged and this tab is moving to the memory cache. */\n  | 'fell-back'\n\nexport interface StallRecoveryDeps {\n  /** Take the client off the network. */\n  disable: () => Promise<void>\n  /** Put it back. */\n  enable: () => Promise<void>\n  /** `navigator.onLine`, or `true` where there is no navigator. */\n  isOnline?: () => boolean\n  /** Whether the document is visible, or `true` where there is none. */\n  isVisible?: () => boolean\n  now?: () => number\n  cooldownMs?: number\n  /** The bound on each of `disable` and `enable`. */\n  stepTimeoutMs?: number\n  /**\n   * Runs after every cycle; resolves `true` when it has moved the tab off\n   * the shared cache. Only a multi-tab client has one.\n   */\n  afterCycle?: () => Promise<boolean>\n}\n\nexport interface StallRecovery {\n  recover: () => Promise<StallRecoveryOutcome>\n}\n\nconst browserOnline = () =>\n  typeof navigator === 'undefined' || navigator.onLine !== false\n\nconst documentVisible = () =>\n  typeof document === 'undefined' || document.visibilityState !== 'hidden'\n\n/** The recovery for one client, with its guards. Pure over `deps`. */\nexport function createStallRecovery(deps: StallRecoveryDeps): StallRecovery {\n  const {\n    disable,\n    enable,\n    isOnline = browserOnline,\n    isVisible = documentVisible,\n    now = Date.now,\n    cooldownMs = STALL_RECOVERY_COOLDOWN_MS,\n    stepTimeoutMs = NETWORK_STEP_TIMEOUT_MS,\n    afterCycle,\n  } = deps\n  let lastStartedAt: number | undefined\n  let running: Promise<StallRecoveryOutcome> | undefined\n\n  /** Whether `step` settled successfully within `stepTimeoutMs`. */\n  const bounded = (step: () => Promise<void>): Promise<boolean> =>\n    new Promise((resolve) => {\n      const timer = setTimeout(() => resolve(false), stepTimeoutMs)\n      const done = (ok: boolean) => {\n        clearTimeout(timer)\n        resolve(ok)\n      }\n      try {\n        step().then(\n          () => done(true),\n          () => done(false),\n        )\n      } catch {\n        done(false)\n      }\n    })\n\n  const cycle = async (): Promise<StallRecoveryOutcome> => {\n    let outcome: StallRecoveryOutcome = 'recovered'\n    if (!(await bounded(disable))) outcome = 'failed'\n    if (!(await bounded(enable))) outcome = 'failed'\n    if (afterCycle) {\n      try {\n        if (await afterCycle()) return 'fell-back'\n      } catch {\n        // The escalation is best effort; the cycle's own outcome stands.\n      }\n    }\n    return outcome\n  }\n\n  return {\n    recover: () => {\n      if (running) return running\n      if (!isOnline()) return Promise.resolve('offline')\n      if (!isVisible()) return Promise.resolve('hidden')\n      const at = now()\n      if (lastStartedAt !== undefined && at - lastStartedAt < cooldownMs) {\n        return Promise.resolve('cooling')\n      }\n      lastStartedAt = at\n      running = cycle().finally(() => {\n        running = undefined\n      })\n      return running\n    },\n  }\n}\n\nconst recoveries = new WeakMap<Firestore, StallRecovery>()\n\n/**\n * Recovers `firestore` if it has stalled. Safe to call from every reader\n * that notices: the guards above collapse the calls into at most one network\n * cycle per cooldown. Never rejects.\n */\nexport function recoverStalledFirestore(\n  firestore: Firestore | null | undefined,\n): Promise<StallRecoveryOutcome> {\n  if (!firestore || typeof firestore !== 'object') {\n    return Promise.resolve('failed')\n  }\n  let recovery = recoveries.get(firestore)\n  if (!recovery) {\n    recovery = createStallRecovery({\n      disable: () => disableNetwork(firestore),\n      enable: () => enableNetwork(firestore),\n      afterCycle: browserWedgeEscalationFor(firestore),\n    })\n    recoveries.set(firestore, recovery)\n  }\n  return recovery.recover().catch(() => 'failed' as const)\n}\n\n/**\n * Arms a stall timer for one read or listen. If `disarm` has not been called\n * within `stallMs`, `onStall` runs (by default, {@link recoverStalledFirestore}).\n * A tab that is hidden when the timer fires waits until it is shown, since\n * that is when a reader is waiting again.\n *\n * Returns `disarm`, which is idempotent.\n */\nexport function armFirestoreStallWatch(\n  firestore: Firestore | null | undefined,\n  options: { stallMs?: number; onStall?: () => void } = {},\n): () => void {\n  const { stallMs = FIRESTORE_STALL_MS } = options\n  const onStall =\n    options.onStall ?? (() => void recoverStalledFirestore(firestore))\n  let done = false\n  let onVisible: (() => void) | undefined\n  const fire = () => {\n    if (done) return\n    if (!documentVisible() && typeof document !== 'undefined') {\n      onVisible = () => {\n        if (!documentVisible()) return\n        document.removeEventListener('visibilitychange', onVisible!)\n        onVisible = undefined\n        fire()\n      }\n      document.addEventListener('visibilitychange', onVisible)\n      return\n    }\n    done = true\n    onStall()\n  }\n  const timer = setTimeout(fire, stallMs)\n  return () => {\n    if (done) return\n    done = true\n    clearTimeout(timer)\n    if (onVisible && typeof document !== 'undefined') {\n      document.removeEventListener('visibilitychange', onVisible)\n    }\n  }\n}\n"],"names":["disableNetwork","enableNetwork","browserWedgeEscalationFor","FIRESTORE_STALL_MS","STALL_RECOVERY_COOLDOWN_MS","NETWORK_STEP_TIMEOUT_MS","browserOnline","navigator","onLine","documentVisible","document","visibilityState","createStallRecovery","deps","disable","enable","isOnline","isVisible","now","Date","cooldownMs","stepTimeoutMs","afterCycle","lastStartedAt","running","bounded","step","Promise","resolve","timer","setTimeout","done","ok","clearTimeout","then","cycle","outcome","recover","at","undefined","finally","recoveries","WeakMap","recoverStalledFirestore","firestore","recovery","get","set","catch","armFirestoreStallWatch","options","stallMs","onStall","onVisible","fire","removeEventListener","addEventListener"],"mappings":"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"}

package/src/lib/hooks/use-host-document-version.d.ts

@@ -0,0 +1,52 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import type * as Aglyn from '@aglyn/aglyn';
+import type { DocumentReference } from 'firebase/firestore';
+import { type FirestoreDocOptions } from './firebase/firebase-services';
+/**
+ * A plugin document's working version, at
+ * `hosts/{hostId}/{collection}/{docId}/versions/{versionId}` — the storage a
+ * kind declared in `besignerDocuments` keeps (`plugin-manager/
+ * besigner-documents.ts`).
+ *
+ * Compressed at rest, and carrying the same asymmetry a component version
+ * does: the PUBLISHED tree lives on the parent document, because a placed
+ * document has to resolve on the hot path of a page render and one
+ * collection query reaches every one on the site. These documents are
+ * editing history — the besigner's draft surface — and nothing renders from
+ * them.
+ */
+export interface HostDocumentVersion {
+    displayName?: string;
+    /** The node a placed copy grafts from; absent on a tree never published. */
+    rootId?: Aglyn.NodeId;
+    nodes?: Record<Aglyn.NodeId, Aglyn.AglynNodeSchema>;
+    updatedAt?: unknown;
+}
+export interface HostDocumentVersionIds {
+    hostId: string;
+    /** The subcollection under `hosts/{hostId}` the document lives in. */
+    collection: string;
+    docId: string;
+    versionId: string;
+}
+export declare const useHostDocumentVersionRef: ({ hostId, collection, docId, versionId, }: HostDocumentVersionIds) => DocumentReference<HostDocumentVersion>;
+export declare const useHostDocumentVersion: (ids: HostDocumentVersionIds, options?: FirestoreDocOptions<HostDocumentVersion>) => {
+    doc: import("./firebase/firebase-services").ObservableStatus<HostDocumentVersion>;
+    setDoc: import("./helpers/use-modify-doc-callback").ModifyDocCallback<HostDocumentVersion>;
+};
+export default useHostDocumentVersion;