@aglyn/aglyn 1.0.0-beta.143

package/src/lib/app-utils/bandwidth-cap.js

@@ -0,0 +1,193 @@
+/**
+ * @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.
+ */ /**
+ * The free plan's BANDWIDTH HARD CAP (AGL-1967 / AGL-2070 / AGL-2155).
+ *
+ * Enforced from before public signups, so the cap is proven under real
+ * traffic while the cohort is small and a mistake is cheap. The requirement
+ * this module exists to make true: the free/hobby tier hard-caps, so that it
+ * always actually stays free.
+ *
+ * Until this shipped, bandwidth was the ONE billable dimension with no
+ * runtime refusal anywhere. Media ingress, forms, contacts, datasets, API and
+ * seats all hard-stop on free; `bandwidthGb: 5` appeared only in the plan
+ * table, in reporting arithmetic and in UI. A free site that went viral
+ * served every page and Aglyn paid the egress with no ceiling.
+ *
+ * ## Why a MARKER on the org doc, and not a check
+ *
+ * The obvious implementation — read the page-view counter before rendering —
+ * is the one thing this cap must not do. Page views are counted AFTER the
+ * fact, by a client beacon into `hosts/{id}/analytics/{day}`; consulting them
+ * per render would put a Firestore read on the hot path of every public page
+ * on the platform, paid by every PAYING customer too, to answer a question
+ * only free orgs can ever fail. That is the exact cost the whole ISR/cache
+ * design exists to avoid.
+ *
+ * So the decision is made where the arithmetic already happens, and its
+ * verdict is denormalized onto the org document as {@link OrgBandwidthCap}.
+ * The serving path then reads it from `getOrgBilling`, the org doc it ALREADY
+ * loads and caches for 60 seconds as "the suspension gate and every
+ * entitlement input for the render". **The cap costs zero additional reads.**
+ *
+ * ### TWO writers, and neither is on the render path (AGL-2413)
+ *
+ * 1. `apps/tenant/app/api/analytics/collect` — the beacon that WRITES the
+ *    page-view counter, on its existing 1-in-200 sample. It already sums this
+ *    month with this query and already loads this org doc for the abuse
+ *    ceiling, so the cap rides both for free.
+ * 2. `api/billing/usage-alerts` — the daily sweep, which sums page views
+ *    ORG-WIDE across up to 100 hosts and is therefore the backstop for any
+ *    org running more than one site.
+ *
+ * The beacon is the one that matters, and it exists because the sweep alone
+ * was not a cap at all: it skips every org with no `plan` field, and
+ * `createOrganization` writes none — so for the whole never-subscribed free
+ * tier the marker had never once been written. The general lesson: **a cap
+ * that lives only in a scheduled sweep stops existing the moment the sweep
+ * does not run.** Every other free dimension refuses at the
+ * point of use; this one now does too.
+ *
+ * ### The latency, stated plainly
+ *
+ * The beacon closes the window to the sampling slop — at most
+ * (200 x instances) page views past the band, against a free band of ~8,700 —
+ * so on the common single-site free org the cap engages within a couple of
+ * hundred views. It is still not a per-request throttle, and the honest way to
+ * describe it is "a free site cannot run away", not "a free site cannot serve
+ * byte 5,368,709,121". Do not close the remaining slop by adding a read to the
+ * RENDER path; the place to close it is the CDN, which is Vercel configuration
+ * and not a repo change.
+ *
+ * ### It RELEASES immediately, though
+ *
+ * Asymmetric on purpose, and this is why {@link bandwidthCapEngaged} re-reads
+ * the plan rather than trusting the marker alone. An org that upgrades starts
+ * serving again on the next org-doc TTL — about 60 seconds — without waiting
+ * for any cron to run or any flag to be cleared. Making somebody who has just
+ * paid wait until tomorrow morning for their site to come back is the failure
+ * mode that would make this feature worse than the hole it closes.
+ *
+ * Nothing ever CLEARS the marker either: it names the month it was written
+ * for, so a new month simply stops matching. A cap whose lift depends on a
+ * write is a cap that stays engaged when the writer fails.
+ */ import { isCustomPricedPlan, planMetersInfraOverage, resolveEffectivePlan, resolveOrgEntitlements } from "./plan-entitlements.js";
+/**
+ * The month key the marker is stamped with: UTC `YYYY-MM`, the same shape as
+ * `submissionMonthKey` and the `orgs/{id}/usage/{month}` document id, and the
+ * same key `usage-alerts` dedupes its own guards by. One month boundary
+ * across the platform — a cap that reset on a different day from the counter
+ * it is derived from would engage against last month's traffic.
+ */ export function bandwidthCapMonthKey(now = new Date()) {
+    return now.toISOString().slice(0, 7);
+}
+/**
+ * How long a crawler or uptime check is told to wait.
+ *
+ * NOT "until the month rolls over", which is the arithmetically correct
+ * answer and can be three weeks. The site can come back at any moment — the
+ * owner upgrades and the release path above restores it in about a minute —
+ * so a multi-week `Retry-After` would tell Google to stop looking long after
+ * the site was serving again. An hour is short enough to be wrong in the
+ * recoverable direction.
+ */ export const BANDWIDTH_CAP_RETRY_AFTER_SECONDS = 3600;
+/**
+ * Is this org's serving currently refused by the free-plan bandwidth cap?
+ *
+ * THREE conditions, and the second and third are the ones that matter:
+ *
+ *  1. the marker names the CURRENT month (a stale marker is not a cap);
+ *  2. the org's plan does not meter infrastructure overage — i.e. it is the
+ *     free plan, or a paid plan held as a staff comp (AGL-3034), which has no
+ *     subscription to bill past the band either. Paid plans BILL bandwidth
+ *     past the band and are never cut off; that promise is older than this
+ *     cap and this function is where it is kept. Re-derived from the CURRENT
+ *     plan on every read, which is what releases an upgraded org without a
+ *     write;
+ *  3. the plan is not custom-priced, and its band is finite. Enterprise also
+ *     answers false to `planMetersInfraOverage` — its price is negotiated —
+ *     and since 2026-09-07 its band is a FINITE fallback (twice Agency's), so
+ *     "unmetered and finite" would describe a contracted customer exactly as
+ *     it describes a free one. Its traffic is paid for by agreement, not by
+ *     invoice, and this cap is the free plan's rule alone: an enterprise org
+ *     carrying a marker some future writer left behind is never refused.
+ *     Belt and braces: today's writer cannot produce that marker, and this
+ *     makes it impossible rather than merely unreachable.
+ *
+ * Fail OPEN on anything unrecognised. A missing org, a malformed marker or a
+ * plan this build cannot read all serve the site: an unreadable org doc is an
+ * outage, and taking a customer's website down over one is not a cap, it is
+ * the incident.
+ */ export function bandwidthCapEngaged(org, now = new Date()) {
+    if (!org) return false;
+    if (planMetersInfraOverage(org)) return false;
+    if (isCustomPricedPlan(resolveEffectivePlan(org))) return false;
+    if (!Number.isFinite(resolveOrgEntitlements(org).bandwidthGb)) return false;
+    const cap = org.bandwidthCap;
+    if (!cap || typeof cap !== 'object') return false;
+    return cap.month === bandwidthCapMonthKey(now);
+}
+/**
+ * Should the cap be ENGAGED for this org-month? The writer's half of the
+ * question, kept beside the reader's so the two cannot drift apart.
+ *
+ * Takes the measured figure and the band rather than reading anything, so the
+ * cron passes in the very numbers it alerts on. `>` and not `>=`: an org
+ * exactly at its band has used what it was given and is not over it.
+ */ export function bandwidthCapShouldEngage(options) {
+    const { org, usedBandwidthGb, includedBandwidthGb } = options;
+    if (planMetersInfraOverage(org)) return false;
+    // The reader's third condition, kept in step: a custom-priced plan is paid
+    // for by agreement and is never paused, whatever its band resolves to.
+    if (isCustomPricedPlan(resolveEffectivePlan(org))) return false;
+    if (!Number.isFinite(includedBandwidthGb) || !(includedBandwidthGb > 0)) {
+        return false;
+    }
+    return usedBandwidthGb > includedBandwidthGb;
+}
+/**
+ * The visitor's sentence.
+ *
+ * Constrained the same way the form abuse-ceiling copy is (AGL-1666), and for
+ * the same reason: the person reading it is a stranger to the site, so it
+ * must not disclose the owner's plan, their bill, or anything about their
+ * account beyond the one fact that makes the page they asked for absent. It
+ * says what happened, that it is not their fault and not permanent, and when
+ * it ends — and then stops. "Upgrade your plan" belongs in the owner's
+ * console and their inbox, which is where the usage alert already puts it,
+ * not on a page shown to their readers.
+ *
+ * Deliberately NOT routed through `lockdownNotice`. A lockdown is the panic
+ * button — staff-set, security or billing, "contact support" — and its copy
+ * would be a lie here in both directions: nobody took this site down and
+ * support cannot lift it. Reusing the RENDERING channel (the 503 notice page)
+ * while keeping the WORDS separate is the split that keeps both honest.
+ */ export function bandwidthCapNotice() {
+    return {
+        title: 'Over the monthly traffic limit',
+        body: 'This site has used all of the traffic included with it this month, ' + 'so its pages are paused until the start of next month. Nothing is ' + 'wrong with your connection, and nothing here has been removed.'
+    };
+}
+/**
+ * The refusal code on the machine-readable half of the verdict, so a caller
+ * can tell a capped site from a locked one. The two answer the same HTTP
+ * status from the same notice page on purpose — a 503 with `Retry-After` is
+ * the only status that tells a crawler "come back", where a 402 or a 403
+ * risks a customer's site being de-indexed over one busy month — so the
+ * status discriminates nothing and this code is the whole discriminator.
+ */ export const BANDWIDTH_CAP_CODE = 'bandwidth-cap';
+
+//# sourceMappingURL=bandwidth-cap.js.map

package/src/lib/app-utils/bandwidth-cap.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/bandwidth-cap.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 * The free plan's BANDWIDTH HARD CAP (AGL-1967 / AGL-2070 / AGL-2155).\n *\n * Enforced from before public signups, so the cap is proven under real\n * traffic while the cohort is small and a mistake is cheap. The requirement\n * this module exists to make true: the free/hobby tier hard-caps, so that it\n * always actually stays free.\n *\n * Until this shipped, bandwidth was the ONE billable dimension with no\n * runtime refusal anywhere. Media ingress, forms, contacts, datasets, API and\n * seats all hard-stop on free; `bandwidthGb: 5` appeared only in the plan\n * table, in reporting arithmetic and in UI. A free site that went viral\n * served every page and Aglyn paid the egress with no ceiling.\n *\n * ## Why a MARKER on the org doc, and not a check\n *\n * The obvious implementation — read the page-view counter before rendering —\n * is the one thing this cap must not do. Page views are counted AFTER the\n * fact, by a client beacon into `hosts/{id}/analytics/{day}`; consulting them\n * per render would put a Firestore read on the hot path of every public page\n * on the platform, paid by every PAYING customer too, to answer a question\n * only free orgs can ever fail. That is the exact cost the whole ISR/cache\n * design exists to avoid.\n *\n * So the decision is made where the arithmetic already happens, and its\n * verdict is denormalized onto the org document as {@link OrgBandwidthCap}.\n * The serving path then reads it from `getOrgBilling`, the org doc it ALREADY\n * loads and caches for 60 seconds as \"the suspension gate and every\n * entitlement input for the render\". **The cap costs zero additional reads.**\n *\n * ### TWO writers, and neither is on the render path (AGL-2413)\n *\n * 1. `apps/tenant/app/api/analytics/collect` — the beacon that WRITES the\n *    page-view counter, on its existing 1-in-200 sample. It already sums this\n *    month with this query and already loads this org doc for the abuse\n *    ceiling, so the cap rides both for free.\n * 2. `api/billing/usage-alerts` — the daily sweep, which sums page views\n *    ORG-WIDE across up to 100 hosts and is therefore the backstop for any\n *    org running more than one site.\n *\n * The beacon is the one that matters, and it exists because the sweep alone\n * was not a cap at all: it skips every org with no `plan` field, and\n * `createOrganization` writes none — so for the whole never-subscribed free\n * tier the marker had never once been written. The general lesson: **a cap\n * that lives only in a scheduled sweep stops existing the moment the sweep\n * does not run.** Every other free dimension refuses at the\n * point of use; this one now does too.\n *\n * ### The latency, stated plainly\n *\n * The beacon closes the window to the sampling slop — at most\n * (200 x instances) page views past the band, against a free band of ~8,700 —\n * so on the common single-site free org the cap engages within a couple of\n * hundred views. It is still not a per-request throttle, and the honest way to\n * describe it is \"a free site cannot run away\", not \"a free site cannot serve\n * byte 5,368,709,121\". Do not close the remaining slop by adding a read to the\n * RENDER path; the place to close it is the CDN, which is Vercel configuration\n * and not a repo change.\n *\n * ### It RELEASES immediately, though\n *\n * Asymmetric on purpose, and this is why {@link bandwidthCapEngaged} re-reads\n * the plan rather than trusting the marker alone. An org that upgrades starts\n * serving again on the next org-doc TTL — about 60 seconds — without waiting\n * for any cron to run or any flag to be cleared. Making somebody who has just\n * paid wait until tomorrow morning for their site to come back is the failure\n * mode that would make this feature worse than the hole it closes.\n *\n * Nothing ever CLEARS the marker either: it names the month it was written\n * for, so a new month simply stops matching. A cap whose lift depends on a\n * write is a cap that stays engaged when the writer fails.\n */\n\nimport type { AglynOrgBilling, OrgBandwidthCap } from '../foundation'\nimport {\n  isCustomPricedPlan,\n  planMetersInfraOverage,\n  resolveEffectivePlan,\n  resolveOrgEntitlements,\n} from './plan-entitlements'\n\n/**\n * The month key the marker is stamped with: UTC `YYYY-MM`, the same shape as\n * `submissionMonthKey` and the `orgs/{id}/usage/{month}` document id, and the\n * same key `usage-alerts` dedupes its own guards by. One month boundary\n * across the platform — a cap that reset on a different day from the counter\n * it is derived from would engage against last month's traffic.\n */\nexport function bandwidthCapMonthKey(now: Date = new Date()): string {\n  return now.toISOString().slice(0, 7)\n}\n\n/**\n * How long a crawler or uptime check is told to wait.\n *\n * NOT \"until the month rolls over\", which is the arithmetically correct\n * answer and can be three weeks. The site can come back at any moment — the\n * owner upgrades and the release path above restores it in about a minute —\n * so a multi-week `Retry-After` would tell Google to stop looking long after\n * the site was serving again. An hour is short enough to be wrong in the\n * recoverable direction.\n */\nexport const BANDWIDTH_CAP_RETRY_AFTER_SECONDS = 3600\n\n/**\n * Is this org's serving currently refused by the free-plan bandwidth cap?\n *\n * THREE conditions, and the second and third are the ones that matter:\n *\n *  1. the marker names the CURRENT month (a stale marker is not a cap);\n *  2. the org's plan does not meter infrastructure overage — i.e. it is the\n *     free plan, or a paid plan held as a staff comp (AGL-3034), which has no\n *     subscription to bill past the band either. Paid plans BILL bandwidth\n *     past the band and are never cut off; that promise is older than this\n *     cap and this function is where it is kept. Re-derived from the CURRENT\n *     plan on every read, which is what releases an upgraded org without a\n *     write;\n *  3. the plan is not custom-priced, and its band is finite. Enterprise also\n *     answers false to `planMetersInfraOverage` — its price is negotiated —\n *     and since 2026-09-07 its band is a FINITE fallback (twice Agency's), so\n *     \"unmetered and finite\" would describe a contracted customer exactly as\n *     it describes a free one. Its traffic is paid for by agreement, not by\n *     invoice, and this cap is the free plan's rule alone: an enterprise org\n *     carrying a marker some future writer left behind is never refused.\n *     Belt and braces: today's writer cannot produce that marker, and this\n *     makes it impossible rather than merely unreachable.\n *\n * Fail OPEN on anything unrecognised. A missing org, a malformed marker or a\n * plan this build cannot read all serve the site: an unreadable org doc is an\n * outage, and taking a customer's website down over one is not a cap, it is\n * the incident.\n */\nexport function bandwidthCapEngaged(\n  org: Partial<AglynOrgBilling> | null | undefined,\n  now: Date = new Date(),\n): boolean {\n  if (!org) return false\n  if (planMetersInfraOverage(org)) return false\n  if (isCustomPricedPlan(resolveEffectivePlan(org))) return false\n  if (!Number.isFinite(resolveOrgEntitlements(org).bandwidthGb)) return false\n  const cap = org.bandwidthCap\n  if (!cap || typeof cap !== 'object') return false\n  return cap.month === bandwidthCapMonthKey(now)\n}\n\n/**\n * Should the cap be ENGAGED for this org-month? The writer's half of the\n * question, kept beside the reader's so the two cannot drift apart.\n *\n * Takes the measured figure and the band rather than reading anything, so the\n * cron passes in the very numbers it alerts on. `>` and not `>=`: an org\n * exactly at its band has used what it was given and is not over it.\n */\nexport function bandwidthCapShouldEngage(options: {\n  org: Partial<AglynOrgBilling> | null | undefined\n  usedBandwidthGb: number\n  includedBandwidthGb: number\n}): boolean {\n  const { org, usedBandwidthGb, includedBandwidthGb } = options\n  if (planMetersInfraOverage(org)) return false\n  // The reader's third condition, kept in step: a custom-priced plan is paid\n  // for by agreement and is never paused, whatever its band resolves to.\n  if (isCustomPricedPlan(resolveEffectivePlan(org))) return false\n  if (!Number.isFinite(includedBandwidthGb) || !(includedBandwidthGb > 0)) {\n    return false\n  }\n  return usedBandwidthGb > includedBandwidthGb\n}\n\n/** What a visitor sees on a capped site. */\nexport interface BandwidthCapNotice {\n  title: string\n  body: string\n}\n\n/**\n * The visitor's sentence.\n *\n * Constrained the same way the form abuse-ceiling copy is (AGL-1666), and for\n * the same reason: the person reading it is a stranger to the site, so it\n * must not disclose the owner's plan, their bill, or anything about their\n * account beyond the one fact that makes the page they asked for absent. It\n * says what happened, that it is not their fault and not permanent, and when\n * it ends — and then stops. \"Upgrade your plan\" belongs in the owner's\n * console and their inbox, which is where the usage alert already puts it,\n * not on a page shown to their readers.\n *\n * Deliberately NOT routed through `lockdownNotice`. A lockdown is the panic\n * button — staff-set, security or billing, \"contact support\" — and its copy\n * would be a lie here in both directions: nobody took this site down and\n * support cannot lift it. Reusing the RENDERING channel (the 503 notice page)\n * while keeping the WORDS separate is the split that keeps both honest.\n */\nexport function bandwidthCapNotice(): BandwidthCapNotice {\n  return {\n    title: 'Over the monthly traffic limit',\n    body:\n      'This site has used all of the traffic included with it this month, ' +\n      'so its pages are paused until the start of next month. Nothing is ' +\n      'wrong with your connection, and nothing here has been removed.',\n  }\n}\n\n/**\n * The refusal code on the machine-readable half of the verdict, so a caller\n * can tell a capped site from a locked one. The two answer the same HTTP\n * status from the same notice page on purpose — a 503 with `Retry-After` is\n * the only status that tells a crawler \"come back\", where a 402 or a 403\n * risks a customer's site being de-indexed over one busy month — so the\n * status discriminates nothing and this code is the whole discriminator.\n */\nexport const BANDWIDTH_CAP_CODE = 'bandwidth-cap'\n"],"names":["isCustomPricedPlan","planMetersInfraOverage","resolveEffectivePlan","resolveOrgEntitlements","bandwidthCapMonthKey","now","Date","toISOString","slice","BANDWIDTH_CAP_RETRY_AFTER_SECONDS","bandwidthCapEngaged","org","Number","isFinite","bandwidthGb","cap","bandwidthCap","month","bandwidthCapShouldEngage","options","usedBandwidthGb","includedBandwidthGb","bandwidthCapNotice","title","body","BANDWIDTH_CAP_CODE"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAuEC,GAGD,SACEA,kBAAkB,EAClBC,sBAAsB,EACtBC,oBAAoB,EACpBC,sBAAsB,QACjB,yBAAqB;AAE5B;;;;;;CAMC,GACD,OAAO,SAASC,qBAAqBC,MAAY,IAAIC,MAAM;IACzD,OAAOD,IAAIE,WAAW,GAAGC,KAAK,CAAC,GAAG;AACpC;AAEA;;;;;;;;;CASC,GACD,OAAO,MAAMC,oCAAoC,KAAI;AAErD;;;;;;;;;;;;;;;;;;;;;;;;;;;CA2BC,GACD,OAAO,SAASC,oBACdC,GAAgD,EAChDN,MAAY,IAAIC,MAAM;IAEtB,IAAI,CAACK,KAAK,OAAO;IACjB,IAAIV,uBAAuBU,MAAM,OAAO;IACxC,IAAIX,mBAAmBE,qBAAqBS,OAAO,OAAO;IAC1D,IAAI,CAACC,OAAOC,QAAQ,CAACV,uBAAuBQ,KAAKG,WAAW,GAAG,OAAO;IACtE,MAAMC,MAAMJ,IAAIK,YAAY;IAC5B,IAAI,CAACD,OAAO,OAAOA,QAAQ,UAAU,OAAO;IAC5C,OAAOA,IAAIE,KAAK,KAAKb,qBAAqBC;AAC5C;AAEA;;;;;;;CAOC,GACD,OAAO,SAASa,yBAAyBC,OAIxC;IACC,MAAM,EAAER,GAAG,EAAES,eAAe,EAAEC,mBAAmB,EAAE,GAAGF;IACtD,IAAIlB,uBAAuBU,MAAM,OAAO;IACxC,2EAA2E;IAC3E,uEAAuE;IACvE,IAAIX,mBAAmBE,qBAAqBS,OAAO,OAAO;IAC1D,IAAI,CAACC,OAAOC,QAAQ,CAACQ,wBAAwB,CAAEA,CAAAA,sBAAsB,CAAA,GAAI;QACvE,OAAO;IACT;IACA,OAAOD,kBAAkBC;AAC3B;AAQA;;;;;;;;;;;;;;;;;CAiBC,GACD,OAAO,SAASC;IACd,OAAO;QACLC,OAAO;QACPC,MACE,wEACA,uEACA;IACJ;AACF;AAEA;;;;;;;CAOC,GACD,OAAO,MAAMC,qBAAqB,gBAAe"}

package/src/lib/app-utils/binding-token-catalog.d.ts

@@ -0,0 +1,82 @@
+/**
+ * @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 DatasetModel } from './dataset-models';
+/**
+ * Browsable data-placeholder catalogs for the designer's insert picker
+ * (AGL-583). Hand-typing `{{entry.title}}` stays the advanced path; these
+ * catalogs give every token a friendly label + description so editors can
+ * browse and insert instead of memorizing the grammar.
+ *
+ * The token STRINGS are owned elsewhere — `collectionEntryTokens`
+ * (collection-entries.ts) and the tenant compose pipeline resolve them —
+ * this module only names them for pickers. The spec cross-checks the entry
+ * catalog against the resolver so the two can never drift.
+ */
+export interface BindingTokenCatalogEntry {
+    /** The literal token inserted into the prop, e.g. `{{entry.title}}`. */
+    token: string;
+    /** Friendly picker label, e.g. `Title`. */
+    label: string;
+    /** One-line description shown as the option's secondary text. */
+    description?: string;
+}
+/**
+ * `{{entry.*}}` tokens (AGL-105/551/582) — resolve per entry inside a
+ * Collection entries block and page-wide on entry-template screens.
+ * Mirrors {@link collectionEntryTokens}; the spec enforces the mirror.
+ */
+export declare const ENTRY_TOKEN_CATALOG: readonly BindingTokenCatalogEntry[];
+/**
+ * `{{collection.*}}` and `{{pagination.*}}` tokens (AGL-551/1321/1386) —
+ * resolve on collection list/entry template screens (see the tenant compose
+ * pipeline's collection tokens).
+ *
+ * The category and pagination tokens all resolve to the empty string where
+ * they do not apply, so they are safe to bind unconditionally: ONE list
+ * screen serves the bare listing, every `/page/{n}` and every
+ * `/category/{slug}`, and a template has no runtime conditional to vary
+ * itself with.
+ */
+export declare const COLLECTION_TOKEN_CATALOG: readonly BindingTokenCatalogEntry[];
+/**
+ * `{{author.*}}` tokens (AGL-2518) — resolve on an author's own page,
+ * `/author/{slug}`.
+ *
+ * Empty everywhere else, like the category tokens above and for the same
+ * reason: a template has no runtime conditional, so the tokens have to be the
+ * thing that varies. A heading bound to `{{author.name}}` prints a name on an
+ * author page and nothing anywhere else.
+ *
+ * The `{{pagination.*}}` tokens resolve HERE TOO, over this author's own
+ * archive — deliberately the same four names a collection listing uses, so a
+ * pager built once works on both.
+ */
+export declare const AUTHOR_TOKEN_CATALOG: readonly BindingTokenCatalogEntry[];
+/**
+ * Renders an `{{item.*}}` token for a dataset field, optionally hopping
+ * one reference to a field of the referenced record (AGL-180). Always
+ * takes the stable model field ID — display names are labels only.
+ */
+export declare function datasetItemToken(fieldId: string, targetFieldId?: string): string;
+/**
+ * Dataset-item token entries for a repeatable container's model: one per
+ * field in model order, labeled with the CURRENT display name while the
+ * token carries the stable reference id (AGL-578 — renaming a label never
+ * breaks bindings). Reference fields with a configured display field also
+ * get their one-hop token (`{{item.author.name}}`).
+ */
+export declare function datasetItemTokens(model: DatasetModel): BindingTokenCatalogEntry[];

package/src/lib/app-utils/binding-token-catalog.js

@@ -0,0 +1,293 @@
+/**
+ * @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 { DATASET_FIELD_TYPE_LABELS } from "./dataset-models.js";
+import { humanizeDatasetFieldId } from "./datasets.js";
+/**
+ * `{{entry.*}}` tokens (AGL-105/551/582) — resolve per entry inside a
+ * Collection entries block and page-wide on entry-template screens.
+ * Mirrors {@link collectionEntryTokens}; the spec enforces the mirror.
+ */ export const ENTRY_TOKEN_CATALOG = [
+    {
+        token: '{{entry.title}}',
+        label: 'Title',
+        description: 'The entry headline.'
+    },
+    {
+        token: '{{entry.excerpt}}',
+        label: 'Excerpt',
+        description: 'Short summary text.'
+    },
+    {
+        token: '{{entry.body}}',
+        label: 'Body',
+        description: 'The full entry body.'
+    },
+    {
+        token: '{{entry.url}}',
+        label: 'Link URL',
+        description: 'Auto-route to the entry page.'
+    },
+    {
+        token: '{{entry.date}}',
+        label: 'Published date',
+        description: 'Formatted publish date.'
+    },
+    /*
+    Beside the readable date on purpose: a designer reaching for "the date" in
+    a Video element's Publication date field has to see that the readable one
+    is the wrong pick there, and why.
+  */ {
+        token: '{{entry.publishedAt}}',
+        label: 'Publish timestamp',
+        description: 'The publish date and time in ISO 8601, for a field that needs a ' + 'machine-readable date, such as a Video element’s publication date.'
+    },
+    {
+        token: '{{entry.author}}',
+        label: 'Author',
+        description: 'The byline set on the entry.'
+    },
+    {
+        token: '{{entry.authorBio}}',
+        label: 'Author bio',
+        description: 'Blurb from the author’s record.'
+    },
+    {
+        token: '{{entry.authorImage}}',
+        label: 'Author portrait',
+        description: 'Portrait or logo from the author’s record.'
+    },
+    {
+        token: '{{entry.authorUrl}}',
+        label: 'Author link',
+        description: 'The author’s own page.'
+    },
+    {
+        token: '{{entry.authorPageUrl}}',
+        label: 'Author page',
+        description: 'This author’s page on this site — everything they wrote, across every ' + 'collection. Separate from Author link, which is their own site.'
+    },
+    {
+        token: '{{entry.slug}}',
+        label: 'Slug',
+        description: 'URL-safe entry identifier.'
+    },
+    /*
+    Named "Its collection…" rather than "Collection…", which is what these
+    describe and also exactly what the `{{collection.*}}` entries below are
+    called. The picker groups options by heading, so the two sets sit apart —
+    but a designer scanning it reads the LABEL, and two options reading
+    "Collection name" three lines apart is a choice made by guessing. The
+    pronoun is doing real work: on the one page where both resolve, they mean
+    different collections.
+  */ {
+        token: '{{entry.collection}}',
+        label: 'Its collection',
+        description: 'Which section this entry belongs to. Worth binding on a listing that ' + 'MIXES collections — an author page — where a card otherwise cannot ' + 'tell a release note from an essay.'
+    },
+    {
+        token: '{{entry.collectionSlug}}',
+        label: 'Its collection slug',
+        description: 'That collection’s URL segment.'
+    },
+    {
+        token: '{{entry.collectionUrl}}',
+        label: 'Its collection link',
+        description: 'The listing this entry belongs to.'
+    },
+    {
+        token: '{{entry.coverImage}}',
+        label: 'Cover image',
+        description: 'Cover image URL.'
+    },
+    {
+        token: '{{entry.coverVideo}}',
+        label: 'Featured video',
+        description: 'The featured video’s source — a library film, a video link or a ' + 'Wistia link — for a Video element.'
+    },
+    {
+        token: '{{entry.category}}',
+        label: 'Category',
+        description: 'The entry category.'
+    },
+    {
+        token: '{{entry.tags}}',
+        label: 'Tags',
+        description: 'Tags, comma separated.'
+    },
+    {
+        token: '{{entry.seoTitle}}',
+        label: 'SEO title',
+        description: 'Search title; falls back to Title.'
+    },
+    {
+        token: '{{entry.seoDescription}}',
+        label: 'SEO description',
+        description: 'Meta description; falls back to Excerpt.'
+    }
+];
+/**
+ * `{{collection.*}}` and `{{pagination.*}}` tokens (AGL-551/1321/1386) —
+ * resolve on collection list/entry template screens (see the tenant compose
+ * pipeline's collection tokens).
+ *
+ * The category and pagination tokens all resolve to the empty string where
+ * they do not apply, so they are safe to bind unconditionally: ONE list
+ * screen serves the bare listing, every `/page/{n}` and every
+ * `/category/{slug}`, and a template has no runtime conditional to vary
+ * itself with.
+ */ export const COLLECTION_TOKEN_CATALOG = [
+    {
+        token: '{{collection.name}}',
+        label: 'Collection name',
+        description: 'Display name of the routed collection.'
+    },
+    {
+        token: '{{collection.slug}}',
+        label: 'Collection slug',
+        description: 'URL slug of the routed collection.'
+    },
+    {
+        token: '{{collection.category}}',
+        label: 'Filtered category',
+        description: 'Category the URL filtered on; empty when unfiltered.'
+    },
+    {
+        token: '{{collection.categorySlug}}',
+        label: 'Filtered category slug',
+        description: 'That category’s URL segment; empty when unfiltered.'
+    },
+    {
+        token: '{{pagination.page}}',
+        label: 'Current page',
+        description: 'Page number this URL is showing.'
+    },
+    {
+        token: '{{pagination.totalPages}}',
+        label: 'Total pages',
+        description: 'Pages in the listing, after any category filter.'
+    },
+    {
+        token: '{{pagination.prevUrl}}',
+        label: 'Previous page link',
+        description: 'Keeps the category; empty on the first page.'
+    },
+    {
+        token: '{{pagination.nextUrl}}',
+        label: 'Next page link',
+        description: 'Keeps the category; empty on the last page.'
+    }
+];
+/**
+ * `{{author.*}}` tokens (AGL-2518) — resolve on an author's own page,
+ * `/author/{slug}`.
+ *
+ * Empty everywhere else, like the category tokens above and for the same
+ * reason: a template has no runtime conditional, so the tokens have to be the
+ * thing that varies. A heading bound to `{{author.name}}` prints a name on an
+ * author page and nothing anywhere else.
+ *
+ * The `{{pagination.*}}` tokens resolve HERE TOO, over this author's own
+ * archive — deliberately the same four names a collection listing uses, so a
+ * pager built once works on both.
+ */ export const AUTHOR_TOKEN_CATALOG = [
+    {
+        token: '{{author.name}}',
+        label: 'Name',
+        description: 'The byline this page collects.'
+    },
+    {
+        token: '{{author.bio}}',
+        label: 'Bio',
+        description: 'Their blurb, from the author record.'
+    },
+    {
+        token: '{{author.image}}',
+        label: 'Portrait',
+        description: 'Their portrait or logo, from the author record.'
+    },
+    {
+        token: '{{author.jobTitle}}',
+        label: 'Role',
+        description: 'Their job title; empty for an Organization author.'
+    },
+    {
+        token: '{{author.worksFor}}',
+        label: 'Organization',
+        description: 'Who they write for; empty for an Organization author.'
+    },
+    {
+        token: '{{author.url}}',
+        label: 'Their own site',
+        description: 'The url on their record — a personal site, not this page. Empty when ' + 'they have none.'
+    },
+    {
+        token: '{{author.pageUrl}}',
+        label: 'This page',
+        description: 'The canonical address of the page you are designing.'
+    },
+    {
+        token: '{{author.entryCount}}',
+        label: 'Post count',
+        description: 'How many entries they have published, across every collection.'
+    },
+    {
+        token: '{{author.entryCountLabel}}',
+        label: 'Post count, worded',
+        description: '"1 post" or "12 posts" — pluralized for you, because a template has no ' + 'conditional to do it with.'
+    }
+];
+/**
+ * Renders an `{{item.*}}` token for a dataset field, optionally hopping
+ * one reference to a field of the referenced record (AGL-180). Always
+ * takes the stable model field ID — display names are labels only.
+ */ export function datasetItemToken(fieldId, targetFieldId) {
+    return targetFieldId ? `{{item.${fieldId}.${targetFieldId}}}` : `{{item.${fieldId}}}`;
+}
+/**
+ * Dataset-item token entries for a repeatable container's model: one per
+ * field in model order, labeled with the CURRENT display name while the
+ * token carries the stable reference id (AGL-578 — renaming a label never
+ * breaks bindings). Reference fields with a configured display field also
+ * get their one-hop token (`{{item.author.name}}`).
+ */ export function datasetItemTokens(model) {
+    var _model_order;
+    const entries = [];
+    for (const fieldId of (_model_order = model.order) != null ? _model_order : []){
+        var _DATASET_FIELD_TYPE_LABELS_field_type;
+        var _model_fields, _field_name, _field_reference;
+        const field = (_model_fields = model.fields) == null ? void 0 : _model_fields[fieldId];
+        if (!field) continue;
+        const label = ((_field_name = field.name) == null ? void 0 : _field_name.trim()) || humanizeDatasetFieldId(fieldId);
+        entries.push({
+            token: datasetItemToken(fieldId),
+            label,
+            description: (_DATASET_FIELD_TYPE_LABELS_field_type = DATASET_FIELD_TYPE_LABELS[field.type]) != null ? _DATASET_FIELD_TYPE_LABELS_field_type : field.type
+        });
+        // One reference hop (AGL-180): surface the configured display field of
+        // the referenced record — the hop editors reach for most.
+        const hopId = field.type === 'reference' ? (_field_reference = field.reference) == null ? void 0 : _field_reference.displayFieldId : undefined;
+        if (hopId) {
+            entries.push({
+                token: datasetItemToken(fieldId, hopId),
+                label: `${label} → ${humanizeDatasetFieldId(hopId)}`,
+                description: 'Field from the referenced record.'
+            });
+        }
+    }
+    return entries;
+}
+
+//# sourceMappingURL=binding-token-catalog.js.map

package/src/lib/app-utils/binding-token-catalog.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/binding-token-catalog.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  DATASET_FIELD_TYPE_LABELS,\n  type DatasetModel,\n} from './dataset-models'\nimport { humanizeDatasetFieldId } from './datasets'\n\n/**\n * Browsable data-placeholder catalogs for the designer's insert picker\n * (AGL-583). Hand-typing `{{entry.title}}` stays the advanced path; these\n * catalogs give every token a friendly label + description so editors can\n * browse and insert instead of memorizing the grammar.\n *\n * The token STRINGS are owned elsewhere — `collectionEntryTokens`\n * (collection-entries.ts) and the tenant compose pipeline resolve them —\n * this module only names them for pickers. The spec cross-checks the entry\n * catalog against the resolver so the two can never drift.\n */\nexport interface BindingTokenCatalogEntry {\n  /** The literal token inserted into the prop, e.g. `{{entry.title}}`. */\n  token: string\n  /** Friendly picker label, e.g. `Title`. */\n  label: string\n  /** One-line description shown as the option's secondary text. */\n  description?: string\n}\n\n/**\n * `{{entry.*}}` tokens (AGL-105/551/582) — resolve per entry inside a\n * Collection entries block and page-wide on entry-template screens.\n * Mirrors {@link collectionEntryTokens}; the spec enforces the mirror.\n */\nexport const ENTRY_TOKEN_CATALOG: readonly BindingTokenCatalogEntry[] = [\n  { token: '{{entry.title}}', label: 'Title', description: 'The entry headline.' },\n  {\n    token: '{{entry.excerpt}}',\n    label: 'Excerpt',\n    description: 'Short summary text.',\n  },\n  {\n    token: '{{entry.body}}',\n    label: 'Body',\n    description: 'The full entry body.',\n  },\n  {\n    token: '{{entry.url}}',\n    label: 'Link URL',\n    description: 'Auto-route to the entry page.',\n  },\n  {\n    token: '{{entry.date}}',\n    label: 'Published date',\n    description: 'Formatted publish date.',\n  },\n  /*\n    Beside the readable date on purpose: a designer reaching for \"the date\" in\n    a Video element's Publication date field has to see that the readable one\n    is the wrong pick there, and why.\n  */\n  {\n    token: '{{entry.publishedAt}}',\n    label: 'Publish timestamp',\n    description:\n      'The publish date and time in ISO 8601, for a field that needs a ' +\n      'machine-readable date, such as a Video element’s publication date.',\n  },\n  {\n    token: '{{entry.author}}',\n    label: 'Author',\n    description: 'The byline set on the entry.',\n  },\n  {\n    token: '{{entry.authorBio}}',\n    label: 'Author bio',\n    description: 'Blurb from the author’s record.',\n  },\n  {\n    token: '{{entry.authorImage}}',\n    label: 'Author portrait',\n    description: 'Portrait or logo from the author’s record.',\n  },\n  {\n    token: '{{entry.authorUrl}}',\n    label: 'Author link',\n    description: 'The author’s own page.',\n  },\n  {\n    token: '{{entry.authorPageUrl}}',\n    label: 'Author page',\n    description:\n      'This author’s page on this site — everything they wrote, across every ' +\n      'collection. Separate from Author link, which is their own site.',\n  },\n  {\n    token: '{{entry.slug}}',\n    label: 'Slug',\n    description: 'URL-safe entry identifier.',\n  },\n  /*\n    Named \"Its collection…\" rather than \"Collection…\", which is what these\n    describe and also exactly what the `{{collection.*}}` entries below are\n    called. The picker groups options by heading, so the two sets sit apart —\n    but a designer scanning it reads the LABEL, and two options reading\n    \"Collection name\" three lines apart is a choice made by guessing. The\n    pronoun is doing real work: on the one page where both resolve, they mean\n    different collections.\n  */\n  {\n    token: '{{entry.collection}}',\n    label: 'Its collection',\n    description:\n      'Which section this entry belongs to. Worth binding on a listing that ' +\n      'MIXES collections — an author page — where a card otherwise cannot ' +\n      'tell a release note from an essay.',\n  },\n  {\n    token: '{{entry.collectionSlug}}',\n    label: 'Its collection slug',\n    description: 'That collection’s URL segment.',\n  },\n  {\n    token: '{{entry.collectionUrl}}',\n    label: 'Its collection link',\n    description: 'The listing this entry belongs to.',\n  },\n  {\n    token: '{{entry.coverImage}}',\n    label: 'Cover image',\n    description: 'Cover image URL.',\n  },\n  {\n    token: '{{entry.coverVideo}}',\n    label: 'Featured video',\n    description:\n      'The featured video’s source — a library film, a video link or a ' +\n      'Wistia link — for a Video element.',\n  },\n  {\n    token: '{{entry.category}}',\n    label: 'Category',\n    description: 'The entry category.',\n  },\n  {\n    token: '{{entry.tags}}',\n    label: 'Tags',\n    description: 'Tags, comma separated.',\n  },\n  {\n    token: '{{entry.seoTitle}}',\n    label: 'SEO title',\n    description: 'Search title; falls back to Title.',\n  },\n  {\n    token: '{{entry.seoDescription}}',\n    label: 'SEO description',\n    description: 'Meta description; falls back to Excerpt.',\n  },\n]\n\n/**\n * `{{collection.*}}` and `{{pagination.*}}` tokens (AGL-551/1321/1386) —\n * resolve on collection list/entry template screens (see the tenant compose\n * pipeline's collection tokens).\n *\n * The category and pagination tokens all resolve to the empty string where\n * they do not apply, so they are safe to bind unconditionally: ONE list\n * screen serves the bare listing, every `/page/{n}` and every\n * `/category/{slug}`, and a template has no runtime conditional to vary\n * itself with.\n */\nexport const COLLECTION_TOKEN_CATALOG: readonly BindingTokenCatalogEntry[] = [\n  {\n    token: '{{collection.name}}',\n    label: 'Collection name',\n    description: 'Display name of the routed collection.',\n  },\n  {\n    token: '{{collection.slug}}',\n    label: 'Collection slug',\n    description: 'URL slug of the routed collection.',\n  },\n  {\n    token: '{{collection.category}}',\n    label: 'Filtered category',\n    description: 'Category the URL filtered on; empty when unfiltered.',\n  },\n  {\n    token: '{{collection.categorySlug}}',\n    label: 'Filtered category slug',\n    description: 'That category’s URL segment; empty when unfiltered.',\n  },\n  {\n    token: '{{pagination.page}}',\n    label: 'Current page',\n    description: 'Page number this URL is showing.',\n  },\n  {\n    token: '{{pagination.totalPages}}',\n    label: 'Total pages',\n    description: 'Pages in the listing, after any category filter.',\n  },\n  {\n    token: '{{pagination.prevUrl}}',\n    label: 'Previous page link',\n    description: 'Keeps the category; empty on the first page.',\n  },\n  {\n    token: '{{pagination.nextUrl}}',\n    label: 'Next page link',\n    description: 'Keeps the category; empty on the last page.',\n  },\n]\n\n/**\n * `{{author.*}}` tokens (AGL-2518) — resolve on an author's own page,\n * `/author/{slug}`.\n *\n * Empty everywhere else, like the category tokens above and for the same\n * reason: a template has no runtime conditional, so the tokens have to be the\n * thing that varies. A heading bound to `{{author.name}}` prints a name on an\n * author page and nothing anywhere else.\n *\n * The `{{pagination.*}}` tokens resolve HERE TOO, over this author's own\n * archive — deliberately the same four names a collection listing uses, so a\n * pager built once works on both.\n */\nexport const AUTHOR_TOKEN_CATALOG: readonly BindingTokenCatalogEntry[] = [\n  {\n    token: '{{author.name}}',\n    label: 'Name',\n    description: 'The byline this page collects.',\n  },\n  {\n    token: '{{author.bio}}',\n    label: 'Bio',\n    description: 'Their blurb, from the author record.',\n  },\n  {\n    token: '{{author.image}}',\n    label: 'Portrait',\n    description: 'Their portrait or logo, from the author record.',\n  },\n  {\n    token: '{{author.jobTitle}}',\n    label: 'Role',\n    description: 'Their job title; empty for an Organization author.',\n  },\n  {\n    token: '{{author.worksFor}}',\n    label: 'Organization',\n    description: 'Who they write for; empty for an Organization author.',\n  },\n  {\n    token: '{{author.url}}',\n    label: 'Their own site',\n    description:\n      'The url on their record — a personal site, not this page. Empty when ' +\n      'they have none.',\n  },\n  {\n    token: '{{author.pageUrl}}',\n    label: 'This page',\n    description: 'The canonical address of the page you are designing.',\n  },\n  {\n    token: '{{author.entryCount}}',\n    label: 'Post count',\n    description: 'How many entries they have published, across every collection.',\n  },\n  {\n    token: '{{author.entryCountLabel}}',\n    label: 'Post count, worded',\n    description:\n      '\"1 post\" or \"12 posts\" — pluralized for you, because a template has no ' +\n      'conditional to do it with.',\n  },\n]\n\n/**\n * Renders an `{{item.*}}` token for a dataset field, optionally hopping\n * one reference to a field of the referenced record (AGL-180). Always\n * takes the stable model field ID — display names are labels only.\n */\nexport function datasetItemToken(\n  fieldId: string,\n  targetFieldId?: string,\n): string {\n  return targetFieldId\n    ? `{{item.${fieldId}.${targetFieldId}}}`\n    : `{{item.${fieldId}}}`\n}\n\n/**\n * Dataset-item token entries for a repeatable container's model: one per\n * field in model order, labeled with the CURRENT display name while the\n * token carries the stable reference id (AGL-578 — renaming a label never\n * breaks bindings). Reference fields with a configured display field also\n * get their one-hop token (`{{item.author.name}}`).\n */\nexport function datasetItemTokens(\n  model: DatasetModel,\n): BindingTokenCatalogEntry[] {\n  const entries: BindingTokenCatalogEntry[] = []\n  for (const fieldId of model.order ?? []) {\n    const field = model.fields?.[fieldId]\n    if (!field) continue\n    const label = field.name?.trim() || humanizeDatasetFieldId(fieldId)\n    entries.push({\n      token: datasetItemToken(fieldId),\n      label,\n      description: DATASET_FIELD_TYPE_LABELS[field.type] ?? field.type,\n    })\n    // One reference hop (AGL-180): surface the configured display field of\n    // the referenced record — the hop editors reach for most.\n    const hopId =\n      field.type === 'reference' ? field.reference?.displayFieldId : undefined\n    if (hopId) {\n      entries.push({\n        token: datasetItemToken(fieldId, hopId),\n        label: `${label} → ${humanizeDatasetFieldId(hopId)}`,\n        description: 'Field from the referenced record.',\n      })\n    }\n  }\n  return entries\n}\n"],"names":["DATASET_FIELD_TYPE_LABELS","humanizeDatasetFieldId","ENTRY_TOKEN_CATALOG","token","label","description","COLLECTION_TOKEN_CATALOG","AUTHOR_TOKEN_CATALOG","datasetItemToken","fieldId","targetFieldId","datasetItemTokens","model","entries","order","field","fields","name","trim","push","type","hopId","reference","displayFieldId","undefined"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED,SACEA,yBAAyB,QAEpB,sBAAkB;AACzB,SAASC,sBAAsB,QAAQ,gBAAY;AAsBnD;;;;CAIC,GACD,OAAO,MAAMC,sBAA2D;IACtE;QAAEC,OAAO;QAAmBC,OAAO;QAASC,aAAa;IAAsB;IAC/E;QACEF,OAAO;QACPC,OAAO;QACPC,aAAa;IACf;IACA;QACEF,OAAO;QACPC,OAAO;QACPC,aAAa;IACf;IACA;QACEF,OAAO;QACPC,OAAO;QACPC,aAAa;IACf;IACA;QACEF,OAAO;QACPC,OAAO;QACPC,aAAa;IACf;IACA;;;;EAIA,GACA;QACEF,OAAO;QACPC,OAAO;QACPC,aACE,qEACA;IACJ;IACA;QACEF,OAAO;QACPC,OAAO;QACPC,aAAa;IACf;IACA;QACEF,OAAO;QACPC,OAAO;QACPC,aAAa;IACf;IACA;QACEF,OAAO;QACPC,OAAO;QACPC,aAAa;IACf;IACA;QACEF,OAAO;QACPC,OAAO;QACPC,aAAa;IACf;IACA;QACEF,OAAO;QACPC,OAAO;QACPC,aACE,2EACA;IACJ;IACA;QACEF,OAAO;QACPC,OAAO;QACPC,aAAa;IACf;IACA;;;;;;;;EAQA,GACA;QACEF,OAAO;QACPC,OAAO;QACPC,aACE,0EACA,wEACA;IACJ;IACA;QACEF,OAAO;QACPC,OAAO;QACPC,aAAa;IACf;IACA;QACEF,OAAO;QACPC,OAAO;QACPC,aAAa;IACf;IACA;QACEF,OAAO;QACPC,OAAO;QACPC,aAAa;IACf;IACA;QACEF,OAAO;QACPC,OAAO;QACPC,aACE,qEACA;IACJ;IACA;QACEF,OAAO;QACPC,OAAO;QACPC,aAAa;IACf;IACA;QACEF,OAAO;QACPC,OAAO;QACPC,aAAa;IACf;IACA;QACEF,OAAO;QACPC,OAAO;QACPC,aAAa;IACf;IACA;QACEF,OAAO;QACPC,OAAO;QACPC,aAAa;IACf;CACD,CAAA;AAED;;;;;;;;;;CAUC,GACD,OAAO,MAAMC,2BAAgE;IAC3E;QACEH,OAAO;QACPC,OAAO;QACPC,aAAa;IACf;IACA;QACEF,OAAO;QACPC,OAAO;QACPC,aAAa;IACf;IACA;QACEF,OAAO;QACPC,OAAO;QACPC,aAAa;IACf;IACA;QACEF,OAAO;QACPC,OAAO;QACPC,aAAa;IACf;IACA;QACEF,OAAO;QACPC,OAAO;QACPC,aAAa;IACf;IACA;QACEF,OAAO;QACPC,OAAO;QACPC,aAAa;IACf;IACA;QACEF,OAAO;QACPC,OAAO;QACPC,aAAa;IACf;IACA;QACEF,OAAO;QACPC,OAAO;QACPC,aAAa;IACf;CACD,CAAA;AAED;;;;;;;;;;;;CAYC,GACD,OAAO,MAAME,uBAA4D;IACvE;QACEJ,OAAO;QACPC,OAAO;QACPC,aAAa;IACf;IACA;QACEF,OAAO;QACPC,OAAO;QACPC,aAAa;IACf;IACA;QACEF,OAAO;QACPC,OAAO;QACPC,aAAa;IACf;IACA;QACEF,OAAO;QACPC,OAAO;QACPC,aAAa;IACf;IACA;QACEF,OAAO;QACPC,OAAO;QACPC,aAAa;IACf;IACA;QACEF,OAAO;QACPC,OAAO;QACPC,aACE,0EACA;IACJ;IACA;QACEF,OAAO;QACPC,OAAO;QACPC,aAAa;IACf;IACA;QACEF,OAAO;QACPC,OAAO;QACPC,aAAa;IACf;IACA;QACEF,OAAO;QACPC,OAAO;QACPC,aACE,4EACA;IACJ;CACD,CAAA;AAED;;;;CAIC,GACD,OAAO,SAASG,iBACdC,OAAe,EACfC,aAAsB;IAEtB,OAAOA,gBACH,CAAC,OAAO,EAAED,QAAQ,CAAC,EAAEC,cAAc,EAAE,CAAC,GACtC,CAAC,OAAO,EAAED,QAAQ,EAAE,CAAC;AAC3B;AAEA;;;;;;CAMC,GACD,OAAO,SAASE,kBACdC,KAAmB;QAGGA;IADtB,MAAMC,UAAsC,EAAE;IAC9C,KAAK,MAAMJ,YAAWG,eAAAA,MAAME,KAAK,YAAXF,eAAe,EAAE,CAAE;YAOxBZ;YANDY,eAEAG,aASiBA;QAX/B,MAAMA,SAAQH,gBAAAA,MAAMI,MAAM,qBAAZJ,aAAc,CAACH,QAAQ;QACrC,IAAI,CAACM,OAAO;QACZ,MAAMX,QAAQW,EAAAA,cAAAA,MAAME,IAAI,qBAAVF,YAAYG,IAAI,OAAMjB,uBAAuBQ;QAC3DI,QAAQM,IAAI,CAAC;YACXhB,OAAOK,iBAAiBC;YACxBL;YACAC,WAAW,GAAEL,wCAAAA,yBAAyB,CAACe,MAAMK,IAAI,CAAC,YAArCpB,wCAAyCe,MAAMK,IAAI;QAClE;QACA,uEAAuE;QACvE,0DAA0D;QAC1D,MAAMC,QACJN,MAAMK,IAAI,KAAK,eAAcL,mBAAAA,MAAMO,SAAS,qBAAfP,iBAAiBQ,cAAc,GAAGC;QACjE,IAAIH,OAAO;YACTR,QAAQM,IAAI,CAAC;gBACXhB,OAAOK,iBAAiBC,SAASY;gBACjCjB,OAAO,GAAGA,MAAM,GAAG,EAAEH,uBAAuBoB,QAAQ;gBACpDhB,aAAa;YACf;QACF;IACF;IACA,OAAOQ;AACT"}