@gradial/aci 0.1.51-ssr.3 → 0.1.51-ssr.5

package/README.md

@@ -1,6 +1,6 @@
 # Agentic Content Infrastructure SDK
 
-`@gradial/aci` `0.1.51-ssr.3` is a pre-1.0 public-surface reset for the ACI
+`@gradial/aci` `0.1.51-ssr.5` 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.51-ssr.3 zod@^4
+npm install @gradial/aci@0.1.51-ssr.5 zod@^4
 ```
 
 ## Root Import
@@ -78,13 +78,13 @@ host bundles select and serve immutable release artifacts.
 The first RC scaffold path is Next:
 
 ```bash
-npx @gradial/aci@0.1.51-ssr.3 init my-site --template next-starter
+npx @gradial/aci@0.1.51-ssr.5 init my-site --template next-starter
 ```
 
 List available templates:
 
 ```bash
-npx @gradial/aci@0.1.51-ssr.3 init --list
+npx @gradial/aci@0.1.51-ssr.5 init --list
 ```
 
 ## Personalization: The One-Tag Install

package/dist/next/error-pages.js

@@ -15,11 +15,16 @@ import { ErrorPageMarker } from './error-page-marker.js';
 export async function resolveErrorPage(kind) {
     let siteConfig = null;
     const warnings = [];
-    try {
-        siteConfig = await getSiteConfig();
-    }
-    catch (error) {
-        warnings.push(`site config unavailable at the error seat: ${String(error)}`);
+    // A deployed SSR release has no local `.aci/compiled` tree. The error
+    // seat must remain independent of the renderer that just failed, so serve
+    // the shipped default rather than opening FileContentProvider here.
+    if (process.env.HOSTING_DELIVERY_MODE !== 'ssr') {
+        try {
+            siteConfig = await getSiteConfig();
+        }
+        catch (error) {
+            warnings.push(`site config unavailable at the error seat: ${String(error)}`);
+        }
     }
     const resolved = await resolveErrorPageForSite(kind, siteConfig);
     return { ...resolved, warnings: [...warnings, ...resolved.warnings], siteConfig };

package/dist/next/page.js

@@ -43,18 +43,24 @@ export function createPage(registry, options) {
     const dynamic = 'force-dynamic';
     async function generateMetadata({ params }) {
         const resolved = await resolveRoute(params);
-        const input = await getRenderInput(resolved.route, resolved.context);
-        const meta = routeMetadataForContent(input.siteConfig, input.page);
-        return {
-            title: meta.title,
-            description: meta.description,
-            alternates: meta.canonical ? { canonical: meta.canonical } : undefined,
-            openGraph: {
+        try {
+            const input = await getRenderInput(resolved.route, resolved.context);
+            const meta = routeMetadataForContent(input.siteConfig, input.page);
+            return {
                 title: meta.title,
                 description: meta.description,
-                siteName: meta.siteName,
-            },
-        };
+                alternates: meta.canonical ? { canonical: meta.canonical } : undefined,
+                openGraph: {
+                    title: meta.title,
+                    description: meta.description,
+                    siteName: meta.siteName,
+                },
+            };
+        }
+        catch (error) {
+            logRenderFailure('metadata', resolved, error);
+            throw error;
+        }
     }
     async function CatchAllPage({ params }) {
         const resolved = await resolveRoute(params);
@@ -63,8 +69,13 @@ export function createPage(registry, options) {
             const input = await getRenderInput(resolved.route, context);
             if (!input.page)
                 notFound();
-            const layout = await getLayout(input.page.layout, context);
-            const resolvedSlots = await resolveSlots(layout, input.page.regions || {}, (id) => getFragment(id, context));
+            const provider = input.contentProvider;
+            const layout = provider
+                ? await provider.getLayout(input.page.layout)
+                : await getLayout(input.page.layout, context);
+            const resolvedSlots = await resolveSlots(layout, input.page.regions || {}, (id) => provider
+                ? provider.getFragment(id)
+                : getFragment(id, context));
             const renderedSlots = await Promise.all(layout.slots.map(async (slot) => {
                 const blocks = resolvedSlots[slot.name];
                 if (!blocks?.length)
@@ -81,6 +92,7 @@ export function createPage(registry, options) {
         catch (error) {
             if (error instanceof PageNotFoundError)
                 notFound();
+            logRenderFailure('page', resolved, error);
             throw error;
         }
     }
@@ -95,7 +107,9 @@ export function createPage(registry, options) {
  */
 async function resolveRoute(params) {
     const resolved = await params;
-    const slug = resolved.slug ?? [];
+    const slug = decodePathSegments(resolved.slug ?? []);
+    if (!slug)
+        return { route: '/' };
     if (slug.length >= 2 && slug[0] === '__r') {
         const releaseId = slug[1];
         const selected = slug.slice(2);
@@ -129,3 +143,22 @@ function portableReleaseId(value) {
 function portablePathPart(value) {
     return value.length > 0 && value !== '.' && value !== '..' && !value.includes('/');
 }
+function decodePathSegments(segments) {
+    try {
+        return segments.map((segment) => decodeURIComponent(segment));
+    }
+    catch {
+        return null;
+    }
+}
+function logRenderFailure(phase, resolved, error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    console.error(JSON.stringify({
+        message: 'aci.ssr.render_failed',
+        phase,
+        releaseId: resolved.context?.releaseId,
+        pageRef: resolved.context?.pageRef,
+        route: resolved.route,
+        error: detail.slice(0, 512),
+    }));
+}

package/dist/next/server.d.ts

@@ -1,4 +1,4 @@
-import { FragmentNotFoundError, LayoutNotFoundError, PageNotFoundError } from '../content/provider.js';
+import { FragmentNotFoundError, LayoutNotFoundError, PageNotFoundError, type ContentProvider } from '../content/provider.js';
 import { type ReleaseObjectReader } from '../providers/object.js';
 export { FragmentNotFoundError, PageNotFoundError, LayoutNotFoundError };
 export interface ServerRenderInput<TPage, TSite extends SiteConfig = SiteConfig> {
@@ -8,6 +8,8 @@ export interface ServerRenderInput<TPage, TSite extends SiteConfig = SiteConfig>
     siteConfig: TSite;
     page: TPage;
     fragments?: Record<string, unknown>;
+    /** Internal request-local provider reused by createPage for chrome reads. */
+    contentProvider?: ContentProvider;
 }
 export interface SiteConfig {
     domain?: string;

package/dist/next/server.js

@@ -65,6 +65,7 @@ export async function getRenderInput(route = '/', context = {}) {
         locale: siteConfig.defaultLocale || 'en-us',
         siteConfig,
         page,
+        contentProvider: provider,
     };
 }
 // getCompilerRenderInput is the offline page-compiler seam used by the Next

package/dist/providers/object.d.ts

@@ -1,4 +1,4 @@
-import { type CompiledManifest, type ContentProvider, type RouteEntry } from '../content/provider.js';
+import { type ContentProvider, type RouteEntry } from '../content/provider.js';
 export interface ReleaseObjectReader {
     readReleaseObject(releaseId: string, path: string): Promise<Uint8Array>;
 }
@@ -7,7 +7,7 @@ export interface ObjectContentProviderOptions {
     pageRef: string;
     reader: ReleaseObjectReader;
 }
-/** Reads one immutable compiled release through a host-injected object reader. */
+/** Reads one exact immutable SSR page release through a host-injected reader. */
 export declare class ObjectContentProvider implements ContentProvider {
     #private;
     readonly releaseId: string;
@@ -19,6 +19,7 @@ export declare class ObjectContentProvider implements ContentProvider {
     getPage<T = unknown>(route: string): Promise<T>;
     getFragment<T = unknown>(id: string): Promise<T>;
     getLayout<T = unknown>(name: string): Promise<T>;
-    manifest(): Promise<CompiledManifest>;
+    private envelope;
+    private readSharedJSON;
     private readJSON;
 }

package/dist/providers/object.js

@@ -1,11 +1,58 @@
 import { FragmentNotFoundError, LayoutNotFoundError, PageNotFoundError, } from '../content/provider.js';
 import { normalizeRoute } from '../content/routes.js';
-/** Reads one immutable compiled release through a host-injected object reader. */
+const SSR_PAGE_ENVELOPE_SCHEMA = 'gradial.ssr-page.v1';
+const SHARED_CACHE_MAX_ENTRIES = 128;
+const SHARED_CACHE_MAX_BYTES = 16 * 1024 * 1024;
+// Release objects are immutable. This bounded process-local cache needs no
+// invalidation or TTL: an entry is either the exact verified bytes named by a
+// release envelope or it is evicted. Pages and manifests intentionally bypass
+// it so high-cardinality request objects cannot consume the cache.
+class ImmutableSharedObjectCache {
+    #entries = new Map();
+    #pending = new Map();
+    #bytes = 0;
+    async read(key, load) {
+        const cached = this.#entries.get(key);
+        if (cached) {
+            this.#entries.delete(key);
+            this.#entries.set(key, cached);
+            return cached.bytes;
+        }
+        let pending = this.#pending.get(key);
+        if (!pending) {
+            pending = load();
+            this.#pending.set(key, pending);
+            pending.then((bytes) => this.#store(key, bytes), () => undefined)
+                .finally(() => this.#pending.delete(key));
+        }
+        return await pending;
+    }
+    #store(key, bytes) {
+        if (bytes.byteLength > SHARED_CACHE_MAX_BYTES)
+            return;
+        const existing = this.#entries.get(key);
+        if (existing)
+            this.#bytes -= existing.size;
+        while (this.#entries.size >= SHARED_CACHE_MAX_ENTRIES || this.#bytes + bytes.byteLength > SHARED_CACHE_MAX_BYTES) {
+            const oldest = this.#entries.keys().next().value;
+            if (oldest === undefined)
+                break;
+            const evicted = this.#entries.get(oldest);
+            this.#entries.delete(oldest);
+            if (evicted)
+                this.#bytes -= evicted.size;
+        }
+        this.#entries.set(key, { bytes, size: bytes.byteLength });
+        this.#bytes += bytes.byteLength;
+    }
+}
+const sharedObjectCache = new ImmutableSharedObjectCache();
+/** Reads one exact immutable SSR page release through a host-injected reader. */
 export class ObjectContentProvider {
     releaseId;
     pageRef;
     reader;
-    #manifest;
+    #envelope;
     constructor(options) {
         if (!portableReleaseId(options.releaseId))
             throw new Error('ACI release ID is invalid');
@@ -15,73 +62,113 @@ export class ObjectContentProvider {
         this.pageRef = options.pageRef;
         this.reader = options.reader;
     }
+    // Hosted SSR receives an exact page ref from edge routing. Enumerating a
+    // whole release would require manifest.json and is intentionally unavailable
+    // on this provider; FileContentProvider remains the manifest consumer.
     async listRoutes() {
-        return Object.values((await this.manifest()).routes)
-            .sort((left, right) => left.path.localeCompare(right.path));
+        throw new Error('ACI hosted SSR does not support route enumeration');
     }
     async getSiteConfig() {
-        const manifest = await this.manifest();
-        return await this.readJSON(manifest.siteConfigRef);
+        const envelope = await this.envelope();
+        return await this.readSharedJSON(envelope.render.site);
     }
     async getPage(route) {
-        const normalized = normalizeRoute(route);
-        const entries = Object.values((await this.manifest()).routes)
-            .filter((entry) => normalizeRoute(entry.path) === normalized);
-        if (entries.length !== 1)
-            throw new PageNotFoundError(route);
-        const entry = entries[0];
-        const candidates = [
-            { ref: entry.payloadRef, digest: entry.digest },
-            ...Object.values(entry.variants ?? {}).map((variant) => ({
-                ref: variant.payloadRef,
-                digest: variant.digest,
-            })),
-        ];
-        const exact = candidates.find((candidate) => candidate.ref === this.pageRef);
-        if (!exact)
-            throw new PageNotFoundError(route, new Error(`selected page ref is not declared: ${this.pageRef}`));
-        try {
-            return await this.readJSON(exact.ref, exact.digest);
-        }
-        catch (error) {
-            throw new PageNotFoundError(route, error);
+        const envelope = await this.envelope();
+        if (normalizeRoute(route) !== normalizeRoute(envelope.route)) {
+            throw new PageNotFoundError(route, new Error(`selected page route is ${envelope.route}`));
         }
+        return envelope.page;
     }
     async getFragment(id) {
-        const entry = (await this.manifest()).fragments[id];
-        if (!entry)
-            throw new FragmentNotFoundError(id);
+        const envelope = await this.envelope();
+        const ref = envelope.render.fragments?.[id];
+        if (!ref)
+            throw new FragmentNotFoundError(id, new Error('fragment is not bound by the selected page'));
         try {
-            return await this.readJSON(entry.payloadRef, entry.digest);
+            return await this.readSharedJSON(ref);
         }
         catch (error) {
             throw new FragmentNotFoundError(id, error);
         }
     }
     async getLayout(name) {
-        const entry = (await this.manifest()).layouts?.[name];
-        if (!entry)
-            throw new LayoutNotFoundError(name);
+        const envelope = await this.envelope();
+        if (name !== envelope.render.layout.name) {
+            throw new LayoutNotFoundError(name, new Error(`selected page layout is ${envelope.render.layout.name}`));
+        }
         try {
-            return await this.readJSON(`layouts/${name}/index.json`);
+            return await this.readSharedJSON(envelope.render.layout);
         }
         catch (error) {
             throw new LayoutNotFoundError(name, error);
         }
     }
-    async manifest() {
-        this.#manifest ??= this.readJSON('manifest.json');
-        return await this.#manifest;
+    async envelope() {
+        this.#envelope ??= this.readJSON(this.pageRef).then((value) => validateEnvelope(value, this.pageRef));
+        return await this.#envelope;
+    }
+    async readSharedJSON(ref) {
+        const path = cleanObjectPath(ref.payloadRef);
+        if (!path || path !== ref.payloadRef)
+            throw new Error(`ACI shared object path is invalid: ${ref.payloadRef}`);
+        const key = JSON.stringify([this.releaseId, path, ref.digest]);
+        const bytes = await sharedObjectCache.read(key, async () => {
+            const value = await this.reader.readReleaseObject(this.releaseId, path);
+            await verifyDigest(value, ref.digest, path);
+            return value;
+        });
+        return parseJSON(bytes, path);
     }
-    async readJSON(path, digest) {
+    async readJSON(path) {
         const clean = cleanObjectPath(path);
         if (!clean || clean !== path)
             throw new Error(`ACI release object path is invalid: ${path}`);
-        const bytes = await this.reader.readReleaseObject(this.releaseId, clean);
-        if (digest)
-            await verifyDigest(bytes, digest, clean);
+        return parseJSON(await this.reader.readReleaseObject(this.releaseId, clean), clean);
+    }
+}
+function validateEnvelope(value, pageRef) {
+    if (!isObject(value) || value.schemaVersion !== SSR_PAGE_ENVELOPE_SCHEMA || typeof value.route !== 'string' || !isObject(value.render)) {
+        throw new Error(`ACI SSR page envelope is invalid: ${pageRef}`);
+    }
+    const render = value.render;
+    if (!validRef(render.site) || !isObject(render.layout) || typeof render.layout.name !== 'string' || !validRef(render.layout)) {
+        throw new Error(`ACI SSR page envelope bindings are invalid: ${pageRef}`);
+    }
+    const fragments = {};
+    if (render.fragments !== undefined) {
+        if (!isObject(render.fragments))
+            throw new Error(`ACI SSR page fragments are invalid: ${pageRef}`);
+        for (const [id, ref] of Object.entries(render.fragments)) {
+            if (!id || !validRef(ref))
+                throw new Error(`ACI SSR page fragment binding is invalid: ${pageRef}`);
+            fragments[id] = ref;
+        }
+    }
+    return {
+        schemaVersion: SSR_PAGE_ENVELOPE_SCHEMA,
+        route: value.route,
+        variantKey: typeof value.variantKey === 'string' ? value.variantKey : '',
+        page: value.page,
+        render: {
+            site: render.site,
+            layout: { name: render.layout.name, payloadRef: render.layout.payloadRef, digest: render.layout.digest },
+            fragments,
+        },
+    };
+}
+function validRef(value) {
+    return isObject(value) && typeof value.payloadRef === 'string' && cleanObjectPath(value.payloadRef) === value.payloadRef && /^sha256:[0-9a-f]{64}$/.test(String(value.digest));
+}
+function isObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function parseJSON(bytes, path) {
+    try {
         return JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(bytes));
     }
+    catch (error) {
+        throw new Error(`ACI release object is not valid JSON: ${path}`, { cause: error });
+    }
 }
 async function verifyDigest(bytes, expected, path) {
     const match = /^sha256:([0-9a-f]{64})$/.exec(expected);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gradial/aci",
-  "version": "0.1.51-ssr.3",
+  "version": "0.1.51-ssr.5",
   "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.51-ssr.3",
-    "@gradial/aci-cli-darwin-x64": "0.1.51-ssr.3",
-    "@gradial/aci-cli-linux-arm64": "0.1.51-ssr.3",
-    "@gradial/aci-cli-linux-x64": "0.1.51-ssr.3",
-    "@gradial/aci-cli-win32-arm64": "0.1.51-ssr.3",
-    "@gradial/aci-cli-win32-x64": "0.1.51-ssr.3"
+    "@gradial/aci-cli-darwin-arm64": "0.1.51-ssr.5",
+    "@gradial/aci-cli-darwin-x64": "0.1.51-ssr.5",
+    "@gradial/aci-cli-linux-arm64": "0.1.51-ssr.5",
+    "@gradial/aci-cli-linux-x64": "0.1.51-ssr.5",
+    "@gradial/aci-cli-win32-arm64": "0.1.51-ssr.5",
+    "@gradial/aci-cli-win32-x64": "0.1.51-ssr.5"
   }
 }