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

package/src/lib/hooks/sorted-collection-window.d.ts

@@ -0,0 +1,207 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { type Query } from 'firebase/firestore';
+/**
+ * A paged list SORTED BY A FIELD that still drops nothing (AGL-2853).
+ *
+ * ## The trap a field sort walks into
+ *
+ * `orderBy(field)` matches only documents that HAVE the field. A document
+ * without it is not sorted last, it is not in the result at all, so a list
+ * ordered that way does not mis-order the documents a writer left the field
+ * off — it hides them, and the rows it does show look complete. That is why
+ * `collectionPage` orders on the document name, which no document can lack.
+ *
+ * Content entries are the case that made the name order untenable: a
+ * changelog read in id order puts its newest release on whichever page the
+ * random id lands. And they carry exactly the gaps the trap feeds on —
+ * unpublishing deletes `publishedAt`, and a restored archive has no
+ * `createdAt`. Ordering on either hides every draft or every import.
+ *
+ * ## Two segments, one sequence
+ *
+ * The list is split by whether a document carries the sort field, and each
+ * half is walked by a query that can see all of it:
+ *
+ *   KEYED    `orderBy(field, dir), orderBy(documentId(), dir)` — every document
+ *            that has the field, including an explicit `null`, in the
+ *            requested order. The name is the tiebreak, so the order is total
+ *            and a page boundary cannot fall between two equal values
+ *            differently on two reads.
+ *   UNKEYED  `orderBy(documentId())` over the same base, kept to the documents
+ *            that LACK the field. Firestore cannot query for an absent field,
+ *            so this segment is a scan: it reads the base in name order and
+ *            keeps what the keyed walk could not see.
+ *
+ * The two are disjoint and together are the whole base, so the list is the
+ * keyed segment followed by the unkeyed one — documents missing the sorted
+ * value come after every document that has one, in both directions. Every
+ * page is a slice of that one sequence, which is what keeps a document from
+ * being skipped or shown twice across a page boundary.
+ *
+ * ## What it costs
+ *
+ * The keyed walk is a window like `usePagedCollection`'s: one page plus a
+ * probe row, widened a page at a time. The scan opens only once the keyed
+ * walk has come back SHORT of its window — a server-confirmed fact that the
+ * keyed segment ends on this page — so the first pages of a long list cost
+ * exactly what an unsorted list costs. The scan starts at the number of rows
+ * the window still needs and doubles while it holds its whole limit without
+ * finding them; it stops the moment it has enough or reads past the end of the
+ * base. Its worst case is the base itself, reached only on the last pages.
+ *
+ * A base narrowed by an equality predicate narrows the scan with it, which is
+ * what keeps a filtered view cheap: a status filter scans only that status.
+ *
+ * ## Why the planner is pure
+ *
+ * `planKeyedSegment` and `planSortedWindow` are the whole decision — which
+ * limits to ask for, when the scan widens, which rows the page shows and
+ * whether another page exists. The hook adapts them to live listeners; the
+ * emulator spec drives the same two functions against a real Firestore, so
+ * the proof that nothing is dropped runs the code the console runs rather
+ * than a copy of it.
+ */
+export type CollectionSortDirection = 'asc' | 'desc';
+/** A field to sort a collection by, and which way. */
+export interface CollectionSort {
+    /** A Firestore field path. Dotted paths address nested fields. */
+    field: string;
+    direction: CollectionSortDirection;
+}
+/**
+ * The KEYED segment: every document of `base` that carries `sort.field`, in
+ * that order, one window at a time.
+ *
+ * A field `base` already pins by EQUALITY holds one value across every
+ * matching document, so ordering on it orders nothing and neither direction
+ * means anything — the walk orders by the document name, ascending, which is
+ * the shape the field's automatic index serves. Every document of such a base
+ * carries the field, so no unkeyed segment exists; see `sortFieldIsTotal`.
+ */
+export declare function sortedKeyedQuery(base: Query, sort: CollectionSort, pageLimit: number, equalityFields?: readonly string[]): Query;
+/**
+ * The scan behind the UNKEYED segment: `base` in document-name order.
+ *
+ * Always ascending. The names are generated ids, so neither direction means
+ * anything to a reader, and an equality predicate followed by an ascending
+ * name order is the one shape every automatic index serves.
+ */
+export declare function sortedUnkeyedQuery(base: Query, scanLimit: number): Query;
+/**
+ * Whether every document `base` matches carries the sort field, because
+ * `base` pins that field by equality. Such a base has no unkeyed segment.
+ */
+export declare function sortFieldIsTotal(sort: CollectionSort, equalityFields?: readonly string[]): boolean;
+/**
+ * Whether a row read off a snapshot LACKS `field` — the membership test of
+ * the unkeyed segment, and the exact complement of what `orderBy(field)`
+ * returns.
+ *
+ * `undefined` and nothing else. Firestore cannot store `undefined`, so a
+ * missing key is the only way to read one; an explicit `null` is a stored
+ * value, indexed and returned by the keyed walk, and must not be read twice.
+ */
+export declare function lacksSortField(row: unknown, field: string): boolean;
+/** What the keyed read has established about the window. */
+export interface KeyedSegmentPlan {
+    /** Rows before the page being read. */
+    offset: number;
+    /** Every page up to and including the one being read. */
+    windowSize: number;
+    /** The keyed walk's limit: the window plus a single probe row. */
+    keyedLimit: number;
+    /**
+     * Rows the unkeyed segment must supply to fill the window and its probe —
+     * `0` until the server has confirmed the keyed walk ends inside the window.
+     */
+    tailNeeded: number;
+}
+/** The keyed read, as the planner needs to see it. */
+export interface KeyedSegmentInput<T> {
+    page: number;
+    pageSize: number;
+    /** The keyed rows read at this window's limit, or `undefined` if unread. */
+    keyed: readonly T[] | undefined;
+    /** The server has answered the keyed read — not only the local cache. */
+    keyedSettled: boolean;
+    /** See `sortFieldIsTotal`. */
+    keyedIsTotal: boolean;
+}
+/**
+ * The keyed half of the plan: the limit to ask for, and how many rows the
+ * scan owes the window.
+ *
+ * The scan is owed rows only when the keyed walk came back holding LESS than
+ * its limit, and only once the server said so. A cached answer can be short
+ * because the cache is, and opening a scan on it would pay to read documents
+ * the server's answer is about to render unnecessary.
+ */
+export declare function planKeyedSegment<T>(input: KeyedSegmentInput<T>): KeyedSegmentPlan;
+/**
+ * The limit the scan should be open at: `0` when no rows are owed, otherwise
+ * never less than it has already been widened to, so a keyed row arriving
+ * mid-scan does not re-open the scan one document narrower.
+ */
+export declare function sortedScanLimit(plan: KeyedSegmentPlan, widenedTo: number): number;
+/** Both reads, as the planner needs to see them. */
+export interface SortedWindowInput<T> extends KeyedSegmentInput<T> {
+    sort: CollectionSort;
+    /** The scan rows read at `scanLimit`, or `undefined` if unread. */
+    scan: readonly T[] | undefined;
+    /** The server has answered the scan — not only the local cache. */
+    scanSettled: boolean;
+    /** The limit `scan` was read at; `0` when no scan is open. */
+    scanLimit: number;
+    /** A row's document id, which dedupes the two segments. */
+    idOf: (row: T) => string;
+}
+/** The window a list renders. */
+export interface SortedWindow<T> extends KeyedSegmentPlan {
+    /**
+     * The limit the scan should be open at. Greater than the input's when the
+     * scan held its whole limit without finding the rows it owes, which is the
+     * signal to widen it.
+     */
+    scanLimit: number;
+    /** The page being read. Never the probe row. */
+    rows: T[];
+    /** A further page exists. A fact from the probe row, not a comparison. */
+    hasMore: boolean;
+    /**
+     * `rows` and `hasMore` are the server's answer for this window: the keyed
+     * walk is confirmed, and the scan is confirmed at its final limit whenever
+     * the window needed one.
+     */
+    settled: boolean;
+    /** The keyed rows then the unkeyed rows, deduped — probe row included. */
+    ordered: T[];
+}
+/**
+ * The page, from the keyed rows and the scan rows.
+ *
+ * The scan is widened only on a CONFIRMED short read: it held its whole limit
+ * (so the base continues past it) and kept fewer rows than the window owes.
+ * A scan that read past the end of the base has found every document the
+ * keyed walk cannot see, however few, and is done.
+ *
+ * Rows are deduped by id across the two segments. A document gaining or
+ * losing the sort field reaches the two listeners separately, and for the
+ * moment between their snapshots one of them still describes it the old way;
+ * the keyed copy wins, because the keyed walk is the one that orders it.
+ */
+export declare function planSortedWindow<T>(input: SortedWindowInput<T>): SortedWindow<T>;

package/src/lib/hooks/sorted-collection-window.js

@@ -0,0 +1,150 @@
+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 { documentId, limit, orderBy, query } from "firebase/firestore";
+/**
+ * The KEYED segment: every document of `base` that carries `sort.field`, in
+ * that order, one window at a time.
+ *
+ * A field `base` already pins by EQUALITY holds one value across every
+ * matching document, so ordering on it orders nothing and neither direction
+ * means anything — the walk orders by the document name, ascending, which is
+ * the shape the field's automatic index serves. Every document of such a base
+ * carries the field, so no unkeyed segment exists; see `sortFieldIsTotal`.
+ */ export function sortedKeyedQuery(base, sort, pageLimit, equalityFields = []) {
+    if (equalityFields.includes(sort.field)) {
+        return query(base, orderBy(documentId()), limit(pageLimit));
+    }
+    return query(base, orderBy(sort.field, sort.direction), orderBy(documentId(), sort.direction), limit(pageLimit));
+}
+/**
+ * The scan behind the UNKEYED segment: `base` in document-name order.
+ *
+ * Always ascending. The names are generated ids, so neither direction means
+ * anything to a reader, and an equality predicate followed by an ascending
+ * name order is the one shape every automatic index serves.
+ */ export function sortedUnkeyedQuery(base, scanLimit) {
+    return query(base, orderBy(documentId()), limit(scanLimit));
+}
+/**
+ * Whether every document `base` matches carries the sort field, because
+ * `base` pins that field by equality. Such a base has no unkeyed segment.
+ */ export function sortFieldIsTotal(sort, equalityFields = []) {
+    return equalityFields.includes(sort.field);
+}
+/**
+ * Whether a row read off a snapshot LACKS `field` — the membership test of
+ * the unkeyed segment, and the exact complement of what `orderBy(field)`
+ * returns.
+ *
+ * `undefined` and nothing else. Firestore cannot store `undefined`, so a
+ * missing key is the only way to read one; an explicit `null` is a stored
+ * value, indexed and returned by the keyed walk, and must not be read twice.
+ */ export function lacksSortField(row, field) {
+    let value = row;
+    for (const key of field.split('.')){
+        if (value === null || typeof value !== 'object') return true;
+        value = value[key];
+    }
+    return value === undefined;
+}
+/**
+ * The keyed half of the plan: the limit to ask for, and how many rows the
+ * scan owes the window.
+ *
+ * The scan is owed rows only when the keyed walk came back holding LESS than
+ * its limit, and only once the server said so. A cached answer can be short
+ * because the cache is, and opening a scan on it would pay to read documents
+ * the server's answer is about to render unnecessary.
+ */ export function planKeyedSegment(input) {
+    var _ref;
+    var _input_keyed;
+    const offset = input.page * input.pageSize;
+    const windowSize = offset + input.pageSize;
+    const keyedLimit = windowSize + 1;
+    const held = (_ref = (_input_keyed = input.keyed) == null ? void 0 : _input_keyed.length) != null ? _ref : 0;
+    const exhausted = input.keyed !== undefined && input.keyedSettled && held < keyedLimit;
+    return {
+        offset,
+        windowSize,
+        keyedLimit,
+        tailNeeded: exhausted && !input.keyedIsTotal ? keyedLimit - held : 0
+    };
+}
+/**
+ * The limit the scan should be open at: `0` when no rows are owed, otherwise
+ * never less than it has already been widened to, so a keyed row arriving
+ * mid-scan does not re-open the scan one document narrower.
+ */ export function sortedScanLimit(plan, widenedTo) {
+    return plan.tailNeeded > 0 ? Math.max(widenedTo, plan.tailNeeded) : 0;
+}
+/**
+ * The page, from the keyed rows and the scan rows.
+ *
+ * The scan is widened only on a CONFIRMED short read: it held its whole limit
+ * (so the base continues past it) and kept fewer rows than the window owes.
+ * A scan that read past the end of the base has found every document the
+ * keyed walk cannot see, however few, and is done.
+ *
+ * Rows are deduped by id across the two segments. A document gaining or
+ * losing the sort field reaches the two listeners separately, and for the
+ * moment between their snapshots one of them still describes it the old way;
+ * the keyed copy wins, because the keyed walk is the one that orders it.
+ */ export function planSortedWindow(input) {
+    var _input_keyed;
+    const plan = planKeyedSegment(input);
+    const keyed = (_input_keyed = input.keyed) != null ? _input_keyed : [];
+    const keyedSettled = input.keyed !== undefined && input.keyedSettled;
+    let scanLimit = 0;
+    let tail = [];
+    let tailSettled = true;
+    if (plan.tailNeeded > 0) {
+        var _ref;
+        const scanned = input.scanLimit > 0 ? input.scan : undefined;
+        const scanSettled = scanned !== undefined && input.scanSettled;
+        const scanExhausted = scanSettled && ((_ref = scanned == null ? void 0 : scanned.length) != null ? _ref : 0) < input.scanLimit;
+        tail = (scanned != null ? scanned : []).filter((row)=>lacksSortField(row, input.sort.field));
+        if (scanExhausted || scanSettled && tail.length >= plan.tailNeeded) {
+            scanLimit = input.scanLimit;
+        } else if (scanSettled) {
+            scanLimit = Math.max(input.scanLimit * 2, plan.tailNeeded);
+            tailSettled = false;
+        } else {
+            scanLimit = Math.max(input.scanLimit, plan.tailNeeded);
+            tailSettled = false;
+        }
+    }
+    const seen = new Set();
+    const ordered = [];
+    for (const row of [
+        ...keyed,
+        ...tail
+    ]){
+        const id = input.idOf(row);
+        if (seen.has(id)) continue;
+        seen.add(id);
+        ordered.push(row);
+    }
+    return _extends({}, plan, {
+        scanLimit,
+        rows: ordered.slice(plan.offset, plan.windowSize),
+        hasMore: ordered.length > plan.windowSize,
+        settled: keyedSettled && tailSettled,
+        ordered
+    });
+}
+
+//# sourceMappingURL=sorted-collection-window.js.map

package/src/lib/hooks/sorted-collection-window.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../../libs/tenant/feature/instance/src/lib/hooks/sorted-collection-window.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport {\n  documentId,\n  limit,\n  orderBy,\n  query,\n  type Query,\n} from 'firebase/firestore'\n\n/**\n * A paged list SORTED BY A FIELD that still drops nothing (AGL-2853).\n *\n * ## The trap a field sort walks into\n *\n * `orderBy(field)` matches only documents that HAVE the field. A document\n * without it is not sorted last, it is not in the result at all, so a list\n * ordered that way does not mis-order the documents a writer left the field\n * off — it hides them, and the rows it does show look complete. That is why\n * `collectionPage` orders on the document name, which no document can lack.\n *\n * Content entries are the case that made the name order untenable: a\n * changelog read in id order puts its newest release on whichever page the\n * random id lands. And they carry exactly the gaps the trap feeds on —\n * unpublishing deletes `publishedAt`, and a restored archive has no\n * `createdAt`. Ordering on either hides every draft or every import.\n *\n * ## Two segments, one sequence\n *\n * The list is split by whether a document carries the sort field, and each\n * half is walked by a query that can see all of it:\n *\n *   KEYED    `orderBy(field, dir), orderBy(documentId(), dir)` — every document\n *            that has the field, including an explicit `null`, in the\n *            requested order. The name is the tiebreak, so the order is total\n *            and a page boundary cannot fall between two equal values\n *            differently on two reads.\n *   UNKEYED  `orderBy(documentId())` over the same base, kept to the documents\n *            that LACK the field. Firestore cannot query for an absent field,\n *            so this segment is a scan: it reads the base in name order and\n *            keeps what the keyed walk could not see.\n *\n * The two are disjoint and together are the whole base, so the list is the\n * keyed segment followed by the unkeyed one — documents missing the sorted\n * value come after every document that has one, in both directions. Every\n * page is a slice of that one sequence, which is what keeps a document from\n * being skipped or shown twice across a page boundary.\n *\n * ## What it costs\n *\n * The keyed walk is a window like `usePagedCollection`'s: one page plus a\n * probe row, widened a page at a time. The scan opens only once the keyed\n * walk has come back SHORT of its window — a server-confirmed fact that the\n * keyed segment ends on this page — so the first pages of a long list cost\n * exactly what an unsorted list costs. The scan starts at the number of rows\n * the window still needs and doubles while it holds its whole limit without\n * finding them; it stops the moment it has enough or reads past the end of the\n * base. Its worst case is the base itself, reached only on the last pages.\n *\n * A base narrowed by an equality predicate narrows the scan with it, which is\n * what keeps a filtered view cheap: a status filter scans only that status.\n *\n * ## Why the planner is pure\n *\n * `planKeyedSegment` and `planSortedWindow` are the whole decision — which\n * limits to ask for, when the scan widens, which rows the page shows and\n * whether another page exists. The hook adapts them to live listeners; the\n * emulator spec drives the same two functions against a real Firestore, so\n * the proof that nothing is dropped runs the code the console runs rather\n * than a copy of it.\n */\n\nexport type CollectionSortDirection = 'asc' | 'desc'\n\n/** A field to sort a collection by, and which way. */\nexport interface CollectionSort {\n  /** A Firestore field path. Dotted paths address nested fields. */\n  field: string\n  direction: CollectionSortDirection\n}\n\n/**\n * The KEYED segment: every document of `base` that carries `sort.field`, in\n * that order, one window at a time.\n *\n * A field `base` already pins by EQUALITY holds one value across every\n * matching document, so ordering on it orders nothing and neither direction\n * means anything — the walk orders by the document name, ascending, which is\n * the shape the field's automatic index serves. Every document of such a base\n * carries the field, so no unkeyed segment exists; see `sortFieldIsTotal`.\n */\nexport function sortedKeyedQuery(\n  base: Query,\n  sort: CollectionSort,\n  pageLimit: number,\n  equalityFields: readonly string[] = [],\n): Query {\n  if (equalityFields.includes(sort.field)) {\n    return query(base, orderBy(documentId()), limit(pageLimit))\n  }\n  return query(\n    base,\n    orderBy(sort.field, sort.direction),\n    orderBy(documentId(), sort.direction),\n    limit(pageLimit),\n  )\n}\n\n/**\n * The scan behind the UNKEYED segment: `base` in document-name order.\n *\n * Always ascending. The names are generated ids, so neither direction means\n * anything to a reader, and an equality predicate followed by an ascending\n * name order is the one shape every automatic index serves.\n */\nexport function sortedUnkeyedQuery(base: Query, scanLimit: number): Query {\n  return query(base, orderBy(documentId()), limit(scanLimit))\n}\n\n/**\n * Whether every document `base` matches carries the sort field, because\n * `base` pins that field by equality. Such a base has no unkeyed segment.\n */\nexport function sortFieldIsTotal(\n  sort: CollectionSort,\n  equalityFields: readonly string[] = [],\n): boolean {\n  return equalityFields.includes(sort.field)\n}\n\n/**\n * Whether a row read off a snapshot LACKS `field` — the membership test of\n * the unkeyed segment, and the exact complement of what `orderBy(field)`\n * returns.\n *\n * `undefined` and nothing else. Firestore cannot store `undefined`, so a\n * missing key is the only way to read one; an explicit `null` is a stored\n * value, indexed and returned by the keyed walk, and must not be read twice.\n */\nexport function lacksSortField(row: unknown, field: string): boolean {\n  let value: unknown = row\n  for (const key of field.split('.')) {\n    if (value === null || typeof value !== 'object') return true\n    value = (value as Record<string, unknown>)[key]\n  }\n  return value === undefined\n}\n\n/** What the keyed read has established about the window. */\nexport interface KeyedSegmentPlan {\n  /** Rows before the page being read. */\n  offset: number\n  /** Every page up to and including the one being read. */\n  windowSize: number\n  /** The keyed walk's limit: the window plus a single probe row. */\n  keyedLimit: number\n  /**\n   * Rows the unkeyed segment must supply to fill the window and its probe —\n   * `0` until the server has confirmed the keyed walk ends inside the window.\n   */\n  tailNeeded: number\n}\n\n/** The keyed read, as the planner needs to see it. */\nexport interface KeyedSegmentInput<T> {\n  page: number\n  pageSize: number\n  /** The keyed rows read at this window's limit, or `undefined` if unread. */\n  keyed: readonly T[] | undefined\n  /** The server has answered the keyed read — not only the local cache. */\n  keyedSettled: boolean\n  /** See `sortFieldIsTotal`. */\n  keyedIsTotal: boolean\n}\n\n/**\n * The keyed half of the plan: the limit to ask for, and how many rows the\n * scan owes the window.\n *\n * The scan is owed rows only when the keyed walk came back holding LESS than\n * its limit, and only once the server said so. A cached answer can be short\n * because the cache is, and opening a scan on it would pay to read documents\n * the server's answer is about to render unnecessary.\n */\nexport function planKeyedSegment<T>(\n  input: KeyedSegmentInput<T>,\n): KeyedSegmentPlan {\n  const offset = input.page * input.pageSize\n  const windowSize = offset + input.pageSize\n  const keyedLimit = windowSize + 1\n  const held = input.keyed?.length ?? 0\n  const exhausted =\n    input.keyed !== undefined && input.keyedSettled && held < keyedLimit\n  return {\n    offset,\n    windowSize,\n    keyedLimit,\n    tailNeeded: exhausted && !input.keyedIsTotal ? keyedLimit - held : 0,\n  }\n}\n\n/**\n * The limit the scan should be open at: `0` when no rows are owed, otherwise\n * never less than it has already been widened to, so a keyed row arriving\n * mid-scan does not re-open the scan one document narrower.\n */\nexport function sortedScanLimit(\n  plan: KeyedSegmentPlan,\n  widenedTo: number,\n): number {\n  return plan.tailNeeded > 0 ? Math.max(widenedTo, plan.tailNeeded) : 0\n}\n\n/** Both reads, as the planner needs to see them. */\nexport interface SortedWindowInput<T> extends KeyedSegmentInput<T> {\n  sort: CollectionSort\n  /** The scan rows read at `scanLimit`, or `undefined` if unread. */\n  scan: readonly T[] | undefined\n  /** The server has answered the scan — not only the local cache. */\n  scanSettled: boolean\n  /** The limit `scan` was read at; `0` when no scan is open. */\n  scanLimit: number\n  /** A row's document id, which dedupes the two segments. */\n  idOf: (row: T) => string\n}\n\n/** The window a list renders. */\nexport interface SortedWindow<T> extends KeyedSegmentPlan {\n  /**\n   * The limit the scan should be open at. Greater than the input's when the\n   * scan held its whole limit without finding the rows it owes, which is the\n   * signal to widen it.\n   */\n  scanLimit: number\n  /** The page being read. Never the probe row. */\n  rows: T[]\n  /** A further page exists. A fact from the probe row, not a comparison. */\n  hasMore: boolean\n  /**\n   * `rows` and `hasMore` are the server's answer for this window: the keyed\n   * walk is confirmed, and the scan is confirmed at its final limit whenever\n   * the window needed one.\n   */\n  settled: boolean\n  /** The keyed rows then the unkeyed rows, deduped — probe row included. */\n  ordered: T[]\n}\n\n/**\n * The page, from the keyed rows and the scan rows.\n *\n * The scan is widened only on a CONFIRMED short read: it held its whole limit\n * (so the base continues past it) and kept fewer rows than the window owes.\n * A scan that read past the end of the base has found every document the\n * keyed walk cannot see, however few, and is done.\n *\n * Rows are deduped by id across the two segments. A document gaining or\n * losing the sort field reaches the two listeners separately, and for the\n * moment between their snapshots one of them still describes it the old way;\n * the keyed copy wins, because the keyed walk is the one that orders it.\n */\nexport function planSortedWindow<T>(\n  input: SortedWindowInput<T>,\n): SortedWindow<T> {\n  const plan = planKeyedSegment(input)\n  const keyed = input.keyed ?? []\n  const keyedSettled = input.keyed !== undefined && input.keyedSettled\n\n  let scanLimit = 0\n  let tail: readonly T[] = []\n  let tailSettled = true\n  if (plan.tailNeeded > 0) {\n    const scanned = input.scanLimit > 0 ? input.scan : undefined\n    const scanSettled = scanned !== undefined && input.scanSettled\n    const scanExhausted =\n      scanSettled && (scanned?.length ?? 0) < input.scanLimit\n    tail = (scanned ?? []).filter((row) =>\n      lacksSortField(row, input.sort.field),\n    )\n    if (scanExhausted || (scanSettled && tail.length >= plan.tailNeeded)) {\n      scanLimit = input.scanLimit\n    } else if (scanSettled) {\n      scanLimit = Math.max(input.scanLimit * 2, plan.tailNeeded)\n      tailSettled = false\n    } else {\n      scanLimit = Math.max(input.scanLimit, plan.tailNeeded)\n      tailSettled = false\n    }\n  }\n\n  const seen = new Set<string>()\n  const ordered: T[] = []\n  for (const row of [...keyed, ...tail]) {\n    const id = input.idOf(row)\n    if (seen.has(id)) continue\n    seen.add(id)\n    ordered.push(row)\n  }\n\n  return {\n    ...plan,\n    scanLimit,\n    rows: ordered.slice(plan.offset, plan.windowSize),\n    hasMore: ordered.length > plan.windowSize,\n    settled: keyedSettled && tailSettled,\n    ordered,\n  }\n}\n"],"names":["documentId","limit","orderBy","query","sortedKeyedQuery","base","sort","pageLimit","equalityFields","includes","field","direction","sortedUnkeyedQuery","scanLimit","sortFieldIsTotal","lacksSortField","row","value","key","split","undefined","planKeyedSegment","input","offset","page","pageSize","windowSize","keyedLimit","held","keyed","length","exhausted","keyedSettled","tailNeeded","keyedIsTotal","sortedScanLimit","plan","widenedTo","Math","max","planSortedWindow","tail","tailSettled","scanned","scan","scanSettled","scanExhausted","filter","seen","Set","ordered","id","idOf","has","add","push","rows","slice","hasMore","settled"],"mappings":"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"}

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

@@ -0,0 +1,43 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import type * as Aglyn from '@aglyn/aglyn';
+import type { DocumentReference } from 'firebase/firestore';
+import { type FirestoreDocOptions } from './firebase/firebase-services';
+/**
+ * A reusable component's working version (AGL-679), at
+ * `hosts/{hostId}/components/{componentId}/versions/{versionId}`.
+ *
+ * Compressed at rest like screen and layout versions. Note the asymmetry
+ * with those two: the component's PUBLISHED nodes live on the parent doc,
+ * because the tenant runtime reads every component in one collection query
+ * — pulling published content into version docs would make that N+1 per
+ * page render. These docs are editing history only.
+ */
+export declare const useComponentVersionRef: ({ hostId, componentId, versionId, }: {
+    hostId: string;
+    componentId: string;
+    versionId: string;
+}) => DocumentReference<Aglyn.AglynHostComponentVersion>;
+export declare const useComponentVersion: (data: {
+    hostId: string;
+    componentId: string;
+    versionId: string;
+}, options?: FirestoreDocOptions<Aglyn.AglynHostComponentVersion>) => {
+    doc: import("./firebase/firebase-services").ObservableStatus<Aglyn.AglynHostComponentVersion<Aglyn.AglynNodeSchema<Partial<Record<JSX.Key.Any, unknown>>>>>;
+    setDoc: import("./helpers/use-modify-doc-callback").ModifyDocCallback<Aglyn.AglynHostComponentVersion<Aglyn.AglynNodeSchema<Partial<Record<JSX.Key.Any, unknown>>>>>;
+};
+export default useComponentVersion;

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

@@ -0,0 +1,73 @@
+/**
+ * @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.
+ */ // 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";
+/**
+ * A reusable component's working version (AGL-679), at
+ * `hosts/{hostId}/components/{componentId}/versions/{versionId}`.
+ *
+ * Compressed at rest like screen and layout versions. Note the asymmetry
+ * with those two: the component's PUBLISHED nodes live on the parent doc,
+ * because the tenant runtime reads every component in one collection query
+ * — pulling published content into version docs would make that N+1 per
+ * page render. These docs are editing history only.
+ */ export const useComponentVersionRef = ({ hostId, componentId, versionId })=>{
+    const firestore = useFirestore();
+    const ref = doc(firestore, 'hosts', hostId, 'components', componentId, 'versions', versionId);
+    return ref.withConverter({
+        toFirestore (data) {
+            const { $id } = data, rest = _object_without_properties_loose(data, [
+                "$id"
+            ]);
+            // Only emit `nodes` when the write carries them — see the note in
+            // use-screen-version (AGL-1250). This is the converter the component
+            // Properties dialog writes through, and unconditional compression
+            // destroyed a real component's tree on the first partial write.
+            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 useComponentVersion = (data, options)=>{
+    return useDoc(useComponentVersionRef(data), options);
+};
+export default useComponentVersion;
+
+//# sourceMappingURL=use-component-version.js.map

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

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../../libs/tenant/feature/instance/src/lib/hooks/use-component-version.tsx"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\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 {\n  useFirestore,\n  type FirestoreDocOptions,\n} from './firebase/firebase-services'\nimport useDoc from './helpers/use-doc'\n\n/**\n * A reusable component's working version (AGL-679), at\n * `hosts/{hostId}/components/{componentId}/versions/{versionId}`.\n *\n * Compressed at rest like screen and layout versions. Note the asymmetry\n * with those two: the component's PUBLISHED nodes live on the parent doc,\n * because the tenant runtime reads every component in one collection query\n * — pulling published content into version docs would make that N+1 per\n * page render. These docs are editing history only.\n */\nexport const useComponentVersionRef = ({\n  hostId,\n  componentId,\n  versionId,\n}: {\n  hostId: string\n  componentId: string\n  versionId: string\n}) => {\n  const firestore = useFirestore()\n  const ref = doc(\n    firestore,\n    'hosts',\n    hostId,\n    'components',\n    componentId,\n    'versions',\n    versionId,\n  )\n  return ref.withConverter({\n    toFirestore(data) {\n      const { $id, ...rest } = data\n      // Only emit `nodes` when the write carries them — see the note in\n      // use-screen-version (AGL-1250). This is the converter the component\n      // Properties dialog writes through, and unconditional compression\n      // destroyed a real component's tree on the first partial write.\n      if (rest?.nodes === undefined) return { ...rest, updatedAt: Timestamp.now() }\n      const nodes =\n        rest.nodes instanceof Bytes ? rest.nodes : 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 {\n          ...data,\n          nodes: decompress(data.nodes),\n        } as Aglyn.AglynHostComponentVersion\n      }\n      return data as Aglyn.AglynHostComponentVersion\n    },\n  }) as DocumentReference<Aglyn.AglynHostComponentVersion>\n}\n\nexport const useComponentVersion = (\n  data: {\n    hostId: string\n    componentId: string\n    versionId: string\n  },\n  options?: FirestoreDocOptions<Aglyn.AglynHostComponentVersion>,\n) => {\n  return useDoc(useComponentVersionRef(data), options)\n}\n\nexport default useComponentVersion\n"],"names":["compress","decompress","Timestamp","Bytes","doc","useFirestore","useDoc","useComponentVersionRef","hostId","componentId","versionId","firestore","ref","withConverter","toFirestore","data","$id","rest","nodes","undefined","updatedAt","now","fromUint8Array","fromFirestore","snapshot","options","exists","useComponentVersion"],"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,SACEC,YAAY,QAEP,kCAA8B;AACrC,OAAOC,YAAY,uBAAmB;AAEtC;;;;;;;;;CASC,GACD,OAAO,MAAMC,yBAAyB,CAAC,EACrCC,MAAM,EACNC,WAAW,EACXC,SAAS,EAKV;IACC,MAAMC,YAAYN;IAClB,MAAMO,MAAMR,IACVO,WACA,SACAH,QACA,cACAC,aACA,YACAC;IAEF,OAAOE,IAAIC,aAAa,CAAC;QACvBC,aAAYC,IAAI;YACd,MAAM,EAAEC,GAAG,EAAW,GAAGD,MAATE,wCAASF;;;YACzB,kEAAkE;YAClE,qEAAqE;YACrE,kEAAkE;YAClE,gEAAgE;YAChE,IAAIE,CAAAA,wBAAAA,KAAMC,KAAK,MAAKC,WAAW,OAAO,aAAKF;gBAAMG,WAAWlB,UAAUmB,GAAG;;YACzE,MAAMH,QACJD,KAAKC,KAAK,YAAYf,QAAQc,KAAKC,KAAK,GAAGf,MAAMmB,cAAc,CAACtB,SAASiB,KAAKC,KAAK;YACrF,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,aACFY;oBACHG,OAAOjB,WAAWc,KAAKG,KAAK;;YAEhC;YACA,OAAOH;QACT;IACF;AACF,EAAC;AAED,OAAO,MAAMY,sBAAsB,CACjCZ,MAKAU;IAEA,OAAOnB,OAAOC,uBAAuBQ,OAAOU;AAC9C,EAAC;AAED,eAAeE,oBAAmB"}

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

@@ -0,0 +1,39 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import type * as Aglyn from '@aglyn/aglyn';
+import type { DocumentReference } from 'firebase/firestore';
+import { type FirestoreDocOptions } from './firebase/firebase-services';
+/**
+ * A reusable component definition (AGL-680).
+ *
+ * `nodes` and `rootId` on this doc are the PUBLISHED copy — what the tenant
+ * runtime renders, read for every component in one collection query. They
+ * are stored plainly rather than compressed, unlike screen and layout
+ * versions, so the runtime can read them without decoding.
+ */
+export declare const useComponentRef: ({ hostId, componentId, }: {
+    hostId: Aglyn.HostUid;
+    componentId: string;
+}) => DocumentReference<Aglyn.AglynHostComponent>;
+export declare const useComponent: (data: {
+    hostId: Aglyn.HostUid;
+    componentId: string;
+}, options?: FirestoreDocOptions<Aglyn.AglynHostComponent>) => {
+    doc: import("./firebase/firebase-services").ObservableStatus<Aglyn.AglynHostComponent<Aglyn.AglynNodeSchema<Partial<Record<JSX.Key.Any, unknown>>>>>;
+    setDoc: import("./helpers/use-modify-doc-callback").ModifyDocCallback<Aglyn.AglynHostComponent<Aglyn.AglynNodeSchema<Partial<Record<JSX.Key.Any, unknown>>>>>;
+};
+export default useComponent;

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

@@ -0,0 +1,55 @@
+/**
+ * @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.
+ */ // 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 { Timestamp } from "@aglyn/shared-util-timestamp";
+import { doc } from "firebase/firestore";
+import { useFirestore } from "./firebase/firebase-services.js";
+import useDoc from "./helpers/use-doc.js";
+/**
+ * A reusable component definition (AGL-680).
+ *
+ * `nodes` and `rootId` on this doc are the PUBLISHED copy — what the tenant
+ * runtime renders, read for every component in one collection query. They
+ * are stored plainly rather than compressed, unlike screen and layout
+ * versions, so the runtime can read them without decoding.
+ */ export const useComponentRef = ({ hostId, componentId })=>{
+    const firestore = useFirestore();
+    const ref = doc(firestore, 'hosts', hostId, 'components', componentId);
+    return ref.withConverter({
+        toFirestore (data) {
+            const { $id } = data, rest = _object_without_properties_loose(data, [
+                "$id"
+            ]);
+            return _extends({}, rest, {
+                updatedAt: Timestamp.now()
+            });
+        },
+        fromFirestore (snapshot, options) {
+            if (!snapshot.exists()) return undefined;
+            return snapshot.data(options);
+        }
+    });
+};
+export const useComponent = (data, options)=>{
+    return useDoc(useComponentRef(data), options);
+};
+export default useComponent;
+
+//# sourceMappingURL=use-component.js.map

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

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../../libs/tenant/feature/instance/src/lib/hooks/use-component.tsx"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\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 { Timestamp } from '@aglyn/shared-util-timestamp'\nimport type { DocumentReference } from 'firebase/firestore'\nimport { doc } from 'firebase/firestore'\nimport {\n  useFirestore,\n  type FirestoreDocOptions,\n} from './firebase/firebase-services'\nimport useDoc from './helpers/use-doc'\n\n/**\n * A reusable component definition (AGL-680).\n *\n * `nodes` and `rootId` on this doc are the PUBLISHED copy — what the tenant\n * runtime renders, read for every component in one collection query. They\n * are stored plainly rather than compressed, unlike screen and layout\n * versions, so the runtime can read them without decoding.\n */\nexport const useComponentRef = ({\n  hostId,\n  componentId,\n}: {\n  hostId: Aglyn.HostUid\n  componentId: string\n}) => {\n  const firestore = useFirestore()\n  const ref = doc(firestore, 'hosts', hostId, 'components', componentId)\n  return ref.withConverter({\n    toFirestore(data: Aglyn.AglynHostComponent) {\n      const { $id, ...rest } = data\n      return { ...rest, updatedAt: Timestamp.now() }\n    },\n    fromFirestore(snapshot, options) {\n      if (!snapshot.exists()) return undefined\n      return snapshot.data(options) as Aglyn.AglynHostComponent\n    },\n  }) as DocumentReference<Aglyn.AglynHostComponent>\n}\n\nexport const useComponent = (\n  data: { hostId: Aglyn.HostUid; componentId: string },\n  options?: FirestoreDocOptions<Aglyn.AglynHostComponent>,\n) => {\n  return useDoc(useComponentRef(data), options)\n}\n\nexport default useComponent\n"],"names":["Timestamp","doc","useFirestore","useDoc","useComponentRef","hostId","componentId","firestore","ref","withConverter","toFirestore","data","$id","rest","updatedAt","now","fromFirestore","snapshot","options","exists","undefined","useComponent"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED,4EAA4E;AAC5E,yEAAyE;AACzE,wEAAwE;;;AAExE,SAASA,SAAS,QAAQ,+BAA8B;AAExD,SAASC,GAAG,QAAQ,qBAAoB;AACxC,SACEC,YAAY,QAEP,kCAA8B;AACrC,OAAOC,YAAY,uBAAmB;AAEtC;;;;;;;CAOC,GACD,OAAO,MAAMC,kBAAkB,CAAC,EAC9BC,MAAM,EACNC,WAAW,EAIZ;IACC,MAAMC,YAAYL;IAClB,MAAMM,MAAMP,IAAIM,WAAW,SAASF,QAAQ,cAAcC;IAC1D,OAAOE,IAAIC,aAAa,CAAC;QACvBC,aAAYC,IAA8B;YACxC,MAAM,EAAEC,GAAG,EAAW,GAAGD,MAATE,wCAASF;;;YACzB,OAAO,aAAKE;gBAAMC,WAAWd,UAAUe,GAAG;;QAC5C;QACAC,eAAcC,QAAQ,EAAEC,OAAO;YAC7B,IAAI,CAACD,SAASE,MAAM,IAAI,OAAOC;YAC/B,OAAOH,SAASN,IAAI,CAACO;QACvB;IACF;AACF,EAAC;AAED,OAAO,MAAMG,eAAe,CAC1BV,MACAO;IAEA,OAAOf,OAAOC,gBAAgBO,OAAOO;AACvC,EAAC;AAED,eAAeG,aAAY"}

package/src/lib/hooks/use-console-host-route.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Console route base for a host: `/{orgSlug}/hosts/{subdomain}` (AGL-673).
+ *
+ * Plugin components are handed a host DOC ID and used to build links as
+ * `/{hostDocId}/…`. Console routes have been `/[orgSlug]/hosts/[subdomain]/…`
+ * since AGL-621/622, so every one of those links silently began 404ing —
+ * found three separate times in different plugins, each looking like a new
+ * bug. This is the one resolution, so the next plugin does not become the
+ * fourth.
+ *
+ * `null` until resolved, and `null` forever if the org has no slug. Callers
+ * must render plain text rather than a link in that case: a link to nowhere
+ * is worse than no link.
+ *
+ * Reads `hostIndex` (signed-in readable, mirrors `subdomain` and `orgId`)
+ * plus the org doc for its slug — both cheap and already cached by the SDK
+ * on most screens.
+ */
+export declare function useConsoleHostRoute(hostId: string | undefined | null): {
+    base: string | null;
+    orgSlug: string | null;
+    subdomain: string | null;
+};
+export default useConsoleHostRoute;