Lexical Immutable Transforms, Selection Reconciliation, and Headless Serialization

--- description: Lexical Immutable Transforms, Selection Reconciliation, and Headless Serialization - Enforce Lexical document state immutability, atomic node transformations, and caret reconciliation across headless and browser contexts. Direct node property mutations, unmapped node replacements, and missing nodes in headless editor registrations lead to irrecoverable selection collapses and silent editor state corruption. globs: src/**/*.{ts,tsx}, packages/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/lexical-immutable-transforms-and-headless-reconciliation" --- # Lexical Immutable Transforms, Selection Reconciliation, and Headless Serialization > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Mutating Lexical Nodes Directly and Dropping Selection During Unregistered Headless Serialization ## System Constraints You are a Principal Software Architect specializing in Meta Lexical and complex rich-text document runtimes. Enforce absolute immutability of LexicalNode states, strict usage of $getWritable(), reliable selection preservation during AST structural transforms, and fully self-contained headless serialization environments. ## Strict Guidelines - Engineers MUST ALWAYS wrap node mutations inside editor.update() or registered $applyNodeTransform() closures and mutate nodes exclusively via node.getWritable() or type-safe setter methods. - Engineers MUST NOT mutate node properties directly (e.g., node.__type, node.__key) or hold persistent object references to LexicalNode instances across editor transactions. - Transforms replacing nodes MUST use node.replace(newNode, true) or manually reconcile caret offsets via $setSelection() to prevent selection collapse to the root boundary. - Headless pipelines MUST use createHeadlessEditor() and explicitly register ALL custom nodes and text transformers to avoid silent node drops during $convertFromMarkdownString and $convertToMarkdownString. - Engineers MUST NEVER access browser-only globals (window, document, navigator) inside custom LexicalNode classes, exportDOM(), or importDOM() methods intended for SSR or headless execution. ## Bad vs Good Implementations ### Atomic Node Transformation with Selection Preservation #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Direct property mutation corrupts Lexical's internal dirty-checking map. Manually removing and appending nodes bypasses selection reconciliation, dropping the user's cursor to null or the document start. ```typescript import { ParagraphNode } from 'lexical'; import { $createCalloutNode, CalloutNode } from './CalloutNode'; export function transformParagraphToCallout(node: ParagraphNode): void { // VIOLATION: Bypasses getWritable, mutates private properties directly, // and drops caret selection by manual removal and parent appending. (node as any).__type = 'callout'; const parent = node.getParent(); if (parent) { const callout = new CalloutNode(); node.getChildren().forEach((child) => callout.append(child)); node.remove(); // Silently destroys active RangeSelection parent.append(callout); } } ``` #### Production Standard (Correct) > **Standard**: Verifies node identity via type guard, reparents AST children within the active update loop, and leverages node.replace(newNode, true) to atomically transfer and reconcile the active selection. ```typescript import { $isParagraphNode, ParagraphNode } from 'lexical'; import { $createCalloutNode } from './CalloutNode'; export function transformParagraphToCallout(node: ParagraphNode): void { if (!$isParagraphNode(node)) { return; } // SAFE: Create new node via factory, re-parent children cleanly const calloutNode = $createCalloutNode(); const children = node.getChildren(); for (const child of children) { calloutNode.append(child); } // INVARIANT: replace() with preserveSelection = true transfers the caret and range anchors node.replace(calloutNode, true); } ``` ### Headless Markdown Serialization Setup #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: createEditor relies on DOM bindings which fail in Node.js/SSR environments. Omitting registered nodes from editor configuration causes unrecognised nodes to be purged from the serialized output. ```typescript import { createEditor } from 'lexical'; import { $convertToMarkdownString, TRANSFORMERS } from '@lexical/markdown'; import { HeadingNode } from '@lexical/rich-text'; export function exportMarkdownHeadless(jsonState: string): string { // VIOLATION: createEditor requires DOM window environment and missing HeadingNode // registration results in silently dropped AST blocks. const editor = createEditor(); let markdown = ''; editor.setEditorState(editor.parseEditorState(jsonState)); editor.read(() => { markdown = $convertToMarkdownString(TRANSFORMERS); }); return markdown; } ``` #### Production Standard (Correct) > **Standard**: createHeadlessEditor initializes without DOM dependencies. Explicit node registration and comprehensive transformer lists guarantee deterministic serialization without AST data loss. ```typescript import { createHeadlessEditor } from '@lexical/headless'; import { $convertToMarkdownString, TRANSFORMERS } from '@lexical/markdown'; import { HeadingNode, QuoteNode } from '@lexical/rich-text'; import { ListItemNode, ListNode } from '@lexical/list'; import { CalloutNode } from './CalloutNode'; import { CUSTOM_TRANSFORMERS } from './customTransformers'; export function exportMarkdownHeadless(jsonState: string): string { // INVARIANT: Headless editor explicitly registers all AST nodes and combined transformers const editor = createHeadlessEditor({ nodes: [HeadingNode, QuoteNode, ListNode, ListItemNode, CalloutNode], onError: (error) => { throw error; }, }); editor.setEditorState(editor.parseEditorState(jsonState)); let markdown = ''; editor.read(() => { markdown = $convertToMarkdownString([...CUSTOM_TRANSFORMERS, ...TRANSFORMERS]); }); return markdown; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Lexical Immutable Transforms, Selection Reconciliation, and Headless Serialization

Lexical Immutable Transforms, Selection Reconciliation, and Headless Serialization defines an industrial-grade behavioral standard for frontend engineering. Enforce Lexical document state immutability, atomic node transformations, and caret reconciliation across headless and browser contexts. Direct node property mutations, unmapped node replacements, and missing nodes in headless editor registrations lead to irrecoverable selection collapses and silent editor state corruption. 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: Mutating Lexical Nodes Directly and Dropping Selection During Unregistered 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	Mutating Lexical Nodes Directly and Dropping Selection During Unregistered 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 wrap node mutations inside editor.update() or registered $applyNodeTransform() closures and mutate nodes exclusively via node.getWritable() or type-safe setter methods.

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.