@gradial/aci 0.1.53-rc.2 → 0.1.53-rc.4

package/CHANGELOG.md

@@ -4,12 +4,59 @@
 
 ### Added
 
+- Public `aci schemas compile` and `aci error-pages prepare|emit` commands let
+  site build scripts compile code-owned artifacts without invoking SDK internals.
+
+- `AciRootProps` (the new name of `RootIdentityProps`, which stays as an
+  alias) and `aciRootAttrs(props)`, exported from `@gradial/aci`.
+- The `rootIdentity` check covers every file that calls `createRegistry(`,
+  renders a component no content places with props derived from its
+  contract's schema, and prints its coverage: components checked, and each
+  one not run with the reason.
 - Page `metadata.robots` accepts boolean `index` and `follow` directives.
   Next and Astro emit the corresponding HTML tag. Publish excludes pages with
   `index: false` from the release sitemap.
 
 ### Migration required
 
+- Error-artifact `prepare` no longer compiles authored content. Sites relying
+  on that side effect must run `content:compile` during local development or
+  explicit content validation. Production Next builds require contracts and
+  code only; authored error-page content is resolved during ACI preview/publish.
+
+- **Block root identity: render the root on every render** (ADR 0051) — each
+  registered component must put `aciRootAttrs(props)` (or its rest props) on
+  its own root element, and must render that root even when its content is
+  empty; the `rootIdentity` conformance check now fails a component that
+  renders nothing. Runbook: `.agents/skills/authoring/references/sdk-migrations.md`,
+  section "Root identity (0.1.52-rc.24)".
+- **Migration required: test loader** — the `rootIdentity` check in
+  `@gradial/aci/testing` imports your component registry, so your test
+  process must be able to load TypeScript, JSX, and your `tsconfig` path
+  aliases. Run your test suite with the `tsx` loader, as the starters do:
+
+  ```json
+  "test": "node --import tsx --test tests/**/*.test.ts"
+  ```
+
+  A test process without the loader (for example `node --test` or
+  `node --test --experimental-strip-types`) now fails `npm test` with:
+
+  ```text
+  rootIdentity: cannot load src/cms/registry.ts: this test process cannot resolve the path alias "@/cms".
+    Run tests with:  node --import tsx --test
+    See the @gradial/aci CHANGELOG, "Migration required: test loader".
+  ```
+
+  If you turned the check off with `checks: { rootIdentity: false }` because
+  it could not load CSS modules or path aliases, remove that option: the
+  check now loads stylesheets, images, fonts, `next/image`, `next/link`, and
+  `next/font` as inert stubs, and reads every registry file in the site.
+
+  There is no build gate. `next build` and `astro build` do not run the
+  check. The local signal is `npm test`, where the conformance check renders
+  every registered component in isolation. A component it cannot load or
+  render is reported as not run, never as a failure.
 - Existing Astro sites must install `@gradial/aci/astro/Head` and pass resolved
   metadata as one object through their route and layout. Next sites must upgrade
   the SDK and rebuild. See [page metadata migration](./migrations/page-metadata-head.md).
@@ -18,8 +65,38 @@
   before telling an author that `noindex` is present. No platform test currently
   enforces that check on older site builds.
 
+### Removed
+
+- `astroAuthoredBlocks` is no longer exported from `@gradial/aci/testing`:
+  the Astro `rootIdentity` check renders components instead of scanning
+  `dist/`. `findRootIdentityFailures` and `RootIdentityFailure` are no longer
+  exported either; `checkRootIdentity` and `formatRootIdentityFailures` stay.
+
 ### Changed
 
+- Next production builds and error-artifact preparation are content-independent
+  without `ACI_CODE_ARTIFACT_BUILD`. Local Next development still validates and
+  previews authored error seats; production authored error pages belong to
+  preview/publish. Sites should compile contracts in `prebuild`, validate content
+  explicitly, and remove build-phase switches from their scripts.
+
+- **`rootIdentity` reads every registry file again.** The `registry` option
+  introduced in 0.1.52-rc.33 is still accepted, but it is no longer required:
+  the check covers every file that calls `createRegistry(` (a main registry
+  and an error-page registry are both checked). Sites that added the option
+  for rc.33 need no change.
+- **Nested blocks carry their root identity in their props.** The renderers
+  now put `data-aci-block` and `data-aci-component` into the `props` of
+  every component block nested in a block's props, at any depth (a block
+  slot, or a list inside an item such as `tabs[].blocks`). A container that
+  renders child blocks from plain data with `<Component {...block.props} />`
+  now emits each child's identity on the child's root, so `rootIdentity`
+  passes for it without a site change. Containers that call
+  `renderChildren` are unchanged: the same values are applied once. A
+  container that rebuilds a child's props from selected fields (for example
+  `<Component text={block.props.text} />`) still drops the identity and is
+  still reported. The `props` of nested blocks now contain the two identity
+  keys at render time; the compiled content does not change.
 - Immutable code builds (`ACI_CODE_ARTIFACT_BUILD=1`) no longer read or compile
   authored error-page content. Native client error seats use the shipped
   default; publish resolves authored CDN error pages independently. Error

package/README.md

@@ -1,6 +1,6 @@
 # Agentic Content Infrastructure SDK
 
-`@gradial/aci` `0.1.53-rc.2` is a pre-1.0 public-surface reset for the ACI
+`@gradial/aci` `0.1.53-rc.4` 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.53-rc.2 zod@^4
+npm install @gradial/aci@0.1.53-rc.4 zod@^4
 ```
 
 ## Root Import
@@ -137,13 +137,13 @@ host bundles select and serve immutable release artifacts.
 The first RC scaffold path is Next:
 
 ```bash
-npx @gradial/aci@0.1.53-rc.2 init my-site --template next-starter
+npx @gradial/aci@0.1.53-rc.4 init my-site --template next-starter
 ```
 
 List available templates:
 
 ```bash
-npx @gradial/aci@0.1.53-rc.2 init --list
+npx @gradial/aci@0.1.53-rc.4 init --list
 ```
 
 ## Personalization: The One-Tag Install
@@ -223,3 +223,25 @@ From `packages/sdk`:
 pnpm run build
 pnpm run generate-starters
 ```
+
+## Public code-build commands
+
+Use the installed `aci` binary from npm scripts, not files beneath the package's
+`src`, `dist`, or `bin` directories:
+
+```json
+{
+  "scripts": {
+    "schemas:compile": "aci schemas compile",
+    "prebuild": "npm run schemas:compile",
+    "build": "aci error-pages prepare && next build && aci error-pages emit",
+    "content:compile": "npm run schemas:compile && aci content compile --content ./.content --out ./.aci/compiled"
+  }
+}
+```
+
+`schemas compile` reads the component/data registry paths from `.aci.yaml` and
+recompiles contracts without reading authored content. The error commands prepare
+code-owned analytics policy and emit the default hosting fallback (preserving a
+site-owned `public/500.html`). All three honor `--site-dir`; helper failures exit
+nonzero. Local development/content validation must explicitly compile content.

package/dist/astro/index.js

@@ -2,6 +2,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { contentWatchPlugin, damAssetPlugin, devRefreshPort, } from '../dev/content-watch.js';
 import { createDevRefreshBrowserScript } from '../dev/index.js';
+import { withAciRootProps, withNestedAciRootProps } from '../internal/aci-root.js';
 // ---------------------------------------------------------------------------
 // Static paths helper — for Astro SSG
 // ---------------------------------------------------------------------------
@@ -57,14 +58,10 @@ export function createRenderChildren(registry) {
         return blocks.map((block) => {
             const entry = registry.find((r) => r.id === block.component);
             const hasBlockSlots = !!entry?.contract.blockSlots;
-            const props = { ...block.props };
+            const props = withAciRootProps(withNestedAciRootProps(block.props), block);
             if (hasBlockSlots) {
                 props.renderChildren = renderChildren;
             }
-            // sdk I-19 (ADR 0051): root identity props are applied last so content
-            // props cannot overwrite them. The template spreads them onto the root.
-            props['data-aci-block'] = block.id;
-            props['data-aci-component'] = block.component;
             return { Component: entry?.component, props };
         });
     }

package/dist/cli/emit-error-pages.d.mts

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-export function prepareCodeArtifact(root: string | undefined, content: any): Promise<string>;
+export function prepare(root: string | undefined, content: any): Promise<string>;
 /**
  * D-15 policy resolution for the 500.html instrumentation tag (page_type
  * "error"; self-contained inline delivery — this copy is a real static
@@ -38,3 +38,4 @@ export function writeInstrumentationArtifact(root: string | undefined, content:
  * loudly instead.
  */
 export function stampInstrumentation(html: any, instrumentationTag: any): any;
+export function emit(root: string | undefined, content: any): Promise<void>;

package/dist/cli/emit-error-pages.mjs

@@ -1,80 +1,19 @@
 #!/usr/bin/env node
-// Authorable error pages — build integration (spec:
-// specs/features/authorable-error-pages, T3/T11; REQ-10/REQ-11/REQ-14, D-9,
-// D-16).
-//
-// ACI_CODE_ARTIFACT_BUILD=1 makes both phases content-independent: prepare
-// serializes only the code-owned policy at its existing .aci/compiled path.
-// Emit uses the shipped default without resolving authored error-page bindings.
-//
-// Two phases. The Next template wires both around `next build`; the Astro
-// template runs only `prepare` before `astro build` (its 404/500 seats
-// render through the framework, but the D-16 instrumentation artifact must
-// still reach the compiled content root for the AWS lane):
-//
-//   prepare  (before `next build`)
-//     Ensures compiled content exists at .aci/compiled so withAci() can
-//     serialize the bound catchAll page for the client-only error seat
-//     (D-9). Compiles ./.content via the platform CLI when needed; when
-//     neither compiled content nor authored content exists, it warns and
-//     leaves the shipped default in play (REQ-4, warn posture). Then writes
-//     error-pages/instrumentation.json (both kinds' serialized tags) into
-//     the compiled content root so the tag crosses the JS→Go boundary as
-//     data: builders retain the instrumentation file at its existing capsule
-//     path, and the Go publish materializer stamps the kind-matching tag into the CDN
-//     error artifacts (D-16). An unserializable tenant push fails the build
-//     loudly here (delta FIND-006).
-//
-//   emit     (after `next build`)
-//     Materializes `public/500.html` from the page bound to
-//     site.json#errorPages.catchAll by booting the standalone build,
-//     fetching the bound route, and post-processing the document. Boot-and-
-//     fetch beats re-rendering the page here because the standalone server
-//     is the only renderer that produces the document exactly as served
-//     (layout shell, resolved fragments, RSC-injected head and styles).
-//     Post-processing:
-//       - all script tags and preload/prefetch links stripped — this
-//         removes the collect and assignment tags (REQ-11) along with the
-//         framework runtime, which is useless in a statically served copy;
-//       - same-origin stylesheets inlined from .next/static (REQ-14 spirit:
-//         inline styles; note @font-face/image URLs inside the CSS keep
-//         their same-origin paths — this copy is served by the Vercel
-//         platform on the deployment that owns those assets);
-//       - one self-contained inline script appended pushing the D-14
-//         `page_view` (page_type "error") — a static document executes
-//         inline scripts, unlike the flight-rendered not-found seat. The
-//         push body is site policy (D-15): the tenant-owned
-//         src/aci/error-page-instrumentation.mjs when present, the SDK
-//         default otherwise;
-//       - hard size budget: ≤150 KB raw (REQ-14) — exceeding it fails the
-//         build; trimming the design system or falling back to system
-//         fonts is the sanctioned escape hatch.
-//     Skips when the site already provides its own public/500.html (a file
-//     without the generation marker); regenerates its own prior output.
-//     Absent bindings emit the shipped branded-neutral default (REQ-4).
-//     Vercel picks static per-status files out of the build output
-//     ("file presence = configuration"); on the current Pro plan the file
-//     serves app-level 500s only and lights up for platform 5xx on a plan
-//     upgrade (REQ-10, P-1).
-//
-// Usage: node ./node_modules/@gradial/aci/src/cli/emit-error-pages.mjs <prepare|emit>
-import { execFileSync, spawn } from 'node:child_process';
+// Code-build error artifacts. prepare transports code-owned analytics policy;
+// emit writes a content-independent static 500. Authored error-page bindings
+// and rendering belong to content preview/publish, never the framework build.
+// Usage: emit-error-pages.mjs <prepare|emit>
 import fs from 'node:fs';
-import net from 'node:net';
 import path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 const MARKER = '<!-- aci:error-pages generated -->';
 const SIZE_BUDGET = 150 * 1024;
-const BOOT_DEADLINE_MS = 60_000;
 const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
 const siteRoot = process.cwd();
 const contentRoot = path.resolve(siteRoot, process.env.ACI_CONTENT_ROOT || '.aci/compiled');
 function log(message) {
     console.log(`[aci error-pages] ${message}`);
 }
-function warn(message) {
-    console.warn(`\n[aci error-pages] WARNING: ${message}\n`);
-}
 function fail(message) {
     console.error(`\n[aci error-pages] ERROR: ${message}\n`);
     process.exit(1);
@@ -82,175 +21,11 @@ function fail(message) {
 async function sdkContent() {
     return await import(pathToFileURL(path.join(packageRoot, 'dist', 'content', 'index.js')).href);
 }
-function hasCompiledContent() {
-    return fs.existsSync(path.join(contentRoot, 'manifest.json'));
-}
-// ---------------------------------------------------------------------------
-// prepare
-// ---------------------------------------------------------------------------
-// Retain the deployed transport path for SDK-first upgrades. This file is
-// executable policy, not a compiled page snapshot; do not compile content here.
-export async function prepareCodeArtifact(root = siteRoot, content) {
+// Keep the existing capsule transport path for SDK-first upgrades. This file
+// is executable policy, not a compiled content snapshot.
+export async function prepare(root = siteRoot, content) {
     return writeInstrumentationArtifact(root, content, path.join(root, '.aci', 'compiled'));
 }
-async function prepare() {
-    if (process.env.ACI_CODE_ARTIFACT_BUILD === '1') {
-        // Code artifacts carry executable policy only. The selected content and
-        // its error-page bindings belong to preview/publish, never this build.
-        await prepareCodeArtifact();
-        return;
-    }
-    if (hasCompiledContent()) {
-        log(`compiled content present at ${contentRoot}`);
-    }
-    else {
-        const authored = path.join(siteRoot, '.content');
-        if (!fs.existsSync(authored)) {
-            warn(`neither compiled content (${contentRoot}) nor authored content (./.content) exists; `
-                + 'the error seat and 500.html will serve the shipped default page (REQ-4)');
-        }
-        else {
-            log('compiling ./.content for the error-page build steps');
-            execFileSync('node', [path.join(packageRoot, 'bin', 'aci.js'), 'content', 'compile', '--content', authored, '--out', contentRoot], { cwd: siteRoot, stdio: 'inherit' });
-        }
-    }
-    // D-16: the instrumentation artifact rides the compiled content root into
-    // the AWS-lane code capsule (source/.aci/compiled/**). Written even when
-    // content is absent — the tenant policy module is independent of authored
-    // content, and an artifact the Go materializer never receives silently
-    // degrades to the default tags (the exact gap D-16 closes).
-    try {
-        await writeInstrumentationArtifact();
-    }
-    catch (error) {
-        fail(error.message);
-    }
-}
-// ---------------------------------------------------------------------------
-// emit
-// ---------------------------------------------------------------------------
-async function resolveCatchAllRoute() {
-    const { resolveErrorPageBindings, defaultErrorPageHtml, errorPagePostureFromEnv } = await sdkContent();
-    // D-5 posture: the one shared config surface (ACI_ERROR_PAGES_POSTURE);
-    // unknown values fail closed here just like the Go stack.
-    let posture;
-    try {
-        posture = errorPagePostureFromEnv();
-    }
-    catch (error) {
-        fail(error.message);
-    }
-    if (!hasCompiledContent()) {
-        if (posture === 'enforce') {
-            fail(`no compiled content at ${contentRoot}; the enforce posture fails closed (D-5)`);
-        }
-        warn(`no compiled content at ${contentRoot}; emitting the shipped default 500.html (REQ-4)`);
-        return { route: null, defaultHtml: defaultErrorPageHtml() };
-    }
-    const { FileContentProvider } = await import(pathToFileURL(path.join(packageRoot, 'dist', 'providers', 'file.js')).href);
-    const provider = new FileContentProvider(contentRoot);
-    const siteConfig = await provider.getSiteConfig();
-    const resolution = await resolveErrorPageBindings(siteConfig, { source: provider, posture });
-    if (resolution.errors.length > 0) {
-        fail(`errorPages bindings are invalid (REQ-5, fail closed):\n- ${resolution.errors.join('\n- ')}`);
-    }
-    for (const warning of resolution.warnings)
-        warn(warning);
-    if (resolution.defaulted || !resolution.bindings) {
-        return { route: null, defaultHtml: defaultErrorPageHtml() };
-    }
-    return { route: resolution.bindings.catchAll, defaultHtml: defaultErrorPageHtml() };
-}
-async function freePort() {
-    return new Promise((resolve, reject) => {
-        const server = net.createServer();
-        server.unref();
-        server.on('error', reject);
-        server.listen(0, '127.0.0.1', () => {
-            const { port } = server.address();
-            server.close(() => resolve(port));
-        });
-    });
-}
-async function fetchRenderedRoute(route) {
-    const serverPath = path.join(siteRoot, '.next', 'standalone', 'server.js');
-    if (!fs.existsSync(serverPath)) {
-        fail(`${serverPath} missing — the emit phase must run after \`next build\` (withAci uses standalone output)`);
-    }
-    const port = await freePort();
-    const logChunks = [];
-    const child = spawn('node', [serverPath], {
-        cwd: siteRoot,
-        detached: true,
-        stdio: ['ignore', 'pipe', 'pipe'],
-        env: {
-            ...process.env,
-            NODE_ENV: 'production',
-            PORT: String(port),
-            HOSTNAME: '127.0.0.1',
-            ACI_CONTENT_PROVIDER: 'file',
-            ACI_CONTENT_ROOT: contentRoot,
-        },
-    });
-    child.stdout.on('data', (c) => logChunks.push(String(c)));
-    child.stderr.on('data', (c) => logChunks.push(String(c)));
-    const exited = new Promise((resolve) => {
-        child.on('exit', resolve);
-        child.on('error', (error) => {
-            logChunks.push(`spawn failed: ${error.message}\n`);
-            resolve(null);
-        });
-    });
-    try {
-        const url = `http://127.0.0.1:${port}${route}`;
-        const start = Date.now();
-        let last = 'no attempt made';
-        while (Date.now() - start < BOOT_DEADLINE_MS) {
-            try {
-                const response = await fetch(url, { redirect: 'follow' });
-                if (response.status === 200)
-                    return await response.text();
-                last = `status ${response.status}`;
-            }
-            catch (error) {
-                last = error.message;
-            }
-            await new Promise((r) => setTimeout(r, 500));
-        }
-        fail(`GET ${url} did not render within ${BOOT_DEADLINE_MS}ms (last: ${last})\n--- server output ---\n${logChunks.join('').slice(-4000)}`);
-        return '';
-    }
-    finally {
-        const killGroup = (signal) => {
-            if (!child.pid)
-                return;
-            try {
-                process.kill(-child.pid, signal);
-            }
-            catch { /* gone */ }
-        };
-        killGroup('SIGTERM');
-        const killTimer = setTimeout(() => killGroup('SIGKILL'), 10_000);
-        await exited;
-        clearTimeout(killTimer);
-        killGroup('SIGKILL');
-    }
-}
-function inlineStylesheets(html) {
-    return html.replace(/<link\b[^>]*rel="stylesheet"[^>]*>/gi, (tag) => {
-        const href = tag.match(/href="([^"]+)"/i)?.[1];
-        if (!href || !href.startsWith('/_next/')) {
-            warn(`dropping non-inlinable stylesheet ${href ?? '<unknown>'} from 500.html (self-containment, REQ-14)`);
-            return '';
-        }
-        const cssPath = path.join(siteRoot, '.next', href.replace(/^\/_next\//, ''));
-        if (!fs.existsSync(cssPath)) {
-            warn(`stylesheet ${href} not found in .next output; dropping it from 500.html`);
-            return '';
-        }
-        return `<style>${fs.readFileSync(cssPath, 'utf8')}</style>`;
-    });
-}
 // Relative convention path of the tenant-owned instrumentation policy
 // module (D-15, code-organization R-14).
 const INSTRUMENTATION_MODULE = path.join('src', 'aci', 'error-page-instrumentation.mjs');
@@ -351,48 +126,16 @@ export function stampInstrumentation(html, instrumentationTag) {
     }
     return stamped;
 }
-function postProcess(html, instrumentationTag) {
-    let out = html;
-    // Strip every script tag: framework runtime chunks are dead weight in a
-    // statically served copy, and this removes the collect script and the
-    // data-aci-assignments tag (REQ-11) in one sweep.
-    out = out.replace(/<script\b[\s\S]*?<\/script>/gi, '');
-    out = out.replace(/<link\b[^>]*rel="(?:preload|modulepreload|prefetch)"[^>]*>/gi, '');
-    out = inlineStylesheets(out);
-    return stampInstrumentation(out, instrumentationTag);
-}
-async function emit() {
-    const publicDir = path.join(siteRoot, 'public');
+export async function emit(root = siteRoot, content) {
+    const publicDir = path.join(root, 'public');
     const target = path.join(publicDir, '500.html');
     if (fs.existsSync(target) && !fs.readFileSync(target, 'utf8').includes(MARKER)) {
         log('public/500.html already provided by the site; leaving it untouched (skip-if-present)');
         return;
     }
-    const { route, defaultHtml } = process.env.ACI_CODE_ARTIFACT_BUILD === '1'
-        ? { route: null, defaultHtml: (await sdkContent()).defaultErrorPageHtml() }
-        : await resolveCatchAllRoute();
-    let instrumentationTag;
-    try {
-        instrumentationTag = await resolveInstrumentationTag();
-    }
-    catch (error) {
-        fail(error.message);
-    }
-    let html;
-    try {
-        if (!route) {
-            // The shipped default is already self-contained; it gets the same
-            // instrumentation-plus-marker append used for rendered pages.
-            html = stampInstrumentation(defaultHtml, instrumentationTag);
-        }
-        else {
-            log(`rendering bound catchAll page ${route} for public/500.html`);
-            html = postProcess(await fetchRenderedRoute(route), instrumentationTag);
-        }
-    }
-    catch (error) {
-        fail(error.message);
-    }
+    const sdk = content ?? (await sdkContent());
+    const instrumentationTag = await resolveInstrumentationTag(root, sdk);
+    const html = stampInstrumentation(sdk.defaultErrorPageHtml(), instrumentationTag);
     const size = Buffer.byteLength(html);
     if (size > SIZE_BUDGET) {
         fail(`public/500.html is ${size} bytes, over the ${SIZE_BUDGET}-byte budget (REQ-14). `
@@ -400,7 +143,7 @@ async function emit() {
     }
     fs.mkdirSync(publicDir, { recursive: true });
     fs.writeFileSync(target, html);
-    log(`wrote public/500.html (${size} bytes${route ? `, from ${route}` : ', shipped default'})`);
+    log(`wrote public/500.html (${size} bytes, shipped default)`);
 }
 // Run only when executed as a CLI — the module is also imported by unit
 // tests for stampInstrumentation.

package/dist/content/component-block.d.ts

@@ -0,0 +1,17 @@
+export interface ComponentBlock {
+    id: string;
+    component: string;
+}
+/**
+ * The content compiler's block predicate (`compiler.IsComponentBlock`): an
+ * explicit `$type: "component"` marker, or a non-empty string `component`
+ * with an object `props`. The shared Go/TS vector
+ * `internal/domain/content/compiler/testdata/component-block-predicate.v1.json`
+ * pins both sides.
+ */
+export declare function isComponentBlock(node: Record<string, unknown>): boolean;
+/**
+ * Every component block in a compiled page payload that carries an id,
+ * parents before children, nested slots included.
+ */
+export declare function collectComponentBlocks(payload: unknown): ComponentBlock[];

package/dist/content/component-block.js

@@ -0,0 +1,40 @@
+// The content compiler's component-block rule, shared by rendering (root
+// identity, slot resolution) and the rootIdentity conformance check.
+/**
+ * The content compiler's block predicate (`compiler.IsComponentBlock`): an
+ * explicit `$type: "component"` marker, or a non-empty string `component`
+ * with an object `props`. The shared Go/TS vector
+ * `internal/domain/content/compiler/testdata/component-block-predicate.v1.json`
+ * pins both sides.
+ */
+export function isComponentBlock(node) {
+    if (node.$type === 'component')
+        return true;
+    const props = node.props;
+    return typeof node.component === 'string' && node.component !== ''
+        && typeof props === 'object' && props !== null && !Array.isArray(props);
+}
+/**
+ * Every component block in a compiled page payload that carries an id,
+ * parents before children, nested slots included.
+ */
+export function collectComponentBlocks(payload) {
+    const out = [];
+    const walk = (node) => {
+        if (Array.isArray(node)) {
+            for (const item of node)
+                walk(item);
+            return;
+        }
+        if (typeof node !== 'object' || node === null)
+            return;
+        const record = node;
+        if (isComponentBlock(record) && typeof record.id === 'string' && record.id !== '') {
+            out.push({ id: record.id, component: typeof record.component === 'string' ? record.component : '' });
+        }
+        for (const value of Object.values(record))
+            walk(value);
+    };
+    walk(payload);
+    return out;
+}

package/dist/content/resolve-slots.js

@@ -1,3 +1,4 @@
+import { isComponentBlock } from './component-block.js';
 /**
  * Shared Go/TS limit contract (sdk I-21). These values are pinned against
  * internal/domain/content/compiler/testdata/limit-conformance.v1.json by
@@ -105,10 +106,7 @@ function* walkValue(value, ancestry, state) {
         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) {
+    if (isComponentBlock(node) && ++state.blocks > MAX_EXPANDED_BLOCKS) {
         throw new FragmentResolutionError(`ACI rendered page exceeds ${MAX_EXPANDED_BLOCKS} component blocks`);
     }
     const result = {};

package/dist/index.d.ts

@@ -3,7 +3,8 @@ export { createRegistry, registryLookup } from './registry.js';
 export type { Registry, RegistryEntry, AnyComponent } from './registry.js';
 export { blockRef, blockRefArray } from './types/block-ref.js';
 export type { BlockRef, BlockRefEntry, BlockRefMeta, BlockRefUnion } from './types/block-ref.js';
-export type { ComponentContract, ComponentContractID, ComponentContractValidator, ComponentRegistry, ComponentValidationContext, ComponentValidationIssue, InferComponentProps, RootIdentityProps, } from './types/component.js';
+export type { ComponentContract, ComponentContractID, ComponentContractValidator, ComponentRegistry, ComponentValidationContext, ComponentValidationIssue, InferComponentProps, AciRootProps, RootIdentityProps, } from './types/component.js';
+export { aciRootAttrs } from './types/component.js';
 export { ImageSchema, imageAttrs, primaryImageSource, type Image, type ImageSource, type ImageAttrs, type ImageSlotContract, type SlotOutput, } from './types/image.js';
 export { LinkSchema, type Link, type LinkTarget, type LinkResolverContext, resolveLink, resolveHref, assertSafeHref, normalizeLinkRel, } from './types/link.js';
 export { HeadingSchema, InlineContentSchema, RichTextValueSchema, type Heading, type InlineContent, type RichTextValue, } from './types/rich-text.js';

package/dist/index.js

@@ -1,6 +1,7 @@
 export { defineComponentContract } from './define-component.js';
 export { createRegistry, registryLookup } from './registry.js';
 export { blockRef, blockRefArray } from './types/block-ref.js';
+export { aciRootAttrs } from './types/component.js';
 export { ImageSchema, imageAttrs, primaryImageSource, } from './types/image.js';
 export { LinkSchema, resolveLink, resolveHref, assertSafeHref, normalizeLinkRel, } from './types/link.js';
 export { HeadingSchema, InlineContentSchema, RichTextValueSchema, } from './types/rich-text.js';

package/dist/internal/aci-root.d.ts

@@ -0,0 +1 @@
+export {};