@contentful/experiences-core 0.0.1 → 0.2.0

package/dist/resolve-experience.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/resolve-experience.ts"],"sourcesContent":["/*\n * Single async entry that turns an XDA Experience payload into a\n * runtime-neutral PortableRenderPlan ready to render.\n *\n * v1 behavior:\n *  - Walk the payload's nodes recursively. Each ComponentType node becomes\n *    a PortableRenderNode with `registration.componentTypeId` extracted\n *    from `componentType.sys.urn` (last slash-segment).\n *  - Split content + design properties onto `node.props.{content,design}`.\n *    Design-prop envelopes (DesignToken / ManualDesignValue / ValuesByViewport)\n *    are preserved on the IR; the design package unwraps them at render time.\n *  - Template-variant nodes are skipped with a console.warn — out of v1 scope.\n *  - For every component whose registration declares `resolveData`, run the\n *    resolver (sync or async) in parallel with peers, and attach the result\n *    to `node.props.resolved`.\n *  - Unknown component-type-id is a render-time concern (handled by the\n *    framework adapter via `renderUnknown`); the IR still emits the node.\n */\n\nimport type {\n  ComponentTypeNode,\n  DesignPropValue,\n  ExperienceContext,\n  ExperienceNode,\n  ExperiencePayload,\n  PortableRenderNode,\n  PortableRenderPlan,\n  PortableTemplate,\n  ResolveContext,\n} from './types';\n\n/**\n * Structural type the resolver walker depends on. Matches the React\n * adapter's `Config` shape but doesn't require importing it — render-core\n * stays decoupled from React.\n */\nexport interface ResolverConfig {\n  components: Record<\n    string,\n    {\n      resolveData?: (\n        ctx: ResolveContext\n      ) => Record<string, unknown> | Promise<Record<string, unknown>>;\n    }\n  >;\n  templates?: Record<\n    string,\n    {\n      resolveData?: (\n        ctx: ResolveContext\n      ) => Record<string, unknown> | Promise<Record<string, unknown>>;\n    }\n  >;\n}\n\nexport interface ResolveExperienceOptions {\n  /**\n   * Per-render runtime context exposed to every resolver as `ctx.experience`.\n   * Defaults to `{ isPreview: false, metadata: {} }`.\n   */\n  experience?: Partial<ExperienceContext>;\n}\n\nconst DEFAULT_EXPERIENCE: ExperienceContext = {\n  isPreview: false,\n  metadata: {},\n};\n\nfunction isComponentTypeNode(node: ExperienceNode): node is ComponentTypeNode {\n  return 'componentType' in node;\n}\n\n/**\n * Extract the flat id (componentType or template) from its `ResourceLink`\n * URN. Real URN shapes:\n *   crn:contentful:::experience:spaces/$self/environments/$self/componentTypes/<id>\n *   crn:contentful:::experience:spaces/$self/environments/$self/templates/<id>\n *\n * The id is the final path segment. We split on `/` and take the last\n * non-empty piece so this also tolerates trailing slashes or alternative\n * prefix shapes.\n */\nfunction extractIdFromUrn(urn: string): string {\n  const segments = urn.split('/').filter((s) => s.length > 0);\n  return segments[segments.length - 1] ?? urn;\n}\n\n/**\n * Recursively turn a payload node into an IR node. The collected `nodeRefs`\n * array is for the resolver pass — every built node with a registered\n * resolver gets a reference appended so we can run them in parallel without\n * walking the tree twice.\n */\nfunction buildNode(\n  node: ExperienceNode,\n  config: ResolverConfig,\n  nodeRefs: PortableRenderNode[]\n): PortableRenderNode | null {\n  if (!isComponentTypeNode(node)) {\n    if (typeof console !== 'undefined') {\n      console.warn(\n        '[@contentful/experiences-core] Skipping Template-variant node — Templates are not supported in v1.'\n      );\n    }\n    return null;\n  }\n\n  const componentTypeId = extractIdFromUrn(node.componentType.sys.urn);\n\n  const slots: Record<string, PortableRenderNode[]> = {};\n  if (node.slots) {\n    for (const [slotName, children] of Object.entries(node.slots)) {\n      if (!Array.isArray(children)) {\n        throw new TypeError(\n          `Slot \"${slotName}\" on component \"${componentTypeId}\" must be an array of nodes.`\n        );\n      }\n      const built: PortableRenderNode[] = [];\n      for (const child of children) {\n        const childNode = buildNode(child, config, nodeRefs);\n        if (childNode === null) continue;\n        built.push(childNode);\n      }\n      slots[slotName] = built;\n    }\n  }\n\n  const built: PortableRenderNode = {\n    registration: { componentTypeId },\n    props: {\n      content: { ...(node.contentProperties ?? {}) },\n      design: { ...(node.designProperties ?? {}) } as Record<string, DesignPropValue>,\n    },\n    slots,\n  };\n  if (node.id) built.nodeId = node.id;\n  if (config.components[componentTypeId]?.resolveData) {\n    nodeRefs.push(built);\n  }\n  return built;\n}\n\n/**\n * Turns an Experience payload (XDA response shape) into a PortableRenderPlan\n * ready to hand to a renderer. Walks the tree, classifies props, captures\n * slots, and runs any component-declared `resolveData` hooks (sync or async)\n * in parallel.\n *\n * Implementation note: the function is always async — even when no component\n * declares a resolver, the cost is one microtask. Customers get a single\n * uniform call site.\n */\nexport async function resolveExperience(\n  payload: ExperiencePayload,\n  config: ResolverConfig,\n  options: ResolveExperienceOptions = {}\n): Promise<PortableRenderPlan> {\n  // Pass 1: walk the payload into the IR. Collect refs to nodes that need\n  // resolveData so pass 2 can run them in parallel without re-walking.\n  const nodeRefs: PortableRenderNode[] = [];\n  const nodes: PortableRenderNode[] = [];\n  for (const node of payload.nodes) {\n    const built = buildNode(node, config, nodeRefs);\n    if (built !== null) nodes.push(built);\n  }\n\n  // Build the page-level template stub if the payload carries one. v1 XDA\n  // payloads don't yet emit template-level content/design properties, so\n  // the IR carries empty bags — additive when the API grows them.\n  const templateUrn = payload.sys?.template?.sys.urn;\n  let template: PortableTemplate | undefined;\n  if (typeof templateUrn === 'string' && templateUrn.length > 0) {\n    template = {\n      templateId: extractIdFromUrn(templateUrn),\n      props: { content: {}, design: {} },\n    };\n  }\n\n  // Pass 2: run resolveData hooks for components AND the template in parallel.\n  const experience: ExperienceContext = {\n    ...DEFAULT_EXPERIENCE,\n    ...options.experience,\n    metadata: {\n      ...DEFAULT_EXPERIENCE.metadata,\n      ...(options.experience?.metadata ?? {}),\n    },\n  };\n\n  const tasks: Array<Promise<void>> = [];\n\n  for (const node of nodeRefs) {\n    const resolver = config.components[node.registration.componentTypeId]?.resolveData;\n    if (!resolver) continue;\n    const ctx: ResolveContext = {\n      content: node.props.content,\n      design: node.props.design,\n      experience,\n    };\n    tasks.push(\n      Promise.resolve(resolver(ctx)).then((resolved) => {\n        node.props.resolved = resolved;\n      })\n    );\n  }\n\n  if (template) {\n    const tplResolver = config.templates?.[template.templateId]?.resolveData;\n    if (tplResolver) {\n      const ctx: ResolveContext = {\n        content: template.props.content,\n        design: template.props.design,\n        experience,\n      };\n      const tpl = template;\n      tasks.push(\n        Promise.resolve(tplResolver(ctx)).then((resolved) => {\n          tpl.props.resolved = resolved;\n        })\n      );\n    }\n  }\n\n  if (tasks.length > 0) await Promise.all(tasks);\n\n  return {\n    viewports: payload.viewports,\n    nodes,\n    ...(template ? { template } : {}),\n  };\n}\n"],"mappings":"AA+DA,MAAM,qBAAwC;AAAA,EAC5C,WAAW;AAAA,EACX,UAAU,CAAC;AACb;AAEA,SAAS,oBAAoB,MAAiD;AAC5E,SAAO,mBAAmB;AAC5B;AAYA,SAAS,iBAAiB,KAAqB;AAC7C,QAAM,WAAW,IAAI,MAAM,GAAG,EAAE,OAAO,CAAC,MAAM,EAAE,SAAS,CAAC;AAC1D,SAAO,SAAS,SAAS,SAAS,CAAC,KAAK;AAC1C;AAQA,SAAS,UACP,MACA,QACA,UAC2B;AAC3B,MAAI,CAAC,oBAAoB,IAAI,GAAG;AAC9B,QAAI,OAAO,YAAY,aAAa;AAClC,cAAQ;AAAA,QACN;AAAA,MACF;AAAA,IACF;AACA,WAAO;AAAA,EACT;AAEA,QAAM,kBAAkB,iBAAiB,KAAK,cAAc,IAAI,GAAG;AAEnE,QAAM,QAA8C,CAAC;AACrD,MAAI,KAAK,OAAO;AACd,eAAW,CAAC,UAAU,QAAQ,KAAK,OAAO,QAAQ,KAAK,KAAK,GAAG;AAC7D,UAAI,CAAC,MAAM,QAAQ,QAAQ,GAAG;AAC5B,cAAM,IAAI;AAAA,UACR,SAAS,QAAQ,mBAAmB,eAAe;AAAA,QACrD;AAAA,MACF;AACA,YAAMA,SAA8B,CAAC;AACrC,iBAAW,SAAS,UAAU;AAC5B,cAAM,YAAY,UAAU,OAAO,QAAQ,QAAQ;AACnD,YAAI,cAAc,KAAM;AACxB,QAAAA,OAAM,KAAK,SAAS;AAAA,MACtB;AACA,YAAM,QAAQ,IAAIA;AAAA,IACpB;AAAA,EACF;AAEA,QAAM,QAA4B;AAAA,IAChC,cAAc,EAAE,gBAAgB;AAAA,IAChC,OAAO;AAAA,MACL,SAAS,EAAE,GAAI,KAAK,qBAAqB,CAAC,EAAG;AAAA,MAC7C,QAAQ,EAAE,GAAI,KAAK,oBAAoB,CAAC,EAAG;AAAA,IAC7C;AAAA,IACA;AAAA,EACF;AACA,MAAI,KAAK,GAAI,OAAM,SAAS,KAAK;AACjC,MAAI,OAAO,WAAW,eAAe,GAAG,aAAa;AACnD,aAAS,KAAK,KAAK;AAAA,EACrB;AACA,SAAO;AACT;AAYA,eAAsB,kBACpB,SACA,QACA,UAAoC,CAAC,GACR;AAG7B,QAAM,WAAiC,CAAC;AACxC,QAAM,QAA8B,CAAC;AACrC,aAAW,QAAQ,QAAQ,OAAO;AAChC,UAAM,QAAQ,UAAU,MAAM,QAAQ,QAAQ;AAC9C,QAAI,UAAU,KAAM,OAAM,KAAK,KAAK;AAAA,EACtC;AAKA,QAAM,cAAc,QAAQ,KAAK,UAAU,IAAI;AAC/C,MAAI;AACJ,MAAI,OAAO,gBAAgB,YAAY,YAAY,SAAS,GAAG;AAC7D,eAAW;AAAA,MACT,YAAY,iBAAiB,WAAW;AAAA,MACxC,OAAO,EAAE,SAAS,CAAC,GAAG,QAAQ,CAAC,EAAE;AAAA,IACnC;AAAA,EACF;AAGA,QAAM,aAAgC;AAAA,IACpC,GAAG;AAAA,IACH,GAAG,QAAQ;AAAA,IACX,UAAU;AAAA,MACR,GAAG,mBAAmB;AAAA,MACtB,GAAI,QAAQ,YAAY,YAAY,CAAC;AAAA,IACvC;AAAA,EACF;AAEA,QAAM,QAA8B,CAAC;AAErC,aAAW,QAAQ,UAAU;AAC3B,UAAM,WAAW,OAAO,WAAW,KAAK,aAAa,eAAe,GAAG;AACvE,QAAI,CAAC,SAAU;AACf,UAAM,MAAsB;AAAA,MAC1B,SAAS,KAAK,MAAM;AAAA,MACpB,QAAQ,KAAK,MAAM;AAAA,MACnB;AAAA,IACF;AACA,UAAM;AAAA,MACJ,QAAQ,QAAQ,SAAS,GAAG,CAAC,EAAE,KAAK,CAAC,aAAa;AAChD,aAAK,MAAM,WAAW;AAAA,MACxB,CAAC;AAAA,IACH;AAAA,EACF;AAEA,MAAI,UAAU;AACZ,UAAM,cAAc,OAAO,YAAY,SAAS,UAAU,GAAG;AAC7D,QAAI,aAAa;AACf,YAAM,MAAsB;AAAA,QAC1B,SAAS,SAAS,MAAM;AAAA,QACxB,QAAQ,SAAS,MAAM;AAAA,QACvB;AAAA,MACF;AACA,YAAM,MAAM;AACZ,YAAM;AAAA,QACJ,QAAQ,QAAQ,YAAY,GAAG,CAAC,EAAE,KAAK,CAAC,aAAa;AACnD,cAAI,MAAM,WAAW;AAAA,QACvB,CAAC;AAAA,MACH;AAAA,IACF;AAAA,EACF;AAEA,MAAI,MAAM,SAAS,EAAG,OAAM,QAAQ,IAAI,KAAK;AAE7C,SAAO;AAAA,IACL,WAAW,QAAQ;AAAA,IACnB;AAAA,IACA,GAAI,WAAW,EAAE,SAAS,IAAI,CAAC;AAAA,EACjC;AACF;","names":["built"]}

package/dist/types.d.ts

@@ -1,244 +1,200 @@
-import { Entry, Asset, AssetFile } from 'contentful';
-import { SCROLL_STATES, OUTGOING_EVENTS, INCOMING_EVENTS, INTERNAL_EVENTS } from './constants.js';
-import { EntityStore } from './entity/EntityStore.js';
-import { Document } from '@contentful/rich-text-types';
-import { ComponentDefinitionPropertyType, ComponentPropertyValue, ExperienceDataSource, ExperienceUnboundValues, Breakpoint, ExperienceComponentTree, ExperienceUsedComponents, ExperienceComponentSettings, ValuesByBreakpoint, PrimitiveValue } from '@contentful/experiences-validators';
-export { BoundValue, Breakpoint, ComponentDefinitionPropertyType as ComponentDefinitionVariableType, ComponentPropertyValue, ComponentTreeNode, ComponentValue, DesignValue, ExperienceComponentSettings, ExperienceDataSource, ExperienceUnboundValues, PrimitiveValue, SchemaVersions, UnboundValue, ValuesByBreakpoint } from '@contentful/experiences-validators';
-
-type ScrollStateKey = keyof typeof SCROLL_STATES;
-type ScrollState = (typeof SCROLL_STATES)[ScrollStateKey];
-type OutgoingEventKey = keyof typeof OUTGOING_EVENTS;
-type OutgoingEvent = (typeof OUTGOING_EVENTS)[OutgoingEventKey];
-type IncomingEventKey = keyof typeof INCOMING_EVENTS;
-type IncomingEvent = (typeof INCOMING_EVENTS)[IncomingEventKey];
-type InternalEventKey = keyof typeof INTERNAL_EVENTS;
-type InternalEvent = (typeof INTERNAL_EVENTS)[InternalEventKey];
-interface Link<T extends string> {
-    sys: {
-        type: 'Link';
-        linkType: T;
-        id: string;
-    };
+/**
+ * Per-render runtime context attached to every customer component as the
+ * `experience` prop. The conventional, single injection point — kept small
+ * at v1. Token resolution, locale, viewport metadata, analytics emitter,
+ * etc. land here in later iterations.
+ */
+interface ExperienceContext {
+    isPreview: boolean;
+    metadata: Record<string, unknown>;
 }
-type VariableFormats = 'URL';
-type ValidationOption<T extends ComponentDefinitionPropertyType> = {
-    value: T extends 'Text' ? string : T extends 'Number' ? number : never;
-    displayName?: string;
-};
-type ComponentDefinitionVariableValidation<T extends ComponentDefinitionPropertyType> = {
-    required?: boolean;
-    in?: ValidationOption<T>[];
-    format?: VariableFormats;
-};
-interface ComponentDefinitionVariableBase<T extends ComponentDefinitionPropertyType> {
-    type: T;
-    validations?: ComponentDefinitionVariableValidation<T>;
-    group?: 'style' | 'content';
-    description?: string;
-    displayName?: string;
-    defaultValue?: string | boolean | number | Record<any, any>;
-}
-type ComponentDefinitionVariable<T extends ComponentDefinitionPropertyType = ComponentDefinitionPropertyType> = ComponentDefinitionVariableBase<T>;
-type ComponentDefinition<T extends ComponentDefinitionPropertyType = ComponentDefinitionPropertyType> = {
+/**
+ * One viewport definition from a delivered Experience. The `query` is the
+ * Contentful media-query DSL ("*" | "<992px" | ">1200px"), not raw CSS.
+ *
+ * The first viewport in the list is conventionally the wildcard ("*") that
+ * always matches. The viewport order encodes the cascade direction —
+ * desktop-first (descending) or mobile-first (ascending).
+ */
+interface ViewportDef {
     id: string;
-    name: string;
-    category?: string;
-    thumbnailUrl?: string;
-    variables: Partial<Record<ContainerStyleVariableName, ComponentDefinitionVariable<T>>> & Record<string, ComponentDefinitionVariable<T>>;
-    builtInStyles?: Array<keyof Omit<StyleProps, 'cfHyperlink' | 'cfOpenInNewTab'>>;
-    children?: boolean;
-    tooltip?: {
-        imageUrl?: string;
-        description: string;
+    query: string;
+    displayName: string;
+    previewSize: string;
+}
+/**
+ * Discriminated design-property value as it arrives from XDA. v1 accepts:
+ *  - ManualDesignValue: an explicit scalar (no viewport involved).
+ *  - ValuesByViewport: a viewport-keyed bag where each entry is itself a
+ *                      ManualDesignValue or DesignToken.
+ *  - DesignToken: a token reference, passed through to customer components
+ *                 as-is for v1. Resolution lands in the future tokens package.
+ */
+type DesignPropValue = ManualDesignValue | DesignToken | ValuesByViewport;
+interface ManualDesignValue {
+    type: 'ManualDesignValue';
+    value: string | number | boolean;
+}
+interface DesignToken {
+    type: 'DesignToken';
+    value: string;
+}
+interface ValuesByViewport {
+    type: 'ValuesByViewport';
+    values: Record<string, ManualDesignValue | DesignToken>;
+}
+/**
+ * Resource-link reference to a registered Component Type. The `urn` carries
+ * the type id; the build-plan extracts the id by taking the segment after
+ * the last slash.
+ */
+interface ComponentTypeRef {
+    sys: {
+        type: 'ResourceLink';
+        linkType: 'Contentful:ComponentType';
+        urn: string;
     };
-};
-type ComponentRegistration = {
-    component: React.ElementType;
-    definition: ComponentDefinition;
-    options?: {
-        wrapComponent?: boolean;
-        wrapContainerTag?: keyof JSX.IntrinsicElements;
+}
+/**
+ * Resource-link reference to a Template. Templates are out of v1 scope and
+ * are skipped at plan-build time with a diagnostic.
+ */
+interface TemplateRef {
+    sys: {
+        type: 'ResourceLink';
+        linkType: 'Contentful:Template';
+        urn: string;
     };
-};
-type ComponentRegistrationOptions = {
-    enabledBuiltInComponents?: string[];
-};
-type Binding = {
-    spaceId: string;
-    environmentId: string;
-    entityId: string;
-    entityType: 'Entry' | 'Asset' | 'ContentType';
-    path: string[];
-};
-type ComponentBinding = Record<string, Binding>;
-type BindingMap = Record<string, ComponentBinding>;
-type BindingMapByBlockId = Record<string, BindingMap>;
-type DataSourceEntryValueType = Link<'Entry' | 'Asset'>;
-/** Type of a single node of the experience tree exchanged via postMessage between the SDK and Contentful Web app */
-type ExperienceTreeNode = {
-    type: 'block' | 'root' | 'editorRoot' | 'designComponent' | 'designComponentBlock' | 'assembly' | 'assemblyBlock';
-    data: {
-        id: string;
-        blockId?: string;
-        assembly?: {
-            id: string;
-            componentId: string;
-            nodeLocation: string | null;
-        };
-        props: Record<string, ComponentPropertyValue>;
-        dataSource: ExperienceDataSource;
-        unboundValues: ExperienceUnboundValues;
-        breakpoints: Breakpoint[];
+}
+/**
+ * One node from `GetExperienceViewResponse.nodes` (or any `slots[name]`).
+ * Discriminated by which of `componentType` / `template` is present.
+ */
+type ExperienceNode = ComponentTypeNode | TemplateNode;
+interface ComponentTypeNode {
+    componentType: ComponentTypeRef;
+    id?: string;
+    contentProperties?: Record<string, unknown>;
+    designProperties?: Record<string, DesignPropValue>;
+    slots?: Record<string, ExperienceNode[]>;
+    contentBindings?: string;
+}
+interface TemplateNode {
+    template: TemplateRef;
+    id?: string;
+    contentProperties?: Record<string, unknown>;
+    designProperties?: Record<string, DesignPropValue>;
+    slots?: Record<string, ExperienceNode[]>;
+    contentBindings?: string;
+}
+/**
+ * Top-level `sys` block on an Experience payload. The bits the SDK actually
+ * reads are typed; everything else is left loose because the upstream
+ * type carries dozens of editor/audit fields the renderer doesn't care about.
+ */
+interface ExperienceSys {
+    /**
+     * Optional page-level template reference. When present, the renderer wraps
+     * the experience nodes with the matching template registered in the
+     * customer's Config. When absent, nodes render at the top level.
+     */
+    template?: TemplateRef;
+    [key: string]: unknown;
+}
+/**
+ * Top-level Experience payload as returned by the Experience Delivery API
+ * (`GetExperienceViewResponse` from `@contentful/experience-delivery`).
+ *
+ * Structurally compatible with the upstream type — no normalization step
+ * required when consuming a delivery-client response.
+ */
+interface ExperiencePayload {
+    viewports: ViewportDef[];
+    nodes: ExperienceNode[];
+    errors?: unknown[];
+    extensions?: unknown;
+    sys?: ExperienceSys;
+}
+/**
+ * Per-node context handed to a component's `resolveData` resolver. Carries
+ * the raw content + design props from the payload (design envelopes are NOT
+ * pre-resolved against a viewport — viewport resolution stays a render-time
+ * concern so client viewport changes don't re-trigger async resolvers).
+ */
+interface ResolveContext {
+    content: Record<string, unknown>;
+    design: Record<string, DesignPropValue>;
+    experience: ExperienceContext;
+}
+/**
+ * Registration metadata for a single instance — the SDK's interpreted
+ * pointer to the customer's component implementation. v1 carries only the
+ * resolved component-type id; capabilities (state requirements, supported
+ * events, lifecycle hints, fallback ids) land on this object in later
+ * iterations without breaking the IR.
+ */
+interface PortableRegistration {
+    componentTypeId: string;
+}
+/**
+ * The IR — one node per component instance. The seam that lets non-React
+ * adapters (Angular, SwiftUI, Compose) consume the same interpretation.
+ *
+ * Design props preserve the discriminated envelope as they arrived. Adapters
+ * unwrap to plain scalars at render time, given an active viewport.
+ * (DesignToken envelopes pass through unwrapped — customer components decide
+ * how to resolve them in v1.)
+ *
+ * `props.resolved` is populated by `resolveExperience` from any
+ * customer-supplied `resolveData` resolver and merged into the final prop bag
+ * after content + design but before slot props.
+ */
+interface PortableRenderNode {
+    /**
+     * Optional. Passed through from the XDA payload's `id` field when the
+     * editor supplies one. The SDK does NOT auto-generate ids; adapters fall
+     * back to the array index for React keys / debug labels when absent.
+     */
+    nodeId?: string;
+    registration: PortableRegistration;
+    props: {
+        content: Record<string, unknown>;
+        design: Record<string, DesignPropValue>;
+        resolved?: Record<string, unknown>;
     };
-    children: ExperienceTreeNode[];
-    parentId?: string;
-};
-/** Type of the tree data structure exchanged via postMessage between the SDK and Contentful Web app */
-type ExperienceTree = {
-    root: ExperienceTreeNode;
-};
-type ExternalSDKMode = 'preview' | 'delivery';
-type InternalSDKMode = ExternalSDKMode | 'editor';
+    slots: Record<string, PortableRenderNode[]>;
+}
 /**
- * Internally defined style variables are prefix with `cf` to avoid
- * collisions with user defined variables.
+ * Interpreted page-level template — the optional wrapper around the
+ * experience tree. `templateId` is extracted from
+ * `payload.sys.template.sys.urn` (last slash-segment).
+ *
+ * Templates carry the same prop-resolution shape as components: content +
+ * design envelopes plus an optional `resolved` bag from a `resolveData` hook.
+ * v1 payloads from XDA don't carry template-level content/design properties
+ * yet, but the IR makes room for them so the API doesn't need to break later.
  */
-type StyleProps = {
-    cfHorizontalAlignment: 'start' | 'end' | 'center';
-    cfVerticalAlignment: 'start' | 'end' | 'center';
-    cfMargin: string;
-    cfPadding: string;
-    cfBackgroundColor: string;
-    cfWidth: string;
-    cfMaxWidth: string;
-    cfHeight: string;
-    cfFlexDirection: 'row' | 'column';
-    cfFlexWrap: 'nowrap' | 'wrap';
-    cfBorder: string;
-    cfBorderRadius: string;
-    cfGap: string;
-    cfHyperlink: string;
-    cfImageAsset: OptimizedImageAsset | string;
-    cfImageOptions: ImageOptions;
-    cfBackgroundImageUrl: OptimizedBackgroundImageAsset | string;
-    cfBackgroundImageOptions: BackgroundImageOptions;
-    cfOpenInNewTab: boolean;
-    cfFontSize: string;
-    cfFontWeight: string;
-    cfLineHeight: string;
-    cfLetterSpacing: string;
-    cfTextColor: string;
-    cfTextAlign: 'left' | 'center' | 'right';
-    cfTextTransform: 'none' | 'capitalize' | 'uppercase' | 'lowercase';
-    cfTextBold: boolean;
-    cfTextItalic: boolean;
-    cfTextUnderline: boolean;
-    cfColumns: string;
-    cfColumnSpan: string;
-    cfColumnSpanLock: boolean;
-    cfWrapColumns: boolean;
-    cfWrapColumnsCount: string;
-};
-type CSSProperties = React.CSSProperties;
-type ContainerStyleVariableName = keyof StyleProps;
-type ExperienceFields = {
-    title: string;
-    slug: string;
-    componentTree: ExperienceComponentTree;
-    dataSource: ExperienceDataSource;
-    unboundValues: ExperienceUnboundValues;
-    usedComponents?: ExperienceUsedComponents | Array<ExperienceEntry>;
-    componentSettings?: ExperienceComponentSettings;
-};
-type RecursiveDesignTokenDefinition = {
-    [key: string]: string | RecursiveDesignTokenDefinition;
-};
-type DesignTokensDefinition = {
-    spacing?: Record<string, string>;
-    sizing?: Record<string, string>;
-    color?: Record<string, string>;
-    border?: Record<string, {
-        width: string;
-        style: 'solid' | 'dashed' | 'dotted';
-        color: string;
-    }>;
-    borderRadius?: Record<string, string>;
-    fontSize?: Record<string, string>;
-    lineHeight?: Record<string, string>;
-    letterSpacing?: Record<string, string>;
-    textColor?: Record<string, string>;
-} & RecursiveDesignTokenDefinition;
-/** Type of experience entry JSON data structure as returned by CPA/CDA */
-type ExperienceEntry = {
-    sys: Entry['sys'];
-    fields: ExperienceFields;
-    metadata: Entry['metadata'];
-};
-interface RawCoordinates {
-    left: number;
-    top: number;
-    width: number;
-    height: number;
-}
-interface Coordinates extends RawCoordinates {
-    childrenCoordinates: RawCoordinates[];
-}
-interface HoveredElement {
-    blockType: string | undefined;
-    nodeId: string | undefined;
-    blockId: string | undefined;
-}
-interface Experience<T extends EntityStore = EntityStore> {
-    entityStore?: T;
-}
-type ResolveDesignValueType = (valuesByBreakpoint: ValuesByBreakpoint, variableName: string) => PrimitiveValue;
-type ManagementEntity = (Entry | Asset) & {
-    sys: {
-        version: number;
+interface PortableTemplate {
+    templateId: string;
+    props: {
+        content: Record<string, unknown>;
+        design: Record<string, DesignPropValue>;
+        resolved?: Record<string, unknown>;
     };
-};
-type RequestEntitiesMessage = {
-    entityIds: string[];
-    entityType: 'Asset' | 'Entry';
-    locale: string;
-};
-type RequestedEntitiesMessage = {
-    entities: Array<Entry | Asset>;
-    missingEntityIds?: string[];
-};
-type BoundComponentPropertyTypes = string | number | boolean | AssetFile | Record<string, AssetFile | undefined> | Document | OptimizedBackgroundImageAsset | OptimizedImageAsset | Link<'Asset'> | undefined;
-type OptimizedImageAsset = {
-    url: string;
-    srcSet?: string[];
-    sizes?: string;
-    quality?: number;
-    format?: string;
-    file: AssetFile;
-};
-type OptimizedBackgroundImageAsset = {
-    url: string;
-    srcSet?: string[];
-    file: AssetFile;
-};
-type ImageObjectFitOption = 'contain' | 'cover' | 'none';
-type ImageObjectPositionOption = 'left' | 'right' | 'top' | 'bottom' | 'left top' | 'left center' | 'left bottom' | 'right top' | 'right center' | 'right bottom' | 'center top' | 'center center' | 'center bottom';
-type ImageOptions = {
-    format?: string;
-    width: string;
-    height: string;
-    objectFit?: ImageObjectFitOption;
-    objectPosition?: ImageObjectPositionOption;
-    quality?: string;
-    targetSize: string;
-};
-type BackgroundImageScalingOption = 'fit' | 'fill' | 'tile';
-type BackgroundImageAlignmentOption = 'left' | 'right' | 'top' | 'bottom' | 'left top' | 'left center' | 'left bottom' | 'right top' | 'right center' | 'right bottom' | 'center top' | 'center center' | 'center bottom';
-type BackgroundImageOptions = {
-    format?: string;
-    scaling: BackgroundImageScalingOption;
-    alignment: BackgroundImageAlignmentOption;
-    quality?: string;
-    targetSize: string;
-};
+}
+/**
+ * The interpreted experience tree.
+ *
+ * Top-level is `nodes: PortableRenderNode[]` (array, not single root) to
+ * match the actual XDA payload shape. Renderers iterate top-level nodes
+ * and recurse into `node.slots`. When `template` is present, the renderer
+ * wraps the nodes with the matching template config; otherwise nodes
+ * render at the top level.
+ */
+interface PortableRenderPlan {
+    viewports: ViewportDef[];
+    nodes: PortableRenderNode[];
+    template?: PortableTemplate;
+}
 
-export type { BackgroundImageAlignmentOption, BackgroundImageOptions, BackgroundImageScalingOption, Binding, BindingMap, BindingMapByBlockId, BoundComponentPropertyTypes, CSSProperties, ComponentBinding, ComponentDefinition, ComponentDefinitionVariable, ComponentDefinitionVariableBase, ComponentDefinitionVariableValidation, ComponentRegistration, ComponentRegistrationOptions, ContainerStyleVariableName, Coordinates, DataSourceEntryValueType, DesignTokensDefinition, Experience, ExperienceEntry, ExperienceFields, ExperienceTree, ExperienceTreeNode, ExternalSDKMode, HoveredElement, ImageObjectFitOption, ImageObjectPositionOption, ImageOptions, IncomingEvent, InternalEvent, InternalSDKMode, Link, ManagementEntity, OptimizedBackgroundImageAsset, OptimizedImageAsset, OutgoingEvent, RawCoordinates, RecursiveDesignTokenDefinition, RequestEntitiesMessage, RequestedEntitiesMessage, ResolveDesignValueType, ScrollState, StyleProps, ValidationOption, VariableFormats };
+export type { ComponentTypeNode, ComponentTypeRef, DesignPropValue, DesignToken, ExperienceContext, ExperienceNode, ExperiencePayload, ExperienceSys, ManualDesignValue, PortableRegistration, PortableRenderNode, PortableRenderPlan, PortableTemplate, ResolveContext, TemplateNode, TemplateRef, ValuesByViewport, ViewportDef };

package/dist/types.js

@@ -0,0 +1 @@
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/package.json

@@ -1,75 +1,32 @@
 {
   "name": "@contentful/experiences-core",
-  "version": "0.0.1",
-  "description": "",
-  "main": "dist/index.js",
-  "module": "dist/index.js",
-  "types": "dist/index.d.ts",
+  "version": "0.2.0",
+  "description": "Runtime-neutral types + experience resolution for Contentful Experiences",
+  "license": "MIT",
   "type": "module",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/contentful/experience-builder.git"
+  "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": [
-    "readme.md",
-    "package.json",
-    "dist/**/*.*"
+    "dist",
+    "README.md",
+    "CHANGELOG.md"
   ],
-  "exports": {
-    ".": "./dist/index.js",
-    "./constants": "./dist/constants.js"
-  },
   "publishConfig": {
-    "registry": "https://npm.pkg.github.com/"
-  },
-  "typesVersions": {
-    "*": {
-      "types": [
-        "./dist/types.d.ts"
-      ],
-      "constants": [
-        "./dist/constants.d.ts"
-      ]
-    }
+    "access": "public"
   },
-  "scripts": {
-    "clean": "rimraf dist",
-    "prebuild": "npm run clean",
-    "build": "rollup -c ./rollup.config.mjs",
-    "predev": "npm run clean",
-    "dev": "rollup -c ./rollup.config.mjs --watch --environment DEV",
-    "lint": "eslint src --ext '.ts,.tsx,.js,.jsx' --max-warnings 0 --ignore-path ../../.eslintignore",
-    "lint:fix": "eslint src --ext '.ts,.tsx,.js,.jsx' --fix",
-    "test": "vitest",
-    "test:coverage": "vitest run --coverage",
-    "depcruise": "depcruise src"
-  },
-  "author": "",
-  "license": "MIT",
-  "devDependencies": {
-    "@rollup/plugin-commonjs": "^25.0.7",
-    "@rollup/plugin-node-resolve": "^15.2.3",
-    "@rollup/plugin-terser": "^0.4.4",
-    "@rollup/plugin-typescript": "^11.1.5",
-    "@types/lodash-es": "^4.17.12",
-    "@typescript-eslint/eslint-plugin": "^7.0.2",
-    "@typescript-eslint/parser": "^7.0.2",
-    "@vitest/coverage-v8": "^1.0.4",
-    "contentful": "^10.6.4",
-    "eslint": "^8.54.0",
-    "happy-dom": "^13.3.8",
-    "rimraf": "^5.0.5",
-    "rollup-plugin-dts": "^6.1.0",
-    "rollup-plugin-ts": "^3.4.5",
-    "vite-tsconfig-paths": "^4.2.2",
-    "vitest": "^1.0.4"
-  },
-  "dependencies": {
-    "@contentful/experiences-validators": "^0.0.1",
-    "@contentful/rich-text-types": "^16.3.0"
-  },
-  "peerDependencies": {
-    "contentful": ">=10.6.0"
-  },
-  "gitHead": "4b635ce38f276566da970c47ef8aec0cde771608"
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/contentful/experiences.git",
+    "directory": "packages/core"
+  }
 }

package/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2023 Contentful
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.

package/dist/communication/sendMessage.d.ts

@@ -1,6 +0,0 @@
-import { PostMessageMethods } from '../constants.js';
-import { OutgoingEvent } from '../types.js';
-
-declare const sendMessage: (eventType: OutgoingEvent | PostMessageMethods, data?: unknown) => void;
-
-export { sendMessage };