@gradial/aci 0.1.52-rc.1 → 0.1.52-rc.13

package/dist/next/collect-route.js

@@ -1,5 +1,6 @@
 import { MAX_BATCH_EVENTS } from '../collect/batcher.js';
 import { computeEnvelopeDigest } from './envelope-digest.js';
+import { validateMimicToken } from '../mimic/core.js';
 import { consentSignals, IdentityErasureFencedError, identityHashHex, parseCookieHeader, verifyClaims, verifyIdentityCookie, } from './personalization-host.js';
 const MAX_COLLECT_BODY_BYTES = 64 * 1024;
 const DEFAULT_RETENTION_SECONDS = 13 * 30 * 24 * 60 * 60;
@@ -78,6 +79,20 @@ export function createPersonalizationCollectRoute(config) {
             return validationResponse(error);
         }
         const cookies = parseCookieHeader(request.headers.get('cookie'));
+        // Mimic suppression (audience-mimic REQ-5): a validly signed, unexpired
+        // aci_mimic cookie marks a marketer's view-as session — accept uniformly,
+        // store nothing, and never rotate the visitor's real aci_claims. Placed
+        // after schema validation so the 400/202 split stays independent of
+        // session type; an invalid cookie is ignored (events process normally).
+        if (config.mimicSignKey) {
+            const mimicCookie = cookies.get('aci_mimic') || '';
+            if (mimicCookie) {
+                const mimic = await validateMimicToken(mimicCookie, config.mimicSignKey, config.siteId);
+                if (mimic) {
+                    return accepted(new Headers({ 'cache-control': 'no-store', 'content-type': 'application/json' }));
+                }
+            }
+        }
         const signals = consentSignals(request, cookies);
         const rawIdentity = await verifyIdentityCookie(cookies.get('aci_id') || '', config.identityKeys);
         const now = (config.now ?? (() => new Date()))();

package/dist/next/error-seat-payload.js

@@ -104,7 +104,7 @@ export function buildErrorSeatPayload(contentRoot, posture) {
                 if (!fragmentRef)
                     continue;
                 const fragment = readJSON(root, fragmentRef);
-                blocks.push({ id: fragment.id, component: fragment.component, props: fragment.props || {} });
+                blocks.push({ $type: 'component', id: fragment.id, component: fragment.component, props: fragment.props || {} });
             }
             if (blocks.length)
                 slots[slot.name] = blocks;

package/dist/next/hosted-page-target.d.ts

@@ -0,0 +1,7 @@
+export type HostedPageTarget = Readonly<{
+    kind: 'base' | 'variant';
+    route: string;
+    pageRef: string;
+    variantKey?: string;
+}>;
+export declare function parseHostedPageTarget(rawSegments: readonly string[]): HostedPageTarget | null;

package/dist/next/hosted-page-target.js

@@ -0,0 +1,39 @@
+const VARIANT_NAMESPACE = '__variant';
+export function parseHostedPageTarget(rawSegments) {
+    const segments = decodeSegments(rawSegments);
+    if (!segments)
+        return null;
+    const variantAt = segments.indexOf(VARIANT_NAMESPACE);
+    if (variantAt < 0)
+        return target('base', segments, segments);
+    if (variantAt !== segments.lastIndexOf(VARIANT_NAMESPACE) || variantAt !== segments.length - 2) {
+        return null;
+    }
+    return {
+        ...target('variant', segments.slice(0, variantAt), segments),
+        variantKey: segments[variantAt + 1],
+    };
+}
+function target(kind, routeSegments, targetSegments) {
+    return {
+        kind,
+        route: routeSegments.length === 0 ? '/' : `/${routeSegments.join('/')}/`,
+        pageRef: ['routes', ...targetSegments, 'index.json'].join('/'),
+    };
+}
+function decodeSegments(rawSegments) {
+    const segments = [];
+    for (const raw of rawSegments) {
+        let segment;
+        try {
+            segment = decodeURIComponent(raw);
+        }
+        catch {
+            return null;
+        }
+        if (!segment || segment === '.' || segment === '..' || segment.includes('/'))
+            return null;
+        segments.push(segment);
+    }
+    return segments;
+}

package/dist/next/index.d.ts

@@ -5,7 +5,6 @@ export { createPage, type CreatePageOptions, type SlotPropsFn } from './page.js'
 export { getSiteConfig, getFragment, getLayout, getPage, getRenderInput, routeFromNextParams } from './server.js';
 export { PageNotFoundError, FragmentNotFoundError, LayoutNotFoundError } from './server.js';
 export { CollectScript, type CollectScriptProps } from './collect-script.js';
-export { aciMiddlewareMatcher } from './middleware.js';
 export { AssignmentsScript, type AssignmentsScriptProps } from './assignments-script.js';
 export { createNotFound, renderPageForRoute, resolveErrorPage, type NextResolvedErrorPage, } from './error-pages.js';
 export { ErrorPageInstrumentation } from './error-page-instrumentation.js';

package/dist/next/index.js

@@ -5,7 +5,6 @@ export { createPage } from './page.js';
 export { getSiteConfig, getFragment, getLayout, getPage, getRenderInput, routeFromNextParams } from './server.js';
 export { PageNotFoundError, FragmentNotFoundError, LayoutNotFoundError } from './server.js';
 export { CollectScript } from './collect-script.js';
-export { aciMiddlewareMatcher } from './middleware.js';
 export { AssignmentsScript } from './assignments-script.js';
 export { createNotFound, renderPageForRoute, resolveErrorPage, } from './error-pages.js';
 export { ErrorPageInstrumentation } from './error-page-instrumentation.js';

package/dist/next/page.d.ts

@@ -31,12 +31,10 @@ export interface CreatePageOptions {
  * the collect script tag exactly once per page (design/04 contract tag).
  *
  * Release-scoped routes (production): the middleware rewrites a public URL
- * to `/__r/{releaseId}/routes/{path}`. The optional catch-all `[[...slug]]`
- * receives `['__r', releaseId, 'routes', ...pathSegments]`. createPage
- * extracts the releaseId and passes it to the content loader, giving
- * each release a unique CDN cache key without a separate route folder.
- * The `routes` namespace segment leaves room for future siblings under
- * the release prefix (e.g. `/__r/{releaseId}/assets/*`).
+ * to `/__r/{releaseId}/{targetRef}`. The target ref selects the exact immutable
+ * base or variant page while its prefix identifies the logical public route.
+ * createPage passes both identities to the content loader, giving each target
+ * a distinct CDN cache key without sending selection headers into Next.
  *
  * Dev pass-through (ACI_CONTENT_PROVIDER=file): the middleware passes
  * requests through unrewritten, so `/` arrives with an empty/undefined
@@ -54,4 +52,29 @@ export declare function createPage(registry: Registry, options?: CreatePageOptio
     generateMetadata: ({ params }: NextPageProps) => Promise<Metadata>;
     default: ({ params }: NextPageProps) => Promise<import("react").JSX.Element>;
 };
+/**
+ * Resolves the logical route and releaseId from Next.js catch-all params.
+ *
+ * Two shapes are supported:
+ *
+ * 1. **Rewritten (production):** middleware rewrites a public URL to the exact
+ *    selected target under `/__r/{releaseId}`. A root variant therefore has
+ *    `['__r', releaseId, '__variant', variantKey]`. The full suffix selects the
+ *    immutable page object; the segments before the reserved `__variant`
+ *    namespace form the logical public route.
+ *
+ * 2. **Dev pass-through (ACI_CONTENT_PROVIDER=file):** middleware passes
+ *    requests through unrewritten, so the slug is the raw public path
+ *    segments (possibly empty/undefined for `/`). No releaseId is present;
+ *    the file provider serves content from disk.
+ */
+export declare function resolveRouteAndRelease(params: Promise<{
+    slug?: string[];
+}> | {
+    slug?: string[];
+}): Promise<{
+    route: string;
+    releaseId?: string;
+    pageRef?: string;
+}>;
 export {};

package/dist/next/page.js

@@ -1,12 +1,15 @@
 import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
 import { notFound } from 'next/navigation.js';
+import { headers } from 'next/headers.js';
 import { Fragment } from 'react';
 import { PageNotFoundError, getRenderInput, getLayout, getFragment, } from './server.js';
+import { MIMIC_BANNER_HEADER, decodeMimicBanner } from '../mimic/core.js';
 import { routeMetadataForContent, resolveSlots, } from '../content/index.js';
 import { renderBlocks } from './render.js';
 import { AssignmentsScript } from './assignments-script.js';
 import { CollectScript } from './collect-script.js';
 import { renderProofContentFor } from '../internal/render-proof.js';
+import { parseHostedPageTarget } from './hosted-page-target.js';
 /**
  * Creates the catch-all route handler for a Next.js ACI site.
  *
@@ -28,12 +31,10 @@ import { renderProofContentFor } from '../internal/render-proof.js';
  * the collect script tag exactly once per page (design/04 contract tag).
  *
  * Release-scoped routes (production): the middleware rewrites a public URL
- * to `/__r/{releaseId}/routes/{path}`. The optional catch-all `[[...slug]]`
- * receives `['__r', releaseId, 'routes', ...pathSegments]`. createPage
- * extracts the releaseId and passes it to the content loader, giving
- * each release a unique CDN cache key without a separate route folder.
- * The `routes` namespace segment leaves room for future siblings under
- * the release prefix (e.g. `/__r/{releaseId}/assets/*`).
+ * to `/__r/{releaseId}/{targetRef}`. The target ref selects the exact immutable
+ * base or variant page while its prefix identifies the logical public route.
+ * createPage passes both identities to the content loader, giving each target
+ * a distinct CDN cache key without sending selection headers into Next.
  *
  * Dev pass-through (ACI_CONTENT_PROVIDER=file): the middleware passes
  * requests through unrewritten, so `/` arrives with an empty/undefined
@@ -49,8 +50,9 @@ import { renderProofContentFor } from '../internal/render-proof.js';
 export function createPage(registry, options) {
     const dynamic = 'force-dynamic';
     async function generateMetadata({ params }) {
-        const { route, releaseId } = await resolveRouteAndRelease(params);
-        const input = await getRenderInput(route, { releaseId });
+        const { route, releaseId, pageRef } = await resolveRouteAndRelease(params);
+        const fetchConfig = { releaseId, pageRef };
+        const input = await getRenderInput(route, fetchConfig);
         const meta = routeMetadataForContent(input.siteConfig, input.page);
         return {
             title: meta.title,
@@ -64,8 +66,8 @@ export function createPage(registry, options) {
         };
     }
     async function CatchAllPage({ params }) {
-        const { route, releaseId } = await resolveRouteAndRelease(params);
-        const fetchConfig = { releaseId };
+        const { route, releaseId, pageRef } = await resolveRouteAndRelease(params);
+        const fetchConfig = { releaseId, pageRef };
         try {
             const input = await getRenderInput(route, fetchConfig);
             if (!input.page)
@@ -84,9 +86,9 @@ export function createPage(registry, options) {
                 }
                 return (_jsx(Fragment, { children: renderedBlocks }, slot.name));
             }));
-            return (_jsxs(_Fragment, { children: [renderProofContent
+            return (_jsxs(_Fragment, { children: [renderedSlots.filter(Boolean), _jsx(AssignmentsScript, { page: input.page }), _jsx(CollectScript, { siteConfig: input.siteConfig }), _jsx(MimicBanner, { html: await readMimicBannerHTML() }), renderProofContent
                         ? _jsx("meta", { name: "aci-render-proof", content: renderProofContent })
-                        : null, renderedSlots.filter(Boolean), _jsx(AssignmentsScript, { page: input.page }), _jsx(CollectScript, { siteConfig: input.siteConfig })] }));
+                        : null] }));
         }
         catch (error) {
             if (error instanceof PageNotFoundError)
@@ -105,19 +107,18 @@ export function createPage(registry, options) {
  *
  * Two shapes are supported:
  *
- * 1. **Rewritten (production):** middleware rewrites a public URL to
- *    `/__r/{releaseId}/routes/{path}`, so slug is
- *    `['__r', releaseId, 'routes', ...pathSegments]`. The releaseId is
- *    extracted; the remaining segments form the content route. The `routes`
- *    segment is the namespace for page routes (siblings like `assets/` live
- *    under the same release prefix).
+ * 1. **Rewritten (production):** middleware rewrites a public URL to the exact
+ *    selected target under `/__r/{releaseId}`. A root variant therefore has
+ *    `['__r', releaseId, '__variant', variantKey]`. The full suffix selects the
+ *    immutable page object; the segments before the reserved `__variant`
+ *    namespace form the logical public route.
  *
  * 2. **Dev pass-through (ACI_CONTENT_PROVIDER=file):** middleware passes
  *    requests through unrewritten, so the slug is the raw public path
  *    segments (possibly empty/undefined for `/`). No releaseId is present;
  *    the file provider serves content from disk.
  */
-async function resolveRouteAndRelease(params) {
+export async function resolveRouteAndRelease(params) {
     const resolved = await params;
     const slug = resolved.slug ?? [];
     if (slug.length >= 2 && slug[0] === '__r') {
@@ -125,13 +126,14 @@ async function resolveRouteAndRelease(params) {
         if (!releaseId || releaseId.includes('/') || releaseId === '.' || releaseId === '..') {
             return { route: '/' };
         }
-        // Skip the 'routes' namespace segment when present.
-        const rest = slug.length >= 3 && slug[2] === 'routes' ? slug.slice(3) : slug.slice(2);
-        if (rest.length === 0)
-            return { route: '/', releaseId };
-        if (rest.some((s) => s === '' || s === '.' || s === '..'))
+        const target = parseHostedPageTarget(slug.slice(2));
+        if (!target)
             return { route: '/' };
-        return { route: `/${rest.join('/')}/`, releaseId };
+        return {
+            route: target.route,
+            releaseId,
+            pageRef: target.pageRef,
+        };
     }
     const route = routeFromSlug(slug);
     return { route };
@@ -141,3 +143,23 @@ function routeFromSlug(slug) {
         return '/';
     return `/${slug.join('/')}/`;
 }
+// The middleware emits the banner HTML in a reserved request header only
+// after validating a signed mimic token; viewer-forged copies are stripped at
+// the dispatch gate (specs/features/audience-mimic REQ-4). The header read
+// happens here (the page already awaits request-scoped data) so the banner
+// itself stays a synchronous leaf.
+async function readMimicBannerHTML() {
+    try {
+        const current = await headers();
+        return decodeMimicBanner(current.get(MIMIC_BANNER_HEADER) || '');
+    }
+    catch {
+        // headers() has no request context in static generation and unit tests.
+        return '';
+    }
+}
+function MimicBanner({ html }) {
+    if (!html)
+        return null;
+    return _jsx("div", { dangerouslySetInnerHTML: { __html: html } });
+}

package/dist/next/personalization-host.d.ts

@@ -88,6 +88,10 @@ export interface PersonalizationHostConfig {
     secureCookies?: boolean;
     now?: () => Date;
     randomBytes?: (length: number) => Uint8Array;
+    mimicClaims?: {
+        aud?: string[];
+        seg?: string[];
+    };
 }
 export interface CookieMutation {
     name: string;

package/dist/next/personalization-host.js

@@ -23,6 +23,9 @@ export class IdentityErasureFencedError extends Error {
 }
 export async function resolvePersonalizationRequest(request, releaseId, config) {
     const requestHeaders = new Headers(request.headers);
+    // The mimic banner header is middleware-emitted only; a viewer-presented
+    // copy never reaches the render.
+    requestHeaders.delete('x-aci-mimic-banner');
     const cookies = parseCookieHeader(request.headers.get('cookie'));
     const consent = consentSignals(request, cookies);
     const mutations = [];
@@ -35,10 +38,14 @@ export async function resolvePersonalizationRequest(request, releaseId, config)
     // re-minting (REQ-4). aci_m is issue-only (D-11): a resolve-path refresh
     // would put a Set-Cookie on every returning visitor's response, defeating
     // the any-Set-Cookie => private, no-store cache rule.
-    let rawIdentity = consent.privacyDenied
+    //
+    // Mimic (audience-mimic): a validated mimicClaims input skips identity
+    // entirely — no read, no mint, no claims-cookie touch (REQ-5).
+    const mimic = config.mimicClaims;
+    let rawIdentity = mimic || consent.privacyDenied
         ? null
         : await verifyIdentityCookie(cookies.get('aci_id') || '', config.identityKeys);
-    if (!consent.privacyDenied && !rawIdentity) {
+    if (!mimic && !consent.privacyDenied && !rawIdentity) {
         rawIdentity = randomIdentity(config.randomBytes);
         const signed = await signIdentity(rawIdentity, config.identityKeys.current);
         const maxAge = config.identityCookieTTLSeconds ?? DEFAULT_IDENTITY_TTL_SECONDS;
@@ -48,7 +55,7 @@ export async function resolvePersonalizationRequest(request, releaseId, config)
     // The identity hash feeds experiment bucketing for EVERY identified
     // visitor. Claims are a signed cookie written by /collect; the EdgeRouter
     // never reads the customer object store to refresh or revoke them.
-    let signedClaims = cookies.get('aci_claims') || '';
+    let signedClaims = mimic ? '' : cookies.get('aci_claims') || '';
     let identityHash = '';
     if (rawIdentity) {
         identityHash = await identityHashHex('aci_id', rawIdentity);
@@ -58,7 +65,9 @@ export async function resolvePersonalizationRequest(request, releaseId, config)
             signedClaims = '';
         }
     }
-    if ((!consent.allowsIdentityTier || !rawIdentity || !signedClaims) && cookies.has('aci_claims')) {
+    // Under mimic the visitor's real aci_claims is never touched (REQ-5) — the
+    // exit path returns them to exactly their pre-mimic state.
+    if (!mimic && (!consent.allowsIdentityTier || !rawIdentity || !signedClaims) && cookies.has('aci_claims')) {
         mutations.push(expireCookie('aci_claims', secure));
     }
     const manifest = await config.store.readEdgeManifest(releaseId);
@@ -66,9 +75,11 @@ export async function resolvePersonalizationRequest(request, releaseId, config)
     let contentPath = route?.dispatch.contentPath || '';
     let variantKey = '';
     if (route) {
-        const claims = consent.allowsIdentityTier
-            ? await verifyClaims(signedClaims, config.claimsKeys || {}, now)
-            : null;
+        const claims = mimic
+            ? { aud: mimic.aud, seg: mimic.seg, iat: 0, exp: 0 }
+            : consent.allowsIdentityTier
+                ? await verifyClaims(signedClaims, config.claimsKeys || {}, now)
+                : null;
         const decision = resolvePersonalizationDecision(toPersonalizationRequestContext(request), route, claims, manifest?.experiments, identityHash
             ? { usable: true, siteId: config.siteId, namespace: 'aci_id', identityHash }
             : undefined);

package/dist/next/server.js

@@ -1,14 +1,18 @@
 import { headers } from 'next/headers.js';
 import { FragmentNotFoundError, LayoutNotFoundError, PageNotFoundError, } from '../content/provider.js';
+import { ObjectContentProvider } from '../providers/object.js';
 import { normalizeRoute } from '../content/routes.js';
 import { getCachedManifest, getCachedSiteConfig } from '../content/cache.js';
 import { S3ContentProvider } from '../providers/s3.js';
+import { VercelReleaseObjectReader } from '../providers/vercel-object-reader.js';
 import { GRADIAL_RENDER_INPUT_HEADER, getPendingRenderInput } from '../runtime/page.js';
 import { attachRenderProofReceipt, selectVerifiedPage, } from '../internal/render-proof.js';
 import { getUncachedEdgeConfigValue } from './edge-config.js';
 import { activeReleaseV1Key, clampDeploymentCompatibleReleaseV1, decodeActiveReleaseV1, decodeDeploymentCompatibilityV1, deploymentCompatibilityKey, } from './vercel-edge-projection-v1.js';
 export { FragmentNotFoundError, PageNotFoundError, LayoutNotFoundError };
-const releaseObjectReaderSymbol = Symbol.for('aci.releaseObjectReader');
+const releaseObjectReaderSymbol = Symbol.for('@gradial/aci.release-object-reader');
+const objectProviders = new WeakMap();
+let vercelReleaseObjectReader;
 export function setReleaseObjectReader(reader) {
     const scope = globalThis;
     if (reader)
@@ -339,6 +343,29 @@ async function resolveS3Provider(config) {
 }
 async function resolveProviderWithFallback(config) {
     const injected = getInjectedReader();
+    const pageRef = config.pageRef;
+    const hostedReaderConfigured = injected || config.roleArn || process.env.AWS_ROLE_ARN;
+    if (pageRef && hostedReaderConfigured) {
+        const releaseId = config.releaseId || process.env.ACI_RELEASE_ID || 'test';
+        let provider = objectProviders.get(config);
+        if (!provider) {
+            if (!injected && !vercelReleaseObjectReader) {
+                vercelReleaseObjectReader = new VercelReleaseObjectReader({
+                    bucket: config.bucket,
+                    keyPrefix: config.keyPrefix,
+                    region: config.region,
+                    roleArn: config.roleArn,
+                    endpoint: config.endpoint,
+                });
+            }
+            const reader = injected || vercelReleaseObjectReader;
+            if (!reader)
+                throw new Error('ACI hosted page reader is unavailable');
+            provider = new ObjectContentProvider({ releaseId, pageRef, reader });
+            objectProviders.set(config, provider);
+        }
+        return provider;
+    }
     if (injected) {
         const releaseId = config.releaseId || process.env.ACI_RELEASE_ID || 'test';
         return new InjectedReaderProvider(releaseId, injected);

package/dist/next/vercel-edge-projection-v1.js

@@ -411,7 +411,7 @@ function validateExperiment(value) {
         'allocationVersion',
         'salt',
         'arms',
-    ], [], 'v1 edge experiment');
+    ], ['eligibilityAudienceId'], 'v1 edge experiment');
     if (!Array.isArray(record.arms)) {
         throw new Error('v1 edge experiment arms must be an array');
     }
@@ -441,6 +441,11 @@ function validateExperiment(value) {
         priority: requiredSafeInteger(record.priority, 'v1 edge experiment priority'),
         allocationVersion: optionalString(record.allocationVersion, 'v1 edge experiment allocation version'),
         salt: optionalString(record.salt, 'v1 edge experiment assignment salt'),
+        ...(Object.prototype.hasOwnProperty.call(record, 'eligibilityAudienceId')
+            ? {
+                eligibilityAudienceId: optionalString(record.eligibilityAudienceId, 'v1 edge experiment eligibility audience ID'),
+            }
+            : {}),
         arms,
     };
 }
@@ -529,6 +534,7 @@ function canonicalExperimentNode(value) {
         ['priority', canonicalUnknownNode(record.priority)],
         ['allocationVersion', canonicalUnknownNode(record.allocationVersion)],
         ['salt', canonicalUnknownNode(record.salt)],
+        ...optionalCanonicalEntry(record, 'eligibilityAudienceId', canonicalUnknownNode),
         [
             'arms',
             record.arms.map((armValue) => {

package/dist/next/vercel-s3-personalization.d.ts

@@ -76,4 +76,5 @@ export declare function createVercelCollectionFromEnv(env?: Record<string, strin
     identityKeys: PersonalizationHostConfig['identityKeys'];
     claimsKeys: Record<string, string>;
     secureCookies: boolean;
+    mimicSignKey?: string;
 } | undefined;

package/dist/next/vercel-s3-personalization.js

@@ -493,6 +493,7 @@ export function createVercelCollectionFromEnv(env = process.env) {
             ...(previousKID ? { [previousKID]: previousSecret } : {}),
         },
         secureCookies: env.AUDIENCE_IDENTITY_COOKIE_SECURE !== 'false',
+        mimicSignKey: env.GRADIAL_PREVIEW_SIGN_KEY || env.ACI_PREVIEW_SIGN_KEY || undefined,
     };
 }
 function requiredSegment(value, label) {

package/dist/providers/s3.js

@@ -78,12 +78,13 @@ export class S3ContentProvider {
     }
     async getLayout(name) {
         const manifest = await this.manifest();
-        const layouts = manifest.layouts;
-        if (!layouts || !layouts[name]) {
+        const entry = manifest.layouts?.[name];
+        if (!entry) {
             throw new LayoutNotFoundError(name);
         }
+        const ref = entry.payloadRef;
         try {
-            return await this.getJSON(`layouts/${name}.json`);
+            return await this.getJSON(ref);
         }
         catch (error) {
             throw new LayoutNotFoundError(name, error);
@@ -199,7 +200,13 @@ export class S3ContentProvider {
         }
         let page;
         try {
-            page = JSON.parse(source);
+            const parsed = JSON.parse(source);
+            if (parsed?.schemaVersion === 'gradial.ssr-page.v1' && parsed.page !== undefined) {
+                page = parsed.page;
+            }
+            else {
+                page = parsed;
+            }
         }
         catch (cause) {
             throw pageIntegrityError(`invalid JSON for ${tuple.contentRef}`, cause);

package/dist/types/block-ref.d.ts

@@ -5,6 +5,7 @@ export interface BlockRefMeta {
     multiple: boolean;
 }
 declare const blockRefBase: z.ZodObject<{
+    $type: z.ZodLiteral<"component">;
     id: z.ZodString;
     component: z.ZodString;
     props: z.ZodRecord<z.ZodString, z.ZodUnknown>;
@@ -12,6 +13,7 @@ declare const blockRefBase: z.ZodObject<{
 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> = {
+    $type: 'component';
     id: string;
     component: InferContractId<T>;
     props: InferContractProps<T>;

package/dist/types/block-ref.js

@@ -1,6 +1,7 @@
 import { z } from 'zod';
 const BLOCK_REF_KEY = '_gradialBlockRef';
 const blockRefBase = z.object({
+    $type: z.literal('component'),
     id: z.string().min(1),
     component: z.string().min(1),
     props: z.record(z.string(), z.unknown()),

package/package.json

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

package/src/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';
@@ -19,14 +20,15 @@ try {
   if (!globalThis.React) 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) {
@@ -430,9 +432,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' },
@@ -741,3 +744,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 };