@elytracms/next 0.0.92 → 0.0.94

package/dist/host-image.d.ts

@@ -1,4 +1,5 @@
 import { ReactNode } from 'react';
+import { ResolvedAsset } from '@elytracms/core/cms-core';
 
 /**
  * `@elytracms/next/host-image` — the host image-delivery seam for DUAL-RENDERED
@@ -37,26 +38,21 @@ import { ReactNode } from 'react';
  * 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;
-    /**
-     * LQIP blur-placeholder data URI (EC-420) → next/image blurDataURL. Optional so a
-     * consumer mapping a `ResolvedAsset` in stays source-compatible; when present the
-     * delivered image blurs up while the optimized bytes load.
-     */
-    lqip?: string | null;
-}
+/**
+ * The resolved-asset slice a host image renderer needs — DERIVED from `ResolvedAsset`
+ * (EC-587; it used to mirror it by hand). `lqip` (EC-420 → next/image blurDataURL) is
+ * optional so a caller handing a partial asset stays source-compatible; when present
+ * the delivered image blurs up while the optimized bytes load.
+ */
+type HostImageAsset = Pick<ResolvedAsset, 'url' | 'width' | 'height' | 'alt' | 'focalPoint'> & Partial<Pick<ResolvedAsset, 'lqip'>>;
 interface HostImageProps {
     asset: HostImageAsset;
-    alt: string;
+    /**
+     * The image's alt text. Omitted → the ASSET's alt (EC-587: an asset's alt has one
+     * home and one reader). Pass it only to override deliberately — e.g. `''` for a
+     * decorative image.
+     */
+    alt?: string;
     className?: string;
     loading?: 'eager' | 'lazy';
     /** Above-the-fold opt-out of lazy-loading (the hero image). */

package/dist/host-image.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/host-image.ts"],"names":[],"mappings":";AAoEA,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   * LQIP blur-placeholder data URI (EC-420) → next/image blurDataURL. Optional so a\n   * consumer mapping a `ResolvedAsset` in stays source-compatible; when present the\n   * delivered image blurs up while the optimized bytes load.\n   */\n  lqip?: string | 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"]}
+{"version":3,"sources":["../src/host-image.ts"],"names":[],"mappings":";AAoEA,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'\nimport type { ResolvedAsset } from '@elytracms/core/cms-core'\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/**\n * The resolved-asset slice a host image renderer needs — DERIVED from `ResolvedAsset`\n * (EC-587; it used to mirror it by hand). `lqip` (EC-420 → next/image blurDataURL) is\n * optional so a caller handing a partial asset stays source-compatible; when present\n * the delivered image blurs up while the optimized bytes load.\n */\nexport type HostImageAsset = Pick<ResolvedAsset, 'url' | 'width' | 'height' | 'alt' | 'focalPoint'> &\n  Partial<Pick<ResolvedAsset, 'lqip'>>\n\nexport interface HostImageProps {\n  asset: HostImageAsset\n  /**\n   * The image's alt text. Omitted → the ASSET's alt (EC-587: an asset's alt has one\n   * home and one reader). Pass it only to override deliberately — e.g. `''` for a\n   * decorative image.\n   */\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

@@ -13,6 +13,7 @@ import { Clock } from '@elytracms/core/determinism';
 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 { IngestPayload } from '@elytracms/core/ingest';
 import { ImageLoader } from 'next/image';
 import { HostImageRenderer } from './host-image.js';
 export { z } from 'zod';
@@ -310,6 +311,12 @@ interface StaticContentData {
      * explicit unresolved-placeholder scheme (never a silent empty string).
      */
     assetUrl?: (asset: AssetRecord) => string;
+    /**
+     * EC-585 — the stored rows the host could not read (`parseDeliveredDocuments`), handed
+     * to every client of this source as its `sourceIssues` (and in the results they
+     * concern). A malformed row is not delivered, and never silently.
+     */
+    sourceIssues?: readonly CmsValidationIssue[];
 }
 /**
  * Assemble a `ContentSource` from plain prefetched data — the pure half of
@@ -372,6 +379,25 @@ interface CanvasWrapContext extends CanvasRequestInfo {
      */
     result: ResolvePageResult;
 }
+/**
+ * EC-618 — what the route's `analytics` slot is told about the page it renders on: the
+ * resolved document (the content model, not the URL — slug changes and locale paths then
+ * attribute correctly), the locale it rendered in, the request path and the status. Plain
+ * serializable values, so the slot may be a client component.
+ */
+interface CanvasBeaconProps {
+    /** The request path as served (including any locale prefix). */
+    path: string;
+    /** 200: the route renders the slot only on a rendered page (a 404 never reaches it). */
+    status: 200;
+    /** The locale the page rendered in. */
+    locale: string;
+    /** The resolved document's collection and id — absent when the URL resolved to no document. */
+    collection?: string;
+    documentId?: string;
+}
+/** PURE core (EC-618): the slot's props from a render outcome's resolution and the request info. */
+declare function canvasBeaconProps(result: ResolvePageResult, info: CanvasRequestInfo): CanvasBeaconProps;
 type CanvasPageOutcome = {
     kind: 'redirect';
     target: string;
@@ -723,6 +749,21 @@ interface CanvasRouteOptions {
      * the default.
      */
     wrap?: (children: ReactNode, ctx: CanvasWrapContext) => ReactNode;
+    /**
+     * The ANALYTICS slot (EC-618): a component the route renders inside every `render`
+     * outcome, AFTER the page (and outside `wrap`, so a wrapper cannot drop it), with the
+     * resolved document, the locale, the path and the status ({@link CanvasBeaconProps}).
+     * Published perspective only — a draft preview is an editor at work, not a visit.
+     *
+     * The engine supplies the slot and nothing else: its value is the beacon of the
+     * analytics addon, `@elytracms/analytics/next` — **unpublished, pending counsel's
+     * verdict on its consent-free claim** (EC-618) — or a host's own component. Absent, the
+     * route renders exactly what it rendered before, and sends nothing.
+     *
+     * A not-found page never reaches this slot (`notFound()` renders the host's
+     * `not-found.tsx`), so a 404 beacon lives in that file.
+     */
+    analytics?: ComponentType<CanvasBeaconProps>;
 }
 interface CanvasRouteProps {
     params: Promise<{
@@ -1052,6 +1093,177 @@ interface RevalidateRouteHandlers {
  */
 declare function createRevalidateRoute(options: RevalidateRouteOptions): RevalidateRouteHandlers;
 
+/**
+ * EC-617 — the pure decision core of the PUBLIC INGEST route (`createIngestRoute`, the
+ * Next wrapper in `ingest.ts`): no Next imports, no network, an injected clock — the
+ * house "pure core + thin wrapper" shape of `evaluateRevalidateRequest` /
+ * `createRevalidateRoute`.
+ *
+ * The route is a site's one public write path (ruling EC-565 § 6c). It runs, in order:
+ *
+ * 1. **method** — `POST` only (405);
+ * 2. **configured** — the server-held `INGEST_SECRET` and the receiver URL are set (503
+ *    otherwise: the route stays closed until deliberately configured, never a no-op);
+ * 3. **same-origin** — a browser request from another origin (`Origin` / `Sec-Fetch-Site`)
+ *    is refused (403). The route emits no CORS headers and reads no cookie;
+ * 4. **rate limit** — a fixed window per CLIENT KEY (429, `Retry-After`);
+ * 5. **size** — the raw body capped at `maxBodyBytes` (413), checked before parsing;
+ * 6. **shape** — JSON in the ingest envelope (400, with the issues);
+ * 7. **bot gate** — the host's own check, an injected seam (403, `{ gate: 'bot' }`): the
+ *    engine supplies the slot, never the vendor;
+ * 8. **enrichment** (EC-618) — an optional seam an ADDON fills (the analytics addon derives
+ *    a country and a visitor's sketch coordinates here, where the request is): it returns the
+ *    payload to forward, which is re-validated against the envelope and the receiver's cap
+ *    (500 — the site's own fault — when it throws or returns something invalid). Absent, the
+ *    route is exactly what it was;
+ *
+ * then the wrapper signs the payload with the server-held secret and forwards it to the
+ * one Convex receiver, relaying its answer. Only the PAYLOAD is forwarded — never a request
+ * header — so whatever an enrichment reads from the request (the client address, the user
+ * agent, a geo header) stays in this request's memory; only what it derives travels.
+ */
+/** The answer the core gives the wrapper. */
+type IngestEvaluation = {
+    ok: true;
+    payload: IngestPayload;
+} | {
+    ok: false;
+    status: 400 | 403 | 405 | 413 | 429 | 500 | 503;
+    body: Record<string, unknown>;
+    headers?: Record<string, string>;
+};
+/** What the host's bot gate answers (a Turnstile / hCaptcha / honeypot check the HOST implements). */
+type BotGateVerdict = {
+    allow: true;
+} | {
+    allow: false;
+    reason: string;
+};
+/**
+ * The bot-gate seam: called with the request and the parsed payload, AFTER the cheap
+ * checks (so a flood never reaches a paid verification API). Absent → no gate.
+ */
+type IngestBotGate = (input: {
+    request: Request;
+    payload: IngestPayload;
+}) => BotGateVerdict | Promise<BotGateVerdict>;
+/**
+ * EC-618 — the enrichment seam: called with the request and the parsed payload LAST (after
+ * the bot gate), it returns the payload the route signs and forwards. The engine supplies
+ * the slot, never the code: an addon fills it (`@elytracms/analytics/next`'s
+ * `analyticsEnrichment`), and a host may compose its own. Whatever it reads from the
+ * request is held for this request only — the route forwards the returned payload and
+ * nothing else. Absent → no enrichment, the payload forwarded as parsed.
+ */
+type IngestEnrich = (input: {
+    request: Request;
+    payload: IngestPayload;
+}) => IngestPayload | Promise<IngestPayload>;
+/**
+ * The fixed-window limiter — the AI route's pattern (EC-602), keyed per client. Holds,
+ * in memory only, one `{ windowStart, count }` per key seen in the current window; expired
+ * windows are dropped as the clock moves, so the map is bounded by the clients of one
+ * window. Each server instance holds its own windows (a serverless platform runs several),
+ * so the limit is per instance — the same documented limitation as the AI route.
+ */
+interface FixedWindowLimiter {
+    /** Count one request for `key`; `retryAfterSeconds` when it is over the limit. */
+    hit(key: string): {
+        allowed: true;
+    } | {
+        allowed: false;
+        retryAfterSeconds: number;
+    };
+    /** How many keys the limiter currently holds (for the bound test). */
+    size(): number;
+}
+declare function createFixedWindowLimiter(options: {
+    limit: number;
+    windowMs?: number;
+    now?: () => number;
+}): FixedWindowLimiter;
+/**
+ * The DEFAULT client key: the first hop of `x-forwarded-for` (what Vercel and most proxies
+ * set), else `x-real-ip`, else one shared `unknown` bucket. An IP address is personal
+ * data: it is held ONLY as a key of the in-memory window above, for at most one window,
+ * and is never stored, logged or forwarded to the receiver. A host that wants a different
+ * key (a hashed one, a session id) passes `clientKey`.
+ */
+declare function defaultIngestClientKey(request: Request): string;
+/** Is this a cross-origin BROWSER request? (A request with no browser headers is not judged here.) */
+declare function isCrossOrigin(request: Request): boolean;
+interface IngestEvaluationInput {
+    request: Request;
+    /** The raw body, read by the wrapper up to `maxBodyBytes + 1` bytes (`undefined` when over). */
+    rawBody: string | undefined;
+    configured: boolean;
+    limiter: FixedWindowLimiter;
+    clientKey: (request: Request) => string;
+    botGate?: IngestBotGate;
+    enrich?: IngestEnrich;
+}
+/** Evaluate one request (see the module header for the order). */
+declare function evaluateIngestRequest(input: IngestEvaluationInput): Promise<IngestEvaluation>;
+/**
+ * Read a request body as text, at most `maxBytes` (counted in UTF-8 bytes). `undefined`
+ * when it is longer — the over-size body is never buffered whole. A declared
+ * `Content-Length` over the cap is refused before a byte is read.
+ */
+declare function readCappedBody(request: Request, maxBytes?: number): Promise<string | undefined>;
+
+/**
+ * EC-617 — the PUBLIC INGEST route: a site's one write path into its project (form
+ * submissions, analytics events, upload URLs), mounted SAME-ORIGIN in the site's own
+ * App Router:
+ *
+ * ```ts
+ * // frontend/app/api/ingest/route.ts — through the delivery kit
+ * export const { POST } = elytra.ingestRoute()
+ * ```
+ *
+ * The decisions are the pure core's (`evaluateIngestRequest`: method, configured,
+ * same-origin, rate limit, size, shape, the host's bot gate); this wrapper then SIGNS the
+ * payload with the server-held `INGEST_SECRET` (it never reaches a browser) and forwards it
+ * to the deployment's ONE receiver (`<deployment>.convex.site/elytra/ingest`), relaying the
+ * receiver's answer. A receiver that rejects the signature is a SITE misconfiguration
+ * (the two secrets differ), answered 502 with that sentence — never a 401 a visitor could
+ * read as their fault.
+ *
+ * Uploads leave same-origin by design: an `upload` payload asks the receiver for ONE
+ * short-lived storage URL (the request rides this route's gate, limiter and bot gate), and
+ * the browser then sends the bytes straight to that URL; the submission that follows claims
+ * the stored file, which is checked against what the upload request declared.
+ */
+interface IngestRouteOptions {
+    /** The server-held HMAC secret (= the deployment's `ELYTRA_INGEST_SECRET`). Unset → 503. */
+    secret: string | undefined;
+    /** The deployment's HTTP origin (`https://<name>.convex.site`); the receiver path is appended. Unset → 503. */
+    siteUrl: string | undefined;
+    /** Cap on the raw JSON body, ≤ the receiver's `INGEST_MAX_BODY_BYTES` (default). */
+    maxBodyBytes?: number;
+    /** Requests per client key per minute (default 30). */
+    maxRequestsPerMinute?: number;
+    /** The rate limiter's key for a request (default: the client IP, in memory only — see `defaultIngestClientKey`). */
+    clientKey?: (request: Request) => string;
+    /** The host's bot check (Turnstile, hCaptcha, a honeypot …). The engine supplies the slot, never the vendor. */
+    botGate?: IngestBotGate;
+    /**
+     * EC-618 — an addon's enrichment, run last: it returns the payload to sign and forward
+     * (the analytics addon adds a country and the visitor's sketch coordinates, derived from
+     * the request here and never forwarded raw). Absent → the payload is forwarded as parsed.
+     */
+    enrich?: IngestEnrich;
+    /** Injected clock (tests). */
+    now?: () => number;
+    /** Injected transport (tests). */
+    fetchImpl?: typeof fetch;
+}
+interface IngestRouteHandlers {
+    POST(request: Request): Promise<Response>;
+}
+/** Create the ingest route handler (see the module header). */
+declare function createIngestRoute(options: IngestRouteOptions): IngestRouteHandlers;
+
 /**
  * Image delivery for the embedded runtime (EC-152).
  *
@@ -1247,6 +1459,8 @@ 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`)             |
+ * | `INGEST_SECRET`       | Public-ingest HMAC secret (EC-617; must equal the    |
+ * |                       | deployment's `ELYTRA_INGEST_SECRET`)                 |
  *
  * 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.
@@ -1257,12 +1471,14 @@ declare const ELYTRA_HOST_ENV_KEYS: {
     readonly projectId: "ELYTRA_PROJECT_ID";
     readonly draftToken: "DRAFT_PREVIEW_TOKEN";
     readonly revalidateSecret: "REVALIDATE_SECRET";
+    readonly ingestSecret: "INGEST_SECRET";
 };
 interface ElytraHostEnv {
     convexUrl?: string;
     projectId?: string;
     draftToken?: string;
     revalidateSecret?: string;
+    ingestSecret?: string;
 }
 /**
  * Resolve the kit's env bag from a raw env record (`process.env` by default at
@@ -1579,6 +1795,12 @@ interface HostCanvasRouteOptions {
      * invalidation — a disagreement would drop nothing, silently.
      */
     published?: CanvasRouteOptions['published'];
+    /**
+     * EC-618 — the analytics slot (see `CanvasRouteOptions.analytics`): its value is an
+     * addon's beacon (`@elytracms/analytics/next`, unpublished pending counsel). Absent →
+     * nothing renders and nothing is sent.
+     */
+    analytics?: CanvasRouteOptions['analytics'];
 }
 interface LoadGlobalsOptions {
     /** Perspective of the chrome read. Default `'published'` (live is published-only). */
@@ -1699,6 +1921,15 @@ interface ElytraHost<Collections extends readonly CollectionDef[] = readonly Col
     previewRoute(): PreviewRouteHandlers;
     /** The draft-mode DISABLE route (no token — it only reduces visibility). */
     previewDisableRoute(): PreviewRouteHandlers;
+    /**
+     * EC-617 — the PUBLIC INGEST route for `app/api/ingest/route.ts`: the site's one write path
+     * (form submissions, analytics events, upload URLs), signed with `INGEST_SECRET` and
+     * forwarded to this deployment's receiver (its HTTP origin derived from
+     * `ELYTRA_CONVEX_URL`; pass `siteUrl` for a self-hosted backend). Unset secret or no
+     * backend = 503, closed. The rate limit, the client key and the bot gate are the host's to
+     * tune — the engine supplies the slots, never a vendor.
+     */
+    ingestRoute(options?: Partial<Omit<IngestRouteOptions, 'secret'>>): IngestRouteHandlers;
     /**
      * 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
@@ -1864,4 +2095,4 @@ declare function evaluatePreviewRequest(requestUrl: string | URL, expectedToken:
  */
 declare const PACKAGE = "@elytracms/next";
 
-export { type AssetImageLoaderOptions, type BakedListing, CANVAS_VALIDATION_SLUG, type CanvasCacheKey, type CanvasContentRequest, type CanvasPageOutcome, CanvasRenderer, type CanvasRendererProps, type CanvasRequestInfo, type CanvasRoute, type CanvasRouteOptions, type CanvasRouteProps, type CanvasSitemapOptions, type CanvasSitemapResult, type CanvasWrapContext, type ContentSnapshot, type ContentSnapshotOptions, type ContentSource, type CreateCanvasSitemapOptions, type DeliveryPresentation, ELYTRA_HOST_ENV_KEYS, type ElytraContentMode, type ElytraHost, type ElytraHostEnv, type ElytraHostImageOptions, type ElytraHostOptions, ElytraImage, type ElytraImageAsset, type ElytraImageProps, type GlobalsConventions, type HostCanvasRouteOptions, type HostComponent, type HostComponents, type LiveContentOptions, type LoadGlobalsOptions, type NextImageOptions, PACKAGE, type PreviewEvaluation, type PreviewRouteHandlers, type PreviewRouteOptions, type ResolveCanvasPageOptions, type ResolveGlobalsOptions, type ResolvedLink, type ResolvedNavEntry, type ResolvedNavLink, type RevalidateEvaluation, type RevalidateRouteHandlers, type RevalidateRouteOptions, type RevalidationProject, type SeoMetadataContext, type SiteGlobals, type SitemapSkippedRoute, type StaticContentData, assembleLiveSource, bodyItemsOf, canvasSitemapEntries, collectionCacheTag, createAssetImageLoader, createCanvasRoute, createCanvasSitemap, createContentSnapshot, createElytraHost, createPreviewDisableRoute, createPreviewRoute, createRevalidateRoute, createStaticContentSource, defineHostComponents, docCacheTag, elytraHostImage, evaluatePreviewRequest, evaluateRevalidateRequest, firstBlockFullBleed, loadLiveContent, mergeCacheTags, mergeMetadataOverParent, nextCacheTags, openGraphLocale, pathFromSlug, projectSweepTag, requestPerspective, resolveCanvasPage, resolveGlobals, resolveHostEnv, revalidationTags, routeCacheTag, safeRedirectTarget, scopeCacheTag, seoContextOf, seoMetadata, seoObjectOf, withNextImage };
+export { type AssetImageLoaderOptions, type BakedListing, type BotGateVerdict, CANVAS_VALIDATION_SLUG, type CanvasBeaconProps, type CanvasCacheKey, type CanvasContentRequest, type CanvasPageOutcome, CanvasRenderer, type CanvasRendererProps, type CanvasRequestInfo, type CanvasRoute, type CanvasRouteOptions, type CanvasRouteProps, type CanvasSitemapOptions, type CanvasSitemapResult, type CanvasWrapContext, type ContentSnapshot, type ContentSnapshotOptions, type ContentSource, type CreateCanvasSitemapOptions, type DeliveryPresentation, ELYTRA_HOST_ENV_KEYS, type ElytraContentMode, type ElytraHost, type ElytraHostEnv, type ElytraHostImageOptions, type ElytraHostOptions, ElytraImage, type ElytraImageAsset, type ElytraImageProps, type FixedWindowLimiter, type GlobalsConventions, type HostCanvasRouteOptions, type HostComponent, type HostComponents, type IngestBotGate, type IngestEnrich, type IngestEvaluation, type IngestRouteHandlers, type IngestRouteOptions, type LiveContentOptions, type LoadGlobalsOptions, type NextImageOptions, PACKAGE, type PreviewEvaluation, type PreviewRouteHandlers, type PreviewRouteOptions, type ResolveCanvasPageOptions, type ResolveGlobalsOptions, type ResolvedLink, type ResolvedNavEntry, type ResolvedNavLink, type RevalidateEvaluation, type RevalidateRouteHandlers, type RevalidateRouteOptions, type RevalidationProject, type SeoMetadataContext, type SiteGlobals, type SitemapSkippedRoute, type StaticContentData, assembleLiveSource, bodyItemsOf, canvasBeaconProps, canvasSitemapEntries, collectionCacheTag, createAssetImageLoader, createCanvasRoute, createCanvasSitemap, createContentSnapshot, createElytraHost, createFixedWindowLimiter, createIngestRoute, createPreviewDisableRoute, createPreviewRoute, createRevalidateRoute, createStaticContentSource, defaultIngestClientKey, defineHostComponents, docCacheTag, elytraHostImage, evaluateIngestRequest, evaluatePreviewRequest, evaluateRevalidateRequest, firstBlockFullBleed, isCrossOrigin, loadLiveContent, mergeCacheTags, mergeMetadataOverParent, nextCacheTags, openGraphLocale, pathFromSlug, projectSweepTag, readCappedBody, requestPerspective, resolveCanvasPage, resolveGlobals, resolveHostEnv, revalidationTags, routeCacheTag, safeRedirectTarget, scopeCacheTag, seoContextOf, seoMetadata, seoObjectOf, withNextImage };