@contentful/experiences-svelte 0.4.1 → 0.5.1

package/CHANGELOG.md

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

package/README.md

@@ -20,7 +20,7 @@ The public API mirrors `@contentful/experiences-react` 1:1 in shape; only the re
 
 ```ts
 defineComponent<Props>(config); // Type-narrowing identity for component-type configs
-defineTemplate<Props>(config); // Same shape, for page-level template wrappers
+defineExperienceTemplate<Props>(config); // Same shape, for page-level Experience Template wrappers
 ```
 
 ### Resolver
@@ -35,7 +35,7 @@ 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
 ```
 
@@ -46,7 +46,7 @@ getDesignValues<T>(); // Resolved design values for the current node; read in a
 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)
-getContentfulTemplate(); // Same, for the page-level template
+getContentfulExperienceTemplate(); // Same, for the page-level Experience Template
 type ToCssOptions;
 ```
 
@@ -56,12 +56,12 @@ Design is **not** injected as props; components read it via `getDesignValues()`
 
 ```ts
 // From core
-type Config, Components, Templates, Registration, TemplateRegistration,
-type ComponentConfig, TemplateConfig,
-type ContentfulComponent, ContentfulTemplate,
+type Config, Components, ExperienceTemplates, Registration, ExperienceTemplateRegistration,
+type ComponentConfig, ExperienceTemplateConfig,
+type ContentfulComponent, ContentfulExperienceTemplate,
 type RenderContext, ResolveToken,
-type ExperiencePayload, ExperienceNode, ComponentTypeNode, TemplateNode,
-type PortableRenderPlan, PortableRenderNode, PortableTemplate,
+type ExperiencePayload, ExperienceNode, ComponentNode, ExperienceTemplateNode,
+type PortableRenderPlan, PortableRenderNode, PortableExperienceTemplate,
 type DesignPropValue, ManualDesignValue, DesignToken, ValuesByViewport,
 type ViewportDef, ExperienceContext, ResolveContext,
 type ResolverConfig, ResolveExperienceOptions
@@ -124,6 +124,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

@@ -14,7 +14,7 @@
   import DebugExperience from './DebugExperience.svelte';
   import MissingComponent from './MissingComponent.svelte';
   import NodesRenderer from './NodesRenderer.svelte';
-  import WrapWithTemplate from './WrapWithTemplate.svelte';
+  import WrapWithExperienceTemplate from './WrapWithExperienceTemplate.svelte';
   import type { ClientExperienceRendererProps } from './component-props.js';
   import { setExperience } from './context.js';
   import type { RenderContext } from './types.js';
@@ -73,7 +73,7 @@
   {#if debug}
     <DebugExperience {experience} />
   {/if}
-  <WrapWithTemplate template={experience.template} {config} experience={liveContext}>
+  <WrapWithExperienceTemplate experienceTemplate={experience.experienceTemplate} {config} experience={liveContext}>
     {#snippet children()}
       <NodesRenderer
         nodes={experience.nodes}
@@ -82,5 +82,5 @@
         {renderUnknown}
       />
     {/snippet}
-  </WrapWithTemplate>
+  </WrapWithExperienceTemplate>
 {/if}

package/dist/DebugExperience.svelte

@@ -19,7 +19,9 @@
   const nodeCount = $derived(experience.nodes.length);
   const summary = $derived(
     `Experience debug — ${nodeCount} top-level node${nodeCount === 1 ? '' : 's'}${
-      experience.template ? `, template: ${experience.template.templateId}` : ''
+      experience.experienceTemplate
+        ? `, experience template: ${experience.experienceTemplate.experienceTemplateId}`
+        : ''
     }`
   );
 

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

@@ -1 +1 @@
-{"version":3,"file":"DebugExperience.svelte.d.ts","sourceRoot":"","sources":["../src/DebugExperience.svelte.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAmDjE,QAAA,MAAM,eAAe,0DAAwC,CAAC;AAC9D,KAAK,eAAe,GAAG,UAAU,CAAC,OAAO,eAAe,CAAC,CAAC;AAC1D,eAAe,eAAe,CAAC"}
+{"version":3,"file":"DebugExperience.svelte.d.ts","sourceRoot":"","sources":["../src/DebugExperience.svelte.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAqDjE,QAAA,MAAM,eAAe,0DAAwC,CAAC;AAC9D,KAAK,eAAe,GAAG,UAAU,CAAC,OAAO,eAAe,CAAC,CAAC;AAC1D,eAAe,eAAe,CAAC"}

package/dist/DebugExperience.test.js

@@ -2,9 +2,9 @@ import { render } from '@testing-library/svelte';
 import { describe, expect, it } from 'vitest';
 import DebugExperience from './DebugExperience.svelte';
 const emptyPlan = { nodes: [], viewports: [] };
-function node(componentTypeId, content = {}) {
+function node(componentId, content = {}) {
     return {
-        registration: { componentTypeId },
+        registration: { componentId },
         props: { content, design: {} },
         slots: {},
     };
@@ -29,14 +29,14 @@ describe('DebugExperience.svelte', () => {
         const { container } = render(DebugExperience, { props: { experience: one } });
         expect(container.innerHTML).toContain('Experience debug — 1 top-level node');
     });
-    it('names the template in the summary when present', () => {
+    it('names the experienceTemplate in the summary when present', () => {
         const plan = {
             viewports: [],
             nodes: [],
-            template: { templateId: 'page', props: { content: {}, design: {} } },
+            experienceTemplate: { experienceTemplateId: 'page', props: { content: {}, design: {} } },
         };
         const { container } = render(DebugExperience, { props: { experience: plan } });
-        expect(container.innerHTML).toContain('template: page');
+        expect(container.innerHTML).toContain('experience template: page');
     });
     it('dumps the plan as pretty JSON', () => {
         const plan = {
@@ -44,7 +44,7 @@ describe('DebugExperience.svelte', () => {
             nodes: [node('button', { label: 'Go' })],
         };
         const { container } = render(DebugExperience, { props: { experience: plan } });
-        expect(container.innerHTML).toContain('componentTypeId');
+        expect(container.innerHTML).toContain('componentId');
         expect(container.innerHTML).toContain('button');
         expect(container.innerHTML).toContain('Go');
     });

package/dist/MissingComponent.svelte

@@ -1,5 +1,5 @@
 <!--
- * Default fallback rendered when an instance references a component type
+ * Default fallback rendered when an instance references a component
  * not present in the Config.
  *
  * Behavior: a visible debug box when `debug` is on, silent null otherwise.
@@ -10,14 +10,14 @@
   import type { MissingComponentProps } from './component-props.js';
   import { getExperience } from './context.js';
 
-  let { componentTypeId, nodeId }: MissingComponentProps = $props();
+  let { componentId, nodeId }: MissingComponentProps = $props();
   const experience = getExperience();
 
   $effect(() => {
     if (typeof console !== 'undefined') {
       const idLabel = nodeId ? ` (nodeId: ${nodeId})` : '';
       console.warn(
-        `[@contentful/experiences] No component registered for type "${componentTypeId}"${idLabel}.`
+        `[@contentful/experiences] No component registered for id "${componentId}"${idLabel}.`
       );
     }
   });
@@ -26,15 +26,15 @@
 {#if experience.debug}
   <div
     style="border: 2px solid red; padding: 1rem; color: red; background: #fff; font-family: ui-monospace, SFMono-Regular, Menlo, monospace; font-size: 0.8125rem;"
-    data-experiences-missing={componentTypeId}
+    data-experiences-missing={componentId}
   >
-    <strong>Missing component &lsquo;{componentTypeId}&rsquo;</strong>
+    <strong>Missing component &lsquo;{componentId}&rsquo;</strong>
     <p style="margin: 0.5rem 0;">
       This component is referenced by the Experience payload but is not registered in the Config.
       Register it under this key in your <code>components</code> map:
     </p>
     <pre style="margin: 0; white-space: pre-wrap;">{JSON.stringify(
-        { componentTypeId, nodeId: nodeId ?? null },
+        { componentId, nodeId: nodeId ?? null },
         null,
         2
       )}</pre>

package/dist/NodeRenderer.svelte

@@ -23,16 +23,16 @@
     config: Config;
     experience: RenderContext;
     renderUnknown: RenderUnknown;
-    children: Snippet;
+    children: Snippet[];
   }
 
   let { node, config, experience, renderUnknown, children }: NodeRendererProps = $props();
 
-  const entry = $derived(config.components[node.registration.componentTypeId]);
+  const entry = $derived(config.components[node.registration.componentId]);
   const componentConfig = $derived(entry ? normalizeComponentRegistration(entry) : null);
 
   const contentful: ContentfulComponent = {
-    componentTypeId: node.registration.componentTypeId,
+    componentId: node.registration.componentId,
     nodeId: node.nodeId,
     content: node.props.content,
     design: node.props.design,
@@ -52,7 +52,7 @@
     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.componentTypeId}": ${unresolved.join(', ')}. getDesignValues() will omit those keys.`
+        `[@contentful/experiences-svelte] resolveToken returned undefined for token id(s) on "${node.registration.componentId}": ${unresolved.join(', ')}. getDesignValues() will omit those keys.`
       );
     }
     return props;
@@ -77,7 +77,7 @@
 {:else}
   {@const Unknown = renderUnknown}
   <Unknown
-    componentTypeId={node.registration.componentTypeId}
+    componentId={node.registration.componentId}
     nodeId={node.nodeId}
   />
 {/if}

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;AAoEH,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

@@ -14,7 +14,7 @@
   import DebugExperience from './DebugExperience.svelte';
   import MissingComponent from './MissingComponent.svelte';
   import NodesRenderer from './NodesRenderer.svelte';
-  import WrapWithTemplate from './WrapWithTemplate.svelte';
+  import WrapWithExperienceTemplate from './WrapWithExperienceTemplate.svelte';
   import type { ServerExperienceRendererProps } from './component-props.js';
   import { setExperience } from './context.js';
   import type { RenderContext } from './types.js';
@@ -62,7 +62,7 @@
   {#if debug}
     <DebugExperience {experience} />
   {/if}
-  <WrapWithTemplate template={experience.template} {config} experience={renderContext}>
+  <WrapWithExperienceTemplate experienceTemplate={experience.experienceTemplate} {config} experience={renderContext}>
     {#snippet children()}
       <NodesRenderer
         nodes={experience.nodes}
@@ -71,5 +71,5 @@
         {renderUnknown}
       />
     {/snippet}
-  </WrapWithTemplate>
+  </WrapWithExperienceTemplate>
 {/if}

package/dist/WrapWithExperienceTemplate.svelte

@@ -0,0 +1,87 @@
+<!--
+ * Wraps the rendered Experience nodes with the page-level Experience Template when the
+ * plan carries one and the customer registered an Experience Template config under that
+ * id. When the Experience Template is referenced but unregistered, warns once and
+ * renders children unwrapped — graceful degradation matches the
+ * unknown-component fallback story.
+-->
+<script lang="ts">
+  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 {
+    normalizeExperienceTemplateRegistration,
+    type ContentfulExperienceTemplate,
+    type Config,
+    type RenderContext,
+  } from './types.js';
+
+  interface WrapWithExperienceTemplateProps {
+    experienceTemplate: PortableExperienceTemplate | undefined;
+    config: Config;
+    experience: RenderContext;
+    children: Snippet;
+  }
+
+  let { experienceTemplate, config, experience, children }: WrapWithExperienceTemplateProps = $props();
+
+  // setContext must run during synchronous component init — call once with
+  // the initial value (Experience Templates do not toggle on/off mid-mount).
+  if (experienceTemplate) {
+    setContentfulExperienceTemplate({
+      experienceTemplateId: experienceTemplate.experienceTemplateId,
+      content: experienceTemplate.props.content,
+      design: experienceTemplate.props.design,
+      resolved: experienceTemplate.props.resolved,
+    } satisfies ContentfulExperienceTemplate);
+  }
+
+  const entry = $derived(experienceTemplate ? config.experienceTemplates?.[experienceTemplate.experienceTemplateId] : undefined);
+  const experienceTemplateConfig = $derived(entry ? normalizeExperienceTemplateRegistration(entry) : null);
+
+  const tokenResolvedDesign = $derived.by(() => {
+    if (!experienceTemplate) return {};
+    const resolvedDesign = resolveDesignProperties(
+      experienceTemplate.props.design,
+      experience.viewports,
+      experience.activeViewportIndex
+    );
+    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.`
+      );
+    }
+    return props;
+  });
+
+  // A getter (not a snapshot) so getDesignValues() stays reactive; not merged into props.
+  setResolvedDesign(() => tokenResolvedDesign);
+
+  const composed = $derived.by(() => {
+    if (!experienceTemplate || !experienceTemplateConfig) return null;
+    return {
+      ...experienceTemplateConfig.defaults,
+      ...experienceTemplate.props.content,
+      ...experienceTemplate.props.resolved,
+    };
+  });
+
+  $effect(() => {
+    if (experienceTemplate && !experienceTemplateConfig && typeof console !== 'undefined') {
+      console.warn(
+        `[@contentful/experiences-svelte] No experience template registered for id "${experienceTemplate.experienceTemplateId}". Rendering nodes without the experience template wrapper.`
+      );
+    }
+  });
+</script>
+
+{#if experienceTemplate && experienceTemplateConfig && composed}
+  {@const Tpl = experienceTemplateConfig.component}
+  <Tpl {...composed} {children} />
+{:else}
+  {@render children()}
+{/if}

package/dist/WrapWithExperienceTemplate.svelte.d.ts

@@ -0,0 +1,13 @@
+import type { Snippet } from 'svelte';
+import type { PortableExperienceTemplate } from '@contentful/experiences-sdk-core';
+import { type Config, type RenderContext } from './types.js';
+interface WrapWithExperienceTemplateProps {
+    experienceTemplate: PortableExperienceTemplate | undefined;
+    config: Config;
+    experience: RenderContext;
+    children: Snippet;
+}
+declare const WrapWithExperienceTemplate: import("svelte").Component<WrapWithExperienceTemplateProps, {}, "">;
+type WrapWithExperienceTemplate = ReturnType<typeof WrapWithExperienceTemplate>;
+export default WrapWithExperienceTemplate;
+//# sourceMappingURL=WrapWithExperienceTemplate.svelte.d.ts.map

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

@@ -0,0 +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"}

package/dist/component-props.d.ts

@@ -20,7 +20,7 @@ export interface ServerExperienceRendererProps {
 }
 export type ClientExperienceRendererProps = ServerExperienceRendererProps;
 export interface MissingComponentProps {
-    componentTypeId: string;
+    componentId: string;
     /** Optional — only present when the payload supplied an id for this node. */
     nodeId?: string;
 }

package/dist/component-props.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"component-props.d.ts","sourceRoot":"","sources":["../src/component-props.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,QAAQ,CAAC;AAExC,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,kCAAkC,CAAC;AAE3E,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAEzC,MAAM,WAAW,6BAA6B;IAC5C,UAAU,EAAE,kBAAkB,GAAG,IAAI,GAAG,SAAS,CAAC;IAClD,MAAM,EAAE,MAAM,CAAC;IACf,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC;;;;OAIG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,aAAa,CAAC,EAAE,aAAa,CAAC;CAC/B;AAED,MAAM,MAAM,6BAA6B,GAAG,6BAA6B,CAAC;AAE1E,MAAM,WAAW,qBAAqB;IACpC,eAAe,EAAE,MAAM,CAAC;IACxB,6EAA6E;IAC7E,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,MAAM,aAAa,GAAG,SAAS,CAAC,qBAAqB,CAAC,CAAC;AAE7D,MAAM,WAAW,oBAAoB;IACnC,+EAA+E;IAC/E,UAAU,EAAE,kBAAkB,CAAC;IAC/B,oEAAoE;IACpE,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB"}
+{"version":3,"file":"component-props.d.ts","sourceRoot":"","sources":["../src/component-props.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,QAAQ,CAAC;AAExC,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,kCAAkC,CAAC;AAE3E,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAEzC,MAAM,WAAW,6BAA6B;IAC5C,UAAU,EAAE,kBAAkB,GAAG,IAAI,GAAG,SAAS,CAAC;IAClD,MAAM,EAAE,MAAM,CAAC;IACf,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC;;;;OAIG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,aAAa,CAAC,EAAE,aAAa,CAAC;CAC/B;AAED,MAAM,MAAM,6BAA6B,GAAG,6BAA6B,CAAC;AAE1E,MAAM,WAAW,qBAAqB;IACpC,WAAW,EAAE,MAAM,CAAC;IACpB,6EAA6E;IAC7E,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,MAAM,aAAa,GAAG,SAAS,CAAC,qBAAqB,CAAC,CAAC;AAE7D,MAAM,WAAW,oBAAoB;IACnC,+EAA+E;IAC/E,UAAU,EAAE,kBAAkB,CAAC;IAC/B,oEAAoE;IACpE,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB"}

package/dist/context.d.ts

@@ -1,19 +1,20 @@
-import type { ContentfulComponent, ContentfulTemplate, RenderContext } from './types.js';
+import type { ContentfulComponent, ContentfulExperienceTemplate, RenderContext } from './types.js';
 export declare function setExperience(ctx: RenderContext): void;
 export declare function setContentfulComponent(node: ContentfulComponent): void;
-export declare function setContentfulTemplate(tpl: ContentfulTemplate): void;
+export declare function setContentfulExperienceTemplate(tpl: ContentfulExperienceTemplate): void;
 /**
- * Publish the resolved design values for the enclosing node/template. Takes a
+ * Publish the resolved design values for the enclosing node or experience template. Takes a
  * getter (not a snapshot) so callers reading it inside a `$derived` stay
  * reactive across viewport changes.
  */
 export declare function setResolvedDesign(getDesign: () => Record<string, unknown>): void;
 export declare function getExperience(): RenderContext;
 export declare function getContentfulComponent(): ContentfulComponent | undefined;
-export declare function getContentfulTemplate(): ContentfulTemplate | undefined;
+export declare function getContentfulExperienceTemplate(): ContentfulExperienceTemplate | undefined;
 /**
  * Read the design values the renderer resolved for the enclosing node or
- * template. Returns `undefined` outside a rendered node/template, which
+ * experience template. Returns `undefined` outside a rendered node or
+ * experience template, which
  * `getDesignValues` treats as "nothing to read."
  */
 export declare function getResolvedDesign(): Record<string, unknown> | undefined;

package/dist/context.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AAoBA,OAAO,KAAK,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAOzF,wBAAgB,aAAa,CAAC,GAAG,EAAE,aAAa,GAAG,IAAI,CAEtD;AAED,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,mBAAmB,GAAG,IAAI,CAEtE;AAED,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,kBAAkB,GAAG,IAAI,CAEnE;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,MAAM,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAEhF;AAED,wBAAgB,aAAa,IAAI,aAAa,CAQ7C;AAED,wBAAgB,sBAAsB,IAAI,mBAAmB,GAAG,SAAS,CAExE;AAED,wBAAgB,qBAAqB,IAAI,kBAAkB,GAAG,SAAS,CAEtE;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAGvE"}
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AAoBA,OAAO,KAAK,EAAE,mBAAmB,EAAE,4BAA4B,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AASnG,wBAAgB,aAAa,CAAC,GAAG,EAAE,aAAa,GAAG,IAAI,CAEtD;AAED,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,mBAAmB,GAAG,IAAI,CAEtE;AAED,wBAAgB,+BAA+B,CAAC,GAAG,EAAE,4BAA4B,GAAG,IAAI,CAEvF;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,MAAM,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAEhF;AAED,wBAAgB,aAAa,IAAI,aAAa,CAQ7C;AAED,wBAAgB,sBAAsB,IAAI,mBAAmB,GAAG,SAAS,CAExE;AAED,wBAAgB,+BAA+B,IAAI,4BAA4B,GAAG,SAAS,CAE1F;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAGvE"}