@contentful/experiences-svelte 0.5.10 → 0.5.12

package/CHANGELOG.md

@@ -1,3 +1,23 @@
+## 0.5.12 (2026-08-28)
+
+### 🚀 Features
+
+- error handling and sensible fallbacks for non-happy-path rendering [AIS-364] ([#156](https://github.com/contentful/experiences/pull/156))
+
+### 🧱 Updated Dependencies
+
+- Updated client to 0.3.11
+- Updated design to 0.7.11
+- Updated core to 0.7.11
+
+## 0.5.11 (2026-08-27)
+
+### 🧱 Updated Dependencies
+
+- Updated client to 0.3.10
+- Updated design to 0.7.10
+- Updated core to 0.7.10
+
 ## 0.5.10 (2026-08-26)
 
 ### 🧱 Updated Dependencies

package/dist/ClientExperienceRenderer.svelte

@@ -11,6 +11,7 @@
 <script lang="ts">
   import type { ExperienceContext, ViewportDef } from '@contentful/experiences-sdk-core';
 
+  import ComponentError from './ComponentError.svelte';
   import DebugExperience from './DebugExperience.svelte';
   import MissingComponent from './MissingComponent.svelte';
   import NodesRenderer from './NodesRenderer.svelte';
@@ -39,8 +40,33 @@
     metadata,
     debug = false,
     renderUnknown = MissingComponent,
+    renderError = ComponentError,
   }: ClientExperienceRendererProps = $props();
 
+  // Render-time diagnostics, `$state`-backed so a component that throws well
+  // after first paint (a later re-render, an event handler) still makes
+  // `<DebugExperience>` re-render with the new diagnostic — a mutated plain
+  // array wouldn't be reactive here the way it's fine to be for the
+  // synchronous, single-pass server renderer.
+  //
+  // `queueMicrotask` defers the actual mutation: most of these diagnostics
+  // (component-not-registered, malformed-slot,
+  // experience-template-not-registered) are reported from NodeRenderer's
+  // `{@const}`/`$derived.by` blocks — i.e. from inside a template expression
+  // — and Svelte 5 forbids mutating `$state` there directly
+  // ("state_unsafe_mutation"). Escaping to a microtask (same "break the
+  // synchronous call chain" rationale as core's resolveData deferral)
+  // performs the mutation once that expression has finished evaluating.
+  // `component-render-error`, reported from `<svelte:boundary onerror>`
+  // (already outside any derived/template evaluation), is unaffected by the
+  // restriction but deferred too, to keep one code path.
+  const renderDiagnostics = $state<Error[]>([]);
+  function onDiagnostic(error: Error): void {
+    queueMicrotask(() => {
+      renderDiagnostics.push(error);
+    });
+  }
+
   const viewports = $derived(experience?.viewports ?? []);
   const tracker = useActiveViewport(viewports, initialViewportId);
 
@@ -71,13 +97,18 @@
 </script>
 
 {#if experience}
-  {#if debug}
-    <DebugExperience {experience} />
-  {/if}
   <NodesRenderer
     nodes={experience.nodes}
     {config}
     experience={liveContext}
     {renderUnknown}
+    {renderError}
+    {onDiagnostic}
   />
+  {#if debug}
+    <DebugExperience
+      {experience}
+      errors={[...(experience.diagnostics ?? []), ...renderDiagnostics]}
+    />
+  {/if}
 {/if}

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

@@ -1 +1 @@
-{"version":3,"file":"ClientExperienceRenderer.svelte.d.ts","sourceRoot":"","sources":["../src/ClientExperienceRenderer.svelte.ts"],"names":[],"mappings":"AAqFA,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":"AAgHA,QAAA,MAAM,wBAAwB,kGAAwC,CAAC;AACvE,KAAK,wBAAwB,GAAG,UAAU,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAC5E,eAAe,wBAAwB,CAAC"}

package/dist/ComponentError.svelte

@@ -0,0 +1,35 @@
+<!--
+ * Default fallback rendered when a registered component throws while
+ * rendering. Sibling of `MissingComponent` — same debug-gated behavior
+ * (visible box in debug mode, silent null otherwise), visually distinct
+ * (different color/label) so a customer can tell "not registered" apart
+ * from "registered but threw" at a glance. The diagnostic + console.warn
+ * for this failure mode are recorded once, at the `<svelte:boundary>` call
+ * site in `NodeRenderer.svelte` — not here — so they still fire even when a
+ * customer overrides `renderError` with their own fallback.
+-->
+<script lang="ts">
+  import type { ComponentErrorProps } from './component-props.js';
+  import { getExperience } from './context.js';
+
+  let { componentId, nodeId, message }: ComponentErrorProps = $props();
+  const experience = getExperience();
+</script>
+
+{#if experience.debug}
+  <div
+    style="border: 2px solid #b91c1c; padding: 1rem; color: #b91c1c; background: #fff; font-family: ui-monospace, SFMono-Regular, Menlo, monospace; font-size: 0.8125rem;"
+    data-experiences-render-error={componentId}
+  >
+    <strong>Component &lsquo;{componentId}&rsquo; threw while rendering</strong>
+    <p style="margin: 0.5rem 0;">
+      This component is registered but threw during render. Rendering this fallback instead of
+      crashing the surrounding tree.
+    </p>
+    <pre style="margin: 0; white-space: pre-wrap;">{JSON.stringify(
+        { componentId, nodeId: nodeId ?? null, message: message ?? null },
+        null,
+        2
+      )}</pre>
+  </div>
+{/if}

package/dist/ComponentError.svelte.d.ts

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"ComponentError.svelte.d.ts","sourceRoot":"","sources":["../src/ComponentError.svelte.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AA6BhE,QAAA,MAAM,cAAc,yDAAwC,CAAC;AAC7D,KAAK,cAAc,GAAG,UAAU,CAAC,OAAO,cAAc,CAAC,CAAC;AACxD,eAAe,cAAc,CAAC"}

package/dist/DebugExperience.svelte

@@ -14,7 +14,12 @@
 <script lang="ts">
   import type { DebugExperienceProps } from './component-props.js';
 
-  let { experience, defaultOpen = false }: DebugExperienceProps = $props();
+  let { experience, defaultOpen = false, errors = [] }: DebugExperienceProps = $props();
+
+  // Auto-expand whenever there's something to see, even if the caller didn't
+  // explicitly ask — a beta customer shouldn't have to know to click into a
+  // collapsed panel to discover that something went wrong.
+  const open = $derived(defaultOpen || errors.length > 0);
 
   const nodeCount = $derived(experience.nodes.length);
   // Coded Experience Templates are ordinary top-level nodes, so name them from
@@ -52,7 +57,12 @@
         2
       );
     } catch (err) {
-      return `[DebugExperience: could not serialize plan — ${(err as Error).message}]`;
+      // `err` isn't guaranteed to be an Error — a getter deep in customer data
+      // (a resolveData result, resolved design values) can `throw null` or
+      // `throw 'reason'` during JSON.stringify's replacer walk, and this
+      // fallback's whole job is to never throw itself.
+      const reason = err instanceof Error ? err.message : String(err);
+      return `[DebugExperience: could not serialize plan — ${reason}]`;
     }
   }
 
@@ -60,7 +70,7 @@
 </script>
 
 <details
-  open={defaultOpen}
+  {open}
   data-experiences-debug
   style="margin: 1rem 0; border: 1px solid #6b7280; border-radius: 6px; background: #0b1021; color: #e2e8f0; font-family: ui-monospace, SFMono-Regular, Menlo, monospace; font-size: 0.75rem; overflow: hidden;"
 >
@@ -69,6 +79,15 @@
   >
     {summary}
   </summary>
+  {#if errors.length > 0}
+    <!-- Deliberately unstyled for now — this just needs to make the data
+         visible, not console-only. Visual treatment can grow later. -->
+    <ul data-experiences-debug-errors>
+      {#each errors as error, index (index)}
+        <li>{error.message}</li>
+      {/each}
+    </ul>
+  {/if}
   <pre
     style="margin: 0; padding: 0.75rem; overflow: auto; max-height: 32rem; white-space: pre-wrap; word-break: break-word;">{json}</pre>
 </details>

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;AA4DjE,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;AA8EjE,QAAA,MAAM,eAAe,0DAAwC,CAAC;AAC9D,KAAK,eAAe,GAAG,UAAU,CAAC,OAAO,eAAe,CAAC,CAAC;AAC1D,eAAe,eAAe,CAAC"}

package/dist/DebugExperience.test.js

@@ -1,7 +1,12 @@
 import { render } from '@testing-library/svelte';
 import { describe, expect, it } from 'vitest';
 import DebugExperience from './DebugExperience.svelte';
-const emptyPlan = { nodes: [], viewports: [], fallbackViewportIndex: 0 };
+const emptyPlan = {
+    nodes: [],
+    viewports: [],
+    fallbackViewportIndex: 0,
+    diagnostics: [],
+};
 function node(id, content = {}) {
     return {
         registration: { kind: 'component', id },
@@ -36,6 +41,7 @@ describe('DebugExperience.svelte', () => {
             viewports: [],
             nodes: [node('button')],
             fallbackViewportIndex: 0,
+            diagnostics: [],
         };
         const { container } = render(DebugExperience, { props: { experience: one } });
         expect(container.innerHTML).toContain('Experience debug — 1 top-level node');
@@ -45,6 +51,7 @@ describe('DebugExperience.svelte', () => {
             viewports: [],
             nodes: [templateNode('page')],
             fallbackViewportIndex: 0,
+            diagnostics: [],
         };
         const { container } = render(DebugExperience, { props: { experience: plan } });
         expect(container.innerHTML).toContain('experience template: page');
@@ -54,6 +61,7 @@ describe('DebugExperience.svelte', () => {
             viewports: [],
             nodes: [node('button'), node('text')],
             fallbackViewportIndex: 0,
+            diagnostics: [],
         };
         const { container } = render(DebugExperience, { props: { experience: plan } });
         expect(container.innerHTML).toContain('Experience debug — 2 top-level nodes');
@@ -64,6 +72,7 @@ describe('DebugExperience.svelte', () => {
             viewports: [],
             nodes: [node('button', { label: 'Go' })],
             fallbackViewportIndex: 0,
+            diagnostics: [],
         };
         const { container } = render(DebugExperience, { props: { experience: plan } });
         expect(container.innerHTML).toContain('registration');
@@ -73,9 +82,60 @@ 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], fallbackViewportIndex: 0 };
+        const plan = {
+            viewports: [],
+            nodes: [n],
+            fallbackViewportIndex: 0,
+            diagnostics: [],
+        };
         expect(() => render(DebugExperience, { props: { experience: plan } })).not.toThrow();
         const { container } = render(DebugExperience, { props: { experience: plan } });
         expect(container.innerHTML).toContain('[Circular]');
     });
+    it('degrades a non-Error throw during serialization to a placeholder instead of crashing', () => {
+        const n = node('button');
+        // A customer's resolveData (or resolved design value) could stash a
+        // getter that throws a non-Error — a bare `throw null`/`throw 'reason'`
+        // rather than `throw new Error(...)`. JSON.stringify's replacer walk
+        // invokes it, and the safety net's job is to never throw itself either.
+        Object.defineProperty(n.props.resolved ?? (n.props.resolved = {}), 'poison', {
+            enumerable: true,
+            get() {
+                throw null;
+            },
+        });
+        const plan = {
+            viewports: [],
+            nodes: [n],
+            fallbackViewportIndex: 0,
+            diagnostics: [],
+        };
+        expect(() => render(DebugExperience, { props: { experience: plan } })).not.toThrow();
+        const { container } = render(DebugExperience, { props: { experience: plan } });
+        expect(container.innerHTML).toContain('could not serialize plan');
+    });
+});
+describe('DebugExperience.svelte — errors prop', () => {
+    const warning = new Error('No component registered for id "hero".');
+    const error = new Error('Component "card" threw while rendering: boom.');
+    it('stays collapsed and renders no error list when errors is empty or omitted', () => {
+        const { container } = render(DebugExperience, { props: { experience: emptyPlan } });
+        expect(container.querySelector('details').open).toBe(false);
+        expect(container.querySelector('[data-experiences-debug-errors]')).toBeNull();
+    });
+    it('auto-expands even without defaultOpen when there are errors', () => {
+        const { container } = render(DebugExperience, {
+            props: { experience: emptyPlan, errors: [warning] },
+        });
+        expect(container.querySelector('details').open).toBe(true);
+    });
+    it('renders a diagnostic list above the JSON dump', () => {
+        const { container } = render(DebugExperience, {
+            props: { experience: emptyPlan, errors: [warning, error] },
+        });
+        expect(container.querySelector('[data-experiences-debug-errors]')).not.toBeNull();
+        expect(container.innerHTML).toContain('No component registered for id "hero".');
+        expect(container.innerHTML).toContain('Component "card" threw while rendering: boom.');
+        expect(container.innerHTML.indexOf('data-experiences-debug-errors')).toBeLessThan(container.innerHTML.indexOf('<pre'));
+    });
 });

package/dist/NodeRenderer.svelte

@@ -19,7 +19,7 @@
     setContentfulExperienceTemplate,
     setResolvedDesign,
   } from './context.js';
-  import type { RenderUnknown } from './component-props.js';
+  import type { DiagnosticReporter, RenderError, RenderUnknown } from './component-props.js';
   import {
     normalizeComponentRegistration,
     normalizeExperienceTemplateRegistration,
@@ -34,6 +34,8 @@
     config: Config;
     experience: RenderContext;
     renderUnknown: RenderUnknown;
+    renderError: RenderError;
+    onDiagnostic: DiagnosticReporter;
     /**
      * Pre-rendered slot children keyed by slot name — one zero-arg Snippet per
      * child node. Spread onto the customer component as named props, so a slot
@@ -42,11 +44,33 @@
     slotSnippets: Record<string, Snippet[]>;
   }
 
-  let { node, config, experience, renderUnknown, slotSnippets }: NodeRendererProps = $props();
+  let {
+    node,
+    config,
+    experience,
+    renderUnknown,
+    renderError,
+    onDiagnostic,
+    slotSnippets,
+  }: NodeRendererProps = $props();
 
   const { kind, id } = node.registration;
   const isExperienceTemplate = kind === 'experienceTemplate';
 
+  // Any reactive re-run of this component's `$derived`/`{@const}` blocks
+  // (e.g. an ancestor's viewport change) would otherwise re-report the same
+  // diagnostic every time — matches Angular's `lastDiagnostics` guard in
+  // NodeRenderEngine and React's equivalent in NodeRenderer. `reported` is a
+  // plain (non-reactive) binding, stable for this component instance's
+  // lifetime — mutating it doesn't itself trigger reactivity, it's purely a
+  // guard for calls this component makes.
+  const reported = new Set<string>();
+  function reportOnce(error: Error): void {
+    if (reported.has(error.message)) return;
+    reported.add(error.message);
+    onDiagnostic(error);
+  }
+
   const entry = $derived(
     isExperienceTemplate ? config.experienceTemplates?.[id] : config.components[id]
   );
@@ -113,23 +137,55 @@
   // unwrapped — the content survives, the diagnostic names what's missing.
   const orphanedSnippets = $derived.by(() => {
     if (componentConfig || !isExperienceTemplate) return null;
+    const message = `No experience template registered for id "${id}". Rendering its slot children without the experience template wrapper.`;
     if (typeof console !== 'undefined') {
-      console.warn(
-        `[@contentful/experiences-svelte] No experience template registered for id "${id}". Rendering its slot children without the experience template wrapper.`
-      );
+      console.warn(`[@contentful/experiences-svelte] ${message}`);
     }
+    reportOnce(new Error(message));
     return Object.values(slotSnippets).flat();
   });
+
+  // `MissingComponent` (the default `renderUnknown`) does its own
+  // console.warn via an `$effect`; a custom override may not, so the
+  // diagnostic is recorded here regardless of which fallback ends up
+  // rendering.
+  function reportMissingComponent(): true {
+    const message = `No component registered for id "${id}"${node.nodeId ? ` (nodeId: ${node.nodeId})` : ''}.`;
+    reportOnce(new Error(message));
+    return true;
+  }
+
+  // Reported from `<svelte:boundary onerror={...}>` when the customer's
+  // component throws during render. See the README's error-handling section
+  // for the SSR/CSR asymmetry: `<svelte:boundary>` only catches client-side —
+  // a throw during SvelteKit's server render still fails the whole render.
+  function reportRenderError(error: unknown): void {
+    const reason = error instanceof Error ? error.message : String(error);
+    const message =
+      `Component "${id}" (${kind}${node.nodeId ? `, node "${node.nodeId}"` : ''}) threw while ` +
+      `rendering: ${reason}. Rendering the error fallback instead of crashing the surrounding tree.`;
+    if (typeof console !== 'undefined') {
+      console.warn(`[@contentful/experiences-svelte] ${message}`);
+    }
+    onDiagnostic(new Error(message, { cause: error instanceof Error ? error : undefined }));
+  }
 </script>
 
 {#if componentConfig && composed}
   {@const Cmp = componentConfig.component}
-  <Cmp {...composed} />
+  {@const ErrorFallback = renderError}
+  <svelte:boundary onerror={(error) => reportRenderError(error)}>
+    <Cmp {...composed} />
+    {#snippet failed()}
+      <ErrorFallback componentId={id} nodeId={node.nodeId} />
+    {/snippet}
+  </svelte:boundary>
 {:else if orphanedSnippets}
   {#each orphanedSnippets as childSnippet, index (index)}
     {@render childSnippet()}
   {/each}
 {:else}
+  {@const _reported = reportMissingComponent()}
   {@const Unknown = renderUnknown}
   <Unknown
     componentId={id}

package/dist/NodeRenderer.svelte.d.ts

@@ -1,12 +1,14 @@
 import type { Snippet } from 'svelte';
 import type { PortableRenderNode } from '@contentful/experiences-sdk-core';
-import type { RenderUnknown } from './component-props.js';
+import type { DiagnosticReporter, RenderError, RenderUnknown } from './component-props.js';
 import { type Config, type RenderContext } from './types.js';
 interface NodeRendererProps {
     node: PortableRenderNode;
     config: Config;
     experience: RenderContext;
     renderUnknown: RenderUnknown;
+    renderError: RenderError;
+    onDiagnostic: DiagnosticReporter;
     /**
      * Pre-rendered slot children keyed by slot name — one zero-arg Snippet per
      * child node. Spread onto the customer component as named props, so a slot

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;AAQ3E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,EAKH,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;;;;OAIG;IACH,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,EAAE,CAAC,CAAC;CACzC;AA2GH,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;AAQ3E,OAAO,KAAK,EAAE,kBAAkB,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAC3F,OAAO,EAKH,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,WAAW,EAAE,WAAW,CAAC;IACzB,YAAY,EAAE,kBAAkB,CAAC;IACjC;;;;OAIG;IACH,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,EAAE,CAAC,CAAC;CACzC;AAgKH,QAAA,MAAM,YAAY,uDAAwC,CAAC;AAC3D,KAAK,YAAY,GAAG,UAAU,CAAC,OAAO,YAAY,CAAC,CAAC;AACpD,eAAe,YAAY,CAAC"}

package/dist/NodeRenderer.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=NodeRenderer.test.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"NodeRenderer.test.d.ts","sourceRoot":"","sources":["../src/NodeRenderer.test.ts"],"names":[],"mappings":""}

package/dist/NodeRenderer.test.js

@@ -0,0 +1,124 @@
+/*
+ * `component-render-error` isolation on the CLIENT (jsdom, client-compiled
+ * output — the default `vitest.config.ts`). `<svelte:boundary>` genuinely
+ * catches here, unlike under `svelte/server` — see `nodes-renderer.ssr.test.ts`
+ * for that documented, proven gap. Both `ServerExperienceRenderer` and
+ * `ClientExperienceRenderer` share the same `NodesRenderer`/`NodeRenderer`
+ * boundary code, so both are exercised — the distinction between the two
+ * components is about viewport-tracking reactivity, not error handling.
+ */
+import { render } from '@testing-library/svelte';
+import { describe, expect, it, vi } from 'vitest';
+// `ClientExperienceRenderer`'s onDiagnostic defers via `queueMicrotask` (see
+// its own comment for why); a test asserting against the debug panel needs to
+// let that microtask settle first.
+async function flushMicrotasks() {
+    await new Promise((resolve) => queueMicrotask(resolve));
+}
+import { resolveExperience } from '@contentful/experiences-sdk-core';
+import ClientExperienceRenderer from './ClientExperienceRenderer.svelte';
+import ServerExperienceRenderer from './ServerExperienceRenderer.svelte';
+import BrokenFixture from './test-fixtures/BrokenFixture.svelte';
+import ButtonFixture from './test-fixtures/ButtonFixture.svelte';
+const VIEWPORTS = [{ id: 'desktop', query: '*', displayName: 'Desktop', previewSize: '100%' }];
+function componentNode(typeId, rest = {}) {
+    return {
+        component: {
+            sys: {
+                type: 'ResourceLink',
+                linkType: 'Contentful:Component',
+                urn: `crn:contentful:::experience:spaces/$self/environments/$self/components/${typeId}`,
+            },
+        },
+        ...rest,
+    };
+}
+describe.each([
+    ['ServerExperienceRenderer', ServerExperienceRenderer],
+    ['ClientExperienceRenderer', ClientExperienceRenderer],
+])('%s — component-render-error, client-side catch', (name, Renderer) => {
+    it('isolates the failing node — sibling still renders, records a diagnostic', async () => {
+        const warn = vi.spyOn(console, 'warn').mockImplementation(() => { });
+        try {
+            const payload = {
+                viewports: VIEWPORTS,
+                nodes: [
+                    componentNode('broken', { id: 'b' }),
+                    componentNode('contentful-button', { id: 'f', contentProperties: { label: 'sibling' } }),
+                ],
+            };
+            const config = {
+                components: { broken: BrokenFixture, 'contentful-button': ButtonFixture },
+            };
+            const plan = await resolveExperience(payload, config);
+            const { container } = render(Renderer, {
+                props: { experience: plan, config, debug: true },
+            });
+            expect(container.querySelector('button')?.textContent).toBe('sibling');
+            expect(container.querySelector('[data-experiences-render-error="broken"]')).not.toBeNull();
+            expect(warn).toHaveBeenCalledWith(expect.stringContaining('boom'));
+            await flushMicrotasks();
+            // Only ClientExperienceRenderer's debug panel is reactive
+            // ($state-backed renderDiagnostics): the boundary's onerror resolves
+            // after the initial render even under this client-mounted harness, and
+            // ServerExperienceRenderer's plain-array collection is evaluated once,
+            // matching its documented "one synchronous SSR pass" contract — real
+            // `svelte/server` never reaches the catching code at all (see the
+            // README's SSR/CSR asymmetry section), so this component never shows
+            // this diagnostic in the debug panel in any real deployment either.
+            if (name === 'ClientExperienceRenderer') {
+                const errorList = container.querySelector('[data-experiences-debug-errors]');
+                expect(errorList).not.toBeNull();
+                expect(errorList.textContent).toContain('Component "broken"');
+                expect(errorList.textContent).toContain('boom');
+            }
+        }
+        finally {
+            warn.mockRestore();
+        }
+    });
+    it('renders nothing from the default fallback when debug is off, but still warns', async () => {
+        const warn = vi.spyOn(console, 'warn').mockImplementation(() => { });
+        try {
+            const payload = {
+                viewports: VIEWPORTS,
+                nodes: [componentNode('broken', { id: 'b' })],
+            };
+            const config = { components: { broken: BrokenFixture } };
+            const plan = await resolveExperience(payload, config);
+            const { container } = render(Renderer, {
+                props: { experience: plan, config },
+            });
+            expect(container.querySelector('[data-experiences-render-error]')).toBeNull();
+            expect(warn).toHaveBeenCalledWith(expect.stringContaining('boom'));
+        }
+        finally {
+            warn.mockRestore();
+        }
+    });
+});
+describe('ClientExperienceRenderer — render-time diagnostics dedupe across re-renders', () => {
+    it('reports a persistently-unregistered component only once, not once per re-render', async () => {
+        const warn = vi.spyOn(console, 'warn').mockImplementation(() => { });
+        try {
+            const payload = {
+                viewports: VIEWPORTS,
+                nodes: [componentNode('missing', { id: 'm' })],
+            };
+            const config = { components: {} };
+            const plan = await resolveExperience(payload, config);
+            const { container, rerender } = render(ClientExperienceRenderer, {
+                props: { experience: plan, config, debug: true },
+            });
+            // Force NodeRenderer's reactive blocks to re-run without any real new
+            // occurrence — an ancestor re-render (a viewport change, an unrelated
+            // parent update) does the same thing in production.
+            await rerender({ experience: plan, config, debug: true });
+            expect(container.querySelectorAll('[data-experiences-debug-errors] li')).toHaveLength(1);
+            expect(container.textContent).toContain('No component registered for id "missing"');
+        }
+        finally {
+            warn.mockRestore();
+        }
+    });
+});

package/dist/NodesRenderer.svelte

@@ -26,7 +26,7 @@
   import type { PortableRenderNode } from '@contentful/experiences-sdk-core';
 
   import NodeRenderer from './NodeRenderer.svelte';
-  import type { RenderUnknown } from './component-props.js';
+  import type { DiagnosticReporter, RenderError, RenderUnknown } from './component-props.js';
   import type { Config, RenderContext } from './types.js';
 
   interface NodesRendererProps {
@@ -34,9 +34,24 @@
     config: Config;
     experience: RenderContext;
     renderUnknown: RenderUnknown;
+    renderError: RenderError;
+    onDiagnostic: DiagnosticReporter;
   }
 
-  let { nodes, config, experience, renderUnknown }: NodesRendererProps = $props();
+  let { nodes, config, experience, renderUnknown, renderError, onDiagnostic }: NodesRendererProps =
+    $props();
+
+  // Same re-run-doesn't-mean-new-occurrence problem as NodeRenderer.svelte's
+  // `reportOnce` — `renderNode`'s `{@const}`s re-run per node on every
+  // reactive re-render of the `{#each}` block. One Set covers every node in
+  // this list since the diagnostic's own context (nodeId/slotName) already
+  // makes the signature unique per node+slot.
+  const reportedSlots = new Set<string>();
+  function reportSlotDiagnosticOnce(error: Error): void {
+    if (reportedSlots.has(error.message)) return;
+    reportedSlots.add(error.message);
+    onDiagnostic(error);
+  }
 
   // Curry the parameterized `renderNode` snippet into a zero-arg Snippet bound
   // to one node: forward the anchor (the renderer, under SSR) and supply the
@@ -62,9 +77,29 @@
   // themselves are compile-time entities, but the merged props object is
   // plain runtime data — so an unbounded set of payload-driven slot names is
   // fine as long as each snippet comes from `toChildSnippet`.
-  function toSlotSnippets(node: PortableRenderNode): Record<string, Snippet[]> {
+  //
+  // Defensive: `node.slots[x]` is typed as an array, but a hand-built
+  // PortableRenderPlan (a supported path — customers can construct one
+  // directly instead of going through `resolveExperience`) is not
+  // type-checked at runtime. Warn + drop rather than letting `.map` throw.
+  function toSlotSnippets(
+    node: PortableRenderNode,
+    onDiagnosticFn: DiagnosticReporter
+  ): Record<string, Snippet[]> {
     const slotSnippets: Record<string, Snippet[]> = {};
     for (const [slotName, children] of Object.entries(node.slots)) {
+      if (!Array.isArray(children)) {
+        const { kind, id } = node.registration;
+        const message =
+          `Slot "${slotName}" on ${kind} "${id}"${node.nodeId ? ` (node "${node.nodeId}")` : ''} ` +
+          `is not an array of nodes; rendering it as empty instead of throwing.`;
+        if (typeof console !== 'undefined') {
+          console.warn(`[@contentful/experiences-svelte] ${message}`);
+        }
+        onDiagnosticFn(new Error(message));
+        slotSnippets[slotName] = [];
+        continue;
+      }
       slotSnippets[slotName] = children.map(toChildSnippet);
     }
     return slotSnippets;
@@ -73,8 +108,16 @@
 
 {#snippet renderNode(nodeArg: NodeArg)}
   {@const node = unwrapNode(nodeArg)}
-  {@const slotSnippets = toSlotSnippets(node)}
-  <NodeRenderer {node} {config} {experience} {renderUnknown} {slotSnippets} />
+  {@const slotSnippets = toSlotSnippets(node, reportSlotDiagnosticOnce)}
+  <NodeRenderer
+    {node}
+    {config}
+    {experience}
+    {renderUnknown}
+    {renderError}
+    {onDiagnostic}
+    {slotSnippets}
+  />
 {/snippet}
 
 {#each nodes as node, index (node.nodeId ?? index)}