@lexical/html 0.44.1-nightly.20260519.0 → 0.45.0

package/dist/import/types.d.ts

@@ -0,0 +1,394 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ */
+import type { DOMImportContextSymbol } from '../constants';
+import type { AnyContextConfigPairOrUpdater, ContextConfig, ContextRecord } from '../types';
+import type { CompiledOverlayRules } from './defineOverlayRules';
+import type { LexicalNode } from 'lexical';
+/**
+ * Phantom-typed branding so consumers cannot construct or mutate a
+ * {@link CompiledSelector} directly; the only way to obtain one is via the
+ * {@link sel} builder or {@link parseSelector}. The actual runtime shape is
+ * an internal implementation detail (see `./sel`).
+ *
+ * @experimental
+ */
+export declare const NodeBrand: unique symbol;
+/** @experimental */
+export declare const CaptureBrand: unique symbol;
+/**
+ * An opaque, compiled selector used as the `match` field of a
+ * {@link DOMImportRule}. The two phantom type parameters carry the matched
+ * Node subtype (`N`) and a record of named regex captures (`C`) so the
+ * importer body gets correctly-typed `ctx` and `node` arguments without
+ * casts.
+ *
+ * @experimental
+ */
+export interface CompiledSelector<N extends Node = Node, C extends Record<string, RegExpMatchArray> = Record<string, RegExpMatchArray>> {
+    readonly [NodeBrand]?: N;
+    readonly [CaptureBrand]?: C;
+}
+/**
+ * The Node subtype matched by a selector (e.g. `HTMLAnchorElement` for
+ * `sel.tag('a')`, `Text` for `sel.text()`).
+ *
+ * @experimental
+ */
+export type NodeOfSelector<S> = S extends CompiledSelector<infer N, Record<string, RegExpMatchArray>> ? N : Node;
+/**
+ * The named-capture map for a selector.
+ *
+ * @experimental
+ */
+export type CapturesOfSelector<S> = S extends CompiledSelector<Node, infer C> ? C : Record<string, never>;
+/**
+ * Options bag for {@link ElementSelectorBuilder.attr} when the value is a
+ * regex. Future options will be added here without breaking existing
+ * call-sites.
+ *
+ * @experimental
+ */
+export interface AttrMatchOptions<K extends string = string> {
+    /**
+     * If provided, the {@link RegExpMatchArray} from the successful match is
+     * stored on `ctx.captures[capture]` for the importer to consume — saving
+     * a second regex execution.
+     */
+    readonly capture?: K;
+}
+/**
+ * Options bag for {@link ElementSelectorBuilder.styleAny} when the value is a
+ * regex. See {@link AttrMatchOptions} for capture semantics.
+ *
+ * @experimental
+ */
+export interface StyleMatchOptions<K extends string = string> {
+    readonly capture?: K;
+}
+/**
+ * Fluent builder for an element selector. The two type parameters carry the
+ * matched element type and the named-capture map; each call refines them.
+ *
+ * The builder itself implements {@link CompiledSelector} so it can be used
+ * directly as the `match` field of a rule — no `.build()` call needed.
+ *
+ * @experimental
+ */
+export interface ElementSelectorBuilder<E extends HTMLElement, C extends Record<string, RegExpMatchArray> = Record<string, never>> extends CompiledSelector<E, C> {
+    /** Require every listed class to be present on the element. */
+    classAll(...classes: readonly string[]): ElementSelectorBuilder<E, C>;
+    /** Require at least one of the listed classes to be present. */
+    classAny(...classes: readonly string[]): ElementSelectorBuilder<E, C>;
+    /** Require the attribute to be present (any value). */
+    attr(name: string, value: true): ElementSelectorBuilder<E, C>;
+    /** Require the attribute to equal the given string. */
+    attr(name: string, value: string): ElementSelectorBuilder<E, C>;
+    /**
+     * Require the attribute to match the given regex. With
+     * `{capture: 'name'}` the match result is exposed on
+     * `ctx.captures.name`.
+     */
+    attr<const O extends AttrMatchOptions>(name: string, value: RegExp, options?: O): ElementSelectorBuilder<E, O extends {
+        capture: infer K;
+    } ? C & Record<K & string, RegExpMatchArray> : C>;
+    /** Require the inline-style declaration to equal `value`. */
+    styleAny(prop: string, value: string): ElementSelectorBuilder<E, C>;
+    /** Require the inline-style declaration to match `value`. */
+    styleAny<const O extends StyleMatchOptions>(prop: string, value: RegExp, options?: O): ElementSelectorBuilder<E, O extends {
+        capture: infer K;
+    } ? C & Record<K & string, RegExpMatchArray> : C>;
+}
+/**
+ * Argument to {@link DOMImportContext.branch} / `$importChildren({context})`
+ * — see {@link ContextConfigPair} / {@link ContextConfigUpdater}.
+ *
+ * @experimental
+ */
+export type ImportContextPairOrUpdater = AnyContextConfigPairOrUpdater<typeof DOMImportContextSymbol>;
+/**
+ * A typed context-state key for the import pipeline. Create with
+ * {@link createImportState}.
+ *
+ * @experimental
+ */
+export type ImportStateConfig<V> = ContextConfig<typeof DOMImportContextSymbol, V>;
+/**
+ * A mutable, document-order-shared store for the import pipeline. Lets a
+ * rule visited early in the document write information that rules visited
+ * later can read — e.g. parse `<style>` or `<meta>` and influence
+ * subsequent matching.
+ *
+ * Implemented as the root-layer {@link ContextRecord} of the import walk:
+ * `ctx.session.set(cfg, v)` mutates the slot on that root record, and
+ * every unshadowed `ctx.get(cfg)` read in any branch picks it up. A
+ * `$importChildren({context: [...]})` branch that explicitly writes the
+ * same slot shadows the session value for the duration of that branch.
+ *
+ * @experimental
+ */
+export interface ImportSession {
+    /** Read the current value, returning the config's default if unset. */
+    get<V>(cfg: ImportStateConfig<V>): V;
+    /** Write `value` into the slot. */
+    set<V>(cfg: ImportStateConfig<V>, value: V): void;
+    /** Read-modify-write. */
+    update<V>(cfg: ImportStateConfig<V>, updater: (prev: V) => V): void;
+    /** Returns `true` if the slot has been written since session creation. */
+    has<V>(cfg: ImportStateConfig<V>): boolean;
+}
+/**
+ * Context exposed to a rule's `$import` function. Mirrors the existing render
+ * context (see {@link RenderContext}) but is import-scoped.
+ *
+ * @experimental
+ */
+export interface DOMImportContext<C extends Record<string, RegExpMatchArray> = Record<string, never>> {
+    /** Captures from this rule's selector. Fresh per rule invocation. */
+    readonly captures: Readonly<C>;
+    /**
+     * Mutable, document-order-shared store. Use to make information from
+     * earlier-visited nodes available to later-visited ones (e.g. a
+     * `<style>` or `<meta>` at the top of the document influencing how
+     * later elements are interpreted). One {@link ImportSession} instance
+     * is created per top-level `$generateNodesFromDOM` call and is shared
+     * across all recursive `$importChildren` / `$importOne` invocations.
+     */
+    readonly session: ImportSession;
+    /** Read a typed context value. */
+    get<V>(cfg: ImportStateConfig<V>): V;
+    /**
+     * Recursively import every child of `parent` and return the produced
+     * lexical nodes, optionally enforcing a {@link ChildSchema} and/or
+     * branching the import context for the duration of the call (via
+     * `opts.context`).
+     */
+    $importChildren(parent: ParentNode, opts?: ImportChildrenOpts): LexicalNode[];
+    /**
+     * Recursively import a single DOM node.
+     */
+    $importOne(node: Node, opts?: ImportNodeOpts): LexicalNode[];
+}
+/**
+ * Options accepted by {@link DOMImportContext.$importChildren}. The combination
+ * of `schema`, `$onChild`, and `$after` is sufficient to express every
+ * child-handling pattern in the legacy `forChild` / `after` / wrap-continuous
+ * machinery.
+ *
+ * @experimental
+ */
+export interface ImportChildrenOpts {
+    /**
+     * How to validate and (re)package produced children. Defaults to whichever
+     * schema the parent's importer passed; the top-level entry uses
+     * {@link BlockSchema}.
+     */
+    readonly schema?: ChildSchema;
+    /**
+     * Called for each produced lexical child immediately after its rule
+     * returned, with the chance to substitute or drop it. Equivalent to the
+     * old `forChild` hook but scoped to one `$importChildren` call.
+     */
+    readonly $onChild?: (child: LexicalNode) => LexicalNode | null | undefined;
+    /**
+     * Called once with the full child array after all DOM children have been
+     * recursively imported but before {@link ChildSchema.$packageRun} is
+     * applied. Equivalent to the old `after` hook.
+     */
+    readonly $after?: (children: LexicalNode[]) => LexicalNode[];
+    /** Context overrides scoped to the children traversal. */
+    readonly context?: readonly ImportContextPairOrUpdater[];
+    /**
+     * Additional {@link DOMImportRule}s active only for this children
+     * traversal (and any nested `$importChildren` calls that don't push
+     * their own overlay). The overlay is checked BEFORE the main
+     * dispatcher, so its rules take precedence; calling `$next()` from an
+     * overlay rule falls through to the next overlay-or-main rule.
+     *
+     * Use this to scope cost-bearing rules to where they apply. For
+     * example, a GitHub code-table rule installs an overlay that
+     * unwraps `<tr>` / `<td>` inside the table, without paying that
+     * predicate cost on every other `<tr>` / `<td>` paste.
+     *
+     * The value must be produced by
+     * {@link defineOverlayRules}; this forces the dispatcher to be
+     * compiled once at module scope and reused across
+     * `$importChildren` calls, instead of being recompiled per invocation.
+     */
+    readonly rules?: CompiledOverlayRules;
+}
+/** @experimental */
+export interface ImportNodeOpts {
+    readonly context?: readonly ImportContextPairOrUpdater[];
+}
+/**
+ * A {@link ChildSchema} encodes which lexical nodes a parent accepts as
+ * children and how to package or reject the rest. The legacy
+ * `wrapContinuousInlines` / `ArtificialNode__DO_NOT_USE` logic is the
+ * `BlockSchema` and `NestedBlockSchema` cases of this primitive.
+ *
+ * A schema only controls how the *children* are assembled before being
+ * appended to the parent the calling rule already chose. It cannot
+ * change the parent itself. Cases where the parent's shape needs to
+ * change in response to its children — e.g. an inline `<a>` that
+ * encloses a block `<h1>`, which must be lifted so the heading takes
+ * the link's place and the link is redistributed onto the heading's
+ * inline contents — belong in the rule body, not the schema. See the
+ * "Lifting blocks out of an inline parent" section of the docs.
+ *
+ * @experimental
+ */
+export interface ChildSchema {
+    /** Optional name for debug output. */
+    readonly name?: string;
+    /**
+     * Returns `true` if `child` is a valid child of `parent` in this position.
+     */
+    $accepts(child: LexicalNode, parent: LexicalNode | null): boolean;
+    /**
+     * Package a maximal run of non-accepted siblings into zero or more
+     * accepted nodes. The returned nodes replace the rejected run at the
+     * same position in the child list and are not re-checked against
+     * `$accepts` — the caller is trusted to return valid children. If
+     * omitted, or if it returns an empty array, {@link ChildSchema.onReject}
+     * is consulted instead.
+     */
+    $packageRun?(rejected: LexicalNode[], parent: LexicalNode | null, domParent: Node | null): LexicalNode[];
+    /**
+     * Fallback strategy for a run of non-accepted children when
+     * `$packageRun` is missing or returns an empty array:
+     *
+     * - `'drop'` (default) — silently discards the run. Use when the
+     *   schema is strict and rejected content is meaningless in this
+     *   position (e.g. text between table rows).
+     * - `'hoist'` — emits the rejected nodes unchanged at the same
+     *   position in the assembled child list. The caller's parent then
+     *   receives them as-is, which is only useful if the calling rule
+     *   intends to surface mixed content to *its* parent (a less common
+     *   pattern; usually `$packageRun` should re-shape the run first).
+     *
+     * `'hoist'` does NOT lift the run all the way up out of the calling
+     * rule's parent — that requires the rule itself to detect the
+     * situation and emit a different parent structure (see the
+     * "Lifting blocks out of an inline parent" section).
+     */
+    readonly onReject?: 'hoist' | 'drop';
+    /**
+     * Final pass over the assembled child list (after `$packageRun`). Returns
+     * the children to actually attach. Use to enforce structural invariants
+     * (e.g. drop empty runs, pad short table rows).
+     */
+    $finalize?(children: LexicalNode[], parent: LexicalNode | null): LexicalNode[];
+}
+/**
+ * The middleware signature of an import rule. Call `$next()` to delegate to
+ * the next-matching rule for this node (returning its result, which may then
+ * be inspected or wrapped); return `[]` to drop the node.
+ *
+ * @experimental
+ */
+export type DOMImportFn<E extends Node, C extends Record<string, RegExpMatchArray> = Record<string, never>> = (ctx: DOMImportContext<C>, node: E, $next: () => readonly LexicalNode[]) => readonly LexicalNode[];
+/**
+ * An importer for a DOM node, dispatched by `match` and implemented by
+ * `$import`.
+ *
+ * @experimental
+ */
+export interface DOMImportRule<S extends CompiledSelector = CompiledSelector> {
+    /**
+     * Optional identifier surfaced in dev-mode logs, error messages, and
+     * introspection devtools. Convention: `'@scope/package/rule-id'` for
+     * library rules.
+     */
+    readonly name?: string;
+    /** A {@link CompiledSelector} produced by the {@link sel} builder. */
+    readonly match: S;
+    /** Middleware that converts the matched DOM node into lexical nodes. */
+    readonly $import: DOMImportFn<NodeOfSelector<S>, CapturesOfSelector<S>>;
+}
+/** @experimental */
+export type AnyDOMImportRule = DOMImportRule<any>;
+/**
+ * Context exposed to a {@link DOMPreprocessFn}. Lets the preprocessor:
+ *
+ * - Write to the per-import {@link ImportSession} (the same
+ *   `ctx.session` rules see during the walk). Writes mutate the
+ *   root-layer context record, so they are visible to every scoped
+ *   `ctx.get(cfg)` read that hasn't been shadowed by a branch.
+ *
+ * @experimental
+ */
+export interface DOMPreprocessContext {
+    /**
+     * Document-order-shared store, same instance as `ctx.session` in
+     * rules. Use to pass info from the DOM preprocess phase (e.g.
+     * inspected `<meta>` tags, collected `<style>` text) to the
+     * importer rules.
+     */
+    readonly session: ImportSession;
+}
+/**
+ * A middleware step in the DOM-preprocess chain. Runs before walking
+ * begins and may:
+ *
+ * - Mutate the input DOM in place (e.g. inline stylesheets, strip
+ *   unsafe elements, normalize attributes).
+ * - Write to {@link DOMPreprocessContext.session} for rules to read
+ *   (and for unshadowed scoped reads to pick up).
+ * - Call `$next()` to defer to the next-lower preprocessor in the
+ *   stack; omit the call to short-circuit and skip the rest.
+ *
+ * The preprocess phase runs inside the same editor read / update
+ * context as the walk that follows, so a preprocess function may call
+ * `$`-prefixed Lexical APIs (e.g. `$getState`, `$getRoot`) as needed.
+ * The `$next` parameter is named with a `$` prefix to make that
+ * editor-context expectation visible to readers and lints.
+ *
+ * Append-style merge applies: an extension's preprocessors are appended
+ * to the existing stack, so later-registered preprocessors run first
+ * and may delegate to earlier (lower-priority) ones via `$next()`. Same
+ * convention as {@link ExportMimeTypeFunction} on the export side.
+ *
+ * @experimental
+ */
+export type DOMPreprocessFn = (dom: Document | ParentNode, ctx: DOMPreprocessContext, $next: () => void) => void;
+/**
+ * Per-call options to the extension's `$generateNodesFromDOM`.
+ *
+ * @experimental
+ */
+export interface GenerateNodesFromDOMOptions {
+    /**
+     * Context pairs/updaters applied for the duration of this import only —
+     * use to communicate per-call info such as the {@link ImportSource}.
+     */
+    readonly context?: readonly ImportContextPairOrUpdater[];
+    /**
+     * Additional preprocessors to run on this call only, on top of the
+     * extension's configured {@link DOMImportConfig.preprocess}. Per-call
+     * preprocessors run AFTER the configured ones.
+     */
+    readonly preprocess?: readonly DOMPreprocessFn[];
+}
+/**
+ * Output of {@link DOMImportExtension}.
+ *
+ * @experimental
+ */
+export interface DOMImportExtensionOutput {
+    /**
+     * Convert a {@link Document} or {@link ParentNode} into lexical nodes,
+     * using the dispatcher compiled from this extension's configured
+     * {@link DOMImportRule}s.
+     *
+     * Must be called within an `editor.update()` or `editor.read()` because
+     * the importers may invoke `$create...` helpers.
+     */
+    $generateNodesFromDOM(dom: Document | ParentNode, options?: GenerateNodesFromDOMOptions): LexicalNode[];
+    /** @internal */
+    readonly defaults: undefined | ContextRecord<typeof DOMImportContextSymbol>;
+}

package/dist/index.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ */
+import type { BaseSelection, LexicalEditor, LexicalNode } from 'lexical';
+export { contextUpdater, contextValue } from './ContextRecord';
+export { domOverride } from './domOverride';
+export { DOMRenderExtension } from './DOMRenderExtension';
+export type { AnyDOMImportRule, AttrMatchOptions, CapturesOfSelector, ChildSchema, CompiledOverlayRules, CompiledSelector, DOMImportContext, DOMImportExtensionOutput, DOMImportFn, DOMImportRule, DOMImportRuleEntry, DOMPreprocessContext, DOMPreprocessFn, ElementSelectorBuilder, GenerateNodesFromDOMOptions, ImportChildrenOpts, ImportContextPairOrUpdater, ImportNodeOpts, ImportSession, ImportStateConfig, NodeOfSelector, StyleMatchOptions, } from './import';
+export { $distributeInlineWrapper, $generateNodesFromDOMViaExtension, $getImportContextValue, $inlineStylesFromStyleSheets, $isBlockLevel, $withImportContext, BlockSchema, CoreImportExtension, CoreImportRules, createImportState, defaultIsInline, defaultPreservesWhitespace, defineImportRule, defineOverlayRules, type DOMImportConfig, DOMImportExtension, HorizontalRuleImportExtension, HorizontalRuleImportRules, ImportOverlays, ImportSource, ImportSourceDataTransfer, type ImportSourceKind, ImportTextFormat, ImportTextStyle, ImportWhitespaceConfig, InlineSchema, isElementOfTag, type IsInlineForWhitespace, type IsPreserveWhitespaceDom, NestedBlockSchema, parseSelector, RootSchema, sel, type WhitespaceImportConfig, } from './import';
+export { $getRenderContextValue, $getSessionDOMRenderConfig, $setRenderContextValue, $updateRenderContextValue, $withRenderContext, createRenderState, RenderContextExport, RenderContextRoot, } from './RenderContext';
+export type { AnyDOMRenderMatch, AnyRenderStateConfig, AnyRenderStateConfigPairOrUpdater, ContextPairOrUpdater, DOMOverrideOptions, DOMRenderConfig, DOMRenderExtensionOutput, DOMRenderMatch, DOMRenderMatchConfig, NodeMatch, RenderContextReader, } from './types';
+/**
+ * How you parse your html string to get a document is left up to you. In the browser you can use the native
+ * DOMParser API to generate a document (see clipboard.ts), but to use in a headless environment you can use JSDom
+ * or an equivalent library and pass in the document here.
+ */
+export declare function $generateNodesFromDOM(editor: LexicalEditor, dom: Document | ParentNode): Array<LexicalNode>;
+/**
+ * Generate DOM nodes from the editor state into the given container element,
+ * using the editor's {@link EditorDOMRenderConfig}.
+ * @experimental
+ */
+export declare function $generateDOMFromNodes<T extends HTMLElement | DocumentFragment>(container: T, selection?: null | BaseSelection, editor?: LexicalEditor): T;
+/**
+ * Generate DOM nodes from a root node into the given container element,
+ * including the root node itself. Uses the editor's {@link EditorDOMRenderConfig}.
+ * @experimental
+ */
+export declare function $generateDOMFromRoot<T extends HTMLElement | DocumentFragment>(container: T, root?: LexicalNode): T;
+/**
+ * Generate an HTML string from the editor's current state (or `selection`
+ * if provided).
+ *
+ * Must be called inside an active editor scope — i.e. `editor.update(...)`,
+ * `editor.read(...)`, or `editor.getEditorState().read(callback, {editor})`.
+ * The legacy `editor.getEditorState().read(callback)` call (without the
+ * `{editor}` option) does not set an active editor and is not supported;
+ * `editor.read(...)` is the drop-in replacement.
+ */
+export declare function $generateHtmlFromNodes(editor: LexicalEditor, selection?: BaseSelection | null): string;

package/{types.d.ts → dist/types.d.ts}

@@ -5,14 +5,14 @@
  * LICENSE file in the root directory of this source tree.
  *
  */
-import type { DOMRenderContextSymbol } from './constants';
-import type { BaseSelection, DOMExportOutput, ElementDOMSlot, Klass, LexicalEditor, LexicalNode, StateConfig } from 'lexical';
+import type { DOMImportContextSymbol, DOMRenderContextSymbol } from './constants';
+import type { BaseSelection, DOMExportOutput, DOMSlotForNode, EditorDOMRenderConfig, Klass, LexicalEditor, LexicalNode, StateConfig } from 'lexical';
 /**
  * @experimental
  *
- * Any ContextSymbol for {@link ContextConfig} (currently only {@link DOMRenderContextSymbol})
+ * Any ContextSymbol for {@link ContextConfig} (DOM render or DOM import).
  */
-export type AnyContextSymbol = typeof DOMRenderContextSymbol;
+export type AnyContextSymbol = typeof DOMRenderContextSymbol | typeof DOMImportContextSymbol;
 /**
  * @experimental
  *
@@ -68,6 +68,73 @@ export type AnyContextConfigPairOrUpdater<Ctx extends AnyContextSymbol> = Contex
 export interface DOMRenderExtensionOutput {
     /** @internal */
     defaults: undefined | ContextRecord<typeof DOMRenderContextSymbol>;
+    /** @internal */
+    runtime: DOMRenderRuntime;
+}
+/**
+ * @experimental
+ *
+ * A read-only view of a render context layer, passed to the
+ * {@link DOMOverrideOptions} predicates so they can decide whether an
+ * override should be installed based only on context values.
+ */
+export interface RenderContextReader {
+    get<V>(cfg: RenderStateConfig<V>): V;
+}
+/**
+ * @experimental
+ * @internal
+ *
+ * Per-editor runtime state for {@link DOMRenderExtension} that backs the
+ * imperative editor context ({@link createRenderState} writes via
+ * `$setRenderContextValue`) and the conditional install of overrides.
+ */
+export interface DOMRenderRuntime {
+    /**
+     * The mutable, persistent editor-level context record. Reads of a
+     * {@link RenderStateConfig} during reconciliation (and as the base layer
+     * during a session) fall through to this record. It is also the layer
+     * that {@link DOMOverrideOptions.disabledForEditor} predicates read from.
+     */
+    readonly editorContext: ContextRecord<typeof DOMRenderContextSymbol>;
+    /**
+     * Imperatively set a value in the editor context. If the change flips any
+     * override's `disabledForEditor` result, the resident render config is
+     * recompiled and the affected nodes are re-rendered (recreating DOM for
+     * structural overrides).
+     */
+    setContextValue<V>(cfg: RenderStateConfig<V>, value: V): void;
+    /**
+     * Resolve the {@link EditorDOMRenderConfig} for the current export/generate
+     * session, applying any {@link DOMOverrideOptions.disabledForSession}
+     * predicates against the active session context. Returns the resident
+     * config when no session gating applies.
+     */
+    getSessionConfig(): EditorDOMRenderConfig;
+}
+/**
+ * @experimental
+ *
+ * Options for {@link domOverride} controlling *whether* an override is
+ * installed, based only on render context. Both predicates default to
+ * "not disabled".
+ */
+export interface DOMOverrideOptions {
+    /**
+     * Gate residency in the editor's render config (used by reconciliation and
+     * as the base for export/generate). Evaluated against the persistent editor
+     * context at compile time, and re-evaluated when that context changes via
+     * `$setRenderContextValue`; a change recompiles the config and re-renders
+     * affected nodes. Return `true` to remove the override. Default: not disabled.
+     */
+    disabledForEditor?: (ctx: RenderContextReader) => boolean;
+    /**
+     * Gate participation in a single export/generate session. Evaluated once at
+     * the start of each session against that session's context. Has no effect on
+     * live reconciliation (which is not a session). Return `true` to remove the
+     * override for that session. Default: not disabled.
+     */
+    disabledForSession?: (ctx: RenderContextReader) => boolean;
 }
 /**
  * @experimental
@@ -157,16 +224,19 @@ export interface DOMRenderMatch<T extends LexicalNode> {
      * after the children. The root of the node returned by createDOM must
      * still be exactly one HTMLElement.
      *
-     * Generally you will call `$next()` to get an ElementDOMSlot and then use
-     * its methods to create a new one.
+     * Generally you will call `$next()` to get a slot and then use its methods
+     * to create a new one. The slot type is narrowed via {@link DOMSlotForNode}:
+     * for `ElementNode` it resolves to {@link ElementDOMSlot} with
+     * children-management semantics; for non-Element nodes the base
+     * {@link DOMSlot} pointing at the keyed DOM.
      *
      * @param node The LexicalNode
      * @param dom The rendered HTMLElement
      * @param $next Call the next implementation
      * @param editor The editor
-     * @returns The `ElementDOMSlot` for this node
+     * @returns The slot for this node
      */
-    $getDOMSlot?: <N extends LexicalNode>(node: N, dom: HTMLElement, $next: () => ElementDOMSlot<HTMLElement>, editor: LexicalEditor) => ElementDOMSlot<HTMLElement>;
+    $getDOMSlot?: (node: T, dom: HTMLElement, $next: () => DOMSlotForNode<T>, editor: LexicalEditor) => DOMSlotForNode<T>;
     /**
      * Called during the reconciliation process to determine which nodes
      * to insert into the DOM for this Lexical Node. This is also the default
@@ -290,4 +360,22 @@ export interface DOMRenderMatch<T extends LexicalNode> {
      * @returns true if this
      */
     $extractWithChild?: (node: T, childNode: LexicalNode, selection: null | BaseSelection, destination: 'clone' | 'html', $next: () => boolean, editor: LexicalEditor) => boolean;
+    /**
+     * Set via {@link domOverride}'s options argument, not directly. See
+     * {@link DOMOverrideOptions.disabledForEditor}.
+     */
+    disabledForEditor?: (ctx: RenderContextReader) => boolean;
+    /**
+     * Set via {@link domOverride}'s options argument, not directly. See
+     * {@link DOMOverrideOptions.disabledForSession}.
+     */
+    disabledForSession?: (ctx: RenderContextReader) => boolean;
 }
+/**
+ * @experimental
+ *
+ * The hook fields of a {@link DOMRenderMatch} — i.e. without `nodes` or the
+ * {@link DOMOverrideOptions} predicates, which are passed separately to
+ * {@link domOverride}.
+ */
+export type DOMRenderMatchConfig<T extends LexicalNode> = Omit<DOMRenderMatch<T>, 'nodes' | keyof DOMOverrideOptions>;

package/package.json

@@ -8,37 +8,52 @@
     "html"
   ],
   "license": "MIT",
-  "version": "0.44.1-nightly.20260519.0",
-  "main": "LexicalHtml.js",
-  "types": "index.d.ts",
+  "version": "0.45.0",
+  "main": "./dist/LexicalHtml.js",
+  "types": "./dist/index.d.ts",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/facebook/lexical.git",
     "directory": "packages/lexical-html"
   },
   "dependencies": {
-    "@lexical/extension": "0.44.1-nightly.20260519.0",
-    "@lexical/selection": "0.44.1-nightly.20260519.0",
-    "@lexical/utils": "0.44.1-nightly.20260519.0",
-    "lexical": "0.44.1-nightly.20260519.0"
+    "@lexical/extension": "0.45.0",
+    "@lexical/internal": "0.45.0",
+    "@lexical/selection": "0.45.0",
+    "@lexical/utils": "0.45.0",
+    "lexical": "0.45.0"
   },
-  "module": "LexicalHtml.mjs",
+  "module": "./dist/LexicalHtml.mjs",
   "sideEffects": false,
   "exports": {
     ".": {
+      "source": "./src/index.ts",
       "import": {
-        "types": "./index.d.ts",
-        "development": "./LexicalHtml.dev.mjs",
-        "production": "./LexicalHtml.prod.mjs",
-        "node": "./LexicalHtml.node.mjs",
-        "default": "./LexicalHtml.mjs"
+        "types": "./dist/index.d.ts",
+        "development": "./dist/LexicalHtml.dev.mjs",
+        "production": "./dist/LexicalHtml.prod.mjs",
+        "node": "./dist/LexicalHtml.node.mjs",
+        "default": "./dist/LexicalHtml.mjs"
       },
       "require": {
-        "types": "./index.d.ts",
-        "development": "./LexicalHtml.dev.js",
-        "production": "./LexicalHtml.prod.js",
-        "default": "./LexicalHtml.js"
+        "types": "./dist/index.d.ts",
+        "development": "./dist/LexicalHtml.dev.js",
+        "production": "./dist/LexicalHtml.prod.js",
+        "default": "./dist/LexicalHtml.js"
       }
     }
-  }
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/__tests__",
+    "!src/__bench__",
+    "!src/__mocks__",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.tsx",
+    "!src/**/*.bench.ts",
+    "!src/**/*.bench.tsx",
+    "README.md",
+    "LICENSE"
+  ]
 }