@elytracms/core 0.0.6

package/dist/runtime-renderer/render.js

@@ -0,0 +1,825 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createElement, Fragment } from 'react';
+import { DEFAULT_SLOT, OUTLET_SLOT } from '@elytracms/core/project-graph';
+import { manifestSlots, propValueValidator } from '@elytracms/core/component-registry';
+import { isAssetNode, readDocumentRef } from '@elytracms/core/cms-core';
+import { getImplementation } from './context';
+import { ContentClientProvider } from './content-client';
+import { evaluateCondition } from './condition';
+import { MissingComponentFallback, MissingSlotPlaceholder, RenderErrorBoundary, RenderErrorFallback, } from './fallback';
+/**
+ * Render a single component node to React. Never throws on a node: missing components,
+ * invalid props, missing required slots, and resolver errors all degrade to visible
+ * fallbacks (brief §4.11).
+ */
+export function renderNode(node, ctx) {
+    // Condition gate — render nothing when false.
+    if (node.condition && !evaluateCondition(node.condition, ctx.resolveBinding, ctx.item)) {
+        return null;
+    }
+    const manifest = ctx.registry.getManifest(node.componentId);
+    const implementation = getImplementation(ctx.implementations, node.componentId);
+    // Missing component: no manifest OR no implementation.
+    if (!manifest || !implementation) {
+        return decorate(ctx, node, _jsx(MissingComponentFallback, { nodeId: node.id, componentId: node.componentId }));
+    }
+    let resolved;
+    try {
+        resolved = resolveRender(node, manifest, ctx);
+    }
+    catch (error) {
+        // A thrown resolver (binding/prop) error yields a fallback, not a crash.
+        return decorate(ctx, node, _jsx(RenderErrorFallback, { nodeId: node.id, message: messageOf(error) }));
+    }
+    const element = createElement(implementation, { ...resolved.props, ...resolved.slotProps, key: node.id }, resolved.children);
+    // Wrap each node so a throw during the implementation's own render degrades on the client.
+    return decorate(ctx, node, _jsx(RenderErrorBoundary, { nodeId: node.id, children: element }, node.id));
+}
+/** Apply the host's optional per-node decorator (Builder selection markers). */
+function decorate(ctx, node, rendered) {
+    return ctx.decorateNode ? ctx.decorateNode(node, rendered) : rendered;
+}
+/**
+ * Bind a `RichTextEmbedRenderer` (EC-189) to a `RenderContext`: each embedded
+ * composition node renders through `renderComposition` with the SAME context, so an
+ * embed reuses the EC-015 visible fallbacks, the injected binding resolver, the
+ * content client, and any active item scope exactly as on a page.
+ *
+ * The bound renderer is a FUNCTION closed over `ctx`, so it is injected into the
+ * consuming component as a **prop** (see `resolveRender`), never through a
+ * `'use client'` React-context provider: a function cannot cross the RSC
+ * server→client boundary into a client component, so the provider approach
+ * 500s a server-rendered (host) page. A server→server prop is fine, and the
+ * studio's client render injects the identical prop the same way.
+ */
+export function createEmbedRenderer(ctx) {
+    return (node) => renderComposition(node, ctx);
+}
+/** Whether a manifest declares a `richText` prop — i.e. it may render embeds (EC-189). */
+function manifestConsumesEmbeds(manifest) {
+    return Object.values(manifest.props).some((field) => field.type === 'richText');
+}
+/**
+ * Bind a blocks renderer to a `RenderContext` (EC-254 transclusion): renders a
+ * populated relation target's `blocks` field value as a composition through the
+ * SAME `renderComposition` pipeline (EC-015 fallbacks, the injected resolvers, any
+ * active item scope), so a referenced document's sub-blocks compose inline exactly
+ * like a page's. Like {@link createEmbedRenderer}, it is a FUNCTION closed over
+ * `ctx` injected as a PROP (`renderBlocks`), never a `'use client'` context
+ * provider — a function cannot cross the RSC boundary into a client component.
+ */
+export function createBlocksRenderer(ctx) {
+    return (value) => renderComposition(value, ctx);
+}
+/** Whether a manifest declares a `relation` prop — i.e. it populates/transcludes (EC-254). */
+function manifestConsumesRelations(manifest) {
+    return Object.values(manifest.props).some((field) => field.type === 'relation');
+}
+/**
+ * A `{ collection, id }` relation reference, or `null` when the value is not one.
+ * EC-277: accepts the self-typed envelope (`{ type:'reference', collection, id }`)
+ * and legacy bare `{ collection, id }` via the shared tolerant reader.
+ */
+function relationRefOf(value) {
+    return readDocumentRef(value) ?? null;
+}
+/**
+ * The asset id a prop value points at, or `undefined`. EC-277: a self-typed asset
+ * envelope (`{ type:'asset', id }`) OR a legacy bare id string — but NOT a literal
+ * URL string, which the renderer passes through as a direct src (URL-passthrough).
+ */
+function assetIdOfProp(value) {
+    if (isAssetNode(value))
+        return value.id;
+    if (typeof value === 'string' && value !== '' && !isUrlLike(value))
+        return value;
+    return undefined;
+}
+/** Stable cycle-guard key for a relation target. */
+function relationKey(ref) {
+    return `${ref.collection}:${ref.id}`;
+}
+/** The cycle-guard keys (`collection:id`) of a node's static relation props (EC-254). */
+function nodeRelationKeys(node, manifest) {
+    const keys = [];
+    for (const [name, value] of Object.entries(node.props ?? {})) {
+        if (value.kind !== 'static')
+            continue;
+        const spec = manifest.props[name];
+        if (spec?.type !== 'relation')
+            continue;
+        const refs = spec.cardinality === 'many' ? (Array.isArray(value.value) ? value.value : []) : [value.value];
+        for (const raw of refs) {
+            const ref = relationRefOf(raw);
+            if (ref)
+                keys.push(relationKey(ref));
+        }
+    }
+    return keys;
+}
+/**
+ * Populate a static `relation` prop's stored value to delivery shape (EC-254).
+ * `one` → the single populated target, or `undefined` (omit the prop) when the
+ * ref is malformed, unresolved (missing/invisible target), or cyclic. `many` →
+ * the array of populated targets with such entries dropped. A ref already on the
+ * transclude path is skipped — the cycle guard. Mirrors the asset branch's
+ * "resolved object or graceful omission" contract; the caller only assigns a
+ * defined result.
+ */
+function resolveRelationProp(cardinality, value, ctx) {
+    const resolveOne = (raw) => {
+        const ref = relationRefOf(raw);
+        if (!ref)
+            return null;
+        if (ctx.transcludePath?.includes(relationKey(ref)))
+            return null; // reference cycle
+        return ctx.resolveRelation?.(ref) ?? null;
+    };
+    if (cardinality === 'many') {
+        const refs = Array.isArray(value) ? value : [];
+        const out = [];
+        for (const raw of refs) {
+            const target = resolveOne(raw);
+            if (target)
+                out.push(target);
+        }
+        return out;
+    }
+    return resolveOne(value) ?? undefined;
+}
+/**
+ * Wrap a composite render in the `ContentClientProvider` when a content client is
+ * injected (EC-191), so self-fetching components reach it via `useContentClient()`.
+ * Nested wraps are harmless (inner provider wins with an equivalent value).
+ *
+ * Note (EC-189): the rich-text embed renderer is NOT wrapped here — it is a
+ * function and a `'use client'` provider cannot receive it across the RSC
+ * boundary (it threw "Functions cannot be passed directly to Client Components"
+ * on every server-rendered page). It is injected as a prop in `resolveRender`.
+ */
+function withContent(ctx, rendered) {
+    if (ctx.content)
+        return _jsx(ContentClientProvider, { client: ctx.content, children: rendered });
+    return rendered;
+}
+/** Resolve a node's props and slot children. Throws only if a resolver throws (caught upstream). */
+function resolveRender(node, manifest, ctx) {
+    const props = resolveProps(node, manifest, ctx);
+    // EC-189: a component with a `richText` prop (the RichText primitive) renders
+    // `componentEmbed` nodes through the renderer. Inject the embed renderer as a
+    // prop — server-safe (a server→server function prop), unlike a `'use client'`
+    // context provider, which cannot receive a function across the RSC boundary.
+    if (manifestConsumesEmbeds(manifest))
+        props.renderEmbed = createEmbedRenderer(ctx);
+    // EC-254: a component with a `relation` prop may transclude a populated target's
+    // `blocks` field (e.g. `project.Reusable` rendering the referenced `reusable`'s
+    // `content`). Inject a composition renderer — server-safe like `renderEmbed` —
+    // closed over a context whose cycle-guard path includes THIS node's relation
+    // targets, so a transcluded sub-block that references an ancestor target degrades
+    // instead of looping. Population above ran with `ctx` (the un-extended path), so
+    // the node's OWN targets are populated, never pre-blocked.
+    if (manifestConsumesRelations(manifest)) {
+        props.renderBlocks = createBlocksRenderer({
+            ...ctx,
+            transcludePath: [...(ctx.transcludePath ?? []), ...nodeRelationKeys(node, manifest)],
+        });
+    }
+    // EC-255: a component whose manifest declares a `listing` renders documents from
+    // a LIVE query (a dynamic grid), not a static pick. Build the query from its
+    // filter-source prop and inject the resolved documents as the declared prop — the
+    // host runs the query (Next bakes it, the studio runs it live); the renderer never
+    // executes one. No resolver wired, or no usable pick, yields an empty array, so the
+    // block shows its own empty state rather than listing the whole collection.
+    if (manifest.listing) {
+        const query = listingQueryOf(node, manifest.listing);
+        props[manifest.listing.prop] = (query && ctx.resolveListing?.(query)) || [];
+    }
+    // Repeater nodes iterate their items prop over the item slot template.
+    if (manifest.iterate) {
+        return resolveRepeater(node, manifest, manifest.iterate, props, ctx);
+    }
+    // Composition hosts render a block-field value (a ComponentNode tree) as children.
+    if (manifest.composition) {
+        return resolveComposition(manifest.composition, props, ctx);
+    }
+    const { children, slotProps } = renderSlots(node, manifest, ctx);
+    return { props, slotProps, children };
+}
+/**
+ * Render a composition host: the resolved `valueProp` holds a stored composition
+ * (a `ComponentNode` tree), which becomes the component's children via
+ * `renderComposition` — so a `blocks` field value composes inside a page/template
+ * exactly like authored nodes (EC-188, AD-12). Mirrors `resolveRepeater`: the raw
+ * value stays in `props` (harmless; the implementation typically ignores it) and the
+ * rendered tree is handed over as `children`.
+ */
+function resolveComposition(spec, props, ctx) {
+    return { props, slotProps: {}, children: renderComposition(props[spec.valueProp], ctx) };
+}
+/** Resolve every prop of a node into a concrete runtime value. */
+function resolveProps(node, manifest, ctx) {
+    const out = {};
+    const entries = Object.entries(node.props ?? {});
+    const isSpread = (value) => value.kind === 'binding' && value.binding.mode === 'spread';
+    // Apply spread bindings first, then explicit props — so a named static/value prop always wins
+    // over a same-named spread key, predictably and independent of authoring order (EC-089).
+    for (const [name, value] of entries)
+        if (isSpread(value))
+            resolveProp(name, value, manifest, ctx, out);
+    for (const [name, value] of entries)
+        if (!isSpread(value))
+            resolveProp(name, value, manifest, ctx, out);
+    return out;
+}
+/**
+ * A value an `asset` prop can carry verbatim instead of an asset id: an absolute
+ * URL (`https://…`, protocol-relative `//…`), a root-relative path (`/…`), or an
+ * inline `data:`/`blob:` source. Lets the Image primitive keep accepting plain
+ * URLs (back-compat: `Image.src` was a free `text` prop before EC-195) and keeps
+ * the renderer usable with no asset store wired.
+ */
+function isUrlLike(value) {
+    return (/^(https?:)?\/\//.test(value) ||
+        value.startsWith('/') ||
+        value.startsWith('data:') ||
+        value.startsWith('blob:'));
+}
+/**
+ * Collect the asset ids a node tree resolves through `resolveAsset` (EC-205): the
+ * STATIC `asset`-typed props holding a real asset id (not a passthrough URL/path).
+ * Mirrors {@link resolveProp}'s asset branch exactly, so the set is COMPLETE (no
+ * referenced asset is missed → no broken image) and MINIMAL (only ids the renderer
+ * would resolve). Bound asset props resolve via bindings, and document asset FIELDS
+ * resolve separately — neither uses the baked asset list, so neither is collected.
+ * Lets a delivery host page-scope the baked assets to exactly what a page uses.
+ */
+export function collectReferencedAssetIds(node, registry, into = new Set()) {
+    const manifest = registry.getManifest(node.componentId);
+    if (manifest) {
+        for (const [name, value] of Object.entries(node.props ?? {})) {
+            if (value.kind !== 'static')
+                continue;
+            const spec = manifest.props[name];
+            if (spec?.type === 'asset') {
+                const assetId = assetIdOfProp(value.value);
+                if (assetId !== undefined)
+                    into.add(assetId);
+            }
+            else if (spec?.type === 'object') {
+                // EC-253: a gallery/repeater prop nests asset ids — collect them too, so the
+                // delivery host bakes every referenced asset and no nested image is missed.
+                collectObjectPropAssetIds(spec.fields, spec.cardinality, value.value, into);
+            }
+        }
+    }
+    for (const children of Object.values(node.slots ?? {})) {
+        for (const child of children)
+            collectReferencedAssetIds(child, registry, into);
+    }
+    return into;
+}
+/**
+ * Walk a composition (a page's blocks + its layout root) and POPULATE every static
+ * `relation` prop it references into a serializable `{ "collection:id": target }`
+ * map (EC-254) — the relation analog of {@link collectReferencedAssetIds}. A
+ * delivery host bakes this into its (serializable) render outcome and rebuilds
+ * `RenderContext.resolveRelation` from the map inside the RSC, exactly as it does
+ * with the page-scoped asset list — because a function (the content client) can
+ * ride neither the data cache nor the RSC server→client boundary.
+ *
+ * Transclusion-aware + cycle-safe: a populated target's composition-shaped fields
+ * (a `reusable`'s `content` blocks, which a component renders inline via
+ * `renderBlocks`) are recursively walked so those blocks' own relations are
+ * populated too; a target already in the map is never re-walked, so a reference
+ * cycle terminates. `resolveRelation` is the injected populate (depth-1) — passed
+ * in, never imported, so this stays free of the content/persistence packages.
+ *
+ * Optional `refKeys` records the `collection:id` of EVERY referenced pick — even
+ * one that resolved to `null` (an unpublished/missing target) — so a delivery host
+ * can cache-tag the page by it (EC-254/EC-146): editing or publishing a referenced
+ * document then invalidates the embedding page, including a previously-unpublished
+ * pick that should appear the moment it publishes.
+ */
+export function collectReferencedRelations(nodes, registry, resolveRelation, into = {}, refKeys) {
+    for (const node of nodes) {
+        const manifest = registry.getManifest(node.componentId);
+        if (manifest) {
+            for (const [name, value] of Object.entries(node.props ?? {})) {
+                if (value.kind !== 'static')
+                    continue;
+                const spec = manifest.props[name];
+                if (spec?.type === 'relation') {
+                    const refs = spec.cardinality === 'many'
+                        ? Array.isArray(value.value)
+                            ? value.value
+                            : []
+                        : [value.value];
+                    for (const raw of refs) {
+                        const ref = relationRefOf(raw);
+                        if (!ref)
+                            continue;
+                        const key = relationKey(ref);
+                        refKeys?.add(key); // tag every pick, even an unresolved one (negative dependency)
+                        if (key in into)
+                            continue; // already populated → also terminates cycles
+                        const target = resolveRelation(ref);
+                        if (!target)
+                            continue;
+                        into[key] = target;
+                        // Transclusion: recurse into the target's composition-shaped fields so a
+                        // reusable's inlined `content` blocks get their own relations populated.
+                        for (const fieldValue of Object.values(target)) {
+                            const childNodes = compositionRoots(fieldValue);
+                            if (childNodes.length > 0) {
+                                collectReferencedRelations(childNodes, registry, resolveRelation, into, refKeys);
+                            }
+                        }
+                    }
+                }
+                else if (spec?.type === 'object' && value.value != null) {
+                    // EC-256: a `relation` nested in an `object` prop (a link object's `page`
+                    // ref) is baked + tagged like a top-level pick, so renaming the target page
+                    // invalidates the embedding page. Depth-1, NO transclusion — a link target
+                    // is read for its path, not inlined (else link-following bakes the whole
+                    // linked-site relation graph).
+                    collectObjectPropRelations(spec.fields, spec.cardinality, value.value, resolveRelation, into, refKeys);
+                }
+            }
+            // A composition host stores its composed blocks in `node.props[valueProp]` (a
+            // blocks VALUE), NOT `node.slots` — and `manifestSlots` excludes the valueProp
+            // — so the slot recursion below misses them. Walk those composed nodes too, so
+            // a relation prop on a block nested inside a composition is collected (and thus
+            // baked for the host), matching what the render path resolves at depth.
+            if (manifest.composition) {
+                const composed = node.props?.[manifest.composition.valueProp];
+                if (composed?.kind === 'static') {
+                    collectReferencedRelations(compositionRoots(composed.value), registry, resolveRelation, into, refKeys);
+                }
+            }
+        }
+        for (const children of Object.values(node.slots ?? {})) {
+            collectReferencedRelations(children, registry, resolveRelation, into, refKeys);
+        }
+    }
+    return into;
+}
+/**
+ * Build the {@link ListingQuery} a node's `listing` manifest declares (EC-255),
+ * or `null` when its filter-source prop carries no usable pick — the block then
+ * renders empty rather than listing the whole collection. Reads the `fromProp`
+ * STATIC pick (a relation value `{ collection, id }` reduced to its id, or a bare
+ * id string) and binds it to the listed collection's filter `field`. Pure (node
+ * props + manifest only; no content import), so the Next bake and the studio live
+ * resolver build the IDENTICAL query — and thus agree on the baked cache key.
+ */
+export function listingQueryOf(node, spec) {
+    const pick = node.props?.[spec.filter.fromProp];
+    if (!pick || pick.kind !== 'static')
+        return null;
+    const ref = relationRefOf(pick.value);
+    const id = ref ? ref.id : typeof pick.value === 'string' && pick.value !== '' ? pick.value : null;
+    if (id === null)
+        return null;
+    const query = { collection: spec.collection, where: { [spec.filter.field]: id } };
+    if (spec.sort)
+        query.sort = spec.sort;
+    if (spec.limit !== undefined)
+        query.limit = spec.limit;
+    return query;
+}
+/**
+ * Deterministic cache key for a {@link ListingQuery} (EC-255): a stable JSON shape
+ * (where-keys sorted, sort/limit normalized) so the Next host can key its baked
+ * `query → docs` map and the rebuilt resolver looks the listing up by the SAME key
+ * the renderer's {@link listingQueryOf} produces. Mirrors `@elytracms/core/content`'s
+ * `serializeListQuery`, kept local so the renderer takes no content dependency.
+ */
+export function serializeListingQuery(query) {
+    const where = {};
+    for (const key of Object.keys(query.where).sort()) {
+        const value = query.where[key];
+        if (value !== undefined)
+            where[key] = value;
+    }
+    return JSON.stringify({
+        collection: query.collection,
+        where,
+        sort: query.sort ? { field: query.sort.field, direction: query.sort.direction ?? 'asc' } : null,
+        limit: query.limit ?? null,
+    });
+}
+/**
+ * Walk a composition (a page's blocks + its layout root) and resolve every
+ * `listing` a node declares into a serializable `{ serializedQuery: docs[] }` map
+ * (EC-255) — the listing analog of {@link collectReferencedRelations}. A delivery
+ * host bakes this into its (serializable) render outcome and rebuilds
+ * `RenderContext.resolveListing` from the map inside the RSC, exactly as it does
+ * with relations and the page-scoped asset list, because the content client (which
+ * runs the query) can ride neither the data cache nor the RSC server→client
+ * boundary.
+ *
+ * `runListing` is the injected query executor (the host's `listDocuments`) — passed
+ * in, never imported, so this stays free of the content/persistence packages. The
+ * key is {@link serializeListingQuery}, so two nodes with the same query share a
+ * single execution.
+ *
+ * Transclusion-aware + cycle-safe, exactly like {@link collectReferencedRelations}:
+ * a composition host's composed blocks, child slots, AND a populated relation
+ * target's composition-shaped fields (a `reusable`'s `content` a block transcludes
+ * via `renderBlocks`) are all walked — so a listing nested inside a transcluded
+ * reusable is baked too, matching what the render path resolves at depth. Without
+ * this the Next host would render such a grid empty (the studio's live resolver
+ * still works) AND drop its collection-membership cache tag. `resolveRelation` is
+ * the injected populate (depth-1) used to reach those transcluded fields; a target
+ * already visited is never re-walked, so a reference cycle terminates.
+ */
+export function collectReferencedListings(nodes, registry, runListing, resolveRelation, into = {}, visitedRelations = new Set()) {
+    for (const node of nodes) {
+        const manifest = registry.getManifest(node.componentId);
+        if (manifest?.listing) {
+            const query = listingQueryOf(node, manifest.listing);
+            if (query) {
+                const key = serializeListingQuery(query);
+                if (!(key in into))
+                    into[key] = runListing(query);
+            }
+        }
+        if (manifest) {
+            // Transclusion: a static `relation` prop (e.g. `Reusable.element`) inlines its
+            // target's composition-shaped fields via `renderBlocks` at render — walk them
+            // so a listing nested in a transcluded reusable's content is baked too (the
+            // listing analog of `collectReferencedRelations`' transclusion recursion).
+            for (const [name, value] of Object.entries(node.props ?? {})) {
+                if (value.kind !== 'static')
+                    continue;
+                const spec = manifest.props[name];
+                if (spec?.type !== 'relation')
+                    continue;
+                const refs = spec.cardinality === 'many' ? (Array.isArray(value.value) ? value.value : []) : [value.value];
+                for (const raw of refs) {
+                    const ref = relationRefOf(raw);
+                    if (!ref)
+                        continue;
+                    const relKey = relationKey(ref);
+                    if (visitedRelations.has(relKey))
+                        continue; // already walked → terminates cycles
+                    visitedRelations.add(relKey);
+                    const target = resolveRelation(ref);
+                    if (!target)
+                        continue;
+                    for (const fieldValue of Object.values(target)) {
+                        const childNodes = compositionRoots(fieldValue);
+                        if (childNodes.length > 0) {
+                            collectReferencedListings(childNodes, registry, runListing, resolveRelation, into, visitedRelations);
+                        }
+                    }
+                }
+            }
+        }
+        if (manifest?.composition) {
+            const composed = node.props?.[manifest.composition.valueProp];
+            if (composed?.kind === 'static') {
+                collectReferencedListings(compositionRoots(composed.value), registry, runListing, resolveRelation, into, visitedRelations);
+            }
+        }
+        for (const children of Object.values(node.slots ?? {})) {
+            collectReferencedListings(children, registry, runListing, resolveRelation, into, visitedRelations);
+        }
+    }
+    return into;
+}
+/** Collect the asset ids nested inside an `object` prop value (mirrors {@link resolveObjectProps}). */
+function collectObjectPropAssetIds(fields, cardinality, value, into) {
+    const items = cardinality === 'many' ? (Array.isArray(value) ? value : []) : [value];
+    for (const item of items) {
+        if (!item || typeof item !== 'object' || Array.isArray(item))
+            continue;
+        const record = item;
+        for (const sub of fields) {
+            const sv = record[sub.name];
+            if (sub.type === 'asset') {
+                const assetId = assetIdOfProp(sv);
+                if (assetId !== undefined)
+                    into.add(assetId);
+            }
+            else if (sub.type === 'object' && sv != null)
+                collectObjectPropAssetIds(sub.fields, sub.cardinality, sv, into);
+        }
+    }
+}
+/**
+ * Populate (depth-1) the `relation` refs nested inside an `object` prop value into
+ * the relations bake map + refKeys (EC-256) — the relation analog of
+ * {@link collectObjectPropAssetIds}, so a `page` ref inside a link object
+ * (`buttons[].link.page`) is baked and cache-tagged exactly like a top-level pick.
+ * Recurses into nested `object` subfields. UNLIKE the top-level relation walk it
+ * does NOT transclude the target's composition-shaped fields: a link's target page
+ * is read for its path (depth-1), never inlined — following it would bake the whole
+ * linked-site relation graph into every embedding page. `refKeys` tags every pick
+ * (even an unresolved one) so publishing/renaming the target invalidates the page.
+ */
+function collectObjectPropRelations(fields, cardinality, value, resolveRelation, into, refKeys) {
+    const items = cardinality === 'many' ? (Array.isArray(value) ? value : []) : [value];
+    for (const item of items) {
+        if (!item || typeof item !== 'object' || Array.isArray(item))
+            continue;
+        const record = item;
+        for (const sub of fields) {
+            const sv = record[sub.name];
+            if (sub.type === 'relation' && sv != null) {
+                const refs = sub.cardinality === 'many' ? (Array.isArray(sv) ? sv : []) : [sv];
+                for (const raw of refs) {
+                    const ref = relationRefOf(raw);
+                    if (!ref)
+                        continue;
+                    const key = relationKey(ref);
+                    refKeys?.add(key);
+                    if (key in into)
+                        continue;
+                    const target = resolveRelation(ref);
+                    if (target)
+                        into[key] = target; // depth-1 only — never transclude a link target
+                }
+            }
+            else if (sub.type === 'object' && sv != null) {
+                collectObjectPropRelations(sub.fields, sub.cardinality, sv, resolveRelation, into, refKeys);
+            }
+        }
+    }
+}
+/**
+ * Resolve the `asset` and `relation` subfields nested inside an `object` / repeater
+ * prop value to delivery shape (EC-253 assets, EC-256 relations). The top-level
+ * branches of {@link resolveProp} only resolve a TOP-LEVEL `asset`/`relation` prop,
+ * so an asset nested in an `object` (a gallery's `images[].image`) or a relation
+ * nested in one (a link object's `buttons[].link.page`) would otherwise reach the
+ * implementation as a raw id/ref. This walks the prop's declared subfields:
+ *
+ * - `asset` → `ctx.resolveAsset` (url-like values pass through; an unresolved id
+ *   drops the subfield), exactly as the top level does.
+ * - `relation` → `ctx.resolveRelation` depth-1 via {@link resolveRelationProp}, so
+ *   the implementation reads the target's fields (e.g. a link's `page.slug` → a live
+ *   path). No resolver → the raw ref passes through (graceful degradation); an
+ *   unresolved `one` drops the subfield. Depth-1 only — a nested relation is never
+ *   transcluded (a link target is read, not inlined).
+ *
+ * and recurses into nested `object` subfields. Pure; non-object items pass through.
+ */
+function resolveObjectProps(fields, cardinality, value, ctx) {
+    const items = cardinality === 'many' ? (Array.isArray(value) ? value : []) : [value];
+    const resolvedItems = items.map((item) => {
+        if (!item || typeof item !== 'object' || Array.isArray(item))
+            return item;
+        const next = { ...item };
+        for (const sub of fields) {
+            const sv = next[sub.name];
+            if (sub.type === 'asset') {
+                const assetId = assetIdOfProp(sv);
+                if (assetId === undefined)
+                    continue; // URL string / empty / not an asset → leave as-is
+                const resolved = ctx.resolveAsset?.(assetId);
+                if (resolved)
+                    next[sub.name] = resolved;
+                else
+                    delete next[sub.name];
+            }
+            else if (sub.type === 'relation' && sv != null) {
+                if (!ctx.resolveRelation)
+                    continue; // no resolver → leave the raw ref (degrade)
+                const resolved = resolveRelationProp(sub.cardinality, sv, ctx);
+                if (resolved !== undefined)
+                    next[sub.name] = resolved;
+                else
+                    delete next[sub.name]; // unresolved `one` → drop the subfield
+            }
+            else if (sub.type === 'object' && sv != null) {
+                next[sub.name] = resolveObjectProps(sub.fields, sub.cardinality, sv, ctx);
+            }
+        }
+        return next;
+    });
+    return cardinality === 'many' ? resolvedItems : resolvedItems[0];
+}
+/** Resolve a single prop into `out`, applying invalid-static-prop fallbacks and spread. */
+function resolveProp(name, value, manifest, ctx, out) {
+    const spec = manifest.props[name];
+    if (value.kind === 'static') {
+        // Validate against the prop's field-def (EC-190); on failure use the field's
+        // `default` or omit — the EC-015 invalid-static-prop visible fallback.
+        const validate = propValueValidator(manifest, name);
+        if (validate && !validate(value.value)) {
+            if (spec?.default !== undefined)
+                out[name] = spec.default;
+            // else: omit the prop entirely and continue.
+            return;
+        }
+        // EC-195: an `asset`-typed prop stores an asset id; resolve it to a usable
+        // asset (url + intrinsic dimensions + alt) so an uploaded image renders
+        // optimized. A raw URL/path value passes through (back-compat, and so the
+        // renderer never *requires* an asset store). A missing asset omits the prop
+        // — the implementation shows its own empty/fallback state, never a crash.
+        if (spec?.type === 'asset') {
+            // EC-277: an asset id arrives self-typed (`{ type:'asset', id }`) or as a legacy
+            // bare id; a literal URL/path string passes through unchanged (back-compat).
+            const assetId = assetIdOfProp(value.value);
+            if (assetId === undefined) {
+                if (typeof value.value === 'string')
+                    out[name] = value.value;
+                return;
+            }
+            const resolved = ctx.resolveAsset?.(assetId);
+            if (resolved)
+                out[name] = resolved;
+            // else omit — unresolved asset id → visible fallback in the implementation.
+            return;
+        }
+        // EC-253/EC-256: an `object` / repeater prop may nest `asset` subfields (a
+        // gallery's `images[].image`) or `relation` subfields (a link object's
+        // `buttons[].link.page`); resolve those to delivery shape so the implementation
+        // reads `item.image.url` / `link.page.slug`, mirroring the top-level branches at
+        // every depth.
+        if (spec?.type === 'object' && value.value != null) {
+            out[name] = resolveObjectProps(spec.fields, spec.cardinality, value.value, ctx);
+            return;
+        }
+        // EC-254: a `relation` prop stores a `{ collection, id }` ref (or an array for
+        // `many`) — the editor's document pick on a block. Populate it to the target's
+        // depth-1 delivery shape so the implementation reads resolved fields, not a raw
+        // ref. Mirrors the asset branch: unresolved → omit (`one`) / drop (`many`); no
+        // resolver wired → the raw ref passes through (the same graceful degradation).
+        if (spec?.type === 'relation') {
+            if (!ctx.resolveRelation) {
+                out[name] = value.value;
+                return;
+            }
+            const resolved = resolveRelationProp(spec.cardinality, value.value, ctx);
+            if (resolved !== undefined)
+                out[name] = resolved;
+            return;
+        }
+        out[name] = value.value;
+        return;
+    }
+    // Bound prop — resolve through the injected resolver (may throw; caught by caller).
+    // NB (EC-254): relation population is intentionally STATIC-only — a relation prop
+    // is the editor's document pick (v1 props are static, AD-12; prop bindings are
+    // parked). A bound value passes through as the resolver returns it, never through
+    // `resolveRelationProp`, so a relation prop should not be bound until prop bindings
+    // and their population are designed together.
+    const resolved = ctx.resolveBinding(value.binding, ctx.item);
+    if (value.binding.mode === 'spread') {
+        if (resolved && typeof resolved === 'object' && !Array.isArray(resolved)) {
+            Object.assign(out, resolved);
+        }
+        return;
+    }
+    out[name] = resolved;
+}
+/** Render the named slots of a node: `children` maps to React children, others to props. */
+function renderSlots(node, manifest, ctx) {
+    const slots = node.slots ?? {};
+    const slotProps = {};
+    let children = renderSlotChildren(slots[DEFAULT_SLOT], ctx);
+    // EC-190: `blocks` props are slots too (named child regions); `manifestSlots`
+    // folds them in (a no-op for manifests without blocks props).
+    const declaredSlots = manifestSlots(manifest);
+    for (const slotSpec of declaredSlots) {
+        if (slotSpec.name === DEFAULT_SLOT)
+            continue;
+        const nodes = slots[slotSpec.name];
+        if ((!nodes || nodes.length === 0) && slotSpec.required) {
+            // Missing required named slot — visible placeholder in that slot position.
+            slotProps[slotSpec.name] = _jsx(MissingSlotPlaceholder, { nodeId: node.id, slot: slotSpec.name });
+            continue;
+        }
+        slotProps[slotSpec.name] = renderSlotChildren(nodes, ctx);
+    }
+    // Pass through any node slots not declared on the manifest (e.g. a Switch's dynamic
+    // `case:*` slots), so dynamic-slot components receive their children as props.
+    const declared = new Set(declaredSlots.map((s) => s.name));
+    for (const [name, nodes] of Object.entries(slots)) {
+        if (name === DEFAULT_SLOT || declared.has(name))
+            continue;
+        slotProps[name] = renderSlotChildren(nodes, ctx);
+    }
+    // Missing required default slot — placeholder as children.
+    const defaultSpec = declaredSlots.find((s) => s.name === DEFAULT_SLOT);
+    const defaultNodes = slots[DEFAULT_SLOT];
+    if (defaultSpec?.required && (!defaultNodes || defaultNodes.length === 0)) {
+        children = _jsx(MissingSlotPlaceholder, { nodeId: node.id, slot: DEFAULT_SLOT });
+    }
+    return { children, slotProps };
+}
+/**
+ * Render an ordered list of slot child nodes (array order preserved). Each
+ * entry is wrapped in a Fragment keyed by the node id: `renderNode`'s return
+ * value may be an unkeyed fallback element (missing component, render error)
+ * or have its key stripped by a host `decorateNode`, and unkeyed entries in
+ * this array would trigger React's `unique "key" prop` warning on every page.
+ */
+function renderSlotChildren(nodes, ctx) {
+    if (!nodes || nodes.length === 0)
+        return null;
+    return (_jsx(Fragment, { children: nodes.map((child) => (_jsx(Fragment, { children: renderNode(child, ctx) }, child.id))) }));
+}
+/**
+ * Render a repeater: resolve `itemsProp` to an array and render the `itemSlot` template
+ * once per item, with `ItemContext` set so `repeaterItem`-mode bindings resolve against
+ * the item. The repeater implementation receives the rendered items as `children`.
+ */
+function resolveRepeater(node, manifest, iterate, props, ctx) {
+    const itemsValue = props[iterate.itemsProp];
+    const items = Array.isArray(itemsValue) ? itemsValue : [];
+    const template = node.slots?.[iterate.itemSlot];
+    const slotSpec = manifest.slots.find((s) => s.name === iterate.itemSlot);
+    if ((!template || template.length === 0) && slotSpec?.required) {
+        // No item template but the slot is required — visible placeholder, no iteration.
+        return {
+            props,
+            slotProps: {},
+            children: _jsx(MissingSlotPlaceholder, { nodeId: node.id, slot: iterate.itemSlot }),
+        };
+    }
+    const rendered = items.map((item, index) => {
+        const itemCtx = { ...ctx, item: { item, index } };
+        return (_jsx(Fragment, { children: (template ?? []).map((child) => (
+            // Keyed per template node for the same reason as renderSlotChildren.
+            _jsx(Fragment, { children: renderNode(child, itemCtx) }, child.id))) }, index));
+    });
+    return { props, slotProps: {}, children: _jsx(Fragment, { children: rendered }) };
+}
+/**
+ * Render a composition FIELD VALUE (EC-188, AD-12): one `ComponentNode` root or an
+ * ordered list of them — a `blocks` field's stored value. Each root renders through
+ * `renderNode` with the SAME `RenderContext`, so the EC-015 visible fallbacks, the
+ * injected binding resolver, and any active item scope all apply exactly as on a
+ * page. An empty/absent value renders nothing (the host component owns its own empty
+ * state). Roots are keyed by id — `renderNode` may return an unkeyed fallback —
+ * mirroring `renderSlotChildren`.
+ *
+ * This is the shared delivery primitive for every composition surface: the block
+ * field (here), and later the page collection (EC-187) and rich-text embeds (EC-189).
+ */
+export function renderComposition(value, ctx) {
+    const roots = compositionRoots(value);
+    if (roots.length === 0)
+        return null;
+    return withContent(ctx, _jsx(Fragment, { children: roots.map((root) => (_jsx(Fragment, { children: renderNode(root, ctx) }, root.id))) }));
+}
+/** Coerce a stored composition value (one node, many, or absent) to a root list. */
+function compositionRoots(value) {
+    if (Array.isArray(value))
+        return value.filter(isComponentNode);
+    if (isComponentNode(value))
+        return [value];
+    return [];
+}
+/** Structural ComponentNode guard — the stored value is opaque at the type level. */
+function isComponentNode(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        typeof value.id === 'string' &&
+        typeof value.componentId === 'string');
+}
+/**
+ * Render a composition (`blocks`) field value composed INTO a graph layout
+ * (EC-187): the page collection's delivery primitive. The composition renders
+ * via `renderComposition` (the same per-node pipeline + EC-015 fallbacks), and
+ * the result is injected into the layout root's `outlet` slot — so a
+ * page-collection document's `body` composes inside its layout chrome.
+ *
+ * Degrades, never crashes: an `undefined`/unknown `layoutId`, or a graph with no
+ * matching layout, renders the bare composition (no layout chrome) rather than
+ * blanking the page. `withContent` wraps the output so a `ContentClient` on
+ * `ctx` propagates to self-fetching blocks (EC-191).
+ */
+export function renderCompositionInLayout(graph, layoutId, value, ctx) {
+    const layout = layoutId ? graph.layouts.find((l) => l.id === layoutId) : undefined;
+    // No layout selected, or the selected layout is absent from the graph: render
+    // the bare composition rather than blanking the page.
+    if (!layout)
+        return withContent(ctx, renderComposition(value, ctx));
+    // With a layout, inject the composition's roots into the layout root's outlet
+    // slot, so the composition renders through the layout's chrome via the
+    // identical per-node pipeline. `compositionRoots` coerces the stored value
+    // (one node, many, or absent) to the outlet's `ComponentNode[]`.
+    const root = injectNodesIntoOutlet(layout.root, compositionRoots(value));
+    return withContent(ctx, renderNode(root, ctx));
+}
+/**
+ * Produce a layout tree with `nodes` inserted into the layout root's `outlet`
+ * slot. The original graph is never mutated.
+ */
+function injectNodesIntoOutlet(root, nodes) {
+    return {
+        ...root,
+        slots: {
+            ...(root.slots ?? {}),
+            [OUTLET_SLOT]: nodes,
+        },
+    };
+}
+function messageOf(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+//# sourceMappingURL=render.js.map