@aglyn/aglyn 1.0.0-beta.182 → 1.0.0-beta.183

package/src/lib/foundation/definitions/platform.types.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../../../../../libs/aglyn/src/lib/foundation/definitions/platform.types.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport type { HttpStatusCode } from '@aglyn/shared-data-enums'\nimport type { HostTheme } from '@aglyn/shared-data-types'\nimport type { ITimestamp } from '@aglyn/shared-util-timestamp'\nimport type {\n  AglynNodeSchema,\n  FieldComponentType,\n  NodeId,\n} from './components.types'\n// Type-only, so this stays a definitions file with no runtime edge into\n// `app-utils`: the two video shapes are DEFINED beside the code that\n// validates them (`normalizeVideoMetadata`, `parseMediaRendition`) so a\n// document field and its validator can never describe different things.\nimport type { MediaVideoMetadata } from '../../app-utils/media-metadata'\nimport type { MediaVideoRendition } from '../../app-utils/media-ref'\n\n/**\n * Platform-side definitions: documents, hosts, screens, media, users.\n * The ORG BILLING family (`AglynOrgBilling` and the Org* plan/entitlement\n * vocabulary) lives in `org-billing.types.ts` — see the docs-site glossary\n * for the org/workspace/tenant/host naming convention. (This file was\n * `workspace.types.ts`; renamed in AGL-443 because nothing in it is the\n * workspace/org entity.)\n */\nexport interface AglynDocument {\n  [field: string]: any\n}\n\nexport enum HostScreenStatus {\n  UNPUBLISHED = 0x1 << 0x1,\n  PUBLISHED = 0x1 << 0x2,\n  SCHEDULED_TO_PUBLISH_UNPUBLISHED = UNPUBLISHED | (0x1 << 0x3),\n  SCHEDULED_TO_UNPUBLISH_PUBLISHED = PUBLISHED | (0x1 << 0x4),\n  SCHEDULED_TO_UPDATE_PUBLISHED = PUBLISHED | (0x1 << 0x5),\n  SCHEDULED_TO_REVERT_UPDATE_PUBLISHED = PUBLISHED | (0x1 << 0x6),\n}\n\nexport enum HostScreenVisibility {\n  PUBLIC = 0x1 << 0x1,\n  UNLISTED = PUBLIC | (0x1 << 0x2),\n  PRIVATE = 0x1 << 0x3,\n  PASSWORD = PRIVATE | (0x1 << 0x4),\n  AUTHENTICATED = PRIVATE | (0x1 << 0x5),\n  AUTHORIZED = AUTHENTICATED | (0x1 << 0x6),\n}\n\nexport enum HostViewType {\n  SCREEN = 0x1,\n  LAYOUT = 0x2,\n  /** A besigner-designed email document (screen with kind 'email', AGL-395). */\n  EMAIL = 0x4,\n}\n\nexport enum HostViewFormat {\n  NORMALIZED = 0x1,\n  DENORMALIZED = 0x2,\n}\n\nexport enum HostEntityType {\n  ORGANIZATION = 0x1,\n  PERSON = 0x2,\n}\n\nexport enum HostRedirectParams {\n  IGNORE,\n  FORWARD = 0x1,\n  MATCH = 0x2,\n}\n\n/** Org document id (`orgs/{orgId}`). Formerly TenantUid (AGL-444). */\nexport type OrgUid = string\n\nexport type UserUid = string\n\nexport interface AglynUser extends AglynDocument {\n  $id: UserUid\n  admin?: boolean\n  email?: string\n}\n\n/**\n * Site-wide announcement bar config on the host doc (AGL-195). Text may\n * contain binding tokens; the tenant render resolves them server-side.\n */\nexport interface HostAnnouncementBar {\n  enabled?: boolean\n  text?: string\n  /** Optional link the whole bar navigates to. */\n  href?: string\n  backgroundColor?: string\n  textColor?: string\n  /** Visitors may hide the bar; hidden state re-arms when text changes. */\n  dismissible?: boolean\n}\n\n/**\n * Promotional popup config on the host doc (AGL-196); one per host,\n * marketingOverlays-gated. Body text may contain binding tokens; the\n * tenant render resolves them server-side.\n */\nexport interface HostPopup {\n  enabled?: boolean\n  headline?: string\n  body?: string\n  /** Media-library image URL shown above the copy. */\n  imageUrl?: string\n  /**\n   * Alt text for {@link imageUrl} (AGL-1896). Defaults from the chosen DAM\n   * asset's own alt when the author picks through \"Browse media\"; empty\n   * still renders `alt=\"\"`, which is correct for a decorative banner.\n   */\n  imageAlt?: string\n  ctaLabel?: string\n  ctaHref?: string\n  /** Render an email-capture field posting into the forms pipeline. */\n  collectEmail?: boolean\n  /** How the popup opens. */\n  trigger?: 'delay' | 'scroll' | 'exit'\n  /** Seconds (delay trigger) or percent 0-100 (scroll trigger). */\n  triggerValue?: number\n  /**\n   * Re-show after this many days once dismissed (localStorage).\n   *\n   * Ignored when {@link oncePerSession} is set — the two are alternative\n   * answers to the same question, and honouring both would mean a popup\n   * suppressed for the session AND for seven days after it.\n   */\n  frequencyDays?: number\n  /**\n   * Show at most once per browser SESSION (AGL-2174).\n   *\n   * `/product/marketing` sells \"per-session frequency caps\" in as many\n   * words, and the only cap the product had was day-based — a visitor who\n   * dismissed a popup did not see it again for a week, which is a\n   * different promise. Backed by `sessionStorage`, which is exactly the\n   * lifetime the copy describes: it clears when the tab closes.\n   */\n  oncePerSession?: boolean\n  /** Optional showing window (epoch millis; simple to serialize). */\n  startAtMs?: number\n  endAtMs?: number\n}\n\nexport type ProjectUid = string\nexport type ProjectNumber = number\n\nexport type HostUid = string\nexport type HostPath = string\nexport type HostMediaUid = string\n\n/**\n * Persisted MUI theme customization for a host's published site.\n * Canonical shape lives in `@aglyn/shared-data-types` so UI-scope libs can\n * consume it without depending on this framework lib.\n */\nexport type AglynHostTheme = HostTheme\n\n/** Host-scoped document */\nexport interface AglynHost extends AglynDocument {\n  $id: HostUid\n  /** Owning org (AGL-233); mirrored into `hostIndex/{hostId}`. */\n  orgId?: OrgUid\n  /** Membership projection from the org (AGL-233): uid → role tier. */\n  memberRoles?: Record<UserUid, string>\n  subdomain?: string\n  cname?: string\n  /** Site-wide announcement bar (AGL-195); marketingOverlays-gated. */\n  announcementBar?: HostAnnouncementBar\n  /** Promotional popup (AGL-196); marketingOverlays-gated. */\n  popup?: HostPopup\n  displayName?: string\n  /**\n   * Site logo URL (AGL-594): the host's own brand mark, shown by the\n   * tenant's navigation loader (and future chrome). Distinct from\n   * `seo.entity.logo`, which is publisher-semantic JSON-LD.\n   */\n  logoUrl?: string\n  seo?: {\n    title?: string\n    description?: string\n    separator?: string\n    favicon?: string\n    /**\n     * The square mark a visitor installs to their home screen — the `icons`\n     * entry of `/manifest.webmanifest`.\n     *\n     * Distinct from both of its neighbours, and the distinction is what the\n     * field exists for. {@link favicon} is drawn at 16–32px in a tab, so it is\n     * a glyph rather than artwork. `logoUrl` is the site's LOCKUP — a wordmark\n     * on most sites, which is a wide rectangle, and the manifest fell back to\n     * it for want of anything else: an installer that trusted a declared size\n     * painted a stretched or letterboxed tile on somebody's home screen.\n     *\n     * A `media:` reference or a plain URL, absolutized before it is written\n     * into the manifest because nothing fetches an install icon from the page\n     * that linked it. Unset falls back to `logoUrl`, which is what every site\n     * installs with today; a site with neither gets no `icons` array at all,\n     * so the browser uses a screenshot rather than a broken tile.\n     */\n    appIcon?: string\n    /**\n     * Site-wide default social card image (AGL-1337) — used by every page\n     * that sets none of its own. A `media:` reference (what the picker\n     * writes) or a raw URL; resolved and made absolute by\n     * `resolveSocialImage`, never emitted as stored.\n     *\n     * `''` is a CLEARED field, written directly to Firestore by the picker\n     * card rather than through the attributes form stack, which maps `''` to\n     * `undefined` and would leave a default nobody could remove (AGL-1191).\n     */\n    image?: string\n    /**\n     * Copied from the media record at pick time, and the FALLBACK rather than\n     * the answer: a replace rewrites the asset's pair and cannot reach this\n     * copy, so the head prefers what the asset's document records when the\n     * page is composed (AGL-2850). See `resolveSocialImage`.\n     */\n    imageWidth?: number\n    imageHeight?: number\n    /**\n     * `og:image:alt` (AGL-2417) — what the card SHOWS, for the screen\n     * readers that announce a social preview. Defaulted from the chosen DAM\n     * asset's own alt at pick time and editable per surface; stored beside\n     * the reference so `resolveSocialImage` emits the description belonging\n     * to the image that actually won the precedence list.\n     *\n     * Blank is never stored: `og:image:alt=\"\"` asserts the image conveys\n     * nothing, which is not what an undescribed card means.\n     */\n    imageAlt?: string\n    /**\n     * Site-wide \"discourage search engines\" (AGL-1263): `robots.txt` refuses\n     * everything, the sitemap goes empty, and every page carries `noindex`.\n     * The staged-launch control — a site that is live but not ready to be\n     * found, which until now could only be approximated by setting each\n     * screen to {@link HostScreenVisibility.UNLISTED} one at a time.\n     *\n     * Absent means INDEX, and must keep meaning that. Reading a missing field\n     * as \"hide\" would let a schema slip de-index every customer at once.\n     */\n    discourageSearchEngines?: boolean\n    entity?: {\n      type?: HostEntityType\n      name?: string\n      logo?: string\n      /**\n       * What the publisher IS, in a sentence — `Organization.description`\n       * (AGL-2716).\n       *\n       * Distinct from {@link AglynHost.seo.description}, which is the meta\n       * description of the site's home page: one describes a business, the\n       * other describes a document, and a site whose home page is a product\n       * launch should not be telling an AI assistant that the company is a\n       * product launch. Unset falls back to the site description, because a\n       * fallback that is approximately right beats an entity with no\n       * description at all — which is what every site published before this\n       * field existed.\n       */\n      description?: string\n      /**\n       * The publisher's own canonical address, when it is not this site —\n       * a brand site for a company whose main presence is elsewhere. Unset\n       * means this site's origin, which is the common case.\n       */\n      url?: string\n      /**\n       * Profiles that identify the SAME entity — `schema.org/sameAs`. The\n       * company's LinkedIn, its Crunchbase entry, its Wikipedia article. Not\n       * a link list: a page that merely mentions the entity is not the\n       * entity, and listing one teaches a consumer the wrong identity.\n       */\n      sameAs?: string[]\n      /**\n       * How to reach a person — `Organization.contactPoint`.\n       *\n       * Split into fields rather than stored as a `contactPoint` object\n       * because the console collects them as three form controls, and a\n       * nested object in a settings document is a shape a partial write can\n       * blank. Assembled at serialization; see `siteEntityJsonLd`.\n       */\n      email?: string\n      telephone?: string\n      /**\n       * Which kind of enquiry that contact answers — `customer support`,\n       * `sales`, `technical support`. Free text, because `schema.org` defines\n       * the property as text rather than an enumeration.\n       */\n      contactType?: string\n      /**\n       * Postal address — `Organization.address`, a `PostalAddress`.\n       *\n       * Every field optional and every field omitted when blank: a partial\n       * address is still a real answer to \"where are they\", while a\n       * `PostalAddress` carrying empty strings is a claim that the street is\n       * the empty string.\n       */\n      address?: {\n        streetAddress?: string\n        addressLocality?: string\n        addressRegion?: string\n        postalCode?: string\n        /** ISO 3166-1 alpha-2, or a country name. */\n        addressCountry?: string\n      }\n    }\n    /**\n     * Guidance for AI agents, published in `/llms.txt` (AGL-2716).\n     *\n     * Its own key rather than a field on `entity`, because it is about the\n     * SITE's usefulness rather than about who publishes it — and because the\n     * two are edited by different people at different times.\n     */\n    agent?: {\n      /**\n       * When an agent should reach for this site: the jobs it is the right\n       * source for, in the author's own words.\n       *\n       * Absent is not a gap. `buildLlmsTxt` derives a when-to-use section\n       * from what the site demonstrably publishes, so a site whose author\n       * writes nothing here still ships checkable guidance; this is the place\n       * to say the things that cannot be derived.\n       */\n      whenToUse?: string\n      /** How an agent should call the site — endpoints, etiquette, limits. */\n      howToUse?: string\n    }\n  }\n  /**\n   * Customer-configured third-party analytics (AGL-138/661). Long written by\n   * the console and read by the tenant through `any` casts; declared as of\n   * AGL-1498 so the write-deny guard sees it through the type rather than\n   * not at all. The id is format-checked (`GA_MEASUREMENT_ID_PATTERN`)\n   * before it reaches the inline script, and its LOADING is consent-gated\n   * by `visitor-consent.ts` — see `consent` below.\n   */\n  analytics?: {\n    gaMeasurementId?: string\n    /**\n     * Google Tag Manager container (AGL-2486), `GTM-XXXXXXX`.\n     *\n     * Declared here for the reason the `consent` comment below spells out at\n     * length: a field the console persists and the tenant reads, but that no\n     * type knows about, is how a whole-object write silently drops a sibling.\n     *\n     * Format-checked by `GTM_CONTAINER_ID_PATTERN` before it reaches an\n     * inline script, and consent-gated exactly as `gaMeasurementId` is — a\n     * container counts as a gated feature in `consentGatedCategories`, so a\n     * site running only a container still gets the banner. It has to: a\n     * container is the likeliest thing on a page to carry advertising tags,\n     * and advertising is opt-in worldwide.\n     */\n    gtmContainerId?: string\n    /**\n     * Advertising pixels, vendor id → that vendor's account id (AGL-2486).\n     *\n     * Declared here for exactly the reason the `gtmContainerId` comment above\n     * gives, and it is the field that proved the point: the console persisted\n     * it and the tenant read it through `advertising-tags.ts`, while no type\n     * knew about it. `aglyn-marketing` carries a live Meta pixel in it today,\n     * and a whole-object write to `analytics` would have dropped it silently.\n     *\n     * The vendor descriptors — which script each id loads, and therefore which\n     * hosts the CSP has to admit — live in `advertising-tags.ts`. An id here\n     * for a vendor with no descriptor loads nothing.\n     */\n    adTags?: Record<string, string> | null\n  }\n  /**\n   * Visitor consent tool (AGL-1498). The tool is ACTIVE when this is absent\n   * — but only ever on sites that use a consent-gated feature (today:\n   * `analytics.gaMeasurementId`); with none configured no consent UI exists\n   * and this map decides nothing. `disabled: true` is the host's opt-out\n   * (they run their own consent solution, and gated features load ungated).\n   * `mode` is the host's posture: `'geo'` (geo-conditional: implied consent\n   * with an always-available opt-out in opt-out regions, a prior-consent\n   * banner in EU/EEA/UK and unknown regions) or `'strict'` (the banner for\n   * everyone). Absent `mode` behaves as `'geo'`. Absent-means-active is the\n   * only safe default for the tool itself: a schema slip must fail toward\n   * asking, never toward silently tracking. See `visitor-consent.ts`.\n   *\n   * `advertising` (AGL-1649) is the host's opt-in to ASKING a second\n   * question. It was persisted by the console and read by the tenant for four\n   * days without being declared here — the same undeclared-field shape the\n   * `analytics` comment above says was fixed for AGL-1498, on the very key\n   * this issue exists to deliver. The cost is not typos: `consent` is an\n   * inline object type, so a whole-object write built against a type missing\n   * the key drops a host's advertising opt-in and TypeScript agrees with the\n   * drop. `consent-host-schema-coverage.spec.ts` now fails the build on any\n   * `consent.*` key that is written or read but not declared.\n   */\n  consent?: {\n    disabled?: boolean\n    mode?: 'geo' | 'strict'\n    /**\n     * Host opt-in to asking visitors about advertising storage (AGL-1649).\n     * PERSISTED NAME; absent or `false` — the state of every site that\n     * exists — means the visitor is asked about analytics only and\n     * `ad_storage`, `ad_user_data` and `ad_personalization` stay denied\n     * where AGL-1622 put them.\n     *\n     * `true` does not grant anything by itself — it makes the category\n     * REACHABLE. It adds a second, separate question to the banner and the\n     * privacy-choices panel, and where advertising then starts follows the\n     * visitor's region: asked-first in the prior-consent set (the EU 27, the\n     * EEA/EFTA three, the UK, Gibraltar, the outermost regions, and any\n     * visitor whose region cannot be determined), running from the first\n     * visit everywhere else on the same implied basis analytics uses. A\n     * refusal — declined, opted out, or GPC — denies it everywhere.\n     *\n     * See `advertisingGrantedByStatus`; this sentence and that function are\n     * locked together by `consent-advertising-copy-drift.spec.ts`, and the\n     * published Cookie Policy moves before either of them.\n     *\n     * Read only through `hostAsksAboutAdvertising`, which also requires a\n     * configured measurement id and tests `=== true`, so a truthy string out\n     * of a hand-edited document cannot turn a consent category on.\n     */\n    advertising?: boolean\n  }\n  screens?: Record<ScreenUid, ScreenSlug>\n  /** Screen rendered (noindex) for unmatched paths (AGL-87). */\n  notFoundScreenId?: ScreenUid\n  /**\n   * Designable error screens by status (AGL-131). `notFound` supersedes\n   * `notFoundScreenId` (kept in sync for back-compat).\n   */\n  errorScreens?: HostErrorScreens\n  /**\n   * Designable membership screens (AGL-553): which besigner-built screen\n   * renders at `/signin`, `/signup` and `/recover`. An empty slot falls back\n   * to the built-in form.\n   *\n   * ADMIN TIER, not authoring — the one thing that separates it from its\n   * sibling `errorScreens`, which is a binding to screens the editor already\n   * controls and serves only their own visitors. These three addresses are\n   * where a site's members type their password, so the field decides what a\n   * sign-in page IS. `enabledPlugins` is denied to an editor one tier down\n   * for deciding merely whether those addresses EXIST; the field that\n   * decides what they render cannot sit in a weaker tier than the field that\n   * opens them.\n   *\n   * It is also a live-content surface that does not go through the routing\n   * map: the tenant loader resolves the slot straight to a screen document,\n   * and `screenClaimsToBeAPage` asks only whether that screen is deleted. So\n   * `screens` being frozen for an `author` does not reach it, and an author\n   * — the role sold as \"edit content but not publish\" — could otherwise put\n   * a screen on the site's sign-in address without publishing anything.\n   */\n  authScreens?: HostAuthScreens\n  /** Maintenance mode (AGL-131): every path renders the 503 screen. */\n  maintenance?: boolean\n  /**\n   * STAFF host takedown (AGL-1501) — the host scope of the panic button,\n   * for an infected or abusive site. The same field family as the org's\n   * AGL-202 suspension: while `suspendedAt` is set (and `suspendedUntilMs`\n   * has not passed) the site serves the lockdown notice instead of content.\n   * Deliberately separate from `maintenance` above, which is the CUSTOMER'S\n   * own switch — a takedown the site's editors could clear from the client\n   * SDK would not be a takedown, so all four keys are client-denied in the\n   * rules and written only by /api/admin/lockdown. `suspendedMessage` is\n   * visitor-facing; timestamps are plain epoch ms (converter-safe).\n   * Normalized by `app-utils/lockdown.ts`.\n   */\n  suspendedAt?: number\n  suspendedReasonCode?: string\n  suspendedMessage?: string\n  suspendedUntilMs?: number\n  /**\n   * Per-site plugin deny-list (AGL-1014): plugin ids the org has enabled\n   * but this site switches OFF. Subtracted from the org's resolved set by\n   * `resolveHostEnabledPlugins` — the host can only ever narrow, never\n   * widen, and an absent field means every org-enabled plugin runs here.\n   * Writable by site ADMINS only (rules). The base component library's id is\n   * ignored; a plugin on for every workspace (AI) is switched off for this\n   * site like any other (AGL-3028).\n   */\n  disabledPlugins?: string[]\n  /**\n   * Per-site plugin OPT-IN list (AGL-2486): the `defaultOffPerSite` plugin\n   * ids this site has explicitly turned on. Today that is `accounts` — the\n   * user-accounts capability behind `/signin`, `/signup` and `/recover`.\n   *\n   * The companion of `disabledPlugins` above, not a duplicate of it, because\n   * a deny-list cannot express \"off until asked\": absent means ON there, and\n   * every published site was therefore serving member pages whether or not\n   * it had members. This field is what an absent value means OFF for, and it\n   * is read ONLY for ids the catalog marks default-off, so it can never\n   * widen a site past its org. Writable by site ADMINS only (rules).\n   */\n  enabledPlugins?: string[]\n  /**\n   * External image hosts this site's owner has approved (AGL-1152).\n   *\n   * The tenant's `img-src` is built from this list, per site, in the\n   * middleware — which is the only layer that runs ahead of the ISR cache, and\n   * therefore the only place a per-site policy can be set at all.\n   *\n   * ## Why the list exists rather than a platform-wide allowlist\n   *\n   * AGL-1726 refused to enforce `img-src` because hotlinking an external image\n   * is an ADVERTISED authoring feature (`image.tsx` tells authors to paste a\n   * URL), so a first-party-only policy would silently revoke a documented\n   * capability from every published site at once. Enforcement against a list\n   * the OWNER chose revokes nothing, and the console warns at authoring time\n   * so a refusal is never the first anyone hears of it.\n   *\n   * It is also what gives that issue's condition 6 — \"a rollback that does not\n   * need a deploy\" — an answer: this is host data, so widening or emptying it\n   * propagates within the verdict TTL with no Vercel build in the path.\n   *\n   * ⛔ NOT a place to put `firebasestorage.googleapis.com`. That host is PINNED\n   * in `security-origins.js` and deliberately not owner-removable: orgs without\n   * the paid `mediaCdn` entitlement store absolute download URLs, so an owner\n   * who deleted it would blank their own images (AGL-1726 condition 5).\n   *\n   * Stored as bare hostnames (`cdn.example.com`, or one leading `*.` label).\n   * Anything with a scheme, port, path or separator is REFUSED at the parse\n   * rather than repaired — `img-src` sources are space-delimited and\n   * directives `;`-delimited, so both are injection points. Writable by site\n   * ADMINS only (rules).\n   */\n  approvedImageHosts?: string[]\n  /** Site languages (AGL-164), e.g. ['en', 'es']; first is the default\n   * unless `defaultLocale` says otherwise. */\n  locales?: string[]\n  defaultLocale?: string\n  /**\n   * The IANA zone THIS SITE's published dates read in (AGL-3252) — absent\n   * means the workspace's `timeZone`, and absent there means UTC.\n   *\n   * AGL-3237 put the zone on the organization and said a per-site override\n   * was worth its own issue because it would need a second rules change. It\n   * does not: the host document's client branch is a deny-list, so a field\n   * it does not name is already writable, and what the override actually\n   * needed was the classification below. An agency running a Chicago site\n   * and a Berlin site out of one workspace is the case it exists for.\n   *\n   * Read through `resolveSiteTimeZone`, never directly: a stored zone can\n   * predate an IANA rename, and an unusable one has to fall back to the\n   * workspace rather than throw inside a page render.\n   */\n  timeZone?: string\n  /** Directory of shared layouts by display name (mirrors `screens`). */\n  layouts?: Record<LayoutUid, string>\n  theme?: AglynHostTheme\n\n  // CONCEPT: Redirect screens\n  redirects?: Record<RedirectUid, true>\n\n  // CONCEPT: Enterprise - Siloed projects\n  projectId?: ProjectUid\n  projectNumber?: ProjectNumber\n}\n\n/**\n * Host-document fields an editor may legitimately write, each with the reason\n * (AGL-1361). Everything else must be denied in the rules' host key diff.\n *\n * `host-write-deny-coverage.spec.ts` fails the build for any field of this\n * document that is in neither list, so \"I forgot\" is not a reachable state —\n * the answer that costs nothing is always to deny. The reason strings are the\n * point: they record that somebody decided, rather than that somebody did not\n * notice. AGL-1364 is what this catches, found while writing it.\n *\n * The bar for landing here: could a client rewrite change what the platform\n * DECIDES — an entitlement, a price, where a request routes, who may read? If\n * so it belongs in the rules, whatever the console does today.\n */\nexport const HOST_CLIENT_WRITABLE_FIELDS: Readonly<Record<string, string>> = {\n  displayName:\n    'The site name shown in the console. Cosmetic, org-scoped, and decides ' +\n    'nothing — the public address is `subdomain`/`cname`, both denied.',\n  logoUrl:\n    'The site brand mark rendered by the tenant nav (AGL-594). Authored ' +\n    'content pointing at already-public media; no gate reads it.',\n  seo:\n    'Title, description, favicon, app icon, social card and the AGL-1263 ' +\n    '`discourageSearchEngines` switch. All of it is authoring: the values ' +\n    'end up in the page the editor is already free to write.',\n  // `screens` LEFT this map in AGL-2334 and is now classified as denied,\n  // following the `disabledPlugins` precedent: it is TIERED, not freely\n  // client-writable. The reason it used to carry — \"an editor who may add a\n  // screen may name it\" — is still true of an editor and false of an\n  // `author`, and a field one role may write and another may not belongs on\n  // the denied side of this partition, where the tier is visible. Registering\n  // a path in this map is what makes a page reachable on the live site, so it\n  // is the publish surface an author is refused; see `canPublishHostContent`\n  // in cloud/firebase-firestore.rules.\n  layouts:\n    'The shared-layout directory. A layout has no route of its own, so unlike ' +\n    '`screens` this map decides nothing about reachability — it is an index ' +\n    'maintained alongside API-created layout docs. What publishing a layout ' +\n    'moves is the `versionId` pointer on the layout document, which the rules ' +\n    'freeze for an `author` there (AGL-2334), not here.',\n  redirects:\n    'The redirect directory. The redirect DOCS are API-create-only so the ' +\n    '`redirectsPerHost` quota has somewhere to be enforced; this is the index.',\n  notFoundScreenId:\n    'Which screen renders unmatched paths (AGL-87). Points at a screen the ' +\n    'editor already owns, and serves their own visitors only.',\n  errorScreens:\n    'Designable error screens by status (AGL-131). Same reasoning as ' +\n    '`notFoundScreenId` — a binding to screens this editor already controls.',\n  maintenance:\n    'Maintenance mode (AGL-131): every path renders the 503 screen. A ' +\n    'site-wide availability switch, but it only ever takes the editor\\'s OWN ' +\n    'site down, which they can equally do by deleting its screens.',\n  locales:\n    'Site languages (AGL-164). The `multilingual` entitlement is re-checked ' +\n    'server-side at page load, so writing this buys nothing a plan forbids.',\n  defaultLocale: 'Which of `locales` serves an unprefixed path. Authoring.',\n  timeZone:\n    'Which calendar day this site attributes a published instant to ' +\n    '(AGL-3252), overriding the workspace zone. Editorial, and it reaches ' +\n    'only this site\\'s own rendered dates — nothing bills, gates or routes ' +\n    'on it, and every read validates it through `isSupportedTimeZone`, so ' +\n    'the worst a rewrite can do is move one publisher\\'s archive by a day. ' +\n    'The org\\'s `timeZone` is denied because /api/orgs/settings owns the ' +\n    'whole org document; this one rides the settings form\\'s client write ' +\n    'beside `seo`, which is read by the same renderer for the same reason.',\n  theme:\n    'The persisted MUI theme for the published site. Authoring — the theme ' +\n    'editor writes it directly, and it renders only on this host.',\n  themeOverride:\n    'The editor\\'s local diff on top of an installed marketplace theme, ' +\n    'written wholesale by the setup page. Authoring. Its PROVENANCE ' +\n    '(`themeInstalledFrom`) is denied instead, which is the half that has to ' +\n    'be true for `isOverrideForCurrentTheme` to mean anything.',\n  announcementBar:\n    'Site-wide announcement bar (AGL-195). `marketingOverlays`-gated, but ' +\n    'the gate is enforced where it counts — `site-page-enricher` re-checks ' +\n    'the entitlement at RENDER, so a free plan writing this bar never ships ' +\n    'it. The console gate is the affordance, not the boundary.',\n  popup: 'Promotional popup (AGL-196). Identical reasoning to `announcementBar`.',\n  business:\n    'Support email, address and social links behind the AGL-1022 host ' +\n    'tokens. Publisher-authored contact detail that renders into their own ' +\n    'pages and emails; undeclared on this interface, so the guard sees it ' +\n    'through the resolver sweep rather than the type.',\n  analytics:\n    'The Google Analytics measurement id the host configures for their own ' +\n    'site (AGL-138). Authoring: it only ever tags THEIR pages, the tenant ' +\n    'format-checks it before the inline script, and loading it is ' +\n    'consent-gated (AGL-1498). A rewrite mis-tags the rewriter\\'s own site.',\n  consent:\n    'The visitor consent tool switch (AGL-1498). Decides whether the ' +\n    'host\\'s OWN site asks its visitors before loading the analytics the ' +\n    'host configured — their compliance posture on their own pages, exactly ' +\n    'like `seo.discourageSearchEngines`. No platform gate reads it.',\n  createdAt:\n    'Stamped by /api/hosts/create. Nothing gates on it — the org owns ' +\n    'billing dates — and console saves touch it freely.',\n  updatedAt:\n    'Bumped by console saves to drive \"last edited\" copy. Decides nothing; ' +\n    'a forged value misleads the editor about their own site.',\n}\n\n/**\n * Host-document keys that never reach Firestore, so the rules have no opinion.\n */\nexport const HOST_UNPERSISTED_FIELDS: Readonly<Record<string, string>> = {\n  $id: 'The document id, attached on read by the Firestore hooks. Never a field.',\n}\n\n/** Error-screen bindings by HTTP-ish status (AGL-131). */\nexport interface HostErrorScreens {\n  notFound?: ScreenUid\n  unauthorized?: ScreenUid\n  forbidden?: ScreenUid\n  unavailable?: ScreenUid\n}\n\n/**\n * The membership screen slots (AGL-553), keyed as the console card and the\n * tenant loader spell them. The names carry the `ScreenId` suffix because\n * that is how they are persisted; the console writes them as dotted field\n * paths (`authScreens.signinScreenId`).\n */\nexport interface HostAuthScreens {\n  signinScreenId?: ScreenUid\n  signupScreenId?: ScreenUid\n  recoveryScreenId?: ScreenUid\n}\n\n/**\n * The error slots, as a value (AGL-2092).\n *\n * The console card enumerated these separately and so did nothing else, which\n * was fine while the list was only a list. It stopped being only a list when\n * `kind: 'error'` made an assigned screen stop counting against\n * `screensPerHost`: the number of slots is now the BOUND on how many screens a\n * host can take off its plan that way, so the bound and the pickers have to be\n * the same four things or the exemption is unbounded in one of them.\n *\n * `ERROR_SCREEN_MAX_PER_HOST` is `.length` of this, deliberately — adding a\n * fifth status here widens the exemption to five, which is correct and is the\n * only way it should ever widen.\n */\nexport const HOST_ERROR_SCREEN_SLOTS = [\n  'notFound',\n  'unauthorized',\n  'forbidden',\n  'unavailable',\n] as const\n\nexport type HostErrorScreenSlot = (typeof HOST_ERROR_SCREEN_SLOTS)[number]\n\nexport type ScreenUid = string\nexport type ScreenSlug = string\nexport type VersionUid = string\nexport type LayoutUid = string\n\n/**\n * Who may see an org-owned resource (AGL-1037): `'org'` is every site in\n * the org, `host:{hostId}` names one. Lives here rather than beside its\n * helpers in `app-utils/scope-tokens` because foundation cannot import\n * app-utils; that module re-exports this type along with the helpers.\n */\nexport type ScopeToken = 'org' | `host:${string}`\n\n/**\n * Uploaded media metadata (AGL-72): the binary lives in Firebase Storage at\n * `hosts/{hostId}/media/{mediaId}`; this doc mirrors it in Firestore at the\n * same logical path so the library can list without Storage list calls.\n */\nexport interface AglynHostMedia {\n  $id: HostMediaUid\n  fileName?: string\n  contentType?: string\n  sizeBytes?: number\n  /** Download URL captured at upload time; nodes reference this directly. */\n  url?: string\n  /**\n   * Folder doc id in `hosts/{hostId}/mediaFolders` (AGL-171); null/absent\n   * = root. Replaces the legacy free-text `folder` string below.\n   */\n  folderId?: string | null\n  /** Legacy AGL-124 free-text folder; read as fallback until migrated. */\n  folder?: string\n  tags?: string[]\n  alt?: string\n  description?: string\n  /** Auto-captured at upload (AGL-173); best-effort for images only. */\n  width?: number\n  height?: number\n  uploadedBy?: string\n  /**\n   * CDN delivery (AGL-175 / AGL-829): the stable, mediaId-keyed path\n   * (`/api/media/cdn/{scope}/{mediaId}`) served by both apps — location- and\n   * replace-independent (references never break; the route revalidates via\n   * the `contentHash` ETag). The same route also serves an immutable\n   * `…/{mediaId}/{hash}` form. `variants` are the WebP widths from upload.\n   */\n  cdnPath?: string\n  contentHash?: string\n  /**\n   * The FULL 64-hex sha256 of the served bytes (AGL-1614), written only by\n   * the routes that hash the bytes server-side. Additive beside\n   * {@link contentHash}, which is unchanged and stays the ETag and the\n   * immutable-URL segment.\n   *\n   * The distinction is load-bearing rather than tidy. `contentHash` is a\n   * 16-hex (64-bit) TRUNCATION of one of TWO digests — sha256 on\n   * `/api/media/upload` and `/api/media/replace`, GCS's md5 on\n   * `/api/media/upload-url` — which is fine for a cache validator (opaque,\n   * per-URL, self-consistent) and weak for anything that has to be a\n   * SECURITY key. Two md5 files with the same digest are hours of laptop\n   * compute to construct, and a truncation to 64 bits inherits that\n   * immediately; a quarantine keyed on such a value can be made to refuse an\n   * innocent asset. `contentSha256` has neither property.\n   *\n   * Absent, not null, when the server never held the bytes: the signed-upload\n   * route streams client → bucket and only downloads them back for an SVG\n   * sanitization pass, so that is the one case there where it is written.\n   * Absent means \"no strong key for these bytes\", and every consumer already\n   * degrades to `contentHash` and then to the per-asset key.\n   */\n  contentSha256?: string\n  variants?: number[]\n  /**\n   * Why an eligible asset has no {@link variants}, when generation was\n   * attempted and did not complete (AGL-1468).\n   *\n   * Written by every upload route and by `/api/media/replace`, and declared\n   * here late: it has been on production documents since AGL-1468 and was\n   * missing from this interface, so every reader either cast or guessed.\n   * Absent is the common, correct case — an SVG, a document, a source\n   * already narrower than 320px — and must never look like a fault.\n   */\n  variantsError?: string\n  /**\n   * The Cloud Storage object path (`{hosts|orgs}/{id}/media/{folders…}/{id}`).\n   * Written at upload, rewritten by a folder move, and read back by\n   * `serveMediaCdn` — which honors it ONLY inside this scope's media prefix,\n   * because it is client-influenced data on an admin-SDK bucket read\n   * (AGL-1881). Legacy assets have none and fall back to the flat layout.\n   */\n  storagePath?: string\n  /** Constructs `sanitizeSvgBuffer` removed (AGL-1474). Absent when clean. */\n  svgSanitized?: string[]\n  /** Uid of whoever last replaced the bytes (`/api/media/replace`). */\n  replacedBy?: string\n  /**\n   * What the uploader's browser measured about a VIDEO (AGL-2742).\n   *\n   * Client-reported and bounded by `normalizeVideoMetadata` before it lands,\n   * which is why it does not widen {@link width}/{@link height}: those are\n   * read from the bytes by the server and carry a stronger claim. A reader\n   * that folds the two together loses the ability to tell which it has.\n   *\n   * All three numbers or none — a `VideoObject` emitting a `duration` with\n   * no `width` is worse than one emitting neither.\n   */\n  video?: MediaVideoMetadata\n  /**\n   * The generated poster still for a video (AGL-2742), served by the CDN as\n   * `?poster=1` and — because it genuinely is an `image/webp` — under the\n   * shared edge policy rather than the origin-only one video takes.\n   *\n   * `variants` here are poster widths, generated by the same `sharp` pass\n   * that produces an image's, at `{storagePath}__poster__w{n}.webp`.\n   */\n  poster?: { width: number; height: number; variants: number[] }\n  /**\n   * Why a video has no {@link poster}: the browser could not decode it,\n   * would not paint a frame, or the encoder refused the bytes it sent.\n   * Absent on every video that has one, and on every non-video.\n   */\n  posterError?: string\n  /**\n   * Compressed delivery copies of a video (AGL-2745), in the order a\n   * renderer should emit `<source>` elements — most efficient codec first,\n   * because a browser takes the first it can decode.\n   *\n   * Produced out of band by `tools/scripts/generate-video-renditions.mjs`\n   * rather than at upload: there is no decoder in either upload runtime, and\n   * a hosted transcoder is a recurring bill this platform's budget does not\n   * carry. Absent means the master is the only copy, which is what every\n   * video served before this shipped.\n   */\n  videoRenditions?: MediaVideoRendition[]\n  /**\n   * User-defined key/value metadata (AGL-822), mirrored onto the Storage\n   * object's `customMetadata` by `/api/media/folders` (action\n   * `custom-metadata`); this doc copy is the source of truth for display.\n   */\n  customMetadata?: Record<string, string>\n  /**\n   * Which sites may see this asset (AGL-1037); absent = org-wide until the\n   * AGL-1040 backfill stamps it. Only meaningful on the org-scoped library\n   * (`orgs/{orgId}/media`) — a host's own library is private already.\n   */\n  visibleTo?: ScopeToken[]\n  /**\n   * Not fetchable without a signature (AGL-1051). **Orthogonal to\n   * `visibleTo`**, and the distinction is the whole point:\n   *\n   * - `visibleTo` answers *which sites may USE this asset* — a discovery\n   *   and authoring control. An asset restricted to one site is still\n   *   served to anyone who has its URL, because that site's pages are\n   *   public and the CDN that serves them is unauthenticated.\n   * - `private` answers *may the public FETCH these bytes at all*.\n   *\n   * A private asset carries no {@link cdnPath}, is refused by the pickers\n   * that place media into page content, and is reachable only through a\n   * short-lived signed URL minted for an authorized caller. Use it for\n   * things that are not web assets — a signed contract, unreleased\n   * artwork, an embargoed release — never for \"this image is only on one\n   * site\", which is what `visibleTo` is for.\n   */\n  private?: boolean\n  createdAt?: ITimestamp\n  updatedAt?: ITimestamp\n  deletedAt?: ITimestamp\n}\n\n/**\n * Media folder doc (AGL-171): `hosts/{hostId}/mediaFolders/{folderId}`.\n * Hierarchy/validation helpers live in `app-utils/media-folders`.\n */\nexport interface AglynHostMediaFolder {\n  $id: string\n  name: string\n  /** Parent folder id; null = root. Depth capped at 5 (see app-utils). */\n  parentId?: string | null\n  order?: number\n  /**\n   * Which sites may see this folder (AGL-1037). Assets carry their own\n   * scope — a folder's is applied to them by an explicit write-time\n   * cascade (AGL-1042), never inherited at read time.\n   */\n  visibleTo?: ScopeToken[]\n  createdAt?: ITimestamp\n}\n\n/**\n * Pending scheduled publication (AGL-61): when `publishAt` passes, the\n * parent doc's `versionId` pointer moves to `versionId`. Applied lazily by\n * the tenant's ISR revalidation (no dedicated cron needed).\n */\nexport interface PublishSchedule {\n  /** Version to make live; unused for `action: 'unpublish'` (AGL-113). */\n  versionId?: VersionUid\n  /**\n   * What happens at `publishAt` (AGL-113): `publish` (default) flips the\n   * live version pointer; `unpublish` removes the screen's routing-map\n   * entry so its path 404s after the next revalidate.\n   */\n  action?: 'publish' | 'unpublish'\n  publishAt: ITimestamp\n  /**\n   * `skipped-unentitled` is a terminal refusal (AGL-1185): the schedule came\n   * due on a plan without `scheduledPublishing`, so the executor declined it\n   * and will not reconsider.\n   *\n   * It exists because leaving it `pending` meant the refusal was not recorded\n   * anywhere — the schedule stayed due forever, and the moment the org upgraded\n   * to Business the next beat published it. Content someone scheduled and\n   * forgot, months later, surfacing during an upgrade. Recording the refusal is\n   * what makes it stop being due.\n   *\n   * Every reader tests `=== 'pending'`, so adding a member here degrades\n   * correctly rather than needing each one updated — checked, not assumed.\n   *\n   * `skipped-unroutable` is the second terminal refusal (AGL-1589): the\n   * publish came due on a screen with no live route and no address the\n   * executor could give it — no slug on the screen or one of its ancestors,\n   * an address another screen already holds, or an email document, which has\n   * no URL at all. One value for the three because they share a remedy (fix\n   * the address in the console and schedule it again) and because a terminal\n   * state is a thing every reader has to reason about; the console names the\n   * causes in its message.\n   *\n   * It exists for the same reason as the value above: before AGL-1589 that\n   * publish reported `applied` while the page kept 404ing, which is a silent\n   * failure in the worst direction. A recorded refusal is the difference\n   * between a schedule that did not run and one that pretended it had.\n   */\n  status:\n    | 'pending'\n    | 'applied'\n    | 'canceled'\n    | 'skipped-unentitled'\n    | 'skipped-unroutable'\n  createdAt?: ITimestamp\n}\n\n/** Host-scoped document */\nexport interface AglynScreen extends AglynDocument {\n  $id: ScreenUid\n  hostId?: HostUid\n  parentId?: ScreenUid\n  slug?: ScreenSlug\n  /** Position among siblings (screens sharing `parentId`) in the screens list. */\n  order?: number\n  versionId?: VersionUid\n  publishSchedule?: PublishSchedule\n  /** Password protection (AGL-87): sha256 hex of the visitor password. */\n  protection?: { passwordHash?: string }\n  /** Language this screen is written in (AGL-164), e.g. 'en'. */\n  locale?: string\n  /** Translations of this screen: locale → screen id (AGL-164). */\n  localeVariants?: Record<string, ScreenUid>\n  status?: HostScreenStatus\n  createdAt?: ITimestamp\n  updatedAt?: ITimestamp\n  /**\n   * When the screen's route was last published (AGL: date-published). Stamped\n   * by `publishScreenRoute` and cleared on unpublish, so it is present only\n   * while the screen is reachable — distinct from `createdAt`.\n   */\n  publishedAt?: ITimestamp\n  deletedAt?: ITimestamp\n  displayName?: string\n  /**\n   * Normalized `displayName` for case-insensitive prefix search (AGL-835);\n   * see `nameSearchKey`. Stamped by the screen create/import write paths so\n   * the besigner switcher can query screens by name instead of loading the\n   * whole collection.\n   */\n  nameLower?: string\n  description?: string\n  seo?: {\n    title?: string\n    description?: string\n    breadcrumb?: string\n    /**\n     * This screen's social card image (AGL-1337), overriding the host\n     * default. Same storage contract as {@link AglynHost.seo.image}: a\n     * `media:` reference or URL, `''` meaning cleared — which is how a screen\n     * goes back to inheriting the site default.\n     */\n    image?: string\n    /**\n     * Copied from the media record at pick time, and the FALLBACK rather than\n     * the answer: a replace rewrites the asset's pair and cannot reach this\n     * copy, so the head prefers what the asset's document records when the\n     * page is composed (AGL-2850). See `resolveSocialImage`.\n     */\n    imageWidth?: number\n    imageHeight?: number\n    /**\n     * `og:image:alt` (AGL-2417) — what the card SHOWS, for the screen\n     * readers that announce a social preview. Defaulted from the chosen DAM\n     * asset's own alt at pick time and editable per surface; stored beside\n     * the reference so `resolveSocialImage` emits the description belonging\n     * to the image that actually won the precedence list.\n     *\n     * Blank is never stored: `og:image:alt=\"\"` asserts the image conveys\n     * nothing, which is not what an undescribed card means.\n     */\n    imageAlt?: string\n  }\n\n  // CONCEPT: Scheduling\n  schedule?: {\n    startAt?: ITimestamp\n    endAt?: ITimestamp\n    next?: VersionUid\n    previous?: VersionUid\n  }\n\n  // CONCEPT: Contextual visibility\n  visibility?: HostScreenVisibility\n\n  // NOTE (AGL-676): `owner` and `contributors` were declared here and NEVER\n  // read or written by anything — zero call sites across the whole repo.\n  // Removed rather than left dangling: a declared-but-unmaintained field is\n  // how the next person builds on something that was never real. Editor\n  // attribution lives in `hosts/{hostId}/activity`, which is actually\n  // written. If a contributor set is wanted later, add one that is kept up\n  // to date.\n\n  /** Shared layout this screen renders inside (see {@link AglynLayout}). */\n  layoutId?: LayoutUid\n}\n\n/**\n * Host-scoped document.\n * `N` lets higher layers narrow the node schema (e.g. the aglyn SDK\n * instantiates it with its richer `NodeSchema`).\n */\nexport interface AglynScreenVersion<N = AglynNodeSchema>\n  extends AglynDocument {\n  $id: VersionUid\n  hostId?: HostUid\n  screenId?: ScreenUid\n  createdAt?: ITimestamp\n  updatedAt?: ITimestamp\n  nodes?: Record<NodeId, N>\n  /**\n   * Shared layout THIS VERSION renders inside (see {@link AglynLayout}).\n   *\n   * Key-present wins over the screen document's {@link AglynScreen.layoutId}:\n   * a `LayoutUid` binds the version to that layout, an explicit `null` renders\n   * the version with no layout, and an absent key inherits the screen's\n   * binding. Per-version binding is what lets a scheduled version bring its\n   * own chrome live at publish time without reframing the currently served\n   * version. On layout versions ({@link AglynLayoutVersion}) this same key is\n   * instead the back-pointer to the owning layout document.\n   */\n  layoutId?: LayoutUid | null\n  /**\n   * This version's values for the properties of the layouts it renders inside\n   * (AGL-2893), stored beside the {@link layoutId} binding: layout id →\n   * property name → value, for every layout in the chain.\n   *\n   * Keyed by layout so that binding a different layout never hands this\n   * screen's values to a property of the same name there, and so that a\n   * layout nested inside another can be given values of its own. A property\n   * the screen leaves unset renders with its default. Read on screen versions\n   * only.\n   */\n  layoutPropValues?: Record<\n    LayoutUid,\n    Record<string, ReusableComponentPropValue>\n  >\n  /**\n   * This version's restyling of the layouts it renders inside (AGL-3286),\n   * stored beside {@link layoutPropValues}: layout id → that layout's own\n   * node id → an sx record merged over the element's styling for this page\n   * only. The layout's content stays the layout's, and every other screen\n   * using it is unaffected. A node id the layout no longer has is ignored.\n   * Read on screen versions only — see `layout-style-overrides.ts`.\n   */\n  layoutStyleOverrides?: Record<\n    LayoutUid,\n    Record<string, Record<string, unknown>>\n  >\n}\n\n/** Unique id of a host-level reusable component definition. */\nexport type ComponentDefUid = string\n\n/**\n * Attribute field kinds that hold no value of their own: they arrange other\n * fields (a sub-form, tabs, a wizard, a repeating field array), decorate one\n * (an input add-on), or only display or trigger something (plain text, a\n * button). A property is one value, so none of these is a property kind —\n * see `NON_VALUE_FIELD_KINDS` for the reason each is listed.\n */\nexport type NonValueFieldKind =\n  | FieldComponentType.BUTTON\n  | FieldComponentType.BUTTON_GROUP\n  | FieldComponentType.FIELD_ARRAY\n  | FieldComponentType.INPUT_ADDON_BUTTON_GROUP\n  | FieldComponentType.INPUT_ADDON_GROUP\n  | FieldComponentType.PLAIN_TEXT\n  | FieldComponentType.SUB_FORM\n  | FieldComponentType.TAB_ITEM\n  | FieldComponentType.TABS\n  | FieldComponentType.WIZARD\n\n/**\n * Attribute field kinds whose property kind was named before properties\n * covered every field kind, and keeps that stored name: a text field is\n * `text`, a textarea `richText`, a switch `boolean`, a dropdown `choice`, an\n * icon picker `icon` and a screen picker `href`.\n */\nexport type LegacyNamedFieldKind =\n  | FieldComponentType.TEXT_FIELD\n  | FieldComponentType.TEXTAREA\n  | FieldComponentType.SWITCH\n  | FieldComponentType.SELECT\n  | FieldComponentType.ICON_PICKER\n  | FieldComponentType.SCREEN_SELECT\n\n/**\n * Kind of a declared component or layout property (AGL-1247, AGL-2893): which\n * control edits it, in the Properties dialog and on every page that sets it,\n * and which fields it can be bound to.\n *\n * Derived from the attribute schema's own field kinds rather than listed\n * beside them. Every {@link FieldComponentType} that holds a value is a\n * property kind — under its own stored value (`color-picker`,\n * `css-dimension`, …), or under the name it already had\n * ({@link LegacyNamedFieldKind}). `number` and `image` are the two text-field\n * variants a coded component declares as `type: 'number'` or as a media\n * field. So a field kind added to the attribute schema is a property kind the\n * moment it exists, and `REUSABLE_PROP_KINDS` fails to compile until it says\n * how the kind is edited.\n *\n * These values are stored in component and layout documents. Never rename\n * one.\n */\nexport type ReusableComponentPropType =\n  | 'text'\n  | 'richText'\n  | 'image'\n  | 'href'\n  | 'number'\n  | 'boolean'\n  | 'choice'\n  | 'icon'\n  | `${Exclude<FieldComponentType, NonValueFieldKind | LegacyNamedFieldKind>}`\n\n/**\n * A property's value as it is stored: a default on the declaration, or a\n * page's own value in `propValues` / `layoutPropValues`.\n *\n * The shape follows the kind's control — a Yes / no stores a boolean, a\n * slider a number, a list of answers an array, an icon pick its id and path —\n * and text-shaped kinds store text. Defaults written before the kinds were\n * typed are text (`'true'`, `'28'`), which every reader accepts.\n */\nexport type ReusableComponentPropValue =\n  | string\n  | number\n  | boolean\n  | ReadonlyArray<string | number>\n  | ReusableComponentIcon\n\n/**\n * One rule of a property's `condition`: the attribute schema's condition\n * (data-driven-forms' `ConditionDefinition`), with `when` naming another\n * property of the same component or layout instead of an attribute.\n *\n * The operators are the schema's own — `is` (one value, or any of a list),\n * `notMatch` to negate `is` or `pattern`, `isEmpty`, `isNotEmpty`, `pattern`\n * with `flags`, and the four comparisons — and the rule is evaluated by\n * data-driven-forms' own parser, in the Attributes panel and at render. Only\n * the serializable part is here: a stored document cannot carry a function.\n */\nexport interface ReusableComponentPropRule {\n  /** The name of the property whose value decides. */\n  when: string\n  is?: string | number | boolean | ReadonlyArray<string | number | boolean>\n  notMatch?: boolean\n  isEmpty?: boolean\n  isNotEmpty?: boolean\n  pattern?: string\n  flags?: string\n  greaterThan?: number\n  greaterThanOrEqualTo?: number\n  lessThan?: number\n  lessThanOrEqualTo?: number\n}\n\n/**\n * When a property shows and applies: one rule, a list that must ALL hold, or\n * the schema's `and` / `or` / `not` over rules.\n */\nexport type ReusableComponentPropCondition =\n  | ReusableComponentPropRule\n  | { and: ReusableComponentPropCondition[] }\n  | { or: ReusableComponentPropCondition[] }\n  | { not: ReusableComponentPropCondition | ReusableComponentPropCondition[] }\n\n/**\n * One answer a `choice` prop offers (AGL-2871).\n *\n * Two halves because two people read it: the page author picks the `label`,\n * and the field inside the component receives the `value` — which is why a\n * dropdown bound to the prop needs values it offers itself.\n */\nexport interface ReusableComponentPropOption {\n  /** What a field bound to the prop receives. */\n  value: string\n  /** What the Attributes panel shows; falls back to `value`. */\n  label?: string\n}\n\n/**\n * A prop a reusable component declares (AGL-1247), so one definition can\n * render different content per instance instead of being copied per page.\n *\n * Inside the definition the author binds a node prop to it with the\n * existing token syntax — `{{prop.headline}}`, the same mechanism behind\n * `{{entry.*}}` and `{{host.*}}` — and `composeReusableComponentNodes`\n * substitutes each instance's own values as it grafts.\n */\nexport interface ReusableComponentProp {\n  /**\n   * Token name: `{{prop.<name>}}`. This is the STABLE key instances store\n   * their overrides under, so renaming one orphans every existing value —\n   * the editor must rename in place rather than remove-and-add.\n   */\n  name: string\n  type?: ReusableComponentPropType\n  /** Field label in the Attributes panel; falls back to `name`. */\n  label?: string\n  /**\n   * Help shown beside the property's field wherever a page sets it — the\n   * attribute schema's `description`.\n   */\n  description?: string\n  /**\n   * Rendered wherever an instance leaves this prop unset, and shown as the\n   * Attributes field's placeholder. One field serving both is deliberate:\n   * a component that renders its own sensible copy until overridden is the\n   * \"shows the placeholder from the component\" behaviour, and it means an\n   * unset prop can never collapse a section to empty on a live page.\n   */\n  defaultValue?: ReusableComponentPropValue\n  /**\n   * The answers a page picks from, in the order offered, for a kind whose\n   * control lists answers (`choice`, `radio`, `toggle-button`,\n   * `dual-list-select`, and a `checkbox` that is a list). A `defaultValue`\n   * names one of their values, or several for a kind that takes several.\n   */\n  options?: ReusableComponentPropOption[]\n  /**\n   * The kind's own settings, named by the kind's `settings` in\n   * `REUSABLE_PROP_KINDS`: a slider's range, whether a choice takes several\n   * answers, which theme scale a theme-scale field offers. They are the\n   * attribute field's own props, so a coded component's attribute and a\n   * property of the same kind are configured with the same words.\n   */\n  settings?: Record<string, string | number | boolean>\n  /**\n   * When the property shows and applies. While it does not hold, the field is\n   * hidden wherever a page sets it, and the property renders as one with no\n   * value and no default: text bound to it is empty, a Yes / no is a no, and\n   * a field bound to it keeps its own default.\n   */\n  condition?: ReusableComponentPropCondition | ReusableComponentPropCondition[]\n  /**\n   * `icon` only: the SVG path of the icon `defaultValue` names, stored beside\n   * the id when the default is picked, for the reason\n   * {@link ReusableComponentIcon} stores both — a published page never loads\n   * the icon catalog, so an id alone draws the empty Icon placeholder. An\n   * instance's own pick travels the same way, as a whole\n   * {@link ReusableComponentIcon} in its prop values.\n   */\n  defaultIconPath?: string\n}\n\n/**\n * A reusable component's chosen icon (AGL-1193), stood in for by the generic\n * package glyph when unset.\n *\n * Both halves are stored, for the reason AGL-1212 exists: the MDI catalog is\n * ~2.9 MB and only picker surfaces load it, so anything that had to resolve\n * `iconId` on a render surface got `DEFAULT_ICON` — a real path, so every\n * icon painted a confident \"help\" glyph. The id stays the source of truth;\n * `iconPath` is the denormalized copy that travels with the document.\n */\nexport interface ReusableComponentIcon {\n  iconId?: string\n  iconPath?: string\n}\n\n/**\n * Reusable component definition: a node subtree promoted from a screen,\n * inserted anywhere as an instance node (`componentId: 'reusableInstance'`,\n * `props.refId`) and grafted at render time (see\n * `composeReusableComponentNodes`). Host-scoped document at\n * `hosts/{hostId}/components/{componentId}`.\n */\nexport interface AglynHostComponent<N = AglynNodeSchema>\n  extends AglynDocument {\n  $id: ComponentDefUid\n  hostId?: HostUid\n  displayName?: string\n  description?: string\n  /**\n   * Icon shown wherever an instance of this component is represented in the\n   * besigner (AGL-1193) — the hierarchy row, the canvas badge, the element\n   * drawer. Absent on every component that predates the picker, which is\n   * why it is optional and never defaulted: unset means \"the package glyph\",\n   * not \"an icon we failed to read\".\n   */\n  icon?: ReusableComponentIcon\n  /**\n   * Definition tree root id within {@link AglynHostComponent.nodes}.\n   *\n   * `rootId` and `nodes` on THIS doc are the published snapshot — the copy\n   * the tenant runtime renders. `getComponents` reads every component in a\n   * single collection query on each page render, so they deliberately stay\n   * here rather than moving into the version docs below: relocating them\n   * would turn one query into N+1 on the hot path of every published site\n   * (AGL-679).\n   */\n  rootId?: NodeId\n  nodes?: Record<NodeId, N>\n  /**\n   * Declared props (AGL-1247), published alongside `rootId`/`nodes` and for\n   * the same reason: the tenant reads this doc, so a definition whose props\n   * stayed on the version doc would graft with every `{{prop.*}}` token\n   * unresolved on the live site.\n   */\n  props?: ReusableComponentProp[]\n  /**\n   * Working version pointer (AGL-679). Absent on components that predate\n   * the standalone editor — those still render from the fields above, and\n   * opening one creates version 1 from them.\n   */\n  versionId?: VersionUid\n  createdAt?: ITimestamp\n  updatedAt?: ITimestamp\n  deletedAt?: ITimestamp\n}\n\n/**\n * A reusable component's editing history (AGL-679), at\n * `hosts/{hostId}/components/{componentId}/versions/{versionId}`.\n *\n * Same shape as a screen version, with the component's `rootId` carried so\n * publishing is a copy of both fields onto the parent rather than a\n * reconstruction. Edits here are invisible to live sites until published —\n * the same mental model screens already have.\n */\nexport interface AglynHostComponentVersion<N = AglynNodeSchema>\n  extends AglynDocument {\n  $id: VersionUid\n  hostId?: HostUid\n  componentId?: ComponentDefUid\n  displayName?: string\n  rootId?: NodeId\n  nodes?: Record<NodeId, N>\n  /** Declared props being edited; published onto the parent (AGL-1247). */\n  props?: ReusableComponentProp[]\n  createdAt?: ITimestamp\n  updatedAt?: ITimestamp\n}\n\n/**\n * Shared layout: canvas chrome (appbar, footer, nav) designed once and\n * rendered around every bound screen. Host-scoped document at\n * `hosts/{hostId}/layouts/{layoutId}`.\n */\nexport interface AglynLayout extends AglynDocument {\n  $id: LayoutUid\n  hostId?: HostUid\n  /** Published version pointer; bound screens render this version. */\n  versionId?: VersionUid\n  publishSchedule?: PublishSchedule\n  versions?: Array<VersionUid>\n  displayName?: string\n  description?: string\n  /**\n   * Layout this layout renders inside (AGL-703) — the same relationship\n   * `AglynScreen.layoutId` expresses, one level up, so shared chrome can\n   * sit outside a more specific frame. Must not be this layout, or any\n   * layout already below it; see `canNestLayout`.\n   */\n  layoutId?: LayoutUid\n  // `contributors` removed here too — see the note on AglynScreen (AGL-676).\n  createdAt?: ITimestamp\n  updatedAt?: ITimestamp\n}\n\n/**\n * Shared layout version. Node map has the same shape as a screen version\n * (including compression at rest) plus a LayoutSlot node marking where the\n * bound screen's content is grafted. Hosted at\n * `hosts/{hostId}/layouts/{layoutId}/versions/{versionId}`.\n */\nexport interface AglynLayoutVersion<N = AglynNodeSchema>\n  extends AglynScreenVersion<N> {\n  layoutId?: LayoutUid\n  hostId?: HostUid\n  /**\n   * The properties this layout declares (AGL-2893), each set by the screens\n   * that render inside it. On the version rather than the layout document,\n   * beside the nodes that bind them: a layout is served by its version\n   * pointer, so a version's properties go live with its tree.\n   */\n  props?: ReusableComponentProp[]\n}\n\nexport type TemplateUid = string\n\n/** What a template can be instantiated as. */\nexport type TemplateKind = 'page' | 'component' | 'layout'\n\n/**\n * A named substitution offered when the template is instantiated. Values are\n * applied with `resolveNamedTokens` — the same `{{name}}` mechanism that\n * renders collection entry templates — so a template author marks copy as\n * `{{productName}}` and is prompted for it on use.\n */\nexport interface TemplatePlaceholder {\n  /** Token name as it appears in the nodes, without the braces. */\n  name: string\n  /** Prompt label shown when instantiating. */\n  label?: string\n  defaultValue?: string\n}\n\n/**\n * Where a template came from.\n *\n * SERVER-MANAGED. A client that could write this would be able to stamp\n * `marketplace` provenance on something it authored, and the library shows\n * this to the user as a trust signal.\n */\nexport interface TemplateSource {\n  type: 'authored' | 'marketplace' | 'starter'\n  /** Marketplace listing this was installed from. */\n  listingId?: string\n  /** Listing version installed — compared against `latestVersion` to\n   *  surface \"update available\" without storing anything extra. */\n  version?: number | string\n  /** First-party starter id from `starter-templates.ts`. */\n  starterId?: string\n  /**\n   * Bundle-level identity for a seeded starter (AGL-687). A multi-page\n   * starter seeds one page template per screen, exactly as a marketplace\n   * install does; these carry the name/description/order of the bundle the\n   * screens belong to so the gallery can present them as the single starter\n   * they were authored as, without a second, code-side template source.\n   */\n  starterName?: string\n  starterDescription?: string\n  /** Position within the starter; fixes the order pages are created in. */\n  starterOrder?: number\n}\n\n/**\n * Reusable starting point for a page, component or layout (AGL-666).\n * Host-scoped document at `hosts/{hostId}/templates/{templateId}`.\n *\n * Distinct from the things it produces: a template is inert until\n * instantiated, so marketplace downloads land here rather than becoming live\n * pages. `nodes` carries the same node-map shape screens, components and\n * layouts already use, which is what lets one collection serve all three\n * kinds.\n */\nexport interface AglynTemplate<N = AglynNodeSchema> extends AglynDocument {\n  $id: TemplateUid\n  hostId?: HostUid\n  kind?: TemplateKind\n  displayName?: string\n  description?: string\n  category?: string\n  nodes?: Record<NodeId, N>\n  /** Definition tree root — `component` kind, mirroring AglynHostComponent. */\n  rootId?: NodeId\n  /**\n   * The properties a `component` or `layout` template's tree binds to\n   * (AGL-2932), carried so what is made from it declares them — without them\n   * every `{{prop.*}}` in the tree renders raw.\n   */\n  props?: ReusableComponentProp[]\n  /** Suggested slug — `page` kind; de-conflicted against the host on use. */\n  slug?: string\n  /** Mirrors AglynScreen.seo — carried through to the created page. */\n  seo?: {\n    title?: string\n    description?: string\n    breadcrumb?: string\n    image?: string\n    imageWidth?: number\n    imageHeight?: number\n    /** Mirrors `AglynScreen.seo.imageAlt` (AGL-2417). */\n    imageAlt?: string\n  }\n  placeholders?: Array<TemplatePlaceholder>\n  /**\n   * Theme the template was designed against, carried over from a site\n   * template's snapshot. Held rather than applied: applying a theme changes\n   * the whole site's appearance, which is exactly the kind of instant,\n   * site-wide change installing is not allowed to make (AGL-669).\n   */\n  theme?: Record<string, unknown>\n  source?: TemplateSource\n  createdAt?: ITimestamp\n  updatedAt?: ITimestamp\n  deletedAt?: ITimestamp\n}\n\nexport type RedirectUid = string\n\n/** CONCEPT: Host redirects. Host-scoped document */\nexport interface AglynRedirect extends AglynDocument {\n  $id: RedirectUid\n  hostId?: HostUid\n  sourcePath?: HostPath\n  sourceScreen?: ScreenUid\n  destinationPath?: HostPath\n  destinationScreen?: ScreenUid\n  statusCode?: HttpStatusCode\n  params?: HostRedirectParams\n  flags?: {\n    regex?: true\n    ignoreSlash?: true\n    ignoreCase?: true\n  }\n  hits?: number\n  lastAccess?: ITimestamp\n  description?: string\n}\n"],"names":["HostScreenStatus","HostScreenVisibility","HostViewType","HostViewFormat","HostEntityType","HostRedirectParams","HOST_CLIENT_WRITABLE_FIELDS","displayName","logoUrl","seo","layouts","redirects","notFoundScreenId","errorScreens","maintenance","locales","defaultLocale","timeZone","theme","themeOverride","announcementBar","popup","business","analytics","consent","createdAt","updatedAt","HOST_UNPERSISTED_FIELDS","$id","HOST_ERROR_SCREEN_SLOTS"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GA6BD,OAAO,IAAA,AAAKA,0CAAAA;;;;;;;WAAAA;MAOX;AAED,OAAO,IAAA,AAAKC,8CAAAA;;;;;;;WAAAA;MAOX;AAED,OAAO,IAAA,AAAKC,sCAAAA;0CACD;0CACA;IACT,4EAA4E,wCACpE;WAJEA;MAKX;AAED,OAAO,IAAA,AAAKC,wCAAAA;kDACG;oDACE;WAFLA;MAGX;AAED,OAAO,IAAA,AAAKC,wCAAAA;oDACK;8CACN;WAFCA;MAGX;AAED,OAAO,IAAA,AAAKC,4CAAAA;;uDAEA;qDACF;WAHEA;MAIX;AAueD;;;;;;;;;;;;;CAaC,GACD,OAAO,MAAMC,8BAAgE;IAC3EC,aACE,2EACA;IACFC,SACE,wEACA;IACFC,KACE,yEACA,0EACA;IACF,uEAAuE;IACvE,sEAAsE;IACtE,0EAA0E;IAC1E,mEAAmE;IACnE,0EAA0E;IAC1E,4EAA4E;IAC5E,4EAA4E;IAC5E,2EAA2E;IAC3E,qCAAqC;IACrCC,SACE,8EACA,4EACA,4EACA,8EACA;IACFC,WACE,0EACA;IACFC,kBACE,2EACA;IACFC,cACE,qEACA;IACFC,aACE,sEACA,6EACA;IACFC,SACE,4EACA;IACFC,eAAe;IACfC,UACE,oEACA,0EACA,2EACA,0EACA,2EACA,yEACA,0EACA;IACFC,OACE,2EACA;IACFC,eACE,wEACA,oEACA,6EACA;IACFC,iBACE,0EACA,2EACA,4EACA;IACFC,OAAO;IACPC,UACE,sEACA,2EACA,0EACA;IACFC,WACE,2EACA,0EACA,kEACA;IACFC,SACE,qEACA,yEACA,4EACA;IACFC,WACE,sEACA;IACFC,WACE,2EACA;AACJ,EAAC;AAED;;CAEC,GACD,OAAO,MAAMC,0BAA4D;IACvEC,KAAK;AACP,EAAC;AAsBD;;;;;;;;;;;;;CAaC,GACD,OAAO,MAAMC,0BAA0B;IACrC;IACA;IACA;IACA;CACD,CAAS"}
+{"version":3,"sources":["../../../../../../../libs/aglyn/src/lib/foundation/definitions/platform.types.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport type { HttpStatusCode } from '@aglyn/shared-data-enums'\nimport type { HostTheme } from '@aglyn/shared-data-types'\nimport type { ITimestamp } from '@aglyn/shared-util-timestamp'\nimport type {\n  AglynNodeSchema,\n  FieldComponentType,\n  NodeId,\n} from './components.types'\n// Type-only, so this stays a definitions file with no runtime edge into\n// `app-utils`: the two video shapes are DEFINED beside the code that\n// validates them (`normalizeVideoMetadata`, `parseMediaRendition`) so a\n// document field and its validator can never describe different things.\nimport type { MediaVideoMetadata } from '../../app-utils/media-metadata'\nimport type { MediaVideoRendition } from '../../app-utils/media-ref'\n\n/**\n * Platform-side definitions: documents, hosts, screens, media, users.\n * The ORG BILLING family (`AglynOrgBilling` and the Org* plan/entitlement\n * vocabulary) lives in `org-billing.types.ts` — see the docs-site glossary\n * for the org/workspace/tenant/host naming convention. (This file was\n * `workspace.types.ts`; renamed in AGL-443 because nothing in it is the\n * workspace/org entity.)\n */\nexport interface AglynDocument {\n  [field: string]: any\n}\n\nexport enum HostScreenStatus {\n  UNPUBLISHED = 0x1 << 0x1,\n  PUBLISHED = 0x1 << 0x2,\n  SCHEDULED_TO_PUBLISH_UNPUBLISHED = UNPUBLISHED | (0x1 << 0x3),\n  SCHEDULED_TO_UNPUBLISH_PUBLISHED = PUBLISHED | (0x1 << 0x4),\n  SCHEDULED_TO_UPDATE_PUBLISHED = PUBLISHED | (0x1 << 0x5),\n  SCHEDULED_TO_REVERT_UPDATE_PUBLISHED = PUBLISHED | (0x1 << 0x6),\n}\n\nexport enum HostScreenVisibility {\n  PUBLIC = 0x1 << 0x1,\n  UNLISTED = PUBLIC | (0x1 << 0x2),\n  PRIVATE = 0x1 << 0x3,\n  PASSWORD = PRIVATE | (0x1 << 0x4),\n  AUTHENTICATED = PRIVATE | (0x1 << 0x5),\n  AUTHORIZED = AUTHENTICATED | (0x1 << 0x6),\n}\n\nexport enum HostViewType {\n  SCREEN = 0x1,\n  LAYOUT = 0x2,\n  /** A besigner-designed email document (screen with kind 'email', AGL-395). */\n  EMAIL = 0x4,\n}\n\nexport enum HostViewFormat {\n  NORMALIZED = 0x1,\n  DENORMALIZED = 0x2,\n}\n\nexport enum HostEntityType {\n  ORGANIZATION = 0x1,\n  PERSON = 0x2,\n}\n\nexport enum HostRedirectParams {\n  IGNORE,\n  FORWARD = 0x1,\n  MATCH = 0x2,\n}\n\n/** Org document id (`orgs/{orgId}`). Formerly TenantUid (AGL-444). */\nexport type OrgUid = string\n\nexport type UserUid = string\n\nexport interface AglynUser extends AglynDocument {\n  $id: UserUid\n  admin?: boolean\n  email?: string\n}\n\n/**\n * Site-wide announcement bar config on the host doc (AGL-195). Text may\n * contain binding tokens; the tenant render resolves them server-side.\n */\nexport interface HostAnnouncementBar {\n  enabled?: boolean\n  text?: string\n  /** Optional link the whole bar navigates to. */\n  href?: string\n  backgroundColor?: string\n  textColor?: string\n  /** Visitors may hide the bar; hidden state re-arms when text changes. */\n  dismissible?: boolean\n}\n\n/**\n * Promotional popup config on the host doc (AGL-196); one per host,\n * marketingOverlays-gated. Body text may contain binding tokens; the\n * tenant render resolves them server-side.\n */\nexport interface HostPopup {\n  enabled?: boolean\n  headline?: string\n  body?: string\n  /** Media-library image URL shown above the copy. */\n  imageUrl?: string\n  /**\n   * Alt text for {@link imageUrl} (AGL-1896). Defaults from the chosen DAM\n   * asset's own alt when the author picks through \"Browse media\"; empty\n   * still renders `alt=\"\"`, which is correct for a decorative banner.\n   */\n  imageAlt?: string\n  ctaLabel?: string\n  ctaHref?: string\n  /** Render an email-capture field posting into the forms pipeline. */\n  collectEmail?: boolean\n  /** How the popup opens. */\n  trigger?: 'delay' | 'scroll' | 'exit'\n  /** Seconds (delay trigger) or percent 0-100 (scroll trigger). */\n  triggerValue?: number\n  /**\n   * Re-show after this many days once dismissed (localStorage).\n   *\n   * Ignored when {@link oncePerSession} is set — the two are alternative\n   * answers to the same question, and honouring both would mean a popup\n   * suppressed for the session AND for seven days after it.\n   */\n  frequencyDays?: number\n  /**\n   * Show at most once per browser SESSION (AGL-2174).\n   *\n   * `/product/marketing` sells \"per-session frequency caps\" in as many\n   * words, and the only cap the product had was day-based — a visitor who\n   * dismissed a popup did not see it again for a week, which is a\n   * different promise. Backed by `sessionStorage`, which is exactly the\n   * lifetime the copy describes: it clears when the tab closes.\n   */\n  oncePerSession?: boolean\n  /** Optional showing window (epoch millis; simple to serialize). */\n  startAtMs?: number\n  endAtMs?: number\n}\n\nexport type ProjectUid = string\nexport type ProjectNumber = number\n\nexport type HostUid = string\nexport type HostPath = string\nexport type HostMediaUid = string\n\n/**\n * Persisted MUI theme customization for a host's published site.\n * Canonical shape lives in `@aglyn/shared-data-types` so UI-scope libs can\n * consume it without depending on this framework lib.\n */\nexport type AglynHostTheme = HostTheme\n\n/** Host-scoped document */\nexport interface AglynHost extends AglynDocument {\n  $id: HostUid\n  /** Owning org (AGL-233); mirrored into `hostIndex/{hostId}`. */\n  orgId?: OrgUid\n  /** Membership projection from the org (AGL-233): uid → role tier. */\n  memberRoles?: Record<UserUid, string>\n  subdomain?: string\n  cname?: string\n  /** Site-wide announcement bar (AGL-195); marketingOverlays-gated. */\n  announcementBar?: HostAnnouncementBar\n  /** Promotional popup (AGL-196); marketingOverlays-gated. */\n  popup?: HostPopup\n  displayName?: string\n  /**\n   * Site logo URL (AGL-594): the host's own brand mark, shown by the\n   * tenant's navigation loader (and future chrome). Distinct from\n   * `seo.entity.logo`, which is publisher-semantic JSON-LD.\n   */\n  logoUrl?: string\n  seo?: {\n    title?: string\n    description?: string\n    separator?: string\n    favicon?: string\n    /**\n     * The square mark a visitor installs to their home screen — the `icons`\n     * entry of `/manifest.webmanifest`.\n     *\n     * Distinct from both of its neighbours, and the distinction is what the\n     * field exists for. {@link favicon} is drawn at 16–32px in a tab, so it is\n     * a glyph rather than artwork. `logoUrl` is the site's LOCKUP — a wordmark\n     * on most sites, which is a wide rectangle, and the manifest fell back to\n     * it for want of anything else: an installer that trusted a declared size\n     * painted a stretched or letterboxed tile on somebody's home screen.\n     *\n     * A `media:` reference or a plain URL, absolutized before it is written\n     * into the manifest because nothing fetches an install icon from the page\n     * that linked it. Unset falls back to `logoUrl`, which is what every site\n     * installs with today; a site with neither gets no `icons` array at all,\n     * so the browser uses a screenshot rather than a broken tile.\n     */\n    appIcon?: string\n    /**\n     * Site-wide default social card image (AGL-1337) — used by every page\n     * that sets none of its own. A `media:` reference (what the picker\n     * writes) or a raw URL; resolved and made absolute by\n     * `resolveSocialImage`, never emitted as stored.\n     *\n     * `''` is a CLEARED field, written directly to Firestore by the picker\n     * card rather than through the attributes form stack, which maps `''` to\n     * `undefined` and would leave a default nobody could remove (AGL-1191).\n     */\n    image?: string\n    /**\n     * Copied from the media record at pick time, and the FALLBACK rather than\n     * the answer: a replace rewrites the asset's pair and cannot reach this\n     * copy, so the head prefers what the asset's document records when the\n     * page is composed (AGL-2850). See `resolveSocialImage`.\n     */\n    imageWidth?: number\n    imageHeight?: number\n    /**\n     * `og:image:alt` (AGL-2417) — what the card SHOWS, for the screen\n     * readers that announce a social preview. Defaulted from the chosen DAM\n     * asset's own alt at pick time and editable per surface; stored beside\n     * the reference so `resolveSocialImage` emits the description belonging\n     * to the image that actually won the precedence list.\n     *\n     * Blank is never stored: `og:image:alt=\"\"` asserts the image conveys\n     * nothing, which is not what an undescribed card means.\n     */\n    imageAlt?: string\n    /**\n     * Site-wide \"discourage search engines\" (AGL-1263): `robots.txt` refuses\n     * everything, the sitemap goes empty, and every page carries `noindex`.\n     * The staged-launch control — a site that is live but not ready to be\n     * found, which until now could only be approximated by setting each\n     * screen to {@link HostScreenVisibility.UNLISTED} one at a time.\n     *\n     * Absent means INDEX, and must keep meaning that. Reading a missing field\n     * as \"hide\" would let a schema slip de-index every customer at once.\n     */\n    discourageSearchEngines?: boolean\n    entity?: {\n      type?: HostEntityType\n      name?: string\n      logo?: string\n      /**\n       * What the publisher IS, in a sentence — `Organization.description`\n       * (AGL-2716).\n       *\n       * Distinct from {@link AglynHost.seo.description}, which is the meta\n       * description of the site's home page: one describes a business, the\n       * other describes a document, and a site whose home page is a product\n       * launch should not be telling an AI assistant that the company is a\n       * product launch. Unset falls back to the site description, because a\n       * fallback that is approximately right beats an entity with no\n       * description at all — which is what every site published before this\n       * field existed.\n       */\n      description?: string\n      /**\n       * The publisher's own canonical address, when it is not this site —\n       * a brand site for a company whose main presence is elsewhere. Unset\n       * means this site's origin, which is the common case.\n       */\n      url?: string\n      /**\n       * Profiles that identify the SAME entity — `schema.org/sameAs`. The\n       * company's LinkedIn, its Crunchbase entry, its Wikipedia article. Not\n       * a link list: a page that merely mentions the entity is not the\n       * entity, and listing one teaches a consumer the wrong identity.\n       */\n      sameAs?: string[]\n      /**\n       * How to reach a person — `Organization.contactPoint`.\n       *\n       * Split into fields rather than stored as a `contactPoint` object\n       * because the console collects them as three form controls, and a\n       * nested object in a settings document is a shape a partial write can\n       * blank. Assembled at serialization; see `siteEntityJsonLd`.\n       */\n      email?: string\n      telephone?: string\n      /**\n       * Which kind of enquiry that contact answers — `customer support`,\n       * `sales`, `technical support`. Free text, because `schema.org` defines\n       * the property as text rather than an enumeration.\n       */\n      contactType?: string\n      /**\n       * Postal address — `Organization.address`, a `PostalAddress`.\n       *\n       * Every field optional and every field omitted when blank: a partial\n       * address is still a real answer to \"where are they\", while a\n       * `PostalAddress` carrying empty strings is a claim that the street is\n       * the empty string.\n       */\n      address?: {\n        streetAddress?: string\n        addressLocality?: string\n        addressRegion?: string\n        postalCode?: string\n        /** ISO 3166-1 alpha-2, or a country name. */\n        addressCountry?: string\n      }\n    }\n    /**\n     * Guidance for AI agents, published in `/llms.txt` (AGL-2716).\n     *\n     * Its own key rather than a field on `entity`, because it is about the\n     * SITE's usefulness rather than about who publishes it — and because the\n     * two are edited by different people at different times.\n     */\n    agent?: {\n      /**\n       * When an agent should reach for this site: the jobs it is the right\n       * source for, in the author's own words.\n       *\n       * Absent is not a gap. `buildLlmsTxt` derives a when-to-use section\n       * from what the site demonstrably publishes, so a site whose author\n       * writes nothing here still ships checkable guidance; this is the place\n       * to say the things that cannot be derived.\n       */\n      whenToUse?: string\n      /** How an agent should call the site — endpoints, etiquette, limits. */\n      howToUse?: string\n    }\n  }\n  /**\n   * Customer-configured third-party analytics (AGL-138/661). Long written by\n   * the console and read by the tenant through `any` casts; declared as of\n   * AGL-1498 so the write-deny guard sees it through the type rather than\n   * not at all. The id is format-checked (`GA_MEASUREMENT_ID_PATTERN`)\n   * before it reaches the inline script, and its LOADING is consent-gated\n   * by `visitor-consent.ts` — see `consent` below.\n   */\n  analytics?: {\n    gaMeasurementId?: string\n    /**\n     * Google Tag Manager container (AGL-2486), `GTM-XXXXXXX`.\n     *\n     * Declared here for the reason the `consent` comment below spells out at\n     * length: a field the console persists and the tenant reads, but that no\n     * type knows about, is how a whole-object write silently drops a sibling.\n     *\n     * Format-checked by `GTM_CONTAINER_ID_PATTERN` before it reaches an\n     * inline script, and consent-gated exactly as `gaMeasurementId` is — a\n     * container counts as a gated feature in `consentGatedCategories`, so a\n     * site running only a container still gets the banner. It has to: a\n     * container is the likeliest thing on a page to carry advertising tags,\n     * and advertising is opt-in worldwide.\n     */\n    gtmContainerId?: string\n    /**\n     * Advertising pixels, vendor id → that vendor's account id (AGL-2486).\n     *\n     * Declared here for exactly the reason the `gtmContainerId` comment above\n     * gives, and it is the field that proved the point: the console persisted\n     * it and the tenant read it through `advertising-tags.ts`, while no type\n     * knew about it. `aglyn-marketing` carries a live Meta pixel in it today,\n     * and a whole-object write to `analytics` would have dropped it silently.\n     *\n     * The vendor descriptors — which script each id loads, and therefore which\n     * hosts the CSP has to admit — live in `advertising-tags.ts`. An id here\n     * for a vendor with no descriptor loads nothing.\n     */\n    adTags?: Record<string, string> | null\n  }\n  /**\n   * Visitor consent tool (AGL-1498). The tool is ACTIVE when this is absent\n   * — but only ever on sites that use a consent-gated feature (today:\n   * `analytics.gaMeasurementId`); with none configured no consent UI exists\n   * and this map decides nothing. `disabled: true` is the host's opt-out\n   * (they run their own consent solution, and gated features load ungated).\n   * `mode` is the host's posture: `'geo'` (geo-conditional: implied consent\n   * with an always-available opt-out in opt-out regions, a prior-consent\n   * banner in EU/EEA/UK and unknown regions) or `'strict'` (the banner for\n   * everyone). Absent `mode` behaves as `'geo'`. Absent-means-active is the\n   * only safe default for the tool itself: a schema slip must fail toward\n   * asking, never toward silently tracking. See `visitor-consent.ts`.\n   *\n   * `advertising` (AGL-1649) is the host's opt-in to ASKING a second\n   * question. It was persisted by the console and read by the tenant for four\n   * days without being declared here — the same undeclared-field shape the\n   * `analytics` comment above says was fixed for AGL-1498, on the very key\n   * this issue exists to deliver. The cost is not typos: `consent` is an\n   * inline object type, so a whole-object write built against a type missing\n   * the key drops a host's advertising opt-in and TypeScript agrees with the\n   * drop. `consent-host-schema-coverage.spec.ts` now fails the build on any\n   * `consent.*` key that is written or read but not declared.\n   */\n  consent?: {\n    disabled?: boolean\n    mode?: 'geo' | 'strict'\n    /**\n     * Host opt-in to asking visitors about advertising storage (AGL-1649).\n     * PERSISTED NAME; absent or `false` — the state of every site that\n     * exists — means the visitor is asked about analytics only and\n     * `ad_storage`, `ad_user_data` and `ad_personalization` stay denied\n     * where AGL-1622 put them.\n     *\n     * `true` does not grant anything by itself — it makes the category\n     * REACHABLE. It adds a second, separate question to the banner and the\n     * privacy-choices panel, and where advertising then starts follows the\n     * visitor's region: asked-first in the prior-consent set (the EU 27, the\n     * EEA/EFTA three, the UK, Gibraltar, the outermost regions, and any\n     * visitor whose region cannot be determined), running from the first\n     * visit everywhere else on the same implied basis analytics uses. A\n     * refusal — declined, opted out, or GPC — denies it everywhere.\n     *\n     * See `advertisingGrantedByStatus`; this sentence and that function are\n     * locked together by `consent-advertising-copy-drift.spec.ts`, and the\n     * published Cookie Policy moves before either of them.\n     *\n     * Read only through `hostAsksAboutAdvertising`, which also requires a\n     * configured measurement id and tests `=== true`, so a truthy string out\n     * of a hand-edited document cannot turn a consent category on.\n     */\n    advertising?: boolean\n  }\n  screens?: Record<ScreenUid, ScreenSlug>\n  /** Screen rendered (noindex) for unmatched paths (AGL-87). */\n  notFoundScreenId?: ScreenUid\n  /**\n   * Designable error screens by status (AGL-131). `notFound` supersedes\n   * `notFoundScreenId` (kept in sync for back-compat).\n   */\n  errorScreens?: HostErrorScreens\n  /**\n   * Designable membership screens (AGL-553): which besigner-built screen\n   * renders at `/signin`, `/signup` and `/recover`. An empty slot falls back\n   * to the built-in form.\n   *\n   * ADMIN TIER, not authoring — the one thing that separates it from its\n   * sibling `errorScreens`, which is a binding to screens the editor already\n   * controls and serves only their own visitors. These three addresses are\n   * where a site's members type their password, so the field decides what a\n   * sign-in page IS. `enabledPlugins` is denied to an editor one tier down\n   * for deciding merely whether those addresses EXIST; the field that\n   * decides what they render cannot sit in a weaker tier than the field that\n   * opens them.\n   *\n   * It is also a live-content surface that does not go through the routing\n   * map: the tenant loader resolves the slot straight to a screen document,\n   * and `screenClaimsToBeAPage` asks only whether that screen is deleted. So\n   * `screens` being frozen for an `author` does not reach it, and an author\n   * — the role sold as \"edit content but not publish\" — could otherwise put\n   * a screen on the site's sign-in address without publishing anything.\n   */\n  authScreens?: HostAuthScreens\n  /** Maintenance mode (AGL-131): every path renders the 503 screen. */\n  maintenance?: boolean\n  /**\n   * STAFF host takedown (AGL-1501) — the host scope of the panic button,\n   * for an infected or abusive site. The same field family as the org's\n   * AGL-202 suspension: while `suspendedAt` is set (and `suspendedUntilMs`\n   * has not passed) the site serves the lockdown notice instead of content.\n   * Deliberately separate from `maintenance` above, which is the CUSTOMER'S\n   * own switch — a takedown the site's editors could clear from the client\n   * SDK would not be a takedown, so all four keys are client-denied in the\n   * rules and written only by /api/admin/lockdown. `suspendedMessage` is\n   * visitor-facing; timestamps are plain epoch ms (converter-safe).\n   * Normalized by `app-utils/lockdown.ts`.\n   */\n  suspendedAt?: number\n  suspendedReasonCode?: string\n  suspendedMessage?: string\n  suspendedUntilMs?: number\n  /**\n   * Per-site plugin deny-list (AGL-1014): plugin ids the org has enabled\n   * but this site switches OFF. Subtracted from the org's resolved set by\n   * `resolveHostEnabledPlugins` — the host can only ever narrow, never\n   * widen, and an absent field means every org-enabled plugin runs here.\n   * Writable by site ADMINS only (rules). The base component library's id is\n   * ignored; a plugin on for every workspace (AI) is switched off for this\n   * site like any other (AGL-3028).\n   */\n  disabledPlugins?: string[]\n  /**\n   * Per-site plugin OPT-IN list (AGL-2486): the `defaultOffPerSite` plugin\n   * ids this site has explicitly turned on. Today that is `accounts` — the\n   * user-accounts capability behind `/signin`, `/signup` and `/recover`.\n   *\n   * The companion of `disabledPlugins` above, not a duplicate of it, because\n   * a deny-list cannot express \"off until asked\": absent means ON there, and\n   * every published site was therefore serving member pages whether or not\n   * it had members. This field is what an absent value means OFF for, and it\n   * is read ONLY for ids the catalog marks default-off, so it can never\n   * widen a site past its org. Writable by site ADMINS only (rules).\n   */\n  enabledPlugins?: string[]\n  /**\n   * External image hosts this site's owner has approved (AGL-1152).\n   *\n   * The tenant's `img-src` is built from this list, per site, in the\n   * middleware — which is the only layer that runs ahead of the ISR cache, and\n   * therefore the only place a per-site policy can be set at all.\n   *\n   * ## Why the list exists rather than a platform-wide allowlist\n   *\n   * AGL-1726 refused to enforce `img-src` because hotlinking an external image\n   * is an ADVERTISED authoring feature (`image.tsx` tells authors to paste a\n   * URL), so a first-party-only policy would silently revoke a documented\n   * capability from every published site at once. Enforcement against a list\n   * the OWNER chose revokes nothing, and the console warns at authoring time\n   * so a refusal is never the first anyone hears of it.\n   *\n   * It is also what gives that issue's condition 6 — \"a rollback that does not\n   * need a deploy\" — an answer: this is host data, so widening or emptying it\n   * propagates within the verdict TTL with no Vercel build in the path.\n   *\n   * ⛔ NOT a place to put `firebasestorage.googleapis.com`. That host is PINNED\n   * in `security-origins.js` and deliberately not owner-removable: orgs without\n   * the paid `mediaCdn` entitlement store absolute download URLs, so an owner\n   * who deleted it would blank their own images (AGL-1726 condition 5).\n   *\n   * Stored as bare hostnames (`cdn.example.com`, or one leading `*.` label).\n   * Anything with a scheme, port, path or separator is REFUSED at the parse\n   * rather than repaired — `img-src` sources are space-delimited and\n   * directives `;`-delimited, so both are injection points. Writable by site\n   * ADMINS only (rules).\n   */\n  approvedImageHosts?: string[]\n  /** Site languages (AGL-164), e.g. ['en', 'es']; first is the default\n   * unless `defaultLocale` says otherwise. */\n  locales?: string[]\n  defaultLocale?: string\n  /**\n   * The IANA zone THIS SITE's published dates read in (AGL-3252) — absent\n   * means the workspace's `timeZone`, and absent there means UTC.\n   *\n   * AGL-3237 put the zone on the organization and said a per-site override\n   * was worth its own issue because it would need a second rules change. It\n   * does not: the host document's client branch is a deny-list, so a field\n   * it does not name is already writable, and what the override actually\n   * needed was the classification below. An agency running a Chicago site\n   * and a Berlin site out of one workspace is the case it exists for.\n   *\n   * Read through `resolveSiteTimeZone`, never directly: a stored zone can\n   * predate an IANA rename, and an unusable one has to fall back to the\n   * workspace rather than throw inside a page render.\n   */\n  timeZone?: string\n  /** Directory of shared layouts by display name (mirrors `screens`). */\n  layouts?: Record<LayoutUid, string>\n  theme?: AglynHostTheme\n\n  // CONCEPT: Redirect screens\n  redirects?: Record<RedirectUid, true>\n\n  // CONCEPT: Enterprise - Siloed projects\n  projectId?: ProjectUid\n  projectNumber?: ProjectNumber\n}\n\n/**\n * Host-document fields an editor may legitimately write, each with the reason\n * (AGL-1361). Everything else must be denied in the rules' host key diff.\n *\n * `host-write-deny-coverage.spec.ts` fails the build for any field of this\n * document that is in neither list, so \"I forgot\" is not a reachable state —\n * the answer that costs nothing is always to deny. The reason strings are the\n * point: they record that somebody decided, rather than that somebody did not\n * notice. AGL-1364 is what this catches, found while writing it.\n *\n * The bar for landing here: could a client rewrite change what the platform\n * DECIDES — an entitlement, a price, where a request routes, who may read? If\n * so it belongs in the rules, whatever the console does today.\n */\nexport const HOST_CLIENT_WRITABLE_FIELDS: Readonly<Record<string, string>> = {\n  displayName:\n    'The site name shown in the console. Cosmetic, org-scoped, and decides ' +\n    'nothing — the public address is `subdomain`/`cname`, both denied.',\n  logoUrl:\n    'The site brand mark rendered by the tenant nav (AGL-594). Authored ' +\n    'content pointing at already-public media; no gate reads it.',\n  seo:\n    'Title, description, favicon, app icon, social card and the AGL-1263 ' +\n    '`discourageSearchEngines` switch. All of it is authoring: the values ' +\n    'end up in the page the editor is already free to write.',\n  // `screens` LEFT this map in AGL-2334 and is now classified as denied,\n  // following the `disabledPlugins` precedent: it is TIERED, not freely\n  // client-writable. The reason it used to carry — \"an editor who may add a\n  // screen may name it\" — is still true of an editor and false of an\n  // `author`, and a field one role may write and another may not belongs on\n  // the denied side of this partition, where the tier is visible. Registering\n  // a path in this map is what makes a page reachable on the live site, so it\n  // is the publish surface an author is refused; see `canPublishHostContent`\n  // in cloud/firebase-firestore.rules.\n  layouts:\n    'The shared-layout directory. A layout has no route of its own, so unlike ' +\n    '`screens` this map decides nothing about reachability — it is an index ' +\n    'maintained alongside API-created layout docs. What publishing a layout ' +\n    'moves is the `versionId` pointer on the layout document, which the rules ' +\n    'freeze for an `author` there (AGL-2334), not here.',\n  redirects:\n    'The redirect directory. The redirect DOCS are API-create-only so the ' +\n    '`redirectsPerHost` quota has somewhere to be enforced; this is the index.',\n  notFoundScreenId:\n    'Which screen renders unmatched paths (AGL-87). Points at a screen the ' +\n    'editor already owns, and serves their own visitors only.',\n  errorScreens:\n    'Designable error screens by status (AGL-131). Same reasoning as ' +\n    '`notFoundScreenId` — a binding to screens this editor already controls.',\n  maintenance:\n    'Maintenance mode (AGL-131): every path renders the 503 screen. A ' +\n    'site-wide availability switch, but it only ever takes the editor\\'s OWN ' +\n    'site down, which they can equally do by deleting its screens.',\n  locales:\n    'Site languages (AGL-164). The `multilingual` entitlement is re-checked ' +\n    'server-side at page load, so writing this buys nothing a plan forbids.',\n  defaultLocale: 'Which of `locales` serves an unprefixed path. Authoring.',\n  timeZone:\n    'Which calendar day this site attributes a published instant to ' +\n    '(AGL-3252), overriding the workspace zone. Editorial, and it reaches ' +\n    'only this site\\'s own rendered dates — nothing bills, gates or routes ' +\n    'on it, and every read validates it through `isSupportedTimeZone`, so ' +\n    'the worst a rewrite can do is move one publisher\\'s archive by a day. ' +\n    'The org\\'s `timeZone` is denied because /api/orgs/settings owns the ' +\n    'whole org document; this one rides the settings form\\'s client write ' +\n    'beside `seo`, which is read by the same renderer for the same reason.',\n  theme:\n    'The persisted MUI theme for the published site. Authoring — the theme ' +\n    'editor writes it directly, and it renders only on this host.',\n  themeOverride:\n    'The editor\\'s local diff on top of an installed marketplace theme, ' +\n    'written wholesale by the setup page. Authoring. Its PROVENANCE ' +\n    '(`themeInstalledFrom`) is denied instead, which is the half that has to ' +\n    'be true for `isOverrideForCurrentTheme` to mean anything.',\n  announcementBar:\n    'Site-wide announcement bar (AGL-195). `marketingOverlays`-gated, but ' +\n    'the gate is enforced where it counts — `site-page-enricher` re-checks ' +\n    'the entitlement at RENDER, so a free plan writing this bar never ships ' +\n    'it. The console gate is the affordance, not the boundary.',\n  popup: 'Promotional popup (AGL-196). Identical reasoning to `announcementBar`.',\n  business:\n    'Support email, address and social links behind the AGL-1022 host ' +\n    'tokens. Publisher-authored contact detail that renders into their own ' +\n    'pages and emails; undeclared on this interface, so the guard sees it ' +\n    'through the resolver sweep rather than the type.',\n  analytics:\n    'The Google Analytics measurement id the host configures for their own ' +\n    'site (AGL-138). Authoring: it only ever tags THEIR pages, the tenant ' +\n    'format-checks it before the inline script, and loading it is ' +\n    'consent-gated (AGL-1498). A rewrite mis-tags the rewriter\\'s own site.',\n  consent:\n    'The visitor consent tool switch (AGL-1498). Decides whether the ' +\n    'host\\'s OWN site asks its visitors before loading the analytics the ' +\n    'host configured — their compliance posture on their own pages, exactly ' +\n    'like `seo.discourageSearchEngines`. No platform gate reads it.',\n  createdAt:\n    'Stamped by /api/hosts/create. Nothing gates on it — the org owns ' +\n    'billing dates — and console saves touch it freely.',\n  updatedAt:\n    'Bumped by console saves to drive \"last edited\" copy. Decides nothing; ' +\n    'a forged value misleads the editor about their own site.',\n}\n\n/**\n * Host-document keys that never reach Firestore, so the rules have no opinion.\n */\nexport const HOST_UNPERSISTED_FIELDS: Readonly<Record<string, string>> = {\n  $id: 'The document id, attached on read by the Firestore hooks. Never a field.',\n}\n\n/** Error-screen bindings by HTTP-ish status (AGL-131). */\nexport interface HostErrorScreens {\n  notFound?: ScreenUid\n  unauthorized?: ScreenUid\n  forbidden?: ScreenUid\n  unavailable?: ScreenUid\n}\n\n/**\n * The membership screen slots (AGL-553), keyed as the console card and the\n * tenant loader spell them. The names carry the `ScreenId` suffix because\n * that is how they are persisted; the console writes them as dotted field\n * paths (`authScreens.signinScreenId`).\n */\nexport interface HostAuthScreens {\n  signinScreenId?: ScreenUid\n  signupScreenId?: ScreenUid\n  recoveryScreenId?: ScreenUid\n}\n\n/**\n * The error slots, as a value (AGL-2092).\n *\n * The console card enumerated these separately and so did nothing else, which\n * was fine while the list was only a list. It stopped being only a list when\n * `kind: 'error'` made an assigned screen stop counting against\n * `screensPerHost`: the number of slots is now the BOUND on how many screens a\n * host can take off its plan that way, so the bound and the pickers have to be\n * the same four things or the exemption is unbounded in one of them.\n *\n * `ERROR_SCREEN_MAX_PER_HOST` is `.length` of this, deliberately — adding a\n * fifth status here widens the exemption to five, which is correct and is the\n * only way it should ever widen.\n */\nexport const HOST_ERROR_SCREEN_SLOTS = [\n  'notFound',\n  'unauthorized',\n  'forbidden',\n  'unavailable',\n] as const\n\nexport type HostErrorScreenSlot = (typeof HOST_ERROR_SCREEN_SLOTS)[number]\n\nexport type ScreenUid = string\nexport type ScreenSlug = string\nexport type VersionUid = string\nexport type LayoutUid = string\n\n/**\n * Who may see an org-owned resource (AGL-1037): `'org'` is every site in\n * the org, `host:{hostId}` names one. Lives here rather than beside its\n * helpers in `app-utils/scope-tokens` because foundation cannot import\n * app-utils; that module re-exports this type along with the helpers.\n */\nexport type ScopeToken = 'org' | `host:${string}`\n\n/**\n * Uploaded media metadata (AGL-72): the binary lives in Firebase Storage at\n * `hosts/{hostId}/media/{mediaId}`; this doc mirrors it in Firestore at the\n * same logical path so the library can list without Storage list calls.\n */\nexport interface AglynHostMedia {\n  $id: HostMediaUid\n  fileName?: string\n  contentType?: string\n  sizeBytes?: number\n  /** Download URL captured at upload time; nodes reference this directly. */\n  url?: string\n  /**\n   * Folder doc id in `hosts/{hostId}/mediaFolders` (AGL-171); null/absent\n   * = root. Replaces the legacy free-text `folder` string below.\n   */\n  folderId?: string | null\n  /** Legacy AGL-124 free-text folder; read as fallback until migrated. */\n  folder?: string\n  tags?: string[]\n  alt?: string\n  description?: string\n  /** Auto-captured at upload (AGL-173); best-effort for images only. */\n  width?: number\n  height?: number\n  uploadedBy?: string\n  /**\n   * CDN delivery (AGL-175 / AGL-829): the stable, mediaId-keyed path\n   * (`/api/media/cdn/{scope}/{mediaId}`) served by both apps — location- and\n   * replace-independent (references never break; the route revalidates via\n   * the `contentHash` ETag). The same route also serves an immutable\n   * `…/{mediaId}/{hash}` form. `variants` are the WebP widths from upload.\n   */\n  cdnPath?: string\n  contentHash?: string\n  /**\n   * The FULL 64-hex sha256 of the served bytes (AGL-1614), written only by\n   * the routes that hash the bytes server-side. Additive beside\n   * {@link contentHash}, which is unchanged and stays the ETag and the\n   * immutable-URL segment.\n   *\n   * The distinction is load-bearing rather than tidy. `contentHash` is a\n   * 16-hex (64-bit) TRUNCATION of one of TWO digests — sha256 on\n   * `/api/media/upload` and `/api/media/replace`, GCS's md5 on\n   * `/api/media/upload-url` — which is fine for a cache validator (opaque,\n   * per-URL, self-consistent) and weak for anything that has to be a\n   * SECURITY key. Two md5 files with the same digest are hours of laptop\n   * compute to construct, and a truncation to 64 bits inherits that\n   * immediately; a quarantine keyed on such a value can be made to refuse an\n   * innocent asset. `contentSha256` has neither property.\n   *\n   * Absent, not null, when the server never held the bytes: the signed-upload\n   * route streams client → bucket and only downloads them back for an SVG\n   * sanitization pass, so that is the one case there where it is written.\n   * Absent means \"no strong key for these bytes\", and every consumer already\n   * degrades to `contentHash` and then to the per-asset key.\n   */\n  contentSha256?: string\n  variants?: number[]\n  /**\n   * Why an eligible asset has no {@link variants}, when generation was\n   * attempted and did not complete (AGL-1468).\n   *\n   * Written by every upload route and by `/api/media/replace`, and declared\n   * here late: it has been on production documents since AGL-1468 and was\n   * missing from this interface, so every reader either cast or guessed.\n   * Absent is the common, correct case — an SVG, a document, a source\n   * already narrower than 320px — and must never look like a fault.\n   */\n  variantsError?: string\n  /**\n   * The Cloud Storage object path (`{hosts|orgs}/{id}/media/{folders…}/{id}`).\n   * Written at upload, rewritten by a folder move, and read back by\n   * `serveMediaCdn` — which honors it ONLY inside this scope's media prefix,\n   * because it is client-influenced data on an admin-SDK bucket read\n   * (AGL-1881). Legacy assets have none and fall back to the flat layout.\n   */\n  storagePath?: string\n  /** Constructs `sanitizeSvgBuffer` removed (AGL-1474). Absent when clean. */\n  svgSanitized?: string[]\n  /** Uid of whoever last replaced the bytes (`/api/media/replace`). */\n  replacedBy?: string\n  /**\n   * What the uploader's browser measured about a VIDEO (AGL-2742).\n   *\n   * Client-reported and bounded by `normalizeVideoMetadata` before it lands,\n   * which is why it does not widen {@link width}/{@link height}: those are\n   * read from the bytes by the server and carry a stronger claim. A reader\n   * that folds the two together loses the ability to tell which it has.\n   *\n   * All three numbers or none — a `VideoObject` emitting a `duration` with\n   * no `width` is worse than one emitting neither.\n   */\n  video?: MediaVideoMetadata\n  /**\n   * The generated poster still for a video (AGL-2742), served by the CDN as\n   * `?poster=1` and — because it genuinely is an `image/webp` — under the\n   * shared edge policy rather than the origin-only one video takes.\n   *\n   * `variants` here are poster widths, generated by the same `sharp` pass\n   * that produces an image's, at `{storagePath}__poster__w{n}.webp`.\n   */\n  poster?: { width: number; height: number; variants: number[] }\n  /**\n   * Why a video has no {@link poster}: the browser could not decode it,\n   * would not paint a frame, or the encoder refused the bytes it sent.\n   * Absent on every video that has one, and on every non-video.\n   */\n  posterError?: string\n  /**\n   * Compressed delivery copies of a video (AGL-2745), in the order a\n   * renderer should emit `<source>` elements — most efficient codec first,\n   * because a browser takes the first it can decode.\n   *\n   * Produced out of band by `tools/scripts/generate-video-renditions.mjs`\n   * rather than at upload: there is no decoder in either upload runtime, and\n   * a hosted transcoder is a recurring bill this platform's budget does not\n   * carry. Absent means the master is the only copy, which is what every\n   * video served before this shipped.\n   */\n  videoRenditions?: MediaVideoRendition[]\n  /**\n   * User-defined key/value metadata (AGL-822), mirrored onto the Storage\n   * object's `customMetadata` by `/api/media/folders` (action\n   * `custom-metadata`); this doc copy is the source of truth for display.\n   */\n  customMetadata?: Record<string, string>\n  /**\n   * Which sites may see this asset (AGL-1037); absent = org-wide until the\n   * AGL-1040 backfill stamps it. Only meaningful on the org-scoped library\n   * (`orgs/{orgId}/media`) — a host's own library is private already.\n   */\n  visibleTo?: ScopeToken[]\n  /**\n   * Not fetchable without a signature (AGL-1051). **Orthogonal to\n   * `visibleTo`**, and the distinction is the whole point:\n   *\n   * - `visibleTo` answers *which sites may USE this asset* — a discovery\n   *   and authoring control. An asset restricted to one site is still\n   *   served to anyone who has its URL, because that site's pages are\n   *   public and the CDN that serves them is unauthenticated.\n   * - `private` answers *may the public FETCH these bytes at all*.\n   *\n   * A private asset carries no {@link cdnPath}, is refused by the pickers\n   * that place media into page content, and is reachable only through a\n   * short-lived signed URL minted for an authorized caller. Use it for\n   * things that are not web assets — a signed contract, unreleased\n   * artwork, an embargoed release — never for \"this image is only on one\n   * site\", which is what `visibleTo` is for.\n   */\n  private?: boolean\n  createdAt?: ITimestamp\n  updatedAt?: ITimestamp\n  deletedAt?: ITimestamp\n}\n\n/**\n * Media folder doc (AGL-171): `hosts/{hostId}/mediaFolders/{folderId}`.\n * Hierarchy/validation helpers live in `app-utils/media-folders`.\n */\nexport interface AglynHostMediaFolder {\n  $id: string\n  name: string\n  /** Parent folder id; null = root. Depth capped at 5 (see app-utils). */\n  parentId?: string | null\n  order?: number\n  /**\n   * Which sites may see this folder (AGL-1037). Assets carry their own\n   * scope — a folder's is applied to them by an explicit write-time\n   * cascade (AGL-1042), never inherited at read time.\n   */\n  visibleTo?: ScopeToken[]\n  createdAt?: ITimestamp\n}\n\n/**\n * Pending scheduled publication (AGL-61): when `publishAt` passes, the\n * parent doc's `versionId` pointer moves to `versionId`. Applied lazily by\n * the tenant's ISR revalidation (no dedicated cron needed).\n */\nexport interface PublishSchedule {\n  /** Version to make live; unused for `action: 'unpublish'` (AGL-113). */\n  versionId?: VersionUid\n  /**\n   * What happens at `publishAt` (AGL-113): `publish` (default) flips the\n   * live version pointer; `unpublish` removes the screen's routing-map\n   * entry so its path 404s after the next revalidate.\n   */\n  action?: 'publish' | 'unpublish'\n  publishAt: ITimestamp\n  /**\n   * `skipped-unentitled` is a terminal refusal (AGL-1185): the schedule came\n   * due on a plan without `scheduledPublishing`, so the executor declined it\n   * and will not reconsider.\n   *\n   * It exists because leaving it `pending` meant the refusal was not recorded\n   * anywhere — the schedule stayed due forever, and the moment the org upgraded\n   * to Business the next beat published it. Content someone scheduled and\n   * forgot, months later, surfacing during an upgrade. Recording the refusal is\n   * what makes it stop being due.\n   *\n   * Every reader tests `=== 'pending'`, so adding a member here degrades\n   * correctly rather than needing each one updated — checked, not assumed.\n   *\n   * `skipped-unroutable` is the second terminal refusal (AGL-1589): the\n   * publish came due on a screen with no live route and no address the\n   * executor could give it — no slug on the screen or one of its ancestors,\n   * an address another screen already holds, or an email document, which has\n   * no URL at all. One value for the three because they share a remedy (fix\n   * the address in the console and schedule it again) and because a terminal\n   * state is a thing every reader has to reason about; the console names the\n   * causes in its message.\n   *\n   * It exists for the same reason as the value above: before AGL-1589 that\n   * publish reported `applied` while the page kept 404ing, which is a silent\n   * failure in the worst direction. A recorded refusal is the difference\n   * between a schedule that did not run and one that pretended it had.\n   */\n  status:\n    | 'pending'\n    | 'applied'\n    | 'canceled'\n    | 'skipped-unentitled'\n    | 'skipped-unroutable'\n  createdAt?: ITimestamp\n}\n\n/** Host-scoped document */\nexport interface AglynScreen extends AglynDocument {\n  $id: ScreenUid\n  hostId?: HostUid\n  parentId?: ScreenUid\n  slug?: ScreenSlug\n  /** Position among siblings (screens sharing `parentId`) in the screens list. */\n  order?: number\n  versionId?: VersionUid\n  publishSchedule?: PublishSchedule\n  /** Password protection (AGL-87): sha256 hex of the visitor password. */\n  protection?: { passwordHash?: string }\n  /** Language this screen is written in (AGL-164), e.g. 'en'. */\n  locale?: string\n  /** Translations of this screen: locale → screen id (AGL-164). */\n  localeVariants?: Record<string, ScreenUid>\n  status?: HostScreenStatus\n  createdAt?: ITimestamp\n  updatedAt?: ITimestamp\n  /**\n   * When the screen's route was last published (AGL: date-published). Stamped\n   * by `publishScreenRoute` and cleared on unpublish, so it is present only\n   * while the screen is reachable — distinct from `createdAt`.\n   */\n  publishedAt?: ITimestamp\n  deletedAt?: ITimestamp\n  displayName?: string\n  /**\n   * Normalized `displayName` for case-insensitive prefix search (AGL-835);\n   * see `nameSearchKey`. Stamped by the screen create/import write paths so\n   * the besigner switcher can query screens by name instead of loading the\n   * whole collection.\n   */\n  nameLower?: string\n  description?: string\n  seo?: {\n    title?: string\n    description?: string\n    breadcrumb?: string\n    /**\n     * This screen's social card image (AGL-1337), overriding the host\n     * default. Same storage contract as {@link AglynHost.seo.image}: a\n     * `media:` reference or URL, `''` meaning cleared — which is how a screen\n     * goes back to inheriting the site default.\n     */\n    image?: string\n    /**\n     * Copied from the media record at pick time, and the FALLBACK rather than\n     * the answer: a replace rewrites the asset's pair and cannot reach this\n     * copy, so the head prefers what the asset's document records when the\n     * page is composed (AGL-2850). See `resolveSocialImage`.\n     */\n    imageWidth?: number\n    imageHeight?: number\n    /**\n     * `og:image:alt` (AGL-2417) — what the card SHOWS, for the screen\n     * readers that announce a social preview. Defaulted from the chosen DAM\n     * asset's own alt at pick time and editable per surface; stored beside\n     * the reference so `resolveSocialImage` emits the description belonging\n     * to the image that actually won the precedence list.\n     *\n     * Blank is never stored: `og:image:alt=\"\"` asserts the image conveys\n     * nothing, which is not what an undescribed card means.\n     */\n    imageAlt?: string\n  }\n\n  // CONCEPT: Scheduling\n  schedule?: {\n    startAt?: ITimestamp\n    endAt?: ITimestamp\n    next?: VersionUid\n    previous?: VersionUid\n  }\n\n  // CONCEPT: Contextual visibility\n  visibility?: HostScreenVisibility\n\n  // NOTE (AGL-676): `owner` and `contributors` were declared here and NEVER\n  // read or written by anything — zero call sites across the whole repo.\n  // Removed rather than left dangling: a declared-but-unmaintained field is\n  // how the next person builds on something that was never real. Editor\n  // attribution lives in `hosts/{hostId}/activity`, which is actually\n  // written. If a contributor set is wanted later, add one that is kept up\n  // to date.\n\n  /** Shared layout this screen renders inside (see {@link AglynLayout}). */\n  layoutId?: LayoutUid\n}\n\n/**\n * Host-scoped document.\n * `N` lets higher layers narrow the node schema (e.g. the aglyn SDK\n * instantiates it with its richer `NodeSchema`).\n */\nexport interface AglynScreenVersion<N = AglynNodeSchema>\n  extends AglynDocument {\n  $id: VersionUid\n  hostId?: HostUid\n  screenId?: ScreenUid\n  createdAt?: ITimestamp\n  updatedAt?: ITimestamp\n  nodes?: Record<NodeId, N>\n  /**\n   * Shared layout THIS VERSION renders inside (see {@link AglynLayout}).\n   *\n   * Key-present wins over the screen document's {@link AglynScreen.layoutId}:\n   * a `LayoutUid` binds the version to that layout, an explicit `null` renders\n   * the version with no layout, and an absent key inherits the screen's\n   * binding. Per-version binding is what lets a scheduled version bring its\n   * own chrome live at publish time without reframing the currently served\n   * version. On layout versions ({@link AglynLayoutVersion}) this same key is\n   * instead the back-pointer to the owning layout document.\n   */\n  layoutId?: LayoutUid | null\n  /**\n   * This version's values for the properties of the layouts it renders inside\n   * (AGL-2893), stored beside the {@link layoutId} binding: layout id →\n   * property name → value, for every layout in the chain.\n   *\n   * Keyed by layout so that binding a different layout never hands this\n   * screen's values to a property of the same name there, and so that a\n   * layout nested inside another can be given values of its own. A property\n   * the screen leaves unset renders with its default. Read on screen versions\n   * only.\n   */\n  layoutPropValues?: Record<\n    LayoutUid,\n    Record<string, ReusableComponentPropValue>\n  >\n  /**\n   * This version's restyling of the layouts it renders inside (AGL-3286),\n   * stored beside {@link layoutPropValues}: layout id → that layout's own\n   * node id → an sx record merged over the element's styling for this page\n   * only. The layout's content stays the layout's, and every other screen\n   * using it is unaffected. A node id the layout no longer has is ignored.\n   * Read on screen versions only — see `layout-style-overrides.ts`.\n   */\n  layoutStyleOverrides?: Record<\n    LayoutUid,\n    Record<string, Record<string, unknown>>\n  >\n}\n\n/** Unique id of a host-level reusable component definition. */\nexport type ComponentDefUid = string\n\n/**\n * Attribute field kinds that hold no value of their own: they arrange other\n * fields (a sub-form, tabs, a wizard, a repeating field array), decorate one\n * (an input add-on), or only display or trigger something (plain text, a\n * button). A property is one value, so none of these is a property kind —\n * see `NON_VALUE_FIELD_KINDS` for the reason each is listed.\n */\nexport type NonValueFieldKind =\n  | FieldComponentType.BUTTON\n  | FieldComponentType.BUTTON_GROUP\n  | FieldComponentType.FIELD_ARRAY\n  | FieldComponentType.INPUT_ADDON_BUTTON_GROUP\n  | FieldComponentType.INPUT_ADDON_GROUP\n  | FieldComponentType.PLAIN_TEXT\n  | FieldComponentType.SUB_FORM\n  | FieldComponentType.TAB_ITEM\n  | FieldComponentType.TABS\n  | FieldComponentType.WIZARD\n\n/**\n * Attribute field kinds whose property kind was named before properties\n * covered every field kind, and keeps that stored name: a text field is\n * `text`, a textarea `richText`, a switch `boolean`, a dropdown `choice`, an\n * icon picker `icon` and a screen picker `href`.\n */\nexport type LegacyNamedFieldKind =\n  | FieldComponentType.TEXT_FIELD\n  | FieldComponentType.TEXTAREA\n  | FieldComponentType.SWITCH\n  | FieldComponentType.SELECT\n  | FieldComponentType.ICON_PICKER\n  | FieldComponentType.SCREEN_SELECT\n\n/**\n * Kind of a declared component or layout property (AGL-1247, AGL-2893): which\n * control edits it, in the Properties dialog and on every page that sets it,\n * and which fields it can be bound to.\n *\n * Derived from the attribute schema's own field kinds rather than listed\n * beside them. Every {@link FieldComponentType} that holds a value is a\n * property kind — under its own stored value (`color-picker`,\n * `css-dimension`, …), or under the name it already had\n * ({@link LegacyNamedFieldKind}). `number` and `image` are the two text-field\n * variants a coded component declares as `type: 'number'` or as a media\n * field. So a field kind added to the attribute schema is a property kind the\n * moment it exists, and `REUSABLE_PROP_KINDS` fails to compile until it says\n * how the kind is edited.\n *\n * These values are stored in component and layout documents. Never rename\n * one.\n */\nexport type ReusableComponentPropType =\n  | 'text'\n  | 'richText'\n  | 'image'\n  | 'href'\n  | 'number'\n  | 'boolean'\n  | 'choice'\n  | 'icon'\n  | `${Exclude<FieldComponentType, NonValueFieldKind | LegacyNamedFieldKind>}`\n\n/**\n * A property's value as it is stored: a default on the declaration, or a\n * page's own value in `propValues` / `layoutPropValues`.\n *\n * The shape follows the kind's control — a Yes / no stores a boolean, a\n * slider a number, a list of answers an array, an icon pick its id and path —\n * and text-shaped kinds store text. Defaults written before the kinds were\n * typed are text (`'true'`, `'28'`), which every reader accepts.\n */\nexport type ReusableComponentPropValue =\n  | string\n  | number\n  | boolean\n  | ReadonlyArray<string | number>\n  | ReusableComponentIcon\n\n/**\n * One rule of a property's `condition`: the attribute schema's condition\n * (data-driven-forms' `ConditionDefinition`), with `when` naming another\n * property of the same component or layout instead of an attribute.\n *\n * The operators are the schema's own — `is` (one value, or any of a list),\n * `notMatch` to negate `is` or `pattern`, `isEmpty`, `isNotEmpty`, `pattern`\n * with `flags`, and the four comparisons — and the rule is evaluated by\n * data-driven-forms' own parser, in the Attributes panel and at render. Only\n * the serializable part is here: a stored document cannot carry a function.\n */\nexport interface ReusableComponentPropRule {\n  /** The name of the property whose value decides. */\n  when: string\n  is?: string | number | boolean | ReadonlyArray<string | number | boolean>\n  notMatch?: boolean\n  isEmpty?: boolean\n  isNotEmpty?: boolean\n  pattern?: string\n  flags?: string\n  greaterThan?: number\n  greaterThanOrEqualTo?: number\n  lessThan?: number\n  lessThanOrEqualTo?: number\n}\n\n/**\n * When a property shows and applies: one rule, a list that must ALL hold, or\n * the schema's `and` / `or` / `not` over rules.\n */\nexport type ReusableComponentPropCondition =\n  | ReusableComponentPropRule\n  | { and: ReusableComponentPropCondition[] }\n  | { or: ReusableComponentPropCondition[] }\n  | { not: ReusableComponentPropCondition | ReusableComponentPropCondition[] }\n\n/**\n * One answer a `choice` prop offers (AGL-2871).\n *\n * Two halves because two people read it: the page author picks the `label`,\n * and the field inside the component receives the `value` — which is why a\n * dropdown bound to the prop needs values it offers itself.\n */\nexport interface ReusableComponentPropOption {\n  /** What a field bound to the prop receives. */\n  value: string\n  /** What the Attributes panel shows; falls back to `value`. */\n  label?: string\n}\n\n/**\n * A prop a reusable component declares (AGL-1247), so one definition can\n * render different content per instance instead of being copied per page.\n *\n * Inside the definition the author binds a node prop to it with the\n * existing token syntax — `{{prop.headline}}`, the same mechanism behind\n * `{{entry.*}}` and `{{host.*}}` — and `composeReusableComponentNodes`\n * substitutes each instance's own values as it grafts.\n */\nexport interface ReusableComponentProp {\n  /**\n   * Token name: `{{prop.<name>}}`. This is the STABLE key instances store\n   * their overrides under, so renaming one orphans every existing value —\n   * the editor must rename in place rather than remove-and-add.\n   */\n  name: string\n  type?: ReusableComponentPropType\n  /** Field label in the Attributes panel; falls back to `name`. */\n  label?: string\n  /**\n   * Help shown beside the property's field wherever a page sets it — the\n   * attribute schema's `description`.\n   */\n  description?: string\n  /**\n   * Rendered wherever an instance leaves this prop unset, and shown as the\n   * Attributes field's placeholder. One field serving both is deliberate:\n   * a component that renders its own sensible copy until overridden is the\n   * \"shows the placeholder from the component\" behaviour, and it means an\n   * unset prop can never collapse a section to empty on a live page.\n   */\n  defaultValue?: ReusableComponentPropValue\n  /**\n   * The answers a page picks from, in the order offered, for a kind whose\n   * control lists answers (`choice`, `radio`, `toggle-button`,\n   * `dual-list-select`, and a `checkbox` that is a list). A `defaultValue`\n   * names one of their values, or several for a kind that takes several.\n   */\n  options?: ReusableComponentPropOption[]\n  /**\n   * The kind's own settings, named by the kind's `settings` in\n   * `REUSABLE_PROP_KINDS`: a slider's range, whether a choice takes several\n   * answers, which theme scale a theme-scale field offers. They are the\n   * attribute field's own props, so a coded component's attribute and a\n   * property of the same kind are configured with the same words.\n   */\n  settings?: Record<string, string | number | boolean>\n  /**\n   * When the property shows and applies. While it does not hold, the field is\n   * hidden wherever a page sets it, and the property renders as one with no\n   * value and no default: text bound to it is empty, a Yes / no is a no, and\n   * a field bound to it keeps its own default.\n   */\n  condition?: ReusableComponentPropCondition | ReusableComponentPropCondition[]\n  /**\n   * `icon` only: the SVG path of the icon `defaultValue` names, stored beside\n   * the id when the default is picked, for the reason\n   * {@link ReusableComponentIcon} stores both — a published page never loads\n   * the icon catalog, so an id alone draws the empty Icon placeholder. An\n   * instance's own pick travels the same way, as a whole\n   * {@link ReusableComponentIcon} in its prop values.\n   */\n  defaultIconPath?: string\n}\n\n/**\n * A reusable component's chosen icon (AGL-1193), stood in for by the generic\n * package glyph when unset.\n *\n * Both halves are stored, for the reason AGL-1212 exists: the MDI catalog is\n * ~2.9 MB and only picker surfaces load it, so anything that had to resolve\n * `iconId` on a render surface got `DEFAULT_ICON` — a real path, so every\n * icon painted a confident \"help\" glyph. The id stays the source of truth;\n * `iconPath` is the denormalized copy that travels with the document.\n */\nexport interface ReusableComponentIcon {\n  iconId?: string\n  iconPath?: string\n}\n\n/**\n * Where a reusable component is placed (AGL-3287): on the site's pages, or in\n * the emails the site sends.\n *\n * The two are built from different elements — an email is made of the email\n * plugin's mail-safe blocks, a page of everything else — and neither renders\n * the other's, so a component belongs to exactly one. Absent on every\n * component made before emails could reuse one, which is why absent means\n * `site` and is never backfilled.\n */\nexport type ReusableComponentKind = 'site' | 'email'\n\n/**\n * Reusable component definition: a node subtree promoted from a screen,\n * inserted anywhere as an instance node (`componentId: 'reusableInstance'`,\n * `props.refId`) and grafted at render time (see\n * `composeReusableComponentNodes`). Host-scoped document at\n * `hosts/{hostId}/components/{componentId}`.\n */\nexport interface AglynHostComponent<N = AglynNodeSchema>\n  extends AglynDocument {\n  $id: ComponentDefUid\n  hostId?: HostUid\n  displayName?: string\n  description?: string\n  /**\n   * Where this component is placed (AGL-3287): `email` for a block reused\n   * across emails — a header, a footer — and absent (or `site`) for one\n   * placed on pages. It decides which drawer offers the component: an email\n   * offers email blocks alone, and a page never offers one.\n   *\n   * Set when the component is created and carried by every copy made of it\n   * — a duplicate, a template, a marketplace install — so a copy lands in\n   * the same drawer as its source.\n   */\n  kind?: ReusableComponentKind\n  /**\n   * Icon shown wherever an instance of this component is represented in the\n   * besigner (AGL-1193) — the hierarchy row, the canvas badge, the element\n   * drawer. Absent on every component that predates the picker, which is\n   * why it is optional and never defaulted: unset means \"the package glyph\",\n   * not \"an icon we failed to read\".\n   */\n  icon?: ReusableComponentIcon\n  /**\n   * Definition tree root id within {@link AglynHostComponent.nodes}.\n   *\n   * `rootId` and `nodes` on THIS doc are the published snapshot — the copy\n   * the tenant runtime renders. `getComponents` reads every component in a\n   * single collection query on each page render, so they deliberately stay\n   * here rather than moving into the version docs below: relocating them\n   * would turn one query into N+1 on the hot path of every published site\n   * (AGL-679).\n   */\n  rootId?: NodeId\n  nodes?: Record<NodeId, N>\n  /**\n   * Declared props (AGL-1247), published alongside `rootId`/`nodes` and for\n   * the same reason: the tenant reads this doc, so a definition whose props\n   * stayed on the version doc would graft with every `{{prop.*}}` token\n   * unresolved on the live site.\n   */\n  props?: ReusableComponentProp[]\n  /**\n   * Working version pointer (AGL-679). Absent on components that predate\n   * the standalone editor — those still render from the fields above, and\n   * opening one creates version 1 from them.\n   */\n  versionId?: VersionUid\n  createdAt?: ITimestamp\n  updatedAt?: ITimestamp\n  deletedAt?: ITimestamp\n}\n\n/**\n * A reusable component's editing history (AGL-679), at\n * `hosts/{hostId}/components/{componentId}/versions/{versionId}`.\n *\n * Same shape as a screen version, with the component's `rootId` carried so\n * publishing is a copy of both fields onto the parent rather than a\n * reconstruction. Edits here are invisible to live sites until published —\n * the same mental model screens already have.\n */\nexport interface AglynHostComponentVersion<N = AglynNodeSchema>\n  extends AglynDocument {\n  $id: VersionUid\n  hostId?: HostUid\n  componentId?: ComponentDefUid\n  displayName?: string\n  rootId?: NodeId\n  nodes?: Record<NodeId, N>\n  /** Declared props being edited; published onto the parent (AGL-1247). */\n  props?: ReusableComponentProp[]\n  createdAt?: ITimestamp\n  updatedAt?: ITimestamp\n}\n\n/**\n * Shared layout: canvas chrome (appbar, footer, nav) designed once and\n * rendered around every bound screen. Host-scoped document at\n * `hosts/{hostId}/layouts/{layoutId}`.\n */\nexport interface AglynLayout extends AglynDocument {\n  $id: LayoutUid\n  hostId?: HostUid\n  /** Published version pointer; bound screens render this version. */\n  versionId?: VersionUid\n  publishSchedule?: PublishSchedule\n  versions?: Array<VersionUid>\n  displayName?: string\n  description?: string\n  /**\n   * Layout this layout renders inside (AGL-703) — the same relationship\n   * `AglynScreen.layoutId` expresses, one level up, so shared chrome can\n   * sit outside a more specific frame. Must not be this layout, or any\n   * layout already below it; see `canNestLayout`.\n   */\n  layoutId?: LayoutUid\n  // `contributors` removed here too — see the note on AglynScreen (AGL-676).\n  createdAt?: ITimestamp\n  updatedAt?: ITimestamp\n}\n\n/**\n * Shared layout version. Node map has the same shape as a screen version\n * (including compression at rest) plus a LayoutSlot node marking where the\n * bound screen's content is grafted. Hosted at\n * `hosts/{hostId}/layouts/{layoutId}/versions/{versionId}`.\n */\nexport interface AglynLayoutVersion<N = AglynNodeSchema>\n  extends AglynScreenVersion<N> {\n  layoutId?: LayoutUid\n  hostId?: HostUid\n  /**\n   * The properties this layout declares (AGL-2893), each set by the screens\n   * that render inside it. On the version rather than the layout document,\n   * beside the nodes that bind them: a layout is served by its version\n   * pointer, so a version's properties go live with its tree.\n   */\n  props?: ReusableComponentProp[]\n}\n\nexport type TemplateUid = string\n\n/** What a template can be instantiated as. */\nexport type TemplateKind = 'page' | 'component' | 'layout'\n\n/**\n * A named substitution offered when the template is instantiated. Values are\n * applied with `resolveNamedTokens` — the same `{{name}}` mechanism that\n * renders collection entry templates — so a template author marks copy as\n * `{{productName}}` and is prompted for it on use.\n */\nexport interface TemplatePlaceholder {\n  /** Token name as it appears in the nodes, without the braces. */\n  name: string\n  /** Prompt label shown when instantiating. */\n  label?: string\n  defaultValue?: string\n}\n\n/**\n * Where a template came from.\n *\n * SERVER-MANAGED. A client that could write this would be able to stamp\n * `marketplace` provenance on something it authored, and the library shows\n * this to the user as a trust signal.\n */\nexport interface TemplateSource {\n  type: 'authored' | 'marketplace' | 'starter'\n  /** Marketplace listing this was installed from. */\n  listingId?: string\n  /** Listing version installed — compared against `latestVersion` to\n   *  surface \"update available\" without storing anything extra. */\n  version?: number | string\n  /** First-party starter id from `starter-templates.ts`. */\n  starterId?: string\n  /**\n   * Bundle-level identity for a seeded starter (AGL-687). A multi-page\n   * starter seeds one page template per screen, exactly as a marketplace\n   * install does; these carry the name/description/order of the bundle the\n   * screens belong to so the gallery can present them as the single starter\n   * they were authored as, without a second, code-side template source.\n   */\n  starterName?: string\n  starterDescription?: string\n  /** Position within the starter; fixes the order pages are created in. */\n  starterOrder?: number\n}\n\n/**\n * Reusable starting point for a page, component or layout (AGL-666).\n * Host-scoped document at `hosts/{hostId}/templates/{templateId}`.\n *\n * Distinct from the things it produces: a template is inert until\n * instantiated, so marketplace downloads land here rather than becoming live\n * pages. `nodes` carries the same node-map shape screens, components and\n * layouts already use, which is what lets one collection serve all three\n * kinds.\n */\nexport interface AglynTemplate<N = AglynNodeSchema> extends AglynDocument {\n  $id: TemplateUid\n  hostId?: HostUid\n  kind?: TemplateKind\n  displayName?: string\n  description?: string\n  category?: string\n  nodes?: Record<NodeId, N>\n  /** Definition tree root — `component` kind, mirroring AglynHostComponent. */\n  rootId?: NodeId\n  /**\n   * The properties a `component` or `layout` template's tree binds to\n   * (AGL-2932), carried so what is made from it declares them — without them\n   * every `{{prop.*}}` in the tree renders raw.\n   */\n  props?: ReusableComponentProp[]\n  /**\n   * A `component` template's {@link AglynHostComponent.kind} (AGL-3287), so\n   * the component made from it is offered where its source was: an email\n   * block saved as a template makes an email block again. Named apart from\n   * {@link kind}, which says what the template makes.\n   */\n  componentKind?: ReusableComponentKind\n  /** Suggested slug — `page` kind; de-conflicted against the host on use. */\n  slug?: string\n  /** Mirrors AglynScreen.seo — carried through to the created page. */\n  seo?: {\n    title?: string\n    description?: string\n    breadcrumb?: string\n    image?: string\n    imageWidth?: number\n    imageHeight?: number\n    /** Mirrors `AglynScreen.seo.imageAlt` (AGL-2417). */\n    imageAlt?: string\n  }\n  placeholders?: Array<TemplatePlaceholder>\n  /**\n   * Theme the template was designed against, carried over from a site\n   * template's snapshot. Held rather than applied: applying a theme changes\n   * the whole site's appearance, which is exactly the kind of instant,\n   * site-wide change installing is not allowed to make (AGL-669).\n   */\n  theme?: Record<string, unknown>\n  source?: TemplateSource\n  createdAt?: ITimestamp\n  updatedAt?: ITimestamp\n  deletedAt?: ITimestamp\n}\n\nexport type RedirectUid = string\n\n/** CONCEPT: Host redirects. Host-scoped document */\nexport interface AglynRedirect extends AglynDocument {\n  $id: RedirectUid\n  hostId?: HostUid\n  sourcePath?: HostPath\n  sourceScreen?: ScreenUid\n  destinationPath?: HostPath\n  destinationScreen?: ScreenUid\n  statusCode?: HttpStatusCode\n  params?: HostRedirectParams\n  flags?: {\n    regex?: true\n    ignoreSlash?: true\n    ignoreCase?: true\n  }\n  hits?: number\n  lastAccess?: ITimestamp\n  description?: string\n}\n"],"names":["HostScreenStatus","HostScreenVisibility","HostViewType","HostViewFormat","HostEntityType","HostRedirectParams","HOST_CLIENT_WRITABLE_FIELDS","displayName","logoUrl","seo","layouts","redirects","notFoundScreenId","errorScreens","maintenance","locales","defaultLocale","timeZone","theme","themeOverride","announcementBar","popup","business","analytics","consent","createdAt","updatedAt","HOST_UNPERSISTED_FIELDS","$id","HOST_ERROR_SCREEN_SLOTS"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GA6BD,OAAO,IAAA,AAAKA,0CAAAA;;;;;;;WAAAA;MAOX;AAED,OAAO,IAAA,AAAKC,8CAAAA;;;;;;;WAAAA;MAOX;AAED,OAAO,IAAA,AAAKC,sCAAAA;0CACD;0CACA;IACT,4EAA4E,wCACpE;WAJEA;MAKX;AAED,OAAO,IAAA,AAAKC,wCAAAA;kDACG;oDACE;WAFLA;MAGX;AAED,OAAO,IAAA,AAAKC,wCAAAA;oDACK;8CACN;WAFCA;MAGX;AAED,OAAO,IAAA,AAAKC,4CAAAA;;uDAEA;qDACF;WAHEA;MAIX;AAueD;;;;;;;;;;;;;CAaC,GACD,OAAO,MAAMC,8BAAgE;IAC3EC,aACE,2EACA;IACFC,SACE,wEACA;IACFC,KACE,yEACA,0EACA;IACF,uEAAuE;IACvE,sEAAsE;IACtE,0EAA0E;IAC1E,mEAAmE;IACnE,0EAA0E;IAC1E,4EAA4E;IAC5E,4EAA4E;IAC5E,2EAA2E;IAC3E,qCAAqC;IACrCC,SACE,8EACA,4EACA,4EACA,8EACA;IACFC,WACE,0EACA;IACFC,kBACE,2EACA;IACFC,cACE,qEACA;IACFC,aACE,sEACA,6EACA;IACFC,SACE,4EACA;IACFC,eAAe;IACfC,UACE,oEACA,0EACA,2EACA,0EACA,2EACA,yEACA,0EACA;IACFC,OACE,2EACA;IACFC,eACE,wEACA,oEACA,6EACA;IACFC,iBACE,0EACA,2EACA,4EACA;IACFC,OAAO;IACPC,UACE,sEACA,2EACA,0EACA;IACFC,WACE,2EACA,0EACA,kEACA;IACFC,SACE,qEACA,yEACA,4EACA;IACFC,WACE,sEACA;IACFC,WACE,2EACA;AACJ,EAAC;AAED;;CAEC,GACD,OAAO,MAAMC,0BAA4D;IACvEC,KAAK;AACP,EAAC;AAsBD;;;;;;;;;;;;;CAaC,GACD,OAAO,MAAMC,0BAA0B;IACrC;IACA;IACA;IACA;CACD,CAAS"}

package/src/lib/foundation/index.d.ts

@@ -23,7 +23,7 @@ export * from './definitions/shared';
 export { HOST_ERROR_SCREEN_SLOTS, HOST_UNPERSISTED_FIELDS, HostEntityType, HostRedirectParams, HostScreenStatus, HostScreenVisibility, HostViewFormat, HostViewType, } from './definitions/platform.types';
 export { ORG_CLIENT_WRITABLE_FIELDS, ORG_UNPERSISTED_FIELDS, } from './definitions/org-billing.types';
 export type { AglynOrgBilling, CoreOrgEntitlements, CoreOrgFeatureFlags, OrgBandwidthCap, OrgBrandingProfile, OrgCrmAssignmentRule, OrgCrmHostSettings, OrgCrmInbound, OrgCrmRoundRobin, OrgCrmSettings, OrgDiscount, OrgEntitlements, OrgFeatureFlags, OrgPlan, OrgPlanComp, OrgSeatAddons, OrgSubscription, OrgUid, } from './definitions/org-billing.types';
-export type { AglynDocument, AglynHost, AglynHostComponent, AglynHostComponentVersion, AglynHostMedia, AglynHostMediaFolder, AglynHostTheme, AglynLayout, AglynRedirect, AglynScreen, AglynTemplate, AglynUser, ComponentDefUid, HostAnnouncementBar, HostErrorScreens, HostErrorScreenSlot, HostPopup, HostMediaUid, HostPath, HostUid, LayoutUid, LegacyNamedFieldKind, NonValueFieldKind, ProjectNumber, ProjectUid, PublishSchedule, RedirectUid, ReusableComponentIcon, ReusableComponentProp, ReusableComponentPropCondition, ReusableComponentPropOption, ReusableComponentPropRule, ReusableComponentPropType, ReusableComponentPropValue, ScopeToken, ScreenSlug, ScreenUid, TemplateKind, TemplatePlaceholder, TemplateSource, TemplateUid, UserUid, VersionUid, } from './definitions/platform.types';
+export type { AglynDocument, AglynHost, AglynHostComponent, AglynHostComponentVersion, AglynHostMedia, AglynHostMediaFolder, AglynHostTheme, AglynLayout, AglynRedirect, AglynScreen, AglynTemplate, AglynUser, ComponentDefUid, HostAnnouncementBar, HostErrorScreens, HostErrorScreenSlot, HostPopup, HostMediaUid, HostPath, HostUid, LayoutUid, LegacyNamedFieldKind, NonValueFieldKind, ProjectNumber, ProjectUid, PublishSchedule, RedirectUid, ReusableComponentIcon, ReusableComponentKind, ReusableComponentProp, ReusableComponentPropCondition, ReusableComponentPropOption, ReusableComponentPropRule, ReusableComponentPropType, ReusableComponentPropValue, ScopeToken, ScreenSlug, ScreenUid, TemplateKind, TemplatePlaceholder, TemplateSource, TemplateUid, UserUid, VersionUid, } from './definitions/platform.types';
 export * from './constants/_internal';
 export * from './constants/app';
 export * from './constants/canvas';

package/src/lib/foundation/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/foundation/index.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2022 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//    / __ \\/ ____/ ____/  _/ | / /  _/_  __/  _/ __ \\/ | / / ___/\n//   / / / / __/ / /_   / //  |/ // /  / /  / // / / /  |/ /\\__ \\\n//  / /_/ / /___/ __/ _/ // /|  // /  / / _/ // /_/ / /|  /___/ /\n// /_____/_____/_/   /___/_/ |_/___/ /_/ /___/\\____/_/ |_//____/\n// 👇\n\nexport * from './definitions/components.types'\n// One postal address + one phone format, shared by the personal profile, the\n// org billing address and the Stripe customer (AGL-1133). The failure this\n// prevents is a phone number stored three ways in three collections.\nexport * from './definitions/contact.types'\n// Which host subcollections the media usage scan reads, and which it skips\n// with a written reason (AGL-1867). A VALUE, and exported here rather than\n// kept in the console, because the guard that keeps it equal to a repo-wide\n// sweep lives beside the other derived host-subcollection guards.\nexport * from './definitions/host-content-collections'\nexport * from './definitions/organization.types'\n// The component and layout property kinds (AGL-2893), VALUES because the\n// Properties dialog, the Attributes panel and the graft all read the same\n// table — one list per field kind, derived from `FieldComponentType`.\nexport * from './definitions/property-kinds'\nexport * from './definitions/shared'\n// `HOST_UNPERSISTED_FIELDS` is a VALUE for the same reason its org twin below\n// is: it states which `hosts/{hostId}` keys are never fields. It is exported\n// here so the write boundary can enforce that declaration at runtime\n// (AGL-1429), not only so the rules coverage guard can read it.\nexport {\n  // The four error slots as a VALUE (AGL-2092). Exported because their COUNT\n  // is now the bound on `kind: 'error'` exemptions (`ERROR_SCREEN_MAX_PER_HOST`)\n  // as well as the console card's picker list — one list, so the pickers and\n  // the bound cannot drift apart.\n  HOST_ERROR_SCREEN_SLOTS,\n  HOST_UNPERSISTED_FIELDS,\n  HostEntityType,\n  HostRedirectParams,\n  HostScreenStatus,\n  HostScreenVisibility,\n  HostViewFormat,\n  HostViewType,\n} from './definitions/platform.types'\n// AglynScreenVersion/AglynLayoutVersion are exported (specialized with the\n// SDK's NodeSchema) from ../types/screen instead of this generic form.\n// Org billing vocabulary (see definitions/org-billing.types.ts and the\n// glossary). The two ownership maps are VALUES, not types: they are the\n// declared client-writable/unpersisted partition of `orgs/{orgId}` that the\n// AGL-1355 coverage guard checks the Firestore rules against.\nexport {\n  ORG_CLIENT_WRITABLE_FIELDS,\n  ORG_UNPERSISTED_FIELDS,\n} from './definitions/org-billing.types'\nexport type {\n  AglynOrgBilling,\n  // The core halves of the two composed shapes (AGL-3124): what a plan table\n  // declares exhaustively, beside the plugin half every reader gets through\n  // `OrgEntitlements` / `OrgFeatureFlags`.\n  CoreOrgEntitlements,\n  CoreOrgFeatureFlags,\n  OrgBandwidthCap,\n  OrgBrandingProfile,\n  OrgCrmAssignmentRule,\n  OrgCrmHostSettings,\n  OrgCrmInbound,\n  OrgCrmRoundRobin,\n  OrgCrmSettings,\n  OrgDiscount,\n  OrgEntitlements,\n  OrgFeatureFlags,\n  OrgPlan,\n  OrgPlanComp,\n  OrgSeatAddons,\n  OrgSubscription,\n  OrgUid,\n} from './definitions/org-billing.types'\nexport type {\n  AglynDocument,\n  AglynHost,\n  AglynHostComponent,\n  AglynHostComponentVersion,\n  AglynHostMedia,\n  AglynHostMediaFolder,\n  AglynHostTheme,\n  AglynLayout,\n  AglynRedirect,\n  AglynScreen,\n  AglynTemplate,\n  AglynUser,\n  ComponentDefUid,\n  HostAnnouncementBar,\n  HostErrorScreens,\n  HostErrorScreenSlot,\n  HostPopup,\n  HostMediaUid,\n  HostPath,\n  HostUid,\n  LayoutUid,\n  LegacyNamedFieldKind,\n  NonValueFieldKind,\n  ProjectNumber,\n  ProjectUid,\n  PublishSchedule,\n  RedirectUid,\n  ReusableComponentIcon,\n  ReusableComponentProp,\n  ReusableComponentPropCondition,\n  ReusableComponentPropOption,\n  ReusableComponentPropRule,\n  ReusableComponentPropType,\n  ReusableComponentPropValue,\n  ScopeToken,\n  ScreenSlug,\n  ScreenUid,\n  TemplateKind,\n  TemplatePlaceholder,\n  TemplateSource,\n  TemplateUid,\n  UserUid,\n  VersionUid,\n} from './definitions/platform.types'\n\n//    __________  _   ________________    _   _____________\n//   / ____/ __ \\/ | / / ___/_  __/   |  / | / /_  __/ ___/\n//  / /   / / / /  |/ /\\__ \\ / / / /| | /  |/ / / /  \\__ \\\n// / /___/ /_/ / /|  /___/ // / / ___ |/ /|  / / /  ___/ /\n// \\____/\\____/_/ |_//____//_/ /_/  |_/_/ |_/ /_/  /____/\n// 👇\n\nexport * from './constants/_internal'\nexport * from './constants/app'\nexport * from './constants/canvas'\nexport * from './constants/components'\nexport * from './constants/shared'\nexport * from './constants/symbol'\n"],"names":["HOST_ERROR_SCREEN_SLOTS","HOST_UNPERSISTED_FIELDS","HostEntityType","HostRedirectParams","HostScreenStatus","HostScreenVisibility","HostViewFormat","HostViewType","ORG_CLIENT_WRITABLE_FIELDS","ORG_UNPERSISTED_FIELDS"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED,kEAAkE;AAClE,kEAAkE;AAClE,iEAAiE;AACjE,iEAAiE;AACjE,gEAAgE;AAChE,KAAK;AAEL,cAAc,oCAAgC;AAC9C,6EAA6E;AAC7E,2EAA2E;AAC3E,qEAAqE;AACrE,cAAc,iCAA6B;AAC3C,2EAA2E;AAC3E,2EAA2E;AAC3E,4EAA4E;AAC5E,kEAAkE;AAClE,cAAc,4CAAwC;AACtD,cAAc,sCAAkC;AAChD,yEAAyE;AACzE,0EAA0E;AAC1E,sEAAsE;AACtE,cAAc,kCAA8B;AAC5C,cAAc,0BAAsB;AACpC,8EAA8E;AAC9E,6EAA6E;AAC7E,qEAAqE;AACrE,gEAAgE;AAChE,SACE,2EAA2E;AAC3E,+EAA+E;AAC/E,2EAA2E;AAC3E,gCAAgC;AAChCA,uBAAuB,EACvBC,uBAAuB,EACvBC,cAAc,EACdC,kBAAkB,EAClBC,gBAAgB,EAChBC,oBAAoB,EACpBC,cAAc,EACdC,YAAY,QACP,kCAA8B;AACrC,2EAA2E;AAC3E,uEAAuE;AACvE,uEAAuE;AACvE,wEAAwE;AACxE,4EAA4E;AAC5E,8DAA8D;AAC9D,SACEC,0BAA0B,EAC1BC,sBAAsB,QACjB,qCAAiC;AAsExC,2DAA2D;AAC3D,2DAA2D;AAC3D,0DAA0D;AAC1D,0DAA0D;AAC1D,yDAAyD;AACzD,KAAK;AAEL,cAAc,2BAAuB;AACrC,cAAc,qBAAiB;AAC/B,cAAc,wBAAoB;AAClC,cAAc,4BAAwB;AACtC,cAAc,wBAAoB;AAClC,cAAc,wBAAoB"}
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/foundation/index.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2022 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//    / __ \\/ ____/ ____/  _/ | / /  _/_  __/  _/ __ \\/ | / / ___/\n//   / / / / __/ / /_   / //  |/ // /  / /  / // / / /  |/ /\\__ \\\n//  / /_/ / /___/ __/ _/ // /|  // /  / / _/ // /_/ / /|  /___/ /\n// /_____/_____/_/   /___/_/ |_/___/ /_/ /___/\\____/_/ |_//____/\n// 👇\n\nexport * from './definitions/components.types'\n// One postal address + one phone format, shared by the personal profile, the\n// org billing address and the Stripe customer (AGL-1133). The failure this\n// prevents is a phone number stored three ways in three collections.\nexport * from './definitions/contact.types'\n// Which host subcollections the media usage scan reads, and which it skips\n// with a written reason (AGL-1867). A VALUE, and exported here rather than\n// kept in the console, because the guard that keeps it equal to a repo-wide\n// sweep lives beside the other derived host-subcollection guards.\nexport * from './definitions/host-content-collections'\nexport * from './definitions/organization.types'\n// The component and layout property kinds (AGL-2893), VALUES because the\n// Properties dialog, the Attributes panel and the graft all read the same\n// table — one list per field kind, derived from `FieldComponentType`.\nexport * from './definitions/property-kinds'\nexport * from './definitions/shared'\n// `HOST_UNPERSISTED_FIELDS` is a VALUE for the same reason its org twin below\n// is: it states which `hosts/{hostId}` keys are never fields. It is exported\n// here so the write boundary can enforce that declaration at runtime\n// (AGL-1429), not only so the rules coverage guard can read it.\nexport {\n  // The four error slots as a VALUE (AGL-2092). Exported because their COUNT\n  // is now the bound on `kind: 'error'` exemptions (`ERROR_SCREEN_MAX_PER_HOST`)\n  // as well as the console card's picker list — one list, so the pickers and\n  // the bound cannot drift apart.\n  HOST_ERROR_SCREEN_SLOTS,\n  HOST_UNPERSISTED_FIELDS,\n  HostEntityType,\n  HostRedirectParams,\n  HostScreenStatus,\n  HostScreenVisibility,\n  HostViewFormat,\n  HostViewType,\n} from './definitions/platform.types'\n// AglynScreenVersion/AglynLayoutVersion are exported (specialized with the\n// SDK's NodeSchema) from ../types/screen instead of this generic form.\n// Org billing vocabulary (see definitions/org-billing.types.ts and the\n// glossary). The two ownership maps are VALUES, not types: they are the\n// declared client-writable/unpersisted partition of `orgs/{orgId}` that the\n// AGL-1355 coverage guard checks the Firestore rules against.\nexport {\n  ORG_CLIENT_WRITABLE_FIELDS,\n  ORG_UNPERSISTED_FIELDS,\n} from './definitions/org-billing.types'\nexport type {\n  AglynOrgBilling,\n  // The core halves of the two composed shapes (AGL-3124): what a plan table\n  // declares exhaustively, beside the plugin half every reader gets through\n  // `OrgEntitlements` / `OrgFeatureFlags`.\n  CoreOrgEntitlements,\n  CoreOrgFeatureFlags,\n  OrgBandwidthCap,\n  OrgBrandingProfile,\n  OrgCrmAssignmentRule,\n  OrgCrmHostSettings,\n  OrgCrmInbound,\n  OrgCrmRoundRobin,\n  OrgCrmSettings,\n  OrgDiscount,\n  OrgEntitlements,\n  OrgFeatureFlags,\n  OrgPlan,\n  OrgPlanComp,\n  OrgSeatAddons,\n  OrgSubscription,\n  OrgUid,\n} from './definitions/org-billing.types'\nexport type {\n  AglynDocument,\n  AglynHost,\n  AglynHostComponent,\n  AglynHostComponentVersion,\n  AglynHostMedia,\n  AglynHostMediaFolder,\n  AglynHostTheme,\n  AglynLayout,\n  AglynRedirect,\n  AglynScreen,\n  AglynTemplate,\n  AglynUser,\n  ComponentDefUid,\n  HostAnnouncementBar,\n  HostErrorScreens,\n  HostErrorScreenSlot,\n  HostPopup,\n  HostMediaUid,\n  HostPath,\n  HostUid,\n  LayoutUid,\n  LegacyNamedFieldKind,\n  NonValueFieldKind,\n  ProjectNumber,\n  ProjectUid,\n  PublishSchedule,\n  RedirectUid,\n  ReusableComponentIcon,\n  ReusableComponentKind,\n  ReusableComponentProp,\n  ReusableComponentPropCondition,\n  ReusableComponentPropOption,\n  ReusableComponentPropRule,\n  ReusableComponentPropType,\n  ReusableComponentPropValue,\n  ScopeToken,\n  ScreenSlug,\n  ScreenUid,\n  TemplateKind,\n  TemplatePlaceholder,\n  TemplateSource,\n  TemplateUid,\n  UserUid,\n  VersionUid,\n} from './definitions/platform.types'\n\n//    __________  _   ________________    _   _____________\n//   / ____/ __ \\/ | / / ___/_  __/   |  / | / /_  __/ ___/\n//  / /   / / / /  |/ /\\__ \\ / / / /| | /  |/ / / /  \\__ \\\n// / /___/ /_/ / /|  /___/ // / / ___ |/ /|  / / /  ___/ /\n// \\____/\\____/_/ |_//____//_/ /_/  |_/_/ |_/ /_/  /____/\n// 👇\n\nexport * from './constants/_internal'\nexport * from './constants/app'\nexport * from './constants/canvas'\nexport * from './constants/components'\nexport * from './constants/shared'\nexport * from './constants/symbol'\n"],"names":["HOST_ERROR_SCREEN_SLOTS","HOST_UNPERSISTED_FIELDS","HostEntityType","HostRedirectParams","HostScreenStatus","HostScreenVisibility","HostViewFormat","HostViewType","ORG_CLIENT_WRITABLE_FIELDS","ORG_UNPERSISTED_FIELDS"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED,kEAAkE;AAClE,kEAAkE;AAClE,iEAAiE;AACjE,iEAAiE;AACjE,gEAAgE;AAChE,KAAK;AAEL,cAAc,oCAAgC;AAC9C,6EAA6E;AAC7E,2EAA2E;AAC3E,qEAAqE;AACrE,cAAc,iCAA6B;AAC3C,2EAA2E;AAC3E,2EAA2E;AAC3E,4EAA4E;AAC5E,kEAAkE;AAClE,cAAc,4CAAwC;AACtD,cAAc,sCAAkC;AAChD,yEAAyE;AACzE,0EAA0E;AAC1E,sEAAsE;AACtE,cAAc,kCAA8B;AAC5C,cAAc,0BAAsB;AACpC,8EAA8E;AAC9E,6EAA6E;AAC7E,qEAAqE;AACrE,gEAAgE;AAChE,SACE,2EAA2E;AAC3E,+EAA+E;AAC/E,2EAA2E;AAC3E,gCAAgC;AAChCA,uBAAuB,EACvBC,uBAAuB,EACvBC,cAAc,EACdC,kBAAkB,EAClBC,gBAAgB,EAChBC,oBAAoB,EACpBC,cAAc,EACdC,YAAY,QACP,kCAA8B;AACrC,2EAA2E;AAC3E,uEAAuE;AACvE,uEAAuE;AACvE,wEAAwE;AACxE,4EAA4E;AAC5E,8DAA8D;AAC9D,SACEC,0BAA0B,EAC1BC,sBAAsB,QACjB,qCAAiC;AAuExC,2DAA2D;AAC3D,2DAA2D;AAC3D,0DAA0D;AAC1D,0DAA0D;AAC1D,yDAAyD;AACzD,KAAK;AAEL,cAAc,2BAAuB;AACrC,cAAc,qBAAiB;AAC/B,cAAc,wBAAoB;AAClC,cAAc,4BAAwB;AACtC,cAAc,wBAAoB;AAClC,cAAc,wBAAoB"}

package/src/lib/plugin-manager/plugin-resource-drafts.d.ts

@@ -14,6 +14,7 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
+import type { ReusableComponentTree } from '../app-utils/compose-reusable-components';
 /**
  * Drafts one plugin writes for another (AGL-2912).
  *
@@ -97,6 +98,21 @@ export type PluginDraftCheck = {
     ok: false;
     problems: string[];
 };
+/** What a check is told beside the content. */
+export interface PluginDraftCheckContext {
+    hostId: string;
+    /**
+     * The site's published reusable components the content places, keyed by id
+     * — what `loadReferencedComponents` reads (AGL-3287).
+     *
+     * `check` does no I/O, so a caller whose content may place a component loads
+     * the definitions first and hands them in; a writer whose resource renders
+     * placed components composes them before judging, so what passes is what
+     * would render. Absent means none were loaded, and the content is judged as
+     * written.
+     */
+    components?: Readonly<Record<string, ReusableComponentTree | undefined>>;
+}
 export type PluginDraftWrite = (PluginDraftRecord & {
     ok: true;
     replayed: boolean;
@@ -107,9 +123,7 @@ export interface PluginResourceDraftWriter {
     /** Whether this member may create one on this site now; `null` admits. */
     refusal(context: PluginDraftContext): Promise<PluginDraftRefusal | null>;
     /** Whether content is well-formed, with what the owner derived from it. Pure. */
-    check(content: Readonly<Record<string, unknown>>, context: {
-        hostId: string;
-    }): PluginDraftCheck;
+    check(content: Readonly<Record<string, unknown>>, context: PluginDraftCheckContext): PluginDraftCheck;
     /** The draft written under `id`, or `null`. */
     read(context: {
         hostId: string;

package/src/lib/plugin-manager/plugin-resource-drafts.js

@@ -1,4 +1,3 @@
-import { _ as _extends } from "@swc/helpers/_/_extends";
 /**
  * @license
  * Copyright 2026 Aglyn LLC
@@ -14,7 +13,8 @@ import { _ as _extends } from "@swc/helpers/_/_extends";
  * 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 { getRegisteringPluginId } from "../app-utils/registering-plugin.js";
+ */ import { _ as _extends } from "@swc/helpers/_/_extends";
+import { getRegisteringPluginId } from "../app-utils/registering-plugin.js";
 import { definePluginServiceContract, registerPluginService, resolvePluginServices } from "./plugin-services.js";
 export const PLUGIN_RESOURCE_DRAFTS = definePluginServiceContract('core.resource-drafts', {
     multiple: true

package/src/lib/plugin-manager/plugin-resource-drafts.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/plugin-manager/plugin-resource-drafts.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 { getRegisteringPluginId } from '../app-utils/registering-plugin'\nimport {\n  definePluginServiceContract,\n  registerPluginService,\n  resolvePluginServices,\n} from './plugin-services'\n\n/**\n * Drafts one plugin writes for another (AGL-2912).\n *\n * A resource belongs to the plugin that models it: the document's shape, the\n * allowance a create counts against, who may create one, and what makes one\n * well-formed. A different plugin that produces such a resource — an importer\n * turning a file into pages, a generator turning a brief into an email, a\n * migration bringing campaigns over from another tool — must not write the\n * document itself, because it would restate the owner's rules and drift from\n * them the day the owner changes one. Nor may it import the owner, which the\n * package map forbids.\n *\n * So the owner registers a WRITER for the resource from its server surfaces,\n * and a caller asks for one by resource name. Every rule stays the owner's:\n *\n *  - `refusal` answers, before the caller spends anything, whether this\n *    member may create one on this site now: their role, the site's room;\n *  - `check` answers, synchronously and without I/O, whether content is\n *    well-formed, so a caller can hold what it produces to the owner's rules\n *    before it keeps it;\n *  - `read` reports the draft already written under an id, so a caller that\n *    runs again finds its draft rather than making a second;\n *  - `write` makes the draft, meets the allowance inside its own write, and\n *    never publishes, schedules or sends anything.\n *\n * Built on the typed service registry (`plugin-services`): one contract, every\n * writer registered under its resource name as the service's key.\n *\n * ## The registry carries no authorization of the CALLER\n *\n * Like `order-fulfilment`, a writer is a pre-authorized operation. It applies\n * the owner's rules to the member the draft is for, and knows nothing about\n * whether the caller may act for that member. A caller establishes, in its\n * own terms and before it asks: who is asking, that the org owns the site,\n * and that the owning plugin is switched on for that site.\n *\n * ## One writer per resource\n *\n * A resource has one owner. A second plugin registering a writer for a\n * resource another plugin already writes is refused, naming both, and the\n * incumbent keeps serving; the same plugin registering again — from its second\n * server surface, or on a hot reload — replaces its own.\n */\n\n/** Who a draft is for, on which site, and when. */\nexport interface PluginDraftContext {\n  orgId: string\n  hostId: string\n  /** The member the draft is made for: the owner applies its rules to them and records them as the author. */\n  uid: string\n  /** The org document the caller already read, for the owner's entitlement and allowance reads. */\n  org: Readonly<Record<string, unknown>> | null\n  now: Date\n}\n\n/** Why a draft cannot be made. */\nexport interface PluginDraftRefusal {\n  status: 400 | 403 | 404 | 409\n  /** Customer-safe: a caller shows it as it stands. */\n  error: string\n}\n\n/** A draft that exists. */\nexport interface PluginDraftRecord {\n  id: string\n  name: string\n  /** The version the draft opens on, where the resource has versions. */\n  versionId: string | null\n  /** What the owner reports about the draft beyond its identity, in the shape its writer documents. */\n  facts: Readonly<Record<string, unknown>>\n}\n\nexport interface PluginDraftRequest extends PluginDraftContext {\n  /** The draft's id, chosen by the caller: one per act, so a write asked again finds its draft. */\n  id: string\n  /** The name asked for; the owner may number it to keep it unique. */\n  name: string\n  /** The resource's content, in the shape the owner's writer documents and validates. */\n  content: Readonly<Record<string, unknown>>\n}\n\nexport type PluginDraftCheck =\n  | { ok: true; facts: Readonly<Record<string, unknown>> }\n  | { ok: false; problems: string[] }\n\nexport type PluginDraftWrite =\n  | (PluginDraftRecord & { ok: true; replayed: boolean })\n  | (PluginDraftRefusal & { ok: false })\n\nexport interface PluginResourceDraftWriter {\n  /** Whether this member may create one on this site now; `null` admits. */\n  refusal(context: PluginDraftContext): Promise<PluginDraftRefusal | null>\n  /** Whether content is well-formed, with what the owner derived from it. Pure. */\n  check(\n    content: Readonly<Record<string, unknown>>,\n    context: { hostId: string },\n  ): PluginDraftCheck\n  /** The draft written under `id`, or `null`. */\n  read(context: { hostId: string; id: string }): Promise<PluginDraftRecord | null>\n  /** Makes the draft; a refusal is returned, never thrown. */\n  write(request: PluginDraftRequest): Promise<PluginDraftWrite>\n}\n\nexport const PLUGIN_RESOURCE_DRAFTS =\n  definePluginServiceContract<PluginResourceDraftWriter>('core.resource-drafts', {\n    multiple: true,\n  })\n\n/**\n * Registers the writer for a resource. The owner is the loader's marker when\n * a register fn is running, else `options.pluginId`; with neither the\n * registration throws. A writer for a resource another plugin writes throws\n * naming both.\n */\nexport function registerPluginResourceDraftWriter(\n  resource: string,\n  writer: PluginResourceDraftWriter,\n  options?: { pluginId?: string },\n): void {\n  const key = resource.trim()\n  if (!key) throw new Error('a resource draft writer needs a resource name')\n  const pluginId = (getRegisteringPluginId() ?? options?.pluginId ?? '').trim()\n  const incumbent = resolvePluginServices(PLUGIN_RESOURCE_DRAFTS).find(\n    (entry) => entry.key === key,\n  )\n  if (incumbent && pluginId && incumbent.pluginId !== pluginId) {\n    throw new Error(\n      `resource \"${key}\" already has a draft writer from \"${incumbent.pluginId}\"; ` +\n        `refused \"${pluginId}\"`,\n    )\n  }\n  registerPluginService(PLUGIN_RESOURCE_DRAFTS, writer, {\n    ...(options?.pluginId ? { pluginId: options.pluginId } : {}),\n    key,\n  })\n}\n\nexport interface ResolvedPluginDraftWriter {\n  /** The plugin that owns the resource. */\n  pluginId: string\n  writer: PluginResourceDraftWriter\n}\n\n/** The writer for a resource, with its owner, or `null` when no plugin writes it. */\nexport function pluginResourceDraftWriter(resource: string): ResolvedPluginDraftWriter | null {\n  const key = resource.trim()\n  const entry = resolvePluginServices(PLUGIN_RESOURCE_DRAFTS).find((one) => one.key === key)\n  return entry ? { pluginId: entry.pluginId, writer: entry.impl } : null\n}\n"],"names":["getRegisteringPluginId","definePluginServiceContract","registerPluginService","resolvePluginServices","PLUGIN_RESOURCE_DRAFTS","multiple","registerPluginResourceDraftWriter","resource","writer","options","key","trim","Error","pluginId","incumbent","find","entry","pluginResourceDraftWriter","one","impl"],"mappings":";AAAA;;;;;;;;;;;;;;;CAeC,GAED,SAASA,sBAAsB,QAAQ,qCAAiC;AACxE,SACEC,2BAA2B,EAC3BC,qBAAqB,EACrBC,qBAAqB,QAChB,uBAAmB;AAyG1B,OAAO,MAAMC,yBACXH,4BAAuD,wBAAwB;IAC7EI,UAAU;AACZ,GAAE;AAEJ;;;;;CAKC,GACD,OAAO,SAASC,kCACdC,QAAgB,EAChBC,MAAiC,EACjCC,OAA+B;QAIbT,MAAAA;IAFlB,MAAMU,MAAMH,SAASI,IAAI;IACzB,IAAI,CAACD,KAAK,MAAM,IAAIE,MAAM;IAC1B,MAAMC,WAAW,EAACb,QAAAA,0BAAAA,oCAAAA,0BAA4BS,2BAAAA,QAASI,QAAQ,YAA7Cb,OAAiD,IAAIW,IAAI;IAC3E,MAAMG,YAAYX,sBAAsBC,wBAAwBW,IAAI,CAClE,CAACC,QAAUA,MAAMN,GAAG,KAAKA;IAE3B,IAAII,aAAaD,YAAYC,UAAUD,QAAQ,KAAKA,UAAU;QAC5D,MAAM,IAAID,MACR,CAAC,UAAU,EAAEF,IAAI,mCAAmC,EAAEI,UAAUD,QAAQ,CAAC,GAAG,CAAC,GAC3E,CAAC,SAAS,EAAEA,SAAS,CAAC,CAAC;IAE7B;IACAX,sBAAsBE,wBAAwBI,QAAQ,aAChDC,CAAAA,2BAAAA,QAASI,QAAQ,IAAG;QAAEA,UAAUJ,QAAQI,QAAQ;IAAC,IAAI,CAAC;QAC1DH;;AAEJ;AAQA,mFAAmF,GACnF,OAAO,SAASO,0BAA0BV,QAAgB;IACxD,MAAMG,MAAMH,SAASI,IAAI;IACzB,MAAMK,QAAQb,sBAAsBC,wBAAwBW,IAAI,CAAC,CAACG,MAAQA,IAAIR,GAAG,KAAKA;IACtF,OAAOM,QAAQ;QAAEH,UAAUG,MAAMH,QAAQ;QAAEL,QAAQQ,MAAMG,IAAI;IAAC,IAAI;AACpE"}
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/plugin-manager/plugin-resource-drafts.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport type { ReusableComponentTree } from '../app-utils/compose-reusable-components'\nimport { getRegisteringPluginId } from '../app-utils/registering-plugin'\nimport {\n  definePluginServiceContract,\n  registerPluginService,\n  resolvePluginServices,\n} from './plugin-services'\n\n/**\n * Drafts one plugin writes for another (AGL-2912).\n *\n * A resource belongs to the plugin that models it: the document's shape, the\n * allowance a create counts against, who may create one, and what makes one\n * well-formed. A different plugin that produces such a resource — an importer\n * turning a file into pages, a generator turning a brief into an email, a\n * migration bringing campaigns over from another tool — must not write the\n * document itself, because it would restate the owner's rules and drift from\n * them the day the owner changes one. Nor may it import the owner, which the\n * package map forbids.\n *\n * So the owner registers a WRITER for the resource from its server surfaces,\n * and a caller asks for one by resource name. Every rule stays the owner's:\n *\n *  - `refusal` answers, before the caller spends anything, whether this\n *    member may create one on this site now: their role, the site's room;\n *  - `check` answers, synchronously and without I/O, whether content is\n *    well-formed, so a caller can hold what it produces to the owner's rules\n *    before it keeps it;\n *  - `read` reports the draft already written under an id, so a caller that\n *    runs again finds its draft rather than making a second;\n *  - `write` makes the draft, meets the allowance inside its own write, and\n *    never publishes, schedules or sends anything.\n *\n * Built on the typed service registry (`plugin-services`): one contract, every\n * writer registered under its resource name as the service's key.\n *\n * ## The registry carries no authorization of the CALLER\n *\n * Like `order-fulfilment`, a writer is a pre-authorized operation. It applies\n * the owner's rules to the member the draft is for, and knows nothing about\n * whether the caller may act for that member. A caller establishes, in its\n * own terms and before it asks: who is asking, that the org owns the site,\n * and that the owning plugin is switched on for that site.\n *\n * ## One writer per resource\n *\n * A resource has one owner. A second plugin registering a writer for a\n * resource another plugin already writes is refused, naming both, and the\n * incumbent keeps serving; the same plugin registering again — from its second\n * server surface, or on a hot reload — replaces its own.\n */\n\n/** Who a draft is for, on which site, and when. */\nexport interface PluginDraftContext {\n  orgId: string\n  hostId: string\n  /** The member the draft is made for: the owner applies its rules to them and records them as the author. */\n  uid: string\n  /** The org document the caller already read, for the owner's entitlement and allowance reads. */\n  org: Readonly<Record<string, unknown>> | null\n  now: Date\n}\n\n/** Why a draft cannot be made. */\nexport interface PluginDraftRefusal {\n  status: 400 | 403 | 404 | 409\n  /** Customer-safe: a caller shows it as it stands. */\n  error: string\n}\n\n/** A draft that exists. */\nexport interface PluginDraftRecord {\n  id: string\n  name: string\n  /** The version the draft opens on, where the resource has versions. */\n  versionId: string | null\n  /** What the owner reports about the draft beyond its identity, in the shape its writer documents. */\n  facts: Readonly<Record<string, unknown>>\n}\n\nexport interface PluginDraftRequest extends PluginDraftContext {\n  /** The draft's id, chosen by the caller: one per act, so a write asked again finds its draft. */\n  id: string\n  /** The name asked for; the owner may number it to keep it unique. */\n  name: string\n  /** The resource's content, in the shape the owner's writer documents and validates. */\n  content: Readonly<Record<string, unknown>>\n}\n\nexport type PluginDraftCheck =\n  | { ok: true; facts: Readonly<Record<string, unknown>> }\n  | { ok: false; problems: string[] }\n\n/** What a check is told beside the content. */\nexport interface PluginDraftCheckContext {\n  hostId: string\n  /**\n   * The site's published reusable components the content places, keyed by id\n   * — what `loadReferencedComponents` reads (AGL-3287).\n   *\n   * `check` does no I/O, so a caller whose content may place a component loads\n   * the definitions first and hands them in; a writer whose resource renders\n   * placed components composes them before judging, so what passes is what\n   * would render. Absent means none were loaded, and the content is judged as\n   * written.\n   */\n  components?: Readonly<Record<string, ReusableComponentTree | undefined>>\n}\n\nexport type PluginDraftWrite =\n  | (PluginDraftRecord & { ok: true; replayed: boolean })\n  | (PluginDraftRefusal & { ok: false })\n\nexport interface PluginResourceDraftWriter {\n  /** Whether this member may create one on this site now; `null` admits. */\n  refusal(context: PluginDraftContext): Promise<PluginDraftRefusal | null>\n  /** Whether content is well-formed, with what the owner derived from it. Pure. */\n  check(\n    content: Readonly<Record<string, unknown>>,\n    context: PluginDraftCheckContext,\n  ): PluginDraftCheck\n  /** The draft written under `id`, or `null`. */\n  read(context: { hostId: string; id: string }): Promise<PluginDraftRecord | null>\n  /** Makes the draft; a refusal is returned, never thrown. */\n  write(request: PluginDraftRequest): Promise<PluginDraftWrite>\n}\n\nexport const PLUGIN_RESOURCE_DRAFTS =\n  definePluginServiceContract<PluginResourceDraftWriter>('core.resource-drafts', {\n    multiple: true,\n  })\n\n/**\n * Registers the writer for a resource. The owner is the loader's marker when\n * a register fn is running, else `options.pluginId`; with neither the\n * registration throws. A writer for a resource another plugin writes throws\n * naming both.\n */\nexport function registerPluginResourceDraftWriter(\n  resource: string,\n  writer: PluginResourceDraftWriter,\n  options?: { pluginId?: string },\n): void {\n  const key = resource.trim()\n  if (!key) throw new Error('a resource draft writer needs a resource name')\n  const pluginId = (getRegisteringPluginId() ?? options?.pluginId ?? '').trim()\n  const incumbent = resolvePluginServices(PLUGIN_RESOURCE_DRAFTS).find(\n    (entry) => entry.key === key,\n  )\n  if (incumbent && pluginId && incumbent.pluginId !== pluginId) {\n    throw new Error(\n      `resource \"${key}\" already has a draft writer from \"${incumbent.pluginId}\"; ` +\n        `refused \"${pluginId}\"`,\n    )\n  }\n  registerPluginService(PLUGIN_RESOURCE_DRAFTS, writer, {\n    ...(options?.pluginId ? { pluginId: options.pluginId } : {}),\n    key,\n  })\n}\n\nexport interface ResolvedPluginDraftWriter {\n  /** The plugin that owns the resource. */\n  pluginId: string\n  writer: PluginResourceDraftWriter\n}\n\n/** The writer for a resource, with its owner, or `null` when no plugin writes it. */\nexport function pluginResourceDraftWriter(resource: string): ResolvedPluginDraftWriter | null {\n  const key = resource.trim()\n  const entry = resolvePluginServices(PLUGIN_RESOURCE_DRAFTS).find((one) => one.key === key)\n  return entry ? { pluginId: entry.pluginId, writer: entry.impl } : null\n}\n"],"names":["getRegisteringPluginId","definePluginServiceContract","registerPluginService","resolvePluginServices","PLUGIN_RESOURCE_DRAFTS","multiple","registerPluginResourceDraftWriter","resource","writer","options","key","trim","Error","pluginId","incumbent","find","entry","pluginResourceDraftWriter","one","impl"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC;AAGD,SAASA,sBAAsB,QAAQ,qCAAiC;AACxE,SACEC,2BAA2B,EAC3BC,qBAAqB,EACrBC,qBAAqB,QAChB,uBAAmB;AAyH1B,OAAO,MAAMC,yBACXH,4BAAuD,wBAAwB;IAC7EI,UAAU;AACZ,GAAE;AAEJ;;;;;CAKC,GACD,OAAO,SAASC,kCACdC,QAAgB,EAChBC,MAAiC,EACjCC,OAA+B;QAIbT,MAAAA;IAFlB,MAAMU,MAAMH,SAASI,IAAI;IACzB,IAAI,CAACD,KAAK,MAAM,IAAIE,MAAM;IAC1B,MAAMC,WAAW,EAACb,QAAAA,0BAAAA,oCAAAA,0BAA4BS,2BAAAA,QAASI,QAAQ,YAA7Cb,OAAiD,IAAIW,IAAI;IAC3E,MAAMG,YAAYX,sBAAsBC,wBAAwBW,IAAI,CAClE,CAACC,QAAUA,MAAMN,GAAG,KAAKA;IAE3B,IAAII,aAAaD,YAAYC,UAAUD,QAAQ,KAAKA,UAAU;QAC5D,MAAM,IAAID,MACR,CAAC,UAAU,EAAEF,IAAI,mCAAmC,EAAEI,UAAUD,QAAQ,CAAC,GAAG,CAAC,GAC3E,CAAC,SAAS,EAAEA,SAAS,CAAC,CAAC;IAE7B;IACAX,sBAAsBE,wBAAwBI,QAAQ,aAChDC,CAAAA,2BAAAA,QAASI,QAAQ,IAAG;QAAEA,UAAUJ,QAAQI,QAAQ;IAAC,IAAI,CAAC;QAC1DH;;AAEJ;AAQA,mFAAmF,GACnF,OAAO,SAASO,0BAA0BV,QAAgB;IACxD,MAAMG,MAAMH,SAASI,IAAI;IACzB,MAAMK,QAAQb,sBAAsBC,wBAAwBW,IAAI,CAAC,CAACG,MAAQA,IAAIR,GAAG,KAAKA;IACtF,OAAOM,QAAQ;QAAEH,UAAUG,MAAMH,QAAQ;QAAEL,QAAQQ,MAAMG,IAAI;IAAC,IAAI;AACpE"}