@contentful/experiences-core 1.42.4-prerelease-20250702T1207-37b3bfc.0 → 2.0.0-beta.1

package/dist/index.js

@@ -2,6 +2,7 @@ import { z, ZodIssueCode } from 'zod';
 import { omit, isArray, uniqBy } from 'lodash-es';
 import md5 from 'md5';
 import { BLOCKS } from '@contentful/rich-text-types';
+import { create } from 'zustand';
 
 const INCOMING_EVENTS = {
     RequestEditorMode: 'requestEditorMode',
@@ -114,14 +115,6 @@ const CF_STYLE_ATTRIBUTES = [
     'cfTextBold',
     'cfTextItalic',
     'cfTextUnderline',
-    // For backwards compatibility
-    // we need to keep those in this constant array
-    // so that omit() in <VisualEditorBlock> and <CompositionBlock>
-    // can filter them out and not pass as props
-    'cfBackgroundImageScaling',
-    'cfBackgroundImageAlignment',
-    'cfBackgroundImageAlignmentVertical',
-    'cfBackgroundImageAlignmentHorizontal',
 ];
 const EMPTY_CONTAINER_HEIGHT = '80px';
 const DEFAULT_IMAGE_WIDTH = '500px';
@@ -1457,6 +1450,24 @@ propertyName, resolveDesignTokens = true) => {
         return valuesByBreakpoint;
     }
 };
+/** Overwrites the default value breakpoint by breakpoint. If a breakpoint
+ * is not overwritten, it will fall back to the default. */
+function mergeDesignValuesByBreakpoint(defaultValue, overwriteValue) {
+    if (!defaultValue || !overwriteValue) {
+        return defaultValue ?? overwriteValue;
+    }
+    const mergedValuesByBreakpoint = { ...defaultValue.valuesByBreakpoint };
+    for (const [breakpointId, value] of Object.entries(overwriteValue.valuesByBreakpoint)) {
+        if (!isValidBreakpointValue(value)) {
+            continue;
+        }
+        mergedValuesByBreakpoint[breakpointId] = value;
+    }
+    return {
+        type: 'DesignValue',
+        valuesByBreakpoint: mergedValuesByBreakpoint,
+    };
+}
 
 const CF_DEBUG_KEY = 'cf_debug';
 /**
@@ -1586,11 +1597,19 @@ const getElementCoordinates = (element) => {
     });
 };
 
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
 const isLinkToAsset = (variable) => {
-    if (!variable)
+    if (variable === null || typeof variable !== 'object')
+        return false;
+    // The `'prop' in` pattern is informing TypeScript of the object shape, no need to cast `as`.
+    if (!('sys' in variable))
+        return false;
+    if (variable.sys === null || typeof variable.sys !== 'object')
+        return false;
+    if (!('linkType' in variable.sys))
+        return false;
+    if (!('id' in variable.sys))
         return false;
-    if (typeof variable !== 'object')
+    if (!('type' in variable.sys))
         return false;
     return (variable.sys?.linkType === 'Asset' &&
         typeof variable.sys?.id === 'string' &&
@@ -1598,13 +1617,33 @@ const isLinkToAsset = (variable) => {
         variable.sys?.type === 'Link');
 };
 
+const isLinkToEntry = (variable) => {
+    if (variable === null || typeof variable !== 'object')
+        return false;
+    // The `'prop' in` pattern is informing TypeScript of the object shape, no need to cast `as`.
+    if (!('sys' in variable))
+        return false;
+    if (variable.sys === null || typeof variable.sys !== 'object')
+        return false;
+    if (!('linkType' in variable.sys))
+        return false;
+    if (!('id' in variable.sys))
+        return false;
+    if (!('type' in variable.sys))
+        return false;
+    return (variable.sys?.linkType === 'Entry' &&
+        typeof variable.sys?.id === 'string' &&
+        !!variable.sys?.id &&
+        variable.sys?.type === 'Link');
+};
+
 const isLink = (maybeLink) => {
     if (maybeLink === null)
         return false;
     if (typeof maybeLink !== 'object')
         return false;
     const link = maybeLink;
-    return Boolean(link.sys?.id) && link.sys?.type === 'Link';
+    return Boolean(link.sys?.id) && link.sys?.type === 'Link' && Boolean(link.sys?.linkType);
 };
 
 /**
@@ -1831,11 +1870,6 @@ const transformVisibility = (value) => {
     // Don't explicitly set anything when visible to not overwrite values like `grid` or `flex`.
     return {};
 };
-// TODO: Remove in next major version v2 since the change is 17 months old
-// Keep this for backwards compatibility - deleting this would be a breaking change
-// because existing components on a users experience will have the width value as fill
-// rather than 100%
-const transformFill = (value) => (value === 'fill' ? '100%' : value);
 const transformGridColumn = (span) => {
     if (!span) {
         return {};
@@ -1880,34 +1914,6 @@ const transformBackgroundImage = (cfBackgroundImageUrl, cfBackgroundImageOptions
             return;
         }
         let [horizontalAlignment, verticalAlignment] = alignment.trim().split(/\s+/, 2);
-        // Special case for handling single values
-        // for backwards compatibility with single values 'right','left', 'center', 'top','bottom'
-        if (horizontalAlignment && !verticalAlignment) {
-            const singleValue = horizontalAlignment;
-            switch (singleValue) {
-                case 'left':
-                    horizontalAlignment = 'left';
-                    verticalAlignment = 'center';
-                    break;
-                case 'right':
-                    horizontalAlignment = 'right';
-                    verticalAlignment = 'center';
-                    break;
-                case 'center':
-                    horizontalAlignment = 'center';
-                    verticalAlignment = 'center';
-                    break;
-                case 'top':
-                    horizontalAlignment = 'center';
-                    verticalAlignment = 'top';
-                    break;
-                case 'bottom':
-                    horizontalAlignment = 'center';
-                    verticalAlignment = 'bottom';
-                    break;
-                // just fall down to the normal validation logic for horiz and vert
-            }
-        }
         const isHorizontalValid = ['left', 'right', 'center'].includes(horizontalAlignment);
         const isVerticalValid = ['top', 'bottom', 'center'].includes(verticalAlignment);
         horizontalAlignment = isHorizontalValid ? horizontalAlignment : 'left';
@@ -1992,8 +1998,8 @@ const buildCfStyles = (values) => {
         margin: values.cfMargin,
         padding: values.cfPadding,
         backgroundColor: values.cfBackgroundColor,
-        width: transformFill(values.cfWidth || values.cfImageOptions?.width),
-        height: transformFill(values.cfHeight || values.cfImageOptions?.height),
+        width: values.cfWidth || values.cfImageOptions?.width,
+        height: values.cfHeight || values.cfImageOptions?.height,
         maxWidth: values.cfMaxWidth,
         ...transformGridColumn(values.cfColumnSpan),
         ...transformBorderStyle(values.cfBorder),
@@ -2216,7 +2222,7 @@ const detachExperienceStyles = (experience) => {
              * {
              *   desktop: {
              *     cfMargin: '1px',
-             *     cfWidth: 'fill',
+             *     cfWidth: '100%',
              *     cfBackgroundImageUrl: 'https://example.com/image.jpg'
              *     //...
              *   }
@@ -2385,9 +2391,10 @@ const resolveComponentVariablesOverwrites = ({ patternNode, wrapperComponentVari
             const overwritingValue = wrapperComponentVariablesOverwrites?.[propertyValue.key];
             // Property definition from the parent pattern
             const propertyDefinition = wrapperComponentSettings?.variableDefinitions?.[propertyValue.key];
+            const defaultValue = propertyDefinition?.defaultValue;
             // The overwriting value is either a custom value from the experience or default value from a
             // wrapping pattern node that got trickled down to this nesting level.
-            resolvedValues[propertyName] = overwritingValue ?? propertyDefinition?.defaultValue;
+            resolvedValues[propertyName] = mergeDefaultAndOverwriteValues(defaultValue, overwritingValue);
         }
         else {
             // Keep raw values
@@ -2470,15 +2477,15 @@ const resolveBackgroundImageBinding = ({ variableData, getBoundEntityById, dataS
         // @ts-expect-error TODO: Types coming from validations erroneously assume that `defaultValue` can be a primitive value (e.g. string or number)
         const defaultValueKey = variableDefinition.defaultValue?.key;
         const defaultValue = unboundValues[defaultValueKey].value;
-        const userSetValue = componentVariablesOverwrites?.[variableDefinitionKey];
-        // userSetValue is a ComponentValue we can safely return the default value
-        if (!userSetValue || userSetValue.type === 'ComponentValue') {
+        const overwriteValue = componentVariablesOverwrites?.[variableDefinitionKey];
+        // overwriteValue is a ComponentValue we can safely return the default value
+        if (!overwriteValue || overwriteValue.type === 'ComponentValue') {
             return defaultValue;
         }
-        // at this point userSetValue will either be type of 'DesignValue' or 'BoundValue'
+        // at this point overwriteValue will either be type of 'DesignValue' or 'BoundValue'
         // so we recursively run resolution again to resolve it
         const resolvedValue = resolveBackgroundImageBinding({
-            variableData: userSetValue,
+            variableData: overwriteValue,
             getBoundEntityById,
             dataSource,
             unboundValues,
@@ -2631,10 +2638,10 @@ const indexByBreakpoint = ({ variables, breakpointIds, getBoundEntityById, unbou
         let resolvedVariableData = variableData;
         if (variableData.type === 'ComponentValue') {
             const variableDefinition = componentSettings?.variableDefinitions[variableData.key];
-            if (variableDefinition.group === 'style' && variableDefinition.defaultValue !== undefined) {
-                const overrideVariableData = componentVariablesOverwrites?.[variableData.key];
-                resolvedVariableData =
-                    overrideVariableData || variableDefinition.defaultValue;
+            const defaultValue = variableDefinition.defaultValue;
+            if (variableDefinition.group === 'style' && defaultValue !== undefined) {
+                const overwriteVariableData = componentVariablesOverwrites?.[variableData.key];
+                resolvedVariableData = mergeDefaultAndOverwriteValues(defaultValue, overwriteVariableData);
             }
         }
         if (resolvedVariableData.type !== 'DesignValue') {
@@ -2672,6 +2679,12 @@ const flattenDesignTokenRegistry = (designTokenRegistry) => {
         };
     }, {});
 };
+function mergeDefaultAndOverwriteValues(defaultValue, overwriteValue) {
+    if (defaultValue?.type === 'DesignValue' && overwriteValue?.type === 'DesignValue') {
+        return mergeDesignValuesByBreakpoint(defaultValue, overwriteValue);
+    }
+    return overwriteValue ?? defaultValue;
+}
 
 /**
  * Turns a condition like `<768px` or `>1024px` into a media query rule.
@@ -2767,7 +2780,9 @@ const transformRichText = (entryOrAsset, entityStore, path) => {
     }
     if (typeof value === 'object' && value.nodeType === BLOCKS.DOCUMENT) {
         // resolve any links to assets/entries/hyperlinks
-        const richTextDocument = value;
+        // we need to clone, as we want to keep the original Entity in the EntityStore intact,
+        // and resolveLinks() is mutating the node object.
+        const richTextDocument = structuredClone(value);
         resolveLinks(richTextDocument, entityStore);
         return richTextDocument;
     }
@@ -2881,17 +2896,37 @@ const transformMedia = (asset, variables, resolveDesignValue, variableName, path
     return asset.fields.file?.url;
 };
 
-const isAsset = (value) => {
+const isExperienceEntry = (entry) => {
+    return (entry?.sys?.type === 'Entry' &&
+        !!entry.fields?.title &&
+        !!entry.fields?.slug &&
+        !!entry.fields?.componentTree &&
+        Array.isArray(entry.fields.componentTree.breakpoints) &&
+        Array.isArray(entry.fields.componentTree.children) &&
+        typeof entry.fields.componentTree.schemaVersion === 'string');
+};
+const isPatternEntry = (entry) => {
+    return isExperienceEntry(entry) && !!entry.fields?.componentSettings; // signals that this is pattern (not experience) entry
+};
+const isEntry = (value) => {
     return (null !== value &&
         typeof value === 'object' &&
         'sys' in value &&
-        value.sys?.type === 'Asset');
+        value.sys?.type === 'Entry');
 };
-const isEntry = (value) => {
+const isAsset = (value) => {
     return (null !== value &&
         typeof value === 'object' &&
         'sys' in value &&
-        value.sys?.type === 'Entry');
+        value.sys?.type === 'Asset');
+};
+/**
+ * Checks if the values is an array of links.
+ * Note: we use convention where empty arrays are considered valid "arrays of links"
+ * as they don't contradict the type definition.
+ */
+const isArrayOfLinks = (value) => {
+    return Array.isArray(value) && value.every((item) => isLink(item));
 };
 
 function getResolvedEntryFromLink(entryOrAsset, path, entityStore) {
@@ -2901,7 +2936,8 @@ function getResolvedEntryFromLink(entryOrAsset, path, entityStore) {
     else if (!isEntry(entryOrAsset)) {
         throw new Error(`Expected an Entry or Asset, but got: ${JSON.stringify(entryOrAsset)}`);
     }
-    const value = get(entryOrAsset, path.split('/').slice(2, -1));
+    const fieldName = path.split('/').slice(2, -1);
+    const value = get(entryOrAsset, fieldName);
     let resolvedEntity;
     if (isAsset(value) || isEntry(value)) {
         // In some cases, reference fields are already resolved
@@ -2910,74 +2946,67 @@ function getResolvedEntryFromLink(entryOrAsset, path, entityStore) {
     else if (value?.sys.type === 'Link') {
         // Look up the reference in the entity store
         resolvedEntity = entityStore.getEntityFromLink(value);
-        if (!resolvedEntity) {
-            return;
-        }
     }
     else {
-        console.warn(`Expected a link to a reference, but got: ${JSON.stringify(value)}`);
+        console.warn(`When attempting to follow link in field '${fieldName}' of entity, the value is expected to be a link, but got: ${JSON.stringify(value)}`, { entity: entryOrAsset });
+        return;
+    }
+    // no need to make structuredClone(entityStore.getEntityFromLink(value)) because
+    // we provide component with the original Object.frozen object of the entity.
+    // As we don't resolve L3 and don't mutate the entity before returning anymore,
+    // we don't need to make a copy of the entity. And even provide better referential integrity
+    // for the component for the same entity.
+    if (!resolvedEntity) {
         return;
     }
-    //resolve any embedded links - we currently only support 2 levels deep
-    const fields = resolvedEntity.fields || {};
-    Object.entries(fields).forEach(([fieldKey, field]) => {
-        if (field && field.sys?.type === 'Link') {
-            const entity = entityStore.getEntityFromLink(field);
-            if (entity) {
-                resolvedEntity.fields[fieldKey] = entity;
-            }
-        }
-        else if (field && Array.isArray(field)) {
-            resolvedEntity.fields[fieldKey] = field.map((innerField) => {
-                if (innerField && innerField.sys?.type === 'Link') {
-                    const entity = entityStore.getEntityFromLink(innerField);
-                    if (entity) {
-                        return entity;
-                    }
-                }
-                return innerField;
-            });
-        }
-    });
     return resolvedEntity;
 }
 
+const excludeUndefined = (value) => {
+    return value !== undefined;
+};
 function getArrayValue(entryOrAsset, path, entityStore) {
+    // NOTE: Not sure if we need this if-statement,
+    // as it is NOT possible to bind to Array variable an Asset
+    // (as Assets don't have multi-reference fields) unless it's a degenerate case.
     if (entryOrAsset.sys.type === 'Asset') {
         return entryOrAsset;
     }
-    const arrayValue = get(entryOrAsset, path.split('/').slice(2, -1));
+    const fieldName = path.split('/').slice(2, -1);
+    const arrayValue = get(entryOrAsset, fieldName);
     if (!isArray(arrayValue)) {
-        console.warn(`Expected a value to be an array, but got: ${JSON.stringify(arrayValue)}`);
+        console.warn(`A field '${fieldName}' of an entity was bound to an Array variable. Expected value of that field to be an array, but got: ${JSON.stringify(arrayValue)}`, { entity: entryOrAsset });
         return;
     }
-    const result = arrayValue.map((value) => {
+    const result = arrayValue
+        .map((value) => {
         if (typeof value === 'string') {
-            return value;
+            return value; // handles case where Text array is bound (in [Content Model] tab of the platform, select Text and make it a list)
         }
         else if (value?.sys?.type === 'Link') {
             const resolvedEntity = entityStore.getEntityFromLink(value);
             if (!resolvedEntity) {
+                // We return undefined, which means that entity wasn't availble in the Entity Store due to:
+                //  - because it's archived entity (and they normally wouldn't be sent to the Entity Store)
+                //  - bug where some entity wasn't added to the Entity Store
+                //  BTW, deleted entities shouldn't even be possible here as they require CT deletion first and that shouldn't allow us to load them at all)
                 return;
             }
-            //resolve any embedded links - we currently only support 2 levels deep
-            const fields = resolvedEntity.fields || {};
-            Object.entries(fields).forEach(([fieldKey, field]) => {
-                if (field && field.sys?.type === 'Link') {
-                    const entity = entityStore.getEntityFromLink(field);
-                    if (entity) {
-                        resolvedEntity.fields[fieldKey] = entity;
-                    }
-                }
-            });
             return resolvedEntity;
         }
         else {
             console.warn(`Expected value to be a string or Link, but got: ${JSON.stringify(value)}`);
             return undefined;
         }
-    });
-    return result;
+    })
+        .filter(excludeUndefined);
+    // eg. imagine you have multi-referene field with 3 links to archived entries,
+    //     all of them will be undefined on previous step and will be filtered out
+    //     of resultWithoutUndefined. Instead of passing to component an empty array,
+    //     we pass undefined. This means that develloper making custom component
+    //     does not have to handle empty array case. But only undefiened, which signals:
+    //     user didn't bind anything; user bound to reference field which is unset; all references are archived
+    return result.length > 0 ? result : undefined;
 }
 
 const transformBoundContentValue = (variables, entityStore, binding, resolveDesignValue, variableName, variableType, path) => {
@@ -3038,16 +3067,6 @@ function treeMap(node, onNode) {
     return newNode;
 }
 
-const isExperienceEntry = (entry) => {
-    return (entry?.sys?.type === 'Entry' &&
-        !!entry.fields?.title &&
-        !!entry.fields?.slug &&
-        !!entry.fields?.componentTree &&
-        Array.isArray(entry.fields.componentTree.breakpoints) &&
-        Array.isArray(entry.fields.componentTree.children) &&
-        typeof entry.fields.componentTree.schemaVersion === 'string');
-};
-
 const getDataFromTree = (tree) => {
     let dataSource = {};
     let unboundValues = {};
@@ -3122,8 +3141,6 @@ const checkIsAssemblyNode = ({ componentId, usedComponents, }) => {
         return false;
     return usedComponents.some((usedComponent) => usedComponent.sys.id === componentId);
 };
-/** @deprecated use `checkIsAssemblyNode` instead. Will be removed with SDK v5. */
-const checkIsAssembly = checkIsAssemblyNode;
 /**
  * This check assumes that the entry is already ensured to be an experience, i.e. the
  * content type of the entry is an experience type with the necessary annotations.
@@ -3221,6 +3238,124 @@ const validateExperienceBuilderConfig = ({ locale, mode, }) => {
     }
 };
 
+const uniqueById = (arr) => {
+    const map = new Map();
+    arr.forEach((item) => map.set(item.sys.id, item));
+    return [...map.values()];
+};
+const isObject = (value) => {
+    return typeof value === 'object' && value !== null;
+};
+/**
+ * Extracts all references from an entry.
+ * Handles both: reference and multi-reference fields.
+ * Returns unique array of references (even if they repeat within the entry).
+ */
+const referencesOf = (entry, fnShouldFollowReferencesOfEntryField) => {
+    const references = [];
+    const handleArray = (fieldValue, _fieldName) => {
+        for (const item of fieldValue) {
+            if (isObject(item) && item.sys?.type === 'Link') {
+                references.push(item);
+            }
+        }
+    };
+    const handleLink = (fieldValue, _fieldName) => {
+        references.push(fieldValue);
+    };
+    for (const [fieldName, fieldValue] of Object.entries(entry.fields)) {
+        if (fnShouldFollowReferencesOfEntryField &&
+            !fnShouldFollowReferencesOfEntryField(fieldName, entry)) {
+            continue;
+        }
+        if (fieldValue === undefined) {
+            continue; // edge case when field is present on object, but is set to undefined explicitly e.g. during test mocking { myField: undefined }
+        }
+        if (Array.isArray(fieldValue)) {
+            handleArray(fieldValue);
+        }
+        else if (fieldValue !== null &&
+            isObject(fieldValue) &&
+            fieldValue.sys?.type === 'Link') {
+            handleLink(fieldValue);
+        }
+    }
+    return uniqueById(references);
+};
+// -- REFERENCE EXTRACTION UTILITIES --
+function extractReferencesFromEntriesAsIds(entries) {
+    const [uniqueEntries, uniqueAssets, uniqueReferences] = extractReferencesFromEntries(entries);
+    const entryIds = uniqueEntries.map((link) => link.sys.id);
+    const assetIds = uniqueAssets.map((link) => link.sys.id);
+    const referenceIds = uniqueReferences.map((link) => link.sys.id);
+    return [entryIds, assetIds, referenceIds];
+}
+function extractReferencesFromEntries(entries) {
+    const allReferences = entries.flatMap((entry) => referencesOf(entry));
+    const uniqueReferences = uniqueById(allReferences);
+    const uniqueAssets = uniqueReferences.filter((link) => link.sys.linkType === 'Asset');
+    const uniqueEntries = uniqueReferences.filter((link) => link.sys.linkType === 'Entry');
+    return [uniqueEntries, uniqueAssets, uniqueReferences];
+}
+
+const excludeAssets = (entity) => !isAsset(entity);
+const excludePatternEntries = (entry) => !isPatternEntry(entry);
+/**
+ * Parses experience and extracts all leaf links that are referenced from the experience.
+ * PRECONDITION: Relies on the fact that entityStore is preloaded with all dataSource
+ * entries using include=2 (meaning that up to L3 entries are already preloaded into EntitStore).
+ *
+ * The function iterates over all entries in the entityStore (assuming they can be L1, L2, L3) and
+ * over all of their references. Any references that are NOT available in the entityStore are considered
+ * "leaf references" aka "leaf links" and are returned.
+ *
+ * The EntityStore happens to contain also entities representing patterns, which we do NOT consider
+ * as entries that point to leaf links. So we don't iterate over patterns only over entries which
+ * can be used for binding.
+ */
+const extractLeafLinksReferencedFromExperience = (experience) => {
+    const assetLinks = [];
+    const entryLinks = [];
+    if (!experience.entityStore) {
+        throw new Error('Parameter `experience` should have valid `experience.entityStore` object. Without it, we cannot extract leaf links. Most likely you passed `experience` instance that was not fully fetched. Check your experience fetching logic.');
+    }
+    // We want only leaf links which can be used for binding. We use two filters:
+    // excludeAssets:         because assets do not have references, so we don't need to traverse them
+    // excludePatternEntries: because EntityStore happens to also store pattern-entries.
+    //                        Those point to other patterns, and we don't want to consider them as
+    //                        parents of leaf links pointing to actual data carrying entries used for binding.
+    const entries = experience.entityStore.entities
+        .filter(excludeAssets)
+        .filter(excludePatternEntries);
+    // We assume that ALL of the entries in the experience
+    for (const entry of entries) {
+        const references = referencesOf(entry);
+        for (const ref of references) {
+            if (isLinkToAsset(ref)) {
+                if (!experience.entityStore.getEntityFromLink(ref)) {
+                    assetLinks.push(ref);
+                }
+            }
+            else if (isLinkToEntry(ref)) {
+                if (!experience.entityStore.getEntityFromLink(ref)) {
+                    entryLinks.push(ref);
+                }
+            }
+            else {
+                console.warn(`Unexpected reference type found in entry "${entry.sys.id}": ${JSON.stringify(ref)}`);
+            }
+        }
+    }
+    const dedupedAssetLinks = uniqueById(assetLinks);
+    const dedupedEntryLinks = uniqueById(entryLinks);
+    return {
+        assetLinks: dedupedAssetLinks,
+        entryLinks: dedupedEntryLinks,
+        assetIds: dedupedAssetLinks.map((link) => link.sys.id),
+        entryIds: dedupedEntryLinks.map((link) => link.sys.id),
+    };
+};
+
 const sendMessage = (eventType, data) => {
     if (typeof window === 'undefined') {
         return;
@@ -3237,6 +3372,17 @@ const sendMessage = (eventType, data) => {
     }, '*');
 };
 
+function deepFreeze(obj) {
+    const propNames = Object.getOwnPropertyNames(obj);
+    for (const name of propNames) {
+        const value = obj[name];
+        if (value && typeof value === 'object') {
+            deepFreeze(value);
+        }
+    }
+    return Object.freeze(obj);
+}
+
 /**
  * Base Store for entities
  * Can be extended for the different loading behaviours (editor, production, ..)
@@ -3305,6 +3451,22 @@ class EntityStoreBase {
         }
         return resolvedEntity;
     }
+    getAssetById(assetId) {
+        const asset = this.assetMap.get(assetId);
+        if (!asset) {
+            console.warn(`Asset with ID "${assetId}" is not found in the store`);
+            return;
+        }
+        return asset;
+    }
+    getEntryById(entryId) {
+        const entry = this.entryMap.get(entryId);
+        if (!entry) {
+            console.warn(`Entry with ID "${entryId}" is not found in the store`);
+            return;
+        }
+        return entry;
+    }
     getEntitiesFromMap(type, ids) {
         const resolved = [];
         const missing = [];
@@ -3324,10 +3486,12 @@ class EntityStoreBase {
     }
     addEntity(entity) {
         if (isAsset(entity)) {
-            this.assetMap.set(entity.sys.id, entity);
+            // cloned and frozen
+            this.assetMap.set(entity.sys.id, deepFreeze(structuredClone(entity)));
         }
         else if (isEntry(entity)) {
-            this.entryMap.set(entity.sys.id, entity);
+            // cloned and frozen
+            this.entryMap.set(entity.sys.id, deepFreeze(structuredClone(entity)));
         }
         else {
             throw new Error(`Attempted to add an entity to the store that is neither Asset nor Entry: '${JSON.stringify(entity)}'`);
@@ -3592,7 +3756,6 @@ class EditorModeEntityStore extends EditorEntityStore {
             };
         };
         super({ entities, sendMessage, subscribe, locale, timeoutDuration: REQUEST_TIMEOUT });
-        this.locale = locale;
     }
     /**
      * This function collects and returns the list of requested entries and assets. Additionally, it checks
@@ -3820,6 +3983,89 @@ class EntityStore extends EntityStoreBase {
     }
 }
 
+class UninitializedEntityStore extends EntityStoreBase {
+    constructor() {
+        super({ entities: [], locale: 'uninitialized-locale-in-uninitialized-entity-store' });
+    }
+}
+
+const inMemoryEntitiesStore = create((set, get) => ({
+    // The UninitializedEntityStore is a placeholder instance and is here to highlight the
+    // // fact that it's not used by anything until during loading lifecycle it'sreplaced by real entity store:
+    //   - in Preview+Delivery mode: right after we fetch Expereince and it entities
+    //   - in EDITOR (VisualEditor) mode: right after the VisualEditor is async imported and initialize event happens
+    entityStore: new UninitializedEntityStore(),
+    areEntitiesFetched: false,
+    setEntitiesFetched(fetched) {
+        set({ areEntitiesFetched: fetched });
+    },
+    resolveAssetById(assetId) {
+        if (!assetId)
+            return undefined;
+        const { entityStore } = get();
+        return entityStore.getAssetById(assetId);
+    },
+    resolveEntryById(entryId) {
+        if (!entryId)
+            return undefined;
+        const { entityStore } = get();
+        return entityStore.getEntryById(entryId);
+    },
+    resolveEntity(link) {
+        if (!link)
+            return undefined;
+        const { entityStore } = get();
+        return entityStore.getEntityFromLink(link);
+    },
+    resetEntityStore(entityStore) {
+        set({
+            entityStore,
+            areEntitiesFetched: false,
+        });
+    },
+}));
+
+function maybeResolveLink(maybeLink) {
+    if (!isLink(maybeLink)) {
+        console.warn('maybeResolveLink function must receive Link shape. Provided argument does not match the Link shape: ', maybeLink);
+        return undefined;
+    }
+    return inMemoryEntitiesStore.getState().resolveEntity(maybeLink);
+}
+function maybeResolveByAssetId(assetId) {
+    return inMemoryEntitiesStore.getState().resolveAssetById(assetId);
+}
+function maybeResolveByEntryId(entryId) {
+    return inMemoryEntitiesStore.getState().resolveEntryById(entryId);
+}
+function hasEntry(entryId) {
+    return Boolean(maybeResolveByEntryId(entryId));
+}
+function hasAsset(assetId) {
+    return Boolean(maybeResolveByAssetId(assetId));
+}
+function addEntities(entities) {
+    if (!Array.isArray(entities) || entities.length === 0) {
+        return;
+    }
+    const { entityStore } = inMemoryEntitiesStore.getState();
+    const definedEntities = entities.filter(Boolean);
+    for (const entity of definedEntities) {
+        entityStore.updateEntity(entity);
+    }
+}
+const inMemoryEntities = {
+    maybeResolveLink,
+    maybeResolveByAssetId,
+    maybeResolveByEntryId,
+    hasEntry,
+    hasAsset,
+    addEntities,
+};
+const useInMemoryEntities = () => {
+    return inMemoryEntities;
+};
+
 var VisualEditorMode;
 (function (VisualEditorMode) {
     VisualEditorMode["LazyLoad"] = "lazyLoad";
@@ -3827,11 +4073,9 @@ var VisualEditorMode;
 })(VisualEditorMode || (VisualEditorMode = {}));
 
 function createExperience(options) {
+    let entityStore;
     if (typeof options === 'string') {
-        const entityStore = new EntityStore(options);
-        return {
-            entityStore,
-        };
+        entityStore = new EntityStore(options);
     }
     else {
         const { experienceEntry, referencedAssets, referencedEntries, locale } = options;
@@ -3841,15 +4085,16 @@ function createExperience(options) {
         if (!isExperienceEntry(experienceEntry)) {
             throw new Error('Provided entry is not an experience entry');
         }
-        const entityStore = new EntityStore({
+        entityStore = new EntityStore({
             experienceEntry,
             entities: [...referencedEntries, ...referencedAssets],
             locale,
         });
-        return {
-            entityStore,
-        };
     }
+    inMemoryEntitiesStore.getState().resetEntityStore(entityStore);
+    return {
+        entityStore,
+    };
 }
 // Following the API shape, we check the `sys.locale` property as we can't rely on the shape of
 // fields to determine whether it's localized or not.
@@ -4443,5 +4688,5 @@ async function fetchById({ client, experienceTypeId, id, localeCode, isEditorMod
     }
 }
 
-export { DebugLogger, DeepReference, EditorModeEntityStore, EntityStore, EntityStoreBase, MEDIA_QUERY_REGEXP, VisualEditorMode, addLocale, addMinHeightForEmptyStructures, breakpointsRegistry, buildCfStyles, buildStyleTag, buildTemplate, builtInStyles, calculateNodeDefaultHeight, checkIsAssembly, checkIsAssemblyDefinition, checkIsAssemblyEntry, checkIsAssemblyNode, columnsBuiltInStyles, containerBuiltInStyles, createExperience, debug, defineBreakpoints, defineDesignTokens, designTokensRegistry, detachExperienceStyles, disableDebug, dividerBuiltInStyles, doesMismatchMessageSchema, enableDebug, fetchAllAssets, fetchAllEntries, fetchById, fetchBySlug, fetchExperienceEntry, fetchReferencedEntities, findOutermostCoordinates, flattenDesignTokenRegistry, gatherDeepReferencesFromExperienceEntry, gatherDeepReferencesFromTree, generateRandomId, getActiveBreakpointIndex, getBreakpointRegistration, getDataFromTree, getDesignTokenRegistration, getElementCoordinates, getFallbackBreakpointIndex, getInsertionData, getTargetValueInPixels, getTemplateValue, getValueForBreakpoint, indexByBreakpoint, isAsset, isCfStyleAttribute, isComponentAllowedOnRoot, isContentfulComponent, isContentfulStructureComponent, isDeepPath, isEntry, isExperienceEntry, isLink, isLinkToAsset, isPatternComponent, isStructureWithRelativeHeight, isValidBreakpointValue, lastPathNamedSegmentEq, localizeEntity, maybePopulateDesignTokenValue, mediaQueryMatcher, optionalBuiltInStyles, parseCSSValue, parseDataSourcePathIntoFieldset, parseDataSourcePathWithL1DeepBindings, resetBreakpointsRegistry, resetDesignTokenRegistry, resolveBackgroundImageBinding, resolveHyperlinkPattern, runBreakpointsValidation, sanitizeNodeProps, sectionBuiltInStyles, sendMessage, singleColumnBuiltInStyles, stringifyCssProperties, toCSSAttribute, toMediaQuery, transformBoundContentValue, transformVisibility, treeMap, treeVisit, tryParseMessage, validateExperienceBuilderConfig };
+export { DebugLogger, DeepReference, EditorModeEntityStore, EntityStore, EntityStoreBase, MEDIA_QUERY_REGEXP, VisualEditorMode, addLocale, addMinHeightForEmptyStructures, breakpointsRegistry, buildCfStyles, buildStyleTag, buildTemplate, builtInStyles, calculateNodeDefaultHeight, checkIsAssemblyDefinition, checkIsAssemblyEntry, checkIsAssemblyNode, columnsBuiltInStyles, containerBuiltInStyles, createExperience, debug, defineBreakpoints, defineDesignTokens, designTokensRegistry, detachExperienceStyles, disableDebug, dividerBuiltInStyles, doesMismatchMessageSchema, enableDebug, extractLeafLinksReferencedFromExperience, extractReferencesFromEntries, extractReferencesFromEntriesAsIds, fetchAllAssets, fetchAllEntries, fetchById, fetchBySlug, fetchExperienceEntry, fetchReferencedEntities, findOutermostCoordinates, flattenDesignTokenRegistry, gatherDeepReferencesFromExperienceEntry, gatherDeepReferencesFromTree, generateRandomId, getActiveBreakpointIndex, getBreakpointRegistration, getDataFromTree, getDesignTokenRegistration, getElementCoordinates, getFallbackBreakpointIndex, getInsertionData, getTargetValueInPixels, getTemplateValue, getValueForBreakpoint, inMemoryEntities, inMemoryEntitiesStore, indexByBreakpoint, isArrayOfLinks, isAsset, isCfStyleAttribute, isComponentAllowedOnRoot, isContentfulComponent, isContentfulStructureComponent, isDeepPath, isEntry, isExperienceEntry, isLink, isLinkToAsset, isLinkToEntry, isPatternComponent, isPatternEntry, isStructureWithRelativeHeight, isValidBreakpointValue, lastPathNamedSegmentEq, localizeEntity, maybePopulateDesignTokenValue, mediaQueryMatcher, mergeDesignValuesByBreakpoint, optionalBuiltInStyles, parseCSSValue, parseDataSourcePathIntoFieldset, parseDataSourcePathWithL1DeepBindings, referencesOf, resetBreakpointsRegistry, resetDesignTokenRegistry, resolveBackgroundImageBinding, resolveHyperlinkPattern, runBreakpointsValidation, sanitizeNodeProps, sectionBuiltInStyles, sendMessage, singleColumnBuiltInStyles, stringifyCssProperties, toCSSAttribute, toMediaQuery, transformBoundContentValue, transformVisibility, treeMap, treeVisit, tryParseMessage, uniqueById, useInMemoryEntities, validateExperienceBuilderConfig };
 //# sourceMappingURL=index.js.map