lexical 0.32.2-nightly.20250620.0 → 0.32.2-nightly.20250624.0

package/Lexical.dev.js

@@ -191,6 +191,7 @@ const TEXT_TYPE_TO_MODE = {
   [IS_TOKEN]: 'token'
 };
 const NODE_STATE_KEY = '$';
+const PROTOTYPE_CONFIG_METHOD = '$config';
 
 /**
  * Copyright (c) Meta Platforms, Inc. and affiliates.
@@ -471,71 +472,42 @@ function initMutationObserver(editor) {
   });
 }
 
-function coerceToJSON(v) {
-  return v;
-}
-
 /**
- * The return value of {@link createState}, for use with
- * {@link $getState} and {@link $setState}.
+ * Get the value type (V) from a StateConfig
  */
-class StateConfig {
-  /** The string key used when serializing this state to JSON */
-
-  /** The parse function from the StateValueConfig passed to createState */
-
-  /**
-   * The unparse function from the StateValueConfig passed to createState,
-   * with a default that is simply a pass-through that assumes the value is
-   * JSON serializable.
-   */
-
-  /**
-   * An equality function from the StateValueConfig, with a default of
-   * Object.is.
-   */
-
-  /**
-   * The result of `stateValueConfig.parse(undefined)`, which is computed only
-   * once and used as the default value. When the current value `isEqual` to
-   * the `defaultValue`, it will not be serialized to JSON.
-   */
-
-  constructor(key, stateValueConfig) {
-    this.key = key;
-    this.parse = stateValueConfig.parse.bind(stateValueConfig);
-    this.unparse = (stateValueConfig.unparse || coerceToJSON).bind(stateValueConfig);
-    this.isEqual = (stateValueConfig.isEqual || Object.is).bind(stateValueConfig);
-    this.defaultValue = this.parse(undefined);
-  }
-}
 
 /**
- * For advanced use cases, using this type is not recommended unless
- * it is required (due to TypeScript's lack of features like
- * higher-kinded types).
- *
- * A {@link StateConfig} type with any key and any value that can be
- * used in situations where the key and value type can not be known,
- * such as in a generic constraint when working with a collection of
- * StateConfig.
- *
- * {@link StateConfigKey} and {@link StateConfigValue} will be
- * useful when this is used as a generic constraint.
+ * Get the key type (K) from a StateConfig
  */
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
 
 /**
- * Get the value type (V) from a StateConfig
+ * A value type, or an updater for that value type. For use with
+ * {@link $setState} or any user-defined wrappers around it.
  */
 
 /**
- * Get the key type (K) from a StateConfig
+ * A type alias to make it easier to define setter methods on your node class
+ *
+ * @example
+ * ```ts
+ * const fooState = createState("foo", { parse: ... });
+ * class MyClass extends TextNode {
+ *   // ...
+ *   setFoo(valueOrUpdater: StateValueOrUpdater<typeof fooState>): this {
+ *     return $setState(this, fooState, valueOrUpdater);
+ *   }
+ * }
+ * ```
  */
 
+// eslint-disable-next-line @typescript-eslint/ban-types
+
+/* eslint-disable @typescript-eslint/no-explicit-any */
+
+/* eslint-enable @typescript-eslint/no-explicit-any */
+
 /**
- * A value type, or an updater for that value type. For use with
- * {@link $setState} or any user-defined wrappers around it.
+ * The NodeState JSON produced by this LexicalNode
  */
 
 /**
@@ -579,6 +551,56 @@ class StateConfig {
  * zod, valibot, ajv, Effect, TypeBox, etc. perhaps with a wrapper function.
  */
 
+/**
+ * The return value of {@link createState}, for use with
+ * {@link $getState} and {@link $setState}.
+ */
+class StateConfig {
+  /** The string key used when serializing this state to JSON */
+
+  /** The parse function from the StateValueConfig passed to createState */
+
+  /**
+   * The unparse function from the StateValueConfig passed to createState,
+   * with a default that is simply a pass-through that assumes the value is
+   * JSON serializable.
+   */
+
+  /**
+   * An equality function from the StateValueConfig, with a default of
+   * Object.is.
+   */
+
+  /**
+   * The result of `stateValueConfig.parse(undefined)`, which is computed only
+   * once and used as the default value. When the current value `isEqual` to
+   * the `defaultValue`, it will not be serialized to JSON.
+   */
+
+  constructor(key, stateValueConfig) {
+    this.key = key;
+    this.parse = stateValueConfig.parse.bind(stateValueConfig);
+    this.unparse = (stateValueConfig.unparse || coerceToJSON).bind(stateValueConfig);
+    this.isEqual = (stateValueConfig.isEqual || Object.is).bind(stateValueConfig);
+    this.defaultValue = this.parse(undefined);
+  }
+}
+
+/**
+ * For advanced use cases, using this type is not recommended unless
+ * it is required (due to TypeScript's lack of features like
+ * higher-kinded types).
+ *
+ * A {@link StateConfig} type with any key and any value that can be
+ * used in situations where the key and value type can not be known,
+ * such as in a generic constraint when working with a collection of
+ * StateConfig.
+ *
+ * {@link StateConfigKey} and {@link StateConfigValue} will be
+ * useful when this is used as a generic constraint.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+
 /**
  * Create a StateConfig for the given string key and StateValueConfig.
  *
@@ -596,26 +618,6 @@ function createState(key, valueConfig) {
   return new StateConfig(key, valueConfig);
 }
 
-/**
- * Given two versions of a node and a stateConfig, compare their state values
- * using `$getState(nodeVersion, stateConfig, 'direct')`.
- * If the values are equal according to `stateConfig.isEqual`, return `null`,
- * otherwise return `[value, prevValue]`.
- *
- * This is useful for implementing updateDOM. Note that the `'direct'`
- * version argument is used for both nodes.
- *
- * @param node Any LexicalNode
- * @param prevNode A previous version of node
- * @param stateConfig The configuration of the state to read
- * @returns `[value, prevValue]` if changed, otherwise `null`
- */
-function $getStateChange(node, prevNode, stateConfig) {
-  const value = $getState(node, stateConfig, 'direct');
-  const prevValue = $getState(prevNode, stateConfig, 'direct');
-  return stateConfig.isEqual(value, prevValue) ? null : [value, prevValue];
-}
-
 /**
  * The accessor for working with node state. This will read the value for the
  * state on the given node, and will return `stateConfig.defaultValue` if the
@@ -646,20 +648,23 @@ function $getState(node, stateConfig, version = 'latest') {
 }
 
 /**
- * @internal
+ * Given two versions of a node and a stateConfig, compare their state values
+ * using `$getState(nodeVersion, stateConfig, 'direct')`.
+ * If the values are equal according to `stateConfig.isEqual`, return `null`,
+ * otherwise return `[value, prevValue]`.
  *
- * Register the config to this node's sharedConfigMap and throw an exception in
- * `true` when a collision is detected.
+ * This is useful for implementing updateDOM. Note that the `'direct'`
+ * version argument is used for both nodes.
+ *
+ * @param node Any LexicalNode
+ * @param prevNode A previous version of node
+ * @param stateConfig The configuration of the state to read
+ * @returns `[value, prevValue]` if changed, otherwise `null`
  */
-function $checkCollision(node, stateConfig, state) {
-  {
-    const collision = state.sharedConfigMap.get(stateConfig.key);
-    if (collision !== undefined && collision !== stateConfig) {
-      {
-        formatDevErrorMessage(`$setState: State key collision ${JSON.stringify(stateConfig.key)} detected in ${node.constructor.name} node with type ${node.getType()} and key ${node.getKey()}. Only one StateConfig with a given key should be used on a node.`);
-      }
-    }
-  }
+function $getStateChange(node, prevNode, stateConfig) {
+  const value = $getState(node, stateConfig, 'direct');
+  const prevValue = $getState(prevNode, stateConfig, 'direct');
+  return stateConfig.isEqual(value, prevValue) ? null : [value, prevValue];
 }
 
 /**
@@ -704,6 +709,70 @@ function $setState(node, stateConfig, valueOrUpdater) {
   state.updateFromKnown(stateConfig, value);
   return writable;
 }
+
+/**
+ * @internal
+ *
+ * Register the config to this node's sharedConfigMap and throw an exception in
+ * `true` when a collision is detected.
+ */
+function $checkCollision(node, stateConfig, state) {
+  {
+    const collision = state.sharedNodeState.sharedConfigMap.get(stateConfig.key);
+    if (collision !== undefined && collision !== stateConfig) {
+      {
+        formatDevErrorMessage(`$setState: State key collision ${JSON.stringify(stateConfig.key)} detected in ${node.constructor.name} node with type ${node.getType()} and key ${node.getKey()}. Only one StateConfig with a given key should be used on a node.`);
+      }
+    }
+  }
+}
+
+/**
+ * @internal
+ *
+ * Opaque state to be stored on the editor's RegisterNode for use by NodeState
+ */
+
+/**
+ * @internal
+ *
+ * Create the state to store on RegisteredNode
+ */
+function createSharedNodeState(nodeConfig) {
+  const sharedConfigMap = new Map();
+  const flatKeys = new Set();
+  for (let klass = typeof nodeConfig === 'function' ? nodeConfig : nodeConfig.replace; klass.prototype && klass.prototype.getType !== undefined; klass = Object.getPrototypeOf(klass)) {
+    const {
+      ownNodeConfig
+    } = getStaticNodeConfig(klass);
+    if (ownNodeConfig && ownNodeConfig.stateConfigs) {
+      for (const requiredStateConfig of ownNodeConfig.stateConfigs) {
+        let stateConfig;
+        if ('stateConfig' in requiredStateConfig) {
+          stateConfig = requiredStateConfig.stateConfig;
+          if (requiredStateConfig.flat) {
+            flatKeys.add(stateConfig.key);
+          }
+        } else {
+          stateConfig = requiredStateConfig;
+        }
+        sharedConfigMap.set(stateConfig.key, stateConfig);
+      }
+    }
+  }
+  return {
+    flatKeys,
+    sharedConfigMap
+  };
+}
+
+/**
+ * @internal
+ *
+ * A Map of string keys to state configurations to be shared across nodes
+ * and/or node versions.
+ */
+
 /**
  * @internal
  */
@@ -736,8 +805,7 @@ class NodeState {
    * imported but has not been parsed yet.
    *
    * It stays here until a get state requires us to parse it, and since we
-   * then know the value is safe we move it to knownState and garbage collect
-   * it at the next version.
+   * then know the value is safe we move it to knownState.
    *
    * Note that since only string keys are used here, we can only allow this
    * state to pass-through on export or on the next version since there is
@@ -750,8 +818,9 @@ class NodeState {
   /**
    * @internal
    *
-   * This sharedConfigMap is preserved across all versions of a given node and
-   * remains writable. It is how keys are resolved to configuration.
+   * This sharedNodeState is preserved across all instances of a given
+   * node type in an editor and remains writable. It is how keys are resolved
+   * to configuration.
    */
 
   /**
@@ -764,11 +833,14 @@ class NodeState {
   /**
    * @internal
    */
-  constructor(node, sharedConfigMap = new Map(), unknownState = undefined, knownState = new Map(), size = undefined) {
+  constructor(node, sharedNodeState, unknownState = undefined, knownState = new Map(), size = undefined) {
     this.node = node;
-    this.sharedConfigMap = sharedConfigMap;
+    this.sharedNodeState = sharedNodeState;
     this.unknownState = unknownState;
     this.knownState = knownState;
+    const {
+      sharedConfigMap
+    } = this.sharedNodeState;
     const computedSize = size !== undefined ? size : computeSize(sharedConfigMap, unknownState, knownState);
     {
       if (!(size === undefined || computedSize === size)) {
@@ -783,13 +855,21 @@ class NodeState {
     this.size = computedSize;
   }
 
-  /** @internal */
+  /**
+   * @internal
+   *
+   * Get the value from knownState, or parse it from unknownState
+   * if it contains the given key.
+   *
+   * Updates the sharedConfigMap when no known state is found.
+   * Updates unknownState and knownState when an unknownState is parsed.
+   */
   getValue(stateConfig) {
     const known = this.knownState.get(stateConfig);
     if (known !== undefined) {
       return known;
     }
-    this.sharedConfigMap.set(stateConfig.key, stateConfig);
+    this.sharedNodeState.sharedConfigMap.set(stateConfig.key, stateConfig);
     let parsed = stateConfig.defaultValue;
     if (this.unknownState && stateConfig.key in this.unknownState) {
       const jsonValue = this.unknownState[stateConfig.key];
@@ -824,6 +904,7 @@ class NodeState {
     const state = {
       ...this.unknownState
     };
+    const flatState = {};
     for (const [stateConfig, v] of this.knownState) {
       if (stateConfig.isEqual(v, stateConfig.defaultValue)) {
         delete state[stateConfig.key];
@@ -831,9 +912,16 @@ class NodeState {
         state[stateConfig.key] = stateConfig.unparse(v);
       }
     }
-    return undefinedIfEmpty(state) ? {
-      [NODE_STATE_KEY]: state
-    } : {};
+    for (const key of this.sharedNodeState.flatKeys) {
+      if (key in state) {
+        flatState[key] = state[key];
+        delete state[key];
+      }
+    }
+    if (undefinedIfEmpty(state)) {
+      flatState[NODE_STATE_KEY] = state;
+    }
+    return flatState;
   }
 
   /**
@@ -856,26 +944,27 @@ class NodeState {
     if (this.node === node) {
       return this;
     }
+    const {
+      sharedNodeState,
+      unknownState
+    } = this;
     const nextKnownState = new Map(this.knownState);
-    const nextUnknownState = cloneUnknownState(this.unknownState);
-    if (nextUnknownState) {
-      // Garbage collection
-      for (const stateConfig of nextKnownState.keys()) {
-        delete nextUnknownState[stateConfig.key];
-      }
-    }
-    return new NodeState(node, this.sharedConfigMap, undefinedIfEmpty(nextUnknownState), nextKnownState, this.size);
+    return new NodeState(node, sharedNodeState, parseAndPruneNextUnknownState(sharedNodeState.sharedConfigMap, nextKnownState, unknownState), nextKnownState, this.size);
   }
 
   /** @internal */
   updateFromKnown(stateConfig, value) {
     const key = stateConfig.key;
-    this.sharedConfigMap.set(key, stateConfig);
+    this.sharedNodeState.sharedConfigMap.set(key, stateConfig);
     const {
       knownState,
       unknownState
     } = this;
     if (!(knownState.has(stateConfig) || unknownState && key in unknownState)) {
+      if (unknownState) {
+        delete unknownState[key];
+        this.unknownState = undefinedIfEmpty(unknownState);
+      }
       this.size++;
     }
     knownState.set(stateConfig, value);
@@ -896,7 +985,7 @@ class NodeState {
    * @param v The unknown value from an UnknownStateRecord
    */
   updateFromUnknown(k, v) {
-    const stateConfig = this.sharedConfigMap.get(k);
+    const stateConfig = this.sharedNodeState.sharedConfigMap.get(k);
     if (stateConfig) {
       this.updateFromKnown(stateConfig, stateConfig.parse(v));
     } else {
@@ -931,15 +1020,77 @@ class NodeState {
     // the size starts at the number of known keys
     // and will be updated as we traverse the new state
     this.size = knownState.size;
-    this.unknownState = {};
+    this.unknownState = undefined;
     if (unknownState) {
       for (const [k, v] of Object.entries(unknownState)) {
         this.updateFromUnknown(k, v);
       }
     }
-    this.unknownState = undefinedIfEmpty(this.unknownState);
   }
 }
+
+/**
+ * @internal
+ *
+ * Only for direct use in very advanced integrations, such as lexical-yjs.
+ * Typically you would only use {@link createState}, {@link $getState}, and
+ * {@link $setState}. This is effectively the preamble for {@link $setState}.
+ */
+function $getWritableNodeState(node) {
+  const writable = node.getWritable();
+  const state = writable.__state ? writable.__state.getWritable(writable) : new NodeState(writable, $getSharedNodeState(writable));
+  writable.__state = state;
+  return state;
+}
+
+/**
+ * @internal
+ *
+ * Get the SharedNodeState for a node on this editor
+ */
+function $getSharedNodeState(node) {
+  return getRegisteredNodeOrThrow($getEditor(), node.getType()).sharedNodeState;
+}
+
+/**
+ * @internal
+ *
+ * This is used to implement LexicalNode.updateFromJSON and is
+ * not intended to be exported from the package.
+ *
+ * @param node any LexicalNode
+ * @param unknownState undefined or a serialized State
+ * @returns A writable version of node, with the state set.
+ */
+function $updateStateFromJSON(node, unknownState) {
+  const writable = node.getWritable();
+  if (unknownState || writable.__state) {
+    $getWritableNodeState(node).updateFromJSON(unknownState);
+  }
+  return writable;
+}
+
+/**
+ * @internal
+ *
+ * Return true if the two nodes have equivalent NodeState, to be used
+ * to determine when TextNode are being merged, not a lot of use cases
+ * otherwise.
+ */
+function nodeStatesAreEquivalent(a, b) {
+  if (a === b) {
+    return true;
+  }
+  if (a && b && a.size !== b.size) {
+    return false;
+  }
+  const keys = new Set();
+  return !(a && hasUnequalMapEntry(keys, a, b) || b && hasUnequalMapEntry(keys, b, a) || a && hasUnequalRecordEntry(keys, a, b) || b && hasUnequalRecordEntry(keys, b, a));
+}
+
+/**
+ * Compute the number of distinct keys that will be in a NodeState
+ */
 function computeSize(sharedConfigMap, unknownState, knownState) {
   let size = knownState.size;
   if (unknownState) {
@@ -954,6 +1105,8 @@ function computeSize(sharedConfigMap, unknownState, knownState) {
 }
 
 /**
+ * @internal
+ *
  * Return obj if it is an object with at least one property, otherwise
  * return undefined.
  */
@@ -967,95 +1120,93 @@ function undefinedIfEmpty(obj) {
 }
 
 /**
- * Return undefined if unknownState is undefined or an empty object,
- * otherwise return a shallow clone of it.
+ * @internal
+ *
+ * Cast the given v to unknown
  */
-function cloneUnknownState(unknownState) {
-  return undefinedIfEmpty(unknownState) && {
-    ...unknownState
-  };
+function coerceToJSON(v) {
+  return v;
 }
 
 /**
  * @internal
  *
- * Only for direct use in very advanced integrations, such as lexical-yjs.
- * Typically you would only use {@link createState}, {@link $getState}, and
- * {@link $setState}. This is effectively the preamble for {@link $setState}.
+ * Parse all knowable values in an UnknownStateRecord into nextKnownState
+ * and return the unparsed values in a new UnknownStateRecord. Returns
+ * undefined if no unknown values remain.
  */
-function $getWritableNodeState(node) {
-  const writable = node.getWritable();
-  const state = writable.__state ? writable.__state.getWritable(writable) : new NodeState(writable);
-  writable.__state = state;
-  return state;
+function parseAndPruneNextUnknownState(sharedConfigMap, nextKnownState, unknownState) {
+  let nextUnknownState = undefined;
+  if (unknownState) {
+    for (const [k, v] of Object.entries(unknownState)) {
+      const stateConfig = sharedConfigMap.get(k);
+      if (stateConfig) {
+        if (!nextKnownState.has(stateConfig)) {
+          nextKnownState.set(stateConfig, stateConfig.parse(v));
+        }
+      } else {
+        nextUnknownState = nextUnknownState || {};
+        nextUnknownState[k] = v;
+      }
+    }
+  }
+  return nextUnknownState;
 }
 
 /**
  * @internal
  *
- * This is used to implement LexicalNode.updateFromJSON and is
- * not intended to be exported from the package.
+ * Compare each entry of sourceState.knownState that is not in keys to
+ * otherState (or the default value if otherState is undefined.
+ * Note that otherState will return the defaultValue as well if it
+ * has never been set. Any checked entry's key will be added to keys.
  *
- * @param node any LexicalNode
- * @param unknownState undefined or a serialized State
- * @returns A writable version of node, with the state set.
+ * @returns true if any difference is found, false otherwise
  */
-function $updateStateFromJSON(node, unknownState) {
-  const writable = node.getWritable();
-  if (unknownState || writable.__state) {
-    $getWritableNodeState(node).updateFromJSON(unknownState);
+function hasUnequalMapEntry(keys, sourceState, otherState) {
+  for (const [stateConfig, value] of sourceState.knownState) {
+    if (keys.has(stateConfig.key)) {
+      continue;
+    }
+    keys.add(stateConfig.key);
+    const otherValue = otherState ? otherState.getValue(stateConfig) : stateConfig.defaultValue;
+    if (otherValue !== value && !stateConfig.isEqual(otherValue, value)) {
+      return true;
+    }
   }
-  return writable;
+  return false;
 }
 
 /**
  * @internal
  *
- * Return true if the two nodes have equivalent NodeState, to be used
- * to determine when TextNode are being merged, not a lot of use cases
- * otherwise.
+ * Compare each entry of sourceState.unknownState that is not in keys to
+ * otherState.unknownState (or undefined if otherState is undefined).
+ * Any checked entry's key will be added to keys.
+ *
+ * Notably since we have already checked hasUnequalMapEntry on both sides,
+ * we do not do any parsing or checking of knownState.
+ *
+ * @returns true if any difference is found, false otherwise
  */
-function $nodeStatesAreEquivalent(a, b) {
-  if (a === b) {
-    return true;
-  }
-  if (a && b && a.size !== b.size) {
-    return false;
-  }
-  const keys = new Set();
-  const hasUnequalMapEntry = (sourceState, otherState) => {
-    for (const [stateConfig, value] of sourceState.knownState) {
-      if (keys.has(stateConfig.key)) {
+function hasUnequalRecordEntry(keys, sourceState, otherState) {
+  const {
+    unknownState
+  } = sourceState;
+  const otherUnknownState = otherState ? otherState.unknownState : undefined;
+  if (unknownState) {
+    for (const [key, value] of Object.entries(unknownState)) {
+      if (keys.has(key)) {
         continue;
       }
-      keys.add(stateConfig.key);
-      const otherValue = otherState ? otherState.getValue(stateConfig) : stateConfig.defaultValue;
-      if (otherValue !== value && !stateConfig.isEqual(otherValue, value)) {
+      keys.add(key);
+      const otherValue = otherUnknownState ? otherUnknownState[key] : undefined;
+      if (value !== otherValue) {
         return true;
       }
     }
-    return false;
-  };
-  const hasUnequalRecordEntry = (sourceState, otherState) => {
-    const {
-      unknownState
-    } = sourceState;
-    const otherUnknownState = otherState ? otherState.unknownState : undefined;
-    if (unknownState) {
-      for (const [key, value] of Object.entries(unknownState)) {
-        if (keys.has(key)) {
-          continue;
-        }
-        keys.add(key);
-        const otherValue = otherUnknownState ? otherUnknownState[key] : undefined;
-        if (value !== otherValue) {
-          return true;
-        }
-      }
-    }
-    return false;
-  };
-  return !(a && hasUnequalMapEntry(a, b) || b && hasUnequalMapEntry(b, a) || a && hasUnequalRecordEntry(a, b) || b && hasUnequalRecordEntry(b, a));
+  }
+  return false;
 }
 
 /**
@@ -1075,7 +1226,7 @@ function $canSimpleTextNodesBeMerged(node1, node2) {
   const node2Style = node2.__style;
   const node1State = node1.__state;
   const node2State = node2.__state;
-  return (node1Mode === null || node1Mode === node2Mode) && (node1Format === null || node1Format === node2Format) && (node1Style === null || node1Style === node2Style) && (node1.__state === null || node1State === node2State || $nodeStatesAreEquivalent(node1State, node2State));
+  return (node1Mode === null || node1Mode === node2Mode) && (node1Format === null || node1Format === node2Format) && (node1Style === null || node1Style === node2Style) && (node1.__state === null || node1State === node2State || nodeStatesAreEquivalent(node1State, node2State));
 }
 function $mergeTextNodes(node1, node2) {
   const writableNode1 = node1.mergeWithSibling(node2);
@@ -2915,6 +3066,59 @@ function markCollapsedSelectionFormat(format, style, offset, key, timeStamp) {
  * The base type for all serialized nodes
  */
 
+/**
+ * EXPERIMENTAL
+ * The configuration of a node returned by LexicalNode.$config()
+ *
+ * @example
+ * ```ts
+ * class CustomText extends TextNode {
+ *   $config() {
+ *     return this.config('custom-text', {extends: TextNode}};
+ *   }
+ * }
+ * ```
+ */
+
+/**
+ * This is the type of LexicalNode.$config() that can be
+ * overridden by subclasses.
+ */
+
+/**
+ * Used to extract the node and type from a StaticNodeConfigRecord
+ */
+
+/**
+ * Any StaticNodeConfigValue (for generics and collections)
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+
+/**
+ * @internal
+ *
+ * This is the more specific type than BaseStaticNodeConfig that a subclass
+ * should return from $config()
+ */
+
+/**
+ * Extract the type from a node based on its $config
+ *
+ * @example
+ * ```ts
+ * type TextNodeType = GetStaticNodeType<TextNode>;
+ *      // ? 'text'
+ * ```
+ */
+
+/**
+ * The most precise type we can infer for the JSON that will
+ * be produced by T.exportJSON().
+ *
+ * Do not use this for the return type of T.exportJSON()! It must be
+ * a more generic type to be compatible with subclassing.
+ */
+
 /**
  * Omit the children, type, and version properties from the given SerializedLexicalNode definition.
  */
@@ -2959,6 +3163,14 @@ function $removeNode(nodeToRemove, restoreSelection, preserveEmptyParent) {
     parent.selectEnd();
   }
 }
+/**
+ * An identity function that will infer the type of DOM nodes
+ * based on tag names to make it easier to construct a
+ * DOMConversionMap.
+ */
+function buildImportMap(importMap) {
+  return importMap;
+}
 class LexicalNode {
   // Allow us to look up the type including static props
 
@@ -3004,6 +3216,41 @@ class LexicalNode {
     }
   }
 
+  /**
+   * Override this to implement the new static node configuration protocol,
+   * this method is called directly on the prototype and must not depend
+   * on anything initialized in the constructor. Generally it should be
+   * a trivial implementation.
+   *
+   * @example
+   * ```ts
+   * class MyNode extends TextNode {
+   *   $config() {
+   *     return this.config('my-node', {extends: TextNode});
+   *   }
+   * }
+   * ```
+   */
+  $config() {
+    return {};
+  }
+
+  /**
+   * This is a convenience method for $config that
+   * aids in type inference. See {@link LexicalNode.$config}
+   * for example usage.
+   */
+  config(type, config) {
+    const parentKlass = config.extends || Object.getPrototypeOf(this.constructor);
+    Object.assign(config, {
+      extends: parentKlass,
+      type
+    });
+    return {
+      [type]: config
+    };
+  }
+
   /**
    * Perform any state updates on the clone of prevNode that are not already
    * handled by the constructor call in the static clone method. If you have
@@ -3929,7 +4176,7 @@ class LexicalNode {
   }
 }
 function errorOnTypeKlassMismatch(type, klass) {
-  const registeredNode = getActiveEditor()._nodes.get(type);
+  const registeredNode = getRegisteredNode(getActiveEditor(), type);
   // Common error - split in its own invariant
   if (registeredNode === undefined) {
     {
@@ -7913,6 +8160,7 @@ function parseEditorState(serializedEditorState, editor, updateFn) {
   activeEditorState = editorState;
   isReadOnlyMode = false;
   activeEditor = editor;
+  setPendingNodeToClone(null);
   try {
     const registeredNodes = editor._nodes;
     const serializedNode = serializedEditorState.root;
@@ -8284,6 +8532,7 @@ function $beginUpdate(editor, updateFn, options) {
   editor._updating = true;
   activeEditor = editor;
   const headless = editor._headless || editor.getRootElement() === null;
+  setPendingNodeToClone(null);
   try {
     if (editorStateWasCloned) {
       if (headless) {
@@ -9593,6 +9842,10 @@ function $isParagraphNode(node) {
 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 
+/**
+ * A LexicalNode class or LexicalNodeReplacement configuration
+ */
+
 const DEFAULT_SKIP_INITIALIZATION = false;
 
 /**
@@ -9728,40 +9981,37 @@ function createEditor(editorConfig) {
         replace = options.with;
         replaceWithKlass = options.withKlass || null;
       }
+      const {
+        ownNodeConfig
+      } = getStaticNodeConfig(klass);
       // Ensure custom nodes implement required methods and replaceWithKlass is instance of base klass.
       {
         // ArtificialNode__DO_NOT_USE can get renamed, so we use the type
-        const nodeType = Object.prototype.hasOwnProperty.call(klass, 'getType') && klass.getType();
         const name = klass.name;
+        const nodeType = hasOwn(klass, 'getType') && klass.getType();
         if (replaceWithKlass) {
           if (!(replaceWithKlass.prototype instanceof klass)) {
             formatDevErrorMessage(`${replaceWithKlass.name} doesn't extend the ${name}`);
           }
+        } else if (replace) {
+          console.warn(`Override for ${name} specifies 'replace' without 'withKlass'. 'withKlass' will be required in a future version.`);
         }
         if (name !== 'RootNode' && nodeType !== 'root' && nodeType !== 'artificial') {
           const proto = klass.prototype;
           ['getType', 'clone'].forEach(method => {
-            // eslint-disable-next-line no-prototype-builtins
-            if (!klass.hasOwnProperty(method)) {
+            if (!hasOwn(klass, method)) {
               console.warn(`${name} must implement static "${method}" method`);
             }
           });
-          if (
-          // eslint-disable-next-line no-prototype-builtins
-          !klass.hasOwnProperty('importDOM') &&
-          // eslint-disable-next-line no-prototype-builtins
-          klass.hasOwnProperty('exportDOM')) {
+          if (!hasOwn(klass, 'importDOM') && hasOwn(klass, 'exportDOM')) {
             console.warn(`${name} should implement "importDOM" if using a custom "exportDOM" method to ensure HTML serialization (important for copy & paste) works as expected`);
           }
           if ($isDecoratorNode(proto)) {
-            // eslint-disable-next-line no-prototype-builtins
-            if (!proto.hasOwnProperty('decorate')) {
+            if (!hasOwn(proto, 'decorate')) {
               console.warn(`${proto.constructor.name} must implement "decorate" method`);
             }
           }
-          if (
-          // eslint-disable-next-line no-prototype-builtins
-          !klass.hasOwnProperty('importJSON')) {
+          if (!hasOwn(klass, 'importJSON')) {
             console.warn(`${name} should implement "importJSON" method to ensure JSON and default HTML serialization works as expected`);
           }
         }
@@ -9769,6 +10019,9 @@ function createEditor(editorConfig) {
       const type = klass.getType();
       const transform = klass.transform();
       const transforms = new Set();
+      if (ownNodeConfig && ownNodeConfig.$transform) {
+        transforms.add(ownNodeConfig.$transform);
+      }
       if (transform !== null) {
         transforms.add(transform);
       }
@@ -9777,6 +10030,7 @@ function createEditor(editorConfig) {
         klass,
         replace,
         replaceWithKlass,
+        sharedNodeState: createSharedNodeState(nodes[i]),
         transforms
       });
     }
@@ -10361,14 +10615,6 @@ class LexicalEditor {
    * where Lexical editor state can be safely mutated.
    * @param updateFn - A function that has access to writable editor state.
    * @param options - A bag of options to control the behavior of the update.
-   * @param options.onUpdate - A function to run once the update is complete.
-   * Useful for synchronizing updates in some cases.
-   * @param options.skipTransforms - Setting this to true will suppress all node
-   * transforms for this update cycle.
-   * @param options.tag - A tag to identify this update, in an update listener, for instance.
-   * Some tags are reserved by the core and control update behavior in different ways.
-   * @param options.discrete - If true, prevents this update from being batched, forcing it to
-   * run synchronously.
    */
   update(updateFn, options) {
     updateEditor(this, updateFn, options);
@@ -10382,8 +10628,6 @@ class LexicalEditor {
    *
    * @param callbackFn - A function to run after the editor is focused.
    * @param options - A bag of options
-   * @param options.defaultSelection - Where to move selection when the editor is
-   * focused. Can be rootStart, rootEnd, or undefined. Defaults to rootEnd.
    */
   focus(callbackFn, options = {}) {
     const rootElement = this._rootElement;
@@ -10467,8 +10711,17 @@ class LexicalEditor {
     };
   }
 }
-LexicalEditor.version = "0.32.2-nightly.20250620.0+dev.cjs";
+LexicalEditor.version = "0.32.2-nightly.20250624.0+dev.cjs";
 
+let pendingNodeToClone = null;
+function setPendingNodeToClone(pendingNode) {
+  pendingNodeToClone = pendingNode;
+}
+function getPendingNodeToClone() {
+  const node = pendingNodeToClone;
+  pendingNodeToClone = null;
+  return node;
+}
 let keyCounter = 1;
 function resetRandomKey() {
   keyCounter = 1;
@@ -10476,8 +10729,12 @@ function resetRandomKey() {
 function generateRandomKey() {
   return '' + keyCounter++;
 }
+
+/**
+ * @internal
+ */
 function getRegisteredNodeOrThrow(editor, nodeType) {
-  const registeredNode = editor._nodes.get(nodeType);
+  const registeredNode = getRegisteredNode(editor, nodeType);
   if (registeredNode === undefined) {
     {
       formatDevErrorMessage(`registeredNode: Type ${nodeType} not found`);
@@ -10485,6 +10742,13 @@ function getRegisteredNodeOrThrow(editor, nodeType) {
   }
   return registeredNode;
 }
+
+/**
+ * @internal
+ */
+function getRegisteredNode(editor, nodeType) {
+  return editor._nodes.get(nodeType);
+}
 const scheduleMicroTask = typeof queueMicrotask === 'function' ? queueMicrotask : fn => {
   // No window prefix intended (#1400)
   Promise.resolve().then(fn);
@@ -10610,9 +10874,11 @@ function $isLeafNode(node) {
   return $isTextNode(node) || $isLineBreakNode(node) || $isDecoratorNode(node);
 }
 function $setNodeKey(node, existingKey) {
+  const pendingNode = getPendingNodeToClone();
+  existingKey = existingKey || pendingNode && pendingNode.__key;
   if (existingKey != null) {
     {
-      errorOnNodeKeyConstructorMismatch(node, existingKey);
+      errorOnNodeKeyConstructorMismatch(node, existingKey, pendingNode);
     }
     node.__key = existingKey;
     return;
@@ -10633,13 +10899,18 @@ function $setNodeKey(node, existingKey) {
   editor._dirtyType = HAS_DIRTY_NODES;
   node.__key = key;
 }
-function errorOnNodeKeyConstructorMismatch(node, existingKey) {
+function errorOnNodeKeyConstructorMismatch(node, existingKey, pendingNode) {
   const editorState = internalGetActiveEditorState();
   if (!editorState) {
     // tests expect to be able to do this kind of clone without an active editor state
     return;
   }
   const existingNode = editorState._nodeMap.get(existingKey);
+  if (pendingNode) {
+    if (!(existingKey === pendingNode.__key)) {
+      formatDevErrorMessage(`Lexical node with constructor ${node.constructor.name} (type ${node.getType()}) has an incorrect clone implementation, got ${String(existingKey)} for nodeKey when expecting ${pendingNode.__key}`);
+    }
+  }
   if (existingNode && existingNode.constructor !== node.constructor) {
     // Lifted condition to if statement because the inverted logic is a bit confusing
     if (node.constructor.name !== existingNode.constructor.name) {
@@ -11519,8 +11790,8 @@ function $copyNode(node) {
 }
 function $applyNodeReplacement(node) {
   const editor = getActiveEditor();
-  const nodeType = node.constructor.getType();
-  const registeredNode = editor._nodes.get(nodeType);
+  const nodeType = node.getType();
+  const registeredNode = getRegisteredNode(editor, nodeType);
   if (!(registeredNode !== undefined)) {
     formatDevErrorMessage(`$applyNodeReplacement node ${node.constructor.name} with type ${nodeType} must be registered to the editor. You can do this by passing the node class via the "nodes" array in the editor config.`);
   }
@@ -11844,7 +12115,7 @@ function computeTypeToNodeMap(editorState) {
  * do not try and use this function to duplicate or copy an existing node.
  *
  * Does not mutate the EditorState.
- * @param node - The node to be cloned.
+ * @param latestNode - The node to be cloned.
  * @returns The clone of the node.
  */
 function $cloneWithProperties(latestNode) {
@@ -11888,6 +12159,102 @@ function isDOMUnmanaged(elementDom) {
   return el.__lexicalUnmanaged === true;
 }
 
+/**
+ * @internal
+ *
+ * Object.hasOwn ponyfill
+ */
+function hasOwn(o, k) {
+  return Object.prototype.hasOwnProperty.call(o, k);
+}
+
+/** @internal */
+function isAbstractNodeClass(klass) {
+  return klass === DecoratorNode || klass === ElementNode || klass === Object.getPrototypeOf(ElementNode);
+}
+
+/** @internal */
+function getStaticNodeConfig(klass) {
+  const nodeConfigRecord = PROTOTYPE_CONFIG_METHOD in klass.prototype ? klass.prototype[PROTOTYPE_CONFIG_METHOD]() : undefined;
+  const isAbstract = isAbstractNodeClass(klass);
+  const nodeType = !isAbstract && hasOwn(klass, 'getType') ? klass.getType() : undefined;
+  let ownNodeConfig;
+  let ownNodeType = nodeType;
+  if (nodeConfigRecord) {
+    if (nodeType) {
+      ownNodeConfig = nodeConfigRecord[nodeType];
+    } else {
+      for (const [k, v] of Object.entries(nodeConfigRecord)) {
+        ownNodeType = k;
+        ownNodeConfig = v;
+      }
+    }
+  }
+  if (!isAbstract && ownNodeType) {
+    if (!hasOwn(klass, 'getType')) {
+      klass.getType = () => ownNodeType;
+    }
+    if (!hasOwn(klass, 'clone')) {
+      {
+        if (!(klass.length === 0)) {
+          formatDevErrorMessage(`${klass.name} (type ${ownNodeType}) must implement a static clone method since its constructor has ${String(klass.length)} required arguments (expecting 0). Use an explicit default in the first argument of your constructor(prop: T=X, nodeKey?: NodeKey).`);
+        }
+      }
+      klass.clone = prevNode => {
+        setPendingNodeToClone(prevNode);
+        return new klass();
+      };
+    }
+    if (!hasOwn(klass, 'importJSON')) {
+      {
+        if (!(klass.length === 0)) {
+          formatDevErrorMessage(`${klass.name} (type ${ownNodeType}) must implement a static importJSON method since its constructor has ${String(klass.length)} required arguments (expecting 0). Use an explicit default in the first argument of your constructor(prop: T=X, nodeKey?: NodeKey).`);
+        }
+      }
+      klass.importJSON = ownNodeConfig && ownNodeConfig.$importJSON || (serializedNode => new klass().updateFromJSON(serializedNode));
+    }
+    if (!hasOwn(klass, 'importDOM') && ownNodeConfig) {
+      const {
+        importDOM
+      } = ownNodeConfig;
+      if (importDOM) {
+        klass.importDOM = () => importDOM;
+      }
+    }
+  }
+  return {
+    ownNodeConfig,
+    ownNodeType
+  };
+}
+
+/**
+ * Create an node from its class.
+ *
+ * Note that this will directly construct the final `withKlass` node type,
+ * and will ignore the deprecated `with` functions. This allows `$create` to
+ * skip any intermediate steps where the replaced node would be created and
+ * then immediately discarded (once per configured replacement of that node).
+ *
+ * This does not support any arguments to the constructor.
+ * Setters can be used to initialize your node, and they can
+ * be chained. You can of course write your own mutliple-argument functions
+ * to wrap that.
+ *
+ * @example
+ * ```ts
+ * function $createTokenText(text: string): TextNode {
+ *   return $create(TextNode).setTextContent(text).setMode('token');
+ * }
+ * ```
+ */
+function $create(klass) {
+  const editor = $getEditor();
+  errorOnReadOnly();
+  const registeredNode = editor.resolveRegisteredNodeAfterReplacements(editor.getRegisteredNode(klass));
+  return new registeredNode.klass();
+}
+
 /**
  * The direction of a caret, 'next' points towards the end of the document
  * and 'previous' points towards the beginning
@@ -12862,7 +13229,7 @@ function $isCaretAttached(caret) {
  * blocks then the remaining contents of the later block will be merged with
  * the earlier block.
  *
- * @param range The range to remove text and nodes from
+ * @param initialRange The range to remove text and nodes from
  * @param sliceMode If 'preserveEmptyTextPointCaret' it will leave an empty TextPointCaret at the anchor for insert if one exists, otherwise empty slices will be removed
  * @returns The new collapsed range (biased towards the earlier node)
  */
@@ -13136,8 +13503,9 @@ function $getChildCaretAtIndex(parent, index, direction) {
  * R -> P -> T1, T2
  *   -> P2
  * returns T2 for node T1, P2 for node T2, and null for node P2.
- * @param node LexicalNode.
- * @returns An array (tuple) containing the found Lexical node and the depth difference, or null, if this node doesn't exist.
+ * @param startCaret The initial caret
+ * @param rootMode The root mode, 'root' ('default') or 'shadowRoot'
+ * @returns An array (tuple) containing the found caret and the depth difference, or null, if this node doesn't exist.
  */
 function $getAdjacentSiblingOrParentSiblingCaret(startCaret, rootMode = 'root') {
   let depthDiff = 0;
@@ -13237,6 +13605,7 @@ exports.$caretRangeFromSelection = $caretRangeFromSelection;
 exports.$cloneWithProperties = $cloneWithProperties;
 exports.$comparePointCaretNext = $comparePointCaretNext;
 exports.$copyNode = $copyNode;
+exports.$create = $create;
 exports.$createLineBreakNode = $createLineBreakNode;
 exports.$createNodeSelection = $createNodeSelection;
 exports.$createParagraphNode = $createParagraphNode;
@@ -13393,8 +13762,10 @@ exports.TEXT_TYPE_TO_FORMAT = TEXT_TYPE_TO_FORMAT;
 exports.TabNode = TabNode;
 exports.TextNode = TextNode;
 exports.UNDO_COMMAND = UNDO_COMMAND;
+exports.buildImportMap = buildImportMap;
 exports.createCommand = createCommand;
 exports.createEditor = createEditor;
+exports.createSharedNodeState = createSharedNodeState;
 exports.createState = createState;
 exports.flipDirection = flipDirection;
 exports.getDOMOwnerDocument = getDOMOwnerDocument;
@@ -13403,6 +13774,8 @@ exports.getDOMSelectionFromTarget = getDOMSelectionFromTarget;
 exports.getDOMTextNode = getDOMTextNode;
 exports.getEditorPropertyFromDOMNode = getEditorPropertyFromDOMNode;
 exports.getNearestEditorFromDOMNode = getNearestEditorFromDOMNode;
+exports.getRegisteredNode = getRegisteredNode;
+exports.getRegisteredNodeOrThrow = getRegisteredNodeOrThrow;
 exports.isBlockDomNode = isBlockDomNode;
 exports.isCurrentlyReadOnlyMode = isCurrentlyReadOnlyMode;
 exports.isDOMDocumentNode = isDOMDocumentNode;