@gradial/aci 0.1.46 → 0.1.48

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

@@ -0,0 +1,57 @@
+import type { KernelPageBlock } from '../content/types.js';
+import type { ErrorPagePush } from '../content/error-page-kind.js';
+import type { Registry } from '../registry.js';
+/**
+ * Build-time serialization of the bound catchAll page (authorable-error-pages
+ * D-9): Next's error seat is client-only and cannot reach the server content
+ * provider, so withAci() resolves `site.json#errorPages.catchAll` while
+ * next.config is evaluated and injects the page's resolved slots into the
+ * bundle as the `__ACI_ERROR_PAGE__` webpack define (same mechanism as the
+ * middleware's `__ACI_PUBLIC_PATHS__`). Content edits to the bound page
+ * therefore require a code build — accepted by D-4.
+ */
+export interface ErrorSeatPayload {
+    /** True when no binding is authored: render the shipped default (REQ-4). */
+    defaulted: boolean;
+    /** Shipped branded-neutral default fragment — always present as last resort. */
+    defaultHtml: string;
+    route?: string;
+    title?: string;
+    /** Layout slot order, then resolved blocks per slot (fragments included). */
+    slotOrder?: string[];
+    slots?: Record<string, KernelPageBlock[]>;
+}
+/** The build-time serialized payload, or null when the define is absent. */
+export declare function errorSeatPayload(): ErrorSeatPayload | null;
+export interface ErrorSeatProps {
+    registry: Registry;
+    /** Next passes the boundary error; it is logged by Next, never rendered. */
+    error?: (Error & {
+        digest?: string;
+    }) | null;
+    /** Test seam: overrides the build-time serialization when provided. */
+    payload?: ErrorSeatPayload | null;
+    /**
+     * The tenant-owned policy module's push (D-15), forwarded to
+     * ErrorPageInstrumentation; omitted → the SDK default.
+     */
+    pushErrorPageView?: ErrorPagePush;
+}
+/**
+ * The Next app-error seat (`src/app/error.tsx` delegates here). Renders the
+ * bound catchAll page's serialized content entirely from the client bundle —
+ * no fetch, no content provider: the failing system is never re-entered
+ * (ANTI-2). Collect/assignment tags are stripped by construction (REQ-11):
+ * only content blocks are serialized and this renderer emits no script tags.
+ *
+ * Coverage (documented for operators): an error boundary catches render/
+ * lifecycle errors of route segments BELOW the root layout. It does NOT
+ * catch: errors in the root layout itself (Next's global-error seat),
+ * middleware failures, event-handler/async errors, or platform 5xx
+ * (crash/timeout/throttle) — the latter are covered by the emitted
+ * `public/500.html` where the hosting plan supports substitution (REQ-10).
+ *
+ * The seat must never throw: unknown serialized components are skipped, and
+ * a missing/defaulted payload renders the shipped default fragment.
+ */
+export declare function ErrorSeat({ registry, payload, pushErrorPageView }: ErrorSeatProps): import("react").JSX.Element;

package/dist/next/error-seat.js

@@ -0,0 +1,83 @@
+'use client';
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { Component, Fragment } from 'react';
+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. */
+export function errorSeatPayload() {
+    return typeof __ACI_ERROR_PAGE__ === 'undefined' ? null : __ACI_ERROR_PAGE__;
+}
+/**
+ * The Next app-error seat (`src/app/error.tsx` delegates here). Renders the
+ * bound catchAll page's serialized content entirely from the client bundle —
+ * no fetch, no content provider: the failing system is never re-entered
+ * (ANTI-2). Collect/assignment tags are stripped by construction (REQ-11):
+ * only content blocks are serialized and this renderer emits no script tags.
+ *
+ * Coverage (documented for operators): an error boundary catches render/
+ * lifecycle errors of route segments BELOW the root layout. It does NOT
+ * catch: errors in the root layout itself (Next's global-error seat),
+ * middleware failures, event-handler/async errors, or platform 5xx
+ * (crash/timeout/throttle) — the latter are covered by the emitted
+ * `public/500.html` where the hosting plan supports substitution (REQ-10).
+ *
+ * The seat must never throw: unknown serialized components are skipped, and
+ * a missing/defaulted payload renders the shipped default fragment.
+ */
+export function ErrorSeat({ registry, payload, pushErrorPageView }) {
+    const data = payload !== undefined ? payload : errorSeatPayload();
+    return (_jsxs(_Fragment, { children: [_jsx(PayloadBoundary, { fallbackHtml: data?.defaultHtml || LAST_RESORT_HTML, children: renderPayload(data, registry) }), _jsx(ErrorPageMarker, { kind: "catchAll" }), _jsx(ErrorPageInstrumentation, { kind: "catchAll", push: pushErrorPageView })] }));
+}
+/**
+ * The seat's own safety net (quorum RISK-004): the serialized payload renders
+ * arbitrary registry components, and one that throws at the error seat would
+ * otherwise take the whole seat down. This client error boundary catches the
+ * render failure and falls back to the shipped default HTML.
+ */
+class PayloadBoundary extends Component {
+    state = { failed: false };
+    static getDerivedStateFromError() {
+        return { failed: true };
+    }
+    render() {
+        if (this.state.failed) {
+            return _jsx("div", { dangerouslySetInnerHTML: { __html: this.props.fallbackHtml } });
+        }
+        return this.props.children;
+    }
+}
+const LAST_RESORT_HTML = '<main style="max-width:26rem;margin:0 auto;padding:4rem 1rem;text-align:center;font-family:system-ui,sans-serif">'
+    + '<h1 style="font-size:1.5rem">Something went wrong.</h1>'
+    + '<p>An unexpected error occurred while serving this page.</p>'
+    + '<a href="/">Back to homepage</a></main>';
+function renderPayload(data, registry) {
+    if (!data || data.defaulted || !data.slots || !data.slotOrder) {
+        return _jsx("div", { dangerouslySetInnerHTML: { __html: data?.defaultHtml || LAST_RESORT_HTML } });
+    }
+    return data.slotOrder.map((slotName) => {
+        const blocks = data.slots?.[slotName];
+        if (!blocks?.length)
+            return null;
+        const rendered = renderClientBlocks(blocks, registry);
+        if (slotName === 'main') {
+            return (_jsx("main", { id: "content-main", children: rendered }, "main"));
+        }
+        return _jsx(Fragment, { children: rendered }, slotName);
+    });
+}
+// A synchronous client-side mirror of next/render renderBlocks (that one is
+// async and server-oriented). Unknown components are skipped — the error
+// seat degrades, it never crashes.
+function renderClientBlocks(blocks, registry) {
+    return blocks.map((block) => {
+        const entry = registry.find((r) => r.id === block.component);
+        if (!entry)
+            return null;
+        const Component = entry.component;
+        const componentProps = { ...block.props };
+        if (entry.contract.blockSlots) {
+            componentProps.renderChildren = (children) => renderClientBlocks(children, registry);
+        }
+        return _jsx(Component, { ...componentProps }, block.id);
+    });
+}

package/dist/next/index.d.ts

@@ -7,3 +7,7 @@ export { PageNotFoundError, FragmentNotFoundError, LayoutNotFoundError } from '.
 export { CollectScript, type CollectScriptProps } from './collect-script.js';
 export { aciMiddlewareMatcher } from './middleware.js';
 export { AssignmentsScript, type AssignmentsScriptProps } from './assignments-script.js';
+export { createNotFound, renderPageForRoute, resolveErrorPage, type NextResolvedErrorPage, } from './error-pages.js';
+export { ErrorPageInstrumentation } from './error-page-instrumentation.js';
+export { ErrorPageMarker } from './error-page-marker.js';
+export { errorPageType, type ErrorPageType } from '../content/error-pages.js';

package/dist/next/index.js

@@ -7,3 +7,11 @@ export { PageNotFoundError, FragmentNotFoundError, LayoutNotFoundError } from '.
 export { CollectScript } from './collect-script.js';
 export { aciMiddlewareMatcher } from './middleware.js';
 export { AssignmentsScript } from './assignments-script.js';
+export { createNotFound, renderPageForRoute, resolveErrorPage, } from './error-pages.js';
+export { ErrorPageInstrumentation } from './error-page-instrumentation.js';
+export { ErrorPageMarker } from './error-page-marker.js';
+// Single definition of the kind→page_type mapping (quorum SIMPLE-005).
+export { errorPageType } from '../content/error-pages.js';
+// NOTE: ErrorSeat is deliberately NOT re-exported here — client components
+// (src/app/error.tsx) must import '@gradial/aci/next/error-seat', because
+// this barrel pulls server-only modules (next/headers).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gradial/aci",
-  "version": "0.1.46",
+  "version": "0.1.48",
   "repository": {
     "type": "git",
     "url": "https://github.com/gradial/bare-metal-go.git",
@@ -91,6 +91,11 @@
       "types": "./dist/next/dev-refresh.d.ts",
       "import": "./dist/next/dev-refresh.js"
     },
+    "./next/error-seat": {
+      "types": "./dist/next/error-seat.d.ts",
+      "import": "./dist/next/error-seat.js",
+      "default": "./dist/next/error-seat.js"
+    },
     "./next/server": {
       "types": "./dist/next/server.d.ts",
       "import": "./dist/next/server.js",
@@ -115,8 +120,9 @@
   },
   "scripts": {
     "build": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\" && tsc -p tsconfig.json && node scripts/assert-render-proof-public-surface.mjs && node scripts/build-collect.mjs",
-    "test": "node --import tsx --test \"src/**/*.test.ts\"",
+    "test": "node --import tsx --test \"src/**/*.test.ts\" \"src/**/*.test.tsx\"",
     "build:collect": "node scripts/build-collect.mjs",
+    "generate-default-error-page": "node scripts/generate-default-error-page.mjs",
     "build:cli": "cd ../.. && ./scripts/build-cli.sh",
     "generate-starters": "cd ../.. && tsx scripts/generate-starters.ts",
     "compile-registry": "tsx src/cli/compile-registry.mjs",
@@ -164,11 +170,11 @@
     "zod": "^4.0.0"
   },
   "optionalDependencies": {
-    "@gradial/aci-cli-darwin-arm64": "0.1.45",
-    "@gradial/aci-cli-darwin-x64": "0.1.45",
-    "@gradial/aci-cli-linux-arm64": "0.1.45",
-    "@gradial/aci-cli-linux-x64": "0.1.45",
-    "@gradial/aci-cli-win32-arm64": "0.1.45",
-    "@gradial/aci-cli-win32-x64": "0.1.45"
+    "@gradial/aci-cli-darwin-arm64": "0.1.48",
+    "@gradial/aci-cli-darwin-x64": "0.1.48",
+    "@gradial/aci-cli-linux-arm64": "0.1.48",
+    "@gradial/aci-cli-linux-x64": "0.1.48",
+    "@gradial/aci-cli-win32-arm64": "0.1.48",
+    "@gradial/aci-cli-win32-x64": "0.1.48"
   }
 }

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

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

package/templates/astro/template/package.json.tmpl

@@ -5,7 +5,7 @@
   "type": "module",
   "scripts": {
     "dev": "astro dev --host 0.0.0.0",
-    "build": "astro build",
+    "build": "node ./node_modules/@gradial/aci/src/cli/emit-error-pages.mjs prepare && astro build",
     "preview": "ACI_CONTENT_ROOT=./.aci/compiled astro preview --host 0.0.0.0",
     "typecheck": "ACI_CONTENT_ROOT=./.aci/compiled astro check --tsconfig ./tsconfig.json",
     "test": "node --import tsx --test tests/**/*.test.ts",