@contentful/experiences-sdk-core 0.5.2

package/CHANGELOG.md

@@ -0,0 +1,37 @@
+## 0.5.2 (2026-07-20)
+
+### 🩹 Fixes
+
+- rename experiences-core to experiences-sdk-core [AIS-305] ([#76](https://github.com/contentful/experiences/pull/76))
+
+## 0.5.1 (2026-07-17)
+
+### 🚀 Features
+
+- design-token resolution via resolveToken + useDesignValues [AIS-149] ([#53](https://github.com/contentful/experiences/pull/53))
+
+## 0.5.0 (2026-07-17)
+
+This was a version bump only for core to align it with other projects, there were no code changes.
+
+## 0.4.0 (2026-07-08)
+
+### 🚀 Features
+
+- idiomatic adapters — bare components + context hooks ([0365bfb](https://github.com/contentful/experiences/commit/0365bfb))
+
+## 0.3.0 (2026-06-24)
+
+### 🚀 Features
+
+- more-robust examples + simple/advanced README split + contentful prop ([#18](https://github.com/contentful/experiences/pull/18))
+
+## 0.2.0 (2026-06-24)
+
+This was a version bump only for core to align it with other projects, there were no code changes.
+
+## 0.1.0 (2026-06-23)
+
+### 🚀 Features
+
+- initial Experiences SDK monorepo with React adapter [] ([#16](https://github.com/contentful/experiences/pull/16))

package/README.md

@@ -0,0 +1,20 @@
+# @contentful/experiences-sdk-core
+
+> ⚠️ **Internal package.** Customers do not install this directly. The framework adapter (e.g. [`@contentful/experiences-react`](../adapter-react/)) re-exports everything customers need.
+
+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`.
+- **`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?
+
+Future Angular, Svelte, Vue, SwiftUI, and Compose adapters consume the same plan. Sharing core means each adapter has zero plan-building or prop-classification logic to duplicate — the seam is the `PortableRenderPlan` contract.
+
+See [`../../AGENTS.md`](../../AGENTS.md) for the full architecture and design decisions.
+
+## License
+
+MIT. See the repository [`LICENSE`](../../LICENSE) and [`NOTICE`](../../NOTICE) for full attribution.

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { ComponentTypeNode, ComponentTypeRef, DesignPropValue, DesignToken, ExperienceContext, ExperienceNode, ExperiencePayload, ExperienceSys, ManualDesignValue, PortableRegistration, PortableRenderNode, PortableRenderPlan, PortableTemplate, ResolveContext, ResolveToken, TemplateNode, TemplateRef, ValuesByViewport, ViewportDef } from './types.js';
+export { ResolveExperienceOptions, ResolverConfig, resolveExperience } from './resolve-experience.js';

package/dist/index.js

@@ -0,0 +1,6 @@
+export * from "./types";
+import { resolveExperience } from "./resolve-experience";
+export {
+  resolveExperience
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["export * from './types';\nexport { resolveExperience } from './resolve-experience';\nexport type { ResolverConfig, ResolveExperienceOptions } from './resolve-experience';\n"],"mappings":"AAAA,cAAc;AACd,SAAS,yBAAyB;","names":[]}

package/dist/resolve-experience.d.ts

@@ -0,0 +1,37 @@
+import { ExperienceContext, ExperiencePayload, PortableRenderPlan } from './types.js';
+
+/**
+ * Structural type the resolver walker depends on. Matches the React /
+ * Svelte adapter `Config` shape but doesn't require importing them —
+ * render-core stays decoupled from any framework.
+ *
+ * Registry values are typed as `unknown` because each adapter accepts
+ * either a bare framework component (function / Svelte class / etc.) OR
+ * a config-object shape with `{ component, defaults?, resolveData? }`.
+ * The resolver only cares about `resolveData`; it duck-types each entry
+ * at runtime and ignores anything without it.
+ */
+interface ResolverConfig {
+    components: Record<string, unknown>;
+    templates?: Record<string, unknown>;
+}
+interface ResolveExperienceOptions {
+    /**
+     * Per-render runtime context exposed to every resolver as `ctx.experience`.
+     * Defaults to `{ isPreview: false, metadata: {} }`.
+     */
+    experience?: Partial<ExperienceContext>;
+}
+/**
+ * Turns an Experience payload (XDA response shape) into a PortableRenderPlan
+ * ready to hand to a renderer. Walks the tree, classifies props, captures
+ * slots, and runs any component-declared `resolveData` hooks (sync or async)
+ * in parallel.
+ *
+ * Implementation note: the function is always async — even when no component
+ * declares a resolver, the cost is one microtask. Customers get a single
+ * uniform call site.
+ */
+declare function resolveExperience(payload: ExperiencePayload, config: ResolverConfig, options?: ResolveExperienceOptions): Promise<PortableRenderPlan>;
+
+export { type ResolveExperienceOptions, type ResolverConfig, resolveExperience };

package/dist/resolve-experience.js

@@ -0,0 +1,124 @@
+function getResolver(entry) {
+  if (typeof entry !== "object" || entry === null) return void 0;
+  const candidate = entry.resolveData;
+  return typeof candidate === "function" ? candidate : void 0;
+}
+const DEFAULT_EXPERIENCE = {
+  isPreview: false,
+  metadata: {},
+  viewports: []
+};
+function isComponentTypeNode(node) {
+  return "componentType" 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 (typeof console !== "undefined") {
+      console.warn(
+        "[@contentful/experiences-sdk-core] Skipping Template-variant node \u2014 Templates are not supported in v1."
+      );
+    }
+    return null;
+  }
+  const componentTypeId = extractIdFromUrn(node.componentType.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.`
+        );
+      }
+      const built2 = [];
+      for (const child of children) {
+        const childNode = buildNode(child, config, nodeRefs);
+        if (childNode === null) continue;
+        built2.push(childNode);
+      }
+      slots[slotName] = built2;
+    }
+  }
+  const built = {
+    registration: { componentTypeId },
+    props: {
+      content: { ...node.contentProperties ?? {} },
+      design: { ...node.designProperties ?? {} }
+    },
+    slots
+  };
+  if (node.id) built.nodeId = node.id;
+  if (getResolver(config.components[componentTypeId])) {
+    nodeRefs.push(built);
+  }
+  return built;
+}
+async function resolveExperience(payload, config, options = {}) {
+  const nodeRefs = [];
+  const nodes = [];
+  for (const node of payload.nodes) {
+    const built = buildNode(node, config, nodeRefs);
+    if (built !== null) nodes.push(built);
+  }
+  const templateUrn = payload.sys?.template?.sys.urn;
+  let template;
+  if (typeof templateUrn === "string" && templateUrn.length > 0) {
+    template = {
+      templateId: extractIdFromUrn(templateUrn),
+      props: { content: {}, design: {} }
+    };
+  }
+  const experience = {
+    ...DEFAULT_EXPERIENCE,
+    ...options.experience,
+    metadata: {
+      ...DEFAULT_EXPERIENCE.metadata,
+      ...options.experience?.metadata ?? {}
+    },
+    viewports: payload.viewports
+  };
+  const tasks = [];
+  for (const node of nodeRefs) {
+    const resolver = getResolver(config.components[node.registration.componentTypeId]);
+    if (!resolver) continue;
+    const ctx = {
+      content: node.props.content,
+      design: node.props.design,
+      experience
+    };
+    tasks.push(
+      Promise.resolve(resolver(ctx)).then((resolved) => {
+        node.props.resolved = resolved;
+      })
+    );
+  }
+  if (template) {
+    const tplResolver = getResolver(config.templates?.[template.templateId]);
+    if (tplResolver) {
+      const ctx = {
+        content: template.props.content,
+        design: template.props.design,
+        experience
+      };
+      const tpl = template;
+      tasks.push(
+        Promise.resolve(tplResolver(ctx)).then((resolved) => {
+          tpl.props.resolved = resolved;
+        })
+      );
+    }
+  }
+  if (tasks.length > 0) await Promise.all(tasks);
+  return {
+    viewports: payload.viewports,
+    nodes,
+    ...template ? { template } : {}
+  };
+}
+export {
+  resolveExperience
+};
+//# sourceMappingURL=resolve-experience.js.map

package/dist/resolve-experience.js.map

@@ -0,0 +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 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   * Per-render runtime context exposed to every resolver as `ctx.experience`.\n   * Defaults to `{ isPreview: false, metadata: {} }`.\n   */\n  experience?: Partial<ExperienceContext>;\n}\n\nconst DEFAULT_EXPERIENCE: ExperienceContext = {\n  isPreview: 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  // 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\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 — caller-supplied\n  // options.experience.viewports is ignored (the list is fact, not opinion).\n  const experience: ExperienceContext = {\n    ...DEFAULT_EXPERIENCE,\n    ...options.experience,\n    metadata: {\n      ...DEFAULT_EXPERIENCE.metadata,\n      ...(options.experience?.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  if (tasks.length > 0) await Promise.all(tasks);\n\n  return {\n    viewports: payload.viewports,\n    nodes,\n    ...(template ? { template } : {}),\n  };\n}\n"],"mappings":"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","names":["built"]}

package/dist/types.d.ts

@@ -0,0 +1,211 @@
+/**
+ * Per-render runtime context attached to every customer component as the
+ * `experience` prop, and passed to every `resolveData` hook as `ctx.experience`.
+ * The conventional, single injection point — kept small at v1.
+ *
+ * `viewports` (the *list*) is here so customer resolvers can inspect what
+ * viewports an Experience declares (e.g. "is there a mobile viewport?").
+ * The *active* viewport is render-time only and lives on the framework
+ * adapter's RenderContext — exposing it here would mean async resolvers
+ * re-fire on every viewport change, which would be a footgun.
+ */
+interface ExperienceContext {
+    isPreview: boolean;
+    metadata: Record<string, unknown>;
+    viewports: ViewportDef[];
+}
+/**
+ * One viewport definition from a delivered Experience. The `query` is the
+ * Contentful media-query DSL ("*" | "<992px" | ">1200px"), not raw CSS.
+ *
+ * The first viewport in the list is conventionally the wildcard ("*") that
+ * always matches. The viewport order encodes the cascade direction —
+ * desktop-first (descending) or mobile-first (ascending).
+ */
+interface ViewportDef {
+    id: string;
+    query: string;
+    displayName: string;
+    previewSize: string;
+}
+/**
+ * Discriminated design-property value as it arrives from XDA. v1 accepts:
+ *  - ManualDesignValue: an explicit scalar (no viewport involved).
+ *  - ValuesByViewport: a viewport-keyed bag where each entry is itself a
+ *                      ManualDesignValue or DesignToken.
+ *  - DesignToken: a token reference, passed through to customer components
+ *                 as-is for v1. Resolution lands in the future tokens package.
+ */
+type DesignPropValue = ManualDesignValue | DesignToken | ValuesByViewport;
+interface ManualDesignValue {
+    type: 'ManualDesignValue';
+    value: string | number | boolean;
+}
+interface DesignToken {
+    type: 'DesignToken';
+    value: string;
+}
+/**
+ * Turns a `DesignToken` envelope into a runtime value. `ref.value` is the
+ * customer-defined token id; returning `undefined` means "not resolvable" and
+ * the adapter drops the key (with a warning). Sync only — it runs at render time.
+ */
+type ResolveToken = (ref: DesignToken) => unknown;
+interface ValuesByViewport {
+    type: '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
+ * the last slash.
+ */
+interface ComponentTypeRef {
+    sys: {
+        type: 'ResourceLink';
+        linkType: 'Contentful:ComponentType';
+        urn: string;
+    };
+}
+/**
+ * Resource-link reference to a Template. Templates are out of v1 scope and
+ * are skipped at plan-build time with a diagnostic.
+ */
+interface TemplateRef {
+    sys: {
+        type: 'ResourceLink';
+        linkType: 'Contentful:Template';
+        urn: string;
+    };
+}
+/**
+ * One node from `GetExperienceViewResponse.nodes` (or any `slots[name]`).
+ * Discriminated by which of `componentType` / `template` is present.
+ */
+type ExperienceNode = ComponentTypeNode | TemplateNode;
+interface ComponentTypeNode {
+    componentType: ComponentTypeRef;
+    id?: string;
+    contentProperties?: Record<string, unknown>;
+    designProperties?: Record<string, DesignPropValue>;
+    slots?: Record<string, ExperienceNode[]>;
+    contentBindings?: string;
+}
+interface TemplateNode {
+    template: TemplateRef;
+    id?: string;
+    contentProperties?: Record<string, unknown>;
+    designProperties?: Record<string, DesignPropValue>;
+    slots?: Record<string, ExperienceNode[]>;
+    contentBindings?: string;
+}
+/**
+ * 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.
+ */
+interface ExperienceSys {
+    /**
+     * Optional page-level 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.
+     */
+    template?: TemplateRef;
+    [key: string]: unknown;
+}
+/**
+ * Top-level Experience payload as returned by the Experience Delivery API
+ * (`GetExperienceViewResponse` from `@contentful/experience-delivery`).
+ *
+ * Structurally compatible with the upstream type — no normalization step
+ * required when consuming a delivery-client response.
+ */
+interface ExperiencePayload {
+    viewports: ViewportDef[];
+    nodes: ExperienceNode[];
+    errors?: unknown[];
+    extensions?: unknown;
+    sys?: ExperienceSys;
+}
+/**
+ * Per-node context handed to a component's `resolveData` resolver. Carries
+ * the raw content + design props from the payload (design envelopes are NOT
+ * pre-resolved against a viewport — viewport resolution stays a render-time
+ * concern so client viewport changes don't re-trigger async resolvers).
+ */
+interface ResolveContext {
+    content: Record<string, unknown>;
+    design: Record<string, DesignPropValue>;
+    experience: ExperienceContext;
+}
+/**
+ * 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,
+ * supported events, lifecycle hints, fallback ids) land here when needed.
+ */
+interface PortableRegistration {
+    componentTypeId: string;
+}
+/**
+ * The IR — one node per component instance. The seam that lets non-React
+ * adapters (Angular, SwiftUI, Compose) consume the same interpretation.
+ *
+ * Design props preserve the discriminated envelope as they arrived. Adapters
+ * unwrap to plain scalars at render time, given an active viewport.
+ * (DesignToken envelopes pass through unwrapped — customer components decide
+ * how to resolve them in v1.)
+ *
+ * `props.resolved` is populated by `resolveExperience` from any
+ * customer-supplied `resolveData` resolver and merged into the final prop bag
+ * after content + design but before slot props.
+ */
+interface PortableRenderNode {
+    /**
+     * Optional. Passed through from the XDA payload's `id` field when the
+     * editor supplies one. The SDK does NOT auto-generate ids; adapters fall
+     * back to the array index for React keys / debug labels when absent.
+     */
+    nodeId?: string;
+    registration: PortableRegistration;
+    props: {
+        content: Record<string, unknown>;
+        design: Record<string, DesignPropValue>;
+        resolved?: Record<string, unknown>;
+    };
+    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).
+ *
+ * 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;
+    props: {
+        content: Record<string, unknown>;
+        design: Record<string, DesignPropValue>;
+        resolved?: Record<string, unknown>;
+    };
+}
+/**
+ * The interpreted experience tree.
+ *
+ * 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.
+ */
+interface PortableRenderPlan {
+    viewports: ViewportDef[];
+    nodes: PortableRenderNode[];
+    template?: PortableTemplate;
+}
+
+export type { ComponentTypeNode, ComponentTypeRef, DesignPropValue, DesignToken, ExperienceContext, ExperienceNode, ExperiencePayload, ExperienceSys, ManualDesignValue, PortableRegistration, PortableRenderNode, PortableRenderPlan, PortableTemplate, ResolveContext, ResolveToken, TemplateNode, TemplateRef, ValuesByViewport, ViewportDef };

package/dist/types.js

@@ -0,0 +1 @@
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@contentful/experiences-sdk-core",
+  "version": "0.5.2",
+  "description": "Runtime-neutral types + experience resolution for Contentful Experiences",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/contentful/experiences.git",
+    "directory": "packages/core"
+  }
+}