@gradial/aci 0.1.52-rc.3 → 0.1.52-rc.34-e2e.1

package/dist/mintlify/types.d.ts

@@ -0,0 +1,74 @@
+import type { FragmentRefNode } from '../types/page.js';
+export type MintlifyJSONValue = null | boolean | number | string | MintlifyJSONValue[] | {
+    [key: string]: MintlifyJSONValue;
+};
+export interface MintlifyNavigationGroup {
+    group: string;
+    pages: string[];
+}
+/** Native Mintlify docs.json configuration from `.content/config/mintlify.json`. */
+export type MintlifySite = Record<string, MintlifyJSONValue>;
+export interface MintlifyBlock {
+    $type: 'component';
+    id: string;
+    component: 'mintlify.markdown' | 'mintlify.mdx' | 'mintlify.anchor' | 'mintlify.steps' | 'mintlify.step' | 'mintlify.card-group' | 'mintlify.card' | 'mintlify.accordion-group' | 'mintlify.accordion' | 'mintlify.callout' | 'mintlify.tabs' | 'mintlify.tab' | 'mintlify.snippet-ref';
+    props: {
+        source?: string;
+        name?: string;
+        variant?: 'info' | 'warning' | 'note' | 'tip' | 'check';
+        children?: MintlifyBlock[];
+        [key: string]: MintlifyJSONValue | MintlifyBlock[] | undefined;
+    };
+}
+export interface MintlifyDocument {
+    $type: 'page';
+    id: string;
+    status: string;
+    path: string;
+    metadata: {
+        title: string;
+        description?: string;
+        mintlify?: {
+            sidebarTitle?: string;
+            icon?: string;
+            frontmatter?: Record<string, MintlifyJSONValue>;
+        };
+    };
+    regions: {
+        main: MintlifyBlock[];
+    };
+}
+export interface MintlifySnippet {
+    $type: 'fragment';
+    id: string;
+    path: string;
+    block: MintlifyBlock;
+}
+export interface MintlifyConfigFragment {
+    $type: 'mintlify.config-fragment';
+    schemaVersion: 1;
+    path: string;
+    value: MintlifyJSONValue;
+}
+export interface MintlifyAPISpec {
+    $type: 'mintlify.api-spec';
+    schemaVersion: 1;
+    path: string;
+    format: 'openapi' | 'asyncapi' | 'graphql';
+    source: string;
+}
+export interface MintlifySource {
+    site: MintlifySite;
+    documents: MintlifyDocument[];
+    snippets?: MintlifySnippet[];
+    configFragments?: MintlifyConfigFragment[];
+    apiSpecs?: MintlifyAPISpec[];
+}
+export interface MaterializeMintlifySiteOptions extends Omit<MintlifySource, 'documents'> {
+    documents: Array<Omit<MintlifyDocument, 'regions'> & {
+        regions: {
+            main: Array<MintlifyBlock | FragmentRefNode>;
+        };
+    }>;
+    outputDir: string;
+}

package/dist/mintlify/types.js

@@ -0,0 +1 @@
+export {};

package/dist/mintlify/validate.d.ts

@@ -0,0 +1,7 @@
+import type { MintlifyAPISpec, MintlifyConfigFragment, MintlifyDocument, MintlifyJSONValue, MintlifySite, MintlifySnippet } from './types.js';
+export declare function validateSource(site: MintlifyJSONValue, documents: MintlifyDocument[], snippets: MintlifySnippet[], apiSpecs: MintlifyAPISpec[]): void;
+export declare function validateSite(value: unknown, label: string): MintlifySite;
+export declare function validateDocument(value: unknown, label: string, sourcePath?: string): MintlifyDocument;
+export declare function validateSnippet(value: unknown, label: string, sourcePath?: string): MintlifySnippet;
+export declare function validateConfigFragment(value: unknown, label: string): MintlifyConfigFragment;
+export declare function validateAPISpec(value: unknown, label: string): MintlifyAPISpec;

package/dist/mintlify/validate.js

@@ -0,0 +1,256 @@
+import { validateBlock, validateSnippetReferences } from './blocks.js';
+import { cleanDocumentPath, cleanFilePath, isExternalReference, isMintlifyJSONValue, isObject, nonEmptyString, } from './json.js';
+const CONFIG_FRAGMENT_SCHEMA_VERSION = 1;
+const API_SPEC_SCHEMA_VERSION = 1;
+export function validateSource(site, documents, snippets, apiSpecs) {
+    const paths = new Set();
+    for (const document of documents) {
+        if (paths.has(document.path))
+            throw new Error(`ACI Mintlify document path is duplicated: ${document.path}`);
+        paths.add(document.path);
+    }
+    const navigated = new Set();
+    const navigation = isObject(site) ? site.navigation : undefined;
+    validateNavigationPartitions(navigation);
+    for (const page of navigationPages(navigation)) {
+        // Links are valid Mintlify navigation items but are not ACI documents.
+        if (isExternalReference(page))
+            continue;
+        const normalized = cleanDocumentPath(page);
+        if (!normalized || normalized !== page)
+            throw new Error(`ACI Mintlify navigation page is invalid: ${page}`);
+        if (!paths.has(page))
+            throw new Error(`ACI Mintlify navigation references missing document: ${page}`);
+        if (navigated.has(page))
+            throw new Error(`ACI Mintlify navigation references document more than once: ${page}`);
+        navigated.add(page);
+    }
+    validateRedirects(isObject(site) ? site.redirects : undefined, paths);
+    validateSnippetReferences(documents, snippets);
+    validateAPISpecReferences(site, apiSpecs);
+}
+export function validateSite(value, label) {
+    if (!isObject(value) || !isMintlifyJSONValue(value)) {
+        throw new Error(`ACI Mintlify site is invalid: ${label}`);
+    }
+    if ('$schema' in value && value.$schema !== 'https://mintlify.com/docs.json') {
+        throw new Error(`ACI Mintlify site has an unsupported docs schema: ${label}`);
+    }
+    return value;
+}
+export function validateDocument(value, label, sourcePath) {
+    const metadata = isObject(value) && isObject(value.metadata) ? value.metadata : undefined;
+    const regions = isObject(value) && isObject(value.regions) ? value.regions : undefined;
+    if (!isObject(value) || value.$type !== 'page' || !nonEmptyString(value.id) || !nonEmptyString(value.status) || !nonEmptyString(sourcePath) || !metadata || !nonEmptyString(metadata.title) || !regions || !Array.isArray(regions.main)) {
+        throw new Error(`ACI Mintlify document is invalid: ${label}`);
+    }
+    for (const region of Object.keys(regions)) {
+        if (region !== 'main')
+            throw new Error(`ACI Mintlify document ${label} has unsupported region ${JSON.stringify(region)}; only main is supported`);
+    }
+    const documentPath = cleanDocumentPath(sourcePath);
+    if (!documentPath || documentPath !== sourcePath)
+        throw new Error(`ACI Mintlify document path is invalid: ${sourcePath}`);
+    const ids = new Set();
+    const blocks = regions.main.map((block, index) => validateBlock(block, `${label}.regions.main[${index}]`, ids));
+    const renderer = isObject(metadata.mintlify) ? metadata.mintlify : {};
+    return {
+        $type: 'page', id: value.id, status: value.status, path: documentPath,
+        metadata: { title: metadata.title,
+            ...(nonEmptyString(metadata.description) ? { description: metadata.description } : {}),
+            mintlify: {
+                ...(nonEmptyString(renderer.sidebarTitle) ? { sidebarTitle: renderer.sidebarTitle } : {}),
+                ...(nonEmptyString(renderer.icon) ? { icon: renderer.icon } : {}),
+                ...(validFrontmatter(renderer.frontmatter) ? { frontmatter: renderer.frontmatter } : {}),
+            },
+        }, regions: { main: blocks },
+    };
+}
+export function validateSnippet(value, label, sourcePath) {
+    if (!isObject(value) || value.$type !== 'fragment' || !nonEmptyString(value.id) || !nonEmptyString(sourcePath) || !isObject(value.block)) {
+        throw new Error(`ACI Mintlify snippet is invalid: ${label}`);
+    }
+    const snippetPath = cleanFilePath(sourcePath, '.mdx');
+    if (!snippetPath || snippetPath !== sourcePath)
+        throw new Error(`ACI Mintlify snippet path is invalid: ${sourcePath}`);
+    const ids = new Set();
+    return {
+        $type: 'fragment', id: value.id,
+        path: snippetPath, block: validateBlock(value.block, `${label}.block`, ids),
+    };
+}
+export function validateConfigFragment(value, label) {
+    if (!isObject(value) || value.$type !== 'mintlify.config-fragment' || value.schemaVersion !== CONFIG_FRAGMENT_SCHEMA_VERSION || !nonEmptyString(value.path) || !isMintlifyJSONValue(value.value)) {
+        throw new Error(`ACI Mintlify config fragment is invalid: ${label}`);
+    }
+    const fragmentPath = cleanFilePath(value.path, '.json');
+    if (!fragmentPath || fragmentPath !== value.path || fragmentPath === 'docs.json')
+        throw new Error(`ACI Mintlify config fragment path is invalid: ${value.path}`);
+    return { $type: 'mintlify.config-fragment', schemaVersion: CONFIG_FRAGMENT_SCHEMA_VERSION, path: fragmentPath, value: value.value };
+}
+export function validateAPISpec(value, label) {
+    if (!isObject(value) || value.$type !== 'mintlify.api-spec' || value.schemaVersion !== API_SPEC_SCHEMA_VERSION || !nonEmptyString(value.path) || !['openapi', 'asyncapi', 'graphql'].includes(String(value.format)) || !nonEmptyString(value.source)) {
+        throw new Error(`ACI Mintlify API specification is invalid: ${label}`);
+    }
+    const sourcePath = value.path;
+    const extensions = value.format === 'graphql' ? ['.graphql', '.gql', '.json'] : ['.json', '.yaml', '.yml'];
+    const specPath = extensions.map((extension) => cleanFilePath(sourcePath, extension)).find(Boolean) ?? '';
+    if (!specPath || specPath !== sourcePath)
+        throw new Error(`ACI Mintlify API specification path is invalid: ${sourcePath}`);
+    return {
+        $type: 'mintlify.api-spec',
+        schemaVersion: API_SPEC_SCHEMA_VERSION,
+        path: specPath,
+        format: value.format,
+        source: value.source,
+    };
+}
+function validFrontmatter(value) {
+    if (value === undefined)
+        return false;
+    if (!isObject(value))
+        throw new Error('ACI Mintlify document frontmatter is invalid');
+    for (const [key, entry] of Object.entries(value)) {
+        if (!/^[A-Za-z][A-Za-z0-9_-]*$/.test(key) || !isMintlifyJSONValue(entry)) {
+            throw new Error('ACI Mintlify document frontmatter is invalid');
+        }
+        if (['title', 'description', 'sidebarTitle', 'icon'].includes(key))
+            throw new Error(`ACI Mintlify document frontmatter key is reserved: ${key}`);
+    }
+    return true;
+}
+function validateRedirects(value, documentPaths) {
+    if (value === undefined)
+        return;
+    if (!Array.isArray(value))
+        throw new Error('ACI Mintlify redirects are invalid');
+    const redirects = new Map();
+    const routes = new Set([...documentPaths].map((documentPath) => `/${documentPath}`));
+    for (const entry of value) {
+        if (!isObject(entry) || !nonEmptyString(entry.source) || !nonEmptyString(entry.destination) || (entry.permanent !== undefined && typeof entry.permanent !== 'boolean')) {
+            throw new Error('ACI Mintlify redirect is invalid');
+        }
+        if (!entry.source.startsWith('/') || entry.source.includes('?') || entry.source.includes('#')) {
+            throw new Error(`ACI Mintlify redirect source is invalid: ${entry.source}`);
+        }
+        if (!entry.destination.startsWith('/') && !isExternalReference(entry.destination)) {
+            throw new Error(`ACI Mintlify redirect destination is invalid: ${entry.destination}`);
+        }
+        if (redirects.has(entry.source))
+            throw new Error(`ACI Mintlify redirect source is duplicated: ${entry.source}`);
+        if (!entry.source.includes('*') && !entry.source.includes(':') && routes.has(trimRouteSlash(entry.source))) {
+            throw new Error(`ACI Mintlify redirect source collides with a document: ${entry.source}`);
+        }
+        redirects.set(entry.source, entry.destination);
+    }
+    for (const [source, destination] of redirects) {
+        if (isExternalReference(destination) || destination.includes('*') || destination.includes(':'))
+            continue;
+        const destinationPath = trimRouteSlash(destination.split(/[?#]/, 1)[0]);
+        if (!routes.has(destinationPath) && !redirects.has(destinationPath)) {
+            throw new Error(`ACI Mintlify redirect destination is missing: ${destination}`);
+        }
+        const seen = new Set([source]);
+        let next = destinationPath;
+        while (redirects.has(next)) {
+            if (seen.has(next))
+                throw new Error(`ACI Mintlify redirect cycle includes: ${next}`);
+            seen.add(next);
+            const target = redirects.get(next);
+            if (isExternalReference(target) || target.includes('*') || target.includes(':'))
+                break;
+            next = trimRouteSlash(target.split(/[?#]/, 1)[0]);
+        }
+    }
+}
+function trimRouteSlash(value) {
+    return value.length > 1 ? value.replace(/\/+$/, '') : value;
+}
+function validateAPISpecReferences(site, specs) {
+    const byPath = new Map();
+    for (const spec of specs) {
+        if (byPath.has(spec.path))
+            throw new Error(`ACI Mintlify API specification path is duplicated: ${spec.path}`);
+        byPath.set(spec.path, spec);
+    }
+    const visit = (value) => {
+        if (Array.isArray(value)) {
+            for (const child of value)
+                visit(child);
+            return;
+        }
+        if (!isObject(value))
+            return;
+        for (const [key, child] of Object.entries(value)) {
+            if (['openapi', 'asyncapi', 'graphql'].includes(key)) {
+                const references = typeof child === 'string' ? [child] : Array.isArray(child) ? child.filter((entry) => typeof entry === 'string') : [];
+                for (const reference of references) {
+                    if (isExternalReference(reference))
+                        continue;
+                    const spec = byPath.get(reference);
+                    if (!spec || spec.format !== key)
+                        throw new Error(`ACI Mintlify API specification reference is missing or has the wrong format: ${reference}`);
+                }
+            }
+            visit(child);
+        }
+    };
+    visit(site);
+}
+function navigationPages(value) {
+    if (!isObject(value))
+        return [];
+    const pages = [];
+    visitNavigation(value, pages);
+    return pages;
+}
+function visitNavigation(value, pages) {
+    if (Array.isArray(value)) {
+        for (const item of value)
+            visitNavigation(item, pages);
+        return;
+    }
+    if (!isObject(value))
+        return;
+    for (const [key, child] of Object.entries(value)) {
+        if (key === 'pages' && Array.isArray(child)) {
+            for (const item of child) {
+                if (typeof item === 'string')
+                    pages.push(item);
+                else
+                    visitNavigation(item, pages);
+            }
+            continue;
+        }
+        visitNavigation(child, pages);
+    }
+}
+function validateNavigationPartitions(value) {
+    if (Array.isArray(value)) {
+        for (const child of value)
+            validateNavigationPartitions(child);
+        return;
+    }
+    if (!isObject(value))
+        return;
+    for (const [key, child] of Object.entries(value)) {
+        if ((key === 'languages' || key === 'versions') && Array.isArray(child)) {
+            const identityKey = key === 'languages' ? 'language' : 'version';
+            const identities = new Set();
+            let defaults = 0;
+            for (const entry of child) {
+                if (!isObject(entry) || !nonEmptyString(entry[identityKey]))
+                    throw new Error(`ACI Mintlify ${key} navigation is invalid`);
+                const identity = entry[identityKey];
+                if (identities.has(identity))
+                    throw new Error(`ACI Mintlify ${key} navigation is duplicated: ${identity}`);
+                identities.add(identity);
+                if (entry.default === true)
+                    defaults += 1;
+            }
+            if (defaults > 1)
+                throw new Error(`ACI Mintlify navigation has multiple default ${key}`);
+        }
+        validateNavigationPartitions(child);
+    }
+}

package/dist/next/assignments-navigation.d.ts

@@ -0,0 +1,4 @@
+/** Signals from the committed page tree, including a page with no assignments. */
+export declare function AssignmentsNavigation({ json }: {
+    json: string;
+}): null;

package/dist/next/assignments-navigation.js

@@ -0,0 +1,18 @@
+'use client';
+import { useLayoutEffect } from 'react';
+/** Signals from the committed page tree, including a page with no assignments. */
+export function AssignmentsNavigation({ json }) {
+    // Deliberately runs on each page commit, including unchanged assignment props
+    // on a query navigation. The collector deduplicates hydration/StrictMode and
+    // same-URL/hash commits; discarded concurrent renders never run this effect.
+    useLayoutEffect(() => {
+        const win = window;
+        if (typeof win.aci !== 'function') {
+            const queue = (...args) => { (queue.q ??= []).push(args); };
+            win.aci = queue;
+        }
+        const assignments = json ? JSON.parse(json).experiments : [];
+        win.aci('navigation-complete', { url: win.location.href, assignments });
+    });
+    return null;
+}

package/dist/next/assignments-script.d.ts

@@ -7,8 +7,9 @@ export interface AssignmentsScriptProps {
  * (`<script type="application/json" data-aci-assignments>` with a
  * {"v":1,"experiments":[…]} body, personalization-reporting design/04) when
  * the page payload carries a build-time `experiments` block, and nothing
- * otherwise. createPage appends it to the page tree exactly once per page;
+ * otherwise. Its client commit hook also signals empty pages so SPA
+ * attribution clears when leaving an experiment. createPage appends it to the page tree exactly once per page;
  * sites composing their own pages can render it directly. The JSON body is
  * HTML-safe (assignmentsScriptJSON \u-escapes angle brackets).
  */
-export declare function AssignmentsScript({ page }: AssignmentsScriptProps): import("react").JSX.Element | null;
+export declare function AssignmentsScript({ page }: AssignmentsScriptProps): import("react").JSX.Element;

package/dist/next/assignments-script.js

@@ -1,17 +1,17 @@
-import { jsx as _jsx } from "react/jsx-runtime";
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { AssignmentsNavigation } from './assignments-navigation.js';
 import { assignmentsScriptJSON, } from '../content/personalization.js';
 /**
  * AssignmentsScript renders the page-level experiment assignment tag
  * (`<script type="application/json" data-aci-assignments>` with a
  * {"v":1,"experiments":[…]} body, personalization-reporting design/04) when
  * the page payload carries a build-time `experiments` block, and nothing
- * otherwise. createPage appends it to the page tree exactly once per page;
+ * otherwise. Its client commit hook also signals empty pages so SPA
+ * attribution clears when leaving an experiment. createPage appends it to the page tree exactly once per page;
  * sites composing their own pages can render it directly. The JSON body is
  * HTML-safe (assignmentsScriptJSON \u-escapes angle brackets).
  */
 export function AssignmentsScript({ page }) {
     const json = assignmentsScriptJSON(page);
-    if (!json)
-        return null;
-    return (_jsx("script", { type: "application/json", "data-aci-assignments": "", dangerouslySetInnerHTML: { __html: json } }));
+    return (_jsxs(_Fragment, { children: [json ? _jsx("script", { type: "application/json", "data-aci-assignments": "", dangerouslySetInnerHTML: { __html: json } }) : null, _jsx(AssignmentsNavigation, { json: json })] }));
 }

package/dist/next/error-pages.d.ts

@@ -17,6 +17,10 @@ export interface NextResolvedErrorPage extends ResolvedErrorPage {
  * warn posture (D-5). Never throws: an unreachable site config degrades to
  * the shipped default — an error surface must not re-enter the failing
  * system (ANTI-2).
+ *
+ * The seat receives no route params, so on a hosted request its release
+ * comes from the router's signed release context (resolveReleaseId): the
+ * same release the catch-all of that request was rewritten to.
  */
 export declare function resolveErrorPage(kind: ErrorPageKind, config?: FetchConfig): Promise<NextResolvedErrorPage>;
 /**

package/dist/next/error-pages.js

@@ -11,6 +11,10 @@ import { ErrorPageMarker } from './error-page-marker.js';
  * warn posture (D-5). Never throws: an unreachable site config degrades to
  * the shipped default — an error surface must not re-enter the failing
  * system (ANTI-2).
+ *
+ * The seat receives no route params, so on a hosted request its release
+ * comes from the router's signed release context (resolveReleaseId): the
+ * same release the catch-all of that request was rewritten to.
  */
 export async function resolveErrorPage(kind, config = {}) {
     let siteConfig = null;

package/dist/next/error-seat-payload.d.ts

@@ -13,7 +13,8 @@ import type { ErrorSeatPayload } from './error-seat.js';
  * - present-but-broken bindings — exactly the enumerated REQ-5 failures
  *   (malformed route, unresolved page, unpublished page, audience/experiment
  *   overlays — REQ-11) → `errors` in BOTH postures;
- * - ANY other exception (stale/corrupt compiled content, old manifest
+ * - selected fragment binding or expansion failures are errors in both postures;
+ * - other exceptions (stale/corrupt compiled content, old manifest
  *   shapes) warns-and-defaults under warn and errors only under enforce, so
  *   a stale .aci/compiled tree can never break a binding-less build.
  *

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

@@ -1,3 +1,4 @@
+import { FragmentResolutionError, resolveSlotsSync } from '../content/resolve-slots.js';
 import { existsSync, readFileSync } from 'node:fs';
 import path from 'node:path';
 import { ERROR_PAGE_ROUTE_PATTERN } from '../content/error-pages.js';
@@ -86,29 +87,13 @@ export function buildErrorSeatPayload(contentRoot, posture) {
         const route = bindings.catchAll;
         const page = readJSON(root, catchAllEntry.payloadRef);
         const layout = readJSON(root, `layouts/${page.layout}.json`);
-        const slots = {};
-        const slotOrder = [];
-        for (const slot of layout.slots) {
-            slotOrder.push(slot.name);
-            const pageBlocks = page.regions?.[slot.name];
-            if (pageBlocks?.length) {
-                slots[slot.name] = pageBlocks;
-                continue;
-            }
-            const defaults = layout.defaults?.[slot.name];
-            if (!defaults?.length)
-                continue;
-            const blocks = [];
-            for (const ref of defaults) {
-                const fragmentRef = manifest.fragments[ref.fragmentId]?.payloadRef;
-                if (!fragmentRef)
-                    continue;
-                const fragment = readJSON(root, fragmentRef);
-                blocks.push({ id: fragment.id, component: fragment.component, props: fragment.props || {} });
-            }
-            if (blocks.length)
-                slots[slot.name] = blocks;
-        }
+        const slots = resolveSlotsSync(layout, page.regions ?? {}, (id) => {
+            const fragmentRef = manifest.fragments[id]?.payloadRef;
+            if (!fragmentRef)
+                throw new Error(`Fragment not found: ${id}`);
+            return readJSON(root, fragmentRef);
+        });
+        const slotOrder = layout.slots.map((slot) => slot.name);
         return {
             payload: {
                 defaulted: false,
@@ -123,7 +108,12 @@ export function buildErrorSeatPayload(contentRoot, posture) {
         };
     }
     catch (error) {
-        // Not one of the enumerated REQ-5 binding failures (those are pushed to
+        if (error instanceof FragmentResolutionError) {
+            errors.push(error.message);
+            return defaulted();
+        }
+        // Neither a selected-fragment failure nor an enumerated REQ-5 binding
+        // failure (those are pushed to
         // `errors` above): stale/corrupt compiled content or an old manifest
         // shape. Warn-and-default under the warn posture so it can never break a
         // build; fail closed only under enforce (quorum RISK-002).

package/dist/next/error-seat.js

@@ -69,7 +69,7 @@ function renderPayload(data, registry) {
 // async and server-oriented). Unknown components are skipped — the error
 // seat degrades, it never crashes.
 function renderClientBlocks(blocks, registry) {
-    return blocks.map((block) => {
+    return blocks.map((block, index) => {
         const entry = registry.find((r) => r.id === block.component);
         if (!entry)
             return null;
@@ -78,6 +78,11 @@ function renderClientBlocks(blocks, registry) {
         if (entry.contract.blockSlots) {
             componentProps.renderChildren = (children) => renderClientBlocks(children, registry);
         }
-        return _jsx(Component, { ...componentProps }, block.id);
+        // sdk I-19 (ADR 0051): the error seat is an injection seam too.
+        componentProps['data-aci-block'] = block.id;
+        componentProps['data-aci-component'] = block.component;
+        // Index+id composite: a repeated fragment placement repeats its authored
+        // id, and sibling keys must stay unique for React reconciliation.
+        return _jsx(Component, { ...componentProps }, `${index}:${block.id}`);
     });
 }

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

@@ -2,10 +2,10 @@ export { DevRefresh, type DevRefreshProps } from './dev-refresh.js';
 export { withAci, type WithAciOptions } from './config.js';
 export { isPreviewMode } from './preview-mode.js';
 export { createPage, type CreatePageOptions, type SlotPropsFn } from './page.js';
+export { renderBlock, renderBlocks } from './render.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

@@ -2,10 +2,12 @@ export { DevRefresh } from './dev-refresh.js';
 export { withAci } from './config.js';
 export { isPreviewMode } from './preview-mode.js';
 export { createPage } from './page.js';
+// The block renderer seam (sdk I-19, ADR 0051): exported so a site's own
+// conformance test can prove its components carry root identity.
+export { renderBlock, renderBlocks } from './render.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 {};