@aglyn/tenant-feature-instance 1.0.0-beta.143

package/src/lib/hooks/use-console-host-route.js

@@ -0,0 +1,77 @@
+/**
+ * @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 { doc, getDoc } from "firebase/firestore";
+import { useEffect, useState } from "react";
+import { useFirestore } from "./firebase/firebase-services.js";
+/**
+ * Console route base for a host: `/{orgSlug}/hosts/{subdomain}` (AGL-673).
+ *
+ * Plugin components are handed a host DOC ID and used to build links as
+ * `/{hostDocId}/…`. Console routes have been `/[orgSlug]/hosts/[subdomain]/…`
+ * since AGL-621/622, so every one of those links silently began 404ing —
+ * found three separate times in different plugins, each looking like a new
+ * bug. This is the one resolution, so the next plugin does not become the
+ * fourth.
+ *
+ * `null` until resolved, and `null` forever if the org has no slug. Callers
+ * must render plain text rather than a link in that case: a link to nowhere
+ * is worse than no link.
+ *
+ * Reads `hostIndex` (signed-in readable, mirrors `subdomain` and `orgId`)
+ * plus the org doc for its slug — both cheap and already cached by the SDK
+ * on most screens.
+ */ export function useConsoleHostRoute(hostId) {
+    const firestore = useFirestore();
+    const [resolved, setResolved] = useState({
+        base: null,
+        orgSlug: null,
+        subdomain: null
+    });
+    useEffect(()=>{
+        if (!hostId) return;
+        let active = true;
+        void (async ()=>{
+            try {
+                var _index_get;
+                const index = await getDoc(doc(firestore, 'hostIndex', hostId));
+                const orgId = index.get('orgId');
+                const subdomain = (_index_get = index.get('subdomain')) != null ? _index_get : hostId;
+                if (!orgId) return;
+                const org = await getDoc(doc(firestore, 'orgs', orgId));
+                const orgSlug = org.get('slug');
+                if (!active || !orgSlug) return;
+                setResolved({
+                    base: `/${orgSlug}/hosts/${subdomain}`,
+                    orgSlug,
+                    subdomain
+                });
+            } catch (unused) {
+            // Unreadable index or org — stay unresolved so callers degrade.
+            }
+        })();
+        return ()=>{
+            active = false;
+        };
+    }, [
+        firestore,
+        hostId
+    ]);
+    return resolved;
+}
+export default useConsoleHostRoute;
+
+//# sourceMappingURL=use-console-host-route.js.map

package/src/lib/hooks/use-console-host-route.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../../libs/tenant/feature/instance/src/lib/hooks/use-console-host-route.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'use client'\n\nimport { doc, getDoc } from 'firebase/firestore'\nimport { useEffect, useState } from 'react'\nimport { useFirestore } from './firebase/firebase-services'\n\n/**\n * Console route base for a host: `/{orgSlug}/hosts/{subdomain}` (AGL-673).\n *\n * Plugin components are handed a host DOC ID and used to build links as\n * `/{hostDocId}/…`. Console routes have been `/[orgSlug]/hosts/[subdomain]/…`\n * since AGL-621/622, so every one of those links silently began 404ing —\n * found three separate times in different plugins, each looking like a new\n * bug. This is the one resolution, so the next plugin does not become the\n * fourth.\n *\n * `null` until resolved, and `null` forever if the org has no slug. Callers\n * must render plain text rather than a link in that case: a link to nowhere\n * is worse than no link.\n *\n * Reads `hostIndex` (signed-in readable, mirrors `subdomain` and `orgId`)\n * plus the org doc for its slug — both cheap and already cached by the SDK\n * on most screens.\n */\nexport function useConsoleHostRoute(hostId: string | undefined | null): {\n  base: string | null\n  orgSlug: string | null\n  subdomain: string | null\n} {\n  const firestore = useFirestore()\n  const [resolved, setResolved] = useState<{\n    base: string | null\n    orgSlug: string | null\n    subdomain: string | null\n  }>({ base: null, orgSlug: null, subdomain: null })\n\n  useEffect(() => {\n    if (!hostId) return\n    let active = true\n    void (async () => {\n      try {\n        const index = await getDoc(doc(firestore, 'hostIndex', hostId))\n        const orgId = index.get('orgId') as string | undefined\n        const subdomain = (index.get('subdomain') as string | undefined) ?? hostId\n        if (!orgId) return\n        const org = await getDoc(doc(firestore, 'orgs', orgId))\n        const orgSlug = org.get('slug') as string | undefined\n        if (!active || !orgSlug) return\n        setResolved({\n          base: `/${orgSlug}/hosts/${subdomain}`,\n          orgSlug,\n          subdomain,\n        })\n      } catch {\n        // Unreadable index or org — stay unresolved so callers degrade.\n      }\n    })()\n    return () => {\n      active = false\n    }\n  }, [firestore, hostId])\n\n  return resolved\n}\n\nexport default useConsoleHostRoute\n"],"names":["doc","getDoc","useEffect","useState","useFirestore","useConsoleHostRoute","hostId","firestore","resolved","setResolved","base","orgSlug","subdomain","active","index","orgId","get","org"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GACD;AAEA,SAASA,GAAG,EAAEC,MAAM,QAAQ,qBAAoB;AAChD,SAASC,SAAS,EAAEC,QAAQ,QAAQ,QAAO;AAC3C,SAASC,YAAY,QAAQ,kCAA8B;AAE3D;;;;;;;;;;;;;;;;;CAiBC,GACD,OAAO,SAASC,oBAAoBC,MAAiC;IAKnE,MAAMC,YAAYH;IAClB,MAAM,CAACI,UAAUC,YAAY,GAAGN,SAI7B;QAAEO,MAAM;QAAMC,SAAS;QAAMC,WAAW;IAAK;IAEhDV,UAAU;QACR,IAAI,CAACI,QAAQ;QACb,IAAIO,SAAS;QACb,KAAK,AAAC,CAAA;YACJ,IAAI;oBAGiBC;gBAFnB,MAAMA,QAAQ,MAAMb,OAAOD,IAAIO,WAAW,aAAaD;gBACvD,MAAMS,QAAQD,MAAME,GAAG,CAAC;gBACxB,MAAMJ,aAAaE,aAAAA,MAAME,GAAG,CAAC,wBAAVF,aAAiDR;gBACpE,IAAI,CAACS,OAAO;gBACZ,MAAME,MAAM,MAAMhB,OAAOD,IAAIO,WAAW,QAAQQ;gBAChD,MAAMJ,UAAUM,IAAID,GAAG,CAAC;gBACxB,IAAI,CAACH,UAAU,CAACF,SAAS;gBACzBF,YAAY;oBACVC,MAAM,CAAC,CAAC,EAAEC,QAAQ,OAAO,EAAEC,WAAW;oBACtCD;oBACAC;gBACF;YACF,EAAE,eAAM;YACN,gEAAgE;YAClE;QACF,CAAA;QACA,OAAO;YACLC,SAAS;QACX;IACF,GAAG;QAACN;QAAWD;KAAO;IAEtB,OAAOE;AACT;AAEA,eAAeH,oBAAmB"}

package/src/lib/hooks/use-duplicate-resource-api.d.ts

@@ -0,0 +1,43 @@
+/**
+ * @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 { DuplicableHostResourceKind } from '@aglyn/aglyn/app-utils/duplicate-resource';
+export interface DuplicateHostResourceOptions {
+    hostId: string;
+    kind: DuplicableHostResourceKind;
+    sourceId: string;
+    /** The name the copy takes; blank means `Copy of <source>`. */
+    name?: string;
+    /**
+     * Minted once per dialog, so a double click or a retry after a dropped
+     * response makes one copy and answers with it.
+     */
+    attemptKey: string;
+}
+export interface DuplicatedHostResource {
+    id: string;
+    /** The copy's first version, for the kinds that open by version. */
+    versionId: string | null;
+    name: string;
+}
+/**
+ * Asks the resources door to copy a site resource whole, as a draft
+ * (AGL-2936). The same route the create hook posts to, with
+ * `action: 'duplicate'`; the server reads the source, so nothing about it
+ * crosses the wire but its id.
+ */
+export declare function useDuplicateResourceApi(): (options: DuplicateHostResourceOptions) => Promise<DuplicatedHostResource>;
+export default useDuplicateResourceApi;

package/src/lib/hooks/use-duplicate-resource-api.js

@@ -0,0 +1,61 @@
+/**
+ * @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";
+import { authorizedFetch } from "@aglyn/shared-util-http/authorized-token";
+import { useCallback } from "react";
+import { useUser } from "./firebase/firebase-services.js";
+/**
+ * Asks the resources door to copy a site resource whole, as a draft
+ * (AGL-2936). The same route the create hook posts to, with
+ * `action: 'duplicate'`; the server reads the source, so nothing about it
+ * crosses the wire but its id.
+ */ export function useDuplicateResourceApi() {
+    const { data: user } = useUser();
+    return useCallback(async ({ hostId, kind, sourceId, name, attemptKey })=>{
+        var _ref, _result_name;
+        const response = await authorizedFetch(user, '/api/hosts/resources', {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json'
+            },
+            body: JSON.stringify(_extends({
+                hostId,
+                resource: kind,
+                action: 'duplicate',
+                sourceId
+            }, name ? {
+                name
+            } : {}, {
+                attemptKey
+            }))
+        });
+        const result = await response.json().catch(()=>({}));
+        if (!response.ok) {
+            var _ref1;
+            throw new Error((_ref1 = result == null ? void 0 : result.error) != null ? _ref1 : 'Duplicate failed');
+        }
+        return {
+            id: String(result.id),
+            versionId: result.versionId ? String(result.versionId) : null,
+            name: String((_ref = (_result_name = result.name) != null ? _result_name : name) != null ? _ref : '')
+        };
+    }, [
+        user
+    ]);
+}
+export default useDuplicateResourceApi;
+
+//# sourceMappingURL=use-duplicate-resource-api.js.map

package/src/lib/hooks/use-duplicate-resource-api.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../../libs/tenant/feature/instance/src/lib/hooks/use-duplicate-resource-api.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 { DuplicableHostResourceKind } from '@aglyn/aglyn/app-utils/duplicate-resource'\nimport { authorizedFetch } from '@aglyn/shared-util-http/authorized-token'\nimport { useCallback } from 'react'\nimport { useUser } from './firebase/firebase-services'\n\nexport interface DuplicateHostResourceOptions {\n  hostId: string\n  kind: DuplicableHostResourceKind\n  sourceId: string\n  /** The name the copy takes; blank means `Copy of <source>`. */\n  name?: string\n  /**\n   * Minted once per dialog, so a double click or a retry after a dropped\n   * response makes one copy and answers with it.\n   */\n  attemptKey: string\n}\n\nexport interface DuplicatedHostResource {\n  id: string\n  /** The copy's first version, for the kinds that open by version. */\n  versionId: string | null\n  name: string\n}\n\n/**\n * Asks the resources door to copy a site resource whole, as a draft\n * (AGL-2936). The same route the create hook posts to, with\n * `action: 'duplicate'`; the server reads the source, so nothing about it\n * crosses the wire but its id.\n */\nexport function useDuplicateResourceApi(): (\n  options: DuplicateHostResourceOptions,\n) => Promise<DuplicatedHostResource> {\n  const { data: user } = useUser()\n  return useCallback(\n    async ({ hostId, kind, sourceId, name, attemptKey }) => {\n      const response = await authorizedFetch(user, '/api/hosts/resources', {\n        method: 'POST',\n        headers: { 'Content-Type': 'application/json' },\n        body: JSON.stringify({\n          hostId,\n          resource: kind,\n          action: 'duplicate',\n          sourceId,\n          ...(name ? { name } : {}),\n          attemptKey,\n        }),\n      })\n      const result = await response.json().catch(() => ({}))\n      if (!response.ok) {\n        throw new Error(result?.error ?? 'Duplicate failed')\n      }\n      return {\n        id: String(result.id),\n        versionId: result.versionId ? String(result.versionId) : null,\n        name: String(result.name ?? name ?? ''),\n      }\n    },\n    [user],\n  )\n}\n\nexport default useDuplicateResourceApi\n"],"names":["authorizedFetch","useCallback","useUser","useDuplicateResourceApi","data","user","hostId","kind","sourceId","name","attemptKey","result","response","method","headers","body","JSON","stringify","resource","action","json","catch","ok","Error","error","id","String","versionId"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC;AAGD,SAASA,eAAe,QAAQ,2CAA0C;AAC1E,SAASC,WAAW,QAAQ,QAAO;AACnC,SAASC,OAAO,QAAQ,kCAA8B;AAsBtD;;;;;CAKC,GACD,OAAO,SAASC;IAGd,MAAM,EAAEC,MAAMC,IAAI,EAAE,GAAGH;IACvB,OAAOD,YACL,OAAO,EAAEK,MAAM,EAAEC,IAAI,EAAEC,QAAQ,EAAEC,IAAI,EAAEC,UAAU,EAAE;YAoBlCC,MAAAA;QAnBf,MAAMC,WAAW,MAAMZ,gBAAgBK,MAAM,wBAAwB;YACnEQ,QAAQ;YACRC,SAAS;gBAAE,gBAAgB;YAAmB;YAC9CC,MAAMC,KAAKC,SAAS,CAAC;gBACnBX;gBACAY,UAAUX;gBACVY,QAAQ;gBACRX;eACIC,OAAO;gBAAEA;YAAK,IAAI,CAAC;gBACvBC;;QAEJ;QACA,MAAMC,SAAS,MAAMC,SAASQ,IAAI,GAAGC,KAAK,CAAC,IAAO,CAAA,CAAC,CAAA;QACnD,IAAI,CAACT,SAASU,EAAE,EAAE;;YAChB,MAAM,IAAIC,eAAMZ,0BAAAA,OAAQa,KAAK,oBAAI;QACnC;QACA,OAAO;YACLC,IAAIC,OAAOf,OAAOc,EAAE;YACpBE,WAAWhB,OAAOgB,SAAS,GAAGD,OAAOf,OAAOgB,SAAS,IAAI;YACzDlB,MAAMiB,QAAOf,QAAAA,eAAAA,OAAOF,IAAI,YAAXE,eAAeF,gBAAfE,OAAuB;QACtC;IACF,GACA;QAACN;KAAK;AAEV;AAEA,eAAeF,wBAAuB"}

package/src/lib/hooks/use-firestore-collection.d.ts

@@ -0,0 +1,62 @@
+import { type DocumentData, type FirestoreError, type Query } from 'firebase/firestore';
+import { type DependencyList } from 'react';
+export type FirestoreCollectionStatus = 'loading' | 'success' | 'error';
+export interface UseFirestoreCollectionOptions {
+    idField?: string;
+    /**
+     * Confirm against the server when a document disappears from a NON-EMPTY
+     * result, instead of trusting the live snapshot (AGL-1196).
+     *
+     * OPT-IN, and only worth setting for a query whose `where` reads a MUTABLE
+     * field. Such a document can stop matching mid-session — a scope edit, an
+     * un/republish — leave the query target, and get cached as a `noDocument`
+     * tombstone at its own path, which is then served to every other reader of
+     * that path including single-document reads (AGL-827/929).
+     *
+     * A query with no predicate, or one keyed on `documentId()`, cannot produce
+     * this and must not pay for the extra read. Where the predicate can be
+     * dropped entirely, drop it — that removes the mechanism rather than
+     * repairing it after the fact (AGL-1190).
+     */
+    confirmDisappearances?: boolean;
+}
+export interface UseFirestoreCollectionResult<T> {
+    data: T[];
+    status: FirestoreCollectionStatus;
+    error: FirestoreError | undefined;
+    /**
+     * `data` came from the local cache and the server has not confirmed it
+     * (AGL-1066). See `ObservableStatus.fromCache` for why this matters and
+     * why it is the signal to reach for rather than `staleSession`.
+     */
+    fromCache: boolean;
+    /**
+     * The server has REFUSED this listen for longer than the retry budget, and
+     * no server snapshot has arrived since (AGL-1066).
+     *
+     * Kept after the flip rather than folded into `status`, because it says
+     * something `status` does not: WHY the listen is failing. `status:
+     * 'error'` covers every terminal error; this one counts `permission-denied`
+     * alone, so it cannot fire offline, and a single server snapshot clears it.
+     * A consumer asking "is what I am rendering cache-only because the session
+     * is refused" wants this; one asking "did the read fail at all" wants
+     * `status`.
+     */
+    serverDenied: boolean;
+}
+/**
+ * Collection-query counterpart to reactfire's `useFirestoreCollectionData`,
+ * but backed by a raw `onSnapshot` listener with its own retry/backoff
+ * instead of reactfire's cached Observable. That cache terminates forever on
+ * its first error — a transient `permission-denied` right after sign-in
+ * (before Firestore's own credential provider has attached the user's ID
+ * token) permanently breaks the query for the rest of the session, even
+ * across remounts. A fresh `onSnapshot` call each retry reopens a genuinely
+ * new listener, so it recovers once the token has propagated (AGL-216/217).
+ *
+ * `buildQuery` is re-invoked from `deps` the same way a `useEffect`/`useMemo`
+ * callback would be — pass the same primitive values (ids, uid, firestore)
+ * you'd put in a `useMemo` dependency array, not the `Query` object itself.
+ */
+export declare function useFirestoreCollection<T = DocumentData>(buildQuery: () => Query<DocumentData> | null | undefined, deps: DependencyList, options?: UseFirestoreCollectionOptions): UseFirestoreCollectionResult<T>;
+export default useFirestoreCollection;

package/src/lib/hooks/use-firestore-collection.js

@@ -0,0 +1,307 @@
+/**
+ * @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 { _ as _extends } from "@swc/helpers/_/_extends";
+import { getDocsFromServer, onSnapshot } from "firebase/firestore";
+import { useEffect, useRef, useState } from "react";
+import { CONFIRMABLE_LISTEN_OPTIONS } from "./helpers/listen-options.js";
+import { DENIAL_STREAK_TO_REPORT, denialLabelForQuery, reportFirestoreDenial, reportFirestoreServerRead, scheduleRefusedReopen, subscribeFirestoreSessionHeal } from "./firestore-denial-reporter.js";
+const RETRY_DELAY_MS = 400;
+const MAX_RETRIES = 5;
+/**
+ * Collection-query counterpart to reactfire's `useFirestoreCollectionData`,
+ * but backed by a raw `onSnapshot` listener with its own retry/backoff
+ * instead of reactfire's cached Observable. That cache terminates forever on
+ * its first error — a transient `permission-denied` right after sign-in
+ * (before Firestore's own credential provider has attached the user's ID
+ * token) permanently breaks the query for the rest of the session, even
+ * across remounts. A fresh `onSnapshot` call each retry reopens a genuinely
+ * new listener, so it recovers once the token has propagated (AGL-216/217).
+ *
+ * `buildQuery` is re-invoked from `deps` the same way a `useEffect`/`useMemo`
+ * callback would be — pass the same primitive values (ids, uid, firestore)
+ * you'd put in a `useMemo` dependency array, not the `Query` object itself.
+ */ export function useFirestoreCollection(buildQuery, deps, options = {}) {
+    const [data, setData] = useState([]);
+    const [status, setStatus] = useState('loading');
+    const [error, setError] = useState(undefined);
+    // Un-confirmed until a snapshot says otherwise: a hook that has not heard
+    // from the server yet must not read as server-confirmed.
+    const [fromCache, setFromCache] = useState(true);
+    const [serverDenied, setServerDenied] = useState(false);
+    const buildQueryRef = useRef(buildQuery);
+    buildQueryRef.current = buildQuery;
+    const idField = options.idField;
+    const confirmDisappearances = options.confirmDisappearances;
+    useEffect(()=>{
+        setStatus('loading');
+        setError(undefined);
+        // Clear on EVERY dep change, not only when the query goes null: when
+        // the scope moves between two live queries (org A → org B, host A →
+        // host B) the old rows would otherwise stay rendered until the new
+        // snapshot arrives — the org-switch "remnants" bug (AGL-591). Same
+        // hold-nothing-rather-than-show-the-wrong-org rule as useOrgHosts.
+        setData([]);
+        setFromCache(true);
+        setServerDenied(false);
+        const q = buildQueryRef.current();
+        if (!q) {
+            return;
+        }
+        let cancelled = false;
+        let unsubscribe = null;
+        let timer = null;
+        /** Cancels a pending reopen on the refused cadence (AGL-2944). */ let cancelRefusedReopen = null;
+        let attempt = 0;
+        /**
+     * Refusals since the last SERVER snapshot (AGL-1066).
+     *
+     * Deliberately not `attempt`: that one is reset by any snapshot,
+     * including a cached one, so under `persistentLocalCache` it never
+     * reaches its budget and can never report anything.
+     */ let deniedStreak = 0;
+        /** Epoch ms of the current streak's first refusal (AGL-1440). */ let deniedStreakStartedAt = 0;
+        let denialReported = false;
+        /**
+     * The retry budget is spent and the last thing the server did was refuse
+     * (AGL-1066).
+     *
+     * This is what makes `status: 'error'` STICK. Every reopened listen emits
+     * from the cache before it learns it is still refused, and an
+     * unconditional `setStatus('success')` in the success handler would hand
+     * the page back to `success` on that emission — so the surface would
+     * oscillate error → success → error at the retry cadence, which is worse
+     * to look at than either state. Only a snapshot the SERVER answered
+     * clears this, for the same reason it is the only thing that clears
+     * `deniedStreak`: a cached emission is not evidence about the server.
+     */ let terminal = false;
+        const denialLabel = denialLabelForQuery(q);
+        // Disappearance tracking (AGL-1196); inert unless opted in.
+        const seen = new Set();
+        const confirmedGone = new Set();
+        const emit = (docs, cached)=>{
+            // A server-answered emission is the one thing that ends the refusal,
+            // including the `getDocsFromServer` confirmation path below.
+            if (!cached) terminal = false;
+            if (!terminal) {
+                setStatus('success');
+                setError(undefined);
+            }
+            setFromCache(cached);
+            setData(docs.map((docSnap)=>{
+                const value = _extends({}, docSnap.data());
+                if (idField) value[idField] = docSnap.id;
+                return value;
+            }));
+        };
+        const subscribe = ()=>{
+            unsubscribe = onSnapshot(q, // Without this the cache→server confirmation is never delivered and
+            // `fromCache` latches true for the life of the listener, refusing
+            // every guarded save on the page (AGL-2486). See `listen-options.ts`.
+            CONFIRMABLE_LISTEN_OPTIONS, (snapshot)=>{
+                if (cancelled) return;
+                /**
+           * Only a SERVER-answered snapshot refunds the retry budget — the
+           * AGL-1066 flip, and the reason it took four commits to become
+           * safe.
+           *
+           * Under `persistentLocalCache` a reopened listen emits from the
+           * cache BEFORE it learns the server refused it. Refunding on that
+           * emission handed the budget back every cycle, so `attempt` never
+           * reached `MAX_RETRIES`, `status` could never become `'error'`, and
+           * a dead session looked exactly like a healthy one on every
+           * listener-backed page for as long as it stayed dead.
+           *
+           * Landing this alone would have been a regression, and the three
+           * things that made it one are now in place:
+           *
+           *  - the budget is 5 x 400ms, and the error branch used to stop
+           *    retrying for good, while the heal is an AGL-664 in-place
+           *    re-auth that takes as long as a human takes to type a
+           *    password. A resolved re-auth now broadcasts and this listener
+           *    reopens on it (`subscribeFirestoreSessionHeal` below), and a
+           *    refusal streak keeps a slow road back for a recovery nobody
+           *    announced (see the error branch);
+           *  - `status: 'error'` had to become STICKY, or the cached emission
+           *    that precedes each refusal would flip it straight back — see
+           *    `terminal` above;
+           *  - the surfaces that BLANK on `error` had to learn the
+           *    difference between "never had data" and "have data, the server
+           *    refused". They read `hasEmitted` now, so the besigner canvas
+           *    and the host setup Theme tab keep rendering across a refusal
+           *    instead of collapsing to "Not found".
+           *
+           * The withholding is keyed on a REFUSAL having happened, not on the
+           * emission being cached, and that is load-bearing: offline stays
+           * exactly as inert as it was. A lost network yields `unavailable`
+           * (when it yields an error callback at all), which never enters
+           * `deniedStreak`, so a cached emission still refunds the budget and
+           * an offline listener still never goes terminal. The cache exists
+           * for offline; this must not change what happens there.
+           */ // Only the SERVER answering is evidence the session can read.
+                if (!snapshot.metadata.fromCache) {
+                    attempt = 0;
+                    deniedStreak = 0;
+                    denialReported = false;
+                    setServerDenied(false);
+                    // Proof the session can read — stronger than any accumulated
+                    // denial, and what stops a scoped collaborator's by-design
+                    // denials from ever adding up to a re-auth prompt.
+                    reportFirestoreServerRead();
+                } else if (deniedStreak === 0) {
+                    // Cached, but nothing has been refused since the server last
+                    // answered — so this is not the AGL-1066 fault and the budget is
+                    // refunded exactly as it always was.
+                    attempt = 0;
+                }
+                if (confirmDisappearances) {
+                    const present = new Set(snapshot.docs.map((d)=>d.id));
+                    const vanished = [
+                        ...seen
+                    ].filter((id)=>!present.has(id) && !confirmedGone.has(id));
+                    if (vanished.length) {
+                        // A fresh (non-resumed) read ignores the resume token, returns
+                        // the true set and rewrites the cache, dropping any tombstone.
+                        getDocsFromServer(q).then((fresh)=>{
+                            if (cancelled) return;
+                            const freshIds = new Set(fresh.docs.map((d)=>d.id));
+                            // Only an absence the SERVER agrees with is real. One that
+                            // came back was a tombstone and must stay eligible to heal
+                            // if it vanishes again.
+                            vanished.forEach((id)=>{
+                                if (!freshIds.has(id)) confirmedGone.add(id);
+                            });
+                            freshIds.forEach((id)=>seen.add(id));
+                            // `getDocsFromServer` is server-confirmed by definition.
+                            emit(fresh.docs, false);
+                        }).catch(()=>{
+                            // Couldn't confirm: show the live result rather than an
+                            // error. A possibly-short list beats an empty one.
+                            if (!cancelled) emit(snapshot.docs, snapshot.metadata.fromCache);
+                        });
+                        return;
+                    }
+                    snapshot.docs.forEach((d)=>seen.add(d.id));
+                }
+                emit(snapshot.docs, snapshot.metadata.fromCache);
+            }, (err)=>{
+                if (cancelled) return;
+                unsubscribe == null ? void 0 : unsubscribe();
+                // Say so once per outage, and only for a refusal — a lost network
+                // produces no error callback at all, so this cannot fire offline.
+                if ((err == null ? void 0 : err.code) === 'permission-denied') {
+                    deniedStreak += 1;
+                    // When the streak began — the reference point that lets
+                    // `refusedRetryDelayMs` ask whether the session has read from
+                    // the server SINCE this listen started being refused (AGL-1440).
+                    if (deniedStreak === 1) deniedStreakStartedAt = Date.now();
+                    if (deniedStreak >= DENIAL_STREAK_TO_REPORT) {
+                        setServerDenied(true);
+                        if (!denialReported) {
+                            denialReported = true;
+                            reportFirestoreDenial(denialLabel);
+                        }
+                    }
+                }
+                if (attempt < MAX_RETRIES) {
+                    attempt += 1;
+                    if (deniedStreak > MAX_RETRIES) {
+                        cancelRefusedReopen = scheduleRefusedReopen(subscribe, deniedStreakStartedAt);
+                    } else {
+                        timer = setTimeout(subscribe, RETRY_DELAY_MS);
+                    }
+                } else {
+                    terminal = true;
+                    setStatus('error');
+                    setError(err);
+                    /**
+             * A refusal streak keeps a slow road back (AGL-1066).
+             *
+             * Before the flip this listener reopened forever, which is also
+             * what HEALED it — a token that attached late, an App Check
+             * hiccup, one of the AGL-1143 transient token-layer denials.
+             * None of those broadcast a heal, because none of them involved
+             * a re-auth the console asked for, so stopping here would leave
+             * every listen in the console terminal until the user reloaded.
+             * The status is corrected; the recovery is not taken away.
+             *
+             * Any OTHER terminal error still stops exactly as before — this
+             * is deliberately keyed on the refusal streak, not on `attempt`.
+             * How slow the road is depends on whether the refusal looks like
+             * the session or the ref (AGL-1440) and on how long it has
+             * lasted (AGL-2945), and a hidden tab waits to be looked at
+             * (AGL-2944) — see `scheduleRefusedReopen`.
+             */ if (deniedStreak > MAX_RETRIES) {
+                        cancelRefusedReopen = scheduleRefusedReopen(subscribe, deniedStreakStartedAt);
+                    }
+                }
+            });
+        };
+        subscribe();
+        /**
+     * The session came back — reopen NOW rather than on the next tick of a
+     * cadence tuned for a session that has not (AGL-1066).
+     *
+     * Gated on this listener actually being refused. A healthy listener has
+     * an open subscription and nothing to recover, so it must ignore the
+     * broadcast entirely: without this gate a heal would tear down and
+     * reopen every listen in the console at once, which is a listener storm
+     * dressed up as a fix.
+     *
+     * What is refunded is `attempt` — the retry BUDGET, which was spent on a
+     * fault that is now over. `deniedStreak` is deliberately left alone: it
+     * is evidence about the server, and only the server answering may clear
+     * it. So `serverDenied` stays true across the heal and goes false on the
+     * snapshot that actually proves the read works, and a heal that turns
+     * out to be wishful thinking falls straight back to the slow cadence
+     * instead of resuming a 400ms storm.
+     *
+     * `denialReported` IS reset: the outage ended here. If reads are still
+     * refused afterwards that is a new one, and it has to be able to raise
+     * the AGL-1063 banner again.
+     */ const unsubscribeHeal = subscribeFirestoreSessionHeal(()=>{
+            if (cancelled || deniedStreak === 0) return;
+            if (timer) {
+                clearTimeout(timer);
+                timer = null;
+            }
+            cancelRefusedReopen == null ? void 0 : cancelRefusedReopen();
+            cancelRefusedReopen = null;
+            unsubscribe == null ? void 0 : unsubscribe();
+            attempt = 0;
+            denialReported = false;
+            subscribe();
+        });
+        return ()=>{
+            cancelled = true;
+            unsubscribeHeal();
+            if (timer) clearTimeout(timer);
+            cancelRefusedReopen == null ? void 0 : cancelRefusedReopen();
+            unsubscribe == null ? void 0 : unsubscribe();
+        };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, deps);
+    return {
+        data,
+        status,
+        error,
+        fromCache,
+        serverDenied
+    };
+}
+export default useFirestoreCollection;
+
+//# sourceMappingURL=use-firestore-collection.js.map

package/src/lib/hooks/use-firestore-collection.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../../libs/tenant/feature/instance/src/lib/hooks/use-firestore-collection.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'use client'\n\nimport {\n  getDocsFromServer,\n  onSnapshot,\n  type DocumentData,\n  type FirestoreError,\n  type Query,\n  type QueryDocumentSnapshot,\n} from 'firebase/firestore'\nimport { useEffect, useRef, useState, type DependencyList } from 'react'\nimport { CONFIRMABLE_LISTEN_OPTIONS } from './helpers/listen-options'\nimport {\n  DENIAL_STREAK_TO_REPORT,\n  denialLabelForQuery,\n  reportFirestoreDenial,\n  reportFirestoreServerRead,\n  scheduleRefusedReopen,\n  subscribeFirestoreSessionHeal,\n} from './firestore-denial-reporter'\n\nconst RETRY_DELAY_MS = 400\nconst MAX_RETRIES = 5\n\n/*\n * The cadence once a refusal streak has outlived the retry budget lives in\n * `firestore-denial-reporter.ts` (`scheduleRefusedReopen`), shared by all\n * three listener hooks. It starts at 2s while the fault could be the whole\n * session and at 60s once another listener's server answer proves the\n * session reads and this refusal is about the ref (AGL-1440), then grows\n * with the streak's age to a five-minute ceiling (AGL-2945). A hidden tab\n * sets no timer (AGL-2944). The tab becoming visible, the window regaining\n * focus and a heal broadcast (`subscribeFirestoreSessionHeal`) all reopen\n * at once.\n */\n\nexport type FirestoreCollectionStatus = 'loading' | 'success' | 'error'\n\nexport interface UseFirestoreCollectionOptions {\n  idField?: string\n  /**\n   * Confirm against the server when a document disappears from a NON-EMPTY\n   * result, instead of trusting the live snapshot (AGL-1196).\n   *\n   * OPT-IN, and only worth setting for a query whose `where` reads a MUTABLE\n   * field. Such a document can stop matching mid-session — a scope edit, an\n   * un/republish — leave the query target, and get cached as a `noDocument`\n   * tombstone at its own path, which is then served to every other reader of\n   * that path including single-document reads (AGL-827/929).\n   *\n   * A query with no predicate, or one keyed on `documentId()`, cannot produce\n   * this and must not pay for the extra read. Where the predicate can be\n   * dropped entirely, drop it — that removes the mechanism rather than\n   * repairing it after the fact (AGL-1190).\n   */\n  confirmDisappearances?: boolean\n}\n\nexport interface UseFirestoreCollectionResult<T> {\n  data: T[]\n  status: FirestoreCollectionStatus\n  error: FirestoreError | undefined\n  /**\n   * `data` came from the local cache and the server has not confirmed it\n   * (AGL-1066). See `ObservableStatus.fromCache` for why this matters and\n   * why it is the signal to reach for rather than `staleSession`.\n   */\n  fromCache: boolean\n  /**\n   * The server has REFUSED this listen for longer than the retry budget, and\n   * no server snapshot has arrived since (AGL-1066).\n   *\n   * Kept after the flip rather than folded into `status`, because it says\n   * something `status` does not: WHY the listen is failing. `status:\n   * 'error'` covers every terminal error; this one counts `permission-denied`\n   * alone, so it cannot fire offline, and a single server snapshot clears it.\n   * A consumer asking \"is what I am rendering cache-only because the session\n   * is refused\" wants this; one asking \"did the read fail at all\" wants\n   * `status`.\n   */\n  serverDenied: boolean\n}\n\n/**\n * Collection-query counterpart to reactfire's `useFirestoreCollectionData`,\n * but backed by a raw `onSnapshot` listener with its own retry/backoff\n * instead of reactfire's cached Observable. That cache terminates forever on\n * its first error — a transient `permission-denied` right after sign-in\n * (before Firestore's own credential provider has attached the user's ID\n * token) permanently breaks the query for the rest of the session, even\n * across remounts. A fresh `onSnapshot` call each retry reopens a genuinely\n * new listener, so it recovers once the token has propagated (AGL-216/217).\n *\n * `buildQuery` is re-invoked from `deps` the same way a `useEffect`/`useMemo`\n * callback would be — pass the same primitive values (ids, uid, firestore)\n * you'd put in a `useMemo` dependency array, not the `Query` object itself.\n */\nexport function useFirestoreCollection<T = DocumentData>(\n  buildQuery: () => Query<DocumentData> | null | undefined,\n  deps: DependencyList,\n  options: UseFirestoreCollectionOptions = {},\n): UseFirestoreCollectionResult<T> {\n  const [data, setData] = useState<T[]>([])\n  const [status, setStatus] = useState<FirestoreCollectionStatus>('loading')\n  const [error, setError] = useState<FirestoreError | undefined>(undefined)\n  // Un-confirmed until a snapshot says otherwise: a hook that has not heard\n  // from the server yet must not read as server-confirmed.\n  const [fromCache, setFromCache] = useState(true)\n  const [serverDenied, setServerDenied] = useState(false)\n  const buildQueryRef = useRef(buildQuery)\n  buildQueryRef.current = buildQuery\n  const idField = options.idField\n  const confirmDisappearances = options.confirmDisappearances\n\n  useEffect(() => {\n    setStatus('loading')\n    setError(undefined)\n    // Clear on EVERY dep change, not only when the query goes null: when\n    // the scope moves between two live queries (org A → org B, host A →\n    // host B) the old rows would otherwise stay rendered until the new\n    // snapshot arrives — the org-switch \"remnants\" bug (AGL-591). Same\n    // hold-nothing-rather-than-show-the-wrong-org rule as useOrgHosts.\n    setData([])\n    setFromCache(true)\n    setServerDenied(false)\n\n    const q = buildQueryRef.current()\n    if (!q) {\n      return\n    }\n\n    let cancelled = false\n    let unsubscribe: (() => void) | null = null\n    let timer: ReturnType<typeof setTimeout> | null = null\n    /** Cancels a pending reopen on the refused cadence (AGL-2944). */\n    let cancelRefusedReopen: (() => void) | null = null\n    let attempt = 0\n    /**\n     * Refusals since the last SERVER snapshot (AGL-1066).\n     *\n     * Deliberately not `attempt`: that one is reset by any snapshot,\n     * including a cached one, so under `persistentLocalCache` it never\n     * reaches its budget and can never report anything.\n     */\n    let deniedStreak = 0\n    /** Epoch ms of the current streak's first refusal (AGL-1440). */\n    let deniedStreakStartedAt = 0\n    let denialReported = false\n    /**\n     * The retry budget is spent and the last thing the server did was refuse\n     * (AGL-1066).\n     *\n     * This is what makes `status: 'error'` STICK. Every reopened listen emits\n     * from the cache before it learns it is still refused, and an\n     * unconditional `setStatus('success')` in the success handler would hand\n     * the page back to `success` on that emission — so the surface would\n     * oscillate error → success → error at the retry cadence, which is worse\n     * to look at than either state. Only a snapshot the SERVER answered\n     * clears this, for the same reason it is the only thing that clears\n     * `deniedStreak`: a cached emission is not evidence about the server.\n     */\n    let terminal = false\n    const denialLabel = denialLabelForQuery(q)\n    // Disappearance tracking (AGL-1196); inert unless opted in.\n    const seen = new Set<string>()\n    const confirmedGone = new Set<string>()\n\n    const emit = (\n      docs: QueryDocumentSnapshot<DocumentData>[],\n      cached: boolean,\n    ) => {\n      // A server-answered emission is the one thing that ends the refusal,\n      // including the `getDocsFromServer` confirmation path below.\n      if (!cached) terminal = false\n      if (!terminal) {\n        setStatus('success')\n        setError(undefined)\n      }\n      setFromCache(cached)\n      setData(\n        docs.map((docSnap) => {\n          const value = { ...docSnap.data() } as Record<string, unknown>\n          if (idField) value[idField] = docSnap.id\n          return value as T\n        }),\n      )\n    }\n\n    const subscribe = () => {\n      unsubscribe = onSnapshot(\n        q,\n        // Without this the cache→server confirmation is never delivered and\n        // `fromCache` latches true for the life of the listener, refusing\n        // every guarded save on the page (AGL-2486). See `listen-options.ts`.\n        CONFIRMABLE_LISTEN_OPTIONS,\n        (snapshot) => {\n          if (cancelled) return\n          /**\n           * Only a SERVER-answered snapshot refunds the retry budget — the\n           * AGL-1066 flip, and the reason it took four commits to become\n           * safe.\n           *\n           * Under `persistentLocalCache` a reopened listen emits from the\n           * cache BEFORE it learns the server refused it. Refunding on that\n           * emission handed the budget back every cycle, so `attempt` never\n           * reached `MAX_RETRIES`, `status` could never become `'error'`, and\n           * a dead session looked exactly like a healthy one on every\n           * listener-backed page for as long as it stayed dead.\n           *\n           * Landing this alone would have been a regression, and the three\n           * things that made it one are now in place:\n           *\n           *  - the budget is 5 x 400ms, and the error branch used to stop\n           *    retrying for good, while the heal is an AGL-664 in-place\n           *    re-auth that takes as long as a human takes to type a\n           *    password. A resolved re-auth now broadcasts and this listener\n           *    reopens on it (`subscribeFirestoreSessionHeal` below), and a\n           *    refusal streak keeps a slow road back for a recovery nobody\n           *    announced (see the error branch);\n           *  - `status: 'error'` had to become STICKY, or the cached emission\n           *    that precedes each refusal would flip it straight back — see\n           *    `terminal` above;\n           *  - the surfaces that BLANK on `error` had to learn the\n           *    difference between \"never had data\" and \"have data, the server\n           *    refused\". They read `hasEmitted` now, so the besigner canvas\n           *    and the host setup Theme tab keep rendering across a refusal\n           *    instead of collapsing to \"Not found\".\n           *\n           * The withholding is keyed on a REFUSAL having happened, not on the\n           * emission being cached, and that is load-bearing: offline stays\n           * exactly as inert as it was. A lost network yields `unavailable`\n           * (when it yields an error callback at all), which never enters\n           * `deniedStreak`, so a cached emission still refunds the budget and\n           * an offline listener still never goes terminal. The cache exists\n           * for offline; this must not change what happens there.\n           */\n          // Only the SERVER answering is evidence the session can read.\n          if (!snapshot.metadata.fromCache) {\n            attempt = 0\n            deniedStreak = 0\n            denialReported = false\n            setServerDenied(false)\n            // Proof the session can read — stronger than any accumulated\n            // denial, and what stops a scoped collaborator's by-design\n            // denials from ever adding up to a re-auth prompt.\n            reportFirestoreServerRead()\n          } else if (deniedStreak === 0) {\n            // Cached, but nothing has been refused since the server last\n            // answered — so this is not the AGL-1066 fault and the budget is\n            // refunded exactly as it always was.\n            attempt = 0\n          }\n\n          if (confirmDisappearances) {\n            const present = new Set(snapshot.docs.map((d) => d.id))\n            const vanished = [...seen].filter(\n              (id) => !present.has(id) && !confirmedGone.has(id),\n            )\n            if (vanished.length) {\n              // A fresh (non-resumed) read ignores the resume token, returns\n              // the true set and rewrites the cache, dropping any tombstone.\n              getDocsFromServer(q)\n                .then((fresh) => {\n                  if (cancelled) return\n                  const freshIds = new Set(fresh.docs.map((d) => d.id))\n                  // Only an absence the SERVER agrees with is real. One that\n                  // came back was a tombstone and must stay eligible to heal\n                  // if it vanishes again.\n                  vanished.forEach((id) => {\n                    if (!freshIds.has(id)) confirmedGone.add(id)\n                  })\n                  freshIds.forEach((id) => seen.add(id))\n                  // `getDocsFromServer` is server-confirmed by definition.\n                  emit(fresh.docs, false)\n                })\n                .catch(() => {\n                  // Couldn't confirm: show the live result rather than an\n                  // error. A possibly-short list beats an empty one.\n                  if (!cancelled) emit(snapshot.docs, snapshot.metadata.fromCache)\n                })\n              return\n            }\n            snapshot.docs.forEach((d) => seen.add(d.id))\n          }\n\n          emit(snapshot.docs, snapshot.metadata.fromCache)\n        },\n        (err) => {\n          if (cancelled) return\n          unsubscribe?.()\n          // Say so once per outage, and only for a refusal — a lost network\n          // produces no error callback at all, so this cannot fire offline.\n          if (err?.code === 'permission-denied') {\n            deniedStreak += 1\n            // When the streak began — the reference point that lets\n            // `refusedRetryDelayMs` ask whether the session has read from\n            // the server SINCE this listen started being refused (AGL-1440).\n            if (deniedStreak === 1) deniedStreakStartedAt = Date.now()\n            if (deniedStreak >= DENIAL_STREAK_TO_REPORT) {\n              setServerDenied(true)\n              if (!denialReported) {\n                denialReported = true\n                reportFirestoreDenial(denialLabel)\n              }\n            }\n          }\n          if (attempt < MAX_RETRIES) {\n            attempt += 1\n            if (deniedStreak > MAX_RETRIES) {\n              cancelRefusedReopen = scheduleRefusedReopen(\n                subscribe,\n                deniedStreakStartedAt,\n              )\n            } else {\n              timer = setTimeout(subscribe, RETRY_DELAY_MS)\n            }\n          } else {\n            terminal = true\n            setStatus('error')\n            setError(err)\n            /**\n             * A refusal streak keeps a slow road back (AGL-1066).\n             *\n             * Before the flip this listener reopened forever, which is also\n             * what HEALED it — a token that attached late, an App Check\n             * hiccup, one of the AGL-1143 transient token-layer denials.\n             * None of those broadcast a heal, because none of them involved\n             * a re-auth the console asked for, so stopping here would leave\n             * every listen in the console terminal until the user reloaded.\n             * The status is corrected; the recovery is not taken away.\n             *\n             * Any OTHER terminal error still stops exactly as before — this\n             * is deliberately keyed on the refusal streak, not on `attempt`.\n             * How slow the road is depends on whether the refusal looks like\n             * the session or the ref (AGL-1440) and on how long it has\n             * lasted (AGL-2945), and a hidden tab waits to be looked at\n             * (AGL-2944) — see `scheduleRefusedReopen`.\n             */\n            if (deniedStreak > MAX_RETRIES) {\n              cancelRefusedReopen = scheduleRefusedReopen(\n                subscribe,\n                deniedStreakStartedAt,\n              )\n            }\n          }\n        },\n      )\n    }\n    subscribe()\n\n    /**\n     * The session came back — reopen NOW rather than on the next tick of a\n     * cadence tuned for a session that has not (AGL-1066).\n     *\n     * Gated on this listener actually being refused. A healthy listener has\n     * an open subscription and nothing to recover, so it must ignore the\n     * broadcast entirely: without this gate a heal would tear down and\n     * reopen every listen in the console at once, which is a listener storm\n     * dressed up as a fix.\n     *\n     * What is refunded is `attempt` — the retry BUDGET, which was spent on a\n     * fault that is now over. `deniedStreak` is deliberately left alone: it\n     * is evidence about the server, and only the server answering may clear\n     * it. So `serverDenied` stays true across the heal and goes false on the\n     * snapshot that actually proves the read works, and a heal that turns\n     * out to be wishful thinking falls straight back to the slow cadence\n     * instead of resuming a 400ms storm.\n     *\n     * `denialReported` IS reset: the outage ended here. If reads are still\n     * refused afterwards that is a new one, and it has to be able to raise\n     * the AGL-1063 banner again.\n     */\n    const unsubscribeHeal = subscribeFirestoreSessionHeal(() => {\n      if (cancelled || deniedStreak === 0) return\n      if (timer) {\n        clearTimeout(timer)\n        timer = null\n      }\n      cancelRefusedReopen?.()\n      cancelRefusedReopen = null\n      unsubscribe?.()\n      attempt = 0\n      denialReported = false\n      subscribe()\n    })\n\n    return () => {\n      cancelled = true\n      unsubscribeHeal()\n      if (timer) clearTimeout(timer)\n      cancelRefusedReopen?.()\n      unsubscribe?.()\n    }\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n  }, deps)\n\n  return { data, status, error, fromCache, serverDenied }\n}\n\nexport default useFirestoreCollection\n"],"names":["getDocsFromServer","onSnapshot","useEffect","useRef","useState","CONFIRMABLE_LISTEN_OPTIONS","DENIAL_STREAK_TO_REPORT","denialLabelForQuery","reportFirestoreDenial","reportFirestoreServerRead","scheduleRefusedReopen","subscribeFirestoreSessionHeal","RETRY_DELAY_MS","MAX_RETRIES","useFirestoreCollection","buildQuery","deps","options","data","setData","status","setStatus","error","setError","undefined","fromCache","setFromCache","serverDenied","setServerDenied","buildQueryRef","current","idField","confirmDisappearances","q","cancelled","unsubscribe","timer","cancelRefusedReopen","attempt","deniedStreak","deniedStreakStartedAt","denialReported","terminal","denialLabel","seen","Set","confirmedGone","emit","docs","cached","map","docSnap","value","id","subscribe","snapshot","metadata","present","d","vanished","filter","has","length","then","fresh","freshIds","forEach","add","catch","err","code","Date","now","setTimeout","unsubscribeHeal","clearTimeout"],"mappings":"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"}