@contentful/experiences-sdk-core 0.9.2 → 0.10.1

package/CHANGELOG.md

@@ -1,3 +1,19 @@
+## 0.10.1 (2026-10-01)
+
+### 🚀 Features
+
+- persist web personalization profile ID ([#213](https://github.com/contentful/experiences/pull/213))
+
+## 0.10.0 (2026-09-30)
+
+### 🚀 Features
+
+- ⚠️  add XDA personalization extensions ([#211](https://github.com/contentful/experiences/pull/211))
+
+### ⚠️  Breaking Changes
+
+- add XDA personalization extensions  ([#211](https://github.com/contentful/experiences/pull/211))
+
 ## 0.9.2 (2026-09-29)
 
 This was a version bump only for core to align it with other projects, there were no code changes.

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export { ComponentNode, ComponentRef, DesignPropValue, DesignToken, ExperienceContext, ExperienceNode, ExperiencePayload, ExperienceSourceMap, ExperienceSys, ExperienceTemplateNode, ExperienceTemplateRef, ManualDesignValue, PortableRegistration, PortableRenderNode, PortableRenderPlan, RenderContext, ResolveContext, ResolveToken, ValuesByViewport, ViewportDef } from './types.js';
+export { ComponentNode, ComponentRef, DesignPropValue, DesignToken, ExperienceContext, ExperienceExtensions, ExperienceNode, ExperiencePayload, ExperienceSourceMap, ExperienceSys, ExperienceTemplateNode, ExperienceTemplateRef, ManualDesignValue, PortableRegistration, PortableRenderNode, PortableRenderPlan, RenderContext, ResolveContext, ResolveToken, ValuesByViewport, ViewportDef } from './types.js';
 export { ResolveExperienceOptions, ResolverConfig, resolveExperience } from './resolve-experience.js';
 export { DebugLogger, createDebugLogger } from './debug-logger.js';
 export { applyTokenResolver, getValueForViewport, getViewportIndex, resolveDesignProperties } from './viewport.js';

package/dist/resolve-experience.js

@@ -231,6 +231,10 @@ async function resolveExperience(payload, config, options = {}) {
     debug: experience.debug
   };
   if (options.sourceMap !== void 0) plan.sourceMap = options.sourceMap;
+  const profileId = isPlainPayload && payload.extensions?.personalization?.profile?.id;
+  if (profileId) {
+    plan.personalization = { profileId };
+  }
   return plan;
 }
 export {

package/dist/resolve-experience.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/resolve-experience.ts"],"sourcesContent":["/*\n * Turns an XDA Experience payload into a runtime-neutral PortableRenderPlan.\n * Walks nodes recursively, splits content + design props, runs any registered\n * `resolveData` hooks in parallel, and pre-resolves design against a fallback\n * viewport (see `resolveExperience` below).\n */\n\nimport { createDebugLogger, type DebugLogger } from './debug-logger.js';\nimport type {\n  DesignPropValue,\n  ExperienceContext,\n  ExperienceSourceMap,\n  ExperienceNode,\n  ExperiencePayload,\n  PortableRegistration,\n  PortableRenderNode,\n  PortableRenderPlan,\n  ResolveContext,\n  ResolveToken,\n  ViewportDef,\n} from './types.js';\nimport { applyTokenResolver, getViewportIndex, resolveDesignProperties } from './viewport.js';\n\n/**\n * Structural type the resolver walker depends on. Matches the React /\n * Svelte adapter `Config` shape but doesn't require importing them —\n * render-core stays decoupled from any framework.\n *\n * Registry values are typed as `unknown` because each adapter accepts\n * either a bare framework component (function / Svelte class / etc.) OR\n * a config-object shape with `{ component, defaults?, resolveData? }`.\n * The resolver only cares about `resolveData`; it duck-types each entry\n * at runtime and ignores anything without it.\n */\nexport interface ResolverConfig {\n  components: Record<string, unknown>;\n  experienceTemplates?: Record<string, unknown>;\n  /**\n   * Resolves `DesignToken` design properties to runtime values. Mirrors the\n   * adapter `Config.resolveToken`, so server and client agree without the\n   * caller re-supplying it. Used during server-side pre-resolution.\n   */\n  resolveToken?: ResolveToken;\n  /**\n   * Default fallback viewport for server-side design pre-resolution. When unset\n   * (and not overridden by `initialViewportId`), defaults to viewport[0].\n   */\n  fallbackViewportId?: string;\n}\n\nfunction getResolver(\n  entry: unknown\n):\n  | ((ctx: ResolveContext) => Record<string, unknown> | Promise<Record<string, unknown>>)\n  | undefined {\n  if (typeof entry !== 'object' || entry === null) return undefined;\n  const candidate = (entry as { resolveData?: unknown }).resolveData;\n  return typeof candidate === 'function'\n    ? (candidate as (\n        ctx: ResolveContext\n      ) => Record<string, unknown> | Promise<Record<string, unknown>>)\n    : undefined;\n}\n\nexport interface ResolveExperienceOptions {\n  /**\n   * Arbitrary per-render metadata exposed to every resolver as\n   * `ctx.experience.metadata`. Defaults to `{}`.\n   */\n  metadata?: Record<string, unknown>;\n  /**\n   * Observability switch. When on, `resolveExperience` logs the resolution\n   * steps and per-node `resolveData` fan-out timings. Threads through to the\n   * resolver context as `ctx.experience.debug`. Defaults to `false`.\n   */\n  debug?: boolean;\n  /**\n   * Per-request override for the design pre-resolution fallback viewport. Wins\n   * over `config.fallbackViewportId` — pass a request-time value (e.g. a\n   * User-Agent-detected viewport) so SSR targets the device's expected\n   * viewport. Defaults to viewport[0] when unset or unknown.\n   */\n  initialViewportId?: string;\n  /** Carried onto the plan as-is. Omit for no source map. */\n  sourceMap?: ExperienceSourceMap;\n}\n\nconst DEFAULT_EXPERIENCE: ExperienceContext = {\n  debug: false,\n  metadata: {},\n  viewports: [],\n};\n\n/**\n * Registry lookup for a built node. A node's `kind` decides which half of the\n * customer Config owns its implementation — components and Experience\n * Templates are otherwise interchangeable at every other step.\n */\nfunction lookupEntry(config: ResolverConfig, registration: PortableRegistration): unknown {\n  return registration.kind === 'experienceTemplate'\n    ? config.experienceTemplates?.[registration.id]\n    : config.components[registration.id];\n}\n\n/**\n * Extract the flat id (component or experienceTemplate) from its\n * `ResourceLink` URN. Real URN shapes:\n *   crn:contentful:::experience:spaces/$self/environments/$self/components/<id>\n *   crn:contentful:::experience:spaces/$self/environments/$self/experienceTemplates/<id>\n *\n * The id is the final path segment. We split on `/` and take the last\n * non-empty piece so this also tolerates trailing slashes or alternative\n * prefix shapes.\n */\nfunction extractIdFromUrn(urn: string): string {\n  const segments = urn.split('/').filter((s) => s.length > 0);\n  return segments[segments.length - 1] ?? urn;\n}\n\n/**\n * Read the ResourceLink a node points at. Which key is present is the only\n * difference between the two node variants: `experienceTemplate` means the\n * implementation lives in the customer's `experienceTemplates` registry,\n * `component` in `components`. Both carry ids in the same URN shape, the same\n * props shape, and the same slots — so everything downstream is kind-agnostic.\n *\n * `ExperienceNode` is a closed union, so a typed caller cannot produce anything\n * else. Payloads, however, are untrusted JSON at runtime, and the realistic way\n * a third shape arrives is a node kind *newer than this SDK*. Returns `null`\n * for anything unidentifiable rather than letting the ref access throw — see\n * `buildNode`.\n */\nfunction readNodeRef(\n  node: ExperienceNode\n): { kind: PortableRegistration['kind']; urn: string } | null {\n  const isExperienceTemplate = 'experienceTemplate' in node;\n  const ref = isExperienceTemplate\n    ? node.experienceTemplate\n    : 'component' in node\n      ? node.component\n      : undefined;\n  // Cast because the runtime value may violate the declared type: a node can\n  // carry `component: {}`, which satisfies `'component' in node` but has no urn.\n  const urn = (ref as { sys?: { urn?: unknown } } | undefined)?.sys?.urn;\n  if (typeof urn !== 'string' || urn.length === 0) return null;\n  return { kind: isExperienceTemplate ? 'experienceTemplate' : 'component', urn };\n}\n\n/**\n * Guards a top-level payload field that must be an array. A malformed or\n * partial payload (bad JSON, a hand-authored payload with the wrong shape)\n * should degrade to an empty experience rather than throwing and failing the\n * whole render — same \"dropping beats throwing\" rationale as\n * `warnUnrenderableNode` below, just one level up the tree.\n */\nfunction ensureArray<T>(\n  value: unknown,\n  field: string,\n  log: DebugLogger,\n  diagnostics: Error[]\n): T[] {\n  if (Array.isArray(value)) return value as T[];\n  const message =\n    `Experience payload's \"${field}\" is not an array (got ${value === null ? 'null' : typeof value}); ` +\n    `treating it as empty instead of throwing. This usually means a malformed or partial payload — ` +\n    `check what produced it.`;\n  if (typeof console !== 'undefined') {\n    console.warn(`[@contentful/experiences] ${message}`);\n  }\n  log.log(message);\n  diagnostics.push(new Error(message));\n  return [];\n}\n\n/** Total node count in a payload subtree, the node itself included. */\nfunction countPayloadNodes(node: ExperienceNode): number {\n  const slots = (node as { slots?: Record<string, unknown> }).slots;\n  let total = 1;\n  if (slots && typeof slots === 'object') {\n    for (const children of Object.values(slots)) {\n      if (!Array.isArray(children)) continue;\n      for (const child of children) total += countPayloadNodes(child as ExperienceNode);\n    }\n  }\n  return total;\n}\n\n/**\n * The one case where a node is dropped. AIS-413 was the opposite failure —\n * a node kind the SDK recognized and could have rendered, skipped behind a\n * vague warning, taking its whole subtree with it — so the bar here is that\n * nothing vanishes without a diagnostic naming what was lost.\n *\n * Dropping beats throwing: a `resolveExperience` rejection fails the entire\n * experience, so one unrecognized node in a sidebar would take down every page\n * containing it, for a payload the customer does not control and cannot fix.\n */\nfunction warnUnrenderableNode(node: ExperienceNode, log: DebugLogger, diagnostics: Error[]): void {\n  const id = (node as { id?: unknown }).id;\n  const label = typeof id === 'string' ? ` \"${id}\"` : '';\n  const keys = Object.keys(node);\n  const descendants = countPayloadNodes(node) - 1;\n  const message =\n    `Skipping unidentifiable node${label}: expected a \\`component\\` or \\`experienceTemplate\\` ` +\n    `ResourceLink carrying a urn, got keys [${keys.join(', ')}]. Dropping it and ${descendants} ` +\n    `descendant node(s). A payload node kind this SDK does not know is usually a version skew — ` +\n    `upgrading @contentful/experiences-sdk-core may be all that is needed.`;\n  if (typeof console !== 'undefined') {\n    console.warn(`[@contentful/experiences] ${message}`);\n  }\n  log.log(message);\n  diagnostics.push(new Error(message));\n}\n\n/**\n * Walk a sibling list into IR nodes, dropping any node `buildNode` cannot\n * identify. Used for both the top-level list and every slot.\n */\nfunction buildNodes(\n  nodes: ExperienceNode[],\n  config: ResolverConfig,\n  nodeRefs: PortableRenderNode[],\n  log: DebugLogger,\n  diagnostics: Error[]\n): PortableRenderNode[] {\n  const built: PortableRenderNode[] = [];\n  for (const node of nodes) {\n    const one = buildNode(node, config, nodeRefs, log, diagnostics);\n    if (one !== null) built.push(one);\n  }\n  return built;\n}\n\n/**\n * Recursively turn a payload node into an IR node. The collected `nodeRefs`\n * array is for the resolver pass — every built node with a registered\n * resolver gets a reference appended so we can run them in parallel without\n * walking the tree twice.\n *\n * Returns `null` only for a node whose ResourceLink cannot be read, which\n * `warnUnrenderableNode` has already reported. Callers go through `buildNodes`.\n */\nfunction buildNode(\n  node: ExperienceNode,\n  config: ResolverConfig,\n  nodeRefs: PortableRenderNode[],\n  log: DebugLogger,\n  diagnostics: Error[]\n): PortableRenderNode | null {\n  const ref = readNodeRef(node);\n  if (ref === null) {\n    warnUnrenderableNode(node, log, diagnostics);\n    return null;\n  }\n  const registration: PortableRegistration = {\n    kind: ref.kind,\n    id: extractIdFromUrn(ref.urn),\n  };\n  const nodeId = typeof node.id === 'string' ? node.id : undefined;\n\n  const slots: Record<string, PortableRenderNode[]> = {};\n  if (node.slots) {\n    for (const [slotName, children] of Object.entries(node.slots)) {\n      if (!Array.isArray(children)) {\n        const message =\n          `Slot \"${slotName}\" on ${registration.kind} \"${registration.id}\"` +\n          `${nodeId ? ` (node \"${nodeId}\")` : ''} is not an array of nodes (got ` +\n          `${children === null ? 'null' : typeof children}); treating it as empty instead of ` +\n          `failing the whole experience. A hand-built payload with the wrong slot shape is the ` +\n          `usual cause.`;\n        if (typeof console !== 'undefined') {\n          console.warn(`[@contentful/experiences] ${message}`);\n        }\n        log.log(message);\n        diagnostics.push(new Error(message));\n        slots[slotName] = [];\n        continue;\n      }\n      slots[slotName] = buildNodes(children, config, nodeRefs, log, diagnostics);\n    }\n  }\n\n  const built: PortableRenderNode = {\n    registration,\n    props: {\n      content: { ...(node.contentProperties ?? {}) },\n      // Resolved flat values are written by the pre-resolution pass below.\n      design: {},\n      designRaw: { ...(node.designProperties ?? {}) } as Record<string, DesignPropValue>,\n    },\n    slots,\n  };\n  if (node.id) built.nodeId = node.id;\n  if (getResolver(lookupEntry(config, registration))) {\n    nodeRefs.push(built);\n  }\n  return built;\n}\n\n// Cascade a node's raw design to the fallback viewport and resolve tokens.\n// Returns the flat resolved map plus any token ids left unresolved (dropped).\nfunction preResolveDesignProperties(\n  design: Record<string, DesignPropValue>,\n  viewports: ViewportDef[],\n  fallbackViewportIndex: number,\n  resolveToken: ResolveToken | undefined\n): { props: Record<string, unknown>; unresolved: string[] } {\n  const cascaded = resolveDesignProperties(design, viewports, fallbackViewportIndex);\n  return applyTokenResolver(cascaded, resolveToken);\n}\n\n// Warn when resolveToken left tokens unresolved, so pass-through keys are diagnosable.\nfunction warnUnresolvedTokens(\n  label: string,\n  unresolved: string[],\n  log: DebugLogger,\n  diagnostics: Error[]\n): void {\n  if (!unresolved.length) return;\n  const message = `resolveToken returned undefined for token id(s) on \"${label}\": ${unresolved.join(', ')}. Resolved design (getDesignValues()) will carry the raw, unresolved DesignToken for those keys.`;\n  if (typeof console !== 'undefined') {\n    console.warn(`[@contentful/experiences] ${message}`);\n  }\n  log.log(`unresolved token id(s) on \"${label}\": ${unresolved.join(', ')}`);\n  for (const tokenId of unresolved) {\n    diagnostics.push(\n      new Error(\n        `Design token \"${tokenId}\" on ${label} has no \\`resolveToken\\` mapping; the raw token reaches the component unresolved.`\n      )\n    );\n  }\n}\n\n// Depth-first pre-resolve for a node and its slot children.\nfunction preResolveNodeTree(\n  node: PortableRenderNode,\n  viewports: ViewportDef[],\n  fallbackViewportIndex: number,\n  resolveToken: ResolveToken | undefined,\n  log: DebugLogger,\n  diagnostics: Error[]\n): void {\n  const { props, unresolved } = preResolveDesignProperties(\n    node.props.designRaw,\n    viewports,\n    fallbackViewportIndex,\n    resolveToken\n  );\n  node.props.design = props;\n  warnUnresolvedTokens(\n    `${node.registration.kind}:${node.registration.id}`,\n    unresolved,\n    log,\n    diagnostics\n  );\n  for (const children of Object.values(node.slots)) {\n    for (const child of children) {\n      preResolveNodeTree(child, viewports, fallbackViewportIndex, resolveToken, log, diagnostics);\n    }\n  }\n}\n\n/**\n * Turns an Experience payload (XDA response shape) into a PortableRenderPlan\n * ready to hand to a renderer. Walks the tree, classifies props, captures\n * slots, and runs any component-declared `resolveData` hooks (sync or async)\n * in parallel.\n *\n * Implementation note: the function is always async — even when no component\n * declares a resolver, the cost is one microtask. Customers get a single\n * uniform call site.\n */\nexport async function resolveExperience(\n  payload: ExperiencePayload,\n  config: ResolverConfig,\n  options: ResolveExperienceOptions = {}\n): Promise<PortableRenderPlan> {\n  const log = createDebugLogger(options.debug, 'core');\n  log.lazy('resolveExperience called with payload', () => payload);\n\n  const diagnostics: Error[] = [];\n\n  // A payload that isn't an object at all (missing fetch result, a raw\n  // `null`/`undefined` handed in by a broken transform step) can't be\n  // guarded field-by-field via `ensureArray` below — that only guards once\n  // we're already inside a `payload.nodes` access. Guard the whole payload\n  // first so we degrade to an empty experience instead of throwing a raw\n  // TypeError, and report exactly one diagnostic rather than double-counting\n  // once we also run `nodes`/`viewports` through `ensureArray`.\n  const isPlainPayload = payload !== null && typeof payload === 'object';\n  if (!isPlainPayload) {\n    const message =\n      `Experience payload is ${payload === null ? 'null' : typeof payload}, not an object; ` +\n      `treating it as an empty experience (no nodes, no viewports) instead of throwing. This ` +\n      `usually means the fetch or transform pipeline handed resolveExperience a missing or ` +\n      `malformed payload — check what produced it.`;\n    if (typeof console !== 'undefined') {\n      console.warn(`[@contentful/experiences] ${message}`);\n    }\n    log.log(message);\n    diagnostics.push(new Error(message));\n  }\n  const payloadNodes = isPlainPayload\n    ? ensureArray<ExperienceNode>(payload.nodes, 'nodes', log, diagnostics)\n    : [];\n  // `viewports` is being removed from the API, so its absence is expected, not\n  // malformed — only warn via `ensureArray` when the field is present but not\n  // an array. Otherwise default to `[]` silently.\n  const viewports =\n    isPlainPayload && payload.viewports !== undefined\n      ? ensureArray<ViewportDef>(payload.viewports, 'viewports', log, diagnostics)\n      : [];\n\n  // Pass 1: walk the payload into the IR. Collect refs to nodes that need\n  // resolveData so pass 2 can run them in parallel without re-walking.\n  const nodeRefs: PortableRenderNode[] = [];\n  const nodes: PortableRenderNode[] = buildNodes(payloadNodes, config, nodeRefs, log, diagnostics);\n  log.log(`built ${nodes.length} top-level node(s); ${nodeRefs.length} declare resolveData`);\n\n  // Pass 2: run every node's resolveData hook in parallel.\n  // `viewports` is always sourced from the payload — the viewport list is fact,\n  // not opinion, so it can't be overridden by the caller.\n  const experience: ExperienceContext = {\n    debug: options.debug ?? DEFAULT_EXPERIENCE.debug,\n    metadata: {\n      ...DEFAULT_EXPERIENCE.metadata,\n      ...(options.metadata ?? {}),\n    },\n    viewports,\n  };\n\n  const tasks: Array<Promise<void>> = [];\n\n  for (const node of nodeRefs) {\n    const resolver = getResolver(lookupEntry(config, node.registration));\n    if (!resolver) continue;\n    const ctx: ResolveContext = {\n      content: node.props.content,\n      design: node.props.designRaw,\n      experience,\n    };\n    tasks.push(\n      // Deferred via `.then(() => resolver(ctx))` rather than\n      // `Promise.resolve(resolver(ctx))`: the latter calls `resolver(ctx)`\n      // eagerly as an argument, so a resolver that throws *synchronously*\n      // escapes immediately instead of becoming a rejection. The `onFailure`\n      // handler below never rethrows, so one broken resolver can't fail the\n      // `Promise.all` for every other node.\n      Promise.resolve()\n        .then(() => resolver(ctx))\n        .then(\n          (resolved) => {\n            node.props.resolved = resolved;\n          },\n          (err: unknown) => {\n            const label = `${node.registration.kind}:${node.registration.id}`;\n            const reason = err instanceof Error ? err.message : String(err);\n            const message =\n              `resolveData for ${label}${node.nodeId ? ` (node \"${node.nodeId}\")` : ''} threw or ` +\n              `rejected: ${reason}. Rendering the node without resolved data instead of failing ` +\n              `the whole experience.`;\n            if (typeof console !== 'undefined') {\n              console.warn(`[@contentful/experiences] ${message}`);\n            }\n            log.log(message);\n            diagnostics.push(new Error(message, { cause: err instanceof Error ? err : undefined }));\n          }\n        )\n    );\n  }\n\n  // Time the fan-out as a whole rather than per-resolver — one aggregate line\n  // keeps the timing signal without a line per node (which gets noisy fast).\n  if (tasks.length > 0) {\n    await log.time(`${tasks.length} resolveData hook(s)`, () => Promise.all(tasks));\n  }\n\n  // Pre-resolve design against the fallback viewport so SSR paints correct\n  // values on first render. Fallback is initialViewportId, else\n  // config.fallbackViewportId, else viewport[0].\n  const fallbackViewportId = options.initialViewportId ?? config.fallbackViewportId;\n  const fallbackViewportIndex = getViewportIndex(viewports, fallbackViewportId);\n  for (const node of nodes) {\n    preResolveNodeTree(\n      node,\n      viewports,\n      fallbackViewportIndex,\n      config.resolveToken,\n      log,\n      diagnostics\n    );\n  }\n  log.log(`pre-resolved design against fallback viewport index ${fallbackViewportIndex}`);\n\n  // Reuse `experience.metadata` rather than re-merging, so resolvers and the\n  // renderer read the same object. `viewports` is the guarded local, not\n  // `payload.viewports` — a malformed payload degrades to an empty list.\n  const plan: PortableRenderPlan = {\n    viewports,\n    nodes,\n    fallbackViewportIndex,\n    diagnostics,\n    metadata: experience.metadata,\n    debug: experience.debug,\n  };\n  if (options.sourceMap !== undefined) plan.sourceMap = options.sourceMap;\n  return plan;\n}\n"],"mappings":"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","names":[]}
+{"version":3,"sources":["../src/resolve-experience.ts"],"sourcesContent":["/*\n * Turns an XDA Experience payload into a runtime-neutral PortableRenderPlan.\n * Walks nodes recursively, splits content + design props, runs any registered\n * `resolveData` hooks in parallel, and pre-resolves design against a fallback\n * viewport (see `resolveExperience` below).\n */\n\nimport { createDebugLogger, type DebugLogger } from './debug-logger.js';\nimport type {\n  DesignPropValue,\n  ExperienceContext,\n  ExperienceSourceMap,\n  ExperienceNode,\n  ExperiencePayload,\n  PortableRegistration,\n  PortableRenderNode,\n  PortableRenderPlan,\n  ResolveContext,\n  ResolveToken,\n  ViewportDef,\n} from './types.js';\nimport { applyTokenResolver, getViewportIndex, resolveDesignProperties } from './viewport.js';\n\n/**\n * Structural type the resolver walker depends on. Matches the React /\n * Svelte adapter `Config` shape but doesn't require importing them —\n * render-core stays decoupled from any framework.\n *\n * Registry values are typed as `unknown` because each adapter accepts\n * either a bare framework component (function / Svelte class / etc.) OR\n * a config-object shape with `{ component, defaults?, resolveData? }`.\n * The resolver only cares about `resolveData`; it duck-types each entry\n * at runtime and ignores anything without it.\n */\nexport interface ResolverConfig {\n  components: Record<string, unknown>;\n  experienceTemplates?: Record<string, unknown>;\n  /**\n   * Resolves `DesignToken` design properties to runtime values. Mirrors the\n   * adapter `Config.resolveToken`, so server and client agree without the\n   * caller re-supplying it. Used during server-side pre-resolution.\n   */\n  resolveToken?: ResolveToken;\n  /**\n   * Default fallback viewport for server-side design pre-resolution. When unset\n   * (and not overridden by `initialViewportId`), defaults to viewport[0].\n   */\n  fallbackViewportId?: string;\n}\n\nfunction getResolver(\n  entry: unknown\n):\n  | ((ctx: ResolveContext) => Record<string, unknown> | Promise<Record<string, unknown>>)\n  | undefined {\n  if (typeof entry !== 'object' || entry === null) return undefined;\n  const candidate = (entry as { resolveData?: unknown }).resolveData;\n  return typeof candidate === 'function'\n    ? (candidate as (\n        ctx: ResolveContext\n      ) => Record<string, unknown> | Promise<Record<string, unknown>>)\n    : undefined;\n}\n\nexport interface ResolveExperienceOptions {\n  /**\n   * Arbitrary per-render metadata exposed to every resolver as\n   * `ctx.experience.metadata`. Defaults to `{}`.\n   */\n  metadata?: Record<string, unknown>;\n  /**\n   * Observability switch. When on, `resolveExperience` logs the resolution\n   * steps and per-node `resolveData` fan-out timings. Threads through to the\n   * resolver context as `ctx.experience.debug`. Defaults to `false`.\n   */\n  debug?: boolean;\n  /**\n   * Per-request override for the design pre-resolution fallback viewport. Wins\n   * over `config.fallbackViewportId` — pass a request-time value (e.g. a\n   * User-Agent-detected viewport) so SSR targets the device's expected\n   * viewport. Defaults to viewport[0] when unset or unknown.\n   */\n  initialViewportId?: string;\n  /** Carried onto the plan as-is. Omit for no source map. */\n  sourceMap?: ExperienceSourceMap;\n}\n\nconst DEFAULT_EXPERIENCE: ExperienceContext = {\n  debug: false,\n  metadata: {},\n  viewports: [],\n};\n\n/**\n * Registry lookup for a built node. A node's `kind` decides which half of the\n * customer Config owns its implementation — components and Experience\n * Templates are otherwise interchangeable at every other step.\n */\nfunction lookupEntry(config: ResolverConfig, registration: PortableRegistration): unknown {\n  return registration.kind === 'experienceTemplate'\n    ? config.experienceTemplates?.[registration.id]\n    : config.components[registration.id];\n}\n\n/**\n * Extract the flat id (component or experienceTemplate) from its\n * `ResourceLink` URN. Real URN shapes:\n *   crn:contentful:::experience:spaces/$self/environments/$self/components/<id>\n *   crn:contentful:::experience:spaces/$self/environments/$self/experienceTemplates/<id>\n *\n * The id is the final path segment. We split on `/` and take the last\n * non-empty piece so this also tolerates trailing slashes or alternative\n * prefix shapes.\n */\nfunction extractIdFromUrn(urn: string): string {\n  const segments = urn.split('/').filter((s) => s.length > 0);\n  return segments[segments.length - 1] ?? urn;\n}\n\n/**\n * Read the ResourceLink a node points at. Which key is present is the only\n * difference between the two node variants: `experienceTemplate` means the\n * implementation lives in the customer's `experienceTemplates` registry,\n * `component` in `components`. Both carry ids in the same URN shape, the same\n * props shape, and the same slots — so everything downstream is kind-agnostic.\n *\n * `ExperienceNode` is a closed union, so a typed caller cannot produce anything\n * else. Payloads, however, are untrusted JSON at runtime, and the realistic way\n * a third shape arrives is a node kind *newer than this SDK*. Returns `null`\n * for anything unidentifiable rather than letting the ref access throw — see\n * `buildNode`.\n */\nfunction readNodeRef(\n  node: ExperienceNode\n): { kind: PortableRegistration['kind']; urn: string } | null {\n  const isExperienceTemplate = 'experienceTemplate' in node;\n  const ref = isExperienceTemplate\n    ? node.experienceTemplate\n    : 'component' in node\n      ? node.component\n      : undefined;\n  // Cast because the runtime value may violate the declared type: a node can\n  // carry `component: {}`, which satisfies `'component' in node` but has no urn.\n  const urn = (ref as { sys?: { urn?: unknown } } | undefined)?.sys?.urn;\n  if (typeof urn !== 'string' || urn.length === 0) return null;\n  return { kind: isExperienceTemplate ? 'experienceTemplate' : 'component', urn };\n}\n\n/**\n * Guards a top-level payload field that must be an array. A malformed or\n * partial payload (bad JSON, a hand-authored payload with the wrong shape)\n * should degrade to an empty experience rather than throwing and failing the\n * whole render — same \"dropping beats throwing\" rationale as\n * `warnUnrenderableNode` below, just one level up the tree.\n */\nfunction ensureArray<T>(\n  value: unknown,\n  field: string,\n  log: DebugLogger,\n  diagnostics: Error[]\n): T[] {\n  if (Array.isArray(value)) return value as T[];\n  const message =\n    `Experience payload's \"${field}\" is not an array (got ${value === null ? 'null' : typeof value}); ` +\n    `treating it as empty instead of throwing. This usually means a malformed or partial payload — ` +\n    `check what produced it.`;\n  if (typeof console !== 'undefined') {\n    console.warn(`[@contentful/experiences] ${message}`);\n  }\n  log.log(message);\n  diagnostics.push(new Error(message));\n  return [];\n}\n\n/** Total node count in a payload subtree, the node itself included. */\nfunction countPayloadNodes(node: ExperienceNode): number {\n  const slots = (node as { slots?: Record<string, unknown> }).slots;\n  let total = 1;\n  if (slots && typeof slots === 'object') {\n    for (const children of Object.values(slots)) {\n      if (!Array.isArray(children)) continue;\n      for (const child of children) total += countPayloadNodes(child as ExperienceNode);\n    }\n  }\n  return total;\n}\n\n/**\n * The one case where a node is dropped. AIS-413 was the opposite failure —\n * a node kind the SDK recognized and could have rendered, skipped behind a\n * vague warning, taking its whole subtree with it — so the bar here is that\n * nothing vanishes without a diagnostic naming what was lost.\n *\n * Dropping beats throwing: a `resolveExperience` rejection fails the entire\n * experience, so one unrecognized node in a sidebar would take down every page\n * containing it, for a payload the customer does not control and cannot fix.\n */\nfunction warnUnrenderableNode(node: ExperienceNode, log: DebugLogger, diagnostics: Error[]): void {\n  const id = (node as { id?: unknown }).id;\n  const label = typeof id === 'string' ? ` \"${id}\"` : '';\n  const keys = Object.keys(node);\n  const descendants = countPayloadNodes(node) - 1;\n  const message =\n    `Skipping unidentifiable node${label}: expected a \\`component\\` or \\`experienceTemplate\\` ` +\n    `ResourceLink carrying a urn, got keys [${keys.join(', ')}]. Dropping it and ${descendants} ` +\n    `descendant node(s). A payload node kind this SDK does not know is usually a version skew — ` +\n    `upgrading @contentful/experiences-sdk-core may be all that is needed.`;\n  if (typeof console !== 'undefined') {\n    console.warn(`[@contentful/experiences] ${message}`);\n  }\n  log.log(message);\n  diagnostics.push(new Error(message));\n}\n\n/**\n * Walk a sibling list into IR nodes, dropping any node `buildNode` cannot\n * identify. Used for both the top-level list and every slot.\n */\nfunction buildNodes(\n  nodes: ExperienceNode[],\n  config: ResolverConfig,\n  nodeRefs: PortableRenderNode[],\n  log: DebugLogger,\n  diagnostics: Error[]\n): PortableRenderNode[] {\n  const built: PortableRenderNode[] = [];\n  for (const node of nodes) {\n    const one = buildNode(node, config, nodeRefs, log, diagnostics);\n    if (one !== null) built.push(one);\n  }\n  return built;\n}\n\n/**\n * Recursively turn a payload node into an IR node. The collected `nodeRefs`\n * array is for the resolver pass — every built node with a registered\n * resolver gets a reference appended so we can run them in parallel without\n * walking the tree twice.\n *\n * Returns `null` only for a node whose ResourceLink cannot be read, which\n * `warnUnrenderableNode` has already reported. Callers go through `buildNodes`.\n */\nfunction buildNode(\n  node: ExperienceNode,\n  config: ResolverConfig,\n  nodeRefs: PortableRenderNode[],\n  log: DebugLogger,\n  diagnostics: Error[]\n): PortableRenderNode | null {\n  const ref = readNodeRef(node);\n  if (ref === null) {\n    warnUnrenderableNode(node, log, diagnostics);\n    return null;\n  }\n  const registration: PortableRegistration = {\n    kind: ref.kind,\n    id: extractIdFromUrn(ref.urn),\n  };\n  const nodeId = typeof node.id === 'string' ? node.id : undefined;\n\n  const slots: Record<string, PortableRenderNode[]> = {};\n  if (node.slots) {\n    for (const [slotName, children] of Object.entries(node.slots)) {\n      if (!Array.isArray(children)) {\n        const message =\n          `Slot \"${slotName}\" on ${registration.kind} \"${registration.id}\"` +\n          `${nodeId ? ` (node \"${nodeId}\")` : ''} is not an array of nodes (got ` +\n          `${children === null ? 'null' : typeof children}); treating it as empty instead of ` +\n          `failing the whole experience. A hand-built payload with the wrong slot shape is the ` +\n          `usual cause.`;\n        if (typeof console !== 'undefined') {\n          console.warn(`[@contentful/experiences] ${message}`);\n        }\n        log.log(message);\n        diagnostics.push(new Error(message));\n        slots[slotName] = [];\n        continue;\n      }\n      slots[slotName] = buildNodes(children, config, nodeRefs, log, diagnostics);\n    }\n  }\n\n  const built: PortableRenderNode = {\n    registration,\n    props: {\n      content: { ...(node.contentProperties ?? {}) },\n      // Resolved flat values are written by the pre-resolution pass below.\n      design: {},\n      designRaw: { ...(node.designProperties ?? {}) } as Record<string, DesignPropValue>,\n    },\n    slots,\n  };\n  if (node.id) built.nodeId = node.id;\n  if (getResolver(lookupEntry(config, registration))) {\n    nodeRefs.push(built);\n  }\n  return built;\n}\n\n// Cascade a node's raw design to the fallback viewport and resolve tokens.\n// Returns the flat resolved map plus any token ids left unresolved (dropped).\nfunction preResolveDesignProperties(\n  design: Record<string, DesignPropValue>,\n  viewports: ViewportDef[],\n  fallbackViewportIndex: number,\n  resolveToken: ResolveToken | undefined\n): { props: Record<string, unknown>; unresolved: string[] } {\n  const cascaded = resolveDesignProperties(design, viewports, fallbackViewportIndex);\n  return applyTokenResolver(cascaded, resolveToken);\n}\n\n// Warn when resolveToken left tokens unresolved, so pass-through keys are diagnosable.\nfunction warnUnresolvedTokens(\n  label: string,\n  unresolved: string[],\n  log: DebugLogger,\n  diagnostics: Error[]\n): void {\n  if (!unresolved.length) return;\n  const message = `resolveToken returned undefined for token id(s) on \"${label}\": ${unresolved.join(', ')}. Resolved design (getDesignValues()) will carry the raw, unresolved DesignToken for those keys.`;\n  if (typeof console !== 'undefined') {\n    console.warn(`[@contentful/experiences] ${message}`);\n  }\n  log.log(`unresolved token id(s) on \"${label}\": ${unresolved.join(', ')}`);\n  for (const tokenId of unresolved) {\n    diagnostics.push(\n      new Error(\n        `Design token \"${tokenId}\" on ${label} has no \\`resolveToken\\` mapping; the raw token reaches the component unresolved.`\n      )\n    );\n  }\n}\n\n// Depth-first pre-resolve for a node and its slot children.\nfunction preResolveNodeTree(\n  node: PortableRenderNode,\n  viewports: ViewportDef[],\n  fallbackViewportIndex: number,\n  resolveToken: ResolveToken | undefined,\n  log: DebugLogger,\n  diagnostics: Error[]\n): void {\n  const { props, unresolved } = preResolveDesignProperties(\n    node.props.designRaw,\n    viewports,\n    fallbackViewportIndex,\n    resolveToken\n  );\n  node.props.design = props;\n  warnUnresolvedTokens(\n    `${node.registration.kind}:${node.registration.id}`,\n    unresolved,\n    log,\n    diagnostics\n  );\n  for (const children of Object.values(node.slots)) {\n    for (const child of children) {\n      preResolveNodeTree(child, viewports, fallbackViewportIndex, resolveToken, log, diagnostics);\n    }\n  }\n}\n\n/**\n * Turns an Experience payload (XDA response shape) into a PortableRenderPlan\n * ready to hand to a renderer. Walks the tree, classifies props, captures\n * slots, and runs any component-declared `resolveData` hooks (sync or async)\n * in parallel.\n *\n * Implementation note: the function is always async — even when no component\n * declares a resolver, the cost is one microtask. Customers get a single\n * uniform call site.\n */\nexport async function resolveExperience(\n  payload: ExperiencePayload,\n  config: ResolverConfig,\n  options: ResolveExperienceOptions = {}\n): Promise<PortableRenderPlan> {\n  const log = createDebugLogger(options.debug, 'core');\n  log.lazy('resolveExperience called with payload', () => payload);\n\n  const diagnostics: Error[] = [];\n\n  // A payload that isn't an object at all (missing fetch result, a raw\n  // `null`/`undefined` handed in by a broken transform step) can't be\n  // guarded field-by-field via `ensureArray` below — that only guards once\n  // we're already inside a `payload.nodes` access. Guard the whole payload\n  // first so we degrade to an empty experience instead of throwing a raw\n  // TypeError, and report exactly one diagnostic rather than double-counting\n  // once we also run `nodes`/`viewports` through `ensureArray`.\n  const isPlainPayload = payload !== null && typeof payload === 'object';\n  if (!isPlainPayload) {\n    const message =\n      `Experience payload is ${payload === null ? 'null' : typeof payload}, not an object; ` +\n      `treating it as an empty experience (no nodes, no viewports) instead of throwing. This ` +\n      `usually means the fetch or transform pipeline handed resolveExperience a missing or ` +\n      `malformed payload — check what produced it.`;\n    if (typeof console !== 'undefined') {\n      console.warn(`[@contentful/experiences] ${message}`);\n    }\n    log.log(message);\n    diagnostics.push(new Error(message));\n  }\n  const payloadNodes = isPlainPayload\n    ? ensureArray<ExperienceNode>(payload.nodes, 'nodes', log, diagnostics)\n    : [];\n  // `viewports` is being removed from the API, so its absence is expected, not\n  // malformed — only warn via `ensureArray` when the field is present but not\n  // an array. Otherwise default to `[]` silently.\n  const viewports =\n    isPlainPayload && payload.viewports !== undefined\n      ? ensureArray<ViewportDef>(payload.viewports, 'viewports', log, diagnostics)\n      : [];\n\n  // Pass 1: walk the payload into the IR. Collect refs to nodes that need\n  // resolveData so pass 2 can run them in parallel without re-walking.\n  const nodeRefs: PortableRenderNode[] = [];\n  const nodes: PortableRenderNode[] = buildNodes(payloadNodes, config, nodeRefs, log, diagnostics);\n  log.log(`built ${nodes.length} top-level node(s); ${nodeRefs.length} declare resolveData`);\n\n  // Pass 2: run every node's resolveData hook in parallel.\n  // `viewports` is always sourced from the payload — the viewport list is fact,\n  // not opinion, so it can't be overridden by the caller.\n  const experience: ExperienceContext = {\n    debug: options.debug ?? DEFAULT_EXPERIENCE.debug,\n    metadata: {\n      ...DEFAULT_EXPERIENCE.metadata,\n      ...(options.metadata ?? {}),\n    },\n    viewports,\n  };\n\n  const tasks: Array<Promise<void>> = [];\n\n  for (const node of nodeRefs) {\n    const resolver = getResolver(lookupEntry(config, node.registration));\n    if (!resolver) continue;\n    const ctx: ResolveContext = {\n      content: node.props.content,\n      design: node.props.designRaw,\n      experience,\n    };\n    tasks.push(\n      // Deferred via `.then(() => resolver(ctx))` rather than\n      // `Promise.resolve(resolver(ctx))`: the latter calls `resolver(ctx)`\n      // eagerly as an argument, so a resolver that throws *synchronously*\n      // escapes immediately instead of becoming a rejection. The `onFailure`\n      // handler below never rethrows, so one broken resolver can't fail the\n      // `Promise.all` for every other node.\n      Promise.resolve()\n        .then(() => resolver(ctx))\n        .then(\n          (resolved) => {\n            node.props.resolved = resolved;\n          },\n          (err: unknown) => {\n            const label = `${node.registration.kind}:${node.registration.id}`;\n            const reason = err instanceof Error ? err.message : String(err);\n            const message =\n              `resolveData for ${label}${node.nodeId ? ` (node \"${node.nodeId}\")` : ''} threw or ` +\n              `rejected: ${reason}. Rendering the node without resolved data instead of failing ` +\n              `the whole experience.`;\n            if (typeof console !== 'undefined') {\n              console.warn(`[@contentful/experiences] ${message}`);\n            }\n            log.log(message);\n            diagnostics.push(new Error(message, { cause: err instanceof Error ? err : undefined }));\n          }\n        )\n    );\n  }\n\n  // Time the fan-out as a whole rather than per-resolver — one aggregate line\n  // keeps the timing signal without a line per node (which gets noisy fast).\n  if (tasks.length > 0) {\n    await log.time(`${tasks.length} resolveData hook(s)`, () => Promise.all(tasks));\n  }\n\n  // Pre-resolve design against the fallback viewport so SSR paints correct\n  // values on first render. Fallback is initialViewportId, else\n  // config.fallbackViewportId, else viewport[0].\n  const fallbackViewportId = options.initialViewportId ?? config.fallbackViewportId;\n  const fallbackViewportIndex = getViewportIndex(viewports, fallbackViewportId);\n  for (const node of nodes) {\n    preResolveNodeTree(\n      node,\n      viewports,\n      fallbackViewportIndex,\n      config.resolveToken,\n      log,\n      diagnostics\n    );\n  }\n  log.log(`pre-resolved design against fallback viewport index ${fallbackViewportIndex}`);\n\n  // Reuse `experience.metadata` rather than re-merging, so resolvers and the\n  // renderer read the same object. `viewports` is the guarded local, not\n  // `payload.viewports` — a malformed payload degrades to an empty list.\n  const plan: PortableRenderPlan = {\n    viewports,\n    nodes,\n    fallbackViewportIndex,\n    diagnostics,\n    metadata: experience.metadata,\n    debug: experience.debug,\n  };\n  if (options.sourceMap !== undefined) plan.sourceMap = options.sourceMap;\n  const profileId = isPlainPayload && payload.extensions?.personalization?.profile?.id;\n  if (profileId) {\n    plan.personalization = { profileId };\n  }\n  return plan;\n}\n"],"mappings":"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","names":[]}

package/dist/types.d.ts

@@ -200,6 +200,21 @@ interface ExperienceSourceMap {
     dataAssemblies: unknown[];
     nodes: Record<string, unknown>;
 }
+/**
+ * XDA response extensions consumed by the SDK. Kept as a structural subset of
+ * `HydratedExperienceViewExtensions` so Core remains dependency-free.
+ */
+interface ExperienceExtensions {
+    personalization?: {
+        /** Optional here so hand-authored and partial payloads remain accepted. */
+        profile?: {
+            id?: string;
+        };
+        experiences?: unknown[];
+        changes?: unknown[];
+    };
+    sourceMap?: ExperienceSourceMap;
+}
 /**
  * Top-level Experience payload as returned by the Experience Delivery API
  * (`HydratedExperienceView` from `@contentful/experience-delivery`).
@@ -218,7 +233,7 @@ interface ExperiencePayload {
     viewports?: ViewportDef[];
     nodes: ExperienceNode[];
     errors?: unknown[];
-    extensions?: unknown;
+    extensions?: ExperienceExtensions;
     sys?: ExperienceSys;
 }
 /**
@@ -323,8 +338,13 @@ interface PortableRenderPlan {
     metadata: Record<string, unknown>;
     /** The `debug` flag the resolve step ran with. The renderer's prop overrides it. */
     debug: boolean;
-    /** Present only when the fetch opted in via `withSourceMap`. */
+    /** Present only when the fetch requested the `sourceMap` extension. */
     sourceMap?: ExperienceSourceMap;
+    /** Present when XDA returned personalization state for this Experience. */
+    personalization?: {
+        /** Profile id to use for subsequent personalized requests. */
+        profileId: string;
+    };
     /**
      * Resolve-time diagnostics collected while building this plan — malformed
      * payload/slot shapes, an unidentifiable node, a failing `resolveData`, an
@@ -343,4 +363,4 @@ interface PortableRenderPlan {
     diagnostics: Error[];
 }
 
-export type { ComponentNode, ComponentRef, DesignPropValue, DesignToken, ExperienceContext, ExperienceNode, ExperiencePayload, ExperienceSourceMap, ExperienceSys, ExperienceTemplateNode, ExperienceTemplateRef, ManualDesignValue, PortableRegistration, PortableRenderNode, PortableRenderPlan, RenderContext, ResolveContext, ResolveToken, ValuesByViewport, ViewportDef };
+export type { ComponentNode, ComponentRef, DesignPropValue, DesignToken, ExperienceContext, ExperienceExtensions, ExperienceNode, ExperiencePayload, ExperienceSourceMap, ExperienceSys, ExperienceTemplateNode, ExperienceTemplateRef, ManualDesignValue, PortableRegistration, PortableRenderNode, PortableRenderPlan, RenderContext, ResolveContext, ResolveToken, ValuesByViewport, ViewportDef };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contentful/experiences-sdk-core",
-  "version": "0.9.2",
+  "version": "0.10.1",
   "description": "Runtime-neutral types + experience resolution for Contentful Experiences",
   "license": "MIT",
   "type": "module",