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

package/dist/mintlify/materialize.js

@@ -1,3 +1,5 @@
+import { resolveSlots, resolveFragmentNodes } from '../content/resolve-slots.js';
+import { FragmentNotFoundError } from '../content/provider.js';
 import { mkdir, readFile, readdir, writeFile, } from 'node:fs/promises';
 import path from 'node:path';
 import { resolveConfigReferences, toDocsJSON } from './config.js';
@@ -20,10 +22,19 @@ export async function loadMintlifySource(sourceDir) {
         readOptionalJSONResources(path.join(sourceDir, 'config', 'mintlify')),
         readOptionalJSONResources(path.join(sourceDir, 'data', 'mintlify-api')),
     ]);
+    const sourceFragments = new Map(fragmentResources.map(({ value, relative }) => [relative.slice(0, -'/_index.json'.length), value]));
+    const getFragment = async (id) => {
+        if (!sourceFragments.has(id))
+            throw new FragmentNotFoundError(id);
+        return sourceFragments.get(id);
+    };
     return {
         site: validateSite(site, sitePath),
-        documents: pageResources.map(({ value, file, relative }) => validateDocument(value, file, relative === '_index.json' ? 'index' : relative.slice(0, -'/_index.json'.length))),
-        snippets: fragmentResources.map(({ value, file, relative }) => validateSnippet(value, file, `${relative.slice(0, -'/_index.json'.length)}.mdx`)),
+        documents: await Promise.all(pageResources.map(async ({ value, file, relative }) => validateDocument(await expandDocument(value, getFragment), file, relative === '_index.json' ? 'index' : relative.slice(0, -'/_index.json'.length)))),
+        snippets: await Promise.all(fragmentResources.map(async ({ value, file, relative }) => {
+            const id = relative.slice(0, -'/_index.json'.length);
+            return validateSnippet(await expandSnippet(value, id, getFragment), file, `${id}.mdx`);
+        })),
         configFragments: configFragments.map(({ value, file }) => validateConfigFragment(value, file)),
         apiSpecs: apiSpecs.map(({ value, file }) => validateAPISpec(value, file)),
     };
@@ -40,16 +51,27 @@ export async function loadCompiledMintlifySource(sourceDir, compiledDir) {
     if (!isObject(manifestValue) || !isObject(manifestValue.routes) || !isObject(manifestValue.fragments)) {
         throw new Error(`ACI compiled manifest is invalid: ${manifestPath}`);
     }
-    const documents = await Promise.all(Object.entries(manifestValue.routes).map(async ([slug, entry]) => {
+    const fragments = await Promise.all(Object.entries(manifestValue.fragments).map(async ([id, entry]) => {
         if (!isObject(entry) || typeof entry.payloadRef !== 'string')
-            throw new Error(`ACI compiled route is invalid: ${slug}`);
-        return validateDocument(await readJSON(safeOutputPath(compiledDir, entry.payloadRef)), entry.payloadRef, slug || 'index');
+            throw new Error(`ACI compiled fragment is invalid: ${id}`);
+        return { id, entry, value: await readJSON(safeOutputPath(compiledDir, entry.payloadRef)) };
     }));
-    const snippets = await Promise.all(Object.entries(manifestValue.fragments).map(async ([id, entry]) => {
+    const byId = new Map(fragments.map(({ id, value }) => [id, value]));
+    const getFragment = async (id) => {
+        if (!byId.has(id))
+            throw new FragmentNotFoundError(id);
+        return byId.get(id);
+    };
+    const documents = await Promise.all(Object.entries(manifestValue.routes).map(async ([slug, entry]) => {
         if (!isObject(entry) || typeof entry.payloadRef !== 'string')
-            throw new Error(`ACI compiled fragment is invalid: ${id}`);
-        return validateSnippet(await readJSON(safeOutputPath(compiledDir, entry.payloadRef)), entry.payloadRef, `${id}.mdx`);
+            throw new Error(`ACI compiled route is invalid: ${slug}`);
+        const value = await readJSON(safeOutputPath(compiledDir, entry.payloadRef));
+        const layout = isObject(value) && typeof value.layout === 'string' && isObject(manifestValue.layouts)
+            ? manifestValue.layouts[value.layout] : undefined;
+        const plan = requireMintlifyLayout(value, layout, entry.payloadRef);
+        return validateDocument(await expandDocument(value, getFragment, plan), entry.payloadRef, slug || 'index');
     }));
+    const snippets = await Promise.all(fragments.map(async ({ id, entry, value }) => validateSnippet(await expandSnippet(value, id, getFragment), String(entry.payloadRef), `${id}.mdx`)));
     return {
         site: validateSite(siteValue, sitePath), documents, snippets,
         configFragments: configFragments.map(({ value, file }) => validateConfigFragment(value, file)),
@@ -60,8 +82,9 @@ export async function loadCompiledMintlifySource(sourceDir, compiledDir) {
 export async function materializeMintlifySite(options) {
     const outputDir = path.resolve(options.outputDir);
     const site = validateSite(options.site, 'site');
-    const documents = options.documents.map((document, index) => validateDocument(document, `documents[${index}]`, document.path));
-    const snippets = (options.snippets ?? []).map((snippet, index) => validateSnippet(snippet, `snippets[${index}]`, snippet.path));
+    const getFragment = fragmentLoader(options.snippets ?? []);
+    const documents = await Promise.all(options.documents.map(async (document, index) => validateDocument(await expandDocument(document, getFragment), `documents[${index}]`, document.path)));
+    const snippets = await Promise.all((options.snippets ?? []).map(async (snippet, index) => validateSnippet(await expandSnippet(snippet, snippet.id, getFragment), `snippets[${index}]`, snippet.path)));
     const configFragments = (options.configFragments ?? []).map((fragment, index) => validateConfigFragment(fragment, `configFragments[${index}]`));
     const apiSpecs = (options.apiSpecs ?? []).map((spec, index) => validateAPISpec(spec, `apiSpecs[${index}]`));
     const nativeConfig = toDocsJSON(site);
@@ -157,3 +180,75 @@ function safeOutputPath(root, relativePath) {
         throw new Error(`ACI Mintlify generated path escapes output directory: ${relativePath}`);
     return target;
 }
+function fragmentLoader(fragments) {
+    const byId = new Map();
+    for (const fragment of fragments) {
+        if (!isObject(fragment) || typeof fragment.id !== 'string')
+            continue;
+        if (byId.has(fragment.id))
+            throw new Error(`ACI fragment ID is duplicated: ${fragment.id}`);
+        byId.set(fragment.id, fragment);
+    }
+    return async (id) => {
+        const fragment = byId.get(id);
+        if (!fragment)
+            throw new FragmentNotFoundError(id);
+        return fragment;
+    };
+}
+function requireMintlifyLayout(page, value, label) {
+    if (!isObject(page) || !isObject(value) || typeof value.name !== 'string'
+        || page.layout !== value.name || !Array.isArray(value.slots)) {
+        throw new Error(`ACI Mintlify document ${label} requires its exact bound template render plan`);
+    }
+    for (const slot of value.slots) {
+        if (!isObject(slot) || slot.name !== 'main') {
+            throw new Error(`ACI Mintlify template ${value.name} has unsupported region ${JSON.stringify(isObject(slot) ? slot.name : slot)}; only main is supported (${label})`);
+        }
+    }
+    if (value.slots.length !== 1)
+        throw new Error(`ACI Mintlify template ${value.name} must declare exactly one main region (${label})`);
+    if (value.defaults !== undefined) {
+        if (!isObject(value.defaults))
+            throw new Error(`ACI Mintlify template ${value.name} has invalid defaults (${label})`);
+        for (const [region, nodes] of Object.entries(value.defaults)) {
+            if (region !== 'main')
+                throw new Error(`ACI Mintlify template ${value.name} has unsupported default region ${JSON.stringify(region)}; only main is supported (${label})`);
+            if (!Array.isArray(nodes))
+                throw new Error(`ACI Mintlify template ${value.name} has invalid main defaults (${label})`);
+        }
+    }
+    return value;
+}
+async function expandDocument(value, getFragment, layout) {
+    if (!isObject(value) || !isObject(value.regions))
+        return value;
+    if (Object.hasOwn(value.regions, 'main') && !Array.isArray(value.regions.main))
+        return value;
+    if (layout) {
+        const resolved = await resolveSlots(layout, value.regions, getFragment);
+        // Preserve unexpected authored keys so validateDocument can refuse them.
+        return { ...value, regions: { ...value.regions, main: resolved.main ?? [] } };
+    }
+    if (!Array.isArray(value.regions.main))
+        return value;
+    return { ...value, regions: { ...value.regions, main: await resolveFragmentNodes(value.regions.main, getFragment) } };
+}
+/** Project a runtime page using only its selected, immutable fragment bindings. */
+export async function resolveMintlifyDocument(value, fragments, documentPath, layout) {
+    const getFragment = async (id) => {
+        if (!Object.hasOwn(fragments, id))
+            throw new FragmentNotFoundError(id);
+        return fragments[id];
+    };
+    const plan = requireMintlifyLayout(value, layout, documentPath);
+    return validateDocument(await expandDocument(value, getFragment, plan), documentPath, documentPath);
+}
+// Standalone snippets traverse the root reference too, so a root self-reference
+// uses the same ancestry/depth checks as a page placement.
+async function expandSnippet(value, id, getFragment) {
+    if (!isObject(value))
+        return value;
+    const [block] = await resolveFragmentNodes([{ kind: 'fragment-ref', fragmentId: id }], getFragment);
+    return { ...value, id: value.id ?? id, block };
+}

package/dist/mintlify/types.d.ts

@@ -1,3 +1,4 @@
+import type { FragmentRefNode } from '../types/page.js';
 export type MintlifyJSONValue = null | boolean | number | string | MintlifyJSONValue[] | {
     [key: string]: MintlifyJSONValue;
 };
@@ -23,7 +24,6 @@ export interface MintlifyDocument {
     $type: 'page';
     id: string;
     status: string;
-    layout: string;
     path: string;
     metadata: {
         title: string;
@@ -64,6 +64,11 @@ export interface MintlifySource {
     configFragments?: MintlifyConfigFragment[];
     apiSpecs?: MintlifyAPISpec[];
 }
-export interface MaterializeMintlifySiteOptions extends MintlifySource {
+export interface MaterializeMintlifySiteOptions extends Omit<MintlifySource, 'documents'> {
+    documents: Array<Omit<MintlifyDocument, 'regions'> & {
+        regions: {
+            main: Array<MintlifyBlock | FragmentRefNode>;
+        };
+    }>;
     outputDir: string;
 }

package/dist/mintlify/validate.js

@@ -41,9 +41,13 @@ export function validateSite(value, label) {
 export function validateDocument(value, label, sourcePath) {
     const metadata = isObject(value) && isObject(value.metadata) ? value.metadata : undefined;
     const regions = isObject(value) && isObject(value.regions) ? value.regions : undefined;
-    if (!isObject(value) || value.$type !== 'page' || !nonEmptyString(value.id) || !nonEmptyString(value.status) || !nonEmptyString(value.layout) || !nonEmptyString(sourcePath) || !metadata || !nonEmptyString(metadata.title) || !regions || !Array.isArray(regions.main)) {
+    if (!isObject(value) || value.$type !== 'page' || !nonEmptyString(value.id) || !nonEmptyString(value.status) || !nonEmptyString(sourcePath) || !metadata || !nonEmptyString(metadata.title) || !regions || !Array.isArray(regions.main)) {
         throw new Error(`ACI Mintlify document is invalid: ${label}`);
     }
+    for (const region of Object.keys(regions)) {
+        if (region !== 'main')
+            throw new Error(`ACI Mintlify document ${label} has unsupported region ${JSON.stringify(region)}; only main is supported`);
+    }
     const documentPath = cleanDocumentPath(sourcePath);
     if (!documentPath || documentPath !== sourcePath)
         throw new Error(`ACI Mintlify document path is invalid: ${sourcePath}`);
@@ -51,7 +55,7 @@ export function validateDocument(value, label, sourcePath) {
     const blocks = regions.main.map((block, index) => validateBlock(block, `${label}.regions.main[${index}]`, ids));
     const renderer = isObject(metadata.mintlify) ? metadata.mintlify : {};
     return {
-        $type: 'page', id: value.id, status: value.status, layout: value.layout, path: documentPath,
+        $type: 'page', id: value.id, status: value.status, path: documentPath,
         metadata: { title: metadata.title,
             ...(nonEmptyString(metadata.description) ? { description: metadata.description } : {}),
             mintlify: {

package/dist/next/config.js

@@ -33,33 +33,9 @@ export function withAci(nextConfig = {}, options = {}) {
     const userRewrites = nextConfig.rewrites;
     const userHeaders = nextConfig.headers;
     const userWebpack = nextConfig.webpack;
-    // Build assets (_next/static/*) are content-addressed and stored globally.
-    // When ACI_ASSET_BASE_TPL is an absolute CDN URL, strip __RELEASE_ID__
-    // (release-independent) and use it as Next.js's native assetPrefix so the
-    // build writes absolute CDN URLs for _next/static chunks — no post-
-    // processing needed.
-    //   - Managed tenants (edge handler): "/__r/__RELEASE_ID__/" or unset →
-    //     do not set assetPrefix; the SSG writes relative paths and the edge
-    //     handler rewrites to the global S3 key.
-    //   - External CDN tenants: "https://cdn.gradial.com/" → absolute CDN URLs.
-    const rawAssetBaseTpl = process.env.ACI_ASSET_BASE_TPL || '';
-    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') {
-        throw new Error('ACI_ASSET_PATH_LAYOUT=flat-assets currently supports Astro builds only');
-    }
-    const cdnAssetPrefix = rawAssetBaseTpl
-        .replace('__RELEASE_ID__/', '')
-        .replace('__RELEASE_ID__', '')
-        .replace(/\/+$/, '/');
-    const isCdnUrl = cdnAssetPrefix.startsWith('http://') || cdnAssetPrefix.startsWith('https://');
-    const nextAssetPrefix = (isCdnUrl && cdnAssetPrefix !== '/') ? cdnAssetPrefix : undefined;
     return {
         ...nextConfig,
         output: 'standalone',
-        assetPrefix: nextAssetPrefix ?? nextConfig.assetPrefix,
         outputFileTracingRoot: nextConfig.outputFileTracingRoot ?? process.cwd(),
         headers: async () => {
             const gradialHeaders = [

package/dist/next/error-seat-payload.d.ts

@@ -13,7 +13,8 @@ import type { ErrorSeatPayload } from './error-seat.js';
  * - present-but-broken bindings — exactly the enumerated REQ-5 failures
  *   (malformed route, unresolved page, unpublished page, audience/experiment
  *   overlays — REQ-11) → `errors` in BOTH postures;
- * - ANY other exception (stale/corrupt compiled content, old manifest
+ * - selected fragment binding or expansion failures are errors in both postures;
+ * - other exceptions (stale/corrupt compiled content, old manifest
  *   shapes) warns-and-defaults under warn and errors only under enforce, so
  *   a stale .aci/compiled tree can never break a binding-less build.
  *

package/dist/next/error-seat-payload.js

@@ -1,3 +1,4 @@
+import { FragmentResolutionError, resolveSlotsSync } from '../content/resolve-slots.js';
 import { existsSync, readFileSync } from 'node:fs';
 import path from 'node:path';
 import { ERROR_PAGE_ROUTE_PATTERN } from '../content/error-pages.js';
@@ -86,29 +87,13 @@ export function buildErrorSeatPayload(contentRoot, posture) {
         const route = bindings.catchAll;
         const page = readJSON(root, catchAllEntry.payloadRef);
         const layout = readJSON(root, `layouts/${page.layout}.json`);
-        const slots = {};
-        const slotOrder = [];
-        for (const slot of layout.slots) {
-            slotOrder.push(slot.name);
-            const pageBlocks = page.regions?.[slot.name];
-            if (pageBlocks?.length) {
-                slots[slot.name] = pageBlocks;
-                continue;
-            }
-            const defaults = layout.defaults?.[slot.name];
-            if (!defaults?.length)
-                continue;
-            const blocks = [];
-            for (const ref of defaults) {
-                const fragmentRef = manifest.fragments[ref.fragmentId]?.payloadRef;
-                if (!fragmentRef)
-                    continue;
-                const fragment = readJSON(root, fragmentRef);
-                blocks.push({ $type: 'component', id: fragment.id, component: fragment.component, props: fragment.props || {} });
-            }
-            if (blocks.length)
-                slots[slot.name] = blocks;
-        }
+        const slots = resolveSlotsSync(layout, page.regions ?? {}, (id) => {
+            const fragmentRef = manifest.fragments[id]?.payloadRef;
+            if (!fragmentRef)
+                throw new Error(`Fragment not found: ${id}`);
+            return readJSON(root, fragmentRef);
+        });
+        const slotOrder = layout.slots.map((slot) => slot.name);
         return {
             payload: {
                 defaulted: false,
@@ -123,7 +108,12 @@ export function buildErrorSeatPayload(contentRoot, posture) {
         };
     }
     catch (error) {
-        // Not one of the enumerated REQ-5 binding failures (those are pushed to
+        if (error instanceof FragmentResolutionError) {
+            errors.push(error.message);
+            return defaulted();
+        }
+        // Neither a selected-fragment failure nor an enumerated REQ-5 binding
+        // failure (those are pushed to
         // `errors` above): stale/corrupt compiled content or an old manifest
         // shape. Warn-and-default under the warn posture so it can never break a
         // build; fail closed only under enforce (quorum RISK-002).

package/dist/next/error-seat.js

@@ -69,7 +69,7 @@ function renderPayload(data, registry) {
 // async and server-oriented). Unknown components are skipped — the error
 // seat degrades, it never crashes.
 function renderClientBlocks(blocks, registry) {
-    return blocks.map((block) => {
+    return blocks.map((block, index) => {
         const entry = registry.find((r) => r.id === block.component);
         if (!entry)
             return null;
@@ -81,6 +81,8 @@ function renderClientBlocks(blocks, registry) {
         // sdk I-19 (ADR 0051): the error seat is an injection seam too.
         componentProps['data-aci-block'] = block.id;
         componentProps['data-aci-component'] = block.component;
-        return _jsx(Component, { ...componentProps }, block.id);
+        // Index+id composite: a repeated fragment placement repeats its authored
+        // id, and sibling keys must stay unique for React reconciliation.
+        return _jsx(Component, { ...componentProps }, `${index}:${block.id}`);
     });
 }

package/dist/next/render.d.ts

@@ -1,5 +1,5 @@
 import type { ReactElement } from 'react';
 import type { KernelPageBlock } from '../content/types.js';
 import type { Registry } from '../registry.js';
-export declare function renderBlock(block: KernelPageBlock, registry: Registry, extraProps?: Record<string, unknown>): Promise<ReactElement>;
+export declare function renderBlock(block: KernelPageBlock, registry: Registry, key: string, extraProps?: Record<string, unknown>): Promise<ReactElement>;
 export declare function renderBlocks(blocks: readonly KernelPageBlock[], registry: Registry, extraProps?: Record<string, unknown>): Promise<ReactElement[]>;

package/dist/next/render.js

@@ -1,8 +1,8 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-export async function renderBlock(block, registry, extraProps) {
+export async function renderBlock(block, registry, key, extraProps) {
     const entry = registry.find((r) => r.id === block.component);
     if (!entry) {
-        return (_jsxs("div", { className: "mx-auto my-4 max-w-[var(--max-width-container)] rounded-card border-2 border-red-600 bg-red-50 px-5 py-4 font-mono text-sm leading-relaxed text-red-900", children: [_jsx("strong", { children: "Unknown block:" }), " ", _jsx("code", { children: block.component }), _jsx("br", {}), _jsxs("span", { className: "text-red-800 opacity-70", children: ["id: ", block.id] })] }, block.id));
+        return (_jsxs("div", { className: "mx-auto my-4 max-w-[var(--max-width-container)] rounded-card border-2 border-red-600 bg-red-50 px-5 py-4 font-mono text-sm leading-relaxed text-red-900", children: [_jsx("strong", { children: "Unknown block:" }), " ", _jsx("code", { children: block.component }), _jsx("br", {}), _jsxs("span", { className: "text-red-800 opacity-70", children: ["id: ", block.id] })] }, key));
     }
     const Component = entry.component;
     const hasBlockSlots = !!entry.contract.blockSlots;
@@ -17,8 +17,11 @@ export async function renderBlock(block, registry, extraProps) {
     if (hasBlockSlots) {
         componentProps.renderChildren = (blocks) => renderBlocks(blocks, registry, extraProps);
     }
-    return _jsx(Component, { ...componentProps }, block.id);
+    return _jsx(Component, { ...componentProps }, key);
 }
 export async function renderBlocks(blocks, registry, extraProps) {
-    return Promise.all(blocks.map((block) => renderBlock(block, registry, extraProps)));
+    // Sibling keys are index+id composites: one fragment placed twice repeats
+    // its authored block id, and React reconciliation keys must be unique per
+    // sibling (ADR 0051 covers analytics identity, not reconciliation).
+    return Promise.all(blocks.map((block, index) => renderBlock(block, registry, `${index}:${block.id}`, extraProps)));
 }

package/dist/next/server.js

@@ -44,8 +44,9 @@ export async function getFragment(name, config = {}) {
     const runtimeInput = await getPageRuntimeRenderInput();
     if (runtimeInput) {
         const fragments = runtimeInput.fragments || {};
-        if (name in fragments)
+        if (Object.hasOwn(fragments, name))
             return fragments[name];
+        throw new FragmentNotFoundError(name, new Error('fragment is not bound by the selected page'));
     }
     const provider = await resolveProviderWithFallback(config);
     return await provider.getFragment(name);

package/dist/testing/conformance/root-identity.js

@@ -38,7 +38,7 @@ export async function findRootIdentityFailures(registry, blocks, react, fileFor
     const probe = async (block, contentBacked) => {
         if (failures.has(block.component))
             return;
-        const element = await renderBlock(block, registry);
+        const element = await renderBlock(block, registry, `probe:${block.id}`);
         let html;
         try {
             html = await markupFor(element, react);

package/dist/types/block-ref.js

@@ -16,10 +16,10 @@ function attachMeta(schema, allowed, multiple) {
     return schema;
 }
 export function blockRefArray(contracts) {
-    return attachMeta(z.array(blockRefBase), contracts.map((c) => c.id), true);
+    return attachMeta(z.array(blockRefBase.extend({ component: z.enum(contracts.map((c) => c.id)) })), contracts.map((c) => c.id), true);
 }
 export function blockRef(contracts) {
-    return attachMeta(blockRefBase, contracts.map((c) => c.id), false);
+    return attachMeta(blockRefBase.extend({ component: z.enum(contracts.map((c) => c.id)) }), contracts.map((c) => c.id), false);
 }
 export function getBlockRefMeta(schema) {
     if (schema && typeof schema === 'object' && BLOCK_REF_KEY in schema) {

package/dist/types/config.d.ts

@@ -9,7 +9,6 @@ export interface Config {
     };
     componentRegistry: string;
     dataRegistry?: string;
-    layoutRegistry: string;
     routes: RouteConfig;
     dam?: DAMConfig;
     externalDependencies?: ExternalDependency[];

package/dist/types/index.d.ts

@@ -1,7 +1,6 @@
 export * from './config.js';
 export * from './component.js';
 export * from './data.js';
-export * from './layout.js';
 export * from './page.js';
 export * from './rich-text.js';
 export * from './image.js';

package/dist/types/index.js

@@ -1,7 +1,6 @@
 export * from './config.js';
 export * from './component.js';
 export * from './data.js';
-export * from './layout.js';
 export * from './page.js';
 export * from './rich-text.js';
 export * from './image.js';

package/dist/types/page.d.ts

@@ -32,5 +32,4 @@ export interface BlockNode {
 export interface FragmentRefNode {
     kind: 'fragment-ref';
     fragmentId: string;
-    inline: boolean;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gradial/aci",
-  "version": "0.1.52-rc.26",
+  "version": "0.1.52-rc.28",
   "repository": {
     "type": "git",
     "url": "https://github.com/gradial/bare-metal-go.git",
@@ -159,11 +159,11 @@
     "zod": "^4.0.0"
   },
   "optionalDependencies": {
-    "@gradial/aci-cli-darwin-arm64": "0.1.52-rc.26",
-    "@gradial/aci-cli-darwin-x64": "0.1.52-rc.26",
-    "@gradial/aci-cli-linux-arm64": "0.1.52-rc.26",
-    "@gradial/aci-cli-linux-x64": "0.1.52-rc.26",
-    "@gradial/aci-cli-win32-arm64": "0.1.52-rc.26",
-    "@gradial/aci-cli-win32-x64": "0.1.52-rc.26"
+    "@gradial/aci-cli-darwin-arm64": "0.1.52-rc.28",
+    "@gradial/aci-cli-darwin-x64": "0.1.52-rc.28",
+    "@gradial/aci-cli-linux-arm64": "0.1.52-rc.28",
+    "@gradial/aci-cli-linux-x64": "0.1.52-rc.28",
+    "@gradial/aci-cli-win32-arm64": "0.1.52-rc.28",
+    "@gradial/aci-cli-win32-x64": "0.1.52-rc.28"
   }
 }

package/src/cli/compile-registry.mjs

@@ -32,13 +32,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')
     : [];
@@ -68,9 +70,6 @@ async function compileRegistry(options) {
     });
   }
 
-  const seenLayouts = new Set();
-  const layoutEntries = layouts.map((layout, index) => validateLayout(layout, index, seenLayouts));
-
   const seenDataModels = new Set();
   const dataModelEntries = [];
   if (dataModels.length > 0) {
@@ -104,7 +103,6 @@ async function compileRegistry(options) {
     manifestVersion: '1',
     generatedAt: new Date().toISOString(),
     components: componentEntries,
-    layouts: layoutEntries,
     dataModels: dataModelEntries,
   };
   const registryPath = path.join(outDir, 'registry.json');
@@ -118,7 +116,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;
 }
@@ -390,27 +388,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') {
@@ -505,13 +482,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/src/types/block-ref.test.ts

@@ -4,7 +4,7 @@ import { z } from 'zod';
 
 import { compileSchema } from '../compiler/zod-to-jsonschema.js';
 import { defineComponentContract } from '../define-component.js';
-import { blockRefArray } from './block-ref.js';
+import { blockRef, blockRefArray } from './block-ref.js';
 
 const childContract = defineComponentContract({
   id: 'child',
@@ -43,3 +43,18 @@ test('compiled block-reference schema exposes the component discriminator', () =
   assert.equal(compiled.items?.required?.includes('$type'), true);
   assert.equal(compiled.items?.additionalProperties, false);
 });
+
+
+test('block-reference contracts enforce allowed child IDs at runtime and in compiled schemas', () => {
+  const other = defineComponentContract({ id: 'other', props: z.object({}) });
+  const allowed = { $type: 'component', id: 'child-1', component: 'child', props: { label: 'Hello' } };
+  const disallowed = { ...allowed, component: 'button' };
+  for (const multiple of [false, true]) {
+    const schema = multiple ? blockRefArray([childContract, other]) : blockRef([childContract, other]);
+    assert.equal(schema.safeParse(multiple ? [allowed] : allowed).success, true);
+    assert.equal(schema.safeParse(multiple ? [disallowed] : disallowed).success, false, 'a nested component outside the contract must be refused');
+    const compiled = compileSchema(schema) as any;
+    const block = multiple ? compiled.items : compiled;
+    assert.deepEqual(block.properties.component.enum, ['child', 'other'], 'published JSON Schema must enforce the same finite child set');
+  }
+});

package/src/types/block-ref.ts

@@ -50,7 +50,7 @@ export function blockRefArray<const T extends readonly ComponentContract[]>(
   contracts: T,
 ): z.ZodArray<z.ZodType<BlockRefUnion<T>>> {
   return attachMeta(
-    z.array(blockRefBase) as unknown as z.ZodArray<z.ZodType<BlockRefUnion<T>>>,
+    z.array(blockRefBase.extend({ component: z.enum(contracts.map((c) => c.id)) })) as unknown as z.ZodArray<z.ZodType<BlockRefUnion<T>>>,
     contracts.map((c) => c.id),
     true,
   );
@@ -60,7 +60,7 @@ export function blockRef<const T extends readonly ComponentContract[]>(
   contracts: T,
 ): z.ZodType<BlockRefUnion<T>> {
   return attachMeta(
-    blockRefBase as unknown as z.ZodType<BlockRefUnion<T>>,
+    blockRefBase.extend({ component: z.enum(contracts.map((c) => c.id)) }) as unknown as z.ZodType<BlockRefUnion<T>>,
     contracts.map((c) => c.id),
     false,
   );

package/src/types/config.ts

@@ -9,7 +9,6 @@ export interface Config {
   };
   componentRegistry: string;
   dataRegistry?: string;
-  layoutRegistry: string;
   routes: RouteConfig;
   dam?: DAMConfig;
   externalDependencies?: ExternalDependency[];

package/src/types/index.ts

@@ -1,7 +1,6 @@
 export * from './config.js';
 export * from './component.js';
 export * from './data.js';
-export * from './layout.js';
 export * from './page.js';
 export * from './rich-text.js';
 export * from './image.js';

package/src/types/page.ts

@@ -34,5 +34,4 @@ export interface BlockNode {
 export interface FragmentRefNode {
   kind: 'fragment-ref';
   fragmentId: string;
-  inline: boolean;
 }

package/templates/astro/template/.aci.yaml.tmpl

@@ -9,7 +9,6 @@ source:
   publicDir: "public"
 
 componentRegistry: ./src/cms/contracts/components/index.ts
-layoutRegistry: ./src/cms/contracts/layouts/index.ts
 
 routes:
   cmsManaged: "/[...slug]"

package/templates/common/.agents/skills/aci/SKILL.md

@@ -244,10 +244,10 @@ If a value doesn't survive the round-trip, check:
 |------|---------|
 | `.aci.yaml` | ACI config: contract paths, framework, routes, capabilities |
 | `src/cms/contracts/components/index.ts` | Component contract barrel |
-| `src/cms/contracts/layouts/index.ts` | Layout contract barrel |
 | `src/cms/registry.ts` | Component registry (`createRegistry` with `[contract, component]` tuples) |
 | `src/components/` | Runtime component implementations |
 | `src/design-system/` | Design tokens and global styles |
+| `.content/templates/` | Page composition contracts |
 | `.content/` | Local content for development |
 
 ## Deep Dive: Authoring