Lexical Immutable Node Transforms, Selection Reconciliation & Headless Serialization Invariants

--- description: Lexical Immutable Node Transforms, Selection Reconciliation & Headless Serialization Invariants - Enforces strict compliance with Lexical's double-buffered copy-on-write immutability, deterministic selection reconciliation, and DOM-agnostic headless serialization. Mandates idempotent node transforms with loop guards, selection restoration across structural tree mutations, and isolation of DOM globals during headless Markdown transforms. globs: src/**/*.{ts,tsx}, lib/**/*.{ts,tsx}, packages/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/lexical-node-transforms-selection-reconciliation-headless" --- # Lexical Immutable Node Transforms, Selection Reconciliation & Headless Serialization Invariants > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Direct Node Mutation, Blind Selection Collapsing, and DOM-Dependent Headless Serialization ## System Constraints You are a Principal Software Architect enforcing production invariants for Meta Lexical rich-text architectures. You mandate absolute compliance with Lexical's double-buffered EditorState tree, ensuring that all mutations utilize copy-on-write semantics ($getWritable), selection offsets are preserved across AST modifications, node transforms are protected against infinite cycles with idempotent preconditions, and headless document pipelines execute without DOM dependencies. ## Strict Guidelines - Engineers MUST ALWAYS execute node modifications inside `editor.update()` or active transform contexts; never cache or modify node instances across transactional boundaries. - Engineers MUST invoke `$is<NodeType>` and obtain an updated writable reference via `$getNodeByKey()` or internal `getWritable()` mechanisms before altering node fields in custom classes. - Engineers MUST include strict idempotency guards inside `editor.registerNodeTransform` callbacks to prevent infinite transform loops (Lexical throws an unrecoverable maximum transform loop error if dirtying is unconstrained). - Structural tree mutations (insertions, removals, splits) MUST cache and reconcile the active selection via `$getSelection()` and `$setSelection()`, explicitly handling `RangeSelection` anchor/focus offsets to prevent cursor snapping or losing IME composition state. - Headless pipelines (e.g., server-side or worker-based Markdown parsing/generation) MUST use `createHeadlessEditor` and MUST NEVER access `window`, `document`, or DOM elements inside custom node serializers, transformers, or plugins. - Markdown export and import transformations MUST register all referenced custom Node types in the headless editor constructor, ensuring `$convertToMarkdownString` and `$convertFromMarkdownString` map strictly across AST nodes and transformer specifications. ## Bad vs Good Implementations ### Idempotent Node Transform with Selection Preservation vs Dirty Transform Loop #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Lexical schedules a new transform cycle whenever a node is marked dirty inside a transform. Changing text unconditionally without checking if the transformed value equals the current value triggers an infinite transform loop. Additionally, altering text directly collapses the active selection back to position 0. ```typescript import { $getSelection, $isRangeSelection, TextNode, LexicalEditor } from 'lexical'; export function registerUppercaseTransform(editor: LexicalEditor) { // Anti-Pattern: Lacks idempotency guard; directly mutates text without checking // if the node is already transformed, causing an infinite transform loop. // Fails to preserve range selection offsets. return editor.registerNodeTransform(TextNode, (node: TextNode) => { const text = node.getTextContent(); node.setTextContent(text.toUpperCase()); // Dirty marks node unconditionally -> crash! }); } ``` #### Production Standard (Correct) > **Standard**: The transform inspects the current state, exiting early if the invariant is satisfied to avoid re-dirtying the node. It checks selection intersection, records original offsets, updates the node within copy-on-write boundaries, and reconciles selection without collapsing or shifting focus. ```typescript import { $getSelection, $isRangeSelection, TextNode, LexicalEditor } from 'lexical'; export function registerUppercaseTransform(editor: LexicalEditor): () => void { return editor.registerNodeTransform(TextNode, (node: TextNode) => { if (!node.isSimpleText() || node.hasFormat('code')) { return; } const currentText = node.getTextContent(); const upperText = currentText.toUpperCase(); // Guard: Prevent re-dirtying if text already matches expected invariant if (currentText === upperText) { return; } const selection = $getSelection(); const isTargetSelected = $isRangeSelection(selection) && selection.getNodes().some((n) => n.getKey() === node.getKey()); // Save selection offsets if selection intersects with mutating node const anchorOffset = isTargetSelected ? selection.anchor.offset : null; const focusOffset = isTargetSelected ? selection.focus.offset : null; // Perform copy-on-write mutation node.setTextContent(upperText); // Reconcile selection state post-mutation if (isTargetSelected && $isRangeSelection(selection) && anchorOffset !== null && focusOffset !== null) { selection.setTextNodeRange(node, anchorOffset, node, focusOffset); } }); } ``` ### DOM-Free Headless Markdown Serialization vs DOM-Dependent Execution #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Standard `createEditor` expects a DOM environment and attempts DOM reconciliation. In backend jobs, serverless functions, or build pipelines, this crashes with `ReferenceError: window is not defined` or `document is not defined`. ```typescript import { createEditor } from 'lexical'; import { $convertToMarkdownString, TRANSFORMERS } from '@lexical/markdown'; import { HeadingNode, QuoteNode } from '@lexical/rich-text'; // Anti-Pattern: Uses standard browser createEditor in a backend/worker process. // Relies on global document/window which triggers ReferenceError in headless Node.js. export function exportMarkdown(serializedState: string): string { const editor = createEditor({ nodes: [HeadingNode, QuoteNode], onError: (error) => { throw error; }, }); let markdown = ''; const state = editor.parseEditorState(serializedState); editor.setEditorState(state); editor.read(() => { // Relies on DOM-dependent markdown transformers markdown = $convertToMarkdownString(TRANSFORMERS); }); return markdown; } ``` #### Production Standard (Correct) > **Standard**: Uses `createHeadlessEditor` from `@lexical/headless` with all AST nodes explicitly declared. Uses pure transformer arrays free of DOM dependencies, and forces synchronous state computation via `{ discrete: true }` in Node.js/worker runtimes. ```typescript import { createHeadlessEditor } from '@lexical/headless'; import { $convertToMarkdownString, $convertFromMarkdownString, Transformer, ELEMENT_TRANSFORMERS, TEXT_FORMAT_TRANSFORMERS, TEXT_MATCH_TRANSFORMERS, } from '@lexical/markdown'; import { HeadingNode, QuoteNode } from '@lexical/rich-text'; import { ListItemNode, ListNode } from '@lexical/list'; import { CodeNode } from '@lexical/code'; import { LinkNode } from '@lexical/link'; const HEADLESS_NODES = [HeadingNode, QuoteNode, ListNode, ListItemNode, CodeNode, LinkNode]; const PURE_TRANSFORMERS: Transformer[] = [ ...ELEMENT_TRANSFORMERS, ...TEXT_FORMAT_TRANSFORMERS, ...TEXT_MATCH_TRANSFORMERS, ]; export function headlessStateToMarkdown(serializedState: string): string { const editor = createHeadlessEditor({ nodes: HEADLESS_NODES, onError: (error: Error) => { throw new Error(`[Lexical Headless Error]: ${error.message}`); }, }); const editorState = editor.parseEditorState(serializedState); editor.setEditorState(editorState); let markdown = ''; editor.read(() => { markdown = $convertToMarkdownString(PURE_TRANSFORMERS); }); return markdown; } export function headlessMarkdownToState(markdown: string): string { const editor = createHeadlessEditor({ nodes: HEADLESS_NODES, onError: (error: Error) => { throw new Error(`[Lexical Headless Error]: ${error.message}`); }, }); editor.update(() => { $convertFromMarkdownString(markdown, PURE_TRANSFORMERS); }, { discrete: true }); return JSON.stringify(editor.getEditorState().toJSON()); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Lexical Immutable Node Transforms, Selection Reconciliation & Headless Serialization Invariants

Lexical Immutable Node Transforms, Selection Reconciliation & Headless Serialization Invariants defines an industrial-grade behavioral standard for frontend engineering. Enforces strict compliance with Lexical's double-buffered copy-on-write immutability, deterministic selection reconciliation, and DOM-agnostic headless serialization. Mandates idempotent node transforms with loop guards, selection restoration across structural tree mutations, and isolation of DOM globals during headless Markdown transforms. Modern software architectures require strict adherence to deterministic patterns to guarantee high availability, maintainability, and zero security vulnerabilities.

Framework Paradigm Shift & Drift MechanicsLLMs are trained on millions of open-source repositories containing outdated code, legacy idioms, and unpatched antipatterns. When coding assistants generate implementations for this stack, they default to common statistical tokens: Direct Node Mutation, Blind Selection Collapsing, and DOM-Dependent Headless Serialization Without an explicit system instruction file, developers spend hours debugging silent failures.

Failure Modes & Production Blast Radius

Hazard Analysis: What Breaks Without This Rule

The following failure modes have been cataloged from hundreds of hours of production code reviews where AI assistants produced non-compliant implementations:

Failure Mode	AI Symptom (The Anti-Pattern)	Severity	Production Impact & Remedy
AI Hallucination & Deprecation Drift	Direct Node Mutation, Blind Selection Collapsing, and DOM-Dependent Headless Serialization	Critical	Violating this industrial standard introduces regression bugs, security risks, and unexpected runtime failures in production. Enforce explicit behavioral system directives across all AI coding assistants in your repository.
Silent Architecture Inconsistency	AI assistants produce mixed paradigms across files, creating fragmented codebase conventions.	Medium	Increases cognitive load during code reviews and leads to maintenance debt across engineering teams. Pin project conventions in .cursor/rules, CLAUDE.md, and AGENTS.md so all team agents follow identical guardrails.

Architectural Directives in Detail

Step-by-Step Production Directives

Each rule constraint below is injected into the AI agent's system prompt to establish deterministic boundaries:

Engineers MUST ALWAYS execute node modifications inside `editor.update()` or active transform contexts

Engineers MUST ALWAYS execute node modifications inside `editor.update()` or active transform contexts; never cache or modify node instances across transactional boundaries.

Rationale:AI models frequently generate unconstrained code here because statistical language distributions lack project-specific architectural context. Mandating this directive ensures that generated code adheres to verified industrial production requirements.