@gradial/aci 0.1.40 → 0.1.42

package/dist/collect/assignments.d.ts

@@ -0,0 +1,65 @@
+import type { PendingEvent } from "./batcher.js";
+import type { DebugFn } from "./config.js";
+export declare const EXPERIMENT_EXPOSURE_EVENT = "experiment.exposure";
+/** One active assignment read from the page's data-aci-assignments tag. */
+export interface ExperimentAssignment {
+    experimentId: string;
+    armId: string;
+    allocationVersion: string;
+}
+interface DocumentLike {
+    querySelector(selectors: string): {
+        textContent: string | null;
+    } | null;
+}
+/**
+ * readAssignments parses the page's data-aci-assignments tag. Absence, a
+ * malformed body, or an unknown version are tolerated as "no assignments"
+ * (debug record, no throw).
+ */
+export declare function readAssignments(doc: DocumentLike, debug?: DebugFn): ExperimentAssignment[];
+export interface AssignmentsEnv {
+    document: DocumentLike;
+    /** Only location.href is read (the exposure event's url). */
+    window: {
+        location: {
+            href: string;
+        };
+    };
+    debug?: DebugFn;
+}
+export interface AssignmentsHandle {
+    /** The assignments active for the current page view (copies). */
+    getActiveAssignments(): ExperimentAssignment[];
+    /**
+     * start reads the assignments tag and emits `experiment.exposure` once per
+     * (experiment, page view) through `emit`. Called once by init AFTER the
+     * emit pipeline is fully constructed — the handle is created first so
+     * emit's withAssignmentContext dependency exists before emit can run.
+     */
+    start(emit: (event: PendingEvent) => void): void;
+    /**
+     * rearm resets the per-page-view exposure dedupe and re-reads the tag.
+     * Wired by init into the shared navigation hook, ORDERED BEFORE the SPA
+     * page-view emitter so rum.page_view is stamped with the new page's
+     * context (REQ-2/3; see the module-header stale-tag limitation).
+     */
+    rearm(): void;
+}
+/**
+ * withAssignmentContext stamps the first active assignment's experiment
+ * context onto an event that does not already carry one (REQ-3). Events with
+ * explicit context (exposures, explicit conversions) are never overwritten.
+ */
+export declare function withAssignmentContext(event: PendingEvent, handle: AssignmentsHandle | undefined): PendingEvent;
+/**
+ * createAssignments builds the assignments collector without emitting
+ * anything: creation and exposure emission are split so init can construct
+ * the emit pipeline against the handle before any event flows (no circular
+ * "emit captures a not-yet-assigned handle" wiring). start() reads the tag
+ * and emits exposures; rearm() is the SPA-navigation reset, fanned out from
+ * the single navigation hook installed by init — so an "exposure per page
+ * view" matches a "page view" exactly.
+ */
+export declare function createAssignments(env: AssignmentsEnv): AssignmentsHandle;
+export {};

package/dist/collect/assignments.js

@@ -0,0 +1,138 @@
+// Experiment assignments (personalization-reporting design/04/05): the
+// starters render the page's build-time assignment context as a
+// `<script type="application/json" data-aci-assignments>` JSON tag
+// ({"v":1,"experiments":[{experimentId,armId,allocationVersion}]}). This
+// collector parses it, emits `experiment.exposure` at most once per
+// (experiment, page view) (REQ-2), and exposes the active assignments so the
+// emit path can stamp experiment context on every event while an assignment
+// is active (REQ-3). Absent or malformed tags are a silent no-op with a
+// debug record; the page is never affected.
+//
+// KNOWN LIMITATION — SPA client-side routing reads a stale tag. The re-arm
+// (AssignmentsHandle.rearm, wired to the shared navigation hook in init)
+// runs synchronously when pushState/replaceState returns, but client
+// routers (e.g. the Next app router) swap the page's DOM — including the
+// assignments tag — AFTER pushState returns. The re-arm therefore reads the
+// PREVIOUS page's tag. The design assumption is MPA / full-SSR-first
+// navigation, where every page view is a fresh document load and the tag is
+// always current; under pure client-side transitions, exposures and context
+// stamping for the newly routed page lag one navigation behind. Accepted
+// for now — do not "fix" with a MutationObserver.
+export const EXPERIMENT_EXPOSURE_EVENT = "experiment.exposure";
+const ASSIGNMENTS_SELECTOR = 'script[type="application/json"][data-aci-assignments]';
+const ASSIGNMENTS_VERSION = 1;
+function parseAssignment(value) {
+    if (typeof value !== "object" || value === null)
+        return null;
+    const record = value;
+    const experimentId = record.experimentId;
+    const armId = record.armId;
+    const allocationVersion = record.allocationVersion;
+    if (typeof experimentId !== "string" ||
+        experimentId === "" ||
+        typeof armId !== "string" ||
+        armId === "" ||
+        typeof allocationVersion !== "string") {
+        return null;
+    }
+    return { experimentId, armId, allocationVersion };
+}
+/**
+ * readAssignments parses the page's data-aci-assignments tag. Absence, a
+ * malformed body, or an unknown version are tolerated as "no assignments"
+ * (debug record, no throw).
+ */
+export function readAssignments(doc, debug) {
+    try {
+        const tag = doc.querySelector(ASSIGNMENTS_SELECTOR);
+        if (!tag)
+            return [];
+        const raw = tag.textContent;
+        if (raw == null || raw.trim() === "")
+            return [];
+        const parsed = JSON.parse(raw);
+        if (typeof parsed !== "object" || parsed === null) {
+            debug?.("capture", { reason: "assignments_malformed" });
+            return [];
+        }
+        const body = parsed;
+        if (body.v !== ASSIGNMENTS_VERSION || !Array.isArray(body.experiments)) {
+            debug?.("capture", { reason: "assignments_malformed" });
+            return [];
+        }
+        const assignments = [];
+        for (const entry of body.experiments) {
+            const assignment = parseAssignment(entry);
+            if (assignment)
+                assignments.push(assignment);
+        }
+        return assignments;
+    }
+    catch (err) {
+        debug?.("capture", {
+            reason: "assignments_parse_failed",
+            error: String(err),
+        });
+        return [];
+    }
+}
+/**
+ * withAssignmentContext stamps the first active assignment's experiment
+ * context onto an event that does not already carry one (REQ-3). Events with
+ * explicit context (exposures, explicit conversions) are never overwritten.
+ */
+export function withAssignmentContext(event, handle) {
+    if (!handle || event.experiment !== undefined)
+        return event;
+    const first = handle.getActiveAssignments()[0];
+    if (!first)
+        return event;
+    const experiment = {
+        experimentId: first.experimentId,
+        armId: first.armId,
+        allocationVersion: first.allocationVersion,
+    };
+    return { ...event, experiment };
+}
+/**
+ * createAssignments builds the assignments collector without emitting
+ * anything: creation and exposure emission are split so init can construct
+ * the emit pipeline against the handle before any event flows (no circular
+ * "emit captures a not-yet-assigned handle" wiring). start() reads the tag
+ * and emits exposures; rearm() is the SPA-navigation reset, fanned out from
+ * the single navigation hook installed by init — so an "exposure per page
+ * view" matches a "page view" exactly.
+ */
+export function createAssignments(env) {
+    let active = [];
+    const exposed = new Set();
+    let emit;
+    const arm = () => {
+        active = readAssignments(env.document, env.debug);
+        for (const assignment of active) {
+            if (exposed.has(assignment.experimentId))
+                continue;
+            exposed.add(assignment.experimentId);
+            emit?.({
+                eventName: EXPERIMENT_EXPOSURE_EVENT,
+                url: env.window.location.href,
+                experiment: {
+                    experimentId: assignment.experimentId,
+                    armId: assignment.armId,
+                    allocationVersion: assignment.allocationVersion,
+                },
+            });
+        }
+    };
+    return {
+        getActiveAssignments: () => active.map((assignment) => ({ ...assignment })),
+        start(emitFn) {
+            emit = emitFn;
+            arm();
+        },
+        rearm() {
+            exposed.clear();
+            arm();
+        },
+    };
+}

package/dist/collect/batcher.d.ts

@@ -1,4 +1,16 @@
 import type { DebugFn } from "./config.js";
+/**
+ * Structured experiment context (personalization-reporting REQ-1/REQ-3):
+ * populated from the page's data-aci-assignments tag so conversions are
+ * attributable to (experiment, arm) at ingest. Explicit conversions may add
+ * goalId.
+ */
+export interface ExperimentContext {
+    experimentId: string;
+    armId: string;
+    allocationVersion: string;
+    goalId?: string;
+}
 /** One collect event on the wire (personalization-data-plane design/04). */
 export interface CollectEvent {
     eventId: string;
@@ -7,11 +19,20 @@ export interface CollectEvent {
     properties?: Record<string, unknown>;
     url?: string;
     referrer?: string;
+    experiment?: ExperimentContext;
 }
 /** An event at capture time, before the eventId is stamped. */
 export type PendingEvent = Omit<CollectEvent, "eventId">;
 /** Planning threshold: full serialized envelope, UTF-8 bytes. */
 export declare const MAX_BATCH_BYTES: number;
+/**
+ * Hard event-count cap per envelope. The Next collect-route imports this
+ * constant and rejects larger envelopes (the Go handler enforces only the
+ * 64KiB body cap today), so a byte-capped-only batch of small events (~400
+ * fit in 60KiB) would 400 on that host and silently lose the whole flush.
+ * The client caps at the strictest host.
+ */
+export declare const MAX_BATCH_EVENTS = 100;
 /** Flush interval (build-time constant, design/04 config table). */
 export declare const FLUSH_INTERVAL_MS = 5000;
 export interface BatcherTimers {

package/dist/collect/batcher.js

@@ -4,6 +4,14 @@
 // per-event size computed at enqueue — so a flush stays O(n).
 /** Planning threshold: full serialized envelope, UTF-8 bytes. */
 export const MAX_BATCH_BYTES = 60 * 1024;
+/**
+ * Hard event-count cap per envelope. The Next collect-route imports this
+ * constant and rejects larger envelopes (the Go handler enforces only the
+ * 64KiB body cap today), so a byte-capped-only batch of small events (~400
+ * fit in 60KiB) would 400 on that host and silently lose the whole flush.
+ * The client caps at the strictest host.
+ */
+export const MAX_BATCH_EVENTS = 100;
 /** Flush interval (build-time constant, design/04 config table). */
 export const FLUSH_INTERVAL_MS = 5000;
 const ENVELOPE_PREFIX = '{"events":[';
@@ -111,6 +119,8 @@ export class Batcher {
                 const next = this.queue[0];
                 if (ENVELOPE_OVERHEAD + next.bytes > this.maxBytes)
                     break; // oversize: outer loop drops it
+                if (parts.length >= MAX_BATCH_EVENTS)
+                    break; // host-side envelope cap
                 const nextSize = size + next.bytes + (parts.length > 0 ? 1 : 0);
                 if (nextSize > this.maxBytes)
                     break;

package/dist/collect/declarative.d.ts

@@ -31,5 +31,5 @@ export declare function toCustomEventName(raw: unknown): string | undefined;
  * environment has an IntersectionObserver, observes every visible-declared
  * element present at start.
  */
-export declare function startDeclarative(emit: (event: PendingEvent) => void, env: DeclarativeEnv): void;
+export declare function startDeclarative(emit: (event: PendingEvent) => void, env: DeclarativeEnv, refresh?: () => void): void;
 export {};

package/dist/collect/declarative.js

@@ -6,6 +6,7 @@
 const EVENT_ATTR = "data-aci-event";
 const ON_ATTR = "data-aci-on";
 const PROP_ATTR_PREFIX = "data-aci-prop-";
+const REFRESH_ATTR = "data-aci-refresh";
 const CUSTOM_PREFIX = "custom.";
 const VISIBLE_THRESHOLD = 0.5;
 /**
@@ -50,11 +51,16 @@ function trigger(el) {
  * environment has an IntersectionObserver, observes every visible-declared
  * element present at start.
  */
-export function startDeclarative(emit, env) {
+export function startDeclarative(emit, env, refresh) {
     const { document: doc, debug } = env;
     doc.addEventListener("click", (e) => {
         try {
             const target = e.target;
+            const refreshTarget = target?.closest?.(`[${REFRESH_ATTR}]`);
+            if (refreshTarget) {
+                refresh?.();
+                return;
+            }
             const el = target?.closest?.(`[${EVENT_ATTR}]`);
             if (!el)
                 return;

package/dist/collect/index.js

@@ -3,6 +3,7 @@
 // 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 { Batcher } from "./batcher.js";
 import { createDebug, readTagConfig } from "./config.js";
 import { start as startC15t } from "./consent/adapters/c15t.js";
@@ -13,8 +14,8 @@ import { applyConsent, envelopeGrantsPersonalization, readConsentCookie, sanitiz
 import { startDeclarative } from "./declarative.js";
 import { GapBuffer, hasMintMarker, maybeFlushGapBuffer, routeEvent, } from "./gapbuffer.js";
 import { startLinkClicks } from "./linkclicks.js";
-import { startPageViews } from "./pageviews.js";
-import { send } from "./transport.js";
+import { installNavigationHook, startPageViews, } from "./pageviews.js";
+import { refreshClaims, send } from "./transport.js";
 import { ulid } from "./ulid.js";
 import { startVariationViews } from "./variationviews.js";
 import { startWebVitals } from "./webvitals.js";
@@ -94,12 +95,24 @@ 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
+        // 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) => {
             routeEvent({
-                ...event,
+                ...withAssignmentContext(event, assignments),
                 eventId: ulid(undefined, (bytes) => w.crypto.getRandomValues(bytes)),
             }, { grants, marker, gapBuffer, batcher });
         };
+        // 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 }),
             consent: ({ p, src }) => {
@@ -111,11 +124,24 @@ export function init(win) {
                 applyConsent(purposes, typeof src === "string" && src.trim() !== "" ? src.trim() : "manual", { document: doc, gapBuffer });
             },
         }, debug);
-        startPageViews(emit, w);
+        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,
+        ]);
         startDeclarative(emit, {
             document: doc,
             intersectionObserver: w.IntersectionObserver,
             debug,
+        }, () => {
+            void refreshClaims(transportEnv).then((refreshed) => {
+                if (refreshed)
+                    w.location.reload();
+            });
         });
         startLinkClicks(emit, { document: doc, debug });
         startWebVitals(emit, {

package/dist/collect/pageviews.d.ts

@@ -15,8 +15,20 @@ export interface PageViewWindow {
     addEventListener(type: string, fn: () => void): void;
 }
 /**
- * startPageViews emits the initial page view and hooks
- * pushState/replaceState/popstate for SPA route changes.
+ * 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 startPageViews(emit: (event: PendingEvent) => void, win: PageViewWindow): void;
+export declare function installNavigationHook(win: PageViewWindow, subscribers: ReadonlyArray<() => void>): void;
+/**
+ * startPageViews emits the initial page view and returns the emitter for
+ * SPA route-change views — init subscribes it to the single navigation hook
+ * (after the assignments re-arm; see installNavigationHook).
+ */
+export declare function startPageViews(emit: (event: PendingEvent) => void, win: PageViewWindow): () => void;
 export {};

package/dist/collect/pageviews.js

@@ -9,34 +9,49 @@ function stripHash(href) {
     return i === -1 ? href : href.slice(0, i);
 }
 /**
- * startPageViews emits the initial page view and hooks
- * pushState/replaceState/popstate for SPA route changes.
+ * 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 startPageViews(emit, win) {
-    const view = () => emit({
-        eventName: PAGE_VIEW_EVENT,
-        url: win.location.href,
-        referrer: win.document.referrer,
-    });
+export function installNavigationHook(win, subscribers) {
     let last = stripHash(win.location.href);
-    view();
-    const onNavigate = () => {
+    const handler = () => {
         const current = stripHash(win.location.href);
         if (current === last)
             return; // hash-only change or same-URL repeat
         last = current;
-        view();
+        for (const onNavigate of subscribers)
+            onNavigate();
     };
     const history = win.history;
     const wrap = (method) => {
         const original = history[method].bind(history);
         history[method] = (...args) => {
             const result = original(...args);
-            onNavigate();
+            handler();
             return result;
         };
     };
     wrap("pushState");
     wrap("replaceState");
-    win.addEventListener("popstate", onNavigate);
+    win.addEventListener("popstate", handler);
+}
+/**
+ * startPageViews emits the initial page view and returns the emitter for
+ * SPA route-change views — init subscribes it to the single navigation hook
+ * (after the assignments re-arm; see installNavigationHook).
+ */
+export function startPageViews(emit, win) {
+    const view = () => emit({
+        eventName: PAGE_VIEW_EVENT,
+        url: win.location.href,
+        referrer: win.document.referrer,
+    });
+    view();
+    return view;
 }

package/dist/collect/transport.d.ts

@@ -7,6 +7,7 @@ export type FetchLike = (input: string, init?: {
     method?: string;
     body?: Blob;
     keepalive?: boolean;
+    credentials?: "same-origin";
 }) => Promise<unknown>;
 export interface TransportEnv {
     /** Present key (even if undefined) overrides the global for tests. */
@@ -20,3 +21,4 @@ export interface TransportEnv {
  * never affected.
  */
 export declare function send(body: string, env?: TransportEnv): void;
+export declare function refreshClaims(env?: TransportEnv): Promise<boolean>;

package/dist/collect/transport.js

@@ -50,3 +50,35 @@ export function send(body, env) {
         debug?.("flush", { reason: "fetch_failed", error: String(err) });
     }
 }
+// refreshClaims deliberately uses fetch rather than sendBeacon. The host's
+// response may refresh the visitor's audience state, so this explicit action
+// must make a normal same-origin request with an empty event envelope.
+export function refreshClaims(env) {
+    const fetchFn = env !== undefined && "fetch" in env
+        ? env.fetch
+        : globalThis.fetch;
+    if (!fetchFn)
+        return Promise.resolve(false);
+    try {
+        const body = new Blob(['{"events":[]}'], { type: "text/plain" });
+        return fetchFn(COLLECT_PATH, {
+            method: "POST",
+            body,
+            keepalive: true,
+            credentials: "same-origin",
+        }).then((response) => {
+            if (typeof response === "object" && response !== null && "ok" in response && response.ok === false) {
+                env?.debug?.("flush", { reason: "refresh_failed", status: "not_ok" });
+                return false;
+            }
+            return true;
+        }).catch((err) => {
+            env?.debug?.("flush", { reason: "refresh_failed", error: String(err) });
+            return false;
+        });
+    }
+    catch (err) {
+        env?.debug?.("flush", { reason: "refresh_failed", error: String(err) });
+        return Promise.resolve(false);
+    }
+}

package/dist/content/personalization.d.ts

@@ -55,3 +55,38 @@ export declare function collectTagAttributes(siteConfig: PersonalizationSiteConf
  * when personalization is disabled.
  */
 export declare function collectScriptTagHTML(siteConfig: PersonalizationSiteConfig | null | undefined): string;
+/** Version of the data-aci-assignments tag body. */
+export declare const ASSIGNMENTS_TAG_VERSION = 1;
+/**
+ * One experiment assignment carried by a variant payload's `experiments`
+ * block (wire field names match the SDK event contract).
+ */
+export interface ExperimentAssignmentContext {
+    experimentId: string;
+    armId: string;
+    allocationVersion: string;
+}
+/**
+ * The minimal page-payload surface assignments tag emission reads: the
+ * top-level `experiments` block stamped at build time onto experiment
+ * variant payloads. `KernelPage` satisfies this structurally.
+ */
+export interface AssignmentsPayloadSource {
+    experiments?: ExperimentAssignmentContext[] | null;
+}
+/**
+ * assignmentsScriptJSON derives the HTML-safe JSON body of the
+ * data-aci-assignments tag ({"v":1,"experiments":[…]}) from the page
+ * payload, or "" when the payload carries no experiment assignments.
+ * `<` / `>` / `&` are \u-escaped so the JSON can never break out of the
+ * script element (standard JSON-in-script escaping; application/json tags
+ * are data, never executed).
+ */
+export declare function assignmentsScriptJSON(page: AssignmentsPayloadSource | null | undefined): string;
+/**
+ * assignmentsScriptTagHTML renders the contract tag
+ * (`<script type="application/json" data-aci-assignments>…</script>`,
+ * design/04) as an HTML snippet for emitters without a React element seam
+ * (the Astro slug page). Returns "" when the payload carries no assignments.
+ */
+export declare function assignmentsScriptTagHTML(page: AssignmentsPayloadSource | null | undefined): string;

package/dist/content/personalization.js

@@ -52,3 +52,60 @@ function escapeAttribute(value) {
         .replace(/</g, "&lt;")
         .replace(/>/g, "&gt;");
 }
+// ---------------------------------------------------------------------------
+// Assignments tag (personalization-reporting design/04, D-PR-6): experiment
+// variant payloads carry a build-time `experiments` block; the starters
+// render it as ONE page-level JSON script tag the collect SDK reads for
+// exposure emission and context stamping. Base payloads carry no block and
+// emit no tag. Like the collect tag, both framework emitters derive the tag
+// through this module so there is exactly one derivation code path.
+// ---------------------------------------------------------------------------
+/** Version of the data-aci-assignments tag body. */
+export const ASSIGNMENTS_TAG_VERSION = 1;
+function isAssignment(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const record = value;
+    return (typeof record.experimentId === "string" &&
+        record.experimentId !== "" &&
+        typeof record.armId === "string" &&
+        record.armId !== "" &&
+        typeof record.allocationVersion === "string");
+}
+/**
+ * assignmentsScriptJSON derives the HTML-safe JSON body of the
+ * data-aci-assignments tag ({"v":1,"experiments":[…]}) from the page
+ * payload, or "" when the payload carries no experiment assignments.
+ * `<` / `>` / `&` are \u-escaped so the JSON can never break out of the
+ * script element (standard JSON-in-script escaping; application/json tags
+ * are data, never executed).
+ */
+export function assignmentsScriptJSON(page) {
+    const experiments = (page?.experiments ?? []).filter(isAssignment);
+    if (experiments.length === 0)
+        return "";
+    const body = JSON.stringify({
+        v: ASSIGNMENTS_TAG_VERSION,
+        experiments: experiments.map(({ experimentId, armId, allocationVersion }) => ({
+            experimentId,
+            armId,
+            allocationVersion,
+        })),
+    });
+    return body
+        .replace(/</g, "\\u003c")
+        .replace(/>/g, "\\u003e")
+        .replace(/&/g, "\\u0026");
+}
+/**
+ * assignmentsScriptTagHTML renders the contract tag
+ * (`<script type="application/json" data-aci-assignments>…</script>`,
+ * design/04) as an HTML snippet for emitters without a React element seam
+ * (the Astro slug page). Returns "" when the payload carries no assignments.
+ */
+export function assignmentsScriptTagHTML(page) {
+    const json = assignmentsScriptJSON(page);
+    if (!json)
+        return "";
+    return `<script type="application/json" data-aci-assignments>${json}</script>`;
+}

package/dist/content/types.d.ts

@@ -1,4 +1,4 @@
-import type { SitePersonalizationConfig } from './personalization.js';
+import type { ExperimentAssignmentContext, SitePersonalizationConfig } from './personalization.js';
 export type ButtonVariant = 'primary' | 'secondary' | 'tertiary' | 'outline' | 'ghost';
 export interface KernelImage {
     src: string;
@@ -58,6 +58,12 @@ export interface KernelPage {
     layout: string;
     metadata: KernelPageSeo;
     regions: Record<string, KernelPageBlock[]>;
+    /**
+     * Build-time experiment assignment context (personalization-reporting
+     * design/04); present only on experiment variant payloads. The starters
+     * render it as the data-aci-assignments tag.
+     */
+    experiments?: ExperimentAssignmentContext[];
 }
 export interface KernelSiteConfig {
     id: string;

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

@@ -0,0 +1,11 @@
+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;
+};