@contentful/experiences-svelte 0.3.1

package/CHANGELOG.md

@@ -0,0 +1,52 @@
+## 0.3.1 (2026-07-17)
+
+### 🚀 Features
+
+- design-token resolution via resolveToken + useDesignValues [AIS-149] ([#53](https://github.com/contentful/experiences/pull/53))
+
+### 🧱 Updated Dependencies
+
+- Updated client to 0.1.1
+- Updated design to 0.5.1
+- Updated core to 0.5.1
+
+## 0.3.0 (2026-07-17)
+
+### 🚀 Features
+
+- add packages/client with fetchExperience and delivery client [AIS-147] ([#30](https://github.com/contentful/experiences/pull/30), [#27](https://github.com/contentful/experiences/issues/27))
+
+### 🧱 Updated Dependencies
+
+- Updated client to 0.1.0
+- Updated design to 0.5.0
+- Updated core to 0.5.0
+
+## 0.2.0 (2026-07-08)
+
+### 🚀 Features
+
+- idiomatic adapters — bare components + context hooks ([0365bfb](https://github.com/contentful/experiences/commit/0365bfb))
+
+### 🧱 Updated Dependencies
+
+- Updated design to 0.4.0
+- Updated core to 0.4.0
+
+## 0.1.0 (2026-06-24)
+
+### 🚀 Features
+
+- more-robust examples + simple/advanced README split + contentful prop ([#18](https://github.com/contentful/experiences/pull/18))
+
+### 🧱 Updated Dependencies
+
+- Updated design to 0.3.0
+- Updated core to 0.3.0
+
+## 0.0.1 (2026-06-24)
+
+### 🧱 Updated Dependencies
+
+- Updated design to 0.2.0
+- Updated core to 0.2.0

package/README.md

@@ -0,0 +1,107 @@
+# @contentful/experiences-svelte
+
+> ⚠️ **Pre-alpha.** Not yet published to npm. APIs are unstable and will change.
+
+The Svelte adapter for the Contentful Experiences SDK suite. Renders Experience payloads from the Experience Delivery API (XDA) using customer-supplied Svelte 5 components.
+
+```sh
+npm install @contentful/experiences-svelte @contentful/experience-delivery
+```
+
+This is the **only SDK package customers install** — it re-exports everything from `@contentful/experiences-core` and `@contentful/experiences-design` that consumers need. The other packages are workspace-internal.
+
+The public API mirrors `@contentful/experiences-react` 1:1 in shape; only the rendering primitives change (`component: SvelteComponent` instead of `render: () => ReactNode`, Snippets instead of `children: ReactNode`).
+
+---
+
+## Public API
+
+### Authoring
+
+```ts
+defineComponent<Props>(config); // Type-narrowing identity for component-type configs
+defineTemplate<Props>(config); // Same shape, for page-level template wrappers
+```
+
+### Resolver
+
+```ts
+resolveExperience(payload, config, opts?); // Async — walks payload, runs resolveData, returns a PortableRenderPlan
+```
+
+### Renderers
+
+```ts
+ServerExperienceRenderer; // SSR-safe; active viewport seeded from initialViewportId
+ClientExperienceRenderer; // Subscribes to window.matchMedia via runes
+MissingComponent; // Default fallback for unregistered component types
+useActiveViewport; // Rune-backed reactive object; rarely needed by consumers
+```
+
+### Re-exported types and utilities
+
+```ts
+// From core
+type Config, Components, Templates,
+type ComponentConfig, TemplateConfig,
+type ComponentProps, TemplateProps,
+type RenderContext,
+type ExperiencePayload, ExperienceNode, ComponentTypeNode, TemplateNode,
+type PortableRenderPlan, PortableRenderNode, PortableTemplate,
+type DesignPropValue, ManualDesignValue, DesignToken, ValuesByViewport,
+type ViewportDef, ExperienceContext, ResolveContext,
+type ResolverConfig, ResolveExperienceOptions
+
+// From design (for customers who want to do their own viewport-aware resolution)
+getValueForViewport, getViewportIndex, resolveDesignProperties, toCssMediaQuery
+```
+
+---
+
+## Quick reference
+
+```svelte
+<!-- Button.svelte -->
+<script lang="ts">
+  let { text = 'Button', url, type = 'primary' }: ButtonProps = $props();
+</script>
+{#if url}
+  <a href={url}>{text}</a>
+{:else}
+  <button type="button">{text}</button>
+{/if}
+```
+
+```ts
+// experience-config.ts
+import { defineComponent, type Config, type Components } from '@contentful/experiences-svelte';
+import Button from './components/Button.svelte';
+import type { ButtonProps } from './components/Button.svelte';
+
+const components: Components = {
+  button: defineComponent<ButtonProps>({
+    defaults: { type: 'primary' },
+    resolveData: ({ content }) => ({ url: ensureScheme(content.url) }),
+    component: Button,
+  }),
+};
+
+export const experienceConfig: Config = { components };
+```
+
+```svelte
+<!-- +page.svelte -->
+<script lang="ts">
+  import { ServerExperienceRenderer } from '@contentful/experiences-svelte';
+  let { data } = $props();
+</script>
+<ServerExperienceRenderer experience={data.experience} config={experienceConfig} />
+```
+
+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).
+
+---
+
+## License
+
+MIT. See the repository [`LICENSE`](../../LICENSE) and [`NOTICE`](../../NOTICE) for full attribution.

package/dist/ClientExperienceRenderer.svelte

@@ -0,0 +1,81 @@
+<!--
+ * Client Experience renderer. First paint matches the server renderer
+ * (active viewport resolved from `initialViewportId`); after hydration,
+ * `useActiveViewport` takes over via `window.matchMedia` and re-renders
+ * when the viewport changes.
+ *
+ * Safe to render on the server: `useActiveViewport` no-ops outside the
+ * browser, so SSR output matches `<ServerExperienceRenderer>` given the
+ * same seed.
+-->
+<script lang="ts">
+  import type { ExperienceContext, ViewportDef } from '@contentful/experiences-core';
+
+  import MissingComponent from './MissingComponent.svelte';
+  import NodesRenderer from './NodesRenderer.svelte';
+  import WrapWithTemplate from './WrapWithTemplate.svelte';
+  import type { ClientExperienceRendererProps } from './component-props.js';
+  import { setExperience } from './context.js';
+  import type { RenderContext } from './types.js';
+  import { useActiveViewport } from './use-active-viewport.svelte.js';
+
+  const DEFAULT_CONTEXT: ExperienceContext = {
+    isPreview: false,
+    metadata: {},
+    viewports: [],
+  };
+
+  const FALLBACK_VIEWPORT: ViewportDef = {
+    id: '_',
+    query: '*',
+    displayName: 'Default',
+    previewSize: '100%',
+  };
+
+  let {
+    experience,
+    config,
+    initialViewportId,
+    context,
+    renderUnknown = MissingComponent,
+  }: ClientExperienceRendererProps = $props();
+
+  const viewports = $derived(experience?.viewports ?? []);
+  const tracker = useActiveViewport(viewports, initialViewportId);
+
+  // A $state-backed mirror so descendants reading getExperience() stay
+  // reactive across viewport changes. The fields update in an $effect below.
+  const liveContext = $state<RenderContext>({
+    ...DEFAULT_CONTEXT,
+    ...context,
+    metadata: { ...DEFAULT_CONTEXT.metadata, ...(context?.metadata ?? {}) },
+    viewports: experience?.viewports ?? [],
+    activeViewport: experience?.viewports[0] ?? FALLBACK_VIEWPORT,
+    activeViewportIndex: 0,
+  });
+
+  setExperience(liveContext);
+
+  $effect(() => {
+    if (!experience) return;
+    const idx = tracker.activeViewportIndex;
+    liveContext.viewports = experience.viewports;
+    liveContext.activeViewport = experience.viewports[idx] ?? FALLBACK_VIEWPORT;
+    liveContext.activeViewportIndex = idx;
+    liveContext.isPreview = context?.isPreview ?? false;
+    liveContext.metadata = { ...DEFAULT_CONTEXT.metadata, ...(context?.metadata ?? {}) };
+  });
+</script>
+
+{#if experience}
+  <WrapWithTemplate template={experience.template} {config} experience={liveContext}>
+    {#snippet children()}
+      <NodesRenderer
+        nodes={experience.nodes}
+        {config}
+        experience={liveContext}
+        {renderUnknown}
+      />
+    {/snippet}
+  </WrapWithTemplate>
+{/if}

package/dist/ClientExperienceRenderer.svelte.d.ts

@@ -0,0 +1,4 @@
+declare const ClientExperienceRenderer: import("svelte").Component<import("./component-props.js").ServerExperienceRendererProps, {}, "">;
+type ClientExperienceRenderer = ReturnType<typeof ClientExperienceRenderer>;
+export default ClientExperienceRenderer;
+//# sourceMappingURL=ClientExperienceRenderer.svelte.d.ts.map

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

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

package/dist/MissingComponent.svelte

@@ -0,0 +1,35 @@
+<!--
+ * Default fallback rendered when an instance references a component type
+ * not present in the Config.
+ *
+ * Behavior: a visible red error box in preview, silent null in production.
+ * Customers can override per-render via <ServerExperienceRenderer renderUnknown=... />.
+-->
+<script lang="ts">
+  import type { MissingComponentProps } from './component-props.js';
+  import { getExperience } from './context.js';
+
+  let { componentTypeId, 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}.`
+      );
+    }
+  });
+</script>
+
+{#if experience.isPreview}
+  <div
+    style="border: 2px solid red; padding: 1rem; color: red; background: #fff;"
+    data-experiences-missing={componentTypeId}
+  >
+    <strong>Missing component &lsquo;{componentTypeId}&rsquo;</strong>
+    <p>
+      This component is referenced by the Experience payload but is not registered in the Config.
+    </p>
+  </div>
+{/if}

package/dist/MissingComponent.svelte.d.ts

@@ -0,0 +1,5 @@
+import type { MissingComponentProps } from './component-props.js';
+declare const MissingComponent: import("svelte").Component<MissingComponentProps, {}, "">;
+type MissingComponent = ReturnType<typeof MissingComponent>;
+export default MissingComponent;
+//# sourceMappingURL=MissingComponent.svelte.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"MissingComponent.svelte.d.ts","sourceRoot":"","sources":["../src/MissingComponent.svelte.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAgClE,QAAA,MAAM,gBAAgB,2DAAwC,CAAC;AAC/D,KAAK,gBAAgB,GAAG,UAAU,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAC5D,eAAe,gBAAgB,CAAC"}

package/dist/NodeRenderer.svelte

@@ -0,0 +1,83 @@
+<!--
+ * Single-node renderer. Splits out of NodesRenderer so the per-node
+ * `setContext` for the contentful payload happens during *that node's*
+ * component init (Svelte's setContext can only be called at top level).
+-->
+<script lang="ts">
+  import type { Snippet } from 'svelte';
+
+  import type { PortableRenderNode } from '@contentful/experiences-core';
+  import { applyTokenResolver, resolveDesignProperties } from '@contentful/experiences-design';
+
+  import { setContentfulComponent, setResolvedDesign } from './context.js';
+  import type { RenderUnknown } from './component-props.js';
+  import {
+    normalizeComponentRegistration,
+    type ContentfulComponent,
+    type Config,
+    type RenderContext,
+  } from './types.js';
+
+  interface NodeRendererProps {
+    node: PortableRenderNode;
+    config: Config;
+    experience: RenderContext;
+    renderUnknown: RenderUnknown;
+    children: Snippet;
+  }
+
+  let { node, config, experience, renderUnknown, children }: NodeRendererProps = $props();
+
+  const entry = $derived(config.components[node.registration.componentTypeId]);
+  const componentConfig = $derived(entry ? normalizeComponentRegistration(entry) : null);
+
+  const contentful: ContentfulComponent = {
+    componentTypeId: node.registration.componentTypeId,
+    nodeId: node.nodeId,
+    content: node.props.content,
+    design: node.props.design,
+    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,
+      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 "${node.registration.componentTypeId}": ${unresolved.join(', ')}. getDesignValues() will omit those keys.`
+      );
+    }
+    return props;
+  });
+
+  setResolvedDesign(() => tokenResolvedDesign);
+
+  const composed = $derived.by(() => {
+    if (!componentConfig) return null;
+    return {
+      ...componentConfig.defaults,
+      ...node.props.content,
+      ...node.props.resolved,
+      children,
+    };
+  });
+</script>
+
+{#if componentConfig && composed}
+  {@const Cmp = componentConfig.component}
+  <Cmp {...composed} />
+{:else}
+  {@const Unknown = renderUnknown}
+  <Unknown
+    componentTypeId={node.registration.componentTypeId}
+    nodeId={node.nodeId}
+  />
+{/if}

package/dist/NodeRenderer.svelte.d.ts

@@ -0,0 +1,15 @@
+import type { Snippet } from 'svelte';
+import type { PortableRenderNode } from '@contentful/experiences-core';
+import type { RenderUnknown } from './component-props.js';
+import { type Config, type RenderContext } from './types.js';
+interface NodeRendererProps {
+    node: PortableRenderNode;
+    config: Config;
+    experience: RenderContext;
+    renderUnknown: RenderUnknown;
+    children: Snippet;
+}
+declare const NodeRenderer: import("svelte").Component<NodeRendererProps, {}, "">;
+type NodeRenderer = ReturnType<typeof NodeRenderer>;
+export default NodeRenderer;
+//# sourceMappingURL=NodeRenderer.svelte.d.ts.map

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

@@ -0,0 +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,8BAA8B,CAAC;AAIvE,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"}

package/dist/NodesRenderer.svelte

@@ -0,0 +1,51 @@
+<!--
+ * Recursive renderer over PortableRenderNodes. Customer components receive
+ * the merged content / design / resolveData prop bag plus the default
+ * `children` slot as a named Snippet:
+ *
+ *     <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).
+ *
+ * The Experience runtime context and the raw Contentful payload are read
+ * via `getExperience` / `getContentfulComponent`.
+ *
+ * Server vs client variants share this component; they differ only in how
+ * the active viewport is sourced (initial seed vs reactive matchMedia).
+-->
+<script lang="ts">
+  import type { PortableRenderNode } from '@contentful/experiences-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';
+
+  interface NodesRendererProps {
+    nodes: PortableRenderNode[];
+    config: Config;
+    experience: RenderContext;
+    renderUnknown: RenderUnknown;
+  }
+
+  let { nodes, config, experience, renderUnknown }: NodesRendererProps = $props();
+</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}
+  <NodeRenderer {node} {config} {experience} {renderUnknown} {children} />
+{/each}

package/dist/NodesRenderer.svelte.d.ts

@@ -0,0 +1,14 @@
+import type { PortableRenderNode } from '@contentful/experiences-core';
+import NodesRenderer from './NodesRenderer.svelte';
+import type { RenderUnknown } from './component-props.js';
+import type { Config, RenderContext } from './types.js';
+interface NodesRendererProps {
+    nodes: PortableRenderNode[];
+    config: Config;
+    experience: RenderContext;
+    renderUnknown: RenderUnknown;
+}
+declare const NodesRenderer: import("svelte").Component<NodesRendererProps, {}, "">;
+type NodesRenderer = ReturnType<typeof NodesRenderer>;
+export default NodesRenderer;
+//# sourceMappingURL=NodesRenderer.svelte.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"NodesRenderer.svelte.d.ts","sourceRoot":"","sources":["../src/NodesRenderer.svelte.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,8BAA8B,CAAC;AAGvE,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"}

package/dist/ServerExperienceRenderer.svelte

@@ -0,0 +1,70 @@
+<!--
+ * Server-safe Experience renderer. Resolves the active viewport once from
+ * `initialViewportId` (typically derived from User-Agent on the request)
+ * and renders without any reactive subscription. SSR-friendly.
+ *
+ * SSR + interactive editor mode are mutually exclusive — the message-event
+ * preview client requires window listeners and lives only in the client
+ * renderer. For editor mode, render the client variant on a hydrated route.
+-->
+<script lang="ts">
+  import type { ExperienceContext, ViewportDef } from '@contentful/experiences-core';
+  import { getViewportIndex } from '@contentful/experiences-design';
+
+  import MissingComponent from './MissingComponent.svelte';
+  import NodesRenderer from './NodesRenderer.svelte';
+  import WrapWithTemplate from './WrapWithTemplate.svelte';
+  import type { ServerExperienceRendererProps } from './component-props.js';
+  import { setExperience } from './context.js';
+  import type { RenderContext } from './types.js';
+
+  const DEFAULT_CONTEXT: ExperienceContext = {
+    isPreview: false,
+    metadata: {},
+    viewports: [],
+  };
+
+  const FALLBACK_VIEWPORT: ViewportDef = {
+    id: '_',
+    query: '*',
+    displayName: 'Default',
+    previewSize: '100%',
+  };
+
+  let {
+    experience,
+    config,
+    initialViewportId,
+    context,
+    renderUnknown = MissingComponent,
+  }: ServerExperienceRendererProps = $props();
+
+  function buildContext(): RenderContext {
+    const viewports = experience?.viewports ?? [];
+    const idx = experience ? getViewportIndex(experience.viewports, initialViewportId) : 0;
+    return {
+      ...DEFAULT_CONTEXT,
+      ...context,
+      metadata: { ...DEFAULT_CONTEXT.metadata, ...(context?.metadata ?? {}) },
+      viewports,
+      activeViewport: experience?.viewports[idx] ?? FALLBACK_VIEWPORT,
+      activeViewportIndex: idx,
+    };
+  }
+
+  const renderContext = buildContext();
+  setExperience(renderContext);
+</script>
+
+{#if experience}
+  <WrapWithTemplate template={experience.template} {config} experience={renderContext}>
+    {#snippet children()}
+      <NodesRenderer
+        nodes={experience.nodes}
+        {config}
+        experience={renderContext}
+        {renderUnknown}
+      />
+    {/snippet}
+  </WrapWithTemplate>
+{/if}

package/dist/ServerExperienceRenderer.svelte.d.ts

@@ -0,0 +1,5 @@
+import type { ServerExperienceRendererProps } from './component-props.js';
+declare const ServerExperienceRenderer: import("svelte").Component<ServerExperienceRendererProps, {}, "">;
+type ServerExperienceRenderer = ReturnType<typeof ServerExperienceRenderer>;
+export default ServerExperienceRenderer;
+//# sourceMappingURL=ServerExperienceRenderer.svelte.d.ts.map

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

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

package/dist/WrapWithTemplate.svelte

@@ -0,0 +1,87 @@
+<!--
+ * Wraps the rendered Experience nodes with the page-level template when the
+ * plan carries one and the customer registered a template config under that
+ * id. When the 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 { PortableTemplate } from '@contentful/experiences-core';
+  import { applyTokenResolver, resolveDesignProperties } from '@contentful/experiences-design';
+
+  import { setContentfulTemplate, setResolvedDesign } from './context.js';
+  import {
+    normalizeTemplateRegistration,
+    type ContentfulTemplate,
+    type Config,
+    type RenderContext,
+  } from './types.js';
+
+  interface WrapWithTemplateProps {
+    template: PortableTemplate | undefined;
+    config: Config;
+    experience: RenderContext;
+    children: Snippet;
+  }
+
+  let { template, config, experience, children }: WrapWithTemplateProps = $props();
+
+  // setContext must run during synchronous component init — call once with
+  // the initial template value (templates don't toggle on/off mid-mount).
+  if (template) {
+    setContentfulTemplate({
+      templateId: template.templateId,
+      content: template.props.content,
+      design: template.props.design,
+      resolved: template.props.resolved,
+    } satisfies ContentfulTemplate);
+  }
+
+  const entry = $derived(template ? config.templates?.[template.templateId] : undefined);
+  const templateConfig = $derived(entry ? normalizeTemplateRegistration(entry) : null);
+
+  const tokenResolvedDesign = $derived.by(() => {
+    if (!template) return {};
+    const resolvedDesign = resolveDesignProperties(
+      template.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 template "${template.templateId}": ${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 (!template || !templateConfig) return null;
+    return {
+      ...templateConfig.defaults,
+      ...template.props.content,
+      ...template.props.resolved,
+    };
+  });
+
+  $effect(() => {
+    if (template && !templateConfig && typeof console !== 'undefined') {
+      console.warn(
+        `[@contentful/experiences-svelte] No template registered for id "${template.templateId}". Rendering nodes without the template wrapper.`
+      );
+    }
+  });
+</script>
+
+{#if template && templateConfig && composed}
+  {@const Tpl = templateConfig.component}
+  <Tpl {...composed} {children} />
+{:else}
+  {@render children()}
+{/if}

package/dist/WrapWithTemplate.svelte.d.ts

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"WrapWithTemplate.svelte.d.ts","sourceRoot":"","sources":["../src/WrapWithTemplate.svelte.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAC;AAEtC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AAIrE,OAAO,EAGH,KAAK,MAAM,EACX,KAAK,aAAa,EACnB,MAAM,YAAY,CAAC;AAGpB,UAAU,qBAAqB;IAC7B,QAAQ,EAAE,gBAAgB,GAAG,SAAS,CAAC;IACvC,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,aAAa,CAAC;IAC1B,QAAQ,EAAE,OAAO,CAAC;CACnB;AA0EH,QAAA,MAAM,gBAAgB,2DAAwC,CAAC;AAC/D,KAAK,gBAAgB,GAAG,UAAU,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAC5D,eAAe,gBAAgB,CAAC"}