@aglyn/aglyn 1.0.0-beta.233 → 1.0.0-beta.234

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aglyn/aglyn",
-  "version": "1.0.0-beta.233",
+  "version": "1.0.0-beta.234",
   "license": "Apache-2.0",
   "homepage": "https://aglyn.com",
   "repository": {
@@ -37,16 +37,16 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@aglyn/shared-data-enums": "1.0.0-beta.233",
-    "@aglyn/shared-data-mdi": "1.0.0-beta.233",
-    "@aglyn/shared-data-types": "1.0.0-beta.233",
-    "@aglyn/shared-util-email": "1.0.0-beta.233",
-    "@aglyn/shared-util-first-touch": "1.0.0-beta.233",
-    "@aglyn/shared-util-http": "1.0.0-beta.233",
-    "@aglyn/shared-util-logger": "1.0.0-beta.233",
-    "@aglyn/shared-util-timestamp": "1.0.0-beta.233",
-    "@aglyn/shared-util-tools": "1.0.0-beta.233",
-    "@aglyn/shared-util-vendor": "1.0.0-beta.233",
+    "@aglyn/shared-data-enums": "1.0.0-beta.234",
+    "@aglyn/shared-data-mdi": "1.0.0-beta.234",
+    "@aglyn/shared-data-types": "1.0.0-beta.234",
+    "@aglyn/shared-util-email": "1.0.0-beta.234",
+    "@aglyn/shared-util-first-touch": "1.0.0-beta.234",
+    "@aglyn/shared-util-http": "1.0.0-beta.234",
+    "@aglyn/shared-util-logger": "1.0.0-beta.234",
+    "@aglyn/shared-util-timestamp": "1.0.0-beta.234",
+    "@aglyn/shared-util-tools": "1.0.0-beta.234",
+    "@aglyn/shared-util-vendor": "1.0.0-beta.234",
     "@data-driven-forms/react-form-renderer": "^4.2.0",
     "@msgpack/msgpack": "^3.1.3",
     "@types/unist": "^3.0.3",

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

@@ -842,10 +842,43 @@ export interface AglynHostMedia {
      * site", which is what `visibleTo` is for.
      */
     private?: boolean;
+    /**
+     * Where a photo copied from a stock library came from (AGL-3660), written
+     * by the server ingest that copied it (`core.media-ingest`). `key` is what
+     * a site's library is searched by before a photo is copied again, so one
+     * photo is stored once per site.
+     */
+    stockPhoto?: AglynHostMediaStockSource;
     createdAt?: ITimestamp;
     updatedAt?: ITimestamp;
     deletedAt?: ITimestamp;
 }
+/**
+ * The credit an asset copied from a stock photo library keeps (AGL-3660):
+ * the library, the photo's page there, its contributor and its license.
+ * Recorded whether or not the license requires a credit shown.
+ */
+export interface AglynHostMediaStockSource {
+    /** `{provider}:{id}`: the key a site's library reuses the asset by. */
+    key: string;
+    /** The provider's id, `pixabay`. */
+    provider: string;
+    /** The library's name, `Pixabay`. */
+    providerLabel: string;
+    /** The library's own id for the photo. */
+    id: string;
+    /** The photo's page at the library. */
+    pageUrl: string;
+    photographer: string;
+    photographerUrl?: string;
+    license: string;
+    licenseUrl: string;
+    /** Whether the license requires the credit shown wherever the photo is. */
+    attributionRequired: boolean;
+    /** The search words that found it. */
+    query?: string;
+    importedAt?: ITimestamp;
+}
 /**
  * Media folder doc (AGL-171): `hosts/{hostId}/mediaFolders/{folderId}`.
  * Hierarchy/validation helpers live in `app-utils/media-folders`.

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   * 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  /**\n   * When the starter was written to a site born without it (AGL-3594): the\n   * person left the guided AI start for a blank site, or traded a guided\n   * start that did not work out for the starter. The site has made its\n   * choice, so the guided start is not offered again. Absent on every site\n   * born with the starter, which may still be offered it.\n   */\n  starterProvisionedAt?: unknown\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;AAijBD;;;;;;;;;;;;;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  /**\n   * When the starter was written to a site born without it (AGL-3594): the\n   * person left the guided AI start for a blank site, or traded a guided\n   * start that did not work out for the starter. The site has made its\n   * choice, so the guided start is not offered again. Absent on every site\n   * born with the starter, which may still be offered it.\n   */\n  starterProvisionedAt?: unknown\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  /**\n   * Where a photo copied from a stock library came from (AGL-3660), written\n   * by the server ingest that copied it (`core.media-ingest`). `key` is what\n   * a site's library is searched by before a photo is copied again, so one\n   * photo is stored once per site.\n   */\n  stockPhoto?: AglynHostMediaStockSource\n  createdAt?: ITimestamp\n  updatedAt?: ITimestamp\n  deletedAt?: ITimestamp\n}\n\n/**\n * The credit an asset copied from a stock photo library keeps (AGL-3660):\n * the library, the photo's page there, its contributor and its license.\n * Recorded whether or not the license requires a credit shown.\n */\nexport interface AglynHostMediaStockSource {\n  /** `{provider}:{id}`: the key a site's library reuses the asset by. */\n  key: string\n  /** The provider's id, `pixabay`. */\n  provider: string\n  /** The library's name, `Pixabay`. */\n  providerLabel: string\n  /** The library's own id for the photo. */\n  id: string\n  /** The photo's page at the library. */\n  pageUrl: string\n  photographer: string\n  photographerUrl?: string\n  license: string\n  licenseUrl: string\n  /** Whether the license requires the credit shown wherever the photo is. */\n  attributionRequired: boolean\n  /** The search words that found it. */\n  query?: string\n  importedAt?: 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;AAijBD;;;;;;;;;;;;;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/plugin-manager/plugin-media-ingest.d.ts

@@ -0,0 +1,87 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import type { AglynHostMediaStockSource } from '../foundation/definitions/platform.types';
+/**
+ * A SERVER PROCESS STORES A PICTURE IN A SITE'S MEDIA LIBRARY (AGL-3660).
+ *
+ * The media library takes bytes through the console's own ingress — the
+ * upload routes and the v1 API — which check the caller, the site's
+ * lockdown, the bytes' structure, the takedown list, the plan and the
+ * storage band before anything is written. A plugin that holds a picture on
+ * the server with no browser request behind it (an AI job copying a stock
+ * photo) has no route to post to. This is that route's door for it: the
+ * console registers the one implementation at boot (`instrumentation.ts`),
+ * the same direction as `core.site-cache`, and it applies the ingress checks
+ * as the member named, so a plugin never writes a media document or a
+ * Storage object itself.
+ *
+ * Images only: a server-held video or document has no caller yet.
+ *
+ * A process with no implementation answers `null` from
+ * {@link pluginMediaIngest}, and a caller keeps its own fallback.
+ */
+export interface PluginMediaIngestRequest {
+    hostId: string;
+    /**
+     * The member the asset is stored as. Their access to the site, the site's
+     * lockdown and the workspace's plan and storage band are checked as for
+     * an upload they made themselves.
+     */
+    uid: string;
+    fileName: string;
+    /** A raster image type: `image/jpeg`, `image/png`, `image/webp` or `image/gif`. */
+    contentType: string;
+    bytes: Uint8Array;
+    alt?: string;
+    description?: string;
+    /** Where a photo copied from a stock library came from (`stockPhoto` on the asset). */
+    stockPhoto?: Omit<AglynHostMediaStockSource, 'importedAt'>;
+}
+/** A stored asset, as a page names it. */
+export interface PluginMediaAsset {
+    mediaId: string;
+    /** What an `image` node's `src` holds: the asset's media reference, else its URL. */
+    src: string;
+    width?: number;
+    height?: number;
+}
+export type PluginMediaIngestResult = ({
+    ok: true;
+} & PluginMediaAsset) | {
+    ok: false;
+    status: number;
+    reason: string;
+};
+export interface PluginMediaIngest {
+    /** Stores one picture in the site's own library. */
+    ingest(request: PluginMediaIngestRequest): Promise<PluginMediaIngestResult>;
+    /**
+     * The site's live, public asset copied from a stock photo with this source
+     * key (`{provider}:{id}`), so a photo is never stored twice in one library.
+     */
+    findStockPhoto(input: {
+        hostId: string;
+        sourceKey: string;
+    }): Promise<PluginMediaAsset | null>;
+}
+/** One implementation: the app that holds the media ingress. */
+export declare const PLUGIN_MEDIA_INGEST: import("./plugin-services").PluginServiceContract<PluginMediaIngest>;
+export declare function registerPluginMediaIngest(ingest: PluginMediaIngest, options?: {
+    pluginId?: string;
+}): void;
+/** The registered ingest, or `null` in a process that registered none. */
+export declare function pluginMediaIngest(): PluginMediaIngest | null;

package/src/lib/plugin-manager/plugin-media-ingest.js

@@ -0,0 +1,34 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ import { _ as _extends } from "@swc/helpers/_/_extends";
+import { definePluginServiceContract, registerPluginService, resolvePluginService } from "./plugin-services.js";
+/** One implementation: the app that holds the media ingress. */ export const PLUGIN_MEDIA_INGEST = definePluginServiceContract('core.media-ingest', {
+    multiple: false
+});
+export function registerPluginMediaIngest(ingest, options) {
+    if (typeof (ingest == null ? void 0 : ingest.ingest) !== 'function' || typeof (ingest == null ? void 0 : ingest.findStockPhoto) !== 'function') {
+        throw new Error('a media ingest needs ingest and findStockPhoto');
+    }
+    registerPluginService(PLUGIN_MEDIA_INGEST, ingest, _extends({}, (options == null ? void 0 : options.pluginId) ? {
+        pluginId: options.pluginId
+    } : {}));
+}
+/** The registered ingest, or `null` in a process that registered none. */ export function pluginMediaIngest() {
+    var _resolvePluginService;
+    return (_resolvePluginService = resolvePluginService(PLUGIN_MEDIA_INGEST)) != null ? _resolvePluginService : null;
+}
+
+//# sourceMappingURL=plugin-media-ingest.js.map

package/src/lib/plugin-manager/plugin-media-ingest.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/plugin-manager/plugin-media-ingest.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 { AglynHostMediaStockSource } from '../foundation/definitions/platform.types'\nimport {\n  definePluginServiceContract,\n  registerPluginService,\n  resolvePluginService,\n} from './plugin-services'\n\n/**\n * A SERVER PROCESS STORES A PICTURE IN A SITE'S MEDIA LIBRARY (AGL-3660).\n *\n * The media library takes bytes through the console's own ingress — the\n * upload routes and the v1 API — which check the caller, the site's\n * lockdown, the bytes' structure, the takedown list, the plan and the\n * storage band before anything is written. A plugin that holds a picture on\n * the server with no browser request behind it (an AI job copying a stock\n * photo) has no route to post to. This is that route's door for it: the\n * console registers the one implementation at boot (`instrumentation.ts`),\n * the same direction as `core.site-cache`, and it applies the ingress checks\n * as the member named, so a plugin never writes a media document or a\n * Storage object itself.\n *\n * Images only: a server-held video or document has no caller yet.\n *\n * A process with no implementation answers `null` from\n * {@link pluginMediaIngest}, and a caller keeps its own fallback.\n */\n\nexport interface PluginMediaIngestRequest {\n  hostId: string\n  /**\n   * The member the asset is stored as. Their access to the site, the site's\n   * lockdown and the workspace's plan and storage band are checked as for\n   * an upload they made themselves.\n   */\n  uid: string\n  fileName: string\n  /** A raster image type: `image/jpeg`, `image/png`, `image/webp` or `image/gif`. */\n  contentType: string\n  bytes: Uint8Array\n  alt?: string\n  description?: string\n  /** Where a photo copied from a stock library came from (`stockPhoto` on the asset). */\n  stockPhoto?: Omit<AglynHostMediaStockSource, 'importedAt'>\n}\n\n/** A stored asset, as a page names it. */\nexport interface PluginMediaAsset {\n  mediaId: string\n  /** What an `image` node's `src` holds: the asset's media reference, else its URL. */\n  src: string\n  width?: number\n  height?: number\n}\n\nexport type PluginMediaIngestResult =\n  | ({ ok: true } & PluginMediaAsset)\n  | { ok: false; status: number; reason: string }\n\nexport interface PluginMediaIngest {\n  /** Stores one picture in the site's own library. */\n  ingest(request: PluginMediaIngestRequest): Promise<PluginMediaIngestResult>\n  /**\n   * The site's live, public asset copied from a stock photo with this source\n   * key (`{provider}:{id}`), so a photo is never stored twice in one library.\n   */\n  findStockPhoto(input: { hostId: string; sourceKey: string }): Promise<PluginMediaAsset | null>\n}\n\n/** One implementation: the app that holds the media ingress. */\nexport const PLUGIN_MEDIA_INGEST = definePluginServiceContract<PluginMediaIngest>(\n  'core.media-ingest',\n  { multiple: false },\n)\n\nexport function registerPluginMediaIngest(\n  ingest: PluginMediaIngest,\n  options?: { pluginId?: string },\n): void {\n  if (typeof ingest?.ingest !== 'function' || typeof ingest?.findStockPhoto !== 'function') {\n    throw new Error('a media ingest needs ingest and findStockPhoto')\n  }\n  registerPluginService(PLUGIN_MEDIA_INGEST, ingest, {\n    ...(options?.pluginId ? { pluginId: options.pluginId } : {}),\n  })\n}\n\n/** The registered ingest, or `null` in a process that registered none. */\nexport function pluginMediaIngest(): PluginMediaIngest | null {\n  return resolvePluginService(PLUGIN_MEDIA_INGEST) ?? null\n}\n"],"names":["definePluginServiceContract","registerPluginService","resolvePluginService","PLUGIN_MEDIA_INGEST","multiple","registerPluginMediaIngest","ingest","options","findStockPhoto","Error","pluginId","pluginMediaIngest"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC;AAGD,SACEA,2BAA2B,EAC3BC,qBAAqB,EACrBC,oBAAoB,QACf,uBAAmB;AA+D1B,8DAA8D,GAC9D,OAAO,MAAMC,sBAAsBH,4BACjC,qBACA;IAAEI,UAAU;AAAM,GACnB;AAED,OAAO,SAASC,0BACdC,MAAyB,EACzBC,OAA+B;IAE/B,IAAI,QAAOD,0BAAAA,OAAQA,MAAM,MAAK,cAAc,QAAOA,0BAAAA,OAAQE,cAAc,MAAK,YAAY;QACxF,MAAM,IAAIC,MAAM;IAClB;IACAR,sBAAsBE,qBAAqBG,QAAQ,aAC7CC,CAAAA,2BAAAA,QAASG,QAAQ,IAAG;QAAEA,UAAUH,QAAQG,QAAQ;IAAC,IAAI,CAAC;AAE9D;AAEA,wEAAwE,GACxE,OAAO,SAASC;QACPT;IAAP,QAAOA,wBAAAA,qBAAqBC,gCAArBD,wBAA6C;AACtD"}

package/src/lib/plugin-manager/stock-photo-provider.d.ts

@@ -0,0 +1,141 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * STOCK PHOTOS (AGL-3660): a library of licensed photos outside this
+ * platform that a server process searches and copies from.
+ *
+ * Core defines the contract and never names a library. A plugin registers a
+ * provider from its server declarations, and a caller — the AI site build is
+ * the first — asks for {@link stockPhotoProvider} and gets the first one
+ * this deployment configured, or `null`. Nothing here stores a photo: a
+ * caller that keeps one copies its bytes into the site's own media library
+ * (`plugin-media-ingest.ts`), because a page that names a library's own
+ * address would hotlink it, and most libraries' terms refuse that.
+ *
+ * What a provider owes its library's terms — caching searches, its rate
+ * limit, the hosts it may fetch from — it keeps inside itself, so a caller
+ * cannot get them wrong. What it owes the caller is {@link
+ * StockPhotoProvider.credit}: the words and links the asset records about
+ * where it came from, and whether the library requires them shown.
+ *
+ * A provider that is registered and not configured (its key unset) answers
+ * as absent, so a deployment without the key behaves as one without the
+ * plugin.
+ */
+/** The shape a caller wants; a provider maps it onto its own filter. */
+export type StockPhotoOrientation = 'horizontal' | 'vertical' | 'any';
+export interface StockPhotoSearchRequest {
+    /** Plain search words, at most {@link STOCK_PHOTO_QUERY_MAX_CHARS}. */
+    query: string;
+    orientation?: StockPhotoOrientation;
+    /** The smallest original a hit may have, in pixels. */
+    minWidth?: number;
+    minHeight?: number;
+    /** A hint that the photo should show people, where the library can filter by it. */
+    people?: boolean;
+}
+/** The longest query a caller sends; libraries refuse or truncate longer ones. */
+export declare const STOCK_PHOTO_QUERY_MAX_CHARS = 100;
+/** One photo a search found. */
+export interface StockPhoto {
+    /** The registering provider's id. */
+    provider: string;
+    /** The library's own id for the photo, stable across searches. */
+    id: string;
+    /** The size of the copy {@link StockPhotoProvider.download} fetches. */
+    width: number;
+    height: number;
+    /** The photo's page at the library, for the credit. */
+    pageUrl: string;
+    /** The contributor's name as the library shows it. */
+    photographer: string;
+    /** The contributor's page at the library, when it has one. */
+    photographerUrl?: string;
+    /** The library's tags, lowercase. */
+    tags: string[];
+}
+/** What an asset copied from a library records about where it came from. */
+export interface StockPhotoCredit {
+    /** The library's name, as its terms ask it written. */
+    providerLabel: string;
+    /** The license the photo is used under. */
+    license: string;
+    licenseUrl: string;
+    /** Whether the license requires the credit shown wherever the photo is. */
+    attributionRequired: boolean;
+    /** A sentence crediting the photo, for the asset's description. */
+    text: string;
+}
+export interface StockPhotoSearchResult {
+    photos: StockPhoto[];
+    /** Whether the answer came from the provider's own cache. */
+    cached: boolean;
+}
+export interface StockPhotoDownload {
+    bytes: Uint8Array;
+    /** `image/jpeg`, `image/png` or `image/webp`. */
+    contentType: string;
+}
+export interface StockPhotoProvider {
+    /** A stable id, the prefix of every source key: `pixabay`. */
+    id: string;
+    /** The library's name, in customer copy. */
+    label: string;
+    /** Whether this deployment holds what the provider needs to search. */
+    isConfigured(): boolean;
+    /**
+     * The photos matching `request`, best first. `null` when the provider
+     * cannot ask right now — its rate limit is spent, or the library failed —
+     * which a caller treats as "no photo", never as an error to retry.
+     */
+    search(request: StockPhotoSearchRequest, options?: {
+        signal?: AbortSignal;
+    }): Promise<StockPhotoSearchResult | null>;
+    /**
+     * The photo's bytes, fetched only from the library's own image hosts, or
+     * `null` when they cannot be had within `maxBytes` and the signal.
+     */
+    download(photo: StockPhoto, options: {
+        maxBytes: number;
+        signal?: AbortSignal;
+    }): Promise<StockPhotoDownload | null>;
+    /** How an asset copied from `photo` credits it. */
+    credit(photo: StockPhoto): StockPhotoCredit;
+}
+/**
+ * Many plugins may each register a library; a caller is handed the first
+ * configured one, highest priority first.
+ */
+export declare const STOCK_PHOTO_PROVIDERS: import("./plugin-services").PluginServiceContract<StockPhotoProvider>;
+/** The key an asset copied from a library is found again by: `{provider}:{id}`. */
+export declare function stockPhotoSourceKey(photo: Pick<StockPhoto, 'provider' | 'id'>): string;
+/**
+ * Registers a library. The owner is the loader's marker when a register fn
+ * is running, else `options.pluginId`; the provider's own id tells two
+ * libraries of one plugin apart.
+ */
+export declare function registerStockPhotoProvider(provider: StockPhotoProvider, options?: {
+    pluginId?: string;
+    priority?: number;
+}): void;
+/**
+ * The first registered library this deployment configured, or `null`.
+ * Synchronous and free of I/O. A provider whose configuration check throws
+ * answers as unconfigured: a stock photo is decoration, and its failure
+ * leaves the caller's own fallback standing.
+ */
+export declare function stockPhotoProvider(): StockPhotoProvider | null;

package/src/lib/plugin-manager/stock-photo-provider.js

@@ -0,0 +1,59 @@
+import { _ as _extends } from "@swc/helpers/_/_extends";
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ import { definePluginServiceContract, registerPluginService, resolvePluginServices } from "./plugin-services.js";
+/** The longest query a caller sends; libraries refuse or truncate longer ones. */ export const STOCK_PHOTO_QUERY_MAX_CHARS = 100;
+/**
+ * Many plugins may each register a library; a caller is handed the first
+ * configured one, highest priority first.
+ */ export const STOCK_PHOTO_PROVIDERS = definePluginServiceContract('core.stock-photos', {
+    multiple: true
+});
+/** The key an asset copied from a library is found again by: `{provider}:{id}`. */ export function stockPhotoSourceKey(photo) {
+    return `${photo.provider}:${photo.id}`;
+}
+/**
+ * Registers a library. The owner is the loader's marker when a register fn
+ * is running, else `options.pluginId`; the provider's own id tells two
+ * libraries of one plugin apart.
+ */ export function registerStockPhotoProvider(provider, options) {
+    var _provider_id;
+    if (!(provider == null ? void 0 : (_provider_id = provider.id) == null ? void 0 : _provider_id.trim())) throw new Error('a stock photo provider needs an id');
+    registerPluginService(STOCK_PHOTO_PROVIDERS, provider, _extends({
+        key: provider.id
+    }, (options == null ? void 0 : options.pluginId) ? {
+        pluginId: options.pluginId
+    } : {}, (options == null ? void 0 : options.priority) !== undefined ? {
+        priority: options.priority
+    } : {}));
+}
+/**
+ * The first registered library this deployment configured, or `null`.
+ * Synchronous and free of I/O. A provider whose configuration check throws
+ * answers as unconfigured: a stock photo is decoration, and its failure
+ * leaves the caller's own fallback standing.
+ */ export function stockPhotoProvider() {
+    for (const { impl } of resolvePluginServices(STOCK_PHOTO_PROVIDERS)){
+        try {
+            if (impl.isConfigured()) return impl;
+        } catch (unused) {
+        // Unconfigured, as the note says.
+        }
+    }
+    return null;
+}
+
+//# sourceMappingURL=stock-photo-provider.js.map

package/src/lib/plugin-manager/stock-photo-provider.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/plugin-manager/stock-photo-provider.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport {\n  definePluginServiceContract,\n  registerPluginService,\n  resolvePluginServices,\n} from './plugin-services'\n\n/**\n * STOCK PHOTOS (AGL-3660): a library of licensed photos outside this\n * platform that a server process searches and copies from.\n *\n * Core defines the contract and never names a library. A plugin registers a\n * provider from its server declarations, and a caller — the AI site build is\n * the first — asks for {@link stockPhotoProvider} and gets the first one\n * this deployment configured, or `null`. Nothing here stores a photo: a\n * caller that keeps one copies its bytes into the site's own media library\n * (`plugin-media-ingest.ts`), because a page that names a library's own\n * address would hotlink it, and most libraries' terms refuse that.\n *\n * What a provider owes its library's terms — caching searches, its rate\n * limit, the hosts it may fetch from — it keeps inside itself, so a caller\n * cannot get them wrong. What it owes the caller is {@link\n * StockPhotoProvider.credit}: the words and links the asset records about\n * where it came from, and whether the library requires them shown.\n *\n * A provider that is registered and not configured (its key unset) answers\n * as absent, so a deployment without the key behaves as one without the\n * plugin.\n */\n\n/** The shape a caller wants; a provider maps it onto its own filter. */\nexport type StockPhotoOrientation = 'horizontal' | 'vertical' | 'any'\n\nexport interface StockPhotoSearchRequest {\n  /** Plain search words, at most {@link STOCK_PHOTO_QUERY_MAX_CHARS}. */\n  query: string\n  orientation?: StockPhotoOrientation\n  /** The smallest original a hit may have, in pixels. */\n  minWidth?: number\n  minHeight?: number\n  /** A hint that the photo should show people, where the library can filter by it. */\n  people?: boolean\n}\n\n/** The longest query a caller sends; libraries refuse or truncate longer ones. */\nexport const STOCK_PHOTO_QUERY_MAX_CHARS = 100\n\n/** One photo a search found. */\nexport interface StockPhoto {\n  /** The registering provider's id. */\n  provider: string\n  /** The library's own id for the photo, stable across searches. */\n  id: string\n  /** The size of the copy {@link StockPhotoProvider.download} fetches. */\n  width: number\n  height: number\n  /** The photo's page at the library, for the credit. */\n  pageUrl: string\n  /** The contributor's name as the library shows it. */\n  photographer: string\n  /** The contributor's page at the library, when it has one. */\n  photographerUrl?: string\n  /** The library's tags, lowercase. */\n  tags: string[]\n}\n\n/** What an asset copied from a library records about where it came from. */\nexport interface StockPhotoCredit {\n  /** The library's name, as its terms ask it written. */\n  providerLabel: string\n  /** The license the photo is used under. */\n  license: string\n  licenseUrl: string\n  /** Whether the license requires the credit shown wherever the photo is. */\n  attributionRequired: boolean\n  /** A sentence crediting the photo, for the asset's description. */\n  text: string\n}\n\nexport interface StockPhotoSearchResult {\n  photos: StockPhoto[]\n  /** Whether the answer came from the provider's own cache. */\n  cached: boolean\n}\n\nexport interface StockPhotoDownload {\n  bytes: Uint8Array\n  /** `image/jpeg`, `image/png` or `image/webp`. */\n  contentType: string\n}\n\nexport interface StockPhotoProvider {\n  /** A stable id, the prefix of every source key: `pixabay`. */\n  id: string\n  /** The library's name, in customer copy. */\n  label: string\n  /** Whether this deployment holds what the provider needs to search. */\n  isConfigured(): boolean\n  /**\n   * The photos matching `request`, best first. `null` when the provider\n   * cannot ask right now — its rate limit is spent, or the library failed —\n   * which a caller treats as \"no photo\", never as an error to retry.\n   */\n  search(\n    request: StockPhotoSearchRequest,\n    options?: { signal?: AbortSignal },\n  ): Promise<StockPhotoSearchResult | null>\n  /**\n   * The photo's bytes, fetched only from the library's own image hosts, or\n   * `null` when they cannot be had within `maxBytes` and the signal.\n   */\n  download(\n    photo: StockPhoto,\n    options: { maxBytes: number; signal?: AbortSignal },\n  ): Promise<StockPhotoDownload | null>\n  /** How an asset copied from `photo` credits it. */\n  credit(photo: StockPhoto): StockPhotoCredit\n}\n\n/**\n * Many plugins may each register a library; a caller is handed the first\n * configured one, highest priority first.\n */\nexport const STOCK_PHOTO_PROVIDERS = definePluginServiceContract<StockPhotoProvider>(\n  'core.stock-photos',\n  { multiple: true },\n)\n\n/** The key an asset copied from a library is found again by: `{provider}:{id}`. */\nexport function stockPhotoSourceKey(photo: Pick<StockPhoto, 'provider' | 'id'>): string {\n  return `${photo.provider}:${photo.id}`\n}\n\n/**\n * Registers a library. The owner is the loader's marker when a register fn\n * is running, else `options.pluginId`; the provider's own id tells two\n * libraries of one plugin apart.\n */\nexport function registerStockPhotoProvider(\n  provider: StockPhotoProvider,\n  options?: { pluginId?: string; priority?: number },\n): void {\n  if (!provider?.id?.trim()) throw new Error('a stock photo provider needs an id')\n  registerPluginService(STOCK_PHOTO_PROVIDERS, provider, {\n    key: provider.id,\n    ...(options?.pluginId ? { pluginId: options.pluginId } : {}),\n    ...(options?.priority !== undefined ? { priority: options.priority } : {}),\n  })\n}\n\n/**\n * The first registered library this deployment configured, or `null`.\n * Synchronous and free of I/O. A provider whose configuration check throws\n * answers as unconfigured: a stock photo is decoration, and its failure\n * leaves the caller's own fallback standing.\n */\nexport function stockPhotoProvider(): StockPhotoProvider | null {\n  for (const { impl } of resolvePluginServices(STOCK_PHOTO_PROVIDERS)) {\n    try {\n      if (impl.isConfigured()) return impl\n    } catch {\n      // Unconfigured, as the note says.\n    }\n  }\n  return null\n}\n"],"names":["definePluginServiceContract","registerPluginService","resolvePluginServices","STOCK_PHOTO_QUERY_MAX_CHARS","STOCK_PHOTO_PROVIDERS","multiple","stockPhotoSourceKey","photo","provider","id","registerStockPhotoProvider","options","trim","Error","key","pluginId","priority","undefined","stockPhotoProvider","impl","isConfigured"],"mappings":";AAAA;;;;;;;;;;;;;;;CAeC,GAED,SACEA,2BAA2B,EAC3BC,qBAAqB,EACrBC,qBAAqB,QAChB,uBAAmB;AAuC1B,gFAAgF,GAChF,OAAO,MAAMC,8BAA8B,IAAG;AA0E9C;;;CAGC,GACD,OAAO,MAAMC,wBAAwBJ,4BACnC,qBACA;IAAEK,UAAU;AAAK,GAClB;AAED,iFAAiF,GACjF,OAAO,SAASC,oBAAoBC,KAA0C;IAC5E,OAAO,GAAGA,MAAMC,QAAQ,CAAC,CAAC,EAAED,MAAME,EAAE,EAAE;AACxC;AAEA;;;;CAIC,GACD,OAAO,SAASC,2BACdF,QAA4B,EAC5BG,OAAkD;QAE7CH;IAAL,IAAI,EAACA,6BAAAA,eAAAA,SAAUC,EAAE,qBAAZD,aAAcI,IAAI,KAAI,MAAM,IAAIC,MAAM;IAC3CZ,sBAAsBG,uBAAuBI,UAAU;QACrDM,KAAKN,SAASC,EAAE;OACZE,CAAAA,2BAAAA,QAASI,QAAQ,IAAG;QAAEA,UAAUJ,QAAQI,QAAQ;IAAC,IAAI,CAAC,GACtDJ,CAAAA,2BAAAA,QAASK,QAAQ,MAAKC,YAAY;QAAED,UAAUL,QAAQK,QAAQ;IAAC,IAAI,CAAC;AAE5E;AAEA;;;;;CAKC,GACD,OAAO,SAASE;IACd,KAAK,MAAM,EAAEC,IAAI,EAAE,IAAIjB,sBAAsBE,uBAAwB;QACnE,IAAI;YACF,IAAIe,KAAKC,YAAY,IAAI,OAAOD;QAClC,EAAE,eAAM;QACN,kCAAkC;QACpC;IACF;IACA,OAAO;AACT"}