@gradial/aci 0.1.53-rc.7 → 0.2.0-canary.715

package/CHANGELOG.md

@@ -4,6 +4,26 @@
 
 ### Fixed
 
+- The staged and live checks fetch the stable collect script
+  (`/_aci/aci.js`) at the judged release's own path,
+  `/__r/<release>/_aci/aci.js`. The stable URL answers the active
+  release's SDK, so on a Vercel staged preview (a deployment the active
+  pointer does not target yet) it answered 404 and every SSR publish with a
+  new code deployment failed `assets.notFound`.
+- Page verification treats redirects as site logic. A page a redirect
+  answers (next.config redirects, vercel.json, a host rule) is judged on
+  where it lands: a 2xx passes with the warning `route.redirected` (the
+  published page is unreachable at its own URL; the hop chain is in the
+  message), and only the status check runs on it. A redirect that lands on
+  a 4xx or 5xx, loops, or still redirects after 10 hops is `status.notOk`.
+  The release marker is read on the page a redirect lands on, and not at
+  all when it lands on another origin. A link to a route the release does
+  not publish passes when the server redirects it to a 2xx. The candidate
+  server keeps an upstream redirect on its own origin, and answers the
+  site's own `next.config` redirects (`siteRedirects`, from the build's
+  routes manifest) for a path no page holds, so a link to a redirected
+  route passes before staging too.
+
 - Astro root-identity conformance checks now load the site-configured UI renderers,
   allowing nested React and other integration components to render in the isolated
   container.
@@ -32,6 +52,55 @@
 - 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.
+- Page verification fetches the images an inline `style` attribute
+  references (`url()`), so a missing hero background is `fetch.notFound`,
+  and warns with `document.unrenderedValue` when page text shows
+  `undefined`, `NaN` or `[object Object]`. The warning never blocks.
+- `.aci/registry.json` records `sdkVersion`, the SDK that compiled it.
+- `@gradial/aci/verify`: page verification, a map and a reduce whose loop the
+  caller owns. `testUnit({ ref, source, profile })` verifies one route ×
+  variant and returns a plain-JSON `UnitResult` (its findings and the facts
+  the release checks need), so units can run in other processes or CI jobs;
+  `reduce(unitResults, { routes, profile })` judges every unit's facts
+  against the release's routes and returns
+  `{ errors, warnings, sdkVersion, stats }`. `withFetchCache(source)` shares
+  one fetch cache across the units you run. `@gradial/aci/verify/local`
+  holds the local loop, `runSuite({ source, profile })`, and adds
+  `listLocalUnits`, `runLocalShard` (one `--shard i/n`) and
+  `reduceLocalResults` for a sharded CI run. Profiles: `health` (each page
+  answers 2xx, and an error page at `/_errors/404/` answers 404:
+  `status.*`), `smoke` (plus the page's own scripts, stylesheets and images
+  load: `assets.*`) and `full` (plus each page is a full HTML document,
+  `document.*`, and error pages need exactly one
+  `<script data-aci-error-page>` tag; every component block has its
+  `data-aci-block` root, `blocks.missingRoot`; every internal link goes to
+  a published route, `links.unpublishedTarget`; every script, stylesheet,
+  image, srcset candidate and file link answers, `fetch.notFound` and
+  `fetch.failed`). A failed same-origin or DAM URL is an error; a failed
+  third-party URL is a warning. One source kind:
+  `urlSource({ baseUrl, pages, auth?, address? })` reads pages over HTTP from
+  a dev server, a CI server, a candidate server, a staged preview or live.
+  `serveCandidate({ pages?, renderer?, units?, mounts? })` is the candidate
+  server: pre-rendered pages, or compiled pages rendered on request through
+  `@gradial/aci/render`, plus your build's assets (`siteAssetMounts`). `auth` headers only go to the server's
+  own origin. Pass `pages` to verify a subset; links are still checked
+  against every route. A page that cannot be rendered or reached is an
+  error with its `render.*` or `page.unreachable` code. A check that throws
+  is a `<check>.crashed` error on the page it was judging; the rest of the
+  run still judges. A page without a compiled payload is listed under
+  `stats.unjudged` for the checks that need one (`blocks`). The base render
+  has no `variantKey`.
+- Next: `withAci()` traces `@gradial/aci/render` and `@gradial/aci/verify`
+  (their whole import closure) into the standalone output, where the
+  platform loads them.
+- `@gradial/aci/render`: `createRenderer({ siteRoot, contentRoot })` starts
+  your built Next, Astro or Mintlify site once and `render(page)` returns one
+  compiled page's HTML, rejecting with a typed `RenderError` (`code`, `route`,
+  `variantKey`). The platform renders publish-time pages through it when your
+  installed SDK has it; older SDKs keep the platform's own harness. The base
+  render omits `variantKey` (`"base"` and `""` are refused as `render.input`),
+  and a page without a site config, domain or locale is `render.input`
+  instead of a guessed default.
 
 ### Migration required
 
@@ -46,6 +115,23 @@
   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)".
+- **Publish verifies every page** (sdk I-33) — before a release is staged,
+  publish renders every page and variant and runs the `@gradial/aci/verify`
+  `full` profile over them; any error refuses the publish with
+  `publish.verification_failed` and the findings (route, code, what to fix).
+  The block-root rule above is its `blocks.missingRoot` check. A check that
+  crashes is a `<check>.crashed` error on that page, which an owner can force
+  past. Run the same checks first: `aci verify` (below) locally, in
+  `npm test`, and in the `aci-verify.yml` CI workflow.
+- **`npm test` runs `aci verify`; the site-stage preset is gone** — the
+  scaffold's `npm test` now ends with `npm run verify`, which is
+  `aci verify --build`. To adopt it in
+  an existing site, add `"verify": "aci verify --build"` and append
+  `&& npm run verify` to your `test` script. `siteStagePreset`,
+  `runLocalSiteStage`, `siteStageProblem` and `testUnit` are no longer
+  exported from `@gradial/aci/testing`: delete `tests/aci-platform.test.mjs`
+  and the `playwright` devDependency if you added them. The browser-driven
+  `livePage` and `rootIdentity` platform tests no longer run anywhere.
 - **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
@@ -69,10 +155,13 @@
   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.
+  There is no build gate. `next build` and `astro build` do not run the check.
+  The signals are `npm test` in your repository, where the conformance check
+  renders every registered component in isolation and `aci verify` renders
+  every page, and publish, which rejects a release when a rendered block has no
+  root identity. A component the conformance check cannot load or render is
+  reported as not run, never as a failure; `aci verify` and publish still check
+  the pages that use it.
 - 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).
@@ -245,7 +334,6 @@ below) — delete it from any imports.
 - `visitorProfileDataModel`: the schema had no server-side document contract
   and no consumers. Drop it from imports; `audienceDataModels` no longer
   includes it.
-
 ## 0.1.52-rc.7 - 2026-08-19
 
 ### Fixed

package/README.md

@@ -1,6 +1,6 @@
 # Agentic Content Infrastructure SDK
 
-`@gradial/aci` `0.1.53-rc.7` is a pre-1.0 public-surface reset for the ACI
+`@gradial/aci` `0.2.0-canary.715` 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.7 zod@^4
+npm install @gradial/aci@0.2.0-canary.715 zod@^4
 ```
 
 ## Root Import
@@ -72,23 +72,27 @@ including the `blog_body` contract pattern for page-specific container children.
 ## Block Root Identity
 
 The renderer passes every block two props, `data-aci-block` (the authored
-block id) and `data-aci-component`. A component extends `RootIdentityProps`
-and spreads the rest of its props onto its root element, so analytics can join
-events to content by (page path, block id):
+block id) and `data-aci-component`. A component extends `AciRootProps` and
+places exactly those props on its root element with `aciRootAttrs(props)`, so
+analytics can join events to content by (page path, block id):
 
 ```tsx
-import type { RootIdentityProps } from '@gradial/aci';
+import { aciRootAttrs, type AciRootProps } from '@gradial/aci';
 
-export function StatsBar({ stats = [], ...root }: ContentProps & RootIdentityProps) {
-  return <section {...root} className="…">…</section>;
+export function StatsBar(props: ContentProps & AciRootProps) {
+  const { stats = [] } = props;
+  return <section {...aciRootAttrs(props)} className="…">…</section>;
 }
 ```
 
-Three checks make this required: `createRegistry` fails typecheck for a
-component whose props type lacks the keys, the default `rootIdentity`
-conformance check renders every registered component and fails when the root
-lacks the attributes, and publish rejects a release whose rendered HTML is
-missing a block id. `runConformanceChecks` is async; `await` it before reading
+`RootIdentityProps` is the former name of `AciRootProps`, and a rest-spread
+(`{ stats, ...root }`, then `{...root}` on the root) still works. Three checks
+make this required: `createRegistry` fails typecheck for a component whose
+props type lacks the keys; the default `rootIdentity` conformance check (and,
+on Astro, `astro build` through `withAci()`) renders every registered
+component in isolation and fails naming its source file; and `aci verify` and
+publish run the `@gradial/aci/verify` `blocks` check over every rendered page.
+`runConformanceChecks` is async; `await` it before reading
 `.passed`.
 
 ## Mintlify
@@ -137,13 +141,13 @@ host bundles select and serve immutable release artifacts.
 The first RC scaffold path is Next:
 
 ```bash
-npx @gradial/aci@0.1.53-rc.7 init my-site --template next-starter
+npx @gradial/aci@0.2.0-canary.715 init my-site --template next-starter
 ```
 
 List available templates:
 
 ```bash
-npx @gradial/aci@0.1.53-rc.7 init --list
+npx @gradial/aci@0.2.0-canary.715 init --list
 ```
 
 ## Personalization: The One-Tag Install

package/dist/astro/index.d.ts

@@ -11,12 +11,15 @@ interface AstroConfigSetupParams {
 }
 interface AstroBuildDoneParams {
     dir: URL;
+    logger?: {
+        info(message: string): void;
+    };
 }
 export interface AstroIntegrationLike {
     name: string;
     hooks: {
         'astro:config:setup'(params: AstroConfigSetupParams): void;
-        'astro:build:done'?(params: AstroBuildDoneParams): void;
+        'astro:build:done'?(params: AstroBuildDoneParams): void | Promise<void>;
     };
 }
 /**

package/dist/cli/compile-registry.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { realpathSync } from 'node:fs';
+import { readFileSync, realpathSync } from 'node:fs';
 import { mkdir, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
@@ -96,6 +96,9 @@ async function compileRegistry(options) {
     }
     const registry = {
         manifestVersion: '1',
+        // The installed SDK that built this artifact (ADR 0063): publish asks only
+        // whether it is recent enough to have produced a platform test's outcome.
+        sdkVersion: installedSDKVersion(),
         generatedAt: new Date().toISOString(),
         components: componentEntries,
         dataModels: dataModelEntries,
@@ -106,6 +109,10 @@ async function compileRegistry(options) {
     schemaFiles.push(pageSchemaPath);
     return { registry: registryPath, schemas: schemaFiles };
 }
+function installedSDKVersion() {
+    const manifest = JSON.parse(readFileSync(new URL('../../package.json', import.meta.url), 'utf8'));
+    return manifest.version;
+}
 async function loadDefaultArray(modulePath, label) {
     const mod = await import(pathToFileURL(path.resolve(modulePath)).href);
     const value = mod.default ?? mod.registry ?? mod.components ?? mod.dataModels;

package/dist/cli/materialize-template.mjs

@@ -17,7 +17,7 @@ const EXCLUDE_PATTERNS = [
     /storybook-static/,
     /starter-content/,
 ];
-const COMMON_DIRS = ['.aci', '.agents', '.content', 'eslint-rules'];
+const COMMON_DIRS = ['.aci', '.agents', '.content', 'eslint-rules', '.github'];
 const COMMON_ROOT_FILES = ['.nvmrc'];
 // Per-framework values rendered into shared templates (e.g. README.md.tmpl).
 // Derived here so `aci init` and `generate-starters` can never disagree.

package/dist/content/component-block.js

@@ -1,5 +1,5 @@
 // The content compiler's component-block rule, shared by rendering (root
-// identity, slot resolution) and the rootIdentity conformance check.
+// identity, slot resolution), the verify `blocks` check and conformance.
 /**
  * The content compiler's block predicate (`compiler.IsComponentBlock`): an
  * explicit `$type: "component"` marker, or a non-empty string `component`

package/dist/internal/release-marker.d.ts

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

package/dist/internal/release-marker.js

@@ -0,0 +1,11 @@
+/**
+ * The release marker: `<meta name="aci-release" content="<releaseId>">`,
+ * written by the platform on every page of a release, never by the site.
+ * Publish injects it into every HTML page of an SSG release; the SDK's SSR
+ * page writes it per request from the release the router dispatched to. The
+ * platform's checks read it to know which release produced the HTML they
+ * judged, whatever an edge cached (hosting I-27). Pinned with the platform by
+ * internal/domain/publish/pageverify/testdata/platform-paths.v1.json.
+ * @internal
+ */
+export const RELEASE_MARKER = 'aci-release';

package/dist/next/config.js

@@ -3,6 +3,7 @@ import { join, relative } from 'path';
 import { createRequire } from 'module';
 import { createContentWatchWebpackPlugin } from './content-watch.js';
 import { buildErrorSeatPayload } from './error-seat-payload.js';
+import { withPlatformTraced } from './platform-tracing.js';
 import { defaultErrorPageFragmentHtml } from '../content/default-error-page.js';
 const require = createRequire(import.meta.url);
 export function withAci(nextConfig = {}, options = {}) {
@@ -35,6 +36,7 @@ export function withAci(nextConfig = {}, options = {}) {
         ...nextConfig,
         output: 'standalone',
         outputFileTracingRoot: nextConfig.outputFileTracingRoot ?? process.cwd(),
+        outputFileTracingIncludes: withPlatformTraced(nextConfig.outputFileTracingIncludes),
         headers: async () => {
             const gradialHeaders = [
                 {

package/dist/next/page.js

@@ -7,6 +7,7 @@ import { renderBlocks } from './render.js';
 import { AssignmentsScript } from './assignments-script.js';
 import { CollectScript } from './collect-script.js';
 import { renderProofContentFor } from '../internal/render-proof.js';
+import { RELEASE_MARKER } from '../internal/release-marker.js';
 import { parseHostedPageTarget } from './hosted-page-target.js';
 /**
  * Creates the catch-all route handler for a Next.js ACI site.
@@ -88,7 +89,7 @@ export function createPage(registry, options) {
             }));
             return (_jsxs(_Fragment, { children: [renderedSlots.filter(Boolean), _jsx(AssignmentsScript, { page: input.page }), _jsx(CollectScript, { siteConfig: input.siteConfig }), renderProofContent
                         ? _jsx("meta", { name: "aci-render-proof", content: renderProofContent })
-                        : null] }));
+                        : null, releaseId ? _jsx("meta", { name: RELEASE_MARKER, content: releaseId }) : null] }));
         }
         catch (error) {
             if (error instanceof PageNotFoundError)

package/dist/next/platform-tracing.d.ts

@@ -0,0 +1,10 @@
+import type { NextConfig } from 'next';
+/**
+ * The SDK entries the platform loads from a Next site's standalone tree: the
+ * capsule's page harness imports `./render` (page_sdk.mjs) and the publish
+ * verify host imports `./verify` (verify_suite.mjs). No server code imports
+ * either, so Next's file tracing would prune them.
+ */
+export declare const PLATFORM_ENTRIES: readonly ["./render", "./verify"];
+export declare const PLATFORM_TRACED_FILES: string[];
+export declare function withPlatformTraced(includes: NextConfig['outputFileTracingIncludes']): NonNullable<NextConfig['outputFileTracingIncludes']>;

package/dist/next/platform-tracing.js

@@ -0,0 +1,24 @@
+/**
+ * The SDK entries the platform loads from a Next site's standalone tree: the
+ * capsule's page harness imports `./render` (page_sdk.mjs) and the publish
+ * verify host imports `./verify` (verify_suite.mjs). No server code imports
+ * either, so Next's file tracing would prune them.
+ */
+export const PLATFORM_ENTRIES = ['./render', './verify'];
+// The import closure of PLATFORM_ENTRIES, as dist globs, plus the package
+// manifest that resolves the exports (and that sdkVersion reads).
+// platform-tracing.test.ts walks the closure from the sources and fails on
+// any file these globs miss.
+export const PLATFORM_TRACED_FILES = [
+    './node_modules/@gradial/aci/package.json',
+    './node_modules/@gradial/aci/dist/render/**/*.js',
+    './node_modules/@gradial/aci/dist/runtime/**/*.js',
+    './node_modules/@gradial/aci/dist/verify/**/*.js',
+    './node_modules/@gradial/aci/dist/content/component-block.js',
+    './node_modules/@gradial/aci/dist/collect/aci.js',
+    './node_modules/@gradial/aci/dist/internal/release-marker.js',
+];
+export function withPlatformTraced(includes) {
+    const all = includes ?? {};
+    return { ...all, '/**': [...(all['/**'] ?? []), ...PLATFORM_TRACED_FILES] };
+}

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

@@ -1,6 +1,7 @@
 /**
  * The root-identity judgement conformance runs over a site's renders
- * (`./testing`, site-check.ts).
+ * (`./testing`, site-check.ts). Publish and `aci verify` judge root identity
+ * through the verify `blocks` check instead, which reads parsed tags.
  */
 export { collectComponentBlocks, isComponentBlock, type ComponentBlock } from '../content/component-block.js';
 export type TestVerdict = 'pass' | 'fail' | 'not-run';

package/dist/platform-tests/index.js

@@ -1,6 +1,7 @@
 /**
  * The root-identity judgement conformance runs over a site's renders
- * (`./testing`, site-check.ts).
+ * (`./testing`, site-check.ts). Publish and `aci verify` judge root identity
+ * through the verify `blocks` check instead, which reads parsed tags.
  */
 import { collectComponentBlocks } from '../content/component-block.js';
 export { collectComponentBlocks, isComponentBlock } from '../content/component-block.js';

package/dist/render/astro.d.ts

@@ -0,0 +1,2 @@
+import type { FrameworkAdapter } from './types.js';
+export declare const astroAdapter: FrameworkAdapter;

package/dist/render/astro.js

@@ -0,0 +1,88 @@
+import { existsSync } from 'node:fs';
+import http from 'node:http';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { RenderError } from './errors.js';
+import { GRADIAL_RENDER_INPUT_HEADER, astroRoute, renderInputFor, withPendingInput } from './input.js';
+const SERVER_ENTRIES = ['dist/server/entry.mjs', 'dist-astro/server/entry.mjs'];
+// The handler's own no-match fallback body; never an authored page.
+const NOT_FOUND_BODY = 'not found';
+function astroServerEntry(siteRoot) {
+    const entry = SERVER_ENTRIES.map((rel) => path.join(siteRoot, rel)).find((file) => existsSync(file));
+    if (!entry) {
+        throw new Error(`Astro server entry was not found under ${siteRoot} (looked for ${SERVER_ENTRIES.join(', ')})`);
+    }
+    return entry;
+}
+async function loadHandler(entryPath) {
+    const entry = (await import(pathToFileURL(entryPath).href));
+    const handler = entry.handler ?? entry.default ?? entry.start;
+    if (typeof handler !== 'function') {
+        throw new Error(`Astro server entry ${entryPath} must export handler`);
+    }
+    return handler;
+}
+async function listen(handler) {
+    const server = http.createServer((req, res) => {
+        const next = (error) => {
+            res.statusCode = error ? 500 : 404;
+            res.end(error ? (error instanceof Error ? error.message : String(error)) : NOT_FOUND_BODY);
+        };
+        const pending = handler(req, res, next, {});
+        if (pending && typeof pending.catch === 'function')
+            pending.catch(next);
+    });
+    await new Promise((resolve, reject) => {
+        server.once('error', reject);
+        server.listen(0, '127.0.0.1', resolve);
+    });
+    const { port } = server.address();
+    return { server, baseURL: `http://127.0.0.1:${port}` };
+}
+/**
+ * Binding `/404/` collides with Astro's native 404 seat (D-11): the server
+ * answers the direct route with the authored page and status 404. That is a
+ * successful render of a page served with 200 (the static artifact), so the
+ * render answers 200, as the Next renderer does for the same page.
+ */
+function isAuthoredNotFoundPage(route, status, html) {
+    const body = html.trim();
+    return status === 404 && route === '/404/' && body !== '' && body !== NOT_FOUND_BODY;
+}
+async function start(options) {
+    process.chdir(options.siteRoot);
+    Object.assign(process.env, { NODE_ENV: 'production', ACI_PAGE_RUNTIME: '1' });
+    const { server, baseURL } = await listen(await loadHandler(astroServerEntry(options.siteRoot)));
+    async function render(page) {
+        const route = astroRoute(page.route);
+        const input = renderInputFor(page, route);
+        return withPendingInput(input, async (inputID) => {
+            const response = await fetch(new URL(route, baseURL), { headers: { [GRADIAL_RENDER_INPUT_HEADER]: inputID } });
+            const html = await response.text();
+            if (!response.ok && !isAuthoredNotFoundPage(route, response.status, html)) {
+                throw new RenderError('render.status', route, `astro page runtime ${route} returned ${response.status}: ${html.slice(0, 500)}`, {
+                    variantKey: page.variantKey,
+                });
+            }
+            if (!html.trim()) {
+                throw new RenderError('render.empty', route, `astro page runtime ${route} returned empty HTML`, { variantKey: page.variantKey });
+            }
+            return { html, status: isAuthoredNotFoundPage(route, response.status, html) ? 200 : response.status };
+        });
+    }
+    return {
+        render,
+        close: () => new Promise((resolve) => server.close(() => resolve())),
+    };
+}
+/** Importing the entry makes Node resolve the bundle's whole import graph. */
+async function check(options) {
+    try {
+        await import(pathToFileURL(astroServerEntry(options.siteRoot)).href);
+        return [];
+    }
+    catch (error) {
+        return [`import astro server entry: ${error instanceof Error ? error.message : String(error)}`];
+    }
+}
+export const astroAdapter = { start, check };

package/dist/render/errors.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Why one page failed to render. Codes are stable "render.<reason>" strings:
+ *
+ * - render.input      the compiled payload cannot drive this framework's render
+ * - render.threw      the framework handler threw
+ * - render.status     the framework answered with a non-2xx status (a redirect
+ *                     still pending after the allowed hops counts)
+ * - render.empty      the framework answered 2xx with an empty document
+ * - render.timeout    the framework did not answer in time
+ */
+export declare const RENDER_ERROR_CODES: readonly ["render.input", "render.threw", "render.status", "render.empty", "render.timeout"];
+export type RenderErrorCode = (typeof RENDER_ERROR_CODES)[number];
+export declare class RenderError extends Error {
+    readonly code: RenderErrorCode;
+    readonly route: string;
+    readonly variantKey?: string;
+    constructor(code: RenderErrorCode, route: string, message: string, options?: {
+        variantKey?: string;
+        cause?: unknown;
+    });
+}
+/** Wraps anything a framework threw as render.threw, keeping RenderErrors as they are. */
+export declare function asRenderError(error: unknown, route: string, variantKey: string | undefined): RenderError;

package/dist/render/errors.js

@@ -0,0 +1,31 @@
+/**
+ * Why one page failed to render. Codes are stable "render.<reason>" strings:
+ *
+ * - render.input      the compiled payload cannot drive this framework's render
+ * - render.threw      the framework handler threw
+ * - render.status     the framework answered with a non-2xx status (a redirect
+ *                     still pending after the allowed hops counts)
+ * - render.empty      the framework answered 2xx with an empty document
+ * - render.timeout    the framework did not answer in time
+ */
+export const RENDER_ERROR_CODES = ['render.input', 'render.threw', 'render.status', 'render.empty', 'render.timeout'];
+export class RenderError extends Error {
+    code;
+    route;
+    variantKey;
+    constructor(code, route, message, options = {}) {
+        super(message, options.cause === undefined ? undefined : { cause: options.cause });
+        this.name = 'RenderError';
+        this.code = code;
+        this.route = route;
+        if (options.variantKey !== undefined)
+            this.variantKey = options.variantKey;
+    }
+}
+/** Wraps anything a framework threw as render.threw, keeping RenderErrors as they are. */
+export function asRenderError(error, route, variantKey) {
+    if (error instanceof RenderError)
+        return error;
+    const message = error instanceof Error ? error.message : String(error);
+    return new RenderError('render.threw', route, message, { variantKey, cause: error });
+}

package/dist/render/index.d.ts

@@ -0,0 +1,22 @@
+import type { RenderFramework, Renderer, RendererOptions } from './types.js';
+export { RenderError } from './errors.js';
+export type { RenderErrorCode } from './errors.js';
+export type { RenderFramework, RenderPage, RenderPayload, RenderResult, Renderer, RendererOptions } from './types.js';
+/** One page render may not outlast this; the framework is left running. */
+export declare const RENDER_TIMEOUT_MS = 60000;
+/**
+ * Names the framework whose production build sits in siteRoot. The checks
+ * are each framework's own build marker, so exactly one matches a real build.
+ */
+export declare function detectFramework(options: Pick<RendererOptions, 'siteRoot' | 'contentRoot'>): RenderFramework;
+/**
+ * Starts the site's framework once and renders compiled pages through it.
+ * Every failure of one page rejects with a RenderError; startup failures
+ * reject createRenderer itself.
+ */
+export declare function createRenderer(options: RendererOptions): Promise<Renderer>;
+/**
+ * Proves the framework's runtime dependencies resolve from siteRoot without
+ * starting it. Returns one message per problem; empty means ready.
+ */
+export declare function checkRenderer(options: RendererOptions): Promise<string[]>;

package/dist/render/index.js

@@ -0,0 +1,73 @@
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { RenderError, asRenderError } from './errors.js';
+import { assertRenderPage } from './input.js';
+export { RenderError } from './errors.js';
+/** One page render may not outlast this; the framework is left running. */
+export const RENDER_TIMEOUT_MS = 60_000;
+// Loaded on demand: a site's runtime carries only its own framework's
+// dependencies (a Next standalone tree has no Mintlify projector).
+const ADAPTERS = {
+    next: async () => (await import('./next.js')).nextAdapter,
+    astro: async () => (await import('./astro.js')).astroAdapter,
+    mintlify: async () => (await import('./mintlify.js')).mintlifyAdapter,
+};
+/**
+ * Names the framework whose production build sits in siteRoot. The checks
+ * are each framework's own build marker, so exactly one matches a real build.
+ */
+export function detectFramework(options) {
+    const markers = [
+        ['mintlify', path.join(options.contentRoot, 'renderers', 'mintlify', 'docs.json')],
+        ['next', path.join(options.siteRoot, '.next', 'BUILD_ID')],
+        ['astro', path.join(options.siteRoot, 'dist', 'server', 'entry.mjs')],
+        ['astro', path.join(options.siteRoot, 'dist-astro', 'server', 'entry.mjs')],
+    ];
+    const found = markers.find(([, marker]) => existsSync(marker));
+    if (!found) {
+        throw new Error(`no Next, Astro or Mintlify production build found in ${options.siteRoot}; build the site first`);
+    }
+    return found[0];
+}
+function withDeadline(page, rendering) {
+    let timer;
+    const deadline = new Promise((_, reject) => {
+        timer = setTimeout(() => {
+            reject(new RenderError('render.timeout', page.route, `render of ${page.route} exceeded ${RENDER_TIMEOUT_MS / 1000}s`, {
+                variantKey: page.variantKey,
+            }));
+        }, RENDER_TIMEOUT_MS);
+    });
+    return Promise.race([rendering, deadline]).finally(() => clearTimeout(timer));
+}
+/**
+ * Starts the site's framework once and renders compiled pages through it.
+ * Every failure of one page rejects with a RenderError; startup failures
+ * reject createRenderer itself.
+ */
+export async function createRenderer(options) {
+    const adapter = await adapterFor(options);
+    const renderer = await adapter.start(options);
+    return {
+        async render(page) {
+            try {
+                assertRenderPage(page);
+                return await withDeadline(page, renderer.render(page));
+            }
+            catch (error) {
+                throw asRenderError(error, page.route, page.variantKey);
+            }
+        },
+        close: () => renderer.close(),
+    };
+}
+/**
+ * Proves the framework's runtime dependencies resolve from siteRoot without
+ * starting it. Returns one message per problem; empty means ready.
+ */
+export async function checkRenderer(options) {
+    return (await adapterFor(options)).check(options);
+}
+function adapterFor(options) {
+    return ADAPTERS[options.framework ?? detectFramework(options)]();
+}