@aglyn/aglyn 1.0.0-beta.143

package/src/lib/app-utils/name-search.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/name-search.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 * Normalized search key for a human display name (AGL-835).\n *\n * Firestore has no case-insensitive query, so name search is done by storing\n * a normalized `nameLower` alongside the display name and running a prefix\n * range query against it: `orderBy(nameLower) startAt(q) endAt(q + '')`.\n * For that to match, the stored key and the typed query MUST be normalized the\n * same way — so both the write paths (screen/host creates and renames) and the\n * switcher's query builder run the raw text through this one function.\n *\n * Normalization is deliberately minimal and reversible-in-spirit: lower-case,\n * trim, and collapse internal whitespace. Diacritics are intentionally NOT\n * stripped — a user who types \"café\" should match the stored \"café\", and one\n * who types \"cafe\" is doing a different search; folding accents here would make\n * the prefix range silently disagree with the key. Returns '' for nullish or\n * blank input, which callers treat as \"no searchable name / skip the field\".\n */\nexport function nameSearchKey(name: string | null | undefined): string {\n  return (name ?? '').trim().replace(/\\s+/g, ' ').toLowerCase()\n}\n\n/**\n * The longest word-prefix a token may be.\n *\n * Every prefix of every word is stored, so the token count grows with name\n * LENGTH rather than word count. Twelve characters is past the point where a\n * search box narrows anything — a reader who has typed twelve characters has\n * already found it — and it keeps a long name from spending a hundred index\n * entries on the tail of one word.\n */\nexport const NAME_TOKEN_MAX_PREFIX = 12\n\n/** Ceiling on tokens per document, so a pathological name cannot bloat the index. */\nexport const NAME_TOKEN_LIMIT = 120\n\n/**\n * Word-prefix tokens for `array-contains` search (AGL-2501).\n *\n * `nameSearchKey` supports a PREFIX range, which is anchored at the start of\n * the whole name: \"acme\" finds \"Acme Coffee\" and \"coffee\" does not. That is\n * the wrong shape for a search box, where the word a reader remembers is\n * rarely the first one.\n *\n * Firestore cannot answer `contains` on a string, but it can answer\n * `array-contains` on a field the write path prepared. Storing every prefix\n * of every WORD turns \"does this name contain a word starting with X\" into a\n * single indexed equality:\n *\n *   \"Acme Coffee\" → a, ac, acm, acme, c, co, cof, coff, coffe, coffee\n *\n * So \"cof\" finds it, and so does \"acme\". What it still cannot do is match\n * mid-word — \"offee\" is not a prefix of any word — which is the honest edge\n * of doing this without a search service.\n *\n * Normalized through `nameSearchKey` so the stored tokens and the typed query\n * agree on case, trimming and internal whitespace; diacritics are kept, for\n * the reason given there.\n */\nexport function nameSearchTokens(name: string | null | undefined): string[] {\n  const key = nameSearchKey(name)\n  if (!key) return []\n  const tokens = new Set<string>()\n  for (const word of key.split(' ')) {\n    if (!word) continue\n    const capped = word.slice(0, NAME_TOKEN_MAX_PREFIX)\n    for (let end = 1; end <= capped.length; end += 1) {\n      tokens.add(capped.slice(0, end))\n      if (tokens.size >= NAME_TOKEN_LIMIT) return [...tokens]\n    }\n  }\n  return [...tokens]\n}\n\n/**\n * The one token a typed query becomes.\n *\n * `array-contains` takes a single value, and Firestore allows only one such\n * clause per query — so a multi-word query cannot be an AND on the server.\n * The FIRST word is used, which is what a reader is narrowing by when they\n * type \"acme cof\": they see the Acme results and read the rest themselves.\n * Capped to the same prefix length the tokens were written at, or a longer\n * query would match a token that was never stored.\n */\nexport function nameSearchToken(query: string | null | undefined): string {\n  const key = nameSearchKey(query)\n  if (!key) return ''\n  return (key.split(' ')[0] ?? '').slice(0, NAME_TOKEN_MAX_PREFIX)\n}\n\n/**\n * The normalized name, reversed, so \"ends with\" becomes a prefix range.\n *\n * Firestore has one string operator that is not equality: the range. That\n * gives \"starts with\" directly — `>= q` and `<= q + ''` over\n * `nameLower` — and gives \"ends with\" nothing at all, because a range is\n * anchored at the front of the stored value.\n *\n * Reversing the stored key moves the end to the front. \"Acme Coffee\" is\n * stored as \"eeffoc emca\", and a search for names ending \"coffee\" becomes a\n * prefix range for \"eeffoc\" — the same query, on the same kind of index.\n *\n * Reversed by CODEPOINT (`[...key]`), not by UTF-16 unit: `split('')` cuts\n * surrogate pairs in half, so an emoji or a non-BMP character in a workspace\n * name would reverse into two lone surrogates and never match anything.\n */\nexport function nameSearchReversed(name: string | null | undefined): string {\n  return [...nameSearchKey(name)].reverse().join('')\n}\n\n/**\n * The three search fields that travel with a `name`, as one object.\n *\n * Every collection whose list is SEARCHED on the server carries them, and\n * carrying only some is the failure mode worth designing against: `orderBy`\n * drops a document missing the field it sorts by, and `array-contains` drops\n * one missing the array. Either way the record still LISTS normally, so the\n * gap shows up only as a search that quietly cannot find one row.\n *\n * ⚠️ Spread this at every write that sets `name`, and only where `name` is\n * actually being written — a partial write that stamped an empty key over a\n * real one would make the document unfindable by the name it still displays.\n */\nexport function nameSearchFields(name: string): {\n  name: string\n  nameLower: string\n  nameTokens: string[]\n  nameReversed: string\n} {\n  // `name` is INCLUDED so this is a drop-in replacement for writing `{ name }`.\n  // A helper that returned only the derived keys would be spread beside the\n  // name at four call sites, and the one that forgot would write search keys\n  // for a name it never stored.\n  return {\n    name,\n    nameLower: nameSearchKey(name),\n    nameTokens: nameSearchTokens(name),\n    nameReversed: nameSearchReversed(name),\n  }\n}\n"],"names":["nameSearchKey","name","trim","replace","toLowerCase","NAME_TOKEN_MAX_PREFIX","NAME_TOKEN_LIMIT","nameSearchTokens","key","tokens","Set","word","split","capped","slice","end","length","add","size","nameSearchToken","query","nameSearchReversed","reverse","join","nameSearchFields","nameLower","nameTokens","nameReversed"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED;;;;;;;;;;;;;;;;CAgBC,GACD,OAAO,SAASA,cAAcC,IAA+B;IAC3D,OAAO,CAACA,eAAAA,OAAQ,IAAIC,IAAI,GAAGC,OAAO,CAAC,QAAQ,KAAKC,WAAW;AAC7D;AAEA;;;;;;;;CAQC,GACD,OAAO,MAAMC,wBAAwB,GAAE;AAEvC,mFAAmF,GACnF,OAAO,MAAMC,mBAAmB,IAAG;AAEnC;;;;;;;;;;;;;;;;;;;;;;CAsBC,GACD,OAAO,SAASC,iBAAiBN,IAA+B;IAC9D,MAAMO,MAAMR,cAAcC;IAC1B,IAAI,CAACO,KAAK,OAAO,EAAE;IACnB,MAAMC,SAAS,IAAIC;IACnB,KAAK,MAAMC,QAAQH,IAAII,KAAK,CAAC,KAAM;QACjC,IAAI,CAACD,MAAM;QACX,MAAME,SAASF,KAAKG,KAAK,CAAC,GAAGT;QAC7B,IAAK,IAAIU,MAAM,GAAGA,OAAOF,OAAOG,MAAM,EAAED,OAAO,EAAG;YAChDN,OAAOQ,GAAG,CAACJ,OAAOC,KAAK,CAAC,GAAGC;YAC3B,IAAIN,OAAOS,IAAI,IAAIZ,kBAAkB,OAAO;mBAAIG;aAAO;QACzD;IACF;IACA,OAAO;WAAIA;KAAO;AACpB;AAEA;;;;;;;;;CASC,GACD,OAAO,SAASU,gBAAgBC,KAAgC;QAGtDZ;IAFR,MAAMA,MAAMR,cAAcoB;IAC1B,IAAI,CAACZ,KAAK,OAAO;IACjB,OAAO,EAACA,cAAAA,IAAII,KAAK,CAAC,IAAI,CAAC,EAAE,YAAjBJ,cAAqB,IAAIM,KAAK,CAAC,GAAGT;AAC5C;AAEA;;;;;;;;;;;;;;;CAeC,GACD,OAAO,SAASgB,mBAAmBpB,IAA+B;IAChE,OAAO;WAAID,cAAcC;KAAM,CAACqB,OAAO,GAAGC,IAAI,CAAC;AACjD;AAEA;;;;;;;;;;;;CAYC,GACD,OAAO,SAASC,iBAAiBvB,IAAY;IAM3C,8EAA8E;IAC9E,0EAA0E;IAC1E,2EAA2E;IAC3E,8BAA8B;IAC9B,OAAO;QACLA;QACAwB,WAAWzB,cAAcC;QACzByB,YAAYnB,iBAAiBN;QAC7B0B,cAAcN,mBAAmBpB;IACnC;AACF"}

package/src/lib/app-utils/node-capabilities.d.ts

@@ -0,0 +1,85 @@
+/**
+ * @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 AglynAttributeSchema } from '../foundation/definitions/components.types';
+/**
+ * What every NODE can do, as against what one component declares (AGL-3156).
+ *
+ * A component schema says what its own element is: a Stack's direction, a
+ * Button's label. A capability here says what any element can be made to do
+ * whatever it is — repeat over records, today — and the editor offers it on
+ * all of them, the way it offers visibility and animation.
+ *
+ * The declarations live in core because the capability does. The Attributes
+ * panel draws these fields, the published page's composition consumes the
+ * props they persist, and anything that has to DESCRIBE the palette an author
+ * works with reads them from here. Before this module each of those held its
+ * own copy of the list, so a capability that moved off a component schema fell
+ * out of every reader that walked component schemas to find it: repeat became a
+ * node capability and stopped being offered to a draft entirely, because the
+ * only list that named it was the one it had just left.
+ *
+ * Reached by path, never through a barrel. These are labels, descriptions and
+ * field kinds — editor weight, which a published page must not download.
+ */
+/**
+ * One field a capability contributes to every node, in the same shape a
+ * component schema declares an attribute in, so a reader that already walks
+ * attributes needs no second code path for these.
+ */
+export interface NodeCapabilityAttribute extends AglynAttributeSchema {
+    /**
+     * Offered only on a node that holds a child list. A control whose options
+     * both do the same thing is worse than no control.
+     */
+    requiresChildren?: boolean;
+    /** The fragment of the capability's docs page that explains this field. */
+    docsAnchor?: string;
+}
+/** One thing every node can be made to do. */
+export interface NodeCapability {
+    /** Stable id, and the docs page the fields link to. */
+    id: string;
+    /** What the Attributes panel calls the section. */
+    label: string;
+    /** One sentence describing the capability, for a catalog that lists it. */
+    summary: string;
+    /**
+     * The fields the capability contributes to every node. What a repeat is
+     * OVER is not among them — that belongs to the plugin that owns the rows,
+     * which registers a source of its own (`repeat-sources.ts`). These are the
+     * properties of the capability itself, shared by every source.
+     */
+    attributes: readonly NodeCapabilityAttribute[];
+}
+/**
+ * Repeating, on any element (AGL-3111).
+ *
+ * The bounds are properties of the REPEAT and not of the rows: the composition
+ * applies the same scope, filter, sort and limit whatever answered with the
+ * records, so they are declared once here rather than per source.
+ */
+export declare const REPEAT_NODE_CAPABILITY: NodeCapability;
+/**
+ * Every node-level capability, in the order an editor offers them.
+ *
+ * A reader that describes what an author can build reads this list beside the
+ * component schemas rather than instead of them. One that reads only the
+ * schemas is answering a question the product stopped being shaped like.
+ */
+export declare const NODE_CAPABILITIES: readonly NodeCapability[];
+/** The capability registered under `id`. */
+export declare function getNodeCapability(id: string): NodeCapability | undefined;

package/src/lib/app-utils/node-capabilities.js

@@ -0,0 +1,88 @@
+/**
+ * @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 { FieldComponentType } from "../foundation/definitions/components.types.js";
+import { REPEAT_MAX_RECORDS, REPEAT_SELF_PROP } from "./expand-repeatables.js";
+/**
+ * Repeating, on any element (AGL-3111).
+ *
+ * The bounds are properties of the REPEAT and not of the rows: the composition
+ * applies the same scope, filter, sort and limit whatever answered with the
+ * records, so they are declared once here rather than per source.
+ */ export const REPEAT_NODE_CAPABILITY = {
+    id: 'repeat',
+    label: 'Repeat',
+    summary: 'Renders an element once per record of the data it repeats over.',
+    attributes: [
+        {
+            name: REPEAT_SELF_PROP,
+            component: FieldComponentType.SELECT,
+            label: 'Repeat',
+            description: 'Whether each record gets a copy of this element, or a copy of what ' + 'is inside it. A row of cards repeats the card; a list that IS the ' + 'row repeats its contents.',
+            docsAnchor: '#what-repeats-the-element-or-whats-inside-it',
+            requiresChildren: true,
+            // A real value on the default option, never `''` (AGL-1451): an empty
+            // value cannot persist, so an author who switched to "This element"
+            // could never switch back.
+            initialValue: 'false',
+            options: [
+                {
+                    value: 'false',
+                    label: 'What is inside this element'
+                },
+                {
+                    value: 'true',
+                    label: 'This element'
+                }
+            ]
+        },
+        {
+            name: 'repeatLimit',
+            component: FieldComponentType.TEXT_FIELD,
+            type: 'number',
+            label: 'Repeat limit',
+            description: `Most records to render (blank = all, capped at ${REPEAT_MAX_RECORDS}).`,
+            docsAnchor: '#the-hundred-record-ceiling'
+        },
+        {
+            name: 'repeatFilter',
+            component: FieldComponentType.TEXT_FIELD,
+            label: 'Repeat filter',
+            description: 'Optional "field op value" filter, e.g. "price <= 20", ' + '"tier == plus", or "tags contains red". Ops: == != > >= < <= ' + `contains. Applies to the first ${REPEAT_MAX_RECORDS} records.`,
+            docsAnchor: '#bound-what-renders'
+        },
+        {
+            name: 'repeatSort',
+            component: FieldComponentType.TEXT_FIELD,
+            label: 'Repeat sort',
+            description: 'Optional "field" or "field desc" ordering, e.g. "price desc".',
+            docsAnchor: '#bound-what-renders'
+        }
+    ]
+};
+/**
+ * Every node-level capability, in the order an editor offers them.
+ *
+ * A reader that describes what an author can build reads this list beside the
+ * component schemas rather than instead of them. One that reads only the
+ * schemas is answering a question the product stopped being shaped like.
+ */ export const NODE_CAPABILITIES = [
+    REPEAT_NODE_CAPABILITY
+];
+/** The capability registered under `id`. */ export function getNodeCapability(id) {
+    return NODE_CAPABILITIES.find((capability)=>capability.id === id);
+}
+
+//# sourceMappingURL=node-capabilities.js.map

package/src/lib/app-utils/node-capabilities.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/node-capabilities.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  FieldComponentType,\n  type AglynAttributeSchema,\n} from '../foundation/definitions/components.types'\nimport { REPEAT_MAX_RECORDS, REPEAT_SELF_PROP } from './expand-repeatables'\n\n/**\n * What every NODE can do, as against what one component declares (AGL-3156).\n *\n * A component schema says what its own element is: a Stack's direction, a\n * Button's label. A capability here says what any element can be made to do\n * whatever it is — repeat over records, today — and the editor offers it on\n * all of them, the way it offers visibility and animation.\n *\n * The declarations live in core because the capability does. The Attributes\n * panel draws these fields, the published page's composition consumes the\n * props they persist, and anything that has to DESCRIBE the palette an author\n * works with reads them from here. Before this module each of those held its\n * own copy of the list, so a capability that moved off a component schema fell\n * out of every reader that walked component schemas to find it: repeat became a\n * node capability and stopped being offered to a draft entirely, because the\n * only list that named it was the one it had just left.\n *\n * Reached by path, never through a barrel. These are labels, descriptions and\n * field kinds — editor weight, which a published page must not download.\n */\n\n/**\n * One field a capability contributes to every node, in the same shape a\n * component schema declares an attribute in, so a reader that already walks\n * attributes needs no second code path for these.\n */\nexport interface NodeCapabilityAttribute extends AglynAttributeSchema {\n  /**\n   * Offered only on a node that holds a child list. A control whose options\n   * both do the same thing is worse than no control.\n   */\n  requiresChildren?: boolean\n  /** The fragment of the capability's docs page that explains this field. */\n  docsAnchor?: string\n}\n\n/** One thing every node can be made to do. */\nexport interface NodeCapability {\n  /** Stable id, and the docs page the fields link to. */\n  id: string\n  /** What the Attributes panel calls the section. */\n  label: string\n  /** One sentence describing the capability, for a catalog that lists it. */\n  summary: string\n  /**\n   * The fields the capability contributes to every node. What a repeat is\n   * OVER is not among them — that belongs to the plugin that owns the rows,\n   * which registers a source of its own (`repeat-sources.ts`). These are the\n   * properties of the capability itself, shared by every source.\n   */\n  attributes: readonly NodeCapabilityAttribute[]\n}\n\n/**\n * Repeating, on any element (AGL-3111).\n *\n * The bounds are properties of the REPEAT and not of the rows: the composition\n * applies the same scope, filter, sort and limit whatever answered with the\n * records, so they are declared once here rather than per source.\n */\nexport const REPEAT_NODE_CAPABILITY: NodeCapability = {\n  id: 'repeat',\n  label: 'Repeat',\n  summary: 'Renders an element once per record of the data it repeats over.',\n  attributes: [\n    {\n      name: REPEAT_SELF_PROP,\n      component: FieldComponentType.SELECT,\n      label: 'Repeat',\n      description:\n        'Whether each record gets a copy of this element, or a copy of what ' +\n        'is inside it. A row of cards repeats the card; a list that IS the ' +\n        'row repeats its contents.',\n      docsAnchor: '#what-repeats-the-element-or-whats-inside-it',\n      requiresChildren: true,\n      // A real value on the default option, never `''` (AGL-1451): an empty\n      // value cannot persist, so an author who switched to \"This element\"\n      // could never switch back.\n      initialValue: 'false',\n      options: [\n        { value: 'false', label: 'What is inside this element' },\n        { value: 'true', label: 'This element' },\n      ],\n    },\n    {\n      name: 'repeatLimit',\n      component: FieldComponentType.TEXT_FIELD,\n      type: 'number',\n      label: 'Repeat limit',\n      description: `Most records to render (blank = all, capped at ${REPEAT_MAX_RECORDS}).`,\n      docsAnchor: '#the-hundred-record-ceiling',\n    },\n    {\n      name: 'repeatFilter',\n      component: FieldComponentType.TEXT_FIELD,\n      label: 'Repeat filter',\n      description:\n        'Optional \"field op value\" filter, e.g. \"price <= 20\", ' +\n        '\"tier == plus\", or \"tags contains red\". Ops: == != > >= < <= ' +\n        `contains. Applies to the first ${REPEAT_MAX_RECORDS} records.`,\n      docsAnchor: '#bound-what-renders',\n    },\n    {\n      name: 'repeatSort',\n      component: FieldComponentType.TEXT_FIELD,\n      label: 'Repeat sort',\n      description:\n        'Optional \"field\" or \"field desc\" ordering, e.g. \"price desc\".',\n      docsAnchor: '#bound-what-renders',\n    },\n  ],\n}\n\n/**\n * Every node-level capability, in the order an editor offers them.\n *\n * A reader that describes what an author can build reads this list beside the\n * component schemas rather than instead of them. One that reads only the\n * schemas is answering a question the product stopped being shaped like.\n */\nexport const NODE_CAPABILITIES: readonly NodeCapability[] = [\n  REPEAT_NODE_CAPABILITY,\n]\n\n/** The capability registered under `id`. */\nexport function getNodeCapability(id: string): NodeCapability | undefined {\n  return NODE_CAPABILITIES.find((capability) => capability.id === id)\n}\n"],"names":["FieldComponentType","REPEAT_MAX_RECORDS","REPEAT_SELF_PROP","REPEAT_NODE_CAPABILITY","id","label","summary","attributes","name","component","SELECT","description","docsAnchor","requiresChildren","initialValue","options","value","TEXT_FIELD","type","NODE_CAPABILITIES","getNodeCapability","find","capability"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED,SACEA,kBAAkB,QAEb,gDAA4C;AACnD,SAASC,kBAAkB,EAAEC,gBAAgB,QAAQ,0BAAsB;AAuD3E;;;;;;CAMC,GACD,OAAO,MAAMC,yBAAyC;IACpDC,IAAI;IACJC,OAAO;IACPC,SAAS;IACTC,YAAY;QACV;YACEC,MAAMN;YACNO,WAAWT,mBAAmBU,MAAM;YACpCL,OAAO;YACPM,aACE,wEACA,uEACA;YACFC,YAAY;YACZC,kBAAkB;YAClB,sEAAsE;YACtE,oEAAoE;YACpE,2BAA2B;YAC3BC,cAAc;YACdC,SAAS;gBACP;oBAAEC,OAAO;oBAASX,OAAO;gBAA8B;gBACvD;oBAAEW,OAAO;oBAAQX,OAAO;gBAAe;aACxC;QACH;QACA;YACEG,MAAM;YACNC,WAAWT,mBAAmBiB,UAAU;YACxCC,MAAM;YACNb,OAAO;YACPM,aAAa,CAAC,+CAA+C,EAAEV,mBAAmB,EAAE,CAAC;YACrFW,YAAY;QACd;QACA;YACEJ,MAAM;YACNC,WAAWT,mBAAmBiB,UAAU;YACxCZ,OAAO;YACPM,aACE,2DACA,kEACA,CAAC,+BAA+B,EAAEV,mBAAmB,SAAS,CAAC;YACjEW,YAAY;QACd;QACA;YACEJ,MAAM;YACNC,WAAWT,mBAAmBiB,UAAU;YACxCZ,OAAO;YACPM,aACE;YACFC,YAAY;QACd;KACD;AACH,EAAC;AAED;;;;;;CAMC,GACD,OAAO,MAAMO,oBAA+C;IAC1DhB;CACD,CAAA;AAED,0CAA0C,GAC1C,OAAO,SAASiB,kBAAkBhB,EAAU;IAC1C,OAAOe,kBAAkBE,IAAI,CAAC,CAACC,aAAeA,WAAWlB,EAAE,KAAKA;AAClE"}

package/src/lib/app-utils/node-definition-sanitizer.d.ts

@@ -0,0 +1,164 @@
+/**
+ * @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 { SAFE_SRC_PATTERN } from './node-url-policy';
+import { SAFE_HREF_PATTERN } from './screen-link-value';
+/**
+ * Component ids publishable to the marketplace. Mirrors the persisted ids in
+ * plugins-mui (plugin.spec.ts) minus `reusableInstance` — nested
+ * instances would smuggle references to another tenant's private
+ * definitions — and minus `layoutSlot`, which is layout chrome. Keep sorted.
+ *
+ * The rule this list encodes is "inert and self-contained": an element that
+ * renders from its own props travels to another workspace intact. What stays
+ * out is what cannot — raw-HTML escape hatches (`customHtml`), references to
+ * another tenant's documents (`reusableInstance`), third-party code
+ * (`plugin`), host chrome (`layoutSlot`) and anything bound to the source
+ * site's data (`collection`, `product`).
+ *
+ * It must cover everything the besigner's palette offers under those terms, or
+ * the catalogue promises what the exporter refuses — which is how `section`
+ * came to be missing (AGL-1033): every Sections & Blocks preset composes it,
+ * so the whole category was unpublishable. `blocks-publishable.spec.ts` walks
+ * the presets and fails if this list falls behind them again.
+ */
+export declare const MARKETPLACE_COMPONENT_ID_ALLOWLIST: readonly string[];
+/**
+ * Email block ids publishable as an `emailTemplate` (AGL-657).
+ *
+ * A separate list from the page allowlist because the two vocabularies don't
+ * overlap — an email design is built entirely from `plugins-email` blocks, and
+ * page components (MUI, forms, video) don't survive an email client anyway.
+ *
+ * `emailHtml` is excluded deliberately, for the same reason `reusableInstance`
+ * is excluded above: it is a raw-HTML escape hatch, and a published template
+ * lands in another org's OUTGOING CUSTOMER EMAIL. Email clients don't run
+ * scripts, so this isn't XSS — it's that arbitrary markup sent from someone
+ * else's domain is a phishing and tracking-pixel vector that no amount of
+ * render-time sanitization makes reviewable. Keep sorted.
+ */
+export declare const MARKETPLACE_EMAIL_COMPONENT_ID_ALLOWLIST: readonly string[];
+/**
+ * Email block ids publishable as an `emailStarter` — the transactional list
+ * minus `emailRichtext`.
+ *
+ * Derived rather than written out, so a block added to the list above cannot
+ * silently miss this one. What it subtracts is the reason it exists.
+ *
+ * `emailRichtext` holds its content in an `html` prop, and the email renderer's
+ * `sanitize` hook defaults to identity with no production caller supplying one
+ * — so that prop reaches the recipient's inbox exactly as authored. On a
+ * transactional design that is the site's own author writing their own mail. In
+ * a STARTER it is a stranger's markup mailed from the shared sending domain
+ * under the tenant's From header, which is the raw-HTML escape hatch
+ * `emailHtml` was excluded for, wearing a friendlier block name. A remote
+ * `<img>` inside it is a tracking pixel that the src policy on `emailImage`
+ * would otherwise have caught.
+ *
+ * Subtracting the block is deliberate rather than sanitizing its markup: an
+ * allowlist over someone else's HTML is a judgment we would have to keep
+ * re-making, and everything rich text can express in an email — a heading, a
+ * paragraph, a link, a button — the remaining blocks already express as a
+ * structured tree we render ourselves.
+ */
+export declare const MARKETPLACE_EMAIL_STARTER_COMPONENT_ID_ALLOWLIST: readonly string[];
+/** Serialized definition size cap (Firestore doc limit is 1 MiB). */
+export declare const MARKETPLACE_DEFINITION_MAX_BYTES: number;
+/**
+ * The address rules a published node's `href` and `src` meet — the linking
+ * elements' navigable protocols, and https, inline or site-relative images
+ * (see `node-url-policy`).
+ *
+ * Exported under these names for the marketplace's property sanitizer, which
+ * holds a published property's Link default to the same rule as a published
+ * node's `href`, and an Image default to the `src` rule.
+ */
+export { SAFE_HREF_PATTERN as MARKETPLACE_SAFE_HREF, SAFE_SRC_PATTERN as MARKETPLACE_SAFE_SRC, };
+export type MarketplaceDefinitionNodes = Record<string, {
+    $id: string;
+    componentId: string;
+    pluginId?: string;
+    parentId: string | null;
+    props?: Record<string, unknown>;
+    nodes?: string[];
+}>;
+/**
+ * Validates and strips a host component definition for publishing:
+ * - only allowlisted component ids (no reusable instances, no layout chrome)
+ * - only the persisted node keys (drops runtime fields like resolvedProps)
+ * - the subtree reachable from `rootId` only, and a serialized size cap
+ *
+ * - per-node prop hardening (see `sanitizePublishedNodeProps`, AGL-784)
+ *
+ * XSS note: rich-text `html` props stay as-authored here — they are sanitized
+ * at render time (sanitize-rich-text allowlist), which also covers definitions
+ * written to Firestore directly (see docs/SECURITY_CONTENT_REVIEW.md). Props
+ * that are spread onto the DOM (`dangerouslySetInnerHTML`, `on*`, `href`,
+ * `src`) are hardened HERE as well, because publishing hands them to a
+ * different org's render tree.
+ */
+export declare function sanitizeMarketplaceDefinition(definition: {
+    rootId: string;
+    nodes: Record<string, any>;
+}, options?: {
+    /**
+     * Additional component ids permitted for this artifact type.
+     *
+     * `layoutSlot` is excluded from the shared allowlist because a slot in
+     * page content has nowhere to graft — but a published LAYOUT is
+     * meaningless without one (AGL-671). Scoped per call rather than added
+     * globally so page and component publishing stay unchanged.
+     */
+    extraComponentIds?: readonly string[];
+    /**
+     * Replaces the page allowlist outright, for artifact types built from a
+     * disjoint component vocabulary — an email design uses `plugins-email`
+     * blocks and nothing else (AGL-657), so EXTENDING the page list would
+     * green-light a `videoEmbed` or `form` that no email client can render.
+     */
+    componentIds?: readonly string[];
+    /**
+     * The properties the tree declares, as they are published beside it
+     * (AGL-2933). A node's `href` or `src` bound whole to one of the kind that
+     * holds that address is kept — see `sanitizePublishedNodeProps`. Absent
+     * for a tree that declares none, which keeps no binding.
+     */
+    declaredProps?: ReadonlyArray<{
+        name?: unknown;
+        type?: unknown;
+    }>;
+}): {
+    ok: true;
+    rootId: string;
+    nodes: MarketplaceDefinitionNodes;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * Converts a sanitized marketplace/AI definition (normalized map) into the
+ * nested node shape `canvas.addNodeFromPreset` grafts — ids regenerate on
+ * insert, so collisions with existing canvas nodes are impossible
+ * (AGL-169). A seen-set guards malformed self-referencing trees.
+ */
+export declare function marketplaceDefinitionToNested(rootId: string, nodes: MarketplaceDefinitionNodes): Record<string, unknown> | null;
+/**
+ * Field types a published dataset schema may declare (AGL-657). Mirrors
+ * `DATASET_FIELD_TYPES` in core; duplicated rather than imported to keep this
+ * module dependency-free (it is imported by API routes and client components
+ * alike), and asserted against the source of truth in the spec.
+ */
+export declare const MARKETPLACE_DATASET_FIELD_TYPES: readonly string[];