@contentful/experiences-svelte 0.5.11 → 0.6.0

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)}

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';
@@ -36,17 +37,30 @@
     config,
     initialViewportId,
     metadata,
-    debug = false,
+    debug,
     renderUnknown = MissingComponent,
+    renderError = ComponentError,
   }: ServerExperienceRendererProps = $props();
 
+  // `??`, not `||`, so an explicit `debug={false}` overrides a debug-on plan.
+  const resolvedDebug = $derived(debug ?? experience?.debug ?? false);
+
   function buildContext(): RenderContext {
     const viewports = experience?.viewports ?? [];
-    const idx = experience ? getViewportIndex(experience.viewports, initialViewportId) : 0;
+    // Default to the pre-resolved viewport so first paint needs no recompute.
+    const idx = !experience
+      ? 0
+      : initialViewportId === undefined
+        ? experience.fallbackViewportIndex
+        : getViewportIndex(experience.viewports, initialViewportId);
     return {
       ...DEFAULT_CONTEXT,
-      debug,
-      metadata: { ...DEFAULT_CONTEXT.metadata, ...(metadata ?? {}) },
+      debug: resolvedDebug,
+      metadata: {
+        ...DEFAULT_CONTEXT.metadata,
+        ...(experience?.metadata ?? {}),
+        ...(metadata ?? {}),
+      },
       viewports,
       activeViewport: experience?.viewports[idx] ?? FALLBACK_VIEWPORT,
       activeViewportIndex: idx,
@@ -56,16 +70,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 resolvedDebug}
+    <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;AA0F1E,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

@@ -5,18 +5,17 @@ export interface ServerExperienceRendererProps {
     experience: PortableRenderPlan | null | undefined;
     config: Config;
     initialViewportId?: string;
-    /**
-     * Arbitrary per-render metadata, readable by descendants via
-     * `getExperience()` and by resolvers via `ctx.experience.metadata`.
-     */
+    /** Shallow-merges over the plan's `metadata`. Only needed to override it. */
     metadata?: Record<string, unknown>;
     /**
      * Observability switch. When on: renders the visible missing-component box,
      * turns the default `renderUnknown` fallback into the debug component, and
-     * auto-mounts `<DebugExperience>` after the tree.
+     * auto-mounts `<DebugExperience>` after the tree. Defaults to the plan's `debug`.
      */
     debug?: boolean;
     renderUnknown?: RenderUnknown;
+    /** Override the fallback rendered when a registered component throws. */
+    renderError?: RenderError;
 }
 export type ClientExperienceRendererProps = ServerExperienceRendererProps;
 export interface MissingComponentProps {
@@ -25,10 +24,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,6EAA6E;IAC7E,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 type { ComponentNode, ComponentRef, DesignPropValue, DesignToken, ExperienceContext, ExperienceNode, ExperiencePayload, ExperienceSourceMap, 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 type { ClientOptions, CreateClientOptions, ExperienceOptions, ResolveOptions, } from '@contentful/experiences-client';
+export { ContentfulViewDelivery, ContentfulViewDeliveryClient, DELIVERY_HOST, ExperienceFetchError, NotFoundError, PREVIEW_HOST, createClient, fetchExperience, readSourceMap, toExperiencePayload, } from '@contentful/experiences-client';
+export type { ClientOptions, CreateClientOptions, ExperienceOptions, ExperienceResponse, 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,mBAAmB,EACnB,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,EACf,aAAa,EACb,mBAAmB,GACpB,MAAM,gCAAgC,CAAC;AACxC,YAAY,EACV,aAAa,EACb,mBAAmB,EACnB,iBAAiB,EACjB,kBAAkB,EAClB,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, readSourceMap, toExperiencePayload, } from '@contentful/experiences-client';