@elytracms/next 0.0.1

package/dist/index.d.ts

@@ -0,0 +1,2616 @@
+import { ComponentType, ReactNode } from 'react';
+import { z } from 'zod';
+export { z } from 'zod';
+import { Metadata, MetadataRoute } from 'next';
+import { ImageLoader } from 'next/image';
+
+/**
+ * A structured CMS validation issue. Same conventions as
+ * `@elytracms/project-graph`'s `ValidationIssue`: a path locating the offending
+ * data, optional document/collection identity, and free-form metadata.
+ */
+declare const cmsValidationIssueSchema: z.ZodObject<{
+    code: z.ZodEnum<{
+        "duplicate-collection": "duplicate-collection";
+        "duplicate-field": "duplicate-field";
+        "unknown-collection": "unknown-collection";
+        "invalid-collection-config": "invalid-collection-config";
+        "invalid-field-config": "invalid-field-config";
+        "missing-required-field": "missing-required-field";
+        "invalid-field-value": "invalid-field-value";
+        "unknown-relation-target": "unknown-relation-target";
+        "unpublished-relation-target": "unpublished-relation-target";
+        "cardinality-violation": "cardinality-violation";
+        "unknown-asset": "unknown-asset";
+        "duplicate-document": "duplicate-document";
+        "unknown-locale": "unknown-locale";
+        "missing-localized-value": "missing-localized-value";
+        "route-conflict": "route-conflict";
+        "redirect-loop": "redirect-loop";
+        "unknown-route-target": "unknown-route-target";
+        "hierarchy-cycle": "hierarchy-cycle";
+        "unknown-version": "unknown-version";
+    }>;
+    severity: z.ZodEnum<{
+        error: "error";
+        warning: "warning";
+    }>;
+    message: z.ZodString;
+    path: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+    collectionId: z.ZodOptional<z.ZodString>;
+    documentId: z.ZodOptional<z.ZodString>;
+    meta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+type CmsValidationIssue = z.infer<typeof cmsValidationIssueSchema>;
+type CmsPath = ReadonlyArray<string | number>;
+
+/** How many related documents a relation field points at. */
+declare const cardinalitySchema: z.ZodEnum<{
+    one: "one";
+    many: "many";
+}>;
+type Cardinality = z.infer<typeof cardinalitySchema>;
+/** A single allowed option for a `select` field. */
+declare const selectOptionSchema: z.ZodObject<{
+    value: z.ZodString;
+    label: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type SelectOption = z.infer<typeof selectOptionSchema>;
+/** A schema of just the shared base attributes — the source for {@link BaseFieldDef}. */
+declare const baseFieldObjectSchema: z.ZodObject<{
+    name: z.ZodString;
+    localized: z.ZodOptional<z.ZodBoolean>;
+    filterable: z.ZodOptional<z.ZodBoolean>;
+    context: z.ZodOptional<z.ZodEnum<{
+        document: "document";
+        prop: "prop";
+        both: "both";
+    }>>;
+    default: z.ZodOptional<z.ZodUnknown>;
+    form: z.ZodOptional<z.ZodObject<{
+        label: z.ZodOptional<z.ZodString>;
+        description: z.ZodOptional<z.ZodString>;
+        placeholder: z.ZodOptional<z.ZodString>;
+        group: z.ZodOptional<z.ZodString>;
+        tab: z.ZodOptional<z.ZodString>;
+        order: z.ZodOptional<z.ZodNumber>;
+        readOnly: z.ZodOptional<z.ZodBoolean>;
+        hidden: z.ZodOptional<z.ZodBoolean>;
+        control: z.ZodOptional<z.ZodEnum<{
+            input: "input";
+            textarea: "textarea";
+            color: "color";
+            json: "json";
+        }>>;
+        inlineEditable: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>>;
+    validation: z.ZodOptional<z.ZodObject<{
+        required: z.ZodOptional<z.ZodBoolean>;
+        min: z.ZodOptional<z.ZodNumber>;
+        max: z.ZodOptional<z.ZodNumber>;
+        pattern: z.ZodOptional<z.ZodString>;
+        unique: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+/** Attributes every field-def carries, derived from {@link baseFieldShape}. */
+type BaseFieldDef = z.infer<typeof baseFieldObjectSchema>;
+/**
+ * A field definition (the shape {@link fieldDefSchema} parses to). Written
+ * explicitly rather than via `z.infer` because the `object` variant is recursive
+ * — its `fields` reference `FieldDef` itself — and TypeScript cannot infer a
+ * self-referential `z.infer`. The schema below is annotated with this type and the
+ * two are kept in lock-step (`object-field.test.ts` round-trips against drift).
+ *
+ * A discriminated union on `type` so relation/asset/select/object carry exactly
+ * the extra config they need and nothing more.
+ */
+type FieldDef = (BaseFieldDef & {
+    type: 'text';
+}) | (BaseFieldDef & {
+    type: 'number';
+}) | (BaseFieldDef & {
+    type: 'boolean';
+}) | (BaseFieldDef & {
+    type: 'date';
+}) | (BaseFieldDef & {
+    type: 'select';
+    options: SelectOption[];
+    multiple?: boolean;
+}) | (BaseFieldDef & {
+    type: 'richText';
+    allow?: string[];
+}) | (BaseFieldDef & {
+    type: 'relation';
+    target: string;
+    cardinality: Cardinality;
+    populate?: boolean;
+    strict?: boolean;
+}) | (BaseFieldDef & {
+    type: 'asset';
+    cardinality: Cardinality;
+    accept?: string[];
+}) | (BaseFieldDef & {
+    type: 'blocks';
+    allow?: string[];
+    cardinality: Cardinality;
+}) | (BaseFieldDef & {
+    type: 'object';
+    fields: FieldDef[];
+    cardinality: Cardinality;
+});
+
+/**
+ * A collection definition: an id, a kind, an ordered list of fields, and
+ * optional form metadata. The field whose value identifies a document for
+ * routing/display defaults to `title` when present (see `titleFieldOf`).
+ */
+declare const collectionDefSchema: z.ZodObject<{
+    id: z.ZodString;
+    kind: z.ZodDefault<z.ZodEnum<{
+        asset: "asset";
+        document: "document";
+    }>>;
+    fields: z.ZodDefault<z.ZodArray<z.ZodType<FieldDef, unknown, z.core.$ZodTypeInternals<FieldDef, unknown>>>>;
+    form: z.ZodOptional<z.ZodObject<{
+        label: z.ZodOptional<z.ZodString>;
+        labelSingular: z.ZodOptional<z.ZodString>;
+        description: z.ZodOptional<z.ZodString>;
+        groups: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        tabs: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>;
+    localized: z.ZodOptional<z.ZodBoolean>;
+    titleField: z.ZodOptional<z.ZodString>;
+    singleton: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+type CollectionDef = z.infer<typeof collectionDefSchema>;
+
+/**
+ * A locale code (BCP-47-ish, e.g. `en`, `en-US`, `de`). Kept as a plain
+ * non-empty string so unusual locales still parse; validity against a project's
+ * declared locale set is checked semantically (EC-018).
+ */
+declare const localeSchema: z.ZodString;
+type Locale = z.infer<typeof localeSchema>;
+/**
+ * A document identity (EC-017): the stable pointer to a piece of content. A
+ * document belongs to exactly one collection and has a stable id. For localized
+ * content the *identity* is collection+id; a specific localized variant is
+ * addressed by additionally carrying a locale (see `LocaleAwareDocumentRef`).
+ */
+declare const documentRefSchema: z.ZodObject<{
+    collection: z.ZodString;
+    id: z.ZodString;
+}, z.core.$strip>;
+type DocumentRef = z.infer<typeof documentRefSchema>;
+/**
+ * A stored document (EC-016/017/018). The live row is the continuous DRAFT
+ * (the Sanity model, EC-224). Holds:
+ * - identity (`collection` + `id`),
+ * - non-localized field values in `values`,
+ * - per-locale field values in `localized` (only for localized fields).
+ *
+ * Publish-ness is NOT a field here: a document is published when an append-only
+ * version is pinned via the record's `publishedVersion` pointer (EC-224). The
+ * delivery `published` perspective serves that pinned snapshot; this live row
+ * is always the working draft.
+ */
+declare const documentSchema: z.ZodObject<{
+    collection: z.ZodString;
+    id: z.ZodString;
+    values: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    localized: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+    defaultLocale: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type CmsDocument = z.infer<typeof documentSchema>;
+
+/**
+ * Locale configuration for a project (EC-018): the set of supported locales and
+ * the default used for fallback. Provider-neutral.
+ */
+declare const localeConfigSchema: z.ZodObject<{
+    default: z.ZodString;
+    locales: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+type LocaleConfig = z.infer<typeof localeConfigSchema>;
+
+/** A JSON-serializable value. The project graph contains only these — never functions or runtime handles. */
+type JsonValue = string | number | boolean | null | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+
+/** A pointer from the graph into a data source via a stable path token. */
+declare const bindingReferenceSchema: z.ZodObject<{
+    sourceId: z.ZodString;
+    token: z.ZodString;
+    mode: z.ZodEnum<{
+        object: "object";
+        value: "value";
+        spread: "spread";
+        repeaterItem: "repeaterItem";
+        condition: "condition";
+    }>;
+}, z.core.$strip>;
+type BindingReference = z.infer<typeof bindingReferenceSchema>;
+/** Gates whether a node renders. The left operand is resolved from a binding. */
+declare const conditionSchema: z.ZodObject<{
+    source: z.ZodObject<{
+        sourceId: z.ZodString;
+        token: z.ZodString;
+        mode: z.ZodEnum<{
+            object: "object";
+            value: "value";
+            spread: "spread";
+            repeaterItem: "repeaterItem";
+            condition: "condition";
+        }>;
+    }, z.core.$strip>;
+    operator: z.ZodEnum<{
+        truthy: "truthy";
+        exists: "exists";
+        eq: "eq";
+        neq: "neq";
+        gt: "gt";
+        gte: "gte";
+        lt: "lt";
+        lte: "lte";
+    }>;
+    value: z.ZodOptional<z.ZodType<JsonValue, unknown, z.core.$ZodTypeInternals<JsonValue, unknown>>>;
+}, z.core.$strip>;
+type Condition = z.infer<typeof conditionSchema>;
+
+/** A prop value is either a static JSON value or a binding into a data source. */
+declare const propValueSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"static">;
+    value: z.ZodType<JsonValue, unknown, z.core.$ZodTypeInternals<JsonValue, unknown>>;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"binding">;
+    binding: z.ZodObject<{
+        sourceId: z.ZodString;
+        token: z.ZodString;
+        mode: z.ZodEnum<{
+            object: "object";
+            value: "value";
+            spread: "spread";
+            repeaterItem: "repeaterItem";
+            condition: "condition";
+        }>;
+    }, z.core.$strip>;
+}, z.core.$strip>], "kind">;
+type PropValue = z.infer<typeof propValueSchema>;
+/**
+ * An instance of a registered component. Recursive via `slots`: each named slot
+ * holds an ordered list of child nodes. The reserved slot `children` is the default
+ * insertion point.
+ */
+interface ComponentNode {
+    id: string;
+    /** Namespaced registered component id (validated semantically, not at parse time). */
+    componentId: string;
+    props?: Record<string, PropValue>;
+    slots?: Record<string, ComponentNode[]>;
+    condition?: Condition;
+}
+
+/**
+ * Schema version 2 (EC-187): the graph is LAYOUTS-ONLY. Version 1 carried a
+ * `pages` array (page-as-graph-node); v2 removes it — a page is now a document
+ * in the `page` collection whose `body` composition renders into a layout via
+ * `renderCompositionInLayout`. A deployment NOT reseeded to v2 serves a null
+ * graph, so the host degrades to its visible fallback rather than crashing.
+ */
+declare const PROJECT_GRAPH_SCHEMA_VERSION = 2;
+/**
+ * The canonical project graph — LAYOUTS-ONLY (EC-187). The single source of
+ * truth for the dev-frame layout scaffolding; page content lives in the `page`
+ * collection.
+ */
+declare const projectGraphSchema: z.ZodObject<{
+    id: z.ZodString;
+    schemaVersion: z.ZodNumber;
+    metadata: z.ZodOptional<z.ZodObject<{
+        name: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    settingsRef: z.ZodOptional<z.ZodString>;
+    layouts: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+        root: z.ZodType<ComponentNode, unknown, z.core.$ZodTypeInternals<ComponentNode, unknown>>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+type ProjectGraph = z.infer<typeof projectGraphSchema>;
+
+/** A structured validation issue carrying a JSON path into the graph. */
+declare const validationIssueSchema: z.ZodObject<{
+    code: z.ZodEnum<{
+        "route-conflict": "route-conflict";
+        "invalid-component-name": "invalid-component-name";
+        "unknown-component": "unknown-component";
+        "duplicate-node-id": "duplicate-node-id";
+        "unknown-prop": "unknown-prop";
+        "invalid-prop": "invalid-prop";
+        "binding-not-allowed": "binding-not-allowed";
+        "unresolved-binding": "unresolved-binding";
+        "missing-required-slot": "missing-required-slot";
+        "unknown-slot": "unknown-slot";
+        "forbidden-component": "forbidden-component";
+        "server-only-component": "server-only-component";
+        "unknown-layout": "unknown-layout";
+        "invalid-container-direction": "invalid-container-direction";
+        "invalid-container-alignment": "invalid-container-alignment";
+        "invalid-container-gap": "invalid-container-gap";
+        "invalid-container-columns": "invalid-container-columns";
+        "invalid-container-responsive": "invalid-container-responsive";
+    }>;
+    severity: z.ZodEnum<{
+        error: "error";
+        warning: "warning";
+    }>;
+    message: z.ZodString;
+    path: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+    nodeId: z.ZodOptional<z.ZodString>;
+    meta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodType<JsonValue, unknown, z.core.$ZodTypeInternals<JsonValue, unknown>>>>;
+}, z.core.$strip>;
+type ValidationIssue = z.infer<typeof validationIssueSchema>;
+
+/**
+ * Structural views of a component manifest, supplied by the registry. The graph
+ * package depends only on these shapes (not on `@elytracms/component-registry`) so it
+ * stays free of cycles. The registry's Manifest satisfies these structurally.
+ */
+interface PropView {
+    /** Whether this prop accepts a binding. Defaults to allowed when omitted. */
+    bindable?: boolean;
+    /** Optional static-value validator (typically backed by the manifest's Zod schema). */
+    validate?: (value: unknown) => boolean;
+}
+interface SlotView {
+    name: string;
+    required?: boolean;
+    /**
+     * Allowed child component ids (EC-186). Omit to allow any registered
+     * component; when present, a child whose `componentId` is not listed is a
+     * `forbidden-component` error. Mirrors the registry's `SlotSpec.allow`.
+     */
+    allow?: readonly string[];
+}
+interface ManifestView {
+    id: string;
+    props?: Record<string, PropView>;
+    slots?: SlotView[];
+    /**
+     * Canvas-eligibility (EC-191). `false` marks a server-only / RSC component that
+     * is NOT client-renderable, so it may not appear in an editor composition (the
+     * canvas is client-rendered). Omitted/true = canvas-eligible. Only enforced when
+     * `requireCanvasEligible` is set (i.e. validating a composition value, not a
+     * dev-authored page/layout frame).
+     */
+    clientRenderable?: boolean;
+}
+interface ComponentLookup {
+    has(componentId: string): boolean;
+    get(componentId: string): ManifestView | undefined;
+}
+
+type ParseResult = {
+    ok: true;
+    graph: ProjectGraph;
+} | {
+    ok: false;
+    error: z.ZodError;
+};
+/** Parse a project graph from a JSON string or already-parsed value. Never throws on invalid input. */
+declare function parseProjectGraph(input: string | unknown): ParseResult;
+
+/**
+ * A route record (EC-019, reshaped by EC-187). A path pattern may contain
+ * dynamic segments written `:name` (e.g. `/blog/:slug`). A route maps a concrete
+ * URL to a **render target = a collection + document** via its `document` ref
+ * — `/` → `{ collection: 'page', id: 'home' }`, `/blog/:slug` →
+ * `{ collection: 'post', id: ':slug' }`. The catch-all dispatches on the
+ * resolved document's collection. There is no `templateId`/`pageId` anymore:
+ * page content is a `page`-collection document, not a graph page.
+ */
+declare const routeRecordSchema: z.ZodObject<{
+    id: z.ZodString;
+    pattern: z.ZodString;
+    locale: z.ZodOptional<z.ZodString>;
+    document: z.ZodOptional<z.ZodObject<{
+        collection: z.ZodString;
+        id: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+type RouteRecord = z.infer<typeof routeRecordSchema>;
+/** A redirect record (EC-019/020). */
+declare const redirectRecordSchema: z.ZodObject<{
+    id: z.ZodString;
+    from: z.ZodString;
+    to: z.ZodString;
+    permanent: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>;
+type RedirectRecord = z.infer<typeof redirectRecordSchema>;
+/** Result of `resolveUrl` (EC-019). */
+type ResolveStatus = 'ok' | 'redirect' | 'notFound';
+
+/**
+ * A snapshot of a document at a point in time (EC-021 version history). Stores a
+ * full copy of the document's stored state plus bookkeeping. Snapshots are
+ * immutable records of prior states.
+ */
+declare const documentVersionSchema: z.ZodObject<{
+    version: z.ZodNumber;
+    snapshot: z.ZodObject<{
+        collection: z.ZodString;
+        id: z.ZodString;
+        values: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        localized: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+        defaultLocale: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    createdAt: z.ZodNumber;
+    label: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type DocumentVersion = z.infer<typeof documentVersionSchema>;
+/**
+ * Draft/published primitives + version history for a single document (EC-021).
+ *
+ * Holds the live `draft` state, the last `published` state (if any), and an
+ * ordered history of recorded versions. All mutations return new states or
+ * append history; nothing is silently dropped, and retrieving an unknown
+ * version yields a structured issue rather than throwing.
+ */
+interface DocumentHistory {
+    /** The current working draft. */
+    readonly draft: CmsDocument;
+    /** The last published snapshot, if the document has ever been published. */
+    readonly published: CmsDocument | undefined;
+    /** Recorded versions, oldest first. */
+    readonly versions: readonly DocumentVersion[];
+}
+
+/** Distributive `Omit` that preserves a discriminated union (one variant per member). */
+type DistributiveOmit<T, K extends PropertyKey> = T extends unknown ? Omit<T, K> : never;
+/**
+ * A component prop is a **field-def** (EC-190 "props as fields", AD-12): the SAME
+ * vocabulary the CMS uses for document fields (`@elytracms/cms-core` `FieldDef`) —
+ * text/number/boolean/select/date/relation/asset/richText/blocks — minus the
+ * `name` (the record key on `ComponentManifest.props` IS the prop name). One
+ * schema vocabulary, one inspector/form engine, recursively: a prop of type
+ * `blocks` carries a nested composition. Authoring metadata (label, default,
+ * inline-editing, control hint) lives on the field-def's `form` and `default`.
+ * Use `context: 'prop'` (or `'both'`); document-only attributes (`filterable`,
+ * `unique`) are flagged by cms-core's `assertPropFieldDef`, never silently honoured.
+ */
+type PropField = DistributiveOmit<FieldDef, 'name'>;
+/** A named child insertion point. */
+interface SlotSpec {
+    name: string;
+    label?: string;
+    required?: boolean;
+    /** Restrict which component ids may be inserted (omit to allow any). */
+    allow?: string[];
+}
+/** A deterministic preview fixture for a component state. */
+interface ComponentFixture {
+    name: string;
+    props?: Record<string, JsonValue>;
+    /** Named slots rendered with literal child component ids for preview. */
+    slotChildren?: Record<string, string[]>;
+}
+/** Declares that a component iterates a list prop over an item slot (e.g. Repeater). */
+interface IterateSpec {
+    itemsProp: string;
+    itemSlot: string;
+}
+/**
+ * Declares that a component renders a composition FIELD VALUE (EC-188, AD-12): the
+ * `valueProp` carries a stored composition (one `ComponentNode` root or an ordered
+ * list — a `blocks` field's value), which the renderer renders as the component's
+ * children via `renderComposition`, with the live `RenderContext`. The mirror of
+ * `IterateSpec`: a manifest opts a host component into rendering a composition tree
+ * wherever it is placed (e.g. a post template's body), so the same renderer/export
+ * pipeline that renders pages renders block fields too.
+ */
+interface CompositionSpec {
+    valueProp: string;
+}
+/**
+ * Declares that a component renders a LISTING — a live, query-resolved set of
+ * documents (EC-255, un-parks AD-9 "this section repeats over a collection,
+ * filtered, sorted"). The `prop` receives the matching documents (delivery-shaped),
+ * injected by the host exactly like a composition's children — NOT a static
+ * relation pick the editor maintains by hand. The filter binds the listed
+ * collection's `field` to the ref a SIBLING authored prop (`fromProp`) carries:
+ * a ProductGrid picks one `category`, and the listing lists `product` where its
+ * `categories` (a `many` relation) contains that pick. `sort`/`limit` are the
+ * closed AD-3 query envelope. The mirror of {@link CompositionSpec} for a
+ * query-resolved prop — so the same renderer/export pipeline that renders pages
+ * renders dynamic grids, and adding/removing a member re-renders them.
+ */
+interface ListingSpec {
+    /** Prop the resolved documents are injected as (read by the implementation). */
+    prop: string;
+    /** Collection to list (e.g. `product`). */
+    collection: string;
+    /**
+     * The membership filter: the listed collection's `field` must contain the ref
+     * the sibling authored prop `fromProp` holds (a relation pick, reduced to its
+     * target id). Closed to a single equality/contains term — the AD-3 vocabulary.
+     */
+    filter: {
+        field: string;
+        fromProp: string;
+    };
+    /** Optional single-field sort (ties break by id, like every list — EC-143). */
+    sort?: {
+        field: string;
+        direction?: 'asc' | 'desc';
+    };
+    /** Optional page-size cap. */
+    limit?: number;
+}
+/** The typed manifest each editable component declares (brief §7.2). */
+interface ComponentManifest {
+    /** Namespaced id, e.g. `base.primitives.Stack` or `project.MarketingHero`. */
+    id: string;
+    /** Source namespace: `base.primitives` for platform primitives, `project` for project code. */
+    namespace: string;
+    title?: string;
+    description?: string;
+    category?: string;
+    /** Editable props as field-defs (EC-190), keyed by prop name. */
+    props: Record<string, PropField>;
+    slots: SlotSpec[];
+    /** Design-token usage hints (e.g. `['color.surface', 'space.gap']`). */
+    designTokens?: string[];
+    fixtures?: ComponentFixture[];
+    iterate?: IterateSpec;
+    /** Marks the component as a composition host: `valueProp` holds a block-field tree (EC-188). */
+    composition?: CompositionSpec;
+    /** Marks the component as a listing host: `prop` receives a live query's documents (EC-255). */
+    listing?: ListingSpec;
+    /**
+     * Canvas-eligibility (EC-191). Editors place components on a **client-rendered**
+     * canvas, so a placeable component must be client-renderable (isomorphic React).
+     * Defaults to eligible; set `clientRenderable: false` for a server-only / RSC
+     * component — it stays usable in dev frames (`page.tsx` / `layout.tsx`) but the
+     * blocks panel won't offer it and a composition that contains it is invalid.
+     */
+    clientRenderable?: boolean;
+}
+/** Identity helper that infers nothing but documents intent at call sites. */
+declare function defineComponent(manifest: ComponentManifest): ComponentManifest;
+
+/** Structured issues surfaced by the registry itself (distinct from graph issues). */
+interface ComponentIssue {
+    code: 'duplicate-id' | 'invalid-namespace' | 'invalid-id';
+    componentId: string;
+    message: string;
+}
+
+interface ListFilter {
+    namespace?: string;
+    category?: string;
+    /** Case-insensitive substring match over id / title / category. */
+    query?: string;
+}
+/**
+ * The component registry serves the Builder, renderer, AI tools, export pipeline, and
+ * CLI. It distinguishes platform primitives from project components, supports lookup,
+ * filtering, required lookups, and reports duplicate ids as structured issues.
+ */
+declare class ComponentRegistry {
+    private readonly byId;
+    private readonly viewCache;
+    readonly issues: ComponentIssue[];
+    constructor(manifests?: Iterable<ComponentManifest>);
+    register(manifest: ComponentManifest): void;
+    has(id: string): boolean;
+    getManifest(id: string): ComponentManifest | undefined;
+    /** Required lookup — throws when the component is not registered. */
+    require(id: string): ComponentManifest;
+    list(filter?: ListFilter): ComponentManifest[];
+    /** Platform primitives (`base.primitives.*`). */
+    primitives(): ComponentManifest[];
+    /** Project-level components (everything not under `base.primitives.*`). */
+    projectComponents(): ComponentManifest[];
+    get size(): number;
+    /** A `ComponentLookup` view for the project-graph validator. */
+    get lookup(): ComponentLookup;
+}
+
+/**
+ * A single repeater item scope. When set, `repeaterItem`-mode bindings resolve against
+ * `item` rather than the root data source (brief §4.6 — uniform binding model).
+ */
+interface ItemContext {
+    item: unknown;
+    index: number;
+}
+/**
+ * Resolves a binding to a runtime value. INJECTED by the host (builder preview, export
+ * runtime, tests) so the renderer never imports `@elytracms/data-binding`. When an
+ * `ItemContext` is active, it is passed through so `repeaterItem` bindings resolve
+ * relative to the current item.
+ */
+type ResolveBinding = (ref: BindingReference, item?: ItemContext) => unknown;
+/**
+ * A resolved asset, ready to hand to an image implementation (EC-195). The
+ * delivery-shaped subset of `@elytracms/content`'s `ResolvedAsset` the renderer
+ * needs — kept minimal so the renderer takes no dependency on the content or
+ * persistence packages. `width`/`height` are intrinsic dimensions (so the host
+ * can reserve space and `next/image` can size variants); `null` when unknown.
+ */
+interface RenderAsset {
+    url: string;
+    width: number | null;
+    height: number | null;
+    alt: string | null;
+    /**
+     * Normalized focal point `{ x, y }` in 0–1 (EC-230) → CSS `object-position` so
+     * an art-directed image keeps its subject in frame when cropped; `null` when
+     * none. Kept as a plain pair so the renderer stays free of content/persistence.
+     */
+    focalPoint: {
+        x: number;
+        y: number;
+    } | null;
+}
+/**
+ * A relation target populated to delivery shape (EC-254): identity plus the
+ * target document's resolved fields (relations inside stay `{ id, collection }`
+ * stubs at depth-1; assets inside resolve to objects). Opaque to the renderer —
+ * the host's content layer produces it, the component implementation reads its
+ * fields. The minimal structural face is `{ id, collection }`.
+ */
+type RelationTarget = {
+    id: string;
+    collection: string;
+} & Record<string, unknown>;
+/**
+ * Maps namespaced component ids to their React implementations. Implementations receive
+ * resolved props plus rendered slot children: the default slot `children` maps to React
+ * `children`, and every other named slot is passed as a prop named after the slot.
+ */
+type ComponentImplementations = Record<string, ComponentType<Record<string, unknown>>> | Map<string, ComponentType<Record<string, unknown>>>;
+
+/**
+ * One host-repo component: the manifest the builder edits against plus the
+ * real React implementation that renders it (vision AD-2 — project components
+ * are real code in the host repo, never generated).
+ */
+interface HostComponent {
+    manifest: ComponentManifest;
+    implementation: ComponentType<Record<string, unknown>>;
+}
+/**
+ * The registered component surface a host app hands to `<CanvasRenderer />`
+ * and the catch-all route helper: a manifest registry plus the implementation
+ * map, with registration problems surfaced as structured issues (never
+ * thrown — an unknown component renders the EC-015 fallback).
+ */
+interface HostComponents {
+    registry: ComponentRegistry;
+    implementations: ComponentImplementations;
+    /** Structural registration issues (duplicate ids, invalid namespaces). */
+    issues: readonly ComponentIssue[];
+}
+interface DefineHostComponentsOptions {
+    /**
+     * Include the platform primitives (`base.primitives.*`) that ship with
+     * `@elytracms/runtime-renderer`. Defaults to `true` — graphs authored in the
+     * builder assume them.
+     */
+    includeBasePrimitives?: boolean;
+}
+/**
+ * Component registration API for the embedded runtime (EC-144). The host repo
+ * supplies real implementations + manifests; base primitives are included by
+ * default. A host implementation registered under a primitive id replaces the
+ * default implementation (the manifest of the first registration wins, which
+ * is the primitive's — by design, so prop schemas stay canonical).
+ */
+declare function defineHostComponents(components?: readonly HostComponent[], options?: DefineHostComponentsOptions): HostComponents;
+
+/**
+ * Which side of the draft/published split a delivery request reads from
+ * (EC-021, vision AD-4). `published` never exposes draft content; `draft` is
+ * the editor/preview view.
+ */
+declare const perspectiveSchema: z.ZodEnum<{
+    draft: "draft";
+    published: "published";
+}>;
+type Perspective = z.infer<typeof perspectiveSchema>;
+/**
+ * Ambient request context (vision AD-4): locale and perspective are set once
+ * per request and threaded through every resolution function — never per-call
+ * ceremony. The locale config travels along so EC-018 fallback needs no extra
+ * arguments either.
+ */
+interface ContentContext {
+    /** The locale requested for this delivery (EC-018 fallback applies). */
+    readonly locale: Locale;
+    /** Draft or published perspective (EC-021). */
+    readonly perspective: Perspective;
+    /** The project's locale configuration (default + supported set). */
+    readonly locales: LocaleConfig;
+}
+
+/**
+ * What delivery resolution accepts as a document source: either a bare stored
+ * row (`CmsDocument`, always a working draft — EC-224 retired the `state` flag)
+ * or the full draft/published history (`DocumentHistory`, EC-021) whose
+ * `published` field carries the pinned snapshot. Lookups hand these in;
+ * resolution stays pure — no fetching at this layer.
+ */
+type ContentDocumentSource = CmsDocument | DocumentHistory;
+
+/**
+ * A report entry for one field whose value was served from a different locale
+ * than the one requested (EC-018 default-locale fallback). Paths are rooted at
+ * the resolved document, e.g. `['title']` or `['author', 'bio']` for a field
+ * inside a populated relation.
+ */
+interface FieldLocaleFallback {
+    path: CmsPath;
+    /** The field name (last path segment, repeated for convenience). */
+    field: string;
+    /** The locale the request asked for. */
+    requestedLocale: Locale;
+    /** The locale the value was actually read from. */
+    sourceLocale: Locale;
+}
+
+/**
+ * Which backend a persistence adapter is talking to, and whether it's reachable.
+ * Lets the Studio surface degraded/offline states without leaking provider types.
+ */
+declare const backendKindSchema: z.ZodEnum<{
+    convex: "convex";
+    "in-memory": "in-memory";
+}>;
+type BackendKind = z.infer<typeof backendKindSchema>;
+interface BackendStatus {
+    backend: BackendKind;
+    available: boolean;
+    detail?: string;
+}
+
+/**
+ * An immutable record of one saved graph state (brief §7.1, §10). Each save
+ * appends a revision; the highest revision is the latest. The graph is stored
+ * serialized so reload is provably lossless (serialize → parse round-trip).
+ */
+declare const graphRevisionRecordSchema: z.ZodObject<{
+    id: z.ZodString;
+    projectId: z.ZodString;
+    revision: z.ZodNumber;
+    serializedGraph: z.ZodString;
+    schemaVersion: z.ZodNumber;
+    createdAt: z.ZodString;
+    label: z.ZodOptional<z.ZodString>;
+    message: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type GraphRevisionRecord = z.infer<typeof graphRevisionRecordSchema>;
+/** A revision paired with its parsed graph. */
+interface LoadedGraph {
+    graph: ProjectGraph;
+    revision: GraphRevisionRecord;
+}
+interface SaveGraphOptions {
+    label?: string;
+    message?: string;
+}
+/**
+ * Persists project graphs and their revision history (brief §7.1, §10).
+ * Provider-neutral: an in-memory and a Convex implementation both satisfy it.
+ */
+interface GraphRepository {
+    /** Append a new revision for the project's graph and return it. */
+    saveGraph(projectId: string, graph: ProjectGraph, options?: SaveGraphOptions): Promise<GraphRevisionRecord>;
+    /** Load the latest graph + revision. Throws `RecordNotFoundError` if none. */
+    getLatest(projectId: string): Promise<LoadedGraph>;
+    /** Load a specific revision. Throws `RecordNotFoundError` if absent. */
+    getRevision(projectId: string, revision: number): Promise<LoadedGraph>;
+    /** All revisions for a project, newest first. */
+    listRevisions(projectId: string): Promise<GraphRevisionRecord[]>;
+    /** Whether any graph revision exists for the project. */
+    hasGraph(projectId: string): Promise<boolean>;
+}
+
+/** The persisted CMS schema for a project: its collection definitions (brief §7.4, §10). */
+declare const cmsSchemaRecordSchema: z.ZodObject<{
+    createdAt: z.ZodString;
+    updatedAt: z.ZodString;
+    projectId: z.ZodString;
+    collections: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        kind: z.ZodDefault<z.ZodEnum<{
+            asset: "asset";
+            document: "document";
+        }>>;
+        fields: z.ZodDefault<z.ZodArray<z.ZodType<FieldDef, unknown, z.core.$ZodTypeInternals<FieldDef, unknown>>>>;
+        form: z.ZodOptional<z.ZodObject<{
+            label: z.ZodOptional<z.ZodString>;
+            labelSingular: z.ZodOptional<z.ZodString>;
+            description: z.ZodOptional<z.ZodString>;
+            groups: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            tabs: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        }, z.core.$strip>>;
+        localized: z.ZodOptional<z.ZodBoolean>;
+        titleField: z.ZodOptional<z.ZodString>;
+        singleton: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+type CmsSchemaRecord = z.infer<typeof cmsSchemaRecordSchema>;
+/**
+ * A persisted CMS document. The stored `document` is the continuous working
+ * **draft** (every edit updates it); `publishedVersion` pins which recorded
+ * version is currently live (the Sanity draft/published model, EC-224). Absent
+ * `publishedVersion` means the document has never been published / is unpublished.
+ * Localized variants ride along on the `CmsDocument` itself.
+ */
+declare const cmsDocumentRecordSchema: z.ZodObject<{
+    createdAt: z.ZodString;
+    updatedAt: z.ZodString;
+    projectId: z.ZodString;
+    document: z.ZodObject<{
+        collection: z.ZodString;
+        id: z.ZodString;
+        values: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        localized: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+        defaultLocale: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    publishedVersion: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+type CmsDocumentRecord = z.infer<typeof cmsDocumentRecordSchema>;
+/**
+ * An immutable snapshot of a document at one recorded version (EC-224). Append-only,
+ * mirroring {@link GraphRevisionRecord} but document-scoped: one row per version,
+ * keyed by (projectId, collection, docId, version). Created on publish (the promoted
+ * draft) and by an explicit pre-restore snapshot, never on a plain draft edit.
+ */
+declare const documentVersionRecordSchema: z.ZodObject<{
+    projectId: z.ZodString;
+    collection: z.ZodString;
+    docId: z.ZodString;
+    version: z.ZodNumber;
+    snapshot: z.ZodObject<{
+        collection: z.ZodString;
+        id: z.ZodString;
+        values: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        localized: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+        defaultLocale: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    createdAt: z.ZodString;
+    label: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type DocumentVersionRecord = z.infer<typeof documentVersionRecordSchema>;
+interface SaveDocumentVersionOptions {
+    label?: string;
+}
+/**
+ * Persists CMS collection schemas and documents (brief §7.4, §10). Localized
+ * variants and draft/published state ride along on the `CmsDocument` itself.
+ */
+interface CmsRepository {
+    /** Persist (replace) the project's collection schema; validates structural shape. */
+    saveSchema(projectId: string, collections: readonly CollectionDef[]): Promise<CmsSchemaRecord>;
+    getSchema(projectId: string): Promise<CmsSchemaRecord>;
+    findSchema(projectId: string): Promise<CmsSchemaRecord | undefined>;
+    /** Insert or update a document (keyed by collection + id). */
+    upsertDocument(projectId: string, document: CmsDocument): Promise<CmsDocumentRecord>;
+    getDocument(projectId: string, ref: DocumentRef): Promise<CmsDocumentRecord>;
+    findDocument(projectId: string, ref: DocumentRef): Promise<CmsDocumentRecord | undefined>;
+    /** All documents for a project, optionally filtered to one collection. */
+    listDocuments(projectId: string, collection?: string): Promise<CmsDocumentRecord[]>;
+    deleteDocument(projectId: string, ref: DocumentRef): Promise<void>;
+    /**
+     * Append a snapshot of a document as a new monotonic version (EC-224). Used by
+     * publish (the promoted draft) and the pre-restore snapshot so a rollback is
+     * itself undoable. The (collection, docId) is derived from the snapshot.
+     */
+    saveDocumentVersion(projectId: string, snapshot: CmsDocument, options?: SaveDocumentVersionOptions): Promise<DocumentVersionRecord>;
+    /** All recorded versions for a document, newest first. Empty when none. */
+    listDocumentVersions(projectId: string, ref: DocumentRef): Promise<DocumentVersionRecord[]>;
+    /**
+     * Every recorded version across all documents in a project (EC-224). Backs the
+     * delivery feeders, which reconstruct each document's `DocumentHistory` from
+     * one bulk fetch rather than a per-document query. Order is deterministic
+     * (by document key, then version ascending).
+     */
+    listAllDocumentVersions(projectId: string): Promise<DocumentVersionRecord[]>;
+    /** A specific recorded version. Throws `RecordNotFoundError` if absent. */
+    getDocumentVersion(projectId: string, ref: DocumentRef, version: number): Promise<DocumentVersionRecord>;
+    /**
+     * Pin an existing recorded version live (EC-224 publish). Throws
+     * `RecordNotFoundError` if the document or the version is unknown.
+     */
+    publishDocumentVersion(projectId: string, ref: DocumentRef, version: number): Promise<CmsDocumentRecord>;
+    /**
+     * Clear the live pin (EC-224 unpublish). Throws `PersistenceValidationError`
+     * if the document is not currently published.
+     */
+    unpublishDocument(projectId: string, ref: DocumentRef): Promise<CmsDocumentRecord>;
+}
+
+/**
+ * Persisted asset metadata (brief §7.4, §8.6, §10). The bytes themselves live in
+ * a {@link BlobStorageAdapter}; this record is the queryable metadata that CMS
+ * `asset` fields point at by id.
+ */
+declare const assetRecordSchema: z.ZodObject<{
+    createdAt: z.ZodString;
+    updatedAt: z.ZodString;
+    id: z.ZodString;
+    projectId: z.ZodString;
+    filename: z.ZodString;
+    contentType: z.ZodString;
+    byteSize: z.ZodNumber;
+    width: z.ZodOptional<z.ZodNumber>;
+    height: z.ZodOptional<z.ZodNumber>;
+    alt: z.ZodOptional<z.ZodString>;
+    title: z.ZodOptional<z.ZodString>;
+    storageKey: z.ZodString;
+    url: z.ZodOptional<z.ZodString>;
+    focalPoint: z.ZodOptional<z.ZodObject<{
+        x: z.ZodNumber;
+        y: z.ZodNumber;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+type AssetRecord = z.infer<typeof assetRecordSchema>;
+interface NewAssetInput {
+    id?: string;
+    filename: string;
+    contentType: string;
+    byteSize: number;
+    width?: number;
+    height?: number;
+    alt?: string;
+    /** Editable display title (EC-152 asset library metadata). */
+    title?: string;
+    /** Defaults to a key derived from the asset id. */
+    storageKey?: string;
+    /** Resolvable serve URL for the stored bytes (EC-151). */
+    url?: string;
+    /** Normalized image focal point `{ x, y }` in 0–1 (EC-230). */
+    focalPoint?: {
+        x: number;
+        y: number;
+    };
+}
+/**
+ * Storage boundary for asset *bytes* (brief §8.6). Project-owned and swappable
+ * (Convex file storage, S3, etc.); the in-memory implementation backs tests and
+ * local inspection. Metadata stays in the {@link AssetRepository}.
+ */
+interface BlobStorageAdapter {
+    put(key: string, data: Uint8Array, contentType?: string): Promise<void>;
+    get(key: string): Promise<Uint8Array | undefined>;
+    /** A resolvable locator for the blob (e.g. a CDN/file URL). */
+    url(key: string): string;
+    has(key: string): Promise<boolean>;
+    delete(key: string): Promise<void>;
+    /**
+     * Store bytes under a backend-assigned key and return it (EC-151). Backends
+     * like Convex file storage mint their own ids, so callers cannot choose the
+     * key up front the way {@link put} assumes. Optional; in-memory implements it
+     * deterministically.
+     */
+    store?(data: Uint8Array, contentType?: string): Promise<string>;
+    /**
+     * Mint a short-lived URL the client can POST bytes to directly (EC-151,
+     * Convex `storage.generateUploadUrl()`). Optional — backends without
+     * client-direct uploads omit it and callers fall back to {@link store}/{@link put}.
+     */
+    createUploadUrl?(): Promise<string>;
+    /**
+     * Resolve the serve URL for a stored blob asynchronously (EC-151, Convex
+     * `storage.getUrl()`). Returns `undefined` when the blob does not exist.
+     * Optional; backends with synchronous stable URLs can rely on {@link url}.
+     */
+    resolveUrl?(key: string): Promise<string | undefined>;
+}
+/** Persists asset metadata records (brief §7.4, §8.6, §10). */
+interface AssetRepository {
+    upsertAsset(projectId: string, input: NewAssetInput): Promise<AssetRecord>;
+    getAsset(projectId: string, id: string): Promise<AssetRecord>;
+    findAsset(projectId: string, id: string): Promise<AssetRecord | undefined>;
+    listAssets(projectId: string): Promise<AssetRecord[]>;
+    removeAsset(projectId: string, id: string): Promise<void>;
+    /** Resolve persisted metadata for the asset ids referenced by CMS fields. */
+    resolveMany(projectId: string, ids: readonly string[]): Promise<Map<string, AssetRecord>>;
+}
+
+/**
+ * Publishing state (brief §10). Single-environment (EC-179, vision AD-8): a
+ * deployment IS one environment, so there is exactly ONE publishing-state
+ * record per project. A `published` record pins the graph revision that is
+ * live. Moving a release between environments is a deployment/code-pipeline
+ * concern, not an in-deployment dimension — see `env-is-deployment-boundary`.
+ */
+declare const publishingStateRecordSchema: z.ZodObject<{
+    createdAt: z.ZodString;
+    updatedAt: z.ZodString;
+    projectId: z.ZodString;
+    status: z.ZodEnum<{
+        draft: "draft";
+        published: "published";
+    }>;
+    publishedRevisionId: z.ZodOptional<z.ZodString>;
+    publishedRevision: z.ZodOptional<z.ZodNumber>;
+    publishedAt: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type PublishingStateRecord = z.infer<typeof publishingStateRecordSchema>;
+interface PublishInput {
+    revisionId: string;
+    revision: number;
+}
+/**
+ * Persists and transitions publishing state (brief §10). Transitions are
+ * validated: publishing requires a revision; unpublishing requires a
+ * currently-published deployment.
+ */
+interface PublishingRepository {
+    getState(projectId: string): Promise<PublishingStateRecord>;
+    findState(projectId: string): Promise<PublishingStateRecord | undefined>;
+    /** Publish a graph revision. */
+    publish(projectId: string, input: PublishInput): Promise<PublishingStateRecord>;
+    /** Revert to draft (must currently be published). */
+    unpublish(projectId: string): Promise<PublishingStateRecord>;
+}
+
+/**
+ * Reference-index substrate (EC-155, vision AD-6 / pillar 3.6).
+ *
+ * On every write the operations layer extracts *outbound* references — relation
+ * fields, rich-text link marks and inline refs, page-graph bindings and
+ * component usage, asset usages — into this index, for draft and published
+ * variants separately. One index powers many features: "used by" panels, safe
+ * unpublish (the queryable answer to Sanity's hidden-draft-reference failure),
+ * component/asset where-used, and broken-link audits (UX lands in Milestone B).
+ *
+ * Records are **derived data**: they carry no timestamps and are deterministic
+ * functions of the indexed content, so backfill is idempotent and two runs over
+ * the same data are byte-for-byte identical.
+ */
+/** Which content variant an entry was extracted from (the Sanity failure-case axis). */
+declare const referenceVariantSchema: z.ZodEnum<{
+    draft: "draft";
+    published: "published";
+}>;
+type ReferenceVariant = z.infer<typeof referenceVariantSchema>;
+/**
+ * What kind of entity *holds* the reference. Documents are keyed by their
+ * `documentKey` (`collection:id`); pages/layouts by their graph ids.
+ */
+declare const referenceSourceTypeSchema: z.ZodEnum<{
+    document: "document";
+    page: "page";
+    layout: "layout";
+}>;
+type ReferenceSourceType = z.infer<typeof referenceSourceTypeSchema>;
+declare const referenceSourceSchema: z.ZodObject<{
+    type: z.ZodEnum<{
+        document: "document";
+        page: "page";
+        layout: "layout";
+    }>;
+    id: z.ZodString;
+}, z.core.$strip>;
+type ReferenceSource = z.infer<typeof referenceSourceSchema>;
+declare const referenceTargetSchema: z.ZodObject<{
+    type: z.ZodEnum<{
+        asset: "asset";
+        document: "document";
+        component: "component";
+    }>;
+    id: z.ZodString;
+}, z.core.$strip>;
+type ReferenceTarget = z.infer<typeof referenceTargetSchema>;
+/**
+ * One outbound reference found *inside* a source, before it is attributed to
+ * that source: the exact field/node path, the target, and which structure
+ * produced it. `path` is a `/`-joined token path into the stored value, e.g.
+ * `values/author`, `localized/en/body/doc/content/0/marks/0`,
+ * `root/slots/children/2/props/items/binding`.
+ */
+declare const outboundReferenceSchema: z.ZodObject<{
+    path: z.ZodString;
+    target: z.ZodObject<{
+        type: z.ZodEnum<{
+            asset: "asset";
+            document: "document";
+            component: "component";
+        }>;
+        id: z.ZodString;
+    }, z.core.$strip>;
+    kind: z.ZodEnum<{
+        "relation-field": "relation-field";
+        "asset-field": "asset-field";
+        "rich-text-link": "rich-text-link";
+        "rich-text-node": "rich-text-node";
+        "component-usage": "component-usage";
+        "prop-binding": "prop-binding";
+        "condition-binding": "condition-binding";
+    }>;
+}, z.core.$strip>;
+type OutboundReference = z.infer<typeof outboundReferenceSchema>;
+/** An outbound reference attributed to its holding source entity. */
+declare const referenceEntrySchema: z.ZodObject<{
+    path: z.ZodString;
+    target: z.ZodObject<{
+        type: z.ZodEnum<{
+            asset: "asset";
+            document: "document";
+            component: "component";
+        }>;
+        id: z.ZodString;
+    }, z.core.$strip>;
+    kind: z.ZodEnum<{
+        "relation-field": "relation-field";
+        "asset-field": "asset-field";
+        "rich-text-link": "rich-text-link";
+        "rich-text-node": "rich-text-node";
+        "component-usage": "component-usage";
+        "prop-binding": "prop-binding";
+        "condition-binding": "condition-binding";
+    }>;
+    source: z.ZodObject<{
+        type: z.ZodEnum<{
+            document: "document";
+            page: "page";
+            layout: "layout";
+        }>;
+        id: z.ZodString;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+type ReferenceEntry = z.infer<typeof referenceEntrySchema>;
+/** The persisted index record: entry + project + variant. Derived, timestamp-free. */
+declare const referenceEntryRecordSchema: z.ZodObject<{
+    path: z.ZodString;
+    target: z.ZodObject<{
+        type: z.ZodEnum<{
+            asset: "asset";
+            document: "document";
+            component: "component";
+        }>;
+        id: z.ZodString;
+    }, z.core.$strip>;
+    kind: z.ZodEnum<{
+        "relation-field": "relation-field";
+        "asset-field": "asset-field";
+        "rich-text-link": "rich-text-link";
+        "rich-text-node": "rich-text-node";
+        "component-usage": "component-usage";
+        "prop-binding": "prop-binding";
+        "condition-binding": "condition-binding";
+    }>;
+    source: z.ZodObject<{
+        type: z.ZodEnum<{
+            document: "document";
+            page: "page";
+            layout: "layout";
+        }>;
+        id: z.ZodString;
+    }, z.core.$strip>;
+    projectId: z.ZodString;
+    variant: z.ZodEnum<{
+        draft: "draft";
+        published: "published";
+    }>;
+}, z.core.$strip>;
+type ReferenceEntryRecord = z.infer<typeof referenceEntryRecordSchema>;
+interface ReferenceLookupOptions {
+    /** Restrict the lookup to one variant; omit for both (draft + published). */
+    variant?: ReferenceVariant;
+}
+/**
+ * Persists the reference index (EC-155). Writes are **replace-all-for-source**:
+ * saving an entity recomputes every outbound reference it holds and replaces the
+ * previous set atomically, so edits/deletes/unpublishes can never leave stale
+ * entries behind. Lookups work in both directions with field/node-path
+ * granularity and are variant-aware.
+ */
+interface ReferenceIndexRepository {
+    /**
+     * Replace all entries held by `source` in `variant` with the given outbound
+     * references. An empty list removes the source's entries entirely.
+     */
+    replaceForSource(projectId: string, variant: ReferenceVariant, source: ReferenceSource, references: readonly OutboundReference[]): Promise<ReferenceEntryRecord[]>;
+    /**
+     * Replace all entries held by sources of the given types in `variant` (the
+     * graph recompute path: one revision yields entries across many pages/layouts,
+     * and pages removed from the graph must drop their entries too).
+     */
+    replaceForSourceTypes(projectId: string, variant: ReferenceVariant, sourceTypes: readonly ReferenceSourceType[], entries: readonly ReferenceEntry[]): Promise<ReferenceEntryRecord[]>;
+    /** Remove all entries held by `source` (in one variant, or both when omitted). */
+    removeForSource(projectId: string, source: ReferenceSource, variant?: ReferenceVariant): Promise<void>;
+    /** Outbound: what does `source` reference? */
+    outbound(projectId: string, source: ReferenceSource, options?: ReferenceLookupOptions): Promise<ReferenceEntryRecord[]>;
+    /** Inbound: what references `target`? (The "used by" / safe-unpublish direction.) */
+    inbound(projectId: string, target: ReferenceTarget, options?: ReferenceLookupOptions): Promise<ReferenceEntryRecord[]>;
+    /** Every entry of a project (optionally one variant), deterministically ordered. */
+    listEntries(projectId: string, variant?: ReferenceVariant): Promise<ReferenceEntryRecord[]>;
+    /** Drop the whole index of a project (backfill starts from a clean slate). */
+    clearProject(projectId: string): Promise<void>;
+}
+
+/**
+ * Per-project membership records (EC-150, vision AD-7). The role model is
+ * deliberately minimal for v1 — three roles, project-scoped, no field-level
+ * permissions. Workspace-level grants (who may create projects, default
+ * memberships) land with EC-154; everything here stays project-scoped.
+ *
+ * Roles:
+ * - `viewer`  — read-only: queries succeed, every command is denied.
+ * - `editor`  — edits and publishes content, but cannot administer the project
+ *               (lifecycle, settings, members, CLI tokens).
+ * - `admin`   — everything within the project.
+ *
+ * Enforcement lives at the operations chokepoint
+ * (`@elytracms/operations` `createRoleAuthorization`) and server-side in the
+ * Convex functions (`apps/builder/convex/guard.ts`); this module only defines
+ * the storage contract.
+ */
+declare const projectRoleSchema: z.ZodEnum<{
+    admin: "admin";
+    editor: "editor";
+    viewer: "viewer";
+}>;
+type ProjectRole = z.infer<typeof projectRoleSchema>;
+declare const projectMemberRecordSchema: z.ZodObject<{
+    projectId: z.ZodString;
+    userId: z.ZodString;
+    role: z.ZodEnum<{
+        admin: "admin";
+        editor: "editor";
+        viewer: "viewer";
+    }>;
+    createdAt: z.ZodString;
+    updatedAt: z.ZodString;
+}, z.core.$strip>;
+type ProjectMemberRecord = z.infer<typeof projectMemberRecordSchema>;
+/**
+ * Membership storage boundary. Mirrors the other repository contracts: the
+ * in-memory implementation below and the Convex-backed implementation in
+ * `apps/builder` both satisfy it.
+ */
+interface MembersRepository {
+    /** Upsert a membership (add a member or change their role). */
+    setMember(projectId: string, userId: string, role: ProjectRole): Promise<ProjectMemberRecord>;
+    /** Look up one membership; `undefined` when the user is not a member. */
+    findMember(projectId: string, userId: string): Promise<ProjectMemberRecord | undefined>;
+    /** All members of a project, ordered by userId for determinism. */
+    listMembers(projectId: string): Promise<ProjectMemberRecord[]>;
+    /** All memberships of a user across projects, ordered by projectId. */
+    listMembershipsForUser(userId: string): Promise<ProjectMemberRecord[]>;
+    /** Remove a membership. Throws `RecordNotFoundError` when absent. */
+    removeMember(projectId: string, userId: string): Promise<void>;
+}
+
+/**
+ * Revocable per-project CLI tokens (EC-150). The EC-147 push CLI authenticates
+ * with `Authorization: Bearer <token>`; the builder stores only a SHA-256 hash
+ * of the token (`tokenHash`) — the plaintext is shown exactly once at issuance
+ * and never persisted. Verification (`verifyCliToken` in `@elytracms/operations`)
+ * hashes the presented token and looks it up here; revoked tokens stay stored
+ * (with `revokedAt`) so revocation is auditable and ids stay stable.
+ */
+declare const cliTokenRecordSchema: z.ZodObject<{
+    id: z.ZodString;
+    label: z.ZodString;
+    tokenHash: z.ZodString;
+    createdAt: z.ZodString;
+    revokedAt: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type CliTokenRecord = z.infer<typeof cliTokenRecordSchema>;
+interface NewCliTokenInput {
+    label: string;
+    tokenHash: string;
+}
+/**
+ * Token storage boundary. The in-memory implementation below and the
+ * Convex-backed implementation in `apps/builder` both satisfy it.
+ */
+interface CliTokenRepository {
+    /** Persist a freshly issued token (hash only). */
+    createToken(input: NewCliTokenInput): Promise<CliTokenRecord>;
+    /** All tokens of this deployment (revoked included), ordered by id. */
+    listTokens(): Promise<CliTokenRecord[]>;
+    /** Mark a token revoked (idempotent). Throws `RecordNotFoundError` when absent. */
+    revokeToken(tokenId: string): Promise<CliTokenRecord>;
+    /** Look a token up by its hash — the verification path. */
+    findByHash(tokenHash: string): Promise<CliTokenRecord | undefined>;
+}
+
+/**
+ * Inputs to the backend validation service (brief §4.11, §10). Any subset may be
+ * provided; only supplied domains are validated.
+ */
+interface BackendValidationInput {
+    graph?: ProjectGraph;
+    /** Registry lookup for component/prop/slot checks against the graph. */
+    components?: ComponentLookup;
+    /** Known data-source ids for binding resolution. */
+    knownSourceIds?: ReadonlySet<string>;
+    collections?: readonly CollectionDef[];
+    routes?: readonly RouteRecord[];
+    redirects?: readonly RedirectRecord[];
+    defaultLocale?: string;
+}
+/** Structured, typed validation results returned to clients (brief §4.11). */
+interface BackendValidationResult {
+    ok: boolean;
+    /** Graph + binding + component issues (from `@elytracms/project-graph`). */
+    graphIssues: ValidationIssue[];
+    /** Collection/field schema issues (from `@elytracms/cms-core`). */
+    schemaIssues: CmsValidationIssue[];
+    /** Route conflict + redirect loop issues (from `@elytracms/cms-core`). */
+    routeIssues: CmsValidationIssue[];
+    /** Count of error-severity issues across all domains. */
+    errorCount: number;
+}
+
+/**
+ * The aggregate persistence boundary (brief §4.10, §10). Core packages depend on
+ * this interface — never on Convex directly. A Convex-backed implementation and
+ * the in-memory implementation below both satisfy it, so the Studio, seeds, and
+ * tests are provider-agnostic.
+ */
+interface PersistenceAdapter {
+    readonly graphs: GraphRepository;
+    readonly cms: CmsRepository;
+    readonly assets: AssetRepository;
+    readonly publishing: PublishingRepository;
+    /** Reference index — outbound/inbound reference entries per variant (EC-155, AD-6). */
+    readonly references: ReferenceIndexRepository;
+    /** Per-project membership roles — admin/editor/viewer (EC-150, AD-7). */
+    readonly members: MembersRepository;
+    /** Revocable per-project CLI sync tokens, stored hashed (EC-150). */
+    readonly cliTokens: CliTokenRepository;
+    /** Blob storage boundary for asset bytes. */
+    readonly blobs: BlobStorageAdapter;
+    /** Backend identity + reachability, for degraded-state UI. */
+    status(): Promise<BackendStatus>;
+    /** Server-side validation service (brief §4.11, EC-047). */
+    validate(input: BackendValidationInput): BackendValidationResult;
+}
+
+/**
+ * The delivery shape of an asset (vision AD-4): a directly usable object, not
+ * an id. Optional metadata that the stored record lacks is `null` (never
+ * `undefined`) so resolved documents stay JSON-stable.
+ */
+interface ResolvedAsset {
+    /** The asset id the field stored (kept for cache keys and re-lookup). */
+    id: string;
+    /** Resolvable URL for the asset bytes (EC-044 blob storage locator). */
+    url: string;
+    width: number | null;
+    height: number | null;
+    alt: string | null;
+    mimeType: string;
+    /**
+     * Normalized image focal point `{ x, y }` in 0–1 (EC-230), or `null`. Threaded
+     * to the image primitive's CSS `object-position` so a migrated hotspot keeps
+     * the subject in frame when a layout crops the image (`object-fit: cover`).
+     */
+    focalPoint: {
+        x: number;
+        y: number;
+    } | null;
+}
+
+/**
+ * A document in delivery shape: identity plus resolved field values, flat —
+ * `post.title`, `post.author.name`, `post.cover.url`. The precise per-collection
+ * shape is what `generateDeliveryTypes` emits (EC-142 codegen).
+ */
+type ResolvedDocument = {
+    id: string;
+    collection: string;
+} & Record<string, unknown>;
+/**
+ * The minimal structural face of any delivery-shaped document — what the typed
+ * accessors (EC-143) constrain their per-collection generics against. The
+ * generated interfaces from `generateDeliveryTypes` (e.g. `Post`) satisfy this
+ * where they cannot satisfy `ResolvedDocument`'s index signature.
+ */
+interface DeliveryDocument {
+    id: string;
+    collection: string;
+}
+/**
+ * Structured information about *how* a document was resolved — most notably
+ * which fields served their value via EC-018 locale fallback.
+ */
+interface ResolutionInfo {
+    locale: Locale;
+    perspective: Perspective;
+    localeFallbacks: FieldLocaleFallback[];
+}
+
+/** A scalar a filter can compare against (relation/asset filters use the id). */
+type FilterScalar = string | number | boolean;
+/** One field's filter: every present operator must hold (AND). */
+interface FilterCondition {
+    eq?: FilterScalar;
+    gt?: FilterScalar;
+    gte?: FilterScalar;
+    in?: readonly FilterScalar[];
+    lt?: FilterScalar;
+    lte?: FilterScalar;
+}
+/**
+ * The `where` input: field name → condition. A bare scalar is shorthand for
+ * `{ eq: value }`. Generated per-collection types (`PostWhere`) narrow the
+ * keys to the fields declared `filterable` in the schema.
+ */
+type WhereInput = Readonly<Record<string, FilterScalar | FilterCondition | undefined>>;
+type SortDirection = 'asc' | 'desc';
+/** Single-field sort; ties always break by document id ascending. */
+interface SortInput {
+    field: string;
+    direction?: SortDirection;
+}
+/** The full `listDocuments` query envelope (vision AD-3, rung 3). */
+interface ListDocumentsQuery<TWhere extends WhereInput = WhereInput> {
+    where?: TWhere;
+    sort?: SortInput;
+    limit?: number;
+    cursor?: string;
+}
+/**
+ * Codes for structured accessor query errors (EC-143). These describe *caller*
+ * mistakes (bad filter, bad cursor), as opposed to `CmsValidationIssue`s which
+ * describe content/schema problems. Accessors never throw — invalid queries
+ * come back as an error result carrying these.
+ */
+type ContentQueryErrorCode = 'unknown-collection' | 'list-not-supported' | 'non-filterable-field' | 'invalid-filter' | 'invalid-sort' | 'invalid-limit' | 'invalid-cursor';
+interface ContentQueryError {
+    code: ContentQueryErrorCode;
+    message: string;
+    /** Path into the query input, e.g. ['where', 'title'] or ['sort', 'field']. */
+    path: CmsPath;
+    meta?: Record<string, unknown>;
+}
+
+/**
+ * Cache-tag metadata carried by every accessor result (EC-143, vision AD-5):
+ * fetch-time tagging of what was *actually returned*, so EC-146 can map each
+ * entry to a `revalidateTag` call. Deterministic by construction — every list
+ * is sorted and deduplicated.
+ */
+interface CacheTags {
+    /**
+     * Identities of every document whose content is present in the result —
+     * the returned documents themselves plus their depth-1 populated relation
+     * targets. Entries are `documentKey` strings (`collection:id`), sorted.
+     */
+    docs: string[];
+    /**
+     * Collections the accessor read from (the coarse membership tags of AD-5:
+     * create/delete/publish in a collection sweeps them). Sorted.
+     */
+    collections: string[];
+    /**
+     * Normalized URL paths the accessor touched (`resolvePage` only): the
+     * requested path, plus every hop of a redirect chain — editing any hop
+     * changes the result. Sorted.
+     */
+    routes: string[];
+    /**
+     * Asset ids the result *baked* its delivery shape from (EC-227): the page's
+     * page-scoped `ResolvedAsset` set (url/dimensions/alt) + its `seoOgImage`.
+     * Editing the asset record (alt/dimensions/re-upload) must drop the page that
+     * baked it — without this dimension the only invalidation triggers are
+     * unrelated (doc/collection/project), so an asset-only edit serves stale
+     * until one of those fires. Sorted.
+     */
+    assets: string[];
+    /** The locale the result was resolved for. */
+    locale: Locale;
+}
+
+/**
+ * The closed-form v1 query surface (EC-143, vision AD-3): `resolvePage`,
+ * `getDocument`, `listDocuments` — no query language. Every result is
+ * delivery-shaped (EC-142) and carries deterministic `CacheTags` for EC-146.
+ *
+ * Pure and synchronous like the rest of the package: the client reads through
+ * a `ContentLookup`; EC-144/EC-145 bind it to Convex/Next later. The ambient
+ * `{ locale, perspective }` context is taken once at creation — never per-call
+ * ceremony (per-call `locale` overrides exist for route-level needs only).
+ */
+interface ResolvePageResult {
+    /** Route resolution status (EC-019 parity): ok | redirect | notFound. */
+    status: ResolveStatus;
+    /** The matched route record, when status is `ok`. */
+    route: RouteRecord | null;
+    /** Extracted dynamic params, e.g. `{ slug: 'hello-world' }`. */
+    dynamicParams: Record<string, string>;
+    /** True when route matching fell back to the default locale (EC-018). */
+    localeFallback: boolean;
+    /** Terminal redirect target + permanence, when status is `redirect`. */
+    redirect: {
+        target: string;
+        permanent: boolean;
+    } | null;
+    /**
+     * The document this URL resolves to, delivery-shaped (EC-142, EC-187). A
+     * `page`-collection document (its `body` composition renders into a layout)
+     * or a content-collection document (rendered by a dev route component). SEO
+     * for a page is read from this document's flat `seo*` fields — there is no
+     * separate page-graph `seo` block anymore.
+     */
+    document: ResolvedDocument | null;
+    issues: CmsValidationIssue[];
+    tags: CacheTags;
+}
+interface GetDocumentResult<TDoc extends DeliveryDocument = ResolvedDocument> {
+    /**
+     * The delivery-shaped document, or `null` when not found / not visible in
+     * the context perspective (correct behavior, not an error — see EC-142).
+     */
+    document: TDoc | null;
+    info: ResolutionInfo | null;
+    issues: CmsValidationIssue[];
+    tags: CacheTags;
+}
+type ListDocumentsResult<TDoc extends DeliveryDocument = ResolvedDocument> = {
+    ok: true;
+    documents: TDoc[];
+    /** Cursor for the next page, `null` when this page exhausts the list. */
+    nextCursor: string | null;
+    issues: CmsValidationIssue[];
+    tags: CacheTags;
+} | {
+    /** The query itself was invalid (never thrown — structured errors). */
+    ok: false;
+    errors: ContentQueryError[];
+    tags: CacheTags;
+};
+interface ContentClient {
+    readonly context: ContentContext;
+    /** Structural route issues from construction (conflicts, redirect loops). */
+    readonly routerIssues: readonly CmsValidationIssue[];
+    resolvePage(url: string, locale?: Locale): ResolvePageResult;
+    getDocument<TDoc extends DeliveryDocument = ResolvedDocument>(collection: string, idOrSlug: string, locale?: Locale): GetDocumentResult<TDoc>;
+    listDocuments<TDoc extends DeliveryDocument = ResolvedDocument, TWhere extends WhereInput = WhereInput>(collection: string, query?: ListDocumentsQuery<TWhere>): ListDocumentsResult<TDoc>;
+    /**
+     * Populate a relation reference to depth-1 delivery shape (EC-254), or `null`
+     * when the target is missing or not visible in the active perspective. A
+     * renderer host wires this as `RenderContext.resolveRelation` to populate the
+     * COMPOSITION-NODE relation props of the nodes inside a page's `blocks` field
+     * (e.g. a ProductGrid block's picked `product`s) — which `resolvePage` leaves
+     * raw, since document resolution does not descend into a composition value.
+     */
+    resolveRelation(ref: DocumentRef): ResolvedDocument | null;
+}
+
+/**
+ * Binding payloads for the embedded runtime (EC-144): one payload value per
+ * binding `sourceId`. The catch-all route helper provides `document` (the
+ * route-bound resolved document) and `params` (dynamic route params) by
+ * default; hosts add more through the route helper's `payloads` factory
+ * (e.g. a `listDocuments` result for a posts repeater).
+ *
+ * This is a deliberately small, pure resolver — the embedded runtime never
+ * imports `@elytracms/data-binding` (a builder-side package). Semantics mirror
+ * EC-023 tokens: a binding token is a JSON Pointer (RFC 6901) into the
+ * payload; a miss resolves to `undefined`, never a throw (the renderer turns
+ * unresolvable bindings into visible fallback behavior, EC-015).
+ */
+type BindingPayloads = Record<string, unknown>;
+/**
+ * Marker key of an {@link SourcePayloadError} payload. A plain string property
+ * (not a Symbol) on purpose: the route helper's cached path JSON-serializes
+ * payloads through `unstable_cache`, and the marker must survive that
+ * round-trip.
+ */
+declare const SOURCE_PAYLOAD_ERROR_KEY = "__elytraSourcePayloadError";
+/**
+ * Explicit issue payload for a source whose stored query was REJECTED at
+ * delivery (EC-177 gap 3) — e.g. a sort/filter field that is no longer
+ * filterable in the live schema. Materialization stores this instead of a
+ * silently-absent payload; `createBindingResolver` throws on it, which the
+ * renderer converts into its visible per-node render-error fallback (EC-015).
+ * Validation principle: a broken stored query is a visible state, never an
+ * empty section.
+ */
+interface SourcePayloadError {
+    [SOURCE_PAYLOAD_ERROR_KEY]: true;
+    sourceId: string;
+    /** Human-readable messages of the structured query errors. */
+    messages: string[];
+}
+/** Build the explicit issue payload for one failed source query. */
+declare function sourcePayloadError(sourceId: string, messages: readonly string[]): SourcePayloadError;
+/** `true` when a payload value is an explicit {@link SourcePayloadError}. */
+declare function isSourcePayloadError(value: unknown): value is SourcePayloadError;
+/**
+ * Resolve a JSON Pointer token within a payload value. Numeric segments index
+ * arrays; string segments index plain objects. Any miss (unknown key,
+ * out-of-range index, traversal through a primitive) yields `undefined`.
+ */
+declare function resolvePayloadToken(payload: unknown, token: string): unknown;
+/**
+ * Create the renderer's `ResolveBinding` over a payload map. Mode semantics
+ * (brief §4.6, uniform binding model):
+ *
+ * - `value` / `object` / `condition` — the value at the token within the
+ *   payload named by `sourceId`.
+ * - `spread` — same lookup; the renderer spreads the resulting object.
+ * - `repeaterItem` — the token resolves against the active repeater item,
+ *   not the root payload.
+ *
+ * Total for data misses: an unknown `sourceId` or missing path resolves to
+ * `undefined` — the renderer (EC-015) degrades visibly instead of crashing.
+ * An explicit {@link SourcePayloadError} payload (a REJECTED stored query, not
+ * merely missing data) throws instead: the renderer catches per node and
+ * renders its visible render-error fallback with the query error message;
+ * conditions treat the throw as `false` (the node hides) — never a page crash.
+ */
+declare function createBindingResolver(payloads: BindingPayloads): ResolveBinding;
+
+/**
+ * `<CanvasRenderer />` (EC-144, vision AD-1): an async React Server Component
+ * that renders a resolved page (from `resolvePage`, EC-143) through
+ * `@elytracms/runtime-renderer` with the host app's component registry. EC-015
+ * fallback behavior is identical to the builder: a missing component, invalid
+ * prop, or missing required slot renders a visible fallback — a page never
+ * crashes and never silently omits a node.
+ */
+interface CanvasRendererProps {
+    /** The `resolvePage` result for the current URL. */
+    result: ResolvePageResult;
+    /** Host component surface from `defineHostComponents`. */
+    components: HostComponents;
+    /**
+     * The full project graph for the active perspective (from
+     * `ContentSource.graph`). Needed for layout composition; without it the
+     * page root renders without its layout.
+     */
+    graph?: ProjectGraph | null;
+    /**
+     * Binding payloads keyed by `sourceId`. Defaults to
+     * `{ document, params }` derived from the result.
+     */
+    payloads?: BindingPayloads;
+    /** Full custom binding resolver — overrides `payloads` when provided. */
+    resolveBinding?: ResolveBinding;
+    /**
+     * Delivery-shaped assets the page may reference (EC-195, from the render
+     * outcome). An `asset`-typed Image prop resolves through these to a url +
+     * intrinsic dimensions; an unknown id degrades to the visible fallback.
+     */
+    assets?: readonly ResolvedAsset[];
+    /**
+     * Populated composition-node `relation` props, keyed `collection:id` (EC-254,
+     * from the render outcome). A block's `relation` prop (e.g. a ProductGrid's
+     * picked products) resolves through these to the populated target; an unknown
+     * key degrades to the block's own empty state. Absent → relation props pass
+     * through unresolved (raw ref), the same degradation as a missing asset list.
+     */
+    relations?: Record<string, RelationTarget>;
+    /**
+     * Documents each `listing` block resolved to, keyed by serialized query (EC-255,
+     * from the render outcome). A ProductGrid keyed to a picked `category` reads its
+     * products through this; an unknown key (or absent map) degrades to the block's
+     * own empty state — the same degradation as a missing relation.
+     */
+    listings?: Record<string, RelationTarget[]>;
+}
+/** Default payloads: the route-bound document and the dynamic route params. */
+declare function defaultBindingPayloads(result: ResolvePageResult): BindingPayloads;
+/**
+ * Render a resolved page server-side. Async so hosts can compose it like any
+ * other RSC; resolution itself is synchronous (the content was prefetched by
+ * the `ContentSource`).
+ */
+declare function CanvasRenderer(props: CanvasRendererProps): Promise<ReactNode>;
+
+/**
+ * The content seam of the embedded runtime (EC-144, vision AD-1/AD-4): the
+ * catch-all route helper consumes this interface, so where the content comes
+ * from is swappable. EC-144 ships the in-memory snapshot bridge
+ * (`createContentSnapshot` over a `PersistenceAdapter`); EC-145/146 plug a
+ * Convex-backed source into the exact same seam.
+ *
+ * Accessors are synchronous over a prefetched `ContentLookup` (vision AD-4);
+ * any fetching happens when the source is loaded, before clients are minted.
+ */
+/**
+ * One data-source definition the published graph's bindings reference
+ * (EC-166 delivery): the structural shape of an `@elytracms/data-binding`
+ * `DataSource`, declared here so the embedded runtime stays free of
+ * builder-side packages. Only `cms`-kind sources with the EC-166 per-scope id
+ * prefixes (`cms.section.<nodeId>` / `cms.template.<pageId>`) participate in
+ * automatic payload materialization; everything else is ignored.
+ */
+interface CanvasDataSource {
+    kind: string;
+    id: string;
+    label?: string;
+    /** Kind-specific config; cms query configs parse via `@elytracms/content`. */
+    config?: unknown;
+}
+interface ContentSource {
+    /** The project's locale configuration (default + supported set, EC-018). */
+    readonly locales: LocaleConfig;
+    /**
+     * Mint a typed accessor client (EC-143) bound to a perspective. The locale
+     * defaults to the project default; the route helper overrides it per
+     * request from the URL's locale prefix.
+     */
+    client(init: {
+        perspective: Perspective;
+        locale?: Locale;
+    }): ContentClient;
+    /**
+     * The full project graph visible in a perspective — `draft` is the latest
+     * working revision, `published` the revision pinned by publishing state.
+     * `null` when nothing is visible (e.g. never published). The renderer needs
+     * the graph (not just the page) for layout composition.
+     */
+    graph(perspective: Perspective): ProjectGraph | null;
+    /**
+     * The route records the source's clients resolve against (EC-171, additive).
+     * Lets enumerating consumers — the sitemap helper — walk the same route
+     * table `resolvePage` uses, instead of keeping a second list. Optional so
+     * existing custom sources stay valid; without it the sitemap helper needs
+     * explicit routes.
+     */
+    readonly routes?: readonly RouteRecord[];
+    /**
+     * Data-source definitions the graph's bindings reference (EC-166 delivery,
+     * additive). When present, the route helper materializes per-section list
+     * sources automatically by replaying their stored where/sort/limit through
+     * `listDocuments` — see `materializeSourcePayloads`. Optional so existing
+     * custom sources stay valid; absent definitions degrade to unresolved
+     * bindings (the renderer's visible fallbacks), never a crash.
+     */
+    readonly sources?: readonly CanvasDataSource[];
+    /**
+     * The project's delivery-shaped assets (EC-195, additive). Lets the route
+     * helper bake the assets a page may reference into the (serializable) render
+     * outcome, so the renderer can resolve an `asset`-typed Image prop to a usable
+     * url + intrinsic dimensions — and a cached page keeps its images during a
+     * backend outage. Optional so existing custom sources stay valid; without it,
+     * asset-typed props fall back to their raw value (the renderer's visible
+     * degradation), never a crash.
+     */
+    assets?(): readonly ResolvedAsset[];
+}
+/**
+ * Merge accessor cache tags into one deterministic set (sorted, deduplicated)
+ * — used by the route helper to combine the `resolvePage` tags with tags
+ * added by the host's payload factory (e.g. a `listDocuments` call). The
+ * merged set is what the EC-146 `onTags` hook receives.
+ */
+declare function mergeCacheTags(first: CacheTags, ...rest: readonly CacheTags[]): CacheTags;
+
+/**
+ * Automatic payload materialization for EC-166 repeating sections — the
+ * delivery half of the builder's collection-driven LAYOUTS (EC-187: layouts
+ * are the only graph trees that can bind section sources now). A published
+ * layout may carry bindings against per-scope CMS sources; the renderer needs
+ * the source PAYLOADS:
+ *
+ * - **Repeating sections** (`cms.section.<nodeId>`): the stored source config
+ *   carries the closed AD-3 query. For every section source a referenced
+ *   layout tree actually binds, the stored where/sort/limit replays through
+ *   the request client's `listDocuments` — published perspective and ambient
+ *   locale come from the client itself. The list result's `CacheTags` (the
+ *   fetch-time doc tags of what was actually returned plus the coarse
+ *   collection tag — the EC-146 contract) are surfaced so the route helper
+ *   merges them into the request tag set.
+ *
+ * The `cms.template.<pageId>` "current document" source is RETIRED (EC-187):
+ * there is no template page, and a routed page document's `body` uses static
+ * props (v1). A collection detail route's document is read by the dev route
+ * component directly via the route's `document` ref.
+ *
+ * Everything degrades visibly, never a crash:
+ *
+ * - a missing source definition, a non-cms kind, or a malformed config leaves
+ *   the payload absent, so the binding resolves to `undefined` and the
+ *   renderer shows its EC-015 fallback (an empty list renders the section's
+ *   empty state);
+ * - a structured query error (the stored query was REJECTED at delivery, e.g.
+ *   a sort field no longer filterable in the live schema) stores an explicit
+ *   {@link sourcePayloadError} payload instead — the binding resolver throws
+ *   on it and the renderer shows its visible per-node render-error fallback,
+ *   not a silently empty section (EC-177 gap 3).
+ */
+/** Collect every binding `sourceId` referenced in a node tree (props, conditions, slots). */
+declare function collectBindingSourceIds(node: ComponentNode, into?: Set<string>): Set<string>;
+interface MaterializeSourcePayloadsInput {
+    /** Accessor client bound to this request's perspective + locale. */
+    client: ContentClient;
+    result: ResolvePageResult;
+    /** The graph for the active perspective (layout trees may bind sections too). */
+    graph: ProjectGraph | null;
+    /** Source definitions from the `ContentSource` (absent ones simply skip). */
+    sources: readonly CanvasDataSource[];
+}
+interface MaterializedSourcePayloads {
+    payloads: BindingPayloads;
+    /** `CacheTags` of every accessor call made here (one entry per section list). */
+    tags: CacheTags[];
+}
+/**
+ * Materialize the EC-166 source payloads for one resolved page. Pure over the
+ * prefetched source — `listDocuments` is synchronous; tags are returned (not
+ * applied) so the caller owns the merge.
+ */
+declare function materializeSourcePayloads(input: MaterializeSourcePayloadsInput): MaterializedSourcePayloads;
+
+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;
+    /**
+     * Data-source definitions the graph's bindings reference (EC-166): section
+     * sources (`cms.section.<nodeId>`) carry their stored where/sort/limit, and
+     * the route helper materializes their payloads automatically.
+     */
+    sources?: readonly CanvasDataSource[];
+}
+interface ContentSnapshot extends ContentSource {
+    readonly projectId: string;
+}
+/**
+ * Plain prefetched data for {@link createStaticContentSource} (EC-156): the
+ * same inputs `createContentSnapshot` reads from a `PersistenceAdapter`, as
+ * already-loaded values. Everything content-bearing is optional — an absent
+ * piece simply resolves to "not visible", with the runtime's explicit
+ * fallbacks (never a crash).
+ */
+interface StaticContentData {
+    projectId: string;
+    /** Locale configuration; defaults to English-only. */
+    locales?: LocaleConfig;
+    /** Route records served by `resolvePage` (EC-019). */
+    routes?: readonly RouteRecord[];
+    /** Redirect records served by `resolvePage` (EC-019/020). */
+    redirects?: readonly RedirectRecord[];
+    collections?: readonly CollectionDef[];
+    /**
+     * Stored document sources. Either a bare `CmsDocument` (gated by its own
+     * `state`) or a `DocumentHistory` carrying the live draft + the pinned
+     * published snapshot (EC-224). Perspective gating happens in the pure
+     * accessors (`selectPerspective`, EC-142): a `published` client sees a
+     * history's pinned snapshot (or nothing), and never a bare `draft` row.
+     */
+    documents?: readonly ContentDocumentSource[];
+    assets?: readonly AssetRecord[];
+    /**
+     * The graph visible per perspective: `draft` is the latest working
+     * revision, `published` the revision pinned by publishing state. `null` /
+     * absent means "nothing visible in that perspective".
+     */
+    graphs?: {
+        draft?: ProjectGraph | null;
+        published?: ProjectGraph | null;
+    };
+    /**
+     * Resolve a serve URL for assets without a stored `url`. Defaults to an
+     * explicit unresolved-placeholder scheme (never a silent empty string).
+     */
+    assetUrl?: (asset: AssetRecord) => string;
+    /**
+     * Data-source definitions the graph's bindings reference (EC-166 delivery).
+     * Absent definitions degrade to unresolved bindings, never a crash.
+     */
+    sources?: readonly CanvasDataSource[];
+}
+/**
+ * Merge stored route records with derived fallback routes (EC-177 gap 2):
+ * stored records win per pattern+locale; fallback routes only fill patterns
+ * the stored set does not cover. Never XOR — the first stored route must not
+ * drop the implicit per-locale home-page fallback (or vice versa).
+ *
+ * Coverage rules mirror the router's locale matching (EC-018/019): a stored
+ * locale-agnostic route (no `locale`) covers its pattern for every locale; a
+ * locale-specific stored route covers only that locale, so fallbacks for the
+ * other locales still apply.
+ */
+declare function mergeRouteRecords(stored: readonly RouteRecord[], fallback: readonly RouteRecord[]): RouteRecord[];
+/**
+ * Assemble a `ContentSource` from plain prefetched data — the pure half of
+ * {@link createContentSnapshot}, shared with hosts that fetched the data
+ * themselves (e.g. the EC-156 live delivery snapshot). Accessor semantics are
+ * byte-identical across both paths: the same `ContentLookup` feeds the same
+ * pure `@elytracms/content` client.
+ */
+declare function createStaticContentSource(data: StaticContentData): ContentSnapshot;
+/**
+ * Prefetch a project's content from a `PersistenceAdapter` into an in-memory
+ * `ContentSource`. The snapshot is a point-in-time view: load once per
+ * 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 pure half of the catch-all route helper (EC-144): URL → outcome, with
+ * no Next.js imports — so redirects, 404s, locale handling, payload assembly,
+ * and tag merging are all unit-testable as plain functions. `route.tsx` maps
+ * each outcome onto `redirect()` / `permanentRedirect()` / `notFound()` /
+ * `<CanvasRenderer />`.
+ */
+/** What the host's payload factory sees for one request. */
+interface CanvasPayloadContext {
+    /** Accessor client bound to this request's perspective + locale. */
+    client: ContentClient;
+    result: ResolvePageResult;
+    perspective: Perspective;
+    /** The normalized request path (locale prefix stripped). */
+    path: string;
+    params: Record<string, string>;
+    /**
+     * Register the `CacheTags` of any extra accessor call this factory makes
+     * (e.g. `listDocuments`) so they join the request's merged tag set — the
+     * EC-146 invalidation hook sees everything the request actually read.
+     */
+    addTags(tags: CacheTags): void;
+}
+/**
+ * Builds the binding payloads for a page render. The defaults
+ * (`document`, `params`) are always present; factory entries win on conflict.
+ */
+type CanvasPayloadsFactory = (ctx: CanvasPayloadContext) => BindingPayloads | Promise<BindingPayloads>;
+type CanvasPageOutcome = {
+    kind: 'redirect';
+    target: string;
+    permanent: boolean;
+    tags: CacheTags;
+} | {
+    kind: 'not-found';
+    tags: CacheTags;
+} | {
+    kind: 'render';
+    result: ResolvePageResult;
+    graph: ProjectGraph | null;
+    payloads: BindingPayloads;
+    /**
+     * The delivery-shaped assets the page may reference (EC-195). Baked into
+     * the outcome (serializable) so the renderer resolves `asset`-typed Image
+     * props to a url + intrinsic dimensions, and a cached page keeps its
+     * images during a backend outage.
+     */
+    assets: readonly ResolvedAsset[];
+    /**
+     * The composition-node `relation` props this page references, populated to
+     * depth-1 delivery shape and keyed `collection:id` (EC-254). Baked into the
+     * outcome (serializable) so `<CanvasRenderer />` rebuilds
+     * `RenderContext.resolveRelation` from it inside the RSC — a function (the
+     * content client) cannot ride the data cache or cross the RSC boundary, so
+     * the data is baked exactly as the page-scoped `assets` list is.
+     */
+    relations: Record<string, RelationTarget>;
+    /**
+     * The documents each `listing` block on this page resolved to (EC-255),
+     * keyed by serialized query. Baked into the outcome (serializable) so
+     * `<CanvasRenderer />` rebuilds `RenderContext.resolveListing` from it inside
+     * the RSC — like `relations`, because the content client that runs the query
+     * cannot ride the data cache or cross the RSC boundary. A listing depends on
+     * collection MEMBERSHIP (a product joining/leaving the category), so its
+     * invalidation rides the per-query `listDocuments` tags merged into `tags`.
+     */
+    listings: Record<string, RelationTarget[]>;
+    tags: CacheTags;
+};
+/** Build the request path from a Next catch-all `slug` param. */
+declare function pathFromSlug(slug: readonly string[] | undefined): string;
+/**
+ * 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 ResolveCanvasPageOptions {
+    payloads?: CanvasPayloadsFactory;
+    /**
+     * Component registry (EC-205): when provided, the baked {@link CanvasPageOutcome}
+     * `assets` are PAGE-SCOPED to exactly the asset ids this page's composition +
+     * layout resolve through `resolveAsset` — not the whole project asset list,
+     * which otherwise rides in every page's cache entry + RSC payload. Omitted →
+     * all source assets (back-compat). Scoping mirrors the renderer's asset
+     * resolution exactly, so no referenced image is ever dropped.
+     */
+    registry?: ComponentRegistry;
+}
+/**
+ * Resolve one request URL against a content source: split the locale, run
+ * `resolvePage` in the requested perspective, assemble binding payloads, and
+ * merge every accessor's `CacheTags` into one deterministic set. Pure — all
+ * data was prefetched by the source.
+ */
+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
+     * id the studio publishes under, so the webhook dispatcher's tags match.
+     * Omit only when the emitter also emits unscoped tags (see `cache.ts`).
+     */
+    scope?: string;
+}
+/**
+ * What the route helper tells the content loader about the request it is
+ * loading for (EC-156). Loaders that serve both perspectives from one
+ * prefetched source (the fixture snapshot) can ignore it; a live loader uses
+ * it to fetch the draft-perspective snapshot only for draft-mode requests —
+ * it must NOT call request APIs like `draftMode()` itself, because on the
+ * cached published path the loader runs inside `unstable_cache`, where
+ * dynamic request APIs are unavailable.
+ */
+interface CanvasContentRequest {
+    perspective: Perspective;
+}
+interface CanvasRouteOptions {
+    /**
+     * Async content loader — the seam EC-145/146 plug Convex into. For the
+     * fixture-backed example this memoizes a `createContentSnapshot` call.
+     * Invoked per request; cache/memoize inside the loader as appropriate.
+     * With `cache` configured it only runs on a cache miss (once per
+     * revalidation cycle) — cache hits never touch the content backend.
+     * Receives the request's perspective (see {@link CanvasContentRequest});
+     * zero-arg loaders remain valid.
+     */
+    loadContent: (request: CanvasContentRequest) => Promise<ContentSource>;
+    /** Host component surface from `defineHostComponents`. */
+    components: HostComponents;
+    /** Extra binding payloads per request (e.g. `listDocuments` for a list page). */
+    payloads?: CanvasPayloadsFactory;
+    /**
+     * EC-146 instant publish: cache the published-perspective resolution in
+     * Next's data cache (`unstable_cache`), tagged with the response's own
+     * fetch-time tags, invalidated by the `/api/revalidate` webhook. Draft mode
+     * always bypasses this cache entirely. Tag-driven only — no time-based
+     * revalidation (the AD-5 model). Cached values are JSON-serialized, so
+     * payload factories must return plain data on the cached path.
+     */
+    cache?: CanvasCacheOptions;
+    /**
+     * EC-146 hook: receives the merged `CacheTags` of everything this request
+     * read (the `resolvePage` tags plus any tags the payload factory
+     * registered via `addTags`). On a cache hit these are the stored tags of
+     * the run that wrote the entry.
+     */
+    onTags?: (tags: CacheTags, info: CanvasRequestInfo) => void;
+    /** Override the generated `<head>` metadata for a resolved page. */
+    metadata?: (result: ResolvePageResult, info: CanvasRequestInfo) => Metadata;
+}
+interface CanvasRouteProps {
+    params: Promise<{
+        slug?: string[];
+    }>;
+}
+interface CanvasRoute {
+    /** The page component: `export default route.Page`. */
+    Page: (props: CanvasRouteProps) => Promise<ReactNode>;
+    /** Next metadata hook: `export const generateMetadata = route.generateMetadata`. */
+    generateMetadata: (props: CanvasRouteProps) => Promise<Metadata>;
+}
+/** Create the `{ Page, generateMetadata }` pair for `app/[[...slug]]/page.tsx`. */
+declare function createCanvasRoute(options: CanvasRouteOptions): CanvasRoute;
+
+declare function canvasPageMetadata(result: ResolvePageResult, assets?: readonly ResolvedAsset[]): Metadata;
+
+/**
+ * `sitemap.xml` from published routes (EC-171): walk the same route records
+ * `resolvePage` resolves against, resolve every candidate URL in the
+ * **published** perspective, and emit `MetadataRoute.Sitemap` entries per
+ * locale — Next's `app/sitemap.ts` convention. Pages marked `noindex` (and
+ * URLs that do not resolve, e.g. a page that was never published) are
+ * omitted.
+ *
+ * Dynamic routes (`/blog/:slug`): a route record does not declare which
+ * collection feeds its params, so enumeration is delegated to the host's
+ * {@link SitemapParamsProvider} — it gets a published-perspective accessor
+ * client and returns one param record per concrete URL (typically from
+ * `listDocuments`). **Honest limit:** parameterized routes without a provider
+ * (or provider entries missing a param) are skipped and reported in
+ * `skipped`, never guessed. `lastModified` is omitted — the delivery shape
+ * carries no per-page timestamps today.
+ *
+ * Hierarchy mounts (`/:path*`, EC-218): a page-tree mount self-describes its
+ * URLs, so it is enumerated automatically from the collection's published
+ * documents (composing each page's nested path from its parent chain) — no
+ * params provider entry needed.
+ *
+ * Host usage (`app/sitemap.ts`):
+ *
+ * ```ts
+ * import { createCanvasSitemap } from '@elytracms/next'
+ * import { loadContent } from '../lib/content'
+ *
+ * export default createCanvasSitemap({
+ *   loadContent,
+ *   baseUrl: 'https://example.com',
+ *   params: ({ route, client }) =>
+ *     route.id === 'r-post'
+ *       ? (client.listDocuments('post').ok ? … : []) // slug per published post
+ *       : null,
+ * })
+ * ```
+ */
+interface SitemapRouteContext {
+    route: RouteRecord;
+    locale: Locale;
+    /** Published-perspective accessor client bound to `locale`. */
+    client: ContentClient;
+}
+/**
+ * Enumerate the param sets of one dynamic route — one record per concrete
+ * URL (e.g. `[{ slug: 'hello-world' }, …]`). Return `null`/`undefined` to
+ * skip the route (reported in `skipped`).
+ */
+type SitemapParamsProvider = (ctx: SitemapRouteContext) => readonly Record<string, string>[] | null | undefined;
+interface CanvasSitemapOptions {
+    /** Absolute site origin, e.g. `https://example.com` (no trailing slash needed). */
+    baseUrl: string;
+    /** Route records to enumerate; defaults to the source's own route table. */
+    routes?: readonly RouteRecord[];
+    /** Param enumeration for dynamic routes (see {@link SitemapParamsProvider}). */
+    params?: SitemapParamsProvider;
+}
+interface SitemapSkippedRoute {
+    routeId: string;
+    pattern: string;
+    reason: string;
+}
+interface CanvasSitemapResult {
+    entries: MetadataRoute.Sitemap;
+    /** Routes that could not be enumerated — explicit, never silent. */
+    skipped: SitemapSkippedRoute[];
+}
+/**
+ * Enumerate the sitemap entries of one content source (published
+ * perspective). Pure over the prefetched source — synchronous accessors,
+ * deterministic ordering (sorted by URL).
+ */
+declare function canvasSitemapEntries(source: ContentSource, options: CanvasSitemapOptions): CanvasSitemapResult;
+interface CreateCanvasSitemapOptions extends CanvasSitemapOptions {
+    /** The same content loader the catch-all route uses (published perspective). */
+    loadContent: (request: {
+        perspective: 'published';
+    }) => Promise<ContentSource>;
+}
+/**
+ * The `app/sitemap.ts` one-liner: `export default createCanvasSitemap({ … })`.
+ * Loads the published content source and returns the enumerated entries
+ * (skipped routes are dropped here — use {@link canvasSitemapEntries} to
+ * inspect them).
+ */
+declare function createCanvasSitemap(options: CreateCanvasSitemapOptions): () => Promise<MetadataRoute.Sitemap>;
+
+/**
+ * Cache-tag pipeline (EC-146, vision AD-5) — the pure half.
+ *
+ * This module defines (a) the **canonical Next.js tag string format** mapping
+ * the accessor-level `CacheTags` (EC-143) onto `revalidateTag` keys, and (b)
+ * the **tag-discovery caching logic** the catch-all route helper runs inside
+ * `unstable_cache`. No Next.js imports — everything here is unit-testable;
+ * `route.tsx` injects the real `unstable_cache` via {@link CacheWrapper}.
+ *
+ * ## Tag format
+ *
+ * - `doc:<collection>:<id>` — one per document whose content was actually in
+ *   the response (fetch-time tagging: includes depth-1 populated relation
+ *   targets, and documents inside filtered/dynamic lists *after* the filter
+ *   ran).
+ * - `collection:<name>:<locale>` — the coarse membership tag: every response
+ *   that read from a collection carries it, so create/delete/newly-matching
+ *   documents sweep cached lists without read-set tracking.
+ * - `route:<pattern>:<locale>` — the resolved URL path plus every hop of a
+ *   redirect chain.
+ * - `asset:<id>` — one per asset whose delivery shape the page *baked*
+ *   (page-scoped images + `seoOgImage`, EC-227); editing that asset record
+ *   (alt/dimensions/re-upload) drops exactly the pages that baked it. Not
+ *   locale-scoped — an asset record is locale-agnostic.
+ * - `project` — the whole-project sweep tag attached to **every** cached
+ *   entry; graph publish/unpublish emits it (a layout or route change can
+ *   affect any page, so the honest v1 fallback is a full project sweep).
+ *
+ * ## Project scope
+ *
+ * Every tag is prefixed `p:<projectId>:` when a scope is configured (e.g.
+ * `p:prj_aurora:doc:post:post-1`). The cost is a few bytes per tag and it
+ * keeps multi-project hosts (one Next app serving several builder projects)
+ * from cross-invalidating, so the prefix is **on whenever the host knows its
+ * project id** — decision: include it. The emitter (the studio's webhook
+ * dispatcher, `apps/builder/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
+ * both sides pin the exact literal strings to keep them in lock-step.
+ */
+/** Apply the optional multi-project scope prefix to one tag. */
+declare function scopeCacheTag(tag: string, scope?: string): string;
+/**
+ * Tag for one document identity. `docKey` is the EC-143 `documentKey` string
+ * (`<collection>:<id>`), exactly as found in `CacheTags.docs`.
+ */
+declare function docCacheTag(docKey: string, scope?: string): string;
+/** The coarse membership tag of one collection in one locale. */
+declare function collectionCacheTag(collection: string, locale: string, scope?: string): string;
+/** Tag for one resolved route path (or redirect-chain hop) in one locale. */
+declare function routeCacheTag(pattern: string, locale: string, scope?: string): string;
+/**
+ * The whole-project sweep tag. Attached to every cached page entry; emitted
+ * on graph publish/unpublish (and as the emitter's honest fallback when a
+ * change's precise tag set is unknowable).
+ */
+declare function projectSweepTag(scope?: string): string;
+/**
+ * Map an accessor-level `CacheTags` (what one request actually read) onto the
+ * full, deterministic (sorted, deduplicated) set of Next tag strings for the
+ * cache entry — including the project sweep tag.
+ */
+declare function nextCacheTags(tags: CacheTags, scope?: string): string[];
+/**
+ * The slice of `unstable_cache` the discovery logic needs, injectable so the
+ * logic is testable against a faithful in-memory model (and so the test model
+ * can mirror the real semantics this design depends on — see below).
+ */
+interface CacheWrapperOptions {
+    tags: string[];
+    /** `false` = never expire by time (tag-driven invalidation only). */
+    revalidate: number | false;
+}
+type CacheWrapper = <T>(cb: () => Promise<T>, keyParts: string[], options: CacheWrapperOptions) => () => Promise<T>;
+/** What one cached request stores: the outcome plus its own discovered tags. */
+interface CachedEntry<T> {
+    value: T;
+    /** The Next tag strings discovered at fetch time by the run that wrote this entry. */
+    tags: string[];
+}
+/**
+ * Fetch-time tag discovery over `unstable_cache` — the heart of EC-146.
+ *
+ * The problem: `unstable_cache` fixes an entry's tags when the *wrapper* is
+ * created (`options.tags` is validated and **copied** at construction time in
+ * Next 15 — mutating the array during the callback does not propagate), but
+ * the correct tags are only known *after* the loader resolved the page. So a
+ * single wrapper can never both (a) run the loader and (b) store the result
+ * under the tags that run discovered.
+ *
+ * The design ("resolve once, cache with discovered tags, serve cached
+ * thereafter") uses two wrapper constructions per request around **one**
+ * cache entry:
+ *
+ * 1. **Probe pass** — a wrapper keyed by `keyParts` whose callback runs the
+ *    loader, captures the result + its discovered tags into the closure, and
+ *    then throws an internal sentinel.
+ *    - Cache **hit**: the stored entry (written by a previous request with
+ *      its full discovered tags) is returned; the callback — and therefore
+ *      the loader and any backend access — never runs. This is the outage
+ *      story: fully cached routes keep serving when the backend is down.
+ *    - Cache **miss**: the loader runs exactly once; the sentinel throw
+ *      prevents `unstable_cache` from persisting the entry under the
+ *      incomplete baseline tags (thrown callbacks cache nothing).
+ * 2. **Write pass** (miss only) — a second wrapper is constructed *now that
+ *    the tags are known*, with `options.tags` = the discovered set, same key.
+ *    Its callback just returns the already-loaded entry, so the backend is
+ *    not hit again; `unstable_cache` persists the entry under the full
+ *    fetch-time tag set. `revalidateTag` on any of those tags drops the
+ *    entry and the next request repeats the cycle with fresh data.
+ *
+ * The loader runs **once per revalidation cycle** (per key), never once per
+ * request. Time-based revalidation is intentionally not exposed: 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.
+ *
+ * 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).
+ */
+declare function loadCachedEntry<T>(cache: CacheWrapper, keyParts: string[], baselineTags: readonly string[], load: () => Promise<CachedEntry<T>>): Promise<CachedEntry<T>>;
+
+/**
+ * Pure signature/payload logic of the revalidation webhook receiver (EC-146),
+ * kept free of Next.js imports so it is unit-testable. `revalidate.ts` wires
+ * it into a route handler with `revalidateTag`.
+ *
+ * Scheme: HMAC-SHA256 over the **raw request body** with a shared secret,
+ * carried as `x-elytra-signature: sha256=<hex>`. The emitter (the studio's
+ * webhook dispatcher) signs the exact JSON string it sends; the receiver
+ * verifies over the raw text *before* parsing, with a timing-safe compare.
+ */
+/** Header carrying the HMAC signature. */
+declare const REVALIDATE_SIGNATURE_HEADER = "x-elytra-signature";
+/** The webhook body: which tags to revalidate, and why. */
+declare const revalidatePayloadSchema: z.ZodObject<{
+    projectId: z.ZodString;
+    event: z.ZodString;
+    tags: z.ZodArray<z.ZodString>;
+    timestamp: z.ZodString;
+}, z.core.$strip>;
+type RevalidatePayload = z.infer<typeof revalidatePayloadSchema>;
+/** Compute the signature header value for a raw body (emitter/test side). */
+declare function signRevalidateBody(rawBody: string, secret: string): string;
+type RevalidateEvaluation = {
+    ok: true;
+    payload: RevalidatePayload;
+} | {
+    ok: false;
+    status: 400 | 401;
+    message: string;
+};
+/**
+ * Evaluate one webhook request: verify the HMAC first (auth before parsing),
+ * then validate the payload shape.
+ *
+ * - unconfigured (empty) secret → 401 for every request: the endpoint stays
+ *   closed until a secret is deliberately configured (mirrors EC-144 preview);
+ * - missing/malformed/mismatched signature → 401 (timing-safe compare);
+ * - unparseable or schema-invalid body → 400 with no tag revalidated.
+ */
+declare function evaluateRevalidateRequest(rawBody: string, signature: string | null | undefined, secret: string | undefined): RevalidateEvaluation;
+
+/**
+ * Revalidation webhook route handler (EC-146): the receiving end of the
+ * publish → live-in-seconds pipeline. The studio's dispatcher POSTs a signed
+ * `{projectId, event, tags, timestamp}` payload; this handler verifies the
+ * HMAC over the raw body and calls `revalidateTag` for each tag, dropping
+ * exactly the cached entries whose fetch-time tag sets contained them.
+ *
+ * Server-only by construction — consumed from an App Router route handler
+ * file, never from client bundles.
+ */
+interface RevalidateRouteOptions {
+    /**
+     * Shared HMAC secret. An empty/undefined secret rejects every request with
+     * 401 — the endpoint stays closed until deliberately configured.
+     */
+    secret: string | undefined;
+    /**
+     * CORS origin allowed to call this endpoint (e.g. the studio's origin).
+     * The v1 dispatcher is a browser `fetch` from the studio, and the custom
+     * signature header always triggers a CORS preflight — so cross-origin
+     * studio → host dispatch only works when this is set. Server-side emitters
+     * (the Convex action variant, CLIs, CI) need no CORS and may leave it
+     * unset. Never use `*` with a real secret-bearing deployment unless you
+     * accept that any origin may *attempt* deliveries (they still need the
+     * secret to have any effect).
+     */
+    allowOrigin?: string;
+}
+interface RevalidateRouteHandlers {
+    POST(request: Request): Promise<Response>;
+    OPTIONS(): Promise<Response>;
+}
+/**
+ * Create the webhook route handlers for `app/api/revalidate/route.ts`:
+ *
+ * ```ts
+ * export const { POST, OPTIONS } = createRevalidateRoute({
+ *   secret: process.env.REVALIDATE_SECRET,
+ * })
+ * ```
+ *
+ * Unsigned/invalid requests are rejected with 401 (timing-safe HMAC check,
+ * see `evaluateRevalidateRequest`); valid requests revalidate every carried
+ * tag and answer `{ revalidated: tags }`.
+ */
+declare function createRevalidateRoute(options: RevalidateRouteOptions): RevalidateRouteHandlers;
+
+/**
+ * Image delivery for the embedded runtime (EC-152).
+ *
+ * ## The honest v1 design
+ *
+ * Stored asset bytes are served from plain blob-storage URLs (Convex file
+ * storage serve URLs in production). Those URLs do **not** transform — there
+ * is no `?w=`/`?q=` resizing service behind them, and no image CDN build-out
+ * in v1. The standard, no-CDN path is therefore `next/image` with its
+ * **default loader**: the host app's own Next.js optimizer fetches the remote
+ * asset URL, resizes/re-encodes it, and serves the variants same-origin from
+ * `/_next/image`. That is exactly what {@link ElytraImage} does.
+ *
+ * For that to work the host app must allowlist the asset origin in
+ * `next.config.mjs`:
+ *
+ * ```js
+ * const nextConfig = {
+ *   images: {
+ *     remotePatterns: [
+ *       // Convex file storage serve URLs:
+ *       { protocol: 'https', hostname: '*.convex.cloud' },
+ *     ],
+ *   },
+ * }
+ * ```
+ *
+ * {@link createAssetImageLoader} exists for the day the asset URLs sit behind
+ * a CDN that *does* honor width/quality query params — it appends them and
+ * nothing more. Pointing it at raw Convex serve URLs would silently serve
+ * full-size bytes while pretending to resize, so it is **not** the default.
+ */
+/**
+ * The slice of the {@link ResolvedAsset} delivery shape an image needs:
+ * the resolvable URL, intrinsic dimensions for layout stability, and alt
+ * text. Structurally satisfied by every `ResolvedAsset`.
+ */
+type ElytraImageAsset = Pick<ResolvedAsset, 'url' | 'width' | 'height' | 'alt' | 'focalPoint'>;
+interface ElytraImageProps {
+    /** The resolved asset (delivery shape). `null` renders nothing. */
+    asset: ElytraImageAsset | null | undefined;
+    /** `sizes` hint forwarded to `next/image` for responsive variants. */
+    sizes?: string;
+    /** Preload hint forwarded to `next/image` (above-the-fold images). */
+    priority?: boolean;
+    /** Quality (1–100) forwarded to `next/image`; Next defaults to 75. */
+    quality?: number;
+    className?: string;
+    /**
+     * Custom `next/image` loader (e.g. from {@link createAssetImageLoader})
+     * when assets sit behind a transforming CDN. Omit for the v1 default:
+     * Next's own optimizer.
+     */
+    loader?: ImageLoader;
+}
+/**
+ * Render a resolved asset through `next/image` (EC-152).
+ *
+ * - With known intrinsic dimensions the optimizer serves resized variants
+ *   and the reserved width/height prevent layout shift.
+ * - Without dimensions `next/image` cannot render (it requires `width` +
+ *   `height` or `fill`), so the component degrades to a plain `<img>` —
+ *   un-optimized but visible, never a crash. Records written by the EC-151
+ *   upload flow always carry detected dimensions.
+ * - A `null`/empty asset renders nothing (missing assets surface as
+ *   structured `unknown-asset` validation issues upstream, not here).
+ */
+declare function ElytraImage(props: ElytraImageProps): ReactNode;
+interface AssetImageLoaderOptions {
+    /** Query param name for the requested width. Default `"w"`. */
+    widthParam?: string;
+    /** Query param name for the requested quality. Default `"q"`. */
+    qualityParam?: string;
+    /** Quality used when `next/image` passes none. Default `75`. */
+    defaultQuality?: number;
+}
+/**
+ * A `next/image` loader for asset URLs served through a transforming CDN:
+ * it appends width/quality query params to the asset URL and returns it.
+ *
+ * Be honest about what this does: it only *requests* a transform. Plain
+ * Convex file-storage serve URLs ignore these params and return the original
+ * bytes, so this loader is only correct once the asset origin actually
+ * resizes (e.g. an image CDN in front of storage). Until then, use the
+ * default `next/image` loader (see module docs) — that is the v1 path.
+ */
+declare function createAssetImageLoader(options?: AssetImageLoaderOptions): ImageLoader;
+/**
+ * Host registration that swaps the `base.primitives.Image` implementation
+ * for {@link ElytraImage} while keeping the primitive's canonical manifest
+ * (the first registration's manifest wins in `defineHostComponents` — by
+ * design, so prop schemas stay canonical; the duplicate-id registry issue it
+ * reports is the documented override signal, not an error):
+ *
+ * ```ts
+ * export const hostComponents = defineHostComponents([
+ *   nextImagePrimitive(),
+ *   // ...project components
+ * ])
+ * ```
+ */
+declare function nextImagePrimitive(): HostComponent;
+
+/**
+ * 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;
+
+/**
+ * Draft preview route handlers (EC-144): Next.js `draftMode()` integration.
+ * Server-only by construction — these factories are consumed from App Router
+ * route handler files, never from client bundles.
+ */
+interface PreviewRouteOptions {
+    /**
+     * The shared secret gating draft preview. An empty/undefined token means
+     * every request is rejected with 401 — drafts stay unreachable until a
+     * token is configured.
+     */
+    token: string | undefined;
+}
+/** The shape an `app/api/.../route.ts` file re-exports. */
+interface PreviewRouteHandlers {
+    GET(request: Request): Promise<Response>;
+}
+/**
+ * Create the preview-enable route handler for
+ * `app/api/preview/route.ts`:
+ *
+ * ```ts
+ * export const { GET } = createPreviewRoute({ token: process.env.PREVIEW_TOKEN })
+ * ```
+ *
+ * `GET /api/preview?token=...&redirect=/some/path` checks the token, enables
+ * Next draft mode (the catch-all helper then renders the `draft`
+ * perspective), and redirects to the target path. Wrong/missing token → 401.
+ */
+declare function createPreviewRoute(options: PreviewRouteOptions): PreviewRouteHandlers;
+/**
+ * Create the preview-disable route handler (e.g.
+ * `app/api/preview/disable/route.ts`). Disabling needs no token — it only
+ * ever reduces visibility back to the published perspective.
+ */
+declare function createPreviewDisableRoute(): PreviewRouteHandlers;
+
+/**
+ * @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
+ * the user's own components. Drop `createCanvasRoute` into a catch-all
+ * route, register components with `defineHostComponents`, done.
+ *
+ * Nothing here imports builder-only code (no studio, no operations, no
+ * TanStack) — only the runtime packages: content accessors, the component
+ * registry, and the runtime renderer.
+ */
+declare const PACKAGE = "@elytracms/next";
+
+export { type AssetImageLoaderOptions, type AssetRecord, 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 CmsDocument, type CollectionDef, type ComponentImplementations, type ComponentManifest, type ComponentNode, type ContentSnapshot, type ContentSnapshotOptions, type ContentSource, type CreateCanvasSitemapOptions, type DefineHostComponentsOptions, ElytraImage, type ElytraImageAsset, type ElytraImageProps, type FieldDef, type HostComponent, type HostComponents, type Locale, type LocaleConfig, type MaterializeSourcePayloadsInput, type MaterializedSourcePayloads, PACKAGE, PROJECT_GRAPH_SCHEMA_VERSION, type Perspective, type PreviewEvaluation, type PreviewRouteHandlers, type PreviewRouteOptions, type ProjectGraph, type PropField, REVALIDATE_SIGNATURE_HEADER, type RedirectRecord, type RenderAsset, type ResolveCanvasPageOptions, type RevalidateEvaluation, type RevalidatePayload, type RevalidateRouteHandlers, type RevalidateRouteOptions, type RouteRecord, type SitemapParamsProvider, type SitemapRouteContext, type SitemapSkippedRoute, type SlotSpec, type SourcePayloadError, type StaticContentData, canvasPageMetadata, canvasSitemapEntries, collectBindingSourceIds, collectionCacheTag, createAssetImageLoader, createBindingResolver, createCanvasRoute, createCanvasSitemap, createContentSnapshot, createPreviewDisableRoute, createPreviewRoute, createRevalidateRoute, createStaticContentSource, defaultBindingPayloads, defineComponent, defineHostComponents, docCacheTag, documentSchema, evaluatePreviewRequest, evaluateRevalidateRequest, isSourcePayloadError, loadCachedEntry, localeConfigSchema, materializeSourcePayloads, mergeCacheTags, mergeRouteRecords, nextCacheTags, nextImagePrimitive, parseProjectGraph, pathFromSlug, projectSweepTag, redirectRecordSchema, resolveCanvasPage, resolvePayloadToken, revalidatePayloadSchema, routeCacheTag, routeRecordSchema, safeRedirectTarget, scopeCacheTag, signRevalidateBody, sourcePayloadError, splitLocalePath };