@aglyn/aglyn 1.0.0-beta.143

package/src/lib/app-utils/email-topics.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/email-topics.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 * EMAIL TOPICS — the streams a recipient can leave one at a time.\n *\n * ## The gap this closes\n *\n * `docs/specs/email-competitive-gaps.md` §1f records the only row in that\n * table where every competitor has something and we have nothing: \"Preference\n * center / subscription topics — unsubscribe is all-or-nothing per site\".\n * A recipient who wanted the newsletter but not the sales mail had exactly one\n * lever, and pulling it took the newsletter too. The lever people reach for\n * when the only unsubscribe is total is \"report spam\", which is a complaint,\n * which is the sending domain's problem and therefore every tenant's.\n *\n * ## Scope: definitions are ORG-shared, opt-outs are PER-SITE\n *\n * The topic CATALOG lives at `orgs/{orgId}/emailTopics`, which is where\n * `lists` live (AGL-254) and for the same reason: a topic is authored\n * editorial content — a name and a sentence of description — that an agency\n * writes once and points several sites at. Following `lists` also means the\n * console surface that manages topics inherits a scoping question that has\n * already been answered, rather than inventing a second answer.\n *\n * A recipient's OPT-OUT is per site, at `hosts/{hostId}/topicOptOuts`. It sits\n * beside `hosts/{hostId}/suppressions`, which is per site, and it answers the\n * same shape of question one notch finer: the suppression says \"nothing from\n * this site\", the opt-out says \"not this stream from this site\". Two facts\n * about one person that live at different scopes would make \"may I mail this\n * person about product updates\" a question with two answers. It also keeps\n * the unauthenticated preference page honest — the signed link names a host\n * and nothing else, so a per-site read is exactly what the link authorizes.\n *\n * ## Why the defaults are code and not seeded documents\n *\n * Every tenant that exists today has an empty `emailTopics` collection. A\n * seeding migration would have to run against every org, would leave any org\n * created while it was mid-flight with none, and — like every backfill — is a\n * thing that gets written and then not run. So {@link DEFAULT_EMAIL_TOPICS} is\n * the floor of the catalog rather than its initial contents: it is present for\n * every org from the moment this ships, with no write anywhere, and a stored\n * document at the same id renames, re-describes or archives one. The catalog a\n * reader sees is {@link mergeEmailTopics} of the two.\n */\n\n/** One subscribable stream. */\nexport interface EmailTopic {\n  /**\n   * The stored id. Rides in the unsubscribe link's `tid` and is covered by\n   * its signature, so it is treated as persisted — rename the {@link name},\n   * never the id.\n   */\n  id: string\n  /** What the recipient sees on the preference page. */\n  name: string\n  /** One sentence of \"what will I get\", shown under the name. */\n  description: string\n  /**\n   * Retired. An archived topic stays in the catalog for the send path and the\n   * preference page's history, and is hidden from the composer's picker —\n   * campaigns already sent under it must go on resolving, or their unsubscribe\n   * links stop naming anything.\n   */\n  archived?: boolean\n  /**\n   * Whether joining this stream needs a confirmation click.\n   *\n   * `undefined` — the ordinary state — means \"whatever the site says\", which\n   * is what {@link topicRequiresDoubleOptIn} resolves. A stored `true` or\n   * `false` is a decision made about THIS stream and overrides the site: a\n   * merchant who confirms their newsletter and not their order-related\n   * product updates is expressing something real, and a per-site switch alone\n   * cannot hold it.\n   */\n  doubleOptIn?: boolean\n}\n\n/**\n * DOUBLE OPT-IN — per topic, defaulting per site.\n *\n * `docs/specs/email-competitive-gaps.md` P8. Of the ten vendors surveyed\n * **none mandates it**, so this is an option and never a default: the field\n * above is absent everywhere until a merchant turns it on, and the site\n * default is off.\n *\n * ## Why per topic, with a per-site default\n *\n * Three reasons, and the first is the one that decides it.\n *\n * The recipient-facing vocabulary is ALREADY per topic. The signed link\n * carries `tid`, the opt-out record is keyed by topic, and the preference\n * page is a list of topics. A confirmation scoped to anything else would need\n * a second vocabulary to express \"confirmed for what\", and the recipient\n * would meet both.\n *\n * It is also the axis the compared products chose — Brevo and Klaviyo offer\n * double opt-in per LIST — and a topic is our per-list.\n *\n * The site default exists because the merchant who wants this usually wants\n * it everywhere: in the jurisdictions where a DOI is the accepted proof of\n * consent, \"on for the newsletter but not for the four others\" is not the\n * answer they are after, and asking them to set it on each topic they now\n * have plus each one they later add is the shape that gets half-done.\n *\n * ## What it must have to be worth anything\n *\n * ActiveCampaign is the implementation worth copying because it has teeth:\n * an unconfirmed subscriber lands in a real quarantine and \"you cannot send\n * any emails to contacts that have this status\". Recording a pending\n * confirmation that the send path then ignores is Customer.io's DIY recipe,\n * whose own documentation warns that it \"doesn't automatically check this\n * attribute before sending messages\" — a fact stored and not enforced. So the\n * state below is read by `filterTopicSendable`, in the same pass that reads\n * the opt-outs.\n *\n * ## On the law, precisely\n *\n * No jurisdiction verified requires double opt-in by statute. They require\n * prior express consent plus a burden of proof on the sender — EU ePrivacy\n * Art. 13(1), German UWG §7(2), Canada's CASL s.13. Germany's own\n * certification body says a DOI is not required by law and then explains why\n * everyone does it anyway: the proof has so far been recognized by the courts\n * exclusively via a DOI. The law requires provable consent; a DOI is the\n * accepted proof.\n */\nexport const DEFAULT_SITE_DOUBLE_OPT_IN = false\n\n/**\n * How long a confirmation link stays good.\n *\n * 72 hours, Klaviyo's number rather than one of our own. Brevo's is 30 days,\n * which is long enough that the click stops being evidence of anything\n * contemporaneous; the point of the confirmation is to show that the person\n * holding that mailbox wanted this, and a month-old click shows it much less\n * well than a same-day one.\n *\n * Expiry stops the LINK working. It does not make an unconfirmed address\n * mailable — see {@link readTopicSubscriptionState}, where the two are\n * deliberately separate questions.\n */\nexport const DOUBLE_OPT_IN_EXPIRY_MS = 72 * 60 * 60 * 1000\n\n/**\n * Whether joining `topic` on this site needs a confirmation click.\n *\n * The topic's own setting when it has one, the site's otherwise. `false`\n * stored on a topic is a real answer and not an absence, which is what lets a\n * merchant confirm everything except their order-related stream.\n */\nexport function topicRequiresDoubleOptIn(\n  topic: Pick<EmailTopic, 'doubleOptIn'> | null | undefined,\n  siteDefault: boolean = DEFAULT_SITE_DOUBLE_OPT_IN,\n): boolean {\n  return typeof topic?.doubleOptIn === 'boolean'\n    ? topic.doubleOptIn\n    : siteDefault === true\n}\n\n/** What one person's record says about one stream on one site. */\nexport type TopicSubscriptionState =\n  /** They may be mailed about this. */\n  | 'subscribed'\n  /** Asked to join and has not confirmed. NOT mailable. */\n  | 'pending'\n  /** Left this stream and has not rejoined. NOT mailable. */\n  | 'opted-out'\n\n/** One entry in a `topicOptOuts` document's `topics` map, as stored. */\nexport interface TopicSubscriptionEntry {\n  optedOutAt?: unknown\n  resubscribedAt?: unknown\n  /** When a confirmation was asked for. */\n  pendingAt?: unknown\n  /** When they confirmed, or absent/null while they have not. */\n  confirmedAt?: unknown\n}\n\n/**\n * What an entry means, in one place, for every reader.\n *\n * ## Why this is a function and not a field test at each site\n *\n * There were two fields and one test — \"an entry with no `resubscribedAt` is a\n * live opt-out\" — written out at three call sites. Adding a third and fourth\n * field breaks that test everywhere it appears at once: a CONFIRMED entry\n * carries `pendingAt` and `confirmedAt` and no `resubscribedAt`, so the old\n * shorthand reads it as somebody who left. Nobody would find that by reading\n * one call site.\n *\n * ## Precedence: a refusal outranks a pending confirmation\n *\n * Somebody who left a stream and never rejoined is opted out even if a\n * confirmation was once asked of them, because leaving is the more recent and\n * more explicit act — and because a pending confirmation that could outrank a\n * refusal would be a way to re-arm sending by asking again.\n *\n * ## An EXPIRED confirmation is still not a subscriber\n *\n * Expiry stops the link working; it does not admit anybody. The alternative —\n * treating a lapsed pending record as subscribed — would make the whole\n * mechanism a delay rather than a gate, and waiting it out would be the way\n * past it.\n */\nexport function readTopicSubscriptionState(\n  entry: TopicSubscriptionEntry | null | undefined,\n): TopicSubscriptionState {\n  if (!entry) return 'subscribed'\n  if (entry.optedOutAt && !entry.resubscribedAt) return 'opted-out'\n  if (entry.pendingAt && !entry.confirmedAt) return 'pending'\n  return 'subscribed'\n}\n\n/**\n * Whether a confirmation request is too old to be acted on.\n *\n * A separate question from {@link readTopicSubscriptionState} on purpose: one\n * answers \"may we mail them\", the other answers \"does this link still work\",\n * and collapsing them is how an expiry comes to admit somebody.\n */\nexport function doubleOptInExpired(\n  pendingAtMs: number | null | undefined,\n  nowMs: number,\n): boolean {\n  const at = Number(pendingAtMs)\n  if (!Number.isFinite(at) || at <= 0) return true\n  return nowMs - at > DOUBLE_OPT_IN_EXPIRY_MS\n}\n\n/** `orgs/{orgId}/emailTopics` — the catalog, org-shared like `lists`. */\nexport const EMAIL_TOPICS_COLLECTION = 'emailTopics'\n\n/** `hosts/{hostId}/topicOptOuts/{emailKey}` — one document per recipient. */\nexport const TOPIC_OPT_OUTS_SUBCOLLECTION = 'topicOptOuts'\n\n/*==========================================\n * THE BUILT-IN STREAM IDS.\n *\n * Named rather than written as literals wherever a send declares which stream\n * it belongs to, because a mistyped id does not fail loudly. It names a\n * stream nobody has opted out of, so `filterTopicSendable` finds no opt-out\n * and the send goes to everybody — the control silently doing nothing, which\n * is the failure mode a topic filter is least able to reveal.\n *\n * The value is also a Firestore path component and a colon-joined component\n * of the unsubscribe link's signed subject, so it is a wire format: changing\n * one of these strings orphans every opt-out already recorded against it.\n *=========================================*/\n\n/** Sales, discounts, seasonal campaigns — and the cart a shopper left. */\nexport const EMAIL_TOPIC_MARKETING = 'marketing'\n/** Regular news and stories, including a site's posts to its members. */\nexport const EMAIL_TOPIC_NEWSLETTER = 'newsletter'\n/** New products, restocks, and changes to what a site offers. */\nexport const EMAIL_TOPIC_PRODUCT_UPDATES = 'product-updates'\n/** One person here writing to another about working together. */\nexport const EMAIL_TOPIC_SALES = 'sales'\n\n/**\n * The catalog every org has before anyone opens the console.\n *\n * Four, not twelve. A preference page whose value is \"leave one stream without\n * leaving all of them\" stops working the moment the list is long enough that\n * reading it is a chore, and a merchant who needs a fifth can add one. The ids\n * are the generic names an unsubscribing recipient can recognize without\n * knowing anything about the sender's internal vocabulary.\n */\nexport const DEFAULT_EMAIL_TOPICS: readonly EmailTopic[] = [\n  {\n    id: EMAIL_TOPIC_MARKETING,\n    name: 'Promotions and offers',\n    description: 'Sales, discounts and seasonal campaigns.',\n  },\n  {\n    id: EMAIL_TOPIC_NEWSLETTER,\n    name: 'Newsletter',\n    description: 'Regular news and stories from us.',\n  },\n  {\n    id: EMAIL_TOPIC_PRODUCT_UPDATES,\n    name: 'Product updates',\n    description: 'New products, restocks and changes to what we offer.',\n  },\n  {\n    id: EMAIL_TOPIC_SALES,\n    name: 'Sales outreach',\n    description: 'Messages from a person here about working together.',\n  },\n]\n\n/**\n * The topic a campaign carries when its author picked none.\n *\n * Every campaign resolves to SOME topic, because a campaign with no topic\n * would mint an unsubscribe link the preference page cannot place — it could\n * offer the catalog but not say which entry this message was, which is the one\n * thing the recipient came to the page knowing.\n */\nexport const DEFAULT_CAMPAIGN_TOPIC_ID = EMAIL_TOPIC_MARKETING\n\n/**\n * WHICH STREAM AN AUTOMATED EMAIL BELONGS TO — the one answer, named once.\n *\n * An immediate reply belongs to no stream unless the step named one; anything\n * that goes out on the merchant's schedule belongs to the default stream, as a\n * campaign does. See `FlowEmailScope` for why the two differ.\n *\n * The rule is read TWICE per send — the flow gate filters on it, and the\n * executor signs it into the opt-out link so the preference page opens on the\n * stream the recipient was trying to leave rather than on a list they have to\n * search — so it lives here, in the pure leaf both sides can import, rather\n * than beside either reader. Two spellings of it is how a link comes to name\n * a stream the gate did not check.\n *\n * @returns the topic id, or `''` for a message that belongs to no stream —\n *          which is not \"the default topic\", and must not be signed into a\n *          link as one.\n */\nexport function flowEmailTopicId(\n  topicId: string | null | undefined,\n  scope?: 'scheduled' | 'immediate',\n): string {\n  const named = String(topicId ?? '').trim()\n  return scope === 'immediate' ? named : named || DEFAULT_CAMPAIGN_TOPIC_ID\n}\n\n/**\n * Whether `value` may be a topic id.\n *\n * Two constraints, and the second is the load-bearing one. The id becomes a\n * Firestore path component, so it carries `isDocumentId`'s rules; and it\n * becomes a COLON-JOINED component of the unsubscribe link's signed subject,\n * so a colon inside it would let one signed subject be read as two different\n * parameter tuples. See `signatureMatches` in the email plugin's\n * `unsubscribe-link.ts` for what that ambiguity would buy.\n */\nexport function isEmailTopicId(value: unknown): value is string {\n  return (\n    typeof value === 'string' &&\n    value.length > 0 &&\n    value.length <= 120 &&\n    !value.includes('/') &&\n    !value.includes(':') &&\n    value !== '.' &&\n    value !== '..' &&\n    !/^__.*__$/.test(value)\n  )\n}\n\n/** Coerces one stored document into a topic, or `null` if it is not one. */\nexport function normalizeEmailTopic(\n  id: unknown,\n  data: Record<string, unknown> | null | undefined,\n): EmailTopic | null {\n  if (!isEmailTopicId(id)) return null\n  const name = String(data?.['name'] ?? '').trim()\n  return {\n    id,\n    // A nameless stored document falls back to the id rather than rendering a\n    // blank checkbox on the preference page. The console refuses to create\n    // one; a restore or an API write is not bound by that.\n    name: name || id,\n    description: String(data?.['description'] ?? '').trim(),\n    ...(data?.['archived'] === true ? { archived: true as const } : {}),\n    /*\n     * Carried only when the document actually holds a boolean.\n     *\n     * A missing field and a stored `false` are different answers here —\n     * `topicRequiresDoubleOptIn` reads absence as \"ask the site\" and `false`\n     * as \"not this stream, whatever the site says\" — so coercing with `===\n     * true` the way `archived` does would erase the second of the three\n     * states this field has.\n     */\n    ...(typeof data?.['doubleOptIn'] === 'boolean'\n      ? { doubleOptIn: data['doubleOptIn'] as boolean }\n      : {}),\n  }\n}\n\n/**\n * The catalog a reader sees: the built-in floor, overlaid by whatever the org\n * has stored, plus the org's own topics.\n *\n * Overlay rather than replace, so an org that adds one custom topic does not\n * thereby delete the four every one of its recipients has been unsubscribing\n * against. A built-in is removed by storing it `archived`, which is a\n * decision someone made rather than a side effect of making a different one.\n *\n * Sorted with the built-ins first in their declared order and custom topics\n * alphabetically after, so the preference page's checkbox order is stable\n * across renders and across sites.\n */\nexport function mergeEmailTopics(\n  stored: readonly EmailTopic[] | null | undefined,\n): EmailTopic[] {\n  const overrides = new Map<string, EmailTopic>()\n  for (const topic of stored ?? []) {\n    if (isEmailTopicId(topic?.id)) overrides.set(topic.id, topic)\n  }\n  const builtIn = DEFAULT_EMAIL_TOPICS.map(\n    (topic) => overrides.get(topic.id) ?? topic,\n  )\n  const custom = [...overrides.values()]\n    .filter((topic) => !DEFAULT_EMAIL_TOPICS.some((it) => it.id === topic.id))\n    .sort((a, b) => a.name.localeCompare(b.name))\n  return [...builtIn, ...custom]\n}\n\n/**\n * The catalog minus retired topics — what a composer's picker and a\n * preference page's checkboxes offer.\n *\n * The send path deliberately does NOT filter through this: a scheduled\n * campaign whose topic was archived between scheduling and sending still\n * belongs to that topic, and re-pointing it at something else would attribute\n * the unsubscribes to the wrong stream.\n */\nexport function activeEmailTopics(\n  topics: readonly EmailTopic[],\n): EmailTopic[] {\n  return topics.filter((topic) => !topic.archived)\n}\n\n/**\n * The topic a campaign belongs to, given what it stored and what the org\n * offers.\n *\n * Resolves an unknown or missing id to the default rather than to nothing: a\n * campaign sent before topics existed carries no `topicId`, and its\n * unsubscribe links are in inboxes right now. They must land on a preference\n * page that names A topic, not on one that says the message came from\n * nowhere.\n */\nexport function resolveCampaignTopic(\n  topicId: string | null | undefined,\n  topics: readonly EmailTopic[],\n): EmailTopic {\n  const found = topicId\n    ? topics.find((topic) => topic.id === topicId)\n    : undefined\n  if (found) return found\n  return (\n    topics.find((topic) => topic.id === DEFAULT_CAMPAIGN_TOPIC_ID) ??\n    topics[0] ?? {\n      id: DEFAULT_CAMPAIGN_TOPIC_ID,\n      name: 'Email',\n      description: '',\n    }\n  )\n}\n"],"names":["DEFAULT_SITE_DOUBLE_OPT_IN","DOUBLE_OPT_IN_EXPIRY_MS","topicRequiresDoubleOptIn","topic","siteDefault","doubleOptIn","readTopicSubscriptionState","entry","optedOutAt","resubscribedAt","pendingAt","confirmedAt","doubleOptInExpired","pendingAtMs","nowMs","at","Number","isFinite","EMAIL_TOPICS_COLLECTION","TOPIC_OPT_OUTS_SUBCOLLECTION","EMAIL_TOPIC_MARKETING","EMAIL_TOPIC_NEWSLETTER","EMAIL_TOPIC_PRODUCT_UPDATES","EMAIL_TOPIC_SALES","DEFAULT_EMAIL_TOPICS","id","name","description","DEFAULT_CAMPAIGN_TOPIC_ID","flowEmailTopicId","topicId","scope","named","String","trim","isEmailTopicId","value","length","includes","test","normalizeEmailTopic","data","archived","mergeEmailTopics","stored","overrides","Map","set","builtIn","map","get","custom","values","filter","some","it","sort","a","b","localeCompare","activeEmailTopics","topics","resolveCampaignTopic","found","find","undefined"],"mappings":"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"}

package/src/lib/app-utils/enabled-plugins-context.d.ts

@@ -0,0 +1,100 @@
+/**
+ * @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 EDITOR's view of per-site plugin enablement (AGL-1014).
+ *
+ * `enabledPlugins` is a boundary, not a preference, and the issue names four
+ * surfaces that must enforce it identically: console navigation, the editor,
+ * published sites, and API dispatch. The other three read
+ * `resolveHostEnabledPlugins` on the server or subtract the deny-list in the
+ * console shell. This context is how the same answer reaches the besigner —
+ * the host app resolves it (only it can read an org and a host) and publishes
+ * it; the designer stays storage-agnostic.
+ *
+ * It has to be a READ-TIME filter rather than a narrower load. The preset
+ * registry is a module-global union that only ever grows: `consolePluginLoader`
+ * never unloads a bundle, and a plugin whose site components registered while
+ * editing site A goes on offering palette entries on site B. Loading less
+ * cannot un-register what is already there, so the component drawer filters
+ * every entry against this set instead.
+ *
+ * `undefined` means no set was supplied and leaves consumers unfiltered — the
+ * same opt-in shape `listConsoleExtensions` uses, so surfaces with no host
+ * (the platform email editor, tests) behave exactly as before.
+ */
+export declare const EnabledPluginsContext: import("react").Context<readonly string[]>;
+/** The edited site's effective plugin ids, or undefined where none is set. */
+export declare function useEnabledPlugins(): readonly string[] | undefined;
+/**
+ * Whether a registry entry's owning plugin runs on the site being edited.
+ *
+ * An entry with no `pluginId` belongs to no plugin, so no deny-list entry can
+ * name it and it passes; so does everything when no set was supplied.
+ */
+/**
+ * Component categories whose entries follow a per-site CAPABILITY rather
+ * than the bundle that ships them (AGL-2486).
+ *
+ * The Members blocks — Member sign-in, Member sign-up, Password recovery —
+ * are registered by the COMMERCE bundle, so `pluginId` alone said "commerce
+ * is on, offer them" on sites whose `/signin`, `/signup` and `/recover`
+ * return 404. An author drops a sign-in block on a page, publishes it, and
+ * finds out from a visitor.
+ *
+ * Attribution by category rather than by re-registering the components
+ * under the `accounts` id: re-registering moves where they LOAD from and
+ * would change what sites already using those blocks serve. This map is
+ * read-time only — it decides what the picker OFFERS, never what a page
+ * that already contains one renders.
+ */
+export declare const CATEGORY_REQUIRED_CAPABILITY: Readonly<Record<string, string>>;
+/**
+ * Whether a category's required capability (if it has one) runs on the site
+ * being edited. Categories with no requirement always pass, as does
+ * everything when no set was supplied.
+ */
+export declare function isCategoryCapabilityEnabled(category: string | undefined, enabledPluginIds: readonly string[] | undefined): boolean;
+export declare function isFromEnabledPlugin(item: {
+    pluginId?: string;
+} | undefined, enabledPluginIds: readonly string[] | undefined): boolean;
+/**
+ * Whether a REGISTERED component must be drawn as though it were not
+ * registered at all, because its first-party plugin does not run on the site
+ * being rendered (AGL-3033).
+ *
+ * The component registry is process-global and only grows. On a server that
+ * serves many sites, a bundle one site's page loaded stays registered for
+ * every later render, so asking the registry alone draws a switched-off
+ * plugin's elements in full on a site that switched it off — while that
+ * site's browser, which never loads the bundle, draws the unregistered
+ * fallback. The HTML shows what the site switched off, and hydration fails on
+ * the difference. Asking the rendered site's plugin set as well makes the
+ * server and the browser give one answer.
+ *
+ * Only a FIRST-PARTY id is asked about. A marketplace bundle's components name
+ * the id in its manifest, which is not the listing id the site's set carries,
+ * and a component naming no plugin belongs to none. Both render as registered,
+ * as does the base library, which no site can switch off.
+ *
+ * An EMPTY set is no answer. Every set a site resolves carries the base
+ * library, so an empty one is a surface saying it has no site to answer for —
+ * the console's editor gate publishes `[]` while the URL names no workspace it
+ * has resolved — and drawing every element there as unregistered would blank
+ * the canvas. It renders as though no set was supplied.
+ */
+export declare function isSwitchedOffForRenderedSite(pluginId: string | undefined, enabledPluginIds: readonly string[] | undefined): boolean;
+export default EnabledPluginsContext;

package/src/lib/app-utils/enabled-plugins-context.js

@@ -0,0 +1,113 @@
+/**
+ * @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 { createContext, useContext } from "react";
+import { ComponentCategory } from "../foundation/constants/components.js";
+import { ACCOUNTS_PLUGIN_ID, isFirstPartyPlugin, isLockedOnForSite } from "../plugin-manager/enabled-plugins.js";
+/**
+ * The EDITOR's view of per-site plugin enablement (AGL-1014).
+ *
+ * `enabledPlugins` is a boundary, not a preference, and the issue names four
+ * surfaces that must enforce it identically: console navigation, the editor,
+ * published sites, and API dispatch. The other three read
+ * `resolveHostEnabledPlugins` on the server or subtract the deny-list in the
+ * console shell. This context is how the same answer reaches the besigner —
+ * the host app resolves it (only it can read an org and a host) and publishes
+ * it; the designer stays storage-agnostic.
+ *
+ * It has to be a READ-TIME filter rather than a narrower load. The preset
+ * registry is a module-global union that only ever grows: `consolePluginLoader`
+ * never unloads a bundle, and a plugin whose site components registered while
+ * editing site A goes on offering palette entries on site B. Loading less
+ * cannot un-register what is already there, so the component drawer filters
+ * every entry against this set instead.
+ *
+ * `undefined` means no set was supplied and leaves consumers unfiltered — the
+ * same opt-in shape `listConsoleExtensions` uses, so surfaces with no host
+ * (the platform email editor, tests) behave exactly as before.
+ */ export const EnabledPluginsContext = createContext(undefined);
+EnabledPluginsContext.displayName = 'EnabledPluginsContext';
+/** The edited site's effective plugin ids, or undefined where none is set. */ export function useEnabledPlugins() {
+    return useContext(EnabledPluginsContext);
+}
+/**
+ * Whether a registry entry's owning plugin runs on the site being edited.
+ *
+ * An entry with no `pluginId` belongs to no plugin, so no deny-list entry can
+ * name it and it passes; so does everything when no set was supplied.
+ */ /**
+ * Component categories whose entries follow a per-site CAPABILITY rather
+ * than the bundle that ships them (AGL-2486).
+ *
+ * The Members blocks — Member sign-in, Member sign-up, Password recovery —
+ * are registered by the COMMERCE bundle, so `pluginId` alone said "commerce
+ * is on, offer them" on sites whose `/signin`, `/signup` and `/recover`
+ * return 404. An author drops a sign-in block on a page, publishes it, and
+ * finds out from a visitor.
+ *
+ * Attribution by category rather than by re-registering the components
+ * under the `accounts` id: re-registering moves where they LOAD from and
+ * would change what sites already using those blocks serve. This map is
+ * read-time only — it decides what the picker OFFERS, never what a page
+ * that already contains one renders.
+ */ export const CATEGORY_REQUIRED_CAPABILITY = {
+    [ComponentCategory.MEMBERS]: ACCOUNTS_PLUGIN_ID
+};
+/**
+ * Whether a category's required capability (if it has one) runs on the site
+ * being edited. Categories with no requirement always pass, as does
+ * everything when no set was supplied.
+ */ export function isCategoryCapabilityEnabled(category, enabledPluginIds) {
+    if (!enabledPluginIds) return true;
+    const required = category ? CATEGORY_REQUIRED_CAPABILITY[category] : undefined;
+    return !required || enabledPluginIds.includes(required);
+}
+export function isFromEnabledPlugin(item, enabledPluginIds) {
+    if (!enabledPluginIds) return true;
+    const pluginId = item == null ? void 0 : item.pluginId;
+    return !pluginId || enabledPluginIds.includes(pluginId);
+}
+/**
+ * Whether a REGISTERED component must be drawn as though it were not
+ * registered at all, because its first-party plugin does not run on the site
+ * being rendered (AGL-3033).
+ *
+ * The component registry is process-global and only grows. On a server that
+ * serves many sites, a bundle one site's page loaded stays registered for
+ * every later render, so asking the registry alone draws a switched-off
+ * plugin's elements in full on a site that switched it off — while that
+ * site's browser, which never loads the bundle, draws the unregistered
+ * fallback. The HTML shows what the site switched off, and hydration fails on
+ * the difference. Asking the rendered site's plugin set as well makes the
+ * server and the browser give one answer.
+ *
+ * Only a FIRST-PARTY id is asked about. A marketplace bundle's components name
+ * the id in its manifest, which is not the listing id the site's set carries,
+ * and a component naming no plugin belongs to none. Both render as registered,
+ * as does the base library, which no site can switch off.
+ *
+ * An EMPTY set is no answer. Every set a site resolves carries the base
+ * library, so an empty one is a surface saying it has no site to answer for —
+ * the console's editor gate publishes `[]` while the URL names no workspace it
+ * has resolved — and drawing every element there as unregistered would blank
+ * the canvas. It renders as though no set was supplied.
+ */ export function isSwitchedOffForRenderedSite(pluginId, enabledPluginIds) {
+    if (!pluginId || !(enabledPluginIds == null ? void 0 : enabledPluginIds.length)) return false;
+    if (isLockedOnForSite(pluginId)) return false;
+    return isFirstPartyPlugin(pluginId) && !enabledPluginIds.includes(pluginId);
+}
+export default EnabledPluginsContext;
+
+//# sourceMappingURL=enabled-plugins-context.js.map

package/src/lib/app-utils/enabled-plugins-context.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/enabled-plugins-context.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 { createContext, useContext } from 'react'\nimport { ComponentCategory } from '../foundation/constants/components'\nimport {\n  ACCOUNTS_PLUGIN_ID,\n  isFirstPartyPlugin,\n  isLockedOnForSite,\n} from '../plugin-manager/enabled-plugins'\n\n/**\n * The EDITOR's view of per-site plugin enablement (AGL-1014).\n *\n * `enabledPlugins` is a boundary, not a preference, and the issue names four\n * surfaces that must enforce it identically: console navigation, the editor,\n * published sites, and API dispatch. The other three read\n * `resolveHostEnabledPlugins` on the server or subtract the deny-list in the\n * console shell. This context is how the same answer reaches the besigner —\n * the host app resolves it (only it can read an org and a host) and publishes\n * it; the designer stays storage-agnostic.\n *\n * It has to be a READ-TIME filter rather than a narrower load. The preset\n * registry is a module-global union that only ever grows: `consolePluginLoader`\n * never unloads a bundle, and a plugin whose site components registered while\n * editing site A goes on offering palette entries on site B. Loading less\n * cannot un-register what is already there, so the component drawer filters\n * every entry against this set instead.\n *\n * `undefined` means no set was supplied and leaves consumers unfiltered — the\n * same opt-in shape `listConsoleExtensions` uses, so surfaces with no host\n * (the platform email editor, tests) behave exactly as before.\n */\nexport const EnabledPluginsContext = createContext<\n  readonly string[] | undefined\n>(undefined)\nEnabledPluginsContext.displayName = 'EnabledPluginsContext'\n\n/** The edited site's effective plugin ids, or undefined where none is set. */\nexport function useEnabledPlugins(): readonly string[] | undefined {\n  return useContext(EnabledPluginsContext)\n}\n\n/**\n * Whether a registry entry's owning plugin runs on the site being edited.\n *\n * An entry with no `pluginId` belongs to no plugin, so no deny-list entry can\n * name it and it passes; so does everything when no set was supplied.\n */\n/**\n * Component categories whose entries follow a per-site CAPABILITY rather\n * than the bundle that ships them (AGL-2486).\n *\n * The Members blocks — Member sign-in, Member sign-up, Password recovery —\n * are registered by the COMMERCE bundle, so `pluginId` alone said \"commerce\n * is on, offer them\" on sites whose `/signin`, `/signup` and `/recover`\n * return 404. An author drops a sign-in block on a page, publishes it, and\n * finds out from a visitor.\n *\n * Attribution by category rather than by re-registering the components\n * under the `accounts` id: re-registering moves where they LOAD from and\n * would change what sites already using those blocks serve. This map is\n * read-time only — it decides what the picker OFFERS, never what a page\n * that already contains one renders.\n */\nexport const CATEGORY_REQUIRED_CAPABILITY: Readonly<Record<string, string>> = {\n  [ComponentCategory.MEMBERS]: ACCOUNTS_PLUGIN_ID,\n}\n\n/**\n * Whether a category's required capability (if it has one) runs on the site\n * being edited. Categories with no requirement always pass, as does\n * everything when no set was supplied.\n */\nexport function isCategoryCapabilityEnabled(\n  category: string | undefined,\n  enabledPluginIds: readonly string[] | undefined,\n): boolean {\n  if (!enabledPluginIds) return true\n  const required = category ? CATEGORY_REQUIRED_CAPABILITY[category] : undefined\n  return !required || enabledPluginIds.includes(required)\n}\n\nexport function isFromEnabledPlugin(\n  item: { pluginId?: string } | undefined,\n  enabledPluginIds: readonly string[] | undefined,\n): boolean {\n  if (!enabledPluginIds) return true\n  const pluginId = item?.pluginId\n  return !pluginId || enabledPluginIds.includes(pluginId)\n}\n\n/**\n * Whether a REGISTERED component must be drawn as though it were not\n * registered at all, because its first-party plugin does not run on the site\n * being rendered (AGL-3033).\n *\n * The component registry is process-global and only grows. On a server that\n * serves many sites, a bundle one site's page loaded stays registered for\n * every later render, so asking the registry alone draws a switched-off\n * plugin's elements in full on a site that switched it off — while that\n * site's browser, which never loads the bundle, draws the unregistered\n * fallback. The HTML shows what the site switched off, and hydration fails on\n * the difference. Asking the rendered site's plugin set as well makes the\n * server and the browser give one answer.\n *\n * Only a FIRST-PARTY id is asked about. A marketplace bundle's components name\n * the id in its manifest, which is not the listing id the site's set carries,\n * and a component naming no plugin belongs to none. Both render as registered,\n * as does the base library, which no site can switch off.\n *\n * An EMPTY set is no answer. Every set a site resolves carries the base\n * library, so an empty one is a surface saying it has no site to answer for —\n * the console's editor gate publishes `[]` while the URL names no workspace it\n * has resolved — and drawing every element there as unregistered would blank\n * the canvas. It renders as though no set was supplied.\n */\nexport function isSwitchedOffForRenderedSite(\n  pluginId: string | undefined,\n  enabledPluginIds: readonly string[] | undefined,\n): boolean {\n  if (!pluginId || !enabledPluginIds?.length) return false\n  if (isLockedOnForSite(pluginId)) return false\n  return isFirstPartyPlugin(pluginId) && !enabledPluginIds.includes(pluginId)\n}\n\nexport default EnabledPluginsContext\n"],"names":["createContext","useContext","ComponentCategory","ACCOUNTS_PLUGIN_ID","isFirstPartyPlugin","isLockedOnForSite","EnabledPluginsContext","undefined","displayName","useEnabledPlugins","CATEGORY_REQUIRED_CAPABILITY","MEMBERS","isCategoryCapabilityEnabled","category","enabledPluginIds","required","includes","isFromEnabledPlugin","item","pluginId","isSwitchedOffForRenderedSite","length"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED,SAASA,aAAa,EAAEC,UAAU,QAAQ,QAAO;AACjD,SAASC,iBAAiB,QAAQ,wCAAoC;AACtE,SACEC,kBAAkB,EAClBC,kBAAkB,EAClBC,iBAAiB,QACZ,uCAAmC;AAE1C;;;;;;;;;;;;;;;;;;;;;CAqBC,GACD,OAAO,MAAMC,wBAAwBN,cAEnCO,WAAU;AACZD,sBAAsBE,WAAW,GAAG;AAEpC,4EAA4E,GAC5E,OAAO,SAASC;IACd,OAAOR,WAAWK;AACpB;AAEA;;;;;CAKC,GACD;;;;;;;;;;;;;;;CAeC,GACD,OAAO,MAAMI,+BAAiE;IAC5E,CAACR,kBAAkBS,OAAO,CAAC,EAAER;AAC/B,EAAC;AAED;;;;CAIC,GACD,OAAO,SAASS,4BACdC,QAA4B,EAC5BC,gBAA+C;IAE/C,IAAI,CAACA,kBAAkB,OAAO;IAC9B,MAAMC,WAAWF,WAAWH,4BAA4B,CAACG,SAAS,GAAGN;IACrE,OAAO,CAACQ,YAAYD,iBAAiBE,QAAQ,CAACD;AAChD;AAEA,OAAO,SAASE,oBACdC,IAAuC,EACvCJ,gBAA+C;IAE/C,IAAI,CAACA,kBAAkB,OAAO;IAC9B,MAAMK,WAAWD,wBAAAA,KAAMC,QAAQ;IAC/B,OAAO,CAACA,YAAYL,iBAAiBE,QAAQ,CAACG;AAChD;AAEA;;;;;;;;;;;;;;;;;;;;;;;;CAwBC,GACD,OAAO,SAASC,6BACdD,QAA4B,EAC5BL,gBAA+C;IAE/C,IAAI,CAACK,YAAY,EAACL,oCAAAA,iBAAkBO,MAAM,GAAE,OAAO;IACnD,IAAIhB,kBAAkBc,WAAW,OAAO;IACxC,OAAOf,mBAAmBe,aAAa,CAACL,iBAAiBE,QAAQ,CAACG;AACpE;AAEA,eAAeb,sBAAqB"}

package/src/lib/app-utils/ensure-canvas-root.d.ts

@@ -0,0 +1,38 @@
+/**
+ * @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.
+ */
+type Nodes = Record<string, any>;
+/**
+ * Guarantee the canvas gets a root (AGL-931).
+ *
+ * `setNodes` stores whatever it is handed and `rootNode` looks up
+ * `_@_` exactly, so a map without it leaves the editor with no root: the
+ * hierarchy renders 'Invalid node' and Add Element is disabled. That is not
+ * merely an empty editor — it is one with no way out, so the document can
+ * never be repaired from the UI. AGL-753 hit this with a component stored as
+ * `nodes: {}`; screens and layouts had no equivalent guard at all.
+ *
+ * A rootless map keeps its content rather than being replaced: every node
+ * with no resolvable parent is adopted by the synthetic root. Recovering
+ * into an editable document beats discarding what is there, and for a screen
+ * or layout the result is the shape it should have had all along.
+ *
+ * Deliberately NOT `definitionToCanvasTree`: that one is about the
+ * definition shape, where a single promoted root is wrapped and unwrapped
+ * again on publish. This is the shared floor under every editor.
+ */
+export declare function ensureCanvasRoot(nodes: Nodes | undefined): Nodes;
+export default ensureCanvasRoot;

package/src/lib/app-utils/ensure-canvas-root.js

@@ -0,0 +1,61 @@
+import { _ as _extends } from "@swc/helpers/_/_extends";
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ import { CANVAS_ROOT_ELEMENT_ID } from "../foundation/constants/canvas.js";
+/**
+ * Guarantee the canvas gets a root (AGL-931).
+ *
+ * `setNodes` stores whatever it is handed and `rootNode` looks up
+ * `_@_` exactly, so a map without it leaves the editor with no root: the
+ * hierarchy renders 'Invalid node' and Add Element is disabled. That is not
+ * merely an empty editor — it is one with no way out, so the document can
+ * never be repaired from the UI. AGL-753 hit this with a component stored as
+ * `nodes: {}`; screens and layouts had no equivalent guard at all.
+ *
+ * A rootless map keeps its content rather than being replaced: every node
+ * with no resolvable parent is adopted by the synthetic root. Recovering
+ * into an editable document beats discarding what is there, and for a screen
+ * or layout the result is the shape it should have had all along.
+ *
+ * Deliberately NOT `definitionToCanvasTree`: that one is about the
+ * definition shape, where a single promoted root is wrapped and unwrapped
+ * again on publish. This is the shared floor under every editor.
+ */ export function ensureCanvasRoot(nodes) {
+    const map = nodes != null ? nodes : {};
+    if (map[CANVAS_ROOT_ELEMENT_ID]) return map;
+    // A parent that is not itself in the map is no parent — that node is as
+    // much a root as one with no `parentId` at all.
+    const roots = Object.keys(map).filter((id)=>{
+        var _map_id;
+        return !((_map_id = map[id]) == null ? void 0 : _map_id.parentId) || !map[map[id].parentId];
+    });
+    return _extends({}, Object.fromEntries(Object.entries(map).map(([id, node])=>[
+            id,
+            roots.includes(id) ? _extends({}, node, {
+                parentId: CANVAS_ROOT_ELEMENT_ID
+            }) : node
+        ])), {
+        [CANVAS_ROOT_ELEMENT_ID]: {
+            $id: CANVAS_ROOT_ELEMENT_ID,
+            componentId: 'div',
+            parentId: null,
+            nodes: roots
+        }
+    });
+}
+export default ensureCanvasRoot;
+
+//# sourceMappingURL=ensure-canvas-root.js.map

package/src/lib/app-utils/ensure-canvas-root.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/ensure-canvas-root.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 { CANVAS_ROOT_ELEMENT_ID } from '../foundation/constants/canvas'\n\ntype Nodes = Record<string, any>\n\n/**\n * Guarantee the canvas gets a root (AGL-931).\n *\n * `setNodes` stores whatever it is handed and `rootNode` looks up\n * `_@_` exactly, so a map without it leaves the editor with no root: the\n * hierarchy renders 'Invalid node' and Add Element is disabled. That is not\n * merely an empty editor — it is one with no way out, so the document can\n * never be repaired from the UI. AGL-753 hit this with a component stored as\n * `nodes: {}`; screens and layouts had no equivalent guard at all.\n *\n * A rootless map keeps its content rather than being replaced: every node\n * with no resolvable parent is adopted by the synthetic root. Recovering\n * into an editable document beats discarding what is there, and for a screen\n * or layout the result is the shape it should have had all along.\n *\n * Deliberately NOT `definitionToCanvasTree`: that one is about the\n * definition shape, where a single promoted root is wrapped and unwrapped\n * again on publish. This is the shared floor under every editor.\n */\nexport function ensureCanvasRoot(nodes: Nodes | undefined): Nodes {\n  const map = nodes ?? {}\n  if (map[CANVAS_ROOT_ELEMENT_ID]) return map\n\n  // A parent that is not itself in the map is no parent — that node is as\n  // much a root as one with no `parentId` at all.\n  const roots = Object.keys(map).filter(\n    (id) => !map[id]?.parentId || !map[map[id].parentId],\n  )\n\n  return {\n    ...Object.fromEntries(\n      Object.entries(map).map(([id, node]) => [\n        id,\n        roots.includes(id) ? { ...node, parentId: CANVAS_ROOT_ELEMENT_ID } : node,\n      ]),\n    ),\n    [CANVAS_ROOT_ELEMENT_ID]: {\n      $id: CANVAS_ROOT_ELEMENT_ID,\n      componentId: 'div',\n      parentId: null,\n      nodes: roots,\n    },\n  }\n}\n\nexport default ensureCanvasRoot\n"],"names":["CANVAS_ROOT_ELEMENT_ID","ensureCanvasRoot","nodes","map","roots","Object","keys","filter","id","parentId","fromEntries","entries","node","includes","$id","componentId"],"mappings":";AAAA;;;;;;;;;;;;;;;CAeC,GAED,SAASA,sBAAsB,QAAQ,oCAAgC;AAIvE;;;;;;;;;;;;;;;;;;CAkBC,GACD,OAAO,SAASC,iBAAiBC,KAAwB;IACvD,MAAMC,MAAMD,gBAAAA,QAAS,CAAC;IACtB,IAAIC,GAAG,CAACH,uBAAuB,EAAE,OAAOG;IAExC,wEAAwE;IACxE,gDAAgD;IAChD,MAAMC,QAAQC,OAAOC,IAAI,CAACH,KAAKI,MAAM,CACnC,CAACC;YAAQL;eAAD,GAACA,UAAAA,GAAG,CAACK,GAAG,qBAAPL,QAASM,QAAQ,KAAI,CAACN,GAAG,CAACA,GAAG,CAACK,GAAG,CAACC,QAAQ,CAAC;;IAGtD,OAAO,aACFJ,OAAOK,WAAW,CACnBL,OAAOM,OAAO,CAACR,KAAKA,GAAG,CAAC,CAAC,CAACK,IAAII,KAAK,GAAK;YACtCJ;YACAJ,MAAMS,QAAQ,CAACL,MAAM,aAAKI;gBAAMH,UAAUT;iBAA2BY;SACtE;QAEH,CAACZ,uBAAuB,EAAE;YACxBc,KAAKd;YACLe,aAAa;YACbN,UAAU;YACVP,OAAOE;QACT;;AAEJ;AAEA,eAAeH,iBAAgB"}

package/src/lib/app-utils/entity-picker-context.d.ts

@@ -0,0 +1,199 @@
+export interface EntityOption {
+    /** Stable document id — the persisted reference (AGL-343/344). */
+    id: string;
+    /** Current display name, resolved at edit time. */
+    label: string;
+}
+/**
+ * Edit-time option lists for id-based entity pickers in component
+ * attributes (products, collections, categories, datasets, forms). Names are
+ * display-only; nodes persist the id, so renames never break references —
+ * the same contract as {@link ScreenLinkContext}. Provided by the
+ * console's besigner/preview surfaces; absent on the tenant (the tenant
+ * only resolves ids, never lists them).
+ */
+/** The lists a picker can ask for. */
+export type EntityPickerKind = 'products' | 'collections' | 'categories' | 'datasets' | 'forms';
+/**
+ * How much an empty list is worth believing.
+ *
+ * Every one of these renders as a dropdown with no entries, and an author
+ * looking at four identical empty dropdowns cannot tell "this site has no
+ * forms yet" from "the read failed" from "this editor never lists forms at
+ * all". Only the first of those is a fact about their site; the other two
+ * are the picker being broken, and a picker that cannot say which it is
+ * sends the author looking for a form they already made.
+ *
+ * - `unavailable` — no provider is mounted, so nothing on this surface can
+ *   list entities. The tenant, and any editor outside a host.
+ * - `loading` — a read is open or about to be, and no answer has arrived.
+ *   Also the state of a list nothing has asked for yet: demand is declared
+ *   on the same commit that would display it, so "not asked" and "asked,
+ *   unanswered" are the same beat.
+ * - `ready` — the read settled. An empty list here IS the site's answer.
+ * - `error` — the read failed. Empty means nothing.
+ */
+export type EntityListState = 'unavailable' | 'loading' | 'ready' | 'error';
+/**
+ * How many documents a picker BROWSES.
+ *
+ * A picker is not a catalog viewer. It is a dropdown on a besigner surface
+ * where the author is placing one element, and no table in the console offers
+ * a page past `TABLE_PAGE_SIZE_OPTIONS` — a dropdown is the smaller surface of
+ * the two, not the larger.
+ *
+ * The middle of that range rather than its floor: a table has a pager under it
+ * and a dropdown does not, so the page a reader cannot advance is worth more
+ * rows than the one they can.
+ *
+ * What makes this size SAFE is that browsing is the only job it does. A stored
+ * value is named by {@link EntityPickerContextValue.resolve} — one keyed read
+ * for the one document, exact at any catalog size — so nothing here has to be
+ * wide enough to contain whatever an author picked last month. A window that
+ * carried both jobs would have to be, and would still render a bound element
+ * as unbound past its own width; widening this cannot fix that, only make it
+ * rarer and more expensive.
+ */
+export declare const ENTITY_PICKER_BROWSE_LIMIT = 25;
+/**
+ * How many documents a server-side name search may return.
+ *
+ * The same size as the browse window, for the same reason: a reader who has
+ * typed a query and still faces 25 rows narrows it further rather than
+ * scrolling. Only the kinds in {@link EntityPickerContextValue.searchable}
+ * spend this at all.
+ */
+export declare const ENTITY_PICKER_SEARCH_LIMIT = 25;
+export interface EntityPickerContextValue {
+    products?: EntityOption[];
+    collections?: EntityOption[];
+    categories?: EntityOption[];
+    datasets?: EntityOption[];
+    /** The host's form entities, id-first, feeding FORM_SELECT attributes. */
+    forms?: EntityOption[];
+    /**
+     * Per-dataset model fields (AGL-556), keyed by dataset id, in model
+     * order: id = stable model fieldId, label = current display name. Feeds
+     * DATASET_FIELD_SELECT attributes (e.g. a form field's "Maps to schema
+     * field" picker).
+     */
+    datasetFields?: Record<string, EntityOption[]>;
+    /**
+     * Declare that a picker of this kind is on screen (AGL-703).
+     *
+     * The provider reads these lists from Firestore, and it used to read ALL of
+     * them the moment the besigner opened — up to 300 products, 200 catalog
+     * collections, 200 categories and 200 datasets, on a site with a real
+     * catalog, for pickers most editing sessions never open. Nothing about
+     * moving a heading needs the product list.
+     *
+     * So the lists are demand-driven now, and the demand signal is the thing
+     * that would DISPLAY one: a selected node whose schema declares a
+     * `PRODUCT_SELECT`, a repeat bound to a dataset. Call this when that is
+     * true and read the list on the render after; until then the list is
+     * absent, exactly as it is for the beat before any listener syncs.
+     *
+     * Optional, and absent on the tenant — which resolves ids and never lists
+     * them, so nothing there has a picker to ask for.
+     */
+    request?: (kind: EntityPickerKind) => void;
+    /**
+     * Per-kind read state, so a picker can say WHY it has nothing to offer.
+     * A kind the provider omits reads as `loading`; see {@link entityListState}.
+     */
+    status?: Partial<Record<EntityPickerKind, EntityListState>>;
+    /**
+     * The browse window came back FULL for this kind, so the list above is a
+     * page of the site's catalog and not the whole of it.
+     *
+     * Measured with a probe — the read asks for one document past
+     * {@link ENTITY_PICKER_BROWSE_LIMIT} and the extra one is never offered —
+     * so this is a fact about the collection rather than a guess from the
+     * window being exactly full.
+     *
+     * A picker owes the reader this sentence for the same reason the inbox's
+     * form filter does: "not in the picker" and "does not exist" are the same
+     * empty dropdown, and only one of them is a fact about their site.
+     */
+    truncated?: Partial<Record<EntityPickerKind, boolean>>;
+    /**
+     * This kind's documents carry the name-search keys, so a typed query
+     * reaches the WHOLE collection rather than only the browse window.
+     *
+     * True for products alone today: `nameTokens`/`nameLower` are stamped by
+     * the catalog's own write path, and `hosts/{host}/resources` deliberately
+     * does not stamp them on the other four kinds. A picker for a kind that is
+     * absent here must say its search covers the window only — claiming
+     * otherwise would let an unfound entity read as a nonexistent one.
+     */
+    searchable?: Partial<Record<EntityPickerKind, boolean>>;
+    /**
+     * Narrow this kind's offered list to what somebody typed.
+     *
+     * Matching is the provider's, not the dropdown's: it is the only side that
+     * can merge the window's own matches with the ones a server query found
+     * past it, and it uses `scoreMatch` so a query matches a word ANYWHERE in a
+     * name — the same rule the switchers and global search follow.
+     *
+     * Passing an empty string restores the browse window.
+     */
+    search?: (kind: EntityPickerKind, text: string) => void;
+    /**
+     * Resolve ONE stored id to its current name, whatever the browse window
+     * holds.
+     *
+     * Deliberately NOT a job for the browse list, though a bulk read could do
+     * both. Sharing one read makes the list's width the limit on which stored
+     * values can be named, and past that width a picker renders a bound element
+     * as UNBOUND rather than as its label — an empty control on an element that
+     * is set, which an author repairs by picking again. That is how a correct
+     * reference gets replaced with a different one.
+     *
+     * One keyed `getDoc` for one document instead: exact at any catalog size,
+     * and asked for only when a node actually carries a value. Results land in
+     * {@link resolved} and are never re-read.
+     */
+    resolve?: (kind: EntityPickerKind, id: string) => void;
+    /**
+     * What {@link resolve} found, keyed by kind and then by id.
+     *
+     * Three states, and the picker renders a different label for each: an
+     * `EntityOption` is the resolved name, `null` is a settled read that found
+     * NO such document, and an absent key is a resolution still in flight.
+     * Absent must never render as missing — a picker that flashed "unavailable"
+     * over every live reference for the beat before its read landed would teach
+     * authors to ignore the one warning that matters.
+     */
+    resolved?: Partial<Record<EntityPickerKind, Readonly<Record<string, EntityOption | null>>>>;
+}
+/**
+ * What the picker for `kind` should believe about its own emptiness.
+ *
+ * `request` is the "a provider is mounted" signal — it is the one member the
+ * contract already says is absent wherever nothing lists entities — so a
+ * surface with no provider resolves to `unavailable` rather than passing an
+ * empty list off as the site's answer.
+ */
+export declare function entityListState(context: EntityPickerContextValue | undefined, kind: EntityPickerKind): EntityListState;
+/**
+ * The id whose label a picker still needs a keyed read to learn, if any.
+ *
+ * Part of the contract rather than of one screen, because two surfaces ask
+ * it — the attributes panel about a node's picker value, and the insert-token
+ * menu about the dataset a repeat is bound to — and an answer that differed
+ * between them would be a second keyed read for a document one of them
+ * already had.
+ *
+ * Four cases resolve to "ask nobody", and each is a read not spent: there is
+ * no value; the browse window already carries it, which is the common case on
+ * a small site; a resolution has already answered, including the answer that
+ * the document is gone; or the browse read has not settled, so the window may
+ * be about to supply it for free.
+ *
+ * The last is the one worth stating. Asking while the listener is still
+ * loading would spend a keyed read on nearly every picker on every site,
+ * which is the cost splitting these two jobs exists to remove rather than to
+ * move.
+ */
+export declare function entityValueNeedsResolution(context: EntityPickerContextValue | undefined, kind: EntityPickerKind, value: unknown): string | undefined;
+export declare const EntityPickerContext: import("react").Context<EntityPickerContextValue>;