@contentful/experiences-svelte 0.5.10 → 0.5.12

package/dist/NodesRenderer.svelte.d.ts

@@ -1,11 +1,13 @@
 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, RenderContext } from './types.js';
 interface NodesRendererProps {
     nodes: PortableRenderNode[];
     config: Config;
     experience: RenderContext;
     renderUnknown: RenderUnknown;
+    renderError: RenderError;
+    onDiagnostic: DiagnosticReporter;
 }
 declare const NodesRenderer: import("svelte").Component<NodesRendererProps, {}, "">;
 type NodesRenderer = ReturnType<typeof NodesRenderer>;

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

@@ -1 +1 @@
-{"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;AA4DH,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,kBAAkB,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAC3F,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;IAC7B,WAAW,EAAE,WAAW,CAAC;IACzB,YAAY,EAAE,kBAAkB,CAAC;CAClC;AA6FH,QAAA,MAAM,aAAa,wDAAwC,CAAC;AAC5D,KAAK,aAAa,GAAG,UAAU,CAAC,OAAO,aAAa,CAAC,CAAC;AACtD,eAAe,aAAa,CAAC"}

package/dist/ServerExperienceRenderer.svelte

@@ -11,6 +11,7 @@
   import type { ExperienceContext, ViewportDef } from '@contentful/experiences-sdk-core';
   import { getViewportIndex } from '@contentful/experiences-design';
 
+  import ComponentError from './ComponentError.svelte';
   import DebugExperience from './DebugExperience.svelte';
   import MissingComponent from './MissingComponent.svelte';
   import NodesRenderer from './NodesRenderer.svelte';
@@ -38,6 +39,7 @@
     metadata,
     debug = false,
     renderUnknown = MissingComponent,
+    renderError = ComponentError,
   }: ServerExperienceRendererProps = $props();
 
   function buildContext(): RenderContext {
@@ -56,16 +58,32 @@
 
   const renderContext = buildContext();
   setExperience(renderContext);
+
+  // Render-time diagnostics (unregistered id, a component that threw),
+  // collected into a plain array rather than `$state`: Svelte SSR is
+  // synchronous top-down, so by the time `<DebugExperience>` renders — after
+  // the tree, matching the React adapter's element-order fix for
+  // consistency, even though Svelte's own reactivity wouldn't strictly
+  // require it — this array is already fully populated.
+  const renderDiagnostics: Error[] = [];
+  function onDiagnostic(error: Error): void {
+    renderDiagnostics.push(error);
+  }
 </script>
 
 {#if experience}
-  {#if debug}
-    <DebugExperience {experience} />
-  {/if}
   <NodesRenderer
     nodes={experience.nodes}
     {config}
     experience={renderContext}
     {renderUnknown}
+    {renderError}
+    {onDiagnostic}
   />
+  {#if debug}
+    <DebugExperience
+      {experience}
+      errors={[...(experience.diagnostics ?? []), ...renderDiagnostics]}
+    />
+  {/if}
 {/if}

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

@@ -1 +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;AAiE1E,QAAA,MAAM,wBAAwB,mEAAwC,CAAC;AACvE,KAAK,wBAAwB,GAAG,UAAU,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAC5E,eAAe,wBAAwB,CAAC"}
+{"version":3,"file":"ServerExperienceRenderer.svelte.d.ts","sourceRoot":"","sources":["../src/ServerExperienceRenderer.svelte.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,6BAA6B,EAAE,MAAM,sBAAsB,CAAC;AA8E1E,QAAA,MAAM,wBAAwB,mEAAwC,CAAC;AACvE,KAAK,wBAAwB,GAAG,UAAU,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAC5E,eAAe,wBAAwB,CAAC"}

package/dist/component-props.d.ts

@@ -17,6 +17,8 @@ export interface ServerExperienceRendererProps {
      */
     debug?: boolean;
     renderUnknown?: RenderUnknown;
+    /** Override the fallback rendered when a registered component throws. */
+    renderError?: RenderError;
 }
 export type ClientExperienceRendererProps = ServerExperienceRendererProps;
 export interface MissingComponentProps {
@@ -25,10 +27,36 @@ export interface MissingComponentProps {
     nodeId?: string;
 }
 export type RenderUnknown = Component<MissingComponentProps>;
+export interface ComponentErrorProps {
+    componentId: string;
+    /** Optional — only present when the payload supplied an id for this node. */
+    nodeId?: string;
+    /** The caught error's message, when available. */
+    message?: string;
+}
+export type RenderError = Component<ComponentErrorProps>;
+/**
+ * Reports one render-time diagnostic (unregistered id, a component that
+ * threw). `ServerExperienceRenderer` passes a closure that pushes onto a
+ * plain array (Svelte SSR is synchronous top-down, so the array is fully
+ * populated by the time `<DebugExperience>` reads it). `ClientExperienceRenderer`
+ * passes a closure that mutates a `$state` array instead, so `<DebugExperience>`
+ * re-renders reactively when a later interaction throws.
+ */
+export type DiagnosticReporter = (error: Error) => void;
 export interface DebugExperienceProps {
     /** The resolved plan to inspect (what a renderer receives as `experience`). */
     experience: PortableRenderPlan;
     /** Start expanded. Defaults to collapsed to stay out of the way. */
     defaultOpen?: boolean;
+    /**
+     * Resolve-time + render-time diagnostics for this render, merged by the
+     * caller (`ServerExperienceRenderer` / `ClientExperienceRenderer`). Plain
+     * `Error`s — the two cases that wrap a real caught exception
+     * (`component-render-error`, `resolve-data-failed`) set `.cause` to the
+     * original error, inspectable via `console.error` or `error.cause.stack`.
+     * Defaults to `[]` for a manually-mounted `<DebugExperience>`.
+     */
+    errors?: Error[];
 }
 //# sourceMappingURL=component-props.d.ts.map

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,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"}
+{"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;IAC9B,yEAAyE;IACzE,WAAW,CAAC,EAAE,WAAW,CAAC;CAC3B;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,mBAAmB;IAClC,WAAW,EAAE,MAAM,CAAC;IACpB,6EAA6E;IAC7E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,kDAAkD;IAClD,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,MAAM,WAAW,GAAG,SAAS,CAAC,mBAAmB,CAAC,CAAC;AAEzD;;;;;;;GAOG;AACH,MAAM,MAAM,kBAAkB,GAAG,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;AAExD,MAAM,WAAW,oBAAoB;IACnC,+EAA+E;IAC/E,UAAU,EAAE,kBAAkB,CAAC;IAC/B,oEAAoE;IACpE,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB;;;;;;;OAOG;IACH,MAAM,CAAC,EAAE,KAAK,EAAE,CAAC;CAClB"}

package/dist/debug-panel-coverage.ssr.test.d.ts

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

package/dist/debug-panel-coverage.ssr.test.d.ts.map

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

package/dist/debug-panel-coverage.ssr.test.js

@@ -0,0 +1,61 @@
+/*
+ * True SSR coverage of a resolve-time diagnostic reaching the debug panel —
+ * renders through `svelte/server` (Svelte's *server*-compiled output), not
+ * `@testing-library/svelte` (the client build every other coverage test in
+ * this package uses). `token-unresolved` is the trigger: it's produced by
+ * `resolveExperience` itself, so it's already baked into `plan.diagnostics`
+ * before any renderer sees it — proving the panel surfaces a resolve-time
+ * diagnostic under a real, synchronous server render, not just under a
+ * client-mounted test harness.
+ *
+ * Runs under vitest.ssr.config.ts (environment: node) — the `.ssr.test.ts`
+ * suffix is load-bearing, see nodes-renderer.ssr.test.ts for why.
+ */
+import { describe, expect, it, vi } from 'vitest';
+import { render } from 'svelte/server';
+import { resolveExperience } from '@contentful/experiences-sdk-core';
+import ServerExperienceRenderer from './ServerExperienceRenderer.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('debug panel — true SSR coverage of a resolve-time diagnostic', () => {
+    it('token-unresolved reaches the debug panel under svelte/server', async () => {
+        const warn = vi.spyOn(console, 'warn').mockImplementation(() => { });
+        try {
+            const payload = {
+                viewports: VIEWPORTS,
+                nodes: [
+                    componentNode('button', {
+                        id: 'b',
+                        designProperties: { cfColor: { type: 'DesignToken', value: 'color.brand' } },
+                    }),
+                ],
+            };
+            const config = {
+                components: { button: ButtonFixture },
+                resolveToken: () => undefined,
+            };
+            const plan = await resolveExperience(payload, config);
+            const html = render(ServerExperienceRenderer, {
+                props: { experience: plan, config, debug: true },
+            }).body;
+            expect(html).toContain('data-experiences-debug-errors');
+            expect(html).toContain('color.brand');
+            expect(html).toContain('resolveToken');
+        }
+        finally {
+            warn.mockRestore();
+        }
+    });
+});

package/dist/debug-panel-coverage.test.d.ts

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

package/dist/debug-panel-coverage.test.d.ts.map

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

package/dist/debug-panel-coverage.test.js

@@ -0,0 +1,229 @@
+/*
+ * End-to-end proof that every one of the 8 non-happy-path failure modes
+ * reaches `<DebugExperience>`'s rendered output — through a real
+ * `resolveExperience` + renderer pipeline, not a hand-built diagnostic
+ * fixture (see DebugExperience.test.ts for the fixture-level tests of the
+ * panel's own rendering logic). Each test asserts a distinguishing substring
+ * of the real message, not the whole string, so wording tweaks don't make
+ * these overly brittle.
+ *
+ * True SSR coverage of a resolve-time diagnostic (`token-unresolved`) lives
+ * in debug-panel-coverage.ssr.test.ts, using `svelte/server`'s `render` — this
+ * file's `ServerExperienceRenderer` tests mount client-side via
+ * `@testing-library/svelte`, same as the rest of this package's suite.
+ */
+import { render } from '@testing-library/svelte';
+import { describe, expect, it, vi } from 'vitest';
+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';
+// `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));
+}
+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('debug panel — end-to-end coverage of every non-happy-path failure mode', () => {
+    it('malformed-payload: a non-array nodes field', async () => {
+        const warn = vi.spyOn(console, 'warn').mockImplementation(() => { });
+        try {
+            const plan = await resolveExperience({ viewports: VIEWPORTS, nodes: 'not-an-array' }, { components: {} });
+            const { container } = render(ServerExperienceRenderer, {
+                props: { experience: plan, config: { components: {} }, debug: true },
+            });
+            expect(container.innerHTML).toContain('data-experiences-debug-errors');
+            expect(container.innerHTML).toContain('"nodes" is not an array');
+        }
+        finally {
+            warn.mockRestore();
+        }
+    });
+    it('malformed-slot: a slot value that is not an array', async () => {
+        const warn = vi.spyOn(console, 'warn').mockImplementation(() => { });
+        try {
+            const payload = {
+                viewports: VIEWPORTS,
+                nodes: [
+                    componentNode('contentful-container', {
+                        id: 'page',
+                        slots: { children: 'oops' },
+                    }),
+                ],
+            };
+            const config = { components: { 'contentful-container': ButtonFixture } };
+            const plan = await resolveExperience(payload, config);
+            const { container } = render(ServerExperienceRenderer, {
+                props: { experience: plan, config, debug: true },
+            });
+            expect(container.innerHTML).toContain('data-experiences-debug-errors');
+            expect(container.innerHTML).toContain('Slot "children"');
+        }
+        finally {
+            warn.mockRestore();
+        }
+    });
+    it('unidentifiable-node: a node with no readable component/experienceTemplate ref', async () => {
+        const warn = vi.spyOn(console, 'warn').mockImplementation(() => { });
+        try {
+            const payload = {
+                viewports: VIEWPORTS,
+                nodes: [{ pattern: {} }, componentNode('button', { id: 'b' })],
+            };
+            const config = { components: { button: ButtonFixture } };
+            const plan = await resolveExperience(payload, config);
+            const { container } = render(ServerExperienceRenderer, {
+                props: { experience: plan, config, debug: true },
+            });
+            expect(container.innerHTML).toContain('data-experiences-debug-errors');
+            expect(container.innerHTML).toContain('Skipping unidentifiable node');
+        }
+        finally {
+            warn.mockRestore();
+        }
+    });
+    it('resolve-data-failed: resolveData throws for a registered component', async () => {
+        const warn = vi.spyOn(console, 'warn').mockImplementation(() => { });
+        try {
+            const payload = {
+                viewports: VIEWPORTS,
+                nodes: [componentNode('button', { id: 'b' })],
+            };
+            const config = {
+                components: {
+                    button: {
+                        resolveData: () => {
+                            throw new Error('enrichment service down');
+                        },
+                        component: ButtonFixture,
+                    },
+                },
+            };
+            const plan = await resolveExperience(payload, config);
+            expect(plan.diagnostics[0]).toBeInstanceOf(Error);
+            expect(plan.diagnostics[0].cause?.message).toBe('enrichment service down');
+            const { container } = render(ServerExperienceRenderer, {
+                props: { experience: plan, config, debug: true },
+            });
+            expect(container.innerHTML).toContain('data-experiences-debug-errors');
+            expect(container.innerHTML).toContain('component:button');
+            expect(container.innerHTML).toContain('enrichment service down');
+        }
+        finally {
+            warn.mockRestore();
+        }
+    });
+    it('token-unresolved: a DesignToken with no resolveToken mapping', async () => {
+        const warn = vi.spyOn(console, 'warn').mockImplementation(() => { });
+        try {
+            const payload = {
+                viewports: VIEWPORTS,
+                nodes: [
+                    componentNode('button', {
+                        id: 'b',
+                        designProperties: { cfColor: { type: 'DesignToken', value: 'color.brand' } },
+                    }),
+                ],
+            };
+            const config = {
+                components: { button: ButtonFixture },
+                resolveToken: () => undefined,
+            };
+            const plan = await resolveExperience(payload, config);
+            const { container } = render(ServerExperienceRenderer, {
+                props: { experience: plan, config, debug: true },
+            });
+            expect(container.innerHTML).toContain('data-experiences-debug-errors');
+            expect(container.innerHTML).toContain('color.brand');
+            expect(container.innerHTML).toContain('resolveToken');
+        }
+        finally {
+            warn.mockRestore();
+        }
+    });
+    it('component-not-registered: an id with no matching entry in config.components', 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 } = render(ServerExperienceRenderer, {
+                props: { experience: plan, config, debug: true },
+            });
+            expect(container.innerHTML).toContain('data-experiences-debug-errors');
+            expect(container.innerHTML).toContain('No component registered for id "missing"');
+        }
+        finally {
+            warn.mockRestore();
+        }
+    });
+    it('experience-template-not-registered: a template id with no matching entry in config.experienceTemplates', async () => {
+        const warn = vi.spyOn(console, 'warn').mockImplementation(() => { });
+        try {
+            const payload = {
+                viewports: VIEWPORTS,
+                nodes: [
+                    {
+                        experienceTemplate: {
+                            sys: {
+                                type: 'ResourceLink',
+                                linkType: 'Contentful:ExperienceTemplate',
+                                urn: 'crn:contentful:::experience:spaces/$self/environments/$self/experienceTemplates/missing-template',
+                            },
+                        },
+                        id: 'tpl',
+                    },
+                ],
+            };
+            const config = { components: {} };
+            const plan = await resolveExperience(payload, config);
+            const { container } = render(ServerExperienceRenderer, {
+                props: { experience: plan, config, debug: true },
+            });
+            expect(container.innerHTML).toContain('data-experiences-debug-errors');
+            expect(container.innerHTML).toContain('No experience template registered for id "missing-template"');
+        }
+        finally {
+            warn.mockRestore();
+        }
+    });
+    it('component-render-error: a registered component that throws while rendering', 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(ClientExperienceRenderer, {
+                props: { experience: plan, config, debug: true },
+            });
+            await flushMicrotasks();
+            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();
+        }
+    });
+});

package/dist/index.d.ts

@@ -2,6 +2,7 @@ export { default as ClientExperienceRenderer } from './ClientExperienceRenderer.
 export { default as ExperienceRenderer } from './ClientExperienceRenderer.svelte';
 export { default as ServerExperienceRenderer } from './ServerExperienceRenderer.svelte';
 export { default as MissingComponent } from './MissingComponent.svelte';
+export { default as ComponentError } from './ComponentError.svelte';
 export { default as DebugExperience } from './DebugExperience.svelte';
 export { default as NodesRenderer } from './NodesRenderer.svelte';
 export { useActiveViewport } from './use-active-viewport.svelte.js';
@@ -10,13 +11,13 @@ export { getExperience, getContentfulComponent, getContentfulExperienceTemplate,
 export { getDesignValues } from './get-design-values.js';
 export { toCss } from './design-utils.js';
 export type { ToCssOptions } from './design-utils.js';
-export type { ClientExperienceRendererProps, ClientExperienceRendererProps as ExperienceRendererProps, DebugExperienceProps, MissingComponentProps, RenderUnknown, ServerExperienceRendererProps, } from './component-props.js';
+export type { ClientExperienceRendererProps, ClientExperienceRendererProps as ExperienceRendererProps, ComponentErrorProps, DebugExperienceProps, DiagnosticReporter, MissingComponentProps, RenderError, RenderUnknown, ServerExperienceRendererProps, } from './component-props.js';
 export { defineComponent, defineExperienceTemplate, normalizeComponentRegistration, normalizeExperienceTemplateRegistration, } from './types.js';
 export type { ComponentConfig, Components, Config, ContentfulComponent, ContentfulExperienceTemplate, ExperienceTemplateConfig, ExperienceTemplateRegistration, ExperienceTemplates, Registration, RenderContext, ResolveToken, } from './types.js';
 export { resolveExperience } from '@contentful/experiences-sdk-core';
 export type { ResolverConfig, ResolveExperienceOptions } from '@contentful/experiences-sdk-core';
 export type { ComponentNode, ComponentRef, DesignPropValue, DesignToken, ExperienceContext, ExperienceNode, ExperiencePayload, ExperienceSys, ExperienceTemplateNode, ExperienceTemplateRef, ManualDesignValue, PortableRegistration, PortableRenderNode, PortableRenderPlan, ResolveContext, ValuesByViewport, ViewportDef, } from '@contentful/experiences-sdk-core';
 export { CSS_PROPERTIES, getValueForViewport, getViewportIndex, isCssProperty, resolveDesignProperties, toCssKey, toCssMediaQuery, } from '@contentful/experiences-design';
-export { ContentfulViewDelivery, ContentfulViewDeliveryClient, DELIVERY_HOST, NotFoundError, PREVIEW_HOST, createClient, fetchExperience, } from '@contentful/experiences-client';
+export { ContentfulViewDelivery, ContentfulViewDeliveryClient, DELIVERY_HOST, ExperienceFetchError, NotFoundError, PREVIEW_HOST, createClient, fetchExperience, } from '@contentful/experiences-client';
 export type { ClientOptions, CreateClientOptions, ExperienceOptions, ResolveOptions, } from '@contentful/experiences-client';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAeA,OAAO,EAAE,OAAO,IAAI,wBAAwB,EAAE,MAAM,mCAAmC,CAAC;AACxF,OAAO,EAAE,OAAO,IAAI,kBAAkB,EAAE,MAAM,mCAAmC,CAAC;AAClF,OAAO,EAAE,OAAO,IAAI,wBAAwB,EAAE,MAAM,mCAAmC,CAAC;AACxF,OAAO,EAAE,OAAO,IAAI,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AACxE,OAAO,EAAE,OAAO,IAAI,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAKtE,OAAO,EAAE,OAAO,IAAI,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAElE,OAAO,EAAE,iBAAiB,EAAE,MAAM,iCAAiC,CAAC;AACpE,YAAY,EAAE,uBAAuB,EAAE,MAAM,iCAAiC,CAAC;AAG/E,OAAO,EACL,aAAa,EACb,sBAAsB,EACtB,+BAA+B,GAChC,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAC1C,YAAY,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAItD,YAAY,EACV,6BAA6B,EAC7B,6BAA6B,IAAI,uBAAuB,EACxD,oBAAoB,EACpB,qBAAqB,EACrB,aAAa,EACb,6BAA6B,GAC9B,MAAM,sBAAsB,CAAC;AAG9B,OAAO,EACL,eAAe,EACf,wBAAwB,EACxB,8BAA8B,EAC9B,uCAAuC,GACxC,MAAM,YAAY,CAAC;AACpB,YAAY,EACV,eAAe,EACf,UAAU,EACV,MAAM,EACN,mBAAmB,EACnB,4BAA4B,EAC5B,wBAAwB,EACxB,8BAA8B,EAC9B,mBAAmB,EACnB,YAAY,EACZ,aAAa,EACb,YAAY,GACb,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAE,iBAAiB,EAAE,MAAM,kCAAkC,CAAC;AACrE,YAAY,EAAE,cAAc,EAAE,wBAAwB,EAAE,MAAM,kCAAkC,CAAC;AAGjG,YAAY,EACV,aAAa,EACb,YAAY,EACZ,eAAe,EACf,WAAW,EACX,iBAAiB,EACjB,cAAc,EACd,iBAAiB,EACjB,aAAa,EACb,sBAAsB,EACtB,qBAAqB,EACrB,iBAAiB,EACjB,oBAAoB,EACpB,kBAAkB,EAClB,kBAAkB,EAClB,cAAc,EACd,gBAAgB,EAChB,WAAW,GACZ,MAAM,kCAAkC,CAAC;AAG1C,OAAO,EACL,cAAc,EACd,mBAAmB,EACnB,gBAAgB,EAChB,aAAa,EACb,uBAAuB,EACvB,QAAQ,EACR,eAAe,GAChB,MAAM,gCAAgC,CAAC;AAGxC,OAAO,EACL,sBAAsB,EACtB,4BAA4B,EAC5B,aAAa,EACb,aAAa,EACb,YAAY,EACZ,YAAY,EACZ,eAAe,GAChB,MAAM,gCAAgC,CAAC;AACxC,YAAY,EACV,aAAa,EACb,mBAAmB,EACnB,iBAAiB,EACjB,cAAc,GACf,MAAM,gCAAgC,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAeA,OAAO,EAAE,OAAO,IAAI,wBAAwB,EAAE,MAAM,mCAAmC,CAAC;AACxF,OAAO,EAAE,OAAO,IAAI,kBAAkB,EAAE,MAAM,mCAAmC,CAAC;AAClF,OAAO,EAAE,OAAO,IAAI,wBAAwB,EAAE,MAAM,mCAAmC,CAAC;AACxF,OAAO,EAAE,OAAO,IAAI,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AACxE,OAAO,EAAE,OAAO,IAAI,cAAc,EAAE,MAAM,yBAAyB,CAAC;AACpE,OAAO,EAAE,OAAO,IAAI,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAKtE,OAAO,EAAE,OAAO,IAAI,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAElE,OAAO,EAAE,iBAAiB,EAAE,MAAM,iCAAiC,CAAC;AACpE,YAAY,EAAE,uBAAuB,EAAE,MAAM,iCAAiC,CAAC;AAG/E,OAAO,EACL,aAAa,EACb,sBAAsB,EACtB,+BAA+B,GAChC,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAC1C,YAAY,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAItD,YAAY,EACV,6BAA6B,EAC7B,6BAA6B,IAAI,uBAAuB,EACxD,mBAAmB,EACnB,oBAAoB,EACpB,kBAAkB,EAClB,qBAAqB,EACrB,WAAW,EACX,aAAa,EACb,6BAA6B,GAC9B,MAAM,sBAAsB,CAAC;AAG9B,OAAO,EACL,eAAe,EACf,wBAAwB,EACxB,8BAA8B,EAC9B,uCAAuC,GACxC,MAAM,YAAY,CAAC;AACpB,YAAY,EACV,eAAe,EACf,UAAU,EACV,MAAM,EACN,mBAAmB,EACnB,4BAA4B,EAC5B,wBAAwB,EACxB,8BAA8B,EAC9B,mBAAmB,EACnB,YAAY,EACZ,aAAa,EACb,YAAY,GACb,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAE,iBAAiB,EAAE,MAAM,kCAAkC,CAAC;AACrE,YAAY,EAAE,cAAc,EAAE,wBAAwB,EAAE,MAAM,kCAAkC,CAAC;AAGjG,YAAY,EACV,aAAa,EACb,YAAY,EACZ,eAAe,EACf,WAAW,EACX,iBAAiB,EACjB,cAAc,EACd,iBAAiB,EACjB,aAAa,EACb,sBAAsB,EACtB,qBAAqB,EACrB,iBAAiB,EACjB,oBAAoB,EACpB,kBAAkB,EAClB,kBAAkB,EAClB,cAAc,EACd,gBAAgB,EAChB,WAAW,GACZ,MAAM,kCAAkC,CAAC;AAG1C,OAAO,EACL,cAAc,EACd,mBAAmB,EACnB,gBAAgB,EAChB,aAAa,EACb,uBAAuB,EACvB,QAAQ,EACR,eAAe,GAChB,MAAM,gCAAgC,CAAC;AAGxC,OAAO,EACL,sBAAsB,EACtB,4BAA4B,EAC5B,aAAa,EACb,oBAAoB,EACpB,aAAa,EACb,YAAY,EACZ,YAAY,EACZ,eAAe,GAChB,MAAM,gCAAgC,CAAC;AACxC,YAAY,EACV,aAAa,EACb,mBAAmB,EACnB,iBAAiB,EACjB,cAAc,GACf,MAAM,gCAAgC,CAAC"}

package/dist/index.js

@@ -16,6 +16,7 @@ export { default as ClientExperienceRenderer } from './ClientExperienceRenderer.
 export { default as ExperienceRenderer } from './ClientExperienceRenderer.svelte';
 export { default as ServerExperienceRenderer } from './ServerExperienceRenderer.svelte';
 export { default as MissingComponent } from './MissingComponent.svelte';
+export { default as ComponentError } from './ComponentError.svelte';
 export { default as DebugExperience } from './DebugExperience.svelte';
 // Every slot already arrives as a same-named `Snippet[]` prop; this is exposed so
 // advanced customers can render a slot's raw nodes themselves instead:
@@ -33,4 +34,4 @@ export { resolveExperience } from '@contentful/experiences-sdk-core';
 // ─── Design utilities (re-exported from design) ───────────────────────────
 export { CSS_PROPERTIES, getValueForViewport, getViewportIndex, isCssProperty, resolveDesignProperties, toCssKey, toCssMediaQuery, } from '@contentful/experiences-design';
 // ─── Delivery client + fetchExperience ────────────────────────────────────
-export { ContentfulViewDelivery, ContentfulViewDeliveryClient, DELIVERY_HOST, NotFoundError, PREVIEW_HOST, createClient, fetchExperience, } from '@contentful/experiences-client';
+export { ContentfulViewDelivery, ContentfulViewDeliveryClient, DELIVERY_HOST, ExperienceFetchError, NotFoundError, PREVIEW_HOST, createClient, fetchExperience, } from '@contentful/experiences-client';

package/dist/nodes-renderer.ssr.test.js

@@ -15,6 +15,7 @@ import { describe, expect, it } from 'vitest';
 import { render } from 'svelte/server';
 import { resolveExperience } from '@contentful/experiences-sdk-core';
 import ServerExperienceRenderer from './ServerExperienceRenderer.svelte';
+import BrokenFixture from './test-fixtures/BrokenFixture.svelte';
 import ButtonFixture from './test-fixtures/ButtonFixture.svelte';
 import ContainerFixture from './test-fixtures/ContainerFixture.svelte';
 import ExperienceTemplateFixture from './test-fixtures/ExperienceTemplateFixture.svelte';
@@ -124,3 +125,51 @@ describe('NodesRenderer — SSR (server-compiled output)', () => {
         expect(html).not.toContain('<main');
     });
 });
+/*
+ * The load-bearing SSR/CSR asymmetry this ticket documents: unlike React's
+ * class-boundary + internal <Suspense> (which degrades gracefully under both
+ * legacy and streaming SSR — see the React adapter's nodes-renderer.ssr.test.tsx),
+ * Svelte's native `<svelte:boundary>` has NO server-rendering story at all.
+ * `svelte/server`'s render is a synchronous string walk with no boundary
+ * concept; a throw during that walk simply propagates. This is proven here,
+ * not just asserted in a comment, per the plan's "prove it, don't just
+ * document it" bar. See `NodeRenderer.test.ts` for the client-side catch.
+ */
+describe('NodesRenderer — SSR component-render-error (the documented gap)', () => {
+    const brokenConfig = {
+        components: { broken: BrokenFixture, 'contentful-button': ButtonFixture },
+    };
+    it('has no recovery path under svelte/server — no graceful fallback markup is produced', async () => {
+        const payload = {
+            viewports: VIEWPORTS,
+            nodes: [componentNode('broken', { id: 'b' }), button('sibling')],
+        };
+        const plan = await resolveExperience(payload, brokenConfig);
+        // Propagates as an exception in most runs, but the exact timing is
+        // inconsistent across invocation contexts (sync throw in some runs,
+        // seemingly swallowed in others) — unlike React's deterministic
+        // Suspense-based degradation, Svelte's `<svelte:boundary>` has no
+        // supported SSR recovery contract at all, so nothing guarantees *how*
+        // the failure surfaces. The one invariant that holds in every run: the
+        // `failed` snippet's markup never appears, so there's no graceful
+        // degradation to rely on either way. No adapter-level fix is possible —
+        // `svelte/server` has no per-node recovery primitive below its single
+        // top-level `render()` call — see the README's SvelteKit mitigation note.
+        let html;
+        let caught;
+        try {
+            html = render(ServerExperienceRenderer, {
+                props: { experience: plan, config: brokenConfig },
+            }).body;
+        }
+        catch (err) {
+            caught = err;
+        }
+        if (caught) {
+            expect(caught.message).toBe('boom');
+        }
+        else {
+            expect(html).not.toContain('data-experiences-render-error');
+        }
+    });
+});

package/dist/server-renderer.test.js

@@ -390,12 +390,14 @@ describe('ServerExperienceRenderer', () => {
         };
         const plan = await resolveExperience(tplPayload, cfg);
         const { container } = render(ServerExperienceRenderer, {
-            props: { experience: plan, config: cfg },
+            props: { experience: plan, config: cfg, debug: true },
         });
         // The subtree survives — an unregistered template must not blank the page.
         expect(container.innerHTML).toContain('data-value="unwrapped"');
         expect(container.innerHTML).not.toContain('data-experience-template');
         expect(warn).toHaveBeenCalledWith(expect.stringContaining('missing-experienceTemplate'));
+        expect(container.innerHTML).toContain('data-experiences-debug-errors');
+        expect(container.innerHTML).toContain('No experience template registered for id "missing-experienceTemplate"');
         warn.mockRestore();
     });
 });
@@ -557,7 +559,7 @@ describe('ServerExperienceRenderer — resolveToken', () => {
         expect(container.innerHTML).toContain('data-bg="#4f39f6"');
         expect(container.innerHTML).not.toContain('DesignToken');
     });
-    it('warns and drops the key from the design values when the resolver returns undefined', async () => {
+    it('warns and passes the raw token through the design values when the resolver returns undefined', async () => {
         const warn = vi.spyOn(console, 'warn').mockImplementation(() => { });
         const cfg = {
             components: { 'contentful-button': CapturingComponent },
@@ -576,7 +578,7 @@ describe('ServerExperienceRenderer — resolveToken', () => {
         render(ServerExperienceRenderer, {
             props: { experience: plan, config: cfg },
         });
-        expect(captureSink[0].designValues).not.toHaveProperty('cfBackgroundColor');
+        expect(captureSink[0].designValues.cfBackgroundColor).toEqual(dt('color/unknown'));
         expect(warn).toHaveBeenCalledWith(expect.stringContaining('color/unknown'));
         expect(warn).toHaveBeenCalledWith(expect.stringContaining('contentful-button'));
         warn.mockRestore();

package/dist/test-fixtures/BrokenFixture.svelte

@@ -0,0 +1,4 @@
+<!-- Throws unconditionally — used to exercise `component-render-error` isolation. -->
+<script lang="ts">
+  throw new Error('boom');
+</script>

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

@@ -0,0 +1,19 @@
+interface $$__sveltets_2_IsomorphicComponent<Props extends Record<string, any> = any, Events extends Record<string, any> = any, Slots extends Record<string, any> = any, Exports = {}, Bindings = string> {
+    new (options: import('svelte').ComponentConstructorOptions<Props>): import('svelte').SvelteComponent<Props, Events, Slots> & {
+        $$bindings?: Bindings;
+    } & Exports;
+    (internal: unknown, props: {
+        $$events?: Events;
+        $$slots?: Slots;
+    }): Exports & {
+        $set?: any;
+        $on?: any;
+    };
+    z_$$bindings?: Bindings;
+}
+declare const BrokenFixture: $$__sveltets_2_IsomorphicComponent<Record<string, never>, {
+    [evt: string]: CustomEvent<any>;
+}, {}, {}, string>;
+type BrokenFixture = InstanceType<typeof BrokenFixture>;
+export default BrokenFixture;
+//# sourceMappingURL=BrokenFixture.svelte.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"BrokenFixture.svelte.d.ts","sourceRoot":"","sources":["../../src/test-fixtures/BrokenFixture.svelte.ts"],"names":[],"mappings":"AAUA,UAAU,kCAAkC,CAAC,KAAK,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,GAAG,EAAE,MAAM,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,GAAG,EAAE,KAAK,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,GAAG,EAAE,OAAO,GAAG,EAAE,EAAE,QAAQ,GAAG,MAAM;IACpM,KAAK,OAAO,EAAE,OAAO,QAAQ,EAAE,2BAA2B,CAAC,KAAK,CAAC,GAAG,OAAO,QAAQ,EAAE,eAAe,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,CAAC,GAAG;QAAE,UAAU,CAAC,EAAE,QAAQ,CAAA;KAAE,GAAG,OAAO,CAAC;IACjK,CAAC,QAAQ,EAAE,OAAO,EAAE,KAAK,EAAE;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,KAAK,CAAA;KAAC,GAAG,OAAO,GAAG;QAAE,IAAI,CAAC,EAAE,GAAG,CAAC;QAAC,GAAG,CAAC,EAAE,GAAG,CAAA;KAAE,CAAC;IACtG,YAAY,CAAC,EAAE,QAAQ,CAAC;CAC3B;AAKD,QAAA,MAAM,aAAa;;kBAA+E,CAAC;AACjF,KAAK,aAAa,GAAG,YAAY,CAAC,OAAO,aAAa,CAAC,CAAC;AAC1D,eAAe,aAAa,CAAC"}

package/package.json

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