Widget decoration DOM identity·key·destroy lifecycle 조사

[developer-1px]

조사할 것

widget decoration은 문서 model에는 없지만 DOM에는 존재하는 zero-size view이다. widget DOM identity, key reuse, destroy cleanup, selection side가 불안정하면 cursor와 DOM diff가 깨진다.

prosemirror-view 근거

• WidgetType.eq는 기본적으로 DOM constructor/spec를 비교하고, key가 있으면 key로 동일성을 판단한다.
  https://github.com/ProseMirror/prosemirror-view/blob/ca4c78e9b56f1b164c0b3758b59d8748f11b7534/src/decoration.ts#L23-L49
• Decoration.widget의 side, relaxedSide, stopEvent, ignoreSelection, key, destroy 옵션이 DOM selection과 lifecycle을 제어한다.
  https://github.com/ProseMirror/prosemirror-view/blob/ca4c78e9b56f1b164c0b3758b59d8748f11b7534/src/decoration.ts#L135-L203
• WidgetViewDesc는 raw가 아니면 DOM을 span으로 감싸고 contentEditable=false, ProseMirror-widget class를 설정한다.
  https://github.com/ProseMirror/prosemirror-view/blob/ca4c78e9b56f1b164c0b3758b59d8748f11b7534/src/viewdesc.ts#L536-L557
• widget은 parse에서 ignore되고, mutation/selection ignore와 destroy hook도 별도 처리된다.
  https://github.com/ProseMirror/prosemirror-view/blob/ca4c78e9b56f1b164c0b3758b59d8748f11b7534/src/viewdesc.ts#L559-L583

우리 에디터에서 확인할 것

• placeholder, inline menu anchor, comment marker, cursor affordance가 widget인지 document node인지 분류한다.
• DOM node 재사용과 key 기반 재생성 중 어떤 방식을 쓸지 정한다.

완료 기준

• widget-like DOM 목록과 model ownership 여부를 분류한다.
• widget key collision과 stale event handler 재사용 테스트를 만든다.
• widget destroy cleanup 기준을 정한다.

관련

• decoration/widget/mark boundary가 composition과 cursor를 깨는 문제 조사 #11 decoration/widget/mark boundary가 composition과 cursor를 깨는 문제 조사

[developer-1px]

처리 완료했습니다.

변경:

• docs/editor-widget-decoration-lifecycle-audit.md 추가
• README Docs inventory 갱신
• 현재 widget-like DOM과 document-owned DOM 분류
• widget key/event/destroy lifecycle policy 정리
• SelectionOverlay range overlay key를 rect signature별 occurrence 기반으로 변경
• 동일 geometry range rect 두 개가 있어도 duplicate key warning 없이 두 overlay가 유지되는 테스트 추가

중요 판정:

• 현재 ProseMirror식 widget registry는 추가하지 않습니다. 실제 widget producer가 없어서 dead abstraction입니다.
• mention/figure/empty text-run은 widget이 아니라 document render surface입니다.
• 현재 stale event handler 재사용 위험은 낮습니다. overlay에는 handler가 없고 toolbar/debug는 React lifecycle입니다. future imperative widget에는 destroy cleanup 테스트가 필요합니다.

검증:

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

커밋: a534ef4 (Document widget decoration lifecycle policy)