@contentful/experiences-svelte 0.5.0 → 0.5.2

package/CHANGELOG.md

@@ -1,3 +1,21 @@
+## 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
+
+- expose slot children as an array instead of a single wrapping node ([#122](https://github.com/contentful/experiences/pull/122))
+
 ## 0.5.0 (2026-08-07)
 
 ### 🩹 Fixes

package/README.md

@@ -35,14 +35,14 @@ resolveExperience(payload, config, opts?); // Async; walks payload, runs resolve
 ServerExperienceRenderer; // SSR-safe; active viewport seeded from initialViewportId
 ClientExperienceRenderer; // Subscribes to window.matchMedia via runes
 MissingComponent; // Default fallback for unregistered component types
-NodesRenderer; // Exposed so you can render non-`children` slots manually
+NodesRenderer; // Exposed so you can render non-`children` slots manually (see Slot children)
 useActiveViewport; // Rune-backed reactive object; you'll rarely need it directly
 ```
 
 ### 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}
 ```
 
@@ -124,6 +127,37 @@ export const experienceConfig: Config = { components, resolveToken };
 <ServerExperienceRenderer experience={data.experience} config={experienceConfig} />
 ```
 
+### Slot children
+
+A component's default slot children arrive as an **array of Snippets** (`Snippet[]`), one per child — not a single wrapping Snippet. For the common "just render them" case, iterate the array with `{#each}` and `{@render}`; to wrap, reorder, or drop children individually, do it inside that loop.
+
+```svelte
+<!-- Section.svelte -->
+<script lang="ts">
+  import type { Snippet } from 'svelte';
+
+  let { children }: { children?: Snippet[] } = $props();
+</script>
+
+<!-- Common case — render them all: -->
+<div>
+  {#each children ?? [] as child}
+    {@render child()}
+  {/each}
+</div>
+
+<!-- Or take control of each child: -->
+<!--
+<div>
+  {#each children ?? [] as child, i}
+    <div class="cell">{@render child()}</div>
+  {/each}
+</div>
+-->
+```
+
+The default slot is injected as the `children` prop. Any **additional named slots** are not auto-injected — reach them from the raw payload via `getContentfulComponent().slots` (a `Record<string, PortableRenderNode[]>`) and render them yourself with `NodesRenderer`.
+
 For the full getting-started walkthrough, the merge-precedence rules, viewport handling, and design rationale, see the [root README](../../README.md) and [`AGENTS.md`](../../AGENTS.md).
 
 ---

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,
@@ -23,7 +23,7 @@
     config: Config;
     experience: RenderContext;
     renderUnknown: RenderUnknown;
-    children: Snippet;
+    children: Snippet[];
   }
 
   let { node, config, experience, renderUnknown, children }: NodeRendererProps = $props();
@@ -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

@@ -7,7 +7,7 @@ interface NodeRendererProps {
     config: Config;
     experience: RenderContext;
     renderUnknown: RenderUnknown;
-    children: Snippet;
+    children: Snippet[];
 }
 declare const NodeRenderer: import("svelte").Component<NodeRendererProps, {}, "">;
 type NodeRenderer = ReturnType<typeof NodeRenderer>;

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,CAAC;CACnB;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/NodesRenderer.svelte

@@ -1,22 +1,17 @@
 <!--
  * Recursive renderer over PortableRenderNodes. Customer components receive
  * the merged content / design / resolveData prop bag plus the default
- * `children` slot as a named Snippet:
+ * `children` slot as an ARRAY of Snippets — one zero-arg Snippet per
+ * pre-rendered child node — declared as `children?: Snippet[]`. A component
+ * renders them all with an each-block + @render, or maps/filters/wraps the
+ * children individually. The array mirrors the React adapter's ReactNode[]
+ * slot contract; see the README for the consuming-a-slot example.
  *
- *     <script lang="ts">
- *       import type { Snippet } from 'svelte';
- *       let { text, children }: { text?: string; children?: Snippet } = $props();
- *     </script>
- *     <button>
- *       {text}
- *       {@render children?.()}
- *     </button>
- *
- * Only the `children` slot is rendered automatically — Svelte 5 Snippets are
- * compile-time entities, so the renderer can't synthesize an unbounded set
- * of named Snippet props from runtime payload data. Additional named slots
- * are reachable through `getContentfulComponent().slots` and can be rendered
- * with the exported `<NodesRenderer />` (see README).
+ * Only the default `children` slot is injected as a prop — Svelte 5 Snippets
+ * are compile-time entities, so the renderer can't synthesize an unbounded
+ * set of named Snippet props from runtime payload data. Additional named
+ * slots are reachable through `getContentfulComponent().slots` and can be
+ * rendered with the exported NodesRenderer (see README).
  *
  * The Experience runtime context and the raw Contentful payload are read
  * via `getExperience` / `getContentfulComponent`.
@@ -25,10 +20,11 @@
  * the active viewport is sourced (initial seed vs reactive matchMedia).
 -->
 <script lang="ts">
+  import type { Snippet } from 'svelte';
+
   import type { PortableRenderNode } from '@contentful/experiences-sdk-core';
 
   import NodeRenderer from './NodeRenderer.svelte';
-  import NodesRenderer from './NodesRenderer.svelte';
   import type { RenderUnknown } from './component-props.js';
   import type { Config, RenderContext } from './types.js';
 
@@ -40,12 +36,24 @@
   }
 
   let { nodes, config, experience, renderUnknown }: NodesRendererProps = $props();
+
+  // Curry the parameterized `renderNode` snippet into a zero-arg Snippet bound
+  // to one node. Svelte 5 invokes a snippet as `(anchor, ...argGetters)`, so we
+  // forward the anchor and supply the node through a getter. This is the one
+  // spot that leans on Svelte's snippet calling convention; pinned by the
+  // `children`-array tests in server-renderer.test.ts.
+  function toChildSnippet(node: PortableRenderNode): Snippet {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any -- programmatic snippet construction; see note above.
+    return ((anchor: unknown) => (renderNode as any)(anchor, () => node)) as Snippet;
+  }
 </script>
 
-{#each nodes as node, index (node.nodeId ?? index)}
-  {#snippet children()}
-    {@const childrenNodes = (node.slots.children ?? []) as PortableRenderNode[]}
-    <NodesRenderer nodes={childrenNodes} {config} {experience} {renderUnknown} />
-  {/snippet}
+{#snippet renderNode(node: PortableRenderNode)}
+  {@const childNodes = (node.slots.children ?? []) as PortableRenderNode[]}
+  {@const children = childNodes.map(toChildSnippet)}
   <NodeRenderer {node} {config} {experience} {renderUnknown} {children} />
+{/snippet}
+
+{#each nodes as node, index (node.nodeId ?? index)}
+  {@render renderNode(node)}
 {/each}

package/dist/NodesRenderer.svelte.d.ts

@@ -1,5 +1,4 @@
 import type { PortableRenderNode } from '@contentful/experiences-sdk-core';
-import NodesRenderer from './NodesRenderer.svelte';
 import type { RenderUnknown } from './component-props.js';
 import type { Config, RenderContext } from './types.js';
 interface NodesRendererProps {

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

@@ -1 +1 @@
-{"version":3,"file":"NodesRenderer.svelte.d.ts","sourceRoot":"","sources":["../src/NodesRenderer.svelte.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,kCAAkC,CAAC;AAG3E,OAAO,aAAa,MAAM,wBAAwB,CAAC;AACnD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,KAAK,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAGtD,UAAU,kBAAkB;IAC1B,KAAK,EAAE,kBAAkB,EAAE,CAAC;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,aAAa,CAAC;IAC1B,aAAa,EAAE,aAAa,CAAC;CAC9B;AAwBH,QAAA,MAAM,aAAa,wDAAwC,CAAC;AAC5D,KAAK,aAAa,GAAG,UAAU,CAAC,OAAO,aAAa,CAAC,CAAC;AACtD,eAAe,aAAa,CAAC"}
+{"version":3,"file":"NodesRenderer.svelte.d.ts","sourceRoot":"","sources":["../src/NodesRenderer.svelte.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,kCAAkC,CAAC;AAG3E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,KAAK,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAGtD,UAAU,kBAAkB;IAC1B,KAAK,EAAE,kBAAkB,EAAE,CAAC;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,aAAa,CAAC;IAC1B,aAAa,EAAE,aAAa,CAAC;CAC9B;AAqCH,QAAA,MAAM,aAAa,wDAAwC,CAAC;AAC5D,KAAK,aAAa,GAAG,UAAU,CAAC,OAAO,aAAa,CAAC,CAAC;AACtD,eAAe,aAAa,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

@@ -9,6 +9,7 @@ import HeadingFixture from './test-fixtures/HeadingFixture.svelte';
 import ItemFixture from './test-fixtures/ItemFixture.svelte';
 import PrecedenceFixture from './test-fixtures/PrecedenceFixture.svelte';
 import ExperienceTemplateFixture from './test-fixtures/ExperienceTemplateFixture.svelte';
+import WrappingContainerFixture from './test-fixtures/WrappingContainerFixture.svelte';
 import { captureSink } from './test-fixtures/capture-sink.js';
 import { toCss } from './design-utils.js';
 const VIEWPORTS = [
@@ -153,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: {},
                             },
                         ],
@@ -241,6 +243,7 @@ describe('ServerExperienceRenderer', () => {
         };
         const planWithResolved = {
             viewports: VIEWPORTS,
+            fallbackViewportIndex: 0,
             nodes: [
                 {
                     nodeId: 'r',
@@ -248,6 +251,7 @@ describe('ServerExperienceRenderer', () => {
                     props: {
                         content: { value: 'fromContent' },
                         design: {},
+                        designRaw: {},
                         resolved: { value: 'fromResolveData' },
                     },
                     slots: {},
@@ -313,6 +317,66 @@ describe('ServerExperienceRenderer', () => {
         warn.mockRestore();
     });
 });
+describe('ServerExperienceRenderer — slot children as an array', () => {
+    const childrenPayload = () => ({
+        viewports: VIEWPORTS,
+        nodes: [
+            componentNode('contentful-container', {
+                id: 'c',
+                slots: {
+                    children: [
+                        componentNode('contentful-heading', {
+                            id: 'a',
+                            contentProperties: { text: 'one' },
+                        }),
+                        componentNode('contentful-heading', {
+                            id: 'b',
+                            contentProperties: { text: 'two' },
+                        }),
+                        componentNode('contentful-heading', {
+                            id: 'd',
+                            contentProperties: { text: 'three' },
+                        }),
+                    ],
+                },
+            }),
+        ],
+    });
+    it('passes slot children as a Snippet[] a component can wrap individually', async () => {
+        const cfg = {
+            components: {
+                'contentful-container': WrappingContainerFixture,
+                'contentful-heading': HeadingFixture,
+            },
+        };
+        const plan = await resolveExperience(childrenPayload(), cfg);
+        const { container } = render(ServerExperienceRenderer, {
+            props: { experience: plan, config: cfg },
+        });
+        // The component received a real array of the right length.
+        expect(captureSink[0].props.childrenIsArray).toBe(true);
+        expect(captureSink[0].props.childCount).toBe(3);
+        // Each child got its own wrapper — proves per-child rendering control.
+        const wrappers = container.querySelectorAll('.wrap');
+        expect(wrappers.length).toBe(3);
+        expect(container.querySelector('[data-index="0"]')).not.toBeNull();
+        expect(container.querySelector('[data-index="2"]')).not.toBeNull();
+        expect(container.textContent).toContain('one');
+        expect(container.textContent).toContain('three');
+    });
+    it('renders an empty container when the slot has no children', async () => {
+        const cfg = {
+            components: { 'contentful-container': WrappingContainerFixture },
+        };
+        const plan = await resolveExperience({ viewports: VIEWPORTS, nodes: [componentNode('contentful-container', { id: 'c' })] }, cfg);
+        const { container } = render(ServerExperienceRenderer, {
+            props: { experience: plan, config: cfg },
+        });
+        expect(captureSink[0].props.childCount).toBe(0);
+        expect(container.querySelectorAll('.wrap').length).toBe(0);
+        expect(container.querySelector('[data-container]')).not.toBeNull();
+    });
+});
 describe('ServerExperienceRenderer — bare-component registrations', () => {
     it('accepts a bare Svelte component as a registry entry', async () => {
         const cfg = { components: { item: PrecedenceFixture } };
@@ -389,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),
@@ -410,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 },
@@ -434,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,
@@ -449,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]"');
     });
@@ -474,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,
@@ -499,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),
@@ -554,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/test-fixtures/ContainerFixture.svelte

@@ -3,10 +3,12 @@
 
   import { getDesignValues } from '../get-design-values.js';
 
-  let { children }: { children?: Snippet } = $props();
+  let { children }: { children?: Snippet[] } = $props();
   const design = $derived(getDesignValues());
 </script>
 
 <div data-padding={design.cfPadding as string}>
-  {#if children}{@render children()}{/if}
+  {#each children ?? [] as child}
+    {@render child()}
+  {/each}
 </div>

package/dist/test-fixtures/ContainerFixture.svelte.d.ts

@@ -1,6 +1,6 @@
 import type { Snippet } from 'svelte';
 type $$ComponentProps = {
-    children?: Snippet;
+    children?: Snippet[];
 };
 declare const ContainerFixture: import("svelte").Component<$$ComponentProps, {}, "">;
 type ContainerFixture = ReturnType<typeof ContainerFixture>;

package/dist/test-fixtures/ContainerFixture.svelte.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ContainerFixture.svelte.d.ts","sourceRoot":"","sources":["../../src/test-fixtures/ContainerFixture.svelte.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAC;AAIrC,KAAK,gBAAgB,GAAI;IAAE,QAAQ,CAAC,EAAE,OAAO,CAAA;CAAE,CAAC;AAgBjD,QAAA,MAAM,gBAAgB,sDAAwC,CAAC;AAC/D,KAAK,gBAAgB,GAAG,UAAU,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAC5D,eAAe,gBAAgB,CAAC"}
+{"version":3,"file":"ContainerFixture.svelte.d.ts","sourceRoot":"","sources":["../../src/test-fixtures/ContainerFixture.svelte.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAC;AAIrC,KAAK,gBAAgB,GAAI;IAAE,QAAQ,CAAC,EAAE,OAAO,EAAE,CAAA;CAAE,CAAC;AAkBnD,QAAA,MAAM,gBAAgB,sDAAwC,CAAC;AAC/D,KAAK,gBAAgB,GAAG,UAAU,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAC5D,eAAe,gBAAgB,CAAC"}

package/dist/test-fixtures/WrappingContainerFixture.svelte

@@ -0,0 +1,27 @@
+<!--
+  Test fixture: proves slot children arrive as an array of Snippets that a
+  component can iterate and wrap individually. Also records the received array
+  length in the capture sink.
+-->
+<script lang="ts">
+  import type { Snippet } from 'svelte';
+
+  import { getContentfulComponent, getExperience } from '../context.js';
+  import { captureSink } from './capture-sink.js';
+
+  let { children }: { children?: Snippet[] } = $props();
+
+  captureSink.push({
+    props: { childCount: children?.length ?? 0, childrenIsArray: Array.isArray(children) },
+    experience: getExperience(),
+    contentful: getContentfulComponent(),
+  });
+</script>
+
+<div data-container>
+  {#each children ?? [] as child, i}
+    <div class="wrap" data-index={i}>
+      {@render child()}
+    </div>
+  {/each}
+</div>

package/dist/test-fixtures/WrappingContainerFixture.svelte.d.ts

@@ -0,0 +1,8 @@
+import type { Snippet } from 'svelte';
+type $$ComponentProps = {
+    children?: Snippet[];
+};
+declare const WrappingContainerFixture: import("svelte").Component<$$ComponentProps, {}, "">;
+type WrappingContainerFixture = ReturnType<typeof WrappingContainerFixture>;
+export default WrappingContainerFixture;
+//# sourceMappingURL=WrappingContainerFixture.svelte.d.ts.map

package/dist/test-fixtures/WrappingContainerFixture.svelte.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"WrappingContainerFixture.svelte.d.ts","sourceRoot":"","sources":["../../src/test-fixtures/WrappingContainerFixture.svelte.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAC;AAKrC,KAAK,gBAAgB,GAAI;IAAE,QAAQ,CAAC,EAAE,OAAO,EAAE,CAAA;CAAE,CAAC;AA2BnD,QAAA,MAAM,wBAAwB,sDAAwC,CAAC;AACvE,KAAK,wBAAwB,GAAG,UAAU,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAC5E,eAAe,wBAAwB,CAAC"}

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":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,QAAQ,CAAC;AAExC,OAAO,KAAK,EACV,eAAe,EACf,iBAAiB,EACjB,cAAc,EACd,YAAY,EACZ,WAAW,EACZ,MAAM,kCAAkC,CAAC;AAE1C,YAAY,EAAE,cAAc,EAAE,YAAY,EAAE,CAAC;AAE7C;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,mBAAmB;IAClC,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;IACxC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC;;;;;OAKG;IACH,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChC;AAED;;;;GAIG;AACH,MAAM,WAAW,4BAA4B;IAC3C,oBAAoB,EAAE,MAAM,CAAC;IAC7B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;IACxC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED;;;;GAIG;AACH,MAAM,WAAW,aAAc,SAAQ,iBAAiB;IACtD,cAAc,EAAE,WAAW,CAAC;IAC5B,mBAAmB,EAAE,MAAM,CAAC;CAC7B;AAED;;;;;;GAMG;AACH,MAAM,WAAW,eAAe,CAAC,KAAK,SAAS,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAC7E,QAAQ,CAAC,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC;IAC1B,WAAW,CAAC,EAAE,CAAC,GAAG,EAAE,cAAc,KAAK,OAAO,CAAC,KAAK,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC;IAEhF,SAAS,EAAE,SAAS,CAAC,GAAG,CAAC,CAAC;CAC3B;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,YAAY,CAAC,KAAK,SAAS,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,IAErE,SAAS,CAAC,GAAG,CAAC,GAAG,eAAe,CAAC,KAAK,CAAC,CAAC;AAE1C,MAAM,WAAW,wBAAwB,CAAC,KAAK,SAAS,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IACtF,QAAQ,CAAC,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC;IAC1B,WAAW,CAAC,EAAE,CAAC,GAAG,EAAE,cAAc,KAAK,OAAO,CAAC,KAAK,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC;IAEhF,SAAS,EAAE,SAAS,CAAC,GAAG,CAAC,CAAC;CAC3B;AAED,MAAM,MAAM,8BAA8B,CAAC,KAAK,SAAS,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,IAEvF,SAAS,CAAC,GAAG,CAAC,GAAG,wBAAwB,CAAC,KAAK,CAAC,CAAC;AAEnD,wBAAgB,wBAAwB,CAAC,KAAK,SAAS,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACrF,MAAM,EAAE,wBAAwB,CAAC,KAAK,CAAC,GACtC,wBAAwB,CAAC,KAAK,CAAC,CAEjC;AAED,wBAAgB,eAAe,CAAC,KAAK,SAAS,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC5E,MAAM,EAAE,eAAe,CAAC,KAAK,CAAC,GAC7B,eAAe,CAAC,KAAK,CAAC,CAExB;AAGD,MAAM,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC;AAE3D,MAAM,MAAM,mBAAmB,GAAG,MAAM,CAAC,MAAM,EAAE,8BAA8B,CAAC,GAAG,CAAC,CAAC,CAAC;AAEtF,MAAM,WAAW,MAAM;IACrB,UAAU,EAAE,UAAU,CAAC;IACvB,mBAAmB,CAAC,EAAE,mBAAmB,CAAC;IAC1C;;;;OAIG;IACH,YAAY,CAAC,EAAE,YAAY,CAAC;CAC7B;AAED;;;;;GAKG;AACH,wBAAgB,8BAA8B,CAAC,CAAC,SAAS,MAAM,EAC7D,GAAG,EAAE,YAAY,CAAC,CAAC,CAAC,GACnB,eAAe,CAAC,CAAC,CAAC,CAMpB;AAED,wBAAgB,uCAAuC,CAAC,CAAC,SAAS,MAAM,EACtE,GAAG,EAAE,8BAA8B,CAAC,CAAC,CAAC,GACrC,wBAAwB,CAAC,CAAC,CAAC,CAM7B"}
+{"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.0",
+  "version": "0.5.2",
   "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.1",
+    "@contentful/experiences-sdk-core": "0.7.1",
+    "@contentful/experiences-design": "0.7.1"
   },
   "peerDependencies": {
     "svelte": "^5.55.7"