@gradial/aci 0.1.53-canary.694 → 0.1.53-canary.700

package/CHANGELOG.md

@@ -4,12 +4,51 @@
 
 ### Added
 
+- `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
 
+- **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 +57,32 @@
   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
 
+- **`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-canary.694` is a pre-1.0 public-surface reset for the ACI
+`@gradial/aci` `0.1.53-canary.700` 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-canary.694 zod@^4
+npm install @gradial/aci@0.1.53-canary.700 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-canary.694 init my-site --template next-starter
+npx @gradial/aci@0.1.53-canary.700 init my-site --template next-starter
 ```
 
 List available templates:
 
 ```bash
-npx @gradial/aci@0.1.53-canary.694 init --list
+npx @gradial/aci@0.1.53-canary.700 init --list
 ```
 
 ## Personalization: The One-Tag Install

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/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 {};

package/dist/internal/aci-root.js

@@ -0,0 +1,49 @@
+import { isComponentBlock } from '../content/component-block.js';
+/**
+ * The one place a renderer seam applies the block root identity (sdk I-31,
+ * ADR 0063 §One verifier). The identity props go last, so neither content
+ * props nor tenant slotProps can overwrite them.
+ *
+ * @internal
+ */
+export function withAciRootProps(props, block) {
+    return {
+        ...props,
+        'data-aci-block': block.id,
+        'data-aci-component': block.component,
+    };
+}
+/**
+ * A copy of a block's content props in which every nested component block
+ * (the `rootIdentity` predicate, at any depth: a block slot, or a list inside
+ * an item such as `tabs[].blocks`) carries its own identity in its `props`
+ * (sdk I-31). A container that renders a child with `{...child.props}` then
+ * emits the child's identity; one that calls `renderChildren` re-applies the
+ * same values, so nothing doubles. Walk only compiled content, never tenant
+ * slotProps: those can hold React elements.
+ *
+ * @internal
+ */
+export function withNestedAciRootProps(props) {
+    return stampNested(props);
+}
+function stampNested(value) {
+    if (Array.isArray(value))
+        return value.map(stampNested);
+    if (!isPlainObject(value))
+        return value;
+    const out = {};
+    for (const [key, child] of Object.entries(value))
+        out[key] = stampNested(child);
+    if (isComponentBlock(out) && typeof out.id === 'string' && out.id !== ''
+        && typeof out.component === 'string' && isPlainObject(out.props)) {
+        out.props = withAciRootProps(out.props, { id: out.id, component: out.component });
+    }
+    return out;
+}
+function isPlainObject(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const proto = Object.getPrototypeOf(value);
+    return proto === Object.prototype || proto === null;
+}

package/dist/next/error-seat.js

@@ -1,6 +1,7 @@
 'use client';
 import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
 import { Component, Fragment } from 'react';
+import { withAciRootProps, withNestedAciRootProps } from '../internal/aci-root.js';
 import { ErrorPageInstrumentation } from './error-page-instrumentation.js';
 import { ErrorPageMarker } from './error-page-marker.js';
 /** The build-time serialized payload, or null when the define is absent. */
@@ -74,13 +75,11 @@ function renderClientBlocks(blocks, registry) {
         if (!entry)
             return null;
         const Component = entry.component;
-        const componentProps = { ...block.props };
+        // sdk I-31 (ADR 0051): the error seat is an injection seam too.
+        const componentProps = withAciRootProps(withNestedAciRootProps(block.props), block);
         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;
         // 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.js

@@ -1,4 +1,5 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { withAciRootProps, withNestedAciRootProps } from '../internal/aci-root.js';
 export async function renderBlock(block, registry, key, extraProps) {
     const entry = registry.find((r) => r.id === block.component);
     if (!entry) {
@@ -6,14 +7,7 @@ export async function renderBlock(block, registry, key, extraProps) {
     }
     const Component = entry.component;
     const hasBlockSlots = !!entry.contract.blockSlots;
-    // 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,
-    };
+    const componentProps = withAciRootProps({ ...withNestedAciRootProps(block.props), ...extraProps }, block);
     if (hasBlockSlots) {
         componentProps.renderChildren = (blocks) => renderBlocks(blocks, registry, extraProps);
     }

package/dist/platform-tests/adapters/astro.d.ts

@@ -0,0 +1,2 @@
+import type { LoadedSite } from './types.js';
+export declare function openAstroSite(siteDir: string, explicit?: readonly string[]): Promise<LoadedSite>;

package/dist/platform-tests/adapters/astro.js

@@ -0,0 +1,101 @@
+/**
+ * Astro adapter: renders one registered component with the Astro Container
+ * API over a Vite server that Astro configures for the site
+ * (`getViteConfig`), the way Astro documents testing components. No site
+ * build and no emitted HTML, so static and server output are covered alike.
+ * astro, its container, and vite resolve from the site, never from the SDK.
+ */
+import { createRequire } from 'node:module';
+import { join, relative, sep } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { createRenderChildren } from '../../astro/index.js';
+import { classifyLoadError, findRegistryFiles, mergeRegistries, registryExport } from './site.js';
+export async function openAstroSite(siteDir, explicit = []) {
+    // Every file that calls createRegistry(, plus any registry the site names explicitly.
+    const registryFiles = [...new Set([...findRegistryFiles(siteDir), ...explicit])].sort();
+    if (registryFiles.length === 0)
+        throw new Error('no registry file imports createRegistry from @gradial/aci');
+    const fromSite = createRequire(join(siteDir, 'package.json'));
+    const importFrom = async (resolve, specifier) => (await import(pathToFileURL(resolve(specifier)).href));
+    const { getViteConfig } = await importFrom(fromSite.resolve, 'astro/config');
+    const { experimental_AstroContainer } = await importFrom(fromSite.resolve, 'astro/container');
+    const fromAstro = createRequire(fromSite.resolve('astro/package.json'));
+    const { createServer } = await importFrom(fromAstro.resolve, 'vite');
+    const vite = await withoutContentWatch(async () => {
+        // An isolated SSR render needs no client dependency optimizer and no dev
+        // toolbar; both would otherwise run in the background past close().
+        const config = await getViteConfig({
+            logLevel: 'silent',
+            optimizeDeps: { noDiscovery: true, include: [] },
+        }, { root: siteDir, logLevel: 'silent', devToolbar: { enabled: false } })({ mode: 'development', command: 'serve' });
+        const server = (config.server ?? {});
+        return createServer({
+            ...config,
+            server: { ...server, middlewareMode: true, hmr: false, ws: false, watch: null },
+            appType: 'custom',
+        });
+    });
+    try {
+        // Every registry file is loaded through Astro's own Vite pipeline; one
+        // that cannot load is reported and does not hide the others.
+        const registries = [];
+        const unloadable = [];
+        for (const registryFile of registryFiles) {
+            const rel = relative(siteDir, registryFile);
+            try {
+                const registry = registryExport(await vite.ssrLoadModule('/' + rel.split(sep).join('/')));
+                if (registry)
+                    registries.push(registry);
+                else
+                    unloadable.push({ file: rel, reason: 'does not export the createRegistry result' });
+            }
+            catch (err) {
+                unloadable.push({ file: rel, reason: classifyLoadError(err).reason });
+            }
+        }
+        const registry = mergeRegistries(registries);
+        const container = await experimental_AstroContainer.create();
+        return {
+            registry,
+            adapter: createAstroAdapter(registry, container, siteDir),
+            unloadable,
+            close: () => vite.close(),
+        };
+    }
+    catch (err) {
+        await vite.close();
+        throw err;
+    }
+}
+function createAstroAdapter(registry, container, siteDir) {
+    const renderChildren = createRenderChildren(registry);
+    return {
+        id: 'astro',
+        async renderBlock(block) {
+            const [{ Component, props }] = renderChildren([block]);
+            if (!Component)
+                throw new Error(`no registered component "${block.component}"`);
+            return container.renderToString(Component, { props });
+        },
+        sourceFileFor(componentId) {
+            // Astro's compiler stamps every component factory with its source path.
+            const component = registry.find((entry) => entry.id === componentId)?.component;
+            return typeof component?.moduleId === 'string' ? relative(siteDir, component.moduleId) : undefined;
+        },
+    };
+}
+// withAci() recompiles content when a dev server starts; an isolated render
+// needs neither the recompile nor the watcher.
+async function withoutContentWatch(fn) {
+    const previous = process.env.ACI_DISABLE_CONTENT_WATCH;
+    process.env.ACI_DISABLE_CONTENT_WATCH = '1';
+    try {
+        return await fn();
+    }
+    finally {
+        if (previous === undefined)
+            delete process.env.ACI_DISABLE_CONTENT_WATCH;
+        else
+            process.env.ACI_DISABLE_CONTENT_WATCH = previous;
+    }
+}

package/dist/platform-tests/adapters/next.d.ts

@@ -0,0 +1,9 @@
+import type { Registry } from '../../registry.js';
+import type { FrameworkAdapter, LoadedSite } from './types.js';
+/** The react-dom/server surface the adapter needs. */
+interface ReactRuntime {
+    renderToStaticMarkup(element: unknown): string;
+}
+export declare function openNextSite(siteDir: string, explicit?: readonly string[]): Promise<LoadedSite>;
+export declare function createNextAdapter(registry: Registry, react: ReactRuntime, sourceFileFor: (componentId: string) => string | undefined): FrameworkAdapter;
+export {};

package/dist/platform-tests/adapters/next.js

@@ -0,0 +1,112 @@
+/**
+ * Next adapter: renders one registered component with react-dom/server from
+ * the site's own React, through the SDK's `renderBlock`. `next/link` and
+ * `next/image` are stubbed (testing/conformance/next-stubs.ts) because their
+ * CommonJS interop objects cannot render outside Next's bundler.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { join, relative } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { renderBlock } from '../../next/render.js';
+import { classifyLoadError, findRegistryFiles, LoaderMissingError, mergeRegistries, registryExport } from './site.js';
+export async function openNextSite(siteDir, explicit = []) {
+    // Every file that calls createRegistry(, plus any registry the site names explicitly.
+    const registryFiles = [...new Set([...findRegistryFiles(siteDir), ...explicit])].sort();
+    if (registryFiles.length === 0)
+        throw new Error('no registry file imports createRegistry from @gradial/aci');
+    const fromSite = createRequire(join(siteDir, 'package.json'));
+    const react = fromSite('react-dom/server');
+    // The site's tsconfig may keep `jsx: preserve` for Next, in which case the
+    // test transform emits classic React.createElement calls.
+    globalThis.React = fromSite('react');
+    const { register } = await import('node:module');
+    register(stubHookURL());
+    // Every registry file is loaded; one that cannot load does not hide the
+    // others. A process with no TypeScript/JSX loader is a different failure:
+    // nothing can be checked and the fix is one line, so it throws.
+    const registries = [];
+    const unloadable = [];
+    const fileFor = new Map();
+    for (const registryFile of registryFiles) {
+        const rel = relative(siteDir, registryFile);
+        let mod;
+        try {
+            mod = (await import(pathToFileURL(registryFile).href));
+        }
+        catch (err) {
+            const failure = classifyLoadError(err);
+            if (failure.kind === 'loader-missing')
+                throw new LoaderMissingError(rel, failure.reason);
+            unloadable.push({ file: rel, reason: failure.reason });
+            continue;
+        }
+        const registry = registryExport(mod);
+        if (!registry) {
+            unloadable.push({ file: rel, reason: 'does not export the createRegistry result' });
+            continue;
+        }
+        registries.push(registry);
+        const resolve = componentFileResolver(readFileSync(registryFile, 'utf8'), registry);
+        for (const entry of registry) {
+            const file = resolve(entry.id);
+            if (file && !fileFor.has(entry.id))
+                fileFor.set(entry.id, file);
+        }
+    }
+    const registry = mergeRegistries(registries);
+    return {
+        registry,
+        adapter: createNextAdapter(registry, react, (id) => fileFor.get(id)),
+        unloadable,
+        close: async () => { },
+    };
+}
+export function createNextAdapter(registry, react, sourceFileFor) {
+    return {
+        id: 'next',
+        async renderBlock(block) {
+            if (!registry.some((entry) => entry.id === block.component)) {
+                throw new Error(`no registered component "${block.component}"`);
+            }
+            return markupFor(await renderBlock(block, registry, `probe:${block.id}`), react);
+        },
+        sourceFileFor,
+    };
+}
+/**
+ * Slot components are async server components in Next; react-dom/server
+ * cannot render those, so the element the SDK produced is unwrapped by
+ * awaiting the component function directly.
+ */
+async function markupFor(element, react) {
+    const el = element;
+    if (typeof el.type === 'function' && el.type.constructor?.name === 'AsyncFunction') {
+        return react.renderToStaticMarkup(await el.type(el.props));
+    }
+    return react.renderToStaticMarkup(element);
+}
+/** The stub hook: compiled `.js` in dist, `.ts` when run from source. */
+function stubHookURL() {
+    const js = new URL('../../testing/conformance/next-stubs.js', import.meta.url);
+    if (existsSync(fileURLToPath(js)))
+        return js;
+    return new URL('../../testing/conformance/next-stubs.ts', import.meta.url);
+}
+/** Map a registered component id to the import path the registry file names for it. */
+function componentFileResolver(registrySource, registry) {
+    const imports = new Map();
+    for (const m of registrySource.matchAll(/import\s+(?:\{([^}]*)\}|(\w+))\s+from\s+['"]([^'"]+)['"]/g)) {
+        const names = (m[1] ?? m[2]).split(',').map((n) => n.trim().split(/\s+as\s+/).pop()).filter(Boolean);
+        for (const name of names)
+            imports.set(name, m[3]);
+    }
+    const byId = new Map();
+    for (const entry of registry) {
+        const fn = entry.component;
+        const file = typeof fn === 'function' && fn.name ? imports.get(fn.name) : undefined;
+        if (file)
+            byId.set(entry.id, file);
+    }
+    return (componentId) => byId.get(componentId);
+}

package/dist/platform-tests/adapters/site.d.ts

@@ -0,0 +1,29 @@
+import type { Registry } from '../../registry.js';
+/**
+ * Every source file that calls `createRegistry(`, in a stable order: under
+ * `src/` when the site has one, so a build output directory (whose bundled
+ * chunks also contain the call) is never mistaken for a registry. A site may
+ * keep several (a main registry, an error-page registry); the check covers
+ * the union, so "passed" means every registered component was looked at.
+ */
+export declare function findRegistryFiles(siteDir: string): string[];
+/** Merge registries by component id; the first file that registers an id wins. */
+export declare function mergeRegistries(registries: readonly Registry[]): Registry;
+/**
+ * Why a registry file could not be loaded. `loader-missing` means the test
+ * process itself cannot load TypeScript, JSX, or the site's path aliases:
+ * a site configuration defect with a one-line fix, and the check verified
+ * nothing. Anything else is a limit of the isolated loader, reported as
+ * not-run and left to publish.
+ */
+export type LoadFailure = {
+    kind: 'loader-missing' | 'unloadable';
+    reason: string;
+};
+export declare function classifyLoadError(err: unknown): LoadFailure;
+/** Thrown when the test process has no TypeScript/JSX loader at all. */
+export declare class LoaderMissingError extends Error {
+    constructor(file: string, reason: string);
+}
+/** The `createRegistry` result among a module's exports. */
+export declare function registryExport(mod: Record<string, unknown>): Registry | undefined;