@gradial/aci 0.1.45 → 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/src/cli/validate-content.mjs

@@ -19,24 +19,21 @@
  * Uses the JSON schemas generated by compile-registry — portable, no React/CSS
  * imports needed, same schemas usable by Go backend or other tools.
  */
-import { realpathSync } from 'node:fs';
 import { readdir, readFile } from 'node:fs/promises';
 import path from 'node:path';
-import { fileURLToPath } from 'node:url';
-
-if (isMainModule()) {
-  const args = parseArgs(process.argv.slice(2));
-  try {
-    const result = await validateContent(args);
-    console.log(JSON.stringify(result, null, 2));
-    if (!result.success) process.exitCode = 1;
-  } catch (error) {
-    console.error(JSON.stringify({
-      success: false,
-      errors: [{ message: String(error?.message ?? error) }],
-    }, null, 2));
-    process.exitCode = 1;
-  }
+
+const args = parseArgs(process.argv.slice(2));
+
+try {
+  const result = await validateContent(args);
+  console.log(JSON.stringify(result, null, 2));
+  if (!result.success) process.exitCode = 1;
+} catch (error) {
+  console.error(JSON.stringify({
+    success: false,
+    errors: [{ message: String(error?.message ?? error) }],
+  }, null, 2));
+  process.exitCode = 1;
 }
 
 // ---------------------------------------------------------------------------
@@ -98,24 +95,6 @@ async function validateContent(options) {
     for (const block of blocks) {
       blocksValidated++;
 
-      if (!block || typeof block !== 'object') {
-        collector.push({
-          page: relativePath,
-          blockId: '<unknown>',
-          message: 'page region entry must be a component block',
-        });
-        continue;
-      }
-
-      if (block.$type !== 'component') {
-        collector.push({
-          page: relativePath,
-          blockId: block.id ?? '<unknown>',
-          path: '$type',
-          message: 'block "$type" must be "component"',
-        });
-      }
-
       if (!block.component) {
         collector.push({
           page: relativePath,
@@ -401,13 +380,6 @@ function validateNestedSlots(parentBlock, componentMap, schemaMap, path = 'props
         issues.push({ path: nestedPath, message: `${parentBlock.component}: block ref child must be a block` });
         continue;
       }
-      if (nestedBlock.$type !== 'component') {
-        issues.push({
-          path: `${nestedPath}.$type`,
-          message: `${parentBlock.component}: block ref child "$type" must be "component"`,
-        });
-        continue;
-      }
 
       if (!componentMap.has(nestedBlock.component)) {
         issues.push({ path: `${nestedPath}.component`, message: `${parentBlock.component}: unknown nested component "${nestedBlock.component}"` });
@@ -478,14 +450,3 @@ function parseArgs(argv) {
   }
   return out;
 }
-
-function isMainModule() {
-  if (!process.argv[1]) return false;
-  try {
-    return realpathSync(fileURLToPath(import.meta.url)) === realpathSync(path.resolve(process.argv[1]));
-  } catch {
-    return false;
-  }
-}
-
-export { validateContent };

package/src/cli/verify-next-cdn-routes.mjs

@@ -71,6 +71,12 @@ checkMissing(
   'The root catch-all handles release-scoped rewrites. Do not create a separate __r route folder.',
 );
 
+checkMissing(
+  'platform-owned collect route is absent',
+  'src/app/collect/route.ts',
+  'ACI injects the reserved /collect function during Vercel Build Output composition; customer source must not own it.',
+);
+
 checkFile(
   'next.config uses withAci',
   'next.config.mjs',

package/src/types/block-ref.ts

@@ -9,7 +9,6 @@ export interface BlockRefMeta {
 }
 
 const blockRefBase = z.object({
-  $type: z.literal('component'),
   id: z.string().min(1),
   component: z.string().min(1),
   props: z.record(z.string(), z.unknown()),
@@ -22,7 +21,6 @@ type InferContractProps<T> = T extends ComponentContract<string, infer Schema>
 type InferContractId<T> = T extends ComponentContract<infer Id, unknown> ? Id : never;
 
 export type BlockRefEntry<T extends ComponentContract> = {
-  $type: 'component';
   id: string;
   component: InferContractId<T>;
   props: InferContractProps<T>;

package/templates/astro/starter-content/src/fixtures/atomicBlocks.ts

@@ -13,18 +13,17 @@ export const atomicBlockStoryFixtures: AtomicBlockStoryFixture[] = [
     storybookId: 'core-atomic-blocks-button--variants',
     title: 'Button / All Variants',
     block: {
-      $type: 'component',
       id: 'fixture-button-variants',
       component: 'container',
       props: {
         theme: 'auto',
         blocks: [
-          { $type: 'component', id: 'btn-primary', component: 'button', props: { label: 'Primary button', href: '#', variant: 'primary' } },
-          { $type: 'component', id: 'btn-secondary', component: 'button', props: { label: 'Secondary button', href: '#', variant: 'secondary' } },
-          { $type: 'component', id: 'btn-tertiary', component: 'button', props: { label: 'Tertiary button', href: '#', variant: 'tertiary' } },
-          { $type: 'component', id: 'btn-icon-before', component: 'button', props: { label: 'Icon before', href: '#', variant: 'primary', icon: 'arrow-right', iconPosition: 'before' } },
-          { $type: 'component', id: 'btn-icon-after', component: 'button', props: { label: 'Icon after', href: '#', variant: 'secondary', icon: 'arrow-right', iconPosition: 'after' } },
-          { $type: 'component', id: 'btn-new-window', component: 'button', props: { label: 'Opens in new tab', href: 'https://example.com', variant: 'primary', newWindow: true, icon: 'arrow-right', iconPosition: 'after' } }
+          { id: 'btn-primary', component: 'button', props: { label: 'Primary button', href: '#', variant: 'primary' } },
+          { id: 'btn-secondary', component: 'button', props: { label: 'Secondary button', href: '#', variant: 'secondary' } },
+          { id: 'btn-tertiary', component: 'button', props: { label: 'Tertiary button', href: '#', variant: 'tertiary' } },
+          { id: 'btn-icon-before', component: 'button', props: { label: 'Icon before', href: '#', variant: 'primary', icon: 'arrow-right', iconPosition: 'before' } },
+          { id: 'btn-icon-after', component: 'button', props: { label: 'Icon after', href: '#', variant: 'secondary', icon: 'arrow-right', iconPosition: 'after' } },
+          { id: 'btn-new-window', component: 'button', props: { label: 'Opens in new tab', href: 'https://example.com', variant: 'primary', newWindow: true, icon: 'arrow-right', iconPosition: 'after' } }
         ]
       }
     }

package/templates/astro/starter-content/src/fixtures/composition.ts

@@ -14,15 +14,14 @@ export const compositionStoryFixtures: CompositionStoryFixture[] = [
     storybookId: 'composition-container--buttons',
     title: 'Container / Buttons',
     block: {
-      $type: 'component',
       id: 'fixture-container-buttons',
       component: 'container',
       props: {
         theme: 'auto',
         className: 'space-y-4',
         blocks: [
-          { $type: 'component', id: 'btn-1', component: 'button', props: { label: 'Primary action', href: '#', variant: 'primary', icon: 'arrow_forward', iconPosition: 'after' } },
-          { $type: 'component', id: 'btn-2', component: 'button', props: { label: 'Secondary action', href: '#', variant: 'secondary' } }
+          { id: 'btn-1', component: 'button', props: { label: 'Primary action', href: '#', variant: 'primary', icon: 'arrow_forward', iconPosition: 'after' } },
+          { id: 'btn-2', component: 'button', props: { label: 'Secondary action', href: '#', variant: 'secondary' } }
         ]
       }
     }

package/templates/astro/starter-content/src/fixtures/sections.ts

@@ -14,7 +14,6 @@ export const sectionStoryFixtures: SectionStoryFixture[] = [
     storybookId: 'sections-home-hero--default',
     title: 'Home Hero',
     block: {
-      $type: 'component',
       id: 'fixture-home-hero',
       component: 'home_hero',
       props: {
@@ -23,7 +22,7 @@ export const sectionStoryFixtures: SectionStoryFixture[] = [
         description: 'One content model, three renderers. Build once in Next.js, Astro, and SvelteKit—then prove parity with shared fixtures.',
         ctaLabel: 'Get started',
         ctaHref: '/docs',
-        image: {
+          image: {
           $type: 'gradial.image',
           assetId: 'fixture_seattle',
           versionId: 'v0001',

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,
+  });
+}