@gradial/aci 0.1.51-ssr.5 → 0.1.52-rc.10

package/README.md

@@ -1,6 +1,6 @@
 # Agentic Content Infrastructure SDK
 
-`@gradial/aci` `0.1.51-ssr.5` is a pre-1.0 public-surface reset for the ACI
+`@gradial/aci` `0.1.52-rc.10` 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.51-ssr.5 zod@^4
+npm install @gradial/aci@0.1.52-rc.10 zod@^4
 ```
 
 ## Root Import
@@ -78,13 +78,13 @@ host bundles select and serve immutable release artifacts.
 The first RC scaffold path is Next:
 
 ```bash
-npx @gradial/aci@0.1.51-ssr.5 init my-site --template next-starter
+npx @gradial/aci@0.1.52-rc.10 init my-site --template next-starter
 ```
 
 List available templates:
 
 ```bash
-npx @gradial/aci@0.1.51-ssr.5 init --list
+npx @gradial/aci@0.1.52-rc.10 init --list
 ```
 
 ## Personalization: The One-Tag Install

package/dist/astro/assets.d.ts

@@ -5,16 +5,16 @@
  * at the URL level. Instead:
  *
  * - In dev: the Vite `damAssetPlugin` serves DAM assets from compiled
- *   content at `/.gradial-dam/{path}` (already handled by withAci).
+ *   content at `/dam/{path}` (already handled by withAci).
  *
- * - In production: the provider host maps `/.gradial-dam/*` to authoritative
- *   S3/R2/CDN storage. There is no app-level asset route
- *   (the retired Next `/gradial/assets` proxy no longer exists).
+ * - In production: CloudFront maps `/dam/*` to the S3 bucket
+ *   containing the compiled assets. There is no app-level asset route
+ *   (unlike Next.js which has `/gradial/assets/[releaseId]/[...path]`).
  *   The assets are content-addressed (hashed filenames) so the CDN
  *   can cache them with long TTLs.
  *
  * - At build time: `withAci`'s `astro:build:done` hook copies the
- *   `.gradial-dam` directory from compiled content into the build output,
+ *   `dam` directory from compiled content into the build output,
  *   so `astro build` produces a self-contained artifact.
  *
  * This module provides a helper to construct asset URLs that work in both
@@ -25,15 +25,15 @@
  * Default asset URL prefix. Matches the Vite middleware path and the
  * provider gateway's asset path.
  */
-export declare const DAM_ASSET_PREFIX = "/.gradial-dam";
+export declare const DAM_ASSET_PREFIX = "/dam";
 /**
  * Construct a DAM asset URL from a logical asset path.
  *
- * In both dev and production, DAM assets live under `/.gradial-dam/`.
+ * In both dev and production, DAM assets live under `/dam/`.
  * This function normalizes the path and prepends the prefix.
  *
  * @param logicalPath - The asset path as stored in content (e.g. "images/hero.webp")
- * @returns The full URL path (e.g. "/.gradial-dam/images/hero.webp")
+ * @returns The full URL path (e.g. "/dam/images/hero.webp")
  *
  * @example
  * ```astro

package/dist/astro/assets.js

@@ -5,16 +5,16 @@
  * at the URL level. Instead:
  *
  * - In dev: the Vite `damAssetPlugin` serves DAM assets from compiled
- *   content at `/.gradial-dam/{path}` (already handled by withAci).
+ *   content at `/dam/{path}` (already handled by withAci).
  *
- * - In production: the provider host maps `/.gradial-dam/*` to authoritative
- *   S3/R2/CDN storage. There is no app-level asset route
- *   (the retired Next `/gradial/assets` proxy no longer exists).
+ * - In production: CloudFront maps `/dam/*` to the S3 bucket
+ *   containing the compiled assets. There is no app-level asset route
+ *   (unlike Next.js which has `/gradial/assets/[releaseId]/[...path]`).
  *   The assets are content-addressed (hashed filenames) so the CDN
  *   can cache them with long TTLs.
  *
  * - At build time: `withAci`'s `astro:build:done` hook copies the
- *   `.gradial-dam` directory from compiled content into the build output,
+ *   `dam` directory from compiled content into the build output,
  *   so `astro build` produces a self-contained artifact.
  *
  * This module provides a helper to construct asset URLs that work in both
@@ -25,15 +25,15 @@
  * Default asset URL prefix. Matches the Vite middleware path and the
  * provider gateway's asset path.
  */
-export const DAM_ASSET_PREFIX = '/.gradial-dam';
+export const DAM_ASSET_PREFIX = '/dam';
 /**
  * Construct a DAM asset URL from a logical asset path.
  *
- * In both dev and production, DAM assets live under `/.gradial-dam/`.
+ * In both dev and production, DAM assets live under `/dam/`.
  * This function normalizes the path and prepends the prefix.
  *
  * @param logicalPath - The asset path as stored in content (e.g. "images/hero.webp")
- * @returns The full URL path (e.g. "/.gradial-dam/images/hero.webp")
+ * @returns The full URL path (e.g. "/dam/images/hero.webp")
  *
  * @example
  * ```astro

package/dist/astro/index.js

@@ -94,10 +94,10 @@ export function withAci(options = {}) {
             'astro:build:done'({ dir }) {
                 const siteDir = process.cwd();
                 const compiledRoot = path.resolve(siteDir, options.compiledRoot || process.env.ACI_CONTENT_ROOT || '.aci/compiled');
-                const source = path.join(compiledRoot, '.gradial-dam');
+                const source = path.join(compiledRoot, 'dam');
                 if (!fs.existsSync(source))
                     return;
-                const target = path.join(dir.pathname, '.gradial-dam');
+                const target = path.join(dir.pathname, 'dam');
                 fs.rmSync(target, { recursive: true, force: true });
                 fs.cpSync(source, target, { recursive: true });
             },

package/dist/audience-data-models.d.ts

@@ -336,6 +336,9 @@ export declare const experimentDataModel: import("./index.js").DataModelContract
         routes: z.ZodOptional<z.ZodArray<z.ZodString>>;
         fragments: z.ZodOptional<z.ZodArray<z.ZodString>>;
     }, z.core.$strip>;
+    eligibility: z.ZodOptional<z.ZodObject<{
+        audienceRef: z.ZodString;
+    }, z.core.$strict>>;
     primaryGoalRef: z.ZodOptional<z.ZodString>;
     primaryGoalId: z.ZodOptional<z.ZodString>;
     goalRefs: z.ZodOptional<z.ZodArray<z.ZodString>>;
@@ -426,6 +429,9 @@ export declare const experimentationDataModels: (import("./index.js").DataModelC
         routes: z.ZodOptional<z.ZodArray<z.ZodString>>;
         fragments: z.ZodOptional<z.ZodArray<z.ZodString>>;
     }, z.core.$strip>;
+    eligibility: z.ZodOptional<z.ZodObject<{
+        audienceRef: z.ZodString;
+    }, z.core.$strict>>;
     primaryGoalRef: z.ZodOptional<z.ZodString>;
     primaryGoalId: z.ZodOptional<z.ZodString>;
     goalRefs: z.ZodOptional<z.ZodArray<z.ZodString>>;
@@ -794,6 +800,9 @@ export declare const audienceDataModels: (import("./index.js").DataModelContract
         routes: z.ZodOptional<z.ZodArray<z.ZodString>>;
         fragments: z.ZodOptional<z.ZodArray<z.ZodString>>;
     }, z.core.$strip>;
+    eligibility: z.ZodOptional<z.ZodObject<{
+        audienceRef: z.ZodString;
+    }, z.core.$strict>>;
     primaryGoalRef: z.ZodOptional<z.ZodString>;
     primaryGoalId: z.ZodOptional<z.ZodString>;
     goalRefs: z.ZodOptional<z.ZodArray<z.ZodString>>;

package/dist/audience-data-models.js

@@ -127,6 +127,9 @@ export const experimentDataModel = defineDataModel({
             routes: z.array(z.string().min(1)).optional(),
             fragments: z.array(z.string().min(1)).optional(),
         }),
+        eligibility: z.object({
+            audienceRef: z.string().min(1),
+        }).strict().optional(),
         primaryGoalRef: z.string().optional(),
         primaryGoalId: z.string().optional(),
         goalRefs: z.array(z.string().min(1)).optional(),

package/dist/cli/compile-registry.d.mts

@@ -1,2 +1,6 @@
 #!/usr/bin/env node
-export {};
+export function compileRegistry(options: any): Promise<{
+    registry: string;
+    schemas: string[];
+}>;
+export function generatePageSchema(schemaDir: any, componentEntries: any, outDir: any): Promise<string>;

package/dist/cli/compile-registry.mjs

@@ -1,7 +1,8 @@
 #!/usr/bin/env node
+import { realpathSync } from 'node:fs';
 import { mkdir, writeFile } from 'node:fs/promises';
 import path from 'node:path';
-import { pathToFileURL } from 'node:url';
+import { fileURLToPath, pathToFileURL } from 'node:url';
 import { z } from 'zod';
 import { ImageSchema } from '../types/image.ts';
 import { VideoSchema } from '../types/video.ts';
@@ -18,14 +19,16 @@ try {
         globalThis.React = React;
 }
 catch { /* react not available — component files without JSX will still work */ }
-const args = parseArgs(process.argv.slice(2));
-try {
-    const result = await compileRegistry(args);
-    console.log(JSON.stringify({ success: true, ...result, errors: [] }, null, 2));
-}
-catch (error) {
-    console.error(JSON.stringify({ success: false, errors: [String(error?.message ?? error)] }, null, 2));
-    process.exitCode = 1;
+if (isMainModule()) {
+    const args = parseArgs(process.argv.slice(2));
+    try {
+        const result = await compileRegistry(args);
+        console.log(JSON.stringify({ success: true, ...result, errors: [] }, null, 2));
+    }
+    catch (error) {
+        console.error(JSON.stringify({ success: false, errors: [String(error?.message ?? error)] }, null, 2));
+        process.exitCode = 1;
+    }
 }
 async function compileRegistry(options) {
     const required = ['components', 'layouts', 'output'];
@@ -440,9 +443,10 @@ async function generatePageSchema(schemaDir, componentEntries, outDir) {
     const defs = {
         baseBlock: {
             type: 'object',
-            required: ['id', 'component', 'props'],
+            required: ['$type', 'id', 'component', 'props'],
             additionalProperties: true,
             properties: {
+                $type: { const: 'component' },
                 id: { type: 'string', minLength: 1 },
                 component: { type: 'string' },
                 props: { type: 'object' },
@@ -757,3 +761,14 @@ 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 { compileRegistry, generatePageSchema };

package/dist/cli/validate-content.d.mts

@@ -1,2 +1,32 @@
 #!/usr/bin/env node
-export {};
+export function validateContent(options: any): Promise<{
+    warnings?: any[] | undefined;
+    success: boolean;
+    pagesValidated: number;
+    blocksValidated: number;
+    errors: ({
+        page: string;
+        message: string;
+        fragment?: undefined;
+        component?: undefined;
+        path?: undefined;
+    } | {
+        fragment: string;
+        message: string;
+        page?: undefined;
+        component?: undefined;
+        path?: undefined;
+    } | {
+        fragment: string;
+        component: any;
+        message: string;
+        page?: undefined;
+        path?: undefined;
+    } | {
+        fragment: string;
+        component: any;
+        path: any;
+        message: any;
+        page?: undefined;
+    })[];
+}>;

package/dist/cli/validate-content.mjs

@@ -19,21 +19,25 @@
  * 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';
-const args = parseArgs(process.argv.slice(2));
-try {
-    const result = await validateContent(args);
-    console.log(JSON.stringify(result, null, 2));
-    if (!result.success)
+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;
-}
-catch (error) {
-    console.error(JSON.stringify({
-        success: false,
-        errors: [{ message: String(error?.message ?? error) }],
-    }, null, 2));
-    process.exitCode = 1;
+    }
 }
 // ---------------------------------------------------------------------------
 // Main
@@ -86,6 +90,22 @@ async function validateContent(options) {
         const blocks = collectBlocks(pageData);
         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,
@@ -348,6 +368,13 @@ 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}"` });
                 continue;
@@ -424,3 +451,14 @@ 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/dist/content/cache.d.ts

@@ -1,11 +1,16 @@
-import type { ContentProvider } from './provider.js';
+import type { CompiledManifest, ContentProvider } from './provider.js';
 export declare function getCacheStats(): {
+    manifest: {
+        hits: number;
+        misses: number;
+    };
     siteConfig: {
         hits: number;
         misses: number;
     };
 };
 export declare function resetCacheStats(): void;
+export declare function getCachedManifest(provider: ContentProvider): Promise<CompiledManifest>;
 /**
  * Get site config with caching. Use this instead of calling provider.getSiteConfig() directly.
  */

package/dist/content/cache.js

@@ -5,19 +5,44 @@
  *
  * Keyed by provider instance for automatic invalidation when its input changes.
  */
+const manifestCache = new WeakMap();
 const siteConfigCache = new WeakMap();
 // Cache hit/miss stats for observability
+let manifestHits = 0;
+let manifestMisses = 0;
 let siteConfigHits = 0;
 let siteConfigMisses = 0;
 export function getCacheStats() {
     return {
+        manifest: { hits: manifestHits, misses: manifestMisses },
         siteConfig: { hits: siteConfigHits, misses: siteConfigMisses },
     };
 }
 export function resetCacheStats() {
+    manifestHits = 0;
+    manifestMisses = 0;
     siteConfigHits = 0;
     siteConfigMisses = 0;
 }
+// getCachedManifest is intentionally capability based: the general content
+// interface does not require a manifest, while release-backed providers do.
+export function getCachedManifest(provider) {
+    const cached = manifestCache.get(provider);
+    if (cached) {
+        manifestHits++;
+        return cached;
+    }
+    if (!('manifest' in provider) || typeof provider.manifest !== 'function') {
+        throw new Error('Provider does not support manifest()');
+    }
+    manifestMisses++;
+    const promise = provider.manifest().catch((error) => {
+        manifestCache.delete(provider);
+        throw error;
+    });
+    manifestCache.set(provider, promise);
+    return promise;
+}
 /**
  * Get site config with caching. Use this instead of calling provider.getSiteConfig() directly.
  */
@@ -44,5 +69,6 @@ export function getCachedSiteConfig(provider) {
  * Useful for testing or manual cache invalidation.
  */
 export function clearProviderCache(provider) {
+    manifestCache.delete(provider);
     siteConfigCache.delete(provider);
 }

package/dist/content/provider.d.ts

@@ -21,6 +21,7 @@ export interface FragmentEntry {
 }
 export interface LayoutEntry {
     name: string;
+    payloadRef: string;
     slots: LayoutSlot[];
     defaults?: Record<string, FragmentRef[]>;
 }

package/dist/content/resolve-slots.d.ts

@@ -1,9 +1,16 @@
 import type { LayoutEntry } from './provider.js';
 import type { KernelPageBlock } from './types.js';
-export interface FragmentData {
-    id: string;
+export interface FragmentBlock {
+    $type: 'component';
     component: string;
     props?: Record<string, unknown>;
 }
+export interface FragmentData {
+    fragmentId?: string;
+    id?: string;
+    block?: FragmentBlock;
+    component?: string;
+    props?: Record<string, unknown>;
+}
 export type FragmentLoader = (id: string) => Promise<FragmentData>;
 export declare function resolveSlots(layout: LayoutEntry, pageRegions: Record<string, KernelPageBlock[]>, getFragment: FragmentLoader): Promise<Record<string, KernelPageBlock[]>>;

package/dist/content/resolve-slots.js

@@ -11,10 +11,12 @@ export async function resolveSlots(layout, pageRegions, getFragment) {
             const blocks = [];
             for (const ref of defaults) {
                 const fragment = await getFragment(ref.fragmentId);
+                const block = fragment.block ?? { component: fragment.component ?? '', props: fragment.props };
                 blocks.push({
-                    id: fragment.id,
-                    component: fragment.component,
-                    props: fragment.props || {},
+                    $type: 'component',
+                    id: fragment.id ?? fragment.fragmentId ?? ref.fragmentId,
+                    component: block.component,
+                    props: block.props || {},
                 });
             }
             resolved[slot.name] = blocks;

package/dist/content/types.d.ts

@@ -42,11 +42,13 @@ export interface KernelPageSeo {
     canonical?: string;
 }
 export interface KernelPageBlock {
+    $type: 'component';
     id: string;
     component: string;
     props: Record<string, unknown>;
 }
 export interface KernelAtomicBlock {
+    $type: 'component';
     id: string;
     component: string;
     props: Record<string, unknown>;

package/dist/dev/content-watch.js

@@ -95,7 +95,7 @@ export function damAssetPlugin(options = {}) {
         configureServer(server) {
             if (!server.middlewares)
                 return;
-            server.middlewares.use('/.gradial-dam', async (req, res, next) => {
+            server.middlewares.use('/dam', async (req, res, next) => {
                 const root = path.resolve(options.compiledRoot || compiledContentRoot());
                 const requestPath = safeRequestPath(req.url || '');
                 if (!requestPath) {
@@ -103,7 +103,7 @@ export function damAssetPlugin(options = {}) {
                     res.end('asset not found');
                     return;
                 }
-                const filePath = path.resolve(root, '.gradial-dam', requestPath.replace(/^\/+/, ''));
+                const filePath = path.resolve(root, 'dam', requestPath.replace(/^\/+/, ''));
                 if (!isInside(root, filePath)) {
                     res.statusCode = 404;
                     res.end('asset not found');
@@ -127,7 +127,7 @@ function safeRequestPath(url) {
     const rawPath = url.split('?')[0] || '';
     try {
         const decoded = decodeURIComponent(rawPath);
-        return decoded.startsWith('/.gradial-dam/') ? decoded.slice('/.gradial-dam/'.length) : decoded;
+        return decoded.startsWith('/dam/') ? decoded.slice('/dam/'.length) : decoded;
     }
     catch {
         return '';

package/dist/edge/personalization-core.d.ts

@@ -0,0 +1,11 @@
+export function selectPersonalizationVariant(request: any, route: any, claims: any, experiments: any, identity: any): any;
+export function resolvePersonalizationDecision(request: any, route: any, claims: any, experiments: any, identity: any): {
+    variant: any;
+    experiment: {
+        experimentId: any;
+        armId: any;
+        allocationVersion: string;
+        variantKey: any;
+        bucket: number;
+    } | null;
+};