@contentful/experiences-react 0.5.1

package/CHANGELOG.md

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

package/README.md

@@ -0,0 +1,117 @@
+# @contentful/experiences-react
+
+> ⚠️ **Pre-alpha.** Not yet published to npm. APIs are unstable and will change.
+
+The React adapter for the Contentful Experiences SDK suite. Renders Experience payloads from the Experience Delivery API (XDA) using customer-supplied React components.
+
+```sh
+npm install @contentful/experiences-react
+```
+
+This is the **only SDK package customers install** — it re-exports everything from `@contentful/experiences-core`, `@contentful/experiences-design`, and `@contentful/experiences-client` that consumers need. The other packages are workspace-internal.
+
+---
+
+## Public API
+
+### Authoring
+
+```ts
+defineComponent<Props>(config); // Type-narrowing identity for component-type configs
+defineTemplate<Props>(config); // Same shape, for page-level template wrappers
+```
+
+### Fetching
+
+```ts
+fetchExperience(experienceOptions, clientOptions, resolveOptions)  // Async — fetches from XDA + resolves in one call
+createClient(options)                       // Functional constructor matching the SDK's option shape
+ContentfulViewDeliveryClient                // Re-exported delivery client for advanced use cases
+NotFoundError                               // Thrown when the Experience ID doesn't exist
+ContentfulViewDelivery                      // Full error namespace from the delivery client
+type ExperienceOptions, ClientOptions, ResolveOptions, CreateClientOptions
+```
+
+### Resolver
+
+```ts
+resolveExperience(payload, config, opts?)   // Async — walks payload, runs resolveData, returns a PortableRenderPlan
+```
+
+### Renderers
+
+```ts
+ServerExperienceRenderer; // RSC-friendly, active viewport seeded from initialViewportId
+ClientExperienceRenderer; // 'use client', subscribes to window.matchMedia, alias: ExperienceRenderer
+MissingComponent; // Default fallback for unregistered component types
+useActiveViewport; // Hook used inside ClientExperienceRenderer (rarely needed by consumers)
+```
+
+### Re-exported types and utilities
+
+```ts
+// From core
+type Config, Components, Templates,
+type ComponentConfig, TemplateConfig,
+type ComponentProps, TemplateProps,
+type RenderContext,
+type ExperiencePayload, ExperienceNode, ComponentTypeNode, TemplateNode,
+type PortableRenderPlan, PortableRenderNode, PortableTemplate,
+type DesignPropValue, ManualDesignValue, DesignToken, ValuesByViewport,
+type ViewportDef, ExperienceContext, ResolveContext,
+type ResolverConfig, ResolveExperienceOptions
+
+// From design (for customers who want to do their own viewport-aware resolution)
+getValueForViewport, getViewportIndex, resolveDesignProperties, toCssMediaQuery
+```
+
+---
+
+## Quick reference
+
+```tsx
+import { notFound } from 'next/navigation';
+import {
+  defineComponent,
+  defineTemplate,
+  fetchExperience,
+  NotFoundError,
+  ServerExperienceRenderer,
+  type Config,
+  type Components,
+  type Templates,
+} from '@contentful/experiences-react';
+
+import { Button, type ButtonProps } from './components/Button';
+
+const components: Components = {
+  button: defineComponent<ButtonProps>({
+    defaults: { type: 'primary' },
+    resolveData: ({ content }) => ({ url: ensureScheme(content.url) }),
+    render: Button,
+  }),
+};
+
+const experienceConfig: Config = { components };
+
+// In a server component:
+try {
+  const experience = await fetchExperience(
+    { spaceId: process.env.SPACE_ID!, environmentId: 'master', experienceId: slug },
+    { accessToken: process.env.CDA_TOKEN! },
+    { config: experienceConfig }
+  );
+  return <ServerExperienceRenderer experience={experience} config={experienceConfig} />;
+} catch (err) {
+  if (err instanceof NotFoundError) notFound();
+  throw err;
+}
+```
+
+For the full getting-started walkthrough, the merge-precedence rules, viewport handling, and design rationale, see the [root README](../../README.md) and [`AGENTS.md`](../../AGENTS.md).
+
+---
+
+## License
+
+MIT. See the repository [`LICENSE`](../../LICENSE) and [`NOTICE`](../../NOTICE) for full attribution.

package/dist/client-renderer.d.ts

@@ -0,0 +1,17 @@
+import { ReactNode } from 'react';
+import { PortableRenderPlan, ExperienceContext } from '@contentful/experiences-core';
+import { RenderUnknown } from './nodes-renderer.js';
+import { Config } from './types.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;
+    context?: Partial<ExperienceContext>;
+    renderUnknown?: RenderUnknown;
+}
+declare function ClientExperienceRenderer({ experience, config, initialViewportId, context, renderUnknown, }: ClientExperienceRendererProps): ReactNode;
+
+export { ClientExperienceRenderer, type ClientExperienceRendererProps };

package/dist/client-renderer.js

@@ -0,0 +1,60 @@
+"use client";
+import { jsx } from "react/jsx-runtime";
+import { ExperienceProvider } from "./context";
+import { MissingComponent } from "./missing-component";
+import { NodesRenderer, WrapWithTemplate } from "./nodes-renderer";
+import { useActiveViewport } from "./use-active-viewport";
+const DEFAULT_CONTEXT = {
+  isPreview: false,
+  metadata: {},
+  viewports: []
+};
+const FALLBACK_VIEWPORT = {
+  id: "_",
+  query: "*",
+  displayName: "Default",
+  previewSize: "100%"
+};
+function ClientExperienceRenderer({
+  experience,
+  config,
+  initialViewportId,
+  context,
+  renderUnknown = MissingComponent
+}) {
+  if (!experience) return null;
+  const { activeViewportIndex } = useActiveViewport(experience.viewports, initialViewportId);
+  const contextViewports = experience.viewports.map((v) => ({ ...v }));
+  const activeViewport = { ...experience.viewports[activeViewportIndex] ?? FALLBACK_VIEWPORT };
+  const renderContext = {
+    ...DEFAULT_CONTEXT,
+    ...context,
+    metadata: { ...DEFAULT_CONTEXT.metadata, ...context?.metadata ?? {} },
+    viewports: contextViewports,
+    activeViewport,
+    activeViewportIndex
+  };
+  return /* @__PURE__ */ jsx(ExperienceProvider, { value: renderContext, children: /* @__PURE__ */ jsx(
+    WrapWithTemplate,
+    {
+      template: experience.template,
+      config,
+      viewports: experience.viewports,
+      activeViewportIndex,
+      children: /* @__PURE__ */ jsx(
+        NodesRenderer,
+        {
+          nodes: experience.nodes,
+          config,
+          viewports: experience.viewports,
+          activeViewportIndex,
+          renderUnknown
+        }
+      )
+    }
+  ) });
+}
+export {
+  ClientExperienceRenderer
+};
+//# sourceMappingURL=client-renderer.js.map

package/dist/client-renderer.js.map

@@ -0,0 +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-core';\n\nimport { ExperienceProvider } from './context';\nimport { MissingComponent } from './missing-component';\nimport { NodesRenderer, WrapWithTemplate, type RenderUnknown } from './nodes-renderer';\nimport type { Config, RenderContext } from './types';\nimport { useActiveViewport } from './use-active-viewport';\n\nconst DEFAULT_CONTEXT: ExperienceContext = {\n  isPreview: 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  context?: Partial<ExperienceContext>;\n  renderUnknown?: RenderUnknown;\n}\n\nexport function ClientExperienceRenderer({\n  experience,\n  config,\n  initialViewportId,\n  context,\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    ...context,\n    metadata: { ...DEFAULT_CONTEXT.metadata, ...(context?.metadata ?? {}) },\n    viewports: contextViewports,\n    activeViewport,\n    activeViewportIndex,\n  };\n\n  return (\n    <ExperienceProvider value={renderContext}>\n      <WrapWithTemplate\n        template={experience.template}\n        config={config}\n        viewports={experience.viewports}\n        activeViewportIndex={activeViewportIndex}\n      >\n        <NodesRenderer\n          nodes={experience.nodes}\n          config={config}\n          viewports={experience.viewports}\n          activeViewportIndex={activeViewportIndex}\n          renderUnknown={renderUnknown}\n        />\n      </WrapWithTemplate>\n    </ExperienceProvider>\n  );\n}\n"],"mappings":";AA4EQ;AA3DR,SAAS,0BAA0B;AACnC,SAAS,wBAAwB;AACjC,SAAS,eAAe,wBAA4C;AAEpE,SAAS,yBAAyB;AAElC,MAAM,kBAAqC;AAAA,EACzC,WAAW;AAAA,EACX,UAAU,CAAC;AAAA,EACX,WAAW,CAAC;AACd;AAEA,MAAM,oBAAiC;AAAA,EACrC,IAAI;AAAA,EACJ,OAAO;AAAA,EACP,aAAa;AAAA,EACb,aAAa;AACf;AAWO,SAAS,yBAAyB;AAAA,EACvC;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA,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,GAAG;AAAA,IACH,UAAU,EAAE,GAAG,gBAAgB,UAAU,GAAI,SAAS,YAAY,CAAC,EAAG;AAAA,IACtE,WAAW;AAAA,IACX;AAAA,IACA;AAAA,EACF;AAEA,SACE,oBAAC,sBAAmB,OAAO,eACzB;AAAA,IAAC;AAAA;AAAA,MACC,UAAU,WAAW;AAAA,MACrB;AAAA,MACA,WAAW,WAAW;AAAA,MACtB;AAAA,MAEA;AAAA,QAAC;AAAA;AAAA,UACC,OAAO,WAAW;AAAA,UAClB;AAAA,UACA,WAAW,WAAW;AAAA,UACtB;AAAA,UACA;AAAA;AAAA,MACF;AAAA;AAAA,EACF,GACF;AAEJ;","names":[]}

package/dist/context.d.ts

@@ -0,0 +1,46 @@
+import { ReactNode } from 'react';
+import { ContentfulComponent, ContentfulTemplate, RenderContext } from './types.js';
+import '@contentful/experiences-core';
+
+declare function ExperienceProvider({ value, children, }: {
+    value: RenderContext;
+    children: ReactNode;
+}): ReactNode;
+declare function ContentfulComponentProvider({ value, children, }: {
+    value: ContentfulComponent;
+    children: ReactNode;
+}): ReactNode;
+declare function ContentfulTemplateProvider({ value, children, }: {
+    value: ContentfulTemplate;
+    children: ReactNode;
+}): ReactNode;
+declare function ResolvedDesignProvider({ value, children, }: {
+    value: Record<string, unknown>;
+    children: ReactNode;
+}): ReactNode;
+/**
+ * Read the current Experience runtime context — viewports, the active
+ * viewport, preview flag, and free-form metadata. Throws when called outside
+ * any Experience renderer subtree.
+ */
+declare function useExperience(): RenderContext;
+/**
+ * Read the raw Contentful payload for the nearest enclosing Experience node.
+ * Returns `null` outside any rendered node (e.g. from a template's chrome
+ * that wraps the nodes but isn't itself a node).
+ */
+declare function useContentfulComponent(): ContentfulComponent | null;
+/**
+ * Read the raw Contentful payload for the page-level template, if one is in
+ * scope. Returns `null` outside a template's render tree.
+ */
+declare function useContentfulTemplate(): ContentfulTemplate | null;
+/**
+ * Read the design values the renderer already resolved for the enclosing
+ * node or template — viewport-cascaded and token-resolved, the same bag that
+ * feeds the component's props. Returns `null` outside a rendered node/
+ * template, which `useDesignValues` treats as "nothing to read."
+ */
+declare function useResolvedDesign(): Record<string, unknown> | null;
+
+export { ContentfulComponentProvider, ContentfulTemplateProvider, ExperienceProvider, ResolvedDesignProvider, useContentfulComponent, useContentfulTemplate, useExperience, useResolvedDesign };

package/dist/context.js

@@ -0,0 +1,60 @@
+"use client";
+import { jsx } from "react/jsx-runtime";
+import { createContext, useContext } from "react";
+const ExperienceContext = createContext(null);
+const ContentfulComponentContext = createContext(null);
+const ContentfulTemplateContext = createContext(null);
+const ResolvedDesignContext = createContext(null);
+function ExperienceProvider({
+  value,
+  children
+}) {
+  return /* @__PURE__ */ jsx(ExperienceContext.Provider, { value, children });
+}
+function ContentfulComponentProvider({
+  value,
+  children
+}) {
+  return /* @__PURE__ */ jsx(ContentfulComponentContext.Provider, { value, children });
+}
+function ContentfulTemplateProvider({
+  value,
+  children
+}) {
+  return /* @__PURE__ */ jsx(ContentfulTemplateContext.Provider, { value, children });
+}
+function ResolvedDesignProvider({
+  value,
+  children
+}) {
+  return /* @__PURE__ */ jsx(ResolvedDesignContext.Provider, { value, children });
+}
+function useExperience() {
+  const ctx = useContext(ExperienceContext);
+  if (ctx === null) {
+    throw new Error(
+      "useExperience() must be called inside a <ServerExperienceRenderer> or <ClientExperienceRenderer> subtree."
+    );
+  }
+  return ctx;
+}
+function useContentfulComponent() {
+  return useContext(ContentfulComponentContext);
+}
+function useContentfulTemplate() {
+  return useContext(ContentfulTemplateContext);
+}
+function useResolvedDesign() {
+  return useContext(ResolvedDesignContext);
+}
+export {
+  ContentfulComponentProvider,
+  ContentfulTemplateProvider,
+  ExperienceProvider,
+  ResolvedDesignProvider,
+  useContentfulComponent,
+  useContentfulTemplate,
+  useExperience,
+  useResolvedDesign
+};
+//# sourceMappingURL=context.js.map

package/dist/context.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/context.tsx"],"sourcesContent":["/*\n * React context providers + hooks that expose runtime context and the raw\n * Contentful payload to descendants of a rendered Experience. Customer\n * components receive only their declared props via the renderer; anything\n * that needs the Experience runtime context or the underlying payload calls\n * the hook explicitly at the top of its component body.\n */\n\n'use client';\n\nimport { createContext, useContext, type ReactNode } from 'react';\n\nimport type { ContentfulComponent, ContentfulTemplate, RenderContext } from './types';\n\nconst ExperienceContext = createContext<RenderContext | null>(null);\nconst ContentfulComponentContext = createContext<ContentfulComponent | null>(null);\nconst ContentfulTemplateContext = createContext<ContentfulTemplate | null>(null);\n// Plain data only (never the Config or its functions) so it crosses RSC cleanly.\nconst ResolvedDesignContext = createContext<Record<string, unknown> | null>(null);\n\n// Wrapped as real client-component functions, not re-exported `Context.Provider`\n// objects — the server renderer imports these across the RSC boundary and\n// Next.js requires a function reference there (\"Element type is invalid\" otherwise).\n\nexport function ExperienceProvider({\n  value,\n  children,\n}: {\n  value: RenderContext;\n  children: ReactNode;\n}): ReactNode {\n  return <ExperienceContext.Provider value={value}>{children}</ExperienceContext.Provider>;\n}\n\nexport function ContentfulComponentProvider({\n  value,\n  children,\n}: {\n  value: ContentfulComponent;\n  children: ReactNode;\n}): ReactNode {\n  return (\n    <ContentfulComponentContext.Provider value={value}>\n      {children}\n    </ContentfulComponentContext.Provider>\n  );\n}\n\nexport function ContentfulTemplateProvider({\n  value,\n  children,\n}: {\n  value: ContentfulTemplate;\n  children: ReactNode;\n}): ReactNode {\n  return (\n    <ContentfulTemplateContext.Provider value={value}>\n      {children}\n    </ContentfulTemplateContext.Provider>\n  );\n}\n\nexport function ResolvedDesignProvider({\n  value,\n  children,\n}: {\n  value: Record<string, unknown>;\n  children: ReactNode;\n}): ReactNode {\n  return <ResolvedDesignContext.Provider value={value}>{children}</ResolvedDesignContext.Provider>;\n}\n\n/**\n * Read the current Experience runtime context — viewports, the active\n * viewport, preview flag, and free-form metadata. Throws when called outside\n * any Experience renderer subtree.\n */\nexport function useExperience(): RenderContext {\n  const ctx = useContext(ExperienceContext);\n  if (ctx === null) {\n    throw new Error(\n      'useExperience() must be called inside a <ServerExperienceRenderer> or <ClientExperienceRenderer> subtree.'\n    );\n  }\n  return ctx;\n}\n\n/**\n * Read the raw Contentful payload for the nearest enclosing Experience node.\n * Returns `null` outside any rendered node (e.g. from a template's chrome\n * that wraps the nodes but isn't itself a node).\n */\nexport function useContentfulComponent(): ContentfulComponent | null {\n  return useContext(ContentfulComponentContext);\n}\n\n/**\n * Read the raw Contentful payload for the page-level template, if one is in\n * scope. Returns `null` outside a template's render tree.\n */\nexport function useContentfulTemplate(): ContentfulTemplate | null {\n  return useContext(ContentfulTemplateContext);\n}\n\n/**\n * Read the design values the renderer already resolved for the enclosing\n * node or template — viewport-cascaded and token-resolved, the same bag that\n * feeds the component's props. Returns `null` outside a rendered node/\n * template, which `useDesignValues` treats as \"nothing to read.\"\n */\nexport function useResolvedDesign(): Record<string, unknown> | null {\n  return useContext(ResolvedDesignContext);\n}\n"],"mappings":";AA+BS;AArBT,SAAS,eAAe,kBAAkC;AAI1D,MAAM,oBAAoB,cAAoC,IAAI;AAClE,MAAM,6BAA6B,cAA0C,IAAI;AACjF,MAAM,4BAA4B,cAAyC,IAAI;AAE/E,MAAM,wBAAwB,cAA8C,IAAI;AAMzE,SAAS,mBAAmB;AAAA,EACjC;AAAA,EACA;AACF,GAGc;AACZ,SAAO,oBAAC,kBAAkB,UAAlB,EAA2B,OAAe,UAAS;AAC7D;AAEO,SAAS,4BAA4B;AAAA,EAC1C;AAAA,EACA;AACF,GAGc;AACZ,SACE,oBAAC,2BAA2B,UAA3B,EAAoC,OAClC,UACH;AAEJ;AAEO,SAAS,2BAA2B;AAAA,EACzC;AAAA,EACA;AACF,GAGc;AACZ,SACE,oBAAC,0BAA0B,UAA1B,EAAmC,OACjC,UACH;AAEJ;AAEO,SAAS,uBAAuB;AAAA,EACrC;AAAA,EACA;AACF,GAGc;AACZ,SAAO,oBAAC,sBAAsB,UAAtB,EAA+B,OAAe,UAAS;AACjE;AAOO,SAAS,gBAA+B;AAC7C,QAAM,MAAM,WAAW,iBAAiB;AACxC,MAAI,QAAQ,MAAM;AAChB,UAAM,IAAI;AAAA,MACR;AAAA,IACF;AAAA,EACF;AACA,SAAO;AACT;AAOO,SAAS,yBAAqD;AACnE,SAAO,WAAW,0BAA0B;AAC9C;AAMO,SAAS,wBAAmD;AACjE,SAAO,WAAW,yBAAyB;AAC7C;AAQO,SAAS,oBAAoD;AAClE,SAAO,WAAW,qBAAqB;AACzC;","names":[]}

package/dist/design-utils.d.ts

@@ -0,0 +1,18 @@
+import { CSSProperties } from 'react';
+
+interface ToCssOptions {
+    /** Keys to skip, matched against the original record key. */
+    exclude?: string[];
+    /** When set, only these keys pass through (still whitelist-filtered). */
+    include?: string[];
+}
+/**
+ * Convert a design record into a `CSSProperties` object, keeping only keys
+ * that normalize to a known CSS property. Non-CSS keys (`variant`, `as`, …)
+ * are dropped; read those off the `useDesignValues()` record directly.
+ *
+ *   toCss({ fontSize: '20px', variant: 'h1' }) //=> { fontSize: '20px' }
+ */
+declare function toCss(design: object, { include, exclude }?: ToCssOptions): CSSProperties;
+
+export { type ToCssOptions, toCss };

package/dist/design-utils.js

@@ -0,0 +1,17 @@
+import { isCssProperty, toCssKey } from "@contentful/experiences-design";
+function toCss(design, { include, exclude } = {}) {
+  const out = {};
+  for (const [key, value] of Object.entries(design)) {
+    if (include && !include.includes(key)) continue;
+    if (exclude?.includes(key)) continue;
+    if (value === void 0 || value === null) continue;
+    const cssKey = toCssKey(key);
+    if (!isCssProperty(cssKey)) continue;
+    out[cssKey] = value;
+  }
+  return out;
+}
+export {
+  toCss
+};
+//# sourceMappingURL=design-utils.js.map

package/dist/design-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/design-utils.ts"],"sourcesContent":["import type { CSSProperties } from 'react';\n\nimport { isCssProperty, toCssKey } from '@contentful/experiences-design';\n\nexport interface ToCssOptions {\n  /** Keys to skip, matched against the original record key. */\n  exclude?: string[];\n  /** When set, only these keys pass through (still whitelist-filtered). */\n  include?: string[];\n}\n\n/**\n * Convert a design record into a `CSSProperties` object, keeping only keys\n * that normalize to a known CSS property. Non-CSS keys (`variant`, `as`, …)\n * are dropped; read those off the `useDesignValues()` record directly.\n *\n *   toCss({ fontSize: '20px', variant: 'h1' }) //=> { fontSize: '20px' }\n */\nexport function toCss(design: object, { include, exclude }: ToCssOptions = {}): CSSProperties {\n  const out: Record<string, unknown> = {};\n  for (const [key, value] of Object.entries(design)) {\n    if (include && !include.includes(key)) continue;\n    if (exclude?.includes(key)) continue;\n    if (value === undefined || value === null) continue;\n    const cssKey = toCssKey(key);\n    if (!isCssProperty(cssKey)) continue;\n    out[cssKey] = value;\n  }\n  return out as CSSProperties;\n}\n"],"mappings":"AAEA,SAAS,eAAe,gBAAgB;AAgBjC,SAAS,MAAM,QAAgB,EAAE,SAAS,QAAQ,IAAkB,CAAC,GAAkB;AAC5F,QAAM,MAA+B,CAAC;AACtC,aAAW,CAAC,KAAK,KAAK,KAAK,OAAO,QAAQ,MAAM,GAAG;AACjD,QAAI,WAAW,CAAC,QAAQ,SAAS,GAAG,EAAG;AACvC,QAAI,SAAS,SAAS,GAAG,EAAG;AAC5B,QAAI,UAAU,UAAa,UAAU,KAAM;AAC3C,UAAM,SAAS,SAAS,GAAG;AAC3B,QAAI,CAAC,cAAc,MAAM,EAAG;AAC5B,QAAI,MAAM,IAAI;AAAA,EAChB;AACA,SAAO;AACT;","names":[]}

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+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 { UseActiveViewportResult, useActiveViewport } from './use-active-viewport.js';
+export { RenderUnknown } from './nodes-renderer.js';
+export { useContentfulComponent, useContentfulTemplate, useExperience } from './context.js';
+export { useDesignValues } from './use-design-values.js';
+export { ToCssOptions, toCss } from './design-utils.js';
+export { ComponentConfig, Components, Config, ContentfulComponent, ContentfulTemplate, Registration, RenderContext, TemplateConfig, TemplateRegistration, Templates, defineComponent, defineTemplate, normalizeComponentRegistration, normalizeTemplateRegistration } from './types.js';
+export { ComponentTypeNode, ComponentTypeRef, DesignPropValue, DesignToken, ExperienceContext, ExperienceNode, ExperiencePayload, ExperienceSys, ManualDesignValue, PortableRegistration, PortableRenderNode, PortableRenderPlan, PortableTemplate, ResolveContext, ResolveExperienceOptions, ResolveToken, ResolverConfig, TemplateNode, TemplateRef, ValuesByViewport, ViewportDef, resolveExperience } from '@contentful/experiences-core';
+export { CSS_PROPERTIES, getValueForViewport, getViewportIndex, isCssProperty, resolveDesignProperties, toCssKey, toCssMediaQuery } from '@contentful/experiences-design';
+export { ClientOptions, ContentfulViewDelivery, ContentfulViewDeliveryClient, CreateClientOptions, ExperienceOptions, NotFoundError, ResolveOptions, createClient, fetchExperience } from '@contentful/experiences-client';
+import 'react';

package/dist/index.js

@@ -0,0 +1,63 @@
+import {
+  ClientExperienceRenderer,
+  ClientExperienceRenderer as ClientExperienceRenderer2
+} from "./client-renderer";
+import { ServerExperienceRenderer } from "./server-renderer";
+import { MissingComponent } from "./missing-component";
+import { useActiveViewport } from "./use-active-viewport";
+import { useExperience, useContentfulComponent, useContentfulTemplate } from "./context";
+import { useDesignValues } from "./use-design-values";
+import { toCss } from "./design-utils";
+import {
+  defineComponent,
+  defineTemplate,
+  normalizeComponentRegistration,
+  normalizeTemplateRegistration
+} from "./types";
+import { resolveExperience } from "@contentful/experiences-core";
+import {
+  CSS_PROPERTIES,
+  getValueForViewport,
+  getViewportIndex,
+  isCssProperty,
+  resolveDesignProperties,
+  toCssKey,
+  toCssMediaQuery
+} from "@contentful/experiences-design";
+import {
+  ContentfulViewDelivery,
+  ContentfulViewDeliveryClient,
+  NotFoundError,
+  createClient,
+  fetchExperience
+} from "@contentful/experiences-client";
+export {
+  CSS_PROPERTIES,
+  ClientExperienceRenderer2 as ClientExperienceRenderer,
+  ContentfulViewDelivery,
+  ContentfulViewDeliveryClient,
+  ClientExperienceRenderer as ExperienceRenderer,
+  MissingComponent,
+  NotFoundError,
+  ServerExperienceRenderer,
+  createClient,
+  defineComponent,
+  defineTemplate,
+  fetchExperience,
+  getValueForViewport,
+  getViewportIndex,
+  isCssProperty,
+  normalizeComponentRegistration,
+  normalizeTemplateRegistration,
+  resolveDesignProperties,
+  resolveExperience,
+  toCss,
+  toCssKey,
+  toCssMediaQuery,
+  useActiveViewport,
+  useContentfulComponent,
+  useContentfulTemplate,
+  useDesignValues,
+  useExperience
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +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-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 { 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, useContentfulTemplate } 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  defineTemplate,\n  normalizeComponentRegistration,\n  normalizeTemplateRegistration,\n} from './types';\nexport type {\n  ComponentConfig,\n  Components,\n  Config,\n  ContentfulComponent,\n  ContentfulTemplate,\n  Registration,\n  RenderContext,\n  ResolveToken,\n  TemplateConfig,\n  TemplateRegistration,\n  Templates,\n} from './types';\n\n// ─── Resolver (re-exported from render-core) ──────────────────────────────\nexport { resolveExperience } from '@contentful/experiences-core';\nexport type { ResolverConfig, ResolveExperienceOptions } from '@contentful/experiences-core';\n\n// ─── Core IR + payload types (re-exported from render-core) ───────────────\nexport type {\n  ComponentTypeNode,\n  ComponentTypeRef,\n  DesignPropValue,\n  DesignToken,\n  ExperienceContext,\n  ExperienceNode,\n  ExperiencePayload,\n  ExperienceSys,\n  ManualDesignValue,\n  PortableRegistration,\n  PortableRenderNode,\n  PortableRenderPlan,\n  PortableTemplate,\n  ResolveContext,\n  TemplateNode,\n  TemplateRef,\n  ValuesByViewport,\n  ViewportDef,\n} from '@contentful/experiences-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  NotFoundError,\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,yBAAyB;AAMlC,SAAS,eAAe,wBAAwB,6BAA6B;AAC7E,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,OACK;","names":["ClientExperienceRenderer"]}

package/dist/missing-component.d.ts

@@ -0,0 +1,10 @@
+import { ReactNode } from 'react';
+
+interface MissingComponentProps {
+    componentTypeId: string;
+    /** Optional — only present when the payload supplied an id for this node. */
+    nodeId?: string;
+}
+declare function MissingComponent({ componentTypeId, nodeId }: MissingComponentProps): ReactNode;
+
+export { MissingComponent, type MissingComponentProps };

package/dist/missing-component.js

@@ -0,0 +1,36 @@
+import { jsx, jsxs } from "react/jsx-runtime";
+import { useExperience } from "./context";
+function MissingComponent({ componentTypeId, nodeId }) {
+  const { isPreview } = useExperience();
+  if (typeof console !== "undefined") {
+    const idLabel = nodeId ? ` (nodeId: ${nodeId})` : "";
+    console.warn(
+      `[@contentful/experiences] No component registered for type "${componentTypeId}"${idLabel}.`
+    );
+  }
+  if (!isPreview) return null;
+  return /* @__PURE__ */ jsxs(
+    "div",
+    {
+      style: {
+        border: "2px solid red",
+        padding: "1rem",
+        color: "red",
+        background: "#fff"
+      },
+      "data-experiences-missing": componentTypeId,
+      children: [
+        /* @__PURE__ */ jsxs("strong", { children: [
+          "Missing component \u2018",
+          componentTypeId,
+          "\u2019"
+        ] }),
+        /* @__PURE__ */ jsx("p", { children: "This component is referenced by the Experience payload but is not registered in the Config." })
+      ]
+    }
+  );
+}
+export {
+  MissingComponent
+};
+//# sourceMappingURL=missing-component.js.map

package/dist/missing-component.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/missing-component.tsx"],"sourcesContent":["/*\n * Default fallback rendered when an instance references a component type\n * not present in the Config.\n *\n * Behavior: a visible red error box in preview, silent null in production.\n * Customers can override per-render via <ExperienceRenderer renderUnknown=...>.\n */\n\nimport type { ReactNode } from 'react';\n\nimport { useExperience } from './context';\n\nexport interface MissingComponentProps {\n  componentTypeId: string;\n  /** Optional — only present when the payload supplied an id for this node. */\n  nodeId?: string;\n}\n\nexport function MissingComponent({ componentTypeId, nodeId }: MissingComponentProps): ReactNode {\n  const { isPreview } = useExperience();\n  if (typeof console !== 'undefined') {\n    const idLabel = nodeId ? ` (nodeId: ${nodeId})` : '';\n    console.warn(\n      `[@contentful/experiences] No component registered for type \"${componentTypeId}\"${idLabel}.`\n    );\n  }\n  if (!isPreview) return null;\n  return (\n    <div\n      style={{\n        border: '2px solid red',\n        padding: '1rem',\n        color: 'red',\n        background: '#fff',\n      }}\n      data-experiences-missing={componentTypeId}\n    >\n      <strong>Missing component &lsquo;{componentTypeId}&rsquo;</strong>\n      <p>\n        This component is referenced by the Experience payload but is not registered in the Config.\n      </p>\n    </div>\n  );\n}\n"],"mappings":"AAqCM,SACA,KADA;AA3BN,SAAS,qBAAqB;AAQvB,SAAS,iBAAiB,EAAE,iBAAiB,OAAO,GAAqC;AAC9F,QAAM,EAAE,UAAU,IAAI,cAAc;AACpC,MAAI,OAAO,YAAY,aAAa;AAClC,UAAM,UAAU,SAAS,aAAa,MAAM,MAAM;AAClD,YAAQ;AAAA,MACN,+DAA+D,eAAe,IAAI,OAAO;AAAA,IAC3F;AAAA,EACF;AACA,MAAI,CAAC,UAAW,QAAO;AACvB,SACE;AAAA,IAAC;AAAA;AAAA,MACC,OAAO;AAAA,QACL,QAAQ;AAAA,QACR,SAAS;AAAA,QACT,OAAO;AAAA,QACP,YAAY;AAAA,MACd;AAAA,MACA,4BAA0B;AAAA,MAE1B;AAAA,6BAAC,YAAO;AAAA;AAAA,UAA0B;AAAA,UAAgB;AAAA,WAAO;AAAA,QACzD,oBAAC,OAAE,yGAEH;AAAA;AAAA;AAAA,EACF;AAEJ;","names":[]}

package/dist/nodes-renderer.d.ts

@@ -0,0 +1,28 @@
+import { ReactNode } from 'react';
+import { PortableRenderNode, ViewportDef, PortableTemplate } from '@contentful/experiences-core';
+import { MissingComponentProps } from './missing-component.js';
+import { Config } from './types.js';
+
+type RenderUnknown = (props: MissingComponentProps) => ReactNode;
+interface NodesRendererProps {
+    nodes: PortableRenderNode[];
+    config: Config;
+    viewports: ViewportDef[];
+    activeViewportIndex: number;
+    renderUnknown: RenderUnknown;
+}
+declare function NodesRenderer({ nodes, config, viewports, activeViewportIndex, renderUnknown, }: NodesRendererProps): ReactNode;
+interface WrapWithTemplateProps {
+    template: PortableTemplate | undefined;
+    config: Config;
+    viewports: ViewportDef[];
+    activeViewportIndex: number;
+    children: ReactNode;
+}
+/**
+ * Wraps the rendered nodes with the page-level template. If the template is
+ * referenced but unregistered, warns once and renders children unwrapped.
+ */
+declare function WrapWithTemplate({ template, config, viewports, activeViewportIndex, children, }: WrapWithTemplateProps): ReactNode;
+
+export { NodesRenderer, type NodesRendererProps, type RenderUnknown, WrapWithTemplate, type WrapWithTemplateProps };

package/dist/nodes-renderer.js

@@ -0,0 +1,134 @@
+import { jsx } from "react/jsx-runtime";
+import { Fragment, createElement } from "react";
+import { applyTokenResolver, resolveDesignProperties } from "@contentful/experiences-design";
+import {
+  ContentfulComponentProvider,
+  ContentfulTemplateProvider,
+  ResolvedDesignProvider
+} from "./context";
+import {
+  normalizeComponentRegistration,
+  normalizeTemplateRegistration
+} from "./types";
+function NodesRenderer({
+  nodes,
+  config,
+  viewports,
+  activeViewportIndex,
+  renderUnknown
+}) {
+  if (!nodes.length) return null;
+  return /* @__PURE__ */ jsx(Fragment, { children: nodes.map((node, index) => /* @__PURE__ */ jsx(
+    NodeRenderer,
+    {
+      node,
+      config,
+      viewports,
+      activeViewportIndex,
+      renderUnknown
+    },
+    node.nodeId ?? index
+  )) });
+}
+function NodeRenderer({
+  node,
+  config,
+  viewports,
+  activeViewportIndex,
+  renderUnknown
+}) {
+  const { componentTypeId } = node.registration;
+  const entry = config.components[componentTypeId];
+  if (!entry) {
+    return renderUnknown({ componentTypeId, nodeId: node.nodeId });
+  }
+  const componentConfig = normalizeComponentRegistration(entry);
+  const slotProps = {};
+  for (const [slotName, children] of Object.entries(node.slots)) {
+    slotProps[slotName] = /* @__PURE__ */ jsx(
+      NodesRenderer,
+      {
+        nodes: children,
+        config,
+        viewports,
+        activeViewportIndex,
+        renderUnknown
+      }
+    );
+  }
+  const resolvedDesign = resolveDesignProperties(node.props.design, viewports, activeViewportIndex);
+  const { props: tokenResolvedDesign, unresolved } = applyTokenResolver(
+    resolvedDesign,
+    config.resolveToken
+  );
+  if (unresolved.length && typeof console !== "undefined") {
+    console.warn(
+      `[@contentful/experiences-react] resolveToken returned undefined for token id(s) on "${componentTypeId}": ${unresolved.join(", ")}. useDesignValues() will omit those keys.`
+    );
+  }
+  const contentful = {
+    componentTypeId,
+    nodeId: node.nodeId,
+    content: node.props.content,
+    design: node.props.design,
+    resolved: node.props.resolved
+  };
+  const composed = {
+    ...componentConfig.defaults,
+    ...node.props.content,
+    ...node.props.resolved,
+    ...slotProps
+  };
+  return /* @__PURE__ */ jsx(ContentfulComponentProvider, { value: contentful, children: /* @__PURE__ */ jsx(ResolvedDesignProvider, { value: tokenResolvedDesign, children: createElement(componentConfig.component, composed) }) });
+}
+function WrapWithTemplate({
+  template,
+  config,
+  viewports,
+  activeViewportIndex,
+  children
+}) {
+  if (!template) return /* @__PURE__ */ jsx(Fragment, { children });
+  const entry = config.templates?.[template.templateId];
+  if (!entry) {
+    if (typeof console !== "undefined") {
+      console.warn(
+        `[@contentful/experiences-react] No template registered for id "${template.templateId}". Rendering nodes without the template wrapper.`
+      );
+    }
+    return /* @__PURE__ */ jsx(Fragment, { children });
+  }
+  const templateConfig = normalizeTemplateRegistration(entry);
+  const resolvedDesign = resolveDesignProperties(
+    template.props.design,
+    viewports,
+    activeViewportIndex
+  );
+  const { props: tokenResolvedDesign, unresolved } = applyTokenResolver(
+    resolvedDesign,
+    config.resolveToken
+  );
+  if (unresolved.length && typeof console !== "undefined") {
+    console.warn(
+      `[@contentful/experiences-react] resolveToken returned undefined for token id(s) on template "${template.templateId}": ${unresolved.join(", ")}. useDesignValues() will omit those keys.`
+    );
+  }
+  const contentful = {
+    templateId: template.templateId,
+    content: template.props.content,
+    design: template.props.design,
+    resolved: template.props.resolved
+  };
+  const composed = {
+    ...templateConfig.defaults,
+    ...template.props.content,
+    ...template.props.resolved,
+    children
+  };
+  return /* @__PURE__ */ jsx(ContentfulTemplateProvider, { value: contentful, children: /* @__PURE__ */ jsx(ResolvedDesignProvider, { value: tokenResolvedDesign, children: createElement(templateConfig.component, composed) }) });
+}
+export {
+  NodesRenderer,
+  WrapWithTemplate
+};
+//# sourceMappingURL=nodes-renderer.js.map

package/dist/nodes-renderer.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/nodes-renderer.tsx"],"sourcesContent":["/*\n * Recursive renderer over PortableRenderNodes. Customer components receive the\n * merged prop bag (defaults + content + resolveData + slots); design values\n * are read via `useDesignValues()`, not injected as props.\n */\n\nimport { Fragment, createElement, type ReactNode } from 'react';\n\nimport type {\n  PortableRenderNode,\n  PortableTemplate,\n  ViewportDef,\n} from '@contentful/experiences-core';\nimport { applyTokenResolver, resolveDesignProperties } from '@contentful/experiences-design';\n\nimport {\n  ContentfulComponentProvider,\n  ContentfulTemplateProvider,\n  ResolvedDesignProvider,\n} from './context';\nimport type { MissingComponentProps } from './missing-component';\nimport {\n  normalizeComponentRegistration,\n  normalizeTemplateRegistration,\n  type ContentfulComponent,\n  type ContentfulTemplate,\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  renderUnknown: RenderUnknown;\n}\n\nexport function NodesRenderer({\n  nodes,\n  config,\n  viewports,\n  activeViewportIndex,\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          renderUnknown={renderUnknown}\n        />\n      ))}\n    </Fragment>\n  );\n}\n\ninterface NodeRendererProps {\n  node: PortableRenderNode;\n  config: Config;\n  viewports: ViewportDef[];\n  activeViewportIndex: number;\n  renderUnknown: RenderUnknown;\n}\n\nfunction NodeRenderer({\n  node,\n  config,\n  viewports,\n  activeViewportIndex,\n  renderUnknown,\n}: NodeRendererProps): ReactNode {\n  const { componentTypeId } = node.registration;\n  const entry = config.components[componentTypeId];\n  if (!entry) {\n    return renderUnknown({ componentTypeId, nodeId: node.nodeId });\n  }\n  const componentConfig = normalizeComponentRegistration(entry);\n\n  // Pre-render slot subtrees so components receive ReactNodes by slot name.\n  const slotProps: Record<string, ReactNode> = {};\n  for (const [slotName, children] of Object.entries(node.slots)) {\n    slotProps[slotName] = (\n      <NodesRenderer\n        nodes={children}\n        config={config}\n        viewports={viewports}\n        activeViewportIndex={activeViewportIndex}\n        renderUnknown={renderUnknown}\n      />\n    );\n  }\n\n  // Cascade design to the active viewport, then resolve DesignToken envelopes.\n  // Published on context for useDesignValues() — never spread onto props.\n  const resolvedDesign = resolveDesignProperties(node.props.design, viewports, activeViewportIndex);\n  const { props: tokenResolvedDesign, unresolved } = applyTokenResolver(\n    resolvedDesign,\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 \"${componentTypeId}\": ${unresolved.join(', ')}. useDesignValues() will omit those keys.`\n    );\n  }\n\n  const contentful: ContentfulComponent = {\n    componentTypeId,\n    nodeId: node.nodeId,\n    content: node.props.content,\n    design: node.props.design,\n    resolved: node.props.resolved,\n  };\n\n  // Merge precedence (last wins): defaults < content < resolveData < slots.\n  const composed = {\n    ...componentConfig.defaults,\n    ...node.props.content,\n    ...node.props.resolved,\n    ...slotProps,\n  };\n\n  return (\n    <ContentfulComponentProvider value={contentful}>\n      <ResolvedDesignProvider value={tokenResolvedDesign}>\n        {createElement(componentConfig.component, composed)}\n      </ResolvedDesignProvider>\n    </ContentfulComponentProvider>\n  );\n}\n\nexport interface WrapWithTemplateProps {\n  template: PortableTemplate | undefined;\n  config: Config;\n  viewports: ViewportDef[];\n  activeViewportIndex: number;\n  children: ReactNode;\n}\n\n/**\n * Wraps the rendered nodes with the page-level template. If the template is\n * referenced but unregistered, warns once and renders children unwrapped.\n */\nexport function WrapWithTemplate({\n  template,\n  config,\n  viewports,\n  activeViewportIndex,\n  children,\n}: WrapWithTemplateProps): ReactNode {\n  if (!template) return <Fragment>{children}</Fragment>;\n  const entry = config.templates?.[template.templateId];\n  if (!entry) {\n    if (typeof console !== 'undefined') {\n      console.warn(\n        `[@contentful/experiences-react] No template registered for id \"${template.templateId}\". Rendering nodes without the template wrapper.`\n      );\n    }\n    return <Fragment>{children}</Fragment>;\n  }\n  const templateConfig = normalizeTemplateRegistration(entry);\n\n  const resolvedDesign = resolveDesignProperties(\n    template.props.design,\n    viewports,\n    activeViewportIndex\n  );\n\n  const { props: tokenResolvedDesign, unresolved } = applyTokenResolver(\n    resolvedDesign,\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 template \"${template.templateId}\": ${unresolved.join(', ')}. useDesignValues() will omit those keys.`\n    );\n  }\n\n  const contentful: ContentfulTemplate = {\n    templateId: template.templateId,\n    content: template.props.content,\n    design: template.props.design,\n    resolved: template.props.resolved,\n  };\n\n  const composed = {\n    ...templateConfig.defaults,\n    ...template.props.content,\n    ...template.props.resolved,\n    children,\n  };\n\n  return (\n    <ContentfulTemplateProvider value={contentful}>\n      <ResolvedDesignProvider value={tokenResolvedDesign}>\n        {createElement(templateConfig.component, composed)}\n      </ResolvedDesignProvider>\n    </ContentfulTemplateProvider>\n  );\n}\n"],"mappings":"AAsDQ;AAhDR,SAAS,UAAU,qBAAqC;AAOxD,SAAS,oBAAoB,+BAA+B;AAE5D;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,OACK;AAEP;AAAA,EACE;AAAA,EACA;AAAA,OAIK;AAgBA,SAAS,cAAc;AAAA,EAC5B;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;AAAA,IALK,KAAK,UAAU;AAAA,EAMtB,CACD,GACH;AAEJ;AAUA,SAAS,aAAa;AAAA,EACpB;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF,GAAiC;AAC/B,QAAM,EAAE,gBAAgB,IAAI,KAAK;AACjC,QAAM,QAAQ,OAAO,WAAW,eAAe;AAC/C,MAAI,CAAC,OAAO;AACV,WAAO,cAAc,EAAE,iBAAiB,QAAQ,KAAK,OAAO,CAAC;AAAA,EAC/D;AACA,QAAM,kBAAkB,+BAA+B,KAAK;AAG5D,QAAM,YAAuC,CAAC;AAC9C,aAAW,CAAC,UAAU,QAAQ,KAAK,OAAO,QAAQ,KAAK,KAAK,GAAG;AAC7D,cAAU,QAAQ,IAChB;AAAA,MAAC;AAAA;AAAA,QACC,OAAO;AAAA,QACP;AAAA,QACA;AAAA,QACA;AAAA,QACA;AAAA;AAAA,IACF;AAAA,EAEJ;AAIA,QAAM,iBAAiB,wBAAwB,KAAK,MAAM,QAAQ,WAAW,mBAAmB;AAChG,QAAM,EAAE,OAAO,qBAAqB,WAAW,IAAI;AAAA,IACjD;AAAA,IACA,OAAO;AAAA,EACT;AACA,MAAI,WAAW,UAAU,OAAO,YAAY,aAAa;AACvD,YAAQ;AAAA,MACN,uFAAuF,eAAe,MAAM,WAAW,KAAK,IAAI,CAAC;AAAA,IACnI;AAAA,EACF;AAEA,QAAM,aAAkC;AAAA,IACtC;AAAA,IACA,QAAQ,KAAK;AAAA,IACb,SAAS,KAAK,MAAM;AAAA,IACpB,QAAQ,KAAK,MAAM;AAAA,IACnB,UAAU,KAAK,MAAM;AAAA,EACvB;AAGA,QAAM,WAAW;AAAA,IACf,GAAG,gBAAgB;AAAA,IACnB,GAAG,KAAK,MAAM;AAAA,IACd,GAAG,KAAK,MAAM;AAAA,IACd,GAAG;AAAA,EACL;AAEA,SACE,oBAAC,+BAA4B,OAAO,YAClC,8BAAC,0BAAuB,OAAO,qBAC5B,wBAAc,gBAAgB,WAAW,QAAQ,GACpD,GACF;AAEJ;AAcO,SAAS,iBAAiB;AAAA,EAC/B;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF,GAAqC;AACnC,MAAI,CAAC,SAAU,QAAO,oBAAC,YAAU,UAAS;AAC1C,QAAM,QAAQ,OAAO,YAAY,SAAS,UAAU;AACpD,MAAI,CAAC,OAAO;AACV,QAAI,OAAO,YAAY,aAAa;AAClC,cAAQ;AAAA,QACN,kEAAkE,SAAS,UAAU;AAAA,MACvF;AAAA,IACF;AACA,WAAO,oBAAC,YAAU,UAAS;AAAA,EAC7B;AACA,QAAM,iBAAiB,8BAA8B,KAAK;AAE1D,QAAM,iBAAiB;AAAA,IACrB,SAAS,MAAM;AAAA,IACf;AAAA,IACA;AAAA,EACF;AAEA,QAAM,EAAE,OAAO,qBAAqB,WAAW,IAAI;AAAA,IACjD;AAAA,IACA,OAAO;AAAA,EACT;AACA,MAAI,WAAW,UAAU,OAAO,YAAY,aAAa;AACvD,YAAQ;AAAA,MACN,gGAAgG,SAAS,UAAU,MAAM,WAAW,KAAK,IAAI,CAAC;AAAA,IAChJ;AAAA,EACF;AAEA,QAAM,aAAiC;AAAA,IACrC,YAAY,SAAS;AAAA,IACrB,SAAS,SAAS,MAAM;AAAA,IACxB,QAAQ,SAAS,MAAM;AAAA,IACvB,UAAU,SAAS,MAAM;AAAA,EAC3B;AAEA,QAAM,WAAW;AAAA,IACf,GAAG,eAAe;AAAA,IAClB,GAAG,SAAS,MAAM;AAAA,IAClB,GAAG,SAAS,MAAM;AAAA,IAClB;AAAA,EACF;AAEA,SACE,oBAAC,8BAA2B,OAAO,YACjC,8BAAC,0BAAuB,OAAO,qBAC5B,wBAAc,eAAe,WAAW,QAAQ,GACnD,GACF;AAEJ;","names":[]}

package/dist/server-renderer.d.ts

@@ -0,0 +1,19 @@
+import { ReactNode } from 'react';
+import { PortableRenderPlan, ExperienceContext } from '@contentful/experiences-core';
+import { RenderUnknown } from './nodes-renderer.js';
+import { Config } from './types.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;
+    /** Per-render context shallow-merged onto defaults. */
+    context?: Partial<ExperienceContext>;
+    /** Override the fallback rendered for unregistered component types. */
+    renderUnknown?: RenderUnknown;
+}
+declare function ServerExperienceRenderer({ experience, config, initialViewportId, context, renderUnknown, }: ServerExperienceRendererProps): ReactNode;
+
+export { ServerExperienceRenderer, type ServerExperienceRendererProps };

package/dist/server-renderer.js

@@ -0,0 +1,59 @@
+import { jsx } from "react/jsx-runtime";
+import { getViewportIndex } from "@contentful/experiences-design";
+import { ExperienceProvider } from "./context";
+import { MissingComponent } from "./missing-component";
+import { NodesRenderer, WrapWithTemplate } from "./nodes-renderer";
+const DEFAULT_CONTEXT = {
+  isPreview: false,
+  metadata: {},
+  viewports: []
+};
+const FALLBACK_VIEWPORT = {
+  id: "_",
+  query: "*",
+  displayName: "Default",
+  previewSize: "100%"
+};
+function ServerExperienceRenderer({
+  experience,
+  config,
+  initialViewportId,
+  context,
+  renderUnknown = MissingComponent
+}) {
+  if (!experience) return null;
+  const activeViewportIndex = getViewportIndex(experience.viewports, initialViewportId);
+  const contextViewports = experience.viewports.map((v) => ({ ...v }));
+  const activeViewport = { ...experience.viewports[activeViewportIndex] ?? FALLBACK_VIEWPORT };
+  const renderContext = {
+    ...DEFAULT_CONTEXT,
+    ...context,
+    metadata: { ...DEFAULT_CONTEXT.metadata, ...context?.metadata ?? {} },
+    viewports: contextViewports,
+    activeViewport,
+    activeViewportIndex
+  };
+  return /* @__PURE__ */ jsx(ExperienceProvider, { value: renderContext, children: /* @__PURE__ */ jsx(
+    WrapWithTemplate,
+    {
+      template: experience.template,
+      config,
+      viewports: experience.viewports,
+      activeViewportIndex,
+      children: /* @__PURE__ */ jsx(
+        NodesRenderer,
+        {
+          nodes: experience.nodes,
+          config,
+          viewports: experience.viewports,
+          activeViewportIndex,
+          renderUnknown
+        }
+      )
+    }
+  ) });
+}
+export {
+  ServerExperienceRenderer
+};
+//# sourceMappingURL=server-renderer.js.map

package/dist/server-renderer.js.map

@@ -0,0 +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-core';\nimport { getViewportIndex } from '@contentful/experiences-design';\n\nimport { ExperienceProvider } from './context';\nimport { MissingComponent } from './missing-component';\nimport { NodesRenderer, WrapWithTemplate, type RenderUnknown } from './nodes-renderer';\nimport type { Config, RenderContext } from './types';\n\nconst DEFAULT_CONTEXT: ExperienceContext = {\n  isPreview: 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  /** Per-render context shallow-merged onto defaults. */\n  context?: Partial<ExperienceContext>;\n  /** Override the fallback rendered for unregistered component types. */\n  renderUnknown?: RenderUnknown;\n}\n\nexport function ServerExperienceRenderer({\n  experience,\n  config,\n  initialViewportId,\n  context,\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    ...context,\n    metadata: { ...DEFAULT_CONTEXT.metadata, ...(context?.metadata ?? {}) },\n    viewports: contextViewports,\n    activeViewport,\n    activeViewportIndex,\n  };\n\n  return (\n    <ExperienceProvider value={renderContext}>\n      <WrapWithTemplate\n        template={experience.template}\n        config={config}\n        viewports={experience.viewports}\n        activeViewportIndex={activeViewportIndex}\n      >\n        <NodesRenderer\n          nodes={experience.nodes}\n          config={config}\n          viewports={experience.viewports}\n          activeViewportIndex={activeViewportIndex}\n          renderUnknown={renderUnknown}\n        />\n      </WrapWithTemplate>\n    </ExperienceProvider>\n  );\n}\n"],"mappings":"AA8EQ;AAlER,SAAS,wBAAwB;AAEjC,SAAS,0BAA0B;AACnC,SAAS,wBAAwB;AACjC,SAAS,eAAe,wBAA4C;AAGpE,MAAM,kBAAqC;AAAA,EACzC,WAAW;AAAA,EACX,UAAU,CAAC;AAAA,EACX,WAAW,CAAC;AACd;AAGA,MAAM,oBAAiC;AAAA,EACrC,IAAI;AAAA,EACJ,OAAO;AAAA,EACP,aAAa;AAAA,EACb,aAAa;AACf;AAaO,SAAS,yBAAyB;AAAA,EACvC;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA,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,GAAG;AAAA,IACH,UAAU,EAAE,GAAG,gBAAgB,UAAU,GAAI,SAAS,YAAY,CAAC,EAAG;AAAA,IACtE,WAAW;AAAA,IACX;AAAA,IACA;AAAA,EACF;AAEA,SACE,oBAAC,sBAAmB,OAAO,eACzB;AAAA,IAAC;AAAA;AAAA,MACC,UAAU,WAAW;AAAA,MACrB;AAAA,MACA,WAAW,WAAW;AAAA,MACtB;AAAA,MAEA;AAAA,QAAC;AAAA;AAAA,UACC,OAAO,WAAW;AAAA,UAClB;AAAA,UACA,WAAW,WAAW;AAAA,UACtB;AAAA,UACA;AAAA;AAAA,MACF;AAAA;AAAA,EACF,GACF;AAEJ;","names":[]}

package/dist/types.d.ts

@@ -0,0 +1,135 @@
+import { ComponentType, ReactNode } from 'react';
+import { ResolveContext, ResolveToken, DesignPropValue, ExperienceContext, ViewportDef } from '@contentful/experiences-core';
+export { ResolveContext, ResolveToken } from '@contentful/experiences-core';
+
+/**
+ * The full Contentful-side payload for a single component instance, exposed
+ * via `useContentfulComponent()` to any descendant of a rendered Experience
+ * node. Useful for custom design-property resolution outside the SDK's
+ * cascade, branching by `componentTypeId` in a generic wrapper, keying
+ * analytics on `nodeId`, or rendering a raw-payload panel in preview.
+ *
+ * Design properties stay in their **raw envelope form** here (the same shape
+ * `ctx.design` carries inside `resolveData`). The viewport-cascaded, token-
+ * resolved values are what `useDesignValues()` returns.
+ */
+interface ContentfulComponent {
+    componentTypeId: string;
+    nodeId?: string;
+    content: Record<string, unknown>;
+    design: Record<string, DesignPropValue>;
+    resolved?: Record<string, unknown>;
+}
+/**
+ * Same shape as `ContentfulComponent`, but for the page-level template.
+ * Exposed via `useContentfulTemplate()` inside a template's component tree.
+ */
+interface ContentfulTemplate {
+    templateId: string;
+    content: Record<string, unknown>;
+    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 type. The `component`
+ * receives the merged prop bag (content + resolveData + slots). Design values
+ * are not injected — a component reads them via `useDesignValues()`. Runtime
+ * context and raw payload come from `useExperience()` / `useContentfulComponent()`.
+ */
+interface ComponentConfig<Props extends object = Record<string, unknown>> {
+    /**
+     * Lowest-precedence prop bag. Merged in before content / resolveData /
+     * slots. Useful for variant fallbacks the editorial layer doesn't always supply.
+     */
+    defaults?: Partial<Props>;
+    /**
+     * Optional sync-or-async hook that derives final props from the raw
+     * Experience inputs. Runs once during `resolveExperience`, before render —
+     * does NOT re-fire on viewport changes.
+     */
+    resolveData?: (ctx: ResolveContext) => Partial<Props> | Promise<Partial<Props>>;
+    /**
+     * The React component to render. Receives the merged prop bag as its props.
+     */
+    component: ComponentType<Props>;
+}
+/**
+ * Registry value. Register a bare React component for the common case, or
+ * the full `ComponentConfig` shape when you need defaults or a `resolveData`
+ * hook.
+ *
+ *   button: Button,                                  // bare
+ *   header: { component: Header, defaults: {...} }, // with defaults
+ *   card:   defineComponent<CardProps>({ component: Card, resolveData: ... }),
+ */
+type Registration<Props extends object = Record<string, unknown>> = ComponentType<Props> | ComponentConfig<Props>;
+/**
+ * Customer-supplied configuration for a page-level template. The template's
+ * component receives the rendered Experience nodes as `children`.
+ */
+interface TemplateConfig<Props extends object = Record<string, unknown>> {
+    defaults?: Partial<Props>;
+    resolveData?: (ctx: ResolveContext) => Partial<Props> | Promise<Partial<Props>>;
+    component: ComponentType<Props & {
+        children?: ReactNode;
+    }>;
+}
+/**
+ * Registry value for templates. Same dual-shape as component registrations.
+ */
+type TemplateRegistration<Props extends object = Record<string, unknown>> = ComponentType<Props & {
+    children?: ReactNode;
+}> | TemplateConfig<Props>;
+/**
+ * Identity helper — returns the config as-is, but narrows the `resolveData`
+ * and `component` parameter types to your declared `Props`.
+ */
+declare function defineComponent<Props extends object = Record<string, unknown>>(config: ComponentConfig<Props>): ComponentConfig<Props>;
+/**
+ * Identity helper — returns the template config as-is, with `Props` narrowing.
+ */
+declare function defineTemplate<Props extends object = Record<string, unknown>>(config: TemplateConfig<Props>): TemplateConfig<Props>;
+/**
+ * Component registry — keyed by `componentTypeId` (last slash-segment of
+ * `componentType.sys.urn`). Per-entry prop narrowing happens at
+ * `defineComponent<Props>` or at the bare-component's own type.
+ */
+type Components = Record<string, Registration<any>>;
+/**
+ * Template registry — keyed by `templateId` (last slash-segment of
+ * `payload.sys.template.sys.urn`).
+ */
+type Templates = Record<string, TemplateRegistration<any>>;
+interface Config {
+    components: Components;
+    templates?: Templates;
+    /**
+     * Resolves `DesignToken` envelopes to runtime values before they reach a
+     * component. If omitted, envelopes pass through unchanged. See `ResolveToken`
+     * in `@contentful/experiences-core` for the full contract.
+     */
+    resolveToken?: ResolveToken;
+}
+/**
+ * Normalize a registry entry — bare component OR config object — into the
+ * common `ComponentConfig` shape used by the renderer.
+ *
+ * React function components are plain functions; `React.memo` /
+ * `React.forwardRef` yield objects carrying a `$$typeof` symbol. Both count
+ * as bare components; a config object is discriminated by having a
+ * `component` field and no `$$typeof`.
+ */
+declare function normalizeComponentRegistration<P extends object>(reg: Registration<P>): ComponentConfig<P>;
+declare function normalizeTemplateRegistration<P extends object>(reg: TemplateRegistration<P>): TemplateConfig<P>;
+
+export { type ComponentConfig, type Components, type Config, type ContentfulComponent, type ContentfulTemplate, type Registration, type RenderContext, type TemplateConfig, type TemplateRegistration, type Templates, defineComponent, defineTemplate, normalizeComponentRegistration, normalizeTemplateRegistration };

package/dist/types.js

@@ -0,0 +1,25 @@
+function defineComponent(config) {
+  return config;
+}
+function defineTemplate(config) {
+  return config;
+}
+function normalizeComponentRegistration(reg) {
+  if (typeof reg === "object" && reg !== null && !("$$typeof" in reg) && "component" in reg) {
+    return reg;
+  }
+  return { component: reg };
+}
+function normalizeTemplateRegistration(reg) {
+  if (typeof reg === "object" && reg !== null && !("$$typeof" in reg) && "component" in reg) {
+    return reg;
+  }
+  return { component: reg };
+}
+export {
+  defineComponent,
+  defineTemplate,
+  normalizeComponentRegistration,
+  normalizeTemplateRegistration
+};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/types.ts"],"sourcesContent":["import type { ComponentType, ReactNode } from 'react';\n\nimport type {\n  DesignPropValue,\n  ExperienceContext,\n  ResolveContext,\n  ResolveToken,\n  ViewportDef,\n} from '@contentful/experiences-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 `componentTypeId` 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 envelope form** here (the same shape\n * `ctx.design` carries inside `resolveData`). The viewport-cascaded, token-\n * resolved values are what `useDesignValues()` returns.\n */\nexport interface ContentfulComponent {\n  componentTypeId: 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 the page-level template.\n * Exposed via `useContentfulTemplate()` inside a template's component tree.\n */\nexport interface ContentfulTemplate {\n  templateId: 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 type. The `component`\n * receives the merged prop bag (content + resolveData + slots). Design values\n * are not injected — a component reads them via `useDesignValues()`. Runtime\n * context and raw payload come from `useExperience()` / `useContentfulComponent()`.\n */\nexport interface ComponentConfig<Props extends object = Record<string, unknown>> {\n  /**\n   * Lowest-precedence prop bag. 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 prop bag as its 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>\n  | ComponentConfig<Props>;\n\n/**\n * Customer-supplied configuration for a page-level template. The template's\n * component receives the rendered Experience nodes as `children`.\n */\nexport interface TemplateConfig<Props extends object = Record<string, unknown>> {\n  defaults?: Partial<Props>;\n  resolveData?: (ctx: ResolveContext) => Partial<Props> | Promise<Partial<Props>>;\n  component: ComponentType<Props & { children?: ReactNode }>;\n}\n\n/**\n * Registry value for templates. Same dual-shape as component registrations.\n */\nexport type TemplateRegistration<Props extends object = Record<string, unknown>> =\n  | ComponentType<Props & { children?: ReactNode }>\n  | TemplateConfig<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 template config as-is, with `Props` narrowing.\n */\nexport function defineTemplate<Props extends object = Record<string, unknown>>(\n  config: TemplateConfig<Props>\n): TemplateConfig<Props> {\n  return config;\n}\n\n/**\n * Component registry — keyed by `componentTypeId` (last slash-segment of\n * `componentType.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 * Template registry — keyed by `templateId` (last slash-segment of\n * `payload.sys.template.sys.urn`).\n */\n// eslint-disable-next-line @typescript-eslint/no-explicit-any -- per-entry narrowing happens at the registration author's call site.\nexport type Templates = Record<string, TemplateRegistration<any>>;\n\nexport interface Config {\n  components: Components;\n  templates?: Templates;\n  /**\n   * Resolves `DesignToken` envelopes to runtime values before they reach a\n   * component. If omitted, envelopes pass through unchanged. See `ResolveToken`\n   * in `@contentful/experiences-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 normalizeTemplateRegistration<P extends object>(\n  reg: TemplateRegistration<P>\n): TemplateConfig<P> {\n  if (typeof reg === 'object' && reg !== null && !('$$typeof' in reg) && 'component' in reg) {\n    return reg as TemplateConfig<P>;\n  }\n  return { component: reg as ComponentType<P & { children?: ReactNode }> };\n}\n"],"mappings":"AAmHO,SAAS,gBACd,QACwB;AACxB,SAAO;AACT;AAKO,SAAS,eACd,QACuB;AACvB,SAAO;AACT;AAqCO,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,8BACd,KACmB;AACnB,MAAI,OAAO,QAAQ,YAAY,QAAQ,QAAQ,EAAE,cAAc,QAAQ,eAAe,KAAK;AACzF,WAAO;AAAA,EACT;AACA,SAAO,EAAE,WAAW,IAAmD;AACzE;","names":[]}

package/dist/use-active-viewport.d.ts

@@ -0,0 +1,8 @@
+import { ViewportDef } from '@contentful/experiences-core';
+
+interface UseActiveViewportResult {
+    activeViewportIndex: number;
+}
+declare function useActiveViewport(viewports: ViewportDef[], initialViewportId?: string): UseActiveViewportResult;
+
+export { type UseActiveViewportResult, useActiveViewport };

package/dist/use-active-viewport.js

@@ -0,0 +1,61 @@
+"use client";
+import { useEffect, useState } from "react";
+import { getViewportIndex, toCssMediaQuery } from "@contentful/experiences-design";
+function createMediaQueryMatchers(viewports) {
+  const mediaQueryMatches = new Array(viewports.length).fill(false);
+  mediaQueryMatches[0] = true;
+  const mediaQueryMatchers = [];
+  if (typeof window === "undefined") {
+    return [mediaQueryMatchers, mediaQueryMatches];
+  }
+  for (let index = 0; index < viewports.length; index++) {
+    const viewport = viewports[index];
+    if (!viewport) continue;
+    const cssQuery = toCssMediaQuery(viewport);
+    if (!cssQuery) continue;
+    const matcher = window.matchMedia(cssQuery);
+    mediaQueryMatches[index] = matcher.matches;
+    mediaQueryMatchers.push({ index, signal: matcher });
+  }
+  return [mediaQueryMatchers, mediaQueryMatches];
+}
+function useMediaQueryMatchers(viewports) {
+  const [, initialMatches] = createMediaQueryMatchers(viewports);
+  const [matches, setMatches] = useState(initialMatches);
+  useEffect(() => {
+    const [matchers] = createMediaQueryMatchers(viewports);
+    const listeners = matchers.map(({ index, signal }) => {
+      const onChange = () => setMatches((prev) => {
+        const next = [...prev];
+        next[index] = signal.matches;
+        return next;
+      });
+      signal.addEventListener("change", onChange);
+      return onChange;
+    });
+    return () => {
+      listeners.forEach((listener, i) => {
+        const matcher = matchers[i];
+        if (matcher) matcher.signal.removeEventListener("change", listener);
+      });
+    };
+  }, [viewports]);
+  return matches;
+}
+function useActiveViewport(viewports, initialViewportId) {
+  const matches = useMediaQueryMatchers(viewports);
+  const [activeViewportIndex, setActiveViewportIndex] = useState(
+    () => getViewportIndex(viewports, initialViewportId)
+  );
+  useEffect(() => {
+    const currentIndex = matches.findLastIndex((isMatch) => isMatch);
+    if (currentIndex !== -1 && currentIndex !== activeViewportIndex) {
+      setActiveViewportIndex(currentIndex);
+    }
+  }, [activeViewportIndex, matches]);
+  return { activeViewportIndex };
+}
+export {
+  useActiveViewport
+};
+//# sourceMappingURL=use-active-viewport.js.map

package/dist/use-active-viewport.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/use-active-viewport.ts"],"sourcesContent":["/*\n * Reactive viewport-matcher hook.\n *\n * \"Active viewport\" = the last-matching media query in the ordered viewports\n * list. With desktop-first ordering (`*`, `<992px`, `<576px`), the narrowest\n * matching query wins. With mobile-first ordering, the widest wins. Either\n * way: the last `findLastIndex` of `mediaQueryMatches[i] === true`.\n *\n * Pass `initialViewportId` (typically derived from User-Agent on the server)\n * to seed the first render so SSR + client agree on viewport before\n * window.matchMedia takes over.\n */\n\n'use client';\n\nimport { useEffect, useState } from 'react';\n\nimport type { ViewportDef } from '@contentful/experiences-core';\nimport { getViewportIndex, toCssMediaQuery } from '@contentful/experiences-design';\n\ninterface MediaQueryMatcher {\n  index: number;\n  signal: MediaQueryList;\n}\n\nfunction createMediaQueryMatchers(viewports: ViewportDef[]): [MediaQueryMatcher[], boolean[]] {\n  const mediaQueryMatches: boolean[] = new Array(viewports.length).fill(false);\n  // The first viewport is the wildcard \"*\" and always matches.\n  mediaQueryMatches[0] = true;\n\n  const mediaQueryMatchers: MediaQueryMatcher[] = [];\n  if (typeof window === 'undefined') {\n    return [mediaQueryMatchers, mediaQueryMatches];\n  }\n  for (let index = 0; index < viewports.length; index++) {\n    const viewport = viewports[index];\n    if (!viewport) continue;\n    const cssQuery = toCssMediaQuery(viewport);\n    if (!cssQuery) continue;\n    const matcher = window.matchMedia(cssQuery);\n    mediaQueryMatches[index] = matcher.matches;\n    mediaQueryMatchers.push({ index, signal: matcher });\n  }\n  return [mediaQueryMatchers, mediaQueryMatches];\n}\n\nfunction useMediaQueryMatchers(viewports: ViewportDef[]): boolean[] {\n  const [, initialMatches] = createMediaQueryMatchers(viewports);\n  const [matches, setMatches] = useState<boolean[]>(initialMatches);\n\n  useEffect(() => {\n    const [matchers] = createMediaQueryMatchers(viewports);\n    const listeners = matchers.map(({ index, signal }) => {\n      const onChange = (): void =>\n        setMatches((prev) => {\n          const next = [...prev];\n          next[index] = signal.matches;\n          return next;\n        });\n      signal.addEventListener('change', onChange);\n      return onChange;\n    });\n    return () => {\n      listeners.forEach((listener, i) => {\n        const matcher = matchers[i];\n        if (matcher) matcher.signal.removeEventListener('change', listener);\n      });\n    };\n  }, [viewports]);\n\n  return matches;\n}\n\nexport interface UseActiveViewportResult {\n  activeViewportIndex: number;\n}\n\nexport function useActiveViewport(\n  viewports: ViewportDef[],\n  initialViewportId?: string\n): UseActiveViewportResult {\n  const matches = useMediaQueryMatchers(viewports);\n  const [activeViewportIndex, setActiveViewportIndex] = useState<number>(() =>\n    getViewportIndex(viewports, initialViewportId)\n  );\n\n  useEffect(() => {\n    const currentIndex = matches.findLastIndex((isMatch) => isMatch);\n    if (currentIndex !== -1 && currentIndex !== activeViewportIndex) {\n      setActiveViewportIndex(currentIndex);\n    }\n  }, [activeViewportIndex, matches]);\n\n  return { activeViewportIndex };\n}\n"],"mappings":";AAeA,SAAS,WAAW,gBAAgB;AAGpC,SAAS,kBAAkB,uBAAuB;AAOlD,SAAS,yBAAyB,WAA4D;AAC5F,QAAM,oBAA+B,IAAI,MAAM,UAAU,MAAM,EAAE,KAAK,KAAK;AAE3E,oBAAkB,CAAC,IAAI;AAEvB,QAAM,qBAA0C,CAAC;AACjD,MAAI,OAAO,WAAW,aAAa;AACjC,WAAO,CAAC,oBAAoB,iBAAiB;AAAA,EAC/C;AACA,WAAS,QAAQ,GAAG,QAAQ,UAAU,QAAQ,SAAS;AACrD,UAAM,WAAW,UAAU,KAAK;AAChC,QAAI,CAAC,SAAU;AACf,UAAM,WAAW,gBAAgB,QAAQ;AACzC,QAAI,CAAC,SAAU;AACf,UAAM,UAAU,OAAO,WAAW,QAAQ;AAC1C,sBAAkB,KAAK,IAAI,QAAQ;AACnC,uBAAmB,KAAK,EAAE,OAAO,QAAQ,QAAQ,CAAC;AAAA,EACpD;AACA,SAAO,CAAC,oBAAoB,iBAAiB;AAC/C;AAEA,SAAS,sBAAsB,WAAqC;AAClE,QAAM,CAAC,EAAE,cAAc,IAAI,yBAAyB,SAAS;AAC7D,QAAM,CAAC,SAAS,UAAU,IAAI,SAAoB,cAAc;AAEhE,YAAU,MAAM;AACd,UAAM,CAAC,QAAQ,IAAI,yBAAyB,SAAS;AACrD,UAAM,YAAY,SAAS,IAAI,CAAC,EAAE,OAAO,OAAO,MAAM;AACpD,YAAM,WAAW,MACf,WAAW,CAAC,SAAS;AACnB,cAAM,OAAO,CAAC,GAAG,IAAI;AACrB,aAAK,KAAK,IAAI,OAAO;AACrB,eAAO;AAAA,MACT,CAAC;AACH,aAAO,iBAAiB,UAAU,QAAQ;AAC1C,aAAO;AAAA,IACT,CAAC;AACD,WAAO,MAAM;AACX,gBAAU,QAAQ,CAAC,UAAU,MAAM;AACjC,cAAM,UAAU,SAAS,CAAC;AAC1B,YAAI,QAAS,SAAQ,OAAO,oBAAoB,UAAU,QAAQ;AAAA,MACpE,CAAC;AAAA,IACH;AAAA,EACF,GAAG,CAAC,SAAS,CAAC;AAEd,SAAO;AACT;AAMO,SAAS,kBACd,WACA,mBACyB;AACzB,QAAM,UAAU,sBAAsB,SAAS;AAC/C,QAAM,CAAC,qBAAqB,sBAAsB,IAAI;AAAA,IAAiB,MACrE,iBAAiB,WAAW,iBAAiB;AAAA,EAC/C;AAEA,YAAU,MAAM;AACd,UAAM,eAAe,QAAQ,cAAc,CAAC,YAAY,OAAO;AAC/D,QAAI,iBAAiB,MAAM,iBAAiB,qBAAqB;AAC/D,6BAAuB,YAAY;AAAA,IACrC;AAAA,EACF,GAAG,CAAC,qBAAqB,OAAO,CAAC;AAEjC,SAAO,EAAE,oBAAoB;AAC/B;","names":[]}

package/dist/use-design-values.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Read the current node's resolved design values (viewport-cascaded +
+ * token-resolved). Returns `{}` when there's no design in scope.
+ *
+ * Pass a type argument to shape the bag, like `useState<T>()`:
+ *
+ *   const design = useDesignValues<{ as?: 'h1' | 'h2' }>();
+ *
+ * `T` is a convenience assertion, not validated at runtime — treat keys as
+ * possibly `undefined`.
+ */
+declare function useDesignValues<T extends object = Record<string, unknown>>(): T;
+
+export { useDesignValues };

package/dist/use-design-values.js

@@ -0,0 +1,9 @@
+"use client";
+import { useResolvedDesign } from "./context";
+function useDesignValues() {
+  return useResolvedDesign() ?? {};
+}
+export {
+  useDesignValues
+};
+//# sourceMappingURL=use-design-values.js.map

package/dist/use-design-values.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/use-design-values.tsx"],"sourcesContent":["'use client';\n\nimport { useResolvedDesign } from './context';\n\n/**\n * Read the current node's resolved design values (viewport-cascaded +\n * token-resolved). Returns `{}` when there's no design in scope.\n *\n * Pass a type argument to shape the bag, like `useState<T>()`:\n *\n *   const design = useDesignValues<{ as?: 'h1' | 'h2' }>();\n *\n * `T` is a convenience assertion, not validated at runtime — treat keys as\n * possibly `undefined`.\n */\nexport function useDesignValues<T extends object = Record<string, unknown>>(): T {\n  return (useResolvedDesign() ?? {}) as T;\n}\n"],"mappings":";AAEA,SAAS,yBAAyB;AAa3B,SAAS,kBAAiE;AAC/E,SAAQ,kBAAkB,KAAK,CAAC;AAClC;","names":[]}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@contentful/experiences-react",
+  "version": "0.5.1",
+  "description": "React adapter for Contentful Experiences — Server and Client renderers over a PortableRenderPlan",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/contentful/experiences.git",
+    "directory": "packages/adapter-react"
+  },
+  "dependencies": {
+    "@contentful/experiences-client": "0.1.1",
+    "@contentful/experiences-core": "0.5.1",
+    "@contentful/experiences-design": "0.5.1"
+  },
+  "peerDependencies": {
+    "react": "^18.0.0 || ^19.0.0",
+    "react-dom": "^18.0.0 || ^19.0.0"
+  },
+  "peerDependenciesMeta": {
+    "react-dom": {
+      "optional": true
+    }
+  }
+}