@contentful/experiences-sdk-core 0.6.0 → 0.7.0

package/CHANGELOG.md

@@ -1,3 +1,94 @@
+## 0.7.0 (2026-08-07)
+
+### 🩹 Fixes
+
+- ⚠️  bump @contentful/experience-delivery to 1.0.0-dev.6 + migrate to renamed API [AIS-339] ([#120](https://github.com/contentful/experiences/pull/120))
+
+### ⚠️  Breaking Changes
+
+- bump @contentful/experience-delivery to 1.0.0-dev.6 + migrate to renamed API [AIS-339]  ([#120](https://github.com/contentful/experiences/pull/120))
+  the public API uses the component / experienceTemplate vocabulary.
+  - `registration.componentTypeId` -> `registration.componentId`
+  - `plan.template` -> `plan.experienceTemplate`
+  - `PortableTemplate` -> `PortableExperienceTemplate` (`templateId` ->
+    `experienceTemplateId`)
+  - `Config.templates` -> `Config.experienceTemplates`; `Templates` ->
+    `ExperienceTemplates`
+  - `defineTemplate` -> `defineExperienceTemplate`; `TemplateConfig` ->
+    `ExperienceTemplateConfig`; `TemplateRegistration` ->
+    `ExperienceTemplateRegistration`; `normalizeTemplateRegistration` ->
+    `normalizeExperienceTemplateRegistration`
+  - `useContentfulTemplate()` / `getContentfulTemplate()` ->
+    `useContentfulExperienceTemplate()` / `getContentfulExperienceTemplate()`;
+    `ContentfulTemplate` -> `ContentfulExperienceTemplate`
+  - `MissingComponentProps.componentTypeId` -> `componentId`
+  - Core payload types: `ComponentTypeNode`/`ComponentTypeRef` ->
+    `ComponentNode`/`ComponentRef`; `TemplateNode`/`TemplateRef` ->
+    `ExperienceTemplateNode`/`ExperienceTemplateRef`
+  `packages/core` stays zero-dep, so its payload types are hand-mirrored from the
+  delivery package rather than imported; each carries a doc comment naming its
+  upstream counterpart, and `client:typecheck` catches drift when the delivery SDK
+  regenerates. Documented in AGENTS.md.
+  `examples/scripts/` is intentionally unchanged: it targets the management SDK
+  (`contentful-management`), which has its own entity-type surface, and adopting it
+  would require changing that dependency. The seed script therefore still
+  provisions the shapes that SDK produces.
+  Verified: build, typecheck, and 157 tests pass across all five packages.
+  Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
+  * docs: describe current state only in comments and docs
+  Drop ticket ids, tracker links, and before/after narrative from doc comments and
+  prose so they explain what the code does now rather than how it got here.
+  - `alpha-feature.ts`: state what the header selects and why it is required,
+    without the two-shapes-in-transition framing or the removal timeline.
+  - `core/src/types.ts`: keep each type's upstream counterpart in
+    `@contentful/experience-delivery` (load-bearing for maintenance) but drop the
+    "formerly known as" and old-link-type asides.
+  - README: replace the rename migration table with a description of the
+    alpha-feature header and when a caller needs to send it.
+  - AGENTS.md: reframe the rationale entries that opened on prior designs to state
+    the current design and its reason.
+  - Drop stale option-shape asides ("was nested under ...") and a test name that
+    described superseded behaviour.
+  Generated CHANGELOG.md files are untouched — they are release history.
+  Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
+  * feat!: migrate bootstrap fixture script to component/experienceTemplate entities
+  contentful-management@12.14.0 exposes the renamed ExO entities (Component,
+  ExperienceTemplate) alongside the deprecated ComponentType/Template ones. Adopt
+  the renamed shapes throughout examples/scripts so a freshly bootstrapped demo
+  Experience uses the same entity vocabulary the delivery-consuming packages now
+  read.
+  - Bump contentful-management to ^12.14.0 (existing dependency, version only —
+    no new packages).
+  - fixture/component-types.ts -> fixture/components.ts: ComponentTypeFixture ->
+    ComponentFixture.
+  - fixture/templates.ts -> fixture/experience-templates.ts:
+    TemplateFixture -> ExperienceTemplateFixture, TemplateTreeNode ->
+    ExperienceTemplateTreeNode.
+  - fixture/types.ts, fixture/experience.ts: ExperienceFixture.templateId ->
+    experienceTemplateId; node nodeType 'InlineFragment' ->
+    'InlineExperienceFragment' with componentTypeId -> componentId, matching
+    contentful-management's InlineExperienceFragmentNode.
+  - fixture/data-assemblies.ts: dataAssemblyComponentTypeLinks ->
+    dataAssemblyComponentLinks (componentTypeId -> componentId).
+  - bootstrap-example.ts: cma.componentType -> cma.component,
+    cma.template -> cma.experienceTemplate; sys.type 'ComponentType' ->
+    'Component', 'Template' -> 'ExperienceTemplate'; resource-link types
+    Contentful:ComponentType -> Contentful:Component and Contentful:Template ->
+    Contentful:ExperienceTemplate; URN segments components/ and
+    experienceTemplates/; seedComponentType -> seedComponent, seedTemplate ->
+    seedExperienceTemplate, linkDataAssembliesToComponentTypes ->
+    linkDataAssembliesToComponents.
+  The metadata.annotations.Template composed/coded-implementation marker is
+  unrelated to this rename (identical shape in 12.10.0 and 12.14.0) and is left
+  untouched.
+  Verified: examples/scripts typechecks clean; the main workspace's build,
+  typecheck, and 157 tests are unaffected.
+  Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
+
+## 0.6.1 (2026-08-06)
+
+This was a version bump only for core to align it with other projects, there were no code changes.
+
 ## 0.6.0 (2026-08-05)
 
 ### 🚀 Features

package/README.md

@@ -6,7 +6,7 @@ Runtime-neutral primitives shared across all framework adapters.
 
 ## What lives here
 
-- **Types** — `PortableRenderPlan`, `PortableRenderNode`, `PortableTemplate`, `ExperiencePayload`, `ExperienceNode`, the discriminated `DesignPropValue` union (`ManualDesignValue` / `DesignToken` / `ValuesByViewport`), `ViewportDef`, `ExperienceContext`, `ResolveContext`.
+- **Types** — `PortableRenderPlan`, `PortableRenderNode`, `PortableExperienceTemplate`, `ExperiencePayload`, `ExperienceNode`, the discriminated `DesignPropValue` union (`ManualDesignValue` / `DesignToken` / `ValuesByViewport`), `ViewportDef`, `ExperienceContext`, `ResolveContext`.
 - **`resolveExperience(payload, config, opts)`** — single async entry that walks an XDA payload, classifies content vs. design properties, captures slots, runs any component-declared `resolveData` hooks in parallel, and emits a runtime-neutral `PortableRenderPlan` ready for any framework adapter to render.
 
 ## Why a separate package?

package/dist/index.d.ts

@@ -1,3 +1,3 @@
-export { ComponentTypeNode, ComponentTypeRef, DesignPropValue, DesignToken, ExperienceContext, ExperienceNode, ExperiencePayload, ExperienceSys, ManualDesignValue, PortableRegistration, PortableRenderNode, PortableRenderPlan, PortableTemplate, ResolveContext, ResolveToken, TemplateNode, TemplateRef, ValuesByViewport, ViewportDef } from './types.js';
+export { ComponentNode, ComponentRef, DesignPropValue, DesignToken, ExperienceContext, ExperienceNode, ExperiencePayload, ExperienceSys, ExperienceTemplateNode, ExperienceTemplateRef, ManualDesignValue, PortableExperienceTemplate, PortableRegistration, PortableRenderNode, PortableRenderPlan, ResolveContext, ResolveToken, ValuesByViewport, ViewportDef } from './types.js';
 export { ResolveExperienceOptions, ResolverConfig, resolveExperience } from './resolve-experience.js';
 export { DebugLogger, createDebugLogger } from './debug-logger.js';

package/dist/resolve-experience.d.ts

@@ -13,13 +13,12 @@ import { ExperiencePayload, PortableRenderPlan } from './types.js';
  */
 interface ResolverConfig {
     components: Record<string, unknown>;
-    templates?: Record<string, unknown>;
+    experienceTemplates?: Record<string, unknown>;
 }
 interface ResolveExperienceOptions {
     /**
      * Arbitrary per-render metadata exposed to every resolver as
-     * `ctx.experience.metadata`. Flattened to a top-level option (was nested
-     * under `experience`). Defaults to `{}`.
+     * `ctx.experience.metadata`. Defaults to `{}`.
      */
     metadata?: Record<string, unknown>;
     /**

package/dist/resolve-experience.js

@@ -9,29 +9,29 @@ const DEFAULT_EXPERIENCE = {
   metadata: {},
   viewports: []
 };
-function isComponentTypeNode(node) {
-  return "componentType" in node;
+function isComponentNode(node) {
+  return "component" in node;
 }
 function extractIdFromUrn(urn) {
   const segments = urn.split("/").filter((s) => s.length > 0);
   return segments[segments.length - 1] ?? urn;
 }
 function buildNode(node, config, nodeRefs) {
-  if (!isComponentTypeNode(node)) {
+  if (!isComponentNode(node)) {
     if (typeof console !== "undefined") {
       console.warn(
-        "[@contentful/experiences-sdk-core] Skipping Template-variant node \u2014 Templates are not supported in v1."
+        "[@contentful/experiences-sdk-core] Skipping Experience-Template-variant node \u2014 Experience Templates are not supported as nodes in v1."
       );
     }
     return null;
   }
-  const componentTypeId = extractIdFromUrn(node.componentType.sys.urn);
+  const componentId = extractIdFromUrn(node.component.sys.urn);
   const slots = {};
   if (node.slots) {
     for (const [slotName, children] of Object.entries(node.slots)) {
       if (!Array.isArray(children)) {
         throw new TypeError(
-          `Slot "${slotName}" on component "${componentTypeId}" must be an array of nodes.`
+          `Slot "${slotName}" on component "${componentId}" must be an array of nodes.`
         );
       }
       const built2 = [];
@@ -44,7 +44,7 @@ function buildNode(node, config, nodeRefs) {
     }
   }
   const built = {
-    registration: { componentTypeId },
+    registration: { componentId },
     props: {
       content: { ...node.contentProperties ?? {} },
       design: { ...node.designProperties ?? {} }
@@ -52,7 +52,7 @@ function buildNode(node, config, nodeRefs) {
     slots
   };
   if (node.id) built.nodeId = node.id;
-  if (getResolver(config.components[componentTypeId])) {
+  if (getResolver(config.components[componentId])) {
     nodeRefs.push(built);
   }
   return built;
@@ -67,11 +67,11 @@ async function resolveExperience(payload, config, options = {}) {
     if (built !== null) nodes.push(built);
   }
   log.log(`built ${nodes.length} top-level node(s); ${nodeRefs.length} declare resolveData`);
-  const templateUrn = payload.sys?.template?.sys.urn;
-  let template;
-  if (typeof templateUrn === "string" && templateUrn.length > 0) {
-    template = {
-      templateId: extractIdFromUrn(templateUrn),
+  const experienceTemplateUrn = payload.sys?.experienceTemplate?.sys.urn;
+  let experienceTemplate;
+  if (typeof experienceTemplateUrn === "string" && experienceTemplateUrn.length > 0) {
+    experienceTemplate = {
+      experienceTemplateId: extractIdFromUrn(experienceTemplateUrn),
       props: { content: {}, design: {} }
     };
   }
@@ -85,7 +85,7 @@ async function resolveExperience(payload, config, options = {}) {
   };
   const tasks = [];
   for (const node of nodeRefs) {
-    const resolver = getResolver(config.components[node.registration.componentTypeId]);
+    const resolver = getResolver(config.components[node.registration.componentId]);
     if (!resolver) continue;
     const ctx = {
       content: node.props.content,
@@ -98,15 +98,17 @@ async function resolveExperience(payload, config, options = {}) {
       })
     );
   }
-  if (template) {
-    const tplResolver = getResolver(config.templates?.[template.templateId]);
+  if (experienceTemplate) {
+    const tplResolver = getResolver(
+      config.experienceTemplates?.[experienceTemplate.experienceTemplateId]
+    );
     if (tplResolver) {
       const ctx = {
-        content: template.props.content,
-        design: template.props.design,
+        content: experienceTemplate.props.content,
+        design: experienceTemplate.props.design,
         experience
       };
-      const tpl = template;
+      const tpl = experienceTemplate;
       tasks.push(
         Promise.resolve(tplResolver(ctx)).then((resolved) => {
           tpl.props.resolved = resolved;
@@ -120,7 +122,7 @@ async function resolveExperience(payload, config, options = {}) {
   return {
     viewports: payload.viewports,
     nodes,
-    ...template ? { template } : {}
+    ...experienceTemplate ? { experienceTemplate } : {}
   };
 }
 export {

package/dist/resolve-experience.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/resolve-experience.ts"],"sourcesContent":["/*\n * Single async entry that turns an XDA Experience payload into a\n * runtime-neutral PortableRenderPlan ready to render.\n *\n * v1 behavior:\n *  - Walk the payload's nodes recursively. Each ComponentType node becomes\n *    a PortableRenderNode with `registration.componentTypeId` extracted\n *    from `componentType.sys.urn` (last slash-segment).\n *  - Split content + design properties onto `node.props.{content,design}`.\n *    Design-prop envelopes (DesignToken / ManualDesignValue / ValuesByViewport)\n *    are preserved on the IR; the design package unwraps them at render time.\n *  - Template-variant nodes are skipped with a console.warn — out of v1 scope.\n *  - For every component whose registration declares `resolveData`, run the\n *    resolver (sync or async) in parallel with peers, and attach the result\n *    to `node.props.resolved`.\n *  - Unknown component-type-id is a render-time concern (handled by the\n *    framework adapter via `renderUnknown`); the IR still emits the node.\n */\n\nimport { createDebugLogger } from './debug-logger';\nimport type {\n  ComponentTypeNode,\n  DesignPropValue,\n  ExperienceContext,\n  ExperienceNode,\n  ExperiencePayload,\n  PortableRenderNode,\n  PortableRenderPlan,\n  PortableTemplate,\n  ResolveContext,\n} from './types';\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  templates?: Record<string, unknown>;\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`. Flattened to a top-level option (was nested\n   * under `experience`). 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\nconst DEFAULT_EXPERIENCE: ExperienceContext = {\n  debug: false,\n  metadata: {},\n  viewports: [],\n};\n\nfunction isComponentTypeNode(node: ExperienceNode): node is ComponentTypeNode {\n  return 'componentType' in node;\n}\n\n/**\n * Extract the flat id (componentType or template) from its `ResourceLink`\n * URN. Real URN shapes:\n *   crn:contentful:::experience:spaces/$self/environments/$self/componentTypes/<id>\n *   crn:contentful:::experience:spaces/$self/environments/$self/templates/<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 * 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 */\nfunction buildNode(\n  node: ExperienceNode,\n  config: ResolverConfig,\n  nodeRefs: PortableRenderNode[]\n): PortableRenderNode | null {\n  if (!isComponentTypeNode(node)) {\n    if (typeof console !== 'undefined') {\n      console.warn(\n        '[@contentful/experiences-sdk-core] Skipping Template-variant node — Templates are not supported in v1.'\n      );\n    }\n    return null;\n  }\n\n  const componentTypeId = extractIdFromUrn(node.componentType.sys.urn);\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        throw new TypeError(\n          `Slot \"${slotName}\" on component \"${componentTypeId}\" must be an array of nodes.`\n        );\n      }\n      const built: PortableRenderNode[] = [];\n      for (const child of children) {\n        const childNode = buildNode(child, config, nodeRefs);\n        if (childNode === null) continue;\n        built.push(childNode);\n      }\n      slots[slotName] = built;\n    }\n  }\n\n  const built: PortableRenderNode = {\n    registration: { componentTypeId },\n    props: {\n      content: { ...(node.contentProperties ?? {}) },\n      design: { ...(node.designProperties ?? {}) } as Record<string, DesignPropValue>,\n    },\n    slots,\n  };\n  if (node.id) built.nodeId = node.id;\n  if (getResolver(config.components[componentTypeId])) {\n    nodeRefs.push(built);\n  }\n  return built;\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  // 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[] = [];\n  for (const node of payload.nodes) {\n    const built = buildNode(node, config, nodeRefs);\n    if (built !== null) nodes.push(built);\n  }\n  log.log(`built ${nodes.length} top-level node(s); ${nodeRefs.length} declare resolveData`);\n\n  // Build the page-level template stub if the payload carries one. XDA\n  // payloads don't yet emit template-level content/design properties, so\n  // the IR carries empty bags.\n  const templateUrn = payload.sys?.template?.sys.urn;\n  let template: PortableTemplate | undefined;\n  if (typeof templateUrn === 'string' && templateUrn.length > 0) {\n    template = {\n      templateId: extractIdFromUrn(templateUrn),\n      props: { content: {}, design: {} },\n    };\n  }\n\n  // Pass 2: run resolveData hooks for components AND the template 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: payload.viewports,\n  };\n\n  const tasks: Array<Promise<void>> = [];\n\n  for (const node of nodeRefs) {\n    const resolver = getResolver(config.components[node.registration.componentTypeId]);\n    if (!resolver) continue;\n    const ctx: ResolveContext = {\n      content: node.props.content,\n      design: node.props.design,\n      experience,\n    };\n    tasks.push(\n      Promise.resolve(resolver(ctx)).then((resolved) => {\n        node.props.resolved = resolved;\n      })\n    );\n  }\n\n  if (template) {\n    const tplResolver = getResolver(config.templates?.[template.templateId]);\n    if (tplResolver) {\n      const ctx: ResolveContext = {\n        content: template.props.content,\n        design: template.props.design,\n        experience,\n      };\n      const tpl = template;\n      tasks.push(\n        Promise.resolve(tplResolver(ctx)).then((resolved) => {\n          tpl.props.resolved = resolved;\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  return {\n    viewports: payload.viewports,\n    nodes,\n    ...(template ? { template } : {}),\n  };\n}\n"],"mappings":"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","names":["built"]}
+{"version":3,"sources":["../src/resolve-experience.ts"],"sourcesContent":["/*\n * Single async entry that turns an XDA Experience payload into a\n * runtime-neutral PortableRenderPlan ready to render.\n *\n * v1 behavior:\n *  - Walk the payload's nodes recursively. Each Component node becomes\n *    a PortableRenderNode with `registration.componentId` extracted\n *    from `component.sys.urn` (last slash-segment).\n *  - Split content + design properties onto `node.props.{content,design}`.\n *    Design-prop envelopes (DesignToken / ManualDesignValue / ValuesByViewport)\n *    are preserved on the IR; the design package unwraps them at render time.\n *  - Experience-Template-variant nodes are skipped with a console.warn — out\n *    of v1 scope.\n *  - For every component whose registration declares `resolveData`, run the\n *    resolver (sync or async) in parallel with peers, and attach the result\n *    to `node.props.resolved`.\n *  - Unknown component id is a render-time concern (handled by the\n *    framework adapter via `renderUnknown`); the IR still emits the node.\n */\n\nimport { createDebugLogger } from './debug-logger';\nimport type {\n  ComponentNode,\n  DesignPropValue,\n  ExperienceContext,\n  ExperienceNode,\n  ExperiencePayload,\n  PortableExperienceTemplate,\n  PortableRenderNode,\n  PortableRenderPlan,\n  ResolveContext,\n} from './types';\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\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\nconst DEFAULT_EXPERIENCE: ExperienceContext = {\n  debug: false,\n  metadata: {},\n  viewports: [],\n};\n\nfunction isComponentNode(node: ExperienceNode): node is ComponentNode {\n  return 'component' in node;\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 * 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 */\nfunction buildNode(\n  node: ExperienceNode,\n  config: ResolverConfig,\n  nodeRefs: PortableRenderNode[]\n): PortableRenderNode | null {\n  if (!isComponentNode(node)) {\n    if (typeof console !== 'undefined') {\n      console.warn(\n        '[@contentful/experiences-sdk-core] Skipping Experience-Template-variant node — Experience Templates are not supported as nodes in v1.'\n      );\n    }\n    return null;\n  }\n\n  const componentId = extractIdFromUrn(node.component.sys.urn);\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        throw new TypeError(\n          `Slot \"${slotName}\" on component \"${componentId}\" must be an array of nodes.`\n        );\n      }\n      const built: PortableRenderNode[] = [];\n      for (const child of children) {\n        const childNode = buildNode(child, config, nodeRefs);\n        if (childNode === null) continue;\n        built.push(childNode);\n      }\n      slots[slotName] = built;\n    }\n  }\n\n  const built: PortableRenderNode = {\n    registration: { componentId },\n    props: {\n      content: { ...(node.contentProperties ?? {}) },\n      design: { ...(node.designProperties ?? {}) } as Record<string, DesignPropValue>,\n    },\n    slots,\n  };\n  if (node.id) built.nodeId = node.id;\n  if (getResolver(config.components[componentId])) {\n    nodeRefs.push(built);\n  }\n  return built;\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  // 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[] = [];\n  for (const node of payload.nodes) {\n    const built = buildNode(node, config, nodeRefs);\n    if (built !== null) nodes.push(built);\n  }\n  log.log(`built ${nodes.length} top-level node(s); ${nodeRefs.length} declare resolveData`);\n\n  // Build the page-level Experience Template stub if the payload carries one.\n  // XDA payloads don't yet emit template-level content/design properties, so\n  // the IR carries empty bags.\n  const experienceTemplateUrn = payload.sys?.experienceTemplate?.sys.urn;\n  let experienceTemplate: PortableExperienceTemplate | undefined;\n  if (typeof experienceTemplateUrn === 'string' && experienceTemplateUrn.length > 0) {\n    experienceTemplate = {\n      experienceTemplateId: extractIdFromUrn(experienceTemplateUrn),\n      props: { content: {}, design: {} },\n    };\n  }\n\n  // Pass 2: run resolveData hooks for components AND the template 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: payload.viewports,\n  };\n\n  const tasks: Array<Promise<void>> = [];\n\n  for (const node of nodeRefs) {\n    const resolver = getResolver(config.components[node.registration.componentId]);\n    if (!resolver) continue;\n    const ctx: ResolveContext = {\n      content: node.props.content,\n      design: node.props.design,\n      experience,\n    };\n    tasks.push(\n      Promise.resolve(resolver(ctx)).then((resolved) => {\n        node.props.resolved = resolved;\n      })\n    );\n  }\n\n  if (experienceTemplate) {\n    const tplResolver = getResolver(\n      config.experienceTemplates?.[experienceTemplate.experienceTemplateId]\n    );\n    if (tplResolver) {\n      const ctx: ResolveContext = {\n        content: experienceTemplate.props.content,\n        design: experienceTemplate.props.design,\n        experience,\n      };\n      const tpl = experienceTemplate;\n      tasks.push(\n        Promise.resolve(tplResolver(ctx)).then((resolved) => {\n          tpl.props.resolved = resolved;\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  return {\n    viewports: payload.viewports,\n    nodes,\n    ...(experienceTemplate ? { experienceTemplate } : {}),\n  };\n}\n"],"mappings":"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","names":["built"]}

package/dist/types.d.ts

@@ -12,10 +12,9 @@
  * `debug` is the single observability switch. When on it: emits verbose logs
  * from `resolveExperience` and `fetchExperience`; renders the visible
  * missing-component box (see the adapters' `MissingComponent`); and turns the
- * default `renderUnknown` fallback into the richer debug component. It replaced
- * the old `isPreview` render flag — a single boolean that threads through both
- * fetch and render so a customer can't enable one half and be confused by the
- * other.
+ * default `renderUnknown` fallback into the richer debug component. One boolean
+ * threads through both fetch and render, so a customer can't enable one half
+ * and be confused by the other.
  */
 interface ExperienceContext {
     debug: boolean;
@@ -64,43 +63,52 @@ interface ValuesByViewport {
     values: Record<string, ManualDesignValue | DesignToken>;
 }
 /**
- * Resource-link reference to a registered Component Type. The `urn` carries
- * the type id; the build-plan extracts the id by taking the segment after
+ * Resource-link reference to a registered Component. The `urn` carries
+ * the component id; the build-plan extracts the id by taking the segment after
  * the last slash.
+ *
+ * Mirrors `ComponentLink` from `@contentful/experience-delivery`.
  */
-interface ComponentTypeRef {
+interface ComponentRef {
     sys: {
         type: 'ResourceLink';
-        linkType: 'Contentful:ComponentType';
+        linkType: 'Contentful:Component';
         urn: string;
     };
 }
 /**
- * Resource-link reference to a Template. Templates are out of v1 scope and
- * are skipped at plan-build time with a diagnostic.
+ * Resource-link reference to an Experience Template. Experience Templates
+ * are out of v1 scope as *nodes* and are skipped at plan-build time with a
+ * diagnostic; the page-level reference on `sys` is honored.
+ *
+ * Mirrors `ExperienceTemplateLink` from `@contentful/experience-delivery`.
  */
-interface TemplateRef {
+interface ExperienceTemplateRef {
     sys: {
         type: 'ResourceLink';
-        linkType: 'Contentful:Template';
+        linkType: 'Contentful:ExperienceTemplate';
         urn: string;
     };
 }
 /**
- * One node from `GetExperienceViewResponse.nodes` (or any `slots[name]`).
- * Discriminated by which of `componentType` / `template` is present.
+ * One node from `HydratedExperienceView.nodes` (or any `slots[name]`).
+ * Discriminated by which of `component` / `experienceTemplate` is present.
+ *
+ * Mirrors `RenamedHydratedTreeNode` from `@contentful/experience-delivery`.
  */
-type ExperienceNode = ComponentTypeNode | TemplateNode;
-interface ComponentTypeNode {
-    componentType: ComponentTypeRef;
+type ExperienceNode = ComponentNode | ExperienceTemplateNode;
+/** Mirrors `RenamedComponentTreeNode` from `@contentful/experience-delivery`. */
+interface ComponentNode {
+    component: ComponentRef;
     id?: string;
     contentProperties?: Record<string, unknown>;
     designProperties?: Record<string, DesignPropValue>;
     slots?: Record<string, ExperienceNode[]>;
     contentBindings?: string;
 }
-interface TemplateNode {
-    template: TemplateRef;
+/** Mirrors `RenamedTemplateTreeNode` from `@contentful/experience-delivery`. */
+interface ExperienceTemplateNode {
+    experienceTemplate: ExperienceTemplateRef;
     id?: string;
     contentProperties?: Record<string, unknown>;
     designProperties?: Record<string, DesignPropValue>;
@@ -111,22 +119,32 @@ interface TemplateNode {
  * Top-level `sys` block on an Experience payload. The bits the SDK actually
  * reads are typed; everything else is left loose because the upstream
  * type carries dozens of editor/audit fields the renderer doesn't care about.
+ *
+ * Mirrors the parts of `RenamedDeliveryExperienceSys` the renderer reads.
  */
 interface ExperienceSys {
     /**
-     * Optional page-level template reference. When present, the renderer wraps
+     * Page-level Experience Template reference. When present, the renderer wraps
      * the experience nodes with the matching template registered in the
      * customer's Config. When absent, nodes render at the top level.
+     *
+     * Optional here while the delivery type declares it required — a required
+     * field satisfies an optional one, and keeping it optional lets
+     * `resolveExperience` accept hand-authored payloads for Experiences that
+     * carry no template.
      */
-    template?: TemplateRef;
+    experienceTemplate?: ExperienceTemplateRef;
     [key: string]: unknown;
 }
 /**
  * Top-level Experience payload as returned by the Experience Delivery API
- * (`GetExperienceViewResponse` from `@contentful/experience-delivery`).
+ * (`HydratedExperienceView` from `@contentful/experience-delivery`).
  *
  * Structurally compatible with the upstream type — no normalization step
- * required when consuming a delivery-client response.
+ * required when consuming a delivery-client response. The delivery API returns
+ * this shape when the request carries the
+ * `x-contentful-enable-alpha-feature: new-exo-entity-types` header, which
+ * `@contentful/experiences-client` sends on every request.
  */
 interface ExperiencePayload {
     viewports: ViewportDef[];
@@ -149,11 +167,11 @@ interface ResolveContext {
 /**
  * Registration metadata for a single instance — the SDK's interpreted
  * pointer to the customer's component implementation. Today carries only
- * the resolved component-type id; capabilities (state requirements,
+ * the resolved component id; capabilities (state requirements,
  * supported events, lifecycle hints, fallback ids) land here when needed.
  */
 interface PortableRegistration {
-    componentTypeId: string;
+    componentId: string;
 }
 /**
  * The IR — one node per component instance. The seam that lets non-React
@@ -184,17 +202,18 @@ interface PortableRenderNode {
     slots: Record<string, PortableRenderNode[]>;
 }
 /**
- * Interpreted page-level template — the optional wrapper around the
- * experience tree. `templateId` is extracted from
- * `payload.sys.template.sys.urn` (last slash-segment).
+ * Interpreted page-level Experience Template — the optional wrapper around the
+ * experience tree. `experienceTemplateId` is extracted from
+ * `payload.sys.experienceTemplate.sys.urn` (last slash-segment).
  *
- * Templates carry the same prop-resolution shape as components: content +
- * design envelopes plus an optional `resolved` bag from a `resolveData` hook.
- * v1 payloads from XDA don't carry template-level content/design properties
- * yet, but the IR makes room for them so the API doesn't need to break later.
+ * Experience Templates carry the same prop-resolution shape as components:
+ * content + design envelopes plus an optional `resolved` bag from a
+ * `resolveData` hook. v1 payloads from XDA don't carry template-level
+ * content/design properties yet, but the IR makes room for them so the API
+ * doesn't need to break later.
  */
-interface PortableTemplate {
-    templateId: string;
+interface PortableExperienceTemplate {
+    experienceTemplateId: string;
     props: {
         content: Record<string, unknown>;
         design: Record<string, DesignPropValue>;
@@ -206,14 +225,14 @@ interface PortableTemplate {
  *
  * Top-level is `nodes: PortableRenderNode[]` (array, not single root) to
  * match the actual XDA payload shape. Renderers iterate top-level nodes
- * and recurse into `node.slots`. When `template` is present, the renderer
- * wraps the nodes with the matching template config; otherwise nodes
- * render at the top level.
+ * and recurse into `node.slots`. When `experienceTemplate` is present, the
+ * renderer wraps the nodes with the matching Experience Template config;
+ * otherwise nodes render at the top level.
  */
 interface PortableRenderPlan {
     viewports: ViewportDef[];
     nodes: PortableRenderNode[];
-    template?: PortableTemplate;
+    experienceTemplate?: PortableExperienceTemplate;
 }
 
-export type { ComponentTypeNode, ComponentTypeRef, DesignPropValue, DesignToken, ExperienceContext, ExperienceNode, ExperiencePayload, ExperienceSys, ManualDesignValue, PortableRegistration, PortableRenderNode, PortableRenderPlan, PortableTemplate, ResolveContext, ResolveToken, TemplateNode, TemplateRef, ValuesByViewport, ViewportDef };
+export type { ComponentNode, ComponentRef, DesignPropValue, DesignToken, ExperienceContext, ExperienceNode, ExperiencePayload, ExperienceSys, ExperienceTemplateNode, ExperienceTemplateRef, ManualDesignValue, PortableExperienceTemplate, PortableRegistration, PortableRenderNode, PortableRenderPlan, ResolveContext, ResolveToken, ValuesByViewport, ViewportDef };

package/package.json

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