@gradial/aci 0.1.53-rc.5 → 0.1.53-rc.7

package/CHANGELOG.md

@@ -4,6 +4,10 @@
 
 ### Fixed
 
+- Astro root-identity conformance checks now load the site-configured UI renderers,
+  allowing nested React and other integration components to render in the isolated
+  container.
+
 - 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
@@ -12,6 +16,10 @@
 
 ### 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.5` is a pre-1.0 public-surface reset for the ACI
+`@gradial/aci` `0.1.53-rc.7` 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.5 zod@^4
+npm install @gradial/aci@0.1.53-rc.7 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.5 init my-site --template next-starter
+npx @gradial/aci@0.1.53-rc.7 init my-site --template next-starter
 ```
 
 List available templates:
 
 ```bash
-npx @gradial/aci@0.1.53-rc.5 init --list
+npx @gradial/aci@0.1.53-rc.7 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/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/dist/platform-tests/adapters/astro.js

@@ -54,7 +54,10 @@ export async function openAstroSite(siteDir, explicit = []) {
             }
         }
         const registry = mergeRegistries(registries);
-        const container = await experimental_AstroContainer.create();
+        // Use the same renderer modules Astro registered from the site config,
+        // loaded through Vite so they share the components' module environment.
+        const { renderers } = await vite.ssrLoadModule('virtual:astro:renderers');
+        const container = await experimental_AstroContainer.create({ renderers });
         return {
             registry,
             adapter: createAstroAdapter(registry, container, siteDir),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gradial/aci",
-  "version": "0.1.53-rc.5",
+  "version": "0.1.53-rc.7",
   "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.5",
-    "@gradial/aci-cli-darwin-x64": "0.1.53-rc.5",
-    "@gradial/aci-cli-linux-arm64": "0.1.53-rc.5",
-    "@gradial/aci-cli-linux-x64": "0.1.53-rc.5",
-    "@gradial/aci-cli-win32-arm64": "0.1.53-rc.5",
-    "@gradial/aci-cli-win32-x64": "0.1.53-rc.5"
+    "@gradial/aci-cli-darwin-arm64": "0.1.53-rc.7",
+    "@gradial/aci-cli-darwin-x64": "0.1.53-rc.7",
+    "@gradial/aci-cli-linux-arm64": "0.1.53-rc.7",
+    "@gradial/aci-cli-linux-x64": "0.1.53-rc.7",
+    "@gradial/aci-cli-win32-arm64": "0.1.53-rc.7",
+    "@gradial/aci-cli-win32-x64": "0.1.53-rc.7"
   }
 }

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