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

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/config.js

@@ -13,19 +13,12 @@ export function withAci(nextConfig = {}, options = {}) {
             '`next dev` / `next build` without --turbopack.');
     }
     const publicPaths = collectPublicPaths(join(process.cwd(), 'public'));
-    // Authorable error pages (D-9): the Next error seat is client-only, so the
-    // bound catchAll page's content is serialized here — while next.config is
-    // evaluated — and injected into the bundle via DefinePlugin below. The D-5
-    // posture rides ACI_ERROR_PAGES_POSTURE (the same variable the Go stack
-    // reads): under warn (default), absent bindings/content and non-REQ-5
-    // serialization failures warn and serialize the shipped default (REQ-4);
-    // under enforce they fail the build closed, and unknown posture values
-    // fail closed too. Present-but-broken bindings fail closed always (REQ-5).
-    // A code artifact is independent of every content snapshot. Authored error
-    // bindings are validated when previewing/publishing the selected content.
-    const errorSeat = process.env.ACI_CODE_ARTIFACT_BUILD === '1'
-        ? { payload: { defaulted: true, defaultHtml: defaultErrorPageFragmentHtml() }, warnings: [], errors: [] }
-        : buildErrorSeatPayload(undefined, process.env.ACI_ERROR_PAGES_POSTURE);
+    // Local dev previews the authored error seat. Production code builds must
+    // never bake a content snapshot into the native client-only error seat;
+    // the selected release's authored errors are materialized at publish.
+    const errorSeat = process.env.NODE_ENV === 'development'
+        ? buildErrorSeatPayload(undefined, process.env.ACI_ERROR_PAGES_POSTURE)
+        : { payload: { defaulted: true, defaultHtml: defaultErrorPageFragmentHtml() }, warnings: [], errors: [] };
     if (errorSeat.errors.length > 0) {
         throw new Error(`ACI errorPages bindings are invalid (site.json#errorPages):\n- ${errorSeat.errors.join('\n- ')}`);
     }

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

@@ -1,6 +1,6 @@
 import type { ErrorSeatPayload } from './error-seat.js';
 /**
- * Build-time serialization of the bound catchAll page for the client-only
+ * Local-development serialization of the bound catchAll page for the client-only
  * Next error seat (authorable-error-pages D-9). Synchronous by design: it
  * runs inside withAci() while next.config is evaluated, reading the compiled
  * content tree directly (the async providers cannot be awaited there).

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

@@ -29,8 +29,7 @@ export function buildErrorSeatPayload(contentRoot, posture) {
     const root = path.resolve(process.cwd(), contentRoot || process.env.ACI_CONTENT_ROOT || '.aci/compiled');
     if (!existsSync(path.join(root, 'manifest.json'))) {
         const message = `no compiled content at ${root}; the error seat will serve the shipped default page — `
-            + 'run the content compile before `next build` (the template build script\'s '
-            + '`emit-error-pages.mjs prepare` phase does this)';
+            + 'run `npm run content:compile` to preview authored error pages locally';
         if (effectivePosture === 'enforce') {
             errors.push(`${message} (posture "enforce" fails closed, D-5)`);
         }

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;

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

@@ -0,0 +1,92 @@
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+/**
+ * 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 function findRegistryFiles(siteDir) {
+    const src = join(siteDir, 'src');
+    const underSrc = existsSync(src) ? walkForRegistries(src) : [];
+    return underSrc.length > 0 ? underSrc : walkForRegistries(siteDir);
+}
+function walkForRegistries(rootDir) {
+    const skip = new Set(['node_modules', '.next', '.aci', 'dist', '.git', 'tests', 'scripts']);
+    const found = [];
+    const walk = (dir) => {
+        for (const entry of readdirSync(dir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+            if (entry.name.startsWith('.'))
+                continue;
+            const full = join(dir, entry.name);
+            if (entry.isDirectory()) {
+                if (!skip.has(entry.name))
+                    walk(full);
+            }
+            else if (/\.(ts|tsx|js|mjs)$/.test(entry.name) && !/\.(test|spec)\./.test(entry.name)
+                && readFileSync(full, 'utf8').includes('createRegistry(')) {
+                found.push(full);
+            }
+        }
+    };
+    walk(rootDir);
+    return found;
+}
+/** Merge registries by component id; the first file that registers an id wins. */
+export function mergeRegistries(registries) {
+    const seen = new Set();
+    const merged = [];
+    for (const registry of registries) {
+        for (const entry of registry) {
+            if (seen.has(entry.id))
+                continue;
+            seen.add(entry.id);
+            merged.push(entry);
+        }
+    }
+    return merged;
+}
+export function classifyLoadError(err) {
+    const e = err;
+    const message = e?.message ?? String(err);
+    const code = e?.code ?? '';
+    const unknownExt = /Unknown file extension "(\.[a-z]+)"/i.exec(message)?.[1]?.toLowerCase();
+    if (code === 'ERR_UNKNOWN_FILE_EXTENSION' && unknownExt && ['.ts', '.tsx', '.mts', '.cts', '.jsx'].includes(unknownExt)) {
+        return { kind: 'loader-missing', reason: `cannot load ${unknownExt} files` };
+    }
+    if (code === 'ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX' || code === 'ERR_INVALID_TYPESCRIPT_SYNTAX'
+        || code === 'ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING') {
+        return { kind: 'loader-missing', reason: 'cannot compile TypeScript or JSX' };
+    }
+    const missing = /Cannot find (?:package|module) '([^']+)'/.exec(message)?.[1];
+    if ((code === 'ERR_MODULE_NOT_FOUND' || code === 'MODULE_NOT_FOUND') && missing && /^[@~]\//.test(missing)) {
+        return { kind: 'loader-missing', reason: `cannot resolve the path alias "${missing}"` };
+    }
+    return { kind: 'unloadable', reason: firstLine(message) };
+}
+/** Thrown when the test process has no TypeScript/JSX loader at all. */
+export class LoaderMissingError extends Error {
+    constructor(file, reason) {
+        super(`cannot load ${file}: this test process ${reason}.\n`
+            + '  Run tests with:  node --import tsx --test\n'
+            + '  See the @gradial/aci CHANGELOG, "Migration required: test loader".');
+        this.name = 'LoaderMissingError';
+    }
+}
+function firstLine(text) {
+    const line = text.split('\n').find((l) => l.trim()) ?? text;
+    return line.length > 200 ? `${line.slice(0, 200)}…` : line;
+}
+/** The `createRegistry` result among a module's exports. */
+export function registryExport(mod) {
+    // The canonical `registry` export may be empty; any other export must look
+    // like a registry to count as one.
+    if (Array.isArray(mod.registry) && mod.registry.length === 0)
+        return [];
+    return Object.values(mod).find(isRegistry);
+}
+function isRegistry(value) {
+    return Array.isArray(value) && value.length > 0
+        && value.every((e) => e && typeof e === 'object' && typeof e.id === 'string' && 'component' in e && 'contract' in e);
+}

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

@@ -0,0 +1,27 @@
+import type { KernelPageBlock } from '../../content/types.js';
+import type { Registry } from '../../registry.js';
+export type AdapterId = 'astro' | 'next';
+/**
+ * The one framework seam the platform tests have (ADR 0063 §One verifier):
+ * render one registered component outside the site build, and map a
+ * registry entry to its source file. Everything else is framework-neutral.
+ */
+export interface FrameworkAdapter {
+    id: AdapterId;
+    /** Render one block in isolation through the SDK's own prop injection. */
+    renderBlock(block: KernelPageBlock): Promise<string>;
+    /** The site-relative source file of a registered component, when known. */
+    sourceFileFor(componentId: string): string | undefined;
+}
+/** A site's registry loaded for isolated renders, and its adapter. */
+export interface LoadedSite {
+    /** The union of every registry file that loaded. */
+    registry: Registry;
+    adapter: FrameworkAdapter;
+    /** Registry files the isolated loader could not load, with the reason. */
+    unloadable: {
+        file: string;
+        reason: string;
+    }[];
+    close(): Promise<void>;
+}

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

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

package/dist/platform-tests/index.d.ts

@@ -0,0 +1,47 @@
+/**
+ * The root-identity judgement conformance runs over a site's renders
+ * (`./testing`, site-check.ts).
+ */
+export { collectComponentBlocks, isComponentBlock, type ComponentBlock } from '../content/component-block.js';
+export type TestVerdict = 'pass' | 'fail' | 'not-run';
+export interface TestFinding {
+    route: string;
+    variantKey?: string;
+    blockId: string;
+    component: string;
+    message: string;
+}
+export interface TestOutcome {
+    test: string;
+    /** The test's own contract version, raised only on a breaking change. */
+    version: number;
+    verdict: TestVerdict;
+    findings: TestFinding[];
+}
+export interface TestContext {
+    /** Route path, e.g. "/" or "/about". */
+    route: string;
+    /** Personalization variant; absent for the base render. */
+    variantKey?: string;
+    /** The compiled page payload the renderer was given. */
+    payload: unknown;
+    /** The HTML the render produced. */
+    html: string;
+}
+export interface PlatformTest {
+    version: number;
+    run(ctx: TestContext): TestOutcome;
+}
+/** Every platform test the SDK declares. */
+export declare const TESTS: {
+    readonly rootIdentity: {
+        readonly version: 1;
+        readonly run: typeof rootIdentity;
+    };
+};
+declare function rootIdentity(ctx: TestContext): TestOutcome;
+/**
+ * An attribute value as each SDK renderer writes it: Astro's addAttribute
+ * escapes only & and "; react-dom/server also escapes ' < >.
+ */
+export declare function renderedAttributeValues(value: string): [astro: string, react: string];

package/dist/platform-tests/index.js

@@ -0,0 +1,50 @@
+/**
+ * The root-identity judgement conformance runs over a site's renders
+ * (`./testing`, site-check.ts).
+ */
+import { collectComponentBlocks } from '../content/component-block.js';
+export { collectComponentBlocks, isComponentBlock } from '../content/component-block.js';
+/** Every platform test the SDK declares. */
+export const TESTS = {
+    rootIdentity: { version: 1, run: rootIdentity },
+};
+// ---------------------------------------------------------------------------
+// rootIdentity (ADR 0051, ADR 0063): every component block in the payload
+// appears in the HTML as an element carrying data-aci-block="<id>".
+// ---------------------------------------------------------------------------
+const ROOT_IDENTITY_MESSAGE = 'no element carries the block\'s data-aci-block attribute';
+function rootIdentity(ctx) {
+    const outcome = (verdict, findings) => ({
+        test: 'rootIdentity',
+        version: TESTS.rootIdentity.version,
+        verdict,
+        findings,
+    });
+    if (typeof ctx?.html !== 'string' || typeof ctx.route !== 'string')
+        return outcome('not-run', []);
+    // One pass over the HTML: every attribute value as the renderer wrote it.
+    const rendered = new Set();
+    for (const match of ctx.html.matchAll(/\sdata-aci-block="([^"]*)"/g))
+        rendered.add(match[1]);
+    const findings = [];
+    for (const block of collectComponentBlocks(ctx.payload)) {
+        if (renderedAttributeValues(block.id).some((value) => rendered.has(value)))
+            continue;
+        findings.push({
+            route: ctx.route,
+            ...(ctx.variantKey ? { variantKey: ctx.variantKey } : {}),
+            blockId: block.id,
+            component: block.component,
+            message: ROOT_IDENTITY_MESSAGE,
+        });
+    }
+    return outcome(findings.length > 0 ? 'fail' : 'pass', findings);
+}
+/**
+ * An attribute value as each SDK renderer writes it: Astro's addAttribute
+ * escapes only & and "; react-dom/server also escapes ' < >.
+ */
+export function renderedAttributeValues(value) {
+    const astro = value.replace(/&/g, '&amp;').replace(/"/g, '&quot;');
+    return [astro, astro.replace(/'/g, '&#x27;').replace(/</g, '&lt;').replace(/>/g, '&gt;')];
+}

package/dist/platform-tests/sample-props.d.ts

@@ -0,0 +1,2 @@
+/** A props object the schema accepts, or undefined when it cannot be derived. */
+export declare function samplePropsFromSchema(schema: unknown): Record<string, unknown> | undefined;