@aglyn/aglyn 1.0.0-beta.143

package/src/lib/app-utils/collection-kind.d.ts

@@ -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.
+ */
+/**
+ * Two unrelated features share `hosts/{hostId}/collections` (AGL-954):
+ *
+ * - **content** — the Content page's publishable collections. They own an
+ *   `entries` subcollection and serve at `/{collectionSlug}/{entrySlug}`.
+ * - **catalog** — commerce's manual/smart product collections. They own
+ *   nothing and serve at `/collections/{slug}`.
+ *
+ * Nothing on the documents said which was which, so every surface listed the
+ * other's rows and a public slug lookup could resolve to the wrong kind.
+ * Every document now carries `kind` — both console surfaces stamp it, site
+ * import stamps it, and the pre-existing documents were backfilled (AGL-979),
+ * so reads no longer infer anything from shape. `legacyCollectionKind` below
+ * is the one remaining inference, confined to the import adapter.
+ */
+export type HostCollectionKind = 'content' | 'catalog';
+/** Written onto every collection doc created from here on (AGL-954). */
+export declare const HOST_COLLECTION_KINDS: readonly HostCollectionKind[];
+/**
+ * Which feature owns this `collections` doc.
+ *
+ * Reads `kind` and nothing else. A document that does not say what it is is
+ * treated as content — the safe direction, because content is the kind that
+ * owns `entries`, and mistaking it for catalog is what puts those entries in
+ * reach of a delete.
+ */
+export declare function hostCollectionKind(data: object | null | undefined): HostCollectionKind;
+/**
+ * Classify a collection that predates the `kind` field, from its shape.
+ *
+ * ONLY for the site-import adapter: a bundle exported before AGL-954 has no
+ * `kind`, and that is the one path where an old catalog collection can still
+ * arrive. Every other reader uses {@link hostCollectionKind}, which does not
+ * guess. Only catalog collections carry the membership keys, so their presence
+ * is decisive; everything else is content.
+ */
+export declare function legacyCollectionKind(data: object | null | undefined): HostCollectionKind;
+/** Filter helper: `docs.filter(isHostCollectionKind('catalog'))`. */
+export declare function isHostCollectionKind(kind: HostCollectionKind): (data: object | null | undefined) => boolean;

package/src/lib/app-utils/collection-kind.js

@@ -0,0 +1,69 @@
+/**
+ * @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.
+ */ /**
+ * Two unrelated features share `hosts/{hostId}/collections` (AGL-954):
+ *
+ * - **content** — the Content page's publishable collections. They own an
+ *   `entries` subcollection and serve at `/{collectionSlug}/{entrySlug}`.
+ * - **catalog** — commerce's manual/smart product collections. They own
+ *   nothing and serve at `/collections/{slug}`.
+ *
+ * Nothing on the documents said which was which, so every surface listed the
+ * other's rows and a public slug lookup could resolve to the wrong kind.
+ * Every document now carries `kind` — both console surfaces stamp it, site
+ * import stamps it, and the pre-existing documents were backfilled (AGL-979),
+ * so reads no longer infer anything from shape. `legacyCollectionKind` below
+ * is the one remaining inference, confined to the import adapter.
+ */ /** Written onto every collection doc created from here on (AGL-954). */ export const HOST_COLLECTION_KINDS = [
+    'content',
+    'catalog'
+];
+function isKind(value) {
+    return value === 'content' || value === 'catalog';
+}
+/**
+ * Which feature owns this `collections` doc.
+ *
+ * Reads `kind` and nothing else. A document that does not say what it is is
+ * treated as content — the safe direction, because content is the kind that
+ * owns `entries`, and mistaking it for catalog is what puts those entries in
+ * reach of a delete.
+ */ export function hostCollectionKind(data) {
+    if (!data) return 'content';
+    // Accepts any object shape — callers pass typed rows (HostCollection) as
+    // readily as raw Firestore data.
+    const fields = data['kind'];
+    return isKind(fields) ? fields : 'content';
+}
+/**
+ * Classify a collection that predates the `kind` field, from its shape.
+ *
+ * ONLY for the site-import adapter: a bundle exported before AGL-954 has no
+ * `kind`, and that is the one path where an old catalog collection can still
+ * arrive. Every other reader uses {@link hostCollectionKind}, which does not
+ * guess. Only catalog collections carry the membership keys, so their presence
+ * is decisive; everything else is content.
+ */ export function legacyCollectionKind(data) {
+    if (!data) return 'content';
+    const fields = data;
+    if (isKind(fields['kind'])) return fields['kind'];
+    return fields['mode'] !== undefined || fields['rules'] !== undefined || fields['productIds'] !== undefined ? 'catalog' : 'content';
+}
+/** Filter helper: `docs.filter(isHostCollectionKind('catalog'))`. */ export function isHostCollectionKind(kind) {
+    return (data)=>hostCollectionKind(data) === kind;
+}
+
+//# sourceMappingURL=collection-kind.js.map

package/src/lib/app-utils/collection-kind.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/collection-kind.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\n/**\n * Two unrelated features share `hosts/{hostId}/collections` (AGL-954):\n *\n * - **content** — the Content page's publishable collections. They own an\n *   `entries` subcollection and serve at `/{collectionSlug}/{entrySlug}`.\n * - **catalog** — commerce's manual/smart product collections. They own\n *   nothing and serve at `/collections/{slug}`.\n *\n * Nothing on the documents said which was which, so every surface listed the\n * other's rows and a public slug lookup could resolve to the wrong kind.\n * Every document now carries `kind` — both console surfaces stamp it, site\n * import stamps it, and the pre-existing documents were backfilled (AGL-979),\n * so reads no longer infer anything from shape. `legacyCollectionKind` below\n * is the one remaining inference, confined to the import adapter.\n */\nexport type HostCollectionKind = 'content' | 'catalog'\n\n/** Written onto every collection doc created from here on (AGL-954). */\nexport const HOST_COLLECTION_KINDS: readonly HostCollectionKind[] = [\n  'content',\n  'catalog',\n]\n\nfunction isKind(value: unknown): value is HostCollectionKind {\n  return value === 'content' || value === 'catalog'\n}\n\n/**\n * Which feature owns this `collections` doc.\n *\n * Reads `kind` and nothing else. A document that does not say what it is is\n * treated as content — the safe direction, because content is the kind that\n * owns `entries`, and mistaking it for catalog is what puts those entries in\n * reach of a delete.\n */\nexport function hostCollectionKind(\n  data: object | null | undefined,\n): HostCollectionKind {\n  if (!data) return 'content'\n  // Accepts any object shape — callers pass typed rows (HostCollection) as\n  // readily as raw Firestore data.\n  const fields = (data as Record<string, unknown>)['kind']\n  return isKind(fields) ? fields : 'content'\n}\n\n/**\n * Classify a collection that predates the `kind` field, from its shape.\n *\n * ONLY for the site-import adapter: a bundle exported before AGL-954 has no\n * `kind`, and that is the one path where an old catalog collection can still\n * arrive. Every other reader uses {@link hostCollectionKind}, which does not\n * guess. Only catalog collections carry the membership keys, so their presence\n * is decisive; everything else is content.\n */\nexport function legacyCollectionKind(\n  data: object | null | undefined,\n): HostCollectionKind {\n  if (!data) return 'content'\n  const fields = data as Record<string, unknown>\n  if (isKind(fields['kind'])) return fields['kind']\n  return fields['mode'] !== undefined ||\n    fields['rules'] !== undefined ||\n    fields['productIds'] !== undefined\n    ? 'catalog'\n    : 'content'\n}\n\n/** Filter helper: `docs.filter(isHostCollectionKind('catalog'))`. */\nexport function isHostCollectionKind(kind: HostCollectionKind) {\n  return (data: object | null | undefined): boolean =>\n    hostCollectionKind(data) === kind\n}\n"],"names":["HOST_COLLECTION_KINDS","isKind","value","hostCollectionKind","data","fields","legacyCollectionKind","undefined","isHostCollectionKind","kind"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED;;;;;;;;;;;;;;CAcC,GAGD,sEAAsE,GACtE,OAAO,MAAMA,wBAAuD;IAClE;IACA;CACD,CAAA;AAED,SAASC,OAAOC,KAAc;IAC5B,OAAOA,UAAU,aAAaA,UAAU;AAC1C;AAEA;;;;;;;CAOC,GACD,OAAO,SAASC,mBACdC,IAA+B;IAE/B,IAAI,CAACA,MAAM,OAAO;IAClB,yEAAyE;IACzE,iCAAiC;IACjC,MAAMC,SAAS,AAACD,IAAgC,CAAC,OAAO;IACxD,OAAOH,OAAOI,UAAUA,SAAS;AACnC;AAEA;;;;;;;;CAQC,GACD,OAAO,SAASC,qBACdF,IAA+B;IAE/B,IAAI,CAACA,MAAM,OAAO;IAClB,MAAMC,SAASD;IACf,IAAIH,OAAOI,MAAM,CAAC,OAAO,GAAG,OAAOA,MAAM,CAAC,OAAO;IACjD,OAAOA,MAAM,CAAC,OAAO,KAAKE,aACxBF,MAAM,CAAC,QAAQ,KAAKE,aACpBF,MAAM,CAAC,aAAa,KAAKE,YACvB,YACA;AACN;AAEA,mEAAmE,GACnE,OAAO,SAASC,qBAAqBC,IAAwB;IAC3D,OAAO,CAACL,OACND,mBAAmBC,UAAUK;AACjC"}

package/src/lib/app-utils/collection-slug.d.ts

@@ -0,0 +1,79 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { type HostCollectionKind } from './collection-kind';
+/**
+ * A collection's slug is its public address — `/{slug}` for content,
+ * `/collections/{slug}` for catalog — and nothing made it unique (AGL-957).
+ * Two collections of the same kind could both be `blog`, and the resolvers,
+ * which take the first match of the right kind, then served whichever one
+ * Firestore happened to return. The other became unreachable, with no error
+ * anywhere to say so.
+ *
+ * Uniqueness is per host AND per kind: content and catalog have separate URL
+ * namespaces, so `/blog` and `/collections/blog` may coexist.
+ */
+export interface CollectionSlugCandidate {
+    $id?: string;
+    slug?: string;
+}
+/**
+ * The id of the collection already using `slug`, or null when it is free.
+ *
+ * `exceptId` is the collection being edited — a rename that keeps the same
+ * slug must not collide with itself. Comparison is case- and space-
+ * insensitive because the slugifiers differ slightly between the two
+ * surfaces and "Blog" vs "blog" resolve to the same URL either way.
+ */
+export declare function findCollectionSlugOwner(slug: string, kind: HostCollectionKind, existing: readonly CollectionSlugCandidate[] | null | undefined, exceptId?: string | null): string | null;
+/** Convenience predicate over {@link findCollectionSlugOwner}. */
+export declare function isCollectionSlugTaken(slug: string, kind: HostCollectionKind, existing: readonly CollectionSlugCandidate[] | null | undefined, exceptId?: string | null): boolean;
+/**
+ * An ENTRY's slug is its public address too — `/{collectionSlug}/{entrySlug}`
+ * — and it has exactly the defect AGL-957 fixed one level up (AGL-2498).
+ *
+ * The tenant resolves an entry with `.where('slug', '==', entrySlug)` inside
+ * the collection and takes the first match, so two entries sharing a slug
+ * means one of them is simply unreachable, with nothing anywhere saying so.
+ * Nothing enforced it because nothing could: the slug was DERIVED from the
+ * title on every save, so a collision meant two posts with the same title and
+ * the console never offered a way to tell them apart.
+ *
+ * Now that the slug is editable the collision is reachable on purpose, so it
+ * has to be answerable. Scope is per COLLECTION — two collections may each
+ * have a `/hello`, because the collection segment disambiguates them.
+ */
+export interface EntrySlugCandidate {
+    $id?: string;
+    slug?: string;
+}
+/**
+ * The id of the entry already using `slug` in this collection, or null.
+ *
+ * `exceptId` is the entry being edited — re-saving a post without touching its
+ * slug must not collide with itself. Case- and space-insensitive for the same
+ * reason the collection rule is: `Hello` and `hello` resolve to one URL.
+ *
+ * ⚠️ This decides nothing on its own — it reports what the caller handed it.
+ * The console's caller asks Firestore for the slug directly, so its answer
+ * covers the whole collection rather than a loaded window; a caller that
+ * passes a page instead can only report collisions inside that page, and must
+ * say so rather than implying a guarantee this cannot make.
+ *
+ * It remains fast feedback rather than an enforcement point in either case:
+ * two authors saving the same address at once both read no owner.
+ */
+export declare function findEntrySlugOwner(slug: string, existing: readonly EntrySlugCandidate[] | null | undefined, exceptId?: string | null): string | null;

package/src/lib/app-utils/collection-slug.js

@@ -0,0 +1,70 @@
+/**
+ * @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 { hostCollectionKind } from "./collection-kind.js";
+/**
+ * The id of the collection already using `slug`, or null when it is free.
+ *
+ * `exceptId` is the collection being edited — a rename that keeps the same
+ * slug must not collide with itself. Comparison is case- and space-
+ * insensitive because the slugifiers differ slightly between the two
+ * surfaces and "Blog" vs "blog" resolve to the same URL either way.
+ */ export function findCollectionSlugOwner(slug, kind, existing, exceptId) {
+    const wanted = String(slug != null ? slug : '').trim().toLowerCase();
+    if (!wanted) return null;
+    for (const candidate of existing != null ? existing : []){
+        var _candidate_slug;
+        if (exceptId && candidate.$id === exceptId) continue;
+        if (hostCollectionKind(candidate) !== kind) continue;
+        if (String((_candidate_slug = candidate.slug) != null ? _candidate_slug : '').trim().toLowerCase() === wanted) {
+            var _candidate_$id;
+            return (_candidate_$id = candidate.$id) != null ? _candidate_$id : '';
+        }
+    }
+    return null;
+}
+/** Convenience predicate over {@link findCollectionSlugOwner}. */ export function isCollectionSlugTaken(slug, kind, existing, exceptId) {
+    return findCollectionSlugOwner(slug, kind, existing, exceptId) !== null;
+}
+/**
+ * The id of the entry already using `slug` in this collection, or null.
+ *
+ * `exceptId` is the entry being edited — re-saving a post without touching its
+ * slug must not collide with itself. Case- and space-insensitive for the same
+ * reason the collection rule is: `Hello` and `hello` resolve to one URL.
+ *
+ * ⚠️ This decides nothing on its own — it reports what the caller handed it.
+ * The console's caller asks Firestore for the slug directly, so its answer
+ * covers the whole collection rather than a loaded window; a caller that
+ * passes a page instead can only report collisions inside that page, and must
+ * say so rather than implying a guarantee this cannot make.
+ *
+ * It remains fast feedback rather than an enforcement point in either case:
+ * two authors saving the same address at once both read no owner.
+ */ export function findEntrySlugOwner(slug, existing, exceptId) {
+    const wanted = String(slug != null ? slug : '').trim().toLowerCase();
+    if (!wanted) return null;
+    for (const candidate of existing != null ? existing : []){
+        var _candidate_slug;
+        if (exceptId && candidate.$id === exceptId) continue;
+        if (String((_candidate_slug = candidate.slug) != null ? _candidate_slug : '').trim().toLowerCase() === wanted) {
+            var _candidate_$id;
+            return (_candidate_$id = candidate.$id) != null ? _candidate_$id : '';
+        }
+    }
+    return null;
+}
+
+//# sourceMappingURL=collection-slug.js.map

package/src/lib/app-utils/collection-slug.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/collection-slug.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 HostCollectionKind, hostCollectionKind } from './collection-kind'\n\n/**\n * A collection's slug is its public address — `/{slug}` for content,\n * `/collections/{slug}` for catalog — and nothing made it unique (AGL-957).\n * Two collections of the same kind could both be `blog`, and the resolvers,\n * which take the first match of the right kind, then served whichever one\n * Firestore happened to return. The other became unreachable, with no error\n * anywhere to say so.\n *\n * Uniqueness is per host AND per kind: content and catalog have separate URL\n * namespaces, so `/blog` and `/collections/blog` may coexist.\n */\nexport interface CollectionSlugCandidate {\n  $id?: string\n  slug?: string\n}\n\n/**\n * The id of the collection already using `slug`, or null when it is free.\n *\n * `exceptId` is the collection being edited — a rename that keeps the same\n * slug must not collide with itself. Comparison is case- and space-\n * insensitive because the slugifiers differ slightly between the two\n * surfaces and \"Blog\" vs \"blog\" resolve to the same URL either way.\n */\nexport function findCollectionSlugOwner(\n  slug: string,\n  kind: HostCollectionKind,\n  existing: readonly CollectionSlugCandidate[] | null | undefined,\n  exceptId?: string | null,\n): string | null {\n  const wanted = String(slug ?? '').trim().toLowerCase()\n  if (!wanted) return null\n  for (const candidate of existing ?? []) {\n    if (exceptId && candidate.$id === exceptId) continue\n    if (hostCollectionKind(candidate) !== kind) continue\n    if (String(candidate.slug ?? '').trim().toLowerCase() === wanted) {\n      return candidate.$id ?? ''\n    }\n  }\n  return null\n}\n\n/** Convenience predicate over {@link findCollectionSlugOwner}. */\nexport function isCollectionSlugTaken(\n  slug: string,\n  kind: HostCollectionKind,\n  existing: readonly CollectionSlugCandidate[] | null | undefined,\n  exceptId?: string | null,\n): boolean {\n  return findCollectionSlugOwner(slug, kind, existing, exceptId) !== null\n}\n\n/**\n * An ENTRY's slug is its public address too — `/{collectionSlug}/{entrySlug}`\n * — and it has exactly the defect AGL-957 fixed one level up (AGL-2498).\n *\n * The tenant resolves an entry with `.where('slug', '==', entrySlug)` inside\n * the collection and takes the first match, so two entries sharing a slug\n * means one of them is simply unreachable, with nothing anywhere saying so.\n * Nothing enforced it because nothing could: the slug was DERIVED from the\n * title on every save, so a collision meant two posts with the same title and\n * the console never offered a way to tell them apart.\n *\n * Now that the slug is editable the collision is reachable on purpose, so it\n * has to be answerable. Scope is per COLLECTION — two collections may each\n * have a `/hello`, because the collection segment disambiguates them.\n */\nexport interface EntrySlugCandidate {\n  $id?: string\n  slug?: string\n}\n\n/**\n * The id of the entry already using `slug` in this collection, or null.\n *\n * `exceptId` is the entry being edited — re-saving a post without touching its\n * slug must not collide with itself. Case- and space-insensitive for the same\n * reason the collection rule is: `Hello` and `hello` resolve to one URL.\n *\n * ⚠️ This decides nothing on its own — it reports what the caller handed it.\n * The console's caller asks Firestore for the slug directly, so its answer\n * covers the whole collection rather than a loaded window; a caller that\n * passes a page instead can only report collisions inside that page, and must\n * say so rather than implying a guarantee this cannot make.\n *\n * It remains fast feedback rather than an enforcement point in either case:\n * two authors saving the same address at once both read no owner.\n */\nexport function findEntrySlugOwner(\n  slug: string,\n  existing: readonly EntrySlugCandidate[] | null | undefined,\n  exceptId?: string | null,\n): string | null {\n  const wanted = String(slug ?? '').trim().toLowerCase()\n  if (!wanted) return null\n  for (const candidate of existing ?? []) {\n    if (exceptId && candidate.$id === exceptId) continue\n    if (String(candidate.slug ?? '').trim().toLowerCase() === wanted) {\n      return candidate.$id ?? ''\n    }\n  }\n  return null\n}\n"],"names":["hostCollectionKind","findCollectionSlugOwner","slug","kind","existing","exceptId","wanted","String","trim","toLowerCase","candidate","$id","isCollectionSlugTaken","findEntrySlugOwner"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED,SAAkCA,kBAAkB,QAAQ,uBAAmB;AAkB/E;;;;;;;CAOC,GACD,OAAO,SAASC,wBACdC,IAAY,EACZC,IAAwB,EACxBC,QAA+D,EAC/DC,QAAwB;IAExB,MAAMC,SAASC,OAAOL,eAAAA,OAAQ,IAAIM,IAAI,GAAGC,WAAW;IACpD,IAAI,CAACH,QAAQ,OAAO;IACpB,KAAK,MAAMI,aAAaN,mBAAAA,WAAY,EAAE,CAAE;YAG3BM;QAFX,IAAIL,YAAYK,UAAUC,GAAG,KAAKN,UAAU;QAC5C,IAAIL,mBAAmBU,eAAeP,MAAM;QAC5C,IAAII,QAAOG,kBAAAA,UAAUR,IAAI,YAAdQ,kBAAkB,IAAIF,IAAI,GAAGC,WAAW,OAAOH,QAAQ;gBACzDI;YAAP,QAAOA,iBAAAA,UAAUC,GAAG,YAAbD,iBAAiB;QAC1B;IACF;IACA,OAAO;AACT;AAEA,gEAAgE,GAChE,OAAO,SAASE,sBACdV,IAAY,EACZC,IAAwB,EACxBC,QAA+D,EAC/DC,QAAwB;IAExB,OAAOJ,wBAAwBC,MAAMC,MAAMC,UAAUC,cAAc;AACrE;AAsBA;;;;;;;;;;;;;;;CAeC,GACD,OAAO,SAASQ,mBACdX,IAAY,EACZE,QAA0D,EAC1DC,QAAwB;IAExB,MAAMC,SAASC,OAAOL,eAAAA,OAAQ,IAAIM,IAAI,GAAGC,WAAW;IACpD,IAAI,CAACH,QAAQ,OAAO;IACpB,KAAK,MAAMI,aAAaN,mBAAAA,WAAY,EAAE,CAAE;YAE3BM;QADX,IAAIL,YAAYK,UAAUC,GAAG,KAAKN,UAAU;QAC5C,IAAIE,QAAOG,kBAAAA,UAAUR,IAAI,YAAdQ,kBAAkB,IAAIF,IAAI,GAAGC,WAAW,OAAOH,QAAQ;gBACzDI;YAAP,QAAOA,iBAAAA,UAAUC,GAAG,YAAbD,iBAAiB;QAC1B;IACF;IACA,OAAO;AACT"}

package/src/lib/app-utils/compose-layout-nodes.d.ts

@@ -0,0 +1,147 @@
+/**
+ * @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 { AglynNodeSchema, NodeId } from '../foundation';
+/** Persisted component id of the layout content outlet (plugins-mui). */
+export declare const LAYOUT_SLOT_COMPONENT_ID = "layoutSlot";
+/**
+ * Prefix applied to layout node ids during composition so they can never
+ * collide with screen node ids (layout ids repeat across every bound
+ * screen).
+ */
+export declare const LAYOUT_NODE_ID_PREFIX = "layout__";
+/**
+ * How many layouts deep a chain may nest (AGL-703).
+ *
+ * A layout can render inside another layout, so the chain is walked rather
+ * than read once. This bounds it: a cycle is already refused at both write
+ * time and resolution time, and this is the belt to that pair of braces —
+ * a hand-edited document must not be able to hang a render.
+ */
+export declare const MAX_LAYOUT_CHAIN_DEPTH = 5;
+/**
+ * Namespace for one level of the layout chain (AGL-703).
+ *
+ * Depth 1 — the layout a screen names directly — keeps the original
+ * `layout__` exactly. Every interaction authored before nesting existed
+ * stores raw canvas ids that {@link normalizeLeafId} matches against this
+ * prefix, so changing it would silently break them. Outer levels take
+ * `layout2__`, `layout3__`, … which is what keeps a grandparent layout's
+ * node ids from colliding with its child's: without a per-level namespace,
+ * two layouts in one chain sharing a node id would collapse into one node.
+ */
+export declare function layoutNodeIdPrefix(depth?: number): string;
+/** Every namespace a composed tree can carry, outermost depth first. */
+export declare const LAYOUT_NODE_ID_PREFIXES: string[];
+/**
+ * Whether a composed node id came from the LAYOUT chain rather than from the
+ * screen (AGL-1871).
+ *
+ * Composition namespaces ids by origin and nothing else does: a layout node
+ * is `layout__{id}` (`layout2__` … `layout5__` further up the chain, see
+ * {@link layoutNodeIdPrefix}) while a screen node keeps its raw canvas id. A
+ * reusable component grafted onto either one wears its host's id inside its
+ * own namespace — the marketing nav really ships as
+ * `cmp__layout__52Ef-3t6yd___R91yATrXH` — so the graft prefixes are peeled
+ * before the origin is read, and a graft nested in a graft peels the same way.
+ *
+ * A raw canvas id cannot collide with this: nanoid emits a single token with
+ * no `__` boundary in it, so `layout__` can only be a prefix that composition
+ * put there.
+ */
+export declare function isLayoutComposedNodeId(id: string | undefined | null): boolean;
+/**
+ * Whether a composed tree contains anything the SCREEN put there (AGL-1871).
+ *
+ * `composeLayoutAndScreenNodes` always answers with a populated map when the
+ * host has a layout, because the layout chrome is in it whether or not the
+ * screen contributed a single node. So "compose returned nodes" is not the
+ * same question as "this screen has a page on it", and code that treats the
+ * two as one renders a header and a footer around nothing.
+ *
+ * That is not hypothetical. Measured on `aglyn.com` 2026-08-23, the published
+ * *"Not found (404)"* screen composed to **297 nodes, every one of them layout
+ * chrome**, with the `layoutSlot` holding an empty child list — the screen was
+ * routed, published and completely empty. The 404 boundary read the 297 as
+ * "the site has a designed 404", declined its own fallback, and every unmatched
+ * URL on the site served branding wrapped around a blank page.
+ *
+ * The root node is not evidence — composition synthesizes one for an empty
+ * screen — so it is excluded.
+ */
+export declare function hasScreenAuthoredNodes(nodes: Record<string, unknown> | null | undefined): boolean;
+type NormalizedNodes<N extends AglynNodeSchema> = Record<NodeId, N>;
+/**
+ * Grafts a screen's nodes into its layout's LayoutSlot, producing one
+ * normalized node map rooted at the layout root.
+ *
+ * - Layout node ids are namespaced with {@link LAYOUT_NODE_ID_PREFIX} (the
+ *   root id excepted) to avoid collisions with screen ids.
+ * - The screen root's children are appended to the slot's own children and
+ *   repointed at the slot. Slot children shouldn't normally exist, but
+ *   designers do land chrome inside the slot — rendering it above the
+ *   screen content preserves their intent instead of silently dropping it.
+ * - Inputs are never mutated. Without layout nodes — or when the layout has
+ *   no slot — the screen nodes are returned unchanged so a stale or broken
+ *   layout can't take a published screen down.
+ */
+export declare function composeLayoutAndScreenNodes<N extends AglynNodeSchema = AglynNodeSchema>(layoutNodes: NormalizedNodes<N> | undefined, screenNodes: NormalizedNodes<N>, 
+/** Position in the layout chain; 1 = the layout the screen names. */
+depth?: number): NormalizedNodes<N>;
+/**
+ * Grafts a screen through a CHAIN of layouts, innermost first (AGL-703).
+ *
+ * `layoutNodesChain[0]` is the layout the screen names, `[1]` is that
+ * layout's own layout, and so on outward. Each step drops the previous
+ * result into the next layout's slot, so the outermost layout ends up as
+ * the root — the same relationship a screen has always had with its layout,
+ * applied one more time.
+ *
+ * A layout with no slot is skipped rather than fatal, and skipping it does
+ * not strand the layouts outside it: the accumulated tree simply passes
+ * through. That matches the single-layout behaviour, where a broken layout
+ * degrades to the bare screen instead of taking a published page down.
+ *
+ * Cycles are refused before this point (see `resolveLayoutChainIds`), and
+ * the chain is capped at {@link MAX_LAYOUT_CHAIN_DEPTH} regardless.
+ */
+export declare function composeLayoutChainAndScreenNodes<N extends AglynNodeSchema = AglynNodeSchema>(layoutNodesChain: Array<NormalizedNodes<N> | undefined>, screenNodes: NormalizedNodes<N>): NormalizedNodes<N>;
+/**
+ * Walks a layout's ancestry into a flat chain, innermost first (AGL-703).
+ *
+ * `parentOf` returns the layout a given layout renders inside, or undefined
+ * at the top. The walk stops on:
+ *
+ * - **self-reference** — a layout naming itself, which is the case worth
+ *   naming out loud because it is the easy mistake to make;
+ * - **any repeat** — A → B → A would otherwise recurse forever, and a
+ *   guard that only catches self-reference would miss it;
+ * - **depth** — {@link MAX_LAYOUT_CHAIN_DEPTH}.
+ *
+ * Stopping (rather than throwing) is deliberate: a cycle in stored data
+ * should render the layouts up to the repeat, not blank the site.
+ */
+export declare function resolveLayoutChainIds(layoutId: string | undefined | null, parentOf: (layoutId: string) => string | undefined | null): string[];
+/**
+ * Whether `candidateParentId` may be set as `layoutId`'s parent layout.
+ *
+ * Refuses self-reference and any candidate that already has this layout
+ * somewhere above it — picking one would close a loop. This is the
+ * write-time half; `resolveLayoutChainIds` stays defensive anyway, because
+ * a document can be edited by something that never called this.
+ */
+export declare function canNestLayout(layoutId: string, candidateParentId: string, parentOf: (layoutId: string) => string | undefined | null): boolean;
+export default composeLayoutAndScreenNodes;