@gradial/aci 0.1.46 → 0.1.47

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",

package/templates/astro/template/src/aci/error-page-instrumentation.mjs

@@ -0,0 +1,33 @@
+// Error-page analytics policy — THIS FILE IS YOURS (customer-owned;
+// code-organization R-14 / authorable-error-pages D-15). The ACI SDK owns
+// the delivery mechanism (when this runs, serialization, the
+// data-aci-error-page marker); this file owns WHAT is pushed.
+//
+// Contract:
+// - pushErrorPageView MUST stay self-contained: browser globals only — no
+//   imports, no closed-over identifiers. The Astro seats and the 500.html
+//   emitter execute it STRINGIFIED via toString(), so anything outside the
+//   function body is lost.
+// - Emptying the body to a no-op disables error-page analytics on every
+//   surface (404.astro, 500.astro, emitted static copies) — the sanctioned
+//   alternative to GTM-container-side suppression.
+// - Plain .mjs on purpose: it is consumed verbatim, never transpiled.
+
+/**
+ * Pushes one `page_view` event per error-surface view (D-14 default
+ * payload). `page_path` is the visitor's requested path, so 404 reports
+ * double as a broken-link inventory.
+ *
+ * @param {'not_found' | 'error'} pageType
+ */
+export function pushErrorPageView(pageType) {
+  window.dataLayer = window.dataLayer || [];
+  window.dataLayer.push({
+    event: 'page_view',
+    page_type: pageType,
+    page_path: window.location.pathname,
+    page_location: window.location.href,
+    page_referrer: document.referrer || '(direct)',
+    page_title: document.title,
+  });
+}

package/templates/astro/template/src/pages/404.astro

@@ -0,0 +1,54 @@
+---
+// Astro's native notFound error seat (authorable-error-pages REQ-7).
+// Renders the page bound by site.json#errorPages.notFound through the normal
+// SiteLayout path; static builds emit dist/404.html, which doubles as the
+// direct /404/ route and the error surface (D-11 — the instrumentation on a
+// direct visit is the accepted consequence). If the bound page cannot be
+// loaded, the SDK degrades to its shipped default fragment — this seat never
+// throws.
+import { getErrorPageData, createRenderChildren } from '@gradial/aci/astro';
+import { registry } from '../cms/registry';
+import SiteLayout from '../layouts/SiteLayout.astro';
+import { pushErrorPageView } from '../aci/error-page-instrumentation.mjs';
+
+const errorPage = await getErrorPageData(Astro, 'notFound', { pushErrorPageView });
+const data = errorPage.data;
+const renderChildren = createRenderChildren(registry);
+---
+
+<SiteLayout
+  title={errorPage.meta.title}
+  description={errorPage.meta.description}
+  canonical={errorPage.meta.canonical}
+  siteName={errorPage.meta.siteName}
+>
+  {data ? (
+    data.layout.slots.map((slot) => {
+      const blocks = data.slots[slot.name];
+      if (!blocks?.length) return null;
+      const rendered = renderChildren(blocks);
+      if (slot.name === 'main') {
+        return (
+          <main id="content-main">
+            {rendered.map((child) => {
+              const Comp = child.Component as any;
+              return Comp ? <Comp {...child.props} /> : null;
+            })}
+          </main>
+        );
+      }
+      return rendered.map((child) => {
+        const Comp = child.Component as any;
+        return Comp ? <Comp {...child.props} /> : null;
+      });
+    })
+  ) : (
+    <Fragment set:html={errorPage.fallbackHtml} />
+  )}
+  <!-- D-14 error-surface analytics: ONE page_view push with the visitor's
+       requested path. The push body is site-owned (D-15): the SDK serializes
+       src/aci/error-page-instrumentation.mjs into this tag, injected like
+       SiteLayout's collectTag; inline scripts execute here — Astro serves
+       real HTML documents (unlike the Next flight-rendered seat). -->
+  <Fragment set:html={errorPage.instrumentationTag} />
+</SiteLayout>

package/templates/astro/template/src/pages/500.astro

@@ -0,0 +1,53 @@
+---
+// Astro's native catchAll (500) error seat (authorable-error-pages REQ-7).
+// Renders the page bound by site.json#errorPages.catchAll through the normal
+// SiteLayout path. Static builds emit dist/500.html for the hosting layer;
+// server output serves this seat when a route throws during on-demand
+// rendering. If the bound page cannot be loaded, the SDK degrades to its
+// shipped default fragment — this seat never throws.
+import { getErrorPageData, createRenderChildren } from '@gradial/aci/astro';
+import { registry } from '../cms/registry';
+import SiteLayout from '../layouts/SiteLayout.astro';
+import { pushErrorPageView } from '../aci/error-page-instrumentation.mjs';
+
+const errorPage = await getErrorPageData(Astro, 'catchAll', { pushErrorPageView });
+const data = errorPage.data;
+const renderChildren = createRenderChildren(registry);
+---
+
+<SiteLayout
+  title={errorPage.meta.title}
+  description={errorPage.meta.description}
+  canonical={errorPage.meta.canonical}
+  siteName={errorPage.meta.siteName}
+>
+  {data ? (
+    data.layout.slots.map((slot) => {
+      const blocks = data.slots[slot.name];
+      if (!blocks?.length) return null;
+      const rendered = renderChildren(blocks);
+      if (slot.name === 'main') {
+        return (
+          <main id="content-main">
+            {rendered.map((child) => {
+              const Comp = child.Component as any;
+              return Comp ? <Comp {...child.props} /> : null;
+            })}
+          </main>
+        );
+      }
+      return rendered.map((child) => {
+        const Comp = child.Component as any;
+        return Comp ? <Comp {...child.props} /> : null;
+      });
+    })
+  ) : (
+    <Fragment set:html={errorPage.fallbackHtml} />
+  )}
+  <!-- D-14 error-surface analytics: ONE page_view push with the visitor's
+       requested path. The push body is site-owned (D-15): the SDK serializes
+       src/aci/error-page-instrumentation.mjs into this tag, injected like
+       SiteLayout's collectTag; inline scripts execute here — Astro serves
+       real HTML documents (unlike the Next flight-rendered seat). -->
+  <Fragment set:html={errorPage.instrumentationTag} />
+</SiteLayout>

package/templates/astro/template/src/pages/[...slug].astro

@@ -1,5 +1,5 @@
 ---
-import { getGradialStaticPaths, getPageData, createRenderChildren } from '@gradial/aci/astro';
+import { getGradialStaticPaths, getPageData, createRenderChildren, PageNotFoundError, type PageData } from '@gradial/aci/astro';
 import { registry } from '../cms/registry';
 import SiteLayout from '../layouts/SiteLayout.astro';
 
@@ -7,7 +7,20 @@ export const getStaticPaths = getGradialStaticPaths;
 
 // SDK owns route normalization, content loading, metadata, layout/slot
 // resolution, and collect-tag emission. No FileContentProvider imports.
-const data = await getPageData(Astro);
+//
+// Server output: unknown routes raise PageNotFoundError here; rewrite to the
+// 404 seat so misses answer HTTP 404, not 500 (authorable-error-pages D-10).
+// src/pages/404.astro is load-bearing for this rewrite — deleting it turns
+// every miss into a 500.
+// Static output never takes this branch — getStaticPaths only emits known
+// routes.
+let data: PageData;
+try {
+  data = await getPageData(Astro);
+} catch (error) {
+  if (error instanceof PageNotFoundError) return Astro.rewrite('/404/');
+  throw error;
+}
 const renderChildren = createRenderChildren(registry);
 ---
 

package/templates/common/.agents/skills/authoring/SKILL.md

@@ -238,6 +238,77 @@ Global elements (navigation, footer, branding, SEO) live in
 }
 ```
 
+### Error Pages
+
+Sites bind their error pages in `site.json` via `errorPages`:
+
+```json
+{
+  "errorPages": {
+    "notFound": "/404/",
+    "catchAll": "/error/"
+  }
+}
+```
+
+- Each binding is a route path resolving to an **ordinary content page**
+  (`.content/pages/404/_index.json`, `.content/pages/error/_index.json`) —
+  authored with normal layouts and components like any other page.
+  `notFound` serves unknown routes with HTTP 404; `catchAll` serves
+  application errors (500-class).
+- Error pages stay out of discovery: set `metadata.sitemap.visible: false`
+  on both pages, and the template `robots.txt` disallows both routes.
+- If `errorPages` is absent, the build warns loudly and ships a
+  branded-neutral default page (warn-then-enforce migration: absent
+  bindings will eventually fail the build, so author them). Present but
+  broken bindings — malformed paths, no matching page, unpublished page —
+  fail the build immediately.
+- Error pages are base-audience only: no personalization, audience, or
+  experiment overlays (validation rejects them), and collect/assignment
+  markup is stripped from materialized copies.
+- Analytics: error-surface renders push one `page_view` event to
+  `window.dataLayer` with `page_type` (`not_found` | `error`),
+  `page_path` (the visitor's requested path), `page_location`,
+  `page_referrer`, and `page_title`. The push body is site-owned
+  (`src/aci/error-page-instrumentation.mjs` — see the GTM/GA4 section
+  below); the SDK wrappers handle delivery.
+
+### Error-page analytics (GTM/GA4)
+
+The push body is YOURS: it lives in the site-owned
+`src/aci/error-page-instrumentation.mjs`, whose `pushErrorPageView`
+function every error surface (Next seats, Astro seats, the emitted static
+`500.html`) executes. The scaffolded default pushes one event to
+`window.dataLayer`:
+
+```js
+{ event: 'page_view', page_type: 'not_found' | 'error',
+  page_path, page_location, page_referrer, page_title }
+```
+
+- **Customize** — edit the function in place. It must stay self-contained
+  (browser globals only, no imports, no closed-over identifiers): some
+  surfaces execute it stringified.
+- **Disable** — make the function body a no-op. That turns off error-page
+  analytics on every surface, and no GTM-side suppression is needed.
+
+Container-side dedup is only needed when you KEEP the default push
+alongside automatic GA4 page views: because the event name is `page_view`,
+either disable `send_page_view` and drive all page views from the
+dataLayer, or add a trigger exception on the config tag for error
+surfaces. The stable suppression signal is the `data-aci-error-page`
+attribute (values `not_found` | `error`; the attribute is SDK-owned and
+stable regardless of what your push does): present on the instrumentation
+script tag (Astro, parse-time) and on a server-rendered marker element
+(Next, in the DOM before container load), so container-load triggers can
+gate on it in both frameworks. If you leave automatic page views on and
+also keep the default push, error pages will double-count — that is a
+container configuration choice, not an SDK default.
+
+Direct visits to `/404/` and `/error/` do not carry error context and do
+not push the event (Astro static output is the one exception: its
+`404.html` doubles as the direct route).
+
 ### ID Conventions
 
 - Every block must have a unique `id` within the page.