@elytracms/next 0.0.87 → 0.0.90

package/dist/index.d.ts

@@ -6,15 +6,16 @@ export { ComponentImplementations, RenderAsset } from '@elytracms/core/runtime-r
 import { HostComponentEntry } from '@elytracms/core/studio-core';
 import { 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 { Metadata, MetadataRoute } from 'next';
-import { z } from 'zod';
-export { z } from 'zod';
+import { ResolvingMetadata, Metadata, ResolvedMetadata, MetadataRoute } from 'next';
+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';
 
 /**
@@ -259,9 +260,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 +276,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). */
@@ -443,9 +444,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;
     /**
@@ -538,13 +539,59 @@ interface CanvasRouteProps {
 interface CanvasRoute {
     /** The page component: `export default route.Page`. */
     Page: (props: CanvasRouteProps) => Promise<ReactNode>;
-    /** Next metadata hook: `export const generateMetadata = route.generateMetadata`. */
-    generateMetadata: (props: CanvasRouteProps) => Promise<Metadata>;
+    /**
+     * Next metadata hook: `export const generateMetadata = route.generateMetadata`.
+     * 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>;
 }
 /** Create the `{ Page, generateMetadata }` pair for `app/[[...slug]]/page.tsx`. */
 declare function createCanvasRoute(options: CanvasRouteOptions): CanvasRoute;
 
+/**
+ * EC-531, narrowed by EC-610 (owner ruling 3, 2026-10-23): `og:locale` ONLY in the
+ * shape Open Graph specifies — `language_TERRITORY` with an underscore (`de_DE`),
+ * where BCP 47 writes `de-DE`. The value is the page's RESOLVED locale
+ * (`result.tags.locale`, the same fact the router used to pick the content). A
+ * bare language code (`de`) is outside that format, so the kit emits nothing for
+ * it and the layout's own value stands through the merge: inventing a territory
+ * (`de` → `de_DE`) would be wrong exactly where it matters (Austria, the UK,
+ * Brazil, Latin America), and a wrong valid value looks deliberate.
+ */
+declare function openGraphLocale(locale: string): string | null;
 declare function canvasPageMetadata(result: ResolvePageResult, assets?: readonly ResolvedAsset[]): Metadata;
+/**
+ * EC-610 (owner ruling 1, 2026-10-13): **the site provides the default tags, and
+ * the page's tags are merged on top** — a value the page states overrides the
+ * site's, a value the page leaves empty falls back to the site's.
+ *
+ * Next merges metadata SHALLOWLY (read: `generate-metadata.md`, "Merging"): a
+ * page segment's `openGraph` object REPLACES the layout's whole `openGraph`, so a
+ * site-wide `type`, `siteName`, site image or `locale` declared once in the root
+ * layout never reached a canvas page, and both real sites hand-rolled around it
+ * differently (NK-039's page hook, Konditorei's post bypass). This is the one
+ * merge, applied by the canvas route to whatever builds the page's metadata (the
+ * kit's default or the host's `metadata` option): every object-valued key the
+ * page sets (`openGraph`, `twitter`, `robots`, `alternates`, …) is merged one
+ * level deep over the parent's RESOLVED value; a key the page does not set is left
+ * to Next, which inherits it from the parent as before; a scalar or array the
+ * page sets wins outright.
+ *
+ * The parent's resolved shapes spread back cleanly: Next hands `generateMetadata`
+ * a `ResolvedMetadata` whose URLs are already strings, whose `images` are
+ * descriptor objects and whose titles are `{ absolute, template }` — all of which
+ * `Metadata` accepts (Next's own "extend rather than replace" example spreads
+ * `(await parent).openGraph?.images`).
+ */
+declare function mergeMetadataOverParent(parent: ResolvedMetadata | null | undefined, page: Metadata): Metadata;
 
 /**
  * `sitemap.xml` from published routes (EC-171): walk the same route records
@@ -648,10 +695,17 @@ 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 `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 **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}.
+ *
+ * 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
  *
@@ -669,8 +723,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; every revalidation event that changes live output invalidates it
+ *   (see {@link revalidationTags} for why, until EC-515).
  *
  * ## Project scope
  *
@@ -678,16 +732,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;
@@ -701,9 +750,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
+ * every revalidation event that changes live output ({@link revalidationTags}).
  */
 declare function projectSweepTag(scope?: string): string;
 /**
@@ -712,6 +760,38 @@ declare function projectSweepTag(scope?: string): string;
  * cache entry — including the project sweep tag.
  */
 declare function nextCacheTags(tags: CacheTags, scope?: string): 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[];
+}
+/**
+ * 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) + the sweep;
+ * - `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 every live-output event also carries the project sweep — a deliberate,
+ * measured deviation from the EC-579 ruling's text, which lists the sweep only for
+ * redirects and asset removes.** A self-hosted Next host honours ONLY the baseline
+ * tags of a cache read (measured in EC-515 on Next 16.2.10 — see
+ * {@link loadCachedEntry}): a discovered `doc:` / `collection:` / `asset:` tag
+ * invalidates nothing there, silently, and Vercel is unmeasured. Until EC-515's
+ * option D makes the precise tags honoured, the precise tags alone would turn
+ * "revalidates coarsely" into "never revalidates" on every self-hosted host — so the
+ * sweep stays on every event, exactly as the Convex path sent it before. Dropping it
+ * from a publish is EC-515's job, together with the read that makes it safe.
+ */
+declare function revalidationTags(event: RevalidationEvent, project: RevalidationProject): 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
@@ -809,11 +889,11 @@ interface CachedEntry<T> {
  * 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
+ * to whatever is in `baselineTags`. {@link revalidationTags} therefore adds the
+ * project sweep to every event that changes live output (EC-579), so instant
+ * publish still *works* there, coarsely; its targeted `doc:`/`collection:`/`asset:`
+ * tags do not reach a self-hosted host's entries 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.
@@ -826,90 +906,80 @@ interface CachedEntry<T> {
 declare function loadCachedEntry<T>(cache: CacheWrapper, keyParts: string[], baselineTags: readonly string[], load: () => Promise<CachedEntry<T>>): Promise<CachedEntry<T>>;
 
 /**
- * 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;
 
@@ -1112,7 +1182,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: {
@@ -1120,14 +1192,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
@@ -1298,7 +1368,7 @@ declare function createPreviewDisableRoute(): PreviewRouteHandlers;
  * export const generateMetadata = route.generateMetadata
  *
  * // 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()
@@ -1324,7 +1394,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
@@ -1336,8 +1406,14 @@ 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[];
     /** Routes as code (AD-3/AD-11): records, or the `(collections) => records` derive. */
@@ -1384,7 +1460,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>;
     /**
@@ -1415,13 +1491,17 @@ 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 data cache (instant publish). 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). */
@@ -1458,8 +1538,9 @@ type ElytraContentMode = 'live' | 'fallback' | 'empty';
 /** The delivery host handle {@link createElytraHost} yields. */
 interface ElytraHost {
     /**
-     * The cache-tag scope: `ELYTRA_PROJECT_ID` in live mode (matching the
-     * studio's webhook tags), else the config slug.
+     * 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;
     /**
@@ -1492,11 +1573,13 @@ interface ElytraHost {
     /** 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
@@ -1542,8 +1625,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. */
@@ -1668,4 +1754,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, nextCacheTags, nextImagePrimitive, pathFromSlug, projectSweepTag, resolveCanvasPage, resolveGlobals, resolveHostEnv, revalidatePayloadSchema, routeCacheTag, safeRedirectTarget, scopeCacheTag, signRevalidateBody };
+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, 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, loadCachedEntry, loadLiveContent, mergeCacheTags, mergeMetadataOverParent, nextCacheTags, nextImagePrimitive, openGraphLocale, pathFromSlug, projectSweepTag, resolveCanvasPage, resolveGlobals, resolveHostEnv, revalidationTags, routeCacheTag, safeRedirectTarget, scopeCacheTag };