@aglyn/tenant-feature-instance 1.0.0-beta.202 → 1.0.0-beta.204

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aglyn/tenant-feature-instance",
-  "version": "1.0.0-beta.202",
+  "version": "1.0.0-beta.204",
   "license": "Apache-2.0",
   "homepage": "https://aglyn.com",
   "repository": {
@@ -25,11 +25,12 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@aglyn/aglyn": "1.0.0-beta.202",
-    "@aglyn/shared-data-enums": "1.0.0-beta.202",
-    "@aglyn/shared-ui-jsx": "1.0.0-beta.202",
-    "@aglyn/shared-util-http": "1.0.0-beta.202",
-    "@aglyn/shared-util-timestamp": "1.0.0-beta.202",
+    "@aglyn/aglyn": "1.0.0-beta.204",
+    "@aglyn/shared-data-enums": "1.0.0-beta.204",
+    "@aglyn/shared-ui-jsx": "1.0.0-beta.204",
+    "@aglyn/shared-util-email": "1.0.0-beta.204",
+    "@aglyn/shared-util-http": "1.0.0-beta.204",
+    "@aglyn/shared-util-timestamp": "1.0.0-beta.204",
     "@swc/helpers": "0.5.23",
     "lodash-es": "^4.18.1"
   },

package/src/lib/components/sender-readiness-panel.d.ts

@@ -0,0 +1,16 @@
+import type { SenderReadiness } from '@aglyn/shared-util-email';
+/** Accessible names of the rows, spelled once for the specs. */
+export declare const SENDER_READINESS_ROWS: {
+    readonly spf: "SPF";
+    readonly dkim: "DKIM";
+    readonly dmarc: "DMARC";
+    readonly alignment: "Alignment";
+};
+export interface SenderReadinessPanelProps {
+    readiness: SenderReadiness;
+}
+export declare function SenderReadinessPanel(props: SenderReadinessPanelProps): import("react").JSX.Element;
+export declare namespace SenderReadinessPanel {
+    var displayName: string;
+}
+export default SenderReadinessPanel;

package/src/lib/components/sender-readiness-panel.js

@@ -0,0 +1,160 @@
+/**
+ * @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.
+ */ 'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Alert, Box, Chip, Stack, Typography } from "@mui/material";
+/**
+ * SENDER READINESS, on a card (AGL-3328): SPF, DKIM and DMARC for the domain
+ * mail leaves from, and whether DMARC passes on a mechanism that lines up
+ * with the From domain.
+ *
+ * One component for both places a sender is set up — a sending domain in
+ * Emails and a connected mailbox in Sequences — so the two read the same
+ * zone the same way. What it renders is the server's verdict
+ * (`assessSenderReadiness`); it decides nothing itself.
+ */ const STATE_LABEL = {
+    pass: 'Pass',
+    warn: 'Check',
+    fail: 'Fail',
+    unknown: 'Not answered'
+};
+const STATE_COLOR = {
+    pass: 'success',
+    warn: 'warning',
+    fail: 'error',
+    unknown: 'default'
+};
+const OVERALL_SEVERITY = {
+    pass: 'success',
+    warn: 'warning',
+    fail: 'error',
+    unknown: 'info'
+};
+const OVERALL_SENTENCE = {
+    pass: 'Receivers can tell this mail is really from this domain.',
+    warn: 'Mail is authenticated, with something worth fixing below.',
+    fail: 'Receivers cannot confirm this mail is from this domain. Fix the failing record below.',
+    unknown: 'Some lookups went unanswered. Nothing is known to be wrong; check again in a few minutes.'
+};
+/** Accessible names of the rows, spelled once for the specs. */ export const SENDER_READINESS_ROWS = {
+    spf: 'SPF',
+    dkim: 'DKIM',
+    dmarc: 'DMARC',
+    alignment: 'Alignment'
+};
+function ReadinessRow(props) {
+    const { label, check } = props;
+    return /*#__PURE__*/ _jsxs(Stack, {
+        spacing: 0.25,
+        role: "group",
+        "aria-label": label,
+        children: [
+            /*#__PURE__*/ _jsxs(Stack, {
+                direction: "row",
+                spacing: 1,
+                useFlexGap: true,
+                sx: {
+                    alignItems: 'center',
+                    flexWrap: 'wrap'
+                },
+                children: [
+                    /*#__PURE__*/ _jsx(Chip, {
+                        size: "small",
+                        variant: "outlined",
+                        color: STATE_COLOR[check.state],
+                        label: STATE_LABEL[check.state]
+                    }),
+                    /*#__PURE__*/ _jsx(Typography, {
+                        variant: "body2",
+                        sx: {
+                            fontWeight: 'bold'
+                        },
+                        children: label
+                    }),
+                    check.host ? /*#__PURE__*/ _jsx(Typography, {
+                        variant: "caption",
+                        color: "text.secondary",
+                        sx: {
+                            fontFamily: 'monospace',
+                            overflowWrap: 'anywhere'
+                        },
+                        children: check.host
+                    }) : null
+                ]
+            }),
+            /*#__PURE__*/ _jsx(Typography, {
+                variant: "body2",
+                color: "text.secondary",
+                children: check.detail
+            }),
+            check.record ? /*#__PURE__*/ _jsx(Typography, {
+                variant: "caption",
+                color: "text.secondary",
+                sx: {
+                    fontFamily: 'monospace',
+                    overflowWrap: 'anywhere'
+                },
+                children: check.record.length > 160 ? `${check.record.slice(0, 160)}…` : check.record
+            }) : null
+        ]
+    });
+}
+export function SenderReadinessPanel(props) {
+    const { readiness } = props;
+    return /*#__PURE__*/ _jsxs(Stack, {
+        spacing: 1.5,
+        "aria-label": "Sender readiness",
+        children: [
+            /*#__PURE__*/ _jsxs(Box, {
+                children: [
+                    /*#__PURE__*/ _jsx(Typography, {
+                        variant: "subtitle2",
+                        children: 'Sender readiness'
+                    }),
+                    /*#__PURE__*/ _jsx(Typography, {
+                        variant: "caption",
+                        color: "text.secondary",
+                        children: `How receivers judge mail from ${readiness.fromDomain} sent by ${readiness.provider}. ` + `Checked ${new Date(readiness.checkedAtMs).toLocaleString()}.`
+                    })
+                ]
+            }),
+            /*#__PURE__*/ _jsx(Alert, {
+                severity: OVERALL_SEVERITY[readiness.overall],
+                children: OVERALL_SENTENCE[readiness.overall]
+            }),
+            /*#__PURE__*/ _jsx(ReadinessRow, {
+                label: SENDER_READINESS_ROWS.spf,
+                check: readiness.spf
+            }),
+            /*#__PURE__*/ _jsx(ReadinessRow, {
+                label: SENDER_READINESS_ROWS.dkim,
+                check: readiness.dkim
+            }),
+            /*#__PURE__*/ _jsx(ReadinessRow, {
+                label: SENDER_READINESS_ROWS.dmarc,
+                check: readiness.dmarc
+            }),
+            /*#__PURE__*/ _jsx(ReadinessRow, {
+                label: SENDER_READINESS_ROWS.alignment,
+                check: readiness.alignment
+            })
+        ]
+    });
+}
+SenderReadinessPanel.displayName = 'SenderReadinessPanel';
+export default SenderReadinessPanel;
+
+//# sourceMappingURL=sender-readiness-panel.js.map

package/src/lib/components/sender-readiness-panel.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../../libs/tenant/feature/instance/src/lib/components/sender-readiness-panel.tsx"],"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'use client'\n\nimport type {\n  SenderReadiness,\n  SenderReadinessCheck,\n  SenderReadinessState,\n} from '@aglyn/shared-util-email'\nimport { Alert, Box, Chip, Stack, Typography } from '@mui/material'\n\n/**\n * SENDER READINESS, on a card (AGL-3328): SPF, DKIM and DMARC for the domain\n * mail leaves from, and whether DMARC passes on a mechanism that lines up\n * with the From domain.\n *\n * One component for both places a sender is set up — a sending domain in\n * Emails and a connected mailbox in Sequences — so the two read the same\n * zone the same way. What it renders is the server's verdict\n * (`assessSenderReadiness`); it decides nothing itself.\n */\n\nconst STATE_LABEL: Record<SenderReadinessState, string> = {\n  pass: 'Pass',\n  warn: 'Check',\n  fail: 'Fail',\n  unknown: 'Not answered',\n}\n\nconst STATE_COLOR: Record<SenderReadinessState, 'success' | 'warning' | 'error' | 'default'> = {\n  pass: 'success',\n  warn: 'warning',\n  fail: 'error',\n  unknown: 'default',\n}\n\nconst OVERALL_SEVERITY: Record<SenderReadinessState, 'success' | 'warning' | 'error' | 'info'> = {\n  pass: 'success',\n  warn: 'warning',\n  fail: 'error',\n  unknown: 'info',\n}\n\nconst OVERALL_SENTENCE: Record<SenderReadinessState, string> = {\n  pass: 'Receivers can tell this mail is really from this domain.',\n  warn: 'Mail is authenticated, with something worth fixing below.',\n  fail: 'Receivers cannot confirm this mail is from this domain. Fix the failing record below.',\n  unknown: 'Some lookups went unanswered. Nothing is known to be wrong; check again in a few minutes.',\n}\n\n/** Accessible names of the rows, spelled once for the specs. */\nexport const SENDER_READINESS_ROWS = {\n  spf: 'SPF',\n  dkim: 'DKIM',\n  dmarc: 'DMARC',\n  alignment: 'Alignment',\n} as const\n\nfunction ReadinessRow(props: { label: string; check: SenderReadinessCheck }) {\n  const { label, check } = props\n  return (\n    <Stack spacing={0.25} role=\"group\" aria-label={label}>\n      <Stack direction=\"row\" spacing={1} useFlexGap sx={{ alignItems: 'center', flexWrap: 'wrap' }}>\n        <Chip\n          size=\"small\"\n          variant=\"outlined\"\n          color={STATE_COLOR[check.state]}\n          label={STATE_LABEL[check.state]}\n        />\n        <Typography variant=\"body2\" sx={{ fontWeight: 'bold' }}>\n          {label}\n        </Typography>\n        {check.host ? (\n          <Typography variant=\"caption\" color=\"text.secondary\" sx={{ fontFamily: 'monospace', overflowWrap: 'anywhere' }}>\n            {check.host}\n          </Typography>\n        ) : null}\n      </Stack>\n      <Typography variant=\"body2\" color=\"text.secondary\">\n        {check.detail}\n      </Typography>\n      {check.record ? (\n        <Typography\n          variant=\"caption\"\n          color=\"text.secondary\"\n          sx={{ fontFamily: 'monospace', overflowWrap: 'anywhere' }}\n        >\n          {check.record.length > 160 ? `${check.record.slice(0, 160)}…` : check.record}\n        </Typography>\n      ) : null}\n    </Stack>\n  )\n}\n\nexport interface SenderReadinessPanelProps {\n  readiness: SenderReadiness\n}\n\nexport function SenderReadinessPanel(props: SenderReadinessPanelProps) {\n  const { readiness } = props\n  return (\n    <Stack spacing={1.5} aria-label=\"Sender readiness\">\n      <Box>\n        <Typography variant=\"subtitle2\">{'Sender readiness'}</Typography>\n        <Typography variant=\"caption\" color=\"text.secondary\">\n          {`How receivers judge mail from ${readiness.fromDomain} sent by ${readiness.provider}. ` +\n            `Checked ${new Date(readiness.checkedAtMs).toLocaleString()}.`}\n        </Typography>\n      </Box>\n      <Alert severity={OVERALL_SEVERITY[readiness.overall]}>{OVERALL_SENTENCE[readiness.overall]}</Alert>\n      <ReadinessRow label={SENDER_READINESS_ROWS.spf} check={readiness.spf} />\n      <ReadinessRow label={SENDER_READINESS_ROWS.dkim} check={readiness.dkim} />\n      <ReadinessRow label={SENDER_READINESS_ROWS.dmarc} check={readiness.dmarc} />\n      <ReadinessRow label={SENDER_READINESS_ROWS.alignment} check={readiness.alignment} />\n    </Stack>\n  )\n}\nSenderReadinessPanel.displayName = 'SenderReadinessPanel'\n\nexport default SenderReadinessPanel\n"],"names":["Alert","Box","Chip","Stack","Typography","STATE_LABEL","pass","warn","fail","unknown","STATE_COLOR","OVERALL_SEVERITY","OVERALL_SENTENCE","SENDER_READINESS_ROWS","spf","dkim","dmarc","alignment","ReadinessRow","props","label","check","spacing","role","aria-label","direction","useFlexGap","sx","alignItems","flexWrap","size","variant","color","state","fontWeight","host","fontFamily","overflowWrap","detail","record","length","slice","SenderReadinessPanel","readiness","fromDomain","provider","Date","checkedAtMs","toLocaleString","severity","overall","displayName"],"mappings":"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"}

package/src/lib/hooks/firebase/firestore-bounded-read.d.ts

@@ -0,0 +1,79 @@
+/**
+ * @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 DocumentData, type DocumentReference, type DocumentSnapshot, type Firestore, type Query, type QuerySnapshot } from 'firebase/firestore';
+/**
+ * ONE-OFF READS THAT CANNOT HANG (AGL-3373).
+ *
+ * `getDocs` and `getDoc` wait for the server whenever the client believes it
+ * is online. When the client is wrong about that — the multi-tab wedge
+ * `firestore-stall-recovery.ts` describes — they never settle, and a page
+ * that set `loading` before awaiting one never clears it. The notifications
+ * feed read "No notifications match these filters" for ten minutes that way.
+ *
+ * These race the server read against {@link FIRESTORE_STALL_MS}. If the
+ * server has not answered by then, the client is asked to recover, and the
+ * read settles from the local cache with `stale: true`, so the caller can
+ * say "this may be out of date" instead of spinning. The server read is not
+ * abandoned: `fresh` resolves with its answer if it arrives, so a caller can
+ * swap the cached rows for confirmed ones without reading again.
+ *
+ * When the cache cannot answer either — `getDocFromCache` for a document the
+ * cache has never held — the read REJECTS with {@link FirestoreStallError}.
+ * A caller's error path is a better place to land than a spinner that never
+ * ends.
+ */
+/** A read that settled, and whether it had to settle for the cache. */
+export interface BoundedRead<S> {
+    snapshot: S;
+    /**
+     * The server did not answer in time and `snapshot` is the local cache's.
+     * It may be out of date.
+     */
+    stale: boolean;
+    /**
+     * For a stale read, the server's answer if it ever arrives, otherwise
+     * `undefined`. Never rejects. Absent for a read the server answered.
+     */
+    fresh?: Promise<S | undefined>;
+}
+export interface BoundedReadOptions {
+    /** Override {@link FIRESTORE_STALL_MS}. */
+    stallMs?: number;
+}
+/** Neither the server nor the cache could answer in time. */
+export declare class FirestoreStallError extends Error {
+    readonly cacheError?: unknown;
+    readonly code = "unavailable";
+    /** Why the cache could not answer. */
+    constructor(cacheError?: unknown);
+}
+interface BoundedReadDeps<S> {
+    server: () => Promise<S>;
+    cache: () => Promise<S>;
+    firestore: Firestore | undefined;
+    stallMs: number;
+    recover?: (firestore: Firestore | undefined) => unknown;
+}
+/** The race itself, over injected reads. */
+export declare function boundedRead<S>(deps: BoundedReadDeps<S>): Promise<BoundedRead<S>>;
+/** `getDocs`, bounded. See the module comment. */
+export declare function getDocsBounded<T = DocumentData>(query: Query<T>, options?: BoundedReadOptions): Promise<BoundedRead<QuerySnapshot<T>>>;
+/** `getDoc`, bounded. See the module comment. */
+export declare function getDocBounded<T = DocumentData>(reference: DocumentReference<T>, options?: BoundedReadOptions): Promise<BoundedRead<DocumentSnapshot<T>>>;
+/** The notice a surface shows over a stale read. */
+export declare const STALE_READ_NOTICE = "This may be out of date \u2014 reconnecting\u2026";
+export {};

package/src/lib/hooks/firebase/firestore-bounded-read.js

@@ -0,0 +1,80 @@
+/**
+ * @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 { getDoc, getDocFromCache, getDocs, getDocsFromCache } from "firebase/firestore";
+import { FIRESTORE_STALL_MS, recoverStalledFirestore } from "./firestore-stall-recovery.js";
+/** Neither the server nor the cache could answer in time. */ export class FirestoreStallError extends Error {
+    /** Why the cache could not answer. */ constructor(cacheError){
+        super('The server did not answer in time and nothing is cached for this read.'), this.cacheError = cacheError, this.code = 'unavailable';
+        this.name = 'FirestoreStallError';
+    }
+}
+const STALLED = Symbol('stalled');
+/** The race itself, over injected reads. */ export async function boundedRead(deps) {
+    var _deps_recover;
+    const { server, cache, firestore, stallMs } = deps;
+    const recover = (_deps_recover = deps.recover) != null ? _deps_recover : recoverStalledFirestore;
+    const serverRead = server();
+    let timer;
+    const stalled = new Promise((resolve)=>{
+        timer = setTimeout(()=>resolve(STALLED), stallMs);
+    });
+    let winner;
+    try {
+        winner = await Promise.race([
+            serverRead,
+            stalled
+        ]);
+    } finally{
+        clearTimeout(timer);
+    }
+    if (winner !== STALLED) return {
+        snapshot: winner,
+        stale: false
+    };
+    void recover(firestore);
+    const fresh = serverRead.then((snapshot)=>snapshot, ()=>undefined);
+    try {
+        const snapshot = await cache();
+        return {
+            snapshot,
+            stale: true,
+            fresh
+        };
+    } catch (error) {
+        throw new FirestoreStallError(error);
+    }
+}
+/** `getDocs`, bounded. See the module comment. */ export function getDocsBounded(query, options = {}) {
+    var _options_stallMs;
+    return boundedRead({
+        server: ()=>getDocs(query),
+        cache: ()=>getDocsFromCache(query),
+        firestore: query.firestore,
+        stallMs: (_options_stallMs = options.stallMs) != null ? _options_stallMs : FIRESTORE_STALL_MS
+    });
+}
+/** `getDoc`, bounded. See the module comment. */ export function getDocBounded(reference, options = {}) {
+    var _options_stallMs;
+    return boundedRead({
+        server: ()=>getDoc(reference),
+        cache: ()=>getDocFromCache(reference),
+        firestore: reference.firestore,
+        stallMs: (_options_stallMs = options.stallMs) != null ? _options_stallMs : FIRESTORE_STALL_MS
+    });
+}
+/** The notice a surface shows over a stale read. */ export const STALE_READ_NOTICE = 'This may be out of date — reconnecting…';
+
+//# sourceMappingURL=firestore-bounded-read.js.map

package/src/lib/hooks/firebase/firestore-bounded-read.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../../../libs/tenant/feature/instance/src/lib/hooks/firebase/firestore-bounded-read.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  getDoc,\n  getDocFromCache,\n  getDocs,\n  getDocsFromCache,\n  type DocumentData,\n  type DocumentReference,\n  type DocumentSnapshot,\n  type Firestore,\n  type Query,\n  type QuerySnapshot,\n} from 'firebase/firestore'\nimport {\n  FIRESTORE_STALL_MS,\n  recoverStalledFirestore,\n} from './firestore-stall-recovery'\n\n/**\n * ONE-OFF READS THAT CANNOT HANG (AGL-3373).\n *\n * `getDocs` and `getDoc` wait for the server whenever the client believes it\n * is online. When the client is wrong about that — the multi-tab wedge\n * `firestore-stall-recovery.ts` describes — they never settle, and a page\n * that set `loading` before awaiting one never clears it. The notifications\n * feed read \"No notifications match these filters\" for ten minutes that way.\n *\n * These race the server read against {@link FIRESTORE_STALL_MS}. If the\n * server has not answered by then, the client is asked to recover, and the\n * read settles from the local cache with `stale: true`, so the caller can\n * say \"this may be out of date\" instead of spinning. The server read is not\n * abandoned: `fresh` resolves with its answer if it arrives, so a caller can\n * swap the cached rows for confirmed ones without reading again.\n *\n * When the cache cannot answer either — `getDocFromCache` for a document the\n * cache has never held — the read REJECTS with {@link FirestoreStallError}.\n * A caller's error path is a better place to land than a spinner that never\n * ends.\n */\n\n/** A read that settled, and whether it had to settle for the cache. */\nexport interface BoundedRead<S> {\n  snapshot: S\n  /**\n   * The server did not answer in time and `snapshot` is the local cache's.\n   * It may be out of date.\n   */\n  stale: boolean\n  /**\n   * For a stale read, the server's answer if it ever arrives, otherwise\n   * `undefined`. Never rejects. Absent for a read the server answered.\n   */\n  fresh?: Promise<S | undefined>\n}\n\nexport interface BoundedReadOptions {\n  /** Override {@link FIRESTORE_STALL_MS}. */\n  stallMs?: number\n}\n\n/** Neither the server nor the cache could answer in time. */\nexport class FirestoreStallError extends Error {\n  readonly code = 'unavailable'\n  /** Why the cache could not answer. */\n  constructor(readonly cacheError?: unknown) {\n    super(\n      'The server did not answer in time and nothing is cached for this read.',\n    )\n    this.name = 'FirestoreStallError'\n  }\n}\n\ninterface BoundedReadDeps<S> {\n  server: () => Promise<S>\n  cache: () => Promise<S>\n  firestore: Firestore | undefined\n  stallMs: number\n  recover?: (firestore: Firestore | undefined) => unknown\n}\n\nconst STALLED = Symbol('stalled')\n\n/** The race itself, over injected reads. */\nexport async function boundedRead<S>(\n  deps: BoundedReadDeps<S>,\n): Promise<BoundedRead<S>> {\n  const { server, cache, firestore, stallMs } = deps\n  const recover = deps.recover ?? recoverStalledFirestore\n  const serverRead = server()\n  let timer: ReturnType<typeof setTimeout> | undefined\n  const stalled = new Promise<typeof STALLED>((resolve) => {\n    timer = setTimeout(() => resolve(STALLED), stallMs)\n  })\n  let winner: S | typeof STALLED\n  try {\n    winner = await Promise.race([serverRead, stalled])\n  } finally {\n    clearTimeout(timer)\n  }\n  if (winner !== STALLED) return { snapshot: winner, stale: false }\n\n  void recover(firestore)\n  const fresh = serverRead.then(\n    (snapshot) => snapshot,\n    () => undefined,\n  )\n  try {\n    const snapshot = await cache()\n    return { snapshot, stale: true, fresh }\n  } catch (error) {\n    throw new FirestoreStallError(error)\n  }\n}\n\n/** `getDocs`, bounded. See the module comment. */\nexport function getDocsBounded<T = DocumentData>(\n  query: Query<T>,\n  options: BoundedReadOptions = {},\n): Promise<BoundedRead<QuerySnapshot<T>>> {\n  return boundedRead({\n    server: () => getDocs(query),\n    cache: () => getDocsFromCache(query),\n    firestore: (query as { firestore?: Firestore }).firestore,\n    stallMs: options.stallMs ?? FIRESTORE_STALL_MS,\n  })\n}\n\n/** `getDoc`, bounded. See the module comment. */\nexport function getDocBounded<T = DocumentData>(\n  reference: DocumentReference<T>,\n  options: BoundedReadOptions = {},\n): Promise<BoundedRead<DocumentSnapshot<T>>> {\n  return boundedRead({\n    server: () => getDoc(reference),\n    cache: () => getDocFromCache(reference),\n    firestore: (reference as { firestore?: Firestore }).firestore,\n    stallMs: options.stallMs ?? FIRESTORE_STALL_MS,\n  })\n}\n\n/** The notice a surface shows over a stale read. */\nexport const STALE_READ_NOTICE = 'This may be out of date — reconnecting…'\n"],"names":["getDoc","getDocFromCache","getDocs","getDocsFromCache","FIRESTORE_STALL_MS","recoverStalledFirestore","FirestoreStallError","Error","cacheError","code","name","STALLED","Symbol","boundedRead","deps","server","cache","firestore","stallMs","recover","serverRead","timer","stalled","Promise","resolve","setTimeout","winner","race","clearTimeout","snapshot","stale","fresh","then","undefined","error","getDocsBounded","query","options","getDocBounded","reference","STALE_READ_NOTICE"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED,SACEA,MAAM,EACNC,eAAe,EACfC,OAAO,EACPC,gBAAgB,QAOX,qBAAoB;AAC3B,SACEC,kBAAkB,EAClBC,uBAAuB,QAClB,gCAA4B;AA4CnC,2DAA2D,GAC3D,OAAO,MAAMC,4BAA4BC;IAEvC,oCAAoC,GACpC,YAAY,AAASC,UAAoB,CAAE;QACzC,KAAK,CACH,gFAFiBA,aAAAA,iBAFZC,OAAO;QAMd,IAAI,CAACC,IAAI,GAAG;IACd;AACF;AAUA,MAAMC,UAAUC,OAAO;AAEvB,0CAA0C,GAC1C,OAAO,eAAeC,YACpBC,IAAwB;QAGRA;IADhB,MAAM,EAAEC,MAAM,EAAEC,KAAK,EAAEC,SAAS,EAAEC,OAAO,EAAE,GAAGJ;IAC9C,MAAMK,WAAUL,gBAAAA,KAAKK,OAAO,YAAZL,gBAAgBT;IAChC,MAAMe,aAAaL;IACnB,IAAIM;IACJ,MAAMC,UAAU,IAAIC,QAAwB,CAACC;QAC3CH,QAAQI,WAAW,IAAMD,QAAQb,UAAUO;IAC7C;IACA,IAAIQ;IACJ,IAAI;QACFA,SAAS,MAAMH,QAAQI,IAAI,CAAC;YAACP;YAAYE;SAAQ;IACnD,SAAU;QACRM,aAAaP;IACf;IACA,IAAIK,WAAWf,SAAS,OAAO;QAAEkB,UAAUH;QAAQI,OAAO;IAAM;IAEhE,KAAKX,QAAQF;IACb,MAAMc,QAAQX,WAAWY,IAAI,CAC3B,CAACH,WAAaA,UACd,IAAMI;IAER,IAAI;QACF,MAAMJ,WAAW,MAAMb;QACvB,OAAO;YAAEa;YAAUC,OAAO;YAAMC;QAAM;IACxC,EAAE,OAAOG,OAAO;QACd,MAAM,IAAI5B,oBAAoB4B;IAChC;AACF;AAEA,gDAAgD,GAChD,OAAO,SAASC,eACdC,KAAe,EACfC,UAA8B,CAAC,CAAC;QAMrBA;IAJX,OAAOxB,YAAY;QACjBE,QAAQ,IAAMb,QAAQkC;QACtBpB,OAAO,IAAMb,iBAAiBiC;QAC9BnB,WAAW,AAACmB,MAAoCnB,SAAS;QACzDC,OAAO,GAAEmB,mBAAAA,QAAQnB,OAAO,YAAfmB,mBAAmBjC;IAC9B;AACF;AAEA,+CAA+C,GAC/C,OAAO,SAASkC,cACdC,SAA+B,EAC/BF,UAA8B,CAAC,CAAC;QAMrBA;IAJX,OAAOxB,YAAY;QACjBE,QAAQ,IAAMf,OAAOuC;QACrBvB,OAAO,IAAMf,gBAAgBsC;QAC7BtB,WAAW,AAACsB,UAAwCtB,SAAS;QAC7DC,OAAO,GAAEmB,mBAAAA,QAAQnB,OAAO,YAAfmB,mBAAmBjC;IAC9B;AACF;AAEA,kDAAkD,GAClD,OAAO,MAAMoC,oBAAoB,0CAAyC"}

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

@@ -0,0 +1,142 @@
+/**
+ * @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 Firestore } from 'firebase/firestore';
+/**
+ * RECOVERING A FIRESTORE CLIENT THAT HAS STOPPED SYNCING (AGL-3373).
+ *
+ * ## The wedge
+ *
+ * The console runs the persistent cache with `persistentMultipleTabManager`
+ * (`firestore-cache.ts`). Only the PRIMARY tab talks to the backend; every
+ * other tab reads the shared IndexedDB cache and takes its online state from
+ * a `localStorage` record the primary writes. A secondary that believes the
+ * client is online answers a `getDocs` only once the primary has synced the
+ * query, and raises no first snapshot for a listener whose cache is empty.
+ *
+ * When the primary dies without handing over — a crashed, discarded or
+ * frozen tab — its "Online" record outlives it, and until some tab runs the
+ * lease election and wins, nothing syncs. The election runs on a 4-second
+ * timer inside each tab, which the browser throttles to about once a minute
+ * in a hidden tab. On 2026-09-28 no live tab synced for about ten minutes:
+ * the notifications page never left its loading state and a staff page sat
+ * on its splash until a fresh tab (which wins the election on start) was
+ * opened.
+ *
+ * ## The recovery, and why it is this one
+ *
+ * `disableNetwork` then `enableNetwork`, from the tab that noticed. Both are
+ * public API, and in the multi-tab client each one calls
+ * `setNetworkEnabled`, which schedules the lease election for IMMEDIATE
+ * execution instead of the next (possibly throttled) timer tick. A visible
+ * tab that finds the lease lapsed takes it, starts its own streams and
+ * writes its own online state, which replaces the dead tab's. A tab that was
+ * already primary with a silently dead stream gets fresh streams.
+ *
+ * Nothing is lost. Writes made meanwhile sit in the mutation queue (in
+ * IndexedDB, under the persistent cache) and are sent when the network comes
+ * back; the SDK's own contract for `disableNetwork` is that writes queue.
+ *
+ * The rejected alternatives:
+ *
+ * - **Clearing the persistence cache** (`terminate` + `clearIndexedDbPersistence`).
+ *   It deletes the mutation queue, so pending writes are lost, and
+ *   `waitForPendingWrites` cannot drain them first because draining is the
+ *   very thing that is stuck. It also refuses to run while any other tab
+ *   holds the database, which in a multi-tab wedge is always. And
+ *   `terminate` invalidates the one `Firestore` instance every hook in the
+ *   console holds.
+ * - **Pruning the dead tab's online-state record at startup**, beside the
+ *   AGL-2845 prune. The SDK already ignores an online-state record at
+ *   startup unless its writer is an active, non-zombie client
+ *   (`WebStorageSharedClientState.handleOnlineStateEvent`), and a freshly
+ *   started tab wins the election anyway — which is why a fresh tab fixed
+ *   the incident. The tabs that stayed stuck were the ones ALREADY running,
+ *   which a startup prune never reaches.
+ * - **`persistentSingleTabManager`.** It removes cross-tab dependency, but
+ *   every tab after the first falls back to a memory cache, so writes made
+ *   offline in those tabs are lost when they close. And a tab still on the
+ *   multi-tab build that meets a single-tab lease holder fails its queue
+ *   with `failed-precondition` until reloaded, so the rollout itself would
+ *   wedge the tabs left open across it.
+ *
+ * ## Guards
+ *
+ * - **Online only.** A browser that reports no network is correctly offline,
+ *   and the cache answering is the cache doing its job.
+ * - **Visible only.** A hidden tab's timers are throttled and its reader is
+ *   not waiting; if it is stalled, it recovers the moment it is looked at.
+ * - **Once per {@link STALL_RECOVERY_COOLDOWN_MS} per client.** Every list on
+ *   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.
+ */
+/**
+ * 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
+ * in well under two seconds; this leaves room for a slow network without
+ * leaving a reader on a spinner for long.
+ */
+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;
+/** What a recovery request did. */
+export type StallRecoveryOutcome = 
+/** The browser reports no network: the cache is the right answer. */
+'offline'
+/** The tab is hidden: nobody is waiting on it. */
+ | 'hidden'
+/** A recovery ran moments ago; this request rode on it. */
+ | 'cooling'
+/** The network was cycled. */
+ | 'recovered'
+/** The cycle threw; the network was still re-enabled if at all possible. */
+ | 'failed';
+export interface StallRecoveryDeps {
+    /** Take the client off the network. */
+    disable: () => Promise<void>;
+    /** Put it back. */
+    enable: () => Promise<void>;
+    /** `navigator.onLine`, or `true` where there is no navigator. */
+    isOnline?: () => boolean;
+    /** Whether the document is visible, or `true` where there is none. */
+    isVisible?: () => boolean;
+    now?: () => number;
+    cooldownMs?: number;
+}
+export interface StallRecovery {
+    recover: () => Promise<StallRecoveryOutcome>;
+}
+/** The recovery for one client, with its guards. Pure over `deps`. */
+export declare function createStallRecovery(deps: StallRecoveryDeps): StallRecovery;
+/**
+ * Recovers `firestore` if it has stalled. Safe to call from every reader
+ * that notices: the guards above collapse the calls into at most one network
+ * cycle per cooldown. Never rejects.
+ */
+export declare function recoverStalledFirestore(firestore: Firestore | null | undefined): Promise<StallRecoveryOutcome>;
+/**
+ * Arms a stall timer for one read or listen. If `disarm` has not been called
+ * within `stallMs`, `onStall` runs (by default, {@link recoverStalledFirestore}).
+ * A tab that is hidden when the timer fires waits until it is shown, since
+ * that is when a reader is waiting again.
+ *
+ * Returns `disarm`, which is idempotent.
+ */
+export declare function armFirestoreStallWatch(firestore: Firestore | null | undefined, options?: {
+    stallMs?: number;
+    onStall?: () => void;
+}): () => void;