@elytracms/next 0.0.81 → 0.0.83

package/dist/index.d.ts

@@ -1,12 +1,12 @@
 import { ComponentType, ReactNode } from 'react';
 import { ComponentRegistry, ComponentIssue, ComponentManifest } from '@elytracms/core/component-registry';
 export { ComponentManifest, PropField, SlotSpec, defineComponent } from '@elytracms/core/component-registry';
-import { ComponentImplementations, ResolveBinding, RelationTarget } from '@elytracms/core/runtime-renderer';
+import { ComponentImplementations, ResolveBinding, RelationTarget, DocumentBodyItem } from '@elytracms/core/runtime-renderer';
 export { ComponentImplementations, RenderAsset } from '@elytracms/core/runtime-renderer';
 import { ResolvePageResult, ResolvedAsset, Perspective, ContentClient, CacheTags, ContentDocumentSource, ResolvedDocument } from '@elytracms/core/content';
 export { Perspective } from '@elytracms/core/content';
-import { LocaleConfig, Locale, RouteRecord, RedirectRecord, CollectionDef } from '@elytracms/core/cms-core';
-export { CmsDocument, CollectionDef, FieldDef, Locale, LocaleConfig, RedirectRecord, RouteRecord, documentSchema, fallbackHomeRoutes, localeConfigSchema, mergeRouteRecords, redirectRecordSchema, routeRecordSchema } from '@elytracms/core/cms-core';
+import { LocaleConfig, Locale, RouteRecord, CollectionDef, RedirectRecord } from '@elytracms/core/cms-core';
+export { CmsDocument, CollectionDef, FieldDef, Locale, LocaleConfig, LocaleUrlPath, RedirectRecord, RouteRecord, documentSchema, fallbackHomeRoutes, localeConfigSchema, localeUrlPath, mergeRouteRecords, redirectRecordSchema, routeRecordSchema, splitLocalePath } from '@elytracms/core/cms-core';
 import { ComponentNode } from '@elytracms/core/project-graph';
 export { ComponentNode } from '@elytracms/core/project-graph';
 import { AssetRecord, PersistenceAdapter } from '@elytracms/core/persistence';
@@ -16,6 +16,7 @@ import { z } from 'zod';
 export { z } from 'zod';
 import { ImageLoader } from 'next/image';
 import { HostImageRenderer } from './host-image.js';
+import { HostComponentEntry } from '@elytracms/core/studio-core';
 
 /**
  * One host-repo component: the manifest the builder edits against plus the
@@ -169,6 +170,29 @@ interface CanvasRendererProps {
      * issue (EC-290), never a silent `#`.
      */
     links?: Record<string, string>;
+    /**
+     * The resolved document's collection-declared delivery presentation (EC-499,
+     * from the render outcome): which field(s) hold the body. Absent → the EC-458
+     * shape picker selects the body by VALUE, exactly as before.
+     */
+    presentation?: DeliveryPresentation;
+}
+/**
+ * A collection's `presentation` declaration (EC-499), resolved for delivery: the
+ * body field list normalized from `string | string[]`. Plain data — it rides the
+ * (serializable) render outcome and the RSC boundary like the baked
+ * assets/relations/links do.
+ *
+ * EC-524: this renderer applies no CHROME. It carried a `wrapper` component id
+ * briefly (never released); a detail wrapper is a page template, templates are
+ * code, and the host now supplies one from its own route file via
+ * `createCanvasRoute`'s `wrap` option. What stays here is content selection —
+ * which is exactly what makes a canvas body and a rich-text body render
+ * agnostically through the one entry point.
+ */
+interface DeliveryPresentation {
+    /** Field names whose values form the body, in render order. */
+    body?: readonly string[];
 }
 /** Default payloads: the route-bound document and the dynamic route params. */
 declare function defaultBindingPayloads(result: ResolvePageResult): BindingPayloads;
@@ -178,6 +202,15 @@ declare function defaultBindingPayloads(result: ResolvePageResult): BindingPaylo
  * the `ContentSource`).
  */
 declare function CanvasRenderer(props: CanvasRendererProps): Promise<ReactNode>;
+/**
+ * The ordered body items of a resolved document (EC-499): the values of the
+ * collection's declared `presentation.body` fields concatenated in declaration
+ * order, or — when the collection declares nothing — the EC-458 value-shape
+ * pick, unchanged. A declared field the document has no value for contributes
+ * nothing (an empty body is legitimate); a declared field holding something that
+ * is neither composition nor rich text contributes a visible fallback.
+ */
+declare function bodyItemsOf(document: Record<string, unknown> | null | undefined, presentation?: DeliveryPresentation): DocumentBodyItem[];
 
 /**
  * The content seam of the embedded runtime (EC-144, vision AD-1/AD-4): the
@@ -224,6 +257,16 @@ interface ContentSource {
      * explicit routes.
      */
     readonly routes?: readonly RouteRecord[];
+    /**
+     * The project's collection definitions (EC-499, additive) — config-owned
+     * (AD-11), already prefetched by every source that reads a schema. The route
+     * helper reads the resolved document's collection from here to honour its
+     * declared `presentation` (which field(s) hold the delivery body, and the
+     * optional detail wrapper). Optional so existing custom sources stay valid;
+     * without it every collection is treated as undeclared and the EC-458 shape
+     * picker decides, exactly as before.
+     */
+    readonly collections?: readonly CollectionDef[];
     /**
      * Data-source definitions the graph's bindings reference (EC-166 delivery,
      * additive). When present, the route helper materializes per-section list
@@ -306,13 +349,36 @@ interface MaterializedSourcePayloads {
  */
 declare function materializeSourcePayloads(input: MaterializeSourcePayloadsInput): MaterializedSourcePayloads;
 
+/**
+ * Bridge from a `PersistenceAdapter` to the synchronous `ContentLookup` the
+ * accessors (EC-143) read through: prefetch the project's collections,
+ * documents, assets, and graphs ONCE (async), then serve every accessor call
+ * synchronously from memory. This is how `apps/example-site` reads the seeded
+ * in-memory fixture project; a Convex-backed `ContentSource` (EC-145/146)
+ * replaces this bridge without touching the route helper.
+ *
+ * The assembly half is exposed separately as {@link createStaticContentSource}
+ * (EC-156): a host that already holds the prefetched data as plain values —
+ * e.g. a delivery-snapshot payload fetched over Convex's public HTTP query
+ * API — assembles the exact same `ContentSource` without faking an adapter.
+ */
 interface ContentSnapshotOptions {
     /** Route records served by `resolvePage` (EC-019). */
     routes?: readonly RouteRecord[];
     /** Redirect records served by `resolvePage` (EC-019/020). */
     redirects?: readonly RedirectRecord[];
-    /** Locale configuration; defaults to English-only. */
-    locales?: LocaleConfig;
+    /**
+     * Locale configuration — **required**, never defaulted (EC-530). The default
+     * locale is the storage key every localized value is written under, so a
+     * fabricated `en` is a data migration to undo, not a config edit: content
+     * authored under one locale and served under another, silently (EC-512
+     * measured exactly that). EC-490 made a config declaring no locales an error
+     * 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.
+     */
+    locales: LocaleConfig;
     /**
      * Data-source definitions the graph's bindings reference (EC-166): section
      * sources (`cms.section.<nodeId>`) carry their stored where/sort/limit, and
@@ -332,8 +398,8 @@ interface ContentSnapshot extends ContentSource {
  */
 interface StaticContentData {
     projectId: string;
-    /** Locale configuration; defaults to English-only. */
-    locales?: LocaleConfig;
+    /** Locale configuration — **required**, never defaulted (see EC-530 above). */
+    locales: LocaleConfig;
     /** Route records served by `resolvePage` (EC-019). */
     routes?: readonly RouteRecord[];
     /** Redirect records served by `resolvePage` (EC-019/020). */
@@ -374,53 +440,7 @@ declare function createStaticContentSource(data: StaticContentData): ContentSnap
  * request (or memoize across requests for fixture-backed sites) — accessors
  * never reach back to the adapter.
  */
-declare function createContentSnapshot(adapter: PersistenceAdapter, projectId: string, options?: ContentSnapshotOptions): Promise<ContentSnapshot>;
-
-/**
- * The locale ⇄ URL mapping, owned in ONE place (EC-486).
- *
- * The delivery host reads a request URL and derives `{ locale, path }`; the
- * sitemap goes the other way, turning an enumerated `{ locale, path }` back
- * into the URL a crawler will request. Those are inverse functions, and while
- * they lived in two files they disagreed: a page whose top-level slug happens
- * to equal a **non-default locale code** (`/de` in a project whose locales are
- * `['en','de']`, default `en`) was published to `sitemap.xml` as
- * `https://site/de`, which the host then split as *locale `de`, path `/`* and
- * 404'd. Measured — see EC-486.
- *
- * Keeping both directions here makes the round-trip checkable, which is what
- * {@link localeUrlPath} reports: some `{ locale, path }` pairs simply have **no
- * URL that addresses them**, and a caller that publishes URLs must be able to
- * tell rather than emit a link nothing serves.
- */
-/**
- * Derive the request locale from a leading URL segment (`/de/about` → locale
- * `de`, path `/about`) and return the remaining path. No prefix (or the
- * default locale's own content at root) falls back to the default locale.
- */
-declare function splitLocalePath(url: string, locales: LocaleConfig): {
-    locale: Locale;
-    path: string;
-};
-interface LocaleUrlPath {
-    /** The request path a client uses to reach `path` in `locale`. */
-    urlPath: string;
-    /**
-     * Whether {@link splitLocalePath} recovers exactly the `{ locale, path }`
-     * this was built from. `false` means the pair is **unaddressable**: every URL
-     * that could denote it is read by the host as a different locale/path pair,
-     * so the content is unreachable and the URL must not be published.
-     */
-    addressable: boolean;
-}
-/**
- * The inverse of {@link splitLocalePath}: default locale serves the root,
- * other locales get a `/<locale>` prefix — then the result is round-tripped
- * back through `splitLocalePath` so an unaddressable pair is reported rather
- * than silently emitted (AGENTS.md §4: never a fallback that hides a broken
- * state).
- */
-declare function localeUrlPath(path: string, locale: Locale, locales: LocaleConfig): LocaleUrlPath;
+declare function createContentSnapshot(adapter: PersistenceAdapter, projectId: string, options: ContentSnapshotOptions): Promise<ContentSnapshot>;
 
 /**
  * The pure half of the catch-all route helper (EC-144): URL → outcome, with
@@ -429,6 +449,43 @@ declare function localeUrlPath(path: string, locale: Locale, locales: LocaleConf
  * each outcome onto `redirect()` / `permanentRedirect()` / `notFound()` /
  * `<CanvasRenderer />`.
  */
+/** What the route helper tells a host callback about the request it is serving. */
+interface CanvasRequestInfo {
+    /** The raw request path (including any locale prefix). */
+    url: string;
+    perspective: Perspective;
+}
+/**
+ * What a host's `wrap` function is told about the request it is wrapping
+ * (EC-524 — see `CanvasRouteOptions.wrap`).
+ *
+ * Every field is something the route already had in hand at the wrap point:
+ * nothing is gathered for this seam, and nothing was invented for it.
+ */
+interface CanvasWrapContext extends CanvasRequestInfo {
+    /**
+     * The collection of the document this URL resolved to — **the branch key**.
+     * `undefined` when the resolution carried no document, so a host branching on
+     * a collection id naturally wraps nothing there (which is what the removed
+     * `presentation.wrapper` declaration did too: it only applied with a document).
+     */
+    collection?: string;
+    /**
+     * The resolved document. Verbatim the `document` prop the removed wrapper
+     * component received, so a wrapper ported to this seam needs no other source
+     * for its field-level chrome (the title, a byline, a date).
+     */
+    document: ResolvedDocument | null;
+    /**
+     * The whole resolution — the same value the `metadata` callback already
+     * receives, so this is the established host-callback argument on this route
+     * rather than a new surface. It carries `dynamicParams`, `route`,
+     * `localeFallback` and `issues` for a wrapper that needs more than the
+     * document (EC-499 recorded wanting exactly that and could not have it across
+     * a serializable declaration).
+     */
+    result: ResolvePageResult;
+}
 /** What the host's payload factory sees for one request. */
 interface CanvasPayloadContext {
     /** Accessor client bound to this request's perspective + locale. */
@@ -500,6 +557,15 @@ type CanvasPageOutcome = {
      * embedding page's href.
      */
     links: Record<string, string>;
+    /**
+     * The resolved document's collection-declared delivery presentation
+     * (EC-499): which field(s) are the render body. Plain, serializable data —
+     * handed to `<CanvasRenderer />` so ONE catch-all renders every
+     * collection's body, whatever its shape. Absent when the collection
+     * declares nothing (or the source exposes no collections), and the EC-458
+     * value-shape picker then decides exactly as before.
+     */
+    presentation?: DeliveryPresentation;
     tags: CacheTags;
 };
 /** Build the request path from a Next catch-all `slug` param. */
@@ -525,28 +591,6 @@ interface ResolveCanvasPageOptions {
  */
 declare function resolveCanvasPage(source: ContentSource, url: string, perspective: Perspective, options?: ResolveCanvasPageOptions): Promise<CanvasPageOutcome>;
 
-/**
- * Catch-all route helper (EC-144): the factory a host app calls once in
- * `app/[[...slug]]/page.tsx` to wire `resolvePage` → `<CanvasRenderer />`,
- * with redirects answered by Next's `redirect()`/`permanentRedirect()` (per
- * the route's `permanent` flag), unknown URLs answered by `notFound()` (the
- * host's 404 renders), and the perspective chosen by Next `draftMode()` —
- * draft when enabled (via the token-gated preview route), published
- * otherwise.
- *
- * With `cache` configured (EC-146), the published-perspective resolve+render
- * data work runs inside `unstable_cache`, keyed by URL and tagged with the
- * fetch-time tag set of what the response actually contained (see
- * `cache.ts`). Publishing in the studio then invalidates exactly the affected
- * entries via the signed `/api/revalidate` webhook — and while the content
- * backend is unreachable, cached entries keep serving because a cache hit
- * never invokes `loadContent`.
- */
-interface CanvasRequestInfo {
-    /** The raw request path (including any locale prefix). */
-    url: string;
-    perspective: Perspective;
-}
 interface CanvasCacheOptions {
     /**
      * Project scope prefix for every tag (`p:<scope>:…`) — must be the project
@@ -600,6 +644,38 @@ interface CanvasRouteOptions {
     onTags?: (tags: CacheTags, info: CanvasRequestInfo) => void;
     /** Override the generated `<head>` metadata for a resolved page. */
     metadata?: (result: ResolvePageResult, info: CanvasRequestInfo) => Metadata;
+    /**
+     * Wrap the rendered page in the host's own chrome (EC-524) — a detail
+     * template, a per-collection layout, a draft ribbon. Receives the rendered
+     * canvas as `children` and returns whatever should stand in its place:
+     *
+     * ```tsx
+     * elytra.canvasRoute({
+     *   wrap: (children, ctx) =>
+     *     ctx.collection === 'post' ? <PostDetail document={ctx.document}>{children}</PostDetail> : children,
+     * })
+     * ```
+     *
+     * **This is deliberately host code, not config** (owner ruling 2026-08-01):
+     * *"this sounds very much like page-templates … templates belong in code, so
+     * the wrapper is something the developer has to care about … the page-content
+     * (Canvas or Rich-Text) should render agnostically."* A collection's
+     * `presentation.body` still names WHICH field is the content — that is content
+     * selection, and it is what lets one catch-all render a canvas page and a
+     * rich-text post through the same call. What surrounds that content is the
+     * developer's implementation decision, branched here in their own file.
+     *
+     * It replaced a `presentation.wrapper` component-id STRING resolved from the
+     * canvas registry, which forced a delivery-only component to register as a
+     * pseudo-block (EC-514). A function beats that on every axis that matters: it
+     * cannot dangle, the compiler checks it, and it can branch on anything in
+     * {@link CanvasWrapContext} rather than on collection identity alone.
+     *
+     * Applied to the `render` outcome only — a redirect or a 404 never reaches it.
+     * Returning `children` unchanged is the no-op, and omitting `wrap` entirely is
+     * the default.
+     */
+    wrap?: (children: ReactNode, ctx: CanvasWrapContext) => ReactNode;
 }
 interface CanvasRouteProps {
     params: Promise<{
@@ -750,14 +826,14 @@ declare function createCanvasSitemap(options: CreateCanvasSitemapOptions): () =>
  * 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, `apps/builder/src/lib/webhooks`) always scopes with the
+ * 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 builder), so
- * `apps/builder/src/lib/webhooks/tags.ts` mirrors these formatters; tests on
+ * `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.
  */
 /** Apply the optional multi-project scope prefix to one tag. */
@@ -832,14 +908,67 @@ interface CachedEntry<T> {
  *    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: a
- * stale-while-revalidate background refresh would re-run the probe callback
- * (whose bail aborts the refresh), so this design is tag-driven only —
- * `revalidate: false` — which is exactly the AD-5 model.
+ * 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.
  */
 declare function loadCachedEntry<T>(cache: CacheWrapper, keyParts: string[], baselineTags: readonly string[], load: () => Promise<CachedEntry<T>>): Promise<CachedEntry<T>>;
 
@@ -1298,16 +1427,13 @@ declare function createPreviewDisableRoute(): PreviewRouteHandlers;
  * ```ts
  * // frontend/lib/elytra.ts — the ONE seam file
  * import { createElytraHost } from '@elytracms/next'
- * import { collections, routes } from '../../cms'
- * import { siteComponents } from '../../components'
- *
- * export const elytra = createElytraHost({
- *   slug: 'my-site',
- *   locales: { default: 'en', locales: ['en'] },
- *   collections,
- *   routes,
- *   components: siteComponents,
- * })
+ * // Read the project out of the repo's own config — `elytra.config.ts` is the
+ * // single contract surface, and importing it costs a delivery bundle nothing
+ * // (EC-532). Any other module layout works just as well; this is an example,
+ * // not a required path.
+ * import { site } from '../../elytra.config'
+ *
+ * export const elytra = createElytraHost({ ...site })
  * ```
  *
  * ```ts
@@ -1339,7 +1465,23 @@ interface ElytraHostOptions {
      * Used as the content scope when no live backend is configured.
      */
     slug: string;
-    /** Locale config — config-owned (AD-11), never read from the snapshot. */
+    /**
+     * 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
+     * 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
+     * bundle can import `elytra.config.ts` itself for zero engine modules
+     * (measured), so `createElytraHost({ ...site })` over a project exported from
+     * the config is the shortest correct answer.
+     *
+     * This used to be `{ default, locales }` against a config spelling the same
+     * 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).
+     */
     locales: LocaleConfig;
     /** CMS collection schema — config-owned (AD-11). */
     collections: readonly CollectionDef[];
@@ -1350,8 +1492,26 @@ interface ElytraHostOptions {
      * SAME modules the studio composes with). Base primitives are always
      * included; `base.Image` is swapped for `next/image` delivery by default
      * (see `image`).
+     *
+     * Typed as the CONFIG's `HostComponentEntry` (`implementation: unknown`), not
+     * the stricter {@link HostComponent}, so that `createElytraHost({ ...site })`
+     * — the shape EC-532 makes the contract — compiles however the consumer typed
+     * their project entry. It previously demanded `ComponentType`, which meant the
+     * recommended spread worked only when the entry's implementation types
+     * survived inference: `apps/demo/elytra.config.ts` gets away with it via
+     * `satisfies`, and anyone using the engine's own published `HostComponentEntry`
+     * / `WorkspaceProjectEntry` annotation did not. Both production consumers hit
+     * exactly that and each carried one hand-restated `components` line (EC-539).
+     *
+     * What this costs, stated plainly rather than glossed: a list passed HERE no
+     * longer gets a compile-time check that each `implementation` is really a
+     * component, and nothing yet checks it at runtime either — a garbage value
+     * would reach the renderer. `defineHostComponents` keeps the strict
+     * {@link HostComponent} signature, so a hand-built list passed there directly
+     * is still checked. Closing the gap properly needs a registration issue code
+     * in the core registry; booked as EC-541 rather than smuggled in here.
      */
-    components?: readonly HostComponent[];
+    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
@@ -1390,6 +1550,12 @@ interface HostCanvasRouteOptions {
     onTags?: (tags: CacheTags, info: CanvasRequestInfo) => void;
     /** Metadata override (see `CanvasRouteOptions.metadata`). */
     metadata?: (result: ResolvePageResult, info: CanvasRequestInfo) => Metadata;
+    /**
+     * Host-owned chrome around the rendered page (EC-524) — the seam a per-
+     * collection detail template lives on. Branch on `ctx.collection` in your own
+     * route file (see `CanvasRouteOptions.wrap`).
+     */
+    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
@@ -1401,6 +1567,25 @@ interface LoadGlobalsOptions {
     /** Perspective of the chrome read. Default `'published'` (live is published-only). */
     perspective?: Perspective;
 }
+/**
+ * Which world {@link ElytraHost.loadContent} reads from.
+ *
+ * - `live` — the configured Convex deployment (published; token-gated draft).
+ * - `fallback` — the host's own `fallbackContent` world (the scaffold's seeded
+ *   starter, the demo's in-memory fixture). A legitimate, supported mode.
+ * - `empty` — no backend and no fallback: this project's structure with no
+ *   content, so every URL is a clean 404. Correct for a CI build; almost never
+ *   what a deployed site intends.
+ *
+ * The mode was decided from env long before EC-527 and readable by **nobody**,
+ * so a site serving the fallback looked identical from the outside to one
+ * reading the real deployment. Measured on the demo: `/` returned `200` while
+ * all four of EC-512's published fixtures 404'd — an agent following AGENTS.md
+ * §5 gets no signal that the thing under test was never exercised. Declared
+ * once, read here, so a host can *say* which world it is in instead of
+ * re-deriving it from `env` and drifting.
+ */
+type ElytraContentMode = 'live' | 'fallback' | 'empty';
 /** The delivery host handle {@link createElytraHost} yields. */
 interface ElytraHost {
     /**
@@ -1408,6 +1593,13 @@ interface ElytraHost {
      * studio's webhook tags), else the config slug.
      */
     contentScope: string;
+    /**
+     * Which world {@link loadContent} reads from — see {@link ElytraContentMode}.
+     * Read it to announce the mode (a boot line, a dev-only banner) rather than
+     * re-deriving it from {@link env}, which is the drift this field exists to
+     * prevent.
+     */
+    contentMode: ElytraContentMode;
     /** The resolved env bag (documented names, trimmed, empty = unset). */
     env: ElytraHostEnv;
     /** Materialized route records (a derive is run once, at factory time). */
@@ -1533,6 +1725,12 @@ declare function loadLiveContent(options: LiveContentOptions, perspective: Persp
  * document, empty composition, unknown component, or an undeclared hint all
  * answer `false` — the safe default is clearance.
  *
+ * EC-499: pass the collection's resolved `presentation` (from the render
+ * outcome) so this reads the SAME body the renderer will render when the
+ * collection declares one — otherwise the value-shape pick could name a
+ * different field than the declaration does. A body whose first item is prose
+ * rather than a block answers `false`, which is right: rich text opens no hero.
+ *
  * ```tsx
  * const outcome = client.resolvePage(path)
  * const fullBleed = firstBlockFullBleed(outcome.document, components.registry)
@@ -1541,7 +1739,7 @@ declare function loadLiveContent(options: LiveContentOptions, perspective: Persp
  *
  * The host kit wires the resolution half for you: `elytra.pageOpensFullBleed(slug)`.
  */
-declare function firstBlockFullBleed(document: Record<string, unknown> | null | undefined, registry: ComponentRegistry): boolean;
+declare function firstBlockFullBleed(document: Record<string, unknown> | null | undefined, registry: ComponentRegistry, presentation?: DeliveryPresentation): boolean;
 
 /**
  * Pure token/target logic of the draft-preview routes (EC-144), kept free of
@@ -1589,4 +1787,4 @@ declare function evaluatePreviewRequest(requestUrl: string | URL, expectedToken:
  */
 declare const PACKAGE = "@elytracms/next";
 
-export { type AssetImageLoaderOptions, type BindingPayloads, type CacheWrapper, type CacheWrapperOptions, type CachedEntry, type CanvasCacheOptions, type CanvasContentRequest, type CanvasDataSource, type CanvasPageOutcome, type CanvasPayloadContext, type CanvasPayloadsFactory, CanvasRenderer, type CanvasRendererProps, type CanvasRequestInfo, type CanvasRoute, type CanvasRouteOptions, type CanvasRouteProps, type CanvasSitemapOptions, type CanvasSitemapResult, type ContentSnapshot, type ContentSnapshotOptions, type ContentSource, type CreateCanvasSitemapOptions, type DefineHostComponentsOptions, ELYTRA_HOST_ENV_KEYS, 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 LocaleUrlPath, type MaterializeSourcePayloadsInput, type MaterializedSourcePayloads, 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 SourcePayloadError, type StaticContentData, assembleLiveSource, canvasPageMetadata, canvasSitemapEntries, collectBindingSourceIds, collectionCacheTag, createAssetImageLoader, createBindingResolver, createCanvasRoute, createCanvasSitemap, createContentSnapshot, createElytraHost, createPreviewDisableRoute, createPreviewRoute, createRevalidateRoute, createStaticContentSource, defaultBindingPayloads, defineHostComponents, docCacheTag, elytraHostImage, evaluatePreviewRequest, evaluateRevalidateRequest, firstBlockFullBleed, isSourcePayloadError, loadCachedEntry, loadLiveContent, localeUrlPath, materializeSourcePayloads, mergeCacheTags, nextCacheTags, nextImagePrimitive, pathFromSlug, projectSweepTag, resolveCanvasPage, resolveGlobals, resolveHostEnv, resolvePayloadToken, revalidatePayloadSchema, routeCacheTag, safeRedirectTarget, scopeCacheTag, signRevalidateBody, sourcePayloadError, splitLocalePath };
+export { type AssetImageLoaderOptions, type BindingPayloads, type CacheWrapper, type CacheWrapperOptions, type CachedEntry, type CanvasCacheOptions, type CanvasContentRequest, type CanvasDataSource, type CanvasPageOutcome, type CanvasPayloadContext, type CanvasPayloadsFactory, 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 MaterializeSourcePayloadsInput, type MaterializedSourcePayloads, 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 SourcePayloadError, type StaticContentData, assembleLiveSource, bodyItemsOf, canvasPageMetadata, canvasSitemapEntries, collectBindingSourceIds, collectionCacheTag, createAssetImageLoader, createBindingResolver, createCanvasRoute, createCanvasSitemap, createContentSnapshot, createElytraHost, createPreviewDisableRoute, createPreviewRoute, createRevalidateRoute, createStaticContentSource, defaultBindingPayloads, defineHostComponents, docCacheTag, elytraHostImage, evaluatePreviewRequest, evaluateRevalidateRequest, firstBlockFullBleed, isSourcePayloadError, loadCachedEntry, loadLiveContent, materializeSourcePayloads, mergeCacheTags, nextCacheTags, nextImagePrimitive, pathFromSlug, projectSweepTag, resolveCanvasPage, resolveGlobals, resolveHostEnv, resolvePayloadToken, revalidatePayloadSchema, routeCacheTag, safeRedirectTarget, scopeCacheTag, signRevalidateBody, sourcePayloadError };