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

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.28` 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.28 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.28 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.28 init --list
 ```
 
 ## Personalization: The One-Tag Install

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,7 +31,7 @@
  * 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.

package/dist/astro/page.js

@@ -30,6 +30,7 @@
  * 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';
@@ -87,8 +88,10 @@ export async function getPageData(astro, _options) {
     const layout = await resolveLayout(runtimeInput, provider, providerModule, page.layout);
     // 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);

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

@@ -25,6 +25,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 +45,6 @@ export interface LayoutSlot {
 export interface FragmentRef {
     kind: string;
     fragmentId: string;
-    inline: boolean;
 }
 export interface CompiledManifest {
     manifestVersion: string;

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 || {},
+    };
+}

package/dist/content/types.d.ts

@@ -1,4 +1,5 @@
 import type { ExperimentAssignmentContext, SitePersonalizationConfig } from './personalization.js';
+import type { FragmentRefNode } from '../types/page.js';
 export type ButtonVariant = 'primary' | 'secondary' | 'tertiary' | 'outline' | 'ghost';
 export interface KernelImage {
     src: string;
@@ -47,6 +48,7 @@ export interface KernelPageBlock {
     component: string;
     props: Record<string, unknown>;
 }
+export type KernelPageNode = KernelPageBlock | FragmentRefNode;
 export interface KernelAtomicBlock {
     $type: 'component';
     id: string;
@@ -59,7 +61,7 @@ export interface KernelPage {
     status: string;
     layout: string;
     metadata: KernelPageSeo;
-    regions: Record<string, KernelPageBlock[]>;
+    regions: Record<string, KernelPageNode[]>;
     /**
      * Build-time experiment assignment context (personalization-reporting
      * design/04); present only on experiment variant payloads. The starters

package/dist/index.d.ts

@@ -1,5 +1,4 @@
 export { defineComponentContract } from './define-component.js';
-export { defineLayoutContract, slot, fragmentDefault } from './define-layout.js';
 export { createRegistry, registryLookup } from './registry.js';
 export type { Registry, RegistryEntry, AnyComponent } from './registry.js';
 export { blockRef, blockRefArray } from './types/block-ref.js';

package/dist/index.js

@@ -1,5 +1,4 @@
 export { defineComponentContract } from './define-component.js';
-export { defineLayoutContract, slot, fragmentDefault } from './define-layout.js';
 export { createRegistry, registryLookup } from './registry.js';
 export { blockRef, blockRefArray } from './types/block-ref.js';
 export { ImageSchema, imageAttrs, primaryImageSource, } from './types/image.js';

package/dist/mintlify/blocks.js

@@ -1,3 +1,4 @@
+import { fragmentRootScope, preserveFragmentScope } from '../content/resolve-slots.js';
 import { cleanFilePath, isMintlifyJSONValue, isObject, nonEmptyString } from './json.js';
 const GENERATED_MARKER = '{/* Generated by @gradial/aci; edit .content instead. */}';
 const SUPPORTED_COMPONENTS = new Set([
@@ -92,6 +93,8 @@ export function validateBlock(value, label, ids) {
     if (!isObject(value) || value.$type !== 'component' || !nonEmptyString(value.id) || !nonEmptyString(value.component) || !isObject(value.props)) {
         throw new Error(`ACI Mintlify block is invalid: ${label}`);
     }
+    if (Object.hasOwn(value, fragmentRootScope))
+        ids = new Set();
     if (ids.has(value.id))
         throw new Error(`ACI Mintlify block ID is duplicated: ${value.id}`);
     ids.add(value.id);
@@ -112,7 +115,7 @@ export function validateBlock(value, label, ids) {
         }
     }
     validateComponentProps(value.component, props, label);
-    return { $type: 'component', id: value.id, component: value.component, props };
+    return preserveFragmentScope(value, { $type: 'component', id: value.id, component: value.component, props });
 }
 function validateComponentProps(component, props, label) {
     if (component === 'mintlify.markdown' || component === 'mintlify.mdx') {

package/dist/mintlify/index.d.ts

@@ -1,3 +1,3 @@
-export { materializeMintlifySite, loadMintlifySource, loadCompiledMintlifySource, } from './materialize.js';
+export { materializeMintlifySite, resolveMintlifyDocument, loadMintlifySource, loadCompiledMintlifySource, } from './materialize.js';
 export { renderDocument, renderSnippet } from './blocks.js';
 export type { MintlifyAPISpec, MintlifyBlock, MintlifyConfigFragment, MintlifyDocument, MintlifyJSONValue, MintlifyNavigationGroup, MintlifySite, MintlifySnippet, MintlifySource, } from './types.js';

package/dist/mintlify/index.js

@@ -1,2 +1,2 @@
-export { materializeMintlifySite, loadMintlifySource, loadCompiledMintlifySource, } from './materialize.js';
+export { materializeMintlifySite, resolveMintlifyDocument, loadMintlifySource, loadCompiledMintlifySource, } from './materialize.js';
 export { renderDocument, renderSnippet } from './blocks.js';

package/dist/mintlify/materialize.d.ts

@@ -1,4 +1,4 @@
-import type { MaterializeMintlifySiteOptions, MintlifySource } from './types.js';
+import type { MaterializeMintlifySiteOptions, MintlifyDocument, MintlifySource } from './types.js';
 /**
  * Reads a site and its documents from ACI's portable JSON content tree.
  * The source shape is standard ACI content: `config/mintlify.json`, resources
@@ -10,3 +10,5 @@ export declare function loadMintlifySource(sourceDir: string): Promise<MintlifyS
 export declare function loadCompiledMintlifySource(sourceDir: string, compiledDir: string): Promise<MintlifySource>;
 /** Materializes one exact Mintlify site from ACI source content. */
 export declare function materializeMintlifySite(options: MaterializeMintlifySiteOptions): Promise<void>;
+/** Project a runtime page using only its selected, immutable fragment bindings. */
+export declare function resolveMintlifyDocument(value: unknown, fragments: Record<string, unknown>, documentPath: string, layout: unknown): Promise<MintlifyDocument>;