@contentful/experiences-svelte 0.5.1 → 0.5.3

package/CHANGELOG.md

@@ -1,3 +1,23 @@
+## 0.5.3 (2026-08-10)
+
+### 🧱 Updated Dependencies
+
+- Updated client to 0.3.2
+- Updated design to 0.7.2
+- Updated core to 0.7.2
+
+## 0.5.2 (2026-08-07)
+
+### 🚀 Features
+
+- server-side design pre-resolution against a fallback viewport [AIS-386] ([#119](https://github.com/contentful/experiences/pull/119))
+
+### 🧱 Updated Dependencies
+
+- Updated client to 0.3.1
+- Updated design to 0.7.1
+- Updated core to 0.7.1
+
 ## 0.5.1 (2026-08-07)
 
 ### 🚀 Features

package/README.md

@@ -42,7 +42,7 @@ useActiveViewport; // Rune-backed reactive object; you'll rarely need it directl
 ### Styling + runtime context (helpers)
 
 ```ts
-getDesignValues<T>(); // Resolved design values for the current node; read in a $derived to stay reactive
+getDesignValues<T>(); // Optional helper: the same resolved design record that auto-fills props; read in a $derived to stay reactive
 toCss(design, options?); // Turns a design record into a plain style object, keeping only real CSS keys
 getExperience(); // RenderContext: debug, metadata, viewports, activeViewport
 getContentfulComponent(); // Raw payload for the enclosing node (or undefined)
@@ -50,7 +50,7 @@ getContentfulExperienceTemplate(); // Same, for the page-level Experience Templa
 type ToCssOptions;
 ```
 
-Design is **not** injected as props; components read it via `getDesignValues()` from the top of their `<script>` block. Token resolution is configured with `resolveToken` on your `Config` (`type ResolveToken`).
+Resolved design values (viewport-cascaded + token-resolved server-side) are **auto-filled onto your component's props** by key, alongside content. Styling straight from `$props()` is the recommended path; `getDesignValues()` exposes the same record (read it in a `$derived` to stay reactive) for cases props don't cover. Token resolution is configured with `resolveToken` on your `Config` (`type ResolveToken`).
 
 ### Re-exported types and utilities
 
@@ -76,18 +76,21 @@ isCssProperty, toCssKey, CSS_PROPERTIES
 ## Quick reference
 
 ```svelte
-<!-- Button.svelte: content via props, design via the helper -->
+<!-- Button.svelte: content + resolved design both arrive as props -->
 <script lang="ts">
-  import { getDesignValues, toCss } from '@contentful/experiences-svelte';
-
-  let { label = 'Button', url }: ButtonProps = $props();
-  const design = $derived(getDesignValues());
-  const style = $derived(toCss(design));
+  interface ButtonProps {
+    label?: string;
+    url?: string;
+    backgroundColor?: string; // resolved design, auto-filled
+    color?: string;
+  }
+
+  let { label = 'Button', url, backgroundColor, color }: ButtonProps = $props();
 </script>
 {#if url}
-  <a href={url} style={style}>{label}</a>
+  <a href={url} style="background: {backgroundColor}; color: {color};">{label}</a>
 {:else}
-  <button type="button" style={style}>{label}</button>
+  <button type="button" style="background: {backgroundColor}; color: {color};">{label}</button>
 {/if}
 ```
 

package/dist/ClientExperienceRenderer.svelte

@@ -54,6 +54,7 @@
     viewports: experience?.viewports ?? [],
     activeViewport: experience?.viewports[0] ?? FALLBACK_VIEWPORT,
     activeViewportIndex: 0,
+    fallbackViewportIndex: experience?.fallbackViewportIndex ?? 0,
   });
 
   setExperience(liveContext);
@@ -64,6 +65,7 @@
     liveContext.viewports = experience.viewports;
     liveContext.activeViewport = experience.viewports[idx] ?? FALLBACK_VIEWPORT;
     liveContext.activeViewportIndex = idx;
+    liveContext.fallbackViewportIndex = experience.fallbackViewportIndex;
     liveContext.debug = debug;
     liveContext.metadata = { ...DEFAULT_CONTEXT.metadata, ...(metadata ?? {}) };
   });

package/dist/ClientExperienceRenderer.svelte.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ClientExperienceRenderer.svelte.d.ts","sourceRoot":"","sources":["../src/ClientExperienceRenderer.svelte.ts"],"names":[],"mappings":"AAyFA,QAAA,MAAM,wBAAwB,kGAAwC,CAAC;AACvE,KAAK,wBAAwB,GAAG,UAAU,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAC5E,eAAe,wBAAwB,CAAC"}
+{"version":3,"file":"ClientExperienceRenderer.svelte.d.ts","sourceRoot":"","sources":["../src/ClientExperienceRenderer.svelte.ts"],"names":[],"mappings":"AA2FA,QAAA,MAAM,wBAAwB,kGAAwC,CAAC;AACvE,KAAK,wBAAwB,GAAG,UAAU,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAC5E,eAAe,wBAAwB,CAAC"}

package/dist/DebugExperience.test.js

@@ -1,11 +1,11 @@
 import { render } from '@testing-library/svelte';
 import { describe, expect, it } from 'vitest';
 import DebugExperience from './DebugExperience.svelte';
-const emptyPlan = { nodes: [], viewports: [] };
+const emptyPlan = { nodes: [], viewports: [], fallbackViewportIndex: 0 };
 function node(componentId, content = {}) {
     return {
         registration: { componentId },
-        props: { content, design: {} },
+        props: { content, design: {}, designRaw: {} },
         slots: {},
     };
 }
@@ -25,7 +25,11 @@ describe('DebugExperience.svelte', () => {
     it('summarizes the node count, pluralizing correctly', () => {
         const { container: zero } = render(DebugExperience, { props: { experience: emptyPlan } });
         expect(zero.innerHTML).toContain('Experience debug — 0 top-level nodes');
-        const one = { viewports: [], nodes: [node('button')] };
+        const one = {
+            viewports: [],
+            nodes: [node('button')],
+            fallbackViewportIndex: 0,
+        };
         const { container } = render(DebugExperience, { props: { experience: one } });
         expect(container.innerHTML).toContain('Experience debug — 1 top-level node');
     });
@@ -33,7 +37,11 @@ describe('DebugExperience.svelte', () => {
         const plan = {
             viewports: [],
             nodes: [],
-            experienceTemplate: { experienceTemplateId: 'page', props: { content: {}, design: {} } },
+            experienceTemplate: {
+                experienceTemplateId: 'page',
+                props: { content: {}, design: {}, designRaw: {} },
+            },
+            fallbackViewportIndex: 0,
         };
         const { container } = render(DebugExperience, { props: { experience: plan } });
         expect(container.innerHTML).toContain('experience template: page');
@@ -42,6 +50,7 @@ describe('DebugExperience.svelte', () => {
         const plan = {
             viewports: [],
             nodes: [node('button', { label: 'Go' })],
+            fallbackViewportIndex: 0,
         };
         const { container } = render(DebugExperience, { props: { experience: plan } });
         expect(container.innerHTML).toContain('componentId');
@@ -51,7 +60,7 @@ describe('DebugExperience.svelte', () => {
     it('degrades a circular reference to a placeholder instead of throwing', () => {
         const n = node('button');
         n.props.resolved = { self: n.props };
-        const plan = { viewports: [], nodes: [n] };
+        const plan = { viewports: [], nodes: [n], fallbackViewportIndex: 0 };
         expect(() => render(DebugExperience, { props: { experience: plan } })).not.toThrow();
         const { container } = render(DebugExperience, { props: { experience: plan } });
         expect(container.innerHTML).toContain('[Circular]');

package/dist/NodeRenderer.svelte

@@ -7,9 +7,9 @@
   import type { Snippet } from 'svelte';
 
   import type { PortableRenderNode } from '@contentful/experiences-sdk-core';
-  import { applyTokenResolver, resolveDesignProperties } from '@contentful/experiences-design';
 
   import { setContentfulComponent, setResolvedDesign } from './context.js';
+  import { selectResolvedDesign } from './design-utils.js';
   import type { RenderUnknown } from './component-props.js';
   import {
     normalizeComponentRegistration,
@@ -35,21 +35,20 @@
     componentId: node.registration.componentId,
     nodeId: node.nodeId,
     content: node.props.content,
-    design: node.props.design,
+    design: node.props.designRaw,
     resolved: node.props.resolved,
     slots: node.slots,
   };
   setContentfulComponent(contentful);
 
-  // Cascade design + resolve tokens; published on context for getDesignValues(),
-  // never merged into props.
   const tokenResolvedDesign = $derived.by(() => {
-    const resolvedDesign = resolveDesignProperties(
-      node.props.design,
+    const { props, unresolved } = selectResolvedDesign(
+      node.props,
       experience.viewports,
-      experience.activeViewportIndex
+      experience.activeViewportIndex,
+      experience.fallbackViewportIndex,
+      config.resolveToken
     );
-    const { props, unresolved } = applyTokenResolver(resolvedDesign, config.resolveToken);
     if (unresolved.length && typeof console !== 'undefined') {
       console.warn(
         `[@contentful/experiences-svelte] resolveToken returned undefined for token id(s) on "${node.registration.componentId}": ${unresolved.join(', ')}. getDesignValues() will omit those keys.`
@@ -60,10 +59,12 @@
 
   setResolvedDesign(() => tokenResolvedDesign);
 
+  // Merge precedence (last wins): defaults < design < content < resolveData < children.
   const composed = $derived.by(() => {
     if (!componentConfig) return null;
     return {
       ...componentConfig.defaults,
+      ...tokenResolvedDesign,
       ...node.props.content,
       ...node.props.resolved,
       children,

package/dist/NodeRenderer.svelte.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"NodeRenderer.svelte.d.ts","sourceRoot":"","sources":["../src/NodeRenderer.svelte.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAC;AAEtC,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,kCAAkC,CAAC;AAI3E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,EAGH,KAAK,MAAM,EACX,KAAK,aAAa,EACnB,MAAM,YAAY,CAAC;AAGpB,UAAU,iBAAiB;IACzB,IAAI,EAAE,kBAAkB,CAAC;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,aAAa,CAAC;IAC1B,aAAa,EAAE,aAAa,CAAC;IAC7B,QAAQ,EAAE,OAAO,EAAE,CAAC;CACrB;AAoEH,QAAA,MAAM,YAAY,uDAAwC,CAAC;AAC3D,KAAK,YAAY,GAAG,UAAU,CAAC,OAAO,YAAY,CAAC,CAAC;AACpD,eAAe,YAAY,CAAC"}
+{"version":3,"file":"NodeRenderer.svelte.d.ts","sourceRoot":"","sources":["../src/NodeRenderer.svelte.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAC;AAEtC,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,kCAAkC,CAAC;AAI3E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,EAGH,KAAK,MAAM,EACX,KAAK,aAAa,EACnB,MAAM,YAAY,CAAC;AAGpB,UAAU,iBAAiB;IACzB,IAAI,EAAE,kBAAkB,CAAC;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,aAAa,CAAC;IAC1B,aAAa,EAAE,aAAa,CAAC;IAC7B,QAAQ,EAAE,OAAO,EAAE,CAAC;CACrB;AAqEH,QAAA,MAAM,YAAY,uDAAwC,CAAC;AAC3D,KAAK,YAAY,GAAG,UAAU,CAAC,OAAO,YAAY,CAAC,CAAC;AACpD,eAAe,YAAY,CAAC"}

package/dist/ServerExperienceRenderer.svelte

@@ -51,6 +51,7 @@
       viewports,
       activeViewport: experience?.viewports[idx] ?? FALLBACK_VIEWPORT,
       activeViewportIndex: idx,
+      fallbackViewportIndex: experience?.fallbackViewportIndex ?? 0,
     };
   }
 

package/dist/ServerExperienceRenderer.svelte.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ServerExperienceRenderer.svelte.d.ts","sourceRoot":"","sources":["../src/ServerExperienceRenderer.svelte.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,6BAA6B,EAAE,MAAM,sBAAsB,CAAC;AAqE1E,QAAA,MAAM,wBAAwB,mEAAwC,CAAC;AACvE,KAAK,wBAAwB,GAAG,UAAU,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAC5E,eAAe,wBAAwB,CAAC"}
+{"version":3,"file":"ServerExperienceRenderer.svelte.d.ts","sourceRoot":"","sources":["../src/ServerExperienceRenderer.svelte.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,6BAA6B,EAAE,MAAM,sBAAsB,CAAC;AAsE1E,QAAA,MAAM,wBAAwB,mEAAwC,CAAC;AACvE,KAAK,wBAAwB,GAAG,UAAU,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAC5E,eAAe,wBAAwB,CAAC"}

package/dist/WrapWithExperienceTemplate.svelte

@@ -9,9 +9,9 @@
   import type { Snippet } from 'svelte';
 
   import type { PortableExperienceTemplate } from '@contentful/experiences-sdk-core';
-  import { applyTokenResolver, resolveDesignProperties } from '@contentful/experiences-design';
 
   import { setContentfulExperienceTemplate, setResolvedDesign } from './context.js';
+  import { selectResolvedDesign } from './design-utils.js';
   import {
     normalizeExperienceTemplateRegistration,
     type ContentfulExperienceTemplate,
@@ -34,7 +34,7 @@
     setContentfulExperienceTemplate({
       experienceTemplateId: experienceTemplate.experienceTemplateId,
       content: experienceTemplate.props.content,
-      design: experienceTemplate.props.design,
+      design: experienceTemplate.props.designRaw,
       resolved: experienceTemplate.props.resolved,
     } satisfies ContentfulExperienceTemplate);
   }
@@ -44,12 +44,13 @@
 
   const tokenResolvedDesign = $derived.by(() => {
     if (!experienceTemplate) return {};
-    const resolvedDesign = resolveDesignProperties(
-      experienceTemplate.props.design,
+    const { props, unresolved } = selectResolvedDesign(
+      experienceTemplate.props,
       experience.viewports,
-      experience.activeViewportIndex
+      experience.activeViewportIndex,
+      experience.fallbackViewportIndex,
+      config.resolveToken
     );
-    const { props, unresolved } = applyTokenResolver(resolvedDesign, config.resolveToken);
     if (unresolved.length && typeof console !== 'undefined') {
       console.warn(
         `[@contentful/experiences-svelte] resolveToken returned undefined for token id(s) on experience template "${experienceTemplate.experienceTemplateId}": ${unresolved.join(', ')}. getDesignValues() will omit those keys.`
@@ -58,13 +59,15 @@
     return props;
   });
 
-  // A getter (not a snapshot) so getDesignValues() stays reactive; not merged into props.
+  // A getter (not a snapshot) so getDesignValues() stays reactive.
   setResolvedDesign(() => tokenResolvedDesign);
 
+  // Same precedence as component nodes.
   const composed = $derived.by(() => {
     if (!experienceTemplate || !experienceTemplateConfig) return null;
     return {
       ...experienceTemplateConfig.defaults,
+      ...tokenResolvedDesign,
       ...experienceTemplate.props.content,
       ...experienceTemplate.props.resolved,
     };

package/dist/WrapWithExperienceTemplate.svelte.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"WrapWithExperienceTemplate.svelte.d.ts","sourceRoot":"","sources":["../src/WrapWithExperienceTemplate.svelte.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAC;AAEtC,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,kCAAkC,CAAC;AAInF,OAAO,EAGH,KAAK,MAAM,EACX,KAAK,aAAa,EACnB,MAAM,YAAY,CAAC;AAGpB,UAAU,+BAA+B;IACvC,kBAAkB,EAAE,0BAA0B,GAAG,SAAS,CAAC;IAC3D,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,aAAa,CAAC;IAC1B,QAAQ,EAAE,OAAO,CAAC;CACnB;AA0EH,QAAA,MAAM,0BAA0B,qEAAwC,CAAC;AACzE,KAAK,0BAA0B,GAAG,UAAU,CAAC,OAAO,0BAA0B,CAAC,CAAC;AAChF,eAAe,0BAA0B,CAAC"}
+{"version":3,"file":"WrapWithExperienceTemplate.svelte.d.ts","sourceRoot":"","sources":["../src/WrapWithExperienceTemplate.svelte.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAC;AAEtC,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,kCAAkC,CAAC;AAInF,OAAO,EAGH,KAAK,MAAM,EACX,KAAK,aAAa,EACnB,MAAM,YAAY,CAAC;AAGpB,UAAU,+BAA+B;IACvC,kBAAkB,EAAE,0BAA0B,GAAG,SAAS,CAAC;IAC3D,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,aAAa,CAAC;IAC1B,QAAQ,EAAE,OAAO,CAAC;CACnB;AA6EH,QAAA,MAAM,0BAA0B,qEAAwC,CAAC;AACzE,KAAK,0BAA0B,GAAG,UAAU,CAAC,OAAO,0BAA0B,CAAC,CAAC;AAChF,eAAe,0BAA0B,CAAC"}

package/dist/design-utils.d.ts

@@ -1,3 +1,11 @@
+import type { DesignPropValue, ResolveToken, ViewportDef } from '@contentful/experiences-sdk-core';
+export declare function selectResolvedDesign(props: {
+    design: Record<string, unknown>;
+    designRaw: Record<string, DesignPropValue>;
+}, viewports: ViewportDef[], activeViewportIndex: number, fallbackViewportIndex: number, resolveToken: ResolveToken | undefined): {
+    props: Record<string, unknown>;
+    unresolved: string[];
+};
 export interface ToCssOptions {
     /** Keys to skip, matched against the original record key. */
     exclude?: string[];

package/dist/design-utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"design-utils.d.ts","sourceRoot":"","sources":["../src/design-utils.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,YAAY;IAC3B,6DAA6D;IAC7D,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,yEAAyE;IACzE,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;CACpB;AAED;;;;;;;GAOG;AACH,wBAAgB,KAAK,CACnB,MAAM,EAAE,MAAM,EACd,EAAE,OAAO,EAAE,OAAO,EAAE,GAAE,YAAiB,GACtC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,CAYjC"}
+{"version":3,"file":"design-utils.d.ts","sourceRoot":"","sources":["../src/design-utils.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,kCAAkC,CAAC;AAUnG,wBAAgB,oBAAoB,CAClC,KAAK,EAAE;IAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAA;CAAE,EACtF,SAAS,EAAE,WAAW,EAAE,EACxB,mBAAmB,EAAE,MAAM,EAC3B,qBAAqB,EAAE,MAAM,EAC7B,YAAY,EAAE,YAAY,GAAG,SAAS,GACrC;IAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAAC,UAAU,EAAE,MAAM,EAAE,CAAA;CAAE,CAM1D;AAED,MAAM,WAAW,YAAY;IAC3B,6DAA6D;IAC7D,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,yEAAyE;IACzE,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;CACpB;AAED;;;;;;;GAOG;AACH,wBAAgB,KAAK,CACnB,MAAM,EAAE,MAAM,EACd,EAAE,OAAO,EAAE,OAAO,EAAE,GAAE,YAAiB,GACtC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,CAYjC"}

package/dist/design-utils.js

@@ -1,4 +1,13 @@
-import { isCssProperty, toCssKey } from '@contentful/experiences-design';
+import { applyTokenResolver, isCssProperty, resolveDesignProperties, toCssKey, } from '@contentful/experiences-design';
+// Use the server-resolved `props.design` when the active viewport matches the
+// fallback; otherwise recompute the cascade from raw `props.designRaw`.
+export function selectResolvedDesign(props, viewports, activeViewportIndex, fallbackViewportIndex, resolveToken) {
+    if (activeViewportIndex === fallbackViewportIndex) {
+        return { props: props.design, unresolved: [] };
+    }
+    const resolvedDesign = resolveDesignProperties(props.designRaw, viewports, activeViewportIndex);
+    return applyTokenResolver(resolvedDesign, resolveToken);
+}
 /**
  * Convert a design record into a plain style object, keeping only keys that
  * normalize to a known CSS property. Non-CSS keys (`variant`, `as`, …) and

package/dist/server-renderer.test.js

@@ -154,17 +154,18 @@ describe('ServerExperienceRenderer', () => {
         };
         const planWithMissing = {
             viewports: VIEWPORTS,
+            fallbackViewportIndex: 0,
             nodes: [
                 {
                     nodeId: 'root',
                     registration: { componentId: 'contentful-container' },
-                    props: { content: {}, design: {} },
+                    props: { content: {}, design: {}, designRaw: {} },
                     slots: {
                         children: [
                             {
                                 nodeId: 'ghost',
                                 registration: { componentId: 'NotRegistered' },
-                                props: { content: {}, design: {} },
+                                props: { content: {}, design: {}, designRaw: {} },
                                 slots: {},
                             },
                         ],
@@ -242,6 +243,7 @@ describe('ServerExperienceRenderer', () => {
         };
         const planWithResolved = {
             viewports: VIEWPORTS,
+            fallbackViewportIndex: 0,
             nodes: [
                 {
                     nodeId: 'r',
@@ -249,6 +251,7 @@ describe('ServerExperienceRenderer', () => {
                     props: {
                         content: { value: 'fromContent' },
                         design: {},
+                        designRaw: {},
                         resolved: { value: 'fromResolveData' },
                     },
                     slots: {},
@@ -450,7 +453,7 @@ describe('ServerExperienceRenderer — getContentfulComponent()', () => {
     });
 });
 describe('ServerExperienceRenderer — resolveToken', () => {
-    it('passes DesignToken envelopes through the resolver before render', async () => {
+    it('passes DesignToken values through the resolver before render', async () => {
         const cfg = {
             components: { 'contentful-button': ButtonFixture },
             resolveToken: (ref) => (ref.value === 'color/surface/hero' ? '#4f39f6' : undefined),
@@ -471,7 +474,7 @@ describe('ServerExperienceRenderer — resolveToken', () => {
         expect(container.innerHTML).toContain('data-bg="#4f39f6"');
         expect(container.innerHTML).not.toContain('DesignToken');
     });
-    it('warns and drops the key from the design bag when the resolver returns undefined', async () => {
+    it('warns and drops the key from the design values when the resolver returns undefined', async () => {
         const warn = vi.spyOn(console, 'warn').mockImplementation(() => { });
         const cfg = {
             components: { 'contentful-button': CapturingComponent },
@@ -495,7 +498,7 @@ describe('ServerExperienceRenderer — resolveToken', () => {
         expect(warn).toHaveBeenCalledWith(expect.stringContaining('contentful-button'));
         warn.mockRestore();
     });
-    it('leaves envelopes untouched when no resolver is supplied', async () => {
+    it('leaves token values untouched when no resolver is supplied (backward-compatible)', async () => {
         const cfg = { components: { 'contentful-button': ButtonFixture } };
         const plan = await resolveExperience({
             viewports: VIEWPORTS,
@@ -510,8 +513,8 @@ describe('ServerExperienceRenderer — resolveToken', () => {
         const { container } = render(ServerExperienceRenderer, {
             props: { experience: plan, config: cfg },
         });
-        // Svelte stringifies the envelope object into "[object Object]" on the
-        // attribute — the point is that the raw envelope reaches the component
+        // Svelte stringifies the token object into "[object Object]" on the
+        // attribute — the point is that the raw token value reaches the component
         // unchanged, so the customer can inspect it or resolve it themselves.
         expect(container.innerHTML).toContain('data-bg="[object Object]"');
     });
@@ -535,17 +538,20 @@ describe('ServerExperienceRenderer — resolveToken', () => {
             nodes: [componentNode('item', { id: 'i', contentProperties: { value: 'ok' } })],
         };
         const plan = await resolveExperience(tplPayload, tplConfig);
-        // Templates don't carry design props in the current XDA payload shape;
-        // seed one on the resolved plan so we exercise the experienceTemplate path.
-        plan.experienceTemplate.props.design = { cfBackground: dt('brand/canvas') };
+        // Experience Templates don't carry design props in the current XDA payload
+        // shape; seed a raw token on the resolved plan so we exercise the
+        // experienceTemplate path. Render at a non-fallback viewport (mobile ≠
+        // fallback index 0) so the adapter recomputes from the seeded raw design
+        // and runs resolveToken.
+        plan.experienceTemplate.props.designRaw = { cfBackground: dt('brand/canvas') };
         const { container } = render(ServerExperienceRenderer, {
-            props: { experience: plan, config: tplConfig },
+            props: { experience: plan, config: tplConfig, initialViewportId: 'mobile' },
         });
         expect(container.innerHTML).toContain('data-bg="#111827"');
     });
 });
-describe('ServerExperienceRenderer — design values are not injected as props', () => {
-    it('does NOT spread resolved design values onto component props', async () => {
+describe('ServerExperienceRenderer — design values auto-fill props', () => {
+    it('spreads resolved design values onto component props by their raw key', async () => {
         const cfg = { components: { capture: CapturingComponent } };
         const plan = await resolveExperience({
             viewports: VIEWPORTS,
@@ -560,20 +566,39 @@ describe('ServerExperienceRenderer — design values are not injected as props',
         render(ServerExperienceRenderer, {
             props: { experience: plan, config: cfg },
         });
-        const keys = Object.keys(captureSink[0].props);
-        // Content still flows as a prop; design does not.
-        expect(keys).toContain('label');
-        expect(keys).not.toContain('cfBackgroundColor');
-        expect(keys).not.toContain('cfPadding');
+        // Content flows as a prop, and design auto-fills props under its raw key.
+        expect(captureSink[0].props).toMatchObject({
+            label: 'keep me',
+            cfBackgroundColor: '#f00',
+            cfPadding: '10px',
+        });
         // The values are still readable through getDesignValues().
         expect(captureSink[0].designValues).toEqual({
             cfBackgroundColor: '#f00',
             cfPadding: '10px',
         });
     });
+    it('lets content override design on a key collision (content wins)', async () => {
+        const cfg = { components: { capture: CapturingComponent } };
+        const plan = await resolveExperience({
+            viewports: VIEWPORTS,
+            nodes: [
+                componentNode('capture', {
+                    id: 'p',
+                    // Same key in both channels: content must win.
+                    contentProperties: { cfPadding: 'from-content' },
+                    designProperties: { cfPadding: m('from-design') },
+                }),
+            ],
+        }, cfg);
+        render(ServerExperienceRenderer, {
+            props: { experience: plan, config: cfg },
+        });
+        expect(captureSink[0].props).toMatchObject({ cfPadding: 'from-content' });
+    });
 });
 describe('ServerExperienceRenderer — getDesignValues()', () => {
-    it('returns the resolved design bag for the current node', async () => {
+    it('returns the resolved design values for the current node', async () => {
         const cfg = {
             components: { capture: CapturingComponent },
             resolveToken: (ref) => (ref.value === 'brand/primary' ? '#4f39f6' : undefined),
@@ -615,6 +640,46 @@ describe('ServerExperienceRenderer — getDesignValues()', () => {
         expect(captureSink[0].designValues).toEqual({ cfPadding: '12px' });
     });
 });
+describe('ServerExperienceRenderer — server pre-resolved design values', () => {
+    const probePayload = {
+        viewports: VIEWPORTS,
+        nodes: [
+            componentNode('contentful-container', {
+                id: 'p',
+                designProperties: { cfPadding: vbv({ desktop: m('40px'), mobile: m('12px') }) },
+            }),
+        ],
+    };
+    it('consumes props.design as-is when the active viewport equals the fallback', async () => {
+        const plan = await resolveExperience(probePayload, config, { initialViewportId: 'mobile' });
+        // Tamper the precomputed values with a sentinel the cascade could never produce.
+        plan.nodes[0].props.design = { cfPadding: 'SENTINEL' };
+        const { container } = render(ServerExperienceRenderer, {
+            props: { experience: plan, config, initialViewportId: 'mobile' },
+        });
+        expect(container.innerHTML).toContain('data-padding="SENTINEL"');
+    });
+    it('recomputes from raw design properties when the active viewport differs from the fallback', async () => {
+        const plan = await resolveExperience(probePayload, config, { initialViewportId: 'mobile' });
+        plan.nodes[0].props.design = { cfPadding: 'SENTINEL' };
+        // Active viewport (desktop, idx 0) ≠ fallback (mobile, idx 2) → recompute.
+        const { container } = render(ServerExperienceRenderer, {
+            props: { experience: plan, config, initialViewportId: 'desktop' },
+        });
+        expect(container.innerHTML).toContain('data-padding="40px"');
+        expect(container.innerHTML).not.toContain('SENTINEL');
+    });
+    it('recomputes when the active viewport differs from the default fallback (viewport[0])', async () => {
+        const plan = await resolveExperience(probePayload, config);
+        // No fallback configured → pre-resolved against viewport[0] (desktop, idx 0).
+        expect(plan.fallbackViewportIndex).toBe(0);
+        // Active viewport is mobile (idx 2) ≠ fallback (idx 0) → recompute to 12px.
+        const { container } = render(ServerExperienceRenderer, {
+            props: { experience: plan, config, initialViewportId: 'mobile' },
+        });
+        expect(container.innerHTML).toContain('data-padding="12px"');
+    });
+});
 describe('toCss (Svelte)', () => {
     it('converts bare (non-cf) CSS keys — the shape real payloads use', () => {
         expect(toCss({ fontSize: '20px', backgroundColor: '#4f39f6' })).toEqual({

package/dist/types.d.ts

@@ -9,9 +9,9 @@ export type { ResolveContext, ResolveToken };
  * analytics on `nodeId`, rendering a raw-payload panel in preview, or
  * rendering non-`children` slots through the exported `<NodesRenderer />`.
  *
- * Design properties stay in their **raw envelope form** here (the same shape
- * `ctx.design` carries inside `resolveData`). The viewport-cascaded, token-
- * resolved values are what `getDesignValues()` returns.
+ * Design properties stay in their **raw discriminated form** here (the same
+ * shape `ctx.design` carries inside `resolveData`). The viewport-cascaded,
+ * token-resolved values are what `getDesignValues()` returns.
  */
 export interface ContentfulComponent {
     componentId: string;
@@ -46,12 +46,19 @@ export interface ContentfulExperienceTemplate {
 export interface RenderContext extends ExperienceContext {
     activeViewport: ViewportDef;
     activeViewportIndex: number;
+    /**
+     * Viewport index the server pre-resolved design against (from
+     * `PortableRenderPlan.fallbackViewportIndex`). Renderers use `props.design`
+     * as-is when `activeViewportIndex` matches, and recompute otherwise. Always a
+     * number — the plan field is required, so the match is a real comparison.
+     */
+    fallbackViewportIndex: number;
 }
 /**
  * Customer-supplied configuration for a single component type. The `component`
- * receives the merged prop bag (content + resolveData + `children` Snippet).
- * Design values are not injected — a component reads them via
- * `getDesignValues()`. Runtime context and raw payload come from
+ * receives the merged props (design + content + resolveData + `children`
+ * Snippet); resolved design values auto-fill matching props and are also
+ * readable via `getDesignValues()`. Runtime context and raw payload come from
  * `getExperience()` / `getContentfulComponent()`.
  */
 export interface ComponentConfig<Props extends object = Record<string, unknown>> {
@@ -83,8 +90,8 @@ export interface Config {
     components: Components;
     experienceTemplates?: ExperienceTemplates;
     /**
-     * Resolves `DesignToken` envelopes to runtime values before they reach a
-     * component. If omitted, envelopes pass through unchanged. See `ResolveToken`
+     * Resolves `DesignToken` values to runtime values before they reach a
+     * component. If omitted, they pass through unchanged. See `ResolveToken`
      * in `@contentful/experiences-sdk-core` for the full contract.
      */
     resolveToken?: ResolveToken;

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contentful/experiences-svelte",
-  "version": "0.5.1",
+  "version": "0.5.3",
   "description": "Svelte adapter for Contentful Experiences — Server and Client renderers over a PortableRenderPlan",
   "license": "MIT",
   "type": "module",
@@ -35,9 +35,9 @@
     "check": "svelte-check --tsconfig ./tsconfig.json"
   },
   "dependencies": {
-    "@contentful/experiences-client": "0.3.0",
-    "@contentful/experiences-sdk-core": "0.7.0",
-    "@contentful/experiences-design": "0.7.0"
+    "@contentful/experiences-client": "0.3.2",
+    "@contentful/experiences-sdk-core": "0.7.2",
+    "@contentful/experiences-design": "0.7.2"
   },
   "peerDependencies": {
     "svelte": "^5.55.7"