@gradial/aci 0.1.52-rc.28 → 0.1.52-rc.29

package/README.md

@@ -1,6 +1,6 @@
 # Agentic Content Infrastructure SDK
 
-`@gradial/aci` `0.1.52-rc.28` is a pre-1.0 public-surface reset for the ACI
+`@gradial/aci` `0.1.52-rc.29` 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.52-rc.28 zod@^4
+npm install @gradial/aci@0.1.52-rc.29 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.52-rc.28 init my-site --template next-starter
+npx @gradial/aci@0.1.52-rc.29 init my-site --template next-starter
 ```
 
 List available templates:
 
 ```bash
-npx @gradial/aci@0.1.52-rc.28 init --list
+npx @gradial/aci@0.1.52-rc.29 init --list
 ```
 
 ## Personalization: The One-Tag Install

package/dist/astro/error-page.js

@@ -50,6 +50,7 @@ export async function getErrorPageData(astro, kind, options = {}) {
         if (resolved.route) {
             const slug = resolved.route.replace(/^\/+|\/+$/g, '');
             const data = await getPageData({
+                isPrerendered: astro.isPrerendered,
                 params: { slug },
                 request: astro.request,
                 url: astro.url,

package/dist/astro/page.d.ts

@@ -37,6 +37,7 @@ import { type LayoutEntry } from '../content/provider.js';
  * This avoids depending on Astro's own types at the SDK level.
  */
 export interface AstroGlobal {
+    isPrerendered?: boolean;
     params: {
         slug?: string;
     };
@@ -51,6 +52,8 @@ export interface AstroGlobal {
 export interface PageData {
     /** Route string (normalized, e.g. "/" or "/about"). */
     route: string;
+    /** Selected render tuple, including the explicit "base" identity. */
+    variantKey: string;
     /** Site configuration. */
     siteConfig: KernelSiteConfig;
     /** Page content. */
@@ -91,4 +94,4 @@ export interface GetPageDataOptions {
  * directly from CloudFront in production (the CDN points at the release
  * artifacts in S3, no runtime content fetching).
  */
-export declare function getPageData(astro: AstroGlobal, _options?: GetPageDataOptions): Promise<PageData>;
+export declare function getPageData(astro: AstroGlobal, options?: GetPageDataOptions): Promise<PageData>;

package/dist/astro/page.js

@@ -35,7 +35,7 @@ import { normalizeRoute } from '../content/routes.js';
 import { routeMetadataForContent } from '../content/provider.js';
 import { resolveSlots } from '../content/resolve-slots.js';
 import { assignmentsScriptTagHTML, collectScriptTagHTML } from '../content/personalization.js';
-import { getPendingRenderInputFromHeaders } from '../runtime/page.js';
+import { GRADIAL_RENDER_INPUT_HEADER, getPendingRenderInputFromHeaders } from '../runtime/page.js';
 // ---------------------------------------------------------------------------
 // Implementation
 // ---------------------------------------------------------------------------
@@ -53,23 +53,25 @@ import { getPendingRenderInputFromHeaders } from '../runtime/page.js';
  * directly from CloudFront in production (the CDN points at the release
  * artifacts in S3, no runtime content fetching).
  */
-export async function getPageData(astro, _options) {
+export async function getPageData(astro, options) {
     const route = normalizeRoute(astro.params.slug ? `/${astro.params.slug}` : '/');
-    // Check for preview render input first (same as Next.js tier 1)
-    // Skip during prerender/static generation — request.headers is not available
+    // 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;
-    try {
-        runtimeInput = getPendingRenderInputFromHeaders(astro.request.headers);
-    }
-    catch {
-        // Astro throws when accessing request.headers during prerender — this is
-        // expected and harmless; preview mode is a request-time concern.
+    if (!astro.isPrerendered) {
+        const headers = astro.request.headers;
+        runtimeInput = getPendingRenderInputFromHeaders(headers);
+        if (headers.has(GRADIAL_RENDER_INPUT_HEADER) && !runtimeInput) {
+            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;
     }
@@ -77,15 +79,17 @@ export async function getPageData(astro, _options) {
         // Lazy-import FileContentProvider to avoid pulling it in when
         // preview render input is available
         providerModule = await import('../providers/file.js');
-        provider = new providerModule.FileContentProvider();
+        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);
     }
     const meta = routeMetadataForContent(siteConfig, page);
     // Resolve layout: prefer render input, fall back to provider
-    const layout = await resolveLayout(runtimeInput, provider, providerModule, page.layout);
+    const layout = await resolveLayout(runtimeInput, provider, page.layout, route);
     // Resolve slots: page regions filled, then layout fragment defaults
     const slots = await resolveSlots(layout, page?.regions || {}, async (id) => {
         if (runtimeInput) {
@@ -100,22 +104,27 @@ export async function getPageData(astro, _options) {
     const isPreview = astro.url.searchParams.has('preview_token');
     const collectTag = isPreview ? '' : collectScriptTagHTML(siteConfig);
     const assignmentsTag = isPreview ? '' : assignmentsScriptTagHTML(page);
-    return { route, siteConfig, page, meta, layout, slots, collectTag, assignmentsTag };
+    return { route, variantKey, siteConfig, page, meta, layout, slots, collectTag, assignmentsTag };
+}
+function requireVariantKey(value, route) {
+    if (typeof value !== 'string' || !value.trim() || value !== value.trim()) {
+        throw new Error(`ACI Astro render variant identity is missing or invalid for route ${route}; supply an explicit variantKey ("base" for an unpersonalized render)`);
+    }
+    return value;
 }
 // ---------------------------------------------------------------------------
 // Internal helpers
 // ---------------------------------------------------------------------------
-async function resolveLayout(runtimeInput, provider, providerModule, layoutName) {
-    // Check render input first
-    if (runtimeInput?.layouts?.[layoutName]) {
-        return runtimeInput.layouts[layoutName];
+async function resolveLayout(runtimeInput, provider, layoutName, route) {
+    if (runtimeInput) {
+        const layout = runtimeInput.layouts?.[layoutName];
+        if (!layout)
+            throw new Error(`ACI Astro render input for route ${route} is missing its selected layout ${JSON.stringify(layoutName)}`);
+        return layout;
     }
     // Fall back to provider
     if (provider) {
         return await provider.getLayout(layoutName);
     }
-    // Last resort: create a new provider
-    const mod = providerModule ?? await import('../providers/file.js');
-    const p = new mod.FileContentProvider();
-    return await p.getLayout(layoutName);
+    throw new Error(`ACI Astro content provider is unavailable for route ${route}`);
 }

package/dist/content/provider.d.ts

@@ -2,6 +2,7 @@ import type { KernelPage, KernelRouteMetadata, KernelSiteConfig, RenderInput } f
 export interface RouteEntry {
     slug: string;
     path: string;
+    variantKey: string;
     payloadRef: string;
     digest: string;
     fragmentRefs?: string[];
@@ -71,8 +72,9 @@ export declare class LayoutNotFoundError extends Error {
     constructor(name: string, cause?: unknown);
 }
 export interface RenderInputOptions {
+    variantKey: string;
     domain?: string;
     locale?: string;
 }
-export declare function loadRenderInput(provider: ContentProvider, route?: string, options?: RenderInputOptions): Promise<RenderInput>;
+export declare function loadRenderInput(provider: ContentProvider, route: string | undefined, options: RenderInputOptions): Promise<RenderInput>;
 export declare function routeMetadataForContent(siteConfig: KernelSiteConfig, page: KernelPage | null): KernelRouteMetadata;

package/dist/content/provider.js

@@ -24,8 +24,11 @@ export class LayoutNotFoundError extends Error {
     }
 }
 import { getCachedSiteConfig } from './cache.js';
-export async function loadRenderInput(provider, route = '/', options = {}) {
+export async function loadRenderInput(provider, route = '/', options) {
     const normalized = normalizeRoute(route);
+    if (typeof options?.variantKey !== 'string' || !options.variantKey.trim() || options.variantKey !== options.variantKey.trim()) {
+        throw new Error(`ACI render variant identity is missing or invalid for route ${normalized}; supply an explicit variantKey`);
+    }
     const [siteConfig, page] = await Promise.all([
         getCachedSiteConfig(provider),
         provider.getPage(normalized).catch((error) => {
@@ -36,6 +39,7 @@ export async function loadRenderInput(provider, route = '/', options = {}) {
     ]);
     return {
         route: normalized,
+        variantKey: options.variantKey,
         domain: options.domain || siteConfig.domain,
         locale: (options.locale || siteConfig.defaultLocale || 'en-us').toLowerCase(),
         siteConfig,

package/dist/content/types.d.ts

@@ -112,6 +112,8 @@ export interface KernelRouteMetadata {
 }
 export interface RenderInput<TPage extends KernelPage = KernelPage, TSiteConfig extends KernelSiteConfig = KernelSiteConfig> {
     route: string;
+    /** Selected render tuple. Unpersonalized renders explicitly use "base". */
+    variantKey: string;
     domain: string;
     locale: string;
     siteConfig: TSiteConfig;

package/dist/testing/index.d.ts

@@ -17,7 +17,7 @@ export declare class FixtureContentProvider implements ContentProvider {
     getFragment<T = unknown>(id: string): Promise<T>;
     getLayout<T = unknown>(name: string): Promise<T>;
     listRoutes(): Promise<RouteEntry[]>;
-    loadRenderInput(route?: string, options?: RenderInputOptions): Promise<RenderInput>;
+    loadRenderInput(route: string | undefined, options: RenderInputOptions): Promise<RenderInput>;
     resolveRouteMetadata(route?: string): Promise<KernelRouteMetadata>;
 }
 export declare function createFixtureContentProvider(options?: FixtureContentProviderOptions): FixtureContentProvider;

package/dist/testing/index.js

@@ -55,11 +55,12 @@ export class FixtureContentProvider {
             .map(([routePath, page]) => ({
             slug: routePath === '/' ? '' : routePath.replace(/^\//, ''),
             path: routePath,
+            variantKey: 'base',
             payloadRef: routePath === '/' ? 'routes/index.json' : `routes/${routePath.replace(/^\//, '')}.json`,
             digest: '',
         }));
     }
-    async loadRenderInput(route = '/', options = {}) {
+    async loadRenderInput(route = '/', options) {
         return loadRenderInput(this, route, options);
     }
     async resolveRouteMetadata(route = '/') {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gradial/aci",
-  "version": "0.1.52-rc.28",
+  "version": "0.1.52-rc.29",
   "repository": {
     "type": "git",
     "url": "https://github.com/gradial/bare-metal-go.git",
@@ -159,11 +159,11 @@
     "zod": "^4.0.0"
   },
   "optionalDependencies": {
-    "@gradial/aci-cli-darwin-arm64": "0.1.52-rc.28",
-    "@gradial/aci-cli-darwin-x64": "0.1.52-rc.28",
-    "@gradial/aci-cli-linux-arm64": "0.1.52-rc.28",
-    "@gradial/aci-cli-linux-x64": "0.1.52-rc.28",
-    "@gradial/aci-cli-win32-arm64": "0.1.52-rc.28",
-    "@gradial/aci-cli-win32-x64": "0.1.52-rc.28"
+    "@gradial/aci-cli-darwin-arm64": "0.1.52-rc.29",
+    "@gradial/aci-cli-darwin-x64": "0.1.52-rc.29",
+    "@gradial/aci-cli-linux-arm64": "0.1.52-rc.29",
+    "@gradial/aci-cli-linux-x64": "0.1.52-rc.29",
+    "@gradial/aci-cli-win32-arm64": "0.1.52-rc.29",
+    "@gradial/aci-cli-win32-x64": "0.1.52-rc.29"
   }
 }