@octane-xplat/lexical 0.10.0 → 0.11.1

package/README.md

@@ -64,12 +64,98 @@ export function DocumentCopy() {
 }
 ```
 
-The facade's plugin set is fixed on purpose. Apps needing custom nodes,
-plugins, or transforms import `@octanejs/lexical` directly on web — the
-facade does not expose a composer/plugin surface it cannot honor on
-native. There is no live `LexicalEditor` on Android: no `dispatchCommand`,
-no node transforms; `native` returns the `AztecText` and the headless
-editor used for conversions is an internal detail.
+On web, `web.nodes` adds custom Lexical node classes to the facade's built-in
+nodes, and `web.plugins` renders additional Octane plugin components inside
+the Lexical composer. Set `replaceNodes` to `true` when `web.nodes` should be
+the full custom node registry. Set `replacePlugins` to `true` to replace the
+default history, list, link, and autofocus plugins with your own composition;
+the rich-text surface and facade change/ref bindings remain installed. This
+lets a custom node keep its Lexical JSON type and HTML representation during
+a round-trip.
+
+```tsx
+import { LexicalEditor } from '@octane-xplat/lexical'
+import { BadgeNode, BadgePlugin } from './lexical-extensions'
+
+export function NoteEditor() {
+	return (
+		<LexicalEditor
+			value='<p><span data-badge>Voyager</span></p>'
+			web={{ nodes: [BadgeNode], plugins: <BadgePlugin /> }}
+		/>
+	)
+}
+```
+
+The `web` options are ignored on native. Native still edits with Aztec on
+Android and uses the fixed headless conversion node set for JSON. Caller
+plugins, custom nodes, browser views, and arbitrary JavaScript transforms do
+not run there. Apps replacing the web defaults can set both replacement
+options and register the node classes Lexical requires for their documents.
+
+```tsx
+import { LexicalEditor } from '@octane-xplat/lexical'
+import { BadgeNode, BadgePlugin } from './lexical-extensions'
+
+export function NoteEditor() {
+	return (
+		<LexicalEditor
+			web={{ replaceNodes: true, nodes: [BadgeNode], replacePlugins: true, plugins: <BadgePlugin /> }}
+		/>
+	)
+}
+```
+
+## Engine and feature boundary
+
+| Target | Editing engine | `web` options | Caller plugins, custom nodes, and browser views |
+| --- | --- | --- | --- |
+| Web | Lexical `LexicalComposer` with the facade's default nodes and plugins | `nodes`, `plugins`, and replacement flags apply | Supported by the web Lexical engine |
+| Android | WordPress Aztec `AztecText`; a headless Lexical editor converts serialized state to and from HTML | Ignored | Unsupported; no live Lexical editor, plugin, transform, custom node, or browser view runs |
+| iOS | Unsupported placeholder from `@octane-xplat/richtext` | Ignored | Unsupported; `supported` is `false` |
+| macOS AppKit | Bundled Lexical editor in WKWebView | Ignored by the AppKit host | Unsupported through this facade |
+
+On Android, save HTML as the canonical document. Lexical serialized state is
+a best-effort conversion through the fixed built-in node set; it is not a live
+Lexical editor state that supports commands or plugins.
+The 2026-10-06 [Aztec nested-tree run](../../.agents/docs/parity/nested-tree-editor.md)
+preserved nested wrappers, attributes, and child order through synthetic text
+edits and save/reopen, but flattened paragraphs and accumulated `<br>` elements
+on reopen. That run exercised the shared Aztec HTML leaf, not Lexical's JSON
+conversion or structural commands. See the
+[per-row capability record](../../docs/notes/editor-capabilities.md).
+
+```tsx
+import { useState } from 'octane'
+import { LexicalEditor, supported } from '@octane-xplat/lexical'
+import { Text } from '@octane-xplat/ui'
+
+export function Notes() {
+	const [html, setHTML] = useState('<p>Travel notes</p>')
+	return supported ? (
+		<LexicalEditor value={html} editable onChange={setHTML} />
+	) : (
+		<Text>Editing is unavailable on this target</Text>
+	)
+}
+```
+
+Focus callbacks report focus entering or leaving the editable surface.
+`onJSONReady(true)` fires once the web editor handle exists, so `getJSON()` is
+available from `onReady` and after readiness. On native, `onJSONReady` still
+reports when the lazy conversion bridge settles.
+
+```tsx
+<LexicalEditor
+	onJSONReady={(ready) => console.log('JSON ready:', ready)}
+	onFocus={() => console.log('Editor focused')}
+	onBlur={() => console.log('Editor blurred')}
+/>
+```
+
+There is no live `LexicalEditor` on Android: no `dispatchCommand`, no node
+transforms; `native` returns the `AztecText` and the headless editor used for
+conversions is an internal detail.
 
 The lexical family pins to `0.51.0` and `@octanejs/lexical` to `0.2.0`
 (peers `octane ^0.6.0`). `@lexical/link` carries a workspace patch for its
@@ -83,4 +169,4 @@ The macOS export mounts a bundled local editor document in WKWebView.
 RichText uses StarterKit; Tiptap and Lexical use their existing web facades.
 Wait for `onReady`; synchronous getters return the latest received snapshot
 and commands cross WebKit asynchronously. The `native` handle is the Swift
-host transport. See [AppKit setup and engine limits](../../docs/rich-text.md#macos-appkit-editing).
+host transport. See [AppKit setup and engine limits](../../docs/app/rich-text.md#macos-appkit-editing).