@gradial/aci 0.1.52-rc.21 → 0.1.52-rc.24

package/dist/mintlify/validate.js

@@ -0,0 +1,252 @@
+import { validateBlock, validateSnippetReferences } from './blocks.js';
+import { cleanDocumentPath, cleanFilePath, isExternalReference, isMintlifyJSONValue, isObject, nonEmptyString, } from './json.js';
+const CONFIG_FRAGMENT_SCHEMA_VERSION = 1;
+const API_SPEC_SCHEMA_VERSION = 1;
+export function validateSource(site, documents, snippets, apiSpecs) {
+    const paths = new Set();
+    for (const document of documents) {
+        if (paths.has(document.path))
+            throw new Error(`ACI Mintlify document path is duplicated: ${document.path}`);
+        paths.add(document.path);
+    }
+    const navigated = new Set();
+    const navigation = isObject(site) ? site.navigation : undefined;
+    validateNavigationPartitions(navigation);
+    for (const page of navigationPages(navigation)) {
+        // Links are valid Mintlify navigation items but are not ACI documents.
+        if (isExternalReference(page))
+            continue;
+        const normalized = cleanDocumentPath(page);
+        if (!normalized || normalized !== page)
+            throw new Error(`ACI Mintlify navigation page is invalid: ${page}`);
+        if (!paths.has(page))
+            throw new Error(`ACI Mintlify navigation references missing document: ${page}`);
+        if (navigated.has(page))
+            throw new Error(`ACI Mintlify navigation references document more than once: ${page}`);
+        navigated.add(page);
+    }
+    validateRedirects(isObject(site) ? site.redirects : undefined, paths);
+    validateSnippetReferences(documents, snippets);
+    validateAPISpecReferences(site, apiSpecs);
+}
+export function validateSite(value, label) {
+    if (!isObject(value) || !isMintlifyJSONValue(value)) {
+        throw new Error(`ACI Mintlify site is invalid: ${label}`);
+    }
+    if ('$schema' in value && value.$schema !== 'https://mintlify.com/docs.json') {
+        throw new Error(`ACI Mintlify site has an unsupported docs schema: ${label}`);
+    }
+    return value;
+}
+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)) {
+        throw new Error(`ACI Mintlify document is invalid: ${label}`);
+    }
+    const documentPath = cleanDocumentPath(sourcePath);
+    if (!documentPath || documentPath !== sourcePath)
+        throw new Error(`ACI Mintlify document path is invalid: ${sourcePath}`);
+    const ids = new Set();
+    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,
+        metadata: { title: metadata.title,
+            ...(nonEmptyString(metadata.description) ? { description: metadata.description } : {}),
+            mintlify: {
+                ...(nonEmptyString(renderer.sidebarTitle) ? { sidebarTitle: renderer.sidebarTitle } : {}),
+                ...(nonEmptyString(renderer.icon) ? { icon: renderer.icon } : {}),
+                ...(validFrontmatter(renderer.frontmatter) ? { frontmatter: renderer.frontmatter } : {}),
+            },
+        }, regions: { main: blocks },
+    };
+}
+export function validateSnippet(value, label, sourcePath) {
+    if (!isObject(value) || value.$type !== 'fragment' || !nonEmptyString(value.id) || !nonEmptyString(sourcePath) || !isObject(value.block)) {
+        throw new Error(`ACI Mintlify snippet is invalid: ${label}`);
+    }
+    const snippetPath = cleanFilePath(sourcePath, '.mdx');
+    if (!snippetPath || snippetPath !== sourcePath)
+        throw new Error(`ACI Mintlify snippet path is invalid: ${sourcePath}`);
+    const ids = new Set();
+    return {
+        $type: 'fragment', id: value.id,
+        path: snippetPath, block: validateBlock(value.block, `${label}.block`, ids),
+    };
+}
+export function validateConfigFragment(value, label) {
+    if (!isObject(value) || value.$type !== 'mintlify.config-fragment' || value.schemaVersion !== CONFIG_FRAGMENT_SCHEMA_VERSION || !nonEmptyString(value.path) || !isMintlifyJSONValue(value.value)) {
+        throw new Error(`ACI Mintlify config fragment is invalid: ${label}`);
+    }
+    const fragmentPath = cleanFilePath(value.path, '.json');
+    if (!fragmentPath || fragmentPath !== value.path || fragmentPath === 'docs.json')
+        throw new Error(`ACI Mintlify config fragment path is invalid: ${value.path}`);
+    return { $type: 'mintlify.config-fragment', schemaVersion: CONFIG_FRAGMENT_SCHEMA_VERSION, path: fragmentPath, value: value.value };
+}
+export function validateAPISpec(value, label) {
+    if (!isObject(value) || value.$type !== 'mintlify.api-spec' || value.schemaVersion !== API_SPEC_SCHEMA_VERSION || !nonEmptyString(value.path) || !['openapi', 'asyncapi', 'graphql'].includes(String(value.format)) || !nonEmptyString(value.source)) {
+        throw new Error(`ACI Mintlify API specification is invalid: ${label}`);
+    }
+    const sourcePath = value.path;
+    const extensions = value.format === 'graphql' ? ['.graphql', '.gql', '.json'] : ['.json', '.yaml', '.yml'];
+    const specPath = extensions.map((extension) => cleanFilePath(sourcePath, extension)).find(Boolean) ?? '';
+    if (!specPath || specPath !== sourcePath)
+        throw new Error(`ACI Mintlify API specification path is invalid: ${sourcePath}`);
+    return {
+        $type: 'mintlify.api-spec',
+        schemaVersion: API_SPEC_SCHEMA_VERSION,
+        path: specPath,
+        format: value.format,
+        source: value.source,
+    };
+}
+function validFrontmatter(value) {
+    if (value === undefined)
+        return false;
+    if (!isObject(value))
+        throw new Error('ACI Mintlify document frontmatter is invalid');
+    for (const [key, entry] of Object.entries(value)) {
+        if (!/^[A-Za-z][A-Za-z0-9_-]*$/.test(key) || !isMintlifyJSONValue(entry)) {
+            throw new Error('ACI Mintlify document frontmatter is invalid');
+        }
+        if (['title', 'description', 'sidebarTitle', 'icon'].includes(key))
+            throw new Error(`ACI Mintlify document frontmatter key is reserved: ${key}`);
+    }
+    return true;
+}
+function validateRedirects(value, documentPaths) {
+    if (value === undefined)
+        return;
+    if (!Array.isArray(value))
+        throw new Error('ACI Mintlify redirects are invalid');
+    const redirects = new Map();
+    const routes = new Set([...documentPaths].map((documentPath) => `/${documentPath}`));
+    for (const entry of value) {
+        if (!isObject(entry) || !nonEmptyString(entry.source) || !nonEmptyString(entry.destination) || (entry.permanent !== undefined && typeof entry.permanent !== 'boolean')) {
+            throw new Error('ACI Mintlify redirect is invalid');
+        }
+        if (!entry.source.startsWith('/') || entry.source.includes('?') || entry.source.includes('#')) {
+            throw new Error(`ACI Mintlify redirect source is invalid: ${entry.source}`);
+        }
+        if (!entry.destination.startsWith('/') && !isExternalReference(entry.destination)) {
+            throw new Error(`ACI Mintlify redirect destination is invalid: ${entry.destination}`);
+        }
+        if (redirects.has(entry.source))
+            throw new Error(`ACI Mintlify redirect source is duplicated: ${entry.source}`);
+        if (!entry.source.includes('*') && !entry.source.includes(':') && routes.has(trimRouteSlash(entry.source))) {
+            throw new Error(`ACI Mintlify redirect source collides with a document: ${entry.source}`);
+        }
+        redirects.set(entry.source, entry.destination);
+    }
+    for (const [source, destination] of redirects) {
+        if (isExternalReference(destination) || destination.includes('*') || destination.includes(':'))
+            continue;
+        const destinationPath = trimRouteSlash(destination.split(/[?#]/, 1)[0]);
+        if (!routes.has(destinationPath) && !redirects.has(destinationPath)) {
+            throw new Error(`ACI Mintlify redirect destination is missing: ${destination}`);
+        }
+        const seen = new Set([source]);
+        let next = destinationPath;
+        while (redirects.has(next)) {
+            if (seen.has(next))
+                throw new Error(`ACI Mintlify redirect cycle includes: ${next}`);
+            seen.add(next);
+            const target = redirects.get(next);
+            if (isExternalReference(target) || target.includes('*') || target.includes(':'))
+                break;
+            next = trimRouteSlash(target.split(/[?#]/, 1)[0]);
+        }
+    }
+}
+function trimRouteSlash(value) {
+    return value.length > 1 ? value.replace(/\/+$/, '') : value;
+}
+function validateAPISpecReferences(site, specs) {
+    const byPath = new Map();
+    for (const spec of specs) {
+        if (byPath.has(spec.path))
+            throw new Error(`ACI Mintlify API specification path is duplicated: ${spec.path}`);
+        byPath.set(spec.path, spec);
+    }
+    const visit = (value) => {
+        if (Array.isArray(value)) {
+            for (const child of value)
+                visit(child);
+            return;
+        }
+        if (!isObject(value))
+            return;
+        for (const [key, child] of Object.entries(value)) {
+            if (['openapi', 'asyncapi', 'graphql'].includes(key)) {
+                const references = typeof child === 'string' ? [child] : Array.isArray(child) ? child.filter((entry) => typeof entry === 'string') : [];
+                for (const reference of references) {
+                    if (isExternalReference(reference))
+                        continue;
+                    const spec = byPath.get(reference);
+                    if (!spec || spec.format !== key)
+                        throw new Error(`ACI Mintlify API specification reference is missing or has the wrong format: ${reference}`);
+                }
+            }
+            visit(child);
+        }
+    };
+    visit(site);
+}
+function navigationPages(value) {
+    if (!isObject(value))
+        return [];
+    const pages = [];
+    visitNavigation(value, pages);
+    return pages;
+}
+function visitNavigation(value, pages) {
+    if (Array.isArray(value)) {
+        for (const item of value)
+            visitNavigation(item, pages);
+        return;
+    }
+    if (!isObject(value))
+        return;
+    for (const [key, child] of Object.entries(value)) {
+        if (key === 'pages' && Array.isArray(child)) {
+            for (const item of child) {
+                if (typeof item === 'string')
+                    pages.push(item);
+                else
+                    visitNavigation(item, pages);
+            }
+            continue;
+        }
+        visitNavigation(child, pages);
+    }
+}
+function validateNavigationPartitions(value) {
+    if (Array.isArray(value)) {
+        for (const child of value)
+            validateNavigationPartitions(child);
+        return;
+    }
+    if (!isObject(value))
+        return;
+    for (const [key, child] of Object.entries(value)) {
+        if ((key === 'languages' || key === 'versions') && Array.isArray(child)) {
+            const identityKey = key === 'languages' ? 'language' : 'version';
+            const identities = new Set();
+            let defaults = 0;
+            for (const entry of child) {
+                if (!isObject(entry) || !nonEmptyString(entry[identityKey]))
+                    throw new Error(`ACI Mintlify ${key} navigation is invalid`);
+                const identity = entry[identityKey];
+                if (identities.has(identity))
+                    throw new Error(`ACI Mintlify ${key} navigation is duplicated: ${identity}`);
+                identities.add(identity);
+                if (entry.default === true)
+                    defaults += 1;
+            }
+            if (defaults > 1)
+                throw new Error(`ACI Mintlify navigation has multiple default ${key}`);
+        }
+        validateNavigationPartitions(child);
+    }
+}

package/dist/next/assignments-navigation.d.ts

@@ -0,0 +1,4 @@
+/** Signals from the committed page tree, including a page with no assignments. */
+export declare function AssignmentsNavigation({ json }: {
+    json: string;
+}): null;

package/dist/next/assignments-navigation.js

@@ -0,0 +1,18 @@
+'use client';
+import { useLayoutEffect } from 'react';
+/** Signals from the committed page tree, including a page with no assignments. */
+export function AssignmentsNavigation({ json }) {
+    // Deliberately runs on each page commit, including unchanged assignment props
+    // on a query navigation. The collector deduplicates hydration/StrictMode and
+    // same-URL/hash commits; discarded concurrent renders never run this effect.
+    useLayoutEffect(() => {
+        const win = window;
+        if (typeof win.aci !== 'function') {
+            const queue = (...args) => { (queue.q ??= []).push(args); };
+            win.aci = queue;
+        }
+        const assignments = json ? JSON.parse(json).experiments : [];
+        win.aci('navigation-complete', { url: win.location.href, assignments });
+    });
+    return null;
+}

package/dist/next/assignments-script.d.ts

@@ -7,8 +7,9 @@ export interface AssignmentsScriptProps {
  * (`<script type="application/json" data-aci-assignments>` with a
  * {"v":1,"experiments":[…]} body, personalization-reporting design/04) when
  * the page payload carries a build-time `experiments` block, and nothing
- * otherwise. createPage appends it to the page tree exactly once per page;
+ * otherwise. Its client commit hook also signals empty pages so SPA
+ * attribution clears when leaving an experiment. createPage appends it to the page tree exactly once per page;
  * sites composing their own pages can render it directly. The JSON body is
  * HTML-safe (assignmentsScriptJSON \u-escapes angle brackets).
  */
-export declare function AssignmentsScript({ page }: AssignmentsScriptProps): import("react").JSX.Element | null;
+export declare function AssignmentsScript({ page }: AssignmentsScriptProps): import("react").JSX.Element;

package/dist/next/assignments-script.js

@@ -1,17 +1,17 @@
-import { jsx as _jsx } from "react/jsx-runtime";
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { AssignmentsNavigation } from './assignments-navigation.js';
 import { assignmentsScriptJSON, } from '../content/personalization.js';
 /**
  * AssignmentsScript renders the page-level experiment assignment tag
  * (`<script type="application/json" data-aci-assignments>` with a
  * {"v":1,"experiments":[…]} body, personalization-reporting design/04) when
  * the page payload carries a build-time `experiments` block, and nothing
- * otherwise. createPage appends it to the page tree exactly once per page;
+ * otherwise. Its client commit hook also signals empty pages so SPA
+ * attribution clears when leaving an experiment. createPage appends it to the page tree exactly once per page;
  * sites composing their own pages can render it directly. The JSON body is
  * HTML-safe (assignmentsScriptJSON \u-escapes angle brackets).
  */
 export function AssignmentsScript({ page }) {
     const json = assignmentsScriptJSON(page);
-    if (!json)
-        return null;
-    return (_jsx("script", { type: "application/json", "data-aci-assignments": "", dangerouslySetInnerHTML: { __html: json } }));
+    return (_jsxs(_Fragment, { children: [json ? _jsx("script", { type: "application/json", "data-aci-assignments": "", dangerouslySetInnerHTML: { __html: json } }) : null, _jsx(AssignmentsNavigation, { json: json })] }));
 }

package/dist/next/error-seat.js

@@ -78,6 +78,9 @@ function renderClientBlocks(blocks, registry) {
         if (entry.contract.blockSlots) {
             componentProps.renderChildren = (children) => renderClientBlocks(children, 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);
     });
 }

package/dist/next/index.d.ts

@@ -2,6 +2,7 @@ export { DevRefresh, type DevRefreshProps } from './dev-refresh.js';
 export { withAci, type WithAciOptions } from './config.js';
 export { isPreviewMode } from './preview-mode.js';
 export { createPage, type CreatePageOptions, type SlotPropsFn } from './page.js';
+export { renderBlock, renderBlocks } from './render.js';
 export { getSiteConfig, getFragment, getLayout, getPage, getRenderInput, routeFromNextParams } from './server.js';
 export { PageNotFoundError, FragmentNotFoundError, LayoutNotFoundError } from './server.js';
 export { CollectScript, type CollectScriptProps } from './collect-script.js';

package/dist/next/index.js

@@ -2,6 +2,9 @@ export { DevRefresh } from './dev-refresh.js';
 export { withAci } from './config.js';
 export { isPreviewMode } from './preview-mode.js';
 export { createPage } from './page.js';
+// The block renderer seam (sdk I-19, ADR 0051): exported so a site's own
+// conformance test can prove its components carry root identity.
+export { renderBlock, renderBlocks } from './render.js';
 export { getSiteConfig, getFragment, getLayout, getPage, getRenderInput, routeFromNextParams } from './server.js';
 export { PageNotFoundError, FragmentNotFoundError, LayoutNotFoundError } from './server.js';
 export { CollectScript } from './collect-script.js';

package/dist/next/render.js

@@ -6,7 +6,14 @@ export async function renderBlock(block, registry, extraProps) {
     }
     const Component = entry.component;
     const hasBlockSlots = !!entry.contract.blockSlots;
-    const componentProps = { ...block.props, ...extraProps };
+    // sdk I-19 (ADR 0051): root identity props are applied last so neither
+    // content props nor tenant slotProps can overwrite them.
+    const componentProps = {
+        ...block.props,
+        ...extraProps,
+        'data-aci-block': block.id,
+        'data-aci-component': block.component,
+    };
     if (hasBlockSlots) {
         componentProps.renderChildren = (blocks) => renderBlocks(blocks, registry, extraProps);
     }

package/dist/react/VideoPlayer.d.ts

@@ -20,10 +20,10 @@ export declare function VideoPlayer({ video, ...attrs }: VideoPlayerProps): impo
     style?: import("react").CSSProperties | undefined;
     dir?: string | undefined | undefined;
     hidden?: boolean | undefined | undefined;
+    children?: import("react").ReactNode;
     dangerouslySetInnerHTML?: {
         __html: string | TrustedHTML;
     } | undefined | undefined;
-    children?: import("react").ReactNode;
     className?: string | undefined | undefined;
     crossOrigin?: "" | "anonymous" | "use-credentials" | undefined;
     defaultChecked?: boolean | undefined | undefined;

package/dist/react/index.d.ts

@@ -29,10 +29,10 @@ export declare function Image({ image, value, ...attrs }: ImageProps): import("r
     style?: import("react").CSSProperties | undefined;
     dir?: string | undefined | undefined;
     hidden?: boolean | undefined | undefined;
+    children?: ReactNode;
     dangerouslySetInnerHTML?: {
         __html: string | TrustedHTML;
     } | undefined | undefined;
-    children?: ReactNode;
     className?: string | undefined | undefined;
     crossOrigin?: "" | "anonymous" | "use-credentials" | undefined;
     fetchPriority?: "high" | "low" | "auto" | undefined | undefined;

package/dist/registry.d.ts

@@ -1,4 +1,4 @@
-import type { ComponentContract, InferComponentProps } from './types/component.js';
+import type { ComponentContract, ComponentContractID, InferComponentProps } from './types/component.js';
 export type AnyComponent = (abstract new (...args: any[]) => any) | ((props: any) => any) | Record<string, any>;
 export interface RegistryEntry {
     id: string;
@@ -6,7 +6,9 @@ export interface RegistryEntry {
     contract: ComponentContract;
 }
 export type Registry = readonly RegistryEntry[];
-type ValidatedEntry<T> = T extends readonly [infer C extends ComponentContract, infer Comp] ? Comp extends (props: InferComponentProps<C>) => any ? T : Comp extends (props: InferComponentProps<C> & infer _) => any ? T : Comp extends new (props: InferComponentProps<C>, ...args: any[]) => any ? T : Comp extends Record<string, any> ? T : never : never;
+type ValidatedEntry<T> = T extends readonly [infer C extends ComponentContract, infer Comp] ? Comp extends (props: InferComponentProps<C>) => any ? RootIdentityChecked<C, Comp, T> : Comp extends (props: InferComponentProps<C> & infer _) => any ? RootIdentityChecked<C, Comp, T> : Comp extends new (props: InferComponentProps<C>, ...args: any[]) => any ? RootIdentityChecked<C, Comp, T> : Comp extends Record<string, any> ? T : never : never;
+type DeclaredProps<Comp> = Comp extends (props: infer P) => any ? P : Comp extends abstract new (props: infer P, ...args: any[]) => any ? P : Record<string, any>;
+type RootIdentityChecked<C extends ComponentContract, Comp, T> = 'data-aci-block' extends keyof DeclaredProps<Comp> ? 'data-aci-component' extends keyof DeclaredProps<Comp> ? T : `${ComponentContractID<C>}: props type must extend RootIdentityProps from @gradial/aci` : `${ComponentContractID<C>}: props type must extend RootIdentityProps from @gradial/aci`;
 type ValidatedEntries<T extends readonly (readonly [ComponentContract, AnyComponent])[]> = {
     [K in keyof T]: ValidatedEntry<T[K]>;
 };

package/dist/testing/conformance/checks.d.ts

@@ -1,4 +1,4 @@
-import type { ConformanceCheckResult, ConformanceCheckName, ConformanceContext } from './types.js';
+import type { ConformanceCheckResult, ConformanceCheckName, ConformanceContext, ConformanceCheckFn } from './types.js';
 export declare function checkConfig(ctx: ConformanceContext): ConformanceCheckResult[];
 export declare function checkRegistry(ctx: ConformanceContext): ConformanceCheckResult[];
 export declare function checkPageEntry(ctx: ConformanceContext): ConformanceCheckResult[];
@@ -9,4 +9,4 @@ export declare function checkNoRequestTimeAssetRoute(ctx: ConformanceContext): C
 export declare function checkBuildSucceeds(ctx: ConformanceContext): ConformanceCheckResult[];
 export declare function checkContentCompile(ctx: ConformanceContext): ConformanceCheckResult[];
 export declare function checkSdkVersion(ctx: ConformanceContext): ConformanceCheckResult[];
-export declare const CHECK_REGISTRY: Record<ConformanceCheckName, (ctx: ConformanceContext) => ConformanceCheckResult[]>;
+export declare const CHECK_REGISTRY: Record<ConformanceCheckName, ConformanceCheckFn>;

package/dist/testing/conformance/checks.js

@@ -9,6 +9,7 @@
 import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
 import { join, relative } from 'node:path';
 import { execSync } from 'node:child_process';
+import { checkRootIdentity } from './root-identity.js';
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
@@ -445,4 +446,5 @@ export const CHECK_REGISTRY = {
     buildSucceeds: checkBuildSucceeds,
     contentCompile: checkContentCompile,
     sdkVersion: checkSdkVersion,
+    rootIdentity: checkRootIdentity,
 };

package/dist/testing/conformance/index.d.ts

@@ -1,3 +1,4 @@
 export { conformancePreset, runConformanceChecks } from './preset.js';
 export { checkConfig, checkRegistry, checkPageEntry, checkMiddleware, checkNoFileContentProvider, checkNoCustomContent, checkNoRequestTimeAssetRoute, checkBuildSucceeds, checkContentCompile, checkSdkVersion, CHECK_REGISTRY, } from './checks.js';
+export { checkRootIdentity, findRootIdentityFailures, formatRootIdentityFailures, astroAuthoredBlocks, type RootIdentityFailure, } from './root-identity.js';
 export type { ConformanceFramework, ConformanceCheckName, ConformancePresetOptions, ConformanceCheckResult, ConformanceResult, ConformanceContext, ConformanceCheckFn, } from './types.js';

package/dist/testing/conformance/index.js

@@ -1,2 +1,3 @@
 export { conformancePreset, runConformanceChecks } from './preset.js';
 export { checkConfig, checkRegistry, checkPageEntry, checkMiddleware, checkNoFileContentProvider, checkNoCustomContent, checkNoRequestTimeAssetRoute, checkBuildSucceeds, checkContentCompile, checkSdkVersion, CHECK_REGISTRY, } from './checks.js';
+export { checkRootIdentity, findRootIdentityFailures, formatRootIdentityFailures, astroAuthoredBlocks, } from './root-identity.js';

package/dist/testing/conformance/next-stubs.d.ts

@@ -0,0 +1,6 @@
+export declare function resolve(specifier: string, context: unknown, nextResolve: (specifier: string, context: unknown) => Promise<{
+    url: string;
+}>): Promise<{
+    url: string;
+    shortCircuit?: boolean;
+}>;

package/dist/testing/conformance/next-stubs.js

@@ -0,0 +1,9 @@
+// Node module customization hook for the rootIdentity check: outside Next's
+// bundler, `next/link` and `next/image` resolve to CommonJS interop objects
+// that react-dom/server cannot render. Swap them for plain-element stubs.
+export async function resolve(specifier, context, nextResolve) {
+    if (specifier === 'next/link' || specifier === 'next/image') {
+        return { url: new URL(`./stubs/${specifier.replace('/', '-')}.js`, import.meta.url).href, shortCircuit: true };
+    }
+    return nextResolve(specifier, context);
+}

package/dist/testing/conformance/preset.d.ts

@@ -2,9 +2,10 @@ import type { ConformancePresetOptions, ConformanceResult } from './types.js';
 /**
  * Run all resolved checks and return an aggregate result.
  * This is the programmatic API — call it directly if you don't want the
- * node:test integration.
+ * node:test integration. It is async: the rootIdentity check renders
+ * components, so `await` the result before reading `.passed`.
  */
-export declare function runConformanceChecks(options: ConformancePresetOptions): ConformanceResult;
+export declare function runConformanceChecks(options: ConformancePresetOptions): Promise<ConformanceResult>;
 /**
  * Register a conformance test suite using node:test.
  *

package/dist/testing/conformance/preset.js

@@ -29,6 +29,9 @@ const ALL_CHECKS = [
     'noCustomContent',
     'noRequestTimeAssetRoute',
     'sdkVersion',
+    // Renders every registered component (ADR 0051); on Astro it scans dist/,
+    // building first when absent.
+    'rootIdentity',
     // Expensive checks last — these shell out
     'contentCompile',
     'buildSucceeds',
@@ -51,19 +54,20 @@ function resolveChecks(input) {
 /**
  * Run all resolved checks and return an aggregate result.
  * This is the programmatic API — call it directly if you don't want the
- * node:test integration.
+ * node:test integration. It is async: the rootIdentity check renders
+ * components, so `await` the result before reading `.passed`.
  */
-export function runConformanceChecks(options) {
+export async function runConformanceChecks(options) {
     const ctx = {
         framework: options.framework,
         siteId: options.siteId ?? '',
         rootDir: options.rootDir || process.cwd(),
     };
     const checks = resolveChecks(options.checks);
-    const allResults = checks.flatMap((name) => {
-        const checkFn = CHECK_REGISTRY[name];
-        return checkFn(ctx);
-    });
+    const allResults = [];
+    for (const name of checks) {
+        allResults.push(...(await CHECK_REGISTRY[name](ctx)));
+    }
     const failures = allResults.filter((r) => !r.ok);
     return {
         passed: failures.length === 0,
@@ -86,9 +90,9 @@ export function conformancePreset(options) {
             rootDir: options.rootDir || process.cwd(),
         };
         for (const checkName of checks) {
-            await t.test(checkName, () => {
+            await t.test(checkName, async () => {
                 const checkFn = CHECK_REGISTRY[checkName];
-                const results = checkFn(ctx);
+                const results = await checkFn(ctx);
                 for (const result of results) {
                     assert.ok(result.ok, `${result.label}${result.detail ? ` (${result.detail})` : ''}`);
                 }

package/dist/testing/conformance/root-identity.d.ts

@@ -0,0 +1,31 @@
+import type { ConformanceCheckResult, ConformanceContext } from './types.js';
+import type { Registry } from '../../registry.js';
+import type { KernelPageBlock } from '../../content/types.js';
+export interface RootIdentityFailure {
+    component: string;
+    file?: string;
+    missing: string[];
+}
+/** Minimal React surface the renderer needs; injected so tests can pass fakes. */
+export interface ReactRuntime {
+    renderToStaticMarkup: (element: unknown) => string;
+}
+/**
+ * Render each block through the SDK renderer and report every component
+ * whose root element lacks the identity attributes. `blocks` are the blocks
+ * to exercise; registry entries not covered by a block are probed with empty
+ * props so an unused component cannot hide a forgotten spread.
+ */
+export declare function findRootIdentityFailures(registry: Registry, blocks: readonly KernelPageBlock[], react: ReactRuntime, fileFor?: (component: string) => string | undefined): Promise<RootIdentityFailure[]>;
+/** The failure message: one line of what, the list, one line of fix. */
+export declare function formatRootIdentityFailures(failures: readonly RootIdentityFailure[], framework: 'next' | 'astro'): string;
+export declare function checkRootIdentity(ctx: ConformanceContext): Promise<ConformanceCheckResult[]>;
+/**
+ * Every block the Astro scan must find in dist/: page blocks by their own id,
+ * plus fragments (navbar, footer) by fragment id, which is the block id the
+ * renderer synthesizes when a layout slot default places them.
+ */
+export declare function astroAuthoredBlocks(contentDir: string): Array<{
+    id: string;
+    component: string;
+}>;