@contentful/experiences-react 0.7.11 → 0.8.0

package/CHANGELOG.md

@@ -1,3 +1,23 @@
+## 0.8.0 (2026-08-28)
+
+### 🧱 Updated Dependencies
+
+- Updated client to 0.4.0
+- Updated design to 0.8.0
+- Updated core to 0.8.0
+
+## 0.7.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.7.11 (2026-08-27)
 
 ### 🧱 Updated Dependencies

package/README.md

@@ -50,7 +50,7 @@ useActiveViewport; // Hook used inside ClientExperienceRenderer (you'll rarely n
 ### Styling + runtime context (hooks)
 
 ```ts
-useDesignValues<T>(); // Optional hook: the same resolved design record that auto-fills props
+useDesignValues<T>(); // Escape hatch: the same resolved design record that auto-fills props
 toCss(design, options?); // Turns a design record into CSSProperties, keeping only real CSS keys
 useExperience(); // RenderContext: debug, metadata, viewports, activeViewport
 useContentfulComponent(); // Raw payload for the enclosing node (or null)
@@ -58,7 +58,7 @@ useContentfulExperienceTemplate(); // Same, for an enclosing coded Experience Te
 type ToCssOptions;
 ```
 
-Resolved design values (viewport-cascaded + token-resolved server-side) are **auto-filled onto your component's props** by key, alongside content. Styling straight from props is the recommended path; `useDesignValues()` exposes the same record for cases props don't cover. Token resolution is configured with `resolveToken` on your `Config` (`type ResolveToken`).
+Resolved design values (viewport-cascaded + token-resolved server-side) are **auto-filled onto your component's props** by key, alongside content. Styling from those props is the one recommended path. `useDesignValues()` exposes the same record as an escape hatch. Reach for it only for a nested child that isn't itself a registered component, or for design needed outside the render path (an effect, an imperative measurement) — see [Styling components](../../README.md#styling-components). Token resolution is configured with `resolveToken` on your `Config` (`type ResolveToken`).
 
 ### Re-exported types and utilities
 

package/dist/client-renderer.d.ts

@@ -1,27 +1,30 @@
 import { ReactNode } from 'react';
 import { PortableRenderPlan } from '@contentful/experiences-sdk-core';
-import { RenderUnknown } from './nodes-renderer.js';
+import { RenderUnknown, RenderError } from './nodes-renderer.js';
 import { Config } from './types.js';
+import './component-error.js';
 import './missing-component.js';
 
 interface ClientExperienceRendererProps {
     experience: PortableRenderPlan | null | undefined;
     config: Config;
-    /** Initial viewport seed; should match what the server-rendered output used. */
-    initialViewportId?: string;
     /**
-     * Arbitrary per-render metadata, readable by descendants via
-     * `useExperience()` and by resolvers via `ctx.experience.metadata`.
+     * Viewport to render for, typically derived from the request's User-Agent.
+     * Defaults to the viewport the plan was pre-resolved against.
      */
+    initialViewportId?: string;
+    /** 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;
 }
-declare function ClientExperienceRenderer({ experience, config, initialViewportId, metadata, debug, renderUnknown, }: ClientExperienceRendererProps): ReactNode;
+declare function ClientExperienceRenderer({ experience, config, initialViewportId, metadata, debug, renderUnknown, renderError, }: ClientExperienceRendererProps): ReactNode;
 
 export { ClientExperienceRenderer, type ClientExperienceRendererProps };

package/dist/client-renderer.js

@@ -1,5 +1,8 @@
 "use client";
 import { jsx, jsxs } from "react/jsx-runtime";
+import { useCallback, useState } from "react";
+import { ComponentError } from "./component-error";
+import { DiagnosticReporterContext } from "./component-error-boundary";
 import { DebugExperience } from "./debug-experience";
 import { ExperienceProvider } from "./context";
 import { MissingComponent } from "./missing-component";
@@ -21,24 +24,35 @@ function ClientExperienceRenderer({
   config,
   initialViewportId,
   metadata,
-  debug = false,
-  renderUnknown = MissingComponent
+  debug,
+  renderUnknown = MissingComponent,
+  renderError = ComponentError
 }) {
+  const [renderDiagnostics, setRenderDiagnostics] = useState([]);
+  const onDiagnostic = useCallback((error) => {
+    queueMicrotask(() => {
+      setRenderDiagnostics(
+        (prev) => prev.some((seen) => seen.message === error.message) ? prev : [...prev, error]
+      );
+    });
+  }, []);
+  const seedViewportId = initialViewportId ?? (experience ? experience.viewports[experience.fallbackViewportIndex]?.id : void 0);
+  const { activeViewportIndex } = useActiveViewport(experience?.viewports ?? [], seedViewportId);
   if (!experience) return null;
-  const { activeViewportIndex } = useActiveViewport(experience.viewports, initialViewportId);
+  const resolvedDebug = debug ?? experience.debug;
   const contextViewports = experience.viewports.map((v) => ({ ...v }));
   const activeViewport = { ...experience.viewports[activeViewportIndex] ?? FALLBACK_VIEWPORT };
   const renderContext = {
     ...DEFAULT_CONTEXT,
-    debug,
-    metadata: { ...DEFAULT_CONTEXT.metadata, ...metadata ?? {} },
+    debug: resolvedDebug,
+    metadata: { ...DEFAULT_CONTEXT.metadata, ...experience.metadata, ...metadata ?? {} },
     viewports: contextViewports,
     activeViewport,
-    activeViewportIndex
+    activeViewportIndex,
+    fallbackViewportIndex: experience.fallbackViewportIndex
   };
   return /* @__PURE__ */ jsxs(ExperienceProvider, { value: renderContext, children: [
-    debug ? /* @__PURE__ */ jsx(DebugExperience, { experience }) : null,
-    /* @__PURE__ */ jsx(
+    /* @__PURE__ */ jsx(DiagnosticReporterContext.Provider, { value: onDiagnostic, children: /* @__PURE__ */ jsx(
       NodesRenderer,
       {
         nodes: experience.nodes,
@@ -46,9 +60,18 @@ function ClientExperienceRenderer({
         viewports: experience.viewports,
         activeViewportIndex,
         fallbackViewportIndex: experience.fallbackViewportIndex,
-        renderUnknown
+        renderUnknown,
+        renderError,
+        onDiagnostic
       }
-    )
+    ) }),
+    resolvedDebug ? /* @__PURE__ */ jsx(
+      DebugExperience,
+      {
+        experience,
+        errors: [...experience.diagnostics ?? [], ...renderDiagnostics]
+      }
+    ) : null
   ] });
 }
 export {

package/dist/client-renderer.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/client-renderer.tsx"],"sourcesContent":["/*\n * Client Experience renderer. First paint matches the server renderer; after\n * hydration `useActiveViewport` takes over via `matchMedia`. Server-safe: the\n * hook returns the seeded index and registers no listeners when there's no\n * window, so SSR output matches `<ServerExperienceRenderer>`.\n */\n\n'use client';\n\nimport type { ReactNode } from 'react';\n\nimport type {\n  ExperienceContext,\n  PortableRenderPlan,\n  ViewportDef,\n} from '@contentful/experiences-sdk-core';\n\nimport { DebugExperience } from './debug-experience';\nimport { ExperienceProvider } from './context';\nimport { MissingComponent } from './missing-component';\nimport { NodesRenderer, type RenderUnknown } from './nodes-renderer';\nimport type { Config, RenderContext } from './types';\nimport { useActiveViewport } from './use-active-viewport';\n\nconst DEFAULT_CONTEXT: ExperienceContext = {\n  debug: false,\n  metadata: {},\n  viewports: [],\n};\n\nconst FALLBACK_VIEWPORT: ViewportDef = {\n  id: '_',\n  query: '*',\n  displayName: 'Default',\n  previewSize: '100%',\n};\n\nexport interface ClientExperienceRendererProps {\n  experience: PortableRenderPlan | null | undefined;\n  config: Config;\n  /** Initial viewport seed; should match what the server-rendered output used. */\n  initialViewportId?: string;\n  /**\n   * Arbitrary per-render metadata, readable by descendants via\n   * `useExperience()` and by resolvers via `ctx.experience.metadata`.\n   */\n  metadata?: Record<string, unknown>;\n  /**\n   * Observability switch. When on: renders the visible missing-component box,\n   * turns the default `renderUnknown` fallback into the debug component, and\n   * auto-mounts `<DebugExperience>` after the tree.\n   */\n  debug?: boolean;\n  renderUnknown?: RenderUnknown;\n}\n\nexport function ClientExperienceRenderer({\n  experience,\n  config,\n  initialViewportId,\n  metadata,\n  debug = false,\n  renderUnknown = MissingComponent,\n}: ClientExperienceRendererProps): ReactNode {\n  if (!experience) return null;\n  const { activeViewportIndex } = useActiveViewport(experience.viewports, initialViewportId);\n  // Copy so the context shares no object identity with the plan arrays — see\n  // the note in `server-renderer.tsx`.\n  const contextViewports = experience.viewports.map((v) => ({ ...v }));\n  const activeViewport = { ...(experience.viewports[activeViewportIndex] ?? FALLBACK_VIEWPORT) };\n\n  const renderContext: RenderContext = {\n    ...DEFAULT_CONTEXT,\n    debug,\n    metadata: { ...DEFAULT_CONTEXT.metadata, ...(metadata ?? {}) },\n    viewports: contextViewports,\n    activeViewport,\n    activeViewportIndex,\n  };\n\n  return (\n    <ExperienceProvider value={renderContext}>\n      {debug ? <DebugExperience experience={experience} /> : null}\n      <NodesRenderer\n        nodes={experience.nodes}\n        config={config}\n        viewports={experience.viewports}\n        activeViewportIndex={activeViewportIndex}\n        fallbackViewportIndex={experience.fallbackViewportIndex}\n        renderUnknown={renderUnknown}\n      />\n    </ExperienceProvider>\n  );\n}\n"],"mappings":";AAiFI,SACW,KADX;AAhEJ,SAAS,uBAAuB;AAChC,SAAS,0BAA0B;AACnC,SAAS,wBAAwB;AACjC,SAAS,qBAAyC;AAElD,SAAS,yBAAyB;AAElC,MAAM,kBAAqC;AAAA,EACzC,OAAO;AAAA,EACP,UAAU,CAAC;AAAA,EACX,WAAW,CAAC;AACd;AAEA,MAAM,oBAAiC;AAAA,EACrC,IAAI;AAAA,EACJ,OAAO;AAAA,EACP,aAAa;AAAA,EACb,aAAa;AACf;AAqBO,SAAS,yBAAyB;AAAA,EACvC;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA,QAAQ;AAAA,EACR,gBAAgB;AAClB,GAA6C;AAC3C,MAAI,CAAC,WAAY,QAAO;AACxB,QAAM,EAAE,oBAAoB,IAAI,kBAAkB,WAAW,WAAW,iBAAiB;AAGzF,QAAM,mBAAmB,WAAW,UAAU,IAAI,CAAC,OAAO,EAAE,GAAG,EAAE,EAAE;AACnE,QAAM,iBAAiB,EAAE,GAAI,WAAW,UAAU,mBAAmB,KAAK,kBAAmB;AAE7F,QAAM,gBAA+B;AAAA,IACnC,GAAG;AAAA,IACH;AAAA,IACA,UAAU,EAAE,GAAG,gBAAgB,UAAU,GAAI,YAAY,CAAC,EAAG;AAAA,IAC7D,WAAW;AAAA,IACX;AAAA,IACA;AAAA,EACF;AAEA,SACE,qBAAC,sBAAmB,OAAO,eACxB;AAAA,YAAQ,oBAAC,mBAAgB,YAAwB,IAAK;AAAA,IACvD;AAAA,MAAC;AAAA;AAAA,QACC,OAAO,WAAW;AAAA,QAClB;AAAA,QACA,WAAW,WAAW;AAAA,QACtB;AAAA,QACA,uBAAuB,WAAW;AAAA,QAClC;AAAA;AAAA,IACF;AAAA,KACF;AAEJ;","names":[]}
+{"version":3,"sources":["../src/client-renderer.tsx"],"sourcesContent":["/*\n * Client Experience renderer. First paint matches the server renderer; after\n * hydration `useActiveViewport` takes over via `matchMedia`. Server-safe: the\n * hook returns the seeded index and registers no listeners when there's no\n * window, so SSR output matches `<ServerExperienceRenderer>`.\n */\n\n'use client';\n\nimport { useCallback, useState, type ReactNode } from 'react';\n\nimport type {\n  ExperienceContext,\n  PortableRenderPlan,\n  ViewportDef,\n} from '@contentful/experiences-sdk-core';\n\nimport { ComponentError } from './component-error';\nimport { DiagnosticReporterContext } from './component-error-boundary';\nimport { DebugExperience } from './debug-experience';\nimport { ExperienceProvider } from './context';\nimport { MissingComponent } from './missing-component';\nimport { NodesRenderer, type RenderError, type RenderUnknown } from './nodes-renderer';\nimport type { Config, RenderContext } from './types';\nimport { useActiveViewport } from './use-active-viewport';\n\nconst DEFAULT_CONTEXT: ExperienceContext = {\n  debug: false,\n  metadata: {},\n  viewports: [],\n};\n\nconst FALLBACK_VIEWPORT: ViewportDef = {\n  id: '_',\n  query: '*',\n  displayName: 'Default',\n  previewSize: '100%',\n};\n\nexport interface ClientExperienceRendererProps {\n  experience: PortableRenderPlan | null | undefined;\n  config: Config;\n  /**\n   * Viewport to render for, typically derived from the request's User-Agent.\n   * Defaults to the viewport the plan was pre-resolved against.\n   */\n  initialViewportId?: string;\n  /** Shallow-merges over the plan's `metadata`. Only needed to override it. */\n  metadata?: Record<string, unknown>;\n  /**\n   * Observability switch. When on: renders the visible missing-component box,\n   * turns the default `renderUnknown` fallback into the debug component, and\n   * auto-mounts `<DebugExperience>` after the tree. Defaults to the plan's `debug`.\n   */\n  debug?: boolean;\n  renderUnknown?: RenderUnknown;\n  /** Override the fallback rendered when a registered component throws. */\n  renderError?: RenderError;\n}\n\nexport function ClientExperienceRenderer({\n  experience,\n  config,\n  initialViewportId,\n  metadata,\n  debug,\n  renderUnknown = MissingComponent,\n  renderError = ComponentError,\n}: ClientExperienceRendererProps): ReactNode {\n  const [renderDiagnostics, setRenderDiagnostics] = useState<Error[]>([]);\n  // A `setState` updater rather than the SSR renderer's plain-array push: this\n  // tree stays mounted and interactive, so a component that throws well after\n  // first paint (a later re-render, an event handler) must still make\n  // `<DebugExperience>` re-render with the new diagnostic — a mutated array\n  // wouldn't trigger that.\n  //\n  // `queueMicrotask` defers the actual `setState` call: most of these\n  // diagnostics (component-not-registered, malformed-slot,\n  // experience-template-not-registered) are reported synchronously from\n  // *inside* NodeRenderer's own render body, i.e. while React is mid-render\n  // of a descendant — calling this component's setState right there is\n  // exactly React's \"Cannot update a component while rendering a different\n  // component\" anti-pattern. Escaping to a microtask (same \"break the\n  // synchronous call chain\" rationale as core's resolveData deferral)\n  // schedules the update for after the current render/commit fully unwinds.\n  // `component-render-error`, reported from `componentDidCatch`, is already\n  // commit-phase-safe — deferring it too is harmless and keeps one code path.\n  // This is client-only (NodeRenderer's own onDiagnostic call is unchanged\n  // and stays synchronous — see nodes-renderer.tsx for why SSR needs that):\n  // `ServerExperienceRenderer` threads a plain synchronous array-push\n  // closure instead of this setState-backed one, so SSR is unaffected.\n  const onDiagnostic = useCallback((error: Error) => {\n    queueMicrotask(() => {\n      // Dedup by message, the guard `NodeRenderer` used to hold in a `useRef`.\n      // It lives here so that module stays hook-free and therefore usable from\n      // a React Server Component. Returning `prev` unchanged also skips a\n      // pointless re-render, which matters more here than on the server: every\n      // ancestor re-render re-reports the same diagnostic.\n      setRenderDiagnostics((prev) =>\n        prev.some((seen) => seen.message === error.message) ? prev : [...prev, error]\n      );\n    });\n  }, []);\n\n  // Seed from the plan so first paint matches the server renderer. Computed\n  // before the `experience` guard because the hook below cannot be called\n  // conditionally.\n  const seedViewportId =\n    initialViewportId ??\n    (experience ? experience.viewports[experience.fallbackViewportIndex]?.id : undefined);\n  const { activeViewportIndex } = useActiveViewport(experience?.viewports ?? [], seedViewportId);\n  if (!experience) return null;\n  // `??`, not `||`, so an explicit `debug={false}` overrides a debug-on plan.\n  const resolvedDebug = debug ?? experience.debug;\n  // Copy so the context shares no object identity with the plan arrays — see\n  // the note in `server-renderer.tsx`.\n  const contextViewports = experience.viewports.map((v) => ({ ...v }));\n  const activeViewport = { ...(experience.viewports[activeViewportIndex] ?? FALLBACK_VIEWPORT) };\n\n  const renderContext: RenderContext = {\n    ...DEFAULT_CONTEXT,\n    debug: resolvedDebug,\n    metadata: { ...DEFAULT_CONTEXT.metadata, ...experience.metadata, ...(metadata ?? {}) },\n    viewports: contextViewports,\n    activeViewport,\n    activeViewportIndex,\n    fallbackViewportIndex: experience.fallbackViewportIndex,\n  };\n\n  return (\n    <ExperienceProvider value={renderContext}>\n      {/*\n        Established here, not in `ServerExperienceRenderer`: this Provider\n        (and the closure it carries) never crosses a Server→Client boundary\n        because everything from `ClientExperienceRenderer` down is already\n        client-rendered. `ComponentErrorBoundary` reads it via `contextType`\n        to report a render-time throw without receiving a callback prop —\n        see component-error-boundary.tsx for why that specifically matters.\n      */}\n      <DiagnosticReporterContext.Provider value={onDiagnostic}>\n        <NodesRenderer\n          nodes={experience.nodes}\n          config={config}\n          viewports={experience.viewports}\n          activeViewportIndex={activeViewportIndex}\n          fallbackViewportIndex={experience.fallbackViewportIndex}\n          renderUnknown={renderUnknown}\n          renderError={renderError}\n          onDiagnostic={onDiagnostic}\n        />\n      </DiagnosticReporterContext.Provider>\n      {resolvedDebug ? (\n        <DebugExperience\n          experience={experience}\n          errors={[...(experience.diagnostics ?? []), ...renderDiagnostics]}\n        />\n      ) : null}\n    </ExperienceProvider>\n  );\n}\n"],"mappings":";AAkII,SAUI,KAVJ;AAzHJ,SAAS,aAAa,gBAAgC;AAQtD,SAAS,sBAAsB;AAC/B,SAAS,iCAAiC;AAC1C,SAAS,uBAAuB;AAChC,SAAS,0BAA0B;AACnC,SAAS,wBAAwB;AACjC,SAAS,qBAA2D;AAEpE,SAAS,yBAAyB;AAElC,MAAM,kBAAqC;AAAA,EACzC,OAAO;AAAA,EACP,UAAU,CAAC;AAAA,EACX,WAAW,CAAC;AACd;AAEA,MAAM,oBAAiC;AAAA,EACrC,IAAI;AAAA,EACJ,OAAO;AAAA,EACP,aAAa;AAAA,EACb,aAAa;AACf;AAuBO,SAAS,yBAAyB;AAAA,EACvC;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA,gBAAgB;AAAA,EAChB,cAAc;AAChB,GAA6C;AAC3C,QAAM,CAAC,mBAAmB,oBAAoB,IAAI,SAAkB,CAAC,CAAC;AAsBtE,QAAM,eAAe,YAAY,CAAC,UAAiB;AACjD,mBAAe,MAAM;AAMnB;AAAA,QAAqB,CAAC,SACpB,KAAK,KAAK,CAAC,SAAS,KAAK,YAAY,MAAM,OAAO,IAAI,OAAO,CAAC,GAAG,MAAM,KAAK;AAAA,MAC9E;AAAA,IACF,CAAC;AAAA,EACH,GAAG,CAAC,CAAC;AAKL,QAAM,iBACJ,sBACC,aAAa,WAAW,UAAU,WAAW,qBAAqB,GAAG,KAAK;AAC7E,QAAM,EAAE,oBAAoB,IAAI,kBAAkB,YAAY,aAAa,CAAC,GAAG,cAAc;AAC7F,MAAI,CAAC,WAAY,QAAO;AAExB,QAAM,gBAAgB,SAAS,WAAW;AAG1C,QAAM,mBAAmB,WAAW,UAAU,IAAI,CAAC,OAAO,EAAE,GAAG,EAAE,EAAE;AACnE,QAAM,iBAAiB,EAAE,GAAI,WAAW,UAAU,mBAAmB,KAAK,kBAAmB;AAE7F,QAAM,gBAA+B;AAAA,IACnC,GAAG;AAAA,IACH,OAAO;AAAA,IACP,UAAU,EAAE,GAAG,gBAAgB,UAAU,GAAG,WAAW,UAAU,GAAI,YAAY,CAAC,EAAG;AAAA,IACrF,WAAW;AAAA,IACX;AAAA,IACA;AAAA,IACA,uBAAuB,WAAW;AAAA,EACpC;AAEA,SACE,qBAAC,sBAAmB,OAAO,eASzB;AAAA,wBAAC,0BAA0B,UAA1B,EAAmC,OAAO,cACzC;AAAA,MAAC;AAAA;AAAA,QACC,OAAO,WAAW;AAAA,QAClB;AAAA,QACA,WAAW,WAAW;AAAA,QACtB;AAAA,QACA,uBAAuB,WAAW;AAAA,QAClC;AAAA,QACA;AAAA,QACA;AAAA;AAAA,IACF,GACF;AAAA,IACC,gBACC;AAAA,MAAC;AAAA;AAAA,QACC;AAAA,QACA,QAAQ,CAAC,GAAI,WAAW,eAAe,CAAC,GAAI,GAAG,iBAAiB;AAAA;AAAA,IAClE,IACE;AAAA,KACN;AAEJ;","names":[]}

package/dist/component-error-boundary.d.ts

@@ -0,0 +1,65 @@
+import * as react from 'react';
+import { Component, ReactNode } from 'react';
+
+declare const DiagnosticReporterContext: react.Context<((error: Error) => void) | null>;
+interface ComponentErrorBoundaryProps {
+    children: ReactNode;
+    fallback: ReactNode;
+    /** Plain, serializable identity — never a callback; see the file doc comment. */
+    componentId: string;
+    kind: string;
+    nodeId?: string;
+}
+interface ComponentErrorBoundaryState {
+    hasError: boolean;
+}
+/**
+ * Per-node isolation for a customer component that throws during render. A
+ * class component is the only mechanism React offers for this — there is no
+ * hook equivalent.
+ *
+ * `getDerivedStateFromError`/`componentDidCatch` do NOT catch at all during
+ * React's SSR — neither the legacy `renderToString`/`renderToStaticMarkup`
+ * NOR the modern streaming `renderToPipeableStream`/`renderToReadableStream`
+ * (the one Next.js's App Router actually uses) run the class-error-boundary
+ * machinery server-side. What the modern streaming renderer DOES support is
+ * Suspense-based recovery: if a `<Suspense>` boundary's content throws during
+ * the server walk, Fizz emits that Suspense's `fallback` as the initial HTML
+ * and defers real rendering of that subtree to the client after hydration —
+ * "switch to client rendering" in React's own error message. Wrapping
+ * `children` in an internal `<Suspense fallback={fallback}>` (same fallback
+ * either way) is what makes this component degrade gracefully server-side:
+ * Fizz isolates the failing node without our own `hasError` branch ever
+ * running server-side. Once the client hydrates and re-executes that
+ * Suspense boundary's content, if the throw repeats, the client fiber
+ * reconciler *does* run `getDerivedStateFromError` and re-renders with
+ * `hasError: true` — siblings render normally because Fizz isolates
+ * per-Suspense-boundary.
+ *
+ * Net effect: the diagnostic fires only client-side — after hydration for an
+ * SSR-rendered page, or immediately for a client-only render.
+ * `ServerExperienceRenderer`'s own SSR-time diagnostics list can therefore
+ * never contain a `component-render-error` entry; only
+ * `ClientExperienceRenderer`'s reactive collector can, which is exactly why
+ * that collector is `useState`-based rather than a plain array. See the
+ * README's error-handling section.
+ *
+ * The legacy synchronous `renderToString`/`renderToStaticMarkup` APIs also
+ * honor the Suspense `fallback` for a thrown Error, not just a thrown
+ * thenable — so a customer calling those directly still gets the graceful
+ * fallback and sibling isolation. The difference from the streaming renderer
+ * is that legacy output carries no hydration data and gets no client-side
+ * retry: the fallback markup is permanent, and — same as above — no
+ * diagnostic is ever recorded for that render, since our `hasError` branch
+ * still never runs server-side.
+ */
+declare class ComponentErrorBoundary extends Component<ComponentErrorBoundaryProps, ComponentErrorBoundaryState> {
+    static contextType: react.Context<((error: Error) => void) | null>;
+    context: React.ContextType<typeof DiagnosticReporterContext>;
+    state: ComponentErrorBoundaryState;
+    static getDerivedStateFromError(): ComponentErrorBoundaryState;
+    componentDidCatch(error: unknown): void;
+    render(): ReactNode;
+}
+
+export { ComponentErrorBoundary, DiagnosticReporterContext };

package/dist/component-error-boundary.js

@@ -0,0 +1,31 @@
+"use client";
+import { jsx } from "react/jsx-runtime";
+import { Component, Suspense, createContext } from "react";
+const DiagnosticReporterContext = createContext(null);
+class ComponentErrorBoundary extends Component {
+  static contextType = DiagnosticReporterContext;
+  state = { hasError: false };
+  static getDerivedStateFromError() {
+    return { hasError: true };
+  }
+  componentDidCatch(error) {
+    const { componentId, kind, nodeId } = this.props;
+    const reason = error instanceof Error ? error.message : String(error);
+    const message = `Component "${componentId}" (${kind}${nodeId ? `, node "${nodeId}"` : ""}) threw while rendering: ${reason}. Rendering the error fallback instead of crashing the surrounding tree.`;
+    if (typeof console !== "undefined") {
+      console.warn(`[@contentful/experiences-react] ${message}`);
+    }
+    this.context?.(new Error(message, { cause: error instanceof Error ? error : void 0 }));
+  }
+  render() {
+    if (this.state.hasError) {
+      return this.props.fallback;
+    }
+    return /* @__PURE__ */ jsx(Suspense, { fallback: this.props.fallback, children: this.props.children });
+  }
+}
+export {
+  ComponentErrorBoundary,
+  DiagnosticReporterContext
+};
+//# sourceMappingURL=component-error-boundary.js.map

package/dist/component-error-boundary.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/component-error-boundary.tsx"],"sourcesContent":["/*\n * Split into its own file, `'use client'`-marked, because it's a class\n * component: Next.js's RSC bundler statically rejects a class component\n * import from a file with no directive (\"You're importing a class component.\n * It only works in a Client Component...\"), even though the class itself\n * renders fine under every SSR path this SDK supports. `nodes-renderer.tsx`\n * stays directive-free so it can still be imported from `server-renderer.tsx`\n * (a genuine Server Component); Server Components importing Client\n * Components is the normal RSC pattern, so this split costs nothing.\n *\n * Reporting goes through `DiagnosticReporterContext`, not a prop, for a\n * second RSC reason beyond the class-component one above: `NodeRenderer`\n * runs as part of the SERVER render when reached from\n * `ServerExperienceRenderer` (a real Server Component with no directive), and\n * React refuses to serialize a plain closure passed as a Client Component\n * prop from there (\"Event handlers cannot be passed to Client Component\n * props\"). Only `ClientExperienceRenderer` establishes this context (with a\n * `Provider` element that, being entirely within its own already-client-\n * rendered tree, never crosses that boundary); `context` reads `null` under\n * `ServerExperienceRenderer`, which is fine because `componentDidCatch` never\n * runs there anyway (see the class doc comment).\n */\n'use client';\n\nimport { Component, Suspense, createContext, type ReactNode } from 'react';\n\nexport const DiagnosticReporterContext = createContext<((error: Error) => void) | null>(null);\n\ninterface ComponentErrorBoundaryProps {\n  children: ReactNode;\n  fallback: ReactNode;\n  /** Plain, serializable identity — never a callback; see the file doc comment. */\n  componentId: string;\n  kind: string;\n  nodeId?: string;\n}\n\ninterface ComponentErrorBoundaryState {\n  hasError: boolean;\n}\n\n/**\n * Per-node isolation for a customer component that throws during render. A\n * class component is the only mechanism React offers for this — there is no\n * hook equivalent.\n *\n * `getDerivedStateFromError`/`componentDidCatch` do NOT catch at all during\n * React's SSR — neither the legacy `renderToString`/`renderToStaticMarkup`\n * NOR the modern streaming `renderToPipeableStream`/`renderToReadableStream`\n * (the one Next.js's App Router actually uses) run the class-error-boundary\n * machinery server-side. What the modern streaming renderer DOES support is\n * Suspense-based recovery: if a `<Suspense>` boundary's content throws during\n * the server walk, Fizz emits that Suspense's `fallback` as the initial HTML\n * and defers real rendering of that subtree to the client after hydration —\n * \"switch to client rendering\" in React's own error message. Wrapping\n * `children` in an internal `<Suspense fallback={fallback}>` (same fallback\n * either way) is what makes this component degrade gracefully server-side:\n * Fizz isolates the failing node without our own `hasError` branch ever\n * running server-side. Once the client hydrates and re-executes that\n * Suspense boundary's content, if the throw repeats, the client fiber\n * reconciler *does* run `getDerivedStateFromError` and re-renders with\n * `hasError: true` — siblings render normally because Fizz isolates\n * per-Suspense-boundary.\n *\n * Net effect: the diagnostic fires only client-side — after hydration for an\n * SSR-rendered page, or immediately for a client-only render.\n * `ServerExperienceRenderer`'s own SSR-time diagnostics list can therefore\n * never contain a `component-render-error` entry; only\n * `ClientExperienceRenderer`'s reactive collector can, which is exactly why\n * that collector is `useState`-based rather than a plain array. See the\n * README's error-handling section.\n *\n * The legacy synchronous `renderToString`/`renderToStaticMarkup` APIs also\n * honor the Suspense `fallback` for a thrown Error, not just a thrown\n * thenable — so a customer calling those directly still gets the graceful\n * fallback and sibling isolation. The difference from the streaming renderer\n * is that legacy output carries no hydration data and gets no client-side\n * retry: the fallback markup is permanent, and — same as above — no\n * diagnostic is ever recorded for that render, since our `hasError` branch\n * still never runs server-side.\n */\nexport class ComponentErrorBoundary extends Component<\n  ComponentErrorBoundaryProps,\n  ComponentErrorBoundaryState\n> {\n  static override contextType = DiagnosticReporterContext;\n  declare context: React.ContextType<typeof DiagnosticReporterContext>;\n\n  override state: ComponentErrorBoundaryState = { hasError: false };\n\n  static getDerivedStateFromError(): ComponentErrorBoundaryState {\n    return { hasError: true };\n  }\n\n  override componentDidCatch(error: unknown): void {\n    const { componentId, kind, nodeId } = this.props;\n    const reason = error instanceof Error ? error.message : String(error);\n    const message =\n      `Component \"${componentId}\" (${kind}${nodeId ? `, node \"${nodeId}\"` : ''}) threw ` +\n      `while rendering: ${reason}. Rendering the error fallback instead of crashing the ` +\n      `surrounding tree.`;\n    if (typeof console !== 'undefined') {\n      console.warn(`[@contentful/experiences-react] ${message}`);\n    }\n    this.context?.(new Error(message, { cause: error instanceof Error ? error : undefined }));\n  }\n\n  override render(): ReactNode {\n    if (this.state.hasError) {\n      return this.props.fallback;\n    }\n    return <Suspense fallback={this.props.fallback}>{this.props.children}</Suspense>;\n  }\n}\n"],"mappings":";AA+GW;AAvFX,SAAS,WAAW,UAAU,qBAAqC;AAE5D,MAAM,4BAA4B,cAA+C,IAAI;AAuDrF,MAAM,+BAA+B,UAG1C;AAAA,EACA,OAAgB,cAAc;AAAA,EAGrB,QAAqC,EAAE,UAAU,MAAM;AAAA,EAEhE,OAAO,2BAAwD;AAC7D,WAAO,EAAE,UAAU,KAAK;AAAA,EAC1B;AAAA,EAES,kBAAkB,OAAsB;AAC/C,UAAM,EAAE,aAAa,MAAM,OAAO,IAAI,KAAK;AAC3C,UAAM,SAAS,iBAAiB,QAAQ,MAAM,UAAU,OAAO,KAAK;AACpE,UAAM,UACJ,cAAc,WAAW,MAAM,IAAI,GAAG,SAAS,WAAW,MAAM,MAAM,EAAE,4BACpD,MAAM;AAE5B,QAAI,OAAO,YAAY,aAAa;AAClC,cAAQ,KAAK,mCAAmC,OAAO,EAAE;AAAA,IAC3D;AACA,SAAK,UAAU,IAAI,MAAM,SAAS,EAAE,OAAO,iBAAiB,QAAQ,QAAQ,OAAU,CAAC,CAAC;AAAA,EAC1F;AAAA,EAES,SAAoB;AAC3B,QAAI,KAAK,MAAM,UAAU;AACvB,aAAO,KAAK,MAAM;AAAA,IACpB;AACA,WAAO,oBAAC,YAAS,UAAU,KAAK,MAAM,UAAW,eAAK,MAAM,UAAS;AAAA,EACvE;AACF;","names":[]}

package/dist/component-error.d.ts

@@ -0,0 +1,12 @@
+import { ReactNode } from 'react';
+
+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;
+}
+declare function ComponentError({ componentId, nodeId, message }: ComponentErrorProps): ReactNode;
+
+export { ComponentError, type ComponentErrorProps };

package/dist/component-error.js

@@ -0,0 +1,34 @@
+"use client";
+import { jsx, jsxs } from "react/jsx-runtime";
+import { useExperience } from "./context";
+function ComponentError({ componentId, nodeId, message }) {
+  const { debug } = useExperience();
+  if (!debug) return null;
+  return /* @__PURE__ */ jsxs(
+    "div",
+    {
+      style: {
+        border: "2px solid #b91c1c",
+        padding: "1rem",
+        color: "#b91c1c",
+        background: "#fff",
+        fontFamily: "ui-monospace, SFMono-Regular, Menlo, monospace",
+        fontSize: "0.8125rem"
+      },
+      "data-experiences-render-error": componentId,
+      children: [
+        /* @__PURE__ */ jsxs("strong", { children: [
+          "Component \u2018",
+          componentId,
+          "\u2019 threw while rendering"
+        ] }),
+        /* @__PURE__ */ jsx("p", { style: { margin: "0.5rem 0" }, children: "This component is registered but threw during render. Rendering this fallback instead of crashing the surrounding tree." }),
+        /* @__PURE__ */ jsx("pre", { style: { margin: 0, whiteSpace: "pre-wrap" }, children: JSON.stringify({ componentId, nodeId: nodeId ?? null, message: message ?? null }, null, 2) })
+      ]
+    }
+  );
+}
+export {
+  ComponentError
+};
+//# sourceMappingURL=component-error.js.map

package/dist/component-error.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/component-error.tsx"],"sourcesContent":["/*\n * Default fallback rendered when a registered component throws while\n * rendering. Sibling of `MissingComponent` — same debug-gated behavior\n * (visible box in debug mode, silent null otherwise), visually distinct\n * (different color/label) so a customer can tell \"not registered\" apart from\n * \"registered but threw\" at a glance. The diagnostic + console.warn for this\n * failure mode are recorded once, at the error-boundary call site in\n * `nodes-renderer.tsx` — not here — so they still fire even when a customer\n * overrides `renderError` with their own fallback.\n */\n'use client';\n\nimport type { ReactNode } from 'react';\n\nimport { useExperience } from './context';\n\nexport interface ComponentErrorProps {\n  componentId: string;\n  /** Optional — only present when the payload supplied an id for this node. */\n  nodeId?: string;\n  /** The caught error's message, when available. */\n  message?: string;\n}\n\nexport function ComponentError({ componentId, nodeId, message }: ComponentErrorProps): ReactNode {\n  const { debug } = useExperience();\n  if (!debug) return null;\n  return (\n    <div\n      style={{\n        border: '2px solid #b91c1c',\n        padding: '1rem',\n        color: '#b91c1c',\n        background: '#fff',\n        fontFamily: 'ui-monospace, SFMono-Regular, Menlo, monospace',\n        fontSize: '0.8125rem',\n      }}\n      data-experiences-render-error={componentId}\n    >\n      <strong>Component &lsquo;{componentId}&rsquo; threw while rendering</strong>\n      <p style={{ margin: '0.5rem 0' }}>\n        This component is registered but threw during render. Rendering this fallback instead of\n        crashing the surrounding tree.\n      </p>\n      <pre style={{ margin: 0, whiteSpace: 'pre-wrap' }}>\n        {JSON.stringify({ componentId, nodeId: nodeId ?? null, message: message ?? null }, null, 2)}\n      </pre>\n    </div>\n  );\n}\n"],"mappings":";AAuCM,SACA,KADA;AAzBN,SAAS,qBAAqB;AAUvB,SAAS,eAAe,EAAE,aAAa,QAAQ,QAAQ,GAAmC;AAC/F,QAAM,EAAE,MAAM,IAAI,cAAc;AAChC,MAAI,CAAC,MAAO,QAAO;AACnB,SACE;AAAA,IAAC;AAAA;AAAA,MACC,OAAO;AAAA,QACL,QAAQ;AAAA,QACR,SAAS;AAAA,QACT,OAAO;AAAA,QACP,YAAY;AAAA,QACZ,YAAY;AAAA,QACZ,UAAU;AAAA,MACZ;AAAA,MACA,iCAA+B;AAAA,MAE/B;AAAA,6BAAC,YAAO;AAAA;AAAA,UAAkB;AAAA,UAAY;AAAA,WAA6B;AAAA,QACnE,oBAAC,OAAE,OAAO,EAAE,QAAQ,WAAW,GAAG,qIAGlC;AAAA,QACA,oBAAC,SAAI,OAAO,EAAE,QAAQ,GAAG,YAAY,WAAW,GAC7C,eAAK,UAAU,EAAE,aAAa,QAAQ,UAAU,MAAM,SAAS,WAAW,KAAK,GAAG,MAAM,CAAC,GAC5F;AAAA;AAAA;AAAA,EACF;AAEJ;","names":[]}

package/dist/context.d.ts

@@ -1,6 +1,6 @@
 import { ReactNode } from 'react';
-import { ContentfulComponent, ContentfulExperienceTemplate, RenderContext } from './types.js';
-import '@contentful/experiences-sdk-core';
+import { ContentfulComponent, ContentfulExperienceTemplate } from './types.js';
+import { RenderContext } from '@contentful/experiences-sdk-core';
 
 declare function ExperienceProvider({ value, children, }: {
     value: RenderContext;

package/dist/debug-experience.d.ts

@@ -6,7 +6,16 @@ interface DebugExperienceProps {
     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[];
 }
-declare function DebugExperience({ experience, defaultOpen, }: DebugExperienceProps): ReactNode;
+declare function DebugExperience({ experience, defaultOpen, errors, }: DebugExperienceProps): ReactNode;
 
 export { DebugExperience, type DebugExperienceProps };

package/dist/debug-experience.js

@@ -1,15 +1,17 @@
 import { jsx, jsxs } from "react/jsx-runtime";
 function DebugExperience({
   experience,
-  defaultOpen = false
+  defaultOpen = false,
+  errors = []
 }) {
   const nodeCount = experience.nodes.length;
   const templateIds = experience.nodes.filter((node) => node.registration.kind === "experienceTemplate").map((node) => node.registration.id);
   const summary = `Experience debug \u2014 ${nodeCount} top-level node${nodeCount === 1 ? "" : "s"}${templateIds.length ? `, experience template${templateIds.length === 1 ? "" : "s"}: ${templateIds.join(", ")}` : ""}`;
+  const open = defaultOpen || errors.length > 0;
   return /* @__PURE__ */ jsxs(
     "details",
     {
-      open: defaultOpen,
+      open,
       "data-experiences-debug": true,
       style: {
         margin: "1rem 0",
@@ -34,6 +36,7 @@ function DebugExperience({
             children: summary
           }
         ),
+        errors.length > 0 ? /* @__PURE__ */ jsx(DiagnosticList, { errors }) : null,
         /* @__PURE__ */ jsx(
           "pre",
           {
@@ -52,6 +55,9 @@ function DebugExperience({
     }
   );
 }
+function DiagnosticList({ errors }) {
+  return /* @__PURE__ */ jsx("ul", { "data-experiences-debug-errors": true, children: errors.map((error, index) => /* @__PURE__ */ jsx("li", { children: error.message }, index)) });
+}
 function safeStringify(value) {
   const seen = /* @__PURE__ */ new WeakSet();
   try {
@@ -69,7 +75,8 @@ function safeStringify(value) {
       2
     );
   } catch (err) {
-    return `[DebugExperience: could not serialize plan \u2014 ${err.message}]`;
+    const reason = err instanceof Error ? err.message : String(err);
+    return `[DebugExperience: could not serialize plan \u2014 ${reason}]`;
   }
 }
 export {

package/dist/debug-experience.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/debug-experience.tsx"],"sourcesContent":["/*\n * First-party debug panel. Renders the resolved Experience plan as pretty\n * JSON so a customer can see exactly what the SDK interpreted from the payload\n * — node tree, registrations, resolved props, viewports.\n *\n * Two ways to use it:\n *  - Auto-mounted by the renderers when `debug` is on (above the tree).\n *  - Mounted manually anywhere: `<DebugExperience experience={plan} />`.\n *\n * v1 is just the JSON dump wrapped in a native <details> so it collapses\n * without any client JS (safe in server components). Room to grow into a\n * node-tree explorer, viewport indicator, and resolveData timing panel — kept\n * deliberately small for now.\n *\n * No React hooks here on purpose: it must render in both server and client\n * renderer subtrees.\n */\n\nimport type { ReactNode } from 'react';\n\nimport type { PortableRenderPlan } from '@contentful/experiences-sdk-core';\n\nexport interface DebugExperienceProps {\n  /** The resolved plan to inspect (what a renderer receives as `experience`). */\n  experience: PortableRenderPlan;\n  /** Start expanded. Defaults to collapsed to stay out of the way. */\n  defaultOpen?: boolean;\n}\n\nexport function DebugExperience({\n  experience,\n  defaultOpen = false,\n}: DebugExperienceProps): ReactNode {\n  const nodeCount = experience.nodes.length;\n  // Coded Experience Templates are ordinary top-level nodes, so name them from\n  // the node list — a composite Experience simply has none to report.\n  const templateIds = experience.nodes\n    .filter((node) => node.registration.kind === 'experienceTemplate')\n    .map((node) => node.registration.id);\n  const summary = `Experience debug — ${nodeCount} top-level node${nodeCount === 1 ? '' : 's'}${\n    templateIds.length\n      ? `, experience template${templateIds.length === 1 ? '' : 's'}: ${templateIds.join(', ')}`\n      : ''\n  }`;\n\n  return (\n    <details\n      open={defaultOpen}\n      data-experiences-debug\n      style={{\n        margin: '1rem 0',\n        border: '1px solid #6b7280',\n        borderRadius: '6px',\n        background: '#0b1021',\n        color: '#e2e8f0',\n        fontFamily: 'ui-monospace, SFMono-Regular, Menlo, monospace',\n        fontSize: '0.75rem',\n        overflow: 'hidden',\n      }}\n    >\n      <summary\n        style={{\n          cursor: 'pointer',\n          padding: '0.5rem 0.75rem',\n          background: '#111827',\n          userSelect: 'none',\n        }}\n      >\n        {summary}\n      </summary>\n      <pre\n        style={{\n          margin: 0,\n          padding: '0.75rem',\n          overflow: 'auto',\n          maxHeight: '32rem',\n          whiteSpace: 'pre-wrap',\n          wordBreak: 'break-word',\n        }}\n      >\n        {safeStringify(experience)}\n      </pre>\n    </details>\n  );\n}\n\n/**\n * JSON.stringify with a circular-reference guard. A resolved plan is plain\n * data, but a customer's `resolveData` could stash a non-serializable value on\n * `props.resolved` — degrade to a placeholder rather than throwing inside a\n * debug panel.\n */\nfunction safeStringify(value: unknown): string {\n  const seen = new WeakSet<object>();\n  try {\n    return JSON.stringify(\n      value,\n      (_key, val) => {\n        if (typeof val === 'object' && val !== null) {\n          if (seen.has(val)) return '[Circular]';\n          seen.add(val);\n        }\n        if (typeof val === 'function') return `[Function ${val.name || 'anonymous'}]`;\n        if (typeof val === 'undefined') return '[undefined]';\n        return val;\n      },\n      2\n    );\n  } catch (err) {\n    return `[DebugExperience: could not serialize plan — ${(err as Error).message}]`;\n  }\n}\n"],"mappings":"AA8CI,SAcE,KAdF;AAjBG,SAAS,gBAAgB;AAAA,EAC9B;AAAA,EACA,cAAc;AAChB,GAAoC;AAClC,QAAM,YAAY,WAAW,MAAM;AAGnC,QAAM,cAAc,WAAW,MAC5B,OAAO,CAAC,SAAS,KAAK,aAAa,SAAS,oBAAoB,EAChE,IAAI,CAAC,SAAS,KAAK,aAAa,EAAE;AACrC,QAAM,UAAU,2BAAsB,SAAS,kBAAkB,cAAc,IAAI,KAAK,GAAG,GACzF,YAAY,SACR,wBAAwB,YAAY,WAAW,IAAI,KAAK,GAAG,KAAK,YAAY,KAAK,IAAI,CAAC,KACtF,EACN;AAEA,SACE;AAAA,IAAC;AAAA;AAAA,MACC,MAAM;AAAA,MACN,0BAAsB;AAAA,MACtB,OAAO;AAAA,QACL,QAAQ;AAAA,QACR,QAAQ;AAAA,QACR,cAAc;AAAA,QACd,YAAY;AAAA,QACZ,OAAO;AAAA,QACP,YAAY;AAAA,QACZ,UAAU;AAAA,QACV,UAAU;AAAA,MACZ;AAAA,MAEA;AAAA;AAAA,UAAC;AAAA;AAAA,YACC,OAAO;AAAA,cACL,QAAQ;AAAA,cACR,SAAS;AAAA,cACT,YAAY;AAAA,cACZ,YAAY;AAAA,YACd;AAAA,YAEC;AAAA;AAAA,QACH;AAAA,QACA;AAAA,UAAC;AAAA;AAAA,YACC,OAAO;AAAA,cACL,QAAQ;AAAA,cACR,SAAS;AAAA,cACT,UAAU;AAAA,cACV,WAAW;AAAA,cACX,YAAY;AAAA,cACZ,WAAW;AAAA,YACb;AAAA,YAEC,wBAAc,UAAU;AAAA;AAAA,QAC3B;AAAA;AAAA;AAAA,EACF;AAEJ;AAQA,SAAS,cAAc,OAAwB;AAC7C,QAAM,OAAO,oBAAI,QAAgB;AACjC,MAAI;AACF,WAAO,KAAK;AAAA,MACV;AAAA,MACA,CAAC,MAAM,QAAQ;AACb,YAAI,OAAO,QAAQ,YAAY,QAAQ,MAAM;AAC3C,cAAI,KAAK,IAAI,GAAG,EAAG,QAAO;AAC1B,eAAK,IAAI,GAAG;AAAA,QACd;AACA,YAAI,OAAO,QAAQ,WAAY,QAAO,aAAa,IAAI,QAAQ,WAAW;AAC1E,YAAI,OAAO,QAAQ,YAAa,QAAO;AACvC,eAAO;AAAA,MACT;AAAA,MACA;AAAA,IACF;AAAA,EACF,SAAS,KAAK;AACZ,WAAO,qDAAiD,IAAc,OAAO;AAAA,EAC/E;AACF;","names":[]}
+{"version":3,"sources":["../src/debug-experience.tsx"],"sourcesContent":["/*\n * First-party debug panel. Renders the resolved Experience plan as pretty\n * JSON so a customer can see exactly what the SDK interpreted from the payload\n * — node tree, registrations, resolved props, viewports.\n *\n * Two ways to use it:\n *  - Auto-mounted by the renderers when `debug` is on (above the tree).\n *  - Mounted manually anywhere: `<DebugExperience experience={plan} />`.\n *\n * v1 is just the JSON dump wrapped in a native <details> so it collapses\n * without any client JS (safe in server components). Room to grow into a\n * node-tree explorer, viewport indicator, and resolveData timing panel — kept\n * deliberately small for now.\n *\n * No React hooks here on purpose: it must render in both server and client\n * renderer subtrees.\n */\n\nimport type { ReactNode } from 'react';\n\nimport type { PortableRenderPlan } from '@contentful/experiences-sdk-core';\n\nexport interface DebugExperienceProps {\n  /** The resolved plan to inspect (what a renderer receives as `experience`). */\n  experience: PortableRenderPlan;\n  /** Start expanded. Defaults to collapsed to stay out of the way. */\n  defaultOpen?: boolean;\n  /**\n   * Resolve-time + render-time diagnostics for this render, merged by the\n   * caller (`ServerExperienceRenderer` / `ClientExperienceRenderer`). Plain\n   * `Error`s — the two cases that wrap a real caught exception\n   * (`component-render-error`, `resolve-data-failed`) set `.cause` to the\n   * original error, inspectable via `console.error` or `error.cause.stack`.\n   * Defaults to `[]` for a manually-mounted `<DebugExperience>`.\n   */\n  errors?: Error[];\n}\n\nexport function DebugExperience({\n  experience,\n  defaultOpen = false,\n  errors = [],\n}: DebugExperienceProps): ReactNode {\n  const nodeCount = experience.nodes.length;\n  // Coded Experience Templates are ordinary top-level nodes, so name them from\n  // the node list — a composite Experience simply has none to report.\n  const templateIds = experience.nodes\n    .filter((node) => node.registration.kind === 'experienceTemplate')\n    .map((node) => node.registration.id);\n  const summary = `Experience debug — ${nodeCount} top-level node${nodeCount === 1 ? '' : 's'}${\n    templateIds.length\n      ? `, experience template${templateIds.length === 1 ? '' : 's'}: ${templateIds.join(', ')}`\n      : ''\n  }`;\n\n  // Auto-expand whenever there's something to see, even if the caller didn't\n  // explicitly ask — a beta customer shouldn't have to know to click into a\n  // collapsed panel to discover that something went wrong.\n  const open = defaultOpen || errors.length > 0;\n\n  return (\n    <details\n      open={open}\n      data-experiences-debug\n      style={{\n        margin: '1rem 0',\n        border: '1px solid #6b7280',\n        borderRadius: '6px',\n        background: '#0b1021',\n        color: '#e2e8f0',\n        fontFamily: 'ui-monospace, SFMono-Regular, Menlo, monospace',\n        fontSize: '0.75rem',\n        overflow: 'hidden',\n      }}\n    >\n      <summary\n        style={{\n          cursor: 'pointer',\n          padding: '0.5rem 0.75rem',\n          background: '#111827',\n          userSelect: 'none',\n        }}\n      >\n        {summary}\n      </summary>\n      {errors.length > 0 ? <DiagnosticList errors={errors} /> : null}\n      <pre\n        style={{\n          margin: 0,\n          padding: '0.75rem',\n          overflow: 'auto',\n          maxHeight: '32rem',\n          whiteSpace: 'pre-wrap',\n          wordBreak: 'break-word',\n        }}\n      >\n        {safeStringify(experience)}\n      </pre>\n    </details>\n  );\n}\n\n// Deliberately unstyled for now — this just needs to make the data visible,\n// not console-only. Visual treatment (grouping, color, counts) can grow later.\nfunction DiagnosticList({ errors }: { errors: Error[] }): ReactNode {\n  return (\n    <ul data-experiences-debug-errors>\n      {errors.map((error, index) => (\n        <li key={index}>{error.message}</li>\n      ))}\n    </ul>\n  );\n}\n\n/**\n * JSON.stringify with a circular-reference guard. A resolved plan is plain\n * data, but a customer's `resolveData` could stash a non-serializable value on\n * `props.resolved` — degrade to a placeholder rather than throwing inside a\n * debug panel.\n */\nfunction safeStringify(value: unknown): string {\n  const seen = new WeakSet<object>();\n  try {\n    return JSON.stringify(\n      value,\n      (_key, val) => {\n        if (typeof val === 'object' && val !== null) {\n          if (seen.has(val)) return '[Circular]';\n          seen.add(val);\n        }\n        if (typeof val === 'function') return `[Function ${val.name || 'anonymous'}]`;\n        if (typeof val === 'undefined') return '[undefined]';\n        return val;\n      },\n      2\n    );\n  } catch (err) {\n    // `err` isn't guaranteed to be an Error — a getter deep in customer data\n    // (a resolveData result, resolved design values) can `throw null` or\n    // `throw 'reason'` during JSON.stringify's replacer walk, and this\n    // fallback's whole job is to never throw itself.\n    const reason = err instanceof Error ? err.message : String(err);\n    return `[DebugExperience: could not serialize plan — ${reason}]`;\n  }\n}\n"],"mappings":"AA6DI,SAcE,KAdF;AAvBG,SAAS,gBAAgB;AAAA,EAC9B;AAAA,EACA,cAAc;AAAA,EACd,SAAS,CAAC;AACZ,GAAoC;AAClC,QAAM,YAAY,WAAW,MAAM;AAGnC,QAAM,cAAc,WAAW,MAC5B,OAAO,CAAC,SAAS,KAAK,aAAa,SAAS,oBAAoB,EAChE,IAAI,CAAC,SAAS,KAAK,aAAa,EAAE;AACrC,QAAM,UAAU,2BAAsB,SAAS,kBAAkB,cAAc,IAAI,KAAK,GAAG,GACzF,YAAY,SACR,wBAAwB,YAAY,WAAW,IAAI,KAAK,GAAG,KAAK,YAAY,KAAK,IAAI,CAAC,KACtF,EACN;AAKA,QAAM,OAAO,eAAe,OAAO,SAAS;AAE5C,SACE;AAAA,IAAC;AAAA;AAAA,MACC;AAAA,MACA,0BAAsB;AAAA,MACtB,OAAO;AAAA,QACL,QAAQ;AAAA,QACR,QAAQ;AAAA,QACR,cAAc;AAAA,QACd,YAAY;AAAA,QACZ,OAAO;AAAA,QACP,YAAY;AAAA,QACZ,UAAU;AAAA,QACV,UAAU;AAAA,MACZ;AAAA,MAEA;AAAA;AAAA,UAAC;AAAA;AAAA,YACC,OAAO;AAAA,cACL,QAAQ;AAAA,cACR,SAAS;AAAA,cACT,YAAY;AAAA,cACZ,YAAY;AAAA,YACd;AAAA,YAEC;AAAA;AAAA,QACH;AAAA,QACC,OAAO,SAAS,IAAI,oBAAC,kBAAe,QAAgB,IAAK;AAAA,QAC1D;AAAA,UAAC;AAAA;AAAA,YACC,OAAO;AAAA,cACL,QAAQ;AAAA,cACR,SAAS;AAAA,cACT,UAAU;AAAA,cACV,WAAW;AAAA,cACX,YAAY;AAAA,cACZ,WAAW;AAAA,YACb;AAAA,YAEC,wBAAc,UAAU;AAAA;AAAA,QAC3B;AAAA;AAAA;AAAA,EACF;AAEJ;AAIA,SAAS,eAAe,EAAE,OAAO,GAAmC;AAClE,SACE,oBAAC,QAAG,iCAA6B,MAC9B,iBAAO,IAAI,CAAC,OAAO,UAClB,oBAAC,QAAgB,gBAAM,WAAd,KAAsB,CAChC,GACH;AAEJ;AAQA,SAAS,cAAc,OAAwB;AAC7C,QAAM,OAAO,oBAAI,QAAgB;AACjC,MAAI;AACF,WAAO,KAAK;AAAA,MACV;AAAA,MACA,CAAC,MAAM,QAAQ;AACb,YAAI,OAAO,QAAQ,YAAY,QAAQ,MAAM;AAC3C,cAAI,KAAK,IAAI,GAAG,EAAG,QAAO;AAC1B,eAAK,IAAI,GAAG;AAAA,QACd;AACA,YAAI,OAAO,QAAQ,WAAY,QAAO,aAAa,IAAI,QAAQ,WAAW;AAC1E,YAAI,OAAO,QAAQ,YAAa,QAAO;AACvC,eAAO;AAAA,MACT;AAAA,MACA;AAAA,IACF;AAAA,EACF,SAAS,KAAK;AAKZ,UAAM,SAAS,eAAe,QAAQ,IAAI,UAAU,OAAO,GAAG;AAC9D,WAAO,qDAAgD,MAAM;AAAA,EAC/D;AACF;","names":[]}

package/dist/index.d.ts

@@ -1,14 +1,15 @@
 export { ClientExperienceRenderer, ClientExperienceRendererProps, ClientExperienceRenderer as ExperienceRenderer, ClientExperienceRendererProps as ExperienceRendererProps } from './client-renderer.js';
 export { ServerExperienceRenderer, ServerExperienceRendererProps } from './server-renderer.js';
 export { MissingComponent, MissingComponentProps } from './missing-component.js';
+export { ComponentError, ComponentErrorProps } from './component-error.js';
 export { DebugExperience, DebugExperienceProps } from './debug-experience.js';
 export { UseActiveViewportResult, useActiveViewport } from './use-active-viewport.js';
-export { RenderUnknown } from './nodes-renderer.js';
+export { DiagnosticReporter, RenderError, RenderUnknown } from './nodes-renderer.js';
 export { useContentfulComponent, useContentfulExperienceTemplate, useExperience } from './context.js';
 export { useDesignValues } from './use-design-values.js';
 export { ToCssOptions, toCss } from './design-utils.js';
-export { ComponentConfig, Components, Config, ContentfulComponent, ContentfulExperienceTemplate, ExperienceTemplateConfig, ExperienceTemplateRegistration, ExperienceTemplates, Registration, RenderContext, defineComponent, defineExperienceTemplate, normalizeComponentRegistration, normalizeExperienceTemplateRegistration } from './types.js';
-export { ComponentNode, ComponentRef, DesignPropValue, DesignToken, ExperienceContext, ExperienceNode, ExperiencePayload, ExperienceSys, ExperienceTemplateNode, ExperienceTemplateRef, ManualDesignValue, PortableRegistration, PortableRenderNode, PortableRenderPlan, ResolveContext, ResolveExperienceOptions, ResolveToken, ResolverConfig, ValuesByViewport, ViewportDef, resolveExperience } from '@contentful/experiences-sdk-core';
+export { ComponentConfig, Components, Config, ContentfulComponent, ContentfulExperienceTemplate, ExperienceTemplateConfig, ExperienceTemplateRegistration, ExperienceTemplates, Registration, defineComponent, defineExperienceTemplate, normalizeComponentRegistration, normalizeExperienceTemplateRegistration } from './types.js';
+export { ComponentNode, ComponentRef, DesignPropValue, DesignToken, ExperienceContext, ExperienceNode, ExperiencePayload, ExperienceSourceMap, ExperienceSys, ExperienceTemplateNode, ExperienceTemplateRef, ManualDesignValue, PortableRegistration, PortableRenderNode, PortableRenderPlan, RenderContext, ResolveContext, ResolveExperienceOptions, ResolveToken, ResolverConfig, ValuesByViewport, ViewportDef, resolveExperience } from '@contentful/experiences-sdk-core';
 export { CSS_PROPERTIES, getValueForViewport, getViewportIndex, isCssProperty, resolveDesignProperties, toCssKey, toCssMediaQuery } from '@contentful/experiences-design';
-export { ClientOptions, ContentfulViewDelivery, ContentfulViewDeliveryClient, CreateClientOptions, DELIVERY_HOST, ExperienceOptions, NotFoundError, PREVIEW_HOST, ResolveOptions, createClient, fetchExperience } from '@contentful/experiences-client';
+export { ClientOptions, ContentfulViewDelivery, ContentfulViewDeliveryClient, CreateClientOptions, DELIVERY_HOST, ExperienceFetchError, ExperienceOptions, ExperienceResponse, NotFoundError, PREVIEW_HOST, ResolveOptions, createClient, fetchExperience, readSourceMap, toExperiencePayload } from '@contentful/experiences-client';
 import 'react';

package/dist/index.js

@@ -4,6 +4,7 @@ import {
 } from "./client-renderer";
 import { ServerExperienceRenderer } from "./server-renderer";
 import { MissingComponent } from "./missing-component";
+import { ComponentError } from "./component-error";
 import { DebugExperience } from "./debug-experience";
 import { useActiveViewport } from "./use-active-viewport";
 import { useExperience, useContentfulComponent, useContentfulExperienceTemplate } from "./context";
@@ -29,18 +30,23 @@ import {
   ContentfulViewDelivery,
   ContentfulViewDeliveryClient,
   DELIVERY_HOST,
+  ExperienceFetchError,
   NotFoundError,
   PREVIEW_HOST,
   createClient,
-  fetchExperience
+  fetchExperience,
+  readSourceMap,
+  toExperiencePayload
 } from "@contentful/experiences-client";
 export {
   CSS_PROPERTIES,
   ClientExperienceRenderer2 as ClientExperienceRenderer,
+  ComponentError,
   ContentfulViewDelivery,
   ContentfulViewDeliveryClient,
   DELIVERY_HOST,
   DebugExperience,
+  ExperienceFetchError,
   ClientExperienceRenderer as ExperienceRenderer,
   MissingComponent,
   NotFoundError,
@@ -55,11 +61,13 @@ export {
   isCssProperty,
   normalizeComponentRegistration,
   normalizeExperienceTemplateRegistration,
+  readSourceMap,
   resolveDesignProperties,
   resolveExperience,
   toCss,
   toCssKey,
   toCssMediaQuery,
+  toExperiencePayload,
   useActiveViewport,
   useContentfulComponent,
   useContentfulExperienceTemplate,

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts"],"sourcesContent":["/*\n * Public API surface for `@contentful/experiences-react`.\n *\n * Customers add ONLY this package to their app's dependencies. Everything\n * needed to render an Experience — types, the resolver, viewport utilities,\n * the renderer components, the authoring helpers — is re-exported from here.\n * The internal `@contentful/experiences-sdk-core` and\n * `@contentful/experiences-design` packages are workspace-only implementation\n * details; they are not part of the public API.\n *\n * `ExperienceRenderer` is an alias for `ClientExperienceRenderer`; SSR\n * consumers explicitly import `ServerExperienceRenderer`.\n */\n\n// ─── Renderers ─────────────────────────────────────────────────────────────\nexport {\n  ClientExperienceRenderer as ExperienceRenderer,\n  ClientExperienceRenderer,\n} from './client-renderer';\nexport type { ClientExperienceRendererProps as ExperienceRendererProps } from './client-renderer';\nexport type { ClientExperienceRendererProps } from './client-renderer';\n\nexport { ServerExperienceRenderer } from './server-renderer';\nexport type { ServerExperienceRendererProps } from './server-renderer';\n\nexport { MissingComponent } from './missing-component';\nexport type { MissingComponentProps } from './missing-component';\n\nexport { DebugExperience } from './debug-experience';\nexport type { DebugExperienceProps } from './debug-experience';\n\nexport { useActiveViewport } from './use-active-viewport';\nexport type { UseActiveViewportResult } from './use-active-viewport';\n\nexport type { RenderUnknown } from './nodes-renderer';\n\n// ─── Runtime context hooks ───────────────────────────────────────────────\nexport { useExperience, useContentfulComponent, useContentfulExperienceTemplate } from './context';\nexport { useDesignValues } from './use-design-values';\nexport { toCss } from './design-utils';\nexport type { ToCssOptions } from './design-utils';\n\n// ─── Authoring helpers + Config types ─────────────────────────────────────\nexport {\n  defineComponent,\n  defineExperienceTemplate,\n  normalizeComponentRegistration,\n  normalizeExperienceTemplateRegistration,\n} from './types';\nexport type {\n  ComponentConfig,\n  Components,\n  Config,\n  ContentfulComponent,\n  ContentfulExperienceTemplate,\n  ExperienceTemplateConfig,\n  ExperienceTemplateRegistration,\n  ExperienceTemplates,\n  Registration,\n  RenderContext,\n  ResolveToken,\n} from './types';\n\n// ─── Resolver (re-exported from render-core) ──────────────────────────────\nexport { resolveExperience } from '@contentful/experiences-sdk-core';\nexport type { ResolverConfig, ResolveExperienceOptions } from '@contentful/experiences-sdk-core';\n\n// ─── Core IR + payload types (re-exported from render-core) ───────────────\nexport type {\n  ComponentNode,\n  ComponentRef,\n  DesignPropValue,\n  DesignToken,\n  ExperienceContext,\n  ExperienceNode,\n  ExperiencePayload,\n  ExperienceSys,\n  ExperienceTemplateNode,\n  ExperienceTemplateRef,\n  ManualDesignValue,\n  PortableRegistration,\n  PortableRenderNode,\n  PortableRenderPlan,\n  ResolveContext,\n  ValuesByViewport,\n  ViewportDef,\n} from '@contentful/experiences-sdk-core';\n\n// ─── Design utilities (re-exported from design) ───────────────────────────\nexport {\n  CSS_PROPERTIES,\n  getValueForViewport,\n  getViewportIndex,\n  isCssProperty,\n  resolveDesignProperties,\n  toCssKey,\n  toCssMediaQuery,\n} from '@contentful/experiences-design';\n\n// ─── Delivery client + fetchExperience ────────────────────────────────────\nexport {\n  ContentfulViewDelivery,\n  ContentfulViewDeliveryClient,\n  DELIVERY_HOST,\n  NotFoundError,\n  PREVIEW_HOST,\n  createClient,\n  fetchExperience,\n} from '@contentful/experiences-client';\nexport type {\n  ClientOptions,\n  CreateClientOptions,\n  ExperienceOptions,\n  ResolveOptions,\n} from '@contentful/experiences-client';\n"],"mappings":"AAeA;AAAA,EAC8B;AAAA,EAC5B,4BAAAA;AAAA,OACK;AAIP,SAAS,gCAAgC;AAGzC,SAAS,wBAAwB;AAGjC,SAAS,uBAAuB;AAGhC,SAAS,yBAAyB;AAMlC,SAAS,eAAe,wBAAwB,uCAAuC;AACvF,SAAS,uBAAuB;AAChC,SAAS,aAAa;AAItB;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OACK;AAgBP,SAAS,yBAAyB;AAyBlC;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OACK;AAGP;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OACK;","names":["ClientExperienceRenderer"]}
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["/*\n * Public API surface for `@contentful/experiences-react`.\n *\n * Customers add ONLY this package to their app's dependencies. Everything\n * needed to render an Experience — types, the resolver, viewport utilities,\n * the renderer components, the authoring helpers — is re-exported from here.\n * The internal `@contentful/experiences-sdk-core` and\n * `@contentful/experiences-design` packages are workspace-only implementation\n * details; they are not part of the public API.\n *\n * `ExperienceRenderer` is an alias for `ClientExperienceRenderer`; SSR\n * consumers explicitly import `ServerExperienceRenderer`.\n */\n\n// ─── Renderers ─────────────────────────────────────────────────────────────\nexport {\n  ClientExperienceRenderer as ExperienceRenderer,\n  ClientExperienceRenderer,\n} from './client-renderer';\nexport type { ClientExperienceRendererProps as ExperienceRendererProps } from './client-renderer';\nexport type { ClientExperienceRendererProps } from './client-renderer';\n\nexport { ServerExperienceRenderer } from './server-renderer';\nexport type { ServerExperienceRendererProps } from './server-renderer';\n\nexport { MissingComponent } from './missing-component';\nexport type { MissingComponentProps } from './missing-component';\n\nexport { ComponentError } from './component-error';\nexport type { ComponentErrorProps } from './component-error';\n\nexport { DebugExperience } from './debug-experience';\nexport type { DebugExperienceProps } from './debug-experience';\n\nexport { useActiveViewport } from './use-active-viewport';\nexport type { UseActiveViewportResult } from './use-active-viewport';\n\nexport type { DiagnosticReporter, RenderError, RenderUnknown } from './nodes-renderer';\n\n// ─── Runtime context hooks ───────────────────────────────────────────────\nexport { useExperience, useContentfulComponent, useContentfulExperienceTemplate } from './context';\nexport { useDesignValues } from './use-design-values';\nexport { toCss } from './design-utils';\nexport type { ToCssOptions } from './design-utils';\n\n// ─── Authoring helpers + Config types ─────────────────────────────────────\nexport {\n  defineComponent,\n  defineExperienceTemplate,\n  normalizeComponentRegistration,\n  normalizeExperienceTemplateRegistration,\n} from './types';\nexport type {\n  ComponentConfig,\n  Components,\n  Config,\n  ContentfulComponent,\n  ContentfulExperienceTemplate,\n  ExperienceTemplateConfig,\n  ExperienceTemplateRegistration,\n  ExperienceTemplates,\n  Registration,\n  RenderContext,\n  ResolveToken,\n} from './types';\n\n// ─── Resolver (re-exported from render-core) ──────────────────────────────\nexport { resolveExperience } from '@contentful/experiences-sdk-core';\nexport type { ResolverConfig, ResolveExperienceOptions } from '@contentful/experiences-sdk-core';\n\n// ─── Core IR + payload types (re-exported from render-core) ───────────────\nexport type {\n  ComponentNode,\n  ComponentRef,\n  DesignPropValue,\n  DesignToken,\n  ExperienceContext,\n  ExperienceNode,\n  ExperiencePayload,\n  ExperienceSourceMap,\n  ExperienceSys,\n  ExperienceTemplateNode,\n  ExperienceTemplateRef,\n  ManualDesignValue,\n  PortableRegistration,\n  PortableRenderNode,\n  PortableRenderPlan,\n  ResolveContext,\n  ValuesByViewport,\n  ViewportDef,\n} from '@contentful/experiences-sdk-core';\n\n// ─── Design utilities (re-exported from design) ───────────────────────────\nexport {\n  CSS_PROPERTIES,\n  getValueForViewport,\n  getViewportIndex,\n  isCssProperty,\n  resolveDesignProperties,\n  toCssKey,\n  toCssMediaQuery,\n} from '@contentful/experiences-design';\n\n// ─── Delivery client + fetchExperience ────────────────────────────────────\nexport {\n  ContentfulViewDelivery,\n  ContentfulViewDeliveryClient,\n  DELIVERY_HOST,\n  ExperienceFetchError,\n  NotFoundError,\n  PREVIEW_HOST,\n  createClient,\n  fetchExperience,\n  readSourceMap,\n  toExperiencePayload,\n} from '@contentful/experiences-client';\nexport type {\n  ClientOptions,\n  CreateClientOptions,\n  ExperienceOptions,\n  ExperienceResponse,\n  ResolveOptions,\n} from '@contentful/experiences-client';\n"],"mappings":"AAeA;AAAA,EAC8B;AAAA,EAC5B,4BAAAA;AAAA,OACK;AAIP,SAAS,gCAAgC;AAGzC,SAAS,wBAAwB;AAGjC,SAAS,sBAAsB;AAG/B,SAAS,uBAAuB;AAGhC,SAAS,yBAAyB;AAMlC,SAAS,eAAe,wBAAwB,uCAAuC;AACvF,SAAS,uBAAuB;AAChC,SAAS,aAAa;AAItB;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OACK;AAgBP,SAAS,yBAAyB;AA0BlC;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OACK;AAGP;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OACK;","names":["ClientExperienceRenderer"]}

package/dist/nodes-renderer.d.ts

@@ -1,9 +1,20 @@
 import { ReactNode } from 'react';
 import { PortableRenderNode, ViewportDef } from '@contentful/experiences-sdk-core';
+import { ComponentErrorProps } from './component-error.js';
 import { MissingComponentProps } from './missing-component.js';
 import { Config } from './types.js';
 
 type RenderUnknown = (props: MissingComponentProps) => ReactNode;
+type RenderError = (props: ComponentErrorProps) => ReactNode;
+/**
+ * Reports one render-time diagnostic (unregistered id, a component that
+ * threw). `ServerExperienceRenderer` passes a closure that pushes onto a
+ * plain array (SSR is synchronous top-down, so the array is fully populated
+ * by the time `<DebugExperience>` reads it — see the element-order note
+ * there). `ClientExperienceRenderer` passes a `setState` updater instead, so
+ * `<DebugExperience>` re-renders reactively when a later interaction throws.
+ */
+type DiagnosticReporter = (error: Error) => void;
 interface NodesRendererProps {
     nodes: PortableRenderNode[];
     config: Config;
@@ -12,7 +23,9 @@ interface NodesRendererProps {
     /** Viewport index the server pre-resolved design against. */
     fallbackViewportIndex: number;
     renderUnknown: RenderUnknown;
+    renderError: RenderError;
+    onDiagnostic: DiagnosticReporter;
 }
-declare function NodesRenderer({ nodes, config, viewports, activeViewportIndex, fallbackViewportIndex, renderUnknown, }: NodesRendererProps): ReactNode;
+declare function NodesRenderer({ nodes, config, viewports, activeViewportIndex, fallbackViewportIndex, renderUnknown, renderError, onDiagnostic, }: NodesRendererProps): ReactNode;
 
-export { NodesRenderer, type NodesRendererProps, type RenderUnknown };
+export { type DiagnosticReporter, NodesRenderer, type NodesRendererProps, type RenderError, type RenderUnknown };

package/dist/nodes-renderer.js

@@ -1,6 +1,7 @@
 import { jsx } from "react/jsx-runtime";
 import { Fragment, createElement } from "react";
 import { selectResolvedDesign } from "@contentful/experiences-design";
+import { ComponentErrorBoundary } from "./component-error-boundary";
 import {
   ContentfulComponentProvider,
   ContentfulExperienceTemplateProvider,
@@ -16,7 +17,9 @@ function NodesRenderer({
   viewports,
   activeViewportIndex,
   fallbackViewportIndex,
-  renderUnknown
+  renderUnknown,
+  renderError,
+  onDiagnostic
 }) {
   if (!nodes.length) return null;
   return /* @__PURE__ */ jsx(Fragment, { children: nodes.map((node, index) => /* @__PURE__ */ jsx(
@@ -27,7 +30,9 @@ function NodesRenderer({
       viewports,
       activeViewportIndex,
       fallbackViewportIndex,
-      renderUnknown
+      renderUnknown,
+      renderError,
+      onDiagnostic
     },
     node.nodeId ?? index
   )) });
@@ -38,12 +43,23 @@ function NodeRenderer({
   viewports,
   activeViewportIndex,
   fallbackViewportIndex,
-  renderUnknown
+  renderUnknown,
+  renderError,
+  onDiagnostic
 }) {
   const { kind, id } = node.registration;
   const isExperienceTemplate = kind === "experienceTemplate";
   const slotProps = {};
   for (const [slotName, children] of Object.entries(node.slots)) {
+    if (!Array.isArray(children)) {
+      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-react] ${message}`);
+      }
+      onDiagnostic(new Error(message));
+      slotProps[slotName] = [];
+      continue;
+    }
     slotProps[slotName] = children.map((child, index) => /* @__PURE__ */ jsx(
       NodeRenderer,
       {
@@ -52,7 +68,9 @@ function NodeRenderer({
         viewports,
         activeViewportIndex,
         fallbackViewportIndex,
-        renderUnknown
+        renderUnknown,
+        renderError,
+        onDiagnostic
       },
       child.nodeId ?? index
     ));
@@ -60,13 +78,18 @@ function NodeRenderer({
   const entry = isExperienceTemplate ? config.experienceTemplates?.[id] : config.components[id];
   if (!entry) {
     if (isExperienceTemplate) {
+      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-react] No experience template registered for id "${id}". Rendering its slot children without the experience template wrapper.`
-        );
+        console.warn(`[@contentful/experiences-react] ${message}`);
       }
+      onDiagnostic(new Error(message));
       return /* @__PURE__ */ jsx(Fragment, { children: Object.values(slotProps).flat() });
     }
+    onDiagnostic(
+      new Error(
+        `No component registered for id "${id}"${node.nodeId ? ` (nodeId: ${node.nodeId})` : ""}.`
+      )
+    );
     return createElement(renderUnknown, { componentId: id, nodeId: node.nodeId });
   }
   const registrationConfig = isExperienceTemplate ? normalizeExperienceTemplateRegistration(entry) : normalizeComponentRegistration(entry);
@@ -89,7 +112,16 @@ function NodeRenderer({
     ...node.props.resolved,
     ...slotProps
   };
-  const element = /* @__PURE__ */ jsx(ResolvedDesignProvider, { value: tokenResolvedDesign, children: createElement(registrationConfig.component, composed) });
+  const element = /* @__PURE__ */ jsx(ResolvedDesignProvider, { value: tokenResolvedDesign, children: /* @__PURE__ */ jsx(
+    ComponentErrorBoundary,
+    {
+      fallback: createElement(renderError, { componentId: id, nodeId: node.nodeId }),
+      componentId: id,
+      kind,
+      nodeId: node.nodeId,
+      children: createElement(registrationConfig.component, composed)
+    }
+  ) });
   if (isExperienceTemplate) {
     const contentful2 = {
       experienceTemplateId: id,

package/dist/nodes-renderer.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/nodes-renderer.tsx"],"sourcesContent":["/*\n * Recursive renderer over PortableRenderNodes. Resolved design values auto-fill\n * matching props (below content/resolveData) and are also available via\n * `useDesignValues()`.\n */\n\nimport { Fragment, createElement, type ReactNode } from 'react';\n\nimport type { PortableRenderNode, ViewportDef } from '@contentful/experiences-sdk-core';\nimport { selectResolvedDesign } from '@contentful/experiences-design';\n\nimport {\n  ContentfulComponentProvider,\n  ContentfulExperienceTemplateProvider,\n  ResolvedDesignProvider,\n} from './context';\nimport type { MissingComponentProps } from './missing-component';\nimport {\n  normalizeComponentRegistration,\n  normalizeExperienceTemplateRegistration,\n  type ContentfulComponent,\n  type ContentfulExperienceTemplate,\n  type Config,\n} from './types';\n\nexport type RenderUnknown = (props: MissingComponentProps) => ReactNode;\n\n// Internal renderers take `viewports` + `activeViewportIndex`, not the whole\n// RenderContext object — the context is published once via ExperienceProvider,\n// and re-threading it as an element prop makes React's RSC serializer back-patch\n// a shared reference into frozen props (\"Cannot assign to read only property\").\nexport interface NodesRendererProps {\n  nodes: PortableRenderNode[];\n  config: Config;\n  viewports: ViewportDef[];\n  activeViewportIndex: number;\n  /** Viewport index the server pre-resolved design against. */\n  fallbackViewportIndex: number;\n  renderUnknown: RenderUnknown;\n}\n\nexport function NodesRenderer({\n  nodes,\n  config,\n  viewports,\n  activeViewportIndex,\n  fallbackViewportIndex,\n  renderUnknown,\n}: NodesRendererProps): ReactNode {\n  if (!nodes.length) return null;\n  return (\n    <Fragment>\n      {nodes.map((node, index) => (\n        <NodeRenderer\n          key={node.nodeId ?? index}\n          node={node}\n          config={config}\n          viewports={viewports}\n          activeViewportIndex={activeViewportIndex}\n          fallbackViewportIndex={fallbackViewportIndex}\n          renderUnknown={renderUnknown}\n        />\n      ))}\n    </Fragment>\n  );\n}\n\ninterface NodeRendererProps {\n  node: PortableRenderNode;\n  config: Config;\n  viewports: ViewportDef[];\n  activeViewportIndex: number;\n  fallbackViewportIndex: number;\n  renderUnknown: RenderUnknown;\n}\n\nfunction NodeRenderer({\n  node,\n  config,\n  viewports,\n  activeViewportIndex,\n  fallbackViewportIndex,\n  renderUnknown,\n}: NodeRendererProps): ReactNode {\n  const { kind, id } = node.registration;\n  const isExperienceTemplate = kind === 'experienceTemplate';\n\n  // Pre-render each slot's children as an *array* of ReactNodes (one keyed\n  // element per child), not a single wrapping node. A component can drop the\n  // array straight into JSX for the common \"just render them\" case (React\n  // renders keyed arrays), or map/filter/wrap the children individually.\n  //\n  // Slot name → prop name, for both node kinds: a coded Experience Template\n  // declaring a `content` slot receives a `content` prop. `children` is not a\n  // special case, just the conventional default slot name.\n  const slotProps: Record<string, ReactNode[]> = {};\n  for (const [slotName, children] of Object.entries(node.slots)) {\n    slotProps[slotName] = children.map((child, index) => (\n      <NodeRenderer\n        key={child.nodeId ?? index}\n        node={child}\n        config={config}\n        viewports={viewports}\n        activeViewportIndex={activeViewportIndex}\n        fallbackViewportIndex={fallbackViewportIndex}\n        renderUnknown={renderUnknown}\n      />\n    ));\n  }\n\n  const entry = isExperienceTemplate ? config.experienceTemplates?.[id] : config.components[id];\n  if (!entry) {\n    // An unregistered Experience Template would blank the page if we swapped\n    // it for the missing-component box, so warn and render its slot children\n    // unwrapped — the content survives, the diagnostic names what's missing.\n    if (isExperienceTemplate) {\n      if (typeof console !== 'undefined') {\n        console.warn(\n          `[@contentful/experiences-react] No experience template registered for id \"${id}\". Rendering its slot children without the experience template wrapper.`\n        );\n      }\n      return <Fragment>{Object.values(slotProps).flat()}</Fragment>;\n    }\n    return createElement(renderUnknown, { componentId: id, nodeId: node.nodeId });\n  }\n  const registrationConfig = isExperienceTemplate\n    ? normalizeExperienceTemplateRegistration(entry)\n    : normalizeComponentRegistration(entry);\n\n  const { props: tokenResolvedDesign, unresolved } = selectResolvedDesign(\n    node.props,\n    viewports,\n    activeViewportIndex,\n    fallbackViewportIndex,\n    config.resolveToken\n  );\n  if (unresolved.length && typeof console !== 'undefined') {\n    console.warn(\n      `[@contentful/experiences-react] resolveToken returned undefined for token id(s) on ${kind} \"${id}\": ${unresolved.join(', ')}. useDesignValues() will omit those keys.`\n    );\n  }\n\n  // Merge precedence (last wins): defaults < design < content < resolveData < slots.\n  const composed = {\n    ...registrationConfig.defaults,\n    ...tokenResolvedDesign,\n    ...node.props.content,\n    ...node.props.resolved,\n    ...slotProps,\n  };\n\n  const element = (\n    <ResolvedDesignProvider value={tokenResolvedDesign}>\n      {createElement(registrationConfig.component, composed)}\n    </ResolvedDesignProvider>\n  );\n\n  if (isExperienceTemplate) {\n    const contentful: ContentfulExperienceTemplate = {\n      experienceTemplateId: id,\n      nodeId: node.nodeId,\n      content: node.props.content,\n      design: node.props.designRaw,\n      resolved: node.props.resolved,\n    };\n    return (\n      <ContentfulExperienceTemplateProvider value={contentful}>\n        {element}\n      </ContentfulExperienceTemplateProvider>\n    );\n  }\n\n  const contentful: ContentfulComponent = {\n    componentId: id,\n    nodeId: node.nodeId,\n    content: node.props.content,\n    design: node.props.designRaw,\n    resolved: node.props.resolved,\n  };\n  return <ContentfulComponentProvider value={contentful}>{element}</ContentfulComponentProvider>;\n}\n"],"mappings":"AAqDQ;AA/CR,SAAS,UAAU,qBAAqC;AAGxD,SAAS,4BAA4B;AAErC;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,OACK;AAEP;AAAA,EACE;AAAA,EACA;AAAA,OAIK;AAkBA,SAAS,cAAc;AAAA,EAC5B;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF,GAAkC;AAChC,MAAI,CAAC,MAAM,OAAQ,QAAO;AAC1B,SACE,oBAAC,YACE,gBAAM,IAAI,CAAC,MAAM,UAChB;AAAA,IAAC;AAAA;AAAA,MAEC;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA;AAAA,IANK,KAAK,UAAU;AAAA,EAOtB,CACD,GACH;AAEJ;AAWA,SAAS,aAAa;AAAA,EACpB;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF,GAAiC;AAC/B,QAAM,EAAE,MAAM,GAAG,IAAI,KAAK;AAC1B,QAAM,uBAAuB,SAAS;AAUtC,QAAM,YAAyC,CAAC;AAChD,aAAW,CAAC,UAAU,QAAQ,KAAK,OAAO,QAAQ,KAAK,KAAK,GAAG;AAC7D,cAAU,QAAQ,IAAI,SAAS,IAAI,CAAC,OAAO,UACzC;AAAA,MAAC;AAAA;AAAA,QAEC,MAAM;AAAA,QACN;AAAA,QACA;AAAA,QACA;AAAA,QACA;AAAA,QACA;AAAA;AAAA,MANK,MAAM,UAAU;AAAA,IAOvB,CACD;AAAA,EACH;AAEA,QAAM,QAAQ,uBAAuB,OAAO,sBAAsB,EAAE,IAAI,OAAO,WAAW,EAAE;AAC5F,MAAI,CAAC,OAAO;AAIV,QAAI,sBAAsB;AACxB,UAAI,OAAO,YAAY,aAAa;AAClC,gBAAQ;AAAA,UACN,6EAA6E,EAAE;AAAA,QACjF;AAAA,MACF;AACA,aAAO,oBAAC,YAAU,iBAAO,OAAO,SAAS,EAAE,KAAK,GAAE;AAAA,IACpD;AACA,WAAO,cAAc,eAAe,EAAE,aAAa,IAAI,QAAQ,KAAK,OAAO,CAAC;AAAA,EAC9E;AACA,QAAM,qBAAqB,uBACvB,wCAAwC,KAAK,IAC7C,+BAA+B,KAAK;AAExC,QAAM,EAAE,OAAO,qBAAqB,WAAW,IAAI;AAAA,IACjD,KAAK;AAAA,IACL;AAAA,IACA;AAAA,IACA;AAAA,IACA,OAAO;AAAA,EACT;AACA,MAAI,WAAW,UAAU,OAAO,YAAY,aAAa;AACvD,YAAQ;AAAA,MACN,sFAAsF,IAAI,KAAK,EAAE,MAAM,WAAW,KAAK,IAAI,CAAC;AAAA,IAC9H;AAAA,EACF;AAGA,QAAM,WAAW;AAAA,IACf,GAAG,mBAAmB;AAAA,IACtB,GAAG;AAAA,IACH,GAAG,KAAK,MAAM;AAAA,IACd,GAAG,KAAK,MAAM;AAAA,IACd,GAAG;AAAA,EACL;AAEA,QAAM,UACJ,oBAAC,0BAAuB,OAAO,qBAC5B,wBAAc,mBAAmB,WAAW,QAAQ,GACvD;AAGF,MAAI,sBAAsB;AACxB,UAAMA,cAA2C;AAAA,MAC/C,sBAAsB;AAAA,MACtB,QAAQ,KAAK;AAAA,MACb,SAAS,KAAK,MAAM;AAAA,MACpB,QAAQ,KAAK,MAAM;AAAA,MACnB,UAAU,KAAK,MAAM;AAAA,IACvB;AACA,WACE,oBAAC,wCAAqC,OAAOA,aAC1C,mBACH;AAAA,EAEJ;AAEA,QAAM,aAAkC;AAAA,IACtC,aAAa;AAAA,IACb,QAAQ,KAAK;AAAA,IACb,SAAS,KAAK,MAAM;AAAA,IACpB,QAAQ,KAAK,MAAM;AAAA,IACnB,UAAU,KAAK,MAAM;AAAA,EACvB;AACA,SAAO,oBAAC,+BAA4B,OAAO,YAAa,mBAAQ;AAClE;","names":["contentful"]}
+{"version":3,"sources":["../src/nodes-renderer.tsx"],"sourcesContent":["/*\n * Recursive renderer over PortableRenderNodes. Resolved design values auto-fill\n * matching props (below content/resolveData) and are also available via\n * `useDesignValues()`.\n */\n\nimport { Fragment, createElement, type ReactNode } from 'react';\n\nimport type { PortableRenderNode, ViewportDef } from '@contentful/experiences-sdk-core';\nimport { selectResolvedDesign } from '@contentful/experiences-design';\n\nimport { ComponentErrorBoundary } from './component-error-boundary';\nimport type { ComponentErrorProps } from './component-error';\nimport {\n  ContentfulComponentProvider,\n  ContentfulExperienceTemplateProvider,\n  ResolvedDesignProvider,\n} from './context';\nimport type { MissingComponentProps } from './missing-component';\nimport {\n  normalizeComponentRegistration,\n  normalizeExperienceTemplateRegistration,\n  type ContentfulComponent,\n  type ContentfulExperienceTemplate,\n  type Config,\n} from './types';\n\nexport type RenderUnknown = (props: MissingComponentProps) => ReactNode;\nexport type RenderError = (props: ComponentErrorProps) => ReactNode;\n\n/**\n * Reports one render-time diagnostic (unregistered id, a component that\n * threw). `ServerExperienceRenderer` passes a closure that pushes onto a\n * plain array (SSR is synchronous top-down, so the array is fully populated\n * by the time `<DebugExperience>` reads it — see the element-order note\n * there). `ClientExperienceRenderer` passes a `setState` updater instead, so\n * `<DebugExperience>` re-renders reactively when a later interaction throws.\n */\nexport type DiagnosticReporter = (error: Error) => void;\n\n// Internal renderers take `viewports` + `activeViewportIndex`, not the whole\n// RenderContext object — the context is published once via ExperienceProvider,\n// and re-threading it as an element prop makes React's RSC serializer back-patch\n// a shared reference into frozen props (\"Cannot assign to read only property\").\nexport interface NodesRendererProps {\n  nodes: PortableRenderNode[];\n  config: Config;\n  viewports: ViewportDef[];\n  activeViewportIndex: number;\n  /** Viewport index the server pre-resolved design against. */\n  fallbackViewportIndex: number;\n  renderUnknown: RenderUnknown;\n  renderError: RenderError;\n  onDiagnostic: DiagnosticReporter;\n}\n\nexport function NodesRenderer({\n  nodes,\n  config,\n  viewports,\n  activeViewportIndex,\n  fallbackViewportIndex,\n  renderUnknown,\n  renderError,\n  onDiagnostic,\n}: NodesRendererProps): ReactNode {\n  if (!nodes.length) return null;\n  return (\n    <Fragment>\n      {nodes.map((node, index) => (\n        <NodeRenderer\n          key={node.nodeId ?? index}\n          node={node}\n          config={config}\n          viewports={viewports}\n          activeViewportIndex={activeViewportIndex}\n          fallbackViewportIndex={fallbackViewportIndex}\n          renderUnknown={renderUnknown}\n          renderError={renderError}\n          onDiagnostic={onDiagnostic}\n        />\n      ))}\n    </Fragment>\n  );\n}\n\ninterface NodeRendererProps {\n  node: PortableRenderNode;\n  config: Config;\n  viewports: ViewportDef[];\n  activeViewportIndex: number;\n  fallbackViewportIndex: number;\n  renderUnknown: RenderUnknown;\n  renderError: RenderError;\n  onDiagnostic: DiagnosticReporter;\n}\n\nfunction NodeRenderer({\n  node,\n  config,\n  viewports,\n  activeViewportIndex,\n  fallbackViewportIndex,\n  renderUnknown,\n  renderError,\n  onDiagnostic,\n}: NodeRendererProps): ReactNode {\n  const { kind, id } = node.registration;\n  const isExperienceTemplate = kind === 'experienceTemplate';\n\n  // Diagnostics are reported straight to `onDiagnostic`, synchronously during\n  // render. Deliberate: this component is shared between SSR and CSR, and\n  // `useEffect` never runs during `renderToStaticMarkup`/streaming SSR — an\n  // effect-deferred report would silently vanish on the server.\n  //\n  // Dedup lives in `onDiagnostic` (see both renderers), not here. An ancestor\n  // re-render re-executes this whole function, so an unregistered id or\n  // malformed slot would otherwise be re-reported every time — the collectors\n  // drop a message they already hold. Keeping the guard there rather than in a\n  // `useRef` is what lets this module stay hook-free, and therefore usable from\n  // a React Server Component: `ServerExperienceRenderer` renders it without a\n  // `'use client'` boundary, which is what keeps `config` (component\n  // references, unserializable) from having to cross one.\n\n  // Pre-render each slot's children as an *array* of ReactNodes (one keyed\n  // element per child), not a single wrapping node. A component can drop the\n  // array straight into JSX for the common \"just render them\" case (React\n  // renders keyed arrays), or map/filter/wrap the children individually.\n  //\n  // Slot name → prop name, for both node kinds: a coded Experience Template\n  // declaring a `content` slot receives a `content` prop. `children` is not a\n  // special case, just the conventional default slot name.\n  const slotProps: Record<string, ReactNode[]> = {};\n  for (const [slotName, children] of Object.entries(node.slots)) {\n    // Defensive: `node.slots[x]` is typed as an array, but a hand-built\n    // PortableRenderPlan (a supported path — customers can construct one\n    // directly instead of going through `resolveExperience`) is not\n    // type-checked at runtime. Warn + drop rather than letting `.map` throw.\n    if (!Array.isArray(children)) {\n      const message =\n        `Slot \"${slotName}\" on ${kind} \"${id}\"${node.nodeId ? ` (node \"${node.nodeId}\")` : ''} ` +\n        `is not an array of nodes; rendering it as empty instead of throwing.`;\n      if (typeof console !== 'undefined') {\n        console.warn(`[@contentful/experiences-react] ${message}`);\n      }\n      onDiagnostic(new Error(message));\n      slotProps[slotName] = [];\n      continue;\n    }\n    slotProps[slotName] = children.map((child, index) => (\n      <NodeRenderer\n        key={child.nodeId ?? index}\n        node={child}\n        config={config}\n        viewports={viewports}\n        activeViewportIndex={activeViewportIndex}\n        fallbackViewportIndex={fallbackViewportIndex}\n        renderUnknown={renderUnknown}\n        renderError={renderError}\n        onDiagnostic={onDiagnostic}\n      />\n    ));\n  }\n\n  const entry = isExperienceTemplate ? config.experienceTemplates?.[id] : config.components[id];\n  if (!entry) {\n    // An unregistered Experience Template would blank the page if we swapped\n    // it for the missing-component box, so warn and render its slot children\n    // unwrapped — the content survives, the diagnostic names what's missing.\n    if (isExperienceTemplate) {\n      const message = `No experience template registered for id \"${id}\". Rendering its slot children without the experience template wrapper.`;\n      if (typeof console !== 'undefined') {\n        console.warn(`[@contentful/experiences-react] ${message}`);\n      }\n      onDiagnostic(new Error(message));\n      return <Fragment>{Object.values(slotProps).flat()}</Fragment>;\n    }\n    // `MissingComponent` (the default `renderUnknown`) does its own\n    // console.warn; a custom override may not, so the diagnostic is recorded\n    // here regardless of which fallback ends up rendering.\n    onDiagnostic(\n      new Error(\n        `No component registered for id \"${id}\"${node.nodeId ? ` (nodeId: ${node.nodeId})` : ''}.`\n      )\n    );\n    return createElement(renderUnknown, { componentId: id, nodeId: node.nodeId });\n  }\n  const registrationConfig = isExperienceTemplate\n    ? normalizeExperienceTemplateRegistration(entry)\n    : normalizeComponentRegistration(entry);\n\n  const { props: tokenResolvedDesign, unresolved } = selectResolvedDesign(\n    node.props,\n    viewports,\n    activeViewportIndex,\n    fallbackViewportIndex,\n    config.resolveToken\n  );\n  if (unresolved.length && typeof console !== 'undefined') {\n    console.warn(\n      `[@contentful/experiences-react] resolveToken returned undefined for token id(s) on ${kind} \"${id}\": ${unresolved.join(', ')}. useDesignValues() will omit those keys.`\n    );\n  }\n\n  // Merge precedence (last wins): defaults < design < content < resolveData < slots.\n  const composed = {\n    ...registrationConfig.defaults,\n    ...tokenResolvedDesign,\n    ...node.props.content,\n    ...node.props.resolved,\n    ...slotProps,\n  };\n\n  const element = (\n    <ResolvedDesignProvider value={tokenResolvedDesign}>\n      <ComponentErrorBoundary\n        fallback={createElement(renderError, { componentId: id, nodeId: node.nodeId })}\n        componentId={id}\n        kind={kind}\n        nodeId={node.nodeId}\n      >\n        {createElement(registrationConfig.component, composed)}\n      </ComponentErrorBoundary>\n    </ResolvedDesignProvider>\n  );\n\n  if (isExperienceTemplate) {\n    const contentful: ContentfulExperienceTemplate = {\n      experienceTemplateId: id,\n      nodeId: node.nodeId,\n      content: node.props.content,\n      design: node.props.designRaw,\n      resolved: node.props.resolved,\n    };\n    return (\n      <ContentfulExperienceTemplateProvider value={contentful}>\n        {element}\n      </ContentfulExperienceTemplateProvider>\n    );\n  }\n\n  const contentful: ContentfulComponent = {\n    componentId: id,\n    nodeId: node.nodeId,\n    content: node.props.content,\n    design: node.props.designRaw,\n    resolved: node.props.resolved,\n  };\n  return <ContentfulComponentProvider value={contentful}>{element}</ContentfulComponentProvider>;\n}\n\n// `ComponentErrorBoundary` lives in its own `'use client'` file — see\n// component-error-boundary.tsx for why (it's a class component, which\n// Next.js's RSC bundler rejects from a directive-free file).\n"],"mappings":"AAsEQ;AAhER,SAAS,UAAU,qBAAqC;AAGxD,SAAS,4BAA4B;AAErC,SAAS,8BAA8B;AAEvC;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,OACK;AAEP;AAAA,EACE;AAAA,EACA;AAAA,OAIK;AA+BA,SAAS,cAAc;AAAA,EAC5B;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF,GAAkC;AAChC,MAAI,CAAC,MAAM,OAAQ,QAAO;AAC1B,SACE,oBAAC,YACE,gBAAM,IAAI,CAAC,MAAM,UAChB;AAAA,IAAC;AAAA;AAAA,MAEC;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA;AAAA,IARK,KAAK,UAAU;AAAA,EAStB,CACD,GACH;AAEJ;AAaA,SAAS,aAAa;AAAA,EACpB;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF,GAAiC;AAC/B,QAAM,EAAE,MAAM,GAAG,IAAI,KAAK;AAC1B,QAAM,uBAAuB,SAAS;AAwBtC,QAAM,YAAyC,CAAC;AAChD,aAAW,CAAC,UAAU,QAAQ,KAAK,OAAO,QAAQ,KAAK,KAAK,GAAG;AAK7D,QAAI,CAAC,MAAM,QAAQ,QAAQ,GAAG;AAC5B,YAAM,UACJ,SAAS,QAAQ,QAAQ,IAAI,KAAK,EAAE,IAAI,KAAK,SAAS,WAAW,KAAK,MAAM,OAAO,EAAE;AAEvF,UAAI,OAAO,YAAY,aAAa;AAClC,gBAAQ,KAAK,mCAAmC,OAAO,EAAE;AAAA,MAC3D;AACA,mBAAa,IAAI,MAAM,OAAO,CAAC;AAC/B,gBAAU,QAAQ,IAAI,CAAC;AACvB;AAAA,IACF;AACA,cAAU,QAAQ,IAAI,SAAS,IAAI,CAAC,OAAO,UACzC;AAAA,MAAC;AAAA;AAAA,QAEC,MAAM;AAAA,QACN;AAAA,QACA;AAAA,QACA;AAAA,QACA;AAAA,QACA;AAAA,QACA;AAAA,QACA;AAAA;AAAA,MARK,MAAM,UAAU;AAAA,IASvB,CACD;AAAA,EACH;AAEA,QAAM,QAAQ,uBAAuB,OAAO,sBAAsB,EAAE,IAAI,OAAO,WAAW,EAAE;AAC5F,MAAI,CAAC,OAAO;AAIV,QAAI,sBAAsB;AACxB,YAAM,UAAU,6CAA6C,EAAE;AAC/D,UAAI,OAAO,YAAY,aAAa;AAClC,gBAAQ,KAAK,mCAAmC,OAAO,EAAE;AAAA,MAC3D;AACA,mBAAa,IAAI,MAAM,OAAO,CAAC;AAC/B,aAAO,oBAAC,YAAU,iBAAO,OAAO,SAAS,EAAE,KAAK,GAAE;AAAA,IACpD;AAIA;AAAA,MACE,IAAI;AAAA,QACF,mCAAmC,EAAE,IAAI,KAAK,SAAS,aAAa,KAAK,MAAM,MAAM,EAAE;AAAA,MACzF;AAAA,IACF;AACA,WAAO,cAAc,eAAe,EAAE,aAAa,IAAI,QAAQ,KAAK,OAAO,CAAC;AAAA,EAC9E;AACA,QAAM,qBAAqB,uBACvB,wCAAwC,KAAK,IAC7C,+BAA+B,KAAK;AAExC,QAAM,EAAE,OAAO,qBAAqB,WAAW,IAAI;AAAA,IACjD,KAAK;AAAA,IACL;AAAA,IACA;AAAA,IACA;AAAA,IACA,OAAO;AAAA,EACT;AACA,MAAI,WAAW,UAAU,OAAO,YAAY,aAAa;AACvD,YAAQ;AAAA,MACN,sFAAsF,IAAI,KAAK,EAAE,MAAM,WAAW,KAAK,IAAI,CAAC;AAAA,IAC9H;AAAA,EACF;AAGA,QAAM,WAAW;AAAA,IACf,GAAG,mBAAmB;AAAA,IACtB,GAAG;AAAA,IACH,GAAG,KAAK,MAAM;AAAA,IACd,GAAG,KAAK,MAAM;AAAA,IACd,GAAG;AAAA,EACL;AAEA,QAAM,UACJ,oBAAC,0BAAuB,OAAO,qBAC7B;AAAA,IAAC;AAAA;AAAA,MACC,UAAU,cAAc,aAAa,EAAE,aAAa,IAAI,QAAQ,KAAK,OAAO,CAAC;AAAA,MAC7E,aAAa;AAAA,MACb;AAAA,MACA,QAAQ,KAAK;AAAA,MAEZ,wBAAc,mBAAmB,WAAW,QAAQ;AAAA;AAAA,EACvD,GACF;AAGF,MAAI,sBAAsB;AACxB,UAAMA,cAA2C;AAAA,MAC/C,sBAAsB;AAAA,MACtB,QAAQ,KAAK;AAAA,MACb,SAAS,KAAK,MAAM;AAAA,MACpB,QAAQ,KAAK,MAAM;AAAA,MACnB,UAAU,KAAK,MAAM;AAAA,IACvB;AACA,WACE,oBAAC,wCAAqC,OAAOA,aAC1C,mBACH;AAAA,EAEJ;AAEA,QAAM,aAAkC;AAAA,IACtC,aAAa;AAAA,IACb,QAAQ,KAAK;AAAA,IACb,SAAS,KAAK,MAAM;AAAA,IACpB,QAAQ,KAAK,MAAM;AAAA,IACnB,UAAU,KAAK,MAAM;AAAA,EACvB;AACA,SAAO,oBAAC,+BAA4B,OAAO,YAAa,mBAAQ;AAClE;","names":["contentful"]}

package/dist/server-renderer.d.ts

@@ -1,29 +1,32 @@
 import { ReactNode } from 'react';
 import { PortableRenderPlan } from '@contentful/experiences-sdk-core';
-import { RenderUnknown } from './nodes-renderer.js';
+import { RenderUnknown, RenderError } from './nodes-renderer.js';
 import { Config } from './types.js';
+import './component-error.js';
 import './missing-component.js';
 
 interface ServerExperienceRendererProps {
     experience: PortableRenderPlan | null | undefined;
     config: Config;
-    /** Initial viewport seed (e.g. derived from User-Agent). Defaults to viewport[0]. */
-    initialViewportId?: string;
     /**
-     * Arbitrary per-render metadata, readable by descendants via
-     * `useExperience()` and by resolvers via `ctx.experience.metadata`.
+     * Viewport to render for, typically derived from the request's User-Agent.
+     * Defaults to the viewport the plan was pre-resolved against.
      */
+    initialViewportId?: string;
+    /** 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>` (the resolved-plan JSON panel) after the
-     * tree. Pair with `debug` on `fetchExperience` for end-to-end logging.
+     * tree. Defaults to the plan's `debug`.
      */
     debug?: boolean;
     /** Override the fallback rendered for unregistered component types. */
     renderUnknown?: RenderUnknown;
+    /** Override the fallback rendered when a registered component throws. */
+    renderError?: RenderError;
 }
-declare function ServerExperienceRenderer({ experience, config, initialViewportId, metadata, debug, renderUnknown, }: ServerExperienceRendererProps): ReactNode;
+declare function ServerExperienceRenderer({ experience, config, initialViewportId, metadata, debug, renderUnknown, renderError, }: ServerExperienceRendererProps): ReactNode;
 
 export { ServerExperienceRenderer, type ServerExperienceRendererProps };

package/dist/server-renderer.js

@@ -1,5 +1,6 @@
 import { jsx, jsxs } from "react/jsx-runtime";
 import { getViewportIndex } from "@contentful/experiences-design";
+import { ComponentError } from "./component-error";
 import { DebugExperience } from "./debug-experience";
 import { ExperienceProvider } from "./context";
 import { MissingComponent } from "./missing-component";
@@ -20,34 +21,47 @@ function ServerExperienceRenderer({
   config,
   initialViewportId,
   metadata,
-  debug = false,
-  renderUnknown = MissingComponent
+  debug,
+  renderUnknown = MissingComponent,
+  renderError = ComponentError
 }) {
   if (!experience) return null;
-  const activeViewportIndex = getViewportIndex(experience.viewports, initialViewportId);
+  const resolvedDebug = debug ?? experience.debug;
+  const activeViewportIndex = initialViewportId === void 0 ? experience.fallbackViewportIndex : getViewportIndex(experience.viewports, initialViewportId);
   const contextViewports = experience.viewports.map((v) => ({ ...v }));
   const activeViewport = { ...experience.viewports[activeViewportIndex] ?? FALLBACK_VIEWPORT };
   const renderContext = {
     ...DEFAULT_CONTEXT,
-    debug,
-    metadata: { ...DEFAULT_CONTEXT.metadata, ...metadata ?? {} },
+    debug: resolvedDebug,
+    metadata: { ...DEFAULT_CONTEXT.metadata, ...experience.metadata, ...metadata ?? {} },
     viewports: contextViewports,
     activeViewport,
-    activeViewportIndex
+    activeViewportIndex,
+    fallbackViewportIndex: experience.fallbackViewportIndex
   };
+  const renderDiagnostics = [...experience.diagnostics ?? []];
+  const seenDiagnostics = new Set(renderDiagnostics.map((error) => error.message));
+  const onDiagnostic = (error) => {
+    if (seenDiagnostics.has(error.message)) return;
+    seenDiagnostics.add(error.message);
+    renderDiagnostics.push(error);
+  };
+  const tree = /* @__PURE__ */ jsx(
+    NodesRenderer,
+    {
+      nodes: experience.nodes,
+      config,
+      viewports: experience.viewports,
+      activeViewportIndex,
+      fallbackViewportIndex: experience.fallbackViewportIndex,
+      renderUnknown,
+      renderError,
+      onDiagnostic
+    }
+  );
   return /* @__PURE__ */ jsxs(ExperienceProvider, { value: renderContext, children: [
-    debug ? /* @__PURE__ */ jsx(DebugExperience, { experience }) : null,
-    /* @__PURE__ */ jsx(
-      NodesRenderer,
-      {
-        nodes: experience.nodes,
-        config,
-        viewports: experience.viewports,
-        activeViewportIndex,
-        fallbackViewportIndex: experience.fallbackViewportIndex,
-        renderUnknown
-      }
-    )
+    tree,
+    resolvedDebug ? /* @__PURE__ */ jsx(DebugExperience, { experience, errors: renderDiagnostics }) : null
   ] });
 }
 export {

package/dist/server-renderer.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/server-renderer.tsx"],"sourcesContent":["/*\n * Server-safe Experience renderer. Resolves the active viewport once from\n * `initialViewportId` and renders without any reactive subscription.\n */\n\nimport type { ReactNode } from 'react';\n\nimport type {\n  ExperienceContext,\n  PortableRenderPlan,\n  ViewportDef,\n} from '@contentful/experiences-sdk-core';\nimport { getViewportIndex } from '@contentful/experiences-design';\n\nimport { DebugExperience } from './debug-experience';\nimport { ExperienceProvider } from './context';\nimport { MissingComponent } from './missing-component';\nimport { NodesRenderer, type RenderUnknown } from './nodes-renderer';\nimport type { Config, RenderContext } from './types';\n\nconst DEFAULT_CONTEXT: ExperienceContext = {\n  debug: false,\n  metadata: {},\n  viewports: [],\n};\n\n// Keeps `activeViewport` non-null when a payload declares no viewports.\nconst FALLBACK_VIEWPORT: ViewportDef = {\n  id: '_',\n  query: '*',\n  displayName: 'Default',\n  previewSize: '100%',\n};\n\nexport interface ServerExperienceRendererProps {\n  experience: PortableRenderPlan | null | undefined;\n  config: Config;\n  /** Initial viewport seed (e.g. derived from User-Agent). Defaults to viewport[0]. */\n  initialViewportId?: string;\n  /**\n   * Arbitrary per-render metadata, readable by descendants via\n   * `useExperience()` and by resolvers via `ctx.experience.metadata`.\n   */\n  metadata?: Record<string, unknown>;\n  /**\n   * Observability switch. When on: renders the visible missing-component box,\n   * turns the default `renderUnknown` fallback into the debug component, and\n   * auto-mounts `<DebugExperience>` (the resolved-plan JSON panel) after the\n   * tree. Pair with `debug` on `fetchExperience` for end-to-end logging.\n   */\n  debug?: boolean;\n  /** Override the fallback rendered for unregistered component types. */\n  renderUnknown?: RenderUnknown;\n}\n\nexport function ServerExperienceRenderer({\n  experience,\n  config,\n  initialViewportId,\n  metadata,\n  debug = false,\n  renderUnknown = MissingComponent,\n}: ServerExperienceRendererProps): ReactNode {\n  if (!experience) return null;\n\n  const activeViewportIndex = getViewportIndex(experience.viewports, initialViewportId);\n\n  // Copy viewports/activeViewport so the context (serialized + frozen by RSC)\n  // shares no object identity with the plan arrays the renderers read below —\n  // a shared reference makes Flight back-patch into frozen props and throw.\n  const contextViewports = experience.viewports.map((v) => ({ ...v }));\n  const activeViewport = { ...(experience.viewports[activeViewportIndex] ?? FALLBACK_VIEWPORT) };\n\n  const renderContext: RenderContext = {\n    ...DEFAULT_CONTEXT,\n    debug,\n    metadata: { ...DEFAULT_CONTEXT.metadata, ...(metadata ?? {}) },\n    viewports: contextViewports,\n    activeViewport,\n    activeViewportIndex,\n  };\n\n  return (\n    <ExperienceProvider value={renderContext}>\n      {debug ? <DebugExperience experience={experience} /> : null}\n      <NodesRenderer\n        nodes={experience.nodes}\n        config={config}\n        viewports={experience.viewports}\n        activeViewportIndex={activeViewportIndex}\n        fallbackViewportIndex={experience.fallbackViewportIndex}\n        renderUnknown={renderUnknown}\n      />\n    </ExperienceProvider>\n  );\n}\n"],"mappings":"AAmFI,SACW,KADX;AAvEJ,SAAS,wBAAwB;AAEjC,SAAS,uBAAuB;AAChC,SAAS,0BAA0B;AACnC,SAAS,wBAAwB;AACjC,SAAS,qBAAyC;AAGlD,MAAM,kBAAqC;AAAA,EACzC,OAAO;AAAA,EACP,UAAU,CAAC;AAAA,EACX,WAAW,CAAC;AACd;AAGA,MAAM,oBAAiC;AAAA,EACrC,IAAI;AAAA,EACJ,OAAO;AAAA,EACP,aAAa;AAAA,EACb,aAAa;AACf;AAuBO,SAAS,yBAAyB;AAAA,EACvC;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA,QAAQ;AAAA,EACR,gBAAgB;AAClB,GAA6C;AAC3C,MAAI,CAAC,WAAY,QAAO;AAExB,QAAM,sBAAsB,iBAAiB,WAAW,WAAW,iBAAiB;AAKpF,QAAM,mBAAmB,WAAW,UAAU,IAAI,CAAC,OAAO,EAAE,GAAG,EAAE,EAAE;AACnE,QAAM,iBAAiB,EAAE,GAAI,WAAW,UAAU,mBAAmB,KAAK,kBAAmB;AAE7F,QAAM,gBAA+B;AAAA,IACnC,GAAG;AAAA,IACH;AAAA,IACA,UAAU,EAAE,GAAG,gBAAgB,UAAU,GAAI,YAAY,CAAC,EAAG;AAAA,IAC7D,WAAW;AAAA,IACX;AAAA,IACA;AAAA,EACF;AAEA,SACE,qBAAC,sBAAmB,OAAO,eACxB;AAAA,YAAQ,oBAAC,mBAAgB,YAAwB,IAAK;AAAA,IACvD;AAAA,MAAC;AAAA;AAAA,QACC,OAAO,WAAW;AAAA,QAClB;AAAA,QACA,WAAW,WAAW;AAAA,QACtB;AAAA,QACA,uBAAuB,WAAW;AAAA,QAClC;AAAA;AAAA,IACF;AAAA,KACF;AAEJ;","names":[]}
+{"version":3,"sources":["../src/server-renderer.tsx"],"sourcesContent":["/*\n * Server-safe Experience renderer. Resolves the active viewport once from\n * `initialViewportId` and renders without any reactive subscription.\n */\n\nimport type { ReactNode } from 'react';\n\nimport type {\n  ExperienceContext,\n  PortableRenderPlan,\n  ViewportDef,\n} from '@contentful/experiences-sdk-core';\nimport { getViewportIndex } from '@contentful/experiences-design';\n\nimport { ComponentError } from './component-error';\nimport { DebugExperience } from './debug-experience';\nimport { ExperienceProvider } from './context';\nimport { MissingComponent } from './missing-component';\nimport { NodesRenderer, type RenderError, type RenderUnknown } from './nodes-renderer';\nimport type { Config, RenderContext } from './types';\n\nconst DEFAULT_CONTEXT: ExperienceContext = {\n  debug: false,\n  metadata: {},\n  viewports: [],\n};\n\n// Keeps `activeViewport` non-null when a payload declares no viewports.\nconst FALLBACK_VIEWPORT: ViewportDef = {\n  id: '_',\n  query: '*',\n  displayName: 'Default',\n  previewSize: '100%',\n};\n\nexport interface ServerExperienceRendererProps {\n  experience: PortableRenderPlan | null | undefined;\n  config: Config;\n  /**\n   * Viewport to render for, typically derived from the request's User-Agent.\n   * Defaults to the viewport the plan was pre-resolved against.\n   */\n  initialViewportId?: string;\n  /** Shallow-merges over the plan's `metadata`. Only needed to override it. */\n  metadata?: Record<string, unknown>;\n  /**\n   * Observability switch. When on: renders the visible missing-component box,\n   * turns the default `renderUnknown` fallback into the debug component, and\n   * auto-mounts `<DebugExperience>` (the resolved-plan JSON panel) after the\n   * tree. Defaults to the plan's `debug`.\n   */\n  debug?: boolean;\n  /** Override the fallback rendered for unregistered component types. */\n  renderUnknown?: RenderUnknown;\n  /** Override the fallback rendered when a registered component throws. */\n  renderError?: RenderError;\n}\n\nexport function ServerExperienceRenderer({\n  experience,\n  config,\n  initialViewportId,\n  metadata,\n  debug,\n  renderUnknown = MissingComponent,\n  renderError = ComponentError,\n}: ServerExperienceRendererProps): ReactNode {\n  if (!experience) return null;\n\n  // `??`, not `||`, so an explicit `debug={false}` overrides a debug-on plan.\n  const resolvedDebug = debug ?? experience.debug;\n  // Default to the pre-resolved viewport so first paint needs no recompute.\n  const activeViewportIndex =\n    initialViewportId === undefined\n      ? experience.fallbackViewportIndex\n      : getViewportIndex(experience.viewports, initialViewportId);\n\n  // Copy viewports/activeViewport so the context (serialized + frozen by RSC)\n  // shares no object identity with the plan arrays the renderers read below —\n  // a shared reference makes Flight back-patch into frozen props and throw.\n  const contextViewports = experience.viewports.map((v) => ({ ...v }));\n  const activeViewport = { ...(experience.viewports[activeViewportIndex] ?? FALLBACK_VIEWPORT) };\n\n  const renderContext: RenderContext = {\n    ...DEFAULT_CONTEXT,\n    debug: resolvedDebug,\n    metadata: { ...DEFAULT_CONTEXT.metadata, ...experience.metadata, ...(metadata ?? {}) },\n    viewports: contextViewports,\n    activeViewport,\n    activeViewportIndex,\n    fallbackViewportIndex: experience.fallbackViewportIndex,\n  };\n\n  // Render-time diagnostics (unregistered id, a component that threw),\n  // collected into a plain array rather than React state: SSR is synchronous\n  // top-down, so by the time `<DebugExperience>` renders — after the tree,\n  // see the element-order note below — this array is already fully populated.\n  // Seeded with the resolve-time diagnostics up front rather than spreading\n  // them in later: `<DebugExperience>` below reads this array by reference\n  // (`errors={renderDiagnostics}`), not a spread copy — a copy would be built\n  // right here, before React ever renders `tree` and gets a chance to push\n  // into it.\n  const renderDiagnostics: Error[] = [...(experience.diagnostics ?? [])];\n  // Dedup by message, the guard `NodeRenderer` used to hold in a `useRef`. It\n  // lives here so that module stays hook-free and therefore server-renderable.\n  // One pass on the server, so this mostly guards a node that reports the same\n  // message from several slots.\n  const seenDiagnostics = new Set(renderDiagnostics.map((error) => error.message));\n  const onDiagnostic = (error: Error): void => {\n    if (seenDiagnostics.has(error.message)) return;\n    seenDiagnostics.add(error.message);\n    renderDiagnostics.push(error);\n  };\n\n  const tree = (\n    <NodesRenderer\n      nodes={experience.nodes}\n      config={config}\n      viewports={experience.viewports}\n      activeViewportIndex={activeViewportIndex}\n      fallbackViewportIndex={experience.fallbackViewportIndex}\n      renderUnknown={renderUnknown}\n      renderError={renderError}\n      onDiagnostic={onDiagnostic}\n    />\n  );\n\n  // The node tree renders BEFORE `<DebugExperience>` — required, not\n  // stylistic. React's render is synchronous top-down; if DebugExperience\n  // rendered first (as it used to), it would read `renderDiagnostics` before\n  // any descendant had a chance to push into it, and always see it empty.\n  return (\n    <ExperienceProvider value={renderContext}>\n      {tree}\n      {resolvedDebug ? (\n        <DebugExperience experience={experience} errors={renderDiagnostics} />\n      ) : null}\n    </ExperienceProvider>\n  );\n}\n"],"mappings":"AAmHI,cAiBA,YAjBA;AAvGJ,SAAS,wBAAwB;AAEjC,SAAS,sBAAsB;AAC/B,SAAS,uBAAuB;AAChC,SAAS,0BAA0B;AACnC,SAAS,wBAAwB;AACjC,SAAS,qBAA2D;AAGpE,MAAM,kBAAqC;AAAA,EACzC,OAAO;AAAA,EACP,UAAU,CAAC;AAAA,EACX,WAAW,CAAC;AACd;AAGA,MAAM,oBAAiC;AAAA,EACrC,IAAI;AAAA,EACJ,OAAO;AAAA,EACP,aAAa;AAAA,EACb,aAAa;AACf;AAyBO,SAAS,yBAAyB;AAAA,EACvC;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA,gBAAgB;AAAA,EAChB,cAAc;AAChB,GAA6C;AAC3C,MAAI,CAAC,WAAY,QAAO;AAGxB,QAAM,gBAAgB,SAAS,WAAW;AAE1C,QAAM,sBACJ,sBAAsB,SAClB,WAAW,wBACX,iBAAiB,WAAW,WAAW,iBAAiB;AAK9D,QAAM,mBAAmB,WAAW,UAAU,IAAI,CAAC,OAAO,EAAE,GAAG,EAAE,EAAE;AACnE,QAAM,iBAAiB,EAAE,GAAI,WAAW,UAAU,mBAAmB,KAAK,kBAAmB;AAE7F,QAAM,gBAA+B;AAAA,IACnC,GAAG;AAAA,IACH,OAAO;AAAA,IACP,UAAU,EAAE,GAAG,gBAAgB,UAAU,GAAG,WAAW,UAAU,GAAI,YAAY,CAAC,EAAG;AAAA,IACrF,WAAW;AAAA,IACX;AAAA,IACA;AAAA,IACA,uBAAuB,WAAW;AAAA,EACpC;AAWA,QAAM,oBAA6B,CAAC,GAAI,WAAW,eAAe,CAAC,CAAE;AAKrE,QAAM,kBAAkB,IAAI,IAAI,kBAAkB,IAAI,CAAC,UAAU,MAAM,OAAO,CAAC;AAC/E,QAAM,eAAe,CAAC,UAAuB;AAC3C,QAAI,gBAAgB,IAAI,MAAM,OAAO,EAAG;AACxC,oBAAgB,IAAI,MAAM,OAAO;AACjC,sBAAkB,KAAK,KAAK;AAAA,EAC9B;AAEA,QAAM,OACJ;AAAA,IAAC;AAAA;AAAA,MACC,OAAO,WAAW;AAAA,MAClB;AAAA,MACA,WAAW,WAAW;AAAA,MACtB;AAAA,MACA,uBAAuB,WAAW;AAAA,MAClC;AAAA,MACA;AAAA,MACA;AAAA;AAAA,EACF;AAOF,SACE,qBAAC,sBAAmB,OAAO,eACxB;AAAA;AAAA,IACA,gBACC,oBAAC,mBAAgB,YAAwB,QAAQ,mBAAmB,IAClE;AAAA,KACN;AAEJ;","names":[]}

package/dist/types.d.ts

@@ -1,6 +1,6 @@
 import { ComponentType } from 'react';
-import { ResolveContext, ResolveToken, DesignPropValue, ExperienceContext, ViewportDef } from '@contentful/experiences-sdk-core';
-export { ResolveContext, ResolveToken } from '@contentful/experiences-sdk-core';
+import { ResolveContext, ResolveToken, DesignPropValue } from '@contentful/experiences-sdk-core';
+export { RenderContext, ResolveContext, ResolveToken } from '@contentful/experiences-sdk-core';
 
 /**
  * The full Contentful-side payload for a single component instance, exposed
@@ -32,16 +32,7 @@ interface ContentfulExperienceTemplate {
     design: Record<string, DesignPropValue>;
     resolved?: Record<string, unknown>;
 }
-/**
- * Render-time experience context. Extends the core `ExperienceContext` with
- * the active viewport — a render-time value that resolvers cannot see (they
- * run once before viewport resolution and are not re-triggered by viewport
- * changes). Exposed via `useExperience()` to any descendant of the renderer.
- */
-interface RenderContext extends ExperienceContext {
-    activeViewport: ViewportDef;
-    activeViewportIndex: number;
-}
+
 /**
  * Customer-supplied configuration for a single component. The `component`
  * receives the merged props (design + content + resolveData + slots); resolved
@@ -142,4 +133,4 @@ interface Config {
 declare function normalizeComponentRegistration<P extends object>(reg: Registration<P>): ComponentConfig<P>;
 declare function normalizeExperienceTemplateRegistration<P extends object>(reg: ExperienceTemplateRegistration<P>): ExperienceTemplateConfig<P>;
 
-export { type ComponentConfig, type Components, type Config, type ContentfulComponent, type ContentfulExperienceTemplate, type ExperienceTemplateConfig, type ExperienceTemplateRegistration, type ExperienceTemplates, type Registration, type RenderContext, defineComponent, defineExperienceTemplate, normalizeComponentRegistration, normalizeExperienceTemplateRegistration };
+export { type ComponentConfig, type Components, type Config, type ContentfulComponent, type ContentfulExperienceTemplate, type ExperienceTemplateConfig, type ExperienceTemplateRegistration, type ExperienceTemplates, type Registration, defineComponent, defineExperienceTemplate, normalizeComponentRegistration, normalizeExperienceTemplateRegistration };

package/dist/types.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/types.ts"],"sourcesContent":["import type { ComponentType } from 'react';\n\nimport type {\n  DesignPropValue,\n  ExperienceContext,\n  ResolveContext,\n  ResolveToken,\n  ViewportDef,\n} from '@contentful/experiences-sdk-core';\n\n/**\n * Re-exported for ergonomics: customer code authoring `resolveData` doesn't\n * have to dig into the core package for the context type.\n */\nexport type { ResolveContext, ResolveToken };\n\n/**\n * The full Contentful-side payload for a single component instance, exposed\n * via `useContentfulComponent()` to any descendant of a rendered Experience\n * node. Useful for custom design-property resolution outside the SDK's\n * cascade, branching by `componentId` in a generic wrapper, keying\n * analytics on `nodeId`, or rendering a raw-payload panel in preview.\n *\n * Design properties stay in their **raw discriminated form** here (the same\n * shape `ctx.design` carries inside `resolveData`). The viewport-cascaded,\n * token-resolved values are what `useDesignValues()` returns.\n */\nexport interface ContentfulComponent {\n  componentId: string;\n  nodeId?: string;\n  content: Record<string, unknown>;\n  design: Record<string, DesignPropValue>;\n  resolved?: Record<string, unknown>;\n}\n\n/**\n * Same shape as `ContentfulComponent`, but for an Experience Template node.\n * Exposed via `useContentfulExperienceTemplate()` inside an Experience\n * Template's component tree.\n */\nexport interface ContentfulExperienceTemplate {\n  experienceTemplateId: string;\n  nodeId?: string;\n  content: Record<string, unknown>;\n  design: Record<string, DesignPropValue>;\n  resolved?: Record<string, unknown>;\n}\n\n/**\n * Render-time experience context. Extends the core `ExperienceContext` with\n * the active viewport — a render-time value that resolvers cannot see (they\n * run once before viewport resolution and are not re-triggered by viewport\n * changes). Exposed via `useExperience()` to any descendant of the renderer.\n */\nexport interface RenderContext extends ExperienceContext {\n  activeViewport: ViewportDef;\n  activeViewportIndex: number;\n}\n\n/**\n * Customer-supplied configuration for a single component. The `component`\n * receives the merged props (design + content + resolveData + slots); resolved\n * design values auto-fill matching props and are also readable via\n * `useDesignValues()`. Runtime context and raw payload come from\n * `useExperience()` / `useContentfulComponent()`.\n */\nexport interface ComponentConfig<Props extends object = Record<string, unknown>> {\n  /**\n   * Lowest-precedence defaults object. Merged in before content / resolveData /\n   * slots. Useful for variant fallbacks the editorial layer doesn't always supply.\n   */\n  defaults?: Partial<Props>;\n  /**\n   * Optional sync-or-async hook that derives final props from the raw\n   * Experience inputs. Runs once during `resolveExperience`, before render —\n   * does NOT re-fire on viewport changes.\n   */\n  resolveData?: (ctx: ResolveContext) => Partial<Props> | Promise<Partial<Props>>;\n  /**\n   * The React component to render. Receives the merged props.\n   */\n  component: ComponentType<Props>;\n}\n\n/**\n * Registry value. Register a bare React component for the common case, or\n * the full `ComponentConfig` shape when you need defaults or a `resolveData`\n * hook.\n *\n *   button: Button,                                  // bare\n *   header: { component: Header, defaults: {...} }, // with defaults\n *   card:   defineComponent<CardProps>({ component: Card, resolveData: ... }),\n */\nexport type Registration<Props extends object = Record<string, unknown>> =\n  ComponentType<Props> | ComponentConfig<Props>;\n\n/**\n * Customer-supplied configuration for a coded Experience Template. Identical in\n * shape and behavior to `ComponentConfig` — an Experience Template is just a\n * node whose implementation lives in the `experienceTemplates` registry. Its\n * slots arrive as named props (a `content` slot becomes a `content` prop), so\n * there is no `children` special case.\n */\nexport interface ExperienceTemplateConfig<Props extends object = Record<string, unknown>> {\n  /**\n   * Lowest-precedence defaults object. Merged in before content / resolveData /\n   * slots. Useful for variant fallbacks the editorial layer doesn't always supply.\n   */\n  defaults?: Partial<Props>;\n  resolveData?: (ctx: ResolveContext) => Partial<Props> | Promise<Partial<Props>>;\n  component: ComponentType<Props>;\n}\n\n/**\n * Registry value for Experience Templates. Same dual-shape as component\n * registrations.\n */\nexport type ExperienceTemplateRegistration<Props extends object = Record<string, unknown>> =\n  ComponentType<Props> | ExperienceTemplateConfig<Props>;\n\n/**\n * Identity helper — returns the config as-is, but narrows the `resolveData`\n * and `component` parameter types to your declared `Props`.\n */\nexport function defineComponent<Props extends object = Record<string, unknown>>(\n  config: ComponentConfig<Props>\n): ComponentConfig<Props> {\n  return config;\n}\n\n/**\n * Identity helper — returns the Experience Template config as-is, with `Props`\n * narrowing.\n */\nexport function defineExperienceTemplate<Props extends object = Record<string, unknown>>(\n  config: ExperienceTemplateConfig<Props>\n): ExperienceTemplateConfig<Props> {\n  return config;\n}\n\n/**\n * Component registry — keyed by `componentId` (last slash-segment of\n * `component.sys.urn`). Per-entry prop narrowing happens at\n * `defineComponent<Props>` or at the bare-component's own type.\n */\n// eslint-disable-next-line @typescript-eslint/no-explicit-any -- per-entry narrowing happens at the registration author's call site.\nexport type Components = Record<string, Registration<any>>;\n\n/**\n * Experience Template registry — keyed by `experienceTemplateId` (last\n * slash-segment of an Experience Template node's own\n * `experienceTemplate.sys.urn`). Not read from `payload.sys`; templates are\n * ordinary nodes.\n */\n// eslint-disable-next-line @typescript-eslint/no-explicit-any -- per-entry narrowing happens at the registration author's call site.\nexport type ExperienceTemplates = Record<string, ExperienceTemplateRegistration<any>>;\n\nexport interface Config {\n  components: Components;\n  experienceTemplates?: ExperienceTemplates;\n  /**\n   * Resolves `DesignToken` values to runtime values before they reach a\n   * component. If omitted, they pass through unchanged. See `ResolveToken`\n   * in `@contentful/experiences-sdk-core` for the full contract.\n   */\n  resolveToken?: ResolveToken;\n}\n\n/**\n * Normalize a registry entry — bare component OR config object — into the\n * common `ComponentConfig` shape used by the renderer.\n *\n * React function components are plain functions; `React.memo` /\n * `React.forwardRef` yield objects carrying a `$$typeof` symbol. Both count\n * as bare components; a config object is discriminated by having a\n * `component` field and no `$$typeof`.\n */\nexport function normalizeComponentRegistration<P extends object>(\n  reg: Registration<P>\n): ComponentConfig<P> {\n  if (typeof reg === 'object' && reg !== null && !('$$typeof' in reg) && 'component' in reg) {\n    return reg as ComponentConfig<P>;\n  }\n  return { component: reg as ComponentType<P> };\n}\n\nexport function normalizeExperienceTemplateRegistration<P extends object>(\n  reg: ExperienceTemplateRegistration<P>\n): ExperienceTemplateConfig<P> {\n  if (typeof reg === 'object' && reg !== null && !('$$typeof' in reg) && 'component' in reg) {\n    return reg as ExperienceTemplateConfig<P>;\n  }\n  return { component: reg as ComponentType<P> };\n}\n"],"mappings":"AA4HO,SAAS,gBACd,QACwB;AACxB,SAAO;AACT;AAMO,SAAS,yBACd,QACiC;AACjC,SAAO;AACT;AAuCO,SAAS,+BACd,KACoB;AACpB,MAAI,OAAO,QAAQ,YAAY,QAAQ,QAAQ,EAAE,cAAc,QAAQ,eAAe,KAAK;AACzF,WAAO;AAAA,EACT;AACA,SAAO,EAAE,WAAW,IAAwB;AAC9C;AAEO,SAAS,wCACd,KAC6B;AAC7B,MAAI,OAAO,QAAQ,YAAY,QAAQ,QAAQ,EAAE,cAAc,QAAQ,eAAe,KAAK;AACzF,WAAO;AAAA,EACT;AACA,SAAO,EAAE,WAAW,IAAwB;AAC9C;","names":[]}
+{"version":3,"sources":["../src/types.ts"],"sourcesContent":["import type { ComponentType } from 'react';\n\nimport type {\n  DesignPropValue,\n  RenderContext,\n  ResolveContext,\n  ResolveToken,\n} from '@contentful/experiences-sdk-core';\n\n/**\n * Re-exported for ergonomics: customer code authoring `resolveData` doesn't\n * have to dig into the core package for the context type.\n */\nexport type { ResolveContext, ResolveToken };\n\n/**\n * The full Contentful-side payload for a single component instance, exposed\n * via `useContentfulComponent()` to any descendant of a rendered Experience\n * node. Useful for custom design-property resolution outside the SDK's\n * cascade, branching by `componentId` in a generic wrapper, keying\n * analytics on `nodeId`, or rendering a raw-payload panel in preview.\n *\n * Design properties stay in their **raw discriminated form** here (the same\n * shape `ctx.design` carries inside `resolveData`). The viewport-cascaded,\n * token-resolved values are what `useDesignValues()` returns.\n */\nexport interface ContentfulComponent {\n  componentId: string;\n  nodeId?: string;\n  content: Record<string, unknown>;\n  design: Record<string, DesignPropValue>;\n  resolved?: Record<string, unknown>;\n}\n\n/**\n * Same shape as `ContentfulComponent`, but for an Experience Template node.\n * Exposed via `useContentfulExperienceTemplate()` inside an Experience\n * Template's component tree.\n */\nexport interface ContentfulExperienceTemplate {\n  experienceTemplateId: string;\n  nodeId?: string;\n  content: Record<string, unknown>;\n  design: Record<string, DesignPropValue>;\n  resolved?: Record<string, unknown>;\n}\n\n/** Render-time experience context, read with `useExperience()`. Declared in core so all adapters share one shape. */\nexport type { RenderContext };\n\n/**\n * Customer-supplied configuration for a single component. The `component`\n * receives the merged props (design + content + resolveData + slots); resolved\n * design values auto-fill matching props and are also readable via\n * `useDesignValues()`. Runtime context and raw payload come from\n * `useExperience()` / `useContentfulComponent()`.\n */\nexport interface ComponentConfig<Props extends object = Record<string, unknown>> {\n  /**\n   * Lowest-precedence defaults object. Merged in before content / resolveData /\n   * slots. Useful for variant fallbacks the editorial layer doesn't always supply.\n   */\n  defaults?: Partial<Props>;\n  /**\n   * Optional sync-or-async hook that derives final props from the raw\n   * Experience inputs. Runs once during `resolveExperience`, before render —\n   * does NOT re-fire on viewport changes.\n   */\n  resolveData?: (ctx: ResolveContext) => Partial<Props> | Promise<Partial<Props>>;\n  /**\n   * The React component to render. Receives the merged props.\n   */\n  component: ComponentType<Props>;\n}\n\n/**\n * Registry value. Register a bare React component for the common case, or\n * the full `ComponentConfig` shape when you need defaults or a `resolveData`\n * hook.\n *\n *   button: Button,                                  // bare\n *   header: { component: Header, defaults: {...} }, // with defaults\n *   card:   defineComponent<CardProps>({ component: Card, resolveData: ... }),\n */\nexport type Registration<Props extends object = Record<string, unknown>> =\n  ComponentType<Props> | ComponentConfig<Props>;\n\n/**\n * Customer-supplied configuration for a coded Experience Template. Identical in\n * shape and behavior to `ComponentConfig` — an Experience Template is just a\n * node whose implementation lives in the `experienceTemplates` registry. Its\n * slots arrive as named props (a `content` slot becomes a `content` prop), so\n * there is no `children` special case.\n */\nexport interface ExperienceTemplateConfig<Props extends object = Record<string, unknown>> {\n  /**\n   * Lowest-precedence defaults object. Merged in before content / resolveData /\n   * slots. Useful for variant fallbacks the editorial layer doesn't always supply.\n   */\n  defaults?: Partial<Props>;\n  resolveData?: (ctx: ResolveContext) => Partial<Props> | Promise<Partial<Props>>;\n  component: ComponentType<Props>;\n}\n\n/**\n * Registry value for Experience Templates. Same dual-shape as component\n * registrations.\n */\nexport type ExperienceTemplateRegistration<Props extends object = Record<string, unknown>> =\n  ComponentType<Props> | ExperienceTemplateConfig<Props>;\n\n/**\n * Identity helper — returns the config as-is, but narrows the `resolveData`\n * and `component` parameter types to your declared `Props`.\n */\nexport function defineComponent<Props extends object = Record<string, unknown>>(\n  config: ComponentConfig<Props>\n): ComponentConfig<Props> {\n  return config;\n}\n\n/**\n * Identity helper — returns the Experience Template config as-is, with `Props`\n * narrowing.\n */\nexport function defineExperienceTemplate<Props extends object = Record<string, unknown>>(\n  config: ExperienceTemplateConfig<Props>\n): ExperienceTemplateConfig<Props> {\n  return config;\n}\n\n/**\n * Component registry — keyed by `componentId` (last slash-segment of\n * `component.sys.urn`). Per-entry prop narrowing happens at\n * `defineComponent<Props>` or at the bare-component's own type.\n */\n// eslint-disable-next-line @typescript-eslint/no-explicit-any -- per-entry narrowing happens at the registration author's call site.\nexport type Components = Record<string, Registration<any>>;\n\n/**\n * Experience Template registry — keyed by `experienceTemplateId` (last\n * slash-segment of an Experience Template node's own\n * `experienceTemplate.sys.urn`). Not read from `payload.sys`; templates are\n * ordinary nodes.\n */\n// eslint-disable-next-line @typescript-eslint/no-explicit-any -- per-entry narrowing happens at the registration author's call site.\nexport type ExperienceTemplates = Record<string, ExperienceTemplateRegistration<any>>;\n\nexport interface Config {\n  components: Components;\n  experienceTemplates?: ExperienceTemplates;\n  /**\n   * Resolves `DesignToken` values to runtime values before they reach a\n   * component. If omitted, they pass through unchanged. See `ResolveToken`\n   * in `@contentful/experiences-sdk-core` for the full contract.\n   */\n  resolveToken?: ResolveToken;\n}\n\n/**\n * Normalize a registry entry — bare component OR config object — into the\n * common `ComponentConfig` shape used by the renderer.\n *\n * React function components are plain functions; `React.memo` /\n * `React.forwardRef` yield objects carrying a `$$typeof` symbol. Both count\n * as bare components; a config object is discriminated by having a\n * `component` field and no `$$typeof`.\n */\nexport function normalizeComponentRegistration<P extends object>(\n  reg: Registration<P>\n): ComponentConfig<P> {\n  if (typeof reg === 'object' && reg !== null && !('$$typeof' in reg) && 'component' in reg) {\n    return reg as ComponentConfig<P>;\n  }\n  return { component: reg as ComponentType<P> };\n}\n\nexport function normalizeExperienceTemplateRegistration<P extends object>(\n  reg: ExperienceTemplateRegistration<P>\n): ExperienceTemplateConfig<P> {\n  if (typeof reg === 'object' && reg !== null && !('$$typeof' in reg) && 'component' in reg) {\n    return reg as ExperienceTemplateConfig<P>;\n  }\n  return { component: reg as ComponentType<P> };\n}\n"],"mappings":"AAmHO,SAAS,gBACd,QACwB;AACxB,SAAO;AACT;AAMO,SAAS,yBACd,QACiC;AACjC,SAAO;AACT;AAuCO,SAAS,+BACd,KACoB;AACpB,MAAI,OAAO,QAAQ,YAAY,QAAQ,QAAQ,EAAE,cAAc,QAAQ,eAAe,KAAK;AACzF,WAAO;AAAA,EACT;AACA,SAAO,EAAE,WAAW,IAAwB;AAC9C;AAEO,SAAS,wCACd,KAC6B;AAC7B,MAAI,OAAO,QAAQ,YAAY,QAAQ,QAAQ,EAAE,cAAc,QAAQ,eAAe,KAAK;AACzF,WAAO;AAAA,EACT;AACA,SAAO,EAAE,WAAW,IAAwB;AAC9C;","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contentful/experiences-react",
-  "version": "0.7.11",
+  "version": "0.8.0",
   "description": "React adapter for Contentful Experiences — Server and Client renderers over a PortableRenderPlan",
   "license": "MIT",
   "type": "module",
@@ -30,9 +30,9 @@
     "directory": "packages/adapter-react"
   },
   "dependencies": {
-    "@contentful/experiences-client": "0.3.10",
-    "@contentful/experiences-sdk-core": "0.7.10",
-    "@contentful/experiences-design": "0.7.10"
+    "@contentful/experiences-client": "0.4.0",
+    "@contentful/experiences-sdk-core": "0.8.0",
+    "@contentful/experiences-design": "0.8.0"
   },
   "peerDependencies": {
     "react": "^18.0.0 || ^19.0.0",