@aglyn/tenant-feature-instance 1.0.0-beta.275 → 1.0.0-beta.282

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aglyn/tenant-feature-instance",
-  "version": "1.0.0-beta.275",
+  "version": "1.0.0-beta.282",
   "license": "Apache-2.0",
   "homepage": "https://aglyn.com",
   "repository": {
@@ -25,14 +25,15 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@aglyn/aglyn": "1.0.0-beta.275",
-    "@aglyn/shared-data-enums": "1.0.0-beta.275",
-    "@aglyn/shared-ui-jsx": "1.0.0-beta.275",
-    "@aglyn/shared-util-email": "1.0.0-beta.275",
-    "@aglyn/shared-util-http": "1.0.0-beta.275",
-    "@aglyn/shared-util-timestamp": "1.0.0-beta.275",
+    "@aglyn/aglyn": "1.0.0-beta.282",
+    "@aglyn/shared-data-enums": "1.0.0-beta.282",
+    "@aglyn/shared-ui-jsx": "1.0.0-beta.282",
+    "@aglyn/shared-util-email": "1.0.0-beta.282",
+    "@aglyn/shared-util-http": "1.0.0-beta.282",
+    "@aglyn/shared-util-timestamp": "1.0.0-beta.282",
     "@swc/helpers": "0.5.23",
-    "lodash-es": "^4.18.1"
+    "lodash-es": "^4.18.1",
+    "mobx": "^7.0.5"
   },
   "peerDependencies": {
     "@mui/material": "^9.3.1",

package/src/lib/hooks/use-confirmed-doc.d.ts

@@ -0,0 +1,73 @@
+import { type Firestore } from 'firebase/firestore';
+export interface ConfirmedDocState<T> {
+    /** The doc's data (with `$id`), or undefined while loading / when absent. */
+    data: T | undefined;
+    /**
+     * True once an answer worth acting on has arrived: any snapshot that has
+     * data, or a MISS the server itself has confirmed. Consumers must not
+     * 404, fall back to a default, or otherwise treat "no doc" as real until
+     * this is true.
+     */
+    ready: boolean;
+    /** True only when retries were exhausted — offer a retry, never a 404. */
+    error: boolean;
+    /**
+     * `data` is being served from the local cache and the server has not
+     * confirmed it (AGL-1066). Never a reason to withhold the value — only a
+     * reason not to let it decide something irreversible.
+     */
+    fromCache: boolean;
+}
+export interface UseConfirmedDocOptions {
+    /**
+     * Also confirm a cache-served hit that EXISTS, not just a miss (AGL-1066).
+     *
+     * The base contract trusts any snapshot that exists, whatever its source.
+     * That is right for ordinary content — the value was legitimately the
+     * user's a moment ago, and blanking it costs more than it buys. It is NOT
+     * right for the entitlement doc: `orgs/{orgId}` is the only plan source
+     * (AGL-238), and a cached copy from before a plan change renders the org
+     * at the wrong tier for as long as the session stays stale. AGL-887 closed
+     * the tombstone direction of exactly this fault (a Business workspace
+     * rendering as Free); this closes the stale-EXISTS direction.
+     *
+     * Opt-in because it can cost one extra server read, and only when the
+     * listener has actually failed to reach the server — see the deferral in
+     * the implementation. Enable it for entitlement-shaped documents only.
+     */
+    confirmCachedHit?: boolean;
+}
+/** Test seam — the in-flight map is module scope by design. */
+export declare function resetConfirmedDocSharing(): void;
+/**
+ * A doc listen that never presents an unconfirmed miss (AGL-928).
+ *
+ * This is the shared form of the contract four consumers learned the hard
+ * way (AGL-813/827/875/886/887): the console's multi-tab IndexedDB
+ * persistence can serve a stale `noDocument` tombstone for a LIVE doc, and
+ * a resumed listen never re-sends the correction — so `exists() === false`
+ * from cache looks confirmed while being wrong. Symptoms ranged from valid
+ * hosts 404ing to a Business workspace rendering as Free.
+ *
+ * Contract implemented here:
+ * - Subscribe with a raw `onSnapshot` + exponential-backoff resubscribe:
+ *   right after sign-in (and on cold loads behind App Check) the first
+ *   listen can sit in transient `permission-denied` before the ID token
+ *   attaches (AGL-216); reactfire's cached Observable would replay that
+ *   error forever.
+ * - A snapshot that EXISTS is trusted immediately, whatever its source.
+ * - A snapshot that is MISSING and came from cache is confirmed via
+ *   `getDocFromServer` before it is believed; a failed confirm leaves
+ *   `ready` false rather than lying.
+ * - Exhausted retries set `error` (and `ready`) so consumers can offer
+ *   "try again" — never a false 404 or a fallback default.
+ *
+ * For QUERY listens the same contract lives in `useOrgHosts` (empty →
+ * `getDocsFromServer` confirm); extract it the same way if a third query
+ * consumer appears.
+ *
+ * @param segments Doc path segments (`['orgs', orgId]`), or null to idle
+ *   (state resets while null, matching "clear on scope change").
+ */
+export declare function useConfirmedDoc<T extends Record<string, unknown>>(firestore: Firestore, segments: readonly [string, ...string[]] | null, options?: UseConfirmedDocOptions): ConfirmedDocState<T>;
+export default useConfirmedDoc;

package/src/lib/hooks/use-confirmed-doc.js

@@ -0,0 +1,204 @@
+/**
+ * @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 { doc, getDocFromServer, onSnapshot } from "firebase/firestore";
+import { useEffect, useState } from "react";
+const RETRY_DELAY_MS = 400;
+const MAX_RETRIES = 8;
+const MAX_RETRY_DELAY_MS = 15000;
+/**
+ * How long a cached hit is allowed to stand before it is confirmed.
+ *
+ * Not zero, and this is the whole reason the option is affordable: on a
+ * healthy load the first snapshot is routinely from cache and the server
+ * snapshot follows within milliseconds. Confirming immediately would bill an
+ * extra read on every mount for every user; waiting means the confirm fires
+ * only when the server genuinely did not answer.
+ */ const CONFIRM_CACHED_HIT_DELAY_MS = 1500;
+/**
+ * Confirms in flight, keyed by document path (AGL-1440).
+ *
+ * `useCurrentOrg` is a plain hook, not a context, and the console chrome mounts
+ * it seven-plus times per page — user menu, org switcher, branding, and three
+ * separate paths through `ConsolePluginsGate`. The `onSnapshot`s are nearly
+ * free, because the SDK serves identical listens off ONE target; the confirms
+ * are not. Each instance scheduled its own `getDocFromServer`, so a console
+ * page load billed seven server reads of `orgs/{orgId}` to answer one question.
+ *
+ * Sharing the PROMISE, rather than suppressing the duplicates, is what keeps
+ * this behaviour-preserving: every instance still resolves from a real server
+ * snapshot and still calls `deliver(..., fromCache: false)`, so none of them is
+ * left displaying a value flagged unconfirmed. Suppressing instead would leave
+ * the six quiet instances on `fromCache: true` forever, which is a state
+ * consumers are told means "do not let this decide anything irreversible".
+ *
+ * The entry is dropped as soon as it settles, so this is a burst collapser and
+ * nothing more: a mount two seconds later asks the server again, exactly as it
+ * does today. NOTHING about the entitlement is cached — this shares one READ
+ * of the org document; every consumer evaluates the plan off it as before.
+ */ const confirmsInFlight = new Map();
+/** The server's copy of `ref`, shared with any confirm already in flight. */ function sharedConfirm(pathKey, ref) {
+    const existing = confirmsInFlight.get(pathKey);
+    if (existing) return existing;
+    const pending = getDocFromServer(ref).finally(()=>{
+        confirmsInFlight.delete(pathKey);
+    });
+    confirmsInFlight.set(pathKey, pending);
+    return pending;
+}
+/** Test seam — the in-flight map is module scope by design. */ export function resetConfirmedDocSharing() {
+    confirmsInFlight.clear();
+}
+/**
+ * A doc listen that never presents an unconfirmed miss (AGL-928).
+ *
+ * This is the shared form of the contract four consumers learned the hard
+ * way (AGL-813/827/875/886/887): the console's multi-tab IndexedDB
+ * persistence can serve a stale `noDocument` tombstone for a LIVE doc, and
+ * a resumed listen never re-sends the correction — so `exists() === false`
+ * from cache looks confirmed while being wrong. Symptoms ranged from valid
+ * hosts 404ing to a Business workspace rendering as Free.
+ *
+ * Contract implemented here:
+ * - Subscribe with a raw `onSnapshot` + exponential-backoff resubscribe:
+ *   right after sign-in (and on cold loads behind App Check) the first
+ *   listen can sit in transient `permission-denied` before the ID token
+ *   attaches (AGL-216); reactfire's cached Observable would replay that
+ *   error forever.
+ * - A snapshot that EXISTS is trusted immediately, whatever its source.
+ * - A snapshot that is MISSING and came from cache is confirmed via
+ *   `getDocFromServer` before it is believed; a failed confirm leaves
+ *   `ready` false rather than lying.
+ * - Exhausted retries set `error` (and `ready`) so consumers can offer
+ *   "try again" — never a false 404 or a fallback default.
+ *
+ * For QUERY listens the same contract lives in `useOrgHosts` (empty →
+ * `getDocsFromServer` confirm); extract it the same way if a third query
+ * consumer appears.
+ *
+ * @param segments Doc path segments (`['orgs', orgId]`), or null to idle
+ *   (state resets while null, matching "clear on scope change").
+ */ export function useConfirmedDoc(firestore, segments, options = {}) {
+    const [state, setState] = useState({
+        data: undefined,
+        ready: false,
+        error: false,
+        fromCache: true
+    });
+    // Effect key: a new path must tear down and restart the listen.
+    const pathKey = segments ? segments.join('/') : null;
+    const confirmCachedHit = options.confirmCachedHit;
+    useEffect(()=>{
+        setState({
+            data: undefined,
+            ready: false,
+            error: false,
+            fromCache: true
+        });
+        if (!pathKey) return;
+        let cancelled = false;
+        let unsubscribe = null;
+        let timer = null;
+        let attempt = 0;
+        // One confirm per mount, and never once the server has answered.
+        let confirmTimer = null;
+        let confirmRequested = false;
+        const ref = doc(firestore, pathKey);
+        const deliver = (exists, id, payload, fromCache)=>setState({
+                data: exists ? _extends({
+                    $id: id
+                }, payload) : undefined,
+                ready: true,
+                error: false,
+                fromCache
+            });
+        const subscribe = ()=>{
+            unsubscribe = onSnapshot(ref, (snapshot)=>{
+                if (cancelled) return;
+                attempt = 0;
+                const fromCache = snapshot.metadata.fromCache;
+                if (!fromCache && confirmTimer) {
+                    // The server answered on its own; nothing left to confirm.
+                    clearTimeout(confirmTimer);
+                    confirmTimer = null;
+                }
+                if (!snapshot.exists() && fromCache) {
+                    // Unconfirmed miss: ask the server before believing it. On
+                    // failure stay un-ready — the listener remains subscribed and
+                    // the next (server) snapshot resolves it.
+                    void sharedConfirm(pathKey, ref).then((server)=>{
+                        if (cancelled) return;
+                        deliver(server.exists(), server.id, server.data(), false);
+                    }).catch(()=>undefined);
+                    return;
+                }
+                deliver(snapshot.exists(), snapshot.id, snapshot.data(), fromCache);
+                /**
+           * Unconfirmed HIT (AGL-1066), for entitlement-shaped docs only.
+           *
+           * The value is already delivered above and stays on screen
+           * whatever happens here — this never blanks the page and never
+           * holds `ready` false, because a transient blip must not become a
+           * wrong tier OR a 404. It only replaces a cached answer with the
+           * server's when the server can be reached.
+           */ if (confirmCachedHit && fromCache && snapshot.exists() && !confirmRequested && !confirmTimer) {
+                    confirmTimer = setTimeout(()=>{
+                        confirmTimer = null;
+                        confirmRequested = true;
+                        void sharedConfirm(pathKey, ref).then((server)=>{
+                            if (cancelled) return;
+                            deliver(server.exists(), server.id, server.data(), false);
+                        })// Could not reach the server: keep showing the cached value,
+                        // still flagged `fromCache`. Refusing to answer would be the
+                        // stale-`ready` false-404 this hook exists to prevent.
+                        .catch(()=>undefined);
+                    }, CONFIRM_CACHED_HIT_DELAY_MS);
+                }
+            }, ()=>{
+                if (cancelled) return;
+                unsubscribe == null ? void 0 : unsubscribe();
+                if (attempt < MAX_RETRIES) {
+                    const delay = Math.min(RETRY_DELAY_MS * 2 ** attempt, MAX_RETRY_DELAY_MS);
+                    attempt += 1;
+                    timer = setTimeout(subscribe, delay);
+                } else {
+                    setState({
+                        data: undefined,
+                        ready: true,
+                        error: true,
+                        fromCache: true
+                    });
+                }
+            });
+        };
+        subscribe();
+        return ()=>{
+            cancelled = true;
+            if (timer) clearTimeout(timer);
+            if (confirmTimer) clearTimeout(confirmTimer);
+            unsubscribe == null ? void 0 : unsubscribe();
+        };
+    }, [
+        firestore,
+        pathKey,
+        confirmCachedHit
+    ]);
+    return state;
+}
+export default useConfirmedDoc;
+
+//# sourceMappingURL=use-confirmed-doc.js.map

package/src/lib/hooks/use-confirmed-doc.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../../libs/tenant/feature/instance/src/lib/hooks/use-confirmed-doc.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  doc,\n  getDocFromServer,\n  onSnapshot,\n  type DocumentData,\n  type DocumentReference,\n  type DocumentSnapshot,\n  type Firestore,\n} from 'firebase/firestore'\nimport { useEffect, useState } from 'react'\n\nconst RETRY_DELAY_MS = 400\nconst MAX_RETRIES = 8\nconst MAX_RETRY_DELAY_MS = 15_000\n\nexport interface ConfirmedDocState<T> {\n  /** The doc's data (with `$id`), or undefined while loading / when absent. */\n  data: T | undefined\n  /**\n   * True once an answer worth acting on has arrived: any snapshot that has\n   * data, or a MISS the server itself has confirmed. Consumers must not\n   * 404, fall back to a default, or otherwise treat \"no doc\" as real until\n   * this is true.\n   */\n  ready: boolean\n  /** True only when retries were exhausted — offer a retry, never a 404. */\n  error: boolean\n  /**\n   * `data` is being served from the local cache and the server has not\n   * confirmed it (AGL-1066). Never a reason to withhold the value — only a\n   * reason not to let it decide something irreversible.\n   */\n  fromCache: boolean\n}\n\nexport interface UseConfirmedDocOptions {\n  /**\n   * Also confirm a cache-served hit that EXISTS, not just a miss (AGL-1066).\n   *\n   * The base contract trusts any snapshot that exists, whatever its source.\n   * That is right for ordinary content — the value was legitimately the\n   * user's a moment ago, and blanking it costs more than it buys. It is NOT\n   * right for the entitlement doc: `orgs/{orgId}` is the only plan source\n   * (AGL-238), and a cached copy from before a plan change renders the org\n   * at the wrong tier for as long as the session stays stale. AGL-887 closed\n   * the tombstone direction of exactly this fault (a Business workspace\n   * rendering as Free); this closes the stale-EXISTS direction.\n   *\n   * Opt-in because it can cost one extra server read, and only when the\n   * listener has actually failed to reach the server — see the deferral in\n   * the implementation. Enable it for entitlement-shaped documents only.\n   */\n  confirmCachedHit?: boolean\n}\n\n/**\n * How long a cached hit is allowed to stand before it is confirmed.\n *\n * Not zero, and this is the whole reason the option is affordable: on a\n * healthy load the first snapshot is routinely from cache and the server\n * snapshot follows within milliseconds. Confirming immediately would bill an\n * extra read on every mount for every user; waiting means the confirm fires\n * only when the server genuinely did not answer.\n */\nconst CONFIRM_CACHED_HIT_DELAY_MS = 1_500\n\n/**\n * Confirms in flight, keyed by document path (AGL-1440).\n *\n * `useCurrentOrg` is a plain hook, not a context, and the console chrome mounts\n * it seven-plus times per page — user menu, org switcher, branding, and three\n * separate paths through `ConsolePluginsGate`. The `onSnapshot`s are nearly\n * free, because the SDK serves identical listens off ONE target; the confirms\n * are not. Each instance scheduled its own `getDocFromServer`, so a console\n * page load billed seven server reads of `orgs/{orgId}` to answer one question.\n *\n * Sharing the PROMISE, rather than suppressing the duplicates, is what keeps\n * this behaviour-preserving: every instance still resolves from a real server\n * snapshot and still calls `deliver(..., fromCache: false)`, so none of them is\n * left displaying a value flagged unconfirmed. Suppressing instead would leave\n * the six quiet instances on `fromCache: true` forever, which is a state\n * consumers are told means \"do not let this decide anything irreversible\".\n *\n * The entry is dropped as soon as it settles, so this is a burst collapser and\n * nothing more: a mount two seconds later asks the server again, exactly as it\n * does today. NOTHING about the entitlement is cached — this shares one READ\n * of the org document; every consumer evaluates the plan off it as before.\n */\nconst confirmsInFlight = new Map<\n  string,\n  Promise<DocumentSnapshot<DocumentData>>\n>()\n\n/** The server's copy of `ref`, shared with any confirm already in flight. */\nfunction sharedConfirm(\n  pathKey: string,\n  ref: DocumentReference,\n): Promise<DocumentSnapshot<DocumentData>> {\n  const existing = confirmsInFlight.get(pathKey)\n  if (existing) return existing\n  const pending = getDocFromServer(ref).finally(() => {\n    confirmsInFlight.delete(pathKey)\n  })\n  confirmsInFlight.set(pathKey, pending)\n  return pending\n}\n\n/** Test seam — the in-flight map is module scope by design. */\nexport function resetConfirmedDocSharing(): void {\n  confirmsInFlight.clear()\n}\n\n/**\n * A doc listen that never presents an unconfirmed miss (AGL-928).\n *\n * This is the shared form of the contract four consumers learned the hard\n * way (AGL-813/827/875/886/887): the console's multi-tab IndexedDB\n * persistence can serve a stale `noDocument` tombstone for a LIVE doc, and\n * a resumed listen never re-sends the correction — so `exists() === false`\n * from cache looks confirmed while being wrong. Symptoms ranged from valid\n * hosts 404ing to a Business workspace rendering as Free.\n *\n * Contract implemented here:\n * - Subscribe with a raw `onSnapshot` + exponential-backoff resubscribe:\n *   right after sign-in (and on cold loads behind App Check) the first\n *   listen can sit in transient `permission-denied` before the ID token\n *   attaches (AGL-216); reactfire's cached Observable would replay that\n *   error forever.\n * - A snapshot that EXISTS is trusted immediately, whatever its source.\n * - A snapshot that is MISSING and came from cache is confirmed via\n *   `getDocFromServer` before it is believed; a failed confirm leaves\n *   `ready` false rather than lying.\n * - Exhausted retries set `error` (and `ready`) so consumers can offer\n *   \"try again\" — never a false 404 or a fallback default.\n *\n * For QUERY listens the same contract lives in `useOrgHosts` (empty →\n * `getDocsFromServer` confirm); extract it the same way if a third query\n * consumer appears.\n *\n * @param segments Doc path segments (`['orgs', orgId]`), or null to idle\n *   (state resets while null, matching \"clear on scope change\").\n */\nexport function useConfirmedDoc<T extends Record<string, unknown>>(\n  firestore: Firestore,\n  segments: readonly [string, ...string[]] | null,\n  options: UseConfirmedDocOptions = {},\n): ConfirmedDocState<T> {\n  const [state, setState] = useState<ConfirmedDocState<T>>({\n    data: undefined,\n    ready: false,\n    error: false,\n    fromCache: true,\n  })\n  // Effect key: a new path must tear down and restart the listen.\n  const pathKey = segments ? segments.join('/') : null\n  const confirmCachedHit = options.confirmCachedHit\n\n  useEffect(() => {\n    setState({ data: undefined, ready: false, error: false, fromCache: true })\n    if (!pathKey) return\n\n    let cancelled = false\n    let unsubscribe: (() => void) | null = null\n    let timer: ReturnType<typeof setTimeout> | null = null\n    let attempt = 0\n    // One confirm per mount, and never once the server has answered.\n    let confirmTimer: ReturnType<typeof setTimeout> | null = null\n    let confirmRequested = false\n    const ref = doc(firestore, pathKey)\n\n    const deliver = (\n      exists: boolean,\n      id: string,\n      payload: Record<string, unknown> | undefined,\n      fromCache: boolean,\n    ) =>\n      setState({\n        data: exists ? ({ $id: id, ...payload } as unknown as T) : undefined,\n        ready: true,\n        error: false,\n        fromCache,\n      })\n\n    const subscribe = () => {\n      unsubscribe = onSnapshot(\n        ref,\n        (snapshot) => {\n          if (cancelled) return\n          attempt = 0\n          const fromCache = snapshot.metadata.fromCache\n          if (!fromCache && confirmTimer) {\n            // The server answered on its own; nothing left to confirm.\n            clearTimeout(confirmTimer)\n            confirmTimer = null\n          }\n          if (!snapshot.exists() && fromCache) {\n            // Unconfirmed miss: ask the server before believing it. On\n            // failure stay un-ready — the listener remains subscribed and\n            // the next (server) snapshot resolves it.\n            void sharedConfirm(pathKey, ref)\n              .then((server) => {\n                if (cancelled) return\n                deliver(server.exists(), server.id, server.data(), false)\n              })\n              .catch(() => undefined)\n            return\n          }\n          deliver(snapshot.exists(), snapshot.id, snapshot.data(), fromCache)\n\n          /**\n           * Unconfirmed HIT (AGL-1066), for entitlement-shaped docs only.\n           *\n           * The value is already delivered above and stays on screen\n           * whatever happens here — this never blanks the page and never\n           * holds `ready` false, because a transient blip must not become a\n           * wrong tier OR a 404. It only replaces a cached answer with the\n           * server's when the server can be reached.\n           */\n          if (\n            confirmCachedHit &&\n            fromCache &&\n            snapshot.exists() &&\n            !confirmRequested &&\n            !confirmTimer\n          ) {\n            confirmTimer = setTimeout(() => {\n              confirmTimer = null\n              confirmRequested = true\n              void sharedConfirm(pathKey, ref)\n                .then((server) => {\n                  if (cancelled) return\n                  deliver(server.exists(), server.id, server.data(), false)\n                })\n                // Could not reach the server: keep showing the cached value,\n                // still flagged `fromCache`. Refusing to answer would be the\n                // stale-`ready` false-404 this hook exists to prevent.\n                .catch(() => undefined)\n            }, CONFIRM_CACHED_HIT_DELAY_MS)\n          }\n        },\n        () => {\n          if (cancelled) return\n          unsubscribe?.()\n          if (attempt < MAX_RETRIES) {\n            const delay = Math.min(\n              RETRY_DELAY_MS * 2 ** attempt,\n              MAX_RETRY_DELAY_MS,\n            )\n            attempt += 1\n            timer = setTimeout(subscribe, delay)\n          } else {\n            setState({\n              data: undefined,\n              ready: true,\n              error: true,\n              fromCache: true,\n            })\n          }\n        },\n      )\n    }\n    subscribe()\n\n    return () => {\n      cancelled = true\n      if (timer) clearTimeout(timer)\n      if (confirmTimer) clearTimeout(confirmTimer)\n      unsubscribe?.()\n    }\n  }, [firestore, pathKey, confirmCachedHit])\n\n  return state\n}\n\nexport default useConfirmedDoc\n"],"names":["doc","getDocFromServer","onSnapshot","useEffect","useState","RETRY_DELAY_MS","MAX_RETRIES","MAX_RETRY_DELAY_MS","CONFIRM_CACHED_HIT_DELAY_MS","confirmsInFlight","Map","sharedConfirm","pathKey","ref","existing","get","pending","finally","delete","set","resetConfirmedDocSharing","clear","useConfirmedDoc","firestore","segments","options","state","setState","data","undefined","ready","error","fromCache","join","confirmCachedHit","cancelled","unsubscribe","timer","attempt","confirmTimer","confirmRequested","deliver","exists","id","payload","$id","subscribe","snapshot","metadata","clearTimeout","then","server","catch","setTimeout","delay","Math","min"],"mappings":"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"}

package/src/lib/hooks/use-host-component-definitions.d.ts

@@ -0,0 +1,40 @@
+import type * as Aglyn from '@aglyn/aglyn';
+export interface UseHostComponentDefinitionsResult {
+    /** Raw definition docs, `$id` included, tombstones and all. */
+    docs: Aglyn.AglynHostComponent[];
+    /**
+     * Live definitions keyed by id in the shape
+     * `composeReusableComponentNodes` consumes, or `undefined` until the
+     * first snapshot settles — see the callers for why "loading" and "this
+     * host has none" must not look the same.
+     */
+    definitions: Record<string, Aglyn.ReusableComponentTree> | undefined;
+}
+/**
+ * Client-side twin of `libs/tenant/runtime/src/lib/get-components.ts`: the
+ * host's reusable-component definitions, read through ONE query and shared
+ * by everything in the editor that needs them (AGL-1217).
+ *
+ * "One query", not "read once": `useFirestoreCollection` is a live
+ * `onSnapshot` listener, and that is load-bearing rather than incidental.
+ * It is the entire transport for propagating a component edit into already
+ * open besigners (AGL-1898) — publish a component in one tab and every
+ * canvas rendering an instance of it re-renders, because this map is a new
+ * object and the consumers memo on it. Swapping this for a one-shot read to
+ * "save reads" would silently take that away, and nothing would fail: the
+ * canvas would simply keep drawing a stale component until reloaded.
+ *
+ * Note the boundary. This watches the component's PARENT doc, which only
+ * Publish writes; the component editor's Save writes the version doc and is
+ * invisible here.
+ *
+ * One hook rather than a read per consumer so the console asks the same
+ * question the same way — identical `Query`, so the SDK serves every caller
+ * from a single listener — and so the skip rules stay in one place. A doc
+ * missing `rootId`/`nodes` is unpublished, not broken; skipping it here is
+ * what keeps the canvas agreeing with the live site about which instances
+ * expand. Fail-open like the server loader: an error yields an empty map,
+ * leaving instances as-is rather than blanking the document.
+ */
+export declare function useHostComponentDefinitions(hostId: string | undefined): UseHostComponentDefinitionsResult;
+export default useHostComponentDefinitions;

package/src/lib/hooks/use-host-component-definitions.js

@@ -0,0 +1,92 @@
+/**
+ * @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";
+// Deep path, keeping the type-only barrel import above erased.
+import { decodeStoredNodes } from "@aglyn/aglyn/app-utils/stored-nodes";
+import { useFirestore } from "./firebase/firebase-services.js";
+import { collection, limit, query } from "firebase/firestore";
+import { useMemo } from "react";
+import useFirestoreCollection from "./use-firestore-collection.js";
+/**
+ * Client-side twin of `libs/tenant/runtime/src/lib/get-components.ts`: the
+ * host's reusable-component definitions, read through ONE query and shared
+ * by everything in the editor that needs them (AGL-1217).
+ *
+ * "One query", not "read once": `useFirestoreCollection` is a live
+ * `onSnapshot` listener, and that is load-bearing rather than incidental.
+ * It is the entire transport for propagating a component edit into already
+ * open besigners (AGL-1898) — publish a component in one tab and every
+ * canvas rendering an instance of it re-renders, because this map is a new
+ * object and the consumers memo on it. Swapping this for a one-shot read to
+ * "save reads" would silently take that away, and nothing would fail: the
+ * canvas would simply keep drawing a stale component until reloaded.
+ *
+ * Note the boundary. This watches the component's PARENT doc, which only
+ * Publish writes; the component editor's Save writes the version doc and is
+ * invisible here.
+ *
+ * One hook rather than a read per consumer so the console asks the same
+ * question the same way — identical `Query`, so the SDK serves every caller
+ * from a single listener — and so the skip rules stay in one place. A doc
+ * missing `rootId`/`nodes` is unpublished, not broken; skipping it here is
+ * what keeps the canvas agreeing with the live site about which instances
+ * expand. Fail-open like the server loader: an error yields an empty map,
+ * leaving instances as-is rather than blanking the document.
+ */ export function useHostComponentDefinitions(hostId) {
+    const firestore = useFirestore();
+    const { data, status } = useFirestoreCollection(()=>hostId ? query(collection(firestore, 'hosts', hostId, 'components'), limit(200)) : null, [
+        firestore,
+        hostId
+    ], {
+        idField: '$id'
+    });
+    const definitions = useMemo(()=>{
+        if (status === 'loading') return undefined;
+        const next = {};
+        for (const value of data != null ? data : []){
+            var _value_props, _value_icon;
+            if ((value == null ? void 0 : value.deletedAt) || !(value == null ? void 0 : value.nodes) || !(value == null ? void 0 : value.rootId)) continue;
+            // BOTH stored forms (AGL-1151). This is a raw collection query, so
+            // `nodes` arrives exactly as stored — msgpack for anything promoted
+            // since components were compressed, a plain map for everything older.
+            // The canvas grafts every instance from this map, so a `Bytes` reaching
+            // it blanks every placed component in the editor while the live site
+            // still renders them.
+            const nodes = decodeStoredNodes(value.nodes);
+            if (!nodes) continue;
+            next[value.$id] = _extends({
+                rootId: value.rootId,
+                nodes
+            }, ((_value_props = value.props) == null ? void 0 : _value_props.length) && {
+                props: value.props
+            }, ((_value_icon = value.icon) == null ? void 0 : _value_icon.iconPath) && {
+                icon: value.icon
+            });
+        }
+        return next;
+    }, [
+        data,
+        status
+    ]);
+    return {
+        docs: data != null ? data : [],
+        definitions
+    };
+}
+export default useHostComponentDefinitions;
+
+//# sourceMappingURL=use-host-component-definitions.js.map

package/src/lib/hooks/use-host-component-definitions.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../../libs/tenant/feature/instance/src/lib/hooks/use-host-component-definitions.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 type * as Aglyn from '@aglyn/aglyn'\n// Deep path, keeping the type-only barrel import above erased.\nimport { decodeStoredNodes } from '@aglyn/aglyn/app-utils/stored-nodes'\nimport { useFirestore } from './firebase/firebase-services'\nimport { collection, limit, query } from 'firebase/firestore'\nimport { useMemo } from 'react'\nimport useFirestoreCollection from './use-firestore-collection'\n\nexport interface UseHostComponentDefinitionsResult {\n  /** Raw definition docs, `$id` included, tombstones and all. */\n  docs: Aglyn.AglynHostComponent[]\n  /**\n   * Live definitions keyed by id in the shape\n   * `composeReusableComponentNodes` consumes, or `undefined` until the\n   * first snapshot settles — see the callers for why \"loading\" and \"this\n   * host has none\" must not look the same.\n   */\n  definitions: Record<string, Aglyn.ReusableComponentTree> | undefined\n}\n\n/**\n * Client-side twin of `libs/tenant/runtime/src/lib/get-components.ts`: the\n * host's reusable-component definitions, read through ONE query and shared\n * by everything in the editor that needs them (AGL-1217).\n *\n * \"One query\", not \"read once\": `useFirestoreCollection` is a live\n * `onSnapshot` listener, and that is load-bearing rather than incidental.\n * It is the entire transport for propagating a component edit into already\n * open besigners (AGL-1898) — publish a component in one tab and every\n * canvas rendering an instance of it re-renders, because this map is a new\n * object and the consumers memo on it. Swapping this for a one-shot read to\n * \"save reads\" would silently take that away, and nothing would fail: the\n * canvas would simply keep drawing a stale component until reloaded.\n *\n * Note the boundary. This watches the component's PARENT doc, which only\n * Publish writes; the component editor's Save writes the version doc and is\n * invisible here.\n *\n * One hook rather than a read per consumer so the console asks the same\n * question the same way — identical `Query`, so the SDK serves every caller\n * from a single listener — and so the skip rules stay in one place. A doc\n * missing `rootId`/`nodes` is unpublished, not broken; skipping it here is\n * what keeps the canvas agreeing with the live site about which instances\n * expand. Fail-open like the server loader: an error yields an empty map,\n * leaving instances as-is rather than blanking the document.\n */\nexport function useHostComponentDefinitions(\n  hostId: string | undefined,\n): UseHostComponentDefinitionsResult {\n  const firestore = useFirestore()\n  const { data, status } = useFirestoreCollection<Aglyn.AglynHostComponent>(\n    () =>\n      hostId\n        ? query(collection(firestore, 'hosts', hostId, 'components'), limit(200))\n        : null,\n    [firestore, hostId],\n    { idField: '$id' },\n  )\n\n  const definitions = useMemo(() => {\n    if (status === 'loading') return undefined\n    const next: Record<string, Aglyn.ReusableComponentTree> = {}\n    for (const value of data ?? []) {\n      if (value?.deletedAt || !value?.nodes || !value?.rootId) continue\n      // BOTH stored forms (AGL-1151). This is a raw collection query, so\n      // `nodes` arrives exactly as stored — msgpack for anything promoted\n      // since components were compressed, a plain map for everything older.\n      // The canvas grafts every instance from this map, so a `Bytes` reaching\n      // it blanks every placed component in the editor while the live site\n      // still renders them.\n      const nodes = decodeStoredNodes<Aglyn.ReusableComponentTree['nodes']>(\n        value.nodes,\n      )\n      if (!nodes) continue\n      next[value.$id] = {\n        rootId: value.rootId,\n        nodes,\n        // Declared props ride along (AGL-1247) so the editor's graft\n        // substitutes the same values the live site will.\n        ...(value.props?.length && { props: value.props }),\n        // As does the chosen icon (AGL-1193) — the hierarchy row and canvas\n        // badge draw it from here, so an instance's icon needs no read of\n        // its own.\n        ...(value.icon?.iconPath && { icon: value.icon }),\n      }\n    }\n    return next\n  }, [data, status])\n\n  return { docs: data ?? [], definitions }\n}\n\nexport default useHostComponentDefinitions\n"],"names":["decodeStoredNodes","useFirestore","collection","limit","query","useMemo","useFirestoreCollection","useHostComponentDefinitions","hostId","firestore","data","status","idField","definitions","undefined","next","value","deletedAt","nodes","rootId","$id","props","length","icon","iconPath","docs"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GACD;;AAGA,+DAA+D;AAC/D,SAASA,iBAAiB,QAAQ,sCAAqC;AACvE,SAASC,YAAY,QAAQ,kCAA8B;AAC3D,SAASC,UAAU,EAAEC,KAAK,EAAEC,KAAK,QAAQ,qBAAoB;AAC7D,SAASC,OAAO,QAAQ,QAAO;AAC/B,OAAOC,4BAA4B,gCAA4B;AAc/D;;;;;;;;;;;;;;;;;;;;;;;;;CAyBC,GACD,OAAO,SAASC,4BACdC,MAA0B;IAE1B,MAAMC,YAAYR;IAClB,MAAM,EAAES,IAAI,EAAEC,MAAM,EAAE,GAAGL,uBACvB,IACEE,SACIJ,MAAMF,WAAWO,WAAW,SAASD,QAAQ,eAAeL,MAAM,QAClE,MACN;QAACM;QAAWD;KAAO,EACnB;QAAEI,SAAS;IAAM;IAGnB,MAAMC,cAAcR,QAAQ;QAC1B,IAAIM,WAAW,WAAW,OAAOG;QACjC,MAAMC,OAAoD,CAAC;QAC3D,KAAK,MAAMC,SAASN,eAAAA,OAAQ,EAAE,CAAE;gBAiBxBM,cAIAA;YApBN,IAAIA,CAAAA,yBAAAA,MAAOC,SAAS,KAAI,EAACD,yBAAAA,MAAOE,KAAK,KAAI,EAACF,yBAAAA,MAAOG,MAAM,GAAE;YACzD,mEAAmE;YACnE,oEAAoE;YACpE,sEAAsE;YACtE,wEAAwE;YACxE,qEAAqE;YACrE,sBAAsB;YACtB,MAAMD,QAAQlB,kBACZgB,MAAME,KAAK;YAEb,IAAI,CAACA,OAAO;YACZH,IAAI,CAACC,MAAMI,GAAG,CAAC,GAAG;gBAChBD,QAAQH,MAAMG,MAAM;gBACpBD;eAGIF,EAAAA,eAAAA,MAAMK,KAAK,qBAAXL,aAAaM,MAAM,KAAI;gBAAED,OAAOL,MAAMK,KAAK;YAAC,GAI5CL,EAAAA,cAAAA,MAAMO,IAAI,qBAAVP,YAAYQ,QAAQ,KAAI;gBAAED,MAAMP,MAAMO,IAAI;YAAC;QAEnD;QACA,OAAOR;IACT,GAAG;QAACL;QAAMC;KAAO;IAEjB,OAAO;QAAEc,IAAI,EAAEf,eAAAA,OAAQ,EAAE;QAAEG;IAAY;AACzC;AAEA,eAAeN,4BAA2B"}

package/src/lib/hooks/use-host-form-designs.d.ts

@@ -0,0 +1,42 @@
+import type * as Aglyn from '@aglyn/aglyn';
+/** A form document as the query hands it back, with its id stamped on. */
+type FormDocumentWithId = Aglyn.FormDocument & {
+    $id: string;
+};
+export interface UseHostFormDesignsResult {
+    /** Raw form docs, `$id` included, unpublished ones and all. */
+    docs: FormDocumentWithId[];
+    /**
+     * The published design of each form, keyed by id, or `undefined` until the
+     * first snapshot settles — "loading" and "this host has none" must not look
+     * the same, or the canvas paints the page's own fields and swaps them for
+     * the entity's a beat later.
+     */
+    designs: Record<string, Aglyn.PlacedFormDesign> | undefined;
+}
+/**
+ * Client-side twin of `libs/tenant/runtime/src/lib/get-forms.ts`: the host's
+ * form entities read through ONE query, so a placed form draws its entity's
+ * fields on the canvas exactly as the published page will
+ * (`docs/specs/reusable-forms.md`).
+ *
+ * A sibling of `use-host-component-definitions.ts` in every respect that
+ * matters, because the two answer the same question about different documents.
+ * That includes the live `onSnapshot`, which is load-bearing rather than
+ * incidental: it is the whole transport for propagating a form publish into
+ * already-open screen besigners. A one-shot read would "save reads" and
+ * silently leave every open canvas drawing a stale form until reloaded.
+ *
+ * Note the boundary, the same one the components hook draws: this watches the
+ * form's PARENT doc, which only Publish writes. The form besigner's Save
+ * writes the version doc and is invisible here — a screen must not show fields
+ * the live site has never had.
+ *
+ * A doc with no `rootId`/`nodes`, or whose root is missing from its own nodes,
+ * is unpublished rather than broken; skipping it is what keeps the canvas
+ * agreeing with the live site about which placements resolve. Fail-open like
+ * the server loader: an error yields an empty map, leaving each placement
+ * rendering its own fields rather than blanking it.
+ */
+export declare function useHostFormDesigns(hostId: string | undefined): UseHostFormDesignsResult;
+export default useHostFormDesigns;

package/src/lib/hooks/use-host-form-designs.js

@@ -0,0 +1,84 @@
+/**
+ * @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';
+// Deep path, keeping the type-only barrel import above erased.
+import { decodeStoredNodes } from "@aglyn/aglyn/app-utils/stored-nodes";
+import { useFirestore } from "./firebase/firebase-services.js";
+import { collection, limit, query } from "firebase/firestore";
+import { useMemo } from "react";
+import useFirestoreCollection from "./use-firestore-collection.js";
+/** Matches the tenant render read, so the canvas cannot see more than a page. */ const FORMS_PER_CANVAS = 200;
+/**
+ * Client-side twin of `libs/tenant/runtime/src/lib/get-forms.ts`: the host's
+ * form entities read through ONE query, so a placed form draws its entity's
+ * fields on the canvas exactly as the published page will
+ * (`docs/specs/reusable-forms.md`).
+ *
+ * A sibling of `use-host-component-definitions.ts` in every respect that
+ * matters, because the two answer the same question about different documents.
+ * That includes the live `onSnapshot`, which is load-bearing rather than
+ * incidental: it is the whole transport for propagating a form publish into
+ * already-open screen besigners. A one-shot read would "save reads" and
+ * silently leave every open canvas drawing a stale form until reloaded.
+ *
+ * Note the boundary, the same one the components hook draws: this watches the
+ * form's PARENT doc, which only Publish writes. The form besigner's Save
+ * writes the version doc and is invisible here — a screen must not show fields
+ * the live site has never had.
+ *
+ * A doc with no `rootId`/`nodes`, or whose root is missing from its own nodes,
+ * is unpublished rather than broken; skipping it is what keeps the canvas
+ * agreeing with the live site about which placements resolve. Fail-open like
+ * the server loader: an error yields an empty map, leaving each placement
+ * rendering its own fields rather than blanking it.
+ */ export function useHostFormDesigns(hostId) {
+    const firestore = useFirestore();
+    const { data, status } = useFirestoreCollection(()=>hostId ? query(collection(firestore, 'hosts', hostId, 'forms'), limit(FORMS_PER_CANVAS)) : null, [
+        firestore,
+        hostId
+    ], {
+        idField: '$id'
+    });
+    const designs = useMemo(()=>{
+        if (status === 'loading') return undefined;
+        const next = {};
+        for (const value of data != null ? data : []){
+            if (!(value == null ? void 0 : value.nodes) || !(value == null ? void 0 : value.rootId)) continue;
+            // BOTH stored forms (AGL-1151). This is a raw collection query, so
+            // `nodes` arrives exactly as stored — msgpack for anything published
+            // since compression landed, a plain map for anything older. A `Bytes`
+            // reaching the graft has no `rootId` entry, so every placed form on the
+            // canvas would draw empty while the live site still renders it.
+            const nodes = decodeStoredNodes(value.nodes);
+            if (!(nodes == null ? void 0 : nodes[value.rootId])) continue;
+            next[value.$id] = {
+                rootId: value.rootId,
+                nodes
+            };
+        }
+        return next;
+    }, [
+        data,
+        status
+    ]);
+    return {
+        docs: data != null ? data : [],
+        designs
+    };
+}
+export default useHostFormDesigns;
+
+//# sourceMappingURL=use-host-form-designs.js.map

package/src/lib/hooks/use-host-form-designs.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../../libs/tenant/feature/instance/src/lib/hooks/use-host-form-designs.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 type * as Aglyn from '@aglyn/aglyn'\n// Deep path, keeping the type-only barrel import above erased.\nimport { decodeStoredNodes } from '@aglyn/aglyn/app-utils/stored-nodes'\nimport { useFirestore } from './firebase/firebase-services'\nimport { collection, limit, query } from 'firebase/firestore'\nimport { useMemo } from 'react'\nimport useFirestoreCollection from './use-firestore-collection'\n\n/** Matches the tenant render read, so the canvas cannot see more than a page. */\nconst FORMS_PER_CANVAS = 200\n\n/** A form document as the query hands it back, with its id stamped on. */\ntype FormDocumentWithId = Aglyn.FormDocument & { $id: string }\n\nexport interface UseHostFormDesignsResult {\n  /** Raw form docs, `$id` included, unpublished ones and all. */\n  docs: FormDocumentWithId[]\n  /**\n   * The published design of each form, keyed by id, or `undefined` until the\n   * first snapshot settles — \"loading\" and \"this host has none\" must not look\n   * the same, or the canvas paints the page's own fields and swaps them for\n   * the entity's a beat later.\n   */\n  designs: Record<string, Aglyn.PlacedFormDesign> | undefined\n}\n\n/**\n * Client-side twin of `libs/tenant/runtime/src/lib/get-forms.ts`: the host's\n * form entities read through ONE query, so a placed form draws its entity's\n * fields on the canvas exactly as the published page will\n * (`docs/specs/reusable-forms.md`).\n *\n * A sibling of `use-host-component-definitions.ts` in every respect that\n * matters, because the two answer the same question about different documents.\n * That includes the live `onSnapshot`, which is load-bearing rather than\n * incidental: it is the whole transport for propagating a form publish into\n * already-open screen besigners. A one-shot read would \"save reads\" and\n * silently leave every open canvas drawing a stale form until reloaded.\n *\n * Note the boundary, the same one the components hook draws: this watches the\n * form's PARENT doc, which only Publish writes. The form besigner's Save\n * writes the version doc and is invisible here — a screen must not show fields\n * the live site has never had.\n *\n * A doc with no `rootId`/`nodes`, or whose root is missing from its own nodes,\n * is unpublished rather than broken; skipping it is what keeps the canvas\n * agreeing with the live site about which placements resolve. Fail-open like\n * the server loader: an error yields an empty map, leaving each placement\n * rendering its own fields rather than blanking it.\n */\nexport function useHostFormDesigns(\n  hostId: string | undefined,\n): UseHostFormDesignsResult {\n  const firestore = useFirestore()\n  const { data, status } = useFirestoreCollection<FormDocumentWithId>(\n    () =>\n      hostId\n        ? query(\n            collection(firestore, 'hosts', hostId, 'forms'),\n            limit(FORMS_PER_CANVAS),\n          )\n        : null,\n    [firestore, hostId],\n    { idField: '$id' },\n  )\n\n  const designs = useMemo(() => {\n    if (status === 'loading') return undefined\n    const next: Record<string, Aglyn.PlacedFormDesign> = {}\n    for (const value of data ?? []) {\n      if (!value?.nodes || !value?.rootId) continue\n      // BOTH stored forms (AGL-1151). This is a raw collection query, so\n      // `nodes` arrives exactly as stored — msgpack for anything published\n      // since compression landed, a plain map for anything older. A `Bytes`\n      // reaching the graft has no `rootId` entry, so every placed form on the\n      // canvas would draw empty while the live site still renders it.\n      const nodes = decodeStoredNodes<\n        NonNullable<Aglyn.FormDocument['nodes']>\n      >(value.nodes)\n      if (!nodes?.[value.rootId]) continue\n      next[value.$id] = { rootId: value.rootId, nodes }\n    }\n    return next\n  }, [data, status])\n\n  return { docs: data ?? [], designs }\n}\n\nexport default useHostFormDesigns\n"],"names":["decodeStoredNodes","useFirestore","collection","limit","query","useMemo","useFirestoreCollection","FORMS_PER_CANVAS","useHostFormDesigns","hostId","firestore","data","status","idField","designs","undefined","next","value","nodes","rootId","$id","docs"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GACD;AAGA,+DAA+D;AAC/D,SAASA,iBAAiB,QAAQ,sCAAqC;AACvE,SAASC,YAAY,QAAQ,kCAA8B;AAC3D,SAASC,UAAU,EAAEC,KAAK,EAAEC,KAAK,QAAQ,qBAAoB;AAC7D,SAASC,OAAO,QAAQ,QAAO;AAC/B,OAAOC,4BAA4B,gCAA4B;AAE/D,+EAA+E,GAC/E,MAAMC,mBAAmB;AAiBzB;;;;;;;;;;;;;;;;;;;;;;;CAuBC,GACD,OAAO,SAASC,mBACdC,MAA0B;IAE1B,MAAMC,YAAYT;IAClB,MAAM,EAAEU,IAAI,EAAEC,MAAM,EAAE,GAAGN,uBACvB,IACEG,SACIL,MACEF,WAAWQ,WAAW,SAASD,QAAQ,UACvCN,MAAMI,qBAER,MACN;QAACG;QAAWD;KAAO,EACnB;QAAEI,SAAS;IAAM;IAGnB,MAAMC,UAAUT,QAAQ;QACtB,IAAIO,WAAW,WAAW,OAAOG;QACjC,MAAMC,OAA+C,CAAC;QACtD,KAAK,MAAMC,SAASN,eAAAA,OAAQ,EAAE,CAAE;YAC9B,IAAI,EAACM,yBAAAA,MAAOC,KAAK,KAAI,EAACD,yBAAAA,MAAOE,MAAM,GAAE;YACrC,mEAAmE;YACnE,qEAAqE;YACrE,sEAAsE;YACtE,wEAAwE;YACxE,gEAAgE;YAChE,MAAMD,QAAQlB,kBAEZiB,MAAMC,KAAK;YACb,IAAI,EAACA,yBAAAA,KAAO,CAACD,MAAME,MAAM,CAAC,GAAE;YAC5BH,IAAI,CAACC,MAAMG,GAAG,CAAC,GAAG;gBAAED,QAAQF,MAAME,MAAM;gBAAED;YAAM;QAClD;QACA,OAAOF;IACT,GAAG;QAACL;QAAMC;KAAO;IAEjB,OAAO;QAAES,IAAI,EAAEV,eAAAA,OAAQ,EAAE;QAAEG;IAAQ;AACrC;AAEA,eAAeN,mBAAkB"}