@aglyn/aglyn 1.0.0-beta.220 → 1.0.0-beta.222

package/src/lib/foundation/definitions/organization.types.d.ts

@@ -23,7 +23,7 @@
  */
 import type { ITimestamp } from '@aglyn/shared-util-timestamp';
 import type { AccountAcquisition } from '../../app-utils/account-acquisition';
-import type { OrgCrmSettings, OrgEntitlements, OrgPlan, OrgSeatAddons, OrgSubscription } from './org-billing.types';
+import type { OrgCrmSettings, OrgEntitlements, OrgPlan, OrgSeatAddons, OrgSubscription, OrgUpgradeProposal } from './org-billing.types';
 import type { AglynDocument, HostUid, OrgUid, ScopeToken, UserUid } from './platform.types';
 export type { OrgUid } from './platform.types';
 /** Workspace subdomain label: `{slug}.aglyn.com` (Slack-style). */
@@ -146,6 +146,8 @@ export interface AglynOrganization extends AglynDocument {
     defaultResourceScope?: 'org' | 'host';
     /** The CRM's organization-wide settings (AGL-2613) — see `OrgCrmSettings`. */
     crm?: OrgCrmSettings;
+    /** The plan staff asked the workspace to move to (AGL-3466). */
+    upgradeProposal?: OrgUpgradeProposal;
 }
 /**
  * `orgs/{orgId}/members/{uid}` — THE authorization doc: rules resolve a
@@ -210,14 +212,53 @@ export interface AglynOrgMember extends AglynDocument {
      * single rules read; maintained by the staff suspension API.
      */
     orgSuspended?: boolean;
+    /**
+     * The row belongs to platform staff and takes none of the customer's seats
+     * (AGL-3466).
+     *
+     * Stamped by the server whenever it writes a row for an account that holds
+     * the `staff` claim at that moment — `createOrganization`, `upsertOrgMember`,
+     * `grantHostAccess` — and cleared on every row the account holds when the
+     * claim is revoked. Every seat counter and every seat gate skips a stamped
+     * row, so a staff member who builds a workspace for a prospect, or joins one
+     * to help, never fills the seat the customer is paying for. The rules refuse
+     * client writes to `members`, so nobody can stamp themselves.
+     */
+    staffSeat?: boolean;
+}
+/**
+ * What happens to the outgoing owner when an owner handoff is accepted
+ * (AGL-3466): `stay` keeps them on as an admin, `leave` takes them off the
+ * roster.
+ */
+export type OwnerHandoffPreviousOwner = 'stay' | 'leave';
+/** The handoff half of an owner-handoff invite (AGL-3466). */
+export interface AglynOrgOwnerHandoff {
+    previousOwner: OwnerHandoffPreviousOwner;
 }
 /** `orgs/{orgId}/invites/{inviteId}` — pending email invites. */
 export interface AglynOrgInvite extends AglynDocument {
     $id: string;
     email?: string;
+    /**
+     * `owner` only on an owner-handoff invite, which always carries `handoff`
+     * beside it (AGL-3466). Every other invite is admin, editor or viewer.
+     */
     role?: OrgRole;
     allHosts?: boolean;
     hostAccess?: Record<HostUid, HostAccessRole>;
+    /**
+     * Accepting this invite moves the workspace to the invitee (AGL-3466). It
+     * reserves no seat: the owner seat moves rather than being added, and the
+     * send-time check refuses a `stay` that would need a seat the plan lacks.
+     */
+    handoff?: AglynOrgOwnerHandoff;
+    /**
+     * The address belongs to an account holding the `staff` claim, checked when
+     * the invite is sent, so it reserves no seat (AGL-3466). Checked again at
+     * acceptance, against the account that actually accepts.
+     */
+    staffSeat?: boolean;
     invitedBy?: UserUid;
     createdAt?: ITimestamp;
     acceptedAt?: ITimestamp | null;

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

@@ -1 +1 @@
-{"version":3,"sources":["../../../../../../../libs/aglyn/src/lib/foundation/definitions/organization.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\n/**\n * Multi-tenant organizations (AGL-233, docs/MULTI_TENANT_FIRESTORE.md):\n * the org is the tenant boundary — one subscription, one workspace\n * subdomain, one isolation subtree. Billing fields mirror `AglynOrgBilling`\n * so the plan/entitlement resolvers work on either doc during the\n * transition; org-keyed billing lands with AGL-237.\n */\n\nimport type { ITimestamp } from '@aglyn/shared-util-timestamp'\nimport type { AccountAcquisition } from '../../app-utils/account-acquisition'\nimport type {\n  OrgCrmSettings,\n  OrgEntitlements,\n  OrgPlan,\n  OrgSeatAddons,\n  OrgSubscription,\n} from './org-billing.types'\nimport type {\n  AglynDocument,\n  HostUid,\n  OrgUid,\n  ScopeToken,\n  UserUid,\n} from './platform.types'\n\nexport type { OrgUid } from './platform.types'\n/** Workspace subdomain label: `{slug}.aglyn.com` (Slack-style). */\nexport type OrgSlug = string\n\n/** Org-wide roles, strongest to weakest. */\nexport type OrgRole = 'owner' | 'admin' | 'editor' | 'viewer'\n\n/**\n * Per-host refinement for editor/viewer members (\"3 of 15 sites\").\n *\n * `author` (AGL-2334) is `editor` MINUS publish: it may create and edit\n * every content document on the site, and it may not make any of it live.\n * It exists because the agency guide sells exactly that role — \"a client who\n * may edit content but not publish\" — and until now the narrowest thing we\n * could offer was `viewer`, which cannot edit at all.\n *\n * It is a HOST role rather than a twelfth org permission key deliberately.\n * Publishing is a set of client-direct Firestore writes, so it is enforced\n * in the security rules, and the rules resolve a host request from the\n * `memberRoles` projection with the one `get()` they already do. An org\n * permission key is on the wrong axis: rules cannot evaluate a custom role\n * without a second denormalized projection, and every publish surface would\n * need a server route it does not have.\n *\n * Ordered between `editor` and `viewer` because that is its strength, but\n * NOTHING may treat this union as ordered — `ORG_ROLE_WEIGHT` exists for the\n * org axis and has no counterpart here on purpose. Host roles are compared by\n * membership in a set (`HOST_CONTENT_WRITE_ROLES`, `HOST_PUBLISH_ROLES`), and\n * an author is not \"a weaker editor\" in a way any single number can express.\n */\nexport type HostAccessRole = 'admin' | 'editor' | 'author' | 'viewer'\n\n/**\n * A per-site permission key a collaborator can carry (AGL-2927, AGL-2984).\n * The host role decides what a collaborator may do to the SITE; these keys\n * decide what else they may do on it. Each is a catalog key a plugin\n * declares with host-role defaults, the same dotted key the org catalog\n * names, so one label serves both rosters.\n */\nexport type HostPermissionKey = string\n\n/**\n * Every host role, as a value — for `where('memberRoles.{uid}', 'in', …)`.\n *\n * `/hosts/{hostId}` is gated per document on `memberRoles.{uid}`, and\n * Firestore refuses to run a LIST that could return a denied document. So\n * every client query over `hosts` must carry this filter, and it must name\n * ALL the roles: a role missing from the array is a site the member owns and\n * cannot see, with no error to explain it (AGL-1145).\n *\n * Built from a `Record` rather than written as an array so that adding a role\n * to the union above fails to COMPILE here. A plain `HostAccessRole[]` would\n * happily stay short, which is the silent half of the bug.\n */\nconst HOST_ACCESS_ROLE_KEYS: Record<HostAccessRole, true> = {\n  admin: true,\n  editor: true,\n  author: true,\n  viewer: true,\n}\nexport const HOST_ACCESS_ROLES = Object.keys(\n  HOST_ACCESS_ROLE_KEYS,\n) as HostAccessRole[]\n\nexport interface AglynOrganization extends AglynDocument {\n  $id: OrgUid\n  name?: string\n  slug?: OrgSlug\n  /** Current owner; ownership can move without re-keying anything. */\n  ownerUid?: UserUid\n  /**\n   * Who CREATED the workspace — stamped once inside `createOrganization`'s\n   * transaction and mutated by nothing, `transferOrgOwnership` included\n   * (AGL-2265).\n   *\n   * `ownerUid` moves; this does not, and the difference is the whole point.\n   * The free-workspace ceiling counts the UNION of the two, so handing a\n   * workspace to an alt account, creating a fourth and taking the first one\n   * back is not a way past the limit. Denied to client writes in the rules\n   * for the same reason — a client that could clear its own attribution could\n   * mint free workspaces without limit.\n   *\n   * Absent on every org created before AGL-2265 shipped, and every reader\n   * must tolerate that: those are counted by `ownerUid` exactly as they\n   * always were.\n   */\n  createdByUid?: UserUid\n  /**\n   * Where the workspace came from (AGL-3289): its creator's acquisition\n   * record, copied by `createOrganization` at birth and naming the account it\n   * was copied from. Written by nothing else, and denied to client writes on\n   * every rules branch, for the reason `createdByUid` is: it is the\n   * platform's record about the workspace, not the workspace's about itself.\n   */\n  acquisition?: AccountAcquisition\n  /** Directory of the org's hosts (mirrors AglynOrgBilling.hosts). */\n  hosts?: Record<HostUid, true>\n\n  // Billing (mirrors AglynOrgBilling; source of truth moves here with AGL-237)\n  plan?: OrgPlan\n  entitlements?: OrgEntitlements\n  /**\n   * Per-org plugin switchboard (AGL-416): ids of plugins the workspace\n   * loads (see plugin-manager/enabled-plugins). Absent = all first-party\n   * plugins; always-on ids (base components) and the ids on for every\n   * workspace (AI) are unioned in regardless — a site switches those off for\n   * itself instead.\n   */\n  enabledPlugins?: string[]\n  seatAddons?: OrgSeatAddons\n  stripeCustomerId?: string\n  subscription?: OrgSubscription\n  suspendedAt?: ITimestamp | null\n  /** Staff-internal rationale (AGL-202). NEVER shown to the customer. */\n  suspendedReason?: string\n  /**\n   * Lockdown extensions (AGL-1501) on the shipped AGL-202 carrier — the org\n   * scope of the panic button. `suspendedReasonCode` is the enum the notice\n   * copy switches on (`security`/`billing`/`maintenance`/`manual`; absent =\n   * `manual`), `suspendedMessage` is the CUSTOMER-FACING notice body (unlike\n   * `suspendedReason`), and `suspendedUntilMs` is an optional expiry — once\n   * it passes, the suspension is inactive with no write needed (maintenance\n   * windows end on their own). Plain epoch ms, not a Timestamp, so every\n   * cache serialization reads it back unchanged. All written only by\n   * /api/admin/lockdown; normalized by `app-utils/lockdown.ts`.\n   */\n  suspendedReasonCode?: string\n  suspendedMessage?: string\n  suspendedUntilMs?: number\n  /**\n   * Whether that suspension is in force, stored for the staff list's\n   * Suspended filter (AGL-3416). See `AglynOrgBilling.suspended`.\n   */\n  suspended?: boolean\n  erasureRequestedAt?: ITimestamp | null\n  /**\n   * Scope applied to newly created datasets and media when nobody chooses\n   * (AGL-1048). `'org'` — the default and today's behavior — shares them\n   * with every site. `'host'` starts them private to the site they were\n   * created in, which is what an agency running client sites wants: safe\n   * by default rather than safe by discipline.\n   *\n   * Only meaningful when there IS a site in context. Created from the org\n   * Media or Data page there is no host to scope to, so those stay `'org'`\n   * either way.\n   */\n  defaultResourceScope?: 'org' | 'host'\n  /** The CRM's organization-wide settings (AGL-2613) — see `OrgCrmSettings`. */\n  crm?: OrgCrmSettings\n}\n\n/**\n * `orgs/{orgId}/members/{uid}` — THE authorization doc: rules resolve a\n * request with this single read. Owner/admin span every host; editor and\n * viewer see `hostAccess` (or `allHosts`).\n */\nexport interface AglynOrgMember extends AglynDocument {\n  $id: UserUid\n  role?: OrgRole\n  /**\n   * Custom role reference (AGL-243): id of an `orgs/{orgId}/roles` doc\n   * whose permission map overrides the org role's defaults.\n   */\n  roleId?: string\n  /** Per-member permission overrides (AGL-243); win over every layer. */\n  permissions?: Record<string, boolean>\n  /** Org-wide host access shortcut; otherwise `hostAccess` decides. */\n  allHosts?: boolean\n  hostAccess?: Record<HostUid, HostAccessRole>\n  /**\n   * Per-site permission overrides for a COLLABORATOR (AGL-2927), keyed by\n   * the host the grant is for. Absent keys resolve by the host role's\n   * default, so a document written before this field existed reads the same\n   * as one written after it. Org-wide members are never consulted here:\n   * their org role, custom role and `permissions` map decide.\n   */\n  hostPermissions?: Record<HostUid, Partial<Record<HostPermissionKey, boolean>>>\n  /**\n   * Denormalized reach as scope tokens (AGL-1038), so rules can intersect\n   * it with a resource's `visibleTo` — they cannot derive it from\n   * `hostAccess` because the rules language has no `.map()`. Written only\n   * by `syncOrgAuthProjections`; never edit it by hand.\n   */\n  scopeTokens?: ScopeToken[]\n  /**\n   * Denormalized THREE-LAYER permission verdict, so rules can honor a custom\n   * role they cannot resolve.\n   *\n   * `roleId` points at another document and `permissions` is only the top\n   * layer, so a rule reading either alone answers a different question from\n   * the server — and reproducing the precedence in CEL needs a second\n   * cross-document get() plus correct handling of a dangling id. This is\n   * `resolveOrgPermissions(member, customRole)`, already applied.\n   *\n   * ⚠️ ABSENT IS NOT EMPTY, and the rules must never treat it as either\n   * \"everything allowed\" or \"nothing allowed\". Documents predating this\n   * field, and any written by a path that bypasses\n   * `syncOrgAuthProjections`, carry no map at all; the rules fall back to\n   * the layers they CAN read — the role and the per-member overrides — which\n   * is exactly the verdict they gave before this field existed. Written only\n   * by `syncOrgAuthProjections` and by `createOrganization`'s inline stamp;\n   * never edit it by hand.\n   */\n  resolvedPermissions?: Record<string, boolean>\n  /** Denormalized for member lists without N user lookups. */\n  displayName?: string\n  email?: string\n  invitedBy?: UserUid\n  joinedAt?: ITimestamp\n  /**\n   * Denormalized org suspension flag (AGL-210) so host writes stay a\n   * single rules read; maintained by the staff suspension API.\n   */\n  orgSuspended?: boolean\n}\n\n/** `orgs/{orgId}/invites/{inviteId}` — pending email invites. */\nexport interface AglynOrgInvite extends AglynDocument {\n  $id: string\n  email?: string\n  role?: OrgRole\n  allHosts?: boolean\n  hostAccess?: Record<HostUid, HostAccessRole>\n  invitedBy?: UserUid\n  createdAt?: ITimestamp\n  acceptedAt?: ITimestamp | null\n  acceptedBy?: UserUid\n}\n\n/**\n * `orgSlugs/{slug}` — transactional uniqueness reservation; created and\n * deleted only by the org APIs (Admin SDK), publicly readable so the\n * console can resolve a workspace subdomain client-side.\n */\nexport interface OrgSlugReservation {\n  orgId: OrgUid\n  /**\n   * Set when the previous holder renamed away — the tombstone that keeps old\n   * workspace URLs redirecting until somebody else wants the name.\n   */\n  movedTo?: string\n  /**\n   * Epoch millis at which a PENDING reservation lapses (AGL-2585).\n   *\n   * Present only on a workspace created by an owner whose email was not yet\n   * verified, which is every password signup: the address is held for them,\n   * not granted to them, and the hold ends unless they confirm the address.\n   * Absent means granted, and a grant never expires — so every workspace made\n   * by a verified owner, and every one that predates this field, is outside\n   * the rule entirely.\n   *\n   * Cleared by `reap-unverified-orgs` once the owner verifies. Public, like\n   * the rest of this document, which is why nothing identifying the owner is\n   * written beside it.\n   */\n  reservedUntil?: number\n}\n\n/**\n * `hostIndex/{hostId}` — server-written host → org resolver so the tenant\n * renderer and middleware find a host's org without scanning.\n */\nexport interface HostIndexEntry {\n  orgId: OrgUid\n  subdomain?: string\n}\n\n/**\n * `users/{uid}/orgs/{orgId}` — reverse index for \"my organizations\",\n * maintained transactionally with the member doc by the membership API.\n */\nexport interface UserOrgMembership extends AglynDocument {\n  $id: OrgUid\n  role?: OrgRole\n  orgName?: string\n  slug?: OrgSlug\n  /**\n   * Mirror of `isOrgWideMember(orgs/{orgId}/members/{uid})` (AGL-1032): does\n   * this membership reach the whole org, or only a list of sites?\n   *\n   * `role` alone cannot answer it — `grantHostAccess` writes `role: 'viewer'`\n   * here for a site collaborator, exactly what a genuine org-wide viewer\n   * carries, so the console could not tell them apart without a second read\n   * of the member doc on every org route. Denormalized because the console\n   * navigation guard has to be synchronous: an async answer flashes the org\n   * chrome before hiding it.\n   *\n   * ABSENT means org-wide. Rows predating the mirror carry no flag, and a\n   * missing field must never lock a real member out of their own workspace\n   * (the same legacy shape `isOrgWideMember` handles). Only an explicit\n   * `false` scopes the console — see `isOrgWideMembership`.\n   *\n   * Navigation only. The Firestore rules are the access boundary (AGL-1026);\n   * a stale mirror at worst shows a page whose reads then come back empty.\n   */\n  orgWide?: boolean\n}\n\n/**\n * `users/{uid}/hostMemberships/{hostId}` — reverse index of the sites a user\n * can reach, mirroring `hosts/{hostId}.memberRoles` (AGL-844). Denormalizes the\n * host name so the site switcher and subdomain→id routing query a user's own\n * sites, ordered and name-prefix-searched, without scanning the `hosts`\n * collection. Admin-SDK-maintained beside `memberRoles`; a best-effort\n * convenience index, never an authorization source (the rules still gate host\n * reads on `memberRoles`). NOT named `hosts` — that would collide with the\n * top-level `hosts` collection for collection-group rules/indexes.\n */\nexport interface UserHostMembership extends AglynDocument {\n  $id: HostUid\n  orgId?: OrgUid\n  subdomain?: string\n  displayName?: string\n  nameLower?: string\n  /**\n   * Mirror of the host's `seo.favicon` (AGL-1071). The site switcher renders\n   * from this projection rather than the host doc, so without the mirror it\n   * showed the generic glyph for every site — the favicon feature worked in\n   * the sites list and nowhere else. Absent when the site has none; writers\n   * must DELETE it on clear rather than omit it, since the rows are written\n   * with `{ merge: true }` and an omitted field would keep the old icon.\n   */\n  favicon?: string\n  role?: HostAccessRole\n  updatedAt?: ITimestamp\n}\n"],"names":["HOST_ACCESS_ROLE_KEYS","admin","editor","author","viewer","HOST_ACCESS_ROLES","Object","keys"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED;;;;;;CAMC,GA4DD;;;;;;;;;;;;CAYC,GACD,MAAMA,wBAAsD;IAC1DC,OAAO;IACPC,QAAQ;IACRC,QAAQ;IACRC,QAAQ;AACV;AACA,OAAO,MAAMC,oBAAoBC,OAAOC,IAAI,CAC1CP,uBACmB"}
+{"version":3,"sources":["../../../../../../../libs/aglyn/src/lib/foundation/definitions/organization.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\n/**\n * Multi-tenant organizations (AGL-233, docs/MULTI_TENANT_FIRESTORE.md):\n * the org is the tenant boundary — one subscription, one workspace\n * subdomain, one isolation subtree. Billing fields mirror `AglynOrgBilling`\n * so the plan/entitlement resolvers work on either doc during the\n * transition; org-keyed billing lands with AGL-237.\n */\n\nimport type { ITimestamp } from '@aglyn/shared-util-timestamp'\nimport type { AccountAcquisition } from '../../app-utils/account-acquisition'\nimport type {\n  OrgCrmSettings,\n  OrgEntitlements,\n  OrgPlan,\n  OrgSeatAddons,\n  OrgSubscription,\n  OrgUpgradeProposal,\n} from './org-billing.types'\nimport type {\n  AglynDocument,\n  HostUid,\n  OrgUid,\n  ScopeToken,\n  UserUid,\n} from './platform.types'\n\nexport type { OrgUid } from './platform.types'\n/** Workspace subdomain label: `{slug}.aglyn.com` (Slack-style). */\nexport type OrgSlug = string\n\n/** Org-wide roles, strongest to weakest. */\nexport type OrgRole = 'owner' | 'admin' | 'editor' | 'viewer'\n\n/**\n * Per-host refinement for editor/viewer members (\"3 of 15 sites\").\n *\n * `author` (AGL-2334) is `editor` MINUS publish: it may create and edit\n * every content document on the site, and it may not make any of it live.\n * It exists because the agency guide sells exactly that role — \"a client who\n * may edit content but not publish\" — and until now the narrowest thing we\n * could offer was `viewer`, which cannot edit at all.\n *\n * It is a HOST role rather than a twelfth org permission key deliberately.\n * Publishing is a set of client-direct Firestore writes, so it is enforced\n * in the security rules, and the rules resolve a host request from the\n * `memberRoles` projection with the one `get()` they already do. An org\n * permission key is on the wrong axis: rules cannot evaluate a custom role\n * without a second denormalized projection, and every publish surface would\n * need a server route it does not have.\n *\n * Ordered between `editor` and `viewer` because that is its strength, but\n * NOTHING may treat this union as ordered — `ORG_ROLE_WEIGHT` exists for the\n * org axis and has no counterpart here on purpose. Host roles are compared by\n * membership in a set (`HOST_CONTENT_WRITE_ROLES`, `HOST_PUBLISH_ROLES`), and\n * an author is not \"a weaker editor\" in a way any single number can express.\n */\nexport type HostAccessRole = 'admin' | 'editor' | 'author' | 'viewer'\n\n/**\n * A per-site permission key a collaborator can carry (AGL-2927, AGL-2984).\n * The host role decides what a collaborator may do to the SITE; these keys\n * decide what else they may do on it. Each is a catalog key a plugin\n * declares with host-role defaults, the same dotted key the org catalog\n * names, so one label serves both rosters.\n */\nexport type HostPermissionKey = string\n\n/**\n * Every host role, as a value — for `where('memberRoles.{uid}', 'in', …)`.\n *\n * `/hosts/{hostId}` is gated per document on `memberRoles.{uid}`, and\n * Firestore refuses to run a LIST that could return a denied document. So\n * every client query over `hosts` must carry this filter, and it must name\n * ALL the roles: a role missing from the array is a site the member owns and\n * cannot see, with no error to explain it (AGL-1145).\n *\n * Built from a `Record` rather than written as an array so that adding a role\n * to the union above fails to COMPILE here. A plain `HostAccessRole[]` would\n * happily stay short, which is the silent half of the bug.\n */\nconst HOST_ACCESS_ROLE_KEYS: Record<HostAccessRole, true> = {\n  admin: true,\n  editor: true,\n  author: true,\n  viewer: true,\n}\nexport const HOST_ACCESS_ROLES = Object.keys(\n  HOST_ACCESS_ROLE_KEYS,\n) as HostAccessRole[]\n\nexport interface AglynOrganization extends AglynDocument {\n  $id: OrgUid\n  name?: string\n  slug?: OrgSlug\n  /** Current owner; ownership can move without re-keying anything. */\n  ownerUid?: UserUid\n  /**\n   * Who CREATED the workspace — stamped once inside `createOrganization`'s\n   * transaction and mutated by nothing, `transferOrgOwnership` included\n   * (AGL-2265).\n   *\n   * `ownerUid` moves; this does not, and the difference is the whole point.\n   * The free-workspace ceiling counts the UNION of the two, so handing a\n   * workspace to an alt account, creating a fourth and taking the first one\n   * back is not a way past the limit. Denied to client writes in the rules\n   * for the same reason — a client that could clear its own attribution could\n   * mint free workspaces without limit.\n   *\n   * Absent on every org created before AGL-2265 shipped, and every reader\n   * must tolerate that: those are counted by `ownerUid` exactly as they\n   * always were.\n   */\n  createdByUid?: UserUid\n  /**\n   * Where the workspace came from (AGL-3289): its creator's acquisition\n   * record, copied by `createOrganization` at birth and naming the account it\n   * was copied from. Written by nothing else, and denied to client writes on\n   * every rules branch, for the reason `createdByUid` is: it is the\n   * platform's record about the workspace, not the workspace's about itself.\n   */\n  acquisition?: AccountAcquisition\n  /** Directory of the org's hosts (mirrors AglynOrgBilling.hosts). */\n  hosts?: Record<HostUid, true>\n\n  // Billing (mirrors AglynOrgBilling; source of truth moves here with AGL-237)\n  plan?: OrgPlan\n  entitlements?: OrgEntitlements\n  /**\n   * Per-org plugin switchboard (AGL-416): ids of plugins the workspace\n   * loads (see plugin-manager/enabled-plugins). Absent = all first-party\n   * plugins; always-on ids (base components) and the ids on for every\n   * workspace (AI) are unioned in regardless — a site switches those off for\n   * itself instead.\n   */\n  enabledPlugins?: string[]\n  seatAddons?: OrgSeatAddons\n  stripeCustomerId?: string\n  subscription?: OrgSubscription\n  suspendedAt?: ITimestamp | null\n  /** Staff-internal rationale (AGL-202). NEVER shown to the customer. */\n  suspendedReason?: string\n  /**\n   * Lockdown extensions (AGL-1501) on the shipped AGL-202 carrier — the org\n   * scope of the panic button. `suspendedReasonCode` is the enum the notice\n   * copy switches on (`security`/`billing`/`maintenance`/`manual`; absent =\n   * `manual`), `suspendedMessage` is the CUSTOMER-FACING notice body (unlike\n   * `suspendedReason`), and `suspendedUntilMs` is an optional expiry — once\n   * it passes, the suspension is inactive with no write needed (maintenance\n   * windows end on their own). Plain epoch ms, not a Timestamp, so every\n   * cache serialization reads it back unchanged. All written only by\n   * /api/admin/lockdown; normalized by `app-utils/lockdown.ts`.\n   */\n  suspendedReasonCode?: string\n  suspendedMessage?: string\n  suspendedUntilMs?: number\n  /**\n   * Whether that suspension is in force, stored for the staff list's\n   * Suspended filter (AGL-3416). See `AglynOrgBilling.suspended`.\n   */\n  suspended?: boolean\n  erasureRequestedAt?: ITimestamp | null\n  /**\n   * Scope applied to newly created datasets and media when nobody chooses\n   * (AGL-1048). `'org'` — the default and today's behavior — shares them\n   * with every site. `'host'` starts them private to the site they were\n   * created in, which is what an agency running client sites wants: safe\n   * by default rather than safe by discipline.\n   *\n   * Only meaningful when there IS a site in context. Created from the org\n   * Media or Data page there is no host to scope to, so those stay `'org'`\n   * either way.\n   */\n  defaultResourceScope?: 'org' | 'host'\n  /** The CRM's organization-wide settings (AGL-2613) — see `OrgCrmSettings`. */\n  crm?: OrgCrmSettings\n  /** The plan staff asked the workspace to move to (AGL-3466). */\n  upgradeProposal?: OrgUpgradeProposal\n}\n\n/**\n * `orgs/{orgId}/members/{uid}` — THE authorization doc: rules resolve a\n * request with this single read. Owner/admin span every host; editor and\n * viewer see `hostAccess` (or `allHosts`).\n */\nexport interface AglynOrgMember extends AglynDocument {\n  $id: UserUid\n  role?: OrgRole\n  /**\n   * Custom role reference (AGL-243): id of an `orgs/{orgId}/roles` doc\n   * whose permission map overrides the org role's defaults.\n   */\n  roleId?: string\n  /** Per-member permission overrides (AGL-243); win over every layer. */\n  permissions?: Record<string, boolean>\n  /** Org-wide host access shortcut; otherwise `hostAccess` decides. */\n  allHosts?: boolean\n  hostAccess?: Record<HostUid, HostAccessRole>\n  /**\n   * Per-site permission overrides for a COLLABORATOR (AGL-2927), keyed by\n   * the host the grant is for. Absent keys resolve by the host role's\n   * default, so a document written before this field existed reads the same\n   * as one written after it. Org-wide members are never consulted here:\n   * their org role, custom role and `permissions` map decide.\n   */\n  hostPermissions?: Record<HostUid, Partial<Record<HostPermissionKey, boolean>>>\n  /**\n   * Denormalized reach as scope tokens (AGL-1038), so rules can intersect\n   * it with a resource's `visibleTo` — they cannot derive it from\n   * `hostAccess` because the rules language has no `.map()`. Written only\n   * by `syncOrgAuthProjections`; never edit it by hand.\n   */\n  scopeTokens?: ScopeToken[]\n  /**\n   * Denormalized THREE-LAYER permission verdict, so rules can honor a custom\n   * role they cannot resolve.\n   *\n   * `roleId` points at another document and `permissions` is only the top\n   * layer, so a rule reading either alone answers a different question from\n   * the server — and reproducing the precedence in CEL needs a second\n   * cross-document get() plus correct handling of a dangling id. This is\n   * `resolveOrgPermissions(member, customRole)`, already applied.\n   *\n   * ⚠️ ABSENT IS NOT EMPTY, and the rules must never treat it as either\n   * \"everything allowed\" or \"nothing allowed\". Documents predating this\n   * field, and any written by a path that bypasses\n   * `syncOrgAuthProjections`, carry no map at all; the rules fall back to\n   * the layers they CAN read — the role and the per-member overrides — which\n   * is exactly the verdict they gave before this field existed. Written only\n   * by `syncOrgAuthProjections` and by `createOrganization`'s inline stamp;\n   * never edit it by hand.\n   */\n  resolvedPermissions?: Record<string, boolean>\n  /** Denormalized for member lists without N user lookups. */\n  displayName?: string\n  email?: string\n  invitedBy?: UserUid\n  joinedAt?: ITimestamp\n  /**\n   * Denormalized org suspension flag (AGL-210) so host writes stay a\n   * single rules read; maintained by the staff suspension API.\n   */\n  orgSuspended?: boolean\n  /**\n   * The row belongs to platform staff and takes none of the customer's seats\n   * (AGL-3466).\n   *\n   * Stamped by the server whenever it writes a row for an account that holds\n   * the `staff` claim at that moment — `createOrganization`, `upsertOrgMember`,\n   * `grantHostAccess` — and cleared on every row the account holds when the\n   * claim is revoked. Every seat counter and every seat gate skips a stamped\n   * row, so a staff member who builds a workspace for a prospect, or joins one\n   * to help, never fills the seat the customer is paying for. The rules refuse\n   * client writes to `members`, so nobody can stamp themselves.\n   */\n  staffSeat?: boolean\n}\n\n/**\n * What happens to the outgoing owner when an owner handoff is accepted\n * (AGL-3466): `stay` keeps them on as an admin, `leave` takes them off the\n * roster.\n */\nexport type OwnerHandoffPreviousOwner = 'stay' | 'leave'\n\n/** The handoff half of an owner-handoff invite (AGL-3466). */\nexport interface AglynOrgOwnerHandoff {\n  previousOwner: OwnerHandoffPreviousOwner\n}\n\n/** `orgs/{orgId}/invites/{inviteId}` — pending email invites. */\nexport interface AglynOrgInvite extends AglynDocument {\n  $id: string\n  email?: string\n  /**\n   * `owner` only on an owner-handoff invite, which always carries `handoff`\n   * beside it (AGL-3466). Every other invite is admin, editor or viewer.\n   */\n  role?: OrgRole\n  allHosts?: boolean\n  hostAccess?: Record<HostUid, HostAccessRole>\n  /**\n   * Accepting this invite moves the workspace to the invitee (AGL-3466). It\n   * reserves no seat: the owner seat moves rather than being added, and the\n   * send-time check refuses a `stay` that would need a seat the plan lacks.\n   */\n  handoff?: AglynOrgOwnerHandoff\n  /**\n   * The address belongs to an account holding the `staff` claim, checked when\n   * the invite is sent, so it reserves no seat (AGL-3466). Checked again at\n   * acceptance, against the account that actually accepts.\n   */\n  staffSeat?: boolean\n  invitedBy?: UserUid\n  createdAt?: ITimestamp\n  acceptedAt?: ITimestamp | null\n  acceptedBy?: UserUid\n}\n\n/**\n * `orgSlugs/{slug}` — transactional uniqueness reservation; created and\n * deleted only by the org APIs (Admin SDK), publicly readable so the\n * console can resolve a workspace subdomain client-side.\n */\nexport interface OrgSlugReservation {\n  orgId: OrgUid\n  /**\n   * Set when the previous holder renamed away — the tombstone that keeps old\n   * workspace URLs redirecting until somebody else wants the name.\n   */\n  movedTo?: string\n  /**\n   * Epoch millis at which a PENDING reservation lapses (AGL-2585).\n   *\n   * Present only on a workspace created by an owner whose email was not yet\n   * verified, which is every password signup: the address is held for them,\n   * not granted to them, and the hold ends unless they confirm the address.\n   * Absent means granted, and a grant never expires — so every workspace made\n   * by a verified owner, and every one that predates this field, is outside\n   * the rule entirely.\n   *\n   * Cleared by `reap-unverified-orgs` once the owner verifies. Public, like\n   * the rest of this document, which is why nothing identifying the owner is\n   * written beside it.\n   */\n  reservedUntil?: number\n}\n\n/**\n * `hostIndex/{hostId}` — server-written host → org resolver so the tenant\n * renderer and middleware find a host's org without scanning.\n */\nexport interface HostIndexEntry {\n  orgId: OrgUid\n  subdomain?: string\n}\n\n/**\n * `users/{uid}/orgs/{orgId}` — reverse index for \"my organizations\",\n * maintained transactionally with the member doc by the membership API.\n */\nexport interface UserOrgMembership extends AglynDocument {\n  $id: OrgUid\n  role?: OrgRole\n  orgName?: string\n  slug?: OrgSlug\n  /**\n   * Mirror of `isOrgWideMember(orgs/{orgId}/members/{uid})` (AGL-1032): does\n   * this membership reach the whole org, or only a list of sites?\n   *\n   * `role` alone cannot answer it — `grantHostAccess` writes `role: 'viewer'`\n   * here for a site collaborator, exactly what a genuine org-wide viewer\n   * carries, so the console could not tell them apart without a second read\n   * of the member doc on every org route. Denormalized because the console\n   * navigation guard has to be synchronous: an async answer flashes the org\n   * chrome before hiding it.\n   *\n   * ABSENT means org-wide. Rows predating the mirror carry no flag, and a\n   * missing field must never lock a real member out of their own workspace\n   * (the same legacy shape `isOrgWideMember` handles). Only an explicit\n   * `false` scopes the console — see `isOrgWideMembership`.\n   *\n   * Navigation only. The Firestore rules are the access boundary (AGL-1026);\n   * a stale mirror at worst shows a page whose reads then come back empty.\n   */\n  orgWide?: boolean\n}\n\n/**\n * `users/{uid}/hostMemberships/{hostId}` — reverse index of the sites a user\n * can reach, mirroring `hosts/{hostId}.memberRoles` (AGL-844). Denormalizes the\n * host name so the site switcher and subdomain→id routing query a user's own\n * sites, ordered and name-prefix-searched, without scanning the `hosts`\n * collection. Admin-SDK-maintained beside `memberRoles`; a best-effort\n * convenience index, never an authorization source (the rules still gate host\n * reads on `memberRoles`). NOT named `hosts` — that would collide with the\n * top-level `hosts` collection for collection-group rules/indexes.\n */\nexport interface UserHostMembership extends AglynDocument {\n  $id: HostUid\n  orgId?: OrgUid\n  subdomain?: string\n  displayName?: string\n  nameLower?: string\n  /**\n   * Mirror of the host's `seo.favicon` (AGL-1071). The site switcher renders\n   * from this projection rather than the host doc, so without the mirror it\n   * showed the generic glyph for every site — the favicon feature worked in\n   * the sites list and nowhere else. Absent when the site has none; writers\n   * must DELETE it on clear rather than omit it, since the rows are written\n   * with `{ merge: true }` and an omitted field would keep the old icon.\n   */\n  favicon?: string\n  role?: HostAccessRole\n  updatedAt?: ITimestamp\n}\n"],"names":["HOST_ACCESS_ROLE_KEYS","admin","editor","author","viewer","HOST_ACCESS_ROLES","Object","keys"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED;;;;;;CAMC,GA6DD;;;;;;;;;;;;CAYC,GACD,MAAMA,wBAAsD;IAC1DC,OAAO;IACPC,QAAQ;IACRC,QAAQ;IACRC,QAAQ;AACV;AACA,OAAO,MAAMC,oBAAoBC,OAAOC,IAAI,CAC1CP,uBACmB"}

package/src/lib/foundation/definitions/platform.types.d.ts

@@ -460,10 +460,12 @@ export interface AglynHost extends AglynDocument {
     screens?: Record<ScreenUid, ScreenSlug>;
     /**
      * The placeholder home page the site was created with (AGL-3408), while it
-     * still holds `/`. A starter applied afterwards may take the root from this
-     * screen — and only this one — leaving it as a draft; `first_publish` does
-     * not count its routing entry. Absent on sites created before it and once a
-     * starter has taken the root.
+     * is still the platform's page. A starter applied afterwards may take the
+     * root from this screen — and only this one — leaving it as a draft;
+     * `first_publish` does not count its routing entry. Absent on sites created
+     * before it, once a starter has taken the root, and once the owner has
+     * published the screen themselves, which makes it their home page
+     * (AGL-3478).
      */
     defaultHomeScreenId?: ScreenUid;
     /** Screen rendered (noindex) for unmatched paths (AGL-87). */

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 { MediaEmbeddedMetadata } from '../../app-utils/media-embedded-fields'\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  /**\n   * The site logo for the DARK scheme (AGL-3400). A wordmark drawn for a\n   * light ground — dark ink on a transparent PNG — disappears on the dark\n   * loader scrim and error screens, so a site may name a second mark for\n   * them. Unset means {@link logoUrl} serves both schemes. Read only where a\n   * scheme is known; emails, `{{host.logo}}` and the install icon stay on\n   * `logoUrl`, because a mail client paints a light ground.\n   */\n  logoDarkUrl?: 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       * The `schema.org` LocalBusiness subtype this entity publishes as —\n       * `Plumber`, `Restaurant`, `LocalBusiness` (AGL-3383).\n       *\n       * Beside `type` rather than a third value of it: `type` still\n       * answers Organization or Person for every reader that asks, and a\n       * business is an Organization. Only a value on `LOCAL_BUSINESS_TYPES`\n       * publishes; anything else, or a Person, publishes as before. The four\n       * fields below are published only when this is.\n       */\n      businessType?: string\n      /** Cities or areas the business serves, published as `areaServed`. */\n      areaServed?: string[]\n      /**\n       * Opening hours, one line per set of days — `Mo-Fr 09:00-17:00` — the\n       * syntax `schema.org`'s own `openingHours` text uses. Parsed into\n       * `openingHoursSpecification` at serialization; a line that does not\n       * read is dropped. See `parseOpeningHours`.\n       */\n      openingHours?: string\n      /** Free text, e.g. `$$` or `$100–$500`. */\n      priceRange?: string\n      /** Free text, e.g. `Cash, credit card, Zelle`. */\n      paymentAccepted?: string\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     * Search engine ownership tokens (AGL-3399), emitted by the tenant as\n     * `<meta name=\"google-site-verification\">` and `<meta name=\"msvalidate.01\">`\n     * in the head of every published page.\n     *\n     * The HTML-tag method is the only one a site on a platform subdomain can\n     * use: it has no DNS of its own and cannot upload a file to the origin.\n     * Only the tag's `content` value is stored, and the tenant re-checks it\n     * against `SEARCH_ENGINE_VERIFICATION_TOKEN_PATTERN` before emitting, so a\n     * stored value is never echoed into the head as written.\n     */\n    verification?: {\n      google?: string\n      bing?: 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  /**\n   * The placeholder home page the site was created with (AGL-3408), while it\n   * still holds `/`. A starter applied afterwards may take the root from this\n   * screen — and only this one — leaving it as a draft; `first_publish` does\n   * not count its routing entry. Absent on sites created before it and once a\n   * starter has taken the root.\n   */\n  defaultHomeScreenId?: ScreenUid\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   * Whether the takedown above is IN FORCE, stored so the staff Sites list\n   * can filter by it with an equality (AGL-3416). `false` on every site not\n   * taken down; written beside the family by the lockdown core, and cleared\n   * on a lapsed timed takedown before the list queries it. Never an\n   * enforcement input: every enforcing reader asks the family itself.\n   */\n  suspended?: boolean\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  logoDarkUrl:\n    'The dark-scheme variant of `logoUrl` (AGL-3400). Same reasoning: ' +\n    'authored content pointing at already-public media; no gate reads it.',\n  seo:\n    'Title, description, favicon, app icon, social card, search engine ' +\n    'verification tokens and the AGL-1263 `discourageSearchEngines` switch. ' +\n    'All of it is authoring: the values end up in the page the editor is ' +\n    '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 diff on top of the picked theme (AGL-3404: every edit is ' +\n    'one), 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  themeSelection:\n    'Which library theme the site picked (AGL-3404), written by ' +\n    '/api/hosts/theme. A label and a pointer, never an input to a decision: ' +\n    'the page renders `theme` ⊕ `themeOverride`, both already authoring ' +\n    'fields, and the route re-reads the library itself rather than trusting ' +\n    'it. A forged one can only misname the theme in the picker or file the ' +\n    'next switch\\'s stash under another entry of the same site.',\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   * The metadata the file carries INSIDE its bytes (AGL-3331) — EXIF, IPTC\n   * and XMP on a photo, a PDF's document info, an Office file's properties,\n   * a video's tags — as read by `readMediaEmbeddedMetadata`. Server-written\n   * only (at upload, or the first time the Details drawer opens) and locked\n   * in the rules; edits go INTO the file through `/api/media/metadata`,\n   * which rewrites the bytes and this record together. Distinct from\n   * `customMetadata`, which is Aglyn's own and never touches the file.\n   */\n  embeddedMetadata?: MediaEmbeddedMetadata\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 an\n * installer's provenance on something it authored, and the library shows\n * this to the user as a trust signal.\n */\nexport interface TemplateSource {\n  /**\n   * `authored` (saved on this site) and `starter` are the platform's own. Any\n   * other value is the stamp of the plugin that installed the template, as\n   * it declares it (`templateSource` in `plugins.config.json`, read through\n   * `plugin-manager/plugin-template-sources`).\n   */\n  type: 'authored' | 'starter' | (string & {})\n  /** The listing an installing plugin installed this 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 template\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","logoDarkUrl","seo","layouts","redirects","notFoundScreenId","errorScreens","maintenance","locales","defaultLocale","timeZone","theme","themeOverride","themeSelection","announcementBar","popup","business","analytics","consent","createdAt","updatedAt","HOST_UNPERSISTED_FIELDS","$id","HOST_ERROR_SCREEN_SLOTS"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GA8BD,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;AAuiBD;;;;;;;;;;;;;CAaC,GACD,OAAO,MAAMC,8BAAgE;IAC3EC,aACE,2EACA;IACFC,SACE,wEACA;IACFC,aACE,sEACA;IACFC,KACE,uEACA,4EACA,yEACA;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,4EACA,0EACA,6EACA;IACFC,gBACE,gEACA,4EACA,wEACA,4EACA,2EACA;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 { MediaEmbeddedMetadata } from '../../app-utils/media-embedded-fields'\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  /**\n   * The site logo for the DARK scheme (AGL-3400). A wordmark drawn for a\n   * light ground — dark ink on a transparent PNG — disappears on the dark\n   * loader scrim and error screens, so a site may name a second mark for\n   * them. Unset means {@link logoUrl} serves both schemes. Read only where a\n   * scheme is known; emails, `{{host.logo}}` and the install icon stay on\n   * `logoUrl`, because a mail client paints a light ground.\n   */\n  logoDarkUrl?: 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       * The `schema.org` LocalBusiness subtype this entity publishes as —\n       * `Plumber`, `Restaurant`, `LocalBusiness` (AGL-3383).\n       *\n       * Beside `type` rather than a third value of it: `type` still\n       * answers Organization or Person for every reader that asks, and a\n       * business is an Organization. Only a value on `LOCAL_BUSINESS_TYPES`\n       * publishes; anything else, or a Person, publishes as before. The four\n       * fields below are published only when this is.\n       */\n      businessType?: string\n      /** Cities or areas the business serves, published as `areaServed`. */\n      areaServed?: string[]\n      /**\n       * Opening hours, one line per set of days — `Mo-Fr 09:00-17:00` — the\n       * syntax `schema.org`'s own `openingHours` text uses. Parsed into\n       * `openingHoursSpecification` at serialization; a line that does not\n       * read is dropped. See `parseOpeningHours`.\n       */\n      openingHours?: string\n      /** Free text, e.g. `$$` or `$100–$500`. */\n      priceRange?: string\n      /** Free text, e.g. `Cash, credit card, Zelle`. */\n      paymentAccepted?: string\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     * Search engine ownership tokens (AGL-3399), emitted by the tenant as\n     * `<meta name=\"google-site-verification\">` and `<meta name=\"msvalidate.01\">`\n     * in the head of every published page.\n     *\n     * The HTML-tag method is the only one a site on a platform subdomain can\n     * use: it has no DNS of its own and cannot upload a file to the origin.\n     * Only the tag's `content` value is stored, and the tenant re-checks it\n     * against `SEARCH_ENGINE_VERIFICATION_TOKEN_PATTERN` before emitting, so a\n     * stored value is never echoed into the head as written.\n     */\n    verification?: {\n      google?: string\n      bing?: 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  /**\n   * The placeholder home page the site was created with (AGL-3408), while it\n   * is still the platform's page. A starter applied afterwards may take the\n   * root from this screen — and only this one — leaving it as a draft;\n   * `first_publish` does not count its routing entry. Absent on sites created\n   * before it, once a starter has taken the root, and once the owner has\n   * published the screen themselves, which makes it their home page\n   * (AGL-3478).\n   */\n  defaultHomeScreenId?: ScreenUid\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   * Whether the takedown above is IN FORCE, stored so the staff Sites list\n   * can filter by it with an equality (AGL-3416). `false` on every site not\n   * taken down; written beside the family by the lockdown core, and cleared\n   * on a lapsed timed takedown before the list queries it. Never an\n   * enforcement input: every enforcing reader asks the family itself.\n   */\n  suspended?: boolean\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  logoDarkUrl:\n    'The dark-scheme variant of `logoUrl` (AGL-3400). Same reasoning: ' +\n    'authored content pointing at already-public media; no gate reads it.',\n  seo:\n    'Title, description, favicon, app icon, social card, search engine ' +\n    'verification tokens and the AGL-1263 `discourageSearchEngines` switch. ' +\n    'All of it is authoring: the values end up in the page the editor is ' +\n    '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 diff on top of the picked theme (AGL-3404: every edit is ' +\n    'one), 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  themeSelection:\n    'Which library theme the site picked (AGL-3404), written by ' +\n    '/api/hosts/theme. A label and a pointer, never an input to a decision: ' +\n    'the page renders `theme` ⊕ `themeOverride`, both already authoring ' +\n    'fields, and the route re-reads the library itself rather than trusting ' +\n    'it. A forged one can only misname the theme in the picker or file the ' +\n    'next switch\\'s stash under another entry of the same site.',\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   * The metadata the file carries INSIDE its bytes (AGL-3331) — EXIF, IPTC\n   * and XMP on a photo, a PDF's document info, an Office file's properties,\n   * a video's tags — as read by `readMediaEmbeddedMetadata`. Server-written\n   * only (at upload, or the first time the Details drawer opens) and locked\n   * in the rules; edits go INTO the file through `/api/media/metadata`,\n   * which rewrites the bytes and this record together. Distinct from\n   * `customMetadata`, which is Aglyn's own and never touches the file.\n   */\n  embeddedMetadata?: MediaEmbeddedMetadata\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 an\n * installer's provenance on something it authored, and the library shows\n * this to the user as a trust signal.\n */\nexport interface TemplateSource {\n  /**\n   * `authored` (saved on this site) and `starter` are the platform's own. Any\n   * other value is the stamp of the plugin that installed the template, as\n   * it declares it (`templateSource` in `plugins.config.json`, read through\n   * `plugin-manager/plugin-template-sources`).\n   */\n  type: 'authored' | 'starter' | (string & {})\n  /** The listing an installing plugin installed this 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 template\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","logoDarkUrl","seo","layouts","redirects","notFoundScreenId","errorScreens","maintenance","locales","defaultLocale","timeZone","theme","themeOverride","themeSelection","announcementBar","popup","business","analytics","consent","createdAt","updatedAt","HOST_UNPERSISTED_FIELDS","$id","HOST_ERROR_SCREEN_SLOTS"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GA8BD,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;AAyiBD;;;;;;;;;;;;;CAaC,GACD,OAAO,MAAMC,8BAAgE;IAC3EC,aACE,2EACA;IACFC,SACE,wEACA;IACFC,aACE,sEACA;IACFC,KACE,uEACA,4EACA,yEACA;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,4EACA,0EACA,6EACA;IACFC,gBACE,gEACA,4EACA,wEACA,4EACA,2EACA;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

@@ -22,7 +22,7 @@ export * from './definitions/property-kinds';
 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, OrgCrmRoundRobin, OrgCrmSettings, OrgDiscount, OrgEntitlements, OrgFeatureFlags, OrgPlan, OrgPlanComp, OrgSeatAddons, OrgSubscription, OrgUid, } from './definitions/org-billing.types';
+export type { AglynOrgBilling, CoreOrgEntitlements, CoreOrgFeatureFlags, OrgBandwidthCap, OrgBrandingProfile, OrgCrmAssignmentRule, OrgCrmHostSettings, OrgCrmRoundRobin, OrgCrmSettings, OrgDiscount, OrgEntitlements, OrgFeatureFlags, OrgPlan, OrgPlanComp, OrgSeatAddons, OrgSubscription, OrgUid, OrgUpgradeProposal, } 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, 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';