@contentful/experiences-sdk-core 0.7.0 → 0.7.1

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## 0.7.1 (2026-08-07)
+
+### 🚀 Features
+
+- server-side design pre-resolution against a fallback viewport [AIS-386] ([#119](https://github.com/contentful/experiences/pull/119))
+
 ## 0.7.0 (2026-08-07)
 
 ### 🩹 Fixes

package/dist/index.d.ts

@@ -1,3 +1,4 @@
 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';
+export { applyTokenResolver, getValueForViewport, getViewportIndex, resolveDesignProperties } from './viewport.js';

package/dist/index.js

@@ -1,8 +1,18 @@
 export * from "./types";
 import { resolveExperience } from "./resolve-experience";
 import { createDebugLogger } from "./debug-logger";
+import {
+  applyTokenResolver,
+  getValueForViewport,
+  getViewportIndex,
+  resolveDesignProperties
+} from "./viewport";
 export {
+  applyTokenResolver,
   createDebugLogger,
+  getValueForViewport,
+  getViewportIndex,
+  resolveDesignProperties,
   resolveExperience
 };
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts"],"sourcesContent":["export * from './types';\nexport { resolveExperience } from './resolve-experience';\nexport type { ResolverConfig, ResolveExperienceOptions } from './resolve-experience';\nexport { createDebugLogger } from './debug-logger';\nexport type { DebugLogger } from './debug-logger';\n"],"mappings":"AAAA,cAAc;AACd,SAAS,yBAAyB;AAElC,SAAS,yBAAyB;","names":[]}
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["export * from './types';\nexport { resolveExperience } from './resolve-experience';\nexport type { ResolverConfig, ResolveExperienceOptions } from './resolve-experience';\nexport { createDebugLogger } from './debug-logger';\nexport type { DebugLogger } from './debug-logger';\nexport {\n  applyTokenResolver,\n  getValueForViewport,\n  getViewportIndex,\n  resolveDesignProperties,\n} from './viewport';\n"],"mappings":"AAAA,cAAc;AACd,SAAS,yBAAyB;AAElC,SAAS,yBAAyB;AAElC;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OACK;","names":[]}

package/dist/resolve-experience.d.ts

@@ -1,4 +1,4 @@
-import { ExperiencePayload, PortableRenderPlan } from './types.js';
+import { ResolveToken, ExperiencePayload, PortableRenderPlan } from './types.js';
 
 /**
  * Structural type the resolver walker depends on. Matches the React /
@@ -14,6 +14,17 @@ import { ExperiencePayload, PortableRenderPlan } from './types.js';
 interface ResolverConfig {
     components: Record<string, unknown>;
     experienceTemplates?: Record<string, unknown>;
+    /**
+     * Resolves `DesignToken` design properties to runtime values. Mirrors the
+     * adapter `Config.resolveToken`, so server and client agree without the
+     * caller re-supplying it. Used during server-side pre-resolution.
+     */
+    resolveToken?: ResolveToken;
+    /**
+     * Default fallback viewport for server-side design pre-resolution. When unset
+     * (and not overridden by `initialViewportId`), defaults to viewport[0].
+     */
+    fallbackViewportId?: string;
 }
 interface ResolveExperienceOptions {
     /**
@@ -27,6 +38,13 @@ interface ResolveExperienceOptions {
      * resolver context as `ctx.experience.debug`. Defaults to `false`.
      */
     debug?: boolean;
+    /**
+     * Per-request override for the design pre-resolution fallback viewport. Wins
+     * over `config.fallbackViewportId` — pass a request-time value (e.g. a
+     * User-Agent-detected viewport) so SSR targets the device's expected
+     * viewport. Defaults to viewport[0] when unset or unknown.
+     */
+    initialViewportId?: string;
 }
 /**
  * Turns an Experience payload (XDA response shape) into a PortableRenderPlan

package/dist/resolve-experience.js

@@ -1,4 +1,5 @@
 import { createDebugLogger } from "./debug-logger";
+import { applyTokenResolver, getViewportIndex, resolveDesignProperties } from "./viewport";
 function getResolver(entry) {
   if (typeof entry !== "object" || entry === null) return void 0;
   const candidate = entry.resolveData;
@@ -47,7 +48,9 @@ function buildNode(node, config, nodeRefs) {
     registration: { componentId },
     props: {
       content: { ...node.contentProperties ?? {} },
-      design: { ...node.designProperties ?? {} }
+      // Resolved flat values are written by the pre-resolution pass below.
+      design: {},
+      designRaw: { ...node.designProperties ?? {} }
     },
     slots
   };
@@ -57,6 +60,32 @@ function buildNode(node, config, nodeRefs) {
   }
   return built;
 }
+function preResolveDesignProperties(design, viewports, fallbackViewportIndex, resolveToken) {
+  const cascaded = resolveDesignProperties(design, viewports, fallbackViewportIndex);
+  return applyTokenResolver(cascaded, resolveToken);
+}
+function warnUnresolvedTokens(label, unresolved, log) {
+  if (!unresolved.length || typeof console === "undefined") return;
+  console.warn(
+    `[@contentful/experiences] resolveToken returned undefined for token id(s) on "${label}": ${unresolved.join(", ")}. Resolved design (getDesignValues()) will omit those keys.`
+  );
+  log.log(`unresolved token id(s) on "${label}": ${unresolved.join(", ")}`);
+}
+function preResolveNodeTree(node, viewports, fallbackViewportIndex, resolveToken, log) {
+  const { props, unresolved } = preResolveDesignProperties(
+    node.props.designRaw,
+    viewports,
+    fallbackViewportIndex,
+    resolveToken
+  );
+  node.props.design = props;
+  warnUnresolvedTokens(node.registration.componentId, unresolved, log);
+  for (const children of Object.values(node.slots)) {
+    for (const child of children) {
+      preResolveNodeTree(child, viewports, fallbackViewportIndex, resolveToken, log);
+    }
+  }
+}
 async function resolveExperience(payload, config, options = {}) {
   const log = createDebugLogger(options.debug, "core");
   log.lazy("resolveExperience called with payload", () => payload);
@@ -72,7 +101,7 @@ async function resolveExperience(payload, config, options = {}) {
   if (typeof experienceTemplateUrn === "string" && experienceTemplateUrn.length > 0) {
     experienceTemplate = {
       experienceTemplateId: extractIdFromUrn(experienceTemplateUrn),
-      props: { content: {}, design: {} }
+      props: { content: {}, design: {}, designRaw: {} }
     };
   }
   const experience = {
@@ -89,7 +118,7 @@ async function resolveExperience(payload, config, options = {}) {
     if (!resolver) continue;
     const ctx = {
       content: node.props.content,
-      design: node.props.design,
+      design: node.props.designRaw,
       experience
     };
     tasks.push(
@@ -105,7 +134,7 @@ async function resolveExperience(payload, config, options = {}) {
     if (tplResolver) {
       const ctx = {
         content: experienceTemplate.props.content,
-        design: experienceTemplate.props.design,
+        design: experienceTemplate.props.designRaw,
         experience
       };
       const tpl = experienceTemplate;
@@ -119,10 +148,31 @@ async function resolveExperience(payload, config, options = {}) {
   if (tasks.length > 0) {
     await log.time(`${tasks.length} resolveData hook(s)`, () => Promise.all(tasks));
   }
+  const fallbackViewportId = options.initialViewportId ?? config.fallbackViewportId;
+  const fallbackViewportIndex = getViewportIndex(payload.viewports, fallbackViewportId);
+  for (const node of nodes) {
+    preResolveNodeTree(node, payload.viewports, fallbackViewportIndex, config.resolveToken, log);
+  }
+  if (experienceTemplate) {
+    const { props, unresolved } = preResolveDesignProperties(
+      experienceTemplate.props.designRaw,
+      payload.viewports,
+      fallbackViewportIndex,
+      config.resolveToken
+    );
+    experienceTemplate.props.design = props;
+    warnUnresolvedTokens(
+      `experienceTemplate:${experienceTemplate.experienceTemplateId}`,
+      unresolved,
+      log
+    );
+  }
+  log.log(`pre-resolved design against fallback viewport index ${fallbackViewportIndex}`);
   return {
     viewports: payload.viewports,
     nodes,
-    ...experienceTemplate ? { experienceTemplate } : {}
+    ...experienceTemplate ? { experienceTemplate } : {},
+    fallbackViewportIndex
   };
 }
 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 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"]}
+{"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';\nimport type {\n  ComponentNode,\n  DesignPropValue,\n  ExperienceContext,\n  ExperienceNode,\n  ExperiencePayload,\n  PortableExperienceTemplate,\n  PortableRenderNode,\n  PortableRenderPlan,\n  ResolveContext,\n  ResolveToken,\n  ViewportDef,\n} from './types';\nimport { applyTokenResolver, getViewportIndex, resolveDesignProperties } from './viewport';\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}\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      // 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(config.components[componentId])) {\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 dropped keys are diagnosable.\nfunction warnUnresolvedTokens(label: string, unresolved: string[], log: DebugLogger): void {\n  if (!unresolved.length || typeof console === 'undefined') return;\n  console.warn(\n    `[@contentful/experiences] resolveToken returned undefined for token id(s) on \"${label}\": ${unresolved.join(', ')}. Resolved design (getDesignValues()) will omit those keys.`\n  );\n  log.log(`unresolved token id(s) on \"${label}\": ${unresolved.join(', ')}`);\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): void {\n  const { props, unresolved } = preResolveDesignProperties(\n    node.props.designRaw,\n    viewports,\n    fallbackViewportIndex,\n    resolveToken\n  );\n  node.props.design = props;\n  warnUnresolvedTokens(node.registration.componentId, unresolved, log);\n  for (const children of Object.values(node.slots)) {\n    for (const child of children) {\n      preResolveNodeTree(child, viewports, fallbackViewportIndex, resolveToken, log);\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  // 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: {}, designRaw: {} },\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.designRaw,\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.designRaw,\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  // 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(payload.viewports, fallbackViewportId);\n  for (const node of nodes) {\n    preResolveNodeTree(node, payload.viewports, fallbackViewportIndex, config.resolveToken, log);\n  }\n  if (experienceTemplate) {\n    const { props, unresolved } = preResolveDesignProperties(\n      experienceTemplate.props.designRaw,\n      payload.viewports,\n      fallbackViewportIndex,\n      config.resolveToken\n    );\n    experienceTemplate.props.design = props;\n    warnUnresolvedTokens(\n      `experienceTemplate:${experienceTemplate.experienceTemplateId}`,\n      unresolved,\n      log\n    );\n  }\n  log.log(`pre-resolved design against fallback viewport index ${fallbackViewportIndex}`);\n\n  return {\n    viewports: payload.viewports,\n    nodes,\n    ...(experienceTemplate ? { experienceTemplate } : {}),\n    fallbackViewportIndex,\n  };\n}\n"],"mappings":"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","names":["built"]}

package/dist/types.d.ts

@@ -38,7 +38,7 @@ interface ViewportDef {
 /**
  * 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
+ *  - ValuesByViewport: a viewport-keyed map 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.
@@ -53,7 +53,7 @@ interface DesignToken {
     value: string;
 }
 /**
- * Turns a `DesignToken` envelope into a runtime value. `ref.value` is the
+ * Turns a `DesignToken` 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.
  */
@@ -155,7 +155,7 @@ interface ExperiencePayload {
 }
 /**
  * Per-node context handed to a component's `resolveData` resolver. Carries
- * the raw content + design props from the payload (design envelopes are NOT
+ * the raw content + design props from the payload (design properties are NOT
  * pre-resolved against a viewport — viewport resolution stays a render-time
  * concern so client viewport changes don't re-trigger async resolvers).
  */
@@ -177,14 +177,19 @@ interface PortableRegistration {
  * 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
+ * Design props preserve the discriminated value shape as they arrived. Adapters
  * unwrap to plain scalars at render time, given an active viewport.
- * (DesignToken envelopes pass through unwrapped — customer components decide
+ * (DesignToken values 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
+ * customer-supplied `resolveData` resolver and merged into the final props
  * after content + design but before slot props.
+ *
+ * `props.design` is the server pre-resolution of design against the plan's
+ * fallback viewport; the raw per-viewport form stays on `props.designRaw` so
+ * the client can re-resolve when the active viewport differs. See the fields
+ * below.
  */
 interface PortableRenderNode {
     /**
@@ -196,8 +201,11 @@ interface PortableRenderNode {
     registration: PortableRegistration;
     props: {
         content: Record<string, unknown>;
-        design: Record<string, DesignPropValue>;
+        /** Flat, viewport-cascaded, token-resolved design values (server-side). */
+        design: Record<string, unknown>;
         resolved?: Record<string, unknown>;
+        /** Raw per-viewport design, for client re-resolution on viewport change. */
+        designRaw: Record<string, DesignPropValue>;
     };
     slots: Record<string, PortableRenderNode[]>;
 }
@@ -207,7 +215,7 @@ interface PortableRenderNode {
  * `payload.sys.experienceTemplate.sys.urn` (last slash-segment).
  *
  * Experience Templates carry the same prop-resolution shape as components:
- * content + design envelopes plus an optional `resolved` bag from a
+ * content + design properties plus an optional `resolved` map 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.
@@ -216,8 +224,11 @@ interface PortableExperienceTemplate {
     experienceTemplateId: string;
     props: {
         content: Record<string, unknown>;
-        design: Record<string, DesignPropValue>;
+        /** Same as `PortableRenderNode.props.design`. */
+        design: Record<string, unknown>;
         resolved?: Record<string, unknown>;
+        /** Same as `PortableRenderNode.props.designRaw`. */
+        designRaw: Record<string, DesignPropValue>;
     };
 }
 /**
@@ -233,6 +244,12 @@ interface PortableRenderPlan {
     viewports: ViewportDef[];
     nodes: PortableRenderNode[];
     experienceTemplate?: PortableExperienceTemplate;
+    /**
+     * Viewport index the server pre-resolved design against (viewport[0] by
+     * default). Adapters use `props.design` as-is when their active viewport
+     * matches this, and recompute from `props.designRaw` otherwise.
+     */
+    fallbackViewportIndex: number;
 }
 
 export type { ComponentNode, ComponentRef, DesignPropValue, DesignToken, ExperienceContext, ExperienceNode, ExperiencePayload, ExperienceSys, ExperienceTemplateNode, ExperienceTemplateRef, ManualDesignValue, PortableExperienceTemplate, PortableRegistration, PortableRenderNode, PortableRenderPlan, ResolveContext, ResolveToken, ValuesByViewport, ViewportDef };

package/dist/viewport.d.ts

@@ -0,0 +1,20 @@
+import { DesignToken, ResolveToken, DesignPropValue, ViewportDef } from './types.js';
+
+/** Viewport id → index. Returns 0 (the wildcard viewport) when unknown. */
+declare function getViewportIndex(viewports: ViewportDef[], viewportId?: string): number;
+/** Resolve one design property to its render-time value (cascade + unwrap). */
+declare function getValueForViewport(prop: DesignPropValue | undefined, viewports: ViewportDef[], activeViewportIndex: number): string | number | boolean | DesignToken | undefined;
+/** Resolve every design property on a node into a flat record keyed by name. */
+declare function resolveDesignProperties(designProperties: Record<string, DesignPropValue> | undefined, viewports: ViewportDef[], activeViewportIndex: number): Record<string, string | number | boolean | DesignToken>;
+/**
+ * Resolve `DesignToken` values via `resolveToken`; scalars pass through. Keys
+ * that resolve to `undefined` are dropped and their token ids collected in
+ * `unresolved` for a grouped warning. With no resolver but tokens present,
+ * warns once (those keys would reach components as raw token objects).
+ */
+declare function applyTokenResolver(props: Record<string, string | number | boolean | DesignToken>, resolveToken?: ResolveToken): {
+    props: Record<string, unknown>;
+    unresolved: string[];
+};
+
+export { applyTokenResolver, getValueForViewport, getViewportIndex, resolveDesignProperties };

package/dist/viewport.js

@@ -0,0 +1,71 @@
+function getViewportIndex(viewports, viewportId) {
+  if (!viewportId) return 0;
+  const index = viewports.findIndex((v) => v.id === viewportId);
+  return index === -1 ? 0 : index;
+}
+function unwrapInner(inner) {
+  if (!inner) return void 0;
+  if (inner.type === "ManualDesignValue") return inner.value;
+  return inner;
+}
+function resolveValuesByViewport(valuesByViewport, viewports, activeViewportIndex) {
+  for (let i = activeViewportIndex; i >= 0; i--) {
+    const viewport = viewports[i];
+    if (!viewport) continue;
+    const candidate = valuesByViewport.values[viewport.id];
+    if (candidate !== void 0 && candidate !== null) return candidate;
+  }
+  return void 0;
+}
+function getValueForViewport(prop, viewports, activeViewportIndex) {
+  if (!prop) return void 0;
+  if (prop.type === "ManualDesignValue") return prop.value;
+  if (prop.type === "DesignToken") return prop;
+  return unwrapInner(resolveValuesByViewport(prop, viewports, activeViewportIndex));
+}
+function resolveDesignProperties(designProperties, viewports, activeViewportIndex) {
+  const out = {};
+  if (!designProperties) return out;
+  for (const [key, prop] of Object.entries(designProperties)) {
+    const value = getValueForViewport(prop, viewports, activeViewportIndex);
+    if (value !== void 0) out[key] = value;
+  }
+  return out;
+}
+let warnedMissingResolver = false;
+function applyTokenResolver(props, resolveToken) {
+  if (!resolveToken) {
+    if (!warnedMissingResolver && typeof console !== "undefined") {
+      const tokenKeys = Object.entries(props).filter(([, v]) => typeof v === "object" && v !== null && v.type === "DesignToken").map(([k]) => k);
+      if (tokenKeys.length) {
+        warnedMissingResolver = true;
+        console.warn(
+          `[@contentful/experiences] Design tokens are present but no \`resolveToken\` is configured on the Config; token-valued design props (${tokenKeys.join(", ")}) reach components unresolved. Add \`resolveToken\` to your Config to map token ids to values.`
+        );
+      }
+    }
+    return { props, unresolved: [] };
+  }
+  const out = {};
+  const unresolved = [];
+  for (const [key, value] of Object.entries(props)) {
+    if (typeof value === "object" && value !== null && value.type === "DesignToken") {
+      const resolved = resolveToken(value);
+      if (resolved === void 0) {
+        unresolved.push(value.value);
+        continue;
+      }
+      out[key] = resolved;
+      continue;
+    }
+    out[key] = value;
+  }
+  return { props: out, unresolved };
+}
+export {
+  applyTokenResolver,
+  getValueForViewport,
+  getViewportIndex,
+  resolveDesignProperties
+};
+//# sourceMappingURL=viewport.js.map

package/dist/viewport.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/viewport.ts"],"sourcesContent":["/*\n * Viewport math + design-property resolution. Lives in core (not design) so the\n * resolve pipeline can pre-resolve design props server-side; the design package\n * re-exports these, so its public API is unchanged.\n *\n * Viewport order encodes cascade direction (desktop-first descends by width,\n * mobile-first ascends). The \"active viewport\" is the last-matching media query;\n * `getValueForViewport` walks backwards from it to viewport[0] and returns the\n * first defined value, matching CSS cascade behavior.\n */\n\nimport type {\n  DesignPropValue,\n  DesignToken,\n  ManualDesignValue,\n  ResolveToken,\n  ValuesByViewport,\n  ViewportDef,\n} from './types';\n\n/** Viewport id → index. Returns 0 (the wildcard viewport) when unknown. */\nexport function getViewportIndex(viewports: ViewportDef[], viewportId?: string): number {\n  if (!viewportId) return 0;\n  const index = viewports.findIndex((v) => v.id === viewportId);\n  return index === -1 ? 0 : index;\n}\n\n// ManualDesignValue → its scalar; DesignToken → passed through (resolved later).\nfunction unwrapInner(\n  inner: ManualDesignValue | DesignToken | undefined\n): string | number | boolean | DesignToken | undefined {\n  if (!inner) return undefined;\n  if (inner.type === 'ManualDesignValue') return inner.value;\n  return inner;\n}\n\n// Cascade-lookup: walk back from activeViewportIndex to viewport[0], first defined wins.\nfunction resolveValuesByViewport(\n  valuesByViewport: ValuesByViewport,\n  viewports: ViewportDef[],\n  activeViewportIndex: number\n): ManualDesignValue | DesignToken | undefined {\n  for (let i = activeViewportIndex; i >= 0; i--) {\n    const viewport = viewports[i];\n    if (!viewport) continue;\n    const candidate = valuesByViewport.values[viewport.id];\n    if (candidate !== undefined && candidate !== null) return candidate;\n  }\n  return undefined;\n}\n\n/** Resolve one design property to its render-time value (cascade + unwrap). */\nexport function getValueForViewport(\n  prop: DesignPropValue | undefined,\n  viewports: ViewportDef[],\n  activeViewportIndex: number\n): string | number | boolean | DesignToken | undefined {\n  if (!prop) return undefined;\n  if (prop.type === 'ManualDesignValue') return prop.value;\n  if (prop.type === 'DesignToken') return prop;\n  return unwrapInner(resolveValuesByViewport(prop, viewports, activeViewportIndex));\n}\n\n/** Resolve every design property on a node into a flat record keyed by name. */\nexport function resolveDesignProperties(\n  designProperties: Record<string, DesignPropValue> | undefined,\n  viewports: ViewportDef[],\n  activeViewportIndex: number\n): Record<string, string | number | boolean | DesignToken> {\n  const out: Record<string, string | number | boolean | DesignToken> = {};\n  if (!designProperties) return out;\n  for (const [key, prop] of Object.entries(designProperties)) {\n    const value = getValueForViewport(prop, viewports, activeViewportIndex);\n    if (value !== undefined) out[key] = value;\n  }\n  return out;\n}\n\nlet warnedMissingResolver = false;\n\n/**\n * Resolve `DesignToken` values via `resolveToken`; scalars pass through. Keys\n * that resolve to `undefined` are dropped and their token ids collected in\n * `unresolved` for a grouped warning. With no resolver but tokens present,\n * warns once (those keys would reach components as raw token objects).\n */\nexport function applyTokenResolver(\n  props: Record<string, string | number | boolean | DesignToken>,\n  resolveToken?: ResolveToken\n): { props: Record<string, unknown>; unresolved: string[] } {\n  if (!resolveToken) {\n    if (!warnedMissingResolver && typeof console !== 'undefined') {\n      const tokenKeys = Object.entries(props)\n        .filter(([, v]) => typeof v === 'object' && v !== null && v.type === 'DesignToken')\n        .map(([k]) => k);\n      if (tokenKeys.length) {\n        warnedMissingResolver = true;\n        console.warn(\n          `[@contentful/experiences] Design tokens are present but no \\`resolveToken\\` is configured on the Config; token-valued design props (${tokenKeys.join(', ')}) reach components unresolved. Add \\`resolveToken\\` to your Config to map token ids to values.`\n        );\n      }\n    }\n    return { props, unresolved: [] };\n  }\n  const out: Record<string, unknown> = {};\n  const unresolved: string[] = [];\n  for (const [key, value] of Object.entries(props)) {\n    if (typeof value === 'object' && value !== null && value.type === 'DesignToken') {\n      const resolved = resolveToken(value);\n      if (resolved === undefined) {\n        unresolved.push(value.value);\n        continue;\n      }\n      out[key] = resolved;\n      continue;\n    }\n    out[key] = value;\n  }\n  return { props: out, unresolved };\n}\n"],"mappings":"AAqBO,SAAS,iBAAiB,WAA0B,YAA6B;AACtF,MAAI,CAAC,WAAY,QAAO;AACxB,QAAM,QAAQ,UAAU,UAAU,CAAC,MAAM,EAAE,OAAO,UAAU;AAC5D,SAAO,UAAU,KAAK,IAAI;AAC5B;AAGA,SAAS,YACP,OACqD;AACrD,MAAI,CAAC,MAAO,QAAO;AACnB,MAAI,MAAM,SAAS,oBAAqB,QAAO,MAAM;AACrD,SAAO;AACT;AAGA,SAAS,wBACP,kBACA,WACA,qBAC6C;AAC7C,WAAS,IAAI,qBAAqB,KAAK,GAAG,KAAK;AAC7C,UAAM,WAAW,UAAU,CAAC;AAC5B,QAAI,CAAC,SAAU;AACf,UAAM,YAAY,iBAAiB,OAAO,SAAS,EAAE;AACrD,QAAI,cAAc,UAAa,cAAc,KAAM,QAAO;AAAA,EAC5D;AACA,SAAO;AACT;AAGO,SAAS,oBACd,MACA,WACA,qBACqD;AACrD,MAAI,CAAC,KAAM,QAAO;AAClB,MAAI,KAAK,SAAS,oBAAqB,QAAO,KAAK;AACnD,MAAI,KAAK,SAAS,cAAe,QAAO;AACxC,SAAO,YAAY,wBAAwB,MAAM,WAAW,mBAAmB,CAAC;AAClF;AAGO,SAAS,wBACd,kBACA,WACA,qBACyD;AACzD,QAAM,MAA+D,CAAC;AACtE,MAAI,CAAC,iBAAkB,QAAO;AAC9B,aAAW,CAAC,KAAK,IAAI,KAAK,OAAO,QAAQ,gBAAgB,GAAG;AAC1D,UAAM,QAAQ,oBAAoB,MAAM,WAAW,mBAAmB;AACtE,QAAI,UAAU,OAAW,KAAI,GAAG,IAAI;AAAA,EACtC;AACA,SAAO;AACT;AAEA,IAAI,wBAAwB;AAQrB,SAAS,mBACd,OACA,cAC0D;AAC1D,MAAI,CAAC,cAAc;AACjB,QAAI,CAAC,yBAAyB,OAAO,YAAY,aAAa;AAC5D,YAAM,YAAY,OAAO,QAAQ,KAAK,EACnC,OAAO,CAAC,CAAC,EAAE,CAAC,MAAM,OAAO,MAAM,YAAY,MAAM,QAAQ,EAAE,SAAS,aAAa,EACjF,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC;AACjB,UAAI,UAAU,QAAQ;AACpB,gCAAwB;AACxB,gBAAQ;AAAA,UACN,uIAAuI,UAAU,KAAK,IAAI,CAAC;AAAA,QAC7J;AAAA,MACF;AAAA,IACF;AACA,WAAO,EAAE,OAAO,YAAY,CAAC,EAAE;AAAA,EACjC;AACA,QAAM,MAA+B,CAAC;AACtC,QAAM,aAAuB,CAAC;AAC9B,aAAW,CAAC,KAAK,KAAK,KAAK,OAAO,QAAQ,KAAK,GAAG;AAChD,QAAI,OAAO,UAAU,YAAY,UAAU,QAAQ,MAAM,SAAS,eAAe;AAC/E,YAAM,WAAW,aAAa,KAAK;AACnC,UAAI,aAAa,QAAW;AAC1B,mBAAW,KAAK,MAAM,KAAK;AAC3B;AAAA,MACF;AACA,UAAI,GAAG,IAAI;AACX;AAAA,IACF;AACA,QAAI,GAAG,IAAI;AAAA,EACb;AACA,SAAO,EAAE,OAAO,KAAK,WAAW;AAClC;","names":[]}

package/package.json

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