@aglyn/aglyn 1.0.0-beta.143

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

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