@gradial/aci 0.1.23 → 0.1.24

package/README.md

@@ -1,6 +1,6 @@
 # Agentic Content Infrastructure SDK
 
-`@gradial/aci` `0.1.23` is a pre-1.0 public-surface reset for the ACI
+`@gradial/aci` `0.1.21` 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.23 zod@^4
+npm install @gradial/aci@0.1.21 zod@^4
 ```
 
 ## Root Import
@@ -68,13 +68,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.23 init my-site --template next-starter
+npx @gradial/aci@0.1.21 init my-site --template next-starter
 ```
 
 List available templates:
 
 ```bash
-npx @gradial/aci@0.1.23 init --list
+npx @gradial/aci@0.1.21 init --list
 ```
 
 ## Verify Locally

package/dist/content/assets.js

@@ -31,7 +31,7 @@ export async function getReleaseAssetResponse(input) {
     copyHeader(res.headers, headers, 'content-length');
     copyHeader(res.headers, headers, 'etag');
     copyHeader(res.headers, headers, 'last-modified');
-    headers.set('cache-control', 'public, max-age=31536000, immutable');
+    headers.set('cache-control', 'public, max-age=300, must-revalidate');
     return new Response(res.body, { status: 200, headers });
 }
 function cleanAssetPath(value) {

package/dist/next/asset-route.d.ts

@@ -2,7 +2,6 @@ type AssetRouteContext = {
     params: Promise<AssetRouteParams>;
 };
 type AssetRouteParams = {
-    releaseId?: string;
     path?: string[];
 };
 export declare const runtime = "nodejs";

package/dist/next/asset-route.js

@@ -1,21 +1,20 @@
 import { FileContentProvider } from '../providers/file.js';
-import { getReleaseAssetResponse } from '../content/assets.js';
-const LOCAL_RELEASE_ID = 'local';
+import { getReleaseAssetResponse, resolveReleaseId } from './server.js';
 export const runtime = 'nodejs';
 export const dynamic = 'force-dynamic';
 export async function GET(_request, { params }) {
     const resolvedParams = await params;
-    const releaseId = resolvedParams.releaseId || '';
     const assetPath = '/' + (resolvedParams.path || []).join('/');
-    if (!releaseId || assetPath === '/') {
+    if (assetPath === '/') {
         return new Response('asset not found', { status: 404 });
     }
-    if (releaseId === LOCAL_RELEASE_ID) {
+    if (process.env.ACI_CONTENT_PROVIDER === 'file') {
         const provider = new FileContentProvider();
         return provider.fetchRaw(assetPath);
     }
     try {
-        return await getReleaseAssetResponse({ releaseId, assetPath });
+        const releaseId = await resolveReleaseId();
+        return await getReleaseAssetResponse(releaseId, assetPath);
     }
     catch {
         return new Response('asset not found', { status: 404 });

package/dist/next/config.js

@@ -2,14 +2,38 @@ import { createContentWatchWebpackPlugin } from './content-watch.js';
 export function withAci(nextConfig = {}, options = {}) {
     const assetPrefix = options.assetPrefix || '/.gradial-dam';
     const userRewrites = nextConfig.rewrites;
+    const userHeaders = nextConfig.headers;
     const userWebpack = nextConfig.webpack;
     return {
         ...nextConfig,
+        headers: async () => {
+            const gradialHeaders = [
+                {
+                    source: '/__r/:releaseId/routes/:path*',
+                    headers: [
+                        { key: 'Cache-Control', value: 'public, max-age=0, must-revalidate' },
+                        { key: 'CDN-Cache-Control', value: 'max-age=31536000' },
+                        { key: 'Vercel-CDN-Cache-Control', value: 'max-age=31536000' },
+                    ],
+                },
+                {
+                    source: '/gradial/assets/:path*',
+                    headers: [
+                        { key: 'Cache-Control', value: 'public, max-age=300, must-revalidate' },
+                        { key: 'CDN-Cache-Control', value: 'max-age=300' },
+                    ],
+                },
+            ];
+            if (!userHeaders)
+                return gradialHeaders;
+            const userResult = await (typeof userHeaders === 'function' ? userHeaders() : userHeaders);
+            return [...gradialHeaders, ...userResult];
+        },
         rewrites: async () => {
             const rewrites = [
                 {
                     source: `${assetPrefix}/:path*`,
-                    destination: `/gradial/assets/local${assetPrefix}/:path*`,
+                    destination: `/gradial/assets${assetPrefix}/:path*`,
                 },
             ];
             if (!userRewrites)

package/dist/next/middleware.d.ts

@@ -1,4 +1,4 @@
-import { NextResponse, type NextRequest } from 'next/server.js';
+import { type NextRequest } from 'next/server.js';
 export interface GradialMiddlewareConfig {
     siteId?: string;
     edgeConfig?: string;
@@ -6,7 +6,7 @@ export interface GradialMiddlewareConfig {
     deploymentId?: string;
     deploymentProtectionBypass?: string;
 }
-export declare function createGradialMiddleware(config?: GradialMiddlewareConfig): (request: NextRequest) => Promise<NextResponse<unknown>>;
+export declare function createGradialMiddleware(config?: GradialMiddlewareConfig): (request: NextRequest) => Promise<Response>;
 export declare const config: {
     matcher: string[];
 };

package/dist/next/middleware.js

@@ -1,8 +1,7 @@
 import { NextResponse } from 'next/server.js';
 import { getUncachedEdgeConfigValue } from './edge-config.js';
-import { PREVIEW_TOKEN_COOKIE, PREVIEW_RELEASE_COOKIE, PREVIEW_HEADER, RELEASE_HEADER, extractPreviewToken, resolvePreviewContext, createPreviewCookies, previewSignKey, } from '../preview/core.js';
-const ROUTE_HEADER = 'x-gradial-route';
-const DISPATCH_HEADER = 'x-gradial-dispatch';
+import { PREVIEW_TOKEN_COOKIE, PREVIEW_RELEASE_COOKIE, extractPreviewToken, resolvePreviewContext, createPreviewCookies, previewSignKey, } from '../preview/core.js';
+const RELEASE_SCOPED_PREFIX = '/__r';
 export function createGradialMiddleware(config = {}) {
     return async function middleware(request) {
         const url = request.nextUrl;
@@ -14,20 +13,32 @@ export function createGradialMiddleware(config = {}) {
             response.cookies.delete(PREVIEW_RELEASE_COOKIE);
             return response;
         }
-        const requestHeaders = gradialHeaders(request.headers);
+        // Block direct access to /__r/... — only middleware rewrites may use it.
+        if (isReleaseScopedPath(url.pathname, RELEASE_SCOPED_PREFIX)) {
+            return new Response('not found', {
+                status: 404,
+                headers: { 'Cache-Control': 'private, no-store' },
+            });
+        }
         // Try preview token first; if valid, use that release.
         // If no token or invalid, fall through to active release from edge config.
         const preview = await resolvePreviewFromRequest(request, config);
         const releaseId = preview?.releaseId || await activeReleaseFromEdgeConfig(config);
         if (!releaseId) {
-            return NextResponse.next({ request: { headers: requestHeaders } });
+            if (process.env.ACI_CONTENT_PROVIDER === 'file') {
+                return NextResponse.next();
+            }
+            return new Response('no active release', {
+                status: 503,
+                headers: { 'Cache-Control': 'private, no-store' },
+            });
         }
         // Cross-deployment preview: if the token was staged on a different Vercel
         // deployment, rewrite the request to that deployment. This keeps the browser
         // on the production domain while the correct code runtime serves the request.
         const rewriteTarget = preview ? previewRewriteTarget(request, preview, config) : null;
         if (rewriteTarget) {
-            const response = NextResponse.rewrite(rewriteTarget, { request: { headers: requestHeaders } });
+            const response = NextResponse.rewrite(rewriteTarget);
             if (preview?.token && preview.isPreview) {
                 for (const cookie of createPreviewCookies(preview.token, releaseId)) {
                     response.cookies.set(cookie.name, cookie.value, cookie.options);
@@ -35,13 +46,10 @@ export function createGradialMiddleware(config = {}) {
             }
             return response;
         }
-        requestHeaders.set(RELEASE_HEADER, releaseId);
-        requestHeaders.set(ROUTE_HEADER, url.pathname);
-        requestHeaders.set(DISPATCH_HEADER, 'ssr-page');
-        if (preview?.isPreview) {
-            requestHeaders.set(PREVIEW_HEADER, '1');
-        }
-        const response = NextResponse.next({ request: { headers: requestHeaders } });
+        // Rewrite public URL to release-scoped internal path for CDN cache isolation.
+        // Each release gets a unique URL (/__r/{releaseId}/routes/...) so the CDN
+        // cache key is per-release. New release = new URL = cache miss = fresh content.
+        const response = rewriteToReleaseScopedPath(request, releaseId, Boolean(preview?.isPreview));
         // Persist preview token as cookie so navigation stays in preview
         if (preview?.token && preview.isPreview) {
             for (const cookie of createPreviewCookies(preview.token, releaseId)) {
@@ -51,6 +59,27 @@ export function createGradialMiddleware(config = {}) {
         return response;
     };
 }
+function rewriteToReleaseScopedPath(request, releaseId, isPreview) {
+    const rewriteURL = new URL(request.url);
+    rewriteURL.pathname = releaseScopedPath(RELEASE_SCOPED_PREFIX, releaseId, request.nextUrl.pathname);
+    const response = NextResponse.rewrite(rewriteURL);
+    if (isPreview) {
+        response.headers.set('Cache-Control', 'private, no-store');
+    }
+    else {
+        response.headers.set('Cache-Control', 'public, max-age=0, must-revalidate');
+        response.headers.set('CDN-Cache-Control', 'max-age=31536000');
+        response.headers.set('Vercel-CDN-Cache-Control', 'max-age=31536000');
+    }
+    return response;
+}
+function isReleaseScopedPath(pathname, prefix) {
+    return pathname === prefix || pathname.startsWith(`${prefix}/`);
+}
+function releaseScopedPath(prefix, releaseId, pathname) {
+    const suffix = pathname === '/' ? '' : pathname;
+    return `${prefix}/${encodeURIComponent(releaseId)}/routes${suffix}`;
+}
 function previewRewriteTarget(request, preview, config) {
     const claims = preview.claims;
     if (!claims?.deploymentId || !claims?.deploymentUrl || !preview.token) {
@@ -77,14 +106,6 @@ function buildDeploymentUrl(value) {
     }
     return `https://${value}`;
 }
-function gradialHeaders(headers) {
-    const next = new Headers(headers);
-    next.delete(RELEASE_HEADER);
-    next.delete(ROUTE_HEADER);
-    next.delete(DISPATCH_HEADER);
-    next.delete(PREVIEW_HEADER);
-    return next;
-}
 async function resolvePreviewFromRequest(request, config) {
     const token = extractPreviewToken({
         query: request.nextUrl.searchParams,
@@ -177,10 +198,6 @@ function clampRelease(activeReleaseId, activeSequence, compatibility) {
 function edgeKeySegment(value) {
     return value.replace(/[^A-Za-z0-9_-]/g, '_');
 }
-// Default matcher. _next/static is included so that cross-deployment previews
-// can rewrite static assets to the staged deployment. _next/image is excluded
-// because it is a generic optimization endpoint and does not carry code-specific
-// assets in most configurations. Consumers can override this if needed.
 export const config = {
     matcher: ['/((?!_next/image|favicon.ico|\\.gradial-dam|api/baremetal-assets|gradial/assets).*)'],
 };

package/dist/next/page.d.ts

@@ -28,6 +28,12 @@ export interface CreatePageOptions {
  * The SDK owns param normalization, content loading, metadata generation,
  * notFound handling, layout resolution, and block rendering via the registry.
  *
+ * Release-scoped routes: when the middleware rewrites a public URL to
+ * `/__r/{releaseId}/routes/{path}`, the catch-all slug becomes
+ * `['__r', releaseId, 'routes', ...pathSegments]`. createPage detects this
+ * prefix, extracts the releaseId, and passes it to the content loader. This
+ * gives each release a unique CDN cache key without a separate route folder.
+ *
  * Layout slots: createPage loads the page's layout, iterates all slots, and
  * fills each from the page's regions. If a slot is empty, it falls back to
  * the layout's fragment defaults (loaded via getFragment). This lets chrome

package/dist/next/page.js

@@ -22,6 +22,12 @@ import { renderBlocks } from './render.js';
  * The SDK owns param normalization, content loading, metadata generation,
  * notFound handling, layout resolution, and block rendering via the registry.
  *
+ * Release-scoped routes: when the middleware rewrites a public URL to
+ * `/__r/{releaseId}/routes/{path}`, the catch-all slug becomes
+ * `['__r', releaseId, 'routes', ...pathSegments]`. createPage detects this
+ * prefix, extracts the releaseId, and passes it to the content loader. This
+ * gives each release a unique CDN cache key without a separate route folder.
+ *
  * Layout slots: createPage loads the page's layout, iterates all slots, and
  * fills each from the page's regions. If a slot is empty, it falls back to
  * the layout's fragment defaults (loaded via getFragment). This lets chrome
@@ -30,8 +36,8 @@ import { renderBlocks } from './render.js';
 export function createPage(registry, options) {
     const dynamic = 'force-dynamic';
     async function generateMetadata({ params }) {
-        const route = await routeFromNextParams(params);
-        const input = await getRenderInput(route);
+        const { route, releaseId } = await resolveRouteAndRelease(params);
+        const input = await getRenderInput(route, { releaseId });
         const meta = routeMetadataForContent(input.siteConfig, input.page);
         return {
             title: meta.title,
@@ -45,9 +51,9 @@ export function createPage(registry, options) {
         };
     }
     async function CatchAllPage({ params }) {
-        const route = await routeFromNextParams(params);
+        const { route, releaseId } = await resolveRouteAndRelease(params);
         try {
-            const input = await getRenderInput(route);
+            const input = await getRenderInput(route, { releaseId });
             if (!input.page)
                 notFound();
             const layout = await getLayout(input.page.layout);
@@ -77,3 +83,27 @@ export function createPage(registry, options) {
         default: CatchAllPage,
     };
 }
+/**
+ * Resolves the logical route and optional releaseId from Next.js catch-all
+ * params. When the middleware rewrites to /__r/{releaseId}/routes/{path},
+ * the slug is ['__r', releaseId, 'routes', ...pathSegments]. Otherwise the
+ * slug is treated as the public route directly.
+ */
+async function resolveRouteAndRelease(params) {
+    const resolved = await params;
+    const slug = resolved?.slug;
+    if (slug && slug.length >= 3 && slug[0] === '__r' && slug[2] === 'routes') {
+        const releaseId = decodeURIComponent(slug[1]);
+        if (!releaseId || releaseId.includes('/') || releaseId === '.' || releaseId === '..') {
+            return { route: '/' };
+        }
+        const pathSegments = slug.slice(3);
+        if (pathSegments.length === 0)
+            return { route: '/', releaseId };
+        if (pathSegments.some((s) => s === '' || s === '.' || s === '..'))
+            return { route: '/' };
+        return { route: `/${pathSegments.join('/')}/`, releaseId };
+    }
+    const route = await routeFromNextParams(params);
+    return { route };
+}

package/dist/next/preview-mode.js

@@ -1,9 +1,8 @@
-import { headers } from 'next/headers.js';
-import { PREVIEW_HEADER, RELEASE_HEADER } from '../preview/core.js';
+import { cookies } from 'next/headers.js';
+import { PREVIEW_RELEASE_COOKIE, PREVIEW_TOKEN_COOKIE } from '../preview/core.js';
 export async function isPreviewMode() {
-    const current = await headers();
-    if (current.get(PREVIEW_HEADER) === '1') {
-        return current.get(RELEASE_HEADER) || '';
-    }
-    return '';
+    const current = await cookies();
+    if (!current.get(PREVIEW_TOKEN_COOKIE)?.value)
+        return '';
+    return current.get(PREVIEW_RELEASE_COOKIE)?.value || '';
 }

package/dist/next/server.js

@@ -4,8 +4,6 @@ import { getCachedManifest, getCachedSiteConfig } from '../content/cache.js';
 import { S3ContentProvider } from '../providers/s3.js';
 import { GRADIAL_RENDER_INPUT_HEADER, getPendingRenderInput } from '../runtime/page.js';
 import { getUncachedEdgeConfigValue } from './edge-config.js';
-const RELEASE_HEADER = 'x-gradial-release-id';
-const PREVIEW_HEADER = 'x-gradial-preview';
 export { FragmentNotFoundError, PageNotFoundError, LayoutNotFoundError };
 export async function getPage(route = '', config = {}) {
     const runtimeInput = await getPageRuntimeRenderInput();
@@ -125,7 +123,7 @@ export async function getReleaseAssetResponse(releaseId, assetPath, config = {})
     copyHeader(res.headers, headers, 'content-length');
     copyHeader(res.headers, headers, 'etag');
     copyHeader(res.headers, headers, 'last-modified');
-    headers.set('cache-control', 'public, max-age=31536000, immutable');
+    headers.set('cache-control', 'public, max-age=300, must-revalidate');
     return new Response(res.body, { status: 200, headers });
 }
 function cleanAssetPath(value) {
@@ -150,17 +148,14 @@ async function safeResponseText(res) {
 export async function resolveReleaseId(config = {}) {
     if (config.releaseId)
         return config.releaseId;
-    const headerReleaseId = await releaseIdFromHeaders();
-    if (headerReleaseId)
-        return headerReleaseId;
     if (process.env.ACI_RELEASE_ID)
         return process.env.ACI_RELEASE_ID;
     const activeReleaseId = await activeReleaseFromEdgeConfig(config);
     if (activeReleaseId)
         return activeReleaseId;
-    throw new Error('ACI release ID is not available from headers, ACI_RELEASE_ID, or Edge Config');
+    throw new Error('ACI release ID is required. Pass releaseId from the release-scoped route or set ACI_RELEASE_ID.');
 }
-async function resolveProvider(config) {
+async function resolveS3Provider(config) {
     const releaseId = await resolveReleaseId(config);
     const provider = new S3ContentProvider({
         bucket: config.bucket,
@@ -180,16 +175,7 @@ async function resolveProviderWithFallback(config) {
         const { FileContentProvider } = await import('../providers/file.js');
         return new FileContentProvider();
     }
-    return await resolveProvider(config);
-}
-async function releaseIdFromHeaders() {
-    try {
-        const current = await headers();
-        return current.get(RELEASE_HEADER) || '';
-    }
-    catch {
-        return '';
-    }
+    return await resolveS3Provider(config);
 }
 async function activeReleaseFromEdgeConfig(config) {
     const edgeConfig = config.edgeConfig || process.env.EDGE_CONFIG || '';
@@ -272,5 +258,3 @@ function joinKey(...parts) {
         .filter(Boolean)
         .join('/');
 }
-// Note: React cache() would be redundant here since getCachedSiteConfig already
-// returns the same Promise for the same provider instance within a request

package/dist/preview/core.d.ts

@@ -34,8 +34,6 @@ export interface PreviewCookie {
         path: string;
     };
 }
-export declare const PREVIEW_HEADER = "x-gradial-preview";
-export declare const RELEASE_HEADER = "x-gradial-release-id";
 export declare const PREVIEW_TOKEN_COOKIE = "aci_preview";
 export declare const PREVIEW_RELEASE_COOKIE = "aci_preview_release";
 export declare function validatePreviewToken(token: string, signKey: string): Promise<PreviewClaims | null>;

package/dist/preview/core.js

@@ -1,5 +1,3 @@
-export const PREVIEW_HEADER = 'x-gradial-preview';
-export const RELEASE_HEADER = 'x-gradial-release-id';
 export const PREVIEW_TOKEN_COOKIE = 'aci_preview';
 export const PREVIEW_RELEASE_COOKIE = 'aci_preview_release';
 export async function validatePreviewToken(token, signKey) {
@@ -43,7 +41,7 @@ export function extractPreviewToken(source) {
     return undefined;
 }
 export function previewSignKey() {
-    return process.env.GRADIAL_PREVIEW_SIGN_KEY || undefined;
+    return process.env.GRADIAL_PREVIEW_SIGN_KEY || process.env.ACI_PREVIEW_SIGN_KEY || undefined;
 }
 export async function resolvePreviewContext(options) {
     const token = options.token;

package/dist/react/Media.d.ts

@@ -19,6 +19,6 @@ export interface MediaProps {
  * HTML element based on $type.
  *
  * - gradial.image → <img> with srcset via Picture
- * - gradial.video → <video> via VideoPlayer
+ * - gradial.video → <video> or <iframe> via VideoPlayer
  */
 export declare function Media({ media, className, style, loading, imgProps, videoProps, }: MediaProps): import("react").FunctionComponentElement<import("./VideoPlayer.js").VideoPlayerProps> | import("react").FunctionComponentElement<import("./Picture.js").PictureProps>;

package/dist/react/Media.js

@@ -6,7 +6,7 @@ import { VideoPlayer } from './VideoPlayer.js';
  * HTML element based on $type.
  *
  * - gradial.image → <img> with srcset via Picture
- * - gradial.video → <video> via VideoPlayer
+ * - gradial.video → <video> or <iframe> via VideoPlayer
  */
 export function Media({ media, className, style, loading = 'lazy', imgProps, videoProps, }) {
     switch (media.$type) {