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

package/CHANGELOG.md

@@ -2,8 +2,20 @@
 
 ## Unreleased
 
+### Fixed
+
+- Astro authored 404/500 helpers use the shared `getPageData` pipeline and
+  consume the selected render input during ACI
+  preview/publish, preserving authored content and styling in code artifacts
+  without compiled content snapshots. Unrelated or personalized inputs cannot
+  replace the bound base error page.
+
 ### Added
 
+- Optional Node-only `src/aci/hosting-error-page.mjs` policy adds site-specific
+  browser bootstrap code to the SDK-owned static 500 fallback, with syntax
+  validation, script-data escaping, and the shared output-size budget.
+
 - Public `aci schemas compile` and `aci error-pages prepare|emit` commands let
   site build scripts compile code-owned artifacts without invoking SDK internals.
 

package/README.md

@@ -1,6 +1,6 @@
 # Agentic Content Infrastructure SDK
 
-`@gradial/aci` `0.1.53-rc.4` is a pre-1.0 public-surface reset for the ACI
+`@gradial/aci` `0.1.53-rc.6` 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.4 zod@^4
+npm install @gradial/aci@0.1.53-rc.6 zod@^4
 ```
 
 ## Root Import
@@ -137,13 +137,13 @@ host bundles select and serve immutable release artifacts.
 The first RC scaffold path is Next:
 
 ```bash
-npx @gradial/aci@0.1.53-rc.4 init my-site --template next-starter
+npx @gradial/aci@0.1.53-rc.6 init my-site --template next-starter
 ```
 
 List available templates:
 
 ```bash
-npx @gradial/aci@0.1.53-rc.4 init --list
+npx @gradial/aci@0.1.53-rc.6 init --list
 ```
 
 ## Personalization: The One-Tag Install
@@ -245,3 +245,37 @@ recompiles contracts without reading authored content. The error commands prepar
 code-owned analytics policy and emit the default hosting fallback (preserving a
 site-owned `public/500.html`). All three honor `--site-dir`; helper failures exit
 nonzero. Local development/content validation must explicitly compile content.
+
+## Hosting error-page policy
+
+`aci error-pages emit` owns the static `public/500.html` fallback. To add a
+site-specific analytics/consent bootstrap without recreating its HTML emitter,
+create a **Node-only build module** at `src/aci/hosting-error-page.mjs`:
+
+```js
+/** @type {import('@gradial/aci/content').HostingErrorPageScript} */
+export const hostingErrorPageScript = async ({ kind, pageType }) => {
+  // Return bundled browser JavaScript, or an empty string for no bootstrap.
+  return '';
+};
+```
+
+The hook receives `{ kind: 'catchAll', pageType: 'error' }`. It runs at build
+time, may import build helpers, and must return self-contained classic browser
+JavaScript. It must not read authored content or select an authored error page.
+Keep consent decisions and vendor-specific behavior in the site policy. It
+must not repeat the error-view push: the SDK emits that first from the existing
+client-safe `src/aci/error-page-instrumentation.mjs` policy.
+
+The SDK checks script syntax, escapes HTML script-data delimiters, appends a
+separate `data-aci-error-page-bootstrap="error"` script, and enforces a combined
+150 KiB HTML budget. Invalid present policies fail the build before replacing
+the previous generated fallback. A missing module adds no bootstrap. An existing
+unmarked site-owned `public/500.html` is left untouched. This hook affects the
+native hosting fallback only; it does not add loaders to authored CDN errors or
+change the instrumentation capsule consumed by publish.
+
+When replacing a site-local generator, delete its old ignored generated
+`public/500.html` once so it can become SDK-managed. Remove the generator from
+build scripts, retain any shared consent-bundle preparation needed by other
+static routes, and run `aci error-pages emit` as the final build step.

package/dist/astro/error-page.d.ts

@@ -48,8 +48,9 @@ export interface AstroErrorPageData {
  * error seats (`404.astro` / `500.astro`). `astro` is the seat's Astro
  * global; the bound route's content is loaded as if it were the requested
  * route, so static builds emit it into `dist/404.html`/`dist/500.html` and
- * server output renders it at error time from local compiled content — no
- * CMS fetch on the failing path (ANTI-2).
+ * ACI renders use the already resolved input for the bound base page;
+ * local static builds use compiled authoring content. Neither path fetches
+ * CMS content on a failure (ANTI-2).
  */
 export declare function getErrorPageData(astro: AstroGlobal, kind: ErrorPageKind, options?: {
     pushErrorPageView?: ErrorPagePush;

package/dist/astro/error-page.js

@@ -17,7 +17,7 @@
  * returned page data always carries empty collect/assignment tags.
  */
 import { getPageData } from './page.js';
-import { defaultPushErrorPageView, errorPageType, resolveErrorPage, serializeErrorPageInstrumentation, } from '../content/error-pages.js';
+import { defaultPushErrorPageView, errorPageType, serializeErrorPageInstrumentation, } from '../content/error-pages.js';
 import { defaultErrorPageFragmentHtml } from '../content/default-error-page.js';
 const FALLBACK_META = {
     notFound: {
@@ -34,37 +34,23 @@ const FALLBACK_META = {
  * error seats (`404.astro` / `500.astro`). `astro` is the seat's Astro
  * global; the bound route's content is loaded as if it were the requested
  * route, so static builds emit it into `dist/404.html`/`dist/500.html` and
- * server output renders it at error time from local compiled content — no
- * CMS fetch on the failing path (ANTI-2).
+ * ACI renders use the already resolved input for the bound base page;
+ * local static builds use compiled authoring content. Neither path fetches
+ * CMS content on a failure (ANTI-2).
  */
 export async function getErrorPageData(astro, kind, options = {}) {
     const pageType = errorPageType(kind);
     const instrumentationTag = serializeErrorPageInstrumentation(options.pushErrorPageView ?? defaultPushErrorPageView, kind);
     try {
-        const { FileContentProvider } = await import('../providers/file.js');
-        const siteConfig = await new FileContentProvider().getSiteConfig();
-        const resolved = await resolveErrorPage(kind, siteConfig);
-        for (const warning of resolved.warnings) {
-            console.warn(`[aci error-pages] ${warning}`);
-        }
-        if (resolved.route) {
-            const slug = resolved.route.replace(/^\/+|\/+$/g, '');
-            const data = await getPageData({
-                isPrerendered: astro.isPrerendered,
-                params: { slug },
-                request: astro.request,
-                url: astro.url,
-            });
-            return {
-                kind,
-                pageType,
-                instrumentationTag,
-                // Base audience, no personalization on error surfaces (REQ-11).
-                data: { ...data, collectTag: '', assignmentsTag: '' },
-                fallbackHtml: null,
-                meta: data.meta,
-            };
-        }
+        const data = await getPageData(astro, { errorPageKind: kind });
+        return {
+            kind,
+            pageType,
+            instrumentationTag,
+            data,
+            fallbackHtml: null,
+            meta: data.meta,
+        };
     }
     catch (error) {
         console.warn(`[aci error-pages] bound ${kind} page failed to load; serving the shipped default: ${String(error)}`);

package/dist/astro/page.d.ts

@@ -32,6 +32,7 @@
  */
 import type { KernelPage, KernelSiteConfig, KernelRouteMetadata, KernelPageBlock } from '../content/types.js';
 import { type LayoutEntry } from '../content/provider.js';
+import { type ErrorPageKind } from '../content/error-pages.js';
 /**
  * Minimal Astro global shape — only the properties getPageData reads.
  * This avoids depending on Astro's own types at the SDK level.
@@ -77,6 +78,8 @@ export interface PageData {
     assignmentsTag: string;
 }
 export interface GetPageDataOptions {
+    /** Resolve this authored error binding as an unpersonalized base page. */
+    errorPageKind?: ErrorPageKind;
     /** Path to compiled content root. Defaults to ACI_CONTENT_ROOT env or '.aci/compiled'. */
     compiledRoot?: string;
 }

package/dist/astro/page.js

@@ -32,6 +32,7 @@
  */
 import { FragmentNotFoundError } from '../content/provider.js';
 import { normalizeRoute } from '../content/routes.js';
+import { resolveErrorPage } from '../content/error-pages.js';
 import { routeMetadataForContent } from '../content/provider.js';
 import { resolveSlots } from '../content/resolve-slots.js';
 import { assignmentsScriptTagHTML, collectScriptTagHTML } from '../content/personalization.js';
@@ -54,7 +55,7 @@ import { GRADIAL_RENDER_INPUT_HEADER, getPendingRenderInputFromHeaders } from '.
  * artifacts in S3, no runtime content fetching).
  */
 export async function getPageData(astro, options) {
-    const route = normalizeRoute(astro.params.slug ? `/${astro.params.slug}` : '/');
+    let route = normalizeRoute(astro.params.slug ? `/${astro.params.slug}` : '/');
     // Static Astro generation is explicit; unexpected header access errors and
     // expired render-input IDs must not turn a selected variant into local base.
     let runtimeInput = null;
@@ -65,28 +66,29 @@ export async function getPageData(astro, options) {
             throw new Error(`ACI Astro render input is unavailable for route ${route}; refusing to render local base content`);
         }
     }
-    let siteConfig;
-    let page;
-    let providerModule = null;
-    let provider = null;
-    let variantKey;
-    if (runtimeInput) {
-        variantKey = requireVariantKey(runtimeInput.variantKey, route);
-        siteConfig = runtimeInput.siteConfig;
-        page = runtimeInput.page;
-    }
-    else {
-        // Lazy-import FileContentProvider to avoid pulling it in when
-        // preview render input is available
-        providerModule = await import('../providers/file.js');
-        provider = new providerModule.FileContentProvider(options?.compiledRoot);
-        [siteConfig, page] = await Promise.all([
-            provider.getSiteConfig(),
-            provider.getPage(route),
-        ]);
-        const entry = (await provider.listRoutes()).find((entry) => normalizeRoute(entry.path) === route);
-        variantKey = requireVariantKey(entry?.variantKey, route);
+    // Source selection is shared by ordinary pages and authored error seats.
+    // A supplied renderer input never consults local authoring files.
+    const provider = runtimeInput
+        ? null
+        : new (await import('../providers/file.js')).FileContentProvider(options?.compiledRoot);
+    const siteConfig = runtimeInput
+        ? runtimeInput.siteConfig
+        : await provider.getSiteConfig();
+    if (options?.errorPageKind) {
+        const resolved = await resolveErrorPage(options.errorPageKind, siteConfig);
+        for (const warning of resolved.warnings)
+            console.warn(`[aci error-pages] ${warning}`);
+        if (!resolved.route)
+            throw new Error(`No authored ${options.errorPageKind} page is bound`);
+        route = normalizeRoute(resolved.route);
+        if (runtimeInput && (normalizeRoute(runtimeInput.route) !== route || runtimeInput.variantKey !== 'base')) {
+            throw new Error(`ACI Astro ${options.errorPageKind} input must supply the bound base page ${resolved.route}`);
+        }
     }
+    const page = runtimeInput ? runtimeInput.page : await provider.getPage(route);
+    const variantKey = runtimeInput
+        ? requireVariantKey(runtimeInput.variantKey, route)
+        : requireVariantKey((await provider.listRoutes()).find((entry) => normalizeRoute(entry.path) === route)?.variantKey, route);
     const meta = routeMetadataForContent(siteConfig, page);
     // Resolve layout: prefer render input, fall back to provider
     const layout = await resolveLayout(runtimeInput, provider, page.layout, route);
@@ -102,8 +104,9 @@ export async function getPageData(astro, options) {
     });
     // Collect tag: suppress in preview mode (authoring surface, not visitor traffic)
     const isPreview = astro.url.searchParams.has('preview_token');
-    const collectTag = isPreview ? '' : collectScriptTagHTML(siteConfig);
-    const assignmentsTag = isPreview ? '' : assignmentsScriptTagHTML(page);
+    const suppressCollection = isPreview || Boolean(options?.errorPageKind);
+    const collectTag = suppressCollection ? '' : collectScriptTagHTML(siteConfig);
+    const assignmentsTag = suppressCollection ? '' : assignmentsScriptTagHTML(page);
     return { route, variantKey, siteConfig, page, meta, layout, slots, collectTag, assignmentsTag };
 }
 function requireVariantKey(value, route) {

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

@@ -5,6 +5,7 @@
 // Usage: emit-error-pages.mjs <prepare|emit>
 import fs from 'node:fs';
 import path from 'node:path';
+import { Script } from 'node:vm';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 const MARKER = '<!-- aci:error-pages generated -->';
 const SIZE_BUDGET = 150 * 1024;
@@ -15,11 +16,12 @@ function log(message) {
     console.log(`[aci error-pages] ${message}`);
 }
 function fail(message) {
-    console.error(`\n[aci error-pages] ERROR: ${message}\n`);
-    process.exit(1);
+    throw new Error(`[aci error-pages] ${message}`);
 }
 async function sdkContent() {
-    return await import(pathToFileURL(path.join(packageRoot, 'dist', 'content', 'index.js')).href);
+    const content = await import(pathToFileURL(path.join(packageRoot, 'dist', 'content', 'index.js')).href);
+    const { escapeInlineScriptSource } = await import(pathToFileURL(path.join(packageRoot, 'dist', 'content', 'error-page-kind.js')).href);
+    return { ...content, escapeInlineScriptSource };
 }
 // Keep the existing capsule transport path for SDK-first upgrades. This file
 // is executable policy, not a compiled content snapshot.
@@ -126,6 +128,43 @@ export function stampInstrumentation(html, instrumentationTag) {
     }
     return stamped;
 }
+// Node-only build hook. Keep loaders/bundlers out of the client policy module.
+const HOSTING_POLICY_MODULE = path.join('src', 'aci', 'hosting-error-page.mjs');
+async function hostingBootstrapTag(root, sdk) {
+    const modulePath = path.join(root, HOSTING_POLICY_MODULE);
+    if (!fs.existsSync(modulePath))
+        return '';
+    let policy;
+    try {
+        policy = await import(pathToFileURL(modulePath).href);
+    }
+    catch (error) {
+        throw new Error(`${HOSTING_POLICY_MODULE} failed to import: ${error.message}`);
+    }
+    if (typeof policy.hostingErrorPageScript !== 'function') {
+        throw new Error(`${HOSTING_POLICY_MODULE} must export a hostingErrorPageScript function`);
+    }
+    let source;
+    try {
+        source = await policy.hostingErrorPageScript(Object.freeze({ kind: 'catchAll', pageType: 'error' }));
+    }
+    catch (error) {
+        throw new Error(`${HOSTING_POLICY_MODULE}: hostingErrorPageScript failed: ${error.message}`);
+    }
+    if (typeof source !== 'string')
+        throw new Error(`${HOSTING_POLICY_MODULE}: hostingErrorPageScript must return JavaScript source as a string`);
+    if (!source.trim())
+        return '';
+    const escaped = sdk.escapeInlineScriptSource(source);
+    try {
+        new Script(escaped);
+    }
+    catch (error) {
+        throw new Error(`${HOSTING_POLICY_MODULE}: hostingErrorPageScript returned invalid JavaScript: ${error.message}`);
+    }
+    log(`hosting bootstrap source: site module ${HOSTING_POLICY_MODULE}`);
+    return `<script data-aci-error-page-bootstrap="error">${escaped}</script>`;
+}
 export async function emit(root = siteRoot, content) {
     const publicDir = path.join(root, 'public');
     const target = path.join(publicDir, '500.html');
@@ -135,11 +174,13 @@ export async function emit(root = siteRoot, content) {
     }
     const sdk = content ?? (await sdkContent());
     const instrumentationTag = await resolveInstrumentationTag(root, sdk);
-    const html = stampInstrumentation(sdk.defaultErrorPageHtml(), instrumentationTag);
+    const bootstrapTag = await hostingBootstrapTag(root, sdk);
+    const tags = bootstrapTag ? `${instrumentationTag}\n${bootstrapTag}` : instrumentationTag;
+    const html = stampInstrumentation(sdk.defaultErrorPageHtml(), tags);
     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).');
+            + 'Reduce the hosting bootstrap policy output or provide a smaller site-owned hosting fallback.');
     }
     fs.mkdirSync(publicDir, { recursive: true });
     fs.writeFileSync(target, html);

package/dist/content/error-page-kind.d.ts

@@ -3,6 +3,12 @@ export type ErrorPageKind = 'notFound' | 'catchAll';
 export type ErrorPageType = 'not_found' | 'error';
 /** Maps a binding kind to its D-14 page_type. */
 export declare function errorPageType(kind: ErrorPageKind): ErrorPageType;
+/** The Node-only hook used to augment the SDK-owned native hosting fallback. */
+export interface HostingErrorPageContext {
+    readonly kind: 'catchAll';
+    readonly pageType: 'error';
+}
+export type HostingErrorPageScript = (context: HostingErrorPageContext) => string | Promise<string>;
 declare global {
     interface Window {
         dataLayer?: Array<Record<string, unknown>>;

package/dist/content/error-page-kind.js

@@ -65,7 +65,8 @@ export function serializeErrorPageInstrumentation(push, kind) {
  * `\s` and `\!` decode to the original characters, so payload values
  * survive byte-for-byte on every surface.
  */
-function escapeInlineScriptSource(source) {
+/** @internal Shared by SDK build-time hosting policy emission. */
+export function escapeInlineScriptSource(source) {
     return source.replace(/<(\/script|script|!--)/gi, (match) => `<\\${match.slice(1)}`);
 }
 /**

package/dist/content/error-pages.d.ts

@@ -19,7 +19,7 @@ import type { KernelSiteConfig, SiteErrorPages } from './types.js';
 /** D-5 migration posture for absent bindings; default is 'warn' today. */
 export type ErrorPagePosture = 'warn' | 'enforce';
 export { errorPageType, errorPageInstrumentationTag, defaultPushErrorPageView, serializeErrorPageInstrumentation, } from './error-page-kind.js';
-export type { ErrorPageKind, ErrorPageType, ErrorPagePush } from './error-page-kind.js';
+export type { ErrorPageKind, ErrorPageType, ErrorPagePush, HostingErrorPageContext, HostingErrorPageScript } from './error-page-kind.js';
 import type { ErrorPageKind } from './error-page-kind.js';
 /**
  * The one D-5 posture config surface, shared by every stack: the same

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gradial/aci",
-  "version": "0.1.53-rc.4",
+  "version": "0.1.53-rc.6",
   "repository": {
     "type": "git",
     "url": "https://github.com/gradial/bare-metal-go.git",
@@ -164,11 +164,11 @@
     "astro": "^6.4.8"
   },
   "optionalDependencies": {
-    "@gradial/aci-cli-darwin-arm64": "0.1.53-rc.4",
-    "@gradial/aci-cli-darwin-x64": "0.1.53-rc.4",
-    "@gradial/aci-cli-linux-arm64": "0.1.53-rc.4",
-    "@gradial/aci-cli-linux-x64": "0.1.53-rc.4",
-    "@gradial/aci-cli-win32-arm64": "0.1.53-rc.4",
-    "@gradial/aci-cli-win32-x64": "0.1.53-rc.4"
+    "@gradial/aci-cli-darwin-arm64": "0.1.53-rc.6",
+    "@gradial/aci-cli-darwin-x64": "0.1.53-rc.6",
+    "@gradial/aci-cli-linux-arm64": "0.1.53-rc.6",
+    "@gradial/aci-cli-linux-x64": "0.1.53-rc.6",
+    "@gradial/aci-cli-win32-arm64": "0.1.53-rc.6",
+    "@gradial/aci-cli-win32-x64": "0.1.53-rc.6"
   }
 }

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

@@ -6,6 +6,7 @@
 
 import fs from 'node:fs';
 import path from 'node:path';
+import { Script } from 'node:vm';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
 const MARKER = '<!-- aci:error-pages generated -->';
@@ -19,12 +20,13 @@ function log(message) {
   console.log(`[aci error-pages] ${message}`);
 }
 function fail(message) {
-  console.error(`\n[aci error-pages] ERROR: ${message}\n`);
-  process.exit(1);
+  throw new Error(`[aci error-pages] ${message}`);
 }
 
 async function sdkContent() {
-  return await import(pathToFileURL(path.join(packageRoot, 'dist', 'content', 'index.js')).href);
+  const content = await import(pathToFileURL(path.join(packageRoot, 'dist', 'content', 'index.js')).href);
+  const { escapeInlineScriptSource } = await import(pathToFileURL(path.join(packageRoot, 'dist', 'content', 'error-page-kind.js')).href);
+  return { ...content, escapeInlineScriptSource };
 }
 
 // Keep the existing capsule transport path for SDK-first upgrades. This file
@@ -142,6 +144,37 @@ export function stampInstrumentation(html, instrumentationTag) {
   return stamped;
 }
 
+// Node-only build hook. Keep loaders/bundlers out of the client policy module.
+const HOSTING_POLICY_MODULE = path.join('src', 'aci', 'hosting-error-page.mjs');
+
+async function hostingBootstrapTag(root, sdk) {
+  const modulePath = path.join(root, HOSTING_POLICY_MODULE);
+  if (!fs.existsSync(modulePath)) return '';
+  let policy;
+  try {
+    policy = await import(pathToFileURL(modulePath).href);
+  } catch (error) {
+    throw new Error(`${HOSTING_POLICY_MODULE} failed to import: ${error.message}`);
+  }
+  if (typeof policy.hostingErrorPageScript !== 'function') {
+    throw new Error(`${HOSTING_POLICY_MODULE} must export a hostingErrorPageScript function`);
+  }
+  let source;
+  try {
+    source = await policy.hostingErrorPageScript(Object.freeze({ kind: 'catchAll', pageType: 'error' }));
+  } catch (error) {
+    throw new Error(`${HOSTING_POLICY_MODULE}: hostingErrorPageScript failed: ${error.message}`);
+  }
+  if (typeof source !== 'string') throw new Error(`${HOSTING_POLICY_MODULE}: hostingErrorPageScript must return JavaScript source as a string`);
+  if (!source.trim()) return '';
+  const escaped = sdk.escapeInlineScriptSource(source);
+  try { new Script(escaped); } catch (error) {
+    throw new Error(`${HOSTING_POLICY_MODULE}: hostingErrorPageScript returned invalid JavaScript: ${error.message}`);
+  }
+  log(`hosting bootstrap source: site module ${HOSTING_POLICY_MODULE}`);
+  return `<script data-aci-error-page-bootstrap="error">${escaped}</script>`;
+}
+
 export async function emit(root = siteRoot, content) {
   const publicDir = path.join(root, 'public');
   const target = path.join(publicDir, '500.html');
@@ -152,13 +185,15 @@ export async function emit(root = siteRoot, content) {
 
   const sdk = content ?? (await sdkContent());
   const instrumentationTag = await resolveInstrumentationTag(root, sdk);
-  const html = stampInstrumentation(sdk.defaultErrorPageHtml(), instrumentationTag);
+  const bootstrapTag = await hostingBootstrapTag(root, sdk);
+  const tags = bootstrapTag ? `${instrumentationTag}\n${bootstrapTag}` : instrumentationTag;
+  const html = stampInstrumentation(sdk.defaultErrorPageHtml(), tags);
 
   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).',
+      + 'Reduce the hosting bootstrap policy output or provide a smaller site-owned hosting fallback.',
     );
   }