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

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

@@ -0,0 +1,130 @@
+/**
+ * @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 { _ as _object_without_properties_loose } from "@swc/helpers/_/_object_without_properties_loose";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { TABLE_PAGE_SIZE_DEFAULT } from "@aglyn/shared-ui-jsx/const/table-pagination";
+import { useFirestoreCollection } from "./use-firestore-collection.js";
+/**
+ * A paged window over a live collection, instead of a big read sliced small.
+ *
+ * ## The shape this replaces
+ *
+ * A card would listen with `limit(300)` and render `rows.slice(0, 50)`. That
+ * is wrong twice over. Two hundred and fifty documents are read, billed and
+ * discarded on every mount — and the rows past the slice are not merely
+ * wasted, they are UNREACHABLE, because nothing renders them and no control
+ * asks for more. A merchant with sixty gift cards sees fifty and no
+ * indication that ten more exist; past three hundred, a card issued this
+ * morning cannot be reached at all.
+ *
+ * Here the window IS the query, and it is expressed in PAGES so the same
+ * `ListPagination` footer serves this and a cursor feed. The listener is
+ * widened to cover every page up to the one being read, so paging BACK costs
+ * nothing — the rows are already in the snapshot — and paging forward costs
+ * one page more.
+ *
+ * ## Why the window covers page 0..n rather than page n alone
+ *
+ * This is a live `onSnapshot`, not a fetch. Firestore cursors need a document
+ * snapshot to resume from, which a listener that has never read page n - 1
+ * does not have. Widening the limit is what makes forward and backward
+ * symmetrical without a second read path, and the cost is bounded by how deep
+ * the reader actually goes — with the shared default of ten, page three is
+ * thirty-one documents, and most readers never leave page one.
+ *
+ * ## Why over-fetch by one
+ *
+ * `hasMore` has to be a fact. Comparing `length === limit` is wrong exactly
+ * when the count is an even multiple of the page size — the case that offers
+ * a "next page" leading nowhere, or hides one that leads somewhere. The probe
+ * row answers it outright and is never rendered.
+ *
+ * ## Why the window resets on `deps`
+ *
+ * `deps` identify the SUBJECT being listened to. Without the reset, a card
+ * paged three deep on one site opens the next site three pages in — a read
+ * the reader never asked for, charged to whoever they switched to.
+ *
+ * `buildQuery` receives the limit to apply, so the caller keeps ownership of
+ * ordering and predicates:
+ *
+ * ```ts
+ * usePagedCollection<Card>(
+ *   (pageLimit) =>
+ *     hostId
+ *       ? query(collection(firestore, 'hosts', hostId, 'giftCards'),
+ *               orderBy('createdAt', 'desc'), limit(pageLimit))
+ *       : null,
+ *   [firestore, hostId],
+ *   { idField: '$id' },
+ * )
+ * ```
+ */ export function usePagedCollection(buildQuery, deps, options = {}) {
+    var _ref;
+    var _result_data;
+    const { pageSize: initialPageSize = TABLE_PAGE_SIZE_DEFAULT } = options, collectionOptions = _object_without_properties_loose(options, [
+        "pageSize"
+    ]);
+    const [pageSize, setPageSizeState] = useState(initialPageSize);
+    const [page, setPage] = useState(0);
+    const buildQueryRef = useRef(buildQuery);
+    buildQueryRef.current = buildQuery;
+    /*
+   * A new subject starts at page one. Spreading `deps` is the same contract
+   * `useFirestoreCollection` documents — pass the primitive ids, not the
+   * Query.
+   */ useEffect(()=>{
+        setPage(0);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [
+        ...deps
+    ]);
+    // Everything up to and including the page being read, plus the probe row.
+    const windowSize = pageSize * (page + 1);
+    const result = useFirestoreCollection(()=>buildQueryRef.current(windowSize + 1), // eslint-disable-next-line react-hooks/exhaustive-deps
+    [
+        ...deps,
+        windowSize
+    ], collectionOptions);
+    const hasMore = ((_ref = (_result_data = result.data) == null ? void 0 : _result_data.length) != null ? _ref : 0) > windowSize;
+    const rows = useMemo(()=>{
+        var _result_data;
+        return ((_result_data = result.data) != null ? _result_data : []).slice(page * pageSize, windowSize);
+    }, [
+        result.data,
+        page,
+        pageSize,
+        windowSize
+    ]);
+    const setPageSize = useCallback((next)=>{
+        setPageSizeState(next);
+        // Page four of a ten-row list does not exist once the reader asks for
+        // fifty at a time, and an out-of-range page renders as an empty list
+        // with no explanation — which reads as the data having gone.
+        setPage(0);
+    }, []);
+    return _extends({}, result, {
+        rows,
+        hasMore,
+        page,
+        setPage,
+        pageSize,
+        setPageSize
+    });
+}
+
+//# sourceMappingURL=use-paged-collection.js.map

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

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../../libs/tenant/feature/instance/src/lib/hooks/use-paged-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\nimport type { DocumentData, Query } from 'firebase/firestore'\nimport {\n  useCallback,\n  useEffect,\n  useMemo,\n  useRef,\n  useState,\n  type DependencyList,\n} from 'react'\nimport { TABLE_PAGE_SIZE_DEFAULT } from '@aglyn/shared-ui-jsx/const/table-pagination'\nimport {\n  useFirestoreCollection,\n  type UseFirestoreCollectionOptions,\n  type UseFirestoreCollectionResult,\n} from './use-firestore-collection'\n\nexport interface UsePagedCollectionOptions\n  extends UseFirestoreCollectionOptions {\n  /**\n   * Rows per page. Defaults to the console-wide smallest option — a list\n   * that picks its own number is how five different ones appear, and on a\n   * query bounded by its page size the smallest page is the smallest bill.\n   */\n  pageSize?: number\n}\n\nexport interface UsePagedCollectionResult<T>\n  extends UseFirestoreCollectionResult<T> {\n  /** The current page's rows. `data` holds the probe row; this never does. */\n  rows: T[]\n  /** A further page exists. A FACT from the probe row, not a guess. */\n  hasMore: boolean\n  /** Zero-based, to match `ListPagination` and MUI. */\n  page: number\n  setPage: (page: number) => void\n  pageSize: number\n  setPageSize: (pageSize: number) => void\n}\n\n/**\n * A paged window over a live collection, instead of a big read sliced small.\n *\n * ## The shape this replaces\n *\n * A card would listen with `limit(300)` and render `rows.slice(0, 50)`. That\n * is wrong twice over. Two hundred and fifty documents are read, billed and\n * discarded on every mount — and the rows past the slice are not merely\n * wasted, they are UNREACHABLE, because nothing renders them and no control\n * asks for more. A merchant with sixty gift cards sees fifty and no\n * indication that ten more exist; past three hundred, a card issued this\n * morning cannot be reached at all.\n *\n * Here the window IS the query, and it is expressed in PAGES so the same\n * `ListPagination` footer serves this and a cursor feed. The listener is\n * widened to cover every page up to the one being read, so paging BACK costs\n * nothing — the rows are already in the snapshot — and paging forward costs\n * one page more.\n *\n * ## Why the window covers page 0..n rather than page n alone\n *\n * This is a live `onSnapshot`, not a fetch. Firestore cursors need a document\n * snapshot to resume from, which a listener that has never read page n - 1\n * does not have. Widening the limit is what makes forward and backward\n * symmetrical without a second read path, and the cost is bounded by how deep\n * the reader actually goes — with the shared default of ten, page three is\n * thirty-one documents, and most readers never leave page one.\n *\n * ## Why over-fetch by one\n *\n * `hasMore` has to be a fact. Comparing `length === limit` is wrong exactly\n * when the count is an even multiple of the page size — the case that offers\n * a \"next page\" leading nowhere, or hides one that leads somewhere. The probe\n * row answers it outright and is never rendered.\n *\n * ## Why the window resets on `deps`\n *\n * `deps` identify the SUBJECT being listened to. Without the reset, a card\n * paged three deep on one site opens the next site three pages in — a read\n * the reader never asked for, charged to whoever they switched to.\n *\n * `buildQuery` receives the limit to apply, so the caller keeps ownership of\n * ordering and predicates:\n *\n * ```ts\n * usePagedCollection<Card>(\n *   (pageLimit) =>\n *     hostId\n *       ? query(collection(firestore, 'hosts', hostId, 'giftCards'),\n *               orderBy('createdAt', 'desc'), limit(pageLimit))\n *       : null,\n *   [firestore, hostId],\n *   { idField: '$id' },\n * )\n * ```\n */\nexport function usePagedCollection<T = DocumentData>(\n  buildQuery: (pageLimit: number) => Query<DocumentData> | null | undefined,\n  deps: DependencyList,\n  options: UsePagedCollectionOptions = {},\n): UsePagedCollectionResult<T> {\n  const { pageSize: initialPageSize = TABLE_PAGE_SIZE_DEFAULT, ...collectionOptions } =\n    options\n  const [pageSize, setPageSizeState] = useState(initialPageSize)\n  const [page, setPage] = useState(0)\n  const buildQueryRef = useRef(buildQuery)\n  buildQueryRef.current = buildQuery\n\n  /*\n   * A new subject starts at page one. Spreading `deps` is the same contract\n   * `useFirestoreCollection` documents — pass the primitive ids, not the\n   * Query.\n   */\n  useEffect(() => {\n    setPage(0)\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n  }, [...deps])\n\n  // Everything up to and including the page being read, plus the probe row.\n  const windowSize = pageSize * (page + 1)\n  const result = useFirestoreCollection<T>(\n    () => buildQueryRef.current(windowSize + 1),\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n    [...deps, windowSize],\n    collectionOptions,\n  )\n\n  const hasMore = (result.data?.length ?? 0) > windowSize\n  const rows = useMemo(\n    () => (result.data ?? []).slice(page * pageSize, windowSize),\n    [result.data, page, pageSize, windowSize],\n  )\n  const setPageSize = useCallback((next: number) => {\n    setPageSizeState(next)\n    // Page four of a ten-row list does not exist once the reader asks for\n    // fifty at a time, and an out-of-range page renders as an empty list\n    // with no explanation — which reads as the data having gone.\n    setPage(0)\n  }, [])\n\n  return { ...result, rows, hasMore, page, setPage, pageSize, setPageSize }\n}\n"],"names":["useCallback","useEffect","useMemo","useRef","useState","TABLE_PAGE_SIZE_DEFAULT","useFirestoreCollection","usePagedCollection","buildQuery","deps","options","result","pageSize","initialPageSize","collectionOptions","setPageSizeState","page","setPage","buildQueryRef","current","windowSize","hasMore","data","length","rows","slice","setPageSize","next"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC;;AAGD,SACEA,WAAW,EACXC,SAAS,EACTC,OAAO,EACPC,MAAM,EACNC,QAAQ,QAEH,QAAO;AACd,SAASC,uBAAuB,QAAQ,8CAA6C;AACrF,SACEC,sBAAsB,QAGjB,gCAA4B;AAyBnC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAuDC,GACD,OAAO,SAASC,mBACdC,UAAyE,EACzEC,IAAoB,EACpBC,UAAqC,CAAC,CAAC;;QA4BtBC;IA1BjB,MAAM,EAAEC,UAAUC,kBAAkBR,uBAAuB,EAAwB,GACjFK,SAD8DI,qDAC9DJ;;;IACF,MAAM,CAACE,UAAUG,iBAAiB,GAAGX,SAASS;IAC9C,MAAM,CAACG,MAAMC,QAAQ,GAAGb,SAAS;IACjC,MAAMc,gBAAgBf,OAAOK;IAC7BU,cAAcC,OAAO,GAAGX;IAExB;;;;GAIC,GACDP,UAAU;QACRgB,QAAQ;IACR,uDAAuD;IACzD,GAAG;WAAIR;KAAK;IAEZ,0EAA0E;IAC1E,MAAMW,aAAaR,WAAYI,CAAAA,OAAO,CAAA;IACtC,MAAML,SAASL,uBACb,IAAMY,cAAcC,OAAO,CAACC,aAAa,IACzC,uDAAuD;IACvD;WAAIX;QAAMW;KAAW,EACrBN;IAGF,MAAMO,UAAU,UAACV,eAAAA,OAAOW,IAAI,qBAAXX,aAAaY,MAAM,mBAAI,KAAKH;IAC7C,MAAMI,OAAOtB,QACX;YAAOS;eAAD,EAACA,eAAAA,OAAOW,IAAI,YAAXX,eAAe,EAAE,EAAEc,KAAK,CAACT,OAAOJ,UAAUQ;OACjD;QAACT,OAAOW,IAAI;QAAEN;QAAMJ;QAAUQ;KAAW;IAE3C,MAAMM,cAAc1B,YAAY,CAAC2B;QAC/BZ,iBAAiBY;QACjB,sEAAsE;QACtE,qEAAqE;QACrE,6DAA6D;QAC7DV,QAAQ;IACV,GAAG,EAAE;IAEL,OAAO,aAAKN;QAAQa;QAAMH;QAASL;QAAMC;QAASL;QAAUc;;AAC9D"}

package/src/lib/hooks/use-plugin-config.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Live per-plugin config for a workspace (AGL-428): the org's
+ * `pluginSettings/{pluginId}` overrides merged over the plugin's declared
+ * schema defaults (type-coerced). Plugins call this from console pages/
+ * widgets with the orgId the shell resolves; `ready` turns true once the
+ * doc read settles either way.
+ */
+export declare function usePluginConfig(orgId: string | null | undefined, pluginId: string): {
+    config: Record<string, unknown>;
+    ready: boolean;
+};
+/**
+ * The same config, resolved for ONE SITE (AGL-428, AGL-1014): the
+ * workspace's stored overrides, then only the keys this site answers for
+ * itself, over the plugin's declared schema defaults. `overrides` names those keys, so a
+ * surface can say which answers are the site's own rather than inferring it
+ * by comparing values — two levels that happen to agree are still two levels.
+ *
+ * BOTH refs are held at null until their id is known, never addressed as
+ * `orgs/-pending-` or `hosts/-pending-` (AGL-1440). `pluginSettings` is
+ * member-gated at both scopes, so a sentinel id is a guaranteed permission
+ * denial on every mount rather than a read that might succeed — the
+ * anti-pattern `use-org-plan.ts` documents removing (AGL-1064). A null ref
+ * issues nothing and holds `status` at `'loading'`, which is already this
+ * hook's contract while the answer is unknown.
+ *
+ * `ready` needs BOTH reads, and needs both to have SUCCEEDED (AGL-1066).
+ * Answering ready off the org read alone would hand a caller the workspace's
+ * value as though it were this site's, which is the exact failure the site
+ * layer exists to prevent — and answering it off a refused read would hand
+ * them schema defaults as though they were stored settings.
+ */
+export declare function useSitePluginConfig(orgId: string | null | undefined, hostId: string | null | undefined, pluginId: string): {
+    config: Record<string, unknown>;
+    overrides: string[];
+    ready: boolean;
+};
+export default usePluginConfig;

package/src/lib/hooks/use-plugin-config.js

@@ -0,0 +1,120 @@
+/**
+ * @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 { getPluginConfigSchema, mergePluginConfig, pluginConfigOverrides, resolvePluginConfig } from "@aglyn/aglyn";
+import { doc } from "firebase/firestore";
+import { useMemo } from "react";
+import { useFirestore } from "./firebase/firebase-services.js";
+import { useFirestoreDoc } from "./use-firestore-doc.js";
+/**
+ * Live per-plugin config for a workspace (AGL-428): the org's
+ * `pluginSettings/{pluginId}` overrides merged over the plugin's declared
+ * schema defaults (type-coerced). Plugins call this from console pages/
+ * widgets with the orgId the shell resolves; `ready` turns true once the
+ * doc read settles either way.
+ */ export function usePluginConfig(orgId, pluginId) {
+    const firestore = useFirestore();
+    // Held at null while the org is unknown, never addressed as
+    // `orgs/-pending-` (AGL-1440): `pluginSettings` is member-gated, so the
+    // sentinel was a guaranteed-denied read on every mount of every plugin
+    // surface — the exact anti-pattern `use-org-plan.ts` documents removing
+    // (AGL-1064). A null ref issues nothing, `status` stays `'loading'`, and
+    // `ready` below stays false, which is already this hook's contract while
+    // the answer is unknown.
+    const { data, status } = useFirestoreDoc(()=>orgId ? doc(firestore, 'orgs', orgId, 'pluginSettings', pluginId) : null, [
+        firestore,
+        orgId,
+        pluginId
+    ]);
+    const config = useMemo(()=>{
+        const schema = getPluginConfigSchema(pluginId);
+        if (!schema) return data != null ? data : {};
+        return mergePluginConfig(schema, data != null ? data : null);
+    }, [
+        pluginId,
+        data
+    ]);
+    // `'success'` rather than `!== 'loading'` (AGL-1066): a refused listen can
+    // now reach `'error'`, and answering "ready" with an empty config would let
+    // a caller act on schema defaults as though they were the stored settings.
+    return {
+        config,
+        ready: status === 'success'
+    };
+}
+/**
+ * The same config, resolved for ONE SITE (AGL-428, AGL-1014): the
+ * workspace's stored overrides, then only the keys this site answers for
+ * itself, over the plugin's declared schema defaults. `overrides` names those keys, so a
+ * surface can say which answers are the site's own rather than inferring it
+ * by comparing values — two levels that happen to agree are still two levels.
+ *
+ * BOTH refs are held at null until their id is known, never addressed as
+ * `orgs/-pending-` or `hosts/-pending-` (AGL-1440). `pluginSettings` is
+ * member-gated at both scopes, so a sentinel id is a guaranteed permission
+ * denial on every mount rather than a read that might succeed — the
+ * anti-pattern `use-org-plan.ts` documents removing (AGL-1064). A null ref
+ * issues nothing and holds `status` at `'loading'`, which is already this
+ * hook's contract while the answer is unknown.
+ *
+ * `ready` needs BOTH reads, and needs both to have SUCCEEDED (AGL-1066).
+ * Answering ready off the org read alone would hand a caller the workspace's
+ * value as though it were this site's, which is the exact failure the site
+ * layer exists to prevent — and answering it off a refused read would hand
+ * them schema defaults as though they were stored settings.
+ */ export function useSitePluginConfig(orgId, hostId, pluginId) {
+    const firestore = useFirestore();
+    const { data: org, status: orgStatus } = useFirestoreDoc(()=>orgId ? doc(firestore, 'orgs', orgId, 'pluginSettings', pluginId) : null, [
+        firestore,
+        orgId,
+        pluginId
+    ]);
+    const { data: host, status: hostStatus } = useFirestoreDoc(()=>hostId ? doc(firestore, 'hosts', hostId, 'pluginSettings', pluginId) : null, [
+        firestore,
+        hostId,
+        pluginId
+    ]);
+    const resolved = useMemo(()=>{
+        const schema = getPluginConfigSchema(pluginId);
+        // Without a registered schema there is no field list to layer by, so the
+        // site's raw document simply narrows the workspace's — the same degrade
+        // `usePluginConfig` makes, one level deeper.
+        if (!schema) {
+            return {
+                config: _extends({}, org != null ? org : {}, host != null ? host : {}),
+                overrides: Object.keys(host != null ? host : {})
+            };
+        }
+        return {
+            config: resolvePluginConfig(schema, {
+                org: org != null ? org : null,
+                host: host != null ? host : null
+            }),
+            overrides: pluginConfigOverrides(schema, host != null ? host : null)
+        };
+    }, [
+        pluginId,
+        org,
+        host
+    ]);
+    return _extends({}, resolved, {
+        ready: orgStatus === 'success' && hostStatus === 'success'
+    });
+}
+export default usePluginConfig;
+
+//# sourceMappingURL=use-plugin-config.js.map

package/src/lib/hooks/use-plugin-config.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../../libs/tenant/feature/instance/src/lib/hooks/use-plugin-config.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  getPluginConfigSchema,\n  mergePluginConfig,\n  pluginConfigOverrides,\n  resolvePluginConfig,\n} from '@aglyn/aglyn'\nimport { doc } from 'firebase/firestore'\nimport { useMemo } from 'react'\nimport { useFirestore } from './firebase/firebase-services'\nimport { useFirestoreDoc } from './use-firestore-doc'\n\n/**\n * Live per-plugin config for a workspace (AGL-428): the org's\n * `pluginSettings/{pluginId}` overrides merged over the plugin's declared\n * schema defaults (type-coerced). Plugins call this from console pages/\n * widgets with the orgId the shell resolves; `ready` turns true once the\n * doc read settles either way.\n */\nexport function usePluginConfig(\n  orgId: string | null | undefined,\n  pluginId: string,\n): { config: Record<string, unknown>; ready: boolean } {\n  const firestore = useFirestore()\n  // Held at null while the org is unknown, never addressed as\n  // `orgs/-pending-` (AGL-1440): `pluginSettings` is member-gated, so the\n  // sentinel was a guaranteed-denied read on every mount of every plugin\n  // surface — the exact anti-pattern `use-org-plan.ts` documents removing\n  // (AGL-1064). A null ref issues nothing, `status` stays `'loading'`, and\n  // `ready` below stays false, which is already this hook's contract while\n  // the answer is unknown.\n  const { data, status } = useFirestoreDoc<Record<string, unknown>>(\n    () =>\n      orgId\n        ? doc(firestore, 'orgs', orgId, 'pluginSettings', pluginId)\n        : null,\n    [firestore, orgId, pluginId],\n  )\n  const config = useMemo(() => {\n    const schema = getPluginConfigSchema(pluginId)\n    if (!schema) return (data as Record<string, unknown>) ?? {}\n    return mergePluginConfig(schema, data ?? null)\n  }, [pluginId, data])\n  // `'success'` rather than `!== 'loading'` (AGL-1066): a refused listen can\n  // now reach `'error'`, and answering \"ready\" with an empty config would let\n  // a caller act on schema defaults as though they were the stored settings.\n  return { config, ready: status === 'success' }\n}\n\n/**\n * The same config, resolved for ONE SITE (AGL-428, AGL-1014): the\n * workspace's stored overrides, then only the keys this site answers for\n * itself, over the plugin's declared schema defaults. `overrides` names those keys, so a\n * surface can say which answers are the site's own rather than inferring it\n * by comparing values — two levels that happen to agree are still two levels.\n *\n * BOTH refs are held at null until their id is known, never addressed as\n * `orgs/-pending-` or `hosts/-pending-` (AGL-1440). `pluginSettings` is\n * member-gated at both scopes, so a sentinel id is a guaranteed permission\n * denial on every mount rather than a read that might succeed — the\n * anti-pattern `use-org-plan.ts` documents removing (AGL-1064). A null ref\n * issues nothing and holds `status` at `'loading'`, which is already this\n * hook's contract while the answer is unknown.\n *\n * `ready` needs BOTH reads, and needs both to have SUCCEEDED (AGL-1066).\n * Answering ready off the org read alone would hand a caller the workspace's\n * value as though it were this site's, which is the exact failure the site\n * layer exists to prevent — and answering it off a refused read would hand\n * them schema defaults as though they were stored settings.\n */\nexport function useSitePluginConfig(\n  orgId: string | null | undefined,\n  hostId: string | null | undefined,\n  pluginId: string,\n): { config: Record<string, unknown>; overrides: string[]; ready: boolean } {\n  const firestore = useFirestore()\n  const { data: org, status: orgStatus } = useFirestoreDoc<\n    Record<string, unknown>\n  >(\n    () =>\n      orgId ? doc(firestore, 'orgs', orgId, 'pluginSettings', pluginId) : null,\n    [firestore, orgId, pluginId],\n  )\n  const { data: host, status: hostStatus } = useFirestoreDoc<\n    Record<string, unknown>\n  >(\n    () =>\n      hostId\n        ? doc(firestore, 'hosts', hostId, 'pluginSettings', pluginId)\n        : null,\n    [firestore, hostId, pluginId],\n  )\n  const resolved = useMemo(() => {\n    const schema = getPluginConfigSchema(pluginId)\n    // Without a registered schema there is no field list to layer by, so the\n    // site's raw document simply narrows the workspace's — the same degrade\n    // `usePluginConfig` makes, one level deeper.\n    if (!schema) {\n      return {\n        config: { ...(org ?? {}), ...(host ?? {}) },\n        overrides: Object.keys(host ?? {}),\n      }\n    }\n    return {\n      config: resolvePluginConfig(schema, {\n        org: org ?? null,\n        host: host ?? null,\n      }),\n      overrides: pluginConfigOverrides(schema, host ?? null),\n    }\n  }, [pluginId, org, host])\n  return {\n    ...resolved,\n    ready: orgStatus === 'success' && hostStatus === 'success',\n  }\n}\n\nexport default usePluginConfig\n"],"names":["getPluginConfigSchema","mergePluginConfig","pluginConfigOverrides","resolvePluginConfig","doc","useMemo","useFirestore","useFirestoreDoc","usePluginConfig","orgId","pluginId","firestore","data","status","config","schema","ready","useSitePluginConfig","hostId","org","orgStatus","host","hostStatus","resolved","overrides","Object","keys"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GACD;;AAEA,SACEA,qBAAqB,EACrBC,iBAAiB,EACjBC,qBAAqB,EACrBC,mBAAmB,QACd,eAAc;AACrB,SAASC,GAAG,QAAQ,qBAAoB;AACxC,SAASC,OAAO,QAAQ,QAAO;AAC/B,SAASC,YAAY,QAAQ,kCAA8B;AAC3D,SAASC,eAAe,QAAQ,yBAAqB;AAErD;;;;;;CAMC,GACD,OAAO,SAASC,gBACdC,KAAgC,EAChCC,QAAgB;IAEhB,MAAMC,YAAYL;IAClB,4DAA4D;IAC5D,wEAAwE;IACxE,uEAAuE;IACvE,wEAAwE;IACxE,yEAAyE;IACzE,yEAAyE;IACzE,yBAAyB;IACzB,MAAM,EAAEM,IAAI,EAAEC,MAAM,EAAE,GAAGN,gBACvB,IACEE,QACIL,IAAIO,WAAW,QAAQF,OAAO,kBAAkBC,YAChD,MACN;QAACC;QAAWF;QAAOC;KAAS;IAE9B,MAAMI,SAAST,QAAQ;QACrB,MAAMU,SAASf,sBAAsBU;QACrC,IAAI,CAACK,QAAQ,OAAQH,eAAAA,OAAoC,CAAC;QAC1D,OAAOX,kBAAkBc,QAAQH,eAAAA,OAAQ;IAC3C,GAAG;QAACF;QAAUE;KAAK;IACnB,2EAA2E;IAC3E,4EAA4E;IAC5E,2EAA2E;IAC3E,OAAO;QAAEE;QAAQE,OAAOH,WAAW;IAAU;AAC/C;AAEA;;;;;;;;;;;;;;;;;;;;CAoBC,GACD,OAAO,SAASI,oBACdR,KAAgC,EAChCS,MAAiC,EACjCR,QAAgB;IAEhB,MAAMC,YAAYL;IAClB,MAAM,EAAEM,MAAMO,GAAG,EAAEN,QAAQO,SAAS,EAAE,GAAGb,gBAGvC,IACEE,QAAQL,IAAIO,WAAW,QAAQF,OAAO,kBAAkBC,YAAY,MACtE;QAACC;QAAWF;QAAOC;KAAS;IAE9B,MAAM,EAAEE,MAAMS,IAAI,EAAER,QAAQS,UAAU,EAAE,GAAGf,gBAGzC,IACEW,SACId,IAAIO,WAAW,SAASO,QAAQ,kBAAkBR,YAClD,MACN;QAACC;QAAWO;QAAQR;KAAS;IAE/B,MAAMa,WAAWlB,QAAQ;QACvB,MAAMU,SAASf,sBAAsBU;QACrC,yEAAyE;QACzE,wEAAwE;QACxE,6CAA6C;QAC7C,IAAI,CAACK,QAAQ;YACX,OAAO;gBACLD,QAAQ,aAAMK,cAAAA,MAAO,CAAC,GAAQE,eAAAA,OAAQ,CAAC;gBACvCG,WAAWC,OAAOC,IAAI,CAACL,eAAAA,OAAQ,CAAC;YAClC;QACF;QACA,OAAO;YACLP,QAAQX,oBAAoBY,QAAQ;gBAClCI,GAAG,EAAEA,cAAAA,MAAO;gBACZE,IAAI,EAAEA,eAAAA,OAAQ;YAChB;YACAG,WAAWtB,sBAAsBa,QAAQM,eAAAA,OAAQ;QACnD;IACF,GAAG;QAACX;QAAUS;QAAKE;KAAK;IACxB,OAAO,aACFE;QACHP,OAAOI,cAAc,aAAaE,eAAe;;AAErD;AAEA,eAAed,gBAAe"}

package/src/lib/hooks/use-scope-tokens.d.ts

@@ -0,0 +1,28 @@
+export interface ScopeTokensState {
+    /** The caller's read set, for `array-contains-any` (AGL-1037). */
+    tokens: string[];
+    /** Org-wide members read everything and need no query filter. */
+    orgWide: boolean;
+    loaded: boolean;
+}
+/**
+ * The signed-in user's scope tokens in an org (AGL-1044/1045).
+ *
+ * This is NOT a UI-gating convenience — it is required for correctness.
+ * Under AGL-1041/1042 the rules evaluate per document on a LIST, and
+ * Firestore rejects the WHOLE query if any candidate would fail. So a
+ * scoped collaborator's unfiltered `collection(...)` read comes back
+ * `permission-denied`, not filtered: without the matching
+ * `array-contains-any` constraint the page does not show less, it shows
+ * an error.
+ *
+ * Org-wide members deliberately get `orgWide: true` and no filter. Adding
+ * one would cost them a composite index for no benefit, and would silently
+ * hide any doc whose `visibleTo` the backfill has not reached.
+ *
+ * Defaults to org-wide while loading: the rules are the enforcement point,
+ * and guessing "scoped" before the member doc arrives would flash an empty
+ * library at people who can see everything.
+ */
+export declare function useScopeTokens(orgId: string | undefined): ScopeTokensState;
+export default useScopeTokens;

package/src/lib/hooks/use-scope-tokens.js

@@ -0,0 +1,100 @@
+'use client';
+import { _ as _extends } from "@swc/helpers/_/_extends";
+/**
+ * @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 { isOrgWideMember, memberScopeTokens, ORG_SCOPE_TOKEN } from "@aglyn/aglyn";
+import { doc, getDoc } from "firebase/firestore";
+import { useEffect, useState } from "react";
+import { useFirestore, useUser } from "./firebase/firebase-services.js";
+/**
+ * The signed-in user's scope tokens in an org (AGL-1044/1045).
+ *
+ * This is NOT a UI-gating convenience — it is required for correctness.
+ * Under AGL-1041/1042 the rules evaluate per document on a LIST, and
+ * Firestore rejects the WHOLE query if any candidate would fail. So a
+ * scoped collaborator's unfiltered `collection(...)` read comes back
+ * `permission-denied`, not filtered: without the matching
+ * `array-contains-any` constraint the page does not show less, it shows
+ * an error.
+ *
+ * Org-wide members deliberately get `orgWide: true` and no filter. Adding
+ * one would cost them a composite index for no benefit, and would silently
+ * hide any doc whose `visibleTo` the backfill has not reached.
+ *
+ * Defaults to org-wide while loading: the rules are the enforcement point,
+ * and guessing "scoped" before the member doc arrives would flash an empty
+ * library at people who can see everything.
+ */ export function useScopeTokens(orgId) {
+    const { data: user } = useUser();
+    const firestore = useFirestore();
+    const [state, setState] = useState({
+        tokens: [
+            ORG_SCOPE_TOKEN
+        ],
+        orgWide: true,
+        loaded: false
+    });
+    useEffect(()=>{
+        const uid = user == null ? void 0 : user.uid;
+        if (!uid || !orgId) {
+            setState({
+                tokens: [
+                    ORG_SCOPE_TOKEN
+                ],
+                orgWide: true,
+                loaded: Boolean(uid)
+            });
+            return;
+        }
+        let cancelled = false;
+        getDoc(doc(firestore, 'orgs', orgId, 'members', uid)).then((snapshot)=>{
+            if (cancelled) return;
+            const member = snapshot.exists() ? _extends({
+                $id: uid
+            }, snapshot.data()) : undefined;
+            // `memberScopeTokens` owns the "stored projection, else recompute"
+            // rule so the client and every Admin-SDK gate answer it the same
+            // way — a member doc the AGL-1040 backfill has not reached must
+            // still resolve to what `grantHostAccess` would have stamped.
+            setState({
+                tokens: memberScopeTokens(member),
+                orgWide: isOrgWideMember(member),
+                loaded: true
+            });
+        }).catch(()=>{
+            if (!cancelled) {
+                setState({
+                    tokens: [
+                        ORG_SCOPE_TOKEN
+                    ],
+                    orgWide: true,
+                    loaded: true
+                });
+            }
+        });
+        return ()=>{
+            cancelled = true;
+        };
+    }, [
+        firestore,
+        orgId,
+        user
+    ]);
+    return state;
+}
+export default useScopeTokens;
+
+//# sourceMappingURL=use-scope-tokens.js.map

package/src/lib/hooks/use-scope-tokens.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../../libs/tenant/feature/instance/src/lib/hooks/use-scope-tokens.ts"],"sourcesContent":["'use client'\n\n/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport {\n  isOrgWideMember,\n  memberScopeTokens,\n  ORG_SCOPE_TOKEN,\n  type AglynOrgMember,\n} from '@aglyn/aglyn'\nimport { doc, getDoc } from 'firebase/firestore'\nimport { useEffect, useState } from 'react'\nimport { useFirestore, useUser } from './firebase/firebase-services'\n\nexport interface ScopeTokensState {\n  /** The caller's read set, for `array-contains-any` (AGL-1037). */\n  tokens: string[]\n  /** Org-wide members read everything and need no query filter. */\n  orgWide: boolean\n  loaded: boolean\n}\n\n/**\n * The signed-in user's scope tokens in an org (AGL-1044/1045).\n *\n * This is NOT a UI-gating convenience — it is required for correctness.\n * Under AGL-1041/1042 the rules evaluate per document on a LIST, and\n * Firestore rejects the WHOLE query if any candidate would fail. So a\n * scoped collaborator's unfiltered `collection(...)` read comes back\n * `permission-denied`, not filtered: without the matching\n * `array-contains-any` constraint the page does not show less, it shows\n * an error.\n *\n * Org-wide members deliberately get `orgWide: true` and no filter. Adding\n * one would cost them a composite index for no benefit, and would silently\n * hide any doc whose `visibleTo` the backfill has not reached.\n *\n * Defaults to org-wide while loading: the rules are the enforcement point,\n * and guessing \"scoped\" before the member doc arrives would flash an empty\n * library at people who can see everything.\n */\nexport function useScopeTokens(orgId: string | undefined): ScopeTokensState {\n  const { data: user } = useUser()\n  const firestore = useFirestore()\n  const [state, setState] = useState<ScopeTokensState>({\n    tokens: [ORG_SCOPE_TOKEN],\n    orgWide: true,\n    loaded: false,\n  })\n\n  useEffect(() => {\n    const uid = (user as { uid?: string } | undefined)?.uid\n    if (!uid || !orgId) {\n      setState({ tokens: [ORG_SCOPE_TOKEN], orgWide: true, loaded: Boolean(uid) })\n      return\n    }\n    let cancelled = false\n    getDoc(doc(firestore, 'orgs', orgId, 'members', uid))\n      .then((snapshot) => {\n        if (cancelled) return\n        const member = snapshot.exists()\n          ? ({ $id: uid, ...snapshot.data() } as Partial<AglynOrgMember>)\n          : undefined\n        // `memberScopeTokens` owns the \"stored projection, else recompute\"\n        // rule so the client and every Admin-SDK gate answer it the same\n        // way — a member doc the AGL-1040 backfill has not reached must\n        // still resolve to what `grantHostAccess` would have stamped.\n        setState({\n          tokens: memberScopeTokens(member),\n          orgWide: isOrgWideMember(member),\n          loaded: true,\n        })\n      })\n      .catch(() => {\n        if (!cancelled) {\n          setState({ tokens: [ORG_SCOPE_TOKEN], orgWide: true, loaded: true })\n        }\n      })\n    return () => {\n      cancelled = true\n    }\n  }, [firestore, orgId, user])\n\n  return state\n}\n\nexport default useScopeTokens\n"],"names":["isOrgWideMember","memberScopeTokens","ORG_SCOPE_TOKEN","doc","getDoc","useEffect","useState","useFirestore","useUser","useScopeTokens","orgId","data","user","firestore","state","setState","tokens","orgWide","loaded","uid","Boolean","cancelled","then","snapshot","member","exists","$id","undefined","catch"],"mappings":"AAAA;;AAEA;;;;;;;;;;;;;;;CAeC,GAED,SACEA,eAAe,EACfC,iBAAiB,EACjBC,eAAe,QAEV,eAAc;AACrB,SAASC,GAAG,EAAEC,MAAM,QAAQ,qBAAoB;AAChD,SAASC,SAAS,EAAEC,QAAQ,QAAQ,QAAO;AAC3C,SAASC,YAAY,EAAEC,OAAO,QAAQ,kCAA8B;AAUpE;;;;;;;;;;;;;;;;;;CAkBC,GACD,OAAO,SAASC,eAAeC,KAAyB;IACtD,MAAM,EAAEC,MAAMC,IAAI,EAAE,GAAGJ;IACvB,MAAMK,YAAYN;IAClB,MAAM,CAACO,OAAOC,SAAS,GAAGT,SAA2B;QACnDU,QAAQ;YAACd;SAAgB;QACzBe,SAAS;QACTC,QAAQ;IACV;IAEAb,UAAU;QACR,MAAMc,MAAOP,wBAAD,AAACA,KAAuCO,GAAG;QACvD,IAAI,CAACA,OAAO,CAACT,OAAO;YAClBK,SAAS;gBAAEC,QAAQ;oBAACd;iBAAgB;gBAAEe,SAAS;gBAAMC,QAAQE,QAAQD;YAAK;YAC1E;QACF;QACA,IAAIE,YAAY;QAChBjB,OAAOD,IAAIU,WAAW,QAAQH,OAAO,WAAWS,MAC7CG,IAAI,CAAC,CAACC;YACL,IAAIF,WAAW;YACf,MAAMG,SAASD,SAASE,MAAM,KACzB;gBAAEC,KAAKP;eAAQI,SAASZ,IAAI,MAC7BgB;YACJ,mEAAmE;YACnE,iEAAiE;YACjE,gEAAgE;YAChE,8DAA8D;YAC9DZ,SAAS;gBACPC,QAAQf,kBAAkBuB;gBAC1BP,SAASjB,gBAAgBwB;gBACzBN,QAAQ;YACV;QACF,GACCU,KAAK,CAAC;YACL,IAAI,CAACP,WAAW;gBACdN,SAAS;oBAAEC,QAAQ;wBAACd;qBAAgB;oBAAEe,SAAS;oBAAMC,QAAQ;gBAAK;YACpE;QACF;QACF,OAAO;YACLG,YAAY;QACd;IACF,GAAG;QAACR;QAAWH;QAAOE;KAAK;IAE3B,OAAOE;AACT;AAEA,eAAeL,eAAc"}

package/src/lib/hooks/use-screen-version.d.ts

@@ -0,0 +1,33 @@
+/**
+ * @license
+ * Copyright 2022 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import type * as Aglyn from '@aglyn/aglyn';
+import type { DocumentReference } from 'firebase/firestore';
+import { type FirestoreDocOptions } from './firebase/firebase-services';
+export declare const useScreenVersionRef: ({ hostId, screenId, versionId }: {
+    hostId: string;
+    screenId: string;
+    versionId: string;
+}) => DocumentReference<Aglyn.AglynScreenVersion>;
+export declare const useScreenVersion: (data: {
+    screenId: string;
+    versionId: string;
+    hostId: string;
+}, options?: FirestoreDocOptions<Aglyn.AglynScreenVersion>) => {
+    doc: import("./firebase/firebase-services").ObservableStatus<Aglyn.AglynScreenVersion>;
+    setDoc: import("./helpers/use-modify-doc-callback").ModifyDocCallback<Aglyn.AglynScreenVersion>;
+};
+export default useScreenVersion;

package/src/lib/hooks/use-screen-version.js

@@ -0,0 +1,65 @@
+/**
+ * @license
+ * Copyright 2022 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.
+ */ // A TYPE-only namespace: every `Aglyn.` reference below is a type, and held
+// as a VALUE the namespace pins every module the barrel reaches into the
+// console shell that renders these hooks. `import type` erases instead.
+import { _ as _extends } from "@swc/helpers/_/_extends";
+import { _ as _object_without_properties_loose } from "@swc/helpers/_/_object_without_properties_loose";
+import { compress, decompress } from "@aglyn/aglyn";
+import { Timestamp } from "@aglyn/shared-util-timestamp";
+import { Bytes, doc } from "firebase/firestore";
+import { useFirestore } from "./firebase/firebase-services.js";
+import useDoc from "./helpers/use-doc.js";
+export const useScreenVersionRef = ({ hostId, screenId, versionId })=>{
+    const firestore = useFirestore();
+    const ref = doc(firestore, 'hosts', hostId, 'screens', screenId, 'versions', versionId);
+    return ref.withConverter({
+        toFirestore (data) {
+            const { $id } = data, rest = _object_without_properties_loose(data, [
+                "$id"
+            ]);
+            // Only emit `nodes` when the write actually carries them (AGL-1250).
+            // Compressing `rest?.nodes || {}` unconditionally meant a partial
+            // `setDoc(…, {merge: true})` — one that set some other field —
+            // shipped an EMPTY compressed map, and merge faithfully merged that
+            // emptiness over the real tree, silently destroying the document.
+            if ((rest == null ? void 0 : rest.nodes) === undefined) return _extends({}, rest, {
+                updatedAt: Timestamp.now()
+            });
+            const nodes = rest.nodes instanceof Bytes ? rest.nodes : Bytes.fromUint8Array(compress(rest.nodes));
+            return _extends({}, rest, {
+                nodes,
+                updatedAt: Timestamp.now()
+            });
+        },
+        fromFirestore (snapshot, options) {
+            if (!snapshot.exists()) return undefined;
+            const data = snapshot.data(options);
+            if ((data == null ? void 0 : data.nodes) instanceof Bytes) {
+                return _extends({}, data, {
+                    nodes: decompress(data.nodes)
+                });
+            }
+            return data;
+        }
+    });
+};
+export const useScreenVersion = (data, options)=>{
+    return useDoc(useScreenVersionRef(data), options);
+};
+export default useScreenVersion;
+
+//# sourceMappingURL=use-screen-version.js.map

package/src/lib/hooks/use-screen-version.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../../libs/tenant/feature/instance/src/lib/hooks/use-screen-version.tsx"],"sourcesContent":["/**\n * @license\n * Copyright 2022 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\n// A TYPE-only namespace: every `Aglyn.` reference below is a type, and held\n// as a VALUE the namespace pins every module the barrel reaches into the\n// console shell that renders these hooks. `import type` erases instead.\nimport type * as Aglyn from '@aglyn/aglyn'\nimport { compress, decompress } from '@aglyn/aglyn'\nimport { Timestamp } from '@aglyn/shared-util-timestamp'\nimport type { DocumentReference } from 'firebase/firestore'\nimport { Bytes, doc } from 'firebase/firestore'\nimport { useFirestore, type FirestoreDocOptions } from './firebase/firebase-services'\nimport useDoc from './helpers/use-doc'\n\nexport const useScreenVersionRef = ({ hostId, screenId, versionId }: { hostId: string; screenId: string; versionId: string }) => {\n  const firestore = useFirestore()\n  const ref = doc(\n    firestore,\n    'hosts',\n    hostId,\n    'screens',\n    screenId,\n    'versions',\n    versionId,\n  )\n  return ref.withConverter({\n    toFirestore(data) {\n      const { $id, ...rest } = data\n      // Only emit `nodes` when the write actually carries them (AGL-1250).\n      // Compressing `rest?.nodes || {}` unconditionally meant a partial\n      // `setDoc(…, {merge: true})` — one that set some other field —\n      // shipped an EMPTY compressed map, and merge faithfully merged that\n      // emptiness over the real tree, silently destroying the document.\n      if (rest?.nodes === undefined) return { ...rest, updatedAt: Timestamp.now() }\n      const nodes = rest.nodes instanceof Bytes\n        ? rest.nodes\n        : Bytes.fromUint8Array(compress(rest.nodes))\n      return { ...rest, nodes, updatedAt: Timestamp.now() }\n    },\n    fromFirestore(snapshot, options) {\n      if (!snapshot.exists()) return undefined\n      const data = snapshot.data(options)\n      if (data?.nodes instanceof Bytes) {\n        return { ...data, nodes: decompress(data.nodes) } as Aglyn.AglynScreenVersion\n      }\n      return data as Aglyn.AglynScreenVersion\n    },\n  }) as DocumentReference<Aglyn.AglynScreenVersion>\n}\n\nexport const useScreenVersion = (\n  data: {\n    screenId: string\n    versionId: string\n    hostId: string\n  },\n  options?: FirestoreDocOptions<Aglyn.AglynScreenVersion>,\n) => {\n  return useDoc(useScreenVersionRef(data), options)\n}\n\nexport default useScreenVersion\n"],"names":["compress","decompress","Timestamp","Bytes","doc","useFirestore","useDoc","useScreenVersionRef","hostId","screenId","versionId","firestore","ref","withConverter","toFirestore","data","$id","rest","nodes","undefined","updatedAt","now","fromUint8Array","fromFirestore","snapshot","options","exists","useScreenVersion"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED,4EAA4E;AAC5E,yEAAyE;AACzE,wEAAwE;;;AAExE,SAASA,QAAQ,EAAEC,UAAU,QAAQ,eAAc;AACnD,SAASC,SAAS,QAAQ,+BAA8B;AAExD,SAASC,KAAK,EAAEC,GAAG,QAAQ,qBAAoB;AAC/C,SAASC,YAAY,QAAkC,kCAA8B;AACrF,OAAOC,YAAY,uBAAmB;AAEtC,OAAO,MAAMC,sBAAsB,CAAC,EAAEC,MAAM,EAAEC,QAAQ,EAAEC,SAAS,EAA2D;IAC1H,MAAMC,YAAYN;IAClB,MAAMO,MAAMR,IACVO,WACA,SACAH,QACA,WACAC,UACA,YACAC;IAEF,OAAOE,IAAIC,aAAa,CAAC;QACvBC,aAAYC,IAAI;YACd,MAAM,EAAEC,GAAG,EAAW,GAAGD,MAATE,wCAASF;;;YACzB,qEAAqE;YACrE,kEAAkE;YAClE,+DAA+D;YAC/D,oEAAoE;YACpE,kEAAkE;YAClE,IAAIE,CAAAA,wBAAAA,KAAMC,KAAK,MAAKC,WAAW,OAAO,aAAKF;gBAAMG,WAAWlB,UAAUmB,GAAG;;YACzE,MAAMH,QAAQD,KAAKC,KAAK,YAAYf,QAChCc,KAAKC,KAAK,GACVf,MAAMmB,cAAc,CAACtB,SAASiB,KAAKC,KAAK;YAC5C,OAAO,aAAKD;gBAAMC;gBAAOE,WAAWlB,UAAUmB,GAAG;;QACnD;QACAE,eAAcC,QAAQ,EAAEC,OAAO;YAC7B,IAAI,CAACD,SAASE,MAAM,IAAI,OAAOP;YAC/B,MAAMJ,OAAOS,SAAST,IAAI,CAACU;YAC3B,IAAIV,CAAAA,wBAAAA,KAAMG,KAAK,aAAYf,OAAO;gBAChC,OAAO,aAAKY;oBAAMG,OAAOjB,WAAWc,KAAKG,KAAK;;YAChD;YACA,OAAOH;QACT;IACF;AACF,EAAC;AAED,OAAO,MAAMY,mBAAmB,CAC9BZ,MAKAU;IAEA,OAAOnB,OAAOC,oBAAoBQ,OAAOU;AAC3C,EAAC;AAED,eAAeE,iBAAgB"}

package/src/lib/hooks/use-screen.d.ts

@@ -0,0 +1,68 @@
+/**
+ * @license
+ * Copyright 2022 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import type * as Aglyn from '@aglyn/aglyn';
+import { Timestamp } from '@aglyn/shared-util-timestamp';
+import { type FirestoreDocOptions } from './firebase/firebase-services';
+export declare const useScreenRef: ({ hostId, screenId }: {
+    hostId: Aglyn.HostUid;
+    screenId: Aglyn.ScreenUid;
+}) => import("@firebase/firestore").DocumentReference<Aglyn.AglynScreen, {
+    updatedAt: Timestamp;
+    hostId?: Aglyn.HostUid;
+    parentId?: Aglyn.ScreenUid;
+    slug?: Aglyn.ScreenSlug;
+    order?: number;
+    versionId?: Aglyn.VersionUid;
+    publishSchedule?: Aglyn.PublishSchedule;
+    protection?: {
+        passwordHash?: string;
+    };
+    locale?: string;
+    localeVariants?: Record<string, Aglyn.ScreenUid>;
+    status?: Aglyn.HostScreenStatus;
+    createdAt?: import("@aglyn/shared-util-timestamp").ITimestamp;
+    publishedAt?: import("@aglyn/shared-util-timestamp").ITimestamp;
+    deletedAt?: import("@aglyn/shared-util-timestamp").ITimestamp;
+    displayName?: string;
+    nameLower?: string;
+    description?: string;
+    seo?: {
+        title?: string;
+        description?: string;
+        breadcrumb?: string;
+        image?: string;
+        imageWidth?: number;
+        imageHeight?: number;
+        imageAlt?: string;
+    };
+    schedule?: {
+        startAt?: import("@aglyn/shared-util-timestamp").ITimestamp;
+        endAt?: import("@aglyn/shared-util-timestamp").ITimestamp;
+        next?: Aglyn.VersionUid;
+        previous?: Aglyn.VersionUid;
+    };
+    visibility?: Aglyn.HostScreenVisibility;
+    layoutId?: Aglyn.LayoutUid;
+}>;
+export declare const useScreen: (data: {
+    hostId: Aglyn.HostUid;
+    screenId: Aglyn.ScreenUid;
+}, options?: FirestoreDocOptions<Aglyn.AglynScreen>) => {
+    doc: import("./firebase/firebase-services").ObservableStatus<Aglyn.AglynScreen>;
+    setDoc: import("./helpers/use-modify-doc-callback").ModifyDocCallback<Aglyn.AglynScreen>;
+};
+export default useScreen;