@gradial/aci 0.1.52-rc.26 → 0.1.52-rc.29

package/CHANGELOG.md

@@ -1,33 +1,5 @@
 # Changelog
 
-## 0.1.52-rc.26 - 2026-09-30
-
-### Fixed
-
-- Configure Astro's `build.assetsPrefix` for external CDN builds. Astro
-  overrides a nested Vite `base`, which caused real production builds to keep
-  emitting root-relative `/assets/` URLs even when a CDN base was configured.
-
-## 0.1.52-rc.25 - 2026-09-30
-
-### Added
-
-- Allow Astro builds to opt into framework-neutral `assets/` output with
-  `ACI_ASSET_PATH_LAYOUT=flat-assets`. Next.js rejects that layout until it
-  can produce the same public and stored paths safely.
-
-## 0.1.52-rc.24 - 2026-09-18
-
-### Added
-
-- `withAci()` (Astro and Next.js) reads `ACI_ASSET_BASE_TPL` and, when it is
-  an absolute CDN URL, sets Vite's `base` / Next.js's `assetPrefix` to it so
-  the SSG build writes asset URLs pointing at the CDN directly — no HTML
-  post-processing needed. `__RELEASE_ID__` is stripped because build assets
-  are content-addressed and release-independent. Managed tenants (the
-  `/__r/__RELEASE_ID__/` default) are left untouched; the edge handler
-  rewrites relative paths to the global S3 key.
-
 ## 0.1.52-rc.7 - 2026-08-19
 
 ### Fixed

package/README.md

@@ -1,6 +1,6 @@
 # Agentic Content Infrastructure SDK
 
-`@gradial/aci` `0.1.52-rc.26` is a pre-1.0 public-surface reset for the ACI
+`@gradial/aci` `0.1.52-rc.29` is a pre-1.0 public-surface reset for the ACI
 client SDK. Breaking changes from the old `0.1.x` accidental surface are
 intentional: the root import is framework-neutral, framework runtime behavior is
 behind explicit subpaths, and the first required customer path is React/Next.
@@ -8,7 +8,7 @@ behind explicit subpaths, and the first required customer path is React/Next.
 ## Install
 
 ```bash
-npm install @gradial/aci@0.1.52-rc.26 zod@^4
+npm install @gradial/aci@0.1.52-rc.29 zod@^4
 ```
 
 ## Root Import
@@ -62,6 +62,13 @@ export default withAci(nextConfig, {
 
 Astro public subpath is `@gradial/aci/astro`.
 
+## Page Templates
+
+Pages use content-authored templates for region order, defaults, composition
+rules, and personalization locks. Start with the [page templates guide](docs/page-templates.md),
+including the `blog_body` contract pattern for page-specific container children.
+[Component contracts](docs/component-contracts.md) define props and nested block types.
+
 ## Block Root Identity
 
 The renderer passes every block two props, `data-aci-block` (the authored
@@ -130,13 +137,13 @@ host bundles select and serve immutable release artifacts.
 The first RC scaffold path is Next:
 
 ```bash
-npx @gradial/aci@0.1.52-rc.26 init my-site --template next-starter
+npx @gradial/aci@0.1.52-rc.29 init my-site --template next-starter
 ```
 
 List available templates:
 
 ```bash
-npx @gradial/aci@0.1.52-rc.26 init --list
+npx @gradial/aci@0.1.52-rc.29 init --list
 ```
 
 ## Personalization: The One-Tag Install

package/dist/astro/error-page.js

@@ -50,6 +50,7 @@ export async function getErrorPageData(astro, kind, options = {}) {
         if (resolved.route) {
             const slug = resolved.route.replace(/^\/+|\/+$/g, '');
             const data = await getPageData({
+                isPrerendered: astro.isPrerendered,
                 params: { slug },
                 request: astro.request,
                 url: astro.url,

package/dist/astro/index.d.ts

@@ -4,10 +4,6 @@ import type { BlockRef } from '../types/block-ref.js';
 interface AstroConfigSetupParams {
     injectScript(stage: 'head-inline' | 'page' | 'page-ssr', content: string): void;
     updateConfig(config: {
-        build?: {
-            assets?: string;
-            assetsPrefix?: string;
-        };
         vite?: {
             plugins?: unknown[];
         };

package/dist/astro/index.js

@@ -83,38 +83,6 @@ export function withAci(options = {}) {
         name: 'aci-astro',
         hooks: {
             'astro:config:setup'({ injectScript, updateConfig }) {
-                const assetPathLayout = (process.env.ACI_ASSET_PATH_LAYOUT || 'preserve').trim();
-                if (assetPathLayout !== 'preserve' && assetPathLayout !== 'flat-assets') {
-                    throw new Error('ACI_ASSET_PATH_LAYOUT must be preserve or flat-assets');
-                }
-                if (assetPathLayout === 'flat-assets') {
-                    updateConfig({ build: { assets: 'assets' } });
-                }
-                // Asset URL prefix for production builds. When
-                // ACI_ASSET_BASE_TPL is an absolute CDN URL, use Astro's
-                // build.assetsPrefix so the SSG build writes generated asset URLs
-                // (CSS and JS) pointing at the CDN directly. Astro owns Vite's final
-                // base value, so setting vite.base here does not survive a real build.
-                //
-                // Build assets are content-addressed (hashed filenames) and stored
-                // globally, so the URL is release-independent: strip __RELEASE_ID__.
-                //   - Managed tenants (edge handler): ACI_ASSET_BASE_TPL is
-                //     "/__r/__RELEASE_ID__/" or unset — do NOT set Vite base; the
-                //     SSG writes relative paths (/_astro/foo.js) and the edge
-                //     handler's viewer-request rewrites to the global S3 key.
-                //   - External CDN tenants: "https://cdn.gradial.com/" → Vite base,
-                //     Astro writes absolute CDN URLs.
-                const rawTpl = process.env.ACI_ASSET_BASE_TPL || '';
-                const assetBase = rawTpl
-                    .replace('__RELEASE_ID__/', '')
-                    .replace('__RELEASE_ID__', '')
-                    .replace(/\/+$/, '/');
-                const isAbsoluteUrl = assetBase.startsWith('http://') || assetBase.startsWith('https://');
-                if (isAbsoluteUrl
-                    && assetBase !== '/'
-                    && process.env.NODE_ENV === 'production') {
-                    updateConfig({ build: { assetsPrefix: assetBase } });
-                }
                 if (process.env.NODE_ENV === 'production') {
                     return;
                 }

package/dist/astro/page.d.ts

@@ -31,12 +31,13 @@
  * iterate slots and render blocks via the registry.
  */
 import type { KernelPage, KernelSiteConfig, KernelRouteMetadata, KernelPageBlock } from '../content/types.js';
-import type { LayoutEntry } from '../content/provider.js';
+import { type LayoutEntry } from '../content/provider.js';
 /**
  * Minimal Astro global shape — only the properties getPageData reads.
  * This avoids depending on Astro's own types at the SDK level.
  */
 export interface AstroGlobal {
+    isPrerendered?: boolean;
     params: {
         slug?: string;
     };
@@ -51,6 +52,8 @@ export interface AstroGlobal {
 export interface PageData {
     /** Route string (normalized, e.g. "/" or "/about"). */
     route: string;
+    /** Selected render tuple, including the explicit "base" identity. */
+    variantKey: string;
     /** Site configuration. */
     siteConfig: KernelSiteConfig;
     /** Page content. */
@@ -91,4 +94,4 @@ export interface GetPageDataOptions {
  * directly from CloudFront in production (the CDN points at the release
  * artifacts in S3, no runtime content fetching).
  */
-export declare function getPageData(astro: AstroGlobal, _options?: GetPageDataOptions): Promise<PageData>;
+export declare function getPageData(astro: AstroGlobal, options?: GetPageDataOptions): Promise<PageData>;

package/dist/astro/page.js

@@ -30,11 +30,12 @@
  * The page template receives a typed data object and only needs to
  * iterate slots and render blocks via the registry.
  */
+import { FragmentNotFoundError } from '../content/provider.js';
 import { normalizeRoute } from '../content/routes.js';
 import { routeMetadataForContent } from '../content/provider.js';
 import { resolveSlots } from '../content/resolve-slots.js';
 import { assignmentsScriptTagHTML, collectScriptTagHTML } from '../content/personalization.js';
-import { getPendingRenderInputFromHeaders } from '../runtime/page.js';
+import { GRADIAL_RENDER_INPUT_HEADER, getPendingRenderInputFromHeaders } from '../runtime/page.js';
 // ---------------------------------------------------------------------------
 // Implementation
 // ---------------------------------------------------------------------------
@@ -52,23 +53,25 @@ import { getPendingRenderInputFromHeaders } from '../runtime/page.js';
  * directly from CloudFront in production (the CDN points at the release
  * artifacts in S3, no runtime content fetching).
  */
-export async function getPageData(astro, _options) {
+export async function getPageData(astro, options) {
     const route = normalizeRoute(astro.params.slug ? `/${astro.params.slug}` : '/');
-    // Check for preview render input first (same as Next.js tier 1)
-    // Skip during prerender/static generation — request.headers is not available
+    // Static Astro generation is explicit; unexpected header access errors and
+    // expired render-input IDs must not turn a selected variant into local base.
     let runtimeInput = null;
-    try {
-        runtimeInput = getPendingRenderInputFromHeaders(astro.request.headers);
-    }
-    catch {
-        // Astro throws when accessing request.headers during prerender — this is
-        // expected and harmless; preview mode is a request-time concern.
+    if (!astro.isPrerendered) {
+        const headers = astro.request.headers;
+        runtimeInput = getPendingRenderInputFromHeaders(headers);
+        if (headers.has(GRADIAL_RENDER_INPUT_HEADER) && !runtimeInput) {
+            throw new Error(`ACI Astro render input is unavailable for route ${route}; refusing to render local base content`);
+        }
     }
     let siteConfig;
     let page;
     let providerModule = null;
     let provider = null;
+    let variantKey;
     if (runtimeInput) {
+        variantKey = requireVariantKey(runtimeInput.variantKey, route);
         siteConfig = runtimeInput.siteConfig;
         page = runtimeInput.page;
     }
@@ -76,19 +79,23 @@ export async function getPageData(astro, _options) {
         // Lazy-import FileContentProvider to avoid pulling it in when
         // preview render input is available
         providerModule = await import('../providers/file.js');
-        provider = new providerModule.FileContentProvider();
+        provider = new providerModule.FileContentProvider(options?.compiledRoot);
         [siteConfig, page] = await Promise.all([
             provider.getSiteConfig(),
             provider.getPage(route),
         ]);
+        const entry = (await provider.listRoutes()).find((entry) => normalizeRoute(entry.path) === route);
+        variantKey = requireVariantKey(entry?.variantKey, route);
     }
     const meta = routeMetadataForContent(siteConfig, page);
     // Resolve layout: prefer render input, fall back to provider
-    const layout = await resolveLayout(runtimeInput, provider, providerModule, page.layout);
+    const layout = await resolveLayout(runtimeInput, provider, page.layout, route);
     // Resolve slots: page regions filled, then layout fragment defaults
     const slots = await resolveSlots(layout, page?.regions || {}, async (id) => {
-        if (runtimeInput?.fragments?.[id]) {
-            return runtimeInput.fragments[id];
+        if (runtimeInput) {
+            if (Object.hasOwn(runtimeInput.fragments ?? {}, id))
+                return runtimeInput.fragments[id];
+            throw new FragmentNotFoundError(id, new Error('fragment is not bound by the selected page'));
         }
         const p = provider ?? new (await import('../providers/file.js')).FileContentProvider();
         return await p.getFragment(id);
@@ -97,22 +104,27 @@ export async function getPageData(astro, _options) {
     const isPreview = astro.url.searchParams.has('preview_token');
     const collectTag = isPreview ? '' : collectScriptTagHTML(siteConfig);
     const assignmentsTag = isPreview ? '' : assignmentsScriptTagHTML(page);
-    return { route, siteConfig, page, meta, layout, slots, collectTag, assignmentsTag };
+    return { route, variantKey, siteConfig, page, meta, layout, slots, collectTag, assignmentsTag };
+}
+function requireVariantKey(value, route) {
+    if (typeof value !== 'string' || !value.trim() || value !== value.trim()) {
+        throw new Error(`ACI Astro render variant identity is missing or invalid for route ${route}; supply an explicit variantKey ("base" for an unpersonalized render)`);
+    }
+    return value;
 }
 // ---------------------------------------------------------------------------
 // Internal helpers
 // ---------------------------------------------------------------------------
-async function resolveLayout(runtimeInput, provider, providerModule, layoutName) {
-    // Check render input first
-    if (runtimeInput?.layouts?.[layoutName]) {
-        return runtimeInput.layouts[layoutName];
+async function resolveLayout(runtimeInput, provider, layoutName, route) {
+    if (runtimeInput) {
+        const layout = runtimeInput.layouts?.[layoutName];
+        if (!layout)
+            throw new Error(`ACI Astro render input for route ${route} is missing its selected layout ${JSON.stringify(layoutName)}`);
+        return layout;
     }
     // Fall back to provider
     if (provider) {
         return await provider.getLayout(layoutName);
     }
-    // Last resort: create a new provider
-    const mod = providerModule ?? await import('../providers/file.js');
-    const p = new mod.FileContentProvider();
-    return await p.getLayout(layoutName);
+    throw new Error(`ACI Astro content provider is unavailable for route ${route}`);
 }

package/dist/cli/compile-registry.mjs

@@ -31,13 +31,15 @@ if (isMainModule()) {
     }
 }
 async function compileRegistry(options) {
-    const required = ['components', 'layouts', 'output'];
+    if (options.layouts) {
+        throw new Error('--layouts is retired; author page composition under /templates instead');
+    }
+    const required = ['components', 'output'];
     for (const key of required) {
         if (!options[key])
             throw new Error(`missing --${key}`);
     }
     const components = await loadDefaultArray(options.components, 'component registry');
-    const layouts = await loadDefaultArray(options.layouts, 'layout registry');
     const dataModels = options.data
         ? await loadDefaultArray(options.data, 'data model registry')
         : [];
@@ -65,8 +67,6 @@ async function compileRegistry(options) {
             ...(Object.keys(slots).length ? { slots } : {}),
         });
     }
-    const seenLayouts = new Set();
-    const layoutEntries = layouts.map((layout, index) => validateLayout(layout, index, seenLayouts));
     const seenDataModels = new Set();
     const dataModelEntries = [];
     if (dataModels.length > 0) {
@@ -98,7 +98,6 @@ async function compileRegistry(options) {
         manifestVersion: '1',
         generatedAt: new Date().toISOString(),
         components: componentEntries,
-        layouts: layoutEntries,
         dataModels: dataModelEntries,
     };
     const registryPath = path.join(outDir, 'registry.json');
@@ -109,7 +108,7 @@ async function compileRegistry(options) {
 }
 async function loadDefaultArray(modulePath, label) {
     const mod = await import(pathToFileURL(path.resolve(modulePath)).href);
-    const value = mod.default ?? mod.registry ?? mod.components ?? mod.layouts ?? mod.dataModels;
+    const value = mod.default ?? mod.registry ?? mod.components ?? mod.dataModels;
     if (!Array.isArray(value))
         throw new Error(`${label} must export an array`);
     return value;
@@ -397,32 +396,6 @@ function unwrapSchema(schema) {
     }
     return current;
 }
-function validateLayout(layout, index, seen) {
-    if (!layout || typeof layout !== 'object')
-        throw new Error(`layouts[${index}] must be an object`);
-    if (!layout.name)
-        throw new Error(`layouts[${index}].name is required`);
-    if (seen.has(layout.name))
-        throw new Error(`duplicate layout name ${layout.name}`);
-    seen.add(layout.name);
-    if (!Array.isArray(layout.slots))
-        throw new Error(`layouts[${index}].slots must be an array`);
-    const slots = [];
-    const seenSlots = new Set();
-    for (const [slotIndex, slot] of layout.slots.entries()) {
-        if (!slot?.name)
-            throw new Error(`layouts[${index}].slots[${slotIndex}].name is required`);
-        if (seenSlots.has(slot.name))
-            throw new Error(`duplicate slot name ${slot.name} in layout ${layout.name}`);
-        seenSlots.add(slot.name);
-        slots.push({ name: slot.name, required: Boolean(slot.required) });
-    }
-    const entry = { name: layout.name, slots };
-    if (layout.defaults && typeof layout.defaults === 'object') {
-        entry.defaults = layout.defaults;
-    }
-    return entry;
-}
 function compileSchema(schema, name) {
     const toJSONSchema = z.toJSONSchema;
     if (typeof toJSONSchema !== 'function') {
@@ -516,13 +489,12 @@ async function generatePageSchema(schemaDir, componentEntries, outDir) {
         $id: 'https://baremetal.local/schemas/page.schema.json',
         title: 'bare-metal Page',
         type: 'object',
-        required: ['$type', 'id', 'status', 'layout', 'metadata', 'regions'],
+        required: ['$type', 'id', 'status', 'metadata', 'regions'],
         additionalProperties: true,
         properties: {
             $type: { const: 'page' },
             id: { type: 'string', minLength: 1 },
             status: { type: 'string', minLength: 1 },
-            layout: { type: 'string', minLength: 1 },
             metadata: {
                 type: 'object',
                 required: ['title'],

package/dist/content/index.d.ts

@@ -3,6 +3,7 @@ export * from './routes.js';
 export * from './types.js';
 export * from './personalization.js';
 export * from './cache.js';
-export * from './resolve-slots.js';
+export { FragmentResolutionError, MAX_EXPANDED_BLOCKS, MAX_FRAGMENT_DEPTH, fragmentToBlock, preserveFragmentScope, resolveFragmentNodes, resolveSlots, resolveSlotsSync, } from './resolve-slots.js';
+export type { FragmentBlock, FragmentData, FragmentLoader } from './resolve-slots.js';
 export * from './default-error-page.js';
 export * from './error-pages.js';

package/dist/content/index.js

@@ -3,6 +3,9 @@ export * from './routes.js';
 export * from './types.js';
 export * from './personalization.js';
 export * from './cache.js';
-export * from './resolve-slots.js';
+// Explicit list, not `export *`: fragmentRootScope is runtime-only provenance
+// shared with mintlify/blocks.ts via a direct resolve-slots import and must
+// never leak into the public '@gradial/aci/content' surface.
+export { FragmentResolutionError, MAX_EXPANDED_BLOCKS, MAX_FRAGMENT_DEPTH, fragmentToBlock, preserveFragmentScope, resolveFragmentNodes, resolveSlots, resolveSlotsSync, } from './resolve-slots.js';
 export * from './default-error-page.js';
 export * from './error-pages.js';

package/dist/content/provider.d.ts

@@ -2,6 +2,7 @@ import type { KernelPage, KernelRouteMetadata, KernelSiteConfig, RenderInput } f
 export interface RouteEntry {
     slug: string;
     path: string;
+    variantKey: string;
     payloadRef: string;
     digest: string;
     fragmentRefs?: string[];
@@ -25,6 +26,11 @@ export interface LayoutVariantEntry {
     slots: LayoutSlot[];
     defaults?: Record<string, FragmentRef[]>;
 }
+/**
+ * Derived template render plan in the compiled release wire format.
+ * This is never an authorable layout: page templates own regions and defaults.
+ * The LayoutEntry name and layouts wire key remain for retained release readers.
+ */
 export interface LayoutEntry {
     name: string;
     digest?: string;
@@ -40,7 +46,6 @@ export interface LayoutSlot {
 export interface FragmentRef {
     kind: string;
     fragmentId: string;
-    inline: boolean;
 }
 export interface CompiledManifest {
     manifestVersion: string;
@@ -67,8 +72,9 @@ export declare class LayoutNotFoundError extends Error {
     constructor(name: string, cause?: unknown);
 }
 export interface RenderInputOptions {
+    variantKey: string;
     domain?: string;
     locale?: string;
 }
-export declare function loadRenderInput(provider: ContentProvider, route?: string, options?: RenderInputOptions): Promise<RenderInput>;
+export declare function loadRenderInput(provider: ContentProvider, route: string | undefined, options: RenderInputOptions): Promise<RenderInput>;
 export declare function routeMetadataForContent(siteConfig: KernelSiteConfig, page: KernelPage | null): KernelRouteMetadata;

package/dist/content/provider.js

@@ -24,8 +24,11 @@ export class LayoutNotFoundError extends Error {
     }
 }
 import { getCachedSiteConfig } from './cache.js';
-export async function loadRenderInput(provider, route = '/', options = {}) {
+export async function loadRenderInput(provider, route = '/', options) {
     const normalized = normalizeRoute(route);
+    if (typeof options?.variantKey !== 'string' || !options.variantKey.trim() || options.variantKey !== options.variantKey.trim()) {
+        throw new Error(`ACI render variant identity is missing or invalid for route ${normalized}; supply an explicit variantKey`);
+    }
     const [siteConfig, page] = await Promise.all([
         getCachedSiteConfig(provider),
         provider.getPage(normalized).catch((error) => {
@@ -36,6 +39,7 @@ export async function loadRenderInput(provider, route = '/', options = {}) {
     ]);
     return {
         route: normalized,
+        variantKey: options.variantKey,
         domain: options.domain || siteConfig.domain,
         locale: (options.locale || siteConfig.defaultLocale || 'en-us').toLowerCase(),
         siteConfig,

package/dist/content/resolve-slots.d.ts

@@ -1,5 +1,5 @@
 import type { LayoutEntry } from './provider.js';
-import type { KernelPageBlock } from './types.js';
+import type { KernelPageBlock, KernelPageNode } from './types.js';
 export interface FragmentBlock {
     $type: 'component';
     component: string;
@@ -13,4 +13,26 @@ export interface FragmentData {
     props?: Record<string, unknown>;
 }
 export type FragmentLoader = (id: string) => Promise<FragmentData>;
-export declare function resolveSlots(layout: LayoutEntry, pageRegions: Record<string, KernelPageBlock[]>, getFragment: FragmentLoader): Promise<Record<string, KernelPageBlock[]>>;
+/**
+ * Shared Go/TS limit contract (sdk I-21). These values are pinned against
+ * internal/domain/content/compiler/testdata/limit-conformance.v1.json by
+ * limit-conformance.test.ts (TS) and limit_conformance_test.go (Go); the
+ * compiler's MaxFragmentDepth/MaxExpandedBlocks must match.
+ */
+/** Bounds a selected fragment reference chain, counting its root fragment. */
+export declare const MAX_FRAGMENT_DEPTH = 10;
+/** Bounds rendered component occurrences per page, including repeated placements. */
+export declare const MAX_EXPANDED_BLOCKS = 4096;
+/** Failures in a selected fragment are never eligible for local-content fallback. */
+export declare class FragmentResolutionError extends Error {
+    constructor(message: string, options?: ErrorOptions);
+}
+export declare const fragmentRootScope: unique symbol;
+export declare function preserveFragmentScope<T extends object>(source: object, target: T): T;
+export declare function resolveSlots(plan: LayoutEntry, pageRegions: Record<string, KernelPageNode[]>, getFragment: FragmentLoader): Promise<Record<string, KernelPageBlock[]>>;
+/** The config-time error seat uses the identical traversal with synchronous file reads. */
+export declare function resolveSlotsSync(plan: LayoutEntry, pageRegions: Record<string, KernelPageNode[]>, getFragment: (id: string) => FragmentData): Record<string, KernelPageBlock[]>;
+/** Resolve compiled references through the exact fragment bindings selected for this page. */
+export declare function resolveFragmentNodes(nodes: readonly KernelPageNode[], getFragment: FragmentLoader): Promise<KernelPageBlock[]>;
+/** Use the same fragment root identity for layout defaults and region placements. */
+export declare function fragmentToBlock(fragment: FragmentData, id: string): KernelPageBlock;

package/dist/content/resolve-slots.js

@@ -1,26 +1,132 @@
-export async function resolveSlots(layout, pageRegions, getFragment) {
-    const resolved = {};
-    for (const slot of layout.slots) {
-        const pageBlocks = pageRegions[slot.name];
-        if (pageBlocks && pageBlocks.length > 0) {
-            resolved[slot.name] = pageBlocks;
-            continue;
+/**
+ * Shared Go/TS limit contract (sdk I-21). These values are pinned against
+ * internal/domain/content/compiler/testdata/limit-conformance.v1.json by
+ * limit-conformance.test.ts (TS) and limit_conformance_test.go (Go); the
+ * compiler's MaxFragmentDepth/MaxExpandedBlocks must match.
+ */
+/** Bounds a selected fragment reference chain, counting its root fragment. */
+export const MAX_FRAGMENT_DEPTH = 10;
+/** Bounds rendered component occurrences per page, including repeated placements. */
+export const MAX_EXPANDED_BLOCKS = 4096;
+/** Failures in a selected fragment are never eligible for local-content fallback. */
+export class FragmentResolutionError extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = 'FragmentResolutionError';
+    }
+}
+// Runtime-only provenance keeps each fragment placement's authored IDs in its
+// own validation scope. It is never emitted into compiled JSON or HTML.
+export const fragmentRootScope = Symbol('aci.fragment-root-scope');
+export function preserveFragmentScope(source, target) {
+    return Object.hasOwn(source, fragmentRootScope)
+        ? Object.defineProperty(target, fragmentRootScope, { value: true })
+        : target;
+}
+export async function resolveSlots(plan, pageRegions, getFragment) {
+    return resolveAsync(walkSlots(plan, pageRegions), getFragment);
+}
+/** The config-time error seat uses the identical traversal with synchronous file reads. */
+export function resolveSlotsSync(plan, pageRegions, getFragment) {
+    const walk = walkSlots(plan, pageRegions);
+    let step = walk.next();
+    while (!step.done) {
+        let fragment;
+        try {
+            fragment = getFragment(step.value);
         }
-        const defaults = layout.defaults?.[slot.name];
-        if (defaults?.length) {
-            const blocks = [];
-            for (const ref of defaults) {
-                const fragment = await getFragment(ref.fragmentId);
-                const block = fragment.block ?? { component: fragment.component ?? '', props: fragment.props };
-                blocks.push({
-                    $type: 'component',
-                    id: fragment.id ?? fragment.fragmentId ?? ref.fragmentId,
-                    component: block.component,
-                    props: block.props || {},
-                });
-            }
-            resolved[slot.name] = blocks;
+        catch (cause) {
+            throw bindingError(step.value, cause);
         }
+        step = walk.next(fragment);
+    }
+    return step.value;
+}
+/** Resolve compiled references through the exact fragment bindings selected for this page. */
+export async function resolveFragmentNodes(nodes, getFragment) {
+    return resolveAsync(walkNodes(nodes, { blocks: 0 }), getFragment);
+}
+async function resolveAsync(walk, getFragment) {
+    let step = walk.next();
+    while (!step.done) {
+        let fragment;
+        try {
+            fragment = await getFragment(step.value);
+        }
+        catch (cause) {
+            throw bindingError(step.value, cause);
+        }
+        step = walk.next(fragment);
+    }
+    return step.value;
+}
+function bindingError(id, cause) {
+    return new FragmentResolutionError(`ACI fragment ${id} selected binding failed: ${String(cause)}`, { cause });
+}
+function* walkSlots(plan, pageRegions) {
+    const resolved = {};
+    const state = { blocks: 0 };
+    for (const slot of plan.slots) {
+        const pageBlocks = pageRegions[slot.name];
+        const nodes = pageBlocks?.length ? pageBlocks : plan.defaults?.[slot.name];
+        if (nodes?.length)
+            resolved[slot.name] = yield* walkNodes(nodes, state);
     }
     return resolved;
 }
+function* walkNodes(nodes, state) {
+    const blocks = [];
+    for (const node of nodes)
+        blocks.push((yield* walkValue(node, [], state)));
+    return blocks;
+}
+// Active ancestry belongs to each placement, while the block budget belongs to
+// the whole rendered page. A repeated fragment in another branch is valid.
+function* walkValue(value, ancestry, state) {
+    if (Array.isArray(value)) {
+        const result = [];
+        for (const child of value)
+            result.push(yield* walkValue(child, ancestry, state));
+        return result;
+    }
+    if (value === null || typeof value !== 'object')
+        return value;
+    const node = value;
+    if (node.kind === 'fragment-ref') {
+        const id = node.fragmentId;
+        if (typeof id !== 'string' || !id)
+            throw new FragmentResolutionError('ACI fragment reference has no fragmentId');
+        const chain = [...ancestry, id];
+        if (ancestry.includes(id))
+            throw new FragmentResolutionError(`ACI fragment cycle: ${chain.join(' -> ')}`);
+        if (chain.length > MAX_FRAGMENT_DEPTH)
+            throw new FragmentResolutionError(`ACI fragment depth exceeds ${MAX_FRAGMENT_DEPTH}: ${chain.join(' -> ')}`);
+        const fragment = yield id;
+        const block = (yield* walkValue(fragmentToBlock(fragment, id), chain, state));
+        return Object.defineProperty(block, fragmentRootScope, { value: true });
+    }
+    const isBlock = node.$type === 'component'
+        || (typeof node.component === 'string' && node.component.length > 0
+            && node.props !== null && typeof node.props === 'object' && !Array.isArray(node.props));
+    if (isBlock && ++state.blocks > MAX_EXPANDED_BLOCKS) {
+        throw new FragmentResolutionError(`ACI rendered page exceeds ${MAX_EXPANDED_BLOCKS} component blocks`);
+    }
+    const result = {};
+    for (const [key, child] of Object.entries(node))
+        result[key] = yield* walkValue(child, ancestry, state);
+    return preserveFragmentScope(node, result);
+}
+/** Use the same fragment root identity for layout defaults and region placements. */
+export function fragmentToBlock(fragment, id) {
+    const block = fragment?.block ?? fragment;
+    if (!block || typeof block.component !== 'string' || !block.component
+        || (block.props !== undefined && (typeof block.props !== 'object' || block.props === null || Array.isArray(block.props)))) {
+        throw new FragmentResolutionError(`ACI fragment ${id} has no component block`);
+    }
+    return {
+        $type: 'component',
+        id: fragment.id ?? fragment.fragmentId ?? id,
+        component: block.component,
+        props: block.props || {},
+    };
+}