hidden DOM selection과 overlay selection 표시 lifecycle 조사

[developer-1px]

조사할 것

model selection이 항상 native DOM selection으로 그대로 보이면 안 되는 경우가 있다. hidden selection class, cursor wrapper, node selection 표시를 어떤 lifecycle로 관리해야 하는지 조사한다.

prosemirror-view 근거

• selectionToDOM은 NodeSelection 표시를 sync한 뒤 editor가 selection을 소유할 때만 DOM selection을 갱신한다.
  https://github.com/ProseMirror/prosemirror-view/blob/ca4c78e9b56f1b164c0b3758b59d8748f11b7534/src/selection.ts#L55-L76
• invisible selection에서는 ProseMirror-hideselection class를 붙이고 selectionchange 후 지연 제거한다.
  https://github.com/ProseMirror/prosemirror-view/blob/ca4c78e9b56f1b164c0b3758b59d8748f11b7534/src/selection.ts#L92-L147
• cursor wrapper 선택은 실제 DOM selection을 wrapper 주변으로 강제한다.
  https://github.com/ProseMirror/prosemirror-view/blob/ca4c78e9b56f1b164c0b3758b59d8748f11b7534/src/selection.ts#L149-L164
• node selection은 selectNode/deselectNode hook으로 DOM state를 정리한다.
  https://github.com/ProseMirror/prosemirror-view/blob/ca4c78e9b56f1b164c0b3758b59d8748f11b7534/src/selection.ts#L166-L185

우리 에디터에서 확인할 것

• block selection, figure selection, mention selection이 native selection과 overlay selection 중 무엇으로 표현되어야 하는지 정한다.
• selection hidden class가 focus/blur, drag, toolbar click 뒤에 남지 않는지 확인한다.

완료 기준

• selection visibility state machine을 정의한다.
• hidden selection class leak 재현 테스트를 만든다.
• node selection과 text selection 전환 시 DOM cleanup 기준을 정한다.

[developer-1px]

처리 완료했습니다.

• docs/editor-selection-visibility-lifecycle-audit.md를 추가해 selection visibility state machine, native range/custom overlay/no overlay 소유권, node/text 전환 cleanup 기준을 정리했습니다.
• 현재 정책은 ProseMirror식 hidden selection class를 도입하지 않고, native DOM range가 보일 때 custom overlay를 숨기는 방식으로 고정했습니다.
• BlockEditor.test.tsx에 native range -> blur 전환 후에도 ProseMirror-hideselection/local hidden selection class가 생기지 않는 회귀 테스트를 추가했습니다.
• README docs inventory에 새 audit 문서를 등록했습니다.

검증:

• pnpm exec vitest run src/editor/internal/react/BlockEditor.test.tsx --reporter=verbose
• pnpm run verify:docs
• pnpm check
• pnpm run verify:internal -- --repeat=1

커밋: aa6ddfc

[developer-1px]

완료되어 닫습니다.

[developer-1px]

처리 완료했습니다.\n\n- 를 추가해 selection visibility state machine, native range/custom overlay/no overlay 소유권, node/text 전환 cleanup 기준을 정리했습니다.\n- 현재 정책은 ProseMirror식 hidden selection class를 도입하지 않고, native DOM range가 보일 때 custom overlay를 숨기는 방식으로 고정했습니다.\n- 에 native range -> blur 전환 후에도 /local hidden selection class가 생기지 않는 회귀 테스트를 추가했습니다.\n- README docs inventory에 새 audit 문서를 등록했습니다.\n\n검증:\n-
RUN v4.1.9 /Users/user/Desktop/@interactive-os/editable

✓ src/editor/internal/react/BlockEditor.test.tsx > BlockEditor > autofocuses the editor and places native selection at the model cursor 251ms
✓ src/editor/internal/react/BlockEditor.test.tsx > BlockEditor > keeps editor focus and selection when toolbar buttons receive mouse down 174ms
✓ src/editor/internal/react/BlockEditor.test.tsx > BlockEditor > scrolls the canonical selection into view after keyboard movement 308ms
✓ src/editor/internal/react/BlockEditor.test.tsx > BlockEditor > records input, JSON, and DOM between Cmd+Shift+Backslash toggles 245ms
✓ src/editor/internal/react/BlockEditor.test.tsx > BlockEditor > records the clipboard payload that paste and copy actually use 349ms
✓ src/editor/internal/react/BlockEditor.test.tsx > BlockEditor > records warn and error console diagnostics while debugging 248ms
✓ src/editor/internal/react/BlockEditor.test.tsx > BlockEditor > reports debug copy failure while keeping the raw report in memory 326ms
✓ src/editor/internal/react/BlockEditor.test.tsx > BlockEditor > keeps only the five most recent raw debug reports 2775ms
✓ src/editor/internal/react/BlockEditor.test.tsx > BlockEditor > pastes editor-owned mention clipboard data through the text envelope 711ms
✓ src/editor/internal/react/BlockEditor.test.tsx > BlockEditor > pastes markdown clipboard fallback data as a mention atom 593ms
✓ src/editor/internal/react/BlockEditor.test.tsx > BlockEditor > routes markdown beforeinput paste through the same rich paste path 433ms
✓ src/editor/internal/react/BlockEditor.test.tsx > BlockEditor > pastes editor-owned multi-block clipboard data as blocks 89ms
✓ src/editor/internal/react/BlockEditor.test.tsx > BlockEditor > does not record debug inspector DOM changes as editor state 115ms
✓ src/editor/internal/react/BlockEditor.test.tsx > BlockEditor > uses beforeinput for printable text and keydown for structural editing 159ms
✓ src/editor/internal/react/BlockEditor.test.tsx > BlockEditor > inserts printable text with the active mark from keyboard shortcuts 128ms
✓ src/editor/internal/react/BlockEditor.test.tsx > BlockEditor > pastes structured clipboard data through the transfer reader 85ms
✓ src/editor/internal/react/BlockEditor.test.tsx > BlockEditor > pastes at the observed collapsed native caret 151ms
✓ src/editor/internal/react/BlockEditor.test.tsx > BlockEditor > pastes over a visible model range when the native DOM caret is collapsed 125ms
✓ src/editor/internal/react/BlockEditor.test.tsx > BlockEditor > drops transfer text through the command layer 133ms
✓ src/editor/internal/react/BlockEditor.test.tsx > BlockEditor > drops markdown transfer text through the rich command path 434ms
✓ src/editor/internal/react/BlockEditor.test.tsx > BlockEditor > hides the custom cursor while a range selection is visible 157ms
✓ src/editor/internal/react/BlockEditor.test.tsx > BlockEditor > preserves canonical range selection when focus is lost 182ms
✓ src/editor/internal/react/BlockEditor.test.tsx > BlockEditor > hides custom overlays while a native DOM range selection is visible 84ms
✓ src/editor/internal/react/BlockEditor.test.tsx > BlockEditor > does not create hidden selection classes across native range and focus transitions 80ms
✓ src/editor/internal/react/BlockEditor.test.tsx > BlockEditor > replaces a native DOM range selection when text is typed 127ms
✓ src/editor/internal/react/BlockEditor.test.tsx > BlockEditor > copies native DOM range selections through editor clipboard serialization 52ms
✓ src/editor/internal/react/BlockEditor.test.tsx > BlockEditor > keeps an observed native range selected after copy 57ms
✓ src/editor/internal/react/BlockEditor.test.tsx > BlockEditor > copies selection from keymap without waiting for native copy events 47ms
✓ src/editor/internal/react/BlockEditor.test.tsx > BlockEditor > flushes active native edits before copying the current DOM range 119ms
✓ src/editor/internal/react/BlockEditor.test.tsx > BlockEditor > cuts native DOM range selections through the command layer 84ms
✓ src/editor/internal/react/BlockEditor.test.tsx > BlockEditor > cuts selection from keymap after clipboard write succeeds 89ms
✓ src/editor/internal/react/BlockEditor.test.tsx > BlockEditor > does not delete selection from keymap when clipboard write fails 72ms
✓ src/editor/internal/react/BlockEditor.test.tsx > BlockEditor > does not create hidden DOM fallback when keymap copy has no Clipboard API 61ms
✓ src/editor/internal/react/BlockEditor.test.tsx > BlockEditor > lets paste keymap shortcuts continue to the paste event 57ms
✓ src/editor/internal/react/BlockEditor.test.tsx > BlockEditor > does not run clipboard keymap mutation while composition owns keydown 62ms
✓ src/editor/internal/react/BlockEditor.test.tsx > BlockEditor > flushes active native edits before cutting the current DOM range 329ms
✓ src/editor/internal/react/BlockEditor.test.tsx > BlockEditor > keeps read-only editing cursor-only across keyboard, DOM, paste, and cut input 416ms
✓ src/editor/internal/react/BlockEditor.test.tsx > BlockEditor > ignores dropped transfer text in read-only mode 61ms
✓ src/editor/internal/react/BlockEditor.test.tsx > BlockEditor > keeps read-only history shortcuts non-mutating 328ms
✓ src/editor/internal/react/BlockEditor.test.tsx > BlockEditor > resets read-only composition input without mutating the document 262ms
✓ src/editor/internal/react/BlockEditor.test.tsx > BlockEditor > recovers active native edits immediately when switching to read-only 196ms
✓ src/editor/internal/react/BlockEditor.test.tsx > BlockEditor > preserves a selected native range when switching to read-only 131ms
✓ src/editor/internal/react/BlockEditor.test.tsx > BlockEditor > keeps read-only title and toolbar commands non-mutating 332ms
✓ src/editor/internal/react/BlockEditor.test.tsx > BlockEditor > stores editable title changes in document history 164ms
✓ src/editor/internal/react/BlockEditor.test.tsx > BlockEditor > selects atom nodes on pointer down and copies their fallback data 127ms
✓ src/editor/internal/react/BlockEditor.test.tsx > BlockEditor > does not let a stale native text range override atom selection 111ms
✓ src/editor/internal/react/BlockEditor.test.tsx > BlockEditor > replaces explicit atom selection when text is typed 153ms
✓ src/editor/internal/react/BlockEditor.test.tsx > BlockEditor > extends selection to atom nodes with shift pointer down 147ms
✓ src/editor/internal/react/BlockEditor.test.tsx > BlockEditor > triple pointer down selects the current block 122ms
✓ src/editor/internal/react/BlockEditor.test.tsx > BlockEditor > places the caret at a text point on single pointer down 138ms
✓ src/editor/internal/react/BlockEditor.test.tsx > BlockEditor > ignores non-primary pointer buttons 98ms
✓ src/editor/internal/react/BlockEditor.test.tsx > BlockEditor > double pointer down selects the nearest word 90ms
✓ src/editor/internal/react/BlockEditor.test.tsx > BlockEditor > creates canonical range selection while pointer dragging 193ms
✓ src/editor/internal/react/BlockEditor.test.tsx > BlockEditor > captures and releases primary pointer drags 79ms
✓ src/editor/internal/react/BlockEditor.test.tsx > BlockEditor > stops drag selection updates after pointer cancel 85ms
✓ src/editor/internal/react/BlockEditor.test.tsx > BlockEditor > moves the rendered cursor to the previous paragraph when Backspace removes an empty paragraph 211ms
✓ src/editor/internal/react/BlockEditor.test.tsx > BlockEditor > does not draw a stale custom cursor while IME composition owns the native caret 195ms
✓ src/editor/internal/react/BlockEditor.test.tsx > BlockEditor > commits IME text with active marks through the marked text path 125ms
✓ src/editor/internal/react/BlockEditor.test.tsx > BlockEditor > ends composition UI state before toolbar commands 160ms
✓ src/editor/internal/react/BlockEditor.test.tsx > BlockEditor > applies toolbar commands on top of flushed native text edits 199ms
✓ src/editor/internal/react/BlockEditor.test.tsx > BlockEditor > applies toolbar insertion after appended native text edits 199ms
✓ src/editor/internal/react/BlockEditor.test.tsx > BlockEditor > defers native contenteditable text sync until editing is released 116ms
✓ src/editor/internal/react/BlockEditor.test.tsx > BlockEditor > records blur-flushed native text edits as one undo unit 245ms
✓ src/editor/internal/react/BlockEditor.test.tsx > BlockEditor > keeps separate blur-flushed native text edit sessions as separate undo units 247ms
✓ src/editor/internal/react/BlockEditor.test.tsx > BlockEditor > runs headless beforeinput at the flushed native caret 200ms
✓ src/editor/internal/react/BlockEditor.test.tsx > BlockEditor > pastes after active native text edits at the flushed caret 158ms
✓ src/editor/internal/react/BlockEditor.test.tsx > BlockEditor > pastes over a selected active native text edit instead of the flushed caret 155ms
✓ src/editor/internal/react/BlockEditor.test.tsx > BlockEditor > pastes over a DOM range inside newly appended native text 147ms
✓ src/editor/internal/react/BlockEditor.test.tsx > BlockEditor > copies a DOM range inside newly appended native text after flushing it 109ms
✓ src/editor/internal/react/BlockEditor.test.tsx > BlockEditor > cuts a DOM range inside newly appended native text after flushing it 140ms
✓ src/editor/internal/react/BlockEditor.test.tsx > BlockEditor > flushes active native text edits before keyboard undo and redo 204ms
✓ src/editor/internal/react/BlockEditor.test.tsx > BlockEditor > flushes active native text edits before beforeinput history undo and redo 180ms
✓ src/editor/internal/react/BlockEditor.test.tsx > BlockEditor > restores the native caret after history undo from an observed range 113ms
✓ src/editor/internal/react/BlockEditor.test.tsx > BlockEditor > ignores history shortcuts while composition is active 78ms
✓ src/editor/internal/react/BlockEditor.test.tsx > BlockEditor > commits mention and figure insertion from toolbar controls 145ms
✓ src/editor/internal/react/BlockEditor.test.tsx > BlockEditor > maps render selected pointers from the headless range only 0ms

Test Files 1 passed (1)
Tests 76 passed (76)
Start at 12:26:58
Duration 18.45s (transform 974ms, setup 0ms, import 1.56s, tests 16.06s, environment 699ms)\n-

editable@ verify:docs /Users/user/Desktop/@interactive-os/editable
node scripts/verify-docs-inventory.mjs

[verify-docs-inventory] README Docs covers 62 docs files; evidence strength covers 60 editor docs\n-

editable@ check /Users/user/Desktop/@interactive-os/editable
biome check

Checked 105 files in 137ms. No fixes applied.\n-

editable@ verify:internal /Users/user/Desktop/@interactive-os/editable
node scripts/verify-internal.mjs -- --repeat=1

[verify-internal] iteration 1/1
[verify-internal] focused/skipped/todo test marker scan
[verify-internal] test marker scan passed (35 test files)
[verify-internal] Vitest discovery parity passed (35 test files)
[verify-internal] pnpm run verify:docs

editable@ verify:docs /Users/user/Desktop/@interactive-os/editable
node scripts/verify-docs-inventory.mjs

[verify-docs-inventory] README Docs covers 62 docs files; evidence strength covers 60 editor docs
[verify-internal] pnpm run verify:boundaries

editable@ verify:boundaries /Users/user/Desktop/@interactive-os/editable
node scripts/verify-editor-boundaries.mjs

[verify-internal] pnpm exec tsc --noEmit
[verify-internal] pnpm test

editable@ test /Users/user/Desktop/@interactive-os/editable
vitest run

RUN v4.1.9 /Users/user/Desktop/@interactive-os/editable

Test Files 35 passed (35)
Tests 834 passed (834)
Start at 12:27:28
Duration 26.61s (transform 11.75s, setup 0ms, import 23.78s, tests 53.85s, environment 10.24s)

[verify-internal] pnpm exec vitest run --sequence.shuffle --sequence.seed=20260621

RUN v4.1.9 /Users/user/Desktop/@interactive-os/editable
Running tests with seed "20260621"

Test Files 35 passed (35)
Tests 834 passed (834)
Start at 12:27:57
Duration 30.27s (transform 22.76s, setup 0ms, import 42.19s, tests 60.44s, environment 13.69s)

[verify-internal] pnpm check

editable@ check /Users/user/Desktop/@interactive-os/editable
biome check

Checked 105 files in 185ms. No fixes applied.
[verify-internal] pnpm build

editable@ build /Users/user/Desktop/@interactive-os/editable
vite build

vite v8.0.16 building client environment for production...
�[2K
transforming...✓ 1989 modules transformed.
rendering chunks...
computing gzip size...
dist/client/assets/styles-CXh6BQ1m.css 13.19 kB │ gzip: 3.64 kB
dist/client/assets/index-BLlYW51I.js 315.64 kB │ gzip: 100.02 kB
dist/client/assets/routes-C3wWE7hZ.js 445.06 kB │ gzip: 120.75 kB

✓ built in 652ms
vite v8.0.16 building ssr environment for production...
�[2K
transforming...✓ 151 modules transformed.
rendering chunks...
computing gzip size...
dist/server/assets/empty-plugin-adapters-DzrEkdBF.js 0.28 kB │ gzip: 0.18 kB
dist/server/assets/start-4MrCPdlE.js 0.28 kB │ gzip: 0.19 kB
dist/server/assets/_tanstack-start-manifest_v-DuyP0v88.js 0.54 kB │ gzip: 0.31 kB
dist/server/assets/router-C9A4rBhw.js 1.54 kB │ gzip: 0.72 kB
dist/server/server.js 170.39 kB │ gzip: 42.42 kB
dist/server/assets/routes-BvBkMezs.js 305.59 kB │ gzip: 53.88 kB

✓ built in 267ms
[verify-internal] git diff --check

[verify-internal] passed 1/1 iterations\n\n커밋: aa6ddfc