@gradial/aci 0.1.48 → 0.1.51-ssr.2

package/templates/common/.agents/skills/authoring/references/block-registry.md

@@ -45,13 +45,10 @@ The SDK provides `createPage(registry)` which owns param normalization, content
 loading, layout resolution, metadata generation, notFound handling, slot
 resolution (including fragment defaults), and block rendering.
 
-Path shape: `/__r/{releaseId}/routes/{...slug}`. The SDK extracts releaseId
-internally; middleware rewrites public URLs to `/__r/{releaseId}/routes/{path}`
-for the app-level route. The `routes` namespace leaves room for future siblings
-under the release prefix. The filesystem uses an **optional catch-all** `[[...slug]]`
-(not required `[...slug]`). Production middleware always rewrites to
-`/__r/{releaseId}/routes/{path}`, but file-provider local dev passes requests
-unrewritten so `/` arrives with an empty slug.
+The filesystem uses an **optional catch-all** `[[...slug]]` (not required
+`[...slug]`) so file-provider local development can render `/`. During publish,
+the compiler invokes this route with an isolated render input; hosted CMS
+traffic is served from the resulting immutable HTML and does not enter Next.
 
 Chrome (Header/Footer) is **not** in `layout.tsx`. It is CMS-managed via
 layout fragment defaults. The `layout.tsx` file is minimal and includes
@@ -197,41 +194,21 @@ the rewrite automatically.
 | Storybook | `.storybook/main.ts`, `.storybook/preview.ts` |
 | Assets | CloudFront function rewrite (automatic, no infrastructure changes needed) |
 
-## Middleware
+## Hosted routing
 
-Middleware requires explicit `siteId`. The SDK exports a canonical matcher that
-repos re-export:
-
-```ts
-// src/middleware.ts
-import { createGradialMiddleware } from '@gradial/aci/next/middleware';
-export { config } from '@gradial/aci/next/middleware';
-export default createGradialMiddleware({ siteId: 'your-tenant-id' });
-```
-
-The middleware rewrites public URLs to `/__r/{releaseId}/routes/{path}` for
-the app-level route. The SDK extracts releaseId internally.
+Do not add customer middleware for CMS routing. Provider edge bundles own
+release/variant selection and protected immutable-artifact dispatch outside the
+framework. Next receives neither the dispatch assertion nor a content reference.
 
 ## Asset Routes
 
-**Preferred: NO app-level asset route.** Assets are served via URL rewrite
-(Next.js `withAci()`) or CloudFront function rewrite (Astro/CloudFront) directly
-to S3.
+Do not add an app-level asset route. Host adapters serve immutable browser and
+DAM assets directly from S3/R2/CDN storage. Next's `withAci()` supports an
+explicit direct asset-origin rewrite for local/custom builds.
 
 DAM derivative assets are content-addressed and globally shared — staged once at
-`{keyPrefix}/.gradial-dam/` and shared across all releases. The SDK's `withAci()`
-already injects a `/.gradial-dam/:path*` rewrite. For CloudFront, the existing
-CloudFront function handles the rewrite automatically.
-
-For transitional compatibility, the SDK still exports an asset route handler:
-
-```ts
-// src/app/gradial/assets/[...path]/route.ts (transitional)
-export { GET, runtime, dynamic } from '@gradial/aci/next/asset-route';
-```
-
-**Note**: Asset URLs do NOT include `[releaseId]` in the path. DAM assets are
-globally scoped and content-addressed via filename hashes.
+`{keyPrefix}/.gradial-dam/` and shared across all releases. Asset URLs do not
+need a release segment because their filenames bind content.
 
 ## Anti-Patterns
 

package/templates/common/.agents/skills/authoring/references/contracts.md

@@ -121,19 +121,11 @@ source:
 componentRegistry: ./src/cms/contracts/components/index.ts
 layoutRegistry: ./src/cms/contracts/layouts/index.ts
 
-capabilities:
-  staticRender: true
-  ssr: true
-  ssrIslands: true
-  clientIslands: true
-  fragmentRender: true
+# Optional for custom renderers; Astro/Next use framework conventions.
+# rendererEntry: ./src/cms/renderer.ts
 
 routes:
   cmsManaged: "/[[...slug]]"
-  frameworkOwned:
-    - "/api/*"
-    - "/_next/*"       # Next.js
-    - "/.gradial-dam/*"
 
 rendererProtocol: stdio-json
 ```
@@ -150,20 +142,21 @@ rendererProtocol: stdio-json
 | `source.publicDir` | Public assets directory (Astro) |
 | `componentRegistry` | Path to component contract barrel |
 | `layoutRegistry` | Path to layout contract barrel |
-| `capabilities` | Render capabilities (static, SSR, islands, fragments) |
+| `rendererEntry` | Optional renderer entry override; omit for framework conventions |
 | `routes.cmsManaged` | Catch-all route pattern for CMS pages |
-| `routes.frameworkOwned` | Route patterns excluded from CMS routing |
 | `rendererProtocol` | Renderer communication protocol |
 
-### Removed fields
+### Retired fields
 
-- `rendererEntry` has been removed from `.aci.yaml`. Do not include it.
+- `capabilities` is rejected. Deterministic CMS delivery always produces
+  complete static HTML.
+- `routes.frameworkOwned` is rejected. Application-owned routes are a separate
+  hosting contract, not a fallback from CMS delivery.
 
 ### Rules
 
 - `componentRegistry` and `layoutRegistry` point to contract-only modules.
 - No secrets in `.aci.yaml`, docs, fixtures, or generated files.
 - The `cmsManaged` route pattern should match the filesystem: use `/[[...slug]]`
-  (optional catch-all) for Next.js repos. Production middleware always rewrites
-  to `/__r/{releaseId}/routes/{path}` so slug is non-empty, but file-provider
-  local dev passes requests unrewritten so `/` arrives with an empty slug.
+  (optional catch-all) for Next.js repos so local `/` arrives with an empty
+  slug. Hosted routing selects already-rendered artifacts outside Next.

package/templates/common/.agents/skills/authoring/references/repo-structure.md

@@ -104,8 +104,8 @@ Only Next.js and Astro are supported. SvelteKit support has been removed.
 | Root layout | `src/app/layout.tsx` (minimal — imports CSS, includes `<DevRefresh />`, no chrome) |
 | Config | `next.config.ts` with bare `withAci()` |
 | Registry | `src/cms/registry.ts` (shared, `createRegistry` with `[contract, component]` tuples) |
-| Middleware | `src/middleware.ts` with `createGradialMiddleware({ siteId })` and SDK-exported matcher |
-| Asset route | `src/app/gradial/assets/[...path]/route.ts` — thin SDK re-export from `@gradial/aci/next/asset-route`. Serves CMS documents (robots.txt, sitemap.xml) via withAci rewrites and local-dev DAM assets. Hand-rolled asset routes and the legacy release-scoped `[releaseId]/[...path]` variant are banned. Astro has no route (CDN/global path). |
+| Middleware | None for CMS routing; the provider host bundle selects immutable artifacts outside Next |
+| Asset route | None; host gateways serve immutable browser/DAM assets directly and conformance rejects request-time Next asset routes |
 
 ### Astro
 

package/templates/common/.agents/skills/authoring/references/sdk-server-functions.md

@@ -2,10 +2,11 @@
 
 ## `@gradial/aci/next` Exports
 
-The SDK provides server-side functions that handle content resolution
-across preview, local file, and deployed S3 modes. **Always use these
-functions instead of directly importing `FileContentProvider` or
-`S3ContentProvider`.** The SDK handles the resolution chain automatically.
+The SDK provides server-side functions for the publish-time Next renderer and
+local file-backed development. They resolve either a compiler-injected render
+input or `.aci/compiled` content. Hosted CMS requests do not enter Next and
+these functions never resolve a mutable provider pointer or fetch deployed page
+content from S3.
 
 ### `createPage(registry, options?)`
 
@@ -14,11 +15,9 @@ normalization, content loading via render input, metadata generation,
 `notFound` handling, layout resolution, and block rendering via the
 registry.
 
-Path shape: in production, middleware rewrites to `/__r/{releaseId}/routes/{...slug}`.
-The SDK's `resolveRouteAndRelease` decomposes `['__r', releaseId, 'routes', ...pathSegments]`.
-In local dev (`ACI_CONTENT_PROVIDER=file`), requests pass through unrewritten, so `/`
-arrives with an empty/undefined slug. The filesystem uses an **optional catch-all**
-`[[...slug]]` to handle both shapes.
+The filesystem uses an **optional catch-all** `[[...slug]]` so local `/`
+requests arrive with an empty slug. During publish, the compiler invokes the
+same route against an isolated render input and captures complete HTML.
 
 ```tsx
 // src/app/[[...slug]]/page.tsx
@@ -38,11 +37,10 @@ fragments.
 
 ### `withAci(nextConfig?, options?)`
 
-Next.js config wrapper. Owns all canonical SDK behavior: output mode,
-outputFileTracingRoot, base-path/build-mode/dist-dir env injection, CDN
-headers, asset rewrites (`/.gradial-dam` prefix), content-watch plugin,
-and public-path scanning. Repos should pass a bare `withAci()` call and
-rely on SDK defaults.
+Next.js config wrapper for the local-dev and publish-time renderer capsule. It
+owns standalone output, `outputFileTracingRoot`, optional direct asset-origin
+rewrites, content watching, and error-page build payloads. Repos should pass a
+bare `withAci()` call unless they have an explicit CDN asset origin.
 
 ```ts
 // next.config.ts
@@ -51,22 +49,15 @@ import { withAci } from '@gradial/aci/next/config';
 export default withAci();
 ```
 
-For site-specific non-CMS routes, pass `passthroughRoutes`:
-
-```ts
-export default withAci({
-  passthroughRoutes: ['/api/*', '/admin/*'],
-});
-```
-
-Do not manually configure outputFileTracing, base-path, build-mode, dist-dir,
-or custom rewrites/redirects for ACI concerns. The SDK handles these.
+Do not add routing middleware or request-time content rewrites for CMS routes.
+Provider hosting bundles own public route selection and immutable artifact
+delivery outside the Next application.
 
 ### `getSiteConfig<T>()`
 
-Loads the site configuration. Checks the render input header first
-(preview mode), then falls back to file or S3 provider. **MUST be used
-in `layout.tsx` instead of `new FileContentProvider()`.**
+Loads the site configuration from the current compiler render input, then from
+the local file provider. **MUST be used in `layout.tsx` instead of constructing
+a provider directly.**
 
 ```tsx
 import { getSiteConfig } from '@gradial/aci/next';
@@ -79,23 +70,21 @@ Generic: pass your site config interface for typed access:
 
 ### `getFragment(name)`
 
-Loads a fragment by name. Checks render input first (preview mode), then
-provider fallback.
+Loads a fragment by name from the compiler render input or local files.
 
 ### `getLayout(name)`
 
-Loads a layout by name. Checks render input first (preview mode), then
-provider fallback.
+Loads a layout by name from the compiler render input or local files.
 
 ### `getPage(route)`
 
-Loads page content for a specific route. Checks render input first
-(preview mode), then provider fallback.
+Loads page content for a specific route from the compiler render input or local
+files.
 
 ### `getRenderInput(route)`
 
 Loads the full render input (page + siteConfig + domain + locale). Used
-internally by `createPage`. Available for custom server composition when
+internally by `createPage`. Available for custom publish-time rendering when
 you need the full render context.
 
 ### `routeFromNextParams(params)`
@@ -113,37 +102,13 @@ const previewRelease = await isPreviewMode();
 if (previewRelease) { /* preview-specific logic */ }
 ```
 
-### `createGradialMiddleware(config)`
-
-Creates Next.js middleware for ACI sites. Requires explicit `siteId`.
-
-```ts
-// src/middleware.ts
-import { createGradialMiddleware } from '@gradial/aci/next/middleware';
-
-export default createGradialMiddleware({ siteId: 'your-tenant-id' });
-export { config } from '@gradial/aci/next/middleware';
-```
-
-The SDK exports a canonical middleware matcher via the `config` export. Repos
-should re-export it verbatim. Do not hand-roll custom matcher patterns unless
-site-specific static paths require exclusions.
+### Provider-owned routing
 
-**Config interface:**
-
-```ts
-export interface GradialMiddlewareConfig {
-  siteId: string;                              // REQUIRED
-  edgeConfig?: string;
-  previewSignKey?: string;
-  deploymentId?: string;
-  deploymentProtectionBypass?: string;
-}
-```
-
-The middleware rewrites public URLs to `/__r/{releaseId}/routes/{path}` for
-the app-level route. The SDK extracts releaseId and resolves the content route
-internally.
+Do not add `src/middleware.ts` for CMS routing. Vercel's composed Build Output
+contains host-owned middleware and a protected static gateway; CloudFront and
+Cloudflare have equivalent provider adapters. They select and serve an
+immutable artifact without passing a release selector, content reference, or
+dispatch assertion into Next.
 
 ### `DevRefresh`
 
@@ -172,50 +137,35 @@ import { DevRefresh } from '@gradial/aci/next';
 `createPage` catches `PageNotFoundError` and calls `notFound()`
 automatically.
 
-## Three-Tier Content Resolution
+## Two Build-Time Content Inputs
 
-Every SDK server function follows the same resolution chain:
+Every SDK server function follows the same local/publish-time resolution chain:
 
-### Tier 1: Render Input (Preview Mode)
+### Tier 1: Compiler Render Input
 
 When the Go harness sends a render request, it sets the
 `x-gradial-render-input-id` header. The SDK checks the
 `pendingRenderInputs` in-process map for a matching render input and
-returns page data directly from the Go harness's render payload. This
-is how preview works — the harness pushes content into the Next.js
-process without touching S3 or disk.
+returns page data directly from the Go harness's render payload. This is how
+preview and publish render a finite content snapshot without giving the
+framework live storage authority.
 
 ### Tier 2: File Provider (`ACI_CONTENT_PROVIDER=file`)
 
-When the `ACI_CONTENT_PROVIDER` environment variable is set to `file`,
-the SDK reads compiled content from `.aci/compiled/` on disk. This is
-the local development path. Also used as a fallback in preview mode when
-no render input header is present.
-
-### Tier 3: S3 Provider (Deployed SSR)
-
-When neither render input nor file provider is active, the SDK reads
-from S3. The release ID is resolved from (in order):
-
-1. `x-gradial-release-id` header (set by middleware)
-2. `ACI_RELEASE_ID` environment variable
-3. Vercel Edge Config active release pointer
+Without a compiler render input, the SDK reads compiled content from
+`.aci/compiled/` on disk. This is the local development path. There is no third
+request-time S3 or Edge Config tier.
 
 ## Critical Rule
 
-**NEVER import `FileContentProvider` or `S3ContentProvider` directly in
-app code.** Always use `getPage()`, `getSiteConfig()`, `getFragment()`,
+**NEVER construct a content provider directly in app code.** Always use
+`getPage()`, `getSiteConfig()`, `getFragment()`,
 `getLayout()`, or `getRenderInput()` from `@gradial/aci/next`. The SDK
-handles the resolution chain automatically.
-
-The only exception is the transitional asset route handler
-(`src/app/gradial/assets/[...path]/route.ts`), which directly
-uses `FileContentProvider` for local asset serving and
-`getReleaseAssetResponse` for S3 assets. The preferred path is to use no
-app-level asset route at all (`withAci()` handles rewrites for Next.js;
-CloudFront function rewrite for Astro). DAM derivative assets are
-content-addressed and globally shared — staged once at `{keyPrefix}/.gradial-dam/`
-and shared across all releases.
+keeps the compiler-input and local-file boundary explicit.
+
+Do not add an app-level asset route. Host gateways serve immutable browser and
+DAM assets directly; `withAci()` may rewrite to an explicitly configured asset
+origin for local/custom builds.
 
 ## Layout.tsx Pattern
 

package/templates/common/.agents/skills/migration/references/canon-migration.md

@@ -47,19 +47,11 @@ export default defineConfig({
 Delete manual env-var plumbing, outputFileTracing, custom rewrites/redirects
 for ACI concerns.
 
-### 4. Middleware: Require `siteId`
+### 4. Middleware: Remove Customer Ownership
 
-Update middleware to pass explicit `siteId`:
-
-```ts
-// src/middleware.ts
-import { createGradialMiddleware } from '@gradial/aci/next/middleware';
-export { config } from '@gradial/aci/next/middleware';
-export default createGradialMiddleware({ siteId: 'your-tenant-id' });
-```
-
-Re-export the SDK's canonical matcher via `config`. Delete custom matchers
-unless site-specific static paths require exclusions.
+Delete `src/middleware.ts` when it performs CMS routing. The provider host bundle
+owns release/variant selection and protected immutable-artifact delivery outside
+the framework; customer code must not implement a second decision path.
 
 ### 5. Path Shape: `[[...slug]]` (Optional Catch-All)
 
@@ -76,10 +68,9 @@ routes:
   cmsManaged: "/[[...slug]]"
 ```
 
-Production middleware always rewrites to `/__r/{releaseId}/routes/{path}` so
-slug is non-empty there, but file-provider local dev passes requests
-unrewritten so `/` arrives with an empty slug. A required catch-all 404s
-the dev homepage.
+File-provider local development sends `/` to the framework with an empty slug,
+so a required catch-all 404s the dev homepage. Hosted CMS requests use the
+provider's immutable artifact path and do not enter this Next route.
 
 ### 6. DevRefresh Mandated
 
@@ -235,22 +226,14 @@ conformancePreset({
 
 4. **Remove Custom Asset Route**
 
-   Delete `src/app/gradial/assets/[releaseId]/[...path]/route.ts` (with extra
-   `[releaseId]` segment). Replace with standard path:
-
-   ```ts
-   // src/app/gradial/assets/[...path]/route.ts
-   export { GET, runtime, dynamic } from '@gradial/aci/next/asset-route';
-   ```
-
-   The SDK asset-route handler resolves releaseId internally. No need for an
-   explicit path segment.
+   Delete every `src/app/gradial/assets/**/route.ts` form. Do not replace it;
+   provider gateways serve immutable browser and DAM assets directly.
 
 5. **Delete `content-assets` Route and `.gradial-dam` Rewrite**
 
-   Delete `src/app/content-assets/[...key]/route.ts` and remove the
-   `.gradial-dam` rewrite from `next.config.ts`. The SDK asset route handles
-   both dev-mode file serving and deployed S3 serving.
+   Delete `src/app/content-assets/[...key]/route.ts` and any hand-written
+   request-time `.gradial-dam` rewrite. The SDK adapter owns local development;
+   provider gateways own deployed asset delivery.
 
 6. **Delete Runtime `layouts.ts`**
 
@@ -313,13 +296,10 @@ conformancePreset({
    ];
    ```
 
-2. **Add `siteId` to Middleware**
-
-   Update middleware to pass explicit `siteId`:
+2. **Remove Customer Middleware**
 
-   ```ts
-   export default createGradialMiddleware({ siteId: 'bnc' });
-   ```
+   Delete `src/middleware.ts` when it implements CMS release or variant
+   selection. Provider routing occurs outside the framework.
 
 3. **General Migration Steps**
 
@@ -444,10 +424,10 @@ The preset validates (default checks):
 - `config` -- `withAci()` present in config
 - `registry` -- `createRegistry()` usage (no hand-rolled maps)
 - `pageEntry` -- `createPage(registry)` usage in catch-all route
-- `middleware` -- `createGradialMiddleware({ siteId })` with correct siteId
+- `middleware` -- no customer middleware implementing a second CMS decision path
 - `noFileContentProvider` -- no direct `FileContentProvider` imports in app code
 - `noCustomContent` -- no `src/lib/content.ts` shim
-- `noLegacyAssetRoute` -- no `[releaseId]` segment in asset route path
+- `noRequestTimeAssetRoute` -- no Next asset-delivery route
 - `sdkVersion` -- SDK version >= 0.1.31
 
 Optional (disabled by default, shell out):

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

@@ -9,18 +9,7 @@ source:
 componentRegistry: ./src/cms/contracts/components/index.ts
 layoutRegistry: ./src/cms/contracts/layouts/index.ts
 
-capabilities:
-  staticRender: true
-  ssr: true
-  ssrIslands: true
-  clientIslands: true
-  fragmentRender: true
-
 routes:
   cmsManaged: "/[...slug]"
-  frameworkOwned:
-    - "/api/*"
-    - "/_next/*"
-    - "/.gradial-dam/*"
 
 rendererProtocol: stdio-json

package/templates/nextjs/template/README.md.tmpl

@@ -47,6 +47,5 @@ src/cms/               Contracts and component registry
 src/components/        Runtime React components
 src/design-system/     Design tokens and global styles
 src/app/               Next.js App Router pages and routes
-src/middleware.ts       ACI middleware (siteId, release routing)
 .agents/skills/        Skills for humans and agents
 ```

package/templates/nextjs/template/src/app/[[...slug]]/page.tsx

@@ -5,4 +5,4 @@ const page = createPage(registry);
 
 export const dynamic = 'force-dynamic';
 export const generateMetadata = page.generateMetadata;
-export default page.default;
+export default page.default;

package/dist/content/assets.d.ts

@@ -1,18 +0,0 @@
-export interface ReleaseAssetConfig {
-    bucket?: string;
-    keyPrefix?: string;
-    region?: string;
-    accessKeyId?: string;
-    secretAccessKey?: string;
-    sessionToken?: string;
-    roleArn?: string;
-    endpoint?: string;
-}
-export declare class ReleaseAssetNotFoundError extends Error {
-    constructor(releaseId: string, assetPath: string, cause?: unknown);
-}
-export declare function getReleaseAssetResponse(input: {
-    releaseId: string;
-    assetPath: string;
-    config?: ReleaseAssetConfig;
-}): Promise<Response>;

package/dist/content/assets.js

@@ -1,66 +0,0 @@
-import { S3ContentProvider } from '../providers/s3.js';
-export class ReleaseAssetNotFoundError extends Error {
-    constructor(releaseId, assetPath, cause) {
-        super(`ACI release asset not found: ${releaseId}/${assetPath}`);
-        this.name = 'ReleaseAssetNotFoundError';
-        this.cause = cause;
-    }
-}
-export async function getReleaseAssetResponse(input) {
-    const clean = cleanAssetPath(input.assetPath);
-    if (!input.releaseId || !clean) {
-        throw new ReleaseAssetNotFoundError(input.releaseId, input.assetPath);
-    }
-    const config = input.config ?? {};
-    const provider = new S3ContentProvider({
-        bucket: config.bucket,
-        keyPrefix: releaseKey(config, input.releaseId),
-        region: config.region,
-        accessKeyId: config.accessKeyId,
-        secretAccessKey: config.secretAccessKey,
-        sessionToken: config.sessionToken,
-        roleArn: config.roleArn,
-        endpoint: config.endpoint,
-    });
-    const key = joinKey(provider.config.keyPrefix, 'assets', clean);
-    const res = await provider.fetchRaw(key);
-    if (!res.ok || !res.body) {
-        throw new ReleaseAssetNotFoundError(input.releaseId, clean, await safeResponseText(res));
-    }
-    const headers = new Headers();
-    copyHeader(res.headers, headers, 'content-type');
-    copyHeader(res.headers, headers, 'content-length');
-    copyHeader(res.headers, headers, 'etag');
-    copyHeader(res.headers, headers, 'last-modified');
-    headers.set('cache-control', 'public, max-age=300, must-revalidate');
-    return new Response(res.body, { status: 200, headers });
-}
-function cleanAssetPath(value) {
-    const clean = value.replace(/^\/+|\/+$/g, '').replace(/\/+/g, '/');
-    if (!clean || clean.split('/').some((segment) => segment === '..' || segment === '.'))
-        return '';
-    return clean;
-}
-function copyHeader(from, to, name) {
-    const value = from.get(name);
-    if (value)
-        to.set(name, value);
-}
-async function safeResponseText(res) {
-    try {
-        return await res.text();
-    }
-    catch {
-        return '';
-    }
-}
-function releaseKey(config, releaseId) {
-    return joinKey(config.keyPrefix || process.env.ACI_S3_KEY_PREFIX || '', 'releases', releaseId);
-}
-function joinKey(...parts) {
-    return parts
-        .filter(Boolean)
-        .map((part) => part.replace(/^\/+|\/+$/g, ''))
-        .filter(Boolean)
-        .join('/');
-}

package/dist/edge/personalization-core.d.ts

@@ -1,11 +0,0 @@
-export function selectPersonalizationVariant(request: any, route: any, claims: any, experiments: any, identity: any): any;
-export function resolvePersonalizationDecision(request: any, route: any, claims: any, experiments: any, identity: any): {
-    variant: any;
-    experiment: {
-        experimentId: any;
-        armId: any;
-        allocationVersion: string;
-        variantKey: any;
-        bucket: number;
-    } | null;
-};

package/dist/internal/render-proof.d.ts

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