@xenia-martech/sdk-js 1.1.0 → 1.2.0-dev.1

package/dist/client/react/index.d.cts

@@ -1,7 +1,7 @@
 import * as react from 'react';
 import { ReactNode, ElementType, ComponentType } from 'react';
-import { y as XeniaClientOptions, x as XeniaClient, s as ResolveResult, q as ResolveBatchResult, J as JsonValue, t as WebhookResponse, R as ResolveBatchItem, g as AnalyticsEventName, T as TrackOptions, e as XeniaAction, I as InteractionType, o as MessageMountContext, c as MessageComponentRenderer } from '../../actions-CKeiofxJ.cjs';
-export { A as AnalyticsContext, h as AnalyticsIdentity, i as AnalyticsIngestResponse, j as ClientEvent, C as ConsentState, k as ContentSwap, l as IdentifyRequest, m as IdentifyResponse, M as MessageCta, f as MessagePlacement, p as MessageRenderContext, b as MessageTemplateFn, P as PersonalizationSwap, r as ResolveOptions, X as XeniaConfig, a as XeniaEvent, z as createXeniaClient, B as extractContentSwaps, D as parseActions, E as spliceSlots } from '../../actions-CKeiofxJ.cjs';
+import { E as XeniaClientOptions, D as XeniaClient, w as ResolveResult, u as ResolveBatchResult, J as JsonValue, x as WebhookResponse, R as ResolveBatchItem, g as AnalyticsEventName, T as TrackOptions, P as PagePersonalizeOptions, j as AppliedSwap, s as PageRef, e as XeniaAction, I as InteractionType, q as MessageMountContext, c as MessageComponentRenderer } from '../../actions-D9_aAvCv.cjs';
+export { A as AnalyticsContext, h as AnalyticsIdentity, i as AnalyticsIngestResponse, k as ClientEvent, l as CmsAdapter, C as ConsentState, m as ContentSwap, n as IdentifyRequest, o as IdentifyResponse, M as MessageCta, f as MessagePlacement, r as MessageRenderContext, b as MessageTemplateFn, t as PersonalizationSwap, v as ResolveOptions, X as XeniaConfig, a as XeniaEvent, F as XeniaMarker, G as createXeniaClient, H as extractContentSwaps, K as parseActions, L as pendingTargets, N as personalizeContent, O as personalizePage, Q as spliceSlots } from '../../actions-D9_aAvCv.cjs';
 
 interface XeniaProviderProps extends XeniaClientOptions {
     children: ReactNode;
@@ -118,6 +118,56 @@ declare function useWebhook(triggerId: string): UseWebhookResult;
 /** Read the last saved webhook response for a key (reactive to sends via re-render). */
 declare function useXeniaResponse(key: string): WebhookResponse | undefined;
 
+/** Where one personalized entry stands while the page resolves. */
+type EntryStatus = "pending" | "personalized" | "base";
+interface UsePersonalizedContentOptions extends PagePersonalizeOptions {
+    /**
+     * What to render before Xenia answers:
+     * - `"base-first"` (default): the CMS content immediately, swapped in place round by round
+     *   (best LCP; personalized sections can visibly change).
+     * - `"hide-until-resolved"`: `content` is null until done or `hideTimeoutMs` — render a skeleton
+     *   while `isLoading` (no flicker, costs up to `hideTimeoutMs` of blank).
+     */
+    render?: "base-first" | "hide-until-resolved";
+    /** Cap on the hidden period for `"hide-until-resolved"`. Default: `timeoutMs` (300). */
+    hideTimeoutMs?: number;
+}
+interface UsePersonalizedContentResult<T> {
+    content: T | null;
+    isLoading: boolean;
+    /**
+     * True once every personalized entry was decided. False while loading, and after a timeout or a
+     * failed Xenia/CMS call — the undecided entries then show their base content.
+     */
+    complete: boolean;
+    applied: AppliedSwap[];
+    /** Per-entry state, for skeletons / fades on just the sections being decided. */
+    status(entryId: string): EntryStatus;
+}
+/**
+ * Personalize a CMS page in the browser — `XeniaClient.personalizeContent` as a hook. Re-runs when
+ * `page` (by identity) or the serialized `data`/`locale` change. Never throws: on failure the base
+ * content renders. For pages that can render on the server, prefer `XeniaServer.personalizeContent`
+ * (no flicker, no client round trip).
+ */
+declare function usePersonalizedContent<T>(page: T | null | undefined, opts: UsePersonalizedContentOptions): UsePersonalizedContentResult<T>;
+/**
+ * Fetch a page through `opts.cms` and personalize it in the browser — `usePersonalizedContent`
+ * without the fetch in app code. `content` is null (and `isLoading` true) while the page loads; a
+ * failed or missing page ends with `content: null`, `isLoading: false`.
+ */
+declare function usePersonalizedPage<T = unknown>(ref: PageRef, opts: UsePersonalizedContentOptions): UsePersonalizedContentResult<T>;
+/** Shares a `usePersonalizedContent` result with nested sections (`useXeniaEntry`). */
+declare function XeniaContentProvider(props: {
+    value: UsePersonalizedContentResult<unknown>;
+    children?: ReactNode;
+}): react.FunctionComponentElement<react.ProviderProps<UsePersonalizedContentResult<unknown> | null>>;
+/** Loading state of one entry inside a `<XeniaContentProvider>` — e.g. a skeleton for just that section. */
+declare function useXeniaEntry(entryId: string): {
+    status: EntryStatus;
+    isLoading: boolean;
+};
+
 interface XeniaTrackProps {
     /** Event id to fire. */
     event: string;
@@ -173,4 +223,4 @@ type XeniaMessageComponentProps = MessageMountContext;
  */
 declare function reactMessageComponent(Component: ComponentType<XeniaMessageComponentProps>): MessageComponentRenderer;
 
-export { AnalyticsEventName, InteractionType, JsonValue, MessageComponentRenderer, MessageMountContext, ResolveBatchItem, ResolveBatchResult, ResolveResult, TrackOptions, type UsePersonalizationResolveResult, type UsePersonalizationResolveSlotsResult, type UsePersonalizationResult, type UsePersonalizationSlotsResult, type UseWebhookResult, WebhookResponse, XeniaAction, XeniaClient, XeniaClientOptions, XeniaContext, XeniaMessage, type XeniaMessageComponentProps, type XeniaMessageProps, XeniaProvider, type XeniaProviderProps, XeniaTrack, type XeniaTrackProps, reactMessageComponent, usePersonalization, usePersonalizationResolve, usePersonalizationResolveSlots, usePersonalizationSlots, useTrack, useWebhook, useXenia, useXeniaResponse };
+export { AnalyticsEventName, AppliedSwap, type EntryStatus, InteractionType, JsonValue, MessageComponentRenderer, MessageMountContext, PagePersonalizeOptions, PageRef, ResolveBatchItem, ResolveBatchResult, ResolveResult, TrackOptions, type UsePersonalizationResolveResult, type UsePersonalizationResolveSlotsResult, type UsePersonalizationResult, type UsePersonalizationSlotsResult, type UsePersonalizedContentOptions, type UsePersonalizedContentResult, type UseWebhookResult, WebhookResponse, XeniaAction, XeniaClient, XeniaClientOptions, XeniaContentProvider, XeniaContext, XeniaMessage, type XeniaMessageComponentProps, type XeniaMessageProps, XeniaProvider, type XeniaProviderProps, XeniaTrack, type XeniaTrackProps, reactMessageComponent, usePersonalization, usePersonalizationResolve, usePersonalizationResolveSlots, usePersonalizationSlots, usePersonalizedContent, usePersonalizedPage, useTrack, useWebhook, useXenia, useXeniaEntry, useXeniaResponse };

package/dist/client/react/index.d.ts

@@ -1,7 +1,7 @@
 import * as react from 'react';
 import { ReactNode, ElementType, ComponentType } from 'react';
-import { y as XeniaClientOptions, x as XeniaClient, s as ResolveResult, q as ResolveBatchResult, J as JsonValue, t as WebhookResponse, R as ResolveBatchItem, g as AnalyticsEventName, T as TrackOptions, e as XeniaAction, I as InteractionType, o as MessageMountContext, c as MessageComponentRenderer } from '../../actions-CKeiofxJ.js';
-export { A as AnalyticsContext, h as AnalyticsIdentity, i as AnalyticsIngestResponse, j as ClientEvent, C as ConsentState, k as ContentSwap, l as IdentifyRequest, m as IdentifyResponse, M as MessageCta, f as MessagePlacement, p as MessageRenderContext, b as MessageTemplateFn, P as PersonalizationSwap, r as ResolveOptions, X as XeniaConfig, a as XeniaEvent, z as createXeniaClient, B as extractContentSwaps, D as parseActions, E as spliceSlots } from '../../actions-CKeiofxJ.js';
+import { E as XeniaClientOptions, D as XeniaClient, w as ResolveResult, u as ResolveBatchResult, J as JsonValue, x as WebhookResponse, R as ResolveBatchItem, g as AnalyticsEventName, T as TrackOptions, P as PagePersonalizeOptions, j as AppliedSwap, s as PageRef, e as XeniaAction, I as InteractionType, q as MessageMountContext, c as MessageComponentRenderer } from '../../actions-D9_aAvCv.js';
+export { A as AnalyticsContext, h as AnalyticsIdentity, i as AnalyticsIngestResponse, k as ClientEvent, l as CmsAdapter, C as ConsentState, m as ContentSwap, n as IdentifyRequest, o as IdentifyResponse, M as MessageCta, f as MessagePlacement, r as MessageRenderContext, b as MessageTemplateFn, t as PersonalizationSwap, v as ResolveOptions, X as XeniaConfig, a as XeniaEvent, F as XeniaMarker, G as createXeniaClient, H as extractContentSwaps, K as parseActions, L as pendingTargets, N as personalizeContent, O as personalizePage, Q as spliceSlots } from '../../actions-D9_aAvCv.js';
 
 interface XeniaProviderProps extends XeniaClientOptions {
     children: ReactNode;
@@ -118,6 +118,56 @@ declare function useWebhook(triggerId: string): UseWebhookResult;
 /** Read the last saved webhook response for a key (reactive to sends via re-render). */
 declare function useXeniaResponse(key: string): WebhookResponse | undefined;
 
+/** Where one personalized entry stands while the page resolves. */
+type EntryStatus = "pending" | "personalized" | "base";
+interface UsePersonalizedContentOptions extends PagePersonalizeOptions {
+    /**
+     * What to render before Xenia answers:
+     * - `"base-first"` (default): the CMS content immediately, swapped in place round by round
+     *   (best LCP; personalized sections can visibly change).
+     * - `"hide-until-resolved"`: `content` is null until done or `hideTimeoutMs` — render a skeleton
+     *   while `isLoading` (no flicker, costs up to `hideTimeoutMs` of blank).
+     */
+    render?: "base-first" | "hide-until-resolved";
+    /** Cap on the hidden period for `"hide-until-resolved"`. Default: `timeoutMs` (300). */
+    hideTimeoutMs?: number;
+}
+interface UsePersonalizedContentResult<T> {
+    content: T | null;
+    isLoading: boolean;
+    /**
+     * True once every personalized entry was decided. False while loading, and after a timeout or a
+     * failed Xenia/CMS call — the undecided entries then show their base content.
+     */
+    complete: boolean;
+    applied: AppliedSwap[];
+    /** Per-entry state, for skeletons / fades on just the sections being decided. */
+    status(entryId: string): EntryStatus;
+}
+/**
+ * Personalize a CMS page in the browser — `XeniaClient.personalizeContent` as a hook. Re-runs when
+ * `page` (by identity) or the serialized `data`/`locale` change. Never throws: on failure the base
+ * content renders. For pages that can render on the server, prefer `XeniaServer.personalizeContent`
+ * (no flicker, no client round trip).
+ */
+declare function usePersonalizedContent<T>(page: T | null | undefined, opts: UsePersonalizedContentOptions): UsePersonalizedContentResult<T>;
+/**
+ * Fetch a page through `opts.cms` and personalize it in the browser — `usePersonalizedContent`
+ * without the fetch in app code. `content` is null (and `isLoading` true) while the page loads; a
+ * failed or missing page ends with `content: null`, `isLoading: false`.
+ */
+declare function usePersonalizedPage<T = unknown>(ref: PageRef, opts: UsePersonalizedContentOptions): UsePersonalizedContentResult<T>;
+/** Shares a `usePersonalizedContent` result with nested sections (`useXeniaEntry`). */
+declare function XeniaContentProvider(props: {
+    value: UsePersonalizedContentResult<unknown>;
+    children?: ReactNode;
+}): react.FunctionComponentElement<react.ProviderProps<UsePersonalizedContentResult<unknown> | null>>;
+/** Loading state of one entry inside a `<XeniaContentProvider>` — e.g. a skeleton for just that section. */
+declare function useXeniaEntry(entryId: string): {
+    status: EntryStatus;
+    isLoading: boolean;
+};
+
 interface XeniaTrackProps {
     /** Event id to fire. */
     event: string;
@@ -173,4 +223,4 @@ type XeniaMessageComponentProps = MessageMountContext;
  */
 declare function reactMessageComponent(Component: ComponentType<XeniaMessageComponentProps>): MessageComponentRenderer;
 
-export { AnalyticsEventName, InteractionType, JsonValue, MessageComponentRenderer, MessageMountContext, ResolveBatchItem, ResolveBatchResult, ResolveResult, TrackOptions, type UsePersonalizationResolveResult, type UsePersonalizationResolveSlotsResult, type UsePersonalizationResult, type UsePersonalizationSlotsResult, type UseWebhookResult, WebhookResponse, XeniaAction, XeniaClient, XeniaClientOptions, XeniaContext, XeniaMessage, type XeniaMessageComponentProps, type XeniaMessageProps, XeniaProvider, type XeniaProviderProps, XeniaTrack, type XeniaTrackProps, reactMessageComponent, usePersonalization, usePersonalizationResolve, usePersonalizationResolveSlots, usePersonalizationSlots, useTrack, useWebhook, useXenia, useXeniaResponse };
+export { AnalyticsEventName, AppliedSwap, type EntryStatus, InteractionType, JsonValue, MessageComponentRenderer, MessageMountContext, PagePersonalizeOptions, PageRef, ResolveBatchItem, ResolveBatchResult, ResolveResult, TrackOptions, type UsePersonalizationResolveResult, type UsePersonalizationResolveSlotsResult, type UsePersonalizationResult, type UsePersonalizationSlotsResult, type UsePersonalizedContentOptions, type UsePersonalizedContentResult, type UseWebhookResult, WebhookResponse, XeniaAction, XeniaClient, XeniaClientOptions, XeniaContentProvider, XeniaContext, XeniaMessage, type XeniaMessageComponentProps, type XeniaMessageProps, XeniaProvider, type XeniaProviderProps, XeniaTrack, type XeniaTrackProps, reactMessageComponent, usePersonalization, usePersonalizationResolve, usePersonalizationResolveSlots, usePersonalizationSlots, usePersonalizedContent, usePersonalizedPage, useTrack, useWebhook, useXenia, useXeniaEntry, useXeniaResponse };

package/dist/client/react/index.js

@@ -547,6 +547,25 @@ var XeniaApi = class {
     });
     return data;
   }
+  /**
+   * Resolve personalized CMS entries by id for one visitor (≤200) —
+   * `POST /api/personalization/resolve-entries`. The page resolver
+   * ({@link personalizeContent}) calls this once per round with the runtime
+   * targets it found; callers rarely need it directly.
+   */
+  async resolveEntries(entryIds, opts = {}) {
+    const { data } = await this.http.request({
+      method: "POST",
+      path: "/api/personalization/resolve-entries",
+      headers: await this.authHeaders(),
+      body: compact({
+        entryIds,
+        data: opts.data,
+        locale: opts.locale
+      })
+    });
+    return data;
+  }
 };
 
 // src/core/cookie-names.ts
@@ -661,6 +680,233 @@ function toEventId(raw) {
   return digest;
 }
 
+// src/core/personalize-content.ts
+var DEFAULT_TIMEOUT_MS = 300;
+var DEFAULT_MAX_ROUNDS = 3;
+var copyOf = (v) => v && typeof v === "object" && typeof structuredClone === "function" ? structuredClone(v) : v;
+async function personalizeContent(payload, options) {
+  const { cms } = options;
+  const maxRounds = options.maxRounds ?? DEFAULT_MAX_ROUNDS;
+  const deadline = Date.now() + (options.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+  const applied = [];
+  const report = (swap) => {
+    applied.push(swap);
+    try {
+      options.onApplied?.(swap);
+    } catch {
+    }
+  };
+  let content = payload;
+  try {
+    if (!options.inPlace && typeof structuredClone === "function") content = structuredClone(content);
+    content = cms.prepare ? cms.prepare(content) : content;
+  } catch (error) {
+    return { content: payload, applied, complete: false, error };
+  }
+  const box = { root: content };
+  const settled = /* @__PURE__ */ new WeakSet();
+  const decided = /* @__PURE__ */ new Map();
+  let frontier = [{ parent: box, key: "root", value: box.root }];
+  const settle = (target, d, round) => {
+    settled.add(target.entry);
+    cms.clearMarker?.(target.entry);
+    const items = d.items.map(copyOf);
+    if (!d.decision || items.length === 0) {
+      return deferredSlots(target, cms);
+    }
+    for (const item of items) if (item && typeof item === "object") settled.add(item);
+    const op = d.decision.op ?? target.marker.op ?? "replace";
+    const next = apply(target, op, d.decision.field ?? target.marker.field, items, cms);
+    report({
+      target: target.id,
+      kind: "runtime",
+      op,
+      entryIds: items.map((e) => cms.entryId(e)).filter((id) => !!id),
+      contentKey: d.decision.contentKey,
+      bucket: d.decision.bucket,
+      round
+    });
+    return next;
+  };
+  for (let round = 0; ; round++) {
+    const pending = walk(frontier, cms, settled, round, report, (t) => {
+      const d = decided.get(t.id);
+      return d ? settle(t, d, round) : void 0;
+    });
+    if (pending.size === 0) return { content: box.root, applied, complete: true };
+    if (!options.resolve || round >= maxRounds) {
+      return { content: box.root, applied, complete: !options.resolve };
+    }
+    progress(options, { content: box.root, round, pending: [...pending.keys()] });
+    let decisions;
+    let entriesById;
+    let queried;
+    try {
+      decisions = await withDeadline(options.resolve([...pending.keys()]), deadline);
+      ({ entriesById, queried } = await withDeadline(loadReplacements(decisions, cms, options.locale), deadline));
+    } catch (error) {
+      return { content: box.root, applied, complete: false, error: error === TIMEOUT ? void 0 : error };
+    }
+    const byTarget = new Map(decisions.map((d) => [d.target, d]));
+    frontier = [];
+    for (const target of pending.values()) {
+      const decision = byTarget.get(target.id);
+      const items = decision ? decision.ids ? decision.ids.map((id) => entriesById.get(id)).filter((e) => e !== void 0) : queried.get(decision) ?? [] : [];
+      const d = { decision, items };
+      decided.set(target.id, d);
+      frontier.push(...settle(target, d, round));
+    }
+    progress(options, { content: box.root, round, pending: [] });
+  }
+}
+function progress(options, p) {
+  try {
+    options.onProgress?.(p);
+  } catch {
+  }
+}
+function walk(frontier, cms, settled, round, report, reuse) {
+  const pending = /* @__PURE__ */ new Map();
+  const seen = /* @__PURE__ */ new WeakSet();
+  const deferred = /* @__PURE__ */ new WeakSet();
+  const queue = [...frontier];
+  while (queue.length > 0) {
+    const slot = queue.shift();
+    const value = slot.value;
+    if (!value || typeof value !== "object" || deferred.has(value)) continue;
+    const id = settled.has(value) ? void 0 : cms.entryId(value);
+    const marker = id ? cms.marker(value) : null;
+    if (id && marker?.kind === "runtime") {
+      const again = reuse({ id, marker, entry: value, slots: [slot] });
+      if (again) {
+        queue.push(...again);
+        continue;
+      }
+      const existing = pending.get(id);
+      if (existing) {
+        existing.slots.push(slot);
+      } else {
+        pending.set(id, { id, marker, entry: value, slots: [slot] });
+        if (marker.op === "items" && marker.field) {
+          const held = cms.getField(value, marker.field);
+          if (held && typeof held === "object") deferred.add(held);
+          queue.push(...children(value));
+        }
+      }
+      continue;
+    }
+    if (id && marker?.kind === "static") {
+      const variants = cms.staticVariants(value).filter((v) => v && typeof v === "object");
+      settled.add(value);
+      cms.clearMarker?.(value);
+      if (variants.length > 0) {
+        for (const v of variants) settled.add(v);
+        const op = marker.op ?? "replace";
+        const target = { entry: value, slots: [slot] };
+        queue.push(...apply(target, op, marker.field, variants, cms));
+        report({
+          target: id,
+          kind: "static",
+          op,
+          entryIds: variants.map((v) => cms.entryId(v)).filter((x) => !!x),
+          round
+        });
+        continue;
+      }
+    }
+    if (seen.has(value)) continue;
+    seen.add(value);
+    queue.push(...children(value));
+  }
+  return pending;
+}
+function apply(target, op, field, items, cms) {
+  if (op === "items") {
+    if (field) {
+      cms.setField(target.entry, field, items);
+      return [{ parent: target.entry, key: field, value: cms.getField(target.entry, field) }];
+    }
+    if (cms.mergeItems) {
+      cms.mergeItems(target.entry, items[0]);
+      return target.slots.map((s) => ({ ...s, value: target.entry }));
+    }
+    op = "replace";
+  }
+  const next = [];
+  for (const slot of target.slots) {
+    const placed = op === "expand" && Array.isArray(slot.parent) ? items : [items[0]];
+    if (Array.isArray(slot.parent)) {
+      const index = slot.parent.indexOf(target.entry);
+      if (index < 0) continue;
+      slot.parent.splice(index, 1, ...placed);
+    } else {
+      slot.parent[slot.key] = placed[0];
+    }
+    for (const value of placed) next.push({ parent: slot.parent, key: slot.key, value });
+  }
+  return next;
+}
+function deferredSlots(target, cms) {
+  if (target.marker.op === "items" && target.marker.field) {
+    return [{ parent: target.entry, key: target.marker.field, value: cms.getField(target.entry, target.marker.field) }];
+  }
+  return target.slots.map((s) => ({ ...s, value: target.entry }));
+}
+function children(value) {
+  if (Array.isArray(value)) return value.map((v, i) => ({ parent: value, key: i, value: v }));
+  return Object.keys(value).map((k) => ({ parent: value, key: k, value: value[k] }));
+}
+async function loadReplacements(decisions, cms, locale) {
+  const ids = [...new Set(decisions.flatMap((d) => d.ids ?? []))];
+  const queries = decisions.filter((d) => !d.ids && d.query);
+  const [fetched, ...results] = await Promise.all([
+    ids.length > 0 ? cms.fetchEntries(ids, locale) : Promise.resolve([]),
+    ...queries.map((d) => cms.queryEntries(d.query, locale).catch(() => []))
+  ]);
+  const entriesById = /* @__PURE__ */ new Map();
+  for (const entry of fetched) {
+    const id = cms.entryId(entry);
+    if (id) entriesById.set(id, entry);
+  }
+  const queried = /* @__PURE__ */ new Map();
+  queries.forEach((d, i) => queried.set(d, results[i]));
+  return { entriesById, queried };
+}
+var TIMEOUT = /* @__PURE__ */ Symbol("timeout");
+function withDeadline(promise, deadline) {
+  const remaining = deadline - Date.now();
+  if (remaining <= 0) return Promise.reject(TIMEOUT);
+  let timer;
+  return Promise.race([
+    promise,
+    new Promise((_, reject) => {
+      timer = setTimeout(() => reject(TIMEOUT), remaining);
+    })
+  ]).finally(() => clearTimeout(timer));
+}
+function pendingTargets(payload, cms) {
+  try {
+    let content = typeof structuredClone === "function" ? structuredClone(payload) : payload;
+    content = cms.prepare ? cms.prepare(content) : content;
+    const root = { parent: { root: content }, key: "root", value: content };
+    return [...walk([root], cms, /* @__PURE__ */ new WeakSet(), 0, () => {
+    }, () => void 0).keys()];
+  } catch {
+    return [];
+  }
+}
+async function personalizePage(ref, options) {
+  let page;
+  try {
+    if (!options.cms.fetchPage) throw new Error("This CMS adapter cannot fetch pages; use personalizeContent(page)");
+    page = await options.cms.fetchPage(ref, options.locale);
+  } catch (error) {
+    return { content: null, applied: [], complete: false, error };
+  }
+  if (page == null) return { content: null, applied: [], complete: true };
+  return personalizeContent(page, options);
+}
+
 // src/core/response-store.ts
 var MemoryResponseStore = class {
   map = /* @__PURE__ */ new Map();
@@ -1912,7 +2158,10 @@ var XeniaClient = class {
   renderer;
   analyticsQueue;
   tracker = null;
-  ready = false;
+  /** The in-flight (or finished) boot; shared so concurrent `init()` calls start one tracker. */
+  booting = null;
+  /** Bumped by `destroy()`, so a boot still waiting on the device id knows to stop. */
+  generation = 0;
   consentState;
   listeners = /* @__PURE__ */ new Map();
   constructor(options) {
@@ -1942,10 +2191,14 @@ var XeniaClient = class {
     });
   }
   /** Boot the client: resolve device id and start auto-tracking. Idempotent. */
-  async init() {
-    if (this.ready || !isBrowser()) return;
+  init() {
+    if (!isBrowser()) return Promise.resolve();
+    return this.booting ??= this.boot();
+  }
+  async boot() {
+    const generation = this.generation;
     await this.identity.resolveDeviceId();
-    this.ready = true;
+    if (generation !== this.generation) return;
     if (this.analyticsAllowed()) this.analyticsQueue.start();
     if (this.options.autoTrack !== false) {
       this.tracker = new AutoTracker({
@@ -1981,7 +2234,8 @@ var XeniaClient = class {
     this.tracker = null;
     this.renderer.destroy();
     this.analyticsQueue.stop();
-    this.ready = false;
+    this.booting = null;
+    this.generation++;
   }
   // ── Identity ───────────────────────────────────────────────────────────────
   /**
@@ -2110,6 +2364,27 @@ var XeniaClient = class {
   async resolveBatch(items, opts) {
     return this.api.resolveBatch(items, this.withVisitor(opts));
   }
+  /**
+   * Personalize a fetched CMS page: static swaps are applied from the payload, runtime targets are
+   * decided by Xenia in one `resolve-entries` call per nesting level, and replacements are loaded
+   * through `opts.cms` (e.g. `contentfulAdapter(...)`). Never throws — anything undecided within
+   * `opts.timeoutMs` keeps its base content.
+   */
+  async personalizeContent(page, opts) {
+    return personalizeContent(page, { ...opts, resolve: this.entryResolver(opts) });
+  }
+  /**
+   * Fetch a page through `opts.cms` and personalize it — the app passes only the page's identity
+   * (entry id, or `{ contentType, fields: { slug } }`). Never throws: a failed fetch is `content:
+   * null` with `error`, a missing page `content: null`.
+   */
+  async personalizePage(ref, opts) {
+    return personalizePage(ref, { ...opts, resolve: this.entryResolver(opts) });
+  }
+  entryResolver(opts) {
+    const resolveOpts = this.withVisitor({ data: opts.data, locale: opts.locale });
+    return async (ids) => (await this.api.resolveEntries(ids, resolveOpts)).decisions ?? [];
+  }
   /** The SDK-owned visitor anchor: the `identify()`/`config.visitorId` id, else the device id. */
   resolveVisitorId() {
     return this.identity.getVisitorId() ?? this.identity.getDeviceId() ?? void 0;
@@ -2188,8 +2463,8 @@ var XeniaClient = class {
     const response = await this.api.webhook(triggerId, body, opts?.method ?? "POST");
     this.responses.set(triggerId, response);
     this.emit("response", { triggerId, response });
-    const apply = opts?.apply ?? this.options.autoApplyActions !== false;
-    if (apply && response.actions.length) {
+    const apply2 = opts?.apply ?? this.options.autoApplyActions !== false;
+    if (apply2 && response.actions.length) {
       this.applyActions(response.actions);
     }
     return response;
@@ -2243,8 +2518,8 @@ var XeniaClient = class {
       compact({ ...ambient, fields })
     );
     this.emit("response", { triggerId: ref, response });
-    const apply = opts?.apply ?? this.options.autoApplyActions !== false;
-    if (apply && response.actions.length) this.applyActions(response.actions);
+    const apply2 = opts?.apply ?? this.options.autoApplyActions !== false;
+    if (apply2 && response.actions.length) this.applyActions(response.actions);
     return response;
   }
   // ── Imperative render helpers ─────────────────────────────────────────────────
@@ -2322,7 +2597,7 @@ function useXenia() {
   }
   return client;
 }
-function XeniaProvider({ children, client, ...options }) {
+function XeniaProvider({ children: children2, client, ...options }) {
   const ref = useRef(null);
   const instance = useMemo(() => {
     if (client) return client;
@@ -2333,7 +2608,7 @@ function XeniaProvider({ children, client, ...options }) {
     void instance.init();
     return () => instance.destroy();
   }, [instance]);
-  return /* @__PURE__ */ jsx(XeniaContext.Provider, { value: instance, children });
+  return /* @__PURE__ */ jsx(XeniaContext.Provider, { value: instance, children: children2 });
 }
 
 // src/core/content-splice.ts
@@ -2520,12 +2795,92 @@ function useXeniaResponse(key) {
   const xenia = useXenia();
   return xenia.getResponse(key);
 }
+function usePersonalizedContent(page, opts) {
+  const xenia = useXenia();
+  const hide = opts.render === "hide-until-resolved";
+  const initialPending = useMemo(
+    () => new Set(page == null ? [] : pendingTargets(page, opts.cms)),
+    [page]
+    // markers live in `page`; a new adapter object for the same page changes nothing
+  );
+  const [state, setState] = useState(
+    () => ({ page, content: hide ? null : page ?? null, done: false, complete: false, applied: [], pending: initialPending })
+  );
+  const optsRef = useRef(opts);
+  optsRef.current = opts;
+  const optsKey = JSON.stringify({ data: opts.data ?? {}, locale: opts.locale });
+  useEffect(() => {
+    if (page == null) return;
+    let active = true;
+    const o = optsRef.current;
+    setState({ page, content: hide ? null : page, done: false, complete: false, applied: [], pending: initialPending });
+    const reveal = hide ? setTimeout(() => active && setState((s) => s.content ? s : { ...s, content: page }), o.hideTimeoutMs ?? o.timeoutMs ?? 300) : void 0;
+    const applied = [];
+    void xenia.personalizeContent(page, {
+      ...o,
+      onApplied(swap) {
+        applied.push(swap);
+        o.onApplied?.(swap);
+      },
+      onProgress(p) {
+        o.onProgress?.(p);
+        if (!active || hide) return;
+        setState({ page, content: p.content, done: false, complete: false, applied: [...applied], pending: new Set(p.pending) });
+      }
+    }).then((r) => {
+      if (active) setState({ page, content: r.content, done: true, complete: r.complete, applied: r.applied, pending: /* @__PURE__ */ new Set() });
+    }).finally(() => clearTimeout(reveal));
+    return () => {
+      active = false;
+      clearTimeout(reveal);
+    };
+  }, [xenia, page, optsKey, hide, initialPending]);
+  const personalized = new Set(state.applied.map((a) => a.target));
+  const pending = state.page === page ? state.pending : initialPending;
+  return {
+    content: state.content,
+    isLoading: page != null && !state.done,
+    complete: state.complete,
+    applied: state.applied,
+    status: (id) => pending.has(id) ? "pending" : personalized.has(id) ? "personalized" : "base"
+  };
+}
+function usePersonalizedPage(ref, opts) {
+  const [page, setPage] = useState({ value: null, loaded: false });
+  const cmsRef = useRef(opts.cms);
+  cmsRef.current = opts.cms;
+  const refKey = JSON.stringify([ref, opts.locale]);
+  useEffect(() => {
+    let active = true;
+    setPage({ value: null, loaded: false });
+    const fetchPage = cmsRef.current.fetchPage;
+    Promise.resolve(fetchPage ? fetchPage.call(cmsRef.current, ref, opts.locale) : null).then(
+      (value) => active && setPage({ value: value ?? null, loaded: true }),
+      () => active && setPage({ value: null, loaded: true, failed: true })
+    );
+    return () => {
+      active = false;
+    };
+  }, [refKey]);
+  const result = usePersonalizedContent(page.value, opts);
+  const complete = page.value == null ? page.loaded && !page.failed : result.complete;
+  return { ...result, isLoading: !page.loaded || result.isLoading, complete };
+}
+var PersonalizedContentContext = createContext(null);
+function XeniaContentProvider(props) {
+  return createElement(PersonalizedContentContext.Provider, { value: props.value }, props.children);
+}
+function useXeniaEntry(entryId) {
+  const ctx = useContext(PersonalizedContentContext);
+  const status = ctx ? ctx.status(entryId) : "base";
+  return { status, isLoading: status === "pending" };
+}
 function XeniaTrack({
   event,
   on = "click",
   props,
   as = "span",
-  children,
+  children: children2,
   className
 }) {
   const xenia = useXenia();
@@ -2557,7 +2912,7 @@ function XeniaTrack({
   const handlers = on === "click" ? {
     onClick: () => xenia.track(event, { ...props, interactionType: "click" }, { trigger: true })
   } : {};
-  return createElement(as, { ref, className, ...handlers }, children);
+  return createElement(as, { ref, className, ...handlers }, children2);
 }
 function XeniaMessage({ actions }) {
   const xenia = useXenia();
@@ -2574,6 +2929,6 @@ function reactMessageComponent(Component) {
   };
 }
 
-export { XeniaClient, XeniaContext, XeniaMessage, XeniaProvider, XeniaTrack, createXeniaClient, extractContentSwaps, parseActions, reactMessageComponent, spliceSlots, usePersonalization, usePersonalizationResolve, usePersonalizationResolveSlots, usePersonalizationSlots, useTrack, useWebhook, useXenia, useXeniaResponse };
+export { XeniaClient, XeniaContentProvider, XeniaContext, XeniaMessage, XeniaProvider, XeniaTrack, createXeniaClient, extractContentSwaps, parseActions, pendingTargets, personalizeContent, personalizePage, reactMessageComponent, spliceSlots, usePersonalization, usePersonalizationResolve, usePersonalizationResolveSlots, usePersonalizationSlots, usePersonalizedContent, usePersonalizedPage, useTrack, useWebhook, useXenia, useXeniaEntry, useXeniaResponse };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map