@elytracms/next 0.0.52 → 0.0.54

package/dist/host-image.d.ts

@@ -0,0 +1,86 @@
+import { ReactNode } from 'react';
+
+/**
+ * `@elytracms/next/host-image` — the host image-delivery seam for DUAL-RENDERED
+ * project components (EC-368, from the consumer-proven EC-271 pattern).
+ *
+ * The `project.*` page-builder components are dual-rendered: the SAME module
+ * renders in the Vite studio canvas AND the Next host (AD-2/AD-11), so it may
+ * not statically import `next/image` — that would break the Vite build. And in
+ * the Next host these components render as Server Components, where React
+ * context is unavailable, so an optimized `<Image>` can't be threaded through a
+ * provider either.
+ *
+ * The seam that satisfies both: a tiny module singleton the host sets once at
+ * boot. The studio never sets it (it renders the components via the root
+ * `elytra.config`, which never imports the Next host), so the canvas keeps a
+ * plain-`<img>` fallback; the Next host injects the `ElytraImage`-backed
+ * renderer so content images go through `next/image`'s optimizer:
+ *
+ * ```ts
+ * // frontend/lib/host.ts — imported once by the catch-all route at boot
+ * import { elytraHostImage } from '@elytracms/next'
+ * import { setHostImage } from '@elytracms/next/host-image'
+ *
+ * setHostImage(elytraHostImage())
+ * ```
+ *
+ * WHEN (and whether) to register stays consumer-owned — legacy-interop windows
+ * are real: a host whose global `next/image` config is still owned by a
+ * previous stack (e.g. a Sanity-era custom loader) deliberately skips
+ * registration until the conflict clears, and its components keep the honest
+ * plain-`<img>` fallback.
+ *
+ * This module is deliberately its OWN subpath entry importing nothing but React
+ * types — safe in Vite, in RSC, and in `next.config.*`. The main
+ * `@elytracms/next` entry never imports it at runtime (that would bundle a
+ * second singleton instance into the server entry, disconnecting
+ * `setHostImage` from `getHostImage` — pinned by `package-build.test.ts`).
+ */
+/** The resolved-asset slice a host image renderer needs (mirrors `ResolvedAsset`). */
+interface HostImageAsset {
+    url: string;
+    width: number | null;
+    height: number | null;
+    alt: string | null;
+    focalPoint: {
+        x: number;
+        y: number;
+    } | null;
+}
+interface HostImageProps {
+    asset: HostImageAsset;
+    alt: string;
+    className?: string;
+    loading?: 'eager' | 'lazy';
+    /** Above-the-fold opt-out of lazy-loading (the hero image). */
+    priority?: boolean;
+    /** Responsive `sizes` hint so the optimizer serves a column-sized variant. */
+    sizes?: string;
+}
+type HostImageRenderer = (props: HostImageProps) => ReactNode;
+/** Host-only: register the optimized image renderer (called once at host boot). */
+declare function setHostImage(renderer: HostImageRenderer | null): void;
+/** The registered host renderer, or `null` in the studio canvas (plain-`<img>` fallback). */
+declare function getHostImage(): HostImageRenderer | null;
+/**
+ * The `next.config.*` `images.remotePatterns` preset for Elytra asset delivery
+ * (EC-368 image defaults): Convex file-storage serve URLs, where uploaded
+ * assets live in connected mode. Without it `next/image` refuses the remote
+ * origin and delivery images 400 — spread it into your config:
+ *
+ * ```js
+ * // next.config.mjs
+ * import { convexAssetRemotePatterns } from '@elytracms/next/host-image'
+ *
+ * const nextConfig = {
+ *   images: { remotePatterns: [...convexAssetRemotePatterns] },
+ * }
+ * ```
+ */
+declare const convexAssetRemotePatterns: readonly {
+    protocol: 'https';
+    hostname: string;
+}[];
+
+export { type HostImageAsset, type HostImageProps, type HostImageRenderer, convexAssetRemotePatterns, getHostImage, setHostImage };

package/dist/host-image.js

@@ -0,0 +1,15 @@
+// src/host-image.ts
+var hostImage = null;
+function setHostImage(renderer) {
+  hostImage = renderer;
+}
+function getHostImage() {
+  return hostImage;
+}
+var convexAssetRemotePatterns = [
+  { protocol: "https", hostname: "*.convex.cloud" }
+];
+
+export { convexAssetRemotePatterns, getHostImage, setHostImage };
+//# sourceMappingURL=host-image.js.map
+//# sourceMappingURL=host-image.js.map

package/dist/host-image.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/host-image.ts"],"names":[],"mappings":";AA8DA,IAAI,SAAA,GAAsC,IAAA;AAGnC,SAAS,aAAa,QAAA,EAA0C;AACrE,EAAA,SAAA,GAAY,QAAA;AACd;AAGO,SAAS,YAAA,GAAyC;AACvD,EAAA,OAAO,SAAA;AACT;AAiBO,IAAM,yBAAA,GAAgF;AAAA,EAC3F,EAAE,QAAA,EAAU,OAAA,EAAS,QAAA,EAAU,gBAAA;AACjC","file":"host-image.js","sourcesContent":["import type { ReactNode } from 'react'\n\n/**\n * `@elytracms/next/host-image` — the host image-delivery seam for DUAL-RENDERED\n * project components (EC-368, from the consumer-proven EC-271 pattern).\n *\n * The `project.*` page-builder components are dual-rendered: the SAME module\n * renders in the Vite studio canvas AND the Next host (AD-2/AD-11), so it may\n * not statically import `next/image` — that would break the Vite build. And in\n * the Next host these components render as Server Components, where React\n * context is unavailable, so an optimized `<Image>` can't be threaded through a\n * provider either.\n *\n * The seam that satisfies both: a tiny module singleton the host sets once at\n * boot. The studio never sets it (it renders the components via the root\n * `elytra.config`, which never imports the Next host), so the canvas keeps a\n * plain-`<img>` fallback; the Next host injects the `ElytraImage`-backed\n * renderer so content images go through `next/image`'s optimizer:\n *\n * ```ts\n * // frontend/lib/host.ts — imported once by the catch-all route at boot\n * import { elytraHostImage } from '@elytracms/next'\n * import { setHostImage } from '@elytracms/next/host-image'\n *\n * setHostImage(elytraHostImage())\n * ```\n *\n * WHEN (and whether) to register stays consumer-owned — legacy-interop windows\n * are real: a host whose global `next/image` config is still owned by a\n * previous stack (e.g. a Sanity-era custom loader) deliberately skips\n * registration until the conflict clears, and its components keep the honest\n * plain-`<img>` fallback.\n *\n * This module is deliberately its OWN subpath entry importing nothing but React\n * types — safe in Vite, in RSC, and in `next.config.*`. The main\n * `@elytracms/next` entry never imports it at runtime (that would bundle a\n * second singleton instance into the server entry, disconnecting\n * `setHostImage` from `getHostImage` — pinned by `package-build.test.ts`).\n */\n\n/** The resolved-asset slice a host image renderer needs (mirrors `ResolvedAsset`). */\nexport interface HostImageAsset {\n  url: string\n  width: number | null\n  height: number | null\n  alt: string | null\n  focalPoint: { x: number; y: number } | null\n}\n\nexport interface HostImageProps {\n  asset: HostImageAsset\n  alt: string\n  className?: string\n  loading?: 'eager' | 'lazy'\n  /** Above-the-fold opt-out of lazy-loading (the hero image). */\n  priority?: boolean\n  /** Responsive `sizes` hint so the optimizer serves a column-sized variant. */\n  sizes?: string\n}\n\nexport type HostImageRenderer = (props: HostImageProps) => ReactNode\n\nlet hostImage: HostImageRenderer | null = null\n\n/** Host-only: register the optimized image renderer (called once at host boot). */\nexport function setHostImage(renderer: HostImageRenderer | null): void {\n  hostImage = renderer\n}\n\n/** The registered host renderer, or `null` in the studio canvas (plain-`<img>` fallback). */\nexport function getHostImage(): HostImageRenderer | null {\n  return hostImage\n}\n\n/**\n * The `next.config.*` `images.remotePatterns` preset for Elytra asset delivery\n * (EC-368 image defaults): Convex file-storage serve URLs, where uploaded\n * assets live in connected mode. Without it `next/image` refuses the remote\n * origin and delivery images 400 — spread it into your config:\n *\n * ```js\n * // next.config.mjs\n * import { convexAssetRemotePatterns } from '@elytracms/next/host-image'\n *\n * const nextConfig = {\n *   images: { remotePatterns: [...convexAssetRemotePatterns] },\n * }\n * ```\n */\nexport const convexAssetRemotePatterns: readonly { protocol: 'https'; hostname: string }[] = [\n  { protocol: 'https', hostname: '*.convex.cloud' },\n]\n"]}

package/dist/index.d.ts

@@ -3,9 +3,9 @@ import { ComponentRegistry, ComponentIssue, ComponentManifest } from '@elytracms
 export { ComponentManifest, PropField, SlotSpec, defineComponent } from '@elytracms/core/component-registry';
 import { ComponentImplementations, ResolveBinding, RelationTarget } from '@elytracms/core/runtime-renderer';
 export { ComponentImplementations, RenderAsset } from '@elytracms/core/runtime-renderer';
-import { ResolvePageResult, ResolvedAsset, Perspective, ContentClient, CacheTags, ContentDocumentSource } from '@elytracms/core/content';
+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';
+import { LocaleConfig, Locale, RouteRecord, RedirectRecord, CollectionDef, CmsDocument } from '@elytracms/core/cms-core';
 export { CmsDocument, CollectionDef, FieldDef, Locale, LocaleConfig, RedirectRecord, RouteRecord, documentSchema, localeConfigSchema, redirectRecordSchema, routeRecordSchema } from '@elytracms/core/cms-core';
 import { ComponentNode } from '@elytracms/core/project-graph';
 export { ComponentNode } from '@elytracms/core/project-graph';
@@ -15,6 +15,7 @@ import { Metadata, MetadataRoute } from 'next';
 import { z } from 'zod';
 export { z } from 'zod';
 import { ImageLoader } from 'next/image';
+import { HostImageRenderer } from './host-image.js';
 
 /**
  * One host-repo component: the manifest the builder edits against plus the
@@ -1035,35 +1036,167 @@ interface NextImagePrimitiveOptions {
  * ```
  */
 declare function nextImagePrimitive(options?: NextImagePrimitiveOptions): HostComponent;
+/** Per-deployment options for {@link elytraHostImage} (the EC-271 loader seam). */
+interface ElytraHostImageOptions {
+    /** Custom `next/image` loader for non-Vercel CDNs (see {@link NextImagePrimitiveOptions}). */
+    loader?: ImageLoader;
+    /** Default quality (1–100) when a call site doesn't set one (Next defaults to 75). */
+    quality?: number;
+}
+/**
+ * The `next/image`-backed {@link HostImageRenderer} (EC-368 image defaults): the
+ * renderer a Next host registers on the `@elytracms/next/host-image` bridge so
+ * DUAL-RENDERED project components (which can't import `next/image` themselves)
+ * deliver optimized images — resized/modern-format variants, intrinsic
+ * dimensions (no layout shift), focal-point `object-position`. A dimensionless
+ * record degrades to a plain `<img>` (honest, never a crash), exactly like
+ * {@link ElytraImage}.
+ *
+ * ```ts
+ * import { elytraHostImage } from '@elytracms/next'
+ * import { setHostImage } from '@elytracms/next/host-image'
+ *
+ * setHostImage(elytraHostImage()) // once, at host boot (never in the studio)
+ * ```
+ */
+declare function elytraHostImage(options?: ElytraHostImageOptions): HostImageRenderer;
 
 /**
- * Pure token/target logic of the draft-preview routes (EC-144), kept free of
- * Next.js imports so it is unit-testable. `preview.ts` wires it into route
- * handlers with `draftMode()`.
+ * Env resolution for the delivery host kit (EC-368). ONE documented name per
+ * concern — every kit surface reads the same resolved bag, so the two-
+ * disconnected-secrets class of bug (a preview route gating on one env var
+ * while the draft loader reads another) is structurally impossible: there is
+ * exactly one `DRAFT_PREVIEW_TOKEN`, consumed by BOTH the preview-enable route
+ * and the draft snapshot fetch.
+ *
+ * | Env var               | Concern                                              |
+ * | --------------------- | ---------------------------------------------------- |
+ * | `ELYTRA_CONVEX_URL`   | Convex deployment URL — presence (with the project   |
+ * |                       | id) switches the loader to LIVE mode                 |
+ * | `ELYTRA_PROJECT_ID`   | The project the studio publishes under (= tag scope) |
+ * | `DRAFT_PREVIEW_TOKEN` | The ONE draft secret: gates the preview-enable route |
+ * |                       | AND authenticates the draft snapshot fetch (must     |
+ * |                       | 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   |
  */
-type PreviewEvaluation = {
-    ok: true;
-    redirectTo: string;
-} | {
-    ok: false;
-    status: 400 | 401;
-    message: string;
+/** The kit's documented env names (single source of truth, also used in docs/tests). */
+declare const ELYTRA_HOST_ENV_KEYS: {
+    readonly convexUrl: "ELYTRA_CONVEX_URL";
+    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;
+}
 /**
- * Only same-site path targets are accepted (`/...` but not `//host`), so the
- * preview endpoint can never be used as an open redirect.
+ * Resolve the kit's env bag from a raw env record (`process.env` by default at
+ * the factory). Values are trimmed; empty strings resolve to `undefined` — an
+ * env var set to `""` must behave exactly like an unset one (endpoints stay
+ * closed, live mode stays off), never like a configured empty secret.
  */
-declare function safeRedirectTarget(value: string | null | undefined, fallback?: string): string | null;
+declare function resolveHostEnv(env: Record<string, string | undefined>): ElytraHostEnv;
+
 /**
- * Evaluate a preview-enable request. Drafts are token-gated (EC-144
- * acceptance: without the token, drafts are never reachable):
+ * Site-chrome globals for delivery hosts (EC-368, from EC-369 finding #5): the
+ * layout, header, and footer are NOT rendered through the canvas, so they read
+ * the `settings` singleton + `navigation` documents straight from the
+ * `ContentSource` and pre-resolve everything — keeping the chrome components
+ * pure presentational, with no `ContentClient` or `@elytracms/*` knowledge.
+ * Both real consumers hand-authored this ~200-line layer independently; the
+ * MECHANISM now lives here, while the per-project projection (which settings
+ * fields exist, what the chrome looks like) stays consumer-owned:
  *
- * - an unconfigured (empty) expected token rejects every request — preview
- *   cannot be accidentally left open;
- * - a missing or mismatched `token` query param is a 401;
- * - an off-site `redirect` target is a 400.
+ * - **settings**: the singleton collection's lone document (EC-274) — no
+ *   document id is ever named.
+ * - **navigation by slot**: menus are addressed by their EC-284 alias slot
+ *   (`main`, `footer`), never a document id — delivery shape carries `alias`
+ *   since EC-364.
+ * - **link resolution**: link-object values (`linkType: href | page | file`)
+ *   resolve through `client.resolveLink` — the same `urlForDocument` authority
+ *   the router serves, so a nav link to a nested page carries its FULL composed
+ *   path (`/krippe/tagesablauf`, EC-218/EC-360), and `home → '/'` needs no
+ *   special-casing.
+ * - **asset resolution**: asset field values (stored ids) resolve to serve URLs
+ *   through the source's delivery-shaped asset list.
+ *
+ * Everything degrades explicitly: a missing settings document is `null`, a
+ * missing slot is `null`/`[]`, an unresolvable link drops out (never a silent
+ * `#`), an unknown asset id is `undefined` — the host renders sensible empties
+ * for the empty-source build and surfaces gaps honestly.
  */
-declare function evaluatePreviewRequest(requestUrl: string | URL, expectedToken: string | undefined): PreviewEvaluation;
+interface GlobalsConventions {
+    /** The settings singleton's collection id. Default `'settings'`. */
+    settingsCollection?: string;
+    /** The navigation documents' collection id. Default `'navigation'`. */
+    navigationCollection?: string;
+    /**
+     * Field names probed (in order) for a navigation document's entry list.
+     * Default `['items', 'links']` — the two shapes the shipped consumers and the
+     * starter template use.
+     */
+    navigationItemsFields?: readonly string[];
+}
+/** A fully-resolved link: the composed href plus the new-tab flag. */
+interface ResolvedLink {
+    href: string;
+    openInNewTab: boolean;
+}
+/** A leaf navigation link (children of a dropdown / footer column). */
+interface ResolvedNavLink extends ResolvedLink {
+    label: string;
+    /** Optional subline shown under the label (wide header dropdowns). */
+    description?: string;
+}
+/** A top-level navigation entry; `href` is absent for pure group headings. */
+interface ResolvedNavEntry {
+    label: string;
+    href?: string;
+    openInNewTab: boolean;
+    description?: string;
+    children: ResolvedNavLink[];
+}
+/** The resolved chrome-globals surface `loadGlobals` yields (EC-368). */
+interface SiteGlobals {
+    /** The settings singleton, delivery-shaped, or `null` (empty build / not published). */
+    settings: ResolvedDocument | null;
+    /** The navigation document filling a slot alias (EC-284/EC-364), or `null`. */
+    navigation(slot: string): ResolvedDocument | null;
+    /**
+     * A slot's entry list, fully resolved: labels, composed hrefs (nested paths
+     * included), new-tab flags, sublines, one level of children. Entries whose
+     * link cannot resolve to an href are kept only when they carry children (a
+     * group heading); leaf entries without a resolvable href drop out.
+     */
+    navigationEntries(slot: string): ResolvedNavEntry[];
+    /** Resolve a link-object field value to an href + new-tab flag, or `null`. */
+    resolveLink(value: unknown): ResolvedLink | null;
+    /** Resolve an asset field value (stored id / URL / `{ url }`) to a URL, or `undefined`. */
+    assetUrl(value: unknown): string | undefined;
+    /** The accessor client behind the globals — for bespoke projections. */
+    client: ContentClient;
+    /** The underlying content source (assets(), locales, routes). */
+    source: ContentSource;
+}
+interface ResolveGlobalsOptions {
+    /** Perspective of the chrome read. Default `'published'` (live is published-only). */
+    perspective?: Perspective;
+    locale?: Locale;
+    conventions?: GlobalsConventions;
+}
+/**
+ * Resolve the chrome globals over an already-loaded `ContentSource` — the pure
+ * core of the host kit's `loadGlobals` (directly testable over fixture
+ * sources).
+ */
+declare function resolveGlobals(source: ContentSource, options?: ResolveGlobalsOptions): SiteGlobals;
 
 /**
  * Draft preview route handlers (EC-144): Next.js `draftMode()` integration.
@@ -1102,6 +1235,299 @@ declare function createPreviewRoute(options: PreviewRouteOptions): PreviewRouteH
  */
 declare function createPreviewDisableRoute(): PreviewRouteHandlers;
 
+/**
+ * The delivery host kit (EC-368): ONE factory over (env, project config) that
+ * yields every engine-shaped delivery surface a Next.js host mounts — content
+ * loading (live snapshot / build-safe empty / token-gated draft), the catch-all
+ * canvas route, the instant-publish revalidate webhook, draft-mode plumbing,
+ * chrome globals, and the full-bleed layout hint. A consumer wires env + ~5
+ * lines per surface; no engine logic is ever copied into a host repo again
+ * (EC-369 findings #4/#5/#6/#11).
+ *
+ * ```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,
+ * })
+ * ```
+ *
+ * ```ts
+ * // app/[[...slug]]/page.tsx
+ * const route = elytra.canvasRoute()
+ * export default route.Page
+ * export const generateMetadata = route.generateMetadata
+ *
+ * // app/api/revalidate/route.ts
+ * export const { POST, OPTIONS } = elytra.revalidateRoute()
+ *
+ * // app/api/draft/route.ts            — GET /api/draft?token=…&redirect=/path
+ * export const { GET } = elytra.previewRoute()
+ *
+ * // app/api/draft/disable/route.ts
+ * export const { GET } = elytra.previewDisableRoute()
+ * ```
+ *
+ * Trust boundaries are unchanged: live surfaces read the PUBLISHED snapshot;
+ * draft is reachable only through explicit Next draft mode behind the ONE
+ * `DRAFT_PREVIEW_TOKEN` (which also authenticates the draft snapshot fetch —
+ * see `host-env.ts`); the revalidate webhook stays HMAC-signed. The consumer
+ * keeps ownership of project config (AD-11), host components, form endpoints,
+ * and anything genuinely bespoke.
+ */
+interface ElytraHostOptions {
+    /**
+     * The project slug (config-as-code identity, mirrors `elytra.config.ts`).
+     * Used as the content scope when no live backend is configured.
+     */
+    slug: string;
+    /** Locale config — config-owned (AD-11), never read from the snapshot. */
+    locales: LocaleConfig;
+    /** CMS collection schema — config-owned (AD-11). */
+    collections: readonly CollectionDef[];
+    /** 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`).
+     */
+    components?: readonly HostComponent[];
+    /**
+     * `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.
+     */
+    frontendUrl?: string;
+    /**
+     * 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`.
+     */
+    env?: Record<string, string | undefined>;
+    /**
+     * The no-backend content fallback, used whenever `ELYTRA_CONVEX_URL` +
+     * `ELYTRA_PROJECT_ID` are not both set. Default: a build-safe EMPTY source —
+     * consumer CI builds green with no backend, and every URL is a clean 404
+     * until content exists. The starter template overrides this with its seeded
+     * in-memory world.
+     */
+    fallbackContent?: (request: CanvasContentRequest) => Promise<ContentSource>;
+    /** Chrome-globals conventions (settings/navigation collection ids, items fields). */
+    globals?: GlobalsConventions;
+    /** Fetch implementation override for the live snapshot loader (tests, proxies). */
+    fetch?: typeof globalThis.fetch;
+}
+/** Pass-through canvas-route options the kit does not own. */
+interface HostCanvasRouteOptions {
+    /** Extra binding payloads per request (see `CanvasRouteOptions.payloads`). */
+    payloads?: CanvasPayloadsFactory;
+    /** Tag observation hook (see `CanvasRouteOptions.onTags`). */
+    onTags?: (tags: CacheTags, info: CanvasRequestInfo) => void;
+    /** Metadata override (see `CanvasRouteOptions.metadata`). */
+    metadata?: (result: ResolvePageResult, info: CanvasRequestInfo) => Metadata;
+    /**
+     * 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.
+     */
+    cache?: CanvasCacheOptions | false;
+}
+interface LoadGlobalsOptions {
+    /** Perspective of the chrome read. Default `'published'` (live is published-only). */
+    perspective?: Perspective;
+}
+/** 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.
+     */
+    contentScope: string;
+    /** The resolved env bag (documented names, trimmed, empty = unset). */
+    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). */
+    components: HostComponents;
+    /** The public base URL of the delivery site, when configured. */
+    frontendUrl?: string;
+    /**
+     * 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.
+     */
+    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.
+     */
+    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.
+     */
+    revalidateRoute(overrides?: Partial<RevalidateRouteOptions>): RevalidateRouteHandlers;
+    /**
+     * The draft-mode ENABLE route for e.g. `app/api/draft/route.ts` —
+     * `GET /api/draft?token=…&redirect=/path`, gated by the ONE
+     * `DRAFT_PREVIEW_TOKEN` (the same secret the draft snapshot fetch sends, so
+     * the two can never disconnect). Unset token = drafts unreachable.
+     */
+    previewRoute(): PreviewRouteHandlers;
+    /** The draft-mode DISABLE route (no token — it only reduces visibility). */
+    previewDisableRoute(): PreviewRouteHandlers;
+    /**
+     * 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.
+     */
+    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;
+
+/**
+ * The LIVE half of the delivery host kit (EC-368): fetch the delivery snapshot
+ * from a Convex deployment (`convex/delivery.ts` in the builder app) over
+ * Convex's public HTTP query API — a plain `fetch` to
+ * `POST {deployment}/api/query`, no Convex npm dependency — and assemble it
+ * through the same `createStaticContentSource` path the fixture snapshot uses,
+ * so accessor and rendering semantics are byte-identical across seeded, empty,
+ * and live modes. This engine-izes the ~300-line `live-content.ts` both real
+ * consumers hand-copied (EC-369 finding #5); the fetch + Zod-validation logic
+ * now lives in exactly one place.
+ *
+ * Perspective handling: published requests fetch the PUBLIC `delivery:snapshot`
+ * (published documents only — the standing live-is-published-only invariant).
+ * Draft-mode requests fetch `delivery:draftSnapshot`, gated by the deployment's
+ * `DRAFT_PREVIEW_TOKEN` — the same single secret that gates the kit's
+ * preview-enable route (see `host-env.ts`).
+ *
+ * Routes: config-sourced route records (AD-3/AD-11, EC-207 — the host repo's
+ * own `cms/`, passed via options) and the implicit per-locale home fallback are
+ * MERGED (EC-177 gap 2), never XOR'd — config records win per pattern+locale.
+ * The backend never carries route data.
+ */
+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;
+    /** 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. */
+    routes: readonly RouteRecord[];
+    /** `DRAFT_PREVIEW_TOKEN` — required for draft-perspective loads. */
+    draftToken?: string;
+    /** Fetch implementation override (tests, custom agents). Defaults to global fetch. */
+    fetch?: typeof globalThis.fetch;
+}
+/**
+ * The `delivery.ts` payload shape (validated field-by-field below). A
+ * deployment IS one environment (EC-179); the snapshot carries content only
+ * (EC-287) — documents, assets, editorial redirects (EC-303), and persisted
+ * data-source definitions (EC-166).
+ */
+interface DeliverySnapshotPayload {
+    projectId: string;
+    redirects?: unknown[];
+    sources?: unknown;
+    documents: unknown[];
+    assets: unknown[];
+}
+/**
+ * Implicit fallback route table (EC-187): `/` → the first `page`-collection
+ * document (lowest id), once per configured locale. Merged UNDER the stored
+ * records. The delivery snapshot is already perspective-filtered server-side,
+ * so in draft mode this correctly previews the draft home even when
+ * unpublished.
+ */
+declare function fallbackHomeRoutes(documents: readonly CmsDocument[], locales: LocaleConfig): RouteRecord[];
+/**
+ * Assemble a fetched delivery-snapshot payload into a `ContentSource` — the
+ * pure half of {@link loadLiveContent}, exported so the parsing/assembly rules
+ * are directly testable against fixture payloads (no network).
+ */
+declare function assembleLiveSource(payload: DeliverySnapshotPayload, options: Pick<LiveContentOptions, 'locales' | 'collections' | 'routes'>, perspective: Perspective): ContentSource;
+/** Fetch the live delivery snapshot and assemble the `ContentSource` for one request. */
+declare function loadLiveContent(options: LiveContentOptions, perspective: Perspective): Promise<ContentSource>;
+
+/**
+ * Manifest-driven header clearance (EC-368): does this page OPEN full-bleed?
+ *
+ * A host with a floating header (occupying no flow space) must pad a page's
+ * content down by the header height — unless the page's FIRST canvas block is a
+ * structural hero that deliberately bleeds to the viewport top and renders
+ * under the header. Which components bleed is declared on their OWN manifest
+ * (`presentation: { fullBleed: true }`, `@elytracms/core/component-registry`),
+ * so the host derives the decision from the registry instead of keeping a
+ * parallel hand-maintained component-id set that silently drifts when a new
+ * hero ships.
+ *
+ * Pure over the delivery-shaped document: the composition field is found by
+ * VALUE (the same `compositionNodesOf` selection the renderer uses), so hosts
+ * with `body`, `content`, or bespoke composition field names all work. Absent
+ * document, empty composition, unknown component, or an undeclared hint all
+ * answer `false` — the safe default is clearance.
+ *
+ * ```tsx
+ * const outcome = client.resolvePage(path)
+ * const fullBleed = firstBlockFullBleed(outcome.document, components.registry)
+ * return fullBleed ? page : <div className="pt-[var(--header-clearance)]">{page}</div>
+ * ```
+ *
+ * The host kit wires the resolution half for you: `elytra.pageOpensFullBleed(slug)`.
+ */
+declare function firstBlockFullBleed(document: Record<string, unknown> | null | undefined, registry: ComponentRegistry): boolean;
+
+/**
+ * Pure token/target logic of the draft-preview routes (EC-144), kept free of
+ * Next.js imports so it is unit-testable. `preview.ts` wires it into route
+ * handlers with `draftMode()`.
+ */
+type PreviewEvaluation = {
+    ok: true;
+    redirectTo: string;
+} | {
+    ok: false;
+    status: 400 | 401;
+    message: string;
+};
+/**
+ * Only same-site path targets are accepted (`/...` but not `//host`), so the
+ * preview endpoint can never be used as an open redirect.
+ */
+declare function safeRedirectTarget(value: string | null | undefined, fallback?: string): string | null;
+/**
+ * Evaluate a preview-enable request. Drafts are token-gated (EC-144
+ * acceptance: without the token, drafts are never reachable):
+ *
+ * - an unconfigured (empty) expected token rejects every request — preview
+ *   cannot be accidentally left open;
+ * - a missing or mismatched `token` query param is a 401;
+ * - an off-site `redirect` target is a 400.
+ */
+declare function evaluatePreviewRequest(requestUrl: string | URL, expectedToken: string | undefined): PreviewEvaluation;
+
 /**
  * @elytracms/next — the embedded runtime (EC-144, vision AD-1): render
  * builder-managed pages inside the user's own Next.js App Router repo with
@@ -1114,4 +1540,4 @@ declare function createPreviewDisableRoute(): PreviewRouteHandlers;
  */
 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, ElytraImage, type ElytraImageAsset, type ElytraImageProps, type HostComponent, type HostComponents, type MaterializeSourcePayloadsInput, type MaterializedSourcePayloads, PACKAGE, type PreviewEvaluation, type PreviewRouteHandlers, type PreviewRouteOptions, REVALIDATE_SIGNATURE_HEADER, type ResolveCanvasPageOptions, type RevalidateEvaluation, type RevalidatePayload, type RevalidateRouteHandlers, type RevalidateRouteOptions, type SitemapParamsProvider, type SitemapRouteContext, type SitemapSkippedRoute, type SourcePayloadError, type StaticContentData, canvasPageMetadata, canvasSitemapEntries, collectBindingSourceIds, collectionCacheTag, createAssetImageLoader, createBindingResolver, createCanvasRoute, createCanvasSitemap, createContentSnapshot, createPreviewDisableRoute, createPreviewRoute, createRevalidateRoute, createStaticContentSource, defaultBindingPayloads, defineHostComponents, docCacheTag, evaluatePreviewRequest, evaluateRevalidateRequest, isSourcePayloadError, loadCachedEntry, materializeSourcePayloads, mergeCacheTags, mergeRouteRecords, nextCacheTags, nextImagePrimitive, pathFromSlug, projectSweepTag, resolveCanvasPage, 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 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 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, fallbackHomeRoutes, firstBlockFullBleed, isSourcePayloadError, loadCachedEntry, loadLiveContent, materializeSourcePayloads, mergeCacheTags, mergeRouteRecords, nextCacheTags, nextImagePrimitive, pathFromSlug, projectSweepTag, resolveCanvasPage, resolveGlobals, resolveHostEnv, resolvePayloadToken, revalidatePayloadSchema, routeCacheTag, safeRedirectTarget, scopeCacheTag, signRevalidateBody, sourcePayloadError, splitLocalePath };