@elytracms/next 0.0.88 → 0.0.91

package/dist/index.d.ts

@@ -1,20 +1,22 @@
 import { ComponentType, ReactNode } from 'react';
-import { ComponentRegistry, ComponentIssue, ComponentManifest } from '@elytracms/core/component-registry';
+import { ComponentRegistry, ComponentManifest } from '@elytracms/core/component-registry';
 export { ComponentManifest, PropField, SlotSpec, defineComponent } from '@elytracms/core/component-registry';
 import { ComponentImplementations, RelationTarget, DocumentBodyItem } from '@elytracms/core/runtime-renderer';
 export { ComponentImplementations, RenderAsset } from '@elytracms/core/runtime-renderer';
 import { HostComponentEntry } from '@elytracms/core/studio-core';
-import { ResolvePageResult, ResolvedAsset, Perspective, ContentClient, CacheTags, ContentDocumentSource, ResolvedDocument } from '@elytracms/core/content';
+import { ContentQueryError, ResolvePageResult, ResolvedAsset, Perspective, ContentClient, CacheTags, ContentDocumentSource, ResolvedDocument } from '@elytracms/core/content';
 export { Perspective } from '@elytracms/core/content';
-import { LocaleConfig, Locale, RouteRecord, CollectionDef, RedirectRecord } from '@elytracms/core/cms-core';
-export { CmsDocument, CollectionDef, FieldDef, Locale, LocaleConfig, LocaleRequest, LocaleStrategy, LocaleUrlPath, RedirectRecord, RouteRecord, documentSchema, fallbackHomeRoutes, localeConfigSchema, localeUrlPath, mergeRouteRecords, redirectRecordSchema, resolveLocale, routeRecordSchema, splitLocalePath, textDirection } from '@elytracms/core/cms-core';
+import { LocaleConfig, Locale, RouteRecord, CollectionDef, RedirectRecord, LocaleConfigInput } from '@elytracms/core/cms-core';
+export { CmsDocument, CollectionDef, FieldDef, Locale, LocaleConfig, LocaleConfigInput, LocaleRequest, LocaleStrategy, LocaleUrlPath, RedirectRecord, RouteRecord, documentSchema, fallbackHomeRoutes, localeConfigSchema, localeUrlPath, mergeRouteRecords, parseLocaleConfig, redirectRecordSchema, resolveLocale, routeRecordSchema, splitLocalePath, textDirection } from '@elytracms/core/cms-core';
 import { AssetRecord, PersistenceAdapter } from '@elytracms/core/persistence';
 export { AssetRecord } from '@elytracms/core/persistence';
+import { Clock } from '@elytracms/core/determinism';
 import { ResolvingMetadata, Metadata, ResolvedMetadata, MetadataRoute } from 'next';
-import { z } from 'zod';
-export { z } from 'zod';
+import { RevalidationEvent } from '@elytracms/core/revalidation';
+export { REVALIDATE_SIGNATURE_HEADER, RevalidationEvent, RevalidationEventKind, revalidationEventSchema, signRevalidationBody, signedRevalidationRequest } from '@elytracms/core/revalidation';
 import { ImageLoader } from 'next/image';
 import { HostImageRenderer } from './host-image.js';
+export { z } from 'zod';
 export { ComponentNode } from '@elytracms/core/project-graph';
 
 /**
@@ -36,48 +38,43 @@ interface HostComponent {
 /**
  * The registered component surface a host app hands to `<CanvasRenderer />`
  * and the catch-all route helper: a manifest registry plus the implementation
- * map, with registration problems surfaced as structured issues (never
- * thrown — an unknown component renders the EC-015 fallback).
+ * map. Registration problems — duplicate ids, invalid ids, role claims, and
+ * `invalid-implementation` for an entry whose `implementation` is not a React
+ * component — are structured issues in `registry.issues`, the ONE record every
+ * surface reads (EC-591; never thrown — an unknown component renders the EC-015
+ * fallback). The studio registers the same config list through the same core
+ * step, so it shows exactly these issues.
  */
 interface HostComponents {
     registry: ComponentRegistry;
     implementations: ComponentImplementations;
-    /**
-     * Structural registration issues: the registry's own (duplicate ids, invalid
-     * namespaces, …) plus `invalid-implementation` for an entry whose
-     * `implementation` is not a React component (EC-541).
-     */
-    issues: readonly ComponentIssue[];
-}
-interface DefineHostComponentsOptions {
-    /**
-     * Include the platform primitives (`base.*`) that ship with
-     * `@elytracms/core/runtime-renderer`. Defaults to `true` — graphs authored in the
-     * builder assume them.
-     */
-    includeBasePrimitives?: boolean;
 }
 /**
- * Component registration API for the embedded runtime (EC-144). The host repo
- * supplies real implementations + manifests; base primitives are included by
- * default. A host implementation registered under a primitive id replaces the
- * default implementation (the manifest of the first registration wins, which
- * is the primitive's — by design, so prop schemas stay canonical).
+ * Component registration for the embedded runtime (EC-144, EC-591): the host
+ * registers EXACTLY the list it is given — the config's `components` — through
+ * core's one registration step `registerComponents`, the same step the studio
+ * registry and the preview harness call. The engine adds nothing: there are no
+ * base primitives and no override layer (EC-591 deleted `includeBasePrimitives`).
+ * The components Elytra ships are an opt-in package listed in the config like any
+ * other (`components: [...elytraComponents, ...siteComponents]`).
+ *
+ * One precedence rule: a duplicate id is refused WHOLE (`duplicate-id`, the first
+ * entry kept), so a manifest never ships with another entry's implementation.
+ * To replace a shipped component, list yours under the id and leave the shipped
+ * entry out; to swap only the Image implementation for `next/image`, wrap the
+ * list in {@link withNextImage}.
  *
  * Accepts the CONFIG's entry shape (`implementation: unknown`) rather than the
  * strict {@link HostComponent}: the config declares implementations opaquely,
  * and EC-539 made `createElytraHost({ ...site })` the contract, so a
  * compile-time check at this seam was already gone for the recommended path.
- * The check is RUNTIME instead (EC-541), through core's one registration step
- * `registerImplementations` (EC-555 — the studio registry and the preview
- * harness call the same one): a value that is not a component is
+ * The check is RUNTIME instead (EC-541): a value that is not a component is
  * recorded as an `invalid-implementation` issue naming the component id and
  * the received kind, and is NOT put into `implementations` — so the renderer
  * takes its missing-component path (a visible EC-015 fallback) instead of
  * crashing the server render on `createElement` ("Element type is invalid")
  * or, for a string, silently rendering an HTML tag. The manifest still
- * registers, so the registry's own issues (duplicate id, invalid id) for that
- * entry are reported alongside.
+ * registers, so the entry shows as broken rather than vanishing.
  *
  * One consequence of the `unknown` parameter: an INLINE
  * `implementation: (props) => …` literal no longer gets `props` contextually
@@ -86,7 +83,7 @@ interface DefineHostComponentsOptions {
  * anyway. (An overload pair was tried and does not restore it: TypeScript
  * resolves the context-sensitive literal against the wider overload.)
  */
-declare function defineHostComponents(components?: readonly HostComponentEntry[], options?: DefineHostComponentsOptions): HostComponents;
+declare function defineHostComponents(components?: readonly HostComponentEntry[]): HostComponents;
 
 /**
  * `<CanvasRenderer />` (EC-144, vision AD-1): an async React Server Component
@@ -119,9 +116,10 @@ interface CanvasRendererProps {
      * Documents each `listing` block resolved to, keyed by serialized query (EC-255,
      * from the render outcome). A ProductGrid keyed to a picked `category` reads its
      * products through this; an unknown key (or absent map) degrades to the block's
-     * own empty state — the same degradation as a missing relation.
+     * own empty state — the same degradation as a missing relation. A query that
+     * could not run is baked as its errors (EC-581 6a) and shown above the block.
      */
-    listings?: Record<string, RelationTarget[]>;
+    listings?: Record<string, BakedListing>;
     /**
      * URL paths for the documents this page's rich-text props LINK to, keyed
      * `collection:id` (EC-291, from the render outcome). A self-typed internal link
@@ -154,6 +152,14 @@ interface DeliveryPresentation {
     /** Field names whose values form the body, in render order. */
     body?: readonly string[];
 }
+/**
+ * One listing's baked result (EC-255; EC-581 6a): the documents its query matched,
+ * or the structured errors `listDocuments` refused it with. Plain data — it rides
+ * the serializable render outcome and the RSC boundary like the other bakes.
+ */
+type BakedListing = RelationTarget[] | {
+    errors: readonly ContentQueryError[];
+};
 /**
  * Render a resolved page server-side. Async so hosts can compose it like any
  * other RSC; resolution itself is synchronous (the content was prefetched by
@@ -259,9 +265,9 @@ interface ContentSnapshotOptions {
      * and EC-519 collapsed the two declarations into one; this was the last place
      * in the chain still inventing the value, and it sits in the package that
      * resolves the URLs. Hand it the project's `LocaleConfig` — the one the
-     * config declares.
+     * config declares. Parsed here (EC-580): a `default` outside `locales` throws.
      */
-    locales: LocaleConfig;
+    locales: LocaleConfigInput;
 }
 interface ContentSnapshot extends ContentSource {
     readonly projectId: string;
@@ -275,8 +281,8 @@ interface ContentSnapshot extends ContentSource {
  */
 interface StaticContentData {
     projectId: string;
-    /** Locale configuration — **required**, never defaulted (see EC-530 above). */
-    locales: LocaleConfig;
+    /** Locale configuration — **required**, never defaulted (see EC-530 above); parsed (EC-580). */
+    locales: LocaleConfigInput;
     /** Route records served by `resolvePage` (EC-019). */
     routes?: readonly RouteRecord[];
     /** Redirect records served by `resolvePage` (EC-019/020). */
@@ -394,8 +400,24 @@ type CanvasPageOutcome = {
      * cannot ride the data cache or cross the RSC boundary. A listing depends on
      * collection MEMBERSHIP (a product joining/leaving the category), so its
      * invalidation rides the per-query `listDocuments` tags merged into `tags`.
+     *
+     * EC-581 6a: a query `listDocuments` refused (a non-filterable field, an
+     * operand of the wrong type, a bad limit) is baked as `{ errors }` — the
+     * structured `ContentQueryError`s — and `<CanvasRenderer />` shows them above
+     * the block (`data-ec-fallback="invalid-listing"`), never an empty grid
+     * indistinguishable from "no matching content".
      */
-    listings: Record<string, RelationTarget[]>;
+    listings: Record<string, BakedListing>;
+    /**
+     * EC-581 6a: whether resolving this page READ THE CLOCK — a listing on it
+     * binds an operand to `now` (e.g. "events whose date is still ahead"). Such a
+     * page's content changes as time passes, not only on publish: a cached entry
+     * of it is correct for the instant it was resolved and goes stale when a
+     * listed document crosses its `now` boundary, which no publish tag covers. A
+     * cache layer must bound that entry's life (the delivery cache — EC-515 —
+     * reads this). `false` for every page with no `now`-bound listing.
+     */
+    readsNow: boolean;
     /**
      * The public URL path of every document a rich-text prop on this page LINKS
      * to (EC-291), keyed `collection:id`. Baked into the outcome (serializable) so
@@ -432,6 +454,14 @@ interface ResolveCanvasPageOptions {
      * resolution exactly, so no referenced image is ever dropped.
      */
     registry?: ComponentRegistry;
+    /**
+     * The clock a `{ now: true }` listing operand reads (EC-581 6a) — an ISO-8601
+     * UTC instant, read at most once per resolution so every listing on the page
+     * compares against the SAME instant. Defaults to the system clock; tests and
+     * fixtures inject a fixed one. Taken as a FUNCTION, read during resolution, so a
+     * `now` value is never an argument a cache keys on.
+     */
+    clock?: Clock;
 }
 /**
  * Resolve one request URL against a content source: split the locale, run
@@ -443,9 +473,9 @@ declare function resolveCanvasPage(source: ContentSource, url: string, perspecti
 
 interface CanvasCacheOptions {
     /**
-     * Project scope prefix for every tag (`p:<scope>:…`) — must be the project
-     * id the studio publishes under, so the webhook dispatcher's tags match.
-     * Omit only when the emitter also emits unscoped tags (see `cache.ts`).
+     * Project scope prefix for every tag (`p:<scope>:…`) — must be the SAME scope
+     * the revalidate receiver derives its tags with (`createRevalidateRoute`'s
+     * `scope`; the delivery kit hands its one `contentScope` to both, EC-579).
      */
     scope?: string;
     /**
@@ -462,8 +492,8 @@ interface CanvasCacheOptions {
  * prefetched source (the fixture snapshot) can ignore it; a live loader uses
  * it to fetch the draft-perspective snapshot only for draft-mode requests —
  * it must NOT call request APIs like `draftMode()` itself, because on the
- * cached published path the loader runs inside `unstable_cache`, where
- * dynamic request APIs are unavailable.
+ * cached published path the loader runs inside a `'use cache'` function, where
+ * request APIs are unavailable.
  */
 interface CanvasContentRequest {
     perspective: Perspective;
@@ -482,11 +512,12 @@ interface CanvasRouteOptions {
     /** Host component surface from `defineHostComponents`. */
     components: HostComponents;
     /**
-     * EC-146 instant publish: cache the published-perspective resolution in
-     * Next's data cache (`unstable_cache`), tagged with the response's own
-     * fetch-time tags, invalidated by the `/api/revalidate` webhook. Draft mode
-     * always bypasses this cache entirely. Tag-driven only — no time-based
-     * revalidation (the AD-5 model). Cached values are JSON-serialized plain data.
+     * EC-146 instant publish: cache the published-perspective resolution as a
+     * `'use cache'` entry tagged with the response's own fetch-time tags,
+     * invalidated by the `/api/revalidate` webhook (EC-515). Draft mode and
+     * `next dev` always bypass it. Tag-driven only — no time-based revalidation
+     * (the AD-5 model, `CANVAS_CACHE_LIFE`). Requires `cacheComponents: true` in
+     * the host's `next.config`.
      */
     cache?: CanvasCacheOptions;
     /**
@@ -543,9 +574,41 @@ interface CanvasRoute {
      * Next passes the parent segment's resolving metadata as the second argument;
      * the route merges the page's tags over it (EC-610). A caller that invokes this
      * by hand (the scaffold's `app/page.tsx`) forwards its own `parent`.
+     *
+     * `parent` is REQUIRED, not optional (EC-614): Next's webpack build validates a
+     * page's `generateMetadata` with `SecondArg<…> extends ResolvingMetadata`, and an
+     * optional parameter reads as `ResolvingMetadata | undefined`, which fails that
+     * constraint — a consumer re-exporting this hook could not `next build --webpack`
+     * on 0.0.88 (the Turbopack validator is lenient, which is how the gate missed it).
      */
-    generateMetadata: (props: CanvasRouteProps, parent?: ResolvingMetadata) => Promise<Metadata>;
+    generateMetadata: (props: CanvasRouteProps, parent: ResolvingMetadata) => Promise<Metadata>;
+    /**
+     * `export const generateStaticParams = route.generateStaticParams` — REQUIRED in
+     * the catch-all page file under `cacheComponents` (EC-515, measured on Next
+     * 16.2.10): without it, awaiting the catch-all's `params` fails `next build`
+     * ("Uncached data was accessed outside of <Suspense>"). Wrapping the page in
+     * `<Suspense>` (or a root `loading.tsx`) instead also builds, but answers every
+     * 404 and every redirect with HTTP 200 — the status is committed before the
+     * content resolves. Declaring params keeps the page blocking, so `notFound()` is a
+     * real 404 and a redirect a real 308/307.
+     *
+     * It names ONE param set: {@link CANVAS_VALIDATION_SLUG}, a sample that Next
+     * prerenders to validate the route and that resolves to not-found without
+     * reading content (the build never touches the backend for it). It fits both
+     * catch-all shapes (`[[...slug]]` and the scaffold's required `[...slug]`, which
+     * rejects an empty slug), and it is never empty (Next rejects an empty list).
+     * Every real URL renders on its first request and is cached from then on.
+     */
+    generateStaticParams: () => Promise<Array<{
+        slug: string[];
+    }>>;
 }
+/**
+ * The catch-all's build-time validation sample (see
+ * {@link CanvasRoute.generateStaticParams}). The path is reserved: the canvas
+ * route answers it with not-found and never resolves it against content.
+ */
+declare const CANVAS_VALIDATION_SLUG: readonly string[];
 /** Create the `{ Page, generateMetadata }` pair for `app/[[...slug]]/page.tsx`. */
 declare function createCanvasRoute(options: CanvasRouteOptions): CanvasRoute;
 
@@ -688,10 +751,20 @@ declare function createCanvasSitemap(options: CreateCanvasSitemapOptions): () =>
  * Cache-tag pipeline (EC-146, vision AD-5) — the pure half.
  *
  * This module defines (a) the **canonical Next.js tag string format** mapping
- * the accessor-level `CacheTags` (EC-143) onto `revalidateTag` keys, and (b)
- * the **tag-discovery caching logic** the catch-all route helper runs inside
- * `unstable_cache`. No Next.js imports — everything here is unit-testable;
- * `route.tsx` injects the real `unstable_cache` via {@link CacheWrapper}.
+ * the accessor-level `CacheTags` (EC-143) onto `cacheTag` / `revalidateTag` keys,
+ * (b) the **tag derivation for a revalidation event** ({@link revalidationTags},
+ * EC-579 — the receiver's half of the one emitter), and (c) the **pure half of the
+ * route's cache entry** (EC-515): its key ({@link canvasCacheKey}), its `cacheTag`
+ * calls ({@link entryTagCalls}), its life ({@link CANVAS_CACHE_LIFE}) and the
+ * resolver registry the module-level `'use cache'` function reads its loader from
+ * ({@link registerCanvasResolver}). No Next.js imports — everything here is
+ * unit-testable; `route.tsx` holds the one `'use cache'` function that calls
+ * `cacheTag` / `cacheLife` with these values.
+ *
+ * This is the ONE tag module: the entries are tagged here and the invalidations
+ * are derived here, from the same formatters and the same scope. Before EC-579 the
+ * format was mirrored twice more (the studio's browser dispatcher and an inline
+ * literal in the Convex emitter), and each emitter brought its own scope.
  *
  * ## Tag format
  *
@@ -709,8 +782,8 @@ declare function createCanvasSitemap(options: CreateCanvasSitemapOptions): () =>
  *   (alt/dimensions/re-upload) drops exactly the pages that baked it. Not
  *   locale-scoped — an asset record is locale-agnostic.
  * - `project` — the whole-project sweep tag attached to **every** cached
- *   entry; graph publish/unpublish emits it (a layout or route change can
- *   affect any page, so the honest v1 fallback is a full project sweep).
+ *   entry; derived for the events whose effect no narrower tag names (a redirect
+ *   change, an asset edit — see {@link revalidationTags}).
  *
  * ## Project scope
  *
@@ -718,16 +791,11 @@ declare function createCanvasSitemap(options: CreateCanvasSitemapOptions): () =>
  * `p:prj_aurora:doc:post:post-1`). The cost is a few bytes per tag and it
  * keeps multi-project hosts (one Next app serving several builder projects)
  * from cross-invalidating, so the prefix is **on whenever the host knows its
- * project id** — decision: include it. The emitter (the studio's webhook
- * dispatcher, `packages/studio/src/lib/webhooks`) always scopes with the
- * operation's `projectId`; a host that omits `cache.scope` therefore will not
- * match studio-emitted tags. Configure `cache.scope` with the same project id
- * the studio publishes under.
- *
- * The studio-side emitter cannot depend on this package (it would drag the
- * `next` peer dependency into the studio bundle), so
- * `packages/studio/src/lib/webhooks/tags.ts` mirrors these formatters; tests on
- * both sides pin the exact literal strings to keep them in lock-step.
+ * project id** — decision: include it. Since EC-579 the scope has ONE owner: the
+ * host. The webhook carries an event, not tags, and the receiver derives the
+ * tags with the same scope its cache entries are written under (the delivery
+ * kit hands both the one `contentScope`), so emitter and host can no longer
+ * disagree about it.
  */
 /** Apply the optional multi-project scope prefix to one tag. */
 declare function scopeCacheTag(tag: string, scope?: string): string;
@@ -741,9 +809,8 @@ declare function collectionCacheTag(collection: string, locale: string, scope?:
 /** Tag for one resolved route path (or redirect-chain hop) in one locale. */
 declare function routeCacheTag(pattern: string, locale: string, scope?: string): string;
 /**
- * The whole-project sweep tag. Attached to every cached page entry; emitted
- * on graph publish/unpublish (and as the emitter's honest fallback when a
- * change's precise tag set is unknowable).
+ * The whole-project sweep tag. Attached to every cached page entry; derived for
+ * the events no narrower tag covers ({@link revalidationTags}).
  */
 declare function projectSweepTag(scope?: string): string;
 /**
@@ -752,204 +819,115 @@ declare function projectSweepTag(scope?: string): string;
  * cache entry — including the project sweep tag.
  */
 declare function nextCacheTags(tags: CacheTags, scope?: string): string[];
-/**
- * The slice of `unstable_cache` the discovery logic needs, injectable so the
- * logic is testable against a faithful in-memory model (and so the test model
- * can mirror the real semantics this design depends on — see below).
- */
-interface CacheWrapperOptions {
-    tags: string[];
-    /** `false` = never expire by time (tag-driven invalidation only). */
-    revalidate: number | false;
-}
-type CacheWrapper = <T>(cb: () => Promise<T>, keyParts: string[], options: CacheWrapperOptions) => () => Promise<T>;
-/** What one cached request stores: the outcome plus its own discovered tags. */
-interface CachedEntry<T> {
-    value: T;
-    /** The Next tag strings discovered at fetch time by the run that wrote this entry. */
-    tags: string[];
+/** The receiver's own project — what its cached entries are tagged with. */
+interface RevalidationProject {
+    /** The tag scope of this host's cache entries (`p:<scope>:…`), if any. */
+    scope?: string | undefined;
+    /** Every locale this host serves — one `collection:` tag per locale. */
+    locales: readonly string[];
 }
 /**
- * Fetch-time tag discovery over `unstable_cache` — the heart of EC-146.
- *
- * The problem: `unstable_cache` fixes an entry's tags when the *wrapper* is
- * created (`options.tags` is validated and **copied** at construction time in
- * Next 15 — mutating the array during the callback does not propagate), but
- * the correct tags are only known *after* the loader resolved the page. So a
- * single wrapper can never both (a) run the loader and (b) store the result
- * under the tags that run discovered.
- *
- * The design ("resolve once, cache with discovered tags, serve cached
- * thereafter") uses two wrapper constructions per request around **one**
- * cache entry:
- *
- * 1. **Probe pass** — a wrapper keyed by `keyParts` whose callback runs the
- *    loader, captures the result + its discovered tags into the closure, and
- *    then throws an internal sentinel.
- *    - Cache **hit**: the stored entry (written by a previous request with
- *      its full discovered tags) is returned; the callback — and therefore
- *      the loader and any backend access — never runs. This is the outage
- *      story: fully cached routes keep serving when the backend is down.
- *    - Cache **miss**: the loader runs exactly once; the sentinel throw
- *      prevents `unstable_cache` from persisting the entry under the
- *      incomplete baseline tags (thrown callbacks cache nothing).
- * 2. **Write pass** (miss only) — a second wrapper is constructed *now that
- *    the tags are known*, with `options.tags` = the discovered set, same key.
- *    Its callback just returns the already-loaded entry, so the backend is
- *    not hit again; `unstable_cache` persists the entry under the full
- *    fetch-time tag set. `revalidateTag` on any of those tags drops the
- *    entry and the next request repeats the cycle with fresh data.
- *
- * The loader runs **once per revalidation cycle** (per key), never once per
- * request. Time-based revalidation is intentionally not exposed, and the reason
- * is a real hazard rather than a preference: a stale-while-revalidate background
- * refresh re-runs the probe callback, whose bail aborts the refresh, so the
- * entry is never rewritten. `revalidate: false` keeps *time* from ever putting
- * an entry into that state — which is the AD-5 model.
- *
- * **What `revalidate: false` does NOT buy (EC-515, measured on Next 16.2.10).**
- * The earlier version of this comment claimed `revalidate: false` made the SWR
- * hazard unreachable. It does not: a **tag** can put an entry into the stale
- * state too, and then exactly the aborted-refresh loop above happens. Whether it
- * does is decided by how the invalidator stamps the tag —
- * `revalidateTag(tag, 'max')` marks entries stale (365-day expiry) and triggers
- * the loop; `revalidateTag(tag, { expire: 0 })` drops them outright and does
- * not. `revalidate.ts` therefore sends `{ expire: 0 }`, and the reasoning lives
- * at that call site. Keep the two in step: this design only survives an
- * invalidation that **drops** the entry, never one that merely staleness-marks
- * it.
- *
- * Concurrency: wrappers and the captured closure are per-request, so there is
- * no cross-request mutation; two racing first requests both resolve and the
- * last write wins (deterministic content ⇒ identical entries).
- *
- * ## ⚠️ Self-hosted hosts: only the BASELINE tags invalidate (EC-515)
- *
- * **Measured on a self-hosted `next start` (Next 16.2.10, default
- * `FileSystemCache`, `.next/cache` on disk); NOT measured on Vercel.**
- *
- * Fetch-time tag discovery writes the entry with the tags the response actually
- * read — but the default self-hosted cache handler decides staleness and expiry
- * from the tags the **reading** wrapper names (`ctx.tags`, see
- * `IncrementalCache.get` / `FileSystemCache.get` for `kind: FETCH`), not from
- * the tags the entry was **stored** with. The stored tag set is only ever used
- * to decide whether to re-write the entry with a superset.
- *
- * Every read in {@link loadCachedEntry} goes through the **probe** wrapper,
- * whose tags are `baselineTags`. So on such a host:
- *
- * - revalidating a tag that is in `baselineTags` works (the route helper passes
- *   the project sweep tag, so `project` sweeps do invalidate);
- * - revalidating a *discovered* `doc:` / `collection:` / `route:` / `asset:` tag
- *   invalidates **nothing** — silently. No error, no log line, no loader run.
- *
- * Measured 2×2 that isolates it (same host, same run): a probe handed the full
- * discovered tag set up front DOES honour a `doc:` tag, and the same probe
- * handed only the baseline does not. So the tags, their formatting and the
- * webhook are all correct — the read simply never consults them.
- *
- * Consequence for a self-hosted deployment: invalidation granularity collapses
- * to whatever is in `baselineTags`. The studio's Convex write chokepoint emits
- * the project sweep on every publish, so instant publish still *works* there,
- * coarsely; the browser dispatcher's targeted `doc:`/`collection:` tag set
- * (`packages/studio/src/lib/webhooks/tags.ts`) does not reach a self-hosted host
- * at all. Vercel-hosted deployments are unaffected in practice — both consumer
- * sites were measured healthy on 2026-08-01 — which is consistent with Vercel's
- * cache handler purging by the entry's stored tags, though that has **not** been
- * measured here.
- *
- * Fixing this properly means the read must be able to name the entry's own tags,
- * which no `unstable_cache` API allows without restructuring the probe/bail
- * seam. That is a deliberate open decision — see EC-515, do not "fix" it here
- * incidentally.
+ * The tags one revalidation event invalidates on this host — sorted, deduplicated,
+ * scoped with the receiver's OWN scope, so the emitter never needs to know it.
+ *
+ * - `publish` / `unpublish` / `delete` → `doc:<collection>:<id>` (its detail page and
+ *   every cached list that contained it) + `collection:<collection>:<locale>` for
+ *   EVERY locale this host serves (list membership may have changed, and a URL
+ *   cached as not-found for a document that now exists carries it too). **No
+ *   sweep** — a publish drops exactly the entries that read the document or its
+ *   collection (EC-515);
+ * - `redirects` → the sweep (routing can change any URL; see the `redirects` trigger
+ *   in the studio's `convex/triggers.ts` for why a targeted `route:` tag is wrong);
+ * - `asset` → `asset:<id>` + the sweep (a page reading the asset through a document
+ *   asset FIELD carries no `asset:` tag — EC-566 D16, EC-589);
+ * - `probe` → nothing (the doctor's no-op ping).
+ *
+ * Why the precise tags are enough now (EC-515, option D): each route entry declares
+ * its tags with `cacheTag` from INSIDE the cached function, and Next decides an
+ * entry's staleness from the tags it was STORED with — so a `doc:` tag drops the
+ * entries that read the document, on a self-hosted host as on any other. Until
+ * then the read named only the baseline sweep (`unstable_cache` judged the
+ * reading wrapper's tags), every precise tag was inert on a self-hosted host, and
+ * every publish carried the sweep to compensate (wave-0091). Measured both ways
+ * in EC-515's harness.
  */
-declare function loadCachedEntry<T>(cache: CacheWrapper, keyParts: string[], baselineTags: readonly string[], load: () => Promise<CachedEntry<T>>): Promise<CachedEntry<T>>;
+declare function revalidationTags(event: RevalidationEvent, project: RevalidationProject): string[];
 
 /**
- * Pure signature/payload logic of the revalidation webhook receiver (EC-146),
- * kept free of Next.js imports so it is unit-testable. `revalidate.ts` wires
- * it into a route handler with `revalidateTag`.
- *
- * Scheme: HMAC-SHA256 over the **raw request body** with a shared secret,
- * carried as `x-elytra-signature: sha256=<hex>`. The emitter (the studio's
- * webhook dispatcher) signs the exact JSON string it sends; the receiver
- * verifies over the raw text *before* parsing, with a timing-safe compare.
+ * Pure request logic of the revalidation webhook receiver (EC-146), kept free of
+ * Next.js imports so it is unit-testable. `revalidate.ts` wires it into a route
+ * handler with `revalidateTag`.
+ *
+ * The wire — event schema, signer, header — is NOT declared here: it is the one
+ * module `@elytracms/core/revalidation`, shared with the emitter (the studio's
+ * Convex write chokepoint) and the doctor probe (EC-579). This file only decides
+ * the HTTP answer: auth before parsing, then the event.
  */
-/** Header carrying the HMAC signature. */
-declare const REVALIDATE_SIGNATURE_HEADER = "x-elytra-signature";
-/** The webhook body: which tags to revalidate, and why. */
-declare const revalidatePayloadSchema: z.ZodObject<{
-    projectId: z.ZodString;
-    event: z.ZodString;
-    tags: z.ZodArray<z.ZodString>;
-    timestamp: z.ZodString;
-}, z.core.$strip>;
-type RevalidatePayload = z.infer<typeof revalidatePayloadSchema>;
-/** Compute the signature header value for a raw body (emitter/test side). */
-declare function signRevalidateBody(rawBody: string, secret: string): string;
 type RevalidateEvaluation = {
     ok: true;
-    payload: RevalidatePayload;
+    event: RevalidationEvent;
 } | {
     ok: false;
     status: 400 | 401;
     message: string;
 };
 /**
- * Evaluate one webhook request: verify the HMAC first (auth before parsing),
- * then validate the payload shape.
- *
- * - unconfigured (empty) secret → 401 for every request: the endpoint stays
- *   closed until a secret is deliberately configured (mirrors EC-144 preview);
- * - missing/malformed/mismatched signature → 401 (timing-safe compare);
- * - unparseable or schema-invalid body → 400 with no tag revalidated.
+ * Evaluate one webhook request: verify the HMAC first (auth before parsing), then
+ * read the event.
+ *
+ * - unconfigured (empty) secret → 401 for every request: the endpoint stays closed
+ *   until a secret is deliberately configured (mirrors EC-144 preview);
+ * - missing/malformed/mismatched signature → 401 (constant-time verify);
+ * - unparseable or schema-invalid body → 400, nothing revalidated; a body in the
+ *   pre-EC-579 tag-list shape gets its own named 400 (an older Elytra emitter —
+ *   deploy the matching studio functions), because a version skew between the
+ *   Convex deployment and this host is the one way a correctly signed body can
+ *   arrive in the wrong shape.
  */
-declare function evaluateRevalidateRequest(rawBody: string, signature: string | null | undefined, secret: string | undefined): RevalidateEvaluation;
+declare function evaluateRevalidateRequest(rawBody: string, signature: string | null | undefined, secret: string | undefined): Promise<RevalidateEvaluation>;
 
 /**
  * Revalidation webhook route handler (EC-146): the receiving end of the
- * publish → live-in-seconds pipeline. The studio's dispatcher POSTs a signed
- * `{projectId, event, tags, timestamp}` payload; this handler verifies the
- * HMAC over the raw body and calls `revalidateTag` for each tag, dropping
- * exactly the cached entries whose fetch-time tag sets contained them.
- *
- * Server-only by construction — consumed from an App Router route handler
- * file, never from client bundles.
+ * publish → live-in-seconds pipeline. The studio's Convex write chokepoint — the ONE
+ * emitter (EC-579) — POSTs a signed EVENT (`{ kind, collection?, id? }`, the wire in
+ * `@elytracms/core/revalidation`); this handler verifies the HMAC over the raw body,
+ * derives the tags from the event with this host's OWN scope and locales
+ * (`revalidationTags`, `cache.ts`) and calls `revalidateTag` for each, dropping the
+ * cached entries whose fetch-time tag sets contained them.
+ *
+ * Server-to-server only: the emitter runs in Convex, so there is no CORS and no
+ * `OPTIONS` preflight (the studio's browser dispatcher that needed them is deleted).
+ * Server-only by construction — consumed from an App Router route handler file,
+ * never from client bundles.
  */
-interface RevalidateRouteOptions {
+interface RevalidateRouteOptions extends RevalidationProject {
     /**
      * Shared HMAC secret. An empty/undefined secret rejects every request with
      * 401 — the endpoint stays closed until deliberately configured.
      */
     secret: string | undefined;
-    /**
-     * CORS origin allowed to call this endpoint (e.g. the studio's origin).
-     * The v1 dispatcher is a browser `fetch` from the studio, and the custom
-     * signature header always triggers a CORS preflight — so cross-origin
-     * studio → host dispatch only works when this is set. Server-side emitters
-     * (the Convex action variant, CLIs, CI) need no CORS and may leave it
-     * unset. Never use `*` with a real secret-bearing deployment unless you
-     * accept that any origin may *attempt* deliveries (they still need the
-     * secret to have any effect).
-     */
-    allowOrigin?: string;
 }
 interface RevalidateRouteHandlers {
     POST(request: Request): Promise<Response>;
-    OPTIONS(): Promise<Response>;
 }
 /**
- * Create the webhook route handlers for `app/api/revalidate/route.ts`:
+ * Create the webhook route handler for `app/api/revalidate/route.ts`. Through the
+ * delivery kit it is `export const { POST } = elytra.revalidateRoute()`, which hands
+ * it the kit's own scope and locales — the ones its cached entries carry. Wiring it
+ * by hand, pass the SAME scope your canvas route caches under:
  *
  * ```ts
- * export const { POST, OPTIONS } = createRevalidateRoute({
+ * export const { POST } = createRevalidateRoute({
  *   secret: process.env.REVALIDATE_SECRET,
+ *   scope: process.env.ELYTRA_PROJECT_ID,
+ *   locales: ['en', 'de'],
  * })
  * ```
  *
- * Unsigned/invalid requests are rejected with 401 (timing-safe HMAC check,
- * see `evaluateRevalidateRequest`); valid requests revalidate every carried
- * tag and answer `{ revalidated: tags }`.
+ * Unsigned/invalid requests are rejected with 401 (constant-time HMAC verify, see
+ * `evaluateRevalidateRequest`), signed-but-unreadable ones with 400; a valid event
+ * revalidates its derived tags and answers `{ revalidated: tags }` (`[]` for the
+ * doctor's `probe`).
  */
 declare function createRevalidateRoute(options: RevalidateRouteOptions): RevalidateRouteHandlers;
 
@@ -1055,20 +1033,12 @@ interface AssetImageLoaderOptions {
  */
 declare function createAssetImageLoader(options?: AssetImageLoaderOptions): ImageLoader;
 /**
- * The `base.Image` implementation for Next.js host apps: same
- * canonical manifest, rendered optimized through {@link ElytraImage}. The
- * renderer resolves an `asset`-typed `src` (EC-195) to `{ url, width, height,
- * alt }` before this runs, so `normalizeImageSource` yields intrinsic dimensions
- * (→ no layout shift, sized variants) whether the editor picked an uploaded asset
- * or pasted a URL. `priority` opts an above-the-fold image out of lazy-loading.
- */
-/**
- * Per-deployment image-delivery options for {@link nextImagePrimitive} (EC-271).
+ * Per-deployment image-delivery options for {@link withNextImage} (EC-271).
  * The default is the host's own Next.js optimizer (Vercel) — zero config. A host
  * on a different CDN supplies its own `loader` (a plain function) to route variants
  * through that CDN instead, without touching component code.
  */
-interface NextImagePrimitiveOptions {
+interface NextImageOptions {
     /**
      * Custom `next/image` loader — the override seam for non-Vercel hosting. Omit
      * for the Vercel default (Next's own `/_next/image` optimizer). Supply a
@@ -1087,31 +1057,35 @@ interface NextImagePrimitiveOptions {
     quality?: number;
 }
 /**
- * Host registration that swaps the `base.Image` implementation
- * for {@link ElytraImage} while keeping the primitive's canonical manifest
- * (the first registration's manifest wins in `defineHostComponents` — by
- * design, so prop schemas stay canonical; the duplicate-id registry issue it
- * reports is the documented override signal, not an error):
+ * Batteries included, opted into (EC-591): return the component list with the
+ * implementation of the component that fills the `image` role swapped for
+ * `next/image` delivery ({@link ElytraImage}) — the manifest is kept, so the
+ * studio and the host still register the same component. Nothing is added to the
+ * list and nothing is registered by the engine: no image-role component in the
+ * list → the list comes back unchanged.
+ *
+ * Which entry fills the role is decided by core's one registration rule (the first
+ * valid claimant — `ComponentRegistry.roleComponent('image')`), so the swap can
+ * never land on a different entry than the one the registry resolves. Use it on
+ * the DELIVERY side only (the studio's canvas runs on Vite, where `next/image`
+ * does not exist) — the scaffold's host seam file does it in one line:
  *
  * ```ts
- * export const hostComponents = defineHostComponents([
- *   nextImagePrimitive(),                       // Vercel default optimizer
- *   // ...project components
- * ])
+ * export const elytra = createElytraHost({ ...site, components: withNextImage(site.components) })
  * ```
  *
- * Pass {@link NextImagePrimitiveOptions} to delegate image delivery to another
- * CDN (EC-271) — the v1 default is Vercel, with room to grow:
+ * Pass {@link NextImageOptions} to delegate image delivery to another CDN
+ * (EC-271) — the v1 default is Vercel, with room to grow:
  *
  * ```ts
- * nextImagePrimitive({ loader: createAssetImageLoader() })       // ?w=&q= CDN
- * nextImagePrimitive({ loader: cloudflareImageLoader })          // Cloudflare Images
+ * withNextImage(site.components, { loader: createAssetImageLoader() })   // ?w=&q= CDN
+ * withNextImage(site.components, { loader: cloudflareImageLoader })      // Cloudflare Images
  * ```
  */
-declare function nextImagePrimitive(options?: NextImagePrimitiveOptions): HostComponent;
+declare function withNextImage(components: readonly HostComponentEntry[] | undefined, options?: NextImageOptions): HostComponentEntry[];
 /** Per-deployment options for {@link elytraHostImage} (the EC-271 loader seam). */
 interface ElytraHostImageOptions {
-    /** Custom `next/image` loader for non-Vercel CDNs (see {@link NextImagePrimitiveOptions}). */
+    /** Custom `next/image` loader for non-Vercel CDNs (see {@link NextImageOptions}). */
     loader?: ImageLoader;
     /** Default quality (1–100) when a call site doesn't set one (Next defaults to 75). */
     quality?: number;
@@ -1152,7 +1126,9 @@ declare function elytraHostImage(options?: ElytraHostImageOptions): HostImageRen
  * |                       | equal the Convex deployment's own env var)           |
  * | `REVALIDATE_SECRET`   | Instant-publish webhook HMAC secret (must equal the  |
  * |                       | deployment's `CANVAS_REVALIDATE_SECRET`)             |
- * | `STUDIO_ORIGIN`       | CORS origin for the studio's browser-dispatch path   |
+ *
+ * EC-579 retired `STUDIO_ORIGIN` (the CORS origin of the studio's deleted browser
+ * dispatcher): the one emitter is the Convex deployment, server to server.
  */
 /** The kit's documented env names (single source of truth, also used in docs/tests). */
 declare const ELYTRA_HOST_ENV_KEYS: {
@@ -1160,14 +1136,12 @@ declare const ELYTRA_HOST_ENV_KEYS: {
     readonly projectId: "ELYTRA_PROJECT_ID";
     readonly draftToken: "DRAFT_PREVIEW_TOKEN";
     readonly revalidateSecret: "REVALIDATE_SECRET";
-    readonly studioOrigin: "STUDIO_ORIGIN";
 };
 interface ElytraHostEnv {
     convexUrl?: string;
     projectId?: string;
     draftToken?: string;
     revalidateSecret?: string;
-    studioOrigin?: string;
 }
 /**
  * Resolve the kit's env bag from a raw env record (`process.env` by default at
@@ -1336,9 +1310,10 @@ declare function createPreviewDisableRoute(): PreviewRouteHandlers;
  * const route = elytra.canvasRoute()
  * export default route.Page
  * export const generateMetadata = route.generateMetadata
+ * export const generateStaticParams = route.generateStaticParams // cacheComponents (EC-515)
  *
  * // app/api/revalidate/route.ts
- * export const { POST, OPTIONS } = elytra.revalidateRoute()
+ * export const { POST } = elytra.revalidateRoute()
  *
  * // app/api/draft/route.ts            — GET /api/draft?token=…&redirect=/path
  * export const { GET } = elytra.previewRoute()
@@ -1354,7 +1329,12 @@ declare function createPreviewDisableRoute(): PreviewRouteHandlers;
  * keeps ownership of project config (AD-11), host components, form endpoints,
  * and anything genuinely bespoke.
  */
-interface ElytraHostOptions {
+/**
+ * EC-581 (ratified 2b): the options are generic over the config's `collections`, so a
+ * project declared with `defineCollection` keeps its literal types through the host and
+ * `InferDocument<typeof host, 'post'>` (`@elytracms/core/cms-core`) is a delivered post.
+ */
+interface ElytraHostOptions<Collections extends readonly CollectionDef[] = readonly CollectionDef[]> {
     /**
      * The project slug (config-as-code identity, mirrors `elytra.config.ts`).
      * Used as the content scope when no live backend is configured.
@@ -1364,7 +1344,7 @@ interface ElytraHostOptions {
      * Locale config — config-owned (AD-11), never read from the snapshot.
      *
      * **Import it, do not restate it** (EC-519). This is the *same*
-     * {@link LocaleConfig} `elytra.config.ts` takes, so a project declares its
+     * {@link LocaleConfigInput} `elytra.config.ts` takes, so a project declares its
      * locales once and hands that one binding to both mounts. It stays a host
      * option because the engine cannot know where a repo keeps the value — but it
      * is no longer an option you have to *retype*: since EC-532 the delivery
@@ -1376,17 +1356,26 @@ interface ElytraHostOptions {
      * fact `locales` + `defaultLocale`, and in our own demo the two drifted — the
      * host said `['en']`, the config said `['en','de']`, and every `/de` URL 404'd
      * silently for weeks (EC-512).
+     *
+     * The DECLARED shape (EC-580): the kit parses it into the engine's `LocaleConfig`
+     * where every content source is assembled (`createStaticContentSource` — the
+     * empty source is built at boot), so a `default` outside `locales` stops the host
+     * with a located message instead of serving — the same rule the studio's
+     * workspace gate applies to the same value.
      */
-    locales: LocaleConfig;
+    locales: LocaleConfigInput;
     /** CMS collection schema — config-owned (AD-11). */
-    collections: readonly CollectionDef[];
+    collections: Collections;
     /** Routes as code (AD-3/AD-11): records, or the `(collections) => records` derive. */
     routes: readonly RouteRecord[] | ((collections: CollectionDef[]) => RouteRecord[]);
     /**
      * The repo's page-builder components (manifest + implementation pairs — the
-     * SAME modules the studio composes with). Base primitives are always
-     * included; `base.Image` is swapped for `next/image` delivery by default
-     * (see `image`).
+     * SAME list the studio composes with, usually `site.components` via the
+     * `{ ...site }` spread). The host registers exactly this list (EC-591): the
+     * engine adds no components of its own — the shipped ones are the opt-in
+     * `@elytracms/components` package, listed in the config. For `next/image`
+     * delivery of the image-role component, pass the list through
+     * `withNextImage(site.components)` (one line, opt-in).
      *
      * Typed as the CONFIG's `HostComponentEntry` (`implementation: unknown`), not
      * the stricter {@link HostComponent}, so that `createElytraHost({ ...site })`
@@ -1403,19 +1392,13 @@ interface ElytraHostOptions {
      * component. The check is RUNTIME instead — `defineHostComponents` takes the
      * same `HostComponentEntry` shape (no cast, one signature) and tests every
      * implementation on registration; a value that is not a component becomes an
-     * `invalid-implementation` issue in `components.issues` and is withheld from
+     * `invalid-implementation` issue in `components.registry.issues` and is withheld from
      * the implementation map, so its nodes render the visible missing-component
      * fallback rather than crashing the server render. Authoring a component
      * module as the strict {@link HostComponent} keeps the compile-time check at
      * the place the implementation is written.
      */
     components?: readonly HostComponentEntry[];
-    /**
-     * `base.Image` delivery options (loader/sizes/quality — the non-Vercel CDN
-     * seam), or `false` to keep the plain-`<img>` primitive. Default: Next's own
-     * optimizer, registered out of the box.
-     */
-    image?: NextImagePrimitiveOptions | false;
     /**
      * The public base URL of the delivery site (mirrors the config's
      * `frontendUrl`) — exposed on the handle for sitemap/canonical use.
@@ -1424,7 +1407,7 @@ interface ElytraHostOptions {
     /**
      * Env bag; defaults to `process.env`. Documented names (see `host-env.ts`):
      * `ELYTRA_CONVEX_URL`, `ELYTRA_PROJECT_ID`, `DRAFT_PREVIEW_TOKEN`,
-     * `REVALIDATE_SECRET`, `STUDIO_ORIGIN`.
+     * `REVALIDATE_SECRET`.
      */
     env?: Record<string, string | undefined>;
     /**
@@ -1455,13 +1438,18 @@ interface HostCanvasRouteOptions {
      */
     wrap?: (children: ReactNode, ctx: CanvasWrapContext) => ReactNode;
     /**
-     * Tagged data cache (instant publish). Default: enabled, scoped to the
-     * kit's content scope so the studio's webhook tags match. `false` disables
-     * caching entirely; an explicit `CanvasCacheOptions` overrides the scope.
-     * The kit's {@link ElytraHost.contentMode} is always part of the entry key
-     * (EC-543) — an override can replace the scope, never drop the mode.
+     * Tagged cache entry (instant publish): one `'use cache'` entry per URL, tagged
+     * with what its resolution read (EC-515; the host enables `cacheComponents`).
+     * Always on and always scoped to the kit's {@link ElytraHost.contentScope}, with
+     * the kit's {@link ElytraHost.contentMode} in the entry key (EC-543). `false`
+     * disables caching entirely.
+     *
+     * There is no scope override (EC-579): the kit's revalidate receiver derives its
+     * tags with that same `contentScope`, so one value scopes both the entries and
+     * their invalidation. An override here was the one way left for the two to
+     * disagree — and a disagreement drops nothing, silently.
      */
-    cache?: CanvasCacheOptions | false;
+    cache?: false;
 }
 interface LoadGlobalsOptions {
     /** Perspective of the chrome read. Default `'published'` (live is published-only). */
@@ -1485,21 +1473,28 @@ interface LoadGlobalsOptions {
  * once, read here, so a host can *say* which world it is in instead of
  * re-deriving it from `env` and drifting.
  *
- * **The mode is also part of the route's data-cache key** (EC-543). A cache
- * entry outlives the process that wrote it and a hit never runs the loader, so
- * until 0.0.85 the "clean 404" above held only on a COLD cache: measured, a
- * `next start` with both env vars blanked and a warm `.next/cache` from a live
- * run answered `200` with the live world's bytes on every cached URL while
- * reporting `empty` — the wrong-world failure EC-527 removed, one layer down.
- * Keyed on the mode (`canvasCacheKey`, `cache.ts`), a world change is a cold
- * miss per URL, never a stale hit, in either direction.
+ * **The mode is also part of the route's cache-entry key** (EC-543; since EC-515
+ * an argument of the cached function). An entry can outlive the world that wrote
+ * it and a hit never runs the loader, so until 0.0.85 the "clean 404" above held
+ * only on a COLD cache: measured, a `next start` with both env vars blanked and a
+ * warm `.next/cache` from a live run answered `200` with the live world's bytes
+ * on every cached URL while reporting `empty` — the wrong-world failure EC-527
+ * removed, one layer down. Keyed on the mode (`canvasCacheKey`, `cache.ts`), a
+ * world change is a cold miss per URL, never a stale hit, in either direction.
  */
 type ElytraContentMode = 'live' | 'fallback' | 'empty';
 /** The delivery host handle {@link createElytraHost} yields. */
-interface ElytraHost {
+interface ElytraHost<Collections extends readonly CollectionDef[] = readonly CollectionDef[]> {
     /**
-     * The cache-tag scope: `ELYTRA_PROJECT_ID` in live mode (matching the
-     * studio's webhook tags), else the config slug.
+     * The config's collections, as passed (EC-581) — typed by their literals when the
+     * project declares them with `defineCollection`, so `InferDocument<typeof host, 'post'>`
+     * types a delivered post with no generation step.
+     */
+    readonly collections: Collections;
+    /**
+     * The cache-tag scope: `ELYTRA_PROJECT_ID` in live mode, else the config slug.
+     * The ONE scope of this host (EC-579): its cache entries are written under it and
+     * its revalidate receiver derives every invalidation tag with it.
      */
     contentScope: string;
     /**
@@ -1513,7 +1508,7 @@ interface ElytraHost {
     env: ElytraHostEnv;
     /** Materialized route records (a derive is run once, at factory time). */
     routes: RouteRecord[];
-    /** The registered component surface (base primitives + image swap + project components). */
+    /** The registered component surface — exactly the `components` option's list (EC-591). */
     components: HostComponents;
     /** The public base URL of the delivery site, when configured. */
     frontendUrl?: string;
@@ -1521,22 +1516,33 @@ interface ElytraHost {
      * The content loader (the seam every kit surface reads through): live
      * delivery snapshot when env is configured — published, or the token-gated
      * draft for draft-mode requests — else the fallback source.
+     *
+     * An UNCACHED read (EC-515): only the canvas route's entry caches. Under
+     * `cacheComponents`, live-mode I/O in a layout or page outside `<Suspense>` fails
+     * `next build` — call it inside a `<Suspense>`'d component (route handlers and
+     * `sitemap.ts` just render dynamically).
      */
     loadContent(request: CanvasContentRequest): Promise<ContentSource>;
     /**
      * Load + resolve the site-chrome globals (settings singleton, navigation by
      * slot alias, link/asset resolution — see `host-globals.ts`). One content
      * load per call; published perspective by default.
+     *
+     * An UNCACHED read, like {@link loadContent}: under `cacheComponents`, render the
+     * chrome that awaits it inside `<Suspense>` — and keep the canvas page OUTSIDE
+     * every boundary, or its 404s and redirects answer HTTP 200 (measured, EC-515).
      */
     loadGlobals(options?: LoadGlobalsOptions): Promise<SiteGlobals>;
     /** The catch-all canvas route pair for `app/[[...slug]]/page.tsx`. */
     canvasRoute(options?: HostCanvasRouteOptions): CanvasRoute;
     /**
-     * The instant-publish webhook handlers for `app/api/revalidate/route.ts`,
-     * wired to `REVALIDATE_SECRET` (+ `STUDIO_ORIGIN` CORS). Unset secret =
-     * endpoint closed (401), never a default secret.
+     * The instant-publish webhook handler for `app/api/revalidate/route.ts`, wired to
+     * `REVALIDATE_SECRET` and to this host's own project — {@link contentScope} and the
+     * config locales — which it derives the tags of every event with (EC-579). Unset
+     * secret = endpoint closed (401), never a default secret. Only the secret can be
+     * overridden: the scope and locales are the ones this kit's cache entries carry.
      */
-    revalidateRoute(overrides?: Partial<RevalidateRouteOptions>): RevalidateRouteHandlers;
+    revalidateRoute(overrides?: Partial<Pick<RevalidateRouteOptions, 'secret'>>): RevalidateRouteHandlers;
     /**
      * The draft-mode ENABLE route for e.g. `app/api/draft/route.ts` —
      * `GET /api/draft?token=…&redirect=/path`, gated by the ONE
@@ -1549,12 +1555,13 @@ interface ElytraHost {
     /**
      * Does the page for this catch-all `slug` OPEN full-bleed? Manifest-driven
      * (`presentation.fullBleed`, EC-368) and draft-mode aware — the host lays out
-     * header clearance from data instead of a hand-kept component-id set.
+     * header clearance from data instead of a hand-kept component-id set. An
+     * uncached read (see {@link loadContent}).
      */
     pageOpensFullBleed(slug: readonly string[] | undefined): Promise<boolean>;
 }
 /** Create the delivery host handle — see the module docs for the full wiring. */
-declare function createElytraHost(options: ElytraHostOptions): ElytraHost;
+declare function createElytraHost<const Collections extends readonly CollectionDef[]>(options: ElytraHostOptions<Collections>): ElytraHost<Collections>;
 
 /**
  * The LIVE half of the delivery host kit (EC-368): fetch the delivery snapshot
@@ -1582,8 +1589,11 @@ interface LiveContentOptions {
     /** Convex deployment URL, e.g. `https://your-deployment-123.convex.cloud`. */
     convexUrl: string;
     projectId: string;
-    /** Project locale config — config-owned (AD-11), never read from the snapshot. */
-    locales: LocaleConfig;
+    /**
+     * Project locale config — config-owned (AD-11), never read from the snapshot.
+     * The declared shape; parsed where the source is assembled (EC-580).
+     */
+    locales: LocaleConfigInput;
     /** CMS collection schema — config-owned (AD-11); drives depth-1 relation population. */
     collections: readonly CollectionDef[];
     /** Route records — config-owned (AD-3/AD-11); merged with the home fallback. */
@@ -1708,4 +1718,4 @@ declare function evaluatePreviewRequest(requestUrl: string | URL, expectedToken:
  */
 declare const PACKAGE = "@elytracms/next";
 
-export { type AssetImageLoaderOptions, type CacheWrapper, type CacheWrapperOptions, type CachedEntry, type CanvasCacheOptions, type CanvasContentRequest, type CanvasPageOutcome, CanvasRenderer, type CanvasRendererProps, type CanvasRequestInfo, type CanvasRoute, type CanvasRouteOptions, type CanvasRouteProps, type CanvasSitemapOptions, type CanvasSitemapResult, type CanvasWrapContext, type ContentSnapshot, type ContentSnapshotOptions, type ContentSource, type CreateCanvasSitemapOptions, type DefineHostComponentsOptions, type DeliveryPresentation, ELYTRA_HOST_ENV_KEYS, type ElytraContentMode, type ElytraHost, type ElytraHostEnv, type ElytraHostImageOptions, type ElytraHostOptions, ElytraImage, type ElytraImageAsset, type ElytraImageProps, type GlobalsConventions, type HostCanvasRouteOptions, type HostComponent, type HostComponents, type LiveContentOptions, type LoadGlobalsOptions, type NextImagePrimitiveOptions, PACKAGE, type PreviewEvaluation, type PreviewRouteHandlers, type PreviewRouteOptions, REVALIDATE_SIGNATURE_HEADER, type ResolveCanvasPageOptions, type ResolveGlobalsOptions, type ResolvedLink, type ResolvedNavEntry, type ResolvedNavLink, type RevalidateEvaluation, type RevalidatePayload, type RevalidateRouteHandlers, type RevalidateRouteOptions, type SiteGlobals, type SitemapParamsProvider, type SitemapRouteContext, type SitemapSkippedRoute, type StaticContentData, assembleLiveSource, bodyItemsOf, canvasPageMetadata, canvasSitemapEntries, collectionCacheTag, createAssetImageLoader, createCanvasRoute, createCanvasSitemap, createContentSnapshot, createElytraHost, createPreviewDisableRoute, createPreviewRoute, createRevalidateRoute, createStaticContentSource, defineHostComponents, docCacheTag, elytraHostImage, evaluatePreviewRequest, evaluateRevalidateRequest, firstBlockFullBleed, loadCachedEntry, loadLiveContent, mergeCacheTags, mergeMetadataOverParent, nextCacheTags, nextImagePrimitive, openGraphLocale, pathFromSlug, projectSweepTag, resolveCanvasPage, resolveGlobals, resolveHostEnv, revalidatePayloadSchema, routeCacheTag, safeRedirectTarget, scopeCacheTag, signRevalidateBody };
+export { type AssetImageLoaderOptions, type BakedListing, CANVAS_VALIDATION_SLUG, type CanvasCacheOptions, type CanvasContentRequest, type CanvasPageOutcome, CanvasRenderer, type CanvasRendererProps, type CanvasRequestInfo, type CanvasRoute, type CanvasRouteOptions, type CanvasRouteProps, type CanvasSitemapOptions, type CanvasSitemapResult, type CanvasWrapContext, type ContentSnapshot, type ContentSnapshotOptions, type ContentSource, type CreateCanvasSitemapOptions, type DeliveryPresentation, ELYTRA_HOST_ENV_KEYS, type ElytraContentMode, type ElytraHost, type ElytraHostEnv, type ElytraHostImageOptions, type ElytraHostOptions, ElytraImage, type ElytraImageAsset, type ElytraImageProps, type GlobalsConventions, type HostCanvasRouteOptions, type HostComponent, type HostComponents, type LiveContentOptions, type LoadGlobalsOptions, type NextImageOptions, PACKAGE, type PreviewEvaluation, type PreviewRouteHandlers, type PreviewRouteOptions, type ResolveCanvasPageOptions, type ResolveGlobalsOptions, type ResolvedLink, type ResolvedNavEntry, type ResolvedNavLink, type RevalidateEvaluation, type RevalidateRouteHandlers, type RevalidateRouteOptions, type RevalidationProject, type SiteGlobals, type SitemapParamsProvider, type SitemapRouteContext, type SitemapSkippedRoute, type StaticContentData, assembleLiveSource, bodyItemsOf, canvasPageMetadata, canvasSitemapEntries, collectionCacheTag, createAssetImageLoader, createCanvasRoute, createCanvasSitemap, createContentSnapshot, createElytraHost, createPreviewDisableRoute, createPreviewRoute, createRevalidateRoute, createStaticContentSource, defineHostComponents, docCacheTag, elytraHostImage, evaluatePreviewRequest, evaluateRevalidateRequest, firstBlockFullBleed, loadLiveContent, mergeCacheTags, mergeMetadataOverParent, nextCacheTags, openGraphLocale, pathFromSlug, projectSweepTag, resolveCanvasPage, resolveGlobals, resolveHostEnv, revalidationTags, routeCacheTag, safeRedirectTarget, scopeCacheTag, withNextImage };