@gradial/aci 0.1.31 → 0.1.34

package/README.md

@@ -1,6 +1,6 @@
 # Agentic Content Infrastructure SDK
 
-`@gradial/aci` `0.1.27` is a pre-1.0 public-surface reset for the ACI
+`@gradial/aci` `0.1.33` 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.27 zod@^4
+npm install @gradial/aci@0.1.33 zod@^4
 ```
 
 ## Root Import
@@ -85,13 +85,13 @@ go through an app-owned HTTP endpoint backed server-side by a `ContentProvider`.
 The first RC scaffold path is Next:
 
 ```bash
-npx @gradial/aci@0.1.27 init my-site --template next-starter
+npx @gradial/aci@0.1.33 init my-site --template next-starter
 ```
 
 List available templates:
 
 ```bash
-npx @gradial/aci@0.1.27 init --list
+npx @gradial/aci@0.1.33 init --list
 ```
 
 ## Personalization: The One-Tag Install

package/bin/aci.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import { spawn } from 'node:child_process';
 import { chmodSync, existsSync } from 'node:fs';
-import { cp, mkdir, readdir, readFile, rename, stat, writeFile } from 'node:fs/promises';
+import { readdir, readFile, stat } from 'node:fs/promises';
 import { createRequire } from 'node:module';
 import { basename, dirname, join, relative, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -23,7 +23,7 @@ const platformKey = `${process.platform}-${process.arch}`;
 const packageName = platformPackages[platformKey];
 
 if (!packageName) {
-  console.error(`Unsupported platform for gradial-aci: ${platformKey}`);
+  console.error(`Unsupported platform for aci: ${platformKey}`);
   process.exit(1);
 }
 
@@ -36,57 +36,86 @@ if (argv[0] === 'init') {
   process.exit(0);
 }
 
-function resolveBundledBinary() {
-  const binaryPath = join(shimDir, `aci-${platformKey}${process.platform === 'win32' ? '.exe' : ''}`);
-  if (existsSync(binaryPath)) return binaryPath;
-  // Local development fallback for packages built before platform-suffixed bins.
-  const legacyPath = join(shimDir, binName);
-  return existsSync(legacyPath) ? legacyPath : null;
-}
+// ── Binary resolution ──────────────────────────────────────────────
+//
+// Resolution order (no fallback chain — exactly one path wins):
+//
+// 1. ACI_CLI_BIN env var — explicit override for debugging / CI.
+// 2. Platform npm package — the published distribution channel.
+//    Resolved via require.resolve('$packageName/package.json').
+// 3. Monorepo workspace — for local development inside this repo.
+//    Looks at packages/cli-<platform>/bin/<binary>.
+// 4. `go run` dev fallback — when working on the Go CLI source
+//    inside this monorepo and no binary has been built yet.
+
+function resolveBinary() {
+  // 1. Explicit override
+  const envBin = process.env.ACI_CLI_BIN;
+  if (envBin) {
+    if (!existsSync(envBin)) {
+      console.error(`ACI_CLI_BIN points to ${envBin} but it does not exist.`);
+      process.exit(1);
+    }
+    return { kind: 'binary', path: envBin };
+  }
 
-function resolvePackagedBinary() {
+  // 2. Platform npm package (installed via optionalDependencies)
   try {
     const packageJsonPath = require.resolve(`${packageName}/package.json`);
     const binaryPath = join(dirname(packageJsonPath), 'bin', binName);
-
-    return existsSync(binaryPath) ? binaryPath : null;
+    if (existsSync(binaryPath)) {
+      return { kind: 'binary', path: binaryPath };
+    }
   } catch {
-    return null;
+    // Not installed — continue
   }
-}
 
-function resolveWorkspaceBinary() {
-  const binaryPath = resolve(repoRoot, 'packages', `cli-${platformKey}`, 'bin', binName);
+  // 3. Monorepo workspace (local dev: binary built by ./scripts/build-cli.sh)
+  const workspaceBin = resolve(repoRoot, 'packages', `cli-${platformKey}`, 'bin', binName);
+  if (existsSync(workspaceBin)) {
+    return { kind: 'binary', path: workspaceBin };
+  }
 
-  return existsSync(binaryPath) ? binaryPath : null;
-}
+  // 4. Go run fallback (monorepo dev without a built binary)
+  const goModPath = join(repoRoot, 'go.mod');
+  const commandDir = join(repoRoot, 'cmd', 'aci');
+  if (existsSync(goModPath) && existsSync(commandDir)) {
+    return {
+      kind: 'go-run',
+      command: 'go',
+      args: ['run', './cmd/aci', ...normalizeArgsForGoFallback(argv)],
+      cwd: repoRoot,
+    };
+  }
 
-const binaryPath = resolveBundledBinary() ?? resolvePackagedBinary() ?? resolveWorkspaceBinary();
-if (binaryPath) {
-  try { chmodSync(binaryPath, 0o755); } catch {}
+  return null;
 }
-const fallback = binaryPath ? null : resolveGoFallback();
 
-if (!binaryPath && !fallback) {
+const resolved = resolveBinary();
+
+if (!resolved) {
   console.error(
-    [
-      `Could not find the aci binary for ${platformKey}.`,
-      `Install ${packageName} or build the local CLI package with ./scripts/build-cli.sh.`,
-    ].join(' '),
+    `Platform package ${packageName} is not installed.\n` +
+    `Install it with: npm install ${packageName}\n` +
+    `Or, if using the @gradial/aci SDK, ensure optionalDependencies resolved for your platform.`,
   );
   process.exit(1);
 }
 
-const child = binaryPath
-  ? spawn(binaryPath, argv, {
+if (resolved.kind === 'binary') {
+  try { chmodSync(resolved.path, 0o755); } catch {}
+}
+
+const child = resolved.kind === 'binary'
+  ? spawn(resolved.path, argv, {
       env: {
         ...process.env,
         ACI_PACKAGE_ROOT: resolve(shimDir, '..'),
       },
       stdio: 'inherit',
     })
-  : spawn(fallback.command, fallback.args, {
-      cwd: fallback.cwd,
+  : spawn(resolved.command, resolved.args, {
+      cwd: resolved.cwd,
       env: {
         ...process.env,
         ACI_PACKAGE_ROOT: resolve(shimDir, '..'),
@@ -95,7 +124,7 @@ const child = binaryPath
     });
 
 child.on('error', (error) => {
-  console.error(`Failed to run gradial-aci: ${error.message}`);
+  console.error(`Failed to run aci: ${error.message}`);
   process.exit(1);
 });
 
@@ -108,21 +137,6 @@ child.on('exit', (code, signal) => {
   process.exit(code ?? 1);
 });
 
-function resolveGoFallback() {
-  const goModPath = join(repoRoot, 'go.mod');
-  const commandDir = join(repoRoot, 'cmd', 'aci');
-
-  if (!existsSync(goModPath) || !existsSync(commandDir)) {
-    return null;
-  }
-
-  return {
-    command: 'go',
-    args: ['run', './cmd/aci', ...normalizeArgsForGoFallback(argv)],
-    cwd: repoRoot,
-  };
-}
-
 function normalizeArgsForGoFallback(args) {
   const pathFlags = new Set(['-s', '--site-dir', '--content', '--out']);
   const normalized = [];
@@ -180,32 +194,49 @@ function isAbsolutePath(value) {
 }
 
 async function runInit(args) {
+  // Inside the function because runInit is invoked from module top-level,
+  // before module-scope const bindings below it would initialize.
+  const initTemplates = {
+    'next-starter': 'nextjs',
+    'astro-starter': 'astro',
+  };
   if (args.includes('--list')) {
-    console.log('next-starter');
+    for (const name of Object.keys(initTemplates)) {
+      console.log(name);
+    }
     return;
   }
 
   const target = args.find((arg) => !arg.startsWith('-'));
   const template = optionValue(args, '--template') || 'next-starter';
+  const templateNames = Object.keys(initTemplates).join('|');
   if (!target) {
-    throw new Error('usage: aci init <target> --template next-starter');
+    throw new Error(`usage: aci init <target> --template ${templateNames}`);
   }
-  if (template !== 'next-starter') {
-    throw new Error(`unknown template "${template}". Available templates: next-starter`);
+  const framework = initTemplates[template];
+  if (!framework) {
+    throw new Error(`unknown template "${template}". Available templates: ${Object.keys(initTemplates).join(', ')}`);
   }
 
   const targetDir = resolve(callerCwd, target);
   await assertEmptyTarget(targetDir);
-  await mkdir(targetDir, { recursive: true });
 
   const packageRoot = resolve(shimDir, '..');
-  await cp(join(packageRoot, 'templates', 'common'), targetDir, { recursive: true });
-  await cp(join(packageRoot, 'templates', 'nextjs', 'template'), targetDir, { recursive: true });
-  await renderTemplates(targetDir, {
-    siteName: basename(targetDir),
-    version: '0.1.0',
+  const packageJson = JSON.parse(await readFile(join(packageRoot, 'package.json'), 'utf-8'));
+  const { materializeTemplate } = await import(
+    new URL('../src/cli/materialize-template.mjs', import.meta.url)
+  );
+  materializeTemplate({
+    templatesDir: join(packageRoot, 'templates'),
+    framework,
+    destDir: targetDir,
+    vars: {
+      siteName: basename(targetDir),
+      version: '0.1.0',
+      aciVersion: packageJson.version,
+    },
   });
-  console.log(`Created ${relative(callerCwd, targetDir) || '.'} from next-starter`);
+  console.log(`Created ${relative(callerCwd, targetDir) || '.'} from ${template}`);
 }
 
 function optionValue(args, name) {
@@ -232,22 +263,3 @@ async function assertEmptyTarget(targetDir) {
     throw error;
   }
 }
-
-async function renderTemplates(root, values) {
-  const entries = await readdir(root, { withFileTypes: true });
-  for (const entry of entries) {
-    const fullPath = join(root, entry.name);
-    if (entry.isDirectory()) {
-      await renderTemplates(fullPath, values);
-      continue;
-    }
-    if (!entry.name.endsWith('.tmpl')) {
-      continue;
-    }
-    const raw = await readFile(fullPath, 'utf-8');
-    const rendered = raw.replace(/\{\{\s*([A-Za-z0-9_]+)\s*\}\}/g, (_match, key) => values[key] ?? '');
-    const nextPath = fullPath.slice(0, -'.tmpl'.length);
-    await writeFile(fullPath, rendered);
-    await rename(fullPath, nextPath);
-  }
-}

package/dist/astro/assets.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Asset URL helpers for Astro SSG sites.
+ *
+ * In the Astro + CloudFront SSG paradigm, assets are NOT release-scoped
+ * at the URL level. Instead:
+ *
+ * - In dev: the Vite `damAssetPlugin` serves DAM assets from compiled
+ *   content at `/.gradial-dam/{path}` (already handled by withAci).
+ *
+ * - In production: CloudFront maps `/.gradial-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,
+ *   so `astro build` produces a self-contained artifact.
+ *
+ * This module provides a helper to construct asset URLs that work in both
+ * dev and production without the template needing to know about the
+ * underlying infrastructure.
+ */
+/**
+ * Default asset URL prefix. Matches the Vite middleware path and the
+ * CloudFront behavior origin path.
+ */
+export declare const DAM_ASSET_PREFIX = "/.gradial-dam";
+/**
+ * Construct a DAM asset URL from a logical asset path.
+ *
+ * In both dev and production, DAM assets live under `/.gradial-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")
+ *
+ * @example
+ * ```astro
+ * ---
+ * import { damAssetUrl } from '@gradial/aci/astro';
+ * ---
+ * <img src={damAssetUrl('images/hero.webp')} alt="Hero" />
+ * ```
+ */
+export declare function damAssetUrl(logicalPath: string): string;

package/dist/astro/assets.js

@@ -0,0 +1,51 @@
+/**
+ * Asset URL helpers for Astro SSG sites.
+ *
+ * In the Astro + CloudFront SSG paradigm, assets are NOT release-scoped
+ * at the URL level. Instead:
+ *
+ * - In dev: the Vite `damAssetPlugin` serves DAM assets from compiled
+ *   content at `/.gradial-dam/{path}` (already handled by withAci).
+ *
+ * - In production: CloudFront maps `/.gradial-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,
+ *   so `astro build` produces a self-contained artifact.
+ *
+ * This module provides a helper to construct asset URLs that work in both
+ * dev and production without the template needing to know about the
+ * underlying infrastructure.
+ */
+/**
+ * Default asset URL prefix. Matches the Vite middleware path and the
+ * CloudFront behavior origin path.
+ */
+export const DAM_ASSET_PREFIX = '/.gradial-dam';
+/**
+ * Construct a DAM asset URL from a logical asset path.
+ *
+ * In both dev and production, DAM assets live under `/.gradial-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")
+ *
+ * @example
+ * ```astro
+ * ---
+ * import { damAssetUrl } from '@gradial/aci/astro';
+ * ---
+ * <img src={damAssetUrl('images/hero.webp')} alt="Hero" />
+ * ```
+ */
+export function damAssetUrl(logicalPath) {
+    const clean = logicalPath.replace(/^\/+/, '').replace(/\/+/g, '/');
+    if (!clean)
+        return DAM_ASSET_PREFIX;
+    return `${DAM_ASSET_PREFIX}/${clean}`;
+}

package/dist/astro/index.d.ts

@@ -35,6 +35,7 @@ export declare function getGradialStaticPaths(): Promise<Array<{
     };
 }>>;
 export declare function getPageRuntimeRenderInput(request: Request): RenderInput | null;
+export { getPageData, type PageData, type AstroGlobal, type GetPageDataOptions, } from './page.js';
 export { createRegistry, registryLookup } from '../registry.js';
 export type { Registry, RegistryEntry, AnyComponent } from '../registry.js';
 export type { BlockRef } from '../types/block-ref.js';
@@ -45,6 +46,7 @@ export interface RenderableBlock {
 }
 export type RenderChildren = (blocks: readonly BlockRef[]) => RenderableBlock[];
 export declare function createRenderChildren(registry: Registry): RenderChildren;
+export { damAssetUrl, DAM_ASSET_PREFIX } from './assets.js';
 export { getPreviewMode, createPreviewBannerHTML, createPreviewCookies, type PreviewContext, type PreviewCookie, } from './preview.js';
 export interface AstroOptions extends ContentWatchOptions {
     /** Path to compiled content root. Defaults to ACI_CONTENT_ROOT env or '.aci/compiled' */

package/dist/astro/index.js

@@ -33,6 +33,10 @@ export function getPageRuntimeRenderInput(request) {
     return getPendingRenderInputFromHeaders(request.headers);
 }
 // ---------------------------------------------------------------------------
+// Page data helper — Astro equivalent of Next.js createPage
+// ---------------------------------------------------------------------------
+export { getPageData, } from './page.js';
+// ---------------------------------------------------------------------------
 // Registry helpers
 // ---------------------------------------------------------------------------
 export { createRegistry, registryLookup } from '../registry.js';
@@ -58,6 +62,10 @@ export function createRenderChildren(registry) {
     return renderChildren;
 }
 // ---------------------------------------------------------------------------
+// Asset URL helpers
+// ---------------------------------------------------------------------------
+export { damAssetUrl, DAM_ASSET_PREFIX } from './assets.js';
+// ---------------------------------------------------------------------------
 // Preview support
 // ---------------------------------------------------------------------------
 export { getPreviewMode, createPreviewBannerHTML, createPreviewCookies, } from './preview.js';

package/dist/astro/page.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Astro page data helper — the Astro equivalent of Next.js createPage.
+ *
+ * Encapsulates route normalization, content resolution (preview runtime
+ * input vs FileContentProvider), metadata derivation, layout resolution,
+ * slot filling, and collect-tag emission into a single call.
+ *
+ * Usage in `src/pages/[...slug].astro`:
+ *
+ * ```astro
+ * ---
+ * import { getGradialStaticPaths, getPageData, createRenderChildren } from '@gradial/aci/astro';
+ * import { registry } from '../cms/registry';
+ *
+ * export const getStaticPaths = getGradialStaticPaths;
+ *
+ * const data = await getPageData(Astro);
+ * const renderChildren = createRenderChildren(registry);
+ * ---
+ * ```
+ *
+ * The SDK owns:
+ * - Param normalization (slug -> route)
+ * - Content loading (preview render input header OR FileContentProvider)
+ * - Metadata generation (routeMetadataForContent)
+ * - Layout resolution (layout from render input OR provider)
+ * - Slot resolution (resolveSlots with fragment fallback)
+ * - Collect-tag emission (gated on preview_token query param)
+ *
+ * The page template receives a typed data object and only needs to
+ * iterate slots and render blocks via the registry.
+ */
+import type { KernelPage, KernelSiteConfig, KernelRouteMetadata, KernelPageBlock } from '../content/types.js';
+import type { LayoutEntry } from '../content/provider.js';
+/**
+ * Minimal Astro global shape — only the properties getPageData reads.
+ * This avoids depending on Astro's own types at the SDK level.
+ */
+export interface AstroGlobal {
+    params: {
+        slug?: string;
+    };
+    request: Request;
+    url: URL;
+}
+/**
+ * Resolved page data returned by getPageData. Contains everything the
+ * Astro page template needs to render: metadata, layout slots with
+ * resolved blocks, and the collect tag HTML.
+ */
+export interface PageData {
+    /** Route string (normalized, e.g. "/" or "/about"). */
+    route: string;
+    /** Site configuration. */
+    siteConfig: KernelSiteConfig;
+    /** Page content. */
+    page: KernelPage;
+    /** Derived metadata (title, description, canonical, siteName). */
+    meta: KernelRouteMetadata;
+    /** Resolved layout with slot definitions. */
+    layout: LayoutEntry;
+    /** Resolved slot contents keyed by slot name. */
+    slots: Record<string, KernelPageBlock[]>;
+    /**
+     * Pre-rendered collect script tag HTML. Empty string when
+     * personalization is disabled or when in preview mode.
+     */
+    collectTag: string;
+}
+export interface GetPageDataOptions {
+    /** Path to compiled content root. Defaults to ACI_CONTENT_ROOT env or '.aci/compiled'. */
+    compiledRoot?: string;
+}
+/**
+ * Load all page data for the current Astro route.
+ *
+ * This is the Astro equivalent of Next.js `createPage`. It resolves
+ * content through the same priority chain:
+ *
+ * 1. Preview render input (via x-gradial-render-input-id header)
+ * 2. FileContentProvider (local compiled content)
+ *
+ * The function does NOT support S3 content resolution — Astro SSG sites
+ * pre-render at build time from compiled content. S3 content is served
+ * 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>;

package/dist/astro/page.js

@@ -0,0 +1,117 @@
+/**
+ * Astro page data helper — the Astro equivalent of Next.js createPage.
+ *
+ * Encapsulates route normalization, content resolution (preview runtime
+ * input vs FileContentProvider), metadata derivation, layout resolution,
+ * slot filling, and collect-tag emission into a single call.
+ *
+ * Usage in `src/pages/[...slug].astro`:
+ *
+ * ```astro
+ * ---
+ * import { getGradialStaticPaths, getPageData, createRenderChildren } from '@gradial/aci/astro';
+ * import { registry } from '../cms/registry';
+ *
+ * export const getStaticPaths = getGradialStaticPaths;
+ *
+ * const data = await getPageData(Astro);
+ * const renderChildren = createRenderChildren(registry);
+ * ---
+ * ```
+ *
+ * The SDK owns:
+ * - Param normalization (slug -> route)
+ * - Content loading (preview render input header OR FileContentProvider)
+ * - Metadata generation (routeMetadataForContent)
+ * - Layout resolution (layout from render input OR provider)
+ * - Slot resolution (resolveSlots with fragment fallback)
+ * - Collect-tag emission (gated on preview_token query param)
+ *
+ * The page template receives a typed data object and only needs to
+ * iterate slots and render blocks via the registry.
+ */
+import { normalizeRoute } from '../content/routes.js';
+import { routeMetadataForContent } from '../content/provider.js';
+import { resolveSlots } from '../content/resolve-slots.js';
+import { collectScriptTagHTML } from '../content/personalization.js';
+import { getPendingRenderInputFromHeaders } from '../runtime/page.js';
+// ---------------------------------------------------------------------------
+// Implementation
+// ---------------------------------------------------------------------------
+/**
+ * Load all page data for the current Astro route.
+ *
+ * This is the Astro equivalent of Next.js `createPage`. It resolves
+ * content through the same priority chain:
+ *
+ * 1. Preview render input (via x-gradial-render-input-id header)
+ * 2. FileContentProvider (local compiled content)
+ *
+ * The function does NOT support S3 content resolution — Astro SSG sites
+ * pre-render at build time from compiled content. S3 content is served
+ * directly from CloudFront in production (the CDN points at the release
+ * artifacts in S3, no runtime content fetching).
+ */
+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
+    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.
+    }
+    let siteConfig;
+    let page;
+    let providerModule = null;
+    let provider = null;
+    if (runtimeInput) {
+        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();
+        [siteConfig, page] = await Promise.all([
+            provider.getSiteConfig(),
+            provider.getPage(route),
+        ]);
+    }
+    const meta = routeMetadataForContent(siteConfig, page);
+    // Resolve layout: prefer render input, fall back to provider
+    const layout = await resolveLayout(runtimeInput, provider, providerModule, page.layout);
+    // Resolve slots: page regions filled, then layout fragment defaults
+    const slots = await resolveSlots(layout, page?.regions || {}, async (id) => {
+        if (runtimeInput?.fragments?.[id]) {
+            return runtimeInput.fragments[id];
+        }
+        const p = provider ?? new (await import('../providers/file.js')).FileContentProvider();
+        return await p.getFragment(id);
+    });
+    // Collect tag: suppress in preview mode (authoring surface, not visitor traffic)
+    const isPreview = astro.url.searchParams.has('preview_token');
+    const collectTag = isPreview ? '' : collectScriptTagHTML(siteConfig);
+    return { route, siteConfig, page, meta, layout, slots, collectTag };
+}
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+async function resolveLayout(runtimeInput, provider, providerModule, layoutName) {
+    // Check render input first
+    if (runtimeInput?.layouts?.[layoutName]) {
+        return runtimeInput.layouts[layoutName];
+    }
+    // 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);
+}

package/dist/dev/content-watch.d.ts

@@ -32,6 +32,7 @@ export interface VitePluginLike {
     transformIndexHtml?(html: string): string;
 }
 export declare function devRefreshPort(options?: DevRefreshOptions): number;
+export declare function resolveBin(options?: ContentWatchOptions): string;
 export declare function contentWatchPlugin(options?: ContentWatchOptions): VitePluginLike;
 export declare function damAssetPlugin(options?: ContentWatchOptions): VitePluginLike;
 export {};

package/dist/dev/content-watch.js

@@ -14,7 +14,7 @@ export function devRefreshPort(options = {}) {
 function sourceContentRoot(options) {
     return path.resolve(options.contentRoot || process.env.ACI_CONTENT_SOURCE || './.content');
 }
-function resolveBin(options) {
+export function resolveBin(options = {}) {
     return options.bin || process.env.ACI_BIN || 'aci';
 }
 function recompileContent(options, reason) {

package/dist/next/config.d.ts

@@ -1,5 +1,11 @@
 import type { NextConfig } from 'next';
 export interface WithAciOptions {
+    /**
+     * S3 bucket URL for DAM asset rewrites. When set, asset requests under
+     * the assetPrefix are rewritten to this URL instead of proxying through
+     * an app-level route. Example: 'https://cdn.example.com/dam'
+     */
+    assetOrigin?: string;
     /** Asset rewrite prefix. Defaults to '/.gradial-dam' */
     assetPrefix?: string;
     /**