@gradial/aci 0.1.52-rc.8 → 0.1.52

package/dist/collect/declarative.js

@@ -1,6 +1,7 @@
 // Declarative events (design/04): elements opt in via data-aci-event, with
 // data-aci-on=click|visible (visible = first intersection >= 50%, once per
-// element per page view) and data-aci-prop-* string properties. One
+// element per page view) and data-aci-prop-* string properties. Every event
+// carries the current page url so ingest can derive path and UTM. One
 // delegated click listener + one IntersectionObserver regardless of element
 // count. Malformed declarations are ignored silently.
 const EVENT_ATTR = "data-aci-event";
@@ -35,13 +36,13 @@ function extractProps(el) {
     }
     return props;
 }
-function declaredEvent(el, debug) {
+function declaredEvent(el, url, debug) {
     const eventName = toCustomEventName(el.getAttribute(EVENT_ATTR));
     if (eventName === undefined) {
         debug?.("capture", { reason: "malformed_declaration", attr: EVENT_ATTR });
         return undefined;
     }
-    return { eventName, properties: extractProps(el) };
+    return { eventName, url, properties: extractProps(el) };
 }
 function trigger(el) {
     return el.getAttribute(ON_ATTR)?.trim().toLowerCase() ?? "click";
@@ -53,6 +54,7 @@ function trigger(el) {
  */
 export function startDeclarative(emit, env, refresh) {
     const { document: doc, debug } = env;
+    const loc = doc.defaultView?.location;
     doc.addEventListener("click", (e) => {
         try {
             const target = e.target;
@@ -66,7 +68,7 @@ export function startDeclarative(emit, env, refresh) {
                 return;
             if (trigger(el) !== "click")
                 return; // visible or malformed trigger
-            const event = declaredEvent(el, debug);
+            const event = declaredEvent(el, loc?.href, debug);
             if (event)
                 emit(event);
         }
@@ -92,7 +94,7 @@ export function startDeclarative(emit, env, refresh) {
                     continue;
                 fired.add(entry.target);
                 obs.unobserve(entry.target); // once per element per page view
-                const event = declaredEvent(entry.target, debug);
+                const event = declaredEvent(entry.target, loc?.href, debug);
                 if (event)
                     emit(event);
             }

package/dist/collect/gapbuffer.d.ts

@@ -39,12 +39,21 @@ export interface RouteDeps {
     marker: () => boolean;
     gapBuffer: GapBuffer;
     batcher: EventSink;
+    /**
+     * Whether a CMP-preset site's consent decision is still pending and no
+     * identity exists (consenthold.ts). Absent means never pending.
+     */
+    consentPending?: () => boolean;
+    /** In-memory hold for consent-pending events (consenthold.ts). */
+    consentHold?: EventSink;
 }
 /**
- * routeEvent implements the emit routing (design/05): events captured in
- * the consent gap — envelope grants personalization AND the marker is
- * absent — are buffered; everything else goes straight to the batcher (the
- * collector enforces consent server-side).
+ * routeEvent implements the emit routing (design/05): events captured while
+ * a CMP's consent decision is pending (and no identity exists) are held in
+ * page memory until the decision; events captured in the consent gap —
+ * envelope grants personalization AND the marker is absent — are buffered;
+ * everything else goes straight to the batcher (the collector enforces
+ * consent server-side).
  */
 export declare function routeEvent(event: CollectEvent, deps: RouteDeps): void;
 /**

package/dist/collect/gapbuffer.js

@@ -4,20 +4,23 @@
 // response. Bounded at 50 (drop-oldest), persisted per-tab in
 // sessionStorage["aci:buf"], purged on withdrawal, flushed through the
 // normal batcher when the marker appears (checked at init and on every
-// flush tick). Flushed events keep their eventIds.
+// flush tick). Flushed events keep their eventIds. Storage is authoritative:
+// a BFCache-retained document must observe another document's drain/purge.
 export const GAP_BUFFER_KEY = "aci:buf";
 export const GAP_BUFFER_CAP = 50;
 const MINT_MARKER_COOKIE = "aci_m";
 export class GapBuffer {
-    events;
+    // Only retain events in memory when storage is unavailable. A successful
+    // storage operation must never leave a second, stale owner of that queue.
+    events = [];
     storage;
     debug;
     constructor(env) {
         this.debug = env?.debug;
         this.storage = env?.storage;
-        this.events = this.restore();
     }
     push(event) {
+        this.events = this.restore();
         this.events.push(event);
         if (this.events.length > GAP_BUFFER_CAP) {
             this.events.splice(0, this.events.length - GAP_BUFFER_CAP);
@@ -27,13 +30,14 @@ export class GapBuffer {
     }
     /** drain returns and clears all buffered events, preserving order and ids. */
     drain() {
-        const drained = this.events;
+        const drained = this.restore();
         this.events = [];
         this.persist();
         return drained;
     }
     /** purge empties the buffer (consent withdrawal). */
     purge() {
+        this.events = this.restore();
         if (this.events.length > 0) {
             this.debug?.("buffer", { reason: "purged", count: this.events.length });
         }
@@ -41,12 +45,12 @@ export class GapBuffer {
         this.persist();
     }
     size() {
-        return this.events.length;
+        return this.restore().length;
     }
     restore() {
         const storage = this.storage;
         if (!storage)
-            return [];
+            return this.events;
         let raw;
         try {
             raw = storage.getItem(GAP_BUFFER_KEY);
@@ -86,6 +90,7 @@ export class GapBuffer {
             else {
                 storage.setItem(GAP_BUFFER_KEY, JSON.stringify(this.events));
             }
+            this.events = [];
         }
         catch (err) {
             this.storage = undefined;
@@ -104,12 +109,18 @@ export function hasMintMarker(doc) {
     return false;
 }
 /**
- * routeEvent implements the emit routing (design/05): events captured in
- * the consent gap — envelope grants personalization AND the marker is
- * absent — are buffered; everything else goes straight to the batcher (the
- * collector enforces consent server-side).
+ * routeEvent implements the emit routing (design/05): events captured while
+ * a CMP's consent decision is pending (and no identity exists) are held in
+ * page memory until the decision; events captured in the consent gap —
+ * envelope grants personalization AND the marker is absent — are buffered;
+ * everything else goes straight to the batcher (the collector enforces
+ * consent server-side).
  */
 export function routeEvent(event, deps) {
+    if (deps.consentHold && deps.consentPending?.()) {
+        deps.consentHold.push(event);
+        return;
+    }
     if (deps.grants() && !deps.marker()) {
         deps.gapBuffer.push(event);
         return;

package/dist/collect/index.js

@@ -3,9 +3,11 @@
 // init(); every failure is swallowed after a debug record so the page is
 // never affected (QR-2/3).
 import { installCommandQueue } from "./api.js";
-import { createAssignments, withAssignmentContext } from "./assignments.js";
+import { createAssignments, readAssignments, withAssignmentContext } from "./assignments.js";
 import { Batcher } from "./batcher.js";
+import { CONSENT_BANNER_DECIDED_EVENT, consentBannerPending, } from "../consent-banner/index.js";
 import { createDebug, readTagConfig } from "./config.js";
+import { ConsentHold, resolveConsentHold } from "./consenthold.js";
 import { start as startC15t } from "./consent/adapters/c15t.js";
 import { start as startCookiebot } from "./consent/adapters/cookiebot.js";
 import { start as startOneTrust } from "./consent/adapters/onetrust.js";
@@ -53,6 +55,9 @@ export function init(win) {
     w.__aci_loaded = true;
     if (!hasBaseline(w))
         return;
+    // Snapshot before exposures or queued commands. Cookie expiry, hydration
+    // and BFCache never turn this synthetic document into a genuine visit.
+    const measurementDisabled = w.__aci_measurement_disabled === true;
     const cfg = readTagConfig(w.document.currentScript);
     const debug = createDebug(cfg.debug);
     try {
@@ -74,6 +79,33 @@ export function init(win) {
                 return false;
             }
         };
+        const decided = () => {
+            try {
+                return readConsentCookie(doc) !== undefined;
+            }
+            catch {
+                return false;
+            }
+        };
+        // Consent-pending hold (personalization-onboarding REQ-15): a decision
+        // is pending when a consent integration has declared it will write the
+        // envelope and has not yet. A CMP preset is that declaration; under the
+        // manual preset it is ACI's own consent banner, through its state API.
+        // Until the decision, and while no identity exists, the collector could
+        // only drop what we send, so events wait in page memory instead. A
+        // manual site with no banner keeps immediate sending.
+        const integrationPending = cfg.preset === "manual"
+            ? () => {
+                try {
+                    return consentBannerPending(doc);
+                }
+                catch {
+                    return false;
+                }
+            }
+            : () => true;
+        const consentHold = new ConsentHold({ debug });
+        const consentPending = () => !decided() && !marker() && integrationPending();
         const transportEnv = {
             navigator: w.navigator,
             fetch: typeof w.fetch === "function"
@@ -85,9 +117,16 @@ export function init(win) {
         batcher = new Batcher({
             send: (body) => send(body, transportEnv),
             debug,
-            // The marker is re-checked on every flush tick, so a mint by another
-            // tab or navigation is noticed.
-            onTick: () => maybeFlushGapBuffer(gapBuffer, batcher, marker, debug),
+            // Every flush tick re-checks the consent decision (so a decision
+            // written by another tab or site code releases or discards the hold)
+            // and then the marker (so a mint by another tab or navigation is
+            // noticed). Held events are older than gap-buffered ones: release first.
+            onTick: () => {
+                if (measurementDisabled)
+                    return;
+                resolveConsentHold(consentHold, { decided, grants, batcher, debug });
+                maybeFlushGapBuffer(gapBuffer, batcher, marker, debug);
+            },
             timers: {
                 setInterval: (fn, ms) => w.setInterval(fn, ms),
                 clearInterval: (id) => w.clearInterval(id),
@@ -95,26 +134,44 @@ export function init(win) {
             documentTarget: doc,
             windowTarget: w,
         });
-        // While an assignment is active, every emitted event carries the first
-        // active assignment's experiment context (REQ-3) unless it already has
-        // one — exposures and explicit conversions carry their own. The handle
+        // Every emitted event carries all active assignments (REQ-3) unless it
+        // already supplies its explicit context — exposures and explicit conversions carry their own. The handle
         // is created (without emitting) BEFORE emit so every dependency of emit
         // exists before emit can run; exposures flow at start() below.
         const assignments = createAssignments({ document: doc, window: w, debug });
         const emit = (event) => {
+            if (measurementDisabled)
+                return;
             routeEvent({
                 ...withAssignmentContext(event, assignments),
                 eventId: ulid(undefined, (bytes) => w.crypto.getRandomValues(bytes)),
-            }, { grants, marker, gapBuffer, batcher });
+            }, { grants, marker, gapBuffer, batcher, consentHold, consentPending });
         };
+        // A decision written through the SDK (or announced by the ACI banner)
+        // flushes at once: the tick releases (grant) or discards (anything else)
+        // the hold, and a released first view leaves before the visitor can
+        // navigate away.
+        const onDecision = () => batcher.flush();
+        doc.addEventListener(CONSENT_BANNER_DECIDED_EVENT, onDecision);
         // Started BEFORE the command-queue drain and page views: pre-load
         // aci('track', ...) calls and the initial rum.page_view must be stamped
         // with the active assignment context, or queued conversions can never
         // match a goal (review-quorum finding). Consent commands drained after
         // this stay safe — events wait in the gap buffer until grants resolve.
         assignments.start(emit);
-        installCommandQueue(w, cfg, {
-            track: (name, properties) => emit({ eventName: name, properties }),
+        let emitPageView = () => { };
+        const navigation = installNavigationHook(w, [
+            contexts => assignments.rearm(contexts),
+            () => emitPageView(),
+        ], () => assignments.clear());
+        // Astro dispatches this nonbubbling event on document after the router commits.
+        doc.addEventListener("astro:page-load", () => navigation.complete({
+            url: w.location.href,
+            assignments: readAssignments(doc, debug),
+        }));
+        installCommandQueue(w, {
+            navigationComplete: completion => navigation.complete(completion),
+            track: (name, properties) => emit({ eventName: name, properties, url: w.location.href }),
             consent: ({ p, src }) => {
                 const purposes = sanitizePurposes(p);
                 if (purposes === undefined) {
@@ -126,25 +183,19 @@ export function init(win) {
                     debug("consent", { reason: "malformed_source" });
                     return;
                 }
-                if (!applyConsent(purposes, source, { document: doc, gapBuffer })) {
+                if (!applyConsent(purposes, source, { document: doc, gapBuffer, onDecision })) {
                     debug("consent", { reason: "oversized_envelope" });
                 }
             },
         }, debug);
-        const emitPageView = startPageViews(emit, w);
-        // The single history patch (one pushState/replaceState wrap, one dedupe
-        // state, one popstate listener). Order is load-bearing: the assignments
-        // re-arm runs BEFORE the SPA page view so rum.page_view is stamped with
-        // the new page's experiment context.
-        installNavigationHook(w, [
-            () => assignments.rearm(),
-            emitPageView,
-        ]);
+        emitPageView = startPageViews(emit, w);
         startDeclarative(emit, {
             document: doc,
             intersectionObserver: w.IntersectionObserver,
             debug,
         }, () => {
+            if (measurementDisabled)
+                return;
             void refreshClaims(transportEnv).then((refreshed) => {
                 if (refreshed)
                     w.location.reload();
@@ -169,6 +220,7 @@ export function init(win) {
                 document: doc,
                 categories: cfg.categories,
                 gapBuffer,
+                onDecision,
                 debug,
                 scheduler: {
                     setTimeout: (fn, ms) => w.setTimeout(fn, ms),
@@ -177,7 +229,12 @@ export function init(win) {
             });
         }
         batcher.start();
-        maybeFlushGapBuffer(gapBuffer, batcher, marker, debug);
+        // Registered after batcher.start(), so the batcher's own pagehide flush
+        // has already released a hold whose decision exists; whatever remains is
+        // undecided and never leaves the page.
+        w.addEventListener("pagehide", () => consentHold.discard("unload"));
+        if (!measurementDisabled)
+            maybeFlushGapBuffer(gapBuffer, batcher, marker, debug);
         debug("init", { config: cfg });
     }
     catch (err) {

package/dist/collect/pageviews.d.ts

@@ -1,3 +1,4 @@
+import type { ExperimentAssignment } from "./assignments.js";
 import type { PendingEvent } from "./batcher.js";
 export declare const PAGE_VIEW_EVENT = "rum.page_view";
 interface HistoryLike {
@@ -14,17 +15,16 @@ export interface PageViewWindow {
     history: HistoryLike;
     addEventListener(type: string, fn: () => void): void;
 }
-/**
- * installNavigationHook wires pushState/replaceState/popstate and invokes
- * the subscribers, in order, once per SPA route change; hash-only changes
- * and same-URL repeats never fire. Installed exactly ONCE by init — one
- * history patch, one dedupe state — and shared by the assignments collector
- * and page views so "page view" means exactly the same thing to both
- * (REQ-2). Subscriber order is the contract: init lists the assignments
- * re-arm BEFORE the page-view emitter so rum.page_view is stamped with the
- * new page's experiment context.
- */
-export declare function installNavigationHook(win: PageViewWindow, subscribers: ReadonlyArray<() => void>): void;
+export interface NavigationCompletion {
+    /** Absolute URL of the page the framework just committed. */
+    url: string;
+    /** Complete committed assignment set, including [] for a base page. */
+    assignments: ExperimentAssignment[];
+}
+/** History signals invalidate context; only framework completion arms a view. */
+export declare function installNavigationHook(win: PageViewWindow, subscribers: ReadonlyArray<(assignments: ExperimentAssignment[]) => void>, onStart?: () => void): {
+    complete(completion: NavigationCompletion): void;
+};
 /**
  * startPageViews emits the initial page view and returns the emitter for
  * SPA route-change views — init subscribes it to the single navigation hook

package/dist/collect/pageviews.js

@@ -1,45 +1,50 @@
 // Page views (design/04): eventName "rum.page_view" with url (the full href
 // including query) and referrer — the SDK never populates utm, ingest
 // derives it from the URL. One event per document load plus one per
-// history-API route change; hash-only changes and same-URL repeats never
+// completed framework route change; hash-only changes and same-URL repeats never
 // double count.
 export const PAGE_VIEW_EVENT = "rum.page_view";
 function stripHash(href) {
     const i = href.indexOf("#");
     return i === -1 ? href : href.slice(0, i);
 }
-/**
- * installNavigationHook wires pushState/replaceState/popstate and invokes
- * the subscribers, in order, once per SPA route change; hash-only changes
- * and same-URL repeats never fire. Installed exactly ONCE by init — one
- * history patch, one dedupe state — and shared by the assignments collector
- * and page views so "page view" means exactly the same thing to both
- * (REQ-2). Subscriber order is the contract: init lists the assignments
- * re-arm BEFORE the page-view emitter so rum.page_view is stamped with the
- * new page's experiment context.
- */
-export function installNavigationHook(win, subscribers) {
-    let last = stripHash(win.location.href);
+/** History signals invalidate context; only framework completion arms a view. */
+export function installNavigationHook(win, subscribers, onStart = () => { }) {
+    let observed = stripHash(win.location.href);
+    let completed = observed;
+    let pending = false;
     const handler = () => {
         const current = stripHash(win.location.href);
-        if (current === last)
-            return; // hash-only change or same-URL repeat
-        last = current;
-        for (const onNavigate of subscribers)
-            onNavigate();
+        if (current === observed)
+            return;
+        observed = current;
+        pending = true;
+        onStart();
     };
     const history = win.history;
-    const wrap = (method) => {
+    for (const method of ["pushState", "replaceState"]) {
         const original = history[method].bind(history);
         history[method] = (...args) => {
             const result = original(...args);
             handler();
             return result;
         };
-    };
-    wrap("pushState");
-    wrap("replaceState");
+    }
     win.addEventListener("popstate", handler);
+    return {
+        complete({ url, assignments }) {
+            const current = stripHash(win.location.href);
+            if (stripHash(url) !== current)
+                return; // late commit for another route
+            handler();
+            if (!pending && completed === current)
+                return;
+            pending = false;
+            completed = current;
+            for (const onNavigate of subscribers)
+                onNavigate(assignments);
+        },
+    };
 }
 /**
  * startPageViews emits the initial page view and returns the emitter for

package/dist/consent-banner/index.d.ts

@@ -16,6 +16,10 @@ export interface ConsentBannerOptions {
     /** Callback fired after a consent decision is written. */
     onDecision?: (granted: boolean) => void;
 }
+/** Rendered with the page by ConsentBanner.astro, before any script runs. */
+export declare const CONSENT_BANNER_MOUNT_ATTR = "data-aci-consent-banner-mount";
+/** Dispatched on the document right after the banner writes a decision. */
+export declare const CONSENT_BANNER_DECIDED_EVENT = "aci:consent-banner-decided";
 /**
  * hasConsentCookie returns true when the aci_consent cookie exists (the user
  * has already made a decision, regardless of whether they granted or denied).
@@ -23,6 +27,19 @@ export interface ConsentBannerOptions {
 export declare function hasConsentCookie(doc: {
     cookie: string;
 }): boolean;
+/**
+ * consentBannerPending is the banner's state API for the collect SDK
+ * (personalization-onboarding REQ-15): true while this page's ACI consent
+ * banner awaits the visitor's decision, meaning the banner is declared (its
+ * mount point, which ConsentBanner.astro renders with the HTML) or mounted,
+ * and no aci_consent decision exists. Because the mount point ships in the
+ * HTML, the answer is already right for the first deferred script to run,
+ * whether the collect SDK or the banner's own script loads first.
+ */
+export declare function consentBannerPending(doc: {
+    cookie: string;
+    querySelector(selectors: string): unknown;
+}): boolean;
 /**
  * mountConsentBanner checks for an existing consent cookie. If none exists,
  * it injects a banner into the document body and wires up accept/reject

package/dist/consent-banner/index.js

@@ -18,6 +18,10 @@ const DEFAULTS = {
 const BANNER_ID = "aci-consent-banner";
 const BANNER_ATTR = "data-aci-consent-banner";
 const BANNER_HIDDEN = "aci-consent-banner--hidden";
+/** Rendered with the page by ConsentBanner.astro, before any script runs. */
+export const CONSENT_BANNER_MOUNT_ATTR = "data-aci-consent-banner-mount";
+/** Dispatched on the document right after the banner writes a decision. */
+export const CONSENT_BANNER_DECIDED_EVENT = "aci:consent-banner-decided";
 /**
  * hasConsentCookie returns true when the aci_consent cookie exists (the user
  * has already made a decision, regardless of whether they granted or denied).
@@ -25,6 +29,20 @@ const BANNER_HIDDEN = "aci-consent-banner--hidden";
 export function hasConsentCookie(doc) {
     return readConsentCookie(doc) !== undefined;
 }
+/**
+ * consentBannerPending is the banner's state API for the collect SDK
+ * (personalization-onboarding REQ-15): true while this page's ACI consent
+ * banner awaits the visitor's decision, meaning the banner is declared (its
+ * mount point, which ConsentBanner.astro renders with the HTML) or mounted,
+ * and no aci_consent decision exists. Because the mount point ships in the
+ * HTML, the answer is already right for the first deferred script to run,
+ * whether the collect SDK or the banner's own script loads first.
+ */
+export function consentBannerPending(doc) {
+    if (hasConsentCookie(doc))
+        return false;
+    return doc.querySelector(`[${CONSENT_BANNER_MOUNT_ATTR}], [${BANNER_ATTR}]`) !== null;
+}
 /**
  * mountConsentBanner checks for an existing consent cookie. If none exists,
  * it injects a banner into the document body and wires up accept/reject
@@ -47,6 +65,11 @@ export function mountConsentBanner(doc, opts = {}) {
         const purposes = granted ? [PERSONALIZATION_PURPOSE] : [];
         if (!applyConsent(purposes, config.source, { document: doc }))
             return;
+        // Tell a collect SDK on this page to act on the decision now rather than
+        // at its next flush tick (it releases or discards what it held).
+        const EventCtor = doc.defaultView?.Event;
+        if (EventCtor)
+            doc.dispatchEvent(new EventCtor(CONSENT_BANNER_DECIDED_EVENT));
         banner.classList.add(BANNER_HIDDEN);
         setTimeout(cleanup, 300);
         opts.onDecision?.(granted);

package/dist/content/index.d.ts

@@ -3,6 +3,7 @@ export * from './routes.js';
 export * from './types.js';
 export * from './personalization.js';
 export * from './cache.js';
-export * from './resolve-slots.js';
+export { FragmentResolutionError, MAX_EXPANDED_BLOCKS, MAX_FRAGMENT_DEPTH, fragmentToBlock, preserveFragmentScope, resolveFragmentNodes, resolveSlots, resolveSlotsSync, } from './resolve-slots.js';
+export type { FragmentBlock, FragmentData, FragmentLoader } from './resolve-slots.js';
 export * from './default-error-page.js';
 export * from './error-pages.js';

package/dist/content/index.js

@@ -3,6 +3,9 @@ export * from './routes.js';
 export * from './types.js';
 export * from './personalization.js';
 export * from './cache.js';
-export * from './resolve-slots.js';
+// Explicit list, not `export *`: fragmentRootScope is runtime-only provenance
+// shared with mintlify/blocks.ts via a direct resolve-slots import and must
+// never leak into the public '@gradial/aci/content' surface.
+export { FragmentResolutionError, MAX_EXPANDED_BLOCKS, MAX_FRAGMENT_DEPTH, fragmentToBlock, preserveFragmentScope, resolveFragmentNodes, resolveSlots, resolveSlotsSync, } from './resolve-slots.js';
 export * from './default-error-page.js';
 export * from './error-pages.js';

package/dist/content/provider.d.ts

@@ -2,6 +2,7 @@ import type { KernelPage, KernelRouteMetadata, KernelSiteConfig, RenderInput } f
 export interface RouteEntry {
     slug: string;
     path: string;
+    variantKey: string;
     payloadRef: string;
     digest: string;
     fragmentRefs?: string[];
@@ -19,8 +20,21 @@ export interface FragmentEntry {
     digest: string;
     fragmentRefs?: string[];
 }
+export interface LayoutVariantEntry {
+    payloadRef: string;
+    digest: string;
+    slots: LayoutSlot[];
+    defaults?: Record<string, FragmentRef[]>;
+}
+/**
+ * Derived template render plan in the compiled release wire format.
+ * This is never an authorable layout: page templates own regions and defaults.
+ * The LayoutEntry name and layouts wire key remain for retained release readers.
+ */
 export interface LayoutEntry {
     name: string;
+    digest?: string;
+    variants?: Record<string, LayoutVariantEntry>;
     payloadRef: string;
     slots: LayoutSlot[];
     defaults?: Record<string, FragmentRef[]>;
@@ -32,7 +46,6 @@ export interface LayoutSlot {
 export interface FragmentRef {
     kind: string;
     fragmentId: string;
-    inline: boolean;
 }
 export interface CompiledManifest {
     manifestVersion: string;
@@ -59,8 +72,9 @@ export declare class LayoutNotFoundError extends Error {
     constructor(name: string, cause?: unknown);
 }
 export interface RenderInputOptions {
+    variantKey: string;
     domain?: string;
     locale?: string;
 }
-export declare function loadRenderInput(provider: ContentProvider, route?: string, options?: RenderInputOptions): Promise<RenderInput>;
+export declare function loadRenderInput(provider: ContentProvider, route: string | undefined, options: RenderInputOptions): Promise<RenderInput>;
 export declare function routeMetadataForContent(siteConfig: KernelSiteConfig, page: KernelPage | null): KernelRouteMetadata;

package/dist/content/provider.js

@@ -24,8 +24,11 @@ export class LayoutNotFoundError extends Error {
     }
 }
 import { getCachedSiteConfig } from './cache.js';
-export async function loadRenderInput(provider, route = '/', options = {}) {
+export async function loadRenderInput(provider, route = '/', options) {
     const normalized = normalizeRoute(route);
+    if (typeof options?.variantKey !== 'string' || !options.variantKey.trim() || options.variantKey !== options.variantKey.trim()) {
+        throw new Error(`ACI render variant identity is missing or invalid for route ${normalized}; supply an explicit variantKey`);
+    }
     const [siteConfig, page] = await Promise.all([
         getCachedSiteConfig(provider),
         provider.getPage(normalized).catch((error) => {
@@ -36,6 +39,7 @@ export async function loadRenderInput(provider, route = '/', options = {}) {
     ]);
     return {
         route: normalized,
+        variantKey: options.variantKey,
         domain: options.domain || siteConfig.domain,
         locale: (options.locale || siteConfig.defaultLocale || 'en-us').toLowerCase(),
         siteConfig,

package/dist/content/resolve-slots.d.ts

@@ -1,5 +1,5 @@
 import type { LayoutEntry } from './provider.js';
-import type { KernelPageBlock } from './types.js';
+import type { KernelPageBlock, KernelPageNode } from './types.js';
 export interface FragmentBlock {
     $type: 'component';
     component: string;
@@ -13,4 +13,26 @@ export interface FragmentData {
     props?: Record<string, unknown>;
 }
 export type FragmentLoader = (id: string) => Promise<FragmentData>;
-export declare function resolveSlots(layout: LayoutEntry, pageRegions: Record<string, KernelPageBlock[]>, getFragment: FragmentLoader): Promise<Record<string, KernelPageBlock[]>>;
+/**
+ * Shared Go/TS limit contract (sdk I-21). These values are pinned against
+ * internal/domain/content/compiler/testdata/limit-conformance.v1.json by
+ * limit-conformance.test.ts (TS) and limit_conformance_test.go (Go); the
+ * compiler's MaxFragmentDepth/MaxExpandedBlocks must match.
+ */
+/** Bounds a selected fragment reference chain, counting its root fragment. */
+export declare const MAX_FRAGMENT_DEPTH = 10;
+/** Bounds rendered component occurrences per page, including repeated placements. */
+export declare const MAX_EXPANDED_BLOCKS = 4096;
+/** Failures in a selected fragment are never eligible for local-content fallback. */
+export declare class FragmentResolutionError extends Error {
+    constructor(message: string, options?: ErrorOptions);
+}
+export declare const fragmentRootScope: unique symbol;
+export declare function preserveFragmentScope<T extends object>(source: object, target: T): T;
+export declare function resolveSlots(plan: LayoutEntry, pageRegions: Record<string, KernelPageNode[]>, getFragment: FragmentLoader): Promise<Record<string, KernelPageBlock[]>>;
+/** The config-time error seat uses the identical traversal with synchronous file reads. */
+export declare function resolveSlotsSync(plan: LayoutEntry, pageRegions: Record<string, KernelPageNode[]>, getFragment: (id: string) => FragmentData): Record<string, KernelPageBlock[]>;
+/** Resolve compiled references through the exact fragment bindings selected for this page. */
+export declare function resolveFragmentNodes(nodes: readonly KernelPageNode[], getFragment: FragmentLoader): Promise<KernelPageBlock[]>;
+/** Use the same fragment root identity for layout defaults and region placements. */
+export declare function fragmentToBlock(fragment: FragmentData, id: string): KernelPageBlock;