@gradial/aci 0.1.20 → 0.1.21

package/README.md

@@ -1,6 +1,6 @@
 # Agentic Content Infrastructure SDK
 
-`@gradial/aci` `0.1.20` 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.20 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.20 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.20 init --list
+npx @gradial/aci@0.1.21 init --list
 ```
 
 ## Verify Locally

package/dist/next/middleware.d.ts

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

package/dist/next/middleware.js

@@ -3,7 +3,7 @@ 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';
-export function createMiddleware(config = {}) {
+export function createGradialMiddleware(config = {}) {
     return async function middleware(request) {
         const url = request.nextUrl;
         // ?leave_preview=1 → clear cookies, redirect to clean URL
@@ -14,7 +14,7 @@ export function createMiddleware(config = {}) {
             response.cookies.delete(PREVIEW_RELEASE_COOKIE);
             return response;
         }
-        const requestHeaders = headers(request.headers);
+        const requestHeaders = gradialHeaders(request.headers);
         // 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);
@@ -22,6 +22,19 @@ export function createMiddleware(config = {}) {
         if (!releaseId) {
             return NextResponse.next({ request: { headers: requestHeaders } });
         }
+        // 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 } });
+            if (preview?.token && preview.isPreview) {
+                for (const cookie of createPreviewCookies(preview.token, releaseId)) {
+                    response.cookies.set(cookie.name, cookie.value, cookie.options);
+                }
+            }
+            return response;
+        }
         requestHeaders.set(RELEASE_HEADER, releaseId);
         requestHeaders.set(ROUTE_HEADER, url.pathname);
         requestHeaders.set(DISPATCH_HEADER, 'ssr-page');
@@ -38,12 +51,33 @@ export function createMiddleware(config = {}) {
         return response;
     };
 }
-export const config = {
-    matcher: [
-        '/((?!_next/static|_next/image|favicon.ico|.*\\.(?:svg|png|jpg|jpeg|gif|webp)$).*)',
-    ],
-};
-function headers(headers) {
+function previewRewriteTarget(request, preview, config) {
+    const claims = preview.claims;
+    if (!claims?.deploymentId || !claims?.deploymentUrl || !preview.token) {
+        return null;
+    }
+    const currentDeploymentId = config.deploymentId || process.env.VERCEL_DEPLOYMENT_ID || '';
+    if (!currentDeploymentId || currentDeploymentId === claims.deploymentId) {
+        return null;
+    }
+    const base = buildDeploymentUrl(claims.deploymentUrl);
+    const target = new URL(request.nextUrl.pathname + request.nextUrl.search, base);
+    if (!target.searchParams.has('preview_token')) {
+        target.searchParams.set('preview_token', preview.token);
+    }
+    const bypass = config.deploymentProtectionBypass || process.env.VERCEL_DEPLOYMENT_PROTECTION_BYPASS;
+    if (bypass) {
+        target.searchParams.set('x-vercel-protection-bypass', bypass);
+    }
+    return target;
+}
+function buildDeploymentUrl(value) {
+    if (value.startsWith('http://') || value.startsWith('https://')) {
+        return value;
+    }
+    return `https://${value}`;
+}
+function gradialHeaders(headers) {
     const next = new Headers(headers);
     next.delete(RELEASE_HEADER);
     next.delete(ROUTE_HEADER);
@@ -143,3 +177,10 @@ 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/preview/core.d.ts

@@ -2,6 +2,10 @@ export interface PreviewClaims {
     scope?: string;
     releaseId?: string;
     siteId?: string;
+    codeDigest?: string;
+    contentSnapshotId?: string;
+    deploymentId?: string;
+    deploymentUrl?: string;
     expiresAt?: string;
 }
 export interface PreviewTokenSource {
@@ -18,6 +22,7 @@ export interface PreviewContext {
     isPreview: boolean;
     releaseId?: string;
     token?: string;
+    claims?: PreviewClaims;
 }
 export interface PreviewCookie {
     name: string;

package/dist/preview/core.js

@@ -63,7 +63,7 @@ export async function resolvePreviewContext(options) {
     if (!claims.expiresAt || Date.parse(claims.expiresAt) <= Date.now()) {
         return { isPreview: false };
     }
-    return { isPreview: true, releaseId: claims.releaseId, token };
+    return { isPreview: true, releaseId: claims.releaseId, token, claims };
 }
 export function createPreviewCookies(token, releaseId) {
     const common = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gradial/aci",
-  "version": "0.1.20",
+  "version": "0.1.21",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -10,6 +10,7 @@
     "bin/aci-*",
     "src/cli/*.mjs",
     "src/types/image.ts",
+    "src/types/block-ref.ts",
     "templates/common",
     "templates/nextjs",
     "templates/astro",

package/src/types/block-ref.ts

@@ -0,0 +1,74 @@
+import { z } from 'zod';
+import type { ComponentContract } from './component.js';
+
+const BLOCK_REF_KEY = '_gradialBlockRef';
+
+export interface BlockRefMeta {
+  allowed: readonly string[];
+  multiple: boolean;
+}
+
+const blockRefBase = z.object({
+  id: z.string().min(1),
+  component: z.string().min(1),
+  props: z.record(z.string(), z.unknown()),
+});
+
+type InferContractProps<T> = T extends ComponentContract<string, infer Schema>
+  ? Schema extends z.ZodType<infer P> ? P : Record<string, unknown>
+  : Record<string, unknown>;
+
+type InferContractId<T> = T extends ComponentContract<infer Id, unknown> ? Id : never;
+
+export type BlockRefEntry<T extends ComponentContract> = {
+  id: string;
+  component: InferContractId<T>;
+  props: InferContractProps<T>;
+};
+
+export type BlockRefUnion<T extends readonly ComponentContract[]> = {
+  [K in keyof T]: BlockRefEntry<T[K]>;
+}[number];
+
+function attachMeta<T extends z.ZodTypeAny>(
+  schema: T,
+  allowed: readonly string[],
+  multiple: boolean,
+): T {
+  Object.defineProperty(schema, BLOCK_REF_KEY, {
+    value: { allowed, multiple } satisfies BlockRefMeta,
+    enumerable: false,
+    writable: false,
+    configurable: false,
+  });
+  return schema;
+}
+
+export function blockRefArray<const T extends readonly ComponentContract[]>(
+  contracts: T,
+): z.ZodArray<z.ZodType<BlockRefUnion<T>>> {
+  return attachMeta(
+    z.array(blockRefBase) as unknown as z.ZodArray<z.ZodType<BlockRefUnion<T>>>,
+    contracts.map((c) => c.id),
+    true,
+  );
+}
+
+export function blockRef<const T extends readonly ComponentContract[]>(
+  contracts: T,
+): z.ZodType<BlockRefUnion<T>> {
+  return attachMeta(
+    blockRefBase as unknown as z.ZodType<BlockRefUnion<T>>,
+    contracts.map((c) => c.id),
+    false,
+  );
+}
+
+export function getBlockRefMeta(schema: unknown): BlockRefMeta | null {
+  if (schema && typeof schema === 'object' && BLOCK_REF_KEY in schema) {
+    return (schema as Record<string, unknown>)[BLOCK_REF_KEY] as BlockRefMeta;
+  }
+  return null;
+}
+
+export type BlockRef = z.infer<typeof blockRefBase>;

package/templates/astro/template/.aci.yaml

@@ -1,5 +1,6 @@
 version: "1"
 siteId: "site_astro"
+domain: "meridian.local"
 framework: astro
 
 source:

package/templates/nextjs/template/.aci.yaml

@@ -1,5 +1,6 @@
 version: "1"
 siteId: "site_nextjs"
+domain: "meridian.local"
 framework: next
 
 source:

package/templates/nextjs/template/src/middleware.ts

@@ -1,4 +1,4 @@
-import { createMiddleware } from '@gradial/aci/next/middleware';
+import { createGradialMiddleware } from '@gradial/aci/next/middleware';
 
-export default createMiddleware();
+export default createGradialMiddleware();
 export { config } from '@gradial/aci/next/middleware';