@barocss/editor-view-react 0.1.0

package/docs/SPEC_VERIFICATION.md

@@ -0,0 +1,109 @@
+# editor-view-react: Spec vs Implementation Verification
+
+This document records the result of verifying the implementation against `editor-view-react-spec.md`.
+
+**Verification date**: 2026-02-01  
+**Test run**: `pnpm --filter @barocss/editor-view-react test:run` — 23 tests, 4 files.
+
+---
+
+## §1–2 Goals, Architecture
+
+| Spec section | Verified | Notes |
+|--------------|----------|--------|
+| §1 Goals and Scope | ✅ | Same Editor/DataStore; renderer-react; no editor-view-dom dependency. |
+| §2 Architecture pipeline | ✅ | EditorViewContextProvider → selectionHandler, inputHandler, mutationObserverManager; EditorView → ContentLayer + overlay layers. |
+| §2 Dependencies | ✅ | dsl, editor-core, renderer-react, shared, text-analyzer (text-run-index API from shared); no editor-view-dom. |
+
+---
+
+## §3 API Contract
+
+| Spec section | Verified | Notes |
+|--------------|----------|--------|
+| §3.1 Exports | ✅ | EditorView, EditorViewContentLayer, EditorViewLayer, EditorViewContextProvider, useEditorViewContext, useOptionalEditorViewContext, createMutationObserverManager, types. |
+| §3.2 EditorView props | ✅ | editor, options (registry, className, layers), children. Test: options.className applied; layers.* control overlay presence; children in CustomLayer. |
+| §3.3 EditorViewContentLayer props | ✅ | options (registry, className, editable). Editor from context. |
+| §3.4 EditorViewLayer props | ✅ | layer, className, style, children. Test: data-bc-layer, position absolute, pointer-events none, default classNames/zIndex. |
+| §3.5 EditorView static subcomponents | ✅ | ContentLayer, Layer, DecoratorLayer, SelectionLayer, ContextLayer, CustomLayer. |
+
+---
+
+## §4 Context and View State
+
+| Spec section | Verified | Notes |
+|--------------|----------|--------|
+| §4.1 EditorViewContextValue | ✅ | Test: Consumer inside Provider receives editor, selectionHandler, inputHandler, mutationObserverManager, setContentEditableElement. |
+| §4.2 EditorViewViewState | ✅ | viewStateRef with isModelDrivenChange, isRendering, isComposing, skipNextRenderFromMO, skipApplyModelSelectionToDOM (used in implementation). |
+| §4.3 Lifecycle | ✅ | Provider creates handlers and manager; ContentLayer subscribes and setContentEditableElement (implementation only; subscription not asserted in tests). |
+
+---
+
+## §5–6 Layers, Content Layer
+
+| Spec section | Verified | Notes |
+|--------------|----------|--------|
+| §5.1 Content layer | ✅ | Test: content layer has data-bc-layer="content", data-testid="editor-content". |
+| §5.2 Overlay layers | ✅ | Test: decorator/selection/custom layers render when options.layers.* set; position absolute, pointer-events none. |
+| §5.3 Conditional rendering | ✅ | Test: overlay layers only when layers.* set; children in CustomLayer. |
+| §6 Document snapshot, ReactRenderer, contenteditable | ✅ | Implementation: getDocumentProxy, editor:content.change, ReactRenderer.build; contentEditable prop. Not asserted in unit tests (would require Editor mock with getDocumentProxy returning model). |
+
+---
+
+## §7 Selection Flow
+
+| Spec section | Verified | Notes |
+|--------------|----------|--------|
+| §7.1 DOM → Model | ✅ | Test: setProgrammaticChange(true) causes handleSelectionChange to skip updateSelection. |
+| §7.2 Model → DOM | ✅ | Implementation: editor:selection.model → requestAnimationFrame ×2 → convertModelSelectionToDOM. |
+| §7.3 ReactSelectionHandler | ✅ | Test: isSelectionInsideEditableText returns false when empty, true when inside inline-text node; setProgrammaticChange behavior. convertDOMSelectionToModel not tested (requires full DOM + shared text-run-index). |
+
+---
+
+## §8 Input and DOM Sync
+
+| Spec section | Verified | Notes |
+|--------------|----------|--------|
+| §8.1 ReactInputHandler | ✅ | Implementation: beforeinput/keydown, setComposing, syncFocusedTextNodeAfterComposition. Not unit tested. |
+| §8.2 handleDomMutations, C1 | ✅ | Implementation: classifyDomChangeC1, replaceText. classifyDomChangeC1 not unit tested (requires Editor + mutations). |
+| §8.3 dom-sync | ✅ | Test: findClosestInlineTextNode (element, child, no ancestor, null); reconstructModelTextFromDOM (concatenated text, empty). |
+
+---
+
+## §9 MutationObserver
+
+| Spec section | Verified | Notes |
+|--------------|----------|--------|
+| §9.1 ReactMutationObserverManager | ✅ | Test: setup(element) observes and invokes callback with batched mutations (setTimeout 0); disconnect() stops observing and callback not called after disconnect. |
+| §9.2 Wiring | ✅ | Implementation: Provider creates manager with onMutations = inputHandler.handleDomMutations; ContentLayer setContentEditableElement. |
+
+---
+
+## §10 Test Strategy
+
+| Spec section | Verified | Notes |
+|--------------|----------|--------|
+| §10.2 Required test categories | ✅ | EditorViewContextProvider (value, useEditorViewContext throw, useOptionalEditorViewContext null). EditorView (root, content layer, options.className, overlay layers, children). EditorViewContentLayer (presence and attributes; subscription behavior not asserted). EditorViewLayer (data-bc-layer, style, default classNames/zIndex). ReactSelectionHandler (instantiate, isSelectionInsideEditableText, setProgrammaticChange). ReactMutationObserverManager (setup/disconnect, batch). dom-sync (findClosestInlineTextNode, reconstructModelTextFromDOM). |
+| §10.3 Test environment | ✅ | Vitest, jsdom, @testing-library/react. Mock Editor used in tests. |
+
+---
+
+## Checklist (Concrete) — Spec §11
+
+- [x] EditorViewContextProvider provides editor, viewStateRef, selectionHandler, inputHandler, mutationObserverManager, setContentEditableElement.
+- [x] useEditorViewContext throws outside Provider; useOptionalEditorViewContext returns null outside.
+- [x] EditorView renders content layer; overlay layers only when options.layers.* set; children in CustomLayer.
+- [x] EditorViewContentLayer subscribes to editor:content.change and editor:selection.model; setContentEditableElement(ref) on mount/unmount. (Implementation verified; not asserted in tests.)
+- [x] EditorViewLayer renders with data-bc-layer, position absolute, pointer-events none, default classNames/zIndex.
+- [x] ReactSelectionHandler convertDOMSelectionToModel / isSelectionInsideEditableText / setProgrammaticChange behave as spec. (isSelectionInsideEditableText and setProgrammaticChange tested; convertDOMSelectionToModel not.)
+- [x] ReactMutationObserverManager setup/disconnect and batch callback.
+- [x] findClosestInlineTextNode, reconstructModelTextFromDOM behave as spec. (classifyDomChangeC1 not tested.)
+
+---
+
+## Gaps (optional future tests)
+
+- **EditorViewContentLayer**: Assert editor.on('editor:content.change') and editor.on('editor:selection.model') called; setContentEditableElement called with ref on mount and null on unmount (with mock Editor and spy).
+- **classifyDomChangeC1**: Unit test with mock Editor, mutations array, and options; assert C1 or UNKNOWN.
+- **ReactSelectionHandler.convertDOMSelectionToModel**: Unit test with full DOM (data-bc-sid nodes, text runs) and mock Editor.dataStore.getNode; assert ModelSelection shape.
+- **ReactInputHandler**: beforeinput/keydown handling with mock Editor and executeCommand spy.

package/docs/editor-view-react-spec.md

@@ -0,0 +1,359 @@
+# editor-view-react Specification
+
+This document defines the spec for `@barocss/editor-view-react`: goals, architecture, API, context, layers, selection/input flow, DOM sync, and test strategy.
+
+---
+
+## Table of Contents
+
+1. [Goals and Scope](#1-goals-and-scope)
+2. [Architecture](#2-architecture)
+3. [API Contract](#3-api-contract)
+4. [Context and View State](#4-context-and-view-state)
+5. [Layers](#5-layers)
+6. [Content Layer and Renderer](#6-content-layer-and-renderer)
+7. [Selection Flow](#7-selection-flow)
+8. [Input and DOM Sync](#8-input-and-dom-sync)
+9. [MutationObserver](#9-mutationobserver)
+10. [Test Strategy and Required Tests](#10-test-strategy-and-required-tests)
+11. [Out of Scope and Future](#11-out-of-scope-and-future)
+
+---
+
+## 1. Goals and Scope
+
+### 1.1 Goals
+
+- **React view layer for Barocss Editor**: Renders the editor document with **renderer-react** (DSL → ReactNode) and re-renders on `editor:content.change`. React counterpart of **editor-view-dom**.
+- **Same Editor/DataStore model**: Uses `Editor` from `@barocss/editor-core` (getDocumentProxy, on/off for events). Same registry and model shape as editor-view-dom for sid/stype semantics.
+- **Selection and input**: DOM selection ↔ model selection via `ReactSelectionHandler`; beforeinput/keydown and DOM mutations via `ReactInputHandler` and `ReactMutationObserverManager`. No dependency on editor-view-dom.
+
+### 1.2 Scope
+
+| In scope | Out of scope |
+|----------|--------------|
+| EditorView composite, EditorViewContentLayer, EditorViewLayer | Full E2E typing tests (apps/editor-react) |
+| EditorViewContext (editor, selectionHandler, inputHandler, mutationObserverManager, viewState) | Decorator/selection overlay rendering (layer slots only) |
+| ReactRenderer + contenteditable div, editor:content.change subscription | renderer-react internals |
+| editor:selection.model → convertModelSelectionToDOM (requestAnimationFrame) | editor-core selection internals |
+| selectionchange → convertDOMSelectionToModel → editor.updateSelection | DOM reconciliation (React) |
+| beforeinput/keydown → commands (replaceText, insertParagraph, etc.) | Command implementations (extensions) |
+| MutationObserver → C1 classification → replaceText / structural commands | when()/each() in templates |
+| data-bc-sid, data-bc-stype on content (from renderer-react) | Portals, decorator DOM |
+
+---
+
+## 2. Architecture
+
+### 2.1 Pipeline
+
+```
+Editor (editor-core)
+    ↓
+EditorViewContextProvider
+    → viewStateRef (isModelDrivenChange, isRendering, isComposing, skipNextRenderFromMO, skipApplyModelSelectionToDOM)
+    → ReactSelectionHandler(editor, getContentEditableElement)
+    → ReactInputHandler(editor, selectionHandler, viewStateRef)
+    → createMutationObserverManager(mutations => inputHandler.handleDomMutations(mutations))
+    → setContentEditableElement(el) — connect/disconnect observer
+    ↓
+EditorView (composite)
+    → EditorViewContentLayer (contenteditable, ReactRenderer.build(documentSnapshot), editor:content.change, editor:selection.model)
+    → EditorView.DecoratorLayer | SelectionLayer | ContextLayer | CustomLayer (EditorViewLayer overlay)
+```
+
+### 2.2 Dependencies
+
+- **@barocss/dsl**: RendererRegistry, getGlobalRegistry.
+- **@barocss/editor-core**: Editor, fromDOMSelection.
+- **@barocss/renderer-react**: ReactRenderer.
+- **@barocss/shared**: getKeyString.
+- **@barocss/text-analyzer**: analyzeTextChanges.
+- **@barocss/shared**: buildTextRunIndex, binarySearchRun, ContainerRuns (text-run-index API).
+- **react**, **react-dom**: Context, hooks, DOM refs.
+
+No dependency on **editor-view-dom** or **renderer-dom**.
+
+### 2.3 Data Flow
+
+- **Content**: editor.getDocumentProxy() → documentSnapshot state → ReactRenderer.build(model) → contenteditable div children. On editor:content.change → setDocumentSnapshot(e.content ?? getDocumentProxy()).
+- **Selection (model → DOM)**: editor:selection.model → skipApplyModelSelectionToDOM check → requestAnimationFrame ×2 → selectionHandler.convertModelSelectionToDOM(sel).
+- **Selection (DOM → model)**: document selectionchange → selectionHandler.handleSelectionChange → convertDOMSelectionToModel → editor.updateSelection(modelSelection).
+- **Input**: contenteditable receives input → beforeinput/keydown captured (if wired) → ReactInputHandler runs commands; or MutationObserver → handleDomMutations → C1 classify → replaceText.
+
+---
+
+## 3. API Contract
+
+### 3.1 Exports
+
+| Export | Type | Description |
+|--------|------|-------------|
+| EditorView | Component | Composite view; provides EditorViewContextProvider and content + overlay layers. |
+| EditorViewContentLayer | Component | Renders document with ReactRenderer in contenteditable div. Must be inside EditorViewContext. |
+| EditorViewLayer | Component | Overlay layer wrapper (layer prop: decorator \| selection \| context \| custom). |
+| EditorViewContextProvider | Component | Provides editor, viewStateRef, selectionHandler, inputHandler, mutationObserverManager, setContentEditableElement. |
+| useEditorViewContext | Hook | Returns EditorViewContextValue; throws if not inside Provider. |
+| useOptionalEditorViewContext | Hook | Returns value or null. |
+| createMutationObserverManager | Function | (onMutations) => ReactMutationObserverManager. |
+| Types | — | EditorViewOptions, EditorViewProps, EditorViewRef, EditorViewHandle, EditorViewContentLayerOptions, EditorViewLayerOptions, EditorViewLayersConfig, EditorViewLayerType, DecoratorExportData, LoadDecoratorsPatternFunctions, DecoratorQueryOptions, DecoratorTypeSchema, ModelSelection, EditorViewViewState, EditorViewContextValue, ReactMutationObserverManager. |
+
+### 3.2 EditorView Props
+
+- **editor**: Editor (required).
+- **options**: Optional.
+  - **registry**: RendererRegistry (for content layer).
+  - **className**: string (root container).
+  - **layers**: EditorViewLayersConfig — content?, decorator?, selection?, context?, custom? (optional className/style overrides; all four overlay layers are always rendered).
+- **children**: ReactNode (rendered inside CustomLayer after overlay decorators).
+
+Decorators are managed internally; use the ref API (EditorViewHandle) when using a ref on EditorView.
+
+### 3.3 EditorView ref (EditorViewHandle)
+
+When using `ref` on EditorView, the following are exposed (parity with editor-view-dom where applicable):
+
+- **addDecorator(decorator: Decorator | DecoratorGenerator)** — Add a target decorator or register a DecoratorGenerator (function-based decorators). Generators are registered with `decoratorGeneratorManager` and their output is included in merged decorators.
+- **removeDecorator(id)**, **updateDecorator(id, updates)** — Remove or update a decorator by id.
+- **getDecorators(options?: DecoratorQueryOptions)** — Return merged decorators (local + remote + pattern-generated + generator-generated), optionally filtered/sorted by category, type, nodeId, enabledOnly, sortBy, sortOrder.
+- **getDecorator(id)** — Return a single decorator or generator by id (searches merged, then local, then remote).
+- **exportDecorators()**, **loadDecorators(data, patternFunctions?)** — Serialize/restore target and pattern decorators; pattern functions provided at load time for pattern logic.
+- **contentEditableElement** — HTMLElement | null (content-editable root).
+- **convertModelSelectionToDOM(sel)**, **convertDOMSelectionToModel(selection)**, **convertStaticRangeToModel(staticRange)** — Selection conversion between model and DOM/StaticRange.
+- **defineDecoratorType(type, category, schema)** — Register a decorator type schema (DecoratorTypeSchema) for validation and defaults when adding decorators; uses shared DecoratorSchemaRegistry.
+- **decoratorManager**, **remoteDecoratorManager**, **patternDecoratorConfigManager**, **decoratorGeneratorManager** — Refs to the shared manager instances (nullable).
+
+Types: `DecoratorExportData`, `LoadDecoratorsPatternFunctions`, `DecoratorQueryOptions`, `DecoratorTypeSchema`, `ModelSelection` are exported from the package (re-exported from `@barocss/shared` where applicable).
+
+### 3.4 EditorViewContentLayer Props
+
+- **options**: Optional.
+  - **registry**: RendererRegistry (default getGlobalRegistry()).
+  - **className**: string (contenteditable wrapper).
+  - **editable**: boolean (default true).
+
+Decorators are taken from internal DecoratorManager (context); no options.decorators or getDecorators. Editor is taken from EditorViewContext only.
+
+### 3.5 EditorViewLayer Props
+
+- **layer**: 'decorator' | 'selection' | 'context' | 'custom'.
+- **className**: Optional string.
+- **style**: Optional React.CSSProperties.
+- **children**: Optional ReactNode.
+
+Default classNames and zIndex per layer: decorator (barocss-editor-decorators, 10), selection (barocss-editor-selection, 100), context (barocss-editor-context, 200), custom (barocss-editor-custom, 1000). Position absolute, pointer-events: none.
+
+### 3.6 EditorView Static Subcomponents
+
+- **EditorView.ContentLayer** = EditorViewContentLayer.
+- **EditorView.Layer** = EditorViewLayer (generic; pass layer prop).
+- **EditorView.DecoratorLayer**, **EditorView.SelectionLayer**, **EditorView.ContextLayer**, **EditorView.CustomLayer** = overlay layers with fixed layer type.
+
+---
+
+## 4. Context and View State
+
+### 4.1 EditorViewContextValue
+
+- **editor**: Editor.
+- **viewStateRef**: MutableRefObject<EditorViewViewState>.
+- **selectionHandler**: ReactSelectionHandler.
+- **inputHandler**: ReactInputHandler.
+- **mutationObserverManager**: ReactMutationObserverManager.
+- **setContentEditableElement**: (el: HTMLElement | null) => void.
+
+### 4.2 EditorViewViewState
+
+- **isModelDrivenChange**: boolean.
+- **isRendering**: boolean.
+- **isComposing**: boolean.
+- **skipNextRenderFromMO**: boolean — when true, next editor:content.change (from model commit during MO C1) must not trigger refresh (data-only update).
+- **skipApplyModelSelectionToDOM**: boolean — when true, editor:selection.model must not call convertModelSelectionToDOM (selection came from DOM input; leave DOM selection as-is).
+
+### 4.3 Lifecycle
+
+- EditorViewContextProvider creates viewStateRef, contentEditableRef, selectionHandler (useMemo), inputHandler (useMemo), mutationObserverManager (useMemo), setContentEditableElement (useCallback). Subscribes to document selectionchange for selectionHandler.handleSelectionChange.
+- EditorViewContentLayer: on mount/update calls setContentEditableElement(contentRef.current); on unmount setContentEditableElement(null). Subscribes to editor:content.change and editor:selection.model.
+
+---
+
+## 5. Layers
+
+See **layers-spec.md** for layerTarget semantics and how selection/context/custom layers are intended to be used.
+
+### 5.1 Content Layer
+
+- Single contenteditable div. data-bc-layer="content", data-testid="editor-content".
+- Renders documentSnapshot via ReactRenderer.build(model, decorators). Decorators come from internal DecoratorManager; inline/block (and layerTarget content) are rendered in the same tree as content. Subscribes to editor:content.change to update documentSnapshot.
+- Ref passed to setContentEditableElement so MutationObserver and selection resolution use the same root.
+
+### 5.2 Overlay Layers
+
+- **decorator**, **selection**, **context**, **custom**: Each is a div with position absolute, full inset, pointer-events: none, data-bc-layer={layer}. All four are always rendered. Content: decorators with layerTarget === that layer are rendered via ReactRenderer.buildOverlayDecorators(filtered). Custom layer also renders EditorView children after overlay decorators.
+
+### 5.3 Rendering in EditorView
+
+- Content layer always rendered (with merged options from options.layers?.content).
+- All four overlay layers (decorator, selection, context, custom) are always rendered. options.layers?.decorator|selection|context|custom supply optional className and style only. Children are rendered inside CustomLayer after overlay decorators.
+
+---
+
+## 6. Content Layer and Renderer
+
+### 6.1 Document Snapshot
+
+- Initial state: editor.getDocumentProxy?.() ?? null.
+- On editor:content.change: setDocumentSnapshot(e?.content ?? editor.getDocumentProxy?.() ?? null).
+- If documentSnapshot is null or has no stype, content layer renders null (empty div).
+
+### 6.2 ReactRenderer
+
+- useMemo(() => new ReactRenderer(registry ?? getGlobalRegistry()), [registry]).
+- decorators = getMergedDecorators(documentSnapshot) (local + remote + pattern-from-model + generator-from-model).
+- content = useMemo(() => documentSnapshot != null && model.stype ? renderer.build(model, decorators) : null, [documentSnapshot, renderer, decorators]).
+- Same registry and model shape as renderer-dom for parity (sid, stype, content, text, marks, decorators).
+
+### 6.3 Decorator source and updates (vs editor-view-dom)
+
+- **editor-view-dom**: Decorators live **inside** the view (DecoratorManager, RemoteDecoratorManager, DecoratorGeneratorManager, PatternDecoratorConfigManager). When render() is called, the view reads decorators from these managers and passes them to DOMRenderer.render(container, model, allDecorators, …).
+- **editor-view-react**: Same: decorators live **inside** the view. Context holds DecoratorManager, RemoteDecoratorManager, PatternDecoratorConfigManager, DecoratorGeneratorManager. Content and overlay layers use **getMergedDecorators(model)** (local + remote + pattern-from-model + generator-from-model). Ref exposes addDecorator, removeDecorator, updateDecorator, getDecorators(), and the four managers. No decorators passed from outside via options.
+
+### 6.4 Contenteditable
+
+- contentEditable={editable} (default true). suppressContentEditableWarning. className and options from props.
+
+---
+
+## 7. Selection Flow
+
+### 7.1 DOM → Model
+
+- **selectionchange** (document): selectionHandler.handleSelectionChange(). If not programmatic and selection inside contentEditable, convertDOMSelectionToModel(selection) → editor.updateSelection(modelSelection).
+- **convertDOMSelectionToModel**: Uses data-bc-sid nodes and text-run-index (buildTextRunIndex, offset conversion) to produce ModelSelection (none | range | node). Skips nodes with data-devtool.
+
+### 7.2 Model → DOM
+
+- **editor:selection.model**: If !skipApplyModelSelectionToDOM, requestAnimationFrame ×2 then selectionHandler.convertModelSelectionToDOM(sel). Converts model range to DOM range and sets selection.
+
+### 7.3 ReactSelectionHandler
+
+- **isSelectionInsideEditableText(domSelection?)**: Returns true if selection is entirely inside inline-text nodes (data-bc-sid + model.stype === 'inline-text').
+- **setProgrammaticChange(value)**: When true, handleSelectionChange no-ops (avoids feedback loop when applying model selection to DOM).
+- **convertModelSelectionToDOM**: Resolves sid + offset to DOM node + offset; uses text-run-index and buildTextRunIndex. Sets window.getSelection() range.
+
+---
+
+## 8. Input and DOM Sync
+
+### 8.1 ReactInputHandler
+
+- **beforeinput / keydown**: Dispatches to replaceText, insertParagraph, deleteContentBackward, etc., based on inputType and key. Uses selectionHandler for current model selection and isSelectionInsideEditableText.
+- **setComposing(isComposing)**: Updates viewStateRef.current.isComposing (and viewState for consumers).
+- **syncFocusedTextNodeAfterComposition**: After compositionend, reconstructs DOM text of focused inline-text node, compares to model; if different, executeCommand('replaceText', …) and update model selection; sets skipApplyModelSelectionToDOM during apply.
+
+### 8.2 handleDomMutations
+
+- MutationObserver batches mutations (setTimeout 0) then calls inputHandler.handleDomMutations(mutations).
+- **classifyDomChangeC1(mutations, options)**: If mutations are confined to a single inline-text node (data-bc-sid, stype === 'inline-text') and no block-like nodes added/removed, returns ClassifiedChangeC1 { nodeId, prevText, newText, … }. Otherwise UNKNOWN.
+- **C1 path**: replaceText command with range and text from classification. Optionally skipNextRenderFromMO to avoid double refresh.
+- **Structural / UNKNOWN**: Can trigger other commands or no-op; behavior is implementation-specific.
+
+### 8.3 DOM Sync Utilities (dom-sync)
+
+- **findClosestInlineTextNode(node)**: Walk up to find Element with data-bc-sid (any; caller checks model stype if needed).
+- **reconstructModelTextFromDOM(inlineTextNode)**: buildTextRunIndex(inner text runs) and concatenate text. Used for C1 newText and syncFocusedTextNodeAfterComposition.
+- **classifyDomChangeC1**: Ported from editor-view-dom C1; uses editor, selection, modelSelection, inputHint, isComposing.
+
+---
+
+## 9. MutationObserver
+
+### 9.1 ReactMutationObserverManager
+
+- **setup(contentEditableElement)**: Disconnect previous observer; create MutationObserver with observe(..., { childList: true, subtree: true, characterData: true, attributes: true, attributeFilter: ['data-bc-edit', 'data-bc-value', 'data-bc-sid', 'data-bc-stype'], characterDataOldValue: true, attributeOldValue: true }). On mutation, push to pending; setTimeout(0) then invoke onMutations(pending) and clear pending.
+- **disconnect()**: Disconnect observer, clear timer and pending.
+
+### 9.2 Wiring
+
+- EditorViewContextProvider creates manager with onMutations = (mutations) => inputHandler.handleDomMutations(mutations).
+- EditorViewContentLayer sets ref → setContentEditableElement(el). Context setContentEditableElement: on change, disconnect from old element, assign ref, setup(new element).
+
+---
+
+## 10. Test Strategy and Required Tests
+
+### 10.1 Principles
+
+- **Spec-first**: Tests assert behavior described in this spec (context, layers, selection/input wiring, DOM sync).
+- **Unit where possible**: ReactSelectionHandler, ReactInputHandler, createMutationObserverManager, classifyDomChangeC1, findClosestInlineTextNode, reconstructModelTextFromDOM can be tested with mocks.
+- **Integration**: EditorView mount with mock Editor (getDocumentProxy, on/off), assert content layer renders, context provides handlers, layers render when configured.
+
+### 10.2 Required Test Categories
+
+1. **EditorViewContextProvider**
+   - Provides editor, selectionHandler, inputHandler, mutationObserverManager, setContentEditableElement, viewStateRef.
+   - useEditorViewContext throws when outside Provider; useOptionalEditorViewContext returns null.
+
+2. **EditorView**
+   - Renders content layer with merged options (registry, className, editable).
+   - Renders overlay layers only when options.layers?.decorator etc. are set.
+   - Renders children inside CustomLayer when layers.custom or children present.
+   - Root div has data-editor-view="true", position relative.
+
+3. **EditorViewContentLayer**
+   - Subscribes to editor:content.change; documentSnapshot updates; renderer.build called with snapshot.
+   - Subscribes to editor:selection.model; when !skipApplyModelSelectionToDOM, convertModelSelectionToDOM called (e.g. in rAF).
+   - setContentEditableElement called with ref on mount and null on unmount.
+   - contenteditable div has data-bc-layer="content", data-testid="editor-content".
+
+4. **EditorViewLayer**
+   - Renders div with data-bc-layer={layer}, position absolute, pointer-events none, correct default className and zIndex per layer type.
+
+5. **ReactSelectionHandler**
+   - convertDOMSelectionToModel with mock Editor and DOM (data-bc-sid nodes) returns expected ModelSelection.
+   - isSelectionInsideEditableText returns true/false for selection inside/outside inline-text.
+   - setProgrammaticChange(true) causes handleSelectionChange to skip updateSelection.
+
+6. **ReactMutationObserverManager**
+   - setup(element) observes element; disconnect() stops observing. Callback invoked with batched mutations (setTimeout 0).
+
+7. **dom-sync**
+   - findClosestInlineTextNode returns closest element with data-bc-sid.
+   - reconstructModelTextFromDOM returns concatenated text from text runs.
+   - classifyDomChangeC1 returns C1 or null for given mutations and options.
+
+### 10.3 Test Environment
+
+- **Vitest** for unit tests. **React Testing Library** (or @testing-library/react) for component tests if needed. JSDOM for DOM/selection tests.
+- Mock Editor: getDocumentProxy(), on(), off(), updateSelection(), executeCommand(), dataStore.getNode().
+
+---
+
+## 11. References and analysis
+
+- **React editing view analysis**: `packages/renderer-react/docs/editing-view-react-analysis.md` — comparison with ProseMirror/Lexical/TipTap, risks (cursor, IME, reconciliation), and improvements (skipNextRenderFromMO, E2E).
+
+---
+
+## 12. Out of Scope and Future
+
+| Feature | Current | Future |
+|---------|---------|--------|
+| Decorator DOM rendering | Layer slot only; no built-in decorator DOM | Optional decorator list and overlay DOM |
+| E2E typing/selection in app | Manual or apps/editor-react E2E | Playwright E2E for editor-react |
+| when()/each() in templates | Handled by renderer-react (unsupported) | — |
+| IME composition edge cases | syncFocusedTextNodeAfterComposition; composition state in viewState | More tests and edge cases |
+| Portal / overlay positioning | Layers are absolute full-size | Fine-grained positioning if needed |
+
+---
+
+## Checklist (Concrete)
+
+- [x] EditorViewContextProvider provides editor, viewStateRef, selectionHandler, inputHandler, mutationObserverManager, setContentEditableElement.
+- [x] useEditorViewContext throws outside Provider; useOptionalEditorViewContext returns null outside.
+- [x] EditorView renders content layer; overlay layers only when options.layers.* set; children in CustomLayer.
+- [x] EditorViewContentLayer subscribes to editor:content.change and editor:selection.model; setContentEditableElement(ref) on mount/unmount (implementation; see SPEC_VERIFICATION.md).
+- [x] EditorViewLayer renders with data-bc-layer, position absolute, pointer-events none, default classNames/zIndex.
+- [x] ReactSelectionHandler isSelectionInsideEditableText / setProgrammaticChange behave as spec (convertDOMSelectionToModel covered by implementation).
+- [x] ReactMutationObserverManager setup/disconnect and batch callback.
+- [x] findClosestInlineTextNode, reconstructModelTextFromDOM behave as spec (classifyDomChangeC1 implementation verified; optional unit test).

package/docs/improvement-opportunities.md

@@ -0,0 +1,66 @@
+# editor-view-dom / editor-view-react 개선 후보
+
+editor-view-dom과 editor-view-react를 비교·분석한 결과, 아래 개선이 가능하다.
+
+**적용 완료 (1–4번)**: DecoratorExportData/LoadDecoratorsPatternFunctions shared 통일, addDecorator(DecoratorGenerator) 지원, IEditorViewDOM 타입 정리, 스펙/README 업데이트.
+
+---
+
+## 1. editor-view-dom
+
+### 1.1 DecoratorExportData·LoadDecoratorsPatternFunctions를 shared에서 사용
+
+- **현재**: `packages/editor-view-dom/src/types.ts`에 `DecoratorExportData`가 로컬로 정의되어 있고, `loadDecorators`의 `patternFunctions`는 인라인 타입으로만 정의됨.
+- **개선**: `DecoratorExportData`, `LoadDecoratorsPatternFunctions`를 `@barocss/shared`에서 import하고, editor-view-dom의 types에서 해당 정의 제거. `loadDecorators` 시그니처에 `LoadDecoratorsPatternFunctions` 사용.
+- **효과**: 타입 중복 제거, shared와 시그니처 일치.
+
+### 1.2 IEditorViewDOM 타입 정리
+
+- **현재**: `getDecorators?(options?: any): any[]`로 되어 있음.
+- **개선**: `getDecorators(options?: DecoratorQueryOptions): (Decorator | DecoratorGenerator)[]`로 명시. `defineDecoratorType`의 `schema` 인자 타입을 shared의 `DecoratorTypeSchema`로 통일.
+- **효과**: 타입 안정성·자동완성 개선, editor-view-react와 개념적 일치.
+
+---
+
+## 2. editor-view-react
+
+### 2.1 addDecorator에 DecoratorGenerator 지원
+
+- **현재**: `addDecorator(decorator: Decorator)`만 받음. editor-view-dom은 `addDecorator(decorator: Decorator | DecoratorGenerator)`를 지원함.
+- **개선**: `EditorViewHandle.addDecorator(decorator: Decorator | DecoratorGenerator)`로 확장. `DecoratorGenerator`인 경우 `decoratorGeneratorManagerRef.current?.registerGenerator(generator, bumpDecoratorVersion)` 호출 후 `bumpDecoratorVersion()` 호출.
+- **효과**: DOM 뷰와 동일하게 generator 기반 데코레이터 등록 가능, API 일치.
+
+### 2.2 ref.destroy() (선택)
+
+- **현재**: editor-view-dom은 `view.destroy()`로 이벤트/observer/레이어 정리. editor-view-react는 언마운트 시 `useEffect` cleanup으로 observer 해제·이벤트 해제.
+- **개선**: ref에 `destroy?(): void`를 두고, 호출 시 데코레이터 매니저 clear·버전 bump 등 선택적 정리만 수행. React는 언마운트가 곧 정리이므로 필수는 아님.
+- **효과**: DOM과 동일한 “명시적 정리” API를 쓰고 싶을 때 사용 가능. 우선순위는 낮음.
+
+---
+
+## 3. 공통·문서
+
+### 3.1 스펙/README 반영
+
+- **editor-view-react**: `editor-view-react-spec.md`, `README.md`에 최근 추가된 ref API 반영  
+  (`defineDecoratorType`, `convertStaticRangeToModel`, `getDecorators(options?)`, `DecoratorSchemaRegistry` 사용).
+- **editor-view-dom**: README/문서에 `LoadDecoratorsPatternFunctions`, `DecoratorQueryOptions` 등 shared 타입 사용 여부 명시.
+
+### 3.2 테스트
+
+- **editor-view-react**: `addDecorator(DecoratorGenerator)` 지원 시, generator 등록 후 `getDecorators()`에 반영되는지 한 번 더 검증하는 테스트 추가.
+- **editor-view-dom**: `DecoratorExportData`를 shared에서 쓰도록 바꾼 뒤, 기존 export/load 관련 테스트가 그대로 통과하는지 확인.
+
+---
+
+## 우선순위 제안
+
+| 순서 | 항목 | 패키지 | 비고 |
+|------|------|--------|------|
+| 1 | DecoratorExportData·LoadDecoratorsPatternFunctions를 shared로 통일 | editor-view-dom | 타입 일원화 |
+| 2 | addDecorator(DecoratorGenerator) 지원 | editor-view-react | DOM과 API parity |
+| 3 | IEditorViewDOM getDecorators·defineDecoratorType 타입 정리 | editor-view-dom | 타입 품질 |
+| 4 | 스펙/README 업데이트 | 둘 다 | 유지보수성 |
+| 5 | ref.destroy() (선택) | editor-view-react | 필요 시 추가 |
+
+원하면 위 항목별로 이슈/PR 단위로 나눠서 적용할 수 있다.

package/docs/layers-spec.md

@@ -0,0 +1,97 @@
+# Editor View Layers Specification
+
+This document defines the five layers used by editor-view-dom and editor-view-react: content, decorator, selection, context, and custom. It describes how `layerTarget` routes decorators to layers and how each layer is intended to be used.
+
+---
+
+## 1. Layer Overview
+
+| Layer      | data-bc-layer | Purpose |
+|-----------|----------------|---------|
+| content   | content        | Document + inline/block decorators (content flow). Single contenteditable root. |
+| decorator | decorator      | Overlay decorators (e.g. comment bubbles, floating annotations). |
+| selection | selection      | Selection/cursor indicators (range highlight, caret). |
+| context   | context        | Context UI (tooltips, autocomplete, menus). |
+| custom    | custom         | App-defined overlay + optional children. |
+
+All overlay layers (decorator, selection, context, custom) are positioned absolute over the content layer, with `pointer-events: none` by default so the content layer receives input. Default z-index: decorator 10, selection 100, context 200, custom 1000.
+
+---
+
+## 2. layerTarget and Routing
+
+Decorators have an optional `layerTarget?: 'content' | 'decorator' | 'selection' | 'context' | 'custom'`.
+
+- **content** (default for inline/block): Rendered inside the content layer in the document tree (inline/block slots). Do not render in overlay layers.
+- **decorator**: Rendered only in the decorator overlay layer (e.g. comment popover, annotation).
+- **selection**: Rendered only in the selection overlay layer (e.g. cursor div, range highlight).
+- **context**: Rendered only in the context overlay layer (e.g. tooltip, autocomplete popup).
+- **custom**: Rendered only in the custom overlay layer (e.g. custom floating UI).
+
+When `layerTarget` is omitted, inline/block decorators default to content; layer-category decorators default to decorator (editor-view-dom DecoratorPrebuilder). In editor-view-react, overlay content is built with `ReactRenderer.buildOverlayDecorators(decorators)` per layer, with decorators filtered by `layerTarget === layer`.
+
+---
+
+## 3. Content Layer
+
+- **Role**: Document body and inline/block decorators that participate in the content flow.
+- **Rendering**: Single contenteditable div. Document model is rendered via ReactRenderer.build(model, decorators). Inline and block decorators (and layer decorators with layerTarget content) are rendered in the same tree (before/after/overlay slots).
+- **Usage**: No app code; view manages document and decorators internally.
+
+---
+
+## 4. Decorator Layer
+
+- **Role**: Overlay decorators that float above content (e.g. comment bubbles, annotations) without being part of the content flow.
+- **Usage**: Add a decorator with `category: 'layer'` and `layerTarget: 'decorator'` (or omit layerTarget for layer category). The view renders it in the decorator overlay via buildOverlayDecorators. Position/size can be set in decorator.data (e.g. data.position for absolute coordinates).
+
+---
+
+## 5. Selection Layer
+
+- **Role**: Visual representation of the current selection or cursor (caret, range highlight).
+- **Usage**: Add decorators with `layerTarget: 'selection'`. Typical use: cursor (collapsed range) or range highlight. In editor-view-dom tests, the selection layer is also used by appending DOM (e.g. a cursor div) directly to `view.layers.selection`. In editor-view-react, selection visuals are driven by decorators with layerTarget 'selection' rendered via buildOverlayDecorators. Future: model selection could be mapped to one or more selection-layer decorators by the view or app.
+
+---
+
+## 6. Context Layer
+
+- **Role**: Contextual UI that appears near the selection or a target (tooltips, autocomplete, inline menus).
+- **Usage**: Add decorators with `layerTarget: 'context'`. Example: tooltip decorator with data.text, or autocomplete popup. Position in data.position. In editor-view-dom tests, context layer is used for tooltips and autocomplete popup.
+
+---
+
+## 7. Custom Layer
+
+- **Role**: App-defined overlay content plus optional React children.
+- **Usage**:
+  - **Decorators**: Add decorators with `layerTarget: 'custom'`; they are rendered in the custom overlay.
+  - **Children**: Pass children to EditorView; they are rendered inside the custom layer after the overlay decorators. Use for custom UI (floating buttons, panels) that are not driven by the decorator model.
+
+---
+
+## 8. Parity with editor-view-dom
+
+- editor-view-dom: Content layer uses DOMRenderer.render(); overlay layers use DecoratorPrebuilder to build DecoratorModels, split by layerTarget, then _decoratorRenderer/_selectionRenderer/_contextRenderer/_customRenderer.renderChildren(layerElement, models).
+- editor-view-react: Content layer uses ReactRenderer.build(model, decorators); overlay layers use EditorViewOverlayLayerContent per layer, which filters decorators by layerTarget and calls ReactRenderer.buildOverlayDecorators(filtered). Same layerTarget semantics and layer order (content, then decorator, selection, context, custom).
+
+---
+
+## 9. References
+
+- editor-view-dom: `packages/editor-view-dom/src/editor-view-dom.ts` (_renderLayers, layerTarget switch), `packages/editor-view-dom/docs/decorator-guide.md`, `packages/editor-view-dom/test/core/layered-api.test.ts`, `packages/editor-view-dom/test/integration/pattern-custom-decorator-render.test.ts`.
+- editor-view-react: EditorViewOverlayLayerContent, EditorView.tsx (DecoratorLayerSlot, SelectionLayerSlot, ContextLayerSlot, CustomLayerSlot), editor-view-react-spec.md (Layers section).
+
+---
+
+## 10. Decorator improvements (future)
+
+Possible improvements to align behavior and reduce drift:
+
+| Item | Description |
+|------|-------------|
+| **Decorator range adjustment on text edit** | When the user types, inline decorator ranges (startOffset/endOffset) should be adjusted so they stay correct. editor-view-dom computes `adjustedDecorators` in handleEfficientEdit (via dataStore.decorators.adjustRanges or edit-position-converter) but applying them back to DecoratorManager is still TODO. editor-view-react does not yet run any adjust step after replaceText. Adding this in both views would keep decorators in sync with content. |
+| **Single Decorator type source** | Decorator is defined in editor-view-dom, shared, and renderer-react. Unifying on shared (and re-exporting or extending in the other packages) would avoid drift. |
+| **ref.updateDecorator(id, updates)** | editor-view-dom exposes updateDecorator(id, updates). editor-view-react ref currently has addDecorator, removeDecorator, getDecorators; adding updateDecorator would call DecoratorManager.update for parity. |
+| **Optional DecoratorRegistry in editor-view-react** | editor-view-dom uses DecoratorRegistry for validation and default values when adding decorators. editor-view-react uses DecoratorManager without a validator; an optional registry would allow the same validation/defaults. |
+| **Remote / Pattern / Generator** | editor-view-react provides RemoteDecoratorManager, PatternDecoratorConfigManager, and DecoratorGeneratorManager via ref. Merged decorators (local + remote + pattern-from-model + generator-from-model) are used for content and overlay rendering. |