From 819ab9b4bb0e118135daf1a809173bae3be556de Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E1=84=8B=E1=85=B2=E1=84=8B=E1=85=AD=E1=86=BC=E1=84=90?=
 =?UTF-8?q?=E1=85=A2?= <teo.v@navercorp.com>
Date: Tue, 8 Sep 2026 07:57:57 +0900
Subject: [PATCH 01/20] =?UTF-8?q?docs:=20=ED=8E=B8=EC=A7=91=20=EC=82=AC?=
 =?UTF-8?q?=EB=A1=80=EC=97=90=EC=84=9C=20=EC=B5=9C=EC=86=8C=20=EB=AC=B8?=
 =?UTF-8?q?=EB=B2=95=EA=B3=BC=20=EC=A1=B0=ED=95=A9=20=ED=95=98=EC=9D=B4?=
 =?UTF-8?q?=EB=9D=BC=ED=82=A4=EB=A5=BC=20=EB=8F=84=EC=B6=9C=ED=95=9C?=
 =?UTF-8?q?=EB=8B=A4?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 standards/editing-grammar.md | 257 +++++++++++++++++++++++++++++++----
 1 file changed, 228 insertions(+), 29 deletions(-)

diff --git a/standards/editing-grammar.md b/standards/editing-grammar.md
index 1cdc03b3..84e71cf3 100644
--- a/standards/editing-grammar.md
+++ b/standards/editing-grammar.md
@@ -18,10 +18,11 @@ member와 편집 문법의 크기는 서로 다른 문제다.
 - Don't: 이번 설계로 Core API를 늘리거나 기존 동작을 변경하지 않는다. 새로운
   범용 editor, command bus, profile registry나 package hierarchy를 만들지 않는다.
 
-구현 근거의 범위는 JSON Document, Selection, Editing, Affordance, Web과
-Document·Sheet·Rich Text의 대표 편집 경로다. Object의 전체 선택과 Database의
-cut 미지원은 profile 차이를 판정하는 사례로 포함한다. 모든 Hands의 완성도,
-브라우저별 입력 일치, 협업 wire protocol의 수렴은 이 설계의 검증 결과가 아니다.
+아래 도출은 11개 내부 편집 사례의 model·의도·조합과 외부 관습을 비교한다.
+실행된 공통 적합성 증거의 범위는 Document·Sheet·Rich Text의 대표 편집 경로와
+Selection·Editing·Affordance·Web 연결이다. 사례를 읽은 것과 같은 profile의
+독립 구현을 검증한 것은 구별한다. 모든 Hands의 완성도, 브라우저별 입력 일치,
+협업 wire protocol의 수렴은 이 설계의 검증 결과가 아니다.
 
 ## 현재 문제와 원인
 
@@ -30,39 +31,207 @@ cut 미지원은 profile 차이를 판정하는 사례로 포함한다. 모든 H
 `dispatch` 형태이며, 동사의 사전 조건과 결과는 editor별 코드와 문서에 있다.
 `Official Hands`도 아직 호환성 약속을 확정하지 않은 후보다.
 
-이 때문에 여러 editor가 같은 API 형태를 제공해도 같은 편집 문법을 따른다는
-증거가 되지 않는다. `selectAllAffordance`의 전체 선택 토글처럼 특정 관습이
-범용 기본값으로 보이고, `selection.move`처럼 문서 변경과 선택 변경이 이름에서
-구별되지 않는 사례도 있다. 동작을 선언하는 규칙과 그 규칙을 검증하는 사례의
-연결이 부족한 것이 원인이다.
+현재 공용 적합성 runner는 대표 editor의 공통 의미를 검증한다. 그 증거를 다른
+장르로 확대하려면 규칙의 적용 조건과 profile 차이가 먼저 드러나야 한다.
+`selectAllAffordance`의 전체 선택 토글과 선택 의도의 멱등성,
+`selection.move`라는 이름 아래의 블록 이동과 선택 위치 이동도 구별해야 한다.
+아직 남은 공백은 앱 사례에서 공통 의미를 도출하는 근거, 중첩된 편집 맥락의
+계약, 같은 profile의 독립 구현 증거다.
 
-## 세 종류의 계약과 기존 소유자
+## 앱 사례에서 최소 문법 도출하기
 
-다음은 새 runtime 계층이 아니라 기존 책임들이 약속할 내용의 구분이다.
+### 명령 이름보다 대상과 결과를 먼저 비교한다
 
-| 계약 | 고정할 의미 | 정본 소유자 |
+Apple의 [1992년 Macintosh Human Interface Guidelines](https://www.vintageapple.org/inside_r/pdf/Human_Interface_Guidelines_1992.pdf)
+인쇄 쪽수 286–300은 선택 후 작업하는 관습과 텍스트·배열·그래픽 선택을 구분하고,
+필드 전체 선택과 내부 텍스트 편집의 차이도 설명한다. Windows의
+[표준 Edit 메뉴](https://learn.microsoft.com/en-us/windows/win32/uxguide/cmd-menus#standard-menus)에도
+같은 명령 어휘가 반복된다. 전자는 역사적 제품 지침, 후자는 Windows 7 시대의
+플랫폼 지침이다. 오래된 공통 어휘의 근거이며 모든 동작이 30년간 동일했다는
+증명은 아니다. 사람의 편집 관습에서 도출하는 것은 관찰 가능한 의미다. Core의
+여섯 member, JSON Patch 표현, package 구조가 그 관습의 유일한 구현이라는
+결론은 나오지 않는다.
+
+다음 표는 현재 구현의 표본이다. 링크는 각 책임의 구현으로 연결된다. 마지막
+열의 중첩 가능성이 모두 구현·검증됐다는 뜻은 아니며 현재 지원과 분리해 읽는다.
+
+| 사례 | 대상·위치·선택 | 현재 대표 작업 | 도출에 필요한 차이 또는 중첩 |
+| --- | --- | --- | --- |
+| [Document](../packages/json-document-editing/src/document.ts) | block ID + text offset, 여러 범위 | 블록 이동·삭제·복사, 블록 text 교체 | Copy는 전체 블록. native 내부 문자열 선택과 대상이 다름 |
+| [Rich Text](../packages/json-document-rich-text/src/editor.ts) | node ID + text/child point + affinity, 여러 범위 | text 삽입, structured slice 대체, mark 변경 | collapsed point에서도 삽입 가능. schema가 허용하는 구간·구조를 함께 판단 |
+| [Order](../packages/json-document-editing/src/order.ts) | item ID, 선형 순서의 범위 | 이름 변경, 항목 제거·복사·삽입 | 항목 선택과 이름 입력 중 문자열 선택을 구별 |
+| [Tree](../packages/json-document-editing/src/tree.ts) | node ID + parent 관계, visible topology의 범위 | 노드 선택·제거·복사·삽입 | Copy·제거는 선택한 노드의 후손까지 포함. 보이는 선택과 실제 영향 집합이 다름 |
+| [Sheet](../packages/json-document-editing/src/sheet.ts) | row/column ID, 셀 직사각형과 primary | 셀 commit, fill, Cut·Paste | Cut은 primary 값을 비움. 셀 구조를 제거하거나 내부 문자열을 잘라내는 작업과 다름 |
+| [Database](../packages/json-document-editing/src/database.ts) | record/property ID, view가 제공하는 표 topology | cell commit, record 추가·삭제, view configure, Paste | 셀 값과 record 구조, 저장되는 view 설정을 구별. 현재 Cut 부재는 보편 규칙이 아님 |
+| [Object](../packages/json-document-editing/src/object.ts) | object ID 집합, x/y/width/height | translate, resize, fill, Copy·Paste | 선택 위치의 이동과 객체 좌표 변경은 다름. 현재 객체 model이 완전한 중첩 text editor는 아님 |
+| [Kanban](../packages/json-document-editing/src/kanban.ts) | card ID 집합, column ID + beforeCardId | 카드 이동·제거 | 이동은 소속과 순서를 바꿈. 보드 모양만으로 새 공통 선택 family를 요구하지 않음 |
+| [Calendar](../packages/json-document-editing/src/calendar.ts) | event ID + occurrenceStart, 구체화된 occurrence 범위 | 생성·이동·resize, Copy·Paste | 선택한 occurrence와 반복 일정 변경 범위는 다름. 시간·반복 규칙은 domain 의미 |
+| [Annotation](../packages/json-document-editing/src/annotation.ts) | annotation ID 집합, source ID + selector | 생성·본문 변경·이동·resize·삭제 | 편집되는 annotation과 가리키는 source 영역을 구별. 원본 이미지 픽셀 편집 사례가 아님 |
+| [Composer](../packages/json-document-composer/src/commands.ts) | Rich Text point, reference atom, attachment ID | text·reference 삽입, attachment·model 변경 | 여러 편집 대상을 한 draft에서 조합. 제출·외부 실행의 효과는 별도 Application 계약 |
+
+11개 사례는 같은 레포의 구현이며 다수가 같은 EditingSession을 쓴다. 그 반복은
+내부 재사용 가능성의 증거다. 서로 다른 생태계가 독립적으로 같은 의미를 채택했다는
+증거로 11번 세지 않는다. Raster·파일 이동은 아래 외부 반례로만 사용한다.
+
+### 하나의 편집을 설명하는 최소 질문
+
+의미를 설명하는 단위는 **작업을 받을 편집 맥락 + 대상·위치 + 의도 → 결과**다.
+API 인자에 모두 넣으라는 뜻은 아니다. 상태나 명시 인자로 이미 정해지는 것은
+그 계약에서 읽으면 된다. 한 범용 state 객체나 command envelope를 추가하지 않는다.
+
+```text
+편집의 의미
+├─ 대상: 무엇의 내용·속성·구조를 다루는가
+│  ├─ identity: 같은 대상을 어떻게 알아보는가
+│  └─ position / topology: 어디이며 어떤 순서·관계로 해석하는가
+├─ 작업 맥락: 어느 편집기가 무엇을 대상으로 받는가
+│  ├─ selection: 대상 집합·범위·영역 또는 삽입점
+│  ├─ 입력 focus: 현재 입력을 받는 곳
+│  └─ 중첩: 객체 / 셀 / 그 안의 텍스트 사이의 진입·복귀
+├─ 의도: 탐색·선택 / 내용·구조 변경 / 교환 / 복원
+└─ 결과와 작업 경계
+   ├─ 진행 중인 draft·preview / 확정 / 취소·거절
+   ├─ 변경된 내용과 후속 선택·위치, 교환 payload
+   └─ 관찰 시점과 Undo/Redo의 대상·단위
+```
+
+이 트리는 질문의 분류다. 상속 관계나 새 runtime 모듈 목록이 아니다. 다음 구별을
+없애면 실제 사례의 결과를 설명할 수 없다.
+
+| 구별 | 없애면 설명할 수 없는 사례 | 남길 계약 / 기존 연결 |
 | --- | --- | --- |
-| 공통 편집 규칙 | 선택 전이, 편집의 원자성, 복사와 History의 관계 | Selection·Editing |
-| Hands profile | 편집 대상, 범위 해석, 삭제·붙여넣기 결과, 지원 작업 | Document Type과 해당 editor의 기존 owner를 조합한 Hands |
-| 입력 매핑 | 키·포인터·IME를 어떤 편집 의도로 해석하는가 | Adapter·Affordance와 framework Connector |
+| Identity와 position | 같은 블록의 offset 변경, 이동한 같은 카드, 같은 event의 여러 occurrence | Point 단위·동등성·mapping은 해당 editor와 Selection. EG-TARGET |
+| Selection과 실제 작업 대상 | `annotation.create`의 새 대상, `record.delete(recordId)`의 명시 대상, Tree의 선택된 부모와 숨은 후손 | 대상은 selection·명시 인자·삽입 위치와 의도로 정한다. 모든 작업에 non-empty selection을 강제하거나 효과를 보이는 선택에만 제한하지 않음 |
+| 입력 focus와 range의 `focus` | 표 셀 입력 중 문자열의 역방향 선택 | 전자는 입력을 받는 곳, 후자는 범위의 한 endpoint. 이름이 같아도 같은 상태가 아님. EG-SELECT·EG-TARGET |
+| 저장 내용과 보이는 topology | 접힌 Tree, 정렬된 Database, 저장되는 `view.configure` | 가시 순서를 읽는 것과 view 설정을 수정하는 것은 다른 작업. EG-TARGET·EG-EDIT |
+| 요청·진행 중 작업과 확정된 편집 | 여러 pointer preview, IME composition, 여러 입력을 묶는 History | 사건 하나·dispatch 하나·commit 하나·Undo 한 step은 일대일이 아님. EG-GESTURE·EG-HISTORY·DOM lifecycle |
+| 작업 결과와 이후 현재 상태 | 구독 중 재진입, 외부 변경 이후 Undo | 결과의 관찰 시점과 선택한 History owner의 복원 의미를 보존. EG-RESULT·EG-HISTORY |
+
+문자마다 stable ID가 있어야 한다거나 모든 위치를 숫자 하나로 표현해야 한다는
+결론은 나오지 않는다. [Rich Text point](../packages/json-document-rich-text/src/model.ts)의
+text/child 구별·affinity와 [Selection family](../packages/json-document-selection/src/core/family.ts)의
+transition·map·reconcile·targets가 이미 이 차이의 정본 경계를 제공한다.
+
+### 중첩은 입력을 받을 곳의 계약이다
+
+[W3C APG Grid](https://www.w3.org/WAI/ARIA/apg/patterns/grid/#editing-and-navigating-inside-a-cell)는
+셀 탐색에 쓰는 화살표와 셀 안의 caret·widget 조작을 구분한다.
+[Keynote의 텍스트 상자](https://support.apple.com/en-ca/guide/keynote/tan4fd6ee725/mac)는
+객체 자체와 그 안의 텍스트를 따로 선택한다. 두 자료는 지침·제품 관습의 근거이며
+범용 editing scope API를 규정하지 않는다.
 
 ```text
-keyboard / pointer / IME ─ Adapter·Affordance ─┐
-직접 호출하는 프로그램 ──────────────────────┤
-                                             ↓
-                         해당 editor의 편집 의도
-                         + Selection / Topology
-                                             ↓
-                         EditingPlan + selectionAfter
-                                             ↓
-                         EditingSession → JSONDocument.commit
-                                             ↓
-                         해당 편집의 snapshot / History
+Application
+└─ 표를 다루는 Hand
+   ├─ 셀 선택: Copy → 셀 payload, Delete 입력 → 선택한 셀 정책
+   └─ 셀 내부 편집
+      └─ 텍스트 선택: Copy → 문자열, Delete 입력 → 문자 편집
+
+Canvas Hand
+└─ 텍스트 객체 선택
+   └─ 내부 텍스트 편집
 ```
 
-이는 대표적인 값 변경 흐름이다. Copy는 조회이며, 선택만 바꾸는 작업은 document
-commit을 만들지 않고, Undo/Redo는 선택한 History owner를 실행한다. 순수 JSON
-소비자에게 Editing이나 Hands 설치를 요구하지 않는다.
+중첩을 조합하는 profile은 진입·복귀, 입력 수신자, 지원하지 않거나 거절한 의도의
+전달 여부, 후속 선택을 결정해야 한다. 내부 편집기가 삭제를 거절했다는 이유만으로
+바깥 객체 삭제가 실행되는 해석을 허용할지 명시해야 한다. 이 설계의 후보는
+**해당 맥락이 맡은 편집의 거절을 바깥의 다른 편집으로 암묵 변환하지 않는 것**이다.
+처리하지 않은 입력의 명시적 위임과 실패를 구별하며, 정확한 키·진입 방법은 입력
+profile이 정한다. 아직 전체 Hands에 실행 검증된 새 규칙은 아니다.
+
+여기서 편집 맥락은 HTML `editing host`, DOM element, JSON subtree, History
+instance와 일대일 대응하지 않는다. Toolbar로 focus가 옮겨져도 편집 명령은 저장된
+선택을 대상으로 할 수 있다. Headless 호출은 DOM focus 없이 대상을 지정할 수 있다.
+Calendar intent의 `scope: "this" | "this-and-following" | "all"`은 반복 일정의
+**변경 범위**이며 이 입력 맥락과 다른 개념이다.
+
+현재 [DocumentTextControl](../packages/json-document-react/src/use-document-text-control.ts)은
+native range의 방향을 투영하고, [Web virtual selection scope](../packages/json-document-web/src/virtual-selection-scope.ts)는
+자신의 영역에서 전체 텍스트 선택·Copy와 editable target 우선 처리를 맡는다.
+이는 기존 소유자의 증거이며 둘 중 하나를 모든 편집 맥락의 정본이라고 선언할
+근거는 아니다. 범용 scope registry나 Host별 dispatcher를 새로 만들지 않는다.
+
+### 반례가 정하는 공통 규칙의 경계
+
+| 과도한 일반화 | 근거 있는 반례 | 이 설계의 처리 |
+| --- | --- | --- |
+| 선택은 언제나 Undo 대상이 아님 | [GIMP Undoing](https://docs.gimp.org/3.0/en/gimp-concepts-undo.html)은 Scissors Select 작업과 Quick Mask 전환의 Undo를 설명 | 현재 일시적 Selection의 EG-SELECT·EG-HISTORY를 유지. Raster 선택 제작의 History 정책으로 일반화하지 않음 |
+| 이동은 항상 Copy 후 즉시 제거한 뒤 Paste | [Finder 이동](https://support.apple.com/en-gb/102650)은 Clipboard의 파일을 목적지에 옮기는 동작을 제공 | EG-CUT은 현재 즉시 제거하는 cut 계약. 지연 이동은 같은 계약의 이름만 다른 구현이 아님 |
+| 복사한 저장 값을 그대로 넣으면 의미도 보존 | [Excel 수식 이동·복사](https://support.microsoft.com/en-us/excel/move-or-copy-a-formula-in-excel)는 복사 시 상대 참조 변경, 수식 이동 시 참조 유지를 구별 | payload의 참조·identity·배치 변환은 profile 계약. JSON 모양이나 text 일치만으로 교환 호환성을 판정하지 않음 |
+| Selection은 항상 문자열의 시작과 끝 | 레포의 Sheet rectangle, Calendar materialized occurrences와 Selection mask 확장 | 대상별 family를 유지. mask algebra의 존재는 raster Hand 완성의 증거가 아님 |
+| 입력이 끝나면 Undo 한 step | 여러 preview와 typing/composition grouping, GIMP의 선택 도구 작업 | 작업의 확정·취소와 History grouping을 따로 명시 |
+
+공통 의미로 남는 것은 대상과 위치의 구별, 같은 의도의 명시된 결과, 효과의
+관찰·실패 경계다. 구체적인 선택 모양, 복사할 내용, 붙여넣기 위치, 영향을 받는
+참조, 기록할 상태와 작업 묶음은 profile이 채운다. Copy의 source 내용 보존과
+clipboard 자체의 변경도 별개의 효과다. 원자적 문서 편집은 이 레포가 제공하는
+강한 계약이며 모든 제품이 이미 같은 실패 보장을 구현했다는 역사적 주장은 아니다.
+
+## 하이라키: 구체화와 조합
+
+고정할 공통 의미와 profile이 결정할 내용을 먼저 나눈다. 그 다음 기존 모듈이
+어떤 부분을 실현하는지 연결한다. 앱 이름과 package 폴더 순서에서 의미의 상속
+관계를 역으로 추정하지 않는다.
+
+```text
+편집 계약
+├─ 공통 규칙: 대상·선택·효과·관찰·실패의 의미
+├─ 대상별 구체화
+│  └─ model / 유효한 position / selection·topology / 연산·교환·복원 정책
+└─ 입력 관습별 구체화
+   └─ key·pointer·IME / focus·중첩 / gesture·native lifecycle
+
+대상별 계약 + 선택한 입력 계약
+                │ 조합하고 함께 검증
+                v
+           Hands profile
+                │ 여러 Hand와 외부 서비스를 조합
+                v
+           Application / Host
+```
+
+대상별 계약과 입력 계약은 서로 다른 축이다. Sheet가 Rich Text를 상속하는 것이
+아니며 Windows·macOS 관습 때문에 문서 model을 복제할 이유도 없다. Hands profile은
+함께 약속하는 조합이다. 위의 구분을 새 package나 public descriptor type으로
+등록하지 않는다. 실제 문서·API·Usage는 아래의 기존 정본 owner에 둔다.
+
+의미를 실현하는 책임 지도는 다음과 같다. 화살표는 이 설계의 책임 연결이며
+현재 package import graph의 모든 edge를 표현하지 않는다.
+
+```text
+Headless API                   Keyboard / Pointer / IME
+     |                                   |
+     |                          Adapter / Affordance
+     +-------------------+---------------+
+                         v
+                   Domain editor
+                    /         \
+          Selection·Topology   EditingPlan + selectionAfter
+                    \         /
+                     v       v
+                    EditingSession
+                 관찰·작업·History 연결
+                         |
+                         v
+                    JSONDocument
+                  값·원자적 commit
+              local / collaboration 구현
+
+Connector: 이 책임들을 framework의 구독·render·focus lifecycle에 연결
+Host: 정본 API의 조합 순서·제품 정책·데이터·layout·외부 instance 주입
+```
+
+Selection의 수학적 전이는 JSONDocument mutation 없이 사용할 수 있고, 순수 JSON
+소비자는 Editing 없이 Core를 사용할 수 있다. Collaboration은 같은 JSONDocument
+계약의 다른 구현이며 `EditingHistory` 연결은 별도 선택이다. 입력 맥락 하나마다
+History를 하나씩 생성하거나 Application 전체에 단일 History를 강제하지 않는다.
+같은 문서를 여러 view에서 편집할 때의 History 귀속은 선택한 owner의 계약이다.
+
+### 기존 소유자와 연결
+
+Copy는 조회이며, 선택만 바꾸는 작업은 document commit을 만들지 않고,
+Undo/Redo는 선택한 History owner를 실행한다. 위의 흐름을 모든 요청이
+Core commit으로 향하는 단일 경로로 해석하지 않는다.
 
 | 기존 owner | 계속 소유할 책임 | 다른 곳으로 넘기지 않을 결정 |
 | --- | --- | --- |
@@ -85,6 +254,13 @@ layout·concrete external instance와 조합을 소유한다.
 증거를 통해 이루어진다. DOM API 모양, JSON 저장 shape, 특정 키 조합은 이
 규칙의 전제가 아니다.
 
+이 표의 적용 범위는 현재 구조·텍스트 편집 profile의 계약이다. EG-SELECT의
+일시적 선택과 문서 History 분리, EG-CUT의 즉시 제거를 다른 장르의 모든 관습으로
+일반화하지 않는다. 범위 확장의 anchor 규칙은 anchor를 가진 range family에
+적용한다. 다른 family나 raster·지연 이동 profile을 동결하려면 해당 상태와
+History·transfer 의미를 먼저 명시해야 하며, 기존 profile의 규칙을 느슨하게
+바꾸어 같은 profile이라고 부르지 않는다.
+
 | ID | 관찰 가능한 규칙 | Owner |
 | --- | --- | --- |
 | EG-SELECT | 선택만 바꾸는 작업은 document value와 문서 Undo/Redo 기록을 바꾸지 않는다. 범위 확장은 유효한 기존 anchor를 보존하고 focus를 이동한다. | Selection·Editing |
@@ -266,6 +442,29 @@ offset도 비교하며 블록 toggle과 전체 블록 Copy의 의미는 유지
 유지하는 증거다. offset 하나로 과거 native range 전체를 복원한다는 계약이나
 profile 동결로 확대하지 않는다.
 
+## 새 도출의 검증 질문
+
+다음은 실행할 수 있도록 시작 상태와 판정 결과를 적은 **후보 사례**다. 앞의
+기존 적합성 표의 통과 항목과 합산하지 않는다. 이 문서 변경은 새 behavior vector나
+구현을 추가하지 않는다.
+
+| 사례 | 시작 상태 → 작업 → 판정할 결과 | 연결·현재 증거의 한계 |
+| --- | --- | --- |
+| 셀과 내부 문자열 | `Alpha` 셀 선택 / 내부 `ph` 선택 각각에서 Copy → 셀 payload / `ph` | EG-TARGET·EG-COPY. 기존 Sheet·native selection 증거는 각각 있으며 이 중첩 전체의 공통 binding은 없음 |
+| 거절 시 바깥으로 전이 금지 | 선택한 객체 안의 text editor가 Delete 거절 → 객체 제거·외부 History entry가 생기지 않음 | EG-EDIT·입력 계약 후보. [Web clipboard ownership](../packages/json-document-web/tests/clipboard-rejection.test.ts)은 한 binding의 거절 처리 증거이며 일반적인 중첩 거절 vector는 없음 |
+| Toolbar 대상 보존 | editor A에서 범위 선택 → Toolbar에 focus → Copy 실행 → A의 선택 payload | 입력 focus와 Selection 구별. 전체 Hands에 대한 공통 실행 증거 없음 |
+| 셀 값과 행 구조 | 값이 있는 셀을 비움 / 해당 record 삭제 → 전자는 구조 유지, 후자는 record 제거 | EG-EDIT·profile 대상. 현재 Sheet Cut과 Database `record.delete`는 서로 다른 계약 |
+| 반복 일정 영향 범위 | 같은 occurrence에 `this` / `all` 이동 → profile이 정한 반복 일정 집합만 영향 | EG-TARGET·EG-EDIT. Calendar domain 사례이며 입력 맥락 전환으로 해석하지 않음 |
+| Draft 취소와 Undo | 미확정 rename draft 수정 → cancel → 확정 label 불변; 확정 rename → Undo → 이전 label | EG-GESTURE·EG-HISTORY. 구조 gesture runner가 모든 rename·IME 취소를 증명하지 않음 |
+| 외부 참조·다른 profile로 Paste | 수식 또는 reference를 다른 위치·profile에 Paste → 변환·보존·거절 중 선언한 결과 | EG-PASTE. 현재 세 editor의 내부 round trip만으로 cross-profile 교환을 인증할 수 없음 |
+| 공유 문서의 두 편집 맥락 | A에서 편집 → B로 입력 focus 전환 → Undo → 선택한 History owner가 명시한 기여·선택 복원 | EG-HISTORY·EG-RESULT. 외부 History 연결 증거와 모든 Hand의 입력 routing 증거는 다름 |
+
+이번 도출로 설계 방향을 정할 수 있는 부분은 대상·위치·선택·입력 수신자의 구별,
+대상별 계약과 입력 계약의 조합, 기존 owner의 유지다. 아직 동결할 수 없는 부분은
+중첩 편집의 진입·거절·복귀 규칙, profile 간 payload 변환, raster/file 편집의
+적용 범위, 여러 편집 맥락의 History routing이다. 같은 profile을 독립적으로
+구현했을 때 이 사례들의 결과가 일치해야 장기 호환성 약속으로 승격할 수 있다.
+
 ## 장기 호환성
 
 약속하는 것은 **고정된 profile의 지원 입력과 관찰 가능한 결과**다. 같은 profile

From c8570dc76bbc6ea03ddb23c53ffc21fa4103e74f Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E1=84=8B=E1=85=B2=E1=84=8B=E1=85=AD=E1=86=BC=E1=84=90?=
 =?UTF-8?q?=E1=85=A2?= <teo.v@navercorp.com>
Date: Tue, 8 Sep 2026 08:01:14 +0900
Subject: [PATCH 02/20] =?UTF-8?q?docs:=20=EC=97=AD=EC=82=AC=EC=A0=81=20?=
 =?UTF-8?q?=EB=B2=94=EC=9C=84=20=ED=99=95=EC=9E=A5=EC=9D=98=20=EC=B0=A8?=
 =?UTF-8?q?=EC=9D=B4=EC=99=80=20Host=20=EC=A1=B0=ED=95=A9=20=EC=97=AD?=
 =?UTF-8?q?=ED=95=A0=EC=9D=84=20=EB=AA=85=ED=99=95=ED=9E=88=20=ED=95=9C?=
 =?UTF-8?q?=EB=8B=A4?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 standards/editing-grammar.md | 9 +++++----
 1 file changed, 5 insertions(+), 4 deletions(-)

diff --git a/standards/editing-grammar.md b/standards/editing-grammar.md
index 84e71cf3..6d255542 100644
--- a/standards/editing-grammar.md
+++ b/standards/editing-grammar.md
@@ -158,6 +158,7 @@ native range의 방향을 투영하고, [Web virtual selection scope](../package
 | 선택은 언제나 Undo 대상이 아님 | [GIMP Undoing](https://docs.gimp.org/3.0/en/gimp-concepts-undo.html)은 Scissors Select 작업과 Quick Mask 전환의 Undo를 설명 | 현재 일시적 Selection의 EG-SELECT·EG-HISTORY를 유지. Raster 선택 제작의 History 정책으로 일반화하지 않음 |
 | 이동은 항상 Copy 후 즉시 제거한 뒤 Paste | [Finder 이동](https://support.apple.com/en-gb/102650)은 Clipboard의 파일을 목적지에 옮기는 동작을 제공 | EG-CUT은 현재 즉시 제거하는 cut 계약. 지연 이동은 같은 계약의 이름만 다른 구현이 아님 |
 | 복사한 저장 값을 그대로 넣으면 의미도 보존 | [Excel 수식 이동·복사](https://support.microsoft.com/en-us/excel/move-or-copy-a-formula-in-excel)는 복사 시 상대 참조 변경, 수식 이동 시 참조 유지를 구별 | payload의 참조·identity·배치 변환은 profile 계약. JSON 모양이나 text 일치만으로 교환 호환성을 판정하지 않음 |
+| Shift-click 확장은 항상 같은 anchor를 고정 | Apple HIG 1992 인쇄 쪽수 290–291은 addition과 fixed-point 두 방식을 설명 | 현재 EG-SELECT의 고정 anchor 전이를 유지. 다른 입력 관습을 같은 전이로 일반화하지 않음 |
 | Selection은 항상 문자열의 시작과 끝 | 레포의 Sheet rectangle, Calendar materialized occurrences와 Selection mask 확장 | 대상별 family를 유지. mask algebra의 존재는 raster Hand 완성의 증거가 아님 |
 | 입력이 끝나면 Undo 한 step | 여러 preview와 typing/composition grouping, GIMP의 선택 도구 작업 | 작업의 확정·취소와 History grouping을 따로 명시 |
 
@@ -185,9 +186,9 @@ clipboard 자체의 변경도 별개의 효과다. 원자적 문서 편집은 
                 │ 조합하고 함께 검증
                 v
            Hands profile
-                │ 여러 Hand와 외부 서비스를 조합
+                │ Host가 여러 Hand와 외부 서비스를 조합
                 v
-           Application / Host
+           Application
 ```
 
 대상별 계약과 입력 계약은 서로 다른 축이다. Sheet가 Rich Text를 상속하는 것이
@@ -256,8 +257,8 @@ layout·concrete external instance와 조합을 소유한다.
 
 이 표의 적용 범위는 현재 구조·텍스트 편집 profile의 계약이다. EG-SELECT의
 일시적 선택과 문서 History 분리, EG-CUT의 즉시 제거를 다른 장르의 모든 관습으로
-일반화하지 않는다. 범위 확장의 anchor 규칙은 anchor를 가진 range family에
-적용한다. 다른 family나 raster·지연 이동 profile을 동결하려면 해당 상태와
+일반화하지 않는다. 범위 확장의 anchor 규칙은 고정 anchor로 확장하는 현재
+range 전이에 적용한다. 다른 family나 raster·지연 이동 profile을 동결하려면 해당 상태와
 History·transfer 의미를 먼저 명시해야 하며, 기존 profile의 규칙을 느슨하게
 바꾸어 같은 profile이라고 부르지 않는다.
 

From 412f5121547927027c001d7911fee07e9939cc48 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E1=84=8B=E1=85=B2=E1=84=8B=E1=85=AD=E1=86=BC=E1=84=90?=
 =?UTF-8?q?=E1=85=A2?= <teo.v@navercorp.com>
Date: Tue, 8 Sep 2026 09:00:03 +0900
Subject: [PATCH 03/20] =?UTF-8?q?docs:=20=EA=B8=B0=EB=B3=B8=20Profile?=
 =?UTF-8?q?=EC=9D=98=20=ED=8E=B8=EC=A7=91=20=EC=95=BD=EC=86=8D=EA=B3=BC=20?=
 =?UTF-8?q?=EB=8B=A8=EC=B6=95=ED=82=A4=20=EA=B4=80=EC=8A=B5=EC=9D=84=20?=
 =?UTF-8?q?=EA=B5=AC=EC=B2=B4=ED=99=94=ED=95=9C=EB=8B=A4?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 standards/editing-grammar.md | 173 +++++++++++++++++++++++++++++++++--
 1 file changed, 164 insertions(+), 9 deletions(-)

diff --git a/standards/editing-grammar.md b/standards/editing-grammar.md
index 6d255542..9caf48c7 100644
--- a/standards/editing-grammar.md
+++ b/standards/editing-grammar.md
@@ -11,6 +11,10 @@ Stable admission이나 외부 상호운용성을 주장하지 않는다.
 작은 Core는 장기간 약속할 수 있는 의미만 소유한다. JSON Document의 여섯
 member와 편집 문법의 크기는 서로 다른 문제다.
 
+기반 계약은 여러 편집 정책을 수용하고, **기본 Profile은 사람들이 익숙한 편집
+동작을 구체적인 약속으로 제공한다**. 예외의 존재는 기본값의 적용 범위와 변형을
+설명하는 근거다. 기본값 자체도 장기간 호환성을 지킬 계약에 포함한다.
+
 - Outcome: 같은 Hands profile을 소비하는 제품은 선택·편집·복사·복원에서 같은
   관찰 가능한 의미를 얻는다.
 - Done: 이 설계에서 공통 규칙과 profile 선택을 구분하고, 각 규칙의 기존 owner,
@@ -36,10 +40,40 @@ Selection·Editing·Affordance·Web 연결이다. 사례를 읽은 것과 같은
 `selectAllAffordance`의 전체 선택 토글과 선택 의도의 멱등성,
 `selection.move`라는 이름 아래의 블록 이동과 선택 위치 이동도 구별해야 한다.
 아직 남은 공백은 앱 사례에서 공통 의미를 도출하는 근거, 중첩된 편집 맥락의
-계약, 같은 profile의 독립 구현 증거다.
+계약, 같은 profile의 독립 구현 증거다. 각 owner에 있는 기본 동작을 함께 쓰는
+Profile의 약속과, 그 Profile이 허용할 차이도 연결해야 한다.
 
 ## 앱 사례에서 최소 문법 도출하기
 
+### 단축키가 드러내는 관습부터 찾는다
+
+핵심 기능을 찾는 출발점은 **단축키로 반복 실행하도록 드러낸 작업**이다.
+사용자가 근육기억으로 익힌 조작을 장기 호환성의 대상으로 보고, 여러 제품과
+오랜 자료에 반복되는 기능부터 조사한다. 단축키의 존재는 조사 우선순위의 단서이며,
+그 기능의 영구 불변성이나 Core 소유권을 단독으로 증명하지는 않는다.
+
+[Mac 단축키](https://support.apple.com/en-us/102650)와
+[Excel 단축키](https://support.microsoft.com/en-us/accessibility/excel/keyboard-shortcuts-in-excel)는
+Undo·Copy·선택 확장을 반복해서 제공한다. 반면 문자와 셀의 선택 단위는 다르고,
+Excel의 `F2`는 셀 내부 편집으로 들어가는 맥락을 드러낸다. 현재 제품의 공개
+동작과 아래 역사적 지침을 대조하며, 현재 목록만으로 30년의 연속성을 주장하지 않는다.
+
+| 먼저 살펴볼 입력·기능 | 추출할 의미와 차이 | 기존 책임에 연결할 후보 |
+| --- | --- | --- |
+| Undo·Redo 단축키 | 되돌릴 작업의 단위, 전후 내용·선택, 실행할 History | Editing·History와 입력 계약 |
+| Copy·Cut·Paste 단축키 | 대상 확보, 교환 표현, 제거·삽입 결과 | Editing·domain codec·Web |
+| 방향키·Shift 확장·Select All | 탐색과 선택 확장, 전체의 범위와 반복 입력 결과 | Selection family·topology·입력 계약 |
+| Delete·Backspace | 선택 대상 제거와 삽입점 주변 삭제, 값 비우기와 구조 제거 | 대상별 Editing 계약 |
+| Enter·F2·Escape | 내부 편집 진입, 확정·취소·복귀의 맥락 | Affordance lifecycle·domain·Web |
+| 서식·채우기 등 대상별 단축키 | 같은 입력 계열에서도 다른 대상의 속성·내용 변경 | 해당 domain 계약 |
+| Save·Print | 저장·출력처럼 문서 편집 밖의 효과 | Application 계약 |
+
+이 표는 기능을 모두 추가하라는 목록이 아니다. 발견한 작업을 **시작 맥락·대상 →
+의도 → 결과·선택·History**로 풀고, 여러 대상에서 유지되는 의미를 공통 문법으로,
+대상별 차이를 domain 계약으로, 키와 수신 조건을 입력 계약으로 구체화한다.
+기본 Hands profile은 이를 익숙한 동작으로 조합한다. 단축키에 직접 드러나지 않는
+선택 mapping·원자성·gesture 취소도 그 작업을 성립시키는 데 필요하면 남긴다.
+
 ### 명령 이름보다 대상과 결과를 먼저 비교한다
 
 Apple의 [1992년 Macintosh Human Interface Guidelines](https://www.vintageapple.org/inside_r/pdf/Human_Interface_Guidelines_1992.pdf)
@@ -114,7 +148,7 @@ transition·map·reconcile·targets가 이미 이 차이의 정본 경계를 제
 
 ### 중첩은 입력을 받을 곳의 계약이다
 
-[W3C APG Grid](https://www.w3.org/WAI/ARIA/apg/patterns/grid/#editing-and-navigating-inside-a-cell)는
+[W3C APG Grid](https://www.w3.org/WAI/ARIA/apg/patterns/grid/#keyboardinteraction-settingfocusandnavigatinginsidecells)는
 셀 탐색에 쓰는 화살표와 셀 안의 caret·widget 조작을 구분한다.
 [Keynote의 텍스트 상자](https://support.apple.com/en-ca/guide/keynote/tan4fd6ee725/mac)는
 객체 자체와 그 안의 텍스트를 따로 선택한다. 두 자료는 지침·제품 관습의 근거이며
@@ -139,6 +173,13 @@ Canvas Hand
 처리하지 않은 입력의 명시적 위임과 실패를 구별하며, 정확한 키·진입 방법은 입력
 profile이 정한다. 아직 전체 Hands에 실행 검증된 새 규칙은 아니다.
 
+명령 후보를 찾는 단계의 미적용과 실행한 편집의 거절도 구별한다.
+[ProseMirror Commands](https://prosemirror.net/docs/guide/#commands)는 적용할 수 없는
+명령의 `false`와 다음 후보 탐색을 정의한다. 이를 이 레포의 `EditingResult.ok: false`와
+같은 뜻으로 연결하지 않는다. [DOM Event](https://dom.spec.whatwg.org/#interface-event)의
+기본 동작 취소·전파 중단도 편집 성공과 별개의 관찰이며, 어떤 입력을 맡았는지는
+해당 binding의 계약으로 판단한다.
+
 여기서 편집 맥락은 HTML `editing host`, DOM element, JSON subtree, History
 instance와 일대일 대응하지 않는다. Toolbar로 focus가 옮겨져도 편집 명령은 저장된
 선택을 대상으로 할 수 있다. Headless 호출은 DOM focus 없이 대상을 지정할 수 있다.
@@ -155,7 +196,7 @@ native range의 방향을 투영하고, [Web virtual selection scope](../package
 
 | 과도한 일반화 | 근거 있는 반례 | 이 설계의 처리 |
 | --- | --- | --- |
-| 선택은 언제나 Undo 대상이 아님 | [GIMP Undoing](https://docs.gimp.org/3.0/en/gimp-concepts-undo.html)은 Scissors Select 작업과 Quick Mask 전환의 Undo를 설명 | 현재 일시적 Selection의 EG-SELECT·EG-HISTORY를 유지. Raster 선택 제작의 History 정책으로 일반화하지 않음 |
+| 선택만 바꾼 작업은 어떤 경우에도 Undo 기록이 아님 | [GIMP Undoing](https://docs.gimp.org/3.0/en/gimp-concepts-undo.html)의 선택 도구 작업과 [AppKit Undo](https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/UndoArchitecture/Articles/AppKitUndo.html)의 저장되지 않는 view selection 기록 | 편집 전 선택 복원과 selection-only 기록을 구별. 현재 EG-SELECT·EG-HISTORY의 기본 정책을 다른 profile 전체에 강제하지 않음 |
 | 이동은 항상 Copy 후 즉시 제거한 뒤 Paste | [Finder 이동](https://support.apple.com/en-gb/102650)은 Clipboard의 파일을 목적지에 옮기는 동작을 제공 | EG-CUT은 현재 즉시 제거하는 cut 계약. 지연 이동은 같은 계약의 이름만 다른 구현이 아님 |
 | 복사한 저장 값을 그대로 넣으면 의미도 보존 | [Excel 수식 이동·복사](https://support.microsoft.com/en-us/excel/move-or-copy-a-formula-in-excel)는 복사 시 상대 참조 변경, 수식 이동 시 참조 유지를 구별 | payload의 참조·identity·배치 변환은 profile 계약. JSON 모양이나 text 일치만으로 교환 호환성을 판정하지 않음 |
 | Shift-click 확장은 항상 같은 anchor를 고정 | Apple HIG 1992 인쇄 쪽수 290–291은 addition과 fixed-point 두 방식을 설명 | 현재 EG-SELECT의 고정 anchor 전이를 유지. 다른 입력 관습을 같은 전이로 일반화하지 않음 |
@@ -249,6 +290,71 @@ Document·Sheet 등은 Editing에, Rich Text는 자신의 package에 구현돼 
 Hands는 기존 공개 API들의 함께 검증된 조합이다. Host는 제품 데이터·권한·copy·
 layout·concrete external instance와 조합을 소유한다.
 
+## 기본 Profile이 제공할 편집 동작
+
+이 설계에서 기본 Hands profile은 **선택한 대상·입력·History 계약과 그 조합의
+적합성 기준**을 묶는다.
+기본 Profile은 해당 편집 대상을 사용할 때 추가 정책 선택 없이 기대할 동작을 정한다.
+Text·Sheet·Object가 같은 저장 model이나 선택 모양을 사용할 필요는 없다.
+공통 기본 규칙을 각 대상별 계약과 조합하며, 같은 책임은 기존 정본 모듈에서 구현한다.
+
+| 층위 | 약속하는 것 | 변형의 경계 |
+| --- | --- | --- |
+| Core와 기반 모듈 | JSONDocument의 원자적 commit·관찰, Selection·Editing 등 각 owner의 공개 계약 | 어떤 Profile도 소비하는 기반 계약의 보장을 약화하지 않음 |
+| 기본 Hands profile | 대상별 의미와 정착한 기본 입력·편집 결과·선택·복원 | 설정을 생략했을 때의 동작까지 명시하고 검증 |
+| 허용된 설정 또는 다른 Profile | 다른 입력 관습·기록 범위·교환 정책이 필요한 경우의 선언된 차이 | 같은 Profile 안에서 허용한 선택인지, 별도 Profile/revision인지 식별 |
+
+기존 [JSON Document v3 profile](json-document-v3/profile.md)은 기반 계약을,
+[Rich Text v1 profile](json-document-rich-text-v1/profile.md)은 대상별 계약을 정의한다.
+[Official Hands Profile](../docs/public/official-hands.md)은 입력까지 조합하는 위치다.
+기본 편집 동작을 묶는다는 이유로 이 계약들을 하나의 runtime 객체로 합치지 않는다.
+
+### 채택할 기본 의미와 구체화할 조건
+
+다음은 이 초안이 기본으로 제공하려는 의미다. 기존 동작·EG 규칙과 연결하며,
+뒤에 적은 조합 검증이 끝나기 전까지 모든 Hands의 구현 완료로 표시하지 않는다.
+
+| 동작 | 기본 Profile의 약속 | 구체화할 조건 / 연결 |
+| --- | --- | --- |
+| Undo 입력 | macOS `Cmd+Z`, Windows `Ctrl+Z`를 Undo 의도로 해석 | 편집 맥락의 수신 History, 실행 가능 여부와 조합 중 입력 처리. Web·Affordance |
+| 편집 Undo/Redo | 외부 변경이 개입하지 않은 Undo는 편집 전 내용·선택을, Redo는 편집 후 내용·선택을 함께 복원 | 선택 범위와 방향, 여러 view의 귀속, 외부 변경 후 유효한 위치 복원. EG-HISTORY·EG-RESULT |
+| 선택만 변경 | document와 문서 Undo/Redo 기록을 유지 | 선택 변경을 별도 Undo 대상으로 제공하는 정책과 구별. EG-SELECT |
+| Copy | 현재 편집 맥락의 대상을 읽고 document·selection·History를 유지 | 셀 전체와 내부 문자열, 구조 표현과 교환 표현. EG-TARGET·EG-COPY |
+| Cut/Paste | 확보한 대상에 대한 제거 또는 목적지에 맞는 삽입을 편집 결과와 후속 선택으로 설명 | 표현 선택·변환·거절·native 위임의 경계. EG-CUT·EG-PASTE |
+| 작업 단위 | typing·composition·drag를 사용자에게 의미 있는 Undo 단위로 제공 | grouping의 경계와 취소 결과는 대상·입력·History 계약의 조합에서 명시. EG-GESTURE·EG-HISTORY |
+
+[CKEditor Undo](https://ckeditor.com/docs/ckeditor5/latest/api/module_undo_undo-Undo.html)는
+batch와 편집 전 selection을 함께 기록하며,
+[UndoCommand](https://ckeditor.com/docs/ckeditor5/latest/api/module_undo_undocommand-UndoCommand.html)는
+그 selection을 복원한다. [CodeMirror History](https://codemirror.net/docs/ref/#commands.history)는
+일반 Undo와 selection 변경도 되돌리는 `undoSelection`을 구별한다. 해당 editor의
+공개 계약은 기본 복원의 근거가 되며, 특정 내부 알고리즘을 Core에 요구하지 않는다.
+
+특히 **편집과 함께 선택을 복원하는 것**과 **선택만 바꾼 작업을 새 Undo step으로
+기록하는 것**은 별개의 결정이다. 기본 Profile은 전자를 약속하고 현재 EG-SELECT의
+selection-only 정책을 유지한다. 후자의 변형이 필요하면 History owner의 지원과
+그 Profile의 적합성을 별도로 확인한다.
+
+### 기본값과 설정의 호환성
+
+설정을 생략하는 것도 Profile의 유효한 사용이다. 따라서 기본값만 바꾸는 변경도
+기존 소비자의 결과를 바꾸면 호환성 변경이다. 사용자가 근육기억으로 익힌 조작은
+키 조합뿐 아니라 어느 맥락의 무엇을 어떻게 바꾸는지까지 포함한다. 기본 키가
+같아도 Undo 수신자나 선택 복원을 바꾸면 그 약속을 바꾼 것이다.
+문서와 검증 사례에는 Profile revision, 대상·입력 계약, 선택한 설정과 생략 시
+기본값을 식별할 수 있게 남긴다.
+모든 payload에 새 식별 필드를 추가하라는 요구는 아니다.
+
+| 변경 | 같은 Profile을 유지할 조건 |
+| --- | --- |
+| 내부 구현·캐시 교체 | 같은 입력·설정에서 대상·결과·선택·History·실패 의미가 보존됨 |
+| 사용자의 단축키 재설정 | Profile이 허용한 입력 설정이며 Undo 의도와 복원 결과는 유지됨 |
+| 기본 단축키·selection-only 기록·Paste 우선순위 변경 | 기존 revision의 생략된 설정과 명시된 설정 모두 기존 의미를 유지해야 함. 보존하지 못하면 별도 Profile/revision으로 제공 |
+
+허용할 설정의 목록은 각 Profile에 둔다. keymap을 재정의할 수 있는 API가 있다고
+모든 재정의를 같은 기본 Profile의 적합한 동작으로 인정하지 않는다. 선택지는
+열어 두되, 기본 경로를 사용하는 제품이 반복해서 정책을 설계할 필요가 없게 한다.
+
 ## 공통으로 고정할 편집 규칙
 
 아래 ID는 설계 요구사항이다. 실제 동결은 owner의 versioned 계약과 적합성
@@ -256,7 +362,7 @@ layout·concrete external instance와 조합을 소유한다.
 규칙의 전제가 아니다.
 
 이 표의 적용 범위는 현재 구조·텍스트 편집 profile의 계약이다. EG-SELECT의
-일시적 선택과 문서 History 분리, EG-CUT의 즉시 제거를 다른 장르의 모든 관습으로
+selection-only 기록 정책과 EG-CUT의 즉시 제거를 다른 장르의 모든 관습으로
 일반화하지 않는다. 범위 확장의 anchor 규칙은 고정 anchor로 확장하는 현재
 range 전이에 적용한다. 다른 family나 raster·지연 이동 profile을 동결하려면 해당 상태와
 History·transfer 의미를 먼저 명시해야 하며, 기존 profile의 규칙을 느슨하게
@@ -284,6 +390,13 @@ Headless `cut()`은 보존 가능한 payload를 반환하고, Web event binding
 서로 다른 결과로 검증한다. 브라우저가 custom edit를 다시 실행하지 않도록 하는
 event ownership은 Web이 소유한다.
 
+Web의 메모리 Clipboard 테스트가 확인하는 것은 표현 쓰기와 editor callback의
+결과다. 쓰기 실패 시 제거 callback이 호출되지 않았더라도 실제 브라우저의 후속
+기본 동작까지 차단됐다고 단정할 수 없다. [Clipboard API 초안의 cut 처리](https://www.w3.org/TR/2026/WD-clipboard-apis-20260624/#cut-action)와
+연결해 event 취소 상태·후속 native 편집·OS Clipboard 반영을 별도로 관찰해야 한다.
+이것은 기본 Cut 보장의 검증 범위이며 확정된 브라우저 결함이나 OS transaction
+보장으로 해석하지 않는다.
+
 EG-HISTORY에서 외부 변경 이후의 의미는 선택한 History 계약을 따른다. 현재
 local inverse History는 이를 비우며, collaboration History는 내 기여를 선택적으로
 되돌린다. 둘을 같은 복원 알고리즘으로 고정하지 않는다. 이미 존재하는
@@ -294,6 +407,12 @@ composition grouping은 [DOM 편집 lifecycle](dom-editing-lifecycle.md)의 별
 계약을 따른다. `createGestureSession`의 존재만으로 Host의 preview가 문서를
 변경하지 않는다고 증명할 수 없으므로 실제 연결까지 검증한다.
 
+입력 중 native 표시와 확정된 document, History step도 구별한다.
+[Input Events Level 2 초안](https://www.w3.org/TR/2026/WD-input-events-2-20260501/#input-event-order-during-composition)은
+취소할 수 없는 IME 조합 갱신을 설명한다. 기본 Profile의 입력 결과·취소·Undo
+의미를 고정하고, 실제 입력 trace가 그 결과로 귀결되는지는 Web binding에서
+검증한다. Working Draft의 특정 이벤트 순서나 지연 시간을 Core에 고정하지 않는다.
+
 ## Hands profile이 반드시 결정할 내용
 
 각 profile은 다음 질문에 하나의 답 또는 명시적인 설정별 답을 제공한다. 이는
@@ -346,6 +465,23 @@ Copy를 부분 문자열 Copy로 바꾸지는 않는다. Sheet의 primary rectan
 아니다. 이미 다른 의미를 가진 호출들을 한 이름으로 합치면 대상과 결과의 차이가
 숨는다. 공통 protocol은 공유하는 규칙에 두고, 문서의 의미는 기존 owner에 둔다.
 
+### 기본 Profile의 코드 연결을 설계할 위치
+
+다음 표는 후속 구현에서 확인할 정본과 공백을 연결한다. 이 문서 변경은 해당 API를
+확장하지 않으며, 기존 API로 조합할 수 있는지 확인한 뒤 부족한 owner만 확장한다.
+
+| 책임 | 기존 코드와 API | 다음 설계에서 닫을 공백 |
+| --- | --- | --- |
+| 기본 입력 해석·실행 가능 표시 | Web [keyboard.ts](../packages/json-document-web/src/keyboard.ts)의 `defaultWebKeymap`, `createWebKeyboardAdapter`; Affordance의 `historyAffordance` | 설정 생략·허용된 재설정에서 Undo 의도가 보존되는지 확인. 기본 keymap을 Host마다 복제하지 않음 |
+| 편집·선택·History 연결 | Editing의 `createEditingSession`, [EditingHistory](../packages/json-document-editing/src/history.ts) | 모델의 전후 선택과 native 선택 투영을 구별하고, 여러 view에서 실행할 History와 복원 대상 명시 |
+| 중첩 진입·복귀와 입력 수신 | Affordance의 rename/gesture lifecycle, Web의 `isWebEditingHostTarget`, 각 domain의 Web binding | 후보 미적용·맡은 편집 거절·명시적 위임을 구별하는 연결. 유효한 조합을 지원하지 못하면 정본 API에서 해결 |
+| 표현 교환과 Paste | Web의 `createWebClipboardBinding`, domain의 codec·표현·paste API | 표현 선택 실패와 선택한 payload의 편집 거절을 구별. 실제 native 후속 처리까지 관찰 |
+
+먼저 아래의 기본 Undo 사례를 공개 API 조합에 연결하고, 같은 기대 결과를 입력
+binding까지 확장한다. 중첩·여러 view·외부 표현의 차이는 해당 계약에서 별도로
+구체화한다. 구현을 바꿀 때 필요한 owner reference·Usage·source 등록은 각 owning
+package의 기존 위치에서 함께 갱신한다.
+
 ## 적합성 설계
 
 테스트의 단위는 함수 유무가 아니라 **시작 상태 → 의미 있는 작업 → 관찰 결과**다.
@@ -452,6 +588,8 @@ profile 동결로 확대하지 않는다.
 | 사례 | 시작 상태 → 작업 → 판정할 결과 | 연결·현재 증거의 한계 |
 | --- | --- | --- |
 | 셀과 내부 문자열 | `Alpha` 셀 선택 / 내부 `ph` 선택 각각에서 Copy → 셀 payload / `ph` | EG-TARGET·EG-COPY. 기존 Sheet·native selection 증거는 각각 있으며 이 중첩 전체의 공통 binding은 없음 |
+| 기본 Undo와 선택 복원 | 아래의 `Alpha` 범위 교체 → Undo → Redo; 정방향·역방향 각각 실행 | EG-HISTORY·EG-RESULT. 전후 model selection 증거와 실제 native range 복원 증거를 구별 |
+| 선택만 변경한 뒤 Redo | 편집 → Undo → 선택만 이동 → Redo → 기록된 편집 후 내용·선택 | EG-SELECT·EG-HISTORY. 기본 Profile에서 선택 이동이 새 문서 History entry를 만들거나 Redo를 지우지 않음 |
 | 거절 시 바깥으로 전이 금지 | 선택한 객체 안의 text editor가 Delete 거절 → 객체 제거·외부 History entry가 생기지 않음 | EG-EDIT·입력 계약 후보. [Web clipboard ownership](../packages/json-document-web/tests/clipboard-rejection.test.ts)은 한 binding의 거절 처리 증거이며 일반적인 중첩 거절 vector는 없음 |
 | Toolbar 대상 보존 | editor A에서 범위 선택 → Toolbar에 focus → Copy 실행 → A의 선택 payload | 입력 focus와 Selection 구별. 전체 Hands에 대한 공통 실행 증거 없음 |
 | 셀 값과 행 구조 | 값이 있는 셀을 비움 / 해당 record 삭제 → 전자는 구조 유지, 후자는 record 제거 | EG-EDIT·profile 대상. 현재 Sheet Cut과 Database `record.delete`는 서로 다른 계약 |
@@ -459,12 +597,29 @@ profile 동결로 확대하지 않는다.
 | Draft 취소와 Undo | 미확정 rename draft 수정 → cancel → 확정 label 불변; 확정 rename → Undo → 이전 label | EG-GESTURE·EG-HISTORY. 구조 gesture runner가 모든 rename·IME 취소를 증명하지 않음 |
 | 외부 참조·다른 profile로 Paste | 수식 또는 reference를 다른 위치·profile에 Paste → 변환·보존·거절 중 선언한 결과 | EG-PASTE. 현재 세 editor의 내부 round trip만으로 cross-profile 교환을 인증할 수 없음 |
 | 공유 문서의 두 편집 맥락 | A에서 편집 → B로 입력 focus 전환 → Undo → 선택한 History owner가 명시한 기여·선택 복원 | EG-HISTORY·EG-RESULT. 외부 History 연결 증거와 모든 Hand의 입력 routing 증거는 다름 |
+| Cut 쓰기 실패 후 native 처리 | editable selection에서 지원하는 Cut의 표현 쓰기 실패 → 해당 작업의 원본 제거 없음 | EG-CUT·Web. 제거 callback 미호출 외에 event 취소·후속 beforeinput/input·document·History를 관찰. 브라우저 재현 전 검증 공백 |
+| IME와 Undo 수신 | 조합 완료 / 취소 / 조합 중 Undo·focus 이동 → 선언된 내용·선택·History·입력 상태 | EG-HISTORY·Web lifecycle. 합성 composition fixture와 OS IME 검증을 구별 |
+
+기본 Undo 사례는 Rich Text에서 다른 변경이 끼어들지 않고 `ph`를 `X`로 교체하는
+상황으로 구체화한다. offset은 같은 text node 안의 위치다.
 
-이번 도출로 설계 방향을 정할 수 있는 부분은 대상·위치·선택·입력 수신자의 구별,
-대상별 계약과 입력 계약의 조합, 기존 owner의 유지다. 아직 동결할 수 없는 부분은
-중첩 편집의 진입·거절·복귀 규칙, profile 간 payload 변환, raster/file 편집의
-적용 범위, 여러 편집 맥락의 History routing이다. 같은 profile을 독립적으로
-구현했을 때 이 사례들의 결과가 일치해야 장기 호환성 약속으로 승격할 수 있다.
+| 단계 | 내용 | 선택과 History의 기대 결과 |
+| --- | --- | --- |
+| 시작 | `Alpha` | 정방향 `(anchor: 2, focus: 4)` 또는 역방향 `(anchor: 4, focus: 2)`으로 `ph` 선택. History 비어 있음 |
+| 교체 | `AlXa` | offset 3의 collapsed caret. 한 번의 Undo 가능 |
+| Undo | `Alpha` | 시작 때의 범위와 방향 복원. Undo 불가·Redo 가능 |
+| Redo | `AlXa` | offset 3의 collapsed caret 복원. Undo 가능·Redo 불가 |
+
+선택만 바꾼 뒤 Redo하는 후보는 Undo 행과 Redo 행 사이에서 caret을 옮겨 실행한다.
+이 선택 이동은 별도 step이 아니며, Redo는 기록된 교체 후 선택을 복원해야 한다.
+이 표는 공개 동작에 대한 기대 결과다. 새 테스트의 통과를 주장하지 않으며,
+Document의 offset 하나만으로 과거 native range 전체를 복원할 수 있다고 가정하지 않는다.
+
+기본 Profile의 역할과 Undo·선택 복원의 기본 의미는 설계에 채택한다. 입력 수신,
+중첩의 진입·거절·복귀, profile 간 payload 변환과 여러 view의 History 귀속은
+위 사례로 더 구체화한다. 기본값을 정하는 것과 동결을 인증하는 것은 다른 단계다.
+같은 profile을 독립적으로 구현했을 때 결과가 일치하고 실제 입력 경로에서도
+약속이 유지되어야 장기 호환성 증거로 승격할 수 있다.
 
 ## 장기 호환성
 

From 97405f78f464b7b311a822d68fddc999422b05e1 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E1=84=8B=E1=85=B2=E1=84=8B=E1=85=AD=E1=86=BC=E1=84=90?=
 =?UTF-8?q?=E1=85=A2?= <teo.v@navercorp.com>
Date: Tue, 8 Sep 2026 09:38:49 +0900
Subject: [PATCH 04/20] =?UTF-8?q?docs:=20=EA=B8=B0=EB=B3=B8=20=ED=8E=B8?=
 =?UTF-8?q?=EC=A7=91=20=EA=B3=84=EC=95=BD=ED=91=9C=EC=99=80=20=EC=B5=9C?=
 =?UTF-8?q?=EC=86=8C=20=EC=BD=94=EB=93=9C=20=EB=B3=80=EA=B2=BD=EC=95=88?=
 =?UTF-8?q?=EC=9D=84=20=EA=B5=AC=EC=B2=B4=ED=99=94=ED=95=9C=EB=8B=A4?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 standards/editing-grammar.md | 151 +++++++++++++++++++++++++----------
 1 file changed, 107 insertions(+), 44 deletions(-)

diff --git a/standards/editing-grammar.md b/standards/editing-grammar.md
index 9caf48c7..9c43ce7c 100644
--- a/standards/editing-grammar.md
+++ b/standards/editing-grammar.md
@@ -309,19 +309,37 @@ Text·Sheet·Object가 같은 저장 model이나 선택 모양을 사용할 필
 [Official Hands Profile](../docs/public/official-hands.md)은 입력까지 조합하는 위치다.
 기본 편집 동작을 묶는다는 이유로 이 계약들을 하나의 runtime 객체로 합치지 않는다.
 
-### 채택할 기본 의미와 구체화할 조건
+### 기본 동작별 계약
 
-다음은 이 초안이 기본으로 제공하려는 의미다. 기존 동작·EG 규칙과 연결하며,
-뒤에 적은 조합 검증이 끝나기 전까지 모든 Hands의 구현 완료로 표시하지 않는다.
+기본 Profile에서 먼저 닫을 범위는 아래 12개 동작이다. 각 대상에 적용되는 동작을
+기본 경로로 제공하며, 미지원과 일시적 실행 불가를 구별한다. 예를 들어 내부 편집을
+제공하는 Hand에는 진입·확정·취소·복귀가 필요하지만, 모든 객체에 text editor를
+내장할 필요는 없다. 표는 이 초안이 채택하는 계약이며 전체 Hands의 구현 완료나
+기존 API 기본값의 즉시 변경을 뜻하지 않는다.
 
-| 동작 | 기본 Profile의 약속 | 구체화할 조건 / 연결 |
-| --- | --- | --- |
-| Undo 입력 | macOS `Cmd+Z`, Windows `Ctrl+Z`를 Undo 의도로 해석 | 편집 맥락의 수신 History, 실행 가능 여부와 조합 중 입력 처리. Web·Affordance |
-| 편집 Undo/Redo | 외부 변경이 개입하지 않은 Undo는 편집 전 내용·선택을, Redo는 편집 후 내용·선택을 함께 복원 | 선택 범위와 방향, 여러 view의 귀속, 외부 변경 후 유효한 위치 복원. EG-HISTORY·EG-RESULT |
-| 선택만 변경 | document와 문서 Undo/Redo 기록을 유지 | 선택 변경을 별도 Undo 대상으로 제공하는 정책과 구별. EG-SELECT |
-| Copy | 현재 편집 맥락의 대상을 읽고 document·selection·History를 유지 | 셀 전체와 내부 문자열, 구조 표현과 교환 표현. EG-TARGET·EG-COPY |
-| Cut/Paste | 확보한 대상에 대한 제거 또는 목적지에 맞는 삽입을 편집 결과와 후속 선택으로 설명 | 표현 선택·변환·거절·native 위임의 경계. EG-CUT·EG-PASTE |
-| 작업 단위 | typing·composition·drag를 사용자에게 의미 있는 Undo 단위로 제공 | grouping의 경계와 취소 결과는 대상·입력·History 계약의 조합에서 명시. EG-GESTURE·EG-HISTORY |
+| 동작 | 대상 → 기본 결과 | 후속 선택·History | 구체화할 차이 / 기존 owner |
+| --- | --- | --- | --- |
+| 탐색 | 현재 맥락의 위치 → 유효한 이웃·경계로 이동, 문서 불변 | 대상별 caret 또는 논리 focus·선택 전이. 문서 History 유지 | 문자·셀·가시 노드의 단위와 선택 동반 여부. Selection·Topology·입력 계약 |
+| 선택 | 유효한 대상·삽입점 → 요청한 선택으로 전이 | 내용·문서 Undo/Redo 기록 유지 | range·key set, primary와 복수 범위. Selection·editor |
+| 선택 확장 | 기존 선택 → 확장한 범위 | 고정 anchor 범위는 anchor를 보존하며 focus 이동. 문서 History 유지 | 문자·셀·가시 순서; key 집합 추가는 별도 전이. Selection·Topology |
+| 전체 선택 | 현재 맥락이 정한 전체 대상 → 한 선택 전이로 전부 선택 | 같은 대상 집합에서 반복해도 유지. 문서 History 유지 | 기본 입력도 선택 해제로 토글하지 않음. 단계적 범위 확대·토글은 다른 입력 정책. Selection·Affordance |
+| 삽입·교체 | 삽입점·대체 범위 또는 명시 대상 → 유효한 새 내용·구조 | 삽입 후 작업 위치 또는 삽입 대상 선택. 확정 작업 단위로 Undo | 문자열 대체·셀 값 commit·객체 삽입의 의미. domain·Editing |
+| 삭제 | 선택 대상 또는 삽입점 주변 → 선언한 내용·구조 제거 | 유효한 남은 위치·대상 또는 빈 선택. 확정 작업 단위로 Undo | 문자 삭제·셀 값 비우기·subtree 제거 구별. domain·Editing |
+| Copy | 현재 맥락의 대상 → 구조 payload와 교환 표현 | document·selection·History 유지 | 셀 전체와 내부 문자열, 표현과 대상 폐포. domain·Web |
+| Cut | 확보한 대상 → payload 확보 후 그 대상 제거 | domain이 정한 삭제 후 선택. 성공한 편집의 Undo | 확보 실패 시 제거 없음, 제거 거절 시 편집 상태 유지. domain·Editing·Web |
+| Paste | 목적지·대체 범위와 payload → 목적지 계약에 맞는 삽입 | 삽입 결과에 맞는 선택. 확정 작업 단위로 Undo | 표현 우선순위·identity·참조 변환·경계·거절. domain·Web·Editing |
+| Undo·Redo | 선택한 History의 작업 → 편집 전·후 상태 복원 | 외부 변경이 없으면 내용과 선택 범위·방향을 함께 복원 | grouping·외부 변경·여러 view의 귀속. Editing·선택한 History owner |
+| 내부 편집 진입 | 선택한 셀·항목·객체 → 해당 내부 편집 맥락 | 진입만으로 문서 History를 만들지 않음. 외부 선택과 복귀 대상 보존 | F2·Enter·pointer의 의미와 내부 선택 초기화. Affordance·domain·Web |
+| 확정·취소·복귀 | 진행 중인 명시적 draft → 성공 시 확정·복귀, 취소 시 확정 내용 유지 | 성공한 확정만 Undo 대상. 확정 거절 시 draft와 편집 맥락 유지 | 대상이 유효한 rename·cell draft의 기본 정책. 연속 입력·IME는 별도 lifecycle. Affordance·domain·Web |
+
+기본 Undo 입력은 macOS `Cmd+Z`, Windows `Ctrl+Z`다. Copy·Cut·Paste와 전체
+선택도 선택한 플랫폼의 기본 입력으로 연결한다. 키 이름만으로 수신자를 정하지
+않으며, 중첩 맥락·native control·조합 중 입력의 소유권을 함께 결정한다.
+typing·composition·drag의 grouping은 각 계약의 작업 경계로 명시한다.
+
+Object의 방향키가 좌표 변경을 뜻하면 그것은 탐색과 다른 편집이며 Undo 대상이다.
+Rich Text의 Enter가 단락 삽입이면 그것을 draft 확정과 같은 작업으로 해석하지
+않는다. 이런 차이는 새 전역 command union 대신 대상별 계약에 남긴다.
 
 [CKEditor Undo](https://ckeditor.com/docs/ckeditor5/latest/api/module_undo_undo-Undo.html)는
 batch와 편집 전 selection을 함께 기록하며,
@@ -433,23 +451,28 @@ composition grouping은 [DOM 편집 lifecycle](dom-editing-lifecycle.md)의 별
 기대되는 기본 편집 흐름을 생략할 수 없으며, 그 선택의 외부 관습이나 제품 목적을
 profile에서 설명한다.
 
-### 현재 구현을 설명하는 대표 매핑
+### 대상별로 비교한 현재 결과
 
 이 표는 현재 동작의 관찰이다. 관찰된 기본값이 곧 영구히 고정할 규칙은 아니다.
 
-| 항목 | Document | Sheet | Rich Text |
+| 대상 / binding | 선택·Copy 대상 | 교체·제거 → 후속 선택 | Paste → 후속 선택 |
 | --- | --- | --- | --- |
-| 편집 단위 | stable ID를 가진 블록과 text | stable row/column ID의 셀 | stable node ID와 text/child point |
-| Copy 대상 | 선택된 블록 전체 | primary rectangle | 선택된 structured slice |
-| Paste | 기본적으로 마지막 선택 블록 뒤에 삽입 | focus 셀부터 고정 경계 안에 기록 | 선택 구간과 schema에 맞게 slice 삽입 |
-| 제거 | 선택 블록 제거 | Cut은 primary rectangle 값을 `null`로 비움 | 선택 구간 제거·schema 제약 적용 |
-| 후속 선택 | 삽입 블록마다 collapsed range, 첫 블록 primary; 삭제 후 남은 이웃 | 붙여넣은 직사각형, Cut은 기존 선택 | transform 후 mapping된 text/child point |
-
-현재 binding은 각각 `json-document-editing/src/document.ts`, `sheet.ts`,
-`json-document-rich-text/src/editor.ts`에 있다. Document의 text offset이 블록
-Copy를 부분 문자열 Copy로 바꾸지는 않는다. Sheet의 primary rectangle 정책도
-여러 범위 전체의 Copy와 구별한다. 이런 차이는 profile 이름과 사용법에서 드러나야
-하며, 공통 함수 이름 때문에 사용자가 동일한 대상을 예상하게 해서는 안 된다.
+| [Rich Text](../packages/json-document-rich-text/src/editor.ts) | node ID + text/child range, structured slice | `text.insert`는 선택 구간 대체; 제거는 schema 제약 적용 → mapping된 point | 선택 구간에 slice 삽입 → 삽입 결과의 point |
+| [Document](../packages/json-document-editing/src/document.ts) | block ID + offset, Copy는 블록 전체 | `text.replace`는 블록 문자열 교체 → 지정 offset 또는 끝; 제거 → 남은 이웃 | 기본적으로 마지막 선택 블록 뒤에 삽입 → 블록마다 collapsed range, 첫 블록 primary |
+| [Tree](../packages/json-document-editing/src/tree.ts) | 가시 노드 범위; Copy·제거는 숨은 후손도 포함 | 선택 subtree 제거 → 남은 가시 이웃 또는 빈 선택 | 대상 노드와 같은 parent 아래 새 ID의 subtree 추가 → 삽입 root들 선택 |
+| [Sheet](../packages/json-document-editing/src/sheet.ts) | 셀 range들의 집합; Copy는 primary rectangle | `cell.commit` → 해당 셀; `selection.fill(null)`은 선택된 셀 값, Cut은 primary 값만 비움 → 선택 유지 | focus 셀부터 경계 내 기록 → 붙여넣은 직사각형 |
+| [Object](../packages/json-document-editing/src/object.ts) | object ID 집합; Copy는 해당 객체 | 속성 변경·이동과 객체 제거를 구별; 제거 → 저장 순서의 남은 이웃 또는 빈 선택 | 새 ID와 선언한 좌표 offset으로 추가 → 삽입 객체들 선택 |
+
+이들의 기본 local History는 외부 변경이 없는 편집의 전후 내용·선택을 기록한다.
+같은 Undo 규칙을 공유해도 문자열 range·가시 노드 범위·셀 rectangle·object ID
+집합을 하나의 선택 모양으로 합칠 필요는 없다.
+
+탐색의 단위도 대상별이다. Text의 caret, Tree의 가시 순서, Sheet의 행·열 topology를
+구별하고 Object의 좌표 변경과 분리한다. 항목 label의 내부 편집은 현재
+[Order](../packages/json-document-editing/src/order.ts)의 `item.rename`과
+`createRenameSession` 조합으로 확인한다. Tree·Object에 같은 내부 편집이 이미
+제공된다고 일반화하지 않는다. Database의 record, Calendar의 occurrence, Annotation의
+source 참조와 Composer의 중첩은 앞의 11개 사례에서 정한 domain 차이를 유지한다.
 
 ## 구현에서 계약으로 옮길 때의 결정
 
@@ -465,22 +488,54 @@ Copy를 부분 문자열 Copy로 바꾸지는 않는다. Sheet의 primary rectan
 아니다. 이미 다른 의미를 가진 호출들을 한 이름으로 합치면 대상과 결과의 차이가
 숨는다. 공통 protocol은 공유하는 규칙에 두고, 문서의 의미는 기존 owner에 둔다.
 
-### 기본 Profile의 코드 연결을 설계할 위치
+### 하이라키 검토와 최소 코드 변경안
 
-다음 표는 후속 구현에서 확인할 정본과 공백을 연결한다. 이 문서 변경은 해당 API를
-확장하지 않으며, 기존 API로 조합할 수 있는지 확인한 뒤 부족한 owner만 확장한다.
+기본 Undo 사례는 기존 `createRichTextEditor`와 Web keymap의 공개 API 조합으로
+실행됐다. 따라서 이 경로를 위해 Core에 Selection·History를 넣거나 새 session
+계층을 추가하지 않는다. 현재 공백은 기반 보장을 기본 동작으로 조합하는 계약에 있다.
 
-| 책임 | 기존 코드와 API | 다음 설계에서 닫을 공백 |
+| 확인한 계약과 증거 | 판단 / 최소 변경안 | 완료를 판정할 사례 |
 | --- | --- | --- |
-| 기본 입력 해석·실행 가능 표시 | Web [keyboard.ts](../packages/json-document-web/src/keyboard.ts)의 `defaultWebKeymap`, `createWebKeyboardAdapter`; Affordance의 `historyAffordance` | 설정 생략·허용된 재설정에서 Undo 의도가 보존되는지 확인. 기본 keymap을 Host마다 복제하지 않음 |
-| 편집·선택·History 연결 | Editing의 `createEditingSession`, [EditingHistory](../packages/json-document-editing/src/history.ts) | 모델의 전후 선택과 native 선택 투영을 구별하고, 여러 view에서 실행할 History와 복원 대상 명시 |
-| 중첩 진입·복귀와 입력 수신 | Affordance의 rename/gesture lifecycle, Web의 `isWebEditingHostTarget`, 각 domain의 Web binding | 후보 미적용·맡은 편집 거절·명시적 위임을 구별하는 연결. 유효한 조합을 지원하지 못하면 정본 API에서 해결 |
-| 표현 교환과 Paste | Web의 `createWebClipboardBinding`, domain의 codec·표현·paste API | 표현 선택 실패와 선택한 payload의 편집 거절을 구별. 실제 native 후속 처리까지 관찰 |
+| Rich Text의 범위 교체·Undo·Redo와 [EditingHistory](../packages/json-document-editing/src/history.ts): 아래 12개 공개 API 사례 통과 | 이 범위의 runtime·API 변경 불필요. 기존 owner의 conformance binding에 사례를 정착시키고 실제 native 선택 경로 확인 | 양방향 범위 복원, Undo 후 선택 이동과 Redo 보존. model과 DOM 관찰 구별 |
+| [selectAllAffordance](../packages/json-document-affordance/src/select.ts)는 `allSelected: true`에서 `clear` 반환 | Affordance에 반복 입력 정책을 명시적으로 선택할 수 있는 경로 추가. 기본 Hands는 선택 유지 정책 사용; 기존 토글 호출의 생략된 설정은 보존 | 같은 universe에서 두 번 Mod+A → 전체 선택 유지; 명시한 토글 경로 → 해제 |
+| [createRenameSession](../packages/json-document-affordance/src/session.ts)의 `onCommit`은 `void`; editor 거절 후에도 draft를 지우고 `onFinish` 호출 | Affordance에 성공 여부를 받는 확정 경로 추가. 거절 시 draft 유지, 성공 시 한 번 종료. 기존 `void` callback 경로는 보존 | label 검증 거절 → 내용·선택·History와 draft 유지; 수정 후 재시도 성공 → 한 번 확정·복귀 |
+| [Rich Text Web](../packages/json-document-rich-text-web/src/contenteditable.ts)은 Undo 키 조건을 직접 판단하고, 구조 입력은 [Web keyboard](../packages/json-document-web/src/keyboard.ts)를 소비 | 공통 Undo/Redo 해석은 Web resolver를 소비하도록 연결. Text 삭제·IME·root 소유권은 Rich Text Web에 유지. 기존 modifier 수용 범위의 차이는 명시적 입력 정책으로 보존 | 기본 Cmd/Ctrl+Z와 Redo가 같은 의도로 해석됨; 추가 modifier·조합 중 입력은 선언한 정책으로 판정 |
+| Document·Order·Tree·Sheet의 `selection.set`은 단일 point 전이; 전체 선택을 단일 전이로 받는 공개 경로는 없음 | 기존 domain Intent에 전체 선택 작업을 추가하고 Selection family로 한 번에 적용. 전체 집합은 Document·Order의 순서, Tree의 visible topology, Sheet의 행·열로 결정. Host의 첫·끝 연속 dispatch는 중간 관찰을 노출하므로 채택하지 않음 | 0·1·여러 대상에서 전체 선택 한 작업, 중간 부분 선택 publication 없음, 반복 결과·History 유지 |
+
+`onCommit` 반환값을 단순히 `void | boolean`으로 바꾸는 안도 기존 callback의
+호환성을 확인해야 한다. 현재 테스트의 `commits.push(...)`처럼 값을 반환하면서
+`void` callback으로 쓰던 호출이 있다. 성공 확인 경로는 기존 호출과 분리해 추가하고,
+정확한 public signature는 그 owner의 호환성 검증과 함께 확정한다.
+
+Affordance의 후속 API 초안은 다음 두 호출을 지원하는 것이다. 아직 존재하지 않는
+옵션을 보여주는 설계 예이며 현재 Usage가 아니다.
+
+```ts
+selectAllAffordance(stroke, state, { repeat: "preserve" });
+createRenameSession<string>({
+  tryCommit: (itemId, label) => editor.dispatch({ type: "item.rename", itemId, label }).ok,
+  onFinish: restoreItemFocus,
+});
+```
 
-먼저 아래의 기본 Undo 사례를 공개 API 조합에 연결하고, 같은 기대 결과를 입력
-binding까지 확장한다. 중첩·여러 view·외부 표현의 차이는 해당 계약에서 별도로
-구체화한다. 구현을 바꿀 때 필요한 owner reference·Usage·source 등록은 각 owning
-package의 기존 위치에서 함께 갱신한다.
+`repeat` 생략은 기존 토글을 유지하고 기본 Hands의 조합이 `preserve`를 선택한다.
+rename은 기존 `onCommit`과 새 동기 `tryCommit` 중 하나를 받으며 둘을 함께
+허용하지 않는 안이다. `false`는 draft 유지, `true`는 종료를 뜻하고 Affordance가
+EditingResult나 domain 검증 규칙을 직접 소유하지 않는다. 비동기 확정은 이 안의
+범위가 아니다. domain의 전체 선택 작업도 기존 point 선택 호출을 보존하는 추가
+계약으로 다루며 새 공통 selection state 객체나 registry를 요구하지 않는다.
+
+Host 연결도 구별한다. [Order Demo](../site/src/routes/order-demo/OrderDemoRoute.tsx)는
+정본 rename session을 `item.rename`에 연결하므로 거절 후 draft 처리를 Host에
+다시 구현하지 않는다. [Canvas Demo](../site/src/routes/canvas-demo/CanvasDemoRoute.tsx)의
+전체 선택은 `selectAllAffordance` 결과를 Object의 한 `selection.set`에 연결한다.
+기본 정책의 소유자는 Affordance·Profile이며 Canvas의 조건문으로 바꾸지 않는다.
+
+후속 구현 순서는 기존 Undo 증거의 정착, 기본 전체 선택의 정본 입력·domain 연결,
+명시적 draft 확정 결과의 연결이다. Native Cut·IME·여러 view의 History는 아래
+검증 질문으로 입력·외부 효과를 확인한 뒤 해당 owner에서 설계한다. 구현을 바꿀 때
+owner reference·Usage·source 등록도 각 package의 기존 위치에서 함께 갱신한다.
+이 문서 변경은 표의 runtime 수정이나 public signature를 적용하지 않는다.
 
 ## 적합성 설계
 
@@ -581,20 +636,21 @@ profile 동결로 확대하지 않는다.
 
 ## 새 도출의 검증 질문
 
-다음은 실행할 수 있도록 시작 상태와 판정 결과를 적은 **후보 사례**다. 앞의
-기존 적합성 표의 통과 항목과 합산하지 않는다. 이 문서 변경은 새 behavior vector나
-구현을 추가하지 않는다.
+다음은 시작 상태와 판정 결과를 적은 **조합 검증 사례**다. 일부 model 경로는
+임시 공개 API 실행으로 확인했으며, 영구 conformance vector·native 입력 검증과
+구별한다. 앞의 기존 적합성 표의 통과 항목과 합산하지 않는다. 이 문서 변경은 새
+behavior vector나 runtime 구현을 추가하지 않는다.
 
 | 사례 | 시작 상태 → 작업 → 판정할 결과 | 연결·현재 증거의 한계 |
 | --- | --- | --- |
 | 셀과 내부 문자열 | `Alpha` 셀 선택 / 내부 `ph` 선택 각각에서 Copy → 셀 payload / `ph` | EG-TARGET·EG-COPY. 기존 Sheet·native selection 증거는 각각 있으며 이 중첩 전체의 공통 binding은 없음 |
-| 기본 Undo와 선택 복원 | 아래의 `Alpha` 범위 교체 → Undo → Redo; 정방향·역방향 각각 실행 | EG-HISTORY·EG-RESULT. 전후 model selection 증거와 실제 native range 복원 증거를 구별 |
-| 선택만 변경한 뒤 Redo | 편집 → Undo → 선택만 이동 → Redo → 기록된 편집 후 내용·선택 | EG-SELECT·EG-HISTORY. 기본 Profile에서 선택 이동이 새 문서 History entry를 만들거나 Redo를 지우지 않음 |
+| 기본 Undo와 선택 복원 | 아래의 `Alpha` 범위 교체 → Undo → Redo; 정방향·역방향 각각 실행 | EG-HISTORY·EG-RESULT. 임시 공개 API 실행에서 model 복원 확인; native range와 영구 vector는 별도 |
+| 선택만 변경한 뒤 Redo | 편집 → Undo → 선택만 이동 → Redo → 기록된 편집 후 내용·선택 | EG-SELECT·EG-HISTORY. 임시 실행에서 새 문서 History entry 없이 Redo·편집 후 선택 보존 확인 |
 | 거절 시 바깥으로 전이 금지 | 선택한 객체 안의 text editor가 Delete 거절 → 객체 제거·외부 History entry가 생기지 않음 | EG-EDIT·입력 계약 후보. [Web clipboard ownership](../packages/json-document-web/tests/clipboard-rejection.test.ts)은 한 binding의 거절 처리 증거이며 일반적인 중첩 거절 vector는 없음 |
 | Toolbar 대상 보존 | editor A에서 범위 선택 → Toolbar에 focus → Copy 실행 → A의 선택 payload | 입력 focus와 Selection 구별. 전체 Hands에 대한 공통 실행 증거 없음 |
 | 셀 값과 행 구조 | 값이 있는 셀을 비움 / 해당 record 삭제 → 전자는 구조 유지, 후자는 record 제거 | EG-EDIT·profile 대상. 현재 Sheet Cut과 Database `record.delete`는 서로 다른 계약 |
 | 반복 일정 영향 범위 | 같은 occurrence에 `this` / `all` 이동 → profile이 정한 반복 일정 집합만 영향 | EG-TARGET·EG-EDIT. Calendar domain 사례이며 입력 맥락 전환으로 해석하지 않음 |
-| Draft 취소와 Undo | 미확정 rename draft 수정 → cancel → 확정 label 불변; 확정 rename → Undo → 이전 label | EG-GESTURE·EG-HISTORY. 구조 gesture runner가 모든 rename·IME 취소를 증명하지 않음 |
+| Draft 취소·거절과 Undo | draft 수정 → cancel 또는 검증 거절 → 확정 label 불변; 성공한 rename → Undo → 이전 label | EG-GESTURE·EG-HISTORY. 현재 rename 거절에서 문서 보존은 확인했으나 draft 종료도 관찰. 제안한 거절 후 유지 계약의 공백 |
 | 외부 참조·다른 profile로 Paste | 수식 또는 reference를 다른 위치·profile에 Paste → 변환·보존·거절 중 선언한 결과 | EG-PASTE. 현재 세 editor의 내부 round trip만으로 cross-profile 교환을 인증할 수 없음 |
 | 공유 문서의 두 편집 맥락 | A에서 편집 → B로 입력 focus 전환 → Undo → 선택한 History owner가 명시한 기여·선택 복원 | EG-HISTORY·EG-RESULT. 외부 History 연결 증거와 모든 Hand의 입력 routing 증거는 다름 |
 | Cut 쓰기 실패 후 native 처리 | editable selection에서 지원하는 Cut의 표현 쓰기 실패 → 해당 작업의 원본 제거 없음 | EG-CUT·Web. 제거 callback 미호출 외에 event 취소·후속 beforeinput/input·document·History를 관찰. 브라우저 재현 전 검증 공백 |
@@ -612,8 +668,15 @@ profile 동결로 확대하지 않는다.
 
 선택만 바꾼 뒤 Redo하는 후보는 Undo 행과 Redo 행 사이에서 caret을 옮겨 실행한다.
 이 선택 이동은 별도 step이 아니며, Redo는 기록된 교체 후 선택을 복원해야 한다.
-이 표는 공개 동작에 대한 기대 결과다. 새 테스트의 통과를 주장하지 않으며,
-Document의 offset 하나만으로 과거 native range 전체를 복원할 수 있다고 가정하지 않는다.
+
+이 사례는 기존 공개 entrypoint의 빌드 결과로 실행했다. 정방향·역방향 2가지,
+Undo 후 caret 이동 여부 2가지, 직접 호출·기본 keymap의 metaKey·ctrlKey 해석
+3가지를 조합한 12개 실행에서 내용·선택·Undo/Redo 상태가 기대와 일치했다.
+키 경로는 `createWebKeyboardAdapter().resolve`의 결과를 editor의 `undo`·`redo`에
+전달했다. 실제 DOM event 수신이나 native range 복원을 검증한 것은 아니다.
+재현 코드와 실행 조건은 [이슈의 학습 기록](https://github.com/developer-1px/json-document/issues/725#issuecomment-5577252880)에 보관하고, 영구 suite의 새 테스트로
+집계하지 않는다. Document의 offset 하나로 과거 native range 전체를 복원할 수
+있다고 가정하지 않는다.
 
 기본 Profile의 역할과 Undo·선택 복원의 기본 의미는 설계에 채택한다. 입력 수신,
 중첩의 진입·거절·복귀, profile 간 payload 변환과 여러 view의 History 귀속은

From 62decf587e4d0e4a648fb5d3d512f0090821ad09 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E1=84=8B=E1=85=B2=E1=84=8B=E1=85=AD=E1=86=BC=E1=84=90?=
 =?UTF-8?q?=E1=85=A2?= <teo.v@navercorp.com>
Date: Tue, 8 Sep 2026 16:40:11 +0900
Subject: [PATCH 05/20] fix(keyboard): consume canonical default chord
 interpretation

---
 docs/api-reference/affordance.md              |  4 +-
 docs/api-reference/composer.md                |  1 +
 package-lock.json                             |  4 +-
 packages/json-document-affordance/README.md   | 11 +++-
 .../json-document-affordance/src/select.ts    | 28 ++++++---
 .../tests/affordance.test.ts                  | 38 ++++++++++++-
 .../json-document-composer-react/README.md    |  5 ++
 .../src/use-composer.tsx                      |  4 +-
 .../tests/composer-react.test.tsx             | 20 ++++++-
 packages/json-document-composer/README.md     | 12 ++++
 packages/json-document-composer/package.json  |  2 +
 .../json-document-composer/src/interaction.ts | 15 ++++-
 .../tests/composer.test.ts                    | 13 +++++
 packages/json-document-composer/tsconfig.json |  1 +
 packages/json-document-web/README.md          | 10 ++++
 .../tests/web-adapters.test.ts                | 18 ++++++
 .../src/shared/demo-workbench/demo-sources.ts | 10 ++++
 site/tests/unit/composer-demo.test.tsx        |  3 +
 site/tests/unit/default-keyboard.test.tsx     | 57 +++++++++++++++++++
 site/tests/unit/demo-workbench.test.tsx       |  1 +
 20 files changed, 240 insertions(+), 17 deletions(-)
 create mode 100644 site/tests/unit/default-keyboard.test.tsx

diff --git a/docs/api-reference/affordance.md b/docs/api-reference/affordance.md
index 370e11f0..a032e743 100644
--- a/docs/api-reference/affordance.md
+++ b/docs/api-reference/affordance.md
@@ -381,7 +381,7 @@ createViewportPositionSession<Key>(options: ViewportPositionOptions<Key>): Viewp
 ## `deleteAffordance`
 
 ```ts
-deleteAffordance(input: { readonly key?: string; }): AffordancePreview
+deleteAffordance(input: Partial<WebKeyboardStroke>): AffordancePreview
 ```
 ## `disclosureAffordance`
 
@@ -781,7 +781,7 @@ resolveAffordanceKey(stroke: WebKeyboardStroke): AffordancePreview
 ## `selectAllAffordance`
 
 ```ts
-selectAllAffordance(stroke: Pick<WebKeyboardStroke, "key" | "metaKey" | "ctrlKey">, state: { readonly allSelected: boolean; }, options?: { readonly repeat?: "preserve" | "toggle"; }): AffordancePreview
+selectAllAffordance(stroke: Pick<WebKeyboardStroke, "key" | "metaKey" | "ctrlKey"> & Partial<Pick<WebKeyboardStroke, "shiftKey" | "altKey">>, state: { readonly allSelected: boolean; }, options?: { readonly repeat?: "preserve" | "toggle"; }): AffordancePreview
 ```
 ## `SelectOperation`
 
diff --git a/docs/api-reference/composer.md b/docs/api-reference/composer.md
index f182ef1a..da3ad8f4 100644
--- a/docs/api-reference/composer.md
+++ b/docs/api-reference/composer.md
@@ -144,6 +144,7 @@ interface ComposerKeyStroke {
   readonly key: string;
   readonly shiftKey?: boolean;
   readonly commandKey?: boolean;
+  readonly altKey?: boolean;
 }
 ```
 ## `ComposerReference`
diff --git a/package-lock.json b/package-lock.json
index 0f02d817..3e02b7fb 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -6562,6 +6562,7 @@
         "@interactive-os/json-document-rich-text": "*",
         "@interactive-os/json-document-rich-text-mention": "*",
         "@interactive-os/json-document-rich-text-suggestion": "*",
+        "@interactive-os/json-document-web": "*",
         "@types/node": "^25.9.0",
         "typescript": "^5.0.0",
         "vitest": "^4.1.7"
@@ -6571,7 +6572,8 @@
         "@interactive-os/json-document-file-intake": "^0.1.0-rc.0",
         "@interactive-os/json-document-rich-text": "^0.1.0-rc.0",
         "@interactive-os/json-document-rich-text-mention": "^0.1.0-rc.0",
-        "@interactive-os/json-document-rich-text-suggestion": "^0.1.0-rc.0"
+        "@interactive-os/json-document-rich-text-suggestion": "^0.1.0-rc.0",
+        "@interactive-os/json-document-web": "^0.1.0-rc.0"
       }
     },
     "packages/json-document-composer-react": {
diff --git a/packages/json-document-affordance/README.md b/packages/json-document-affordance/README.md
index 607d3159..2a569e82 100644
--- a/packages/json-document-affordance/README.md
+++ b/packages/json-document-affordance/README.md
@@ -94,8 +94,8 @@ open/focus semantics remain outside this geometry contract.
 Usage: [Affordance](https://developer-1px.github.io/json-document/docs/affordance)
 
 `selectAllAffordance(stroke, state, { repeat: "preserve" })` emits `select-all`
-for Mod+A even when everything is selected. The default editing Usage chooses
-this policy. Omission or `{ repeat: "toggle" }` retains the existing behavior:
+for Mod+A without Alt or Shift, even when everything is selected. The default
+editing Usage chooses this policy. Omission or `{ repeat: "toggle" }` retains the existing behavior:
 emit `clear` when `state.allSelected`, otherwise `select-all`. This is an input
 policy; domain editors own the selected universe and its semantic transition.
 
@@ -105,3 +105,10 @@ Document's `selection.move`. Structural preview and cancellation leave committed
 value/history unchanged; commit dispatches the latest preview once. This proves
 the tested composition, not every Host callback. IME composition has a separate
 [DOM editing lifecycle](../../standards/dom-editing-lifecycle.md) contract.
+
+`deleteAffordance(stroke)` consumes the Web default structural keymap: bare
+Delete/Backspace delete; modified variants return no hand. Omitted modifiers
+remain false for existing partial-input calls. Pass the full event to preserve
+modifier facts. `selectAllAffordance` uses Web `chordFromStroke` for the same
+normalization, then applies its own select-all repetition policy. Text word or
+line deletion belongs to the text input adapter.
diff --git a/packages/json-document-affordance/src/select.ts b/packages/json-document-affordance/src/select.ts
index 879a7e39..89f81725 100644
--- a/packages/json-document-affordance/src/select.ts
+++ b/packages/json-document-affordance/src/select.ts
@@ -1,4 +1,5 @@
 import {
+  chordFromStroke,
   createWebKeyboardAdapter,
   selectionOperationFromModifiers,
   type WebKeyboardCommand,
@@ -88,9 +89,16 @@ export function planeHitAffordance(input: {
   };
 }
 
-export function deleteAffordance(input: { readonly key?: string }): AffordancePreview {
-  if (input.key === "Delete" || input.key === "Backspace") return { hand: { type: "delete" } };
-  return { hand: null };
+/** Uses the default structural delete chord; omitted modifiers are false. */
+export function deleteAffordance(input: Partial<WebKeyboardStroke>): AffordancePreview {
+  const command = keyboard.resolve({
+    key: input.key ?? "",
+    shiftKey: input.shiftKey ?? false,
+    metaKey: input.metaKey ?? false,
+    ctrlKey: input.ctrlKey ?? false,
+    altKey: input.altKey ?? false,
+  });
+  return { hand: command?.type === "delete" ? command : null };
 }
 
 export function contextMenuAffordance(input: {
@@ -111,14 +119,20 @@ export function resolveAffordanceKey(stroke: WebKeyboardStroke): AffordancePrevi
   return { hand: keyboard.resolve(stroke) };
 }
 
-/** Mod+A selects all. Choose preserve for repeated selection; omission retains the legacy toggle. */
+/** Mod+A without Alt/Shift selects all. Choose preserve for repetition; omission retains the legacy toggle. */
 export function selectAllAffordance(
-  stroke: Pick<WebKeyboardStroke, "key" | "metaKey" | "ctrlKey">,
+  stroke: Pick<WebKeyboardStroke, "key" | "metaKey" | "ctrlKey"> & Partial<Pick<WebKeyboardStroke, "shiftKey" | "altKey">>,
   state: { readonly allSelected: boolean },
   options: { readonly repeat?: "preserve" | "toggle" } = {},
 ): AffordancePreview {
-  const mod = stroke.metaKey || stroke.ctrlKey;
-  if (!mod || stroke.key.toLowerCase() !== "a") return { hand: null };
+  const chord = chordFromStroke({
+    key: stroke.key,
+    shiftKey: stroke.shiftKey ?? false,
+    metaKey: stroke.metaKey,
+    ctrlKey: stroke.ctrlKey,
+    altKey: stroke.altKey ?? false,
+  });
+  if (chord !== "Mod-a") return { hand: null };
   return { hand: { type: state.allSelected && options.repeat !== "preserve" ? "clear" : "select-all" } };
 }
 
diff --git a/packages/json-document-affordance/tests/affordance.test.ts b/packages/json-document-affordance/tests/affordance.test.ts
index c87a454f..c626f126 100644
--- a/packages/json-document-affordance/tests/affordance.test.ts
+++ b/packages/json-document-affordance/tests/affordance.test.ts
@@ -29,6 +29,7 @@ import {
   panAffordance,
   resizeAffordance,
   resolveAffordanceKey,
+  selectAllAffordance,
   snapAffordance,
   treeAffordance,
   createBoardDragSession,
@@ -41,7 +42,7 @@ import {
   wheelAffordance,
   zoomAffordance,
 } from "../src/index.js";
-import { pressInteractionFromWeb } from "@interactive-os/json-document-web";
+import { createWebKeyboardAdapter, pressInteractionFromWeb } from "@interactive-os/json-document-web";
 
 describe("Affordance sessions", () => {
   test("owns drag, resize, and control handle descriptor, cursor, delta, and lifecycle semantics", () => {
@@ -780,3 +781,38 @@ describe("snapAffordance disable key", () => {
       .toEqual({ type: "translate", dx: 47, dy: 51 });
   });
 });
+
+
+describe("default keyboard modifier contract", () => {
+  const keyboard = createWebKeyboardAdapter();
+  for (let mask = 0; mask < 16; mask++) {
+    const modifiers = { metaKey: !!(mask & 1), ctrlKey: !!(mask & 2), shiftKey: !!(mask & 4), altKey: !!(mask & 8) };
+    test(`preserves all modifier facts (${mask})`, () => {
+      for (const key of ["Delete", "Backspace"]) {
+        const stroke = { key, ...modifiers };
+        expect(deleteAffordance(stroke).hand).toEqual(mask === 0 ? { type: "delete" } : null);
+        expect(deleteAffordance(stroke).hand).toEqual(keyboard.resolve(stroke));
+      }
+      for (const key of ["z", "Z"]) {
+        const stroke = { key, ...modifiers };
+        expect(resolveAffordanceKey(stroke).hand).toEqual(keyboard.resolve(stroke));
+        expect(editingCommandFromWebKeyboardStroke(stroke)).toEqual(keyboard.resolve(stroke));
+      }
+      for (const key of ["a", "A"]) {
+        const stroke = { key, ...modifiers };
+        const selected = (modifiers.metaKey || modifiers.ctrlKey) && !modifiers.shiftKey && !modifiers.altKey;
+        expect(selectAllAffordance(stroke, { allSelected: true }, { repeat: "preserve" }).hand)
+          .toEqual(selected ? { type: "select-all" } : null);
+        expect(selectAllAffordance(stroke, { allSelected: true }).hand)
+          .toEqual(selected ? { type: "clear" } : null);
+      }
+    });
+  }
+
+  test("keeps legacy partial inputs without inventing modifiers", () => {
+    expect(deleteAffordance({ key: "Backspace" }).hand).toEqual({ type: "delete" });
+    expect(deleteAffordance({}).hand).toBeNull();
+    expect(selectAllAffordance({ key: "a", metaKey: true, ctrlKey: false }, { allSelected: false }).hand)
+      .toEqual({ type: "select-all" });
+  });
+});
diff --git a/packages/json-document-composer-react/README.md b/packages/json-document-composer-react/README.md
index cbb26934..bd4fda15 100644
--- a/packages/json-document-composer-react/README.md
+++ b/packages/json-document-composer-react/README.md
@@ -20,3 +20,8 @@ composed from the canonical suggestion packages.
 Product copy, styling, layout, suggestions, and concrete ports remain Host-owned.
 Draft/editor subscription, suggestion integration, keyboard/history execution, Web file
 intake, focus recovery, and submit lifecycle remain canonical across Host replacements.
+
+`useComposer` preserves Alt when translating key events to Composer interaction
+meaning. Its history capture handler consumes only the default Undo/Redo chord;
+Alt-modified variants leave the event and canonical history untouched. Submit
+and command-menu handling retain the configured Composer policy.
diff --git a/packages/json-document-composer-react/src/use-composer.tsx b/packages/json-document-composer-react/src/use-composer.tsx
index 733a3fa1..e80662f3 100644
--- a/packages/json-document-composer-react/src/use-composer.tsx
+++ b/packages/json-document-composer-react/src/use-composer.tsx
@@ -108,7 +108,7 @@ export function useComposer<Model extends string, Suggestion extends ComposerHos
   }
 
   function handleKeyDown(event: KeyboardEvent<HTMLElement>) {
-    const interaction = composerInteractionFromKeyStroke({ key: event.key, shiftKey: event.shiftKey, commandKey: event.metaKey || event.ctrlKey }, config.interaction);
+    const interaction = composerInteractionFromKeyStroke({ key: event.key, shiftKey: event.shiftKey, commandKey: event.metaKey || event.ctrlKey, altKey: event.altKey }, config.interaction);
     if (commandMenu.open) {
       commandMenu.handleKeyDown(event);
       if (event.defaultPrevented) {
@@ -123,7 +123,7 @@ export function useComposer<Model extends string, Suggestion extends ComposerHos
   }
 
   function handleHistoryKeyDown(event: KeyboardEvent<HTMLElement>) {
-    const interaction = composerInteractionFromKeyStroke({ key: event.key, shiftKey: event.shiftKey, commandKey: event.metaKey || event.ctrlKey }, config.interaction);
+    const interaction = composerInteractionFromKeyStroke({ key: event.key, shiftKey: event.shiftKey, commandKey: event.metaKey || event.ctrlKey, altKey: event.altKey }, config.interaction);
     if (interaction !== "history.undo" && interaction !== "history.redo") return;
     event.preventDefault();
     event.stopPropagation();
diff --git a/packages/json-document-composer-react/tests/composer-react.test.tsx b/packages/json-document-composer-react/tests/composer-react.test.tsx
index cb0c06da..dadfaad1 100644
--- a/packages/json-document-composer-react/tests/composer-react.test.tsx
+++ b/packages/json-document-composer-react/tests/composer-react.test.tsx
@@ -37,6 +37,24 @@ describe("Composer React integration", () => {
     fireEvent.keyDown(screen.getByTestId("mod-keyboard"), { key: "Enter", ctrlKey: true });
     expect(modSubmit).toHaveBeenCalledTimes(1);
   });
+
+  test.each(["metaKey", "ctrlKey"] as const)("preserves Alt through the real %s history event path", (modifier) => {
+    render(<ComposerHostHarness host="history" config={hostConfig("Fast", "enter")} submit={vi.fn()} />);
+    fireEvent.click(screen.getByRole("button", { name: "history-text" }));
+    const target = screen.getByTestId("history-keyboard");
+    const draft = screen.getByTestId("history-draft");
+    const inserted = draft.textContent;
+    expect(inserted).toContain("hello");
+    expect(fireEvent.keyDown(target, { key: "z", [modifier]: true, altKey: true })).toBe(true);
+    expect(draft.textContent).toBe(inserted);
+    expect(fireEvent.keyDown(target, { key: "z", [modifier]: true })).toBe(false);
+    expect(draft.textContent).not.toContain("hello");
+    const undone = draft.textContent;
+    expect(fireEvent.keyDown(target, { key: "Z", [modifier]: true, shiftKey: true, altKey: true })).toBe(true);
+    expect(draft.textContent).toBe(undone);
+    expect(fireEvent.keyDown(target, { key: "Z", [modifier]: true, shiftKey: true })).toBe(false);
+    expect(draft.textContent).toBe(inserted);
+  });
 });
 
 function hostConfig<Model extends string>(model: Model, submit: "enter" | "mod-enter"): ComposerHostConfig<Model> {
@@ -57,7 +75,7 @@ function ComposerHostHarness<Model extends string>(props: { readonly host: strin
     ports: { createId: () => `${props.host}-${++id}`, submit: props.submit },
     labels: { mentionSuggestions: `${props.host} mentions`, skillSuggestions: `${props.host} skills` },
   });
-  return <div data-testid={`${props.host}-keyboard`} onKeyDown={composer.handleKeyDown}>
+  return <div data-testid={`${props.host}-keyboard`} onKeyDown={composer.handleKeyDown} onKeyDownCapture={composer.handleHistoryKeyDown}>
     <button aria-label={`${props.host}-text`} onClick={() => composer.insertText("hello")}>text</button>
     <output data-testid={`${props.host}-draft`}>{JSON.stringify(composer.document.value)}</output>
   </div>;
diff --git a/packages/json-document-composer/README.md b/packages/json-document-composer/README.md
index 32b8262f..71ae0e79 100644
--- a/packages/json-document-composer/README.md
+++ b/packages/json-document-composer/README.md
@@ -9,3 +9,15 @@ those validated candidates into Composer context attachments.
 `resolveComposerSuggestions(trigger, suggestions)` owns trigger-aware matching of a
 product-configured suggestion catalog. React menu lifecycle and atom projection live in
 `@interactive-os/json-document-composer-react`.
+
+`composerInteractionFromKeyStroke(stroke, policy)` preserves the existing
+`commandKey` input (Meta or Control) and accepts optional `altKey` alongside
+`shiftKey`. Omitted modifiers are false. Its keyboard compatibility boundary
+uses `@interactive-os/json-document-web`'s pure default resolver for Undo/Redo:
+Mod+Z undoes, Mod+Shift+Z redoes, and Alt-modified variants return `null`.
+Composer still owns Escape and the configured Enter submit/newline meaning.
+The keyboard dependency is confined to `interaction.ts`; draft model, schema,
+and commands do not interpret Web events. No DOM environment is required.
+
+Usage: [Composer](https://developer-1px.github.io/json-document/demo/composer).
+The React integration passes all modifier facts to this boundary.
diff --git a/packages/json-document-composer/package.json b/packages/json-document-composer/package.json
index b0d1612e..49ec3d43 100644
--- a/packages/json-document-composer/package.json
+++ b/packages/json-document-composer/package.json
@@ -21,6 +21,7 @@
     "verify": "npm run typecheck && npm test && npm run build"
   },
   "peerDependencies": {
+    "@interactive-os/json-document-web": "^0.1.0-rc.0",
     "@interactive-os/json-document": "^3.0.0",
     "@interactive-os/json-document-file-intake": "^0.1.0-rc.0",
     "@interactive-os/json-document-rich-text-mention": "^0.1.0-rc.0",
@@ -28,6 +29,7 @@
     "@interactive-os/json-document-rich-text": "^0.1.0-rc.0"
   },
   "devDependencies": {
+    "@interactive-os/json-document-web": "*",
     "@interactive-os/json-document": "*",
     "@interactive-os/json-document-file-intake": "*",
     "@interactive-os/json-document-rich-text-mention": "*",
diff --git a/packages/json-document-composer/src/interaction.ts b/packages/json-document-composer/src/interaction.ts
index d37f422e..d1eed3e4 100644
--- a/packages/json-document-composer/src/interaction.ts
+++ b/packages/json-document-composer/src/interaction.ts
@@ -1,19 +1,32 @@
+import { createWebKeyboardAdapter } from "@interactive-os/json-document-web";
 import type { ComposerInteractionPolicy } from "./host-config.js";
 
+const keyboard = createWebKeyboardAdapter();
+
 export interface ComposerKeyStroke {
   readonly key: string;
   readonly shiftKey?: boolean;
   readonly commandKey?: boolean;
+  readonly altKey?: boolean;
 }
 
 export type ComposerInteraction = "dismiss" | "history.redo" | "history.undo" | "newline" | "submit";
 
+/** Uses the Web default history keymap, then applies Composer submit/newline policy. */
 export function composerInteractionFromKeyStroke(
   stroke: ComposerKeyStroke,
   policy: ComposerInteractionPolicy,
 ): ComposerInteraction | null {
   if (stroke.key === "Escape") return "dismiss";
-  if (stroke.commandKey && stroke.key.toLowerCase() === "z") return stroke.shiftKey ? "history.redo" : "history.undo";
+  const command = keyboard.resolve({
+    key: stroke.key,
+    shiftKey: stroke.shiftKey ?? false,
+    metaKey: stroke.commandKey ?? false,
+    ctrlKey: false,
+    altKey: stroke.altKey ?? false,
+  });
+  if (command?.type === "undo") return "history.undo";
+  if (command?.type === "redo") return "history.redo";
   if (stroke.key !== "Enter") return null;
   const submits = policy.submit === "mod-enter" ? stroke.commandKey === true : stroke.commandKey !== true && stroke.shiftKey !== true;
   if (submits) return "submit";
diff --git a/packages/json-document-composer/tests/composer.test.ts b/packages/json-document-composer/tests/composer.test.ts
index 7594cb17..423beb2e 100644
--- a/packages/json-document-composer/tests/composer.test.ts
+++ b/packages/json-document-composer/tests/composer.test.ts
@@ -120,3 +120,16 @@ describe("Composer domain", () => {
     expect(composerInteractionFromKeyStroke({ key: "Escape" }, policy)).toBe("dismiss");
   });
 });
+
+
+describe("Composer default history keyboard", () => {
+  for (const commandKey of [false, true]) for (const shiftKey of [false, true]) for (const altKey of [false, true]) {
+    test(`history command=${commandKey} shift=${shiftKey} alt=${altKey}`, () => {
+      for (const key of ["z", "Z"]) {
+        const stroke = { key, commandKey, shiftKey, altKey };
+        expect(composerInteractionFromKeyStroke(stroke, { submit: "enter", newline: "shift-enter" }))
+          .toBe(commandKey && !altKey ? shiftKey ? "history.redo" : "history.undo" : null);
+      }
+    });
+  }
+});
diff --git a/packages/json-document-composer/tsconfig.json b/packages/json-document-composer/tsconfig.json
index 04c4097d..074937d3 100644
--- a/packages/json-document-composer/tsconfig.json
+++ b/packages/json-document-composer/tsconfig.json
@@ -3,6 +3,7 @@
   "compilerOptions": { "rootDir": "src", "outDir": "dist", "tsBuildInfoFile": "dist/.tsbuildinfo" },
   "references": [
     { "path": "../json-document" },
+    { "path": "../json-document-web" },
     { "path": "../json-document-file-intake" },
     { "path": "../json-document-rich-text-mention" },
     { "path": "../json-document-rich-text-suggestion" },
diff --git a/packages/json-document-web/README.md b/packages/json-document-web/README.md
index ac5dfe8d..1c724bc6 100644
--- a/packages/json-document-web/README.md
+++ b/packages/json-document-web/README.md
@@ -239,3 +239,13 @@ const range = textSelectionFromControl({ currentTarget: textarea });
 [Document Usage](https://developer-1px.github.io/json-document/demo); its source
 view links the React binding to this package's `input.ts` implementation and
 [API reference](https://developer-1px.github.io/json-document/docs/api/web).
+
+Default keyboard interpretation has one owner here. `chordFromStroke` folds
+Meta/Control into `Mod`, preserves Alt/Shift, normalizes single-character case,
+and maps the space key to `Space`. Unlisted chords resolve to `null`; for
+example, Mod+Alt+Z and Mod+Backspace have no default structural command.
+`createWebKeyboardAdapter({ keymap, defaults: false })` can explicitly assign
+such chords for a product profile. Affordance consumes the default delete
+mapping; Composer consumes its Undo/Redo mapping. Select-all remains an
+Affordance policy over the canonical chord normalizer, outside
+`WebKeyboardCommand`.
diff --git a/packages/json-document-web/tests/web-adapters.test.ts b/packages/json-document-web/tests/web-adapters.test.ts
index 3b93bd46..4ccf8aa8 100644
--- a/packages/json-document-web/tests/web-adapters.test.ts
+++ b/packages/json-document-web/tests/web-adapters.test.ts
@@ -646,6 +646,24 @@ describe("Web keyboard Adapter", () => {
     expect(adapter.resolve({ key: "c", shiftKey: false, metaKey: true, ctrlKey: false })).toBeNull();
   });
 
+  test("preserves modifiers while allowing explicit product chord assignments", () => {
+    const product = createWebKeyboardAdapter({
+      defaults: false,
+      keymap: { "Mod-Alt-z": { type: "undo" }, "Mod-Backspace": { type: "delete" } },
+    });
+    for (const modifiers of [{ metaKey: true, ctrlKey: false }, { metaKey: false, ctrlKey: true }]) {
+      const undo = { key: "Z", shiftKey: false, altKey: true, ...modifiers };
+      const remove = { key: "Backspace", shiftKey: false, ...modifiers };
+      expect(adapter.resolve(undo)).toBeNull();
+      expect(adapter.resolve(remove)).toBeNull();
+      expect(product.resolve(undo)).toEqual({ type: "undo" });
+      expect(product.resolve(remove)).toEqual({ type: "delete" });
+      expect(product.resolve({ ...undo, altKey: false })).toBeNull();
+      expect(adapter.resolve({ ...undo, altKey: false })).toEqual({ type: "undo" });
+      expect(adapter.resolve({ ...undo, altKey: false, shiftKey: true })).toEqual({ type: "redo" });
+    }
+  });
+
   test("lets the host replace chords without inventing editing commands", () => {
     const custom = createWebKeyboardAdapter({
       keymap: { ...defaultWebKeymap, Enter: { type: "toggle" } },
diff --git a/site/src/shared/demo-workbench/demo-sources.ts b/site/src/shared/demo-workbench/demo-sources.ts
index 754b4cc0..5d45974e 100644
--- a/site/src/shared/demo-workbench/demo-sources.ts
+++ b/site/src/shared/demo-workbench/demo-sources.ts
@@ -501,6 +501,11 @@ const registeredPublicUsages = [
     symbol: "createWebKeyboardAdapter",
     sourcePath: "packages/json-document-web/src/keyboard.ts",
   },
+  {
+    packageName: "@interactive-os/json-document-web",
+    symbol: "chordFromStroke",
+    sourcePath: "packages/json-document-web/src/keyboard.ts",
+  },
   {
     packageName: "@interactive-os/json-document-web",
     symbol: "calendarMinutesFromWebGrid",
@@ -967,6 +972,11 @@ const registeredPublicUsages = [
     symbol: "selectAllAffordance",
     sourcePath: "packages/json-document-affordance/src/select.ts",
   },
+  {
+    packageName: "@interactive-os/json-document-affordance",
+    symbol: "deleteAffordance",
+    sourcePath: "packages/json-document-affordance/src/select.ts",
+  },
   {
     packageName: "@interactive-os/json-document-editing",
     symbol: "createDocumentEditor",
diff --git a/site/tests/unit/composer-demo.test.tsx b/site/tests/unit/composer-demo.test.tsx
index e3838843..b08708bb 100644
--- a/site/tests/unit/composer-demo.test.tsx
+++ b/site/tests/unit/composer-demo.test.tsx
@@ -71,6 +71,9 @@ describe("Agent Chat Composer Hands", () => {
     expect(screen.getByTestId("composer-draft-json").textContent).toContain("요구사항.md");
     expect(screen.getByRole("button", { name: "전송 (Enter)" }).hasAttribute("disabled")).toBe(false);
 
+    const draftBefore = screen.getByTestId("composer-draft-json").textContent;
+    expect(fireEvent.keyDown(screen.getByTestId("agent-chat-composer"), { key: "z", metaKey: true, altKey: true })).toBe(true);
+    expect(screen.getByTestId("composer-draft-json").textContent).toBe(draftBefore);
     fireEvent.keyDown(screen.getByTestId("agent-chat-composer"), { key: "z", metaKey: true });
     expect(screen.queryByText("요구사항.md")).toBeNull();
     fireEvent.keyDown(screen.getByTestId("agent-chat-composer"), { key: "z", metaKey: true, shiftKey: true });
diff --git a/site/tests/unit/default-keyboard.test.tsx b/site/tests/unit/default-keyboard.test.tsx
new file mode 100644
index 00000000..c3b0bdb9
--- /dev/null
+++ b/site/tests/unit/default-keyboard.test.tsx
@@ -0,0 +1,57 @@
+import { cleanup, fireEvent, render, screen } from "@testing-library/react";
+import { afterEach, expect, test } from "vitest";
+import { deleteAffordance, selectAllAffordance } from "@interactive-os/json-document-affordance";
+import { CanvasDemoRoute } from "../../src/routes/canvas-demo/CanvasDemoRoute";
+import { DocumentDemoRoute } from "../../src/routes/document-demo/DocumentDemoRoute";
+
+afterEach(cleanup);
+
+test.each(["metaKey", "ctrlKey"] as const)("Canvas preserves %s modifier facts for selection and deletion", (modifier) => {
+  render(<CanvasDemoRoute />);
+  const canvas = screen.getByLabelText("Canvas");
+  const objects = () => canvas.querySelectorAll("[data-object-id][data-locked]");
+  const selected = () => canvas.querySelectorAll('[data-object-id][data-locked][data-selected="true"]');
+  const count = objects().length;
+  expect(count).toBeGreaterThan(1);
+  const initialSelection = selected().length;
+  for (const extra of [{ altKey: true }, { shiftKey: true }, { altKey: true, shiftKey: true }]) {
+    expect(fireEvent.keyDown(canvas, { key: "a", [modifier]: true, ...extra })).toBe(true);
+    expect(selected().length).toBe(initialSelection);
+  }
+  expect(fireEvent.keyDown(canvas, { key: "a", [modifier]: true })).toBe(false);
+  const selectionCount = selected().length;
+  expect(selectionCount).toBeGreaterThan(0);
+  fireEvent.keyDown(canvas, { key: "a", [modifier]: true });
+  expect(selected().length).toBe(selectionCount);
+  expect(fireEvent.keyDown(canvas, { key: "Backspace", [modifier]: true })).toBe(true);
+  expect(objects().length).toBe(count);
+  expect(selected().length).toBe(selectionCount);
+  expect(fireEvent.keyDown(canvas, { key: "Backspace" })).toBe(false);
+  expect(objects().length).toBe(count - selectionCount);
+});
+
+test("Document select-all preserves its scope, repetition, and native input ownership", () => {
+  render(<DocumentDemoRoute />);
+  const document = screen.getByLabelText("Editable document");
+  const surface = document.querySelector<HTMLElement>('[tabindex="0"]')!;
+  const selected = () => document.querySelectorAll('article[data-block-id][data-selected="true"]');
+  const initial = selected().length;
+  expect(fireEvent.keyDown(surface, { key: "a", ctrlKey: true, altKey: true })).toBe(true);
+  expect(selected().length).toBe(initial);
+  const input = document.querySelector("input, textarea")!;
+  expect(input).not.toBeNull();
+  expect(fireEvent.keyDown(input, { key: "a", ctrlKey: true })).toBe(true);
+  expect(selected().length).toBe(initial);
+  expect(fireEvent.keyDown(surface, { key: "a", ctrlKey: true })).toBe(false);
+  const count = document.querySelectorAll("article[data-block-id]").length;
+  expect(selected().length).toBe(count);
+  fireEvent.keyDown(surface, { key: "a", ctrlKey: true });
+  expect(selected().length).toBe(count);
+});
+
+test("native KeyboardEvent properties reach the public Affordance APIs", () => {
+  expect(deleteAffordance(new KeyboardEvent("keydown", { key: "Backspace", ctrlKey: true })).hand).toBeNull();
+  expect(deleteAffordance(new KeyboardEvent("keydown", { key: "Backspace" })).hand).toEqual({ type: "delete" });
+  expect(selectAllAffordance(new KeyboardEvent("keydown", { key: "a", metaKey: true, altKey: true }), { allSelected: false }).hand).toBeNull();
+  expect(selectAllAffordance(new KeyboardEvent("keydown", { key: "a", metaKey: true }), { allSelected: false }).hand).toEqual({ type: "select-all" });
+});
diff --git a/site/tests/unit/demo-workbench.test.tsx b/site/tests/unit/demo-workbench.test.tsx
index 17d30ff5..d4c6b14c 100644
--- a/site/tests/unit/demo-workbench.test.tsx
+++ b/site/tests/unit/demo-workbench.test.tsx
@@ -200,6 +200,7 @@ describe("Demo definition and source discovery", () => {
       "packages/json-document-composer/src/commands.ts",
       "packages/json-document-composer/src/host-config.ts",
       "packages/json-document-composer/src/interaction.ts",
+      "packages/json-document-web/src/keyboard.ts",
       "packages/json-document-rich-text-suggestion/src/index.ts",
       "packages/json-document-rich-text-suggestion-react/src/index.ts",
       "packages/json-document-composer-react/src/use-composer.tsx",

From 34f5547cdb9b0c1f92ef14378432b32ff9381cbe Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E1=84=8B=E1=85=B2=E1=84=8B=E1=85=AD=E1=86=BC=E1=84=90?=
 =?UTF-8?q?=E1=85=A2?= <teo.v@navercorp.com>
Date: Wed, 9 Sep 2026 09:27:12 +0900
Subject: [PATCH 06/20] =?UTF-8?q?docs(site):=20=EB=AA=A9=ED=91=9C=20?=
 =?UTF-8?q?=EC=B1=85=EC=9E=84=20=EA=B5=AC=EC=A1=B0=EC=99=80=20=ED=94=84?=
 =?UTF-8?q?=EB=A1=9C=ED=86=A0=EC=BD=9C=C2=B7TBD=EB=A5=BC=20=EC=A0=95?=
 =?UTF-8?q?=EB=A0=AC=ED=95=9C=EB=8B=A4?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 README.md                                     |  27 +-
 docs/README.md                                | 280 ++++------
 docs/api-reference/a2ui.md                    |   4 +-
 docs/api-reference/affordance.md              |   4 +-
 docs/api-reference/ajv.md                     |   4 +-
 docs/api-reference/animation-react.md         |   4 +-
 docs/api-reference/annotation.md              |   4 +-
 docs/api-reference/calendar.md                |   4 +-
 docs/api-reference/collaboration.md           | 179 +++++-
 docs/api-reference/composer-react.md          |   4 +-
 docs/api-reference/composer.md                |   4 +-
 .../contenteditable-collaboration.md          |   4 +-
 docs/api-reference/contenteditable.md         |   4 +-
 docs/api-reference/database.md                |   4 +-
 docs/api-reference/editing.md                 |   4 +-
 docs/api-reference/file-intake.md             |   4 +-
 docs/api-reference/json-document.md           |   4 +-
 docs/api-reference/markdown-react.md          |   4 +-
 docs/api-reference/packages.mjs               |  31 +-
 docs/api-reference/packages.test.mjs          |  31 ++
 docs/api-reference/react-hook-form.md         |   4 +-
 docs/api-reference/react.md                   |   4 +-
 docs/api-reference/rich-text-mention-react.md |   4 +-
 docs/api-reference/rich-text-mention.md       |   4 +-
 docs/api-reference/rich-text-react.md         |   4 +-
 .../rich-text-suggestion-react.md             |   4 +-
 docs/api-reference/rich-text-suggestion.md    |   4 +-
 docs/api-reference/rich-text-web.md           |   4 +-
 docs/api-reference/rich-text.md               |   4 +-
 docs/api-reference/selection.md               |   4 +-
 docs/api-reference/tanstack-table.md          |   4 +-
 docs/api-reference/ui-primitives-react.md     |   4 +-
 docs/api-reference/web.md                     |   4 +-
 docs/api-reference/zod.md                     |   4 +-
 docs/evaluate.mjs                             | 125 ++---
 docs/public/api.md                            |   8 +-
 docs/public/building-blocks.md                |  37 ++
 docs/public/concepts.md                       | 211 +++-----
 docs/public/document-types.md                 |  37 +-
 docs/public/editing.md                        |  76 +++
 docs/public/foundation.md                     |  50 +-
 docs/public/how-we-build.md                   |   7 +-
 docs/public/llms.txt                          |  94 +++-
 docs/public/official-hands.md                 |  50 +-
 docs/public/overview.md                       |  31 +-
 packages/json-document-editing/README.md      |   8 +-
 packages/json-document-selection/README.md    |  15 +-
 packages/json-document-web/README.md          |  35 +-
 packages/json-document/README.md              |  19 +-
 scripts/generate-api-reference.mjs            |  20 +-
 site/scripts/check-documentation-page.mjs     |   4 +-
 site/scripts/route-checks.mjs                 |   6 +-
 site/scripts/route-checks.test.mjs            |  26 +
 site/site-routes.json                         | 350 ++++++++----
 site/src/app/breadcrumb.tsx                   |  14 +-
 site/src/app/navigation-layer-icon.tsx        |   4 +-
 site/src/app/page-descriptors.ts              |   1 +
 site/src/app/routeTree.gen.ts                 | 510 ++++++++++--------
 site/src/app/routes/__root.tsx                |  19 +-
 site/src/app/routes/_page/docs/api.tsx        |   6 -
 site/src/app/routes/_page/docs/api/index.tsx  |   6 +
 .../app/routes/_page/docs/building-blocks.tsx |   6 +
 site/src/app/routes/_page/docs/editing.tsx    |   6 +
 site/src/app/site-layers.ts                   |  17 +-
 .../artifact-viewer/ArtifactViewerRoute.tsx   |  13 +-
 site/src/routes/docs/ConceptsRoute.tsx        |  41 +-
 site/src/routes/docs/DocsRoute.tsx            |   6 +-
 .../docs/DocumentTypeCandidateRoute.tsx       |  14 +-
 site/src/routes/docs/DocumentationPage.tsx    |  19 +-
 site/src/routes/docs/MarkdownViewer.tsx       | 124 +----
 site/src/routes/docs/doc-pages.ts             | 321 ++++-------
 site/src/routes/home/HomeRoute.tsx            |   6 +-
 site/tests/browser/artifact-viewer.spec.ts    |   2 +-
 .../tests/browser/documentation-links.spec.ts |  39 ++
 site/tests/browser/site-shell.spec.ts         |  27 +-
 site/tests/unit/api-routes.test.tsx           |  27 +
 site/tests/unit/app-shell.test.tsx            |  21 +-
 site/tests/unit/breadcrumb.test.ts            |   8 +-
 site/tests/unit/docs-route.test.tsx           |  30 +-
 site/tests/unit/documentation-page.test.tsx   |  84 +++
 standards/json-document-v3/profile.md         |  10 +-
 standards/repository-implementation-shape.md  |   6 +
 standards/repository-naming.md                |  53 +-
 83 files changed, 1901 insertions(+), 1412 deletions(-)
 create mode 100644 docs/api-reference/packages.test.mjs
 create mode 100644 docs/public/building-blocks.md
 create mode 100644 docs/public/editing.md
 create mode 100644 site/scripts/route-checks.test.mjs
 delete mode 100644 site/src/app/routes/_page/docs/api.tsx
 create mode 100644 site/src/app/routes/_page/docs/api/index.tsx
 create mode 100644 site/src/app/routes/_page/docs/building-blocks.tsx
 create mode 100644 site/src/app/routes/_page/docs/editing.tsx
 create mode 100644 site/tests/browser/documentation-links.spec.ts
 create mode 100644 site/tests/unit/api-routes.test.tsx
 create mode 100644 site/tests/unit/documentation-page.test.tsx

diff --git a/README.md b/README.md
index f0a07610..4b1fdba1 100644
--- a/README.md
+++ b/README.md
@@ -28,9 +28,14 @@ stateless JSON Patch
 
 | 목적 | 위치 |
 | --- | --- |
-| 빠른 사용 예제 | [docs/public/quickstart.md](docs/public/quickstart.md) |
+| 빠른 사용 예제 | [Intent guide](docs/public/intent-guide.md) |
+| 목표 구조와 TBD | [Concept Map](docs/public/concepts.md), [Foundation](docs/public/foundation.md) |
 | JSON Document 개념 | [docs/public/overview.md](docs/public/overview.md) |
-| JSON Document API | [docs/public/api.md](docs/public/api.md) |
+| JSON Document Protocol | [docs/public/api.md](docs/public/api.md) |
+| Editing Protocol | [docs/public/editing.md](docs/public/editing.md) |
+| Document Types · TBD | [후보와 완료 조건](docs/public/document-types.md) |
+| Official Hands · TBD | [Profile의 목표와 현재 증거](docs/public/official-hands.md) |
+| Building Blocks | [독립적인 네 책임](docs/public/building-blocks.md) |
 | 편집 개념 | [docs/public/selection.md](docs/public/selection.md), [history](docs/public/history.md), [clipboard](docs/public/clipboard.md), [topology](docs/public/topology.md) |
 | Adapter | [docs/public/adapters.md](docs/public/adapters.md) |
 | Connector | [docs/public/connectors.md](docs/public/connectors.md) |
@@ -68,7 +73,10 @@ Editing, Adapter, Connector와 collaboration package는 독립 version과 releas
 lifecycle을 가집니다. Selection, clipboard, history는 editing companion이
 제공하는 headless lifecycle 위에서 도메인별 모델을 조합합니다. 플랫폼 계약은
 공식 Adapter가 맡고, external framework와 schema의 반복 glue는 공식 Connector가
-맡으며, persistence와 제품별 UI 의미는 host가 소유합니다.
+맡습니다. Host는 조합·실행 순서·제품 정책 값·copy·fixture·layout과 구체
+persistence 인스턴스 주입을 소유합니다. 재사용 모델·연산·투영·UI 행동은 각
+정본 모듈에 둡니다. Document Type 후보와 Official Hands의 전체 Profile은
+아직 TBD이며 기존 package/API의 존재만으로 완료를 선언하지 않습니다.
 일반 DOM과 Input Events 정규화가 필요한 제품은 별도 수명 주기의
 `@interactive-os/editable`도 검토할 수 있습니다.
 
@@ -89,12 +97,15 @@ optional editing companion이 제공하는 것:
 - range-set과 set-selection transition family
 - Document·Order·Sheet·Object·Tree domain slice와 selection-restoring history
 
-편집 제품이 계속 소유하는 것:
+Application/Host가 소유하는 것:
 
-- rendering, DOM focus, keyboard, drag/drop UI와 geometry hit-test
-- DOM focus, system clipboard와 제품별 interaction policy
-- formula engine과 제품별 grid projection 정책
-- product command 이름, layout, route, remote protocol
+- 정본 모듈의 조합과 실행 순서
+- 제품의 권한·기본값·copy·fixture·layout·route
+- 구체 persistence·network 인스턴스와 제품별 정책 값의 주입
+
+문서 의미·formula·grid projection은 해당 의미 owner에, DOM focus·keyboard·
+clipboard·geometry 관찰은 Adapter에, 조작 수명주기와 재사용 UI는 Affordance·
+Connector·UI Primitives에 둡니다. Core 밖의 책임이 모두 Host 책임은 아닙니다.
 
 공식 Adapter가 제공하는 것:
 
diff --git a/docs/README.md b/docs/README.md
index 8bc59c7c..783de0c0 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -1,198 +1,118 @@
 # 문서 구조
 
-이 디렉터리는 외부 사용자에게 공개할 문서 원천만 보관한다.
-릴리스 과정, 검토 루프, 과거 판단 기록은 Git issue와 version history에 남기고
-현재 문서 트리에는 복제하지 않는다.
+이 디렉터리는 외부 사용자에게 공개할 문서 원천과 생성된 owner API reference를
+보관한다. 릴리스 과정·검토 루프·과거 판단은 Git issue와 version history에 남긴다.
 
-```txt
+```text
 docs
-|-- changelog.md              # 사용자 영향 중심 변경 기록
-|-- evaluate.mjs              # 공개 문서 구조·내용 검증
-|-- public-contract-checks.mjs # 문서 원천·Pages 산출물·live 응답의 공통 공개 계약 검증
-`-- public
-|   |-- overview.md            # JSON Document: Why / How / What
-|   |-- api.md                 # JSON Document: 레퍼런스
-|   |-- concepts.md            # Core에서 Artifact까지의 책임·의존 지도
-|   |-- selection.md           # Editing: 구조 선택
-|   |-- history.md             # Editing: 로컬 undo/redo
-|   |-- clipboard.md           # Editing: 구조화된 payload
-|   |-- topology.md            # Editing: 화면 줄과 선택
-|   |-- intent.md              # Editing: Intent 시그니처
-|   |-- intent-guide.md        # Editing: Intent 따라 하기
-|   |-- official-hands.md      # Hands TBD: 완성된 기본 SDK와 확장 경계
-|   |-- collaboration.md       # JSON Document: 같은 계약의 협업 구현
-|   |-- hands.md               # Hands: 사람의 편집 도구
-|   |-- composer.md            # Hands: agent 지시와 구조화된 맥락
-|   |-- mention.md             # Hands: 안정 entity reference atom
-|   |-- order.md               # Hands: 한 줄 목록
-|   |-- object.md              # Hands: 키 선택 객체
-|   |-- tree.md                # Hands: 보이는 나무
-|   |-- database.md            # Hands: 저장된 표 view
-|   |-- adapters.md            # Adapters: 공식 플랫폼 변환
-|   |-- adapter-keyboard.md    # Adapter: Keyboard / Press / ARIA
-|   |-- adapter-grid-cell.md   # Adapter: GridPoint / DOM cell address
-|   |-- adapter-interaction.md # Adapter: Pointer / Drag and Drop session
-|   |-- adapter-clipboard.md   # Adapter: ClipboardEvent
-|   |-- adapter-contenteditable.md # Adapter: native-input DOM
-|   |-- connectors.md          # Connectors: 공식 라이브러리 생태계 연결
-|   |-- connector-react.md     # Connector: React 구독
-|   |-- connector-react-hook-form.md # Connector: form draft와 commit
-|   |-- connector-ajv.md       # Connector: Ajv validation
-|   |-- connector-zod.md       # Connector: Zod database 변환
-|   |-- connector-zod-validate.md # Connector: Zod validation
-|   |-- connector-tanstack-table.md # Connector: visible table topology
-|   |-- react-editing.md       # Connectors: React 선택·커서 질의
-|   `-- llms.txt               # machine-readable 공개 문서
+├─ public/                    # 한국어 개념·계약·사용법, llms.txt
+├─ api-reference/             # owner package별 생성 reference와 등록표
+├─ changelog.md               # 사용자 영향 중심 변경 기록
+├─ evaluate.mjs               # 문서·등록·증거 연결 검사
+└─ public-contract-checks.mjs  # 원천·Pages·live의 공통 공개 계약 검사
 ```
 
-사이트의 문서 탐색은 공개 컨셉 트리를 사용한다. 파일은 `public/`의 평평한 책임
-폴더에 유지하고, 별도 중첩 폴더를 개념으로 추가하지 않는다.
-
-```txt
-JSON Document
-|-- Why
-|-- Concept Map
-`-- API
-
-Editing
-|-- Intent guide
-|-- Intent
-|-- Topology
-|-- Selection
-|-- Clipboard
-`-- History
-
-Adapter
-|-- Overview
-|-- Keyboard
-|-- Clipboard
-`-- Contenteditable
-
-Connector
-|-- Overview
-|-- React
-|   `-- React editing
-|-- React Hook Form
-|-- Ajv
-|-- Zod
-|   `-- Validate
-`-- TanStack Table
-
-Affordance
-|-- Focus
-|-- Caret
-|-- Select
-|-- Typeahead
-|-- Activate
-|-- Escape
-|-- Expand/Collapse
-|-- Undo
-|-- Delete
-|-- Rename
-|-- Nudge
-|-- Hover
-|-- Double-click
-|-- Triple-click
-|-- Context menu
-|-- Drag
-|-- Marquee
-|-- Drop
-|-- Duplicate
-|-- Resize
-|-- Pan
-|-- Scroll
-|-- Zoom
-|-- Snap
-`-- Not-allowed
-
+## 사이트의 읽기 구조
+
+탐색 섹션은 `site/src/app/site-layers.ts`, 페이지 제목·URL·문서 원천의 연결은
+`site/site-routes.json`의 `documentSource`가 소유한다. `doc-pages.ts`는 그 원천을
+읽고, Markdown 링크도 같은 등록표에서 사이트 URL을 찾는다. 별도 파일명→URL
+카탈로그를 유지하지 않는다. 아래는 개념 수준의 지도이며 leaf 페이지 목록을
+복제한 탐색 정본이 아니다.
+
+```text
+Introduction
+├─ Why
+├─ Concept Map
+└─ How We Build
+Foundation
+├─ Overview
+├─ JSON Document Protocol
+├─ Document Types · TBD
+│  └─ 후보별 관찰된 schema·목표 owner·완료 증거
+├─ Editing Protocol
+│  └─ Intent · Topology · Selection · Clipboard · History
+└─ Collaboration
+   └─ Replica · Lifecycle · History · Text
+Building Blocks
+├─ Overview
+├─ Adapter
+├─ Connector
+├─ Affordance
+└─ UI Primitives
 Hands
-|-- Overview
-|-- Official Hands (TBD)
-|-- Order
-|-- Object
-|-- Tree
-|-- Database
-|-- Composer
-`-- Mention
-
-----------------------------------------
-
-Collaboration
-|-- Replica
-|-- Lifecycle
-|-- Collaborative History
-`-- Text
-    `-- native-input DOM lease
+└─ 현재 Usage와 Official Hands Profile · TBD
+Artifact
+└─ Content Prototype · TBD
+Applications
+└─ 제품 조합과 제품에서 발견한 책임
 ```
 
+읽기 순서는 필수 package dependency chain이 아니다. Collaboration은 같은
+JSONDocument의 대체 구현이고 Adapter와 Connector는 독립적으로 선택한다.
+API reference는 각 owner package의 위치에 유지한다. 탐색 분류는 owner의
+책임 종류나 새 runtime 계층이 아니다. Core 안내를 전체 package catalog처럼
+별도의 Reference 섹션에 중복 노출하지 않는다.
+
 ## 규범 우선순위
 
 Repository 전체의 개념과 이름 정본은
 `standards/repository-naming.md`, package 내부 책임 배치 정본은
 `standards/repository-implementation-shape.md`, browser event부터 model
-reconciliation까지의 DOM 편집 정본은 `standards/dom-editing-lifecycle.md`입니다.
+reconciliation까지의 DOM 편집 정본은 `standards/dom-editing-lifecycle.md`다.
 현재 v3 portable root의 compatibility 정본은 `standards/json-document-v3/profile.md`,
-`standards/json-document-v3/public-surface.json`, 그리고 profile이
-지정한 conformance vector와 language binding입니다. 이름 정본은 stable v3
-identifier나 동작을 바꾸지 않으며, 과거 version 문서는 정본 public surface의
-Root symbol·six-member 계약을 확장하지 않습니다.
-
-EditingSession의 확정된 공통 의미는 `standards/editing-session.md`가 소유합니다.
-ES 규칙은 공통 의미를 규정하고 현재 TypeScript binding·local History 정책은 별도
-표에서 구별합니다. callback 형태·재시도 시점·구독 전략을 보편 조건으로 굳히지
-않습니다. 각 규칙을 owner의 행동 테스트에 연결합니다. `docs:evaluate`는 그 증거 연결을 검사하고 package test가
-실제 행동을 검증합니다. 이 확정은 전체 Hands의 Stable 선언을 뜻하지 않습니다.
-
-편집 문법의 안정화 설계는 `standards/editing-grammar.md`에 있습니다. 공통 편집
-규칙, Hands profile의 선택, 입력 매핑의 소유자와 적합성 증거를 연결하는 Design
-Draft이며 기존 Stable profile의 권위를 변경하지 않습니다. API reference와 Usage는
-각 owner에 유지하고, 설계 문서를 별도의 API catalog로 사용하지 않습니다.
-
-문서 원천, Pages 산출물, live 응답의 공개 계약 검사는
-`public-contract-checks.mjs`가 소유합니다. Root symbol 수는 Core의
-`public-contract.json`, 유효한 package 참조는 `api-reference/packages.mjs`에서
-읽습니다. 각 evaluator의 파일·HTTP 읽기와 재시도 정책은 그대로 유지합니다.
-
-## 책임 기준
-
-| 위치 | 책임 | 독자 |
-| --- | --- | --- |
-| `changelog.md` | 사용자 영향 중심 변경 기록 | 외부 사용자, 릴리스 확인자 |
-| `public/` | 사용법과 프로젝트 이해를 위한 공식 문서 원천 | 외부 사용자, LLM, 사이트 방문자 |
+`standards/json-document-v3/public-surface.json`, 지정된 conformance vector와
+language binding이다. 이름 정본은 Stable v3 identifier나 동작을 바꾸지 않는다.
+
+EditingSession의 확정된 공통 의미는 `standards/editing-session.md`가 소유한다.
+ES 규칙과 현재 TypeScript binding·local History 정책은 구별하며 각 규칙을
+owner의 행동 테스트에 연결한다. 이 확정은 전체 Hands의 Stable 선언이 아니다.
+
+편집 문법의 안정화 설계는 `standards/editing-grammar.md`의 Design Draft다.
+공통 규칙·Profile 선택·입력 owner·적합성 증거를 연결하지만 기존 Stable
+계약의 권위를 변경하지 않는다. API reference와 Usage를 대체하지 않는다.
+
+## 현재 계약과 TBD
+
+- Core v3 Stable, EditingSession 공통 의미, 개별 package API의 범위를 구분한다.
+- Document Type은 책임 이름과 경계가 정해졌더라도 후보별 owner 수렴이 남으면
+  `TBD`를 유지한다. schema나 API가 존재한다는 이유만으로 완료 처리하지 않는다.
+- Official Hands는 지원 입력·실패·선택 복원·History와 조합 적합성의 미확정
+  경계 및 완료 증거를 표시한다.
+- Artifact visual prototype은 시각 가설의 증거다. 실제 문서·Hands 연결이나
+  파일 호환성이 없는 경우 제목·설명에서 `TBD`로 드러낸다.
+- TBD는 막연한 미래 목록이 아니라 현재 증거, 목표 책임, 남은 완료 조건을 담는다.
+
+## 책임과 검증
+
+| 원천 | 책임 |
+| --- | --- |
+| `public/` | 외부 사용자와 사이트 방문자의 개념·계약·Usage |
+| `public/llms.txt` | 같은 목표와 현재 계약을 요약한 기계 판독 문서 |
+| `api-reference/packages.mjs` | owner package의 source entrypoint와 사이트 탐색 분류 |
+| `api-reference/*.md` | package root와 공개 subpath에서 생성한 API reference |
+| `changelog.md` | 사용자 영향 중심 변경 기록 |
+
+`package.json#exports`의 TypeScript 진입점과 API 등록을 비교해 subpath 누락을
+검출한다. `docs:evaluate`는 원천 등록과 상대 파일 링크, ES 규칙의 행동 증거
+연결을 확인한다. API 생성 검사는 등록된 파일의 self-consistency만으로 끝내지 않는다.
+
+문서의 목차는 실제 렌더러가 만든 heading과 ID에서 읽는다. site 테스트는 실제
+본문 링크와 목차 대상의 존재, 목표 탐색·제목·TBD 경로를 검증한다.
+문자열이나 링크의 존재는 의미 적합성을 대신하지 않으며 package/browser 검증을
+함께 봐야 한다.
+
+문서 원천·Pages·live의 공통 계약은 `public-contract-checks.mjs`가 소유한다.
+Root symbol 수는 Core `public-contract.json`에서 읽는다.
 
 ## 작성 원칙
 
-- 본문은 한글로 쓴다.
-- 코드 식별자, 명령어, 파일 경로, 표준명은 원문을 유지한다.
-- public 문서는 usage와 프로젝트 이해만 다룬다.
-- 페이지마다 할 일 하나만 쓴다. overview는 Why/How/What 배경,
-  api는 시그니처 레퍼런스, selection은 구조
-  선택, history는 로컬 undo/redo, clipboard는 구조화된 payload,
-  topology는 화면 줄과 선택, intent는 편집 Intent 시그니처,
-  intent-guide는 Intent 따라 하기, adapters는 플랫폼 변환,
-  connectors는 연결 방법이다. react-editing은 React에서 선택과 커서를
-  그리는 사용법이다.
-  concepts는 JSON Document에서 Artifact까지의 책임과 의존 지도다.
-  official-hands는 디자인과 제품 데이터는 열어 두고 수렴된 편집 기능을
-  완성된 SDK로 제공하는 TBD 관점이다.
-  collaboration은 같은 JSON Document의 다른 구현이다. hands는
-  Editing 위 장르의 손이다. order·object·tree는 그 손의
-  나머지 slice다. database는 저장된 표 view의 손이다.
-  composer·mention은 Rich Text와 구조화된 context로 구현한 손이다. App 이름과
-  출력 표현은 Hands로 올리지 않는다.
-- 배경 문서는 왜 만들었는지부터 쓴다. 컨셉 페이지는 그 아이디어를
-  한 문서 위에서 만져보게 한다. 레퍼런스는 호출과 계약부터 쓴다.
-- 새 개념은 독자가 그 개념을 필요로 하는 상황을 본 뒤에 이름 붙인다.
-- 초안을 쓴 뒤 선언 전 사용, 선제 부정, 메타 안내와 중복을 제거하고
-  앞뒤 페이지를 이어 읽는다.
-- 무엇을 하는지로 정의한다. 소유하지 않는 것의 목록으로 시작하지 않는다.
-- 같은 아키텍처 다이어그램과 패키지 카탈로그를 페이지마다 복제하지 않는다.
-- 이름·구현 모양 정본과 profile은 `standards/`에 두고 public 가이드에서 인용하지
-  않는다.
-- 릴리스 history, 검토 loop, maintainer-only gate는 public 문서에 쓰지 않는다.
-- 내부 구현 경로는 public 문서에 쓰지 않는다.
-- 새 문서는 기존 책임 폴더 중 하나에 들어가야 한다.
-- 새 책임 폴더가 필요하면 먼저 이 파일의 책임 표를 갱신한다.
-- 새 public concept와 이름은
-  `standards/repository-naming.md`의 admission과 문법을 먼저
-  통과해야 한다.
+- 본문은 한글로 쓰고 코드 식별자·명령어·경로·표준명은 원문을 유지한다.
+- 페이지마다 책임 하나를 설명하고 인접 owner의 설명과 시그니처는 연결한다.
+- 새로운 개념은 책임과 필요성이 드러난 뒤 이름 붙인다.
+- 같은 아키텍처 다이어그램과 package 목록을 여러 문서에 복제하지 않는다.
+- 표준·명명·구현 배치 정본은 `standards/`에 두며 public 가이드는 사용자 계약과
+  사용법을 설명한다. 내부 경로·검토 루프·maintainer-only gate를 본문에 노출하지 않는다.
+- 재사용 모델·연산·입력 해석·projection·UI를 Host 책임으로 설명하지 않는다.
+  Host는 조합·실행 순서·제품 정책 값·copy·fixture·layout·구체 인스턴스를 소유한다.
+- 새 public 개념과 이름은 정본 naming admission을 먼저 통과해야 한다.
diff --git a/docs/api-reference/a2ui.md b/docs/api-reference/a2ui.md
index c3b66a66..b7a753a8 100644
--- a/docs/api-reference/a2ui.md
+++ b/docs/api-reference/a2ui.md
@@ -1,8 +1,8 @@
 # @interactive-os/json-document-a2ui API
 
-**Owner:** Connector
+**탐색 분류:** Connector
 
-A2UI streaming document connector의 public entrypoint입니다. 아래 항목은 package root에서 import할 수 있는 안정된 public API이며 internal 경로는 계약이 아닙니다.
+A2UI streaming document connector의 public entrypoint입니다. API의 owner는 이 package이며 탐색 분류는 사이트에서 읽는 위치입니다. 별도 subpath 표시가 없는 항목은 package root에서 import합니다. internal 경로는 계약이 아닙니다.
 
 > 이 문서는 `packages/json-document-a2ui/src/index.ts`에서 생성됩니다. API를 변경한 뒤 `npm run docs:api`를 실행하세요.
 
diff --git a/docs/api-reference/affordance.md b/docs/api-reference/affordance.md
index 370e11f0..eecd6fb8 100644
--- a/docs/api-reference/affordance.md
+++ b/docs/api-reference/affordance.md
@@ -1,8 +1,8 @@
 # @interactive-os/json-document-affordance API
 
-**Owner:** Affordance
+**탐색 분류:** Affordance
 
-입력 문법과 interaction session의 public entrypoint입니다. 아래 항목은 package root에서 import할 수 있는 안정된 public API이며 internal 경로는 계약이 아닙니다.
+입력 문법과 interaction session의 public entrypoint입니다. API의 owner는 이 package이며 탐색 분류는 사이트에서 읽는 위치입니다. 별도 subpath 표시가 없는 항목은 package root에서 import합니다. internal 경로는 계약이 아닙니다.
 
 > 이 문서는 `packages/json-document-affordance/src/index.ts`에서 생성됩니다. API를 변경한 뒤 `npm run docs:api`를 실행하세요.
 
diff --git a/docs/api-reference/ajv.md b/docs/api-reference/ajv.md
index 5d288f97..2a4af271 100644
--- a/docs/api-reference/ajv.md
+++ b/docs/api-reference/ajv.md
@@ -1,8 +1,8 @@
 # @interactive-os/json-document-ajv API
 
-**Owner:** Connector
+**탐색 분류:** Connector
 
-Ajv validation connector의 public entrypoint입니다. 아래 항목은 package root에서 import할 수 있는 안정된 public API이며 internal 경로는 계약이 아닙니다.
+Ajv validation connector의 public entrypoint입니다. API의 owner는 이 package이며 탐색 분류는 사이트에서 읽는 위치입니다. 별도 subpath 표시가 없는 항목은 package root에서 import합니다. internal 경로는 계약이 아닙니다.
 
 > 이 문서는 `packages/json-document-ajv/src/index.ts`에서 생성됩니다. API를 변경한 뒤 `npm run docs:api`를 실행하세요.
 
diff --git a/docs/api-reference/animation-react.md b/docs/api-reference/animation-react.md
index eb0951e2..5073bcd1 100644
--- a/docs/api-reference/animation-react.md
+++ b/docs/api-reference/animation-react.md
@@ -1,8 +1,8 @@
 # @interactive-os/json-document-animation-react API
 
-**Owner:** UI Primitives
+**탐색 분류:** UI Primitives
 
-생성 대기 시각 언어의 public entrypoint입니다. 아래 항목은 package root에서 import할 수 있는 안정된 public API이며 internal 경로는 계약이 아닙니다.
+생성 대기 시각 언어의 public entrypoint입니다. API의 owner는 이 package이며 탐색 분류는 사이트에서 읽는 위치입니다. 별도 subpath 표시가 없는 항목은 package root에서 import합니다. internal 경로는 계약이 아닙니다.
 
 > 이 문서는 `packages/json-document-animation-react/src/index.ts`에서 생성됩니다. API를 변경한 뒤 `npm run docs:api`를 실행하세요.
 
diff --git a/docs/api-reference/annotation.md b/docs/api-reference/annotation.md
index c7e6c8a6..4e8cfed6 100644
--- a/docs/api-reference/annotation.md
+++ b/docs/api-reference/annotation.md
@@ -1,8 +1,8 @@
 # @interactive-os/json-document-annotation API
 
-**Owner:** Hands
+**탐색 분류:** Hands
 
-Annotation Hand interaction과 SVG projection의 public entrypoint입니다. 아래 항목은 package root에서 import할 수 있는 안정된 public API이며 internal 경로는 계약이 아닙니다.
+Annotation interaction과 SVG projection의 public entrypoint입니다. API의 owner는 이 package이며 탐색 분류는 사이트에서 읽는 위치입니다. 별도 subpath 표시가 없는 항목은 package root에서 import합니다. internal 경로는 계약이 아닙니다.
 
 > 이 문서는 `packages/json-document-annotation/src/index.ts`에서 생성됩니다. API를 변경한 뒤 `npm run docs:api`를 실행하세요.
 
diff --git a/docs/api-reference/calendar.md b/docs/api-reference/calendar.md
index ddd6773c..3699c5c0 100644
--- a/docs/api-reference/calendar.md
+++ b/docs/api-reference/calendar.md
@@ -1,8 +1,8 @@
 # @interactive-os/json-document-calendar API
 
-**Owner:** Hands
+**탐색 분류:** Hands
 
-Calendar React lifecycle와 occurrence interaction 계약의 public entrypoint입니다. 아래 항목은 package root에서 import할 수 있는 안정된 public API이며 internal 경로는 계약이 아닙니다.
+Calendar React lifecycle와 occurrence interaction 계약의 public entrypoint입니다. API의 owner는 이 package이며 탐색 분류는 사이트에서 읽는 위치입니다. 별도 subpath 표시가 없는 항목은 package root에서 import합니다. internal 경로는 계약이 아닙니다.
 
 > 이 문서는 `packages/json-document-calendar/src/index.ts`에서 생성됩니다. API를 변경한 뒤 `npm run docs:api`를 실행하세요.
 
diff --git a/docs/api-reference/collaboration.md b/docs/api-reference/collaboration.md
index 42a5ce0c..09f7b84a 100644
--- a/docs/api-reference/collaboration.md
+++ b/docs/api-reference/collaboration.md
@@ -1,8 +1,8 @@
 # @interactive-os/json-document-collaboration API
 
-**Owner:** Collaboration
+**탐색 분류:** Collaboration
 
-replica, history, text collaboration runtime의 public entrypoint입니다. 아래 항목은 package root에서 import할 수 있는 안정된 public API이며 internal 경로는 계약이 아닙니다.
+replica, history, text collaboration runtime의 public entrypoint입니다. API의 owner는 이 package이며 탐색 분류는 사이트에서 읽는 위치입니다. 별도 subpath 표시가 없는 항목은 package root에서 import합니다. internal 경로는 계약이 아닙니다.
 
 > 이 문서는 `packages/json-document-collaboration/src/index.ts`에서 생성됩니다. API를 변경한 뒤 `npm run docs:api`를 실행하세요.
 
@@ -504,6 +504,181 @@ interface HistoryStatus {
 ```ts
 restoreHistoryRuntime(input: unknown, options: CollaborationRestoreOptions): HistoryRestoreResult
 ```
+## `@interactive-os/json-document-collaboration/text`
+
+아래 API는 package root가 아닌 이 subpath에서 import합니다.
+### `createTextRuntime`
+
+```ts
+createTextRuntime(initial: unknown, options: CollaborationRuntimeOptions): TextRuntime
+```
+### `History`
+
+```ts
+interface History {
+  status(): HistoryStatus;
+  canUndo(): JSONPatchValidationResult;
+  undo(): HistoryResult;
+  canRedo(): JSONPatchValidationResult;
+  redo(): HistoryResult;
+}
+```
+### `HistoryResult`
+
+```ts
+type HistoryResult =
+  | {
+      readonly ok: true;
+      readonly changeId: ChangeId;
+      readonly target: ChangeId;
+      readonly didChangeDocument: boolean;
+      /** This operation's applied change; null when it only changes causal history. */
+      readonly change: JSONAppliedChange | null;
+      /** Captured before subscribers can author a later transition. */
+      readonly status: HistoryStatus & {
+        readonly canUndo: boolean;
+        readonly canRedo: boolean;
+      };
+    }
+  | {
+      readonly ok: false;
+      readonly code: string;
+      readonly reason?: string;
+    };
+```
+### `HistoryStatus`
+
+```ts
+interface HistoryStatus {
+  readonly undoTarget: ChangeId | null;
+  readonly redoTarget: ChangeId | null;
+  readonly undoDepth: number;
+  readonly redoDepth: number;
+  readonly revision: number;
+}
+```
+### `restoreTextRuntime`
+
+```ts
+restoreTextRuntime(input: unknown, options: CollaborationRestoreOptions): TextRestoreResult
+```
+### `Text`
+
+```ts
+interface Text {
+  capture(pointer: string): TextCaptureResult;
+  plan(
+    capture: TextCapture,
+    observation: TextObservation,
+  ): TextPlanResult;
+  commit(
+    plan: TextPlan,
+    options?: JSONDocumentCommitOptions,
+  ): TextCommitResult;
+}
+```
+### `TextCapture`
+
+```ts
+interface TextCapture {
+  readonly pointer: string;
+  readonly target: MemberId;
+  readonly textNode: TextNodeId;
+  readonly value: string;
+}
+```
+### `TextCaptureResult`
+
+```ts
+type TextCaptureResult =
+  | {
+      readonly ok: true;
+      readonly capture: TextCapture;
+    }
+  | {
+      readonly ok: false;
+      readonly code: string;
+      readonly reason: string;
+    };
+```
+### `TextCommitResult`
+
+```ts
+type TextCommitResult =
+  | {
+      readonly ok: true;
+      readonly change: JSONAppliedChange;
+      readonly changeId: ChangeId | null;
+      readonly didChangeDocument: boolean;
+      readonly value: string;
+      readonly selection: TextSelection | null;
+    }
+  | {
+      readonly ok: false;
+      readonly code: string;
+      readonly reason: string;
+    };
+```
+### `TextObservation`
+
+```ts
+interface TextObservation {
+  readonly value: string;
+  readonly selection?: TextSelection;
+}
+```
+### `TextPlan`
+
+```ts
+interface TextPlan {
+  readonly pointer: string;
+  readonly value: string;
+  readonly selection?: TextSelection;
+}
+```
+### `TextPlanResult`
+
+```ts
+type TextPlanResult =
+  | {
+      readonly ok: true;
+      readonly plan: TextPlan;
+    }
+  | {
+      readonly ok: false;
+      readonly code: string;
+      readonly reason: string;
+    };
+```
+### `TextRestoreResult`
+
+```ts
+type TextRestoreResult =
+  | {
+      readonly ok: true;
+      readonly runtime: TextRuntime;
+    }
+  | {
+      readonly ok: false;
+      readonly code: string;
+      readonly reason: string;
+    };
+```
+### `TextRuntime`
+
+```ts
+interface TextRuntime extends HistoryRuntime {
+  readonly text: Text;
+}
+```
+### `TextSelection`
+
+```ts
+interface TextSelection {
+  readonly anchor: number;
+  readonly focus: number;
+}
+```
 ## `@interactive-os/json-document-collaboration/editing`
 
 아래 API는 package root가 아닌 이 subpath에서 import합니다.
diff --git a/docs/api-reference/composer-react.md b/docs/api-reference/composer-react.md
index 61f51535..e851ae2f 100644
--- a/docs/api-reference/composer-react.md
+++ b/docs/api-reference/composer-react.md
@@ -1,8 +1,8 @@
 # @interactive-os/json-document-composer-react API
 
-**Owner:** Hands
+**탐색 분류:** Hands
 
-Composer React interaction과 reference projection의 public entrypoint입니다. 아래 항목은 package root에서 import할 수 있는 안정된 public API이며 internal 경로는 계약이 아닙니다.
+Composer React interaction과 reference projection의 public entrypoint입니다. API의 owner는 이 package이며 탐색 분류는 사이트에서 읽는 위치입니다. 별도 subpath 표시가 없는 항목은 package root에서 import합니다. internal 경로는 계약이 아닙니다.
 
 > 이 문서는 `packages/json-document-composer-react/src/index.ts`에서 생성됩니다. API를 변경한 뒤 `npm run docs:api`를 실행하세요.
 
diff --git a/docs/api-reference/composer.md b/docs/api-reference/composer.md
index f182ef1a..8db9ec02 100644
--- a/docs/api-reference/composer.md
+++ b/docs/api-reference/composer.md
@@ -1,8 +1,8 @@
 # @interactive-os/json-document-composer API
 
-**Owner:** Hands
+**탐색 분류:** Hands
 
-Composer draft와 reference/trigger command 계약의 public entrypoint입니다. 아래 항목은 package root에서 import할 수 있는 안정된 public API이며 internal 경로는 계약이 아닙니다.
+Composer draft와 reference/trigger command 계약의 public entrypoint입니다. API의 owner는 이 package이며 탐색 분류는 사이트에서 읽는 위치입니다. 별도 subpath 표시가 없는 항목은 package root에서 import합니다. internal 경로는 계약이 아닙니다.
 
 > 이 문서는 `packages/json-document-composer/src/index.ts`에서 생성됩니다. API를 변경한 뒤 `npm run docs:api`를 실행하세요.
 
diff --git a/docs/api-reference/contenteditable-collaboration.md b/docs/api-reference/contenteditable-collaboration.md
index 7dc1a6da..563aa0ee 100644
--- a/docs/api-reference/contenteditable-collaboration.md
+++ b/docs/api-reference/contenteditable-collaboration.md
@@ -1,8 +1,8 @@
 # @interactive-os/json-document-contenteditable-collaboration API
 
-**Owner:** Collaboration
+**탐색 분류:** Collaboration
 
-collaborative contenteditable lease의 public entrypoint입니다. 아래 항목은 package root에서 import할 수 있는 안정된 public API이며 internal 경로는 계약이 아닙니다.
+collaborative contenteditable lease의 public entrypoint입니다. API의 owner는 이 package이며 탐색 분류는 사이트에서 읽는 위치입니다. 별도 subpath 표시가 없는 항목은 package root에서 import합니다. internal 경로는 계약이 아닙니다.
 
 > 이 문서는 `packages/contenteditable-collaboration/src/index.ts`에서 생성됩니다. API를 변경한 뒤 `npm run docs:api`를 실행하세요.
 
diff --git a/docs/api-reference/contenteditable.md b/docs/api-reference/contenteditable.md
index bdae70d6..221c9a7d 100644
--- a/docs/api-reference/contenteditable.md
+++ b/docs/api-reference/contenteditable.md
@@ -1,8 +1,8 @@
 # @interactive-os/json-document-contenteditable API
 
-**Owner:** Adapter
+**탐색 분류:** Adapter
 
-contenteditable platform adapter의 public entrypoint입니다. 아래 항목은 package root에서 import할 수 있는 안정된 public API이며 internal 경로는 계약이 아닙니다.
+contenteditable platform adapter의 public entrypoint입니다. API의 owner는 이 package이며 탐색 분류는 사이트에서 읽는 위치입니다. 별도 subpath 표시가 없는 항목은 package root에서 import합니다. internal 경로는 계약이 아닙니다.
 
 > 이 문서는 `packages/json-document-contenteditable/src/index.ts`에서 생성됩니다. API를 변경한 뒤 `npm run docs:api`를 실행하세요.
 
diff --git a/docs/api-reference/database.md b/docs/api-reference/database.md
index b4e8fa55..c3bca26c 100644
--- a/docs/api-reference/database.md
+++ b/docs/api-reference/database.md
@@ -1,8 +1,8 @@
 # @interactive-os/json-document-database API
 
-**Owner:** Hands
+**탐색 분류:** Hands
 
-Database Hand domain 계약의 public entrypoint입니다. 아래 항목은 package root에서 import할 수 있는 안정된 public API이며 internal 경로는 계약이 아닙니다.
+Database 문서 모델·연산·saved-view projection의 public entrypoint입니다. API의 owner는 이 package이며 탐색 분류는 사이트에서 읽는 위치입니다. 별도 subpath 표시가 없는 항목은 package root에서 import합니다. internal 경로는 계약이 아닙니다.
 
 > 이 문서는 `packages/json-document-database/src/index.ts`에서 생성됩니다. API를 변경한 뒤 `npm run docs:api`를 실행하세요.
 
diff --git a/docs/api-reference/editing.md b/docs/api-reference/editing.md
index 2137c922..e14f160d 100644
--- a/docs/api-reference/editing.md
+++ b/docs/api-reference/editing.md
@@ -1,8 +1,8 @@
 # @interactive-os/json-document-editing API
 
-**Owner:** Editing
+**탐색 분류:** Editing
 
-intent, editor, history 편집 계약의 public entrypoint입니다. 아래 항목은 package root에서 import할 수 있는 안정된 public API이며 internal 경로는 계약이 아닙니다.
+intent, editor, history 편집 계약의 public entrypoint입니다. API의 owner는 이 package이며 탐색 분류는 사이트에서 읽는 위치입니다. 별도 subpath 표시가 없는 항목은 package root에서 import합니다. internal 경로는 계약이 아닙니다.
 
 > 이 문서는 `packages/json-document-editing/src/index.ts`에서 생성됩니다. API를 변경한 뒤 `npm run docs:api`를 실행하세요.
 
diff --git a/docs/api-reference/file-intake.md b/docs/api-reference/file-intake.md
index 19b5174d..6c2e915d 100644
--- a/docs/api-reference/file-intake.md
+++ b/docs/api-reference/file-intake.md
@@ -1,8 +1,8 @@
 # @interactive-os/json-document-file-intake API
 
-**Owner:** Artifact
+**탐색 분류:** Artifact
 
-플랫폼 독립 파일 후보와 수용 정책의 public entrypoint입니다. 아래 항목은 package root에서 import할 수 있는 안정된 public API이며 internal 경로는 계약이 아닙니다.
+플랫폼 독립 파일 후보와 수용 정책의 public entrypoint입니다. API의 owner는 이 package이며 탐색 분류는 사이트에서 읽는 위치입니다. 별도 subpath 표시가 없는 항목은 package root에서 import합니다. internal 경로는 계약이 아닙니다.
 
 > 이 문서는 `packages/json-document-file-intake/src/index.ts`에서 생성됩니다. API를 변경한 뒤 `npm run docs:api`를 실행하세요.
 
diff --git a/docs/api-reference/json-document.md b/docs/api-reference/json-document.md
index fb35e112..64b44fa0 100644
--- a/docs/api-reference/json-document.md
+++ b/docs/api-reference/json-document.md
@@ -1,8 +1,8 @@
 # @interactive-os/json-document API
 
-**Owner:** JSON Document
+**탐색 분류:** JSON Document
 
-Core document 값·주소·patch 계약의 public entrypoint입니다. 아래 항목은 package root에서 import할 수 있는 안정된 public API이며 internal 경로는 계약이 아닙니다.
+Core document 값·주소·patch 계약의 public entrypoint입니다. API의 owner는 이 package이며 탐색 분류는 사이트에서 읽는 위치입니다. 별도 subpath 표시가 없는 항목은 package root에서 import합니다. internal 경로는 계약이 아닙니다.
 
 > 이 문서는 `packages/json-document/src/application/document/index.ts`에서 생성됩니다. API를 변경한 뒤 `npm run docs:api`를 실행하세요.
 
diff --git a/docs/api-reference/markdown-react.md b/docs/api-reference/markdown-react.md
index 40fb9626..19f68f06 100644
--- a/docs/api-reference/markdown-react.md
+++ b/docs/api-reference/markdown-react.md
@@ -1,8 +1,8 @@
 # @interactive-os/json-document-markdown-react API
 
-**Owner:** Artifact
+**탐색 분류:** Artifact
 
-스트리밍 Markdown 투영과 렌더링의 public entrypoint입니다. 아래 항목은 package root에서 import할 수 있는 안정된 public API이며 internal 경로는 계약이 아닙니다.
+스트리밍 Markdown 투영과 렌더링의 public entrypoint입니다. API의 owner는 이 package이며 탐색 분류는 사이트에서 읽는 위치입니다. 별도 subpath 표시가 없는 항목은 package root에서 import합니다. internal 경로는 계약이 아닙니다.
 
 > 이 문서는 `packages/json-document-markdown-react/src/index.ts`에서 생성됩니다. API를 변경한 뒤 `npm run docs:api`를 실행하세요.
 
diff --git a/docs/api-reference/packages.mjs b/docs/api-reference/packages.mjs
index 0ba9cdfe..f78a08b7 100644
--- a/docs/api-reference/packages.mjs
+++ b/docs/api-reference/packages.mjs
@@ -12,12 +12,12 @@ export const apiReferencePackages = [
   ["ui-primitives-react", "@interactive-os/json-document-ui-primitives-react", "packages/json-document-ui-primitives-react/src/index.ts", "UI Primitives", "표준 React UI primitive"],
   ["animation-react", "@interactive-os/json-document-animation-react", "packages/json-document-animation-react/src/index.ts", "UI Primitives", "생성 대기 시각 언어"],
   ["markdown-react", "@interactive-os/json-document-markdown-react", "packages/json-document-markdown-react/src/index.ts", "Artifact", "스트리밍 Markdown 투영과 렌더링"],
-  ["database", "@interactive-os/json-document-database", "packages/json-document-database/src/index.ts", "Hands", "Database Hand domain 계약"],
-  ["annotation", "@interactive-os/json-document-annotation", "packages/json-document-annotation/src/index.ts", "Hands", "Annotation Hand interaction과 SVG projection"],
+  ["database", "@interactive-os/json-document-database", "packages/json-document-database/src/index.ts", "Hands", "Database 문서 모델·연산·saved-view projection"],
+  ["annotation", "@interactive-os/json-document-annotation", "packages/json-document-annotation/src/index.ts", "Hands", "Annotation interaction과 SVG projection"],
   ["calendar", "@interactive-os/json-document-calendar", "packages/json-document-calendar/src/index.ts", "Hands", "Calendar React lifecycle와 occurrence interaction 계약"],
   ["web", "@interactive-os/json-document-web", "packages/json-document-web/src/index.ts", "Adapter", "Web platform adapter"],
   ["contenteditable", "@interactive-os/json-document-contenteditable", "packages/json-document-contenteditable/src/index.ts", "Adapter", "contenteditable platform adapter"],
-  ["rich-text", "@interactive-os/json-document-rich-text", "packages/json-document-rich-text/src/index.ts", "Editing", "Rich Text domain과 editing 계약"],
+  ["rich-text", "@interactive-os/json-document-rich-text", "packages/json-document-rich-text/src/index.ts", "Editing", "Rich Text 문서 의미와 editing 계약"],
   ["file-intake", "@interactive-os/json-document-file-intake", "packages/json-document-file-intake/src/index.ts", "Artifact", "플랫폼 독립 파일 후보와 수용 정책"],
   ["rich-text-suggestion", "@interactive-os/json-document-rich-text-suggestion", "packages/json-document-rich-text-suggestion/src/index.ts", "Hands", "Rich Text suggestion trigger와 상태 계약"],
   ["rich-text-suggestion-react", "@interactive-os/json-document-rich-text-suggestion-react", "packages/json-document-rich-text-suggestion-react/src/index.ts", "Hands", "Rich Text suggestion React interaction binding"],
@@ -29,13 +29,34 @@ export const apiReferencePackages = [
   ["rich-text-react", "@interactive-os/json-document-rich-text-react", "packages/json-document-rich-text-react/src/index.tsx", "Connector", "Rich Text React connector"],
   ["collaboration", "@interactive-os/json-document-collaboration", "packages/json-document-collaboration/src/index.ts", "Collaboration", "replica, history, text collaboration runtime"],
   ["contenteditable-collaboration", "@interactive-os/json-document-contenteditable-collaboration", "packages/contenteditable-collaboration/src/index.ts", "Collaboration", "collaborative contenteditable lease"],
-].map(([slug, packageName, entrypoint, owner, responsibility]) => ({
-  slug, packageName, entrypoint, owner, responsibility,
+].map(([slug, packageName, entrypoint, navigationGroup, responsibility]) => ({
+  slug, packageName, entrypoint, navigationGroup, responsibility,
   subpaths: slug === "collaboration" ? [{
     packageName: "@interactive-os/json-document-collaboration/history",
     entrypoint: "packages/json-document-collaboration/src/history-index.ts",
+  }, {
+    packageName: "@interactive-os/json-document-collaboration/text",
+    entrypoint: "packages/json-document-collaboration/src/text-index.ts",
   }, {
     packageName: "@interactive-os/json-document-collaboration/editing",
     entrypoint: "packages/json-document-collaboration/src/editing-index.ts",
   }] : [],
 }));
+
+export function apiReferenceCoverageErrors(manifests, references = apiReferencePackages) {
+  const expected = manifests.filter((manifest) => !manifest.private).flatMap((manifest) =>
+    Object.entries(manifest.exports).filter(([, target]) => hasTypes(target))
+      .map(([subpath]) => subpath === "." ? manifest.name : `${manifest.name}/${subpath.slice(2)}`));
+  const registered = references.flatMap(({ packageName, subpaths }) =>
+    [packageName, ...subpaths.map((subpath) => subpath.packageName)]);
+  return [
+    ...expected.filter((name) => !registered.includes(name)).map((name) => `API reference missing: ${name}`),
+    ...registered.filter((name) => !expected.includes(name)).map((name) => `API reference is not public: ${name}`),
+    ...registered.filter((name, index) => registered.indexOf(name) !== index).map((name) => `Duplicate API reference: ${name}`),
+  ];
+}
+
+function hasTypes(target) {
+  return target !== null && typeof target === "object"
+    && (typeof target.types === "string" || Object.values(target).some(hasTypes));
+}
diff --git a/docs/api-reference/packages.test.mjs b/docs/api-reference/packages.test.mjs
new file mode 100644
index 00000000..667998ee
--- /dev/null
+++ b/docs/api-reference/packages.test.mjs
@@ -0,0 +1,31 @@
+import { readFileSync } from "node:fs";
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { apiReferenceCoverageErrors, apiReferencePackages } from "./packages.mjs";
+
+const root = new URL("../../", import.meta.url);
+const read = (path) => JSON.parse(readFileSync(new URL(path, root), "utf8"));
+const manifests = read("package.json").workspaces.map((workspace) => read(`${workspace}/package.json`));
+
+test("every published TypeScript entrypoint has its owner reference", () => {
+  assert.deepEqual(apiReferenceCoverageErrors(manifests), []);
+});
+
+test("detects the omitted collaboration text subpath even when every package root is registered", () => {
+  const missingText = apiReferencePackages.map((entry) => ({
+    ...entry,
+    subpaths: entry.subpaths.filter((subpath) => !subpath.packageName.endsWith("/text")),
+  }));
+  assert.deepEqual(apiReferenceCoverageErrors(manifests, missingText), [
+    "API reference missing: @interactive-os/json-document-collaboration/text",
+  ]);
+});
+
+test("does not mistake CSS exports for TypeScript contracts and rejects stale entries", () => {
+  const entry = { packageName: "example", subpaths: [] };
+  const published = [{ name: "example", exports: { ".": { types: "./index.d.ts" }, "./styles.css": "./styles.css" } }];
+  assert.deepEqual(apiReferenceCoverageErrors(published, [entry]), []);
+  assert.deepEqual(apiReferenceCoverageErrors(published, [{ ...entry, subpaths: [{ packageName: "example/removed" }] }]), [
+    "API reference is not public: example/removed",
+  ]);
+});
diff --git a/docs/api-reference/react-hook-form.md b/docs/api-reference/react-hook-form.md
index aff21a23..b7db9efd 100644
--- a/docs/api-reference/react-hook-form.md
+++ b/docs/api-reference/react-hook-form.md
@@ -1,8 +1,8 @@
 # @interactive-os/json-document-react-hook-form API
 
-**Owner:** Connector
+**탐색 분류:** Connector
 
-React Hook Form connector의 public entrypoint입니다. 아래 항목은 package root에서 import할 수 있는 안정된 public API이며 internal 경로는 계약이 아닙니다.
+React Hook Form connector의 public entrypoint입니다. API의 owner는 이 package이며 탐색 분류는 사이트에서 읽는 위치입니다. 별도 subpath 표시가 없는 항목은 package root에서 import합니다. internal 경로는 계약이 아닙니다.
 
 > 이 문서는 `packages/json-document-react-hook-form/src/index.ts`에서 생성됩니다. API를 변경한 뒤 `npm run docs:api`를 실행하세요.
 
diff --git a/docs/api-reference/react.md b/docs/api-reference/react.md
index 36a8d8ab..d84fb355 100644
--- a/docs/api-reference/react.md
+++ b/docs/api-reference/react.md
@@ -1,8 +1,8 @@
 # @interactive-os/json-document-react API
 
-**Owner:** Connector
+**탐색 분류:** Connector
 
-React lifecycle connector의 public entrypoint입니다. 아래 항목은 package root에서 import할 수 있는 안정된 public API이며 internal 경로는 계약이 아닙니다.
+React lifecycle connector의 public entrypoint입니다. API의 owner는 이 package이며 탐색 분류는 사이트에서 읽는 위치입니다. 별도 subpath 표시가 없는 항목은 package root에서 import합니다. internal 경로는 계약이 아닙니다.
 
 > 이 문서는 `packages/json-document-react/src/index.ts`에서 생성됩니다. API를 변경한 뒤 `npm run docs:api`를 실행하세요.
 
diff --git a/docs/api-reference/rich-text-mention-react.md b/docs/api-reference/rich-text-mention-react.md
index 8ca8f59a..62754f1f 100644
--- a/docs/api-reference/rich-text-mention-react.md
+++ b/docs/api-reference/rich-text-mention-react.md
@@ -1,8 +1,8 @@
 # @interactive-os/json-document-rich-text-mention-react API
 
-**Owner:** Hands
+**탐색 분류:** Hands
 
-Rich Text mention React projection의 public entrypoint입니다. 아래 항목은 package root에서 import할 수 있는 안정된 public API이며 internal 경로는 계약이 아닙니다.
+Rich Text mention React projection의 public entrypoint입니다. API의 owner는 이 package이며 탐색 분류는 사이트에서 읽는 위치입니다. 별도 subpath 표시가 없는 항목은 package root에서 import합니다. internal 경로는 계약이 아닙니다.
 
 > 이 문서는 `packages/json-document-rich-text-mention-react/src/index.tsx`에서 생성됩니다. API를 변경한 뒤 `npm run docs:api`를 실행하세요.
 
diff --git a/docs/api-reference/rich-text-mention.md b/docs/api-reference/rich-text-mention.md
index ac0c6b28..349a4652 100644
--- a/docs/api-reference/rich-text-mention.md
+++ b/docs/api-reference/rich-text-mention.md
@@ -1,8 +1,8 @@
 # @interactive-os/json-document-rich-text-mention API
 
-**Owner:** Hands
+**탐색 분류:** Hands
 
-Rich Text entity mention schema와 삽입 계약의 public entrypoint입니다. 아래 항목은 package root에서 import할 수 있는 안정된 public API이며 internal 경로는 계약이 아닙니다.
+Rich Text entity mention schema와 삽입 계약의 public entrypoint입니다. API의 owner는 이 package이며 탐색 분류는 사이트에서 읽는 위치입니다. 별도 subpath 표시가 없는 항목은 package root에서 import합니다. internal 경로는 계약이 아닙니다.
 
 > 이 문서는 `packages/json-document-rich-text-mention/src/index.ts`에서 생성됩니다. API를 변경한 뒤 `npm run docs:api`를 실행하세요.
 
diff --git a/docs/api-reference/rich-text-react.md b/docs/api-reference/rich-text-react.md
index 6c9acf7b..9f06ea9a 100644
--- a/docs/api-reference/rich-text-react.md
+++ b/docs/api-reference/rich-text-react.md
@@ -1,8 +1,8 @@
 # @interactive-os/json-document-rich-text-react API
 
-**Owner:** Connector
+**탐색 분류:** Connector
 
-Rich Text React connector의 public entrypoint입니다. 아래 항목은 package root에서 import할 수 있는 안정된 public API이며 internal 경로는 계약이 아닙니다.
+Rich Text React connector의 public entrypoint입니다. API의 owner는 이 package이며 탐색 분류는 사이트에서 읽는 위치입니다. 별도 subpath 표시가 없는 항목은 package root에서 import합니다. internal 경로는 계약이 아닙니다.
 
 > 이 문서는 `packages/json-document-rich-text-react/src/index.tsx`에서 생성됩니다. API를 변경한 뒤 `npm run docs:api`를 실행하세요.
 
diff --git a/docs/api-reference/rich-text-suggestion-react.md b/docs/api-reference/rich-text-suggestion-react.md
index 061ca76b..6f40279a 100644
--- a/docs/api-reference/rich-text-suggestion-react.md
+++ b/docs/api-reference/rich-text-suggestion-react.md
@@ -1,8 +1,8 @@
 # @interactive-os/json-document-rich-text-suggestion-react API
 
-**Owner:** Hands
+**탐색 분류:** Hands
 
-Rich Text suggestion React interaction binding의 public entrypoint입니다. 아래 항목은 package root에서 import할 수 있는 안정된 public API이며 internal 경로는 계약이 아닙니다.
+Rich Text suggestion React interaction binding의 public entrypoint입니다. API의 owner는 이 package이며 탐색 분류는 사이트에서 읽는 위치입니다. 별도 subpath 표시가 없는 항목은 package root에서 import합니다. internal 경로는 계약이 아닙니다.
 
 > 이 문서는 `packages/json-document-rich-text-suggestion-react/src/index.ts`에서 생성됩니다. API를 변경한 뒤 `npm run docs:api`를 실행하세요.
 
diff --git a/docs/api-reference/rich-text-suggestion.md b/docs/api-reference/rich-text-suggestion.md
index d771a4fb..b70154e5 100644
--- a/docs/api-reference/rich-text-suggestion.md
+++ b/docs/api-reference/rich-text-suggestion.md
@@ -1,8 +1,8 @@
 # @interactive-os/json-document-rich-text-suggestion API
 
-**Owner:** Hands
+**탐색 분류:** Hands
 
-Rich Text suggestion trigger와 상태 계약의 public entrypoint입니다. 아래 항목은 package root에서 import할 수 있는 안정된 public API이며 internal 경로는 계약이 아닙니다.
+Rich Text suggestion trigger와 상태 계약의 public entrypoint입니다. API의 owner는 이 package이며 탐색 분류는 사이트에서 읽는 위치입니다. 별도 subpath 표시가 없는 항목은 package root에서 import합니다. internal 경로는 계약이 아닙니다.
 
 > 이 문서는 `packages/json-document-rich-text-suggestion/src/index.ts`에서 생성됩니다. API를 변경한 뒤 `npm run docs:api`를 실행하세요.
 
diff --git a/docs/api-reference/rich-text-web.md b/docs/api-reference/rich-text-web.md
index 37f35bb0..9311c44f 100644
--- a/docs/api-reference/rich-text-web.md
+++ b/docs/api-reference/rich-text-web.md
@@ -1,8 +1,8 @@
 # @interactive-os/json-document-rich-text-web API
 
-**Owner:** Adapter
+**탐색 분류:** Adapter
 
-Rich Text DOM adapter의 public entrypoint입니다. 아래 항목은 package root에서 import할 수 있는 안정된 public API이며 internal 경로는 계약이 아닙니다.
+Rich Text DOM adapter의 public entrypoint입니다. API의 owner는 이 package이며 탐색 분류는 사이트에서 읽는 위치입니다. 별도 subpath 표시가 없는 항목은 package root에서 import합니다. internal 경로는 계약이 아닙니다.
 
 > 이 문서는 `packages/json-document-rich-text-web/src/index.ts`에서 생성됩니다. API를 변경한 뒤 `npm run docs:api`를 실행하세요.
 
diff --git a/docs/api-reference/rich-text.md b/docs/api-reference/rich-text.md
index 48247c54..6f648e3a 100644
--- a/docs/api-reference/rich-text.md
+++ b/docs/api-reference/rich-text.md
@@ -1,8 +1,8 @@
 # @interactive-os/json-document-rich-text API
 
-**Owner:** Editing
+**탐색 분류:** Editing
 
-Rich Text domain과 editing 계약의 public entrypoint입니다. 아래 항목은 package root에서 import할 수 있는 안정된 public API이며 internal 경로는 계약이 아닙니다.
+Rich Text 문서 의미와 editing 계약의 public entrypoint입니다. API의 owner는 이 package이며 탐색 분류는 사이트에서 읽는 위치입니다. 별도 subpath 표시가 없는 항목은 package root에서 import합니다. internal 경로는 계약이 아닙니다.
 
 > 이 문서는 `packages/json-document-rich-text/src/index.ts`에서 생성됩니다. API를 변경한 뒤 `npm run docs:api`를 실행하세요.
 
diff --git a/docs/api-reference/selection.md b/docs/api-reference/selection.md
index 8e2a7e11..05dad5d3 100644
--- a/docs/api-reference/selection.md
+++ b/docs/api-reference/selection.md
@@ -1,8 +1,8 @@
 # @interactive-os/json-document-selection API
 
-**Owner:** Editing
+**탐색 분류:** Editing
 
-구조적 selection과 topology 계약의 public entrypoint입니다. 아래 항목은 package root에서 import할 수 있는 안정된 public API이며 internal 경로는 계약이 아닙니다.
+구조적 selection과 topology 계약의 public entrypoint입니다. API의 owner는 이 package이며 탐색 분류는 사이트에서 읽는 위치입니다. 별도 subpath 표시가 없는 항목은 package root에서 import합니다. internal 경로는 계약이 아닙니다.
 
 > 이 문서는 `packages/json-document-selection/src/index.ts`에서 생성됩니다. API를 변경한 뒤 `npm run docs:api`를 실행하세요.
 
diff --git a/docs/api-reference/tanstack-table.md b/docs/api-reference/tanstack-table.md
index a13a487a..ee676c51 100644
--- a/docs/api-reference/tanstack-table.md
+++ b/docs/api-reference/tanstack-table.md
@@ -1,8 +1,8 @@
 # @interactive-os/json-document-tanstack-table API
 
-**Owner:** Connector
+**탐색 분류:** Connector
 
-TanStack Table connector의 public entrypoint입니다. 아래 항목은 package root에서 import할 수 있는 안정된 public API이며 internal 경로는 계약이 아닙니다.
+TanStack Table connector의 public entrypoint입니다. API의 owner는 이 package이며 탐색 분류는 사이트에서 읽는 위치입니다. 별도 subpath 표시가 없는 항목은 package root에서 import합니다. internal 경로는 계약이 아닙니다.
 
 > 이 문서는 `packages/json-document-tanstack-table/src/index.ts`에서 생성됩니다. API를 변경한 뒤 `npm run docs:api`를 실행하세요.
 
diff --git a/docs/api-reference/ui-primitives-react.md b/docs/api-reference/ui-primitives-react.md
index ceb8a738..977542c2 100644
--- a/docs/api-reference/ui-primitives-react.md
+++ b/docs/api-reference/ui-primitives-react.md
@@ -1,8 +1,8 @@
 # @interactive-os/json-document-ui-primitives-react API
 
-**Owner:** UI Primitives
+**탐색 분류:** UI Primitives
 
-표준 React UI primitive의 public entrypoint입니다. 아래 항목은 package root에서 import할 수 있는 안정된 public API이며 internal 경로는 계약이 아닙니다.
+표준 React UI primitive의 public entrypoint입니다. API의 owner는 이 package이며 탐색 분류는 사이트에서 읽는 위치입니다. 별도 subpath 표시가 없는 항목은 package root에서 import합니다. internal 경로는 계약이 아닙니다.
 
 > 이 문서는 `packages/json-document-ui-primitives-react/src/index.ts`에서 생성됩니다. API를 변경한 뒤 `npm run docs:api`를 실행하세요.
 
diff --git a/docs/api-reference/web.md b/docs/api-reference/web.md
index b39d5cb4..9f1a287d 100644
--- a/docs/api-reference/web.md
+++ b/docs/api-reference/web.md
@@ -1,8 +1,8 @@
 # @interactive-os/json-document-web API
 
-**Owner:** Adapter
+**탐색 분류:** Adapter
 
-Web platform adapter의 public entrypoint입니다. 아래 항목은 package root에서 import할 수 있는 안정된 public API이며 internal 경로는 계약이 아닙니다.
+Web platform adapter의 public entrypoint입니다. API의 owner는 이 package이며 탐색 분류는 사이트에서 읽는 위치입니다. 별도 subpath 표시가 없는 항목은 package root에서 import합니다. internal 경로는 계약이 아닙니다.
 
 > 이 문서는 `packages/json-document-web/src/index.ts`에서 생성됩니다. API를 변경한 뒤 `npm run docs:api`를 실행하세요.
 
diff --git a/docs/api-reference/zod.md b/docs/api-reference/zod.md
index 9a10e315..efa6b560 100644
--- a/docs/api-reference/zod.md
+++ b/docs/api-reference/zod.md
@@ -1,8 +1,8 @@
 # @interactive-os/json-document-zod API
 
-**Owner:** Connector
+**탐색 분류:** Connector
 
-Zod schema connector의 public entrypoint입니다. 아래 항목은 package root에서 import할 수 있는 안정된 public API이며 internal 경로는 계약이 아닙니다.
+Zod schema connector의 public entrypoint입니다. API의 owner는 이 package이며 탐색 분류는 사이트에서 읽는 위치입니다. 별도 subpath 표시가 없는 항목은 package root에서 import합니다. internal 경로는 계약이 아닙니다.
 
 > 이 문서는 `packages/json-document-zod/src/index.ts`에서 생성됩니다. API를 변경한 뒤 `npm run docs:api`를 실행하세요.
 
diff --git a/docs/evaluate.mjs b/docs/evaluate.mjs
index 25fd93e3..708d746d 100644
--- a/docs/evaluate.mjs
+++ b/docs/evaluate.mjs
@@ -1,15 +1,20 @@
 import { existsSync, readFileSync, readdirSync } from "node:fs";
-import { dirname, join } from "node:path";
+import { basename, dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { spawnSync } from "node:child_process";
 import { validateLlmsContract, validatePublicPackageReferences } from "./public-contract-checks.mjs";
 
 const root = dirname(dirname(fileURLToPath(import.meta.url)));
 
-const apiReferenceCheck = spawnSync(process.execPath, ["scripts/generate-api-reference.mjs", "--check"], { cwd: root, encoding: "utf8" });
-if (apiReferenceCheck.status !== 0) {
-  process.stderr.write(apiReferenceCheck.stderr || apiReferenceCheck.stdout);
-  process.exit(apiReferenceCheck.status ?? 1);
+for (const args of [
+  ["scripts/generate-api-reference.mjs", "--check"],
+  ["--test", "docs/api-reference/packages.test.mjs", "site/scripts/route-checks.test.mjs"],
+]) {
+  const result = spawnSync(process.execPath, args, { cwd: root, encoding: "utf8" });
+  if (result.status !== 0) {
+    process.stderr.write(result.stderr || result.stdout);
+    process.exit(result.status ?? 1);
+  }
 }
 
 function read(path) {
@@ -52,6 +57,8 @@ const publicDocs = {
   applications: read("docs/public/applications.md"),
   concepts: read("docs/public/concepts.md"),
   foundation: read("docs/public/foundation.md"),
+  buildingBlocks: read("docs/public/building-blocks.md"),
+  editing: read("docs/public/editing.md"),
   howWeBuild: read("docs/public/how-we-build.md"),
   documentTypes: read("docs/public/document-types.md"),
   selection: read("docs/public/selection.md"),
@@ -141,83 +148,37 @@ const implementationShape = read("standards/repository-implementation-shape.md")
 const domEditingLifecycle = read("standards/dom-editing-lifecycle.md");
 const editingSession = read("standards/editing-session.md");
 
-if (JSON.stringify(fileNames("docs/public")) !== JSON.stringify([
-  "adapter-clipboard.md",
-  "adapter-contenteditable.md",
-  "adapter-grid-cell.md",
-  "adapter-interaction.md",
-  "adapter-keyboard.md",
-  "adapter-virtual-selection.md",
-  "adapters.md",
-  "affordance-activate.md",
-  "affordance-cancel.md",
-  "affordance-caret.md",
-  "affordance-context-menu.md",
-  "affordance-contextual.md",
-  "affordance-copy-drag.md",
-  "affordance-delete.md",
-  "affordance-double-click.md",
-  "affordance-drag.md",
-  "affordance-drop.md",
-  "affordance-focus.md",
-  "affordance-fold.md",
-  "affordance-forbid.md",
-  "affordance-handles.md",
-  "affordance-history.md",
-  "affordance-hover.md",
-  "affordance-marquee.md",
-  "affordance-nudge.md",
-  "affordance-pan.md",
-  "affordance-rename.md",
-  "affordance-resize.md",
-  "affordance-scroll.md",
-  "affordance-select.md",
-  "affordance-snap.md",
-  "affordance-triple-click.md",
-  "affordance-typeahead.md",
-  "affordance-zoom.md",
-  "affordance.md",
-  "animation.md",
-  "api.md",
-  "applications.md",
-  "clipboard.md",
-  "collaboration-history.md",
-  "collaboration-lease.md",
-  "collaboration-lifecycle.md",
-  "collaboration-replica.md",
-  "collaboration-text.md",
-  "collaboration.md",
-  "composer.md",
-  "concepts.md",
-  "connector-a2ui.md",
-  "connector-ajv.md",
-  "connector-react-hook-form.md",
-  "connector-react.md",
-  "connector-tanstack-table.md",
-  "connector-zod-validate.md",
-  "connector-zod.md",
-  "connectors.md",
-  "database.md",
-  "document-types.md",
-  "foundation.md",
-  "hands.md",
-  "history.md",
-  "how-we-build.md",
-  "intent-guide.md",
-  "intent.md",
-  "llms.txt",
-  "mention.md",
-  "object.md",
-  "official-hands.md",
-  "order.md",
-  "overview.md",
-  "react-editing.md",
-  "selection.md",
-  "topology.md",
-  "tree.md",
-  "ui-primitives.md",
-])) {
-  fail("docs/public: only the active v3 guides and llms.txt may remain.");
+const documentRoutes = readJson("site/site-routes.json").filter((route) => route.documentSource !== undefined);
+const registeredSources = documentRoutes.map((route) => route.documentSource);
+for (const source of registeredSources) {
+  if (!/^docs\/(?:public|api-reference)\/[^/]+\.md$/.test(source) || !existsSync(join(root, source))) {
+    fail(`Invalid documentation source registration: ${source}`);
+  }
+}
+if (new Set(registeredSources).size !== registeredSources.length) fail("Documentation sources must have one canonical route.");
+for (const directory of ["docs/public", "docs/api-reference"]) {
+  const actual = fileNames(directory).filter((name) => directory === "docs/public" || name.endsWith(".md"));
+  const registered = registeredSources.filter((source) => dirname(source) === directory).map((source) => basename(source));
+  if (directory === "docs/public") registered.push("llms.txt");
+  registered.sort();
+  if (JSON.stringify(actual) !== JSON.stringify(registered)) fail(`${directory}: Markdown files must match registered pages.`);
+}
+
+// File links are repository-relative; site Markdown uses the same registered source path.
+const linkedDocuments = [
+  "README.md", "docs/README.md", "docs/changelog.md",
+  ...registeredSources,
+  ...rootPackage.workspaces.filter((workspace) => workspace !== "site").map((workspace) => `${workspace}/README.md`),
+  ...filesUnder("standards").filter((path) => path.endsWith(".md")),
+];
+for (const path of linkedDocuments) {
+  for (const [, href] of read(path).matchAll(/(?<!!)\[[^\]\n]*\]\(([^)\s]+)\)/g)) {
+    if (/^(?:[a-z][a-z\d+.-]*:|[/#?])/i.test(href)) continue;
+    const target = href.split(/[?#]/)[0];
+    if (target && !existsSync(join(root, dirname(path), decodeURIComponent(target)))) {
+      fail(`${path}: missing relative link target ${href}`);
+    }
+  }
 }
 
 if (JSON.stringify(fileNames("standards")) !== JSON.stringify([
diff --git a/docs/public/api.md b/docs/public/api.md
index 786fc770..ec899b97 100644
--- a/docs/public/api.md
+++ b/docs/public/api.md
@@ -1,7 +1,9 @@
-# API Reference
+# JSON Document Protocol
 
-앞 문서에서 사용한 `@interactive-os/json-document`의 공개 API를 작업별로
-정리합니다.
+`JSONDocument`는 값·주소·검증·원자적 변경·관찰의 여섯 member를 갖는 공통
+계약입니다. 로컬 구현과 [Collaboration](collaboration.md)이 같은 계약을
+제공합니다. Core v3의 Stable 계약과 현재 TypeScript API를 작업별로 정리합니다.
+package 전체 시그니처는 [JSON Document API](../api-reference/json-document.md)에 있습니다.
 
 ## 문서 만들기
 
diff --git a/docs/public/building-blocks.md b/docs/public/building-blocks.md
new file mode 100644
index 00000000..089378ce
--- /dev/null
+++ b/docs/public/building-blocks.md
@@ -0,0 +1,37 @@
+# Building Blocks
+
+Building Blocks는 Foundation의 계약을 실제 입력·외부 생태계·UI에 연결하는
+독립적인 책임입니다. 필요한 조각을 골라 Hands를 조합합니다.
+
+## 네 가지 책임
+
+| 위치 | 건너는 경계 | 안내 |
+| --- | --- | --- |
+| Adapter | keyboard, pointer, clipboard, native input 같은 플랫폼 사실 → 기존 편집 계약 | [Adapter](adapters.md) |
+| Connector | React, React Hook Form, Ajv, Zod, TanStack Table, A2UI의 계약 ↔ 문서·편집 계약 | [Connector](connectors.md) |
+| Affordance | 선택·drag·resize·취소 같은 조작 의미와 수명주기 → 장르별 Intent | [Affordance](affordance.md) |
+| UI Primitives | 표준 control·focus·overlay·반복 UI 행동 → 제품의 시각 조합 | [UI Primitives](ui-primitives.md) |
+
+Adapter와 Connector는 앞뒤 계층이 아닙니다. React 없이 Web Adapter를 쓰거나,
+DOM 입력 없이 Connector로 문서를 관찰할 수 있습니다. Affordance가 플랫폼 입력을
+받는 편의 API도 실제 플랫폼 판정은 Adapter의 계약을 소비합니다.
+
+## 조합과 소유권
+
+JSON 값과 원자적 변경은 [JSON Document](api.md), 문서 고유 의미는
+[Document Type](document-types.md), 작업 경계와 선택·History는
+[Editing](editing.md)에 남습니다. Building Blocks는 이 의미를 다시 구현하지 않고
+자신이 연결하는 계약을 소비합니다.
+
+Host는 사용할 모듈, 권한·기본값, 구체 인스턴스와 layout을 선택합니다.
+modifier 해석, gesture 수명주기, native selection 복구와 재사용 UI는 해당
+Adapter·Affordance·Connector·UI Primitives의 책임입니다.
+
+## 현재 제공 범위와 목표
+
+각 안내의 API·Usage·Source는 현재 제공하는 연결을 보여 줍니다. 특정 연결의
+존재가 모든 플랫폼이나 모든 장르의 편집을 보장하지는 않습니다.
+
+[Official Hands · TBD](official-hands.md)는 이 조각들을 조합했을 때 지원 입력,
+선택 복원, Clipboard, 취소와 Undo/Redo가 함께 동작하는 기본 Profile을 목표로
+합니다. 지원 범위와 적합성 증거가 닫히기 전에는 완성된 SDK로 간주하지 않습니다.
diff --git a/docs/public/concepts.md b/docs/public/concepts.md
index ac0a41c6..1c8cf9b3 100644
--- a/docs/public/concepts.md
+++ b/docs/public/concepts.md
@@ -1,163 +1,114 @@
 # Concept Map
 
-이 사이트의 권장 읽기 순서와 package 의존 방향은 같은 것이 아닙니다.
-먼저 Core를 배우고 실제 편집 경험까지 읽어 가지만, 필요한 책임은 아래처럼
-Core 주위에 선택적으로 붙습니다.
-
-```txt
-                         ┌─ Editing ─ Selection · Intent · History
-local JSON Document ─────┤
-                         ├─ Document Types ─ profile · model · schema · operations
-                         ├─ Adapter ─ platform contract
-collaborative Document ──┤
-                         ├─ Connector ─ named ecosystem
-                         └─ optional domain / UI composition
-
-Affordance ─ input grammar ─┐
-UI Primitives ─ standard UI ├─ Host가 장르별 Hands를 조합
-Rich Text 등 domain ────────┘
-
-Hands를 surface에 조합한 결과가 사람이 다루는 Artifact가 됩니다. Artifact는
-navigation이나 workflow를 소유하지 않는 콘텐츠입니다. Application은 Artifact와
-다른 콘텐츠를 runtime과 제품 정책에 놓아 실제 제품 경험으로 제공합니다.
-```
-
-이 그림의 선은 허용된 의존·조합 방향입니다. 모든 노드를 순서대로 설치하라는
-뜻이 아닙니다. Adapter와 Connector는 서로의 선행 계층이 아니며, 각각 플랫폼과
-외부 라이브러리가 필요할 때 고릅니다. Collaboration은 다음 계층이 아니라
-같은 `JSONDocument` 계약의 다른 구현입니다.
-
-권장 읽기 순서는 `Foundation → Building Blocks → Hands → Artifact → Application`입니다.
-Foundation 안에서는 JSON Document, Document Types, Editing과 Collaboration을,
-Building Blocks에서는 Adapter, Connector, Affordance와 UI Primitives를 읽습니다.
-이 순서는 학습을 위한 서사일 뿐 package dependency를 주장하지 않습니다.
-Collaboration은 Core의 대체 구현과 profile 포함 관계로 Foundation 안에서 읽습니다.
-
-프로젝트가 책임을 발견하는 방향은 이 읽기·구현 방향과 반대입니다.
+목표는 같은 역할과 책임이 하나의 정본 모듈을 갖고, Application이 그 공개 API를
+조합하는 구조입니다. 아래는 읽기 순서와 책임 지도입니다. 모든 package가 차례로
+의존하는 직렬 계층은 아닙니다.
 
 ```text
-구현 의존: Foundation → Building Blocks → Hands → Artifact → Application
-책임 발견: Application → 책임 발견 → Canonical Module → Application
+Foundation
+├─ JSON Document ─ value / at / query / validatePatch / commit / subscribe
+│  └─ Local 또는 Collaboration 구현
+├─ Document Types ─ model / schema / invariants / operations / projections
+│  └─ 후보별 owner 수렴과 계약 확정 · TBD
+└─ Editing ─ Selection / Topology / Intent / Clipboard / History
+
+Building Blocks
+├─ Adapter ─ 플랫폼 입력·출력
+├─ Connector ─ 이름 있는 외부 생태계
+├─ Affordance ─ 조작 의미·수명주기
+└─ UI Primitives ─ 재사용 UI
+
+Hands ─ 장르별로 함께 검증된 편집 조합
+└─ Official Hands Profile의 완성 조건 · TBD
+
+Artifact ─ Application 안에서 사람이 다루는 콘텐츠
+└─ 현재 visual prototype의 문서·Hands 계약 연결 · TBD
+
+Applications ─ 조합·실행 순서·제품 정책·layout·외부 인스턴스 주입
 ```
 
-먼저 제품을 만들고 실제 사용 흐름에서 반복되는 책임을 찾습니다. 추출된 책임은
-canonical owner와 public API를 얻고, Application은 임시 구현 대신 그 API를 다시
-소비합니다. 자세한 순환은 [How We Build](how-we-build.md)에서 설명합니다.
-
-## JSON Document
-
-JSON Document는 현재 값을 보관하고, JSON Pointer와 JSONPath로 위치를 찾고,
-JSON Patch를 검사해 적용합니다. 적용된 변경은 구독자에게 전달합니다.
+Adapter와 Connector는 서로의 선행 계층이 아닙니다. 필요한 플랫폼과 생태계를
+독립적으로 선택합니다. Collaboration도 Editing 앞이나 뒤의 필수 단계가 아니라
+같은 `JSONDocument` 계약의 다른 구현입니다.
 
-이 계약에는 화면이나 편집 장르가 들어가지 않습니다. 문서, 표, 보드의
-생김새가 달라도 값의 주소와 변경 형식은 여기서 같습니다. 공개 호출은
-[API](api.md)에 정리되어 있습니다.
+## Foundation의 프로토콜
 
-## Editing
+[Foundation](foundation.md)은 값·의미·작업·관찰의 경계를 설명합니다.
 
-Editing은 문서 값 옆에 편집 중에만 필요한 상태를 둡니다. 화면에서 들어온
-요청은 Intent가 되고, Selection은 대상을, Topology는 보이는 순서를,
-Clipboard는 옮길 내용을 기억합니다. History는 값과 선택을 함께 되돌립니다.
+| 경계 | 현재 계약 | 목표와 남은 일 |
+| --- | --- | --- |
+| JSON Document | 여섯 member와 JSON 표준 연산; Core v3 Stable | UI·장르별 edit verb를 Core에 추가하지 않음 |
+| Document Type | 의미·모델·유효성·연산·Projection이라는 책임 경계 | 후보별 canonical owner와 공개 계약의 수렴 · TBD |
+| Editing | Intent → EditingPlan → Session.apply → commit → EditingSnapshot | Hands별 필수 행동과 조합 적합성의 동결 · TBD |
+| Collaboration | 같은 document 계약과 base → History → Text profile | 각 profile의 지원 범위로 사용; 모든 Hands의 협업 보장과 구별 |
 
-Editing은 화면을 그리지 않습니다. 화면이 보낸 Intent를 현재 문서와 편집
-상태에 적용합니다. 시작점은 [Intent guide](intent-guide.md)입니다.
+[JSON Document Protocol](api.md)과 [Editing Protocol](editing.md)에서 실제 경계를
+건너는 값을 봅니다. Copy는 읽기이고 선택만 바꾸는 작업에는 document commit이
+필요하지 않습니다. 로컬 inverse History와 actor-local 협업 History는 이름이
+같아도 복원 의미와 소유자가 다릅니다.
 
-## Document Types
+## Document Types · TBD
 
 Document Type은 특정 JSON Document가 무엇을 의미하고 어떤 상태와 변경이
 유효한지를 정의합니다. Profile, Document Model, Schema와 invariant,
 Document Operation, Projection이 이 책임에 속합니다.
 
-Document Type은 selection, History 같은 편집 lifecycle이나 화면 표현을
-소유하지 않습니다. 현재 후보와 아직 결정하지 않은 소유권은
-[Document Types · TBD](document-types.md)에 정리되어 있습니다.
-
-## Adapter
+현재 Rich Text·Order·Object·Tree·Database·Calendar·Sheet·Kanban·Annotation은
+분류 후보입니다. [Document Types](document-types.md)에서 현재 관찰된 schema,
+소유권 감사와 완료 조건을 봅니다. 이름이 등록됐다고 package 재배치가 완료된
+것은 아닙니다. 같은 Calendar라도 Document Type, Hand와 Application은 다른 책임입니다.
 
-Adapter는 keyboard, clipboard, contenteditable 같은 플랫폼 계약을 공개
-API에 맞춰 번역합니다. 예를 들어 key chord는 의미 command가 되고,
-브라우저의 clipboard event는 Editing의 copy, cut, paste로 이어집니다.
+## Building Blocks
 
-Adapter는 책임 종류입니다. Web Adapter는 Editing을 소비하지만
-Contenteditable Adapter는 JSON Document와 DOM/React lifecycle을 직접 잇습니다.
-따라서 모든 Adapter가 Editing 다음 dependency라는 뜻은 아닙니다.
+[Building Blocks](building-blocks.md)는 서로 독립적인 네 책임을 제공합니다.
 
-플랫폼마다 다른 event와 lifecycle은 [Adapter](adapters.md)가 맡습니다.
+| 위치 | 소유하는 것 | 안내 |
+| --- | --- | --- |
+| Adapter | keyboard·clipboard·native input 같은 플랫폼 계약의 번역 | [Adapter](adapters.md) |
+| Connector | React·Zod·Ajv·TanStack Table·A2UI 같은 외부 계약의 연결 | [Connector](connectors.md) |
+| Affordance | 선택·drag·resize·취소 같은 조작 의미와 수명주기 | [Affordance](affordance.md) |
+| UI Primitives | 표준 control·focus·overlay와 반복 UI 행동 | [UI Primitives](ui-primitives.md) |
 
-## Connector
-
-Connector는 React, Zod, Ajv, TanStack Table처럼 이름 있는 라이브러리의
-입출력을 기존 계약에 연결합니다. 문서 변경을 React 구독으로 전달하거나,
-화면에 보이는 행과 열을 Sheet의 Topology로 바꾸는 식입니다.
-
-라이브러리를 교체해도 문서와 편집 계약은 바뀌지 않습니다. 지원 범위는
-[Connector](connectors.md)에 있습니다. Connector는 JSON Document, Editing,
-Hands capability 중 자신이 연결하는 계약에 직접 붙으며 Adapter를 전제로 하지
-않습니다.
-
-## Affordance
-
-Affordance는 고르기, 입력하기, 접기, drag, undo처럼 사람이 이미 알고 있는
-조작을 정의합니다. 일부 API는 Adapter가 만든 command를 받고, 일부 Web 편의
-API는 event-shaped input을 내부 Adapter와 함께 해석합니다. 각 reference의
-입력 type이 어느 경계인지 정본입니다.
-
-화면의 모양은 host가 정합니다. 입력의 의미와 조합은
-[Affordance](affordance.md)에서 다룹니다.
+예를 들어 Contenteditable Adapter는 JSON Document와 DOM lifecycle을 직접
+연결할 수 있습니다. 모든 Adapter가 Editing을 거쳐야 한다는 뜻은 아닙니다.
+외부 생태계를 교체해도 문서 고유 의미를 Connector에서 다시 정의하지 않습니다.
 
 ## Hands
 
-Hands는 Core와 필요한 선택 책임을 조합해 사람과 agent가 artifact를 다루게
-하는 장르별 완료 기준입니다.
-Order는 한 줄 목록을 집어 옮기고, Object는 key를 고치며, Tree는 가지를
-접습니다. Composer는 agent에게 지시와 맥락을 건네는 손이고, Mention은
-안정적인 대상을 글 안에 넣는 손입니다. 둘은 아직 TBD입니다.
-
-Hands는 하나의 공통 package나 화면 component 이름이 아닙니다. 장르 document와
-Intent, Selection/Clipboard/History, 대표 Affordance, platform lifecycle이 실제
-Host 조합에서 함께 동작해야 닫힙니다. 재사용 책임은 owner package API로,
-제품 고유 정책은 이름 붙은 Host module로 남습니다. 현재 증거와 목록은
-[Hands](hands.md)에 있습니다.
-
-## Artifact
-
-Artifact는 독립 App이 아니라 앞의 책임을 조합해 사람이 보고 고칠 수 있게 만든
-Application 내부 콘텐츠입니다. navigation, workflow와 제품 정책은 소유하지 않습니다.
-MD, PPT, Sheet는 서로 다른 화면과 Hands를 사용해도 같은 문서와 편집 계약을
-공유할 수 있습니다.
+Hands는 장르의 문서와 Intent, Selection/Clipboard/History, 대표 Affordance,
+platform lifecycle을 실제 편집 경험으로 닫은 조합입니다. 하나의 공통 superclass나
+만능 package 이름이 아닙니다.
 
-현재 Artifact 페이지는 file compatibility나 Core/Hands interoperability를
-증명하지 않는 visual prototype입니다. 여러 artifact surface를 한 Host chrome에
-놓는 정보 구조와 시각 가설만 확인하며, 실제 계약 증거는 각 Hands Live Demo와
-package test에서 봅니다.
+[Hands](hands.md)의 Live Demo와 owner API는 현재 구현의 증거입니다.
+[Official Hands · TBD](official-hands.md)는 디자인과 제품 정책은 열어 두고
+기본 편집을 완성된 SDK로 제공하려는 목표입니다. 구현이 있는 것과 Profile의
+지원 입력·실패·선택 복원·호환성 조건이 모두 닫힌 것은 구별합니다.
 
-## Application
+## Artifact · TBD
 
-Application은 Artifact와 Hands를 실제 제품 경험으로 제공하는 최종 composition
-root입니다. 주요 화면 영역과 실행 순서, URL과 navigation, 제품 copy와 fixture,
-concrete runtime 연결은 Application에 남습니다. 문서의 의미, editing lifecycle,
-platform translation과 반복 UI처럼 같은 역할과 책임을 갖는 코드는 canonical
-module로 추출됩니다.
+Artifact는 navigation과 workflow를 소유하지 않는 Application 내부 콘텐츠입니다.
+서로 다른 Hands를 사용해도 같은 문서·편집 계약으로 사람이 보고 고칠 수 있어야 합니다.
 
-[Calendar와 AI Agent](/applications)는 제품에서 발견한 책임과 App에 남은 정책을
-함께 보여 줍니다. Calendar Document Type, Calendar Hand와 Calendar Application은
-같은 이름을 공유하지만 서로 다른 owner입니다.
+현재 [Artifact](/viewer)는 MD·PPT·Sheet surface를 한 Host chrome에 놓는 visual
+prototype입니다. JSON Document/Hands 연결, 편집 후 복원과 파일 호환성의 증거는
+아직 없습니다. 모양을 전환할 수 있다는 사실을 상호운용이나 완성된 편집의
+증거로 세지 않습니다.
 
-## Collaboration
+## Applications
 
-Collaboration은 JSON Document 계약을 여러 참여자의 인과 변경으로 구현합니다.
-로컬 구현과 마찬가지로 값을 읽고, 변경을 적용하고, 결과를 구독하지만 내부
-기록은 참여자의 변경 순서와 수렴을 다룹니다.
+Application은 Artifact와 Hands를 실제 제품 경험으로 조합합니다. 실행 순서,
+URL과 navigation, 권한·copy·fixture·layout과 concrete runtime 연결을 소유합니다.
+모델·의미 연산·selection·history·gesture·플랫폼 번역·projection·재사용 UI는
+각 canonical module의 책임입니다. 한 제품에서만 쓰여도 이 경계는 같습니다.
 
-Collaboration은 Foundation 안에서 JSON Document와 같은 계약의 대체 구현으로 읽습니다.
-협업 document를 Editing에 주입할 수 있지만 History command는 editor-local
-History 대신 actor-local `runtime.history`로 연결해야 합니다. base → History →
-Text profile의 포함 관계는 [Collaboration](collaboration.md)에 있습니다.
+[Calendar와 AI Agent](applications.md)는 현재 제품에서 드러난 조합을 보여 줍니다.
+읽기 순서는 Foundation에서 Application으로 가지만, 책임을 발견하는 작업은
+Application에서 시작해 정본 API를 만들고 제품이 다시 소비하는 순환입니다.
+이 과정은 [How We Build](how-we-build.md)에 있습니다.
 
 ## Reference vertical: Rich Text
 
-Rich Text는 새 최상위 계층이 아니라 이 책임 graph를 끝까지 적용한 대표
-vertical입니다. JSON Document와 Selection/Editing 위에 versioned domain schema를
-두고, Web와 React integration을 분리한 뒤 Host UI가 조합합니다. profile,
-conformance vector와 browser evidence는 다른 Hands가 경계를 판단할 때 참고하는
-구현 증거입니다.
+Rich Text는 새 최상위 계층이 아니라 이 책임 지도를 적용한 대표 vertical입니다.
+문서 의미와 Editing 위에 Web Adapter, React Connector, 장르별 UI를 조합합니다.
+현재 profile·적합성·browser 증거는 다른 Hands가 경계를 판단할 때 참고할 수 있지만
+모든 Document Type과 Hands의 완료를 대신하지는 않습니다.
diff --git a/docs/public/document-types.md b/docs/public/document-types.md
index 390223c4..40c3aadc 100644
--- a/docs/public/document-types.md
+++ b/docs/public/document-types.md
@@ -59,26 +59,35 @@ Document Type은 DOM event, pointer gesture, React lifecycle, 화면 layout과 
 
 ## 후보 · TBD
 
-현재 사이트에서 다음 항목이 Document Type 후보입니다.
-
-```text
-Document Types · TBD
-├── Rich Text
-├── Order
-├── Object
-├── Tree
-├── Database
-├── Calendar
-├── Sheet
-├── Kanban
-└── Annotation
-```
+현재 사이트에서 다음 후보의 관찰된 schema와 목표 책임을 미리 볼 수 있습니다.
+
+| 후보 | 닫으려는 문서 의미 |
+| --- | --- |
+| [Rich Text · TBD](/docs/document-types/rich-text) | node·mark·text 구조와 schema-aware 연산 |
+| [Order · TBD](/docs/document-types/order) | 항목 identity와 순서·이름 변경 |
+| [Object · TBD](/docs/document-types/object) | 객체 identity·geometry와 의미 연산 |
+| [Tree · TBD](/docs/document-types/tree) | parent/child 관계·subtree 연산·visible projection |
+| [Database · TBD](/docs/document-types/database) | property·record·saved view와 projection |
+| [Calendar · TBD](/docs/document-types/calendar) | event·recurrence·interval·occurrence projection |
+| [Sheet · TBD](/docs/document-types/sheet) | row·column·cell identity와 구조 연산 |
+| [Kanban · TBD](/docs/document-types/kanban) | column·card 관계와 이동 |
+| [Annotation · TBD](/docs/document-types/annotation) | annotation shape와 geometry 연산 |
 
 이 목록은 분류 후보이지 완료 선언이 아닙니다. 각 후보는 모델, invariant,
 operation과 projection의 실제 owner를 감사한 뒤에만 이 위치로 이동할 수
 있습니다. 그때까지 기존 package/API 이름, 모듈 배치와 Hands 내비게이션은
 유지합니다.
 
+## 현재와 목표 사이
+
+현재 구현의 schema와 API는 후보를 검토할 근거입니다. 목표는 model·invariant·
+operation·projection이 한 Document Type owner에서 나오고, Editing과 UI가 그
+공개 계약을 소비하는 것입니다. 편집 lifecycle·DOM geometry 관찰·React 구독은
+각자의 이웃 책임에 남습니다.
+
+Calendar에는 소스 기반 책임 감사가 있으며 아직 canonical move가 남아 있습니다.
+다른 후보도 이름이나 schema 표만으로 소유권 검토를 완료했다고 간주하지 않습니다.
+
 ## 완료 조건 · TBD
 
 각 Document Type의 분류를 확정할 때는 다음 증거가 모두 필요합니다.
diff --git a/docs/public/editing.md b/docs/public/editing.md
new file mode 100644
index 00000000..aa224fce
--- /dev/null
+++ b/docs/public/editing.md
@@ -0,0 +1,76 @@
+# Editing Protocol
+
+Editing은 문서의 변경과 다음 선택을 하나의 작업으로 확정하고 관찰하는 계약입니다.
+현재 TypeScript API의 공통 흐름을 설명하며, 모든 Hands를 하나의 editor
+interface로 통합하거나 새로운 wire protocol을 정의하지 않습니다.
+
+## 입력에서 관찰까지
+
+```text
+플랫폼 입력
+  → Adapter: 플랫폼 사실을 해석
+  → Affordance: 조작 의미와 진행 상태
+  → 장르 editor의 Intent
+      + Document Type의 의미 연산
+      + Selection / Topology
+  → EditingPlan
+  → EditingSession.apply
+  → JSONDocument.commit
+  → EditingResult / EditingSnapshot
+  → Connector / UI
+```
+
+이 그림은 편집을 실행하는 대표 경로입니다. headless 호출은 입력 Adapter가
+필요하지 않고, Connector가 반드시 마지막 단계에만 있는 것도 아닙니다.
+문서의 유효한 연산은 Document Type의 책임이며, 현재 각 editor에 놓인 책임의
+재배치는 [Document Types · TBD](document-types.md)에서 구분합니다.
+
+## 경계를 건너는 계약
+
+| 계약 | 담는 것 | 소유자 |
+| --- | --- | --- |
+| Intent | 사용자가 요청한 편집의 의미와 대상 | 장르별 Editing API |
+| `EditingPlan` | `operations`, `selectionAfter`, `origin`, 선택적인 `history`·`historyGroup` | Editing |
+| `JSONDocument.commit` | JSON Patch의 검증과 원자적 적용 | JSON Document의 로컬 또는 협업 구현 |
+| `EditingResult` | 성공한 자기 작업의 snapshot/change 또는 `ok: false`·`code` | Editing |
+| `EditingSnapshot` | `value`, `selection`, `revision`, `canUndo`, `canRedo` | Editing |
+
+작업 거절은 해당 요청의 문서·선택·History를 바꾸지 않습니다. 구독 중 재진입해
+다음 작업이 실행돼도 반환 결과는 자신의 전이에 속합니다. `revision`은 문서
+commit 횟수가 아니라 편집 상태의 전이입니다.
+
+구체 시그니처는 [Editing API](../api-reference/editing.md), 사용법은
+[Intent guide](intent-guide.md)와 [Intent](intent.md)에서 봅니다.
+
+## 값을 바꾸지 않는 경로
+
+- Selection만 바꾸면 document commit과 local Undo 항목이 생기지 않습니다.
+- Copy는 읽기입니다. 원본·선택·History를 바꾸지 않습니다.
+- Cut은 표현 쓰기와 제거를, Paste는 표현 해석과 의미 연산을 연결합니다.
+  지원 표현과 실패 조건은 해당 [Clipboard](clipboard.md)와 editor의 계약을 따릅니다.
+- 외부 변경은 그 문서에 맞는 선택 복구를 거칩니다. 복구 실패를 이미 완료된
+  document commit의 취소로 바꾸지 않습니다.
+
+## History의 소유자
+
+| 구성 | 복원 의미 | 안내 |
+| --- | --- | --- |
+| 로컬 inverse History | 기록한 문서 변경과 전후 선택을 복원하며, 실제 외부 변경 뒤 오래된 기록을 무효화 | [Local History](history.md) |
+| actor-local 협업 History | 다른 참여자의 변경을 보존하고 현재 참여자의 기여를 선택적으로 되돌림 | [Collaborative History](collaboration-history.md) |
+
+협업 document를 주입했다고 로컬 inverse History가 협업 History가 되지는 않습니다.
+협업 History owner를 연결하고 그 owner의 기록·그룹·복원 정책을 따릅니다.
+현재 외부 History API가 지원하지 않는 `history: "ignore"`는 비어 있지 않은
+operations에 대해 mutation 전에 거절합니다.
+
+## Hands Profile · TBD
+
+EditingSession의 공통 의미는 현재 계약입니다. 반면 각 Hands의 필수 작업,
+여러 선택 범위의 처리, 기본 입력 정책, 중첩 편집의 수신자와 공유 History 단위는
+전체 Profile로 아직 동결하지 않았습니다.
+
+목표는 같은 지원 입력과 Intent에서 같은 문서·선택·실패·복원 의미를 얻는 것입니다.
+이를 위해 각 Profile에 지원/의도적 미지원/미구현을 나누고, 입력부터 Undo/Redo까지의
+적합성 증거를 연결해야 합니다. 현재 API를 호출할 수 있다는 사실만으로 이 목표가
+완료되지는 않습니다. [Official Hands · TBD](official-hands.md)에 남은 경계와
+완료 조건을 정리합니다.
diff --git a/docs/public/foundation.md b/docs/public/foundation.md
index f53683ca..1b84bdac 100644
--- a/docs/public/foundation.md
+++ b/docs/public/foundation.md
@@ -1,32 +1,42 @@
 # Foundation
 
-Foundation은 Application, Artifact와 Hands가 공유하는 기반 계약입니다. 화면이나
-제품 장르보다 먼저 값의 의미, 변경, 편집 상태와 협업 방식을 정의합니다.
+Foundation은 Application, Artifact와 Hands가 공유하는 기반 계약입니다.
+값의 변경, 문서의 의미, 편집 작업과 협업을 서로 다른 책임으로 구분합니다.
 
-## JSON Document
+## JSON Document Protocol
 
-표의 셀과 문서의 블록은 생김새가 달라도 JSON 안에서 주소를 가집니다. 한 위치는
-JSON Pointer로 가리키고 여러 위치는 JSONPath로 찾으며, 변경은 JSON Patch로
-표현합니다. `JSONDocument`는 현재 값을 읽고, 찾고, 검증하고, 원자적으로 적용하고,
-실제로 달라진 결과를 구독자에게 전달하는 공통 계약입니다.
+`JSONDocument`는 `value`, `at`, `query`, `validatePatch`, `commit`,
+`subscribe`의 여섯 member를 제공합니다. 주소는 JSON Pointer, 검색은 JSONPath,
+변경은 JSON Patch로 표현합니다. Core v3의 Stable 계약이며 화면과 장르별
+편집 기능을 포함하지 않습니다. [JSON Document Protocol](api.md)에서 호출과
+실패·관찰 의미를 봅니다.
 
-## Document Types
+## Document Types · TBD
 
-Rich Text, Calendar, Database 같은 Document Type은 Foundation 위에서 데이터의
-의미와 유효한 구조를 정의합니다. 같은 이름을 쓰는 Hand나 Application과는 별도
-책임이며, 제품 화면이나 navigation을 소유하지 않습니다.
+Document Type은 문서 고유의 모델·schema·invariant·의미 연산·Projection을
+소유합니다. 예를 들어 Calendar의 recurrence와 occurrence는 제품의 layout이나
+일시적인 selection과 다른 책임입니다.
 
-## Editing
+[Document Types · TBD](document-types.md)는 목표 위치와 후보를 드러냅니다.
+현재 package에서 이 책임을 어디가 소유하는지 확인하고 API·Usage·Source와
+소비자를 닫기 전에는 재배치 완료를 선언하지 않습니다.
 
-선택, 보이는 순서, clipboard와 history처럼 편집하는 동안만 필요한 상태는 문서 값
-옆에 둡니다. 화면 사건은 Intent가 되고 Editing은 현재 문서와 편집 상태를 읽어
-처리합니다.
+## Editing Protocol
+
+[Editing Protocol](editing.md)은 Intent에서 변경 계획과 다음 선택을 만들고
+`EditingSession.apply`로 적용한 뒤 `EditingSnapshot`을 관찰하는 경계입니다.
+Selection, Topology, Clipboard와 History는 문서의 의미 모델과 구별합니다.
+
+현재 EditingSession의 공통 의미와 모든 Hands Profile의 완성은 다릅니다.
+지원 행동·기본 입력·조합 적합성이 아직 닫히지 않은 범위는
+[Official Hands · TBD](official-hands.md)로 남습니다.
 
 ## Collaboration
 
-협업은 다음 UI 계층이 아니라 같은 `JSONDocument` 계약의 다른 구현입니다. 여러
-참여자의 변경을 인과 순서로 수렴시키면서도 Foundation의 읽기·변경·구독 진입점을
-유지합니다.
+[Collaboration](collaboration.md)은 같은 `JSONDocument` 계약의 다른 구현입니다.
+base, History, Text는 선택적인 profile 포함 관계이며 새로운 UI 계층이 아닙니다.
+협업 document를 Editing에 주입할 때도 actor-local History의 소유권과 복원 의미를
+유지해야 합니다.
 
-다음으로 플랫폼과 생태계 연결을 고르려면 [Building Blocks](adapters.md)를,
-전체 개념 관계를 먼저 보려면 [Concept Map](concepts.md)을 읽습니다.
+플랫폼과 생태계 연결은 [Building Blocks](building-blocks.md), 전체 목표와 현재
+상태의 차이는 [Concept Map](concepts.md)에서 이어집니다.
diff --git a/docs/public/how-we-build.md b/docs/public/how-we-build.md
index 61852375..26935c90 100644
--- a/docs/public/how-we-build.md
+++ b/docs/public/how-we-build.md
@@ -17,13 +17,16 @@ canonical module과 public API로 정본화한다
 Application이 정본 API를 다시 소비한다
 ```
 
-구현 의존 방향과 책임을 발견하는 방향은 서로 반대입니다.
+읽기 순서와 책임을 발견하는 방향을 구별합니다.
 
 ```text
-구현 의존: Foundation → Building Blocks → Hands → Artifact → Application
+읽기 순서: Foundation → Building Blocks → Hands → Artifact → Application
 책임 발견: Application → 책임 발견 → Canonical Module → Application
 ```
 
+이 읽기 순서는 package의 직렬 의존 관계가 아닙니다. Adapter와 Connector는
+독립적으로 선택하고, Collaboration은 같은 JSONDocument 계약을 구현합니다.
+
 여기서 Artifact는 독립 App이 아니라 Application이 만들고 편집하는 콘텐츠입니다.
 Navigation, workflow, runtime과 제품 정책은 Application에 남습니다.
 
diff --git a/docs/public/llms.txt b/docs/public/llms.txt
index 9e822d89..970f8958 100644
--- a/docs/public/llms.txt
+++ b/docs/public/llms.txt
@@ -1,6 +1,6 @@
 # json-document v3
 
-json-document는 문서, 표, 슬라이드, 캔버스, 노트 편집기가 공통으로 사용할 수
+json-document의 Core는 문서, 표, 슬라이드, 캔버스, 노트 편집기가 공통으로 사용할 수
 있는 implementation-neutral JSON 편집 Kernel이다. UI component library가 아니다.
 
 v3 표준 상태는 Stable이다. 현재 release version은 `3.0.0`이다. Reference와 독립
@@ -9,6 +9,35 @@ reference·독립·collaboration binding에서 검증한다.
 
 공식 사이트: https://developer-1px.github.io/json-document/
 
+## 목표 구조와 현재 상태
+
+읽기 순서는 Foundation → Building Blocks → Hands → Artifact → Applications다.
+필수 package dependency chain이 아니다. Foundation은 JSON Document, Document
+Types, Editing, Collaboration을, Building Blocks는 Adapter, Connector,
+Affordance, UI Primitives를 묶는다. Adapter와 Connector는 독립적으로 선택한다.
+Collaboration은 같은 JSONDocument 계약의 다른 구현이다.
+
+Document Type은 model·schema·invariant·Document Operation·Projection을 소유한다.
+Rich Text, Order, Object, Tree, Database, Calendar, Sheet, Kanban, Annotation은
+아직 후보(TBD)다. 관찰된 schema와 API는 증거이지 owner 재배치 완료 선언이 아니다.
+목표 owner, public API·reference, Usage·Source와 소비자 수렴을 닫아야 한다.
+
+Hands는 정본 책임을 장르별 편집 경험으로 닫은 조합이다. Official Hands Profile의
+필수 행동·지원 입력·선택 복원·실패·History·호환성 조건은 TBD다. Artifact는
+Application 내부 콘텐츠이며 현재 viewer는 visual prototype(TBD)다. 실제
+document/Hands 연결과 파일 호환성은 검증하지 않았다.
+
+Application/Host는 조합·실행 순서·제품 정책 값·copy·fixture·layout과 구체 외부
+인스턴스 주입을 소유한다. 같은 역할과 책임은 소비자 수와 무관하게 정본 모듈로
+둔다. 사이트 탐색 분류는 package의 실제 책임 종류나 API owner의 이름이 아니다.
+
+현재 계약 안내:
+- https://developer-1px.github.io/json-document/docs/concepts/
+- https://developer-1px.github.io/json-document/docs/api/
+- https://developer-1px.github.io/json-document/docs/editing/
+- https://developer-1px.github.io/json-document/docs/document-types/
+- https://developer-1px.github.io/json-document/docs/official-hands/
+
 ## 정본 경계
 
 Portable consumer는 Root만 import한다.
@@ -53,8 +82,8 @@ stateless JSON Patch
                                      `-> optional native-input DOM lease
 ```
 
-Stateless JSON Patch는 JSON value, RFC 6901 JSON Pointer, RFC 9535 JSONPath,
-RFC 6902 JSON Patch, Result 의미를 소유한다. JSON Document는 현재 document
+Core의 표준 JSON 책임은 JSON value, RFC 6901 JSON Pointer, RFC 9535 JSONPath,
+RFC 6902 JSON Patch와 Result 의미를 다룬다. JSON Document는 현재 document
 value와 change notification을 연결한다.
 
 Canonical concept와 identifier 문법은
@@ -201,12 +230,14 @@ Core package는 root entrypoint만 공개한다. Selection, clipboard, history
 optional editing companion이 여섯-member `JSONDocument` 위에서 조합한다.
 DOM-free selection state와 semantic interaction은
 `@interactive-os/json-document-selection` companion이 key, range, mask family로
-제공하며 topology, geometry와 physical input 해석은 host port 밖에 둔다.
+제공한다. Topology는 문서·표시 순서의 owner가, geometry 관찰과 physical input
+해석은 플랫폼 Adapter가 제공하며 제품 layout과 구체 입력의 연결은 Host에 둔다.
 브라우저 플랫폼 계약은 independently versioned Adapter가 변환한다. 반복되는
 외부 생태계 integration은 independently versioned Connector가 제공한다.
 Adapter와 Connector는 공통 runtime interface가 아니라 package category다.
 외부 peer는 해당 package의 peer dependency다. Schema introspection, DOM과
-제품별 UI 의미는 해당 Adapter, Connector 또는 host의 명시적인 책임으로 남는다.
+재사용 UI 행동은 해당 Adapter, Connector 또는 UI Primitives의 책임으로 남는다.
+Host는 제품의 정책 값과 시각 조합을 선택한다.
 
 v3 Kernel release는 dependency-free Core package 하나다. Local-only consumer는
 Core만 설치한다. 이 저장소의 `@interactive-os/json-document-editing`은 atomic
@@ -215,28 +246,34 @@ Order, Sheet, Object 및 Tree domain slice를 제공하는 browser-independent
 companion이다. Document, Order, Sheet와 Tree는 range 상태 전이를 공유하고
 Object는 key 상태 전이를 사용한다. 화면 줄은 `LineTopology`와
 `GridTopology`로 넘긴다. Sheet는 `SheetTopology`, Database는 저장된
-뷰의 `recordIds`×`propertyIds`, Tree는 host `visibleIds`다. JSON Patch
-계획은 각 slice 또는 host에 둔다.
+뷰의 `recordIds`×`propertyIds`, Tree는 `projectTreeVisibility`가 계산한
+`visibleIds`다. JSON Patch 계획과 의미 연산은 장르 editor와 문서 의미의
+owner에 둔다.
 Sheet slice는 stable row·column identity, 복수의 anchor/focus rectangular range,
 primary-range JSON/TSV clipboard, selection fill, cell commit과
 selection-restoring undo/redo를 제공한다.
-Tree expand/collapse와 visible order, Object pointer geometry와 hit-test는 host
-책임이다. 값 변경 history는 selection을 함께 복구한다. Native text selection은
+Tree visible projection은 Editing의 `projectTreeVisibility`, React의 접힘 상태와
+입력 연결은 `useTreeEditing`이 소유한다. Host는 초기 expanded IDs 등 정책 값을
+선택한다. Object geometry의 의미 연산과 플랫폼 hit-test도 각각의 정본 owner에
+둔다. 값 변경 history는 selection을 함께 복구한다. Native text selection은
 이 structural selection family에 포함하지 않는다.
 `@interactive-os/json-document-web`은 KeyboardEvent chord, ClipboardEvent
 structured MIME, text-control value/caret과 Web modifier state를 public
-editing·selection contract로 번역하는 공식 Adapter다. Event target, shortcut,
-focus, geometry와 native text selection은 Host가 계속 소유한다.
+editing·selection contract로 번역하는 공식 Adapter다. Event target 경계,
+modifier·기본 chord 해석과 DOM focus 실현은 Web의 정본 API를 소비한다.
+Host는 활성화 조건과 제품별 keymap 정책 값을 선택한다.
 `@interactive-os/json-document-contenteditable`은 local JSONDocument 문자열
 포인터를 leased contenteditable React root에 붙이는 공식 Adapter다.
-툴바, atom, marks와 product chrome은 Host가 소유한다.
+Host는 toolbar와 product chrome을 조합한다. Atom·mark의 문서 의미와 재사용
+rendering·native selection·IME lifecycle은 각 문서·Adapter·UI owner에 둔다.
 `@interactive-os/json-document-react`는 React external-store subscription,
 Document editor component lifecycle, 그리고 선택 범위·focus 커서·text
 offset 질의(`useEditing`)를 제공하는 공식 Connector다.
 `@interactive-os/json-document-react-hook-form`은 React Hook Form이 draft, dirty,
 touched와 field error를 소유하게 두고 유효한 submit만 하나의 canonical editing
-transaction으로 적용한다. Undo, redo와 외부 canonical 변경은 `reset`으로 form에
-동기화하며 field UI와 product schema는 Host가 소유한다.
+transaction으로 적용한다. Undo, redo와 외부 canonical 변경은 Connector의
+leaf 동기화 또는 `reset` 정책으로 form에 반영한다. Host는 field UI를 조합하고
+문서 의미의 owner가 제공하는 schema와 제품 정책 값을 주입한다.
 `@interactive-os/json-document-ajv`는 호출자가 컴파일한 동기 Ajv validator의
 첫 error message와 `instancePath`를 validation diagnostic으로 번역한다. Mutable
 clone을 검사하므로 Ajv option이 만든 변형 결과는 canonical JSON에 채택하지 않는다.
@@ -249,7 +286,7 @@ row/column model을 Sheet topology로 번역해 정렬·필터·column ordering
 cell edit, rectangular multi-range selection, selection fill과 clipboard가 화면
 순서를 따르게 하는 공식 Connector다.
 `@interactive-os/json-document-collaboration`은 같은 canonical JSON Document을
-제공하는 independently versioned, transport-free provider이고,
+제공하는 independently versioned, transport-free collaboration engine이고,
 `@interactive-os/json-document-contenteditable-collaboration`은 collaborative
 string을 위한 optional native-input DOM lease다. 두 companion을 사용해도
 Core Root API와 editor가 받는 `JSONDocument` port는 바뀌지 않는다.
@@ -273,12 +310,27 @@ catalog의 일부가 아니다.
 
 ## Host 책임
 
-Rendering, DOM focus, geometry, keyboard policy, system clipboard, filesystem,
-network, formula engine, CRDT와 OT는 host 또는 adapter가 소유한다. Selection의
-공통 lifecycle은 editing companion에 있지만 grid range나 spatial object 같은
-구체적인 topology는 제품이 소유한다. Tree
-indent/outdent, visible-row focus, slide selection box, grid coordinate와 같은 제품
-의도는 host가 Pointer와 Patch operation으로 번역한다.
+Host는 모듈 조합·실행 순서·제품 정책 값·권한·copy·fixture·layout·구체 외부
+인스턴스 주입만 소유한다. 모델·schema·Intent·command·selection·history·gesture·
+플랫폼 번역·직렬화·projection·재사용 UI의 최종 owner가 아니다.
+Tree indent/outdent나 grid coordinate 해석도 해당 정본 모듈의 공개 API를 소비한다.
+정본이 유효한 사례를 지원하지 못하면 API를 확장하거나 책임을 등록해야 하며
+Host local 구현을 최종 상태로 인정하지 않는다.
+
+## Editing Protocol
+
+장르 editor는 Intent와 Selection/Topology에서 의미 연산을 계획한다.
+EditingPlan은 operations·selectionAfter·origin과 history 정책을 담고,
+EditingSession.apply가 JSONDocument.commit을 사용한다. EditingSnapshot은
+value·selection·revision·canUndo·canRedo를 일관되게 관찰하게 한다.
+거절은 해당 요청의 문서·선택·History를 바꾸지 않는다. Copy는 읽기이며
+selection-only 전이는 document commit과 local History 항목을 만들지 않는다.
+
+EditingSession의 공통 의미는 현재 계약이다. Hands Profile 전체의 동결과
+독립 구현 간 상호운용 인증은 아니다. 로컬 inverse History와 actor-local 협업
+History는 복원 의미와 owner가 다르다. 협업 document를 주입할 때도 협업 History
+owner를 연결해야 하며 현재 외부 History가 지원하지 않는 ignore 정책을 조용히
+다른 의미로 적용하지 않는다.
 
 ## 표준과 검증
 
diff --git a/docs/public/official-hands.md b/docs/public/official-hands.md
index 2ca611d2..1fa9b24f 100644
--- a/docs/public/official-hands.md
+++ b/docs/public/official-hands.md
@@ -1,8 +1,7 @@
 # Official Hands · TBD
 
-> **TBD** — 이 페이지는 Official Hands의 제품 방향을 설명하는 초안입니다.
-> 새로운 public contract, package boundary, kit admission 기준 또는
-> compatibility 약속을 확정하지 않습니다.
+Official Hands의 목표와 남은 경계를 설명하는 초안입니다. 새로운 public contract,
+package boundary, kit admission 기준 또는 compatibility 약속을 확정하지 않습니다.
 
 Official Hands는 디자인과 제품 데이터는 자유롭게 바꿀 수 있지만, 사람이
 편집을 끝내는 데 필요한 기능은 이미 구현되어 있는 SDK를 지향합니다.
@@ -40,15 +39,14 @@ Official은 제품 취향을 임의로 정한다는 뜻이 아닙니다. 여러
 대부분의 사용자는 Official Hands만으로 편집기를 완성할 수 있어야 합니다.
 Custom Hands는 기본 경로가 아니라 제품에만 있는 차이를 위한 escape hatch입니다.
 
-## 하나의 Hands Profile
+## Hands Profile · TBD
 
 완성된 Hands는 행동 함수만 모은 package가 아닙니다. 그 행동이 항상 같은
 뜻을 갖게 하는 최소 profile을 함께 제공합니다.
 
 ```text
 Official Hands Profile
-├─ minimum schema와 canonical shape
-├─ stable identity와 structural invariant
+├─ Document Type Profile 참조: schema · identity · invariant
 ├─ Selection specialization
 ├─ Topology interpretation
 ├─ Intent vocabulary
@@ -64,6 +62,11 @@ row identity, column identity와 cell addressability를 먼저 정해야 합니
 Sheet다운 편집 행동이 무엇을 대상으로 하는지 안정적으로 정하기 위해
 필요합니다.
 
+최소 schema와 의미 연산의 owner는 [Document Type](document-types.md)입니다.
+Hands Profile은 이 계약을 참조하고 Editing·Adapter·Affordance·Connector·UI를
+함께 선택합니다. Hands가 각 책임을 다시 구현하거나 Host가 빈칸을 메우는 구조가
+아닙니다.
+
 ### 공통 규칙과 profile의 선택
 
 공통 편집 규칙은 Selection과 Editing이 소유합니다. Profile은 그 규칙이 자신의
@@ -90,17 +93,17 @@ Selection family, EditingSession을 사용하면서 입력부터 편집 결과
 Official Hands가 최소 profile을 제공해도 완성 제품을 대신 소유하지는 않습니다.
 
 ```text
-Official Hands가 소유
-├─ 장르다운 편집을 성립시키는 최소 shape
-├─ identity와 structural invariant
-├─ 수렴한 편집 행동
-└─ 함께 검증된 기본 조합
+Official Hands Profile이 연결
+├─ Document Type의 shape·identity·invariant
+├─ Editing의 Selection·Intent·Clipboard·History
+├─ Adapter·Affordance·Connector·UI의 편집 경로
+└─ 함께 검증할 지원 범위와 기본 조합
 
 Host가 소유
-├─ 업무 field와 business rule
-├─ permission과 workflow
-├─ persistence와 collaboration policy
-├─ rendering과 layout
+├─ 제품별 정책 값·권한·copy·fixture
+├─ workflow와 실행 순서
+├─ persistence·collaboration의 구체 인스턴스 주입
+├─ UI composition과 layout
 └─ visual design
 ```
 
@@ -109,6 +112,9 @@ automation에서 전혀 다르게 보일 수 있습니다. Hands는 object ident
 Selection, translate와 resize의 의미를 유지하고 Host는 표현과 제품 정책을
 결정합니다.
 
+재사용 가능한 업무 모델·규칙과 rendering 행동은 각각 문서 의미와 UI의 정본
+모듈에 둡니다. 제품에서 선택하는 정책 값과 모듈 자체의 의미를 구별합니다.
+
 ## Affordance까지 닫기
 
 Editing capability만으로는 사람이 작업을 끝낼 수 없습니다. Official Hands는
@@ -186,3 +192,17 @@ Official profile의 지향점은 구현이 바뀌어도 같은 지원 입력에
 구체적인 profile별 필수 작업, Host field 연결, 여러 Hand가 공유하는 History
 단위는 아직 확정하지 않았습니다. 현재 후보 목록과 위 동작 예시는 완성된 SDK의
 호환성 보장이 아닙니다.
+
+## 현재 증거와 완료 조건 · TBD
+
+| 경계 | 현재 있는 것 | 완료에 필요한 것 |
+| --- | --- | --- |
+| 문서 의미 | 각 editor와 package의 모델·연산 | Document Type owner와 Profile 참조의 수렴 |
+| 편집 작업 | 기존 Intent와 EditingSession 공통 의미 | Profile별 지원/의도적 미지원/미구현 및 결과·실패 조건 |
+| 실제 입력 | Hands Live Demo와 platform binding | keyboard·pointer·Clipboard·취소·Undo/Redo가 이어지는 적합성 증거 |
+| 공개 사용 | package API와 Usage·Source | Host의 같은 책임 우회 구현 없이 조합되는 완료 경로 |
+| 호환성 | 개별 구현과 Profile의 증거 | 기본값·중첩 맥락·공유 History와 변경 정책의 명시 |
+
+이 조건을 닫기 전에는 Official Hands를 완성된 SDK나 모든 장르가 상호운용하는
+Stable 계약으로 표시하지 않습니다. 목표를 미리 드러내되 현재 동작의 증거와
+미확정 설계를 섞지 않습니다.
diff --git a/docs/public/overview.md b/docs/public/overview.md
index dd162905..f8721456 100644
--- a/docs/public/overview.md
+++ b/docs/public/overview.md
@@ -45,7 +45,7 @@ json-document는 그 공통 층을 화면과 분리된 문서 커널로 둡니
 통과한 변경만 원자적으로 적용되고, 실제로 값이 달라진 변경만
 구독자에게 전달됩니다. 현재 값을 읽고, 한 위치와 여러 위치를 찾고,
 검사하고, 적용하고, 구독하는 일이 이 계약의 전부입니다. 호출 모양은
-[API](api.md)에 있습니다.
+[JSON Document Protocol](api.md)에 있습니다.
 
 ## 같은 문을 여는 협업
 
@@ -76,8 +76,17 @@ Editing은 이 상태를 JSON Document 옆에 둡니다. 화면은 클릭과 키
 보이는 순서를 알려 줍니다. Clipboard는 JSON과 사람이 읽을 텍스트를 함께
 나릅니다. History는 값과 선택을 같이 되돌립니다.
 
-같은 문서 위에 선택과 작업을 더하는 일이 Editing입니다. 따라 가려면
-[Intent guide](intent-guide.md)에서 시작합니다.
+같은 문서 위에 선택과 작업을 더하는 일이 Editing입니다.
+[Editing Protocol](editing.md)에서 계획·적용·관찰의 경계를 보고,
+[Intent guide](intent-guide.md)에서 직접 호출해 봅니다.
+
+## 문서의 의미와 목표 owner
+
+Calendar의 recurrence나 Tree의 parent/child 관계는 편집 중의 선택과 다른
+책임입니다. Document Type이 model·schema·invariant·의미 연산·Projection을
+소유하고 Editing이 그 계약을 소비하는 구조를 지향합니다.
+[Document Types · TBD](document-types.md)에 현재 후보와 남은 소유권 수렴을
+미리 드러냅니다. 기존 package/API의 존재만으로 이 목표가 완료되지는 않습니다.
 
 ## Artifact에 손을 붙이기
 
@@ -85,11 +94,16 @@ Editing은 이 상태를 JSON Document 옆에 둡니다. 화면은 클릭과 키
 제품처럼 보입니다. 그 아래에서는 같은 문서와 같은 편집 상태를 씁니다.
 다른 것은 그 장르가 손을 얹는 방식입니다.
 
-Hands는 사람이 artifact와 agent를 다루는 편집 도구의 최소 완성본입니다.
+Hands는 사람이 artifact와 agent를 다루는 장르별 편집 조합입니다.
 한 줄 목록을 집어 옮기는 손, 칸을 채우는 손, 가지를 접는 손이 선반에
 있습니다. Agent에게 지시와 맥락을 건네는 Composer와, 안정적인 대상을 글에
 넣는 Mention도 Rich Text와 구조화된 context로 동작합니다. 고르려면 [Hands](hands.md)로 갑니다.
 
+[Official Hands · TBD](official-hands.md)는 이 조합을 기본 편집이 완성된 SDK로
+제공하려는 목표입니다. 전체 지원 입력·실패·선택 복원·호환성 조건은 아직 닫히지
+않았습니다. [Artifact](/viewer)도 현재는 visual prototype이며 문서·Hands 연결과
+파일 호환성을 증명하지 않습니다.
+
 ## 플랫폼, 라이브러리, Affordance
 
 브라우저에서 쓰려면 키보드와 clipboard, contenteditable 같은 플랫폼
@@ -102,12 +116,13 @@ React로 그리거나 Zod로 검사하려면 이름 있는 라이브러리의 
 React 구독으로 흐르고, 표의 보이는 행과 열은 Sheet의 Topology가 됩니다.
 
 고르기, 접기, 드래그, 되돌리기는 제품이 json-document를 만지는 손입니다.
-화면은 호스트가 그리고, 단축키와 마우스 문법은 Affordance가 닫습니다.
+제품 화면은 Host가 조합하고, 플랫폼 사실은 Adapter가 해석하며,
+입력 장치와 독립적인 조작 의미·수명주기는 Affordance가 소유합니다.
 
 Adapter와 Connector는 서로 직렬인 계층이 아니라 환경에 따라 독립적으로
 고르는 책임입니다. Affordance도 필요한 입력 문법을 선택해 Host에 조합합니다.
-[Adapters](adapters.md)와 [Connectors](connectors.md),
-[Affordance](affordance.md)에서 이어서 읽습니다.
+[Building Blocks](building-blocks.md)에서 Adapter·Connector·Affordance·
+UI Primitives의 경계를 함께 봅니다.
 
 ## Artifact editing의 Core
 
@@ -118,5 +133,5 @@ Connector, Affordance와 UI Primitive는 필요한 환경과 입력 문법에 
 Hands는 그 조합이 장르별 최소 편집 loop를 완성했는지 판정합니다.
 
 여러 artifact가 같은 주소와 실행 취소와 협업을 쓰게 하려는 자리가 이
-Core입니다. 각 책임의 경계와 의존 순서는 [Concept Map](concepts.md)에서
+Core입니다. 각 책임의 경계와 선택적인 의존 관계는 [Concept Map](concepts.md)에서
 이어집니다.
diff --git a/packages/json-document-editing/README.md b/packages/json-document-editing/README.md
index eef05856..d1a050a4 100644
--- a/packages/json-document-editing/README.md
+++ b/packages/json-document-editing/README.md
@@ -119,10 +119,10 @@ Its structural selection slices split into two reusable families without
 pretending that every topology is the same:
 
 - `Document`, `Order`, `Sheet`, and `Tree` use the range family.
-  Their host or domain slice supplies ordered axes, visible order, and JSON
-  Patch planning.
-- `Object` uses the key family. The host owns pointer
-  geometry and hit-testing, then sends only stable object IDs to the editor.
+  Ordered axes, visible projections and JSON Patch planning come from the
+  canonical document/editor or external-model connector.
+- `Object` uses the key family. Canonical platform geometry and hit-testing
+  APIs supply stable object IDs to the editor; the Host composes that path.
   Its public `selection.set` accepts the shared `replace`, `extend`, and
   `toggle` vocabulary directly; `extend` has key-family union semantics.
 
diff --git a/packages/json-document-selection/README.md b/packages/json-document-selection/README.md
index 935a6cea..819e5497 100644
--- a/packages/json-document-selection/README.md
+++ b/packages/json-document-selection/README.md
@@ -6,7 +6,10 @@ DOM-free selection families and semantic interaction controllers for structural
 
 The package owns JSON-safe selection state, pure family transitions, reconciliation/mapping, target publication, and pointer/keyboard interaction lifecycles after physical input has been translated into semantic operations.
 
-The host owns DOM or canvas geometry, hit testing implementation, modifier-key mapping, focus and accessibility wiring, native text caret/IME state, and domain edits such as delete, move, fill, and paste.
+플랫폼 geometry 관찰·hit testing·modifier 해석·DOM focus·native caret/IME는
+Adapter와 해당 UI owner가, delete·move·fill·paste의 의미는 문서·Editing owner가
+소유합니다. Host는 제품 정책 값과 구체 인스턴스·layout을 조합하며 이 책임을
+직접 재구현하지 않습니다.
 
 ```text
 platform adapter ─┐
@@ -19,7 +22,7 @@ editing history ──┘
 - `KeySelection`: explicit keys or symbolic `all` with exclusions and a host-issued universe token.
 - `RangeSelection`: directional anchor/focus ranges over a host-provided `OrderedTopology`.
 - `MaterializedRangeSelection`: directional ranges whose resolved points survive virtualized or paged topology changes. Each range keeps its anchor/focus and the points produced by the topology at transition time; reconciliation removes only identities that the topology no longer recognizes.
-- `MaskSelection`: an extension protocol whose weighted representation and algebra remain host-owned.
+- `MaskSelection`: an extension protocol whose weighted representation and algebra belong to the implementing document/editor owner, not anonymous Host logic.
 
 These families share `SelectionFamily`; they do not share a universal reducer.
 
@@ -30,11 +33,9 @@ Use `createMaterializedRangeSelectionFamily` when the visible topology can chang
 Translate physical input before calling the package:
 
 ```ts
-const operation: SelectionOperation = event.shiftKey
-  ? "extend"
-  : event.metaKey || event.ctrlKey
-    ? "toggle"
-    : "replace";
+import { selectionOperationFromModifiers } from "@interactive-os/json-document-web";
+
+const operation = selectionOperationFromModifiers(event);
 ```
 
 Viewport-to-domain coordinate conversion, pointer capture, auto-scroll, and accessibility remain in the adapter. Pass only `PointerSample<Point>` values to `reducePressInteraction` or `reduceMarqueeInteraction`.
diff --git a/packages/json-document-web/README.md b/packages/json-document-web/README.md
index ac5dfe8d..29aa0cb0 100644
--- a/packages/json-document-web/README.md
+++ b/packages/json-document-web/README.md
@@ -68,8 +68,9 @@ const dragDrop = createWebDragDropSession({
 });
 ```
 
-The sessions own platform lifecycle state. Hit testing, valid targets, geometry,
-and document Intent remain in the host.
+세션은 플랫폼 수명주기를 소유합니다. Hit testing과 geometry의 플랫폼 관찰,
+유효 대상과 문서 Intent의 의미는 각각 Adapter와 문서·Editing owner의 계약을
+소비합니다. Host는 제품의 대상·정책 값과 실행 경로를 연결합니다.
 
 `createWebViewportPositionPorts` measures an exact target and its paired tail
 reserve, writes temporary scroll range, performs smooth or instant positioning,
@@ -118,12 +119,12 @@ const keyboard = createWebKeyboardAdapter();
 
 surface.addEventListener("click", (event) => {
   const operation = selectionOperationFromModifiers(event);
-  // The host resolves geometry and dispatches its domain selection intent.
+  // Connect canonical geometry/selection APIs with the product's target.
 });
 
 surface.addEventListener("keydown", (event) => {
   const command = keyboard.resolve(event);
-  // Official adapter output. The host maps it through topology to a domain intent.
+  // Pass the command to the canonical topology/editor API.
 });
 
 input.addEventListener("input", (event) => {
@@ -148,18 +149,19 @@ named codecs remain compatibility aliases over those domain formats. Clipboard
 surfaces write both the structured json-document MIME payload and its
 `text/plain` projection. Paste
 consumes only a valid structured payload. Parsing arbitrary external plain text
-into domain records or cells remains a host policy.
+into domain records or cells belongs to the document/editor's format contract.
+The Host chooses which representations and product policies to enable.
 
 The official keyboard adapter owns `defaultWebKeymap`. `resolve` returns a
 semantic command or `null`; `moveLinePoint` and `moveGridPoint` locate the
 visible neighbor. The host still decides when a command applies and which
 domain Intent to dispatch.
 
-The clipboard binding calls `preventDefault()` only after a successful copy,
-canonical cut, or canonical paste. Cut writes the selected payload before
-asking the Editing companion to remove it. Missing clipboard data, malformed
-payloads, unsupported cut, and rejected editing results leave native handling
-available.
+Cut writes the selected payload before asking Editing to remove it. Once a
+Cut payload is owned, native deletion is cancelled before removal; a rejected
+removal must not trigger another browser deletion. Copy/Paste cancel native
+handling on success. Missing data and unsupported input follow the specific
+failure boundary below.
 
 `createWebClipboardSurface` is the public surface-level orchestration API. It
 projects one binding into `onCopy`, `onCut`, and `onPaste` handlers and reports
@@ -187,11 +189,16 @@ The Adapter owns:
 
 The host owns:
 
-- the event target, canonical focus, when a command applies, and role workflow policy;
-- DOM/canvas geometry and hit testing;
-- external plain-text interpretation and product-specific paste policy;
+- product-specific activation, permissions, and workflow policy;
+- concrete DOM/external instances and visual composition;
+- selection of canonical geometry, editor, focus, and clipboard APIs;
+- product-specific paste policy values;
 - enabled representations and their priority;
-- native text selection, IME, drag/drop, persistence, and remote protocols.
+- composition and execution order of persistence and remote-system integrations.
+
+Native text selection, IME, drag/drop lifecycle, serialization, and reusable UI
+behavior remain at their canonical Adapter, Affordance, Connector, or UI owner.
+Host composition is not an exemption from those module boundaries.
 
 The module does not access `window`, `document`, or `navigator` during import,
 so non-browser tooling can load it safely.
diff --git a/packages/json-document/README.md b/packages/json-document/README.md
index d4247e27..d5f1962d 100644
--- a/packages/json-document/README.md
+++ b/packages/json-document/README.md
@@ -200,15 +200,22 @@ const body = JSON.stringify(operations);
 body satisfies string;
 ```
 
-## Connector와 host 경계
+## 생태계와 Host 경계
 
 Form, data-grid, outliner, rich text, persistence/collaboration extension은 여섯
-member `JSONDocument`를 포트로 받는 것이 권장됩니다. DOM focus, geometry,
-keyboard, system clipboard, filesystem, network, formula, CRDT와 OT는 host가
-소유합니다.
+member `JSONDocument`를 포트로 받습니다. 문서 고유 모델·의미 연산·Projection은
+Document Type, 선택·작업·History는 Editing, 플랫폼 입력과 DOM lifecycle은
+Adapter의 책임입니다. 이 기능을 Core나 Host에 재구현하지 않습니다.
 
 React, Zod와 TanStack Table 같은 외부 생태계의 반복되는 integration은 Root가
 아니라 `@interactive-os/json-document-<target>` 공식 Connector가 제공합니다.
+Host는 제품 정책 값·copy·fixture·layout, 정본 모듈의 조합·실행 순서와
+구체 외부 인스턴스 주입을 소유합니다.
 
-- GitHub Wiki: https://github.com/developer-1px/json-document/wiki
-- Extension guide: https://github.com/developer-1px/json-document/wiki/Labs-and-Extensions
+현재 package 배치와 목표 책임의 수렴은 구별합니다. Document Type 후보와
+Official Hands Profile의 전체 완료는 아직 TBD이며 Core v3의 Stable 계약을
+확장하지 않습니다.
+
+- [Concept Map](../../docs/public/concepts.md)
+- [Building Blocks](../../docs/public/building-blocks.md)
+- [Document Types · TBD](../../docs/public/document-types.md)
diff --git a/scripts/generate-api-reference.mjs b/scripts/generate-api-reference.mjs
index d3595a2d..b91ab3a7 100644
--- a/scripts/generate-api-reference.mjs
+++ b/scripts/generate-api-reference.mjs
@@ -2,14 +2,15 @@ import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import ts from "typescript";
-import { apiReferencePackages } from "../docs/api-reference/packages.mjs";
+import { apiReferenceCoverageErrors, apiReferencePackages } from "../docs/api-reference/packages.mjs";
 
 const root = dirname(dirname(fileURLToPath(import.meta.url)));
 const check = process.argv.includes("--check");
 const configPath = join(root, "tsconfig.build.json");
 const parsed = ts.parseJsonConfigFileContent(ts.readConfigFile(configPath, ts.sys.readFile).config, ts.sys, root);
 const entrypoints = apiReferencePackages.flatMap(({ entrypoint, subpaths }) => [entrypoint, ...subpaths.map((subpath) => subpath.entrypoint)]).map((entrypoint) => join(root, entrypoint));
-const sourcePaths = Object.fromEntries(apiReferencePackages.map(({ packageName, entrypoint }) => [packageName, [entrypoint]]));
+const sourcePaths = Object.fromEntries(apiReferencePackages.flatMap((descriptor) =>
+  [descriptor, ...descriptor.subpaths].map(({ packageName, entrypoint }) => [packageName, [entrypoint]])));
 const program = ts.createProgram([...new Set([...parsed.fileNames, ...entrypoints])], {
   ...parsed.options,
   baseUrl: root,
@@ -20,7 +21,9 @@ const program = ts.createProgram([...new Set([...parsed.fileNames, ...entrypoint
   noEmit: true,
 });
 const checker = program.getTypeChecker();
-const failures = [];
+const manifests = JSON.parse(readFileSync(join(root, "package.json"), "utf8")).workspaces
+  .map((workspace) => JSON.parse(readFileSync(join(root, workspace, "package.json"), "utf8")));
+const failures = apiReferenceCoverageErrors(manifests);
 let exportCount = 0;
 const siteRoutes = JSON.parse(readFileSync(join(root, "site/site-routes.json"), "utf8"));
 
@@ -60,8 +63,11 @@ function clean(signature) {
 
 for (const descriptor of apiReferencePackages) {
   const referencePath = `/docs/api/${descriptor.slug}`;
-  const ownerRoutes = siteRoutes.filter((route) => route.path === referencePath && route.navigationGroup === descriptor.owner);
-  if (ownerRoutes.length !== 1) failures.push(`${descriptor.packageName} owner route`);
+  const referenceRoutes = siteRoutes.filter((route) =>
+    route.path === referencePath
+    && route.navigationGroup === descriptor.navigationGroup
+    && route.documentSource === `docs/api-reference/${descriptor.slug}.md`);
+  if (referenceRoutes.length !== 1) failures.push(`${descriptor.packageName} owner reference route`);
   const entry = program.getSourceFile(join(root, descriptor.entrypoint));
   if (!entry) throw new Error(`public entrypoint를 찾을 수 없습니다: ${descriptor.entrypoint}`);
   const moduleSymbol = checker.getSymbolAtLocation(entry);
@@ -89,9 +95,9 @@ for (const descriptor of apiReferencePackages) {
   const output = [
     `# ${descriptor.packageName} API`,
     "",
-    `**Owner:** ${descriptor.owner}`,
+    `**탐색 분류:** ${descriptor.navigationGroup}`,
     "",
-    `${descriptor.responsibility}의 public entrypoint입니다. 아래 항목은 package root에서 import할 수 있는 안정된 public API이며 internal 경로는 계약이 아닙니다.`,
+    `${descriptor.responsibility}의 public entrypoint입니다. API의 owner는 이 package이며 탐색 분류는 사이트에서 읽는 위치입니다. 별도 subpath 표시가 없는 항목은 package root에서 import합니다. internal 경로는 계약이 아닙니다.`,
     "",
     `> 이 문서는 \`${descriptor.entrypoint}\`에서 생성됩니다. API를 변경한 뒤 \`npm run docs:api\`를 실행하세요.`,
     "",
diff --git a/site/scripts/check-documentation-page.mjs b/site/scripts/check-documentation-page.mjs
index 2d3c047f..eefdbd4b 100644
--- a/site/scripts/check-documentation-page.mjs
+++ b/site/scripts/check-documentation-page.mjs
@@ -4,7 +4,7 @@ import { join } from "node:path";
 const root = new URL("../..", import.meta.url).pathname;
 const docsRoot = join(root, "site/src/routes/docs");
 const canonicalOwner = "DocumentationPage.tsx";
-const consumers = ["DocsRoute.tsx", "ConceptsRoute.tsx", "DocumentTypeCandidateRoute.tsx"];
+const consumers = ["DocsRoute.tsx", "DocumentTypeCandidateRoute.tsx"];
 
 for (const name of readdirSync(docsRoot).filter((entry) => entry.endsWith(".tsx"))) {
   const source = readFileSync(join(docsRoot, name), "utf8");
@@ -14,7 +14,7 @@ for (const name of readdirSync(docsRoot).filter((entry) => entry.endsWith(".tsx"
 }
 
 const owner = readFileSync(join(docsRoot, canonicalOwner), "utf8");
-for (const contract of ["PageFrame", "PageHeader", "MarkdownViewer", "markdownHeadings", "Documentation sections", "On this page", "max-w-3xl"]) {
+for (const contract of ["PageFrame", "PageHeader", "MarkdownViewer", "data-doc-heading", "Documentation sections", "On this page", "max-w-3xl"]) {
   if (!owner.includes(contract)) throw new Error(`DocumentationPage is missing canonical contract: ${contract}`);
 }
 for (const consumer of consumers) {
diff --git a/site/scripts/route-checks.mjs b/site/scripts/route-checks.mjs
index dc0b0835..9a11ee9e 100644
--- a/site/scripts/route-checks.mjs
+++ b/site/scripts/route-checks.mjs
@@ -53,6 +53,9 @@ export function validateSiteRoutes(routes, fail) {
     if (route.heading !== undefined && (typeof route.heading !== "string" || route.heading.trim() === "")) {
       fail(`site route ${route.path} has an invalid heading.`);
     }
+    if (route.documentSource !== undefined && !/^docs\/(?:public|api-reference)\/[^/]+\.md$/.test(route.documentSource)) {
+      fail(`site route ${route.path} has an invalid documentation source.`);
+    }
     if (route.chrome !== undefined && route.chrome !== "app") {
       fail(`site route ${route.path} has an invalid chrome.`);
     }
@@ -81,7 +84,8 @@ export function validateSiteRoutes(routes, fail) {
       files.add(file);
     }
 
-    const navigationLabel = `${route.navigationGroup ?? "hidden"}:${route.label}`;
+    const labelScope = route.parentPath ?? route.navigationGroup ?? (route.sidebar === false ? route.path : "root");
+    const navigationLabel = `${labelScope}:${route.label}`;
     if (labels.has(navigationLabel)) fail(`site navigation group contains duplicate label ${route.label}.`);
     labels.add(navigationLabel);
 
diff --git a/site/scripts/route-checks.test.mjs b/site/scripts/route-checks.test.mjs
new file mode 100644
index 00000000..ed84b930
--- /dev/null
+++ b/site/scripts/route-checks.test.mjs
@@ -0,0 +1,26 @@
+import { readFileSync } from "node:fs";
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { validateSiteRoutes } from "./route-checks.mjs";
+
+const root = { path: "/", label: "Home", title: "Home", description: "Home page" };
+const route = (path, extra = {}) => ({ path, title: path, description: `About ${path}`, label: "Overview", ...extra });
+const errors = (routes) => {
+  const failures = [];
+  validateSiteRoutes(routes, (failure) => failures.push(failure));
+  return failures;
+};
+
+test("validates the real site registry and separate section landings", () => {
+  assert.deepEqual(errors(JSON.parse(readFileSync(new URL("../site-routes.json", import.meta.url), "utf8"))), []);
+  assert.deepEqual(errors([root, route("/docs/foundation", { sidebar: false }), route("/docs/building-blocks", { sidebar: false })]), []);
+});
+
+test("rejects duplicate visible sibling labels and invalid documentation paths", () => {
+  assert.deepEqual(errors([root, route("/docs/one", { navigationGroup: "Editing" }), route("/docs/two", { navigationGroup: "Editing" })]), [
+    "site navigation group contains duplicate label Overview.",
+  ]);
+  assert.deepEqual(errors([root, route("/docs/one", { documentSource: "../private.md" })]), [
+    "site route /docs/one has an invalid documentation source.",
+  ]);
+});
diff --git a/site/site-routes.json b/site/site-routes.json
index 6fa7596e..fdcad414 100644
--- a/site/site-routes.json
+++ b/site/site-routes.json
@@ -7,10 +7,10 @@
   },
   {
     "path": "/viewer",
-    "label": "Document · Presentation · Spreadsheet",
-    "title": "Artifact - json-document",
-    "heading": "Artifact",
-    "description": "MD·PPT·Sheet artifact가 한 host에 나타나고 서로 다른 Hands를 얻는 미래의 mock입니다.",
+    "label": "Content Prototype · TBD",
+    "title": "Artifact · TBD - json-document",
+    "heading": "Artifact · TBD",
+    "description": "Application 안에서 MD·PPT·Sheet를 다루는 visual prototype과 아직 연결하지 않은 문서·Hands·호환성 계약을 구분합니다.",
     "language": "ko",
     "navigationGroup": "Artifact"
   },
@@ -19,9 +19,10 @@
     "label": "Why",
     "title": "json-document Docs - json-document",
     "heading": "왜 json-document인가",
-    "description": "문서·표·보드가 같은 JSON 계약을 쓰고, 협업과 장르의 손과 붙이는 층을 같은 커널 위에 올리는 이유를 설명합니다.",
+    "description": "문서·표·보드가 JSON Document 계약을 공유하고, 독립적인 편집·플랫폼·생태계 책임을 조합하는 이유를 설명합니다.",
     "language": "ko",
-    "navigationGroup": "Introduction"
+    "navigationGroup": "Introduction",
+    "documentSource": "docs/public/overview.md"
   },
   {
     "path": "/docs/foundation",
@@ -30,15 +31,17 @@
     "heading": "Foundation",
     "description": "JSON Document, Document Types, Editing과 Collaboration이 공유하는 기반 계약을 설명합니다.",
     "language": "ko",
-    "navigationGroup": "JSON Document"
+    "documentSource": "docs/public/foundation.md",
+    "sidebar": false
   },
   {
     "path": "/docs/concepts",
     "label": "Concept Map",
     "title": "Concept Map - json-document",
-    "description": "JSON Document에서 Artifact까지 책임이 쌓이는 순서와 각 계층의 경계를 설명합니다.",
+    "description": "목표 레이어·책임 경계와 실제 프로토콜을 구분하고, 현재 제공되는 계약과 TBD를 함께 설명합니다.",
     "language": "ko",
-    "navigationGroup": "Introduction"
+    "navigationGroup": "Introduction",
+    "documentSource": "docs/public/concepts.md"
   },
   {
     "path": "/docs/how-we-build",
@@ -47,7 +50,8 @@
     "heading": "제품에서 정본 모듈을 발견하는 방법",
     "description": "Application을 먼저 만들고 실제 제품 책임을 canonical module로 추출한 뒤 제품이 다시 소비하는 개발 순환을 설명합니다.",
     "language": "ko",
-    "navigationGroup": "Introduction"
+    "navigationGroup": "Introduction",
+    "documentSource": "docs/public/how-we-build.md"
   },
   {
     "path": "/applications",
@@ -56,7 +60,8 @@
     "heading": "Applications",
     "description": "Artifact와 Hands를 실제 제품 경험으로 조합하고 재사용 책임을 발견하는 Application 목록입니다.",
     "language": "ko",
-    "navigationGroup": "Applications"
+    "navigationGroup": "Applications",
+    "documentSource": "docs/public/applications.md"
   },
   {
     "path": "/applications/calendar",
@@ -76,6 +81,16 @@
     "navigationGroup": "Applications",
     "chrome": "app"
   },
+  {
+    "path": "/docs/building-blocks",
+    "label": "Overview",
+    "title": "Building Blocks - json-document",
+    "heading": "Building Blocks",
+    "description": "Adapter·Connector·Affordance·UI Primitives의 독립적인 책임과 Foundation·Hands를 연결하는 계약을 설명합니다.",
+    "language": "ko",
+    "sidebar": false,
+    "documentSource": "docs/public/building-blocks.md"
+  },
   {
     "path": "/docs/document-types",
     "label": "Overview · TBD",
@@ -83,7 +98,8 @@
     "heading": "Document Types · TBD",
     "description": "JSON Document의 의미 모델을 소유하는 Document Type 책임과 아직 확정하지 않은 후보를 정리합니다.",
     "language": "ko",
-    "navigationGroup": "Document Types"
+    "navigationGroup": "Document Types",
+    "documentSource": "docs/public/document-types.md"
   },
   {
     "path": "/docs/document-types/rich-text",
@@ -159,12 +175,13 @@
   },
   {
     "path": "/docs/api",
-    "label": "API Reference",
-    "title": "json-document API - json-document",
-    "heading": "json-document API",
-    "description": "여섯 가지 JSON Document 진입점과 JSON Patch, Pointer, JSONPath 공개 API를 정리합니다.",
+    "label": "JSON Document Protocol",
+    "title": "JSON Document Protocol - json-document",
+    "heading": "JSON Document Protocol",
+    "description": "로컬·협업 구현이 공유하는 여섯 member의 JSONDocument 계약과 JSON 표준 연산 API를 설명합니다.",
     "language": "ko",
-    "navigationGroup": "JSON Document"
+    "navigationGroup": "JSON Document",
+    "documentSource": "docs/public/api.md"
   },
   {
     "path": "/docs/api/json-document",
@@ -172,7 +189,8 @@
     "title": "JSON Document public API - json-document",
     "description": "@interactive-os/json-document의 전체 public export와 signature입니다.",
     "language": "ko",
-    "navigationGroup": "JSON Document"
+    "navigationGroup": "JSON Document",
+    "documentSource": "docs/api-reference/json-document.md"
   },
   {
     "path": "/docs/api/selection",
@@ -180,7 +198,8 @@
     "title": "Selection API - json-document",
     "description": "@interactive-os/json-document-selection의 전체 public API입니다.",
     "language": "ko",
-    "navigationGroup": "Editing"
+    "navigationGroup": "Editing",
+    "documentSource": "docs/api-reference/selection.md"
   },
   {
     "path": "/docs/api/editing",
@@ -188,7 +207,8 @@
     "title": "Editing API - json-document",
     "description": "@interactive-os/json-document-editing의 전체 public API입니다.",
     "language": "ko",
-    "navigationGroup": "Editing"
+    "navigationGroup": "Editing",
+    "documentSource": "docs/api-reference/editing.md"
   },
   {
     "path": "/docs/api/rich-text",
@@ -196,7 +216,8 @@
     "title": "Rich Text API - json-document",
     "description": "@interactive-os/json-document-rich-text의 전체 public API입니다.",
     "language": "ko",
-    "navigationGroup": "Editing"
+    "navigationGroup": "Editing",
+    "documentSource": "docs/api-reference/rich-text.md"
   },
   {
     "path": "/docs/api/file-intake",
@@ -204,7 +225,8 @@
     "title": "File Intake API - json-document",
     "description": "@interactive-os/json-document-file-intake의 전체 public API입니다.",
     "language": "ko",
-    "navigationGroup": "Artifact"
+    "navigationGroup": "Artifact",
+    "documentSource": "docs/api-reference/file-intake.md"
   },
   {
     "path": "/docs/api/rich-text-mention",
@@ -212,7 +234,8 @@
     "title": "Rich Text Mention API - json-document",
     "description": "@interactive-os/json-document-rich-text-mention의 전체 public API입니다.",
     "language": "ko",
-    "navigationGroup": "Hands"
+    "navigationGroup": "Hands",
+    "documentSource": "docs/api-reference/rich-text-mention.md"
   },
   {
     "path": "/docs/api/rich-text-suggestion",
@@ -220,7 +243,8 @@
     "title": "Rich Text Suggestion API - json-document",
     "description": "@interactive-os/json-document-rich-text-suggestion의 전체 public API입니다.",
     "language": "ko",
-    "navigationGroup": "Hands"
+    "navigationGroup": "Hands",
+    "documentSource": "docs/api-reference/rich-text-suggestion.md"
   },
   {
     "path": "/docs/api/rich-text-suggestion-react",
@@ -228,7 +252,8 @@
     "title": "Rich Text Suggestion React API - json-document",
     "description": "@interactive-os/json-document-rich-text-suggestion-react의 전체 public API입니다.",
     "language": "ko",
-    "navigationGroup": "Hands"
+    "navigationGroup": "Hands",
+    "documentSource": "docs/api-reference/rich-text-suggestion-react.md"
   },
   {
     "path": "/docs/api/rich-text-mention-react",
@@ -236,7 +261,8 @@
     "title": "Rich Text Mention React API - json-document",
     "description": "@interactive-os/json-document-rich-text-mention-react의 전체 public API입니다.",
     "language": "ko",
-    "navigationGroup": "Hands"
+    "navigationGroup": "Hands",
+    "documentSource": "docs/api-reference/rich-text-mention-react.md"
   },
   {
     "path": "/docs/api/composer",
@@ -244,7 +270,8 @@
     "title": "Composer API - json-document",
     "description": "@interactive-os/json-document-composer의 전체 public API입니다.",
     "language": "ko",
-    "navigationGroup": "Hands"
+    "navigationGroup": "Hands",
+    "documentSource": "docs/api-reference/composer.md"
   },
   {
     "path": "/docs/api/composer-react",
@@ -252,7 +279,8 @@
     "title": "Composer React API - json-document",
     "description": "@interactive-os/json-document-composer-react의 전체 public API입니다.",
     "language": "ko",
-    "navigationGroup": "Hands"
+    "navigationGroup": "Hands",
+    "documentSource": "docs/api-reference/composer-react.md"
   },
   {
     "path": "/docs/api/web",
@@ -260,7 +288,8 @@
     "title": "Web API - json-document",
     "description": "@interactive-os/json-document-web의 전체 public API입니다.",
     "language": "ko",
-    "navigationGroup": "Adapter"
+    "navigationGroup": "Adapter",
+    "documentSource": "docs/api-reference/web.md"
   },
   {
     "path": "/docs/api/contenteditable",
@@ -268,7 +297,8 @@
     "title": "Contenteditable API - json-document",
     "description": "@interactive-os/json-document-contenteditable의 전체 public API입니다.",
     "language": "ko",
-    "navigationGroup": "Adapter"
+    "navigationGroup": "Adapter",
+    "documentSource": "docs/api-reference/contenteditable.md"
   },
   {
     "path": "/docs/api/rich-text-web",
@@ -276,7 +306,8 @@
     "title": "Rich Text Web API - json-document",
     "description": "@interactive-os/json-document-rich-text-web의 전체 public API입니다.",
     "language": "ko",
-    "navigationGroup": "Adapter"
+    "navigationGroup": "Adapter",
+    "documentSource": "docs/api-reference/rich-text-web.md"
   },
   {
     "path": "/docs/api/react",
@@ -284,7 +315,8 @@
     "title": "React API - json-document",
     "description": "@interactive-os/json-document-react의 전체 public API입니다.",
     "language": "ko",
-    "navigationGroup": "Connector"
+    "navigationGroup": "Connector",
+    "documentSource": "docs/api-reference/react.md"
   },
   {
     "path": "/docs/api/react-hook-form",
@@ -292,7 +324,8 @@
     "title": "React Hook Form API - json-document",
     "description": "@interactive-os/json-document-react-hook-form의 전체 public API입니다.",
     "language": "ko",
-    "navigationGroup": "Connector"
+    "navigationGroup": "Connector",
+    "documentSource": "docs/api-reference/react-hook-form.md"
   },
   {
     "path": "/docs/api/ajv",
@@ -300,7 +333,8 @@
     "title": "Ajv API - json-document",
     "description": "@interactive-os/json-document-ajv의 전체 public API입니다.",
     "language": "ko",
-    "navigationGroup": "Connector"
+    "navigationGroup": "Connector",
+    "documentSource": "docs/api-reference/ajv.md"
   },
   {
     "path": "/docs/api/a2ui",
@@ -308,7 +342,8 @@
     "title": "A2UI API - json-document",
     "description": "@interactive-os/json-document-a2ui의 전체 public API입니다.",
     "language": "ko",
-    "navigationGroup": "Connector"
+    "navigationGroup": "Connector",
+    "documentSource": "docs/api-reference/a2ui.md"
   },
   {
     "path": "/docs/connector-a2ui",
@@ -316,7 +351,8 @@
     "title": "A2UI Connector - json-document",
     "description": "A2UI 메시지와 JSONL을 JSONDocument로 연결합니다.",
     "language": "ko",
-    "navigationGroup": "Connector"
+    "navigationGroup": "Connector",
+    "documentSource": "docs/public/connector-a2ui.md"
   },
   {
     "path": "/docs/api/zod",
@@ -324,7 +360,8 @@
     "title": "Zod API - json-document",
     "description": "@interactive-os/json-document-zod의 전체 public API입니다.",
     "language": "ko",
-    "navigationGroup": "Connector"
+    "navigationGroup": "Connector",
+    "documentSource": "docs/api-reference/zod.md"
   },
   {
     "path": "/docs/api/tanstack-table",
@@ -332,7 +369,8 @@
     "title": "TanStack Table API - json-document",
     "description": "@interactive-os/json-document-tanstack-table의 전체 public API입니다.",
     "language": "ko",
-    "navigationGroup": "Connector"
+    "navigationGroup": "Connector",
+    "documentSource": "docs/api-reference/tanstack-table.md"
   },
   {
     "path": "/docs/api/rich-text-react",
@@ -340,7 +378,8 @@
     "title": "Rich Text React API - json-document",
     "description": "@interactive-os/json-document-rich-text-react의 전체 public API입니다.",
     "language": "ko",
-    "navigationGroup": "Connector"
+    "navigationGroup": "Connector",
+    "documentSource": "docs/api-reference/rich-text-react.md"
   },
   {
     "path": "/docs/api/affordance",
@@ -348,7 +387,8 @@
     "title": "Affordance API - json-document",
     "description": "@interactive-os/json-document-affordance의 전체 public API입니다.",
     "language": "ko",
-    "navigationGroup": "Affordance"
+    "navigationGroup": "Affordance",
+    "documentSource": "docs/api-reference/affordance.md"
   },
   {
     "path": "/docs/api/ui-primitives-react",
@@ -356,7 +396,8 @@
     "title": "UI Primitives API - json-document",
     "description": "@interactive-os/json-document-ui-primitives-react의 전체 public API입니다.",
     "language": "ko",
-    "navigationGroup": "UI Primitives"
+    "navigationGroup": "UI Primitives",
+    "documentSource": "docs/api-reference/ui-primitives-react.md"
   },
   {
     "path": "/docs/api/animation-react",
@@ -364,7 +405,8 @@
     "title": "Animation API - json-document",
     "description": "@interactive-os/json-document-animation-react의 전체 public API입니다.",
     "language": "ko",
-    "navigationGroup": "UI Primitives"
+    "navigationGroup": "UI Primitives",
+    "documentSource": "docs/api-reference/animation-react.md"
   },
   {
     "path": "/docs/api/markdown-react",
@@ -374,7 +416,8 @@
     "language": "ko",
     "navigationGroup": "Artifact",
     "relatedDemoPath": "/demo/markdown",
-    "relatedDemoLabel": "Streaming Markdown"
+    "relatedDemoLabel": "Streaming Markdown",
+    "documentSource": "docs/api-reference/markdown-react.md"
   },
   {
     "path": "/demo/markdown",
@@ -402,7 +445,8 @@
     "title": "Database API - json-document",
     "description": "@interactive-os/json-document-database의 전체 public API입니다.",
     "language": "ko",
-    "navigationGroup": "Hands"
+    "navigationGroup": "Hands",
+    "documentSource": "docs/api-reference/database.md"
   },
   {
     "path": "/docs/api/annotation",
@@ -410,7 +454,8 @@
     "title": "Annotation API - json-document",
     "description": "@interactive-os/json-document-annotation의 전체 public API입니다.",
     "language": "ko",
-    "navigationGroup": "Hands"
+    "navigationGroup": "Hands",
+    "documentSource": "docs/api-reference/annotation.md"
   },
   {
     "path": "/docs/api/calendar",
@@ -418,7 +463,8 @@
     "title": "Calendar API - json-document",
     "description": "@interactive-os/json-document-calendar의 전체 public API입니다.",
     "language": "ko",
-    "navigationGroup": "Hands"
+    "navigationGroup": "Hands",
+    "documentSource": "docs/api-reference/calendar.md"
   },
   {
     "path": "/docs/api/collaboration",
@@ -426,7 +472,8 @@
     "title": "Collaboration API - json-document",
     "description": "@interactive-os/json-document-collaboration의 전체 public API입니다.",
     "language": "ko",
-    "navigationGroup": "Collaboration"
+    "navigationGroup": "Collaboration",
+    "documentSource": "docs/api-reference/collaboration.md"
   },
   {
     "path": "/docs/api/contenteditable-collaboration",
@@ -434,17 +481,18 @@
     "title": "Contenteditable Collaboration API - json-document",
     "description": "@interactive-os/json-document-contenteditable-collaboration의 전체 public API입니다.",
     "language": "ko",
-    "navigationGroup": "Collaboration"
+    "navigationGroup": "Collaboration",
+    "documentSource": "docs/api-reference/contenteditable-collaboration.md"
   },
   {
     "path": "/docs/collaboration",
-    "label": "Collaboration",
+    "label": "Overview",
     "title": "Collaboration - json-document",
     "heading": "Collaboration",
     "description": "같은 JSON Document 계약을 여러 참여자의 인과 변경으로 수렴시킵니다.",
     "language": "ko",
     "navigationGroup": "Collaboration",
-    "sidebar": false
+    "documentSource": "docs/public/collaboration.md"
   },
   {
     "path": "/docs/collaboration/replica",
@@ -453,7 +501,8 @@
     "heading": "Replica",
     "description": "한 참여자가 소유한 인과 상태와 아직 적용하지 못한 변경을 설명합니다.",
     "language": "ko",
-    "navigationGroup": "Collaboration"
+    "navigationGroup": "Collaboration",
+    "documentSource": "docs/public/collaboration-replica.md"
   },
   {
     "path": "/docs/collaboration/lifecycle",
@@ -462,7 +511,8 @@
     "heading": "Lifecycle",
     "description": "epoch, checkpoint, restore, compaction이 협업 세대를 접고 되돌리는 방식을 설명합니다.",
     "language": "ko",
-    "navigationGroup": "Collaboration"
+    "navigationGroup": "Collaboration",
+    "documentSource": "docs/public/collaboration-lifecycle.md"
   },
   {
     "path": "/docs/collaboration/history",
@@ -471,7 +521,8 @@
     "heading": "Collaborative History",
     "description": "다른 참여자를 덮어쓰지 않고 현재 참여자의 인과 기여를 끄거나 켭니다.",
     "language": "ko",
-    "navigationGroup": "Collaboration"
+    "navigationGroup": "Collaboration",
+    "documentSource": "docs/public/collaboration-history.md"
   },
   {
     "path": "/docs/collaboration/text",
@@ -480,7 +531,8 @@
     "heading": "Collaborative Text",
     "description": "같이 쓰는 문자열의 안정된 글자 단위와 상대 위치를 설명합니다.",
     "language": "ko",
-    "navigationGroup": "Collaboration"
+    "navigationGroup": "Collaboration",
+    "documentSource": "docs/public/collaboration-text.md"
   },
   {
     "path": "/docs/collaboration/text/lease",
@@ -489,7 +541,18 @@
     "heading": "Contenteditable lease",
     "description": "협업 문자열이 입력 중에도 인과 변경을 멈추지 않게 하는 native-input DOM lease를 설명합니다.",
     "language": "ko",
-    "parentPath": "/docs/collaboration/text"
+    "parentPath": "/docs/collaboration/text",
+    "documentSource": "docs/public/collaboration-lease.md"
+  },
+  {
+    "path": "/docs/editing",
+    "label": "Editing Protocol",
+    "title": "Editing Protocol - json-document",
+    "heading": "Editing Protocol",
+    "description": "Intent, EditingPlan, EditingSession과 EditingSnapshot의 현재 계약 및 아직 동결하지 않은 Hands Profile을 설명합니다.",
+    "language": "ko",
+    "navigationGroup": "Editing",
+    "documentSource": "docs/public/editing.md"
   },
   {
     "path": "/docs/intent-guide",
@@ -498,7 +561,8 @@
     "heading": "Editor와 Intent 만들기",
     "description": "Document editor를 만들고 요청을 EditingIntent로 표현해 EditingResult를 처리합니다.",
     "language": "ko",
-    "navigationGroup": "Editing"
+    "navigationGroup": "Editing",
+    "documentSource": "docs/public/intent-guide.md"
   },
   {
     "path": "/docs/intent",
@@ -507,7 +571,8 @@
     "heading": "Intent 레퍼런스",
     "description": "EditingIntent, dispatch, EditingResult와 editor별 Intent의 공개 시그니처를 정리합니다.",
     "language": "ko",
-    "navigationGroup": "Editing"
+    "navigationGroup": "Editing",
+    "documentSource": "docs/public/intent.md"
   },
   {
     "path": "/docs/topology",
@@ -517,7 +582,8 @@
     "description": "Selection과 Clipboard가 공유하는 화면 순서인 LineTopology와 GridTopology를 설명합니다.",
     "language": "ko",
     "navigationGroup": "Editing",
-    "relatedDemoPath": "/demo/topology"
+    "relatedDemoPath": "/demo/topology",
+    "documentSource": "docs/public/topology.md"
   },
   {
     "path": "/demo/topology",
@@ -536,7 +602,8 @@
     "description": "문서 값을 바꾸지 않고 편집 대상을 기억하는 구조적 Selection을 설명합니다.",
     "language": "ko",
     "navigationGroup": "Editing",
-    "relatedDemoPath": "/demo/selection"
+    "relatedDemoPath": "/demo/selection",
+    "documentSource": "docs/public/selection.md"
   },
   {
     "path": "/demo/selection",
@@ -555,7 +622,8 @@
     "description": "현재 구조적 Selection에서 copy, cut, paste에 사용할 Clipboard payload를 만듭니다.",
     "language": "ko",
     "navigationGroup": "Editing",
-    "relatedDemoPath": "/demo/clipboard"
+    "relatedDemoPath": "/demo/clipboard",
+    "documentSource": "docs/public/clipboard.md"
   },
   {
     "path": "/demo/clipboard",
@@ -574,7 +642,8 @@
     "description": "document value와 구조적 Selection을 함께 복원하는 로컬 undo와 redo를 설명합니다.",
     "language": "ko",
     "navigationGroup": "Editing",
-    "relatedDemoPath": "/demo/history"
+    "relatedDemoPath": "/demo/history",
+    "documentSource": "docs/public/history.md"
   },
   {
     "path": "/demo/history",
@@ -601,7 +670,8 @@
     "heading": "Hands",
     "description": "닫힌 장르의 손과 TBD 손을 고릅니다.",
     "language": "ko",
-    "navigationGroup": "Hands"
+    "navigationGroup": "Hands",
+    "documentSource": "docs/public/hands.md"
   },
   {
     "path": "/docs/official-hands",
@@ -610,7 +680,8 @@
     "heading": "Official Hands · TBD",
     "description": "디자인과 제품 데이터는 자유롭게 유지하면서 수렴된 편집 기능을 완성된 SDK로 제공하는 방향을 설명합니다.",
     "language": "ko",
-    "navigationGroup": "Hands"
+    "navigationGroup": "Hands",
+    "documentSource": "docs/public/official-hands.md"
   },
   {
     "path": "/demo",
@@ -637,7 +708,8 @@
     "description": "한 줄 목록을 범위 선택으로 집고 옮기는 Order editor를 설명합니다.",
     "language": "ko",
     "navigationGroup": "Hands",
-    "relatedDemoPath": "/demo/order"
+    "relatedDemoPath": "/demo/order",
+    "documentSource": "docs/public/order.md"
   },
   {
     "path": "/demo/order",
@@ -655,7 +727,8 @@
     "description": "안정된 객체 ID를 키 가족으로 집는 Object editor를 설명합니다.",
     "language": "ko",
     "navigationGroup": "Hands",
-    "relatedDemoPath": "/demo/object"
+    "relatedDemoPath": "/demo/object",
+    "documentSource": "docs/public/object.md"
   },
   {
     "path": "/demo/object",
@@ -698,7 +771,8 @@
     "description": "호스트가 만든 보이는 노드 줄에서 범위를 집는 Tree editor를 설명합니다.",
     "language": "ko",
     "navigationGroup": "Hands",
-    "relatedDemoPath": "/demo/tree"
+    "relatedDemoPath": "/demo/tree",
+    "documentSource": "docs/public/tree.md"
   },
   {
     "path": "/demo/tree",
@@ -743,7 +817,8 @@
     "language": "ko",
     "navigationGroup": "UI Primitives",
     "relatedDemoPath": "/demo/animation",
-    "relatedDemoLabel": "Animation"
+    "relatedDemoLabel": "Animation",
+    "documentSource": "docs/public/animation.md"
   },
   {
     "path": "/demo/animation",
@@ -763,7 +838,8 @@
     "description": "저장된 Table view가 순서·숨김·너비·정렬·필터를 투사하는 Database editor를 설명합니다.",
     "language": "ko",
     "navigationGroup": "Hands",
-    "relatedDemoPath": "/demo/database"
+    "relatedDemoPath": "/demo/database",
+    "documentSource": "docs/public/database.md"
   },
   {
     "path": "/demo/database",
@@ -781,7 +857,8 @@
     "description": "사람이 agent에게 지시와 구조화된 context를 한 턴으로 건네는 Composer Hands입니다.",
     "language": "ko",
     "navigationGroup": "Hands",
-    "relatedDemoPath": "/demo/composer"
+    "relatedDemoPath": "/demo/composer",
+    "documentSource": "docs/public/composer.md"
   },
   {
     "path": "/demo/composer",
@@ -805,7 +882,8 @@
     "heading": "Mention",
     "description": "이름으로 보이는 안정적인 entity reference를 inline atom으로 삽입하는 Hands입니다.",
     "language": "ko",
-    "navigationGroup": "Hands"
+    "navigationGroup": "Hands",
+    "documentSource": "docs/public/mention.md"
   },
   {
     "path": "/adapters",
@@ -822,7 +900,8 @@
     "heading": "json-document Adapters",
     "description": "Keyboard, Clipboard, Contenteditable 공식 adapter 계약을 설명합니다.",
     "language": "ko",
-    "navigationGroup": "Adapter"
+    "navigationGroup": "Adapter",
+    "documentSource": "docs/public/adapters.md"
   },
   {
     "path": "/docs/adapter-keyboard",
@@ -831,7 +910,8 @@
     "heading": "Keyboard Adapter",
     "description": "Keyboard, Press와 ARIA platform contract를 Editing 입력으로 번역합니다.",
     "language": "ko",
-    "navigationGroup": "Adapter"
+    "navigationGroup": "Adapter",
+    "documentSource": "docs/public/adapter-keyboard.md"
   },
   {
     "path": "/docs/adapter-grid-cell",
@@ -840,7 +920,8 @@
     "heading": "Grid cell Adapter",
     "description": "GridPoint를 안정된 DOM cell 주소와 focus lookup에 연결합니다.",
     "language": "ko",
-    "navigationGroup": "Adapter"
+    "navigationGroup": "Adapter",
+    "documentSource": "docs/public/adapter-grid-cell.md"
   },
   {
     "path": "/docs/adapter-interaction",
@@ -849,7 +930,8 @@
     "heading": "Interaction Adapter",
     "description": "Pointer capture와 HTML Drag and Drop session을 preview, commit, cancel lifecycle에 연결합니다.",
     "language": "ko",
-    "navigationGroup": "Adapter"
+    "navigationGroup": "Adapter",
+    "documentSource": "docs/public/adapter-interaction.md"
   },
   {
     "path": "/docs/adapter-clipboard",
@@ -858,7 +940,8 @@
     "heading": "Clipboard Adapter",
     "description": "ClipboardEvent를 구조화된 copy, cut, paste 계약에 연결합니다.",
     "language": "ko",
-    "navigationGroup": "Adapter"
+    "navigationGroup": "Adapter",
+    "documentSource": "docs/public/adapter-clipboard.md"
   },
   {
     "path": "/docs/adapter-contenteditable",
@@ -867,7 +950,8 @@
     "heading": "Contenteditable Adapter",
     "description": "문자열 pointer와 native-input DOM lifecycle을 연결합니다.",
     "language": "ko",
-    "navigationGroup": "Adapter"
+    "navigationGroup": "Adapter",
+    "documentSource": "docs/public/adapter-contenteditable.md"
   },
   {
     "path": "/docs/adapter-virtual-selection",
@@ -876,7 +960,8 @@
     "heading": "Virtual Selection Adapter",
     "description": "부분 마운트된 DOM의 Native Selection과 전체 model-backed plain-text 복사를 연결합니다.",
     "language": "ko",
-    "navigationGroup": "Adapter"
+    "navigationGroup": "Adapter",
+    "documentSource": "docs/public/adapter-virtual-selection.md"
   },
   {
     "path": "/affordances/handles",
@@ -949,7 +1034,8 @@
     "heading": "json-document Connectors",
     "description": "React 구독과 선택·커서 질의, React Hook Form, Ajv, Zod, TanStack Table 연결 계약을 설명합니다.",
     "language": "ko",
-    "navigationGroup": "Connector"
+    "navigationGroup": "Connector",
+    "documentSource": "docs/public/connectors.md"
   },
   {
     "path": "/docs/connector-react",
@@ -958,7 +1044,8 @@
     "heading": "React Connector",
     "description": "document와 editor의 변경을 React 구독과 선택 질의로 연결합니다.",
     "language": "ko",
-    "navigationGroup": "Connector"
+    "navigationGroup": "Connector",
+    "documentSource": "docs/public/connector-react.md"
   },
   {
     "path": "/docs/react-editing",
@@ -969,7 +1056,8 @@
     "language": "ko",
     "parentPath": "/docs/connector-react",
     "relatedDemoPath": "/connectors/react",
-    "relatedDemoLabel": "React"
+    "relatedDemoLabel": "React",
+    "documentSource": "docs/public/react-editing.md"
   },
   {
     "path": "/docs/connector-react-hook-form",
@@ -978,7 +1066,8 @@
     "heading": "React Hook Form Connector",
     "description": "form draft와 canonical document commit을 연결합니다.",
     "language": "ko",
-    "navigationGroup": "Connector"
+    "navigationGroup": "Connector",
+    "documentSource": "docs/public/connector-react-hook-form.md"
   },
   {
     "path": "/docs/connector-ajv",
@@ -987,7 +1076,8 @@
     "heading": "Ajv Connector",
     "description": "Ajv validator와 JSON Document validation을 연결합니다.",
     "language": "ko",
-    "navigationGroup": "Connector"
+    "navigationGroup": "Connector",
+    "documentSource": "docs/public/connector-ajv.md"
   },
   {
     "path": "/docs/connector-zod",
@@ -996,7 +1086,8 @@
     "heading": "Zod Connector",
     "description": "Zod schema와 Database document 변환을 설명합니다.",
     "language": "ko",
-    "navigationGroup": "Connector"
+    "navigationGroup": "Connector",
+    "documentSource": "docs/public/connector-zod.md"
   },
   {
     "path": "/docs/connector-zod-validate",
@@ -1005,7 +1096,8 @@
     "heading": "Zod Validate",
     "description": "Zod issue path를 JSON Pointer validation 결과로 번역합니다.",
     "language": "ko",
-    "parentPath": "/docs/connector-zod"
+    "parentPath": "/docs/connector-zod",
+    "documentSource": "docs/public/connector-zod-validate.md"
   },
   {
     "path": "/docs/connector-tanstack-table",
@@ -1014,7 +1106,8 @@
     "heading": "TanStack Table Connector",
     "description": "visible row와 column 순서를 SheetTopology에 연결합니다.",
     "language": "ko",
-    "navigationGroup": "Connector"
+    "navigationGroup": "Connector",
+    "documentSource": "docs/public/connector-tanstack-table.md"
   },
   {
     "path": "/connectors/react",
@@ -1106,7 +1199,8 @@
     "navigationGroup": "UI Primitives",
     "relatedDemoPath": "/demo/ui-primitives",
     "relatedDemoLabel": "Design system",
-    "sidebar": false
+    "sidebar": false,
+    "documentSource": "docs/public/ui-primitives.md"
   },
   {
     "path": "/docs/affordance",
@@ -1116,7 +1210,8 @@
     "description": "제품이 json-document를 만지는 최전선의 키보드·마우스·커서 손을 API와 사용법으로 설명합니다.",
     "language": "ko",
     "navigationGroup": "Affordance",
-    "sidebar": false
+    "sidebar": false,
+    "documentSource": "docs/public/affordance.md"
   },
   {
     "path": "/docs/affordance/focus",
@@ -1126,7 +1221,8 @@
     "description": "Tab은 컴포넌트 사이로, 화살표는 컴포넌트 안에서 초점을 옮기는 손입니다.",
     "language": "ko",
     "navigationGroup": "Affordance",
-    "parentPath": "/docs/affordance"
+    "parentPath": "/docs/affordance",
+    "documentSource": "docs/public/affordance-focus.md"
   },
   {
     "path": "/docs/affordance/caret",
@@ -1136,7 +1232,8 @@
     "description": "I-beam 클릭으로 글 삽입점을 두고, 화살표로 글자 사이를 옮기는 손입니다.",
     "language": "ko",
     "navigationGroup": "Affordance",
-    "parentPath": "/docs/affordance"
+    "parentPath": "/docs/affordance",
+    "documentSource": "docs/public/affordance-caret.md"
   },
   {
     "path": "/docs/affordance/select",
@@ -1148,7 +1245,8 @@
     "navigationGroup": "Affordance",
     "relatedDemoPath": "/widgets/listbox",
     "relatedDemoLabel": "증명 열기",
-    "parentPath": "/docs/affordance"
+    "parentPath": "/docs/affordance",
+    "documentSource": "docs/public/affordance-select.md"
   },
   {
     "path": "/docs/affordance/typeahead",
@@ -1160,7 +1258,8 @@
     "navigationGroup": "Affordance",
     "relatedDemoPath": "/demo/order",
     "relatedDemoLabel": "증명 열기",
-    "parentPath": "/docs/affordance"
+    "parentPath": "/docs/affordance",
+    "documentSource": "docs/public/affordance-typeahead.md"
   },
   {
     "path": "/docs/affordance/activate",
@@ -1172,7 +1271,8 @@
     "navigationGroup": "Affordance",
     "relatedDemoPath": "/demo/canvas",
     "relatedDemoLabel": "증명 열기",
-    "parentPath": "/docs/affordance"
+    "parentPath": "/docs/affordance",
+    "documentSource": "docs/public/affordance-activate.md"
   },
   {
     "path": "/docs/affordance/cancel",
@@ -1184,7 +1284,8 @@
     "navigationGroup": "Affordance",
     "relatedDemoPath": "/demo/canvas",
     "relatedDemoLabel": "증명 열기",
-    "parentPath": "/docs/affordance"
+    "parentPath": "/docs/affordance",
+    "documentSource": "docs/public/affordance-cancel.md"
   },
   {
     "path": "/docs/affordance/fold",
@@ -1196,7 +1297,8 @@
     "navigationGroup": "Affordance",
     "relatedDemoPath": "/widgets/tree",
     "relatedDemoLabel": "증명 열기",
-    "parentPath": "/docs/affordance"
+    "parentPath": "/docs/affordance",
+    "documentSource": "docs/public/affordance-fold.md"
   },
   {
     "path": "/docs/affordance/history",
@@ -1208,7 +1310,8 @@
     "navigationGroup": "Affordance",
     "relatedDemoPath": "/widgets/toolbar",
     "relatedDemoLabel": "증명 열기",
-    "parentPath": "/docs/affordance"
+    "parentPath": "/docs/affordance",
+    "documentSource": "docs/public/affordance-history.md"
   },
   {
     "path": "/docs/affordance/delete",
@@ -1220,7 +1323,8 @@
     "navigationGroup": "Affordance",
     "relatedDemoPath": "/demo/canvas",
     "relatedDemoLabel": "증명 열기",
-    "parentPath": "/docs/affordance"
+    "parentPath": "/docs/affordance",
+    "documentSource": "docs/public/affordance-delete.md"
   },
   {
     "path": "/docs/affordance/rename",
@@ -1230,7 +1334,8 @@
     "description": "F2와 느린 두 번 누르기로 고른 대상의 이름을 고치는 손입니다.",
     "language": "ko",
     "navigationGroup": "Affordance",
-    "parentPath": "/docs/affordance"
+    "parentPath": "/docs/affordance",
+    "documentSource": "docs/public/affordance-rename.md"
   },
   {
     "path": "/docs/affordance/nudge",
@@ -1242,7 +1347,8 @@
     "navigationGroup": "Affordance",
     "relatedDemoPath": "/demo/canvas",
     "relatedDemoLabel": "증명 열기",
-    "parentPath": "/docs/affordance"
+    "parentPath": "/docs/affordance",
+    "documentSource": "docs/public/affordance-nudge.md"
   },
   {
     "path": "/docs/affordance/hover",
@@ -1254,7 +1360,8 @@
     "navigationGroup": "Affordance",
     "relatedDemoPath": "/demo/canvas",
     "relatedDemoLabel": "증명 열기",
-    "parentPath": "/docs/affordance"
+    "parentPath": "/docs/affordance",
+    "documentSource": "docs/public/affordance-hover.md"
   },
   {
     "path": "/docs/affordance/contextual",
@@ -1266,7 +1373,8 @@
     "navigationGroup": "Affordance",
     "relatedDemoPath": "/demo/calendar",
     "relatedDemoLabel": "증명 열기",
-    "parentPath": "/docs/affordance"
+    "parentPath": "/docs/affordance",
+    "documentSource": "docs/public/affordance-contextual.md"
   },
   {
     "path": "/docs/affordance/double-click",
@@ -1276,7 +1384,8 @@
     "description": "click detail 2로 열기·단어 고르기·이름 바꾸기를 여는 손입니다.",
     "language": "ko",
     "navigationGroup": "Affordance",
-    "parentPath": "/docs/affordance"
+    "parentPath": "/docs/affordance",
+    "documentSource": "docs/public/affordance-double-click.md"
   },
   {
     "path": "/docs/affordance/triple-click",
@@ -1286,7 +1395,8 @@
     "description": "click detail 3으로 줄이나 문단을 고르는 손입니다.",
     "language": "ko",
     "navigationGroup": "Affordance",
-    "parentPath": "/docs/affordance"
+    "parentPath": "/docs/affordance",
+    "documentSource": "docs/public/affordance-triple-click.md"
   },
   {
     "path": "/docs/affordance/context-menu",
@@ -1298,7 +1408,8 @@
     "navigationGroup": "Affordance",
     "relatedDemoPath": "/demo/canvas",
     "relatedDemoLabel": "증명 열기",
-    "parentPath": "/docs/affordance"
+    "parentPath": "/docs/affordance",
+    "documentSource": "docs/public/affordance-context-menu.md"
   },
   {
     "path": "/docs/affordance/drag",
@@ -1310,7 +1421,8 @@
     "navigationGroup": "Affordance",
     "relatedDemoPath": "/widgets/canvas",
     "relatedDemoLabel": "증명 열기",
-    "parentPath": "/docs/affordance"
+    "parentPath": "/docs/affordance",
+    "documentSource": "docs/public/affordance-drag.md"
   },
   {
     "path": "/docs/affordance/marquee",
@@ -1322,7 +1434,8 @@
     "navigationGroup": "Affordance",
     "relatedDemoPath": "/demo/canvas",
     "relatedDemoLabel": "증명 열기",
-    "parentPath": "/docs/affordance"
+    "parentPath": "/docs/affordance",
+    "documentSource": "docs/public/affordance-marquee.md"
   },
   {
     "path": "/docs/affordance/drop",
@@ -1334,7 +1447,8 @@
     "navigationGroup": "Affordance",
     "relatedDemoPath": "/demo/canvas",
     "relatedDemoLabel": "증명 열기",
-    "parentPath": "/docs/affordance"
+    "parentPath": "/docs/affordance",
+    "documentSource": "docs/public/affordance-drop.md"
   },
   {
     "path": "/docs/affordance/copy-drag",
@@ -1346,7 +1460,8 @@
     "navigationGroup": "Affordance",
     "relatedDemoPath": "/demo/canvas",
     "relatedDemoLabel": "증명 열기",
-    "parentPath": "/docs/affordance"
+    "parentPath": "/docs/affordance",
+    "documentSource": "docs/public/affordance-copy-drag.md"
   },
   {
     "path": "/docs/affordance/handles",
@@ -1358,7 +1473,8 @@
     "navigationGroup": "Affordance",
     "relatedDemoPath": "/affordances/handles",
     "relatedDemoLabel": "Usage 열기",
-    "parentPath": "/docs/affordance"
+    "parentPath": "/docs/affordance",
+    "documentSource": "docs/public/affordance-handles.md"
   },
   {
     "path": "/docs/affordance/resize",
@@ -1370,7 +1486,8 @@
     "navigationGroup": "Affordance",
     "relatedDemoPath": "/demo/canvas",
     "relatedDemoLabel": "증명 열기",
-    "parentPath": "/docs/affordance"
+    "parentPath": "/docs/affordance",
+    "documentSource": "docs/public/affordance-resize.md"
   },
   {
     "path": "/docs/affordance/pan",
@@ -1382,7 +1499,8 @@
     "navigationGroup": "Affordance",
     "relatedDemoPath": "/demo/canvas",
     "relatedDemoLabel": "증명 열기",
-    "parentPath": "/docs/affordance"
+    "parentPath": "/docs/affordance",
+    "documentSource": "docs/public/affordance-pan.md"
   },
   {
     "path": "/docs/affordance/scroll",
@@ -1394,7 +1512,8 @@
     "navigationGroup": "Affordance",
     "relatedDemoPath": "/demo/canvas",
     "relatedDemoLabel": "증명 열기",
-    "parentPath": "/docs/affordance"
+    "parentPath": "/docs/affordance",
+    "documentSource": "docs/public/affordance-scroll.md"
   },
   {
     "path": "/docs/affordance/zoom",
@@ -1406,7 +1525,8 @@
     "navigationGroup": "Affordance",
     "relatedDemoPath": "/demo/canvas",
     "relatedDemoLabel": "증명 열기",
-    "parentPath": "/docs/affordance"
+    "parentPath": "/docs/affordance",
+    "documentSource": "docs/public/affordance-zoom.md"
   },
   {
     "path": "/docs/affordance/snap",
@@ -1418,7 +1538,8 @@
     "navigationGroup": "Affordance",
     "relatedDemoPath": "/demo/canvas",
     "relatedDemoLabel": "증명 열기",
-    "parentPath": "/docs/affordance"
+    "parentPath": "/docs/affordance",
+    "documentSource": "docs/public/affordance-snap.md"
   },
   {
     "path": "/docs/affordance/forbid",
@@ -1430,7 +1551,8 @@
     "navigationGroup": "Affordance",
     "relatedDemoPath": "/demo/canvas",
     "relatedDemoLabel": "증명 열기",
-    "parentPath": "/docs/affordance"
+    "parentPath": "/docs/affordance",
+    "documentSource": "docs/public/affordance-forbid.md"
   },
   {
     "path": "/widgets/toolbar",
diff --git a/site/src/app/breadcrumb.tsx b/site/src/app/breadcrumb.tsx
index 185b49ed..7ff95394 100644
--- a/site/src/app/breadcrumb.tsx
+++ b/site/src/app/breadcrumb.tsx
@@ -12,14 +12,14 @@ export type BreadcrumbCrumb = {
 const overview: BreadcrumbCrumb = { path: "/", label: "Overview" };
 
 const groupLandings: Record<SiteNavigationGroup, BreadcrumbCrumb> = {
-  Introduction: { path: "/docs", label: "Introduce" },
-  "JSON Document": { path: "/docs/foundation", label: "JSON Document" },
+  Introduction: { path: "/docs", label: "Introduction" },
+  "JSON Document": { path: "/docs/api", label: "JSON Document" },
   "Document Types": { path: "/docs/document-types", label: "Document Types" },
-  Editing: { path: "/docs/intent-guide", label: "Editing" },
+  Editing: { path: "/docs/editing", label: "Editing" },
   Collaboration: { path: "/docs/collaboration", label: "Collaboration" },
-  Adapter: { path: "/docs/adapters", label: "Platform Adapters" },
-  Connector: { path: "/docs/connectors", label: "Ecosystem Connectors" },
-  Affordance: { path: "/docs/affordance", label: "Affordances" },
+  Adapter: { path: "/docs/adapters", label: "Adapter" },
+  Connector: { path: "/docs/connectors", label: "Connector" },
+  Affordance: { path: "/docs/affordance", label: "Affordance" },
   "UI Primitives": { path: "/docs/ui-primitives", label: "UI Primitives" },
   Hands: { path: "/editors", label: "Hands" },
   Artifact: { path: "/viewer", label: "Artifact" },
@@ -42,7 +42,7 @@ export function breadcrumbTrail(
       : undefined;
   }
 
-  const directSection = siteSections.find((section) => section.path === route.path && section.groups.length === 0);
+  const directSection = siteSections.find((section) => section.path === route.path);
   const group = routeGroup(route, routes);
   if (directSection) {
     stack[0] = { path: directSection.path, label: directSection.label };
diff --git a/site/src/app/navigation-layer-icon.tsx b/site/src/app/navigation-layer-icon.tsx
index 8e926627..0c2c3129 100644
--- a/site/src/app/navigation-layer-icon.tsx
+++ b/site/src/app/navigation-layer-icon.tsx
@@ -4,7 +4,6 @@ import {
   Braces,
   Files,
   Hand,
-  Library,
   PanelsTopLeft,
   type LucideIcon,
 } from "lucide-react";
@@ -16,13 +15,12 @@ type LayerIcon = {
 };
 
 const layerIcons: Readonly<Record<SiteSectionId, LayerIcon>> = {
-  introduce: { icon: BookOpen, size: 18 },
+  introduction: { icon: BookOpen, size: 18 },
   foundation: { icon: Braces, size: 19 },
   "building-blocks": { icon: Blocks, size: 18 },
   hands: { icon: Hand, size: 19 },
   artifact: { icon: Files, size: 18 },
   applications: { icon: PanelsTopLeft, size: 19 },
-  reference: { icon: Library, size: 18 },
 };
 
 export function NavigationLayerIcon(props: {
diff --git a/site/src/app/page-descriptors.ts b/site/src/app/page-descriptors.ts
index f95c0f9f..08b71676 100644
--- a/site/src/app/page-descriptors.ts
+++ b/site/src/app/page-descriptors.ts
@@ -21,6 +21,7 @@ export type SiteRoute = {
   readonly label: string;
   readonly title: string;
   readonly heading?: string;
+  readonly documentSource?: string;
   readonly description: string;
   readonly language?: "en" | "ko";
   readonly navigationGroup?: SiteNavigationGroup;
diff --git a/site/src/app/routeTree.gen.ts b/site/src/app/routeTree.gen.ts
index 4251679d..c2aca0f9 100644
--- a/site/src/app/routeTree.gen.ts
+++ b/site/src/app/routeTree.gen.ts
@@ -61,7 +61,7 @@ import { Route as PageDocsAdapterKeyboardRouteImport } from "./routes/_page/docs
 import { Route as PageDocsAdapterVirtualSelectionRouteImport } from "./routes/_page/docs/adapter-virtual-selection";
 import { Route as PageDocsAdaptersRouteImport } from "./routes/_page/docs/adapters";
 import { Route as PageDocsAnimationRouteImport } from "./routes/_page/docs/animation";
-import { Route as PageDocsApiRouteImport } from "./routes/_page/docs/api";
+import { Route as PageDocsBuildingBlocksRouteImport } from "./routes/_page/docs/building-blocks";
 import { Route as PageDocsClipboardRouteImport } from "./routes/_page/docs/clipboard";
 import { Route as PageDocsComposerRouteImport } from "./routes/_page/docs/composer";
 import { Route as PageDocsConceptsRouteImport } from "./routes/_page/docs/concepts";
@@ -74,6 +74,7 @@ import { Route as PageDocsConnectorZodRouteImport } from "./routes/_page/docs/co
 import { Route as PageDocsConnectorZodValidateRouteImport } from "./routes/_page/docs/connector-zod-validate";
 import { Route as PageDocsConnectorsRouteImport } from "./routes/_page/docs/connectors";
 import { Route as PageDocsDatabaseRouteImport } from "./routes/_page/docs/database";
+import { Route as PageDocsEditingRouteImport } from "./routes/_page/docs/editing";
 import { Route as PageDocsFoundationRouteImport } from "./routes/_page/docs/foundation";
 import { Route as PageDocsHistoryRouteImport } from "./routes/_page/docs/history";
 import { Route as PageDocsHowWeBuildRouteImport } from "./routes/_page/docs/how-we-build";
@@ -128,6 +129,7 @@ import { Route as PageDocsAffordanceSnapRouteImport } from "./routes/_page/docs/
 import { Route as PageDocsAffordanceTripleClickRouteImport } from "./routes/_page/docs/affordance/triple-click";
 import { Route as PageDocsAffordanceTypeaheadRouteImport } from "./routes/_page/docs/affordance/typeahead";
 import { Route as PageDocsAffordanceZoomRouteImport } from "./routes/_page/docs/affordance/zoom";
+import { Route as PageDocsApiIndexRouteImport } from "./routes/_page/docs/api/index";
 import { Route as PageDocsApiA2uiRouteImport } from "./routes/_page/docs/api/a2ui";
 import { Route as PageDocsApiAffordanceRouteImport } from "./routes/_page/docs/api/affordance";
 import { Route as PageDocsApiAjvRouteImport } from "./routes/_page/docs/api/ajv";
@@ -436,9 +438,9 @@ const PageDocsAnimationRoute = PageDocsAnimationRouteImport.update({
   path: "/docs/animation",
   getParentRoute: () => PageRoute,
 } as any);
-const PageDocsApiRoute = PageDocsApiRouteImport.update({
-  id: "/docs/api",
-  path: "/docs/api",
+const PageDocsBuildingBlocksRoute = PageDocsBuildingBlocksRouteImport.update({
+  id: "/docs/building-blocks",
+  path: "/docs/building-blocks",
   getParentRoute: () => PageRoute,
 } as any);
 const PageDocsClipboardRoute = PageDocsClipboardRouteImport.update({
@@ -504,6 +506,11 @@ const PageDocsDatabaseRoute = PageDocsDatabaseRouteImport.update({
   path: "/docs/database",
   getParentRoute: () => PageRoute,
 } as any);
+const PageDocsEditingRoute = PageDocsEditingRouteImport.update({
+  id: "/docs/editing",
+  path: "/docs/editing",
+  getParentRoute: () => PageRoute,
+} as any);
 const PageDocsFoundationRoute = PageDocsFoundationRouteImport.update({
   id: "/docs/foundation",
   path: "/docs/foundation",
@@ -792,169 +799,174 @@ const PageDocsAffordanceZoomRoute = PageDocsAffordanceZoomRouteImport.update({
   path: "/docs/affordance/zoom",
   getParentRoute: () => PageRoute,
 } as any);
+const PageDocsApiIndexRoute = PageDocsApiIndexRouteImport.update({
+  id: "/docs/api/",
+  path: "/docs/api/",
+  getParentRoute: () => PageRoute,
+} as any);
 const PageDocsApiA2uiRoute = PageDocsApiA2uiRouteImport.update({
-  id: "/a2ui",
-  path: "/a2ui",
-  getParentRoute: () => PageDocsApiRoute,
+  id: "/docs/api/a2ui",
+  path: "/docs/api/a2ui",
+  getParentRoute: () => PageRoute,
 } as any);
 const PageDocsApiAffordanceRoute = PageDocsApiAffordanceRouteImport.update({
-  id: "/affordance",
-  path: "/affordance",
-  getParentRoute: () => PageDocsApiRoute,
+  id: "/docs/api/affordance",
+  path: "/docs/api/affordance",
+  getParentRoute: () => PageRoute,
 } as any);
 const PageDocsApiAjvRoute = PageDocsApiAjvRouteImport.update({
-  id: "/ajv",
-  path: "/ajv",
-  getParentRoute: () => PageDocsApiRoute,
+  id: "/docs/api/ajv",
+  path: "/docs/api/ajv",
+  getParentRoute: () => PageRoute,
 } as any);
 const PageDocsApiAnimationReactRoute =
   PageDocsApiAnimationReactRouteImport.update({
-    id: "/animation-react",
-    path: "/animation-react",
-    getParentRoute: () => PageDocsApiRoute,
+    id: "/docs/api/animation-react",
+    path: "/docs/api/animation-react",
+    getParentRoute: () => PageRoute,
   } as any);
 const PageDocsApiAnnotationRoute = PageDocsApiAnnotationRouteImport.update({
-  id: "/annotation",
-  path: "/annotation",
-  getParentRoute: () => PageDocsApiRoute,
+  id: "/docs/api/annotation",
+  path: "/docs/api/annotation",
+  getParentRoute: () => PageRoute,
 } as any);
 const PageDocsApiCalendarRoute = PageDocsApiCalendarRouteImport.update({
-  id: "/calendar",
-  path: "/calendar",
-  getParentRoute: () => PageDocsApiRoute,
+  id: "/docs/api/calendar",
+  path: "/docs/api/calendar",
+  getParentRoute: () => PageRoute,
 } as any);
 const PageDocsApiCollaborationRoute =
   PageDocsApiCollaborationRouteImport.update({
-    id: "/collaboration",
-    path: "/collaboration",
-    getParentRoute: () => PageDocsApiRoute,
+    id: "/docs/api/collaboration",
+    path: "/docs/api/collaboration",
+    getParentRoute: () => PageRoute,
   } as any);
 const PageDocsApiComposerRoute = PageDocsApiComposerRouteImport.update({
-  id: "/composer",
-  path: "/composer",
-  getParentRoute: () => PageDocsApiRoute,
+  id: "/docs/api/composer",
+  path: "/docs/api/composer",
+  getParentRoute: () => PageRoute,
 } as any);
 const PageDocsApiComposerReactRoute =
   PageDocsApiComposerReactRouteImport.update({
-    id: "/composer-react",
-    path: "/composer-react",
-    getParentRoute: () => PageDocsApiRoute,
+    id: "/docs/api/composer-react",
+    path: "/docs/api/composer-react",
+    getParentRoute: () => PageRoute,
   } as any);
 const PageDocsApiContenteditableRoute =
   PageDocsApiContenteditableRouteImport.update({
-    id: "/contenteditable",
-    path: "/contenteditable",
-    getParentRoute: () => PageDocsApiRoute,
+    id: "/docs/api/contenteditable",
+    path: "/docs/api/contenteditable",
+    getParentRoute: () => PageRoute,
   } as any);
 const PageDocsApiContenteditableCollaborationRoute =
   PageDocsApiContenteditableCollaborationRouteImport.update({
-    id: "/contenteditable-collaboration",
-    path: "/contenteditable-collaboration",
-    getParentRoute: () => PageDocsApiRoute,
+    id: "/docs/api/contenteditable-collaboration",
+    path: "/docs/api/contenteditable-collaboration",
+    getParentRoute: () => PageRoute,
   } as any);
 const PageDocsApiDatabaseRoute = PageDocsApiDatabaseRouteImport.update({
-  id: "/database",
-  path: "/database",
-  getParentRoute: () => PageDocsApiRoute,
+  id: "/docs/api/database",
+  path: "/docs/api/database",
+  getParentRoute: () => PageRoute,
 } as any);
 const PageDocsApiEditingRoute = PageDocsApiEditingRouteImport.update({
-  id: "/editing",
-  path: "/editing",
-  getParentRoute: () => PageDocsApiRoute,
+  id: "/docs/api/editing",
+  path: "/docs/api/editing",
+  getParentRoute: () => PageRoute,
 } as any);
 const PageDocsApiFileIntakeRoute = PageDocsApiFileIntakeRouteImport.update({
-  id: "/file-intake",
-  path: "/file-intake",
-  getParentRoute: () => PageDocsApiRoute,
+  id: "/docs/api/file-intake",
+  path: "/docs/api/file-intake",
+  getParentRoute: () => PageRoute,
 } as any);
 const PageDocsApiJsonDocumentRoute = PageDocsApiJsonDocumentRouteImport.update({
-  id: "/json-document",
-  path: "/json-document",
-  getParentRoute: () => PageDocsApiRoute,
+  id: "/docs/api/json-document",
+  path: "/docs/api/json-document",
+  getParentRoute: () => PageRoute,
 } as any);
 const PageDocsApiMarkdownReactRoute =
   PageDocsApiMarkdownReactRouteImport.update({
-    id: "/markdown-react",
-    path: "/markdown-react",
-    getParentRoute: () => PageDocsApiRoute,
+    id: "/docs/api/markdown-react",
+    path: "/docs/api/markdown-react",
+    getParentRoute: () => PageRoute,
   } as any);
 const PageDocsApiReactRoute = PageDocsApiReactRouteImport.update({
-  id: "/react",
-  path: "/react",
-  getParentRoute: () => PageDocsApiRoute,
+  id: "/docs/api/react",
+  path: "/docs/api/react",
+  getParentRoute: () => PageRoute,
 } as any);
 const PageDocsApiReactHookFormRoute =
   PageDocsApiReactHookFormRouteImport.update({
-    id: "/react-hook-form",
-    path: "/react-hook-form",
-    getParentRoute: () => PageDocsApiRoute,
+    id: "/docs/api/react-hook-form",
+    path: "/docs/api/react-hook-form",
+    getParentRoute: () => PageRoute,
   } as any);
 const PageDocsApiRichTextRoute = PageDocsApiRichTextRouteImport.update({
-  id: "/rich-text",
-  path: "/rich-text",
-  getParentRoute: () => PageDocsApiRoute,
+  id: "/docs/api/rich-text",
+  path: "/docs/api/rich-text",
+  getParentRoute: () => PageRoute,
 } as any);
 const PageDocsApiRichTextMentionRoute =
   PageDocsApiRichTextMentionRouteImport.update({
-    id: "/rich-text-mention",
-    path: "/rich-text-mention",
-    getParentRoute: () => PageDocsApiRoute,
+    id: "/docs/api/rich-text-mention",
+    path: "/docs/api/rich-text-mention",
+    getParentRoute: () => PageRoute,
   } as any);
 const PageDocsApiRichTextMentionReactRoute =
   PageDocsApiRichTextMentionReactRouteImport.update({
-    id: "/rich-text-mention-react",
-    path: "/rich-text-mention-react",
-    getParentRoute: () => PageDocsApiRoute,
+    id: "/docs/api/rich-text-mention-react",
+    path: "/docs/api/rich-text-mention-react",
+    getParentRoute: () => PageRoute,
   } as any);
 const PageDocsApiRichTextReactRoute =
   PageDocsApiRichTextReactRouteImport.update({
-    id: "/rich-text-react",
-    path: "/rich-text-react",
-    getParentRoute: () => PageDocsApiRoute,
+    id: "/docs/api/rich-text-react",
+    path: "/docs/api/rich-text-react",
+    getParentRoute: () => PageRoute,
   } as any);
 const PageDocsApiRichTextSuggestionRoute =
   PageDocsApiRichTextSuggestionRouteImport.update({
-    id: "/rich-text-suggestion",
-    path: "/rich-text-suggestion",
-    getParentRoute: () => PageDocsApiRoute,
+    id: "/docs/api/rich-text-suggestion",
+    path: "/docs/api/rich-text-suggestion",
+    getParentRoute: () => PageRoute,
   } as any);
 const PageDocsApiRichTextSuggestionReactRoute =
   PageDocsApiRichTextSuggestionReactRouteImport.update({
-    id: "/rich-text-suggestion-react",
-    path: "/rich-text-suggestion-react",
-    getParentRoute: () => PageDocsApiRoute,
+    id: "/docs/api/rich-text-suggestion-react",
+    path: "/docs/api/rich-text-suggestion-react",
+    getParentRoute: () => PageRoute,
   } as any);
 const PageDocsApiRichTextWebRoute = PageDocsApiRichTextWebRouteImport.update({
-  id: "/rich-text-web",
-  path: "/rich-text-web",
-  getParentRoute: () => PageDocsApiRoute,
+  id: "/docs/api/rich-text-web",
+  path: "/docs/api/rich-text-web",
+  getParentRoute: () => PageRoute,
 } as any);
 const PageDocsApiSelectionRoute = PageDocsApiSelectionRouteImport.update({
-  id: "/selection",
-  path: "/selection",
-  getParentRoute: () => PageDocsApiRoute,
+  id: "/docs/api/selection",
+  path: "/docs/api/selection",
+  getParentRoute: () => PageRoute,
 } as any);
 const PageDocsApiTanstackTableRoute =
   PageDocsApiTanstackTableRouteImport.update({
-    id: "/tanstack-table",
-    path: "/tanstack-table",
-    getParentRoute: () => PageDocsApiRoute,
+    id: "/docs/api/tanstack-table",
+    path: "/docs/api/tanstack-table",
+    getParentRoute: () => PageRoute,
   } as any);
 const PageDocsApiUiPrimitivesReactRoute =
   PageDocsApiUiPrimitivesReactRouteImport.update({
-    id: "/ui-primitives-react",
-    path: "/ui-primitives-react",
-    getParentRoute: () => PageDocsApiRoute,
+    id: "/docs/api/ui-primitives-react",
+    path: "/docs/api/ui-primitives-react",
+    getParentRoute: () => PageRoute,
   } as any);
 const PageDocsApiWebRoute = PageDocsApiWebRouteImport.update({
-  id: "/web",
-  path: "/web",
-  getParentRoute: () => PageDocsApiRoute,
+  id: "/docs/api/web",
+  path: "/docs/api/web",
+  getParentRoute: () => PageRoute,
 } as any);
 const PageDocsApiZodRoute = PageDocsApiZodRouteImport.update({
-  id: "/zod",
-  path: "/zod",
-  getParentRoute: () => PageDocsApiRoute,
+  id: "/docs/api/zod",
+  path: "/docs/api/zod",
+  getParentRoute: () => PageRoute,
 } as any);
 const PageDocsCollaborationIndexRoute =
   PageDocsCollaborationIndexRouteImport.update({
@@ -1052,7 +1064,7 @@ export interface FileRoutesByFullPath {
   "/docs/adapter-virtual-selection": typeof PageDocsAdapterVirtualSelectionRoute;
   "/docs/adapters": typeof PageDocsAdaptersRoute;
   "/docs/animation": typeof PageDocsAnimationRoute;
-  "/docs/api": typeof PageDocsApiRouteWithChildren;
+  "/docs/building-blocks": typeof PageDocsBuildingBlocksRoute;
   "/docs/clipboard": typeof PageDocsClipboardRoute;
   "/docs/composer": typeof PageDocsComposerRoute;
   "/docs/concepts": typeof PageDocsConceptsRoute;
@@ -1065,6 +1077,7 @@ export interface FileRoutesByFullPath {
   "/docs/connector-zod-validate": typeof PageDocsConnectorZodValidateRoute;
   "/docs/connectors": typeof PageDocsConnectorsRoute;
   "/docs/database": typeof PageDocsDatabaseRoute;
+  "/docs/editing": typeof PageDocsEditingRoute;
   "/docs/foundation": typeof PageDocsFoundationRoute;
   "/docs/history": typeof PageDocsHistoryRoute;
   "/docs/how-we-build": typeof PageDocsHowWeBuildRoute;
@@ -1158,6 +1171,7 @@ export interface FileRoutesByFullPath {
   "/docs/document-types/$candidate": typeof PageDocsDocumentTypesCandidateRoute;
   "/connectors/zod/": typeof PageConnectorsZodIndexRoute;
   "/docs/affordance/": typeof PageDocsAffordanceIndexRoute;
+  "/docs/api/": typeof PageDocsApiIndexRoute;
   "/docs/collaboration/": typeof PageDocsCollaborationIndexRoute;
   "/docs/document-types/": typeof PageDocsDocumentTypesIndexRoute;
   "/docs/collaboration/text/lease": typeof PageDocsCollaborationTextLeaseRoute;
@@ -1210,7 +1224,7 @@ export interface FileRoutesByTo {
   "/docs/adapter-virtual-selection": typeof PageDocsAdapterVirtualSelectionRoute;
   "/docs/adapters": typeof PageDocsAdaptersRoute;
   "/docs/animation": typeof PageDocsAnimationRoute;
-  "/docs/api": typeof PageDocsApiRouteWithChildren;
+  "/docs/building-blocks": typeof PageDocsBuildingBlocksRoute;
   "/docs/clipboard": typeof PageDocsClipboardRoute;
   "/docs/composer": typeof PageDocsComposerRoute;
   "/docs/concepts": typeof PageDocsConceptsRoute;
@@ -1223,6 +1237,7 @@ export interface FileRoutesByTo {
   "/docs/connector-zod-validate": typeof PageDocsConnectorZodValidateRoute;
   "/docs/connectors": typeof PageDocsConnectorsRoute;
   "/docs/database": typeof PageDocsDatabaseRoute;
+  "/docs/editing": typeof PageDocsEditingRoute;
   "/docs/foundation": typeof PageDocsFoundationRoute;
   "/docs/history": typeof PageDocsHistoryRoute;
   "/docs/how-we-build": typeof PageDocsHowWeBuildRoute;
@@ -1316,6 +1331,7 @@ export interface FileRoutesByTo {
   "/docs/document-types/$candidate": typeof PageDocsDocumentTypesCandidateRoute;
   "/connectors/zod": typeof PageConnectorsZodIndexRoute;
   "/docs/affordance": typeof PageDocsAffordanceIndexRoute;
+  "/docs/api": typeof PageDocsApiIndexRoute;
   "/docs/collaboration": typeof PageDocsCollaborationIndexRoute;
   "/docs/document-types": typeof PageDocsDocumentTypesIndexRoute;
   "/docs/collaboration/text/lease": typeof PageDocsCollaborationTextLeaseRoute;
@@ -1370,7 +1386,7 @@ export interface FileRoutesById {
   "/_page/docs/adapter-virtual-selection": typeof PageDocsAdapterVirtualSelectionRoute;
   "/_page/docs/adapters": typeof PageDocsAdaptersRoute;
   "/_page/docs/animation": typeof PageDocsAnimationRoute;
-  "/_page/docs/api": typeof PageDocsApiRouteWithChildren;
+  "/_page/docs/building-blocks": typeof PageDocsBuildingBlocksRoute;
   "/_page/docs/clipboard": typeof PageDocsClipboardRoute;
   "/_page/docs/composer": typeof PageDocsComposerRoute;
   "/_page/docs/concepts": typeof PageDocsConceptsRoute;
@@ -1383,6 +1399,7 @@ export interface FileRoutesById {
   "/_page/docs/connector-zod-validate": typeof PageDocsConnectorZodValidateRoute;
   "/_page/docs/connectors": typeof PageDocsConnectorsRoute;
   "/_page/docs/database": typeof PageDocsDatabaseRoute;
+  "/_page/docs/editing": typeof PageDocsEditingRoute;
   "/_page/docs/foundation": typeof PageDocsFoundationRoute;
   "/_page/docs/history": typeof PageDocsHistoryRoute;
   "/_page/docs/how-we-build": typeof PageDocsHowWeBuildRoute;
@@ -1476,6 +1493,7 @@ export interface FileRoutesById {
   "/_page/docs/document-types/$candidate": typeof PageDocsDocumentTypesCandidateRoute;
   "/_page/connectors/zod/": typeof PageConnectorsZodIndexRoute;
   "/_page/docs/affordance/": typeof PageDocsAffordanceIndexRoute;
+  "/_page/docs/api/": typeof PageDocsApiIndexRoute;
   "/_page/docs/collaboration/": typeof PageDocsCollaborationIndexRoute;
   "/_page/docs/document-types/": typeof PageDocsDocumentTypesIndexRoute;
   "/_page/docs/collaboration/text/lease": typeof PageDocsCollaborationTextLeaseRoute;
@@ -1530,7 +1548,7 @@ export interface FileRouteTypes {
     | "/docs/adapter-virtual-selection"
     | "/docs/adapters"
     | "/docs/animation"
-    | "/docs/api"
+    | "/docs/building-blocks"
     | "/docs/clipboard"
     | "/docs/composer"
     | "/docs/concepts"
@@ -1543,6 +1561,7 @@ export interface FileRouteTypes {
     | "/docs/connector-zod-validate"
     | "/docs/connectors"
     | "/docs/database"
+    | "/docs/editing"
     | "/docs/foundation"
     | "/docs/history"
     | "/docs/how-we-build"
@@ -1636,6 +1655,7 @@ export interface FileRouteTypes {
     | "/docs/document-types/$candidate"
     | "/connectors/zod/"
     | "/docs/affordance/"
+    | "/docs/api/"
     | "/docs/collaboration/"
     | "/docs/document-types/"
     | "/docs/collaboration/text/lease"
@@ -1688,7 +1708,7 @@ export interface FileRouteTypes {
     | "/docs/adapter-virtual-selection"
     | "/docs/adapters"
     | "/docs/animation"
-    | "/docs/api"
+    | "/docs/building-blocks"
     | "/docs/clipboard"
     | "/docs/composer"
     | "/docs/concepts"
@@ -1701,6 +1721,7 @@ export interface FileRouteTypes {
     | "/docs/connector-zod-validate"
     | "/docs/connectors"
     | "/docs/database"
+    | "/docs/editing"
     | "/docs/foundation"
     | "/docs/history"
     | "/docs/how-we-build"
@@ -1794,6 +1815,7 @@ export interface FileRouteTypes {
     | "/docs/document-types/$candidate"
     | "/connectors/zod"
     | "/docs/affordance"
+    | "/docs/api"
     | "/docs/collaboration"
     | "/docs/document-types"
     | "/docs/collaboration/text/lease"
@@ -1847,7 +1869,7 @@ export interface FileRouteTypes {
     | "/_page/docs/adapter-virtual-selection"
     | "/_page/docs/adapters"
     | "/_page/docs/animation"
-    | "/_page/docs/api"
+    | "/_page/docs/building-blocks"
     | "/_page/docs/clipboard"
     | "/_page/docs/composer"
     | "/_page/docs/concepts"
@@ -1860,6 +1882,7 @@ export interface FileRouteTypes {
     | "/_page/docs/connector-zod-validate"
     | "/_page/docs/connectors"
     | "/_page/docs/database"
+    | "/_page/docs/editing"
     | "/_page/docs/foundation"
     | "/_page/docs/history"
     | "/_page/docs/how-we-build"
@@ -1953,6 +1976,7 @@ export interface FileRouteTypes {
     | "/_page/docs/document-types/$candidate"
     | "/_page/connectors/zod/"
     | "/_page/docs/affordance/"
+    | "/_page/docs/api/"
     | "/_page/docs/collaboration/"
     | "/_page/docs/document-types/"
     | "/_page/docs/collaboration/text/lease"
@@ -2330,11 +2354,11 @@ declare module "@tanstack/react-router" {
       preLoaderRoute: typeof PageDocsAnimationRouteImport;
       parentRoute: typeof PageRoute;
     };
-    "/_page/docs/api": {
-      id: "/_page/docs/api";
-      path: "/docs/api";
-      fullPath: "/docs/api";
-      preLoaderRoute: typeof PageDocsApiRouteImport;
+    "/_page/docs/building-blocks": {
+      id: "/_page/docs/building-blocks";
+      path: "/docs/building-blocks";
+      fullPath: "/docs/building-blocks";
+      preLoaderRoute: typeof PageDocsBuildingBlocksRouteImport;
       parentRoute: typeof PageRoute;
     };
     "/_page/docs/clipboard": {
@@ -2421,6 +2445,13 @@ declare module "@tanstack/react-router" {
       preLoaderRoute: typeof PageDocsDatabaseRouteImport;
       parentRoute: typeof PageRoute;
     };
+    "/_page/docs/editing": {
+      id: "/_page/docs/editing";
+      path: "/docs/editing";
+      fullPath: "/docs/editing";
+      preLoaderRoute: typeof PageDocsEditingRouteImport;
+      parentRoute: typeof PageRoute;
+    };
     "/_page/docs/foundation": {
       id: "/_page/docs/foundation";
       path: "/docs/foundation";
@@ -2799,215 +2830,222 @@ declare module "@tanstack/react-router" {
       preLoaderRoute: typeof PageDocsAffordanceZoomRouteImport;
       parentRoute: typeof PageRoute;
     };
+    "/_page/docs/api/": {
+      id: "/_page/docs/api/";
+      path: "/docs/api";
+      fullPath: "/docs/api/";
+      preLoaderRoute: typeof PageDocsApiIndexRouteImport;
+      parentRoute: typeof PageRoute;
+    };
     "/_page/docs/api/a2ui": {
       id: "/_page/docs/api/a2ui";
-      path: "/a2ui";
+      path: "/docs/api/a2ui";
       fullPath: "/docs/api/a2ui";
       preLoaderRoute: typeof PageDocsApiA2uiRouteImport;
-      parentRoute: typeof PageDocsApiRoute;
+      parentRoute: typeof PageRoute;
     };
     "/_page/docs/api/affordance": {
       id: "/_page/docs/api/affordance";
-      path: "/affordance";
+      path: "/docs/api/affordance";
       fullPath: "/docs/api/affordance";
       preLoaderRoute: typeof PageDocsApiAffordanceRouteImport;
-      parentRoute: typeof PageDocsApiRoute;
+      parentRoute: typeof PageRoute;
     };
     "/_page/docs/api/ajv": {
       id: "/_page/docs/api/ajv";
-      path: "/ajv";
+      path: "/docs/api/ajv";
       fullPath: "/docs/api/ajv";
       preLoaderRoute: typeof PageDocsApiAjvRouteImport;
-      parentRoute: typeof PageDocsApiRoute;
+      parentRoute: typeof PageRoute;
     };
     "/_page/docs/api/animation-react": {
       id: "/_page/docs/api/animation-react";
-      path: "/animation-react";
+      path: "/docs/api/animation-react";
       fullPath: "/docs/api/animation-react";
       preLoaderRoute: typeof PageDocsApiAnimationReactRouteImport;
-      parentRoute: typeof PageDocsApiRoute;
+      parentRoute: typeof PageRoute;
     };
     "/_page/docs/api/annotation": {
       id: "/_page/docs/api/annotation";
-      path: "/annotation";
+      path: "/docs/api/annotation";
       fullPath: "/docs/api/annotation";
       preLoaderRoute: typeof PageDocsApiAnnotationRouteImport;
-      parentRoute: typeof PageDocsApiRoute;
+      parentRoute: typeof PageRoute;
     };
     "/_page/docs/api/calendar": {
       id: "/_page/docs/api/calendar";
-      path: "/calendar";
+      path: "/docs/api/calendar";
       fullPath: "/docs/api/calendar";
       preLoaderRoute: typeof PageDocsApiCalendarRouteImport;
-      parentRoute: typeof PageDocsApiRoute;
+      parentRoute: typeof PageRoute;
     };
     "/_page/docs/api/collaboration": {
       id: "/_page/docs/api/collaboration";
-      path: "/collaboration";
+      path: "/docs/api/collaboration";
       fullPath: "/docs/api/collaboration";
       preLoaderRoute: typeof PageDocsApiCollaborationRouteImport;
-      parentRoute: typeof PageDocsApiRoute;
+      parentRoute: typeof PageRoute;
     };
     "/_page/docs/api/composer": {
       id: "/_page/docs/api/composer";
-      path: "/composer";
+      path: "/docs/api/composer";
       fullPath: "/docs/api/composer";
       preLoaderRoute: typeof PageDocsApiComposerRouteImport;
-      parentRoute: typeof PageDocsApiRoute;
+      parentRoute: typeof PageRoute;
     };
     "/_page/docs/api/composer-react": {
       id: "/_page/docs/api/composer-react";
-      path: "/composer-react";
+      path: "/docs/api/composer-react";
       fullPath: "/docs/api/composer-react";
       preLoaderRoute: typeof PageDocsApiComposerReactRouteImport;
-      parentRoute: typeof PageDocsApiRoute;
+      parentRoute: typeof PageRoute;
     };
     "/_page/docs/api/contenteditable": {
       id: "/_page/docs/api/contenteditable";
-      path: "/contenteditable";
+      path: "/docs/api/contenteditable";
       fullPath: "/docs/api/contenteditable";
       preLoaderRoute: typeof PageDocsApiContenteditableRouteImport;
-      parentRoute: typeof PageDocsApiRoute;
+      parentRoute: typeof PageRoute;
     };
     "/_page/docs/api/contenteditable-collaboration": {
       id: "/_page/docs/api/contenteditable-collaboration";
-      path: "/contenteditable-collaboration";
+      path: "/docs/api/contenteditable-collaboration";
       fullPath: "/docs/api/contenteditable-collaboration";
       preLoaderRoute: typeof PageDocsApiContenteditableCollaborationRouteImport;
-      parentRoute: typeof PageDocsApiRoute;
+      parentRoute: typeof PageRoute;
     };
     "/_page/docs/api/database": {
       id: "/_page/docs/api/database";
-      path: "/database";
+      path: "/docs/api/database";
       fullPath: "/docs/api/database";
       preLoaderRoute: typeof PageDocsApiDatabaseRouteImport;
-      parentRoute: typeof PageDocsApiRoute;
+      parentRoute: typeof PageRoute;
     };
     "/_page/docs/api/editing": {
       id: "/_page/docs/api/editing";
-      path: "/editing";
+      path: "/docs/api/editing";
       fullPath: "/docs/api/editing";
       preLoaderRoute: typeof PageDocsApiEditingRouteImport;
-      parentRoute: typeof PageDocsApiRoute;
+      parentRoute: typeof PageRoute;
     };
     "/_page/docs/api/file-intake": {
       id: "/_page/docs/api/file-intake";
-      path: "/file-intake";
+      path: "/docs/api/file-intake";
       fullPath: "/docs/api/file-intake";
       preLoaderRoute: typeof PageDocsApiFileIntakeRouteImport;
-      parentRoute: typeof PageDocsApiRoute;
+      parentRoute: typeof PageRoute;
     };
     "/_page/docs/api/json-document": {
       id: "/_page/docs/api/json-document";
-      path: "/json-document";
+      path: "/docs/api/json-document";
       fullPath: "/docs/api/json-document";
       preLoaderRoute: typeof PageDocsApiJsonDocumentRouteImport;
-      parentRoute: typeof PageDocsApiRoute;
+      parentRoute: typeof PageRoute;
     };
     "/_page/docs/api/markdown-react": {
       id: "/_page/docs/api/markdown-react";
-      path: "/markdown-react";
+      path: "/docs/api/markdown-react";
       fullPath: "/docs/api/markdown-react";
       preLoaderRoute: typeof PageDocsApiMarkdownReactRouteImport;
-      parentRoute: typeof PageDocsApiRoute;
+      parentRoute: typeof PageRoute;
     };
     "/_page/docs/api/react": {
       id: "/_page/docs/api/react";
-      path: "/react";
+      path: "/docs/api/react";
       fullPath: "/docs/api/react";
       preLoaderRoute: typeof PageDocsApiReactRouteImport;
-      parentRoute: typeof PageDocsApiRoute;
+      parentRoute: typeof PageRoute;
     };
     "/_page/docs/api/react-hook-form": {
       id: "/_page/docs/api/react-hook-form";
-      path: "/react-hook-form";
+      path: "/docs/api/react-hook-form";
       fullPath: "/docs/api/react-hook-form";
       preLoaderRoute: typeof PageDocsApiReactHookFormRouteImport;
-      parentRoute: typeof PageDocsApiRoute;
+      parentRoute: typeof PageRoute;
     };
     "/_page/docs/api/rich-text": {
       id: "/_page/docs/api/rich-text";
-      path: "/rich-text";
+      path: "/docs/api/rich-text";
       fullPath: "/docs/api/rich-text";
       preLoaderRoute: typeof PageDocsApiRichTextRouteImport;
-      parentRoute: typeof PageDocsApiRoute;
+      parentRoute: typeof PageRoute;
     };
     "/_page/docs/api/rich-text-mention": {
       id: "/_page/docs/api/rich-text-mention";
-      path: "/rich-text-mention";
+      path: "/docs/api/rich-text-mention";
       fullPath: "/docs/api/rich-text-mention";
       preLoaderRoute: typeof PageDocsApiRichTextMentionRouteImport;
-      parentRoute: typeof PageDocsApiRoute;
+      parentRoute: typeof PageRoute;
     };
     "/_page/docs/api/rich-text-mention-react": {
       id: "/_page/docs/api/rich-text-mention-react";
-      path: "/rich-text-mention-react";
+      path: "/docs/api/rich-text-mention-react";
       fullPath: "/docs/api/rich-text-mention-react";
       preLoaderRoute: typeof PageDocsApiRichTextMentionReactRouteImport;
-      parentRoute: typeof PageDocsApiRoute;
+      parentRoute: typeof PageRoute;
     };
     "/_page/docs/api/rich-text-react": {
       id: "/_page/docs/api/rich-text-react";
-      path: "/rich-text-react";
+      path: "/docs/api/rich-text-react";
       fullPath: "/docs/api/rich-text-react";
       preLoaderRoute: typeof PageDocsApiRichTextReactRouteImport;
-      parentRoute: typeof PageDocsApiRoute;
+      parentRoute: typeof PageRoute;
     };
     "/_page/docs/api/rich-text-suggestion": {
       id: "/_page/docs/api/rich-text-suggestion";
-      path: "/rich-text-suggestion";
+      path: "/docs/api/rich-text-suggestion";
       fullPath: "/docs/api/rich-text-suggestion";
       preLoaderRoute: typeof PageDocsApiRichTextSuggestionRouteImport;
-      parentRoute: typeof PageDocsApiRoute;
+      parentRoute: typeof PageRoute;
     };
     "/_page/docs/api/rich-text-suggestion-react": {
       id: "/_page/docs/api/rich-text-suggestion-react";
-      path: "/rich-text-suggestion-react";
+      path: "/docs/api/rich-text-suggestion-react";
       fullPath: "/docs/api/rich-text-suggestion-react";
       preLoaderRoute: typeof PageDocsApiRichTextSuggestionReactRouteImport;
-      parentRoute: typeof PageDocsApiRoute;
+      parentRoute: typeof PageRoute;
     };
     "/_page/docs/api/rich-text-web": {
       id: "/_page/docs/api/rich-text-web";
-      path: "/rich-text-web";
+      path: "/docs/api/rich-text-web";
       fullPath: "/docs/api/rich-text-web";
       preLoaderRoute: typeof PageDocsApiRichTextWebRouteImport;
-      parentRoute: typeof PageDocsApiRoute;
+      parentRoute: typeof PageRoute;
     };
     "/_page/docs/api/selection": {
       id: "/_page/docs/api/selection";
-      path: "/selection";
+      path: "/docs/api/selection";
       fullPath: "/docs/api/selection";
       preLoaderRoute: typeof PageDocsApiSelectionRouteImport;
-      parentRoute: typeof PageDocsApiRoute;
+      parentRoute: typeof PageRoute;
     };
     "/_page/docs/api/tanstack-table": {
       id: "/_page/docs/api/tanstack-table";
-      path: "/tanstack-table";
+      path: "/docs/api/tanstack-table";
       fullPath: "/docs/api/tanstack-table";
       preLoaderRoute: typeof PageDocsApiTanstackTableRouteImport;
-      parentRoute: typeof PageDocsApiRoute;
+      parentRoute: typeof PageRoute;
     };
     "/_page/docs/api/ui-primitives-react": {
       id: "/_page/docs/api/ui-primitives-react";
-      path: "/ui-primitives-react";
+      path: "/docs/api/ui-primitives-react";
       fullPath: "/docs/api/ui-primitives-react";
       preLoaderRoute: typeof PageDocsApiUiPrimitivesReactRouteImport;
-      parentRoute: typeof PageDocsApiRoute;
+      parentRoute: typeof PageRoute;
     };
     "/_page/docs/api/web": {
       id: "/_page/docs/api/web";
-      path: "/web";
+      path: "/docs/api/web";
       fullPath: "/docs/api/web";
       preLoaderRoute: typeof PageDocsApiWebRouteImport;
-      parentRoute: typeof PageDocsApiRoute;
+      parentRoute: typeof PageRoute;
     };
     "/_page/docs/api/zod": {
       id: "/_page/docs/api/zod";
-      path: "/zod";
+      path: "/docs/api/zod";
       fullPath: "/docs/api/zod";
       preLoaderRoute: typeof PageDocsApiZodRouteImport;
-      parentRoute: typeof PageDocsApiRoute;
+      parentRoute: typeof PageRoute;
     };
     "/_page/docs/collaboration/": {
       id: "/_page/docs/collaboration/";
@@ -3068,78 +3106,6 @@ declare module "@tanstack/react-router" {
   }
 }
 
-interface PageDocsApiRouteChildren {
-  PageDocsApiA2uiRoute: typeof PageDocsApiA2uiRoute;
-  PageDocsApiAffordanceRoute: typeof PageDocsApiAffordanceRoute;
-  PageDocsApiAjvRoute: typeof PageDocsApiAjvRoute;
-  PageDocsApiAnimationReactRoute: typeof PageDocsApiAnimationReactRoute;
-  PageDocsApiAnnotationRoute: typeof PageDocsApiAnnotationRoute;
-  PageDocsApiCalendarRoute: typeof PageDocsApiCalendarRoute;
-  PageDocsApiCollaborationRoute: typeof PageDocsApiCollaborationRoute;
-  PageDocsApiComposerRoute: typeof PageDocsApiComposerRoute;
-  PageDocsApiComposerReactRoute: typeof PageDocsApiComposerReactRoute;
-  PageDocsApiContenteditableRoute: typeof PageDocsApiContenteditableRoute;
-  PageDocsApiContenteditableCollaborationRoute: typeof PageDocsApiContenteditableCollaborationRoute;
-  PageDocsApiDatabaseRoute: typeof PageDocsApiDatabaseRoute;
-  PageDocsApiEditingRoute: typeof PageDocsApiEditingRoute;
-  PageDocsApiFileIntakeRoute: typeof PageDocsApiFileIntakeRoute;
-  PageDocsApiJsonDocumentRoute: typeof PageDocsApiJsonDocumentRoute;
-  PageDocsApiMarkdownReactRoute: typeof PageDocsApiMarkdownReactRoute;
-  PageDocsApiReactRoute: typeof PageDocsApiReactRoute;
-  PageDocsApiReactHookFormRoute: typeof PageDocsApiReactHookFormRoute;
-  PageDocsApiRichTextRoute: typeof PageDocsApiRichTextRoute;
-  PageDocsApiRichTextMentionRoute: typeof PageDocsApiRichTextMentionRoute;
-  PageDocsApiRichTextMentionReactRoute: typeof PageDocsApiRichTextMentionReactRoute;
-  PageDocsApiRichTextReactRoute: typeof PageDocsApiRichTextReactRoute;
-  PageDocsApiRichTextSuggestionRoute: typeof PageDocsApiRichTextSuggestionRoute;
-  PageDocsApiRichTextSuggestionReactRoute: typeof PageDocsApiRichTextSuggestionReactRoute;
-  PageDocsApiRichTextWebRoute: typeof PageDocsApiRichTextWebRoute;
-  PageDocsApiSelectionRoute: typeof PageDocsApiSelectionRoute;
-  PageDocsApiTanstackTableRoute: typeof PageDocsApiTanstackTableRoute;
-  PageDocsApiUiPrimitivesReactRoute: typeof PageDocsApiUiPrimitivesReactRoute;
-  PageDocsApiWebRoute: typeof PageDocsApiWebRoute;
-  PageDocsApiZodRoute: typeof PageDocsApiZodRoute;
-}
-
-const PageDocsApiRouteChildren: PageDocsApiRouteChildren = {
-  PageDocsApiA2uiRoute: PageDocsApiA2uiRoute,
-  PageDocsApiAffordanceRoute: PageDocsApiAffordanceRoute,
-  PageDocsApiAjvRoute: PageDocsApiAjvRoute,
-  PageDocsApiAnimationReactRoute: PageDocsApiAnimationReactRoute,
-  PageDocsApiAnnotationRoute: PageDocsApiAnnotationRoute,
-  PageDocsApiCalendarRoute: PageDocsApiCalendarRoute,
-  PageDocsApiCollaborationRoute: PageDocsApiCollaborationRoute,
-  PageDocsApiComposerRoute: PageDocsApiComposerRoute,
-  PageDocsApiComposerReactRoute: PageDocsApiComposerReactRoute,
-  PageDocsApiContenteditableRoute: PageDocsApiContenteditableRoute,
-  PageDocsApiContenteditableCollaborationRoute:
-    PageDocsApiContenteditableCollaborationRoute,
-  PageDocsApiDatabaseRoute: PageDocsApiDatabaseRoute,
-  PageDocsApiEditingRoute: PageDocsApiEditingRoute,
-  PageDocsApiFileIntakeRoute: PageDocsApiFileIntakeRoute,
-  PageDocsApiJsonDocumentRoute: PageDocsApiJsonDocumentRoute,
-  PageDocsApiMarkdownReactRoute: PageDocsApiMarkdownReactRoute,
-  PageDocsApiReactRoute: PageDocsApiReactRoute,
-  PageDocsApiReactHookFormRoute: PageDocsApiReactHookFormRoute,
-  PageDocsApiRichTextRoute: PageDocsApiRichTextRoute,
-  PageDocsApiRichTextMentionRoute: PageDocsApiRichTextMentionRoute,
-  PageDocsApiRichTextMentionReactRoute: PageDocsApiRichTextMentionReactRoute,
-  PageDocsApiRichTextReactRoute: PageDocsApiRichTextReactRoute,
-  PageDocsApiRichTextSuggestionRoute: PageDocsApiRichTextSuggestionRoute,
-  PageDocsApiRichTextSuggestionReactRoute:
-    PageDocsApiRichTextSuggestionReactRoute,
-  PageDocsApiRichTextWebRoute: PageDocsApiRichTextWebRoute,
-  PageDocsApiSelectionRoute: PageDocsApiSelectionRoute,
-  PageDocsApiTanstackTableRoute: PageDocsApiTanstackTableRoute,
-  PageDocsApiUiPrimitivesReactRoute: PageDocsApiUiPrimitivesReactRoute,
-  PageDocsApiWebRoute: PageDocsApiWebRoute,
-  PageDocsApiZodRoute: PageDocsApiZodRoute,
-};
-
-const PageDocsApiRouteWithChildren = PageDocsApiRoute._addFileChildren(
-  PageDocsApiRouteChildren,
-);
-
 interface PageRouteChildren {
   PageDemosRoute: typeof PageDemosRoute;
   PageEditorsRoute: typeof PageEditorsRoute;
@@ -3186,7 +3152,7 @@ interface PageRouteChildren {
   PageDocsAdapterVirtualSelectionRoute: typeof PageDocsAdapterVirtualSelectionRoute;
   PageDocsAdaptersRoute: typeof PageDocsAdaptersRoute;
   PageDocsAnimationRoute: typeof PageDocsAnimationRoute;
-  PageDocsApiRoute: typeof PageDocsApiRouteWithChildren;
+  PageDocsBuildingBlocksRoute: typeof PageDocsBuildingBlocksRoute;
   PageDocsClipboardRoute: typeof PageDocsClipboardRoute;
   PageDocsComposerRoute: typeof PageDocsComposerRoute;
   PageDocsConceptsRoute: typeof PageDocsConceptsRoute;
@@ -3199,6 +3165,7 @@ interface PageRouteChildren {
   PageDocsConnectorZodValidateRoute: typeof PageDocsConnectorZodValidateRoute;
   PageDocsConnectorsRoute: typeof PageDocsConnectorsRoute;
   PageDocsDatabaseRoute: typeof PageDocsDatabaseRoute;
+  PageDocsEditingRoute: typeof PageDocsEditingRoute;
   PageDocsFoundationRoute: typeof PageDocsFoundationRoute;
   PageDocsHistoryRoute: typeof PageDocsHistoryRoute;
   PageDocsHowWeBuildRoute: typeof PageDocsHowWeBuildRoute;
@@ -3256,12 +3223,43 @@ interface PageRouteChildren {
   PageDocsAffordanceTripleClickRoute: typeof PageDocsAffordanceTripleClickRoute;
   PageDocsAffordanceTypeaheadRoute: typeof PageDocsAffordanceTypeaheadRoute;
   PageDocsAffordanceZoomRoute: typeof PageDocsAffordanceZoomRoute;
+  PageDocsApiA2uiRoute: typeof PageDocsApiA2uiRoute;
+  PageDocsApiAffordanceRoute: typeof PageDocsApiAffordanceRoute;
+  PageDocsApiAjvRoute: typeof PageDocsApiAjvRoute;
+  PageDocsApiAnimationReactRoute: typeof PageDocsApiAnimationReactRoute;
+  PageDocsApiAnnotationRoute: typeof PageDocsApiAnnotationRoute;
+  PageDocsApiCalendarRoute: typeof PageDocsApiCalendarRoute;
+  PageDocsApiCollaborationRoute: typeof PageDocsApiCollaborationRoute;
+  PageDocsApiComposerRoute: typeof PageDocsApiComposerRoute;
+  PageDocsApiComposerReactRoute: typeof PageDocsApiComposerReactRoute;
+  PageDocsApiContenteditableRoute: typeof PageDocsApiContenteditableRoute;
+  PageDocsApiContenteditableCollaborationRoute: typeof PageDocsApiContenteditableCollaborationRoute;
+  PageDocsApiDatabaseRoute: typeof PageDocsApiDatabaseRoute;
+  PageDocsApiEditingRoute: typeof PageDocsApiEditingRoute;
+  PageDocsApiFileIntakeRoute: typeof PageDocsApiFileIntakeRoute;
+  PageDocsApiJsonDocumentRoute: typeof PageDocsApiJsonDocumentRoute;
+  PageDocsApiMarkdownReactRoute: typeof PageDocsApiMarkdownReactRoute;
+  PageDocsApiReactRoute: typeof PageDocsApiReactRoute;
+  PageDocsApiReactHookFormRoute: typeof PageDocsApiReactHookFormRoute;
+  PageDocsApiRichTextRoute: typeof PageDocsApiRichTextRoute;
+  PageDocsApiRichTextMentionRoute: typeof PageDocsApiRichTextMentionRoute;
+  PageDocsApiRichTextMentionReactRoute: typeof PageDocsApiRichTextMentionReactRoute;
+  PageDocsApiRichTextReactRoute: typeof PageDocsApiRichTextReactRoute;
+  PageDocsApiRichTextSuggestionRoute: typeof PageDocsApiRichTextSuggestionRoute;
+  PageDocsApiRichTextSuggestionReactRoute: typeof PageDocsApiRichTextSuggestionReactRoute;
+  PageDocsApiRichTextWebRoute: typeof PageDocsApiRichTextWebRoute;
+  PageDocsApiSelectionRoute: typeof PageDocsApiSelectionRoute;
+  PageDocsApiTanstackTableRoute: typeof PageDocsApiTanstackTableRoute;
+  PageDocsApiUiPrimitivesReactRoute: typeof PageDocsApiUiPrimitivesReactRoute;
+  PageDocsApiWebRoute: typeof PageDocsApiWebRoute;
+  PageDocsApiZodRoute: typeof PageDocsApiZodRoute;
   PageDocsCollaborationHistoryRoute: typeof PageDocsCollaborationHistoryRoute;
   PageDocsCollaborationLifecycleRoute: typeof PageDocsCollaborationLifecycleRoute;
   PageDocsCollaborationReplicaRoute: typeof PageDocsCollaborationReplicaRoute;
   PageDocsDocumentTypesCandidateRoute: typeof PageDocsDocumentTypesCandidateRoute;
   PageConnectorsZodIndexRoute: typeof PageConnectorsZodIndexRoute;
   PageDocsAffordanceIndexRoute: typeof PageDocsAffordanceIndexRoute;
+  PageDocsApiIndexRoute: typeof PageDocsApiIndexRoute;
   PageDocsCollaborationIndexRoute: typeof PageDocsCollaborationIndexRoute;
   PageDocsDocumentTypesIndexRoute: typeof PageDocsDocumentTypesIndexRoute;
   PageDocsCollaborationTextLeaseRoute: typeof PageDocsCollaborationTextLeaseRoute;
@@ -3314,7 +3312,7 @@ const PageRouteChildren: PageRouteChildren = {
   PageDocsAdapterVirtualSelectionRoute: PageDocsAdapterVirtualSelectionRoute,
   PageDocsAdaptersRoute: PageDocsAdaptersRoute,
   PageDocsAnimationRoute: PageDocsAnimationRoute,
-  PageDocsApiRoute: PageDocsApiRouteWithChildren,
+  PageDocsBuildingBlocksRoute: PageDocsBuildingBlocksRoute,
   PageDocsClipboardRoute: PageDocsClipboardRoute,
   PageDocsComposerRoute: PageDocsComposerRoute,
   PageDocsConceptsRoute: PageDocsConceptsRoute,
@@ -3327,6 +3325,7 @@ const PageRouteChildren: PageRouteChildren = {
   PageDocsConnectorZodValidateRoute: PageDocsConnectorZodValidateRoute,
   PageDocsConnectorsRoute: PageDocsConnectorsRoute,
   PageDocsDatabaseRoute: PageDocsDatabaseRoute,
+  PageDocsEditingRoute: PageDocsEditingRoute,
   PageDocsFoundationRoute: PageDocsFoundationRoute,
   PageDocsHistoryRoute: PageDocsHistoryRoute,
   PageDocsHowWeBuildRoute: PageDocsHowWeBuildRoute,
@@ -3384,12 +3383,45 @@ const PageRouteChildren: PageRouteChildren = {
   PageDocsAffordanceTripleClickRoute: PageDocsAffordanceTripleClickRoute,
   PageDocsAffordanceTypeaheadRoute: PageDocsAffordanceTypeaheadRoute,
   PageDocsAffordanceZoomRoute: PageDocsAffordanceZoomRoute,
+  PageDocsApiA2uiRoute: PageDocsApiA2uiRoute,
+  PageDocsApiAffordanceRoute: PageDocsApiAffordanceRoute,
+  PageDocsApiAjvRoute: PageDocsApiAjvRoute,
+  PageDocsApiAnimationReactRoute: PageDocsApiAnimationReactRoute,
+  PageDocsApiAnnotationRoute: PageDocsApiAnnotationRoute,
+  PageDocsApiCalendarRoute: PageDocsApiCalendarRoute,
+  PageDocsApiCollaborationRoute: PageDocsApiCollaborationRoute,
+  PageDocsApiComposerRoute: PageDocsApiComposerRoute,
+  PageDocsApiComposerReactRoute: PageDocsApiComposerReactRoute,
+  PageDocsApiContenteditableRoute: PageDocsApiContenteditableRoute,
+  PageDocsApiContenteditableCollaborationRoute:
+    PageDocsApiContenteditableCollaborationRoute,
+  PageDocsApiDatabaseRoute: PageDocsApiDatabaseRoute,
+  PageDocsApiEditingRoute: PageDocsApiEditingRoute,
+  PageDocsApiFileIntakeRoute: PageDocsApiFileIntakeRoute,
+  PageDocsApiJsonDocumentRoute: PageDocsApiJsonDocumentRoute,
+  PageDocsApiMarkdownReactRoute: PageDocsApiMarkdownReactRoute,
+  PageDocsApiReactRoute: PageDocsApiReactRoute,
+  PageDocsApiReactHookFormRoute: PageDocsApiReactHookFormRoute,
+  PageDocsApiRichTextRoute: PageDocsApiRichTextRoute,
+  PageDocsApiRichTextMentionRoute: PageDocsApiRichTextMentionRoute,
+  PageDocsApiRichTextMentionReactRoute: PageDocsApiRichTextMentionReactRoute,
+  PageDocsApiRichTextReactRoute: PageDocsApiRichTextReactRoute,
+  PageDocsApiRichTextSuggestionRoute: PageDocsApiRichTextSuggestionRoute,
+  PageDocsApiRichTextSuggestionReactRoute:
+    PageDocsApiRichTextSuggestionReactRoute,
+  PageDocsApiRichTextWebRoute: PageDocsApiRichTextWebRoute,
+  PageDocsApiSelectionRoute: PageDocsApiSelectionRoute,
+  PageDocsApiTanstackTableRoute: PageDocsApiTanstackTableRoute,
+  PageDocsApiUiPrimitivesReactRoute: PageDocsApiUiPrimitivesReactRoute,
+  PageDocsApiWebRoute: PageDocsApiWebRoute,
+  PageDocsApiZodRoute: PageDocsApiZodRoute,
   PageDocsCollaborationHistoryRoute: PageDocsCollaborationHistoryRoute,
   PageDocsCollaborationLifecycleRoute: PageDocsCollaborationLifecycleRoute,
   PageDocsCollaborationReplicaRoute: PageDocsCollaborationReplicaRoute,
   PageDocsDocumentTypesCandidateRoute: PageDocsDocumentTypesCandidateRoute,
   PageConnectorsZodIndexRoute: PageConnectorsZodIndexRoute,
   PageDocsAffordanceIndexRoute: PageDocsAffordanceIndexRoute,
+  PageDocsApiIndexRoute: PageDocsApiIndexRoute,
   PageDocsCollaborationIndexRoute: PageDocsCollaborationIndexRoute,
   PageDocsDocumentTypesIndexRoute: PageDocsDocumentTypesIndexRoute,
   PageDocsCollaborationTextLeaseRoute: PageDocsCollaborationTextLeaseRoute,
diff --git a/site/src/app/routes/__root.tsx b/site/src/app/routes/__root.tsx
index b87c333f..8f47c8c8 100644
--- a/site/src/app/routes/__root.tsx
+++ b/site/src/app/routes/__root.tsx
@@ -60,7 +60,7 @@ function AppShell() {
                 key={section.id}
                 to={section.path}
                 activePath={route.path}
-                className={classes(ui.nav.railItem, section.separated ? ui.nav.railSeparatedItem : undefined, ui.nav.current)}
+                className={classes(ui.nav.railItem, ui.nav.current)}
               >
                 <span className="sr-only">{section.label}</span>
                 <NavigationLayerIcon section={section.id} />
@@ -100,28 +100,18 @@ function AppShell() {
               item.navigationGroup !== undefined
               && section.groups.includes(item.navigationGroup)
               && item.sidebar !== false
-              && !item.path.startsWith("/docs/api")
+              && !item.path.startsWith("/docs/api/")
             );
+            const landingRoute = siteRoutes.find((item) => item.path === section.path && item.navigationGroup === undefined);
             const sectionLabelId = `site-navigation-${section.id}`;
             const open = openSections.has(section.id);
-            if (section.groups.length === 0) return (
-              <ActionLink
-                key={section.id}
-                to={section.path}
-                activePath={route.path}
-                className={classes(ui.nav.item, section.separated ? ui.nav.separatedGroup : undefined, ui.nav.current)}
-              >
-                <NavigationLayerIcon section={section.id} className="shrink-0" />
-                {section.label}
-              </ActionLink>
-            );
             if (sectionRoutes.length === 0) return null;
             return (
               <div
                 key={section.id}
                 role="group"
                 aria-label={section.label}
-                className={classes("grid content-start", section.separated ? ui.nav.separatedGroup : undefined)}
+                className="grid content-start"
               >
                 <DisclosureButton
                   className={classes(ui.nav.groupToggle, activeSection?.id === section.id ? ui.nav.groupActive : ui.nav.groupIdle)}
@@ -148,6 +138,7 @@ function AppShell() {
                   data-open={open ? "true" : undefined}
                   hidden={!open}
                 >
+                  {open && landingRoute ? <NavItem item={landingRoute} currentPath={route.path} routes={siteRoutes} depth={0} /> : null}
                   {open
                     ? section.groups.map((group) => {
                       const groupRoutes = sectionRoutes.filter((item) => {
diff --git a/site/src/app/routes/_page/docs/api.tsx b/site/src/app/routes/_page/docs/api.tsx
deleted file mode 100644
index efaf4142..00000000
--- a/site/src/app/routes/_page/docs/api.tsx
+++ /dev/null
@@ -1,6 +0,0 @@
-import { createFileRoute } from "@tanstack/react-router";
-import { ApiReferenceRoute } from "../../../../routes/docs/DocsRoute";
-
-export const Route = createFileRoute("/_page/docs/api")({
-  component: ApiReferenceRoute,
-});
diff --git a/site/src/app/routes/_page/docs/api/index.tsx b/site/src/app/routes/_page/docs/api/index.tsx
new file mode 100644
index 00000000..95c6d7b3
--- /dev/null
+++ b/site/src/app/routes/_page/docs/api/index.tsx
@@ -0,0 +1,6 @@
+import { createFileRoute } from "@tanstack/react-router";
+import { ApiReferenceRoute } from "../../../../../routes/docs/DocsRoute";
+
+export const Route = createFileRoute("/_page/docs/api/")({
+  component: ApiReferenceRoute,
+});
diff --git a/site/src/app/routes/_page/docs/building-blocks.tsx b/site/src/app/routes/_page/docs/building-blocks.tsx
new file mode 100644
index 00000000..15eec15a
--- /dev/null
+++ b/site/src/app/routes/_page/docs/building-blocks.tsx
@@ -0,0 +1,6 @@
+import { createFileRoute } from "@tanstack/react-router";
+import { DocsRoute } from "../../../../routes/docs/DocsRoute";
+
+export const Route = createFileRoute("/_page/docs/building-blocks")({
+  component: () => <DocsRoute pageId="buildingBlocks" />,
+});
diff --git a/site/src/app/routes/_page/docs/editing.tsx b/site/src/app/routes/_page/docs/editing.tsx
new file mode 100644
index 00000000..2226ae8e
--- /dev/null
+++ b/site/src/app/routes/_page/docs/editing.tsx
@@ -0,0 +1,6 @@
+import { createFileRoute } from "@tanstack/react-router";
+import { DocsRoute } from "../../../../routes/docs/DocsRoute";
+
+export const Route = createFileRoute("/_page/docs/editing")({
+  component: () => <DocsRoute pageId="editing" />,
+});
diff --git a/site/src/app/site-layers.ts b/site/src/app/site-layers.ts
index 06762b45..a5443752 100644
--- a/site/src/app/site-layers.ts
+++ b/site/src/app/site-layers.ts
@@ -1,19 +1,18 @@
 import { type SiteNavigationGroup } from "./page-descriptors";
 
 export type SiteSection = {
-  readonly id: "introduce" | "foundation" | "building-blocks" | "hands" | "artifact" | "applications" | "reference";
+  readonly id: "introduction" | "foundation" | "building-blocks" | "hands" | "artifact" | "applications";
   readonly path: string;
   readonly label: string;
   readonly blurb: string;
   readonly groups: ReadonlyArray<SiteNavigationGroup>;
-  readonly separated?: boolean;
 };
 
 export const siteSections: ReadonlyArray<SiteSection> = [
   {
-    id: "introduce",
+    id: "introduction",
     path: "/docs",
-    label: "Introduce",
+    label: "Introduction",
     blurb: "Why, concepts, and how we build",
     groups: ["Introduction"],
   },
@@ -26,7 +25,7 @@ export const siteSections: ReadonlyArray<SiteSection> = [
   },
   {
     id: "building-blocks",
-    path: "/docs/adapters",
+    path: "/docs/building-blocks",
     label: "Building Blocks",
     blurb: "Platform, ecosystem, interaction, and UI",
     groups: ["Adapter", "Connector", "Affordance", "UI Primitives"],
@@ -52,14 +51,6 @@ export const siteSections: ReadonlyArray<SiteSection> = [
     blurb: "Products that reveal reusable modules",
     groups: ["Applications"],
   },
-  {
-    id: "reference",
-    path: "/docs/api",
-    label: "Reference",
-    blurb: "Canonical package and API indexes",
-    groups: [],
-    separated: true,
-  },
 ];
 
 export type SiteSectionId = (typeof siteSections)[number]["id"];
diff --git a/site/src/routes/artifact-viewer/ArtifactViewerRoute.tsx b/site/src/routes/artifact-viewer/ArtifactViewerRoute.tsx
index b53cc1b3..71878458 100644
--- a/site/src/routes/artifact-viewer/ArtifactViewerRoute.tsx
+++ b/site/src/routes/artifact-viewer/ArtifactViewerRoute.tsx
@@ -21,8 +21,8 @@ export function ArtifactViewerRoute() {
 
   return (
     <>
-      <PageHeader label="Artifact · Content Prototype" title="Application이 다루는 콘텐츠 계약을 검증합니다." illustration="peek">
-        navigation이나 workflow를 소유하지 않고, 서로 다른 Application 안에서 계속 편집할 수 있는 content surface를 기록합니다.
+      <PageHeader title="Artifact · TBD" illustration="peek">
+        Application 안에서 MD·PPT·Sheet를 다루는 visual prototype입니다. JSON Document와 Hands의 연결, 파일 호환성과 Undo/Redo는 아직 검증하지 않았습니다.
       </PageHeader>
 
       <ProductShell
@@ -44,12 +44,11 @@ export function ArtifactViewerRoute() {
       </ProductShell>
 
       <section className={styles.futureMap()} aria-labelledby="viewer-model-title">
-        <p className={ui.text.label}>Dependency map</p>
-        <h2 id="viewer-model-title" className={ui.text.section}>Core와 Hands가 Application 안의 Artifact를 만듭니다.</h2>
+        <h2 id="viewer-model-title" className={ui.text.section}>목표와 완료 조건 · TBD</h2>
         <ol>
-          <li><strong>Core</strong><span>사람과 agent의 변경을 같은 계약에 남깁니다.</span></li>
-          <li><strong>Hands</strong><span>사람에게 익숙한 편집 도구를 붙입니다.</span></li>
-          <li><strong>Artifact</strong><span>Application 안에서 계속 다룰 수 있는 콘텐츠가 됩니다.</span></li>
+          <li><strong>현재</strong><span>한 Host chrome에서 콘텐츠 모양을 전환하는 시각 가설을 확인합니다.</span></li>
+          <li><strong>목표</strong><span>Document Type과 Hands를 연결해 콘텐츠를 편집하고 선택·History를 복원합니다.</span></li>
+          <li><strong>완료 증거</strong><span>정본 API·Usage·Source와 실제 편집·저장·다시 열기의 검증이 필요합니다. navigation과 workflow는 Application에 남습니다.</span></li>
         </ol>
       </section>
     </>
diff --git a/site/src/routes/docs/ConceptsRoute.tsx b/site/src/routes/docs/ConceptsRoute.tsx
index b3e7494d..687e36be 100644
--- a/site/src/routes/docs/ConceptsRoute.tsx
+++ b/site/src/routes/docs/ConceptsRoute.tsx
@@ -1,24 +1,7 @@
-import conceptsMarkdown from "../../../../docs/public/concepts.md?raw";
-import type { PetiteCatIllustration } from "../../shared/ui/primitives";
-import { docPages } from "./doc-pages";
-import { DocumentationPage } from "./DocumentationPage";
 import { DocsRoute } from "./DocsRoute";
 
-const editingConceptIllustrations: Record<"selection" | "history" | "clipboard", PetiteCatIllustration> = {
-  selection: "cursor",
-  history: "branch",
-  clipboard: "clipboard",
-};
-
 export function ConceptsRoute() {
-  return (
-    <EditingConceptRoute
-      title="Concept Map"
-      source={conceptsMarkdown}
-      illustration="sleep"
-      summary="JSON 값에서 시작해 사람이 편집하는 artifact가 되기까지의 책임과 의존 순서입니다."
-    />
-  );
+  return <DocsRoute pageId="concepts" />;
 }
 
 export function SelectionDocsRoute() {
@@ -32,25 +15,3 @@ export function HistoryDocsRoute() {
 export function ClipboardDocsRoute() {
   return <DocsRoute pageId="clipboard" />;
 }
-
-function EditingConceptRoute(props: {
-  readonly pageId?: keyof typeof editingConceptIllustrations;
-  readonly title?: string;
-  readonly source?: string;
-  readonly illustration?: PetiteCatIllustration;
-  readonly summary?: string;
-}) {
-  const page = props.pageId ? docPages[props.pageId] : undefined;
-  const title = props.title ?? page?.title ?? "";
-  const source = props.source ?? page?.source ?? "";
-  const illustration = props.illustration
-    ?? (props.pageId ? editingConceptIllustrations[props.pageId] : "cursor");
-  return (
-    <DocumentationPage
-      title={title}
-      source={source}
-      illustration={illustration}
-      summary={props.summary}
-    />
-  );
-}
diff --git a/site/src/routes/docs/DocsRoute.tsx b/site/src/routes/docs/DocsRoute.tsx
index 3a7b119d..b71f306f 100644
--- a/site/src/routes/docs/DocsRoute.tsx
+++ b/site/src/routes/docs/DocsRoute.tsx
@@ -4,7 +4,10 @@ import { DocumentationPage } from "./DocumentationPage";
 
 const docIllustrations: Record<DocPageId, PetiteCatIllustration> = {
   overview: "package",
+  concepts: "sleep",
   foundation: "braces",
+  buildingBlocks: "braces",
+  editing: "branch",
   howWeBuild: "branch",
   applications: "peek",
   documentTypes: "braces",
@@ -211,8 +214,9 @@ export function DocsRoute({ pageId }: { readonly pageId: DocPageId }) {
   const page = docPages[pageId];
   return (
     <DocumentationPage
-      title={page.heading ?? page.label}
+      title={page.heading ?? page.title.replace(/ - json-document$/, "")}
       source={page.source}
+      sourcePath={page.documentSource}
       illustration={docIllustrations[pageId]}
     />
   );
diff --git a/site/src/routes/docs/DocumentTypeCandidateRoute.tsx b/site/src/routes/docs/DocumentTypeCandidateRoute.tsx
index c86e6237..56a55ba8 100644
--- a/site/src/routes/docs/DocumentTypeCandidateRoute.tsx
+++ b/site/src/routes/docs/DocumentTypeCandidateRoute.tsx
@@ -39,6 +39,18 @@ fixture, copy, layout-only CSS, tests와 generated route는 제외합니다.
 ${name}은 현재 Document Type 후보입니다. 기존 package와 Hands에서 실제 책임을
 옮기거나 완료를 선언하지 않았습니다.
 
+## 목표 경계 · TBD
+
+| 책임 | 목표 owner | 남은 증거 |
+| --- | --- | --- |
+| Document Model · Schema · invariant | ${name} Document Type | 실제 소유자와 유효 상태의 공개 계약 |
+| Document Operation · Projection | ${name} Document Type | 의미 연산·파생 조회의 API와 소비자 연결 |
+| Selection · Intent · Clipboard · History | Editing | 문서 의미와 편집 lifecycle의 경계 |
+| 플랫폼 입력 · framework lifecycle · UI | Adapter · Connector · UI Primitives | Host local bypass 없이 공개 API로 연결 |
+
+이 표는 목표 책임 지도이며 새로운 package나 API를 확정한 목록이 아닙니다.
+현재 관찰된 모델과 이 경계 사이의 차이를 확인한 뒤 아래 완료 증거를 닫습니다.
+
 ## 왜 필요한가
 
 ${profile.why}
@@ -80,7 +92,7 @@ ${auditSource}
       title={`${name} Document Type · TBD`}
       source={source}
       illustration="braces"
-      summary="후보의 이름만 등록했으며 소유권과 구현 경계는 아직 확정하지 않았습니다."
+      summary="관찰된 schema와 목표 책임을 구분합니다. 후보별 owner 수렴과 공개 계약의 완료는 아직 TBD입니다."
     />
   );
 }
diff --git a/site/src/routes/docs/DocumentationPage.tsx b/site/src/routes/docs/DocumentationPage.tsx
index d953f08f..c5e28eea 100644
--- a/site/src/routes/docs/DocumentationPage.tsx
+++ b/site/src/routes/docs/DocumentationPage.tsx
@@ -1,24 +1,27 @@
-import { useMemo, type ReactNode } from "react";
+import { useLayoutEffect, useRef, useState, type ReactNode } from "react";
 import { ActionLink } from "../../shared/ui/interactive";
 import { PageFrame, PageHeader, type PetiteCatIllustration } from "../../shared/ui/primitives";
 import { classes, ui } from "../../shared/ui/styles";
-import { MarkdownViewer, markdownHeadings } from "./MarkdownViewer";
+import { MarkdownViewer } from "./MarkdownViewer";
 
 export function DocumentationPage(props: {
   readonly title: ReactNode;
   readonly source: string;
+  readonly sourcePath?: string;
   readonly illustration: PetiteCatIllustration;
   readonly summary?: ReactNode;
 }) {
-  const headings = useMemo(
-    () => markdownHeadings(props.source).filter((heading) => heading.level === 2),
-    [props.source],
-  );
+  const contentRef = useRef<HTMLDivElement>(null);
+  const [headings, setHeadings] = useState<ReadonlyArray<{ id: string; text: string }>>([]);
+  useLayoutEffect(() => {
+    setHeadings(Array.from(contentRef.current?.querySelectorAll("h2[data-doc-heading]") ?? [])
+      .map((heading) => ({ id: heading.id, text: heading.textContent ?? "" })));
+  }, [props.source]);
 
   return (
     <PageFrame>
       <div className="grid gap-8 lg:grid-cols-[minmax(0,1fr)_11rem]">
-        <div className="min-w-0" data-doc-content>
+        <div ref={contentRef} className="min-w-0" data-doc-content>
           <div className="mx-auto max-w-3xl">
             <PageHeader title={props.title} illustration={props.illustration}>
               {props.summary}
@@ -36,7 +39,7 @@ export function DocumentationPage(props: {
                 ))}
               </div>
             </nav>
-            <MarkdownViewer source={props.source} hideTitle />
+            <MarkdownViewer source={props.source} sourcePath={props.sourcePath} hideTitle />
           </div>
         </div>
 
diff --git a/site/src/routes/docs/MarkdownViewer.tsx b/site/src/routes/docs/MarkdownViewer.tsx
index 393c6766..7bf2ee91 100644
--- a/site/src/routes/docs/MarkdownViewer.tsx
+++ b/site/src/routes/docs/MarkdownViewer.tsx
@@ -1,4 +1,5 @@
 import rehypeSlug from "rehype-slug";
+import { pageDescriptors } from "../../app/page-descriptors";
 import { InlineCode } from "../../shared/ui/code-block";
 import { codeLanguage } from "../../shared/ui/code-tokens";
 import { ShikiSourceCodeBlock } from "../../shared/demo-workbench/ShikiSourceCodeBlock";
@@ -7,9 +8,11 @@ import { classes, ui } from "../../shared/ui/styles";
 import { LiveDemo } from "../../app/live-demo-registry";
 import { MarkdownContent } from "../../shared/ui/markdown-content";
 
-type MarkdownHeading = { id: string; level: number; text: string };
-
-export function MarkdownViewer({ source, hideTitle = false }: { source: string; hideTitle?: boolean }) {
+export function MarkdownViewer({ source, sourcePath = "docs/public/overview.md", hideTitle = false }: {
+  source: string;
+  sourcePath?: string;
+  hideTitle?: boolean;
+}) {
   return (
     <article className="min-w-0 max-w-full">
       <MarkdownContent
@@ -20,7 +23,7 @@ export function MarkdownViewer({ source, hideTitle = false }: { source: string;
             ? null
             : <h1 id={id} className={classes("mb-0 mt-0", ui.text.heading)}>{children}</h1>,
           h2: ({ children, id }) => (
-            <h2 id={id} className={classes("mb-0", ui.text.section)}>
+            <h2 id={id} data-doc-heading className={classes("mb-0", ui.text.section)}>
               {children}
             </h2>
           ),
@@ -41,7 +44,7 @@ export function MarkdownViewer({ source, hideTitle = false }: { source: string;
           },
           pre: ({ children }) => <>{children}</>,
           a: ({ href, children }) => {
-            const target = rewriteMarkdownHref(href);
+            const target = rewriteMarkdownHref(href, sourcePath);
             return target ? <ActionLink href={target}>{children}</ActionLink> : <span>{children}</span>;
           },
         }}
@@ -50,105 +53,16 @@ export function MarkdownViewer({ source, hideTitle = false }: { source: string;
   );
 }
 
-export function markdownHeadings(source: string): MarkdownHeading[] {
-  return source
-    .replace(/\r\n/g, "\n")
-    .split("\n")
-    .flatMap((line): MarkdownHeading[] => {
-      const heading = /^(#{1,3})\s+(.+)$/.exec(line.trim());
-      if (!heading) return [];
-
-      const text = stripInlineMarkdown(heading[2] ?? "");
-      return [{ id: headingId(text), level: heading[1]?.length ?? 1, text }];
-    });
-}
-
-function stripInlineMarkdown(text: string): string {
-  return text.replace(/`([^`]+)`/g, "$1").trim();
-}
-
-const markdownHrefs: Readonly<Record<string, string>> = {
-  "overview.md": "/docs",
-  "api.md": "/docs/api",
-  "concepts.md": "/docs/concepts",
-  "selection.md": "/docs/selection",
-  "history.md": "/docs/history",
-  "clipboard.md": "/docs/clipboard",
-  "topology.md": "/docs/topology",
-  "intent.md": "/docs/intent",
-  "intent-guide.md": "/docs/intent-guide",
-  "connectors.md": "/docs/connectors",
-  "connector-react.md": "/docs/connector-react",
-  "connector-react-hook-form.md": "/docs/connector-react-hook-form",
-  "connector-ajv.md": "/docs/connector-ajv",
-  "connector-zod.md": "/docs/connector-zod",
-  "connector-zod-validate.md": "/docs/connector-zod-validate",
-  "connector-tanstack-table.md": "/docs/connector-tanstack-table",
-  "react-editing.md": "/docs/react-editing",
-  "adapters.md": "/docs/adapters",
-  "adapter-keyboard.md": "/docs/adapter-keyboard",
-  "adapter-grid-cell.md": "/docs/adapter-grid-cell",
-  "adapter-interaction.md": "/docs/adapter-interaction",
-  "adapter-clipboard.md": "/docs/adapter-clipboard",
-  "adapter-contenteditable.md": "/docs/adapter-contenteditable",
-  "affordance.md": "/docs/affordance",
-  "affordance-select.md": "/docs/affordance/select",
-  "affordance-fold.md": "/docs/affordance/fold",
-  "affordance-drag.md": "/docs/affordance/drag",
-  "affordance-history.md": "/docs/affordance/history",
-  "affordance-focus.md": "/docs/affordance/focus",
-  "affordance-caret.md": "/docs/affordance/caret",
-  "affordance-typeahead.md": "/docs/affordance/typeahead",
-  "affordance-activate.md": "/docs/affordance/activate",
-  "affordance-cancel.md": "/docs/affordance/cancel",
-  "affordance-delete.md": "/docs/affordance/delete",
-  "affordance-rename.md": "/docs/affordance/rename",
-  "affordance-nudge.md": "/docs/affordance/nudge",
-  "affordance-hover.md": "/docs/affordance/hover",
-  "affordance-contextual.md": "/docs/affordance/contextual",
-  "affordance-double-click.md": "/docs/affordance/double-click",
-  "affordance-triple-click.md": "/docs/affordance/triple-click",
-  "affordance-context-menu.md": "/docs/affordance/context-menu",
-  "affordance-marquee.md": "/docs/affordance/marquee",
-  "affordance-drop.md": "/docs/affordance/drop",
-  "affordance-copy-drag.md": "/docs/affordance/copy-drag",
-  "affordance-handles.md": "/docs/affordance/handles",
-  "affordance-resize.md": "/docs/affordance/resize",
-  "affordance-pan.md": "/docs/affordance/pan",
-  "affordance-scroll.md": "/docs/affordance/scroll",
-  "affordance-zoom.md": "/docs/affordance/zoom",
-  "affordance-snap.md": "/docs/affordance/snap",
-  "affordance-forbid.md": "/docs/affordance/forbid",
-  "collaboration.md": "/docs/collaboration",
-  "collaboration-replica.md": "/docs/collaboration/replica",
-  "collaboration-history.md": "/docs/collaboration/history",
-  "collaboration-text.md": "/docs/collaboration/text",
-  "collaboration-lease.md": "/docs/collaboration/text/lease",
-  "collaboration-lifecycle.md": "/docs/collaboration/lifecycle",
-  "hands.md": "/editors",
-  "composer.md": "/docs/composer",
-  "mention.md": "/docs/mention",
-  "order.md": "/docs/order",
-  "object.md": "/docs/object",
-  "tree.md": "/docs/tree",
-  "database.md": "/docs/database",
-};
-
-function rewriteMarkdownHref(href: string | undefined): string | undefined {
-  if (!href) return href;
-  const file = href.replace(/^\.\//, "");
-  const hashIndex = file.indexOf("#");
-  const path = hashIndex === -1 ? file : file.slice(0, hashIndex);
-  const hash = hashIndex === -1 ? "" : file.slice(hashIndex);
-  const rewritten = markdownHrefs[path];
-  return rewritten ? `${rewritten}${hash}` : href;
-}
+const documentRoutes = new Map(
+  pageDescriptors.filter((page) => page.documentSource !== undefined)
+    .map((page) => [page.documentSource, page.path]),
+);
 
-function headingId(text: string): string {
-  return text
-    .trim()
-    .toLowerCase()
-    .replace(/[^\p{Letter}\p{Number}]+/gu, "-")
-    .replace(/^-+|-+$/g, "")
-    || "section";
+export function rewriteMarkdownHref(href: string | undefined, sourcePath: string): string | undefined {
+  if (!href || /^(?:[a-z][a-z\d+.-]*:|[/#?])/i.test(href)) return href;
+  const target = new URL(href, `https://documentation.invalid/${sourcePath}`);
+  if (!target.pathname.endsWith(".md")) return href;
+  const path = decodeURIComponent(target.pathname.slice(1));
+  const route = documentRoutes.get(path);
+  return `${route ?? `https://github.com/developer-1px/json-document/blob/main/${path}`}${target.search}${target.hash}`;
 }
diff --git a/site/src/routes/docs/doc-pages.ts b/site/src/routes/docs/doc-pages.ts
index 45bf72af..b1c32ee6 100644
--- a/site/src/routes/docs/doc-pages.ts
+++ b/site/src/routes/docs/doc-pages.ts
@@ -1,214 +1,123 @@
-import apiReferenceMarkdown from "../../../../docs/public/api.md?raw";
-import jsonDocumentApiMarkdown from "../../../../docs/api-reference/json-document.md?raw";
-import selectionApiMarkdown from "../../../../docs/api-reference/selection.md?raw";
-import editingApiMarkdown from "../../../../docs/api-reference/editing.md?raw";
-import reactApiMarkdown from "../../../../docs/api-reference/react.md?raw";
-import reactHookFormApiMarkdown from "../../../../docs/api-reference/react-hook-form.md?raw";
-import ajvApiMarkdown from "../../../../docs/api-reference/ajv.md?raw";
-import a2uiApiMarkdown from "../../../../docs/api-reference/a2ui.md?raw";
-import connectorA2uiMarkdown from "../../../../docs/public/connector-a2ui.md?raw";
-import zodApiMarkdown from "../../../../docs/api-reference/zod.md?raw";
-import tanStackTableApiMarkdown from "../../../../docs/api-reference/tanstack-table.md?raw";
-import affordanceApiMarkdown from "../../../../docs/api-reference/affordance.md?raw";
-import uiPrimitivesApiMarkdown from "../../../../docs/api-reference/ui-primitives-react.md?raw";
-import animationApiMarkdown from "../../../../docs/api-reference/animation-react.md?raw";
-import markdownReactApiMarkdown from "../../../../docs/api-reference/markdown-react.md?raw";
-import databaseApiMarkdown from "../../../../docs/api-reference/database.md?raw";
-import annotationApiMarkdown from "../../../../docs/api-reference/annotation.md?raw";
-import calendarApiMarkdown from "../../../../docs/api-reference/calendar.md?raw";
-import webApiMarkdown from "../../../../docs/api-reference/web.md?raw";
-import contenteditableApiMarkdown from "../../../../docs/api-reference/contenteditable.md?raw";
-import richTextApiMarkdown from "../../../../docs/api-reference/rich-text.md?raw";
-import fileIntakeApiMarkdown from "../../../../docs/api-reference/file-intake.md?raw";
-import richTextSuggestionApiMarkdown from "../../../../docs/api-reference/rich-text-suggestion.md?raw";
-import richTextSuggestionReactApiMarkdown from "../../../../docs/api-reference/rich-text-suggestion-react.md?raw";
-import richTextMentionApiMarkdown from "../../../../docs/api-reference/rich-text-mention.md?raw";
-import richTextMentionReactApiMarkdown from "../../../../docs/api-reference/rich-text-mention-react.md?raw";
-import composerApiMarkdown from "../../../../docs/api-reference/composer.md?raw";
-import composerReactApiMarkdown from "../../../../docs/api-reference/composer-react.md?raw";
-import richTextWebApiMarkdown from "../../../../docs/api-reference/rich-text-web.md?raw";
-import richTextReactApiMarkdown from "../../../../docs/api-reference/rich-text-react.md?raw";
-import collaborationApiMarkdown from "../../../../docs/api-reference/collaboration.md?raw";
-import contenteditableCollaborationApiMarkdown from "../../../../docs/api-reference/contenteditable-collaboration.md?raw";
-import clipboardMarkdown from "../../../../docs/public/clipboard.md?raw";
-import affordanceMarkdown from "../../../../docs/public/affordance.md?raw";
-import uiPrimitivesMarkdown from "../../../../docs/public/ui-primitives.md?raw";
-import animationMarkdown from "../../../../docs/public/animation.md?raw";
-import affordanceDragMarkdown from "../../../../docs/public/affordance-drag.md?raw";
-import affordanceFoldMarkdown from "../../../../docs/public/affordance-fold.md?raw";
-import affordanceHistoryMarkdown from "../../../../docs/public/affordance-history.md?raw";
-import affordanceSelectMarkdown from "../../../../docs/public/affordance-select.md?raw";
-import affordanceFocusMarkdown from "../../../../docs/public/affordance-focus.md?raw";
-import affordanceCaretMarkdown from "../../../../docs/public/affordance-caret.md?raw";
-import affordanceTypeaheadMarkdown from "../../../../docs/public/affordance-typeahead.md?raw";
-import affordanceActivateMarkdown from "../../../../docs/public/affordance-activate.md?raw";
-import affordanceCancelMarkdown from "../../../../docs/public/affordance-cancel.md?raw";
-import affordanceDeleteMarkdown from "../../../../docs/public/affordance-delete.md?raw";
-import affordanceRenameMarkdown from "../../../../docs/public/affordance-rename.md?raw";
-import affordanceNudgeMarkdown from "../../../../docs/public/affordance-nudge.md?raw";
-import affordanceHoverMarkdown from "../../../../docs/public/affordance-hover.md?raw";
-import affordanceContextualMarkdown from "../../../../docs/public/affordance-contextual.md?raw";
-import affordanceDoubleClickMarkdown from "../../../../docs/public/affordance-double-click.md?raw";
-import affordanceTripleClickMarkdown from "../../../../docs/public/affordance-triple-click.md?raw";
-import affordanceContextMenuMarkdown from "../../../../docs/public/affordance-context-menu.md?raw";
-import affordanceMarqueeMarkdown from "../../../../docs/public/affordance-marquee.md?raw";
-import affordanceDropMarkdown from "../../../../docs/public/affordance-drop.md?raw";
-import affordanceCopyDragMarkdown from "../../../../docs/public/affordance-copy-drag.md?raw";
-import affordanceHandlesMarkdown from "../../../../docs/public/affordance-handles.md?raw";
-import affordanceResizeMarkdown from "../../../../docs/public/affordance-resize.md?raw";
-import affordancePanMarkdown from "../../../../docs/public/affordance-pan.md?raw";
-import affordanceScrollMarkdown from "../../../../docs/public/affordance-scroll.md?raw";
-import affordanceZoomMarkdown from "../../../../docs/public/affordance-zoom.md?raw";
-import affordanceSnapMarkdown from "../../../../docs/public/affordance-snap.md?raw";
-import affordanceForbidMarkdown from "../../../../docs/public/affordance-forbid.md?raw";
-import adaptersMarkdown from "../../../../docs/public/adapters.md?raw";
-import adapterKeyboardMarkdown from "../../../../docs/public/adapter-keyboard.md?raw";
-import adapterGridCellMarkdown from "../../../../docs/public/adapter-grid-cell.md?raw";
-import adapterInteractionMarkdown from "../../../../docs/public/adapter-interaction.md?raw";
-import adapterClipboardMarkdown from "../../../../docs/public/adapter-clipboard.md?raw";
-import adapterVirtualSelectionMarkdown from "../../../../docs/public/adapter-virtual-selection.md?raw";
-import adapterContenteditableMarkdown from "../../../../docs/public/adapter-contenteditable.md?raw";
-import collaborationMarkdown from "../../../../docs/public/collaboration.md?raw";
-import collaborationHistoryMarkdown from "../../../../docs/public/collaboration-history.md?raw";
-import collaborationLeaseMarkdown from "../../../../docs/public/collaboration-lease.md?raw";
-import collaborationLifecycleMarkdown from "../../../../docs/public/collaboration-lifecycle.md?raw";
-import collaborationReplicaMarkdown from "../../../../docs/public/collaboration-replica.md?raw";
-import collaborationTextMarkdown from "../../../../docs/public/collaboration-text.md?raw";
-import connectorsMarkdown from "../../../../docs/public/connectors.md?raw";
-import connectorReactMarkdown from "../../../../docs/public/connector-react.md?raw";
-import connectorReactHookFormMarkdown from "../../../../docs/public/connector-react-hook-form.md?raw";
-import connectorAjvMarkdown from "../../../../docs/public/connector-ajv.md?raw";
-import connectorZodMarkdown from "../../../../docs/public/connector-zod.md?raw";
-import connectorZodValidateMarkdown from "../../../../docs/public/connector-zod-validate.md?raw";
-import connectorTanStackTableMarkdown from "../../../../docs/public/connector-tanstack-table.md?raw";
-import composerMarkdown from "../../../../docs/public/composer.md?raw";
-import handsMarkdown from "../../../../docs/public/hands.md?raw";
-import mentionMarkdown from "../../../../docs/public/mention.md?raw";
-import historyMarkdown from "../../../../docs/public/history.md?raw";
-import intentGuideMarkdown from "../../../../docs/public/intent-guide.md?raw";
-import intentMarkdown from "../../../../docs/public/intent.md?raw";
-import objectMarkdown from "../../../../docs/public/object.md?raw";
-import orderMarkdown from "../../../../docs/public/order.md?raw";
-import overviewMarkdown from "../../../../docs/public/overview.md?raw";
-import foundationMarkdown from "../../../../docs/public/foundation.md?raw";
-import reactEditingMarkdown from "../../../../docs/public/react-editing.md?raw";
-import selectionMarkdown from "../../../../docs/public/selection.md?raw";
-import topologyMarkdown from "../../../../docs/public/topology.md?raw";
-import treeMarkdown from "../../../../docs/public/tree.md?raw";
-import databaseMarkdown from "../../../../docs/public/database.md?raw";
-import officialHandsMarkdown from "../../../../docs/public/official-hands.md?raw";
-import documentTypesMarkdown from "../../../../docs/public/document-types.md?raw";
-import howWeBuildMarkdown from "../../../../docs/public/how-we-build.md?raw";
-import applicationsMarkdown from "../../../../docs/public/applications.md?raw";
 import { pageDescriptor } from "../../app/page-descriptors";
 
-function docPage(path: string, source: string) {
-  return { ...pageDescriptor(path), source };
+const documentSources = import.meta.glob<string>(
+  ["../../../../docs/public/*.md", "../../../../docs/api-reference/*.md"],
+  { query: "?raw", import: "default", eager: true },
+);
+
+function docPage(path: string) {
+  const page = pageDescriptor(path);
+  const source = documentSources[`../../../../${page.documentSource}`];
+  if (source === undefined) throw new Error(`Documentation source is not registered: ${path}`);
+  return { ...page, source };
 }
 
 export const docPages = {
-  overview: docPage("/docs", overviewMarkdown),
-  foundation: docPage("/docs/foundation", foundationMarkdown),
-  howWeBuild: docPage("/docs/how-we-build", howWeBuildMarkdown),
-  applications: docPage("/applications", applicationsMarkdown),
-  documentTypes: docPage("/docs/document-types", documentTypesMarkdown),
-  adapters: docPage("/docs/adapters", adaptersMarkdown),
-  adapterKeyboard: docPage("/docs/adapter-keyboard", adapterKeyboardMarkdown),
-  adapterGridCell: docPage("/docs/adapter-grid-cell", adapterGridCellMarkdown),
-  adapterInteraction: docPage("/docs/adapter-interaction", adapterInteractionMarkdown),
-  adapterClipboard: docPage("/docs/adapter-clipboard", adapterClipboardMarkdown),
-  adapterVirtualSelection: docPage("/docs/adapter-virtual-selection", adapterVirtualSelectionMarkdown),
-  adapterContenteditable: docPage("/docs/adapter-contenteditable", adapterContenteditableMarkdown),
-  affordance: docPage("/docs/affordance", affordanceMarkdown),
-  uiPrimitives: docPage("/docs/ui-primitives", uiPrimitivesMarkdown),
-  animation: docPage("/docs/animation", animationMarkdown),
-  affordanceSelect: docPage("/docs/affordance/select", affordanceSelectMarkdown),
-  affordanceFold: docPage("/docs/affordance/fold", affordanceFoldMarkdown),
-  affordanceDrag: docPage("/docs/affordance/drag", affordanceDragMarkdown),
-  affordanceHistory: docPage("/docs/affordance/history", affordanceHistoryMarkdown),
-  affordanceFocus: docPage("/docs/affordance/focus", affordanceFocusMarkdown),
-  affordanceCaret: docPage("/docs/affordance/caret", affordanceCaretMarkdown),
-  affordanceTypeahead: docPage("/docs/affordance/typeahead", affordanceTypeaheadMarkdown),
-  affordanceActivate: docPage("/docs/affordance/activate", affordanceActivateMarkdown),
-  affordanceCancel: docPage("/docs/affordance/cancel", affordanceCancelMarkdown),
-  affordanceDelete: docPage("/docs/affordance/delete", affordanceDeleteMarkdown),
-  affordanceRename: docPage("/docs/affordance/rename", affordanceRenameMarkdown),
-  affordanceNudge: docPage("/docs/affordance/nudge", affordanceNudgeMarkdown),
-  affordanceHover: docPage("/docs/affordance/hover", affordanceHoverMarkdown),
-  affordanceContextual: docPage("/docs/affordance/contextual", affordanceContextualMarkdown),
-  affordanceDoubleClick: docPage("/docs/affordance/double-click", affordanceDoubleClickMarkdown),
-  affordanceTripleClick: docPage("/docs/affordance/triple-click", affordanceTripleClickMarkdown),
-  affordanceContextMenu: docPage("/docs/affordance/context-menu", affordanceContextMenuMarkdown),
-  affordanceMarquee: docPage("/docs/affordance/marquee", affordanceMarqueeMarkdown),
-  affordanceDrop: docPage("/docs/affordance/drop", affordanceDropMarkdown),
-  affordanceCopyDrag: docPage("/docs/affordance/copy-drag", affordanceCopyDragMarkdown),
-  affordanceHandles: docPage("/docs/affordance/handles", affordanceHandlesMarkdown),
-  affordanceResize: docPage("/docs/affordance/resize", affordanceResizeMarkdown),
-  affordancePan: docPage("/docs/affordance/pan", affordancePanMarkdown),
-  affordanceScroll: docPage("/docs/affordance/scroll", affordanceScrollMarkdown),
-  affordanceZoom: docPage("/docs/affordance/zoom", affordanceZoomMarkdown),
-  affordanceSnap: docPage("/docs/affordance/snap", affordanceSnapMarkdown),
-  affordanceForbid: docPage("/docs/affordance/forbid", affordanceForbidMarkdown),
-  connectors: docPage("/docs/connectors", connectorsMarkdown),
-  connectorReact: docPage("/docs/connector-react", connectorReactMarkdown),
-  connectorReactHookForm: docPage("/docs/connector-react-hook-form", connectorReactHookFormMarkdown),
-  connectorAjv: docPage("/docs/connector-ajv", connectorAjvMarkdown),
-  connectorZod: docPage("/docs/connector-zod", connectorZodMarkdown),
-  connectorZodValidate: docPage("/docs/connector-zod-validate", connectorZodValidateMarkdown),
-  connectorTanStackTable: docPage("/docs/connector-tanstack-table", connectorTanStackTableMarkdown),
-  reactEditing: docPage("/docs/react-editing", reactEditingMarkdown),
-  collaboration: docPage("/docs/collaboration", collaborationMarkdown),
-  collaborationReplica: docPage("/docs/collaboration/replica", collaborationReplicaMarkdown),
-  collaborationHistory: docPage("/docs/collaboration/history", collaborationHistoryMarkdown),
-  collaborationText: docPage("/docs/collaboration/text", collaborationTextMarkdown),
-  collaborationLease: docPage("/docs/collaboration/text/lease", collaborationLeaseMarkdown),
-  collaborationLifecycle: docPage("/docs/collaboration/lifecycle", collaborationLifecycleMarkdown),
-  hands: docPage("/editors", handsMarkdown),
-  composer: docPage("/docs/composer", composerMarkdown),
-  mention: docPage("/docs/mention", mentionMarkdown),
-  order: docPage("/docs/order", orderMarkdown),
-  object: docPage("/docs/object", objectMarkdown),
-  tree: docPage("/docs/tree", treeMarkdown),
-  database: docPage("/docs/database", databaseMarkdown),
-  officialHands: docPage("/docs/official-hands", officialHandsMarkdown),
-  intent: docPage("/docs/intent", intentMarkdown),
-  intentGuide: docPage("/docs/intent-guide", intentGuideMarkdown),
-  api: docPage("/docs/api", apiReferenceMarkdown),
-  jsonDocumentApi: docPage("/docs/api/json-document", jsonDocumentApiMarkdown),
-  selectionApi: docPage("/docs/api/selection", selectionApiMarkdown),
-  editingApi: docPage("/docs/api/editing", editingApiMarkdown),
-  reactApi: docPage("/docs/api/react", reactApiMarkdown),
-  reactHookFormApi: docPage("/docs/api/react-hook-form", reactHookFormApiMarkdown),
-  ajvApi: docPage("/docs/api/ajv", ajvApiMarkdown),
-  a2uiApi: docPage("/docs/api/a2ui", a2uiApiMarkdown),
-  connectorA2ui: docPage("/docs/connector-a2ui", connectorA2uiMarkdown),
-  zodApi: docPage("/docs/api/zod", zodApiMarkdown),
-  tanStackTableApi: docPage("/docs/api/tanstack-table", tanStackTableApiMarkdown),
-  affordanceApi: docPage("/docs/api/affordance", affordanceApiMarkdown),
-  uiPrimitivesApi: docPage("/docs/api/ui-primitives-react", uiPrimitivesApiMarkdown),
-  animationApi: docPage("/docs/api/animation-react", animationApiMarkdown),
-  markdownReactApi: docPage("/docs/api/markdown-react", markdownReactApiMarkdown),
-  databaseApi: docPage("/docs/api/database", databaseApiMarkdown),
-  annotationApi: docPage("/docs/api/annotation", annotationApiMarkdown),
-  calendarApi: docPage("/docs/api/calendar", calendarApiMarkdown),
-  webApi: docPage("/docs/api/web", webApiMarkdown),
-  contenteditableApi: docPage("/docs/api/contenteditable", contenteditableApiMarkdown),
-  richTextApi: docPage("/docs/api/rich-text", richTextApiMarkdown),
-  fileIntakeApi: docPage("/docs/api/file-intake", fileIntakeApiMarkdown),
-  richTextSuggestionApi: docPage("/docs/api/rich-text-suggestion", richTextSuggestionApiMarkdown),
-  richTextSuggestionReactApi: docPage("/docs/api/rich-text-suggestion-react", richTextSuggestionReactApiMarkdown),
-  richTextMentionApi: docPage("/docs/api/rich-text-mention", richTextMentionApiMarkdown),
-  richTextMentionReactApi: docPage("/docs/api/rich-text-mention-react", richTextMentionReactApiMarkdown),
-  composerApi: docPage("/docs/api/composer", composerApiMarkdown),
-  composerReactApi: docPage("/docs/api/composer-react", composerReactApiMarkdown),
-  richTextWebApi: docPage("/docs/api/rich-text-web", richTextWebApiMarkdown),
-  richTextReactApi: docPage("/docs/api/rich-text-react", richTextReactApiMarkdown),
-  collaborationApi: docPage("/docs/api/collaboration", collaborationApiMarkdown),
-  contenteditableCollaborationApi: docPage("/docs/api/contenteditable-collaboration", contenteditableCollaborationApiMarkdown),
-  topology: docPage("/docs/topology", topologyMarkdown),
-  selection: docPage("/docs/selection", selectionMarkdown),
-  history: docPage("/docs/history", historyMarkdown),
-  clipboard: docPage("/docs/clipboard", clipboardMarkdown),
+  overview: docPage("/docs"),
+  concepts: docPage("/docs/concepts"),
+  foundation: docPage("/docs/foundation"),
+  buildingBlocks: docPage("/docs/building-blocks"),
+  editing: docPage("/docs/editing"),
+  howWeBuild: docPage("/docs/how-we-build"),
+  applications: docPage("/applications"),
+  documentTypes: docPage("/docs/document-types"),
+  adapters: docPage("/docs/adapters"),
+  adapterKeyboard: docPage("/docs/adapter-keyboard"),
+  adapterGridCell: docPage("/docs/adapter-grid-cell"),
+  adapterInteraction: docPage("/docs/adapter-interaction"),
+  adapterClipboard: docPage("/docs/adapter-clipboard"),
+  adapterVirtualSelection: docPage("/docs/adapter-virtual-selection"),
+  adapterContenteditable: docPage("/docs/adapter-contenteditable"),
+  affordance: docPage("/docs/affordance"),
+  uiPrimitives: docPage("/docs/ui-primitives"),
+  animation: docPage("/docs/animation"),
+  affordanceSelect: docPage("/docs/affordance/select"),
+  affordanceFold: docPage("/docs/affordance/fold"),
+  affordanceDrag: docPage("/docs/affordance/drag"),
+  affordanceHistory: docPage("/docs/affordance/history"),
+  affordanceFocus: docPage("/docs/affordance/focus"),
+  affordanceCaret: docPage("/docs/affordance/caret"),
+  affordanceTypeahead: docPage("/docs/affordance/typeahead"),
+  affordanceActivate: docPage("/docs/affordance/activate"),
+  affordanceCancel: docPage("/docs/affordance/cancel"),
+  affordanceDelete: docPage("/docs/affordance/delete"),
+  affordanceRename: docPage("/docs/affordance/rename"),
+  affordanceNudge: docPage("/docs/affordance/nudge"),
+  affordanceHover: docPage("/docs/affordance/hover"),
+  affordanceContextual: docPage("/docs/affordance/contextual"),
+  affordanceDoubleClick: docPage("/docs/affordance/double-click"),
+  affordanceTripleClick: docPage("/docs/affordance/triple-click"),
+  affordanceContextMenu: docPage("/docs/affordance/context-menu"),
+  affordanceMarquee: docPage("/docs/affordance/marquee"),
+  affordanceDrop: docPage("/docs/affordance/drop"),
+  affordanceCopyDrag: docPage("/docs/affordance/copy-drag"),
+  affordanceHandles: docPage("/docs/affordance/handles"),
+  affordanceResize: docPage("/docs/affordance/resize"),
+  affordancePan: docPage("/docs/affordance/pan"),
+  affordanceScroll: docPage("/docs/affordance/scroll"),
+  affordanceZoom: docPage("/docs/affordance/zoom"),
+  affordanceSnap: docPage("/docs/affordance/snap"),
+  affordanceForbid: docPage("/docs/affordance/forbid"),
+  connectors: docPage("/docs/connectors"),
+  connectorReact: docPage("/docs/connector-react"),
+  connectorReactHookForm: docPage("/docs/connector-react-hook-form"),
+  connectorAjv: docPage("/docs/connector-ajv"),
+  connectorZod: docPage("/docs/connector-zod"),
+  connectorZodValidate: docPage("/docs/connector-zod-validate"),
+  connectorTanStackTable: docPage("/docs/connector-tanstack-table"),
+  reactEditing: docPage("/docs/react-editing"),
+  collaboration: docPage("/docs/collaboration"),
+  collaborationReplica: docPage("/docs/collaboration/replica"),
+  collaborationHistory: docPage("/docs/collaboration/history"),
+  collaborationText: docPage("/docs/collaboration/text"),
+  collaborationLease: docPage("/docs/collaboration/text/lease"),
+  collaborationLifecycle: docPage("/docs/collaboration/lifecycle"),
+  hands: docPage("/editors"),
+  composer: docPage("/docs/composer"),
+  mention: docPage("/docs/mention"),
+  order: docPage("/docs/order"),
+  object: docPage("/docs/object"),
+  tree: docPage("/docs/tree"),
+  database: docPage("/docs/database"),
+  officialHands: docPage("/docs/official-hands"),
+  intent: docPage("/docs/intent"),
+  intentGuide: docPage("/docs/intent-guide"),
+  api: docPage("/docs/api"),
+  jsonDocumentApi: docPage("/docs/api/json-document"),
+  selectionApi: docPage("/docs/api/selection"),
+  editingApi: docPage("/docs/api/editing"),
+  reactApi: docPage("/docs/api/react"),
+  reactHookFormApi: docPage("/docs/api/react-hook-form"),
+  ajvApi: docPage("/docs/api/ajv"),
+  a2uiApi: docPage("/docs/api/a2ui"),
+  connectorA2ui: docPage("/docs/connector-a2ui"),
+  zodApi: docPage("/docs/api/zod"),
+  tanStackTableApi: docPage("/docs/api/tanstack-table"),
+  affordanceApi: docPage("/docs/api/affordance"),
+  uiPrimitivesApi: docPage("/docs/api/ui-primitives-react"),
+  animationApi: docPage("/docs/api/animation-react"),
+  markdownReactApi: docPage("/docs/api/markdown-react"),
+  databaseApi: docPage("/docs/api/database"),
+  annotationApi: docPage("/docs/api/annotation"),
+  calendarApi: docPage("/docs/api/calendar"),
+  webApi: docPage("/docs/api/web"),
+  contenteditableApi: docPage("/docs/api/contenteditable"),
+  richTextApi: docPage("/docs/api/rich-text"),
+  fileIntakeApi: docPage("/docs/api/file-intake"),
+  richTextSuggestionApi: docPage("/docs/api/rich-text-suggestion"),
+  richTextSuggestionReactApi: docPage("/docs/api/rich-text-suggestion-react"),
+  richTextMentionApi: docPage("/docs/api/rich-text-mention"),
+  richTextMentionReactApi: docPage("/docs/api/rich-text-mention-react"),
+  composerApi: docPage("/docs/api/composer"),
+  composerReactApi: docPage("/docs/api/composer-react"),
+  richTextWebApi: docPage("/docs/api/rich-text-web"),
+  richTextReactApi: docPage("/docs/api/rich-text-react"),
+  collaborationApi: docPage("/docs/api/collaboration"),
+  contenteditableCollaborationApi: docPage("/docs/api/contenteditable-collaboration"),
+  topology: docPage("/docs/topology"),
+  selection: docPage("/docs/selection"),
+  history: docPage("/docs/history"),
+  clipboard: docPage("/docs/clipboard"),
 } as const;
 
 export type DocPageId = keyof typeof docPages;
diff --git a/site/src/routes/home/HomeRoute.tsx b/site/src/routes/home/HomeRoute.tsx
index 794a0272..0fe18793 100644
--- a/site/src/routes/home/HomeRoute.tsx
+++ b/site/src/routes/home/HomeRoute.tsx
@@ -46,7 +46,7 @@ export function HomeRoute() {
             제품을 먼저 만들고, 그 안에서 발견한 책임을 모듈과 부품으로 되돌립니다.
           </p>
           <div className={homeStyles.actions()}>
-            <ActionLink to="/docs" kind="prominent">Introduce부터 읽기</ActionLink>
+            <ActionLink to="/docs" kind="prominent">Introduction부터 읽기</ActionLink>
             <ActionLink to="/applications">Applications 보기</ActionLink>
           </div>
           <a className={homeStyles.scrollCue()} href="#foundation-title">이야기를 따라 내려가기</a>
@@ -72,11 +72,11 @@ export function HomeRoute() {
         <p className={homeStyles.eyebrow()}>Hands &amp; Artifact</p>
         <h2 id="hands-artifact-title" className={homeStyles.sceneTitle()}>Hands가 Artifact를 만지고 편집합니다.</h2>
         <p className={homeStyles.sceneDescription()}>
-          Hands는 사람과 agent의 편집 도구입니다. Artifact는 내비게이션 없는 앱의 콘텐츠이며, 문서·프레젠테이션·스프레드시트로 이어집니다.
+          Hands는 편집 책임을 조합하고 Artifact는 Application 안의 콘텐츠가 됩니다. Official Hands Profile과 Artifact의 실제 계약 연결은 아직 TBD입니다.
         </p>
         <div className={homeStyles.actions()}>
           <ActionLink to="/editors" kind="prominent">Hands 보기</ActionLink>
-          <ActionLink to="/viewer">Artifact 보기</ActionLink>
+          <ActionLink to="/viewer">Artifact · TBD</ActionLink>
         </div>
       </HomeScene>
 
diff --git a/site/tests/browser/artifact-viewer.spec.ts b/site/tests/browser/artifact-viewer.spec.ts
index 17098037..487bd2c1 100644
--- a/site/tests/browser/artifact-viewer.spec.ts
+++ b/site/tests/browser/artifact-viewer.spec.ts
@@ -3,7 +3,7 @@ import { expect, test } from "@playwright/test";
 test("Artifact prototype switches between MD, PPT, and Sheet concepts", async ({ page }) => {
   await page.goto("/viewer");
 
-  await expect(page.getByRole("heading", { level: 1, name: "Application이 다루는 콘텐츠 계약을 검증합니다." })).toBeVisible();
+  await expect(page.getByRole("heading", { level: 1, name: "Artifact · TBD" })).toBeVisible();
   await expect(page.getByLabel("Markdown artifact mock")).toBeVisible();
   await expect(page.getByText(/launch-brief\.md · mock artifact/)).toBeVisible();
 
diff --git a/site/tests/browser/documentation-links.spec.ts b/site/tests/browser/documentation-links.spec.ts
new file mode 100644
index 00000000..9be50e55
--- /dev/null
+++ b/site/tests/browser/documentation-links.spec.ts
@@ -0,0 +1,39 @@
+import { expect, test } from "@playwright/test";
+
+test("Concept Map reaches target boundaries and the remaining TBD through real body links", async ({ page }) => {
+  await page.goto("/docs/concepts");
+  await page.locator("[data-doc-content] article").getByRole("link", { name: "Document Types", exact: true }).click();
+  await expect(page).toHaveURL(/\/docs\/document-types$/);
+  await page.getByRole("navigation", { name: "On this page" }).getByRole("link", { name: "후보 · TBD", exact: true }).click();
+  await expect(page.getByRole("heading", { name: "후보 · TBD", level: 2 })).toBeInViewport();
+  await page.locator("[data-doc-content] article").getByRole("link", { name: "Calendar · TBD", exact: true }).click();
+  await expect(page.getByRole("heading", { level: 1, name: "Calendar Document Type · TBD" })).toBeVisible();
+  await expect(page.getByRole("heading", { level: 2, name: "목표 경계 · TBD" })).toBeVisible();
+});
+
+test("protocol and building-block landings preserve the owner hierarchy", async ({ page }) => {
+  for (const path of ["/docs/foundation", "/docs/building-blocks", "/docs/editing"]) {
+    await page.goto(path);
+    const toc = page.getByRole("navigation", { name: "On this page" });
+    await expect(toc).toBeVisible();
+    expect(await toc.getByRole("link").evaluateAll((links) => links.every((link) =>
+      document.getElementById(decodeURIComponent((link as HTMLAnchorElement).hash.slice(1))) !== null,
+    ))).toBe(true);
+    expect(await page.evaluate(() => document.documentElement.scrollWidth <= document.documentElement.clientWidth)).toBe(true);
+  }
+  await expect(page.getByRole("heading", { level: 1, name: "Editing Protocol" })).toBeVisible();
+  await expect(page.getByRole("heading", { level: 2, name: "Hands Profile · TBD" })).toBeVisible();
+});
+
+test("API TOC uses the renderer's underscores and exposes the collaboration text subpath", async ({ page }) => {
+  await page.goto("/docs/api/rich-text");
+  const link = page.getByRole("navigation", { name: "On this page" }).getByRole("link", { name: "RICH_TEXT_PROFILE_V1", exact: true });
+  await expect(link).toHaveAttribute("href", "#rich_text_profile_v1");
+  await link.click();
+  await expect(page.getByRole("heading", { level: 2, name: "RICH_TEXT_PROFILE_V1", exact: true })).toBeInViewport();
+
+  await page.goto("/docs/api/collaboration");
+  await page.getByRole("navigation", { name: "On this page" })
+    .getByRole("link", { name: "@interactive-os/json-document-collaboration/text", exact: true }).click();
+  await expect(page.getByRole("heading", { level: 3, name: "createTextRuntime", exact: true })).toBeVisible();
+});
diff --git a/site/tests/browser/site-shell.spec.ts b/site/tests/browser/site-shell.spec.ts
index 4589ea09..27f35bf4 100644
--- a/site/tests/browser/site-shell.spec.ts
+++ b/site/tests/browser/site-shell.spec.ts
@@ -30,15 +30,15 @@ test("official overview exposes the product hierarchy", async ({ page }) => {
   expect(await page.getByRole("main").evaluate((element) => getComputedStyle(element).scrollSnapType)).toBe("y mandatory");
   await expect(navigation.getByRole("link", { name: "Why" })).toHaveCount(0);
   await expect(navigation.getByRole("link", { name: "Replica" })).toHaveCount(0);
-  await navigation.getByRole("button", { name: "Introduce" }).click();
-  await expect(navigation.getByRole("group", { name: "Introduce" }).getByRole("link")).toHaveText([
+  await navigation.getByRole("button", { name: "Introduction" }).click();
+  await expect(navigation.getByRole("group", { name: "Introduction" }).getByRole("link")).toHaveText([
     "Why",
     "Concept Map",
     "How We Build",
   ]);
   await navigation.getByRole("button", { name: "Foundation" }).click();
   await expect(navigation.getByRole("group", { name: "Foundation" }).getByRole("link", { name: /^API ·/ })).toHaveCount(0);
-  await expect(navigation.getByRole("group", { name: "Foundation" }).getByRole("link", { name: "Overview", exact: true })).toBeVisible();
+  await expect(navigation.getByRole("group", { name: "Foundation" }).getByRole("link", { name: "Overview", exact: true }).first()).toBeVisible();
   await navigation.getByRole("button", { name: "Building Blocks" }).click();
   await expect(navigation.getByRole("group", { name: "Building Blocks" }).getByRole("link", { name: /^API ·/ })).toHaveCount(0);
   await navigation.getByRole("button", { name: "Hands" }).click();
@@ -54,7 +54,7 @@ test("official overview exposes the product hierarchy", async ({ page }) => {
   ]);
   await navigation.getByRole("button", { name: "Artifact" }).click();
   await expect(navigation.getByRole("group", { name: "Artifact" }).getByRole("link")).toHaveText([
-    "Document · Presentation · Spreadsheet",
+    "Content Prototype · TBD",
   ]);
   await navigation.getByRole("button", { name: "Applications" }).click();
   await expect(navigation.getByRole("group", { name: "Applications" }).getByRole("link")).toHaveText([
@@ -62,9 +62,9 @@ test("official overview exposes the product hierarchy", async ({ page }) => {
     "Calendar",
     "AI Agent",
   ]);
-  await expect(navigation.getByRole("link", { name: "Reference", exact: true })).toHaveAttribute("href", "/docs/api");
+  await expect(navigation.getByRole("link", { name: "JSON Document Protocol", exact: true })).toHaveAttribute("href", "/docs/api");
   expect(await navigation.getByRole("group").evaluateAll((nodes) => nodes.map((node) => node.getAttribute("aria-label")))).toEqual([
-    "Introduce",
+    "Introduction",
     "Foundation",
     "Building Blocks",
     "Hands",
@@ -83,7 +83,7 @@ test("mobile navigation preserves the product groups without duplicating documen
   await expect(page.locator("[data-home-scene]")).toHaveCount(5);
 
   const siteNavigation = page.getByRole("navigation", { name: "Site navigation" });
-  await expect(siteNavigation.getByRole("group", { name: "Introduce" })).toBeVisible();
+  await expect(siteNavigation.getByRole("group", { name: "Introduction" })).toBeVisible();
   await expect(siteNavigation.getByRole("group", { name: "Foundation" })).toBeVisible();
   await expect(siteNavigation.getByRole("group", { name: "Core" })).toHaveCount(0);
   await expect(siteNavigation.getByRole("group", { name: "Hands" })).toBeVisible();
@@ -162,16 +162,17 @@ test("official docs routes render with route metadata in a real browser", async
   await expect(page.getByRole("heading", { level: 3, name: "값을 다루는 하나의 계약" })).toHaveCount(0);
   await expect(page.getByRole("navigation", { name: "Documentation pages" })).toHaveCount(0);
   await expect(page.getByRole("navigation", { name: "On this page" })).toBeVisible();
-  await expect(siteNavigation.getByRole("group", { name: "Introduce" }).getByRole("link", { name: "Why" })).toHaveAttribute("aria-current", "page");
+  await expect(siteNavigation.getByRole("group", { name: "Introduction" }).getByRole("link", { name: "Why" })).toHaveAttribute("aria-current", "page");
   await siteNavigation.getByRole("button", { name: "Building Blocks" }).click();
-  await siteNavigation.getByRole("group", { name: "Building Blocks" }).getByRole("link", { name: "Overview", exact: true }).nth(1).click();
+  await siteNavigation.getByRole("group", { name: "Building Blocks" }).getByRole("link", { name: "Overview", exact: true }).nth(2).click();
   await expect(page).toHaveTitle("Connector Docs - json-document");
   await expect(page.getByRole("heading", { level: 1, name: "json-document Connectors" })).toBeVisible();
   await expect(page.locator("[data-live-demo]")).toHaveCount(0);
 
-  await siteNavigation.getByRole("link", { name: "Reference", exact: true }).click();
-  await expect(page).toHaveTitle("json-document API - json-document");
-  await expect(page.getByRole("heading", { level: 1, name: "json-document API" })).toBeVisible();
+  await siteNavigation.getByRole("button", { name: "Foundation" }).click();
+  await siteNavigation.getByRole("link", { name: "JSON Document Protocol", exact: true }).click();
+  await expect(page).toHaveTitle("JSON Document Protocol - json-document");
+  await expect(page.getByRole("heading", { level: 1, name: "JSON Document Protocol" })).toBeVisible();
 });
 
 test("Editing docs and API demos keep one Korean reading flow", async ({ page }) => {
@@ -559,7 +560,7 @@ test("cat palette gives impact to interaction states and keeps code ink-led", as
 test("official site uses window scroll with sticky desktop navigation", async ({ page }) => {
   await page.setViewportSize({ width: 1366, height: 768 });
   await page.goto("/docs/api");
-  await expect(page.getByRole("heading", { level: 1, name: "json-document API" })).toBeVisible();
+  await expect(page.getByRole("heading", { level: 1, name: "JSON Document Protocol" })).toBeVisible();
 
   await page.evaluate(() => window.scrollTo(0, 1200));
 
diff --git a/site/tests/unit/api-routes.test.tsx b/site/tests/unit/api-routes.test.tsx
new file mode 100644
index 00000000..e989f591
--- /dev/null
+++ b/site/tests/unit/api-routes.test.tsx
@@ -0,0 +1,27 @@
+import { cleanup, render, screen, waitFor } from "@testing-library/react";
+import { afterEach, beforeEach, expect, test, vi } from "vitest";
+import { App } from "../../src/app/App";
+import { docPages } from "../../src/routes/docs/doc-pages";
+
+vi.mock("../../src/shared/demo-workbench/ShikiSourceCodeBlock", () => ({
+  ShikiSourceCodeBlock: ({ source }: { source: string }) => <pre><code>{source}</code></pre>,
+}));
+
+beforeEach(() => {
+  Object.defineProperty(window, "scrollTo", { configurable: true, value: vi.fn() });
+});
+afterEach(cleanup);
+
+test.each(Object.values(docPages).filter((page) => page.path.startsWith("/docs/api/")))(
+  "$path renders its own package reference rather than the parent Core guide",
+  async (page) => {
+    window.history.pushState(null, "", page.path);
+    render(<App />);
+    await waitFor(() => expect(document.title).toBe(page.title));
+    expect(await screen.findByRole("heading", { level: 1, name: page.title.replace(/ - json-document$/, "") })).toBeTruthy();
+    const firstSymbol = /^## `([^`]+)`/m.exec(page.source)?.[1];
+    expect(firstSymbol).toBeTruthy();
+    expect(screen.getByRole("heading", { level: 2, name: firstSymbol!, exact: true })).toBeTruthy();
+    expect(screen.queryByRole("heading", { level: 1, name: "JSON Document Protocol" })).toBeNull();
+  },
+);
diff --git a/site/tests/unit/app-shell.test.tsx b/site/tests/unit/app-shell.test.tsx
index 3e3debf7..dbd7e561 100644
--- a/site/tests/unit/app-shell.test.tsx
+++ b/site/tests/unit/app-shell.test.tsx
@@ -48,8 +48,8 @@ describe("official site shell", () => {
     expect(nav.queryByRole("link", { name: "Why" })).toBeNull();
     expect(nav.queryByRole("link", { name: "Replica" })).toBeNull();
     expect(screen.queryByRole("navigation", { name: "Dependency map" })).toBeNull();
-    await user.click(nav.getByRole("button", { name: "Introduce" }));
-    expect(groupLinks(nav, "Introduce")).toEqual([
+    await user.click(nav.getByRole("button", { name: "Introduction" }));
+    expect(groupLinks(nav, "Introduction")).toEqual([
       "Why",
       "Concept Map",
       "How We Build",
@@ -71,12 +71,12 @@ describe("official site shell", () => {
       "Mention",
     ]));
     await user.click(nav.getByRole("button", { name: "Artifact" }));
-    expect(groupLinks(nav, "Artifact")).toEqual(["Document · Presentation · Spreadsheet"]);
+    expect(groupLinks(nav, "Artifact")).toEqual(["Content Prototype · TBD"]);
     await user.click(nav.getByRole("button", { name: "Applications" }));
     expect(groupLinks(nav, "Applications")).toEqual(["Overview", "Calendar", "AI Agent"]);
-    expect(nav.getByRole("link", { name: "Reference" }).getAttribute("href")).toBe("/docs/api");
+    expect(nav.getByRole("link", { name: "JSON Document Protocol" }).getAttribute("href")).toBe("/docs/api");
     expect(nav.getAllByRole("group").map((group) => group.getAttribute("aria-label"))).toEqual([
-      "Introduce",
+      "Introduction",
       "Foundation",
       "Building Blocks",
       "Hands",
@@ -107,7 +107,7 @@ describe("official site shell", () => {
     expect(databaseCrumb.getByRole("link", { name: "Hands" }).getAttribute("href")).toBe("/editors");
     expect(databaseCrumb.getByText("Database")).toBeTruthy();
 
-    await user.click(within(nav.getByRole("group", { name: "Building Blocks" })).getAllByRole("link", { name: "Overview", exact: true })[1]!);
+    await user.click(within(nav.getByRole("group", { name: "Building Blocks" })).getAllByRole("link", { name: "Overview", exact: true })[2]!);
     expect(await screen.findByRole(
       "heading",
       { level: 1, name: "json-document Connectors" },
@@ -134,8 +134,8 @@ describe("official site shell", () => {
     const brand = screen.getByRole("link", { name: "json-document" });
     const siteNav = screen.getByRole("navigation", { name: "Site navigation" });
 
-    await user.click(nav.getByRole("button", { name: "Introduce" }));
-    await user.click(within(nav.getByRole("group", { name: "Introduce" })).getByRole("link", { name: "Why" }));
+    await user.click(nav.getByRole("button", { name: "Introduction" }));
+    await user.click(within(nav.getByRole("group", { name: "Introduction" })).getByRole("link", { name: "Why" }));
     await waitFor(() => expect(document.documentElement.lang).toBe("ko"));
     const frame = await waitFor(() => {
       const node = document.querySelector("[data-page-frame]");
@@ -143,9 +143,10 @@ describe("official site shell", () => {
       return node;
     });
 
-    await user.click(nav.getByRole("link", { name: "Reference" }));
+    await user.click(nav.getByRole("button", { name: "Foundation" }));
+    await user.click(nav.getByRole("link", { name: "JSON Document Protocol" }));
     const crumb = within(await screen.findByRole("navigation", { name: "Breadcrumb" }));
-    await waitFor(() => expect(crumb.getByText("Reference")).toBeTruthy());
+    await waitFor(() => expect(crumb.getByText("JSON Document Protocol")).toBeTruthy());
     expect(screen.getByRole("link", { name: "json-document" })).toBe(brand);
     expect(screen.getByRole("navigation", { name: "Site navigation" })).toBe(siteNav);
     expect(document.querySelector("[data-page-frame]")).toBe(frame);
diff --git a/site/tests/unit/breadcrumb.test.ts b/site/tests/unit/breadcrumb.test.ts
index bcfadcfb..ddfa3fdf 100644
--- a/site/tests/unit/breadcrumb.test.ts
+++ b/site/tests/unit/breadcrumb.test.ts
@@ -13,17 +13,17 @@ function trail(path: string) {
 
 describe("breadcrumbTrail", () => {
   test("places owner groups below the new IA sections", () => {
-    expect(trail("/docs")).toEqual(["Overview:/", "Introduce:/docs"]);
-    expect(trail("/docs/concepts")).toEqual(["Overview:/", "Introduce:/docs", "Concept Map:/docs/concepts"]);
+    expect(trail("/docs")).toEqual(["Overview:/", "Introduction:/docs"]);
+    expect(trail("/docs/concepts")).toEqual(["Overview:/", "Introduction:/docs", "Concept Map:/docs/concepts"]);
     expect(trail("/docs/foundation")).toEqual(["Overview:/", "Foundation:/docs/foundation"]);
     expect(trail("/docs/collaboration/replica")).toEqual([
       "Overview:/", "Foundation:/docs/foundation", "Collaboration:/docs/collaboration", "Replica:/docs/collaboration/replica",
     ]);
     expect(trail("/docs/selection")).toEqual([
-      "Overview:/", "Foundation:/docs/foundation", "Editing:/docs/intent-guide", "Selection:/docs/selection",
+      "Overview:/", "Foundation:/docs/foundation", "Editing:/docs/editing", "Selection:/docs/selection",
     ]);
     expect(trail("/docs/connector-zod-validate")).toEqual([
-      "Overview:/", "Building Blocks:/docs/adapters", "Ecosystem Connectors:/docs/connectors",
+      "Overview:/", "Building Blocks:/docs/building-blocks", "Connector:/docs/connectors",
       "Zod:/docs/connector-zod", "Validate:/docs/connector-zod-validate",
     ]);
     expect(trail("/docs/order")).toEqual(["Overview:/", "Hands:/editors", "Order:/docs/order"]);
diff --git a/site/tests/unit/docs-route.test.tsx b/site/tests/unit/docs-route.test.tsx
index c4868ead..c6a26790 100644
--- a/site/tests/unit/docs-route.test.tsx
+++ b/site/tests/unit/docs-route.test.tsx
@@ -25,21 +25,21 @@ describe("documentation routes", () => {
     const user = userEvent.setup();
     const nav = within(await screen.findByRole("navigation", { name: "Site navigation" }));
 
-    await user.click(nav.getByRole("button", { name: "Introduce" }));
-    await user.click(within(nav.getByRole("group", { name: "Introduce" })).getByRole("link", { name: "Why" }));
+    await user.click(nav.getByRole("button", { name: "Introduction" }));
+    await user.click(within(nav.getByRole("group", { name: "Introduction" })).getByRole("link", { name: "Why" }));
     await waitFor(() => expect(document.title).toBe("json-document Docs - json-document"));
     expect(document.head.querySelector('link[rel="canonical"]')?.getAttribute("href")).toBe("https://developer-1px.github.io/json-document/docs");
     expect(await screen.findByRole("heading", { level: 1 }, { timeout: 10000 })).toBeTruthy();
-    expect(within(nav.getByRole("group", { name: "Introduce" })).getByRole("link", { name: "Why" }).getAttribute("aria-current")).toBe("page");
+    expect(within(nav.getByRole("group", { name: "Introduction" })).getByRole("link", { name: "Why" }).getAttribute("aria-current")).toBe("page");
 
-    await user.click(within(nav.getByRole("group", { name: "Introduce" })).getByRole("link", { name: "Concept Map" }));
+    await user.click(within(nav.getByRole("group", { name: "Introduction" })).getByRole("link", { name: "Concept Map" }));
     await waitFor(() => expect(document.title).toBe("Concept Map - json-document"));
     expect(await screen.findByRole("heading", { level: 1, name: "Concept Map" }, { timeout: 10000 })).toBeTruthy();
 
     expect(screen.queryByRole("navigation", { name: "Documentation pages" })).toBeNull();
 
     await user.click(nav.getByRole("button", { name: "Building Blocks" }));
-    await user.click(within(nav.getByRole("group", { name: "Building Blocks" })).getAllByRole("link", { name: "Overview", exact: true })[1]!);
+    await user.click(within(nav.getByRole("group", { name: "Building Blocks" })).getAllByRole("link", { name: "Overview", exact: true })[2]!);
     await waitFor(() => expect(document.title).toBe("Connector Docs - json-document"), { timeout: 10000 });
     expect(await screen.findByRole("heading", { level: 1, name: "json-document Connectors" }, { timeout: 10000 })).toBeTruthy();
 
@@ -53,12 +53,12 @@ describe("documentation routes", () => {
     await waitFor(() => expect(document.title).toBe("Topology - json-document"));
     expect(await screen.findByRole("heading", { level: 1, name: "Topology" }, { timeout: 10000 })).toBeTruthy();
 
-    await user.click(nav.getByRole("link", { name: "Reference" }));
-    await waitFor(() => expect(document.title).toBe("json-document API - json-document"));
-    expect(document.head.querySelector('meta[name="description"]')?.getAttribute("content")).toBe("여섯 가지 JSON Document 진입점과 JSON Patch, Pointer, JSONPath 공개 API를 정리합니다.");
-    expect(await screen.findByRole("heading", { level: 1, name: "json-document API" }, { timeout: 10000 })).toBeTruthy();
-    expect(within(nav.getByRole("group", { name: "Introduce" })).getByRole("link", { name: "Why" }).getAttribute("aria-current")).toBeNull();
-    expect(nav.getByRole("link", { name: "Reference" }).getAttribute("aria-current")).toBe("page");
+    await user.click(nav.getByRole("link", { name: "JSON Document Protocol" }));
+    await waitFor(() => expect(document.title).toBe("JSON Document Protocol - json-document"));
+    expect(document.head.querySelector('meta[name="description"]')?.getAttribute("content")).toBe("로컬·협업 구현이 공유하는 여섯 member의 JSONDocument 계약과 JSON 표준 연산 API를 설명합니다.");
+    expect(await screen.findByRole("heading", { level: 1, name: "JSON Document Protocol" }, { timeout: 10000 })).toBeTruthy();
+    expect(within(nav.getByRole("group", { name: "Introduction" })).getByRole("link", { name: "Why" }).getAttribute("aria-current")).toBeNull();
+    expect(nav.getByRole("link", { name: "JSON Document Protocol" }).getAttribute("aria-current")).toBe("page");
     const mobileSections = within(screen.getByRole("navigation", { name: "Documentation sections" }));
     expect(mobileSections.getByRole("link", { name: "작업별 진입점" }).getAttribute("href")).toBe("#작업별-진입점");
   });
@@ -70,7 +70,7 @@ describe("documentation routes", () => {
 
     await waitFor(() => expect(document.title).toBe("json-document Docs - json-document"));
     expect(await screen.findByRole("heading", { level: 1 }, { timeout: 10000 })).toBeTruthy();
-    expect(within(nav.getByRole("group", { name: "Introduce" })).getByRole("link", { name: "Why" }).getAttribute("aria-current")).toBe("page");
+    expect(within(nav.getByRole("group", { name: "Introduction" })).getByRole("link", { name: "Why" }).getAttribute("aria-current")).toBe("page");
 
     window.history.pushState(null, "", "/docs/topology/");
     window.dispatchEvent(new Event("popstate"));
@@ -80,9 +80,9 @@ describe("documentation routes", () => {
 
     window.history.pushState(null, "", "/docs/api/");
     window.dispatchEvent(new Event("popstate"));
-    await waitFor(() => expect(document.title).toBe("json-document API - json-document"));
-    expect(await screen.findByRole("heading", { level: 1, name: "json-document API" })).toBeTruthy();
-    expect(nav.getByRole("link", { name: "Reference" }).getAttribute("aria-current")).toBe("page");
+    await waitFor(() => expect(document.title).toBe("JSON Document Protocol - json-document"));
+    expect(await screen.findByRole("heading", { level: 1, name: "JSON Document Protocol" })).toBeTruthy();
+    expect(nav.getByRole("link", { name: "JSON Document Protocol" }).getAttribute("aria-current")).toBe("page");
   });
 
   test("exposes the Interaction Handles ecosystem document", async () => {
diff --git a/site/tests/unit/documentation-page.test.tsx b/site/tests/unit/documentation-page.test.tsx
new file mode 100644
index 00000000..cb1cf781
--- /dev/null
+++ b/site/tests/unit/documentation-page.test.tsx
@@ -0,0 +1,84 @@
+import { cleanup, render, screen, within } from "@testing-library/react";
+import { afterEach, describe, expect, test, vi } from "vitest";
+import { DocumentationPage } from "../../src/routes/docs/DocumentationPage";
+import { DocumentTypeCandidateRoute, type DocumentTypeCandidate } from "../../src/routes/docs/DocumentTypeCandidateRoute";
+import { docPages } from "../../src/routes/docs/doc-pages";
+import { rewriteMarkdownHref } from "../../src/routes/docs/MarkdownViewer";
+import { pageDescriptors } from "../../src/app/page-descriptors";
+import documentTypeAudits from "../../../audits/document-types.json";
+
+// Keep real Markdown rendering; embedded products and highlighting do not own document headings.
+vi.mock("../../src/app/live-demo-registry", () => ({
+  LiveDemo: () => <section><h2 id="embedded-demo-heading">Embedded demo</h2></section>,
+}));
+vi.mock("../../src/shared/demo-workbench/ShikiSourceCodeBlock", () => ({
+  ShikiSourceCodeBlock: ({ source }: { source: string }) => <pre><code>{source}</code></pre>,
+}));
+
+afterEach(cleanup);
+
+describe("canonical documentation projection", () => {
+  test.each(Object.values(docPages))("$path: TOC targets and body links use the rendered document and route registry", (page) => {
+    const { container } = render(
+      <DocumentationPage title={page.title} source={page.source} sourcePath={page.documentSource} illustration="braces" />,
+    );
+    const headings = [...container.querySelectorAll("h2[data-doc-heading]")];
+    expect(new Set(headings.map((heading) => heading.id)).size).toBe(headings.length);
+    for (const name of ["Documentation sections", "On this page"]) {
+      const links = within(screen.getByRole("navigation", { name })).queryAllByRole("link");
+      expect(links.map((link) => decodeURIComponent(link.getAttribute("href") ?? "")))
+        .toEqual(headings.map((heading) => `#${heading.id}`));
+      expect(links.map((link) => link.textContent)).toEqual(headings.map((heading) => heading.textContent));
+    }
+    for (const link of container.querySelectorAll("article a[href]")) {
+      const href = link.getAttribute("href")!;
+      expect(href).not.toMatch(/^(?!https?:).*\.md(?:[?#]|$)/);
+      if (href.startsWith("/") && !href.startsWith("//")) {
+        const path = new URL(href, "https://documentation.invalid").pathname;
+        expect(pageDescriptors.some((route) => route.path === path), href).toBe(true);
+      }
+    }
+  });
+
+  test("uses renderer IDs for underscores, punctuation, duplicate headings and inline Markdown, but not code fences", () => {
+    const source = [
+      "# Page", "", "## `A_B`", "", "## 후보 · TBD", "", "## **Same**", "", "## Same",
+      "", "```md", "## Not a heading", "```",
+    ].join("\n");
+    const { rerender } = render(<DocumentationPage title="Page" source={source} illustration="braces" />);
+    const toc = () => within(screen.getByRole("navigation", { name: "On this page" }));
+    expect(toc().getAllByRole("link").map((link) => decodeURIComponent(link.getAttribute("href")!)))
+      .toEqual(["#a_b", "#후보--tbd", "#same", "#same-1"]);
+    rerender(<DocumentationPage title="Next" source="## Next" illustration="braces" />);
+    expect(toc().getAllByRole("link").map((link) => link.getAttribute("href"))).toEqual(["#next"]);
+  });
+
+  test.each([
+    ["docs/public/concepts.md", "how-we-build.md", "/docs/how-we-build"],
+    ["docs/public/concepts.md", "document-types.md#후보--tbd", "/docs/document-types#후보--tbd"],
+    ["docs/public/adapters.md", "adapter-virtual-selection.md", "/docs/adapter-virtual-selection"],
+    ["docs/public/ui-primitives.md", "animation.md", "/docs/animation"],
+    ["docs/public/connectors.md", "connector-a2ui.md", "/docs/connector-a2ui"],
+    ["docs/public/hands.md", "official-hands.md", "/docs/official-hands"],
+    ["docs/public/connector-a2ui.md", "../api-reference/a2ui.md", "/docs/api/a2ui"],
+    ["docs/api-reference/editing.md", "../public/editing.md?mode=read#입력에서-관찰까지", "/docs/editing?mode=read#입력에서-관찰까지"],
+    ["docs/public/connector-a2ui.md", "../../packages/json-document-a2ui/README.md", "https://github.com/developer-1px/json-document/blob/main/packages/json-document-a2ui/README.md"],
+    ["docs/public/api.md", "#commit", "#commit"],
+    ["docs/public/api.md", "https://example.com/api.md", "https://example.com/api.md"],
+  ])("resolves %s → %s without a second filename catalog", (source, href, expected) => {
+    expect(decodeURIComponent(rewriteMarkdownHref(href, source)!)).toBe(expected);
+  });
+
+  test("registers every document page once, including Concept Map", () => {
+    const registered = pageDescriptors.filter((route) => route.documentSource !== undefined);
+    expect(Object.values(docPages).map((page) => page.path).sort()).toEqual(registered.map((page) => page.path).sort());
+  });
+
+  test.each(documentTypeAudits.candidates as DocumentTypeCandidate[])("%s exposes the target boundary without declaring the candidate complete", (candidate) => {
+    render(<DocumentTypeCandidateRoute candidate={candidate} />);
+    expect(screen.getByRole("heading", { level: 1 }).textContent).toContain("Document Type · TBD");
+    expect(screen.getByRole("heading", { level: 2, name: "목표 경계 · TBD" })).toBeTruthy();
+    expect(screen.getByRole("heading", { level: 2, name: "현재 관찰된 schema · TBD" })).toBeTruthy();
+    expect(screen.getByRole("heading", { level: 2, name: "확정에 필요한 증거" })).toBeTruthy();
+  });
+});
diff --git a/standards/json-document-v3/profile.md b/standards/json-document-v3/profile.md
index 2f2ff894..b6718ef2 100644
--- a/standards/json-document-v3/profile.md
+++ b/standards/json-document-v3/profile.md
@@ -7,7 +7,7 @@ source release는 `3.0.0`이며 npm publication 전까지 release-prepared 상
 이 profile은 JSON Document, stateless JSON Patch, validation과 change
 notification이라는 canonical vocabulary만 사용한다. Repository 전체의 concept와
 naming grammar는
-[Concept and Naming Standard](concept-and-naming-standard.md)가 정의한다.
+[Concept and Naming Standard](../repository-naming.md)가 정의한다.
 
 이 profile은 문서, 표, 슬라이드, 캔버스, 노트 편집기가 공통으로 의존할
 수 있는 최소 JSON 편집 계약을 정의한다. 구현체는 더 많은 기능을 제공할 수
@@ -167,7 +167,7 @@ conformance corpus의 public-root binding을 서로 분리한다.
 | `packages/json-document/tests/conformance/rfc6902.test.ts` | public root `applyPatch`의 전체 RFC 6902 corpus binding |
 | `standards/json-document-v3/conformance/suites/jsonpath.ts` | vendored RFC 9535 CTS를 `query`와 `at`으로 검증하는 runner |
 | `packages/json-document/tests/conformance/jsonpath.test.ts` | public root JSON Document의 전체 RFC 9535 CTS binding |
-| `standards/json-document-v3/conformance/vectors/foundation.json` | Core와 collaboration package-local primitive의 array index·equality parity 및 JSON boundary fixture |
+| `standards/json-document-v3/conformance/vectors/foundation.json` | Core public primitive의 array index·equality 및 JSON boundary fixture |
 | `standards/json-document-v3/conformance/vectors/pressure.json` | form, table/data-grid, outliner/tree, rich text, storage/collaboration 시나리오 |
 | `standards/json-document-v3/conformance/suites/pressure.ts` | 여섯 member만으로 다섯 vertical을 실행하는 injected runner |
 | `standards/json-document-v3/implementations/independent/json-document.ts` | reference runtime을 import하지 않는 독립 6-member test implementation |
@@ -199,9 +199,9 @@ reference와 독립 구현을 모두 통과하며, collaboration public binding
 Core의 JSON equality는 하나의 equality leaf가 소유한다. canonical array index
 `[0]|[1-9][0-9]*`와 JavaScript safe-integer 경계도 하나의 Pointer leaf가
 소유하며, RFC 6902 append marker `-`는 write 문맥에서만 별도로 처리한다.
-collaboration package는 Core private path를 deep import하지 않고 package-local
-두 primitive를 유지하며 `foundation-vectors.json`을 함께 실행해 의미 차이를
-드러낸다.
+collaboration package는 Core private path를 deep import하거나 같은 primitive를
+별도로 구현하지 않는다. Core public API의 `jsonEqual`과 `parseArrayIndex`를
+소비하며 foundation conformance vector로 그 경계 의미를 검증한다.
 
 JSON validation, owning clone, trusted clone은 하나의 traversal abstraction으로
 합치지 않는다. validation은 오류 위치를 설명하고, owning clone은 검증과
diff --git a/standards/repository-implementation-shape.md b/standards/repository-implementation-shape.md
index 56f51df7..6c02333f 100644
--- a/standards/repository-implementation-shape.md
+++ b/standards/repository-implementation-shape.md
@@ -72,6 +72,12 @@ Package는 같은 도구를 쓴다는 이유가 아니라 독립 배포, 외부
 | Validation | State를 바꾸지 않는 입력·candidate 검사 | Transformation과 normalization |
 | Test support | Production-shaped fixture와 test host | 배포 public API |
 
+이 표는 package 내부의 역할 분류이며 사이트의 읽기 레이어와 다르다.
+Document Type은 문서 고유의 Domain model·Domain operation·Projection을 소유하는
+생태계 위치다. 후보별 package 재배치는 아직 TBD이며 아래 현재 package 모형을
+이름만으로 이동시키지 않는다. Hands 내비게이션에서 읽는 React integration도
+실제 주책임이 framework lifecycle이면 Connector다.
+
 한 module에 여러 역할이 보이더라도 같은 이유로 항상 함께 바뀌고 독립 경계를
 만들 수 없다면 하나의 책임으로 유지한다. 표의 행마다 파일을 하나씩 만들지
 않는다.
diff --git a/standards/repository-naming.md b/standards/repository-naming.md
index e3c500ce..2a55c7d4 100644
--- a/standards/repository-naming.md
+++ b/standards/repository-naming.md
@@ -72,9 +72,39 @@ publication
   -> change notification
 ```
 
-`Projection`, capability probe, acceptance callback 같은 이전 synonym은 public
-identifier로 남기지 않는다. Canonical code는 `JSONDocument`, `validatePatch`,
-`JSONPatchValidationResult`, `validate`만 사용한다.
+JSON Document를 뜻하던 `Document Projection`·`Projection snapshot`,
+capability probe, acceptance callback 같은 이전 synonym은 남기지 않는다.
+이 책임의 canonical code는 `JSONDocument`, `validatePatch`,
+`JSONPatchValidationResult`, `validate`를 사용한다. 문서에서 파생 조회를 만드는
+Projection은 아래 Document Type의 별도 의미이며 이 퇴역 규칙에 포함하지 않는다.
+
+### Document Type
+
+| Canonical term | 정의 | 포함하지 않는 것 |
+| --- | --- | --- |
+| Document Type | 특정 JSON Document의 의미·유효 상태·변경을 정의하는 생태계 위치 | 편집 lifecycle, 플랫폼 입력, 제품 화면 |
+| Document Model | 값·entity·관계의 구조 | 일시적 selection, DOM state |
+| Schema / invariant | 구조적·의미적 유효 조건 | 제품의 화면 배치 |
+| Document Operation | 문서 의미를 보존하는 변경 | raw event 해석, 제품 workflow |
+| Projection | 문서를 조회·표현에 필요한 파생 형태로 읽는 계약 | stateful JSON Document의 다른 이름 |
+| Document Type Profile | 문서 인스턴스가 따르는 의미 계약의 식별과 지원 범위 | 모든 Hands의 입력·History 정책 |
+
+이 위치를 `Domain`이나 `Genre`라는 다른 이름으로 등록하지 않는다.
+package 내부의 domain model/operation이라는 책임 분류와 기존 public identifier는
+그대로 유지한다. 책임 이름과 경계는 확정됐지만 후보별 owner 재배치와 공개 계약
+수렴은 TBD다. 현재 package/API의 존재를 그 후보의 완료로 간주하지 않는다.
+
+### 읽기 구조와 조합
+
+Foundation은 JSON Document, Document Types, Editing과 Collaboration을 읽는
+묶음이고, Building Blocks는 Adapter, Connector, Affordance와 UI Primitives를
+읽는 묶음이다. Hands는 장르별 편집 조합, Artifact는 그 조합으로 다루는 콘텐츠,
+Application은 최종 제품 composition root다.
+
+이 분류는 필수 dependency chain이 아니다. Collaboration은 같은 JSONDocument의
+대체 구현이고 Adapter와 Connector는 서로 독립적으로 선택한다. 사이트의
+탐색 분류와 package의 실제 책임 종류도 별도 축이다. API owner는 공개
+entrypoint를 소유하는 package이며, 탐색 분류를 owner 이름으로 사용하지 않는다.
 
 ### Collaboration
 
@@ -201,16 +231,23 @@ companion과 외부 peer version 범위를 기록한다.
 | 위치 | 판정 질문 |
 | --- | --- |
 | Core | UI·편집·platform 없이 JSON 값과 표준 연산만으로 성립하는가? |
+| Document Type | 특정 문서의 model·schema·invariant·의미 연산·Projection을 소유하는가? 후보별 수렴은 TBD인가? |
 | Editing | Intent, Selection, Topology, Clipboard, History처럼 편집 의미를 소유하는가? |
 | Collaboration | 여러 참여자의 causal state와 수렴을 소유하는가? |
 | Adapter | Web/DOM 같은 platform contract를 기존 public contract로 번역하는가? |
 | Connector | React, Zod, Ajv, TanStack Table처럼 이름 있는 외부 생태계의 public contract를 연결하는가? |
-| Affordance | platform input을 사람이 아는 조작 문법으로 해석하는가? |
+| Affordance | 입력 장치와 독립적인 조작 의미와 수명주기를 소유하는가? 플랫폼 사실은 Adapter에서 받는가? |
+| UI Primitives | 표준 control·focus·overlay와 재사용 UI 행동을 소유하는가? |
 | Hands | 한 artifact 장르에서 여러 capability를 조합한 최소 편집 도구인가? |
-| Host | 제품 고유 정책·메시지·UI composition·payload 의미를 결정하는가? |
+| Artifact | 사람이 보고 편집하는 콘텐츠이며 navigation·workflow를 소유하지 않는가? |
+| Application / Host | 정본 모듈 조합·실행 순서·제품 정책 값·copy·fixture·layout·구체 인스턴스 주입만 소유하는가? |
 | Page-local | 한 page의 교육·fixture·presentation 목적 때문에 함께 바뀌는가? |
 | Etc | 아직 위 위치로 설명할 수 없는가? 임시 분류이며 identifier 조각으로 쓰지 않는다. |
 
+Host는 모델·schema·Intent·command·selection·history·gesture·플랫폼 번역·직렬화·
+projection·재사용 UI의 최종 owner가 아니다. 하나의 소비자만 있어도 이 책임은
+이름 있는 canonical module로 두고 Host는 공개 API를 조합한다.
+
 위치를 결정할 때 최소한 다음 네 질문에 답한다.
 
 1. 무엇을 아는가?
@@ -447,7 +484,7 @@ Change    = 작성되거나 적용된 historical record
 | `append*` | 기존 representation에 component 하나 추가 |
 | `track*` | Change를 통과한 identity/location 추적 |
 | `materialize*` | Change history/DAG를 현재 domain value로 fold |
-| `project*` | 낮은 수준 구조에서 read representation 파생; internal 전용 |
+| `project*` | 정본 문서나 구조에서 read representation 파생; 공개 여부는 owner의 계약으로 결정 |
 | `export*` | Typed transport-neutral artifact 생성 |
 | `ingest*` | 신뢰하지 않는 외부 artifact 검증과 replica 통합 |
 | `compact*` | History를 새 recovery boundary로 fold |
@@ -850,8 +887,8 @@ Connector packages
 11. Public boolean은 `is`, `has`, `can`, `should`, `did`로 읽히게 한다.
 12. 새 public field를 불필요하게 축약하지 않는다.
 13. 같은 validation 책임에는 하나의 동사를 사용한다.
-14. Public canonical concept는 JSON Document이며 Projection은 public 또는
-    internal identifier로 사용하지 않는다.
+14. Stateful document의 canonical concept는 JSON Document다. 퇴역한 Document
+    Projection 별칭과 유효한 파생 조회 Projection을 혼동하지 않는다.
 15. 이름 변경은 runtime logic, protocol semantics 또는 wire behavior 변경을
     승인하지 않는다.
 16. Connector는 외부 생태계 integration package의 분류이며 공통 runtime

From dabbe80a39723f43a990481e58d37400c9387947 Mon Sep 17 00:00:00 2001
From: "teo.v" <66650330+developer-1px@users.noreply.github.com>
Date: Wed, 9 Sep 2026 10:28:02 +0900
Subject: [PATCH 07/20] =?UTF-8?q?ci:=20=EC=A0=84=EC=B2=B4=20=EA=B2=80?=
 =?UTF-8?q?=EC=A6=9D=EA=B3=BC=20soak=EB=A5=BC=20=EC=88=98=EB=8F=99=20?=
 =?UTF-8?q?=EC=8B=A4=ED=96=89=EC=9C=BC=EB=A1=9C=20=EC=A0=84=ED=99=98?=
 =?UTF-8?q?=ED=95=9C=EB=8B=A4=20(#742)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-authored-by: 유용태 <teo.v@navercorp.com>
---
 .github/workflows/ci.yml                 | 86 +-----------------------
 .github/workflows/collaboration-soak.yml |  2 -
 AGENTS.md                                | 16 +++++
 README.md                                | 32 +++++++++
 4 files changed, 51 insertions(+), 85 deletions(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index dc6758be..81f5676d 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -1,68 +1,14 @@
 name: CI
 
 on:
-  pull_request:
-  push:
-    branches: [main]
   workflow_dispatch:
 
 permissions:
   contents: read
 
 jobs:
-  plan:
-    name: Plan
-    runs-on: ubuntu-latest
-    outputs:
-      full: ${{ steps.plan.outputs.full }}
-      package_required: ${{ steps.plan.outputs.package_required }}
-      package_workspaces: ${{ steps.plan.outputs.package_workspaces }}
-      browser_specs: ${{ steps.plan.outputs.browser_specs }}
-      docs: ${{ steps.plan.outputs.docs }}
-      site: ${{ steps.plan.outputs.site }}
-      standards: ${{ steps.plan.outputs.standards }}
-      external_kit: ${{ steps.plan.outputs.external_kit }}
-      reason: ${{ steps.plan.outputs.reason }}
-    steps:
-      - uses: actions/checkout@v6
-        with:
-          fetch-depth: 0
-      - uses: actions/setup-node@v6
-        with:
-          node-version: "22"
-      - name: Select verification scope
-        id: plan
-        env:
-          EVENT_NAME: ${{ github.event_name }}
-          BASE_SHA: ${{ github.event.pull_request.base.sha }}
-          HEAD_SHA: ${{ github.event.pull_request.head.sha }}
-        run: |
-          if [ "$EVENT_NAME" = "pull_request" ]; then
-            node scripts/ci-plan.mjs --base "$BASE_SHA" --head "$HEAD_SHA" >> "$GITHUB_OUTPUT"
-          else
-            node scripts/ci-plan.mjs --full >> "$GITHUB_OUTPUT"
-          fi
-      - name: Summarize verification scope
-        env:
-          PLAN_REASON: ${{ steps.plan.outputs.reason }}
-          PACKAGE_WORKSPACES: ${{ steps.plan.outputs.package_workspaces }}
-          BROWSER_SPECS: ${{ steps.plan.outputs.browser_specs }}
-          EXTERNAL_KIT: ${{ steps.plan.outputs.external_kit }}
-        run: |
-          {
-            echo "## CI 검증 계획"
-            echo "- 판단: $PLAN_REASON"
-            echo "- 패키지: $PACKAGE_WORKSPACES"
-            echo "- 브라우저: $BROWSER_SPECS"
-            echo "- 외부 kit: $EXTERNAL_KIT"
-          } >> "$GITHUB_STEP_SUMMARY"
-      - name: Verify workspace contract and planner
-        run: npm run workspace:check && npm run ci:plan:test
-
   package:
     name: Package
-    needs: plan
-    if: needs.plan.outputs.package_required == 'true'
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v6
@@ -71,31 +17,15 @@ jobs:
           node-version: "22"
       - name: Install dependencies
         run: npm ci --no-audit --no-fund
+      - name: Verify planner commands
+        run: npm run ci:plan:test
       - name: Verify full release graph
-        if: needs.plan.outputs.full == 'true'
         env:
           npm_config_cache: ${{ runner.temp }}/npm-cache
         run: npm run release:check
-      - name: Verify affected libraries
-        if: needs.plan.outputs.full != 'true' && needs.plan.outputs.package_workspaces != '[]'
-        env:
-          AFFECTED_WORKSPACES: ${{ needs.plan.outputs.package_workspaces }}
-        run: >-
-          node --input-type=module --eval
-          'import { spawnSync } from "node:child_process";
-          const workspaces = JSON.parse(process.env.AFFECTED_WORKSPACES);
-          const result = spawnSync("node", ["scripts/workspace-tasks.mjs", "verify", ...workspaces], { stdio: "inherit" });
-          process.exit(result.status ?? 1);'
-      - name: Verify standards
-        if: needs.plan.outputs.full != 'true' && needs.plan.outputs.standards == 'true'
-        run: npm run standard:check
-      - name: Verify documentation
-        if: needs.plan.outputs.full != 'true' && needs.plan.outputs.docs == 'true'
-        run: npm run docs:evaluate
 
   playground-site:
     name: Site
-    needs: plan
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v6
@@ -107,22 +37,12 @@ jobs:
       - name: Install Rich Text browser engines
         run: npx playwright install --with-deps firefox webkit
       - name: Verify site
-        if: needs.plan.outputs.site == 'true'
         run: npm run typecheck -w @interactive-os/json-document-site && npm test -w @interactive-os/json-document-site && npm run site:verify:pages
       - name: Verify browser behavior
-        env:
-          BROWSER_SPECS: ${{ needs.plan.outputs.browser_specs }}
-        run: >-
-          node --input-type=module --eval
-          'import { spawnSync } from "node:child_process";
-          const specs = JSON.parse(process.env.BROWSER_SPECS);
-          const result = spawnSync("npm", ["run", "browser:test", "--", ...specs], { stdio: "inherit" });
-          process.exit(result.status ?? 1);'
+        run: npm run browser:test
 
   external-kit:
     name: External kit
-    needs: plan
-    if: needs.plan.outputs.external_kit == 'true'
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v6
diff --git a/.github/workflows/collaboration-soak.yml b/.github/workflows/collaboration-soak.yml
index dfc1f21f..9b326122 100644
--- a/.github/workflows/collaboration-soak.yml
+++ b/.github/workflows/collaboration-soak.yml
@@ -2,8 +2,6 @@ name: Collaboration Soak
 
 on:
   workflow_dispatch:
-  schedule:
-    - cron: "0 19 * * 1"
 
 permissions:
   contents: read
diff --git a/AGENTS.md b/AGENTS.md
index 92bb9365..e2b2e0da 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,5 +1,21 @@
 # Repository agent instructions
 
+## Local verification and remote workflows
+
+This is a solo-maintained project. Agents own change-scoped local verification
+before handoff: run the relevant tests, type checks, builds, and browser flows.
+Report the commands, results, and any unexecuted or failing checks separately.
+An absent remote check must not be reported as a pass.
+
+Pull requests do not automatically run full CI. Main pushes run the Pages
+build/deploy workflow; release tags retain package verification on a clean
+runner. Full CI and the extended collaboration soak are manual workflows.
+Do not wait for automatic PR checks or routinely dispatch manual CI to recreate
+the removed gate. Use remote full verification when deliberately requested.
+
+Keep product tests and verification commands available. The local workflow and
+manual commands are documented in the root README's development section.
+
 ## Canonical module principle
 
 This repository follows **the same role, the same responsibility, the same
diff --git a/README.md b/README.md
index f0a07610..a26f4a28 100644
--- a/README.md
+++ b/README.md
@@ -124,3 +124,35 @@ npm test -w @interactive-os/json-document
 npm run typecheck -w @interactive-os/json-document
 npm run build -w @interactive-os/json-document
 ```
+
+### 검증 운영
+
+1인 개발과 agent의 로컬 검증을 기본으로 합니다. 개발·PR에서는 변경 범위에 맞는
+테스트·타입·빌드·브라우저 검증을 수행하고, 실행 명령과 결과를 인계합니다.
+실행하지 못한 검사와 실패한 검사는 통과와 구분합니다. 자동 CI가 없다는 사실을
+검증 완료로 간주하지 않습니다.
+
+| 시점 | 원격 실행 |
+| --- | --- |
+| PR 생성·갱신 | 자동 전체 CI 없음 |
+| main push | Pages 빌드·배포와 live 확인 |
+| 릴리스 tag | 깨끗한 runner에서 기존 패키지 검증 후 publish |
+| 필요 시 | 전체 CI와 장시간 collaboration soak 수동 실행 |
+
+전체 검증이 필요하면 기존 명령을 사용합니다. 제품 테스트와 검사 CLI는 유지하며,
+변경 영향도 선택기 CLI는 자동 CI의 gate로 사용하지 않습니다.
+
+```sh
+npm run verify
+npm run release:check
+npm run external-kit:verify
+npm run test:collaboration:soak
+```
+
+원격의 깨끗한 환경에서 확인하려면 GitHub Actions의 해당 workflow에서
+`Run workflow`를 선택하거나 아래 명령으로 명시적으로 실행합니다.
+
+```sh
+gh workflow run ci.yml --ref main
+gh workflow run collaboration-soak.yml --ref main
+```

From 19a96084cac463cf60f79c7bf04b28ea3cf95cda Mon Sep 17 00:00:00 2001
From: "teo.v" <66650330+developer-1px@users.noreply.github.com>
Date: Wed, 9 Sep 2026 12:55:56 +0900
Subject: [PATCH 08/20] =?UTF-8?q?fix(calendar):=20=EC=A0=95=EB=B3=B8=20?=
 =?UTF-8?q?=ED=8E=B8=EC=A7=91=20=ED=94=84=EB=A1=9C=ED=86=A0=EC=BD=9C?=
 =?UTF-8?q?=EA=B3=BC=20=EC=9E=85=EB=A0=A5=20=EA=B2=BD=EB=A1=9C=EB=A5=BC=20?=
 =?UTF-8?q?=EC=9D=BC=EC=B9=98=EC=8B=9C=ED=82=A8=EB=8B=A4=20(#744)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-authored-by: 유용태 <teo.v@navercorp.com>
---
 docs/api-reference/calendar.md                |   5 +-
 docs/api-reference/editing.md                 |   4 +-
 docs/evaluate.mjs                             |   3 +-
 package-lock.json                             |   3 +
 packages/json-document-calendar/README.md     |  34 +-
 packages/json-document-calendar/package.json  |   3 +
 .../src/calendar-month-grid.tsx               |   1 +
 .../src/calendar-time-grid.tsx                |   1 +
 .../src/use-calendar-hand.ts                  |  42 +-
 .../src/use-calendar-pointer-interactions.ts  |  82 ++-
 .../tests/calendar-protocol.test.tsx          | 145 ++++++
 .../tests/use-calendar-hand.test.tsx          |   7 +-
 packages/json-document-editing/README.md      |   6 +-
 .../docs/calendar-profile.md                  | 105 ++++
 packages/json-document-editing/package.json   |   2 +-
 .../src/calendar-allday-pointer.ts            |   6 +-
 .../src/calendar-event-plan.ts                | 159 ++++++
 .../src/calendar-month-pointer.ts             |   9 -
 .../src/calendar-occurrence.ts                |  85 ++--
 .../src/calendar-preview.ts                   | 291 +----------
 .../src/calendar-selection-move.ts            | 114 ++---
 .../src/calendar-time-grid-pointer.ts         |  38 +-
 .../src/calendar-validation.ts                |  81 ++-
 .../json-document-editing/src/calendar.ts     | 407 +++------------
 .../tests/calendar-pointer.test.ts            |   8 +-
 .../tests/calendar-protocol.test.ts           | 300 +++++++++++
 site/scripts/check-calendar-allday-span.mjs   |   6 +-
 site/src/app/routeTree.gen.ts                 | 476 +++++++++---------
 site/src/app/routes/_page/docs/api.tsx        |   6 -
 site/src/app/routes/_page/docs/api/index.tsx  |   6 +
 .../calendar-demo/CalendarDemoRoute.tsx       |   7 +-
 site/src/routes/docs/doc-pages.ts             |   5 +-
 .../src/shared/demo-workbench/demo-sources.ts |   8 +
 site/tests/unit/demo-workbench.test.tsx       |  10 +
 site/tests/unit/docs-route.test.tsx           |  21 +
 35 files changed, 1389 insertions(+), 1097 deletions(-)
 create mode 100644 packages/json-document-calendar/tests/calendar-protocol.test.tsx
 create mode 100644 packages/json-document-editing/docs/calendar-profile.md
 create mode 100644 packages/json-document-editing/src/calendar-event-plan.ts
 create mode 100644 packages/json-document-editing/tests/calendar-protocol.test.ts
 delete mode 100644 site/src/app/routes/_page/docs/api.tsx
 create mode 100644 site/src/app/routes/_page/docs/api/index.tsx

diff --git a/docs/api-reference/calendar.md b/docs/api-reference/calendar.md
index ddd6773c..ed523d30 100644
--- a/docs/api-reference/calendar.md
+++ b/docs/api-reference/calendar.md
@@ -216,7 +216,7 @@ interface CalendarHand {
   undo(): void;
   redo(): void;
   copy(): CalendarClipboard | null;
-  cut(): EditingResult<CalendarSelection> | null;
+  cut(clipboard?: CalendarClipboard): EditingResult<CalendarSelection> | null;
   paste(clipboard: CalendarClipboard): EditingResult<CalendarSelection>;
 }
 ```
@@ -226,6 +226,7 @@ interface CalendarHand {
 type CalendarHandOptions = {
   readonly initialOccurrence?: CalendarOccurrenceRange;
   readonly defaultTitle?: string;
+  readonly onResult?: (result: EditingResult<CalendarSelection>) => void;
 };
 ```
 ## `CalendarKeyboardOptions`
@@ -348,6 +349,8 @@ type CalendarPeriod = "day" | CalendarGrain;
 
 ```ts
 interface CalendarPointerInteractions {
+  /** Bind to one Calendar surface; canonical grids attach it automatically. */
+  readonly rootRef: RefObject<HTMLDivElement | null>;
   readonly hoveredTime: { readonly day: string; readonly instant: string; readonly minutes: number } | null;
   instantAt(day: string, clientY: number, grid: Element): string | null;
   timePointerDown(event: PointerEvent<HTMLElement>, day: string, id: string | null, start: string | null, end: string | null, handle: CalendarTimeGridHandle | null): void;
diff --git a/docs/api-reference/editing.md b/docs/api-reference/editing.md
index 2137c922..b79ee7d5 100644
--- a/docs/api-reference/editing.md
+++ b/docs/api-reference/editing.md
@@ -240,8 +240,8 @@ interface CalendarEditor {
   ): CalendarSelectionDragSource | null;
   dispatch(intent: CalendarIntent): EditingResult<CalendarSelection>;
   copy(occurrences?: ReadonlyArray<CalendarOccurrenceSelection>): CalendarClipboard | null;
-  cut(occurrences?: ReadonlyArray<CalendarOccurrenceSelection>): EditingClipboardCut<CalendarClipboard, EditingResult<CalendarSelection>> | null;
-  paste(clipboard: CalendarClipboard, target?: string): EditingResult<CalendarSelection>;
+  cut(source?: ReadonlyArray<CalendarOccurrenceSelection> | CalendarClipboard): EditingClipboardCut<CalendarClipboard, EditingResult<CalendarSelection>> | null;
+  paste(clipboard: CalendarClipboard, target?: string, options?: { readonly calendarId?: string }): EditingResult<CalendarSelection>;
   undo(): EditingResult<CalendarSelection>;
   redo(): EditingResult<CalendarSelection>;
   subscribe(listener: (snapshot: EditingSnapshot<CalendarSelection>) => void): () => void;
diff --git a/docs/evaluate.mjs b/docs/evaluate.mjs
index 25fd93e3..9cd63d0a 100644
--- a/docs/evaluate.mjs
+++ b/docs/evaluate.mjs
@@ -287,11 +287,12 @@ const misplacedMarkdown = filesUnder("").filter((path) => {
   return path.endsWith(".md")
     && !path.startsWith("docs/")
     && !path.startsWith("standards/")
+    && !rootPackage.workspaces.some((workspace) => workspace.startsWith("packages/") && path.startsWith(`${workspace}/docs/`))
     && name !== "README.md"
     && name !== "AGENTS.md";
 });
 if (misplacedMarkdown.length > 0) {
-  fail(`docs layout: non-README markdown must live under docs/: ${misplacedMarkdown.join(", ")}.`);
+  fail(`docs layout: non-README markdown must live under docs/, standards/, or a registered package's docs/: ${misplacedMarkdown.join(", ")}.`);
 }
 
 for (const [name, source] of Object.entries(surfaces)) {
diff --git a/package-lock.json b/package-lock.json
index d8fb9442..e3e60a52 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -6544,6 +6544,9 @@
       "name": "@interactive-os/json-document-calendar",
       "version": "0.1.0-rc.0",
       "license": "MIT",
+      "dependencies": {
+        "@js-temporal/polyfill": "^0.5.1"
+      },
       "devDependencies": {
         "@interactive-os/json-document-affordance": "*",
         "@interactive-os/json-document-editing": "*",
diff --git a/packages/json-document-calendar/README.md b/packages/json-document-calendar/README.md
index 8c961bb8..9eedc1df 100644
--- a/packages/json-document-calendar/README.md
+++ b/packages/json-document-calendar/README.md
@@ -12,19 +12,43 @@ time-grid policy.
 const editor = createCalendarEditor(document);
 const calendar = useCalendarHand(editor);
 
-calendar.dispatch({ type: "selection.set", eventIds: [eventId] });
+calendar.dispatch({
+  type: "selection.set",
+  point: { eventId, occurrenceStart },
+  topology: calendarOccurrenceTopology(document, rangeStart, rangeEnd),
+});
 calendar.applySelectedPatch({ title: "Planning" });
 const payload = calendar.copy();
-calendar.paste(payload);
+if (payload !== null) calendar.paste(payload);
 const titleInput = useCalendarRenameInput(calendar);
-useCalendarKeyboard({ active: true, onView, onShift, onToday, onCreate, onRemove });
+useCalendarKeyboard({ active: true, onView, onShift, onToday, onCreate, onRename, onRemove });
 ```
 
-The Hand resolves the currently focused occurrence as the copy/cut source and
-paste target. The Host selects Web representations; Calendar schema,
+The Hand resolves the currently focused occurrence as the copy source and
+paste target. Bind `cut: calendar.cut` directly to the Web clipboard surface:
+the Hand accepts the payload already written by Web and removes that captured
+target even if selection changes during the write. The Host selects Web representations; Calendar schema,
 occurrence projection, temporal placement, selection, and history remain in
 their canonical owners.
 
+Pass `onResult` to `useCalendarHand` to observe domain rejection codes and
+present product-owned feedback. `commitIntent` runs occurrence/rename aftercare
+only on success. Web clipboard decoding/writing failures remain Web results;
+observe the surface's `onResult` as well. Unexpected provider/programmer errors
+are not converted into a successful edit.
+
+`useCalendarPointerInteractions` exposes `rootRef`. `CalendarTimeGrid` and
+`CalendarMonthGrid` attach it automatically; a custom Calendar surface must
+attach it to its own root. Use one interaction instance per mounted surface.
+Hit tests and all-day column measurements never fall back to global document
+queries. Keyboard listeners can also use the existing `target` option when a
+Host embeds multiple active calendars.
+
+The domain-owned [Calendar protocol profile](../json-document-editing/docs/calendar-profile.md)
+defines temporal values, recurrence scopes, stale-source rejection and clipboard
+compatibility. On the site it is visible under [Editing API](/docs/api/editing#calendar-protocol-profile-rc);
+the Calendar Hand does not introduce a second domain protocol.
+
 Date and time controls belong to this Calendar owner rather than the generic UI
 Primitive package:
 
diff --git a/packages/json-document-calendar/package.json b/packages/json-document-calendar/package.json
index 01111c04..c2a9ab90 100644
--- a/packages/json-document-calendar/package.json
+++ b/packages/json-document-calendar/package.json
@@ -19,6 +19,9 @@
     "typecheck": "tsc -p tsconfig.test.json --noEmit",
     "verify": "npm run typecheck && npm test && npm run build"
   },
+  "dependencies": {
+    "@js-temporal/polyfill": "^0.5.1"
+  },
   "peerDependencies": {
     "@interactive-os/json-document-affordance": ">=0.1.0-rc.0 <1",
     "@interactive-os/json-document-editing": ">=0.1.0-rc.0 <1",
diff --git a/packages/json-document-calendar/src/calendar-month-grid.tsx b/packages/json-document-calendar/src/calendar-month-grid.tsx
index 9dd398be..64e93c43 100644
--- a/packages/json-document-calendar/src/calendar-month-grid.tsx
+++ b/packages/json-document-calendar/src/calendar-month-grid.tsx
@@ -124,6 +124,7 @@ export const CalendarMonthGrid = forwardRef<CalendarMonthGridHandle, CalendarMon
 
     return (
       <div
+        ref={interactions.rootRef}
         role="grid"
         aria-label={props.labels.grid}
         aria-multiselectable="true"
diff --git a/packages/json-document-calendar/src/calendar-time-grid.tsx b/packages/json-document-calendar/src/calendar-time-grid.tsx
index f0bbefdb..2141dcfe 100644
--- a/packages/json-document-calendar/src/calendar-time-grid.tsx
+++ b/packages/json-document-calendar/src/calendar-time-grid.tsx
@@ -116,6 +116,7 @@ export function CalendarTimeGrid(props: CalendarTimeGridProps): ReactNode {
   const gridHeight = (props.hourEnd - props.hourStart) * props.pixelsPerHour;
   return (
     <div
+      ref={interactions.rootRef}
       role="grid"
       aria-multiselectable="true"
       aria-label={props.labels.grid}
diff --git a/packages/json-document-calendar/src/use-calendar-hand.ts b/packages/json-document-calendar/src/use-calendar-hand.ts
index 97d03c04..4a7fbf76 100644
--- a/packages/json-document-calendar/src/use-calendar-hand.ts
+++ b/packages/json-document-calendar/src/use-calendar-hand.ts
@@ -1,6 +1,7 @@
 import { useRef, useState } from "react";
 import { createRenameSession, type RenameSessionSnapshot } from "@interactive-os/json-document-affordance";
 import {
+  calendarClipboardFormat,
   calendarOccurrenceAfterIntent,
   calendarOccurrenceForInspector,
   calendarOccurrenceFromSelection,
@@ -38,6 +39,7 @@ export interface CalendarSelectionDragPreview {
 export type CalendarHandOptions = {
   readonly initialOccurrence?: CalendarOccurrenceRange;
   readonly defaultTitle?: string;
+  readonly onResult?: (result: EditingResult<CalendarSelection>) => void;
 };
 
 export interface CalendarHand {
@@ -88,12 +90,14 @@ export interface CalendarHand {
   undo(): void;
   redo(): void;
   copy(): CalendarClipboard | null;
-  cut(): EditingResult<CalendarSelection> | null;
+  cut(clipboard?: CalendarClipboard): EditingResult<CalendarSelection> | null;
   paste(clipboard: CalendarClipboard): EditingResult<CalendarSelection>;
 }
 
 export function useCalendarHand(editor: CalendarEditor, options: CalendarHandOptions = {}): CalendarHand {
   const snapshot = useEditingSnapshot(editor);
+  const optionsRef = useRef(options);
+  optionsRef.current = options;
   const selectedEvent = editor.selectedEvents[0] ?? null;
   const selectedOccurrences = editor.selectedOccurrences;
   const [occurrence, setOccurrence] = useState<CalendarOccurrenceRange>(
@@ -112,15 +116,13 @@ export function useCalendarHand(editor: CalendarEditor, options: CalendarHandOpt
       if (current === undefined) return;
       const next = draft.trim() || (options.defaultTitle ?? "Event");
       if (next !== current.title) {
-        editor.dispatch(calendarUpdateIntent(current, occurrenceRef.current.start, scopeRef.current, { title: next }));
-        setOccurrence(calendarOccurrenceFromSelection(editor.selectedEvents[0] ?? null));
+        if (dispatch(calendarUpdateIntent(current, occurrenceRef.current.start, scopeRef.current, { title: next }))) rememberSelection();
       }
     },
     onCancel(key, draft) {
       const fallback = options.defaultTitle ?? "Event";
       if (createdRenameKeyRef.current === key && (draft.trim() === "" || draft.trim() === fallback)) {
-        editor.dispatch({ type: "selection.remove" });
-        setOccurrence(calendarOccurrenceFromSelection(editor.selectedEvents[0] ?? null));
+        if (dispatch({ type: "selection.remove" })) rememberSelection();
       }
     },
     onFinish(key) {
@@ -156,11 +158,16 @@ export function useCalendarHand(editor: CalendarEditor, options: CalendarHandOpt
     : selectedEvent?.title ?? "";
 
   function dispatch(intent: CalendarIntent | null): boolean {
-    return intent !== null && editor.dispatch(intent).ok;
+    return intent !== null && observe(editor.dispatch(intent)).ok;
+  }
+
+  function observe(result: EditingResult<CalendarSelection>): EditingResult<CalendarSelection> {
+    optionsRef.current.onResult?.(result);
+    return result;
   }
 
   function rememberSelection(): void {
-    setOccurrence(calendarOccurrenceFromSelection(editor.selectedEvents[0] ?? null));
+    setOccurrence(calendarOccurrenceFromSelection(editor.primaryOccurrence));
   }
 
   function commitIntent(intent: CalendarIntent | null, origin: CalendarOccurrenceRange): boolean {
@@ -170,7 +177,7 @@ export function useCalendarHand(editor: CalendarEditor, options: CalendarHandOpt
   }
 
   function rememberIntent(intent: CalendarIntent | null, origin: CalendarOccurrenceRange): void {
-    const committed = calendarOccurrenceFromSelection(editor.selectedEvents[0] ?? null);
+    const committed = calendarOccurrenceFromSelection(editor.primaryOccurrence);
     setOccurrence(calendarOccurrenceAfterIntent(intent, origin, committed));
     if (intent?.type === "event.create") {
       setScope("this");
@@ -287,28 +294,29 @@ export function useCalendarHand(editor: CalendarEditor, options: CalendarHandOpt
 
   function undo(): void {
     setSelectionDragPreview(null);
-    editor.undo();
-    rememberSelection();
+    if (observe(editor.undo()).ok) rememberSelection();
   }
 
   function redo(): void {
     setSelectionDragPreview(null);
-    editor.redo();
-    rememberSelection();
+    if (observe(editor.redo()).ok) rememberSelection();
   }
 
   function copy(): CalendarClipboard | null {
     return editor.copy();
   }
 
-  function cut(): EditingResult<CalendarSelection> | null {
-    const cut = editor.cut();
-    if (cut?.result.ok) rememberSelection();
-    return cut?.result ?? null;
+  function cut(clipboard?: CalendarClipboard): EditingResult<CalendarSelection> | null {
+    if (clipboard !== undefined && calendarClipboardFormat.parse(clipboard) === null) return observe({ ok: false, code: "clipboard.invalid" });
+    const cut = editor.cut(clipboard);
+    if (cut === null) return null;
+    const result = observe(cut.result);
+    if (result.ok) rememberSelection();
+    return result;
   }
 
   function paste(clipboard: CalendarClipboard): EditingResult<CalendarSelection> {
-    const result = editor.paste(clipboard, occurrence.start ?? selectedEvent?.start);
+    const result = observe(editor.paste(clipboard, occurrence.start ?? selectedEvent?.start));
     if (result.ok) rememberSelection();
     return result;
   }
diff --git a/packages/json-document-calendar/src/use-calendar-pointer-interactions.ts b/packages/json-document-calendar/src/use-calendar-pointer-interactions.ts
index 940b8882..589066b8 100644
--- a/packages/json-document-calendar/src/use-calendar-pointer-interactions.ts
+++ b/packages/json-document-calendar/src/use-calendar-pointer-interactions.ts
@@ -1,10 +1,10 @@
-import { useRef, useState, type PointerEvent } from "react";
+import { useRef, useState, type PointerEvent, type RefObject } from "react";
 import { createGestureSession } from "@interactive-os/json-document-affordance";
 import {
   addCalendarDate, bindCalendarAllDayIntent, bindCalendarMonthIntent, bindCalendarTimeGridIntent,
   calendarEventsOnDay, calendarInstantAt, calendarShiftInstant, calendarVisibleEvents,
   interpretCalendarAllDayPointer, interpretCalendarMonthPointer, interpretCalendarTimeGridPointer,
-  type CalendarAllDayPointerRelease, type CalendarIntent, type CalendarTimeGridHandle,
+  type CalendarAllDayPointerRelease, type CalendarTimeGridHandle,
   type CalendarTimeGridPointerRelease,
   type CalendarSelectionDragSource,
 } from "@interactive-os/json-document-editing";
@@ -43,6 +43,8 @@ type CalendarSelectionDragGesture = {
 };
 
 export interface CalendarPointerInteractions {
+  /** Bind to one Calendar surface; canonical grids attach it automatically. */
+  readonly rootRef: RefObject<HTMLDivElement | null>;
   readonly hoveredTime: { readonly day: string; readonly instant: string; readonly minutes: number } | null;
   instantAt(day: string, clientY: number, grid: Element): string | null;
   timePointerDown(event: PointerEvent<HTMLElement>, day: string, id: string | null, start: string | null, end: string | null, handle: CalendarTimeGridHandle | null): void;
@@ -66,6 +68,7 @@ export interface CalendarPointerInteractions {
 
 /** Owns Calendar's Web pointer preview, commit, cancel, and resize lifecycle. */
 export function useCalendarPointerInteractions(hand: CalendarHand, policy: CalendarPointerPolicy): CalendarPointerInteractions {
+  const rootRef = useRef<HTMLDivElement>(null);
   const [timePointer] = useState(() => createWebPointerSession<TimeRelease>());
   const [allDayPointer] = useState(() => createWebPointerSession<AllDayRelease>());
   const [monthPointer] = useState(() => createWebPointerSession<MonthRelease>());
@@ -76,9 +79,8 @@ export function useCalendarPointerInteractions(hand: CalendarHand, policy: Calen
   const document = hand.document;
   const visibleEvents = calendarVisibleEvents(document);
 
-  function remember(intent: CalendarIntent | null, start: string | null, end: string | null): void {
-    hand.dispatch(intent);
-    hand.rememberIntent(intent, { start, end });
+  function pointTarget(selector: string, event: { clientX: number; clientY: number }): Element | null {
+    return rootRef.current === null ? null : findWebPointTarget<Element>(selector, { x: event.clientX, y: event.clientY }, rootRef.current);
   }
 
   function bindTime(intent: ReturnType<typeof interpretCalendarTimeGridPointer>, occurrenceStart: string | null) {
@@ -97,7 +99,7 @@ export function useCalendarPointerInteractions(hand: CalendarHand, policy: Calen
     if (release.originEventId === null) return;
     const event = document.events.find((item) => item.id === release.originEventId);
     const intent = bindCalendarAllDayIntent(interpretCalendarAllDayPointer(release), event, release.originEventStart, hand.scope);
-    remember(intent, release.originEventStart, event?.end ?? null);
+    hand.commitIntent(intent, { start: release.originEventStart, end: event?.end ?? null });
   }
 
   function timePointerDown(event: PointerEvent<HTMLElement>, day: string, originEventId: string | null, originEventStart: string | null, originEventEnd: string | null, originHandle: CalendarTimeGridHandle | null): void {
@@ -116,7 +118,7 @@ export function useCalendarPointerInteractions(hand: CalendarHand, policy: Calen
   }
 
   function timePointerMove(event: PointerEvent<HTMLElement>): void {
-    const grid = findWebPointTarget<Element>('[data-calendar-grid="time"]', { x: event.clientX, y: event.clientY });
+    const grid = pointTarget('[data-calendar-grid="time"]', event);
     const day = grid?.getAttribute("data-calendar-day");
     if (grid == null || day == null) return;
     if (timePointer.getSnapshot()?.pointerId !== event.pointerId) {
@@ -144,7 +146,11 @@ export function useCalendarPointerInteractions(hand: CalendarHand, policy: Calen
     if (next?.dragSource !== null && next?.dragSource !== undefined) {
       const originAnchor = next.dragSource.anchor.occurrenceStart;
       const move = interpretCalendarTimeGridPointer(next);
-      if (move?.type !== "event.move") return;
+      if (move?.type !== "event.move") {
+        selectionDrag.cancel("pointer-cancel");
+        hand.previewSelectionDrag(null);
+        return;
+      }
       if (selectionDrag.getActive() === null) selectionDrag.begin({ type: "calendar-selection-drag", source: next.dragSource, target: { type: "instant", instant: originAnchor } });
       const gesture = selectionDrag.preview((active) => ({ ...active, target: { type: "instant", instant: move.start } }));
       hand.previewSelectionDrag(gesture);
@@ -168,7 +174,7 @@ export function useCalendarPointerInteractions(hand: CalendarHand, policy: Calen
       hand.setOccurrence({ start: release.targetInstant, end: release.targetInstant });
       return;
     }
-    remember(bindTime(interpretCalendarTimeGridPointer(release), release.originEventStart), release.originEventStart, release.originEventEnd);
+    hand.commitIntent(bindTime(interpretCalendarTimeGridPointer(release), release.originEventStart), { start: release.originEventStart, end: release.originEventEnd });
   }
 
   function allDayPointerDown(event: PointerEvent<HTMLElement>, originDay: string, originEventId: string | null, originEventStart: string | null, originEventEnd: string | null, originHandle: "body" | "start" | "end" | null): void {
@@ -184,7 +190,7 @@ export function useCalendarPointerInteractions(hand: CalendarHand, policy: Calen
 
   function allDayPointerMove(event: PointerEvent<HTMLElement>): void {
     if (allDayPointer.getSnapshot()?.pointerId !== event.pointerId) return;
-    const targetDay = findWebPointTarget<Element>("[data-calendar-allday-day]", { x: event.clientX, y: event.clientY })?.getAttribute("data-calendar-allday-day");
+    const targetDay = pointTarget("[data-calendar-allday-day]", event)?.getAttribute("data-calendar-allday-day");
     if (targetDay == null) return;
     const next = allDayPointer.preview(event.pointerId, (state) => {
       const dragSource = state.dragSource ?? (state.dragCandidate !== null && targetDay !== state.originDay
@@ -193,8 +199,14 @@ export function useCalendarPointerInteractions(hand: CalendarHand, policy: Calen
       return { ...state, targetDay, dragSource };
     });
     if (next?.dragSource !== null && next?.dragSource !== undefined) {
+      const move = interpretCalendarAllDayPointer(next);
+      if (move?.type !== "event.move-day") {
+        selectionDrag.cancel("pointer-cancel");
+        hand.previewSelectionDrag(null);
+        return;
+      }
       if (selectionDrag.getActive() === null) selectionDrag.begin({ type: "calendar-selection-drag", source: next.dragSource, target: { type: "day", day: next.originDay } });
-      const gesture = selectionDrag.preview((active) => ({ ...active, target: { type: "day", day: targetDay } }));
+      const gesture = selectionDrag.preview((active) => ({ ...active, target: { type: "day", day: move.day } }));
       hand.previewSelectionDrag(gesture);
     } else if (next !== null) hand.setAllDayPreview(next);
   }
@@ -203,13 +215,19 @@ export function useCalendarPointerInteractions(hand: CalendarHand, policy: Calen
     const release = allDayPointer.commit(event.pointerId);
     hand.setAllDayPreview(null);
     if (release === null) return;
-    const targetDay = findWebPointTarget<Element>("[data-calendar-allday-day]", { x: event.clientX, y: event.clientY })?.getAttribute("data-calendar-allday-day");
-    if (targetDay == null) return;
+    const targetDay = pointTarget("[data-calendar-allday-day]", event)?.getAttribute("data-calendar-allday-day");
+    if (targetDay == null) {
+      selectionDrag.cancel("pointer-cancel");
+      hand.previewSelectionDrag(null);
+      return;
+    }
     if (release.dragSource !== null) {
       suppressEventClick.current = true;
       suppressDoubleClickBriefly();
       const gesture = selectionDrag.commit();
-      if (gesture !== null) hand.commitSelectionDrag({ ...gesture, target: { type: "day", day: targetDay } });
+      const move = interpretCalendarAllDayPointer({ ...release, targetDay });
+      hand.previewSelectionDrag(null);
+      if (gesture !== null && move?.type === "event.move-day") hand.commitSelectionDrag({ ...gesture, target: { type: "day", day: move.day } });
       return;
     }
     if (release.dragCandidate !== null) return;
@@ -221,7 +239,7 @@ export function useCalendarPointerInteractions(hand: CalendarHand, policy: Calen
     }
     const id = raw?.type === "event.move-day" || raw?.type === "event.resize" ? raw.eventId : null;
     const intent = bindCalendarAllDayIntent(raw, id === null ? undefined : document.events.find((item) => item.id === id), release.originEventStart, hand.scope);
-    remember(intent, release.originEventStart, release.originEventEnd);
+    hand.commitIntent(intent, { start: release.originEventStart, end: release.originEventEnd });
   }
 
   function monthPointerDown(event: PointerEvent<HTMLElement>, fallbackDay: string, rowDays: ReadonlyArray<string>, originEventId: string | null, originEventStart: string | null, originEventEnd: string | null): void {
@@ -242,7 +260,7 @@ export function useCalendarPointerInteractions(hand: CalendarHand, policy: Calen
 
   function monthPointerMove(event: PointerEvent<HTMLElement>): void {
     if (monthPointer.getSnapshot()?.pointerId !== event.pointerId) return;
-    const targetDay = findWebPointTarget<Element>("[data-calendar-day]", { x: event.clientX, y: event.clientY })?.getAttribute("data-calendar-day");
+    const targetDay = pointTarget("[data-calendar-day]", event)?.getAttribute("data-calendar-day");
     if (targetDay == null) return;
     const next = monthPointer.preview(event.pointerId, (state) => {
       const dragSource = state.dragSource ?? (state.dragCandidate !== null && targetDay !== state.originDay
@@ -251,8 +269,14 @@ export function useCalendarPointerInteractions(hand: CalendarHand, policy: Calen
       return { ...state, targetDay, dragSource };
     });
     if (next?.dragSource !== null && next?.dragSource !== undefined) {
+      const move = interpretCalendarMonthPointer(next);
+      if (move?.type !== "event.move-day") {
+        selectionDrag.cancel("pointer-cancel");
+        hand.previewSelectionDrag(null);
+        return;
+      }
       if (selectionDrag.getActive() === null) selectionDrag.begin({ type: "calendar-selection-drag", source: next.dragSource, target: { type: "day", day: next.originDay } });
-      const gesture = selectionDrag.preview((active) => ({ ...active, target: { type: "day", day: targetDay } }));
+      const gesture = selectionDrag.preview((active) => ({ ...active, target: { type: "day", day: move.day } }));
       hand.previewSelectionDrag(gesture);
     } else if (next !== null) hand.setMonthPreview({ ...next, eventsOnTargetDay: [] });
   }
@@ -261,13 +285,19 @@ export function useCalendarPointerInteractions(hand: CalendarHand, policy: Calen
     const release = monthPointer.commit(event.pointerId);
     hand.setMonthPreview(null);
     if (release === null) return;
-    const targetDay = findWebPointTarget<Element>("[data-calendar-day]", { x: event.clientX, y: event.clientY })?.getAttribute("data-calendar-day");
-    if (targetDay == null) return;
+    const targetDay = pointTarget("[data-calendar-day]", event)?.getAttribute("data-calendar-day");
+    if (targetDay == null) {
+      selectionDrag.cancel("pointer-cancel");
+      hand.previewSelectionDrag(null);
+      return;
+    }
     if (release.dragSource !== null) {
       suppressEventClick.current = true;
       suppressDoubleClickBriefly();
       const gesture = selectionDrag.commit();
-      if (gesture !== null) hand.commitSelectionDrag({ ...gesture, target: { type: "day", day: targetDay } });
+      const move = interpretCalendarMonthPointer({ ...release, targetDay });
+      hand.previewSelectionDrag(null);
+      if (gesture !== null && move?.type === "event.move-day") hand.commitSelectionDrag({ ...gesture, target: { type: "day", day: move.day } });
       return;
     }
     if (release.dragCandidate !== null) return;
@@ -279,7 +309,7 @@ export function useCalendarPointerInteractions(hand: CalendarHand, policy: Calen
     }
     const id = raw?.type === "event.move-day" ? raw.eventId : null;
     const intent = bindCalendarMonthIntent(raw, id === null ? undefined : document.events.find((item) => item.id === id), release.originEventStart, hand.scope);
-    remember(intent, release.originEventStart, release.originEventEnd);
+    hand.commitIntent(intent, { start: release.originEventStart, end: release.originEventEnd });
   }
 
   function resizeTimed(id: string, edge: "start" | "end", occurrenceStart: string, origin: string, delta: number, phase: Phase): void {
@@ -289,12 +319,15 @@ export function useCalendarPointerInteractions(hand: CalendarHand, policy: Calen
     const release = { originInstant: origin, originEventId: id, originEventStart: occurrenceStart, originHandle: edge, targetInstant };
     if (phase === "preview") return hand.setTimePreview(release);
     hand.setTimePreview(null);
-    remember(bindTime(interpretCalendarTimeGridPointer(release), occurrenceStart), occurrenceStart, targetInstant);
+    hand.commitIntent(bindTime(interpretCalendarTimeGridPointer(release), occurrenceStart), { start: occurrenceStart, end: targetInstant });
   }
 
   function resizeAllDay(id: string, edge: "start" | "end", originDay: string, occurrenceStart: string, delta: number, phase: Phase): void {
-    const column = globalThis.document.querySelector("[data-calendar-allday-day]") ?? globalThis.document.querySelector("[data-calendar-week] [data-calendar-day]");
-    const targetDay = addCalendarDate(originDay, calendarDayDeltaFromWebWidth(delta, column?.getBoundingClientRect().width ?? 0));
+    const column = rootRef.current?.querySelector("[data-calendar-allday-day]") ?? rootRef.current?.querySelector("[data-calendar-week] [data-calendar-day]");
+    if (column == null) return;
+    const width = column.getBoundingClientRect().width;
+    if (width <= 0) return;
+    const targetDay = addCalendarDate(originDay, calendarDayDeltaFromWebWidth(delta, width));
     if (targetDay === null) return;
     const release = { originDay, originEventId: id, originEventStart: occurrenceStart, originHandle: edge, targetDay };
     if (phase === "preview") return hand.setAllDayPreview(release);
@@ -328,6 +361,7 @@ export function useCalendarPointerInteractions(hand: CalendarHand, policy: Calen
   }
 
   return {
+    rootRef,
     hoveredTime,
     instantAt,
     timePointerDown,
diff --git a/packages/json-document-calendar/tests/calendar-protocol.test.tsx b/packages/json-document-calendar/tests/calendar-protocol.test.tsx
new file mode 100644
index 00000000..1c68ca4c
--- /dev/null
+++ b/packages/json-document-calendar/tests/calendar-protocol.test.tsx
@@ -0,0 +1,145 @@
+import { act, cleanup, renderHook } from "@testing-library/react";
+import { afterEach, describe, expect, test, vi } from "vitest";
+import { calendarClipboardFormat, createCalendarEditor, type CalendarDocument } from "@interactive-os/json-document-editing";
+import { createWebClipboardBinding, createWebJSONClipboardRepresentation } from "@interactive-os/json-document-web";
+import { useCalendarHand, useCalendarPointerInteractions } from "../src/index.js";
+
+afterEach(cleanup);
+const initial: CalendarDocument = {
+  calendars: [{ id: "work", title: "Work", hidden: false, color: "accent" }],
+  events: [{ id: "a", title: "A", start: "2026-08-01T09:00", end: "2026-08-01T10:00", allDay: false, calendarId: "work", recurrence: null, excludeDates: [] }],
+};
+const policy = { hourStart: 0, hourEnd: 24, stepMinutes: 15, pixelsPerHour: 60 };
+const rect = (width: number) => ({ left: 0, right: width, top: 0, bottom: 1440, width, height: 1440, x: 0, y: 0, toJSON: () => ({}) });
+function surface(width: number, day: string) {
+  const root = document.createElement("div");
+  const grid = document.createElement("div");
+  grid.dataset.calendarGrid = "time";
+  grid.dataset.calendarDay = day;
+  grid.dataset.calendarAlldayDay = day;
+  grid.getBoundingClientRect = () => rect(width);
+  root.append(grid);
+  document.body.append(root);
+  return { root, grid };
+}
+
+describe("Calendar Hand protocol composition", () => {
+  test.each(["time", "allDay", "month"] as const)("returning a %s drag to its origin clears preview and does not commit", (kind) => {
+    const sourceEvent = kind === "time" ? initial.events[0]! : { ...initial.events[0]!, start: "2026-08-01", end: "2026-08-02", allDay: true };
+    const editor = createCalendarEditor({ ...initial, events: [sourceEvent] });
+    const { result } = renderHook(() => {
+      const hand = useCalendarHand(editor);
+      return { hand, pointer: useCalendarPointerInteractions(hand, policy) };
+    });
+    const { root, grid } = surface(100, kind === "time" ? "2026-08-01" : "2026-08-02");
+    try {
+      result.current.pointer.rootRef.current = root;
+      const target = { closest: () => kind === "time" ? grid : null, focus() {}, setPointerCapture() {}, hasPointerCapture: () => false, releasePointerCapture() {} };
+      const down = { button: 0, clientX: 50, clientY: 540, currentTarget: target, pointerId: 1 } as never;
+      act(() => {
+        if (kind === "time") result.current.pointer.timePointerDown(down, "2026-08-01", "a", sourceEvent.start, sourceEvent.end, "body");
+        else if (kind === "allDay") result.current.pointer.allDayPointerDown(down, "2026-08-01", "a", sourceEvent.start, sourceEvent.end, "body");
+        else result.current.pointer.monthPointerDown(down, "2026-08-01", ["2026-08-01"], "a", sourceEvent.start, sourceEvent.end);
+      });
+      act(() => result.current.pointer[`${kind}PointerMove`]({ pointerId: 1, clientX: 50, clientY: 600, target: grid } as never));
+      expect(result.current.hand.selectionDragPreview).not.toBeNull();
+      grid.dataset.calendarDay = grid.dataset.calendarAlldayDay = "2026-08-01";
+      act(() => result.current.pointer[`${kind}PointerMove`]({ pointerId: 1, clientX: 50, clientY: 540, target: grid } as never));
+      expect(result.current.hand.selectionDragPreview).toBeNull();
+      act(() => result.current.pointer[`${kind}PointerUp`]({ pointerId: 1, clientX: 50, clientY: 540 } as never));
+      expect(result.current.hand.document.events).toEqual([sourceEvent]);
+      expect(editor.snapshot.canUndo).toBe(false);
+    } finally { root.remove(); }
+  });
+
+  test("cuts the written payload even when the writer re-enters selection", () => {
+    const editor = createCalendarEditor({ ...initial, events: [...initial.events, { ...structuredClone(initial.events[0]!), id: "b", title: "B" }] });
+    const { result } = renderHook(() => useCalendarHand(editor));
+    const data = new Map<string, string>();
+    const binding = createWebClipboardBinding({
+      codec: createWebJSONClipboardRepresentation(calendarClipboardFormat),
+      read: result.current.copy, cut: result.current.cut, paste: result.current.paste,
+    });
+    act(() => {
+      expect(binding.cut({
+        clipboardData: {
+          types: [],
+          getData: (type) => data.get(type) ?? "",
+          setData(type, value) {
+            data.set(type, value);
+            editor.dispatch({ type: "selection.set", point: { eventId: "b", occurrenceStart: "2026-08-01T09:00" } });
+          },
+        },
+        preventDefault() {},
+      }).ok).toBe(true);
+    });
+    expect(JSON.parse(data.get(calendarClipboardFormat.mimeType)!).items[0].sourceEventId).toBe("a");
+    expect(result.current.document.events.map((event) => event.id)).toEqual(["b"]);
+  });
+
+  test("reports a rejected pointer edit without success aftercare", () => {
+    const editor = createCalendarEditor(initial, { createId: () => "draft" });
+    const onResult = vi.fn();
+    const { result } = renderHook(() => {
+      const hand = useCalendarHand(editor, { onResult });
+      return { hand, pointer: useCalendarPointerInteractions(hand, policy) };
+    });
+    act(() => result.current.hand.createInterval("2026-08-01T11:00", "2026-08-01T12:00"));
+    const before = editor.snapshot;
+    const occurrence = result.current.hand.occurrence;
+    act(() => result.current.pointer.resizeTimed("draft", "end", "2026-08-01T11:00", "2026-08-01T12:00", -120, "commit"));
+    expect(editor.snapshot).toEqual(before);
+    expect(result.current.hand.occurrence).toEqual(occurrence);
+    expect(result.current.hand.renaming).toBe(true);
+    expect(onResult).toHaveBeenLastCalledWith(expect.objectContaining({ ok: false, code: "event.invalid-interval" }));
+  });
+
+  test("keeps the edited later occurrence focused for all-scope Inspector follow-up", () => {
+    const editor = createCalendarEditor({ ...initial, events: [{ ...initial.events[0]!, recurrence: { freq: "daily", interval: 1, until: "2026-08-08" } }] });
+    const { result } = renderHook(() => useCalendarHand(editor));
+    act(() => result.current.selectOccurrence("a", "2026-08-03T09:00", "2026-08-03T10:00"));
+    act(() => result.current.setScope("all"));
+    act(() => result.current.applySelectedPatch({ start: "2026-08-03T11:00" }));
+    expect(result.current.inspectedInterval).toEqual({ start: "2026-08-03T11:00", end: "2026-08-03T12:00" });
+    act(() => result.current.applySelectedPatch({ end: "2026-08-03T13:00" }));
+    expect(result.current.document.events[0]).toMatchObject({ start: "2026-08-01T11:00", end: "2026-08-01T13:00" });
+  });
+
+  test("two overlapping Calendar instances hit-test and resize within their own roots", () => {
+    const allDay = { ...initial, events: [{ ...initial.events[0]!, start: "2026-08-01", end: "2026-08-02", allDay: true }] };
+    const first = createCalendarEditor(allDay), second = createCalendarEditor(allDay);
+    const { result } = renderHook(() => {
+      const firstHand = useCalendarHand(first), secondHand = useCalendarHand(second);
+      return { first: useCalendarPointerInteractions(firstHand, policy), second: useCalendarPointerInteractions(secondHand, policy) };
+    });
+    const left = surface(100, "2026-08-01"), right = surface(200, "2026-08-02");
+    try {
+      result.current.first.rootRef.current = left.root;
+      result.current.second.rootRef.current = right.root;
+      act(() => result.current.second.timePointerMove({ pointerId: 1, clientX: 50, clientY: 540, target: right.grid } as never));
+      expect(result.current.second.hoveredTime?.day).toBe("2026-08-02");
+      act(() => result.current.first.resizeAllDay("a", "end", "2026-08-01", "2026-08-01", 200, "commit"));
+      act(() => result.current.second.resizeAllDay("a", "end", "2026-08-01", "2026-08-01", 200, "commit"));
+      expect((first.snapshot.value as CalendarDocument).events[0]?.end).toBe("2026-08-04");
+      expect((second.snapshot.value as CalendarDocument).events[0]?.end).toBe("2026-08-03");
+    } finally { left.root.remove(); right.root.remove(); }
+  });
+
+  test("all-day body dragging preserves the grab offset inside a multi-day span", () => {
+    const editor = createCalendarEditor({ ...initial, events: [{ ...initial.events[0]!, start: "2026-08-01", end: "2026-08-04", allDay: true }] });
+    const { result } = renderHook(() => {
+      const hand = useCalendarHand(editor);
+      return { hand, pointer: useCalendarPointerInteractions(hand, policy) };
+    });
+    const { root, grid } = surface(100, "2026-08-04");
+    try {
+      result.current.pointer.rootRef.current = root;
+      const target = { focus() {}, setPointerCapture() {}, hasPointerCapture: () => false, releasePointerCapture() {} };
+      act(() => result.current.pointer.allDayPointerDown({ button: 0, currentTarget: target, pointerId: 1 } as never, "2026-08-03", "a", "2026-08-01", "2026-08-04", "body"));
+      act(() => result.current.pointer.allDayPointerMove({ pointerId: 1, clientX: 50, clientY: 50, target: grid } as never));
+      expect(result.current.hand.paintedEvents[0]?.start).toBe("2026-08-02");
+      act(() => result.current.pointer.allDayPointerUp({ pointerId: 1, clientX: 50, clientY: 50 } as never));
+      expect(result.current.hand.document.events[0]).toMatchObject({ start: "2026-08-02", end: "2026-08-05" });
+    } finally { root.remove(); }
+  });
+});
diff --git a/packages/json-document-calendar/tests/use-calendar-hand.test.tsx b/packages/json-document-calendar/tests/use-calendar-hand.test.tsx
index 999ec4bf..e5505b9e 100644
--- a/packages/json-document-calendar/tests/use-calendar-hand.test.tsx
+++ b/packages/json-document-calendar/tests/use-calendar-hand.test.tsx
@@ -201,7 +201,10 @@ describe("useCalendarHand", () => {
     grid.dataset.calendarGrid = "time";
     grid.dataset.calendarDay = "2026-08-03";
     grid.getBoundingClientRect = () => ({ left: 0, right: 100, top: 0, bottom: 1440, width: 100, height: 1440, x: 0, y: 0, toJSON: () => ({}) });
-    document.body.append(grid);
+    const root = document.createElement("div");
+    root.append(grid);
+    document.body.append(root);
+    result.current.pointer.rootRef.current = root;
     const target = {
       closest: () => grid,
       focus: () => undefined,
@@ -227,7 +230,7 @@ describe("useCalendarHand", () => {
     expect(result.current.hand.document.events.map((item) => item.start)).toEqual([
       "2026-08-03T09:00", "2026-08-04T11:00",
     ]);
-    grid.remove();
+    root.remove();
   });
 
   test("finishes an outstanding create rename when selection drag commits", () => {
diff --git a/packages/json-document-editing/README.md b/packages/json-document-editing/README.md
index eef05856..a71d50fe 100644
--- a/packages/json-document-editing/README.md
+++ b/packages/json-document-editing/README.md
@@ -180,6 +180,9 @@ It publishes rows with hierarchy/ARIA facts and the matching `TreeTopology`.
 `gridPointKey` and `gridPointFromKey` provide the canonical reversible string
 identity when a selection or rendering adapter needs to key a `GridPoint`.
 
+`Calendar` follows the owner-local [Calendar protocol profile](docs/calendar-profile.md).
+The profile is also rendered on the site's Editing API page; it documents the
+current RC implementation, not a frozen Official Hands wire standard.
 `Calendar` keeps interval events `{ id, title, start, end, allDay }`. Timed
 events use datetime-local strings; all-day events use exclusive-end dates.
 `parseCalendarView` validates untrusted runtime values against the canonical
@@ -210,7 +213,8 @@ the public editors; each domain still owns its projection and removal plan.
 `interpretCalendarAllDayPointer`, and `interpretCalendarMonthPointer` map a
 press-release to those intents from the origin event, not the current
 selection. `calendarTimedLayout` places a timed event on its `start`/`end`
-span. Pixel grids and view chrome stay in the Host.
+span. Calendar Hands own reusable grids and lifecycle, Web owns pixel-coordinate
+translation, and Hosts retain visual composition and policy values.
 
 `Annotation` keeps a target selector separate from its presentation. Point
 targets may use numbered `marker` presentations for instructions or a
diff --git a/packages/json-document-editing/docs/calendar-profile.md b/packages/json-document-editing/docs/calendar-profile.md
new file mode 100644
index 00000000..43034769
--- /dev/null
+++ b/packages/json-document-editing/docs/calendar-profile.md
@@ -0,0 +1,105 @@
+## Calendar protocol profile (RC)
+
+정본 소유자는 `@interactive-os/json-document-editing`이다. 이 문서는 현재
+`0.1.0-rc.0` Calendar 구현의 계약과 한계를 명시한다. Core Stable 프로파일이나
+EditingSession 계약을 변경하지 않으며, Draft인 Official Hands / Editing Grammar를
+동결된 wire 표준으로 승격하지 않는다. Calendar Hands는 이 계약을 입력과 화면에 연결한다.
+
+### 값과 시간
+
+- 일정은 고유한 비어 있지 않은 `id`, 문자열 `title`, `start < end`인 구간을 갖는다.
+- timed 값은 정확히 `YYYY-MM-DDTHH:mm`인 local date-time이다. UTC Instant,
+  offset, timezone, 초 단위는 이 프로파일에 포함하지 않는다.
+- all-day 값은 `YYYY-MM-DD`이다. timed와 all-day 모두 종료는 exclusive이다.
+  8월 1일 하루는 `start: "2026-08-01", end: "2026-08-02"`다.
+- 현재 문서에 calendars가 있으면 비어 있지 않은 `calendarId`는 실제 calendar를
+  참조해야 한다. 기존 간단한 문서의 생략된 calendars / allDay / calendarId /
+  recurrence / excludeDates는 각각 빈 목록 / timed / 미지정 / 반복 없음 / 제외 없음으로
+  읽는 호환 경로를 유지한다. 새 clipboard 출력은 완전한 필드를 갖는다.
+- recurrence의 `freq`는 daily / weekly / monthly / yearly, `interval`은 양의
+  safe integer다. `until: ""`은 무기한, 그 외에는 발생 시작일 기준 inclusive 날짜다.
+  `excludeDates`는 발생 시작일을 제외한다. 월말·윤년의 발생 시작은 Temporal constrain
+  규칙을 따르고, 종료는 원본의 local duration을 보존한다. 시작·종료를 따로 constrain해
+  구간 길이가 0이나 음수가 되지 않는다.
+- projection은 요청한 `[rangeStart, rangeEnd)`와 겹치는 발생분을 계산한다. 과거
+  발생분을 처음부터 순회하거나 400회에서 수명을 잘라내지 않고 요청 구간 근처로 이동한다.
+  매우 넓은 조회의 출력량 자체를 제한하는 pagination 계약은 아직 없다.
+
+### 선택, 범위와 편집
+
+`{ eventId, occurrenceStart }`가 발생분의 정체성이다. Selection 정본의 materialized
+targets를 사용하며, 화면 밖에 있어도 현재 반복 규칙에 존재하는 선택은 유지된다.
+
+| scope | 의미 |
+| --- | --- |
+| this | 해당 발생분만 제외하고 독립 일정으로 분리 |
+| this-and-following | 이전 시리즈를 기준 발생일 전날까지 자르고 이후를 새 시리즈로 분리 |
+| all | 선택한 발생분의 변경량을 원본 시리즈 구간에 적용 |
+
+시작만 바꾸면 해당 발생분의 길이를 보존한다. resize는 지정한 경계만 바꾸며
+반복 시리즈의 원본 날짜와 선택 발생 날짜를 혼동하지 않는다. Inspector, 포인터,
+preview, 그룹 이동은 같은 순수 event/series 계획을 사용한다. preview ID는 임시이며
+commit ID와 같을 필요는 없지만 실제 일정 구간·반복 결과는 같아야 한다.
+
+그룹 이동은 선택 전체에 하나의 시간/일 변화량을 적용한다. this에서는 발생분별로
+분리하고, all / following에서는 같은 시리즈를 한 번만 편집한다. following 기준은
+선택·primary 순서와 무관하게 그 시리즈에서 선택된 가장 이른 발생분이다.
+월/년 주기를 재기준화해 모든 선택점의 같은 변화량을 표현할 수 없으면
+`selection.unrepresentable-series-move`로 그룹 전체를 거절한다. 단일 발생분의 all 편집도
+요청한 구간이 결과 시리즈에 실제로 존재해야 하며 같은 규칙으로 거절한다.
+
+시리즈 이동은 유한한 until과 제외 날짜도 시작일 변화량만큼 옮긴다. following은
+기존 종료일과 이후 제외 날짜를 보존하며 무조건 무기한으로 늘리지 않는다.
+allDay / calendarId / recurrence 자체의 Inspector 변경은 시리즈 속성 변경이다.
+`selection.remove`는 선택된 원본 일정을 삭제한다. 발생분 범위 삭제는
+`occurrence.remove`와 scope, clipboard cut은 캡처된 발생분을 사용한다.
+
+### 거절과 원자성
+
+생성·update·발생분 편집·paste는 생성자와 같은 도메인 불변식을 검증한다.
+잘못된 구간, 미등록 calendar, 소수 recurrence, 알 수 없는 Intent type은
+`{ ok: false, code, reason? }`로 끝나며 값·선택·undo/redo·알림을 바꾸지 않는다.
+성공한 문서는 다시 editor로 읽고 projection할 수 있어야 한다.
+
+드래그의 캡처 구간은 현재 사실이 아니라 precondition이다. commit 시 실제 발생분의
+존재와 start/end를 다시 확인한다. 삭제·제외되었거나 길이가 바뀐 발생분은
+`selection.stale-occurrence`로 거절한다. 제목만 바뀌거나 선택·뷰가 달라진 것은
+드래그를 무효화하지 않으며 새 제목을 보존한다. 그룹 실패는 일부만 적용하지 않는다.
+
+한 번의 편집/cut/paste/그룹 이동은 하나의 EditingSession 이력 단위다.
+입력 거절과 잘못된 provider/programmer 예외는 다르다. 예를 들어 ID provider가
+100회 충돌하면 공통 bounded allocator가 예외를 던지고 문서는 변경하지 않는다.
+Hands는 성공한 결과에만 선택/rename aftercare를 수행하고 `onResult`로 결과를 전달한다.
+
+### Clipboard 호환성과 외부 경계
+
+`application/vnd.interactive-os.calendar+json`은 현재 materialized occurrence
+clipboard 형식이다. `calendarClipboardFormat.parse(unknown)`는 잘못된 날짜·역전
+구간·비정규 event를 거절하고, 직접 호출한 `paste`도 같은 검증을 수행한다.
+anchor가 생략된 기존 payload는 첫 occurrence를 anchor로 읽는다.
+알 수 없는 추가 JSON 필드는 유지하지만 새 버전/새 의미의 호환을 보장하지 않는다.
+
+`copy()`는 빈 선택에서 null이다. `cut(capturedClipboard)`는 이미 기록한 payload의
+발생분만 삭제한다. 그 사이 선택이 달라져도 대상을 다시 선택하지 않으며, 기록하지
+않은 내용 변경이나 사라진 발생분이 있으면 거절한다. Web은 기록 실패 시 cut을
+호출하지 않는다. Web의 별도 이벤트 기본 동작 정책은 이 프로파일을 확장하지 않는다.
+
+paste는 길이와 상대 위치를 보존하고 새 ID를 부여한다. 외부 문서의 calendarId를
+자동으로 다른 calendar로 치환하지 않는다. 명시적 재배치가 필요하면 기존 Editing API로
+목적지를 지정한다.
+
+```ts
+import { createCalendarEditor } from "@interactive-os/json-document-editing";
+
+const destination = createCalendarEditor(destinationDocument);
+const result = destination.paste(clipboard, "2026-08-02T12:00", { calendarId: "personal" });
+if (!result.ok) showError(result.code);
+```
+
+timezone/DST 변환, 서버 저장·동기화의 revision/충돌/재시도, AI command wire,
+외부 calendar connector, recurrence의 범용 RRULE 호환, 프로파일 버전 협상과
+독립 구현 conformance는 **TBD**다. 현재 앱에서 검증한 로컬 계약과 구분한다.
+
+Usage는 [Calendar](/demo/calendar), public API는 [Editing API](/docs/api/editing)와
+[Calendar Hands API](/docs/api/calendar)에 있다. Usage Source는 Editing의 validation,
+event/series plan, selection move, projection과 Calendar Hands의 입력 연결까지 추적한다.
diff --git a/packages/json-document-editing/package.json b/packages/json-document-editing/package.json
index 85d2cf62..7a9a86b7 100644
--- a/packages/json-document-editing/package.json
+++ b/packages/json-document-editing/package.json
@@ -17,7 +17,7 @@
     "provenance": true,
     "tag": "next"
   },
-  "files": ["dist", "!dist/.tsbuildinfo", "README.md", "LICENSE"],
+  "files": ["dist", "!dist/.tsbuildinfo", "README.md", "docs/calendar-profile.md", "LICENSE"],
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
diff --git a/packages/json-document-editing/src/calendar-allday-pointer.ts b/packages/json-document-editing/src/calendar-allday-pointer.ts
index 9aa14104..539ff3b6 100644
--- a/packages/json-document-editing/src/calendar-allday-pointer.ts
+++ b/packages/json-document-editing/src/calendar-allday-pointer.ts
@@ -1,5 +1,5 @@
 import type { CalendarEvent, CalendarIntent } from "./calendar.js";
-import { calendarEventRecurrence } from "./calendar-occurrence.js";
+import { calendarEventRecurrence, resolveCalendarOccurrence } from "./calendar-occurrence.js";
 import { bindCalendarMonthIntent } from "./calendar-month-pointer.js";
 import { addCalendarDate, calendarAllDaySpan, calendarDaysBetween, parseCalendarDate } from "./calendar-validation.js";
 
@@ -75,12 +75,12 @@ export function bindCalendarAllDayIntent(
   if (intent.type !== "event.resize") return intent;
   if (event === undefined || calendarEventRecurrence(event) === null) return intent;
   const start = occurrenceStart ?? event.start;
-  if (scope === "all") return intent;
+  const end = resolveCalendarOccurrence([event], { eventId: event.id, occurrenceStart: start })?.end;
   return {
     type: "occurrence.edit",
     eventId: intent.eventId,
     occurrenceStart: start,
     scope,
-    ...(intent.edge === "start" ? { start: intent.instant } : { end: intent.instant }),
+    ...(intent.edge === "start" ? { start: intent.instant, ...(end === undefined ? {} : { end }) } : { end: intent.instant }),
   };
 }
diff --git a/packages/json-document-editing/src/calendar-event-plan.ts b/packages/json-document-editing/src/calendar-event-plan.ts
new file mode 100644
index 00000000..497aca32
--- /dev/null
+++ b/packages/json-document-editing/src/calendar-event-plan.ts
@@ -0,0 +1,159 @@
+import { buildPointer, type JSONPatchOperation } from "@interactive-os/json-document";
+import type { CalendarEvent, CalendarIntent, CalendarOccurrencePoint } from "./calendar.js";
+import { calendarEventExcludeDates, calendarEventRecurrence, resolveCalendarOccurrence } from "./calendar-occurrence.js";
+import {
+  addCalendarDate, calendarAllDaySpan, calendarDatePart, calendarDaysBetween,
+  calendarEventIntervalAt, calendarMinutesBetween, formatCalendarInstant,
+  parseCalendarDate, parseCalendarInstant, validateCalendarEvent,
+} from "./calendar-validation.js";
+
+type CalendarEventIntent = Extract<CalendarIntent, { type:
+  "event.create" | "event.update" | "event.move" | "event.move-day" | "event.resize" | "occurrence.edit"
+}>;
+
+type CalendarEventPlan = {
+  readonly ok: true;
+  readonly events: ReadonlyArray<CalendarEvent>;
+  readonly operations: ReadonlyArray<JSONPatchOperation>;
+  readonly selected: CalendarOccurrencePoint;
+} | { readonly ok: false; readonly code: string; readonly reason?: string };
+
+/** Calendar's single event/series semantics, shared by commit, preview and group moves. */
+export function planCalendarEventEdit(
+  events: ReadonlyArray<CalendarEvent>,
+  intent: CalendarEventIntent,
+  options: { readonly allocateId: () => string; readonly calendarIds?: ReadonlySet<string>; readonly defaultCalendarId?: string },
+): CalendarEventPlan {
+  const index = intent.type === "event.create" ? -1 : events.findIndex((event) => event.id === intent.eventId);
+  const event = events[index];
+
+  function replace(next: CalendarEvent, selectedStart = next.start, fields?: ReadonlyArray<"start" | "end">): CalendarEventPlan {
+    const validation = validateCalendarEvent(next, options.calendarIds);
+    if (!validation.ok) return validation;
+    return {
+      ok: true,
+      events: events.map((item, position) => position === index ? next : item),
+      operations: fields === undefined
+        ? [{ op: "replace", path: buildPointer(["events", index]), value: next }]
+        : fields.map((field) => ({ op: "replace", path: buildPointer(["events", index, field]), value: next[field] })),
+      selected: { eventId: next.id, occurrenceStart: selectedStart },
+    };
+  }
+
+  function append(next: CalendarEvent, preceding: ReadonlyArray<JSONPatchOperation> = [], previous?: CalendarEvent): CalendarEventPlan {
+    const validation = validateCalendarEvent(next, options.calendarIds);
+    if (!validation.ok) return validation;
+    if (previous !== undefined) {
+      const previousValidation = validateCalendarEvent(previous, options.calendarIds);
+      if (!previousValidation.ok) return previousValidation;
+    }
+    // Detached records own their JSON subtrees, including extension metadata.
+    const appended = JSON.parse(JSON.stringify(next)) as CalendarEvent;
+    return {
+      ok: true,
+      events: [...events.map((item, position) => position === index && previous !== undefined ? previous : item), appended],
+      operations: [...preceding, { op: "add", path: `/events/${events.length}`, value: appended }],
+      selected: { eventId: next.id, occurrenceStart: next.start },
+    };
+  }
+
+  if (intent.type === "event.create") {
+    const candidate: CalendarEvent = {
+      id: "pending", title: intent.title ?? "Event", start: intent.start, end: intent.end,
+      allDay: intent.allDay ?? false, calendarId: intent.calendarId ?? options.defaultCalendarId ?? "",
+      recurrence: intent.recurrence ?? null, excludeDates: [],
+    };
+    const validation = validateCalendarEvent(candidate, options.calendarIds);
+    if (!validation.ok) return validation;
+    return append({ ...candidate, id: options.allocateId() });
+  }
+  if (event === undefined) return failure("selection.event-not-found");
+  if (intent.type === "event.resize") {
+    if (intent.edge !== "start" && intent.edge !== "end") return failure("event.invalid-edge");
+    return replace({ ...event, [intent.edge]: intent.instant }, intent.edge === "start" ? intent.instant : event.start, [intent.edge]);
+  }
+  if (intent.type === "event.move" || intent.type === "event.move-day") {
+    if (intent.type === "event.move" && event.allDay) return failure("event.all-day-move");
+    if (intent.type === "event.move-day" && parseCalendarDate(intent.day) === null) return failure("event.invalid-day");
+    const start = intent.type === "event.move" ? intent.start
+      : event.allDay ? intent.day : `${intent.day}T${event.start.slice(11)}`;
+    const interval = calendarEventIntervalAt(event, start);
+    return interval === null ? failure("event.invalid-instant") : replace({ ...event, ...interval }, start, ["start", "end"]);
+  }
+  if (intent.type === "event.update") {
+    let start = intent.start ?? event.start;
+    let end = intent.end ?? event.end;
+    if (intent.allDay === true && !event.allDay) {
+      start = calendarDatePart(event.start);
+      end = calendarAllDaySpan(start, start)?.end ?? start;
+    } else if (intent.allDay === false && event.allDay) {
+      start = `${calendarDatePart(event.start)}T09:00`;
+      end = `${calendarDatePart(event.start)}T10:00`;
+    } else if (intent.start !== undefined && intent.end === undefined) {
+      const interval = calendarEventIntervalAt(event, intent.start);
+      if (interval === null) return failure("event.invalid-instant");
+      ({ start, end } = interval);
+    }
+    return replace({ ...event, start, end, allDay: intent.allDay ?? event.allDay,
+      title: intent.title ?? event.title, calendarId: intent.calendarId ?? event.calendarId,
+      recurrence: intent.recurrence === undefined ? event.recurrence : intent.recurrence });
+  }
+
+  if (intent.scope !== "this" && intent.scope !== "this-and-following" && intent.scope !== "all") return failure("occurrence.invalid-scope");
+  const occurrence = resolveCalendarOccurrence(events, { eventId: event.id, occurrenceStart: intent.occurrenceStart });
+  if (occurrence === null) return failure("selection.stale-occurrence");
+  const interval = intent.end === undefined
+    ? calendarEventIntervalAt({ ...event, start: occurrence.start, end: occurrence.end }, intent.start ?? occurrence.start)
+    : { start: intent.start ?? occurrence.start, end: intent.end };
+  if (interval === null) return failure("event.invalid-instant");
+  const next = { ...event, ...interval, title: intent.title ?? event.title };
+  const validation = validateCalendarEvent(next, options.calendarIds);
+  if (!validation.ok) return validation;
+  const recurrence = calendarEventRecurrence(event);
+  if (recurrence === null) return replace(next);
+
+  if (intent.scope === "all") {
+    const start = shiftValue(event.start, occurrence.start, interval.start);
+    const end = shiftValue(event.end, occurrence.end, interval.end);
+    if (start === null || end === null) return failure("event.invalid-instant");
+    const shifted = shiftRecurrence(event, occurrence.start, interval.start);
+    const plan = replace({ ...next, start, end, ...shifted }, interval.start);
+    if (!plan.ok) return plan;
+    return resolveCalendarOccurrence(plan.events, plan.selected)?.end === interval.end
+      ? plan : failure("selection.unrepresentable-series-move");
+  }
+  const day = calendarDatePart(occurrence.start);
+  const id = options.allocateId();
+  if (intent.scope === "this") {
+    const excludeDates = [...new Set([...calendarEventExcludeDates(event), day])];
+    return append({ ...next, id, recurrence: null, excludeDates: [] }, [
+      { op: "add", path: buildPointer(["events", index, "excludeDates"]), value: excludeDates },
+    ], { ...event, excludeDates });
+  }
+  const previous = { ...event, recurrence: { ...recurrence, until: addCalendarDate(day, -1)! } };
+  const shifted = shiftRecurrence({ ...event, excludeDates: calendarEventExcludeDates(event).filter((date) => date >= day) }, occurrence.start, interval.start);
+  return append({ ...next, id, ...shifted }, [
+    { op: "replace", path: buildPointer(["events", index, "recurrence"]), value: previous.recurrence },
+  ], previous);
+}
+
+function shiftValue(value: string, origin: string, next: string): string | null {
+  if (value.length === 10) {
+    const from = parseCalendarDate(origin), to = parseCalendarDate(next);
+    return from === null || to === null ? null : addCalendarDate(value, calendarDaysBetween(from, to));
+  }
+  const start = parseCalendarInstant(value), from = parseCalendarInstant(origin), to = parseCalendarInstant(next);
+  return start === null || from === null || to === null ? null
+    : formatCalendarInstant(start.add({ minutes: calendarMinutesBetween(from, to) }));
+}
+
+function shiftRecurrence(event: CalendarEvent, origin: string, next: string): Pick<CalendarEvent, "recurrence" | "excludeDates"> {
+  const recurrence = calendarEventRecurrence(event)!;
+  const delta = calendarDaysBetween(parseCalendarDate(calendarDatePart(origin))!, parseCalendarDate(calendarDatePart(next))!);
+  return {
+    recurrence: { ...recurrence, until: recurrence.until === "" ? "" : addCalendarDate(recurrence.until, delta)! },
+    excludeDates: calendarEventExcludeDates(event).map((date) => addCalendarDate(date, delta)!),
+  };
+}
+
+function failure(code: string): CalendarEventPlan { return { ok: false, code }; }
diff --git a/packages/json-document-editing/src/calendar-month-pointer.ts b/packages/json-document-editing/src/calendar-month-pointer.ts
index 2dbb5902..2e35633d 100644
--- a/packages/json-document-editing/src/calendar-month-pointer.ts
+++ b/packages/json-document-editing/src/calendar-month-pointer.ts
@@ -48,15 +48,6 @@ export function bindCalendarMonthIntent(
   if (intent.type !== "event.move-day") return intent;
   if (event === undefined || calendarEventRecurrence(event) === null) return intent;
   const start = occurrenceStart ?? event.start;
-  const occDay = calendarDatePart(start);
-  const origin = parseCalendarDate(occDay);
-  const next = parseCalendarDate(intent.day);
-  if (origin === null || next === null) return intent;
-  if (scope === "all") {
-    const day = addCalendarDate(calendarDatePart(event.start), calendarDaysBetween(origin, next));
-    if (day === null) return intent;
-    return { type: "event.move-day", eventId: intent.eventId, day };
-  }
   return {
     type: "occurrence.edit",
     eventId: intent.eventId,
diff --git a/packages/json-document-editing/src/calendar-occurrence.ts b/packages/json-document-editing/src/calendar-occurrence.ts
index 80bb8d5d..363f83ca 100644
--- a/packages/json-document-editing/src/calendar-occurrence.ts
+++ b/packages/json-document-editing/src/calendar-occurrence.ts
@@ -1,12 +1,16 @@
 import { Temporal } from "@js-temporal/polyfill";
-import type { CalendarEvent, CalendarRecurrence } from "./calendar.js";
+import type { CalendarEvent, CalendarOccurrencePoint, CalendarOccurrenceSelection, CalendarRecurrence } from "./calendar.js";
 import {
   addCalendarDate,
   calendarDatePart,
   calendarEventBounds,
+  calendarEventIntervalAt,
+  calendarDaysBetween,
+  formatCalendarDate,
+  formatCalendarInstant,
   isCalendarAllDay,
+  isCalendarRecurrence,
   parseCalendarDate,
-  parseCalendarInstant,
 } from "./calendar-validation.js";
 
 export type CalendarOccurrence = {
@@ -16,17 +20,7 @@ export type CalendarOccurrence = {
 };
 
 export function calendarEventRecurrence(event: CalendarEvent): CalendarRecurrence | null {
-  const value = event.recurrence;
-  if (value === null || typeof value !== "object" || Array.isArray(value)) return null;
-  const freq = value.freq;
-  const interval = value.interval;
-  if (
-    (freq !== "daily" && freq !== "weekly" && freq !== "monthly" && freq !== "yearly")
-    || typeof interval !== "number"
-    || interval < 1
-  ) return null;
-  const until = typeof value.until === "string" ? value.until : "";
-  return { freq, interval, until };
+  return isCalendarRecurrence(event.recurrence) ? event.recurrence : null;
 }
 
 export function calendarRecurrenceWithFrequency(
@@ -82,8 +76,21 @@ export function projectCalendarOccurrences(
     }
     const excluded = new Set(calendarEventExcludeDates(event));
     const until = recurrence.until === "" ? null : parseCalendarDate(recurrence.until);
-    for (let index = 0; index < 400; index += 1) {
-      const shifted = shiftOccurrence(event, recurrence.freq, recurrence.interval * index);
+    const end = parseCalendarDate(calendarDatePart(event.end));
+    if (end === null) continue;
+    // Seek by the interval end, not start, so long occurrences overlapping the
+    // window are retained. One preceding period covers constrained month/year ends.
+    const distance = recurrence.freq === "monthly" ? (from.year - end.year) * 12 + from.month - end.month
+      : recurrence.freq === "yearly" ? from.year - end.year
+      : calendarDaysBetween(end, from) / (recurrence.freq === "weekly" ? 7 : 1);
+    const first = Math.max(0, Math.floor(distance / recurrence.interval) - 1);
+    for (let index = first; ; index += 1) {
+      let shifted: ReturnType<typeof shiftOccurrence>;
+      try { shifted = shiftOccurrence(event, recurrence.freq, recurrence.interval * index); }
+      catch (error) {
+        if (!(error instanceof RangeError)) throw error;
+        break; // Beyond the finite Temporal date domain, not a truncated result.
+      }
       if (shifted === null) break;
       const bounds = calendarEventBounds({ ...event, start: shifted.start, end: shifted.end });
       if (bounds === null) break;
@@ -97,37 +104,31 @@ export function projectCalendarOccurrences(
   return occurrences;
 }
 
+/** Resolve against the current recurrence/exclusion rules, including off-screen occurrences. */
+export function resolveCalendarOccurrence(
+  events: ReadonlyArray<CalendarEvent>,
+  point: CalendarOccurrencePoint,
+): CalendarOccurrenceSelection | null {
+  const event = events.find((candidate) => candidate.id === point.eventId);
+  if (event === undefined || typeof point.occurrenceStart !== "string") return null;
+  const day = calendarDatePart(point.occurrenceStart);
+  const next = addCalendarDate(day, 1);
+  if (next === null) return null;
+  const occurrence = projectCalendarOccurrences([event], day, next).find((candidate) => candidate.start === point.occurrenceStart);
+  return occurrence === undefined ? null : { eventId: event.id, start: occurrence.start, end: occurrence.end };
+}
+
 function shiftOccurrence(
   event: CalendarEvent,
   freq: CalendarRecurrence["freq"],
   steps: number,
 ): { readonly start: string; readonly end: string } | null {
   if (steps === 0) return { start: event.start, end: event.end };
-  if (isCalendarAllDay(event)) {
-    const start = shiftDate(event.start, freq, steps);
-    const end = shiftDate(event.end, freq, steps);
-    if (start === null || end === null) return null;
-    return { start, end };
-  }
-  const start = shiftInstant(event.start, freq, steps);
-  const end = shiftInstant(event.end, freq, steps);
-  if (start === null || end === null) return null;
-  return { start, end };
-}
-
-function shiftDate(value: string, freq: CalendarRecurrence["freq"], steps: number): string | null {
-  if (freq === "daily") return addCalendarDate(value, steps);
-  if (freq === "weekly") return addCalendarDate(value, steps * 7);
-  if (parseCalendarDate(value) === null) return null;
-  const duration = freq === "monthly" ? { months: steps } : { years: steps };
-  return Temporal.PlainDate.from(value).add(duration, { overflow: "constrain" }).toString();
-}
-
-function shiftInstant(value: string, freq: CalendarRecurrence["freq"], steps: number): string | null {
-  const dateTime = parseCalendarInstant(value);
-  if (dateTime === null) return null;
-  if (freq === "daily") return dateTime.add({ days: steps }).toString({ smallestUnit: "minute" });
-  if (freq === "weekly") return dateTime.add({ weeks: steps }).toString({ smallestUnit: "minute" });
-  const duration = freq === "monthly" ? { months: steps } : { years: steps };
-  return Temporal.PlainDateTime.from(value).add(duration, { overflow: "constrain" }).toString({ smallestUnit: "minute" });
+  const bounds = calendarEventBounds(event);
+  if (bounds === null) return null;
+  const duration = freq === "daily" ? { days: steps } : freq === "weekly" ? { weeks: steps }
+    : freq === "monthly" ? { months: steps } : { years: steps };
+  const shifted = bounds.from.add(duration, { overflow: "constrain" });
+  const start = isCalendarAllDay(event) ? formatCalendarDate(shifted.toPlainDate()) : formatCalendarInstant(shifted);
+  return calendarEventIntervalAt(event, start);
 }
diff --git a/packages/json-document-editing/src/calendar-preview.ts b/packages/json-document-editing/src/calendar-preview.ts
index 6f414b7e..f7dacf72 100644
--- a/packages/json-document-editing/src/calendar-preview.ts
+++ b/packages/json-document-editing/src/calendar-preview.ts
@@ -1,94 +1,17 @@
-import type { CalendarEvent } from "./calendar.js";
-import { calendarEventExcludeDates, calendarEventRecurrence } from "./calendar-occurrence.js";
-import {
-  bindCalendarAllDayIntent,
-  interpretCalendarAllDayPointer,
-  type CalendarAllDayPointerRelease,
-} from "./calendar-allday-pointer.js";
-import {
-  bindCalendarMonthIntent,
-  interpretCalendarMonthPointer,
-  type CalendarMonthPointerRelease,
-} from "./calendar-month-pointer.js";
-import {
-  bindCalendarTimeGridIntent,
-  interpretCalendarTimeGridPointer,
-  type CalendarTimeGridPointerIntent,
-  type CalendarTimeGridPointerRelease,
-} from "./calendar-time-grid-pointer.js";
-import {
-  addCalendarDate,
-  calendarDatePart,
-  calendarDaysBetween,
-  calendarMinutesBetween,
-  formatCalendarDate,
-  formatCalendarInstant,
-  isCalendarAllDay,
-  parseCalendarDate,
-  parseCalendarInstant,
-} from "./calendar-validation.js";
+import type { CalendarEvent, CalendarIntent } from "./calendar.js";
+import { planCalendarEventEdit } from "./calendar-event-plan.js";
+import { createEditingIdAllocator } from "./identity.js";
+import { bindCalendarAllDayIntent, interpretCalendarAllDayPointer, type CalendarAllDayPointerRelease } from "./calendar-allday-pointer.js";
+import { bindCalendarMonthIntent, interpretCalendarMonthPointer, type CalendarMonthPointerRelease } from "./calendar-month-pointer.js";
+import { bindCalendarTimeGridIntent, interpretCalendarTimeGridPointer, type CalendarTimeGridPointerRelease } from "./calendar-time-grid-pointer.js";
 
 export function previewCalendarAllDay(
   events: ReadonlyArray<CalendarEvent>,
   release: CalendarAllDayPointerRelease,
   scope: "this" | "this-and-following" | "all" = "this",
 ): ReadonlyArray<CalendarEvent> {
-  const intent = interpretCalendarAllDayPointer(release);
-  if (intent === null || intent.type === "selection.set" || intent.type === "selection.clear") return events;
-  if (intent.type === "event.create") {
-    return [...events, {
-      id: "preview",
-      title: "Event",
-      start: intent.start,
-      end: intent.end,
-      allDay: true,
-      calendarId: "",
-      recurrence: null,
-      excludeDates: [],
-    }];
-  }
-  const event = events.find((item) => item.id === intent.eventId);
-  const bound = bindCalendarAllDayIntent(intent, event, release.originEventStart, scope) ?? intent;
-  if (bound.type === "occurrence.edit" && event !== undefined && release.originEventStart !== null) {
-    const excluded = calendarDatePart(release.originEventStart);
-    const start = bound.start ?? release.originEventStart;
-    const end = bound.end ?? event.end;
-    return [
-      ...events.map((item) => item.id === event.id
-        ? { ...item, excludeDates: [...calendarEventExcludeDates(item), excluded] }
-        : item),
-      {
-        ...event,
-        id: "preview",
-        start,
-        end,
-        recurrence: bound.scope === "this" ? null : event.recurrence,
-        excludeDates: [],
-      },
-    ];
-  }
-  if (intent.type === "event.move-day") {
-    return events.map((item) => {
-      if (item.id !== intent.eventId || !isCalendarAllDay(item)) return item;
-      const from = parseCalendarDate(item.start);
-      const to = parseCalendarDate(item.end);
-      const nextDay = parseCalendarDate(intent.day);
-      if (from === null || to === null || nextDay === null) return item;
-      const delta = calendarDaysBetween(from, nextDay);
-      return {
-        ...item,
-        start: formatCalendarDate(from.add({ days: delta })),
-        end: formatCalendarDate(to.add({ days: delta })),
-      };
-    });
-  }
-  return events.map((item) => {
-    if (item.id !== intent.eventId) return item;
-    const start = intent.edge === "start" ? intent.instant : item.start;
-    const end = intent.edge === "end" ? intent.instant : item.end;
-    if (start >= end) return item;
-    return { ...item, start, end };
-  });
+  const event = events.find((item) => item.id === release.originEventId);
+  return preview(events, bindCalendarAllDayIntent(interpretCalendarAllDayPointer(release), event, release.originEventStart, scope));
 }
 
 export function previewCalendarTimeGrid(
@@ -96,50 +19,8 @@ export function previewCalendarTimeGrid(
   release: CalendarTimeGridPointerRelease,
   scope: "this" | "this-and-following" | "all" = "this",
 ): ReadonlyArray<CalendarEvent> {
-  const intent = interpretCalendarTimeGridPointer(release);
-  if (intent === null || intent.type === "selection.set" || intent.type === "selection.clear") return events;
-  if (intent.type === "event.create") {
-    return [...events, {
-      id: "preview",
-      title: "Event",
-      start: intent.start,
-      end: intent.end,
-      allDay: false,
-      calendarId: "",
-      recurrence: null,
-      excludeDates: [],
-    }];
-  }
-  const event = events.find((item) => item.id === intent.eventId);
-  const bound = bindCalendarTimeGridIntent(intent, event, release.originEventStart, scope) ?? intent;
-  if (
-    bound.type === "occurrence.edit"
-    && event !== undefined
-    && release.originEventStart !== null
-  ) {
-    if (bound.scope === "this-and-following") {
-      return previewFollowingOccurrences(events, event, release.originEventStart, intent);
-    }
-    return previewRecurringOccurrence(events, event, release.originEventStart, intent);
-  }
-  if (bound.type === "event.move") {
-    return events.map((item) => {
-      if (item.id !== bound.eventId || isCalendarAllDay(item)) return item;
-      const from = parseCalendarInstant(item.start);
-      const to = parseCalendarInstant(item.end);
-      const nextStart = parseCalendarInstant(bound.start);
-      if (from === null || to === null || nextStart === null) return item;
-      return { ...item, start: bound.start, end: formatCalendarInstant(nextStart.add({ minutes: calendarMinutesBetween(from, to) })) };
-    });
-  }
-  if (bound.type !== "event.resize") return events;
-  return events.map((item) => {
-    if (item.id !== bound.eventId) return item;
-    const start = bound.edge === "start" ? bound.instant : item.start;
-    const end = bound.edge === "end" ? bound.instant : item.end;
-    if (start >= end) return item;
-    return { ...item, start, end };
-  });
+  const event = events.find((item) => item.id === release.originEventId);
+  return preview(events, bindCalendarTimeGridIntent(interpretCalendarTimeGridPointer(release), event, release.originEventStart, scope));
 }
 
 export function previewCalendarMonth(
@@ -147,148 +28,16 @@ export function previewCalendarMonth(
   release: CalendarMonthPointerRelease,
   scope: "this" | "this-and-following" | "all" = "this",
 ): ReadonlyArray<CalendarEvent> {
-  const intent = interpretCalendarMonthPointer(release);
-  if (intent === null || intent.type === "selection.set" || intent.type === "selection.clear") return events;
-  if (intent.type === "event.create") {
-    return [...events, {
-      id: "preview",
-      title: "Event",
-      start: intent.start,
-      end: intent.end,
-      allDay: true,
-      calendarId: "",
-      recurrence: null,
-      excludeDates: [],
-    }];
-  }
-  const event = events.find((item) => item.id === intent.eventId);
-  const bound = bindCalendarMonthIntent(intent, event, release.originEventStart ?? null, scope) ?? intent;
-  if (bound.type === "occurrence.edit" && event !== undefined && (release.originEventStart ?? null) !== null) {
-    const occurrenceStart = release.originEventStart ?? event.start;
-    const excluded = calendarDatePart(occurrenceStart);
-    const start = bound.start ?? occurrenceStart;
-    const end = bound.end ?? event.end;
-    return [
-      ...events.map((item) => item.id === event.id
-        ? { ...item, excludeDates: [...calendarEventExcludeDates(item), excluded] }
-        : item),
-      {
-        ...event,
-        id: "preview",
-        start,
-        end,
-        recurrence: bound.scope === "this" ? null : event.recurrence,
-        excludeDates: [],
-      },
-    ];
-  }
-  if (intent.type !== "event.move-day") return events;
-  return events.map((item) => {
-    if (item.id !== intent.eventId) return item;
-    if (isCalendarAllDay(item)) {
-      const from = parseCalendarDate(item.start);
-      const to = parseCalendarDate(item.end);
-      const nextDay = parseCalendarDate(intent.day);
-      if (from === null || to === null || nextDay === null) return item;
-      const delta = calendarDaysBetween(from, nextDay);
-      return {
-        ...item,
-        start: formatCalendarDate(from.add({ days: delta })),
-        end: formatCalendarDate(to.add({ days: delta })),
-      };
-    }
-    const from = parseCalendarInstant(item.start);
-    const to = parseCalendarInstant(item.end);
-    const currentDay = parseCalendarInstant(`${calendarDatePart(item.start)}T00:00`);
-    const nextDay = parseCalendarInstant(`${intent.day}T00:00`);
-    if (from === null || to === null || currentDay === null || nextDay === null) return item;
-    const delta = calendarMinutesBetween(currentDay, nextDay);
-    return {
-      ...item,
-      start: formatCalendarInstant(from.add({ minutes: delta })),
-      end: formatCalendarInstant(to.add({ minutes: delta })),
-    };
-  });
-}
-
-function previewFollowingOccurrences(
-  events: ReadonlyArray<CalendarEvent>,
-  event: CalendarEvent,
-  occurrenceStart: string,
-  intent: Extract<CalendarTimeGridPointerIntent, { type: "event.move" } | { type: "event.resize" }>,
-): ReadonlyArray<CalendarEvent> {
-  const recurrence = calendarEventRecurrence(event);
-  const from = parseCalendarInstant(event.start);
-  const to = parseCalendarInstant(event.end);
-  const occStart = parseCalendarInstant(occurrenceStart);
-  if (recurrence === null || from === null || to === null || occStart === null) return events;
-  const duration = calendarMinutesBetween(from, to);
-  let start = occurrenceStart;
-  let end = formatCalendarInstant(occStart.add({ minutes: duration }));
-  if (intent.type === "event.move") {
-    const nextStart = parseCalendarInstant(intent.start);
-    if (nextStart === null) return events;
-    start = intent.start;
-    end = formatCalendarInstant(nextStart.add({ minutes: duration }));
-  } else if (intent.edge === "start") {
-    start = intent.instant;
-  } else {
-    end = intent.instant;
-  }
-  if (start >= end) return events;
-  const until = addCalendarDate(calendarDatePart(occurrenceStart), -1);
-  if (until === null) return events;
-  return [
-    ...events.map((item) => item.id === event.id
-      ? { ...item, recurrence: { ...recurrence, until } }
-      : item),
-    {
-      ...event,
-      id: "preview",
-      start,
-      end,
-      recurrence: { ...recurrence, until: "" },
-      excludeDates: [],
-    },
-  ];
+  const event = events.find((item) => item.id === release.originEventId);
+  return preview(events, bindCalendarMonthIntent(interpretCalendarMonthPointer(release), event, release.originEventStart ?? null, scope));
 }
 
-function previewRecurringOccurrence(
-  events: ReadonlyArray<CalendarEvent>,
-  event: CalendarEvent,
-  occurrenceStart: string,
-  intent: Extract<CalendarTimeGridPointerIntent, { type: "event.move" } | { type: "event.resize" }>,
-): ReadonlyArray<CalendarEvent> {
-  const from = parseCalendarInstant(event.start);
-  const to = parseCalendarInstant(event.end);
-  const occStart = parseCalendarInstant(occurrenceStart);
-  if (from === null || to === null || occStart === null) return events;
-  const duration = calendarMinutesBetween(from, to);
-  let start = occurrenceStart;
-  let end = formatCalendarInstant(occStart.add({ minutes: duration }));
-  if (intent.type === "event.move") {
-    const nextStart = parseCalendarInstant(intent.start);
-    if (nextStart === null) return events;
-    start = intent.start;
-    end = formatCalendarInstant(nextStart.add({ minutes: duration }));
-  } else if (intent.edge === "start") {
-    start = intent.instant;
-  } else {
-    end = intent.instant;
-  }
-  if (start >= end) return events;
-  const excluded = calendarDatePart(occurrenceStart);
-  return [
-    ...events.map((item) => item.id === event.id
-      ? { ...item, excludeDates: [...calendarEventExcludeDates(item), excluded] }
-      : item),
-    {
-      ...event,
-      id: "preview",
-      start,
-      end,
-      recurrence: null,
-      excludeDates: [],
-    },
-  ];
+function preview(events: ReadonlyArray<CalendarEvent>, intent: CalendarIntent | null): ReadonlyArray<CalendarEvent> {
+  if (intent === null || !(intent.type === "event.create" || intent.type === "event.update" || intent.type === "event.move"
+    || intent.type === "event.move-day" || intent.type === "event.resize" || intent.type === "occurrence.edit")) return events;
+  let sequence = 0;
+  const plan = planCalendarEventEdit(events, intent, {
+    allocateId: createEditingIdAllocator(events.map((event) => event.id), () => sequence++ === 0 ? "preview" : `preview-${sequence}`, "calendar preview"),
+  });
+  return plan.ok ? plan.events : events;
 }
diff --git a/packages/json-document-editing/src/calendar-selection-move.ts b/packages/json-document-editing/src/calendar-selection-move.ts
index 00bfb5ff..35d40b00 100644
--- a/packages/json-document-editing/src/calendar-selection-move.ts
+++ b/packages/json-document-editing/src/calendar-selection-move.ts
@@ -1,4 +1,6 @@
-import { calendarEventExcludeDates, calendarEventRecurrence } from "./calendar-occurrence.js";
+import { calendarEventRecurrence, resolveCalendarOccurrence } from "./calendar-occurrence.js";
+import { planCalendarEventEdit } from "./calendar-event-plan.js";
+import { createEditingIdAllocator } from "./identity.js";
 import type {
   CalendarEvent,
   CalendarOccurrencePoint,
@@ -29,7 +31,7 @@ export type CalendarSelectionMovePlan =
     }
   | { readonly ok: false; readonly code: string };
 
-/** Plans one atomic temporal translation for a materialized occurrence selection. */
+/** Plans one atomic temporal translation; captured intervals are preconditions, not current truth. */
 export function planCalendarSelectionMove(
   events: ReadonlyArray<CalendarEvent>,
   occurrences: ReadonlyArray<CalendarOccurrenceSelection>,
@@ -41,75 +43,61 @@ export function planCalendarSelectionMove(
     readonly primary?: CalendarOccurrencePoint;
   } = {},
 ): CalendarSelectionMovePlan {
-  const anchorOccurrence = occurrences.find((item) => (
-    item.eventId === anchor.eventId && item.start === anchor.occurrenceStart
-  ));
-  if (anchorOccurrence === undefined || occurrences.length === 0) {
-    return { ok: false, code: "selection.drag-source-not-found" };
+  const matches = (item: CalendarOccurrenceSelection, point: CalendarOccurrencePoint) =>
+    item.eventId === point.eventId && item.start === point.occurrenceStart;
+  const anchorOccurrence = occurrences.find((item) => matches(item, anchor));
+  const primaryIndex = occurrences.findIndex((item) => matches(item, options.primary ?? anchor));
+  if (anchorOccurrence === undefined || primaryIndex < 0) return { ok: false, code: "selection.drag-source-not-found" };
+  const scope = options.scope ?? "this";
+  if (scope !== "this" && scope !== "this-and-following" && scope !== "all") return { ok: false, code: "occurrence.invalid-scope" };
+  const seen = new Set<string>();
+  for (const occurrence of occurrences) {
+    const key = JSON.stringify([occurrence.eventId, occurrence.start]);
+    if (seen.has(key)) return { ok: false, code: "selection.duplicate-occurrence" };
+    seen.add(key);
+    const current = resolveCalendarOccurrence(events, { eventId: occurrence.eventId, occurrenceStart: occurrence.start });
+    if (current === null || current.end !== occurrence.end) return { ok: false, code: "selection.stale-occurrence" };
   }
   const delta = resolveDelta(anchorOccurrence.start, target);
   if (delta === null) return { ok: false, code: "selection.invalid-drop-target" };
-  if (target.type === "instant" && occurrences.some((item) => {
-    const event = events.find((candidate) => candidate.id === item.eventId);
-    return event === undefined || isCalendarAllDay(event);
-  })) return { ok: false, code: "selection.incompatible-drop-target" };
+  if (target.type === "instant" && occurrences.some((item) => (
+    isCalendarAllDay(events.find((event) => event.id === item.eventId)!)
+  ))) return { ok: false, code: "selection.incompatible-drop-target" };
 
-  const next = [...events];
+  let next = events;
+  let sequence = 0;
+  const allocateId = createEditingIdAllocator(events.map((event) => event.id), options.createId ?? (() => `preview-${++sequence}`), "calendar event");
   const moved: CalendarOccurrenceSelection[] = [];
-  const exclusions = new Map<string, Set<string>>();
-  const scope = options.scope ?? "this";
-  const createId = options.createId ?? (() => `preview-${moved.length + 1}`);
-  const seenSeries = new Set<string>();
-
-  for (const occurrence of occurrences) {
-    const index = events.findIndex((event) => event.id === occurrence.eventId);
-    const event = events[index];
-    if (event === undefined) return { ok: false, code: "selection.event-not-found" };
+  const seriesIds = new Map<string, string>();
+  // Following starts at the earliest selected occurrence, independent of selection/primary order.
+  const ordered = occurrences.map((occurrence, index) => ({ occurrence, index }))
+    .sort((left, right) => left.occurrence.start.localeCompare(right.occurrence.start));
+  for (const { occurrence, index } of ordered) {
+    const event = events.find((item) => item.id === occurrence.eventId)!;
     const shifted = shiftInterval(occurrence.start, occurrence.end, delta);
     if (shifted === null) return { ok: false, code: "event.invalid-instant" };
-    const recurrence = calendarEventRecurrence(event);
-    if (recurrence === null) {
-      if (seenSeries.has(event.id)) return { ok: false, code: "selection.duplicate-event" };
-      seenSeries.add(event.id);
-      next[index] = { ...event, start: shifted.start, end: shifted.end };
-      moved.push({ eventId: event.id, ...shifted });
-      continue;
+    const recurring = calendarEventRecurrence(event) !== null;
+    let eventId = recurring && scope !== "this" ? seriesIds.get(event.id) : undefined;
+    if (eventId === undefined) {
+      const plan = planCalendarEventEdit(next, recurring ? {
+        type: "occurrence.edit", eventId: event.id, occurrenceStart: occurrence.start, scope, ...shifted,
+      } : { type: "event.update", eventId: event.id, ...shifted }, { allocateId });
+      if (!plan.ok) return plan;
+      next = plan.events;
+      eventId = plan.selected.eventId;
+      if (recurring && scope !== "this") seriesIds.set(event.id, eventId);
     }
-    if (scope !== "this") return { ok: false, code: "selection.recurring-group-scope-unsupported" };
-    const dates = exclusions.get(event.id) ?? new Set(calendarEventExcludeDates(event));
-    dates.add(calendarDatePart(occurrence.start));
-    exclusions.set(event.id, dates);
-    const detached: CalendarEvent = {
-      ...event,
-      id: uniqueId(next, createId),
-      start: shifted.start,
-      end: shifted.end,
-      recurrence: null,
-      excludeDates: [],
-    };
-    next.push(detached);
-    moved.push({ eventId: detached.id, ...shifted });
-  }
-  for (const [eventId, dates] of exclusions) {
-    const index = next.findIndex((event) => event.id === eventId);
-    next[index] = { ...next[index]!, excludeDates: [...dates] };
+    moved[index] = { eventId, ...shifted };
   }
-  const points = moved.map((item): CalendarOccurrencePoint => ({
-    eventId: item.eventId,
-    occurrenceStart: item.start,
-  }));
-  const primary = options.primary ?? anchor;
-  const primaryIndex = occurrences.findIndex((item) => (
-    item.eventId === primary.eventId && item.start === primary.occurrenceStart
-  ));
+  // A monthly/yearly re-anchor may not represent every translated point: fail atomically.
+  if (moved.some((item) => resolveCalendarOccurrence(next, {
+    eventId: item.eventId, occurrenceStart: item.start,
+  })?.end !== item.end)) return { ok: false, code: "selection.unrepresentable-series-move" };
+  const points = moved.map((item): CalendarOccurrencePoint => ({ eventId: item.eventId, occurrenceStart: item.start }));
   return {
-    ok: true,
-    events: next,
-    movedOccurrences: moved,
+    ok: true, events: next, movedOccurrences: moved,
     selectionAfter: {
-      kind: "range",
-      ranges: points.map((point) => ({ anchor: point, focus: point, points: [point] })),
-      primaryIndex: Math.max(0, primaryIndex),
+      kind: "range", ranges: points.map((point) => ({ anchor: point, focus: point, points: [point] })), primaryIndex,
     },
   };
 }
@@ -146,9 +134,3 @@ function shiftInterval(start: string, end: string, delta: Delta): { start: strin
     end: formatCalendarInstant(to.add({ minutes })),
   };
 }
-
-function uniqueId(events: ReadonlyArray<CalendarEvent>, createId: () => string): string {
-  let id = createId();
-  while (events.some((event) => event.id === id)) id = createId();
-  return id;
-}
diff --git a/packages/json-document-editing/src/calendar-time-grid-pointer.ts b/packages/json-document-editing/src/calendar-time-grid-pointer.ts
index ae9e3321..a91942a0 100644
--- a/packages/json-document-editing/src/calendar-time-grid-pointer.ts
+++ b/packages/json-document-editing/src/calendar-time-grid-pointer.ts
@@ -1,5 +1,5 @@
 import type { CalendarEvent, CalendarIntent } from "./calendar.js";
-import { calendarEventRecurrence } from "./calendar-occurrence.js";
+import { calendarEventRecurrence, resolveCalendarOccurrence } from "./calendar-occurrence.js";
 import { calendarDatePart, calendarMinutesBetween, calendarShiftInstant, parseCalendarInstant } from "./calendar-validation.js";
 
 export type CalendarTimeGridHandle = "body" | "start" | "end";
@@ -64,7 +64,6 @@ export function bindCalendarTimeGridIntent(
   if (intent.type !== "event.move" && intent.type !== "event.resize") return intent;
   if (event === undefined || calendarEventRecurrence(event) === null) return intent;
   const start = occurrenceStart ?? event.start;
-  if (scope === "all") return bindRecurringSeriesTimeGridIntent(intent, event, start);
   if (intent.type === "event.move") {
     return {
       type: "occurrence.edit",
@@ -75,11 +74,7 @@ export function bindCalendarTimeGridIntent(
     };
   }
   if (intent.edge === "start") {
-    const from = parseCalendarInstant(event.start);
-    const to = parseCalendarInstant(event.end);
-    const occurrenceEnd = from === null || to === null
-      ? null
-      : calendarShiftInstant(start, calendarMinutesBetween(from, to));
+    const occurrenceEnd = resolveCalendarOccurrence([event], { eventId: event.id, occurrenceStart: start })?.end ?? null;
     return {
       type: "occurrence.edit",
       eventId: intent.eventId,
@@ -98,35 +93,6 @@ export function bindCalendarTimeGridIntent(
   };
 }
 
-function bindRecurringSeriesTimeGridIntent(
-  intent: Extract<CalendarTimeGridPointerIntent, { type: "event.move" } | { type: "event.resize" }>,
-  event: CalendarEvent,
-  occurrenceStart: string,
-): CalendarIntent {
-  if (intent.type === "event.move") {
-    const origin = parseCalendarInstant(occurrenceStart);
-    const next = parseCalendarInstant(intent.start);
-    if (origin === null || next === null) return intent;
-    const start = calendarShiftInstant(event.start, calendarMinutesBetween(origin, next));
-    if (start === null) return intent;
-    return { type: "event.move", eventId: intent.eventId, start };
-  }
-  const from = parseCalendarInstant(event.start);
-  const to = parseCalendarInstant(event.end);
-  const occStart = parseCalendarInstant(occurrenceStart);
-  const instant = parseCalendarInstant(intent.instant);
-  if (from === null || to === null || occStart === null || instant === null) return intent;
-  if (intent.edge === "start") {
-    const start = calendarShiftInstant(event.start, calendarMinutesBetween(occStart, instant));
-    if (start === null) return intent;
-    return { type: "event.resize", eventId: intent.eventId, edge: "start", instant: start };
-  }
-  const occurrenceEnd = occStart.add({ minutes: calendarMinutesBetween(from, to) });
-  const end = calendarShiftInstant(event.end, calendarMinutesBetween(occurrenceEnd, instant));
-  if (end === null) return intent;
-  return { type: "event.resize", eventId: intent.eventId, edge: "end", instant: end };
-}
-
 function timePart(instant: string): string | null {
   if (parseCalendarInstant(instant) === null) return null;
   return instant.slice(11);
diff --git a/packages/json-document-editing/src/calendar-validation.ts b/packages/json-document-editing/src/calendar-validation.ts
index 4c910715..3d0da3a4 100644
--- a/packages/json-document-editing/src/calendar-validation.ts
+++ b/packages/json-document-editing/src/calendar-validation.ts
@@ -1,5 +1,5 @@
 import { Temporal } from "@js-temporal/polyfill";
-import type { CalendarCalendar, CalendarDocument, CalendarEvent, CalendarView } from "./calendar.js";
+import type { CalendarCalendar, CalendarDocument, CalendarEvent, CalendarRecurrence, CalendarView } from "./calendar.js";
 
 const DATE = /^(\d{4})-(\d{2})-(\d{2})$/;
 const DATETIME = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2})$/;
@@ -22,6 +22,7 @@ export function calendarDocumentEvents(document: CalendarDocument): ReadonlyArra
 }
 
 export function assertCalendarDocument(document: CalendarDocument): void {
+  if (!Array.isArray(document.events)) throw new TypeError("Calendar events must be an array.");
   const calendarIds = new Set<string>();
   for (const calendar of calendarDocumentCalendars(document)) {
     if (calendar.id.length === 0) throw new Error("Calendar ids must not be empty.");
@@ -33,24 +34,64 @@ export function assertCalendarDocument(document: CalendarDocument): void {
   }
   const ids = new Set<string>();
   for (const event of calendarDocumentEvents(document)) {
-    if (event.id.length === 0) throw new Error("Calendar event ids must not be empty.");
+    const result = validateCalendarEvent(event, calendarIds);
+    if (!result.ok) throw new TypeError(result.reason);
     if (ids.has(event.id)) throw new Error(`Calendar event id must be unique: ${JSON.stringify(event.id)}.`);
-    const calendarId = typeof event.calendarId === "string" ? event.calendarId : "";
-    if (calendarId.length > 0 && calendarIds.size > 0 && !calendarIds.has(calendarId)) {
-      throw new Error(`Calendar event must belong to a calendar: ${JSON.stringify(event.id)}.`);
-    }
-    if (isCalendarAllDay(event)) {
-      if (parseCalendarDate(event.start) === null || parseCalendarDate(event.end) === null) {
-        throw new Error(`All-day calendar events must use date strings: ${JSON.stringify(event.id)}.`);
-      }
-    } else if (parseCalendarInstant(event.start) === null || parseCalendarInstant(event.end) === null) {
-      throw new Error(`Calendar event times must be datetime-local strings: ${JSON.stringify(event.id)}.`);
-    }
-    if (event.start >= event.end) throw new Error(`Calendar event must end after it starts: ${JSON.stringify(event.id)}.`);
     ids.add(event.id);
   }
 }
 
+type CalendarValidationResult = { readonly ok: true } | {
+  readonly ok: false; readonly code: string; readonly reason: string;
+};
+
+/** One domain invariant shared by construction, edit planning and clipboard ingress. */
+export function validateCalendarEvent(value: unknown, calendarIds?: ReadonlySet<string>): CalendarValidationResult {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return { ok: false, code: "event.invalid", reason: "Calendar events must be objects." };
+  }
+  const event = value as Record<string, unknown>;
+  if (typeof event.id !== "string" || event.id.length === 0 || typeof event.title !== "string") {
+    return { ok: false, code: "event.invalid", reason: "Calendar events require a nonempty id and a string title." };
+  }
+  if (typeof event.start !== "string" || typeof event.end !== "string"
+    || (event.allDay !== undefined && typeof event.allDay !== "boolean")) {
+    return { ok: false, code: "event.invalid-instant", reason: "Calendar events require canonical temporal values." };
+  }
+  const parse = event.allDay === true ? parseCalendarDate : parseCalendarInstant;
+  if (parse(event.start) === null || parse(event.end) === null) {
+    return { ok: false, code: "event.invalid-instant", reason: event.allDay === true
+      ? `All-day calendar events must use date strings: ${JSON.stringify(event.id)}.`
+      : `Calendar event times must be datetime-local strings: ${JSON.stringify(event.id)}.` };
+  }
+  if (event.start >= event.end) {
+    return { ok: false, code: "event.invalid-interval", reason: `Calendar event must end after it starts: ${JSON.stringify(event.id)}.` };
+  }
+  if (event.calendarId !== undefined && typeof event.calendarId !== "string") {
+    return { ok: false, code: "calendar.not-found", reason: "Calendar references must be strings." };
+  }
+  if (typeof event.calendarId === "string" && event.calendarId.length > 0
+    && calendarIds !== undefined && calendarIds.size > 0 && !calendarIds.has(event.calendarId)) {
+    return { ok: false, code: "calendar.not-found", reason: `Calendar event must belong to a calendar: ${JSON.stringify(event.id)}.` };
+  }
+  if (event.recurrence != null && !isCalendarRecurrence(event.recurrence)) {
+    return { ok: false, code: "event.invalid-recurrence", reason: "Calendar recurrence requires a supported frequency, positive safe integer interval and canonical until date." };
+  }
+  if (event.excludeDates !== undefined && (!Array.isArray(event.excludeDates)
+    || !event.excludeDates.every((date) => typeof date === "string" && parseCalendarDate(date) !== null))) {
+    return { ok: false, code: "event.invalid-exclusions", reason: "Calendar exclusions must be canonical dates." };
+  }
+  return { ok: true };
+}
+
+export function isCalendarRecurrence(value: unknown): value is CalendarRecurrence {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+  const rule = value as Record<string, unknown>;
+  return (rule.freq === "daily" || rule.freq === "weekly" || rule.freq === "monthly" || rule.freq === "yearly")
+    && typeof rule.interval === "number" && Number.isSafeInteger(rule.interval) && rule.interval >= 1
+    && typeof rule.until === "string" && (rule.until === "" || parseCalendarDate(rule.until) !== null);
+}
+
 export function isCalendarAllDay(event: Pick<CalendarEvent, "allDay">): boolean {
   return event.allDay === true;
 }
@@ -145,3 +186,15 @@ export function calendarDaysBetween(from: Temporal.PlainDate, to: Temporal.Plain
 export function calendarMinutesBetween(from: Temporal.PlainDateTime, to: Temporal.PlainDateTime): number {
   return from.until(to, { largestUnit: "minutes" }).total("minutes");
 }
+
+/** Move a Calendar interval without changing its local duration. */
+export function calendarEventIntervalAt(
+  event: Pick<CalendarEvent, "start" | "end" | "allDay">,
+  start: string,
+): { readonly start: string; readonly end: string } | null {
+  const bounds = calendarEventBounds(event);
+  const next = isCalendarAllDay(event) ? parseCalendarDate(start)?.toPlainDateTime() : parseCalendarInstant(start);
+  if (bounds === null || next == null) return null;
+  const end = next.add({ minutes: calendarMinutesBetween(bounds.from, bounds.to) });
+  return { start, end: isCalendarAllDay(event) ? formatCalendarDate(end.toPlainDate()) : formatCalendarInstant(end) };
+}
diff --git a/packages/json-document-editing/src/calendar.ts b/packages/json-document-editing/src/calendar.ts
index ae238577..722ece77 100644
--- a/packages/json-document-editing/src/calendar.ts
+++ b/packages/json-document-editing/src/calendar.ts
@@ -23,7 +23,6 @@ import type { EditingHistoryOptions } from "./history.js";
 import {
   addCalendarDate,
   assertCalendarDocument,
-  calendarAllDaySpan,
   calendarDatePart,
   calendarDaysBetween,
   calendarDocumentCalendars,
@@ -36,8 +35,10 @@ import {
   isCalendarAllDay,
   parseCalendarDate,
   parseCalendarInstant,
+  validateCalendarEvent,
 } from "./calendar-validation.js";
-import { calendarEventExcludeDates, calendarEventRecurrence, projectCalendarOccurrences } from "./calendar-occurrence.js";
+import { calendarEventExcludeDates, calendarEventRecurrence, projectCalendarOccurrences, resolveCalendarOccurrence } from "./calendar-occurrence.js";
+import { planCalendarEventEdit } from "./calendar-event-plan.js";
 import {
   planCalendarSelectionMove,
   type CalendarSelectionMoveTarget,
@@ -126,16 +127,13 @@ export const calendarClipboardFormat = {
     if (!Array.isArray(value.items) || value.items.length === 0) return null;
     if (!value.items.every((item) => (
       isRecord(item)
-      && typeof item.sourceEventId === "string"
-      && typeof item.occurrenceStart === "string"
+      && typeof item.sourceEventId === "string" && item.sourceEventId.length > 0
       && isCalendarClipboardEvent(item.event)
+      && item.occurrenceStart === item.event.start
     ))) return null;
-    return {
-      ...value,
-      anchorOccurrenceStart: typeof value.anchorOccurrenceStart === "string"
-        ? value.anchorOccurrenceStart
-        : (value.items[0] as CalendarClipboardItem).occurrenceStart,
-    } as CalendarClipboard;
+    const anchorOccurrenceStart = value.anchorOccurrenceStart ?? (value.items[0] as CalendarClipboardItem).occurrenceStart;
+    if (!value.items.some((item: CalendarClipboardItem) => item.occurrenceStart === anchorOccurrenceStart)) return null;
+    return { ...value, anchorOccurrenceStart } as CalendarClipboard;
   },
 };
 
@@ -206,8 +204,8 @@ export interface CalendarEditor {
   ): CalendarSelectionDragSource | null;
   dispatch(intent: CalendarIntent): EditingResult<CalendarSelection>;
   copy(occurrences?: ReadonlyArray<CalendarOccurrenceSelection>): CalendarClipboard | null;
-  cut(occurrences?: ReadonlyArray<CalendarOccurrenceSelection>): EditingClipboardCut<CalendarClipboard, EditingResult<CalendarSelection>> | null;
-  paste(clipboard: CalendarClipboard, target?: string): EditingResult<CalendarSelection>;
+  cut(source?: ReadonlyArray<CalendarOccurrenceSelection> | CalendarClipboard): EditingClipboardCut<CalendarClipboard, EditingResult<CalendarSelection>> | null;
+  paste(clipboard: CalendarClipboard, target?: string, options?: { readonly calendarId?: string }): EditingResult<CalendarSelection>;
   undo(): EditingResult<CalendarSelection>;
   redo(): EditingResult<CalendarSelection>;
   subscribe(listener: (snapshot: EditingSnapshot<CalendarSelection>) => void): () => void;
@@ -312,6 +310,10 @@ export function createCalendarEditor(
     if (intent.type === "selection.clear") return success(session.select(emptyCalendarSelection()));
 
     if (intent.type === "selection.move") {
+      if (intent.source.points.length !== intent.source.occurrences.length || intent.source.points.some((point, index) => {
+        const occurrence = intent.source.occurrences[index];
+        return occurrence === undefined || point.eventId !== occurrence.eventId || point.occurrenceStart !== occurrence.start;
+      })) return failure("selection.invalid-drag-source");
       const plan = planCalendarSelectionMove(
         value().events,
         intent.source.occurrences,
@@ -327,50 +329,22 @@ export function createCalendarEditor(
       });
     }
 
-    if (intent.type === "event.create") {
-      if (intent.start >= intent.end) return failure("event.invalid-interval");
-      const allDay = intent.allDay === true;
-      const start = allDay ? parseCalendarDate(intent.start) : parseCalendarInstant(intent.start);
-      const end = allDay ? parseCalendarDate(intent.end) : parseCalendarInstant(intent.end);
-      if (start === null || end === null) return failure("event.invalid-instant");
-      const events = value().events;
-      const event: CalendarEvent = {
-        id: createEditingIdAllocator(events.map((event) => event.id), createId, "calendar event")(),
-        title: intent.title ?? "Event",
-        start: intent.start,
-        end: intent.end,
-        allDay,
-        calendarId: intent.calendarId ?? calendarDocumentCalendars(value())[0]?.id ?? "",
-        recurrence: intent.recurrence ?? null,
-        excludeDates: [],
-      };
+    if (intent.type === "event.create" || intent.type === "event.move" || intent.type === "event.resize"
+      || intent.type === "event.move-day" || intent.type === "event.update" || intent.type === "occurrence.edit") {
+      const current = value();
+      const plan = planCalendarEventEdit(current.events, intent, {
+        allocateId: createEditingIdAllocator(current.events.map((event) => event.id), createId, "calendar event"),
+        calendarIds: new Set(calendarDocumentCalendars(current).map((calendar) => calendar.id)),
+        defaultCalendarId: calendarDocumentCalendars(current)[0]?.id ?? "",
+      });
+      if (!plan.ok) return plan;
       return session.apply({
-        operations: [{ op: "add", path: `/events/${events.length}`, value: event }],
-        selectionAfter: selectionForEvents([...events, event], [event.id]),
+        operations: plan.operations,
+        selectionAfter: selectionForOccurrence(plan.selected.eventId, plan.selected.occurrenceStart),
         origin: intent.type,
       });
     }
 
-    if (intent.type === "event.move") {
-      return moveEvent(intent.eventId, intent.start);
-    }
-
-    if (intent.type === "event.resize") {
-      return resizeEvent(intent.eventId, intent.edge, intent.instant);
-    }
-
-    if (intent.type === "event.move-day") {
-      return moveEventDay(intent.eventId, intent.day);
-    }
-
-    if (intent.type === "event.update") {
-      return updateEvent(intent);
-    }
-
-    if (intent.type === "occurrence.edit") {
-      return editOccurrence(intent);
-    }
-
     if (intent.type === "occurrence.remove") {
       return removeOccurrence(intent);
     }
@@ -379,212 +353,12 @@ export function createCalendarEditor(
       return setCalendarHidden(intent.calendarId, intent.hidden);
     }
 
+    if (intent.type !== "selection.remove") return failure("intent.unsupported");
     const selected = selectedEvents();
     if (selected.length === 0) return failure("selection.empty");
     return removeSelected(selected.map((event) => event.id));
   }
 
-  function moveEvent(eventId: string, start: string): EditingResult<CalendarSelection> {
-    const events = value().events;
-    const index = events.findIndex((event) => event.id === eventId);
-    const event = events[index];
-    if (!event) return failure("selection.event-not-found");
-    if (isCalendarAllDay(event)) return failure("event.all-day-move");
-    const from = parseCalendarInstant(event.start);
-    const to = parseCalendarInstant(event.end);
-    const nextStart = parseCalendarInstant(start);
-    if (from === null || to === null || nextStart === null) return failure("event.invalid-instant");
-    const nextEnd = formatCalendarInstant(nextStart.add({ minutes: calendarMinutesBetween(from, to) }));
-    return session.apply({
-      operations: [
-        { op: "replace", path: buildPointer(["events", index, "start"]), value: start },
-        { op: "replace", path: buildPointer(["events", index, "end"]), value: nextEnd },
-      ],
-      selectionAfter: selectionForOccurrence(eventId, start),
-      origin: "event.move",
-    });
-  }
-
-  function resizeEvent(
-    eventId: string,
-    edge: "start" | "end",
-    instant: string,
-  ): EditingResult<CalendarSelection> {
-    const events = value().events;
-    const index = events.findIndex((event) => event.id === eventId);
-    const event = events[index];
-    if (!event) return failure("selection.event-not-found");
-    const parsed = isCalendarAllDay(event) ? parseCalendarDate(instant) : parseCalendarInstant(instant);
-    if (parsed === null) return failure("event.invalid-instant");
-    const start = edge === "start" ? instant : event.start;
-    const end = edge === "end" ? instant : event.end;
-    if (start >= end) return failure("event.invalid-interval");
-    return session.apply({
-      operations: [{ op: "replace", path: buildPointer(["events", index, edge]), value: instant }],
-      selectionAfter: selectionForOccurrence(eventId, start),
-      origin: "event.resize",
-    });
-  }
-
-  function moveEventDay(eventId: string, day: string): EditingResult<CalendarSelection> {
-    const events = value().events;
-    const index = events.findIndex((event) => event.id === eventId);
-    const event = events[index];
-    if (!event) return failure("selection.event-not-found");
-    if (parseCalendarDate(day) === null) return failure("event.invalid-day");
-    if (isCalendarAllDay(event)) {
-      const from = parseCalendarDate(event.start);
-      const to = parseCalendarDate(event.end);
-      const nextDay = parseCalendarDate(day);
-      if (from === null || to === null || nextDay === null) return failure("event.invalid-instant");
-      const delta = calendarDaysBetween(from, nextDay);
-      const movedStart = formatCalendarDate(from.add({ days: delta }));
-      const movedEnd = formatCalendarDate(to.add({ days: delta }));
-      return session.apply({
-        operations: [
-          { op: "replace", path: buildPointer(["events", index, "start"]), value: movedStart },
-          { op: "replace", path: buildPointer(["events", index, "end"]), value: movedEnd },
-        ],
-        selectionAfter: selectionForOccurrence(eventId, movedStart),
-        origin: "event.move-day",
-      });
-    }
-    const from = parseCalendarInstant(event.start);
-    const to = parseCalendarInstant(event.end);
-    const currentDay = parseCalendarInstant(`${calendarDatePart(event.start)}T00:00`);
-    const nextDay = parseCalendarInstant(`${day}T00:00`);
-    if (from === null || to === null || currentDay === null || nextDay === null) return failure("event.invalid-instant");
-    const delta = calendarMinutesBetween(currentDay, nextDay);
-    const movedStart = formatCalendarInstant(from.add({ minutes: delta }));
-    const movedEnd = formatCalendarInstant(to.add({ minutes: delta }));
-    return session.apply({
-      operations: [
-        { op: "replace", path: buildPointer(["events", index, "start"]), value: movedStart },
-        { op: "replace", path: buildPointer(["events", index, "end"]), value: movedEnd },
-      ],
-      selectionAfter: selectionForOccurrence(eventId, movedStart),
-      origin: "event.move-day",
-    });
-  }
-
-  function updateEvent(intent: Extract<CalendarIntent, { type: "event.update" }>): EditingResult<CalendarSelection> {
-    const events = value().events;
-    const index = events.findIndex((event) => event.id === intent.eventId);
-    const event = events[index];
-    if (!event) return failure("selection.event-not-found");
-    let start = intent.start ?? event.start;
-    let end = intent.end ?? event.end;
-    const allDay = intent.allDay ?? event.allDay;
-    if (intent.allDay === true && !event.allDay) {
-      start = calendarDatePart(event.start);
-      end = calendarAllDaySpan(start, start)?.end ?? start;
-    } else if (intent.allDay === false && event.allDay) {
-      start = `${calendarDatePart(event.start)}T09:00`;
-      end = `${calendarDatePart(event.start)}T10:00`;
-    } else if (intent.start !== undefined && intent.end === undefined) {
-      const times = shiftedOccurrenceTimes(event, event.start, intent.start, undefined);
-      if (times === null) return failure("event.invalid-interval");
-      start = times.start;
-      end = times.end;
-    }
-    if (start >= end) return failure("event.invalid-interval");
-    const next: CalendarEvent = {
-      ...event,
-      title: intent.title ?? event.title,
-      start,
-      end,
-      allDay,
-      calendarId: intent.calendarId ?? event.calendarId,
-      recurrence: intent.recurrence === undefined ? event.recurrence : intent.recurrence,
-    };
-    if (isCalendarAllDay(next) ? parseCalendarDate(next.start) === null : parseCalendarInstant(next.start) === null) {
-      return failure("event.invalid-instant");
-    }
-    return session.apply({
-      operations: [{ op: "replace", path: buildPointer(["events", index]), value: next }],
-      selectionAfter: selectionForOccurrence(event.id, next.start),
-      origin: intent.type,
-    });
-  }
-
-  function editOccurrence(intent: Extract<CalendarIntent, { type: "occurrence.edit" }>): EditingResult<CalendarSelection> {
-    const events = value().events;
-    const index = events.findIndex((event) => event.id === intent.eventId);
-    const event = events[index];
-    if (!event) return failure("selection.event-not-found");
-    const recurrence = calendarEventRecurrence(event);
-    if (recurrence === null) {
-      return updateEvent({
-        type: "event.update",
-        eventId: intent.eventId,
-        ...(intent.title === undefined ? {} : { title: intent.title }),
-        ...(intent.start === undefined ? {} : { start: intent.start }),
-        ...(intent.end === undefined ? {} : { end: intent.end }),
-      });
-    }
-    if (intent.scope === "all") {
-      const start = intent.start === undefined
-        ? undefined
-        : shiftSeriesValue(event.start, intent.occurrenceStart, intent.start);
-      const end = intent.end === undefined
-        ? undefined
-        : shiftSeriesValue(event.end, occurrenceEndOf(event, intent.occurrenceStart), intent.end);
-      if (intent.start !== undefined && start === undefined) return failure("event.invalid-instant");
-      if (intent.end !== undefined && end === undefined) return failure("event.invalid-instant");
-      return updateEvent({
-        type: "event.update",
-        eventId: intent.eventId,
-        ...(intent.title === undefined ? {} : { title: intent.title }),
-        ...(start === undefined ? {} : { start }),
-        ...(end === undefined ? {} : { end }),
-      });
-    }
-    const times = shiftedOccurrenceTimes(event, intent.occurrenceStart, intent.start, intent.end);
-    if (times === null) return failure("event.invalid-interval");
-    const occurrenceDate = calendarDatePart(intent.occurrenceStart);
-    if (intent.scope === "this") {
-      const split: CalendarEvent = {
-        ...event,
-        id: createEditingIdAllocator(events.map((event) => event.id), createId, "calendar event")(),
-        title: intent.title ?? event.title,
-        start: times.start,
-        end: times.end,
-        recurrence: null,
-        excludeDates: [],
-      };
-      return session.apply({
-        operations: [
-          {
-            op: "replace",
-            path: buildPointer(["events", index, "excludeDates"]),
-            value: [...calendarEventExcludeDates(event), occurrenceDate],
-          },
-          { op: "add", path: `/events/${events.length}`, value: split },
-        ],
-        selectionAfter: selectionForEvents([...events, split], [split.id]),
-        origin: intent.type,
-      });
-    }
-    const until = addCalendarDate(occurrenceDate, -1) ?? occurrenceDate;
-    const following: CalendarEvent = {
-      ...event,
-      id: createEditingIdAllocator(events.map((event) => event.id), createId, "calendar event")(),
-      title: intent.title ?? event.title,
-      start: times.start,
-      end: times.end,
-      recurrence: { ...recurrence, until: "" },
-      excludeDates: [],
-    };
-    return session.apply({
-      operations: [
-        { op: "replace", path: buildPointer(["events", index, "recurrence"]), value: { ...recurrence, until } },
-        { op: "add", path: `/events/${events.length}`, value: following },
-      ],
-      selectionAfter: selectionForEvents([...events, following], [following.id]),
-      origin: intent.type,
-    });
-  }
-
   function removeOccurrence(
     intent: Extract<CalendarIntent, { type: "occurrence.remove" }>,
   ): EditingResult<CalendarSelection> {
@@ -592,6 +366,8 @@ export function createCalendarEditor(
     const index = events.findIndex((event) => event.id === intent.eventId);
     const event = events[index];
     if (!event) return failure("selection.event-not-found");
+    if (intent.scope !== "this" && intent.scope !== "this-and-following" && intent.scope !== "all") return failure("occurrence.invalid-scope");
+    if (resolveCalendarOccurrence(events, { eventId: event.id, occurrenceStart: intent.occurrenceStart }) === null) return failure("selection.stale-occurrence");
     const recurrence = calendarEventRecurrence(event);
     if (recurrence === null || intent.scope === "all") {
       return removeSelected([event.id]);
@@ -600,7 +376,7 @@ export function createCalendarEditor(
     if (intent.scope === "this") {
       return session.apply({
         operations: [{
-          op: "replace",
+          op: "add",
           path: buildPointer(["events", index, "excludeDates"]),
           value: [...calendarEventExcludeDates(event), occurrenceDate],
         }],
@@ -624,6 +400,7 @@ export function createCalendarEditor(
   }
 
   function setCalendarHidden(calendarId: string, hidden: boolean): EditingResult<CalendarSelection> {
+    if (typeof hidden !== "boolean") return failure("calendar.invalid-hidden");
     const calendars = calendarDocumentCalendars(value());
     const index = calendars.findIndex((item) => item.id === calendarId);
     if (index < 0) return failure("calendar.not-found");
@@ -655,7 +432,8 @@ export function createCalendarEditor(
     const source = occurrences ?? selectedOccurrences();
     const items = source.flatMap((occurrence): CalendarClipboardItem[] => {
       const event = value().events.find((candidate) => candidate.id === occurrence.eventId);
-      if (event === undefined || occurrence.start >= occurrence.end) return [];
+      const current = resolveCalendarOccurrence(value().events, { eventId: occurrence.eventId, occurrenceStart: occurrence.start });
+      if (event === undefined || current === null || current.end !== occurrence.end) return [];
       return [{
         sourceEventId: event.id,
         occurrenceStart: occurrence.start,
@@ -663,12 +441,14 @@ export function createCalendarEditor(
           ...event,
           start: occurrence.start,
           end: occurrence.end,
+          allDay: isCalendarAllDay(event),
+          calendarId: event.calendarId ?? "",
           recurrence: null,
           excludeDates: [],
         },
       }];
     });
-    if (items.length === 0) return null;
+    if (items.length === 0 || items.length !== source.length) return null;
     return {
       type: "application/vnd.interactive-os.calendar+json",
       anchorOccurrenceStart: items[0]!.occurrenceStart,
@@ -704,9 +484,19 @@ export function createCalendarEditor(
     const events = value().events;
     const removals = new Set<string>();
     const exclusions = new Map<string, Set<string>>();
+    const operations: JSONPatchOperation[] = [];
     for (const item of clipboard.items) {
       const event = events.find((candidate) => candidate.id === item.sourceEventId);
       if (event === undefined) return failure("selection.event-not-found");
+      const current = resolveCalendarOccurrence(events, { eventId: event.id, occurrenceStart: item.occurrenceStart });
+      if (current === null || current.end !== item.event.end) return failure("selection.stale-occurrence");
+      const expected: Record<string, JSONValue> = { ...item.event, start: event.start, end: event.end };
+      // Clipboard events are materialized; keep the source's legacy optional-field shape.
+      for (const field of ["allDay", "calendarId", "recurrence", "excludeDates"] as const) {
+        if (event[field] === undefined) delete expected[field];
+        else if (field === "recurrence" || field === "excludeDates") expected[field] = event[field];
+      }
+      operations.push({ op: "test", path: buildPointer(["events", events.indexOf(event)]), value: expected });
       if (calendarEventRecurrence(event) === null) removals.add(event.id);
       else {
         const dates = exclusions.get(event.id) ?? new Set(calendarEventExcludeDates(event));
@@ -714,10 +504,9 @@ export function createCalendarEditor(
         exclusions.set(event.id, dates);
       }
     }
-    const operations: JSONPatchOperation[] = [];
     for (const [eventId, dates] of exclusions) {
       const index = events.findIndex((event) => event.id === eventId);
-      operations.push({ op: "replace", path: buildPointer(["events", index, "excludeDates"]), value: [...dates] });
+      operations.push({ op: "add", path: buildPointer(["events", index, "excludeDates"]), value: [...dates] });
     }
     for (const index of events.map((event, index) => removals.has(event.id) ? index : -1).filter((index) => index >= 0).sort((a, b) => b - a)) {
       operations.push({ op: "remove", path: buildPointer(["events", index]) });
@@ -725,13 +514,17 @@ export function createCalendarEditor(
     return session.apply({ operations, selectionAfter: emptyCalendarSelection(), origin: "clipboard.cut" });
   }
 
-  function paste(clipboard: CalendarClipboard, target?: string): EditingResult<CalendarSelection> {
-    if (clipboard.items.length === 0) return failure("clipboard.empty");
+  function paste(clipboard: CalendarClipboard, target?: string, options: { readonly calendarId?: string } = {}): EditingResult<CalendarSelection> {
+    const parsed = calendarClipboardFormat.parse(clipboard);
+    if (parsed === null) return failure("clipboard.invalid");
+    clipboard = parsed;
+    const calendarIds = new Set(calendarDocumentCalendars(value()).map((calendar) => calendar.id));
+    if (options.calendarId !== undefined && !calendarIds.has(options.calendarId)) return failure("calendar.not-found");
     const resolvedTarget = target ?? selectedEvents()[0]?.start;
     if (resolvedTarget === undefined) return failure("clipboard.invalid-target");
     const targetInstant = parseCalendarInstant(resolvedTarget);
     const targetDate = parseCalendarDate(calendarDatePart(resolvedTarget));
-    if (targetInstant === null && targetDate === null) return failure("clipboard.invalid-target");
+    if (targetInstant === null && parseCalendarDate(resolvedTarget) === null) return failure("clipboard.invalid-target");
     const timedAnchor = parseCalendarInstant(clipboard.anchorOccurrenceStart)
       ?? clipboard.items.map((item) => parseCalendarInstant(item.event.start)).find((item) => item !== null)
       ?? null;
@@ -763,8 +556,10 @@ export function createCalendarEditor(
         start = source.allDay ? formatCalendarDate(nextStart) : `${formatCalendarDate(nextStart)}T${source.start.slice(11)}`;
         end = source.allDay ? formatCalendarDate(nextStart.add({ days: duration })) : `${formatCalendarDate(nextStart.add({ days: duration }))}T${source.end.slice(11)}`;
       }
-      const event = { ...source, id: allocateId(), start, end, recurrence: null, excludeDates: [] };
-      pasted.push(event);
+      const event = { ...source, start, end, calendarId: options.calendarId ?? source.calendarId, recurrence: null, excludeDates: [] };
+      const validation = validateCalendarEvent(event, calendarIds);
+      if (!validation.ok) return validation;
+      pasted.push({ ...event, id: allocateId() });
     }
     return session.apply({
       operations: pasted.map((event, offset) => ({ op: "add", path: `/events/${existing.length + offset}`, value: event })),
@@ -781,8 +576,8 @@ export function createCalendarEditor(
     prepareSelectionDrag,
     dispatch,
     copy,
-    cut: (occurrences) => cutEditingClipboard(
-      () => copy(occurrences),
+    cut: (source) => cutEditingClipboard(
+      () => source !== undefined && "type" in source ? calendarClipboardFormat.parse(source) : copy(source),
       removeClipboard,
     ),
     paste,
@@ -793,16 +588,9 @@ export function createCalendarEditor(
 }
 
 function isCalendarClipboardEvent(value: unknown): value is CalendarEvent {
-  return isRecord(value)
-    && typeof value.id === "string"
-    && typeof value.title === "string"
-    && typeof value.start === "string"
-    && typeof value.end === "string"
-    && typeof value.allDay === "boolean"
-    && typeof value.calendarId === "string"
-    && value.recurrence === null
-    && Array.isArray(value.excludeDates)
-    && value.excludeDates.every((date) => typeof date === "string");
+  return isRecord(value) && validateCalendarEvent(value).ok
+    && typeof value.allDay === "boolean" && typeof value.calendarId === "string"
+    && value.recurrence === null && Array.isArray(value.excludeDates) && value.excludeDates.length === 0;
 }
 
 function isRecord(value: unknown): value is Record<string, unknown> {
@@ -868,25 +656,6 @@ function compareCalendarOccurrencePoints(
     || left.eventId.localeCompare(right.eventId);
 }
 
-function resolveCalendarOccurrence(
-  events: ReadonlyArray<CalendarEvent>,
-  point: CalendarOccurrencePoint,
-): CalendarOccurrenceSelection | null {
-  const event = events.find((candidate) => candidate.id === point.eventId);
-  if (event === undefined) return null;
-  const day = calendarDatePart(point.occurrenceStart);
-  const next = addCalendarDate(day, 1);
-  if (next === null) return null;
-  const occurrence = projectCalendarOccurrences([event], day, next).find((candidate) => (
-    candidate.start === point.occurrenceStart
-  ));
-  return occurrence === undefined ? null : {
-    eventId: event.id,
-    start: occurrence.start,
-    end: occurrence.end,
-  };
-}
-
 export function calendarNowMarker(nowInstant: string, day: string): { readonly minutes: number } | null {
   if (calendarDatePart(nowInstant) !== day) return null;
   const start = parseCalendarInstant(`${day}T00:00`);
@@ -1156,58 +925,6 @@ export function calendarEventsInMonth(
   }));
 }
 
-function occurrenceEndOf(event: CalendarEvent, occurrenceStart: string): string {
-  const bounds = calendarEventBounds(event);
-  if (bounds === null) return occurrenceStart;
-  if (isCalendarAllDay(event)) {
-    const from = parseCalendarDate(calendarDatePart(occurrenceStart));
-    if (from === null) return occurrenceStart;
-    return formatCalendarDate(from.add({ days: calendarDaysBetween(bounds.from.toPlainDate(), bounds.to.toPlainDate()) }));
-  }
-  const from = parseCalendarInstant(occurrenceStart);
-  if (from === null) return occurrenceStart;
-  return formatCalendarInstant(from.add({ minutes: calendarMinutesBetween(bounds.from, bounds.to) }));
-}
-
-function shiftSeriesValue(seriesValue: string, origin: string, next: string): string | undefined {
-  const originInstant = parseCalendarInstant(origin);
-  const nextInstant = parseCalendarInstant(next);
-  const seriesInstant = parseCalendarInstant(seriesValue);
-  if (originInstant !== null && nextInstant !== null && seriesInstant !== null) {
-    return formatCalendarInstant(seriesInstant.add({ minutes: calendarMinutesBetween(originInstant, nextInstant) }));
-  }
-  const originDate = parseCalendarDate(calendarDatePart(origin));
-  const nextDate = parseCalendarDate(calendarDatePart(next));
-  const seriesDate = parseCalendarDate(calendarDatePart(seriesValue));
-  if (originDate === null || nextDate === null || seriesDate === null) return undefined;
-  return formatCalendarDate(seriesDate.add({ days: calendarDaysBetween(originDate, nextDate) }));
-}
-
-function shiftedOccurrenceTimes(
-  event: CalendarEvent,
-  occurrenceStart: string,
-  start: string | undefined,
-  end: string | undefined,
-): { readonly start: string; readonly end: string } | null {
-  const nextStart = start ?? occurrenceStart;
-  if (end !== undefined) return nextStart < end ? { start: nextStart, end } : null;
-  const bounds = calendarEventBounds(event);
-  if (bounds === null) return null;
-  if (isCalendarAllDay(event)) {
-    const from = parseCalendarDate(calendarDatePart(nextStart));
-    if (from === null) return null;
-    const duration = calendarDaysBetween(bounds.from.toPlainDate(), bounds.to.toPlainDate());
-    const nextEnd = formatCalendarDate(from.add({ days: duration }));
-    const dateStart = calendarDatePart(nextStart);
-    return dateStart < nextEnd ? { start: dateStart, end: nextEnd } : null;
-  }
-  const from = parseCalendarInstant(nextStart);
-  if (from === null) return null;
-  const duration = calendarMinutesBetween(bounds.from, bounds.to);
-  const nextEnd = formatCalendarInstant(from.add({ minutes: duration }));
-  return nextStart < nextEnd ? { start: nextStart, end: nextEnd } : null;
-}
-
 function emptyCalendarSelection(): CalendarSelection {
   return { kind: "range", ranges: [], primaryIndex: null };
 }
diff --git a/packages/json-document-editing/tests/calendar-pointer.test.ts b/packages/json-document-editing/tests/calendar-pointer.test.ts
index 11adcf75..8e0a390d 100644
--- a/packages/json-document-editing/tests/calendar-pointer.test.ts
+++ b/packages/json-document-editing/tests/calendar-pointer.test.ts
@@ -314,7 +314,7 @@ describe("previewCalendarTimeGrid", () => {
     expect(preview.find((item) => item.id === "preview")).toMatchObject({
       start: "2026-08-04T11:00",
       end: "2026-08-04T11:30",
-      recurrence: { freq: "daily", interval: 1, until: "" },
+      recurrence: { freq: "daily", interval: 1, until: "2026-08-05" },
     });
   });
 });
@@ -473,9 +473,11 @@ describe("bindCalendarTimeGridIntent", () => {
     });
     const intent = bindCalendarTimeGridIntent(move, series, "2026-08-04T09:00", "all");
     expect(intent).toEqual({
-      type: "event.move",
+      type: "occurrence.edit",
       eventId: "standup",
-      start: "2026-08-03T11:00",
+      occurrenceStart: "2026-08-04T09:00",
+      scope: "all",
+      start: "2026-08-04T11:00",
     });
     const editor = createCalendarEditor({
       calendars: [{ id: "home", title: "Home", hidden: false, color: "subtle" }],
diff --git a/packages/json-document-editing/tests/calendar-protocol.test.ts b/packages/json-document-editing/tests/calendar-protocol.test.ts
new file mode 100644
index 00000000..3f291145
--- /dev/null
+++ b/packages/json-document-editing/tests/calendar-protocol.test.ts
@@ -0,0 +1,300 @@
+import { describe, expect, test } from "vitest";
+import {
+  addCalendarDate, bindCalendarAllDayIntent, bindCalendarMonthIntent, bindCalendarTimeGridIntent,
+  calendarClipboardFormat, calendarOccurrenceTopology, calendarUpdateIntent, createCalendarEditor,
+  interpretCalendarAllDayPointer, interpretCalendarMonthPointer, interpretCalendarTimeGridPointer,
+  previewCalendarAllDay, previewCalendarMonth, previewCalendarTimeGrid, planCalendarSelectionMove,
+  projectCalendarOccurrences,
+  type CalendarDocument, type CalendarEvent, type CalendarIntent,
+} from "../src/index.js";
+
+const event = (patch: Partial<CalendarEvent> = {}): CalendarEvent => ({
+  id: "a", title: "A", start: "2026-08-01T09:00", end: "2026-08-01T10:00",
+  allDay: false, calendarId: "work", recurrence: null, excludeDates: [], ...patch,
+});
+const document = (events = [event()]): CalendarDocument => ({
+  calendars: [{ id: "work", title: "Work", hidden: false, color: "accent" }], events,
+});
+function editor(events = [event()]) {
+  let sequence = 0;
+  return createCalendarEditor(document(events), { createId: () => `new-${++sequence}` });
+}
+const recurring = (allDay = false) => event({
+  ...(allDay ? { start: "2026-08-01", end: "2026-08-02", allDay } : {}),
+  recurrence: { freq: "daily", interval: 1, until: "2026-08-08" },
+});
+function capture(instance: ReturnType<typeof editor>, start = "2026-08-01T09:00") {
+  const point = { eventId: "a", occurrenceStart: start };
+  const topology = calendarOccurrenceTopology(instance.snapshot.value as CalendarDocument, "2026-08-01", "2026-08-09");
+  instance.dispatch({ type: "selection.set", point, topology });
+  return instance.prepareSelectionDrag(point, topology)!;
+}
+function visible(events: ReadonlyArray<CalendarEvent>) {
+  return projectCalendarOccurrences(events, "2026-08-01", "2026-08-09")
+    .map(({ event, start, end }) => ({ title: event.title, start, end }))
+    .sort((left, right) => JSON.stringify(left).localeCompare(JSON.stringify(right)));
+}
+
+describe("Calendar protocol rejection", () => {
+  test.each([
+    { type: "event.typo" },
+    { type: "event.update", eventId: "a", end: "zz" },
+    { type: "event.update", eventId: "a", calendarId: "unknown" },
+    { type: "event.create", start: "2026-08-01T11:00", end: "2026-08-01T12:00", calendarId: "unknown" },
+    { type: "event.update", eventId: "a", recurrence: { freq: "daily", interval: 1.5, until: "" } },
+    { type: "event.update", eventId: "a", recurrence: { freq: "daily", interval: 1, until: "bad-date" } },
+  ])("rejects $type without changing value, selection, history or notifications", (intent) => {
+    const instance = editor();
+    instance.dispatch({ type: "event.update", eventId: "a", title: "Before undo" });
+    instance.undo();
+    const before = instance.snapshot;
+    const observed: unknown[] = [];
+    const release = instance.subscribe((snapshot) => observed.push(snapshot));
+    expect(instance.dispatch(intent as CalendarIntent)).toMatchObject({ ok: false, code: expect.any(String) });
+    expect(instance.snapshot).toEqual(before);
+    expect(observed).toEqual([]);
+    expect(() => createCalendarEditor(instance.snapshot.value as CalendarDocument)).not.toThrow();
+    expect(instance.redo().ok).toBe(true);
+    release();
+  });
+
+  test("rejects inverted clipboard intervals at parse and direct paste boundaries", () => {
+    const payload = structuredClone(editor().copy()!);
+    const invalid = { ...payload, items: payload.items.map((item) => ({
+      ...item, event: { ...item.event, start: "2026-08-01T11:00", end: "2026-08-01T10:00" },
+    })) };
+    expect(calendarClipboardFormat.parse(invalid)).toBeNull();
+    const instance = editor([]);
+    const before = instance.snapshot;
+    expect(instance.paste(invalid, "2026-08-02T12:00").ok).toBe(false);
+    expect(instance.snapshot).toEqual(before);
+  });
+
+  test("rejects a foreign calendar reference without silently changing its owner", () => {
+    const payload = editor().copy()!;
+    const instance = createCalendarEditor({
+      calendars: [{ id: "personal", title: "Personal", hidden: false, color: "subtle" }], events: [],
+    });
+    const before = instance.snapshot;
+    expect(instance.paste(payload, "2026-08-02T12:00").ok).toBe(false);
+    expect(instance.snapshot).toEqual(before);
+    expect(instance.paste(payload, "2026-08-02T12:00", { calendarId: "personal" }).ok).toBe(true);
+    expect((instance.snapshot.value as CalendarDocument).events[0]?.calendarId).toBe("personal");
+    expect(() => createCalendarEditor(instance.snapshot.value as CalendarDocument)).not.toThrow();
+  });
+
+  test("captured cut rejects content changed after the clipboard write", () => {
+    const instance = editor();
+    const payload = instance.copy()!;
+    instance.dispatch({ type: "event.update", eventId: "a", title: "Not written to clipboard" });
+    const before = instance.snapshot;
+    expect(instance.cut(payload)?.result.ok).toBe(false);
+    expect(instance.snapshot).toEqual(before);
+  });
+
+  test("legacy documents emit canonical clipboard events and can still cut", () => {
+    const instance = createCalendarEditor({ events: [{ id: "legacy", title: "Legacy", start: "2026-08-01T09:00", end: "2026-08-01T10:00" }] } as unknown as CalendarDocument);
+    expect(calendarClipboardFormat.parse(instance.copy())).not.toBeNull();
+    expect(instance.cut()?.result.ok).toBe(true);
+  });
+
+  test("rejects inconsistent captured points and duplicate occurrences atomically", () => {
+    const instance = editor();
+    const source = capture(instance);
+    const before = instance.snapshot;
+    for (const invalid of [
+      { ...source, points: [] },
+      { ...source, points: [...source.points, ...source.points], occurrences: [...source.occurrences, ...source.occurrences] },
+    ]) {
+      expect(instance.dispatch({ type: "selection.move", source: invalid, target: { type: "day", day: "2026-08-02" } }).ok).toBe(false);
+      expect(instance.snapshot).toEqual(before);
+    }
+  });
+
+  test("rejects an occurrence removed after capture", () => {
+    const instance = editor([recurring()]);
+    const source = capture(instance, "2026-08-03T09:00");
+    instance.dispatch({ type: "occurrence.remove", eventId: "a", occurrenceStart: "2026-08-03T09:00", scope: "this" });
+    const before = instance.snapshot;
+    expect(instance.dispatch({ type: "selection.move", source, target: { type: "instant", instant: "2026-08-03T12:00" } })).toMatchObject({ ok: false });
+    expect(instance.snapshot).toEqual(before);
+  });
+
+  test("rejects a drag whose captured interval changed but preserves unrelated edits", () => {
+    const instance = editor();
+    const source = capture(instance);
+    instance.dispatch({ type: "event.update", eventId: "a", end: "2026-08-01T11:00" });
+    const before = instance.snapshot;
+    expect(instance.dispatch({ type: "selection.move", source, target: { type: "instant", instant: "2026-08-01T12:00" } })).toMatchObject({ ok: false });
+    expect(instance.snapshot).toEqual(before);
+    const fresh = capture(instance);
+    instance.dispatch({ type: "event.update", eventId: "a", title: "New title" });
+    expect(instance.dispatch({ type: "selection.move", source: fresh, target: { type: "instant", instant: "2026-08-01T12:00" } }).ok).toBe(true);
+    expect((instance.snapshot.value as CalendarDocument).events[0]).toMatchObject({ title: "New title", start: "2026-08-01T12:00", end: "2026-08-01T14:00" });
+  });
+
+  test("bounds allocator collisions before mutation", () => {
+    let calls = 0;
+    const instance = createCalendarEditor(document([recurring()]), { createId: () => ++calls <= 100 ? "a" : "new" });
+    const source = capture(instance, "2026-08-03T09:00");
+    const before = instance.snapshot;
+    expect(() => instance.dispatch({ type: "selection.move", source, target: { type: "instant", instant: "2026-08-03T12:00" } })).toThrow(/unique/);
+    expect(calls).toBe(100);
+    expect(instance.snapshot).toEqual(before);
+  });
+});
+
+describe("Calendar recurrence and input parity", () => {
+  const scopes = ["this", "this-and-following", "all"] as const;
+  test.each(scopes)("time resize preview matches commit: %s", (scope) => {
+    const original = recurring();
+    const instance = editor([original]);
+    const release = { originInstant: "2026-08-03T10:00", targetInstant: "2026-08-03T11:00", originEventId: "a", originEventStart: "2026-08-03T09:00", originHandle: "end" as const };
+    const preview = previewCalendarTimeGrid([original], release, scope);
+    expect(instance.dispatch(bindCalendarTimeGridIntent(interpretCalendarTimeGridPointer(release), original, release.originEventStart, scope)!).ok).toBe(true);
+    expect(visible(preview)).toEqual(visible((instance.snapshot.value as CalendarDocument).events));
+  });
+  test.each(scopes)("all-day resize preview matches commit: %s", (scope) => {
+    const original = recurring(true);
+    const instance = editor([original]);
+    const release = { originDay: "2026-08-03", targetDay: "2026-08-04", originEventId: "a", originEventStart: "2026-08-03", originHandle: "end" as const };
+    const preview = previewCalendarAllDay([original], release, scope);
+    expect(instance.dispatch(bindCalendarAllDayIntent(interpretCalendarAllDayPointer(release), original, release.originEventStart, scope)!).ok).toBe(true);
+    expect(visible(preview)).toEqual(visible((instance.snapshot.value as CalendarDocument).events));
+  });
+  test.each(scopes)("month move preview matches commit: %s", (scope) => {
+    const original = recurring(true);
+    const instance = editor([original]);
+    const release = { originDay: "2026-08-03", targetDay: "2026-08-04", originEventId: "a", originEventStart: "2026-08-03", eventsOnTargetDay: [] };
+    const preview = previewCalendarMonth([original], release, scope);
+    expect(instance.dispatch(bindCalendarMonthIntent(interpretCalendarMonthPointer(release), original, release.originEventStart, scope)!).ok).toBe(true);
+    expect(visible(preview)).toEqual(visible((instance.snapshot.value as CalendarDocument).events));
+  });
+  test("all-day all-scope resize and Inspector preserve the same two-day interval", () => {
+    const original = recurring(true);
+    const pointer = editor([original]);
+    const inspector = editor([original]);
+    const release = { originDay: "2026-08-03", targetDay: "2026-08-04", originEventId: "a", originEventStart: "2026-08-03", originHandle: "end" as const };
+    pointer.dispatch(bindCalendarAllDayIntent(interpretCalendarAllDayPointer(release), original, release.originEventStart, "all")!);
+    inspector.dispatch(calendarUpdateIntent(original, "2026-08-03", "all", { end: "2026-08-05" }));
+    expect(pointer.snapshot.value).toEqual(inspector.snapshot.value);
+    expect((pointer.snapshot.value as CalendarDocument).events[0]).toMatchObject({ start: "2026-08-01", end: "2026-08-03" });
+  });
+  test.each(scopes)("single recurring selection drag supports %s and one-step undo", (scope) => {
+    const instance = editor([recurring()]);
+    const source = capture(instance, "2026-08-03T09:00");
+    const before = instance.snapshot;
+    expect(instance.dispatch({ type: "selection.move", source, target: { type: "instant", instant: "2026-08-03T11:00" }, scope }).ok).toBe(true);
+    expect(instance.undo().ok).toBe(true);
+    expect(instance.snapshot.value).toEqual(before.value);
+    expect(instance.snapshot.selection).toEqual(before.selection);
+  });
+  test.each([399, 400, 600, 100_000])("projects a narrow window after occurrence %s without a hidden lifetime cap", (index) => {
+    const original = event({ recurrence: { freq: "daily", interval: 1, until: "" } });
+    const day = addCalendarDate("2026-08-01", index)!;
+    expect(projectCalendarOccurrences([original], day, addCalendarDate(day, 1)!)).toMatchObject([{ start: `${day}T09:00`, end: `${day}T10:00` }]);
+  });
+
+  test.each(scopes)("moves duplicate series once for scope %s, retaining every selected point", (scope) => {
+    const original = recurring();
+    const second = { ...structuredClone(original), id: "b", title: "B" };
+    const instance = editor([original, second]);
+    const points = [
+      { eventId: "a", occurrenceStart: "2026-08-04T09:00" },
+      { eventId: "a", occurrenceStart: "2026-08-03T09:00" },
+      { eventId: "b", occurrenceStart: "2026-08-03T09:00" },
+    ];
+    points.forEach((point, index) => instance.dispatch({ type: "selection.set", point, topology: { points }, mode: index === 0 ? "replace" : "toggle" }));
+    const source = instance.prepareSelectionDrag(points[0]!, { points })!;
+    const before = instance.snapshot;
+    const target = { type: "instant" as const, instant: "2026-08-04T11:00" };
+    const preview = planCalendarSelectionMove([original, second], source.occurrences, source.anchor, target, { scope, primary: source.primary });
+    expect(preview.ok).toBe(true);
+    expect(instance.dispatch({ type: "selection.move", source, target, scope }).ok).toBe(true);
+    const current = (instance.snapshot.value as CalendarDocument).events;
+    expect(current).toHaveLength(scope === "this" ? 5 : scope === "all" ? 2 : 4);
+    expect(instance.selectedOccurrences.map(({ start }) => start).sort()).toEqual(["2026-08-03T11:00", "2026-08-03T11:00", "2026-08-04T11:00"]);
+    if (preview.ok) expect(visible(preview.events)).toEqual(visible(current));
+    if (scope === "this-and-following") expect(current[0]?.recurrence?.until).toBe("2026-08-02");
+    expect(instance.undo().ok).toBe(true);
+    expect(instance.snapshot.value).toEqual(before.value);
+    expect(instance.snapshot.selection).toEqual(before.selection);
+  });
+
+  test.each(["all", "this-and-following"] as const)("translates the finite lifetime and future exclusions for %s", (scope) => {
+    const instance = editor([{ ...recurring(), excludeDates: ["2026-08-05"] }]);
+    expect(instance.dispatch({ type: "occurrence.edit", eventId: "a", occurrenceStart: "2026-08-03T09:00", start: "2026-08-04T09:00", scope }).ok).toBe(true);
+    const series = (instance.snapshot.value as CalendarDocument).events.at(-1)!;
+    expect(series.recurrence?.until).toBe("2026-08-09");
+    expect(series.excludeDates).toEqual(["2026-08-06"]);
+    expect(projectCalendarOccurrences([series], "2026-08-06", "2026-08-07")).toEqual([]);
+    expect(projectCalendarOccurrences([series], "2026-08-10", "2026-08-11")).toEqual([]);
+  });
+
+  test.each([
+    ["weekly", "2026-01-01", "2038-07-01", "2038-07-02"],
+    ["monthly", "2026-01-31", "2076-02-29", "2076-03-01"],
+    ["yearly", "2000-02-29", "2600-02-28", "2600-03-01"],
+  ] as const)("seeks late %s occurrences, including constrained dates", (freq, start, from, to) => {
+    const original = event({ start: `${start}T09:00`, end: `${start}T10:00`, recurrence: { freq, interval: 1, until: "" } });
+    expect(projectCalendarOccurrences([original], from, to)).toHaveLength(1);
+  });
+
+  test("seeking retains long intervals already in progress", () => {
+    const original = event({ start: "2026-01-01", end: "2026-01-31", allDay: true, recurrence: { freq: "weekly", interval: 2, until: "" } });
+    const late = projectCalendarOccurrences([original], "2050-01-15", "2050-01-16");
+    expect(late.length).toBeGreaterThanOrEqual(2);
+    expect(late.every((item) => item.start <= "2050-01-15" && item.end > "2050-01-15")).toBe(true);
+  });
+
+  test("preview ID collisions do not alias an existing event", () => {
+    const original = { ...recurring(), id: "preview" };
+    const preview = previewCalendarTimeGrid([original], {
+      originInstant: "2026-08-03T09:00", targetInstant: "2026-08-03T11:00",
+      originEventId: "preview", originEventStart: "2026-08-03T09:00", originHandle: "body",
+    });
+    expect(new Set(preview.map((item) => item.id)).size).toBe(2);
+  });
+
+  test("detached group occurrences preserve independent extension metadata", () => {
+    const instance = editor([{ ...recurring(), metadata: { note: "Keep me" } }]);
+    const source = capture(instance);
+    expect(instance.dispatch({ type: "selection.move", source, target: { type: "instant", instant: "2026-08-01T11:00" } }).ok).toBe(true);
+    const current = instance.snapshot.value as CalendarDocument;
+    expect(current.events.at(-1)?.metadata).toEqual({ note: "Keep me" });
+    expect(() => createCalendarEditor(current)).not.toThrow();
+  });
+
+  test("rejects an unrepresentable constrained monthly group instead of losing points", () => {
+    const original = event({ start: "2026-01-30T09:00", end: "2026-01-30T10:00", recurrence: { freq: "monthly", interval: 1, until: "" } });
+    const plan = planCalendarSelectionMove([original], [
+      { eventId: "a", start: "2026-01-30T09:00", end: "2026-01-30T10:00" },
+      { eventId: "a", start: "2026-02-28T09:00", end: "2026-02-28T10:00" },
+    ], { eventId: "a", occurrenceStart: original.start }, { type: "day", day: "2026-01-31" }, { scope: "all" });
+    expect(plan).toEqual({ ok: false, code: "selection.unrepresentable-series-move" });
+  });
+
+  test("single all-scope edits also reject a monthly anchor that cannot represent the requested occurrence", () => {
+    const original = event({ start: "2026-01-30T09:00", end: "2026-01-30T10:00", recurrence: { freq: "monthly", interval: 1, until: "" } });
+    const instance = editor([original]);
+    const before = instance.snapshot;
+    expect(instance.dispatch({ type: "occurrence.edit", eventId: "a", occurrenceStart: "2026-02-28T09:00", start: "2026-03-01T09:00", scope: "all" }))
+      .toEqual({ ok: false, code: "selection.unrepresentable-series-move" });
+    expect(instance.snapshot).toEqual(before);
+    expect(previewCalendarTimeGrid([original], {
+      originInstant: "2026-02-28T09:00", targetInstant: "2026-03-01T09:00",
+      originEventId: "a", originEventStart: "2026-02-28T09:00", originHandle: "body",
+    }, "all")).toEqual([original]);
+  });
+
+  test.each([
+    ["monthly", true, "2026-01-30", "2026-01-31", "2026-02-28", "2026-03-01"],
+    ["monthly", false, "2026-01-30T23:30", "2026-01-31T00:15", "2026-02-28T23:30", "2026-03-01T00:15"],
+    ["yearly", true, "2028-02-28", "2028-02-29", "2029-02-28", "2029-03-01"],
+  ] as const)("%s projection preserves duration across constrained dates (allDay=%s)", (freq, allDay, start, end, nextStart, nextEnd) => {
+    const original = event({ start, end, allDay, recurrence: { freq, interval: 1, until: "" } });
+    const projected = projectCalendarOccurrences([original], nextStart.slice(0, 10), addCalendarDate(nextEnd.slice(0, 10), 1)!);
+    expect(projected.map(({ start, end }) => ({ start, end }))).toEqual([{ start: nextStart, end: nextEnd }]);
+    expect(() => createCalendarEditor(document(projected.map(({ event, start, end }) => ({ ...event, start, end }))))).not.toThrow();
+  });
+});
diff --git a/site/scripts/check-calendar-allday-span.mjs b/site/scripts/check-calendar-allday-span.mjs
index 7a40663a..179ea4a8 100644
--- a/site/scripts/check-calendar-allday-span.mjs
+++ b/site/scripts/check-calendar-allday-span.mjs
@@ -6,6 +6,7 @@ const owner = read("packages/json-document-editing/src/calendar-validation.ts");
 const ownerIndex = read("packages/json-document-editing/src/index.ts");
 const ownerTest = read("packages/json-document-editing/tests/calendar-validation.test.ts");
 const editor = read("packages/json-document-editing/src/calendar.ts");
+const eventPlan = read("packages/json-document-editing/src/calendar-event-plan.ts");
 const allDayPointer = read("packages/json-document-editing/src/calendar-allday-pointer.ts");
 const monthPointer = read("packages/json-document-editing/src/calendar-month-pointer.ts");
 const host = read("site/src/routes/calendar-demo/CalendarDemoRoute.tsx");
@@ -16,14 +17,15 @@ const usage = read("site/src/shared/demo-workbench/demo-sources.ts");
 requireText(owner, "export function calendarAllDaySpan");
 requireText(ownerIndex, "calendarAllDaySpan");
 requireText(ownerTest, 'calendarAllDaySpan("2026-05-27", "2026-05-25")');
-requireText(editor, "calendarAllDaySpan(start, start)?.end");
+requireText(editor, "planCalendarEventEdit(current.events, intent");
+requireText(eventPlan, "calendarAllDaySpan(start, start)?.end");
 requireCount(allDayPointer, "calendarAllDaySpan(", 2);
 requireCount(monthPointer, "calendarAllDaySpan(", 1);
 requireCount(host, "calendarAllDaySpan(", 0);
 requireCount(inspector, "calendarAllDaySpan(", 1);
 requireCount(timeGrid, "calendarAllDaySpan(", 1);
 forbid(allDayPointer, /addCalendarDate\(release\.targetDay, 1\)/);
-forbid(editor, /addCalendarDate\(start, 1\)/);
+forbid(eventPlan, /addCalendarDate\(start, 1\)/);
 forbid(host, /addCalendarDate\((?:day|value), 1\)/);
 requireText(usage, 'symbol: "calendarAllDaySpan"');
 requireText(usage, 'sourcePath: "packages/json-document-editing/src/calendar-validation.ts"');
diff --git a/site/src/app/routeTree.gen.ts b/site/src/app/routeTree.gen.ts
index 4251679d..e1ead577 100644
--- a/site/src/app/routeTree.gen.ts
+++ b/site/src/app/routeTree.gen.ts
@@ -61,7 +61,6 @@ import { Route as PageDocsAdapterKeyboardRouteImport } from "./routes/_page/docs
 import { Route as PageDocsAdapterVirtualSelectionRouteImport } from "./routes/_page/docs/adapter-virtual-selection";
 import { Route as PageDocsAdaptersRouteImport } from "./routes/_page/docs/adapters";
 import { Route as PageDocsAnimationRouteImport } from "./routes/_page/docs/animation";
-import { Route as PageDocsApiRouteImport } from "./routes/_page/docs/api";
 import { Route as PageDocsClipboardRouteImport } from "./routes/_page/docs/clipboard";
 import { Route as PageDocsComposerRouteImport } from "./routes/_page/docs/composer";
 import { Route as PageDocsConceptsRouteImport } from "./routes/_page/docs/concepts";
@@ -128,6 +127,7 @@ import { Route as PageDocsAffordanceSnapRouteImport } from "./routes/_page/docs/
 import { Route as PageDocsAffordanceTripleClickRouteImport } from "./routes/_page/docs/affordance/triple-click";
 import { Route as PageDocsAffordanceTypeaheadRouteImport } from "./routes/_page/docs/affordance/typeahead";
 import { Route as PageDocsAffordanceZoomRouteImport } from "./routes/_page/docs/affordance/zoom";
+import { Route as PageDocsApiIndexRouteImport } from "./routes/_page/docs/api/index";
 import { Route as PageDocsApiA2uiRouteImport } from "./routes/_page/docs/api/a2ui";
 import { Route as PageDocsApiAffordanceRouteImport } from "./routes/_page/docs/api/affordance";
 import { Route as PageDocsApiAjvRouteImport } from "./routes/_page/docs/api/ajv";
@@ -436,11 +436,6 @@ const PageDocsAnimationRoute = PageDocsAnimationRouteImport.update({
   path: "/docs/animation",
   getParentRoute: () => PageRoute,
 } as any);
-const PageDocsApiRoute = PageDocsApiRouteImport.update({
-  id: "/docs/api",
-  path: "/docs/api",
-  getParentRoute: () => PageRoute,
-} as any);
 const PageDocsClipboardRoute = PageDocsClipboardRouteImport.update({
   id: "/docs/clipboard",
   path: "/docs/clipboard",
@@ -792,169 +787,174 @@ const PageDocsAffordanceZoomRoute = PageDocsAffordanceZoomRouteImport.update({
   path: "/docs/affordance/zoom",
   getParentRoute: () => PageRoute,
 } as any);
+const PageDocsApiIndexRoute = PageDocsApiIndexRouteImport.update({
+  id: "/docs/api/",
+  path: "/docs/api/",
+  getParentRoute: () => PageRoute,
+} as any);
 const PageDocsApiA2uiRoute = PageDocsApiA2uiRouteImport.update({
-  id: "/a2ui",
-  path: "/a2ui",
-  getParentRoute: () => PageDocsApiRoute,
+  id: "/docs/api/a2ui",
+  path: "/docs/api/a2ui",
+  getParentRoute: () => PageRoute,
 } as any);
 const PageDocsApiAffordanceRoute = PageDocsApiAffordanceRouteImport.update({
-  id: "/affordance",
-  path: "/affordance",
-  getParentRoute: () => PageDocsApiRoute,
+  id: "/docs/api/affordance",
+  path: "/docs/api/affordance",
+  getParentRoute: () => PageRoute,
 } as any);
 const PageDocsApiAjvRoute = PageDocsApiAjvRouteImport.update({
-  id: "/ajv",
-  path: "/ajv",
-  getParentRoute: () => PageDocsApiRoute,
+  id: "/docs/api/ajv",
+  path: "/docs/api/ajv",
+  getParentRoute: () => PageRoute,
 } as any);
 const PageDocsApiAnimationReactRoute =
   PageDocsApiAnimationReactRouteImport.update({
-    id: "/animation-react",
-    path: "/animation-react",
-    getParentRoute: () => PageDocsApiRoute,
+    id: "/docs/api/animation-react",
+    path: "/docs/api/animation-react",
+    getParentRoute: () => PageRoute,
   } as any);
 const PageDocsApiAnnotationRoute = PageDocsApiAnnotationRouteImport.update({
-  id: "/annotation",
-  path: "/annotation",
-  getParentRoute: () => PageDocsApiRoute,
+  id: "/docs/api/annotation",
+  path: "/docs/api/annotation",
+  getParentRoute: () => PageRoute,
 } as any);
 const PageDocsApiCalendarRoute = PageDocsApiCalendarRouteImport.update({
-  id: "/calendar",
-  path: "/calendar",
-  getParentRoute: () => PageDocsApiRoute,
+  id: "/docs/api/calendar",
+  path: "/docs/api/calendar",
+  getParentRoute: () => PageRoute,
 } as any);
 const PageDocsApiCollaborationRoute =
   PageDocsApiCollaborationRouteImport.update({
-    id: "/collaboration",
-    path: "/collaboration",
-    getParentRoute: () => PageDocsApiRoute,
+    id: "/docs/api/collaboration",
+    path: "/docs/api/collaboration",
+    getParentRoute: () => PageRoute,
   } as any);
 const PageDocsApiComposerRoute = PageDocsApiComposerRouteImport.update({
-  id: "/composer",
-  path: "/composer",
-  getParentRoute: () => PageDocsApiRoute,
+  id: "/docs/api/composer",
+  path: "/docs/api/composer",
+  getParentRoute: () => PageRoute,
 } as any);
 const PageDocsApiComposerReactRoute =
   PageDocsApiComposerReactRouteImport.update({
-    id: "/composer-react",
-    path: "/composer-react",
-    getParentRoute: () => PageDocsApiRoute,
+    id: "/docs/api/composer-react",
+    path: "/docs/api/composer-react",
+    getParentRoute: () => PageRoute,
   } as any);
 const PageDocsApiContenteditableRoute =
   PageDocsApiContenteditableRouteImport.update({
-    id: "/contenteditable",
-    path: "/contenteditable",
-    getParentRoute: () => PageDocsApiRoute,
+    id: "/docs/api/contenteditable",
+    path: "/docs/api/contenteditable",
+    getParentRoute: () => PageRoute,
   } as any);
 const PageDocsApiContenteditableCollaborationRoute =
   PageDocsApiContenteditableCollaborationRouteImport.update({
-    id: "/contenteditable-collaboration",
-    path: "/contenteditable-collaboration",
-    getParentRoute: () => PageDocsApiRoute,
+    id: "/docs/api/contenteditable-collaboration",
+    path: "/docs/api/contenteditable-collaboration",
+    getParentRoute: () => PageRoute,
   } as any);
 const PageDocsApiDatabaseRoute = PageDocsApiDatabaseRouteImport.update({
-  id: "/database",
-  path: "/database",
-  getParentRoute: () => PageDocsApiRoute,
+  id: "/docs/api/database",
+  path: "/docs/api/database",
+  getParentRoute: () => PageRoute,
 } as any);
 const PageDocsApiEditingRoute = PageDocsApiEditingRouteImport.update({
-  id: "/editing",
-  path: "/editing",
-  getParentRoute: () => PageDocsApiRoute,
+  id: "/docs/api/editing",
+  path: "/docs/api/editing",
+  getParentRoute: () => PageRoute,
 } as any);
 const PageDocsApiFileIntakeRoute = PageDocsApiFileIntakeRouteImport.update({
-  id: "/file-intake",
-  path: "/file-intake",
-  getParentRoute: () => PageDocsApiRoute,
+  id: "/docs/api/file-intake",
+  path: "/docs/api/file-intake",
+  getParentRoute: () => PageRoute,
 } as any);
 const PageDocsApiJsonDocumentRoute = PageDocsApiJsonDocumentRouteImport.update({
-  id: "/json-document",
-  path: "/json-document",
-  getParentRoute: () => PageDocsApiRoute,
+  id: "/docs/api/json-document",
+  path: "/docs/api/json-document",
+  getParentRoute: () => PageRoute,
 } as any);
 const PageDocsApiMarkdownReactRoute =
   PageDocsApiMarkdownReactRouteImport.update({
-    id: "/markdown-react",
-    path: "/markdown-react",
-    getParentRoute: () => PageDocsApiRoute,
+    id: "/docs/api/markdown-react",
+    path: "/docs/api/markdown-react",
+    getParentRoute: () => PageRoute,
   } as any);
 const PageDocsApiReactRoute = PageDocsApiReactRouteImport.update({
-  id: "/react",
-  path: "/react",
-  getParentRoute: () => PageDocsApiRoute,
+  id: "/docs/api/react",
+  path: "/docs/api/react",
+  getParentRoute: () => PageRoute,
 } as any);
 const PageDocsApiReactHookFormRoute =
   PageDocsApiReactHookFormRouteImport.update({
-    id: "/react-hook-form",
-    path: "/react-hook-form",
-    getParentRoute: () => PageDocsApiRoute,
+    id: "/docs/api/react-hook-form",
+    path: "/docs/api/react-hook-form",
+    getParentRoute: () => PageRoute,
   } as any);
 const PageDocsApiRichTextRoute = PageDocsApiRichTextRouteImport.update({
-  id: "/rich-text",
-  path: "/rich-text",
-  getParentRoute: () => PageDocsApiRoute,
+  id: "/docs/api/rich-text",
+  path: "/docs/api/rich-text",
+  getParentRoute: () => PageRoute,
 } as any);
 const PageDocsApiRichTextMentionRoute =
   PageDocsApiRichTextMentionRouteImport.update({
-    id: "/rich-text-mention",
-    path: "/rich-text-mention",
-    getParentRoute: () => PageDocsApiRoute,
+    id: "/docs/api/rich-text-mention",
+    path: "/docs/api/rich-text-mention",
+    getParentRoute: () => PageRoute,
   } as any);
 const PageDocsApiRichTextMentionReactRoute =
   PageDocsApiRichTextMentionReactRouteImport.update({
-    id: "/rich-text-mention-react",
-    path: "/rich-text-mention-react",
-    getParentRoute: () => PageDocsApiRoute,
+    id: "/docs/api/rich-text-mention-react",
+    path: "/docs/api/rich-text-mention-react",
+    getParentRoute: () => PageRoute,
   } as any);
 const PageDocsApiRichTextReactRoute =
   PageDocsApiRichTextReactRouteImport.update({
-    id: "/rich-text-react",
-    path: "/rich-text-react",
-    getParentRoute: () => PageDocsApiRoute,
+    id: "/docs/api/rich-text-react",
+    path: "/docs/api/rich-text-react",
+    getParentRoute: () => PageRoute,
   } as any);
 const PageDocsApiRichTextSuggestionRoute =
   PageDocsApiRichTextSuggestionRouteImport.update({
-    id: "/rich-text-suggestion",
-    path: "/rich-text-suggestion",
-    getParentRoute: () => PageDocsApiRoute,
+    id: "/docs/api/rich-text-suggestion",
+    path: "/docs/api/rich-text-suggestion",
+    getParentRoute: () => PageRoute,
   } as any);
 const PageDocsApiRichTextSuggestionReactRoute =
   PageDocsApiRichTextSuggestionReactRouteImport.update({
-    id: "/rich-text-suggestion-react",
-    path: "/rich-text-suggestion-react",
-    getParentRoute: () => PageDocsApiRoute,
+    id: "/docs/api/rich-text-suggestion-react",
+    path: "/docs/api/rich-text-suggestion-react",
+    getParentRoute: () => PageRoute,
   } as any);
 const PageDocsApiRichTextWebRoute = PageDocsApiRichTextWebRouteImport.update({
-  id: "/rich-text-web",
-  path: "/rich-text-web",
-  getParentRoute: () => PageDocsApiRoute,
+  id: "/docs/api/rich-text-web",
+  path: "/docs/api/rich-text-web",
+  getParentRoute: () => PageRoute,
 } as any);
 const PageDocsApiSelectionRoute = PageDocsApiSelectionRouteImport.update({
-  id: "/selection",
-  path: "/selection",
-  getParentRoute: () => PageDocsApiRoute,
+  id: "/docs/api/selection",
+  path: "/docs/api/selection",
+  getParentRoute: () => PageRoute,
 } as any);
 const PageDocsApiTanstackTableRoute =
   PageDocsApiTanstackTableRouteImport.update({
-    id: "/tanstack-table",
-    path: "/tanstack-table",
-    getParentRoute: () => PageDocsApiRoute,
+    id: "/docs/api/tanstack-table",
+    path: "/docs/api/tanstack-table",
+    getParentRoute: () => PageRoute,
   } as any);
 const PageDocsApiUiPrimitivesReactRoute =
   PageDocsApiUiPrimitivesReactRouteImport.update({
-    id: "/ui-primitives-react",
-    path: "/ui-primitives-react",
-    getParentRoute: () => PageDocsApiRoute,
+    id: "/docs/api/ui-primitives-react",
+    path: "/docs/api/ui-primitives-react",
+    getParentRoute: () => PageRoute,
   } as any);
 const PageDocsApiWebRoute = PageDocsApiWebRouteImport.update({
-  id: "/web",
-  path: "/web",
-  getParentRoute: () => PageDocsApiRoute,
+  id: "/docs/api/web",
+  path: "/docs/api/web",
+  getParentRoute: () => PageRoute,
 } as any);
 const PageDocsApiZodRoute = PageDocsApiZodRouteImport.update({
-  id: "/zod",
-  path: "/zod",
-  getParentRoute: () => PageDocsApiRoute,
+  id: "/docs/api/zod",
+  path: "/docs/api/zod",
+  getParentRoute: () => PageRoute,
 } as any);
 const PageDocsCollaborationIndexRoute =
   PageDocsCollaborationIndexRouteImport.update({
@@ -1052,7 +1052,6 @@ export interface FileRoutesByFullPath {
   "/docs/adapter-virtual-selection": typeof PageDocsAdapterVirtualSelectionRoute;
   "/docs/adapters": typeof PageDocsAdaptersRoute;
   "/docs/animation": typeof PageDocsAnimationRoute;
-  "/docs/api": typeof PageDocsApiRouteWithChildren;
   "/docs/clipboard": typeof PageDocsClipboardRoute;
   "/docs/composer": typeof PageDocsComposerRoute;
   "/docs/concepts": typeof PageDocsConceptsRoute;
@@ -1158,6 +1157,7 @@ export interface FileRoutesByFullPath {
   "/docs/document-types/$candidate": typeof PageDocsDocumentTypesCandidateRoute;
   "/connectors/zod/": typeof PageConnectorsZodIndexRoute;
   "/docs/affordance/": typeof PageDocsAffordanceIndexRoute;
+  "/docs/api/": typeof PageDocsApiIndexRoute;
   "/docs/collaboration/": typeof PageDocsCollaborationIndexRoute;
   "/docs/document-types/": typeof PageDocsDocumentTypesIndexRoute;
   "/docs/collaboration/text/lease": typeof PageDocsCollaborationTextLeaseRoute;
@@ -1210,7 +1210,6 @@ export interface FileRoutesByTo {
   "/docs/adapter-virtual-selection": typeof PageDocsAdapterVirtualSelectionRoute;
   "/docs/adapters": typeof PageDocsAdaptersRoute;
   "/docs/animation": typeof PageDocsAnimationRoute;
-  "/docs/api": typeof PageDocsApiRouteWithChildren;
   "/docs/clipboard": typeof PageDocsClipboardRoute;
   "/docs/composer": typeof PageDocsComposerRoute;
   "/docs/concepts": typeof PageDocsConceptsRoute;
@@ -1316,6 +1315,7 @@ export interface FileRoutesByTo {
   "/docs/document-types/$candidate": typeof PageDocsDocumentTypesCandidateRoute;
   "/connectors/zod": typeof PageConnectorsZodIndexRoute;
   "/docs/affordance": typeof PageDocsAffordanceIndexRoute;
+  "/docs/api": typeof PageDocsApiIndexRoute;
   "/docs/collaboration": typeof PageDocsCollaborationIndexRoute;
   "/docs/document-types": typeof PageDocsDocumentTypesIndexRoute;
   "/docs/collaboration/text/lease": typeof PageDocsCollaborationTextLeaseRoute;
@@ -1370,7 +1370,6 @@ export interface FileRoutesById {
   "/_page/docs/adapter-virtual-selection": typeof PageDocsAdapterVirtualSelectionRoute;
   "/_page/docs/adapters": typeof PageDocsAdaptersRoute;
   "/_page/docs/animation": typeof PageDocsAnimationRoute;
-  "/_page/docs/api": typeof PageDocsApiRouteWithChildren;
   "/_page/docs/clipboard": typeof PageDocsClipboardRoute;
   "/_page/docs/composer": typeof PageDocsComposerRoute;
   "/_page/docs/concepts": typeof PageDocsConceptsRoute;
@@ -1476,6 +1475,7 @@ export interface FileRoutesById {
   "/_page/docs/document-types/$candidate": typeof PageDocsDocumentTypesCandidateRoute;
   "/_page/connectors/zod/": typeof PageConnectorsZodIndexRoute;
   "/_page/docs/affordance/": typeof PageDocsAffordanceIndexRoute;
+  "/_page/docs/api/": typeof PageDocsApiIndexRoute;
   "/_page/docs/collaboration/": typeof PageDocsCollaborationIndexRoute;
   "/_page/docs/document-types/": typeof PageDocsDocumentTypesIndexRoute;
   "/_page/docs/collaboration/text/lease": typeof PageDocsCollaborationTextLeaseRoute;
@@ -1530,7 +1530,6 @@ export interface FileRouteTypes {
     | "/docs/adapter-virtual-selection"
     | "/docs/adapters"
     | "/docs/animation"
-    | "/docs/api"
     | "/docs/clipboard"
     | "/docs/composer"
     | "/docs/concepts"
@@ -1636,6 +1635,7 @@ export interface FileRouteTypes {
     | "/docs/document-types/$candidate"
     | "/connectors/zod/"
     | "/docs/affordance/"
+    | "/docs/api/"
     | "/docs/collaboration/"
     | "/docs/document-types/"
     | "/docs/collaboration/text/lease"
@@ -1688,7 +1688,6 @@ export interface FileRouteTypes {
     | "/docs/adapter-virtual-selection"
     | "/docs/adapters"
     | "/docs/animation"
-    | "/docs/api"
     | "/docs/clipboard"
     | "/docs/composer"
     | "/docs/concepts"
@@ -1794,6 +1793,7 @@ export interface FileRouteTypes {
     | "/docs/document-types/$candidate"
     | "/connectors/zod"
     | "/docs/affordance"
+    | "/docs/api"
     | "/docs/collaboration"
     | "/docs/document-types"
     | "/docs/collaboration/text/lease"
@@ -1847,7 +1847,6 @@ export interface FileRouteTypes {
     | "/_page/docs/adapter-virtual-selection"
     | "/_page/docs/adapters"
     | "/_page/docs/animation"
-    | "/_page/docs/api"
     | "/_page/docs/clipboard"
     | "/_page/docs/composer"
     | "/_page/docs/concepts"
@@ -1953,6 +1952,7 @@ export interface FileRouteTypes {
     | "/_page/docs/document-types/$candidate"
     | "/_page/connectors/zod/"
     | "/_page/docs/affordance/"
+    | "/_page/docs/api/"
     | "/_page/docs/collaboration/"
     | "/_page/docs/document-types/"
     | "/_page/docs/collaboration/text/lease"
@@ -2330,13 +2330,6 @@ declare module "@tanstack/react-router" {
       preLoaderRoute: typeof PageDocsAnimationRouteImport;
       parentRoute: typeof PageRoute;
     };
-    "/_page/docs/api": {
-      id: "/_page/docs/api";
-      path: "/docs/api";
-      fullPath: "/docs/api";
-      preLoaderRoute: typeof PageDocsApiRouteImport;
-      parentRoute: typeof PageRoute;
-    };
     "/_page/docs/clipboard": {
       id: "/_page/docs/clipboard";
       path: "/docs/clipboard";
@@ -2799,215 +2792,222 @@ declare module "@tanstack/react-router" {
       preLoaderRoute: typeof PageDocsAffordanceZoomRouteImport;
       parentRoute: typeof PageRoute;
     };
+    "/_page/docs/api/": {
+      id: "/_page/docs/api/";
+      path: "/docs/api";
+      fullPath: "/docs/api/";
+      preLoaderRoute: typeof PageDocsApiIndexRouteImport;
+      parentRoute: typeof PageRoute;
+    };
     "/_page/docs/api/a2ui": {
       id: "/_page/docs/api/a2ui";
-      path: "/a2ui";
+      path: "/docs/api/a2ui";
       fullPath: "/docs/api/a2ui";
       preLoaderRoute: typeof PageDocsApiA2uiRouteImport;
-      parentRoute: typeof PageDocsApiRoute;
+      parentRoute: typeof PageRoute;
     };
     "/_page/docs/api/affordance": {
       id: "/_page/docs/api/affordance";
-      path: "/affordance";
+      path: "/docs/api/affordance";
       fullPath: "/docs/api/affordance";
       preLoaderRoute: typeof PageDocsApiAffordanceRouteImport;
-      parentRoute: typeof PageDocsApiRoute;
+      parentRoute: typeof PageRoute;
     };
     "/_page/docs/api/ajv": {
       id: "/_page/docs/api/ajv";
-      path: "/ajv";
+      path: "/docs/api/ajv";
       fullPath: "/docs/api/ajv";
       preLoaderRoute: typeof PageDocsApiAjvRouteImport;
-      parentRoute: typeof PageDocsApiRoute;
+      parentRoute: typeof PageRoute;
     };
     "/_page/docs/api/animation-react": {
       id: "/_page/docs/api/animation-react";
-      path: "/animation-react";
+      path: "/docs/api/animation-react";
       fullPath: "/docs/api/animation-react";
       preLoaderRoute: typeof PageDocsApiAnimationReactRouteImport;
-      parentRoute: typeof PageDocsApiRoute;
+      parentRoute: typeof PageRoute;
     };
     "/_page/docs/api/annotation": {
       id: "/_page/docs/api/annotation";
-      path: "/annotation";
+      path: "/docs/api/annotation";
       fullPath: "/docs/api/annotation";
       preLoaderRoute: typeof PageDocsApiAnnotationRouteImport;
-      parentRoute: typeof PageDocsApiRoute;
+      parentRoute: typeof PageRoute;
     };
     "/_page/docs/api/calendar": {
       id: "/_page/docs/api/calendar";
-      path: "/calendar";
+      path: "/docs/api/calendar";
       fullPath: "/docs/api/calendar";
       preLoaderRoute: typeof PageDocsApiCalendarRouteImport;
-      parentRoute: typeof PageDocsApiRoute;
+      parentRoute: typeof PageRoute;
     };
     "/_page/docs/api/collaboration": {
       id: "/_page/docs/api/collaboration";
-      path: "/collaboration";
+      path: "/docs/api/collaboration";
       fullPath: "/docs/api/collaboration";
       preLoaderRoute: typeof PageDocsApiCollaborationRouteImport;
-      parentRoute: typeof PageDocsApiRoute;
+      parentRoute: typeof PageRoute;
     };
     "/_page/docs/api/composer": {
       id: "/_page/docs/api/composer";
-      path: "/composer";
+      path: "/docs/api/composer";
       fullPath: "/docs/api/composer";
       preLoaderRoute: typeof PageDocsApiComposerRouteImport;
-      parentRoute: typeof PageDocsApiRoute;
+      parentRoute: typeof PageRoute;
     };
     "/_page/docs/api/composer-react": {
       id: "/_page/docs/api/composer-react";
-      path: "/composer-react";
+      path: "/docs/api/composer-react";
       fullPath: "/docs/api/composer-react";
       preLoaderRoute: typeof PageDocsApiComposerReactRouteImport;
-      parentRoute: typeof PageDocsApiRoute;
+      parentRoute: typeof PageRoute;
     };
     "/_page/docs/api/contenteditable": {
       id: "/_page/docs/api/contenteditable";
-      path: "/contenteditable";
+      path: "/docs/api/contenteditable";
       fullPath: "/docs/api/contenteditable";
       preLoaderRoute: typeof PageDocsApiContenteditableRouteImport;
-      parentRoute: typeof PageDocsApiRoute;
+      parentRoute: typeof PageRoute;
     };
     "/_page/docs/api/contenteditable-collaboration": {
       id: "/_page/docs/api/contenteditable-collaboration";
-      path: "/contenteditable-collaboration";
+      path: "/docs/api/contenteditable-collaboration";
       fullPath: "/docs/api/contenteditable-collaboration";
       preLoaderRoute: typeof PageDocsApiContenteditableCollaborationRouteImport;
-      parentRoute: typeof PageDocsApiRoute;
+      parentRoute: typeof PageRoute;
     };
     "/_page/docs/api/database": {
       id: "/_page/docs/api/database";
-      path: "/database";
+      path: "/docs/api/database";
       fullPath: "/docs/api/database";
       preLoaderRoute: typeof PageDocsApiDatabaseRouteImport;
-      parentRoute: typeof PageDocsApiRoute;
+      parentRoute: typeof PageRoute;
     };
     "/_page/docs/api/editing": {
       id: "/_page/docs/api/editing";
-      path: "/editing";
+      path: "/docs/api/editing";
       fullPath: "/docs/api/editing";
       preLoaderRoute: typeof PageDocsApiEditingRouteImport;
-      parentRoute: typeof PageDocsApiRoute;
+      parentRoute: typeof PageRoute;
     };
     "/_page/docs/api/file-intake": {
       id: "/_page/docs/api/file-intake";
-      path: "/file-intake";
+      path: "/docs/api/file-intake";
       fullPath: "/docs/api/file-intake";
       preLoaderRoute: typeof PageDocsApiFileIntakeRouteImport;
-      parentRoute: typeof PageDocsApiRoute;
+      parentRoute: typeof PageRoute;
     };
     "/_page/docs/api/json-document": {
       id: "/_page/docs/api/json-document";
-      path: "/json-document";
+      path: "/docs/api/json-document";
       fullPath: "/docs/api/json-document";
       preLoaderRoute: typeof PageDocsApiJsonDocumentRouteImport;
-      parentRoute: typeof PageDocsApiRoute;
+      parentRoute: typeof PageRoute;
     };
     "/_page/docs/api/markdown-react": {
       id: "/_page/docs/api/markdown-react";
-      path: "/markdown-react";
+      path: "/docs/api/markdown-react";
       fullPath: "/docs/api/markdown-react";
       preLoaderRoute: typeof PageDocsApiMarkdownReactRouteImport;
-      parentRoute: typeof PageDocsApiRoute;
+      parentRoute: typeof PageRoute;
     };
     "/_page/docs/api/react": {
       id: "/_page/docs/api/react";
-      path: "/react";
+      path: "/docs/api/react";
       fullPath: "/docs/api/react";
       preLoaderRoute: typeof PageDocsApiReactRouteImport;
-      parentRoute: typeof PageDocsApiRoute;
+      parentRoute: typeof PageRoute;
     };
     "/_page/docs/api/react-hook-form": {
       id: "/_page/docs/api/react-hook-form";
-      path: "/react-hook-form";
+      path: "/docs/api/react-hook-form";
       fullPath: "/docs/api/react-hook-form";
       preLoaderRoute: typeof PageDocsApiReactHookFormRouteImport;
-      parentRoute: typeof PageDocsApiRoute;
+      parentRoute: typeof PageRoute;
     };
     "/_page/docs/api/rich-text": {
       id: "/_page/docs/api/rich-text";
-      path: "/rich-text";
+      path: "/docs/api/rich-text";
       fullPath: "/docs/api/rich-text";
       preLoaderRoute: typeof PageDocsApiRichTextRouteImport;
-      parentRoute: typeof PageDocsApiRoute;
+      parentRoute: typeof PageRoute;
     };
     "/_page/docs/api/rich-text-mention": {
       id: "/_page/docs/api/rich-text-mention";
-      path: "/rich-text-mention";
+      path: "/docs/api/rich-text-mention";
       fullPath: "/docs/api/rich-text-mention";
       preLoaderRoute: typeof PageDocsApiRichTextMentionRouteImport;
-      parentRoute: typeof PageDocsApiRoute;
+      parentRoute: typeof PageRoute;
     };
     "/_page/docs/api/rich-text-mention-react": {
       id: "/_page/docs/api/rich-text-mention-react";
-      path: "/rich-text-mention-react";
+      path: "/docs/api/rich-text-mention-react";
       fullPath: "/docs/api/rich-text-mention-react";
       preLoaderRoute: typeof PageDocsApiRichTextMentionReactRouteImport;
-      parentRoute: typeof PageDocsApiRoute;
+      parentRoute: typeof PageRoute;
     };
     "/_page/docs/api/rich-text-react": {
       id: "/_page/docs/api/rich-text-react";
-      path: "/rich-text-react";
+      path: "/docs/api/rich-text-react";
       fullPath: "/docs/api/rich-text-react";
       preLoaderRoute: typeof PageDocsApiRichTextReactRouteImport;
-      parentRoute: typeof PageDocsApiRoute;
+      parentRoute: typeof PageRoute;
     };
     "/_page/docs/api/rich-text-suggestion": {
       id: "/_page/docs/api/rich-text-suggestion";
-      path: "/rich-text-suggestion";
+      path: "/docs/api/rich-text-suggestion";
       fullPath: "/docs/api/rich-text-suggestion";
       preLoaderRoute: typeof PageDocsApiRichTextSuggestionRouteImport;
-      parentRoute: typeof PageDocsApiRoute;
+      parentRoute: typeof PageRoute;
     };
     "/_page/docs/api/rich-text-suggestion-react": {
       id: "/_page/docs/api/rich-text-suggestion-react";
-      path: "/rich-text-suggestion-react";
+      path: "/docs/api/rich-text-suggestion-react";
       fullPath: "/docs/api/rich-text-suggestion-react";
       preLoaderRoute: typeof PageDocsApiRichTextSuggestionReactRouteImport;
-      parentRoute: typeof PageDocsApiRoute;
+      parentRoute: typeof PageRoute;
     };
     "/_page/docs/api/rich-text-web": {
       id: "/_page/docs/api/rich-text-web";
-      path: "/rich-text-web";
+      path: "/docs/api/rich-text-web";
       fullPath: "/docs/api/rich-text-web";
       preLoaderRoute: typeof PageDocsApiRichTextWebRouteImport;
-      parentRoute: typeof PageDocsApiRoute;
+      parentRoute: typeof PageRoute;
     };
     "/_page/docs/api/selection": {
       id: "/_page/docs/api/selection";
-      path: "/selection";
+      path: "/docs/api/selection";
       fullPath: "/docs/api/selection";
       preLoaderRoute: typeof PageDocsApiSelectionRouteImport;
-      parentRoute: typeof PageDocsApiRoute;
+      parentRoute: typeof PageRoute;
     };
     "/_page/docs/api/tanstack-table": {
       id: "/_page/docs/api/tanstack-table";
-      path: "/tanstack-table";
+      path: "/docs/api/tanstack-table";
       fullPath: "/docs/api/tanstack-table";
       preLoaderRoute: typeof PageDocsApiTanstackTableRouteImport;
-      parentRoute: typeof PageDocsApiRoute;
+      parentRoute: typeof PageRoute;
     };
     "/_page/docs/api/ui-primitives-react": {
       id: "/_page/docs/api/ui-primitives-react";
-      path: "/ui-primitives-react";
+      path: "/docs/api/ui-primitives-react";
       fullPath: "/docs/api/ui-primitives-react";
       preLoaderRoute: typeof PageDocsApiUiPrimitivesReactRouteImport;
-      parentRoute: typeof PageDocsApiRoute;
+      parentRoute: typeof PageRoute;
     };
     "/_page/docs/api/web": {
       id: "/_page/docs/api/web";
-      path: "/web";
+      path: "/docs/api/web";
       fullPath: "/docs/api/web";
       preLoaderRoute: typeof PageDocsApiWebRouteImport;
-      parentRoute: typeof PageDocsApiRoute;
+      parentRoute: typeof PageRoute;
     };
     "/_page/docs/api/zod": {
       id: "/_page/docs/api/zod";
-      path: "/zod";
+      path: "/docs/api/zod";
       fullPath: "/docs/api/zod";
       preLoaderRoute: typeof PageDocsApiZodRouteImport;
-      parentRoute: typeof PageDocsApiRoute;
+      parentRoute: typeof PageRoute;
     };
     "/_page/docs/collaboration/": {
       id: "/_page/docs/collaboration/";
@@ -3068,78 +3068,6 @@ declare module "@tanstack/react-router" {
   }
 }
 
-interface PageDocsApiRouteChildren {
-  PageDocsApiA2uiRoute: typeof PageDocsApiA2uiRoute;
-  PageDocsApiAffordanceRoute: typeof PageDocsApiAffordanceRoute;
-  PageDocsApiAjvRoute: typeof PageDocsApiAjvRoute;
-  PageDocsApiAnimationReactRoute: typeof PageDocsApiAnimationReactRoute;
-  PageDocsApiAnnotationRoute: typeof PageDocsApiAnnotationRoute;
-  PageDocsApiCalendarRoute: typeof PageDocsApiCalendarRoute;
-  PageDocsApiCollaborationRoute: typeof PageDocsApiCollaborationRoute;
-  PageDocsApiComposerRoute: typeof PageDocsApiComposerRoute;
-  PageDocsApiComposerReactRoute: typeof PageDocsApiComposerReactRoute;
-  PageDocsApiContenteditableRoute: typeof PageDocsApiContenteditableRoute;
-  PageDocsApiContenteditableCollaborationRoute: typeof PageDocsApiContenteditableCollaborationRoute;
-  PageDocsApiDatabaseRoute: typeof PageDocsApiDatabaseRoute;
-  PageDocsApiEditingRoute: typeof PageDocsApiEditingRoute;
-  PageDocsApiFileIntakeRoute: typeof PageDocsApiFileIntakeRoute;
-  PageDocsApiJsonDocumentRoute: typeof PageDocsApiJsonDocumentRoute;
-  PageDocsApiMarkdownReactRoute: typeof PageDocsApiMarkdownReactRoute;
-  PageDocsApiReactRoute: typeof PageDocsApiReactRoute;
-  PageDocsApiReactHookFormRoute: typeof PageDocsApiReactHookFormRoute;
-  PageDocsApiRichTextRoute: typeof PageDocsApiRichTextRoute;
-  PageDocsApiRichTextMentionRoute: typeof PageDocsApiRichTextMentionRoute;
-  PageDocsApiRichTextMentionReactRoute: typeof PageDocsApiRichTextMentionReactRoute;
-  PageDocsApiRichTextReactRoute: typeof PageDocsApiRichTextReactRoute;
-  PageDocsApiRichTextSuggestionRoute: typeof PageDocsApiRichTextSuggestionRoute;
-  PageDocsApiRichTextSuggestionReactRoute: typeof PageDocsApiRichTextSuggestionReactRoute;
-  PageDocsApiRichTextWebRoute: typeof PageDocsApiRichTextWebRoute;
-  PageDocsApiSelectionRoute: typeof PageDocsApiSelectionRoute;
-  PageDocsApiTanstackTableRoute: typeof PageDocsApiTanstackTableRoute;
-  PageDocsApiUiPrimitivesReactRoute: typeof PageDocsApiUiPrimitivesReactRoute;
-  PageDocsApiWebRoute: typeof PageDocsApiWebRoute;
-  PageDocsApiZodRoute: typeof PageDocsApiZodRoute;
-}
-
-const PageDocsApiRouteChildren: PageDocsApiRouteChildren = {
-  PageDocsApiA2uiRoute: PageDocsApiA2uiRoute,
-  PageDocsApiAffordanceRoute: PageDocsApiAffordanceRoute,
-  PageDocsApiAjvRoute: PageDocsApiAjvRoute,
-  PageDocsApiAnimationReactRoute: PageDocsApiAnimationReactRoute,
-  PageDocsApiAnnotationRoute: PageDocsApiAnnotationRoute,
-  PageDocsApiCalendarRoute: PageDocsApiCalendarRoute,
-  PageDocsApiCollaborationRoute: PageDocsApiCollaborationRoute,
-  PageDocsApiComposerRoute: PageDocsApiComposerRoute,
-  PageDocsApiComposerReactRoute: PageDocsApiComposerReactRoute,
-  PageDocsApiContenteditableRoute: PageDocsApiContenteditableRoute,
-  PageDocsApiContenteditableCollaborationRoute:
-    PageDocsApiContenteditableCollaborationRoute,
-  PageDocsApiDatabaseRoute: PageDocsApiDatabaseRoute,
-  PageDocsApiEditingRoute: PageDocsApiEditingRoute,
-  PageDocsApiFileIntakeRoute: PageDocsApiFileIntakeRoute,
-  PageDocsApiJsonDocumentRoute: PageDocsApiJsonDocumentRoute,
-  PageDocsApiMarkdownReactRoute: PageDocsApiMarkdownReactRoute,
-  PageDocsApiReactRoute: PageDocsApiReactRoute,
-  PageDocsApiReactHookFormRoute: PageDocsApiReactHookFormRoute,
-  PageDocsApiRichTextRoute: PageDocsApiRichTextRoute,
-  PageDocsApiRichTextMentionRoute: PageDocsApiRichTextMentionRoute,
-  PageDocsApiRichTextMentionReactRoute: PageDocsApiRichTextMentionReactRoute,
-  PageDocsApiRichTextReactRoute: PageDocsApiRichTextReactRoute,
-  PageDocsApiRichTextSuggestionRoute: PageDocsApiRichTextSuggestionRoute,
-  PageDocsApiRichTextSuggestionReactRoute:
-    PageDocsApiRichTextSuggestionReactRoute,
-  PageDocsApiRichTextWebRoute: PageDocsApiRichTextWebRoute,
-  PageDocsApiSelectionRoute: PageDocsApiSelectionRoute,
-  PageDocsApiTanstackTableRoute: PageDocsApiTanstackTableRoute,
-  PageDocsApiUiPrimitivesReactRoute: PageDocsApiUiPrimitivesReactRoute,
-  PageDocsApiWebRoute: PageDocsApiWebRoute,
-  PageDocsApiZodRoute: PageDocsApiZodRoute,
-};
-
-const PageDocsApiRouteWithChildren = PageDocsApiRoute._addFileChildren(
-  PageDocsApiRouteChildren,
-);
-
 interface PageRouteChildren {
   PageDemosRoute: typeof PageDemosRoute;
   PageEditorsRoute: typeof PageEditorsRoute;
@@ -3186,7 +3114,6 @@ interface PageRouteChildren {
   PageDocsAdapterVirtualSelectionRoute: typeof PageDocsAdapterVirtualSelectionRoute;
   PageDocsAdaptersRoute: typeof PageDocsAdaptersRoute;
   PageDocsAnimationRoute: typeof PageDocsAnimationRoute;
-  PageDocsApiRoute: typeof PageDocsApiRouteWithChildren;
   PageDocsClipboardRoute: typeof PageDocsClipboardRoute;
   PageDocsComposerRoute: typeof PageDocsComposerRoute;
   PageDocsConceptsRoute: typeof PageDocsConceptsRoute;
@@ -3256,12 +3183,43 @@ interface PageRouteChildren {
   PageDocsAffordanceTripleClickRoute: typeof PageDocsAffordanceTripleClickRoute;
   PageDocsAffordanceTypeaheadRoute: typeof PageDocsAffordanceTypeaheadRoute;
   PageDocsAffordanceZoomRoute: typeof PageDocsAffordanceZoomRoute;
+  PageDocsApiA2uiRoute: typeof PageDocsApiA2uiRoute;
+  PageDocsApiAffordanceRoute: typeof PageDocsApiAffordanceRoute;
+  PageDocsApiAjvRoute: typeof PageDocsApiAjvRoute;
+  PageDocsApiAnimationReactRoute: typeof PageDocsApiAnimationReactRoute;
+  PageDocsApiAnnotationRoute: typeof PageDocsApiAnnotationRoute;
+  PageDocsApiCalendarRoute: typeof PageDocsApiCalendarRoute;
+  PageDocsApiCollaborationRoute: typeof PageDocsApiCollaborationRoute;
+  PageDocsApiComposerRoute: typeof PageDocsApiComposerRoute;
+  PageDocsApiComposerReactRoute: typeof PageDocsApiComposerReactRoute;
+  PageDocsApiContenteditableRoute: typeof PageDocsApiContenteditableRoute;
+  PageDocsApiContenteditableCollaborationRoute: typeof PageDocsApiContenteditableCollaborationRoute;
+  PageDocsApiDatabaseRoute: typeof PageDocsApiDatabaseRoute;
+  PageDocsApiEditingRoute: typeof PageDocsApiEditingRoute;
+  PageDocsApiFileIntakeRoute: typeof PageDocsApiFileIntakeRoute;
+  PageDocsApiJsonDocumentRoute: typeof PageDocsApiJsonDocumentRoute;
+  PageDocsApiMarkdownReactRoute: typeof PageDocsApiMarkdownReactRoute;
+  PageDocsApiReactRoute: typeof PageDocsApiReactRoute;
+  PageDocsApiReactHookFormRoute: typeof PageDocsApiReactHookFormRoute;
+  PageDocsApiRichTextRoute: typeof PageDocsApiRichTextRoute;
+  PageDocsApiRichTextMentionRoute: typeof PageDocsApiRichTextMentionRoute;
+  PageDocsApiRichTextMentionReactRoute: typeof PageDocsApiRichTextMentionReactRoute;
+  PageDocsApiRichTextReactRoute: typeof PageDocsApiRichTextReactRoute;
+  PageDocsApiRichTextSuggestionRoute: typeof PageDocsApiRichTextSuggestionRoute;
+  PageDocsApiRichTextSuggestionReactRoute: typeof PageDocsApiRichTextSuggestionReactRoute;
+  PageDocsApiRichTextWebRoute: typeof PageDocsApiRichTextWebRoute;
+  PageDocsApiSelectionRoute: typeof PageDocsApiSelectionRoute;
+  PageDocsApiTanstackTableRoute: typeof PageDocsApiTanstackTableRoute;
+  PageDocsApiUiPrimitivesReactRoute: typeof PageDocsApiUiPrimitivesReactRoute;
+  PageDocsApiWebRoute: typeof PageDocsApiWebRoute;
+  PageDocsApiZodRoute: typeof PageDocsApiZodRoute;
   PageDocsCollaborationHistoryRoute: typeof PageDocsCollaborationHistoryRoute;
   PageDocsCollaborationLifecycleRoute: typeof PageDocsCollaborationLifecycleRoute;
   PageDocsCollaborationReplicaRoute: typeof PageDocsCollaborationReplicaRoute;
   PageDocsDocumentTypesCandidateRoute: typeof PageDocsDocumentTypesCandidateRoute;
   PageConnectorsZodIndexRoute: typeof PageConnectorsZodIndexRoute;
   PageDocsAffordanceIndexRoute: typeof PageDocsAffordanceIndexRoute;
+  PageDocsApiIndexRoute: typeof PageDocsApiIndexRoute;
   PageDocsCollaborationIndexRoute: typeof PageDocsCollaborationIndexRoute;
   PageDocsDocumentTypesIndexRoute: typeof PageDocsDocumentTypesIndexRoute;
   PageDocsCollaborationTextLeaseRoute: typeof PageDocsCollaborationTextLeaseRoute;
@@ -3314,7 +3272,6 @@ const PageRouteChildren: PageRouteChildren = {
   PageDocsAdapterVirtualSelectionRoute: PageDocsAdapterVirtualSelectionRoute,
   PageDocsAdaptersRoute: PageDocsAdaptersRoute,
   PageDocsAnimationRoute: PageDocsAnimationRoute,
-  PageDocsApiRoute: PageDocsApiRouteWithChildren,
   PageDocsClipboardRoute: PageDocsClipboardRoute,
   PageDocsComposerRoute: PageDocsComposerRoute,
   PageDocsConceptsRoute: PageDocsConceptsRoute,
@@ -3384,12 +3341,45 @@ const PageRouteChildren: PageRouteChildren = {
   PageDocsAffordanceTripleClickRoute: PageDocsAffordanceTripleClickRoute,
   PageDocsAffordanceTypeaheadRoute: PageDocsAffordanceTypeaheadRoute,
   PageDocsAffordanceZoomRoute: PageDocsAffordanceZoomRoute,
+  PageDocsApiA2uiRoute: PageDocsApiA2uiRoute,
+  PageDocsApiAffordanceRoute: PageDocsApiAffordanceRoute,
+  PageDocsApiAjvRoute: PageDocsApiAjvRoute,
+  PageDocsApiAnimationReactRoute: PageDocsApiAnimationReactRoute,
+  PageDocsApiAnnotationRoute: PageDocsApiAnnotationRoute,
+  PageDocsApiCalendarRoute: PageDocsApiCalendarRoute,
+  PageDocsApiCollaborationRoute: PageDocsApiCollaborationRoute,
+  PageDocsApiComposerRoute: PageDocsApiComposerRoute,
+  PageDocsApiComposerReactRoute: PageDocsApiComposerReactRoute,
+  PageDocsApiContenteditableRoute: PageDocsApiContenteditableRoute,
+  PageDocsApiContenteditableCollaborationRoute:
+    PageDocsApiContenteditableCollaborationRoute,
+  PageDocsApiDatabaseRoute: PageDocsApiDatabaseRoute,
+  PageDocsApiEditingRoute: PageDocsApiEditingRoute,
+  PageDocsApiFileIntakeRoute: PageDocsApiFileIntakeRoute,
+  PageDocsApiJsonDocumentRoute: PageDocsApiJsonDocumentRoute,
+  PageDocsApiMarkdownReactRoute: PageDocsApiMarkdownReactRoute,
+  PageDocsApiReactRoute: PageDocsApiReactRoute,
+  PageDocsApiReactHookFormRoute: PageDocsApiReactHookFormRoute,
+  PageDocsApiRichTextRoute: PageDocsApiRichTextRoute,
+  PageDocsApiRichTextMentionRoute: PageDocsApiRichTextMentionRoute,
+  PageDocsApiRichTextMentionReactRoute: PageDocsApiRichTextMentionReactRoute,
+  PageDocsApiRichTextReactRoute: PageDocsApiRichTextReactRoute,
+  PageDocsApiRichTextSuggestionRoute: PageDocsApiRichTextSuggestionRoute,
+  PageDocsApiRichTextSuggestionReactRoute:
+    PageDocsApiRichTextSuggestionReactRoute,
+  PageDocsApiRichTextWebRoute: PageDocsApiRichTextWebRoute,
+  PageDocsApiSelectionRoute: PageDocsApiSelectionRoute,
+  PageDocsApiTanstackTableRoute: PageDocsApiTanstackTableRoute,
+  PageDocsApiUiPrimitivesReactRoute: PageDocsApiUiPrimitivesReactRoute,
+  PageDocsApiWebRoute: PageDocsApiWebRoute,
+  PageDocsApiZodRoute: PageDocsApiZodRoute,
   PageDocsCollaborationHistoryRoute: PageDocsCollaborationHistoryRoute,
   PageDocsCollaborationLifecycleRoute: PageDocsCollaborationLifecycleRoute,
   PageDocsCollaborationReplicaRoute: PageDocsCollaborationReplicaRoute,
   PageDocsDocumentTypesCandidateRoute: PageDocsDocumentTypesCandidateRoute,
   PageConnectorsZodIndexRoute: PageConnectorsZodIndexRoute,
   PageDocsAffordanceIndexRoute: PageDocsAffordanceIndexRoute,
+  PageDocsApiIndexRoute: PageDocsApiIndexRoute,
   PageDocsCollaborationIndexRoute: PageDocsCollaborationIndexRoute,
   PageDocsDocumentTypesIndexRoute: PageDocsDocumentTypesIndexRoute,
   PageDocsCollaborationTextLeaseRoute: PageDocsCollaborationTextLeaseRoute,
diff --git a/site/src/app/routes/_page/docs/api.tsx b/site/src/app/routes/_page/docs/api.tsx
deleted file mode 100644
index efaf4142..00000000
--- a/site/src/app/routes/_page/docs/api.tsx
+++ /dev/null
@@ -1,6 +0,0 @@
-import { createFileRoute } from "@tanstack/react-router";
-import { ApiReferenceRoute } from "../../../../routes/docs/DocsRoute";
-
-export const Route = createFileRoute("/_page/docs/api")({
-  component: ApiReferenceRoute,
-});
diff --git a/site/src/app/routes/_page/docs/api/index.tsx b/site/src/app/routes/_page/docs/api/index.tsx
new file mode 100644
index 00000000..95c6d7b3
--- /dev/null
+++ b/site/src/app/routes/_page/docs/api/index.tsx
@@ -0,0 +1,6 @@
+import { createFileRoute } from "@tanstack/react-router";
+import { ApiReferenceRoute } from "../../../../../routes/docs/DocsRoute";
+
+export const Route = createFileRoute("/_page/docs/api/")({
+  component: ApiReferenceRoute,
+});
diff --git a/site/src/routes/calendar-demo/CalendarDemoRoute.tsx b/site/src/routes/calendar-demo/CalendarDemoRoute.tsx
index 05417e82..55e1daf0 100644
--- a/site/src/routes/calendar-demo/CalendarDemoRoute.tsx
+++ b/site/src/routes/calendar-demo/CalendarDemoRoute.tsx
@@ -132,16 +132,18 @@ export function CalendarDemoRoute(props: {
       initialEventIds: [],
     });
   });
+  const [errorCode, setErrorCode] = useState<string | null>(null);
   const hand = useCalendarHand(editor, {
     initialOccurrence: { start: null, end: null },
     defaultTitle: "Event",
+    onResult: (result) => setErrorCode(result.ok ? null : result.code),
   });
   const clipboard = createWebClipboardSurface({
     codec: createWebJSONClipboardRepresentation(calendarClipboardFormat),
     read: hand.copy,
     cut: hand.cut,
     paste: hand.paste,
-    onResult: () => {},
+    onResult: (result) => { if (result.ok) setErrorCode(null); else if (result.code !== "editing.rejected") setErrorCode(result.code); },
   });
   const [viewState, setViewState] = useState<CalendarView>(calendarSearchDefaults.view);
   const [visibleDateState, setVisibleDateState] = useState(calendarSearchDefaults.date);
@@ -404,6 +406,9 @@ export function CalendarDemoRoute(props: {
       >
         <div className="relative flex h-full min-h-0 min-w-0 flex-col">
           <div className={styles.controlLayer()}>
+            {errorCode === null ? null : <p role="alert" className={classes("absolute bottom-20 left-4 right-4 m-0", ui.text.meta)}>
+              변경하지 못했습니다. 선택과 입력을 확인한 뒤 다시 시도하세요. ({errorCode})
+            </p>}
             {eventInspectorVisible ? <CalendarEventInspector
               hand={hand}
               calendars={calendars}
diff --git a/site/src/routes/docs/doc-pages.ts b/site/src/routes/docs/doc-pages.ts
index 45bf72af..ec4689ed 100644
--- a/site/src/routes/docs/doc-pages.ts
+++ b/site/src/routes/docs/doc-pages.ts
@@ -2,6 +2,7 @@ import apiReferenceMarkdown from "../../../../docs/public/api.md?raw";
 import jsonDocumentApiMarkdown from "../../../../docs/api-reference/json-document.md?raw";
 import selectionApiMarkdown from "../../../../docs/api-reference/selection.md?raw";
 import editingApiMarkdown from "../../../../docs/api-reference/editing.md?raw";
+import calendarProfileMarkdown from "../../../../packages/json-document-editing/docs/calendar-profile.md?raw";
 import reactApiMarkdown from "../../../../docs/api-reference/react.md?raw";
 import reactHookFormApiMarkdown from "../../../../docs/api-reference/react-hook-form.md?raw";
 import ajvApiMarkdown from "../../../../docs/api-reference/ajv.md?raw";
@@ -176,7 +177,7 @@ export const docPages = {
   api: docPage("/docs/api", apiReferenceMarkdown),
   jsonDocumentApi: docPage("/docs/api/json-document", jsonDocumentApiMarkdown),
   selectionApi: docPage("/docs/api/selection", selectionApiMarkdown),
-  editingApi: docPage("/docs/api/editing", editingApiMarkdown),
+  editingApi: docPage("/docs/api/editing", `${editingApiMarkdown}\n\n${calendarProfileMarkdown}`),
   reactApi: docPage("/docs/api/react", reactApiMarkdown),
   reactHookFormApi: docPage("/docs/api/react-hook-form", reactHookFormApiMarkdown),
   ajvApi: docPage("/docs/api/ajv", ajvApiMarkdown),
@@ -190,7 +191,7 @@ export const docPages = {
   markdownReactApi: docPage("/docs/api/markdown-react", markdownReactApiMarkdown),
   databaseApi: docPage("/docs/api/database", databaseApiMarkdown),
   annotationApi: docPage("/docs/api/annotation", annotationApiMarkdown),
-  calendarApi: docPage("/docs/api/calendar", calendarApiMarkdown),
+  calendarApi: docPage("/docs/api/calendar", `[시간·반복·거절 계약: Editing의 Calendar protocol profile](/docs/api/editing#calendar-protocol-profile-rc)\n\n${calendarApiMarkdown}`),
   webApi: docPage("/docs/api/web", webApiMarkdown),
   contenteditableApi: docPage("/docs/api/contenteditable", contenteditableApiMarkdown),
   richTextApi: docPage("/docs/api/rich-text", richTextApiMarkdown),
diff --git a/site/src/shared/demo-workbench/demo-sources.ts b/site/src/shared/demo-workbench/demo-sources.ts
index 1caa785d..930f514a 100644
--- a/site/src/shared/demo-workbench/demo-sources.ts
+++ b/site/src/shared/demo-workbench/demo-sources.ts
@@ -2,6 +2,7 @@ import type { CodeLanguage } from "../ui/code-tokens";
 import pointerTrackingSource from "../../../../packages/json-document/src/foundation/patch/track.ts?raw";
 import editingObservationSource from "../../../../packages/json-document-react/src/editing-observation.ts?raw";
 import calendarEditingSource from "../../../../packages/json-document-editing/src/calendar.ts?raw";
+import calendarEventPlanSource from "../../../../packages/json-document-editing/src/calendar-event-plan.ts?raw";
 import calendarAllDayPointerSource from "../../../../packages/json-document-editing/src/calendar-allday-pointer.ts?raw";
 import calendarMonthPointerSource from "../../../../packages/json-document-editing/src/calendar-month-pointer.ts?raw";
 import calendarTimeGridPointerSource from "../../../../packages/json-document-editing/src/calendar-time-grid-pointer.ts?raw";
@@ -140,6 +141,7 @@ const packageReferencePaths = new Map([
   ["packages/json-document/", "/docs/api/json-document"],
   ["packages/json-document-selection/", "/docs/api/selection"],
   ["packages/json-document-editing/", "/docs/api/editing"],
+  ["packages/json-document-calendar/", "/docs/api/calendar"],
   ["packages/json-document-react/", "/docs/api/react"],
   ["packages/json-document-react-hook-form/", "/docs/api/react-hook-form"],
   ["packages/json-document-ajv/", "/docs/api/ajv"],
@@ -192,6 +194,7 @@ const registeredUsageSources = new Map<string, string>([
   ["packages/json-document-editing/src/calendar-time-grid-pointer.ts", calendarTimeGridPointerSource],
   ["packages/json-document-editing/src/calendar-occurrence.ts", calendarOccurrenceSource],
   ["packages/json-document-editing/src/calendar-preview.ts", calendarPreviewSource],
+  ["packages/json-document-editing/src/calendar-event-plan.ts", calendarEventPlanSource],
   ["packages/json-document-editing/src/calendar-selection.ts", calendarSelectionSource],
   ["packages/json-document-editing/src/calendar-selection-move.ts", calendarSelectionMoveSource],
   ["packages/json-document-editing/src/calendar-validation.ts", calendarValidationSource],
@@ -396,6 +399,11 @@ const registeredPublicUsages = [
     symbol: "createCalendarEditor",
     sourcePath: "packages/json-document-editing/src/calendar.ts",
   },
+  {
+    packageName: "@interactive-os/json-document-editing",
+    symbol: "createCalendarEditor",
+    sourcePath: "packages/json-document-editing/src/calendar-event-plan.ts",
+  },
   {
     packageName: "@interactive-os/json-document-editing",
     symbol: "calendarOccurrenceTopology",
diff --git a/site/tests/unit/demo-workbench.test.tsx b/site/tests/unit/demo-workbench.test.tsx
index c90d3d57..5f10bc4b 100644
--- a/site/tests/unit/demo-workbench.test.tsx
+++ b/site/tests/unit/demo-workbench.test.tsx
@@ -55,6 +55,16 @@ describe("DemoWorkbench", () => {
 });
 
 describe("Demo definition and source discovery", () => {
+  test("Calendar Usage exposes the shared edit plan and each canonical owner's API", async () => {
+    const sources = await discoverDemoSources("routes/calendar-demo/CalendarDemoRoute.tsx");
+    const plan = sources.find((file) => file.path === "packages/json-document-editing/src/calendar-event-plan.ts");
+    expect(plan?.referencePath).toBe("/docs/api/editing");
+    expect(await plan!.load()).toContain("export function planCalendarEventEdit");
+    const hand = sources.find((file) => file.path === "packages/json-document-calendar/src/use-calendar-hand.ts");
+    expect(hand?.referencePath).toBe("/docs/api/calendar");
+    expect(await hand!.load()).toContain("export function useCalendarHand");
+  });
+
   test("exercises and exposes the canonical ID allocator in Clipboard Usage", async () => {
     const hook = renderHook(useClipboardLab);
     act(() => { hook.result.current.copy(); });
diff --git a/site/tests/unit/docs-route.test.tsx b/site/tests/unit/docs-route.test.tsx
index c4868ead..25ba3992 100644
--- a/site/tests/unit/docs-route.test.tsx
+++ b/site/tests/unit/docs-route.test.tsx
@@ -14,12 +14,33 @@ beforeEach(() => {
     '<link rel="canonical" href="" />',
   ].join("");
   Object.defineProperty(window, "scrollTo", { configurable: true, value: vi.fn() });
+  Object.defineProperty(Element.prototype, "scrollIntoView", { configurable: true, value: vi.fn() });
   window.history.pushState(null, "", "/");
 });
 
 afterEach(cleanup);
 
 describe("documentation routes", () => {
+  test("renders package APIs and the Calendar profile without the API index masking them", async () => {
+    window.history.pushState(null, "", "/docs/api/editing#calendar-protocol-profile-rc");
+    render(<App />);
+
+    expect(await screen.findByRole("heading", { level: 1, name: "API · Editing" }, { timeout: 10000 })).toBeTruthy();
+    expect(screen.getByRole("heading", { level: 2, name: "Calendar protocol profile (RC)" }).id).toBe("calendar-protocol-profile-rc");
+    expect(screen.queryByRole("heading", { level: 1, name: "json-document API" })).toBeNull();
+
+    window.history.pushState(null, "", "/docs/api/calendar");
+    window.dispatchEvent(new Event("popstate"));
+    expect(await screen.findByRole("heading", { level: 1, name: "API · Calendar" }, { timeout: 10000 })).toBeTruthy();
+    expect(screen.getByRole("link", { name: "시간·반복·거절 계약: Editing의 Calendar protocol profile" }).getAttribute("href"))
+      .toBe("/docs/api/editing#calendar-protocol-profile-rc");
+
+    window.history.pushState(null, "", "/docs/api");
+    window.dispatchEvent(new Event("popstate"));
+    expect(await screen.findByRole("heading", { level: 1, name: "json-document API" }, { timeout: 10000 })).toBeTruthy();
+    expect(screen.queryByRole("heading", { level: 2, name: "Calendar protocol profile (RC)" })).toBeNull();
+  }, 15000);
+
   test("navigates across the keyed documentation registry", async () => {
     render(<App />);
     const user = userEvent.setup();

From 1c9351dbcb9d7bd8a8185aa072509880634542cf Mon Sep 17 00:00:00 2001
From: "teo.v" <66650330+developer-1px@users.noreply.github.com>
Date: Wed, 9 Sep 2026 15:18:51 +0900
Subject: [PATCH 09/20] =?UTF-8?q?fix(calendar):=20Document=20Type=20?=
 =?UTF-8?q?=EC=A0=95=EB=B3=B8=20=EA=B3=84=EC=95=BD=EA=B3=BC=20=EC=86=8C?=
 =?UTF-8?q?=EB=B9=84=20=EA=B2=BD=EA=B3=84=EB=A5=BC=20=EB=B3=B4=EA=B0=95?=
 =?UTF-8?q?=ED=95=9C=EB=8B=A4=20(#746)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Calendar 문서 모델·검증·의미 연산·projection을 독립 정본으로 옮기고 선택 회차·붙여넣기·입력 검증을 보강한다. 기존 Editing API 호환 경로, 공통 Editing Grammar, 소유자 문서와 Usage/Source를 연결한다.

관련 테스트 796개와 타입·빌드·외부 tarball 소비·기존 Chrome 검증을 확인했다. Core와 자동 PR CI 정책은 변경하지 않는다.

Closes #745
---
 audits/document-types.json                    | 141 ++++--
 docs/api-reference/calendar-document.md       | 359 +++++++++++++
 docs/api-reference/editing.md                 |  38 +-
 docs/api-reference/packages.mjs               |   1 +
 docs/public/document-types.md                 |  20 +-
 docs/public/hands.md                          | 143 +++---
 package-lock.json                             |  30 +-
 package.json                                  |   1 +
 .../json-document-calendar-document/LICENSE   |  21 +
 .../json-document-calendar-document/README.md |  36 ++
 .../docs/api.md                               | 101 ++++
 .../package.json                              |  24 +
 .../src/calendar-model.ts                     |  42 ++
 .../src/calendar-occurrence.ts                |   4 +-
 .../src/calendar-operation.ts}                | 110 +++-
 .../src/calendar-projection.ts                | 284 +++++++++++
 .../src/calendar-validation.ts                |  49 +-
 .../src/index.ts                              |  52 ++
 .../tests/calendar-document.test.ts           | 106 ++++
 .../tsconfig.json                             |   6 +
 .../tsconfig.test.json                        |   5 +
 .../vitest.config.ts                          |   3 +
 packages/json-document-calendar/README.md     |  16 +-
 packages/json-document-calendar/package.json  |   2 +
 .../src/calendar-event-inspector.tsx          |   2 +-
 .../src/calendar-month-grid.tsx               |   6 +-
 .../src/calendar-time-grid.tsx                |   8 +-
 .../src/use-calendar-hand.ts                  |  61 ++-
 .../src/use-calendar-pointer-interactions.ts  |  19 +-
 .../tests/calendar-protocol.test.tsx          |  44 ++
 packages/json-document-calendar/tsconfig.json |   1 +
 packages/json-document-editing/README.md      |   7 +
 .../docs/calendar-profile.md                  |  47 +-
 packages/json-document-editing/package.json   |   5 +-
 .../src/calendar-allday-pointer.ts            |  11 +-
 .../src/calendar-month-pointer.ts             |  11 +-
 .../src/calendar-preview.ts                   |   9 +-
 .../src/calendar-selection-move.ts            |  14 +-
 .../src/calendar-selection.ts                 |   7 +-
 .../src/calendar-time-grid-pointer.ts         |  11 +-
 .../json-document-editing/src/calendar.ts     | 476 ++----------------
 packages/json-document-editing/src/index.ts   |  29 +-
 .../tests/calendar-protocol.test.ts           |  37 ++
 .../conformance/calendar-grammar.test.ts      |  58 +++
 packages/json-document-editing/tsconfig.json  |   1 +
 .../json-document-editing/vitest.config.ts    |   1 +
 scripts/verify-external-kit.mjs               |   1 +
 site/config/json-document-source-aliases.ts   |   4 +
 site/package.json                             |   1 +
 site/scripts/check-calendar-allday-span.mjs   |   8 +-
 site/scripts/check-calendar-cell-interval.mjs |   2 +-
 site/scripts/check-calendar-date-part.mjs     |   8 +-
 .../check-calendar-document-calendars.mjs     |   6 +-
 .../scripts/check-calendar-instant-format.mjs |  10 +-
 .../check-calendar-interval-last-date.mjs     |  10 +-
 .../check-calendar-recurrence-transition.mjs  |  10 +-
 site/scripts/check-calendar-temporal.mjs      |   1 +
 site/scripts/check-calendar-view-parser.mjs   |   6 +-
 site/scripts/check-document-type-audits.mjs   |  23 +-
 site/site-routes.json                         |  14 +-
 site/src/app/routeTree.gen.ts                 |  22 +
 .../_page/docs/api/calendar-document.tsx      |   8 +
 .../calendar-demo/CalendarDemoRoute.tsx       |  12 +-
 .../calendar-demo/calendar-demo-navigator.tsx |   5 +-
 site/src/routes/docs/DocsRoute.tsx            |   1 +
 .../docs/DocumentTypeCandidateRoute.tsx       |  27 +-
 site/src/routes/docs/doc-pages.ts             |   3 +
 .../src/shared/demo-workbench/demo-sources.ts | 107 ++--
 site/tests/browser/site-shell.spec.ts         |  26 +-
 site/tests/unit/app-shell.test.tsx            |  13 +-
 site/tests/unit/demo-workbench.test.tsx       |   7 +-
 standards/editing-grammar.md                  |   7 +
 standards/repository-implementation-shape.md  |   3 +-
 tsconfig.build.json                           |   1 +
 74 files changed, 1976 insertions(+), 829 deletions(-)
 create mode 100644 docs/api-reference/calendar-document.md
 create mode 100644 packages/json-document-calendar-document/LICENSE
 create mode 100644 packages/json-document-calendar-document/README.md
 create mode 100644 packages/json-document-calendar-document/docs/api.md
 create mode 100644 packages/json-document-calendar-document/package.json
 create mode 100644 packages/json-document-calendar-document/src/calendar-model.ts
 rename packages/{json-document-editing => json-document-calendar-document}/src/calendar-occurrence.ts (98%)
 rename packages/{json-document-editing/src/calendar-event-plan.ts => json-document-calendar-document/src/calendar-operation.ts} (61%)
 create mode 100644 packages/json-document-calendar-document/src/calendar-projection.ts
 rename packages/{json-document-editing => json-document-calendar-document}/src/calendar-validation.ts (81%)
 create mode 100644 packages/json-document-calendar-document/src/index.ts
 create mode 100644 packages/json-document-calendar-document/tests/calendar-document.test.ts
 create mode 100644 packages/json-document-calendar-document/tsconfig.json
 create mode 100644 packages/json-document-calendar-document/tsconfig.test.json
 create mode 100644 packages/json-document-calendar-document/vitest.config.ts
 create mode 100644 packages/json-document-editing/tests/conformance/calendar-grammar.test.ts
 create mode 100644 site/src/app/routes/_page/docs/api/calendar-document.tsx

diff --git a/audits/document-types.json b/audits/document-types.json
index 9e08c16c..1020e90f 100644
--- a/audits/document-types.json
+++ b/audits/document-types.json
@@ -86,7 +86,7 @@
         { "name": "recurrence.freq / interval / until", "description": "반복 주기, 양의 간격과 반복 종료 경계를 정의합니다." },
         { "name": "excludeDates", "description": "반복 projection에서 제외할 occurrence date 목록입니다." }
       ],
-      "sourcePath": "packages/json-document-editing/src/calendar.ts",
+      "sourcePath": "packages/json-document-calendar-document/src/calendar-model.ts",
       "symbol": "CalendarDocument"
     },
     "sheet": {
@@ -135,16 +135,17 @@
   },
   "audits": {
     "calendar": {
-      "status": "audited-tbd",
-      "denominator": 10,
+      "status": "owner-closed",
+      "denominator": 12,
       "horizon": {
         "enumerators": [
+          "packages/json-document-calendar-document/src/index.ts",
           "packages/json-document-editing/src/index.ts",
           "packages/json-document-calendar/src/index.ts",
           "site/src/shared/demo-workbench/demo-sources.ts",
           "site/src/app/live-demo-registry.tsx"
         ],
-        "predicate": "Calendar의 model, invariant, semantic operation, projection, Editing lifecycle, platform translation, affordance, Hand와 reusable UI 책임",
+        "predicate": "Calendar의 model, invariant, semantic operation, projection, Editing lifecycle, platform translation, affordance, Hand와 reusable UI 책임; 정본 선택 대상과 명시적 paste cursor, Calendar Intent binding과 generic gesture lifecycle을 구분",
         "excluded": "fixtures, copy, layout-only CSS, tests and generated route files"
       },
       "occurrences": [
@@ -156,13 +157,13 @@
           "changeReason": "Calendar document vocabulary changes",
           "stateLifecycle": "immutable document value",
           "inputsOutputs": "CalendarDocument and nested JSON values",
-          "currentOwner": "@interactive-os/json-document-editing",
-          "canonicalEvidence": "Document Type boundary: model survives without Editing and UI",
-          "sourcePath": "packages/json-document-editing/src/calendar.ts",
+          "currentOwner": "@interactive-os/json-document-calendar-document",
+          "canonicalEvidence": "Calendar Document Type의 public API, 소유자 docs/api.md, Calendar Usage/Source와 독립 계약 테스트",
+          "sourcePath": "packages/json-document-calendar-document/src/calendar-model.ts",
           "symbol": "CalendarDocument",
-          "disposition": "mislocated module",
-          "intendedOwner": "Calendar Document Type canonical module (missing)",
-          "nextCheck": "admit and name the Calendar Document Type owner before moving the public type"
+          "disposition": "canonical consumer",
+          "intendedOwner": "@interactive-os/json-document-calendar-document",
+          "nextCheck": "기존 Editing type export는 호환 경로이며 새 소비자는 Document Type API를 사용"
         },
         {
           "id": "calendar-invariant",
@@ -172,13 +173,13 @@
           "changeReason": "Calendar validity rules change",
           "stateLifecycle": "stateless validation",
           "inputsOutputs": "CalendarDocument to validation failure or success",
-          "currentOwner": "@interactive-os/json-document-editing",
-          "canonicalEvidence": "Document Type boundary owns schema and invariants",
-          "sourcePath": "packages/json-document-editing/src/calendar-validation.ts",
-          "symbol": "assertCalendarDocument",
-          "disposition": "mislocated module",
-          "intendedOwner": "Calendar Document Type canonical module (missing)",
-          "nextCheck": "define a stable validation contract at the admitted owner"
+          "currentOwner": "@interactive-os/json-document-calendar-document",
+          "canonicalEvidence": "Calendar Document Type의 public API, 소유자 docs/api.md, Calendar Usage/Source와 독립 계약 테스트",
+          "sourcePath": "packages/json-document-calendar-document/src/calendar-validation.ts",
+          "symbol": "validateCalendarDocument",
+          "disposition": "canonical consumer",
+          "intendedOwner": "@interactive-os/json-document-calendar-document",
+          "nextCheck": "독립 validator와 Editing 생성자의 malformed/legacy 회귀 검사"
         },
         {
           "id": "calendar-occurrence-projection",
@@ -188,13 +189,13 @@
           "changeReason": "Calendar recurrence semantics change",
           "stateLifecycle": "stateless projection",
           "inputsOutputs": "CalendarEvent and range to CalendarOccurrence list",
-          "currentOwner": "@interactive-os/json-document-editing",
-          "canonicalEvidence": "Document Type boundary owns projections independent of Editing",
-          "sourcePath": "packages/json-document-editing/src/calendar-occurrence.ts",
+          "currentOwner": "@interactive-os/json-document-calendar-document",
+          "canonicalEvidence": "Calendar Document Type의 public API, 소유자 docs/api.md, Calendar Usage/Source와 독립 계약 테스트",
+          "sourcePath": "packages/json-document-calendar-document/src/calendar-occurrence.ts",
           "symbol": "projectCalendarOccurrences",
-          "disposition": "mislocated module",
-          "intendedOwner": "Calendar Document Type canonical module (missing)",
-          "nextCheck": "separate recurrence projection from occurrence editing transitions"
+          "disposition": "canonical consumer",
+          "intendedOwner": "@interactive-os/json-document-calendar-document",
+          "nextCheck": "독립 projection과 Editing 호환 export가 같은 구현을 소비"
         },
         {
           "id": "calendar-semantic-operation",
@@ -202,15 +203,15 @@
           "knowledge": "Calendar event and recurrence mutation meaning",
           "decision": "the semantic event update represented by a Calendar operation",
           "changeReason": "Calendar mutation semantics change",
-          "stateLifecycle": "operation value interpreted by Editing",
-          "inputsOutputs": "CalendarIntent event cases to document patch",
-          "currentOwner": "@interactive-os/json-document-editing",
-          "canonicalEvidence": "CalendarIntent currently mixes document operations with selection and clipboard intents",
-          "sourcePath": "packages/json-document-editing/src/calendar.ts",
-          "symbol": "CalendarIntent",
-          "disposition": "missing canonical module",
-          "intendedOwner": "Calendar Document Type canonical module (missing)",
-          "nextCheck": "split input-independent Calendar operations from Editing-only intents"
+          "stateLifecycle": "stateless document operation plan",
+          "inputsOutputs": "CalendarEventOperation to events, JSON Patch and affected occurrence; no Editing selection",
+          "currentOwner": "@interactive-os/json-document-calendar-document",
+          "canonicalEvidence": "Calendar Document Type의 public API, 소유자 docs/api.md, Calendar Usage/Source와 독립 계약 테스트",
+          "sourcePath": "packages/json-document-calendar-document/src/calendar-operation.ts",
+          "symbol": "planCalendarEventEdit",
+          "disposition": "canonical consumer",
+          "intendedOwner": "@interactive-os/json-document-calendar-document",
+          "nextCheck": "편집·preview·그룹 이동 및 발생분/원본 제거·visibility는 Document Type 공개 계획을 소비"
         },
         {
           "id": "calendar-editor",
@@ -221,28 +222,28 @@
           "stateLifecycle": "stateful Editing session",
           "inputsOutputs": "EditingDocumentSource and Calendar Intent to EditingResult",
           "currentOwner": "@interactive-os/json-document-editing",
-          "canonicalEvidence": "repository naming standard assigns Intent, Selection, Clipboard and History to Editing",
+          "canonicalEvidence": "EditingSession이 Document Type 공개 연산을 실행하며 primaryOccurrence를 기본 paste target으로 소비",
           "sourcePath": "packages/json-document-editing/src/calendar.ts",
           "symbol": "createCalendarEditor",
-          "disposition": "canonical API gap",
+          "disposition": "canonical consumer",
           "intendedOwner": "@interactive-os/json-document-editing",
-          "nextCheck": "consume the future Calendar Document Type API instead of locally owning its model and rules"
+          "nextCheck": "공통 Calendar Editing Grammar와 API/Hand/초기/외부 selection 경로 회귀 검사"
         },
         {
           "id": "calendar-pointer-interpretation",
-          "role": "Affordance",
-          "knowledge": "input-independent pointer release gesture meaning",
-          "decision": "which Calendar resize or move intent a gesture means",
-          "changeReason": "Calendar gesture grammar changes",
+          "role": "Editing intent binding",
+          "knowledge": "Calendar interval geometry, scope and CalendarIntent",
+          "decision": "bind normalized release values to Calendar-specific Intent",
+          "changeReason": "Calendar intent mapping changes",
           "stateLifecycle": "pointer gesture release",
           "inputsOutputs": "pointer release value to Calendar intent",
           "currentOwner": "@interactive-os/json-document-editing",
-          "canonicalEvidence": "repository naming standard assigns human manipulation grammar to Affordance",
+          "canonicalEvidence": "generic gesture lifecycle은 Affordance, Calendar별 Intent binding은 Editing, DOM capture/좌표는 Web",
           "sourcePath": "packages/json-document-editing/src/calendar-time-grid-pointer.ts",
           "symbol": "interpretCalendarTimeGridPointer",
-          "disposition": "mislocated module",
-          "intendedOwner": "@interactive-os/json-document-affordance",
-          "nextCheck": "compare all-day and month pointer interpreters before choosing one Calendar affordance module"
+          "disposition": "canonical consumer",
+          "intendedOwner": "@interactive-os/json-document-editing",
+          "nextCheck": "time/all-day/month의 bind/interpret가 Document Type 시간 규칙을 소비하는지 확인"
         },
         {
           "id": "calendar-web-input",
@@ -274,7 +275,7 @@
           "symbol": "useCalendarHand",
           "disposition": "canonical consumer",
           "intendedOwner": "@interactive-os/json-document-calendar",
-          "nextCheck": "keep composition only after Document Type capabilities move behind a public API"
+          "nextCheck": "선택 회차는 editor.primaryOccurrence를 읽고 빈 슬롯 paste target만 해당 Editing revision에 묶어 보존"
         },
         {
           "id": "calendar-month-grid",
@@ -290,7 +291,7 @@
           "symbol": "CalendarMonthGrid",
           "disposition": "canonical consumer",
           "intendedOwner": "@interactive-os/json-document-calendar",
-          "nextCheck": "ensure projection inputs come from the future Document Type API"
+          "nextCheck": "Calendar UI는 Document Type의 공개 기간/occurrence projection을 직접 소비"
         },
         {
           "id": "calendar-host",
@@ -306,9 +307,55 @@
           "symbol": "CalendarDemoRoute",
           "disposition": "Host composition",
           "intendedOwner": "site Calendar route",
-          "nextCheck": "audit the runtime import closure for local model, schema, operation or projection implementations"
+          "nextCheck": "CalendarDemoRoute와 navigator는 공개 model/projection/Editing/Hand를 사용하며 fixture·copy·layout·제품 정책만 유지"
+        },
+        {
+          "id": "calendar-selection-target",
+          "role": "Selection target consumption",
+          "knowledge": "canonical occurrence and explicit paste destination",
+          "decision": "derive edit targets from primaryOccurrence; keep only an explicit paste cursor",
+          "changeReason": "Editing selection or paste destination changes",
+          "stateLifecycle": "derived selection and revision-scoped paste cursor",
+          "inputsOutputs": "CalendarEditor primaryOccurrence to inspector/edit/delete/default paste",
+          "currentOwner": "@interactive-os/json-document-calendar",
+          "canonicalEvidence": "Calendar protocol identity and direct API/Hand/initial/external selection regression tests",
+          "sourcePath": "packages/json-document-calendar/src/use-calendar-hand.ts",
+          "symbol": "useCalendarHand",
+          "disposition": "canonical consumer",
+          "intendedOwner": "@interactive-os/json-document-calendar",
+          "nextCheck": "같은 회차를 수정하고 explicit paste target은 상태 변경 후 재사용하지 않음"
+        },
+        {
+          "id": "calendar-gesture-lifecycle",
+          "role": "Affordance",
+          "knowledge": "input-independent gesture lifecycle",
+          "decision": "begin/preview/commit/cancel without Calendar model or DOM capture",
+          "changeReason": "generic gesture lifecycle changes",
+          "stateLifecycle": "GestureSession",
+          "inputsOutputs": "generic data to preview or committed/cancelled result",
+          "currentOwner": "@interactive-os/json-document-affordance",
+          "canonicalEvidence": "Calendar useCalendarPointerInteractions consumes public createGestureSession",
+          "sourcePath": "packages/json-document-affordance/src/gesture-session.ts",
+          "symbol": "createGestureSession",
+          "disposition": "canonical consumer",
+          "intendedOwner": "@interactive-os/json-document-affordance",
+          "nextCheck": "Calendar protocol tests preserve cancellation and one Editing transaction"
         }
-      ]
+      ],
+      "closure": {
+        "owner": "@interactive-os/json-document-calendar-document",
+        "publicEntry": "packages/json-document-calendar-document/src/index.ts",
+        "referencePath": "packages/json-document-calendar-document/docs/api.md",
+        "apiPath": "/docs/api/calendar-document",
+        "usagePath": "/demo/calendar",
+        "usagePagePath": "/editors#calendar-editor",
+        "sourceRegistration": "site/src/shared/demo-workbench/demo-sources.ts",
+        "verification": [
+          "packages/json-document-calendar-document/tests/calendar-document.test.ts",
+          "packages/json-document-editing/tests/conformance/calendar-grammar.test.ts",
+          "packages/json-document-calendar/tests/calendar-protocol.test.tsx"
+        ]
+      }
     }
   }
 }
diff --git a/docs/api-reference/calendar-document.md b/docs/api-reference/calendar-document.md
new file mode 100644
index 00000000..68cb0235
--- /dev/null
+++ b/docs/api-reference/calendar-document.md
@@ -0,0 +1,359 @@
+# @interactive-os/json-document-calendar-document API
+
+**Owner:** Document Types
+
+Calendar 문서 모델·검증·의미 연산·projection 계약의 public entrypoint입니다. 아래 항목은 package root에서 import할 수 있는 안정된 public API이며 internal 경로는 계약이 아닙니다.
+
+> 이 문서는 `packages/json-document-calendar-document/src/index.ts`에서 생성됩니다. API를 변경한 뒤 `npm run docs:api`를 실행하세요.
+
+## `addCalendarDate`
+
+```ts
+addCalendarDate(day: string, days: number): string | null
+```
+## `assertCalendarDocument`
+
+```ts
+assertCalendarDocument(value: unknown): void
+```
+## `calendarAllDayLayout`
+
+```ts
+calendarAllDayLayout(events: ReadonlyArray<CalendarEvent>, days: ReadonlyArray<string>): ReadonlyArray<{ readonly event: CalendarEvent; readonly startIndex: number; readonly span: number; readonly lane: number; readonly laneCount: number; }>
+```
+## `calendarAllDaySpan`
+
+```ts
+calendarAllDaySpan(originDay: string, targetDay: string): { readonly start: string; readonly end: string; } | null
+```
+## `calendarBusyDates`
+
+```ts
+calendarBusyDates(events: ReadonlyArray<CalendarEvent>, rangeStart: string, rangeEnd: string): ReadonlySet<string>
+```
+## `CalendarCalendar`
+
+```ts
+interface CalendarCalendar extends Record<string, JSONValue> {
+  readonly id: string;
+  readonly title: string;
+  readonly hidden: boolean;
+  readonly color: string;
+}
+```
+## `calendarDatePart`
+
+```ts
+calendarDatePart(value: string): string
+```
+## `calendarDaysBetween`
+
+```ts
+calendarDaysBetween(from: Temporal.PlainDate, to: Temporal.PlainDate): number
+```
+## `CalendarDocument`
+
+```ts
+interface CalendarDocument extends Record<string, JSONValue> {
+  readonly calendars: ReadonlyArray<CalendarCalendar>;
+  readonly events: ReadonlyArray<CalendarEvent>;
+}
+```
+## `calendarDocumentCalendar`
+
+```ts
+calendarDocumentCalendar(document: CalendarDocument, calendarId: string): CalendarCalendar | null
+```
+## `calendarDocumentCalendars`
+
+```ts
+calendarDocumentCalendars(document: CalendarDocument): ReadonlyArray<CalendarCalendar>
+```
+## `calendarDocumentEvents`
+
+```ts
+calendarDocumentEvents(document: CalendarDocument): ReadonlyArray<CalendarEvent>
+```
+## `CalendarEvent`
+
+```ts
+interface CalendarEvent extends Record<string, JSONValue> {
+  readonly id: string;
+  readonly title: string;
+  readonly start: string;
+  readonly end: string;
+  readonly allDay: boolean;
+  readonly calendarId: string;
+  readonly recurrence: CalendarRecurrence | null;
+  readonly excludeDates: ReadonlyArray<string>;
+}
+```
+## `calendarEventBounds`
+
+```ts
+calendarEventBounds(event: Pick<CalendarEvent, "start" | "end" | "allDay">): { readonly from: Temporal.PlainDateTime; readonly to: Temporal.PlainDateTime; } | null
+```
+## `calendarEventExcludeDates`
+
+```ts
+calendarEventExcludeDates(event: CalendarEvent): ReadonlyArray<string>
+```
+## `calendarEventIntervalAt`
+
+```ts
+calendarEventIntervalAt(event: Pick<CalendarEvent, "start" | "end" | "allDay">, start: string): { readonly start: string; readonly end: string; } | null
+```
+## `CalendarEventOperation`
+
+```ts
+type CalendarEventOperation =
+  | {
+      readonly type: "event.create";
+      readonly start: string;
+      readonly end: string;
+      readonly title?: string;
+      readonly allDay?: boolean;
+      readonly calendarId?: string;
+      readonly recurrence?: CalendarRecurrence | null;
+    }
+  | { readonly type: "event.move"; readonly eventId: string; readonly start: string }
+  | { readonly type: "event.resize"; readonly eventId: string; readonly edge: "start" | "end"; readonly instant: string }
+  | { readonly type: "event.move-day"; readonly eventId: string; readonly day: string }
+  | {
+      readonly type: "event.update";
+      readonly eventId: string;
+      readonly title?: string;
+      readonly start?: string;
+      readonly end?: string;
+      readonly allDay?: boolean;
+      readonly calendarId?: string;
+      readonly recurrence?: CalendarRecurrence | null;
+    }
+  | {
+      readonly type: "occurrence.edit";
+      readonly eventId: string;
+      readonly occurrenceStart: string;
+      readonly scope: "this" | "this-and-following" | "all";
+      readonly title?: string;
+      readonly start?: string;
+      readonly end?: string;
+    };
+```
+## `CalendarEventPlan`
+
+```ts
+type CalendarEventPlan = {
+  readonly ok: true;
+  readonly events: ReadonlyArray<CalendarEvent>;
+  readonly operations: ReadonlyArray<JSONPatchOperation>;
+  readonly affectedOccurrence: CalendarOccurrencePoint;
+} | { readonly ok: false; readonly code: string; readonly reason?: string };
+```
+## `calendarEventRecurrence`
+
+```ts
+calendarEventRecurrence(event: CalendarEvent): CalendarRecurrence | null
+```
+## `calendarEventsInMonth`
+
+```ts
+calendarEventsInMonth(events: ReadonlyArray<CalendarEvent>, month: string): ReadonlyArray<CalendarEvent>
+```
+## `calendarEventsOnDay`
+
+```ts
+calendarEventsOnDay(events: ReadonlyArray<CalendarEvent>, day: string): ReadonlyArray<CalendarEvent>
+```
+## `CalendarEventsPlan`
+
+```ts
+type CalendarEventsPlan = (Extract<CalendarPatchPlan, { ok: true }> & { readonly events: ReadonlyArray<CalendarEvent> })
+  | Extract<CalendarPatchPlan, { ok: false }>;
+```
+## `calendarInstantAt`
+
+```ts
+calendarInstantAt(day: string, minutesFromMidnight: number): string | null
+```
+## `calendarIntervalLastDate`
+
+```ts
+calendarIntervalLastDate(start: string, end: string, allDay: boolean): string
+```
+## `calendarMinutesBetween`
+
+```ts
+calendarMinutesBetween(from: Temporal.PlainDateTime, to: Temporal.PlainDateTime): number
+```
+## `calendarMonthDayLayout`
+
+```ts
+calendarMonthDayLayout(events: ReadonlyArray<CalendarEvent>, day: string, rowLimit: number): { readonly events: ReadonlyArray<CalendarEvent>; readonly hiddenCount: number; }
+```
+## `calendarMonthWeekLayout`
+
+```ts
+calendarMonthWeekLayout(events: ReadonlyArray<CalendarEvent>, days: ReadonlyArray<string>, rowLimit: number): { readonly items: ReadonlyArray<{ readonly event: CalendarEvent; readonly startIndex: number; readonly span: number; readonly lane: number; }>; readonly hiddenCounts: ReadonlyArray<number>; readonly laneCount: number; }
+```
+## `calendarNowMarker`
+
+```ts
+calendarNowMarker(nowInstant: string, day: string): { readonly minutes: number; } | null
+```
+## `CalendarOccurrence`
+
+```ts
+type CalendarOccurrence = {
+  readonly event: CalendarEvent;
+  readonly start: string;
+  readonly end: string;
+};
+```
+## `CalendarOccurrenceInterval`
+
+```ts
+interface CalendarOccurrenceInterval {
+  readonly eventId: string;
+  readonly start: string;
+  readonly end: string;
+}
+```
+## `CalendarOccurrencePoint`
+
+```ts
+interface CalendarOccurrencePoint extends Record<string, JSONValue> {
+  readonly eventId: string;
+  readonly occurrenceStart: string;
+}
+```
+## `CalendarOccurrenceRemoval`
+
+```ts
+type CalendarOccurrenceRemoval = {
+  readonly eventId: string;
+  readonly occurrenceStart: string;
+  readonly scope: "this" | "this-and-following" | "all";
+};
+```
+## `CalendarPatchPlan`
+
+```ts
+type CalendarPatchPlan = { readonly ok: true; readonly operations: ReadonlyArray<JSONPatchOperation> }
+  | { readonly ok: false; readonly code: string; readonly reason?: string };
+```
+## `CalendarRecurrence`
+
+```ts
+interface CalendarRecurrence extends Record<string, JSONValue> {
+  readonly freq: "daily" | "weekly" | "monthly" | "yearly";
+  readonly interval: number;
+  readonly until: string;
+}
+```
+## `calendarRecurrenceWithFrequency`
+
+```ts
+calendarRecurrenceWithFrequency(current: CalendarRecurrence | null, value: unknown): CalendarRecurrence | null
+```
+## `calendarRecurrenceWithInterval`
+
+```ts
+calendarRecurrenceWithInterval(current: CalendarRecurrence | null, value: unknown): CalendarRecurrence | null
+```
+## `calendarRecurrenceWithUntil`
+
+```ts
+calendarRecurrenceWithUntil(current: CalendarRecurrence | null, until: string): CalendarRecurrence | null
+```
+## `calendarShiftInstant`
+
+```ts
+calendarShiftInstant(instant: string, minutes: number): string | null
+```
+## `calendarTimedLayout`
+
+```ts
+calendarTimedLayout(events: ReadonlyArray<CalendarEvent>, day: string): ReadonlyArray<{ readonly event: CalendarEvent; readonly startMinutes: number; readonly endMinutes: number; readonly lane: number; readonly laneCount: number; }>
+```
+## `CalendarValidationResult`
+
+```ts
+type CalendarValidationResult = { readonly ok: true } | {
+  readonly ok: false; readonly code: string; readonly reason: string;
+};
+```
+## `calendarVisibleEvents`
+
+```ts
+calendarVisibleEvents(document: CalendarDocument): ReadonlyArray<CalendarEvent>
+```
+## `formatCalendarDate`
+
+```ts
+formatCalendarDate(value: Temporal.PlainDate): string
+```
+## `formatCalendarInstant`
+
+```ts
+formatCalendarInstant(value: Temporal.PlainDateTime): string
+```
+## `isCalendarAllDay`
+
+```ts
+isCalendarAllDay(event: Pick<CalendarEvent, "allDay">): boolean
+```
+## `isCalendarRecurrence`
+
+```ts
+isCalendarRecurrence(value: unknown): value is CalendarRecurrence
+```
+## `parseCalendarDate`
+
+```ts
+parseCalendarDate(value: string): Temporal.PlainDate | null
+```
+## `parseCalendarInstant`
+
+```ts
+parseCalendarInstant(value: string): Temporal.PlainDateTime | null
+```
+## `planCalendarEventEdit`
+
+```ts
+planCalendarEventEdit(events: ReadonlyArray<CalendarEvent>, intent: CalendarEventOperation, options: { readonly allocateId: () => string; readonly calendarIds?: ReadonlySet<string>; readonly defaultCalendarId?: string; }): CalendarEventPlan
+```
+## `planCalendarEventRemoval`
+
+```ts
+planCalendarEventRemoval(events: ReadonlyArray<CalendarEvent>, eventIds: ReadonlyArray<string>): CalendarEventsPlan
+```
+## `planCalendarOccurrenceRemoval`
+
+```ts
+planCalendarOccurrenceRemoval(events: ReadonlyArray<CalendarEvent>, removal: CalendarOccurrenceRemoval): CalendarEventsPlan
+```
+## `planCalendarVisibility`
+
+```ts
+planCalendarVisibility(document: CalendarDocument, calendarId: string, hidden: boolean): CalendarPatchPlan
+```
+## `projectCalendarOccurrences`
+
+```ts
+projectCalendarOccurrences(events: ReadonlyArray<CalendarEvent>, rangeStart: string, rangeEnd: string): ReadonlyArray<CalendarOccurrence>
+```
+## `resolveCalendarOccurrence`
+
+```ts
+resolveCalendarOccurrence(events: ReadonlyArray<CalendarEvent>, point: CalendarOccurrencePoint): CalendarOccurrenceInterval | null
+```
+## `validateCalendarDocument`
+
+```ts
+validateCalendarDocument(value: unknown): CalendarValidationResult
+```
+## `validateCalendarEvent`
+
+```ts
+validateCalendarEvent(value: unknown, calendarIds?: ReadonlySet<string>): CalendarValidationResult
+```
diff --git a/docs/api-reference/editing.md b/docs/api-reference/editing.md
index b79ee7d5..e7b82e12 100644
--- a/docs/api-reference/editing.md
+++ b/docs/api-reference/editing.md
@@ -306,37 +306,7 @@ type CalendarIntent =
       readonly target: CalendarSelectionMoveTarget;
       readonly scope?: "this" | "this-and-following" | "all";
     }
-  | {
-      readonly type: "event.create";
-      readonly start: string;
-      readonly end: string;
-      readonly title?: string;
-      readonly allDay?: boolean;
-      readonly calendarId?: string;
-      readonly recurrence?: CalendarRecurrence | null;
-    }
-  | { readonly type: "event.move"; readonly eventId: string; readonly start: string }
-  | { readonly type: "event.resize"; readonly eventId: string; readonly edge: "start" | "end"; readonly instant: string }
-  | { readonly type: "event.move-day"; readonly eventId: string; readonly day: string }
-  | {
-      readonly type: "event.update";
-      readonly eventId: string;
-      readonly title?: string;
-      readonly start?: string;
-      readonly end?: string;
-      readonly allDay?: boolean;
-      readonly calendarId?: string;
-      readonly recurrence?: CalendarRecurrence | null;
-    }
-  | {
-      readonly type: "occurrence.edit";
-      readonly eventId: string;
-      readonly occurrenceStart: string;
-      readonly scope: "this" | "this-and-following" | "all";
-      readonly title?: string;
-      readonly start?: string;
-      readonly end?: string;
-    }
+  | CalendarEventOperation
   | {
       readonly type: "occurrence.remove";
       readonly eventId: string;
@@ -427,11 +397,7 @@ type CalendarOccurrenceRange = {
 ## `CalendarOccurrenceSelection`
 
 ```ts
-interface CalendarOccurrenceSelection {
-  readonly eventId: string;
-  readonly start: string;
-  readonly end: string;
-}
+type CalendarOccurrenceSelection = CalendarOccurrenceInterval;
 ```
 ## `calendarOccurrenceTopology`
 
diff --git a/docs/api-reference/packages.mjs b/docs/api-reference/packages.mjs
index 0ba9cdfe..39165dd5 100644
--- a/docs/api-reference/packages.mjs
+++ b/docs/api-reference/packages.mjs
@@ -1,4 +1,5 @@
 export const apiReferencePackages = [
+  ["calendar-document", "@interactive-os/json-document-calendar-document", "packages/json-document-calendar-document/src/index.ts", "Document Types", "Calendar 문서 모델·검증·의미 연산·projection 계약"],
   ["a2ui", "@interactive-os/json-document-a2ui", "packages/json-document-a2ui/src/index.ts", "Connector", "A2UI streaming document connector"],
   ["json-document", "@interactive-os/json-document", "packages/json-document/src/application/document/index.ts", "JSON Document", "Core document 값·주소·patch 계약"],
   ["selection", "@interactive-os/json-document-selection", "packages/json-document-selection/src/index.ts", "Editing", "구조적 selection과 topology 계약"],
diff --git a/docs/public/document-types.md b/docs/public/document-types.md
index 390223c4..0c91a8d7 100644
--- a/docs/public/document-types.md
+++ b/docs/public/document-types.md
@@ -2,7 +2,8 @@
 
 Document Type은 특정 JSON Document가 무엇을 의미하고 어떤 상태와 변경이
 유효한지를 정의하는 생태계 위치입니다. 이 페이지는 책임 이름과 경계만
-확정하며, 기존 package와 Hands의 실제 소유권 재배치는 아직 결정하지 않습니다.
+확정합니다. Calendar는 공개 소유자와 소비 경계를 확정했고, 나머지 후보의 실제
+소유권 재배치는 아직 결정하지 않았습니다.
 
 ```text
 Document Type
@@ -57,7 +58,16 @@ Document Type은 DOM event, pointer gesture, React lifecycle, 화면 layout과 
 `Domain`은 business bounded context와 혼동되고, `Genre`는 제품 설명과 기술 계약의
 경계를 드러내지 않으므로 이 생태계 위치의 정본 이름으로 사용하지 않습니다.
 
-## 후보 · TBD
+## 현재 소유자와 후보
+
+Calendar의 정본 소유자는 `@interactive-os/json-document-calendar-document`입니다.
+모델·검증·의미 연산·projection은 이 package에, 선택·Clipboard·History는 Editing에,
+입력과 UI 조합은 Calendar Hands에 둡니다. Editing의 기존 문서 관련 export는
+동일 구현을 가리키는 호환 경로입니다.
+
+[Calendar Document Type](/docs/document-types/calendar)에서 공개 API, Usage/Source와
+책임 감사 증거를 확인할 수 있습니다. 이 소유권 확정은 RC 계약을 Stable wire
+프로파일로 승격하거나 나머지 후보의 완료를 선언하지 않습니다.
 
 현재 사이트에서 다음 항목이 Document Type 후보입니다.
 
@@ -68,18 +78,18 @@ Document Types · TBD
 ├── Object
 ├── Tree
 ├── Database
-├── Calendar
+├── Calendar · RC 공개 소유자 확정
 ├── Sheet
 ├── Kanban
 └── Annotation
 ```
 
-이 목록은 분류 후보이지 완료 선언이 아닙니다. 각 후보는 모델, invariant,
+Calendar 이외의 목록은 분류 후보이지 완료 선언이 아닙니다. 각 후보는 모델, invariant,
 operation과 projection의 실제 owner를 감사한 뒤에만 이 위치로 이동할 수
 있습니다. 그때까지 기존 package/API 이름, 모듈 배치와 Hands 내비게이션은
 유지합니다.
 
-## 완료 조건 · TBD
+## 소유권 확정 조건
 
 각 Document Type의 분류를 확정할 때는 다음 증거가 모두 필요합니다.
 
diff --git a/docs/public/hands.md b/docs/public/hands.md
index 3c1b40b3..40840ddc 100644
--- a/docs/public/hands.md
+++ b/docs/public/hands.md
@@ -40,95 +40,74 @@ presentation을 번역합니다.
 
 ## Calendar editor
 
-시간 구간 이벤트의 persistent model과 editing session은
-`@interactive-os/json-document-editing`의 `createCalendarEditor`가 소유합니다.
+Calendar의 문서 모델·검증·의미 연산·projection은
+`@interactive-os/json-document-calendar-document`, 편집 lifecycle은
+`@interactive-os/json-document-editing`, 입력과 UI 조합은
+`@interactive-os/json-document-calendar`가 소유합니다.
 
 ```ts
+import { validateCalendarDocument } from "@interactive-os/json-document-calendar-document";
+import { createCalendarEditor } from "@interactive-os/json-document-editing";
+
+const validation = validateCalendarDocument(calendarDocument);
+if (!validation.ok) throw new Error(validation.reason);
 const editor = createCalendarEditor(calendarDocument);
 editor.dispatch({ type: "event.move", eventId, start: "2026-08-03T10:00" });
-editor.dispatch({ type: "event.move-day", eventId, day: "2026-08-05" });
-editor.dispatch({ type: "event.create", start: "2026-08-03", end: "2026-08-04", allDay: true });
 editor.undo();
 ```
 
-`CalendarDocument`는 캘린더 `{ id, title, hidden, color }`와 이벤트
-`{ id, title, start, end, allDay, calendarId }`를 직렬화합니다. `color`는
-Host가 fill로 옮기는 짧은 토큰입니다. 시간 이벤트는 datetime-local, 종일
-이벤트는 exclusive-end 날짜입니다. 일·주 보기의 빈 구간 drag는 그
-start/end로 만들고, 빈 칸 클릭은 선택을 지웁니다. 빈 칸 더블클릭은 기본
-길이로 만들고 제목을 묻습니다. 블록 이동은 duration을 유지하며 가장자리는
-`event.resize`입니다. 종일 밴드는 날짜 단위로 드래그해 만들고 옮기고
-늘립니다. 월 보기 같은 날 빈 칸 클릭은 선택 해제, 더블클릭은 그날 종일 생성,
-빈 칸을 다른 날로 끌면 그 날들을 덮는 종일 구간을 만들고 제목을 묻습니다.
-여러 날을 덮는 종일 이벤트는 주 행을 가로지르는 막대이고, 주 경계에서 잘립니다.
-Exclusive end를 마지막 점유 날짜로 바꾸는 interval projection은 Editing
-`calendarIntervalLastDate`가 소유합니다. occurrence day 열거, all-day resize end,
-month week clipping이 모두 같은 정본 규칙을 사용합니다.
-날짜 또는 날짜·시간 문자열에서 `YYYY-MM-DD` 날짜 부분을 얻는 projection은
-Editing `calendarDatePart`가 소유합니다. 현재 시각의 오늘 날짜와 새 이벤트의
-생성 날짜도 Host의 문자열 자르기 없이 이 공개 API를 사용합니다.
-Host는 `Temporal.Now`로 concrete clock을 읽고 Editing `formatCalendarInstant`로
-Calendar datetime-local minute 문자열을 만듭니다. clock source와 저장 형식의
-책임을 섞는 route-local formatter는 두지 않습니다.
-Calendar collection과 id lookup은 Editing `calendarDocumentCalendars`,
-`calendarDocumentCalendar`가 소유합니다. Host는 sidebar와 inspector를 조합하고
-calendar color를 UI variant로 바꾸는 시각 정책만 유지합니다.
-Inspector의 repeat frequency·interval·until 변경은 Editing
-`calendarRecurrenceWithFrequency`, `calendarRecurrenceWithInterval`,
-`calendarRecurrenceWithUntil`이 `CalendarRecurrence` model을 만들고 보존합니다.
-Host는 option copy와 recurrence 비활성화 선택만 조합합니다.
-월간 42개 날짜 cell을 6개의 ISO 주 행으로 투영하는 일은 UI Primitives 날짜 값
-정본의 `calendarMonthWeeks`가 소유하며, Host는 각 행의 event layout과 DOM을
-조합합니다.
-표시 cell collection의 첫 날짜부터 마지막 날짜 다음 날까지의 half-open query
-범위는 UI Primitives `calendarCellInterval`이 소유합니다. 연간 12개 month grid와
-sidebar navigator가 같은 interval을 Editing occurrence query에 전달합니다.
-Day와 week time grid의 ordered 날짜 cell도 UI Primitives `calendarCells`가
-소유합니다. Day는 정확한 ISO weekday를 포함한 단일 cell, week는 ISO 주의
-7개 cell을 반환합니다. 각 `CalendarCell`은 canonical date에서 투영한 `day`와
-ISO weekday를 제공하며 Host는 문자열을 해석하지 않고 이 metadata로 날짜 숫자,
-header와 event grid를 조합합니다.
-Inclusive UI 날짜 endpoint를 all-day event의 exclusive storage interval로 바꾸는
-projection은 Editing `calendarAllDaySpan`이 소유합니다. 빈 drag, end resize,
-timed→all-day 전환, 단일 생성과 Inspector 수정이 모두 같은 정본 규칙을 사용합니다.
-막대 가장자리는 종일 밴드와 같이 `event.resize`입니다.
-점유 칸은 origin 이벤트 선택, 다른 날로 끌 때만 `event.move-day`입니다.
-월간 span에서 누른 Web `clientX`는 `calendarKeyFromWebRow`가 주 행 bounds와
-정렬된 날짜를 사용해 origin 날짜로 투영합니다. Calendar React의
-`useCalendarPointerInteractions`가 DOM 측정과 pointer session 시작을 소유하므로
-Host는 이벤트와 날짜 목록만 연결합니다.
-`+N more`는 그 날의 이벤트 목록을 열고 월 보기에 남습니다. 이 매핑은
-`interpretCalendarTimeGridPointer`, `interpretCalendarAllDayPointer`,
-`interpretCalendarMonthPointer`가 소유하며 현재 선택은 입력이 아닙니다.
-
-선택한 occurrence의 body drag는 이 단건 pointer intent를 반복하지 않습니다.
-Selection의 `resolveMaterializedSelectionDragSource`가 source snapshot을 확정하고,
-Editing의 `planCalendarSelectionMove`가 anchor에서 target까지의 temporal delta를
-모든 occurrence에 동일하게 적용합니다. React Calendar binding은 Web pointer
-session과 Affordance `createGestureSession`을 합성해 같은 plan으로 preview한 뒤
-`selection.move`를 한 번 dispatch합니다. 따라서 document 변경, `selectionAfter`,
-undo/redo는 한 Editing transaction으로 함께 이동합니다. ResizeHandle은 이
-selection drag와 별개의 edge geometry lifecycle을 유지합니다.
-연 보기는 12개 미니 월입니다. 월 이름은 월 보기로, 날짜는 일 보기로
-들어갑니다. 연간 12개 월 시작일은 UI Primitives 날짜 값 정본의
-`calendarYearMonths`가 만들고, Host는 월 이름과 grid layout 및 navigation만
-조합합니다. 보기와 날짜는 Host URL (`?view=&date=`)입니다. 픽셀 격자와
-보기 전환은 Host가 조합합니다. 정본 view membership은 Editing
-`parseCalendarView`가 판별하고 URL의 invalid
-값을 어떤 view로 대체할지는 Host 정책으로 남습니다.
-toolbar의 현재 기간 문구는 UI Primitives
-`visiblePeriodLabel`이 view 분기와 날짜 경계를 투영하고, Host가 월 이름 copy와
-week separator policy를 주입합니다.
-Previous/Next 및 keyboard period 이동은 UI Primitives `shiftVisibleDate`가
-day/week/month/year의 단위와 calendar arithmetic을 소유하며, Host는 현재 view와
-direction을 전달하고 결과를 URL state에 반영합니다.
-Timed event의 datetime-local에서 `HH:mm` 문구를 투영하는 일은 UI Primitives
-`calendarTimeLabel`이 소유합니다. Host는 그 결과를 visual copy에 조합하고,
-UI Primitives의 event-label projection도 같은 정본 값을 accessible name에
-사용합니다. Date-only와 유효하지 않은 값은 빈 문구입니다.
-Month event의 accessible name은 UI Primitives `calendarEventLabel`이 all-day에는
-title, timed event에는 가능한 `HH:mm title`을 투영합니다. 이 모듈은 구조적
-event 값만 받아 UI Primitives가 Editing package에 의존하지 않도록 합니다.
+`CalendarDocument`는 calendar와 interval event·recurrence를 정의합니다.
+datetime-local minute과 exclusive-end all-day, calendar 참조, 반복의
+this/following/all 의미는 [Document Type 계약](/docs/api/calendar-document)을
+따릅니다. `validateCalendarDocument`와 생성자는 같은 검증을 사용합니다.
+생략된 legacy 필드와 잘못된 타입은 다르게 처리합니다.
+
+Editing은 Document Type의 `planCalendarEventEdit`, `planCalendarEventRemoval`,
+`planCalendarOccurrenceRemoval`, `planCalendarVisibility`를 실행하고 Selection과
+History를 연결합니다. occurrence 선택은 `{ eventId, occurrenceStart }`로 식별하며
+Hand는 `editor.primaryOccurrence`를 읽습니다. 직접 dispatch, 외부에서 바꾼 선택,
+mount 전 선택도 Inspector·수정·삭제의 같은 대상이 됩니다.
+`editor.paste(clipboard)`의 기본 목적지는 선택 회차이고, 빈 슬롯을 찍은 위치는
+Hand의 명시적 임시 paste target입니다. [Editing 프로파일](/docs/api/editing#calendar-protocol-profile-rc)에
+선택·복사·붙여넣기·History 결과와 공통 검사 근거를 연결합니다.
+
+문서 조회와 시간 변환은 Document Type의 공개 API를 사용합니다.
+
+- `calendarDocumentCalendars` / `calendarDocumentCalendar`: collection과 id lookup
+- `calendarDatePart` / `calendarIntervalLastDate`: 날짜 부분과 exclusive end의 마지막 점유일
+- `calendarAllDaySpan`: inclusive UI 날짜 endpoint를 exclusive 저장 구간으로 변환
+- `formatCalendarInstant`: concrete `Temporal.Now` 값을 저장 형식으로 변환
+- `calendarRecurrenceWithFrequency` / `calendarRecurrenceWithInterval` /
+  `calendarRecurrenceWithUntil`: 반복 모델 변경
+- `projectCalendarOccurrences` / `calendarBusyDates`: 발생분과 점유 날짜 조회
+- `calendarTimedLayout` / `calendarAllDayLayout` / `calendarMonthWeekLayout`:
+  event 구간과 lane projection
+
+Host는 clock 인스턴스, color를 UI variant로 바꾸는 정책, copy와 layout을 조합합니다.
+`CalendarMonthGrid`와 `CalendarTimeGrid`는 표시와 접근성·overflow·interaction을
+소유합니다. 월의 42개 날짜 cell과 6개 주 행은 Calendar Hands의 `calendarMonthWeeks`,
+query 범위는 `calendarCellInterval`, day/week의 ordered cell은 `calendarCells`가
+만듭니다. cell의 ISO weekday metadata와 화면의 주 시작 정책을 같은 개념으로
+설명하지 않습니다. 연간 월 목록은 `calendarYearMonths`가 소유합니다.
+
+Toolbar의 `visiblePeriodLabel`, 날짜 이동의 `shiftVisibleDate`, 시간 문구의
+`calendarTimeLabel`, 접근 가능한 event 이름의 `calendarEventLabel`도 Calendar
+Hands 책임입니다. generic UI Primitives에 Calendar 모델이나 날짜 선택 동작을
+넣지 않습니다. View와 날짜의 URL은 Host가 조합하며 view membership은 기존
+Editing `parseCalendarView`가 판별합니다.
+
+Calendar별 `interpretCalendarTimeGridPointer`, `interpretCalendarAllDayPointer`,
+`interpretCalendarMonthPointer`와 bind 함수는 정규화된 release 값을 Calendar Intent로
+연결하는 Editing 책임입니다. generic gesture의 begin/preview/commit/cancel은
+Affordance, DOM pointer capture와 `calendarKeyFromWebRow` 같은 좌표 변환은 Web에 둡니다.
+`useCalendarPointerInteractions`가 이 API들을 조합하며 자체 root 안에서 hit-test합니다.
+
+선택한 occurrence의 body drag는 Selection의
+`resolveMaterializedSelectionDragSource`로 대상을 캡처하고 Editing의
+`planCalendarSelectionMove`로 preview와 commit을 계획합니다. 같은 Document Type
+연산을 공유하며 전체 document·selection·undo/redo가 한 Editing transaction으로
+이동합니다. Hand는 Web pointer session과 Affordance `createGestureSession`을
+조합하고, resize edge와 그룹 이동의 lifecycle은 구별합니다.
 
 ```live-demo
 /demo/calendar
diff --git a/package-lock.json b/package-lock.json
index e3e60a52..dc4e8f47 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -8,6 +8,7 @@
       "workspaces": [
         "packages/json-document",
         "packages/json-document-selection",
+        "packages/json-document-calendar-document",
         "packages/json-document-editing",
         "packages/json-document-react",
         "packages/json-document-react-hook-form",
@@ -1133,6 +1134,10 @@
       "resolved": "packages/json-document-calendar",
       "link": true
     },
+    "node_modules/@interactive-os/json-document-calendar-document": {
+      "resolved": "packages/json-document-calendar-document",
+      "link": true
+    },
     "node_modules/@interactive-os/json-document-collaboration": {
       "resolved": "packages/json-document-collaboration",
       "link": true
@@ -6549,6 +6554,7 @@
       },
       "devDependencies": {
         "@interactive-os/json-document-affordance": "*",
+        "@interactive-os/json-document-calendar-document": "*",
         "@interactive-os/json-document-editing": "*",
         "@interactive-os/json-document-react": "*",
         "@interactive-os/json-document-ui-primitives-react": "*",
@@ -6563,6 +6569,7 @@
       },
       "peerDependencies": {
         "@interactive-os/json-document-affordance": ">=0.1.0-rc.0 <1",
+        "@interactive-os/json-document-calendar-document": ">=0.1.0-rc.0 <1",
         "@interactive-os/json-document-editing": ">=0.1.0-rc.0 <1",
         "@interactive-os/json-document-react": ">=0.1.0-rc.0 <1",
         "@interactive-os/json-document-ui-primitives-react": ">=0.1.0-rc.0 <1",
@@ -6570,6 +6577,23 @@
         "react": "^18.0.0 || ^19.0.0"
       }
     },
+    "packages/json-document-calendar-document": {
+      "name": "@interactive-os/json-document-calendar-document",
+      "version": "0.1.0-rc.0",
+      "license": "MIT",
+      "dependencies": {
+        "@js-temporal/polyfill": "^0.5.1"
+      },
+      "devDependencies": {
+        "@interactive-os/json-document": "*",
+        "@types/node": "^25.9.0",
+        "typescript": "^5.0.0",
+        "vitest": "^4.1.7"
+      },
+      "peerDependencies": {
+        "@interactive-os/json-document": "^3.0.0"
+      }
+    },
     "packages/json-document-collaboration": {
       "name": "@interactive-os/json-document-collaboration",
       "version": "0.2.0-rc.1",
@@ -6716,11 +6740,9 @@
       "name": "@interactive-os/json-document-editing",
       "version": "0.1.0-rc.0",
       "license": "MIT",
-      "dependencies": {
-        "@js-temporal/polyfill": "^0.5.1"
-      },
       "devDependencies": {
         "@interactive-os/json-document": "*",
+        "@interactive-os/json-document-calendar-document": "*",
         "@interactive-os/json-document-selection": "*",
         "@types/node": "^25.9.0",
         "typescript": "^5.0.0",
@@ -6728,6 +6750,7 @@
       },
       "peerDependencies": {
         "@interactive-os/json-document": "^3.0.0",
+        "@interactive-os/json-document-calendar-document": "^0.1.0-rc.0",
         "@interactive-os/json-document-selection": "^0.1.0-rc.0"
       }
     },
@@ -7065,6 +7088,7 @@
         "@interactive-os/json-document-animation-react": "*",
         "@interactive-os/json-document-annotation": "*",
         "@interactive-os/json-document-calendar": "*",
+        "@interactive-os/json-document-calendar-document": "*",
         "@interactive-os/json-document-collaboration": "*",
         "@interactive-os/json-document-composer": "*",
         "@interactive-os/json-document-composer-react": "*",
diff --git a/package.json b/package.json
index 1cab3947..9267d77d 100644
--- a/package.json
+++ b/package.json
@@ -5,6 +5,7 @@
   "workspaces": [
     "packages/json-document",
     "packages/json-document-selection",
+    "packages/json-document-calendar-document",
     "packages/json-document-editing",
     "packages/json-document-react",
     "packages/json-document-react-hook-form",
diff --git a/packages/json-document-calendar-document/LICENSE b/packages/json-document-calendar-document/LICENSE
new file mode 100644
index 00000000..6a984193
--- /dev/null
+++ b/packages/json-document-calendar-document/LICENSE
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 interactive-os contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/packages/json-document-calendar-document/README.md b/packages/json-document-calendar-document/README.md
new file mode 100644
index 00000000..e3750bc1
--- /dev/null
+++ b/packages/json-document-calendar-document/README.md
@@ -0,0 +1,36 @@
+# @interactive-os/json-document-calendar-document
+
+Calendar Document Type의 RC 공개 소유자입니다. 문서 모델, JSON/Calendar 검증,
+입력 독립 의미 연산과 occurrence/기간 projection을 제공합니다. 의존성은
+JSON Document와 Temporal이며 Editing, Selection, React 또는 DOM을 요구하지 않습니다.
+
+```ts
+import { applyPatch } from "@interactive-os/json-document";
+import {
+  validateCalendarDocument, planCalendarEventEdit, projectCalendarOccurrences,
+} from "@interactive-os/json-document-calendar-document";
+
+const validation = validateCalendarDocument(document);
+if (!validation.ok) throw new Error(validation.reason);
+const plan = planCalendarEventEdit(document.events, {
+  type: "event.move", eventId: "meeting", start: "2026-08-03T10:00",
+}, { allocateId: () => crypto.randomUUID(), calendarIds: new Set(document.calendars.map(calendar => calendar.id)) });
+if (plan.ok) {
+  const result = applyPatch(document, plan.operations);
+  const occurrences = projectCalendarOccurrences(plan.events, "2026-08-03", "2026-08-04");
+}
+```
+
+정본 [API 및 값 계약](docs/api.md)은 이 package에 둡니다. 사이트의
+[Calendar Document API](/docs/api/calendar-document), [Usage / Source](/editors#calendar-editor),
+Usage의 Source 탭에서 실제 소유자와 소비 경로를 확인할 수 있습니다.
+
+`json-document-editing`은 이 package의 연산 결과를 Selection, Clipboard와
+History에 연결합니다. `json-document-calendar`는 Web/Affordance/React와 UI를
+조합합니다. 기존 Editing root의 문서 타입·projection export는 동일 구현의
+호환 경로이며, 새 직접 소비자는 이 package에서 import합니다.
+
+`tests/calendar-document.test.ts`는 editor 없는 소비를 검증합니다.
+Editing의 `tests/conformance/calendar-grammar.test.ts`는 동일 연산을 사용하는
+선택·복사·붙여넣기·삭제·Undo/Redo의 공통 규칙을 검증합니다. Document Type
+소유권의 확정은 wire 프로토콜의 Stable 승격이나 독립 구현 간 호환 보장이 아닙니다.
diff --git a/packages/json-document-calendar-document/docs/api.md b/packages/json-document-calendar-document/docs/api.md
new file mode 100644
index 00000000..1dadbe57
--- /dev/null
+++ b/packages/json-document-calendar-document/docs/api.md
@@ -0,0 +1,101 @@
+## Calendar Document Type 계약 · RC
+
+소유자: `@interactive-os/json-document-calendar-document`, 현재 `0.1.0-rc.0`.
+이 package는 문서 규칙을 소유합니다. 선택·Clipboard·History는
+[Editing 프로파일](/docs/api/editing#calendar-protocol-profile-rc), 사용자 입력과
+UI는 [Calendar Hands](/docs/api/calendar)가 연결합니다. Core Stable 및 Official
+Hands/Editing Grammar의 Draft 지위를 바꾸지 않습니다.
+
+### 모델과 검증
+
+`CalendarDocument`는 `calendars`와 `events`를, `CalendarEvent`는 interval과
+recurrence를 정의합니다. `{ eventId, occurrenceStart }`인 `CalendarOccurrencePoint`는
+문서의 발생분 주소이며 selection 상태가 아닙니다. `CalendarOccurrenceInterval`은
+현재 규칙으로 해석한 `{ eventId, start, end }`입니다.
+
+- `validateCalendarDocument(unknown)`는 JSON과 Calendar 구조·참조·시간 규칙을
+  검사해 `{ ok: true }` 또는 `{ ok: false, code, reason }`을 반환합니다.
+- `assertCalendarDocument(unknown)`는 같은 검사에 실패하면 `TypeError`를 던집니다.
+  검사만 수행하며 입력을 정규화하거나 mutation하지 않습니다. legacy 수용을
+  포함하므로 validator 결과는 필수 필드가 모두 채워졌다는 TypeScript type guard가 아닙니다.
+- calendar의 `id`는 고유한 비어 있지 않은 문자열, `title`은 문자열,
+  `hidden`은 boolean, `color`는 비어 있지 않은 문자열입니다. calendars의 생략은
+  허용하지만 null·문자열 같은 비배열 값은 거절합니다.
+- event는 고유한 비어 있지 않은 `id`, 문자열 `title`, `start < end`를 갖습니다.
+  calendar 목록이 비어 있지 않을 때 비어 있지 않은 `calendarId`는 실제 calendar를 참조합니다.
+- 기존 간단한 문서의 생략된 calendars / allDay / calendarId / recurrence /
+  excludeDates는 빈 목록 / timed / 미지정 / 반복 없음 / 제외 없음으로 읽습니다.
+  이 호환 경로는 잘못된 타입을 생략으로 바꾸지 않습니다.
+
+### 시간과 반복
+
+timed 값은 정확한 `YYYY-MM-DDTHH:mm` local date-time, all-day 값은
+`YYYY-MM-DD`입니다. 둘 다 종료는 exclusive입니다. 8월 1일 하루는
+`start: "2026-08-01", end: "2026-08-02"`입니다. UTC Instant, offset, timezone과
+초 단위는 현재 프로파일에 포함하지 않습니다.
+
+recurrence의 `freq`는 daily / weekly / monthly / yearly, `interval`은 양의 safe
+integer입니다. `until: ""`은 무기한이며 나머지는 발생 시작일 기준 inclusive 날짜입니다.
+`excludeDates`는 발생 시작일을 제외합니다. 월말·윤년의 시작은 Temporal constrain,
+종료는 원본의 local duration을 보존하므로 시작·종료를 따로 constrain하지 않습니다.
+
+### 의미 연산
+
+| API | 입력과 결과 |
+| --- | --- |
+| `planCalendarEventEdit(events, operation, options)` | create/update/move/move-day/resize/occurrence.edit를 events·JSON Patch·affectedOccurrence로 계획 |
+| `planCalendarEventRemoval(events, eventIds)` | 지정한 원본 event들을 제거하는 events·Patch 계획 |
+| `planCalendarOccurrenceRemoval(events, removal)` | 발생분 scope에 따른 제외·시리즈 절단·제거 계획 |
+| `planCalendarVisibility(document, calendarId, hidden)` | 존재하는 calendar의 boolean 가시성 변경 계획 |
+
+모든 plan은 입력을 변경하거나 commit하지 않습니다. 실패하면 `{ ok: false, code,
+reason? }`이며 성공 시 `operations`를 JSONDocument 또는 `applyPatch`에 적용할 수
+있습니다. `affectedOccurrence`는 변경 결과의 문서 주소입니다. 무엇을 선택하고
+어떤 Undo 단위로 묶을지는 Editing이 결정합니다. 기존 Calendar rejection code는
+호환성을 위해 유지하며, `selection.*`라는 code 이름이 Selection 의존성을 뜻하지는 않습니다.
+
+연산의 `events`는 검증된 현재 문서에서 가져옵니다. `calendarIds`에는 그 문서의
+calendar ID 집합을 전달합니다. 생략하면 event의 시간·반복 구조만 검사하므로
+문서 전체의 membership 검증을 대신하지 않습니다. 생성의 `defaultCalendarId`는
+호출자가 고른 기본값이고, 미지정이면 빈 문자열입니다. `allocateId`는 필요한 새 ID를
+공급하며 비어 있거나 이미 있는 ID는 거절합니다. provider 예외는 호출자에게 전파합니다.
+Editing은 기존 bounded ID allocator를 주입합니다.
+
+| scope | 편집 | 삭제 |
+| --- | --- | --- |
+| this | 해당 발생분을 제외하고 독립 일정으로 분리 | 해당 발생분 제외 |
+| this-and-following | 기준일 전날까지 원본을 자르고 이후 시리즈 분리 | 기준일 이후 발생분 제거 |
+| all | 선택한 발생분의 변경량을 원본 시리즈에 적용 | 원본 시리즈 제거 |
+
+시작만 바꾸면 구간 길이를 보존하고 resize는 지정한 경계만 변경합니다. 시리즈
+이동은 유한한 until과 excludeDates를 함께 옮기며 following은 기존 종료와 이후
+제외 날짜를 보존합니다. 월/년 재기준화로 요청한 발생분을 표현할 수 없으면
+`selection.unrepresentable-series-move`로 거절합니다. allDay / calendarId /
+recurrence 자체의 변경은 시리즈 속성 변경입니다.
+
+### Projection과 날짜 값
+
+`projectCalendarOccurrences(events, rangeStart, rangeEnd)`는 `[rangeStart, rangeEnd)`와
+겹치는 발생분을 계산합니다. 범위는 date 문자열입니다. 요청 구간 근처로 seek하며
+400회 같은 lifetime cap은 없습니다. `resolveCalendarOccurrence`는 화면 밖의 주소도
+현재 recurrence와 exclusions로 해석합니다. 잘못된 조회 범위는 빈 결과입니다.
+
+`calendarVisibleEvents`, `calendarEventsOnDay`, `calendarEventsInMonth`,
+`calendarBusyDates`는 문서 조회를, `calendarTimedLayout`, `calendarAllDayLayout`,
+`calendarMonthDayLayout`, `calendarMonthWeekLayout`은 event의 구간/lane projection을
+제공합니다. DOM·CSS·표시 요소의 디자인은 포함하지 않습니다.
+
+`calendarDocumentCalendars` / `calendarDocumentCalendar`는 collection 조회,
+`calendarDatePart` / `calendarIntervalLastDate` / `calendarAllDaySpan`은 시간 값의
+정본 변환입니다. parse/format/add/shift와 recurrence 변경 함수도 같은 owner를
+사용합니다. Calendar 화면의 cell/grid, 날짜 선택과 표시 label은 Calendar Hands에 남습니다.
+
+### 실제 소비와 남은 범위
+
+[Calendar Usage 및 Source](/editors#calendar-editor)는 이 package의 조회·projection을 직접 소비하고,
+Editing이 공개 연산 계획을 통해 변경합니다. Source에서 모델·검증·연산·projection과
+Editing·Hand의 연결을 추적할 수 있습니다. 이 문서 아래에는 전체 export signature가 이어집니다.
+
+timezone/DST, 서버 revision/충돌/재시도, AI command wire, 외부 calendar connector,
+범용 RRULE, 대량 조회 pagination, 프로파일 버전 협상과 독립 구현 conformance는
+TBD입니다. 현재 소유권 및 로컬 RC 동작의 검증과 구분합니다.
diff --git a/packages/json-document-calendar-document/package.json b/packages/json-document-calendar-document/package.json
new file mode 100644
index 00000000..fc22921a
--- /dev/null
+++ b/packages/json-document-calendar-document/package.json
@@ -0,0 +1,24 @@
+{
+  "name": "@interactive-os/json-document-calendar-document",
+  "version": "0.1.0-rc.0",
+  "description": "Calendar Document Type: model, validation, semantic operations and projections without an editor or UI.",
+  "type": "module",
+  "license": "MIT",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "repository": { "type": "git", "url": "git+https://github.com/developer-1px/json-document.git", "directory": "packages/json-document-calendar-document" },
+  "publishConfig": { "access": "public", "provenance": true, "tag": "next" },
+  "files": ["dist", "!dist/.tsbuildinfo", "README.md", "docs", "LICENSE"],
+  "exports": { ".": { "types": "./dist/index.d.ts", "import": "./dist/index.js" } },
+  "scripts": {
+    "build": "tsc -b tsconfig.json",
+    "pretypecheck": "node ../../scripts/workspace-tasks.mjs build-dependencies",
+    "typecheck": "tsc -p tsconfig.test.json --noEmit",
+    "test": "vitest run --config vitest.config.ts",
+    "verify": "npm run typecheck && npm test && npm run build"
+  },
+  "peerDependencies": { "@interactive-os/json-document": "^3.0.0" },
+  "dependencies": { "@js-temporal/polyfill": "^0.5.1" },
+  "devDependencies": { "@interactive-os/json-document": "*", "@types/node": "^25.9.0", "typescript": "^5.0.0", "vitest": "^4.1.7" }
+}
diff --git a/packages/json-document-calendar-document/src/calendar-model.ts b/packages/json-document-calendar-document/src/calendar-model.ts
new file mode 100644
index 00000000..d8a8ff26
--- /dev/null
+++ b/packages/json-document-calendar-document/src/calendar-model.ts
@@ -0,0 +1,42 @@
+import type { JSONValue } from "@interactive-os/json-document";
+
+export interface CalendarCalendar extends Record<string, JSONValue> {
+  readonly id: string;
+  readonly title: string;
+  readonly hidden: boolean;
+  readonly color: string;
+}
+
+export interface CalendarRecurrence extends Record<string, JSONValue> {
+  readonly freq: "daily" | "weekly" | "monthly" | "yearly";
+  readonly interval: number;
+  readonly until: string;
+}
+
+export interface CalendarEvent extends Record<string, JSONValue> {
+  readonly id: string;
+  readonly title: string;
+  readonly start: string;
+  readonly end: string;
+  readonly allDay: boolean;
+  readonly calendarId: string;
+  readonly recurrence: CalendarRecurrence | null;
+  readonly excludeDates: ReadonlyArray<string>;
+}
+
+export interface CalendarDocument extends Record<string, JSONValue> {
+  readonly calendars: ReadonlyArray<CalendarCalendar>;
+  readonly events: ReadonlyArray<CalendarEvent>;
+}
+
+export interface CalendarOccurrencePoint extends Record<string, JSONValue> {
+  readonly eventId: string;
+  readonly occurrenceStart: string;
+}
+
+/** A resolved document occurrence, independent of selection or an editor. */
+export interface CalendarOccurrenceInterval {
+  readonly eventId: string;
+  readonly start: string;
+  readonly end: string;
+}
diff --git a/packages/json-document-editing/src/calendar-occurrence.ts b/packages/json-document-calendar-document/src/calendar-occurrence.ts
similarity index 98%
rename from packages/json-document-editing/src/calendar-occurrence.ts
rename to packages/json-document-calendar-document/src/calendar-occurrence.ts
index 363f83ca..a2e8920c 100644
--- a/packages/json-document-editing/src/calendar-occurrence.ts
+++ b/packages/json-document-calendar-document/src/calendar-occurrence.ts
@@ -1,5 +1,5 @@
 import { Temporal } from "@js-temporal/polyfill";
-import type { CalendarEvent, CalendarOccurrencePoint, CalendarOccurrenceSelection, CalendarRecurrence } from "./calendar.js";
+import type { CalendarEvent, CalendarOccurrencePoint, CalendarOccurrenceInterval, CalendarRecurrence } from "./calendar-model.js";
 import {
   addCalendarDate,
   calendarDatePart,
@@ -108,7 +108,7 @@ export function projectCalendarOccurrences(
 export function resolveCalendarOccurrence(
   events: ReadonlyArray<CalendarEvent>,
   point: CalendarOccurrencePoint,
-): CalendarOccurrenceSelection | null {
+): CalendarOccurrenceInterval | null {
   const event = events.find((candidate) => candidate.id === point.eventId);
   if (event === undefined || typeof point.occurrenceStart !== "string") return null;
   const day = calendarDatePart(point.occurrenceStart);
diff --git a/packages/json-document-editing/src/calendar-event-plan.ts b/packages/json-document-calendar-document/src/calendar-operation.ts
similarity index 61%
rename from packages/json-document-editing/src/calendar-event-plan.ts
rename to packages/json-document-calendar-document/src/calendar-operation.ts
index 497aca32..bd959002 100644
--- a/packages/json-document-editing/src/calendar-event-plan.ts
+++ b/packages/json-document-calendar-document/src/calendar-operation.ts
@@ -1,27 +1,62 @@
 import { buildPointer, type JSONPatchOperation } from "@interactive-os/json-document";
-import type { CalendarEvent, CalendarIntent, CalendarOccurrencePoint } from "./calendar.js";
+import type { CalendarDocument, CalendarEvent, CalendarOccurrencePoint, CalendarRecurrence } from "./calendar-model.js";
 import { calendarEventExcludeDates, calendarEventRecurrence, resolveCalendarOccurrence } from "./calendar-occurrence.js";
 import {
   addCalendarDate, calendarAllDaySpan, calendarDatePart, calendarDaysBetween,
-  calendarEventIntervalAt, calendarMinutesBetween, formatCalendarInstant,
+  calendarDocumentCalendars, calendarEventIntervalAt, calendarMinutesBetween, formatCalendarInstant,
   parseCalendarDate, parseCalendarInstant, validateCalendarEvent,
 } from "./calendar-validation.js";
 
-type CalendarEventIntent = Extract<CalendarIntent, { type:
-  "event.create" | "event.update" | "event.move" | "event.move-day" | "event.resize" | "occurrence.edit"
-}>;
+export type CalendarEventOperation =
+  | {
+      readonly type: "event.create";
+      readonly start: string;
+      readonly end: string;
+      readonly title?: string;
+      readonly allDay?: boolean;
+      readonly calendarId?: string;
+      readonly recurrence?: CalendarRecurrence | null;
+    }
+  | { readonly type: "event.move"; readonly eventId: string; readonly start: string }
+  | { readonly type: "event.resize"; readonly eventId: string; readonly edge: "start" | "end"; readonly instant: string }
+  | { readonly type: "event.move-day"; readonly eventId: string; readonly day: string }
+  | {
+      readonly type: "event.update";
+      readonly eventId: string;
+      readonly title?: string;
+      readonly start?: string;
+      readonly end?: string;
+      readonly allDay?: boolean;
+      readonly calendarId?: string;
+      readonly recurrence?: CalendarRecurrence | null;
+    }
+  | {
+      readonly type: "occurrence.edit";
+      readonly eventId: string;
+      readonly occurrenceStart: string;
+      readonly scope: "this" | "this-and-following" | "all";
+      readonly title?: string;
+      readonly start?: string;
+      readonly end?: string;
+    };
 
-type CalendarEventPlan = {
+export type CalendarOccurrenceRemoval = {
+  readonly eventId: string;
+  readonly occurrenceStart: string;
+  readonly scope: "this" | "this-and-following" | "all";
+};
+
+export type CalendarEventPlan = {
   readonly ok: true;
   readonly events: ReadonlyArray<CalendarEvent>;
   readonly operations: ReadonlyArray<JSONPatchOperation>;
-  readonly selected: CalendarOccurrencePoint;
+  readonly affectedOccurrence: CalendarOccurrencePoint;
 } | { readonly ok: false; readonly code: string; readonly reason?: string };
 
 /** Calendar's single event/series semantics, shared by commit, preview and group moves. */
 export function planCalendarEventEdit(
   events: ReadonlyArray<CalendarEvent>,
-  intent: CalendarEventIntent,
+  intent: CalendarEventOperation,
   options: { readonly allocateId: () => string; readonly calendarIds?: ReadonlySet<string>; readonly defaultCalendarId?: string },
 ): CalendarEventPlan {
   const index = intent.type === "event.create" ? -1 : events.findIndex((event) => event.id === intent.eventId);
@@ -36,13 +71,14 @@ export function planCalendarEventEdit(
       operations: fields === undefined
         ? [{ op: "replace", path: buildPointer(["events", index]), value: next }]
         : fields.map((field) => ({ op: "replace", path: buildPointer(["events", index, field]), value: next[field] })),
-      selected: { eventId: next.id, occurrenceStart: selectedStart },
+      affectedOccurrence: { eventId: next.id, occurrenceStart: selectedStart },
     };
   }
 
   function append(next: CalendarEvent, preceding: ReadonlyArray<JSONPatchOperation> = [], previous?: CalendarEvent): CalendarEventPlan {
     const validation = validateCalendarEvent(next, options.calendarIds);
     if (!validation.ok) return validation;
+    if (events.some((event) => event.id === next.id)) return failure("event.duplicate-id");
     if (previous !== undefined) {
       const previousValidation = validateCalendarEvent(previous, options.calendarIds);
       if (!previousValidation.ok) return previousValidation;
@@ -53,7 +89,7 @@ export function planCalendarEventEdit(
       ok: true,
       events: [...events.map((item, position) => position === index && previous !== undefined ? previous : item), appended],
       operations: [...preceding, { op: "add", path: `/events/${events.length}`, value: appended }],
-      selected: { eventId: next.id, occurrenceStart: next.start },
+      affectedOccurrence: { eventId: next.id, occurrenceStart: next.start },
     };
   }
 
@@ -99,6 +135,7 @@ export function planCalendarEventEdit(
       recurrence: intent.recurrence === undefined ? event.recurrence : intent.recurrence });
   }
 
+  if (intent.type !== "occurrence.edit") return failure("operation.unsupported");
   if (intent.scope !== "this" && intent.scope !== "this-and-following" && intent.scope !== "all") return failure("occurrence.invalid-scope");
   const occurrence = resolveCalendarOccurrence(events, { eventId: event.id, occurrenceStart: intent.occurrenceStart });
   if (occurrence === null) return failure("selection.stale-occurrence");
@@ -119,7 +156,7 @@ export function planCalendarEventEdit(
     const shifted = shiftRecurrence(event, occurrence.start, interval.start);
     const plan = replace({ ...next, start, end, ...shifted }, interval.start);
     if (!plan.ok) return plan;
-    return resolveCalendarOccurrence(plan.events, plan.selected)?.end === interval.end
+    return resolveCalendarOccurrence(plan.events, plan.affectedOccurrence)?.end === interval.end
       ? plan : failure("selection.unrepresentable-series-move");
   }
   const day = calendarDatePart(occurrence.start);
@@ -156,4 +193,53 @@ function shiftRecurrence(event: CalendarEvent, origin: string, next: string): Pi
   };
 }
 
-function failure(code: string): CalendarEventPlan { return { ok: false, code }; }
+export type CalendarPatchPlan = { readonly ok: true; readonly operations: ReadonlyArray<JSONPatchOperation> }
+  | { readonly ok: false; readonly code: string; readonly reason?: string };
+export type CalendarEventsPlan = (Extract<CalendarPatchPlan, { ok: true }> & { readonly events: ReadonlyArray<CalendarEvent> })
+  | Extract<CalendarPatchPlan, { ok: false }>;
+
+/** Remove document records; choosing the next selection belongs to Editing. */
+export function planCalendarEventRemoval(events: ReadonlyArray<CalendarEvent>, eventIds: ReadonlyArray<string>): CalendarEventsPlan {
+  const removing = new Set(eventIds);
+  const knownIds = new Set(events.map((event) => event.id));
+  if (removing.size === 0 || eventIds.some((id) => !knownIds.has(id))) return failure("selection.event-not-found");
+  return {
+    ok: true,
+    events: events.filter((event) => !removing.has(event.id)),
+    operations: events.flatMap((event, index): JSONPatchOperation[] => removing.has(event.id)
+      ? [{ op: "remove", path: buildPointer(["events", index]) }] : []).reverse(),
+  };
+}
+
+/** Exclusion and recurrence truncation have the same meaning without an editor. */
+export function planCalendarOccurrenceRemoval(events: ReadonlyArray<CalendarEvent>, removal: CalendarOccurrenceRemoval): CalendarEventsPlan {
+  const index = events.findIndex((event) => event.id === removal.eventId);
+  const event = events[index];
+  if (event === undefined) return failure("selection.event-not-found");
+  if (removal.scope !== "this" && removal.scope !== "this-and-following" && removal.scope !== "all") return failure("occurrence.invalid-scope");
+  if (resolveCalendarOccurrence(events, removal) === null) return failure("selection.stale-occurrence");
+  const recurrence = calendarEventRecurrence(event);
+  if (recurrence === null || removal.scope === "all") return planCalendarEventRemoval(events, [event.id]);
+  const day = calendarDatePart(removal.occurrenceStart);
+  const until = addCalendarDate(day, -1);
+  if (removal.scope === "this-and-following" && (until === null || until < calendarDatePart(event.start))) {
+    return planCalendarEventRemoval(events, [event.id]);
+  }
+  const field = removal.scope === "this" ? "excludeDates" : "recurrence";
+  const value = removal.scope === "this" ? [...calendarEventExcludeDates(event), day] : { ...recurrence, until: until! };
+  return {
+    ok: true,
+    events: events.map((item, position) => position === index ? { ...item, [field]: value } : item),
+    operations: [{ op: field === "excludeDates" ? "add" : "replace", path: buildPointer(["events", index, field]), value }],
+  };
+}
+
+export function planCalendarVisibility(document: CalendarDocument, calendarId: string, hidden: boolean): CalendarPatchPlan {
+  if (typeof hidden !== "boolean") return failure("calendar.invalid-hidden");
+  const index = calendarDocumentCalendars(document).findIndex((calendar) => calendar.id === calendarId);
+  return index < 0 ? failure("calendar.not-found") : {
+    ok: true, operations: [{ op: "replace", path: buildPointer(["calendars", index, "hidden"]), value: hidden }],
+  };
+}
+
+function failure(code: string): { readonly ok: false; readonly code: string } { return { ok: false, code }; }
diff --git a/packages/json-document-calendar-document/src/calendar-projection.ts b/packages/json-document-calendar-document/src/calendar-projection.ts
new file mode 100644
index 00000000..fe3f8183
--- /dev/null
+++ b/packages/json-document-calendar-document/src/calendar-projection.ts
@@ -0,0 +1,284 @@
+import { Temporal } from "@js-temporal/polyfill";
+import type { CalendarDocument, CalendarEvent } from "./calendar-model.js";
+import { projectCalendarOccurrences } from "./calendar-occurrence.js";
+import {
+  addCalendarDate, calendarDatePart, calendarDocumentCalendars, calendarDocumentEvents,
+  calendarEventBounds, calendarIntervalLastDate, calendarMinutesBetween,
+  isCalendarAllDay, parseCalendarDate, parseCalendarInstant,
+} from "./calendar-validation.js";
+
+export function calendarVisibleEvents(document: CalendarDocument): ReadonlyArray<CalendarEvent> {
+  const events = calendarDocumentEvents(document);
+  const hidden = new Set(calendarDocumentCalendars(document).filter((item) => item.hidden).map((item) => item.id));
+  if (hidden.size === 0) return events;
+  return events.filter((event) => !hidden.has(event.calendarId));
+}
+
+export function calendarNowMarker(nowInstant: string, day: string): { readonly minutes: number } | null {
+  if (calendarDatePart(nowInstant) !== day) return null;
+  const start = parseCalendarInstant(`${day}T00:00`);
+  const now = parseCalendarInstant(nowInstant);
+  if (start === null || now === null) return null;
+  return { minutes: calendarMinutesBetween(start, now) };
+}
+
+export function calendarEventsOnDay(
+  events: ReadonlyArray<CalendarEvent>,
+  day: string,
+): ReadonlyArray<CalendarEvent> {
+  const next = addCalendarDate(day, 1);
+  if (next === null) return [];
+  return projectCalendarOccurrences(events, day, next).map((item) => ({
+    ...item.event,
+    start: item.start,
+    end: item.end,
+  }));
+}
+
+export function calendarMonthDayLayout(
+  events: ReadonlyArray<CalendarEvent>,
+  day: string,
+  rowLimit: number,
+): {
+  readonly events: ReadonlyArray<CalendarEvent>;
+  readonly hiddenCount: number;
+} {
+  const onDay = [...calendarEventsOnDay(events, day)].sort((left, right) => {
+    const leftAllDay = isCalendarAllDay(left);
+    const rightAllDay = isCalendarAllDay(right);
+    if (leftAllDay !== rightAllDay) return leftAllDay ? -1 : 1;
+    return left.start.localeCompare(right.start);
+  });
+  if (rowLimit < 1) return { events: [], hiddenCount: onDay.length };
+  if (onDay.length <= rowLimit) return { events: onDay, hiddenCount: 0 };
+  const shown = Math.max(0, rowLimit - 1);
+  return { events: onDay.slice(0, shown), hiddenCount: onDay.length - shown };
+}
+
+export function calendarBusyDates(
+  events: ReadonlyArray<CalendarEvent>,
+  rangeStart: string,
+  rangeEnd: string,
+): ReadonlySet<string> {
+  const dates = new Set<string>();
+  for (const item of projectCalendarOccurrences(events, rangeStart, rangeEnd)) {
+    for (const day of calendarOccurrenceDays(item.start, item.end, isCalendarAllDay(item.event))) {
+      if (day >= rangeStart && day < rangeEnd) dates.add(day);
+    }
+  }
+  return dates;
+}
+
+function calendarOccurrenceDays(start: string, end: string, allDay: boolean): ReadonlyArray<string> {
+  const first = calendarDatePart(start);
+  const last = calendarIntervalLastDate(start, end, allDay);
+  const days: string[] = [];
+  for (let day = first; day <= last; ) {
+    days.push(day);
+    const next = addCalendarDate(day, 1);
+    if (next === null) break;
+    day = next;
+  }
+  return days;
+}
+
+export function calendarTimedLayout(
+  events: ReadonlyArray<CalendarEvent>,
+  day: string,
+): ReadonlyArray<{
+  readonly event: CalendarEvent;
+  readonly startMinutes: number;
+  readonly endMinutes: number;
+  readonly lane: number;
+  readonly laneCount: number;
+}> {
+  const dayStart = parseCalendarInstant(`${day}T00:00`);
+  if (dayStart === null) return [];
+  const dayEnd = dayStart.add({ days: 1 });
+  const next = addCalendarDate(day, 1);
+  if (next === null) return [];
+  const layout: Array<{ event: CalendarEvent; startMinutes: number; endMinutes: number }> = [];
+  for (const item of projectCalendarOccurrences(events, day, next)) {
+    if (isCalendarAllDay(item.event)) continue;
+    const bounds = calendarEventBounds({ ...item.event, start: item.start, end: item.end });
+    if (bounds === null || Temporal.PlainDateTime.compare(bounds.to, dayStart) <= 0 || Temporal.PlainDateTime.compare(bounds.from, dayEnd) >= 0) continue;
+    const clippedStart = Temporal.PlainDateTime.compare(bounds.from, dayStart) < 0 ? dayStart : bounds.from;
+    const clippedEnd = Temporal.PlainDateTime.compare(bounds.to, dayEnd) > 0 ? dayEnd : bounds.to;
+    layout.push({
+      event: { ...item.event, start: item.start, end: item.end },
+      startMinutes: calendarMinutesBetween(dayStart, clippedStart),
+      endMinutes: calendarMinutesBetween(dayStart, clippedEnd),
+    });
+  }
+  const sorted = layout.sort((left, right) => left.startMinutes - right.startMinutes || left.endMinutes - right.endMinutes);
+  const positioned: Array<typeof sorted[number] & { lane: number; laneCount: number }> = [];
+  let groupStart = 0;
+  while (groupStart < sorted.length) {
+    let groupEnd = groupStart + 1;
+    let occupiedUntil = sorted[groupStart]!.endMinutes;
+    while (groupEnd < sorted.length && sorted[groupEnd]!.startMinutes < occupiedUntil) {
+      occupiedUntil = Math.max(occupiedUntil, sorted[groupEnd]!.endMinutes);
+      groupEnd += 1;
+    }
+    const laneEnds: number[] = [];
+    const group = sorted.slice(groupStart, groupEnd).map((item) => {
+      const available = laneEnds.findIndex((end) => end <= item.startMinutes);
+      const lane = available === -1 ? laneEnds.length : available;
+      laneEnds[lane] = item.endMinutes;
+      return { ...item, lane };
+    });
+    positioned.push(...group.map((item) => ({ ...item, laneCount: laneEnds.length })));
+    groupStart = groupEnd;
+  }
+  return positioned;
+}
+
+export function calendarAllDayLayout(
+  events: ReadonlyArray<CalendarEvent>,
+  days: ReadonlyArray<string>,
+): ReadonlyArray<{
+  readonly event: CalendarEvent;
+  readonly startIndex: number;
+  readonly span: number;
+  readonly lane: number;
+  readonly laneCount: number;
+}> {
+  const rangeStart = days[0];
+  const rangeLast = days.at(-1);
+  if (rangeStart === undefined || rangeLast === undefined) return [];
+  const rangeEnd = addCalendarDate(rangeLast, 1);
+  if (rangeEnd === null) return [];
+  const layout: Array<{ event: CalendarEvent; startIndex: number; span: number }> = [];
+  for (const item of projectCalendarOccurrences(events, rangeStart, rangeEnd)) {
+    if (!isCalendarAllDay(item.event)) continue;
+    const clipped = clipAllDayToDays(item.start, item.end, days);
+    if (clipped === null) continue;
+    layout.push({
+      event: { ...item.event, start: item.start, end: item.end },
+      startIndex: clipped.startIndex,
+      span: clipped.span,
+    });
+  }
+  const sorted = layout.sort((left, right) => left.startIndex - right.startIndex || right.span - left.span);
+  const positioned = assignCalendarSpanLanes(sorted);
+  const laneCount = Math.max(1, positioned[0]?.laneCount ?? 0);
+  return positioned.map((item) => ({ ...item, laneCount }));
+}
+
+export function calendarMonthWeekLayout(
+  events: ReadonlyArray<CalendarEvent>,
+  days: ReadonlyArray<string>,
+  rowLimit: number,
+): {
+  readonly items: ReadonlyArray<{
+    readonly event: CalendarEvent;
+    readonly startIndex: number;
+    readonly span: number;
+    readonly lane: number;
+  }>;
+  readonly hiddenCounts: ReadonlyArray<number>;
+  readonly laneCount: number;
+} {
+  const empty = { items: [], hiddenCounts: days.map(() => 0), laneCount: 0 };
+  const rangeStart = days[0];
+  const rangeLast = days.at(-1);
+  if (rangeStart === undefined || rangeLast === undefined) return empty;
+  const rangeEnd = addCalendarDate(rangeLast, 1);
+  if (rangeEnd === null) return empty;
+  const layout: Array<{ event: CalendarEvent; startIndex: number; span: number }> = [];
+  for (const item of projectCalendarOccurrences(events, rangeStart, rangeEnd)) {
+    const occurrence = { ...item.event, start: item.start, end: item.end };
+    const clipped = isCalendarAllDay(occurrence)
+      ? clipAllDayToDays(item.start, item.end, days)
+      : clipTimedToDays(item.start, item.end, days);
+    if (clipped === null) continue;
+    layout.push({ event: occurrence, startIndex: clipped.startIndex, span: clipped.span });
+  }
+  layout.sort((left, right) => {
+    if (left.startIndex !== right.startIndex) return left.startIndex - right.startIndex;
+    const leftAllDay = isCalendarAllDay(left.event) ? 0 : 1;
+    const rightAllDay = isCalendarAllDay(right.event) ? 0 : 1;
+    if (leftAllDay !== rightAllDay) return leftAllDay - rightAllDay;
+    return right.span - left.span || left.event.start.localeCompare(right.event.start);
+  });
+  const positioned = assignCalendarSpanLanes(layout);
+  const covering = (index: number) => positioned.filter((item) => (
+    index >= item.startIndex && index < item.startIndex + item.span
+  ));
+  const overflow = days.some((_, index) => covering(index).length > rowLimit);
+  const visibleLaneCount = overflow
+    ? Math.max(0, rowLimit - 1)
+    : positioned.reduce((max, item) => Math.max(max, item.lane + 1), 0);
+  return {
+    items: positioned.filter((item) => item.lane < visibleLaneCount),
+    hiddenCounts: days.map((_, index) => covering(index).filter((item) => item.lane >= visibleLaneCount).length),
+    laneCount: visibleLaneCount,
+  };
+}
+
+function assignCalendarSpanLanes<T extends { readonly startIndex: number; readonly span: number }>(
+  layout: ReadonlyArray<T>,
+): ReadonlyArray<T & { readonly lane: number; readonly laneCount: number }> {
+  const laneEnds: number[] = [];
+  const positioned = layout.map((item) => {
+    const available = laneEnds.findIndex((end) => end <= item.startIndex);
+    const lane = available === -1 ? laneEnds.length : available;
+    laneEnds[lane] = item.startIndex + item.span;
+    return { ...item, lane };
+  });
+  const laneCount = laneEnds.length;
+  return positioned.map((item) => ({ ...item, laneCount }));
+}
+
+function clipTimedToDays(
+  start: string,
+  end: string,
+  days: ReadonlyArray<string>,
+): { readonly startIndex: number; readonly span: number } | null {
+  let startIndex = -1;
+  let lastIndex = -1;
+  for (const day of calendarOccurrenceDays(start, end, false)) {
+    const index = days.indexOf(day);
+    if (index < 0) continue;
+    if (startIndex < 0) startIndex = index;
+    lastIndex = index;
+  }
+  if (startIndex < 0 || lastIndex < startIndex) return null;
+  return { startIndex, span: lastIndex - startIndex + 1 };
+}
+
+function clipAllDayToDays(
+  start: string,
+  end: string,
+  days: ReadonlyArray<string>,
+): { readonly startIndex: number; readonly span: number } | null {
+  const first = days[0];
+  const last = days.at(-1);
+  if (first === undefined || last === undefined) return null;
+  const visibleEnd = addCalendarDate(last, 1);
+  if (visibleEnd === null) return null;
+  const startDate = calendarDatePart(start);
+  const exclusiveEnd = calendarDatePart(end);
+  if (exclusiveEnd <= first || startDate >= visibleEnd) return null;
+  const foundStart = days.indexOf(startDate);
+  const foundEnd = days.indexOf(exclusiveEnd);
+  const startIndex = foundStart >= 0 ? foundStart : startDate < first ? 0 : -1;
+  const endIndex = foundEnd >= 0 ? foundEnd : exclusiveEnd >= visibleEnd ? days.length : -1;
+  if (startIndex < 0 || endIndex < 0 || endIndex <= startIndex) return null;
+  return { startIndex, span: endIndex - startIndex };
+}
+
+export function calendarEventsInMonth(
+  events: ReadonlyArray<CalendarEvent>,
+  month: string,
+): ReadonlyArray<CalendarEvent> {
+  const start = `${month}-01`;
+  const startUtc = parseCalendarDate(start);
+  if (startUtc === null) return [];
+  const end = Temporal.PlainYearMonth.from(month).add({ months: 1 }).toPlainDate({ day: 1 }).toString();
+  return projectCalendarOccurrences(events, start, end).map((item) => ({
+    ...item.event,
+    start: item.start,
+    end: item.end,
+  }));
+}
diff --git a/packages/json-document-editing/src/calendar-validation.ts b/packages/json-document-calendar-document/src/calendar-validation.ts
similarity index 81%
rename from packages/json-document-editing/src/calendar-validation.ts
rename to packages/json-document-calendar-document/src/calendar-validation.ts
index 3d0da3a4..268f5713 100644
--- a/packages/json-document-editing/src/calendar-validation.ts
+++ b/packages/json-document-calendar-document/src/calendar-validation.ts
@@ -1,14 +1,9 @@
 import { Temporal } from "@js-temporal/polyfill";
-import type { CalendarCalendar, CalendarDocument, CalendarEvent, CalendarRecurrence, CalendarView } from "./calendar.js";
+import { isJSONValue } from "@interactive-os/json-document";
+import type { CalendarCalendar, CalendarDocument, CalendarEvent, CalendarRecurrence } from "./calendar-model.js";
 
 const DATE = /^(\d{4})-(\d{2})-(\d{2})$/;
 const DATETIME = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2})$/;
-const CALENDAR_VIEWS: ReadonlySet<string> = new Set(["day", "week", "month", "year"]);
-
-export function parseCalendarView(value: unknown): CalendarView | null {
-  return typeof value === "string" && CALENDAR_VIEWS.has(value) ? value as CalendarView : null;
-}
-
 export function calendarDocumentCalendars(document: CalendarDocument): ReadonlyArray<CalendarCalendar> {
   return Array.isArray(document.calendars) ? document.calendars : [];
 }
@@ -21,27 +16,51 @@ export function calendarDocumentEvents(document: CalendarDocument): ReadonlyArra
   return Array.isArray(document.events) ? document.events : [];
 }
 
-export function assertCalendarDocument(document: CalendarDocument): void {
-  if (!Array.isArray(document.events)) throw new TypeError("Calendar events must be an array.");
+export function assertCalendarDocument(value: unknown): void {
+  const result = validateCalendarDocument(value);
+  if (!result.ok) throw new TypeError(result.reason);
+}
+
+/** Validate canonical JSON and Calendar invariants without creating an Editing session. */
+export function validateCalendarDocument(value: unknown): CalendarValidationResult {
+  if (!isJSONValue(value) || typeof value !== "object" || value === null || Array.isArray(value)) {
+    return invalidCalendar("Calendar documents must be JSON objects.");
+  }
+  const document = value as unknown as CalendarDocument;
+  if (!Array.isArray(document.events)) return invalidCalendar("Calendar events must be an array.");
+  if (document.calendars !== undefined && !Array.isArray(document.calendars)) {
+    return invalidCalendar("Calendar calendars must be an array when present.");
+  }
   const calendarIds = new Set<string>();
   for (const calendar of calendarDocumentCalendars(document)) {
-    if (calendar.id.length === 0) throw new Error("Calendar ids must not be empty.");
-    if (calendarIds.has(calendar.id)) throw new Error(`Calendar id must be unique: ${JSON.stringify(calendar.id)}.`);
+    if (typeof calendar !== "object" || calendar === null || Array.isArray(calendar)
+      || typeof calendar.id !== "string" || calendar.id.length === 0) {
+      return invalidCalendar("Calendar ids must be nonempty strings.");
+    }
+    if (calendarIds.has(calendar.id)) return invalidCalendar(`Calendar id must be unique: ${JSON.stringify(calendar.id)}.`);
+    if (typeof calendar.title !== "string" || typeof calendar.hidden !== "boolean") {
+      return invalidCalendar("Calendar title must be a string and hidden must be a boolean.");
+    }
     if (typeof calendar.color !== "string" || calendar.color.length === 0) {
-      throw new Error(`Calendar color must not be empty: ${JSON.stringify(calendar.id)}.`);
+      return invalidCalendar(`Calendar color must not be empty: ${JSON.stringify(calendar.id)}.`);
     }
     calendarIds.add(calendar.id);
   }
   const ids = new Set<string>();
   for (const event of calendarDocumentEvents(document)) {
     const result = validateCalendarEvent(event, calendarIds);
-    if (!result.ok) throw new TypeError(result.reason);
-    if (ids.has(event.id)) throw new Error(`Calendar event id must be unique: ${JSON.stringify(event.id)}.`);
+    if (!result.ok) return result;
+    if (ids.has(event.id)) return invalidCalendar(`Calendar event id must be unique: ${JSON.stringify(event.id)}.`);
     ids.add(event.id);
   }
+  return { ok: true };
+}
+
+function invalidCalendar(reason: string): CalendarValidationResult {
+  return { ok: false, code: "calendar.invalid-document", reason };
 }
 
-type CalendarValidationResult = { readonly ok: true } | {
+export type CalendarValidationResult = { readonly ok: true } | {
   readonly ok: false; readonly code: string; readonly reason: string;
 };
 
diff --git a/packages/json-document-calendar-document/src/index.ts b/packages/json-document-calendar-document/src/index.ts
new file mode 100644
index 00000000..25a27031
--- /dev/null
+++ b/packages/json-document-calendar-document/src/index.ts
@@ -0,0 +1,52 @@
+export type {
+  CalendarCalendar, CalendarDocument, CalendarEvent, CalendarRecurrence,
+  CalendarOccurrencePoint, CalendarOccurrenceInterval,
+} from "./calendar-model.js";
+export { planCalendarEventEdit, planCalendarEventRemoval, planCalendarOccurrenceRemoval, planCalendarVisibility } from "./calendar-operation.js";
+export type { CalendarEventOperation, CalendarEventPlan, CalendarOccurrenceRemoval, CalendarPatchPlan, CalendarEventsPlan } from "./calendar-operation.js";
+export type { CalendarValidationResult } from "./calendar-validation.js";
+export {
+  calendarDocumentCalendars,
+  calendarDocumentCalendar,
+  calendarDocumentEvents,
+  assertCalendarDocument,
+  validateCalendarDocument,
+  validateCalendarEvent,
+  isCalendarRecurrence,
+  isCalendarAllDay,
+  parseCalendarInstant,
+  formatCalendarInstant,
+  parseCalendarDate,
+  formatCalendarDate,
+  addCalendarDate,
+  calendarAllDaySpan,
+  calendarShiftInstant,
+  calendarInstantAt,
+  calendarDatePart,
+  calendarIntervalLastDate,
+  calendarEventBounds,
+  calendarDaysBetween,
+  calendarMinutesBetween,
+  calendarEventIntervalAt,
+} from "./calendar-validation.js";
+export {
+  calendarEventRecurrence,
+  calendarRecurrenceWithFrequency,
+  calendarRecurrenceWithInterval,
+  calendarRecurrenceWithUntil,
+  calendarEventExcludeDates,
+  projectCalendarOccurrences,
+  resolveCalendarOccurrence,
+} from "./calendar-occurrence.js";
+export type { CalendarOccurrence } from "./calendar-occurrence.js";
+export {
+  calendarVisibleEvents,
+  calendarNowMarker,
+  calendarEventsOnDay,
+  calendarMonthDayLayout,
+  calendarBusyDates,
+  calendarTimedLayout,
+  calendarAllDayLayout,
+  calendarMonthWeekLayout,
+  calendarEventsInMonth,
+} from "./calendar-projection.js";
diff --git a/packages/json-document-calendar-document/tests/calendar-document.test.ts b/packages/json-document-calendar-document/tests/calendar-document.test.ts
new file mode 100644
index 00000000..1eaf27f9
--- /dev/null
+++ b/packages/json-document-calendar-document/tests/calendar-document.test.ts
@@ -0,0 +1,106 @@
+import { applyPatch } from "@interactive-os/json-document";
+import { describe, expect, test } from "vitest";
+import {
+  assertCalendarDocument, validateCalendarDocument, planCalendarEventEdit,
+  planCalendarEventRemoval, planCalendarOccurrenceRemoval, planCalendarVisibility,
+  projectCalendarOccurrences, calendarVisibleEvents,
+  type CalendarDocument, type CalendarEventOperation,
+} from "../src/index.js";
+
+const document = (): CalendarDocument => ({
+  calendars: [{ id: "work", title: "Work", hidden: false, color: "accent" }],
+  events: [{ id: "a", title: "A", start: "2026-08-01T09:00", end: "2026-08-01T10:00", allDay: false,
+    calendarId: "work", recurrence: { freq: "daily", interval: 1, until: "2026-08-08" }, excludeDates: [] }],
+});
+
+describe("Calendar Document Type public contract", () => {
+  test("validates without editing state and preserves canonical and legacy inputs", () => {
+    for (const value of [document(), { events: [{ id: "legacy", title: "L", start: "2026-08-01T09:00", end: "2026-08-01T10:00" }] }]) {
+      const before = structuredClone(value);
+      expect(validateCalendarDocument(value)).toEqual({ ok: true });
+      expect(() => assertCalendarDocument(value)).not.toThrow();
+      expect(value).toEqual(before);
+    }
+  });
+
+  test.each([
+    "work", null, 123, {}, [null], [123], [[]],
+    [{ id: 123, title: "Work", hidden: false, color: "accent" }],
+    [{ id: "", title: "Work", hidden: false, color: "accent" }],
+    [{ id: "work", title: 123, hidden: false, color: "accent" }],
+    [{ id: "work", title: "Work", hidden: "false", color: "accent" }],
+    [{ id: "work", title: "Work", hidden: false, color: "" }],
+  ])("rejects malformed calendar containers and records: %j", (calendars) => {
+    const value = { calendars, events: [] };
+    expect(validateCalendarDocument(value)).toMatchObject({ ok: false, code: "calendar.invalid-document" });
+    expect(() => assertCalendarDocument(value)).toThrow(TypeError);
+  });
+
+  test("validates document identity, membership and JSON extension fields", () => {
+    const value = document();
+    for (const invalid of [
+      { ...value, calendars: [...value.calendars, { ...value.calendars[0]! }] },
+      { ...value, events: [...value.events, { ...value.events[0]!, recurrence: { ...value.events[0]!.recurrence! }, excludeDates: [] }] },
+      { ...value, events: [{ ...value.events[0]!, calendarId: "missing" }] },
+      { ...value, metadata: Number.NaN },
+    ]) expect(validateCalendarDocument(invalid).ok).toBe(false);
+  });
+
+  test.each(["this", "this-and-following", "all"] as const)("plans %s edits as document operations, not selection transitions", (scope) => {
+    const value = document();
+    const before = structuredClone(value);
+    const plan = planCalendarEventEdit(value.events, {
+      type: "occurrence.edit", eventId: "a", occurrenceStart: "2026-08-03T09:00", scope,
+      start: "2026-08-03T11:00", title: "Changed",
+    }, { allocateId: () => "new", calendarIds: new Set(["work"]) });
+    expect(plan.ok).toBe(true);
+    if (!plan.ok) throw new Error(plan.code);
+    const applied = applyPatch(value, plan.operations);
+    expect(applied.ok).toBe(true);
+    if (!applied.ok) throw new Error("patch failed");
+    expect((applied.value as CalendarDocument).events).toEqual(plan.events);
+    expect(validateCalendarDocument(applied.value).ok).toBe(true);
+    expect(plan.affectedOccurrence.occurrenceStart).toBe("2026-08-03T11:00");
+    expect(plan).not.toHaveProperty("selectionAfter");
+    const focused = projectCalendarOccurrences(plan.events, "2026-08-03", "2026-08-04")
+      .find((occurrence) => occurrence.event.id === plan.affectedOccurrence.eventId);
+    expect(focused).toMatchObject({ start: "2026-08-03T11:00", end: "2026-08-03T12:00", event: { title: "Changed" } });
+    expect(value).toEqual(before);
+  });
+
+  test("rejects invalid edits, unknown operations and reused allocation identities", () => {
+    const value = document();
+    for (const operation of [
+      { type: "event.create", start: "2026-08-03T11:00", end: "2026-08-03T12:00" },
+      { type: "event.update", eventId: "a", end: "2026-08-01T08:00" },
+      { type: "event.typo", eventId: "a" },
+    ]) expect(planCalendarEventEdit(value.events, operation as CalendarEventOperation, { allocateId: () => "a" }).ok).toBe(false);
+    expect(value).toEqual(document());
+  });
+
+  test.each(["this", "this-and-following", "all"] as const)("owns %s occurrence removal without selection or history", (scope) => {
+    const value = document();
+    const plan = planCalendarOccurrenceRemoval(value.events, { eventId: "a", occurrenceStart: "2026-08-03T09:00", scope });
+    expect(plan.ok).toBe(true);
+    if (!plan.ok) throw new Error(plan.code);
+    const applied = applyPatch(value, plan.operations);
+    expect(applied.ok).toBe(true);
+    if (!applied.ok) throw new Error("patch failed");
+    expect((applied.value as CalendarDocument).events).toEqual(plan.events);
+    const days = projectCalendarOccurrences(plan.events, "2026-08-01", "2026-08-09").map((item) => item.start.slice(8, 10));
+    expect(days).toEqual(scope === "all" ? [] : scope === "this-and-following" ? ["01", "02"] : ["01", "02", "04", "05", "06", "07", "08"]);
+  });
+
+  test("owns record removal and calendar visibility", () => {
+    const value = document();
+    expect(planCalendarEventRemoval(value.events, ["missing"]).ok).toBe(false);
+    expect(planCalendarEventRemoval(value.events, ["a"])).toMatchObject({ ok: true, events: [], operations: [{ op: "remove", path: "/events/0" }] });
+    expect(planCalendarVisibility(value, "missing", true).ok).toBe(false);
+    const plan = planCalendarVisibility(value, "work", true);
+    if (!plan.ok) throw new Error(plan.code);
+    const applied = applyPatch(value, plan.operations);
+    if (!applied.ok) throw new Error("patch failed");
+    expect(calendarVisibleEvents(applied.value as CalendarDocument)).toEqual([]);
+    expect(value).toEqual(document());
+  });
+});
diff --git a/packages/json-document-calendar-document/tsconfig.json b/packages/json-document-calendar-document/tsconfig.json
new file mode 100644
index 00000000..fa193bf2
--- /dev/null
+++ b/packages/json-document-calendar-document/tsconfig.json
@@ -0,0 +1,6 @@
+{
+  "extends": "../../tsconfig/library.json",
+  "compilerOptions": { "rootDir": "src", "outDir": "dist", "tsBuildInfoFile": "dist/.tsbuildinfo" },
+  "references": [{ "path": "../json-document" }],
+  "include": ["src/**/*.ts"]
+}
diff --git a/packages/json-document-calendar-document/tsconfig.test.json b/packages/json-document-calendar-document/tsconfig.test.json
new file mode 100644
index 00000000..47af2477
--- /dev/null
+++ b/packages/json-document-calendar-document/tsconfig.test.json
@@ -0,0 +1,5 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": { "composite": false, "noEmit": true, "rootDir": "../..", "types": ["node", "vitest/globals"] },
+  "include": ["src/**/*.ts", "tests/**/*.ts", "vitest.config.ts"]
+}
diff --git a/packages/json-document-calendar-document/vitest.config.ts b/packages/json-document-calendar-document/vitest.config.ts
new file mode 100644
index 00000000..be8c3f2e
--- /dev/null
+++ b/packages/json-document-calendar-document/vitest.config.ts
@@ -0,0 +1,3 @@
+import { defineNodeProject } from "../../test/vitest.shared.js";
+
+export default defineNodeProject("json-document-calendar-document");
diff --git a/packages/json-document-calendar/README.md b/packages/json-document-calendar/README.md
index 9eedc1df..77a28c1f 100644
--- a/packages/json-document-calendar/README.md
+++ b/packages/json-document-calendar/README.md
@@ -2,8 +2,10 @@
 
 React lifecycle for Calendar Hands over the canonical interval editor. The
 package owns editor subscription, occurrence focus, normalized gesture preview,
-canonical Rename and keyboard composition, and series-scope command binding. The Editing package owns
-Calendar document and intent semantics, Affordance owns the input-independent
+canonical Rename and keyboard composition, and series-scope command binding.
+`@interactive-os/json-document-calendar-document` owns the document model, validation,
+operations and projection; Editing owns selection, Intent execution, Clipboard and History.
+Affordance owns the input-independent
 gesture lifecycle, and Web owns Pointer Events capture and coordinate
 translation. Hosts keep fixtures, URL state, product copy, layout, colors, and
 time-grid policy.
@@ -24,8 +26,12 @@ const titleInput = useCalendarRenameInput(calendar);
 useCalendarKeyboard({ active: true, onView, onShift, onToday, onCreate, onRename, onRemove });
 ```
 
-The Hand resolves the currently focused occurrence as the copy source and
-paste target. Bind `cut: calendar.cut` directly to the Web clipboard surface:
+The Hand derives the focused occurrence from `editor.primaryOccurrence`; direct
+dispatch, external selection and selection made before mounting use the same target.
+`editor.paste(payload)` defaults to that occurrence, not the recurring series origin.
+`setOccurrence` supplies an explicit temporal paste cursor (including an empty slot),
+scoped to the current editor revision; it never overrides the Inspector/edit selection.
+Bind `cut: calendar.cut` directly to the Web clipboard surface:
 the Hand accepts the payload already written by Web and removes that captured
 target even if selection changes during the write. The Host selects Web representations; Calendar schema,
 occurrence projection, temporal placement, selection, and history remain in
@@ -44,7 +50,7 @@ Hit tests and all-day column measurements never fall back to global document
 queries. Keyboard listeners can also use the existing `target` option when a
 Host embeds multiple active calendars.
 
-The domain-owned [Calendar protocol profile](../json-document-editing/docs/calendar-profile.md)
+The [Calendar editing protocol profile](../json-document-editing/docs/calendar-profile.md)
 defines temporal values, recurrence scopes, stale-source rejection and clipboard
 compatibility. On the site it is visible under [Editing API](/docs/api/editing#calendar-protocol-profile-rc);
 the Calendar Hand does not introduce a second domain protocol.
diff --git a/packages/json-document-calendar/package.json b/packages/json-document-calendar/package.json
index c2a9ab90..9529c3a7 100644
--- a/packages/json-document-calendar/package.json
+++ b/packages/json-document-calendar/package.json
@@ -23,6 +23,7 @@
     "@js-temporal/polyfill": "^0.5.1"
   },
   "peerDependencies": {
+    "@interactive-os/json-document-calendar-document": ">=0.1.0-rc.0 <1",
     "@interactive-os/json-document-affordance": ">=0.1.0-rc.0 <1",
     "@interactive-os/json-document-editing": ">=0.1.0-rc.0 <1",
     "@interactive-os/json-document-react": ">=0.1.0-rc.0 <1",
@@ -31,6 +32,7 @@
     "react": "^18.0.0 || ^19.0.0"
   },
   "devDependencies": {
+    "@interactive-os/json-document-calendar-document": "*",
     "@interactive-os/json-document-affordance": "*",
     "@interactive-os/json-document-editing": "*",
     "@interactive-os/json-document-react": "*",
diff --git a/packages/json-document-calendar/src/calendar-event-inspector.tsx b/packages/json-document-calendar/src/calendar-event-inspector.tsx
index 9d8fc118..f07cb715 100644
--- a/packages/json-document-calendar/src/calendar-event-inspector.tsx
+++ b/packages/json-document-calendar/src/calendar-event-inspector.tsx
@@ -8,7 +8,7 @@ import {
   calendarRecurrenceWithInterval,
   calendarRecurrenceWithUntil,
   type CalendarCalendar,
-} from "@interactive-os/json-document-editing";
+} from "@interactive-os/json-document-calendar-document";
 import {
   Choice,
   Command,
diff --git a/packages/json-document-calendar/src/calendar-month-grid.tsx b/packages/json-document-calendar/src/calendar-month-grid.tsx
index 64e93c43..c290a79c 100644
--- a/packages/json-document-calendar/src/calendar-month-grid.tsx
+++ b/packages/json-document-calendar/src/calendar-month-grid.tsx
@@ -8,6 +8,9 @@ import {
   type ReactNode,
   type Ref,
 } from "react";
+import {
+  type CalendarOccurrenceTopologySnapshot,
+} from "@interactive-os/json-document-editing";
 import {
   calendarAllDaySpan,
   calendarEventsOnDay,
@@ -16,8 +19,7 @@ import {
   calendarMonthWeekLayout,
   isCalendarAllDay,
   type CalendarEvent,
-  type CalendarOccurrenceTopologySnapshot,
-} from "@interactive-os/json-document-editing";
+} from "@interactive-os/json-document-calendar-document";
 import { selectionModeFromModifiers } from "@interactive-os/json-document-react";
 import {
   contentInteractionAttributes,
diff --git a/packages/json-document-calendar/src/calendar-time-grid.tsx b/packages/json-document-calendar/src/calendar-time-grid.tsx
index 2141dcfe..f0aeead7 100644
--- a/packages/json-document-calendar/src/calendar-time-grid.tsx
+++ b/packages/json-document-calendar/src/calendar-time-grid.tsx
@@ -1,4 +1,8 @@
 import { type MouseEvent, type ReactNode, type Ref } from "react";
+import {
+  calendarVisibleHourBand,
+  type CalendarOccurrenceTopologySnapshot,
+} from "@interactive-os/json-document-editing";
 import {
   calendarAllDayLayout,
   calendarAllDaySpan,
@@ -6,10 +10,8 @@ import {
   calendarNowMarker,
   calendarShiftInstant,
   calendarTimedLayout,
-  calendarVisibleHourBand,
   type CalendarEvent,
-  type CalendarOccurrenceTopologySnapshot,
-} from "@interactive-os/json-document-editing";
+} from "@interactive-os/json-document-calendar-document";
 import { selectionModeFromModifiers } from "@interactive-os/json-document-react";
 import { contentInteractionAttributes, ResizeHandle, SelectableItem, type ControlAffordance } from "@interactive-os/json-document-ui-primitives-react";
 import { calendarTimeLabel, type CalendarCell } from "./date-values.js";
diff --git a/packages/json-document-calendar/src/use-calendar-hand.ts b/packages/json-document-calendar/src/use-calendar-hand.ts
index 4a7fbf76..03492435 100644
--- a/packages/json-document-calendar/src/use-calendar-hand.ts
+++ b/packages/json-document-calendar/src/use-calendar-hand.ts
@@ -2,20 +2,16 @@ import { useRef, useState } from "react";
 import { createRenameSession, type RenameSessionSnapshot } from "@interactive-os/json-document-affordance";
 import {
   calendarClipboardFormat,
-  calendarOccurrenceAfterIntent,
   calendarOccurrenceForInspector,
   calendarOccurrenceFromSelection,
   calendarUpdateIntent,
-  calendarVisibleEvents,
   previewCalendarAllDay,
   previewCalendarMonth,
   previewCalendarTimeGrid,
   planCalendarSelectionMove,
   type CalendarAllDayPointerRelease,
-  type CalendarDocument,
   type CalendarClipboard,
   type CalendarEditor,
-  type CalendarEvent,
   type CalendarEventPatch,
   type CalendarIntent,
   type CalendarSelection,
@@ -28,6 +24,11 @@ import {
   type CalendarOccurrenceTopologySnapshot,
   type CalendarTimeGridPointerRelease,
 } from "@interactive-os/json-document-editing";
+import {
+  calendarVisibleEvents,
+  type CalendarDocument,
+  type CalendarEvent,
+} from "@interactive-os/json-document-calendar-document";
 import { useEditingSnapshot } from "@interactive-os/json-document-react";
 
 type OccurrenceScope = Extract<CalendarIntent, { type: "occurrence.edit" }>["scope"];
@@ -100,15 +101,19 @@ export function useCalendarHand(editor: CalendarEditor, options: CalendarHandOpt
   optionsRef.current = options;
   const selectedEvent = editor.selectedEvents[0] ?? null;
   const selectedOccurrences = editor.selectedOccurrences;
-  const [occurrence, setOccurrence] = useState<CalendarOccurrenceRange>(
-    options.initialOccurrence ?? calendarOccurrenceFromSelection(selectedEvent),
-  );
+  // A cursor in an empty slot is an explicit paste destination, not a copy of selection.
+  type PasteTarget = { readonly editor: CalendarEditor; readonly revision: number; readonly range: CalendarOccurrenceRange };
+  const [pasteTarget, setPasteTarget] = useState<PasteTarget | null>(() => options.initialOccurrence === undefined
+    ? null : { editor, revision: editor.snapshot.revision, range: options.initialOccurrence });
+  const pasteTargetRef = useRef(pasteTarget);
+  pasteTargetRef.current = pasteTarget;
+  const primaryOccurrence = editor.primaryOccurrence;
+  const occurrence = primaryOccurrence !== null ? calendarOccurrenceFromSelection(primaryOccurrence)
+    : pasteTarget?.editor === editor && pasteTarget.revision === snapshot.revision ? pasteTarget.range : { start: null, end: null };
   const [scope, setScope] = useState<OccurrenceScope>("this");
   const [renameSnapshot, setRenameSnapshot] = useState<RenameSessionSnapshot<string> | null>(null);
-  const occurrenceRef = useRef(occurrence);
   const scopeRef = useRef(scope);
   const createdRenameKeyRef = useRef<string | null>(null);
-  occurrenceRef.current = occurrence;
   scopeRef.current = scope;
   const [renameSession] = useState(() => createRenameSession<string>({
     onCommit(key, draft) {
@@ -116,7 +121,7 @@ export function useCalendarHand(editor: CalendarEditor, options: CalendarHandOpt
       if (current === undefined) return;
       const next = draft.trim() || (options.defaultTitle ?? "Event");
       if (next !== current.title) {
-        if (dispatch(calendarUpdateIntent(current, occurrenceRef.current.start, scopeRef.current, { title: next }))) rememberSelection();
+        if (dispatch(calendarUpdateIntent(current, editor.primaryOccurrence?.start ?? null, scopeRef.current, { title: next }))) rememberSelection();
       }
     },
     onCancel(key, draft) {
@@ -167,7 +172,14 @@ export function useCalendarHand(editor: CalendarEditor, options: CalendarHandOpt
   }
 
   function rememberSelection(): void {
-    setOccurrence(calendarOccurrenceFromSelection(editor.primaryOccurrence));
+    pasteTargetRef.current = null;
+    setPasteTarget(null);
+  }
+
+  function setOccurrence(range: CalendarOccurrenceRange): void {
+    const target = { editor, revision: editor.snapshot.revision, range };
+    pasteTargetRef.current = target;
+    setPasteTarget(target);
   }
 
   function commitIntent(intent: CalendarIntent | null, origin: CalendarOccurrenceRange): boolean {
@@ -176,9 +188,8 @@ export function useCalendarHand(editor: CalendarEditor, options: CalendarHandOpt
     return true;
   }
 
-  function rememberIntent(intent: CalendarIntent | null, origin: CalendarOccurrenceRange): void {
-    const committed = calendarOccurrenceFromSelection(editor.primaryOccurrence);
-    setOccurrence(calendarOccurrenceAfterIntent(intent, origin, committed));
+  function rememberIntent(intent: CalendarIntent | null, _origin: CalendarOccurrenceRange): void {
+    rememberSelection();
     if (intent?.type === "event.create") {
       setScope("this");
       const created = editor.selectedEvents[0] ?? null;
@@ -192,8 +203,9 @@ export function useCalendarHand(editor: CalendarEditor, options: CalendarHandOpt
   }
 
   function applySelectedPatch(patch: CalendarEventPatch): boolean {
-    if (selectedEvent === null) return false;
-    if (!dispatch(calendarUpdateIntent(selectedEvent, occurrence.start, scope, patch))) return false;
+    const current = editor.selectedEvents[0];
+    if (current === undefined) return false;
+    if (!dispatch(calendarUpdateIntent(current, editor.primaryOccurrence?.start ?? null, scopeRef.current, patch))) return false;
     rememberSelection();
     return true;
   }
@@ -225,8 +237,7 @@ export function useCalendarHand(editor: CalendarEditor, options: CalendarHandOpt
       return point?.eventId === eventId && point.occurrenceStart === occurrenceStart;
     }
     const primary = editor.primaryOccurrence ?? editor.selectedOccurrences[0] ?? null;
-    return (primary?.eventId === eventId && primary.start === occurrenceStart)
-      || (selectedEvent?.id === eventId && occurrence.start === occurrenceStart);
+    return primary?.eventId === eventId && primary.start === occurrenceStart;
   }
 
   function selectOccurrence(
@@ -242,8 +253,7 @@ export function useCalendarHand(editor: CalendarEditor, options: CalendarHandOpt
       mode,
       ...(topology === undefined ? {} : { topology }),
     })) return false;
-    const primary = editor.primaryOccurrence ?? editor.selectedOccurrences[0] ?? null;
-    setOccurrence(primary === null ? { start: null, end: null } : { start: primary.start, end: primary.end });
+    rememberSelection();
     return true;
   }
 
@@ -265,9 +275,11 @@ export function useCalendarHand(editor: CalendarEditor, options: CalendarHandOpt
   }
 
   function removeSelected(): boolean {
-    if (selectedEvent === null) return false;
-    const intent: CalendarIntent = selectedEvent.recurrence !== null && occurrence.start !== null
-      ? { type: "occurrence.remove", eventId: selectedEvent.id, occurrenceStart: occurrence.start, scope }
+    const current = editor.selectedEvents[0];
+    if (current === undefined) return false;
+    const primary = editor.primaryOccurrence;
+    const intent: CalendarIntent = current.recurrence !== null && primary !== null
+      ? { type: "occurrence.remove", eventId: current.id, occurrenceStart: primary.start, scope: scopeRef.current }
       : { type: "selection.remove" };
     if (!dispatch(intent)) return false;
     rememberSelection();
@@ -316,7 +328,8 @@ export function useCalendarHand(editor: CalendarEditor, options: CalendarHandOpt
   }
 
   function paste(clipboard: CalendarClipboard): EditingResult<CalendarSelection> {
-    const result = observe(editor.paste(clipboard, occurrence.start ?? selectedEvent?.start));
+    const target = pasteTargetRef.current;
+    const result = observe(editor.paste(clipboard, target?.editor === editor && target.revision === editor.snapshot.revision ? target.range.start ?? undefined : undefined));
     if (result.ok) rememberSelection();
     return result;
   }
diff --git a/packages/json-document-calendar/src/use-calendar-pointer-interactions.ts b/packages/json-document-calendar/src/use-calendar-pointer-interactions.ts
index 589066b8..81138ff1 100644
--- a/packages/json-document-calendar/src/use-calendar-pointer-interactions.ts
+++ b/packages/json-document-calendar/src/use-calendar-pointer-interactions.ts
@@ -1,13 +1,24 @@
 import { useRef, useState, type PointerEvent, type RefObject } from "react";
 import { createGestureSession } from "@interactive-os/json-document-affordance";
 import {
-  addCalendarDate, bindCalendarAllDayIntent, bindCalendarMonthIntent, bindCalendarTimeGridIntent,
-  calendarEventsOnDay, calendarInstantAt, calendarShiftInstant, calendarVisibleEvents,
-  interpretCalendarAllDayPointer, interpretCalendarMonthPointer, interpretCalendarTimeGridPointer,
-  type CalendarAllDayPointerRelease, type CalendarTimeGridHandle,
+  bindCalendarAllDayIntent,
+  bindCalendarMonthIntent,
+  bindCalendarTimeGridIntent,
+  interpretCalendarAllDayPointer,
+  interpretCalendarMonthPointer,
+  interpretCalendarTimeGridPointer,
+  type CalendarAllDayPointerRelease,
+  type CalendarTimeGridHandle,
   type CalendarTimeGridPointerRelease,
   type CalendarSelectionDragSource,
 } from "@interactive-os/json-document-editing";
+import {
+  addCalendarDate,
+  calendarEventsOnDay,
+  calendarInstantAt,
+  calendarShiftInstant,
+  calendarVisibleEvents,
+} from "@interactive-os/json-document-calendar-document";
 import {
   calendarDayDeltaFromWebWidth, calendarKeyFromWebRow, calendarMinutesFromWebGrid,
   createWebPointerSession, findWebPointTarget,
diff --git a/packages/json-document-calendar/tests/calendar-protocol.test.tsx b/packages/json-document-calendar/tests/calendar-protocol.test.tsx
index 1c68ca4c..b6f51c7c 100644
--- a/packages/json-document-calendar/tests/calendar-protocol.test.tsx
+++ b/packages/json-document-calendar/tests/calendar-protocol.test.tsx
@@ -24,6 +24,50 @@ function surface(width: number, day: string) {
 }
 
 describe("Calendar Hand protocol composition", () => {
+  test.each(["hand", "editor", "initial"] as const)("uses canonical occurrence after %s selection, including the README patch/paste path", (path) => {
+    let id = 0;
+    const editor = createCalendarEditor({ ...initial, events: [{ ...initial.events[0]!, recurrence: { freq: "daily", interval: 1, until: "2026-08-08" } }] }, { createId: () => `new-${++id}` });
+    const intent = { type: "selection.set", point: { eventId: "a", occurrenceStart: "2026-08-03T09:00" } } as const;
+    if (path === "initial") editor.dispatch(intent);
+    const { result } = renderHook(() => useCalendarHand(editor));
+    if (path !== "initial") act(() => path === "hand" ? result.current.dispatch(intent) : editor.dispatch(intent));
+    expect(result.current.occurrence).toEqual({ start: "2026-08-03T09:00", end: "2026-08-03T10:00" });
+    expect(result.current.inspectedInterval).toEqual(result.current.occurrence);
+    expect(result.current.isPrimaryOccurrence("a", "2026-08-01T09:00")).toBe(false);
+    expect(result.current.isPrimaryOccurrence("a", "2026-08-03T09:00")).toBe(true);
+    act(() => { expect(result.current.applySelectedPatch({ title: "Planning" })).toBe(true); });
+    expect(result.current.selectedEvent).toMatchObject({ title: "Planning", start: "2026-08-03T09:00", recurrence: null });
+    const payload = result.current.copy()!;
+    act(() => { expect(result.current.paste(payload).ok).toBe(true); });
+    expect(result.current.selectedEvent?.start).toBe("2026-08-03T09:00");
+    act(() => result.current.undo());
+    act(() => result.current.undo());
+    expect(result.current.occurrence.start).toBe("2026-08-03T09:00");
+  });
+
+  test("an explicit empty-slot paste target does not become a stale selected occurrence", () => {
+    const editor = createCalendarEditor(initial);
+    const { result } = renderHook(() => useCalendarHand(editor));
+    act(() => result.current.setOccurrence({ start: "2026-08-04T11:00", end: "2026-08-04T12:00" }));
+    act(() => editor.dispatch({ type: "selection.clear" }));
+    act(() => editor.dispatch({ type: "selection.set", point: { eventId: "a", occurrenceStart: "2026-08-01T09:00" } }));
+    expect(result.current.occurrence.start).toBe("2026-08-01T09:00");
+    act(() => result.current.removeSelected());
+    expect(result.current.selectedEvent).toBeNull();
+    expect(result.current.occurrence).toEqual({ start: null, end: null });
+  });
+
+  test("selection and patch in one event use the live canonical occurrence", () => {
+    const editor = createCalendarEditor({ ...initial, events: [{ ...initial.events[0]!, recurrence: { freq: "daily", interval: 1, until: "2026-08-08" } }] });
+    const { result } = renderHook(() => useCalendarHand(editor));
+    act(() => {
+      result.current.dispatch({ type: "selection.set", point: { eventId: "a", occurrenceStart: "2026-08-03T09:00" } });
+      expect(result.current.applySelectedPatch({ title: "Same event" })).toBe(true);
+    });
+    expect(result.current.selectedEvent).toMatchObject({ title: "Same event", start: "2026-08-03T09:00", recurrence: null });
+    expect((editor.snapshot.value as CalendarDocument).events[0]?.title).toBe("A");
+  });
+
   test.each(["time", "allDay", "month"] as const)("returning a %s drag to its origin clears preview and does not commit", (kind) => {
     const sourceEvent = kind === "time" ? initial.events[0]! : { ...initial.events[0]!, start: "2026-08-01", end: "2026-08-02", allDay: true };
     const editor = createCalendarEditor({ ...initial, events: [sourceEvent] });
diff --git a/packages/json-document-calendar/tsconfig.json b/packages/json-document-calendar/tsconfig.json
index fbedf710..0cd96d40 100644
--- a/packages/json-document-calendar/tsconfig.json
+++ b/packages/json-document-calendar/tsconfig.json
@@ -6,6 +6,7 @@
     "tsBuildInfoFile": "dist/.tsbuildinfo"
   },
   "references": [
+    { "path": "../json-document-calendar-document" },
     { "path": "../json-document-affordance" },
     { "path": "../json-document-editing" },
     { "path": "../json-document-react" },
diff --git a/packages/json-document-editing/README.md b/packages/json-document-editing/README.md
index a71d50fe..9ea50d88 100644
--- a/packages/json-document-editing/README.md
+++ b/packages/json-document-editing/README.md
@@ -181,6 +181,13 @@ It publishes rows with hierarchy/ARIA facts and the matching `TreeTopology`.
 identity when a selection or rendering adapter needs to key a `GridPoint`.
 
 `Calendar` follows the owner-local [Calendar protocol profile](docs/calendar-profile.md).
+
+The document model, validation, semantic operations and projections are owned by
+`@interactive-os/json-document-calendar-document`; the existing exports here are
+compatibility paths to that implementation. Editing owns selection, clipboard,
+Intent execution and history, and consumes the Document Type's public plans.
+`paste(clipboard)` defaults to `primaryOccurrence.start`, including later recurring
+occurrences. The shared grammar binding is `tests/conformance/calendar-grammar.test.ts`.
 The profile is also rendered on the site's Editing API page; it documents the
 current RC implementation, not a frozen Official Hands wire standard.
 `Calendar` keeps interval events `{ id, title, start, end, allDay }`. Timed
diff --git a/packages/json-document-editing/docs/calendar-profile.md b/packages/json-document-editing/docs/calendar-profile.md
index 43034769..1bcd6bbc 100644
--- a/packages/json-document-editing/docs/calendar-profile.md
+++ b/packages/json-document-editing/docs/calendar-profile.md
@@ -1,40 +1,25 @@
 ## Calendar protocol profile (RC)
 
-정본 소유자는 `@interactive-os/json-document-editing`이다. 이 문서는 현재
+Editing lifecycle의 소유자는 `@interactive-os/json-document-editing`이다. 문서 모델·검증·연산·projection은
+`@interactive-os/json-document-calendar-document`가 소유한다. 이 문서는 현재
 `0.1.0-rc.0` Calendar 구현의 계약과 한계를 명시한다. Core Stable 프로파일이나
 EditingSession 계약을 변경하지 않으며, Draft인 Official Hands / Editing Grammar를
 동결된 wire 표준으로 승격하지 않는다. Calendar Hands는 이 계약을 입력과 화면에 연결한다.
 
-### 값과 시간
-
-- 일정은 고유한 비어 있지 않은 `id`, 문자열 `title`, `start < end`인 구간을 갖는다.
-- timed 값은 정확히 `YYYY-MM-DDTHH:mm`인 local date-time이다. UTC Instant,
-  offset, timezone, 초 단위는 이 프로파일에 포함하지 않는다.
-- all-day 값은 `YYYY-MM-DD`이다. timed와 all-day 모두 종료는 exclusive이다.
-  8월 1일 하루는 `start: "2026-08-01", end: "2026-08-02"`다.
-- 현재 문서에 calendars가 있으면 비어 있지 않은 `calendarId`는 실제 calendar를
-  참조해야 한다. 기존 간단한 문서의 생략된 calendars / allDay / calendarId /
-  recurrence / excludeDates는 각각 빈 목록 / timed / 미지정 / 반복 없음 / 제외 없음으로
-  읽는 호환 경로를 유지한다. 새 clipboard 출력은 완전한 필드를 갖는다.
-- recurrence의 `freq`는 daily / weekly / monthly / yearly, `interval`은 양의
-  safe integer다. `until: ""`은 무기한, 그 외에는 발생 시작일 기준 inclusive 날짜다.
-  `excludeDates`는 발생 시작일을 제외한다. 월말·윤년의 발생 시작은 Temporal constrain
-  규칙을 따르고, 종료는 원본의 local duration을 보존한다. 시작·종료를 따로 constrain해
-  구간 길이가 0이나 음수가 되지 않는다.
-- projection은 요청한 `[rangeStart, rangeEnd)`와 겹치는 발생분을 계산한다. 과거
-  발생분을 처음부터 순회하거나 400회에서 수명을 잘라내지 않고 요청 구간 근처로 이동한다.
-  매우 넓은 조회의 출력량 자체를 제한하는 pagination 계약은 아직 없다.
+### 문서 규칙의 소유자
+
+시간 값, recurrence, legacy 필드와 calendar 검증은
+[Calendar Document Type API](/docs/api/calendar-document)의 RC 계약을 소비한다.
+생성자도 같은 공개 `assertCalendarDocument`를 사용한다. 잘못된 calendars 타입,
+calendar id/title/hidden/color와 event 규칙을 각 소비자가 별도로 판단하지 않는다.
 
 ### 선택, 범위와 편집
 
 `{ eventId, occurrenceStart }`가 발생분의 정체성이다. Selection 정본의 materialized
 targets를 사용하며, 화면 밖에 있어도 현재 반복 규칙에 존재하는 선택은 유지된다.
 
-| scope | 의미 |
-| --- | --- |
-| this | 해당 발생분만 제외하고 독립 일정으로 분리 |
-| this-and-following | 이전 시리즈를 기준 발생일 전날까지 자르고 이후를 새 시리즈로 분리 |
-| all | 선택한 발생분의 변경량을 원본 시리즈 구간에 적용 |
+`this` / `this-and-following` / `all`의 event/series 의미와 문서 연산은
+Document Type이 소유한다. Editing은 공개 계획의 `affectedOccurrence`를 후속 선택으로 연결한다.
 
 시작만 바꾸면 해당 발생분의 길이를 보존한다. resize는 지정한 경계만 바꾸며
 반복 시리즈의 원본 날짜와 선택 발생 날짜를 혼동하지 않는다. Inspector, 포인터,
@@ -84,6 +69,10 @@ anchor가 생략된 기존 payload는 첫 occurrence를 anchor로 읽는다.
 않은 내용 변경이나 사라진 발생분이 있으면 거절한다. Web은 기록 실패 시 cut을
 호출하지 않는다. Web의 별도 이벤트 기본 동작 정책은 이 프로파일을 확장하지 않는다.
 
+`paste(clipboard)`의 기본 목적지는 `primaryOccurrence.start`다. 빈 선택에서는
+명시적인 target이 필요하다. 원본 반복 시리즈의 시작일로 되돌아가지 않는다.
+Hand의 빈 슬롯 cursor는 명시적 target이며 해당 Editing revision에서만 유효하다.
+
 paste는 길이와 상대 위치를 보존하고 새 ID를 부여한다. 외부 문서의 calendarId를
 자동으로 다른 calendar로 치환하지 않는다. 명시적 재배치가 필요하면 기존 Editing API로
 목적지를 지정한다.
@@ -100,6 +89,8 @@ timezone/DST 변환, 서버 저장·동기화의 revision/충돌/재시도, AI c
 외부 calendar connector, recurrence의 범용 RRULE 호환, 프로파일 버전 협상과
 독립 구현 conformance는 **TBD**다. 현재 앱에서 검증한 로컬 계약과 구분한다.
 
-Usage는 [Calendar](/demo/calendar), public API는 [Editing API](/docs/api/editing)와
-[Calendar Hands API](/docs/api/calendar)에 있다. Usage Source는 Editing의 validation,
-event/series plan, selection move, projection과 Calendar Hands의 입력 연결까지 추적한다.
+Usage 및 Source는 [Calendar](/editors#calendar-editor), public API는 [Editing API](/docs/api/editing)와
+[Calendar Hands API](/docs/api/calendar)에 있다. Usage Source는 Document Type의 validation·event/series plan·projection,
+Editing의 selection move와 Calendar Hands의 입력 연결까지 추적한다. 공통 적합성 검사는
+`tests/conformance/calendar-grammar.test.ts`, 직접 API/Hand 경로 회귀는
+Calendar package의 `tests/calendar-protocol.test.tsx`에 있다.
diff --git a/packages/json-document-editing/package.json b/packages/json-document-editing/package.json
index 7a9a86b7..f90d073a 100644
--- a/packages/json-document-editing/package.json
+++ b/packages/json-document-editing/package.json
@@ -34,13 +34,12 @@
     "verify": "npm run typecheck && npm test && npm run build"
   },
   "peerDependencies": {
+    "@interactive-os/json-document-calendar-document": "^0.1.0-rc.0",
     "@interactive-os/json-document": "^3.0.0",
     "@interactive-os/json-document-selection": "^0.1.0-rc.0"
   },
-  "dependencies": {
-    "@js-temporal/polyfill": "^0.5.1"
-  },
   "devDependencies": {
+    "@interactive-os/json-document-calendar-document": "*",
     "@interactive-os/json-document": "*",
     "@interactive-os/json-document-selection": "*",
     "@types/node": "^25.9.0",
diff --git a/packages/json-document-editing/src/calendar-allday-pointer.ts b/packages/json-document-editing/src/calendar-allday-pointer.ts
index 539ff3b6..6b8b46fb 100644
--- a/packages/json-document-editing/src/calendar-allday-pointer.ts
+++ b/packages/json-document-editing/src/calendar-allday-pointer.ts
@@ -1,7 +1,12 @@
-import type { CalendarEvent, CalendarIntent } from "./calendar.js";
-import { calendarEventRecurrence, resolveCalendarOccurrence } from "./calendar-occurrence.js";
+import type {
+  CalendarIntent,
+} from "./calendar.js";
+import type {
+  CalendarEvent,
+} from "@interactive-os/json-document-calendar-document";
+import { calendarEventRecurrence, resolveCalendarOccurrence } from "@interactive-os/json-document-calendar-document";
 import { bindCalendarMonthIntent } from "./calendar-month-pointer.js";
-import { addCalendarDate, calendarAllDaySpan, calendarDaysBetween, parseCalendarDate } from "./calendar-validation.js";
+import { addCalendarDate, calendarAllDaySpan, calendarDaysBetween, parseCalendarDate } from "@interactive-os/json-document-calendar-document";
 
 export type CalendarAllDayHandle = "body" | "start" | "end";
 
diff --git a/packages/json-document-editing/src/calendar-month-pointer.ts b/packages/json-document-editing/src/calendar-month-pointer.ts
index 2e35633d..57af5153 100644
--- a/packages/json-document-editing/src/calendar-month-pointer.ts
+++ b/packages/json-document-editing/src/calendar-month-pointer.ts
@@ -1,6 +1,11 @@
-import type { CalendarEvent, CalendarIntent } from "./calendar.js";
-import { calendarEventRecurrence } from "./calendar-occurrence.js";
-import { addCalendarDate, calendarAllDaySpan, calendarDatePart, calendarDaysBetween, isCalendarAllDay, parseCalendarDate } from "./calendar-validation.js";
+import type {
+  CalendarIntent,
+} from "./calendar.js";
+import type {
+  CalendarEvent,
+} from "@interactive-os/json-document-calendar-document";
+import { calendarEventRecurrence } from "@interactive-os/json-document-calendar-document";
+import { addCalendarDate, calendarAllDaySpan, calendarDatePart, calendarDaysBetween, isCalendarAllDay, parseCalendarDate } from "@interactive-os/json-document-calendar-document";
 
 export type CalendarMonthPointerRelease = {
   readonly originDay: string;
diff --git a/packages/json-document-editing/src/calendar-preview.ts b/packages/json-document-editing/src/calendar-preview.ts
index f7dacf72..c044e632 100644
--- a/packages/json-document-editing/src/calendar-preview.ts
+++ b/packages/json-document-editing/src/calendar-preview.ts
@@ -1,5 +1,10 @@
-import type { CalendarEvent, CalendarIntent } from "./calendar.js";
-import { planCalendarEventEdit } from "./calendar-event-plan.js";
+import type {
+  CalendarIntent,
+} from "./calendar.js";
+import type {
+  CalendarEvent,
+} from "@interactive-os/json-document-calendar-document";
+import { planCalendarEventEdit } from "@interactive-os/json-document-calendar-document";
 import { createEditingIdAllocator } from "./identity.js";
 import { bindCalendarAllDayIntent, interpretCalendarAllDayPointer, type CalendarAllDayPointerRelease } from "./calendar-allday-pointer.js";
 import { bindCalendarMonthIntent, interpretCalendarMonthPointer, type CalendarMonthPointerRelease } from "./calendar-month-pointer.js";
diff --git a/packages/json-document-editing/src/calendar-selection-move.ts b/packages/json-document-editing/src/calendar-selection-move.ts
index 35d40b00..46a88c7c 100644
--- a/packages/json-document-editing/src/calendar-selection-move.ts
+++ b/packages/json-document-editing/src/calendar-selection-move.ts
@@ -1,12 +1,14 @@
-import { calendarEventRecurrence, resolveCalendarOccurrence } from "./calendar-occurrence.js";
-import { planCalendarEventEdit } from "./calendar-event-plan.js";
+import { calendarEventRecurrence, resolveCalendarOccurrence } from "@interactive-os/json-document-calendar-document";
+import { planCalendarEventEdit } from "@interactive-os/json-document-calendar-document";
 import { createEditingIdAllocator } from "./identity.js";
 import type {
-  CalendarEvent,
-  CalendarOccurrencePoint,
   CalendarOccurrenceSelection,
   CalendarSelection,
 } from "./calendar.js";
+import type {
+  CalendarEvent,
+  CalendarOccurrencePoint,
+} from "@interactive-os/json-document-calendar-document";
 import {
   calendarDatePart,
   calendarDaysBetween,
@@ -16,7 +18,7 @@ import {
   isCalendarAllDay,
   parseCalendarDate,
   parseCalendarInstant,
-} from "./calendar-validation.js";
+} from "@interactive-os/json-document-calendar-document";
 
 export type CalendarSelectionMoveTarget =
   | { readonly type: "instant"; readonly instant: string }
@@ -84,7 +86,7 @@ export function planCalendarSelectionMove(
       } : { type: "event.update", eventId: event.id, ...shifted }, { allocateId });
       if (!plan.ok) return plan;
       next = plan.events;
-      eventId = plan.selected.eventId;
+      eventId = plan.affectedOccurrence.eventId;
       if (recurring && scope !== "this") seriesIds.set(event.id, eventId);
     }
     moved[index] = { eventId, ...shifted };
diff --git a/packages/json-document-editing/src/calendar-selection.ts b/packages/json-document-editing/src/calendar-selection.ts
index 63be83ae..c66a78c4 100644
--- a/packages/json-document-editing/src/calendar-selection.ts
+++ b/packages/json-document-editing/src/calendar-selection.ts
@@ -1,4 +1,9 @@
-import type { CalendarEvent, CalendarIntent } from "./calendar.js";
+import type {
+  CalendarIntent,
+} from "./calendar.js";
+import type {
+  CalendarEvent,
+} from "@interactive-os/json-document-calendar-document";
 
 export type CalendarEventPatch = {
   readonly title?: string;
diff --git a/packages/json-document-editing/src/calendar-time-grid-pointer.ts b/packages/json-document-editing/src/calendar-time-grid-pointer.ts
index a91942a0..3297879d 100644
--- a/packages/json-document-editing/src/calendar-time-grid-pointer.ts
+++ b/packages/json-document-editing/src/calendar-time-grid-pointer.ts
@@ -1,6 +1,11 @@
-import type { CalendarEvent, CalendarIntent } from "./calendar.js";
-import { calendarEventRecurrence, resolveCalendarOccurrence } from "./calendar-occurrence.js";
-import { calendarDatePart, calendarMinutesBetween, calendarShiftInstant, parseCalendarInstant } from "./calendar-validation.js";
+import type {
+  CalendarIntent,
+} from "./calendar.js";
+import type {
+  CalendarEvent,
+} from "@interactive-os/json-document-calendar-document";
+import { calendarEventRecurrence, resolveCalendarOccurrence } from "@interactive-os/json-document-calendar-document";
+import { calendarDatePart, calendarMinutesBetween, calendarShiftInstant, parseCalendarInstant } from "@interactive-os/json-document-calendar-document";
 
 export type CalendarTimeGridHandle = "body" | "start" | "end";
 
diff --git a/packages/json-document-editing/src/calendar.ts b/packages/json-document-editing/src/calendar.ts
index 722ece77..e43e1246 100644
--- a/packages/json-document-editing/src/calendar.ts
+++ b/packages/json-document-editing/src/calendar.ts
@@ -10,7 +10,6 @@ import {
   type MaterializedRangeSelectionCommand,
   type OrderedTopology,
 } from "@interactive-os/json-document-selection";
-import { Temporal } from "@js-temporal/polyfill";
 import {
   createEditingSession,
   type EditingResult,
@@ -21,62 +20,36 @@ import { resolveDocumentSource, type EditingDocumentSource } from "./document-so
 import { createEditingId, createEditingIdAllocator } from "./identity.js";
 import type { EditingHistoryOptions } from "./history.js";
 import {
-  addCalendarDate,
   assertCalendarDocument,
   calendarDatePart,
   calendarDaysBetween,
   calendarDocumentCalendars,
-  calendarDocumentEvents,
-  calendarEventBounds,
-  calendarIntervalLastDate,
+  calendarVisibleEvents,
   calendarMinutesBetween,
   formatCalendarDate,
   formatCalendarInstant,
   isCalendarAllDay,
   parseCalendarDate,
   parseCalendarInstant,
+  planCalendarEventEdit,
+  planCalendarEventRemoval,
+  planCalendarOccurrenceRemoval,
+  planCalendarVisibility,
+  projectCalendarOccurrences,
+  resolveCalendarOccurrence,
   validateCalendarEvent,
-} from "./calendar-validation.js";
-import { calendarEventExcludeDates, calendarEventRecurrence, projectCalendarOccurrences, resolveCalendarOccurrence } from "./calendar-occurrence.js";
-import { planCalendarEventEdit } from "./calendar-event-plan.js";
+  type CalendarDocument,
+  type CalendarEvent,
+  type CalendarEventOperation,
+  type CalendarOccurrenceInterval,
+  type CalendarOccurrencePoint,
+} from "@interactive-os/json-document-calendar-document";
 import {
   planCalendarSelectionMove,
   type CalendarSelectionMoveTarget,
 } from "./calendar-selection-move.js";
 
-export interface CalendarCalendar extends Record<string, JSONValue> {
-  readonly id: string;
-  readonly title: string;
-  readonly hidden: boolean;
-  readonly color: string;
-}
-
-export interface CalendarRecurrence extends Record<string, JSONValue> {
-  readonly freq: "daily" | "weekly" | "monthly" | "yearly";
-  readonly interval: number;
-  readonly until: string;
-}
-
-export interface CalendarEvent extends Record<string, JSONValue> {
-  readonly id: string;
-  readonly title: string;
-  readonly start: string;
-  readonly end: string;
-  readonly allDay: boolean;
-  readonly calendarId: string;
-  readonly recurrence: CalendarRecurrence | null;
-  readonly excludeDates: ReadonlyArray<string>;
-}
-
-export interface CalendarDocument extends Record<string, JSONValue> {
-  readonly calendars: ReadonlyArray<CalendarCalendar>;
-  readonly events: ReadonlyArray<CalendarEvent>;
-}
-
-export interface CalendarOccurrencePoint extends Record<string, JSONValue> {
-  readonly eventId: string;
-  readonly occurrenceStart: string;
-}
+export type { CalendarCalendar, CalendarDocument, CalendarEvent, CalendarRecurrence, CalendarOccurrencePoint } from "@interactive-os/json-document-calendar-document";
 
 export interface CalendarSelectionRange extends Record<string, JSONValue> {
   readonly anchor: CalendarOccurrencePoint;
@@ -107,11 +80,7 @@ export interface CalendarClipboard extends Record<string, JSONValue> {
   readonly text: string;
 }
 
-export interface CalendarOccurrenceSelection {
-  readonly eventId: string;
-  readonly start: string;
-  readonly end: string;
-}
+export type CalendarOccurrenceSelection = CalendarOccurrenceInterval;
 
 export interface CalendarSelectionDragSource {
   readonly anchor: CalendarOccurrencePoint;
@@ -139,6 +108,12 @@ export const calendarClipboardFormat = {
 
 export type CalendarView = "day" | "week" | "month" | "year";
 
+const CALENDAR_VIEWS: ReadonlySet<string> = new Set(["day", "week", "month", "year"]);
+
+export function parseCalendarView(value: unknown): CalendarView | null {
+  return typeof value === "string" && CALENDAR_VIEWS.has(value) ? value as CalendarView : null;
+}
+
 export type CalendarIntent =
   | {
       readonly type: "selection.set";
@@ -154,37 +129,7 @@ export type CalendarIntent =
       readonly target: CalendarSelectionMoveTarget;
       readonly scope?: "this" | "this-and-following" | "all";
     }
-  | {
-      readonly type: "event.create";
-      readonly start: string;
-      readonly end: string;
-      readonly title?: string;
-      readonly allDay?: boolean;
-      readonly calendarId?: string;
-      readonly recurrence?: CalendarRecurrence | null;
-    }
-  | { readonly type: "event.move"; readonly eventId: string; readonly start: string }
-  | { readonly type: "event.resize"; readonly eventId: string; readonly edge: "start" | "end"; readonly instant: string }
-  | { readonly type: "event.move-day"; readonly eventId: string; readonly day: string }
-  | {
-      readonly type: "event.update";
-      readonly eventId: string;
-      readonly title?: string;
-      readonly start?: string;
-      readonly end?: string;
-      readonly allDay?: boolean;
-      readonly calendarId?: string;
-      readonly recurrence?: CalendarRecurrence | null;
-    }
-  | {
-      readonly type: "occurrence.edit";
-      readonly eventId: string;
-      readonly occurrenceStart: string;
-      readonly scope: "this" | "this-and-following" | "all";
-      readonly title?: string;
-      readonly start?: string;
-      readonly end?: string;
-    }
+  | CalendarEventOperation
   | {
       readonly type: "occurrence.remove";
       readonly eventId: string;
@@ -340,7 +285,7 @@ export function createCalendarEditor(
       if (!plan.ok) return plan;
       return session.apply({
         operations: plan.operations,
-        selectionAfter: selectionForOccurrence(plan.selected.eventId, plan.selected.occurrenceStart),
+        selectionAfter: selectionForOccurrence(plan.affectedOccurrence.eventId, plan.affectedOccurrence.occurrenceStart),
         origin: intent.type,
       });
     }
@@ -363,69 +308,41 @@ export function createCalendarEditor(
     intent: Extract<CalendarIntent, { type: "occurrence.remove" }>,
   ): EditingResult<CalendarSelection> {
     const events = value().events;
-    const index = events.findIndex((event) => event.id === intent.eventId);
-    const event = events[index];
-    if (!event) return failure("selection.event-not-found");
-    if (intent.scope !== "this" && intent.scope !== "this-and-following" && intent.scope !== "all") return failure("occurrence.invalid-scope");
-    if (resolveCalendarOccurrence(events, { eventId: event.id, occurrenceStart: intent.occurrenceStart }) === null) return failure("selection.stale-occurrence");
-    const recurrence = calendarEventRecurrence(event);
-    if (recurrence === null || intent.scope === "all") {
-      return removeSelected([event.id]);
-    }
-    const occurrenceDate = calendarDatePart(intent.occurrenceStart);
-    if (intent.scope === "this") {
-      return session.apply({
-        operations: [{
-          op: "add",
-          path: buildPointer(["events", index, "excludeDates"]),
-          value: [...calendarEventExcludeDates(event), occurrenceDate],
-        }],
-        selectionAfter: selectionForEvents(events, [event.id]),
-        origin: intent.type,
-      });
-    }
-    const until = addCalendarDate(occurrenceDate, -1);
-    if (until === null || until < calendarDatePart(event.start)) {
-      return removeSelected([event.id]);
-    }
+    const plan = planCalendarOccurrenceRemoval(events, intent);
+    if (!plan.ok) return plan;
     return session.apply({
-      operations: [{
-        op: "replace",
-        path: buildPointer(["events", index, "recurrence"]),
-        value: { ...recurrence, until },
-      }],
-      selectionAfter: selectionForEvents(events, [event.id]),
+      operations: plan.operations,
+      selectionAfter: plan.events.some((event) => event.id === intent.eventId)
+        ? selectionForEvents(plan.events, [intent.eventId])
+        : selectionAfterRemoval(events, plan.events, [intent.eventId]),
       origin: intent.type,
     });
   }
 
   function setCalendarHidden(calendarId: string, hidden: boolean): EditingResult<CalendarSelection> {
-    if (typeof hidden !== "boolean") return failure("calendar.invalid-hidden");
-    const calendars = calendarDocumentCalendars(value());
-    const index = calendars.findIndex((item) => item.id === calendarId);
-    if (index < 0) return failure("calendar.not-found");
-    return session.apply({
-      operations: [{ op: "replace", path: buildPointer(["calendars", index, "hidden"]), value: hidden }],
+    const plan = planCalendarVisibility(value(), calendarId, hidden);
+    return plan.ok ? session.apply({
+      operations: plan.operations,
       selectionAfter: session.snapshot.selection,
       origin: "calendar.set-hidden",
-    });
+    }) : plan;
   }
 
   function removeSelected(ids: ReadonlyArray<string>): EditingResult<CalendarSelection> {
     const events = value().events;
+    const plan = planCalendarEventRemoval(events, ids);
+    return plan.ok ? session.apply({
+      operations: plan.operations,
+      selectionAfter: selectionAfterRemoval(events, plan.events, ids),
+      origin: "selection.remove",
+    }) : plan;
+  }
+
+  function selectionAfterRemoval(events: ReadonlyArray<CalendarEvent>, remaining: ReadonlyArray<CalendarEvent>, ids: ReadonlyArray<string>): CalendarSelection {
     const removing = new Set(ids);
-    const indices = events
-      .map((event, index) => removing.has(event.id) ? index : -1)
-      .filter((index) => index >= 0)
-      .sort((left, right) => right - left);
-    const remaining = events.filter((event) => !removing.has(event.id));
-    const firstRemoved = Math.min(...indices);
+    const firstRemoved = events.findIndex((event) => removing.has(event.id));
     const next = remaining[Math.min(firstRemoved, remaining.length - 1)];
-    return session.apply({
-      operations: indices.map((index) => ({ op: "remove", path: buildPointer(["events", index]) })),
-      selectionAfter: selectionForEvents(remaining, next ? [next.id] : []),
-      origin: "selection.remove",
-    });
+    return selectionForEvents(remaining, next ? [next.id] : []);
   }
 
   function copy(occurrences?: ReadonlyArray<CalendarOccurrenceSelection>): CalendarClipboard | null {
@@ -482,8 +399,8 @@ export function createCalendarEditor(
   function removeClipboard(clipboard: CalendarClipboard): EditingResult<CalendarSelection> {
     if (clipboard.items.length === 0) return failure("clipboard.empty");
     const events = value().events;
-    const removals = new Set<string>();
-    const exclusions = new Map<string, Set<string>>();
+    let remaining = events;
+    const preconditions: JSONPatchOperation[] = [];
     const operations: JSONPatchOperation[] = [];
     for (const item of clipboard.items) {
       const event = events.find((candidate) => candidate.id === item.sourceEventId);
@@ -496,22 +413,15 @@ export function createCalendarEditor(
         if (event[field] === undefined) delete expected[field];
         else if (field === "recurrence" || field === "excludeDates") expected[field] = event[field];
       }
-      operations.push({ op: "test", path: buildPointer(["events", events.indexOf(event)]), value: expected });
-      if (calendarEventRecurrence(event) === null) removals.add(event.id);
-      else {
-        const dates = exclusions.get(event.id) ?? new Set(calendarEventExcludeDates(event));
-        dates.add(calendarDatePart(item.occurrenceStart));
-        exclusions.set(event.id, dates);
-      }
-    }
-    for (const [eventId, dates] of exclusions) {
-      const index = events.findIndex((event) => event.id === eventId);
-      operations.push({ op: "add", path: buildPointer(["events", index, "excludeDates"]), value: [...dates] });
-    }
-    for (const index of events.map((event, index) => removals.has(event.id) ? index : -1).filter((index) => index >= 0).sort((a, b) => b - a)) {
-      operations.push({ op: "remove", path: buildPointer(["events", index]) });
+      preconditions.push({ op: "test", path: buildPointer(["events", events.indexOf(event)]), value: expected });
+      const plan = planCalendarOccurrenceRemoval(remaining, {
+        eventId: event.id, occurrenceStart: item.occurrenceStart, scope: "this",
+      });
+      if (!plan.ok) return plan;
+      remaining = plan.events;
+      operations.push(...plan.operations);
     }
-    return session.apply({ operations, selectionAfter: emptyCalendarSelection(), origin: "clipboard.cut" });
+    return session.apply({ operations: [...preconditions, ...operations], selectionAfter: emptyCalendarSelection(), origin: "clipboard.cut" });
   }
 
   function paste(clipboard: CalendarClipboard, target?: string, options: { readonly calendarId?: string } = {}): EditingResult<CalendarSelection> {
@@ -520,7 +430,7 @@ export function createCalendarEditor(
     clipboard = parsed;
     const calendarIds = new Set(calendarDocumentCalendars(value()).map((calendar) => calendar.id));
     if (options.calendarId !== undefined && !calendarIds.has(options.calendarId)) return failure("calendar.not-found");
-    const resolvedTarget = target ?? selectedEvents()[0]?.start;
+    const resolvedTarget = target ?? primaryOccurrence()?.start;
     if (resolvedTarget === undefined) return failure("clipboard.invalid-target");
     const targetInstant = parseCalendarInstant(resolvedTarget);
     const targetDate = parseCalendarDate(calendarDatePart(resolvedTarget));
@@ -597,13 +507,6 @@ function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 
-export function calendarVisibleEvents(document: CalendarDocument): ReadonlyArray<CalendarEvent> {
-  const events = calendarDocumentEvents(document);
-  const hidden = new Set(calendarDocumentCalendars(document).filter((item) => item.hidden).map((item) => item.id));
-  if (hidden.size === 0) return events;
-  return events.filter((event) => !hidden.has(event.calendarId));
-}
-
 export function calendarOccurrenceTopology(
   document: CalendarDocument,
   rangeStart: string,
@@ -656,275 +559,6 @@ function compareCalendarOccurrencePoints(
     || left.eventId.localeCompare(right.eventId);
 }
 
-export function calendarNowMarker(nowInstant: string, day: string): { readonly minutes: number } | null {
-  if (calendarDatePart(nowInstant) !== day) return null;
-  const start = parseCalendarInstant(`${day}T00:00`);
-  const now = parseCalendarInstant(nowInstant);
-  if (start === null || now === null) return null;
-  return { minutes: calendarMinutesBetween(start, now) };
-}
-
-export function calendarEventsOnDay(
-  events: ReadonlyArray<CalendarEvent>,
-  day: string,
-): ReadonlyArray<CalendarEvent> {
-  const next = addCalendarDate(day, 1);
-  if (next === null) return [];
-  return projectCalendarOccurrences(events, day, next).map((item) => ({
-    ...item.event,
-    start: item.start,
-    end: item.end,
-  }));
-}
-
-export function calendarMonthDayLayout(
-  events: ReadonlyArray<CalendarEvent>,
-  day: string,
-  rowLimit: number,
-): {
-  readonly events: ReadonlyArray<CalendarEvent>;
-  readonly hiddenCount: number;
-} {
-  const onDay = [...calendarEventsOnDay(events, day)].sort((left, right) => {
-    const leftAllDay = isCalendarAllDay(left);
-    const rightAllDay = isCalendarAllDay(right);
-    if (leftAllDay !== rightAllDay) return leftAllDay ? -1 : 1;
-    return left.start.localeCompare(right.start);
-  });
-  if (rowLimit < 1) return { events: [], hiddenCount: onDay.length };
-  if (onDay.length <= rowLimit) return { events: onDay, hiddenCount: 0 };
-  const shown = Math.max(0, rowLimit - 1);
-  return { events: onDay.slice(0, shown), hiddenCount: onDay.length - shown };
-}
-
-export function calendarBusyDates(
-  events: ReadonlyArray<CalendarEvent>,
-  rangeStart: string,
-  rangeEnd: string,
-): ReadonlySet<string> {
-  const dates = new Set<string>();
-  for (const item of projectCalendarOccurrences(events, rangeStart, rangeEnd)) {
-    for (const day of calendarOccurrenceDays(item.start, item.end, isCalendarAllDay(item.event))) {
-      if (day >= rangeStart && day < rangeEnd) dates.add(day);
-    }
-  }
-  return dates;
-}
-
-function calendarOccurrenceDays(start: string, end: string, allDay: boolean): ReadonlyArray<string> {
-  const first = calendarDatePart(start);
-  const last = calendarIntervalLastDate(start, end, allDay);
-  const days: string[] = [];
-  for (let day = first; day <= last; ) {
-    days.push(day);
-    const next = addCalendarDate(day, 1);
-    if (next === null) break;
-    day = next;
-  }
-  return days;
-}
-
-export function calendarTimedLayout(
-  events: ReadonlyArray<CalendarEvent>,
-  day: string,
-): ReadonlyArray<{
-  readonly event: CalendarEvent;
-  readonly startMinutes: number;
-  readonly endMinutes: number;
-  readonly lane: number;
-  readonly laneCount: number;
-}> {
-  const dayStart = parseCalendarInstant(`${day}T00:00`);
-  if (dayStart === null) return [];
-  const dayEnd = dayStart.add({ days: 1 });
-  const next = addCalendarDate(day, 1);
-  if (next === null) return [];
-  const layout: Array<{ event: CalendarEvent; startMinutes: number; endMinutes: number }> = [];
-  for (const item of projectCalendarOccurrences(events, day, next)) {
-    if (isCalendarAllDay(item.event)) continue;
-    const bounds = calendarEventBounds({ ...item.event, start: item.start, end: item.end });
-    if (bounds === null || Temporal.PlainDateTime.compare(bounds.to, dayStart) <= 0 || Temporal.PlainDateTime.compare(bounds.from, dayEnd) >= 0) continue;
-    const clippedStart = Temporal.PlainDateTime.compare(bounds.from, dayStart) < 0 ? dayStart : bounds.from;
-    const clippedEnd = Temporal.PlainDateTime.compare(bounds.to, dayEnd) > 0 ? dayEnd : bounds.to;
-    layout.push({
-      event: { ...item.event, start: item.start, end: item.end },
-      startMinutes: calendarMinutesBetween(dayStart, clippedStart),
-      endMinutes: calendarMinutesBetween(dayStart, clippedEnd),
-    });
-  }
-  const sorted = layout.sort((left, right) => left.startMinutes - right.startMinutes || left.endMinutes - right.endMinutes);
-  const positioned: Array<typeof sorted[number] & { lane: number; laneCount: number }> = [];
-  let groupStart = 0;
-  while (groupStart < sorted.length) {
-    let groupEnd = groupStart + 1;
-    let occupiedUntil = sorted[groupStart]!.endMinutes;
-    while (groupEnd < sorted.length && sorted[groupEnd]!.startMinutes < occupiedUntil) {
-      occupiedUntil = Math.max(occupiedUntil, sorted[groupEnd]!.endMinutes);
-      groupEnd += 1;
-    }
-    const laneEnds: number[] = [];
-    const group = sorted.slice(groupStart, groupEnd).map((item) => {
-      const available = laneEnds.findIndex((end) => end <= item.startMinutes);
-      const lane = available === -1 ? laneEnds.length : available;
-      laneEnds[lane] = item.endMinutes;
-      return { ...item, lane };
-    });
-    positioned.push(...group.map((item) => ({ ...item, laneCount: laneEnds.length })));
-    groupStart = groupEnd;
-  }
-  return positioned;
-}
-
-export function calendarAllDayLayout(
-  events: ReadonlyArray<CalendarEvent>,
-  days: ReadonlyArray<string>,
-): ReadonlyArray<{
-  readonly event: CalendarEvent;
-  readonly startIndex: number;
-  readonly span: number;
-  readonly lane: number;
-  readonly laneCount: number;
-}> {
-  const rangeStart = days[0];
-  const rangeLast = days.at(-1);
-  if (rangeStart === undefined || rangeLast === undefined) return [];
-  const rangeEnd = addCalendarDate(rangeLast, 1);
-  if (rangeEnd === null) return [];
-  const layout: Array<{ event: CalendarEvent; startIndex: number; span: number }> = [];
-  for (const item of projectCalendarOccurrences(events, rangeStart, rangeEnd)) {
-    if (!isCalendarAllDay(item.event)) continue;
-    const clipped = clipAllDayToDays(item.start, item.end, days);
-    if (clipped === null) continue;
-    layout.push({
-      event: { ...item.event, start: item.start, end: item.end },
-      startIndex: clipped.startIndex,
-      span: clipped.span,
-    });
-  }
-  const sorted = layout.sort((left, right) => left.startIndex - right.startIndex || right.span - left.span);
-  const positioned = assignCalendarSpanLanes(sorted);
-  const laneCount = Math.max(1, positioned[0]?.laneCount ?? 0);
-  return positioned.map((item) => ({ ...item, laneCount }));
-}
-
-export function calendarMonthWeekLayout(
-  events: ReadonlyArray<CalendarEvent>,
-  days: ReadonlyArray<string>,
-  rowLimit: number,
-): {
-  readonly items: ReadonlyArray<{
-    readonly event: CalendarEvent;
-    readonly startIndex: number;
-    readonly span: number;
-    readonly lane: number;
-  }>;
-  readonly hiddenCounts: ReadonlyArray<number>;
-  readonly laneCount: number;
-} {
-  const empty = { items: [], hiddenCounts: days.map(() => 0), laneCount: 0 };
-  const rangeStart = days[0];
-  const rangeLast = days.at(-1);
-  if (rangeStart === undefined || rangeLast === undefined) return empty;
-  const rangeEnd = addCalendarDate(rangeLast, 1);
-  if (rangeEnd === null) return empty;
-  const layout: Array<{ event: CalendarEvent; startIndex: number; span: number }> = [];
-  for (const item of projectCalendarOccurrences(events, rangeStart, rangeEnd)) {
-    const occurrence = { ...item.event, start: item.start, end: item.end };
-    const clipped = isCalendarAllDay(occurrence)
-      ? clipAllDayToDays(item.start, item.end, days)
-      : clipTimedToDays(item.start, item.end, days);
-    if (clipped === null) continue;
-    layout.push({ event: occurrence, startIndex: clipped.startIndex, span: clipped.span });
-  }
-  layout.sort((left, right) => {
-    if (left.startIndex !== right.startIndex) return left.startIndex - right.startIndex;
-    const leftAllDay = isCalendarAllDay(left.event) ? 0 : 1;
-    const rightAllDay = isCalendarAllDay(right.event) ? 0 : 1;
-    if (leftAllDay !== rightAllDay) return leftAllDay - rightAllDay;
-    return right.span - left.span || left.event.start.localeCompare(right.event.start);
-  });
-  const positioned = assignCalendarSpanLanes(layout);
-  const covering = (index: number) => positioned.filter((item) => (
-    index >= item.startIndex && index < item.startIndex + item.span
-  ));
-  const overflow = days.some((_, index) => covering(index).length > rowLimit);
-  const visibleLaneCount = overflow
-    ? Math.max(0, rowLimit - 1)
-    : positioned.reduce((max, item) => Math.max(max, item.lane + 1), 0);
-  return {
-    items: positioned.filter((item) => item.lane < visibleLaneCount),
-    hiddenCounts: days.map((_, index) => covering(index).filter((item) => item.lane >= visibleLaneCount).length),
-    laneCount: visibleLaneCount,
-  };
-}
-
-function assignCalendarSpanLanes<T extends { readonly startIndex: number; readonly span: number }>(
-  layout: ReadonlyArray<T>,
-): ReadonlyArray<T & { readonly lane: number; readonly laneCount: number }> {
-  const laneEnds: number[] = [];
-  const positioned = layout.map((item) => {
-    const available = laneEnds.findIndex((end) => end <= item.startIndex);
-    const lane = available === -1 ? laneEnds.length : available;
-    laneEnds[lane] = item.startIndex + item.span;
-    return { ...item, lane };
-  });
-  const laneCount = laneEnds.length;
-  return positioned.map((item) => ({ ...item, laneCount }));
-}
-
-function clipTimedToDays(
-  start: string,
-  end: string,
-  days: ReadonlyArray<string>,
-): { readonly startIndex: number; readonly span: number } | null {
-  let startIndex = -1;
-  let lastIndex = -1;
-  for (const day of calendarOccurrenceDays(start, end, false)) {
-    const index = days.indexOf(day);
-    if (index < 0) continue;
-    if (startIndex < 0) startIndex = index;
-    lastIndex = index;
-  }
-  if (startIndex < 0 || lastIndex < startIndex) return null;
-  return { startIndex, span: lastIndex - startIndex + 1 };
-}
-
-function clipAllDayToDays(
-  start: string,
-  end: string,
-  days: ReadonlyArray<string>,
-): { readonly startIndex: number; readonly span: number } | null {
-  const first = days[0];
-  const last = days.at(-1);
-  if (first === undefined || last === undefined) return null;
-  const visibleEnd = addCalendarDate(last, 1);
-  if (visibleEnd === null) return null;
-  const startDate = calendarDatePart(start);
-  const exclusiveEnd = calendarDatePart(end);
-  if (exclusiveEnd <= first || startDate >= visibleEnd) return null;
-  const foundStart = days.indexOf(startDate);
-  const foundEnd = days.indexOf(exclusiveEnd);
-  const startIndex = foundStart >= 0 ? foundStart : startDate < first ? 0 : -1;
-  const endIndex = foundEnd >= 0 ? foundEnd : exclusiveEnd >= visibleEnd ? days.length : -1;
-  if (startIndex < 0 || endIndex < 0 || endIndex <= startIndex) return null;
-  return { startIndex, span: endIndex - startIndex };
-}
-
-export function calendarEventsInMonth(
-  events: ReadonlyArray<CalendarEvent>,
-  month: string,
-): ReadonlyArray<CalendarEvent> {
-  const start = `${month}-01`;
-  const startUtc = parseCalendarDate(start);
-  if (startUtc === null) return [];
-  const end = Temporal.PlainYearMonth.from(month).add({ months: 1 }).toPlainDate({ day: 1 }).toString();
-  return projectCalendarOccurrences(events, start, end).map((item) => ({
-    ...item.event,
-    start: item.start,
-    end: item.end,
-  }));
-}
-
 function emptyCalendarSelection(): CalendarSelection {
   return { kind: "range", ranges: [], primaryIndex: null };
 }
diff --git a/packages/json-document-editing/src/index.ts b/packages/json-document-editing/src/index.ts
index ca8f0454..830826bf 100644
--- a/packages/json-document-editing/src/index.ts
+++ b/packages/json-document-editing/src/index.ts
@@ -1,3 +1,15 @@
+// Published compatibility exports; implementations belong to Calendar Document Type.
+export {
+  calendarAllDayLayout,
+  calendarBusyDates,
+  calendarEventsInMonth,
+  calendarEventsOnDay,
+  calendarMonthDayLayout,
+  calendarMonthWeekLayout,
+  calendarNowMarker,
+  calendarTimedLayout,
+  calendarVisibleEvents,
+} from "@interactive-os/json-document-calendar-document";
 export { createDocumentEditor, documentClipboardFormat, documentSelectionFocus } from "./document.js";
 export { cutEditingClipboard } from "./clipboard.js";
 export type { EditingClipboardCut } from "./clipboard.js";
@@ -25,17 +37,9 @@ export { createTreeEditor, treeClipboardFormat } from "./tree.js";
 export { projectTreeVisibility, treeVisibilityNeighbor } from "./tree-visibility.js";
 export { createKanbanEditor } from "./kanban.js";
 export {
-  calendarAllDayLayout,
-  calendarBusyDates,
-  calendarEventsInMonth,
-  calendarEventsOnDay,
-  calendarMonthDayLayout,
-  calendarMonthWeekLayout,
-  calendarNowMarker,
   calendarOccurrenceTopology,
-  calendarTimedLayout,
-  calendarVisibleEvents,
   createCalendarEditor,
+  parseCalendarView,
   calendarClipboardFormat,
 } from "./calendar.js";
 export {
@@ -43,7 +47,7 @@ export {
   calendarRecurrenceWithInterval,
   calendarRecurrenceWithUntil,
   projectCalendarOccurrences,
-} from "./calendar-occurrence.js";
+} from "@interactive-os/json-document-calendar-document";
 export {
   calendarOccurrenceAfterIntent,
   calendarOccurrenceForInspector,
@@ -67,8 +71,7 @@ export {
   calendarShiftInstant,
   formatCalendarInstant,
   isCalendarAllDay,
-  parseCalendarView,
-} from "./calendar-validation.js";
+} from "@interactive-os/json-document-calendar-document";
 export { ANNOTATION_PROFILE_V1, annotationResizeHandle, annotationSelectorBounds, createAnnotationEditor, transformAnnotationSelector } from "./annotation.js";
 export { assertAnnotationDocument } from "./annotation-validation.js";
 export type {
@@ -201,7 +204,7 @@ export type {
   CalendarSelectionMovePlan,
   CalendarSelectionMoveTarget,
 } from "./calendar-selection-move.js";
-export type { CalendarOccurrence } from "./calendar-occurrence.js";
+export type { CalendarOccurrence } from "@interactive-os/json-document-calendar-document";
 export type {
   CalendarAllDayHandle,
   CalendarAllDayPointerIntent,
diff --git a/packages/json-document-editing/tests/calendar-protocol.test.ts b/packages/json-document-editing/tests/calendar-protocol.test.ts
index 3f291145..b35918c7 100644
--- a/packages/json-document-editing/tests/calendar-protocol.test.ts
+++ b/packages/json-document-editing/tests/calendar-protocol.test.ts
@@ -1,4 +1,6 @@
 import { describe, expect, test } from "vitest";
+import * as calendarDocument from "@interactive-os/json-document-calendar-document";
+import * as editing from "../src/index.js";
 import {
   addCalendarDate, bindCalendarAllDayIntent, bindCalendarMonthIntent, bindCalendarTimeGridIntent,
   calendarClipboardFormat, calendarOccurrenceTopology, calendarUpdateIntent, createCalendarEditor,
@@ -36,6 +38,41 @@ function visible(events: ReadonlyArray<CalendarEvent>) {
 }
 
 describe("Calendar protocol rejection", () => {
+  test("legacy Editing exports resolve to the canonical Document Type implementation", () => {
+    for (const symbol of [
+      "addCalendarDate", "calendarDocumentCalendars", "calendarVisibleEvents", "calendarNowMarker",
+      "calendarTimedLayout", "calendarAllDayLayout", "calendarMonthDayLayout", "calendarMonthWeekLayout",
+      "calendarEventsOnDay", "calendarEventsInMonth", "calendarBusyDates", "projectCalendarOccurrences",
+      "calendarRecurrenceWithFrequency", "calendarRecurrenceWithInterval", "calendarRecurrenceWithUntil",
+    ] as const) {
+      expect(editing[symbol]).toBe(calendarDocument[symbol]);
+    }
+  });
+
+  test.each([
+    "work",
+    null,
+    [{ id: 123, title: "Work", hidden: false, color: "accent" }],
+    [{ id: "work", title: 123, hidden: false, color: "accent" }],
+    [{ id: "work", title: "Work", hidden: "false", color: "accent" }],
+  ])("rejects malformed calendars instead of taking the legacy omission path: %j", (calendars) => {
+    expect(() => createCalendarEditor({ calendars, events: [] } as unknown as CalendarDocument)).toThrow();
+  });
+
+  test.each([false, true])("default paste uses the primary recurring occurrence, allDay=%s", (allDay) => {
+    const instance = editor([recurring(allDay)]);
+    const start = allDay ? "2026-08-03" : "2026-08-03T09:00";
+    capture(instance, start);
+    const payload = instance.copy()!;
+    const before = instance.snapshot;
+    expect(instance.paste(payload).ok).toBe(true);
+    expect(instance.primaryOccurrence?.start).toBe(start);
+    expect(instance.selectedEvents[0]?.start).toBe(start);
+    expect(instance.undo().ok).toBe(true);
+    expect(instance.snapshot.value).toEqual(before.value);
+    expect(instance.snapshot.selection).toEqual(before.selection);
+  });
+
   test.each([
     { type: "event.typo" },
     { type: "event.update", eventId: "a", end: "zz" },
diff --git a/packages/json-document-editing/tests/conformance/calendar-grammar.test.ts b/packages/json-document-editing/tests/conformance/calendar-grammar.test.ts
new file mode 100644
index 00000000..add48fdd
--- /dev/null
+++ b/packages/json-document-editing/tests/conformance/calendar-grammar.test.ts
@@ -0,0 +1,58 @@
+import { createJSONDocument } from "@interactive-os/json-document";
+import { expect } from "vitest";
+import { calendarOccurrenceTopology, createCalendarEditor, type CalendarDocument, type CalendarSelection } from "../../src/index.js";
+import { editingGrammar } from "./editing-grammar.js";
+
+const value: CalendarDocument = {
+  calendars: [{ id: "work", title: "Work", hidden: false, color: "accent" }],
+  events: [{ id: "a", title: "A", start: "2026-08-01T09:00", end: "2026-08-01T10:00", allDay: false,
+    calendarId: "work", recurrence: { freq: "daily", interval: 1, until: "2026-08-03" }, excludeDates: [] }],
+};
+const points = [1, 2, 3].map((day) => ({ eventId: "a", occurrenceStart: `2026-08-0${day}T09:00` }));
+const empty: CalendarSelection = { kind: "range", ranges: [], primaryIndex: null };
+
+editingGrammar("Calendar / materialized recurring occurrences / local history", () => {
+  const document = createJSONDocument(value);
+  let id = 0;
+  const editor = createCalendarEditor(document, { createId: () => `new-${++id}` });
+  const topology = calendarOccurrenceTopology(value, "2026-08-01", "2026-08-04");
+  const items = points.map((point, index) => ({ sourceEventId: "a", occurrenceStart: point.occurrenceStart,
+    event: { ...value.events[0]!, start: point.occurrenceStart, end: `2026-08-0${index + 1}T10:00`, recurrence: null, excludeDates: [] },
+  }));
+  const clipboard = {
+    type: "application/vnd.interactive-os.calendar+json" as const,
+    anchorOccurrenceStart: points[0]!.occurrenceStart,
+    items, text: items.map(({ event }) => `${event.start}\t${event.end}\t${event.title}`).join("\n"),
+  };
+  return {
+    document, editor, clipboard,
+    selectStart: () => editor.dispatch({ type: "selection.set", point: points[0]!, topology }),
+    extend: () => editor.dispatch({ type: "selection.set", point: points[2]!, mode: "extend", topology }),
+    assertSelected(selection) {
+      expect(selection).toEqual({ kind: "range", primaryIndex: 0, ranges: [{ anchor: points[0], focus: points[2], points }] });
+      expect(editor.primaryOccurrence?.start).toBe("2026-08-03T09:00");
+      expect(editor.selectedOccurrences.map((item) => item.start)).toEqual(points.map((point) => point.occurrenceStart));
+    },
+    edit: () => editor.dispatch({ type: "event.update", eventId: "a", title: "Changed" }),
+    assertEdited(snapshot) {
+      expect(snapshot.value).toEqual({ ...value, events: [{ ...value.events[0]!, title: "Changed" }] });
+      expect(editor.primaryOccurrence?.start).toBe("2026-08-01T09:00");
+    },
+    paste: () => editor.paste(clipboard),
+    assertPasted(snapshot) {
+      const pasted = items.map(({ event }, index) => ({ ...event, id: `new-${index + 1}`, start: `2026-08-0${index + 3}T09:00`, end: `2026-08-0${index + 3}T10:00` }));
+      expect(snapshot.value).toEqual({ ...value, events: [...value.events, ...pasted] });
+      expect(editor.selectedEvents.map((event) => event.id)).toEqual(["new-3", "new-1", "new-2"]);
+      expect(editor.primaryOccurrence).toEqual({ eventId: "new-3", start: "2026-08-05T09:00", end: "2026-08-05T10:00" });
+    },
+    assertCut(snapshot) {
+      expect(snapshot.value).toEqual({ ...value, events: [{ ...value.events[0]!, excludeDates: ["2026-08-01", "2026-08-02", "2026-08-03"] }] });
+      expect(snapshot.selection).toEqual(empty);
+    },
+    reject: () => editor.dispatch({ type: "event.update", eventId: "a", end: "2026-08-01T08:00" }),
+    rejectionCode: "event.invalid-interval",
+    noop: () => editor.dispatch({ type: "event.update", eventId: "a", title: "A" }),
+    removeExternal() { expect(document.commit([{ op: "remove", path: "/events/0" }]).ok).toBe(true); },
+    assertExternal(selection) { expect(selection).toEqual(empty); },
+  };
+});
diff --git a/packages/json-document-editing/tsconfig.json b/packages/json-document-editing/tsconfig.json
index 46c63cb7..cc9545cc 100644
--- a/packages/json-document-editing/tsconfig.json
+++ b/packages/json-document-editing/tsconfig.json
@@ -6,6 +6,7 @@
     "tsBuildInfoFile": "dist/.tsbuildinfo"
   },
   "references": [
+    { "path": "../json-document-calendar-document" },
     { "path": "../json-document" },
     { "path": "../json-document-selection" }
   ],
diff --git a/packages/json-document-editing/vitest.config.ts b/packages/json-document-editing/vitest.config.ts
index 38478cb0..d4dbf3f0 100644
--- a/packages/json-document-editing/vitest.config.ts
+++ b/packages/json-document-editing/vitest.config.ts
@@ -3,6 +3,7 @@ import { defineNodeProject } from "../../test/vitest.shared.js";
 export default defineNodeProject("json-document-editing", {
   resolve: {
     alias: {
+      "@interactive-os/json-document-calendar-document": new URL("../json-document-calendar-document/src/index.ts", import.meta.url).pathname,
       "@interactive-os/json-document": new URL("../json-document/src/application/document/index.ts", import.meta.url).pathname,
       "@interactive-os/json-document-selection": new URL("../json-document-selection/src/index.ts", import.meta.url).pathname,
     },
diff --git a/scripts/verify-external-kit.mjs b/scripts/verify-external-kit.mjs
index 35f54e27..fd080932 100644
--- a/scripts/verify-external-kit.mjs
+++ b/scripts/verify-external-kit.mjs
@@ -12,6 +12,7 @@ import { readJson, repositoryRoot } from "./workspace-graph.mjs";
 const kitWorkspaces = [
   "@interactive-os/json-document",
   "@interactive-os/json-document-selection",
+  "@interactive-os/json-document-calendar-document",
   "@interactive-os/json-document-editing",
   "@interactive-os/json-document-rich-text",
   "@interactive-os/json-document-file-intake",
diff --git a/site/config/json-document-source-aliases.ts b/site/config/json-document-source-aliases.ts
index 12c5aa01..dbb3dde2 100644
--- a/site/config/json-document-source-aliases.ts
+++ b/site/config/json-document-source-aliases.ts
@@ -7,6 +7,10 @@ export interface SourceAlias {
 
 export function jsonDocumentSourceAliases(): SourceAlias[] {
   return [
+    {
+      find: "@interactive-os/json-document-calendar-document",
+      replacement: sourceFile("packages/json-document-calendar-document/src/index.ts"),
+    },
     {
       find: "@interactive-os/json-document-a2ui",
       replacement: sourceFile("packages/json-document-a2ui/src/index.ts"),
diff --git a/site/package.json b/site/package.json
index 88ec1dd0..8c2daf13 100644
--- a/site/package.json
+++ b/site/package.json
@@ -58,6 +58,7 @@
     "@interactive-os/json-document-a2ui": "*",
     "@interactive-os/json-document-animation-react": "*",
     "@interactive-os/json-document-calendar": "*",
+    "@interactive-os/json-document-calendar-document": "*",
     "@interactive-os/json-document-collaboration": "*",
     "@interactive-os/json-document-composer": "*",
     "@interactive-os/json-document-composer-react": "*",
diff --git a/site/scripts/check-calendar-allday-span.mjs b/site/scripts/check-calendar-allday-span.mjs
index 179ea4a8..58ceadc8 100644
--- a/site/scripts/check-calendar-allday-span.mjs
+++ b/site/scripts/check-calendar-allday-span.mjs
@@ -2,11 +2,11 @@ import { readFileSync } from "node:fs";
 import { resolve } from "node:path";
 
 const root = resolve(new URL("../..", import.meta.url).pathname);
-const owner = read("packages/json-document-editing/src/calendar-validation.ts");
-const ownerIndex = read("packages/json-document-editing/src/index.ts");
+const owner = read("packages/json-document-calendar-document/src/calendar-validation.ts");
+const ownerIndex = read("packages/json-document-calendar-document/src/index.ts");
 const ownerTest = read("packages/json-document-editing/tests/calendar-validation.test.ts");
 const editor = read("packages/json-document-editing/src/calendar.ts");
-const eventPlan = read("packages/json-document-editing/src/calendar-event-plan.ts");
+const eventPlan = read("packages/json-document-calendar-document/src/calendar-operation.ts");
 const allDayPointer = read("packages/json-document-editing/src/calendar-allday-pointer.ts");
 const monthPointer = read("packages/json-document-editing/src/calendar-month-pointer.ts");
 const host = read("site/src/routes/calendar-demo/CalendarDemoRoute.tsx");
@@ -28,7 +28,7 @@ forbid(allDayPointer, /addCalendarDate\(release\.targetDay, 1\)/);
 forbid(eventPlan, /addCalendarDate\(start, 1\)/);
 forbid(host, /addCalendarDate\((?:day|value), 1\)/);
 requireText(usage, 'symbol: "calendarAllDaySpan"');
-requireText(usage, 'sourcePath: "packages/json-document-editing/src/calendar-validation.ts"');
+requireText(usage, 'sourcePath: "packages/json-document-calendar-document/src/calendar-validation.ts"');
 
 console.log("Calendar all-day span guard ok; owner, pointer consumers, editor, Host, CalendarTimeGrid, and Usage checked.");
 
diff --git a/site/scripts/check-calendar-cell-interval.mjs b/site/scripts/check-calendar-cell-interval.mjs
index 9fae381f..c331265f 100644
--- a/site/scripts/check-calendar-cell-interval.mjs
+++ b/site/scripts/check-calendar-cell-interval.mjs
@@ -18,7 +18,7 @@ requireText(navigator, "calendarCellInterval(cells)");
 forbid(calendar, /addCalendarDate\(yearStart,\s*-7\)/);
 forbid(calendar, /addCalendarDate\(yearEnd,\s*14\)/);
 forbid(navigator, /cells\[0\]\?\.date|cells\.at\(-1\)\?\.date/);
-requireText(usage, "UI Primitives `calendarCellInterval`");
+requireText(usage, "`calendarCellInterval`");
 requireText(sources, 'symbol: "calendarCellInterval"');
 requireText(sources, 'sourcePath: "packages/json-document-calendar/src/date-values.ts"');
 
diff --git a/site/scripts/check-calendar-date-part.mjs b/site/scripts/check-calendar-date-part.mjs
index 627ac576..17be5986 100644
--- a/site/scripts/check-calendar-date-part.mjs
+++ b/site/scripts/check-calendar-date-part.mjs
@@ -2,8 +2,8 @@ import { readFileSync } from "node:fs";
 import { resolve } from "node:path";
 
 const root = resolve(new URL("../..", import.meta.url).pathname);
-const owner = read("packages/json-document-editing/src/calendar-validation.ts");
-const ownerIndex = read("packages/json-document-editing/src/index.ts");
+const owner = read("packages/json-document-calendar-document/src/calendar-validation.ts");
+const ownerIndex = read("packages/json-document-calendar-document/src/index.ts");
 const ownerTest = read("packages/json-document-editing/tests/calendar-validation.test.ts");
 const host = read("site/src/routes/calendar-demo/CalendarDemoRoute.tsx");
 const inspector = read("packages/json-document-calendar/src/calendar-event-inspector.tsx");
@@ -16,9 +16,9 @@ requireCount(host, "calendarDatePart(", 2);
 requireCount(inspector, "calendarDatePart(", 1);
 forbid(host, /\.slice\(0,\s*10\)/);
 requireText(usage, 'symbol: "calendarDatePart"');
-requireText(usage, 'sourcePath: "packages/json-document-editing/src/calendar-validation.ts"');
+requireText(usage, 'sourcePath: "packages/json-document-calendar-document/src/calendar-validation.ts"');
 
-console.log("Calendar date-part guard ok; Editing owner, public export, contract test, Usage, and three Host consumers checked.");
+console.log("Calendar date-part guard ok; Document Type owner, public export, contract test, Usage, and three Host consumers checked.");
 
 function read(path) {
   return readFileSync(resolve(root, path), "utf8");
diff --git a/site/scripts/check-calendar-document-calendars.mjs b/site/scripts/check-calendar-document-calendars.mjs
index a19f9944..49f8de6b 100644
--- a/site/scripts/check-calendar-document-calendars.mjs
+++ b/site/scripts/check-calendar-document-calendars.mjs
@@ -2,8 +2,8 @@ import { readFileSync } from "node:fs";
 import { resolve } from "node:path";
 
 const root = resolve(new URL("../..", import.meta.url).pathname);
-const owner = read("packages/json-document-editing/src/calendar-validation.ts");
-const ownerIndex = read("packages/json-document-editing/src/index.ts");
+const owner = read("packages/json-document-calendar-document/src/calendar-validation.ts");
+const ownerIndex = read("packages/json-document-calendar-document/src/index.ts");
 const ownerTest = read("packages/json-document-editing/tests/calendar-validation.test.ts");
 const host = read("site/src/routes/calendar-demo/CalendarDemoRoute.tsx");
 const inspector = read("packages/json-document-calendar/src/calendar-event-inspector.tsx");
@@ -21,7 +21,7 @@ for (const symbol of ["calendarDocumentCalendars", "calendarDocumentCalendar"])
 forbid(host, /document\.calendars\s*\?\?\s*\[\]/);
 forbid(host, /document\.calendars\.find/);
 
-console.log("Calendar document calendars guard ok; Editing owner/export/tests, Host consumers, Usage, and source registration checked.");
+console.log("Calendar document calendars guard ok; Document Type owner/export/tests, Host consumers, Usage, and source registration checked.");
 
 function read(path) {
   return readFileSync(resolve(root, path), "utf8");
diff --git a/site/scripts/check-calendar-instant-format.mjs b/site/scripts/check-calendar-instant-format.mjs
index 2ac892c3..21c1dff9 100644
--- a/site/scripts/check-calendar-instant-format.mjs
+++ b/site/scripts/check-calendar-instant-format.mjs
@@ -2,8 +2,8 @@ import { readFileSync } from "node:fs";
 import { resolve } from "node:path";
 
 const root = resolve(new URL("../..", import.meta.url).pathname);
-const owner = read("packages/json-document-editing/src/calendar-validation.ts");
-const ownerIndex = read("packages/json-document-editing/src/index.ts");
+const owner = read("packages/json-document-calendar-document/src/calendar-validation.ts");
+const ownerIndex = read("packages/json-document-calendar-document/src/index.ts");
 const ownerTest = read("packages/json-document-editing/tests/calendar-validation.test.ts");
 const host = read("site/src/routes/calendar-demo/CalendarDemoRoute.tsx");
 const usage = read("docs/public/hands.md");
@@ -15,11 +15,11 @@ requireText(ownerTest, 'formatCalendarInstant(Temporal.PlainDateTime.from("2026-
 requireText(host, "formatCalendarInstant(Temporal.Now.plainDateTimeISO())");
 forbid(host, /function clockNow/);
 forbid(host, /\.toString\(\{ smallestUnit: "minute" \}\)/);
-requireText(usage, "Editing `formatCalendarInstant`");
+requireText(usage, "@interactive-os/json-document-calendar-document");
 requireText(sources, 'symbol: "formatCalendarInstant"');
-requireText(sources, 'sourcePath: "packages/json-document-editing/src/calendar-validation.ts"');
+requireText(sources, 'sourcePath: "packages/json-document-calendar-document/src/calendar-validation.ts"');
 
-console.log("Calendar instant format guard ok; Editing owner/export/test, Host clock composition, Usage, and source registration checked.");
+console.log("Calendar instant format guard ok; Document Type owner/export/test, Host clock composition, Usage, and source registration checked.");
 
 function read(path) {
   return readFileSync(resolve(root, path), "utf8");
diff --git a/site/scripts/check-calendar-interval-last-date.mjs b/site/scripts/check-calendar-interval-last-date.mjs
index a03bb1db..97809d3a 100644
--- a/site/scripts/check-calendar-interval-last-date.mjs
+++ b/site/scripts/check-calendar-interval-last-date.mjs
@@ -2,9 +2,9 @@ import { readFileSync } from "node:fs";
 import { resolve } from "node:path";
 
 const root = resolve(new URL("../..", import.meta.url).pathname);
-const owner = read("packages/json-document-editing/src/calendar-validation.ts");
-const editingConsumer = read("packages/json-document-editing/src/calendar.ts");
-const ownerIndex = read("packages/json-document-editing/src/index.ts");
+const owner = read("packages/json-document-calendar-document/src/calendar-validation.ts");
+const projectionConsumer = read("packages/json-document-calendar-document/src/calendar-projection.ts");
+const ownerIndex = read("packages/json-document-calendar-document/src/index.ts");
 const monthGrid = read("packages/json-document-calendar/src/calendar-month-grid.tsx");
 const timeGrid = read("packages/json-document-calendar/src/calendar-time-grid.tsx");
 const inspector = read("packages/json-document-calendar/src/calendar-event-inspector.tsx");
@@ -12,7 +12,7 @@ const host = read("site/src/routes/calendar-demo/CalendarDemoRoute.tsx");
 
 requireText(owner, "calendarIntervalLastDate");
 requireText(owner, "endInstant.hour === 0");
-requireText(editingConsumer, "calendarIntervalLastDate(start, end, allDay)");
+requireText(projectionConsumer, "calendarIntervalLastDate(start, end, allDay)");
 requireText(ownerIndex, "calendarIntervalLastDate");
 requireCount(host, "calendarIntervalLastDate(", 0);
 requireCount(inspector, "calendarIntervalLastDate(", 1);
@@ -20,7 +20,7 @@ requireCount(monthGrid, "calendarIntervalLastDate(", 2);
 requireCount(timeGrid, "calendarIntervalLastDate(", 1);
 forbid(host, /addCalendarDate\([^\n]*\.end[^\n]*, -1\)/);
 
-console.log("Calendar interval last-date guard ok; Editing owner, occurrence, Host, CalendarMonthGrid, and CalendarTimeGrid consumers checked.");
+console.log("Calendar interval last-date guard ok; Document Type owner, occurrence, Host, CalendarMonthGrid, and CalendarTimeGrid consumers checked.");
 
 function read(path) {
   return readFileSync(resolve(root, path), "utf8");
diff --git a/site/scripts/check-calendar-recurrence-transition.mjs b/site/scripts/check-calendar-recurrence-transition.mjs
index b5fd25ec..e2ee2ad9 100644
--- a/site/scripts/check-calendar-recurrence-transition.mjs
+++ b/site/scripts/check-calendar-recurrence-transition.mjs
@@ -2,8 +2,8 @@ import { readFileSync } from "node:fs";
 import { resolve } from "node:path";
 
 const root = resolve(new URL("../..", import.meta.url).pathname);
-const owner = read("packages/json-document-editing/src/calendar-occurrence.ts");
-const ownerIndex = read("packages/json-document-editing/src/index.ts");
+const owner = read("packages/json-document-calendar-document/src/calendar-occurrence.ts");
+const ownerIndex = read("packages/json-document-calendar-document/src/index.ts");
 const ownerTest = read("packages/json-document-editing/tests/calendar-editor.test.ts");
 const host = read("site/src/routes/calendar-demo/CalendarDemoRoute.tsx");
 const inspector = read("packages/json-document-calendar/src/calendar-event-inspector.tsx");
@@ -22,11 +22,11 @@ forbid(inspector, /as CalendarRecurrence\["freq"\]/);
 forbid(inspector, /Math\.max\(1, Math\.floor\(Number\(event\.target\.value\)/);
 forbid(inspector, /recurrence:\s*\{\s*\.\.\.selectedEvent\.recurrence!/);
 forbid(inspector, /selectedEvent\.recurrence!/);
-requireText(usage, "Editing\n`calendarRecurrenceWithFrequency`");
-requireText(sources, 'sourcePath: "packages/json-document-editing/src/calendar-occurrence.ts"');
+requireText(usage, "@interactive-os/json-document-calendar-document");
+requireText(sources, 'sourcePath: "packages/json-document-calendar-document/src/calendar-occurrence.ts"');
 requireText(browserTest, "Calendar recurrence inspector applies canonical model transitions");
 
-console.log("Calendar recurrence transition guard ok; Editing owner/tests, three Host handlers, Usage, and source registration checked.");
+console.log("Calendar recurrence transition guard ok; Document Type owner/tests, three Host handlers, Usage, and source registration checked.");
 
 function read(path) {
   return readFileSync(resolve(root, path), "utf8");
diff --git a/site/scripts/check-calendar-temporal.mjs b/site/scripts/check-calendar-temporal.mjs
index 05177b1f..baa94e6d 100644
--- a/site/scripts/check-calendar-temporal.mjs
+++ b/site/scripts/check-calendar-temporal.mjs
@@ -30,6 +30,7 @@ if (calendarTemporalViolations(goodFixture, "conforming fixture").length !== 0)
 }
 
 const files = [
+  ...collect(path.join(repositoryRoot, "packages/json-document-calendar-document/src"), /^calendar.*\.ts$/),
   ...collect(path.join(repositoryRoot, "packages/json-document-editing/src"), /^calendar.*\.ts$/),
   ...collect(path.join(repositoryRoot, "packages/json-document-calendar/src"), /\.[jt]sx?$/),
   path.join(repositoryRoot, "packages/json-document-calendar/src/date-values.ts"),
diff --git a/site/scripts/check-calendar-view-parser.mjs b/site/scripts/check-calendar-view-parser.mjs
index 097fdbb3..2c68d7ab 100644
--- a/site/scripts/check-calendar-view-parser.mjs
+++ b/site/scripts/check-calendar-view-parser.mjs
@@ -2,7 +2,7 @@ import { readFileSync } from "node:fs";
 import { resolve } from "node:path";
 
 const root = resolve(new URL("../..", import.meta.url).pathname);
-const owner = read("packages/json-document-editing/src/calendar-validation.ts");
+const owner = read("packages/json-document-editing/src/calendar.ts");
 const ownerIndex = read("packages/json-document-editing/src/index.ts");
 const ownerTest = read("packages/json-document-editing/tests/calendar-validation.test.ts");
 const route = read("site/src/routes/calendar-demo/calendar-search.ts");
@@ -15,9 +15,9 @@ requireText(ownerTest, '["day", "week", "month", "year"].map(parseCalendarView)'
 requireText(route, "parseCalendarView(search.view) ?? calendarSearchDefaults.view");
 forbid(route, /new Set\(\["day", "week", "month", "year"\]\)/);
 forbid(route, /as CalendarView/);
-requireText(usage, "`parseCalendarView`가 판별하고");
+requireText(usage, "`parseCalendarView`");
 requireText(sources, 'symbol: "parseCalendarView"');
-requireText(sources, 'sourcePath: "packages/json-document-editing/src/calendar-validation.ts"');
+requireText(sources, 'sourcePath: "packages/json-document-editing/src/calendar.ts"');
 
 console.log("Calendar view parser guard ok; Editing owner, public export, tests, Host composition, Usage, and source registration checked.");
 
diff --git a/site/scripts/check-document-type-audits.mjs b/site/scripts/check-document-type-audits.mjs
index 5cd7b6d0..6bf10710 100644
--- a/site/scripts/check-document-type-audits.mjs
+++ b/site/scripts/check-document-type-audits.mjs
@@ -6,7 +6,7 @@ const ledger = JSON.parse(readFileSync(join(root, "audits/document-types.json"),
 const siteRoutes = JSON.parse(readFileSync(join(root, "site/site-routes.json"), "utf8"));
 const allowed = new Set(["canonical consumer", "Host composition", "duplicate implementation", "canonical API gap", "missing canonical module", "mislocated module", "out of scope", "unverified"]);
 const expectedCandidates = siteRoutes
-  .filter((route) => route.navigationGroup === "Document Types" && route.path !== "/docs/document-types")
+  .filter((route) => route.navigationGroup === "Document Types" && route.path.startsWith("/docs/document-types/"))
   .map((route) => route.path.slice("/docs/document-types/".length));
 
 if (JSON.stringify(ledger.candidates) !== JSON.stringify(expectedCandidates)) throw new Error("Document Type audit candidates do not match the TBD navigation denominator");
@@ -51,8 +51,25 @@ const calendar = ledger.audits.calendar;
 for (const role of ["Document Model", "Validation", "Projection", "Document Operation", "Editing lifecycle", "Affordance", "Web Adapter", "Hand composition", "Reusable UI behavior", "Host composition"]) {
   if (!calendar.occurrences.some((occurrence) => occurrence.role === role)) throw new Error(`Calendar audit is missing role: ${role}`);
 }
-if (calendar.status !== "audited-tbd" || !calendar.occurrences.some((occurrence) => !["canonical consumer", "Host composition"].includes(occurrence.disposition))) {
-  throw new Error("Calendar must remain audited-tbd while nonconforming occurrences remain");
+const remaining = calendar.occurrences.filter((occurrence) => !["canonical consumer", "Host composition"].includes(occurrence.disposition));
+if (calendar.status !== (remaining.length === 0 ? "owner-closed" : "audited-tbd")) {
+  throw new Error("Calendar audit status must reflect its remaining ownership gaps");
+}
+if (calendar.status === "owner-closed") {
+  const closure = calendar.closure;
+  if (!Array.isArray(closure?.verification) || closure.verification.length === 0) throw new Error("Calendar closure needs executable verification evidence");
+  for (const path of [closure.publicEntry, closure.referencePath, closure.sourceRegistration, ...closure.verification]) {
+    if (typeof path !== "string" || !existsSync(join(root, path))) throw new Error(`Calendar closure evidence missing: ${path}`);
+  }
+  for (const path of [closure.apiPath, closure.usagePath, closure.usagePagePath?.split("#")[0]]) {
+    if (!siteRoutes.some((route) => route.path === path)) throw new Error(`Calendar closure route missing: ${path}`);
+  }
+  const manifest = JSON.parse(readFileSync(join(root, "packages/json-document-calendar-document/package.json"), "utf8"));
+  if (closure.owner !== manifest.name) throw new Error("Calendar closure owner must match its public package");
+  const dependencies = Object.keys({ ...manifest.dependencies, ...manifest.peerDependencies });
+  if (dependencies.some((name) => ["@interactive-os/json-document-editing", "@interactive-os/json-document-selection", "@interactive-os/json-document-calendar", "react"].includes(name))) {
+    throw new Error("Calendar Document Type must remain usable without Editing, Selection or React");
+  }
 }
 
 console.log(`Document Type audits ok; candidates=${ledger.candidates.length}; candidate profiles=${Object.keys(ledger.candidateProfiles).length}; audited=${Object.keys(ledger.audits).length}; Calendar occurrences=${calendar.occurrences.length}.`);
diff --git a/site/site-routes.json b/site/site-routes.json
index 6fa7596e..bf861945 100644
--- a/site/site-routes.json
+++ b/site/site-routes.json
@@ -127,9 +127,9 @@
   },
   {
     "path": "/docs/document-types/calendar",
-    "label": "Calendar · TBD",
-    "title": "Calendar Document Type · TBD - json-document",
-    "description": "Calendar의 Document Type 소유권을 확정하기 전 후보 상태와 필요한 증거를 정리합니다.",
+    "label": "Calendar · RC",
+    "title": "Calendar Document Type · RC - json-document",
+    "description": "Calendar 문서 모델·검증·의미 연산·projection의 공개 소유자와 RC 계약을 설명합니다.",
     "language": "ko",
     "navigationGroup": "Document Types"
   },
@@ -412,6 +412,14 @@
     "language": "ko",
     "navigationGroup": "Hands"
   },
+  {
+    "path": "/docs/api/calendar-document",
+    "label": "API · Calendar Document",
+    "title": "Calendar Document Type API - json-document",
+    "description": "@interactive-os/json-document-calendar-document의 문서 계약과 public API입니다.",
+    "language": "ko",
+    "navigationGroup": "Document Types"
+  },
   {
     "path": "/docs/api/calendar",
     "label": "API · Calendar",
diff --git a/site/src/app/routeTree.gen.ts b/site/src/app/routeTree.gen.ts
index e1ead577..aa2027eb 100644
--- a/site/src/app/routeTree.gen.ts
+++ b/site/src/app/routeTree.gen.ts
@@ -134,6 +134,7 @@ import { Route as PageDocsApiAjvRouteImport } from "./routes/_page/docs/api/ajv"
 import { Route as PageDocsApiAnimationReactRouteImport } from "./routes/_page/docs/api/animation-react";
 import { Route as PageDocsApiAnnotationRouteImport } from "./routes/_page/docs/api/annotation";
 import { Route as PageDocsApiCalendarRouteImport } from "./routes/_page/docs/api/calendar";
+import { Route as PageDocsApiCalendarDocumentRouteImport } from "./routes/_page/docs/api/calendar-document";
 import { Route as PageDocsApiCollaborationRouteImport } from "./routes/_page/docs/api/collaboration";
 import { Route as PageDocsApiComposerRouteImport } from "./routes/_page/docs/api/composer";
 import { Route as PageDocsApiComposerReactRouteImport } from "./routes/_page/docs/api/composer-react";
@@ -823,6 +824,12 @@ const PageDocsApiCalendarRoute = PageDocsApiCalendarRouteImport.update({
   path: "/docs/api/calendar",
   getParentRoute: () => PageRoute,
 } as any);
+const PageDocsApiCalendarDocumentRoute =
+  PageDocsApiCalendarDocumentRouteImport.update({
+    id: "/docs/api/calendar-document",
+    path: "/docs/api/calendar-document",
+    getParentRoute: () => PageRoute,
+  } as any);
 const PageDocsApiCollaborationRoute =
   PageDocsApiCollaborationRouteImport.update({
     id: "/docs/api/collaboration",
@@ -1127,6 +1134,7 @@ export interface FileRoutesByFullPath {
   "/docs/api/animation-react": typeof PageDocsApiAnimationReactRoute;
   "/docs/api/annotation": typeof PageDocsApiAnnotationRoute;
   "/docs/api/calendar": typeof PageDocsApiCalendarRoute;
+  "/docs/api/calendar-document": typeof PageDocsApiCalendarDocumentRoute;
   "/docs/api/collaboration": typeof PageDocsApiCollaborationRoute;
   "/docs/api/composer": typeof PageDocsApiComposerRoute;
   "/docs/api/composer-react": typeof PageDocsApiComposerReactRoute;
@@ -1285,6 +1293,7 @@ export interface FileRoutesByTo {
   "/docs/api/animation-react": typeof PageDocsApiAnimationReactRoute;
   "/docs/api/annotation": typeof PageDocsApiAnnotationRoute;
   "/docs/api/calendar": typeof PageDocsApiCalendarRoute;
+  "/docs/api/calendar-document": typeof PageDocsApiCalendarDocumentRoute;
   "/docs/api/collaboration": typeof PageDocsApiCollaborationRoute;
   "/docs/api/composer": typeof PageDocsApiComposerRoute;
   "/docs/api/composer-react": typeof PageDocsApiComposerReactRoute;
@@ -1445,6 +1454,7 @@ export interface FileRoutesById {
   "/_page/docs/api/animation-react": typeof PageDocsApiAnimationReactRoute;
   "/_page/docs/api/annotation": typeof PageDocsApiAnnotationRoute;
   "/_page/docs/api/calendar": typeof PageDocsApiCalendarRoute;
+  "/_page/docs/api/calendar-document": typeof PageDocsApiCalendarDocumentRoute;
   "/_page/docs/api/collaboration": typeof PageDocsApiCollaborationRoute;
   "/_page/docs/api/composer": typeof PageDocsApiComposerRoute;
   "/_page/docs/api/composer-react": typeof PageDocsApiComposerReactRoute;
@@ -1605,6 +1615,7 @@ export interface FileRouteTypes {
     | "/docs/api/animation-react"
     | "/docs/api/annotation"
     | "/docs/api/calendar"
+    | "/docs/api/calendar-document"
     | "/docs/api/collaboration"
     | "/docs/api/composer"
     | "/docs/api/composer-react"
@@ -1763,6 +1774,7 @@ export interface FileRouteTypes {
     | "/docs/api/animation-react"
     | "/docs/api/annotation"
     | "/docs/api/calendar"
+    | "/docs/api/calendar-document"
     | "/docs/api/collaboration"
     | "/docs/api/composer"
     | "/docs/api/composer-react"
@@ -1922,6 +1934,7 @@ export interface FileRouteTypes {
     | "/_page/docs/api/animation-react"
     | "/_page/docs/api/annotation"
     | "/_page/docs/api/calendar"
+    | "/_page/docs/api/calendar-document"
     | "/_page/docs/api/collaboration"
     | "/_page/docs/api/composer"
     | "/_page/docs/api/composer-react"
@@ -2841,6 +2854,13 @@ declare module "@tanstack/react-router" {
       preLoaderRoute: typeof PageDocsApiCalendarRouteImport;
       parentRoute: typeof PageRoute;
     };
+    "/_page/docs/api/calendar-document": {
+      id: "/_page/docs/api/calendar-document";
+      path: "/docs/api/calendar-document";
+      fullPath: "/docs/api/calendar-document";
+      preLoaderRoute: typeof PageDocsApiCalendarDocumentRouteImport;
+      parentRoute: typeof PageRoute;
+    };
     "/_page/docs/api/collaboration": {
       id: "/_page/docs/api/collaboration";
       path: "/docs/api/collaboration";
@@ -3189,6 +3209,7 @@ interface PageRouteChildren {
   PageDocsApiAnimationReactRoute: typeof PageDocsApiAnimationReactRoute;
   PageDocsApiAnnotationRoute: typeof PageDocsApiAnnotationRoute;
   PageDocsApiCalendarRoute: typeof PageDocsApiCalendarRoute;
+  PageDocsApiCalendarDocumentRoute: typeof PageDocsApiCalendarDocumentRoute;
   PageDocsApiCollaborationRoute: typeof PageDocsApiCollaborationRoute;
   PageDocsApiComposerRoute: typeof PageDocsApiComposerRoute;
   PageDocsApiComposerReactRoute: typeof PageDocsApiComposerReactRoute;
@@ -3347,6 +3368,7 @@ const PageRouteChildren: PageRouteChildren = {
   PageDocsApiAnimationReactRoute: PageDocsApiAnimationReactRoute,
   PageDocsApiAnnotationRoute: PageDocsApiAnnotationRoute,
   PageDocsApiCalendarRoute: PageDocsApiCalendarRoute,
+  PageDocsApiCalendarDocumentRoute: PageDocsApiCalendarDocumentRoute,
   PageDocsApiCollaborationRoute: PageDocsApiCollaborationRoute,
   PageDocsApiComposerRoute: PageDocsApiComposerRoute,
   PageDocsApiComposerReactRoute: PageDocsApiComposerReactRoute,
diff --git a/site/src/app/routes/_page/docs/api/calendar-document.tsx b/site/src/app/routes/_page/docs/api/calendar-document.tsx
new file mode 100644
index 00000000..e698e1ec
--- /dev/null
+++ b/site/src/app/routes/_page/docs/api/calendar-document.tsx
@@ -0,0 +1,8 @@
+import { createFileRoute } from "@tanstack/react-router";
+import { DocsRoute } from "../../../../../routes/docs/DocsRoute";
+
+export const Route = createFileRoute("/_page/docs/api/calendar-document")({
+  component: function PackageApiReferenceRoute() {
+    return <DocsRoute pageId="calendarDocumentApi" />;
+  },
+});
diff --git a/site/src/routes/calendar-demo/CalendarDemoRoute.tsx b/site/src/routes/calendar-demo/CalendarDemoRoute.tsx
index 55e1daf0..89e87a7e 100644
--- a/site/src/routes/calendar-demo/CalendarDemoRoute.tsx
+++ b/site/src/routes/calendar-demo/CalendarDemoRoute.tsx
@@ -2,23 +2,25 @@ import { useRef, useState, type ReactNode } from "react";
 import { ArrowUp, CalendarDays, ChevronLeft, ChevronRight, Clock3, Pencil, Repeat2, Sparkles, Trash2 } from "lucide-react";
 import { Temporal } from "@js-temporal/polyfill";
 
+import {
+  calendarOccurrenceTopology,
+  calendarClipboardFormat,
+  createCalendarEditor,
+  type CalendarView,
+} from "@interactive-os/json-document-editing";
 import {
   calendarBusyDates,
   calendarDatePart,
   calendarDocumentCalendar,
   calendarDocumentCalendars,
   calendarInstantAt,
-  calendarOccurrenceTopology,
   calendarShiftInstant,
   calendarVisibleEvents,
-  calendarClipboardFormat,
-  createCalendarEditor,
   formatCalendarInstant,
   type CalendarDocument,
   type CalendarEvent,
   type CalendarRecurrence,
-  type CalendarView,
-} from "@interactive-os/json-document-editing";
+} from "@interactive-os/json-document-calendar-document";
 import { useAnchoredFloatingPosition } from "@interactive-os/json-document-react";
 import { createWebClipboardSurface, createWebJSONClipboardRepresentation, isWebEditableTarget } from "@interactive-os/json-document-web";
 import {
diff --git a/site/src/routes/calendar-demo/calendar-demo-navigator.tsx b/site/src/routes/calendar-demo/calendar-demo-navigator.tsx
index df53d59d..406923cf 100644
--- a/site/src/routes/calendar-demo/calendar-demo-navigator.tsx
+++ b/site/src/routes/calendar-demo/calendar-demo-navigator.tsx
@@ -1,6 +1,9 @@
 import { useEffect, useState, type ReactNode } from "react";
 import { ChevronLeft, ChevronRight } from "lucide-react";
-import { calendarBusyDates, type CalendarEvent } from "@interactive-os/json-document-editing";
+import {
+  calendarBusyDates,
+  type CalendarEvent,
+} from "@interactive-os/json-document-calendar-document";
 import {
   addCalendarMonths,
   calendarCellInterval,
diff --git a/site/src/routes/docs/DocsRoute.tsx b/site/src/routes/docs/DocsRoute.tsx
index 3a7b119d..a3ae514b 100644
--- a/site/src/routes/docs/DocsRoute.tsx
+++ b/site/src/routes/docs/DocsRoute.tsx
@@ -87,6 +87,7 @@ const docIllustrations: Record<DocPageId, PetiteCatIllustration> = {
   databaseApi: "database",
   annotationApi: "cursor",
   calendarApi: "database",
+  calendarDocumentApi: "database",
   webApi: "terminal",
   contenteditableApi: "cursor",
   richTextApi: "terminal",
diff --git a/site/src/routes/docs/DocumentTypeCandidateRoute.tsx b/site/src/routes/docs/DocumentTypeCandidateRoute.tsx
index c86e6237..ee8c07ef 100644
--- a/site/src/routes/docs/DocumentTypeCandidateRoute.tsx
+++ b/site/src/routes/docs/DocumentTypeCandidateRoute.tsx
@@ -19,10 +19,11 @@ export function DocumentTypeCandidateRoute(props: { readonly candidate: Document
   const name = candidateNames[props.candidate];
   const profile = documentTypeAudits.candidateProfiles[props.candidate];
   const audit = props.candidate === "calendar" ? documentTypeAudits.audits.calendar : undefined;
+  const ownerClosed = audit?.status === "owner-closed";
   const auditSource = audit === undefined ? "" : `
 ## 소스 기반 감사 현황
 
-- 상태: **감사됨 · TBD**
+- 상태: **${ownerClosed ? "소유권 확정 · RC" : "감사됨 · TBD"}**
 - 감사 분모: **${audit.denominator}개 책임 occurrence**
 - 정본 소비/Host composition: **${audit.occurrences.filter((item) => item.disposition === "canonical consumer" || item.disposition === "Host composition").length}개**
 - canonical move 필요: **${audit.occurrences.filter((item) => item.disposition !== "canonical consumer" && item.disposition !== "Host composition").length}개**
@@ -34,10 +35,11 @@ ${audit.occurrences.map((item) => `| ${item.role} | \`${item.currentOwner}\` | $
 감사 분모는 \`${audit.horizon.enumerators.join("`, `")}\`에서 출발하며,
 fixture, copy, layout-only CSS, tests와 generated route는 제외합니다.
 `;
-  const source = `## 후보 상태
+  const source = `## ${ownerClosed ? "공개 소유자 · RC" : "후보 상태"}
 
-${name}은 현재 Document Type 후보입니다. 기존 package와 Hands에서 실제 책임을
-옮기거나 완료를 선언하지 않았습니다.
+${ownerClosed
+  ? `${name}의 모델·검증·의미 연산·projection은 \`@interactive-os/json-document-calendar-document\`가 소유합니다. Editing·Selection·React 없이 소비할 수 있으며 기존 Editing export는 호환 경로로 유지합니다. 소유권 확정은 wire Stable 승격을 뜻하지 않습니다.`
+  : `${name}은 현재 Document Type 후보입니다. 기존 package와 Hands에서 실제 책임을 옮기거나 완료를 선언하지 않았습니다.`}
 
 ## 왜 필요한가
 
@@ -47,10 +49,11 @@ ${profile.why}
 
 ${profile.does}
 
-## 현재 관찰된 schema · TBD
+## ${ownerClosed ? "현재 RC 모델" : "현재 관찰된 schema · TBD"}
 
-이 schema는 현재 source에 존재하는 document interface를 축약한 감사 입력입니다.
-정본 owner와 schema 계약이 확정됐다는 뜻은 아닙니다.
+${ownerClosed
+  ? "아래는 정본 document interface입니다. 필드 생략의 legacy 호환, 잘못된 타입 거절과 시간·반복 의미는 [소유자 API 계약](/docs/api/calendar-document)에 명시합니다."
+  : "이 schema는 현재 source에 존재하는 document interface를 축약한 감사 입력입니다. 정본 owner와 schema 계약이 확정됐다는 뜻은 아닙니다."}
 
 \`\`\`ts
 ${profile.schema}
@@ -65,22 +68,24 @@ ${profile.schema}
 ${profile.fields.map((field) => `| \`${field.name}\` | ${field.description} |`).join("\n")}
 ${auditSource}
 
-## 확정에 필요한 증거
+## ${ownerClosed ? "확정 증거와 남은 범위" : "확정에 필요한 증거"}
 
 1. model, invariant, Document Operation과 Projection의 canonical owner
 2. owner package의 안정적인 public API와 API reference
 3. 공개 API를 직접 사용하는 site Usage와 source registration
 4. 같은 책임을 구현하는 Host 또는 Demo local bypass가 없다는 감사 결과
 
-증거가 닫히기 전에는 이 페이지와 내비게이션을 \`${name} · TBD\`로 유지합니다.
+${ownerClosed
+  ? "[공개 API와 값 계약](/docs/api/calendar-document), [Calendar Usage 및 Source](/editors#calendar-editor), 독립 Document Type 테스트와 공통 Calendar Editing Grammar가 연결돼 있습니다. timezone/DST·서버 동기화·AI·RRULE·pagination·독립 구현 conformance는 TBD로 남습니다."
+  : `증거가 닫히기 전에는 이 페이지와 내비게이션을 \`${name} · TBD\`로 유지합니다.`}
 `;
 
   return (
     <DocumentationPage
-      title={`${name} Document Type · TBD`}
+      title={`${name} Document Type · ${ownerClosed ? "RC" : "TBD"}`}
       source={source}
       illustration="braces"
-      summary="후보의 이름만 등록했으며 소유권과 구현 경계는 아직 확정하지 않았습니다."
+      summary={ownerClosed ? "문서 모델·검증·의미 연산·projection의 공개 소유자와 검증 범위를 설명합니다." : "후보의 이름만 등록했으며 소유권과 구현 경계는 아직 확정하지 않았습니다."}
     />
   );
 }
diff --git a/site/src/routes/docs/doc-pages.ts b/site/src/routes/docs/doc-pages.ts
index ec4689ed..380c3a88 100644
--- a/site/src/routes/docs/doc-pages.ts
+++ b/site/src/routes/docs/doc-pages.ts
@@ -17,6 +17,8 @@ import markdownReactApiMarkdown from "../../../../docs/api-reference/markdown-re
 import databaseApiMarkdown from "../../../../docs/api-reference/database.md?raw";
 import annotationApiMarkdown from "../../../../docs/api-reference/annotation.md?raw";
 import calendarApiMarkdown from "../../../../docs/api-reference/calendar.md?raw";
+import calendarDocumentApiMarkdown from "../../../../docs/api-reference/calendar-document.md?raw";
+import calendarDocumentContractMarkdown from "../../../../packages/json-document-calendar-document/docs/api.md?raw";
 import webApiMarkdown from "../../../../docs/api-reference/web.md?raw";
 import contenteditableApiMarkdown from "../../../../docs/api-reference/contenteditable.md?raw";
 import richTextApiMarkdown from "../../../../docs/api-reference/rich-text.md?raw";
@@ -192,6 +194,7 @@ export const docPages = {
   databaseApi: docPage("/docs/api/database", databaseApiMarkdown),
   annotationApi: docPage("/docs/api/annotation", annotationApiMarkdown),
   calendarApi: docPage("/docs/api/calendar", `[시간·반복·거절 계약: Editing의 Calendar protocol profile](/docs/api/editing#calendar-protocol-profile-rc)\n\n${calendarApiMarkdown}`),
+  calendarDocumentApi: docPage("/docs/api/calendar-document", `${calendarDocumentContractMarkdown}\n\n${calendarDocumentApiMarkdown}`),
   webApi: docPage("/docs/api/web", webApiMarkdown),
   contenteditableApi: docPage("/docs/api/contenteditable", contenteditableApiMarkdown),
   richTextApi: docPage("/docs/api/rich-text", richTextApiMarkdown),
diff --git a/site/src/shared/demo-workbench/demo-sources.ts b/site/src/shared/demo-workbench/demo-sources.ts
index 930f514a..b8ba9902 100644
--- a/site/src/shared/demo-workbench/demo-sources.ts
+++ b/site/src/shared/demo-workbench/demo-sources.ts
@@ -1,16 +1,18 @@
 import type { CodeLanguage } from "../ui/code-tokens";
 import pointerTrackingSource from "../../../../packages/json-document/src/foundation/patch/track.ts?raw";
 import editingObservationSource from "../../../../packages/json-document-react/src/editing-observation.ts?raw";
+import calendarDocumentModelSource from "../../../../packages/json-document-calendar-document/src/calendar-model.ts?raw";
+import calendarDocumentProjectionSource from "../../../../packages/json-document-calendar-document/src/calendar-projection.ts?raw";
 import calendarEditingSource from "../../../../packages/json-document-editing/src/calendar.ts?raw";
-import calendarEventPlanSource from "../../../../packages/json-document-editing/src/calendar-event-plan.ts?raw";
+import calendarEventPlanSource from "../../../../packages/json-document-calendar-document/src/calendar-operation.ts?raw";
 import calendarAllDayPointerSource from "../../../../packages/json-document-editing/src/calendar-allday-pointer.ts?raw";
 import calendarMonthPointerSource from "../../../../packages/json-document-editing/src/calendar-month-pointer.ts?raw";
 import calendarTimeGridPointerSource from "../../../../packages/json-document-editing/src/calendar-time-grid-pointer.ts?raw";
-import calendarOccurrenceSource from "../../../../packages/json-document-editing/src/calendar-occurrence.ts?raw";
+import calendarOccurrenceSource from "../../../../packages/json-document-calendar-document/src/calendar-occurrence.ts?raw";
 import calendarPreviewSource from "../../../../packages/json-document-editing/src/calendar-preview.ts?raw";
 import calendarSelectionSource from "../../../../packages/json-document-editing/src/calendar-selection.ts?raw";
 import calendarSelectionMoveSource from "../../../../packages/json-document-editing/src/calendar-selection-move.ts?raw";
-import calendarValidationSource from "../../../../packages/json-document-editing/src/calendar-validation.ts?raw";
+import calendarValidationSource from "../../../../packages/json-document-calendar-document/src/calendar-validation.ts?raw";
 import calendarEventLabelSource from "../../../../packages/json-document-calendar/src/calendar-event-label.ts?raw";
 import dateControlsSource from "../../../../packages/json-document-calendar/src/date-controls.tsx?raw";
 import dateGridSource from "../../../../packages/json-document-calendar/src/date-grid.tsx?raw";
@@ -142,6 +144,7 @@ const packageReferencePaths = new Map([
   ["packages/json-document-selection/", "/docs/api/selection"],
   ["packages/json-document-editing/", "/docs/api/editing"],
   ["packages/json-document-calendar/", "/docs/api/calendar"],
+  ["packages/json-document-calendar-document/", "/docs/api/calendar-document"],
   ["packages/json-document-react/", "/docs/api/react"],
   ["packages/json-document-react-hook-form/", "/docs/api/react-hook-form"],
   ["packages/json-document-ajv/", "/docs/api/ajv"],
@@ -188,16 +191,18 @@ const excludedSources = new Set([
 ]);
 const registeredUsageSources = new Map<string, string>([
   ["packages/json-document/src/foundation/patch/track.ts", pointerTrackingSource],
+  ["packages/json-document-calendar-document/src/calendar-model.ts", calendarDocumentModelSource],
+  ["packages/json-document-calendar-document/src/calendar-projection.ts", calendarDocumentProjectionSource],
   ["packages/json-document-editing/src/calendar.ts", calendarEditingSource],
   ["packages/json-document-editing/src/calendar-allday-pointer.ts", calendarAllDayPointerSource],
   ["packages/json-document-editing/src/calendar-month-pointer.ts", calendarMonthPointerSource],
   ["packages/json-document-editing/src/calendar-time-grid-pointer.ts", calendarTimeGridPointerSource],
-  ["packages/json-document-editing/src/calendar-occurrence.ts", calendarOccurrenceSource],
+  ["packages/json-document-calendar-document/src/calendar-occurrence.ts", calendarOccurrenceSource],
   ["packages/json-document-editing/src/calendar-preview.ts", calendarPreviewSource],
-  ["packages/json-document-editing/src/calendar-event-plan.ts", calendarEventPlanSource],
+  ["packages/json-document-calendar-document/src/calendar-operation.ts", calendarEventPlanSource],
   ["packages/json-document-editing/src/calendar-selection.ts", calendarSelectionSource],
   ["packages/json-document-editing/src/calendar-selection-move.ts", calendarSelectionMoveSource],
-  ["packages/json-document-editing/src/calendar-validation.ts", calendarValidationSource],
+  ["packages/json-document-calendar-document/src/calendar-validation.ts", calendarValidationSource],
   ["packages/json-document-calendar/src/calendar-event-label.ts", calendarEventLabelSource],
   ["packages/json-document-calendar/src/date-controls.tsx", dateControlsSource],
   ["packages/json-document-calendar/src/date-grid.tsx", dateGridSource],
@@ -394,15 +399,45 @@ const registeredPublicUsages = [
     symbol: "findWebPointTarget",
     sourcePath: "packages/json-document-web/src/point-target.ts",
   },
+  {
+    packageName: "@interactive-os/json-document-calendar-document",
+    symbol: "CalendarDocument",
+    sourcePath: "packages/json-document-calendar-document/src/calendar-model.ts",
+  },
+  {
+    packageName: "@interactive-os/json-document-calendar-document",
+    symbol: "validateCalendarDocument",
+    sourcePath: "packages/json-document-calendar-document/src/calendar-validation.ts",
+  },
+  {
+    packageName: "@interactive-os/json-document-calendar-document",
+    symbol: "assertCalendarDocument",
+    sourcePath: "packages/json-document-calendar-document/src/calendar-validation.ts",
+  },
+  {
+    packageName: "@interactive-os/json-document-calendar-document",
+    symbol: "planCalendarEventRemoval",
+    sourcePath: "packages/json-document-calendar-document/src/calendar-operation.ts",
+  },
+  {
+    packageName: "@interactive-os/json-document-calendar-document",
+    symbol: "planCalendarOccurrenceRemoval",
+    sourcePath: "packages/json-document-calendar-document/src/calendar-operation.ts",
+  },
+  {
+    packageName: "@interactive-os/json-document-calendar-document",
+    symbol: "planCalendarVisibility",
+    sourcePath: "packages/json-document-calendar-document/src/calendar-operation.ts",
+  },
   {
     packageName: "@interactive-os/json-document-editing",
     symbol: "createCalendarEditor",
     sourcePath: "packages/json-document-editing/src/calendar.ts",
   },
   {
-    packageName: "@interactive-os/json-document-editing",
-    symbol: "createCalendarEditor",
-    sourcePath: "packages/json-document-editing/src/calendar-event-plan.ts",
+    packageName: "@interactive-os/json-document-calendar-document",
+    symbol: "planCalendarEventEdit",
+    sourcePath: "packages/json-document-calendar-document/src/calendar-operation.ts",
   },
   {
     packageName: "@interactive-os/json-document-editing",
@@ -410,19 +445,19 @@ const registeredPublicUsages = [
     sourcePath: "packages/json-document-editing/src/calendar.ts",
   },
   {
-    packageName: "@interactive-os/json-document-editing",
+    packageName: "@interactive-os/json-document-calendar-document",
     symbol: "calendarMonthDayLayout",
-    sourcePath: "packages/json-document-editing/src/calendar.ts",
+    sourcePath: "packages/json-document-calendar-document/src/calendar-projection.ts",
   },
   {
-    packageName: "@interactive-os/json-document-editing",
+    packageName: "@interactive-os/json-document-calendar-document",
     symbol: "calendarMonthWeekLayout",
-    sourcePath: "packages/json-document-editing/src/calendar.ts",
+    sourcePath: "packages/json-document-calendar-document/src/calendar-projection.ts",
   },
   {
-    packageName: "@interactive-os/json-document-editing",
+    packageName: "@interactive-os/json-document-calendar-document",
     symbol: "calendarBusyDates",
-    sourcePath: "packages/json-document-editing/src/calendar.ts",
+    sourcePath: "packages/json-document-calendar-document/src/calendar-projection.ts",
   },
   {
     packageName: "@interactive-os/json-document-editing",
@@ -440,24 +475,24 @@ const registeredPublicUsages = [
     sourcePath: "packages/json-document-editing/src/calendar-time-grid-pointer.ts",
   },
   {
-    packageName: "@interactive-os/json-document-editing",
+    packageName: "@interactive-os/json-document-calendar-document",
     symbol: "projectCalendarOccurrences",
-    sourcePath: "packages/json-document-editing/src/calendar-occurrence.ts",
+    sourcePath: "packages/json-document-calendar-document/src/calendar-occurrence.ts",
   },
   {
-    packageName: "@interactive-os/json-document-editing",
+    packageName: "@interactive-os/json-document-calendar-document",
     symbol: "calendarRecurrenceWithFrequency",
-    sourcePath: "packages/json-document-editing/src/calendar-occurrence.ts",
+    sourcePath: "packages/json-document-calendar-document/src/calendar-occurrence.ts",
   },
   {
-    packageName: "@interactive-os/json-document-editing",
+    packageName: "@interactive-os/json-document-calendar-document",
     symbol: "calendarRecurrenceWithInterval",
-    sourcePath: "packages/json-document-editing/src/calendar-occurrence.ts",
+    sourcePath: "packages/json-document-calendar-document/src/calendar-occurrence.ts",
   },
   {
-    packageName: "@interactive-os/json-document-editing",
+    packageName: "@interactive-os/json-document-calendar-document",
     symbol: "calendarRecurrenceWithUntil",
-    sourcePath: "packages/json-document-editing/src/calendar-occurrence.ts",
+    sourcePath: "packages/json-document-calendar-document/src/calendar-occurrence.ts",
   },
   {
     packageName: "@interactive-os/json-document-editing",
@@ -485,39 +520,39 @@ const registeredPublicUsages = [
     sourcePath: "packages/json-document-editing/src/calendar-selection.ts",
   },
   {
-    packageName: "@interactive-os/json-document-editing",
+    packageName: "@interactive-os/json-document-calendar-document",
     symbol: "calendarAllDaySpan",
-    sourcePath: "packages/json-document-editing/src/calendar-validation.ts",
+    sourcePath: "packages/json-document-calendar-document/src/calendar-validation.ts",
   },
   {
-    packageName: "@interactive-os/json-document-editing",
+    packageName: "@interactive-os/json-document-calendar-document",
     symbol: "calendarDocumentCalendars",
-    sourcePath: "packages/json-document-editing/src/calendar-validation.ts",
+    sourcePath: "packages/json-document-calendar-document/src/calendar-validation.ts",
   },
   {
-    packageName: "@interactive-os/json-document-editing",
+    packageName: "@interactive-os/json-document-calendar-document",
     symbol: "calendarDocumentCalendar",
-    sourcePath: "packages/json-document-editing/src/calendar-validation.ts",
+    sourcePath: "packages/json-document-calendar-document/src/calendar-validation.ts",
   },
   {
-    packageName: "@interactive-os/json-document-editing",
+    packageName: "@interactive-os/json-document-calendar-document",
     symbol: "calendarDatePart",
-    sourcePath: "packages/json-document-editing/src/calendar-validation.ts",
+    sourcePath: "packages/json-document-calendar-document/src/calendar-validation.ts",
   },
   {
-    packageName: "@interactive-os/json-document-editing",
+    packageName: "@interactive-os/json-document-calendar-document",
     symbol: "calendarIntervalLastDate",
-    sourcePath: "packages/json-document-editing/src/calendar-validation.ts",
+    sourcePath: "packages/json-document-calendar-document/src/calendar-validation.ts",
   },
   {
     packageName: "@interactive-os/json-document-editing",
     symbol: "parseCalendarView",
-    sourcePath: "packages/json-document-editing/src/calendar-validation.ts",
+    sourcePath: "packages/json-document-editing/src/calendar.ts",
   },
   {
-    packageName: "@interactive-os/json-document-editing",
+    packageName: "@interactive-os/json-document-calendar-document",
     symbol: "formatCalendarInstant",
-    sourcePath: "packages/json-document-editing/src/calendar-validation.ts",
+    sourcePath: "packages/json-document-calendar-document/src/calendar-validation.ts",
   },
   {
     packageName: "@interactive-os/json-document-web",
diff --git a/site/tests/browser/site-shell.spec.ts b/site/tests/browser/site-shell.spec.ts
index 4589ea09..34e1ab47 100644
--- a/site/tests/browser/site-shell.spec.ts
+++ b/site/tests/browser/site-shell.spec.ts
@@ -126,29 +126,33 @@ test("Document Types publishes a TBD responsibility boundary", async ({ page })
   await expect(page).toHaveTitle("Document Types · TBD - json-document");
   await expect(page.getByRole("heading", { level: 1, name: "Document Types · TBD" })).toBeVisible();
   await expect(page.getByRole("heading", { level: 2, name: "책임", exact: true })).toBeVisible();
-  await expect(page.getByRole("heading", { level: 2, name: "후보 · TBD" })).toBeVisible();
+  await expect(page.getByRole("heading", { level: 2, name: "현재 소유자와 후보" })).toBeVisible();
   await expect(page.getByRole("navigation", { name: "Breadcrumb" }).getByRole("link", { name: "Foundation" })).toHaveAttribute("href", "/docs/foundation");
   await expect(page.getByRole("navigation", { name: "Breadcrumb" }).getByText("Overview · TBD")).toBeVisible();
 });
 
-test("Document Type candidate submenu keeps ownership explicitly TBD", async ({ page }) => {
+test("Calendar Document Type exposes its RC owner while unrelated candidates remain TBD", async ({ page }) => {
   await page.goto("/docs/document-types/calendar");
 
-  await expect(page).toHaveTitle("Calendar Document Type · TBD - json-document");
-  await expect(page.getByRole("heading", { level: 1, name: "Calendar Document Type · TBD" })).toBeVisible();
-  await expect(page.getByRole("heading", { level: 2, name: "확정에 필요한 증거" })).toBeVisible();
+  await expect(page).toHaveTitle("Calendar Document Type · RC - json-document");
+  await expect(page.getByRole("heading", { level: 1, name: "Calendar Document Type · RC" })).toBeVisible();
+  await expect(page.getByRole("heading", { level: 2, name: "확정 증거와 남은 범위" })).toBeVisible();
   await expect(page.getByRole("heading", { level: 2, name: "소스 기반 감사 현황" })).toBeVisible();
   await expect(page.getByRole("heading", { level: 2, name: "왜 필요한가" })).toBeVisible();
   await expect(page.getByRole("heading", { level: 2, name: "무엇을 하는가" })).toBeVisible();
-  await expect(page.getByRole("heading", { level: 2, name: "현재 관찰된 schema · TBD" })).toBeVisible();
+  await expect(page.getByRole("heading", { level: 2, name: "현재 RC 모델" })).toBeVisible();
   await expect(page.getByRole("heading", { level: 3, name: "필드 설명" })).toBeVisible();
   await expect(page.getByRole("cell", { name: "start / end / allDay", exact: true })).toBeVisible();
-  await expect(page.getByRole("navigation", { name: "On this page" }).getByRole("link", { name: "현재 관찰된 schema · TBD" })).toBeVisible();
+  await expect(page.getByRole("navigation", { name: "On this page" }).getByRole("link", { name: "현재 RC 모델" })).toBeVisible();
   await expect.poll(async () => page.evaluate(() => document.documentElement.scrollWidth <= document.documentElement.clientWidth)).toBe(true);
-  await expect(page.getByText("packages/json-document-editing/src/calendar.ts", { exact: true })).toBeVisible();
-  await expect(page.getByText("10개 책임 occurrence", { exact: false })).toBeVisible();
-  await expect(page.getByRole("cell", { name: "mislocated module", exact: true }).first()).toBeVisible();
-  await expect(page.getByRole("navigation", { name: "Site navigation" }).getByRole("link", { name: "Calendar · TBD" })).toHaveAttribute("aria-current", "page");
+  await expect(page.getByText("packages/json-document-calendar-document/src/calendar-model.ts", { exact: true })).toBeVisible();
+  await expect(page.getByText("12개 책임 occurrence", { exact: false })).toBeVisible();
+  await expect(page.getByRole("cell", { name: "mislocated module", exact: true })).toHaveCount(0);
+  await expect(page.getByRole("navigation", { name: "Site navigation" }).getByRole("link", { name: "Calendar · RC" })).toHaveAttribute("aria-current", "page");
+  await page.getByRole("link", { name: "소유자 API 계약", exact: true }).click();
+  await expect(page.getByRole("heading", { name: "Calendar Document Type 계약 · RC", exact: true })).toBeVisible();
+  await page.goto("/docs/document-types/sheet");
+  await expect(page.getByRole("heading", { level: 1, name: "Sheet Document Type · TBD" })).toBeVisible();
 });
 
 test("official docs routes render with route metadata in a real browser", async ({ page }) => {
diff --git a/site/tests/unit/app-shell.test.tsx b/site/tests/unit/app-shell.test.tsx
index 3e3debf7..e1e1c913 100644
--- a/site/tests/unit/app-shell.test.tsx
+++ b/site/tests/unit/app-shell.test.tsx
@@ -115,18 +115,27 @@ describe("official site shell", () => {
     )).toBeTruthy();
   }, 10000);
 
-  test("exposes the Document Types TBD boundary", async () => {
+  test("exposes the Calendar owner without closing the other Document Types TBD boundary", async () => {
     resetDocument("/docs/document-types");
     render(<App />);
 
     expect(await screen.findByRole("heading", { level: 1, name: "Document Types · TBD" })).toBeTruthy();
     expect(screen.getByRole("heading", { level: 2, name: "책임" })).toBeTruthy();
-    expect(screen.getByText(/기존 package와 Hands의 실제 소유권 재배치는 아직 결정하지 않습니다/)).toBeTruthy();
+    expect(screen.getByText(/Calendar는 공개 소유자와 소비 경계를 확정했고/)).toBeTruthy();
+    expect(screen.getByRole("heading", { level: 2, name: "현재 소유자와 후보" })).toBeTruthy();
     const breadcrumb = within(screen.getByRole("navigation", { name: "Breadcrumb" }));
     expect(breadcrumb.getByRole("link", { name: "Foundation" }).getAttribute("href")).toBe("/docs/foundation");
     expect(breadcrumb.getByText("Overview · TBD")).toBeTruthy();
   });
 
+  test("renders the Calendar owner API reference and package-owned contract", async () => {
+    resetDocument("/docs/api/calendar-document");
+    render(<App />);
+    expect(await screen.findByRole("heading", { level: 1, name: "API · Calendar Document" })).toBeTruthy();
+    expect(screen.getByRole("heading", { name: "Calendar Document Type 계약 · RC" })).toBeTruthy();
+    expect(screen.getAllByRole("link", { name: "validateCalendarDocument", exact: true }).length).toBeGreaterThan(0);
+  });
+
   test("keeps the site chrome mounted across interior routes", async () => {
     render(<App />);
     const user = userEvent.setup();
diff --git a/site/tests/unit/demo-workbench.test.tsx b/site/tests/unit/demo-workbench.test.tsx
index 5f10bc4b..7f7f12e1 100644
--- a/site/tests/unit/demo-workbench.test.tsx
+++ b/site/tests/unit/demo-workbench.test.tsx
@@ -57,9 +57,12 @@ describe("DemoWorkbench", () => {
 describe("Demo definition and source discovery", () => {
   test("Calendar Usage exposes the shared edit plan and each canonical owner's API", async () => {
     const sources = await discoverDemoSources("routes/calendar-demo/CalendarDemoRoute.tsx");
-    const plan = sources.find((file) => file.path === "packages/json-document-editing/src/calendar-event-plan.ts");
-    expect(plan?.referencePath).toBe("/docs/api/editing");
+    const plan = sources.find((file) => file.path === "packages/json-document-calendar-document/src/calendar-operation.ts");
+    expect(plan?.referencePath).toBe("/docs/api/calendar-document");
     expect(await plan!.load()).toContain("export function planCalendarEventEdit");
+    const validation = sources.find((file) => file.path === "packages/json-document-calendar-document/src/calendar-validation.ts");
+    expect(validation?.referencePath).toBe("/docs/api/calendar-document");
+    expect(await validation!.load()).toContain("export function validateCalendarDocument");
     const hand = sources.find((file) => file.path === "packages/json-document-calendar/src/use-calendar-hand.ts");
     expect(hand?.referencePath).toBe("/docs/api/calendar");
     expect(await hand!.load()).toContain("export function useCalendarHand");
diff --git a/standards/editing-grammar.md b/standards/editing-grammar.md
index 1cdc03b3..2e569e4e 100644
--- a/standards/editing-grammar.md
+++ b/standards/editing-grammar.md
@@ -208,6 +208,13 @@ Object identity, 내부 cache, snapshot 객체의 정확한 key 집합은 적합
 
 ### 실행 가능한 대표 증거
 
+Calendar는 [materialized occurrence binding](../packages/json-document-editing/tests/conformance/calendar-grammar.test.ts)을
+같은 공용 runner에 연결한다. 반복 회차 범위 선택·copy/cut·primary 회차 기본 paste·
+거절·외부 삭제·local Undo/Redo를 검사한다. 아래 기존 세 editor의 대표 표와 함께
+읽으며, Calendar의 문서 규칙은 독립 Document Type 공개 API를 소비한다.
+Hand와 직접 호출의 선택 대상 일치는 [Calendar 경로 회귀](../packages/json-document-calendar/tests/calendar-protocol.test.tsx)로
+검증한다. 이는 Calendar profile의 Stable 또는 독립 구현 간 conformance 선언이 아니다.
+
 [Editing의 공용 runner](../packages/json-document-editing/tests/conformance/editing-grammar.ts)는
 각 editor의 공개 entrypoint만 호출한다. [Document·Sheet binding](../packages/json-document-editing/tests/conformance/editing-grammar.test.ts)과
 [Rich Text binding](../packages/json-document-rich-text/tests/conformance/editing-grammar.test.ts)은
diff --git a/standards/repository-implementation-shape.md b/standards/repository-implementation-shape.md
index 56f51df7..e84f48b6 100644
--- a/standards/repository-implementation-shape.md
+++ b/standards/repository-implementation-shape.md
@@ -216,7 +216,7 @@ Core는 [v3 profile](json-document-v3/profile.md), Editing의 상태·관찰·
 
 ## 현재 package 분류
 
-아래 표는 현재 30개 library package를 이 문서의 모형으로 빠짐없이 분류한다.
+아래 표는 현재 31개 library package를 이 문서의 모형으로 빠짐없이 분류한다.
 `후속`은 이 RFC가 source를 이동하지 않고 별도 이슈가 책임짐을 뜻한다.
 
 | Package path | 정본 모형 | 현재 판단 |
@@ -238,6 +238,7 @@ Core는 [v3 profile](json-document-v3/profile.md), Editing의 상태·관찰·
 | `packages/json-document-database` | Product-facing Hand | 기본 admin UI와 customization contract를 소유하고 headless domain package를 내부 구현으로 조합 |
 | `packages/json-document-annotation` | Product-facing Hand | Annotation 도구, gesture-to-Intent, SVG projection, transient preview와 comment UI를 소유 |
 | `packages/json-document-calendar` | Product-facing Hand | Calendar editor 관찰, occurrence focus, naming, Web pointer interaction lifecycle을 정본 hook으로 유지 |
+| `packages/json-document-calendar-document` | Document Type | Calendar model·validation·operation·projection의 공개 소유자. Editing·Selection·React peer 없이 독립 소비하며 기존 Editing export는 호환 경로 유지 |
 | `packages/json-document-tanstack-table` | Single-native Connector | 하나의 Table/Sheet binding으로 flat 유지 |
 | `packages/json-document-web` | Adapter family | keyboard/clipboard/input/modifier 책임 file과 root facade 유지 |
 | `packages/json-document-contenteditable` | Composite Adapter | React entry, binding, DOM adapter 책임 분리 유지 |
diff --git a/tsconfig.build.json b/tsconfig.build.json
index e0c09979..ddf971dd 100644
--- a/tsconfig.build.json
+++ b/tsconfig.build.json
@@ -4,6 +4,7 @@
   "references": [
     { "path": "./packages/json-document" },
     { "path": "./packages/json-document-selection" },
+    { "path": "./packages/json-document-calendar-document" },
     { "path": "./packages/json-document-editing" },
     { "path": "./packages/json-document-react" },
     { "path": "./packages/json-document-react-hook-form" },

From babdaea665013db2f351dc5c44b35865996d7717 Mon Sep 17 00:00:00 2001
From: "teo.v" <66650330+developer-1px@users.noreply.github.com>
Date: Wed, 9 Sep 2026 17:15:05 +0900
Subject: [PATCH 10/20] =?UTF-8?q?feat(canvas):=20Object=20=EC=A0=95?=
 =?UTF-8?q?=EB=B3=B8=20=EC=88=98=EC=A7=81=20=EC=8A=AC=EB=9D=BC=EC=9D=B4?=
 =?UTF-8?q?=EC=8A=A4=EC=99=80=20=EA=B3=B5=ED=86=B5=20=EC=95=84=EC=9D=B4?=
 =?UTF-8?q?=EC=BD=98=20=ED=88=B4=EB=B0=94=EB=A5=BC=20=EA=B5=AC=ED=98=84?=
 =?UTF-8?q?=ED=95=9C=EB=8B=A4=20(#748)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

한 장의 Canvas를 Object Document Type, 기존 Editing, Canvas Hand로 구성하고 두 Host를 정본 소비로 통일한다. 공통 아이콘·툴팁 툴바와 문서·Usage·Source 등록 및 회귀 검증을 포함한다. Closes #747.
---
 audits/document-types.json                    | 262 +++++-
 docs/api-reference/canvas.md                  |  44 +
 docs/api-reference/editing.md                 |  11 +-
 docs/api-reference/object-document.md         | 150 ++++
 docs/api-reference/packages.mjs               |   2 +
 docs/api-reference/ui-primitives-react.md     |   2 +-
 docs/public/affordance-drag.md                |   7 +-
 docs/public/document-types.md                 |  13 +-
 docs/public/object.md                         |  21 +-
 docs/public/ui-primitives.md                  |   8 +-
 package-lock.json                             |  61 ++
 package.json                                  |   2 +
 packages/json-document-canvas/LICENSE         |  21 +
 packages/json-document-canvas/README.md       |  20 +
 packages/json-document-canvas/docs/api.md     |  63 ++
 packages/json-document-canvas/package.json    |  33 +
 .../json-document-canvas/src/canvas-hand.tsx  |  60 ++
 .../src/canvas-object-view.tsx                |  77 ++
 packages/json-document-canvas/src/index.ts    |   2 +
 .../src/use-canvas-hand.ts                    | 222 +++++
 .../tests/canvas-hand.test.tsx                | 155 ++++
 packages/json-document-canvas/tsconfig.json   |  10 +
 .../json-document-canvas/tsconfig.test.json   |   5 +
 .../json-document-canvas/vitest.config.ts     |   7 +
 packages/json-document-editing/package.json   |   2 +
 .../src/object-validation.ts                  |  12 -
 packages/json-document-editing/src/object.ts  | 136 +--
 .../tests/canvas-profile.test.ts              |  71 ++
 packages/json-document-editing/tsconfig.json  |   1 +
 .../json-document-object-document/LICENSE     |  21 +
 .../json-document-object-document/README.md   |  24 +
 .../json-document-object-document/docs/api.md |  64 ++
 .../package.json                              |  23 +
 .../src/index.ts                              |   4 +
 .../src/object-model.ts                       |  45 +
 .../src/object-operation.ts                   |  58 ++
 .../src/object-projection.ts                  |  54 ++
 .../src/object-validation.ts                  |  63 ++
 .../tests/object-document.test.ts             |  63 ++
 .../tsconfig.json                             |   6 +
 .../tsconfig.test.json                        |   5 +
 .../vitest.config.ts                          |   3 +
 .../src/controls.tsx                          |   4 +-
 .../src/surfaces.tsx                          |   8 +-
 .../tests/primitives.test.tsx                 |  16 +
 site/config/json-document-source-aliases.ts   |   2 +
 site/package.json                             |   2 +
 .../check-content-interaction-grammar.mjs     |   4 +-
 site/scripts/check-design-tokens.mjs          |   2 +
 site/scripts/check-interaction-handles.mjs    |   2 +-
 site/scripts/check-product-shell-toolbar.mjs  |   5 +-
 site/site-routes.json                         |  50 +-
 site/src/app/index.css                        |   8 +-
 site/src/app/routeTree.gen.ts                 |  43 +
 site/src/app/routes/_page/docs/api/canvas.tsx |   6 +
 .../routes/_page/docs/api/object-document.tsx |   6 +
 .../routes/canvas-demo/CanvasDemoRoute.tsx    | 843 +-----------------
 site/src/routes/docs/DocsRoute.tsx            |   2 +
 .../docs/DocumentTypeCandidateRoute.tsx       |   8 +-
 site/src/routes/docs/doc-pages.ts             |   6 +
 site/src/routes/widgets/CanvasWidgetRoute.tsx | 405 +--------
 .../demo-workbench/canvas-demo-document.ts    |  16 +
 .../src/shared/demo-workbench/demo-sources.ts |  51 ++
 .../demo-workbench/object-demo-document.ts    |   9 +-
 site/src/shared/ui/styles.ts                  |   1 +
 site/tests/browser/canvas-slice.spec.ts       |  91 ++
 site/tests/browser/editor-slice-demos.spec.ts | 248 ------
 site/tests/browser/widgets.spec.ts            |  33 +-
 site/tests/unit/app-shell.test.tsx            |   4 +-
 site/tests/unit/demo-workbench.test.tsx       |  28 +-
 site/tsconfig.json                            |   2 +
 standards/repository-implementation-shape.md  |   2 +
 tsconfig.build.json                           |   2 +
 73 files changed, 2134 insertions(+), 1688 deletions(-)
 create mode 100644 docs/api-reference/canvas.md
 create mode 100644 docs/api-reference/object-document.md
 create mode 100644 packages/json-document-canvas/LICENSE
 create mode 100644 packages/json-document-canvas/README.md
 create mode 100644 packages/json-document-canvas/docs/api.md
 create mode 100644 packages/json-document-canvas/package.json
 create mode 100644 packages/json-document-canvas/src/canvas-hand.tsx
 create mode 100644 packages/json-document-canvas/src/canvas-object-view.tsx
 create mode 100644 packages/json-document-canvas/src/index.ts
 create mode 100644 packages/json-document-canvas/src/use-canvas-hand.ts
 create mode 100644 packages/json-document-canvas/tests/canvas-hand.test.tsx
 create mode 100644 packages/json-document-canvas/tsconfig.json
 create mode 100644 packages/json-document-canvas/tsconfig.test.json
 create mode 100644 packages/json-document-canvas/vitest.config.ts
 delete mode 100644 packages/json-document-editing/src/object-validation.ts
 create mode 100644 packages/json-document-editing/tests/canvas-profile.test.ts
 create mode 100644 packages/json-document-object-document/LICENSE
 create mode 100644 packages/json-document-object-document/README.md
 create mode 100644 packages/json-document-object-document/docs/api.md
 create mode 100644 packages/json-document-object-document/package.json
 create mode 100644 packages/json-document-object-document/src/index.ts
 create mode 100644 packages/json-document-object-document/src/object-model.ts
 create mode 100644 packages/json-document-object-document/src/object-operation.ts
 create mode 100644 packages/json-document-object-document/src/object-projection.ts
 create mode 100644 packages/json-document-object-document/src/object-validation.ts
 create mode 100644 packages/json-document-object-document/tests/object-document.test.ts
 create mode 100644 packages/json-document-object-document/tsconfig.json
 create mode 100644 packages/json-document-object-document/tsconfig.test.json
 create mode 100644 packages/json-document-object-document/vitest.config.ts
 create mode 100644 site/src/app/routes/_page/docs/api/canvas.tsx
 create mode 100644 site/src/app/routes/_page/docs/api/object-document.tsx
 create mode 100644 site/src/shared/demo-workbench/canvas-demo-document.ts
 create mode 100644 site/tests/browser/canvas-slice.spec.ts

diff --git a/audits/document-types.json b/audits/document-types.json
index 1020e90f..1e2be6da 100644
--- a/audits/document-types.json
+++ b/audits/document-types.json
@@ -33,7 +33,7 @@
     "object": {
       "why": "캔버스 object는 identity, geometry와 presentation 값을 하나의 의미 단위로 유지해야 하기 때문입니다.",
       "does": "object의 위치·크기·색상 모델을 정의하고 translate·resize·fill 같은 공간 연산의 기반을 제공합니다.",
-      "schema": "interface DocumentObject {\n  readonly id: string;\n  readonly label: string;\n  readonly x: number;\n  readonly y: number;\n  readonly width: number;\n  readonly height: number;\n  readonly color: string;\n}\n\ninterface ObjectDocument {\n  readonly objects: ReadonlyArray<DocumentObject>;\n}",
+      "schema": "interface DocumentObject {\n  readonly id: string;\n  readonly label: string;\n  readonly x: number;\n  readonly y: number;\n  readonly width: number;\n  readonly height: number;\n  readonly color: string;\n}\n\ninterface ObjectDocument {\n  readonly objects: ReadonlyArray<DocumentObject>;\n}\n\ntype CanvasObject = DocumentObject & (\n  | { kind: \"text\"; fontSize: number }\n  | { kind: \"rectangle\" | \"ellipse\" }\n  | { kind: \"path\"; points: ReadonlyArray<{ x: number; y: number }>; strokeWidth: number }\n);\ninterface CanvasDocument extends ObjectDocument {\n  readonly profile: \"canvas/1\";\n  readonly width: number; readonly height: number;\n  readonly objects: ReadonlyArray<CanvasObject>;\n}",
       "fields": [
         { "name": "objects", "description": "같은 공간에서 배치·선택되는 object의 ordered collection입니다." },
         { "name": "objects[].id", "description": "selection, transform과 clipboard가 object를 안정적으로 참조하는 identity입니다." },
@@ -42,7 +42,7 @@
         { "name": "width / height", "description": "resize 이후에도 유효해야 하는 object의 공간 크기입니다." },
         { "name": "color", "description": "object가 소유하는 현재 presentation 값입니다." }
       ],
-      "sourcePath": "packages/json-document-editing/src/object.ts",
+      "sourcePath": "packages/json-document-object-document/src/object-model.ts",
       "symbol": "ObjectDocument"
     },
     "tree": {
@@ -134,6 +134,264 @@
     }
   },
   "audits": {
+    "object": {
+      "status": "owner-closed",
+      "denominator": 14,
+      "horizon": {
+        "enumerators": [
+          "packages/json-document-object-document/src/index.ts",
+          "packages/json-document-editing/src/object.ts",
+          "packages/json-document-canvas/src/index.ts",
+          "site/src/app/live-demo-registry.tsx",
+          "site/src/shared/demo-workbench/demo-sources.ts"
+        ],
+        "exclusions": [
+          "Calendar와 Annotation의 독립 문서 의미",
+          "fixture·copy·layout-only CSS·tests·generated route"
+        ]
+      },
+      "occurrences": [
+        {
+          "id": "model",
+          "role": "Document Model",
+          "knowledge": "ID·순서·한 장·variant 문서 어휘",
+          "decision": "기존 Object와 Canvas가 같은 Object 모델을 공유",
+          "changeReason": "프로파일의 값·variant 변경",
+          "stateLifecycle": "문서 값 또는 stateless 계산",
+          "inputsOutputs": "CanvasDocument의 public 계약",
+          "currentOwner": "@interactive-os/json-document-object-document",
+          "canonicalEvidence": "packages/json-document-object-document/src/object-model.ts와 공개 entrypoint·package API 문서·Canvas Usage/Source",
+          "sourcePath": "packages/json-document-object-document/src/object-model.ts",
+          "symbol": "CanvasDocument",
+          "disposition": "canonical consumer",
+          "intendedOwner": "@interactive-os/json-document-object-document",
+          "nextCheck": "회귀 테스트와 실제 Canvas Usage/Source로 검증"
+        },
+        {
+          "id": "validation",
+          "role": "Validation",
+          "knowledge": "JSON·ID·유한 기하·정규화 path",
+          "decision": "잘못된 문서 전체를 거절",
+          "changeReason": "유효성·직렬화 계약 변경",
+          "stateLifecycle": "문서 값 또는 stateless 계산",
+          "inputsOutputs": "assertCanvasDocument의 public 계약",
+          "currentOwner": "@interactive-os/json-document-object-document",
+          "canonicalEvidence": "packages/json-document-object-document/src/object-validation.ts와 공개 entrypoint·package API 문서·Canvas Usage/Source",
+          "sourcePath": "packages/json-document-object-document/src/object-validation.ts",
+          "symbol": "assertCanvasDocument",
+          "disposition": "canonical consumer",
+          "intendedOwner": "@interactive-os/json-document-object-document",
+          "nextCheck": "회귀 테스트와 실제 Canvas Usage/Source로 검증"
+        },
+        {
+          "id": "operation",
+          "role": "Document Operation",
+          "knowledge": "Object 의미 연산과 JSON Patch",
+          "decision": "대상·결과 검증 후 atomic 계획",
+          "changeReason": "문서 변형 의미 변경",
+          "stateLifecycle": "문서 값 또는 stateless 계산",
+          "inputsOutputs": "planObjectOperation의 public 계약",
+          "currentOwner": "@interactive-os/json-document-object-document",
+          "canonicalEvidence": "packages/json-document-object-document/src/object-operation.ts와 공개 entrypoint·package API 문서·Canvas Usage/Source",
+          "sourcePath": "packages/json-document-object-document/src/object-operation.ts",
+          "symbol": "planObjectOperation",
+          "disposition": "canonical consumer",
+          "intendedOwner": "@interactive-os/json-document-object-document",
+          "nextCheck": "회귀 테스트와 실제 Canvas Usage/Source로 검증"
+        },
+        {
+          "id": "projection",
+          "role": "Projection",
+          "knowledge": "Object bounds·path 정규화",
+          "decision": "preview와 commit의 동일한 기하",
+          "changeReason": "기하 표현 변경",
+          "stateLifecycle": "문서 값 또는 stateless 계산",
+          "inputsOutputs": "transformObject의 public 계약",
+          "currentOwner": "@interactive-os/json-document-object-document",
+          "canonicalEvidence": "packages/json-document-object-document/src/object-projection.ts와 공개 entrypoint·package API 문서·Canvas Usage/Source",
+          "sourcePath": "packages/json-document-object-document/src/object-projection.ts",
+          "symbol": "transformObject",
+          "disposition": "canonical consumer",
+          "intendedOwner": "@interactive-os/json-document-object-document",
+          "nextCheck": "회귀 테스트와 실제 Canvas Usage/Source로 검증"
+        },
+        {
+          "id": "editing",
+          "role": "Editing lifecycle",
+          "knowledge": "Object Intent와 post-selection",
+          "decision": "ID 생성·명령 실행·선택 publication",
+          "changeReason": "편집 문법 변경",
+          "stateLifecycle": "소유자 API의 session/component lifecycle",
+          "inputsOutputs": "createObjectEditor의 public 계약",
+          "currentOwner": "@interactive-os/json-document-editing",
+          "canonicalEvidence": "packages/json-document-editing/src/object.ts와 공개 entrypoint·package API 문서·Canvas Usage/Source",
+          "sourcePath": "packages/json-document-editing/src/object.ts",
+          "symbol": "createObjectEditor",
+          "disposition": "canonical consumer",
+          "intendedOwner": "@interactive-os/json-document-editing",
+          "nextCheck": "회귀 테스트와 실제 Canvas Usage/Source로 검증"
+        },
+        {
+          "id": "selection",
+          "role": "Selection",
+          "knowledge": "안정된 key 집합",
+          "decision": "키 선택 transition과 reconciliation",
+          "changeReason": "Selection family 규칙 변경",
+          "stateLifecycle": "소유자 API의 session/component lifecycle",
+          "inputsOutputs": "createKeySelectionFamily의 public 계약",
+          "currentOwner": "@interactive-os/json-document-selection",
+          "canonicalEvidence": "packages/json-document-selection/src/key/index.ts와 공개 entrypoint·package API 문서·Canvas Usage/Source",
+          "sourcePath": "packages/json-document-selection/src/key/index.ts",
+          "symbol": "createKeySelectionFamily",
+          "disposition": "canonical consumer",
+          "intendedOwner": "@interactive-os/json-document-selection",
+          "nextCheck": "회귀 테스트와 실제 Canvas Usage/Source로 검증"
+        },
+        {
+          "id": "history",
+          "role": "History",
+          "knowledge": "commit·inverse·selection",
+          "decision": "한 transaction의 undo/redo와 외부 변경 무효화",
+          "changeReason": "History lifecycle 변경",
+          "stateLifecycle": "소유자 API의 session/component lifecycle",
+          "inputsOutputs": "createEditingSession의 public 계약",
+          "currentOwner": "@interactive-os/json-document-editing",
+          "canonicalEvidence": "packages/json-document-editing/src/session.ts와 공개 entrypoint·package API 문서·Canvas Usage/Source",
+          "sourcePath": "packages/json-document-editing/src/session.ts",
+          "symbol": "createEditingSession",
+          "disposition": "canonical consumer",
+          "intendedOwner": "@interactive-os/json-document-editing",
+          "nextCheck": "회귀 테스트와 실제 Canvas Usage/Source로 검증"
+        },
+        {
+          "id": "gesture",
+          "role": "Affordance",
+          "knowledge": "입력 독립 gesture lifecycle",
+          "decision": "begin/preview/commit/cancel",
+          "changeReason": "interaction 의미 변경",
+          "stateLifecycle": "소유자 API의 session/component lifecycle",
+          "inputsOutputs": "createGestureSession의 public 계약",
+          "currentOwner": "@interactive-os/json-document-affordance",
+          "canonicalEvidence": "packages/json-document-affordance/src/gesture-session.ts와 공개 entrypoint·package API 문서·Canvas Usage/Source",
+          "sourcePath": "packages/json-document-affordance/src/gesture-session.ts",
+          "symbol": "createGestureSession",
+          "disposition": "canonical consumer",
+          "intendedOwner": "@interactive-os/json-document-affordance",
+          "nextCheck": "회귀 테스트와 실제 Canvas Usage/Source로 검증"
+        },
+        {
+          "id": "adapter",
+          "role": "Web Adapter",
+          "knowledge": "Pointer Events·capture",
+          "decision": "pointer identity와 release/cancel",
+          "changeReason": "Web platform 입력 계약 변경",
+          "stateLifecycle": "소유자 API의 session/component lifecycle",
+          "inputsOutputs": "createWebPointerSession의 public 계약",
+          "currentOwner": "@interactive-os/json-document-web",
+          "canonicalEvidence": "packages/json-document-web/src/pointer-session.ts와 공개 entrypoint·package API 문서·Canvas Usage/Source",
+          "sourcePath": "packages/json-document-web/src/pointer-session.ts",
+          "symbol": "createWebPointerSession",
+          "disposition": "canonical consumer",
+          "intendedOwner": "@interactive-os/json-document-web",
+          "nextCheck": "회귀 테스트와 실제 Canvas Usage/Source로 검증"
+        },
+        {
+          "id": "ui",
+          "role": "Reusable UI behavior",
+          "knowledge": "Handle descriptor와 React/Web lifecycle",
+          "decision": "공통 capture continuation과 unmount 정리",
+          "changeReason": "handle UI 행동 변경",
+          "stateLifecycle": "소유자 API의 session/component lifecycle",
+          "inputsOutputs": "useInteractionHandle의 public 계약",
+          "currentOwner": "@interactive-os/json-document-ui-primitives-react",
+          "canonicalEvidence": "packages/json-document-ui-primitives-react/src/surfaces.tsx와 공개 entrypoint·package API 문서·Canvas Usage/Source",
+          "sourcePath": "packages/json-document-ui-primitives-react/src/surfaces.tsx",
+          "symbol": "useInteractionHandle",
+          "disposition": "canonical consumer",
+          "intendedOwner": "@interactive-os/json-document-ui-primitives-react",
+          "nextCheck": "회귀 테스트와 실제 Canvas Usage/Source로 검증"
+        },
+        {
+          "id": "hand",
+          "role": "Hand composition",
+          "knowledge": "Canvas 도구·Object Editing·Web·Affordance",
+          "decision": "transient preview와 text draft를 Intent에 연결",
+          "changeReason": "Canvas 입력 조합 변경",
+          "stateLifecycle": "소유자 API의 session/component lifecycle",
+          "inputsOutputs": "useCanvasHand의 public 계약",
+          "currentOwner": "@interactive-os/json-document-canvas",
+          "canonicalEvidence": "packages/json-document-canvas/src/use-canvas-hand.ts와 공개 entrypoint·package API 문서·Canvas Usage/Source",
+          "sourcePath": "packages/json-document-canvas/src/use-canvas-hand.ts",
+          "symbol": "useCanvasHand",
+          "disposition": "canonical consumer",
+          "intendedOwner": "@interactive-os/json-document-canvas",
+          "nextCheck": "회귀 테스트와 실제 Canvas Usage/Source로 검증"
+        },
+        {
+          "id": "demo",
+          "role": "Host composition",
+          "knowledge": "빈 fixture·제품 값·레이아웃",
+          "decision": "정본 CanvasHand 조합",
+          "changeReason": "제품 fixture와 화면 구성 변경",
+          "stateLifecycle": "소유자 API의 session/component lifecycle",
+          "inputsOutputs": "fixture·public API 입력 → 화면 조합",
+          "currentOwner": "Canvas Demo Host",
+          "canonicalEvidence": "site/src/routes/canvas-demo/CanvasDemoRoute.tsx와 공개 entrypoint·package API 문서·Canvas Usage/Source",
+          "sourcePath": "site/src/routes/canvas-demo/CanvasDemoRoute.tsx",
+          "symbol": "CanvasDemoRoute",
+          "disposition": "Host composition",
+          "intendedOwner": "Canvas Demo Host",
+          "nextCheck": "회귀 테스트와 실제 Canvas Usage/Source로 검증"
+        },
+        {
+          "id": "widget",
+          "role": "Host composition",
+          "knowledge": "샘플 fixture·관찰 UI",
+          "decision": "같은 CanvasHand와 Connector 조합",
+          "changeReason": "샘플과 관찰 화면 변경",
+          "stateLifecycle": "소유자 API의 session/component lifecycle",
+          "inputsOutputs": "fixture·public API 입력 → 화면 조합",
+          "currentOwner": "Canvas Widget Host",
+          "canonicalEvidence": "site/src/routes/widgets/CanvasWidgetRoute.tsx와 공개 entrypoint·package API 문서·Canvas Usage/Source",
+          "sourcePath": "site/src/routes/widgets/CanvasWidgetRoute.tsx",
+          "symbol": "CanvasWidgetRoute",
+          "disposition": "Host composition",
+          "intendedOwner": "Canvas Widget Host",
+          "nextCheck": "회귀 테스트와 실제 Canvas Usage/Source로 검증"
+        },
+        {
+          "id": "object-demo",
+          "role": "Host composition",
+          "knowledge": "기존 Object fixture·작업 조합",
+          "decision": "기존 ObjectEditor 및 Web clipboard 소비 유지",
+          "changeReason": "Object Demo 구성 변경",
+          "stateLifecycle": "소유자 API의 session/component lifecycle",
+          "inputsOutputs": "fixture·public API 입력 → 화면 조합",
+          "currentOwner": "Object Demo Host",
+          "canonicalEvidence": "site/src/routes/object-demo/ObjectDemoRoute.tsx와 공개 entrypoint·package API 문서·Canvas Usage/Source",
+          "sourcePath": "site/src/routes/object-demo/ObjectDemoRoute.tsx",
+          "symbol": "ObjectDemoRoute",
+          "disposition": "Host composition",
+          "intendedOwner": "Object Demo Host",
+          "nextCheck": "회귀 테스트와 실제 Canvas Usage/Source로 검증"
+        }
+      ],
+      "closure": {
+        "owner": "@interactive-os/json-document-object-document",
+        "publicEntry": "packages/json-document-object-document/src/index.ts",
+        "referencePath": "packages/json-document-object-document/docs/api.md",
+        "apiPath": "/docs/api/object-document",
+        "usagePath": "/demo/canvas",
+        "usagePagePath": "/docs/api/canvas",
+        "sourceRegistration": "site/src/shared/demo-workbench/demo-sources.ts",
+        "verification": [
+          "packages/json-document-object-document/tests/object-document.test.ts",
+          "packages/json-document-editing/tests/canvas-profile.test.ts",
+          "packages/json-document-canvas/tests/canvas-hand.test.tsx",
+          "site/tests/unit/demo-workbench.test.tsx"
+        ]
+      }
+    },
     "calendar": {
       "status": "owner-closed",
       "denominator": 12,
diff --git a/docs/api-reference/canvas.md b/docs/api-reference/canvas.md
new file mode 100644
index 00000000..99ee2a89
--- /dev/null
+++ b/docs/api-reference/canvas.md
@@ -0,0 +1,44 @@
+# @interactive-os/json-document-canvas API
+
+**Owner:** Hands
+
+한 장짜리 Canvas의 입력·preview·UI 조합의 public entrypoint입니다. 아래 항목은 package root에서 import할 수 있는 안정된 public API이며 internal 경로는 계약이 아닙니다.
+
+> 이 문서는 `packages/json-document-canvas/src/index.ts`에서 생성됩니다. API를 변경한 뒤 `npm run docs:api`를 실행하세요.
+
+## `CanvasCreationStyle`
+
+```ts
+interface CanvasCreationStyle {
+  readonly color: string;
+  readonly textColor: string;
+  readonly fontSize: number;
+  readonly strokeWidth: number;
+}
+```
+## `CanvasHand`
+
+```ts
+CanvasHand(props: CanvasHandProps): import("<repository>/node_modules/@types/react/jsx-runtime").JSX.Element
+```
+## `CanvasHandProps`
+
+```ts
+interface CanvasHandProps {
+  readonly editor: ObjectEditor;
+  readonly creationStyle: CanvasCreationStyle;
+  readonly className?: string;
+  readonly slideStyle?: CSSProperties;
+  readonly label?: string;
+}
+```
+## `CanvasTool`
+
+```ts
+type CanvasTool = "select" | CanvasObjectKind;
+```
+## `useCanvasHand`
+
+```ts
+useCanvasHand(editor: ObjectEditor, style: CanvasCreationStyle): { document: CanvasDocument; snapshot: import("<repository>/packages/json-document-editing/src/session").EditingSnapshot<ObjectSelection>; ... 16 more ...; surfaceProps: { ...; }; }
+```
diff --git a/docs/api-reference/editing.md b/docs/api-reference/editing.md
index e7b82e12..2e310a05 100644
--- a/docs/api-reference/editing.md
+++ b/docs/api-reference/editing.md
@@ -846,14 +846,8 @@ type DocumentIntent =
 ## `DocumentObject`
 
 ```ts
-interface DocumentObject extends Record<string, JSONValue> {
+interface DocumentObject extends ObjectDraft {
   readonly id: string;
-  readonly label: string;
-  readonly x: number;
-  readonly y: number;
-  readonly width: number;
-  readonly height: number;
-  readonly color: string;
 }
 ```
 ## `DocumentPoint`
@@ -1231,6 +1225,9 @@ interface ObjectEditor {
 
 ```ts
 type ObjectIntent =
+  | { readonly type: "object.create"; readonly object: ObjectDraft }
+  | { readonly type: "object.text"; readonly objectId: string; readonly text: string }
+  | { readonly type: "document.replace"; readonly document: ObjectDocument }
   | {
       readonly type: "selection.set";
       readonly objectIds: ReadonlyArray<string>;
diff --git a/docs/api-reference/object-document.md b/docs/api-reference/object-document.md
new file mode 100644
index 00000000..43ccda38
--- /dev/null
+++ b/docs/api-reference/object-document.md
@@ -0,0 +1,150 @@
+# @interactive-os/json-document-object-document API
+
+**Owner:** Document Types
+
+Object 문서와 Canvas 프로파일의 모델·검증·연산·projection의 public entrypoint입니다. 아래 항목은 package root에서 import할 수 있는 안정된 public API이며 internal 경로는 계약이 아닙니다.
+
+> 이 문서는 `packages/json-document-object-document/src/index.ts`에서 생성됩니다. API를 변경한 뒤 `npm run docs:api`를 실행하세요.
+
+## `assertCanvasDocument`
+
+```ts
+assertCanvasDocument(value: unknown): asserts value is CanvasDocument
+```
+## `assertObjectDocument`
+
+```ts
+assertObjectDocument(value: unknown): void
+```
+## `CanvasDocument`
+
+```ts
+interface CanvasDocument extends ObjectDocument {
+  readonly profile: "canvas/1";
+  readonly width: number;
+  readonly height: number;
+  readonly objects: ReadonlyArray<CanvasObject>;
+}
+```
+## `CanvasObject`
+
+```ts
+type CanvasObject = CanvasObjectDraft & { readonly id: string };
+```
+## `CanvasObjectDraft`
+
+```ts
+type CanvasObjectDraft = ObjectDraft & (
+  | { readonly kind: "text"; readonly fontSize: number }
+  | { readonly kind: "rectangle" | "ellipse" }
+  | { readonly kind: "path"; readonly points: ReadonlyArray<ObjectPoint>; readonly strokeWidth: number }
+);
+```
+## `CanvasObjectKind`
+
+```ts
+type CanvasObjectKind = "text" | "rectangle" | "ellipse" | "path";
+```
+## `createCanvasObject`
+
+```ts
+createCanvasObject(kind: Exclude<CanvasObjectKind, "path">, bounds: ObjectBounds, style: { readonly color: string; readonly label: string; readonly fontSize?: number; }): CanvasObjectDraft
+```
+## `createCanvasPath`
+
+```ts
+createCanvasPath(points: ReadonlyArray<ObjectPoint>, style: { readonly color: string; readonly label: string; readonly strokeWidth: number; }): Extract<CanvasObjectDraft, { readonly kind: "path"; }>
+```
+## `DocumentObject`
+
+```ts
+interface DocumentObject extends ObjectDraft {
+  readonly id: string;
+}
+```
+## `ObjectBounds`
+
+```ts
+interface ObjectBounds {
+  readonly x: number;
+  readonly y: number;
+  readonly width: number;
+  readonly height: number;
+}
+```
+## `ObjectDocument`
+
+```ts
+interface ObjectDocument extends Record<string, JSONValue> {
+  readonly objects: ReadonlyArray<DocumentObject>;
+}
+```
+## `ObjectDraft`
+
+```ts
+interface ObjectDraft extends ObjectBounds, Record<string, JSONValue> {
+  readonly label: string;
+  readonly color: string;
+}
+```
+## `ObjectOperation`
+
+```ts
+type ObjectOperation =
+  | { readonly type: "insert"; readonly objects: ReadonlyArray<DocumentObject> }
+  | { readonly type: "transform"; readonly objectIds: ReadonlyArray<string>; readonly transform: ObjectTransform }
+  | { readonly type: "fill"; readonly objectIds: ReadonlyArray<string>; readonly color: string }
+  | { readonly type: "remove"; readonly objectIds: ReadonlyArray<string> }
+  | { readonly type: "text"; readonly objectId: string; readonly text: string }
+  | { readonly type: "replace"; readonly document: ObjectDocument };
+```
+## `ObjectOperationPlan`
+
+```ts
+type ObjectOperationPlan =
+  | { readonly ok: true; readonly operations: ReadonlyArray<JSONPatchOperation> }
+  | { readonly ok: false; readonly code: string; readonly reason?: string };
+```
+## `ObjectPoint`
+
+```ts
+interface ObjectPoint extends Record<string, JSONValue> {
+  readonly x: number;
+  readonly y: number;
+}
+```
+## `ObjectTransform`
+
+```ts
+interface ObjectTransform {
+  readonly dx: number;
+  readonly dy: number;
+  readonly dw?: number;
+  readonly dh?: number;
+}
+```
+## `parseCanvasDocument`
+
+```ts
+parseCanvasDocument(json: string): CanvasDocument
+```
+## `planObjectOperation`
+
+```ts
+planObjectOperation(document: ObjectDocument, operation: ObjectOperation): ObjectOperationPlan
+```
+## `projectObject`
+
+```ts
+projectObject(object: DocumentObject): CanvasObject
+```
+## `serializeCanvasDocument`
+
+```ts
+serializeCanvasDocument(document: CanvasDocument): string
+```
+## `transformObject`
+
+```ts
+transformObject<Object extends DocumentObject>(object: Object, transform: ObjectTransform): Object
+```
diff --git a/docs/api-reference/packages.mjs b/docs/api-reference/packages.mjs
index 39165dd5..7cae3059 100644
--- a/docs/api-reference/packages.mjs
+++ b/docs/api-reference/packages.mjs
@@ -1,4 +1,6 @@
 export const apiReferencePackages = [
+  ["object-document", "@interactive-os/json-document-object-document", "packages/json-document-object-document/src/index.ts", "Document Types", "Object 문서와 Canvas 프로파일의 모델·검증·연산·projection"],
+  ["canvas", "@interactive-os/json-document-canvas", "packages/json-document-canvas/src/index.ts", "Hands", "한 장짜리 Canvas의 입력·preview·UI 조합"],
   ["calendar-document", "@interactive-os/json-document-calendar-document", "packages/json-document-calendar-document/src/index.ts", "Document Types", "Calendar 문서 모델·검증·의미 연산·projection 계약"],
   ["a2ui", "@interactive-os/json-document-a2ui", "packages/json-document-a2ui/src/index.ts", "Connector", "A2UI streaming document connector"],
   ["json-document", "@interactive-os/json-document", "packages/json-document/src/application/document/index.ts", "JSON Document", "Core document 값·주소·patch 계약"],
diff --git a/docs/api-reference/ui-primitives-react.md b/docs/api-reference/ui-primitives-react.md
index ceb8a738..d6897ed0 100644
--- a/docs/api-reference/ui-primitives-react.md
+++ b/docs/api-reference/ui-primitives-react.md
@@ -296,7 +296,7 @@ Tabs<T extends string | number>(props: { readonly label: string; readonly value:
 ## `Toggle`
 
 ```ts
-Toggle(props: Omit<ButtonHTMLAttributes<HTMLButtonElement>, "aria-pressed"> & FocusPreservingControl & ControlAffordanceProps & { readonly pressed: boolean; readonly presentation?: "button" | "chip"; readonly label?: string; readonly tooltip?: string; }): ReactNode
+Toggle(props: Omit<ButtonHTMLAttributes<HTMLButtonElement>, "aria-pressed"> & FocusPreservingControl & ControlAffordanceProps & { readonly pressed: boolean; readonly presentation?: "button" | "chip" | "icon"; readonly label?: string; readonly tooltip?: string; }): ReactNode
 ```
 ## `Toolbar`
 
diff --git a/docs/public/affordance-drag.md b/docs/public/affordance-drag.md
index 2d78e414..d4964eae 100644
--- a/docs/public/affordance-drag.md
+++ b/docs/public/affordance-drag.md
@@ -79,7 +79,8 @@ Canvas에 한정되지 않은 create/draw/move/resize lifecycle은
 `createGestureSession<Gesture>()`을 사용합니다. `GestureState`는 string `type`만
 요구하며 begin/preview/commit/cancel과 supersede 의미를 소유합니다.
 
-좌표 변환, hit test, 잠금 정책, renderer, tool/viewport 정책은 Host 책임입니다.
+좌표 변환은 Web Adapter, hit target·renderer·tool 조합은 Hand, 문서 기하는
+Document Type이 소유합니다. Host에는 권한·잠금 정책 값과 레이아웃만 남습니다.
 
 ## TBD
 
@@ -88,9 +89,7 @@ Canvas에 한정되지 않은 create/draw/move/resize lifecycle은
 
 ## Live Demo
 
-```live-demo
-/widgets/canvas
-```
+[Canvas Hand의 Usage 및 Source](/docs/api/canvas)에서 같은 drag 문법을 확인할 수 있습니다.
 
 ```live-demo
 /widgets/board
diff --git a/docs/public/document-types.md b/docs/public/document-types.md
index 0c91a8d7..dd49e105 100644
--- a/docs/public/document-types.md
+++ b/docs/public/document-types.md
@@ -2,7 +2,7 @@
 
 Document Type은 특정 JSON Document가 무엇을 의미하고 어떤 상태와 변경이
 유효한지를 정의하는 생태계 위치입니다. 이 페이지는 책임 이름과 경계만
-확정합니다. Calendar는 공개 소유자와 소비 경계를 확정했고, 나머지 후보의 실제
+확정합니다. Calendar와 Object는 공개 소유자와 소비 경계를 확정했고, 나머지 후보의 실제
 소유권 재배치는 아직 결정하지 않았습니다.
 
 ```text
@@ -69,13 +69,18 @@ Calendar의 정본 소유자는 `@interactive-os/json-document-calendar-document
 책임 감사 증거를 확인할 수 있습니다. 이 소유권 확정은 RC 계약을 Stable wire
 프로파일로 승격하거나 나머지 후보의 완료를 선언하지 않습니다.
 
-현재 사이트에서 다음 항목이 Document Type 후보입니다.
+Object와 단일 슬라이드 Canvas 프로파일의 정본 소유자는
+`@interactive-os/json-document-object-document`입니다. 기존 `createObjectEditor`가 이를
+소비하며 `@interactive-os/json-document-canvas` Hand가 두 Canvas Host의 입력·UI를
+닫습니다. [Object 소유권 감사](/docs/document-types/object)와 [Canvas Usage/Source](/docs/api/canvas)를 참고하세요.
+
+현재 사이트에서 다음 항목을 추적합니다.
 
 ```text
 Document Types · TBD
 ├── Rich Text
 ├── Order
-├── Object
+├── Object · RC 공개 소유자 확정
 ├── Tree
 ├── Database
 ├── Calendar · RC 공개 소유자 확정
@@ -84,7 +89,7 @@ Document Types · TBD
 └── Annotation
 ```
 
-Calendar 이외의 목록은 분류 후보이지 완료 선언이 아닙니다. 각 후보는 모델, invariant,
+Calendar·Object 이외의 목록은 분류 후보이지 완료 선언이 아닙니다. 각 후보는 모델, invariant,
 operation과 projection의 실제 owner를 감사한 뒤에만 이 위치로 이동할 수
 있습니다. 그때까지 기존 package/API 이름, 모듈 배치와 Hands 내비게이션은
 유지합니다.
diff --git a/docs/public/object.md b/docs/public/object.md
index 12055fa3..35d21600 100644
--- a/docs/public/object.md
+++ b/docs/public/object.md
@@ -1,11 +1,12 @@
 # Object
 
 Object는 안정된 ID를 가진 객체를 집는 편집기입니다. 줄 번호가 아니라 키
-가족(key family)을 씁니다. 화면에서 어디를 눌렀는지는 제품이 계산하고,
-editor에는 객체 ID만 넘깁니다.
+가족(key family)을 씁니다. 문서 모델·검증·연산은
+[`Object Document Type`](/docs/api/object-document), 입력·기하의 UI 조합은
+[`Canvas Hand`](/docs/api/canvas)가 소유하고 editor에는 객체 ID와 Intent를 넘깁니다.
 
-색을 채우거나 지우는 요청은 Intent로 들어갑니다. 기하와 히트 테스트는
-editor 밖에 남습니다.
+생성·글자 편집·색 채우기·이동·resize·삭제는 Intent로 들어갑니다. 문서의 기하
+규칙은 Document Type이, 화면 좌표와 hit target은 Adapter와 Hand가 소유합니다.
 
 ## API Reference
 
@@ -20,8 +21,8 @@ ID 정책을 Host가 주입하는 자리입니다.
 ### `ObjectIntent`
 
 `dispatch`가 받는 Object domain command입니다. 공개 variant는
-`selection.set`, `selection.remove`, `selection.fill`, `object.translate`,
-`object.resize`, `clipboard.paste`입니다. DOM event, pointer 좌표, clipboard
+`selection.set`, `selection.remove`, `selection.fill`, `object.create`, `object.text`,
+`object.translate`, `object.resize`, `document.replace`, `clipboard.paste`입니다. DOM event, pointer 좌표, clipboard
 event를 Intent에 넣지 않습니다.
 
 ### `ObjectSelectionMode`
@@ -48,7 +49,7 @@ Object Hands는 서로 다른 수명의 상태를 한 덩어리로 만들지 않
 
 - document state는 객체의 값과 기하를 보존합니다.
 - editing session은 선택과 undo/redo를 보존합니다.
-- host interaction state는 active tool, hover, drag, resize처럼 현재 조작만
+- Hand interaction state는 active tool, text draft, drag, resize처럼 현재 조작만
   보존합니다.
 
 객체를 만드는 작업이 끝나면 그 결과를 현재 선택으로 만듭니다. 예를 들어
@@ -68,6 +69,6 @@ Object Hands는 서로 다른 수명의 상태를 한 덩어리로 만들지 않
 /demo/object
 ```
 
-```live-demo
-/demo/canvas
-```
+[한 장짜리 Canvas의 Usage와 Source](/docs/api/canvas)는 별도 Canvas editor 없이
+이 Object Editing을 사용합니다. 기존 Object의 다중 선택·Clipboard API는 유지하지만
+Canvas UI는 단일 선택만 제공합니다.
diff --git a/docs/public/ui-primitives.md b/docs/public/ui-primitives.md
index a205b4a0..dcd11938 100644
--- a/docs/public/ui-primitives.md
+++ b/docs/public/ui-primitives.md
@@ -75,7 +75,7 @@ Escape/Tab의 popup close와 focus restore, filtering과 option content는 Host
 | 역할 | 정본 primitive | 허용 presentation |
 | --- | --- | --- |
 | 명령 실행 | `Command` | label, icon |
-| 이진 상태 | `Toggle` | button, chip |
+| 이진 상태 | `Toggle` | button, chip, icon |
 | 단일 값 선택 | `Choice` | inline, popup |
 | 다중 포함 여부 | `Check` | checkbox |
 | surface 이동 | `Tabs` | tab list |
@@ -118,7 +118,11 @@ icon button은 독립 역할이 아니므로 공개 primitive가 아닙니다.
 보존합니다. `Command`는 명령 실행 역할 하나를 소유하며 label과 icon은 presentation입니다.
 `Toggle`은 `pressed`를 `aria-pressed`에 투영하며 icon-only인 경우
 `label`을 visible tooltip과 accessible name으로 사용합니다. `Command`도
-`label`을 visible tooltip과 accessible name에 투영합니다. `Toggle`은 binary state를,
+`label`을 visible tooltip과 accessible name에 투영합니다. `Toggle`은 label이 있으면
+기본 presentation이 `icon`이며 명시적인 `button`/`chip` 지정은 보존합니다.
+텍스트 버튼에 설명만 추가하려면 `tooltip`을 사용합니다. 아이콘 전용 Command와
+Toggle은 같은 32px hit target, 무테, hover/focus/disabled 문법을 공유하고
+Toggle의 선택 상태는 배경으로 표시합니다. `Toggle`은 binary state를,
 `Choice`는 single choice를, `Tabs`는 navigation surface 전환을 소유합니다.
 `Choice`와 `Tabs`는 option ID generic을 callback까지
 보존하므로 Host는 선택 값을 다시 cast하지 않습니다. `DisclosureButton`은
diff --git a/package-lock.json b/package-lock.json
index dc4e8f47..c517ec01 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -8,6 +8,7 @@
       "workspaces": [
         "packages/json-document",
         "packages/json-document-selection",
+        "packages/json-document-object-document",
         "packages/json-document-calendar-document",
         "packages/json-document-editing",
         "packages/json-document-react",
@@ -22,6 +23,7 @@
         "packages/json-document-database",
         "packages/json-document-annotation",
         "packages/json-document-calendar",
+        "packages/json-document-canvas",
         "packages/json-document-tanstack-table",
         "packages/json-document-web",
         "packages/json-document-contenteditable",
@@ -1138,6 +1140,10 @@
       "resolved": "packages/json-document-calendar-document",
       "link": true
     },
+    "node_modules/@interactive-os/json-document-canvas": {
+      "resolved": "packages/json-document-canvas",
+      "link": true
+    },
     "node_modules/@interactive-os/json-document-collaboration": {
       "resolved": "packages/json-document-collaboration",
       "link": true
@@ -1174,6 +1180,10 @@
       "resolved": "packages/json-document-markdown-react",
       "link": true
     },
+    "node_modules/@interactive-os/json-document-object-document": {
+      "resolved": "packages/json-document-object-document",
+      "link": true
+    },
     "node_modules/@interactive-os/json-document-react": {
       "resolved": "packages/json-document-react",
       "link": true
@@ -6594,6 +6604,39 @@
         "@interactive-os/json-document": "^3.0.0"
       }
     },
+    "packages/json-document-canvas": {
+      "name": "@interactive-os/json-document-canvas",
+      "version": "0.1.0-rc.0",
+      "license": "MIT",
+      "dependencies": {
+        "lucide-react": "^1.33.0"
+      },
+      "devDependencies": {
+        "@interactive-os/json-document-affordance": "*",
+        "@interactive-os/json-document-editing": "*",
+        "@interactive-os/json-document-object-document": "*",
+        "@interactive-os/json-document-react": "*",
+        "@interactive-os/json-document-ui-primitives-react": "*",
+        "@interactive-os/json-document-web": "*",
+        "@testing-library/react": "^16.3.2",
+        "@types/react": "^19.2.14",
+        "@vitejs/plugin-react": "^5.2.0",
+        "jsdom": "^29.1.1",
+        "react": "^19.2.5",
+        "react-dom": "^19.2.5",
+        "typescript": "^5.0.0",
+        "vitest": "^4.1.7"
+      },
+      "peerDependencies": {
+        "@interactive-os/json-document-affordance": ">=0.1.0-rc.0 <1",
+        "@interactive-os/json-document-editing": ">=0.1.0-rc.0 <1",
+        "@interactive-os/json-document-object-document": ">=0.1.0-rc.0 <1",
+        "@interactive-os/json-document-react": ">=0.1.0-rc.0 <1",
+        "@interactive-os/json-document-ui-primitives-react": ">=0.1.0-rc.0 <1",
+        "@interactive-os/json-document-web": ">=0.1.0-rc.0 <1",
+        "react": "^18.0.0 || ^19.0.0"
+      }
+    },
     "packages/json-document-collaboration": {
       "name": "@interactive-os/json-document-collaboration",
       "version": "0.2.0-rc.1",
@@ -6743,6 +6786,7 @@
       "devDependencies": {
         "@interactive-os/json-document": "*",
         "@interactive-os/json-document-calendar-document": "*",
+        "@interactive-os/json-document-object-document": "*",
         "@interactive-os/json-document-selection": "*",
         "@types/node": "^25.9.0",
         "typescript": "^5.0.0",
@@ -6751,6 +6795,7 @@
       "peerDependencies": {
         "@interactive-os/json-document": "^3.0.0",
         "@interactive-os/json-document-calendar-document": "^0.1.0-rc.0",
+        "@interactive-os/json-document-object-document": ">=0.1.0-rc.0 <1",
         "@interactive-os/json-document-selection": "^0.1.0-rc.0"
       }
     },
@@ -6790,6 +6835,20 @@
         "react": "^18.0.0 || ^19.0.0"
       }
     },
+    "packages/json-document-object-document": {
+      "name": "@interactive-os/json-document-object-document",
+      "version": "0.1.0-rc.0",
+      "license": "MIT",
+      "devDependencies": {
+        "@interactive-os/json-document": "*",
+        "@types/node": "^25.9.0",
+        "typescript": "^5.0.0",
+        "vitest": "^4.1.7"
+      },
+      "peerDependencies": {
+        "@interactive-os/json-document": "^3.0.0"
+      }
+    },
     "packages/json-document-react": {
       "name": "@interactive-os/json-document-react",
       "version": "0.1.0-rc.0",
@@ -7089,6 +7148,7 @@
         "@interactive-os/json-document-annotation": "*",
         "@interactive-os/json-document-calendar": "*",
         "@interactive-os/json-document-calendar-document": "*",
+        "@interactive-os/json-document-canvas": "*",
         "@interactive-os/json-document-collaboration": "*",
         "@interactive-os/json-document-composer": "*",
         "@interactive-os/json-document-composer-react": "*",
@@ -7098,6 +7158,7 @@
         "@interactive-os/json-document-editing": "*",
         "@interactive-os/json-document-file-intake": "*",
         "@interactive-os/json-document-markdown-react": "*",
+        "@interactive-os/json-document-object-document": "*",
         "@interactive-os/json-document-react": "*",
         "@interactive-os/json-document-react-hook-form": "*",
         "@interactive-os/json-document-rich-text": "*",
diff --git a/package.json b/package.json
index 9267d77d..ef935a9b 100644
--- a/package.json
+++ b/package.json
@@ -5,6 +5,7 @@
   "workspaces": [
     "packages/json-document",
     "packages/json-document-selection",
+    "packages/json-document-object-document",
     "packages/json-document-calendar-document",
     "packages/json-document-editing",
     "packages/json-document-react",
@@ -19,6 +20,7 @@
     "packages/json-document-database",
     "packages/json-document-annotation",
     "packages/json-document-calendar",
+    "packages/json-document-canvas",
     "packages/json-document-tanstack-table",
     "packages/json-document-web",
     "packages/json-document-contenteditable",
diff --git a/packages/json-document-canvas/LICENSE b/packages/json-document-canvas/LICENSE
new file mode 100644
index 00000000..6a984193
--- /dev/null
+++ b/packages/json-document-canvas/LICENSE
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 interactive-os contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/packages/json-document-canvas/README.md b/packages/json-document-canvas/README.md
new file mode 100644
index 00000000..920b9aa6
--- /dev/null
+++ b/packages/json-document-canvas/README.md
@@ -0,0 +1,20 @@
+# Canvas Hand
+
+`@interactive-os/json-document-canvas`는 한 장의 Object Canvas 프로파일에서
+글자·사각형·타원·그리기를 완성하는 React Hand입니다. 별도 Canvas editor나
+selection/history 구현을 만들지 않고 기존 `createObjectEditor`를 사용합니다.
+
+```tsx
+import { useState } from "react";
+import { createObjectEditor } from "@interactive-os/json-document-editing";
+import { CanvasHand } from "@interactive-os/json-document-canvas";
+
+function Slide() {
+  const [editor] = useState(() => createObjectEditor({ profile: "canvas/1", width: 1280, height: 720, objects: [] }));
+  return <CanvasHand editor={editor} creationStyle={{ color: "#b6c8e8", textColor: "#253044", fontSize: 36, strokeWidth: 4 }} />;
+}
+```
+
+CSS와 레이아웃은 Host가 결정하고 controls는 기존 UI Primitives를 소비합니다.
+슬라이드 크기와 색은 문서/제품 값입니다. [API 계약](docs/api.md)과
+[실제 Usage/Source](https://developer-1px.github.io/json-document/docs/api/canvas)를 참고하세요.
diff --git a/packages/json-document-canvas/docs/api.md b/packages/json-document-canvas/docs/api.md
new file mode 100644
index 00000000..0ba49d22
--- /dev/null
+++ b/packages/json-document-canvas/docs/api.md
@@ -0,0 +1,63 @@
+## Canvas Hand 계약 · RC
+
+`CanvasHand`는 `ObjectEditor`와 `CanvasCreationStyle`을 받아 글자·사각형·타원·자유
+그리기, 단일 선택, 이동·resize·삭제, Undo/Redo, JSON 재열기를 연결합니다.
+`useCanvasHand`는 같은 입력 조합을 custom UI에서 사용할 수 있게 공개합니다.
+
+툴바의 모든 도구·명령은 Lucide 아이콘과 공통 `Toggle`/`Command`의 `label`을
+사용합니다. label이 접근성 이름과 hover/focus 툴팁의 정본이며, 별도 툴팁이나
+버튼 구현을 두지 않습니다. 선택 도구는 `aria-pressed`, 실행 불가 명령은
+`disabled`로 상태를 전달합니다.
+
+```text
+Host: 한 장 fixture, 크기·색상 정책, 레이아웃
+  └─ Canvas Hand: 도구, 조작 preview, plain-text draft, UI 조합
+      ├─ React Connector: Editing snapshot 구독
+      ├─ Web Adapter: SVG 좌표, pointer capture, keyboard 해석
+      ├─ Affordance / UI Primitives: gesture, drag/resize, handle, controls
+      └─ Object Editing: Intent, ID 할당, Selection, History
+          ├─ Object Document Type: Canvas profile, 검증, 연산, projection, JSON
+          └─ Core: immutable 값과 atomic JSON Patch
+```
+
+이는 책임 관계이며 모든 입력이 통과하는 직렬 pipeline이 아닙니다.
+
+### 입력과 History
+
+- 도구를 고르고 클릭하면 기본 크기, 드래그하면 지정한 크기로 생성합니다.
+  생성 후 Select로 돌아가며 새 객체를 선택합니다. 펜은 최소 두 지점이 필요합니다.
+- 객체 경계 상자를 집어 움직이고 네 모서리 손잡이로 resize합니다. 마지막 객체가
+  위에 표시되며 단일 선택만 UI로 제공합니다. ObjectEditor의 기존 집합 API는 유지합니다.
+- 글자는 생성 직후 또는 더블클릭/F2/Enter로 편집합니다. 줄바꿈·IME·선택·native
+  입력 Undo는 textarea에 남습니다. blur 또는 Mod+Enter가 전체 draft를 한 번 commit하고
+  Escape는 draft만 버립니다. 객체의 label이 실제 문자열 값입니다.
+- 이동·resize·생성 중에는 문서를 변경하지 않습니다. pointerup의 최종 좌표로 한 번
+  commit합니다. Escape, pointercancel, capture loss, 외부 문서 변경, unmount는 preview를
+  버립니다. 다른 pointer의 release는 조작을 완료하지 못합니다.
+- 선택만 바꾸거나 0 거리로 움직이면 History가 생기지 않습니다. commit된 편집은
+  한 번의 Undo로 되돌리며 삭제 Undo는 객체와 선택을 함께 복원합니다. Mod+Z/Mod+Shift+Z는
+  입력 필드 밖에서 문서 Undo/Redo를 실행합니다.
+
+### JSON
+
+JSON 버튼은 현재 문서 문자열을 노출합니다. 이 문자열을 저장해 다시 JSON 입력에
+넣고 `JSON 열기`로 복원할 수 있습니다. 재열기는 전체 문서 교체 한 번으로 기록하고
+선택을 비우며 Undo도 가능합니다. 잘못된 JSON은 오류를 표시하고 기존 문서와 History를
+보존합니다. 새 ObjectEditor에 deserialize한 값을 넣으면 새 History 세션으로 시작합니다.
+파일 시스템·서버 persistence 정책은 Host 범위입니다.
+
+### 범위와 Usage
+
+단일 슬라이드를 컨테이너에 맞춰 표시합니다. 확대/축소·페이지·팬·다중 선택·그룹·회전·
+snap·레이어·Clipboard UI·PPTX·collaboration은 이번 Hand의 지원 범위가 아닙니다.
+`creationStyle`은 새 객체에만 적용하는 제품 기본값이며 저장 객체의 스타일을 덮어쓰지 않습니다.
+
+```live-demo
+/demo/canvas
+```
+
+샘플이 있는 두 번째 Host도 같은 Hand를 사용합니다.
+
+```live-demo
+/widgets/canvas
+```
diff --git a/packages/json-document-canvas/package.json b/packages/json-document-canvas/package.json
new file mode 100644
index 00000000..f0333f27
--- /dev/null
+++ b/packages/json-document-canvas/package.json
@@ -0,0 +1,33 @@
+{
+  "name": "@interactive-os/json-document-canvas",
+  "version": "0.1.0-rc.0",
+  "description": "Official React Canvas Hand for a fixed single-slide Object document.",
+  "type": "module", "license": "MIT", "sideEffects": false,
+  "main": "./dist/index.js", "types": "./dist/index.d.ts",
+  "repository": { "type": "git", "url": "git+https://github.com/developer-1px/json-document.git", "directory": "packages/json-document-canvas" },
+  "publishConfig": { "access": "public", "provenance": true, "tag": "next" },
+  "files": ["dist", "!dist/.tsbuildinfo", "README.md", "docs", "LICENSE"],
+  "exports": { ".": { "types": "./dist/index.d.ts", "import": "./dist/index.js" } },
+  "scripts": {
+    "build": "tsc -b tsconfig.json", "pretypecheck": "node ../../scripts/workspace-tasks.mjs build-dependencies",
+    "typecheck": "tsc -p tsconfig.test.json --noEmit", "test": "vitest run --config vitest.config.ts",
+    "verify": "npm run typecheck && npm test && npm run build"
+  },
+  "dependencies": { "lucide-react": "^1.33.0" },
+  "peerDependencies": {
+    "@interactive-os/json-document-object-document": ">=0.1.0-rc.0 <1",
+    "@interactive-os/json-document-editing": ">=0.1.0-rc.0 <1",
+    "@interactive-os/json-document-affordance": ">=0.1.0-rc.0 <1",
+    "@interactive-os/json-document-web": ">=0.1.0-rc.0 <1",
+    "@interactive-os/json-document-react": ">=0.1.0-rc.0 <1",
+    "@interactive-os/json-document-ui-primitives-react": ">=0.1.0-rc.0 <1",
+    "react": "^18.0.0 || ^19.0.0"
+  },
+  "devDependencies": {
+    "@interactive-os/json-document-object-document": "*", "@interactive-os/json-document-editing": "*",
+    "@interactive-os/json-document-affordance": "*", "@interactive-os/json-document-web": "*",
+    "@interactive-os/json-document-react": "*", "@interactive-os/json-document-ui-primitives-react": "*",
+    "@testing-library/react": "^16.3.2", "@types/react": "^19.2.14", "@vitejs/plugin-react": "^5.2.0",
+    "jsdom": "^29.1.1", "react": "^19.2.5", "react-dom": "^19.2.5", "typescript": "^5.0.0", "vitest": "^4.1.7"
+  }
+}
diff --git a/packages/json-document-canvas/src/canvas-hand.tsx b/packages/json-document-canvas/src/canvas-hand.tsx
new file mode 100644
index 00000000..84d74f39
--- /dev/null
+++ b/packages/json-document-canvas/src/canvas-hand.tsx
@@ -0,0 +1,60 @@
+import { useState, type CSSProperties } from "react";
+import { Braces, Circle, MousePointer2, Pencil, RectangleHorizontal, Redo2, Trash2, Type, Undo2, type LucideIcon } from "lucide-react";
+import type { ObjectEditor } from "@interactive-os/json-document-editing";
+import { serializeCanvasDocument } from "@interactive-os/json-document-object-document";
+import { Command, Field, ProductShell, Toggle, ToolbarGroup } from "@interactive-os/json-document-ui-primitives-react";
+import { CanvasObjectTarget, CanvasObjectView, CanvasResizeTarget, CanvasTextInput } from "./canvas-object-view.js";
+import { useCanvasHand, type CanvasCreationStyle, type CanvasTool } from "./use-canvas-hand.js";
+
+export interface CanvasHandProps {
+  readonly editor: ObjectEditor;
+  readonly creationStyle: CanvasCreationStyle;
+  readonly className?: string;
+  readonly slideStyle?: CSSProperties;
+  readonly label?: string;
+}
+
+const tools: ReadonlyArray<{ readonly id: CanvasTool; readonly label: string; readonly icon: LucideIcon }> = [
+  { id: "select", label: "선택", icon: MousePointer2 }, { id: "text", label: "글자", icon: Type },
+  { id: "rectangle", label: "사각형", icon: RectangleHorizontal }, { id: "ellipse", label: "타원", icon: Circle }, { id: "path", label: "그리기", icon: Pencil },
+];
+
+export function CanvasHand(props: CanvasHandProps) {
+  const hand = useCanvasHand(props.editor, props.creationStyle);
+  const [json, setJSON] = useState<string | null>(null);
+  const selected = hand.objects.find((object) => object.id === hand.snapshot.selection.primaryKey);
+  return (
+    <ProductShell className={props.className} toolbarLabel="Canvas tools" toolbar={<ToolbarGroup style={{ flexWrap: "wrap" }}>
+      <ToolbarGroup>{tools.map((tool) => <Toggle key={tool.id} label={tool.label} pressed={hand.tool === tool.id} onClick={() => hand.choose(tool.id)}><tool.icon aria-hidden="true" size={16} /></Toggle>)}</ToolbarGroup>
+      <ToolbarGroup>
+        <Command label="실행 취소" disabled={!hand.snapshot.canUndo} onClick={() => hand.history("undo")}><Undo2 aria-hidden="true" size={16} /></Command>
+        <Command label="다시 실행" disabled={!hand.snapshot.canRedo} onClick={() => hand.history("redo")}><Redo2 aria-hidden="true" size={16} /></Command>
+        <Command label="삭제" disabled={!selected} onClick={hand.remove}><Trash2 aria-hidden="true" size={16} /></Command>
+      </ToolbarGroup>
+      <Command label="JSON" onClick={() => { hand.commitText(); hand.cancel(); setJSON(json === null ? serializeCanvasDocument(props.editor.snapshot.value as typeof hand.document) : null); }}><Braces aria-hidden="true" size={16} /></Command>
+    </ToolbarGroup>}>
+      <svg ref={hand.surface} {...hand.surfaceProps} tabIndex={0} role="group" aria-label={props.label ?? "Canvas slide"}
+        data-canvas-slide="true" data-tool={hand.tool} viewBox={`0 0 ${hand.document.width} ${hand.document.height}`} preserveAspectRatio="none"
+        style={{ display: "block", width: "100%", aspectRatio: `${hand.document.width} / ${hand.document.height}`, touchAction: "none", userSelect: "none", overflow: "hidden", ...props.slideStyle }}>
+        {hand.objects.map((object) => <g key={object.id}>
+          {hand.draft?.id !== object.id && <CanvasObjectView object={object} />}
+          <CanvasObjectTarget object={object} selected={object.id === hand.snapshot.selection.primaryKey} enabled={hand.tool === "select" && hand.draft?.id !== object.id}
+            onSelect={() => hand.select(object.id)} onEdit={() => hand.editText(object.id)} onHandle={(interaction, event) => hand.interaction(interaction, event, object, "drag")} />
+        </g>)}
+        {hand.preview && <g pointerEvents="none" opacity={0.65}><CanvasObjectView object={{ ...hand.preview, id: "preview" }} /></g>}
+        {selected && hand.tool === "select" && <g>
+          <rect x={selected.x} y={selected.y} width={selected.width} height={selected.height} fill="none" stroke="rgb(var(--color-border-accent))" strokeWidth={2} pointerEvents="none" />
+          {!hand.draft && (["nw", "ne", "se", "sw"] as const).map((edge) => <CanvasResizeTarget key={edge} object={selected} edge={edge} onHandle={(interaction, event) => hand.interaction(interaction, event, selected, "resize", edge)} />)}
+        </g>}
+        {selected?.kind === "text" && hand.draft?.id === selected.id && <CanvasTextInput object={selected} text={hand.draft.text} onChange={hand.changeText}
+          onCommit={() => { hand.commitText(); hand.surface.current?.focus(); }} onCancel={() => { hand.cancel(); hand.surface.current?.focus(); }} />}
+      </svg>
+      {hand.error && <p role="alert">{hand.error}</p>}
+      {json !== null && <section aria-label="Canvas JSON">
+        <Field multiline label="Canvas JSON document" value={json} onValueChange={setJSON} rows={10} spellCheck={false} style={{ width: "100%", fontFamily: "monospace" }} />
+        <Command onClick={() => setJSON(serializeCanvasDocument(hand.document))}>현재 문서 읽기</Command>
+        <Command onClick={() => { if (hand.openJSON(json)) setJSON(null); }}>JSON 열기</Command>
+      </section>}
+    </ProductShell>
+  );
+}
diff --git a/packages/json-document-canvas/src/canvas-object-view.tsx b/packages/json-document-canvas/src/canvas-object-view.tsx
new file mode 100644
index 00000000..a7e0e873
--- /dev/null
+++ b/packages/json-document-canvas/src/canvas-object-view.tsx
@@ -0,0 +1,77 @@
+import { useEffect, useRef, type PointerEvent, type ReactNode } from "react";
+import type { CanvasObject } from "@interactive-os/json-document-object-document";
+import type { InteractionHandleEvent, ResizeEdge } from "@interactive-os/json-document-affordance";
+import { contentInteractionAttributes, Field, useInteractionHandle } from "@interactive-os/json-document-ui-primitives-react";
+
+export function CanvasObjectView({ object }: { readonly object: CanvasObject }): ReactNode {
+  if (object.kind === "path") {
+    return <polyline points={object.points.map((point) => `${object.x + point.x * object.width},${object.y + point.y * object.height}`).join(" ")} fill="none" stroke={object.color} strokeWidth={object.strokeWidth} strokeLinecap="round" strokeLinejoin="round" />;
+  }
+  if (object.kind === "text") return (
+    <foreignObject x={object.x} y={object.y} width={object.width} height={object.height}>
+      <div style={{ color: object.color, fontSize: object.fontSize, lineHeight: 1.2, whiteSpace: "pre-wrap", overflowWrap: "anywhere", width: "100%", height: "100%", overflow: "hidden" }}>{object.label}</div>
+    </foreignObject>
+  );
+  return object.kind === "ellipse"
+    ? <ellipse cx={object.x + object.width / 2} cy={object.y + object.height / 2} rx={object.width / 2} ry={object.height / 2} fill={object.color} />
+    : <rect x={object.x} y={object.y} width={object.width} height={object.height} fill={object.color} />;
+}
+
+export function CanvasObjectTarget(props: {
+  readonly object: CanvasObject;
+  readonly selected: boolean;
+  readonly enabled: boolean;
+  readonly onSelect: () => void;
+  readonly onEdit: () => void;
+  readonly onHandle: (interaction: InteractionHandleEvent, event: PointerEvent<SVGElement>) => void;
+}) {
+  const binding = useInteractionHandle<SVGRectElement>({ descriptor: { kind: "drag" }, onHandle: props.onHandle });
+  const { object } = props;
+  return (
+    <rect {...(props.enabled ? binding.handleProps : {})} x={object.x} y={object.y} width={object.width} height={object.height}
+      fill="transparent" role="button" aria-label={object.label || object.kind} aria-pressed={props.selected}
+      {...contentInteractionAttributes({ role: "content", selected: props.selected, dragging: binding.active })}
+      tabIndex={props.enabled ? 0 : -1} data-canvas-object={object.id} data-kind={object.kind}
+      pointerEvents={props.enabled ? "all" : "none"} style={{ cursor: binding.cursor, transform: "none" }}
+      onFocus={props.onSelect} onDoubleClick={props.onEdit}
+      onKeyDown={(event) => { if (event.key === " ") { event.preventDefault(); props.onSelect(); } }} />
+  );
+}
+
+export function CanvasResizeTarget(props: {
+  readonly object: CanvasObject;
+  readonly edge: ResizeEdge;
+  readonly onHandle: (interaction: InteractionHandleEvent, event: PointerEvent<SVGElement>) => void;
+}) {
+  const binding = useInteractionHandle<SVGRectElement>({ descriptor: { kind: "resize", edge: props.edge }, onHandle: props.onHandle });
+  const { object, edge } = props;
+  const x = object.x + (edge.includes("w") ? 0 : edge.includes("e") ? object.width : object.width / 2);
+  const y = object.y + (edge.includes("n") ? 0 : edge.includes("s") ? object.height : object.height / 2);
+  return <rect {...binding.handleProps} data-resize-edge={edge} x={x - 6} y={y - 6} width={12} height={12}
+    fill="rgb(var(--color-background-canvas))" stroke="rgb(var(--color-border-accent))" strokeWidth={2} style={{ cursor: binding.cursor }} />;
+}
+
+export function CanvasTextInput(props: {
+  readonly object: Extract<CanvasObject, { readonly kind: "text" }>;
+  readonly text: string;
+  readonly onChange: (text: string) => void;
+  readonly onCommit: () => void;
+  readonly onCancel: () => void;
+}) {
+  const input = useRef<HTMLTextAreaElement>(null);
+  useEffect(() => { input.current?.focus(); input.current?.select(); }, [props.object.id]);
+  const { object } = props;
+  return (
+    <foreignObject x={object.x} y={object.y} width={object.width} height={object.height}>
+      <Field multiline presentation="seamless" label="Canvas text" controlRef={input} value={props.text} onValueChange={props.onChange}
+        style={{ color: object.color, fontSize: object.fontSize, lineHeight: 1.2, padding: 0, margin: 0, border: 0, width: "100%", height: "100%", resize: "none", background: "transparent", boxSizing: "border-box" }}
+        onBlur={props.onCommit}
+        onKeyDown={(event) => {
+          event.stopPropagation();
+          if (event.nativeEvent.isComposing) return;
+          if (event.key === "Escape") { event.preventDefault(); props.onCancel(); }
+          else if (event.key === "Enter" && (event.metaKey || event.ctrlKey)) { event.preventDefault(); props.onCommit(); }
+        }} />
+    </foreignObject>
+  );
+}
diff --git a/packages/json-document-canvas/src/index.ts b/packages/json-document-canvas/src/index.ts
new file mode 100644
index 00000000..4c1de4e6
--- /dev/null
+++ b/packages/json-document-canvas/src/index.ts
@@ -0,0 +1,2 @@
+export { CanvasHand, type CanvasHandProps } from "./canvas-hand.js";
+export { useCanvasHand, type CanvasTool, type CanvasCreationStyle } from "./use-canvas-hand.js";
diff --git a/packages/json-document-canvas/src/use-canvas-hand.ts b/packages/json-document-canvas/src/use-canvas-hand.ts
new file mode 100644
index 00000000..46186360
--- /dev/null
+++ b/packages/json-document-canvas/src/use-canvas-hand.ts
@@ -0,0 +1,222 @@
+import { useEffect, useMemo, useReducer, useRef, useState, type KeyboardEvent, type PointerEvent } from "react";
+import { createGestureSession, dragAffordance, resizeAffordance, type InteractionHandleEvent, type ResizeEdge } from "@interactive-os/json-document-affordance";
+import { assertCanvasDocument, createCanvasObject, createCanvasPath, parseCanvasDocument, transformObject, type CanvasDocument, type CanvasObject, type CanvasObjectKind, type ObjectPoint } from "@interactive-os/json-document-object-document";
+import type { EditingResult, ObjectEditor, ObjectIntent, ObjectSelection } from "@interactive-os/json-document-editing";
+import { useEditingSnapshot } from "@interactive-os/json-document-react";
+import { createWebKeyboardAdapter, createWebPointerSession, isWebEditableTarget, projectWebClientPointToSVG, webSVGViewportFromElement } from "@interactive-os/json-document-web";
+
+export type CanvasTool = "select" | CanvasObjectKind;
+export interface CanvasCreationStyle {
+  readonly color: string;
+  readonly textColor: string;
+  readonly fontSize: number;
+  readonly strokeWidth: number;
+}
+
+type Gesture = { readonly base: CanvasDocument } & (
+  | { readonly type: "create"; readonly tool: Exclude<CanvasObjectKind, "path">; readonly start: ObjectPoint; readonly point: ObjectPoint }
+  | { readonly type: "draw"; readonly points: ReadonlyArray<ObjectPoint> }
+  | { readonly type: "drag" | "resize"; readonly object: CanvasObject; readonly start: ObjectPoint; readonly point: ObjectPoint; readonly edge: ResizeEdge }
+);
+type TextDraft = { readonly id: string; readonly text: string; readonly base: CanvasDocument };
+
+const keyboard = createWebKeyboardAdapter();
+const commands = createWebKeyboardAdapter<"cancel" | "edit">({ defaults: false, keymap: { Escape: "cancel", Enter: "edit", F2: "edit" } });
+
+/** Owns Canvas interaction composition, never document or history state. */
+export function useCanvasHand(editor: ObjectEditor, style: CanvasCreationStyle) {
+  const snapshot = useEditingSnapshot(editor);
+  const document = useMemo(() => { assertCanvasDocument(snapshot.value); return snapshot.value; }, [snapshot.value]);
+  const surface = useRef<SVGSVGElement>(null);
+  const [, redraw] = useReducer((value: number) => value + 1, 0);
+  const [tool, setTool] = useState<CanvasTool>("select");
+  const [error, setError] = useState<string | null>(null);
+  const draft = useRef<TextDraft | null>(null);
+  const gestures = useMemo(() => createGestureSession<Gesture>({ onBegin: redraw, onPreview: redraw, onCommit: redraw, onCancel: redraw }), [editor]);
+  const pointer = useMemo(() => createWebPointerSession<true>({ onCancel: (_, reason) => gestures.cancel(reason === "lost-capture" ? "lost-capture" : "pointer-cancel") }), [gestures]);
+
+  function current(): CanvasDocument {
+    const value = editor.snapshot.value;
+    assertCanvasDocument(value);
+    return value;
+  }
+
+  function cancel() {
+    const active = pointer.getSnapshot();
+    if (active) pointer.cancel(active.pointerId);
+    gestures.cancel();
+    draft.current = null;
+    redraw();
+  }
+
+  useEffect(() => {
+    // A replacement/external edit invalidates previews, even when an ID survives.
+    const release = editor.subscribe((next) => {
+      if ((gestures.getActive() && gestures.getActive()!.base !== next.value) || (draft.current && draft.current.base !== next.value)) cancel();
+    });
+    return () => {
+      release();
+      const active = pointer.getSnapshot();
+      if (active) pointer.cancel(active.pointerId);
+      gestures.cancel();
+      draft.current = null;
+    };
+  }, [editor, gestures, pointer]);
+
+  function report(result: EditingResult<ObjectSelection>) {
+    setError(result.ok ? null : result.reason ?? result.code);
+    return result;
+  }
+
+  function dispatch(intent: ObjectIntent) { return report(editor.dispatch(intent)); }
+  function select(id: string | null) { dispatch({ type: "selection.set", objectIds: id === null ? [] : [id], mode: "replace" }); }
+
+  function editText(id: string) {
+    const base = current();
+    const object = base.objects.find((item) => item.id === id);
+    if (object?.kind !== "text") return;
+    cancel(); select(id);
+    draft.current = { id, text: object.label, base };
+    redraw();
+  }
+
+  function commitText() {
+    const active = draft.current;
+    if (!active) return;
+    draft.current = null;
+    if (active.base === current()) dispatch({ type: "object.text", objectId: active.id, text: active.text });
+    redraw();
+  }
+
+  function choose(next: CanvasTool) {
+    commitText(); cancel(); setTool(next); setError(null);
+    surface.current?.focus();
+  }
+
+  function eventPoint(event: { readonly clientX: number; readonly clientY: number }): ObjectPoint | null {
+    if (!surface.current) return null;
+    const point = projectWebClientPointToSVG({ x: event.clientX, y: event.clientY }, webSVGViewportFromElement(surface.current));
+    return point && Number.isFinite(point.x) && Number.isFinite(point.y) ? { x: point.x, y: point.y } : null;
+  }
+
+  function createPreview(gesture: Extract<Gesture, { type: "create" | "draw" }>) {
+    if (gesture.type === "draw") return gesture.points.length < 2 ? null : createCanvasPath(gesture.points, { color: style.textColor, label: "Drawing", strokeWidth: style.strokeWidth });
+    const { start, point } = gesture;
+    const click = Math.hypot(point.x - start.x, point.y - start.y) < 3;
+    return createCanvasObject(gesture.tool, {
+      x: Math.min(start.x, point.x), y: Math.min(start.y, point.y),
+      width: click ? (gesture.tool === "text" ? 280 : 160) : Math.abs(point.x - start.x),
+      height: click ? (gesture.tool === "text" ? 64 : 100) : Math.abs(point.y - start.y),
+    }, { color: gesture.tool === "text" ? style.textColor : style.color, label: gesture.tool === "text" ? "Text" : "", fontSize: style.fontSize });
+  }
+
+  function transform(gesture: Extract<Gesture, { type: "drag" | "resize" }>) {
+    const result = gesture.type === "drag" ? dragAffordance(gesture.start, gesture.point) : resizeAffordance(gesture.start, gesture.point, gesture.edge);
+    const hand = result.hand;
+    return hand?.type === "translate" || hand?.type === "resize" ? hand : { dx: 0, dy: 0 };
+  }
+
+  function commitGesture() {
+    const active = gestures.commit();
+    if (!active || active.base !== current()) return;
+    if (active.type === "create" || active.type === "draw") {
+      const object = createPreview(active);
+      if (!object) return;
+      const result = dispatch({ type: "object.create", object });
+      if (result.ok) {
+        setTool("select");
+        const id = result.snapshot.selection.primaryKey;
+        if (active.type === "create" && active.tool === "text" && id) editText(id);
+      }
+    } else {
+      const delta = transform(active);
+      dispatch(active.type === "drag"
+        ? { type: "object.translate", objectIds: [active.object.id], dx: delta.dx, dy: delta.dy }
+        : { type: "object.resize", objectIds: [active.object.id], dx: delta.dx, dy: delta.dy, dw: "dw" in delta ? delta.dw : 0, dh: "dh" in delta ? delta.dh : 0 });
+    }
+  }
+
+  function pointerDown(event: PointerEvent<SVGSVGElement>) {
+    if (event.button !== 0 || isWebEditableTarget(event.target)) return;
+    if (tool === "select" && (event.target as Element).closest("[data-canvas-object]")) return;
+    const point = eventPoint(event);
+    if (!point) return;
+    event.preventDefault();
+    commitText(); cancel(); surface.current?.focus();
+    if (tool === "select") { select(null); return; }
+    pointer.begin(event.currentTarget, event.pointerId, true);
+    const base = current();
+    gestures.begin(tool === "path" ? { type: "draw", points: [point], base } : { type: "create", tool, start: point, point, base });
+  }
+
+  function pointerMove(event: PointerEvent<SVGSVGElement>) {
+    if (pointer.getSnapshot()?.pointerId !== event.pointerId) return;
+    const point = eventPoint(event), active = gestures.getActive();
+    if (!point || !active) return;
+    if (active.type === "draw") {
+      const last = active.points.at(-1)!;
+      if (last.x !== point.x || last.y !== point.y) gestures.preview({ ...active, points: [...active.points, point] });
+    } else gestures.preview({ ...active, point });
+  }
+
+  function interaction(interaction: InteractionHandleEvent, event: PointerEvent<SVGElement>, object: CanvasObject, type: "drag" | "resize", edge: ResizeEdge = "se") {
+    if (interaction.phase === "cancel") { gestures.cancel("pointer-cancel"); return; }
+    const point = eventPoint(event);
+    if (!point) return;
+    if (interaction.phase === "start") {
+      commitText(); cancel(); surface.current?.focus(); select(object.id);
+      const latest = current().objects.find((item) => item.id === object.id);
+      if (latest) gestures.begin({ type, object: latest, start: point, point, edge, base: current() });
+    } else {
+      const active = gestures.getActive();
+      if (!active || active.type !== type || active.object.id !== object.id) return;
+      gestures.preview({ ...active, point });
+      if (interaction.phase === "commit") commitGesture();
+    }
+  }
+
+  function remove() { commitText(); cancel(); dispatch({ type: "selection.remove" }); surface.current?.focus(); }
+  function history(direction: "undo" | "redo") { commitText(); cancel(); report(editor[direction]()); surface.current?.focus(); }
+
+  function keyDown(event: KeyboardEvent) {
+    if (event.nativeEvent.isComposing || isWebEditableTarget(event.target)) return;
+    const command = commands.resolve(event);
+    if (command === "cancel") {
+      event.preventDefault();
+      if (gestures.getActive() || draft.current) cancel(); else select(null);
+      setTool("select"); return;
+    }
+    if (command === "edit" && editor.snapshot.selection.primaryKey) {
+      event.preventDefault(); editText(editor.snapshot.selection.primaryKey); return;
+    }
+    const action = keyboard.resolve(event);
+    if (action?.type === "delete" && editor.snapshot.selection.keys.length) { event.preventDefault(); remove(); }
+    if (action?.type === "undo" || action?.type === "redo") { event.preventDefault(); history(action.type); }
+  }
+
+  const gesture = gestures.getActive();
+  const objects = document.objects.map((object) => gesture && (gesture.type === "drag" || gesture.type === "resize") && gesture.object.id === object.id ? transformObject(object, transform(gesture)) : object);
+  const preview = gesture && (gesture.type === "create" || gesture.type === "draw") ? createPreview(gesture) : null;
+
+  return {
+    document, snapshot, objects, preview, surface, tool, error, draft: draft.current,
+    choose, select, interaction, editText, commitText, cancel, remove, history,
+    changeText(text: string) { if (draft.current) { draft.current = { ...draft.current, text }; redraw(); } },
+    openJSON(json: string) {
+      try {
+        const document = parseCanvasDocument(json);
+        cancel();
+        const result = dispatch({ type: "document.replace", document });
+        if (result.ok) setTool("select");
+        return result.ok;
+      } catch (error) { setError(error instanceof Error ? error.message : String(error)); return false; }
+    },
+    surfaceProps: {
+      onPointerDown: pointerDown, onPointerMove: pointerMove,
+      onPointerUp(event: PointerEvent<SVGSVGElement>) { pointerMove(event); if (pointer.commit(event.pointerId) !== null) commitGesture(); },
+      onPointerCancel(event: PointerEvent<SVGSVGElement>) { pointer.cancel(event.pointerId); },
+      onLostPointerCapture(event: PointerEvent<SVGSVGElement>) { pointer.cancel(event.pointerId, "lost-capture"); },
+      onKeyDown: keyDown,
+    },
+  };
+}
diff --git a/packages/json-document-canvas/tests/canvas-hand.test.tsx b/packages/json-document-canvas/tests/canvas-hand.test.tsx
new file mode 100644
index 00000000..24c99f23
--- /dev/null
+++ b/packages/json-document-canvas/tests/canvas-hand.test.tsx
@@ -0,0 +1,155 @@
+import { act, cleanup, fireEvent, render, screen, within } from "@testing-library/react";
+import { afterEach, beforeAll, expect, test, vi } from "vitest";
+import { createJSONDocument } from "@interactive-os/json-document";
+import { createObjectEditor } from "@interactive-os/json-document-editing";
+import type { CanvasDocument } from "@interactive-os/json-document-object-document";
+import { CanvasHand } from "../src/index.js";
+
+const blank: CanvasDocument = { profile: "canvas/1", width: 1280, height: 720, objects: [] };
+const style = { color: "#abcdef", textColor: "#123456", fontSize: 32, strokeWidth: 3 };
+beforeAll(() => {
+  class Pointer extends MouseEvent { readonly pointerId: number; constructor(type: string, init: PointerEventInit = {}) { super(type, init); this.pointerId = init.pointerId ?? 1; } }
+  vi.stubGlobal("PointerEvent", Pointer);
+  const captures = new WeakMap<Element, number>();
+  Element.prototype.setPointerCapture = function (id) { captures.set(this, id); };
+  Element.prototype.hasPointerCapture = function (id) { return captures.get(this) === id; };
+  Element.prototype.releasePointerCapture = function () { captures.delete(this); };
+});
+afterEach(cleanup);
+
+function setup(document = blank) {
+  const source = createJSONDocument(document);
+  const commits = vi.fn(); source.subscribe(commits);
+  let id = 0;
+  const editor = createObjectEditor(source, { createId: () => `object-${++id}` });
+  const view = render(<CanvasHand editor={editor} creationStyle={style} />);
+  const svg = screen.getByRole("group", { name: "Canvas slide" });
+  Object.defineProperty(svg, "viewBox", { value: { baseVal: { x: 0, y: 0, width: 1280, height: 720 } } });
+  svg.getBoundingClientRect = () => ({ x: 0, y: 0, left: 0, top: 0, right: 640, bottom: 360, width: 640, height: 360, toJSON() {} });
+  const value = () => editor.snapshot.value as CanvasDocument;
+  return { ...view, svg, editor, source, commits, value };
+}
+function event(x: number, y: number, pointerId = 1) { return { clientX: x, clientY: y, pointerId, button: 0, bubbles: true }; }
+function rectangle(svg: Element) {
+  fireEvent.click(screen.getByRole("button", { name: "사각형" }));
+  fireEvent.pointerDown(svg, event(40, 50)); fireEvent.pointerMove(svg, event(140, 100)); fireEvent.pointerUp(svg, event(140, 100));
+}
+
+test("every toolbar control shares icon, accessible name and canonical tooltip without losing state", () => {
+  const { svg } = setup();
+  const toolbar = within(screen.getByRole("toolbar", { name: "Canvas tools" }));
+  const labels = ["선택", "글자", "사각형", "타원", "그리기", "실행 취소", "다시 실행", "삭제", "JSON"];
+  expect(toolbar.getAllByRole("button")).toHaveLength(labels.length);
+  for (const label of labels) {
+    const button = toolbar.getByRole("button", { name: label });
+    expect(button.textContent).toBe("");
+    expect(button.querySelector('svg[aria-hidden="true"]')).not.toBeNull();
+    expect(button.getAttribute("data-ui-presentation")).toBe("icon");
+    expect(button.getAttribute("aria-describedby")).toBe(toolbar.getByRole("tooltip", { name: label }).id);
+    expect(button.hasAttribute("title")).toBe(false);
+  }
+  expect(toolbar.getByRole("button", { name: "선택" }).getAttribute("aria-pressed")).toBe("true");
+  expect((toolbar.getByRole("button", { name: "삭제" }) as HTMLButtonElement).disabled).toBe(true);
+  fireEvent.click(toolbar.getByRole("button", { name: "그리기" }));
+  expect(svg.getAttribute("data-tool")).toBe("path");
+  expect(toolbar.getByRole("button", { name: "그리기" }).getAttribute("aria-pressed")).toBe("true");
+  expect(toolbar.getByRole("button", { name: "선택" }).getAttribute("aria-pressed")).toBe("false");
+});
+
+test("creation is transient until release, scales coordinates and selects the result with one undo step", () => {
+  const { svg, value, editor, commits } = setup();
+  fireEvent.click(screen.getByRole("button", { name: "사각형" }));
+  fireEvent.pointerDown(svg, event(40, 50));
+  fireEvent.pointerMove(svg, event(140, 100));
+  expect(value()).toEqual(blank); expect(commits).not.toHaveBeenCalled();
+  fireEvent.pointerUp(svg, event(140, 100));
+  expect(value().objects[0]).toMatchObject({ kind: "rectangle", x: 80, y: 100, width: 200, height: 100 });
+  expect(editor.snapshot.selection.keys).toEqual(["object-1"]);
+  expect(svg.getAttribute("data-tool")).toBe("select");
+  expect(commits).toHaveBeenCalledTimes(1);
+  fireEvent.click(screen.getByRole("button", { name: "실행 취소" })); expect(value()).toEqual(blank);
+  fireEvent.click(screen.getByRole("button", { name: "다시 실행" })); expect(value().objects).toHaveLength(1);
+});
+
+test.each(["escape", "pointercancel", "lostpointercapture"])("%s cancels creation without a commit or history", (reason) => {
+  const { svg, value, editor } = setup();
+  fireEvent.click(screen.getByRole("button", { name: "타원" }));
+  fireEvent.pointerDown(svg, event(40, 50)); fireEvent.pointerMove(svg, event(140, 100));
+  if (reason === "escape") fireEvent.keyDown(svg, { key: "Escape" });
+  else if (reason === "pointercancel") fireEvent.pointerCancel(svg, event(140, 100));
+  else fireEvent.lostPointerCapture(svg, event(140, 100));
+  fireEvent.pointerUp(svg, event(140, 100));
+  expect(value()).toEqual(blank); expect(editor.snapshot.canUndo).toBe(false);
+});
+
+test("move and resize share preview geometry, cancel safely and commit exactly once", () => {
+  const { svg, value, commits, container } = setup(); rectangle(svg);
+  const target = container.querySelector("[data-canvas-object]")!;
+  const before = value(); commits.mockClear();
+  fireEvent.pointerDown(target, event(70, 70)); fireEvent.pointerMove(window, event(100, 100));
+  expect(value()).toBe(before);
+  fireEvent.keyDown(svg, { key: "Escape" }); fireEvent.pointerUp(window, event(100, 100));
+  expect(value()).toBe(before); expect(commits).not.toHaveBeenCalled();
+  fireEvent.pointerDown(target, event(70, 70)); fireEvent.pointerMove(window, event(100, 100)); fireEvent.pointerUp(window, event(100, 100));
+  expect(value().objects[0]).toMatchObject({ x: 140, y: 160 }); expect(commits).toHaveBeenCalledTimes(1);
+  const handle = container.querySelector('[data-resize-edge="se"]')!;
+  fireEvent.pointerDown(handle, event(170, 130)); fireEvent.pointerMove(window, event(200, 160));
+  expect(value().objects[0]).toMatchObject({ width: 200, height: 100 });
+  fireEvent.pointerUp(window, event(200, 160));
+  expect(value().objects[0]).toMatchObject({ width: 260, height: 160 }); expect(commits).toHaveBeenCalledTimes(2);
+});
+
+test("text draft supports IME, cancellation and one commit without capturing native editing shortcuts", () => {
+  const { svg, value, commits, container } = setup();
+  fireEvent.click(screen.getByRole("button", { name: "글자" }));
+  fireEvent.pointerDown(svg, event(40, 50)); fireEvent.pointerUp(svg, event(40, 50));
+  const input = screen.getByRole("textbox", { name: "Canvas text" });
+  fireEvent.change(input, { target: { value: "안녕하세요\nSlide" } });
+  fireEvent.keyDown(input, { key: "Enter", ctrlKey: true, isComposing: true });
+  expect(value().objects[0]!.label).toBe("Text");
+  fireEvent.keyDown(input, { key: "Enter", ctrlKey: true });
+  expect(value().objects[0]!.label).toBe("안녕하세요\nSlide"); expect(commits).toHaveBeenCalledTimes(2);
+  fireEvent.doubleClick(container.querySelector("[data-canvas-object]")!);
+  fireEvent.change(screen.getByRole("textbox", { name: "Canvas text" }), { target: { value: "Discard" } });
+  fireEvent.keyDown(screen.getByRole("textbox", { name: "Canvas text" }), { key: "Escape" });
+  expect(value().objects[0]!.label).toBe("안녕하세요\nSlide"); expect(commits).toHaveBeenCalledTimes(2);
+  fireEvent.keyDown(svg, { key: "z", metaKey: true }); expect(value().objects[0]!.label).toBe("Text");
+});
+
+test("drawing samples are transient and a foreign pointer cannot finish the gesture", () => {
+  const { svg, value, commits } = setup();
+  fireEvent.click(screen.getByRole("button", { name: "그리기" }));
+  fireEvent.pointerDown(svg, event(20, 20));
+  fireEvent.pointerMove(svg, event(40, 60)); fireEvent.pointerMove(svg, event(100, 70));
+  fireEvent.pointerUp(svg, event(120, 80, 9)); expect(value().objects).toHaveLength(0);
+  fireEvent.pointerUp(svg, event(120, 80));
+  expect(value().objects[0]).toMatchObject({ kind: "path", x: 40, y: 40, width: 200, height: 120 }); expect(commits).toHaveBeenCalledTimes(1);
+});
+
+test("invalid JSON leaves document/history intact; reopening the saved JSON restores the slide", () => {
+  const { svg, value, editor } = setup(); rectangle(svg);
+  fireEvent.click(screen.getByRole("button", { name: "JSON" }));
+  const field = screen.getByRole("textbox", { name: "Canvas JSON document" });
+  const saved = (field as HTMLTextAreaElement).value, before = editor.snapshot;
+  fireEvent.change(field, { target: { value: '{"profile":"canvas/1","objects":[]}' } });
+  fireEvent.click(screen.getByRole("button", { name: "JSON 열기" }));
+  expect(screen.getByRole("alert")).toBeTruthy(); expect(editor.snapshot).toEqual(before);
+  fireEvent.click(screen.getByRole("button", { name: "삭제" })); expect(value().objects).toHaveLength(0);
+  fireEvent.change(field, { target: { value: saved } });
+  fireEvent.click(screen.getByRole("button", { name: "JSON 열기" }));
+  expect(value()).toEqual(JSON.parse(saved)); expect(editor.snapshot.selection.keys).toEqual([]);
+});
+
+test("external replacement cancels an in-flight transform and unmount releases pointer continuation", () => {
+  const { svg, container, source, value, unmount, commits } = setup(); rectangle(svg);
+  fireEvent.pointerDown(container.querySelector("[data-canvas-object]")!, event(70, 70));
+  fireEvent.pointerMove(window, event(90, 90));
+  act(() => { source.commit([{ op: "replace", path: "/objects/0/x", value: 999 }]); });
+  fireEvent.pointerUp(window, event(100, 100)); expect(value().objects[0]!.x).toBe(999);
+  fireEvent.pointerDown(container.querySelector("[data-canvas-object]")!, event(70, 70));
+  commits.mockClear(); unmount();
+  const end = new PointerEvent("pointerup", { ...event(100, 100) });
+  const observer = vi.fn(); window.addEventListener("pointerup", observer);
+  window.dispatchEvent(end); window.removeEventListener("pointerup", observer);
+  expect(observer).toHaveBeenCalled(); expect(commits).not.toHaveBeenCalled();
+});
diff --git a/packages/json-document-canvas/tsconfig.json b/packages/json-document-canvas/tsconfig.json
new file mode 100644
index 00000000..36205524
--- /dev/null
+++ b/packages/json-document-canvas/tsconfig.json
@@ -0,0 +1,10 @@
+{
+  "extends": "../../tsconfig/library-react.json",
+  "compilerOptions": { "rootDir": "src", "outDir": "dist", "tsBuildInfoFile": "dist/.tsbuildinfo" },
+  "references": [
+    { "path": "../json-document-object-document" }, { "path": "../json-document-editing" },
+    { "path": "../json-document-affordance" }, { "path": "../json-document-web" },
+    { "path": "../json-document-react" }, { "path": "../json-document-ui-primitives-react" }
+  ],
+  "include": ["src/**/*.ts", "src/**/*.tsx"]
+}
diff --git a/packages/json-document-canvas/tsconfig.test.json b/packages/json-document-canvas/tsconfig.test.json
new file mode 100644
index 00000000..7850a9a2
--- /dev/null
+++ b/packages/json-document-canvas/tsconfig.test.json
@@ -0,0 +1,5 @@
+{
+  "extends": ["./tsconfig.json", "../../tsconfig/test-dom.json"],
+  "compilerOptions": { "rootDir": "../.." },
+  "include": ["src/**/*.ts", "src/**/*.tsx", "tests/**/*.ts", "tests/**/*.tsx", "vitest.config.ts"]
+}
diff --git a/packages/json-document-canvas/vitest.config.ts b/packages/json-document-canvas/vitest.config.ts
new file mode 100644
index 00000000..ecec11aa
--- /dev/null
+++ b/packages/json-document-canvas/vitest.config.ts
@@ -0,0 +1,7 @@
+import react from "@vitejs/plugin-react";
+import { defineDOMReactProject } from "../../test/vitest.shared.js";
+import { jsonDocumentSourceAliases } from "../../site/config/json-document-source-aliases.js";
+
+export default defineDOMReactProject("json-document-canvas", {
+  plugins: [react()], resolve: { alias: jsonDocumentSourceAliases(), dedupe: ["react", "react-dom"] },
+});
diff --git a/packages/json-document-editing/package.json b/packages/json-document-editing/package.json
index f90d073a..4f8c8546 100644
--- a/packages/json-document-editing/package.json
+++ b/packages/json-document-editing/package.json
@@ -34,11 +34,13 @@
     "verify": "npm run typecheck && npm test && npm run build"
   },
   "peerDependencies": {
+    "@interactive-os/json-document-object-document": ">=0.1.0-rc.0 <1",
     "@interactive-os/json-document-calendar-document": "^0.1.0-rc.0",
     "@interactive-os/json-document": "^3.0.0",
     "@interactive-os/json-document-selection": "^0.1.0-rc.0"
   },
   "devDependencies": {
+    "@interactive-os/json-document-object-document": "*",
     "@interactive-os/json-document-calendar-document": "*",
     "@interactive-os/json-document": "*",
     "@interactive-os/json-document-selection": "*",
diff --git a/packages/json-document-editing/src/object-validation.ts b/packages/json-document-editing/src/object-validation.ts
deleted file mode 100644
index cac5fa94..00000000
--- a/packages/json-document-editing/src/object-validation.ts
+++ /dev/null
@@ -1,12 +0,0 @@
-import type { ObjectDocument } from "./object.js";
-
-export function assertObjectDocument(document: ObjectDocument): void {
-  const ids = new Set<string>();
-  for (const object of document.objects) {
-    if (object.id.length === 0) throw new Error("Object ids must not be empty.");
-    if (ids.has(object.id)) throw new Error(`Object id must be unique: ${JSON.stringify(object.id)}.`);
-    if (![object.x, object.y, object.width, object.height].every(Number.isFinite)) throw new Error(`Object geometry must be finite: ${JSON.stringify(object.id)}.`);
-    if (object.width < 0 || object.height < 0) throw new Error(`Object dimensions must not be negative: ${JSON.stringify(object.id)}.`);
-    ids.add(object.id);
-  }
-}
diff --git a/packages/json-document-editing/src/object.ts b/packages/json-document-editing/src/object.ts
index 37f488e0..9c7ff1f9 100644
--- a/packages/json-document-editing/src/object.ts
+++ b/packages/json-document-editing/src/object.ts
@@ -1,6 +1,4 @@
 import {
-  buildPointer,
-  type JSONPatchOperation,
   type JSONValue,
 } from "@interactive-os/json-document";
 import {
@@ -17,21 +15,11 @@ import { resolveDocumentSource, type EditingDocumentSource } from "./document-so
 import { createEditingId, createEditingIdAllocator } from "./identity.js";
 import type { EditingHistoryOptions } from "./history.js";
 import { cutEditingClipboard, isClipboardRecord } from "./clipboard.js";
-import { assertObjectDocument } from "./object-validation.js";
-
-export interface DocumentObject extends Record<string, JSONValue> {
-  readonly id: string;
-  readonly label: string;
-  readonly x: number;
-  readonly y: number;
-  readonly width: number;
-  readonly height: number;
-  readonly color: string;
-}
-
-export interface ObjectDocument extends Record<string, JSONValue> {
-  readonly objects: ReadonlyArray<DocumentObject>;
-}
+import {
+  assertObjectDocument, planObjectOperation, transformObject,
+  type DocumentObject, type ObjectDocument, type ObjectDraft, type ObjectOperation,
+} from "@interactive-os/json-document-object-document";
+export type { DocumentObject, ObjectDocument } from "@interactive-os/json-document-object-document";
 
 export interface ObjectSelection extends Record<string, JSONValue> {
   readonly kind: "explicit";
@@ -50,16 +38,9 @@ export interface ObjectClipboard extends Record<string, JSONValue> {
 export const objectClipboardFormat = {
   mimeType: "application/vnd.interactive-os.objects+json" as const,
   parse(value: unknown): ObjectClipboard | null {
-    return isClipboardRecord(value)
-      && value.type === this.mimeType
-      && typeof value.text === "string"
-      && Array.isArray(value.objects)
-      && value.objects.every((item) => isClipboardRecord(item)
-        && typeof item.id === "string" && typeof item.label === "string"
-        && typeof item.x === "number" && typeof item.y === "number"
-        && typeof item.width === "number" && typeof item.height === "number"
-        && typeof item.color === "string")
-      ? value as ObjectClipboard : null;
+    if (!isClipboardRecord(value) || value.type !== this.mimeType || typeof value.text !== "string") return null;
+    if (!Array.isArray(value.objects) || value.objects.some((object) => !isClipboardRecord(object) || typeof object.color !== "string")) return null;
+    try { assertObjectDocument(value); return value as ObjectClipboard; } catch { return null; }
   },
 };
 
@@ -70,6 +51,9 @@ export interface ObjectPastePlacement {
 }
 
 export type ObjectIntent =
+  | { readonly type: "object.create"; readonly object: ObjectDraft }
+  | { readonly type: "object.text"; readonly objectId: string; readonly text: string }
+  | { readonly type: "document.replace"; readonly document: ObjectDocument }
   | {
       readonly type: "selection.set";
       readonly objectIds: ReadonlyArray<string>;
@@ -147,6 +131,21 @@ export function createObjectEditor(
   }
 
   function dispatch(intent: ObjectIntent): EditingResult<ObjectSelection> {
+    if (intent.type === "object.create") {
+      const allocate = createEditingIdAllocator(value().objects.map((object) => object.id), createId, "object");
+      let id: string;
+      try { id = allocate(); } catch (error) { return { ok: false, code: "object.identity-unavailable", reason: error instanceof Error ? error.message : String(error) }; }
+      const object = { ...intent.object, id };
+      return apply({ type: "insert", objects: [object] }, selectionFor([object.id]), intent.type);
+    }
+    if (intent.type === "object.text") {
+      return apply({ type: "text", objectId: intent.objectId, text: intent.text }, selectionFor([intent.objectId]), intent.type);
+    }
+    if (intent.type === "document.replace") {
+      // A profile-specific session cannot silently become another document type.
+      if (value().profile !== intent.document?.profile) return failure("object.profile-mismatch");
+      return apply({ type: "replace", document: intent.document }, selectionFor([]), intent.type);
+    }
     if (intent.type === "selection.set") {
       const available = new Set(value().objects.map((object) => object.id));
       if (intent.objectIds.some((id) => !available.has(id))) {
@@ -168,83 +167,36 @@ export function createObjectEditor(
     }
 
     if (intent.type === "object.translate") {
-      const objects = value().objects;
-      const moving = new Set(intent.objectIds);
-      if (intent.objectIds.some((id) => !objects.some((object) => object.id === id))) {
-        return failure("selection.object-not-found");
-      }
-      return session.apply({
-        operations: objects.flatMap((object, index) => {
-          if (!moving.has(object.id)) return [];
-          return [
-            { op: "replace", path: buildPointer(["objects", index, "x"]), value: object.x + intent.dx },
-            { op: "replace", path: buildPointer(["objects", index, "y"]), value: object.y + intent.dy },
-          ];
-        }),
-        selectionAfter: selectionFor(intent.objectIds),
-        origin: intent.type,
-      });
+      return apply({ type: "transform", objectIds: intent.objectIds, transform: { dx: intent.dx, dy: intent.dy } }, selectionFor(intent.objectIds), intent.type);
     }
 
     if (intent.type === "object.resize") {
-      const objects = value().objects;
-      const resizing = new Set(intent.objectIds);
-      if (intent.objectIds.some((id) => !objects.some((object) => object.id === id))) {
-        return failure("selection.object-not-found");
-      }
-      return session.apply({
-        operations: objects.flatMap((object, index) => {
-          if (!resizing.has(object.id)) return [];
-          const width = Math.max(1, object.width + intent.dw);
-          const height = Math.max(1, object.height + intent.dh);
-          return [
-            { op: "replace", path: buildPointer(["objects", index, "x"]), value: object.x + intent.dx },
-            { op: "replace", path: buildPointer(["objects", index, "y"]), value: object.y + intent.dy },
-            { op: "replace", path: buildPointer(["objects", index, "width"]), value: width },
-            { op: "replace", path: buildPointer(["objects", index, "height"]), value: height },
-          ];
-        }),
-        selectionAfter: selectionFor(intent.objectIds),
-        origin: intent.type,
-      });
+      return apply({ type: "transform", objectIds: intent.objectIds, transform: { dx: intent.dx, dy: intent.dy, dw: intent.dw, dh: intent.dh } }, selectionFor(intent.objectIds), intent.type);
     }
 
     if (intent.type === "clipboard.paste") {
       const objects = value().objects;
-      const pasted = cloneObjectsWithUniqueIds(intent.clipboard.objects, objects, createId).map((object) => ({
-        ...object,
-        x: object.x + (intent.placement?.dx ?? 0),
-        y: object.y + (intent.placement?.dy ?? 0),
-      }));
+      if (!objectClipboardFormat.parse(intent.clipboard)) return failure("clipboard.invalid");
+      const dx = intent.placement?.dx ?? 0, dy = intent.placement?.dy ?? 0;
+      if (![dx, dy].every(Number.isFinite)) return failure("object.invalid");
+      const pasted = cloneObjectsWithUniqueIds(intent.clipboard.objects, objects, createId)
+        .map((object) => transformObject(object, { dx, dy }));
       if (pasted.length === 0) return failure("clipboard.empty");
-      return session.apply({
-        operations: pasted.map((object, offset) => ({
-          op: "add",
-          path: `/objects/${objects.length + offset}`,
-          value: object,
-        })),
-        selectionAfter: selectionFor(pasted.map((object) => object.id)),
-        origin: intent.type,
-      });
+      return apply({ type: "insert", objects: pasted }, selectionFor(pasted.map((object) => object.id)), intent.type);
     }
 
     const selected = selectedObjects();
     if (selected.length === 0) return failure("selection.empty");
     if (intent.type === "selection.fill") {
-      const objects = value().objects;
-      const operations: JSONPatchOperation[] = selected.map((object) => ({
-        op: "replace",
-        path: buildPointer(["objects", objects.findIndex((candidate) => candidate.id === object.id), "color"]),
-        value: intent.color,
-      }));
-      return session.apply({
-        operations,
-        selectionAfter: session.snapshot.selection,
-        origin: intent.type,
-      });
+      return apply({ type: "fill", objectIds: selected.map((object) => object.id), color: intent.color }, session.snapshot.selection, intent.type);
     }
 
-    return removeSelected(selected.map((object) => object.id));
+    return intent.type === "selection.remove" ? removeSelected(selected.map((object) => object.id)) : failure("object.unsupported-intent");
+  }
+
+  function apply(operation: ObjectOperation, selectionAfter: ObjectSelection, origin: string): EditingResult<ObjectSelection> {
+    const plan = planObjectOperation(value(), operation);
+    return plan.ok ? session.apply({ operations: plan.operations, selectionAfter, origin }) : plan;
   }
 
   function copy(): ObjectClipboard | null {
@@ -268,11 +220,7 @@ export function createObjectEditor(
     const remaining = objects.filter((object) => !selectedIds.has(object.id));
     const firstRemoved = Math.min(...indices);
     const next = remaining[Math.min(firstRemoved, remaining.length - 1)];
-    return session.apply({
-      operations: indices.map((index) => ({ op: "remove", path: buildPointer(["objects", index]) })),
-      selectionAfter: selectionFor(next ? [next.id] : []),
-      origin: "selection.remove",
-    });
+    return apply({ type: "remove", objectIds: ids }, selectionFor(next ? [next.id] : []), "selection.remove");
   }
 
   return {
diff --git a/packages/json-document-editing/tests/canvas-profile.test.ts b/packages/json-document-editing/tests/canvas-profile.test.ts
new file mode 100644
index 00000000..26b7279a
--- /dev/null
+++ b/packages/json-document-editing/tests/canvas-profile.test.ts
@@ -0,0 +1,71 @@
+import { expect, test } from "vitest";
+import { createJSONDocument } from "@interactive-os/json-document";
+import { createCanvasObject, createCanvasPath, parseCanvasDocument, serializeCanvasDocument, type CanvasDocument } from "@interactive-os/json-document-object-document";
+import { createObjectEditor, type ObjectIntent } from "../src/index.js";
+
+const blank: CanvasDocument = { profile: "canvas/1", width: 1280, height: 720, objects: [] };
+const text = createCanvasObject("text", { x: 10, y: 20, width: 200, height: 100 }, { color: "black", label: "Text" });
+
+test("Canvas creation, direct text edit, transform and deletion use the existing selection-restoring history", () => {
+  const source = createJSONDocument(blank);
+  let commits = 0;
+  source.subscribe(() => commits++);
+  const editor = createObjectEditor(source, { createId: () => "a" });
+  expect(editor.dispatch({ type: "object.create", object: text }).ok).toBe(true);
+  expect(editor.snapshot.selection.keys).toEqual(["a"]);
+  expect(commits).toBe(1);
+  expect(editor.dispatch({ type: "object.text", objectId: "a", text: "A slide\n한 장" }).ok).toBe(true);
+  expect(commits).toBe(2);
+  const written = editor.snapshot.value;
+  expect(editor.dispatch({ type: "object.resize", objectIds: ["a"], dx: 10, dy: 10, dw: 100, dh: 50 }).ok).toBe(true);
+  expect(commits).toBe(3);
+  expect(editor.undo().ok).toBe(true);
+  expect(editor.snapshot.value).toEqual(written);
+  expect(editor.snapshot.selection.keys).toEqual(["a"]);
+  editor.redo();
+  const resized = editor.snapshot.value;
+  editor.dispatch({ type: "selection.remove" });
+  expect(editor.snapshot.value).toEqual(blank);
+  editor.undo();
+  expect(editor.snapshot.value).toEqual(resized);
+  expect(editor.snapshot.selection.keys).toEqual(["a"]);
+});
+
+test("invalid imports and mutations leave document, selection, revision and history untouched", () => {
+  const editor = createObjectEditor(blank, { createId: () => "a" });
+  editor.dispatch({ type: "object.create", object: text });
+  for (const intent of [
+    { type: "object.create", object: { ...text, width: -10 } },
+    { type: "object.translate", objectIds: ["a"], dx: Infinity, dy: 0 },
+    { type: "document.replace", document: { ...blank, objects: [{ ...text, id: "bad", kind: "unknown" }] } },
+    { type: "document.replace", document: { objects: [] } },
+    { type: "unsupported" },
+  ]) {
+    const before = editor.snapshot;
+    expect(editor.dispatch(intent as ObjectIntent).ok).toBe(false);
+    expect(editor.snapshot).toEqual(before);
+  }
+});
+
+test("JSON reopening is one undoable transaction, keeps IDs and clears only transient selection", () => {
+  const editor = createObjectEditor(blank);
+  const saved: CanvasDocument = { ...blank, objects: [{ ...createCanvasPath([{ x: 1, y: 2 }, { x: 40, y: 70 }], { color: "black", label: "Path", strokeWidth: 3 }), id: "p" }] };
+  expect(editor.dispatch({ type: "document.replace", document: parseCanvasDocument(serializeCanvasDocument(saved)) }).ok).toBe(true);
+  expect(editor.snapshot.value).toEqual(saved);
+  expect(editor.snapshot.selection.keys).toEqual([]);
+  editor.undo(); expect(editor.snapshot.value).toEqual(blank);
+  editor.redo(); expect(editor.snapshot.value).toEqual(saved);
+  const next = createObjectEditor(parseCanvasDocument(serializeCanvasDocument(editor.snapshot.value as CanvasDocument)));
+  expect(next.snapshot.value).toEqual(saved);
+  expect(next.snapshot.canUndo).toBe(false);
+});
+
+test("a zero-distance gesture does not create history or clear redo", () => {
+  const editor = createObjectEditor(blank, { createId: () => "a" });
+  editor.dispatch({ type: "object.create", object: text });
+  editor.dispatch({ type: "object.text", objectId: "a", text: "Changed" });
+  editor.undo();
+  editor.dispatch({ type: "object.translate", objectIds: ["a"], dx: 0, dy: 0 });
+  expect(editor.snapshot.canRedo).toBe(true);
+  editor.undo(); expect(editor.snapshot.value).toEqual(blank);
+});
diff --git a/packages/json-document-editing/tsconfig.json b/packages/json-document-editing/tsconfig.json
index cc9545cc..17fb2dcd 100644
--- a/packages/json-document-editing/tsconfig.json
+++ b/packages/json-document-editing/tsconfig.json
@@ -6,6 +6,7 @@
     "tsBuildInfoFile": "dist/.tsbuildinfo"
   },
   "references": [
+    { "path": "../json-document-object-document" },
     { "path": "../json-document-calendar-document" },
     { "path": "../json-document" },
     { "path": "../json-document-selection" }
diff --git a/packages/json-document-object-document/LICENSE b/packages/json-document-object-document/LICENSE
new file mode 100644
index 00000000..6a984193
--- /dev/null
+++ b/packages/json-document-object-document/LICENSE
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 interactive-os contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/packages/json-document-object-document/README.md b/packages/json-document-object-document/README.md
new file mode 100644
index 00000000..3aa0a5bd
--- /dev/null
+++ b/packages/json-document-object-document/README.md
@@ -0,0 +1,24 @@
+# Object Document Type
+
+`@interactive-os/json-document-object-document`는 ID가 있는 Object 문서와
+한 장짜리 Canvas 프로파일의 모델·검증·의미 연산·projection을 소유합니다.
+Core만 의존하며 Editing, Selection, React, DOM 없이 사용할 수 있습니다.
+
+```ts
+import { createJSONDocument } from "@interactive-os/json-document";
+import { parseCanvasDocument, planObjectOperation, serializeCanvasDocument } from "@interactive-os/json-document-object-document";
+
+const value = parseCanvasDocument('{"profile":"canvas/1","width":1280,"height":720,"objects":[]}');
+const document = createJSONDocument(value);
+const plan = planObjectOperation(value, { type: "insert", objects: [
+  { id: "title", kind: "text", x: 80, y: 80, width: 640, height: 96, label: "Hello", color: "#253044", fontSize: 48 },
+] });
+if (plan.ok) document.commit(plan.operations);
+serializeCanvasDocument(parseCanvasDocument(JSON.stringify(document.value)));
+```
+
+편집은 `createObjectEditor`, React 제품은 `CanvasHand`를 조합합니다.
+기존 Editing의 `ObjectDocument`/`DocumentObject` export는 같은 타입을 가리키는
+호환 경로입니다. RC이며 안정된 wire 표준이나 PPTX 지원을 선언하지 않습니다.
+
+[API와 프로파일 계약](docs/api.md) · [Usage 및 Source](https://developer-1px.github.io/json-document/docs/api/canvas)
diff --git a/packages/json-document-object-document/docs/api.md b/packages/json-document-object-document/docs/api.md
new file mode 100644
index 00000000..e6b2df22
--- /dev/null
+++ b/packages/json-document-object-document/docs/api.md
@@ -0,0 +1,64 @@
+## Object Document Type 계약 · RC
+
+소유자는 `@interactive-os/json-document-object-document`입니다. Object의 값과
+의미를 정의하며 선택·ID 할당·Intent·History는 Editing이, 사람의 조작은 Canvas
+Hand가 소유합니다. 기존 Editing 타입 export는 같은 정본 타입의 호환 경로입니다.
+
+### 모델과 Canvas 프로파일
+
+`ObjectDocument.objects`는 뒤에 있는 객체가 위에 그려지는 ordered collection입니다.
+`DocumentObject`의 id는 고유한 비어 있지 않은 문자열, label과 color는 문자열,
+x/y/width/height는 유한수이며 width/height는 음수가 아닙니다. 예전처럼 kind가 없는
+Object도 계속 유효합니다. legacy Object의 생략된 color는 계속 수용하지만 잘못된
+타입은 거절합니다. 이 호환성 때문에 `assertObjectDocument`는 필수 필드 충족을
+주장하는 TypeScript type guard가 아닙니다. Canvas에서는 color가 필수입니다.
+`projectObject`는 legacy Object를 rectangle으로 읽으며 저장값을 바꾸지 않습니다.
+
+`CanvasDocument`는 같은 모델에 `profile: "canvas/1"`, 양의 유한수 width/height와
+명시적인 kind를 추가한 단일 슬라이드 프로파일입니다. 같은 책임의 두 번째 객체
+모델이 아닙니다. 객체 크기도 양수여야 합니다.
+
+| kind | 추가 문서 값 | 표현 |
+| --- | --- | --- |
+| text | 양의 유한수 fontSize | label이 실제 내용인 plain text. 별도의 text 복사본 없음 |
+| rectangle | 없음 | color로 채운 사각형 |
+| ellipse | 없음 | 경계 상자에 내접하는 타원 |
+| path | points, 양의 유한수 strokeWidth | color로 그린 열린 선 |
+
+path points는 최소 두 개의 `{ x, y }`이며 각 좌표는 `[0, 1]`입니다. 경계 상자에
+대한 정규화 좌표이므로 이동·resize는 상자만 바꾸고 점과 strokeWidth를 보존합니다.
+`createCanvasPath`는 슬라이드 좌표의 점을 이 표현으로 변환합니다. 수평·수직 선의
+퇴화한 축은 최소 1 단위의 상자로 표현합니다. `createCanvasObject`는 도형/글자 초안을
+만들며 ID는 Editing의 `object.create`에서 할당합니다.
+
+### 검증과 직렬화
+
+`assertObjectDocument`/`assertCanvasDocument`는 구조 위반 시 TypeError를 던집니다.
+`parseCanvasDocument`는 JSON과 프로파일을 검증한 독립된 immutable 값을 반환하고,
+`serializeCanvasDocument`는 같은 검증 후 JSON 문자열을 반환합니다. 잘못된 root,
+중복 ID, 알 수 없는 kind/profile, 잘못된 수치나 path를 조용히 보정하지 않습니다.
+일반 JSON 확장 필드는 보존합니다. tool·selection·focus·preview·history는 프로파일
+필드가 아니며 Hand가 문서에 넣지 않습니다.
+
+### 의미 연산과 projection
+
+`planObjectOperation(document, operation)`은 insert, transform, fill, remove,
+text, replace를 검증된 JSON Patch로 계획합니다. 성공은 `{ ok: true, operations }`,
+실패는 `{ ok: false, code, reason? }`입니다. 계획은 입력을 변경하거나 commit하지
+않으며 선택과 History를 알지 못합니다. 없는 대상·중복 ID·유효하지 않은 결과는
+전체 거절합니다. no-op는 빈 operations를 반환합니다.
+
+`transformObject`는 preview와 commit의 같은 기하 규칙입니다. translate는 크기를
+유지하고 resize는 결과 크기를 최소 1로 제한합니다. Canvas Hand는 현재 모서리가
+반대쪽을 통과해도 뒤집지 않습니다. 화면 바깥 좌표는 허용하며 Hand가 슬라이드 밖을
+clip합니다. 위치를 자동 보정하거나 snap하지 않습니다.
+
+### Usage와 남은 범위
+
+[Canvas Hand의 실제 Usage/Source](/docs/api/canvas)와 [Object Editing](/docs/object)가
+정본을 소비합니다. [Object 소유권 감사](/docs/document-types/object)는 영향을 받는
+모델·연산·Editing·Hand·두 Canvas Host의 소유자를 기록합니다.
+
+페이지·줌·팬·다중 선택 UI·그룹·회전·정렬·snap·레이어 패널·PPTX·협업은 이
+Canvas slice 범위 밖입니다. 이 RC 프로파일은 독립 구현 간 Stable wire conformance를
+선언하지 않습니다. Annotation의 source/selector/body 모델도 Canvas에 통합하지 않습니다.
diff --git a/packages/json-document-object-document/package.json b/packages/json-document-object-document/package.json
new file mode 100644
index 00000000..19ec59a1
--- /dev/null
+++ b/packages/json-document-object-document/package.json
@@ -0,0 +1,23 @@
+{
+  "name": "@interactive-os/json-document-object-document",
+  "version": "0.1.0-rc.0",
+  "description": "Object Document Type and single-slide Canvas profile: model, validation, operations and projections.",
+  "type": "module",
+  "license": "MIT",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "repository": { "type": "git", "url": "git+https://github.com/developer-1px/json-document.git", "directory": "packages/json-document-object-document" },
+  "publishConfig": { "access": "public", "provenance": true, "tag": "next" },
+  "files": ["dist", "!dist/.tsbuildinfo", "README.md", "docs", "LICENSE"],
+  "exports": { ".": { "types": "./dist/index.d.ts", "import": "./dist/index.js" } },
+  "scripts": {
+    "build": "tsc -b tsconfig.json",
+    "pretypecheck": "node ../../scripts/workspace-tasks.mjs build-dependencies",
+    "typecheck": "tsc -p tsconfig.test.json --noEmit",
+    "test": "vitest run --config vitest.config.ts",
+    "verify": "npm run typecheck && npm test && npm run build"
+  },
+  "peerDependencies": { "@interactive-os/json-document": "^3.0.0" },
+  "devDependencies": { "@interactive-os/json-document": "*", "@types/node": "^25.9.0", "typescript": "^5.0.0", "vitest": "^4.1.7" }
+}
diff --git a/packages/json-document-object-document/src/index.ts b/packages/json-document-object-document/src/index.ts
new file mode 100644
index 00000000..0b8f5783
--- /dev/null
+++ b/packages/json-document-object-document/src/index.ts
@@ -0,0 +1,4 @@
+export type { ObjectBounds, ObjectPoint, ObjectDraft, DocumentObject, ObjectDocument, CanvasObjectKind, CanvasObjectDraft, CanvasObject, CanvasDocument } from "./object-model.js";
+export { assertObjectDocument, assertCanvasDocument, parseCanvasDocument, serializeCanvasDocument } from "./object-validation.js";
+export { createCanvasObject, createCanvasPath, projectObject, transformObject, type ObjectTransform } from "./object-projection.js";
+export { planObjectOperation, type ObjectOperation, type ObjectOperationPlan } from "./object-operation.js";
diff --git a/packages/json-document-object-document/src/object-model.ts b/packages/json-document-object-document/src/object-model.ts
new file mode 100644
index 00000000..229ab7af
--- /dev/null
+++ b/packages/json-document-object-document/src/object-model.ts
@@ -0,0 +1,45 @@
+import type { JSONValue } from "@interactive-os/json-document";
+
+export interface ObjectBounds {
+  readonly x: number;
+  readonly y: number;
+  readonly width: number;
+  readonly height: number;
+}
+
+export interface ObjectPoint extends Record<string, JSONValue> {
+  readonly x: number;
+  readonly y: number;
+}
+
+export interface ObjectDraft extends ObjectBounds, Record<string, JSONValue> {
+  readonly label: string;
+  readonly color: string;
+}
+
+/** The original Object shape remains valid; a missing kind is a labelled rectangle. */
+export interface DocumentObject extends ObjectDraft {
+  readonly id: string;
+}
+
+export interface ObjectDocument extends Record<string, JSONValue> {
+  readonly objects: ReadonlyArray<DocumentObject>;
+}
+
+export type CanvasObjectKind = "text" | "rectangle" | "ellipse" | "path";
+
+export type CanvasObjectDraft = ObjectDraft & (
+  | { readonly kind: "text"; readonly fontSize: number }
+  | { readonly kind: "rectangle" | "ellipse" }
+  | { readonly kind: "path"; readonly points: ReadonlyArray<ObjectPoint>; readonly strokeWidth: number }
+);
+
+export type CanvasObject = CanvasObjectDraft & { readonly id: string };
+
+/** A fixed, single-slide profile of ObjectDocument, not a parallel object model. */
+export interface CanvasDocument extends ObjectDocument {
+  readonly profile: "canvas/1";
+  readonly width: number;
+  readonly height: number;
+  readonly objects: ReadonlyArray<CanvasObject>;
+}
diff --git a/packages/json-document-object-document/src/object-operation.ts b/packages/json-document-object-document/src/object-operation.ts
new file mode 100644
index 00000000..e0aa6c9e
--- /dev/null
+++ b/packages/json-document-object-document/src/object-operation.ts
@@ -0,0 +1,58 @@
+import { applyPatch, buildPointer, jsonEqual, type JSONPatchOperation } from "@interactive-os/json-document";
+import type { DocumentObject, ObjectDocument } from "./object-model.js";
+import { transformObject, type ObjectTransform } from "./object-projection.js";
+import { assertObjectDocument } from "./object-validation.js";
+
+export type ObjectOperation =
+  | { readonly type: "insert"; readonly objects: ReadonlyArray<DocumentObject> }
+  | { readonly type: "transform"; readonly objectIds: ReadonlyArray<string>; readonly transform: ObjectTransform }
+  | { readonly type: "fill"; readonly objectIds: ReadonlyArray<string>; readonly color: string }
+  | { readonly type: "remove"; readonly objectIds: ReadonlyArray<string> }
+  | { readonly type: "text"; readonly objectId: string; readonly text: string }
+  | { readonly type: "replace"; readonly document: ObjectDocument };
+
+export type ObjectOperationPlan =
+  | { readonly ok: true; readonly operations: ReadonlyArray<JSONPatchOperation> }
+  | { readonly ok: false; readonly code: string; readonly reason?: string };
+
+/** Pure, atomic semantic planner. No selection, identity allocation, history or input lifecycle. */
+export function planObjectOperation(document: ObjectDocument, operation: ObjectOperation): ObjectOperationPlan {
+  try {
+    assertObjectDocument(document);
+    const objects = document.objects;
+    const operations: JSONPatchOperation[] = [];
+    if (operation.type === "replace") {
+      assertObjectDocument(operation.document);
+      if (!jsonEqual(document, operation.document)) operations.push({ op: "replace", path: "", value: operation.document });
+    } else if (operation.type === "insert") {
+      operation.objects.forEach((object, index) => operations.push({ op: "add", path: `/objects/${objects.length + index}`, value: object }));
+    } else {
+      const ids = operation.type === "text" ? [operation.objectId] : operation.objectIds;
+      const targets = new Set(ids);
+      if (ids.some((id) => !objects.some((object) => object.id === id))) return { ok: false, code: "selection.object-not-found" };
+      for (let index = objects.length - 1; index >= 0; index--) {
+        const object = objects[index]!;
+        if (!targets.has(object.id)) continue;
+        if (operation.type === "remove") {
+          operations.push({ op: "remove", path: buildPointer(["objects", index]) });
+        } else if (operation.type === "transform") {
+          const next = transformObject(object, operation.transform);
+          for (const key of ["x", "y", "width", "height"] as const) {
+            if (next[key] !== object[key]) operations.push({ op: "replace", path: buildPointer(["objects", index, key]), value: next[key] });
+          }
+        } else if (operation.type === "fill") {
+          if (operation.color !== object.color) operations.push({ op: "replace", path: buildPointer(["objects", index, "color"]), value: operation.color });
+        } else if (operation.type === "text") {
+          if (object.kind !== "text") return { ok: false, code: "object.not-text" };
+          if (operation.text !== object.label) operations.push({ op: "replace", path: buildPointer(["objects", index, "label"]), value: operation.text });
+        }
+      }
+    }
+    const result = applyPatch(document, operations);
+    if (!result.ok) return result;
+    assertObjectDocument(result.value);
+    return { ok: true, operations };
+  } catch (error) {
+    return { ok: false, code: "object.invalid", reason: error instanceof Error ? error.message : String(error) };
+  }
+}
diff --git a/packages/json-document-object-document/src/object-projection.ts b/packages/json-document-object-document/src/object-projection.ts
new file mode 100644
index 00000000..ab4787e6
--- /dev/null
+++ b/packages/json-document-object-document/src/object-projection.ts
@@ -0,0 +1,54 @@
+import type { CanvasObject, CanvasObjectDraft, CanvasObjectKind, DocumentObject, ObjectBounds, ObjectPoint } from "./object-model.js";
+
+export interface ObjectTransform {
+  readonly dx: number;
+  readonly dy: number;
+  readonly dw?: number;
+  readonly dh?: number;
+}
+
+/** Shared committed/preview geometry. Path points stay normalized; resize changes only bounds. */
+export function transformObject<Object extends DocumentObject>(object: Object, transform: ObjectTransform): Object {
+  const { dx, dy, dw = 0, dh = 0 } = transform;
+  if (![dx, dy, dw, dh].every(Number.isFinite)) throw new TypeError("Object transform must be finite.");
+  const resized = transform.dw !== undefined || transform.dh !== undefined;
+  return {
+    ...object,
+    x: object.x + dx,
+    y: object.y + dy,
+    width: resized ? Math.max(1, object.width + dw) : object.width,
+    height: resized ? Math.max(1, object.height + dh) : object.height,
+  };
+}
+
+/** Legacy objects project without changing their persisted shape. Label is the only text value. */
+export function projectObject(object: DocumentObject): CanvasObject {
+  return object.kind === undefined ? { ...object, color: object.color ?? "transparent", kind: "rectangle" } : object as CanvasObject;
+}
+
+export function createCanvasObject(
+  kind: Exclude<CanvasObjectKind, "path">,
+  bounds: ObjectBounds,
+  style: { readonly color: string; readonly label: string; readonly fontSize?: number },
+): CanvasObjectDraft {
+  const base = { ...bounds, width: Math.max(1, bounds.width), height: Math.max(1, bounds.height), color: style.color, label: style.label };
+  return kind === "text" ? { ...base, kind, fontSize: style.fontSize ?? 32 } : { ...base, kind };
+}
+
+/** Converts slide-space samples to one bounding box and normalized path geometry. */
+export function createCanvasPath(
+  points: ReadonlyArray<ObjectPoint>,
+  style: { readonly color: string; readonly label: string; readonly strokeWidth: number },
+): Extract<CanvasObjectDraft, { readonly kind: "path" }> {
+  if (points.length < 2 || points.some((point) => !Number.isFinite(point.x) || !Number.isFinite(point.y))) throw new TypeError("A path requires at least two finite points.");
+  let minX = Infinity, minY = Infinity, maxX = -Infinity, maxY = -Infinity;
+  for (const point of points) {
+    minX = Math.min(minX, point.x); minY = Math.min(minY, point.y);
+    maxX = Math.max(maxX, point.x); maxY = Math.max(maxY, point.y);
+  }
+  const width = Math.max(1, maxX - minX), height = Math.max(1, maxY - minY);
+  return {
+    kind: "path", x: minX, y: minY, width, height, ...style,
+    points: points.map((point) => ({ x: (point.x - minX) / width, y: (point.y - minY) / height })),
+  };
+}
diff --git a/packages/json-document-object-document/src/object-validation.ts b/packages/json-document-object-document/src/object-validation.ts
new file mode 100644
index 00000000..52028286
--- /dev/null
+++ b/packages/json-document-object-document/src/object-validation.ts
@@ -0,0 +1,63 @@
+import { createJSONDocument, type JSONValue } from "@interactive-os/json-document";
+import type { CanvasDocument, ObjectDocument } from "./object-model.js";
+
+function record(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function finite(value: unknown): value is number {
+  return typeof value === "number" && Number.isFinite(value);
+}
+
+function positive(value: unknown): value is number {
+  return finite(value) && value > 0;
+}
+
+export function assertObjectDocument(value: unknown): void {
+  if (!record(value) || !Array.isArray(value.objects)) throw new TypeError("Object document requires an objects array.");
+  createJSONDocument(value as JSONValue);
+  const ids = new Set<string>();
+  for (const object of value.objects) {
+    if (!record(object) || typeof object.id !== "string" || object.id.length === 0) throw new TypeError("Object ids must not be empty.");
+    if (ids.has(object.id)) throw new TypeError(`Object id must be unique: ${JSON.stringify(object.id)}.`);
+    if (typeof object.label !== "string" || (object.color !== undefined && typeof object.color !== "string")) throw new TypeError("Object label and color must be strings.");
+    if (![object.x, object.y, object.width, object.height].every(finite)) throw new TypeError(`Object geometry must be finite: ${JSON.stringify(object.id)}.`);
+    if ((object.width as number) < 0 || (object.height as number) < 0) throw new TypeError(`Object dimensions must not be negative: ${JSON.stringify(object.id)}.`);
+    if (object.kind !== undefined) {
+      if (typeof object.color !== "string") throw new TypeError("Canvas objects require a color string.");
+      if (!["text", "rectangle", "ellipse", "path"].includes(object.kind as string)) throw new TypeError("Unknown Object kind.");
+      if (!positive(object.width) || !positive(object.height)) throw new TypeError("Canvas object dimensions must be positive.");
+      if (object.kind === "text" && !positive(object.fontSize)) throw new TypeError("Text fontSize must be positive and finite.");
+      if (object.kind === "path") {
+        if (!positive(object.strokeWidth) || !Array.isArray(object.points) || object.points.length < 2) throw new TypeError("Path requires a positive strokeWidth and at least two points.");
+        for (const point of object.points) {
+          if (!record(point) || !finite(point.x) || !finite(point.y) || point.x < 0 || point.x > 1 || point.y < 0 || point.y > 1) throw new TypeError("Path points must be finite normalized coordinates in [0, 1].");
+        }
+      }
+    }
+    ids.add(object.id);
+  }
+  if (value.profile === "canvas/1") assertCanvasShape(value as unknown as ObjectDocument);
+}
+
+function assertCanvasShape(value: ObjectDocument): void {
+  if (!positive(value.width) || !positive(value.height)) throw new TypeError("Canvas dimensions must be positive and finite.");
+  if (value.objects.some((object) => object.kind === undefined)) throw new TypeError("Canvas objects require an explicit kind.");
+}
+
+export function assertCanvasDocument(value: unknown): asserts value is CanvasDocument {
+  assertObjectDocument(value);
+  if (!record(value) || value.profile !== "canvas/1") throw new TypeError("Expected Canvas profile canvas/1.");
+}
+
+/** Validates the complete JSON tree as well as the profile; does not retain caller-owned values. */
+export function parseCanvasDocument(json: string): CanvasDocument {
+  const value: unknown = JSON.parse(json);
+  assertCanvasDocument(value);
+  return createJSONDocument(value).value as CanvasDocument;
+}
+
+export function serializeCanvasDocument(document: CanvasDocument): string {
+  assertCanvasDocument(document);
+  return JSON.stringify(createJSONDocument(document as JSONValue).value, null, 2);
+}
diff --git a/packages/json-document-object-document/tests/object-document.test.ts b/packages/json-document-object-document/tests/object-document.test.ts
new file mode 100644
index 00000000..b066b2da
--- /dev/null
+++ b/packages/json-document-object-document/tests/object-document.test.ts
@@ -0,0 +1,63 @@
+import { describe, expect, test } from "vitest";
+import { applyPatch } from "@interactive-os/json-document";
+import { assertCanvasDocument, assertObjectDocument, createCanvasObject, createCanvasPath, parseCanvasDocument, planObjectOperation, serializeCanvasDocument, transformObject, type CanvasDocument } from "../src/index.js";
+
+const blank: CanvasDocument = { profile: "canvas/1", width: 1280, height: 720, objects: [] };
+const text = { ...createCanvasObject("text", { x: 10, y: 20, width: 300, height: 100 }, { color: "#123456", label: "Hello\n안녕", fontSize: 36 }), id: "text" };
+const path = { ...createCanvasPath([{ x: 10, y: 20 }, { x: 40, y: 80 }, { x: 70, y: 50 }], { color: "#123456", label: "Path", strokeWidth: 4 }), id: "path" };
+
+describe("Object document and Canvas profile", () => {
+  test("round-trips every variant, order, identity and extension data without editor state", () => {
+    const document: CanvasDocument = { ...blank, title: "Slide", objects: [text, path,
+      { ...createCanvasObject("rectangle", { x: 100, y: 150, width: 80, height: 60 }, { color: "#abcdef", label: "" }), id: "rect" },
+      { ...createCanvasObject("ellipse", { x: 200, y: 150, width: 80, height: 60 }, { color: "#abcdef", label: "" }), id: "ellipse" },
+    ] };
+    expect(parseCanvasDocument(serializeCanvasDocument(document))).toEqual(document);
+    expect(Object.keys(JSON.parse(serializeCanvasDocument(blank)))).toEqual(["profile", "width", "height", "objects"]);
+  });
+
+  test.each([null, [], {}, { ...blank, objects: null }, { ...blank, width: 0 }, { ...blank, height: Infinity },
+    { ...blank, objects: [text, text] }, { ...blank, objects: [{ ...text, id: "" }] },
+    { ...blank, objects: [{ ...text, label: 1 }] }, { ...blank, objects: [{ ...text, x: NaN }] },
+    { ...blank, objects: [{ ...text, kind: "image" }] }, { ...blank, objects: [{ ...text, fontSize: 0 }] },
+    { ...blank, objects: [{ ...path, points: [{ x: 0, y: 0 }] }] }, { ...blank, objects: [{ ...path, strokeWidth: -1 }] },
+    { ...blank, objects: [{ ...path, points: [{ x: 0, y: 0 }, { x: 1.1, y: 0 }] }] },
+  ])("rejects malformed persisted state %#", (value) => expect(() => assertCanvasDocument(value)).toThrow());
+
+  test("requires a known Canvas profile but keeps legacy Object data valid", () => {
+    const legacy = { objects: [{ id: "a", x: 0, y: 0, width: 0, height: 0, label: "Alpha", color: "blue" }] };
+    expect(() => assertObjectDocument(legacy)).not.toThrow();
+    expect(() => assertCanvasDocument(legacy)).toThrow();
+    expect(() => parseCanvasDocument(JSON.stringify({ ...blank, profile: "canvas/99" }))).toThrow();
+  });
+
+  test("path normalization and resize have one geometry and identical preview/commit", () => {
+    expect(path).toMatchObject({ x: 10, y: 20, width: 60, height: 60, points: [{ x: 0, y: 0 }, { x: 0.5, y: 1 }, { x: 1, y: 0.5 }] });
+    const document = { ...blank, objects: [path] };
+    const transform = { dx: 5, dy: -2, dw: 60, dh: 30 };
+    const plan = planObjectOperation(document, { type: "transform", objectIds: ["path"], transform });
+    expect(plan.ok).toBe(true);
+    if (!plan.ok) return;
+    const result = applyPatch(document, plan.operations);
+    expect(result).toMatchObject({ ok: true, value: { objects: [transformObject(path, transform)] } });
+    expect(transformObject(path, transform).points).toEqual(path.points);
+    expect(transformObject(path, { dx: 0, dy: 0, dw: -1000, dh: -1000 })).toMatchObject({ width: 1, height: 1 });
+  });
+
+  test("vertical and horizontal strokes remain finite and resizable", () => {
+    for (const points of [[{ x: 0, y: 0 }, { x: 0, y: 100 }], [{ x: 0, y: 0 }, { x: 100, y: 0 }]]) {
+      const object = { ...createCanvasPath(points, { color: "black", label: "", strokeWidth: 2 }), id: "p" };
+      expect(() => assertCanvasDocument({ ...blank, objects: [object] })).not.toThrow();
+    }
+  });
+
+  test("planning rejects invalid/unknown targets atomically and does not emit no-op patches", () => {
+    const document = { ...blank, objects: [text] };
+    expect(planObjectOperation(document, { type: "transform", objectIds: ["text"], transform: { dx: NaN, dy: 0 } })).toMatchObject({ ok: false });
+    expect(planObjectOperation(document, { type: "transform", objectIds: ["text", "missing"], transform: { dx: 10, dy: 0 } })).toMatchObject({ ok: false });
+    expect(planObjectOperation(document, { type: "insert", objects: [text] })).toMatchObject({ ok: false });
+    expect(planObjectOperation(document, { type: "text", objectId: "text", text: text.label })).toEqual({ ok: true, operations: [] });
+    expect(planObjectOperation(document, { type: "transform", objectIds: ["text"], transform: { dx: 0, dy: 0 } })).toEqual({ ok: true, operations: [] });
+    expect(document.objects[0]).toBe(text);
+  });
+});
diff --git a/packages/json-document-object-document/tsconfig.json b/packages/json-document-object-document/tsconfig.json
new file mode 100644
index 00000000..fa193bf2
--- /dev/null
+++ b/packages/json-document-object-document/tsconfig.json
@@ -0,0 +1,6 @@
+{
+  "extends": "../../tsconfig/library.json",
+  "compilerOptions": { "rootDir": "src", "outDir": "dist", "tsBuildInfoFile": "dist/.tsbuildinfo" },
+  "references": [{ "path": "../json-document" }],
+  "include": ["src/**/*.ts"]
+}
diff --git a/packages/json-document-object-document/tsconfig.test.json b/packages/json-document-object-document/tsconfig.test.json
new file mode 100644
index 00000000..47af2477
--- /dev/null
+++ b/packages/json-document-object-document/tsconfig.test.json
@@ -0,0 +1,5 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": { "composite": false, "noEmit": true, "rootDir": "../..", "types": ["node", "vitest/globals"] },
+  "include": ["src/**/*.ts", "tests/**/*.ts", "vitest.config.ts"]
+}
diff --git a/packages/json-document-object-document/vitest.config.ts b/packages/json-document-object-document/vitest.config.ts
new file mode 100644
index 00000000..16f56974
--- /dev/null
+++ b/packages/json-document-object-document/vitest.config.ts
@@ -0,0 +1,3 @@
+import { defineNodeProject } from "../../test/vitest.shared.js";
+
+export default defineNodeProject("json-document-object-document");
diff --git a/packages/json-document-ui-primitives-react/src/controls.tsx b/packages/json-document-ui-primitives-react/src/controls.tsx
index aab99961..923c5421 100644
--- a/packages/json-document-ui-primitives-react/src/controls.tsx
+++ b/packages/json-document-ui-primitives-react/src/controls.tsx
@@ -53,12 +53,12 @@ export function Command(
 export function Toggle(
   props: Omit<ButtonHTMLAttributes<HTMLButtonElement>, "aria-pressed"> & FocusPreservingControl & ControlAffordanceProps & {
     readonly pressed: boolean;
-    readonly presentation?: "button" | "chip";
+    readonly presentation?: "button" | "chip" | "icon";
     readonly label?: string;
     readonly tooltip?: string;
   },
 ): ReactNode {
-  const { "aria-label": ariaLabel, affordance, children, label, onMouseDown, presentation = "button", preserveFocus = false, pressed, tooltip, type = "button", ...buttonProps } = props;
+  const { "aria-label": ariaLabel, affordance, children, label, onMouseDown, presentation = label ? "icon" : "button", preserveFocus = false, pressed, tooltip, type = "button", ...buttonProps } = props;
   const accessibleLabel = label ?? ariaLabel;
   const tooltipId = useId();
   const button = (
diff --git a/packages/json-document-ui-primitives-react/src/surfaces.tsx b/packages/json-document-ui-primitives-react/src/surfaces.tsx
index 082d0440..8e932449 100644
--- a/packages/json-document-ui-primitives-react/src/surfaces.tsx
+++ b/packages/json-document-ui-primitives-react/src/surfaces.tsx
@@ -1,4 +1,4 @@
-import { useRef, useState, type ButtonHTMLAttributes, type CSSProperties, type HTMLAttributes, type PointerEvent, type ReactNode, type TdHTMLAttributes } from "react";
+import { useEffect, useRef, useState, type ButtonHTMLAttributes, type CSSProperties, type HTMLAttributes, type PointerEvent, type ReactNode, type TdHTMLAttributes } from "react";
 import {
   createInteractionHandleSession,
   interactionHandleCursor,
@@ -49,6 +49,12 @@ export function useInteractionHandle<ElementType extends Element = HTMLElement>(
   const [interaction] = useState(() => createInteractionHandleSession());
   const [active, setActive] = useState(false);
   const stopNativeContinuation = useRef<(() => void) | null>(null);
+  useEffect(() => () => {
+    stopNativeContinuation.current?.();
+    const active = pointer.getSnapshot();
+    if (active) pointer.cancel(active.pointerId);
+    interaction.cancel();
+  }, [pointer, interaction]);
   const sessionActive = active || interaction.getSnapshot() !== null;
 
   function point(event: PointerEvent<ElementType>) {
diff --git a/packages/json-document-ui-primitives-react/tests/primitives.test.tsx b/packages/json-document-ui-primitives-react/tests/primitives.test.tsx
index 95e73e81..53728579 100644
--- a/packages/json-document-ui-primitives-react/tests/primitives.test.tsx
+++ b/packages/json-document-ui-primitives-react/tests/primitives.test.tsx
@@ -270,6 +270,22 @@ describe("UI Primitives", () => {
     expect(screen.getByRole("button", { name: "Details" }).getAttribute("aria-expanded")).toBe("true");
   });
 
+  test("Toggle labels default to icon presentation while text tooltips and explicit presentations remain intact", () => {
+    render(<>
+      <Toggle label="Draw" pressed><svg aria-hidden="true" /></Toggle>
+      <Toggle tooltip="Show details" pressed={false}>Details</Toggle>
+      <Toggle label="Full label" presentation="button" pressed={false}>Full label</Toggle>
+    </>);
+    const icon = screen.getByRole("button", { name: "Draw" });
+    expect(icon.getAttribute("data-ui-presentation")).toBe("icon");
+    expect(icon.getAttribute("aria-pressed")).toBe("true");
+    expect(icon.getAttribute("aria-describedby")).toBe(screen.getByRole("tooltip", { name: "Draw" }).id);
+    const text = screen.getByRole("button", { name: "Details" });
+    expect(text.getAttribute("data-ui-presentation")).toBe("button");
+    expect(text.getAttribute("aria-describedby")).toBe(screen.getByRole("tooltip", { name: "Show details" }).id);
+    expect(screen.getByRole("button", { name: "Full label" }).getAttribute("data-ui-presentation")).toBe("button");
+  });
+
   test("Command can preserve an editing surface focus during pointer activation", () => {
     render(<><div contentEditable role="textbox" /><Command preserveFocus>Format</Command></>);
     const editor = screen.getByRole("textbox");
diff --git a/site/config/json-document-source-aliases.ts b/site/config/json-document-source-aliases.ts
index dbb3dde2..c4d61b6c 100644
--- a/site/config/json-document-source-aliases.ts
+++ b/site/config/json-document-source-aliases.ts
@@ -7,6 +7,8 @@ export interface SourceAlias {
 
 export function jsonDocumentSourceAliases(): SourceAlias[] {
   return [
+    { find: "@interactive-os/json-document-object-document", replacement: sourceFile("packages/json-document-object-document/src/index.ts") },
+    { find: "@interactive-os/json-document-canvas", replacement: sourceFile("packages/json-document-canvas/src/index.ts") },
     {
       find: "@interactive-os/json-document-calendar-document",
       replacement: sourceFile("packages/json-document-calendar-document/src/index.ts"),
diff --git a/site/package.json b/site/package.json
index 8c2daf13..1bf74dd8 100644
--- a/site/package.json
+++ b/site/package.json
@@ -49,6 +49,8 @@
     "typecheck": "npm run check:ui && npm run check:icons && npm run check:primitives && npm run check:ui-roles && npm run check:choice-id && npm run check:canonical-modules && npm run check:interaction-handles && npm run check:contextual-affordance && npm run check:content-interaction && npm run check:product-shell-toolbar && npm run check:calendar-temporal && npm run check:calendar-keyboard && npm run check:calendar-rename && npm run check:calendar-viewport && npm run check:calendar-pointer-coordinate && npm run check:calendar-selection-drag && npm run check:anchored-floating-position && npm run check:calendar-year-months && npm run check:calendar-month-weeks && npm run check:calendar-period-label && npm run check:calendar-visible-date-shift && npm run check:calendar-time-label && npm run check:calendar-event-label && npm run check:calendar-interval-last-date && npm run check:calendar-date-part && npm run check:calendar-period-cells && npm run check:calendar-allday-span && npm run check:calendar-view-parser && npm run check:calendar-instant-format && npm run check:calendar-cell-interval && npm run check:calendar-date-grid && npm run check:calendar-month-grid && npm run check:calendar-time-grid && npm run check:calendar-event-inspector && npm run check:calendar-recurrence-transition && npm run check:calendar-document-calendars && npm run check:tokens && tsc -p tsconfig.json --noEmit"
   },
   "dependencies": {
+    "@interactive-os/json-document-object-document": "*",
+    "@interactive-os/json-document-canvas": "*",
     "@interactive-os/json-document-annotation": "*",
     "@a2ui/web_core": "^0.10.6",
     "@ag-ui/core": "^0.0.59",
diff --git a/site/scripts/check-content-interaction-grammar.mjs b/site/scripts/check-content-interaction-grammar.mjs
index 88de6850..f1711713 100644
--- a/site/scripts/check-content-interaction-grammar.mjs
+++ b/site/scripts/check-content-interaction-grammar.mjs
@@ -12,7 +12,7 @@ const calendarTime = read("packages/json-document-calendar/src/calendar-time-gri
 const calendarMonth = read("packages/json-document-calendar/src/calendar-month-grid.tsx");
 const database = read("packages/json-document-database/src/database-hand.tsx");
 const board = read("site/src/routes/widgets/BoardWidgetRoute.tsx");
-const canvas = read("site/src/routes/widgets/CanvasWidgetRoute.tsx");
+const canvas = read("packages/json-document-canvas/src/canvas-object-view.tsx");
 const usage = read("docs/public/ui-primitives.md");
 const sources = read("site/src/shared/demo-workbench/demo-sources.ts");
 
@@ -27,7 +27,7 @@ requireText(calendarMonth, 'role: "insertion"');
 requireText(database, "<GridCell");
 requireText(board, 'role: "drop-target"');
 requireText(board, "dragging={activeCardId === card.id}");
-requireText(canvas, "dragging={offset !== null}");
+requireText(canvas, 'contentInteractionAttributes({ role: "content", selected: props.selected, dragging: binding.active })');
 requireText(usage, "### Content interaction grammar");
 requireText(sources, 'symbol: "contentInteractionAffordance"');
 requireText(sources, 'symbol: "contentInteractionAttributes"');
diff --git a/site/scripts/check-design-tokens.mjs b/site/scripts/check-design-tokens.mjs
index c9bdaac6..eb03b3c5 100644
--- a/site/scripts/check-design-tokens.mjs
+++ b/site/scripts/check-design-tokens.mjs
@@ -7,6 +7,8 @@ const sourceRoot = path.join(siteRoot, "src");
 const tokenDefinition = path.join(sourceRoot, "app/index.css");
 const contentDataFiles = new Set([
   path.join(sourceRoot, "shared/demo-workbench/object-demo-document.ts"),
+  // These colors are serialized artwork data, not application presentation tokens.
+  path.join(sourceRoot, "shared/demo-workbench/canvas-demo-document.ts"),
 ]);
 const fixture = path.join(siteRoot, "scripts/fixtures/design-token-violation.tsx");
 
diff --git a/site/scripts/check-interaction-handles.mjs b/site/scripts/check-interaction-handles.mjs
index 0f1a7cc8..ddf54cf7 100644
--- a/site/scripts/check-interaction-handles.mjs
+++ b/site/scripts/check-interaction-handles.mjs
@@ -7,7 +7,7 @@ const sources = {
   owner: read("packages/json-document-affordance/src/interaction-handle.ts"),
   react: read("packages/json-document-ui-primitives-react/src/surfaces.tsx"),
   calendar: read("packages/json-document-calendar/src/use-calendar-pointer-interactions.ts"),
-  canvas: read("site/src/routes/canvas-demo/CanvasDemoRoute.tsx"),
+  canvas: read("packages/json-document-canvas/src/canvas-object-view.tsx"),
   database: read("packages/json-document-database/src/database-hand.tsx"),
   annotation: read("packages/json-document-annotation/src/annotation-hand.tsx"),
 };
diff --git a/site/scripts/check-product-shell-toolbar.mjs b/site/scripts/check-product-shell-toolbar.mjs
index c72f6802..48f6e21e 100644
--- a/site/scripts/check-product-shell-toolbar.mjs
+++ b/site/scripts/check-product-shell-toolbar.mjs
@@ -9,6 +9,7 @@ const usage = read("docs/public/ui-primitives.md");
 const sources = read("site/src/shared/demo-workbench/demo-sources.ts");
 const calendar = read("site/src/routes/calendar-demo/CalendarDemoRoute.tsx");
 const consumers = files("site/src/routes").map((path) => [path, read(path)]);
+const canvasConsumers = files("packages/json-document-canvas/src").map((path) => [path, read(path)]);
 const databaseConsumers = files("packages/json-document-database/src").map((path) => [path, read(path)]);
 
 for (const symbol of ["ProductShell", "ProductCanvas", "ProductInspector"]) {
@@ -29,11 +30,11 @@ requireText(calendar, 'toolbarLabel="Calendar controls"');
 requireText(calendar, '<ToolbarRegion placement="center" label="Calendar view">');
 requireText(usage, '<ToolbarRegion placement="center" label="View">');
 
-const productShellConsumers = consumers.filter(([, source]) => source.includes("<ProductShell"));
+const productShellConsumers = [...consumers, ...canvasConsumers].filter(([, source]) => source.includes("<ProductShell"));
 if (productShellConsumers.length !== 13) {
   throw new Error(`ProductShell 소비자 분모가 달라졌습니다: expected=13 actual=${productShellConsumers.length}`);
 }
-for (const [path, source] of [...consumers, ...databaseConsumers]) {
+for (const [path, source] of [...consumers, ...canvasConsumers, ...databaseConsumers]) {
   forbid(path, source, /\bProductApp\b/);
   forbid(path, source, /role=["']toolbar["']/);
 }
diff --git a/site/site-routes.json b/site/site-routes.json
index bf861945..2019cc02 100644
--- a/site/site-routes.json
+++ b/site/site-routes.json
@@ -103,9 +103,9 @@
   },
   {
     "path": "/docs/document-types/object",
-    "label": "Object · TBD",
-    "title": "Object Document Type · TBD - json-document",
-    "description": "Object의 Document Type 소유권을 확정하기 전 후보 상태와 필요한 증거를 정리합니다.",
+    "label": "Object · RC",
+    "title": "Object Document Type · RC - json-document",
+    "description": "Object와 Canvas 프로파일의 공개 소유자와 책임 감사 증거를 설명합니다.",
     "language": "ko",
     "navigationGroup": "Document Types"
   },
@@ -412,6 +412,22 @@
     "language": "ko",
     "navigationGroup": "Hands"
   },
+  {
+    "path": "/docs/api/object-document",
+    "label": "API · Object Document",
+    "title": "Object Document Type API - json-document",
+    "description": "Object와 Canvas의 문서 계약과 public API입니다.",
+    "language": "ko",
+    "navigationGroup": "Document Types"
+  },
+  {
+    "path": "/docs/api/canvas",
+    "label": "API · Canvas",
+    "title": "Canvas Hand API - json-document",
+    "description": "Canvas 입력·preview·UI 조합의 API와 Usage입니다.",
+    "language": "ko",
+    "navigationGroup": "Hands"
+  },
   {
     "path": "/docs/api/calendar-document",
     "label": "API · Calendar Document",
@@ -686,8 +702,8 @@
     "path": "/demo/canvas",
     "label": "Canvas",
     "title": "Canvas - json-document",
-    "description": "A simple minimal canvas: pick, drag, and fill objects on a plane.",
-    "parentPath": "/docs/object",
+    "description": "한 장에 글자·도형·그리기를 만들고 편집하는 Canvas 수직 슬라이스입니다.",
+    "parentPath": "/docs/api/canvas",
     "sidebar": false
   },
   {
@@ -1248,8 +1264,6 @@
     "description": "화살표로 고른 대상을 한 단위 옮기고, Shift로 큰 단위를 쓰는 손입니다.",
     "language": "ko",
     "navigationGroup": "Affordance",
-    "relatedDemoPath": "/demo/canvas",
-    "relatedDemoLabel": "증명 열기",
     "parentPath": "/docs/affordance"
   },
   {
@@ -1260,8 +1274,6 @@
     "description": "누르지 않고 포인터를 올려 손과 도움말을 드러내는 손입니다.",
     "language": "ko",
     "navigationGroup": "Affordance",
-    "relatedDemoPath": "/demo/canvas",
-    "relatedDemoLabel": "증명 열기",
     "parentPath": "/docs/affordance"
   },
   {
@@ -1304,8 +1316,6 @@
     "description": "오른쪽 클릭, Shift+F10, Menu 키로 자리 메뉴를 여는 손입니다.",
     "language": "ko",
     "navigationGroup": "Affordance",
-    "relatedDemoPath": "/demo/canvas",
-    "relatedDemoLabel": "증명 열기",
     "parentPath": "/docs/affordance"
   },
   {
@@ -1328,8 +1338,6 @@
     "description": "빈 곳에서 끌어서 여러 대상을 한 번에 고르는 손입니다.",
     "language": "ko",
     "navigationGroup": "Affordance",
-    "relatedDemoPath": "/demo/canvas",
-    "relatedDemoLabel": "증명 열기",
     "parentPath": "/docs/affordance"
   },
   {
@@ -1340,8 +1348,6 @@
     "description": "드래그한 대상을 어디에 둘지 정하고, 못 두면 no-drop을 보여주는 손입니다.",
     "language": "ko",
     "navigationGroup": "Affordance",
-    "relatedDemoPath": "/demo/canvas",
-    "relatedDemoLabel": "증명 열기",
     "parentPath": "/docs/affordance"
   },
   {
@@ -1352,8 +1358,6 @@
     "description": "Alt/Option을 누른 채 드래그하면 원본을 복제하는 손입니다.",
     "language": "ko",
     "navigationGroup": "Affordance",
-    "relatedDemoPath": "/demo/canvas",
-    "relatedDemoLabel": "증명 열기",
     "parentPath": "/docs/affordance"
   },
   {
@@ -1388,8 +1392,6 @@
     "description": "손바닥 커서로 평면을 밀고, Space+드래그로 화면을 옮기는 손입니다.",
     "language": "ko",
     "navigationGroup": "Affordance",
-    "relatedDemoPath": "/demo/canvas",
-    "relatedDemoLabel": "증명 열기",
     "parentPath": "/docs/affordance"
   },
   {
@@ -1400,8 +1402,6 @@
     "description": "휠과 드래그 중 자동 스크롤로 보이는 줄을 옮기는 손입니다.",
     "language": "ko",
     "navigationGroup": "Affordance",
-    "relatedDemoPath": "/demo/canvas",
-    "relatedDemoLabel": "증명 열기",
     "parentPath": "/docs/affordance"
   },
   {
@@ -1412,8 +1412,6 @@
     "description": "Mod+휠과 +/- 키, zoom-in/out 커서로 보이는 배율을 바꾸는 손입니다.",
     "language": "ko",
     "navigationGroup": "Affordance",
-    "relatedDemoPath": "/demo/canvas",
-    "relatedDemoLabel": "증명 열기",
     "parentPath": "/docs/affordance"
   },
   {
@@ -1424,8 +1422,6 @@
     "description": "드래그와 크기 바꾸기 중 그리드·가이드에 붙고, 수정 키로 푸는 손입니다.",
     "language": "ko",
     "navigationGroup": "Affordance",
-    "relatedDemoPath": "/demo/canvas",
-    "relatedDemoLabel": "증명 열기",
     "parentPath": "/docs/affordance"
   },
   {
@@ -1436,8 +1432,6 @@
     "description": "할 수 없는 자리에서 not-allowed와 no-drop 커서를 보여주는 손입니다.",
     "language": "ko",
     "navigationGroup": "Affordance",
-    "relatedDemoPath": "/demo/canvas",
-    "relatedDemoLabel": "증명 열기",
     "parentPath": "/docs/affordance"
   },
   {
@@ -1476,7 +1470,7 @@
     "path": "/widgets/canvas",
     "label": "Canvas proof",
     "title": "Canvas proof - json-document",
-    "description": "A canvas reads selected objects on a plane from Object selection.",
+    "description": "같은 Canvas Hand를 샘플 슬라이드와 Selection 관찰 UI에 조합합니다.",
     "parentPath": "/docs/affordance/drag",
     "sidebar": false
   },
diff --git a/site/src/app/index.css b/site/src/app/index.css
index fea41b76..847b8ee5 100644
--- a/site/src/app/index.css
+++ b/site/src/app/index.css
@@ -367,7 +367,6 @@
   [data-ui-component="contextual-controls"] :is(
     [data-ui-control="command"],
     [data-ui-control="toggle"],
-    [data-ui-control="command"][data-ui-presentation="icon"],
     [data-ui-segment="true"]
   ) {
     @apply rounded-control border-transparent bg-background-subtle/60 shadow-none hover:border-line-subtle hover:bg-background-subtle;
@@ -380,7 +379,6 @@
   [data-ui-toolbar="product"] :is(
     [data-ui-control="command"],
     [data-ui-control="toggle"],
-    [data-ui-control="command"][data-ui-presentation="icon"],
     [data-ui-segment="true"]
   ) {
     @apply rounded-control border-line-subtle/60 bg-background-canvas shadow-none hover:border-line-default hover:bg-background-canvas;
@@ -474,10 +472,14 @@
     transform: rotate(180deg);
   }
 
-  [data-ui-control="command"][data-ui-presentation="icon"] {
+  :is([data-ui-control="command"], [data-ui-control="toggle"])[data-ui-presentation="icon"] {
     @apply flex size-8 min-h-8 cursor-pointer items-center justify-center rounded-control border-0 bg-transparent p-0 text-foreground-default outline-none transition-colors hover:bg-background-subtle hover:text-foreground-strong active:bg-background-subtle focus-visible:ring-2 focus-visible:ring-line-accent/25 disabled:cursor-not-allowed disabled:bg-transparent disabled:text-foreground-muted;
   }
 
+  [data-ui-control="toggle"][data-ui-presentation="icon"][aria-pressed="true"] {
+    @apply bg-background-subtle text-foreground-strong disabled:bg-transparent disabled:text-foreground-muted;
+  }
+
   :is([data-ui-component="command-presentation"], [data-ui-component="toggle-presentation"]) {
     @apply relative inline-flex;
   }
diff --git a/site/src/app/routeTree.gen.ts b/site/src/app/routeTree.gen.ts
index aa2027eb..faef116b 100644
--- a/site/src/app/routeTree.gen.ts
+++ b/site/src/app/routeTree.gen.ts
@@ -135,6 +135,7 @@ import { Route as PageDocsApiAnimationReactRouteImport } from "./routes/_page/do
 import { Route as PageDocsApiAnnotationRouteImport } from "./routes/_page/docs/api/annotation";
 import { Route as PageDocsApiCalendarRouteImport } from "./routes/_page/docs/api/calendar";
 import { Route as PageDocsApiCalendarDocumentRouteImport } from "./routes/_page/docs/api/calendar-document";
+import { Route as PageDocsApiCanvasRouteImport } from "./routes/_page/docs/api/canvas";
 import { Route as PageDocsApiCollaborationRouteImport } from "./routes/_page/docs/api/collaboration";
 import { Route as PageDocsApiComposerRouteImport } from "./routes/_page/docs/api/composer";
 import { Route as PageDocsApiComposerReactRouteImport } from "./routes/_page/docs/api/composer-react";
@@ -145,6 +146,7 @@ import { Route as PageDocsApiEditingRouteImport } from "./routes/_page/docs/api/
 import { Route as PageDocsApiFileIntakeRouteImport } from "./routes/_page/docs/api/file-intake";
 import { Route as PageDocsApiJsonDocumentRouteImport } from "./routes/_page/docs/api/json-document";
 import { Route as PageDocsApiMarkdownReactRouteImport } from "./routes/_page/docs/api/markdown-react";
+import { Route as PageDocsApiObjectDocumentRouteImport } from "./routes/_page/docs/api/object-document";
 import { Route as PageDocsApiReactRouteImport } from "./routes/_page/docs/api/react";
 import { Route as PageDocsApiReactHookFormRouteImport } from "./routes/_page/docs/api/react-hook-form";
 import { Route as PageDocsApiRichTextRouteImport } from "./routes/_page/docs/api/rich-text";
@@ -830,6 +832,11 @@ const PageDocsApiCalendarDocumentRoute =
     path: "/docs/api/calendar-document",
     getParentRoute: () => PageRoute,
   } as any);
+const PageDocsApiCanvasRoute = PageDocsApiCanvasRouteImport.update({
+  id: "/docs/api/canvas",
+  path: "/docs/api/canvas",
+  getParentRoute: () => PageRoute,
+} as any);
 const PageDocsApiCollaborationRoute =
   PageDocsApiCollaborationRouteImport.update({
     id: "/docs/api/collaboration",
@@ -885,6 +892,12 @@ const PageDocsApiMarkdownReactRoute =
     path: "/docs/api/markdown-react",
     getParentRoute: () => PageRoute,
   } as any);
+const PageDocsApiObjectDocumentRoute =
+  PageDocsApiObjectDocumentRouteImport.update({
+    id: "/docs/api/object-document",
+    path: "/docs/api/object-document",
+    getParentRoute: () => PageRoute,
+  } as any);
 const PageDocsApiReactRoute = PageDocsApiReactRouteImport.update({
   id: "/docs/api/react",
   path: "/docs/api/react",
@@ -1135,6 +1148,7 @@ export interface FileRoutesByFullPath {
   "/docs/api/annotation": typeof PageDocsApiAnnotationRoute;
   "/docs/api/calendar": typeof PageDocsApiCalendarRoute;
   "/docs/api/calendar-document": typeof PageDocsApiCalendarDocumentRoute;
+  "/docs/api/canvas": typeof PageDocsApiCanvasRoute;
   "/docs/api/collaboration": typeof PageDocsApiCollaborationRoute;
   "/docs/api/composer": typeof PageDocsApiComposerRoute;
   "/docs/api/composer-react": typeof PageDocsApiComposerReactRoute;
@@ -1145,6 +1159,7 @@ export interface FileRoutesByFullPath {
   "/docs/api/file-intake": typeof PageDocsApiFileIntakeRoute;
   "/docs/api/json-document": typeof PageDocsApiJsonDocumentRoute;
   "/docs/api/markdown-react": typeof PageDocsApiMarkdownReactRoute;
+  "/docs/api/object-document": typeof PageDocsApiObjectDocumentRoute;
   "/docs/api/react": typeof PageDocsApiReactRoute;
   "/docs/api/react-hook-form": typeof PageDocsApiReactHookFormRoute;
   "/docs/api/rich-text": typeof PageDocsApiRichTextRoute;
@@ -1294,6 +1309,7 @@ export interface FileRoutesByTo {
   "/docs/api/annotation": typeof PageDocsApiAnnotationRoute;
   "/docs/api/calendar": typeof PageDocsApiCalendarRoute;
   "/docs/api/calendar-document": typeof PageDocsApiCalendarDocumentRoute;
+  "/docs/api/canvas": typeof PageDocsApiCanvasRoute;
   "/docs/api/collaboration": typeof PageDocsApiCollaborationRoute;
   "/docs/api/composer": typeof PageDocsApiComposerRoute;
   "/docs/api/composer-react": typeof PageDocsApiComposerReactRoute;
@@ -1304,6 +1320,7 @@ export interface FileRoutesByTo {
   "/docs/api/file-intake": typeof PageDocsApiFileIntakeRoute;
   "/docs/api/json-document": typeof PageDocsApiJsonDocumentRoute;
   "/docs/api/markdown-react": typeof PageDocsApiMarkdownReactRoute;
+  "/docs/api/object-document": typeof PageDocsApiObjectDocumentRoute;
   "/docs/api/react": typeof PageDocsApiReactRoute;
   "/docs/api/react-hook-form": typeof PageDocsApiReactHookFormRoute;
   "/docs/api/rich-text": typeof PageDocsApiRichTextRoute;
@@ -1455,6 +1472,7 @@ export interface FileRoutesById {
   "/_page/docs/api/annotation": typeof PageDocsApiAnnotationRoute;
   "/_page/docs/api/calendar": typeof PageDocsApiCalendarRoute;
   "/_page/docs/api/calendar-document": typeof PageDocsApiCalendarDocumentRoute;
+  "/_page/docs/api/canvas": typeof PageDocsApiCanvasRoute;
   "/_page/docs/api/collaboration": typeof PageDocsApiCollaborationRoute;
   "/_page/docs/api/composer": typeof PageDocsApiComposerRoute;
   "/_page/docs/api/composer-react": typeof PageDocsApiComposerReactRoute;
@@ -1465,6 +1483,7 @@ export interface FileRoutesById {
   "/_page/docs/api/file-intake": typeof PageDocsApiFileIntakeRoute;
   "/_page/docs/api/json-document": typeof PageDocsApiJsonDocumentRoute;
   "/_page/docs/api/markdown-react": typeof PageDocsApiMarkdownReactRoute;
+  "/_page/docs/api/object-document": typeof PageDocsApiObjectDocumentRoute;
   "/_page/docs/api/react": typeof PageDocsApiReactRoute;
   "/_page/docs/api/react-hook-form": typeof PageDocsApiReactHookFormRoute;
   "/_page/docs/api/rich-text": typeof PageDocsApiRichTextRoute;
@@ -1616,6 +1635,7 @@ export interface FileRouteTypes {
     | "/docs/api/annotation"
     | "/docs/api/calendar"
     | "/docs/api/calendar-document"
+    | "/docs/api/canvas"
     | "/docs/api/collaboration"
     | "/docs/api/composer"
     | "/docs/api/composer-react"
@@ -1626,6 +1646,7 @@ export interface FileRouteTypes {
     | "/docs/api/file-intake"
     | "/docs/api/json-document"
     | "/docs/api/markdown-react"
+    | "/docs/api/object-document"
     | "/docs/api/react"
     | "/docs/api/react-hook-form"
     | "/docs/api/rich-text"
@@ -1775,6 +1796,7 @@ export interface FileRouteTypes {
     | "/docs/api/annotation"
     | "/docs/api/calendar"
     | "/docs/api/calendar-document"
+    | "/docs/api/canvas"
     | "/docs/api/collaboration"
     | "/docs/api/composer"
     | "/docs/api/composer-react"
@@ -1785,6 +1807,7 @@ export interface FileRouteTypes {
     | "/docs/api/file-intake"
     | "/docs/api/json-document"
     | "/docs/api/markdown-react"
+    | "/docs/api/object-document"
     | "/docs/api/react"
     | "/docs/api/react-hook-form"
     | "/docs/api/rich-text"
@@ -1935,6 +1958,7 @@ export interface FileRouteTypes {
     | "/_page/docs/api/annotation"
     | "/_page/docs/api/calendar"
     | "/_page/docs/api/calendar-document"
+    | "/_page/docs/api/canvas"
     | "/_page/docs/api/collaboration"
     | "/_page/docs/api/composer"
     | "/_page/docs/api/composer-react"
@@ -1945,6 +1969,7 @@ export interface FileRouteTypes {
     | "/_page/docs/api/file-intake"
     | "/_page/docs/api/json-document"
     | "/_page/docs/api/markdown-react"
+    | "/_page/docs/api/object-document"
     | "/_page/docs/api/react"
     | "/_page/docs/api/react-hook-form"
     | "/_page/docs/api/rich-text"
@@ -2861,6 +2886,13 @@ declare module "@tanstack/react-router" {
       preLoaderRoute: typeof PageDocsApiCalendarDocumentRouteImport;
       parentRoute: typeof PageRoute;
     };
+    "/_page/docs/api/canvas": {
+      id: "/_page/docs/api/canvas";
+      path: "/docs/api/canvas";
+      fullPath: "/docs/api/canvas";
+      preLoaderRoute: typeof PageDocsApiCanvasRouteImport;
+      parentRoute: typeof PageRoute;
+    };
     "/_page/docs/api/collaboration": {
       id: "/_page/docs/api/collaboration";
       path: "/docs/api/collaboration";
@@ -2931,6 +2963,13 @@ declare module "@tanstack/react-router" {
       preLoaderRoute: typeof PageDocsApiMarkdownReactRouteImport;
       parentRoute: typeof PageRoute;
     };
+    "/_page/docs/api/object-document": {
+      id: "/_page/docs/api/object-document";
+      path: "/docs/api/object-document";
+      fullPath: "/docs/api/object-document";
+      preLoaderRoute: typeof PageDocsApiObjectDocumentRouteImport;
+      parentRoute: typeof PageRoute;
+    };
     "/_page/docs/api/react": {
       id: "/_page/docs/api/react";
       path: "/docs/api/react";
@@ -3210,6 +3249,7 @@ interface PageRouteChildren {
   PageDocsApiAnnotationRoute: typeof PageDocsApiAnnotationRoute;
   PageDocsApiCalendarRoute: typeof PageDocsApiCalendarRoute;
   PageDocsApiCalendarDocumentRoute: typeof PageDocsApiCalendarDocumentRoute;
+  PageDocsApiCanvasRoute: typeof PageDocsApiCanvasRoute;
   PageDocsApiCollaborationRoute: typeof PageDocsApiCollaborationRoute;
   PageDocsApiComposerRoute: typeof PageDocsApiComposerRoute;
   PageDocsApiComposerReactRoute: typeof PageDocsApiComposerReactRoute;
@@ -3220,6 +3260,7 @@ interface PageRouteChildren {
   PageDocsApiFileIntakeRoute: typeof PageDocsApiFileIntakeRoute;
   PageDocsApiJsonDocumentRoute: typeof PageDocsApiJsonDocumentRoute;
   PageDocsApiMarkdownReactRoute: typeof PageDocsApiMarkdownReactRoute;
+  PageDocsApiObjectDocumentRoute: typeof PageDocsApiObjectDocumentRoute;
   PageDocsApiReactRoute: typeof PageDocsApiReactRoute;
   PageDocsApiReactHookFormRoute: typeof PageDocsApiReactHookFormRoute;
   PageDocsApiRichTextRoute: typeof PageDocsApiRichTextRoute;
@@ -3369,6 +3410,7 @@ const PageRouteChildren: PageRouteChildren = {
   PageDocsApiAnnotationRoute: PageDocsApiAnnotationRoute,
   PageDocsApiCalendarRoute: PageDocsApiCalendarRoute,
   PageDocsApiCalendarDocumentRoute: PageDocsApiCalendarDocumentRoute,
+  PageDocsApiCanvasRoute: PageDocsApiCanvasRoute,
   PageDocsApiCollaborationRoute: PageDocsApiCollaborationRoute,
   PageDocsApiComposerRoute: PageDocsApiComposerRoute,
   PageDocsApiComposerReactRoute: PageDocsApiComposerReactRoute,
@@ -3380,6 +3422,7 @@ const PageRouteChildren: PageRouteChildren = {
   PageDocsApiFileIntakeRoute: PageDocsApiFileIntakeRoute,
   PageDocsApiJsonDocumentRoute: PageDocsApiJsonDocumentRoute,
   PageDocsApiMarkdownReactRoute: PageDocsApiMarkdownReactRoute,
+  PageDocsApiObjectDocumentRoute: PageDocsApiObjectDocumentRoute,
   PageDocsApiReactRoute: PageDocsApiReactRoute,
   PageDocsApiReactHookFormRoute: PageDocsApiReactHookFormRoute,
   PageDocsApiRichTextRoute: PageDocsApiRichTextRoute,
diff --git a/site/src/app/routes/_page/docs/api/canvas.tsx b/site/src/app/routes/_page/docs/api/canvas.tsx
new file mode 100644
index 00000000..90850d75
--- /dev/null
+++ b/site/src/app/routes/_page/docs/api/canvas.tsx
@@ -0,0 +1,6 @@
+import { createFileRoute } from "@tanstack/react-router";
+import { DocsRoute } from "../../../../../routes/docs/DocsRoute";
+
+export const Route = createFileRoute("/_page/docs/api/canvas")({
+  component: function CanvasApiReferenceRoute() { return <DocsRoute pageId="canvasApi" />; },
+});
diff --git a/site/src/app/routes/_page/docs/api/object-document.tsx b/site/src/app/routes/_page/docs/api/object-document.tsx
new file mode 100644
index 00000000..da13697e
--- /dev/null
+++ b/site/src/app/routes/_page/docs/api/object-document.tsx
@@ -0,0 +1,6 @@
+import { createFileRoute } from "@tanstack/react-router";
+import { DocsRoute } from "../../../../../routes/docs/DocsRoute";
+
+export const Route = createFileRoute("/_page/docs/api/object-document")({
+  component: function ObjectDocumentApiReferenceRoute() { return <DocsRoute pageId="objectDocumentApi" />; },
+});
diff --git a/site/src/routes/canvas-demo/CanvasDemoRoute.tsx b/site/src/routes/canvas-demo/CanvasDemoRoute.tsx
index 71eab282..63f069bb 100644
--- a/site/src/routes/canvas-demo/CanvasDemoRoute.tsx
+++ b/site/src/routes/canvas-demo/CanvasDemoRoute.tsx
@@ -1,843 +1,16 @@
-import { useRef, useState, type CSSProperties, type KeyboardEvent, type PointerEvent, type WheelEvent } from "react";
+import { useState } from "react";
+import { createObjectEditor } from "@interactive-os/json-document-editing";
+import { CanvasHand } from "@interactive-os/json-document-canvas";
 import { DemoPage } from "../../shared/demo-workbench/DemoPage";
-import { canvasDemoDocument, objectDemoColors } from "../../shared/demo-workbench/object-demo-document";
-import {
-  createObjectEditor,
-  type ObjectDocument,
-} from "@interactive-os/json-document-editing";
-import { useEditing } from "@interactive-os/json-document-react";
-import {
-  activateAffordance,
-  applyAffordance,
-  createCanvasGestureSession,
-  clickCountAffordance,
-  commitAffordance,
-  contextMenuAffordance,
-  deleteAffordance,
-  dragAffordance,
-  dragOperation,
-  dropAffordance,
-  escapeAffordance,
-  hoverAffordance,
-  marqueeAffordance,
-  marqueeHitsAffordance,
-  nudgeAffordance,
-  panAffordance,
-  planeHitAffordance,
-  resizeAffordance,
-  selectAllAffordance,
-  snapAffordance,
-  wheelAffordance,
-  zoomAffordance,
-  type ResizeEdge,
-  type InteractionHandleEvent,
-} from "@interactive-os/json-document-affordance";
-import { createWebPointerSession, pressInteractionFromWeb } from "@interactive-os/json-document-web";
-import { Command, SelectableItem, useInteractionHandle } from "@interactive-os/json-document-ui-primitives-react";
+import { canvasCreationStyle, emptyCanvasDocument } from "../../shared/demo-workbench/canvas-demo-document";
 import { PageHeader } from "../../shared/ui/primitives";
-import { ProductShell } from "@interactive-os/json-document-ui-primitives-react";
-import { classes, ui } from "../../shared/ui/styles";
-import { editingItemProps } from "@interactive-os/json-document-react";
-
-const lockedIds = new Set(["lock"]);
-const resizeEdges: ReadonlyArray<ResizeEdge> = ["n", "ne", "e", "se", "s", "sw", "w", "nw"];
-
-type DragState = {
-  readonly type: "drag";
-  readonly ids: ReadonlyArray<string>;
-  readonly originX: number;
-  readonly originY: number;
-  readonly dx: number;
-  readonly dy: number;
-  readonly copying: boolean;
-};
-
-type MarqueeState = {
-  readonly type: "marquee";
-  readonly originX: number;
-  readonly originY: number;
-  readonly x: number;
-  readonly y: number;
-  readonly width: number;
-  readonly height: number;
-};
-
-type PanState = {
-  readonly type: "pan";
-  readonly x: number;
-  readonly y: number;
-  readonly originX: number;
-  readonly originY: number;
-  readonly active: boolean;
-};
-
-type ResizeState = {
-  readonly type: "resize";
-  readonly id: string;
-  readonly edge: ResizeEdge;
-  readonly originX: number;
-  readonly originY: number;
-  readonly dx: number;
-  readonly dy: number;
-  readonly dw: number;
-  readonly dh: number;
-};
-
-type MenuState = {
-  readonly x: number;
-  readonly y: number;
-};
-
-type CanvasGesture = DragState | MarqueeState | PanState | ResizeState;
+import { ui } from "../../shared/ui/styles";
 
 export function CanvasDemoRoute() {
-  const [editor] = useState(() => createObjectEditor(canvasDemoDocument));
-  const [drag, setDrag] = useState<DragState | null>(null);
-  const [marquee, setMarquee] = useState<MarqueeState | null>(null);
-  const [pan, setPan] = useState<PanState>({ type: "pan", x: 0, y: 0, originX: 0, originY: 0, active: false });
-  const [resize, setResize] = useState<ResizeState | null>(null);
-  const [space, setSpace] = useState(false);
-  const [scale, setScale] = useState(1);
-  const [hoverId, setHoverId] = useState<string | null>(null);
-  const [menu, setMenu] = useState<MenuState | null>(null);
-  const surface = useRef<HTMLDivElement>(null);
-  const dragRef = useRef<DragState | null>(null);
-  const marqueeRef = useRef<MarqueeState | null>(null);
-  const panRef = useRef(pan);
-  const resizeRef = useRef<ResizeState | null>(null);
-  const spaceRef = useRef(space);
-  const scaleRef = useRef(scale);
-  const [gestureSession] = useState(() => createCanvasGestureSession<CanvasGesture>({
-    onBegin: projectGesture,
-    onPreview: projectGesture,
-    onCommit: clearGesture,
-    onCancel: clearGesture,
-  }));
-  const [pointerSession] = useState(() => createWebPointerSession<"drag" | "marquee" | "pan">({
-    onCancel: (_kind, reason) => gestureSession.cancel(reason === "lost-capture" ? "lost-capture" : "pointer-cancel"),
-  }));
-  panRef.current = pan;
-  spaceRef.current = space;
-  scaleRef.current = scale;
-  const editing = useEditing({
-    source: editor,
-    selectedKeys: editor.selectedObjects.map((object) => object.id),
-    focusKey: editor.snapshot.selection.primaryKey,
-    onSelect: (objectId, mode) => {
-      editor.dispatch({
-        type: "selection.set",
-        objectIds: [objectId],
-        mode,
-      });
-    },
-  });
-  const document = editing.snapshot.value as ObjectDocument;
-  const unlockedIds = document.objects.map((object) => object.id).filter((id) => !lockedIds.has(id));
-
-  function projectGesture(next: CanvasGesture) {
-    dragRef.current = next.type === "drag" ? next : null;
-    marqueeRef.current = next.type === "marquee" ? next : null;
-    resizeRef.current = next.type === "resize" ? next : null;
-    setDrag(dragRef.current);
-    setMarquee(marqueeRef.current);
-    setResize(resizeRef.current);
-    if (next.type === "pan") {
-      panRef.current = next;
-      setPan(next);
-    }
-  }
-
-  function clearGesture() {
-    dragRef.current = null;
-    marqueeRef.current = null;
-    resizeRef.current = null;
-    setDrag(null);
-    setMarquee(null);
-    setResize(null);
-    if (panRef.current.active) {
-      panRef.current = { ...panRef.current, active: false };
-      setPan(panRef.current);
-    }
-  }
-
-  function setDragState(next: DragState | null) {
-    if (next === null) gestureSession.cancel();
-    else if (gestureSession.getActive()?.type === "drag") gestureSession.preview(next);
-    else gestureSession.begin(next);
-  }
-
-  function setMarqueeState(next: MarqueeState | null) {
-    if (next === null) gestureSession.cancel();
-    else if (gestureSession.getActive()?.type === "marquee") gestureSession.preview(next);
-    else gestureSession.begin(next);
-  }
-
-  function setPanState(next: PanState) {
-    if (!next.active) {
-      gestureSession.commit();
-      panRef.current = next;
-      setPan(next);
-    } else if (gestureSession.getActive()?.type === "pan") gestureSession.preview(next);
-    else gestureSession.begin(next);
-  }
-
-  function setResizeState(next: ResizeState | null) {
-    if (next === null) gestureSession.cancel();
-    else if (gestureSession.getActive()?.type === "resize") gestureSession.preview(next);
-    else gestureSession.begin(next);
-  }
-
-  function isPanStart(event: PointerEvent<HTMLElement>) {
-    let grabbing = false;
-    applyAffordance(panAffordance({ spaceKey: spaceRef.current, buttons: event.buttons }), {
-      cursor: (cursor) => {
-        grabbing = cursor === "grabbing";
-      },
-      hand: (hand) => {
-        if (hand.type === "translate") grabbing = true;
-      },
-    });
-    return grabbing || (spaceRef.current && event.buttons === 1);
-  }
-
-  function startPan(event: PointerEvent<HTMLElement>) {
-    const current = panRef.current;
-    if (surface.current === null) return;
-    pointerSession.begin(surface.current, event.pointerId, "pan");
-    setPanState({
-      type: "pan",
-      x: current.x,
-      y: current.y,
-      originX: event.clientX - current.x,
-      originY: event.clientY - current.y,
-      active: true,
-    });
-  }
-
-  function planePoint(event: PointerEvent<HTMLElement>) {
-    return {
-      x: (event.nativeEvent.offsetX - panRef.current.x) / scaleRef.current,
-      y: (event.nativeEvent.offsetY - panRef.current.y) / scaleRef.current,
-    };
-  }
-
-  function commitCurrentDrag(event: PointerEvent<HTMLElement>) {
-    pointerSession.commit(event.pointerId);
-    const current = dragRef.current;
-    if (!current) return;
-    const committed = commitAffordance(
-      dragAffordance(
-        { x: current.originX, y: current.originY },
-        { x: event.clientX, y: event.clientY },
-        { shiftKey: event.shiftKey, altKey: event.altKey || current.copying },
-      ),
-    );
-    if (committed) {
-      applyAffordance(committed, {
-        commit: (hand) => {
-          if (hand.type !== "translate") return;
-          const dx = hand.dx / scaleRef.current;
-          const dy = hand.dy / scaleRef.current;
-          let copied = false;
-          applyAffordance(dragOperation({
-            shiftKey: event.shiftKey,
-            metaKey: event.metaKey,
-            ctrlKey: event.ctrlKey,
-            altKey: event.altKey || current.copying,
-          }), {
-            hand: (operation) => {
-              if (operation.type !== "copy") return;
-              copied = true;
-              const clipboard = editor.copy();
-              if (!clipboard) return;
-              editor.dispatch({ type: "clipboard.paste", clipboard });
-              const pasted = editor.selectedObjects.map((object) => object.id);
-              applyAffordance(
-                snapAffordance(
-                  { x: dx, y: dy },
-                  { grid: 8, disable: event.metaKey || event.ctrlKey },
-                ),
-                {
-                  hand: (snapped) => {
-                    if (snapped.type !== "translate") return;
-                    editor.dispatch({
-                      type: "object.translate",
-                      objectIds: pasted,
-                      dx: snapped.dx,
-                      dy: snapped.dy,
-                    });
-                  },
-                },
-              );
-            },
-          });
-          if (copied) return;
-          const drop = commitAffordance(dropAffordance({ canDrop: true }));
-          if (!drop) return;
-          applyAffordance(drop, {
-            commit: (dropped) => {
-              if (dropped.type !== "move-drop") return;
-              applyAffordance(
-                snapAffordance(
-                  { x: dx, y: dy },
-                  { grid: 8, disable: event.metaKey || event.ctrlKey },
-                ),
-                {
-                  hand: (snapped) => {
-                    if (snapped.type !== "translate") return;
-                    editor.dispatch({
-                      type: "object.translate",
-                      objectIds: current.ids,
-                      dx: snapped.dx,
-                      dy: snapped.dy,
-                    });
-                  },
-                },
-              );
-            },
-          });
-        },
-      });
-    }
-    gestureSession.commit();
-  }
-
-  function handleObjectPointerDown(event: PointerEvent<HTMLElement>, objectId: string) {
-    if (isPanStart(event)) {
-      event.preventDefault();
-      event.stopPropagation();
-      surface.current?.focus({ preventScroll: true, focusVisible: false } as FocusOptions);
-      setMenu(null);
-      startPan(event);
-      return;
-    }
-    if (event.button !== 0) return;
-    event.preventDefault();
-    event.stopPropagation();
-    surface.current?.focus({ preventScroll: true, focusVisible: false } as FocusOptions);
-    setMenu(null);
-    applyAffordance(
-      planeHitAffordance({
-        hitId: objectId,
-        selectedIds: editor.selectedObjects.map((object) => object.id),
-        shiftKey: event.shiftKey,
-        metaKey: event.metaKey,
-        ctrlKey: event.ctrlKey,
-        locked: lockedIds.has(objectId),
-      }),
-      {
-        cursor: (cursor) => {
-          event.currentTarget.style.cursor = cursor;
-        },
-        hand: (hand) => {
-          if (hand.type !== "select" || !hand.objectIds) return;
-          pointerSession.begin(event.currentTarget, event.pointerId, "drag");
-          editor.dispatch({
-            type: "selection.set",
-            objectIds: hand.objectIds,
-            mode: "replace",
-          });
-          setDragState({
-            type: "drag",
-            ids: hand.objectIds,
-            originX: event.clientX,
-            originY: event.clientY,
-            dx: 0,
-            dy: 0,
-            copying: event.altKey,
-          });
-        },
-      },
-    );
-  }
-
-  function handleObjectPointerMove(event: PointerEvent<HTMLElement>) {
-    const current = dragRef.current;
-    if (!current) return;
-    applyAffordance(
-      dragAffordance(
-        { x: current.originX, y: current.originY },
-        { x: event.clientX, y: event.clientY },
-        { shiftKey: event.shiftKey, altKey: event.altKey || current.copying },
-      ),
-      {
-        cursor: (cursor) => {
-          event.currentTarget.style.cursor = cursor;
-        },
-        hand: (hand) => {
-          if (hand.type !== "translate") return;
-          setDragState({
-            ...current,
-            dx: hand.dx / scaleRef.current,
-            dy: hand.dy / scaleRef.current,
-            copying: event.altKey || current.copying,
-          });
-        },
-      },
-    );
-  }
-
-  function handleResizeInteraction(interaction: InteractionHandleEvent, event: PointerEvent<HTMLDivElement>, objectId: string, edge: ResizeEdge) {
-    event.preventDefault();
-    if (interaction.phase === "start") {
-      surface.current?.focus({ preventScroll: true, focusVisible: false } as FocusOptions);
-      setResizeState({ type: "resize", id: objectId, edge, originX: interaction.origin.x, originY: interaction.origin.y, dx: 0, dy: 0, dw: 0, dh: 0 });
-      return;
-    }
-    if (interaction.phase === "cancel") {
-      gestureSession.cancel("pointer-cancel");
-      return;
-    }
-    const current = resizeRef.current;
-    if (current === null) return;
-    const result = resizeAffordance(interaction.origin, interaction.point, edge, event);
-    if (interaction.phase === "preview") {
-      applyAffordance(result, {
-        hand: (hand) => {
-          if (hand.type !== "resize") return;
-          const scaleNow = scaleRef.current;
-          setResizeState({ ...current, dx: hand.dx / scaleNow, dy: hand.dy / scaleNow, dw: hand.dw / scaleNow, dh: hand.dh / scaleNow });
-        },
-      });
-      return;
-    }
-    const committed = commitAffordance(result);
-    if (committed !== null) {
-      applyAffordance(committed, {
-        commit: (hand) => {
-          if (hand.type !== "resize") return;
-          editor.dispatch({ type: "object.resize", objectIds: [current.id], dx: hand.dx / scaleRef.current, dy: hand.dy / scaleRef.current, dw: hand.dw / scaleRef.current, dh: hand.dh / scaleRef.current });
-        },
-      });
-    }
-    gestureSession.commit();
-  }
-
-  function handleSurfacePointerDown(event: PointerEvent<HTMLDivElement>) {
-    if (isPanStart(event)) {
-      event.preventDefault();
-      surface.current?.focus({ preventScroll: true, focusVisible: false } as FocusOptions);
-      setMenu(null);
-      startPan(event);
-      return;
-    }
-    if (event.button !== 0) return;
-    event.preventDefault();
-    surface.current?.focus({ preventScroll: true, focusVisible: false } as FocusOptions);
-    setMenu(null);
-    if (surface.current === null) return;
-    pointerSession.begin(surface.current, event.pointerId, "marquee");
-    const origin = planePoint(event);
-    setMarqueeState({ type: "marquee", originX: origin.x, originY: origin.y, x: origin.x, y: origin.y, width: 0, height: 0 });
-  }
-
-  function handleSurfacePointerMove(event: PointerEvent<HTMLDivElement>) {
-    pointerSession.preview(event.pointerId, (kind) => kind);
-    const currentPan = panRef.current;
-    if (currentPan.active) {
-      applyAffordance(
-        panAffordance({
-          spaceKey: true,
-          buttons: event.buttons,
-          origin: { x: currentPan.originX, y: currentPan.originY },
-          point: { x: event.clientX, y: event.clientY },
-        }),
-        {
-          cursor: (cursor) => {
-            event.currentTarget.style.cursor = cursor;
-          },
-          hand: (hand) => {
-            if (hand.type !== "translate") return;
-            setPanState({ ...currentPan, x: hand.dx, y: hand.dy });
-          },
-        },
-      );
-      return;
-    }
-    const currentMarquee = marqueeRef.current;
-    if (!currentMarquee) return;
-    const origin = { x: currentMarquee.originX, y: currentMarquee.originY };
-    const point = planePoint(event);
-    applyAffordance(marqueeAffordance(origin, point, { shiftKey: event.shiftKey }), {
-      cursor: (cursor) => {
-        event.currentTarget.style.cursor = cursor;
-      },
-      hand: (hand) => {
-        if (hand.type !== "select" || !hand.rect) return;
-        setMarqueeState({ type: "marquee", originX: origin.x, originY: origin.y, ...hand.rect });
-      },
-    });
-  }
-
-  function handleSurfacePointerUp(event: PointerEvent<HTMLDivElement>) {
-    const currentPan = panRef.current;
-    if (currentPan.active) {
-      pointerSession.commit(event.pointerId);
-      setPanState({ ...currentPan, active: false });
-      return;
-    }
-    const currentMarquee = marqueeRef.current;
-    if (!currentMarquee) return;
-    pointerSession.commit(event.pointerId);
-    const origin = { x: currentMarquee.originX, y: currentMarquee.originY };
-    const point = planePoint(event);
-    const committed = commitAffordance(marqueeAffordance(origin, point, { shiftKey: event.shiftKey }));
-    if (committed) {
-      applyAffordance(committed, {
-        commit: (hand) => {
-          if (hand.type === "clear") {
-            editor.dispatch({ type: "selection.set", objectIds: [], mode: "replace" });
-            return;
-          }
-          if (hand.type !== "select" || !hand.rect) return;
-          applyAffordance(
-            marqueeHitsAffordance({
-              rect: hand.rect,
-              items: document.objects.filter((object) => !lockedIds.has(object.id)),
-            }),
-            {
-              hand: (hits) => {
-                if (hits.type !== "select" || !hits.objectIds || hits.objectIds.length === 0) return;
-                editor.dispatch({
-                  type: "selection.set",
-                  objectIds: hits.objectIds,
-                  mode: hand.operation,
-                });
-              },
-            },
-          );
-        },
-      });
-    }
-    gestureSession.commit();
-  }
-
-  function cancelHands() {
-    setMenu(null);
-    const activePointer = pointerSession.getSnapshot();
-    if (activePointer) pointerSession.cancel(activePointer.pointerId);
-    else gestureSession.cancel();
-  }
-
-  function onKeyDown(event: KeyboardEvent<HTMLDivElement>) {
-    if (event.key === " ") {
-      setSpace(true);
-      event.preventDefault();
-    }
-    applyAffordance(
-      escapeAffordance({
-        key: event.key,
-        grabbing: dragRef.current != null
-          || marqueeRef.current != null
-          || panRef.current.active
-          || resizeRef.current != null
-          || menu != null,
-        selected: editor.selectedObjects.length > 0,
-      }),
-      {
-        hand: (hand) => {
-          if (hand.type === "cancel") {
-            cancelHands();
-            event.preventDefault();
-            return;
-          }
-          if (hand.type !== "clear") return;
-          editor.dispatch({ type: "selection.set", objectIds: [], mode: "replace" });
-          event.preventDefault();
-        },
-      },
-    );
-    applyAffordance(contextMenuAffordance(event), {
-      hand: (hand) => {
-        if (hand.type === "menu" && hand.action === "cancel") setMenu(null);
-      },
-    });
-    applyAffordance(
-      selectAllAffordance(event, {
-        allSelected: editor.selectedObjects.length === unlockedIds.length && unlockedIds.length > 0,
-      }, { repeat: "preserve" }),
-      {
-        hand: (hand) => {
-          if (hand.type === "select-all") {
-            editor.dispatch({ type: "selection.set", objectIds: unlockedIds, mode: "replace" });
-            event.preventDefault();
-          }
-        },
-      },
-    );
-    applyAffordance(deleteAffordance(event), {
-      hand: (hand) => {
-        if (hand.type !== "delete") return;
-        editor.dispatch({ type: "selection.remove" });
-        event.preventDefault();
-      },
-    });
-    applyAffordance(activateAffordance(pressInteractionFromWeb(event)), {
-      hand: (hand) => {
-        if (hand.type !== "activate") return;
-        event.preventDefault();
-      },
-    });
-    applyAffordance(zoomAffordance(event), {
-      hand: (hand) => {
-        if (hand.type !== "zoom") return;
-        setScale((current) => clampScale(current * hand.factor));
-        event.preventDefault();
-      },
-    });
-    if (editor.selectedObjects.length === 0) {
-      applyAffordance(panAffordance({ key: event.key, selected: false }), {
-        hand: (hand) => {
-          if (hand.type !== "translate") return;
-          setPanState({ ...panRef.current, x: panRef.current.x + hand.dx, y: panRef.current.y + hand.dy });
-          event.preventDefault();
-        },
-      });
-      return;
-    }
-    applyAffordance(nudgeAffordance(event), {
-      hand: (hand) => {
-        if (hand.type !== "nudge") return;
-        const ids = editor.selectedObjects.map((object) => object.id);
-        editor.dispatch({ type: "object.translate", objectIds: ids, dx: hand.dx, dy: hand.dy });
-        event.preventDefault();
-      },
-    });
-  }
-
-  function onWheel(event: WheelEvent<HTMLDivElement>) {
-    applyAffordance(wheelAffordance(event), {
-      cursor: (cursor) => {
-        event.currentTarget.style.cursor = cursor;
-      },
-      hand: (hand) => {
-        if (hand.type === "zoom") {
-          event.preventDefault();
-          setScale((current) => clampScale(current * hand.factor));
-          return;
-        }
-        if (hand.type !== "translate") return;
-        event.preventDefault();
-        setPanState({
-          ...panRef.current,
-          x: panRef.current.x + hand.dx,
-          y: panRef.current.y + hand.dy,
-        });
-      },
-    });
-  }
-
+  const [editor] = useState(() => createObjectEditor(emptyCanvasDocument));
   return (
-    <DemoPage documentation={(
-      <PageHeader illustration="peek" title="Canvas">
-        Pick a box, drag it, then fill the selection. The board is the editor.
-      </PageHeader>
-    )}>
-      <ProductShell
-        toolbarLabel="Canvas actions"
-        canvasClassName="relative min-h-[22rem] overflow-hidden"
-        toolbar={objectDemoColors.map((color) => (
-          <Command label={`Fill ${color}`}
-            key={color}
-            onClick={() => editor.dispatch({ type: "selection.fill", color })}
-          >
-            <span aria-hidden="true" style={{ display: "inline-block", width: "0.75rem", height: "0.75rem", backgroundColor: color }} />
-          </Command>
-        ))}
-      >
-        <div
-          ref={surface}
-          className={classes("relative min-h-[22rem] overflow-hidden", ui.state.focus)}
-          aria-label="Canvas"
-          tabIndex={0}
-          onPointerDown={handleSurfacePointerDown}
-          onPointerMove={handleSurfacePointerMove}
-          onPointerUp={handleSurfacePointerUp}
-          onWheel={onWheel}
-          onContextMenu={(event) => {
-            applyAffordance(contextMenuAffordance(event.nativeEvent), {
-              hand: (hand) => {
-                if (hand.type !== "menu" || hand.action !== "open") return;
-                event.preventDefault();
-                setMenu({ x: event.nativeEvent.offsetX, y: event.nativeEvent.offsetY });
-              },
-            });
-          }}
-          onPointerCancel={(event) => {
-            pointerSession.cancel(event.pointerId);
-            applyAffordance(escapeAffordance(event), {
-              hand: (hand) => {
-                if (hand.type !== "cancel") return;
-                cancelHands();
-              },
-            });
-          }}
-          onKeyDown={onKeyDown}
-          onKeyUp={(event) => {
-            if (event.key === " ") setSpace(false);
-          }}
-        >
-          <div style={{ transform: `translate(${pan.x}px, ${pan.y}px) scale(${scale})`, transformOrigin: "0 0" }}>
-            {document.objects.map((object) => {
-              const resizing = resize?.id === object.id ? resize : null;
-              const offset = drag && !drag.copying && drag.ids.includes(object.id) ? drag : null;
-              const option = editingItemProps(editing.getItem(object.id));
-              return (
-                <SelectableItem
-                  key={object.id}
-                  data-object-id={object.id}
-                  data-locked={lockedIds.has(object.id) ? "true" : "false"}
-                  data-hover={hoverId === object.id}
-                  selected={option.selected}
-                  focus={option.focus}
-                  dragging={offset !== null}
-                  onPointerDown={(event) => handleObjectPointerDown(event, object.id)}
-                  onPointerMove={handleObjectPointerMove}
-                  onPointerUp={commitCurrentDrag}
-                  onPointerEnter={() => {
-                    applyAffordance(hoverAffordance({ elapsedMs: 0, inside: true, highlight: true }), {
-                      hand: (hand) => {
-                        if (hand.type === "hover" && hand.phase === "highlight") setHoverId(object.id);
-                      },
-                    });
-                  }}
-                  onPointerLeave={() => {
-                    applyAffordance(hoverAffordance({ elapsedMs: 0, inside: false, highlight: true }), {
-                      hand: () => setHoverId(null),
-                    });
-                    if (hoverId === object.id) setHoverId(null);
-                  }}
-                  onDoubleClick={(event) => {
-                    applyAffordance(clickCountAffordance(event.detail), {
-                      hand: (hand) => {
-                        if (hand.type !== "click" || hand.count !== 2) return;
-                        applyAffordance(activateAffordance(pressInteractionFromWeb(event)), {
-                          hand: (activated) => {
-                            if (activated.type === "activate") event.preventDefault();
-                          },
-                        });
-                      },
-                    });
-                  }}
-                  onLostPointerCapture={(event) => {
-                    pointerSession.cancel(event.pointerId, "lost-capture");
-                  }}
-                  className={ui.interactive.planeItem}
-                  style={{
-                    left: object.x + (offset?.dx ?? 0) + (resizing?.dx ?? 0),
-                    top: object.y + (offset?.dy ?? 0) + (resizing?.dy ?? 0),
-                    width: object.width + (resizing?.dw ?? 0),
-                    height: object.height + (resizing?.dh ?? 0),
-                    backgroundColor: object.color,
-                    color: "rgb(var(--color-foreground-canvas-object))",
-                  }}
-                >
-                  {object.label}
-                </SelectableItem>
-              );
-            })}
-            {drag?.copying
-              ? drag.ids.map((id) => {
-                const object = document.objects.find((item) => item.id === id);
-                if (!object) return null;
-                return (
-                  <div
-                    key={`ghost-${id}`}
-                    className={classes("pointer-events-none", ui.interactive.planeItem)}
-                    style={{
-                      left: object.x + drag.dx,
-                      top: object.y + drag.dy,
-                      width: object.width,
-                      height: object.height,
-                      backgroundColor: object.color,
-                      opacity: 0.5,
-                    }}
-                  >
-                    {object.label}
-                  </div>
-                );
-              })
-              : null}
-            {document.objects.map((object) => {
-              const option = editingItemProps(editing.getItem(object.id));
-              if (!option.selected || lockedIds.has(object.id)) return null;
-              const resizing = resize?.id === object.id ? resize : null;
-              const offset = drag && !drag.copying && drag.ids.includes(object.id) ? drag : null;
-              const left = object.x + (offset?.dx ?? 0) + (resizing?.dx ?? 0);
-              const top = object.y + (offset?.dy ?? 0) + (resizing?.dy ?? 0);
-              const width = object.width + (resizing?.dw ?? 0);
-              const height = object.height + (resizing?.dh ?? 0);
-              return resizeEdges.map((edge) => (
-                <CanvasResizeHandle
-                  key={`${object.id}-${edge}`}
-                  data-object-id={object.id}
-                  edge={edge}
-                  style={handleStyle(edge, left, top, width, height)}
-                  onHandle={(interaction, event) => handleResizeInteraction(interaction, event, object.id, edge)}
-                />
-              ));
-            })}
-            {marquee ? (
-              <div
-                className={classes("pointer-events-none absolute", ui.surface.marquee)}
-                style={{ left: marquee.x, top: marquee.y, width: marquee.width, height: marquee.height }}
-              />
-            ) : null}
-          </div>
-          {menu ? (
-            <div
-              role="menu"
-              aria-label="Canvas menu"
-              className={ui.interactive.contextMenu}
-              style={{ left: menu.x, top: menu.y }}
-            >
-              <Command
-                className={ui.interactive.contextMenuItem}
-                onClick={() => {
-                  editor.dispatch({ type: "selection.remove" });
-                  setMenu(null);
-                }}
-              >
-                Delete
-              </Command>
-            </div>
-          ) : null}
-        </div>
-      </ProductShell>
+    <DemoPage documentation={<PageHeader illustration="peek" title="Canvas">한 장에 글자·도형·그리기. 도구를 고른 뒤 슬라이드를 클릭하거나 드래그하세요. 글자는 더블클릭으로 편집합니다.</PageHeader>}>
+      <CanvasHand className={ui.product.embedded} editor={editor} creationStyle={canvasCreationStyle} slideStyle={{ background: "rgb(var(--color-background-canvas))" }} />
     </DemoPage>
   );
 }
-
-function clampScale(value: number) {
-  return Math.min(4, Math.max(0.25, value));
-}
-
-function CanvasResizeHandle(props: {
-  readonly edge: ResizeEdge;
-  readonly style: CSSProperties;
-  readonly "data-object-id": string;
-  readonly onHandle: (interaction: InteractionHandleEvent, event: PointerEvent<HTMLDivElement>) => void;
-}) {
-  const binding = useInteractionHandle<HTMLDivElement>({
-    descriptor: { kind: "resize", edge: props.edge },
-    onHandle: props.onHandle,
-  });
-  return (
-    <div
-      {...binding.handleProps}
-      role="presentation"
-      data-resize-edge={props.edge}
-      data-object-id={props["data-object-id"]}
-      className={ui.interactive.resizeHandle}
-      style={{ ...props.style, cursor: binding.cursor }}
-    />
-  );
-}
-
-function handleStyle(edge: ResizeEdge, left: number, top: number, width: number, height: number) {
-  const midX = left + width / 2 - 4;
-  const midY = top + height / 2 - 4;
-  const x = edge.includes("w") ? left - 4 : edge.includes("e") ? left + width - 4 : midX;
-  const y = edge.includes("n") ? top - 4 : edge.includes("s") ? top + height - 4 : midY;
-  return { left: x, top: y };
-}
diff --git a/site/src/routes/docs/DocsRoute.tsx b/site/src/routes/docs/DocsRoute.tsx
index a3ae514b..84dc17b6 100644
--- a/site/src/routes/docs/DocsRoute.tsx
+++ b/site/src/routes/docs/DocsRoute.tsx
@@ -73,6 +73,8 @@ const docIllustrations: Record<DocPageId, PetiteCatIllustration> = {
   jsonDocumentApi: "patch",
   selectionApi: "patch",
   editingApi: "patch",
+  objectDocumentApi: "braces",
+  canvasApi: "peek",
   reactApi: "connector",
   reactHookFormApi: "connector",
   ajvApi: "connector",
diff --git a/site/src/routes/docs/DocumentTypeCandidateRoute.tsx b/site/src/routes/docs/DocumentTypeCandidateRoute.tsx
index ee8c07ef..cca9c5b1 100644
--- a/site/src/routes/docs/DocumentTypeCandidateRoute.tsx
+++ b/site/src/routes/docs/DocumentTypeCandidateRoute.tsx
@@ -18,7 +18,7 @@ export type DocumentTypeCandidate = keyof typeof candidateNames;
 export function DocumentTypeCandidateRoute(props: { readonly candidate: DocumentTypeCandidate }) {
   const name = candidateNames[props.candidate];
   const profile = documentTypeAudits.candidateProfiles[props.candidate];
-  const audit = props.candidate === "calendar" ? documentTypeAudits.audits.calendar : undefined;
+  const audit = documentTypeAudits.audits[props.candidate as keyof typeof documentTypeAudits.audits];
   const ownerClosed = audit?.status === "owner-closed";
   const auditSource = audit === undefined ? "" : `
 ## 소스 기반 감사 현황
@@ -38,7 +38,7 @@ fixture, copy, layout-only CSS, tests와 generated route는 제외합니다.
   const source = `## ${ownerClosed ? "공개 소유자 · RC" : "후보 상태"}
 
 ${ownerClosed
-  ? `${name}의 모델·검증·의미 연산·projection은 \`@interactive-os/json-document-calendar-document\`가 소유합니다. Editing·Selection·React 없이 소비할 수 있으며 기존 Editing export는 호환 경로로 유지합니다. 소유권 확정은 wire Stable 승격을 뜻하지 않습니다.`
+  ? `${name}의 모델·검증·의미 연산·projection은 \`${audit.closure.owner}\`가 소유합니다. Editing·Selection·React 없이 소비할 수 있으며 기존 Editing export는 호환 경로로 유지합니다. 소유권 확정은 wire Stable 승격을 뜻하지 않습니다.`
   : `${name}은 현재 Document Type 후보입니다. 기존 package와 Hands에서 실제 책임을 옮기거나 완료를 선언하지 않았습니다.`}
 
 ## 왜 필요한가
@@ -52,7 +52,7 @@ ${profile.does}
 ## ${ownerClosed ? "현재 RC 모델" : "현재 관찰된 schema · TBD"}
 
 ${ownerClosed
-  ? "아래는 정본 document interface입니다. 필드 생략의 legacy 호환, 잘못된 타입 거절과 시간·반복 의미는 [소유자 API 계약](/docs/api/calendar-document)에 명시합니다."
+  ? `아래는 정본 document interface입니다. 필드 생략의 legacy 호환, 잘못된 타입 거절과 프로파일 의미는 [소유자 API 계약](${audit?.closure.apiPath ?? "/docs/api/calendar-document"})에 명시합니다.`
   : "이 schema는 현재 source에 존재하는 document interface를 축약한 감사 입력입니다. 정본 owner와 schema 계약이 확정됐다는 뜻은 아닙니다."}
 
 \`\`\`ts
@@ -76,7 +76,7 @@ ${auditSource}
 4. 같은 책임을 구현하는 Host 또는 Demo local bypass가 없다는 감사 결과
 
 ${ownerClosed
-  ? "[공개 API와 값 계약](/docs/api/calendar-document), [Calendar Usage 및 Source](/editors#calendar-editor), 독립 Document Type 테스트와 공통 Calendar Editing Grammar가 연결돼 있습니다. timezone/DST·서버 동기화·AI·RRULE·pagination·독립 구현 conformance는 TBD로 남습니다."
+  ? `[공개 API와 값 계약](${audit?.closure.apiPath ?? "/docs/api/calendar-document"}), [${name} Usage 및 Source](${audit.closure.usagePagePath}), 독립 Document Type·Editing·Hand 테스트가 연결돼 있습니다. ${props.candidate === "object" ? "Canvas의 다중 페이지·그룹·레이어·PPTX·협업" : "timezone/DST·서버 동기화·RRULE·pagination"} 및 독립 구현 conformance는 TBD로 남습니다.`
   : `증거가 닫히기 전에는 이 페이지와 내비게이션을 \`${name} · TBD\`로 유지합니다.`}
 `;
 
diff --git a/site/src/routes/docs/doc-pages.ts b/site/src/routes/docs/doc-pages.ts
index 380c3a88..23f3cd69 100644
--- a/site/src/routes/docs/doc-pages.ts
+++ b/site/src/routes/docs/doc-pages.ts
@@ -19,6 +19,10 @@ import annotationApiMarkdown from "../../../../docs/api-reference/annotation.md?
 import calendarApiMarkdown from "../../../../docs/api-reference/calendar.md?raw";
 import calendarDocumentApiMarkdown from "../../../../docs/api-reference/calendar-document.md?raw";
 import calendarDocumentContractMarkdown from "../../../../packages/json-document-calendar-document/docs/api.md?raw";
+import objectDocumentApiMarkdown from "../../../../docs/api-reference/object-document.md?raw";
+import objectDocumentContractMarkdown from "../../../../packages/json-document-object-document/docs/api.md?raw";
+import canvasApiMarkdown from "../../../../docs/api-reference/canvas.md?raw";
+import canvasContractMarkdown from "../../../../packages/json-document-canvas/docs/api.md?raw";
 import webApiMarkdown from "../../../../docs/api-reference/web.md?raw";
 import contenteditableApiMarkdown from "../../../../docs/api-reference/contenteditable.md?raw";
 import richTextApiMarkdown from "../../../../docs/api-reference/rich-text.md?raw";
@@ -195,6 +199,8 @@ export const docPages = {
   annotationApi: docPage("/docs/api/annotation", annotationApiMarkdown),
   calendarApi: docPage("/docs/api/calendar", `[시간·반복·거절 계약: Editing의 Calendar protocol profile](/docs/api/editing#calendar-protocol-profile-rc)\n\n${calendarApiMarkdown}`),
   calendarDocumentApi: docPage("/docs/api/calendar-document", `${calendarDocumentContractMarkdown}\n\n${calendarDocumentApiMarkdown}`),
+  objectDocumentApi: docPage("/docs/api/object-document", `${objectDocumentContractMarkdown}\n\n${objectDocumentApiMarkdown}`),
+  canvasApi: docPage("/docs/api/canvas", `${canvasContractMarkdown}\n\n${canvasApiMarkdown}`),
   webApi: docPage("/docs/api/web", webApiMarkdown),
   contenteditableApi: docPage("/docs/api/contenteditable", contenteditableApiMarkdown),
   richTextApi: docPage("/docs/api/rich-text", richTextApiMarkdown),
diff --git a/site/src/routes/widgets/CanvasWidgetRoute.tsx b/site/src/routes/widgets/CanvasWidgetRoute.tsx
index 6190f8fc..3591e9c4 100644
--- a/site/src/routes/widgets/CanvasWidgetRoute.tsx
+++ b/site/src/routes/widgets/CanvasWidgetRoute.tsx
@@ -1,394 +1,19 @@
-import { useRef, useState, type KeyboardEvent, type PointerEvent } from "react";
-import { createObjectEditor, type ObjectDocument } from "@interactive-os/json-document-editing";
-import { useEditing } from "@interactive-os/json-document-react";
-import {
-  activeDescendantContainerProps,
-  activeDescendantItemProps,
-  createWebPointerSession,
-  projectWebWidgetState,
-} from "@interactive-os/json-document-web";
-import {
-  createCanvasGestureSession,
-  editingCommandFromWebKeyboardStroke,
-  applyAffordance,
-  commitAffordance,
-  dragAffordance,
-  escapeAffordance,
-  forbiddenCursor,
-  marqueeAffordance,
-  marqueeHitsAffordance,
-  nudgeAffordance,
-  panAffordance,
-  planeHitAffordance,
-  snapAffordance,
-} from "@interactive-os/json-document-affordance";
-import { initialObjectDemoDocument } from "../../shared/demo-workbench/object-demo-document";
-import { SelectableItem } from "@interactive-os/json-document-ui-primitives-react";
-import { classes, ui } from "../../shared/ui/styles";
-import { editingItemProps } from "@interactive-os/json-document-react";
+import { useState } from "react";
+import { createObjectEditor } from "@interactive-os/json-document-editing";
+import { useEditingSnapshot } from "@interactive-os/json-document-react";
+import { CanvasHand } from "@interactive-os/json-document-canvas";
+import { canvasCreationStyle, canvasProofDocument } from "../../shared/demo-workbench/canvas-demo-document";
 import { WidgetDemoFrame } from "./WidgetDemoFrame";
-
-type DragState = {
-  readonly type: "drag";
-  readonly ids: ReadonlyArray<string>;
-  readonly originX: number;
-  readonly originY: number;
-  readonly dx: number;
-  readonly dy: number;
-};
-
-type MarqueeState = {
-  readonly type: "marquee";
-  readonly originX: number;
-  readonly originY: number;
-  readonly x: number;
-  readonly y: number;
-  readonly width: number;
-  readonly height: number;
-};
-
-type PanGesture = {
-  readonly type: "pan";
-  readonly originX: number;
-  readonly originY: number;
-};
-
-type CanvasGesture = DragState | MarqueeState | PanGesture;
+import { ui } from "../../shared/ui/styles";
 
 export function CanvasWidgetRoute() {
-  const [editor] = useState(() => createObjectEditor(initialObjectDemoDocument));
-  const [gesture, setGesture] = useState<CanvasGesture | null>(null);
-  const [pan, setPan] = useState({ x: 0, y: 0 });
-  const [space, setSpace] = useState(false);
-  const surface = useRef<HTMLDivElement>(null);
-  const [gestureSession] = useState(() => createCanvasGestureSession<CanvasGesture>({
-    onBegin: setGesture,
-    onPreview: setGesture,
-    onCommit: () => setGesture(null),
-    onCancel: () => setGesture(null),
-  }));
-  const [pointerSession] = useState(() => createWebPointerSession<"drag" | "marquee" | "pan">({
-    onCancel: (_kind, reason) => gestureSession.cancel(reason === "lost-capture" ? "lost-capture" : "pointer-cancel"),
-  }));
-  const drag = gesture?.type === "drag" ? gesture : null;
-  const marquee = gesture?.type === "marquee" ? gesture : null;
-  const panGesture = gesture?.type === "pan" ? gesture : null;
-  const editing = useEditing({
-    source: editor,
-    selectedKeys: editor.selectedObjects.map((object) => object.id),
-    focusKey: editor.snapshot.selection.primaryKey,
-    onSelect: (objectId, mode) => {
-      editor.dispatch({
-        type: "selection.set",
-        objectIds: [objectId],
-        mode,
-      });
-    },
-    keyboard: {
-      resolve: (stroke) => {
-        const command = editingCommandFromWebKeyboardStroke(stroke);
-        return command?.type === "delete" ? command : null;
-      },
-      focusKey: () => editor.snapshot.selection.primaryKey ?? undefined,
-      neighbor: () => null,
-      onDelete: () => {
-        editor.dispatch({ type: "selection.remove" });
-      },
-    },
-  });
-  const document = editing.snapshot.value as ObjectDocument;
-
-  function handlePointerDown(event: PointerEvent<HTMLElement>, objectId?: string) {
-    event.preventDefault();
-    surface.current?.focus();
-    if (surface.current === null) return;
-    let grabbing = false;
-    applyAffordance(panAffordance({ spaceKey: space, buttons: event.buttons }), {
-      cursor: (cursor) => {
-        grabbing = cursor === "grabbing";
-      },
-      hand: (hand) => {
-        if (hand.type === "translate") grabbing = true;
-      },
-    });
-    if (grabbing || (space && event.buttons === 1)) {
-      pointerSession.begin(surface.current, event.pointerId, "pan");
-      gestureSession.begin({ type: "pan", originX: event.clientX - pan.x, originY: event.clientY - pan.y });
-      return;
-    }
-    if (objectId) {
-      applyAffordance(
-        planeHitAffordance({
-          hitId: objectId,
-          selectedIds: editor.selectedObjects.map((object) => object.id),
-          shiftKey: event.shiftKey,
-          metaKey: event.metaKey,
-          ctrlKey: event.ctrlKey,
-        }),
-        {
-          hand: (hand) => {
-            if (hand.type !== "select" || !hand.objectIds) return;
-            editor.dispatch({
-              type: "selection.set",
-              objectIds: hand.objectIds,
-              mode: "replace",
-            });
-            pointerSession.begin(surface.current!, event.pointerId, "drag");
-            gestureSession.begin({
-              type: "drag",
-              ids: hand.objectIds,
-              originX: event.clientX,
-              originY: event.clientY,
-              dx: 0,
-              dy: 0,
-            });
-          },
-        },
-      );
-      return;
-    }
-    const origin = { x: event.nativeEvent.offsetX, y: event.nativeEvent.offsetY };
-    pointerSession.begin(surface.current, event.pointerId, "marquee");
-    gestureSession.begin({ type: "marquee", originX: origin.x, originY: origin.y, x: origin.x, y: origin.y, width: 0, height: 0 });
-  }
-
-  function handlePointerMove(event: PointerEvent<HTMLDivElement>) {
-    pointerSession.preview(event.pointerId, (kind) => kind);
-    applyAffordance(forbiddenCursor({ allowed: true, dropping: drag !== null }), {
-      cursor: (cursor) => {
-        event.currentTarget.style.cursor = space ? "grab" : cursor;
-      },
-    });
-    if (panGesture) {
-      applyAffordance(
-        panAffordance({
-          spaceKey: true,
-          buttons: event.buttons,
-          origin: { x: panGesture.originX, y: panGesture.originY },
-          point: { x: event.clientX, y: event.clientY },
-        }),
-        {
-          cursor: (cursor) => {
-            event.currentTarget.style.cursor = cursor;
-          },
-          hand: (hand) => {
-            if (hand.type !== "translate") return;
-            setPan({ x: hand.dx, y: hand.dy });
-          },
-        },
-      );
-      return;
-    }
-    if (drag) {
-      applyAffordance(
-        dragAffordance({ x: drag.originX, y: drag.originY }, { x: event.clientX, y: event.clientY }),
-        {
-          cursor: (cursor) => {
-            event.currentTarget.style.cursor = cursor;
-          },
-          hand: (hand) => {
-          if (hand.type === "translate") gestureSession.preview({ ...drag, dx: hand.dx, dy: hand.dy });
-          },
-        },
-      );
-      return;
-    }
-    if (marquee) {
-      const origin = { x: marquee.originX, y: marquee.originY };
-      const point = { x: event.nativeEvent.offsetX, y: event.nativeEvent.offsetY };
-      applyAffordance(marqueeAffordance(origin, point, event), {
-        cursor: (cursor) => {
-          event.currentTarget.style.cursor = cursor;
-        },
-        hand: (hand) => {
-          if (hand.type !== "select" || !hand.rect) return;
-          gestureSession.preview({ type: "marquee", originX: origin.x, originY: origin.y, ...hand.rect });
-        },
-      });
-    }
-  }
-
-  function handlePointerUp(event: PointerEvent<HTMLDivElement>) {
-    pointerSession.commit(event.pointerId);
-    if (panGesture) {
-      gestureSession.commit();
-      return;
-    }
-    if (drag) {
-      const committed = commitAffordance(
-        dragAffordance({ x: drag.originX, y: drag.originY }, { x: event.clientX, y: event.clientY }),
-      );
-      if (committed) {
-        applyAffordance(committed, {
-          commit: (hand) => {
-            if (hand.type !== "translate") return;
-            applyAffordance(
-              snapAffordance(
-                { x: hand.dx, y: hand.dy },
-                { grid: 8, disable: event.metaKey || event.ctrlKey },
-              ),
-              {
-                hand: (snapped) => {
-                  if (snapped.type !== "translate") return;
-                  editor.dispatch({
-                    type: "object.translate",
-                    objectIds: drag.ids,
-                    dx: snapped.dx,
-                    dy: snapped.dy,
-                  });
-                },
-              },
-            );
-          },
-        });
-      }
-      gestureSession.commit();
-      return;
-    }
-    if (marquee) {
-      const origin = { x: marquee.originX, y: marquee.originY };
-      const point = { x: event.nativeEvent.offsetX, y: event.nativeEvent.offsetY };
-      const committed = commitAffordance(marqueeAffordance(origin, point, event));
-      if (committed) {
-        applyAffordance(committed, {
-          commit: (hand) => {
-            if (hand.type === "clear") {
-              editor.dispatch({ type: "selection.set", objectIds: [], mode: "replace" });
-              return;
-            }
-            if (hand.type !== "select" || !hand.rect) return;
-            applyAffordance(marqueeHitsAffordance({ rect: hand.rect, items: document.objects }), {
-              hand: (hits) => {
-                if (hits.type !== "select" || !hits.objectIds || hits.objectIds.length === 0) return;
-                editor.dispatch({
-                  type: "selection.set",
-                  objectIds: hits.objectIds,
-                  mode: hand.operation,
-                });
-              },
-            });
-          },
-        });
-      }
-      gestureSession.commit();
-    }
-  }
-
-  function onKeyDown(event: KeyboardEvent<HTMLDivElement>) {
-    if (event.key === " ") {
-      setSpace(true);
-      event.preventDefault();
-    }
-    applyAffordance(
-      escapeAffordance({
-        key: event.key,
-        grabbing: gesture !== null,
-        selected: editor.selectedObjects.length > 0,
-      }),
-      {
-        hand: (hand) => {
-          if (hand.type === "cancel") {
-            const activePointer = pointerSession.getSnapshot();
-            if (activePointer) pointerSession.cancel(activePointer.pointerId);
-            else gestureSession.cancel();
-            event.preventDefault();
-            return;
-          }
-          if (hand.type !== "clear") return;
-          editor.dispatch({ type: "selection.set", objectIds: [], mode: "replace" });
-          event.preventDefault();
-        },
-      },
-    );
-    applyAffordance(nudgeAffordance(event), {
-      hand: (hand) => {
-        if (hand.type !== "nudge") return;
-        const ids = editor.selectedObjects.map((object) => object.id);
-        if (ids.length === 0) return;
-        editor.dispatch({ type: "object.translate", objectIds: ids, dx: hand.dx, dy: hand.dy });
-        event.preventDefault();
-      },
-    });
-    editing.getKeyDownHandler()(event);
-  }
-
-  return (
-    <WidgetDemoFrame
-      title="Canvas"
-      description="Drag, marquee, nudge, snap, and pan use applyAffordance. Writes go through commitAffordance."
-      illustration="peek"
-      widgetLabel="Canvas"
-      widget={(
-        <div
-          ref={surface}
-          className="relative min-h-[16rem] overflow-hidden"
-          role="listbox"
-          aria-multiselectable="true"
-          aria-label="Canvas objects"
-          {...activeDescendantContainerProps(
-            editor.snapshot.selection.primaryKey === null
-              ? null
-              : canvasObjectId(editor.snapshot.selection.primaryKey),
-          )}
-          onPointerDown={(event) => handlePointerDown(event)}
-          onPointerMove={handlePointerMove}
-          onPointerUp={handlePointerUp}
-          onPointerCancel={(event) => pointerSession.cancel(event.pointerId)}
-          onLostPointerCapture={(event) => pointerSession.cancel(event.pointerId, "lost-capture")}
-          onKeyDown={onKeyDown}
-          onKeyUp={(event) => {
-            if (event.key === " ") setSpace(false);
-          }}
-        >
-          <div style={{ transform: `translate(${pan.x}px, ${pan.y}px)` }}>
-            {document.objects.map((object) => {
-              const offset = drag?.ids.includes(object.id) ? drag : null;
-              const option = editingItemProps(editing.getItem(object.id));
-              return (
-                <SelectableItem
-                  as="div"
-                  key={object.id}
-                  className={ui.interactive.planeItem}
-                  style={{
-                    left: object.x + (offset?.dx ?? 0),
-                    top: object.y + (offset?.dy ?? 0),
-                    width: object.width,
-                    height: object.height,
-                    backgroundColor: object.color,
-                    color: "rgb(var(--color-foreground-canvas-object))",
-                  }}
-                  selected={option.selected}
-                  focus={option.focus}
-                  dragging={offset !== null}
-                  {...activeDescendantItemProps(canvasObjectId(object.id))}
-                  {...projectWebWidgetState({ role: "option", selected: option.selected })}
-                  onPointerDown={(event) => {
-                    event.stopPropagation();
-                    handlePointerDown(event, object.id);
-                  }}
-                >
-                  {object.label}
-                </SelectableItem>
-              );
-            })}
-            {marquee ? (
-              <div
-                className={classes("pointer-events-none absolute", ui.surface.marquee)}
-                style={{ left: marquee.x, top: marquee.y, width: marquee.width, height: marquee.height }}
-              />
-            ) : null}
-          </div>
-        </div>
-      )}
-      values={[
-        { label: "selectedKeys", value: editor.selectedObjects.map((object) => object.id), testId: "widget-canvas-selected", size: "compact" },
-        { label: "focus", value: editor.snapshot.selection.primaryKey, testId: "widget-canvas-focus", size: "compact" },
-        { label: "selection", value: editing.snapshot.selection, testId: "widget-canvas-selection", size: "compact" },
-      ]}
-    />
-  );
-}
-
-function canvasObjectId(objectId: string): string {
-  return `widget-canvas-option-${objectId}`;
+  const [editor] = useState(() => createObjectEditor(canvasProofDocument));
+  const snapshot = useEditingSnapshot(editor);
+  return <WidgetDemoFrame title="Canvas" description="같은 Canvas Hand를 다른 fixture와 관찰 UI에 조합합니다. 선택·조작·History는 정본 API가 소유합니다."
+    widgetLabel="Canvas Hand" widget={<CanvasHand className={ui.product.embedded} editor={editor} creationStyle={canvasCreationStyle} slideStyle={{ background: "rgb(var(--color-background-canvas))" }} />}
+    values={[
+      { label: "selectedKeys", value: snapshot.selection.keys, testId: "widget-canvas-selected", size: "compact" },
+      { label: "focus", value: snapshot.selection.primaryKey, testId: "widget-canvas-focus", size: "compact" },
+      { label: "selection", value: snapshot.selection, testId: "widget-canvas-selection", size: "compact" },
+    ]} />;
 }
diff --git a/site/src/shared/demo-workbench/canvas-demo-document.ts b/site/src/shared/demo-workbench/canvas-demo-document.ts
new file mode 100644
index 00000000..dbf9a81f
--- /dev/null
+++ b/site/src/shared/demo-workbench/canvas-demo-document.ts
@@ -0,0 +1,16 @@
+import type { CanvasDocument } from "@interactive-os/json-document-object-document";
+import type { CanvasCreationStyle } from "@interactive-os/json-document-canvas";
+
+export const emptyCanvasDocument: CanvasDocument = { profile: "canvas/1", width: 1280, height: 720, objects: [] };
+
+// Persisted artwork colors are product data, not UI design tokens.
+export const canvasCreationStyle: CanvasCreationStyle = { color: "#b6c8e8", textColor: "#253044", fontSize: 36, strokeWidth: 4 };
+
+export const canvasProofDocument: CanvasDocument = {
+  ...emptyCanvasDocument,
+  objects: [
+    { id: "title", kind: "text", x: 96, y: 96, width: 660, height: 96, label: "One slide. Your ideas.", color: "#253044", fontSize: 48 },
+    { id: "rectangle", kind: "rectangle", x: 96, y: 264, width: 400, height: 240, label: "", color: "#b6c8e8" },
+    { id: "ellipse", kind: "ellipse", x: 616, y: 264, width: 240, height: 240, label: "", color: "#e8bdab" },
+  ],
+};
diff --git a/site/src/shared/demo-workbench/demo-sources.ts b/site/src/shared/demo-workbench/demo-sources.ts
index b8ba9902..7e0f3431 100644
--- a/site/src/shared/demo-workbench/demo-sources.ts
+++ b/site/src/shared/demo-workbench/demo-sources.ts
@@ -1,4 +1,12 @@
 import type { CodeLanguage } from "../ui/code-tokens";
+import objectModelSource from "../../../../packages/json-document-object-document/src/object-model.ts?raw";
+import objectValidationSource from "../../../../packages/json-document-object-document/src/object-validation.ts?raw";
+import objectOperationSource from "../../../../packages/json-document-object-document/src/object-operation.ts?raw";
+import objectProjectionSource from "../../../../packages/json-document-object-document/src/object-projection.ts?raw";
+import canvasHandSource from "../../../../packages/json-document-canvas/src/canvas-hand.tsx?raw";
+import canvasInteractionSource from "../../../../packages/json-document-canvas/src/use-canvas-hand.ts?raw";
+import canvasObjectViewSource from "../../../../packages/json-document-canvas/src/canvas-object-view.tsx?raw";
+import editingSnapshotSource from "../../../../packages/json-document-react/src/editing-snapshot.ts?raw";
 import pointerTrackingSource from "../../../../packages/json-document/src/foundation/patch/track.ts?raw";
 import editingObservationSource from "../../../../packages/json-document-react/src/editing-observation.ts?raw";
 import calendarDocumentModelSource from "../../../../packages/json-document-calendar-document/src/calendar-model.ts?raw";
@@ -140,6 +148,8 @@ export type DemoSourceFile = {
 };
 
 const packageReferencePaths = new Map([
+  ["packages/json-document-object-document/", "/docs/api/object-document"],
+  ["packages/json-document-canvas/", "/docs/api/canvas"],
   ["packages/json-document/", "/docs/api/json-document"],
   ["packages/json-document-selection/", "/docs/api/selection"],
   ["packages/json-document-editing/", "/docs/api/editing"],
@@ -190,6 +200,14 @@ const excludedSources = new Set([
   "routes/widgets/WidgetDemoFrame.tsx",
 ]);
 const registeredUsageSources = new Map<string, string>([
+  ["packages/json-document-object-document/src/object-model.ts", objectModelSource],
+  ["packages/json-document-object-document/src/object-validation.ts", objectValidationSource],
+  ["packages/json-document-object-document/src/object-operation.ts", objectOperationSource],
+  ["packages/json-document-object-document/src/object-projection.ts", objectProjectionSource],
+  ["packages/json-document-canvas/src/canvas-hand.tsx", canvasHandSource],
+  ["packages/json-document-canvas/src/use-canvas-hand.ts", canvasInteractionSource],
+  ["packages/json-document-canvas/src/canvas-object-view.tsx", canvasObjectViewSource],
+  ["packages/json-document-react/src/editing-snapshot.ts", editingSnapshotSource],
   ["packages/json-document/src/foundation/patch/track.ts", pointerTrackingSource],
   ["packages/json-document-calendar-document/src/calendar-model.ts", calendarDocumentModelSource],
   ["packages/json-document-calendar-document/src/calendar-projection.ts", calendarDocumentProjectionSource],
@@ -324,6 +342,39 @@ const registeredUsageSources = new Map<string, string>([
   ["packages/json-document-zod/src/index.ts", zodSource],
 ]);
 const registeredPublicUsages = [
+  {
+    packageName: "@interactive-os/json-document-canvas",
+    symbol: "CanvasHand",
+    sourcePath: "packages/json-document-canvas/src/canvas-hand.tsx",
+  },
+  {
+    packageName: "@interactive-os/json-document-canvas",
+    symbol: "CanvasHand",
+    sourcePath: "packages/json-document-canvas/src/use-canvas-hand.ts",
+  },
+  {
+    packageName: "@interactive-os/json-document-canvas",
+    symbol: "CanvasHand",
+    sourcePath: "packages/json-document-canvas/src/canvas-object-view.tsx",
+  },
+  {
+    packageName: "@interactive-os/json-document-canvas",
+    symbol: "useCanvasHand",
+    sourcePath: "packages/json-document-canvas/src/use-canvas-hand.ts",
+  },
+  {
+    packageName: "@interactive-os/json-document-react",
+    symbol: "useEditingSnapshot",
+    sourcePath: "packages/json-document-react/src/editing-snapshot.ts",
+  },
+  ...(["ObjectDocument", "CanvasDocument", "DocumentObject", "CanvasObject"] as const).map((symbol) => ({ packageName: "@interactive-os/json-document-object-document", symbol, sourcePath: "packages/json-document-object-document/src/object-model.ts" })),
+  ...(["assertObjectDocument", "assertCanvasDocument", "parseCanvasDocument", "serializeCanvasDocument"] as const).map((symbol) => ({ packageName: "@interactive-os/json-document-object-document", symbol, sourcePath: "packages/json-document-object-document/src/object-validation.ts" })),
+  ...(["createCanvasObject", "createCanvasPath", "projectObject", "transformObject"] as const).map((symbol) => ({ packageName: "@interactive-os/json-document-object-document", symbol, sourcePath: "packages/json-document-object-document/src/object-projection.ts" })),
+  {
+    packageName: "@interactive-os/json-document-object-document",
+    symbol: "planObjectOperation",
+    sourcePath: "packages/json-document-object-document/src/object-operation.ts",
+  },
   {
     packageName: "@interactive-os/json-document-web",
     symbol: "textSelectionFromControl",
diff --git a/site/src/shared/demo-workbench/object-demo-document.ts b/site/src/shared/demo-workbench/object-demo-document.ts
index 61bec6c9..6fcb5df7 100644
--- a/site/src/shared/demo-workbench/object-demo-document.ts
+++ b/site/src/shared/demo-workbench/object-demo-document.ts
@@ -1,4 +1,4 @@
-import type { ObjectDocument } from "@interactive-os/json-document-editing";
+import type { ObjectDocument } from "@interactive-os/json-document-object-document";
 
 // These colors are editable document data, not design-system presentation values.
 export const objectDemoColors = ["#de6d55", "#60786f", "#c4a35a", "#4d6a8a"] as const;
@@ -10,10 +10,3 @@ export const initialObjectDemoDocument: ObjectDocument = {
     { id: "chip", label: "Chip", x: 96, y: 136, width: 120, height: 72, color: "#c4a35a" },
   ],
 };
-
-export const canvasDemoDocument: ObjectDocument = {
-  objects: [
-    ...initialObjectDemoDocument.objects,
-    { id: "lock", label: "Lock", x: 248, y: 136, width: 72, height: 72, color: "#8a8a8a" },
-  ],
-};
diff --git a/site/src/shared/ui/styles.ts b/site/src/shared/ui/styles.ts
index f6f7b849..eacb236b 100644
--- a/site/src/shared/ui/styles.ts
+++ b/site/src/shared/ui/styles.ts
@@ -85,6 +85,7 @@ export const ui = {
   },
   product: {
     frame: "rounded-surface bg-background-canvas font-sans text-foreground-default antialiased shadow-surface",
+    embedded: "rounded-none shadow-none",
   },
   demoWorkbench: {
     header: "sticky top-0 z-20 border-b border-line-subtle/40 bg-background-subtle px-2 pt-2",
diff --git a/site/tests/browser/canvas-slice.spec.ts b/site/tests/browser/canvas-slice.spec.ts
new file mode 100644
index 00000000..5cdbff91
--- /dev/null
+++ b/site/tests/browser/canvas-slice.spec.ts
@@ -0,0 +1,91 @@
+import { expect, test, type Page } from "@playwright/test";
+
+for (const route of ["/demo/canvas", "/widgets/canvas"]) {
+  test(`${route} uses shared icon toolbar and hover/focus tooltips`, async ({ page }) => {
+    await page.goto(route);
+    const toolbar = page.getByRole("toolbar", { name: "Canvas tools" });
+    const buttons = toolbar.getByRole("button");
+    await expect(buttons).toHaveCount(9);
+    for (const button of await buttons.all()) {
+      await expect(button).toHaveAttribute("data-ui-presentation", "icon");
+      await expect(button.locator('svg[aria-hidden="true"]')).toHaveCount(1);
+      await expect(button).toHaveCSS("border-top-width", "0px");
+      const box = await button.boundingBox();
+      expect(box?.width).toBe(32); expect(box?.height).toBe(32);
+    }
+    const draw = toolbar.getByRole("button", { name: "그리기", exact: true });
+    const tooltip = toolbar.getByRole("tooltip", { name: "그리기", exact: true });
+    await expect(tooltip).toBeHidden();
+    await draw.hover(); await expect(tooltip).toBeVisible();
+    await page.mouse.move(0, 0); await expect(tooltip).toBeHidden();
+    await draw.focus(); await expect(tooltip).toBeVisible();
+    await expect(draw).not.toHaveCSS("box-shadow", "none");
+    await draw.press("Enter"); await expect(draw).toHaveAttribute("aria-pressed", "true");
+    await expect(page.locator("[data-canvas-slide]")).toHaveAttribute("data-tool", "path");
+  });
+}
+
+async function point(page: Page, x: number, y: number) {
+  const box = await page.locator("[data-canvas-slide]").boundingBox();
+  if (!box) throw new Error("Missing Canvas slide");
+  return { x: box.x + x * box.width / 1280, y: box.y + y * box.height / 720 };
+}
+
+async function create(page: Page, tool: string, from: [number, number], to: [number, number]) {
+  await page.getByRole("button", { name: tool, exact: true }).click();
+  const a = await point(page, ...from), b = await point(page, ...to);
+  await page.mouse.move(a.x, a.y); await page.mouse.down();
+  await page.mouse.move(b.x, b.y, { steps: 8 }); await page.mouse.up();
+}
+
+test("Canvas composes one slide and reopens the same JSON through the canonical Hand", async ({ page }) => {
+  await page.goto("/demo/canvas");
+  await expect(page.locator("[data-canvas-object]")).toHaveCount(0);
+  await create(page, "사각형", [100, 280], [440, 480]);
+  await create(page, "타원", [600, 280], [820, 480]);
+  await create(page, "글자", [100, 80], [920, 200]);
+  const text = page.getByRole("textbox", { name: "Canvas text", exact: true });
+  await text.fill("One slide\n글자·도형·그리기");
+  await text.press("ControlOrMeta+Enter");
+  await create(page, "그리기", [100, 560], [700, 620]);
+  await expect(page.locator("[data-canvas-object]")).toHaveCount(4);
+  await expect(page.locator("[data-canvas-slide]")).toHaveAttribute("data-tool", "select");
+
+  await page.getByRole("button", { name: "JSON", exact: true }).click();
+  const json = page.getByRole("textbox", { name: "Canvas JSON document" });
+  const saved = await json.inputValue();
+  expect(JSON.parse(saved).objects.map((object: { kind: string }) => object.kind)).toEqual(["rectangle", "ellipse", "text", "path"]);
+  await json.fill('{"profile":"canvas/1","width":1280,"height":720,"objects":[]}');
+  await page.getByRole("button", { name: "JSON 열기" }).click();
+  await expect(page.locator("[data-canvas-object]")).toHaveCount(0);
+  await page.getByRole("button", { name: "JSON", exact: true }).click();
+  await json.fill(saved);
+  await page.getByRole("button", { name: "JSON 열기" }).click();
+  await expect(page.locator("[data-canvas-object]")).toHaveCount(4);
+  await page.getByRole("button", { name: "실행 취소" }).click();
+  await expect(page.locator("[data-canvas-object]")).toHaveCount(0);
+  await page.getByRole("button", { name: "다시 실행" }).click();
+  await expect(page.locator("[data-canvas-object]")).toHaveCount(4);
+});
+
+test("Canvas move and resize are single history steps and Escape cancels a gesture", async ({ page }) => {
+  await page.goto("/demo/canvas");
+  await create(page, "사각형", [100, 100], [300, 200]);
+  const object = page.locator("[data-canvas-object]");
+  const a = await point(page, 150, 150), b = await point(page, 220, 190);
+  await page.mouse.move(a.x, a.y); await page.mouse.down(); await page.mouse.move(b.x, b.y, { steps: 6 });
+  await page.keyboard.press("Escape"); await page.mouse.up();
+  await expect(object).toHaveAttribute("x", "100");
+  await page.mouse.move(a.x, a.y); await page.mouse.down(); await page.mouse.move(b.x, b.y); await page.mouse.up();
+  expect(Number(await object.getAttribute("x"))).toBeCloseTo(170);
+  const handle = page.locator('[data-resize-edge="se"]');
+  const box = await handle.boundingBox(); if (!box) throw new Error("Missing resize handle");
+  await page.mouse.move(box.x + box.width / 2, box.y + box.height / 2); await page.mouse.down();
+  await page.mouse.move(box.x + box.width / 2 + 40, box.y + box.height / 2 + 30); await page.mouse.up();
+  expect(Number(await object.getAttribute("width"))).toBeGreaterThan(200);
+  await page.getByRole("button", { name: "실행 취소" }).click();
+  expect(Number(await object.getAttribute("width"))).toBeCloseTo(200);
+  expect(Number(await object.getAttribute("x"))).toBeCloseTo(170);
+  await page.getByRole("button", { name: "실행 취소" }).click();
+  expect(Number(await object.getAttribute("x"))).toBeCloseTo(100);
+});
diff --git a/site/tests/browser/editor-slice-demos.spec.ts b/site/tests/browser/editor-slice-demos.spec.ts
index f2ff27ac..75d52205 100644
--- a/site/tests/browser/editor-slice-demos.spec.ts
+++ b/site/tests/browser/editor-slice-demos.spec.ts
@@ -1,30 +1,5 @@
 import { expect, test } from "@playwright/test";
 
-test("Canvas selection keeps objects absolutely positioned", async ({ page }) => {
-  await page.goto("/demo/canvas");
-  const note = page.getByRole("button", { name: "Note" });
-  const card = page.getByRole("button", { name: "Card" });
-  const chip = page.getByRole("button", { name: "Chip" });
-  const before = await Promise.all([note, card, chip].map((item) => item.boundingBox()));
-  await card.click();
-  for (const item of [note, card, chip]) {
-    await expect.poll(() => item.evaluate((el) => getComputedStyle(el).position)).toBe("absolute");
-  }
-  const after = await Promise.all([note, card, chip].map((item) => item.boundingBox()));
-  after.forEach((box, index) => {
-    expect(box?.x).toBeCloseTo(before[index]?.x ?? 0, 0);
-    expect(box?.y).toBeCloseTo(before[index]?.y ?? 0, 0);
-  });
-});
-
-test("Canvas fills a selected object", async ({ page }) => {
-  await page.goto("/demo/canvas");
-  await expect(page.getByRole("heading", { level: 1, name: "Canvas", exact: true })).toBeVisible();
-  await page.getByRole("button", { name: "Note" }).click();
-  await page.getByRole("button", { name: "Fill #4d6a8a" }).click();
-  await expect(page.getByRole("button", { name: "Note" })).toHaveCSS("background-color", "rgb(77, 106, 138)");
-});
-
 test("Object routes platform history shortcuts from its editing surface", async ({ page }) => {
   await page.goto("/demo/object");
   const note = page.getByRole("button", { name: "Note" });
@@ -128,229 +103,6 @@ test("Document dogfoods caret and native double and triple click counts", async
   await expect(page.getByTestId("document-click-count")).toHaveText("click count 3");
 });
 
-test("Canvas marquee selects several objects and Escape cancels it", async ({ page }) => {
-  await page.goto("/demo/canvas");
-  const note = page.getByRole("button", { name: "Note" });
-  const card = page.getByRole("button", { name: "Card" });
-  const chip = page.getByRole("button", { name: "Chip" });
-  await card.click();
-  await expect(card).toHaveAttribute("data-selected", "true");
-  await expect(note).toHaveAttribute("data-selected", "false");
-
-  const canvas = page.getByLabel("Canvas", { exact: true });
-  const box = await canvas.boundingBox();
-  if (!box) throw new Error("canvas bounding box");
-  await canvas.focus();
-  await page.mouse.move(box.x + box.width - 8, box.y + box.height - 8);
-  await page.mouse.down();
-  await page.mouse.move(box.x + box.width - 24, box.y + box.height - 24);
-  await page.keyboard.press("Escape");
-  await page.mouse.up();
-  await expect(card).toHaveAttribute("data-selected", "true");
-  await expect(note).toHaveAttribute("data-selected", "false");
-
-  await page.mouse.move(box.x + 8, box.y + 8);
-  await page.mouse.down();
-  await page.mouse.move(box.x + box.width - 8, box.y + box.height - 8);
-  await page.mouse.up();
-  await expect(note).toHaveAttribute("data-selected", "true");
-  await expect(card).toHaveAttribute("data-selected", "true");
-  await expect(chip).toHaveAttribute("data-selected", "true");
-});
-
-test("Canvas drags every selected object together", async ({ page }) => {
-  await page.goto("/demo/canvas");
-  const note = page.getByRole("button", { name: "Note" });
-  const card = page.getByRole("button", { name: "Card" });
-  const chip = page.getByRole("button", { name: "Chip" });
-  const canvas = page.getByLabel("Canvas", { exact: true });
-  const box = await canvas.boundingBox();
-  if (!box) throw new Error("canvas bounding box");
-  await page.mouse.move(box.x + 8, box.y + 8);
-  await page.mouse.down();
-  await page.mouse.move(box.x + box.width - 8, box.y + box.height - 8);
-  await page.mouse.up();
-  await expect(note).toHaveAttribute("data-selected", "true");
-  await expect(card).toHaveAttribute("data-selected", "true");
-  await expect(chip).toHaveAttribute("data-selected", "true");
-
-  const before = await Promise.all([note, card, chip].map((item) => item.evaluate((el) => ({
-    left: parseFloat((el as HTMLElement).style.left),
-    top: parseFloat((el as HTMLElement).style.top),
-  }))));
-  const noteBox = await note.boundingBox();
-  if (!noteBox) throw new Error("note bounding box");
-  await note.hover();
-  await page.mouse.down();
-  await page.mouse.move(noteBox.x + noteBox.width / 2 + 40, noteBox.y + noteBox.height / 2);
-  await page.mouse.up();
-  const after = await Promise.all([note, card, chip].map((item) => item.evaluate((el) => ({
-    left: parseFloat((el as HTMLElement).style.left),
-    top: parseFloat((el as HTMLElement).style.top),
-  }))));
-  const dx = after[0].left - before[0].left;
-  expect(dx).toBeGreaterThan(0);
-  expect(after[1].left - before[1].left).toBe(dx);
-  expect(after[2].left - before[2].left).toBe(dx);
-  expect(after[0].top).toBe(before[0].top);
-  expect(after[1].top).toBe(before[1].top);
-  expect(after[2].top).toBe(before[2].top);
-});
-
-test("Canvas empty click and idle Escape clear selection", async ({ page }) => {
-  await page.goto("/demo/canvas");
-  const note = page.getByRole("button", { name: "Note" });
-  const card = page.getByRole("button", { name: "Card" });
-  const canvas = page.getByLabel("Canvas", { exact: true });
-  await card.click();
-  await expect(card).toHaveAttribute("data-selected", "true");
-  const box = await canvas.boundingBox();
-  if (!box) throw new Error("canvas bounding box");
-  await canvas.click({ position: { x: box.width - 12, y: box.height - 12 } });
-  await expect(card).toHaveAttribute("data-selected", "false");
-  await expect(note).toHaveAttribute("data-selected", "false");
-
-  await note.click();
-  await expect(note).toHaveAttribute("data-selected", "true");
-  await canvas.focus();
-  await page.keyboard.press("Escape");
-  await expect(note).toHaveAttribute("data-selected", "false");
-});
-
-test("Canvas pan moves the viewport without writing object positions", async ({ page }) => {
-  await page.goto("/demo/canvas");
-  const note = page.getByRole("button", { name: "Note" });
-  const canvas = page.getByLabel("Canvas", { exact: true });
-  const origin = await note.boundingBox();
-  if (!origin) throw new Error("note bounding box");
-  await canvas.focus();
-  await page.keyboard.down(" ");
-  await page.mouse.move(origin.x + origin.width / 2, origin.y + origin.height / 2);
-  await page.mouse.down();
-  await page.mouse.move(origin.x + origin.width / 2 + 40, origin.y + origin.height / 2);
-  await page.mouse.up();
-  await page.keyboard.up(" ");
-  const moved = await note.boundingBox();
-  if (!moved) throw new Error("note bounding box after pan");
-  expect(moved.x).toBeGreaterThan(origin.x + 20);
-  await expect(note).toHaveCSS("left", "24px");
-});
-
-test("Canvas nudges a selected object and snaps a drag to the grid", async ({ page }) => {
-  await page.goto("/demo/canvas");
-  const note = page.getByRole("button", { name: "Note" });
-  await note.click();
-  await page.getByLabel("Canvas", { exact: true }).focus();
-  await page.keyboard.press("ArrowRight");
-  await expect(note).toHaveCSS("left", "25px");
-
-  const box = await note.boundingBox();
-  if (!box) throw new Error("note bounding box");
-  await note.hover();
-  await page.mouse.down();
-  await page.mouse.move(box.x + box.width / 2 + 10, box.y + box.height / 2);
-  await page.mouse.up();
-  await expect(note).toHaveCSS("left", "33px");
-  await page.getByRole("button", { name: "Card" }).click();
-  await expect(note).toHaveCSS("left", "33px");
-  await expect(page.getByRole("button", { name: "Card" })).toHaveAttribute("data-selected", "true");
-});
-
-test("Canvas select-all, delete, and locked objects", async ({ page }) => {
-  await page.goto("/demo/canvas");
-  const canvas = page.getByLabel("Canvas", { exact: true });
-  const note = page.getByRole("button", { name: "Note" });
-  const lock = page.getByRole("button", { name: "Lock", exact: true });
-  await canvas.focus();
-  await page.keyboard.press("ControlOrMeta+A");
-  await page.keyboard.press("ControlOrMeta+A");
-  await expect(note).toHaveAttribute("data-selected", "true");
-  await expect(page.getByRole("button", { name: "Card" })).toHaveAttribute("data-selected", "true");
-  await expect(lock).toHaveAttribute("data-selected", "false");
-
-  await lock.click();
-  await expect(lock).toHaveAttribute("data-selected", "false");
-  await expect(note).toHaveAttribute("data-selected", "true");
-
-  await note.click();
-  await canvas.focus();
-  await page.keyboard.press("Delete");
-  await expect(page.getByRole("button", { name: "Note" })).toHaveCount(0);
-});
-
-test("Canvas right-click opens a menu without clearing selection", async ({ page }) => {
-  await page.goto("/demo/canvas");
-  const card = page.getByRole("button", { name: "Card" });
-  const canvas = page.getByLabel("Canvas", { exact: true });
-  await card.click();
-  await expect(card).toHaveAttribute("data-selected", "true");
-  const box = await canvas.boundingBox();
-  if (!box) throw new Error("canvas bounding box");
-  await canvas.click({ button: "right", position: { x: box.width - 12, y: box.height - 12 } });
-  await expect(page.getByRole("menu", { name: "Canvas menu" })).toBeVisible();
-  await expect(card).toHaveAttribute("data-selected", "true");
-  await expect(page.getByRole("button", { name: "Note" })).toHaveAttribute("data-selected", "false");
-});
-
-test("Canvas copy-drag, constrain, resize, and zoom", async ({ page }) => {
-  await page.goto("/demo/canvas");
-  const note = page.getByRole("button", { name: "Note" });
-  const canvas = page.getByLabel("Canvas", { exact: true });
-  await note.click();
-  const before = await note.evaluate((el) => ({
-    left: parseFloat((el as HTMLElement).style.left),
-    top: parseFloat((el as HTMLElement).style.top),
-    width: parseFloat((el as HTMLElement).style.width),
-  }));
-
-  const box = await note.boundingBox();
-  if (!box) throw new Error("note bounding box");
-  await note.hover();
-  await page.mouse.down();
-  await page.keyboard.down("Shift");
-  await page.mouse.move(box.x + box.width / 2 + 48, box.y + box.height / 2 + 6);
-  await page.mouse.up();
-  await page.keyboard.up("Shift");
-  const constrained = await note.evaluate((el) => ({
-    left: parseFloat((el as HTMLElement).style.left),
-    top: parseFloat((el as HTMLElement).style.top),
-  }));
-  expect(constrained.left).toBeGreaterThan(before.left);
-  expect(constrained.top).toBe(before.top);
-
-  await note.click();
-  const handle = page.locator("[data-resize-edge=se][data-object-id=note]");
-  const handleBox = await handle.boundingBox();
-  if (!handleBox) throw new Error("resize handle");
-  await handle.hover();
-  await page.mouse.down();
-  await page.mouse.move(handleBox.x + handleBox.width / 2 + 24, handleBox.y + handleBox.height / 2 + 16);
-  await page.mouse.up();
-  const resized = await note.evaluate((el) => parseFloat((el as HTMLElement).style.width));
-  expect(resized).toBeGreaterThan(before.width);
-
-  await note.click();
-  await page.keyboard.down("Alt");
-  const noteBox = await note.boundingBox();
-  if (!noteBox) throw new Error("note bounding box");
-  await note.hover();
-  await page.mouse.down();
-  await page.mouse.move(noteBox.x + noteBox.width / 2 + 40, noteBox.y + noteBox.height / 2);
-  await page.mouse.up();
-  await page.keyboard.up("Alt");
-  await expect(page.getByRole("button", { name: "Note" })).toHaveCount(2);
-
-  await canvas.focus();
-  await canvas.evaluate((element) => {
-    element.dispatchEvent(new WheelEvent("wheel", { deltaY: -80, ctrlKey: true, bubbles: true, cancelable: true }));
-  });
-  const scale = await canvas.evaluate((element) => {
-    const inner = element.querySelector(":scope > div");
-    return inner ? getComputedStyle(inner).transform : "";
-  });
-  expect(scale).toMatch(/matrix\((1\.[1-9]|[2-9])/);
-});
-
 test("Tree repeated select-all uses the collapsed visible topology", async ({ page }) => {
   await page.goto("/demo/tree");
   await page.getByRole("button", { name: "Collapse Fruit" }).click();
diff --git a/site/tests/browser/widgets.spec.ts b/site/tests/browser/widgets.spec.ts
index 7d7c29ba..7e9a0594 100644
--- a/site/tests/browser/widgets.spec.ts
+++ b/site/tests/browser/widgets.spec.ts
@@ -192,19 +192,16 @@ test("Document reads selected keys, focus, and text offset", async ({ page }) =>
   await expect(page.locator("#widget-document-option-move")).toHaveCount(1);
 });
 
-test("Canvas reads selected objects on a plane", async ({ page }) => {
+test("Canvas proof consumes the same Hand and observes single selection", async ({ page }) => {
   await page.goto("/widgets/canvas");
-  const canvas = page.getByRole("listbox", { name: "Canvas objects" });
-  await page.getByRole("option", { name: "Card" }).click();
-  await expect(canvas).toBeFocused();
-  await expect(canvas).toHaveAttribute("aria-activedescendant", "widget-canvas-option-card");
-  expect(await json(page, "widget-canvas-selected")).toEqual(["card"]);
-  expect(await json(page, "widget-canvas-focus")).toBe("card");
+  await page.locator('[data-canvas-object="rectangle"]').click();
+  expect(await json(page, "widget-canvas-selected")).toEqual(["rectangle"]);
+  expect(await json(page, "widget-canvas-focus")).toBe("rectangle");
   await page.keyboard.press("Delete");
-  await expect(page.getByRole("option", { name: "Card" })).toHaveCount(0);
-  await expect(canvas).toBeFocused();
-  await expect(canvas).toHaveAttribute("aria-activedescendant", "widget-canvas-option-chip");
-  await expect(page.locator("#widget-canvas-option-chip")).toHaveCount(1);
+  await expect(page.locator('[data-canvas-object="rectangle"]')).toHaveCount(0);
+  await page.keyboard.press("ControlOrMeta+z");
+  await expect(page.locator('[data-canvas-object="rectangle"]')).toHaveCount(1);
+  expect(await json(page, "widget-canvas-selected")).toEqual(["rectangle"]);
 });
 
 test("Tree reads visible topology and selected keys", async ({ page }) => {
@@ -309,20 +306,18 @@ test("Board modifier click toggles cards and drag moves a card", async ({ page }
   ]);
 });
 
-test("Canvas escape cancels an in-progress marquee", async ({ page }) => {
+test("Canvas proof cancels drawing without adding an object", async ({ page }) => {
   await page.goto("/widgets/canvas");
-  await page.getByRole("option", { name: "Card" }).click();
-  expect(await json(page, "widget-canvas-selected")).toEqual(["card"]);
-  const canvas = page.getByRole("listbox", { name: "Canvas objects" });
+  await page.getByRole("button", { name: "그리기" }).click();
+  const canvas = page.locator("[data-canvas-slide]");
   const box = await canvas.boundingBox();
   if (!box) throw new Error("canvas bounding box");
-  await canvas.focus();
-  await page.mouse.move(box.x + box.width - 24, box.y + box.height - 24);
+  await page.mouse.move(box.x + 20, box.y + 20);
   await page.mouse.down();
-  await page.mouse.move(box.x + box.width - 8, box.y + box.height - 8);
+  await page.mouse.move(box.x + 80, box.y + 60);
   await page.keyboard.press("Escape");
   await page.mouse.up();
-  expect(await json(page, "widget-canvas-selected")).toEqual(["card"]);
+  await expect(page.locator("[data-canvas-object]")).toHaveCount(3);
 });
 
 async function json(page: Page, testId: string): Promise<unknown> {
diff --git a/site/tests/unit/app-shell.test.tsx b/site/tests/unit/app-shell.test.tsx
index e1e1c913..21deab6b 100644
--- a/site/tests/unit/app-shell.test.tsx
+++ b/site/tests/unit/app-shell.test.tsx
@@ -115,13 +115,13 @@ describe("official site shell", () => {
     )).toBeTruthy();
   }, 10000);
 
-  test("exposes the Calendar owner without closing the other Document Types TBD boundary", async () => {
+  test("exposes Calendar and Object owners without closing the remaining Document Types TBD boundary", async () => {
     resetDocument("/docs/document-types");
     render(<App />);
 
     expect(await screen.findByRole("heading", { level: 1, name: "Document Types · TBD" })).toBeTruthy();
     expect(screen.getByRole("heading", { level: 2, name: "책임" })).toBeTruthy();
-    expect(screen.getByText(/Calendar는 공개 소유자와 소비 경계를 확정했고/)).toBeTruthy();
+    expect(screen.getByText(/Calendar와 Object는 공개 소유자와 소비 경계를 확정했고/)).toBeTruthy();
     expect(screen.getByRole("heading", { level: 2, name: "현재 소유자와 후보" })).toBeTruthy();
     const breadcrumb = within(screen.getByRole("navigation", { name: "Breadcrumb" }));
     expect(breadcrumb.getByRole("link", { name: "Foundation" }).getAttribute("href")).toBe("/docs/foundation");
diff --git a/site/tests/unit/demo-workbench.test.tsx b/site/tests/unit/demo-workbench.test.tsx
index 7f7f12e1..b71b370c 100644
--- a/site/tests/unit/demo-workbench.test.tsx
+++ b/site/tests/unit/demo-workbench.test.tsx
@@ -212,6 +212,11 @@ describe("Demo definition and source discovery", () => {
       "packages/json-document-react/src/editing-observation.ts",
       "packages/json-document-web/src/clipboard.ts",
       "packages/json-document-editing/src/object.ts",
+      "packages/json-document-object-document/src/object-model.ts",
+      "packages/json-document-object-document/src/object-validation.ts",
+      "packages/json-document/src/application/document/create.ts",
+      "packages/json-document-object-document/src/object-projection.ts",
+      "packages/json-document-object-document/src/object-operation.ts",
     ]);
   });
 
@@ -309,13 +314,22 @@ describe("Demo definition and source discovery", () => {
     ]);
   });
 
-  test("registers the Canvas gesture owner source next to Canvas usages", async () => {
-    expect((await discoverDemoSources("routes/canvas-demo/CanvasDemoRoute.tsx")).map((file) => file.path)).toContain(
-      "packages/json-document-affordance/src/canvas-gesture-session.ts",
-    );
-    expect((await discoverDemoSources("routes/widgets/CanvasWidgetRoute.tsx")).map((file) => file.path)).toContain(
-      "packages/json-document-affordance/src/canvas-gesture-session.ts",
-    );
+  test("registers the canonical Canvas Hand, Object document, Editing and gesture closure for both Hosts", async () => {
+    for (const entry of ["routes/canvas-demo/CanvasDemoRoute.tsx", "routes/widgets/CanvasWidgetRoute.tsx"]) {
+      const paths = (await discoverDemoSources(entry)).map((file) => file.path);
+      expect(paths).toEqual(expect.arrayContaining([
+        "packages/json-document-canvas/src/canvas-hand.tsx",
+        "packages/json-document-canvas/src/use-canvas-hand.ts",
+        "packages/json-document-canvas/src/canvas-object-view.tsx",
+        "packages/json-document-object-document/src/object-model.ts",
+        "packages/json-document-object-document/src/object-validation.ts",
+        "packages/json-document-object-document/src/object-operation.ts",
+        "packages/json-document-object-document/src/object-projection.ts",
+        "packages/json-document-editing/src/object.ts",
+        "packages/json-document-affordance/src/gesture-session.ts",
+        "packages/json-document-react/src/editing-snapshot.ts",
+      ]));
+    }
   });
 
   test("keeps each Editing concept lab API next to its owning route", async () => {
diff --git a/site/tsconfig.json b/site/tsconfig.json
index 671c75e4..497d598f 100644
--- a/site/tsconfig.json
+++ b/site/tsconfig.json
@@ -6,6 +6,8 @@
     "moduleResolution": "Bundler",
     "baseUrl": ".",
     "paths": {
+      "@interactive-os/json-document-object-document": ["../packages/json-document-object-document/src/index.ts"],
+      "@interactive-os/json-document-canvas": ["../packages/json-document-canvas/src/index.ts"],
       "@interactive-os/json-document": ["../packages/json-document/src/application/document/index.ts"],
       "@interactive-os/json-document-editing": ["../packages/json-document-editing/src/index.ts"],
       "@interactive-os/json-document-calendar": ["../packages/json-document-calendar/src/index.ts"],
diff --git a/standards/repository-implementation-shape.md b/standards/repository-implementation-shape.md
index e84f48b6..2cf4478e 100644
--- a/standards/repository-implementation-shape.md
+++ b/standards/repository-implementation-shape.md
@@ -238,6 +238,8 @@ Core는 [v3 profile](json-document-v3/profile.md), Editing의 상태·관찰·
 | `packages/json-document-database` | Product-facing Hand | 기본 admin UI와 customization contract를 소유하고 headless domain package를 내부 구현으로 조합 |
 | `packages/json-document-annotation` | Product-facing Hand | Annotation 도구, gesture-to-Intent, SVG projection, transient preview와 comment UI를 소유 |
 | `packages/json-document-calendar` | Product-facing Hand | Calendar editor 관찰, occurrence focus, naming, Web pointer interaction lifecycle을 정본 hook으로 유지 |
+| `packages/json-document-canvas` | Product-facing Hand | Object Editing을 통한 단일 슬라이드 생성·편집·gesture·React UI 조합 |
+| `packages/json-document-object-document` | Document Type | 기존 Object와 Canvas 프로파일의 model·validation·operation·projection·JSON 정본. Core만 의존 |
 | `packages/json-document-calendar-document` | Document Type | Calendar model·validation·operation·projection의 공개 소유자. Editing·Selection·React peer 없이 독립 소비하며 기존 Editing export는 호환 경로 유지 |
 | `packages/json-document-tanstack-table` | Single-native Connector | 하나의 Table/Sheet binding으로 flat 유지 |
 | `packages/json-document-web` | Adapter family | keyboard/clipboard/input/modifier 책임 file과 root facade 유지 |
diff --git a/tsconfig.build.json b/tsconfig.build.json
index ddf971dd..3dd46bf8 100644
--- a/tsconfig.build.json
+++ b/tsconfig.build.json
@@ -4,6 +4,7 @@
   "references": [
     { "path": "./packages/json-document" },
     { "path": "./packages/json-document-selection" },
+    { "path": "./packages/json-document-object-document" },
     { "path": "./packages/json-document-calendar-document" },
     { "path": "./packages/json-document-editing" },
     { "path": "./packages/json-document-react" },
@@ -18,6 +19,7 @@
     { "path": "./packages/json-document-database" },
     { "path": "./packages/json-document-annotation" },
     { "path": "./packages/json-document-calendar" },
+    { "path": "./packages/json-document-canvas" },
     { "path": "./packages/json-document-tanstack-table" },
     { "path": "./packages/json-document-web" },
     { "path": "./packages/json-document-contenteditable" },

From cd5608a834ebb02d439a6ac2f174ead2e8d221f1 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E1=84=8B=E1=85=B2=E1=84=8B=E1=85=AD=E1=86=BC=E1=84=90?=
 =?UTF-8?q?=E1=85=A2?= <teo.v@navercorp.com>
Date: Wed, 9 Sep 2026 18:20:06 +0900
Subject: [PATCH 11/20] =?UTF-8?q?feat(affordance):=20=EC=9E=AC=EC=82=AC?=
 =?UTF-8?q?=EC=9A=A9=20=EA=B0=80=EB=8A=A5=ED=95=9C=20=ED=8F=89=EB=A9=B4=20?=
 =?UTF-8?q?Select=20=ED=94=84=EB=A1=9C=ED=8C=8C=EC=9D=BC=EC=9D=84=20?=
 =?UTF-8?q?=EA=B5=AC=ED=98=84=ED=95=9C=EB=8B=A4?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 docs/api-reference/affordance.md              |  86 +++++++++
 docs/api-reference/canvas.md                  |   4 +-
 docs/api-reference/editing.md                 |   1 +
 docs/public/affordance-select.md              |  14 +-
 docs/public/affordance.md                     |   7 +-
 package-lock.json                             |   2 +
 packages/json-document-affordance/README.md   |   6 +
 .../docs/plane-select.md                      |  90 ++++++++++
 .../json-document-affordance/package.json     |   2 +
 .../json-document-affordance/src/index.ts     |   6 +
 .../src/plane-select.ts                       | 167 ++++++++++++++++++
 .../tests/plane-select.test.ts                | 109 ++++++++++++
 .../json-document-affordance/tsconfig.json    |   2 +-
 packages/json-document-canvas/docs/api.md     |  27 ++-
 .../json-document-canvas/src/canvas-hand.tsx  |  16 +-
 .../src/canvas-object-view.tsx                |  12 +-
 .../src/use-canvas-hand.ts                    | 104 ++++++++---
 .../tests/canvas-hand.test.tsx                | 138 ++++++++++++++-
 .../docs/object-selection.md                  |  23 +++
 packages/json-document-editing/src/object.ts  |  24 ++-
 .../tests/object-editor.test.ts               |  31 ++++
 .../routes/canvas-demo/CanvasDemoRoute.tsx    |   6 +-
 site/src/routes/docs/doc-pages.ts             |   6 +-
 site/src/routes/widgets/CanvasWidgetRoute.tsx |   2 +-
 .../src/shared/demo-workbench/demo-sources.ts |  34 ++++
 site/tests/browser/canvas-slice.spec.ts       |  46 +++++
 site/tests/browser/widgets.spec.ts            |  10 +-
 site/tests/unit/demo-workbench.test.tsx       |  21 +++
 28 files changed, 933 insertions(+), 63 deletions(-)
 create mode 100644 packages/json-document-affordance/docs/plane-select.md
 create mode 100644 packages/json-document-affordance/src/plane-select.ts
 create mode 100644 packages/json-document-affordance/tests/plane-select.test.ts
 create mode 100644 packages/json-document-editing/docs/object-selection.md

diff --git a/docs/api-reference/affordance.md b/docs/api-reference/affordance.md
index 370e11f0..da183914 100644
--- a/docs/api-reference/affordance.md
+++ b/docs/api-reference/affordance.md
@@ -363,6 +363,11 @@ createInteractionHandleSession(): InteractionHandleSession
 ```ts
 createLineFocusSession<Key extends string>(options: { readonly initialKey?: Key | null; readonly onFocus: (key: Key | null) => void; readonly wrap?: boolean; }): LineFocusSession<Key>
 ```
+## `createPlaneSelectProfile`
+
+```ts
+createPlaneSelectProfile(options?: PlaneSelectProfileOptions): PlaneSelectProfile
+```
 ## `createRenameSession`
 
 ```ts
@@ -690,6 +695,87 @@ panAffordance(input: { readonly spaceKey?: boolean; readonly buttons?: number; r
 ```ts
 planeHitAffordance(input: { readonly hitId: string; readonly selectedIds: ReadonlyArray<string>; readonly shiftKey?: boolean; readonly metaKey?: boolean; readonly ctrlKey?: boolean; readonly nestedId?: string; readonly locked?: boolean; }): AffordancePreview
 ```
+## `PlaneSelectCommit`
+
+```ts
+interface PlaneSelectCommit {
+  readonly selection: PlaneSelectSelection;
+  readonly translation: PlaneSelectTranslation | null;
+}
+```
+## `PlaneSelectContext`
+
+```ts
+interface PlaneSelectContext {
+  readonly items: ReadonlyArray<Rect & { readonly id: string }>;
+  readonly selection: PlaneSelectSelection;
+}
+```
+## `PlaneSelectInput`
+
+```ts
+interface PlaneSelectInput {
+  readonly point: Point;
+  readonly hitKey: string | null;
+  readonly shiftKey?: boolean;
+}
+```
+## `PlaneSelectKeyResult`
+
+```ts
+type PlaneSelectKeyResult =
+  | { readonly type: "selection"; readonly selection: PlaneSelectSelection }
+  | { readonly type: "delete"; readonly keys: readonly string[] }
+  | { readonly type: "edit"; readonly key: string }
+  | { readonly type: "cancel" };
+```
+## `PlaneSelectPreview`
+
+```ts
+interface PlaneSelectPreview {
+  readonly selection: PlaneSelectSelection;
+  readonly marquee: Rect | null;
+  readonly translation: PlaneSelectTranslation | null;
+}
+```
+## `PlaneSelectProfile`
+
+```ts
+interface PlaneSelectProfile {
+  begin(context: PlaneSelectContext, input: PlaneSelectInput): PlaneSelectPreview;
+  preview(point: Point): PlaneSelectPreview | null;
+  commit(point: Point): PlaneSelectCommit | null;
+  cancel(reason?: GestureCancelReason): void;
+  getPreview(): PlaneSelectPreview | null;
+  /** Discrete activation (e.g. Space), not focus. Shift toggles, plain activation replaces. */
+  select(context: PlaneSelectContext, key: string | null, shiftKey?: boolean): PlaneSelectSelection;
+  /** Native editable/IME ownership is checked by the platform binding before calling. */
+  keyDown(stroke: WebKeyboardStroke, context: PlaneSelectContext, grabbing?: boolean): PlaneSelectKeyResult | null;
+}
+```
+## `PlaneSelectProfileOptions`
+
+```ts
+interface PlaneSelectProfileOptions {
+  /** In the input coordinate space. Defaults to 3; movement is latched once crossed. */
+  readonly dragThreshold?: number;
+  readonly contain?: "intersect" | "inside";
+}
+```
+## `PlaneSelectSelection`
+
+```ts
+type PlaneSelectSelection = Extract<KeySelection, { readonly kind: "explicit" }>;
+```
+## `PlaneSelectTranslation`
+
+```ts
+interface PlaneSelectTranslation {
+  readonly keys: readonly string[];
+  readonly dx: number;
+  readonly dy: number;
+}
+```
 ## `Point`
 
 ```ts
diff --git a/docs/api-reference/canvas.md b/docs/api-reference/canvas.md
index 99ee2a89..098addf3 100644
--- a/docs/api-reference/canvas.md
+++ b/docs/api-reference/canvas.md
@@ -30,6 +30,8 @@ interface CanvasHandProps {
   readonly className?: string;
   readonly slideStyle?: CSSProperties;
   readonly label?: string;
+  /** Optional policy instance; one profile per mounted Hand. */
+  readonly selectProfile?: PlaneSelectProfile;
 }
 ```
 ## `CanvasTool`
@@ -40,5 +42,5 @@ type CanvasTool = "select" | CanvasObjectKind;
 ## `useCanvasHand`
 
 ```ts
-useCanvasHand(editor: ObjectEditor, style: CanvasCreationStyle): { document: CanvasDocument; snapshot: import("<repository>/packages/json-document-editing/src/session").EditingSnapshot<ObjectSelection>; ... 16 more ...; surfaceProps: { ...; }; }
+useCanvasHand(editor: ObjectEditor, style: CanvasCreationStyle, selectProfile?: PlaneSelectProfile): { document: CanvasDocument; snapshot: import("<repository>/packages/json-document-editing/src/session").EditingSnapshot<ObjectSelection>; ... 18 more ...; surfaceProps: { ...; }; }
 ```
diff --git a/docs/api-reference/editing.md b/docs/api-reference/editing.md
index 2e310a05..418b5214 100644
--- a/docs/api-reference/editing.md
+++ b/docs/api-reference/editing.md
@@ -1232,6 +1232,7 @@ type ObjectIntent =
       readonly type: "selection.set";
       readonly objectIds: ReadonlyArray<string>;
       readonly mode?: ObjectSelectionMode;
+      readonly primaryKey?: string;
     }
   | { readonly type: "selection.remove" }
   | { readonly type: "selection.fill"; readonly color: string }
diff --git a/docs/public/affordance-select.md b/docs/public/affordance-select.md
index 664aa7a1..6e879dc4 100644
--- a/docs/public/affordance-select.md
+++ b/docs/public/affordance-select.md
@@ -4,6 +4,13 @@ Select는 대상을 집는 손입니다. 클릭은 그 대상으로 바꾸고, S
 범위를 늘리며, Mod는 토글합니다. 화살표는 이웃으로 옮기고, Shift+화살표는
 범위를 늘립니다.
 
+위 문법은 순서가 있는 선택입니다. **평면**에서는 Shift가 범위가 아닌 집합 toggle입니다.
+`createPlaneSelectProfile`이 click/drag 구분, marquee, 집합 이동 preview, Mod+A, Delete,
+Escape, primary 편집까지 연결합니다. Canvas는 이 public profile을 그대로 소비합니다.
+입력·출력·취소·범위의 정본은 [Affordance API · 평면 Select](/docs/api/affordance)에 있습니다.
+
+[실제 Canvas Usage와 Source](/demo/canvas)에서 프로파일을 실행할 수 있습니다.
+
 ```ts
 import {
   applyAffordance,
@@ -55,8 +62,8 @@ function onSelectAll(event: KeyboardEvent) {
 ```
 
 호스트는 보이는 키와 장르 Intent만 넘깁니다. keymap을 덮어쓰지 않습니다.
-이미 고른 상자를 수정 키 없이 누르면 집합을 유지합니다. 안 고른 상자는
-그 상자만으로 바꿉니다.
+`planeHitAffordance`는 press 시점의 집합 유지를 해석하는 단일 연산입니다.
+완성된 프로파일은 drag면 그 집합을 이동하고, drag 없이 release하면 그 상자 하나로 선택합니다.
 
 ## API Reference
 
@@ -92,7 +99,8 @@ Usage와 Source: [Order](/demo/order), [Tree](/demo/tree), [Sheet](/demo/sheet),
 - selection follows focus vs focus-only move는 [Focus](affordance-focus.md)
 - 글 단어·줄 범위는 [Double-click](affordance-double-click.md)·
   [Triple-click](affordance-triple-click.md)·[Caret](affordance-caret.md)
-- 빈 평면의 여러 대상은 [Marquee](affordance-marquee.md)
+- 독립적인 marquee 연산은 [Marquee](affordance-marquee.md), 완성된 평면 문법은
+  `createPlaneSelectProfile`이 제공합니다.
 
 ## Live Demo
 
diff --git a/docs/public/affordance.md b/docs/public/affordance.md
index f3ebaf84..b69962c9 100644
--- a/docs/public/affordance.md
+++ b/docs/public/affordance.md
@@ -94,6 +94,11 @@ Editing은 선택과 작업을 기억합니다. Adapter는 키 chord를 command
 평면 위 객체에서 손은 선택 도구가 기본입니다. 빈 곳과 객체 히트가 다르고,
 고른 집합이 곧 옮길 대상입니다.
 
+최소 평면 문법은 [`createPlaneSelectProfile`](/docs/api/affordance)로 조합되어
+[Canvas Usage](/demo/canvas)에서 실행됩니다. 아래 표에는 단일 Affordance로만 제공되는
+더 넓은 기능도 포함됩니다. 그룹·중첩 선택·축 구속·복제·snap·zoom/pan은 이 최소 프로파일의
+지원 범위가 아닙니다.
+
 근거 축: [Figma 레이어 선택](https://help.figma.com/hc/en-us/articles/360040449873-Select-layers-and-objects),
 [FigJam 선택·이동](https://help.figma.com/hc/en-us/articles/1500004292221-Select-move-and-order-objects-in-FigJam),
 [Illustrator 기본 단축키](https://helpx.adobe.com/illustrator/using/default-keyboard-shortcuts.html),
@@ -108,7 +113,7 @@ Editing은 선택과 작업을 기억합니다. Adapter는 키 chord를 command
 | 손 | 함의 | 수렴 | 상태 |
 | --- | --- | --- | --- |
 | 객체 click | 그 객체만 replace | 안정 | [닫힘](affordance-select.md) |
-| 이미 고른 객체 click (수정 키 없음) | 집합 유지. 다음 드래그의 대상은 집합 전부 | 안정 | [닫힘](affordance-select.md) |
+| 이미 고른 객체 press (수정 키 없음) | 집합 유지. drag는 집합 전부, drag 없이 release하면 단일 선택 | 안정 | [닫힘](affordance-select.md) |
 | 안 고른 객체 click | 집합을 그 객체 하나로 바꿈. 드래그 대상도 그 하나 | 안정 | [닫힘](affordance-select.md) |
 | Shift+click | 집합에 더하거나, 이미 있으면 뺌 | 안정 | [닫힘](affordance-select.md) |
 | Mod+click (⌘/Ctrl) | 호스트가 `nestedId`를 줄 때만 자식. 없으면 일반 click. 리스트박스 토글이 아님 | 갈림 | [닫힘](affordance-select.md) |
diff --git a/package-lock.json b/package-lock.json
index c517ec01..a8f330b1 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -6480,12 +6480,14 @@
       "version": "0.1.0-rc.0",
       "license": "MIT",
       "devDependencies": {
+        "@interactive-os/json-document-selection": "*",
         "@interactive-os/json-document-web": "*",
         "@types/node": "^25.9.0",
         "typescript": "^5.0.0",
         "vitest": "^4.1.7"
       },
       "peerDependencies": {
+        "@interactive-os/json-document-selection": ">=0.1.0-rc.0 <1",
         "@interactive-os/json-document-web": ">=0.1.0-rc.0 <1"
       }
     },
diff --git a/packages/json-document-affordance/README.md b/packages/json-document-affordance/README.md
index 607d3159..810586c9 100644
--- a/packages/json-document-affordance/README.md
+++ b/packages/json-document-affordance/README.md
@@ -93,6 +93,12 @@ open/focus semantics remain outside this geometry contract.
 
 Usage: [Affordance](https://developer-1px.github.io/json-document/docs/affordance)
 
+`createPlaneSelectProfile` composes key selection, click/drag arbitration, marquee,
+set translation previews and keyboard outcomes without Canvas, React, DOM or a
+document dependency. See the owning [Plane Select API contract](docs/plane-select.md).
+The [Canvas Usage](https://developer-1px.github.io/json-document/demo/canvas)
+imports the public profile and injects it into the Hand.
+
 `selectAllAffordance(stroke, state, { repeat: "preserve" })` emits `select-all`
 for Mod+A even when everything is selected. The default editing Usage chooses
 this policy. Omission or `{ repeat: "toggle" }` retains the existing behavior:
diff --git a/packages/json-document-affordance/docs/plane-select.md b/packages/json-document-affordance/docs/plane-select.md
new file mode 100644
index 00000000..d4a1417d
--- /dev/null
+++ b/packages/json-document-affordance/docs/plane-select.md
@@ -0,0 +1,90 @@
+## 평면 Select 프로파일 · RC
+
+`createPlaneSelectProfile`은 다중 선택까지 닫힌 최소 평면 선택 문법입니다.
+Canvas 모델, React, DOM, 문서 저장소 없이 ID·bounds·현재 선택과 정규화한 입력을
+받습니다. Selection의 `createKeySelectionFamily`로 집합과 primary를 전이하고,
+기존 hit·marquee·drag Affordance와 `createGestureSession`을 조합합니다.
+
+```text
+Web: hit ID, 같은 좌표계의 point, keyboard stroke, pointer capture
+  └─ Affordance: createPlaneSelectProfile
+      ├─ Selection: key 집합·primaryKey 전이/reconcile
+      └─ preview / commit 결과
+          ├─ Hand: 선택 윤곽·marquee·이동 preview 렌더링
+          └─ Editing: 선택 반영, 집합 이동·삭제, primary 편집, History
+```
+
+### API
+
+- `begin(context, { point, hitKey, shiftKey? })`: `items: { id, x, y, width, height }[]`와
+  `selection: { kind: "explicit", keys, primaryKey }`를 캡처합니다. `hitKey: null`은 빈 곳입니다.
+  items의 순서가 선택 순서·primary fallback 순서이며, 사라진 key는 Selection이 제거합니다.
+- `preview(point)` / `getPreview()`: `{ selection, marquee, translation } | null`.
+  `translation`은 `{ keys, dx, dy }` 하나입니다. 문서와 committed selection은 바꾸지 않습니다.
+- `commit(point)`: 최종 point로 `{ selection, translation } | null`을 한 번 반환하고
+  gesture를 비웁니다. Hand가 Selection을 반영한 뒤 translation 전체를 한 Intent로 실행합니다.
+- `cancel(reason?)`: preview를 버립니다. 이후 release는 결과를 만들지 않습니다.
+- `select(context, key, shiftKey?)`: Space 같은 discrete activation의 선택 결과.
+  **focus만으로 호출하지 않습니다.** Focus와 selection은 독립입니다.
+- `keyDown(stroke, context, grabbing?)`: selection / delete(keys) / edit(key) / cancel 또는
+  null. `grabbing`은 resize 등 다른 gesture의 활성 상태입니다. 처리한 command는
+  진행 중 Select preview도 취소합니다. 플랫폼 binding은 native editable/IME를 먼저 제외합니다.
+
+한 mounted Hand마다 하나의 profile instance를 사용합니다. instance 간 상태는 독립입니다.
+외부 문서·대상 geometry·committed selection 변경, 도구 전환, capture loss, unmount에서는 binding이 `cancel`을
+호출합니다. immutable begin snapshot을 사용하므로 오래된 gesture를 새 문서에 적용하지 않습니다.
+
+### 닫힌 문법
+
+| 입력 | 결과 |
+| --- | --- |
+| 객체 click | release에서 그 객체 하나로 replace |
+| 선택된 객체 press → drag | press에서는 집합 유지, drag는 집합 전체에 같은 delta |
+| 선택되지 않은 객체 press → drag | 그 객체 하나로 replace 후 이동 |
+| Shift+click | 포함하면 제거, 아니면 추가; 새 대상이 primary |
+| Shift+객체 drag | press의 toggle 결과로 이동. 누른 대상이 제거되면 이동 없음 |
+| 빈 곳 click | Shift 여부와 관계없이 clear |
+| 빈 곳 drag / Shift+drag | marquee replace / 기존 선택에 add |
+| Mod+A 반복 | 전체 선택 유지, 유효한 기존 primary 유지 |
+| Delete / Backspace | 선택 집합 삭제 요청 |
+| Enter / F2 | primary 하나의 편집 요청 |
+| Escape | gesture만 cancel, idle에서는 선택 clear |
+
+click/drag 임계값은 같은 좌표계의 3단위(`dragThreshold`), marquee는 bounds 교차
+(`contain: "intersect"`)가 기본입니다. `contain: "inside"`를 명시할 수 있습니다.
+임계값을 넘으면 이동을 되돌려도 drag로 유지하며, 최종 delta가 0이면 translation은 null입니다.
+primary가 아닌 객체도 선택 윤곽을 그리지만 resize handles와 텍스트 입력은 primary에만 붙입니다.
+
+Selection 변경은 문서 JSON과 History를 건드리지 않습니다. 문서 commit/Undo는 Editing이
+소유합니다. 이 프로파일에는 그룹·다중 resize·중첩 선택·Mod drill-down·축 구속·복제·
+snap·zoom/pan·레이어 문법이 없습니다. 기존 단일 Affordance의 더 넓은 기능과 구분합니다.
+
+### Usage와 Source
+
+실제 [Canvas Usage](/demo/canvas)는 public constructor를 import하여 `CanvasHand`에
+주입합니다. 생략하면 Hand가 같은 프로파일을 생성합니다. Source는 Affordance 프로파일,
+Selection key family, Object Editing, Canvas binding까지 연결됩니다.
+
+```tsx
+import { createPlaneSelectProfile } from "@interactive-os/json-document-affordance";
+import { CanvasHand } from "@interactive-os/json-document-canvas";
+
+const [selectProfile] = useState(() => createPlaneSelectProfile());
+return <CanvasHand editor={editor} selectProfile={selectProfile} creationStyle={creationStyle} />;
+```
+
+다른 평면 Hand는 CanvasHand 없이 같은 프로파일을 소비합니다.
+
+```ts
+const select = createPlaneSelectProfile();
+const context = {
+  items: [{ id: "node", x: 10, y: 20, width: 80, height: 40 }],
+  selection: { kind: "explicit" as const, keys: ["node"], primaryKey: "node" },
+};
+select.begin(context, { hitKey: "node", point: { x: 20, y: 30 } });
+const preview = select.preview({ x: 40, y: 50 }); // renderer에만 전달
+const result = select.commit({ x: 40, y: 50 }); // keys=["node"], dx=20, dy=20
+```
+
+`tests/plane-select.test.ts`는 Object·Canvas·React를 import하지 않는 diagram 소비자로
+동일 계약을 검증합니다. 실제 문서 commit/취소/Undo는 Canvas 통합 테스트가 검증합니다.
diff --git a/packages/json-document-affordance/package.json b/packages/json-document-affordance/package.json
index fbf340d0..ac808ba1 100644
--- a/packages/json-document-affordance/package.json
+++ b/packages/json-document-affordance/package.json
@@ -33,9 +33,11 @@
     "verify": "npm run typecheck && npm test && npm run build"
   },
   "peerDependencies": {
+    "@interactive-os/json-document-selection": ">=0.1.0-rc.0 <1",
     "@interactive-os/json-document-web": ">=0.1.0-rc.0 <1"
   },
   "devDependencies": {
+    "@interactive-os/json-document-selection": "*",
     "@interactive-os/json-document-web": "*",
     "@types/node": "^25.9.0",
     "typescript": "^5.0.0",
diff --git a/packages/json-document-affordance/src/index.ts b/packages/json-document-affordance/src/index.ts
index 78881e67..ef6c3c76 100644
--- a/packages/json-document-affordance/src/index.ts
+++ b/packages/json-document-affordance/src/index.ts
@@ -16,6 +16,12 @@ export {
 export { createBoardDragSession } from "./board-drag-session.js";
 export { createCanvasGestureSession } from "./canvas-gesture-session.js";
 export { createGestureSession } from "./gesture-session.js";
+export { createPlaneSelectProfile } from "./plane-select.js";
+export type {
+  PlaneSelectCommit, PlaneSelectContext, PlaneSelectInput, PlaneSelectKeyResult,
+  PlaneSelectPreview, PlaneSelectProfile, PlaneSelectProfileOptions, PlaneSelectSelection,
+  PlaneSelectTranslation,
+} from "./plane-select.js";
 export {
   createInteractionHandleSession,
   interactionHandleCursor,
diff --git a/packages/json-document-affordance/src/plane-select.ts b/packages/json-document-affordance/src/plane-select.ts
new file mode 100644
index 00000000..0d92516f
--- /dev/null
+++ b/packages/json-document-affordance/src/plane-select.ts
@@ -0,0 +1,167 @@
+import { createKeySelectionFamily, type KeySelection, type KeySelectionCommand } from "@interactive-os/json-document-selection";
+import { createWebKeyboardAdapter, type WebKeyboardStroke } from "@interactive-os/json-document-web";
+import { dragAffordance, marqueeAffordance, marqueeHitsAffordance, type Point, type Rect } from "./drag.js";
+import { createGestureSession, type GestureCancelReason } from "./gesture-session.js";
+import { escapeAffordance, planeHitAffordance, selectAllAffordance } from "./select.js";
+
+export type PlaneSelectSelection = Extract<KeySelection, { readonly kind: "explicit" }>;
+
+/** Items and pointer points must use the same coordinate space; order determines primary fallback. */
+export interface PlaneSelectContext {
+  readonly items: ReadonlyArray<Rect & { readonly id: string }>;
+  readonly selection: PlaneSelectSelection;
+}
+
+export interface PlaneSelectInput {
+  readonly point: Point;
+  readonly hitKey: string | null;
+  readonly shiftKey?: boolean;
+}
+
+export interface PlaneSelectTranslation {
+  readonly keys: readonly string[];
+  readonly dx: number;
+  readonly dy: number;
+}
+
+export interface PlaneSelectPreview {
+  readonly selection: PlaneSelectSelection;
+  readonly marquee: Rect | null;
+  readonly translation: PlaneSelectTranslation | null;
+}
+
+export interface PlaneSelectCommit {
+  readonly selection: PlaneSelectSelection;
+  readonly translation: PlaneSelectTranslation | null;
+}
+
+export type PlaneSelectKeyResult =
+  | { readonly type: "selection"; readonly selection: PlaneSelectSelection }
+  | { readonly type: "delete"; readonly keys: readonly string[] }
+  | { readonly type: "edit"; readonly key: string }
+  | { readonly type: "cancel" };
+
+export interface PlaneSelectProfileOptions {
+  /** In the input coordinate space. Defaults to 3; movement is latched once crossed. */
+  readonly dragThreshold?: number;
+  readonly contain?: "intersect" | "inside";
+}
+
+export interface PlaneSelectProfile {
+  begin(context: PlaneSelectContext, input: PlaneSelectInput): PlaneSelectPreview;
+  preview(point: Point): PlaneSelectPreview | null;
+  commit(point: Point): PlaneSelectCommit | null;
+  cancel(reason?: GestureCancelReason): void;
+  getPreview(): PlaneSelectPreview | null;
+  /** Discrete activation (e.g. Space), not focus. Shift toggles, plain activation replaces. */
+  select(context: PlaneSelectContext, key: string | null, shiftKey?: boolean): PlaneSelectSelection;
+  /** Native editable/IME ownership is checked by the platform binding before calling. */
+  keyDown(stroke: WebKeyboardStroke, context: PlaneSelectContext, grabbing?: boolean): PlaneSelectKeyResult | null;
+}
+
+type Gesture = {
+  readonly type: "plane-select";
+  readonly context: PlaneSelectContext;
+  readonly input: PlaneSelectInput;
+  readonly selection: PlaneSelectSelection;
+  readonly point: Point;
+  readonly moved: boolean;
+};
+
+const family = createKeySelectionFamily();
+const keyboard = createWebKeyboardAdapter();
+const editKeyboard = createWebKeyboardAdapter<"edit">({ defaults: false, keymap: { Enter: "edit", F2: "edit" } });
+
+function selectionContext(context: PlaneSelectContext) {
+  return { keys: context.items.map((item) => item.id), universe: "plane", universeMismatch: "clear" as const };
+}
+
+function transition(context: PlaneSelectContext, command: KeySelectionCommand): PlaneSelectSelection {
+  const topology = selectionContext(context);
+  const state = family.transition(context.selection, command, topology).state;
+  return { kind: "explicit", keys: family.targets(state, topology), primaryKey: state.primaryKey };
+}
+
+/** Minimal flat selection grammar. Owns previews and outcomes, never a document, DOM or History. */
+export function createPlaneSelectProfile(options: PlaneSelectProfileOptions = {}): PlaneSelectProfile {
+  const threshold = options.dragThreshold ?? 3;
+  if (!Number.isFinite(threshold) || threshold < 0) throw new RangeError("dragThreshold must be finite and non-negative");
+  const gestures = createGestureSession<Gesture>();
+
+  function select(context: PlaneSelectContext, key: string | null, shiftKey = false) {
+    return transition(context, key === null ? { type: "clear" } : { type: shiftKey ? "toggle" : "replace", keys: [key], primaryKey: key });
+  }
+
+  function project(gesture: Gesture): PlaneSelectPreview {
+    const { context, input, point, selection, moved } = gesture;
+    if (input.hitKey === null && moved) {
+      const band = marqueeAffordance(input.point, point, input);
+      if (band.hand?.type === "select" && band.hand.rect) {
+        const hit = marqueeHitsAffordance({ rect: band.hand.rect, items: context.items, contain: options.contain ?? "intersect" });
+        if (hit.hand?.type === "select") return {
+          selection: transition(context, { type: input.shiftKey ? "add" : "replace", keys: hit.hand.objectIds ?? [] }),
+          marquee: band.hand.rect, translation: null,
+        };
+      }
+      return { selection: transition(context, { type: input.shiftKey ? "add" : "replace", keys: [] }), marquee: null, translation: null };
+    }
+    const delta = moved && input.hitKey !== null && selection.keys.includes(input.hitKey)
+      ? dragAffordance(input.point, point).hand : null;
+    return {
+      selection, marquee: null,
+      translation: delta?.type === "translate" && (delta.dx !== 0 || delta.dy !== 0)
+        ? { keys: selection.keys, dx: delta.dx, dy: delta.dy } : null,
+    };
+  }
+
+  function preview(point: Point) {
+    const active = gestures.preview((gesture) => ({ ...gesture, point: { ...point },
+      moved: gesture.moved || Math.hypot(point.x - gesture.input.point.x, point.y - gesture.input.point.y) > threshold,
+    }));
+    return active ? project(active) : null;
+  }
+
+  return {
+    begin(context, input) {
+      const selection = transition(context, { type: "set-primary", key: context.selection.primaryKey });
+      const captured = { items: context.items.map((item) => ({ ...item })), selection };
+      const hitKey = input.hitKey !== null && captured.items.some((item) => item.id === input.hitKey) ? input.hitKey : null;
+      const press = hitKey === null ? null : planeHitAffordance({ hitId: hitKey, selectedIds: selection.keys, shiftKey: input.shiftKey ?? false }).hand;
+      const active = gestures.begin({ type: "plane-select", context: captured, input: { ...input, point: { ...input.point }, hitKey },
+        point: { ...input.point }, moved: false,
+        selection: press?.type === "select" ? transition(captured, { type: "replace", keys: press.objectIds ?? [], primaryKey: hitKey! }) : selection,
+      });
+      return project(active);
+    },
+    preview,
+    commit(point) {
+      preview(point);
+      const active = gestures.commit();
+      if (!active) return null;
+      const result = project(active);
+      return {
+        selection: !active.moved ? select(active.context, active.input.hitKey, active.input.shiftKey) : result.selection,
+        translation: result.translation,
+      };
+    },
+    cancel(reason) { gestures.cancel(reason); },
+    getPreview() { const active = gestures.getActive(); return active ? project(active) : null; },
+    select,
+    keyDown(stroke, context, grabbing = false) {
+      const selection = transition(context, { type: "set-primary", key: context.selection.primaryKey });
+      const escape = escapeAffordance({ key: stroke.key, grabbing: grabbing || gestures.getActive() !== null, selected: selection.keys.length > 0 }).hand;
+      let result: PlaneSelectKeyResult | null = null;
+      if (escape?.type === "cancel") result = { type: "cancel" };
+      else if (escape?.type === "clear") result = { type: "selection", selection: select(context, null) };
+      else if (!stroke.altKey && selectAllAffordance(stroke, { allSelected: false }, { repeat: "preserve" }).hand) {
+        result = { type: "selection", selection: transition(context, { type: "replace", keys: context.items.map((item) => item.id), ...(selection.primaryKey === null ? {} : { primaryKey: selection.primaryKey }) }) };
+      } else {
+        const command = keyboard.resolve(stroke);
+        if (editKeyboard.resolve(stroke) === "edit" && selection.primaryKey !== null) result = { type: "edit", key: selection.primaryKey };
+        else if (command?.type === "delete" && selection.keys.length) result = { type: "delete", keys: selection.keys };
+      }
+      if (result) gestures.cancel();
+      return result;
+    },
+  };
+}
diff --git a/packages/json-document-affordance/tests/plane-select.test.ts b/packages/json-document-affordance/tests/plane-select.test.ts
new file mode 100644
index 00000000..5df28c54
--- /dev/null
+++ b/packages/json-document-affordance/tests/plane-select.test.ts
@@ -0,0 +1,109 @@
+import { expect, test } from "vitest";
+import { createPlaneSelectProfile, type PlaneSelectContext, type PlaneSelectSelection } from "../src/index.js";
+
+// A diagram consumer: no Object document, Editing, Canvas, DOM or React dependency.
+const items = ["node:a", "node:b", "node:c"].map((id, index) => ({ id, x: index * 100, y: 20, width: 40, height: 40 }));
+const point = { x: 10, y: 30 };
+const selected = (keys: readonly string[], primaryKey = keys.at(-1) ?? null): PlaneSelectSelection => ({ kind: "explicit", keys, primaryKey });
+const context = (keys: readonly string[] = ["node:a", "node:b"]): PlaneSelectContext => ({ items, selection: selected(keys) });
+const stroke = (key: string, mod = false) => ({ key, shiftKey: false, metaKey: mod, ctrlKey: false });
+
+test("press retains a selected set, release collapses a click, and drag produces one set delta", () => {
+  const profile = createPlaneSelectProfile();
+  expect(profile.begin(context(), { point, hitKey: "node:a" }).selection).toEqual(selected(["node:a", "node:b"], "node:a"));
+  expect(profile.commit({ x: 12, y: 31 })).toEqual({ selection: selected(["node:a"]), translation: null });
+  profile.begin(context(), { point, hitKey: "node:a" });
+  expect(profile.preview({ x: 40, y: 50 })?.translation).toEqual({ keys: ["node:a", "node:b"], dx: 30, dy: 20 });
+  expect(profile.commit({ x: 50, y: 60 })?.translation).toEqual({ keys: ["node:a", "node:b"], dx: 40, dy: 30 });
+  expect(profile.commit(point)).toBeNull();
+});
+
+test("an unselected hit replaces the drag source; Shift activation toggles without range semantics", () => {
+  const profile = createPlaneSelectProfile();
+  profile.begin(context(), { point, hitKey: "node:c" });
+  expect(profile.commit({ x: 20, y: 40 })?.translation?.keys).toEqual(["node:c"]);
+  expect(profile.select(context(["node:a"]), "node:c", true)).toEqual(selected(["node:a", "node:c"]));
+  expect(profile.select(context(), "node:b", true)).toEqual(selected(["node:a"]));
+  profile.begin(context(), { point, hitKey: "node:b", shiftKey: true });
+  expect(profile.commit({ x: 40, y: 40 })).toEqual({ selection: selected(["node:a"]), translation: null });
+});
+
+test.each([false, true])("marquee is transient and uses base selection for every preview (Shift=%s)", (shiftKey) => {
+  const profile = createPlaneSelectProfile();
+  const base = context(["node:c"]);
+  profile.begin(base, { point: { x: -10, y: 10 }, hitKey: null, shiftKey });
+  expect(profile.preview({ x: 150, y: 70 })?.selection.keys).toEqual(shiftKey ? ["node:a", "node:b", "node:c"] : ["node:a", "node:b"]);
+  const narrowed = profile.preview({ x: 50, y: 70 });
+  expect(narrowed?.selection.keys).toEqual(shiftKey ? ["node:a", "node:c"] : ["node:a"]);
+  expect(narrowed?.marquee).toEqual({ x: -10, y: 10, width: 60, height: 60 });
+  expect(base.selection).toEqual(selected(["node:c"]));
+  expect(profile.commit({ x: 50, y: 70 })?.selection).toEqual(narrowed?.selection);
+  expect(profile.getPreview()).toBeNull();
+});
+
+test("empty click clears even with Shift; reverse marquee intersects bounds and inside is explicit policy", () => {
+  const profile = createPlaneSelectProfile();
+  profile.begin(context(), { point, hitKey: null, shiftKey: true });
+  expect(profile.commit(point)?.selection).toEqual(selected([]));
+  const inside = createPlaneSelectProfile({ contain: "inside" });
+  for (const consumer of [profile, inside]) consumer.begin(context([]), { point: { x: 120, y: 80 }, hitKey: null });
+  expect(profile.commit({ x: -10, y: 10 })?.selection.keys).toEqual(["node:a", "node:b"]);
+  expect(inside.commit({ x: -10, y: 10 })?.selection.keys).toEqual(["node:a"]);
+});
+
+test.each(["cancel", "pointer-cancel", "lost-capture", "superseded"] as const)("%s discards preview without mutating base or producing a commit", (reason) => {
+  const profile = createPlaneSelectProfile();
+  const base = context();
+  profile.begin(base, { point, hitKey: null }); profile.preview({ x: 200, y: 100 });
+  profile.cancel(reason);
+  expect(profile.getPreview()).toBeNull(); expect(profile.commit(point)).toBeNull();
+  expect(base.selection).toEqual(selected(["node:a", "node:b"]));
+});
+
+test("Escape cancels the inner gesture first, then clears idle selection; repeated Mod+A preserves primary", () => {
+  const profile = createPlaneSelectProfile();
+  const base = context();
+  profile.begin(base, { point, hitKey: "node:a" });
+  expect(profile.keyDown(stroke("Escape"), base)).toEqual({ type: "cancel" });
+  expect(profile.commit(point)).toBeNull();
+  expect(profile.keyDown(stroke("Escape"), base)).toEqual({ type: "selection", selection: selected([]) });
+  expect(profile.keyDown(stroke("Escape"), context([]))).toBeNull();
+  expect(profile.keyDown(stroke("Escape"), context([]), true)).toEqual({ type: "cancel" });
+  const all = profile.keyDown(stroke("a", true), base);
+  expect(all).toEqual({ type: "selection", selection: selected(items.map((item) => item.id), "node:b") });
+  if (all?.type !== "selection") throw new Error("selection expected");
+  expect(profile.keyDown({ ...stroke("A"), ctrlKey: true }, { items, selection: all.selection })).toEqual(all);
+});
+
+test("Delete targets the set, edit targets primary only, unrelated/modified keys remain unhandled", () => {
+  const profile = createPlaneSelectProfile();
+  expect(profile.keyDown(stroke("Delete"), context())).toEqual({ type: "delete", keys: ["node:a", "node:b"] });
+  for (const key of ["Enter", "F2"]) expect(profile.keyDown(stroke(key), context())).toEqual({ type: "edit", key: "node:b" });
+  for (const key of ["Delete", "Enter", "F2"]) expect(profile.keyDown(stroke(key), context([]))).toBeNull();
+  for (const key of ["ArrowLeft", "Home", "z"]) expect(profile.keyDown(stroke(key), context())).toBeNull();
+  expect(profile.keyDown(stroke("Enter", true), context())).toBeNull();
+});
+
+test("keys and primary reconcile through Selection; geometry and input are captured, and instances are independent", () => {
+  const profile = createPlaneSelectProfile();
+  const mutable = { items: items.map((item) => ({ ...item })), selection: selected(["missing", "node:a"], "missing") };
+  const input = { point: { x: -10, y: 0 }, hitKey: null };
+  profile.begin(mutable, input);
+  mutable.items[0]!.x = 999; input.point.x = 999;
+  expect(profile.commit({ x: 60, y: 80 })?.selection).toEqual(selected(["node:a"]));
+  const second = createPlaneSelectProfile();
+  profile.begin(context(), { point, hitKey: "node:a" });
+  expect(second.getPreview()).toBeNull();
+  expect(second.select(context(), "missing")).toEqual(selected([]));
+});
+
+test("crossing threshold is latched; returning to the origin has no document delta", () => {
+  const profile = createPlaneSelectProfile({ dragThreshold: 5 });
+  profile.begin(context(), { point, hitKey: "node:a" });
+  expect(profile.preview({ x: 13, y: 34 })?.translation).toBeNull();
+  profile.preview({ x: 30, y: 40 });
+  expect(profile.commit(point)).toEqual({ selection: selected(["node:a", "node:b"], "node:a"), translation: null });
+  profile.begin(context(), { point, hitKey: null }); profile.preview({ x: 100, y: 100 });
+  expect(profile.commit(point)?.selection).toEqual(selected([]));
+  for (const dragThreshold of [-1, NaN, Infinity]) expect(() => createPlaneSelectProfile({ dragThreshold })).toThrow(RangeError);
+});
diff --git a/packages/json-document-affordance/tsconfig.json b/packages/json-document-affordance/tsconfig.json
index ee593812..0fd47ac1 100644
--- a/packages/json-document-affordance/tsconfig.json
+++ b/packages/json-document-affordance/tsconfig.json
@@ -5,6 +5,6 @@
     "outDir": "dist",
     "tsBuildInfoFile": "dist/.tsbuildinfo"
   },
-  "references": [{ "path": "../json-document-web" }],
+  "references": [{ "path": "../json-document-web" }, { "path": "../json-document-selection" }],
   "include": ["src/**/*.ts"]
 }
diff --git a/packages/json-document-canvas/docs/api.md b/packages/json-document-canvas/docs/api.md
index 0ba49d22..5b858ffa 100644
--- a/packages/json-document-canvas/docs/api.md
+++ b/packages/json-document-canvas/docs/api.md
@@ -1,7 +1,7 @@
 ## Canvas Hand 계약 · RC
 
 `CanvasHand`는 `ObjectEditor`와 `CanvasCreationStyle`을 받아 글자·사각형·타원·자유
-그리기, 단일 선택, 이동·resize·삭제, Undo/Redo, JSON 재열기를 연결합니다.
+그리기, 다중 선택, 집합 이동·삭제, primary resize, Undo/Redo, JSON 재열기를 연결합니다.
 `useCanvasHand`는 같은 입력 조합을 custom UI에서 사용할 수 있게 공개합니다.
 
 툴바의 모든 도구·명령은 Lucide 아이콘과 공통 `Toggle`/`Command`의 `label`을
@@ -14,7 +14,9 @@ Host: 한 장 fixture, 크기·색상 정책, 레이아웃
   └─ Canvas Hand: 도구, 조작 preview, plain-text draft, UI 조합
       ├─ React Connector: Editing snapshot 구독
       ├─ Web Adapter: SVG 좌표, pointer capture, keyboard 해석
-      ├─ Affordance / UI Primitives: gesture, drag/resize, handle, controls
+      ├─ Affordance: createPlaneSelectProfile, gesture, resize
+      │   └─ Selection: key 집합·primaryKey 전이
+      ├─ UI Primitives: handle, icon controls·tooltips
       └─ Object Editing: Intent, ID 할당, Selection, History
           ├─ Object Document Type: Canvas profile, 검증, 연산, projection, JSON
           └─ Core: immutable 값과 atomic JSON Patch
@@ -26,14 +28,22 @@ Host: 한 장 fixture, 크기·색상 정책, 레이아웃
 
 - 도구를 고르고 클릭하면 기본 크기, 드래그하면 지정한 크기로 생성합니다.
   생성 후 Select로 돌아가며 새 객체를 선택합니다. 펜은 최소 두 지점이 필요합니다.
-- 객체 경계 상자를 집어 움직이고 네 모서리 손잡이로 resize합니다. 마지막 객체가
-  위에 표시되며 단일 선택만 UI로 제공합니다. ObjectEditor의 기존 집합 API는 유지합니다.
+- 객체 click은 단일 선택, Shift+click은 toggle입니다. 빈 곳 click은 clear,
+  drag는 marquee replace, Shift+marquee는 add입니다. Mod+A를 반복해도 전체 선택을 유지합니다.
+  선택된 객체 press는 집합을 유지하고 release까지 drag가 없으면 단일 선택으로 바꿉니다.
+- 선택된 객체를 끌면 집합 전체가 같은 delta로 이동합니다. 마지막 객체가 위에 표시됩니다.
+  선택 윤곽은 모두 그리지만 네 모서리 resize handles는 primary 하나에만 붙습니다.
+  Delete는 집합 전체를 한 번 삭제하며 primary resize/text 편집은 기존 선택 집합을 보존합니다.
+  Focus만으로 선택하지 않으며, focused 객체에서 Space/Shift+Space로 선택/toggle합니다.
+  focused 객체의 Enter는 그 객체를 선택하고 글자라면 편집합니다. 슬라이드 자체의
+  Enter/F2는 현재 primary를 편집하며, F2는 객체에 focus가 있어도 primary를 대상으로 합니다.
 - 글자는 생성 직후 또는 더블클릭/F2/Enter로 편집합니다. 줄바꿈·IME·선택·native
   입력 Undo는 textarea에 남습니다. blur 또는 Mod+Enter가 전체 draft를 한 번 commit하고
   Escape는 draft만 버립니다. 객체의 label이 실제 문자열 값입니다.
 - 이동·resize·생성 중에는 문서를 변경하지 않습니다. pointerup의 최종 좌표로 한 번
   commit합니다. Escape, pointercancel, capture loss, 외부 문서 변경, unmount는 preview를
-  버립니다. 다른 pointer의 release는 조작을 완료하지 못합니다.
+  버립니다. 다른 pointer의 release는 조작을 완료하지 못합니다. marquee 선택 preview도
+  commit 전까지 Editing에 반영하지 않습니다. Escape는 gesture만 취소하고 idle에서 선택을 비웁니다.
 - 선택만 바꾸거나 0 거리로 움직이면 History가 생기지 않습니다. commit된 편집은
   한 번의 Undo로 되돌리며 삭제 Undo는 객체와 선택을 함께 복원합니다. Mod+Z/Mod+Shift+Z는
   입력 필드 밖에서 문서 Undo/Redo를 실행합니다.
@@ -48,10 +58,15 @@ JSON 버튼은 현재 문서 문자열을 노출합니다. 이 문자열을 저
 
 ### 범위와 Usage
 
-단일 슬라이드를 컨테이너에 맞춰 표시합니다. 확대/축소·페이지·팬·다중 선택·그룹·회전·
+단일 슬라이드를 컨테이너에 맞춰 표시합니다. 확대/축소·페이지·팬·다중 resize·그룹·회전·
 snap·레이어·Clipboard UI·PPTX·collaboration은 이번 Hand의 지원 범위가 아닙니다.
 `creationStyle`은 새 객체에만 적용하는 제품 기본값이며 저장 객체의 스타일을 덮어쓰지 않습니다.
 
+선택은 Affordance의 [평면 Select 프로파일](/docs/api/affordance)을 소비합니다.
+`selectProfile`을 주입하거나 생략하여 기본 instance를 만들 수 있습니다. instance는 Hand마다
+독립적이어야 합니다. `useCanvasHand(editor, style, selectProfile?)`의 `selection`과 `marquee`는
+현재 표시할 preview이며, `snapshot.selection`은 Editing에 확정된 선택입니다.
+
 ```live-demo
 /demo/canvas
 ```
diff --git a/packages/json-document-canvas/src/canvas-hand.tsx b/packages/json-document-canvas/src/canvas-hand.tsx
index 84d74f39..cb5c8d65 100644
--- a/packages/json-document-canvas/src/canvas-hand.tsx
+++ b/packages/json-document-canvas/src/canvas-hand.tsx
@@ -1,6 +1,7 @@
 import { useState, type CSSProperties } from "react";
 import { Braces, Circle, MousePointer2, Pencil, RectangleHorizontal, Redo2, Trash2, Type, Undo2, type LucideIcon } from "lucide-react";
 import type { ObjectEditor } from "@interactive-os/json-document-editing";
+import type { PlaneSelectProfile } from "@interactive-os/json-document-affordance";
 import { serializeCanvasDocument } from "@interactive-os/json-document-object-document";
 import { Command, Field, ProductShell, Toggle, ToolbarGroup } from "@interactive-os/json-document-ui-primitives-react";
 import { CanvasObjectTarget, CanvasObjectView, CanvasResizeTarget, CanvasTextInput } from "./canvas-object-view.js";
@@ -12,6 +13,8 @@ export interface CanvasHandProps {
   readonly className?: string;
   readonly slideStyle?: CSSProperties;
   readonly label?: string;
+  /** Optional policy instance; one profile per mounted Hand. */
+  readonly selectProfile?: PlaneSelectProfile;
 }
 
 const tools: ReadonlyArray<{ readonly id: CanvasTool; readonly label: string; readonly icon: LucideIcon }> = [
@@ -20,9 +23,10 @@ const tools: ReadonlyArray<{ readonly id: CanvasTool; readonly label: string; re
 ];
 
 export function CanvasHand(props: CanvasHandProps) {
-  const hand = useCanvasHand(props.editor, props.creationStyle);
+  const hand = useCanvasHand(props.editor, props.creationStyle, props.selectProfile);
   const [json, setJSON] = useState<string | null>(null);
-  const selected = hand.objects.find((object) => object.id === hand.snapshot.selection.primaryKey);
+  const selected = hand.objects.find((object) => object.id === hand.selection.primaryKey);
+  const selectedKeys = new Set(hand.selection.keys);
   return (
     <ProductShell className={props.className} toolbarLabel="Canvas tools" toolbar={<ToolbarGroup style={{ flexWrap: "wrap" }}>
       <ToolbarGroup>{tools.map((tool) => <Toggle key={tool.id} label={tool.label} pressed={hand.tool === tool.id} onClick={() => hand.choose(tool.id)}><tool.icon aria-hidden="true" size={16} /></Toggle>)}</ToolbarGroup>
@@ -38,14 +42,16 @@ export function CanvasHand(props: CanvasHandProps) {
         style={{ display: "block", width: "100%", aspectRatio: `${hand.document.width} / ${hand.document.height}`, touchAction: "none", userSelect: "none", overflow: "hidden", ...props.slideStyle }}>
         {hand.objects.map((object) => <g key={object.id}>
           {hand.draft?.id !== object.id && <CanvasObjectView object={object} />}
-          <CanvasObjectTarget object={object} selected={object.id === hand.snapshot.selection.primaryKey} enabled={hand.tool === "select" && hand.draft?.id !== object.id}
-            onSelect={() => hand.select(object.id)} onEdit={() => hand.editText(object.id)} onHandle={(interaction, event) => hand.interaction(interaction, event, object, "drag")} />
+          <CanvasObjectTarget object={object} selected={selectedKeys.has(object.id)} enabled={hand.tool === "select" && hand.draft?.id !== object.id}
+            onSelect={(shiftKey) => hand.select(object.id, shiftKey)} onEdit={() => hand.editText(object.id)} onHandle={(interaction, event) => hand.interaction(interaction, event, object, "drag")} />
         </g>)}
         {hand.preview && <g pointerEvents="none" opacity={0.65}><CanvasObjectView object={{ ...hand.preview, id: "preview" }} /></g>}
+        {hand.tool === "select" && hand.objects.filter((object) => selectedKeys.has(object.id)).map((object) =>
+          <rect key={object.id} data-selection-outline={object.id} x={object.x} y={object.y} width={object.width} height={object.height} fill="none" stroke="rgb(var(--color-border-accent))" strokeWidth={object.id === selected?.id ? 2 : 1} pointerEvents="none" />)}
         {selected && hand.tool === "select" && <g>
-          <rect x={selected.x} y={selected.y} width={selected.width} height={selected.height} fill="none" stroke="rgb(var(--color-border-accent))" strokeWidth={2} pointerEvents="none" />
           {!hand.draft && (["nw", "ne", "se", "sw"] as const).map((edge) => <CanvasResizeTarget key={edge} object={selected} edge={edge} onHandle={(interaction, event) => hand.interaction(interaction, event, selected, "resize", edge)} />)}
         </g>}
+        {hand.marquee && <rect data-canvas-marquee="" {...hand.marquee} fill="rgb(var(--color-border-accent) / 0.08)" stroke="rgb(var(--color-border-accent))" pointerEvents="none" />}
         {selected?.kind === "text" && hand.draft?.id === selected.id && <CanvasTextInput object={selected} text={hand.draft.text} onChange={hand.changeText}
           onCommit={() => { hand.commitText(); hand.surface.current?.focus(); }} onCancel={() => { hand.cancel(); hand.surface.current?.focus(); }} />}
       </svg>
diff --git a/packages/json-document-canvas/src/canvas-object-view.tsx b/packages/json-document-canvas/src/canvas-object-view.tsx
index a7e0e873..e27939f4 100644
--- a/packages/json-document-canvas/src/canvas-object-view.tsx
+++ b/packages/json-document-canvas/src/canvas-object-view.tsx
@@ -21,7 +21,7 @@ export function CanvasObjectTarget(props: {
   readonly object: CanvasObject;
   readonly selected: boolean;
   readonly enabled: boolean;
-  readonly onSelect: () => void;
+  readonly onSelect: (shiftKey: boolean) => void;
   readonly onEdit: () => void;
   readonly onHandle: (interaction: InteractionHandleEvent, event: PointerEvent<SVGElement>) => void;
 }) {
@@ -33,8 +33,14 @@ export function CanvasObjectTarget(props: {
       {...contentInteractionAttributes({ role: "content", selected: props.selected, dragging: binding.active })}
       tabIndex={props.enabled ? 0 : -1} data-canvas-object={object.id} data-kind={object.kind}
       pointerEvents={props.enabled ? "all" : "none"} style={{ cursor: binding.cursor, transform: "none" }}
-      onFocus={props.onSelect} onDoubleClick={props.onEdit}
-      onKeyDown={(event) => { if (event.key === " ") { event.preventDefault(); props.onSelect(); } }} />
+      onDoubleClick={props.onEdit}
+      onKeyDown={(event) => {
+        if (event.nativeEvent.isComposing || event.metaKey || event.ctrlKey || event.altKey) return;
+        if (event.key === " " || (event.key === "Enter" && !event.shiftKey)) {
+          event.preventDefault(); event.stopPropagation(); props.onSelect(event.shiftKey);
+          if (event.key === "Enter") props.onEdit();
+        }
+      }} />
   );
 }
 
diff --git a/packages/json-document-canvas/src/use-canvas-hand.ts b/packages/json-document-canvas/src/use-canvas-hand.ts
index 46186360..bea7a42a 100644
--- a/packages/json-document-canvas/src/use-canvas-hand.ts
+++ b/packages/json-document-canvas/src/use-canvas-hand.ts
@@ -1,5 +1,5 @@
 import { useEffect, useMemo, useReducer, useRef, useState, type KeyboardEvent, type PointerEvent } from "react";
-import { createGestureSession, dragAffordance, resizeAffordance, type InteractionHandleEvent, type ResizeEdge } from "@interactive-os/json-document-affordance";
+import { createGestureSession, createPlaneSelectProfile, resizeAffordance, type InteractionHandleEvent, type PlaneSelectProfile, type PlaneSelectSelection, type ResizeEdge } from "@interactive-os/json-document-affordance";
 import { assertCanvasDocument, createCanvasObject, createCanvasPath, parseCanvasDocument, transformObject, type CanvasDocument, type CanvasObject, type CanvasObjectKind, type ObjectPoint } from "@interactive-os/json-document-object-document";
 import type { EditingResult, ObjectEditor, ObjectIntent, ObjectSelection } from "@interactive-os/json-document-editing";
 import { useEditingSnapshot } from "@interactive-os/json-document-react";
@@ -16,15 +16,15 @@ export interface CanvasCreationStyle {
 type Gesture = { readonly base: CanvasDocument } & (
   | { readonly type: "create"; readonly tool: Exclude<CanvasObjectKind, "path">; readonly start: ObjectPoint; readonly point: ObjectPoint }
   | { readonly type: "draw"; readonly points: ReadonlyArray<ObjectPoint> }
-  | { readonly type: "drag" | "resize"; readonly object: CanvasObject; readonly start: ObjectPoint; readonly point: ObjectPoint; readonly edge: ResizeEdge }
+  | { readonly type: "resize"; readonly object: CanvasObject; readonly start: ObjectPoint; readonly point: ObjectPoint; readonly edge: ResizeEdge }
 );
 type TextDraft = { readonly id: string; readonly text: string; readonly base: CanvasDocument };
 
 const keyboard = createWebKeyboardAdapter();
-const commands = createWebKeyboardAdapter<"cancel" | "edit">({ defaults: false, keymap: { Escape: "cancel", Enter: "edit", F2: "edit" } });
+const commands = createWebKeyboardAdapter<"cancel">({ defaults: false, keymap: { Escape: "cancel" } });
 
 /** Owns Canvas interaction composition, never document or history state. */
-export function useCanvasHand(editor: ObjectEditor, style: CanvasCreationStyle) {
+export function useCanvasHand(editor: ObjectEditor, style: CanvasCreationStyle, selectProfile?: PlaneSelectProfile) {
   const snapshot = useEditingSnapshot(editor);
   const document = useMemo(() => { assertCanvasDocument(snapshot.value); return snapshot.value; }, [snapshot.value]);
   const surface = useRef<SVGSVGElement>(null);
@@ -32,8 +32,13 @@ export function useCanvasHand(editor: ObjectEditor, style: CanvasCreationStyle)
   const [tool, setTool] = useState<CanvasTool>("select");
   const [error, setError] = useState<string | null>(null);
   const draft = useRef<TextDraft | null>(null);
+  const selecting = useRef<{ readonly base: CanvasDocument; readonly selection: ObjectSelection; readonly pointerId: number; readonly key: string | null } | null>(null);
+  const profile = useMemo(() => selectProfile ?? createPlaneSelectProfile(), [editor, selectProfile]);
   const gestures = useMemo(() => createGestureSession<Gesture>({ onBegin: redraw, onPreview: redraw, onCommit: redraw, onCancel: redraw }), [editor]);
-  const pointer = useMemo(() => createWebPointerSession<true>({ onCancel: (_, reason) => gestures.cancel(reason === "lost-capture" ? "lost-capture" : "pointer-cancel") }), [gestures]);
+  const pointer = useMemo(() => createWebPointerSession<true>({ onCancel: (_, reason) => {
+    gestures.cancel(reason === "lost-capture" ? "lost-capture" : "pointer-cancel");
+    profile.cancel(reason === "lost-capture" ? "lost-capture" : "pointer-cancel"); selecting.current = null; redraw();
+  } }), [gestures, profile]);
 
   function current(): CanvasDocument {
     const value = editor.snapshot.value;
@@ -45,6 +50,7 @@ export function useCanvasHand(editor: ObjectEditor, style: CanvasCreationStyle)
     const active = pointer.getSnapshot();
     if (active) pointer.cancel(active.pointerId);
     gestures.cancel();
+    profile.cancel(); selecting.current = null;
     draft.current = null;
     redraw();
   }
@@ -52,16 +58,19 @@ export function useCanvasHand(editor: ObjectEditor, style: CanvasCreationStyle)
   useEffect(() => {
     // A replacement/external edit invalidates previews, even when an ID survives.
     const release = editor.subscribe((next) => {
-      if ((gestures.getActive() && gestures.getActive()!.base !== next.value) || (draft.current && draft.current.base !== next.value)) cancel();
+      if ((gestures.getActive() && gestures.getActive()!.base !== next.value)
+        || (selecting.current && (selecting.current.base !== next.value || selecting.current.selection !== next.selection))
+        || (draft.current && draft.current.base !== next.value)) cancel();
     });
     return () => {
       release();
       const active = pointer.getSnapshot();
       if (active) pointer.cancel(active.pointerId);
       gestures.cancel();
+      profile.cancel(); selecting.current = null;
       draft.current = null;
     };
-  }, [editor, gestures, pointer]);
+  }, [editor, gestures, pointer, profile]);
 
   function report(result: EditingResult<ObjectSelection>) {
     setError(result.ok ? null : result.reason ?? result.code);
@@ -69,13 +78,33 @@ export function useCanvasHand(editor: ObjectEditor, style: CanvasCreationStyle)
   }
 
   function dispatch(intent: ObjectIntent) { return report(editor.dispatch(intent)); }
-  function select(id: string | null) { dispatch({ type: "selection.set", objectIds: id === null ? [] : [id], mode: "replace" }); }
+  function selectContext() { return { items: current().objects, selection: editor.snapshot.selection }; }
+  function applySelection(selection: PlaneSelectSelection) {
+    return dispatch({ type: "selection.set", objectIds: selection.keys, ...(selection.primaryKey === null ? {} : { primaryKey: selection.primaryKey }) });
+  }
+  function select(id: string | null, shiftKey = false) { cancel(); applySelection(profile.select(selectContext(), id, shiftKey)); }
+
+  function beginSelect(point: ObjectPoint, key: string | null, event: { readonly pointerId: number; readonly shiftKey: boolean }) {
+    selecting.current = { base: current(), selection: editor.snapshot.selection, pointerId: event.pointerId, key };
+    profile.begin(selectContext(), { point, hitKey: key, shiftKey: event.shiftKey }); redraw();
+  }
+
+  function commitSelect(point: ObjectPoint) {
+    const base = selecting.current?.base;
+    selecting.current = null;
+    const result = profile.commit(point); redraw();
+    if (!result || base !== current()) return;
+    if (!applySelection(result.selection).ok || !result.translation) return;
+    const { keys, dx, dy } = result.translation;
+    dispatch({ type: "object.translate", objectIds: keys, dx, dy });
+  }
 
   function editText(id: string) {
     const base = current();
     const object = base.objects.find((item) => item.id === id);
     if (object?.kind !== "text") return;
-    cancel(); select(id);
+    cancel();
+    if (editor.snapshot.selection.primaryKey !== id) applySelection(profile.select(selectContext(), id));
     draft.current = { id, text: object.label, base };
     redraw();
   }
@@ -110,8 +139,8 @@ export function useCanvasHand(editor: ObjectEditor, style: CanvasCreationStyle)
     }, { color: gesture.tool === "text" ? style.textColor : style.color, label: gesture.tool === "text" ? "Text" : "", fontSize: style.fontSize });
   }
 
-  function transform(gesture: Extract<Gesture, { type: "drag" | "resize" }>) {
-    const result = gesture.type === "drag" ? dragAffordance(gesture.start, gesture.point) : resizeAffordance(gesture.start, gesture.point, gesture.edge);
+  function transform(gesture: Extract<Gesture, { type: "resize" }>) {
+    const result = resizeAffordance(gesture.start, gesture.point, gesture.edge);
     const hand = result.hand;
     return hand?.type === "translate" || hand?.type === "resize" ? hand : { dx: 0, dy: 0 };
   }
@@ -130,9 +159,7 @@ export function useCanvasHand(editor: ObjectEditor, style: CanvasCreationStyle)
       }
     } else {
       const delta = transform(active);
-      dispatch(active.type === "drag"
-        ? { type: "object.translate", objectIds: [active.object.id], dx: delta.dx, dy: delta.dy }
-        : { type: "object.resize", objectIds: [active.object.id], dx: delta.dx, dy: delta.dy, dw: "dw" in delta ? delta.dw : 0, dh: "dh" in delta ? delta.dh : 0 });
+      dispatch({ type: "object.resize", objectIds: [active.object.id], dx: delta.dx, dy: delta.dy, dw: "dw" in delta ? delta.dw : 0, dh: "dh" in delta ? delta.dh : 0 });
     }
   }
 
@@ -143,8 +170,8 @@ export function useCanvasHand(editor: ObjectEditor, style: CanvasCreationStyle)
     if (!point) return;
     event.preventDefault();
     commitText(); cancel(); surface.current?.focus();
-    if (tool === "select") { select(null); return; }
     pointer.begin(event.currentTarget, event.pointerId, true);
+    if (tool === "select") { beginSelect(point, null, event); return; }
     const base = current();
     gestures.begin(tool === "path" ? { type: "draw", points: [point], base } : { type: "create", tool, start: point, point, base });
   }
@@ -152,6 +179,7 @@ export function useCanvasHand(editor: ObjectEditor, style: CanvasCreationStyle)
   function pointerMove(event: PointerEvent<SVGSVGElement>) {
     if (pointer.getSnapshot()?.pointerId !== event.pointerId) return;
     const point = eventPoint(event), active = gestures.getActive();
+    if (point && selecting.current) { profile.preview(point); redraw(); return; }
     if (!point || !active) return;
     if (active.type === "draw") {
       const last = active.points.at(-1)!;
@@ -160,14 +188,24 @@ export function useCanvasHand(editor: ObjectEditor, style: CanvasCreationStyle)
   }
 
   function interaction(interaction: InteractionHandleEvent, event: PointerEvent<SVGElement>, object: CanvasObject, type: "drag" | "resize", edge: ResizeEdge = "se") {
-    if (interaction.phase === "cancel") { gestures.cancel("pointer-cancel"); return; }
+    if (interaction.phase === "cancel") {
+      if (type === "drag" && selecting.current?.key === object.id && selecting.current.pointerId === event.pointerId) { profile.cancel("pointer-cancel"); selecting.current = null; redraw(); }
+      else if (type === "resize") gestures.cancel("pointer-cancel");
+      return;
+    }
     const point = eventPoint(event);
     if (!point) return;
     if (interaction.phase === "start") {
-      commitText(); cancel(); surface.current?.focus(); select(object.id);
+      commitText(); cancel(); surface.current?.focus();
+      if (type === "drag") { beginSelect(point, object.id, event); return; }
       const latest = current().objects.find((item) => item.id === object.id);
       if (latest) gestures.begin({ type, object: latest, start: point, point, edge, base: current() });
     } else {
+      if (type === "drag") {
+        if (selecting.current?.key !== object.id || selecting.current.pointerId !== event.pointerId) return;
+        if (interaction.phase === "commit") commitSelect(point); else { profile.preview(point); redraw(); }
+        return;
+      }
       const active = gestures.getActive();
       if (!active || active.type !== type || active.object.id !== object.id) return;
       gestures.preview({ ...active, point });
@@ -180,26 +218,33 @@ export function useCanvasHand(editor: ObjectEditor, style: CanvasCreationStyle)
 
   function keyDown(event: KeyboardEvent) {
     if (event.nativeEvent.isComposing || isWebEditableTarget(event.target)) return;
-    const command = commands.resolve(event);
-    if (command === "cancel") {
+    const selectedAction = profile.keyDown(event, selectContext(), gestures.getActive() !== null || draft.current !== null);
+    if (selectedAction) {
       event.preventDefault();
-      if (gestures.getActive() || draft.current) cancel(); else select(null);
+      cancel();
+      if (selectedAction.type === "selection") applySelection(selectedAction.selection);
+      else if (selectedAction.type === "delete") remove();
+      else if (selectedAction.type === "edit") editText(selectedAction.key);
       setTool("select"); return;
     }
-    if (command === "edit" && editor.snapshot.selection.primaryKey) {
-      event.preventDefault(); editText(editor.snapshot.selection.primaryKey); return;
-    }
+    if (commands.resolve(event) === "cancel") { event.preventDefault(); setTool("select"); return; }
     const action = keyboard.resolve(event);
-    if (action?.type === "delete" && editor.snapshot.selection.keys.length) { event.preventDefault(); remove(); }
     if (action?.type === "undo" || action?.type === "redo") { event.preventDefault(); history(action.type); }
   }
 
   const gesture = gestures.getActive();
-  const objects = document.objects.map((object) => gesture && (gesture.type === "drag" || gesture.type === "resize") && gesture.object.id === object.id ? transformObject(object, transform(gesture)) : object);
+  const selectionPreview = profile.getPreview();
+  const translation = selectionPreview?.translation;
+  const translating = new Set(translation?.keys);
+  const selection = selectionPreview?.selection ?? snapshot.selection;
+  const objects = document.objects.map((object) => {
+    if (translation && translating.has(object.id)) return transformObject(object, translation);
+    return gesture?.type === "resize" && gesture.object.id === object.id ? transformObject(object, transform(gesture)) : object;
+  });
   const preview = gesture && (gesture.type === "create" || gesture.type === "draw") ? createPreview(gesture) : null;
 
   return {
-    document, snapshot, objects, preview, surface, tool, error, draft: draft.current,
+    document, snapshot, selection, marquee: selectionPreview?.marquee ?? null, objects, preview, surface, tool, error, draft: draft.current,
     choose, select, interaction, editText, commitText, cancel, remove, history,
     changeText(text: string) { if (draft.current) { draft.current = { ...draft.current, text }; redraw(); } },
     openJSON(json: string) {
@@ -213,7 +258,12 @@ export function useCanvasHand(editor: ObjectEditor, style: CanvasCreationStyle)
     },
     surfaceProps: {
       onPointerDown: pointerDown, onPointerMove: pointerMove,
-      onPointerUp(event: PointerEvent<SVGSVGElement>) { pointerMove(event); if (pointer.commit(event.pointerId) !== null) commitGesture(); },
+      onPointerUp(event: PointerEvent<SVGSVGElement>) {
+        pointerMove(event);
+        if (pointer.commit(event.pointerId) === null) return;
+        const point = eventPoint(event);
+        if (selecting.current && point) commitSelect(point); else commitGesture();
+      },
       onPointerCancel(event: PointerEvent<SVGSVGElement>) { pointer.cancel(event.pointerId); },
       onLostPointerCapture(event: PointerEvent<SVGSVGElement>) { pointer.cancel(event.pointerId, "lost-capture"); },
       onKeyDown: keyDown,
diff --git a/packages/json-document-canvas/tests/canvas-hand.test.tsx b/packages/json-document-canvas/tests/canvas-hand.test.tsx
index 24c99f23..2ee56189 100644
--- a/packages/json-document-canvas/tests/canvas-hand.test.tsx
+++ b/packages/json-document-canvas/tests/canvas-hand.test.tsx
@@ -4,6 +4,7 @@ import { createJSONDocument } from "@interactive-os/json-document";
 import { createObjectEditor } from "@interactive-os/json-document-editing";
 import type { CanvasDocument } from "@interactive-os/json-document-object-document";
 import { CanvasHand } from "../src/index.js";
+import { createPlaneSelectProfile } from "@interactive-os/json-document-affordance";
 
 const blank: CanvasDocument = { profile: "canvas/1", width: 1280, height: 720, objects: [] };
 const style = { color: "#abcdef", textColor: "#123456", fontSize: 32, strokeWidth: 3 };
@@ -17,12 +18,12 @@ beforeAll(() => {
 });
 afterEach(cleanup);
 
-function setup(document = blank) {
+function setup(document = blank, selectProfile = createPlaneSelectProfile()) {
   const source = createJSONDocument(document);
   const commits = vi.fn(); source.subscribe(commits);
   let id = 0;
   const editor = createObjectEditor(source, { createId: () => `object-${++id}` });
-  const view = render(<CanvasHand editor={editor} creationStyle={style} />);
+  const view = render(<CanvasHand editor={editor} creationStyle={style} selectProfile={selectProfile} />);
   const svg = screen.getByRole("group", { name: "Canvas slide" });
   Object.defineProperty(svg, "viewBox", { value: { baseVal: { x: 0, y: 0, width: 1280, height: 720 } } });
   svg.getBoundingClientRect = () => ({ x: 0, y: 0, left: 0, top: 0, right: 640, bottom: 360, width: 640, height: 360, toJSON() {} });
@@ -35,6 +36,139 @@ function rectangle(svg: Element) {
   fireEvent.pointerDown(svg, event(40, 50)); fireEvent.pointerMove(svg, event(140, 100)); fireEvent.pointerUp(svg, event(140, 100));
 }
 
+const populated: CanvasDocument = { ...blank, objects: [
+  { id: "a", kind: "text", label: "Title", fontSize: 24, color: "black", x: 100, y: 100, width: 100, height: 100 },
+  { id: "b", kind: "rectangle", label: "Box", color: "blue", x: 300, y: 100, width: 100, height: 100 },
+  { id: "c", kind: "ellipse", label: "Circle", color: "green", x: 600, y: 100, width: 100, height: 100 },
+] };
+function pick(container: HTMLElement, key: string, shiftKey = false) {
+  const target = container.querySelector(`[data-canvas-object="${key}"]`)!;
+  fireEvent.pointerDown(target, { ...event(70, 70), shiftKey });
+  fireEvent.pointerUp(window, { ...event(70, 70), shiftKey });
+}
+
+test("Canvas consumes an injected profile for click/Shift/keyboard while focus remains independent", () => {
+  const profile = createPlaneSelectProfile();
+  const begin = vi.spyOn(profile, "begin"), keyDown = vi.spyOn(profile, "keyDown");
+  const { container, svg, editor, value, commits } = setup(populated, profile);
+  pick(container, "c", true); expect(editor.snapshot.selection.keys).toEqual(["a", "c"]);
+  pick(container, "a", true); expect(editor.snapshot.selection.keys).toEqual(["c"]);
+  pick(container, "b"); expect(editor.snapshot.selection.keys).toEqual(["b"]);
+  expect(begin).toHaveBeenCalledTimes(3);
+  const a = container.querySelector('[data-canvas-object="a"]')!;
+  fireEvent.focus(a); expect(editor.snapshot.selection.keys).toEqual(["b"]);
+  fireEvent.keyDown(a, { key: " ", shiftKey: true }); expect(editor.snapshot.selection.keys).toEqual(["a", "b"]);
+  expect(editor.snapshot.selection.primaryKey).toBe("a");
+  for (let i = 0; i < 2; i++) fireEvent.keyDown(svg, { key: "a", metaKey: true });
+  expect(editor.snapshot.selection.keys).toEqual(["a", "b", "c"]); expect(editor.snapshot.selection.primaryKey).toBe("a");
+  expect(keyDown).toHaveBeenCalled();
+  expect(container.querySelectorAll('[aria-pressed="true"][data-canvas-object]')).toHaveLength(3);
+  fireEvent.pointerDown(svg, event(500, 300)); fireEvent.pointerUp(svg, event(500, 300));
+  expect(editor.snapshot.selection.keys).toEqual([]); expect(value()).toEqual(populated);
+  expect(commits).not.toHaveBeenCalled(); expect(editor.snapshot.canUndo).toBe(false);
+});
+
+test("Enter activates the focused object instead of editing an unrelated primary", () => {
+  const { container, editor } = setup(populated);
+  const box = container.querySelector('[data-canvas-object="b"]')!;
+  fireEvent.focus(box); fireEvent.keyDown(box, { key: "Enter" });
+  expect(editor.snapshot.selection.keys).toEqual(["b"]);
+  expect(screen.queryByRole("textbox", { name: "Canvas text" })).toBeNull();
+  const text = container.querySelector('[data-canvas-object="a"]')!;
+  fireEvent.focus(text); fireEvent.keyDown(text, { key: "Enter" });
+  expect(editor.snapshot.selection.keys).toEqual(["a"]);
+  expect(screen.getByRole("textbox", { name: "Canvas text" })).toBeTruthy();
+});
+
+test("marquee previews replace and Shift-add from the base without committing the document", () => {
+  const { container, svg, editor, value, commits } = setup(populated);
+  pick(container, "c");
+  fireEvent.pointerDown(svg, event(20, 20)); fireEvent.pointerMove(svg, event(210, 110));
+  expect(editor.snapshot.selection.keys).toEqual(["c"]);
+  expect(container.querySelectorAll("[data-selection-outline]")).toHaveLength(2);
+  expect(container.querySelector("[data-canvas-marquee]")).not.toBeNull();
+  fireEvent.pointerUp(svg, event(210, 110)); expect(editor.snapshot.selection.keys).toEqual(["a", "b"]);
+  expect(container.querySelector("[data-canvas-marquee]")).toBeNull();
+  fireEvent.pointerDown(svg, { ...event(280, 20), shiftKey: true });
+  fireEvent.pointerMove(svg, event(360, 110)); fireEvent.pointerUp(svg, event(360, 110));
+  expect(editor.snapshot.selection.keys).toEqual(["a", "b", "c"]);
+  expect(value()).toEqual(populated); expect(commits).not.toHaveBeenCalled();
+});
+
+test("dragging a selected hit moves the set once; one Undo restores the set and Delete removes it atomically", () => {
+  const { container, svg, editor, value, commits } = setup(populated);
+  pick(container, "b", true);
+  const before = value(), target = container.querySelector('[data-canvas-object="a"]')!;
+  fireEvent.pointerDown(target, event(70, 70)); fireEvent.pointerMove(window, event(100, 100));
+  expect(value()).toBe(before); expect(commits).not.toHaveBeenCalled();
+  expect(container.querySelector('[data-canvas-object="b"]')?.getAttribute("x")).toBe("360");
+  fireEvent.pointerUp(window, event(100, 100));
+  expect(value().objects.map((object) => object.x)).toEqual([160, 360, 600]);
+  expect(editor.snapshot.selection).toMatchObject({ keys: ["a", "b"], primaryKey: "a" });
+  expect(commits).toHaveBeenCalledTimes(1);
+  fireEvent.keyDown(svg, { key: "z", metaKey: true }); expect(value()).toEqual(before);
+  expect(editor.snapshot.canUndo).toBe(false); expect(editor.snapshot.selection.keys).toEqual(["a", "b"]);
+  fireEvent.keyDown(svg, { key: "z", metaKey: true, shiftKey: true });
+  const moved = value(); commits.mockClear();
+  fireEvent.keyDown(svg, { key: "Delete" }); expect(value().objects.map((object) => object.id)).toEqual(["c"]);
+  expect(commits).toHaveBeenCalledTimes(1);
+  fireEvent.keyDown(svg, { key: "z", metaKey: true }); expect(value()).toEqual(moved);
+  expect(editor.snapshot.selection).toMatchObject({ keys: ["a", "b"], primaryKey: "a" });
+});
+
+test.each(["Escape", "pointercancel", "lostpointercapture"])("%s cancels marquee before clearing the base selection", (reason) => {
+  const { container, svg, editor, value, commits } = setup(populated);
+  fireEvent.pointerDown(svg, event(20, 20)); fireEvent.pointerMove(svg, event(220, 110));
+  if (reason === "Escape") fireEvent.keyDown(svg, { key: reason });
+  else if (reason === "pointercancel") fireEvent.pointerCancel(svg, event(220, 110));
+  else fireEvent.lostPointerCapture(svg, event(220, 110));
+  fireEvent.pointerUp(svg, event(220, 110));
+  expect(container.querySelector("[data-canvas-marquee]")).toBeNull();
+  expect(editor.snapshot.selection.keys).toEqual(["a"]); expect(value()).toEqual(populated);
+  expect(commits).not.toHaveBeenCalled(); expect(editor.snapshot.canUndo).toBe(false);
+  fireEvent.keyDown(svg, { key: "Escape" }); expect(editor.snapshot.selection.keys).toEqual([]);
+});
+
+test("only primary resizes and edits text while retaining the selected set", () => {
+  const { container, svg, editor, value, commits } = setup(populated);
+  act(() => { editor.dispatch({ type: "selection.set", objectIds: ["a", "b"], primaryKey: "a" }); });
+  expect(container.querySelectorAll("[data-resize-edge]")).toHaveLength(4);
+  const handle = container.querySelector('[data-resize-edge="se"]')!;
+  fireEvent.pointerDown(handle, event(100, 100)); fireEvent.pointerMove(window, event(120, 115)); fireEvent.pointerUp(window, event(120, 115));
+  expect(value().objects[0]!.width).toBeCloseTo(140); expect(value().objects[0]!.height).toBeCloseTo(130);
+  expect(value().objects[1]).toEqual(populated.objects[1]);
+  expect(editor.snapshot.selection).toMatchObject({ keys: ["a", "b"], primaryKey: "a" });
+  expect(commits).toHaveBeenCalledTimes(1);
+  fireEvent.keyDown(svg, { key: "F2" });
+  const input = screen.getByRole("textbox", { name: "Canvas text" });
+  fireEvent.keyDown(input, { key: "a", metaKey: true }); expect(editor.snapshot.selection.keys).toEqual(["a", "b"]);
+  fireEvent.change(input, { target: { value: "Primary only" } });
+  fireEvent.keyDown(input, { key: "Enter", metaKey: true });
+  expect(value().objects[0]!.label).toBe("Primary only"); expect(value().objects[1]).toEqual(populated.objects[1]);
+  expect(editor.snapshot.selection).toMatchObject({ keys: ["a", "b"], primaryKey: "a" });
+  expect(commits).toHaveBeenCalledTimes(2);
+  fireEvent.keyDown(svg, { key: "z", metaKey: true }); expect(value().objects[0]!.label).toBe("Title");
+});
+
+test("external document replacement cancels marquee and stale release cannot select removed targets", () => {
+  const { container, svg, source, editor, value } = setup(populated);
+  fireEvent.pointerDown(svg, event(20, 20)); fireEvent.pointerMove(svg, event(220, 110));
+  act(() => { source.commit([{ op: "remove", path: "/objects/1" }]); });
+  fireEvent.pointerUp(svg, event(220, 110));
+  expect(container.querySelector("[data-canvas-marquee]")).toBeNull();
+  expect(editor.snapshot.selection.keys).toEqual(["a"]);
+  expect(value().objects.map((object) => object.id)).toEqual(["a", "c"]);
+});
+
+test("external selection changes supersede a pending preview without a stale selection commit", () => {
+  const { container, svg, editor, commits } = setup(populated);
+  fireEvent.pointerDown(svg, event(20, 20)); fireEvent.pointerMove(svg, event(220, 110));
+  act(() => { editor.dispatch({ type: "selection.set", objectIds: ["c"] }); });
+  fireEvent.pointerUp(svg, event(220, 110));
+  expect(container.querySelector("[data-canvas-marquee]")).toBeNull();
+  expect(editor.snapshot.selection.keys).toEqual(["c"]); expect(commits).not.toHaveBeenCalled();
+});
+
 test("every toolbar control shares icon, accessible name and canonical tooltip without losing state", () => {
   const { svg } = setup();
   const toolbar = within(screen.getByRole("toolbar", { name: "Canvas tools" }));
diff --git a/packages/json-document-editing/docs/object-selection.md b/packages/json-document-editing/docs/object-selection.md
new file mode 100644
index 00000000..700c47c6
--- /dev/null
+++ b/packages/json-document-editing/docs/object-selection.md
@@ -0,0 +1,23 @@
+## Object Selection · primary와 집합 편집
+
+`selection.set`은 `objectIds`, `mode`와 선택적인 `primaryKey`를 받습니다.
+`primaryKey`를 생략하면 Selection key family의 기본 전이를 사용합니다.
+명시하면 **전이 후 선택 집합에 포함된 key**여야 하며, 아니면
+`selection.primary-not-selected`로 기존 상태·문서·History를 보존합니다.
+
+`object.translate`, `object.resize`, `object.text`의 대상이 현재 선택의 부분집합이면
+선택 집합과 primary를 보존합니다. 선택 밖 대상을 직접 지정하면 기존대로 그 대상을
+선택합니다. 따라서 전체 선택 이동, primary만 resize/text 편집을 같은 ObjectEditor로
+실행할 수 있습니다. 문서 연산·검증은 Object Document Type이 소유합니다.
+
+```ts
+editor.dispatch({ type: "selection.set", objectIds: ["a", "b"], primaryKey: "a" });
+editor.dispatch({ type: "object.translate", objectIds: ["a", "b"], dx: 20, dy: 10 });
+editor.dispatch({ type: "object.resize", objectIds: ["a"], dx: 0, dy: 0, dw: 10, dh: 0 });
+```
+
+선택은 문서 밖의 Editing session 상태입니다. 선택 전이는 문서 commit이나 Undo 기록을
+만들지 않고 redo도 제거하지 않습니다. 집합 이동·삭제는 객체마다 dispatch하지 않고 하나의
+Intent를 사용합니다. Undo/Redo는 해당 문서 변경과 함께 원인 선택 집합·primary를 복원합니다.
+
+실제 public API 소비: [Canvas Usage와 Source](/demo/canvas).
diff --git a/packages/json-document-editing/src/object.ts b/packages/json-document-editing/src/object.ts
index 9c7ff1f9..62adb7f0 100644
--- a/packages/json-document-editing/src/object.ts
+++ b/packages/json-document-editing/src/object.ts
@@ -58,6 +58,7 @@ export type ObjectIntent =
       readonly type: "selection.set";
       readonly objectIds: ReadonlyArray<string>;
       readonly mode?: ObjectSelectionMode;
+      readonly primaryKey?: string;
     }
   | { readonly type: "selection.remove" }
   | { readonly type: "selection.fill"; readonly color: string }
@@ -139,7 +140,7 @@ export function createObjectEditor(
       return apply({ type: "insert", objects: [object] }, selectionFor([object.id]), intent.type);
     }
     if (intent.type === "object.text") {
-      return apply({ type: "text", objectId: intent.objectId, text: intent.text }, selectionFor([intent.objectId]), intent.type);
+      return apply({ type: "text", objectId: intent.objectId, text: intent.text }, selectionForTargets([intent.objectId]), intent.type);
     }
     if (intent.type === "document.replace") {
       // A profile-specific session cannot silently become another document type.
@@ -155,23 +156,28 @@ export function createObjectEditor(
         type: intent.mode === "extend" ? "add" : intent.mode ?? "replace",
         keys: intent.objectIds,
       };
-      const selection = selectionFamily.transition(
+      const context = selectionContext();
+      let selection = selectionFamily.transition(
         session.snapshot.selection,
         command,
-        selectionContext(),
+        context,
       ).state;
+      if (intent.primaryKey !== undefined) {
+        if (!selectionFamily.targets(selection, context).includes(intent.primaryKey)) return failure("selection.primary-not-selected");
+        selection = selectionFamily.transition(selection, { type: "set-primary", key: intent.primaryKey }, context).state;
+      }
       return success(session.select(selectionFor(
-        selectionFamily.targets(selection, selectionContext()),
+        selectionFamily.targets(selection, context),
         selection.primaryKey,
       )));
     }
 
     if (intent.type === "object.translate") {
-      return apply({ type: "transform", objectIds: intent.objectIds, transform: { dx: intent.dx, dy: intent.dy } }, selectionFor(intent.objectIds), intent.type);
+      return apply({ type: "transform", objectIds: intent.objectIds, transform: { dx: intent.dx, dy: intent.dy } }, selectionForTargets(intent.objectIds), intent.type);
     }
 
     if (intent.type === "object.resize") {
-      return apply({ type: "transform", objectIds: intent.objectIds, transform: { dx: intent.dx, dy: intent.dy, dw: intent.dw, dh: intent.dh } }, selectionFor(intent.objectIds), intent.type);
+      return apply({ type: "transform", objectIds: intent.objectIds, transform: { dx: intent.dx, dy: intent.dy, dw: intent.dw, dh: intent.dh } }, selectionForTargets(intent.objectIds), intent.type);
     }
 
     if (intent.type === "clipboard.paste") {
@@ -194,6 +200,12 @@ export function createObjectEditor(
     return intent.type === "selection.remove" ? removeSelected(selected.map((object) => object.id)) : failure("object.unsupported-intent");
   }
 
+  function selectionForTargets(ids: readonly string[]): ObjectSelection {
+    const selection = session.snapshot.selection;
+    const selected = new Set(selection.keys);
+    return ids.length > 0 && ids.every((id) => selected.has(id)) ? selection : selectionFor(ids);
+  }
+
   function apply(operation: ObjectOperation, selectionAfter: ObjectSelection, origin: string): EditingResult<ObjectSelection> {
     const plan = planObjectOperation(value(), operation);
     return plan.ok ? session.apply({ operations: plan.operations, selectionAfter, origin }) : plan;
diff --git a/packages/json-document-editing/tests/object-editor.test.ts b/packages/json-document-editing/tests/object-editor.test.ts
index b032a1ea..d1236fe0 100644
--- a/packages/json-document-editing/tests/object-editor.test.ts
+++ b/packages/json-document-editing/tests/object-editor.test.ts
@@ -13,6 +13,37 @@ const initial: ObjectDocument = {
 };
 
 describe("object editing selection family", () => {
+  test("primaryKey applies after subtract and toggle, and must survive the transition", () => {
+    const editor = createObjectEditor(initial);
+    editor.dispatch({ type: "selection.set", objectIds: ["a", "b", "c"] });
+    editor.dispatch({ type: "selection.set", objectIds: ["b"], mode: "subtract", primaryKey: "a" });
+    expect(editor.snapshot.selection).toEqual({ kind: "explicit", keys: ["a", "c"], primaryKey: "a" });
+    editor.dispatch({ type: "selection.set", objectIds: ["b"], mode: "toggle", primaryKey: "c" });
+    expect(editor.snapshot.selection).toEqual({ kind: "explicit", keys: ["a", "b", "c"], primaryKey: "c" });
+    const before = editor.snapshot;
+    expect(editor.dispatch({ type: "selection.set", objectIds: ["c"], mode: "subtract", primaryKey: "c" }).ok).toBe(false);
+    expect(editor.snapshot).toEqual(before);
+  });
+  test("explicit primary survives set movement and primary-only edits, including undo/redo", () => {
+    const editor = createObjectEditor(initial);
+    editor.dispatch({ type: "selection.set", objectIds: ["a", "c"], primaryKey: "a" });
+    const selected = editor.snapshot.selection;
+    expect(selected.primaryKey).toBe("a");
+    expect(editor.snapshot.canUndo).toBe(false);
+    for (const intent of [
+      { type: "object.translate", objectIds: ["a", "c"], dx: 5, dy: 10 },
+      { type: "object.resize", objectIds: ["a"], dx: 0, dy: 0, dw: 10, dh: 20 },
+    ] as const) {
+      const before = editor.snapshot.value;
+      expect(editor.dispatch(intent).ok).toBe(true);
+      expect(editor.snapshot.selection).toEqual(selected);
+      editor.undo(); expect(editor.snapshot.value).toEqual(before); expect(editor.snapshot.selection).toEqual(selected);
+      editor.redo(); expect(editor.snapshot.selection).toEqual(selected);
+    }
+    const before = editor.snapshot;
+    expect(editor.dispatch({ type: "selection.set", objectIds: ["a"], primaryKey: "c" }).ok).toBe(false);
+    expect(editor.snapshot).toEqual(before);
+  });
   test("uses set transitions for click and host-resolved marquee candidates", () => {
     const editor = createObjectEditor(initial);
     editor.dispatch({ type: "selection.set", objectIds: ["b"], mode: "toggle" });
diff --git a/site/src/routes/canvas-demo/CanvasDemoRoute.tsx b/site/src/routes/canvas-demo/CanvasDemoRoute.tsx
index 63f069bb..c1a80056 100644
--- a/site/src/routes/canvas-demo/CanvasDemoRoute.tsx
+++ b/site/src/routes/canvas-demo/CanvasDemoRoute.tsx
@@ -1,6 +1,7 @@
 import { useState } from "react";
 import { createObjectEditor } from "@interactive-os/json-document-editing";
 import { CanvasHand } from "@interactive-os/json-document-canvas";
+import { createPlaneSelectProfile } from "@interactive-os/json-document-affordance";
 import { DemoPage } from "../../shared/demo-workbench/DemoPage";
 import { canvasCreationStyle, emptyCanvasDocument } from "../../shared/demo-workbench/canvas-demo-document";
 import { PageHeader } from "../../shared/ui/primitives";
@@ -8,9 +9,10 @@ import { ui } from "../../shared/ui/styles";
 
 export function CanvasDemoRoute() {
   const [editor] = useState(() => createObjectEditor(emptyCanvasDocument));
+  const [selectProfile] = useState(() => createPlaneSelectProfile());
   return (
-    <DemoPage documentation={<PageHeader illustration="peek" title="Canvas">한 장에 글자·도형·그리기. 도구를 고른 뒤 슬라이드를 클릭하거나 드래그하세요. 글자는 더블클릭으로 편집합니다.</PageHeader>}>
-      <CanvasHand className={ui.product.embedded} editor={editor} creationStyle={canvasCreationStyle} slideStyle={{ background: "rgb(var(--color-background-canvas))" }} />
+    <DemoPage documentation={<PageHeader illustration="peek" title="Canvas">한 장에 글자·도형·그리기. Shift+클릭으로 다중 선택하고 빈 곳을 드래그해 영역을 고릅니다. 선택한 객체들은 함께 움직이며, 글자는 더블클릭으로 편집합니다.</PageHeader>}>
+      <CanvasHand className={ui.product.embedded} editor={editor} selectProfile={selectProfile} creationStyle={canvasCreationStyle} slideStyle={{ background: "rgb(var(--color-background-canvas))" }} />
     </DemoPage>
   );
 }
diff --git a/site/src/routes/docs/doc-pages.ts b/site/src/routes/docs/doc-pages.ts
index 23f3cd69..563841db 100644
--- a/site/src/routes/docs/doc-pages.ts
+++ b/site/src/routes/docs/doc-pages.ts
@@ -11,6 +11,8 @@ import connectorA2uiMarkdown from "../../../../docs/public/connector-a2ui.md?raw
 import zodApiMarkdown from "../../../../docs/api-reference/zod.md?raw";
 import tanStackTableApiMarkdown from "../../../../docs/api-reference/tanstack-table.md?raw";
 import affordanceApiMarkdown from "../../../../docs/api-reference/affordance.md?raw";
+import planeSelectContractMarkdown from "../../../../packages/json-document-affordance/docs/plane-select.md?raw";
+import objectSelectionContractMarkdown from "../../../../packages/json-document-editing/docs/object-selection.md?raw";
 import uiPrimitivesApiMarkdown from "../../../../docs/api-reference/ui-primitives-react.md?raw";
 import animationApiMarkdown from "../../../../docs/api-reference/animation-react.md?raw";
 import markdownReactApiMarkdown from "../../../../docs/api-reference/markdown-react.md?raw";
@@ -183,7 +185,7 @@ export const docPages = {
   api: docPage("/docs/api", apiReferenceMarkdown),
   jsonDocumentApi: docPage("/docs/api/json-document", jsonDocumentApiMarkdown),
   selectionApi: docPage("/docs/api/selection", selectionApiMarkdown),
-  editingApi: docPage("/docs/api/editing", `${editingApiMarkdown}\n\n${calendarProfileMarkdown}`),
+  editingApi: docPage("/docs/api/editing", `${objectSelectionContractMarkdown}\n\n${editingApiMarkdown}\n\n${calendarProfileMarkdown}`),
   reactApi: docPage("/docs/api/react", reactApiMarkdown),
   reactHookFormApi: docPage("/docs/api/react-hook-form", reactHookFormApiMarkdown),
   ajvApi: docPage("/docs/api/ajv", ajvApiMarkdown),
@@ -191,7 +193,7 @@ export const docPages = {
   connectorA2ui: docPage("/docs/connector-a2ui", connectorA2uiMarkdown),
   zodApi: docPage("/docs/api/zod", zodApiMarkdown),
   tanStackTableApi: docPage("/docs/api/tanstack-table", tanStackTableApiMarkdown),
-  affordanceApi: docPage("/docs/api/affordance", affordanceApiMarkdown),
+  affordanceApi: docPage("/docs/api/affordance", `${planeSelectContractMarkdown}\n\n${affordanceApiMarkdown}`),
   uiPrimitivesApi: docPage("/docs/api/ui-primitives-react", uiPrimitivesApiMarkdown),
   animationApi: docPage("/docs/api/animation-react", animationApiMarkdown),
   markdownReactApi: docPage("/docs/api/markdown-react", markdownReactApiMarkdown),
diff --git a/site/src/routes/widgets/CanvasWidgetRoute.tsx b/site/src/routes/widgets/CanvasWidgetRoute.tsx
index 3591e9c4..55cdd911 100644
--- a/site/src/routes/widgets/CanvasWidgetRoute.tsx
+++ b/site/src/routes/widgets/CanvasWidgetRoute.tsx
@@ -13,7 +13,7 @@ export function CanvasWidgetRoute() {
     widgetLabel="Canvas Hand" widget={<CanvasHand className={ui.product.embedded} editor={editor} creationStyle={canvasCreationStyle} slideStyle={{ background: "rgb(var(--color-background-canvas))" }} />}
     values={[
       { label: "selectedKeys", value: snapshot.selection.keys, testId: "widget-canvas-selected", size: "compact" },
-      { label: "focus", value: snapshot.selection.primaryKey, testId: "widget-canvas-focus", size: "compact" },
+      { label: "primaryKey", value: snapshot.selection.primaryKey, testId: "widget-canvas-primary", size: "compact" },
       { label: "selection", value: snapshot.selection, testId: "widget-canvas-selection", size: "compact" },
     ]} />;
 }
diff --git a/site/src/shared/demo-workbench/demo-sources.ts b/site/src/shared/demo-workbench/demo-sources.ts
index 7e0f3431..d39a6372 100644
--- a/site/src/shared/demo-workbench/demo-sources.ts
+++ b/site/src/shared/demo-workbench/demo-sources.ts
@@ -33,6 +33,8 @@ import dateValuesSource from "../../../../packages/json-document-calendar/src/da
 import editingItemSource from "../../../../packages/json-document-react/src/use-editing.ts?raw";
 import affordanceSessionSource from "../../../../packages/json-document-affordance/src/session.ts?raw";
 import affordanceSelectSource from "../../../../packages/json-document-affordance/src/select.ts?raw";
+import planeSelectSource from "../../../../packages/json-document-affordance/src/plane-select.ts?raw";
+import affordanceDragSource from "../../../../packages/json-document-affordance/src/drag.ts?raw";
 import viewportPositionSource from "../../../../packages/json-document-affordance/src/viewport-position.ts?raw";
 import anchoredFloatingPositionSource from "../../../../packages/json-document-affordance/src/anchored-floating-position.ts?raw";
 import webFocusItemSource from "../../../../packages/json-document-web/src/focus-item.ts?raw";
@@ -276,6 +278,8 @@ const registeredUsageSources = new Map<string, string>([
   ["packages/json-document-affordance/src/board-drag-session.ts", boardDragSessionSource],
   ["packages/json-document-affordance/src/canvas-gesture-session.ts", canvasGestureSessionSource],
   ["packages/json-document-affordance/src/gesture-session.ts", gestureSessionSource],
+  ["packages/json-document-affordance/src/plane-select.ts", planeSelectSource],
+  ["packages/json-document-affordance/src/drag.ts", affordanceDragSource],
   ["packages/json-document-affordance/src/interaction-handle.ts", interactionHandleSource],
   ["packages/json-document-affordance/src/content-interaction.ts", contentInteractionAffordanceSource],
   ["packages/json-document-editing/src/database.ts", databaseEditingSource],
@@ -1272,6 +1276,36 @@ const registeredPublicUsages = [
     symbol: "createCanvasGestureSession",
     sourcePath: "packages/json-document-affordance/src/canvas-gesture-session.ts",
   },
+  {
+    packageName: "@interactive-os/json-document-affordance",
+    symbol: "createPlaneSelectProfile",
+    sourcePath: "packages/json-document-affordance/src/plane-select.ts",
+  },
+  {
+    packageName: "@interactive-os/json-document-affordance",
+    symbol: "createPlaneSelectProfile",
+    sourcePath: "packages/json-document-affordance/src/select.ts",
+  },
+  {
+    packageName: "@interactive-os/json-document-affordance",
+    symbol: "createPlaneSelectProfile",
+    sourcePath: "packages/json-document-affordance/src/drag.ts",
+  },
+  {
+    packageName: "@interactive-os/json-document-affordance",
+    symbol: "createPlaneSelectProfile",
+    sourcePath: "packages/json-document-affordance/src/gesture-session.ts",
+  },
+  ...["dragAffordance", "resizeAffordance", "marqueeAffordance", "marqueeHitsAffordance"].map((symbol) => ({
+    packageName: "@interactive-os/json-document-affordance",
+    symbol,
+    sourcePath: "packages/json-document-affordance/src/drag.ts",
+  })),
+  {
+    packageName: "@interactive-os/json-document-selection",
+    symbol: "createKeySelectionFamily",
+    sourcePath: "packages/json-document-selection/src/key/index.ts",
+  },
   {
     packageName: "@interactive-os/json-document-affordance",
     symbol: "createInteractionHandleSession",
diff --git a/site/tests/browser/canvas-slice.spec.ts b/site/tests/browser/canvas-slice.spec.ts
index 5cdbff91..53fc13e7 100644
--- a/site/tests/browser/canvas-slice.spec.ts
+++ b/site/tests/browser/canvas-slice.spec.ts
@@ -89,3 +89,49 @@ test("Canvas move and resize are single history steps and Escape cancels a gestu
   await page.getByRole("button", { name: "실행 취소" }).click();
   expect(Number(await object.getAttribute("x"))).toBeCloseTo(100);
 });
+
+test("Plane Select moves a selected set with one Undo and collapses a plain click on release", async ({ page }) => {
+  await page.goto("/widgets/canvas");
+  const rectangle = page.locator('[data-canvas-object="rectangle"]');
+  const ellipse = page.locator('[data-canvas-object="ellipse"]');
+  const selected = page.locator('[data-canvas-object][aria-pressed="true"]');
+  await rectangle.click(); await ellipse.click({ modifiers: ["Shift"] });
+  await expect(selected).toHaveCount(2);
+  const start = await point(page, 200, 350), end = await point(page, 280, 390);
+  await page.mouse.move(start.x, start.y); await page.mouse.down();
+  await page.mouse.move(end.x, end.y, { steps: 6 });
+  expect(Number(await rectangle.getAttribute("x"))).toBeCloseTo(176);
+  expect(Number(await ellipse.getAttribute("x"))).toBeCloseTo(696);
+  await page.mouse.up();
+  await page.getByRole("button", { name: "실행 취소" }).click();
+  expect(Number(await rectangle.getAttribute("x"))).toBeCloseTo(96);
+  expect(Number(await ellipse.getAttribute("x"))).toBeCloseTo(616);
+  await expect(selected).toHaveCount(2);
+  await expect(page.getByRole("button", { name: "실행 취소" })).toBeDisabled();
+  await rectangle.click(); await expect(selected).toHaveCount(1);
+});
+
+test("Plane Select marquee, cancellation and primary editing share the public profile", async ({ page }) => {
+  await page.goto("/widgets/canvas");
+  const selected = page.locator('[data-canvas-object][aria-pressed="true"]');
+  const start = await point(page, 50, 230), end = await point(page, 900, 530);
+  await page.mouse.move(start.x, start.y); await page.mouse.down(); await page.mouse.move(end.x, end.y);
+  await expect(page.locator("[data-canvas-marquee]")).toHaveCount(1); await expect(selected).toHaveCount(2);
+  await page.keyboard.press("Escape"); await page.mouse.up();
+  await expect(page.locator("[data-canvas-marquee]")).toHaveCount(0);
+  await expect(page.locator('[data-canvas-object="title"]')).toHaveAttribute("aria-pressed", "true");
+  await page.keyboard.press("Escape"); await expect(selected).toHaveCount(0);
+  await page.mouse.move(start.x, start.y); await page.mouse.down(); await page.mouse.move(end.x, end.y); await page.mouse.up();
+  await expect(selected).toHaveCount(2);
+  await page.locator('[data-canvas-object="title"]').click({ modifiers: ["Shift"] });
+  await expect(selected).toHaveCount(3);
+  await page.keyboard.press("ControlOrMeta+a"); await page.keyboard.press("ControlOrMeta+a");
+  await expect(selected).toHaveCount(3); await expect(page.locator("[data-resize-edge]")).toHaveCount(4);
+  await page.keyboard.press("F2");
+  const text = page.getByRole("textbox", { name: "Canvas text", exact: true });
+  await text.fill("Reusable selection"); await text.press("ControlOrMeta+Enter");
+  await expect(page.locator('[data-canvas-object="title"]')).toHaveAttribute("aria-label", "Reusable selection");
+  await expect(selected).toHaveCount(3);
+  await page.keyboard.press("ControlOrMeta+z");
+  await expect(page.locator('[data-canvas-object="title"]')).toHaveAttribute("aria-label", "One slide. Your ideas.");
+});
diff --git a/site/tests/browser/widgets.spec.ts b/site/tests/browser/widgets.spec.ts
index 7e9a0594..d455cae3 100644
--- a/site/tests/browser/widgets.spec.ts
+++ b/site/tests/browser/widgets.spec.ts
@@ -192,16 +192,20 @@ test("Document reads selected keys, focus, and text offset", async ({ page }) =>
   await expect(page.locator("#widget-document-option-move")).toHaveCount(1);
 });
 
-test("Canvas proof consumes the same Hand and observes single selection", async ({ page }) => {
+test("Canvas proof consumes the same Hand and observes selection independently of primary", async ({ page }) => {
   await page.goto("/widgets/canvas");
   await page.locator('[data-canvas-object="rectangle"]').click();
   expect(await json(page, "widget-canvas-selected")).toEqual(["rectangle"]);
-  expect(await json(page, "widget-canvas-focus")).toBe("rectangle");
+  expect(await json(page, "widget-canvas-primary")).toBe("rectangle");
+  await page.locator('[data-canvas-object="ellipse"]').click({ modifiers: ["Shift"] });
+  expect(await json(page, "widget-canvas-selected")).toEqual(["rectangle", "ellipse"]);
+  expect(await json(page, "widget-canvas-primary")).toBe("ellipse");
   await page.keyboard.press("Delete");
   await expect(page.locator('[data-canvas-object="rectangle"]')).toHaveCount(0);
+  await expect(page.locator('[data-canvas-object="ellipse"]')).toHaveCount(0);
   await page.keyboard.press("ControlOrMeta+z");
   await expect(page.locator('[data-canvas-object="rectangle"]')).toHaveCount(1);
-  expect(await json(page, "widget-canvas-selected")).toEqual(["rectangle"]);
+  expect(await json(page, "widget-canvas-selected")).toEqual(["rectangle", "ellipse"]);
 });
 
 test("Tree reads visible topology and selected keys", async ({ page }) => {
diff --git a/site/tests/unit/demo-workbench.test.tsx b/site/tests/unit/demo-workbench.test.tsx
index b71b370c..6461d390 100644
--- a/site/tests/unit/demo-workbench.test.tsx
+++ b/site/tests/unit/demo-workbench.test.tsx
@@ -55,6 +55,23 @@ describe("DemoWorkbench", () => {
 });
 
 describe("Demo definition and source discovery", () => {
+  test("Canvas Usage imports the reusable Plane Select profile and exposes its canonical closure", async () => {
+    const sources = await discoverDemoSources("routes/canvas-demo/CanvasDemoRoute.tsx");
+    expect(await sources[0]!.load()).toContain("createPlaneSelectProfile()");
+    for (const [path, reference] of [
+      ["packages/json-document-affordance/src/plane-select.ts", "/docs/api/affordance"],
+      ["packages/json-document-affordance/src/drag.ts", "/docs/api/affordance"],
+      ["packages/json-document-affordance/src/select.ts", "/docs/api/affordance"],
+      ["packages/json-document-affordance/src/gesture-session.ts", "/docs/api/affordance"],
+      ["packages/json-document-selection/src/key/index.ts", "/docs/api/selection"],
+      ["packages/json-document-editing/src/object.ts", "/docs/api/editing"],
+      ["packages/json-document-canvas/src/use-canvas-hand.ts", "/docs/api/canvas"],
+    ]) {
+      const file = sources.find((source) => source.path === path);
+      expect(file, path).toBeDefined(); expect(file!.referencePath).toBe(reference);
+      expect(await file!.load()).not.toBe("");
+    }
+  });
   test("Calendar Usage exposes the shared edit plan and each canonical owner's API", async () => {
     const sources = await discoverDemoSources("routes/calendar-demo/CalendarDemoRoute.tsx");
     const plan = sources.find((file) => file.path === "packages/json-document-calendar-document/src/calendar-operation.ts");
@@ -217,6 +234,7 @@ describe("Demo definition and source discovery", () => {
       "packages/json-document/src/application/document/create.ts",
       "packages/json-document-object-document/src/object-projection.ts",
       "packages/json-document-object-document/src/object-operation.ts",
+      "packages/json-document-selection/src/key/index.ts",
     ]);
   });
 
@@ -296,6 +314,7 @@ describe("Demo definition and source discovery", () => {
       "packages/json-document-ui-primitives-react/src/controls.tsx",
       "packages/json-document-ui-primitives-react/src/product-shell.tsx",
       "packages/json-document-editing/src/kanban.ts",
+      "packages/json-document-selection/src/key/index.ts",
       "packages/json-document-web/src/kanban-drop-target.ts",
       "packages/json-document-react/src/use-editing.ts",
       "packages/json-document-web/src/drag-drop-session.ts",
@@ -307,10 +326,12 @@ describe("Demo definition and source discovery", () => {
       "packages/json-document-affordance/src/content-interaction.ts",
       "packages/json-document-ui-primitives-react/src/controls.tsx",
       "packages/json-document-editing/src/kanban.ts",
+      "packages/json-document-selection/src/key/index.ts",
       "packages/json-document-web/src/kanban-drop-target.ts",
       "packages/json-document-react/src/use-editing.ts",
       "packages/json-document-web/src/pointer-session.ts",
       "packages/json-document-affordance/src/board-drag-session.ts",
+      "packages/json-document-affordance/src/drag.ts",
     ]);
   });
 

From 8c494b584ba09c597dafd8d962a87a7b7e74192b Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E1=84=8B=E1=85=B2=E1=84=8B=E1=85=AD=E1=86=BC=E1=84=90?=
 =?UTF-8?q?=E1=85=A2?= <teo.v@navercorp.com>
Date: Wed, 9 Sep 2026 19:19:41 +0900
Subject: [PATCH 12/20] =?UTF-8?q?feat(affordance):=20=ED=8F=89=EB=A9=B4=20?=
 =?UTF-8?q?=EC=84=A0=ED=83=9D=EC=9D=98=20=EB=B3=B5=EC=A0=9C=EC=99=80=20Cli?=
 =?UTF-8?q?pboard=20=EA=B8=B0=EB=B3=B8=EA=B8=B0=EB=A5=BC=20=EC=97=B0?=
 =?UTF-8?q?=EA=B2=B0=ED=95=9C=EB=8B=A4?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 docs/api-reference/affordance.md              |  20 +++-
 docs/api-reference/canvas.md                  |   2 +-
 docs/api-reference/editing.md                 |   8 +-
 docs/public/adapter-clipboard.md              |   3 +
 docs/public/affordance-copy-drag.md           |  83 ++++---------
 docs/public/affordance-nudge.md               |   8 +-
 docs/public/affordance.md                     |   3 +-
 docs/public/object.md                         |  10 +-
 .../docs/plane-select.md                      |  33 ++++--
 .../json-document-affordance/package.json     |   2 +-
 .../json-document-affordance/src/index.ts     |   2 +-
 .../src/plane-select.ts                       |  51 ++++++--
 .../tests/plane-select.test.ts                |  47 +++++++-
 packages/json-document-canvas/README.md       |   2 +
 packages/json-document-canvas/docs/api.md     |  27 ++++-
 .../json-document-canvas/src/canvas-hand.tsx  |  10 +-
 .../src/canvas-object-view.tsx                |   3 +-
 .../src/use-canvas-hand.ts                    |  56 ++++++---
 .../tests/canvas-hand.test.tsx                | 111 +++++++++++++++++-
 .../docs/object-selection.md                  |  33 ++++++
 packages/json-document-editing/package.json   |   2 +-
 packages/json-document-editing/src/object.ts  |  56 ++++++---
 .../tests/identity.test.ts                    |   6 +-
 .../tests/object-copy.test.ts                 |  88 ++++++++++++++
 .../json-document-object-document/docs/api.md |   2 +-
 packages/json-document-web/README.md          |   8 +-
 packages/json-document-web/docs/clipboard.md  |  33 ++++++
 packages/json-document-web/package.json       |   2 +-
 packages/json-document-web/src/clipboard.ts   |   4 +-
 .../tests/clipboard-rejection.test.ts         |   4 +-
 .../tests/web-adapters.test.ts                |   2 +-
 site/src/routes/docs/doc-pages.ts             |   3 +-
 .../routes/object-demo/ObjectDemoRoute.tsx    |  41 +------
 .../src/shared/demo-workbench/demo-sources.ts |  10 ++
 site/tests/browser/canvas-slice.spec.ts       |  29 ++++-
 site/tests/browser/editor-slice-demos.spec.ts |   6 +-
 site/tests/unit/demo-workbench.test.tsx       |   1 +
 37 files changed, 625 insertions(+), 186 deletions(-)
 create mode 100644 packages/json-document-editing/tests/object-copy.test.ts
 create mode 100644 packages/json-document-web/docs/clipboard.md

diff --git a/docs/api-reference/affordance.md b/docs/api-reference/affordance.md
index da183914..7cc3063c 100644
--- a/docs/api-reference/affordance.md
+++ b/docs/api-reference/affordance.md
@@ -714,10 +714,9 @@ interface PlaneSelectContext {
 ## `PlaneSelectInput`
 
 ```ts
-interface PlaneSelectInput {
+interface PlaneSelectInput extends PlaneSelectModifiers {
   readonly point: Point;
   readonly hitKey: string | null;
-  readonly shiftKey?: boolean;
 }
 ```
 ## `PlaneSelectKeyResult`
@@ -726,9 +725,19 @@ interface PlaneSelectInput {
 type PlaneSelectKeyResult =
   | { readonly type: "selection"; readonly selection: PlaneSelectSelection }
   | { readonly type: "delete"; readonly keys: readonly string[] }
+  | { readonly type: "duplicate"; readonly keys: readonly string[] }
+  | { readonly type: "translate"; readonly keys: readonly string[]; readonly dx: number; readonly dy: number }
   | { readonly type: "edit"; readonly key: string }
   | { readonly type: "cancel" };
 ```
+## `PlaneSelectModifiers`
+
+```ts
+interface PlaneSelectModifiers {
+  readonly shiftKey?: boolean;
+  readonly altKey?: boolean;
+}
+```
 ## `PlaneSelectPreview`
 
 ```ts
@@ -743,8 +752,10 @@ interface PlaneSelectPreview {
 ```ts
 interface PlaneSelectProfile {
   begin(context: PlaneSelectContext, input: PlaneSelectInput): PlaneSelectPreview;
-  preview(point: Point): PlaneSelectPreview | null;
-  commit(point: Point): PlaneSelectCommit | null;
+  preview(point: Point, modifiers?: PlaneSelectModifiers): PlaneSelectPreview | null;
+  commit(point: Point, modifiers?: PlaneSelectModifiers): PlaneSelectCommit | null;
+  /** Reproject a stationary drag when a modifier changes; omitted preview modifiers retain this state. */
+  updateModifiers(modifiers: PlaneSelectModifiers): PlaneSelectPreview | null;
   cancel(reason?: GestureCancelReason): void;
   getPreview(): PlaneSelectPreview | null;
   /** Discrete activation (e.g. Space), not focus. Shift toggles, plain activation replaces. */
@@ -771,6 +782,7 @@ type PlaneSelectSelection = Extract<KeySelection, { readonly kind: "explicit" }>
 
 ```ts
 interface PlaneSelectTranslation {
+  readonly operation: "move" | "copy";
   readonly keys: readonly string[];
   readonly dx: number;
   readonly dy: number;
diff --git a/docs/api-reference/canvas.md b/docs/api-reference/canvas.md
index 098addf3..ca2496ee 100644
--- a/docs/api-reference/canvas.md
+++ b/docs/api-reference/canvas.md
@@ -42,5 +42,5 @@ type CanvasTool = "select" | CanvasObjectKind;
 ## `useCanvasHand`
 
 ```ts
-useCanvasHand(editor: ObjectEditor, style: CanvasCreationStyle, selectProfile?: PlaneSelectProfile): { document: CanvasDocument; snapshot: import("<repository>/packages/json-document-editing/src/session").EditingSnapshot<ObjectSelection>; ... 18 more ...; surfaceProps: { ...; }; }
+useCanvasHand(editor: ObjectEditor, style: CanvasCreationStyle, selectProfile?: PlaneSelectProfile): { document: CanvasDocument; snapshot: import("<repository>/packages/json-document-editing/src/session").EditingSnapshot<ObjectSelection>; ... 20 more ...; surfaceProps: { ...; }; }
 ```
diff --git a/docs/api-reference/editing.md b/docs/api-reference/editing.md
index 418b5214..dbaaa08b 100644
--- a/docs/api-reference/editing.md
+++ b/docs/api-reference/editing.md
@@ -1189,11 +1189,13 @@ nextDatabasePropertySort(sort: DatabaseSort | null, propertyId: string): Databas
 ## `ObjectClipboard`
 
 ```ts
-interface ObjectClipboard extends Record<string, JSONValue> {
+type ObjectClipboard = Record<string, JSONValue> & {
   readonly type: "application/vnd.interactive-os.objects+json";
   readonly objects: ReadonlyArray<DocumentObject>;
   readonly text: string;
-}
+  /** Optional for legacy payloads; remapped to the corresponding new ID on paste. */
+  readonly primaryKey?: string | null;
+};
 ```
 ## `objectClipboardFormat`
 
@@ -1226,6 +1228,8 @@ interface ObjectEditor {
 ```ts
 type ObjectIntent =
   | { readonly type: "object.create"; readonly object: ObjectDraft }
+  | { readonly type: "object.duplicate"; readonly objectIds: ReadonlyArray<string>; readonly placement?: ObjectPastePlacement }
+  | { readonly type: "object.remove"; readonly objectIds: ReadonlyArray<string> }
   | { readonly type: "object.text"; readonly objectId: string; readonly text: string }
   | { readonly type: "document.replace"; readonly document: ObjectDocument }
   | {
diff --git a/docs/public/adapter-clipboard.md b/docs/public/adapter-clipboard.md
index 7b617d8b..6e919b4c 100644
--- a/docs/public/adapter-clipboard.md
+++ b/docs/public/adapter-clipboard.md
@@ -68,6 +68,9 @@ mutation, announcement나 실패 시 rollback을 소유하지 않습니다.
 
 DOM listener를 직접 설치하거나 개별 operation을 호출해야 할 때 사용하는
 저수준 API입니다.
+cut callback이 있으면 write 전에 native event를 취소합니다. 쓰기 실패에도 브라우저의
+기본 삭제로 넘어가지 않으며, 전부 쓴 payload의 캡처 대상만 callback으로 제거합니다.
+상세 실패·native editable 계약은 소유 패키지의 [Web Clipboard API](/docs/api/web)에 있습니다.
 
 ```ts
 function createWebClipboardBinding<Payload, EditingResult>(
diff --git a/docs/public/affordance-copy-drag.md b/docs/public/affordance-copy-drag.md
index 2b7accb6..886b8813 100644
--- a/docs/public/affordance-copy-drag.md
+++ b/docs/public/affordance-copy-drag.md
@@ -1,67 +1,36 @@
 # Duplicate
 
-Duplicate는 수정 키를 누른 채 드래그하면 원본을 복제하는 손입니다.
-`copy` / `alias` 커서가 이 손을 가리킵니다.
+Duplicate는 원본을 남기고 새 ID를 가진 사본 집합을 만드는 손입니다.
+평면 선택에서는 [`createPlaneSelectProfile`](/docs/api/affordance)이 기존
+`dragAffordance`·`dragOperation`을 조합하여 `operation: "copy"`를 반환합니다.
+ID·문서·Selection·History는 Object Editing이 소유합니다.
 
 ```ts
-import {
-  applyAffordance,
-  commitAffordance,
-  dragAffordance,
-  dragOperation,
-  dropAffordance,
-} from "@interactive-os/json-document-affordance";
+import { createPlaneSelectProfile } from "@interactive-os/json-document-affordance";
 
-function onPointerMove(event: PointerEvent) {
-  applyAffordance(dragOperation(event), {
-    cursor: (cursor) => {
-      event.currentTarget.style.cursor = cursor;
-    },
-  });
-}
-
-function onPointerUp(event: PointerEvent) {
-  const committed = commitAffordance(
-    dragAffordance(origin, { x: event.clientX, y: event.clientY }),
-  );
-  if (!committed) return;
-  applyAffordance(committed, {
-    commit: (translate) => {
-      if (translate.type !== "translate") return;
-      let copied = false;
-      applyAffordance(dragOperation(event), {
-        hand: (operation) => {
-          if (operation.type !== "copy") return;
-          copied = true;
-          hostDuplicate(objectIds, translate);
-        },
-      });
-      if (copied) return;
-      const drop = commitAffordance(dropAffordance({ canDrop: true }));
-      if (!drop) return;
-      applyAffordance(drop, {
-        commit: (hand) => {
-          if (hand.type !== "move-drop") return;
-          editor.dispatch({
-            type: "object.translate",
-            objectIds,
-            dx: translate.dx,
-            dy: translate.dy,
-          });
-        },
-      });
-    },
-  });
+const profile = createPlaneSelectProfile();
+profile.begin({ items: document.objects, selection: editor.snapshot.selection }, {
+  point: origin, hitKey: objectId, altKey: true,
+});
+const preview = profile.preview(point, modifiers); // 원본과 변환된 사본 렌더링; 문서/ID 불변
+const result = profile.commit(point, modifiers);
+if (result) {
+  editor.dispatch({ type: "selection.set", objectIds: result.selection.keys,
+    ...(result.selection.primaryKey === null ? {} : { primaryKey: result.selection.primaryKey }) });
+  const delta = result.translation;
+  if (delta) editor.dispatch(delta.operation === "copy"
+    ? { type: "object.duplicate", objectIds: delta.keys, placement: { type: "offset", dx: delta.dx, dy: delta.dy } }
+    : { type: "object.translate", objectIds: delta.keys, dx: delta.dx, dy: delta.dy });
 }
 ```
 
-복제 생성은 장르 Intent(호스트 또는 editor)이고, 옮기기는 json-document로
-갑니다. 값의 클립보드 복사/붙이기는 Hands입니다.
+Alt/Option+drag는 copy, release 전에 Alt를 놓으면 move입니다. Shift는 큰 delta 축을
+고정합니다. 원본은 문서 순서 그대로 남고 사본 preview는 위에 그립니다. 취소·Alt-click·
+최종 zero delta는 복제하지 않습니다. 사본 생성과 위치 변경은 하나의 Intent/Undo이며
+사본 집합·대응 primary를 선택합니다. Host에 별도 복제 구현을 두지 않습니다.
 
-닫는 손:
-- Alt/Option + 드래그 → copy
-- 커서 `copy` 또는 `alias`
-- 원본은 자리에 남고, 복제본이 포인터를 따라감
-- 드롭 후 복제본 집합이 선택된 채로 남음
+Mod+D와 공통 아이콘 툴바의 복제는 같은 `object.duplicate`를 사용합니다. 기본 offset은
+x/y 각각 24단위이고 반복 복제는 방금 생성한 선택을 대상으로 합니다. Clipboard는 건드리지
+않습니다. 값의 복사·잘라내기·붙여넣기는 별도로 Web Clipboard와 Object Editing이 연결합니다.
 
-근거: [Apple HIG pointing devices](https://developer.apple.com/design/human-interface-guidelines/pointing-devices), [CSS UI cursor `copy` / `alias`](https://www.w3.org/TR/css-ui-4/#cursor), Figma Option-drag, Illustrator Option, tldraw Alt
+실제 [Canvas Usage와 Source](/demo/canvas)에서 이 정본 경로를 확인할 수 있습니다.
diff --git a/docs/public/affordance-nudge.md b/docs/public/affordance-nudge.md
index e2fee957..7975d95a 100644
--- a/docs/public/affordance-nudge.md
+++ b/docs/public/affordance-nudge.md
@@ -4,6 +4,11 @@ Nudge는 고른 대상을 키보드로 조금 옮기는 손입니다. 화살표
 Shift+화살표는 큰 단위입니다. 항목 이웃으로 초점을 옮기는
 [Select](affordance-select.md)와 다릅니다.
 
+평면 편집기는 [`createPlaneSelectProfile`](/docs/api/affordance)의 `keyDown`이
+이 Affordance를 조합한 집합 `translate` 결과를 소비합니다. [Canvas Usage](/demo/canvas)는
+native editable/IME 및 Ctrl/Meta/Alt 조합을 제외하고 Object Editing에 연결합니다.
+이 최소 프로파일은 선택이 없을 때 nudge를 처리하지 않으며 pan으로 전환하지 않습니다.
+
 ```ts
 import { applyAffordance, nudgeAffordance } from "@interactive-os/json-document-affordance";
 
@@ -24,7 +29,8 @@ function onKeyDown(event: KeyboardEvent) {
 
 손은 1과 10을 닫습니다. 이동은 json-document로 갑니다.
 
-닫는 손:
+단일 Affordance의 조합 규칙:
+
 - Arrow: 1 단위
 - Shift+Arrow: 10 단위
 - 키 반복은 호스트 플랫폼 기본
diff --git a/docs/public/affordance.md b/docs/public/affordance.md
index b69962c9..8c173c54 100644
--- a/docs/public/affordance.md
+++ b/docs/public/affordance.md
@@ -96,7 +96,8 @@ Editing은 선택과 작업을 기억합니다. Adapter는 키 chord를 command
 
 최소 평면 문법은 [`createPlaneSelectProfile`](/docs/api/affordance)로 조합되어
 [Canvas Usage](/demo/canvas)에서 실행됩니다. 아래 표에는 단일 Affordance로만 제공되는
-더 넓은 기능도 포함됩니다. 그룹·중첩 선택·축 구속·복제·snap·zoom/pan은 이 최소 프로파일의
+더 넓은 기능도 포함됩니다. 축 고정·Alt 복제·Mod+D·nudge는 프로파일에 연결되어 있습니다.
+그룹·중첩 선택·snap·zoom/pan은 이 최소 프로파일의
 지원 범위가 아닙니다.
 
 근거 축: [Figma 레이어 선택](https://help.figma.com/hc/en-us/articles/360040449873-Select-layers-and-objects),
diff --git a/docs/public/object.md b/docs/public/object.md
index 35d21600..cab60211 100644
--- a/docs/public/object.md
+++ b/docs/public/object.md
@@ -22,7 +22,7 @@ ID 정책을 Host가 주입하는 자리입니다.
 
 `dispatch`가 받는 Object domain command입니다. 공개 variant는
 `selection.set`, `selection.remove`, `selection.fill`, `object.create`, `object.text`,
-`object.translate`, `object.resize`, `document.replace`, `clipboard.paste`입니다. DOM event, pointer 좌표, clipboard
+`object.translate`, `object.resize`, `object.duplicate`, `object.remove`, `document.replace`, `clipboard.paste`입니다. DOM event, pointer 좌표, clipboard
 event를 Intent에 넣지 않습니다.
 
 ### `ObjectSelectionMode`
@@ -42,6 +42,10 @@ event를 Intent에 넣지 않습니다.
 `clipboard.paste.placement`의 `{ type: "offset", dx, dy }`로 전달합니다. Editor가
 unique ID clone 뒤 placement를 정확히 한 번 적용하므로 clipboard payload에는
 배치 결과를 미리 저장하지 않습니다. placement 생략은 zero offset입니다.
+복제·paste의 primary remap, 새 ID와 원자적 History 계약은 소유 패키지의
+[Object Editing API](/docs/api/editing)에 있습니다. native cut은 성공적으로 쓴 payload의
+ID를 `object.remove`에 전달합니다. Object Demo의 복제 버튼은 OS Clipboard와 별개이며
+copy/cut/paste는 native 이벤트만 사용합니다.
 
 ## 상태의 주인
 
@@ -70,5 +74,5 @@ Object Hands는 서로 다른 수명의 상태를 한 덩어리로 만들지 않
 ```
 
 [한 장짜리 Canvas의 Usage와 Source](/docs/api/canvas)는 별도 Canvas editor 없이
-이 Object Editing을 사용합니다. 기존 Object의 다중 선택·Clipboard API는 유지하지만
-Canvas UI는 단일 선택만 제공합니다.
+이 Object Editing을 사용합니다. Canvas UI는 같은 다중 선택·Clipboard API와
+Affordance의 평면 Select 프로파일을 연결합니다.
diff --git a/packages/json-document-affordance/docs/plane-select.md b/packages/json-document-affordance/docs/plane-select.md
index d4a1417d..0db520f5 100644
--- a/packages/json-document-affordance/docs/plane-select.md
+++ b/packages/json-document-affordance/docs/plane-select.md
@@ -3,30 +3,33 @@
 `createPlaneSelectProfile`은 다중 선택까지 닫힌 최소 평면 선택 문법입니다.
 Canvas 모델, React, DOM, 문서 저장소 없이 ID·bounds·현재 선택과 정규화한 입력을
 받습니다. Selection의 `createKeySelectionFamily`로 집합과 primary를 전이하고,
-기존 hit·marquee·drag Affordance와 `createGestureSession`을 조합합니다.
+기존 hit·marquee·drag·copy·nudge Affordance와 `createGestureSession`을 조합합니다.
 
 ```text
 Web: hit ID, 같은 좌표계의 point, keyboard stroke, pointer capture
   └─ Affordance: createPlaneSelectProfile
       ├─ Selection: key 집합·primaryKey 전이/reconcile
       └─ preview / commit 결과
-          ├─ Hand: 선택 윤곽·marquee·이동 preview 렌더링
-          └─ Editing: 선택 반영, 집합 이동·삭제, primary 편집, History
+          ├─ Hand: 선택 윤곽·marquee·이동/복제 preview 렌더링
+          └─ Editing: 선택 반영, 집합 이동·복제·삭제, primary 편집, History
 ```
 
 ### API
 
-- `begin(context, { point, hitKey, shiftKey? })`: `items: { id, x, y, width, height }[]`와
+- `begin(context, { point, hitKey, shiftKey?, altKey? })`: `items: { id, x, y, width, height }[]`와
   `selection: { kind: "explicit", keys, primaryKey }`를 캡처합니다. `hitKey: null`은 빈 곳입니다.
   items의 순서가 선택 순서·primary fallback 순서이며, 사라진 key는 Selection이 제거합니다.
-- `preview(point)` / `getPreview()`: `{ selection, marquee, translation } | null`.
-  `translation`은 `{ keys, dx, dy }` 하나입니다. 문서와 committed selection은 바꾸지 않습니다.
-- `commit(point)`: 최종 point로 `{ selection, translation } | null`을 한 번 반환하고
+- `preview(point, modifiers?)` / `getPreview()`: `{ selection, marquee, translation } | null`.
+  `translation`은 `{ operation: "move" | "copy", keys, dx, dy }` 하나입니다. 문서와 committed selection은 바꾸지 않습니다.
+- `updateModifiers({ shiftKey?, altKey? })`: 포인터가 정지해 있어도 modifier 변경을 다시 투영합니다.
+  `preview`/`commit`에서 modifiers를 생략하면 마지막 상태를 유지하고, 전달하면 현재 상태로 교체합니다.
+- `commit(point, modifiers?)`: 최종 point로 `{ selection, translation } | null`을 한 번 반환하고
   gesture를 비웁니다. Hand가 Selection을 반영한 뒤 translation 전체를 한 Intent로 실행합니다.
 - `cancel(reason?)`: preview를 버립니다. 이후 release는 결과를 만들지 않습니다.
 - `select(context, key, shiftKey?)`: Space 같은 discrete activation의 선택 결과.
   **focus만으로 호출하지 않습니다.** Focus와 selection은 독립입니다.
-- `keyDown(stroke, context, grabbing?)`: selection / delete(keys) / edit(key) / cancel 또는
+- `keyDown(stroke, context, grabbing?)`: selection / delete(keys) / duplicate(keys) /
+  translate(keys, dx, dy) / edit(key) / cancel 또는
   null. `grabbing`은 resize 등 다른 gesture의 활성 상태입니다. 처리한 command는
   진행 중 Select preview도 취소합니다. 플랫폼 binding은 native editable/IME를 먼저 제외합니다.
 
@@ -42,11 +45,14 @@ Web: hit ID, 같은 좌표계의 point, keyboard stroke, pointer capture
 | 선택된 객체 press → drag | press에서는 집합 유지, drag는 집합 전체에 같은 delta |
 | 선택되지 않은 객체 press → drag | 그 객체 하나로 replace 후 이동 |
 | Shift+click | 포함하면 제거, 아니면 추가; 새 대상이 primary |
-| Shift+객체 drag | press의 toggle 결과로 이동. 누른 대상이 제거되면 이동 없음 |
+| Shift+객체 drag | toggle이 아닌 집합 이동; 큰 delta 축으로 고정 |
+| Alt/Option+객체 drag | 같은 선택 집합의 복제 요청; Shift와 조합 가능 |
 | 빈 곳 click | Shift 여부와 관계없이 clear |
 | 빈 곳 drag / Shift+drag | marquee replace / 기존 선택에 add |
 | Mod+A 반복 | 전체 선택 유지, 유효한 기존 primary 유지 |
 | Delete / Backspace | 선택 집합 삭제 요청 |
+| Mod+D | 선택 집합 복제 요청; ID·배치는 Editing 소유 |
+| 방향키 / Shift+방향키 | 선택 집합 1 / 10단위 이동 요청 |
 | Enter / F2 | primary 하나의 편집 요청 |
 | Escape | gesture만 cancel, idle에서는 선택 clear |
 
@@ -56,8 +62,11 @@ click/drag 임계값은 같은 좌표계의 3단위(`dragThreshold`), marquee는
 primary가 아닌 객체도 선택 윤곽을 그리지만 resize handles와 텍스트 입력은 primary에만 붙입니다.
 
 Selection 변경은 문서 JSON과 History를 건드리지 않습니다. 문서 commit/Undo는 Editing이
-소유합니다. 이 프로파일에는 그룹·다중 resize·중첩 선택·Mod drill-down·축 구속·복제·
-snap·zoom/pan·레이어 문법이 없습니다. 기존 단일 Affordance의 더 넓은 기능과 구분합니다.
+소유합니다. Alt-click과 최종 0 delta는 복제를 만들지 않습니다. 복제 preview에서는 원본을
+유지하고 변환된 사본을 위에 렌더링하지만, commit 전에 ID를 할당하지 않습니다.
+Mod+C/X/V는 처리하지 않습니다. Web의 native clipboard event가 직렬화와 이벤트 소유권을
+맡으며 text 입력·IME는 binding에서 먼저 제외합니다.
+이 프로파일에는 그룹·다중 resize·중첩 선택·Mod drill-down·snap·zoom/pan·레이어 문법이 없습니다.
 
 ### Usage와 Source
 
@@ -83,7 +92,7 @@ const context = {
 };
 select.begin(context, { hitKey: "node", point: { x: 20, y: 30 } });
 const preview = select.preview({ x: 40, y: 50 }); // renderer에만 전달
-const result = select.commit({ x: 40, y: 50 }); // keys=["node"], dx=20, dy=20
+const result = select.commit({ x: 40, y: 50 }); // operation="move", keys=["node"], dx=20, dy=20
 ```
 
 `tests/plane-select.test.ts`는 Object·Canvas·React를 import하지 않는 diagram 소비자로
diff --git a/packages/json-document-affordance/package.json b/packages/json-document-affordance/package.json
index ac808ba1..1be117c1 100644
--- a/packages/json-document-affordance/package.json
+++ b/packages/json-document-affordance/package.json
@@ -17,7 +17,7 @@
     "provenance": true,
     "tag": "next"
   },
-  "files": ["dist", "!dist/.tsbuildinfo", "README.md", "LICENSE"],
+  "files": ["dist", "!dist/.tsbuildinfo", "README.md", "docs", "LICENSE"],
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
diff --git a/packages/json-document-affordance/src/index.ts b/packages/json-document-affordance/src/index.ts
index ef6c3c76..52b0fcd9 100644
--- a/packages/json-document-affordance/src/index.ts
+++ b/packages/json-document-affordance/src/index.ts
@@ -20,7 +20,7 @@ export { createPlaneSelectProfile } from "./plane-select.js";
 export type {
   PlaneSelectCommit, PlaneSelectContext, PlaneSelectInput, PlaneSelectKeyResult,
   PlaneSelectPreview, PlaneSelectProfile, PlaneSelectProfileOptions, PlaneSelectSelection,
-  PlaneSelectTranslation,
+  PlaneSelectTranslation, PlaneSelectModifiers,
 } from "./plane-select.js";
 export {
   createInteractionHandleSession,
diff --git a/packages/json-document-affordance/src/plane-select.ts b/packages/json-document-affordance/src/plane-select.ts
index 0d92516f..1fd45ed4 100644
--- a/packages/json-document-affordance/src/plane-select.ts
+++ b/packages/json-document-affordance/src/plane-select.ts
@@ -1,6 +1,6 @@
 import { createKeySelectionFamily, type KeySelection, type KeySelectionCommand } from "@interactive-os/json-document-selection";
 import { createWebKeyboardAdapter, type WebKeyboardStroke } from "@interactive-os/json-document-web";
-import { dragAffordance, marqueeAffordance, marqueeHitsAffordance, type Point, type Rect } from "./drag.js";
+import { dragAffordance, dragOperation, marqueeAffordance, marqueeHitsAffordance, nudgeAffordance, type Point, type Rect } from "./drag.js";
 import { createGestureSession, type GestureCancelReason } from "./gesture-session.js";
 import { escapeAffordance, planeHitAffordance, selectAllAffordance } from "./select.js";
 
@@ -12,13 +12,18 @@ export interface PlaneSelectContext {
   readonly selection: PlaneSelectSelection;
 }
 
-export interface PlaneSelectInput {
+export interface PlaneSelectModifiers {
+  readonly shiftKey?: boolean;
+  readonly altKey?: boolean;
+}
+
+export interface PlaneSelectInput extends PlaneSelectModifiers {
   readonly point: Point;
   readonly hitKey: string | null;
-  readonly shiftKey?: boolean;
 }
 
 export interface PlaneSelectTranslation {
+  readonly operation: "move" | "copy";
   readonly keys: readonly string[];
   readonly dx: number;
   readonly dy: number;
@@ -38,6 +43,8 @@ export interface PlaneSelectCommit {
 export type PlaneSelectKeyResult =
   | { readonly type: "selection"; readonly selection: PlaneSelectSelection }
   | { readonly type: "delete"; readonly keys: readonly string[] }
+  | { readonly type: "duplicate"; readonly keys: readonly string[] }
+  | { readonly type: "translate"; readonly keys: readonly string[]; readonly dx: number; readonly dy: number }
   | { readonly type: "edit"; readonly key: string }
   | { readonly type: "cancel" };
 
@@ -49,8 +56,10 @@ export interface PlaneSelectProfileOptions {
 
 export interface PlaneSelectProfile {
   begin(context: PlaneSelectContext, input: PlaneSelectInput): PlaneSelectPreview;
-  preview(point: Point): PlaneSelectPreview | null;
-  commit(point: Point): PlaneSelectCommit | null;
+  preview(point: Point, modifiers?: PlaneSelectModifiers): PlaneSelectPreview | null;
+  commit(point: Point, modifiers?: PlaneSelectModifiers): PlaneSelectCommit | null;
+  /** Reproject a stationary drag when a modifier changes; omitted preview modifiers retain this state. */
+  updateModifiers(modifiers: PlaneSelectModifiers): PlaneSelectPreview | null;
   cancel(reason?: GestureCancelReason): void;
   getPreview(): PlaneSelectPreview | null;
   /** Discrete activation (e.g. Space), not focus. Shift toggles, plain activation replaces. */
@@ -66,11 +75,13 @@ type Gesture = {
   readonly selection: PlaneSelectSelection;
   readonly point: Point;
   readonly moved: boolean;
+  readonly modifiers: PlaneSelectModifiers;
 };
 
 const family = createKeySelectionFamily();
 const keyboard = createWebKeyboardAdapter();
 const editKeyboard = createWebKeyboardAdapter<"edit">({ defaults: false, keymap: { Enter: "edit", F2: "edit" } });
+const duplicateKeyboard = createWebKeyboardAdapter<"duplicate">({ defaults: false, keymap: { "Mod-d": "duplicate" } });
 
 function selectionContext(context: PlaneSelectContext) {
   return { keys: context.items.map((item) => item.id), universe: "plane", universeMismatch: "clear" as const };
@@ -93,7 +104,8 @@ export function createPlaneSelectProfile(options: PlaneSelectProfileOptions = {}
   }
 
   function project(gesture: Gesture): PlaneSelectPreview {
-    const { context, input, point, selection, moved } = gesture;
+    const { context, input, point, moved, modifiers } = gesture;
+    let selection = gesture.selection;
     if (input.hitKey === null && moved) {
       const band = marqueeAffordance(input.point, point, input);
       if (band.hand?.type === "select" && band.hand.rect) {
@@ -105,17 +117,23 @@ export function createPlaneSelectProfile(options: PlaneSelectProfileOptions = {}
       }
       return { selection: transition(context, { type: input.shiftKey ? "add" : "replace", keys: [] }), marquee: null, translation: null };
     }
-    const delta = moved && input.hitKey !== null && selection.keys.includes(input.hitKey)
-      ? dragAffordance(input.point, point).hand : null;
+    if (moved && input.hitKey !== null) {
+      // Shift-click toggles; after the threshold Shift constrains the drag, never subtracts its source.
+      const hit = planeHitAffordance({ hitId: input.hitKey, selectedIds: context.selection.keys }).hand;
+      if (hit?.type === "select") selection = transition(context, { type: "replace", keys: hit.objectIds ?? [], primaryKey: input.hitKey });
+    }
+    const delta = moved && input.hitKey !== null ? dragAffordance(input.point, point, modifiers).hand : null;
+    const operation = dragOperation({ ...modifiers, shiftKey: modifiers.shiftKey ?? false, metaKey: false, ctrlKey: false }).hand?.type === "copy" ? "copy" : "move";
     return {
       selection, marquee: null,
       translation: delta?.type === "translate" && (delta.dx !== 0 || delta.dy !== 0)
-        ? { keys: selection.keys, dx: delta.dx, dy: delta.dy } : null,
+        ? { operation, keys: selection.keys, dx: delta.dx, dy: delta.dy } : null,
     };
   }
 
-  function preview(point: Point) {
+  function preview(point: Point, modifiers?: PlaneSelectModifiers) {
     const active = gestures.preview((gesture) => ({ ...gesture, point: { ...point },
+      modifiers: modifiers === undefined ? gesture.modifiers : { shiftKey: modifiers.shiftKey ?? false, altKey: modifiers.altKey ?? false },
       moved: gesture.moved || Math.hypot(point.x - gesture.input.point.x, point.y - gesture.input.point.y) > threshold,
     }));
     return active ? project(active) : null;
@@ -128,14 +146,14 @@ export function createPlaneSelectProfile(options: PlaneSelectProfileOptions = {}
       const hitKey = input.hitKey !== null && captured.items.some((item) => item.id === input.hitKey) ? input.hitKey : null;
       const press = hitKey === null ? null : planeHitAffordance({ hitId: hitKey, selectedIds: selection.keys, shiftKey: input.shiftKey ?? false }).hand;
       const active = gestures.begin({ type: "plane-select", context: captured, input: { ...input, point: { ...input.point }, hitKey },
-        point: { ...input.point }, moved: false,
+        point: { ...input.point }, moved: false, modifiers: { shiftKey: input.shiftKey ?? false, altKey: input.altKey ?? false },
         selection: press?.type === "select" ? transition(captured, { type: "replace", keys: press.objectIds ?? [], primaryKey: hitKey! }) : selection,
       });
       return project(active);
     },
     preview,
-    commit(point) {
-      preview(point);
+    commit(point, modifiers) {
+      preview(point, modifiers);
       const active = gestures.commit();
       if (!active) return null;
       const result = project(active);
@@ -144,6 +162,10 @@ export function createPlaneSelectProfile(options: PlaneSelectProfileOptions = {}
         translation: result.translation,
       };
     },
+    updateModifiers(modifiers) {
+      const active = gestures.getActive();
+      return active ? preview(active.point, modifiers) : null;
+    },
     cancel(reason) { gestures.cancel(reason); },
     getPreview() { const active = gestures.getActive(); return active ? project(active) : null; },
     select,
@@ -157,8 +179,11 @@ export function createPlaneSelectProfile(options: PlaneSelectProfileOptions = {}
         result = { type: "selection", selection: transition(context, { type: "replace", keys: context.items.map((item) => item.id), ...(selection.primaryKey === null ? {} : { primaryKey: selection.primaryKey }) }) };
       } else {
         const command = keyboard.resolve(stroke);
+        const nudge = !stroke.metaKey && !stroke.ctrlKey && !stroke.altKey ? nudgeAffordance(stroke).hand : null;
         if (editKeyboard.resolve(stroke) === "edit" && selection.primaryKey !== null) result = { type: "edit", key: selection.primaryKey };
         else if (command?.type === "delete" && selection.keys.length) result = { type: "delete", keys: selection.keys };
+        else if (duplicateKeyboard.resolve(stroke) && selection.keys.length) result = { type: "duplicate", keys: selection.keys };
+        else if (nudge?.type === "nudge" && selection.keys.length) result = { type: "translate", keys: selection.keys, dx: nudge.dx, dy: nudge.dy };
       }
       if (result) gestures.cancel();
       return result;
diff --git a/packages/json-document-affordance/tests/plane-select.test.ts b/packages/json-document-affordance/tests/plane-select.test.ts
index 5df28c54..2e2272c5 100644
--- a/packages/json-document-affordance/tests/plane-select.test.ts
+++ b/packages/json-document-affordance/tests/plane-select.test.ts
@@ -13,8 +13,8 @@ test("press retains a selected set, release collapses a click, and drag produces
   expect(profile.begin(context(), { point, hitKey: "node:a" }).selection).toEqual(selected(["node:a", "node:b"], "node:a"));
   expect(profile.commit({ x: 12, y: 31 })).toEqual({ selection: selected(["node:a"]), translation: null });
   profile.begin(context(), { point, hitKey: "node:a" });
-  expect(profile.preview({ x: 40, y: 50 })?.translation).toEqual({ keys: ["node:a", "node:b"], dx: 30, dy: 20 });
-  expect(profile.commit({ x: 50, y: 60 })?.translation).toEqual({ keys: ["node:a", "node:b"], dx: 40, dy: 30 });
+  expect(profile.preview({ x: 40, y: 50 })?.translation).toEqual({ operation: "move", keys: ["node:a", "node:b"], dx: 30, dy: 20 });
+  expect(profile.commit({ x: 50, y: 60 })?.translation).toEqual({ operation: "move", keys: ["node:a", "node:b"], dx: 40, dy: 30 });
   expect(profile.commit(point)).toBeNull();
 });
 
@@ -25,7 +25,7 @@ test("an unselected hit replaces the drag source; Shift activation toggles witho
   expect(profile.select(context(["node:a"]), "node:c", true)).toEqual(selected(["node:a", "node:c"]));
   expect(profile.select(context(), "node:b", true)).toEqual(selected(["node:a"]));
   profile.begin(context(), { point, hitKey: "node:b", shiftKey: true });
-  expect(profile.commit({ x: 40, y: 40 })).toEqual({ selection: selected(["node:a"]), translation: null });
+  expect(profile.commit({ x: 40, y: 40 })).toEqual({ selection: selected(["node:a", "node:b"]), translation: { operation: "move", keys: ["node:a", "node:b"], dx: 30, dy: 0 } });
 });
 
 test.each([false, true])("marquee is transient and uses base selection for every preview (Shift=%s)", (shiftKey) => {
@@ -80,10 +80,49 @@ test("Delete targets the set, edit targets primary only, unrelated/modified keys
   expect(profile.keyDown(stroke("Delete"), context())).toEqual({ type: "delete", keys: ["node:a", "node:b"] });
   for (const key of ["Enter", "F2"]) expect(profile.keyDown(stroke(key), context())).toEqual({ type: "edit", key: "node:b" });
   for (const key of ["Delete", "Enter", "F2"]) expect(profile.keyDown(stroke(key), context([]))).toBeNull();
-  for (const key of ["ArrowLeft", "Home", "z"]) expect(profile.keyDown(stroke(key), context())).toBeNull();
+  for (const key of ["Home", "z"]) expect(profile.keyDown(stroke(key), context())).toBeNull();
   expect(profile.keyDown(stroke("Enter", true), context())).toBeNull();
 });
 
+test("Alt-copy and Shift-axis lock reproject the same source, including stationary modifier changes", () => {
+  const profile = createPlaneSelectProfile();
+  const base = context();
+  profile.begin(base, { point, hitKey: "node:a", altKey: true, shiftKey: true });
+  const modifiers = Object.create({ get shiftKey() { return true; }, get altKey() { return true; } });
+  expect(profile.preview({ x: 40, y: 50 }, modifiers)?.translation).toEqual({ operation: "copy", keys: ["node:a", "node:b"], dx: 30, dy: 0 });
+  expect(profile.updateModifiers({ altKey: false })?.translation).toEqual({ operation: "move", keys: ["node:a", "node:b"], dx: 30, dy: 20 });
+  expect(profile.updateModifiers({ altKey: true, shiftKey: true })?.translation?.operation).toBe("copy");
+  expect(profile.commit({ x: 40, y: 90 })?.translation).toEqual({ operation: "copy", keys: ["node:a", "node:b"], dx: 0, dy: 60 });
+  expect(base.selection).toEqual(selected(["node:a", "node:b"]));
+  expect(profile.updateModifiers({})).toBeNull();
+});
+
+test("Alt-click, zero-distance return and cancellation never request duplication", () => {
+  const profile = createPlaneSelectProfile();
+  profile.begin(context(), { point, hitKey: "node:a", altKey: true });
+  expect(profile.commit(point)?.translation).toBeNull();
+  profile.begin(context(), { point, hitKey: "node:a", altKey: true });
+  profile.preview({ x: 40, y: 50 });
+  expect(profile.commit(point)?.translation).toBeNull();
+  profile.begin(context(), { point, hitKey: "node:c", altKey: true });
+  expect(profile.preview({ x: 40, y: 50 })?.translation?.keys).toEqual(["node:c"]);
+  profile.cancel(); expect(profile.commit({ x: 40, y: 50 })).toBeNull();
+});
+
+test("nudge and duplicate target the set, and native clipboard chords remain available", () => {
+  const profile = createPlaneSelectProfile();
+  expect(profile.keyDown(stroke("ArrowRight"), context())).toEqual({ type: "translate", keys: ["node:a", "node:b"], dx: 1, dy: 0 });
+  expect(profile.keyDown({ ...stroke("ArrowUp"), shiftKey: true }, context())).toEqual({ type: "translate", keys: ["node:a", "node:b"], dx: 0, dy: -10 });
+  for (const modifiers of [{ metaKey: true }, { ctrlKey: true }]) {
+    expect(profile.keyDown({ ...stroke("d"), ...modifiers }, context())).toEqual({ type: "duplicate", keys: ["node:a", "node:b"] });
+    for (const key of ["c", "x", "v", "ArrowLeft"]) expect(profile.keyDown({ ...stroke(key), ...modifiers }, context())).toBeNull();
+  }
+  for (const key of ["d", "ArrowLeft"]) {
+    expect(profile.keyDown({ ...stroke(key), altKey: true }, context())).toBeNull();
+    expect(profile.keyDown(stroke(key, key === "d"), context([]))).toBeNull();
+  }
+});
+
 test("keys and primary reconcile through Selection; geometry and input are captured, and instances are independent", () => {
   const profile = createPlaneSelectProfile();
   const mutable = { items: items.map((item) => ({ ...item })), selection: selected(["missing", "node:a"], "missing") };
diff --git a/packages/json-document-canvas/README.md b/packages/json-document-canvas/README.md
index 920b9aa6..2fb686a7 100644
--- a/packages/json-document-canvas/README.md
+++ b/packages/json-document-canvas/README.md
@@ -3,6 +3,8 @@
 `@interactive-os/json-document-canvas`는 한 장의 Object Canvas 프로파일에서
 글자·사각형·타원·그리기를 완성하는 React Hand입니다. 별도 Canvas editor나
 selection/history 구현을 만들지 않고 기존 `createObjectEditor`를 사용합니다.
+재사용 가능한 Plane Select profile로 다중 선택·Alt 복제·Shift 축 고정·방향키 이동을,
+Object Editing과 Web Clipboard로 선택 copy/cut/paste·Mod+D·Undo/Redo를 연결합니다.
 
 ```tsx
 import { useState } from "react";
diff --git a/packages/json-document-canvas/docs/api.md b/packages/json-document-canvas/docs/api.md
index 5b858ffa..3356a58f 100644
--- a/packages/json-document-canvas/docs/api.md
+++ b/packages/json-document-canvas/docs/api.md
@@ -1,7 +1,7 @@
 ## Canvas Hand 계약 · RC
 
 `CanvasHand`는 `ObjectEditor`와 `CanvasCreationStyle`을 받아 글자·사각형·타원·자유
-그리기, 다중 선택, 집합 이동·삭제, primary resize, Undo/Redo, JSON 재열기를 연결합니다.
+그리기, 다중 선택, 집합 이동·복제·삭제, native Clipboard, primary resize, Undo/Redo, JSON 재열기를 연결합니다.
 `useCanvasHand`는 같은 입력 조합을 custom UI에서 사용할 수 있게 공개합니다.
 
 툴바의 모든 도구·명령은 Lucide 아이콘과 공통 `Toggle`/`Command`의 `label`을
@@ -13,7 +13,7 @@
 Host: 한 장 fixture, 크기·색상 정책, 레이아웃
   └─ Canvas Hand: 도구, 조작 preview, plain-text draft, UI 조합
       ├─ React Connector: Editing snapshot 구독
-      ├─ Web Adapter: SVG 좌표, pointer capture, keyboard 해석
+      ├─ Web Adapter: SVG 좌표, pointer capture, keyboard·Clipboard 해석
       ├─ Affordance: createPlaneSelectProfile, gesture, resize
       │   └─ Selection: key 집합·primaryKey 전이
       ├─ UI Primitives: handle, icon controls·tooltips
@@ -40,6 +40,12 @@ Host: 한 장 fixture, 크기·색상 정책, 레이아웃
 - 글자는 생성 직후 또는 더블클릭/F2/Enter로 편집합니다. 줄바꿈·IME·선택·native
   입력 Undo는 textarea에 남습니다. blur 또는 Mod+Enter가 전체 draft를 한 번 commit하고
   Escape는 draft만 버립니다. 객체의 label이 실제 문자열 값입니다.
+- Alt/Option+drag는 선택 집합을 복제합니다. 원본을 남기고 사본 위치를 preview하며
+  release에 새 ID를 할당합니다. Alt를 도중에 누르거나 놓으면 copy/move가 전환됩니다.
+  Shift+drag는 큰 delta 축을 고정하며 Shift+click toggle과 구분합니다.
+  Mod+D 또는 아이콘 툴바의 복제는 24단위 offset으로 복제하고 사본 집합·대응 primary를 선택합니다.
+- 방향키는 선택 집합을 1단위, Shift+방향키는 10단위 이동합니다. 수정 키 없는 입력만
+  처리하며 text/JSON 입력과 IME의 키보드 소유권은 보존합니다.
 - 이동·resize·생성 중에는 문서를 변경하지 않습니다. pointerup의 최종 좌표로 한 번
   commit합니다. Escape, pointercancel, capture loss, 외부 문서 변경, unmount는 preview를
   버립니다. 다른 pointer의 release는 조작을 완료하지 못합니다. marquee 선택 preview도
@@ -48,6 +54,21 @@ Host: 한 장 fixture, 크기·색상 정책, 레이아웃
   한 번의 Undo로 되돌리며 삭제 Undo는 객체와 선택을 함께 복원합니다. Mod+Z/Mod+Shift+Z는
   입력 필드 밖에서 문서 Undo/Redo를 실행합니다.
 
+### Native Clipboard
+
+선택 객체의 Mod+C/X/V 또는 브라우저 native copy/cut/paste 이벤트를 Web Clipboard
+binding에 연결합니다. 구조화 MIME과 label의 `text/plain`을 함께 쓰므로 다른 Canvas
+instance로 객체를 복사하거나 다른 앱에 문자열을 붙일 수 있습니다. 앱 내부 가상
+clipboard는 만들지 않습니다. 복제 버튼은 OS clipboard를 바꾸지 않는 별도 명령입니다.
+
+cut은 쓰기에 성공한 캡처 대상만 제거합니다. 쓰기 실패나 Editing 거절은 오류로 드러내고
+문서 삭제나 브라우저 fallback 삭제를 허용하지 않습니다. paste는 새 ID·대응 primary로
+선택하고 원래 좌표에서 x/y 각각 24만큼 offset합니다. 같은 payload를 반복 paste하면
+같은 offset 위치에 새 사본을 만듭니다. text/JSON textarea의 native clipboard는 가로채지 않습니다.
+
+Canvas 표면으로의 외부 plain text/HTML/image paste와 async clipboard 툴바는 아직 지원하지
+않습니다. 지원 MIME이 없거나 payload가 잘못되면 문서를 바꾸지 않고 실패를 표시합니다.
+
 ### JSON
 
 JSON 버튼은 현재 문서 문자열을 노출합니다. 이 문자열을 저장해 다시 JSON 입력에
@@ -59,7 +80,7 @@ JSON 버튼은 현재 문서 문자열을 노출합니다. 이 문자열을 저
 ### 범위와 Usage
 
 단일 슬라이드를 컨테이너에 맞춰 표시합니다. 확대/축소·페이지·팬·다중 resize·그룹·회전·
-snap·레이어·Clipboard UI·PPTX·collaboration은 이번 Hand의 지원 범위가 아닙니다.
+snap·레이어·PPTX·collaboration은 이번 Hand의 지원 범위가 아닙니다.
 `creationStyle`은 새 객체에만 적용하는 제품 기본값이며 저장 객체의 스타일을 덮어쓰지 않습니다.
 
 선택은 Affordance의 [평면 Select 프로파일](/docs/api/affordance)을 소비합니다.
diff --git a/packages/json-document-canvas/src/canvas-hand.tsx b/packages/json-document-canvas/src/canvas-hand.tsx
index cb5c8d65..71ecad71 100644
--- a/packages/json-document-canvas/src/canvas-hand.tsx
+++ b/packages/json-document-canvas/src/canvas-hand.tsx
@@ -1,5 +1,5 @@
 import { useState, type CSSProperties } from "react";
-import { Braces, Circle, MousePointer2, Pencil, RectangleHorizontal, Redo2, Trash2, Type, Undo2, type LucideIcon } from "lucide-react";
+import { Braces, Circle, CopyPlus, MousePointer2, Pencil, RectangleHorizontal, Redo2, Trash2, Type, Undo2, type LucideIcon } from "lucide-react";
 import type { ObjectEditor } from "@interactive-os/json-document-editing";
 import type { PlaneSelectProfile } from "@interactive-os/json-document-affordance";
 import { serializeCanvasDocument } from "@interactive-os/json-document-object-document";
@@ -27,12 +27,14 @@ export function CanvasHand(props: CanvasHandProps) {
   const [json, setJSON] = useState<string | null>(null);
   const selected = hand.objects.find((object) => object.id === hand.selection.primaryKey);
   const selectedKeys = new Set(hand.selection.keys);
+  const copyOriginals = new Map(hand.copyOriginals.map((object) => [object.id, object]));
   return (
     <ProductShell className={props.className} toolbarLabel="Canvas tools" toolbar={<ToolbarGroup style={{ flexWrap: "wrap" }}>
       <ToolbarGroup>{tools.map((tool) => <Toggle key={tool.id} label={tool.label} pressed={hand.tool === tool.id} onClick={() => hand.choose(tool.id)}><tool.icon aria-hidden="true" size={16} /></Toggle>)}</ToolbarGroup>
       <ToolbarGroup>
         <Command label="실행 취소" disabled={!hand.snapshot.canUndo} onClick={() => hand.history("undo")}><Undo2 aria-hidden="true" size={16} /></Command>
         <Command label="다시 실행" disabled={!hand.snapshot.canRedo} onClick={() => hand.history("redo")}><Redo2 aria-hidden="true" size={16} /></Command>
+        <Command label="복제" disabled={!selected} onClick={() => hand.duplicate()}><CopyPlus aria-hidden="true" size={16} /></Command>
         <Command label="삭제" disabled={!selected} onClick={hand.remove}><Trash2 aria-hidden="true" size={16} /></Command>
       </ToolbarGroup>
       <Command label="JSON" onClick={() => { hand.commitText(); hand.cancel(); setJSON(json === null ? serializeCanvasDocument(props.editor.snapshot.value as typeof hand.document) : null); }}><Braces aria-hidden="true" size={16} /></Command>
@@ -40,11 +42,13 @@ export function CanvasHand(props: CanvasHandProps) {
       <svg ref={hand.surface} {...hand.surfaceProps} tabIndex={0} role="group" aria-label={props.label ?? "Canvas slide"}
         data-canvas-slide="true" data-tool={hand.tool} viewBox={`0 0 ${hand.document.width} ${hand.document.height}`} preserveAspectRatio="none"
         style={{ display: "block", width: "100%", aspectRatio: `${hand.document.width} / ${hand.document.height}`, touchAction: "none", userSelect: "none", overflow: "hidden", ...props.slideStyle }}>
-        {hand.objects.map((object) => <g key={object.id}>
-          {hand.draft?.id !== object.id && <CanvasObjectView object={object} />}
+        {hand.objects.map((object) => <g key={object.id} data-canvas-copy-original={copyOriginals.has(object.id) ? object.id : undefined}>
+          {hand.draft?.id !== object.id && <CanvasObjectView object={copyOriginals.get(object.id) ?? object} />}
           <CanvasObjectTarget object={object} selected={selectedKeys.has(object.id)} enabled={hand.tool === "select" && hand.draft?.id !== object.id}
+            copying={hand.copyOriginals.length > 0 && selectedKeys.has(object.id)}
             onSelect={(shiftKey) => hand.select(object.id, shiftKey)} onEdit={() => hand.editText(object.id)} onHandle={(interaction, event) => hand.interaction(interaction, event, object, "drag")} />
         </g>)}
+        {copyOriginals.size > 0 && <g data-canvas-copy-preview="" pointerEvents="none">{hand.objects.filter((object) => selectedKeys.has(object.id)).map((object) => <CanvasObjectView key={object.id} object={object} />)}</g>}
         {hand.preview && <g pointerEvents="none" opacity={0.65}><CanvasObjectView object={{ ...hand.preview, id: "preview" }} /></g>}
         {hand.tool === "select" && hand.objects.filter((object) => selectedKeys.has(object.id)).map((object) =>
           <rect key={object.id} data-selection-outline={object.id} x={object.x} y={object.y} width={object.width} height={object.height} fill="none" stroke="rgb(var(--color-border-accent))" strokeWidth={object.id === selected?.id ? 2 : 1} pointerEvents="none" />)}
diff --git a/packages/json-document-canvas/src/canvas-object-view.tsx b/packages/json-document-canvas/src/canvas-object-view.tsx
index e27939f4..e67cfa38 100644
--- a/packages/json-document-canvas/src/canvas-object-view.tsx
+++ b/packages/json-document-canvas/src/canvas-object-view.tsx
@@ -21,6 +21,7 @@ export function CanvasObjectTarget(props: {
   readonly object: CanvasObject;
   readonly selected: boolean;
   readonly enabled: boolean;
+  readonly copying?: boolean;
   readonly onSelect: (shiftKey: boolean) => void;
   readonly onEdit: () => void;
   readonly onHandle: (interaction: InteractionHandleEvent, event: PointerEvent<SVGElement>) => void;
@@ -32,7 +33,7 @@ export function CanvasObjectTarget(props: {
       fill="transparent" role="button" aria-label={object.label || object.kind} aria-pressed={props.selected}
       {...contentInteractionAttributes({ role: "content", selected: props.selected, dragging: binding.active })}
       tabIndex={props.enabled ? 0 : -1} data-canvas-object={object.id} data-kind={object.kind}
-      pointerEvents={props.enabled ? "all" : "none"} style={{ cursor: binding.cursor, transform: "none" }}
+      pointerEvents={props.enabled ? "all" : "none"} style={{ cursor: props.copying ? "copy" : binding.cursor, transform: "none" }}
       onDoubleClick={props.onEdit}
       onKeyDown={(event) => {
         if (event.nativeEvent.isComposing || event.metaKey || event.ctrlKey || event.altKey) return;
diff --git a/packages/json-document-canvas/src/use-canvas-hand.ts b/packages/json-document-canvas/src/use-canvas-hand.ts
index bea7a42a..7ab3f1e4 100644
--- a/packages/json-document-canvas/src/use-canvas-hand.ts
+++ b/packages/json-document-canvas/src/use-canvas-hand.ts
@@ -1,9 +1,9 @@
-import { useEffect, useMemo, useReducer, useRef, useState, type KeyboardEvent, type PointerEvent } from "react";
+import { useEffect, useMemo, useReducer, useRef, useState, type ClipboardEvent, type KeyboardEvent, type PointerEvent } from "react";
 import { createGestureSession, createPlaneSelectProfile, resizeAffordance, type InteractionHandleEvent, type PlaneSelectProfile, type PlaneSelectSelection, type ResizeEdge } from "@interactive-os/json-document-affordance";
 import { assertCanvasDocument, createCanvasObject, createCanvasPath, parseCanvasDocument, transformObject, type CanvasDocument, type CanvasObject, type CanvasObjectKind, type ObjectPoint } from "@interactive-os/json-document-object-document";
 import type { EditingResult, ObjectEditor, ObjectIntent, ObjectSelection } from "@interactive-os/json-document-editing";
 import { useEditingSnapshot } from "@interactive-os/json-document-react";
-import { createWebKeyboardAdapter, createWebPointerSession, isWebEditableTarget, projectWebClientPointToSVG, webSVGViewportFromElement } from "@interactive-os/json-document-web";
+import { createWebClipboardBinding, createWebKeyboardAdapter, createWebPointerSession, isWebEditableTarget, objectClipboardCodec, projectWebClientPointToSVG, webSVGViewportFromElement } from "@interactive-os/json-document-web";
 
 export type CanvasTool = "select" | CanvasObjectKind;
 export interface CanvasCreationStyle {
@@ -34,6 +34,12 @@ export function useCanvasHand(editor: ObjectEditor, style: CanvasCreationStyle,
   const draft = useRef<TextDraft | null>(null);
   const selecting = useRef<{ readonly base: CanvasDocument; readonly selection: ObjectSelection; readonly pointerId: number; readonly key: string | null } | null>(null);
   const profile = useMemo(() => selectProfile ?? createPlaneSelectProfile(), [editor, selectProfile]);
+  const clipboard = useMemo(() => createWebClipboardBinding({
+    codec: objectClipboardCodec,
+    read: () => editor.copy(),
+    cut: (payload) => editor.dispatch({ type: "object.remove", objectIds: payload.objects.map((object) => object.id) }),
+    paste: (payload) => editor.dispatch({ type: "clipboard.paste", clipboard: payload, placement: { type: "offset", dx: 24, dy: 24 } }),
+  }), [editor]);
   const gestures = useMemo(() => createGestureSession<Gesture>({ onBegin: redraw, onPreview: redraw, onCommit: redraw, onCancel: redraw }), [editor]);
   const pointer = useMemo(() => createWebPointerSession<true>({ onCancel: (_, reason) => {
     gestures.cancel(reason === "lost-capture" ? "lost-capture" : "pointer-cancel");
@@ -84,19 +90,21 @@ export function useCanvasHand(editor: ObjectEditor, style: CanvasCreationStyle,
   }
   function select(id: string | null, shiftKey = false) { cancel(); applySelection(profile.select(selectContext(), id, shiftKey)); }
 
-  function beginSelect(point: ObjectPoint, key: string | null, event: { readonly pointerId: number; readonly shiftKey: boolean }) {
+  function beginSelect(point: ObjectPoint, key: string | null, event: { readonly pointerId: number; readonly shiftKey: boolean; readonly altKey: boolean }) {
     selecting.current = { base: current(), selection: editor.snapshot.selection, pointerId: event.pointerId, key };
-    profile.begin(selectContext(), { point, hitKey: key, shiftKey: event.shiftKey }); redraw();
+    profile.begin(selectContext(), { point, hitKey: key, shiftKey: event.shiftKey, altKey: event.altKey }); redraw();
   }
 
-  function commitSelect(point: ObjectPoint) {
+  function commitSelect(point: ObjectPoint, modifiers: { readonly shiftKey: boolean; readonly altKey: boolean }) {
     const base = selecting.current?.base;
     selecting.current = null;
-    const result = profile.commit(point); redraw();
+    const result = profile.commit(point, modifiers); redraw();
     if (!result || base !== current()) return;
     if (!applySelection(result.selection).ok || !result.translation) return;
-    const { keys, dx, dy } = result.translation;
-    dispatch({ type: "object.translate", objectIds: keys, dx, dy });
+    const { keys, dx, dy, operation } = result.translation;
+    dispatch(operation === "copy"
+      ? { type: "object.duplicate", objectIds: keys, placement: { type: "offset", dx, dy } }
+      : { type: "object.translate", objectIds: keys, dx, dy });
   }
 
   function editText(id: string) {
@@ -179,7 +187,7 @@ export function useCanvasHand(editor: ObjectEditor, style: CanvasCreationStyle,
   function pointerMove(event: PointerEvent<SVGSVGElement>) {
     if (pointer.getSnapshot()?.pointerId !== event.pointerId) return;
     const point = eventPoint(event), active = gestures.getActive();
-    if (point && selecting.current) { profile.preview(point); redraw(); return; }
+    if (point && selecting.current) { profile.preview(point, event); redraw(); return; }
     if (!point || !active) return;
     if (active.type === "draw") {
       const last = active.points.at(-1)!;
@@ -203,7 +211,7 @@ export function useCanvasHand(editor: ObjectEditor, style: CanvasCreationStyle,
     } else {
       if (type === "drag") {
         if (selecting.current?.key !== object.id || selecting.current.pointerId !== event.pointerId) return;
-        if (interaction.phase === "commit") commitSelect(point); else { profile.preview(point); redraw(); }
+        if (interaction.phase === "commit") commitSelect(point, event); else { profile.preview(point, event); redraw(); }
         return;
       }
       const active = gestures.getActive();
@@ -214,16 +222,32 @@ export function useCanvasHand(editor: ObjectEditor, style: CanvasCreationStyle,
   }
 
   function remove() { commitText(); cancel(); dispatch({ type: "selection.remove" }); surface.current?.focus(); }
+  function duplicate(keys = editor.snapshot.selection.keys) { commitText(); cancel(); dispatch({ type: "object.duplicate", objectIds: keys }); surface.current?.focus(); }
   function history(direction: "undo" | "redo") { commitText(); cancel(); report(editor[direction]()); surface.current?.focus(); }
 
+  function handleClipboard(operation: "copy" | "cut" | "paste", event: ClipboardEvent) {
+    if (isWebEditableTarget(event.target)) return;
+    cancel();
+    const result = clipboard[operation](event);
+    setError(result.ok ? null : result.reason ?? result.code);
+    if (result.ok) setTool("select");
+  }
+
+  function updateModifiers(event: KeyboardEvent) {
+    if (!event.nativeEvent.isComposing && !isWebEditableTarget(event.target) && profile.updateModifiers(event)) redraw();
+  }
+
   function keyDown(event: KeyboardEvent) {
     if (event.nativeEvent.isComposing || isWebEditableTarget(event.target)) return;
+    updateModifiers(event);
     const selectedAction = profile.keyDown(event, selectContext(), gestures.getActive() !== null || draft.current !== null);
     if (selectedAction) {
       event.preventDefault();
       cancel();
       if (selectedAction.type === "selection") applySelection(selectedAction.selection);
       else if (selectedAction.type === "delete") remove();
+      else if (selectedAction.type === "duplicate") duplicate(selectedAction.keys);
+      else if (selectedAction.type === "translate") dispatch({ type: "object.translate", objectIds: selectedAction.keys, dx: selectedAction.dx, dy: selectedAction.dy });
       else if (selectedAction.type === "edit") editText(selectedAction.key);
       setTool("select"); return;
     }
@@ -241,11 +265,12 @@ export function useCanvasHand(editor: ObjectEditor, style: CanvasCreationStyle,
     if (translation && translating.has(object.id)) return transformObject(object, translation);
     return gesture?.type === "resize" && gesture.object.id === object.id ? transformObject(object, transform(gesture)) : object;
   });
+  const copyOriginals = translation?.operation === "copy" ? document.objects.filter((object) => translating.has(object.id)) : [];
   const preview = gesture && (gesture.type === "create" || gesture.type === "draw") ? createPreview(gesture) : null;
 
   return {
-    document, snapshot, selection, marquee: selectionPreview?.marquee ?? null, objects, preview, surface, tool, error, draft: draft.current,
-    choose, select, interaction, editText, commitText, cancel, remove, history,
+    document, snapshot, selection, marquee: selectionPreview?.marquee ?? null, objects, copyOriginals, preview, surface, tool, error, draft: draft.current,
+    choose, select, interaction, editText, commitText, cancel, remove, duplicate, history,
     changeText(text: string) { if (draft.current) { draft.current = { ...draft.current, text }; redraw(); } },
     openJSON(json: string) {
       try {
@@ -262,11 +287,14 @@ export function useCanvasHand(editor: ObjectEditor, style: CanvasCreationStyle,
         pointerMove(event);
         if (pointer.commit(event.pointerId) === null) return;
         const point = eventPoint(event);
-        if (selecting.current && point) commitSelect(point); else commitGesture();
+        if (selecting.current && point) commitSelect(point, event); else commitGesture();
       },
       onPointerCancel(event: PointerEvent<SVGSVGElement>) { pointer.cancel(event.pointerId); },
       onLostPointerCapture(event: PointerEvent<SVGSVGElement>) { pointer.cancel(event.pointerId, "lost-capture"); },
-      onKeyDown: keyDown,
+      onKeyDown: keyDown, onKeyUp: updateModifiers,
+      onCopy: (event: ClipboardEvent) => handleClipboard("copy", event),
+      onCut: (event: ClipboardEvent) => handleClipboard("cut", event),
+      onPaste: (event: ClipboardEvent) => handleClipboard("paste", event),
     },
   };
 }
diff --git a/packages/json-document-canvas/tests/canvas-hand.test.tsx b/packages/json-document-canvas/tests/canvas-hand.test.tsx
index 2ee56189..d26ba35e 100644
--- a/packages/json-document-canvas/tests/canvas-hand.test.tsx
+++ b/packages/json-document-canvas/tests/canvas-hand.test.tsx
@@ -47,6 +47,115 @@ function pick(container: HTMLElement, key: string, shiftKey = false) {
   fireEvent.pointerUp(window, { ...event(70, 70), shiftKey });
 }
 
+function clipboardData() {
+  const data = new Map<string, string>();
+  return { get types() { return [...data.keys()]; }, getData: (format: string) => data.get(format) ?? "", setData: (format: string, value: string) => { data.set(format, value); } };
+}
+function clipboardEvent(target: Element, operation: "copy" | "cut" | "paste", data: ReturnType<typeof clipboardData> | null) {
+  const event = new Event(operation, { bubbles: true, cancelable: true });
+  Object.defineProperty(event, "clipboardData", { value: data });
+  fireEvent(target, event);
+  return event;
+}
+
+test("Alt+Shift drag previews originals and copies, switches live modifiers, then commits the set once", () => {
+  const { container, svg, editor, value, commits } = setup(populated);
+  pick(container, "b", true);
+  const before = value(), target = container.querySelector('[data-canvas-object="a"]')!;
+  fireEvent.pointerDown(target, { ...event(70, 70), altKey: true, shiftKey: true });
+  fireEvent.pointerMove(window, { ...event(120, 90), altKey: true, shiftKey: true });
+  expect(value()).toBe(before); expect(commits).not.toHaveBeenCalled();
+  expect(container.querySelectorAll("[data-canvas-copy-original]")).toHaveLength(2);
+  expect(container.querySelector('[data-canvas-copy-original="a"] foreignObject')?.getAttribute("x")).toBe("100");
+  expect(container.querySelector('[data-canvas-copy-preview] foreignObject')?.getAttribute("x")).toBe("200");
+  expect(target.getAttribute("y")).toBe("100"); expect((target as SVGElement).style.cursor).toBe("copy");
+  fireEvent.keyUp(svg, { key: "Alt", shiftKey: true });
+  expect(container.querySelector("[data-canvas-copy-preview]")).toBeNull();
+  fireEvent.keyDown(svg, { key: "Alt", altKey: true, shiftKey: true });
+  expect(container.querySelector("[data-canvas-copy-preview]")).not.toBeNull();
+  fireEvent.pointerUp(window, { ...event(120, 90), altKey: true, shiftKey: true });
+  expect(value().objects.slice(0, 3)).toEqual(populated.objects);
+  expect(value().objects.slice(3).map((object) => [object.id, object.x, object.y])).toEqual([["object-1", 200, 100], ["object-2", 400, 100]]);
+  expect(editor.snapshot.selection).toMatchObject({ keys: ["object-1", "object-2"], primaryKey: "object-1" });
+  expect(commits).toHaveBeenCalledOnce();
+  fireEvent.keyDown(svg, { key: "z", metaKey: true }); expect(value()).toEqual(before);
+  expect(editor.snapshot.selection).toMatchObject({ keys: ["a", "b"], primaryKey: "a" });
+});
+
+test.each(["Escape", "pointercancel"])("cancelled Alt duplication (%s) does not allocate IDs or commit", (reason) => {
+  const { container, svg, editor, value, commits } = setup(populated);
+  const target = container.querySelector('[data-canvas-object="a"]')!;
+  fireEvent.pointerDown(target, { ...event(70, 70), altKey: true });
+  fireEvent.pointerMove(window, { ...event(120, 90), altKey: true });
+  if (reason === "Escape") fireEvent.keyDown(svg, { key: "Escape" }); else fireEvent.pointerCancel(window, event(120, 90));
+  fireEvent.pointerUp(window, { ...event(120, 90), altKey: true });
+  expect(container.querySelector("[data-canvas-copy-preview]")).toBeNull();
+  expect(value()).toEqual(populated); expect(commits).not.toHaveBeenCalled();
+  fireEvent.keyDown(svg, { key: "d", ctrlKey: true });
+  expect(editor.snapshot.selection.keys).toEqual(["object-1"]);
+});
+
+test("duplicate keyboard/toolbar and nudge reuse Editing with selection-preserving Undo", () => {
+  const { container, svg, editor, value } = setup(populated);
+  pick(container, "b", true);
+  fireEvent.keyDown(svg, { key: "d", metaKey: true });
+  expect(editor.snapshot.selection.keys).toEqual(["object-1", "object-2"]);
+  expect(value().objects[3]!.x).toBe(124);
+  fireEvent.click(screen.getByRole("button", { name: "복제" }));
+  expect(editor.snapshot.selection.keys).toEqual(["object-3", "object-4"]);
+  expect(value().objects[5]!.x).toBe(148);
+  fireEvent.keyDown(svg, { key: "ArrowRight" }); fireEvent.keyDown(svg, { key: "ArrowUp", shiftKey: true });
+  expect(value().objects[5]).toMatchObject({ x: 149, y: 138 });
+  expect(value().objects[6]).toMatchObject({ x: 349, y: 138 });
+  fireEvent.keyDown(svg, { key: "z", metaKey: true });
+  expect(value().objects[5]).toMatchObject({ x: 149, y: 148 });
+  expect(editor.snapshot.selection.keys).toEqual(["object-3", "object-4"]);
+});
+
+test("native structured copy/cut/paste crosses Hand instances with text and primary, and one Undo per edit", () => {
+  const first = setup(populated);
+  act(() => { first.editor.dispatch({ type: "selection.set", objectIds: ["a", "c"], primaryKey: "a" }); });
+  const data = clipboardData();
+  expect(clipboardEvent(first.svg, "copy", data).defaultPrevented).toBe(true);
+  expect(data.getData("text/plain")).toBe("Title\nCircle"); expect(first.commits).not.toHaveBeenCalled();
+  expect(clipboardEvent(first.svg, "cut", data).defaultPrevented).toBe(true);
+  expect(first.value().objects.map((object) => object.id)).toEqual(["b"]); expect(first.commits).toHaveBeenCalledOnce();
+  act(() => { first.editor.undo(); }); expect(first.value()).toEqual(populated);
+  first.unmount();
+  const second = setup();
+  expect(clipboardEvent(second.svg, "paste", data).defaultPrevented).toBe(true);
+  expect(second.value().objects.map((object) => [object.id, object.kind, object.x])).toEqual([["object-1", "text", 124], ["object-2", "ellipse", 624]]);
+  expect(second.editor.snapshot.selection).toMatchObject({ keys: ["object-1", "object-2"], primaryKey: "object-1" });
+  expect(second.commits).toHaveBeenCalledOnce();
+  act(() => { second.editor.undo(); }); expect(second.value()).toEqual(blank);
+});
+
+test("failed cut and invalid paste are observable and cannot delete or partially insert objects", () => {
+  const { svg, value, commits } = setup(populated);
+  const refused = { ...clipboardData(), setData() { throw new Error("write refused"); } };
+  expect(clipboardEvent(svg, "cut", refused).defaultPrevented).toBe(true);
+  expect(screen.getByRole("alert").textContent).toBe("write refused");
+  const data = clipboardData(); data.setData("application/vnd.interactive-os.objects+json", "{}");
+  clipboardEvent(svg, "paste", data);
+  expect(screen.getByRole("alert").textContent).toBe("clipboard.invalid");
+  expect(value()).toEqual(populated); expect(commits).not.toHaveBeenCalled();
+});
+
+test("native clipboard chords, text input, JSON input and IME are not stolen by object editing", () => {
+  const { svg, value, commits } = setup(populated);
+  for (const key of ["c", "x", "v"]) expect(fireEvent.keyDown(svg, { key, metaKey: true })).toBe(true);
+  fireEvent.keyDown(svg, { key: "d", ctrlKey: true, isComposing: true });
+  fireEvent.keyDown(svg, { key: "F2" });
+  const text = screen.getByRole("textbox", { name: "Canvas text" });
+  for (const operation of ["copy", "cut", "paste"] as const) expect(clipboardEvent(text, operation, clipboardData()).defaultPrevented).toBe(false);
+  fireEvent.keyDown(text, { key: "d", metaKey: true }); fireEvent.keyDown(text, { key: "ArrowRight" });
+  fireEvent.keyDown(text, { key: "Escape" });
+  fireEvent.click(screen.getByRole("button", { name: "JSON" }));
+  const json = screen.getByRole("textbox", { name: "Canvas JSON document" });
+  expect(clipboardEvent(json, "cut", clipboardData()).defaultPrevented).toBe(false);
+  expect(value()).toEqual(populated); expect(commits).not.toHaveBeenCalled();
+});
+
 test("Canvas consumes an injected profile for click/Shift/keyboard while focus remains independent", () => {
   const profile = createPlaneSelectProfile();
   const begin = vi.spyOn(profile, "begin"), keyDown = vi.spyOn(profile, "keyDown");
@@ -172,7 +281,7 @@ test("external selection changes supersede a pending preview without a stale sel
 test("every toolbar control shares icon, accessible name and canonical tooltip without losing state", () => {
   const { svg } = setup();
   const toolbar = within(screen.getByRole("toolbar", { name: "Canvas tools" }));
-  const labels = ["선택", "글자", "사각형", "타원", "그리기", "실행 취소", "다시 실행", "삭제", "JSON"];
+  const labels = ["선택", "글자", "사각형", "타원", "그리기", "실행 취소", "다시 실행", "복제", "삭제", "JSON"];
   expect(toolbar.getAllByRole("button")).toHaveLength(labels.length);
   for (const label of labels) {
     const button = toolbar.getByRole("button", { name: label });
diff --git a/packages/json-document-editing/docs/object-selection.md b/packages/json-document-editing/docs/object-selection.md
index 700c47c6..13bc97e8 100644
--- a/packages/json-document-editing/docs/object-selection.md
+++ b/packages/json-document-editing/docs/object-selection.md
@@ -21,3 +21,36 @@ editor.dispatch({ type: "object.resize", objectIds: ["a"], dx: 0, dy: 0, dw: 10,
 Intent를 사용합니다. Undo/Redo는 해당 문서 변경과 함께 원인 선택 집합·primary를 복원합니다.
 
 실제 public API 소비: [Canvas Usage와 Source](/demo/canvas).
+
+### 복제와 Clipboard
+
+`object.duplicate`는 `objectIds` 집합을 문서 순서로 복제합니다. 생략한 `placement`는
+`{ type: "offset", dx: 24, dy: 24 }`이며 Alt drag는 최종 delta를 명시합니다.
+원본 형태·확장 필드·path points·상대 위치를 보존하고 새 ID를 할당합니다. 복제된
+집합을 선택하고 기존 primary와 대응하는 사본을 primary로 삼습니다. source에 primary가
+없으면 마지막 사본이 primary입니다. 반복 복제는 새 선택을 대상으로 같은 offset을 적용합니다.
+
+`clipboard.paste`도 같은 ID 할당·변환·insert 경로를 사용합니다. placement 생략은 기존대로
+zero offset입니다. Object/Canvas Hand의 native paste는 제품 정책으로 24단위 offset을
+전달합니다. 같은 payload의 반복 paste는 같은 위치에 새 ID로 삽입하며 자동 cascade는 하지 않습니다.
+
+`ObjectClipboard`는 구조화 MIME `application/vnd.interactive-os.objects+json`, `objects`,
+`text`와 선택적인 `primaryKey`를 갖습니다. `copy()`는 문서 순서의 객체·label을 결합한 text와
+primary를 투영할 뿐 OS clipboard에 쓰지 않습니다. `objectClipboardFormat.parse`는
+legacy primary 없는 payload도 수용하고, 있으면 복사된 집합의 ID 또는 null인지 검증합니다.
+paste는 primary를 새 ID로 remap합니다. 기존 문서와 source 양쪽 ID를 재사용하지 않습니다.
+
+```ts
+editor.dispatch({ type: "object.duplicate", objectIds: editor.snapshot.selection.keys });
+const captured = editor.copy();
+// Web write가 성공한 뒤에만, 현재 선택을 다시 읽지 않고 캡처된 대상 제거:
+if (captured) editor.dispatch({ type: "object.remove", objectIds: captured.objects.map((object) => object.id) });
+```
+
+`object.remove`는 명시한 ID 집합을 제거합니다. `selection.remove`와 같은 원자적 연산을
+사용하며, 일부 ID가 없으면 전체 거절합니다. `cut()`은 OS 이벤트 밖의 headless 명령이므로
+브라우저에서는 Web binding으로 **write → captured 대상 remove** 순서를 보장해야 합니다.
+
+복제·paste·remove는 명령당 하나의 commit/Undo입니다. ID 할당 불가, 잘못된 offset이나
+payload, 대상/프로파일 위반은 부분 문서·선택·History를 남기지 않습니다. Canvas의 strict
+profile은 generic Object clipboard라도 결과가 유효한 경우만 삽입합니다.
diff --git a/packages/json-document-editing/package.json b/packages/json-document-editing/package.json
index 4f8c8546..edef275c 100644
--- a/packages/json-document-editing/package.json
+++ b/packages/json-document-editing/package.json
@@ -17,7 +17,7 @@
     "provenance": true,
     "tag": "next"
   },
-  "files": ["dist", "!dist/.tsbuildinfo", "README.md", "docs/calendar-profile.md", "LICENSE"],
+  "files": ["dist", "!dist/.tsbuildinfo", "README.md", "docs", "LICENSE"],
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
diff --git a/packages/json-document-editing/src/object.ts b/packages/json-document-editing/src/object.ts
index 62adb7f0..3e4cfbf4 100644
--- a/packages/json-document-editing/src/object.ts
+++ b/packages/json-document-editing/src/object.ts
@@ -29,18 +29,24 @@ export interface ObjectSelection extends Record<string, JSONValue> {
 
 export type ObjectSelectionMode = "replace" | "extend" | "add" | "subtract" | "toggle";
 
-export interface ObjectClipboard extends Record<string, JSONValue> {
+export type ObjectClipboard = Record<string, JSONValue> & {
   readonly type: "application/vnd.interactive-os.objects+json";
   readonly objects: ReadonlyArray<DocumentObject>;
   readonly text: string;
-}
+  /** Optional for legacy payloads; remapped to the corresponding new ID on paste. */
+  readonly primaryKey?: string | null;
+};
 
 export const objectClipboardFormat = {
   mimeType: "application/vnd.interactive-os.objects+json" as const,
   parse(value: unknown): ObjectClipboard | null {
     if (!isClipboardRecord(value) || value.type !== this.mimeType || typeof value.text !== "string") return null;
     if (!Array.isArray(value.objects) || value.objects.some((object) => !isClipboardRecord(object) || typeof object.color !== "string")) return null;
-    try { assertObjectDocument(value); return value as ObjectClipboard; } catch { return null; }
+    try {
+      assertObjectDocument(value);
+      if (value.primaryKey !== undefined && value.primaryKey !== null && !value.objects.some((object) => object.id === value.primaryKey)) return null;
+      return value as ObjectClipboard;
+    } catch { return null; }
   },
 };
 
@@ -52,6 +58,8 @@ export interface ObjectPastePlacement {
 
 export type ObjectIntent =
   | { readonly type: "object.create"; readonly object: ObjectDraft }
+  | { readonly type: "object.duplicate"; readonly objectIds: ReadonlyArray<string>; readonly placement?: ObjectPastePlacement }
+  | { readonly type: "object.remove"; readonly objectIds: ReadonlyArray<string> }
   | { readonly type: "object.text"; readonly objectId: string; readonly text: string }
   | { readonly type: "document.replace"; readonly document: ObjectDocument }
   | {
@@ -180,15 +188,20 @@ export function createObjectEditor(
       return apply({ type: "transform", objectIds: intent.objectIds, transform: { dx: intent.dx, dy: intent.dy, dw: intent.dw, dh: intent.dh } }, selectionForTargets(intent.objectIds), intent.type);
     }
 
+    if (intent.type === "object.remove") return removeSelected(intent.objectIds, intent.type);
+
+    if (intent.type === "object.duplicate") {
+      const ids = new Set(intent.objectIds);
+      const source = value().objects.filter((object) => ids.has(object.id));
+      if (source.length !== ids.size) return failure("selection.object-not-found");
+      if (source.length === 0) return failure("selection.empty");
+      return insertCopies(source, session.snapshot.selection.primaryKey, intent.placement ?? { type: "offset", dx: 24, dy: 24 }, intent.type);
+    }
+
     if (intent.type === "clipboard.paste") {
-      const objects = value().objects;
       if (!objectClipboardFormat.parse(intent.clipboard)) return failure("clipboard.invalid");
-      const dx = intent.placement?.dx ?? 0, dy = intent.placement?.dy ?? 0;
-      if (![dx, dy].every(Number.isFinite)) return failure("object.invalid");
-      const pasted = cloneObjectsWithUniqueIds(intent.clipboard.objects, objects, createId)
-        .map((object) => transformObject(object, { dx, dy }));
-      if (pasted.length === 0) return failure("clipboard.empty");
-      return apply({ type: "insert", objects: pasted }, selectionFor(pasted.map((object) => object.id)), intent.type);
+      if (intent.clipboard.objects.length === 0) return failure("clipboard.empty");
+      return insertCopies(intent.clipboard.objects, intent.clipboard.primaryKey ?? null, intent.placement, intent.type);
     }
 
     const selected = selectedObjects();
@@ -206,6 +219,19 @@ export function createObjectEditor(
     return ids.length > 0 && ids.every((id) => selected.has(id)) ? selection : selectionFor(ids);
   }
 
+  function insertCopies(source: readonly DocumentObject[], primaryKey: string | null, placement: ObjectPastePlacement | undefined, origin: string): EditingResult<ObjectSelection> {
+    const dx = placement?.dx ?? 0, dy = placement?.dy ?? 0;
+    if (![dx, dy].every(Number.isFinite)) return failure("object.invalid");
+    let copies: DocumentObject[];
+    try {
+      copies = cloneObjectsWithUniqueIds(source, value().objects, createId).map((object) => transformObject(object, { dx, dy }));
+    } catch (error) {
+      return { ok: false, code: "object.identity-unavailable", reason: error instanceof Error ? error.message : String(error) };
+    }
+    const primary = copies[source.findIndex((object) => object.id === primaryKey)]?.id ?? copies.at(-1)!.id;
+    return apply({ type: "insert", objects: copies }, selectionFor(copies.map((object) => object.id), primary), origin);
+  }
+
   function apply(operation: ObjectOperation, selectionAfter: ObjectSelection, origin: string): EditingResult<ObjectSelection> {
     const plan = planObjectOperation(value(), operation);
     return plan.ok ? session.apply({ operations: plan.operations, selectionAfter, origin }) : plan;
@@ -218,13 +244,15 @@ export function createObjectEditor(
       type: "application/vnd.interactive-os.objects+json",
       objects,
       text: objects.map((object) => object.label).join("\n"),
+      primaryKey: session.snapshot.selection.primaryKey,
     };
   }
 
-  function removeSelected(ids: ReadonlyArray<string>): EditingResult<ObjectSelection> {
+  function removeSelected(ids: ReadonlyArray<string>, origin = "selection.remove"): EditingResult<ObjectSelection> {
     const objects = value().objects;
     if (ids.length === 0) return failure("selection.empty");
     const selectedIds = new Set(ids);
+    if (ids.some((id) => !objects.some((object) => object.id === id))) return failure("selection.object-not-found");
     const indices = objects
       .map((object, index) => selectedIds.has(object.id) ? index : -1)
       .filter((index) => index >= 0)
@@ -232,7 +260,7 @@ export function createObjectEditor(
     const remaining = objects.filter((object) => !selectedIds.has(object.id));
     const firstRemoved = Math.min(...indices);
     const next = remaining[Math.min(firstRemoved, remaining.length - 1)];
-    return apply({ type: "remove", objectIds: ids }, selectionFor(next ? [next.id] : []), "selection.remove");
+    return apply({ type: "remove", objectIds: [...selectedIds] }, selectionFor(next ? [next.id] : []), origin);
   }
 
   return {
@@ -240,7 +268,7 @@ export function createObjectEditor(
     get selectedObjects() { return selectedObjects(); },
     dispatch,
     copy,
-    cut: () => cutEditingClipboard(copy, () => removeSelected(selectedObjects().map((object) => object.id))),
+    cut: () => cutEditingClipboard(copy, (clipboard) => removeSelected(clipboard.objects.map((object) => object.id))),
     undo: () => session.undo(),
     redo: () => session.redo(),
     subscribe: (listener) => session.subscribe(listener),
@@ -252,7 +280,7 @@ function cloneObjectsWithUniqueIds(
   existing: ReadonlyArray<DocumentObject>,
   createId: () => string,
 ): DocumentObject[] {
-  const allocateId = createEditingIdAllocator(existing.map((object) => object.id), createId, "object");
+  const allocateId = createEditingIdAllocator([...existing, ...source].map((object) => object.id), createId, "object");
   return source.map((object) => ({ ...object, id: allocateId() }));
 }
 
diff --git a/packages/json-document-editing/tests/identity.test.ts b/packages/json-document-editing/tests/identity.test.ts
index dbdaaa68..53da91a0 100644
--- a/packages/json-document-editing/tests/identity.test.ts
+++ b/packages/json-document-editing/tests/identity.test.ts
@@ -54,7 +54,7 @@ describe("default domain identities", () => {
     expect(allocateId()).toBe("next");
   });
 
-  test.each(cases)("$name preserves the collision limit and document on failure", ({ initial, insert }) => {
+  test.each(cases)("$name preserves the collision limit and document on failure", ({ name, initial, insert }) => {
     const randomUUID = vi.fn(() => "collision");
     vi.stubGlobal("crypto", { randomUUID });
     try {
@@ -62,7 +62,9 @@ describe("default domain identities", () => {
       expect(insert(document)).toBe(true);
       const before = document.value;
       randomUUID.mockClear();
-      expect(() => insert(document)).toThrow("createId did not produce a unique");
+      // Object reports identity exhaustion as an EditingResult for native clipboard consumers.
+      if (name === "Object") expect(insert(document)).toBe(false);
+      else expect(() => insert(document)).toThrow("createId did not produce a unique");
       expect(randomUUID).toHaveBeenCalledTimes(100);
       expect(document.value).toBe(before);
     } finally { vi.unstubAllGlobals(); }
diff --git a/packages/json-document-editing/tests/object-copy.test.ts b/packages/json-document-editing/tests/object-copy.test.ts
new file mode 100644
index 00000000..52962a66
--- /dev/null
+++ b/packages/json-document-editing/tests/object-copy.test.ts
@@ -0,0 +1,88 @@
+import { expect, test, vi } from "vitest";
+import { createJSONDocument } from "@interactive-os/json-document";
+import { createObjectEditor, objectClipboardFormat, type ObjectClipboard, type ObjectIntent } from "../src/index.js";
+import type { CanvasDocument } from "@interactive-os/json-document-object-document";
+
+const initial: CanvasDocument = { profile: "canvas/1", width: 1280, height: 720, objects: [
+  { id: "text", kind: "text", x: 10, y: 20, width: 200, height: 80, color: "black", label: "Hello", fontSize: 32 },
+  { id: "path", kind: "path", x: 100, y: 120, width: 150, height: 60, color: "blue", label: "Drawing", strokeWidth: 3, points: [{ x: 0, y: 1 }, { x: 1, y: 0 }] },
+] };
+
+function setup() {
+  let id = 0;
+  const document = createJSONDocument(initial);
+  const editor = createObjectEditor(document, { createId: () => `copy-${++id}` });
+  editor.dispatch({ type: "selection.set", objectIds: ["text", "path"], primaryKey: "text" });
+  const commits = vi.fn(); document.subscribe(commits);
+  return { editor, document, commits };
+}
+
+test.each(["object.duplicate", "clipboard.paste"] as const)("%s remaps primary and fresh identities, preserves order/shape, and commits once", (type) => {
+  const { editor, document, commits } = setup();
+  const selection = editor.snapshot.selection;
+  const clipboard = editor.copy()!;
+  expect(clipboard.primaryKey).toBe("text"); expect(clipboard.text).toBe("Hello\nDrawing");
+  const placement = { type: "offset", dx: 70, dy: -30 } as const;
+  const intent: ObjectIntent = type === "object.duplicate" ? { type, objectIds: ["path", "text", "path"], placement } : { type, clipboard, placement };
+  expect(editor.dispatch(intent).ok).toBe(true);
+  const after = document.value as CanvasDocument;
+  expect(after.objects.slice(0, 2)).toEqual(initial.objects);
+  expect(after.objects.slice(2)).toEqual(initial.objects.map((object, index) => ({ ...object, id: `copy-${index + 1}`, x: object.x + 70, y: object.y - 30 })));
+  expect(editor.snapshot.selection).toEqual({ kind: "explicit", keys: ["copy-1", "copy-2"], primaryKey: "copy-1" });
+  expect(commits).toHaveBeenCalledOnce();
+  expect(editor.undo().ok).toBe(true); expect(document.value).toEqual(initial); expect(editor.snapshot.selection).toEqual(selection);
+  expect(editor.snapshot.canUndo).toBe(false);
+  expect(editor.redo().ok).toBe(true); expect(document.value).toEqual(after); expect(editor.snapshot.selection.primaryKey).toBe("copy-1");
+});
+
+test("repeat duplicate operates on the newly selected set with the default offset", () => {
+  const { editor } = setup();
+  for (let index = 1; index <= 2; index++) {
+    expect(editor.dispatch({ type: "object.duplicate", objectIds: editor.snapshot.selection.keys }).ok).toBe(true);
+    expect(editor.selectedObjects[0]!.x).toBe(10 + 24 * index);
+    expect(editor.selectedObjects[0]!.id).toBe(`copy-${index * 2 - 1}`);
+  }
+});
+
+test("legacy clipboard remains readable and cross-document paste cannot reuse source IDs", () => {
+  const clipboard: ObjectClipboard = { type: objectClipboardFormat.mimeType, objects: initial.objects, text: "Hello\nDrawing" };
+  let id = 0;
+  const ids = ["text", "path", "new-text", "new-path"];
+  const editor = createObjectEditor({ ...initial, objects: [] }, { createId: () => ids[id++]! });
+  expect(objectClipboardFormat.parse(clipboard)).toEqual(clipboard);
+  expect(editor.dispatch({ type: "clipboard.paste", clipboard }).ok).toBe(true);
+  expect(editor.snapshot.selection).toMatchObject({ keys: ["new-text", "new-path"], primaryKey: "new-path" });
+  expect(objectClipboardFormat.parse({ ...clipboard, primaryKey: "missing" })).toBeNull();
+  expect(objectClipboardFormat.parse({ ...clipboard, primaryKey: 1 })).toBeNull();
+});
+
+test("invalid targets, geometry, profile payload and exhausted IDs never partially mutate selection/history/document", () => {
+  const { editor, document, commits } = setup();
+  const before = editor.snapshot;
+  const clipboard = editor.copy()!;
+  const intents: ObjectIntent[] = [
+    { type: "object.duplicate", objectIds: ["text", "missing"] },
+    { type: "object.duplicate", objectIds: [] },
+    { type: "object.duplicate", objectIds: ["text"], placement: { type: "offset", dx: Infinity, dy: 0 } },
+    { type: "object.remove", objectIds: ["text", "missing"] },
+    { type: "clipboard.paste", clipboard: { ...clipboard, objects: [{ ...initial.objects[0]!, kind: "unknown" }] } },
+  ];
+  for (const intent of intents) { expect(editor.dispatch(intent).ok).toBe(false); expect(editor.snapshot).toEqual(before); }
+  expect(document.value).toEqual(initial); expect(commits).not.toHaveBeenCalled();
+  const exhausted = createObjectEditor(initial, { createId: () => "text" });
+  for (const intent of [{ type: "object.duplicate", objectIds: ["text"] }, { type: "clipboard.paste", clipboard }] as const) {
+    expect(exhausted.dispatch(intent)).toMatchObject({ ok: false, code: "object.identity-unavailable" });
+    expect(exhausted.snapshot.value).toEqual(initial); expect(exhausted.snapshot.canUndo).toBe(false);
+  }
+});
+
+test("captured clipboard targets can be removed after selection changes without deleting the new selection", () => {
+  const { editor, commits } = setup();
+  editor.dispatch({ type: "selection.set", objectIds: ["text"] });
+  const clipboard = editor.copy()!;
+  editor.dispatch({ type: "selection.set", objectIds: ["path"] });
+  expect(editor.dispatch({ type: "object.remove", objectIds: clipboard.objects.map((object) => object.id) }).ok).toBe(true);
+  expect((editor.snapshot.value as CanvasDocument).objects.map((object) => object.id)).toEqual(["path"]);
+  expect(commits).toHaveBeenCalledOnce();
+  expect(editor.undo().ok).toBe(true); expect(editor.snapshot.value).toEqual(initial);
+});
diff --git a/packages/json-document-object-document/docs/api.md b/packages/json-document-object-document/docs/api.md
index e6b2df22..800e5fb1 100644
--- a/packages/json-document-object-document/docs/api.md
+++ b/packages/json-document-object-document/docs/api.md
@@ -59,6 +59,6 @@ clip합니다. 위치를 자동 보정하거나 snap하지 않습니다.
 정본을 소비합니다. [Object 소유권 감사](/docs/document-types/object)는 영향을 받는
 모델·연산·Editing·Hand·두 Canvas Host의 소유자를 기록합니다.
 
-페이지·줌·팬·다중 선택 UI·그룹·회전·정렬·snap·레이어 패널·PPTX·협업은 이
+페이지·줌·팬·그룹·회전·정렬·snap·레이어 패널·PPTX·협업은 이
 Canvas slice 범위 밖입니다. 이 RC 프로파일은 독립 구현 간 Stable wire conformance를
 선언하지 않습니다. Annotation의 source/selector/body 모델도 Canvas에 통합하지 않습니다.
diff --git a/packages/json-document-web/README.md b/packages/json-document-web/README.md
index ac5dfe8d..a01ad5a9 100644
--- a/packages/json-document-web/README.md
+++ b/packages/json-document-web/README.md
@@ -31,12 +31,16 @@ ARIA projection, composite focus, and text input. It translates native `Clipboar
 conventional keyboard chords without rendering UI or deciding product
 keyboard policy.
 
-Once a supported cut has written its payload or a paste has decoded a supported
-payload, the binding cancels the native event before calling the editor. A
+When a cut callback is configured, the binding cancels native cut before attempting
+to write, including unavailable/failed/partial writes. It calls the editor only after
+every representation is written. A supported paste is cancelled after decoding and before editing. A
 rejected edit remains `editing.rejected` and cannot fall through to a browser
 mutation. Unsupported or undecodable paste data keeps its existing pass-through
 behavior.
 
+See the owning [Clipboard event contract](docs/clipboard.md) for captured targets,
+native editable ownership and observable failure semantics.
+
 `registerWebVirtualSelectionScope` coordinates native Select All and copy when a
 surface mounts only part of its model. It selects the mounted root with a real
 DOM Range, then writes the registered complete model text during the native
diff --git a/packages/json-document-web/docs/clipboard.md b/packages/json-document-web/docs/clipboard.md
new file mode 100644
index 00000000..028f3656
--- /dev/null
+++ b/packages/json-document-web/docs/clipboard.md
@@ -0,0 +1,33 @@
+## Web Clipboard · 이벤트 소유권
+
+`createWebClipboardBinding`은 플랫폼의 copy/cut/paste와 구조화 payload codec을 연결합니다.
+`createWebClipboardSurface`는 같은 binding의 `onCopy/onCut/onPaste`와 결과 관찰을 제공합니다.
+정본 export는 `@interactive-os/json-document-web`에 있습니다. 도메인 객체와 ID·Selection·History는 Editing 소유입니다.
+
+```ts
+import { createWebClipboardBinding, objectClipboardCodec } from "@interactive-os/json-document-web";
+
+const clipboard = createWebClipboardBinding({
+  codec: objectClipboardCodec,
+  read: () => editor.copy(),
+  cut: (payload) => editor.dispatch({ type: "object.remove", objectIds: payload.objects.map((object) => object.id) }),
+  paste: (payload) => editor.dispatch({ type: "clipboard.paste", clipboard: payload }),
+});
+```
+
+- 기본 write는 codec의 구조화 MIME과 `text/plain`을 함께 기록합니다. `representations`를
+  전달하면 지정한 표현 목록을 사용합니다. 전부 쓰기 성공한 뒤에만 `cut(payload)`를 호출합니다.
+- cut callback이 있으면 쓰기 시도 **전에** native cut을 취소합니다. clipboard 없음·쓰기 거절·
+  부분 쓰기·빈 선택·Editing 거절이 native fallback 삭제로 이어지지 않습니다. native editable
+  target인지 판별하여 호출할 책임은 binding 소비자에게 있습니다. 미지원 cut callback은 이벤트를 소유하지 않습니다.
+- `cut`은 `read`가 반환하고 실제 쓴 payload를 받습니다. 변경 가능한 현재 선택을 다시 읽지 말고
+  이 캡처 대상을 제거합니다. clipboard의 여러 MIME 쓰기 자체는 OS 원자적 transaction이 아니므로
+  앞 표현이 남고 뒤 쓰기가 실패할 수 있습니다. 이때도 도메인 문서는 삭제하지 않습니다.
+- paste는 지원하는 MIME을 decode한 뒤 native event를 취소하고 Editing을 호출합니다.
+  미지원/해독 불가 데이터는 `clipboard.empty/invalid`, 사용 불가는 `clipboard.unavailable`,
+  Editing 거절은 `editing.rejected`로 관찰합니다. 미지원/해독 불가 paste의 기존 pass-through는 유지합니다.
+- Mod+C/X/V keydown을 막으면 native clipboard event가 오지 않을 수 있습니다. 키 명령에서
+  가상의 복사 동작을 만들지 않고 native 이벤트를 이 binding에 연결합니다.
+
+실제 소비와 Source: [Canvas](/demo/canvas), [Object Demo](/demo/object),
+[Clipboard Adapter](/adapters/clipboard). Canvas text/JSON textarea는 native clipboard를 유지합니다.
diff --git a/packages/json-document-web/package.json b/packages/json-document-web/package.json
index 98454e30..5eb7151a 100644
--- a/packages/json-document-web/package.json
+++ b/packages/json-document-web/package.json
@@ -17,7 +17,7 @@
     "provenance": true,
     "tag": "next"
   },
-  "files": ["dist", "!dist/.tsbuildinfo", "README.md", "LICENSE"],
+  "files": ["dist", "!dist/.tsbuildinfo", "README.md", "docs", "LICENSE"],
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
diff --git a/packages/json-document-web/src/clipboard.ts b/packages/json-document-web/src/clipboard.ts
index 16e27cb1..28e3f5b7 100644
--- a/packages/json-document-web/src/clipboard.ts
+++ b/packages/json-document-web/src/clipboard.ts
@@ -165,9 +165,11 @@ export function createWebClipboardBinding<
     },
     cut(event) {
       if (options.cut === undefined) return failure("clipboard.unsupported");
+      // The binding owns this cut, including write failure. Never allow native
+      // fallback deletion after a refused/partial structured clipboard write.
+      event.preventDefault();
       const written = write(event);
       if (!written.ok) return written;
-      event.preventDefault();
       const result = options.cut(written.payload);
       if (result === null) return failure("editing.rejected", "clipboard.empty");
       if (!result.ok) return failure("editing.rejected", result.reason ?? result.code);
diff --git a/packages/json-document-web/tests/clipboard-rejection.test.ts b/packages/json-document-web/tests/clipboard-rejection.test.ts
index 754224be..24e150d3 100644
--- a/packages/json-document-web/tests/clipboard-rejection.test.ts
+++ b/packages/json-document-web/tests/clipboard-rejection.test.ts
@@ -39,16 +39,18 @@ describe("clipboard event ownership", () => {
     const published: unknown[] = [];
     const release = editor.subscribe((snapshot) => published.push(snapshot));
     const written = new Map<string, string>();
+    const preventDefault = vi.fn();
     try {
       const result = binding.cut({
         clipboardData: { types: [], getData: () => "", setData(format, data) {
           if (format === (failedWrite === "structured" ? payload.type : "text/plain")) throw new Error("Clipboard write refused");
           written.set(format, data);
         } },
-        preventDefault() {},
+        preventDefault,
       });
       expect(result).toMatchObject({ ok: false, code: "clipboard.unavailable" });
       expect(remove).not.toHaveBeenCalled();
+      expect(preventDefault).toHaveBeenCalledOnce();
       expect(document.value).toEqual(before.value);
       expect(editor.snapshot).toMatchObject(before);
       expect(published).toEqual([]);
diff --git a/packages/json-document-web/tests/web-adapters.test.ts b/packages/json-document-web/tests/web-adapters.test.ts
index 3b93bd46..20dade68 100644
--- a/packages/json-document-web/tests/web-adapters.test.ts
+++ b/packages/json-document-web/tests/web-adapters.test.ts
@@ -397,7 +397,7 @@ describe("Web clipboard Adapter", () => {
 
     const unavailable = event(null);
     expect(binding.cut(unavailable)).toMatchObject({ ok: false, code: "clipboard.unavailable" });
-    expect(unavailable.defaultPrevented).toBe(false);
+    expect(unavailable.defaultPrevented).toBe(true);
     expect(cutAttempts).toBe(0);
     expect((editor.snapshot.value as BlockDocument).blocks.map((block) => block.id)).toEqual(["a", "b"]);
 
diff --git a/site/src/routes/docs/doc-pages.ts b/site/src/routes/docs/doc-pages.ts
index 563841db..88f5b807 100644
--- a/site/src/routes/docs/doc-pages.ts
+++ b/site/src/routes/docs/doc-pages.ts
@@ -26,6 +26,7 @@ import objectDocumentContractMarkdown from "../../../../packages/json-document-o
 import canvasApiMarkdown from "../../../../docs/api-reference/canvas.md?raw";
 import canvasContractMarkdown from "../../../../packages/json-document-canvas/docs/api.md?raw";
 import webApiMarkdown from "../../../../docs/api-reference/web.md?raw";
+import webClipboardContractMarkdown from "../../../../packages/json-document-web/docs/clipboard.md?raw";
 import contenteditableApiMarkdown from "../../../../docs/api-reference/contenteditable.md?raw";
 import richTextApiMarkdown from "../../../../docs/api-reference/rich-text.md?raw";
 import fileIntakeApiMarkdown from "../../../../docs/api-reference/file-intake.md?raw";
@@ -203,7 +204,7 @@ export const docPages = {
   calendarDocumentApi: docPage("/docs/api/calendar-document", `${calendarDocumentContractMarkdown}\n\n${calendarDocumentApiMarkdown}`),
   objectDocumentApi: docPage("/docs/api/object-document", `${objectDocumentContractMarkdown}\n\n${objectDocumentApiMarkdown}`),
   canvasApi: docPage("/docs/api/canvas", `${canvasContractMarkdown}\n\n${canvasApiMarkdown}`),
-  webApi: docPage("/docs/api/web", webApiMarkdown),
+  webApi: docPage("/docs/api/web", `${webClipboardContractMarkdown}\n\n${webApiMarkdown}`),
   contenteditableApi: docPage("/docs/api/contenteditable", contenteditableApiMarkdown),
   richTextApi: docPage("/docs/api/rich-text", richTextApiMarkdown),
   fileIntakeApi: docPage("/docs/api/file-intake", fileIntakeApiMarkdown),
diff --git a/site/src/routes/object-demo/ObjectDemoRoute.tsx b/site/src/routes/object-demo/ObjectDemoRoute.tsx
index 12d06c91..616f334e 100644
--- a/site/src/routes/object-demo/ObjectDemoRoute.tsx
+++ b/site/src/routes/object-demo/ObjectDemoRoute.tsx
@@ -1,9 +1,8 @@
 import { useState } from "react";
-import { ClipboardPaste, Copy, Redo2, Scissors, Trash2, Undo2 } from "lucide-react";
+import { CopyPlus, Redo2, Trash2, Undo2 } from "lucide-react";
 import { DemoPage } from "../../shared/demo-workbench/DemoPage";
 import {
   createObjectEditor,
-  type ObjectClipboard,
   type ObjectDocument,
   type ObjectIntent,
 } from "@interactive-os/json-document-editing";
@@ -24,12 +23,11 @@ import { editingItemProps } from "@interactive-os/json-document-react";
 
 export function ObjectDemoRoute() {
   const [editor] = useState(() => createObjectEditor(initialObjectDemoDocument));
-  const [clipboard, setClipboard] = useState<ObjectClipboard | null>(null);
   const observation = useEditingObservation<ObjectIntent>("Ready");
   const [clipboardSurface] = useState(() => createWebClipboardSurface({
     codec: objectClipboardCodec,
     read: () => editor.copy(),
-    cut: () => editor.cut()?.result ?? { ok: false, code: "selection.empty" },
+    cut: (payload) => editor.dispatch({ type: "object.remove", objectIds: payload.objects.map((object) => object.id) }),
     paste: (payload) => editor.dispatch({
       type: "clipboard.paste",
       clipboard: payload,
@@ -37,7 +35,6 @@ export function ObjectDemoRoute() {
     }),
     onResult(result) {
       if (!result.ok) return observation.announce(result.code);
-      if (result.operation !== "paste") setClipboard(result.payload);
       const verb = result.operation === "copy" ? "Copied" : result.operation === "cut" ? "Cut" : "Pasted";
       observation.announce(`${verb} ${result.payload.objects.length} structured object${result.payload.objects.length === 1 ? "" : "s"}`);
     },
@@ -70,20 +67,6 @@ export function ObjectDemoRoute() {
   const document = snapshot.value as ObjectDocument;
   const commands = historyAffordance(snapshot).hand;
 
-  function copySelection() {
-    const next = editor.copy();
-    if (!next) return observation.announce("Select an object first");
-    setClipboard(next);
-    observation.announce(`Copied ${next.objects.length} object${next.objects.length === 1 ? "" : "s"}`);
-  }
-
-  function cutSelection() {
-    const result = editor.cut();
-    if (!result) return observation.announce("Select an object first");
-    setClipboard(result.clipboard);
-    observation.announce(`Cut ${result.clipboard.objects.length} object${result.clipboard.objects.length === 1 ? "" : "s"}`);
-  }
-
   return (
     <DemoPage documentation={(
       <PageHeader
@@ -115,21 +98,9 @@ export function ObjectDemoRoute() {
               </Command>
             ))}
             <span className={classes("mx-1 w-px", ui.surface.separator)} aria-hidden="true" />
-            <Command label="Copy" onClick={copySelection}><Copy aria-hidden="true" size={16} /></Command>
-            <Command label="Cut" onClick={cutSelection}><Scissors aria-hidden="true" size={16} /></Command>
-            <Command label="Paste"
-              disabled={!clipboard}
-              onClick={() => {
-                if (!clipboard) return;
-                run({
-                  type: "clipboard.paste",
-                  clipboard,
-                  placement: { type: "offset", dx: 24, dy: 24 },
-                }, `Pasted ${clipboard.objects.length} object${clipboard.objects.length === 1 ? "" : "s"}`);
-              }}
-            >
-              <ClipboardPaste aria-hidden="true" size={16} />
-            </Command>
+            <Command label="Duplicate" disabled={editor.selectedObjects.length === 0}
+              onClick={() => run({ type: "object.duplicate", objectIds: snapshot.selection.keys }, "Selection duplicated")}
+            ><CopyPlus aria-hidden="true" size={16} /></Command>
             <Command label="Delete" onClick={() => run({ type: "selection.remove" }, "Selection deleted")}><Trash2 aria-hidden="true" size={16} /></Command>
             <span className={classes("mx-1 w-px", ui.surface.separator)} aria-hidden="true" />
             <Command label="Undo" disabled={commands.undo.disabled} onClick={() => { editor.undo(); observation.announce("Undone"); }}><Undo2 aria-hidden="true" size={16} /></Command>
@@ -168,7 +139,7 @@ export function ObjectDemoRoute() {
               {object.label}
             </SelectableItem>
           ))}
-          <p className={classes("absolute bottom-3 left-3 mb-0", ui.text.meta)}>Click a box. Mod-click toggles. Fill uses the selected IDs only.</p>
+          <p className={classes("absolute bottom-3 left-3 mb-0", ui.text.meta)}>Click a box. Mod-click toggles. Mod+C/X/V uses the system clipboard.</p>
         </section>
       </ProductShell>
     </DemoPage>
diff --git a/site/src/shared/demo-workbench/demo-sources.ts b/site/src/shared/demo-workbench/demo-sources.ts
index d39a6372..bf3a2ac7 100644
--- a/site/src/shared/demo-workbench/demo-sources.ts
+++ b/site/src/shared/demo-workbench/demo-sources.ts
@@ -1156,6 +1156,16 @@ const registeredPublicUsages = [
     symbol: "createWebClipboardSurface",
     sourcePath: "packages/json-document-web/src/clipboard.ts",
   },
+  {
+    packageName: "@interactive-os/json-document-web",
+    symbol: "createWebClipboardBinding",
+    sourcePath: "packages/json-document-web/src/clipboard.ts",
+  },
+  {
+    packageName: "@interactive-os/json-document-web",
+    symbol: "objectClipboardCodec",
+    sourcePath: "packages/json-document-web/src/clipboard.ts",
+  },
   {
     packageName: "@interactive-os/json-document-web",
     symbol: "createWebJSONClipboardRepresentation",
diff --git a/site/tests/browser/canvas-slice.spec.ts b/site/tests/browser/canvas-slice.spec.ts
index 53fc13e7..bc377483 100644
--- a/site/tests/browser/canvas-slice.spec.ts
+++ b/site/tests/browser/canvas-slice.spec.ts
@@ -5,7 +5,7 @@ for (const route of ["/demo/canvas", "/widgets/canvas"]) {
     await page.goto(route);
     const toolbar = page.getByRole("toolbar", { name: "Canvas tools" });
     const buttons = toolbar.getByRole("button");
-    await expect(buttons).toHaveCount(9);
+    await expect(buttons).toHaveCount(10);
     for (const button of await buttons.all()) {
       await expect(button).toHaveAttribute("data-ui-presentation", "icon");
       await expect(button.locator('svg[aria-hidden="true"]')).toHaveCount(1);
@@ -68,6 +68,33 @@ test("Canvas composes one slide and reopens the same JSON through the canonical
   await expect(page.locator("[data-canvas-object]")).toHaveCount(4);
 });
 
+test("Canvas Alt-copy, nudge, duplicate and native selected clipboard share atomic Editing", async ({ page }) => {
+  await page.goto("/widgets/canvas");
+  await page.locator('[data-canvas-object="rectangle"]').click();
+  await page.locator('[data-canvas-object="ellipse"]').click({ modifiers: ["Shift"] });
+  const start = await point(page, 200, 350), end = await point(page, 300, 390);
+  await page.keyboard.down("Alt"); await page.keyboard.down("Shift");
+  await page.mouse.move(start.x, start.y); await page.mouse.down(); await page.mouse.move(end.x, end.y);
+  await expect(page.locator("[data-canvas-copy-original]")).toHaveCount(2);
+  await expect(page.locator("[data-canvas-object]")).toHaveCount(3);
+  await page.mouse.up(); await page.keyboard.up("Alt"); await page.keyboard.up("Shift");
+  await expect(page.locator("[data-canvas-object]")).toHaveCount(5);
+  await expect(page.locator('[data-canvas-object="rectangle"]')).toHaveAttribute("x", "96");
+  const selected = page.locator('[data-canvas-object][aria-pressed="true"]');
+  expect(Number(await selected.first().getAttribute("y"))).toBeCloseTo(264);
+  await page.keyboard.press("ArrowRight"); await page.keyboard.press("Shift+ArrowDown");
+  expect(Number(await selected.first().getAttribute("x"))).toBeCloseTo(197);
+  expect(Number(await selected.first().getAttribute("y"))).toBeCloseTo(274);
+  await page.keyboard.press("ControlOrMeta+d");
+  await expect(page.locator("[data-canvas-object]")).toHaveCount(7);
+  await page.keyboard.press("ControlOrMeta+c"); await page.keyboard.press("ControlOrMeta+v");
+  await expect(page.locator("[data-canvas-object]")).toHaveCount(9);
+  await expect(selected).toHaveCount(2);
+  await page.keyboard.press("ControlOrMeta+x"); await expect(page.locator("[data-canvas-object]")).toHaveCount(7);
+  await page.keyboard.press("ControlOrMeta+z"); await expect(page.locator("[data-canvas-object]")).toHaveCount(9);
+  await expect(selected).toHaveCount(2);
+});
+
 test("Canvas move and resize are single history steps and Escape cancels a gesture", async ({ page }) => {
   await page.goto("/demo/canvas");
   await create(page, "사각형", [100, 100], [300, 200]);
diff --git a/site/tests/browser/editor-slice-demos.spec.ts b/site/tests/browser/editor-slice-demos.spec.ts
index 75d52205..43277ab4 100644
--- a/site/tests/browser/editor-slice-demos.spec.ts
+++ b/site/tests/browser/editor-slice-demos.spec.ts
@@ -13,7 +13,7 @@ test("Object routes platform history shortcuts from its editing surface", async
   await expect(note).toHaveCSS("background-color", "rgb(77, 106, 138)");
 });
 
-test("Object composes native and toolbar paste with the same placement Intent", async ({ page }) => {
+test("Object uses native clipboard and a separate canonical duplicate command", async ({ page }) => {
   await page.goto("/demo/object");
   const note = page.getByRole("button", { name: "Note" });
   await note.click();
@@ -21,12 +21,12 @@ test("Object composes native and toolbar paste with the same placement Intent",
   await page.getByRole("button", { name: "Card" }).click();
   await page.keyboard.press("ControlOrMeta+V");
   await expect(page.getByRole("button", { name: "Note" })).toHaveCount(2);
-  await page.getByRole("button", { name: "Paste", exact: true }).click();
+  await page.getByRole("button", { name: "Duplicate", exact: true }).click();
   await expect(page.getByRole("button", { name: "Note" })).toHaveCount(3);
   const notes = (await json(page, "object-demo-document")).objects
     .filter((object: { readonly label: string }) => object.label === "Note");
   expect(notes.map((object: { readonly x: number; readonly y: number }) => [object.x, object.y]))
-    .toEqual([[24, 24], [48, 48], [48, 48]]);
+    .toEqual([[24, 24], [48, 48], [72, 72]]);
 });
 
 test("Order repeated select-all and cancelled rename preserve selected items and document history", async ({ page }) => {
diff --git a/site/tests/unit/demo-workbench.test.tsx b/site/tests/unit/demo-workbench.test.tsx
index 6461d390..27319d8f 100644
--- a/site/tests/unit/demo-workbench.test.tsx
+++ b/site/tests/unit/demo-workbench.test.tsx
@@ -65,6 +65,7 @@ describe("Demo definition and source discovery", () => {
       ["packages/json-document-affordance/src/gesture-session.ts", "/docs/api/affordance"],
       ["packages/json-document-selection/src/key/index.ts", "/docs/api/selection"],
       ["packages/json-document-editing/src/object.ts", "/docs/api/editing"],
+      ["packages/json-document-web/src/clipboard.ts", "/docs/api/web"],
       ["packages/json-document-canvas/src/use-canvas-hand.ts", "/docs/api/canvas"],
     ]) {
       const file = sources.find((source) => source.path === path);

From 078bc95368d09782ed056f1d27bfa6bea44a5cc0 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E1=84=8B=E1=85=B2=E1=84=8B=E1=85=AD=E1=86=BC=E1=84=90?=
 =?UTF-8?q?=E1=85=A2?= <teo.v@navercorp.com>
Date: Wed, 9 Sep 2026 20:05:26 +0900
Subject: [PATCH 13/20] =?UTF-8?q?feat(canvas):=20=EC=99=B8=EB=B6=80=20?=
 =?UTF-8?q?=EB=B6=99=EC=97=AC=EB=84=A3=EA=B8=B0=EC=99=80=20=EC=88=9C?=
 =?UTF-8?q?=EC=84=9C=20=EB=B3=B4=EC=9E=A5=20=EC=84=B8=EC=85=98=EC=9D=84=20?=
 =?UTF-8?q?=EC=83=9D=ED=83=9C=EA=B3=84=EC=97=90=20=EC=97=B0=EA=B2=B0?=
 =?UTF-8?q?=ED=95=9C=EB=8B=A4?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 audits/document-types.json                    |   2 +-
 docs/api-reference/canvas.md                  |  19 ++-
 docs/api-reference/editing.md                 |  46 ++++++-
 docs/api-reference/object-document.md         |  15 ++-
 docs/api-reference/web.md                     |  28 ++++-
 package-lock.json                             |   2 +
 packages/json-document-canvas/README.md       |   1 +
 packages/json-document-canvas/docs/api.md     |  32 +++--
 packages/json-document-canvas/package.json    |   2 +
 .../src/canvas-clipboard.ts                   |  74 +++++++++++
 .../json-document-canvas/src/canvas-hand.tsx  |   2 +
 .../src/canvas-object-view.tsx                |   1 +
 packages/json-document-canvas/src/index.ts    |   1 +
 .../src/use-canvas-hand.ts                    |  35 +++---
 .../tests/canvas-clipboard.test.ts            |  86 +++++++++++++
 .../tests/canvas-hand.test.tsx                |  52 +++++++-
 packages/json-document-canvas/tsconfig.json   |   1 +
 .../docs/object-selection.md                  |  44 ++++++-
 .../src/canvas-clipboard.ts                   |  29 +++++
 packages/json-document-editing/src/index.ts   |   2 +
 .../src/object-paste-session.ts               | 100 +++++++++++++++
 packages/json-document-editing/src/object.ts  |  15 ++-
 .../tests/object-paste.test.ts                | 115 ++++++++++++++++++
 .../json-document-object-document/docs/api.md |  15 ++-
 .../src/index.ts                              |   4 +-
 .../src/object-model.ts                       |   3 +-
 .../src/object-projection.ts                  |  15 ++-
 .../src/object-validation.ts                  |  17 ++-
 .../tests/object-document.test.ts             |  15 ++-
 packages/json-document-web/docs/clipboard.md  |  22 ++++
 packages/json-document-web/src/clipboard.ts   |  71 ++++++++---
 packages/json-document-web/src/index.ts       |   4 +-
 .../json-document-web/src/raster-source.ts    |  59 ++++++---
 .../tests/clipboard-paste.test.ts             |  67 ++++++++++
 .../routes/canvas-demo/CanvasDemoRoute.tsx    |   2 +-
 .../routes/object-demo/ObjectDemoRoute.tsx    |   2 +-
 .../src/shared/demo-workbench/demo-sources.ts |  14 ++-
 site/tests/browser/canvas-slice.spec.ts       |  31 +++++
 site/tests/unit/demo-workbench.test.tsx       |   5 +
 39 files changed, 968 insertions(+), 82 deletions(-)
 create mode 100644 packages/json-document-canvas/src/canvas-clipboard.ts
 create mode 100644 packages/json-document-canvas/tests/canvas-clipboard.test.ts
 create mode 100644 packages/json-document-editing/src/canvas-clipboard.ts
 create mode 100644 packages/json-document-editing/src/object-paste-session.ts
 create mode 100644 packages/json-document-editing/tests/object-paste.test.ts
 create mode 100644 packages/json-document-web/tests/clipboard-paste.test.ts

diff --git a/audits/document-types.json b/audits/document-types.json
index 1e2be6da..057820f9 100644
--- a/audits/document-types.json
+++ b/audits/document-types.json
@@ -33,7 +33,7 @@
     "object": {
       "why": "캔버스 object는 identity, geometry와 presentation 값을 하나의 의미 단위로 유지해야 하기 때문입니다.",
       "does": "object의 위치·크기·색상 모델을 정의하고 translate·resize·fill 같은 공간 연산의 기반을 제공합니다.",
-      "schema": "interface DocumentObject {\n  readonly id: string;\n  readonly label: string;\n  readonly x: number;\n  readonly y: number;\n  readonly width: number;\n  readonly height: number;\n  readonly color: string;\n}\n\ninterface ObjectDocument {\n  readonly objects: ReadonlyArray<DocumentObject>;\n}\n\ntype CanvasObject = DocumentObject & (\n  | { kind: \"text\"; fontSize: number }\n  | { kind: \"rectangle\" | \"ellipse\" }\n  | { kind: \"path\"; points: ReadonlyArray<{ x: number; y: number }>; strokeWidth: number }\n);\ninterface CanvasDocument extends ObjectDocument {\n  readonly profile: \"canvas/1\";\n  readonly width: number; readonly height: number;\n  readonly objects: ReadonlyArray<CanvasObject>;\n}",
+      "schema": "interface DocumentObject {\n  readonly id: string;\n  readonly label: string;\n  readonly x: number;\n  readonly y: number;\n  readonly width: number;\n  readonly height: number;\n  readonly color: string;\n}\n\ninterface ObjectDocument {\n  readonly objects: ReadonlyArray<DocumentObject>;\n}\n\ntype CanvasObject = DocumentObject & (\n  | { kind: \"text\"; fontSize: number }\n  | { kind: \"rectangle\" | \"ellipse\" }\n  | { kind: \"path\"; points: ReadonlyArray<{ x: number; y: number }>; strokeWidth: number }\n  | { kind: \"image\"; source: string }\n);\ninterface CanvasDocument extends ObjectDocument {\n  readonly profile: \"canvas/1\";\n  readonly width: number; readonly height: number;\n  readonly objects: ReadonlyArray<CanvasObject>;\n}",
       "fields": [
         { "name": "objects", "description": "같은 공간에서 배치·선택되는 object의 ordered collection입니다." },
         { "name": "objects[].id", "description": "selection, transform과 clipboard가 object를 안정적으로 참조하는 identity입니다." },
diff --git a/docs/api-reference/canvas.md b/docs/api-reference/canvas.md
index ca2496ee..b2159cef 100644
--- a/docs/api-reference/canvas.md
+++ b/docs/api-reference/canvas.md
@@ -6,6 +6,16 @@
 
 > 이 문서는 `packages/json-document-canvas/src/index.ts`에서 생성됩니다. API를 변경한 뒤 `npm run docs:api`를 실행하세요.
 
+## `CanvasClipboardPolicy`
+
+```ts
+interface CanvasClipboardPolicy {
+  readonly textColor: string;
+  readonly fontSize: number;
+  readonly files?: FileAcceptancePolicy;
+  readonly maxImagePixels?: number;
+}
+```
 ## `CanvasCreationStyle`
 
 ```ts
@@ -37,10 +47,15 @@ interface CanvasHandProps {
 ## `CanvasTool`
 
 ```ts
-type CanvasTool = "select" | CanvasObjectKind;
+type CanvasTool = "select" | Exclude<CanvasObjectKind, "image">;
+```
+## `createCanvasClipboardBinding`
+
+```ts
+createCanvasClipboardBinding(editor: ObjectEditor, policy: CanvasClipboardPolicy, options?: { readonly readRaster?: typeof readWebRasterFile; readonly onResult?: (result: { readonly ok: boolean; readonly code?: string; readonly reason?: string; }) => void; readonly onPendingChange?: (pending: boolean) => void; }): { ...; }
 ```
 ## `useCanvasHand`
 
 ```ts
-useCanvasHand(editor: ObjectEditor, style: CanvasCreationStyle, selectProfile?: PlaneSelectProfile): { document: CanvasDocument; snapshot: import("<repository>/packages/json-document-editing/src/session").EditingSnapshot<ObjectSelection>; ... 20 more ...; surfaceProps: { ...; }; }
+useCanvasHand(editor: ObjectEditor, style: CanvasCreationStyle, selectProfile?: PlaneSelectProfile): { document: CanvasDocument; snapshot: import("<repository>/packages/json-document-editing/src/session").EditingSnapshot<ObjectSelection>; ... 21 more ...; surfaceProps: { ...; }; }
 ```
diff --git a/docs/api-reference/editing.md b/docs/api-reference/editing.md
index dbaaa08b..16fb0002 100644
--- a/docs/api-reference/editing.md
+++ b/docs/api-reference/editing.md
@@ -536,6 +536,23 @@ calendarVisibleEvents(document: CalendarDocument): ReadonlyArray<CalendarEvent>
 ```ts
 calendarVisibleHourBand(startMinutes: number, endMinutes: number, hourStart: number, hourEnd: number): { readonly startMinutes: number; readonly endMinutes: number; } | null
 ```
+## `CanvasClipboardContent`
+
+```ts
+type CanvasClipboardContent =
+  | { readonly type: "text"; readonly text: string }
+  | { readonly type: "images"; readonly images: ReadonlyArray<{ readonly source: string; readonly width: number; readonly height: number; readonly label: string }> };
+```
+## `CanvasClipboardOptions`
+
+```ts
+interface CanvasClipboardOptions {
+  readonly bounds: ObjectBounds;
+  readonly textColor: string;
+  readonly fontSize: number;
+  readonly imageOffset?: number;
+}
+```
 ## `createAnnotationEditor`
 
 ```ts
@@ -546,6 +563,11 @@ createAnnotationEditor(source: EditingDocumentSource<AnnotationDocument>, option
 ```ts
 createCalendarEditor(source: EditingDocumentSource<CalendarDocument>, options?: EditingHistoryOptions & { readonly createId?: () => string; readonly initialEventIds?: ReadonlyArray<string>; }): CalendarEditor
 ```
+## `createCanvasClipboard`
+
+```ts
+createCanvasClipboard(content: CanvasClipboardContent, options: CanvasClipboardOptions): ObjectClipboard
+```
 ## `createDatabaseEditor`
 
 ```ts
@@ -581,6 +603,11 @@ createKanbanEditor(source: EditingDocumentSource<KanbanDocument>, options?: Edit
 ```ts
 createObjectEditor(source: EditingDocumentSource<ObjectDocument>, options?: EditingHistoryOptions & { readonly createId?: () => string; }): ObjectEditor
 ```
+## `createObjectPasteSession`
+
+```ts
+createObjectPasteSession(editor: ObjectEditor, options?: { readonly placement?: ObjectPastePlacement; readonly onResult?: (result: EditingResult<ObjectSelection>) => void; readonly onPendingChange?: (pending: boolean) => void; }): ObjectPasteSession
+```
 ## `createOrderEditor`
 
 ```ts
@@ -1260,11 +1287,28 @@ type ObjectIntent =
 
 ```ts
 interface ObjectPastePlacement {
-  readonly type: "offset";
+  readonly type: "offset" | "cascade";
   readonly dx: number;
   readonly dy: number;
 }
 ```
+## `ObjectPastePreparation`
+
+```ts
+type ObjectPastePreparation =
+  | { readonly ok: true; readonly clipboard: ObjectClipboard }
+  | { readonly ok: false; readonly code: string; readonly reason?: string };
+```
+## `ObjectPasteSession`
+
+```ts
+interface ObjectPasteSession {
+  readonly pending: boolean;
+  enqueue(prepare: () => ObjectPastePreparation | Promise<ObjectPastePreparation>, cancelPreparation?: () => void): Promise<EditingResult<ObjectSelection>>;
+  /** Cancels queued work and releases subscriptions. The session can be reused. */
+  cancel(): void;
+}
+```
 ## `ObjectSelection`
 
 ```ts
diff --git a/docs/api-reference/object-document.md b/docs/api-reference/object-document.md
index 43ccda38..f7264869 100644
--- a/docs/api-reference/object-document.md
+++ b/docs/api-reference/object-document.md
@@ -11,6 +11,11 @@ Object 문서와 Canvas 프로파일의 모델·검증·연산·projection의 pu
 ```ts
 assertCanvasDocument(value: unknown): asserts value is CanvasDocument
 ```
+## `assertCanvasImageSource`
+
+```ts
+assertCanvasImageSource(source: unknown): asserts source is string
+```
 ## `assertObjectDocument`
 
 ```ts
@@ -38,17 +43,23 @@ type CanvasObjectDraft = ObjectDraft & (
   | { readonly kind: "text"; readonly fontSize: number }
   | { readonly kind: "rectangle" | "ellipse" }
   | { readonly kind: "path"; readonly points: ReadonlyArray<ObjectPoint>; readonly strokeWidth: number }
+  | { readonly kind: "image"; readonly source: string }
 );
 ```
 ## `CanvasObjectKind`
 
 ```ts
-type CanvasObjectKind = "text" | "rectangle" | "ellipse" | "path";
+type CanvasObjectKind = "text" | "rectangle" | "ellipse" | "path" | "image";
+```
+## `createCanvasImage`
+
+```ts
+createCanvasImage(image: { readonly source: string; readonly width: number; readonly height: number; readonly label: string; }, bounds: ObjectBounds): Extract<CanvasObjectDraft, { readonly kind: "image"; }>
 ```
 ## `createCanvasObject`
 
 ```ts
-createCanvasObject(kind: Exclude<CanvasObjectKind, "path">, bounds: ObjectBounds, style: { readonly color: string; readonly label: string; readonly fontSize?: number; }): CanvasObjectDraft
+createCanvasObject(kind: Exclude<CanvasObjectKind, "path" | "image">, bounds: ObjectBounds, style: { readonly color: string; readonly label: string; readonly fontSize?: number; }): CanvasObjectDraft
 ```
 ## `createCanvasPath`
 
diff --git a/docs/api-reference/web.md b/docs/api-reference/web.md
index b39d5cb4..5d927398 100644
--- a/docs/api-reference/web.md
+++ b/docs/api-reference/web.md
@@ -36,6 +36,11 @@ calendarKeyFromWebRow<Key>(clientX: number, bounds: { readonly left: number; rea
 ```ts
 calendarMinutesFromWebGrid(clientY: number, bounds: { readonly top: number; readonly height: number; }, options: { readonly hourStart: number; readonly hourEnd: number; readonly stepMinutes: number; }): number
 ```
+## `captureWebClipboardPaste`
+
+```ts
+captureWebClipboardPaste<Payload extends WebClipboardPayload>(event: WebClipboardEvent, options: { readonly codec: WebClipboardCodec<Payload>; readonly files?: boolean; readonly text?: boolean; }): WebClipboardPaste<Payload>
+```
 ## `chordFromStroke`
 
 ```ts
@@ -216,7 +221,7 @@ projectWebWidgetState(state: WebWidgetState): WebWidgetARIA
 ## `readWebRasterFile`
 
 ```ts
-readWebRasterFile(file: WebRasterFile): Promise<WebRasterSourceResult>
+readWebRasterFile(file: WebRasterFile, options?: { readonly signal?: WebRasterReadSignal; }): Promise<WebRasterSourceResult>
 ```
 ## `registerWebVirtualSelectionScope`
 
@@ -406,6 +411,7 @@ interface WebClipboardCodec<Payload extends WebClipboardPayload> {
 ```ts
 interface WebClipboardData {
   readonly types: ReadonlyArray<string>;
+  readonly files?: WebFileCandidateList;
   getData(format: string): string;
   setData(format: string, data: string): void;
 }
@@ -418,6 +424,15 @@ interface WebClipboardEvent {
   preventDefault(): void;
 }
 ```
+## `WebClipboardPaste`
+
+```ts
+type WebClipboardPaste<Payload extends WebClipboardPayload> =
+  | { readonly ok: true; readonly type: "structured"; readonly payload: Payload }
+  | { readonly ok: true; readonly type: "files"; readonly files: ReadonlyArray<WebFileCandidate> }
+  | { readonly ok: true; readonly type: "text"; readonly text: string }
+  | Extract<WebClipboardResult<never, never>, { readonly ok: false }>;
+```
 ## `WebClipboardPayload`
 
 ```ts
@@ -769,12 +784,21 @@ interface WebRasterFile {
   readonly type: string;
 }
 ```
+## `WebRasterReadSignal`
+
+```ts
+interface WebRasterReadSignal {
+  readonly aborted: boolean;
+  addEventListener(type: "abort", listener: () => void, options?: { readonly once?: boolean }): void;
+  removeEventListener(type: "abort", listener: () => void): void;
+}
+```
 ## `WebRasterSourceResult`
 
 ```ts
 type WebRasterSourceResult =
   | { readonly ok: true; readonly dataURL: string; readonly width: number; readonly height: number }
-  | { readonly ok: false; readonly code: "raster.read-failed" | "raster.decode-failed"; readonly reason?: string };
+  | { readonly ok: false; readonly code: "raster.read-failed" | "raster.decode-failed" | "raster.cancelled"; readonly reason?: string };
 ```
 ## `WebSVGElement`
 
diff --git a/package-lock.json b/package-lock.json
index a8f330b1..c3ccc2d9 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -6616,6 +6616,7 @@
       "devDependencies": {
         "@interactive-os/json-document-affordance": "*",
         "@interactive-os/json-document-editing": "*",
+        "@interactive-os/json-document-file-intake": "*",
         "@interactive-os/json-document-object-document": "*",
         "@interactive-os/json-document-react": "*",
         "@interactive-os/json-document-ui-primitives-react": "*",
@@ -6632,6 +6633,7 @@
       "peerDependencies": {
         "@interactive-os/json-document-affordance": ">=0.1.0-rc.0 <1",
         "@interactive-os/json-document-editing": ">=0.1.0-rc.0 <1",
+        "@interactive-os/json-document-file-intake": ">=0.1.0-rc.0 <1",
         "@interactive-os/json-document-object-document": ">=0.1.0-rc.0 <1",
         "@interactive-os/json-document-react": ">=0.1.0-rc.0 <1",
         "@interactive-os/json-document-ui-primitives-react": ">=0.1.0-rc.0 <1",
diff --git a/packages/json-document-canvas/README.md b/packages/json-document-canvas/README.md
index 2fb686a7..060f9d37 100644
--- a/packages/json-document-canvas/README.md
+++ b/packages/json-document-canvas/README.md
@@ -5,6 +5,7 @@
 selection/history 구현을 만들지 않고 기존 `createObjectEditor`를 사용합니다.
 재사용 가능한 Plane Select profile로 다중 선택·Alt 복제·Shift 축 고정·방향키 이동을,
 Object Editing과 Web Clipboard로 선택 copy/cut/paste·Mod+D·Undo/Redo를 연결합니다.
+외부 텍스트와 PNG/JPEG/WebP 붙여넣기, 반복 paste 배치와 비동기 취소도 정본 API를 사용합니다.
 
 ```tsx
 import { useState } from "react";
diff --git a/packages/json-document-canvas/docs/api.md b/packages/json-document-canvas/docs/api.md
index 3356a58f..c34432e8 100644
--- a/packages/json-document-canvas/docs/api.md
+++ b/packages/json-document-canvas/docs/api.md
@@ -1,7 +1,7 @@
 ## Canvas Hand 계약 · RC
 
 `CanvasHand`는 `ObjectEditor`와 `CanvasCreationStyle`을 받아 글자·사각형·타원·자유
-그리기, 다중 선택, 집합 이동·복제·삭제, native Clipboard, primary resize, Undo/Redo, JSON 재열기를 연결합니다.
+그리기, 이미지·텍스트 붙여넣기, 다중 선택, 집합 이동·복제·삭제, native Clipboard, primary resize, Undo/Redo, JSON 재열기를 연결합니다.
 `useCanvasHand`는 같은 입력 조합을 custom UI에서 사용할 수 있게 공개합니다.
 
 툴바의 모든 도구·명령은 Lucide 아이콘과 공통 `Toggle`/`Command`의 `label`을
@@ -14,10 +14,11 @@ Host: 한 장 fixture, 크기·색상 정책, 레이아웃
   └─ Canvas Hand: 도구, 조작 preview, plain-text draft, UI 조합
       ├─ React Connector: Editing snapshot 구독
       ├─ Web Adapter: SVG 좌표, pointer capture, keyboard·Clipboard 해석
+      ├─ File Intake: 붙여넣은 파일의 형식·개수·용량 정책 검사
       ├─ Affordance: createPlaneSelectProfile, gesture, resize
       │   └─ Selection: key 집합·primaryKey 전이
       ├─ UI Primitives: handle, icon controls·tooltips
-      └─ Object Editing: Intent, ID 할당, Selection, History
+      └─ Object Editing: Intent, ID 할당, Selection, History, 외부 내용 변환·paste 순서/취소
           ├─ Object Document Type: Canvas profile, 검증, 연산, projection, JSON
           └─ Core: immutable 값과 atomic JSON Patch
 ```
@@ -63,11 +64,28 @@ clipboard는 만들지 않습니다. 복제 버튼은 OS clipboard를 바꾸지
 
 cut은 쓰기에 성공한 캡처 대상만 제거합니다. 쓰기 실패나 Editing 거절은 오류로 드러내고
 문서 삭제나 브라우저 fallback 삭제를 허용하지 않습니다. paste는 새 ID·대응 primary로
-선택하고 원래 좌표에서 x/y 각각 24만큼 offset합니다. 같은 payload를 반복 paste하면
-같은 offset 위치에 새 사본을 만듭니다. text/JSON textarea의 native clipboard는 가로채지 않습니다.
-
-Canvas 표면으로의 외부 plain text/HTML/image paste와 async clipboard 툴바는 아직 지원하지
-않습니다. 지원 MIME이 없거나 payload가 잘못되면 문서를 바꾸지 않고 실패를 표시합니다.
+선택합니다. Editing의 cascade placement로 24/24씩 이동하여 기존 객체와 시작점이 겹치지 않는
+첫 위치를 고릅니다. 객체 간 완전한 충돌 회피나 슬라이드 안 자동 배치는 아닙니다.
+text/JSON textarea의 native clipboard는 가로채지 않습니다.
+
+`createCanvasClipboardBinding(editor, policy, options?)`가 이 연결의 공개 API입니다.
+구조화 Object → 이미지 파일 → 일반 텍스트 순서로 처리하며 잘못된 Object MIME은 문자열로
+조용히 변환하지 않습니다. 외부 문자열은 한 text 객체가 되며 HTML을 실행/보존하지 않고
+줄바꿈·Unicode를 그대로 보존합니다. PNG/JPEG/WebP는 문서 내부 base64 image 객체로 넣습니다.
+기본은 한 paste당 최대 4개, 파일당 10 MiB, decode 후 이미지당 16,000,000픽셀입니다.
+이미지는 비율을 유지해 슬라이드 75% 상자에 맞추고 확대하지 않습니다. 후속 resize는 일반
+객체와 같은 자유 상자 변환입니다. `policy.files`와 `maxImagePixels`로 입력 정책을 지정할 수
+있지만 Object 모델이 지원하지 않는 이미지 표현까지 허용되는 것은 아닙니다.
+
+같은 batch는 순차 decode로 준비하고 모두 성공한 경우만 한 번 삽입합니다. 연속 paste는
+Editing paste session을 통해 입력 순서대로 각각 commit/Undo를 만듭니다. 진행 상태를 표시하고
+Escape·다른 도구/편집·외부 문서/선택·unmount는 준비를 취소합니다. 늦은 완료는 문서를 바꾸거나
+오류 상태를 덮어쓰지 않습니다. `pending`, `cancel()`, `onResult`, `onPendingChange`를 공개하며
+`readRaster`에는 Web API와 호환되는 구체 환경 인스턴스를 주입할 수 있습니다.
+
+이미지도 기존 다중 선택·이동·복제·copy/cut/paste·삭제·Undo/Redo와 JSON 재열기를 사용합니다.
+이미지용 별도 생성 도구, 외부 URL/SVG/HTML import, 이미지 파일 export, asset 서버,
+async clipboard 툴바는 아직 지원하지 않습니다. 표준 MIME이 없는 입력이나 실패는 오류로 드러냅니다.
 
 ### JSON
 
diff --git a/packages/json-document-canvas/package.json b/packages/json-document-canvas/package.json
index f0333f27..50302265 100644
--- a/packages/json-document-canvas/package.json
+++ b/packages/json-document-canvas/package.json
@@ -15,6 +15,7 @@
   },
   "dependencies": { "lucide-react": "^1.33.0" },
   "peerDependencies": {
+    "@interactive-os/json-document-file-intake": ">=0.1.0-rc.0 <1",
     "@interactive-os/json-document-object-document": ">=0.1.0-rc.0 <1",
     "@interactive-os/json-document-editing": ">=0.1.0-rc.0 <1",
     "@interactive-os/json-document-affordance": ">=0.1.0-rc.0 <1",
@@ -24,6 +25,7 @@
     "react": "^18.0.0 || ^19.0.0"
   },
   "devDependencies": {
+    "@interactive-os/json-document-file-intake": "*",
     "@interactive-os/json-document-object-document": "*", "@interactive-os/json-document-editing": "*",
     "@interactive-os/json-document-affordance": "*", "@interactive-os/json-document-web": "*",
     "@interactive-os/json-document-react": "*", "@interactive-os/json-document-ui-primitives-react": "*",
diff --git a/packages/json-document-canvas/src/canvas-clipboard.ts b/packages/json-document-canvas/src/canvas-clipboard.ts
new file mode 100644
index 00000000..ac79bd1e
--- /dev/null
+++ b/packages/json-document-canvas/src/canvas-clipboard.ts
@@ -0,0 +1,74 @@
+import { createCanvasClipboard, createObjectPasteSession, type CanvasClipboardOptions, type EditingResult, type ObjectEditor, type ObjectPastePreparation, type ObjectSelection } from "@interactive-os/json-document-editing";
+import { validateFileCandidates, type FileAcceptancePolicy } from "@interactive-os/json-document-file-intake";
+import { assertCanvasDocument } from "@interactive-os/json-document-object-document";
+import { captureWebClipboardPaste, createWebClipboardBinding, fileCandidatesFromWebFiles, objectClipboardCodec, readWebRasterFile, type WebClipboardEvent, type WebFileCandidate } from "@interactive-os/json-document-web";
+
+export interface CanvasClipboardPolicy {
+  readonly textColor: string;
+  readonly fontSize: number;
+  readonly files?: FileAcceptancePolicy;
+  readonly maxImagePixels?: number;
+}
+
+/** Canvas input composition. File validation, native capture, content conversion, and ordered adoption retain their canonical owners. */
+export function createCanvasClipboardBinding(editor: ObjectEditor, policy: CanvasClipboardPolicy, options: {
+  readonly readRaster?: typeof readWebRasterFile;
+  readonly onResult?: (result: { readonly ok: boolean; readonly code?: string; readonly reason?: string }) => void;
+  readonly onPendingChange?: (pending: boolean) => void;
+} = {}) {
+  const placement = { type: "cascade", dx: 24, dy: 24 } as const;
+  const session = createObjectPasteSession(editor, { placement, ...(options.onResult ? { onResult: options.onResult } : {}), ...(options.onPendingChange ? { onPendingChange: options.onPendingChange } : {}) });
+  const native = createWebClipboardBinding({
+    codec: objectClipboardCodec,
+    read: () => editor.copy(),
+    cut: (payload) => editor.dispatch({ type: "object.remove", objectIds: payload.objects.map((object) => object.id) }),
+    paste: (payload) => editor.dispatch({ type: "clipboard.paste", clipboard: payload, placement }),
+  });
+  const files = policy.files ?? { acceptedMediaTypes: ["image/png", "image/jpeg", "image/webp"], maxFiles: 4, maxBytesPerFile: 10 * 1024 * 1024 };
+  const maxPixels = policy.maxImagePixels ?? 16_000_000;
+  if (!Number.isFinite(maxPixels) || maxPixels <= 0) throw new TypeError("maxImagePixels must be positive and finite.");
+
+  function contentOptions(): CanvasClipboardOptions {
+    const document = editor.snapshot.value;
+    assertCanvasDocument(document);
+    return { bounds: { x: 0, y: 0, width: document.width * 0.75, height: document.height * 0.75 }, textColor: policy.textColor, fontSize: policy.fontSize };
+  }
+  async function images(candidates: readonly WebFileCandidate[], content: CanvasClipboardOptions, signal: AbortSignal): Promise<ObjectPastePreparation> {
+    const accepted = validateFileCandidates(fileCandidatesFromWebFiles(candidates), files);
+    if (!accepted.ok) return accepted;
+    const decoded = [];
+    // Decode a batch sequentially to bound peak memory; adoption remains atomic.
+    for (const file of candidates) {
+      const image = await (options.readRaster ?? readWebRasterFile)(file, { signal });
+      if (!image.ok) return image;
+      if (signal.aborted) return { ok: false, code: "clipboard.cancelled" };
+      if (!Number.isFinite(image.width * image.height) || image.width * image.height > maxPixels) return { ok: false, code: "raster.pixel-limit" };
+      decoded.push({ source: image.dataURL, width: image.width, height: image.height, label: file.name });
+    }
+    return { ok: true, clipboard: createCanvasClipboard({ type: "images", images: decoded }, content) };
+  }
+  return {
+    get pending() { return session.pending; },
+    cancel: () => session.cancel(),
+    copy(event: WebClipboardEvent) {
+      session.cancel();
+      const result = native.copy(event); options.onResult?.(result); return result;
+    },
+    cut(event: WebClipboardEvent) {
+      session.cancel();
+      const result = native.cut(event); options.onResult?.(result); return result;
+    },
+    paste(event: WebClipboardEvent): Promise<EditingResult<ObjectSelection>> {
+      const captured = captureWebClipboardPaste(event, { codec: objectClipboardCodec, files: true, text: true });
+      const controller = new AbortController();
+      return session.enqueue(() => {
+        if (!captured.ok) return captured;
+        if (captured.type === "structured") return { ok: true, clipboard: captured.payload };
+        const content = contentOptions();
+        return captured.type === "text"
+          ? { ok: true, clipboard: createCanvasClipboard({ type: "text", text: captured.text }, content) }
+          : images(captured.files, content, controller.signal);
+      }, () => controller.abort());
+    },
+  };
+}
diff --git a/packages/json-document-canvas/src/canvas-hand.tsx b/packages/json-document-canvas/src/canvas-hand.tsx
index 71ecad71..b9999d46 100644
--- a/packages/json-document-canvas/src/canvas-hand.tsx
+++ b/packages/json-document-canvas/src/canvas-hand.tsx
@@ -40,6 +40,7 @@ export function CanvasHand(props: CanvasHandProps) {
       <Command label="JSON" onClick={() => { hand.commitText(); hand.cancel(); setJSON(json === null ? serializeCanvasDocument(props.editor.snapshot.value as typeof hand.document) : null); }}><Braces aria-hidden="true" size={16} /></Command>
     </ToolbarGroup>}>
       <svg ref={hand.surface} {...hand.surfaceProps} tabIndex={0} role="group" aria-label={props.label ?? "Canvas slide"}
+        aria-busy={hand.pastePending}
         data-canvas-slide="true" data-tool={hand.tool} viewBox={`0 0 ${hand.document.width} ${hand.document.height}`} preserveAspectRatio="none"
         style={{ display: "block", width: "100%", aspectRatio: `${hand.document.width} / ${hand.document.height}`, touchAction: "none", userSelect: "none", overflow: "hidden", ...props.slideStyle }}>
         {hand.objects.map((object) => <g key={object.id} data-canvas-copy-original={copyOriginals.has(object.id) ? object.id : undefined}>
@@ -59,6 +60,7 @@ export function CanvasHand(props: CanvasHandProps) {
         {selected?.kind === "text" && hand.draft?.id === selected.id && <CanvasTextInput object={selected} text={hand.draft.text} onChange={hand.changeText}
           onCommit={() => { hand.commitText(); hand.surface.current?.focus(); }} onCancel={() => { hand.cancel(); hand.surface.current?.focus(); }} />}
       </svg>
+      {hand.pastePending && <p role="status">붙여넣는 중… Escape로 취소</p>}
       {hand.error && <p role="alert">{hand.error}</p>}
       {json !== null && <section aria-label="Canvas JSON">
         <Field multiline label="Canvas JSON document" value={json} onValueChange={setJSON} rows={10} spellCheck={false} style={{ width: "100%", fontFamily: "monospace" }} />
diff --git a/packages/json-document-canvas/src/canvas-object-view.tsx b/packages/json-document-canvas/src/canvas-object-view.tsx
index e67cfa38..2783a651 100644
--- a/packages/json-document-canvas/src/canvas-object-view.tsx
+++ b/packages/json-document-canvas/src/canvas-object-view.tsx
@@ -4,6 +4,7 @@ import type { InteractionHandleEvent, ResizeEdge } from "@interactive-os/json-do
 import { contentInteractionAttributes, Field, useInteractionHandle } from "@interactive-os/json-document-ui-primitives-react";
 
 export function CanvasObjectView({ object }: { readonly object: CanvasObject }): ReactNode {
+  if (object.kind === "image") return <image href={object.source} x={object.x} y={object.y} width={object.width} height={object.height} preserveAspectRatio="none" />;
   if (object.kind === "path") {
     return <polyline points={object.points.map((point) => `${object.x + point.x * object.width},${object.y + point.y * object.height}`).join(" ")} fill="none" stroke={object.color} strokeWidth={object.strokeWidth} strokeLinecap="round" strokeLinejoin="round" />;
   }
diff --git a/packages/json-document-canvas/src/index.ts b/packages/json-document-canvas/src/index.ts
index 4c1de4e6..4a7e72cf 100644
--- a/packages/json-document-canvas/src/index.ts
+++ b/packages/json-document-canvas/src/index.ts
@@ -1,2 +1,3 @@
 export { CanvasHand, type CanvasHandProps } from "./canvas-hand.js";
+export { createCanvasClipboardBinding, type CanvasClipboardPolicy } from "./canvas-clipboard.js";
 export { useCanvasHand, type CanvasTool, type CanvasCreationStyle } from "./use-canvas-hand.js";
diff --git a/packages/json-document-canvas/src/use-canvas-hand.ts b/packages/json-document-canvas/src/use-canvas-hand.ts
index 7ab3f1e4..d8721998 100644
--- a/packages/json-document-canvas/src/use-canvas-hand.ts
+++ b/packages/json-document-canvas/src/use-canvas-hand.ts
@@ -3,9 +3,10 @@ import { createGestureSession, createPlaneSelectProfile, resizeAffordance, type
 import { assertCanvasDocument, createCanvasObject, createCanvasPath, parseCanvasDocument, transformObject, type CanvasDocument, type CanvasObject, type CanvasObjectKind, type ObjectPoint } from "@interactive-os/json-document-object-document";
 import type { EditingResult, ObjectEditor, ObjectIntent, ObjectSelection } from "@interactive-os/json-document-editing";
 import { useEditingSnapshot } from "@interactive-os/json-document-react";
-import { createWebClipboardBinding, createWebKeyboardAdapter, createWebPointerSession, isWebEditableTarget, objectClipboardCodec, projectWebClientPointToSVG, webSVGViewportFromElement } from "@interactive-os/json-document-web";
+import { createWebKeyboardAdapter, createWebPointerSession, isWebEditableTarget, projectWebClientPointToSVG, webSVGViewportFromElement } from "@interactive-os/json-document-web";
+import { createCanvasClipboardBinding } from "./canvas-clipboard.js";
 
-export type CanvasTool = "select" | CanvasObjectKind;
+export type CanvasTool = "select" | Exclude<CanvasObjectKind, "image">;
 export interface CanvasCreationStyle {
   readonly color: string;
   readonly textColor: string;
@@ -14,7 +15,7 @@ export interface CanvasCreationStyle {
 }
 
 type Gesture = { readonly base: CanvasDocument } & (
-  | { readonly type: "create"; readonly tool: Exclude<CanvasObjectKind, "path">; readonly start: ObjectPoint; readonly point: ObjectPoint }
+  | { readonly type: "create"; readonly tool: Exclude<CanvasObjectKind, "path" | "image">; readonly start: ObjectPoint; readonly point: ObjectPoint }
   | { readonly type: "draw"; readonly points: ReadonlyArray<ObjectPoint> }
   | { readonly type: "resize"; readonly object: CanvasObject; readonly start: ObjectPoint; readonly point: ObjectPoint; readonly edge: ResizeEdge }
 );
@@ -34,12 +35,10 @@ export function useCanvasHand(editor: ObjectEditor, style: CanvasCreationStyle,
   const draft = useRef<TextDraft | null>(null);
   const selecting = useRef<{ readonly base: CanvasDocument; readonly selection: ObjectSelection; readonly pointerId: number; readonly key: string | null } | null>(null);
   const profile = useMemo(() => selectProfile ?? createPlaneSelectProfile(), [editor, selectProfile]);
-  const clipboard = useMemo(() => createWebClipboardBinding({
-    codec: objectClipboardCodec,
-    read: () => editor.copy(),
-    cut: (payload) => editor.dispatch({ type: "object.remove", objectIds: payload.objects.map((object) => object.id) }),
-    paste: (payload) => editor.dispatch({ type: "clipboard.paste", clipboard: payload, placement: { type: "offset", dx: 24, dy: 24 } }),
-  }), [editor]);
+  const clipboard = useMemo(() => createCanvasClipboardBinding(editor, { textColor: style.textColor, fontSize: style.fontSize }, {
+    onResult(result) { setError(result.ok ? null : result.reason ?? result.code ?? null); if (result.ok) setTool("select"); },
+    onPendingChange: redraw,
+  }), [editor, style.textColor, style.fontSize]);
   const gestures = useMemo(() => createGestureSession<Gesture>({ onBegin: redraw, onPreview: redraw, onCommit: redraw, onCancel: redraw }), [editor]);
   const pointer = useMemo(() => createWebPointerSession<true>({ onCancel: (_, reason) => {
     gestures.cancel(reason === "lost-capture" ? "lost-capture" : "pointer-cancel");
@@ -52,7 +51,7 @@ export function useCanvasHand(editor: ObjectEditor, style: CanvasCreationStyle,
     return value;
   }
 
-  function cancel() {
+  function cancelInteraction() {
     const active = pointer.getSnapshot();
     if (active) pointer.cancel(active.pointerId);
     gestures.cancel();
@@ -61,6 +60,8 @@ export function useCanvasHand(editor: ObjectEditor, style: CanvasCreationStyle,
     redraw();
   }
 
+  function cancel() { clipboard.cancel(); cancelInteraction(); }
+
   useEffect(() => {
     // A replacement/external edit invalidates previews, even when an ID survives.
     const release = editor.subscribe((next) => {
@@ -70,13 +71,14 @@ export function useCanvasHand(editor: ObjectEditor, style: CanvasCreationStyle,
     });
     return () => {
       release();
+      clipboard.cancel();
       const active = pointer.getSnapshot();
       if (active) pointer.cancel(active.pointerId);
       gestures.cancel();
       profile.cancel(); selecting.current = null;
       draft.current = null;
     };
-  }, [editor, gestures, pointer, profile]);
+  }, [editor, gestures, pointer, profile, clipboard]);
 
   function report(result: EditingResult<ObjectSelection>) {
     setError(result.ok ? null : result.reason ?? result.code);
@@ -227,10 +229,9 @@ export function useCanvasHand(editor: ObjectEditor, style: CanvasCreationStyle,
 
   function handleClipboard(operation: "copy" | "cut" | "paste", event: ClipboardEvent) {
     if (isWebEditableTarget(event.target)) return;
-    cancel();
-    const result = clipboard[operation](event);
-    setError(result.ok ? null : result.reason ?? result.code);
-    if (result.ok) setTool("select");
+    cancelInteraction();
+    setError(null);
+    void clipboard[operation](event);
   }
 
   function updateModifiers(event: KeyboardEvent) {
@@ -240,7 +241,7 @@ export function useCanvasHand(editor: ObjectEditor, style: CanvasCreationStyle,
   function keyDown(event: KeyboardEvent) {
     if (event.nativeEvent.isComposing || isWebEditableTarget(event.target)) return;
     updateModifiers(event);
-    const selectedAction = profile.keyDown(event, selectContext(), gestures.getActive() !== null || draft.current !== null);
+    const selectedAction = profile.keyDown(event, selectContext(), gestures.getActive() !== null || draft.current !== null || clipboard.pending);
     if (selectedAction) {
       event.preventDefault();
       cancel();
@@ -269,7 +270,7 @@ export function useCanvasHand(editor: ObjectEditor, style: CanvasCreationStyle,
   const preview = gesture && (gesture.type === "create" || gesture.type === "draw") ? createPreview(gesture) : null;
 
   return {
-    document, snapshot, selection, marquee: selectionPreview?.marquee ?? null, objects, copyOriginals, preview, surface, tool, error, draft: draft.current,
+    document, snapshot, selection, marquee: selectionPreview?.marquee ?? null, objects, copyOriginals, preview, surface, tool, error, pastePending: clipboard.pending, draft: draft.current,
     choose, select, interaction, editText, commitText, cancel, remove, duplicate, history,
     changeText(text: string) { if (draft.current) { draft.current = { ...draft.current, text }; redraw(); } },
     openJSON(json: string) {
diff --git a/packages/json-document-canvas/tests/canvas-clipboard.test.ts b/packages/json-document-canvas/tests/canvas-clipboard.test.ts
new file mode 100644
index 00000000..2f2627f7
--- /dev/null
+++ b/packages/json-document-canvas/tests/canvas-clipboard.test.ts
@@ -0,0 +1,86 @@
+import { expect, test, vi } from "vitest";
+import { createJSONDocument } from "@interactive-os/json-document";
+import { createObjectEditor } from "@interactive-os/json-document-editing";
+import { parseCanvasDocument, serializeCanvasDocument, type CanvasDocument } from "@interactive-os/json-document-object-document";
+import { objectClipboardCodec, type readWebRasterFile, type WebClipboardData, type WebRasterSourceResult } from "@interactive-os/json-document-web";
+import { createCanvasClipboardBinding } from "../src/index.js";
+
+const blank: CanvasDocument = { profile: "canvas/1", width: 1280, height: 720, objects: [] };
+const style = { textColor: "black", fontSize: 32 };
+const png = "data:image/png;base64,AQID";
+const file = { name: "picture.png", size: 3, type: "image/png" };
+function event(files = [] as typeof file[], values: Record<string, string> = {}) {
+  const data: WebClipboardData = { files, get types() { return Object.keys(values); }, getData: (type) => values[type] ?? "", setData: (type, value) => { values[type] = value; } };
+  return { clipboardData: data, preventDefault: vi.fn() };
+}
+function setup(readRaster: typeof readWebRasterFile = vi.fn(async (): Promise<WebRasterSourceResult> => ({ ok: true, dataURL: png, width: 1600, height: 800 }))) {
+  let id = 0;
+  const document = createJSONDocument(blank), editor = createObjectEditor(document, { createId: () => `image-${++id}` });
+  const commits = vi.fn(), onResult = vi.fn(); document.subscribe(commits);
+  const binding = createCanvasClipboardBinding(editor, style, { readRaster, onResult });
+  return { editor, binding, readRaster, onResult, commits, value: () => editor.snapshot.value as CanvasDocument };
+}
+
+test("image batch is one commit with decoded fit, fresh IDs, primary, native copy and JSON round-trip", async () => {
+  const { binding, editor, value, commits } = setup();
+  const pasted = event([file, { ...file, name: "second.png" }], { "text/plain": "image fallback" });
+  const pending = binding.paste(pasted);
+  expect(pasted.preventDefault).toHaveBeenCalledOnce(); expect(binding.pending).toBe(true); expect(commits).not.toHaveBeenCalled();
+  expect((await pending).ok).toBe(true);
+  expect(value().objects.map((object) => [object.kind, object.x, object.y, object.width, object.height, object.source])).toEqual([
+    ["image", 24, 24, 960, 480, png], ["image", 48, 48, 960, 480, png],
+  ]);
+  expect(editor.snapshot.selection).toMatchObject({ keys: ["image-1", "image-2"], primaryKey: "image-2" });
+  expect(parseCanvasDocument(serializeCanvasDocument(value()))).toEqual(value());
+  expect(commits).toHaveBeenCalledOnce();
+  const copied = event(); binding.copy(copied);
+  editor.undo(); expect(value()).toEqual(blank);
+  await binding.paste(copied); expect(value().objects).toHaveLength(2); expect(editor.snapshot.selection.keys).toEqual(["image-3", "image-4"]);
+  expect(value().objects[0]!.source).toBe(png);
+  editor.dispatch({ type: "object.translate", objectIds: editor.snapshot.selection.keys, dx: 10, dy: 10 });
+  editor.dispatch({ type: "object.resize", objectIds: ["image-4"], dx: 0, dy: 0, dw: 20, dh: 10 });
+  editor.dispatch({ type: "object.duplicate", objectIds: editor.snapshot.selection.keys });
+  expect(value().objects.at(-1)!.source).toBe(png);
+  editor.dispatch({ type: "selection.remove" }); expect(value().objects).toHaveLength(2);
+});
+
+test.each([
+  { files: [{ ...file, type: "image/svg+xml" }], code: "file-intake.media-type" },
+  { files: [{ ...file, size: 11 * 1024 * 1024 }], code: "file-intake.size" },
+  { files: Array.from({ length: 5 }, () => file), code: "file-intake.limit" },
+])("$code rejects before reading any bytes", async ({ files, code }) => {
+  const { binding, readRaster, value } = setup();
+  expect(await binding.paste(event(files))).toMatchObject({ ok: false, code });
+  expect(readRaster).not.toHaveBeenCalled(); expect(value()).toEqual(blank);
+});
+
+test.each(["raster.decode-failed", "raster.pixel-limit"])("%s rejects the entire image batch without IDs/history or partial insertion", async (code) => {
+  const readRaster = vi.fn<() => Promise<WebRasterSourceResult>>()
+    .mockResolvedValueOnce({ ok: true, dataURL: png, width: 100, height: 100 })
+    .mockResolvedValueOnce(code === "raster.decode-failed" ? { ok: false, code } : { ok: true, dataURL: png, width: 5000, height: 5000 });
+  const { binding, value, editor, onResult } = setup(readRaster);
+  expect(await binding.paste(event([file, file]))).toMatchObject({ ok: false, code });
+  expect(value()).toEqual(blank); expect(editor.snapshot.canUndo).toBe(false); expect(onResult).toHaveBeenCalledOnce();
+  await binding.paste(event([], { "text/plain": "After failure" })); expect(value().objects[0]!.id).toBe("image-1");
+});
+
+test("plain text is literal and synchronous, repeats cascade; malformed structured payload never degrades to text", async () => {
+  const { binding, value, readRaster } = setup();
+  const text = event([], { "text/plain": "<b>안녕</b>\nCanvas" });
+  const first = binding.paste(text); expect(value().objects).toHaveLength(1); await first;
+  await binding.paste(text); expect(value().objects.map((object) => object.x)).toEqual([24, 48]);
+  expect(value().objects[0]).toMatchObject({ kind: "text", label: "<b>안녕</b>\nCanvas" });
+  expect(await binding.paste(event([file], { [objectClipboardCodec.mimeType]: "{", "text/plain": "Fallback" }))).toMatchObject({ ok: false, code: "clipboard.invalid" });
+  expect(value().objects).toHaveLength(2); expect(readRaster).not.toHaveBeenCalled();
+});
+
+test("cancellation aborts platform preparation; later resolution cannot commit or notify", async () => {
+  let resolve!: (result: WebRasterSourceResult) => void;
+  const readRaster = vi.fn<typeof readWebRasterFile>(() => new Promise<WebRasterSourceResult>((done) => { resolve = done; }));
+  const { binding, value, onResult } = setup(readRaster);
+  const pending = binding.paste(event([file]));
+  binding.cancel(); expect(await pending).toMatchObject({ ok: false, code: "clipboard.cancelled" });
+  expect(readRaster.mock.calls[0]?.[1]?.signal?.aborted).toBe(true);
+  resolve({ ok: true, dataURL: png, width: 100, height: 100 }); await Promise.resolve();
+  expect(value()).toEqual(blank); expect(onResult).not.toHaveBeenCalled();
+});
diff --git a/packages/json-document-canvas/tests/canvas-hand.test.tsx b/packages/json-document-canvas/tests/canvas-hand.test.tsx
index d26ba35e..5808a26f 100644
--- a/packages/json-document-canvas/tests/canvas-hand.test.tsx
+++ b/packages/json-document-canvas/tests/canvas-hand.test.tsx
@@ -5,6 +5,7 @@ import { createObjectEditor } from "@interactive-os/json-document-editing";
 import type { CanvasDocument } from "@interactive-os/json-document-object-document";
 import { CanvasHand } from "../src/index.js";
 import { createPlaneSelectProfile } from "@interactive-os/json-document-affordance";
+import * as web from "@interactive-os/json-document-web";
 
 const blank: CanvasDocument = { profile: "canvas/1", width: 1280, height: 720, objects: [] };
 const style = { color: "#abcdef", textColor: "#123456", fontSize: 32, strokeWidth: 3 };
@@ -16,7 +17,7 @@ beforeAll(() => {
   Element.prototype.hasPointerCapture = function (id) { return captures.get(this) === id; };
   Element.prototype.releasePointerCapture = function () { captures.delete(this); };
 });
-afterEach(cleanup);
+afterEach(() => { cleanup(); vi.restoreAllMocks(); });
 
 function setup(document = blank, selectProfile = createPlaneSelectProfile()) {
   const source = createJSONDocument(document);
@@ -82,6 +83,55 @@ test("Alt+Shift drag previews originals and copies, switches live modifiers, the
   expect(editor.snapshot.selection).toMatchObject({ keys: ["a", "b"], primaryKey: "a" });
 });
 
+test("external text paste is literal, repeated placement is visible, and editing retains the native field boundary", () => {
+  const { svg, container, value } = setup();
+  const data = clipboardData(); data.setData("text/plain", "<b>한글</b>\nSecond line");
+  expect(clipboardEvent(svg, "paste", data).defaultPrevented).toBe(true);
+  clipboardEvent(svg, "paste", data);
+  expect(value().objects.map((object) => [object.kind, object.x, object.y])).toEqual([["text", 24, 24], ["text", 48, 48]]);
+  expect(container.querySelector("foreignObject b")).toBeNull();
+  const text = container.querySelector('[data-canvas-object="object-2"]')!;
+  fireEvent.doubleClick(text);
+  const input = screen.getByRole("textbox", { name: "Canvas text" });
+  expect(clipboardEvent(input, "paste", data).defaultPrevented).toBe(false);
+  expect(value().objects).toHaveLength(2);
+});
+
+test("image paste reaches the SVG renderer and existing duplication, Undo, and JSON reopening", async () => {
+  const png = "data:image/png;base64,AQID";
+  vi.spyOn(web, "readWebRasterFile").mockResolvedValue({ ok: true, dataURL: png, width: 1600, height: 800 });
+  const { svg, container, value } = setup();
+  const data = { ...clipboardData(), files: [{ name: "picture.png", type: "image/png", size: 3 }] };
+  await act(async () => { clipboardEvent(svg, "paste", data); });
+  expect(container.querySelector("image")?.getAttribute("href")).toBe(png);
+  expect(value().objects[0]).toMatchObject({ kind: "image", width: 960, height: 480 });
+  fireEvent.keyDown(svg, { key: "d", metaKey: true }); expect(container.querySelectorAll("image")).toHaveLength(2);
+  fireEvent.keyDown(svg, { key: "z", metaKey: true }); expect(container.querySelectorAll("image")).toHaveLength(1);
+  fireEvent.click(screen.getByRole("button", { name: "JSON" }));
+  const json = screen.getByRole("textbox", { name: "Canvas JSON document" }) as HTMLTextAreaElement;
+  expect(JSON.parse(json.value).objects[0].source).toBe(png);
+  fireEvent.click(screen.getByRole("button", { name: "JSON 열기" }));
+  expect(container.querySelector("image")?.getAttribute("href")).toBe(png);
+});
+
+test.each(["Escape", "tool", "selection", "unmount"])("pending image paste is cancelled by %s and cannot arrive after the action", async (reason) => {
+  let resolve!: (result: web.WebRasterSourceResult) => void;
+  const read = vi.spyOn(web, "readWebRasterFile").mockImplementation(() => new Promise((done) => { resolve = done; }));
+  const { svg, editor, unmount, value, commits } = setup(populated);
+  const data = { ...clipboardData(), files: [{ name: "picture.png", type: "image/png", size: 3 }] };
+  clipboardEvent(svg, "paste", data);
+  expect(svg.getAttribute("aria-busy")).toBe("true"); expect(screen.getByRole("status").textContent).toContain("Escape");
+  if (reason === "Escape") fireEvent.keyDown(svg, { key: "Escape" });
+  else if (reason === "tool") fireEvent.click(screen.getByRole("button", { name: "사각형" }));
+  else if (reason === "selection") act(() => { editor.dispatch({ type: "selection.set", objectIds: ["b"] }); });
+  else unmount();
+  expect(read.mock.calls[0]?.[1]?.signal?.aborted).toBe(true);
+  await act(async () => { resolve({ ok: true, dataURL: "data:image/png;base64,AQID", width: 100, height: 100 }); });
+  expect(value()).toEqual(populated); expect(commits).not.toHaveBeenCalled();
+  if (reason === "Escape") expect(editor.snapshot.selection.keys).toEqual(["a"]);
+  if (reason !== "unmount") expect(screen.queryByRole("status")).toBeNull();
+});
+
 test.each(["Escape", "pointercancel"])("cancelled Alt duplication (%s) does not allocate IDs or commit", (reason) => {
   const { container, svg, editor, value, commits } = setup(populated);
   const target = container.querySelector('[data-canvas-object="a"]')!;
diff --git a/packages/json-document-canvas/tsconfig.json b/packages/json-document-canvas/tsconfig.json
index 36205524..d561a035 100644
--- a/packages/json-document-canvas/tsconfig.json
+++ b/packages/json-document-canvas/tsconfig.json
@@ -2,6 +2,7 @@
   "extends": "../../tsconfig/library-react.json",
   "compilerOptions": { "rootDir": "src", "outDir": "dist", "tsBuildInfoFile": "dist/.tsbuildinfo" },
   "references": [
+    { "path": "../json-document-file-intake" },
     { "path": "../json-document-object-document" }, { "path": "../json-document-editing" },
     { "path": "../json-document-affordance" }, { "path": "../json-document-web" },
     { "path": "../json-document-react" }, { "path": "../json-document-ui-primitives-react" }
diff --git a/packages/json-document-editing/docs/object-selection.md b/packages/json-document-editing/docs/object-selection.md
index 13bc97e8..5c4adc42 100644
--- a/packages/json-document-editing/docs/object-selection.md
+++ b/packages/json-document-editing/docs/object-selection.md
@@ -31,8 +31,12 @@ Intent를 사용합니다. Undo/Redo는 해당 문서 변경과 함께 원인 
 없으면 마지막 사본이 primary입니다. 반복 복제는 새 선택을 대상으로 같은 offset을 적용합니다.
 
 `clipboard.paste`도 같은 ID 할당·변환·insert 경로를 사용합니다. placement 생략은 기존대로
-zero offset입니다. Object/Canvas Hand의 native paste는 제품 정책으로 24단위 offset을
-전달합니다. 같은 payload의 반복 paste는 같은 위치에 새 ID로 삽입하며 자동 cascade는 하지 않습니다.
+zero offset입니다. `{ type: "offset", dx, dy }`는 명시 좌표를 유지하고,
+`{ type: "cascade", dx, dy }`는 첫 source 객체의 시작점에 1배, 2배… delta를 적용하여
+기존 객체의 시작점과 일치하지 않는 첫 위치를 찾습니다. 모든 사본에 같은 delta를 적용합니다.
+Object/Canvas native paste는 cascade 24/24를 사용합니다. Undo/삭제 후에는 빈 위치를
+재사용하므로 횟수 counter가 없습니다. 직사각형 충돌 회피·snap·슬라이드 내부 배치는 아닙니다.
+0/0 cascade, 비유한 delta, 계산 overflow는 거절합니다. 기존 offset API는 그대로입니다.
 
 `ObjectClipboard`는 구조화 MIME `application/vnd.interactive-os.objects+json`, `objects`,
 `text`와 선택적인 `primaryKey`를 갖습니다. `copy()`는 문서 순서의 객체·label을 결합한 text와
@@ -54,3 +58,39 @@ if (captured) editor.dispatch({ type: "object.remove", objectIds: captured.objec
 복제·paste·remove는 명령당 하나의 commit/Undo입니다. ID 할당 불가, 잘못된 offset이나
 payload, 대상/프로파일 위반은 부분 문서·선택·History를 남기지 않습니다. Canvas의 strict
 profile은 generic Object clipboard라도 결과가 유효한 경우만 삽입합니다.
+
+### 외부 Canvas 내용과 비동기 paste
+
+`createCanvasClipboard(content, options)`는 `{ type: "text", text }` 또는
+`{ type: "images", images: [{ source, width, height, label }] }`를 ObjectClipboard로 바꿉니다.
+문자열은 줄바꿈과 Unicode를 보존하며 HTML로 해석하지 않습니다. 텍스트의 초기 상자는 bounds와
+fontSize로 결정하고, 이미지는 Object Document Type의 `createCanvasImage`로 맞춥니다.
+여러 이미지는 `imageOffset`(기본 24)만큼 분산합니다. `clipboard:0` 같은 임시 source ID는
+payload 내부 식별자일 뿐이며 실제 문서 ID는 paste commit 때만 할당합니다.
+
+```ts
+import { createCanvasClipboard, createObjectPasteSession } from "@interactive-os/json-document-editing";
+
+const pastes = createObjectPasteSession(editor, {
+  placement: { type: "cascade", dx: 24, dy: 24 },
+  onResult: showEditingResult,
+  onPendingChange: showPending,
+});
+pastes.enqueue(() => ({ ok: true, clipboard: createCanvasClipboard({ type: "text", text: "안녕\nCanvas" }, {
+  bounds: { x: 0, y: 0, width: 960, height: 540 }, textColor: "black", fontSize: 36,
+}) }));
+```
+
+`enqueue(prepare, cancelPreparation?)`는 동기 결과 또는 Promise를 받아 요청 순서로
+채택합니다. 준비 결과는 `{ ok: true, clipboard }` 또는 `{ ok: false, code, reason? }`입니다.
+준비는 병행할 수 있지만 앞 요청이 끝나기 전에 뒤 요청이 commit되지 않습니다. 실패한 요청은
+문서·ID·History를 만들지 않으며 다음 요청을 막지 않습니다. 동기 payload는 대기 요청이 없으면
+동기 commit하고 반환 Promise는 해당 EditingResult로 완료됩니다.
+
+`pending`, `onPendingChange`, `onResult`로 상태/결과를 관찰합니다. 외부 문서·선택 변경과
+`cancel()`은 대기 전체를 `clipboard.cancelled`로 완료하고 취소 callback을 부릅니다.
+취소된 작업의 늦은 결과는 commit/`onResult`를 호출하지 않습니다. `cancel()`은 구독을
+해제하며 같은 session을 다시 사용할 수 있으므로 Hand cleanup에서도 호출합니다.
+이 세션은 DOM, React, FileReader를 모르고 Canvas에 한정되지 않습니다.
+
+실제 연결은 [Canvas Usage/Source](/demo/canvas)의 Canvas Clipboard binding에서 볼 수 있습니다.
diff --git a/packages/json-document-editing/src/canvas-clipboard.ts b/packages/json-document-editing/src/canvas-clipboard.ts
new file mode 100644
index 00000000..39756af9
--- /dev/null
+++ b/packages/json-document-editing/src/canvas-clipboard.ts
@@ -0,0 +1,29 @@
+import { createCanvasImage, createCanvasObject, type ObjectBounds } from "@interactive-os/json-document-object-document";
+import { objectClipboardFormat, type ObjectClipboard } from "./object.js";
+
+export type CanvasClipboardContent =
+  | { readonly type: "text"; readonly text: string }
+  | { readonly type: "images"; readonly images: ReadonlyArray<{ readonly source: string; readonly width: number; readonly height: number; readonly label: string }> };
+
+export interface CanvasClipboardOptions {
+  readonly bounds: ObjectBounds;
+  readonly textColor: string;
+  readonly fontSize: number;
+  readonly imageOffset?: number;
+}
+
+/** External content → domain clipboard. No platform objects, document IDs, or history writes. */
+export function createCanvasClipboard(content: CanvasClipboardContent, options: CanvasClipboardOptions): ObjectClipboard {
+  const { bounds } = options;
+  const offset = options.imageOffset ?? 24;
+  if (![bounds.x, bounds.y, offset].every(Number.isFinite)
+    || ![bounds.width, bounds.height, options.fontSize].every((value) => Number.isFinite(value) && value > 0)) throw new TypeError("Canvas clipboard geometry and font size must be valid.");
+  if ((content.type === "text" && content.text.length === 0) || (content.type === "images" && content.images.length === 0)) throw new TypeError("Canvas clipboard must not be empty.");
+  const drafts = content.type === "text"
+    ? [createCanvasObject("text", { ...bounds, height: Math.min(bounds.height, Math.max(1, content.text.split("\n").length) * options.fontSize * 1.2) }, { color: options.textColor, fontSize: options.fontSize, label: content.text })]
+    : content.images.map((image, index) => createCanvasImage(image, { ...bounds, x: bounds.x + index * offset, y: bounds.y + index * offset }));
+  const objects = drafts.map((object, index) => ({ ...object, id: `clipboard:${index}` }));
+  const payload: ObjectClipboard = { type: objectClipboardFormat.mimeType, objects, text: objects.map((object) => object.label).join("\n"), primaryKey: objects.at(-1)!.id };
+  if (!objectClipboardFormat.parse(payload)) throw new TypeError("Invalid Canvas clipboard content.");
+  return payload;
+}
diff --git a/packages/json-document-editing/src/index.ts b/packages/json-document-editing/src/index.ts
index 830826bf..199b7f9b 100644
--- a/packages/json-document-editing/src/index.ts
+++ b/packages/json-document-editing/src/index.ts
@@ -28,6 +28,8 @@ export type { GridPoint, GridRangeBounds, GridTopology, LineTopology } from "./t
 export { createDatabaseEditor, databaseClipboardFormat, nextDatabasePropertySort } from "./database.js";
 export { acceptsDatabaseValue, databaseValueFromText, defaultDatabaseValue } from "./database-property-value.js";
 export { createObjectEditor, objectClipboardFormat } from "./object.js";
+export { createCanvasClipboard, type CanvasClipboardContent, type CanvasClipboardOptions } from "./canvas-clipboard.js";
+export { createObjectPasteSession, type ObjectPasteSession, type ObjectPastePreparation } from "./object-paste-session.js";
 export { createOrderEditor, orderClipboardFormat } from "./order.js";
 export { createEditingSession } from "./session.js";
 export { createEditingId, createEditingIdAllocator } from "./identity.js";
diff --git a/packages/json-document-editing/src/object-paste-session.ts b/packages/json-document-editing/src/object-paste-session.ts
new file mode 100644
index 00000000..2121cbb8
--- /dev/null
+++ b/packages/json-document-editing/src/object-paste-session.ts
@@ -0,0 +1,100 @@
+import type { EditingResult } from "./session.js";
+import type { ObjectClipboard, ObjectEditor, ObjectPastePlacement, ObjectSelection } from "./object.js";
+
+export type ObjectPastePreparation =
+  | { readonly ok: true; readonly clipboard: ObjectClipboard }
+  | { readonly ok: false; readonly code: string; readonly reason?: string };
+
+export interface ObjectPasteSession {
+  readonly pending: boolean;
+  enqueue(prepare: () => ObjectPastePreparation | Promise<ObjectPastePreparation>, cancelPreparation?: () => void): Promise<EditingResult<ObjectSelection>>;
+  /** Cancels queued work and releases subscriptions. The session can be reused. */
+  cancel(): void;
+}
+
+/** Ordered, atomic paste adoption. External document/selection changes invalidate pending work. */
+export function createObjectPasteSession(editor: ObjectEditor, options: {
+  readonly placement?: ObjectPastePlacement;
+  readonly onResult?: (result: EditingResult<ObjectSelection>) => void;
+  readonly onPendingChange?: (pending: boolean) => void;
+} = {}): ObjectPasteSession {
+  type Job = { result?: ObjectPastePreparation; resolve: (result: EditingResult<ObjectSelection>) => void; cancel?: () => void };
+  let queue: Job[] = [];
+  let release: (() => void) | undefined;
+  let applying = false;
+  let draining = false;
+  let publishedPending = false;
+
+  function publishPending(pending: boolean) {
+    if (publishedPending === pending) return;
+    publishedPending = pending;
+    try { options.onPendingChange?.(pending); } catch { /* Observers cannot interrupt adoption or cleanup. */ }
+  }
+  function idle() {
+    release?.(); release = undefined;
+    publishPending(false);
+  }
+  function cancel() {
+    const cancelled = queue;
+    queue = [];
+    if (cancelled.length === 0) return;
+    idle();
+    for (const job of cancelled) {
+      job.resolve({ ok: false, code: "clipboard.cancelled" });
+      try { job.cancel?.(); } catch { /* Other preparations must still be cancelled. */ }
+    }
+  }
+  function drain() {
+    if (draining) return;
+    draining = true;
+    try {
+      while (queue[0]?.result) {
+        const job = queue.shift()!;
+        const prepared = job.result!;
+        applying = true;
+        let result: EditingResult<ObjectSelection>;
+        try {
+          result = prepared.ok ? editor.dispatch({ type: "clipboard.paste", clipboard: prepared.clipboard, ...(options.placement ? { placement: options.placement } : {}) }) : prepared;
+        } catch (error) {
+          result = { ok: false, code: "clipboard.invalid", reason: error instanceof Error ? error.message : String(error) };
+        } finally { applying = false; }
+        job.resolve(result);
+        try { options.onResult?.(result); } catch { /* A completed edit cannot be rejected by an observer. */ }
+        if (result.ok && (editor.snapshot.value !== result.snapshot.value || editor.snapshot.selection !== result.snapshot.selection)) cancel();
+      }
+    } finally {
+      draining = false;
+      if (queue.length === 0) idle();
+    }
+  }
+  function ready(job: Job, result: ObjectPastePreparation) {
+    if (!queue.includes(job)) return;
+    job.result = result;
+    drain();
+  }
+  return {
+    get pending() { return queue.length > 0; },
+    cancel,
+    enqueue(prepare, cancelPreparation) {
+      return new Promise((resolve) => {
+        const job: Job = { resolve, ...(cancelPreparation ? { cancel: cancelPreparation } : {}) };
+        if (!release) {
+          let base = editor.snapshot;
+          release = editor.subscribe((next) => {
+            if (!applying && (base.value !== next.value || base.selection !== next.selection)) cancel();
+            base = next;
+          });
+        }
+        const wasIdle = queue.length === 0;
+        queue.push(job);
+        if (wasIdle) publishPending(true);
+        if (!queue.includes(job)) return;
+        try {
+          const result = prepare();
+          if ("ok" in result) ready(job, result);
+          else void Promise.resolve(result).then((value) => ready(job, value), (error: unknown) => ready(job, { ok: false, code: "clipboard.invalid", reason: error instanceof Error ? error.message : String(error) }));
+        } catch (error) { ready(job, { ok: false, code: "clipboard.invalid", reason: error instanceof Error ? error.message : String(error) }); }
+      });
+    },
+  };
+}
diff --git a/packages/json-document-editing/src/object.ts b/packages/json-document-editing/src/object.ts
index 3e4cfbf4..e04654b2 100644
--- a/packages/json-document-editing/src/object.ts
+++ b/packages/json-document-editing/src/object.ts
@@ -51,7 +51,7 @@ export const objectClipboardFormat = {
 };
 
 export interface ObjectPastePlacement {
-  readonly type: "offset";
+  readonly type: "offset" | "cascade";
   readonly dx: number;
   readonly dy: number;
 }
@@ -220,8 +220,19 @@ export function createObjectEditor(
   }
 
   function insertCopies(source: readonly DocumentObject[], primaryKey: string | null, placement: ObjectPastePlacement | undefined, origin: string): EditingResult<ObjectSelection> {
-    const dx = placement?.dx ?? 0, dy = placement?.dy ?? 0;
+    let dx = placement?.dx ?? 0, dy = placement?.dy ?? 0;
     if (![dx, dy].every(Number.isFinite)) return failure("object.invalid");
+    if (placement?.type === "cascade") {
+      if (dx === 0 && dy === 0) return failure("object.invalid");
+      const occupied = new Set(value().objects.map((object) => `${object.x}:${object.y}`));
+      const anchor = source[0]!;
+      let step = 1;
+      while (occupied.has(`${anchor.x + dx}:${anchor.y + dy}`)) {
+        if (++step > occupied.size + 1) return failure("object.invalid");
+        dx = placement.dx * step; dy = placement.dy * step;
+      }
+    }
+    if (source.some((object) => !Number.isFinite(object.x + dx) || !Number.isFinite(object.y + dy))) return failure("object.invalid");
     let copies: DocumentObject[];
     try {
       copies = cloneObjectsWithUniqueIds(source, value().objects, createId).map((object) => transformObject(object, { dx, dy }));
diff --git a/packages/json-document-editing/tests/object-paste.test.ts b/packages/json-document-editing/tests/object-paste.test.ts
new file mode 100644
index 00000000..530b456b
--- /dev/null
+++ b/packages/json-document-editing/tests/object-paste.test.ts
@@ -0,0 +1,115 @@
+import { expect, test, vi } from "vitest";
+import { createJSONDocument } from "@interactive-os/json-document";
+import { createCanvasClipboard, createObjectEditor, createObjectPasteSession, objectClipboardFormat, type ObjectPastePreparation } from "../src/index.js";
+import type { CanvasDocument } from "@interactive-os/json-document-object-document";
+
+const blank: CanvasDocument = { profile: "canvas/1", width: 1280, height: 720, objects: [] };
+const options = { bounds: { x: 0, y: 0, width: 600, height: 400 }, textColor: "black", fontSize: 32 };
+const placement = { type: "cascade", dx: 24, dy: 24 } as const;
+const payload = (text: string) => createCanvasClipboard({ type: "text", text }, options);
+function setup() {
+  let id = 0;
+  const document = createJSONDocument(blank);
+  const editor = createObjectEditor(document, { createId: () => `object-${++id}` });
+  const commits = vi.fn(); document.subscribe(commits);
+  return { editor, commits, value: () => editor.snapshot.value as CanvasDocument };
+}
+function deferred() {
+  let resolve!: (value: ObjectPastePreparation) => void;
+  const promise = new Promise<ObjectPastePreparation>((done) => { resolve = done; });
+  return { promise, resolve };
+}
+
+test("literal Unicode text and decoded rasters become validated domain clipboard with temporary source identities", () => {
+  const text = payload("<b>안녕</b>\nSecond line");
+  expect(text.objects[0]).toMatchObject({ id: "clipboard:0", kind: "text", label: "<b>안녕</b>\nSecond line", fontSize: 32, height: 76.8 });
+  const images = createCanvasClipboard({ type: "images", images: [
+    { source: "data:image/png;base64,AQID", width: 1200, height: 400, label: "first.png" },
+    { source: "data:image/webp;base64,AQID", width: 100, height: 50, label: "second.webp" },
+  ] }, options);
+  expect(images.objects.map((object) => [object.x, object.y, object.width, object.height])).toEqual([[0, 0, 600, 200], [24, 24, 100, 50]]);
+  expect(images.primaryKey).toBe("clipboard:1"); expect(images.text).toBe("first.png\nsecond.webp");
+  expect(objectClipboardFormat.parse(images)).toEqual(images);
+  expect(() => payload("")).toThrow();
+  expect(() => createCanvasClipboard({ type: "images", images: [] }, options)).toThrow();
+  expect(() => createCanvasClipboard({ type: "text", text: "x" }, { ...options, fontSize: NaN })).toThrow();
+});
+
+test("cascade finds a free group origin, preserves relative bounds and primary, and reuses undone positions without a counter", () => {
+  const { editor, value } = setup();
+  const clipboard = createCanvasClipboard({ type: "images", images: [
+    { source: "data:image/png;base64,AQID", width: 100, height: 100, label: "A" },
+    { source: "data:image/png;base64,AQID", width: 100, height: 100, label: "B" },
+  ] }, options);
+  for (let index = 0; index < 2; index++) expect(editor.dispatch({ type: "clipboard.paste", clipboard, placement }).ok).toBe(true);
+  expect(value().objects.map((object) => object.x)).toEqual([24, 48, 72, 96]);
+  expect(editor.snapshot.selection).toMatchObject({ keys: ["object-3", "object-4"], primaryKey: "object-4" });
+  editor.undo();
+  editor.dispatch({ type: "clipboard.paste", clipboard, placement });
+  expect(value().objects.map((object) => object.x)).toEqual([24, 48, 72, 96]);
+  const before = editor.snapshot;
+  expect(editor.dispatch({ type: "clipboard.paste", clipboard, placement: { type: "cascade", dx: 0, dy: 0 } }).ok).toBe(false);
+  expect(editor.snapshot).toEqual(before);
+});
+
+test("async preparation completes out of order but commits in request order, one Undo each", async () => {
+  const { editor, commits, value } = setup();
+  const onResult = vi.fn(), onPendingChange = vi.fn();
+  const session = createObjectPasteSession(editor, { placement, onResult, onPendingChange });
+  const first = deferred(), second = deferred();
+  const a = session.enqueue(() => first.promise), b = session.enqueue(() => second.promise);
+  const c = session.enqueue(() => ({ ok: true, clipboard: payload("C") }));
+  second.resolve({ ok: true, clipboard: payload("B") }); await Promise.resolve();
+  expect(session.pending).toBe(true); expect(commits).not.toHaveBeenCalled();
+  first.resolve({ ok: true, clipboard: payload("A") });
+  expect((await Promise.all([a, b, c])).every((result) => result.ok)).toBe(true);
+  expect(value().objects.map((object) => [object.label, object.x])).toEqual([["A", 24], ["B", 48], ["C", 72]]);
+  expect(commits).toHaveBeenCalledTimes(3); expect(onResult).toHaveBeenCalledTimes(3);
+  expect(session.pending).toBe(false); expect(onPendingChange.mock.calls).toEqual([[true], [false]]);
+  editor.undo(); expect(value().objects.map((object) => object.label)).toEqual(["A", "B"]);
+  editor.undo(); expect(value().objects.map((object) => object.label)).toEqual(["A"]);
+  editor.undo(); expect(value()).toEqual(blank);
+});
+
+test.each(["cancel", "selection", "document"])("%s invalidates pending and ready work without stale commits, ID allocation or late callbacks", async (reason) => {
+  const { editor, value } = setup();
+  const onResult = vi.fn(), abort = vi.fn();
+  const session = createObjectPasteSession(editor, { placement, onResult });
+  const first = deferred();
+  const a = session.enqueue(() => first.promise, abort), b = session.enqueue(() => ({ ok: true, clipboard: payload("B") }));
+  if (reason === "cancel") session.cancel();
+  else if (reason === "selection") editor.dispatch({ type: "selection.set", objectIds: [] });
+  else editor.dispatch({ type: "document.replace", document: { ...blank, title: "New slide" } });
+  expect(await a).toMatchObject({ ok: false, code: "clipboard.cancelled" });
+  expect(await b).toMatchObject({ ok: false, code: "clipboard.cancelled" });
+  first.resolve({ ok: true, clipboard: payload("A") }); await Promise.resolve();
+  expect(value().objects).toEqual([]); expect(onResult).not.toHaveBeenCalled(); expect(abort).toHaveBeenCalledOnce();
+  expect((await session.enqueue(() => ({ ok: true, clipboard: payload("Fresh") }))).ok).toBe(true);
+  expect(value().objects[0]!.id).toBe("object-1");
+});
+
+test("sync content commits synchronously; rejected preparation does not poison the queue", async () => {
+  const { editor, value, commits } = setup();
+  const session = createObjectPasteSession(editor, { placement });
+  const bad = session.enqueue(() => Promise.reject(new Error("decode failed")));
+  const good = session.enqueue(() => ({ ok: true, clipboard: payload("Valid") }));
+  expect(await bad).toMatchObject({ ok: false, reason: "decode failed" });
+  expect((await good).ok).toBe(true); expect(commits).toHaveBeenCalledOnce();
+  const sync = session.enqueue(() => ({ ok: true, clipboard: payload("Now") }));
+  expect(value().objects.at(-1)!.label).toBe("Now"); await sync;
+});
+
+test("throwing observers and cleanup callbacks cannot strand the queue or change a completed edit", async () => {
+  const { editor, value } = setup();
+  const throwing = () => { throw new Error("observer failed"); };
+  const session = createObjectPasteSession(editor, { onResult: throwing, onPendingChange: throwing });
+  const first = deferred();
+  const a = session.enqueue(() => first.promise), b = session.enqueue(() => ({ ok: true, clipboard: payload("B") }));
+  first.resolve({ ok: true, clipboard: payload("A") });
+  expect((await Promise.all([a, b])).every((result) => result.ok)).toBe(true);
+  expect(value().objects.map((object) => object.label)).toEqual(["A", "B"]);
+  const next = deferred();
+  const c = session.enqueue(() => next.promise, throwing), d = session.enqueue(() => next.promise, throwing);
+  expect(() => session.cancel()).not.toThrow();
+  expect((await Promise.all([c, d])).every((result) => !result.ok && result.code === "clipboard.cancelled")).toBe(true);
+});
diff --git a/packages/json-document-object-document/docs/api.md b/packages/json-document-object-document/docs/api.md
index 800e5fb1..6828fd75 100644
--- a/packages/json-document-object-document/docs/api.md
+++ b/packages/json-document-object-document/docs/api.md
@@ -1,8 +1,8 @@
 ## Object Document Type 계약 · RC
 
 소유자는 `@interactive-os/json-document-object-document`입니다. Object의 값과
-의미를 정의하며 선택·ID 할당·Intent·History는 Editing이, 사람의 조작은 Canvas
-Hand가 소유합니다. 기존 Editing 타입 export는 같은 정본 타입의 호환 경로입니다.
+의미를 정의하며 선택·ID 할당·Intent·History는 Editing이, 조작 문법은 Affordance가,
+입력 연결·렌더링은 Canvas Hand가 소유합니다. 기존 Editing 타입 export는 같은 정본 타입의 호환 경로입니다.
 
 ### 모델과 Canvas 프로파일
 
@@ -24,6 +24,7 @@ Object도 계속 유효합니다. legacy Object의 생략된 color는 계속 수
 | rectangle | 없음 | color로 채운 사각형 |
 | ellipse | 없음 | 경계 상자에 내접하는 타원 |
 | path | points, 양의 유한수 strokeWidth | color로 그린 열린 선 |
+| image | source | 문서에 포함한 PNG/JPEG/WebP의 base64 data URL |
 
 path points는 최소 두 개의 `{ x, y }`이며 각 좌표는 `[0, 1]`입니다. 경계 상자에
 대한 정규화 좌표이므로 이동·resize는 상자만 바꾸고 점과 strokeWidth를 보존합니다.
@@ -31,6 +32,16 @@ path points는 최소 두 개의 `{ x, y }`이며 각 좌표는 `[0, 1]`입니
 퇴화한 축은 최소 1 단위의 상자로 표현합니다. `createCanvasObject`는 도형/글자 초안을
 만들며 ID는 Editing의 `object.create`에서 할당합니다.
 
+`createCanvasImage({ source, width, height, label }, bounds)`는 decode된 자연 크기를
+주어진 상자에 비율을 유지해 맞추며 확대하지 않습니다. image의 color는 공통 모델 호환을
+위한 `transparent`이고 렌더링에는 쓰지 않습니다. 이후 resize는 다른 객체와 같은 자유
+상자 변환이며 원본 비율을 강제하지 않습니다. source 바이트는 이동·resize·복제에 유지됩니다.
+
+`assertCanvasImageSource`는 PNG/JPEG/WebP MIME과 비어 있지 않은 base64 문법을 검증합니다.
+외부 URL, blob URL, SVG, HTML은 거절합니다. 실제 이미지 decode나 파일 크기·픽셀 정책 검사는
+하지 않습니다. Web의 `readWebRasterFile`과 File Intake를 거친 입력만 실제 이미지로 수용하는
+경계는 Canvas Clipboard binding에 있습니다. JSON 문자열만으로 디코딩 가능성을 보증하지 않습니다.
+
 ### 검증과 직렬화
 
 `assertObjectDocument`/`assertCanvasDocument`는 구조 위반 시 TypeError를 던집니다.
diff --git a/packages/json-document-object-document/src/index.ts b/packages/json-document-object-document/src/index.ts
index 0b8f5783..4e295ccb 100644
--- a/packages/json-document-object-document/src/index.ts
+++ b/packages/json-document-object-document/src/index.ts
@@ -1,4 +1,4 @@
 export type { ObjectBounds, ObjectPoint, ObjectDraft, DocumentObject, ObjectDocument, CanvasObjectKind, CanvasObjectDraft, CanvasObject, CanvasDocument } from "./object-model.js";
-export { assertObjectDocument, assertCanvasDocument, parseCanvasDocument, serializeCanvasDocument } from "./object-validation.js";
-export { createCanvasObject, createCanvasPath, projectObject, transformObject, type ObjectTransform } from "./object-projection.js";
+export { assertObjectDocument, assertCanvasDocument, assertCanvasImageSource, parseCanvasDocument, serializeCanvasDocument } from "./object-validation.js";
+export { createCanvasObject, createCanvasPath, createCanvasImage, projectObject, transformObject, type ObjectTransform } from "./object-projection.js";
 export { planObjectOperation, type ObjectOperation, type ObjectOperationPlan } from "./object-operation.js";
diff --git a/packages/json-document-object-document/src/object-model.ts b/packages/json-document-object-document/src/object-model.ts
index 229ab7af..25becd97 100644
--- a/packages/json-document-object-document/src/object-model.ts
+++ b/packages/json-document-object-document/src/object-model.ts
@@ -26,12 +26,13 @@ export interface ObjectDocument extends Record<string, JSONValue> {
   readonly objects: ReadonlyArray<DocumentObject>;
 }
 
-export type CanvasObjectKind = "text" | "rectangle" | "ellipse" | "path";
+export type CanvasObjectKind = "text" | "rectangle" | "ellipse" | "path" | "image";
 
 export type CanvasObjectDraft = ObjectDraft & (
   | { readonly kind: "text"; readonly fontSize: number }
   | { readonly kind: "rectangle" | "ellipse" }
   | { readonly kind: "path"; readonly points: ReadonlyArray<ObjectPoint>; readonly strokeWidth: number }
+  | { readonly kind: "image"; readonly source: string }
 );
 
 export type CanvasObject = CanvasObjectDraft & { readonly id: string };
diff --git a/packages/json-document-object-document/src/object-projection.ts b/packages/json-document-object-document/src/object-projection.ts
index ab4787e6..79c9f61b 100644
--- a/packages/json-document-object-document/src/object-projection.ts
+++ b/packages/json-document-object-document/src/object-projection.ts
@@ -1,4 +1,5 @@
 import type { CanvasObject, CanvasObjectDraft, CanvasObjectKind, DocumentObject, ObjectBounds, ObjectPoint } from "./object-model.js";
+import { assertCanvasImageSource } from "./object-validation.js";
 
 export interface ObjectTransform {
   readonly dx: number;
@@ -27,7 +28,7 @@ export function projectObject(object: DocumentObject): CanvasObject {
 }
 
 export function createCanvasObject(
-  kind: Exclude<CanvasObjectKind, "path">,
+  kind: Exclude<CanvasObjectKind, "path" | "image">,
   bounds: ObjectBounds,
   style: { readonly color: string; readonly label: string; readonly fontSize?: number },
 ): CanvasObjectDraft {
@@ -35,6 +36,18 @@ export function createCanvasObject(
   return kind === "text" ? { ...base, kind, fontSize: style.fontSize ?? 32 } : { ...base, kind };
 }
 
+/** Fits a decoded raster inside bounds without upscaling; persisted bytes survive JSON round trips. */
+export function createCanvasImage(
+  image: { readonly source: string; readonly width: number; readonly height: number; readonly label: string },
+  bounds: ObjectBounds,
+): Extract<CanvasObjectDraft, { readonly kind: "image" }> {
+  assertCanvasImageSource(image.source);
+  if (![image.width, image.height, bounds.width, bounds.height].every((value) => Number.isFinite(value) && value > 0)
+    || ![bounds.x, bounds.y].every(Number.isFinite)) throw new TypeError("Image and fit dimensions must be positive and finite.");
+  const scale = Math.min(1, bounds.width / image.width, bounds.height / image.height);
+  return { kind: "image", source: image.source, label: image.label, color: "transparent", x: bounds.x, y: bounds.y, width: image.width * scale, height: image.height * scale };
+}
+
 /** Converts slide-space samples to one bounding box and normalized path geometry. */
 export function createCanvasPath(
   points: ReadonlyArray<ObjectPoint>,
diff --git a/packages/json-document-object-document/src/object-validation.ts b/packages/json-document-object-document/src/object-validation.ts
index 52028286..8ba42fc0 100644
--- a/packages/json-document-object-document/src/object-validation.ts
+++ b/packages/json-document-object-document/src/object-validation.ts
@@ -25,9 +25,10 @@ export function assertObjectDocument(value: unknown): void {
     if ((object.width as number) < 0 || (object.height as number) < 0) throw new TypeError(`Object dimensions must not be negative: ${JSON.stringify(object.id)}.`);
     if (object.kind !== undefined) {
       if (typeof object.color !== "string") throw new TypeError("Canvas objects require a color string.");
-      if (!["text", "rectangle", "ellipse", "path"].includes(object.kind as string)) throw new TypeError("Unknown Object kind.");
+      if (!["text", "rectangle", "ellipse", "path", "image"].includes(object.kind as string)) throw new TypeError("Unknown Object kind.");
       if (!positive(object.width) || !positive(object.height)) throw new TypeError("Canvas object dimensions must be positive.");
       if (object.kind === "text" && !positive(object.fontSize)) throw new TypeError("Text fontSize must be positive and finite.");
+      if (object.kind === "image") assertCanvasImageSource(object.source);
       if (object.kind === "path") {
         if (!positive(object.strokeWidth) || !Array.isArray(object.points) || object.points.length < 2) throw new TypeError("Path requires a positive strokeWidth and at least two points.");
         for (const point of object.points) {
@@ -40,6 +41,20 @@ export function assertObjectDocument(value: unknown): void {
   if (value.profile === "canvas/1") assertCanvasShape(value as unknown as ObjectDocument);
 }
 
+/** Embedded raster only: no external fetch, SVG, HTML, or session-scoped blob URL. Decoding belongs to the platform. */
+export function assertCanvasImageSource(source: unknown): asserts source is string {
+  if (typeof source !== "string") throw new TypeError("Image source must be an embedded PNG, JPEG, or WebP data URL.");
+  const separator = source.indexOf(",");
+  const header = source.slice(0, separator);
+  const bytes = source.slice(separator + 1);
+  // A flat character check avoids recursive regex stack growth on large rasters.
+  if (!["data:image/png;base64", "data:image/jpeg;base64", "data:image/webp;base64"].includes(header)
+    || bytes.length === 0 || bytes.length % 4 !== 0 || /[^A-Za-z0-9+/=]/.test(bytes)
+    || bytes.slice(0, -2).includes("=") || (bytes.at(-2) === "=" && bytes.at(-1) !== "=")) {
+    throw new TypeError("Image source must be an embedded PNG, JPEG, or WebP base64 data URL.");
+  }
+}
+
 function assertCanvasShape(value: ObjectDocument): void {
   if (!positive(value.width) || !positive(value.height)) throw new TypeError("Canvas dimensions must be positive and finite.");
   if (value.objects.some((object) => object.kind === undefined)) throw new TypeError("Canvas objects require an explicit kind.");
diff --git a/packages/json-document-object-document/tests/object-document.test.ts b/packages/json-document-object-document/tests/object-document.test.ts
index b066b2da..7f62fd2b 100644
--- a/packages/json-document-object-document/tests/object-document.test.ts
+++ b/packages/json-document-object-document/tests/object-document.test.ts
@@ -1,6 +1,6 @@
 import { describe, expect, test } from "vitest";
 import { applyPatch } from "@interactive-os/json-document";
-import { assertCanvasDocument, assertObjectDocument, createCanvasObject, createCanvasPath, parseCanvasDocument, planObjectOperation, serializeCanvasDocument, transformObject, type CanvasDocument } from "../src/index.js";
+import { assertCanvasDocument, assertCanvasImageSource, assertObjectDocument, createCanvasImage, createCanvasObject, createCanvasPath, parseCanvasDocument, planObjectOperation, serializeCanvasDocument, transformObject, type CanvasDocument } from "../src/index.js";
 
 const blank: CanvasDocument = { profile: "canvas/1", width: 1280, height: 720, objects: [] };
 const text = { ...createCanvasObject("text", { x: 10, y: 20, width: 300, height: 100 }, { color: "#123456", label: "Hello\n안녕", fontSize: 36 }), id: "text" };
@@ -11,11 +11,24 @@ describe("Object document and Canvas profile", () => {
     const document: CanvasDocument = { ...blank, title: "Slide", objects: [text, path,
       { ...createCanvasObject("rectangle", { x: 100, y: 150, width: 80, height: 60 }, { color: "#abcdef", label: "" }), id: "rect" },
       { ...createCanvasObject("ellipse", { x: 200, y: 150, width: 80, height: 60 }, { color: "#abcdef", label: "" }), id: "ellipse" },
+      { ...createCanvasImage({ source: "data:image/png;base64,AQID", width: 800, height: 400, label: "Picture" }, { x: 30, y: 40, width: 200, height: 200 }), id: "image" },
     ] };
     expect(parseCanvasDocument(serializeCanvasDocument(document))).toEqual(document);
     expect(Object.keys(JSON.parse(serializeCanvasDocument(blank)))).toEqual(["profile", "width", "height", "objects"]);
   });
 
+  test("embedded raster fitting preserves aspect and transform leaves bytes unchanged", () => {
+    const object = { ...createCanvasImage({ source: "data:image/jpeg;base64,AQID", width: 800, height: 400, label: "Picture" }, { x: 10, y: 20, width: 200, height: 200 }), id: "image" };
+    expect(object).toMatchObject({ kind: "image", width: 200, height: 100 });
+    expect(transformObject(object, { dx: 20, dy: 30, dw: 10, dh: 20 })).toMatchObject({ source: object.source, x: 30, y: 50, width: 210, height: 120 });
+    expect(() => createCanvasImage({ source: object.source, width: 0, height: 10, label: "" }, object)).toThrow();
+    expect(() => assertCanvasImageSource(`data:image/webp;base64,${"AQID".repeat(100_000)}`)).not.toThrow();
+  });
+
+  test.each([undefined, "https://example.com/a.png", "blob:temporary", "data:image/svg+xml;base64,AQID", "data:text/html;base64,AQID", "data:image/png;base64,", "data:image/png;base64,A", "data:image/png;base64,AQ=Z", "data:image/png;base64,A===", "data:image/png;base64,AQID\n"])("rejects nonportable or malformed image source %#", (source) => {
+    expect(() => assertCanvasDocument({ ...blank, objects: [{ ...text, kind: "image", source }] })).toThrow();
+  });
+
   test.each([null, [], {}, { ...blank, objects: null }, { ...blank, width: 0 }, { ...blank, height: Infinity },
     { ...blank, objects: [text, text] }, { ...blank, objects: [{ ...text, id: "" }] },
     { ...blank, objects: [{ ...text, label: 1 }] }, { ...blank, objects: [{ ...text, x: NaN }] },
diff --git a/packages/json-document-web/docs/clipboard.md b/packages/json-document-web/docs/clipboard.md
index 028f3656..9c8cb33b 100644
--- a/packages/json-document-web/docs/clipboard.md
+++ b/packages/json-document-web/docs/clipboard.md
@@ -31,3 +31,25 @@ const clipboard = createWebClipboardBinding({
 
 실제 소비와 Source: [Canvas](/demo/canvas), [Object Demo](/demo/object),
 [Clipboard Adapter](/adapters/clipboard). Canvas text/JSON textarea는 native clipboard를 유지합니다.
+
+### 비동기 입력을 위한 동기 캡처
+
+`captureWebClipboardPaste(event, { codec, files: true, text: true })`는 이벤트가 끝나기 전에
+구조화 MIME → 파일 → `text/plain` 순서로 하나의 표현을 캡처합니다. 성공은 `type`이
+`structured`(payload), `files`(파일 배열), `text`(문자열)인 결과입니다. files/text는 명시한
+경우만 처리하며 기본은 구조화 표현뿐입니다. 파일 메타데이터는 별도 `fileCandidatesFromWebFiles`
+API로 File Intake에 전달하고, 파일 참조는 실제 browser File이어야 읽을 수 있습니다.
+
+캡처한 파일 배열과 문자열을 비동기 작업에 넘기며 ClipboardEvent/DataTransfer를 나중에 다시
+읽지 않습니다. 자신이 처리하는 표현은 즉시 preventDefault합니다. 구조화 MIME이 있으면
+decode 실패도 소유한 실패이며 다른 표현으로 떨어지지 않습니다. 이 strict 캡처는 위의 기존
+동기 binding이 제공하는 여러 representation fallback/pass-through와 구분되는 계약입니다.
+일치하는 표현이 없으면 native 처리를 막지 않고 `clipboard.empty`를 반환합니다.
+
+`readWebRasterFile(file, { signal? })`는 기존 FileReader와 Image decode 정본입니다.
+성공은 dataURL과 자연 width/height, 실패는 `raster.read-failed`, `raster.decode-failed`,
+취소는 `raster.cancelled`입니다. 구조적 `WebRasterReadSignal`은 browser AbortSignal과
+호환되며 read/decode 중 취소하면 리스너를 해제하고 읽기/이미지 요청을 중단합니다.
+파일 형식·크기·개수·픽셀 제한이나 문서 객체 생성은 이 플랫폼 API의 책임이 아닙니다.
+
+실제 텍스트·이미지 입력 및 순서/취소 연결: [Canvas Usage/Source](/demo/canvas).
diff --git a/packages/json-document-web/src/clipboard.ts b/packages/json-document-web/src/clipboard.ts
index 28e3f5b7..d354215f 100644
--- a/packages/json-document-web/src/clipboard.ts
+++ b/packages/json-document-web/src/clipboard.ts
@@ -6,6 +6,7 @@ import {
   sheetClipboardFormat,
   treeClipboardFormat,
 } from "@interactive-os/json-document-editing";
+import type { WebFileCandidate, WebFileCandidateList } from "./file-intake.js";
 
 export interface WebClipboardPayload {
   readonly type: string;
@@ -14,6 +15,7 @@ export interface WebClipboardPayload {
 
 export interface WebClipboardData {
   readonly types: ReadonlyArray<string>;
+  readonly files?: WebFileCandidateList;
   getData(format: string): string;
   setData(format: string, data: string): void;
 }
@@ -23,6 +25,39 @@ export interface WebClipboardEvent {
   preventDefault(): void;
 }
 
+export type WebClipboardPaste<Payload extends WebClipboardPayload> =
+  | { readonly ok: true; readonly type: "structured"; readonly payload: Payload }
+  | { readonly ok: true; readonly type: "files"; readonly files: ReadonlyArray<WebFileCandidate> }
+  | { readonly ok: true; readonly type: "text"; readonly text: string }
+  | Extract<WebClipboardResult<never, never>, { readonly ok: false }>;
+
+/** Captures native data before the event ends: structured → files → literal text. An owned invalid format never falls through. */
+export function captureWebClipboardPaste<Payload extends WebClipboardPayload>(event: WebClipboardEvent, options: {
+  readonly codec: WebClipboardCodec<Payload>;
+  readonly files?: boolean;
+  readonly text?: boolean;
+}): WebClipboardPaste<Payload> {
+  const data = event.clipboardData;
+  if (data === null) return failure("clipboard.unavailable");
+  try {
+    if (Array.from(data.types).includes(options.codec.mimeType)) {
+      event.preventDefault();
+      const result = readRepresentations(data, [options.codec]);
+      return result.ok ? { ok: true, type: "structured", payload: result.payload } : result;
+    }
+    if (options.files && data.files && data.files.length > 0) {
+      event.preventDefault();
+      return { ok: true, type: "files", files: Array.from(data.files) };
+    }
+    if (options.text && Array.from(data.types).includes("text/plain")) {
+      event.preventDefault();
+      const text = data.getData("text/plain");
+      return text.length > 0 ? { ok: true, type: "text", text } : failure("clipboard.empty");
+    }
+    return failure("clipboard.empty");
+  } catch (error) { return failure("clipboard.unavailable", errorMessage(error)); }
+}
+
 export interface WebClipboardCodec<Payload extends WebClipboardPayload> {
   readonly mimeType: Payload["type"];
   encode(payload: Payload): string;
@@ -183,21 +218,9 @@ export function createWebClipboardBinding<
         encode: options.codec.encode,
         decode: options.codec.decode,
       }];
-      let payload: Payload | null = null;
-      let matched = false;
-      let invalidReason: string | undefined;
-      for (const representation of representations) {
-        if (!Array.from(data.types).includes(representation.mimeType)) continue;
-        matched = true;
-        try {
-          payload = representation.decode(data.getData(representation.mimeType));
-        } catch (error) {
-          invalidReason = errorMessage(error);
-        }
-        if (payload !== null) break;
-      }
-      if (!matched) return failure("clipboard.empty");
-      if (payload === null) return failure("clipboard.invalid", invalidReason);
+      const captured = readRepresentations(data, representations);
+      if (!captured.ok) return captured;
+      const { payload } = captured;
       event.preventDefault();
       const result = options.paste(payload);
       if (!result.ok) return failure("editing.rejected", result.reason ?? result.code);
@@ -230,10 +253,26 @@ export function createWebClipboardSurface<
   };
 }
 
+function readRepresentations<Payload extends WebClipboardPayload>(data: WebClipboardData, representations: ReadonlyArray<WebClipboardRepresentation<Payload>>):
+  | { readonly ok: true; readonly payload: Payload }
+  | Extract<WebClipboardResult<never, never>, { readonly ok: false }> {
+  let matched = false;
+  let invalidReason: string | undefined;
+  for (const representation of representations) {
+    if (!Array.from(data.types).includes(representation.mimeType)) continue;
+    matched = true;
+    try {
+      const payload = representation.decode(data.getData(representation.mimeType));
+      if (payload !== null) return { ok: true, payload };
+    } catch (error) { invalidReason = errorMessage(error); }
+  }
+  return failure(matched ? "clipboard.invalid" : "clipboard.empty", invalidReason);
+}
+
 function failure(
   code: Extract<WebClipboardResult<never, never>, { readonly ok: false }>["code"],
   reason?: string,
-): WebClipboardResult<never, never> {
+): Extract<WebClipboardResult<never, never>, { readonly ok: false }> {
   return reason === undefined ? { ok: false, code } : { ok: false, code, reason };
 }
 
diff --git a/packages/json-document-web/src/index.ts b/packages/json-document-web/src/index.ts
index 15ba7e06..acda1c35 100644
--- a/packages/json-document-web/src/index.ts
+++ b/packages/json-document-web/src/index.ts
@@ -1,5 +1,6 @@
 export {
   createWebClipboardBinding,
+  captureWebClipboardPaste,
   createWebJSONClipboardRepresentation,
   createWebClipboardSurface,
   createWebClipboardTextWriter,
@@ -65,6 +66,7 @@ export type {
 } from "./anchored-floating-position.js";
 export type {
   WebClipboardBinding,
+  WebClipboardPaste,
   WebClipboardBindingOptions,
   WebClipboardCodec,
   WebClipboardData,
@@ -118,7 +120,7 @@ export type {
 } from "./viewport-position.js";
 export type { WebKanbanTargetElement } from "./kanban-drop-target.js";
 export type { WebClientPoint, WebSVGElement, WebSVGViewport } from "./svg-coordinate.js";
-export type { WebRasterFile, WebRasterSourceResult } from "./raster-source.js";
+export type { WebRasterFile, WebRasterReadSignal, WebRasterSourceResult } from "./raster-source.js";
 export type { WebComposerClipboardEvent, WebComposerFile, WebComposerFileList, WebFileCandidate, WebFileCandidateList, WebFileClipboardEvent } from "./file-intake.js";
 export type { WebAnnotationRasterResult, WebAnnotationRasterStyle } from "./annotation-raster.js";
 export type {
diff --git a/packages/json-document-web/src/raster-source.ts b/packages/json-document-web/src/raster-source.ts
index 66ec0033..28f80e66 100644
--- a/packages/json-document-web/src/raster-source.ts
+++ b/packages/json-document-web/src/raster-source.ts
@@ -1,6 +1,6 @@
 export type WebRasterSourceResult =
   | { readonly ok: true; readonly dataURL: string; readonly width: number; readonly height: number }
-  | { readonly ok: false; readonly code: "raster.read-failed" | "raster.decode-failed"; readonly reason?: string };
+  | { readonly ok: false; readonly code: "raster.read-failed" | "raster.decode-failed" | "raster.cancelled"; readonly reason?: string };
 
 /** Structural boundary accepted by `FileReader`; browser `File` instances satisfy it. */
 export interface WebRasterFile {
@@ -8,37 +8,64 @@ export interface WebRasterFile {
   readonly type: string;
 }
 
-export async function readWebRasterFile(file: WebRasterFile): Promise<WebRasterSourceResult> {
-  const dataURL = await readDataURL(file);
+/** Structural AbortSignal boundary, usable by DOM-free consumers of Web declarations. */
+export interface WebRasterReadSignal {
+  readonly aborted: boolean;
+  addEventListener(type: "abort", listener: () => void, options?: { readonly once?: boolean }): void;
+  removeEventListener(type: "abort", listener: () => void): void;
+}
+
+export async function readWebRasterFile(file: WebRasterFile, options: { readonly signal?: WebRasterReadSignal } = {}): Promise<WebRasterSourceResult> {
+  if (options.signal?.aborted) return { ok: false, code: "raster.cancelled" };
+  const dataURL = await readDataURL(file, options.signal);
   if (!dataURL.ok) return dataURL;
-  return decodeRaster(dataURL.dataURL);
+  return decodeRaster(dataURL.dataURL, options.signal);
 }
 
-function readDataURL(file: WebRasterFile): Promise<Extract<WebRasterSourceResult, { ok: true }> | Extract<WebRasterSourceResult, { ok: false }>> {
+function readDataURL(file: WebRasterFile, signal?: WebRasterReadSignal): Promise<WebRasterSourceResult> {
   return new Promise((resolve) => {
-    const reader = new FileReader();
-    reader.onerror = () => resolve({
+    let reader: FileReader;
+    try { reader = new FileReader(); } catch (error) { resolve({ ok: false, code: "raster.read-failed", reason: message(error) }); return; }
+    function finish(result: WebRasterSourceResult) {
+      signal?.removeEventListener("abort", abort);
+      reader.onload = reader.onerror = reader.onabort = null;
+      resolve(result);
+    }
+    function abort() { finish({ ok: false, code: "raster.cancelled" }); reader.abort(); }
+    signal?.addEventListener("abort", abort, { once: true });
+    if (signal?.aborted) { abort(); return; }
+    reader.onabort = () => finish({ ok: false, code: "raster.cancelled" });
+    reader.onerror = () => finish({
       ok: false,
       code: "raster.read-failed",
       ...(reader.error === null ? {} : { reason: reader.error.message }),
     });
     reader.onload = () => typeof reader.result === "string"
-      ? resolve({ ok: true, dataURL: reader.result, width: 0, height: 0 })
-      : resolve({ ok: false, code: "raster.read-failed" });
+      ? finish({ ok: true, dataURL: reader.result, width: 0, height: 0 })
+      : finish({ ok: false, code: "raster.read-failed" });
     try { reader.readAsDataURL(file as unknown as Blob); } catch (error) {
-      resolve({ ok: false, code: "raster.read-failed", reason: message(error) });
+      finish({ ok: false, code: "raster.read-failed", reason: message(error) });
     }
   });
 }
 
-function decodeRaster(dataURL: string): Promise<WebRasterSourceResult> {
+function decodeRaster(dataURL: string, signal?: WebRasterReadSignal): Promise<WebRasterSourceResult> {
   return new Promise((resolve) => {
-    const image = new Image();
-    image.onerror = () => resolve({ ok: false, code: "raster.decode-failed" });
+    if (signal?.aborted) { resolve({ ok: false, code: "raster.cancelled" }); return; }
+    let image: HTMLImageElement;
+    try { image = new Image(); } catch (error) { resolve({ ok: false, code: "raster.decode-failed", reason: message(error) }); return; }
+    function finish(result: WebRasterSourceResult) {
+      signal?.removeEventListener("abort", abort);
+      image.onload = image.onerror = null;
+      resolve(result);
+    }
+    function abort() { finish({ ok: false, code: "raster.cancelled" }); image.src = ""; }
+    signal?.addEventListener("abort", abort, { once: true });
+    image.onerror = () => finish({ ok: false, code: "raster.decode-failed" });
     image.onload = () => image.naturalWidth > 0 && image.naturalHeight > 0
-      ? resolve({ ok: true, dataURL, width: image.naturalWidth, height: image.naturalHeight })
-      : resolve({ ok: false, code: "raster.decode-failed" });
-    image.src = dataURL;
+      ? finish({ ok: true, dataURL, width: image.naturalWidth, height: image.naturalHeight })
+      : finish({ ok: false, code: "raster.decode-failed" });
+    try { image.src = dataURL; } catch (error) { finish({ ok: false, code: "raster.decode-failed", reason: message(error) }); }
   });
 }
 
diff --git a/packages/json-document-web/tests/clipboard-paste.test.ts b/packages/json-document-web/tests/clipboard-paste.test.ts
new file mode 100644
index 00000000..99dbc522
--- /dev/null
+++ b/packages/json-document-web/tests/clipboard-paste.test.ts
@@ -0,0 +1,67 @@
+import { afterEach, expect, test, vi } from "vitest";
+import { captureWebClipboardPaste, objectClipboardCodec, readWebRasterFile, type WebClipboardEvent } from "../src/index.js";
+
+const payload = { type: objectClipboardCodec.mimeType, text: "Object", objects: [{ id: "a", x: 0, y: 0, width: 1, height: 1, label: "Object", color: "blue" }] };
+const file = { name: "picture.png", type: "image/png", size: 100 };
+const options = { codec: objectClipboardCodec, files: true, text: true };
+function event(values: Record<string, string> = {}, files = [] as typeof file[]) {
+  return { clipboardData: { types: Object.keys(values), files, getData: (type: string) => values[type] ?? "", setData() {} }, preventDefault: vi.fn() };
+}
+afterEach(() => vi.unstubAllGlobals());
+
+test("captures a portable snapshot in strict structured → files → text order before returning from the event", () => {
+  const structured = event({ [payload.type]: JSON.stringify(payload), "text/plain": "fallback" }, [file]);
+  expect(captureWebClipboardPaste(structured, options)).toEqual({ ok: true, type: "structured", payload });
+  expect(structured.preventDefault).toHaveBeenCalledOnce();
+  const withFiles = event({ "text/plain": "fallback" }, [file]);
+  const captured = captureWebClipboardPaste(withFiles, options);
+  withFiles.clipboardData.files.length = 0;
+  expect(captured).toEqual({ ok: true, type: "files", files: [file] });
+  const plain = event({ "text/plain": "<b>안녕</b>\nSecond" });
+  expect(captureWebClipboardPaste(plain, options)).toEqual({ ok: true, type: "text", text: "<b>안녕</b>\nSecond" });
+  expect(plain.preventDefault).toHaveBeenCalledOnce();
+});
+
+test("invalid owned MIME never becomes files or text, while unmatched data remains native", () => {
+  for (const serialized of ["{", "{}", ""]) {
+    const owned = event({ [payload.type]: serialized, "text/plain": "fallback" }, [file]);
+    expect(captureWebClipboardPaste(owned, options)).toMatchObject({ ok: false, code: "clipboard.invalid" });
+    expect(owned.preventDefault).toHaveBeenCalledOnce();
+  }
+  const html = event({ "text/html": "<p>Unknown</p>" });
+  expect(captureWebClipboardPaste(html, options)).toMatchObject({ ok: false, code: "clipboard.empty" });
+  expect(html.preventDefault).not.toHaveBeenCalled();
+  const plain = event({ "text/plain": "text" });
+  expect(captureWebClipboardPaste(plain, { codec: objectClipboardCodec })).toMatchObject({ ok: false, code: "clipboard.empty" });
+  expect(plain.preventDefault).not.toHaveBeenCalled();
+});
+
+test("unavailable and throwing clipboard reads are observable without exceptions", () => {
+  expect(captureWebClipboardPaste({ clipboardData: null, preventDefault() {} }, options)).toMatchObject({ ok: false, code: "clipboard.unavailable" });
+  const broken: WebClipboardEvent = { ...event({ "text/plain": "x" }), clipboardData: { types: ["text/plain"], setData() {}, getData() { throw new Error("blocked"); } } };
+  expect(captureWebClipboardPaste(broken, options)).toMatchObject({ ok: false, code: "clipboard.unavailable", reason: "blocked" });
+});
+
+test.each(["read", "decode"])("raster cancellation during %s releases listeners and settles without late success", async (phase) => {
+  const controller = new AbortController();
+  const remove = vi.spyOn(controller.signal, "removeEventListener");
+  const abort = vi.fn();
+  let lateRead: (() => void) | null = null, lateDecode: (() => void) | null = null;
+  class Reader {
+    result = "data:image/png;base64,AQID"; error = null; onload: (() => void) | null = null; onerror: (() => void) | null = null; onabort: (() => void) | null = null;
+    readAsDataURL() { lateRead = this.onload; if (phase === "decode") this.onload?.(); }
+    abort = abort;
+  }
+  class Raster {
+    naturalWidth = 100; naturalHeight = 100; onload: (() => void) | null = null; onerror: (() => void) | null = null;
+    set src(value: string) { if (value) lateDecode = this.onload; }
+  }
+  vi.stubGlobal("FileReader", Reader); vi.stubGlobal("Image", Raster);
+  const pending = readWebRasterFile(file, { signal: controller.signal });
+  await Promise.resolve(); controller.abort();
+  expect(await pending).toEqual({ ok: false, code: "raster.cancelled" });
+  expect(remove).toHaveBeenCalled();
+  if (phase === "read") expect(abort).toHaveBeenCalledOnce();
+  (lateRead as (() => void) | null)?.(); (lateDecode as (() => void) | null)?.();
+  expect(await readWebRasterFile(file, { signal: controller.signal })).toEqual({ ok: false, code: "raster.cancelled" });
+});
diff --git a/site/src/routes/canvas-demo/CanvasDemoRoute.tsx b/site/src/routes/canvas-demo/CanvasDemoRoute.tsx
index c1a80056..1e4d3d8c 100644
--- a/site/src/routes/canvas-demo/CanvasDemoRoute.tsx
+++ b/site/src/routes/canvas-demo/CanvasDemoRoute.tsx
@@ -11,7 +11,7 @@ export function CanvasDemoRoute() {
   const [editor] = useState(() => createObjectEditor(emptyCanvasDocument));
   const [selectProfile] = useState(() => createPlaneSelectProfile());
   return (
-    <DemoPage documentation={<PageHeader illustration="peek" title="Canvas">한 장에 글자·도형·그리기. Shift+클릭으로 다중 선택하고 빈 곳을 드래그해 영역을 고릅니다. 선택한 객체들은 함께 움직이며, 글자는 더블클릭으로 편집합니다.</PageHeader>}>
+    <DemoPage documentation={<PageHeader illustration="peek" title="Canvas">한 장에 글자·도형·그리기. Shift+클릭으로 다중 선택하고 Alt+드래그로 복제합니다. 복사한 텍스트·이미지도 붙여넣을 수 있으며, 글자는 더블클릭으로 편집합니다.</PageHeader>}>
       <CanvasHand className={ui.product.embedded} editor={editor} selectProfile={selectProfile} creationStyle={canvasCreationStyle} slideStyle={{ background: "rgb(var(--color-background-canvas))" }} />
     </DemoPage>
   );
diff --git a/site/src/routes/object-demo/ObjectDemoRoute.tsx b/site/src/routes/object-demo/ObjectDemoRoute.tsx
index 616f334e..59454adf 100644
--- a/site/src/routes/object-demo/ObjectDemoRoute.tsx
+++ b/site/src/routes/object-demo/ObjectDemoRoute.tsx
@@ -31,7 +31,7 @@ export function ObjectDemoRoute() {
     paste: (payload) => editor.dispatch({
       type: "clipboard.paste",
       clipboard: payload,
-      placement: { type: "offset", dx: 24, dy: 24 },
+      placement: { type: "cascade", dx: 24, dy: 24 },
     }),
     onResult(result) {
       if (!result.ok) return observation.announce(result.code);
diff --git a/site/src/shared/demo-workbench/demo-sources.ts b/site/src/shared/demo-workbench/demo-sources.ts
index bf3a2ac7..ad09b68b 100644
--- a/site/src/shared/demo-workbench/demo-sources.ts
+++ b/site/src/shared/demo-workbench/demo-sources.ts
@@ -6,6 +6,9 @@ import objectProjectionSource from "../../../../packages/json-document-object-do
 import canvasHandSource from "../../../../packages/json-document-canvas/src/canvas-hand.tsx?raw";
 import canvasInteractionSource from "../../../../packages/json-document-canvas/src/use-canvas-hand.ts?raw";
 import canvasObjectViewSource from "../../../../packages/json-document-canvas/src/canvas-object-view.tsx?raw";
+import canvasClipboardSource from "../../../../packages/json-document-canvas/src/canvas-clipboard.ts?raw";
+import canvasClipboardEditingSource from "../../../../packages/json-document-editing/src/canvas-clipboard.ts?raw";
+import objectPasteSessionSource from "../../../../packages/json-document-editing/src/object-paste-session.ts?raw";
 import editingSnapshotSource from "../../../../packages/json-document-react/src/editing-snapshot.ts?raw";
 import pointerTrackingSource from "../../../../packages/json-document/src/foundation/patch/track.ts?raw";
 import editingObservationSource from "../../../../packages/json-document-react/src/editing-observation.ts?raw";
@@ -209,6 +212,9 @@ const registeredUsageSources = new Map<string, string>([
   ["packages/json-document-canvas/src/canvas-hand.tsx", canvasHandSource],
   ["packages/json-document-canvas/src/use-canvas-hand.ts", canvasInteractionSource],
   ["packages/json-document-canvas/src/canvas-object-view.tsx", canvasObjectViewSource],
+  ["packages/json-document-canvas/src/canvas-clipboard.ts", canvasClipboardSource],
+  ["packages/json-document-editing/src/canvas-clipboard.ts", canvasClipboardEditingSource],
+  ["packages/json-document-editing/src/object-paste-session.ts", objectPasteSessionSource],
   ["packages/json-document-react/src/editing-snapshot.ts", editingSnapshotSource],
   ["packages/json-document/src/foundation/patch/track.ts", pointerTrackingSource],
   ["packages/json-document-calendar-document/src/calendar-model.ts", calendarDocumentModelSource],
@@ -346,6 +352,10 @@ const registeredUsageSources = new Map<string, string>([
   ["packages/json-document-zod/src/index.ts", zodSource],
 ]);
 const registeredPublicUsages = [
+  ...(["CanvasHand", "useCanvasHand", "createCanvasClipboardBinding"] as const).map((symbol) => ({ packageName: "@interactive-os/json-document-canvas", symbol, sourcePath: "packages/json-document-canvas/src/canvas-clipboard.ts" })),
+  { packageName: "@interactive-os/json-document-editing", symbol: "createCanvasClipboard", sourcePath: "packages/json-document-editing/src/canvas-clipboard.ts" },
+  { packageName: "@interactive-os/json-document-editing", symbol: "createObjectPasteSession", sourcePath: "packages/json-document-editing/src/object-paste-session.ts" },
+  { packageName: "@interactive-os/json-document-web", symbol: "captureWebClipboardPaste", sourcePath: "packages/json-document-web/src/clipboard.ts" },
   {
     packageName: "@interactive-os/json-document-canvas",
     symbol: "CanvasHand",
@@ -372,8 +382,8 @@ const registeredPublicUsages = [
     sourcePath: "packages/json-document-react/src/editing-snapshot.ts",
   },
   ...(["ObjectDocument", "CanvasDocument", "DocumentObject", "CanvasObject"] as const).map((symbol) => ({ packageName: "@interactive-os/json-document-object-document", symbol, sourcePath: "packages/json-document-object-document/src/object-model.ts" })),
-  ...(["assertObjectDocument", "assertCanvasDocument", "parseCanvasDocument", "serializeCanvasDocument"] as const).map((symbol) => ({ packageName: "@interactive-os/json-document-object-document", symbol, sourcePath: "packages/json-document-object-document/src/object-validation.ts" })),
-  ...(["createCanvasObject", "createCanvasPath", "projectObject", "transformObject"] as const).map((symbol) => ({ packageName: "@interactive-os/json-document-object-document", symbol, sourcePath: "packages/json-document-object-document/src/object-projection.ts" })),
+  ...(["assertObjectDocument", "assertCanvasDocument", "assertCanvasImageSource", "parseCanvasDocument", "serializeCanvasDocument"] as const).map((symbol) => ({ packageName: "@interactive-os/json-document-object-document", symbol, sourcePath: "packages/json-document-object-document/src/object-validation.ts" })),
+  ...(["createCanvasObject", "createCanvasPath", "createCanvasImage", "projectObject", "transformObject"] as const).map((symbol) => ({ packageName: "@interactive-os/json-document-object-document", symbol, sourcePath: "packages/json-document-object-document/src/object-projection.ts" })),
   {
     packageName: "@interactive-os/json-document-object-document",
     symbol: "planObjectOperation",
diff --git a/site/tests/browser/canvas-slice.spec.ts b/site/tests/browser/canvas-slice.spec.ts
index bc377483..010dbe8a 100644
--- a/site/tests/browser/canvas-slice.spec.ts
+++ b/site/tests/browser/canvas-slice.spec.ts
@@ -95,6 +95,37 @@ test("Canvas Alt-copy, nudge, duplicate and native selected clipboard share atom
   await expect(selected).toHaveCount(2);
 });
 
+test("Canvas captures real raster bytes before the native event ends and queues subsequent literal text", async ({ page }) => {
+  await page.goto("/demo/canvas");
+  const prevented = await page.evaluate(() => {
+    const raster = document.createElement("canvas"); raster.width = 1600; raster.height = 800;
+    const context = raster.getContext("2d")!; context.fillStyle = "#b6c8e8"; context.fillRect(0, 0, 1600, 800);
+    const bytes = Uint8Array.from(atob(raster.toDataURL("image/png").split(",")[1]!), (character) => character.charCodeAt(0));
+    const data = new DataTransfer(); data.items.add(new File([bytes], "clipboard.png", { type: "image/png" }));
+    data.setData("text/plain", "This fallback must not become an object");
+    const slide = document.querySelector("[data-canvas-slide]")!;
+    const image = new ClipboardEvent("paste", { clipboardData: data, bubbles: true, cancelable: true });
+    slide.dispatchEvent(image);
+    data.items.clear(); // Event data is ephemeral; preparation must use its captured snapshot.
+    const text = new DataTransfer(); text.setData("text/plain", "<b>한글</b>\nSecond line");
+    slide.dispatchEvent(new ClipboardEvent("paste", { clipboardData: text, bubbles: true, cancelable: true }));
+    return image.defaultPrevented;
+  });
+  expect(prevented).toBe(true);
+  await expect(page.locator("[data-canvas-object]")).toHaveCount(2);
+  await expect(page.locator("[data-canvas-slide]")).toHaveAttribute("aria-busy", "false");
+  await expect(page.locator("[data-canvas-slide] image")).toHaveAttribute("href", /^data:image\/png;base64,/);
+  await expect(page.locator("[data-canvas-slide] b")).toHaveCount(0);
+  await page.getByRole("button", { name: "JSON", exact: true }).click();
+  const saved = await page.getByRole("textbox", { name: "Canvas JSON document" }).inputValue();
+  const objects = JSON.parse(saved).objects;
+  expect(objects.map((object: { kind: string; x: number }) => [object.kind, object.x])).toEqual([["image", 24], ["text", 48]]);
+  expect(objects[0]).toMatchObject({ width: 960, height: 480, label: "clipboard.png" });
+  expect(objects[1].label).toBe("<b>한글</b>\nSecond line");
+  await page.getByRole("button", { name: "JSON 열기" }).click();
+  await expect(page.locator("[data-canvas-slide] image")).toHaveAttribute("href", objects[0].source);
+});
+
 test("Canvas move and resize are single history steps and Escape cancels a gesture", async ({ page }) => {
   await page.goto("/demo/canvas");
   await create(page, "사각형", [100, 100], [300, 200]);
diff --git a/site/tests/unit/demo-workbench.test.tsx b/site/tests/unit/demo-workbench.test.tsx
index 27319d8f..b07afd58 100644
--- a/site/tests/unit/demo-workbench.test.tsx
+++ b/site/tests/unit/demo-workbench.test.tsx
@@ -67,6 +67,11 @@ describe("Demo definition and source discovery", () => {
       ["packages/json-document-editing/src/object.ts", "/docs/api/editing"],
       ["packages/json-document-web/src/clipboard.ts", "/docs/api/web"],
       ["packages/json-document-canvas/src/use-canvas-hand.ts", "/docs/api/canvas"],
+      ["packages/json-document-canvas/src/canvas-clipboard.ts", "/docs/api/canvas"],
+      ["packages/json-document-editing/src/canvas-clipboard.ts", "/docs/api/editing"],
+      ["packages/json-document-editing/src/object-paste-session.ts", "/docs/api/editing"],
+      ["packages/json-document-web/src/raster-source.ts", "/docs/api/web"],
+      ["packages/json-document-file-intake/src/index.ts", "/docs/api/file-intake"],
     ]) {
       const file = sources.find((source) => source.path === path);
       expect(file, path).toBeDefined(); expect(file!.referencePath).toBe(reference);

From dc981abbb25352d9cd733c41a72b0266477cbab6 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E1=84=8B=E1=85=B2=E1=84=8B=E1=85=AD=E1=86=BC=E1=84=90?=
 =?UTF-8?q?=E1=85=A2?= <teo.v@navercorp.com>
Date: Wed, 9 Sep 2026 21:53:22 +0900
Subject: [PATCH 14/20] =?UTF-8?q?feat(clipboard):=20=EC=9D=B4=EB=AF=B8?=
 =?UTF-8?q?=EC=A7=80=20=EC=A4=80=EB=B9=84=20=EC=A0=95=EB=B3=B8=EA=B3=BC=20?=
 =?UTF-8?q?Composer=20=EC=B2=A8=EB=B6=80=20=EA=B8=B0=EB=B3=B8=EA=B8=B0?=
 =?UTF-8?q?=EB=A5=BC=20=EC=97=B0=EA=B2=B0=ED=95=9C=EB=8B=A4?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 docs/api-reference/composer-react.md          |   6 +
 docs/api-reference/composer.md                |   8 +-
 docs/api-reference/editing.md                 |  24 ++++
 docs/api-reference/file-intake.md             |  19 +++
 docs/api-reference/web.md                     |  22 +++-
 docs/public/adapter-clipboard.md              |  17 ++-
 docs/public/clipboard.md                      |  28 +++++
 docs/public/composer.md                       |  24 ++++
 package-lock.json                             |   8 +-
 .../src/canvas-clipboard.ts                   |  20 +---
 .../json-document-composer-react/README.md    |  37 ++++++
 .../json-document-composer-react/package.json |   4 +
 .../src/attachments.ts                        |  57 +++++++++
 .../src/use-composer.tsx                      |  54 +++++----
 .../tests/composer-attachments.test.tsx       | 110 ++++++++++++++++++
 .../tsconfig.json                             |   2 +
 packages/json-document-composer/README.md     |  19 +++
 .../json-document-composer/src/commands.ts    |  15 ++-
 packages/json-document-composer/src/model.ts  |  10 +-
 .../tests/composer.test.ts                    |  35 ++++++
 packages/json-document-editing/README.md      |  18 +++
 packages/json-document-editing/src/index.ts   |   1 +
 .../src/object-paste-session.ts               | 105 ++++++-----------
 .../src/preparation-queue.ts                  |  80 +++++++++++++
 .../tests/preparation-queue.test.ts           |  56 +++++++++
 packages/json-document-file-intake/README.md  |  18 +++
 .../json-document-file-intake/src/index.ts    |   2 +
 .../src/raster-content.ts                     |  30 +++++
 .../tests/raster-content.test.ts              |  16 +++
 .../package.json                              |   4 +-
 .../src/object-validation.ts                  |  14 +--
 .../tsconfig.json                             |   2 +-
 packages/json-document-web/README.md          |  28 +++--
 packages/json-document-web/docs/clipboard.md  |  19 ++-
 packages/json-document-web/src/clipboard.ts   |   6 +-
 packages/json-document-web/src/index.ts       |   1 +
 .../json-document-web/src/raster-files.ts     |  44 +++++++
 .../tests/raster-files.test.ts                |  52 +++++++++
 site/src/shared/composer/ComposerDemo.tsx     |  17 ++-
 site/src/shared/composer/composer.css         |   2 +
 .../src/shared/demo-workbench/demo-sources.ts |  13 +++
 site/tests/browser/composer-demo.spec.ts      |  20 +++-
 site/tests/unit/composer-demo.test.tsx        |  27 ++++-
 site/tests/unit/demo-workbench.test.tsx       |   4 +
 standards/editing-grammar.md                  |  27 +++++
 45 files changed, 965 insertions(+), 160 deletions(-)
 create mode 100644 packages/json-document-composer-react/src/attachments.ts
 create mode 100644 packages/json-document-composer-react/tests/composer-attachments.test.tsx
 create mode 100644 packages/json-document-editing/src/preparation-queue.ts
 create mode 100644 packages/json-document-editing/tests/preparation-queue.test.ts
 create mode 100644 packages/json-document-file-intake/src/raster-content.ts
 create mode 100644 packages/json-document-file-intake/tests/raster-content.test.ts
 create mode 100644 packages/json-document-web/src/raster-files.ts
 create mode 100644 packages/json-document-web/tests/raster-files.test.ts

diff --git a/docs/api-reference/composer-react.md b/docs/api-reference/composer-react.md
index 61f51535..ac7dd7a1 100644
--- a/docs/api-reference/composer-react.md
+++ b/docs/api-reference/composer-react.md
@@ -18,6 +18,10 @@ interface ComposerBinding<Model extends string, Suggestion extends ComposerHostS
   readonly attachments: ComposerDraft<Model>["attachments"];
   readonly model: Model;
   readonly hasContent: boolean;
+  readonly isPreparingAttachments: boolean;
+  readonly attachmentError: EditingPreparationFailure | null;
+  readonly canSubmit: boolean;
+  cancelAttachments(): void;
   readonly commandKind: "mention" | "skill" | null;
   readonly commandMenu: RichTextSuggestionBinding<Suggestion>;
   readonly commandOpen: boolean;
@@ -61,6 +65,8 @@ interface UseComposerOptions<Model extends string, Suggestion extends ComposerHo
   readonly id: string;
   readonly config: ComposerHostConfig<Model> & { readonly suggestions: ReadonlyArray<Suggestion> };
   readonly ports: ComposerHostPorts<Model>;
+  readonly maxImagePixels?: number;
+  readonly readRaster?: typeof readWebRasterFile;
   readonly labels: {
     readonly mentionSuggestions: string;
     readonly skillSuggestions: string;
diff --git a/docs/api-reference/composer.md b/docs/api-reference/composer.md
index f182ef1a..2ace50e4 100644
--- a/docs/api-reference/composer.md
+++ b/docs/api-reference/composer.md
@@ -34,18 +34,20 @@ const COMPOSER_SKILL_NODE: "os.interactive/skill"
 ## `ComposerAttachment`
 
 ```ts
-interface ComposerAttachment extends Record<string, JSONValue> {
+type ComposerAttachment = Record<string, JSONValue> & {
   readonly id: string;
   readonly kind: "document" | "image";
   readonly name: string;
   readonly size: number;
   readonly mediaType: string | null;
-}
+  /** Absent for metadata-only attachments. Presence retains actual embedded raster content. */
+  readonly image?: RasterImageContent;
+};
 ```
 ## `ComposerAttachmentCandidate`
 
 ```ts
-type ComposerAttachmentCandidate = FileCandidate;
+type ComposerAttachmentCandidate = FileCandidate & { readonly image?: RasterImageContent };
 ```
 ## `ComposerAttachmentPolicy`
 
diff --git a/docs/api-reference/editing.md b/docs/api-reference/editing.md
index 16fb0002..c681de1c 100644
--- a/docs/api-reference/editing.md
+++ b/docs/api-reference/editing.md
@@ -588,6 +588,11 @@ createEditingId(prefix: string): string
 ```ts
 createEditingIdAllocator(existingIds: Iterable<string>, createId: () => string, subject: string): () => string
 ```
+## `createEditingPreparationQueue`
+
+```ts
+createEditingPreparationQueue<Value, Result extends { readonly ok: boolean; }>(options: { readonly apply: (value: Value) => Result; readonly onResult?: (result: Result | EditingPreparationFailure) => void; readonly onPendingChange?: (pending: boolean) => void; readonly cancelCode?: string; readonly errorCode?: string; }): EditingPreparationQueue<Value, Result>
+```
 ## `createEditingSession`
 
 ```ts
@@ -995,6 +1000,25 @@ interface EditingPlan<Selection extends JSONValue> {
   readonly historyGroup?: string;
 }
 ```
+## `EditingPreparation`
+
+```ts
+type EditingPreparation<Value> = { readonly ok: true; readonly value: Value } | EditingPreparationFailure;
+```
+## `EditingPreparationFailure`
+
+```ts
+type EditingPreparationFailure = { readonly ok: false; readonly code: string; readonly reason?: string };
+```
+## `EditingPreparationQueue`
+
+```ts
+interface EditingPreparationQueue<Value, Result> {
+  readonly isPending: boolean;
+  enqueue(prepare: () => EditingPreparation<Value> | Promise<EditingPreparation<Value>>, cancelPreparation?: () => void): Promise<Result | EditingPreparationFailure>;
+  cancel(): void;
+}
+```
 ## `EditingResult`
 
 ```ts
diff --git a/docs/api-reference/file-intake.md b/docs/api-reference/file-intake.md
index 19b5174d..620a0365 100644
--- a/docs/api-reference/file-intake.md
+++ b/docs/api-reference/file-intake.md
@@ -6,6 +6,16 @@
 
 > 이 문서는 `packages/json-document-file-intake/src/index.ts`에서 생성됩니다. API를 변경한 뒤 `npm run docs:api`를 실행하세요.
 
+## `assertRasterImageContent`
+
+```ts
+assertRasterImageContent(value: unknown): asserts value is RasterImageContent
+```
+## `assertRasterImageSource`
+
+```ts
+assertRasterImageSource(source: unknown): asserts source is string
+```
 ## `FileAcceptancePolicy`
 
 ```ts
@@ -36,6 +46,15 @@ type FileIntakeResult<Candidate extends FileCandidate = FileCandidate> =
 ```ts
 formatFileSize(bytes: number): string
 ```
+## `RasterImageContent`
+
+```ts
+interface RasterImageContent extends Record<string, JSONValue> {
+  readonly source: string;
+  readonly width: number;
+  readonly height: number;
+}
+```
 ## `validateFileCandidates`
 
 ```ts
diff --git a/docs/api-reference/web.md b/docs/api-reference/web.md
index 5d927398..50b27b26 100644
--- a/docs/api-reference/web.md
+++ b/docs/api-reference/web.md
@@ -39,7 +39,7 @@ calendarMinutesFromWebGrid(clientY: number, bounds: { readonly top: number; read
 ## `captureWebClipboardPaste`
 
 ```ts
-captureWebClipboardPaste<Payload extends WebClipboardPayload>(event: WebClipboardEvent, options: { readonly codec: WebClipboardCodec<Payload>; readonly files?: boolean; readonly text?: boolean; }): WebClipboardPaste<Payload>
+captureWebClipboardPaste<Payload extends WebClipboardPayload = WebClipboardPayload>(event: WebClipboardEvent, options: { readonly codec?: WebClipboardCodec<Payload>; readonly files?: boolean; readonly text?: boolean; }): WebClipboardPaste<Payload>
 ```
 ## `chordFromStroke`
 
@@ -223,6 +223,11 @@ projectWebWidgetState(state: WebWidgetState): WebWidgetARIA
 ```ts
 readWebRasterFile(file: WebRasterFile, options?: { readonly signal?: WebRasterReadSignal; }): Promise<WebRasterSourceResult>
 ```
+## `readWebRasterFiles`
+
+```ts
+readWebRasterFiles(files: ReadonlyArray<WebFileCandidate>, options: { readonly policy: FileAcceptancePolicy; readonly maxImagePixels: number; readonly signal?: WebRasterReadSignal; readonly readRaster?: typeof readWebRasterFile; }): Promise<WebRasterFilesResult>
+```
 ## `registerWebVirtualSelectionScope`
 
 ```ts
@@ -784,6 +789,21 @@ interface WebRasterFile {
   readonly type: string;
 }
 ```
+## `WebRasterFileContent`
+
+```ts
+interface WebRasterFileContent {
+  readonly candidate: FileCandidate;
+  readonly image: RasterImageContent;
+}
+```
+## `WebRasterFilesResult`
+
+```ts
+type WebRasterFilesResult =
+  | { readonly ok: true; readonly files: ReadonlyArray<WebRasterFileContent> }
+  | { readonly ok: false; readonly code: string; readonly reason?: string };
+```
 ## `WebRasterReadSignal`
 
 ```ts
diff --git a/docs/public/adapter-clipboard.md b/docs/public/adapter-clipboard.md
index 6e919b4c..ab1d1454 100644
--- a/docs/public/adapter-clipboard.md
+++ b/docs/public/adapter-clipboard.md
@@ -43,8 +43,21 @@ interface WebClipboardSurface<Payload, EditingResult> {
 ```
 
 모든 handler는 같은 binding lifecycle을 사용하고 결과를 `onResult`에 한 번
-전달한 뒤 그 결과를 반환합니다. payload 의미, paste policy, 사용자 메시지와
-관찰 상태는 Host 책임입니다.
+전달한 뒤 그 결과를 반환합니다. payload 의미와 문서 반영은 정본 Editing·Hand가
+소유하며 Host는 제품 policy 값, 사용자 메시지와 관찰 표현을 주입합니다.
+
+## 외부 이미지 입력 준비
+
+`captureWebClipboardPaste(event, { codec?, files?, text? })`는 event가 끝나기 전에
+활성화한 표현을 한 번만 선택합니다. Codec을 생략한 `{ files: true }`는 이미지 첨부를
+처리하고, 파일이 없는 text·HTML은 기존 Rich Text binding에 남깁니다.
+`readWebRasterFiles`는 선택한 파일 batch의 정책·PNG/JPEG/WebP decode를 검증하고
+실제 내용과 크기를 반환합니다. 이 단계는 문서나 History를 변경하지 않습니다.
+
+API 계약은 소유 패키지의 [Web API](/docs/api/web)에 있으며
+[Canvas](/demo/canvas)와 [Composer](/demo/composer)가 같은 준비 경로를 사용합니다.
+HTML 이미지·혼합 입력과 외부 앱 왕복은 [Paste × Image TBD](clipboard.md#paste--image-기본기--tbd)에
+구현 범위와 구분해 공개합니다.
 
 ## `createWebClipboardTextWriter`
 
diff --git a/docs/public/clipboard.md b/docs/public/clipboard.md
index dcab4545..b8dbe585 100644
--- a/docs/public/clipboard.md
+++ b/docs/public/clipboard.md
@@ -49,6 +49,34 @@ if (cut?.result.ok) {
 행과 열 순서를 유지합니다. [History](history.md)는 이렇게 기록된 문서 값과
 Selection을 함께 복원합니다.
 
+## Paste × Image 기본기 — TBD
+
+Clipboard의 기본기는 다른 앱에서 가져온 내용을 편집 가능한 문서로 받아들이고,
+다시 다른 앱에 전달하는 과정까지 포함합니다. 아래 TBD는 지원 약속의 목표이며,
+현재 API가 모두 구현했다는 뜻은 아닙니다.
+
+| 기본기 | 현재 범위 / TBD | 완료를 판단할 동작 | 정본 |
+| --- | --- | --- | --- |
+| 이미지 파일 입력 | Canvas·Composer 공통 경로 구현 | PNG/JPEG/WebP를 실제로 읽고 표시하며, 실패 batch는 삽입하지 않음 | File Intake·Web·각 Hand |
+| 이미지 내용 보존 | Canvas 객체·Composer 첨부에 포함 | Undo/Redo·JSON 왕복·Composer submit, Canvas 구조 복사 후에도 내용과 치수 유지 | 각 문서 모델·Editing |
+| 비동기 편집 | 공통 순서·취소 queue 구현 | 연속 요청 순서 유지, 취소 후 늦은 삽입 없음; Composer는 준비 중 타이핑 가능 | Editing·각 Hand |
+| HTML 이미지·글과 이미지 | TBD | HTML 안의 이미지와 글의 순서를 지원하는 문서 의미로 변환; 읽을 수 없는 이미지는 실패를 알림 | Web·Rich Text Web·각 문서 모델 |
+| 서식 없이 붙여넣기 | 명시적인 공통 입력 계약 TBD | 서식 붙여넣기와 plain text 선택을 구별하고 native 입력을 침범하지 않음 | Web·Affordance·각 Hand |
+| 이미지로 복사 | Canvas TBD | 선택한 글·도형·이미지를 PNG로 복사해 외부 앱에 붙임; 실패가 문서를 바꾸지 않음 | Canvas·Web |
+| 실제 플랫폼 왕복 | OS-native 검증 TBD | 스크린샷·브라우저 이미지·Docs/Slides에서 실제 복사하여 붙이고, 외부 앱으로 다시 전달 | Web·제품 경로 검증 |
+
+한 항목의 HTML·텍스트·PNG는 같은 내용의 대체 표현일 수 있습니다. 이를 모두
+별개 내용으로 삽입하지 않습니다. 반면 선택한 HTML 표현 안의 글·이미지는 함께
+보존해야 할 내용일 수 있습니다. 표현 선택과 문서 내용 변환은 다른 결정입니다.
+[Clipboard 표현 모델](https://www.w3.org/TR/clipboard-apis/#clipboard-interface)은
+이 구분을 설명합니다. [Docs·Slides의 이미지 복사](https://support.google.com/docs/answer/161768?hl=en)도
+외부 앱에는 HTML로 전달되므로 HTML 이미지를 고급 문서 import만의 문제로 보지 않습니다.
+
+Canvas는 평면 객체, Composer는 instruction과 첨부 목록을 결과로 만듭니다.
+같은 입력을 받아도 Canvas 좌표를 Composer에 넣거나, 첨부 목록을 Rich Text의
+inline 이미지처럼 설명하지 않습니다. 서버 업로드, 임의 외부 URL의 가져오기,
+Office 전체 레이아웃 재현은 아직 지원하지 않습니다.
+
 ## Live Demo
 
 ```live-demo
diff --git a/docs/public/composer.md b/docs/public/composer.md
index 98c7551e..5f1d3ce6 100644
--- a/docs/public/composer.md
+++ b/docs/public/composer.md
@@ -24,6 +24,9 @@ Composer의 instruction은 Rich Text extension profile을 사용하는 canonical
 사람·agent와 skill은 안정 ID를 가진 inline atom입니다. 첨부 자료도 보이는 파일명과
 별개인 ID를 가진 context로 같은 draft에 남습니다. native contenteditable은 입력,
 Selection, IME, structured Clipboard와 history를 기존 Rich Text editor에 위임합니다.
+PNG·JPEG·WebP 첨부는 파일 정보에 실제 이미지 내용과 원본 크기를 함께 보존합니다.
+이미지 내용이 없는 기존 attachment는 metadata-only이며, 두 상태를 같은 것으로
+표시하지 않습니다.
 
 ## Public contract
 
@@ -38,6 +41,7 @@ Selection, IME, structured Clipboard와 history를 기존 Rich Text editor에 
 `@interactive-os/json-document-file-intake`의 `validateFileCandidates`로 공통 파일
 후보와 수용 정책을 검증한 뒤 Host가 주입한 ID로 Composer attachment를 만들며,
 검증 실패를 명시적인 Composer command 결과로 번역합니다.
+이미지가 있으면 같은 File Intake의 `RasterImageContent` 계약도 검증합니다.
 호환용 `findComposerTrigger`와 `resolveComposerSuggestions`도 공용 Rich Text Suggestion
 계약에 위임합니다.
 
@@ -61,6 +65,18 @@ Web `File`과 `ClipboardEvent`에서 이름·크기·media type을 읽는 일은
 `@interactive-os/json-document-file-intake`의 `FileCandidate`입니다. Composer domain은
 DOM과 Web object를 알지 않으며, Web adapter는 ID·허용 정책·attachment kind를 결정하지 않습니다.
 
+파일 선택·drop·paste의 이미지 준비는 Web `readWebRasterFiles`를 함께 사용합니다.
+Editing `createEditingPreparationQueue`가 완료 순서와 무관하게 입력 순서대로 반영하며,
+한 요청의 실패는 일부 첨부나 Undo 기록을 남기지 않습니다. 준비 중에도 instruction을
+계속 고칠 수 있고, 완료 시점의 최신 첨부 목록에 붙입니다. 이는 inline 문서의 paste
+anchor를 추적하는 기능과는 다릅니다.
+
+`useComposer`의 `isPreparingAttachments`, `attachmentError`, `canSubmit`,
+`cancelAttachments()`로 준비·실패·취소 상태를 표현합니다. 준비 중에는 submit을 막고,
+Escape·binding의 Undo/Redo·unmount는 늦은 결과의 삽입을 취소합니다. 외부에서 draft를
+교체하거나 editor의 History API를 직접 호출할 때도 먼저 `cancelAttachments()`를 호출합니다.
+첨부 완료는 현재 caret이나 focus를 옮기지 않습니다.
+
 Host는 config 값과 runtime port를 주입하고 composer의 배치, copy, CSS와 첨부 preview를
 그립니다. 파일 metadata 표시는 File Intake 정본의 `formatFileSize`를 사용합니다.
 후보 자료·제품 copy·권한은 Host가 정하지만 suggestion open/dismiss, keyboard focus,
@@ -68,6 +84,14 @@ pointer active state와 mention 삽입 lifecycle은 정본 Hands가 소유합니
 검색 source, 파일 저장소, Agent runtime, transcript, think·stream·tool 상태는
 Composer가 소유하지 않습니다.
 
+## 이미지와 Clipboard의 남은 기본기
+
+[Paste × Image TBD](clipboard.md#paste--image-기본기--tbd)에 HTML 이미지·혼합 입력,
+명시적인 plain paste, 이미지로 복사와 OS-native round-trip의 소유자·기대 결과를
+미리 공개합니다. 현재 Composer 이미지 slice는 별도 첨부 목록에 내용을 보존하는
+단계이며 inline 혼합 입력을 구현한 것은 아닙니다. 서버 업로드와 자산 저장소는
+별도 계약이고, 이미지 외 파일은 현재 파일 정보만 보존합니다.
+
 ```live-demo
 /demo/composer
 ```
diff --git a/package-lock.json b/package-lock.json
index c3ccc2d9..9feea7c2 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -6691,6 +6691,8 @@
       "devDependencies": {
         "@interactive-os/json-document": "*",
         "@interactive-os/json-document-composer": "*",
+        "@interactive-os/json-document-editing": "*",
+        "@interactive-os/json-document-file-intake": "*",
         "@interactive-os/json-document-rich-text": "*",
         "@interactive-os/json-document-rich-text-mention": "*",
         "@interactive-os/json-document-rich-text-mention-react": "*",
@@ -6711,6 +6713,8 @@
       "peerDependencies": {
         "@interactive-os/json-document": "^3.0.0",
         "@interactive-os/json-document-composer": "^0.1.0-rc.0",
+        "@interactive-os/json-document-editing": ">=0.1.0-rc.0 <1",
+        "@interactive-os/json-document-file-intake": "^0.1.0-rc.0",
         "@interactive-os/json-document-rich-text": "^0.1.0-rc.0",
         "@interactive-os/json-document-rich-text-mention": "^0.1.0-rc.0",
         "@interactive-os/json-document-rich-text-mention-react": "^0.1.0-rc.0",
@@ -6845,12 +6849,14 @@
       "license": "MIT",
       "devDependencies": {
         "@interactive-os/json-document": "*",
+        "@interactive-os/json-document-file-intake": "*",
         "@types/node": "^25.9.0",
         "typescript": "^5.0.0",
         "vitest": "^4.1.7"
       },
       "peerDependencies": {
-        "@interactive-os/json-document": "^3.0.0"
+        "@interactive-os/json-document": "^3.0.0",
+        "@interactive-os/json-document-file-intake": "^0.1.0-rc.0"
       }
     },
     "packages/json-document-react": {
diff --git a/packages/json-document-canvas/src/canvas-clipboard.ts b/packages/json-document-canvas/src/canvas-clipboard.ts
index ac79bd1e..63b33b34 100644
--- a/packages/json-document-canvas/src/canvas-clipboard.ts
+++ b/packages/json-document-canvas/src/canvas-clipboard.ts
@@ -1,7 +1,7 @@
 import { createCanvasClipboard, createObjectPasteSession, type CanvasClipboardOptions, type EditingResult, type ObjectEditor, type ObjectPastePreparation, type ObjectSelection } from "@interactive-os/json-document-editing";
-import { validateFileCandidates, type FileAcceptancePolicy } from "@interactive-os/json-document-file-intake";
+import type { FileAcceptancePolicy } from "@interactive-os/json-document-file-intake";
 import { assertCanvasDocument } from "@interactive-os/json-document-object-document";
-import { captureWebClipboardPaste, createWebClipboardBinding, fileCandidatesFromWebFiles, objectClipboardCodec, readWebRasterFile, type WebClipboardEvent, type WebFileCandidate } from "@interactive-os/json-document-web";
+import { captureWebClipboardPaste, createWebClipboardBinding, objectClipboardCodec, readWebRasterFile, readWebRasterFiles, type WebClipboardEvent, type WebFileCandidate } from "@interactive-os/json-document-web";
 
 export interface CanvasClipboardPolicy {
   readonly textColor: string;
@@ -34,18 +34,10 @@ export function createCanvasClipboardBinding(editor: ObjectEditor, policy: Canva
     return { bounds: { x: 0, y: 0, width: document.width * 0.75, height: document.height * 0.75 }, textColor: policy.textColor, fontSize: policy.fontSize };
   }
   async function images(candidates: readonly WebFileCandidate[], content: CanvasClipboardOptions, signal: AbortSignal): Promise<ObjectPastePreparation> {
-    const accepted = validateFileCandidates(fileCandidatesFromWebFiles(candidates), files);
-    if (!accepted.ok) return accepted;
-    const decoded = [];
-    // Decode a batch sequentially to bound peak memory; adoption remains atomic.
-    for (const file of candidates) {
-      const image = await (options.readRaster ?? readWebRasterFile)(file, { signal });
-      if (!image.ok) return image;
-      if (signal.aborted) return { ok: false, code: "clipboard.cancelled" };
-      if (!Number.isFinite(image.width * image.height) || image.width * image.height > maxPixels) return { ok: false, code: "raster.pixel-limit" };
-      decoded.push({ source: image.dataURL, width: image.width, height: image.height, label: file.name });
-    }
-    return { ok: true, clipboard: createCanvasClipboard({ type: "images", images: decoded }, content) };
+    const prepared = await readWebRasterFiles(candidates, { policy: files, maxImagePixels: maxPixels, signal, readRaster: options.readRaster ?? readWebRasterFile });
+    return prepared.ok
+      ? { ok: true, clipboard: createCanvasClipboard({ type: "images", images: prepared.files.map(({ candidate, image }) => ({ ...image, label: candidate.name })) }, content) }
+      : prepared;
   }
   return {
     get pending() { return session.pending; },
diff --git a/packages/json-document-composer-react/README.md b/packages/json-document-composer-react/README.md
index cbb26934..4ed2d53a 100644
--- a/packages/json-document-composer-react/README.md
+++ b/packages/json-document-composer-react/README.md
@@ -20,3 +20,40 @@ composed from the canonical suggestion packages.
 Product copy, styling, layout, suggestions, and concrete ports remain Host-owned.
 Draft/editor subscription, suggestion integration, keyboard/history execution, Web file
 intake, focus recovery, and submit lifecycle remain canonical across Host replacements.
+
+## 이미지 준비와 편집
+
+`useComposer`의 `addWebFiles`, `handlePaste`, `handleFileInputChange`는 같은 파일 입력 경로를
+사용합니다. Web `readWebRasterFiles`가 PNG/JPEG/WebP를 실제로 decode하고,
+Editing `createEditingPreparationQueue`가 준비 완료와 무관하게 요청 순서를 유지합니다.
+일반 파일은 기존 metadata-only 첨부로 남으며 `image`가 있는 첨부만 실제 내용을 보존합니다.
+
+| API | 계약 |
+| --- | --- |
+| `isPreparingAttachments` | 아직 완료하지 않은 첨부 준비가 있음 |
+| `attachmentError` | 가장 최근 실패의 `code`와 선택적 `reason`, 성공/새 입력/취소 시 초기화 |
+| `cancelAttachments()` | 대기 batch를 취소하고 실제 파일 읽기를 중단; 늦은 결과는 반영하지 않음 |
+| `canSubmit` | 내용이 있고 대기 중인 첨부가 없음 |
+| `submit()` | 최신 draft를 사용하며, 준비 중에는 호출해도 submit port를 실행하지 않음 |
+| `maxImagePixels?` | 이미지당 decode 후 픽셀 제한, 기본 16,000,000 |
+| `readRaster?` | Web reader의 대체 instance 주입. 테스트·환경 연결용이며 문서 모델을 바꾸지 않음 |
+
+파일 수·byte 제한과 허용 media type은 기존 `config.attachments`가 결정합니다.
+정책은 읽기 전에 검사하고, 실제 추가 직전 최신 첨부 수와 정책으로 다시 검사합니다.
+실패한 batch는 첨부와 History를 일부만 남기지 않습니다. 추가는 최신 첨부 목록의 끝에서
+이루어지므로 준비 중 typing/caret 이동은 유지하며 현재 text selection을 덮어쓰지 않습니다.
+늦은 완료가 focus를 빼앗지 않습니다. 파일 선택 창을 닫을 때만 editor focus를 복구합니다.
+
+Escape, `cancelAttachments`, `handleHistoryKeyDown`의 Undo/Redo, unmount는 준비를 취소합니다.
+직접 `editor.undo/redo` 또는 외부 문서 교체를 수행하는 소비자는 먼저 `cancelAttachments()`를
+호출합니다. queue 자체는 문서 History나 text 삽입 위치 mapping을 대신하지 않습니다.
+React Host는 `handlePaste`와 `handleHistoryKeyDown`을 감싸는 surface의 capture handler에,
+`handleKeyDown`은 editor에 연결하고 상태/실패를 표시합니다.
+
+파일이 있는 paste는 Web에서 동기 캡처하고 한 번만 처리합니다. 파일이 없는 텍스트/HTML은
+기존 Rich Text 경로에 위임합니다. HTML 이미지·글+이미지 변환은 아직 TBD이며,
+파일과 HTML 양쪽의 내용을 모두 별개로 추가하지 않습니다.
+
+Usage와 Source: [Composer](/demo/composer). PNG/JPEG/WebP의 내용·미리보기·삭제·Undo/Redo와
+submit payload를 확인할 수 있습니다. 서버 upload와 OS-native Clipboard 호환성 완료를
+주장하지 않습니다.
diff --git a/packages/json-document-composer-react/package.json b/packages/json-document-composer-react/package.json
index dc60a801..63657085 100644
--- a/packages/json-document-composer-react/package.json
+++ b/packages/json-document-composer-react/package.json
@@ -22,6 +22,8 @@
   "peerDependencies": {
     "@interactive-os/json-document": "^3.0.0",
     "@interactive-os/json-document-composer": "^0.1.0-rc.0",
+    "@interactive-os/json-document-editing": ">=0.1.0-rc.0 <1",
+    "@interactive-os/json-document-file-intake": "^0.1.0-rc.0",
     "@interactive-os/json-document-rich-text": "^0.1.0-rc.0",
     "@interactive-os/json-document-rich-text-mention": "^0.1.0-rc.0",
     "@interactive-os/json-document-rich-text-mention-react": "^0.1.0-rc.0",
@@ -34,6 +36,8 @@
   "devDependencies": {
     "@interactive-os/json-document": "*",
     "@interactive-os/json-document-composer": "*",
+    "@interactive-os/json-document-editing": "*",
+    "@interactive-os/json-document-file-intake": "*",
     "@interactive-os/json-document-rich-text": "*",
     "@interactive-os/json-document-rich-text-mention": "*",
     "@interactive-os/json-document-rich-text-mention-react": "*",
diff --git a/packages/json-document-composer-react/src/attachments.ts b/packages/json-document-composer-react/src/attachments.ts
new file mode 100644
index 00000000..cb709333
--- /dev/null
+++ b/packages/json-document-composer-react/src/attachments.ts
@@ -0,0 +1,57 @@
+import type { JSONDocument } from "@interactive-os/json-document";
+import { addComposerAttachments, createComposerAttachments, type ComposerAttachmentCandidate, type ComposerAttachmentPolicy, type ComposerDraft, type ComposerDraftCommandResult } from "@interactive-os/json-document-composer";
+import { createEditingPreparationQueue, type EditingPreparation, type EditingPreparationFailure } from "@interactive-os/json-document-editing";
+import { validateFileCandidates } from "@interactive-os/json-document-file-intake";
+import type { RichTextEditor } from "@interactive-os/json-document-rich-text";
+import { fileCandidatesFromWebFiles, readWebRasterFiles, type readWebRasterFile, type WebFileCandidate, type WebFileCandidateList } from "@interactive-os/json-document-web";
+import { useEffect, useRef, useState } from "react";
+
+/** Composer appends attachments, so typing and caret changes do not invalidate preparation. */
+export function useComposerAttachments(document: JSONDocument, editor: RichTextEditor, options: {
+  readonly policy: ComposerAttachmentPolicy;
+  readonly createId: () => string;
+  readonly maxImagePixels?: number;
+  readonly readRaster?: typeof readWebRasterFile;
+}) {
+  const current = useRef(options);
+  current.current = options;
+  const [isPending, setPending] = useState(false);
+  const [error, setError] = useState<EditingPreparationFailure | null>(null);
+  const [queue] = useState(() => createEditingPreparationQueue<ReadonlyArray<ComposerAttachmentCandidate>, ComposerDraftCommandResult>({
+    apply(candidates) {
+      const draft = document.value as ComposerDraft;
+      const created = createComposerAttachments(candidates, { createId: current.current.createId, policy: current.current.policy, currentCount: draft.attachments.length });
+      return created.ok ? addComposerAttachments(editor, draft, created.attachments) : created;
+    },
+    onPendingChange: setPending,
+    onResult: (result) => { setError(result.ok ? null : result); },
+  }));
+  useEffect(() => () => queue.cancel(), [queue]);
+
+  function addFiles(input: WebFileCandidateList | ReadonlyArray<WebFileCandidate>) {
+    // Snapshot File references while a paste/drop event still owns them.
+    const files = Array.from(input as ArrayLike<WebFileCandidate>);
+    if (files.length === 0) return;
+    setError(null);
+    const controller = new AbortController();
+    const policy = current.current.policy;
+    const maxImagePixels = current.current.maxImagePixels ?? 16_000_000;
+    const readRaster = current.current.readRaster;
+    void queue.enqueue(() => {
+      const candidates = fileCandidatesFromWebFiles(files);
+      const accepted = validateFileCandidates(candidates, policy, { currentCount: (document.value as ComposerDraft).attachments.length });
+      if (!accepted.ok) return accepted;
+      const images = files.filter((file) => file.type.startsWith("image/"));
+      if (images.length === 0) return { ok: true, value: candidates };
+      return readWebRasterFiles(images, { policy, maxImagePixels, signal: controller.signal, ...(readRaster ? { readRaster } : {}) }).then((prepared): EditingPreparation<ReadonlyArray<ComposerAttachmentCandidate>> => {
+        if (!prepared.ok) return prepared;
+        let imageIndex = 0;
+        return { ok: true, value: candidates.map((candidate) => candidate.mediaType?.startsWith("image/")
+          ? { ...candidate, image: prepared.files[imageIndex++]!.image }
+          : candidate) };
+      });
+    }, () => controller.abort());
+  }
+
+  return { isPending, error, addFiles, reportError: setError, cancel: () => { queue.cancel(); setError(null); }, hasPending: () => queue.isPending };
+}
diff --git a/packages/json-document-composer-react/src/use-composer.tsx b/packages/json-document-composer-react/src/use-composer.tsx
index 733a3fa1..71904739 100644
--- a/packages/json-document-composer-react/src/use-composer.tsx
+++ b/packages/json-document-composer-react/src/use-composer.tsx
@@ -1,9 +1,7 @@
 import { createJSONDocument, type JSONDocument } from "@interactive-os/json-document";
 import {
-  addComposerAttachments,
   composerInteractionFromKeyStroke,
   composerSchema,
-  createComposerAttachments,
   createComposerDraft,
   hasComposerContent,
   insertComposerText,
@@ -17,15 +15,19 @@ import {
 import { createRichTextEditor, type RichTextEditor, type RichTextNode } from "@interactive-os/json-document-rich-text";
 import type { RichTextSuggestionCandidate } from "@interactive-os/json-document-rich-text-suggestion";
 import type { RichTextSuggestionBinding } from "@interactive-os/json-document-rich-text-suggestion-react";
-import { fileCandidatesFromWebClipboard, fileCandidatesFromWebFiles, type WebFileCandidate, type WebFileCandidateList } from "@interactive-os/json-document-web";
+import { captureWebClipboardPaste, type readWebRasterFile, type WebFileCandidate, type WebFileCandidateList } from "@interactive-os/json-document-web";
+import type { EditingPreparationFailure } from "@interactive-os/json-document-editing";
 import { useCallback, useRef, useState, useSyncExternalStore, type ChangeEvent, type ClipboardEvent, type KeyboardEvent, type ReactNode } from "react";
 import { ComposerReferenceAtom, type ComposerReferenceAtomProps } from "./reference-atom.js";
 import { useComposerCommandMenu } from "./command-menu.js";
+import { useComposerAttachments } from "./attachments.js";
 
 export interface UseComposerOptions<Model extends string, Suggestion extends ComposerHostSuggestion & RichTextSuggestionCandidate> {
   readonly id: string;
   readonly config: ComposerHostConfig<Model> & { readonly suggestions: ReadonlyArray<Suggestion> };
   readonly ports: ComposerHostPorts<Model>;
+  readonly maxImagePixels?: number;
+  readonly readRaster?: typeof readWebRasterFile;
   readonly labels: {
     readonly mentionSuggestions: string;
     readonly skillSuggestions: string;
@@ -41,6 +43,10 @@ export interface ComposerBinding<Model extends string, Suggestion extends Compos
   readonly attachments: ComposerDraft<Model>["attachments"];
   readonly model: Model;
   readonly hasContent: boolean;
+  readonly isPreparingAttachments: boolean;
+  readonly attachmentError: EditingPreparationFailure | null;
+  readonly canSubmit: boolean;
+  cancelAttachments(): void;
   readonly commandKind: "mention" | "skill" | null;
   readonly commandMenu: RichTextSuggestionBinding<Suggestion>;
   readonly commandOpen: boolean;
@@ -77,37 +83,38 @@ export function useComposer<Model extends string, Suggestion extends ComposerHos
   const fileInputRef = useRef<HTMLInputElement>(null);
   const commandMenu = useComposerCommandMenu({ id: options.id, editor, document: draft.instruction, suggestions: config.suggestions, createId: ports.createId, labels: options.labels });
   const content = hasComposerContent(draft);
+  const intake = useComposerAttachments(document, editor, {
+    policy: config.attachments, createId: ports.createId,
+    ...(options.maxImagePixels === undefined ? {} : { maxImagePixels: options.maxImagePixels }),
+    ...(options.readRaster ? { readRaster: options.readRaster } : {}),
+  });
 
   function submit() {
-    if (content) void ports.submit(draft);
+    const current = document.value as ComposerDraft<Model>;
+    if (!intake.hasPending() && hasComposerContent(current)) void ports.submit(current);
   }
 
-  function addCandidates(candidates: ReturnType<typeof fileCandidatesFromWebFiles>) {
-    if (candidates.length === 0) return;
-    const created = createComposerAttachments(candidates, { createId: ports.createId, policy: config.attachments, currentCount: draft.attachments.length });
-    if (!created.ok) return;
-    addComposerAttachments(editor, draft, created.attachments);
-    editorElementRef.current?.focus();
-  }
-
-  function addWebFiles(files: Parameters<typeof fileCandidatesFromWebFiles>[0]) {
-    addCandidates(fileCandidatesFromWebFiles(files));
-  }
+  const addWebFiles = intake.addFiles;
 
   function handleFileInputChange(event: ChangeEvent<HTMLInputElement>) {
     addWebFiles(event.currentTarget.files ?? []);
     event.currentTarget.value = "";
+    editorElementRef.current?.focus();
   }
 
   function handlePaste(event: ClipboardEvent<HTMLElement>) {
-    const candidates = fileCandidatesFromWebClipboard(event);
-    if (candidates.length === 0) return;
-    event.preventDefault();
-    event.stopPropagation();
-    addCandidates(candidates);
+    if (event.defaultPrevented) return;
+    const captured = captureWebClipboardPaste(event, { files: true });
+    if (captured.ok && captured.type === "files") {
+      event.stopPropagation();
+      addWebFiles(captured.files);
+    } else if (!captured.ok && captured.code !== "clipboard.empty") intake.reportError(captured);
   }
 
   function handleKeyDown(event: KeyboardEvent<HTMLElement>) {
+    if (event.key === "Escape" && intake.hasPending() && !event.nativeEvent.isComposing) {
+      event.preventDefault(); event.stopPropagation(); intake.cancel(); return;
+    }
     const interaction = composerInteractionFromKeyStroke({ key: event.key, shiftKey: event.shiftKey, commandKey: event.metaKey || event.ctrlKey }, config.interaction);
     if (commandMenu.open) {
       commandMenu.handleKeyDown(event);
@@ -128,6 +135,7 @@ export function useComposer<Model extends string, Suggestion extends ComposerHos
     event.preventDefault();
     event.stopPropagation();
     event.nativeEvent.stopImmediatePropagation();
+    intake.cancel();
     if (interaction === "history.redo") editor.redo();
     else editor.undo();
   }
@@ -145,6 +153,10 @@ export function useComposer<Model extends string, Suggestion extends ComposerHos
     attachments: draft.attachments,
     model: draft.model,
     hasContent: content,
+    isPreparingAttachments: intake.isPending,
+    attachmentError: intake.error,
+    canSubmit: content && !intake.isPending,
+    cancelAttachments: intake.cancel,
     commandKind: commandMenu.kind,
     commandMenu: commandMenu.binding,
     commandOpen: commandMenu.open,
@@ -156,7 +168,7 @@ export function useComposer<Model extends string, Suggestion extends ComposerHos
     handleKeyDown,
     handleHistoryKeyDown,
     openFilePicker: () => fileInputRef.current?.click(),
-    removeAttachment: (attachmentId) => { removeComposerAttachment(editor, draft, attachmentId); },
+    removeAttachment: (attachmentId) => { removeComposerAttachment(editor, document.value as ComposerDraft, attachmentId); },
     selectModel: (model) => { selectComposerModel(editor, model); },
     insertText: (text) => { insertComposerText(editor, text); },
     chooseTrigger: (value) => { editorElementRef.current?.focus(); insertComposerText(editor, value); },
diff --git a/packages/json-document-composer-react/tests/composer-attachments.test.tsx b/packages/json-document-composer-react/tests/composer-attachments.test.tsx
new file mode 100644
index 00000000..e67d7528
--- /dev/null
+++ b/packages/json-document-composer-react/tests/composer-attachments.test.tsx
@@ -0,0 +1,110 @@
+import { act, cleanup, renderHook } from "@testing-library/react";
+import { afterEach, expect, test, vi } from "vitest";
+import { COMPOSER_HOST_PROFILE_V1, composerText, type ComposerHostConfig } from "@interactive-os/json-document-composer";
+import type { readWebRasterFile, WebRasterSourceResult } from "@interactive-os/json-document-web";
+import { useComposer } from "../src/index.js";
+import type { ClipboardEvent, KeyboardEvent } from "react";
+
+afterEach(cleanup);
+const file = { name: "image.png", size: 3, type: "image/png" };
+const image = { ok: true as const, dataURL: "data:image/png;base64,AQID", width: 100, height: 50 };
+const config: ComposerHostConfig<"fast"> = {
+  profile: COMPOSER_HOST_PROFILE_V1, models: [{ id: "fast", value: "fast", label: "Fast", description: "Model" }], suggestions: [],
+  attachments: { acceptedMediaTypes: ["*/*"], maxFiles: 4, maxBytesPerFile: 100 }, interaction: { submit: "enter", newline: "shift-enter" },
+};
+function waiting() {
+  let resolve!: (result: WebRasterSourceResult) => void;
+  const promise = new Promise<WebRasterSourceResult>((done) => { resolve = done; });
+  return { promise, resolve };
+}
+function setup(readRaster: typeof readWebRasterFile = vi.fn(async () => image), policy = config.attachments) {
+  let id = 0;
+  const submit = vi.fn(async () => undefined);
+  const hook = renderHook(() => useComposer({ id: "composer", config: { ...config, attachments: policy }, ports: { createId: () => `id-${++id}`, submit }, labels: { mentionSuggestions: "Mentions", skillSuggestions: "Skills" }, readRaster }));
+  return { ...hook, submit, readRaster };
+}
+function key(key: string, metaKey = false) {
+  return { key, metaKey, preventDefault: vi.fn(), stopPropagation: vi.fn(), nativeEvent: { isComposing: false, stopImmediatePropagation: vi.fn() } } as unknown as KeyboardEvent<HTMLElement>;
+}
+
+test("PI-CONTENT: decoded images survive draft serialization, submit, removal, and Undo/Redo", async () => {
+  const { result, submit } = setup();
+  await act(async () => { result.current.addWebFiles([file]); });
+  const attachment = result.current.attachments[0]!;
+  expect(attachment).toMatchObject({ id: "id-4", name: file.name, image: { source: image.dataURL, width: 100, height: 50 } });
+  expect(JSON.parse(JSON.stringify(result.current.draft)).attachments[0]).toEqual(attachment);
+  act(() => { result.current.submit(); }); expect(submit).toHaveBeenCalledWith(result.current.draft);
+  act(() => { result.current.removeAttachment(attachment.id); }); expect(result.current.attachments).toEqual([]);
+  act(() => { result.current.editor.undo(); }); expect(result.current.attachments).toEqual([attachment]);
+  act(() => { result.current.editor.undo(); }); expect(result.current.attachments).toEqual([]);
+  act(() => { result.current.editor.redo(); }); expect(result.current.attachments).toEqual([attachment]);
+});
+
+test("PI-TYPING/PI-ORDER: typing and caret movement continue; requests append in input order with separate Undo", async () => {
+  const first = waiting(), second = waiting();
+  const reader = vi.fn<typeof readWebRasterFile>().mockImplementationOnce(() => first.promise).mockImplementationOnce(() => second.promise);
+  const { result, submit } = setup(reader);
+  act(() => { result.current.addWebFiles([file]); result.current.addWebFiles([{ ...file, name: "second.png" }]); result.current.insertText("계속 입력"); });
+  expect(result.current.isPreparingAttachments).toBe(true); expect(result.current.canSubmit).toBe(false);
+  const focus = result.current.editor.snapshot.selection.ranges[0]!.focus;
+  expect(focus.kind).toBe("text");
+  if (focus.kind !== "text") return;
+  const caret = { ...focus, offset: 0 };
+  const selection = { kind: "range" as const, ranges: [{ anchor: caret, focus: caret }], primaryIndex: 0 };
+  act(() => { result.current.editor.dispatch({ type: "selection.set", selection }); result.current.submit(); });
+  expect(submit).not.toHaveBeenCalled();
+  await act(async () => { second.resolve(image); }); expect(result.current.attachments).toEqual([]);
+  await act(async () => { first.resolve(image); });
+  expect(result.current.attachments.map((attachment) => attachment.name)).toEqual([file.name, "second.png"]);
+  expect(composerText(result.current.draft.instruction)).toBe("계속 입력");
+  expect(result.current.editor.snapshot.selection).toEqual(selection); expect(result.current.canSubmit).toBe(true);
+  act(() => { result.current.handleHistoryKeyDown(key("z", true)); }); expect(result.current.attachments).toHaveLength(1);
+  act(() => { result.current.handleHistoryKeyDown(key("z", true)); }); expect(result.current.attachments).toHaveLength(0);
+  expect(composerText(result.current.draft.instruction)).toBe("계속 입력");
+});
+
+test.each(["escape", "cancel", "undo", "unmount"])("PI-CANCEL: %s aborts preparation and cannot revive a late image", async (reason) => {
+  const pending = waiting();
+  const reader = vi.fn<typeof readWebRasterFile>(() => pending.promise);
+  const { result, unmount } = setup(reader);
+  act(() => { result.current.addWebFiles([file]); });
+  const document = result.current.document;
+  const initial = document.value;
+  act(() => {
+    if (reason === "escape") result.current.handleKeyDown(key("Escape"));
+    else if (reason === "cancel") result.current.cancelAttachments();
+    else if (reason === "undo") result.current.handleHistoryKeyDown(key("z", true));
+    else unmount();
+  });
+  expect(reader.mock.calls[0]?.[1]?.signal?.aborted).toBe(true);
+  await act(async () => { pending.resolve(image); }); expect(document.value).toEqual(initial);
+});
+
+test("PI-FILE: failed image batch leaves neither metadata-only remnants nor History", async () => {
+  const reader = vi.fn<typeof readWebRasterFile>().mockResolvedValueOnce(image).mockResolvedValueOnce({ ok: false, code: "raster.decode-failed" });
+  const { result } = setup(reader);
+  await act(async () => { result.current.addWebFiles([file, file]); });
+  expect(result.current.attachments).toEqual([]); expect(result.current.editor.snapshot.canUndo).toBe(false);
+  expect(result.current.attachmentError?.code).toBe("raster.decode-failed"); expect(result.current.isPreparingAttachments).toBe(false);
+});
+
+test("queued requests revalidate the latest attachment count before ID allocation", async () => {
+  const first = waiting();
+  const reader = vi.fn<typeof readWebRasterFile>().mockImplementationOnce(() => first.promise).mockResolvedValue(image);
+  const { result } = setup(reader, { ...config.attachments, maxFiles: 1 });
+  act(() => { result.current.addWebFiles([file]); result.current.addWebFiles([{ ...file, name: "overflow.png" }]); });
+  await act(async () => { first.resolve(image); });
+  expect(result.current.attachments).toHaveLength(1); expect(result.current.attachmentError?.code).toBe("composer.attachments.limit");
+  act(() => { result.current.removeAttachment(result.current.attachments[0]!.id); });
+  await act(async () => { result.current.addWebFiles([file]); }); expect(result.current.attachments[0]!.id).toBe("id-5");
+});
+
+test("file-only native paste consumes images once and delegates text/HTML to Rich Text", async () => {
+  const { result } = setup();
+  const preventDefault = vi.fn(), stopPropagation = vi.fn();
+  const event = (files: typeof file[], types: string[]) => ({ clipboardData: { files, types, getData: () => "<p>text</p>", setData() {} }, preventDefault, stopPropagation }) as unknown as ClipboardEvent<HTMLElement>;
+  act(() => { result.current.handlePaste(event([], ["text/html", "text/plain"])); });
+  expect(preventDefault).not.toHaveBeenCalled(); expect(stopPropagation).not.toHaveBeenCalled();
+  await act(async () => { result.current.handlePaste(event([file], ["Files", "text/html"])); });
+  expect(result.current.attachments).toHaveLength(1); expect(preventDefault).toHaveBeenCalledOnce(); expect(stopPropagation).toHaveBeenCalledOnce();
+});
diff --git a/packages/json-document-composer-react/tsconfig.json b/packages/json-document-composer-react/tsconfig.json
index 3340baf9..4fd7db96 100644
--- a/packages/json-document-composer-react/tsconfig.json
+++ b/packages/json-document-composer-react/tsconfig.json
@@ -8,6 +8,8 @@
   "references": [
     { "path": "../json-document" },
     { "path": "../json-document-composer" },
+    { "path": "../json-document-editing" },
+    { "path": "../json-document-file-intake" },
     { "path": "../json-document-rich-text" },
     { "path": "../json-document-rich-text-mention" },
     { "path": "../json-document-rich-text-mention-react" },
diff --git a/packages/json-document-composer/README.md b/packages/json-document-composer/README.md
index 32b8262f..6b613f0c 100644
--- a/packages/json-document-composer/README.md
+++ b/packages/json-document-composer/README.md
@@ -9,3 +9,22 @@ those validated candidates into Composer context attachments.
 `resolveComposerSuggestions(trigger, suggestions)` owns trigger-aware matching of a
 product-configured suggestion catalog. React menu lifecycle and atom projection live in
 `@interactive-os/json-document-composer-react`.
+
+## 이미지 첨부
+
+`ComposerAttachment`와 `ComposerAttachmentCandidate`의 선택적 `image`는 File Intake의
+`RasterImageContent`입니다. 기존 metadata-only 첨부는 그대로 유효합니다.
+`createComposerAttachments`는 image source·치수와 media type을 검사한 뒤 ID를 할당하고,
+`addComposerAttachments`는 한 batch를 기존 Rich Text editor의 한 편집/Undo로 추가합니다.
+이미지 내용은 같은 draft JSON에 남으므로 별도의 임시 blob URL에 의존하지 않습니다.
+
+```ts
+const prepared = createComposerAttachments([
+  { name: "screenshot.png", size: fileSize, mediaType: "image/png", image: decodedImage },
+], { policy, createId, currentCount: draft.attachments.length });
+if (prepared.ok) addComposerAttachments(editor, draft, prepared.attachments);
+```
+
+`image`가 없는 첨부는 파일 이름·크기·형식 정보뿐입니다. 실제 byte 저장이나 서버 업로드가
+완료된 파일이라고 해석하지 않습니다. Clipboard HTML의 글+이미지 변환과 이미지 asset
+저장소 연결은 TBD입니다. 실제 Usage·Source는 [Composer](/demo/composer)에 있습니다.
diff --git a/packages/json-document-composer/src/commands.ts b/packages/json-document-composer/src/commands.ts
index 8891ead7..76317127 100644
--- a/packages/json-document-composer/src/commands.ts
+++ b/packages/json-document-composer/src/commands.ts
@@ -5,7 +5,7 @@ import {
   type RichTextNode,
   type RichTextPoint,
 } from "@interactive-os/json-document-rich-text";
-import { validateFileCandidates } from "@interactive-os/json-document-file-intake";
+import { assertRasterImageContent, validateFileCandidates } from "@interactive-os/json-document-file-intake";
 import { insertRichTextMention } from "@interactive-os/json-document-rich-text-mention";
 import { COMPOSER_MENTION_NODE, COMPOSER_PROFILE_V1, COMPOSER_SKILL_NODE, type ComposerAttachment, type ComposerAttachmentCandidate, type ComposerDraft, type ComposerReference, type ComposerTrigger } from "./model.js";
 import type { ComposerAttachmentPolicy } from "./host-config.js";
@@ -23,7 +23,18 @@ export function createComposerAttachments(
 ): ComposerAttachmentResult {
   const validated = validateFileCandidates(candidates, options.policy, options.currentCount === undefined ? {} : { currentCount: options.currentCount });
   if (!validated.ok) return { ok: false, code: composerAttachmentError(validated.code), candidate: validated.candidate };
-  const attachments: ComposerAttachment[] = validated.candidates.map((candidate) => ({ id: options.createId(), kind: candidate.mediaType?.startsWith("image/") ? "image" : "document", ...candidate }));
+  for (const candidate of candidates) {
+    if (candidate.image === undefined) continue;
+    try {
+      assertRasterImageContent(candidate.image);
+      if (!candidate.image.source.startsWith(`data:${candidate.mediaType};base64,`)) throw new TypeError("Attachment media type does not match its image.");
+    } catch { return { ok: false, code: "composer.attachments.invalid", candidate }; }
+  }
+  const attachments: ComposerAttachment[] = validated.candidates.map((candidate) => ({
+    ...candidate,
+    id: options.createId(), kind: candidate.mediaType?.startsWith("image/") ? "image" : "document",
+    ...(candidate.image ? { image: { source: candidate.image.source, width: candidate.image.width, height: candidate.image.height } } : {}),
+  }));
   return { ok: true, attachments };
 }
 
diff --git a/packages/json-document-composer/src/model.ts b/packages/json-document-composer/src/model.ts
index dc0891b7..dedce4cd 100644
--- a/packages/json-document-composer/src/model.ts
+++ b/packages/json-document-composer/src/model.ts
@@ -1,5 +1,5 @@
 import type { JSONValue } from "@interactive-os/json-document";
-import type { FileCandidate } from "@interactive-os/json-document-file-intake";
+import type { FileCandidate, RasterImageContent } from "@interactive-os/json-document-file-intake";
 import type { RichTextDocument } from "@interactive-os/json-document-rich-text";
 import { RICH_TEXT_MENTION_NODE, type RichTextMention } from "@interactive-os/json-document-rich-text-mention";
 
@@ -11,15 +11,17 @@ export type ComposerReference =
   | ({ readonly kind: "mention" } & RichTextMention)
   | { readonly kind: "skill"; readonly id: string; readonly label: string };
 
-export interface ComposerAttachment extends Record<string, JSONValue> {
+export type ComposerAttachment = Record<string, JSONValue> & {
   readonly id: string;
   readonly kind: "document" | "image";
   readonly name: string;
   readonly size: number;
   readonly mediaType: string | null;
-}
+  /** Absent for metadata-only attachments. Presence retains actual embedded raster content. */
+  readonly image?: RasterImageContent;
+};
 
-export type ComposerAttachmentCandidate = FileCandidate;
+export type ComposerAttachmentCandidate = FileCandidate & { readonly image?: RasterImageContent };
 
 export interface ComposerDraft<Model extends string = string> extends Record<string, JSONValue> {
   readonly id: string;
diff --git a/packages/json-document-composer/tests/composer.test.ts b/packages/json-document-composer/tests/composer.test.ts
index 7594cb17..de267fe0 100644
--- a/packages/json-document-composer/tests/composer.test.ts
+++ b/packages/json-document-composer/tests/composer.test.ts
@@ -111,6 +111,41 @@ describe("Composer domain", () => {
     expect((document.value as typeof draft).attachments).toEqual([]);
   });
 
+  test("owns image content and preserves it through JSON and History", () => {
+    const image = { source: "data:image/png;base64,AAAA", width: 64, height: 32 };
+    const created = createComposerAttachments(
+      [{ name: "brief.png", size: 3, mediaType: "image/png", image }],
+      { createId: () => "image-1", policy: { acceptedMediaTypes: ["image/*"], maxFiles: 2, maxBytesPerFile: 100 } },
+    );
+    expect(created.ok).toBe(true);
+    if (!created.ok) return;
+    image.width = 1;
+    expect(created.attachments[0]?.image?.width).toBe(64);
+    const draft = createComposerDraft({ id: "draft", instructionId: "instruction", paragraphId: "paragraph", model: "fast" });
+    const document = createJSONDocument(draft);
+    const editor = createRichTextEditor({ document, pointer: "/instruction", schema: composerSchema });
+    expect(addComposerAttachments(editor, draft, created.attachments).ok).toBe(true);
+    expect(JSON.parse(JSON.stringify(document.value)).attachments[0].image).toEqual({ source: image.source, width: 64, height: 32 });
+    expect(editor.undo().ok).toBe(true);
+    expect((document.value as typeof draft).attachments).toEqual([]);
+    expect(editor.redo().ok).toBe(true);
+    expect((document.value as typeof draft).attachments).toEqual(created.attachments);
+  });
+
+  test.each([
+    { source: "https://example.com/image.png", width: 64, height: 32 },
+    { source: "data:image/jpeg;base64,AAAA", width: 64, height: 32 },
+    { source: "data:image/png;base64,AAAA", width: 0, height: 32 },
+  ])("rejects an invalid image batch before allocating IDs: %j", (image) => {
+    let ids = 0;
+    const result = createComposerAttachments([
+      { name: "valid.txt", size: 1, mediaType: "text/plain" },
+      { name: "invalid.png", size: 3, mediaType: "image/png", image },
+    ], { createId: () => String(++ids), policy: { acceptedMediaTypes: ["*/*"], maxFiles: null, maxBytesPerFile: null } });
+    expect(result).toMatchObject({ ok: false, code: "composer.attachments.invalid" });
+    expect(ids).toBe(0);
+  });
+
   test("resolves product-configured Composer interaction meaning", () => {
     const policy = { submit: "enter", newline: "shift-enter" } as const;
     expect(composerInteractionFromKeyStroke({ key: "Enter" }, policy)).toBe("submit");
diff --git a/packages/json-document-editing/README.md b/packages/json-document-editing/README.md
index 9ea50d88..f3e66bec 100644
--- a/packages/json-document-editing/README.md
+++ b/packages/json-document-editing/README.md
@@ -73,6 +73,24 @@ Further commands cannot author until restoration succeeds. Fix the callback or
 recreate the editor; do not retry the history operation as if it were rejected.
 Callback exceptions are programming errors, not `{ ok: false }` commit rejections.
 
+## 비동기 준비 순서
+
+`createEditingPreparationQueue<Value, Result>({ apply, onResult?, onPendingChange?, cancelCode?, errorCode? })`는
+`enqueue(prepare, cancelPreparation?)`, `cancel()`, `isPending`을 제공합니다.
+`prepare`는 `{ ok: true, value }` 또는 `{ ok: false, code, reason? }`를 즉시/Promise로
+반환합니다. 준비는 병행할 수 있지만 `apply`는 입력 순서대로 동기 실행합니다.
+준비 실패는 apply를 호출하지 않고, 취소는 대기 Promise를 settle하며 늦은 결과를 무시합니다.
+기본 오류 코드는 `editing.preparation-cancelled`, `editing.preparation-failed`입니다. 기존 public binding은
+`cancelCode/errorCode`로 자신의 오류 어휘를 유지할 수 있습니다.
+
+queue는 문서·selection을 모르며 원자적 편집은 `apply`가 호출하는 정본 editor의 책임입니다.
+이미 완료한 편집을 취소로 되돌리지 않습니다. Object의 `createObjectPasteSession`은
+외부 문서/선택 변경에 취소하고, Composer의 첨부 준비는 typing 중 유지합니다.
+각 요청의 History 단위도 실제 domain apply가 정합니다.
+Usage·Source: [Canvas](/demo/canvas), [Composer](/demo/composer).
+
+## Editing identity and observation
+
 `createEditingId(prefix)` supplies opaque UUID-based identities for Document,
 Order, Object, Tree, Calendar and Rich Text. IDs do not restart per editor or
 replica. Custom `createId` injection remains supported; its provider must ensure
diff --git a/packages/json-document-editing/src/index.ts b/packages/json-document-editing/src/index.ts
index 199b7f9b..fc7e3a45 100644
--- a/packages/json-document-editing/src/index.ts
+++ b/packages/json-document-editing/src/index.ts
@@ -30,6 +30,7 @@ export { acceptsDatabaseValue, databaseValueFromText, defaultDatabaseValue } fro
 export { createObjectEditor, objectClipboardFormat } from "./object.js";
 export { createCanvasClipboard, type CanvasClipboardContent, type CanvasClipboardOptions } from "./canvas-clipboard.js";
 export { createObjectPasteSession, type ObjectPasteSession, type ObjectPastePreparation } from "./object-paste-session.js";
+export { createEditingPreparationQueue, type EditingPreparationQueue, type EditingPreparation, type EditingPreparationFailure } from "./preparation-queue.js";
 export { createOrderEditor, orderClipboardFormat } from "./order.js";
 export { createEditingSession } from "./session.js";
 export { createEditingId, createEditingIdAllocator } from "./identity.js";
diff --git a/packages/json-document-editing/src/object-paste-session.ts b/packages/json-document-editing/src/object-paste-session.ts
index 2121cbb8..9611fc14 100644
--- a/packages/json-document-editing/src/object-paste-session.ts
+++ b/packages/json-document-editing/src/object-paste-session.ts
@@ -1,5 +1,6 @@
 import type { EditingResult } from "./session.js";
 import type { ObjectClipboard, ObjectEditor, ObjectPastePlacement, ObjectSelection } from "./object.js";
+import { createEditingPreparationQueue, type EditingPreparation } from "./preparation-queue.js";
 
 export type ObjectPastePreparation =
   | { readonly ok: true; readonly clipboard: ObjectClipboard }
@@ -18,83 +19,43 @@ export function createObjectPasteSession(editor: ObjectEditor, options: {
   readonly onResult?: (result: EditingResult<ObjectSelection>) => void;
   readonly onPendingChange?: (pending: boolean) => void;
 } = {}): ObjectPasteSession {
-  type Job = { result?: ObjectPastePreparation; resolve: (result: EditingResult<ObjectSelection>) => void; cancel?: () => void };
-  let queue: Job[] = [];
   let release: (() => void) | undefined;
   let applying = false;
-  let draining = false;
-  let publishedPending = false;
-
-  function publishPending(pending: boolean) {
-    if (publishedPending === pending) return;
-    publishedPending = pending;
-    try { options.onPendingChange?.(pending); } catch { /* Observers cannot interrupt adoption or cleanup. */ }
-  }
-  function idle() {
-    release?.(); release = undefined;
-    publishPending(false);
-  }
-  function cancel() {
-    const cancelled = queue;
-    queue = [];
-    if (cancelled.length === 0) return;
-    idle();
-    for (const job of cancelled) {
-      job.resolve({ ok: false, code: "clipboard.cancelled" });
-      try { job.cancel?.(); } catch { /* Other preparations must still be cancelled. */ }
-    }
-  }
-  function drain() {
-    if (draining) return;
-    draining = true;
-    try {
-      while (queue[0]?.result) {
-        const job = queue.shift()!;
-        const prepared = job.result!;
-        applying = true;
-        let result: EditingResult<ObjectSelection>;
-        try {
-          result = prepared.ok ? editor.dispatch({ type: "clipboard.paste", clipboard: prepared.clipboard, ...(options.placement ? { placement: options.placement } : {}) }) : prepared;
-        } catch (error) {
-          result = { ok: false, code: "clipboard.invalid", reason: error instanceof Error ? error.message : String(error) };
-        } finally { applying = false; }
-        job.resolve(result);
-        try { options.onResult?.(result); } catch { /* A completed edit cannot be rejected by an observer. */ }
-        if (result.ok && (editor.snapshot.value !== result.snapshot.value || editor.snapshot.selection !== result.snapshot.selection)) cancel();
+  const queue = createEditingPreparationQueue<ObjectClipboard, EditingResult<ObjectSelection>>({
+    cancelCode: "clipboard.cancelled",
+    errorCode: "clipboard.invalid",
+    apply(clipboard) {
+      applying = true;
+      try { return editor.dispatch({ type: "clipboard.paste", clipboard, ...(options.placement ? { placement: options.placement } : {}) }); }
+      finally { applying = false; }
+    },
+    onPendingChange(pending) {
+      if (!pending) { release?.(); release = undefined; }
+      options.onPendingChange?.(pending);
+    },
+    onResult(result) {
+      try { options.onResult?.(result); }
+      finally {
+        if (result.ok && (editor.snapshot.value !== result.snapshot.value || editor.snapshot.selection !== result.snapshot.selection)) queue.cancel();
       }
-    } finally {
-      draining = false;
-      if (queue.length === 0) idle();
-    }
-  }
-  function ready(job: Job, result: ObjectPastePreparation) {
-    if (!queue.includes(job)) return;
-    job.result = result;
-    drain();
-  }
+    },
+  });
+  const prepared = (result: ObjectPastePreparation): EditingPreparation<ObjectClipboard> => result.ok ? { ok: true, value: result.clipboard } : result;
   return {
-    get pending() { return queue.length > 0; },
-    cancel,
+    get pending() { return queue.isPending; },
+    cancel: queue.cancel,
     enqueue(prepare, cancelPreparation) {
-      return new Promise((resolve) => {
-        const job: Job = { resolve, ...(cancelPreparation ? { cancel: cancelPreparation } : {}) };
-        if (!release) {
-          let base = editor.snapshot;
-          release = editor.subscribe((next) => {
-            if (!applying && (base.value !== next.value || base.selection !== next.selection)) cancel();
-            base = next;
-          });
-        }
-        const wasIdle = queue.length === 0;
-        queue.push(job);
-        if (wasIdle) publishPending(true);
-        if (!queue.includes(job)) return;
-        try {
-          const result = prepare();
-          if ("ok" in result) ready(job, result);
-          else void Promise.resolve(result).then((value) => ready(job, value), (error: unknown) => ready(job, { ok: false, code: "clipboard.invalid", reason: error instanceof Error ? error.message : String(error) }));
-        } catch (error) { ready(job, { ok: false, code: "clipboard.invalid", reason: error instanceof Error ? error.message : String(error) }); }
-      });
+      if (!release) {
+        let base = editor.snapshot;
+        release = editor.subscribe((next) => {
+          if (!applying && (base.value !== next.value || base.selection !== next.selection)) queue.cancel();
+          base = next;
+        });
+      }
+      return queue.enqueue(() => {
+        const result = prepare();
+        return "ok" in result ? prepared(result) : Promise.resolve(result).then(prepared);
+      }, cancelPreparation);
     },
   };
 }
diff --git a/packages/json-document-editing/src/preparation-queue.ts b/packages/json-document-editing/src/preparation-queue.ts
new file mode 100644
index 00000000..ebc7d42f
--- /dev/null
+++ b/packages/json-document-editing/src/preparation-queue.ts
@@ -0,0 +1,80 @@
+export type EditingPreparationFailure = { readonly ok: false; readonly code: string; readonly reason?: string };
+export type EditingPreparation<Value> = { readonly ok: true; readonly value: Value } | EditingPreparationFailure;
+
+export interface EditingPreparationQueue<Value, Result> {
+  readonly isPending: boolean;
+  enqueue(prepare: () => EditingPreparation<Value> | Promise<EditingPreparation<Value>>, cancelPreparation?: () => void): Promise<Result | EditingPreparationFailure>;
+  cancel(): void;
+}
+
+/** Orders asynchronous preparation before synchronous edits. Targets and invalidation policy belong to the consumer. */
+export function createEditingPreparationQueue<Value, Result extends { readonly ok: boolean }>(options: {
+  readonly apply: (value: Value) => Result;
+  readonly onResult?: (result: Result | EditingPreparationFailure) => void;
+  readonly onPendingChange?: (pending: boolean) => void;
+  readonly cancelCode?: string;
+  readonly errorCode?: string;
+}): EditingPreparationQueue<Value, Result> {
+  type Job = { prepared?: EditingPreparation<Value>; resolve: (result: Result | EditingPreparationFailure) => void; cancel?: () => void };
+  let queue: Job[] = [];
+  let draining = false;
+  let publishedPending = false;
+
+  function publishPending(pending: boolean) {
+    if (publishedPending === pending) return;
+    publishedPending = pending;
+    try { options.onPendingChange?.(pending); } catch { /* Observers do not own queue progress. */ }
+  }
+  function failure(error: unknown): EditingPreparationFailure {
+    return { ok: false, code: options.errorCode ?? "editing.preparation-failed", reason: error instanceof Error ? error.message : String(error) };
+  }
+  function cancel() {
+    const cancelled = queue;
+    queue = [];
+    publishPending(false);
+    for (const job of cancelled) {
+      job.resolve({ ok: false, code: options.cancelCode ?? "editing.preparation-cancelled" });
+      try { job.cancel?.(); } catch { /* Every cancelled job must settle. */ }
+    }
+  }
+  function drain() {
+    if (draining) return;
+    draining = true;
+    try {
+      while (queue[0]?.prepared) {
+        const job = queue.shift()!;
+        const prepared = job.prepared!;
+        let result: Result | EditingPreparationFailure;
+        try { result = prepared.ok ? options.apply(prepared.value) : prepared; }
+        catch (error) { result = failure(error); }
+        job.resolve(result);
+        try { options.onResult?.(result); } catch { /* A committed edit remains committed. */ }
+      }
+    } finally {
+      draining = false;
+      if (queue.length === 0) publishPending(false);
+    }
+  }
+  function ready(job: Job, prepared: EditingPreparation<Value>) {
+    if (!queue.includes(job)) return;
+    job.prepared = prepared;
+    drain();
+  }
+  return {
+    get isPending() { return queue.length > 0 || draining; },
+    cancel,
+    enqueue(prepare, cancelPreparation) {
+      return new Promise((resolve) => {
+        const job: Job = { resolve, ...(cancelPreparation ? { cancel: cancelPreparation } : {}) };
+        queue.push(job);
+        publishPending(true);
+        if (!queue.includes(job)) return;
+        try {
+          const result = prepare();
+          if ("ok" in result) ready(job, result);
+          else void Promise.resolve(result).then((value) => ready(job, value), (error: unknown) => ready(job, failure(error)));
+        } catch (error) { ready(job, failure(error)); }
+      });
+    },
+  };
+}
diff --git a/packages/json-document-editing/tests/preparation-queue.test.ts b/packages/json-document-editing/tests/preparation-queue.test.ts
new file mode 100644
index 00000000..7bea5d89
--- /dev/null
+++ b/packages/json-document-editing/tests/preparation-queue.test.ts
@@ -0,0 +1,56 @@
+import { expect, test, vi } from "vitest";
+import { createEditingPreparationQueue, type EditingPreparation } from "../src/index.js";
+
+function deferred<Value>() {
+  let resolve!: (value: EditingPreparation<Value>) => void;
+  const promise = new Promise<EditingPreparation<Value>>((done) => { resolve = done; });
+  return { promise, resolve };
+}
+
+test("PI-ORDER: preparation order is independent of completion; each value applies once", async () => {
+  const applied: string[] = [];
+  const onPendingChange = vi.fn();
+  const queue = createEditingPreparationQueue({ apply: (value: string) => { applied.push(value); return { ok: true as const }; }, onPendingChange });
+  const first = deferred<string>(), second = deferred<string>();
+  const a = queue.enqueue(() => first.promise), b = queue.enqueue(() => second.promise);
+  second.resolve({ ok: true, value: "B" }); await Promise.resolve();
+  expect(applied).toEqual([]);
+  first.resolve({ ok: true, value: "A" }); await Promise.all([a, b]);
+  expect(applied).toEqual(["A", "B"]); expect(queue.isPending).toBe(false);
+  expect(onPendingChange.mock.calls).toEqual([[true], [false]]);
+});
+
+test("PI-CANCEL: cancellation settles every job, aborts preparation, and ignores late results", async () => {
+  const apply = vi.fn((value: string) => ({ ok: true as const, value })), onResult = vi.fn();
+  const queue = createEditingPreparationQueue({ apply, onResult });
+  const waiting = deferred<string>(), abort = vi.fn();
+  const a = queue.enqueue(() => waiting.promise, abort), b = queue.enqueue(() => ({ ok: true, value: "B" }));
+  queue.cancel();
+  expect(await a).toMatchObject({ ok: false, code: "editing.preparation-cancelled" });
+  expect(await b).toMatchObject({ ok: false });
+  waiting.resolve({ ok: true, value: "late" }); await Promise.resolve();
+  expect(apply).not.toHaveBeenCalled(); expect(onResult).not.toHaveBeenCalled(); expect(abort).toHaveBeenCalledOnce();
+  await queue.enqueue(() => ({ ok: true, value: "fresh" })); expect(apply).toHaveBeenCalledWith("fresh");
+});
+
+test("failed preparation and reentrant observers cannot poison later edits", async () => {
+  const values: string[] = [];
+  const queue = createEditingPreparationQueue({
+    apply(value: string) { values.push(value); return { ok: true as const }; },
+    onResult() { if (values.length === 1) void queue.enqueue(() => ({ ok: true, value: "nested" })); throw new Error("observer"); },
+  });
+  expect(await queue.enqueue(() => Promise.reject(new Error("read")))).toMatchObject({ ok: false, reason: "read" });
+  await queue.enqueue(() => ({ ok: true, value: "first" })); expect(values).toEqual(["first", "nested"]);
+});
+
+test("pending observer cancellation prevents preparation and leaves a reusable queue", async () => {
+  const prepare = vi.fn(() => ({ ok: true as const, value: "never" }));
+  let shouldCancel = true;
+  const queue = createEditingPreparationQueue({
+    apply: (value: string) => ({ ok: true as const, value }),
+    onPendingChange(pending) { if (pending && shouldCancel) queue.cancel(); },
+  });
+  expect((await queue.enqueue(prepare)).ok).toBe(false); expect(prepare).not.toHaveBeenCalled();
+  shouldCancel = false;
+  expect((await queue.enqueue(prepare)).ok).toBe(true);
+});
diff --git a/packages/json-document-file-intake/README.md b/packages/json-document-file-intake/README.md
index 8e92f94d..67377250 100644
--- a/packages/json-document-file-intake/README.md
+++ b/packages/json-document-file-intake/README.md
@@ -13,3 +13,21 @@ validateFileCandidates(files, {
 
 formatFileSize(files[0].size);
 ```
+
+## 포함된 이미지 내용
+
+`RasterImageContent`는 `{ source: string, width: number, height: number }`인 JSON 값입니다.
+`assertRasterImageSource(source)`는 PNG/JPEG/WebP base64 data URL 문법을,
+`assertRasterImageContent(value)`는 같은 source와 양의 안전한 정수 치수를 검사합니다.
+외부 URL·blob URL·SVG는 이 계약에 포함하지 않습니다. 파일 byte의 실제 decode와
+픽셀/파일 수용 정책 적용은 별개이며, 문법 검사 성공이 decode 가능성을 보증하지 않습니다.
+
+```ts
+import { assertRasterImageContent } from "@interactive-os/json-document-file-intake";
+
+assertRasterImageContent({ source: "data:image/png;base64,AQID", width: 100, height: 50 });
+// 문법 예시이며 실제 PNG byte를 뜻하지 않습니다.
+```
+
+Object Document Type과 Composer가 이 내용을 각각 객체 source와 첨부 image에 사용합니다.
+실제 이미지 읽기·표시·Undo의 Usage와 Source: [Canvas](/demo/canvas), [Composer](/demo/composer).
diff --git a/packages/json-document-file-intake/src/index.ts b/packages/json-document-file-intake/src/index.ts
index db9e116a..017560e7 100644
--- a/packages/json-document-file-intake/src/index.ts
+++ b/packages/json-document-file-intake/src/index.ts
@@ -1,6 +1,8 @@
 import type { JSONValue } from "@interactive-os/json-document";
 
 export { formatFileSize } from "./file-size.js";
+export { assertRasterImageContent, assertRasterImageSource } from "./raster-content.js";
+export type { RasterImageContent } from "./raster-content.js";
 
 export interface FileCandidate extends Record<string, JSONValue> {
   readonly name: string;
diff --git a/packages/json-document-file-intake/src/raster-content.ts b/packages/json-document-file-intake/src/raster-content.ts
new file mode 100644
index 00000000..7128635a
--- /dev/null
+++ b/packages/json-document-file-intake/src/raster-content.ts
@@ -0,0 +1,30 @@
+import type { JSONValue } from "@interactive-os/json-document";
+
+/** Portable embedded image content. Source syntax validation does not prove that bytes decode. */
+export interface RasterImageContent extends Record<string, JSONValue> {
+  readonly source: string;
+  readonly width: number;
+  readonly height: number;
+}
+
+export function assertRasterImageSource(source: unknown): asserts source is string {
+  if (typeof source !== "string") throw new TypeError("Image source must be an embedded PNG, JPEG, or WebP data URL.");
+  const separator = source.indexOf(",");
+  const header = source.slice(0, separator);
+  const bytes = source.slice(separator + 1);
+  // Flat checks avoid recursive regex stack growth on large rasters.
+  if (!["data:image/png;base64", "data:image/jpeg;base64", "data:image/webp;base64"].includes(header)
+    || bytes.length === 0 || bytes.length % 4 !== 0 || /[^A-Za-z0-9+/=]/.test(bytes)
+    || bytes.slice(0, -2).includes("=") || (bytes.at(-2) === "=" && bytes.at(-1) !== "=")) {
+    throw new TypeError("Image source must be an embedded PNG, JPEG, or WebP base64 data URL.");
+  }
+}
+
+export function assertRasterImageContent(value: unknown): asserts value is RasterImageContent {
+  if (value === null || typeof value !== "object") throw new TypeError("Expected raster image content.");
+  const content = value as Record<string, unknown>;
+  assertRasterImageSource(content.source);
+  if (typeof content.width !== "number" || typeof content.height !== "number"
+    || !Number.isSafeInteger(content.width) || !Number.isSafeInteger(content.height)
+    || content.width <= 0 || content.height <= 0) throw new TypeError("Raster dimensions must be positive safe integers.");
+}
diff --git a/packages/json-document-file-intake/tests/raster-content.test.ts b/packages/json-document-file-intake/tests/raster-content.test.ts
new file mode 100644
index 00000000..06feb704
--- /dev/null
+++ b/packages/json-document-file-intake/tests/raster-content.test.ts
@@ -0,0 +1,16 @@
+import { expect, test } from "vitest";
+import { assertRasterImageContent, assertRasterImageSource } from "../src/index.js";
+
+test.each(["png", "jpeg", "webp"])("PI-CONTENT: %s embedded source is a portable syntax contract, not a decoder", (type) => {
+  const image = { source: `data:image/${type};base64,AQID`, width: 1, height: 2 };
+  expect(() => assertRasterImageContent(image)).not.toThrow();
+  expect(JSON.parse(JSON.stringify(image))).toEqual(image);
+});
+
+test.each(["https://example.com/a.png", "blob:temporary", "data:image/svg+xml;base64,AQID", "data:image/png;base64,A=ID", "data:image/png;base64,"])("PI-CONTENT: rejects nonportable or malformed source %s", (source) => {
+  expect(() => assertRasterImageSource(source)).toThrow(TypeError);
+});
+
+test.each([0, -1, 1.5, NaN, Infinity])("PI-CONTENT: rejects invalid raster dimension %s", (width) => {
+  expect(() => assertRasterImageContent({ source: "data:image/png;base64,AQID", width, height: 1 })).toThrow(TypeError);
+});
diff --git a/packages/json-document-object-document/package.json b/packages/json-document-object-document/package.json
index 19ec59a1..e8ddafdd 100644
--- a/packages/json-document-object-document/package.json
+++ b/packages/json-document-object-document/package.json
@@ -18,6 +18,6 @@
     "test": "vitest run --config vitest.config.ts",
     "verify": "npm run typecheck && npm test && npm run build"
   },
-  "peerDependencies": { "@interactive-os/json-document": "^3.0.0" },
-  "devDependencies": { "@interactive-os/json-document": "*", "@types/node": "^25.9.0", "typescript": "^5.0.0", "vitest": "^4.1.7" }
+  "peerDependencies": { "@interactive-os/json-document": "^3.0.0", "@interactive-os/json-document-file-intake": "^0.1.0-rc.0" },
+  "devDependencies": { "@interactive-os/json-document": "*", "@interactive-os/json-document-file-intake": "*", "@types/node": "^25.9.0", "typescript": "^5.0.0", "vitest": "^4.1.7" }
 }
diff --git a/packages/json-document-object-document/src/object-validation.ts b/packages/json-document-object-document/src/object-validation.ts
index 8ba42fc0..d2eedce8 100644
--- a/packages/json-document-object-document/src/object-validation.ts
+++ b/packages/json-document-object-document/src/object-validation.ts
@@ -1,4 +1,5 @@
 import { createJSONDocument, type JSONValue } from "@interactive-os/json-document";
+import { assertRasterImageSource as assertCanvasImageSource } from "@interactive-os/json-document-file-intake";
 import type { CanvasDocument, ObjectDocument } from "./object-model.js";
 
 function record(value: unknown): value is Record<string, unknown> {
@@ -42,18 +43,7 @@ export function assertObjectDocument(value: unknown): void {
 }
 
 /** Embedded raster only: no external fetch, SVG, HTML, or session-scoped blob URL. Decoding belongs to the platform. */
-export function assertCanvasImageSource(source: unknown): asserts source is string {
-  if (typeof source !== "string") throw new TypeError("Image source must be an embedded PNG, JPEG, or WebP data URL.");
-  const separator = source.indexOf(",");
-  const header = source.slice(0, separator);
-  const bytes = source.slice(separator + 1);
-  // A flat character check avoids recursive regex stack growth on large rasters.
-  if (!["data:image/png;base64", "data:image/jpeg;base64", "data:image/webp;base64"].includes(header)
-    || bytes.length === 0 || bytes.length % 4 !== 0 || /[^A-Za-z0-9+/=]/.test(bytes)
-    || bytes.slice(0, -2).includes("=") || (bytes.at(-2) === "=" && bytes.at(-1) !== "=")) {
-    throw new TypeError("Image source must be an embedded PNG, JPEG, or WebP base64 data URL.");
-  }
-}
+export { assertCanvasImageSource };
 
 function assertCanvasShape(value: ObjectDocument): void {
   if (!positive(value.width) || !positive(value.height)) throw new TypeError("Canvas dimensions must be positive and finite.");
diff --git a/packages/json-document-object-document/tsconfig.json b/packages/json-document-object-document/tsconfig.json
index fa193bf2..22d7f20b 100644
--- a/packages/json-document-object-document/tsconfig.json
+++ b/packages/json-document-object-document/tsconfig.json
@@ -1,6 +1,6 @@
 {
   "extends": "../../tsconfig/library.json",
   "compilerOptions": { "rootDir": "src", "outDir": "dist", "tsBuildInfoFile": "dist/.tsbuildinfo" },
-  "references": [{ "path": "../json-document" }],
+  "references": [{ "path": "../json-document" }, { "path": "../json-document-file-intake" }],
   "include": ["src/**/*.ts"]
 }
diff --git a/packages/json-document-web/README.md b/packages/json-document-web/README.md
index a01ad5a9..c438220e 100644
--- a/packages/json-document-web/README.md
+++ b/packages/json-document-web/README.md
@@ -150,20 +150,29 @@ the formats it enables and their priority, while
 `createWebJSONClipboardRepresentation` owns JSON serialization. The legacy
 named codecs remain compatibility aliases over those domain formats. Clipboard
 surfaces write both the structured json-document MIME payload and its
-`text/plain` projection. Paste
-consumes only a valid structured payload. Parsing arbitrary external plain text
-into domain records or cells remains a host policy.
+`text/plain` projection. `captureWebClipboardPaste` captures an enabled structured
+representation, files, or literal text before the event expires. Its codec is
+optional for file-only consumers. Domain conversion belongs to the canonical
+Editing or Hand API; the Host supplies product policy.
+
+`readWebRasterFiles` validates a PNG/JPEG/WebP batch and prepares its embedded
+content and intrinsic dimensions through `readWebRasterFile`. Canvas and Composer
+share this path. File Intake owns `RasterImageContent`; Web owns reading and
+decoding, not document mutation or server upload. See the
+[Clipboard API and remaining TBD](docs/clipboard.md).
 
 The official keyboard adapter owns `defaultWebKeymap`. `resolve` returns a
 semantic command or `null`; `moveLinePoint` and `moveGridPoint` locate the
 visible neighbor. The host still decides when a command applies and which
 domain Intent to dispatch.
 
-The clipboard binding calls `preventDefault()` only after a successful copy,
-canonical cut, or canonical paste. Cut writes the selected payload before
-asking the Editing companion to remove it. Missing clipboard data, malformed
-payloads, unsupported cut, and rejected editing results leave native handling
-available.
+The clipboard binding cancels cut before attempting a write, and only removes
+the captured selection after the write succeeds. Copy cancels after writing;
+its synchronous paste cancels after decoding a supported representation and
+before invoking Editing. Decode failures retain that binding's existing
+pass-through. In contrast, `captureWebClipboardPaste` claims a recognized
+representation before decoding, so an invalid structured payload cannot fall
+back to other content. Missing or unrecognized content remains unclaimed.
 
 `createWebClipboardSurface` is the public surface-level orchestration API. It
 projects one binding into `onCopy`, `onCut`, and `onPaste` handlers and reports
@@ -195,7 +204,8 @@ The host owns:
 - DOM/canvas geometry and hit testing;
 - external plain-text interpretation and product-specific paste policy;
 - enabled representations and their priority;
-- native text selection, IME, drag/drop, persistence, and remote protocols.
+- composition of canonical text-selection, IME and drag/drop bindings;
+- injection of persistence and remote-system instances.
 
 The module does not access `window`, `document`, or `navigator` during import,
 so non-browser tooling can load it safely.
diff --git a/packages/json-document-web/docs/clipboard.md b/packages/json-document-web/docs/clipboard.md
index 9c8cb33b..8ed686bc 100644
--- a/packages/json-document-web/docs/clipboard.md
+++ b/packages/json-document-web/docs/clipboard.md
@@ -37,7 +37,8 @@ const clipboard = createWebClipboardBinding({
 `captureWebClipboardPaste(event, { codec, files: true, text: true })`는 이벤트가 끝나기 전에
 구조화 MIME → 파일 → `text/plain` 순서로 하나의 표현을 캡처합니다. 성공은 `type`이
 `structured`(payload), `files`(파일 배열), `text`(문자열)인 결과입니다. files/text는 명시한
-경우만 처리하며 기본은 구조화 표현뿐입니다. 파일 메타데이터는 별도 `fileCandidatesFromWebFiles`
+경우만 처리합니다. `codec`을 생략한 `{ files: true }`는 Composer 같은 file-only 소비자를
+지원하며 텍스트/HTML의 native 처리를 소유하지 않습니다. 파일 메타데이터는 별도 `fileCandidatesFromWebFiles`
 API로 File Intake에 전달하고, 파일 참조는 실제 browser File이어야 읽을 수 있습니다.
 
 캡처한 파일 배열과 문자열을 비동기 작업에 넘기며 ClipboardEvent/DataTransfer를 나중에 다시
@@ -52,4 +53,18 @@ decode 실패도 소유한 실패이며 다른 표현으로 떨어지지 않습
 호환되며 read/decode 중 취소하면 리스너를 해제하고 읽기/이미지 요청을 중단합니다.
 파일 형식·크기·개수·픽셀 제한이나 문서 객체 생성은 이 플랫폼 API의 책임이 아닙니다.
 
-실제 텍스트·이미지 입력 및 순서/취소 연결: [Canvas Usage/Source](/demo/canvas).
+### 이미지 batch 준비
+
+`readWebRasterFiles(files, { policy, maxImagePixels, signal?, readRaster? })`는 File Intake의
+정책 검사를 먼저 실행한 뒤 PNG/JPEG/WebP를 순서대로 decode합니다. 성공은
+`{ ok: true, files: [{ candidate, image }] }`이며 image는 File Intake의 `RasterImageContent`입니다.
+한 파일이라도 실패하면 전체 batch의 실패만 반환합니다. 파일 정책 실패, `raster.unsupported`,
+읽기/decode 실패, `raster.pixel-limit`, `raster.cancelled`를 구별합니다.
+
+`policy`와 `maxImagePixels`는 소비자가 결정합니다. 이 함수는 실제 DOM 읽기를
+순차화하지만 문서를 변경하거나 Undo 단위·삽입 위치를 결정하지 않습니다. 준비한
+batch를 어떻게 적용하고 언제 취소할지는 Editing과 각 Hand가 소유합니다.
+
+실제 텍스트·이미지 입력 및 순서/취소 연결: [Canvas Usage/Source](/demo/canvas),
+[Composer Usage/Source](/demo/composer). HTML 이미지, 명시적인 plain paste, 이미지 쓰기와
+OS-native 왕복의 남은 범위는 [Clipboard 기본기 TBD](/docs/clipboard)에 공개합니다.
diff --git a/packages/json-document-web/src/clipboard.ts b/packages/json-document-web/src/clipboard.ts
index d354215f..c0371b1b 100644
--- a/packages/json-document-web/src/clipboard.ts
+++ b/packages/json-document-web/src/clipboard.ts
@@ -32,15 +32,15 @@ export type WebClipboardPaste<Payload extends WebClipboardPayload> =
   | Extract<WebClipboardResult<never, never>, { readonly ok: false }>;
 
 /** Captures native data before the event ends: structured → files → literal text. An owned invalid format never falls through. */
-export function captureWebClipboardPaste<Payload extends WebClipboardPayload>(event: WebClipboardEvent, options: {
-  readonly codec: WebClipboardCodec<Payload>;
+export function captureWebClipboardPaste<Payload extends WebClipboardPayload = WebClipboardPayload>(event: WebClipboardEvent, options: {
+  readonly codec?: WebClipboardCodec<Payload>;
   readonly files?: boolean;
   readonly text?: boolean;
 }): WebClipboardPaste<Payload> {
   const data = event.clipboardData;
   if (data === null) return failure("clipboard.unavailable");
   try {
-    if (Array.from(data.types).includes(options.codec.mimeType)) {
+    if (options.codec && Array.from(data.types).includes(options.codec.mimeType)) {
       event.preventDefault();
       const result = readRepresentations(data, [options.codec]);
       return result.ok ? { ok: true, type: "structured", payload: result.payload } : result;
diff --git a/packages/json-document-web/src/index.ts b/packages/json-document-web/src/index.ts
index acda1c35..5ab7794e 100644
--- a/packages/json-document-web/src/index.ts
+++ b/packages/json-document-web/src/index.ts
@@ -31,6 +31,7 @@ export { createWebViewportPositionPorts } from "./viewport-position.js";
 export { createWebAnchoredFloatingPositionPorts } from "./anchored-floating-position.js";
 export { projectWebClientPointToSVG, webSVGViewportFromElement } from "./svg-coordinate.js";
 export { readWebRasterFile } from "./raster-source.js";
+export { readWebRasterFiles, type WebRasterFileContent, type WebRasterFilesResult } from "./raster-files.js";
 export { composerAttachmentCandidateFromWebFile, composerAttachmentCandidatesFromWebClipboard, composerAttachmentCandidatesFromWebFiles, fileCandidateFromWebFile, fileCandidatesFromWebClipboard, fileCandidatesFromWebFiles } from "./file-intake.js";
 export { renderWebAnnotationRaster } from "./annotation-raster.js";
 export { registerWebVirtualSelectionScope } from "./virtual-selection-scope.js";
diff --git a/packages/json-document-web/src/raster-files.ts b/packages/json-document-web/src/raster-files.ts
new file mode 100644
index 00000000..58c19fc3
--- /dev/null
+++ b/packages/json-document-web/src/raster-files.ts
@@ -0,0 +1,44 @@
+import { assertRasterImageContent, validateFileCandidates, type FileAcceptancePolicy, type FileCandidate, type RasterImageContent } from "@interactive-os/json-document-file-intake";
+import { fileCandidatesFromWebFiles, type WebFileCandidate } from "./file-intake.js";
+import { readWebRasterFile, type WebRasterReadSignal } from "./raster-source.js";
+
+export interface WebRasterFileContent {
+  readonly candidate: FileCandidate;
+  readonly image: RasterImageContent;
+}
+
+export type WebRasterFilesResult =
+  | { readonly ok: true; readonly files: ReadonlyArray<WebRasterFileContent> }
+  | { readonly ok: false; readonly code: string; readonly reason?: string };
+
+/** Validates before reading, decodes sequentially, and returns a complete batch or failure. No document mutation. */
+export async function readWebRasterFiles(files: ReadonlyArray<WebFileCandidate>, options: {
+  readonly policy: FileAcceptancePolicy;
+  readonly maxImagePixels: number;
+  readonly signal?: WebRasterReadSignal;
+  readonly readRaster?: typeof readWebRasterFile;
+}): Promise<WebRasterFilesResult> {
+  if (!Number.isFinite(options.maxImagePixels) || options.maxImagePixels <= 0) throw new TypeError("maxImagePixels must be positive and finite.");
+  const captured = Array.from(files);
+  if (options.signal?.aborted) return { ok: false, code: "raster.cancelled" };
+  const candidates = fileCandidatesFromWebFiles(captured);
+  const accepted = validateFileCandidates(candidates, options.policy);
+  if (!accepted.ok) return accepted;
+  if (candidates.some((file) => !["image/png", "image/jpeg", "image/webp"].includes(file.mediaType ?? ""))) return { ok: false, code: "raster.unsupported" };
+  const prepared: WebRasterFileContent[] = [];
+  for (let index = 0; index < captured.length; index++) {
+    if (options.signal?.aborted) return { ok: false, code: "raster.cancelled" };
+    try {
+      const result = await (options.readRaster ?? readWebRasterFile)(captured[index]!, options.signal ? { signal: options.signal } : {});
+      if (options.signal?.aborted) return { ok: false, code: "raster.cancelled" };
+      if (!result.ok) return result;
+      const image = { source: result.dataURL, width: result.width, height: result.height };
+      assertRasterImageContent(image);
+      if (image.width * image.height > options.maxImagePixels) return { ok: false, code: "raster.pixel-limit" };
+      prepared.push({ candidate: candidates[index]!, image });
+    } catch (error) {
+      return { ok: false, code: "raster.decode-failed", reason: error instanceof Error ? error.message : String(error) };
+    }
+  }
+  return { ok: true, files: prepared };
+}
diff --git a/packages/json-document-web/tests/raster-files.test.ts b/packages/json-document-web/tests/raster-files.test.ts
new file mode 100644
index 00000000..8c2d83dd
--- /dev/null
+++ b/packages/json-document-web/tests/raster-files.test.ts
@@ -0,0 +1,52 @@
+import { expect, test, vi } from "vitest";
+import { captureWebClipboardPaste, readWebRasterFiles, type readWebRasterFile, type WebRasterSourceResult } from "../src/index.js";
+
+const file = { name: "image.png", size: 3, type: "image/png" };
+const image = { ok: true as const, dataURL: "data:image/png;base64,AQID", width: 100, height: 50 };
+const policy = { acceptedMediaTypes: ["image/*"], maxFiles: 4, maxBytesPerFile: 100 };
+const options = { policy, maxImagePixels: 10_000 };
+
+test("PI-FILE: sequential decoding yields portable image content in file order", async () => {
+  let first!: (value: WebRasterSourceResult) => void;
+  const readRaster = vi.fn<typeof readWebRasterFile>().mockImplementationOnce(() => new Promise((resolve) => { first = resolve; })).mockResolvedValue(image);
+  const pending = readWebRasterFiles([file, { ...file, name: "second.png" }], { ...options, readRaster });
+  expect(readRaster).toHaveBeenCalledOnce();
+  first(image);
+  expect(await pending).toEqual({ ok: true, files: [file.name, "second.png"].map((name) => ({ candidate: { name, size: 3, mediaType: "image/png" }, image: { source: image.dataURL, width: 100, height: 50 } })) });
+  expect(readRaster).toHaveBeenCalledTimes(2);
+});
+
+test.each([
+  { input: { ...file, size: 101 }, code: "file-intake.size" },
+  { input: { ...file, type: "image/svg+xml" }, code: "raster.unsupported" },
+  { input: { ...file, name: "" }, code: "file-intake.invalid" },
+])("PI-FILE: $code is rejected before reading", async ({ input, code }) => {
+  const readRaster = vi.fn<typeof readWebRasterFile>();
+  expect(await readWebRasterFiles([input], { ...options, readRaster })).toMatchObject({ ok: false, code });
+  expect(readRaster).not.toHaveBeenCalled();
+});
+
+test.each([
+  { result: { ...image, height: 200 }, code: "raster.pixel-limit" },
+  { result: { ...image, dataURL: "https://example.com/image.png" }, code: "raster.decode-failed" },
+  { result: { ...image, width: NaN }, code: "raster.decode-failed" },
+])("PI-FILE: $code returns no partial batch", async ({ result, code }) => {
+  const readRaster = vi.fn<typeof readWebRasterFile>().mockResolvedValueOnce(image).mockResolvedValueOnce(result);
+  expect(await readWebRasterFiles([file, file], { ...options, readRaster })).toMatchObject({ ok: false, code });
+});
+
+test("PI-CANCEL: cancellation between decoded files prevents subsequent reads", async () => {
+  const controller = new AbortController();
+  const readRaster = vi.fn<typeof readWebRasterFile>(async () => { controller.abort(); return image; });
+  expect(await readWebRasterFiles([file, file], { ...options, readRaster, signal: controller.signal })).toMatchObject({ code: "raster.cancelled" });
+  expect(readRaster).toHaveBeenCalledOnce();
+});
+
+test("file-only Clipboard consumers capture native files without borrowing an Object codec", () => {
+  const files = [file], preventDefault = vi.fn();
+  const event = { clipboardData: { files, types: ["Files", "text/html"], getData: () => "<img>", setData() {} }, preventDefault };
+  const captured = captureWebClipboardPaste(event, { files: true });
+  files.length = 0;
+  expect(captured).toEqual({ ok: true, type: "files", files: [file] }); expect(preventDefault).toHaveBeenCalledOnce();
+  expect(captureWebClipboardPaste({ ...event, clipboardData: { ...event.clipboardData, types: ["text/plain"] } }, { files: true })).toMatchObject({ ok: false, code: "clipboard.empty" });
+});
diff --git a/site/src/shared/composer/ComposerDemo.tsx b/site/src/shared/composer/ComposerDemo.tsx
index 2a3c095a..37050faa 100644
--- a/site/src/shared/composer/ComposerDemo.tsx
+++ b/site/src/shared/composer/ComposerDemo.tsx
@@ -44,7 +44,7 @@ const hostConfig = {
   profile: COMPOSER_HOST_PROFILE_V1,
   models: modelOptions,
   suggestions,
-  attachments: { acceptedMediaTypes: ["*/*"], maxFiles: null, maxBytesPerFile: null },
+  attachments: { acceptedMediaTypes: ["*/*"], maxFiles: 10, maxBytesPerFile: 10 * 1024 * 1024 },
   interaction: { submit: "enter", newline: "shift-enter" },
 } satisfies ComposerHostConfig<ComposerModel>;
 
@@ -72,7 +72,7 @@ export function ComposerDemo(props: {
   const onAction = useCallback(() => undefined, []);
   const renderComposerReference = useCallback((node: RichTextNode) => composer.renderReference(node, { className: "composer-atom" }), [composer.renderReference]);
   const addActions: ReadonlyArray<{ readonly id: string; readonly label: string; readonly content: ReactNode; readonly run: () => void }> = [
-    { id: "file", label: "파일 업로드", content: <><FileText aria-hidden="true" size={16} /><span><strong>파일 업로드</strong><small>이미지와 문서를 첨부해요</small></span></>, run: composer.openFilePicker },
+    { id: "file", label: "파일 첨부", content: <><FileText aria-hidden="true" size={16} /><span><strong>파일 첨부</strong><small>이미지와 파일 정보를 첨부해요</small></span></>, run: composer.openFilePicker },
     { id: "skill", label: "스킬", content: <><span>/</span><span><strong>스킬</strong><small>반복 작업을 빠르게 실행해요</small></span></>, run: () => composer.chooseTrigger("/") },
     { id: "agent", label: "에이전트", content: <><span>@</span><span><strong>에이전트</strong><small>전문 에이전트와 함께 작업해요</small></span></>, run: () => composer.chooseTrigger("@") },
   ];
@@ -101,10 +101,11 @@ export function ComposerDemo(props: {
             <div className="composer-attachments" aria-label="첨부 파일">
               {composer.attachments.map((file) => (
                 <div className="composer-file" key={file.id}>
-                  <span className="composer-file-ic" aria-hidden="true">{file.kind === "image" ? <Image size={16} /> : <FileText size={16} />}</span>
+                  {file.image ? <img className="composer-file-preview" src={file.image.source} alt={file.name} />
+                    : <span className="composer-file-ic" aria-hidden="true">{file.kind === "image" ? <Image size={16} /> : <FileText size={16} />}</span>}
                   <span className="composer-file-info">
                     <span className="composer-file-name">{file.name}</span>
-                    <span className="composer-file-size">{formatFileSize(file.size)}</span>
+                    <span className="composer-file-size">{formatFileSize(file.size)}{file.image ? ` · ${file.image.width} × ${file.image.height}` : " · 파일 정보만"}</span>
                   </span>
                   <Command className="composer-file-remove" label={`${file.name} 제거`} onClick={() => composer.removeAttachment(file.id)}><X aria-hidden="true" size={16} /></Command>
                 </div>
@@ -112,6 +113,12 @@ export function ComposerDemo(props: {
             </div>
           ) : null}
 
+          {composer.isPreparingAttachments ? <div className="composer-attachment-status">
+            <span role="status">이미지를 준비하고 있습니다. 계속 입력할 수 있어요.</span>
+            <Command className="composer-icon-button" label="이미지 준비 취소" onClick={composer.cancelAttachments}><X aria-hidden="true" size={16} /></Command>
+          </div> : null}
+          {composer.attachmentError ? <p className="composer-attachment-status" role="alert">첨부하지 못했습니다: {composer.attachmentError.reason ?? composer.attachmentError.code}</p> : null}
+
           <div className="composer-input-row">
             <Menu
               label="추가"
@@ -151,7 +158,7 @@ export function ComposerDemo(props: {
               classNames={{ root: "composer-select-root", trigger: "composer-model-pill", listbox: "composer-layer composer-model-layer", focusedOption: "selected" }}
             />
             <Command className="composer-icon-button" label="음성 입력"><AudioLines aria-hidden="true" size={16} /></Command>
-            <Command kind="primary" label="전송 (Enter)" className={`composer-send-button${composer.hasContent ? " is-active" : ""}`} disabled={!composer.hasContent} onClick={composer.submit}>전송</Command>
+            <Command kind="primary" label="전송 (Enter)" className={`composer-send-button${composer.canSubmit ? " is-active" : ""}`} disabled={!composer.canSubmit} onClick={composer.submit}>전송</Command>
           </div>
 
           {composer.commandKind === "mention" ? (
diff --git a/site/src/shared/composer/composer.css b/site/src/shared/composer/composer.css
index 060a150e..6db03e86 100644
--- a/site/src/shared/composer/composer.css
+++ b/site/src/shared/composer/composer.css
@@ -51,6 +51,8 @@
 .composer-file { display: flex; width: 220px; min-width: 220px; align-items: center; gap: 10px; padding: 9px 10px; border: 1px solid var(--color-border-subtle); border-radius: var(--radius-surface); background: var(--color-background-canvas); }
 .composer-file-ic { display: grid; width: 34px; height: 34px; flex: 0 0 34px; place-items: center; border-radius: var(--radius-control); background: var(--color-background-subtle); color: var(--color-foreground-muted); }
 .composer-file-info { display: grid; min-width: 0; flex: 1; }
+.composer-file-preview { width: 48px; height: 48px; flex: 0 0 48px; object-fit: contain; }
+.composer-attachment-status { display: flex; align-items: center; gap: 8px; margin: 0; color: var(--color-foreground-muted); font-size: 12px; }
 .composer-file-name { overflow: hidden; color: var(--color-foreground-strong); font-size: 13px; font-weight: 600; text-overflow: ellipsis; white-space: nowrap; }
 .composer-file-size { color: var(--color-foreground-muted); font-size: 11px; }
 .composer-file-remove { border: 0; background: transparent; color: var(--color-foreground-muted); font-size: 18px; cursor: pointer; }
diff --git a/site/src/shared/demo-workbench/demo-sources.ts b/site/src/shared/demo-workbench/demo-sources.ts
index ad09b68b..94bc83b1 100644
--- a/site/src/shared/demo-workbench/demo-sources.ts
+++ b/site/src/shared/demo-workbench/demo-sources.ts
@@ -9,6 +9,7 @@ import canvasObjectViewSource from "../../../../packages/json-document-canvas/sr
 import canvasClipboardSource from "../../../../packages/json-document-canvas/src/canvas-clipboard.ts?raw";
 import canvasClipboardEditingSource from "../../../../packages/json-document-editing/src/canvas-clipboard.ts?raw";
 import objectPasteSessionSource from "../../../../packages/json-document-editing/src/object-paste-session.ts?raw";
+import editingPreparationQueueSource from "../../../../packages/json-document-editing/src/preparation-queue.ts?raw";
 import editingSnapshotSource from "../../../../packages/json-document-react/src/editing-snapshot.ts?raw";
 import pointerTrackingSource from "../../../../packages/json-document/src/foundation/patch/track.ts?raw";
 import editingObservationSource from "../../../../packages/json-document-react/src/editing-observation.ts?raw";
@@ -91,6 +92,7 @@ import annotationHandSource from "../../../../packages/json-document-annotation/
 import annotationEditingSource from "../../../../packages/json-document-editing/src/annotation.ts?raw";
 import webSVGCoordinateSource from "../../../../packages/json-document-web/src/svg-coordinate.ts?raw";
 import webRasterSource from "../../../../packages/json-document-web/src/raster-source.ts?raw";
+import webRasterFilesSource from "../../../../packages/json-document-web/src/raster-files.ts?raw";
 import webAnnotationRasterSource from "../../../../packages/json-document-web/src/annotation-raster.ts?raw";
 import uiMenuSource from "../../../../packages/json-document-ui-primitives-react/src/menu.tsx?raw";
 import uiSelectSource from "../../../../packages/json-document-ui-primitives-react/src/select.tsx?raw";
@@ -114,8 +116,10 @@ import composerInteractionSource from "../../../../packages/json-document-compos
 import composerSuggestionsSource from "../../../../packages/json-document-composer/src/suggestions.ts?raw";
 import composerReferenceAtomSource from "../../../../packages/json-document-composer-react/src/reference-atom.tsx?raw";
 import composerReactLifecycleSource from "../../../../packages/json-document-composer-react/src/use-composer.tsx?raw";
+import composerAttachmentsSource from "../../../../packages/json-document-composer-react/src/attachments.ts?raw";
 import composerCommandMenuSource from "../../../../packages/json-document-composer-react/src/command-menu.ts?raw";
 import fileIntakeSource from "../../../../packages/json-document-file-intake/src/index.ts?raw";
+import rasterContentSource from "../../../../packages/json-document-file-intake/src/raster-content.ts?raw";
 import suggestionSource from "../../../../packages/json-document-rich-text-suggestion/src/index.ts?raw";
 import suggestionReactSource from "../../../../packages/json-document-rich-text-suggestion-react/src/index.ts?raw";
 import mentionSource from "../../../../packages/json-document-rich-text-mention/src/index.ts?raw";
@@ -205,6 +209,10 @@ const excludedSources = new Set([
   "routes/widgets/WidgetDemoFrame.tsx",
 ]);
 const registeredUsageSources = new Map<string, string>([
+  ["packages/json-document-editing/src/preparation-queue.ts", editingPreparationQueueSource],
+  ["packages/json-document-web/src/raster-files.ts", webRasterFilesSource],
+  ["packages/json-document-file-intake/src/raster-content.ts", rasterContentSource],
+  ["packages/json-document-composer-react/src/attachments.ts", composerAttachmentsSource],
   ["packages/json-document-object-document/src/object-model.ts", objectModelSource],
   ["packages/json-document-object-document/src/object-validation.ts", objectValidationSource],
   ["packages/json-document-object-document/src/object-operation.ts", objectOperationSource],
@@ -352,6 +360,11 @@ const registeredUsageSources = new Map<string, string>([
   ["packages/json-document-zod/src/index.ts", zodSource],
 ]);
 const registeredPublicUsages = [
+  { packageName: "@interactive-os/json-document-editing", symbol: "createEditingPreparationQueue", sourcePath: "packages/json-document-editing/src/preparation-queue.ts" },
+  { packageName: "@interactive-os/json-document-editing", symbol: "createObjectPasteSession", sourcePath: "packages/json-document-editing/src/preparation-queue.ts" },
+  { packageName: "@interactive-os/json-document-web", symbol: "readWebRasterFiles", sourcePath: "packages/json-document-web/src/raster-files.ts" },
+  ...["assertRasterImageSource", "assertRasterImageContent", "RasterImageContent"].map((symbol) => ({ packageName: "@interactive-os/json-document-file-intake", symbol, sourcePath: "packages/json-document-file-intake/src/raster-content.ts" })),
+  { packageName: "@interactive-os/json-document-composer-react", symbol: "useComposer", sourcePath: "packages/json-document-composer-react/src/attachments.ts" },
   ...(["CanvasHand", "useCanvasHand", "createCanvasClipboardBinding"] as const).map((symbol) => ({ packageName: "@interactive-os/json-document-canvas", symbol, sourcePath: "packages/json-document-canvas/src/canvas-clipboard.ts" })),
   { packageName: "@interactive-os/json-document-editing", symbol: "createCanvasClipboard", sourcePath: "packages/json-document-editing/src/canvas-clipboard.ts" },
   { packageName: "@interactive-os/json-document-editing", symbol: "createObjectPasteSession", sourcePath: "packages/json-document-editing/src/object-paste-session.ts" },
diff --git a/site/tests/browser/composer-demo.spec.ts b/site/tests/browser/composer-demo.spec.ts
index 654315bf..a5fee35c 100644
--- a/site/tests/browser/composer-demo.spec.ts
+++ b/site/tests/browser/composer-demo.spec.ts
@@ -93,20 +93,34 @@ test("Mention Hands가 가상 포커스와 atom 경계 삭제를 완성한다",
   expect(pageErrors).toEqual([]);
 });
 
-test("클립보드 파일 paste를 undo 가능한 attachment로 저장한다", async ({ page }) => {
+test("실제 Clipboard 이미지 내용을 미리보기와 undo 가능한 attachment로 저장한다", async ({ page }) => {
   await page.goto("/demo/composer");
   const editor = page.getByLabel("Agent Chat Composer");
   await editor.click();
-  await editor.evaluate((element) => {
+  await editor.evaluate(async (element) => {
+    const raster = document.createElement("canvas");
+    raster.width = 64;
+    raster.height = 32;
+    const context = raster.getContext("2d")!;
+    context.fillStyle = "#2864dc";
+    context.fillRect(0, 0, 64, 32);
+    const blob = await new Promise<Blob>((resolve) => raster.toBlob((value) => resolve(value!), "image/png"));
     const clipboard = new DataTransfer();
-    clipboard.items.add(new File(["image"], "pasted.png", { type: "image/png" }));
+    clipboard.items.add(new File([blob], "pasted.png", { type: "image/png" }));
     element.dispatchEvent(new ClipboardEvent("paste", { bubbles: true, cancelable: true, clipboardData: clipboard }));
   });
 
   await expect(page.getByLabel("첨부 파일")).toContainText("pasted.png");
   await expect(page.getByTestId("composer-draft-json")).toContainText('"kind": "image"');
+  await expect(page.getByTestId("composer-draft-json")).toContainText("data:image/png;base64,");
+  const preview = page.getByRole("img", { name: "pasted.png" });
+  await expect(preview).toBeVisible();
+  expect(await preview.evaluate((element) => (element as HTMLImageElement).naturalWidth)).toBe(64);
   await editor.press("Control+z");
   await expect(page.getByLabel("첨부 파일")).not.toBeVisible();
+  await editor.press("Control+Shift+z");
+  await expect(preview).toBeVisible();
+  await expect(page.getByTestId("composer-draft-json")).toContainText('"width": 64');
 });
 
 test("빈 Composer에 처음 입력할 때 React DOM 삭제 오류가 발생하지 않는다", async ({ page }) => {
diff --git a/site/tests/unit/composer-demo.test.tsx b/site/tests/unit/composer-demo.test.tsx
index e3838843..d5dd33a6 100644
--- a/site/tests/unit/composer-demo.test.tsx
+++ b/site/tests/unit/composer-demo.test.tsx
@@ -6,7 +6,9 @@ import composerCommandsSource from "../../../packages/json-document-composer/src
 import composerSchemaSource from "../../../packages/json-document-composer/src/schema.ts?raw";
 import composerReferenceAtomSource from "../../../packages/json-document-composer-react/src/reference-atom.tsx?raw";
 import composerLifecycleSource from "../../../packages/json-document-composer-react/src/use-composer.tsx?raw";
+import composerAttachmentsSource from "../../../packages/json-document-composer-react/src/attachments.ts?raw";
 import composerCommandMenuSource from "../../../packages/json-document-composer-react/src/command-menu.ts?raw";
+import { discoverDemoSources } from "../../src/shared/demo-workbench/demo-sources";
 
 afterEach(cleanup);
 
@@ -35,13 +37,32 @@ describe("Agent Chat Composer Hands", () => {
     expect(composerDemoSource).not.toContain('id === "skill"');
     expect(composerDemoSource).not.toContain('id === "agent"');
     expect(composerDemoSource).toContain("addActions.find((action) => action.id === id)?.run()");
-    expect(composerLifecycleSource).toContain("addComposerAttachments(");
-    expect(composerLifecycleSource).toContain("fileCandidatesFromWebFiles(");
+    expect(composerLifecycleSource).toContain("useComposerAttachments(");
+    expect(composerAttachmentsSource).toContain("addComposerAttachments(");
+    expect(composerAttachmentsSource).toContain("fileCandidatesFromWebFiles(");
+    expect(composerAttachmentsSource).toContain("readWebRasterFiles(");
+    expect(composerAttachmentsSource).toContain("createEditingPreparationQueue<");
     expect(composerCommandMenuSource).toContain("useRichTextSuggestion(");
     expect(composerCommandMenuSource).toContain("useRichTextMentionSuggestions(");
     expect(composerLifecycleSource).toContain("<ComposerReferenceAtom");
   });
 
+  test("exposes the attachment preparation owners with API references in Source", async () => {
+    const sources = await discoverDemoSources("routes/composer-demo/ComposerDemoRoute.tsx");
+    for (const path of [
+      "packages/json-document-composer-react/src/attachments.ts",
+      "packages/json-document-composer/src/commands.ts",
+      "packages/json-document-file-intake/src/raster-content.ts",
+      "packages/json-document-web/src/raster-files.ts",
+      "packages/json-document-editing/src/preparation-queue.ts",
+    ]) {
+      const source = sources.find((entry) => entry.path === path);
+      expect(source, path).toBeDefined();
+      expect(source?.referencePath).toMatch(/^\/docs\/api\//);
+      expect(await source?.load()).toBeTruthy();
+    }
+  });
+
   test("delegates file intake and mention responsibilities to their canonical owners", () => {
     expect(composerCommandsSource).toContain("validateFileCandidates(");
     expect(composerCommandsSource).not.toContain("function acceptsMediaType");
@@ -84,7 +105,7 @@ describe("Agent Chat Composer Hands", () => {
   test("opens the Cstar-shaped add and model layers from real controls", () => {
     render(<ComposerDemoRoute />);
     fireEvent.click(screen.getByRole("button", { name: "추가" }));
-    expect(screen.getByRole("menuitem", { name: /파일 업로드/ })).toBeTruthy();
+    expect(screen.getByRole("menuitem", { name: /파일 첨부/ })).toBeTruthy();
     expect(screen.getByRole("menuitem", { name: /스킬/ })).toBeTruthy();
     expect(screen.getByRole("menuitem", { name: /에이전트/ })).toBeTruthy();
 
diff --git a/site/tests/unit/demo-workbench.test.tsx b/site/tests/unit/demo-workbench.test.tsx
index b07afd58..870a3bca 100644
--- a/site/tests/unit/demo-workbench.test.tsx
+++ b/site/tests/unit/demo-workbench.test.tsx
@@ -70,7 +70,10 @@ describe("Demo definition and source discovery", () => {
       ["packages/json-document-canvas/src/canvas-clipboard.ts", "/docs/api/canvas"],
       ["packages/json-document-editing/src/canvas-clipboard.ts", "/docs/api/editing"],
       ["packages/json-document-editing/src/object-paste-session.ts", "/docs/api/editing"],
+      ["packages/json-document-editing/src/preparation-queue.ts", "/docs/api/editing"],
       ["packages/json-document-web/src/raster-source.ts", "/docs/api/web"],
+      ["packages/json-document-web/src/raster-files.ts", "/docs/api/web"],
+      ["packages/json-document-file-intake/src/raster-content.ts", "/docs/api/file-intake"],
       ["packages/json-document-file-intake/src/index.ts", "/docs/api/file-intake"],
     ]) {
       const file = sources.find((source) => source.path === path);
@@ -237,6 +240,7 @@ describe("Demo definition and source discovery", () => {
       "packages/json-document-editing/src/object.ts",
       "packages/json-document-object-document/src/object-model.ts",
       "packages/json-document-object-document/src/object-validation.ts",
+      "packages/json-document-file-intake/src/raster-content.ts",
       "packages/json-document/src/application/document/create.ts",
       "packages/json-document-object-document/src/object-projection.ts",
       "packages/json-document-object-document/src/object-operation.ts",
diff --git a/standards/editing-grammar.md b/standards/editing-grammar.md
index 2e569e4e..7f46e7d8 100644
--- a/standards/editing-grammar.md
+++ b/standards/editing-grammar.md
@@ -273,6 +273,33 @@ offset도 비교하며 블록 toggle과 전체 블록 Copy의 의미는 유지
 유지하는 증거다. offset 하나로 과거 native range 전체를 복원한다는 계약이나
 profile 동결로 확대하지 않는다.
 
+## Paste × Image 기본기: TBD 선행 계약
+
+TBD는 구현 여부를 숨기는 이름이 아니다. 먼저 지원하려는 입력·관찰 결과·owner와
+판정 사례를 기록하고, 실행 증거를 확보한 범위만 구현으로 바꾼다. 이 표는 기존
+EG-COPY/CUT/PASTE/HISTORY의 구체화이며 새로운 Stable profile이나 Core API가 아니다.
+
+| 사례 | 목표 / profile 결정 | owner | 현재 상태와 증거 |
+| --- | --- | --- | --- |
+| PI-FILE | PNG/JPEG/WebP를 읽고 정책·decode 실패 batch를 원자적으로 거절 | File Intake·Web·각 Hand | 공통 Web batch 구현; [reader 사례](../packages/json-document-web/tests/raster-files.test.ts) |
+| PI-CONTENT | 이미지 내용·치수는 문서에 포함하거나 지속 가능한 asset 참조로 보존; metadata만으로 완료를 주장하지 않음 | 각 Document Type | Canvas·Composer embedded content 구현; [Composer JSON·History 사례](../packages/json-document-composer/tests/composer.test.ts) |
+| PI-ORDER | 준비 완료 순서가 달라도 요청 순서로 한 batch씩 반영 | Editing | Object·Composer가 공통 queue 소비; [순서·재진입 사례](../packages/json-document-editing/tests/preparation-queue.test.ts) |
+| PI-CANCEL | 취소·History 작업·unmount 뒤 늦은 결과는 무효 | Editing·각 Hand | Object 자동 무효화, Composer Escape·binding History·unmount 취소 구현; [취소 사례](../packages/json-document-composer-react/tests/composer-attachments.test.tsx) |
+| PI-TYPING | 첨부 준비 중 typing/caret 이동 허용; 완료 시 최신 첨부 목록 뒤에 추가 | Composer·React Connector | 구현; [연속 첨부·typing·caret 사례](../packages/json-document-composer-react/tests/composer-attachments.test.tsx). inline anchor mapping은 아님 |
+| PI-HTML | 대체 MIME 선택과 HTML 내부의 글+이미지 순서 보존을 구분 | Web·Rich Text Web·각 Hand | TBD: HTML 이미지, 불가한 source의 실패와 안전한 변환 |
+| PI-PLAIN | 명시적인 plain paste와 지원 서식 paste를 분리 | Web·Affordance·각 Hand | TBD: 실제 modifier/native editable 사례 |
+| PI-EXPORT | 선택한 Canvas 객체를 PNG로 복사; write 실패는 문서 불변 | Canvas·Web | TBD: 혼합 선택·투명 배경·권한 실패·외부 앱 확인 |
+| PI-NATIVE | OS screenshot, 브라우저 Copy Image, Docs/Slides HTML, 외부 앱 왕복 | Web·제품 경로 | TBD: DOM 합성 이벤트를 OS-native 증거로 계산하지 않음 |
+
+첫 이미지 slice는 서버 upload·임의 URL fetch·HTML import를 추가하지 않는다.
+TBD를 위해 미동작 public stub이나 범용 registry를 만들지 않는다. Canvas의
+외부 문서/선택 변경 시 취소 정책과 Composer의 typing 중 첨부 준비 유지 정책은
+서로 다른 profile 선택으로 유지한다. 동일한 준비 queue·raster 검증/읽기 책임만
+정본 API로 공유한다. 실제 Usage와 Source는 Canvas·Composer가 각각 소비하는
+owner API에 연결하며 이 표로 API catalog를 대체하지 않는다.
+Composer 외부의 직접 editor Undo/Redo나 draft 교체는 `cancelAttachments()`를 먼저
+호출해야 한다. 이는 binding 바깥의 작업을 자동 감지한다는 보장이 아니다.
+
 ## 장기 호환성
 
 약속하는 것은 **고정된 profile의 지원 입력과 관찰 가능한 결과**다. 같은 profile

From df9f3ab78f0a7b5d3a6161ae320cc53f0df82b11 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E1=84=8B=E1=85=B2=E1=84=8B=E1=85=AD=E1=86=BC=E1=84=90?=
 =?UTF-8?q?=E1=85=A2?= <teo.v@navercorp.com>
Date: Wed, 9 Sep 2026 22:48:42 +0900
Subject: [PATCH 15/20] =?UTF-8?q?feat(clipboard):=20HTML=20=EC=9D=B4?=
 =?UTF-8?q?=EB=AF=B8=EC=A7=80=EC=99=80=20=EC=88=9C=EC=84=9C=20=EC=9E=88?=
 =?UTF-8?q?=EB=8A=94=20=ED=98=BC=ED=95=A9=20=EC=9E=85=EB=A0=A5=EC=9D=84=20?=
 =?UTF-8?q?=EC=97=B0=EA=B2=B0=ED=95=9C=EB=8B=A4?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 docs/api-reference/editing.md                 |  10 +-
 docs/api-reference/web.md                     |  57 +++++++++-
 docs/public/adapter-clipboard.md              |  13 ++-
 docs/public/clipboard.md                      |  16 ++-
 docs/public/composer.md                       |   7 +-
 package-lock.json                             |   1 +
 packages/json-document-canvas/README.md       |   3 +-
 packages/json-document-canvas/docs/api.md     |  13 ++-
 .../src/canvas-clipboard.ts                   |   9 +-
 .../tests/canvas-clipboard.test.ts            |  46 ++++++++
 .../json-document-composer-react/README.md    |  13 ++-
 .../src/attachments.ts                        |  29 +++--
 .../src/use-composer.tsx                      |   7 +-
 .../tests/composer-attachments.test.tsx       |  65 +++++++++++
 packages/json-document-editing/README.md      |  18 ++++
 .../src/canvas-clipboard.ts                   |  38 ++++++-
 packages/json-document-editing/src/index.ts   |   2 +-
 .../tests/canvas-clipboard.test.ts            |  39 +++++++
 .../json-document-rich-text-web/README.md     |   5 +
 .../src/clipboard.ts                          |   8 +-
 .../tests/clipboard.test.ts                   |   7 ++
 packages/json-document-web/README.md          |  13 ++-
 packages/json-document-web/docs/clipboard.md  |  38 ++++++-
 packages/json-document-web/package.json       |   1 +
 packages/json-document-web/src/clipboard.ts   |  27 ++++-
 .../json-document-web/src/html-clipboard.ts   |  79 ++++++++++++++
 .../json-document-web/src/html-fragment.ts    |  17 +++
 packages/json-document-web/src/index.ts       |   3 +
 .../tests/html-clipboard.test.ts              | 102 ++++++++++++++++++
 site/src/shared/composer/ComposerDemo.tsx     |   6 +-
 .../src/shared/demo-workbench/demo-sources.ts |   9 ++
 site/tests/unit/composer-demo.test.tsx        |  16 +++
 site/tests/unit/demo-workbench.test.tsx       |   2 +
 standards/editing-grammar.md                  |   5 +-
 34 files changed, 679 insertions(+), 45 deletions(-)
 create mode 100644 packages/json-document-editing/tests/canvas-clipboard.test.ts
 create mode 100644 packages/json-document-web/src/html-clipboard.ts
 create mode 100644 packages/json-document-web/src/html-fragment.ts
 create mode 100644 packages/json-document-web/tests/html-clipboard.test.ts

diff --git a/docs/api-reference/editing.md b/docs/api-reference/editing.md
index c681de1c..f4589e0f 100644
--- a/docs/api-reference/editing.md
+++ b/docs/api-reference/editing.md
@@ -541,7 +541,14 @@ calendarVisibleHourBand(startMinutes: number, endMinutes: number, hourStart: num
 ```ts
 type CanvasClipboardContent =
   | { readonly type: "text"; readonly text: string }
-  | { readonly type: "images"; readonly images: ReadonlyArray<{ readonly source: string; readonly width: number; readonly height: number; readonly label: string }> };
+  | { readonly type: "images"; readonly images: ReadonlyArray<{ readonly source: string; readonly width: number; readonly height: number; readonly label: string }> }
+  | { readonly type: "mixed"; readonly items: ReadonlyArray<CanvasClipboardItem> };
+```
+## `CanvasClipboardItem`
+
+```ts
+type CanvasClipboardItem = { readonly type: "text"; readonly text: string }
+  | ({ readonly type: "image" } & Parameters<typeof createCanvasImage>[0]);
 ```
 ## `CanvasClipboardOptions`
 
@@ -551,6 +558,7 @@ interface CanvasClipboardOptions {
   readonly textColor: string;
   readonly fontSize: number;
   readonly imageOffset?: number;
+  readonly contentGap?: number;
 }
 ```
 ## `createAnnotationEditor`
diff --git a/docs/api-reference/web.md b/docs/api-reference/web.md
index 50b27b26..9768c6f1 100644
--- a/docs/api-reference/web.md
+++ b/docs/api-reference/web.md
@@ -39,7 +39,8 @@ calendarMinutesFromWebGrid(clientY: number, bounds: { readonly top: number; read
 ## `captureWebClipboardPaste`
 
 ```ts
-captureWebClipboardPaste<Payload extends WebClipboardPayload = WebClipboardPayload>(event: WebClipboardEvent, options: { readonly codec?: WebClipboardCodec<Payload>; readonly files?: boolean; readonly text?: boolean; }): WebClipboardPaste<Payload>
+captureWebClipboardPaste<Payload extends WebClipboardPayload = WebClipboardPayload>(event: WebClipboardEvent, options: { readonly codec?: WebClipboardCodec<Payload>; readonly files?: boolean; readonly text?: boolean; readonly html?: never; readonly delegatedMimeTypes?: ReadonlyArray<string>; }): WebClipboardPaste<Payload>
+captureWebClipboardPaste<Payload extends WebClipboardPayload = WebClipboardPayload>(event: WebClipboardEvent, options: { readonly codec?: WebClipboardCodec<Payload>; readonly files?: boolean; readonly text?: boolean; readonly html?: "images"; readonly delegatedMimeTypes?: ReadonlyArray<string>; }): WebHTMLClipboardPaste<Payload>
 ```
 ## `chordFromStroke`
 
@@ -203,6 +204,16 @@ const objectClipboardCodec: WebClipboardCodec<ObjectClipboard>
 ```ts
 const orderClipboardCodec: WebClipboardCodec<OrderClipboard>
 ```
+## `parseWebClipboardHTML`
+
+```ts
+parseWebClipboardHTML(html: string): WebHTMLClipboardContent | null
+```
+## `parseWebHTMLFragment`
+
+```ts
+parseWebHTMLFragment(html: string): WebHTMLFragment | null
+```
 ## `pressInteractionFromWeb`
 
 ```ts
@@ -218,6 +229,11 @@ projectWebClientPointToSVG(point: WebClientPoint, viewport: WebSVGViewport): Web
 ```ts
 projectWebWidgetState(state: WebWidgetState): WebWidgetARIA
 ```
+## `readWebHTMLClipboard`
+
+```ts
+readWebHTMLClipboard(content: WebHTMLClipboardContent, options: Parameters<typeof readWebRasterFiles>[1] & { readonly currentCount?: number; }): Promise<WebHTMLClipboardResult>
+```
 ## `readWebRasterFile`
 
 ```ts
@@ -626,6 +642,45 @@ interface WebGridCellAddressRoot<Cell extends WebGridCellAddressElement> {
   querySelectorAll(selectors: string): ArrayLike<Cell>;
 }
 ```
+## `WebHTMLClipboardContent`
+
+```ts
+interface WebHTMLClipboardContent { readonly parts: ReadonlyArray<WebHTMLClipboardPart> }
+```
+## `WebHTMLClipboardPart`
+
+```ts
+type WebHTMLClipboardPart =
+  | { readonly type: "text"; readonly text: string }
+  | { readonly type: "image"; readonly source: string; readonly label: string };
+```
+## `WebHTMLClipboardPaste`
+
+```ts
+type WebHTMLClipboardPaste<Payload extends WebClipboardPayload> = WebClipboardPaste<Payload>
+  | { readonly ok: true; readonly type: "html"; readonly content: WebHTMLClipboardContent };
+```
+## `WebHTMLClipboardResult`
+
+```ts
+type WebHTMLClipboardResult =
+  | { readonly ok: true; readonly parts: ReadonlyArray<Extract<WebHTMLClipboardPart, { readonly type: "text" }> | ({ readonly type: "image" } & WebRasterFileContent)> }
+  | { readonly ok: false; readonly code: string; readonly reason?: string };
+```
+## `WebHTMLFragment`
+
+```ts
+interface WebHTMLFragment { readonly childNodes: ArrayLike<WebHTMLNode> }
+```
+## `WebHTMLNode`
+
+```ts
+interface WebHTMLNode {
+  readonly nodeType: number;
+  readonly textContent: string | null;
+  readonly childNodes: ArrayLike<WebHTMLNode>;
+}
+```
 ## `WebJSONClipboardFormat`
 
 ```ts
diff --git a/docs/public/adapter-clipboard.md b/docs/public/adapter-clipboard.md
index ab1d1454..236c2df2 100644
--- a/docs/public/adapter-clipboard.md
+++ b/docs/public/adapter-clipboard.md
@@ -48,15 +48,20 @@ interface WebClipboardSurface<Payload, EditingResult> {
 
 ## 외부 이미지 입력 준비
 
-`captureWebClipboardPaste(event, { codec?, files?, text? })`는 event가 끝나기 전에
-활성화한 표현을 한 번만 선택합니다. Codec을 생략한 `{ files: true }`는 이미지 첨부를
-처리하고, 파일이 없는 text·HTML은 기존 Rich Text binding에 남깁니다.
+`captureWebClipboardPaste(event, { codec?, files?, html?, text?, delegatedMimeTypes? })`는 event가 끝나기 전에
+활성화한 표현을 한 번만 선택합니다. `html: "images"`를 켜면 구조화 → 파일 → 이미지가
+포함된 HTML → 일반 텍스트 순입니다. `delegatedMimeTypes`는 기존 중첩 binding의 MIME을
+캡처 전에 위임합니다. Codec과 text를 생략한 `{ files: true, html: "images" }`는 이미지
+입력을 처리하고 이미지 없는 text·HTML은 기존 Rich Text binding에 남깁니다.
 `readWebRasterFiles`는 선택한 파일 batch의 정책·PNG/JPEG/WebP decode를 검증하고
 실제 내용과 크기를 반환합니다. 이 단계는 문서나 History를 변경하지 않습니다.
+`parseWebClipboardHTML`은 inert fragment에서 글·이미지 순서를 읽고,
+`readWebHTMLClipboard`는 포함된 raster data URL을 같은 정책·decode 경로로 준비합니다.
+외부 URL은 요청하지 않으며 읽을 수 없는 source는 전체 실패입니다.
 
 API 계약은 소유 패키지의 [Web API](/docs/api/web)에 있으며
 [Canvas](/demo/canvas)와 [Composer](/demo/composer)가 같은 준비 경로를 사용합니다.
-HTML 이미지·혼합 입력과 외부 앱 왕복은 [Paste × Image TBD](clipboard.md#paste--image-기본기--tbd)에
+HTML의 남은 source·혼합 입력과 외부 앱 왕복은 [Paste × Image TBD](clipboard.md#paste--image-기본기--tbd)에
 구현 범위와 구분해 공개합니다.
 
 ## `createWebClipboardTextWriter`
diff --git a/docs/public/clipboard.md b/docs/public/clipboard.md
index b8dbe585..c18ed4bd 100644
--- a/docs/public/clipboard.md
+++ b/docs/public/clipboard.md
@@ -60,7 +60,7 @@ Clipboard의 기본기는 다른 앱에서 가져온 내용을 편집 가능한
 | 이미지 파일 입력 | Canvas·Composer 공통 경로 구현 | PNG/JPEG/WebP를 실제로 읽고 표시하며, 실패 batch는 삽입하지 않음 | File Intake·Web·각 Hand |
 | 이미지 내용 보존 | Canvas 객체·Composer 첨부에 포함 | Undo/Redo·JSON 왕복·Composer submit, Canvas 구조 복사 후에도 내용과 치수 유지 | 각 문서 모델·Editing |
 | 비동기 편집 | 공통 순서·취소 queue 구현 | 연속 요청 순서 유지, 취소 후 늦은 삽입 없음; Composer는 준비 중 타이핑 가능 | Editing·각 Hand |
-| HTML 이미지·글과 이미지 | TBD | HTML 안의 이미지와 글의 순서를 지원하는 문서 의미로 변환; 읽을 수 없는 이미지는 실패를 알림 | Web·Rich Text Web·각 문서 모델 |
+| HTML 이미지·글과 이미지 | 일부 구현: 포함된 raster와 Canvas 혼합 입력, Composer 이미지-only | HTML 안의 이미지와 글의 순서를 지원하는 문서 의미로 변환; 읽을 수 없는 이미지는 전체 실패 | Web·Rich Text Web·각 문서 모델 |
 | 서식 없이 붙여넣기 | 명시적인 공통 입력 계약 TBD | 서식 붙여넣기와 plain text 선택을 구별하고 native 입력을 침범하지 않음 | Web·Affordance·각 Hand |
 | 이미지로 복사 | Canvas TBD | 선택한 글·도형·이미지를 PNG로 복사해 외부 앱에 붙임; 실패가 문서를 바꾸지 않음 | Canvas·Web |
 | 실제 플랫폼 왕복 | OS-native 검증 TBD | 스크린샷·브라우저 이미지·Docs/Slides에서 실제 복사하여 붙이고, 외부 앱으로 다시 전달 | Web·제품 경로 검증 |
@@ -72,6 +72,20 @@ Clipboard의 기본기는 다른 앱에서 가져온 내용을 편집 가능한
 이 구분을 설명합니다. [Docs·Slides의 이미지 복사](https://support.google.com/docs/answer/161768?hl=en)도
 외부 앱에는 HTML로 전달되므로 HTML 이미지를 고급 문서 import만의 문제로 보지 않습니다.
 
+현재 Canvas는 구조화 Object → native 이미지 파일 → 이미지가 포함된 HTML → 일반 텍스트
+순으로 표현을 고릅니다. 선택한 HTML의 글과 PNG/JPEG/WebP data URL은 입력 순서의
+편집 가능한 객체가 되며 한 번에 Undo합니다. 배치는 간격을 둔 세로 흐름이며 넘치는 높이를
+함께 축소합니다. HTML 서식·원래 CSS 배치는 재현하지 않습니다.
+
+Composer는 내부 Rich Text 구조화 MIME을 먼저 기존 binding에 위임합니다. 그 외 파일과
+이미지-only HTML은 실제 첨부로 준비하고, 이미지가 없는 HTML은 기존 Rich Text로 처리합니다.
+글+이미지 HTML은 inline 의미를 표현할 수 없어 draft를 바꾸지 않고 미지원 오류를 알립니다.
+
+HTML 이미지의 외부·상대·blob·cid URL, 비어 있거나 깨진 source는 일부 내용만 남기는 대신
+전체 입력을 거절합니다. 임의 다운로드는 하지 않습니다. native 파일과 HTML이 함께 있을 때는
+파일 표현이 우선하며, 둘의 대응과 혼합 의미 보존은 TBD입니다. 이 지원 범위는 브라우저·
+Docs/Slides의 실제 복사 입력을 모두 지원한다는 뜻이 아닙니다.
+
 Canvas는 평면 객체, Composer는 instruction과 첨부 목록을 결과로 만듭니다.
 같은 입력을 받아도 Canvas 좌표를 Composer에 넣거나, 첨부 목록을 Rich Text의
 inline 이미지처럼 설명하지 않습니다. 서버 업로드, 임의 외부 URL의 가져오기,
diff --git a/docs/public/composer.md b/docs/public/composer.md
index 5f1d3ce6..30060898 100644
--- a/docs/public/composer.md
+++ b/docs/public/composer.md
@@ -86,7 +86,12 @@ Composer가 소유하지 않습니다.
 
 ## 이미지와 Clipboard의 남은 기본기
 
-[Paste × Image TBD](clipboard.md#paste--image-기본기--tbd)에 HTML 이미지·혼합 입력,
+이미지-only HTML은 Web의 inert parser와 준비 API를 통해 포함된 PNG/JPEG/WebP를
+실제 첨부로 읽습니다. 내부 Rich Text 구조화 복사는 기존 binding에 우선 위임하며,
+파일이 함께 있으면 파일 표현만 처리합니다. 글+이미지 HTML은 일부 내용을 버리는 대신
+전체를 미지원 오류로 알립니다. 외부·상대·blob·cid 이미지 주소는 다운로드하지 않습니다.
+
+[Paste × Image TBD](clipboard.md#paste--image-기본기--tbd)에 HTML의 남은 source·혼합 입력,
 명시적인 plain paste, 이미지로 복사와 OS-native round-trip의 소유자·기대 결과를
 미리 공개합니다. 현재 Composer 이미지 slice는 별도 첨부 목록에 내용을 보존하는
 단계이며 inline 혼합 입력을 구현한 것은 아닙니다. 서버 업로드와 자산 저장소는
diff --git a/package-lock.json b/package-lock.json
index 9feea7c2..71e22a83 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -7118,6 +7118,7 @@
         "@interactive-os/json-document-file-intake": "*",
         "@interactive-os/json-document-selection": "*",
         "@types/node": "^25.9.0",
+        "jsdom": "^29.1.1",
         "typescript": "^5.0.0",
         "vitest": "^4.1.7"
       },
diff --git a/packages/json-document-canvas/README.md b/packages/json-document-canvas/README.md
index 060f9d37..bb780a3b 100644
--- a/packages/json-document-canvas/README.md
+++ b/packages/json-document-canvas/README.md
@@ -5,7 +5,8 @@
 selection/history 구현을 만들지 않고 기존 `createObjectEditor`를 사용합니다.
 재사용 가능한 Plane Select profile로 다중 선택·Alt 복제·Shift 축 고정·방향키 이동을,
 Object Editing과 Web Clipboard로 선택 copy/cut/paste·Mod+D·Undo/Redo를 연결합니다.
-외부 텍스트와 PNG/JPEG/WebP 붙여넣기, 반복 paste 배치와 비동기 취소도 정본 API를 사용합니다.
+외부 텍스트와 PNG/JPEG/WebP 붙여넣기, 포함된 이미지·글의 HTML 순서 보존,
+반복 paste 배치와 비동기 취소도 정본 API를 사용합니다. 외부 이미지 URL은 가져오지 않습니다.
 
 ```tsx
 import { useState } from "react";
diff --git a/packages/json-document-canvas/docs/api.md b/packages/json-document-canvas/docs/api.md
index c34432e8..d06fdce0 100644
--- a/packages/json-document-canvas/docs/api.md
+++ b/packages/json-document-canvas/docs/api.md
@@ -69,14 +69,21 @@ cut은 쓰기에 성공한 캡처 대상만 제거합니다. 쓰기 실패나 Ed
 text/JSON textarea의 native clipboard는 가로채지 않습니다.
 
 `createCanvasClipboardBinding(editor, policy, options?)`가 이 연결의 공개 API입니다.
-구조화 Object → 이미지 파일 → 일반 텍스트 순서로 처리하며 잘못된 Object MIME은 문자열로
-조용히 변환하지 않습니다. 외부 문자열은 한 text 객체가 되며 HTML을 실행/보존하지 않고
+구조화 Object → 이미지 파일 → 이미지가 포함된 HTML → 일반 텍스트 순서로 처리하며 잘못된 Object MIME은 문자열로
+조용히 변환하지 않습니다. 외부 문자열은 한 text 객체가 되며 HTML 서식을 보존하지 않고
 줄바꿈·Unicode를 그대로 보존합니다. PNG/JPEG/WebP는 문서 내부 base64 image 객체로 넣습니다.
 기본은 한 paste당 최대 4개, 파일당 10 MiB, decode 후 이미지당 16,000,000픽셀입니다.
 이미지는 비율을 유지해 슬라이드 75% 상자에 맞추고 확대하지 않습니다. 후속 resize는 일반
 객체와 같은 자유 상자 변환입니다. `policy.files`와 `maxImagePixels`로 입력 정책을 지정할 수
 있지만 Object 모델이 지원하지 않는 이미지 표현까지 허용되는 것은 아닙니다.
 
+HTML은 Web의 inert parser와 이미지 준비 API를 사용합니다. 포함된 PNG/JPEG/WebP data URL과
+글을 HTML 내부 순서대로 text/image 객체로 바꿉니다. Editing의 `createCanvasClipboard`가
+간격을 둔 세로 흐름으로 배치하고, 전체 높이가 넘으면 이미지 비율·글자 크기·간격을 함께
+줄여 상자 안에 맞춥니다. 긴 내용을 원래 글자 크기로 읽거나 CSS·Office 배치를 재현하는
+기능은 아닙니다. source가 없거나 외부·상대·blob·cid URL이면 글만 남기지 않고 전체를 거절합니다.
+HTML과 native 파일이 함께 있으면 파일을 우선하고, 두 표현을 합치거나 중복 삽입하지 않습니다.
+
 같은 batch는 순차 decode로 준비하고 모두 성공한 경우만 한 번 삽입합니다. 연속 paste는
 Editing paste session을 통해 입력 순서대로 각각 commit/Undo를 만듭니다. 진행 상태를 표시하고
 Escape·다른 도구/편집·외부 문서/선택·unmount는 준비를 취소합니다. 늦은 완료는 문서를 바꾸거나
@@ -84,7 +91,7 @@ Escape·다른 도구/편집·외부 문서/선택·unmount는 준비를 취소
 `readRaster`에는 Web API와 호환되는 구체 환경 인스턴스를 주입할 수 있습니다.
 
 이미지도 기존 다중 선택·이동·복제·copy/cut/paste·삭제·Undo/Redo와 JSON 재열기를 사용합니다.
-이미지용 별도 생성 도구, 외부 URL/SVG/HTML import, 이미지 파일 export, asset 서버,
+이미지용 별도 생성 도구, 외부 URL/SVG·전체 HTML layout import, 이미지 파일 export, asset 서버,
 async clipboard 툴바는 아직 지원하지 않습니다. 표준 MIME이 없는 입력이나 실패는 오류로 드러냅니다.
 
 ### JSON
diff --git a/packages/json-document-canvas/src/canvas-clipboard.ts b/packages/json-document-canvas/src/canvas-clipboard.ts
index 63b33b34..2f8457d8 100644
--- a/packages/json-document-canvas/src/canvas-clipboard.ts
+++ b/packages/json-document-canvas/src/canvas-clipboard.ts
@@ -1,7 +1,7 @@
 import { createCanvasClipboard, createObjectPasteSession, type CanvasClipboardOptions, type EditingResult, type ObjectEditor, type ObjectPastePreparation, type ObjectSelection } from "@interactive-os/json-document-editing";
 import type { FileAcceptancePolicy } from "@interactive-os/json-document-file-intake";
 import { assertCanvasDocument } from "@interactive-os/json-document-object-document";
-import { captureWebClipboardPaste, createWebClipboardBinding, objectClipboardCodec, readWebRasterFile, readWebRasterFiles, type WebClipboardEvent, type WebFileCandidate } from "@interactive-os/json-document-web";
+import { captureWebClipboardPaste, createWebClipboardBinding, objectClipboardCodec, readWebHTMLClipboard, readWebRasterFile, readWebRasterFiles, type WebClipboardEvent, type WebFileCandidate, type WebHTMLClipboardContent } from "@interactive-os/json-document-web";
 
 export interface CanvasClipboardPolicy {
   readonly textColor: string;
@@ -39,6 +39,10 @@ export function createCanvasClipboardBinding(editor: ObjectEditor, policy: Canva
       ? { ok: true, clipboard: createCanvasClipboard({ type: "images", images: prepared.files.map(({ candidate, image }) => ({ ...image, label: candidate.name })) }, content) }
       : prepared;
   }
+  async function html(input: WebHTMLClipboardContent, content: CanvasClipboardOptions, signal: AbortSignal): Promise<ObjectPastePreparation> {
+    const prepared = await readWebHTMLClipboard(input, { policy: files, maxImagePixels: maxPixels, signal, readRaster: options.readRaster ?? readWebRasterFile });
+    return prepared.ok ? { ok: true, clipboard: createCanvasClipboard({ type: "mixed", items: prepared.parts.map((part) => part.type === "text" ? part : { type: "image", ...part.image, label: part.candidate.name }) }, content) } : prepared;
+  }
   return {
     get pending() { return session.pending; },
     cancel: () => session.cancel(),
@@ -51,12 +55,13 @@ export function createCanvasClipboardBinding(editor: ObjectEditor, policy: Canva
       const result = native.cut(event); options.onResult?.(result); return result;
     },
     paste(event: WebClipboardEvent): Promise<EditingResult<ObjectSelection>> {
-      const captured = captureWebClipboardPaste(event, { codec: objectClipboardCodec, files: true, text: true });
+      const captured = captureWebClipboardPaste(event, { codec: objectClipboardCodec, files: true, html: "images", text: true });
       const controller = new AbortController();
       return session.enqueue(() => {
         if (!captured.ok) return captured;
         if (captured.type === "structured") return { ok: true, clipboard: captured.payload };
         const content = contentOptions();
+        if (captured.type === "html") return html(captured.content, content, controller.signal);
         return captured.type === "text"
           ? { ok: true, clipboard: createCanvasClipboard({ type: "text", text: captured.text }, content) }
           : images(captured.files, content, controller.signal);
diff --git a/packages/json-document-canvas/tests/canvas-clipboard.test.ts b/packages/json-document-canvas/tests/canvas-clipboard.test.ts
index 2f2627f7..6d96531f 100644
--- a/packages/json-document-canvas/tests/canvas-clipboard.test.ts
+++ b/packages/json-document-canvas/tests/canvas-clipboard.test.ts
@@ -84,3 +84,49 @@ test("cancellation aborts platform preparation; later resolution cannot commit o
   resolve({ ok: true, dataURL: png, width: 100, height: 100 }); await Promise.resolve();
   expect(value()).toEqual(blank); expect(onResult).not.toHaveBeenCalled();
 });
+
+test("HTML mixed paste preserves order and content in one commit, copy, JSON round-trip and Undo", async () => {
+  const { binding, editor, value, commits } = setup();
+  const input = event([], { "text/html": `<p>Before<img src="${png}" alt="Figure">After</p>`, "text/plain": "Must not also paste" });
+  expect((await binding.paste(input)).ok).toBe(true);
+  expect(input.preventDefault).toHaveBeenCalledOnce(); expect(commits).toHaveBeenCalledOnce();
+  expect(value().objects.map((object) => [object.kind, object.label])).toEqual([["text", "Before"], ["image", "Figure"], ["text", "After"]]);
+  expect(value().objects[0]!.y + value().objects[0]!.height).toBeLessThan(value().objects[1]!.y);
+  expect(value().objects[1]!.y + value().objects[1]!.height).toBeLessThan(value().objects[2]!.y);
+  expect(value().objects.at(-1)!.y + value().objects.at(-1)!.height).toBeLessThanOrEqual(565);
+  expect(value().objects[1]!.source).toBe(png);
+  expect(parseCanvasDocument(serializeCanvasDocument(value()))).toEqual(value());
+  const copied = event(); binding.copy(copied);
+  editor.undo(); expect(value()).toEqual(blank);
+  await binding.paste(copied);
+  expect(value().objects.map((object) => object.id)).toEqual(["image-4", "image-5", "image-6"]);
+  expect(value().objects[1]!.source).toBe(png);
+});
+
+test("unavailable HTML images reject the whole paste without text fallback or consumed IDs", async () => {
+  const { binding, value, editor, readRaster } = setup();
+  expect(await binding.paste(event([], { "text/html": '<p>Before<img src="https://example.invalid/image">After</p>', "text/plain": "Fallback" }))).toMatchObject({ ok: false, code: "raster.source-unsupported" });
+  expect(value()).toEqual(blank); expect(editor.snapshot.canUndo).toBe(false); expect(readRaster).not.toHaveBeenCalled();
+  await binding.paste(event([], { "text/plain": "After failure" })); expect(value().objects[0]!.id).toBe("image-1");
+});
+
+test("HTML and subsequent text requests share ordered adoption", async () => {
+  let resolve!: (value: WebRasterSourceResult) => void;
+  const { binding, value } = setup(() => new Promise((done) => { resolve = done; }));
+  const first = binding.paste(event([], { "text/html": `<p>Before<img src="${png}" alt="Figure">After</p>` }));
+  const next = binding.paste(event([], { "text/plain": "Next paste" }));
+  expect(value()).toEqual(blank);
+  resolve({ ok: true, dataURL: png, width: 100, height: 50 }); await Promise.all([first, next]);
+  expect(value().objects.map((object) => object.label)).toEqual(["Before", "Figure", "After", "Next paste"]);
+});
+
+test("cancelled HTML preparation cannot revive a late image or its surrounding text", async () => {
+  let resolve!: (value: WebRasterSourceResult) => void;
+  const readRaster = vi.fn<typeof readWebRasterFile>(() => new Promise((done) => { resolve = done; }));
+  const { binding, value } = setup(readRaster);
+  const pending = binding.paste(event([], { "text/html": `<p>Before<img src="${png}">After</p>` }));
+  binding.cancel(); expect(await pending).toMatchObject({ code: "clipboard.cancelled" });
+  expect(readRaster.mock.calls[0]?.[1]?.signal?.aborted).toBe(true);
+  resolve({ ok: true, dataURL: png, width: 100, height: 50 }); await Promise.resolve();
+  expect(value()).toEqual(blank);
+});
diff --git a/packages/json-document-composer-react/README.md b/packages/json-document-composer-react/README.md
index 4ed2d53a..8927865a 100644
--- a/packages/json-document-composer-react/README.md
+++ b/packages/json-document-composer-react/README.md
@@ -50,9 +50,16 @@ Escape, `cancelAttachments`, `handleHistoryKeyDown`의 Undo/Redo, unmount는 준
 React Host는 `handlePaste`와 `handleHistoryKeyDown`을 감싸는 surface의 capture handler에,
 `handleKeyDown`은 editor에 연결하고 상태/실패를 표시합니다.
 
-파일이 있는 paste는 Web에서 동기 캡처하고 한 번만 처리합니다. 파일이 없는 텍스트/HTML은
-기존 Rich Text 경로에 위임합니다. HTML 이미지·글+이미지 변환은 아직 TBD이며,
-파일과 HTML 양쪽의 내용을 모두 별개로 추가하지 않습니다.
+내부 Rich Text 구조화 MIME은 기존 binding에 먼저 위임합니다. 나머지는 파일 → 이미지가
+포함된 HTML 순으로 Web에서 동기 캡처하고 한 번만 처리합니다. 이미지가 없는 텍스트/HTML은
+기존 Rich Text 경로에 남깁니다. 이미지-only HTML은 `readWebHTMLClipboard`로 포함된
+PNG/JPEG/WebP data URL을 읽고 기존 첨부와 같은 queue·정책·취소·History를 사용합니다.
+외부·상대·blob·cid source는 가져오지 않고 `raster.source-unsupported`로 실패합니다.
+
+글+이미지 HTML은 inline 위치를 표현할 모델이 아직 없으므로
+`composer.clipboard.mixed-unsupported`로 전체를 거절하고 draft/History를 유지합니다.
+파일과 HTML 양쪽의 내용을 별개로 추가하거나 대응을 추측하지 않습니다. native 파일과
+HTML의 혼합 의미 보존 및 inline 이미지 profile은 TBD입니다.
 
 Usage와 Source: [Composer](/demo/composer). PNG/JPEG/WebP의 내용·미리보기·삭제·Undo/Redo와
 submit payload를 확인할 수 있습니다. 서버 upload와 OS-native Clipboard 호환성 완료를
diff --git a/packages/json-document-composer-react/src/attachments.ts b/packages/json-document-composer-react/src/attachments.ts
index cb709333..95b80986 100644
--- a/packages/json-document-composer-react/src/attachments.ts
+++ b/packages/json-document-composer-react/src/attachments.ts
@@ -3,7 +3,7 @@ import { addComposerAttachments, createComposerAttachments, type ComposerAttachm
 import { createEditingPreparationQueue, type EditingPreparation, type EditingPreparationFailure } from "@interactive-os/json-document-editing";
 import { validateFileCandidates } from "@interactive-os/json-document-file-intake";
 import type { RichTextEditor } from "@interactive-os/json-document-rich-text";
-import { fileCandidatesFromWebFiles, readWebRasterFiles, type readWebRasterFile, type WebFileCandidate, type WebFileCandidateList } from "@interactive-os/json-document-web";
+import { fileCandidatesFromWebFiles, readWebHTMLClipboard, readWebRasterFiles, type readWebRasterFile, type WebFileCandidate, type WebFileCandidateList, type WebHTMLClipboardContent } from "@interactive-os/json-document-web";
 import { useEffect, useRef, useState } from "react";
 
 /** Composer appends attachments, so typing and caret changes do not invalidate preparation. */
@@ -28,30 +28,45 @@ export function useComposerAttachments(document: JSONDocument, editor: RichTextE
   }));
   useEffect(() => () => queue.cancel(), [queue]);
 
+  function enqueue(prepare: (signal: AbortSignal) => EditingPreparation<ReadonlyArray<ComposerAttachmentCandidate>> | Promise<EditingPreparation<ReadonlyArray<ComposerAttachmentCandidate>>>) {
+    setError(null);
+    const controller = new AbortController();
+    void queue.enqueue(() => prepare(controller.signal), () => controller.abort());
+  }
+
   function addFiles(input: WebFileCandidateList | ReadonlyArray<WebFileCandidate>) {
     // Snapshot File references while a paste/drop event still owns them.
     const files = Array.from(input as ArrayLike<WebFileCandidate>);
     if (files.length === 0) return;
-    setError(null);
-    const controller = new AbortController();
     const policy = current.current.policy;
     const maxImagePixels = current.current.maxImagePixels ?? 16_000_000;
     const readRaster = current.current.readRaster;
-    void queue.enqueue(() => {
+    enqueue((signal) => {
       const candidates = fileCandidatesFromWebFiles(files);
       const accepted = validateFileCandidates(candidates, policy, { currentCount: (document.value as ComposerDraft).attachments.length });
       if (!accepted.ok) return accepted;
       const images = files.filter((file) => file.type.startsWith("image/"));
       if (images.length === 0) return { ok: true, value: candidates };
-      return readWebRasterFiles(images, { policy, maxImagePixels, signal: controller.signal, ...(readRaster ? { readRaster } : {}) }).then((prepared): EditingPreparation<ReadonlyArray<ComposerAttachmentCandidate>> => {
+      return readWebRasterFiles(images, { policy, maxImagePixels, signal, ...(readRaster ? { readRaster } : {}) }).then((prepared): EditingPreparation<ReadonlyArray<ComposerAttachmentCandidate>> => {
         if (!prepared.ok) return prepared;
         let imageIndex = 0;
         return { ok: true, value: candidates.map((candidate) => candidate.mediaType?.startsWith("image/")
           ? { ...candidate, image: prepared.files[imageIndex++]!.image }
           : candidate) };
       });
-    }, () => controller.abort());
+    });
+  }
+
+  function addHTML(content: WebHTMLClipboardContent) {
+    const { policy, maxImagePixels = 16_000_000, readRaster } = current.current;
+    enqueue((signal) => {
+      if (content.parts.some((part) => part.type === "text" && part.text.trim())) return { ok: false, code: "composer.clipboard.mixed-unsupported" };
+      return readWebHTMLClipboard(content, { policy, maxImagePixels, signal, currentCount: (document.value as ComposerDraft).attachments.length, ...(readRaster ? { readRaster } : {}) })
+        .then((prepared): EditingPreparation<ReadonlyArray<ComposerAttachmentCandidate>> => prepared.ok
+          ? { ok: true, value: prepared.parts.flatMap((part) => part.type === "image" ? [{ ...part.candidate, image: part.image }] : []) }
+          : prepared);
+    });
   }
 
-  return { isPending, error, addFiles, reportError: setError, cancel: () => { queue.cancel(); setError(null); }, hasPending: () => queue.isPending };
+  return { isPending, error, addFiles, addHTML, reportError: setError, cancel: () => { queue.cancel(); setError(null); }, hasPending: () => queue.isPending };
 }
diff --git a/packages/json-document-composer-react/src/use-composer.tsx b/packages/json-document-composer-react/src/use-composer.tsx
index 71904739..388f7ee8 100644
--- a/packages/json-document-composer-react/src/use-composer.tsx
+++ b/packages/json-document-composer-react/src/use-composer.tsx
@@ -12,7 +12,7 @@ import {
   type ComposerHostPorts,
   type ComposerHostSuggestion,
 } from "@interactive-os/json-document-composer";
-import { createRichTextEditor, type RichTextEditor, type RichTextNode } from "@interactive-os/json-document-rich-text";
+import { createRichTextEditor, RICH_TEXT_CLIPBOARD_MIME, type RichTextEditor, type RichTextNode } from "@interactive-os/json-document-rich-text";
 import type { RichTextSuggestionCandidate } from "@interactive-os/json-document-rich-text-suggestion";
 import type { RichTextSuggestionBinding } from "@interactive-os/json-document-rich-text-suggestion-react";
 import { captureWebClipboardPaste, type readWebRasterFile, type WebFileCandidate, type WebFileCandidateList } from "@interactive-os/json-document-web";
@@ -104,10 +104,13 @@ export function useComposer<Model extends string, Suggestion extends ComposerHos
 
   function handlePaste(event: ClipboardEvent<HTMLElement>) {
     if (event.defaultPrevented) return;
-    const captured = captureWebClipboardPaste(event, { files: true });
+    const captured = captureWebClipboardPaste(event, { files: true, html: "images", delegatedMimeTypes: [RICH_TEXT_CLIPBOARD_MIME] });
     if (captured.ok && captured.type === "files") {
       event.stopPropagation();
       addWebFiles(captured.files);
+    } else if (captured.ok && captured.type === "html") {
+      event.stopPropagation();
+      intake.addHTML(captured.content);
     } else if (!captured.ok && captured.code !== "clipboard.empty") intake.reportError(captured);
   }
 
diff --git a/packages/json-document-composer-react/tests/composer-attachments.test.tsx b/packages/json-document-composer-react/tests/composer-attachments.test.tsx
index e67d7528..7b612842 100644
--- a/packages/json-document-composer-react/tests/composer-attachments.test.tsx
+++ b/packages/json-document-composer-react/tests/composer-attachments.test.tsx
@@ -4,6 +4,7 @@ import { COMPOSER_HOST_PROFILE_V1, composerText, type ComposerHostConfig } from
 import type { readWebRasterFile, WebRasterSourceResult } from "@interactive-os/json-document-web";
 import { useComposer } from "../src/index.js";
 import type { ClipboardEvent, KeyboardEvent } from "react";
+import { RICH_TEXT_CLIPBOARD_MIME } from "@interactive-os/json-document-rich-text";
 
 afterEach(cleanup);
 const file = { name: "image.png", size: 3, type: "image/png" };
@@ -27,6 +28,11 @@ function key(key: string, metaKey = false) {
   return { key, metaKey, preventDefault: vi.fn(), stopPropagation: vi.fn(), nativeEvent: { isComposing: false, stopImmediatePropagation: vi.fn() } } as unknown as KeyboardEvent<HTMLElement>;
 }
 
+function htmlEvent(html: string) {
+  const preventDefault = vi.fn(), stopPropagation = vi.fn();
+  return { clipboardData: { files: [], types: ["text/html", "text/plain"], getData: (type: string) => type === "text/html" ? html : "Fallback", setData() {} }, preventDefault, stopPropagation } as unknown as ClipboardEvent<HTMLElement>;
+}
+
 test("PI-CONTENT: decoded images survive draft serialization, submit, removal, and Undo/Redo", async () => {
   const { result, submit } = setup();
   await act(async () => { result.current.addWebFiles([file]); });
@@ -108,3 +114,62 @@ test("file-only native paste consumes images once and delegates text/HTML to Ric
   await act(async () => { result.current.handlePaste(event([file], ["Files", "text/html"])); });
   expect(result.current.attachments).toHaveLength(1); expect(preventDefault).toHaveBeenCalledOnce(); expect(stopPropagation).toHaveBeenCalledOnce();
 });
+
+test("HTML image-only input shares actual attachment content, History and submit", async () => {
+  const { result, submit } = setup();
+  const input = htmlEvent(`<p><img src="${image.dataURL}" alt="HTML image"></p>`);
+  await act(async () => { result.current.handlePaste(input); });
+  expect(input.preventDefault).toHaveBeenCalledOnce(); expect(input.stopPropagation).toHaveBeenCalledOnce();
+  expect(result.current.attachments[0]).toMatchObject({ name: "HTML image", size: 3, image: { source: image.dataURL, width: 100, height: 50 } });
+  expect(composerText(result.current.draft.instruction)).toBe("");
+  act(() => { result.current.submit(); }); expect(submit).toHaveBeenCalledWith(result.current.draft);
+  act(() => { result.current.handleHistoryKeyDown(key("z", true)); }); expect(result.current.attachments).toEqual([]);
+});
+
+test("Composer leaves structured Rich Text to its original binding before considering HTML", () => {
+  const { result, readRaster } = setup();
+  const input = htmlEvent(`<img src="${image.dataURL}">`);
+  Object.defineProperty(input.clipboardData, "types", { value: [RICH_TEXT_CLIPBOARD_MIME, "text/html"] });
+  act(() => { result.current.handlePaste(input); });
+  expect(input.preventDefault).not.toHaveBeenCalled(); expect(input.stopPropagation).not.toHaveBeenCalled();
+  expect(result.current.attachments).toEqual([]); expect(readRaster).not.toHaveBeenCalled();
+});
+
+test("unsupported HTML mixed content stays an owned atomic failure without dropping text", async () => {
+  const { result, readRaster } = setup();
+  act(() => { result.current.insertText("Existing draft"); });
+  const before = result.current.draft, revision = result.current.editor.snapshot.revision;
+  const input = htmlEvent(`<p>Before<img src="${image.dataURL}">After</p>`);
+  await act(async () => { result.current.handlePaste(input); });
+  expect(input.preventDefault).toHaveBeenCalledOnce(); expect(input.stopPropagation).toHaveBeenCalledOnce();
+  expect(result.current.attachmentError?.code).toBe("composer.clipboard.mixed-unsupported");
+  expect(result.current.draft).toEqual(before); expect(result.current.editor.snapshot.revision).toBe(revision);
+  expect(readRaster).not.toHaveBeenCalled();
+});
+
+test("HTML and file inputs use the same queue even when later preparation finishes first", async () => {
+  const first = waiting(), second = waiting();
+  const readRaster = vi.fn<typeof readWebRasterFile>().mockImplementationOnce(() => first.promise).mockImplementationOnce(() => second.promise);
+  const { result } = setup(readRaster);
+  act(() => { result.current.handlePaste(htmlEvent(`<img src="${image.dataURL}" alt="First HTML">`)); result.current.addWebFiles([file]); result.current.insertText("Typing"); });
+  await act(async () => { second.resolve(image); }); expect(result.current.attachments).toEqual([]);
+  await act(async () => { first.resolve(image); });
+  expect(result.current.attachments.map((attachment) => attachment.name)).toEqual(["First HTML", file.name]);
+  expect(composerText(result.current.draft.instruction)).toBe("Typing");
+});
+
+test("HTML observes the current attachment limit before decoding", async () => {
+  const { result, readRaster } = setup();
+  act(() => { result.current.addWebFiles(Array.from({ length: 4 }, (_, index) => ({ name: `note-${index}`, size: 1, type: "text/plain" }))); });
+  await act(async () => { result.current.handlePaste(htmlEvent(`<img src="${image.dataURL}">`)); });
+  expect(result.current.attachmentError?.code).toBe("file-intake.limit"); expect(result.current.attachments).toHaveLength(4);
+  expect(readRaster).not.toHaveBeenCalled();
+});
+
+test("HTML cancellation aborts its reader and ignores later completion", async () => {
+  const pending = waiting(), readRaster = vi.fn<typeof readWebRasterFile>(() => pending.promise);
+  const { result } = setup(readRaster);
+  act(() => { result.current.handlePaste(htmlEvent(`<img src="${image.dataURL}">`)); result.current.cancelAttachments(); });
+  expect(readRaster.mock.calls[0]?.[1]?.signal?.aborted).toBe(true);
+  await act(async () => { pending.resolve(image); }); expect(result.current.attachments).toEqual([]);
+});
diff --git a/packages/json-document-editing/README.md b/packages/json-document-editing/README.md
index f3e66bec..7c288fd9 100644
--- a/packages/json-document-editing/README.md
+++ b/packages/json-document-editing/README.md
@@ -89,6 +89,24 @@ queue는 문서·selection을 모르며 원자적 편집은 `apply`가 호출하
 각 요청의 History 단위도 실제 domain apply가 정합니다.
 Usage·Source: [Canvas](/demo/canvas), [Composer](/demo/composer).
 
+## Canvas 외부 내용 변환
+
+`createCanvasClipboard(content, { bounds, textColor, fontSize, imageOffset?, contentGap? })`는
+일반 텍스트, 이미지 목록, 순서 있는 글·이미지를 Object clipboard로 변환합니다.
+`{ type: "mixed", items: CanvasClipboardItem[] }`의 item은 `{ type: "text", text }` 또는
+`{ type: "image", source, width, height, label }`입니다. HTML parsing·이미지 decode는
+Web 소유이며 이 API는 DOM이나 File을 받지 않습니다.
+
+mixed는 입력 순서의 세로 흐름으로 배치합니다. `contentGap`의 기본값은 24이며 유한한
+0 이상 값입니다. 전체 높이가 `bounds.height`를 넘으면 객체·글자 크기·간격을 같은 비율로
+축소합니다. 이미지 비율은 유지하며 원본 CSS·Office layout이나 긴 글의 가독성을 보장하지
+않습니다. 기존 text는 단일 객체, images는 `imageOffset`(기본 24)의 cascade를 유지합니다.
+빈 입력·유효하지 않은 geometry는 예외로 거절합니다.
+
+결과의 ID는 clipboard 내부 참조입니다. 실제 문서 ID 할당·선택·History는 Object paste가
+소유하고 마지막 item이 primary가 됩니다. 변환 자체는 문서를 쓰지 않습니다.
+Usage·Source: [Canvas](/demo/canvas).
+
 ## Editing identity and observation
 
 `createEditingId(prefix)` supplies opaque UUID-based identities for Document,
diff --git a/packages/json-document-editing/src/canvas-clipboard.ts b/packages/json-document-editing/src/canvas-clipboard.ts
index 39756af9..a6ac3bac 100644
--- a/packages/json-document-editing/src/canvas-clipboard.ts
+++ b/packages/json-document-editing/src/canvas-clipboard.ts
@@ -1,15 +1,20 @@
-import { createCanvasImage, createCanvasObject, type ObjectBounds } from "@interactive-os/json-document-object-document";
+import { createCanvasImage, createCanvasObject, type CanvasObjectDraft, type ObjectBounds } from "@interactive-os/json-document-object-document";
 import { objectClipboardFormat, type ObjectClipboard } from "./object.js";
 
 export type CanvasClipboardContent =
   | { readonly type: "text"; readonly text: string }
-  | { readonly type: "images"; readonly images: ReadonlyArray<{ readonly source: string; readonly width: number; readonly height: number; readonly label: string }> };
+  | { readonly type: "images"; readonly images: ReadonlyArray<{ readonly source: string; readonly width: number; readonly height: number; readonly label: string }> }
+  | { readonly type: "mixed"; readonly items: ReadonlyArray<CanvasClipboardItem> };
+
+export type CanvasClipboardItem = { readonly type: "text"; readonly text: string }
+  | ({ readonly type: "image" } & Parameters<typeof createCanvasImage>[0]);
 
 export interface CanvasClipboardOptions {
   readonly bounds: ObjectBounds;
   readonly textColor: string;
   readonly fontSize: number;
   readonly imageOffset?: number;
+  readonly contentGap?: number;
 }
 
 /** External content → domain clipboard. No platform objects, document IDs, or history writes. */
@@ -18,12 +23,35 @@ export function createCanvasClipboard(content: CanvasClipboardContent, options:
   const offset = options.imageOffset ?? 24;
   if (![bounds.x, bounds.y, offset].every(Number.isFinite)
     || ![bounds.width, bounds.height, options.fontSize].every((value) => Number.isFinite(value) && value > 0)) throw new TypeError("Canvas clipboard geometry and font size must be valid.");
-  if ((content.type === "text" && content.text.length === 0) || (content.type === "images" && content.images.length === 0)) throw new TypeError("Canvas clipboard must not be empty.");
-  const drafts = content.type === "text"
-    ? [createCanvasObject("text", { ...bounds, height: Math.min(bounds.height, Math.max(1, content.text.split("\n").length) * options.fontSize * 1.2) }, { color: options.textColor, fontSize: options.fontSize, label: content.text })]
+  if ((content.type === "text" && content.text.length === 0) || (content.type === "images" && content.images.length === 0)
+    || (content.type === "mixed" && content.items.length === 0)) throw new TypeError("Canvas clipboard must not be empty.");
+  const drafts = content.type === "mixed" ? mixedObjects(content.items, options)
+    : content.type === "text" ? [textObject(content.text, options)]
     : content.images.map((image, index) => createCanvasImage(image, { ...bounds, x: bounds.x + index * offset, y: bounds.y + index * offset }));
   const objects = drafts.map((object, index) => ({ ...object, id: `clipboard:${index}` }));
   const payload: ObjectClipboard = { type: objectClipboardFormat.mimeType, objects, text: objects.map((object) => object.label).join("\n"), primaryKey: objects.at(-1)!.id };
   if (!objectClipboardFormat.parse(payload)) throw new TypeError("Invalid Canvas clipboard content.");
   return payload;
 }
+
+function textObject(text: string, options: CanvasClipboardOptions): CanvasObjectDraft {
+  if (text.length === 0) throw new TypeError("Canvas clipboard text must not be empty.");
+  return createCanvasObject("text", { ...options.bounds, height: Math.min(options.bounds.height, Math.max(1, text.split("\n").length) * options.fontSize * 1.2) }, { color: options.textColor, fontSize: options.fontSize, label: text });
+}
+
+/** Flow order is domain geometry, not a reconstruction of the source page's CSS. */
+function mixedObjects(items: ReadonlyArray<CanvasClipboardItem>, options: CanvasClipboardOptions): CanvasObjectDraft[] {
+  const gap = options.contentGap ?? 24;
+  if (!Number.isFinite(gap) || gap < 0) throw new TypeError("Canvas content gap must be finite and nonnegative.");
+  let height = 0;
+  const drafts = items.map((item) => {
+    const object = item.type === "text" ? textObject(item.text, options) : createCanvasImage(item, options.bounds);
+    const positioned = { ...object, y: height };
+    height += object.height + gap;
+    return positioned;
+  });
+  const scale = Math.min(1, options.bounds.height / (height - gap));
+  return drafts.map((object) => ({ ...object, x: options.bounds.x, y: options.bounds.y + object.y * scale, width: object.width * scale, height: object.height * scale,
+    ...(object.kind === "text" ? { fontSize: object.fontSize * scale } : {}),
+  }));
+}
diff --git a/packages/json-document-editing/src/index.ts b/packages/json-document-editing/src/index.ts
index fc7e3a45..d8975aeb 100644
--- a/packages/json-document-editing/src/index.ts
+++ b/packages/json-document-editing/src/index.ts
@@ -28,7 +28,7 @@ export type { GridPoint, GridRangeBounds, GridTopology, LineTopology } from "./t
 export { createDatabaseEditor, databaseClipboardFormat, nextDatabasePropertySort } from "./database.js";
 export { acceptsDatabaseValue, databaseValueFromText, defaultDatabaseValue } from "./database-property-value.js";
 export { createObjectEditor, objectClipboardFormat } from "./object.js";
-export { createCanvasClipboard, type CanvasClipboardContent, type CanvasClipboardOptions } from "./canvas-clipboard.js";
+export { createCanvasClipboard, type CanvasClipboardContent, type CanvasClipboardItem, type CanvasClipboardOptions } from "./canvas-clipboard.js";
 export { createObjectPasteSession, type ObjectPasteSession, type ObjectPastePreparation } from "./object-paste-session.js";
 export { createEditingPreparationQueue, type EditingPreparationQueue, type EditingPreparation, type EditingPreparationFailure } from "./preparation-queue.js";
 export { createOrderEditor, orderClipboardFormat } from "./order.js";
diff --git a/packages/json-document-editing/tests/canvas-clipboard.test.ts b/packages/json-document-editing/tests/canvas-clipboard.test.ts
new file mode 100644
index 00000000..d91a89e7
--- /dev/null
+++ b/packages/json-document-editing/tests/canvas-clipboard.test.ts
@@ -0,0 +1,39 @@
+import { expect, test } from "vitest";
+import { createCanvasClipboard, type CanvasClipboardContent } from "../src/index.js";
+
+const source = "data:image/png;base64,AQID";
+const options = { bounds: { x: 10, y: 20, width: 200, height: 120 }, textColor: "black", fontSize: 20, contentGap: 10 };
+const content: CanvasClipboardContent = { type: "mixed", items: [
+  { type: "text", text: "Before" }, { type: "image", source, width: 100, height: 50, label: "Figure" }, { type: "text", text: "After" },
+] };
+
+test("mixed content becomes ordered non-overlapping editable objects, not source CSS", () => {
+  const clipboard = createCanvasClipboard(content, options);
+  expect(clipboard.objects.map((object) => [object.kind, object.label, object.x, object.y, object.height])).toEqual([
+    ["text", "Before", 10, 20, 24], ["image", "Figure", 10, 54, 50], ["text", "After", 10, 114, 24],
+  ]);
+  expect(clipboard.objects.map((object) => object.id)).toEqual(["clipboard:0", "clipboard:1", "clipboard:2"]);
+  expect(clipboard.primaryKey).toBe("clipboard:2"); expect(clipboard.text).toBe("Before\nFigure\nAfter");
+});
+
+test("an overflowing flow fits as a whole while retaining image aspect ratio and content", () => {
+  const clipboard = createCanvasClipboard(content, { ...options, bounds: { ...options.bounds, height: 60 } });
+  const objects = clipboard.objects;
+  expect(objects.at(-1)!.y + objects.at(-1)!.height).toBeCloseTo(80);
+  expect(objects[1]!.width / objects[1]!.height).toBe(2);
+  expect(objects[1]!.source).toBe(source);
+  expect(objects[0]!.fontSize).toBeCloseTo(20 * 60 / 118);
+  expect(objects[0]!.y + objects[0]!.height).toBeLessThan(objects[1]!.y);
+});
+
+test("legacy literal text and image cascade remain unchanged", () => {
+  expect(createCanvasClipboard({ type: "text", text: "<b>A</b>\nB" }, options).objects[0]).toMatchObject({ label: "<b>A</b>\nB", height: 48, fontSize: 20 });
+  const image = { source, width: 100, height: 50, label: "Figure" };
+  expect(createCanvasClipboard({ type: "images", images: [image, image] }, options).objects.map((object) => [object.x, object.y])).toEqual([[10, 20], [34, 44]]);
+});
+
+test("empty parts and invalid flow policy reject before a clipboard is produced", () => {
+  expect(() => createCanvasClipboard({ type: "mixed", items: [] }, options)).toThrow();
+  expect(() => createCanvasClipboard({ type: "mixed", items: [{ type: "text", text: "" }] }, options)).toThrow();
+  expect(() => createCanvasClipboard(content, { ...options, contentGap: -1 })).toThrow();
+});
diff --git a/packages/json-document-rich-text-web/README.md b/packages/json-document-rich-text-web/README.md
index 590202db..778e0f13 100644
--- a/packages/json-document-rich-text-web/README.md
+++ b/packages/json-document-rich-text-web/README.md
@@ -8,6 +8,11 @@ Selection round-trips both text offsets and container child boundaries. Copy,
 cut, and paste publish/consume structured Rich Text, safe semantic HTML, and
 plain text in that priority order.
 
+HTML syntax is read through Web's `parseWebHTMLFragment`, an inert template parser
+shared with Canvas and Composer intake. Active and foreign content is excluded;
+returned nodes are never inserted into a live document. Rich Text Web still owns
+schema-specific block/mark conversion. This profile does not add inline images.
+
 Keyboard Undo/Redo consumes the Web package's `createWebKeyboardAdapter` defaults
 (`Mod-z`, `Mod-Shift-z`). This binding retains its historical Alt variants through
 explicit keymap entries. Root ownership and composition handling stay in this
diff --git a/packages/json-document-rich-text-web/src/clipboard.ts b/packages/json-document-rich-text-web/src/clipboard.ts
index 582c2a0b..1ad7e32e 100644
--- a/packages/json-document-rich-text-web/src/clipboard.ts
+++ b/packages/json-document-rich-text-web/src/clipboard.ts
@@ -14,7 +14,7 @@ import {
   type RichTextParagraph,
   type RichTextSchema,
 } from "@interactive-os/json-document-rich-text";
-import type { WebClipboardCodec, WebClipboardRepresentation } from "@interactive-os/json-document-web";
+import { parseWebHTMLFragment, type WebClipboardCodec, type WebClipboardRepresentation } from "@interactive-os/json-document-web";
 
 export function createRichTextClipboardCodec(schema: RichTextSchema = richTextSchemaV1): WebClipboardCodec<RichTextClipboard> {
   return {
@@ -59,10 +59,10 @@ export function serializeRichTextSlice(slice: RichTextSlice): string {
 }
 
 export function parseRichTextHTML(html: string, createId: () => string, profile: string = RICH_TEXT_PROFILE_V1): RichTextClipboard | null {
-  if (html.length === 0 || typeof DOMParser === "undefined") return null;
-  const document = new DOMParser().parseFromString(html, "text/html");
+  const fragment = parseWebHTMLFragment(html);
+  if (!fragment) return null;
   const blocks: RichTextNode[] = [];
-  for (const child of Array.from(document.body.childNodes)) {
+  for (const child of Array.from(fragment.childNodes)) {
     if (child.nodeType === Node.TEXT_NODE && child.textContent?.trim()) {
       blocks.push(paragraph([textNode(child.textContent, [], createId)], createId));
       continue;
diff --git a/packages/json-document-rich-text-web/tests/clipboard.test.ts b/packages/json-document-rich-text-web/tests/clipboard.test.ts
index 719a7783..11f13b74 100644
--- a/packages/json-document-rich-text-web/tests/clipboard.test.ts
+++ b/packages/json-document-rich-text-web/tests/clipboard.test.ts
@@ -91,4 +91,11 @@ describe("Official Rich Text Web clipboard", () => {
     expect(parsed?.slice.content).toMatchObject([{ content: [{ text: "safe text", marks: [] }] }]);
     expect(parsed?.html).not.toContain("javascript:");
   });
+
+  it("uses the inert Web parser without turning active/foreign content into document text", () => {
+    let id = 0;
+    const parsed = parseRichTextHTML('<script>bad()</script><style>body{color:red}</style><svg><text>foreign</text></svg><p><strong>Kept</strong></p>', () => `id-${++id}`);
+    expect(parsed?.text).toBe("Kept");
+    expect(parsed?.html).toBe("<p><strong>Kept</strong></p>");
+  });
 });
diff --git a/packages/json-document-web/README.md b/packages/json-document-web/README.md
index c438220e..39b98492 100644
--- a/packages/json-document-web/README.md
+++ b/packages/json-document-web/README.md
@@ -151,8 +151,9 @@ the formats it enables and their priority, while
 named codecs remain compatibility aliases over those domain formats. Clipboard
 surfaces write both the structured json-document MIME payload and its
 `text/plain` projection. `captureWebClipboardPaste` captures an enabled structured
-representation, files, or literal text before the event expires. Its codec is
-optional for file-only consumers. Domain conversion belongs to the canonical
+representation, files, opt-in image-containing HTML (`html: "images"`), or literal
+text before the event expires. `delegatedMimeTypes` leaves recognized formats to
+an existing nested binding before this priority. Its codec is optional. Domain conversion belongs to the canonical
 Editing or Hand API; the Host supplies product policy.
 
 `readWebRasterFiles` validates a PNG/JPEG/WebP batch and prepares its embedded
@@ -161,6 +162,14 @@ share this path. File Intake owns `RasterImageContent`; Web owns reading and
 decoding, not document mutation or server upload. See the
 [Clipboard API and remaining TBD](docs/clipboard.md).
 
+`parseWebHTMLFragment` is the inert platform parser shared with Rich Text Web;
+its nodes are conversion input, never live DOM insertion output.
+`parseWebClipboardHTML` projects ordered text/image sources. `readWebHTMLClipboard`
+checks embedded PNG/JPEG/WebP data URLs before allocating bytes and reuses the
+raster batch reader. It does not fetch external, relative, blob, or cid URLs.
+Canvas consumes mixed content; Composer accepts image-only HTML and explicitly
+rejects mixed text/images until its document profile can represent them.
+
 The official keyboard adapter owns `defaultWebKeymap`. `resolve` returns a
 semantic command or `null`; `moveLinePoint` and `moveGridPoint` locate the
 visible neighbor. The host still decides when a command applies and which
diff --git a/packages/json-document-web/docs/clipboard.md b/packages/json-document-web/docs/clipboard.md
index 8ed686bc..8751cf2e 100644
--- a/packages/json-document-web/docs/clipboard.md
+++ b/packages/json-document-web/docs/clipboard.md
@@ -37,7 +37,7 @@ const clipboard = createWebClipboardBinding({
 `captureWebClipboardPaste(event, { codec, files: true, text: true })`는 이벤트가 끝나기 전에
 구조화 MIME → 파일 → `text/plain` 순서로 하나의 표현을 캡처합니다. 성공은 `type`이
 `structured`(payload), `files`(파일 배열), `text`(문자열)인 결과입니다. files/text는 명시한
-경우만 처리합니다. `codec`을 생략한 `{ files: true }`는 Composer 같은 file-only 소비자를
+경우만 처리합니다. `codec`을 생략한 `{ files: true }`는 file-only 소비자를
 지원하며 텍스트/HTML의 native 처리를 소유하지 않습니다. 파일 메타데이터는 별도 `fileCandidatesFromWebFiles`
 API로 File Intake에 전달하고, 파일 참조는 실제 browser File이어야 읽을 수 있습니다.
 
@@ -47,6 +47,13 @@ decode 실패도 소유한 실패이며 다른 표현으로 떨어지지 않습
 동기 binding이 제공하는 여러 representation fallback/pass-through와 구분되는 계약입니다.
 일치하는 표현이 없으면 native 처리를 막지 않고 `clipboard.empty`를 반환합니다.
 
+`html: "images"`를 명시하면 파일 다음, 일반 텍스트 전에 이미지가 포함된 HTML을
+선택합니다. 이 overload는 기존 결과에 `{ ok: true, type: "html", content }`를 더합니다.
+이미지가 없는 HTML은 캡처하지 않으며 `text`를 켜지 않은 소비자는 기존 Rich Text 처리를
+유지합니다. `delegatedMimeTypes`에 지정한 MIME이 있으면 모든 캡처보다 먼저
+`clipboard.empty`로 위임하고 이벤트를 소유하지 않습니다. Composer는 내부 Rich Text
+구조화 MIME을 이렇게 기존 binding에 남깁니다. 위임할 실제 binding이 있는 경우에만 지정합니다.
+
 `readWebRasterFile(file, { signal? })`는 기존 FileReader와 Image decode 정본입니다.
 성공은 dataURL과 자연 width/height, 실패는 `raster.read-failed`, `raster.decode-failed`,
 취소는 `raster.cancelled`입니다. 구조적 `WebRasterReadSignal`은 browser AbortSignal과
@@ -65,6 +72,33 @@ decode 실패도 소유한 실패이며 다른 표현으로 떨어지지 않습
 순차화하지만 문서를 변경하거나 Undo 단위·삽입 위치를 결정하지 않습니다. 준비한
 batch를 어떻게 적용하고 언제 취소할지는 Editing과 각 Hand가 소유합니다.
 
+### HTML 이미지와 순서 있는 내용
+
+`parseWebHTMLFragment(html)`은 브라우저의 inert `template`에서 HTML 문법을 읽습니다.
+`script`·`iframe`·`style`·SVG 등의 요소를 제외하고, DOM 순서의 `childNodes`를 가진
+`WebHTMLFragment` 또는 빈/DOM 미지원 환경에서 `null`을 반환합니다. 반환 노드는 live DOM에
+삽입하지 않습니다. 이 API는 문서 의미로 변환할 입력이지, 임의 HTML을 삽입하는 sanitizer가
+아닙니다. Rich Text Web도 같은 parser를 사용하되 block·mark·schema 변환은 직접 소유합니다.
+
+`parseWebClipboardHTML(html)`은 `{ parts }` 또는 `null`을 반환합니다. 각 part는
+`{ type: "text", text }` 또는 `{ type: "image", source, label }`이며 HTML 내부의 순서를
+유지합니다. block·`br`의 줄바꿈과 table cell 경계를 일반 텍스트로 옮기며 서식·CSS 배치는
+보존하지 않습니다. 문자열 16,777,216 UTF-16 code unit, 탐색 노드 10,000개, part 256개를
+넘으면 `RangeError`입니다. opt-in capture에서 이 실패는 `clipboard.invalid`로 소유하며
+일반 텍스트로 조용히 떨어지지 않습니다.
+
+`readWebHTMLClipboard(content, { policy, maxImagePixels, currentCount?, signal?, readRaster? })`는
+PNG/JPEG/WebP base64 data URL만 준비합니다. 모든 source의 형식과 byte 수·파일 정책을
+검사한 뒤 실제 bytes를 할당하고 `readWebRasterFiles`로 decode합니다. 성공 결과의
+`parts`는 text 또는 `{ type: "image", candidate, image }`입니다. 하나라도 실패하면
+일부 part를 돌려주지 않으며 기존 raster/파일 오류와 `raster.source-unsupported`를 구분합니다.
+외부·상대·blob·cid URL은 다운로드하지 않습니다. 빈 source와 읽을 수 없는 이미지도 실패입니다.
+
+Canvas는 이 결과를 Editing의 순서 있는 객체 변환으로 전달합니다. Composer는 이미지-only
+HTML만 첨부로 받으며 글+이미지 입력은 `composer.clipboard.mixed-unsupported`로 전체를 거절합니다.
+native 파일이 함께 있으면 파일 표현이 우선합니다. 파일과 HTML 이미지의 대응을 추측하거나
+같은 내용을 두 번 추가하지 않으며, 두 표현의 혼합 의미 보존은 아직 TBD입니다.
+
 실제 텍스트·이미지 입력 및 순서/취소 연결: [Canvas Usage/Source](/demo/canvas),
-[Composer Usage/Source](/demo/composer). HTML 이미지, 명시적인 plain paste, 이미지 쓰기와
+[Composer Usage/Source](/demo/composer). HTML의 남은 표현 범위, 명시적인 plain paste, 이미지 쓰기와
 OS-native 왕복의 남은 범위는 [Clipboard 기본기 TBD](/docs/clipboard)에 공개합니다.
diff --git a/packages/json-document-web/package.json b/packages/json-document-web/package.json
index 5eb7151a..0a2c51e9 100644
--- a/packages/json-document-web/package.json
+++ b/packages/json-document-web/package.json
@@ -42,6 +42,7 @@
     "@interactive-os/json-document-editing": "*",
     "@interactive-os/json-document-selection": "*",
     "@types/node": "^25.9.0",
+    "jsdom": "^29.1.1",
     "typescript": "^5.0.0",
     "vitest": "^4.1.7"
   }
diff --git a/packages/json-document-web/src/clipboard.ts b/packages/json-document-web/src/clipboard.ts
index c0371b1b..3aed5c54 100644
--- a/packages/json-document-web/src/clipboard.ts
+++ b/packages/json-document-web/src/clipboard.ts
@@ -7,6 +7,7 @@ import {
   treeClipboardFormat,
 } from "@interactive-os/json-document-editing";
 import type { WebFileCandidate, WebFileCandidateList } from "./file-intake.js";
+import { parseWebClipboardHTML, type WebHTMLClipboardContent } from "./html-clipboard.js";
 
 export interface WebClipboardPayload {
   readonly type: string;
@@ -31,15 +32,28 @@ export type WebClipboardPaste<Payload extends WebClipboardPayload> =
   | { readonly ok: true; readonly type: "text"; readonly text: string }
   | Extract<WebClipboardResult<never, never>, { readonly ok: false }>;
 
-/** Captures native data before the event ends: structured → files → literal text. An owned invalid format never falls through. */
+export type WebHTMLClipboardPaste<Payload extends WebClipboardPayload> = WebClipboardPaste<Payload>
+  | { readonly ok: true; readonly type: "html"; readonly content: WebHTMLClipboardContent };
+
+/** Existing callers retain the original result union; HTML image capture is opt-in. */
+export function captureWebClipboardPaste<Payload extends WebClipboardPayload = WebClipboardPayload>(event: WebClipboardEvent, options: {
+  readonly codec?: WebClipboardCodec<Payload>; readonly files?: boolean; readonly text?: boolean; readonly html?: never; readonly delegatedMimeTypes?: ReadonlyArray<string>;
+}): WebClipboardPaste<Payload>;
+export function captureWebClipboardPaste<Payload extends WebClipboardPayload = WebClipboardPayload>(event: WebClipboardEvent, options: {
+  readonly codec?: WebClipboardCodec<Payload>; readonly files?: boolean; readonly text?: boolean; readonly html?: "images"; readonly delegatedMimeTypes?: ReadonlyArray<string>;
+}): WebHTMLClipboardPaste<Payload>;
+/** Captures one enabled representation: structured → files → HTML with images → literal text. */
 export function captureWebClipboardPaste<Payload extends WebClipboardPayload = WebClipboardPayload>(event: WebClipboardEvent, options: {
   readonly codec?: WebClipboardCodec<Payload>;
   readonly files?: boolean;
   readonly text?: boolean;
-}): WebClipboardPaste<Payload> {
+  readonly html?: "images";
+  readonly delegatedMimeTypes?: ReadonlyArray<string>;
+}): WebHTMLClipboardPaste<Payload> {
   const data = event.clipboardData;
   if (data === null) return failure("clipboard.unavailable");
   try {
+    if (options.delegatedMimeTypes && Array.from(data.types).some((type) => options.delegatedMimeTypes!.includes(type))) return failure("clipboard.empty");
     if (options.codec && Array.from(data.types).includes(options.codec.mimeType)) {
       event.preventDefault();
       const result = readRepresentations(data, [options.codec]);
@@ -49,6 +63,15 @@ export function captureWebClipboardPaste<Payload extends WebClipboardPayload = W
       event.preventDefault();
       return { ok: true, type: "files", files: Array.from(data.files) };
     }
+    if (options.html === "images" && Array.from(data.types).includes("text/html")) {
+      let content: WebHTMLClipboardContent | null;
+      try { content = parseWebClipboardHTML(data.getData("text/html")); }
+      catch (error) { event.preventDefault(); return failure("clipboard.invalid", errorMessage(error)); }
+      if (content?.parts.some((part) => part.type === "image")) {
+        event.preventDefault();
+        return { ok: true, type: "html", content };
+      }
+    }
     if (options.text && Array.from(data.types).includes("text/plain")) {
       event.preventDefault();
       const text = data.getData("text/plain");
diff --git a/packages/json-document-web/src/html-clipboard.ts b/packages/json-document-web/src/html-clipboard.ts
new file mode 100644
index 00000000..41852848
--- /dev/null
+++ b/packages/json-document-web/src/html-clipboard.ts
@@ -0,0 +1,79 @@
+import { assertRasterImageSource, validateFileCandidates, type FileCandidate } from "@interactive-os/json-document-file-intake";
+import { parseWebHTMLFragment } from "./html-fragment.js";
+import { readWebRasterFiles, type WebRasterFileContent } from "./raster-files.js";
+
+export type WebHTMLClipboardPart =
+  | { readonly type: "text"; readonly text: string }
+  | { readonly type: "image"; readonly source: string; readonly label: string };
+
+export interface WebHTMLClipboardContent { readonly parts: ReadonlyArray<WebHTMLClipboardPart> }
+export type WebHTMLClipboardResult =
+  | { readonly ok: true; readonly parts: ReadonlyArray<Extract<WebHTMLClipboardPart, { readonly type: "text" }> | ({ readonly type: "image" } & WebRasterFileContent)> }
+  | { readonly ok: false; readonly code: string; readonly reason?: string };
+
+/** DOM order and plain text boundaries, without CSS layout, external source resolution, or document semantics. */
+export function parseWebClipboardHTML(html: string): WebHTMLClipboardContent | null {
+  if (html.length > 16 * 1024 * 1024) throw new RangeError("Clipboard HTML exceeds 16,777,216 code units.");
+  const fragment = parseWebHTMLFragment(html);
+  if (!fragment) return null;
+  const parts: WebHTMLClipboardPart[] = [];
+  let text = "", visited = 0;
+  const flush = () => { if (text.trim()) parts.push({ type: "text", text: text.trim() }); text = ""; };
+  const boundary = () => { if (text && !text.endsWith("\n")) text += "\n"; };
+  const stack = Array.from(fragment.childNodes).reverse().map((node) => ({ node, exit: false, pre: false }));
+  while (stack.length > 0) {
+    const { node, exit, pre } = stack.pop()!;
+    if (exit) { boundary(); continue; }
+    if (++visited > 10_000 || parts.length > 256) throw new RangeError("Clipboard HTML exceeds the node or content limit.");
+    if (node.nodeType === 3) {
+      const value = pre ? node.textContent ?? "" : (node.textContent ?? "").replace(/[\t\r\n\f ]+/g, " ");
+      text += !pre && /[ \n]$/.test(text) ? value.replace(/^ /, "") : value;
+      continue;
+    }
+    if (node.nodeType !== 1) continue;
+    const element = node as Element, tag = element.localName;
+    if (tag === "img") {
+      flush();
+      parts.push({ type: "image", source: (element.getAttribute("src") ?? "").trim(), label: element.getAttribute("alt") ?? "" });
+      continue;
+    }
+    if (tag === "br") { text += "\n"; continue; }
+    const block = /^(p|div|h[1-6]|blockquote|pre|ul|ol|li|section|article|header|footer|figure|figcaption|table|tr)$/.test(tag);
+    if (block) { boundary(); stack.push({ node, exit: true, pre }); }
+    else if (tag === "td" || tag === "th") { if (text && !/[\t\n]$/.test(text)) text += "\t"; }
+    for (const child of Array.from(node.childNodes).reverse()) stack.push({ node: child, exit: false, pre: pre || tag === "pre" });
+  }
+  flush();
+  if (parts.length > 256) throw new RangeError("Clipboard HTML exceeds 256 content parts.");
+  return parts.length > 0 ? { parts } : null;
+}
+
+/** Embedded raster only. Validates every candidate before allocating bytes; prepares one complete ordered result. */
+export async function readWebHTMLClipboard(content: WebHTMLClipboardContent, options: Parameters<typeof readWebRasterFiles>[1] & { readonly currentCount?: number }): Promise<WebHTMLClipboardResult> {
+  if (options.signal?.aborted) return { ok: false, code: "raster.cancelled" };
+  const parts = content.parts.map((part) => ({ ...part }));
+  const images = parts.filter((part): part is Extract<WebHTMLClipboardPart, { readonly type: "image" }> => part.type === "image");
+  const candidates: FileCandidate[] = [];
+  try {
+    for (const [index, image] of images.entries()) {
+      assertRasterImageSource(image.source);
+      const mediaType = image.source.slice(5, image.source.indexOf(";"));
+      const bytes = image.source.slice(image.source.indexOf(",") + 1);
+      const size = bytes.length / 4 * 3 - (bytes.endsWith("==") ? 2 : bytes.endsWith("=") ? 1 : 0);
+      candidates.push({ name: image.label.trim() || `clipboard-image-${index + 1}.${mediaType === "image/jpeg" ? "jpg" : mediaType.slice(6)}`, size, mediaType });
+    }
+  } catch { return { ok: false, code: "raster.source-unsupported", reason: "HTML images require embedded PNG, JPEG, or WebP content." }; }
+  const accepted = validateFileCandidates(candidates, options.policy, options.currentCount === undefined ? {} : { currentCount: options.currentCount });
+  if (!accepted.ok) return accepted;
+  try {
+    const files = images.map((image, index) => {
+      const candidate = candidates[index]!;
+      const bytes = Uint8Array.from(atob(image.source.slice(image.source.indexOf(",") + 1)), (character) => character.charCodeAt(0));
+      return new File([bytes], candidate.name, { type: candidate.mediaType! });
+    });
+    const prepared = await readWebRasterFiles(files, options);
+    if (!prepared.ok) return prepared;
+    let index = 0;
+    return { ok: true, parts: parts.map((part) => part.type === "text" ? part : { type: "image", ...prepared.files[index++]! }) };
+  } catch (error) { return { ok: false, code: "raster.read-failed", reason: error instanceof Error ? error.message : String(error) }; }
+}
diff --git a/packages/json-document-web/src/html-fragment.ts b/packages/json-document-web/src/html-fragment.ts
new file mode 100644
index 00000000..4a6ee065
--- /dev/null
+++ b/packages/json-document-web/src/html-fragment.ts
@@ -0,0 +1,17 @@
+/** Read-only structural Node boundary; Web declarations remain consumable without lib.dom. */
+export interface WebHTMLNode {
+  readonly nodeType: number;
+  readonly textContent: string | null;
+  readonly childNodes: ArrayLike<WebHTMLNode>;
+}
+export interface WebHTMLFragment { readonly childNodes: ArrayLike<WebHTMLNode> }
+
+/** Parses clipboard HTML in a template's inert document. Never append the returned nodes to a live document. */
+export function parseWebHTMLFragment(html: string): WebHTMLFragment | null {
+  if (html.length === 0 || typeof document === "undefined") return null;
+  const template = document.createElement("template");
+  template.innerHTML = html;
+  // Projection input, not a general-purpose HTML sanitizer or an insertion-ready DOM tree.
+  for (const element of Array.from(template.content.querySelectorAll("script,style,noscript,iframe,object,embed,template,svg,math,link,meta,base,title"))) element.remove();
+  return template.content;
+}
diff --git a/packages/json-document-web/src/index.ts b/packages/json-document-web/src/index.ts
index 5ab7794e..67effb31 100644
--- a/packages/json-document-web/src/index.ts
+++ b/packages/json-document-web/src/index.ts
@@ -1,6 +1,7 @@
 export {
   createWebClipboardBinding,
   captureWebClipboardPaste,
+  type WebHTMLClipboardPaste,
   createWebJSONClipboardRepresentation,
   createWebClipboardSurface,
   createWebClipboardTextWriter,
@@ -32,6 +33,8 @@ export { createWebAnchoredFloatingPositionPorts } from "./anchored-floating-posi
 export { projectWebClientPointToSVG, webSVGViewportFromElement } from "./svg-coordinate.js";
 export { readWebRasterFile } from "./raster-source.js";
 export { readWebRasterFiles, type WebRasterFileContent, type WebRasterFilesResult } from "./raster-files.js";
+export { parseWebHTMLFragment, type WebHTMLFragment, type WebHTMLNode } from "./html-fragment.js";
+export { parseWebClipboardHTML, readWebHTMLClipboard, type WebHTMLClipboardContent, type WebHTMLClipboardPart, type WebHTMLClipboardResult } from "./html-clipboard.js";
 export { composerAttachmentCandidateFromWebFile, composerAttachmentCandidatesFromWebClipboard, composerAttachmentCandidatesFromWebFiles, fileCandidateFromWebFile, fileCandidatesFromWebClipboard, fileCandidatesFromWebFiles } from "./file-intake.js";
 export { renderWebAnnotationRaster } from "./annotation-raster.js";
 export { registerWebVirtualSelectionScope } from "./virtual-selection-scope.js";
diff --git a/packages/json-document-web/tests/html-clipboard.test.ts b/packages/json-document-web/tests/html-clipboard.test.ts
new file mode 100644
index 00000000..609f7178
--- /dev/null
+++ b/packages/json-document-web/tests/html-clipboard.test.ts
@@ -0,0 +1,102 @@
+// @vitest-environment jsdom
+import { expect, expectTypeOf, test, vi } from "vitest";
+import { captureWebClipboardPaste, objectClipboardCodec, parseWebClipboardHTML, parseWebHTMLFragment, readWebHTMLClipboard, type readWebRasterFile, type WebClipboardPaste, type WebClipboardPayload, type WebRasterSourceResult } from "../src/index.js";
+
+const source = "data:image/png;base64,AQID";
+const image = { ok: true as const, dataURL: source, width: 100, height: 50 };
+const options = { policy: { acceptedMediaTypes: ["image/*"], maxFiles: 4, maxBytesPerFile: 100 }, maxImagePixels: 10_000 };
+const markup = `<p>앞 <strong>문장</strong> &amp; 글<img src="${source}" alt="사진">뒤<br>문장</p>`;
+const event = (html = markup, files: File[] = []) => ({ clipboardData: { types: ["text/html", "text/plain"], files, getData: (type: string) => type === "text/html" ? html : "Fallback", setData() {} }, preventDefault: vi.fn() });
+
+test("HTML parts preserve text/image order, entities, and line boundaries", () => {
+  expect(parseWebClipboardHTML(markup)).toEqual({ parts: [
+    { type: "text", text: "앞 문장 & 글" }, { type: "image", source, label: "사진" }, { type: "text", text: "뒤\n문장" },
+  ] });
+  expect(parseWebClipboardHTML('<div>One</div><div>Two</div><pre>a\n  b</pre>')?.parts).toEqual([{ type: "text", text: "One\nTwo\na\n  b" }]);
+  expect(parseWebClipboardHTML('<table><tr><td>A</td><td>B</td></tr><tr><td>C</td><td>D</td></tr></table>')?.parts).toEqual([{ type: "text", text: "A\tB\nC\tD" }]);
+  expect(parseWebClipboardHTML(`<img src="${source}"><img src="${source}">`)?.parts).toHaveLength(2);
+});
+
+test("fragment parsing stays in the template document and excludes active/foreign content", () => {
+  const fragment = parseWebHTMLFragment('<script>bad()</script><style>body{color:red}</style><iframe src="/blocked"></iframe><svg><text>foreign</text></svg><template><img src="/hidden"></template><p>Kept</p><img src="/not-fetched">')!;
+  const nodes = Array.from(fragment.childNodes) as Node[];
+  expect(nodes.map((node) => node.nodeName)).toEqual(["P", "IMG"]);
+  expect(nodes.every((node) => !node.isConnected && node.ownerDocument !== document)).toBe(true);
+  expect(parseWebClipboardHTML('<script>bad()</script><style>bad</style><p>Kept</p>')?.parts).toEqual([{ type: "text", text: "Kept" }]);
+});
+
+test("HTML image capture is opt-in, synchronous, and does not claim text-only HTML", () => {
+  const legacy = captureWebClipboardPaste(event(), { files: true, text: true });
+  expectTypeOf(legacy).toEqualTypeOf<WebClipboardPaste<WebClipboardPayload>>();
+  expect(legacy).toMatchObject({ type: "text", text: "Fallback" });
+  const mixed = event();
+  expect(captureWebClipboardPaste(mixed, { html: "images" })).toMatchObject({ type: "html", content: { parts: [{ type: "text" }, { type: "image" }, { type: "text" }] } });
+  expect(mixed.preventDefault).toHaveBeenCalledOnce();
+  const plain = event("<p><strong>Formatted text</strong></p>");
+  expect(captureWebClipboardPaste(plain, { files: true, html: "images" })).toMatchObject({ ok: false });
+  expect(plain.preventDefault).not.toHaveBeenCalled();
+});
+
+test("structured and native files retain priority; equivalent HTML is never inserted twice", () => {
+  const withFiles = event('<img src="https://example.invalid/image">', [new File(["image"], "native.png", { type: "image/png" })]);
+  expect(captureWebClipboardPaste(withFiles, { files: true, html: "images", text: true })).toMatchObject({ type: "files" });
+  const invalid = event(); invalid.clipboardData.types.unshift(objectClipboardCodec.mimeType);
+  invalid.clipboardData.getData = () => "{";
+  expect(captureWebClipboardPaste(invalid, { codec: objectClipboardCodec, files: true, html: "images", text: true })).toMatchObject({ ok: false, code: "clipboard.invalid" });
+  expect(invalid.preventDefault).toHaveBeenCalledOnce();
+});
+
+test("a delegated structured format stays with its existing editor binding", () => {
+  const delegated = event(); delegated.clipboardData.types.unshift("application/editor+json");
+  expect(captureWebClipboardPaste(delegated, { files: true, html: "images", delegatedMimeTypes: ["application/editor+json"] })).toMatchObject({ ok: false, code: "clipboard.empty" });
+  expect(delegated.preventDefault).not.toHaveBeenCalled();
+});
+
+test.each(["https://example.invalid/image", "/image.png", "blob:https://example.invalid/id", "cid:image", "javascript:alert(1)", "data:image/svg+xml;base64,AQID", "data:image/png;base64,broken", ""])("unavailable HTML source %s fails without reading or fallback", async (src) => {
+  const readRaster = vi.fn<typeof readWebRasterFile>();
+  expect(await readWebHTMLClipboard(parseWebClipboardHTML(`<p>Text<img src="${src}">After</p>`)!, { ...options, readRaster })).toMatchObject({ ok: false, code: "raster.source-unsupported" });
+  expect(readRaster).not.toHaveBeenCalled();
+});
+
+test("HTML image preparation owns candidate bytes and preserves every ordered part", async () => {
+  const readRaster = vi.fn<typeof readWebRasterFile>().mockResolvedValue(image);
+  const result = await readWebHTMLClipboard(parseWebClipboardHTML(markup)!, { ...options, readRaster });
+  expect(result).toEqual({ ok: true, parts: [
+    { type: "text", text: "앞 문장 & 글" },
+    { type: "image", candidate: { name: "사진", size: 3, mediaType: "image/png" }, image: { source, width: 100, height: 50 } },
+    { type: "text", text: "뒤\n문장" },
+  ] });
+  expect(readRaster.mock.calls[0]?.[0]).toBeInstanceOf(File);
+});
+
+test("policy rejects before byte allocation, including the current attachment count", async () => {
+  const atob = vi.spyOn(globalThis, "atob");
+  const readRaster = vi.fn<typeof readWebRasterFile>();
+  try {
+    expect(await readWebHTMLClipboard(parseWebClipboardHTML(markup)!, { ...options, currentCount: 4, readRaster })).toMatchObject({ ok: false, code: "file-intake.limit" });
+    expect(await readWebHTMLClipboard(parseWebClipboardHTML(markup)!, { ...options, policy: { ...options.policy, maxBytesPerFile: 2 }, readRaster })).toMatchObject({ ok: false, code: "file-intake.size" });
+    expect(atob).not.toHaveBeenCalled(); expect(readRaster).not.toHaveBeenCalled();
+  } finally { atob.mockRestore(); }
+});
+
+test("a later decode failure returns neither prepared images nor partial text", async () => {
+  const readRaster = vi.fn<typeof readWebRasterFile>().mockResolvedValueOnce(image).mockResolvedValueOnce({ ok: false, code: "raster.decode-failed" });
+  expect(await readWebHTMLClipboard(parseWebClipboardHTML(`${markup}<img src="${source}">`)!, { ...options, readRaster })).toEqual({ ok: false, code: "raster.decode-failed" });
+});
+
+test("cancellation ignores a late decode and prevents later HTML image reads", async () => {
+  let resolve!: (value: WebRasterSourceResult) => void;
+  const readRaster = vi.fn<typeof readWebRasterFile>(() => new Promise((done) => { resolve = done; }));
+  const controller = new AbortController();
+  const pending = readWebHTMLClipboard(parseWebClipboardHTML(`${markup}<img src="${source}">`)!, { ...options, readRaster, signal: controller.signal });
+  controller.abort(); resolve(image);
+  expect(await pending).toMatchObject({ ok: false, code: "raster.cancelled" }); expect(readRaster).toHaveBeenCalledOnce();
+});
+
+test("oversized HTML fails as an owned input rather than falling back to partial text", () => {
+  const oversized = event(`<img src="${source}">`.repeat(257));
+  expect(captureWebClipboardPaste(oversized, { html: "images", text: true })).toMatchObject({ ok: false, code: "clipboard.invalid" });
+  expect(oversized.preventDefault).toHaveBeenCalledOnce();
+  expect(() => parseWebClipboardHTML(" ".repeat(16 * 1024 * 1024 + 1))).toThrow(RangeError);
+  expect(() => parseWebClipboardHTML("<div></div>".repeat(10_001))).toThrow(RangeError);
+});
diff --git a/site/src/shared/composer/ComposerDemo.tsx b/site/src/shared/composer/ComposerDemo.tsx
index 37050faa..dcb0bc98 100644
--- a/site/src/shared/composer/ComposerDemo.tsx
+++ b/site/src/shared/composer/ComposerDemo.tsx
@@ -117,7 +117,11 @@ export function ComposerDemo(props: {
             <span role="status">이미지를 준비하고 있습니다. 계속 입력할 수 있어요.</span>
             <Command className="composer-icon-button" label="이미지 준비 취소" onClick={composer.cancelAttachments}><X aria-hidden="true" size={16} /></Command>
           </div> : null}
-          {composer.attachmentError ? <p className="composer-attachment-status" role="alert">첨부하지 못했습니다: {composer.attachmentError.reason ?? composer.attachmentError.code}</p> : null}
+          {composer.attachmentError ? <p className="composer-attachment-status" role="alert">{composer.attachmentError.code === "composer.clipboard.mixed-unsupported"
+            ? "글과 이미지가 함께 있는 HTML 붙여넣기는 아직 지원하지 않습니다. 내용을 나누어 붙여넣어 주세요."
+            : composer.attachmentError.code === "raster.source-unsupported"
+              ? "이 HTML 이미지의 내용을 읽을 수 없습니다. PNG·JPEG·WebP 파일을 첨부해 주세요."
+              : `첨부하지 못했습니다: ${composer.attachmentError.reason ?? composer.attachmentError.code}`}</p> : null}
 
           <div className="composer-input-row">
             <Menu
diff --git a/site/src/shared/demo-workbench/demo-sources.ts b/site/src/shared/demo-workbench/demo-sources.ts
index 94bc83b1..59004a08 100644
--- a/site/src/shared/demo-workbench/demo-sources.ts
+++ b/site/src/shared/demo-workbench/demo-sources.ts
@@ -93,6 +93,8 @@ import annotationEditingSource from "../../../../packages/json-document-editing/
 import webSVGCoordinateSource from "../../../../packages/json-document-web/src/svg-coordinate.ts?raw";
 import webRasterSource from "../../../../packages/json-document-web/src/raster-source.ts?raw";
 import webRasterFilesSource from "../../../../packages/json-document-web/src/raster-files.ts?raw";
+import webHTMLFragmentSource from "../../../../packages/json-document-web/src/html-fragment.ts?raw";
+import webHTMLClipboardSource from "../../../../packages/json-document-web/src/html-clipboard.ts?raw";
 import webAnnotationRasterSource from "../../../../packages/json-document-web/src/annotation-raster.ts?raw";
 import uiMenuSource from "../../../../packages/json-document-ui-primitives-react/src/menu.tsx?raw";
 import uiSelectSource from "../../../../packages/json-document-ui-primitives-react/src/select.tsx?raw";
@@ -211,6 +213,8 @@ const excludedSources = new Set([
 const registeredUsageSources = new Map<string, string>([
   ["packages/json-document-editing/src/preparation-queue.ts", editingPreparationQueueSource],
   ["packages/json-document-web/src/raster-files.ts", webRasterFilesSource],
+  ["packages/json-document-web/src/html-fragment.ts", webHTMLFragmentSource],
+  ["packages/json-document-web/src/html-clipboard.ts", webHTMLClipboardSource],
   ["packages/json-document-file-intake/src/raster-content.ts", rasterContentSource],
   ["packages/json-document-composer-react/src/attachments.ts", composerAttachmentsSource],
   ["packages/json-document-object-document/src/object-model.ts", objectModelSource],
@@ -360,6 +364,11 @@ const registeredUsageSources = new Map<string, string>([
   ["packages/json-document-zod/src/index.ts", zodSource],
 ]);
 const registeredPublicUsages = [
+  { packageName: "@interactive-os/json-document-web", symbol: "parseWebHTMLFragment", sourcePath: "packages/json-document-web/src/html-fragment.ts" },
+  ...["captureWebClipboardPaste", "parseWebClipboardHTML", "readWebHTMLClipboard"].flatMap((symbol) => [
+    { packageName: "@interactive-os/json-document-web", symbol, sourcePath: "packages/json-document-web/src/html-clipboard.ts" },
+    { packageName: "@interactive-os/json-document-web", symbol, sourcePath: "packages/json-document-web/src/html-fragment.ts" },
+  ]),
   { packageName: "@interactive-os/json-document-editing", symbol: "createEditingPreparationQueue", sourcePath: "packages/json-document-editing/src/preparation-queue.ts" },
   { packageName: "@interactive-os/json-document-editing", symbol: "createObjectPasteSession", sourcePath: "packages/json-document-editing/src/preparation-queue.ts" },
   { packageName: "@interactive-os/json-document-web", symbol: "readWebRasterFiles", sourcePath: "packages/json-document-web/src/raster-files.ts" },
diff --git a/site/tests/unit/composer-demo.test.tsx b/site/tests/unit/composer-demo.test.tsx
index d5dd33a6..cc4b8ef8 100644
--- a/site/tests/unit/composer-demo.test.tsx
+++ b/site/tests/unit/composer-demo.test.tsx
@@ -19,6 +19,8 @@ describe("Agent Chat Composer Hands", () => {
     expect(composerDemoSource).toContain("useComposer(");
     expect(composerDemoSource).not.toContain("addComposerAttachments(");
     expect(composerDemoSource).not.toContain("fileCandidatesFromWebFiles(");
+    expect(composerDemoSource).not.toContain("parseWebClipboardHTML(");
+    expect(composerDemoSource).not.toContain("readWebHTMLClipboard(");
     expect(composerDemoSource).not.toContain("composerAttachmentCandidatesFromWebFiles(");
     expect(composerDemoSource).not.toContain("composer-placeholder-box");
     expect(composerDemoSource).toContain('placeholder="작업을 입력하세요"');
@@ -41,6 +43,7 @@ describe("Agent Chat Composer Hands", () => {
     expect(composerAttachmentsSource).toContain("addComposerAttachments(");
     expect(composerAttachmentsSource).toContain("fileCandidatesFromWebFiles(");
     expect(composerAttachmentsSource).toContain("readWebRasterFiles(");
+    expect(composerAttachmentsSource).toContain("readWebHTMLClipboard(");
     expect(composerAttachmentsSource).toContain("createEditingPreparationQueue<");
     expect(composerCommandMenuSource).toContain("useRichTextSuggestion(");
     expect(composerCommandMenuSource).toContain("useRichTextMentionSuggestions(");
@@ -54,6 +57,8 @@ describe("Agent Chat Composer Hands", () => {
       "packages/json-document-composer/src/commands.ts",
       "packages/json-document-file-intake/src/raster-content.ts",
       "packages/json-document-web/src/raster-files.ts",
+      "packages/json-document-web/src/html-clipboard.ts",
+      "packages/json-document-web/src/html-fragment.ts",
       "packages/json-document-editing/src/preparation-queue.ts",
     ]) {
       const source = sources.find((entry) => entry.path === path);
@@ -116,6 +121,17 @@ describe("Agent Chat Composer Hands", () => {
     expect(screen.queryByText(/HCX/)).toBeNull();
   });
 
+  test("shows mixed HTML as unsupported without silently dropping part of the draft", async () => {
+    render(<ComposerDemoRoute />);
+    const before = screen.getByTestId("composer-draft-json").textContent;
+    fireEvent.paste(screen.getByLabelText("Agent Chat Composer"), { clipboardData: {
+      types: ["text/html", "text/plain"], files: [],
+      getData: (type: string) => type === "text/html" ? '<p>보존할 글</p><img src="data:image/png;base64,AQID">' : "보존할 글",
+    } });
+    expect(await screen.findByText("글과 이미지가 함께 있는 HTML 붙여넣기는 아직 지원하지 않습니다. 내용을 나누어 붙여넣어 주세요.")).toBeTruthy();
+    expect(screen.getByTestId("composer-draft-json").textContent).toBe(before);
+  });
+
   test("routes dropped files through the same canonical attachment context", () => {
     render(<ComposerDemoRoute />);
     const composer = screen.getByTestId("agent-chat-composer");
diff --git a/site/tests/unit/demo-workbench.test.tsx b/site/tests/unit/demo-workbench.test.tsx
index 870a3bca..6cf55958 100644
--- a/site/tests/unit/demo-workbench.test.tsx
+++ b/site/tests/unit/demo-workbench.test.tsx
@@ -73,6 +73,8 @@ describe("Demo definition and source discovery", () => {
       ["packages/json-document-editing/src/preparation-queue.ts", "/docs/api/editing"],
       ["packages/json-document-web/src/raster-source.ts", "/docs/api/web"],
       ["packages/json-document-web/src/raster-files.ts", "/docs/api/web"],
+      ["packages/json-document-web/src/html-clipboard.ts", "/docs/api/web"],
+      ["packages/json-document-web/src/html-fragment.ts", "/docs/api/web"],
       ["packages/json-document-file-intake/src/raster-content.ts", "/docs/api/file-intake"],
       ["packages/json-document-file-intake/src/index.ts", "/docs/api/file-intake"],
     ]) {
diff --git a/standards/editing-grammar.md b/standards/editing-grammar.md
index 7f46e7d8..b6a85ddb 100644
--- a/standards/editing-grammar.md
+++ b/standards/editing-grammar.md
@@ -286,12 +286,13 @@ EG-COPY/CUT/PASTE/HISTORY의 구체화이며 새로운 Stable profile이나 Core
 | PI-ORDER | 준비 완료 순서가 달라도 요청 순서로 한 batch씩 반영 | Editing | Object·Composer가 공통 queue 소비; [순서·재진입 사례](../packages/json-document-editing/tests/preparation-queue.test.ts) |
 | PI-CANCEL | 취소·History 작업·unmount 뒤 늦은 결과는 무효 | Editing·각 Hand | Object 자동 무효화, Composer Escape·binding History·unmount 취소 구현; [취소 사례](../packages/json-document-composer-react/tests/composer-attachments.test.tsx) |
 | PI-TYPING | 첨부 준비 중 typing/caret 이동 허용; 완료 시 최신 첨부 목록 뒤에 추가 | Composer·React Connector | 구현; [연속 첨부·typing·caret 사례](../packages/json-document-composer-react/tests/composer-attachments.test.tsx). inline anchor mapping은 아님 |
-| PI-HTML | 대체 MIME 선택과 HTML 내부의 글+이미지 순서 보존을 구분 | Web·Rich Text Web·각 Hand | TBD: HTML 이미지, 불가한 source의 실패와 안전한 변환 |
+| PI-HTML | 대체 MIME 선택과 HTML 내부의 글+이미지 순서 보존을 구분 | Web·Rich Text Web·각 Hand | 부분 구현: [inert HTML·우선순위·source 실패](../packages/json-document-web/tests/html-clipboard.test.ts), [Canvas 흐름 변환](../packages/json-document-editing/tests/canvas-clipboard.test.ts), [Composer 이미지-only·mixed 거절](../packages/json-document-composer-react/tests/composer-attachments.test.tsx); TBD: files↔HTML 대응, 외부 source, Composer inline 혼합 의미 |
 | PI-PLAIN | 명시적인 plain paste와 지원 서식 paste를 분리 | Web·Affordance·각 Hand | TBD: 실제 modifier/native editable 사례 |
 | PI-EXPORT | 선택한 Canvas 객체를 PNG로 복사; write 실패는 문서 불변 | Canvas·Web | TBD: 혼합 선택·투명 배경·권한 실패·외부 앱 확인 |
 | PI-NATIVE | OS screenshot, 브라우저 Copy Image, Docs/Slides HTML, 외부 앱 왕복 | Web·제품 경로 | TBD: DOM 합성 이벤트를 OS-native 증거로 계산하지 않음 |
 
-첫 이미지 slice는 서버 upload·임의 URL fetch·HTML import를 추가하지 않는다.
+서버 upload·임의 URL fetch는 추가하지 않는다. 첫 파일 slice에 이어 HTML slice는
+포함된 PNG/JPEG/WebP와 순서 있는 일반 글만 변환하며 원본 CSS·Office layout을 재현하지 않는다.
 TBD를 위해 미동작 public stub이나 범용 registry를 만들지 않는다. Canvas의
 외부 문서/선택 변경 시 취소 정책과 Composer의 typing 중 첨부 준비 유지 정책은
 서로 다른 profile 선택으로 유지한다. 동일한 준비 queue·raster 검증/읽기 책임만

From ec524d78e2f1ea05ce7c16c70d79c9abb66503ef Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E1=84=8B=E1=85=B2=E1=84=8B=E1=85=AD=E1=86=BC=E1=84=90?=
 =?UTF-8?q?=E1=85=A2?= <teo.v@navercorp.com>
Date: Wed, 9 Sep 2026 23:57:16 +0900
Subject: [PATCH 16/20] =?UTF-8?q?fix(canvas):=20=EC=83=9D=EC=84=B1=20?=
 =?UTF-8?q?=EA=B8=B0=EB=B3=B8=20=ED=81=AC=EA=B8=B0=EA=B0=80=20=EB=93=9C?=
 =?UTF-8?q?=EB=9E=98=EA=B7=B8=20=EC=A0=84=EC=97=90=20=EB=85=B8=EC=B6=9C?=
 =?UTF-8?q?=EB=90=98=EB=8A=94=20=EB=AC=B8=EC=A0=9C=EB=A5=BC=20=EA=B3=A0?=
 =?UTF-8?q?=EC=B9=9C=EB=8B=A4?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 packages/json-document-canvas/docs/api.md     |  4 +
 .../json-document-canvas/src/canvas-hand.tsx  |  2 +-
 .../src/use-canvas-hand.ts                    | 17 ++--
 .../tests/canvas-hand.test.tsx                | 85 ++++++++++++++++++-
 4 files changed, 98 insertions(+), 10 deletions(-)

diff --git a/packages/json-document-canvas/docs/api.md b/packages/json-document-canvas/docs/api.md
index d06fdce0..9e6d4e40 100644
--- a/packages/json-document-canvas/docs/api.md
+++ b/packages/json-document-canvas/docs/api.md
@@ -28,6 +28,10 @@ Host: 한 장 fixture, 크기·색상 정책, 레이아웃
 ### 입력과 History
 
 - 도구를 고르고 클릭하면 기본 크기, 드래그하면 지정한 크기로 생성합니다.
+  사각형·타원·글자는 누르거나 작게 흔들리는 동안 기본 크기를 미리 표시하지 않습니다.
+  시작점에서 3 문서 단위 이상 움직이면 실제 드래그 상자만 표시하며, 다시 시작점 근처로
+  돌아와도 클릭 크기로 바뀌지 않습니다. 클릭 기본 크기는 놓을 때 press 위치에만 생성합니다.
+  드래그 후 시작점에 정확히 돌아와 놓으면 객체나 History를 만들지 않습니다.
   생성 후 Select로 돌아가며 새 객체를 선택합니다. 펜은 최소 두 지점이 필요합니다.
 - 객체 click은 단일 선택, Shift+click은 toggle입니다. 빈 곳 click은 clear,
   drag는 marquee replace, Shift+marquee는 add입니다. Mod+A를 반복해도 전체 선택을 유지합니다.
diff --git a/packages/json-document-canvas/src/canvas-hand.tsx b/packages/json-document-canvas/src/canvas-hand.tsx
index b9999d46..b7795f98 100644
--- a/packages/json-document-canvas/src/canvas-hand.tsx
+++ b/packages/json-document-canvas/src/canvas-hand.tsx
@@ -50,7 +50,7 @@ export function CanvasHand(props: CanvasHandProps) {
             onSelect={(shiftKey) => hand.select(object.id, shiftKey)} onEdit={() => hand.editText(object.id)} onHandle={(interaction, event) => hand.interaction(interaction, event, object, "drag")} />
         </g>)}
         {copyOriginals.size > 0 && <g data-canvas-copy-preview="" pointerEvents="none">{hand.objects.filter((object) => selectedKeys.has(object.id)).map((object) => <CanvasObjectView key={object.id} object={object} />)}</g>}
-        {hand.preview && <g pointerEvents="none" opacity={0.65}><CanvasObjectView object={{ ...hand.preview, id: "preview" }} /></g>}
+        {hand.preview && <g data-canvas-preview="" pointerEvents="none" opacity={0.65}><CanvasObjectView object={{ ...hand.preview, id: "preview" }} /></g>}
         {hand.tool === "select" && hand.objects.filter((object) => selectedKeys.has(object.id)).map((object) =>
           <rect key={object.id} data-selection-outline={object.id} x={object.x} y={object.y} width={object.width} height={object.height} fill="none" stroke="rgb(var(--color-border-accent))" strokeWidth={object.id === selected?.id ? 2 : 1} pointerEvents="none" />)}
         {selected && hand.tool === "select" && <g>
diff --git a/packages/json-document-canvas/src/use-canvas-hand.ts b/packages/json-document-canvas/src/use-canvas-hand.ts
index d8721998..77f1b761 100644
--- a/packages/json-document-canvas/src/use-canvas-hand.ts
+++ b/packages/json-document-canvas/src/use-canvas-hand.ts
@@ -15,7 +15,7 @@ export interface CanvasCreationStyle {
 }
 
 type Gesture = { readonly base: CanvasDocument } & (
-  | { readonly type: "create"; readonly tool: Exclude<CanvasObjectKind, "path" | "image">; readonly start: ObjectPoint; readonly point: ObjectPoint }
+  | { readonly type: "create"; readonly tool: Exclude<CanvasObjectKind, "path" | "image">; readonly start: ObjectPoint; readonly point: ObjectPoint; readonly dragged: boolean }
   | { readonly type: "draw"; readonly points: ReadonlyArray<ObjectPoint> }
   | { readonly type: "resize"; readonly object: CanvasObject; readonly start: ObjectPoint; readonly point: ObjectPoint; readonly edge: ResizeEdge }
 );
@@ -138,12 +138,15 @@ export function useCanvasHand(editor: ObjectEditor, style: CanvasCreationStyle,
     return point && Number.isFinite(point.x) && Number.isFinite(point.y) ? { x: point.x, y: point.y } : null;
   }
 
-  function createPreview(gesture: Extract<Gesture, { type: "create" | "draw" }>) {
+  function createPreview(gesture: Extract<Gesture, { type: "create" | "draw" }>, committing = false) {
     if (gesture.type === "draw") return gesture.points.length < 2 ? null : createCanvasPath(gesture.points, { color: style.textColor, label: "Drawing", strokeWidth: style.strokeWidth });
     const { start, point } = gesture;
-    const click = Math.hypot(point.x - start.x, point.y - start.y) < 3;
+    const click = !gesture.dragged;
+    // A default-sized object belongs to the completed click, never its press preview.
+    if (click && !committing) return null;
+    if (!click && start.x === point.x && start.y === point.y) return null;
     return createCanvasObject(gesture.tool, {
-      x: Math.min(start.x, point.x), y: Math.min(start.y, point.y),
+      x: click ? start.x : Math.min(start.x, point.x), y: click ? start.y : Math.min(start.y, point.y),
       width: click ? (gesture.tool === "text" ? 280 : 160) : Math.abs(point.x - start.x),
       height: click ? (gesture.tool === "text" ? 64 : 100) : Math.abs(point.y - start.y),
     }, { color: gesture.tool === "text" ? style.textColor : style.color, label: gesture.tool === "text" ? "Text" : "", fontSize: style.fontSize });
@@ -159,7 +162,7 @@ export function useCanvasHand(editor: ObjectEditor, style: CanvasCreationStyle,
     const active = gestures.commit();
     if (!active || active.base !== current()) return;
     if (active.type === "create" || active.type === "draw") {
-      const object = createPreview(active);
+      const object = createPreview(active, true);
       if (!object) return;
       const result = dispatch({ type: "object.create", object });
       if (result.ok) {
@@ -183,7 +186,7 @@ export function useCanvasHand(editor: ObjectEditor, style: CanvasCreationStyle,
     pointer.begin(event.currentTarget, event.pointerId, true);
     if (tool === "select") { beginSelect(point, null, event); return; }
     const base = current();
-    gestures.begin(tool === "path" ? { type: "draw", points: [point], base } : { type: "create", tool, start: point, point, base });
+    gestures.begin(tool === "path" ? { type: "draw", points: [point], base } : { type: "create", tool, start: point, point, dragged: false, base });
   }
 
   function pointerMove(event: PointerEvent<SVGSVGElement>) {
@@ -194,6 +197,8 @@ export function useCanvasHand(editor: ObjectEditor, style: CanvasCreationStyle,
     if (active.type === "draw") {
       const last = active.points.at(-1)!;
       if (last.x !== point.x || last.y !== point.y) gestures.preview({ ...active, points: [...active.points, point] });
+    } else if (active.type === "create") {
+      gestures.preview({ ...active, point, dragged: active.dragged || Math.hypot(point.x - active.start.x, point.y - active.start.y) >= 3 });
     } else gestures.preview({ ...active, point });
   }
 
diff --git a/packages/json-document-canvas/tests/canvas-hand.test.tsx b/packages/json-document-canvas/tests/canvas-hand.test.tsx
index 5808a26f..5174ba31 100644
--- a/packages/json-document-canvas/tests/canvas-hand.test.tsx
+++ b/packages/json-document-canvas/tests/canvas-hand.test.tsx
@@ -349,6 +349,83 @@ test("every toolbar control shares icon, accessible name and canonical tooltip w
   expect(toolbar.getByRole("button", { name: "선택" }).getAttribute("aria-pressed")).toBe("false");
 });
 
+const creationTools = [
+  { tool: "사각형", kind: "rectangle", width: 160, height: 100 },
+  { tool: "타원", kind: "ellipse", width: 160, height: 100 },
+  { tool: "글자", kind: "text", width: 280, height: 64 },
+] as const;
+
+function creationPreview(container: HTMLElement) {
+  const view = container.querySelector("[data-canvas-preview]")?.firstElementChild;
+  if (!view) return null;
+  return {
+    width: Number(view.getAttribute(view.tagName === "ellipse" ? "rx" : "width")) * (view.tagName === "ellipse" ? 2 : 1),
+    height: Number(view.getAttribute(view.tagName === "ellipse" ? "ry" : "height")) * (view.tagName === "ellipse" ? 2 : 1),
+  };
+}
+
+test.each(creationTools)("$kind press stays empty and a drag previews only its current bounds", ({ tool, kind }) => {
+  const { svg, container, value, commits } = setup();
+  fireEvent.click(screen.getByRole("button", { name: tool }));
+  fireEvent.pointerDown(svg, event(40, 50));
+  expect(creationPreview(container)).toBeNull();
+  fireEvent.pointerMove(svg, event(40.5, 50.5));
+  expect(creationPreview(container)).toBeNull();
+  fireEvent.pointerMove(svg, event(42, 51.5));
+  expect(creationPreview(container)).toEqual({ width: 4, height: 3 });
+  fireEvent.pointerMove(svg, event(44, 53));
+  expect(creationPreview(container)).toEqual({ width: 8, height: 6 });
+  expect(value()).toEqual(blank); expect(commits).not.toHaveBeenCalled();
+  fireEvent.pointerUp(svg, event(140, 100));
+  expect(creationPreview(container)).toBeNull();
+  expect(value().objects[0]).toMatchObject({ kind, x: 80, y: 100, width: 200, height: 100 });
+  expect(commits).toHaveBeenCalledOnce();
+});
+
+test.each(creationTools)("$kind click creates its default size only on release at the press anchor", ({ tool, kind, width, height }) => {
+  const { svg, container, value, commits } = setup();
+  fireEvent.click(screen.getByRole("button", { name: tool }));
+  fireEvent.pointerDown(svg, event(40, 50));
+  fireEvent.pointerMove(svg, event(39.5, 49.5));
+  expect(creationPreview(container)).toBeNull(); expect(value()).toEqual(blank);
+  fireEvent.pointerUp(svg, event(39.5, 49.5));
+  expect(value().objects[0]).toMatchObject({ kind, x: 80, y: 100, width, height });
+  expect(commits).toHaveBeenCalledOnce();
+  expect(screen.queryByRole("textbox", { name: "Canvas text" }) !== null).toBe(kind === "text");
+});
+
+test.each(creationTools)("$kind stays a drag near the origin and an exact return creates nothing", ({ tool, width, height }) => {
+  const { svg, container, value, editor, commits } = setup();
+  fireEvent.click(screen.getByRole("button", { name: tool }));
+  fireEvent.pointerDown(svg, event(40, 50)); fireEvent.pointerMove(svg, event(50, 60));
+  fireEvent.pointerMove(svg, event(40.5, 50.5));
+  expect(creationPreview(container)).toEqual({ width: 1, height: 1 });
+  fireEvent.pointerMove(svg, event(40, 50));
+  expect(creationPreview(container)).toBeNull();
+  fireEvent.pointerUp(svg, event(40, 50));
+  expect(value()).toEqual(blank); expect(editor.snapshot.canUndo).toBe(false); expect(commits).not.toHaveBeenCalled();
+  fireEvent.pointerDown(svg, event(80, 60)); fireEvent.pointerUp(svg, event(80, 60));
+  expect(value().objects[0]).toMatchObject({ id: "object-1", width, height });
+});
+
+test("a foreign pointer cannot change a pending click into a drag", () => {
+  const { svg, container, value } = setup();
+  fireEvent.click(screen.getByRole("button", { name: "사각형" }));
+  fireEvent.pointerDown(svg, event(40, 50));
+  fireEvent.pointerMove(svg, event(140, 100, 9)); fireEvent.pointerUp(svg, event(140, 100, 9));
+  expect(creationPreview(container)).toBeNull(); expect(value()).toEqual(blank);
+  fireEvent.pointerUp(svg, event(40, 50));
+  expect(value().objects[0]).toMatchObject({ x: 80, y: 100, width: 160, height: 100 });
+});
+
+test("release alone can establish a reverse drag using its final coordinates", () => {
+  const { svg, value, commits } = setup();
+  fireEvent.click(screen.getByRole("button", { name: "사각형" }));
+  fireEvent.pointerDown(svg, event(140, 100)); fireEvent.pointerUp(svg, event(40, 50));
+  expect(value().objects[0]).toMatchObject({ x: 80, y: 100, width: 200, height: 100 });
+  expect(commits).toHaveBeenCalledOnce();
+});
+
 test("creation is transient until release, scales coordinates and selects the result with one undo step", () => {
   const { svg, value, editor, commits } = setup();
   fireEvent.click(screen.getByRole("button", { name: "사각형" }));
@@ -364,14 +441,16 @@ test("creation is transient until release, scales coordinates and selects the re
   fireEvent.click(screen.getByRole("button", { name: "다시 실행" })); expect(value().objects).toHaveLength(1);
 });
 
-test.each(["escape", "pointercancel", "lostpointercapture"])("%s cancels creation without a commit or history", (reason) => {
-  const { svg, value, editor } = setup();
+test.each(["escape", "pointercancel", "lostpointercapture"].flatMap((reason) => [false, true].map((drag) => ({ reason, drag }))))("$reason cancels creation (drag=$drag) without a commit or history", ({ reason, drag }) => {
+  const { svg, container, value, editor } = setup();
   fireEvent.click(screen.getByRole("button", { name: "타원" }));
-  fireEvent.pointerDown(svg, event(40, 50)); fireEvent.pointerMove(svg, event(140, 100));
+  fireEvent.pointerDown(svg, event(40, 50));
+  if (drag) fireEvent.pointerMove(svg, event(140, 100));
   if (reason === "escape") fireEvent.keyDown(svg, { key: "Escape" });
   else if (reason === "pointercancel") fireEvent.pointerCancel(svg, event(140, 100));
   else fireEvent.lostPointerCapture(svg, event(140, 100));
   fireEvent.pointerUp(svg, event(140, 100));
+  expect(creationPreview(container)).toBeNull();
   expect(value()).toEqual(blank); expect(editor.snapshot.canUndo).toBe(false);
 });
 

From ed116d81601b3c143d0b42d987e8a2715d90001d Mon Sep 17 00:00:00 2001
From: "teo.v" <66650330+developer-1px@users.noreply.github.com>
Date: Thu, 10 Sep 2026 01:23:26 +0900
Subject: [PATCH 17/20] =?UTF-8?q?feat(canvas):=20=EB=B3=80=EA=B3=BC=20?=
 =?UTF-8?q?=EB=AA=A8=EC=84=9C=EB=A6=AC=EC=9D=98=20=EA=B3=A0=EC=A0=95=20?=
 =?UTF-8?q?=EA=B8=B0=EC=A4=80=20resize=EB=A5=BC=20=EC=99=84=EC=84=B1?=
 =?UTF-8?q?=ED=95=9C=EB=8B=A4=20(#758)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

선택 박스의 모양을 유지하면서 네 변·네 모서리 resize, 반대편 고정, Shift 비율 유지, Alt 중심 기준과 최소 크기 고정을 정본 Affordance에 연결한다.

Canvas의 modifier·취소·no-op·Undo 연결과 owner 문서, Usage/Source, 회귀 검증을 포함한다. Closes #757.
---
 docs/api-reference/affordance.md              |  2 +-
 docs/public/affordance-resize.md              | 10 ++-
 packages/json-document-affordance/README.md   |  5 ++
 .../json-document-affordance/docs/resize.md   | 55 ++++++++++++
 packages/json-document-affordance/src/drag.ts | 42 +++++----
 .../tests/resize.test.ts                      | 72 ++++++++++++++++
 packages/json-document-canvas/docs/api.md     | 12 ++-
 .../json-document-canvas/src/canvas-hand.tsx  |  2 +-
 .../src/canvas-object-view.tsx                |  7 ++
 .../src/use-canvas-hand.ts                    | 35 +++++---
 .../tests/canvas-hand.test.tsx                | 86 ++++++++++++++++++-
 site/src/routes/docs/doc-pages.ts             |  3 +-
 site/tests/unit/demo-workbench.test.tsx       |  3 +
 13 files changed, 296 insertions(+), 38 deletions(-)
 create mode 100644 packages/json-document-affordance/docs/resize.md
 create mode 100644 packages/json-document-affordance/tests/resize.test.ts

diff --git a/docs/api-reference/affordance.md b/docs/api-reference/affordance.md
index 7cc3063c..090db4a4 100644
--- a/docs/api-reference/affordance.md
+++ b/docs/api-reference/affordance.md
@@ -855,7 +855,7 @@ interface RenameSessionSnapshot<Key> {
 ## `resizeAffordance`
 
 ```ts
-resizeAffordance(origin: Point, point: Point, edge: ResizeEdge, modifiers?: { readonly shiftKey?: boolean; readonly altKey?: boolean; }): AffordancePreview
+resizeAffordance(origin: Point, point: Point, edge: ResizeEdge, modifiers?: { readonly shiftKey?: boolean; readonly altKey?: boolean; }, size?: Pick<Rect, "width" | "height">): AffordancePreview
 ```
 ## `ResizeEdge`
 
diff --git a/docs/public/affordance-resize.md b/docs/public/affordance-resize.md
index eacf7a43..a2653fef 100644
--- a/docs/public/affordance-resize.md
+++ b/docs/public/affordance-resize.md
@@ -36,7 +36,7 @@ import {
 import { applyAffordance, commitAffordance, resizeAffordance } from "@interactive-os/json-document-affordance";
 
 function onPointerMove(event: PointerEvent, edge: "se") {
-  applyAffordance(resizeAffordance(origin, { x: event.clientX, y: event.clientY }, edge, event), {
+  applyAffordance(resizeAffordance(origin, { x: event.clientX, y: event.clientY }, edge, event, initialSize), {
     cursor: (cursor) => {
       event.currentTarget.style.cursor = cursor;
     },
@@ -48,7 +48,7 @@ function onPointerMove(event: PointerEvent, edge: "se") {
 
 function onPointerUp(event: PointerEvent, objectId: string, edge: "se") {
   const committed = commitAffordance(
-    resizeAffordance(origin, { x: event.clientX, y: event.clientY }, edge, event),
+    resizeAffordance(origin, { x: event.clientX, y: event.clientY }, edge, event, initialSize),
   );
   if (!committed) return;
   applyAffordance(committed, {
@@ -67,6 +67,12 @@ function onPointerUp(event: PointerEvent, objectId: string, edge: "se") {
 }
 ```
 
+`initialSize`는 press 시점의 `{ width, height }`입니다. `origin`·`point`와 크기는
+같은 좌표계를 사용합니다. 초기 크기를 제공해야 Shift가 실제 객체 비율을 유지하고
+최소 크기에서도 반대편 고정점이 보존됩니다. 네 변은 한 축을 조절하고, Shift와 함께
+잡으면 다른 축은 중심 기준으로 조절합니다. 자세한 API와 실제 Canvas Usage는
+[소유 패키지의 Resize 계약](/docs/api/affordance)에서 확인할 수 있습니다.
+
 커서는 호스트 화면 상태이고, 확정된 크기만 json-document로 갑니다.
 분할선 화살표는 APG Window Splitter와 같고, Shift는 비율, Alt는 가운데
 기준입니다.
diff --git a/packages/json-document-affordance/README.md b/packages/json-document-affordance/README.md
index 810586c9..765840c9 100644
--- a/packages/json-document-affordance/README.md
+++ b/packages/json-document-affordance/README.md
@@ -48,6 +48,11 @@ useEditing({
 `historyAffordance(snapshot).hand` exposes the typed Undo/Redo availability map
 directly. The editing runtime still owns history state and execution.
 
+`resizeAffordance(origin, point, edge, modifiers?, size?)` owns eight-direction
+anchored resizing. Supply the initial size for true Shift aspect-ratio locking,
+Alt center resizing and anchor-preserving minimum bounds. See the
+[Resize API contract](docs/resize.md) and its Canvas Usage/Source.
+
 `contentInteractionAffordance` is the canonical product-content state model.
 It distinguishes persistent selection, transient active feedback, movement,
 drop targets, and insertion positions without owning DOM or product color.
diff --git a/packages/json-document-affordance/docs/resize.md b/packages/json-document-affordance/docs/resize.md
new file mode 100644
index 00000000..54262f0f
--- /dev/null
+++ b/packages/json-document-affordance/docs/resize.md
@@ -0,0 +1,55 @@
+## Resize · 고정 기준과 초기 크기
+
+`resizeAffordance(origin, point, edge, modifiers?, size?)`는 8방향 resize의 정본입니다.
+같은 좌표계의 시작점·현재 점, `ResizeEdge`, Shift/Alt 상태와 **시작할 때의**
+`{ width, height }`를 받아 `{ hand: { type: "resize", dx, dy, dw, dh, edge }, cursor }`를
+반환합니다. 문서, DOM, pointer capture와 History를 소유하지 않습니다.
+
+| 입력 | 고정 기준과 크기 |
+| --- | --- |
+| `n` / `s` | 반대편 변 고정, 높이 조절 |
+| `e` / `w` | 반대편 변 고정, 너비 조절 |
+| `ne` / `se` / `sw` / `nw` | 반대 모서리 고정, 너비·높이 조절 |
+| Shift | 초기 너비/높이 비율 유지. 변에서는 나머지 축의 중심을 고정 |
+| Alt / Option | 객체 중심 고정, 잡은 방향의 반대편도 대칭 조절 |
+| Shift + Alt | 초기 비율과 중심 모두 고정 |
+
+`size`를 주면 결과 크기를 최소 1좌표 단위로 제한하고, 그 결과로 위치 delta를
+계산하므로 최소 크기를 지나쳐도 고정점이 밀리거나 뒤집히지 않습니다. 비율 유지 시
+두 축 모두 최소 크기를 만족합니다. 시작 크기는 유한한 양수여야 하며 아니면
+`RangeError`입니다. 1보다 작은 유효한 입력도 정지한 grab에서는 변하지 않고,
+실제 resize가 발생했을 때만 최소 크기를 적용합니다.
+
+모서리 Shift는 두 축의 상대 크기 변화 중 절댓값이 큰 값을 사용합니다.
+각 preview와 release는 같은 초기 크기에서 다시 계산해야 합니다. 이미 바뀐 preview
+크기를 다음 입력의 `size`로 쓰지 않습니다. 포인터가 정지해도 modifier가 바뀌면
+마지막 point로 재계산하고, release의 최종 point와 modifier로 결과를 확정합니다.
+`commitAffordance`는 0 delta를 null로 거르며 자체적으로 문서를 변경하지 않습니다.
+
+```ts
+import { commitAffordance, resizeAffordance } from "@interactive-os/json-document-affordance";
+
+const origin = { x: 300, y: 200 };
+const size = { width: 200, height: 100 };
+const preview = resizeAffordance(origin, { x: 340, y: 210 }, "se", { shiftKey: true }, size);
+// dx=0, dy=0, dw=40, dh=20: 반대 모서리와 2:1 비율을 유지
+const result = commitAffordance(preview);
+// Hand가 preview를 렌더링하고, release에서만 result를 Object Editing Intent로 전달
+```
+
+`size`를 생략한 기존 호출은 기존 delta-only 의미를 유지합니다. 크기를 알 수 없으므로
+최소 크기 제한이나 객체 비율을 보장하지 않으며, Shift+모서리는 x/y 이동량을 같게
+맞추는 기존 규칙입니다. 객체의 비율을 유지하려는 소비자는 반드시 초기 `size`를 넘깁니다.
+
+### Usage와 Source
+
+[Canvas Usage](/demo/canvas)와 [Canvas Widget](/widgets/canvas)는 같은 `CanvasHand`를
+사용합니다. `useCanvasHand`가 이 공개 API에 초기 객체 크기와 현재 modifier를 전달하며,
+Source에서 Hand → `resizeAffordance` → Object projection/Editing을 확인할 수 있습니다.
+네 변의 연속 hit 영역과 네 모서리는 React의 `useInteractionHandle`을 공유하고,
+pointer capture·장치별 이벤트 수명은 Web binding에 남깁니다. 선택 집합 중 primary만
+resize하며, 그룹 resize·회전·flip·snap·crop은 이 계약에 포함하지 않습니다.
+
+```live-demo
+/demo/canvas
+```
diff --git a/packages/json-document-affordance/src/drag.ts b/packages/json-document-affordance/src/drag.ts
index 207030c3..5b120b19 100644
--- a/packages/json-document-affordance/src/drag.ts
+++ b/packages/json-document-affordance/src/drag.ts
@@ -147,36 +147,42 @@ export function resizeAffordance(
   point: Point,
   edge: ResizeEdge,
   modifiers?: { readonly shiftKey?: boolean; readonly altKey?: boolean },
+  size?: Pick<Rect, "width" | "height">,
 ): AffordancePreview {
   let dx = point.x - origin.x;
   let dy = point.y - origin.y;
   const corner = edge.length === 2;
-  if (modifiers?.shiftKey && corner) {
+  if (modifiers?.shiftKey && corner && !size) {
     const mag = Math.max(Math.abs(dx), Math.abs(dy));
     dx = (dx === 0 ? 1 : Math.sign(dx)) * mag;
     dy = (dy === 0 ? 1 : Math.sign(dy)) * mag;
   }
-  let left = 0;
-  let top = 0;
-  let right = 0;
-  let bottom = 0;
-  if (edge.includes("e")) right = dx;
-  if (edge.includes("w")) left = dx;
-  if (edge.includes("s")) bottom = dy;
-  if (edge.includes("n")) top = dy;
-  if (modifiers?.altKey) {
-    if (edge.includes("e")) left = -dx;
-    if (edge.includes("w")) right = -dx;
-    if (edge.includes("s")) top = -dy;
-    if (edge.includes("n")) bottom = -dy;
+  const west = edge.includes("w"), north = edge.includes("n");
+  const horizontal = west || edge.includes("e"), vertical = north || edge.includes("s");
+  const centered = modifiers?.altKey ?? false, factor = centered ? 2 : 1;
+  let dw = (west ? -dx : horizontal ? dx : 0) * factor;
+  let dh = (north ? -dy : vertical ? dy : 0) * factor;
+  if (size) {
+    const { width, height } = size;
+    if (![width, height].every((value) => Number.isFinite(value) && value > 0)) throw new RangeError("Resize dimensions must be finite and positive.");
+    // A stationary grab is a no-op, including valid imported sub-unit objects.
+    if ((dw !== 0 || dh !== 0) && modifiers?.shiftKey) {
+      const sx = dw / width, sy = dh / height;
+      const growth = horizontal && (!vertical || Math.abs(sx) >= Math.abs(sy)) ? sx : sy;
+      const scaleDelta = Math.max(1 / width - 1, 1 / height - 1, growth);
+      dw = width * scaleDelta; dh = height * scaleDelta;
+    } else if (dw !== 0 || dh !== 0) {
+      dw = Math.max(1 - width, dw); dh = Math.max(1 - height, dh);
+    }
   }
+  // Derive translation from the constrained size so the opposite edge or center stays fixed.
   return {
     hand: {
       type: "resize",
-      dx: left,
-      dy: top,
-      dw: right - left,
-      dh: bottom - top,
+      dx: dw === 0 ? 0 : centered || !horizontal ? -dw / 2 : west ? -dw : 0,
+      dy: dh === 0 ? 0 : centered || !vertical ? -dh / 2 : north ? -dh : 0,
+      dw,
+      dh,
       edge,
     },
     cursor: interactionHandleCursor({ kind: "resize", edge }),
diff --git a/packages/json-document-affordance/tests/resize.test.ts b/packages/json-document-affordance/tests/resize.test.ts
new file mode 100644
index 00000000..3df08f67
--- /dev/null
+++ b/packages/json-document-affordance/tests/resize.test.ts
@@ -0,0 +1,72 @@
+import { describe, expect, test } from "vitest";
+import { commitAffordance, resizeAffordance, type ResizeEdge } from "../src/index.js";
+
+const size = { width: 200, height: 100 };
+const origin = { x: 0, y: 0 };
+const edges = ["n", "ne", "e", "se", "s", "sw", "w", "nw"] as const;
+const modes = [
+  { shiftKey: false, altKey: false }, { shiftKey: true, altKey: false },
+  { shiftKey: false, altKey: true }, { shiftKey: true, altKey: true },
+];
+
+function bounds(edge: ResizeEdge, point: typeof origin, modifiers = modes[0]!, initial = size) {
+  const result = resizeAffordance(origin, point, edge, modifiers, initial);
+  expect(result.cursor).toBe(`${edge}-resize`);
+  const hand = result.hand;
+  if (hand?.type !== "resize") throw new Error("Expected a resize result");
+  return { x: hand.dx, y: hand.dy, width: initial.width + hand.dw, height: initial.height + hand.dh };
+}
+
+describe("size-aware Resize", () => {
+  test.each([
+    ["n", 0, -10, 200, 110], ["ne", 40, -10, 240, 110],
+    ["e", 40, 0, 240, 100], ["se", 40, 10, 240, 110],
+    ["s", 0, 10, 200, 110], ["sw", -40, 10, 240, 110],
+    ["w", -40, 0, 240, 100], ["nw", -40, -10, 240, 110],
+  ] as const)("%s resizes only its axes and fixes the opposite edge/corner", (edge, dx, dy, width, height) => {
+    expect(bounds(edge, { x: dx || 75, y: dy || 75 })).toEqual({
+      x: edge.includes("w") ? 200 - width : 0, y: edge.includes("n") ? 100 - height : 0, width, height,
+    });
+  });
+
+  test.each(edges)("%s uses the initial non-square ratio and Alt fixes the center", (edge) => {
+    const x = edge.includes("w") ? -40 : edge.includes("e") ? 40 : 0;
+    const y = edge.includes("n") ? -10 : edge.includes("s") ? 10 : 0;
+    const width = x === 0 ? 220 : 240, height = width / 2;
+    const resized = bounds(edge, { x, y }, { shiftKey: true, altKey: false });
+    expect(resized.width).toBeCloseTo(width); expect(resized.height).toBeCloseTo(height);
+    expect(resized.x).toBeCloseTo(x === 0 ? (200 - width) / 2 : x < 0 ? 200 - width : 0);
+    expect(resized.y).toBeCloseTo(y === 0 ? (100 - height) / 2 : y < 0 ? 100 - height : 0);
+    for (const shiftKey of [false, true]) {
+      const centered = bounds(edge, { x, y }, { shiftKey, altKey: true });
+      expect(centered.x + centered.width / 2).toBeCloseTo(100);
+      expect(centered.y + centered.height / 2).toBeCloseTo(50);
+      expect(centered.width).toBeCloseTo(shiftKey ? 200 + (width - 200) * 2 : 200 + Math.abs(x) * 2);
+      expect(centered.height).toBeCloseTo(shiftKey ? centered.width / 2 : 100 + Math.abs(y) * 2);
+    }
+  });
+
+  test.each(edges.flatMap((edge) => modes.map((mode) => ({ edge, ...mode }))))("$edge clamps without moving its anchor (Shift=$shiftKey Alt=$altKey)", ({ edge, shiftKey, altKey }) => {
+    const horizontal = edge.includes("e") || edge.includes("w"), vertical = edge.includes("n") || edge.includes("s");
+    const result = bounds(edge, { x: edge.includes("w") ? 1000 : -1000, y: edge.includes("n") ? 1000 : -1000 }, { shiftKey, altKey });
+    expect(result.width).toBeCloseTo(shiftKey ? 2 : horizontal ? 1 : 200);
+    expect(result.height).toBeCloseTo(shiftKey || vertical ? 1 : 100);
+    expect(result.x + result.width * (altKey || !horizontal ? 0.5 : edge.includes("w") ? 1 : 0)).toBeCloseTo(altKey || !horizontal ? 100 : edge.includes("w") ? 200 : 0);
+    expect(result.y + result.height * (altKey || !vertical ? 0.5 : edge.includes("n") ? 1 : 0)).toBeCloseTo(altKey || !vertical ? 50 : edge.includes("n") ? 100 : 0);
+  });
+
+  test.each(edges)("%s keeps a stationary input a no-op in every modifier mode", (edge) => {
+    for (const mode of modes) expect(commitAffordance(resizeAffordance(origin, origin, edge, mode, size))).toBeNull();
+  });
+
+  test("a tall object's ratio, shrinking and initially sub-unit dimensions remain well-defined", () => {
+    expect(bounds("se", { x: -10, y: -80 }, { shiftKey: true, altKey: false }, { width: 100, height: 400 })).toEqual({ x: 0, y: 0, width: 80, height: 320 });
+    const small = { width: 0.5, height: 0.25 };
+    expect(bounds("nw", origin, modes[0], small)).toEqual({ x: 0, y: 0, ...small });
+    expect(bounds("nw", { x: 10, y: 10 }, modes[0], small)).toEqual({ x: -0.5, y: -0.75, width: 1, height: 1 });
+  });
+
+  test.each([0, -1, Infinity, NaN])("rejects invalid initial dimensions (%s)", (width) => {
+    expect(() => resizeAffordance(origin, origin, "e", undefined, { width, height: 100 })).toThrow(RangeError);
+  });
+});
diff --git a/packages/json-document-canvas/docs/api.md b/packages/json-document-canvas/docs/api.md
index 9e6d4e40..e9e97c1f 100644
--- a/packages/json-document-canvas/docs/api.md
+++ b/packages/json-document-canvas/docs/api.md
@@ -37,7 +37,7 @@ Host: 한 장 fixture, 크기·색상 정책, 레이아웃
   drag는 marquee replace, Shift+marquee는 add입니다. Mod+A를 반복해도 전체 선택을 유지합니다.
   선택된 객체 press는 집합을 유지하고 release까지 drag가 없으면 단일 선택으로 바꿉니다.
 - 선택된 객체를 끌면 집합 전체가 같은 delta로 이동합니다. 마지막 객체가 위에 표시됩니다.
-  선택 윤곽은 모두 그리지만 네 모서리 resize handles는 primary 하나에만 붙습니다.
+  선택 윤곽은 모두 그리지만 네 변·네 모서리 resize targets는 primary 하나에만 붙습니다.
   Delete는 집합 전체를 한 번 삭제하며 primary resize/text 편집은 기존 선택 집합을 보존합니다.
   Focus만으로 선택하지 않으며, focused 객체에서 Space/Shift+Space로 선택/toggle합니다.
   focused 객체의 Enter는 그 객체를 선택하고 글자라면 편집합니다. 슬라이드 자체의
@@ -51,6 +51,14 @@ Host: 한 장 fixture, 크기·색상 정책, 레이아웃
   Mod+D 또는 아이콘 툴바의 복제는 24단위 offset으로 복제하고 사본 집합·대응 primary를 선택합니다.
 - 방향키는 선택 집합을 1단위, Shift+방향키는 10단위 이동합니다. 수정 키 없는 입력만
   처리하며 text/JSON 입력과 IME의 키보드 소유권은 보존합니다.
+- 네 모서리 손잡이는 기존 사각 모양을 유지하며 네 변 전체에도 보이지 않는 resize 영역이
+  있습니다. 방향 커서로 구분하며 모서리가 변보다 우선합니다. 변은 한 축만 조절하고 반대편
+  변을, 모서리는 반대 모서리를 고정합니다. Shift는 초기 객체 비율을 유지하고, 변에서 비율을
+  유지할 때 다른 축은 중심 기준입니다. Alt/Option은 중심 기준, Shift+Alt는 중심·비율을
+  함께 고정합니다. 포인터가 멈춰 있어도 modifier 전환을 반영합니다. 최소 1 문서 단위까지
+  줄여도 고정점은 움직이지 않고 뒤집히지 않습니다. 정지한 grab은 크기·History를 바꾸지 않습니다.
+  [Resize 정본 계약](/docs/api/affordance)을 소비하며, 글자 크기·path 정규화 좌표·이미지 원본은
+  그대로 두고 객체 상자만 조절합니다.
 - 이동·resize·생성 중에는 문서를 변경하지 않습니다. pointerup의 최종 좌표로 한 번
   commit합니다. Escape, pointercancel, capture loss, 외부 문서 변경, unmount는 preview를
   버립니다. 다른 pointer의 release는 조작을 완료하지 못합니다. marquee 선택 preview도
@@ -78,7 +86,7 @@ text/JSON textarea의 native clipboard는 가로채지 않습니다.
 줄바꿈·Unicode를 그대로 보존합니다. PNG/JPEG/WebP는 문서 내부 base64 image 객체로 넣습니다.
 기본은 한 paste당 최대 4개, 파일당 10 MiB, decode 후 이미지당 16,000,000픽셀입니다.
 이미지는 비율을 유지해 슬라이드 75% 상자에 맞추고 확대하지 않습니다. 후속 resize는 일반
-객체와 같은 자유 상자 변환입니다. `policy.files`와 `maxImagePixels`로 입력 정책을 지정할 수
+객체와 같은 상자 변환이며 Shift로 초기 비율을 유지할 수 있습니다. `policy.files`와 `maxImagePixels`로 입력 정책을 지정할 수
 있지만 Object 모델이 지원하지 않는 이미지 표현까지 허용되는 것은 아닙니다.
 
 HTML은 Web의 inert parser와 이미지 준비 API를 사용합니다. 포함된 PNG/JPEG/WebP data URL과
diff --git a/packages/json-document-canvas/src/canvas-hand.tsx b/packages/json-document-canvas/src/canvas-hand.tsx
index b7795f98..5664db1a 100644
--- a/packages/json-document-canvas/src/canvas-hand.tsx
+++ b/packages/json-document-canvas/src/canvas-hand.tsx
@@ -54,7 +54,7 @@ export function CanvasHand(props: CanvasHandProps) {
         {hand.tool === "select" && hand.objects.filter((object) => selectedKeys.has(object.id)).map((object) =>
           <rect key={object.id} data-selection-outline={object.id} x={object.x} y={object.y} width={object.width} height={object.height} fill="none" stroke="rgb(var(--color-border-accent))" strokeWidth={object.id === selected?.id ? 2 : 1} pointerEvents="none" />)}
         {selected && hand.tool === "select" && <g>
-          {!hand.draft && (["nw", "ne", "se", "sw"] as const).map((edge) => <CanvasResizeTarget key={edge} object={selected} edge={edge} onHandle={(interaction, event) => hand.interaction(interaction, event, selected, "resize", edge)} />)}
+          {!hand.draft && (["n", "e", "s", "w", "nw", "ne", "se", "sw"] as const).map((edge) => <CanvasResizeTarget key={edge} object={selected} edge={edge} onHandle={(interaction, event) => hand.interaction(interaction, event, selected, "resize", edge)} />)}
         </g>}
         {hand.marquee && <rect data-canvas-marquee="" {...hand.marquee} fill="rgb(var(--color-border-accent) / 0.08)" stroke="rgb(var(--color-border-accent))" pointerEvents="none" />}
         {selected?.kind === "text" && hand.draft?.id === selected.id && <CanvasTextInput object={selected} text={hand.draft.text} onChange={hand.changeText}
diff --git a/packages/json-document-canvas/src/canvas-object-view.tsx b/packages/json-document-canvas/src/canvas-object-view.tsx
index 2783a651..2b74b057 100644
--- a/packages/json-document-canvas/src/canvas-object-view.tsx
+++ b/packages/json-document-canvas/src/canvas-object-view.tsx
@@ -55,6 +55,13 @@ export function CanvasResizeTarget(props: {
   const { object, edge } = props;
   const x = object.x + (edge.includes("w") ? 0 : edge.includes("e") ? object.width : object.width / 2);
   const y = object.y + (edge.includes("n") ? 0 : edge.includes("s") ? object.height : object.height / 2);
+  if (edge.length === 1) {
+    const horizontal = edge === "n" || edge === "s";
+    return <rect {...binding.handleProps} data-resize-edge={edge}
+      x={horizontal ? object.x : x - 6} y={horizontal ? y - 6 : object.y}
+      width={horizontal ? object.width : 12} height={horizontal ? 12 : object.height}
+      fill="transparent" style={{ cursor: binding.cursor }} />;
+  }
   return <rect {...binding.handleProps} data-resize-edge={edge} x={x - 6} y={y - 6} width={12} height={12}
     fill="rgb(var(--color-background-canvas))" stroke="rgb(var(--color-border-accent))" strokeWidth={2} style={{ cursor: binding.cursor }} />;
 }
diff --git a/packages/json-document-canvas/src/use-canvas-hand.ts b/packages/json-document-canvas/src/use-canvas-hand.ts
index 77f1b761..4ab17ce9 100644
--- a/packages/json-document-canvas/src/use-canvas-hand.ts
+++ b/packages/json-document-canvas/src/use-canvas-hand.ts
@@ -1,5 +1,5 @@
 import { useEffect, useMemo, useReducer, useRef, useState, type ClipboardEvent, type KeyboardEvent, type PointerEvent } from "react";
-import { createGestureSession, createPlaneSelectProfile, resizeAffordance, type InteractionHandleEvent, type PlaneSelectProfile, type PlaneSelectSelection, type ResizeEdge } from "@interactive-os/json-document-affordance";
+import { commitAffordance, createGestureSession, createPlaneSelectProfile, resizeAffordance, type InteractionHandleEvent, type PlaneSelectProfile, type PlaneSelectSelection, type ResizeEdge } from "@interactive-os/json-document-affordance";
 import { assertCanvasDocument, createCanvasObject, createCanvasPath, parseCanvasDocument, transformObject, type CanvasDocument, type CanvasObject, type CanvasObjectKind, type ObjectPoint } from "@interactive-os/json-document-object-document";
 import type { EditingResult, ObjectEditor, ObjectIntent, ObjectSelection } from "@interactive-os/json-document-editing";
 import { useEditingSnapshot } from "@interactive-os/json-document-react";
@@ -17,7 +17,8 @@ export interface CanvasCreationStyle {
 type Gesture = { readonly base: CanvasDocument } & (
   | { readonly type: "create"; readonly tool: Exclude<CanvasObjectKind, "path" | "image">; readonly start: ObjectPoint; readonly point: ObjectPoint; readonly dragged: boolean }
   | { readonly type: "draw"; readonly points: ReadonlyArray<ObjectPoint> }
-  | { readonly type: "resize"; readonly object: CanvasObject; readonly start: ObjectPoint; readonly point: ObjectPoint; readonly edge: ResizeEdge }
+  | { readonly type: "resize"; readonly object: CanvasObject; readonly start: ObjectPoint; readonly point: ObjectPoint; readonly edge: ResizeEdge;
+      readonly pointerId: number; readonly shiftKey: boolean; readonly altKey: boolean; readonly selection: ObjectSelection }
 );
 type TextDraft = { readonly id: string; readonly text: string; readonly base: CanvasDocument };
 
@@ -65,7 +66,8 @@ export function useCanvasHand(editor: ObjectEditor, style: CanvasCreationStyle,
   useEffect(() => {
     // A replacement/external edit invalidates previews, even when an ID survives.
     const release = editor.subscribe((next) => {
-      if ((gestures.getActive() && gestures.getActive()!.base !== next.value)
+      const active = gestures.getActive();
+      if ((active && (active.base !== next.value || (active.type === "resize" && active.selection !== next.selection)))
         || (selecting.current && (selecting.current.base !== next.value || selecting.current.selection !== next.selection))
         || (draft.current && draft.current.base !== next.value)) cancel();
     });
@@ -153,9 +155,9 @@ export function useCanvasHand(editor: ObjectEditor, style: CanvasCreationStyle,
   }
 
   function transform(gesture: Extract<Gesture, { type: "resize" }>) {
-    const result = resizeAffordance(gesture.start, gesture.point, gesture.edge);
-    const hand = result.hand;
-    return hand?.type === "translate" || hand?.type === "resize" ? hand : { dx: 0, dy: 0 };
+    const result = commitAffordance(resizeAffordance(gesture.start, gesture.point, gesture.edge, gesture, gesture.object));
+    const hand = result?.hand;
+    return hand?.type === "resize" ? hand : { dx: 0, dy: 0 };
   }
 
   function commitGesture() {
@@ -172,7 +174,7 @@ export function useCanvasHand(editor: ObjectEditor, style: CanvasCreationStyle,
       }
     } else {
       const delta = transform(active);
-      dispatch({ type: "object.resize", objectIds: [active.object.id], dx: delta.dx, dy: delta.dy, dw: "dw" in delta ? delta.dw : 0, dh: "dh" in delta ? delta.dh : 0 });
+      if ("dw" in delta) dispatch({ type: "object.resize", objectIds: [active.object.id], dx: delta.dx, dy: delta.dy, dw: delta.dw, dh: delta.dh });
     }
   }
 
@@ -205,7 +207,10 @@ export function useCanvasHand(editor: ObjectEditor, style: CanvasCreationStyle,
   function interaction(interaction: InteractionHandleEvent, event: PointerEvent<SVGElement>, object: CanvasObject, type: "drag" | "resize", edge: ResizeEdge = "se") {
     if (interaction.phase === "cancel") {
       if (type === "drag" && selecting.current?.key === object.id && selecting.current.pointerId === event.pointerId) { profile.cancel("pointer-cancel"); selecting.current = null; redraw(); }
-      else if (type === "resize") gestures.cancel("pointer-cancel");
+      else if (type === "resize") {
+        const active = gestures.getActive();
+        if (active?.type === "resize" && active.pointerId === event.pointerId && active.edge === edge && active.object.id === object.id) gestures.cancel("pointer-cancel");
+      }
       return;
     }
     const point = eventPoint(event);
@@ -214,7 +219,8 @@ export function useCanvasHand(editor: ObjectEditor, style: CanvasCreationStyle,
       commitText(); cancel(); surface.current?.focus();
       if (type === "drag") { beginSelect(point, object.id, event); return; }
       const latest = current().objects.find((item) => item.id === object.id);
-      if (latest) gestures.begin({ type, object: latest, start: point, point, edge, base: current() });
+      if (latest) gestures.begin({ type, object: latest, start: point, point, edge, base: current(), selection: editor.snapshot.selection,
+        pointerId: event.pointerId, shiftKey: event.shiftKey, altKey: event.altKey });
     } else {
       if (type === "drag") {
         if (selecting.current?.key !== object.id || selecting.current.pointerId !== event.pointerId) return;
@@ -222,8 +228,8 @@ export function useCanvasHand(editor: ObjectEditor, style: CanvasCreationStyle,
         return;
       }
       const active = gestures.getActive();
-      if (!active || active.type !== type || active.object.id !== object.id) return;
-      gestures.preview({ ...active, point });
+      if (!active || active.type !== type || active.object.id !== object.id || active.pointerId !== event.pointerId || active.edge !== edge) return;
+      gestures.preview({ ...active, point, shiftKey: event.shiftKey, altKey: event.altKey });
       if (interaction.phase === "commit") commitGesture();
     }
   }
@@ -240,7 +246,12 @@ export function useCanvasHand(editor: ObjectEditor, style: CanvasCreationStyle,
   }
 
   function updateModifiers(event: KeyboardEvent) {
-    if (!event.nativeEvent.isComposing && !isWebEditableTarget(event.target) && profile.updateModifiers(event)) redraw();
+    if (event.nativeEvent.isComposing || isWebEditableTarget(event.target)) return;
+    if (profile.updateModifiers(event)) redraw();
+    const active = gestures.getActive();
+    if (active?.type === "resize" && (active.shiftKey !== event.shiftKey || active.altKey !== event.altKey)) {
+      gestures.preview({ ...active, shiftKey: event.shiftKey, altKey: event.altKey });
+    }
   }
 
   function keyDown(event: KeyboardEvent) {
diff --git a/packages/json-document-canvas/tests/canvas-hand.test.tsx b/packages/json-document-canvas/tests/canvas-hand.test.tsx
index 5174ba31..3942b152 100644
--- a/packages/json-document-canvas/tests/canvas-hand.test.tsx
+++ b/packages/json-document-canvas/tests/canvas-hand.test.tsx
@@ -291,7 +291,7 @@ test.each(["Escape", "pointercancel", "lostpointercapture"])("%s cancels marquee
 test("only primary resizes and edits text while retaining the selected set", () => {
   const { container, svg, editor, value, commits } = setup(populated);
   act(() => { editor.dispatch({ type: "selection.set", objectIds: ["a", "b"], primaryKey: "a" }); });
-  expect(container.querySelectorAll("[data-resize-edge]")).toHaveLength(4);
+  expect(container.querySelectorAll("[data-resize-edge]")).toHaveLength(8);
   const handle = container.querySelector('[data-resize-edge="se"]')!;
   fireEvent.pointerDown(handle, event(100, 100)); fireEvent.pointerMove(window, event(120, 115)); fireEvent.pointerUp(window, event(120, 115));
   expect(value().objects[0]!.width).toBeCloseTo(140); expect(value().objects[0]!.height).toBeCloseTo(130);
@@ -471,6 +471,90 @@ test("move and resize share preview geometry, cancel safely and commit exactly o
   expect(value().objects[0]).toMatchObject({ width: 260, height: 160 }); expect(commits).toHaveBeenCalledTimes(2);
 });
 
+test.each([
+  ["n", 80, 80, 200, 120], ["e", 80, 100, 240, 100],
+  ["s", 80, 100, 200, 80], ["w", 120, 100, 160, 100],
+] as const)("%s offers an invisible full-edge target and an anchored single-axis resize", (edge, x, y, width, height) => {
+  const { svg, container, value, commits } = setup(); rectangle(svg); commits.mockClear();
+  const handle = container.querySelector(`[data-resize-edge="${edge}"]`)!;
+  expect(handle).not.toBeNull(); expect(handle.getAttribute("fill")).toBe("transparent");
+  expect(handle.getAttribute("stroke")).toBeNull(); expect((handle as SVGElement).style.cursor).toBe(`${edge}-resize`);
+  expect(Number(handle.getAttribute(edge === "n" || edge === "s" ? "width" : "height"))).toBe(edge === "n" || edge === "s" ? 200 : 100);
+  expect([...container.querySelectorAll("[data-resize-edge]")].slice(-4).map((node) => node.getAttribute("data-resize-edge"))).toEqual(["nw", "ne", "se", "sw"]);
+  const before = value();
+  fireEvent.pointerDown(handle, event(80, 80)); fireEvent.pointerMove(window, event(100, 70));
+  const preview = container.querySelector("[data-canvas-object]")!;
+  expect(["x", "y", "width", "height"].map((name) => Number(preview.getAttribute(name)))).toEqual([x, y, width, height]);
+  expect(value()).toBe(before); expect(commits).not.toHaveBeenCalled();
+  fireEvent.pointerUp(window, event(100, 70)); expect(value().objects[0]).toMatchObject({ x, y, width, height });
+  expect(commits).toHaveBeenCalledOnce();
+  fireEvent.keyDown(svg, { key: "z", metaKey: true }); expect(value()).toEqual(before);
+  fireEvent.keyDown(svg, { key: "z", metaKey: true, shiftKey: true }); expect(value().objects[0]).toMatchObject({ x, y, width, height });
+});
+
+test("resize switches Shift/Alt live and commits the release coordinates and modifiers once", () => {
+  const { svg, container, value, commits } = setup(); rectangle(svg); commits.mockClear();
+  const handle = container.querySelector('[data-resize-edge="se"]')!;
+  const target = container.querySelector("[data-canvas-object]")!;
+  const bounds = () => ["x", "y", "width", "height"].map((key) => Number(target.getAttribute(key)));
+  fireEvent.pointerDown(handle, event(140, 100)); fireEvent.pointerMove(window, event(160, 105));
+  expect(bounds()).toEqual([80, 100, 240, 110]);
+  fireEvent.keyDown(svg, { key: "Shift", shiftKey: true }); expect(bounds()).toEqual([80, 100, 240, 120]);
+  fireEvent.keyDown(svg, { key: "Alt", shiftKey: true, altKey: true }); expect(bounds()).toEqual([40, 80, 280, 140]);
+  fireEvent.keyUp(svg, { key: "Shift", altKey: true }); expect(bounds()).toEqual([40, 90, 280, 120]);
+  fireEvent.keyUp(svg, { key: "Alt" }); expect(bounds()).toEqual([80, 100, 240, 110]);
+  expect(commits).not.toHaveBeenCalled();
+  fireEvent.pointerUp(window, { ...event(170, 110), shiftKey: true, altKey: true });
+  expect(value().objects[0]).toMatchObject({ x: 20, y: 70, width: 320, height: 160 });
+  expect(commits).toHaveBeenCalledOnce(); expect(value().objects).toHaveLength(1);
+});
+
+test.each(["rectangle", "ellipse", "text", "path", "image"] as const)("%s uses the same west-edge clamp without changing its content", (kind) => {
+  const object = { id: "a", x: 100, y: 100, width: 200, height: 100, color: "blue", label: "Content", kind,
+    ...(kind === "text" ? { fontSize: 24 } : kind === "path" ? { points: [{ x: 0, y: 0 }, { x: 1, y: 1 }], strokeWidth: 3 } : kind === "image" ? { source: "data:image/png;base64,AQID" } : {}) } as CanvasDocument["objects"][number];
+  const { container, value } = setup({ ...blank, objects: [object] });
+  const handle = container.querySelector('[data-resize-edge="w"]')!;
+  fireEvent.pointerDown(handle, event(50, 70)); fireEvent.pointerMove(window, event(250, 200));
+  expect(container.querySelector("[data-canvas-object]")?.getAttribute("x")).toBe("299");
+  fireEvent.pointerUp(window, event(250, 200));
+  expect(value().objects[0]).toEqual({ ...object, x: 299, width: 1 });
+});
+
+test.each(["Escape", "pointercancel", "lostpointercapture", "document", "selection", "unmount"])("resize cancellation (%s) discards preview and ignores stale release", (reason) => {
+  const { container, svg, editor, source, value, commits, unmount } = setup(populated);
+  const handle = container.querySelector('[data-resize-edge="e"]')!;
+  fireEvent.pointerDown(handle, event(100, 75)); fireEvent.pointerMove(window, event(150, 80));
+  if (reason === "Escape") fireEvent.keyDown(svg, { key: "Escape" });
+  else if (reason === "pointercancel") fireEvent.pointerCancel(window, event(150, 80));
+  else if (reason === "lostpointercapture") fireEvent.lostPointerCapture(handle, event(150, 80));
+  else if (reason === "document") act(() => { source.commit([{ op: "replace", path: "/objects/0/color", value: "red" }]); });
+  else if (reason === "selection") act(() => { editor.dispatch({ type: "selection.set", objectIds: ["b"] }); });
+  else unmount();
+  commits.mockClear(); fireEvent.pointerUp(window, event(180, 90));
+  expect(value().objects[0]!.width).toBe(100); expect(commits).not.toHaveBeenCalled();
+  if (reason !== "unmount") expect(container.querySelector('[data-canvas-object="a"]')?.getAttribute("width")).toBe("100");
+});
+
+test("resize ignores foreign pointers and a return to the original bounds adds no History", () => {
+  const { container, editor, value, commits } = setup(populated);
+  const handle = container.querySelector('[data-resize-edge="n"]')!;
+  fireEvent.pointerDown(handle, event(75, 50));
+  fireEvent.pointerMove(window, event(100, 100, 9)); fireEvent.pointerUp(window, event(100, 100, 9));
+  expect(container.querySelector('[data-canvas-object="a"]')?.getAttribute("height")).toBe("100");
+  fireEvent.pointerMove(window, event(75, 30)); fireEvent.pointerUp(window, event(75, 50));
+  expect(value()).toEqual(populated); expect(commits).not.toHaveBeenCalled(); expect(editor.snapshot.canUndo).toBe(false);
+});
+
+test("an imported sub-unit object does not grow on a stationary resize grab", () => {
+  const object = { ...populated.objects[1]!, width: 0.5, height: 0.25 };
+  const { container, value, commits, editor } = setup({ ...blank, objects: [object] });
+  const handle = container.querySelector('[data-resize-edge="nw"]')!;
+  fireEvent.pointerDown(handle, event(150, 50)); fireEvent.pointerUp(window, event(150, 50));
+  expect(value().objects[0]).toEqual(object); expect(editor.snapshot.canUndo).toBe(false); expect(commits).not.toHaveBeenCalled();
+  fireEvent.pointerDown(handle, event(150, 50)); fireEvent.pointerUp(window, event(200, 100));
+  expect(value().objects[0]).toMatchObject({ x: 299.5, y: 99.25, width: 1, height: 1 });
+});
+
 test("text draft supports IME, cancellation and one commit without capturing native editing shortcuts", () => {
   const { svg, value, commits, container } = setup();
   fireEvent.click(screen.getByRole("button", { name: "글자" }));
diff --git a/site/src/routes/docs/doc-pages.ts b/site/src/routes/docs/doc-pages.ts
index 88f5b807..6f62e9af 100644
--- a/site/src/routes/docs/doc-pages.ts
+++ b/site/src/routes/docs/doc-pages.ts
@@ -12,6 +12,7 @@ import zodApiMarkdown from "../../../../docs/api-reference/zod.md?raw";
 import tanStackTableApiMarkdown from "../../../../docs/api-reference/tanstack-table.md?raw";
 import affordanceApiMarkdown from "../../../../docs/api-reference/affordance.md?raw";
 import planeSelectContractMarkdown from "../../../../packages/json-document-affordance/docs/plane-select.md?raw";
+import resizeContractMarkdown from "../../../../packages/json-document-affordance/docs/resize.md?raw";
 import objectSelectionContractMarkdown from "../../../../packages/json-document-editing/docs/object-selection.md?raw";
 import uiPrimitivesApiMarkdown from "../../../../docs/api-reference/ui-primitives-react.md?raw";
 import animationApiMarkdown from "../../../../docs/api-reference/animation-react.md?raw";
@@ -194,7 +195,7 @@ export const docPages = {
   connectorA2ui: docPage("/docs/connector-a2ui", connectorA2uiMarkdown),
   zodApi: docPage("/docs/api/zod", zodApiMarkdown),
   tanStackTableApi: docPage("/docs/api/tanstack-table", tanStackTableApiMarkdown),
-  affordanceApi: docPage("/docs/api/affordance", `${planeSelectContractMarkdown}\n\n${affordanceApiMarkdown}`),
+  affordanceApi: docPage("/docs/api/affordance", `${planeSelectContractMarkdown}\n\n${resizeContractMarkdown}\n\n${affordanceApiMarkdown}`),
   uiPrimitivesApi: docPage("/docs/api/ui-primitives-react", uiPrimitivesApiMarkdown),
   animationApi: docPage("/docs/api/animation-react", animationApiMarkdown),
   markdownReactApi: docPage("/docs/api/markdown-react", markdownReactApiMarkdown),
diff --git a/site/tests/unit/demo-workbench.test.tsx b/site/tests/unit/demo-workbench.test.tsx
index 6cf55958..42427305 100644
--- a/site/tests/unit/demo-workbench.test.tsx
+++ b/site/tests/unit/demo-workbench.test.tsx
@@ -360,8 +360,11 @@ describe("Demo definition and source discovery", () => {
         "packages/json-document-object-document/src/object-projection.ts",
         "packages/json-document-editing/src/object.ts",
         "packages/json-document-affordance/src/gesture-session.ts",
+        "packages/json-document-affordance/src/drag.ts",
         "packages/json-document-react/src/editing-snapshot.ts",
       ]));
+      const hand = (await discoverDemoSources(entry)).find((file) => file.path === "packages/json-document-canvas/src/use-canvas-hand.ts")!;
+      expect(await hand.load()).toContain("resizeAffordance(gesture.start, gesture.point, gesture.edge, gesture, gesture.object)");
     }
   });
 

From d8502c9c57ad3b0cba42c19c1faf678ee01a5c0a Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E1=84=8B=E1=85=B2=E1=84=8B=E1=85=AD=E1=86=BC=E1=84=90?=
 =?UTF-8?q?=E1=85=A2?= <teo.v@navercorp.com>
Date: Thu, 10 Sep 2026 02:02:14 +0900
Subject: [PATCH 18/20] =?UTF-8?q?feat(canvas):=20=EC=84=A0=ED=83=9D=20?=
 =?UTF-8?q?=EC=8A=A4=ED=83=80=EC=9D=BC=20=ED=8E=B8=EC=A7=91=EC=9D=84=20?=
 =?UTF-8?q?=EC=A0=95=EB=B3=B8=20Object=20=EA=B3=84=EC=95=BD=EC=9C=BC?=
 =?UTF-8?q?=EB=A1=9C=20=EC=97=B0=EA=B2=B0=ED=95=9C=EB=8B=A4?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Refs #759
---
 audits/document-types.json                    | 26 +++++-
 docs/api-reference/canvas.md                  |  2 +-
 docs/api-reference/editing.md                 |  1 +
 docs/api-reference/object-document.md         | 37 +++++++-
 docs/api-reference/ui-primitives-react.md     |  2 +-
 docs/public/intent.md                         |  1 +
 docs/public/object.md                         |  2 +-
 packages/json-document-canvas/docs/api.md     | 25 ++++-
 .../json-document-canvas/src/canvas-hand.tsx  |  2 +
 .../src/canvas-object-view.tsx                | 12 ++-
 .../src/canvas-style-controls.tsx             | 67 +++++++++++++
 .../src/use-canvas-hand.ts                    |  6 +-
 .../tests/canvas-hand.test.tsx                | 93 +++++++++++++++++++
 .../docs/object-selection.md                  | 18 ++++
 packages/json-document-editing/src/object.ts  |  6 +-
 .../tests/object-style.test.ts                | 66 +++++++++++++
 .../json-document-object-document/docs/api.md | 43 ++++++++-
 .../src/index.ts                              |  1 +
 .../src/object-model.ts                       |  4 +-
 .../src/object-operation.ts                   |  9 ++
 .../src/object-style.ts                       | 50 ++++++++++
 .../src/object-validation.ts                  |  3 +
 .../tests/object-style.test.ts                | 68 ++++++++++++++
 .../docs/popover.md                           | 22 +++++
 .../package.json                              |  2 +-
 .../src/presentations.tsx                     | 23 ++++-
 .../tests/primitives.test.tsx                 | 19 ++++
 site/src/app/index.css                        |  4 +
 .../routes/canvas-demo/CanvasDemoRoute.tsx    |  2 +-
 site/src/routes/docs/doc-pages.ts             |  3 +-
 .../src/shared/demo-workbench/demo-sources.ts | 10 ++
 site/tailwind.config.cjs                      |  1 +
 site/tests/unit/demo-workbench.test.tsx       |  6 ++
 33 files changed, 604 insertions(+), 32 deletions(-)
 create mode 100644 packages/json-document-canvas/src/canvas-style-controls.tsx
 create mode 100644 packages/json-document-editing/tests/object-style.test.ts
 create mode 100644 packages/json-document-object-document/src/object-style.ts
 create mode 100644 packages/json-document-object-document/tests/object-style.test.ts
 create mode 100644 packages/json-document-ui-primitives-react/docs/popover.md

diff --git a/audits/document-types.json b/audits/document-types.json
index 057820f9..422acb3b 100644
--- a/audits/document-types.json
+++ b/audits/document-types.json
@@ -32,15 +32,17 @@
     },
     "object": {
       "why": "캔버스 object는 identity, geometry와 presentation 값을 하나의 의미 단위로 유지해야 하기 때문입니다.",
-      "does": "object의 위치·크기·색상 모델을 정의하고 translate·resize·fill 같은 공간 연산의 기반을 제공합니다.",
-      "schema": "interface DocumentObject {\n  readonly id: string;\n  readonly label: string;\n  readonly x: number;\n  readonly y: number;\n  readonly width: number;\n  readonly height: number;\n  readonly color: string;\n}\n\ninterface ObjectDocument {\n  readonly objects: ReadonlyArray<DocumentObject>;\n}\n\ntype CanvasObject = DocumentObject & (\n  | { kind: \"text\"; fontSize: number }\n  | { kind: \"rectangle\" | \"ellipse\" }\n  | { kind: \"path\"; points: ReadonlyArray<{ x: number; y: number }>; strokeWidth: number }\n  | { kind: \"image\"; source: string }\n);\ninterface CanvasDocument extends ObjectDocument {\n  readonly profile: \"canvas/1\";\n  readonly width: number; readonly height: number;\n  readonly objects: ReadonlyArray<CanvasObject>;\n}",
+      "does": "object의 위치·크기·스타일 모델을 정의하고 translate·resize·fill·style의 원자적 연산을 제공합니다.",
+      "schema": "interface DocumentObject {\n  readonly id: string;\n  readonly label: string;\n  readonly x: number;\n  readonly y: number;\n  readonly width: number;\n  readonly height: number;\n  readonly color: string;\n}\n\ninterface ObjectDocument {\n  readonly objects: ReadonlyArray<DocumentObject>;\n}\n\ntype CanvasObject = DocumentObject & (\n  | { kind: \"text\"; fontSize: number; fontWeight?: 400 | 700; textAlign?: \"left\" | \"center\" | \"right\" }\n  | { kind: \"rectangle\" | \"ellipse\"; strokeColor?: string; strokeWidth?: number }\n  | { kind: \"path\"; points: ReadonlyArray<{ x: number; y: number }>; strokeWidth: number }\n  | { kind: \"image\"; source: string }\n);\ninterface CanvasDocument extends ObjectDocument {\n  readonly profile: \"canvas/1\";\n  readonly width: number; readonly height: number;\n  readonly objects: ReadonlyArray<CanvasObject>;\n}",
       "fields": [
         { "name": "objects", "description": "같은 공간에서 배치·선택되는 object의 ordered collection입니다." },
         { "name": "objects[].id", "description": "selection, transform과 clipboard가 object를 안정적으로 참조하는 identity입니다." },
         { "name": "objects[].label", "description": "object의 사용자 가시 이름입니다." },
         { "name": "x / y", "description": "문서 좌표계에서 object 좌상단의 위치입니다." },
         { "name": "width / height", "description": "resize 이후에도 유효해야 하는 object의 공간 크기입니다." },
-        { "name": "color", "description": "object가 소유하는 현재 presentation 값입니다." }
+        { "name": "color", "description": "도형의 채우기·글자색·path 선 색입니다." },
+        { "name": "fontSize / fontWeight / textAlign", "description": "글자의 크기·굵기·정렬입니다. 생략된 굵기는 400, 정렬은 left입니다." },
+        { "name": "strokeColor / strokeWidth", "description": "도형 테두리는 기본 #000000·0이며 path는 color와 양의 strokeWidth를 사용합니다." }
       ],
       "sourcePath": "packages/json-document-object-document/src/object-model.ts",
       "symbol": "ObjectDocument"
@@ -136,7 +138,7 @@
   "audits": {
     "object": {
       "status": "owner-closed",
-      "denominator": 14,
+      "denominator": 15,
       "horizon": {
         "enumerators": [
           "packages/json-document-object-document/src/index.ts",
@@ -151,6 +153,22 @@
         ]
       },
       "occurrences": [
+        {
+          "id": "style",
+          "role": "Document Style",
+          "knowledge": "종류별 스타일·유효 기본값·혼합 선택·요청 검증",
+          "decision": "표시와 편집이 같은 스타일 의미를 소비",
+          "changeReason": "스타일 속성과 적용 가능성 변경",
+          "stateLifecycle": "문서 값 또는 stateless 계산",
+          "inputsOutputs": "readObjectStyle의 public 계약",
+          "currentOwner": "@interactive-os/json-document-object-document",
+          "canonicalEvidence": "packages/json-document-object-document/src/object-style.ts와 공개 API·소유 API 문서·Canvas Usage/Source",
+          "sourcePath": "packages/json-document-object-document/src/object-style.ts",
+          "symbol": "readObjectStyle",
+          "disposition": "canonical consumer",
+          "intendedOwner": "@interactive-os/json-document-object-document",
+          "nextCheck": "혼합 스타일·no-op·원자적 거절 회귀와 두 Canvas Host"
+        },
         {
           "id": "model",
           "role": "Document Model",
diff --git a/docs/api-reference/canvas.md b/docs/api-reference/canvas.md
index b2159cef..261f92b8 100644
--- a/docs/api-reference/canvas.md
+++ b/docs/api-reference/canvas.md
@@ -57,5 +57,5 @@ createCanvasClipboardBinding(editor: ObjectEditor, policy: CanvasClipboardPolicy
 ## `useCanvasHand`
 
 ```ts
-useCanvasHand(editor: ObjectEditor, style: CanvasCreationStyle, selectProfile?: PlaneSelectProfile): { document: CanvasDocument; snapshot: import("<repository>/packages/json-document-editing/src/session").EditingSnapshot<ObjectSelection>; ... 21 more ...; surfaceProps: { ...; }; }
+useCanvasHand(editor: ObjectEditor, style: CanvasCreationStyle, selectProfile?: PlaneSelectProfile): { document: CanvasDocument; snapshot: import("<repository>/packages/json-document-editing/src/session").EditingSnapshot<ObjectSelection>; ... 23 more ...; surfaceProps: { ...; }; }
 ```
diff --git a/docs/api-reference/editing.md b/docs/api-reference/editing.md
index f4589e0f..ef8fa704 100644
--- a/docs/api-reference/editing.md
+++ b/docs/api-reference/editing.md
@@ -1299,6 +1299,7 @@ type ObjectIntent =
     }
   | { readonly type: "selection.remove" }
   | { readonly type: "selection.fill"; readonly color: string }
+  | { readonly type: "selection.style"; readonly style: Partial<ObjectStyle> }
   | {
       readonly type: "object.translate";
       readonly objectIds: ReadonlyArray<string>;
diff --git a/docs/api-reference/object-document.md b/docs/api-reference/object-document.md
index f7264869..e8ba6f5f 100644
--- a/docs/api-reference/object-document.md
+++ b/docs/api-reference/object-document.md
@@ -21,6 +21,11 @@ assertCanvasImageSource(source: unknown): asserts source is string
 ```ts
 assertObjectDocument(value: unknown): void
 ```
+## `assertObjectStyle`
+
+```ts
+assertObjectStyle(value: unknown): asserts value is Partial<ObjectStyle>
+```
 ## `CanvasDocument`
 
 ```ts
@@ -40,8 +45,8 @@ type CanvasObject = CanvasObjectDraft & { readonly id: string };
 
 ```ts
 type CanvasObjectDraft = ObjectDraft & (
-  | { readonly kind: "text"; readonly fontSize: number }
-  | { readonly kind: "rectangle" | "ellipse" }
+  | { readonly kind: "text"; readonly fontSize: number; readonly fontWeight?: 400 | 700; readonly textAlign?: "left" | "center" | "right" }
+  | { readonly kind: "rectangle" | "ellipse"; readonly strokeColor?: string; readonly strokeWidth?: number }
   | { readonly kind: "path"; readonly points: ReadonlyArray<ObjectPoint>; readonly strokeWidth: number }
   | { readonly kind: "image"; readonly source: string }
 );
@@ -73,6 +78,11 @@ interface DocumentObject extends ObjectDraft {
   readonly id: string;
 }
 ```
+## `getObjectStyle`
+
+```ts
+getObjectStyle(object: DocumentObject): Partial<ObjectStyle>
+```
 ## `ObjectBounds`
 
 ```ts
@@ -105,6 +115,7 @@ type ObjectOperation =
   | { readonly type: "insert"; readonly objects: ReadonlyArray<DocumentObject> }
   | { readonly type: "transform"; readonly objectIds: ReadonlyArray<string>; readonly transform: ObjectTransform }
   | { readonly type: "fill"; readonly objectIds: ReadonlyArray<string>; readonly color: string }
+  | { readonly type: "style"; readonly objectIds: ReadonlyArray<string>; readonly style: Partial<ObjectStyle> }
   | { readonly type: "remove"; readonly objectIds: ReadonlyArray<string> }
   | { readonly type: "text"; readonly objectId: string; readonly text: string }
   | { readonly type: "replace"; readonly document: ObjectDocument };
@@ -124,6 +135,23 @@ interface ObjectPoint extends Record<string, JSONValue> {
   readonly y: number;
 }
 ```
+## `ObjectStyle`
+
+```ts
+interface ObjectStyle {
+  readonly color: string;
+  readonly fontSize: number;
+  readonly fontWeight: 400 | 700;
+  readonly textAlign: "left" | "center" | "right";
+  readonly strokeColor: string;
+  readonly strokeWidth: number;
+}
+```
+## `ObjectStyleSelection`
+
+```ts
+type ObjectStyleSelection = { readonly [Key in keyof ObjectStyle]?: ObjectStyle[Key] | null };
+```
 ## `ObjectTransform`
 
 ```ts
@@ -149,6 +177,11 @@ planObjectOperation(document: ObjectDocument, operation: ObjectOperation): Objec
 ```ts
 projectObject(object: DocumentObject): CanvasObject
 ```
+## `readObjectStyle`
+
+```ts
+readObjectStyle(objects: ReadonlyArray<DocumentObject>): ObjectStyleSelection
+```
 ## `serializeCanvasDocument`
 
 ```ts
diff --git a/docs/api-reference/ui-primitives-react.md b/docs/api-reference/ui-primitives-react.md
index d6897ed0..2fa215d1 100644
--- a/docs/api-reference/ui-primitives-react.md
+++ b/docs/api-reference/ui-primitives-react.md
@@ -223,7 +223,7 @@ type MenuItem = {
 ## `Popover`
 
 ```ts
-Popover(props: { readonly label: string; readonly open: boolean; readonly onOpenChange: (open: boolean) => void; readonly trigger: ReactNode; readonly children: ReactNode; readonly className?: string; readonly panelClassName?: string; }): ReactNode
+Popover(props: { readonly label: string; readonly open: boolean; readonly onOpenChange: (open: boolean) => void; readonly trigger: ReactNode; readonly triggerPresentation?: "label" | "icon"; readonly children: ReactNode; readonly className?: string; readonly panelClassName?: string; }): ReactNode
 ```
 ## `ProductCanvas`
 
diff --git a/docs/public/intent.md b/docs/public/intent.md
index 9a4ea6d3..e28f05b4 100644
--- a/docs/public/intent.md
+++ b/docs/public/intent.md
@@ -116,6 +116,7 @@ commit은 되돌아가지 않습니다. Selection mapping/reconciliation callbac
 | `selection.set` | `objectIds`, `mode?` | 객체 선택 변경 |
 | `selection.remove` | | 선택한 객체 제거 |
 | `selection.fill` | `color` | 선택한 객체 색 변경 |
+| `selection.style` | `style` | 지원하는 선택 객체의 색·글자 서식·테두리를 한 번 변경 |
 | `object.translate` | `objectIds`, `dx`, `dy` | 선택한 객체 위치 이동 |
 | `object.resize` | `objectIds`, `dx`, `dy`, `dw`, `dh` | 선택한 객체 크기 |
 | `clipboard.paste` | `clipboard` | 붙여넣기 |
diff --git a/docs/public/object.md b/docs/public/object.md
index cab60211..528d7f62 100644
--- a/docs/public/object.md
+++ b/docs/public/object.md
@@ -21,7 +21,7 @@ ID 정책을 Host가 주입하는 자리입니다.
 ### `ObjectIntent`
 
 `dispatch`가 받는 Object domain command입니다. 공개 variant는
-`selection.set`, `selection.remove`, `selection.fill`, `object.create`, `object.text`,
+`selection.set`, `selection.remove`, `selection.fill`, `selection.style`, `object.create`, `object.text`,
 `object.translate`, `object.resize`, `object.duplicate`, `object.remove`, `document.replace`, `clipboard.paste`입니다. DOM event, pointer 좌표, clipboard
 event를 Intent에 넣지 않습니다.
 
diff --git a/packages/json-document-canvas/docs/api.md b/packages/json-document-canvas/docs/api.md
index e9e97c1f..13c87d2a 100644
--- a/packages/json-document-canvas/docs/api.md
+++ b/packages/json-document-canvas/docs/api.md
@@ -1,7 +1,7 @@
 ## Canvas Hand 계약 · RC
 
 `CanvasHand`는 `ObjectEditor`와 `CanvasCreationStyle`을 받아 글자·사각형·타원·자유
-그리기, 이미지·텍스트 붙여넣기, 다중 선택, 집합 이동·복제·삭제, native Clipboard, primary resize, Undo/Redo, JSON 재열기를 연결합니다.
+그리기, 이미지·텍스트 붙여넣기, 다중 선택, 선택 스타일, 집합 이동·복제·삭제, native Clipboard, primary resize, Undo/Redo, JSON 재열기를 연결합니다.
 `useCanvasHand`는 같은 입력 조합을 custom UI에서 사용할 수 있게 공개합니다.
 
 툴바의 모든 도구·명령은 Lucide 아이콘과 공통 `Toggle`/`Command`의 `label`을
@@ -67,6 +67,29 @@ Host: 한 장 fixture, 크기·색상 정책, 레이아웃
   한 번의 Undo로 되돌리며 삭제 Undo는 객체와 선택을 함께 복원합니다. Mod+Z/Mod+Shift+Z는
   입력 필드 밖에서 문서 Undo/Redo를 실행합니다.
 
+### 선택 스타일
+
+Select 도구에서 스타일을 지원하는 객체가 선택되면 팔레트 아이콘 하나가 나타납니다.
+공통 Popover와 Command 툴팁을 사용하며, 선택한 종류에 필요한 속성만 엽니다.
+색상 팔레트와 굵게·정렬 버튼은 즉시 확정합니다. 직접 입력한 CSS 색·글자 크기·선 굵기는
+Enter 또는 적용 아이콘으로 확정하고, Escape·바깥 클릭으로 닫으면 미확정 입력은 버립니다.
+이미지만 선택한 경우에는 스타일 컨트롤이 없습니다.
+
+혼합 선택은 `readObjectStyle`의 `null`을 `혼합`으로 드러냅니다. 색·크기·정렬을 임의의
+primary 값으로 표시하지 않습니다. 속성은 이를 지원하는 선택 객체에만 적용하고 전체
+선택과 primary를 보존합니다. 굵기가 모두 0인 도형에 테두리색을 고르면 2 단위로 함께
+켭니다. 투명한 테두리색이나 도형의 0 굵기로 테두리를 없앨 수 있습니다. path는 양의
+굵기가 필요하므로 path가 포함된 선택에 0을 입력하면 전체를 거절합니다.
+
+`useCanvasHand`의 `selectedStyle`과 `setStyle(style)`로 같은 기능을 custom UI에 연결할
+수 있습니다. `setStyle`은 `selection.style` Intent의 결과를 반환합니다. 스타일을 열거나
+적용할 때 글자 draft는 먼저 확정하고 진행 중인 gesture·paste는 취소합니다. 글자 편집
+textarea도 표시와 같은 크기·굵기·정렬을 사용합니다. 스타일 확정당 한 번의 Undo이며
+기본값·동일값은 문서와 History를 바꾸지 않습니다.
+
+스타일은 저장 객체에만 적용하며 `creationStyle`의 제품 생성 기본값을 변경하지 않습니다.
+글자 자동 크기, 부분 문자열 서식, 상시 inspector는 이번 범위 밖입니다.
+
 ### Native Clipboard
 
 선택 객체의 Mod+C/X/V 또는 브라우저 native copy/cut/paste 이벤트를 Web Clipboard
diff --git a/packages/json-document-canvas/src/canvas-hand.tsx b/packages/json-document-canvas/src/canvas-hand.tsx
index 5664db1a..3f533ab7 100644
--- a/packages/json-document-canvas/src/canvas-hand.tsx
+++ b/packages/json-document-canvas/src/canvas-hand.tsx
@@ -6,6 +6,7 @@ import { serializeCanvasDocument } from "@interactive-os/json-document-object-do
 import { Command, Field, ProductShell, Toggle, ToolbarGroup } from "@interactive-os/json-document-ui-primitives-react";
 import { CanvasObjectTarget, CanvasObjectView, CanvasResizeTarget, CanvasTextInput } from "./canvas-object-view.js";
 import { useCanvasHand, type CanvasCreationStyle, type CanvasTool } from "./use-canvas-hand.js";
+import { CanvasStyleControls } from "./canvas-style-controls.js";
 
 export interface CanvasHandProps {
   readonly editor: ObjectEditor;
@@ -37,6 +38,7 @@ export function CanvasHand(props: CanvasHandProps) {
         <Command label="복제" disabled={!selected} onClick={() => hand.duplicate()}><CopyPlus aria-hidden="true" size={16} /></Command>
         <Command label="삭제" disabled={!selected} onClick={hand.remove}><Trash2 aria-hidden="true" size={16} /></Command>
       </ToolbarGroup>
+      {hand.tool === "select" && <CanvasStyleControls key={JSON.stringify(hand.snapshot.selection)} value={hand.selectedStyle} onStyle={hand.setStyle} onOpen={() => { hand.commitText(); hand.cancel(); }} />}
       <Command label="JSON" onClick={() => { hand.commitText(); hand.cancel(); setJSON(json === null ? serializeCanvasDocument(props.editor.snapshot.value as typeof hand.document) : null); }}><Braces aria-hidden="true" size={16} /></Command>
     </ToolbarGroup>}>
       <svg ref={hand.surface} {...hand.surfaceProps} tabIndex={0} role="group" aria-label={props.label ?? "Canvas slide"}
diff --git a/packages/json-document-canvas/src/canvas-object-view.tsx b/packages/json-document-canvas/src/canvas-object-view.tsx
index 2b74b057..da22823d 100644
--- a/packages/json-document-canvas/src/canvas-object-view.tsx
+++ b/packages/json-document-canvas/src/canvas-object-view.tsx
@@ -1,21 +1,22 @@
 import { useEffect, useRef, type PointerEvent, type ReactNode } from "react";
-import type { CanvasObject } from "@interactive-os/json-document-object-document";
+import { getObjectStyle, type CanvasObject } from "@interactive-os/json-document-object-document";
 import type { InteractionHandleEvent, ResizeEdge } from "@interactive-os/json-document-affordance";
 import { contentInteractionAttributes, Field, useInteractionHandle } from "@interactive-os/json-document-ui-primitives-react";
 
 export function CanvasObjectView({ object }: { readonly object: CanvasObject }): ReactNode {
+  const style = getObjectStyle(object);
   if (object.kind === "image") return <image href={object.source} x={object.x} y={object.y} width={object.width} height={object.height} preserveAspectRatio="none" />;
   if (object.kind === "path") {
     return <polyline points={object.points.map((point) => `${object.x + point.x * object.width},${object.y + point.y * object.height}`).join(" ")} fill="none" stroke={object.color} strokeWidth={object.strokeWidth} strokeLinecap="round" strokeLinejoin="round" />;
   }
   if (object.kind === "text") return (
     <foreignObject x={object.x} y={object.y} width={object.width} height={object.height}>
-      <div style={{ color: object.color, fontSize: object.fontSize, lineHeight: 1.2, whiteSpace: "pre-wrap", overflowWrap: "anywhere", width: "100%", height: "100%", overflow: "hidden" }}>{object.label}</div>
+      <div style={{ color: style.color, fontSize: style.fontSize, fontWeight: style.fontWeight, textAlign: style.textAlign, lineHeight: 1.2, whiteSpace: "pre-wrap", overflowWrap: "anywhere", width: "100%", height: "100%", overflow: "hidden" }}>{object.label}</div>
     </foreignObject>
   );
   return object.kind === "ellipse"
-    ? <ellipse cx={object.x + object.width / 2} cy={object.y + object.height / 2} rx={object.width / 2} ry={object.height / 2} fill={object.color} />
-    : <rect x={object.x} y={object.y} width={object.width} height={object.height} fill={object.color} />;
+    ? <ellipse cx={object.x + object.width / 2} cy={object.y + object.height / 2} rx={object.width / 2} ry={object.height / 2} fill={object.color} stroke={style.strokeColor} strokeWidth={style.strokeWidth} />
+    : <rect x={object.x} y={object.y} width={object.width} height={object.height} fill={object.color} stroke={style.strokeColor} strokeWidth={style.strokeWidth} />;
 }
 
 export function CanvasObjectTarget(props: {
@@ -76,10 +77,11 @@ export function CanvasTextInput(props: {
   const input = useRef<HTMLTextAreaElement>(null);
   useEffect(() => { input.current?.focus(); input.current?.select(); }, [props.object.id]);
   const { object } = props;
+  const style = getObjectStyle(object);
   return (
     <foreignObject x={object.x} y={object.y} width={object.width} height={object.height}>
       <Field multiline presentation="seamless" label="Canvas text" controlRef={input} value={props.text} onValueChange={props.onChange}
-        style={{ color: object.color, fontSize: object.fontSize, lineHeight: 1.2, padding: 0, margin: 0, border: 0, width: "100%", height: "100%", resize: "none", background: "transparent", boxSizing: "border-box" }}
+        style={{ color: style.color, fontSize: style.fontSize, fontWeight: style.fontWeight, textAlign: style.textAlign, lineHeight: 1.2, padding: 0, margin: 0, border: 0, width: "100%", height: "100%", resize: "none", background: "transparent", boxSizing: "border-box" }}
         onBlur={props.onCommit}
         onKeyDown={(event) => {
           event.stopPropagation();
diff --git a/packages/json-document-canvas/src/canvas-style-controls.tsx b/packages/json-document-canvas/src/canvas-style-controls.tsx
new file mode 100644
index 00000000..d747cc23
--- /dev/null
+++ b/packages/json-document-canvas/src/canvas-style-controls.tsx
@@ -0,0 +1,67 @@
+import { useState } from "react";
+import { AlignCenter, AlignLeft, AlignRight, Bold, Check, Palette, Square, type LucideIcon } from "lucide-react";
+import type { ObjectStyle, ObjectStyleSelection } from "@interactive-os/json-document-object-document";
+import { Command, Field, Popover, Toggle, ToolbarGroup } from "@interactive-os/json-document-ui-primitives-react";
+
+const colors = [
+  ["검정", "#253044"], ["흰색", "#ffffff"], ["파랑", "#3b82f6"], ["빨강", "#ef4444"],
+  ["주황", "#f59e0b"], ["초록", "#22c55e"], ["보라", "#a855f7"], ["투명", "transparent"],
+] as const;
+const alignments: ReadonlyArray<{ readonly value: ObjectStyle["textAlign"]; readonly label: string; readonly icon: LucideIcon }> = [
+  { value: "left", label: "왼쪽 정렬", icon: AlignLeft }, { value: "center", label: "가운데 정렬", icon: AlignCenter }, { value: "right", label: "오른쪽 정렬", icon: AlignRight },
+];
+
+/** Selection-only UI; the Document Type owns supported properties and mixed values. */
+export function CanvasStyleControls(props: {
+  readonly value: ObjectStyleSelection;
+  readonly onStyle: (style: Partial<ObjectStyle>) => { readonly ok: boolean };
+  readonly onOpen: () => void;
+}) {
+  const [open, setOpen] = useState(false);
+  const value = props.value;
+  if (Object.keys(value).length === 0) return null;
+  const apply = (style: Partial<ObjectStyle>) => props.onStyle(style).ok;
+  return <Popover label="스타일" trigger={<Palette aria-hidden="true" size={16} />} triggerPresentation="icon"
+    open={open} onOpenChange={(next) => { if (next) props.onOpen(); setOpen(next); }} panelClassName="canvas-style-panel">
+    {value.color !== undefined && <StyleValue key={`color:${value.color}`} label="색상" value={value.color} color onApply={(color) => apply({ color })} />}
+    {value.strokeColor !== undefined && <StyleValue key={`stroke:${value.strokeColor}`} label="테두리 색" value={value.strokeColor} color
+      onApply={(strokeColor) => apply({ strokeColor, ...(value.strokeWidth === 0 && strokeColor !== "transparent" ? { strokeWidth: 2 } : {}) })} />}
+    {value.fontSize !== undefined && <StyleValue key={`size:${value.fontSize}`} label="글자 크기" value={value.fontSize} onApply={(fontSize) => apply({ fontSize: Number(fontSize) })} />}
+    {value.strokeWidth !== undefined && <StyleValue key={`width:${value.strokeWidth}`} label="선 굵기" value={value.strokeWidth} onApply={(strokeWidth) => apply({ strokeWidth: Number(strokeWidth) })} />}
+    {value.fontWeight !== undefined && <ToolbarGroup label="글자 서식">
+      <Toggle label={value.fontWeight === null ? "굵게: 혼합" : "굵게"} pressed={value.fontWeight === 700} onClick={() => apply({ fontWeight: value.fontWeight === 700 ? 400 : 700 })}><Bold aria-hidden="true" size={16} /></Toggle>
+      {alignments.map(({ value: alignment, label, icon: Icon }) => <Toggle key={alignment} label={label} pressed={value.textAlign === alignment} onClick={() => apply({ textAlign: alignment })}><Icon aria-hidden="true" size={16} /></Toggle>)}
+      {value.textAlign === null && <span>정렬: 혼합</span>}
+    </ToolbarGroup>}
+  </Popover>;
+}
+
+function StyleValue(props: {
+  readonly label: string;
+  readonly value: string | number | null;
+  readonly color?: boolean;
+  readonly onApply: (value: string) => boolean;
+}) {
+  const [draft, setDraft] = useState(props.value === null ? "" : String(props.value));
+  const [error, setError] = useState<string | null>(null);
+  function apply() {
+    const value = draft.trim();
+    if (!value || (props.color && !CSS.supports("color", value))) { setError(props.color ? "유효한 색상을 입력하세요." : "값을 입력하세요."); return; }
+    if (props.onApply(value)) setError(null);
+  }
+  return <div style={{ display: "grid", gap: 4 }}>
+    <span>{props.label}</span>
+    {props.color && <ToolbarGroup label={`${props.label} 팔레트`} style={{ flexWrap: "wrap" }}>
+      {colors.map(([label, color]) => <Toggle key={color} label={`${props.label}: ${label}`} pressed={props.value === color} onClick={() => { props.onApply(color); setDraft(color); setError(null); }}>
+        <Square aria-hidden="true" size={16} fill={color} stroke={color === "transparent" || color === "#ffffff" ? "currentColor" : color} />
+      </Toggle>)}
+    </ToolbarGroup>}
+    <form style={{ display: "flex", gap: 4 }} onSubmit={(event) => { event.preventDefault(); apply(); }}>
+      <Field label={props.label} value={draft} {...(props.value === null ? { placeholder: "혼합" } : {})} inputMode={props.color ? "text" : "decimal"}
+        onKeyDown={(event) => { if (event.nativeEvent.isComposing) { if (event.key === "Enter") event.preventDefault(); event.stopPropagation(); } }}
+        aria-invalid={error !== null} onValueChange={(value) => { setDraft(value); setError(null); }} style={{ width: "100%", minWidth: 0 }} />
+      <Command label={`${props.label} 적용`} type="submit"><Check aria-hidden="true" size={16} /></Command>
+    </form>
+    {error && <span role="alert">{error}</span>}
+  </div>;
+}
diff --git a/packages/json-document-canvas/src/use-canvas-hand.ts b/packages/json-document-canvas/src/use-canvas-hand.ts
index 4ab17ce9..07888876 100644
--- a/packages/json-document-canvas/src/use-canvas-hand.ts
+++ b/packages/json-document-canvas/src/use-canvas-hand.ts
@@ -1,6 +1,6 @@
 import { useEffect, useMemo, useReducer, useRef, useState, type ClipboardEvent, type KeyboardEvent, type PointerEvent } from "react";
 import { commitAffordance, createGestureSession, createPlaneSelectProfile, resizeAffordance, type InteractionHandleEvent, type PlaneSelectProfile, type PlaneSelectSelection, type ResizeEdge } from "@interactive-os/json-document-affordance";
-import { assertCanvasDocument, createCanvasObject, createCanvasPath, parseCanvasDocument, transformObject, type CanvasDocument, type CanvasObject, type CanvasObjectKind, type ObjectPoint } from "@interactive-os/json-document-object-document";
+import { assertCanvasDocument, createCanvasObject, createCanvasPath, parseCanvasDocument, readObjectStyle, transformObject, type CanvasDocument, type CanvasObject, type CanvasObjectKind, type ObjectPoint, type ObjectStyle } from "@interactive-os/json-document-object-document";
 import type { EditingResult, ObjectEditor, ObjectIntent, ObjectSelection } from "@interactive-os/json-document-editing";
 import { useEditingSnapshot } from "@interactive-os/json-document-react";
 import { createWebKeyboardAdapter, createWebPointerSession, isWebEditableTarget, projectWebClientPointToSVG, webSVGViewportFromElement } from "@interactive-os/json-document-web";
@@ -237,6 +237,7 @@ export function useCanvasHand(editor: ObjectEditor, style: CanvasCreationStyle,
   function remove() { commitText(); cancel(); dispatch({ type: "selection.remove" }); surface.current?.focus(); }
   function duplicate(keys = editor.snapshot.selection.keys) { commitText(); cancel(); dispatch({ type: "object.duplicate", objectIds: keys }); surface.current?.focus(); }
   function history(direction: "undo" | "redo") { commitText(); cancel(); report(editor[direction]()); surface.current?.focus(); }
+  function setStyle(style: Partial<ObjectStyle>) { commitText(); cancel(); return dispatch({ type: "selection.style", style }); }
 
   function handleClipboard(operation: "copy" | "cut" | "paste", event: ClipboardEvent) {
     if (isWebEditableTarget(event.target)) return;
@@ -287,7 +288,8 @@ export function useCanvasHand(editor: ObjectEditor, style: CanvasCreationStyle,
 
   return {
     document, snapshot, selection, marquee: selectionPreview?.marquee ?? null, objects, copyOriginals, preview, surface, tool, error, pastePending: clipboard.pending, draft: draft.current,
-    choose, select, interaction, editText, commitText, cancel, remove, duplicate, history,
+    choose, select, interaction, editText, commitText, cancel, remove, duplicate, history, setStyle,
+    selectedStyle: readObjectStyle(editor.selectedObjects),
     changeText(text: string) { if (draft.current) { draft.current = { ...draft.current, text }; redraw(); } },
     openJSON(json: string) {
       try {
diff --git a/packages/json-document-canvas/tests/canvas-hand.test.tsx b/packages/json-document-canvas/tests/canvas-hand.test.tsx
index 3942b152..8ebaf208 100644
--- a/packages/json-document-canvas/tests/canvas-hand.test.tsx
+++ b/packages/json-document-canvas/tests/canvas-hand.test.tsx
@@ -609,3 +609,96 @@ test("external replacement cancels an in-flight transform and unmount releases p
   window.dispatchEvent(end); window.removeEventListener("pointerup", observer);
   expect(observer).toHaveBeenCalled(); expect(commits).not.toHaveBeenCalled();
 });
+
+test("selection style uses an icon tooltip and only exposes supported properties", () => {
+  const { editor } = setup(populated);
+  const trigger = screen.getByRole("button", { name: "스타일" });
+  expect(document.getElementById(trigger.getAttribute("aria-describedby")!)?.textContent).toBe("스타일");
+  fireEvent.click(trigger);
+  expect(screen.getByRole("textbox", { name: "글자 크기" })).toBeTruthy();
+  expect(screen.queryByRole("textbox", { name: "테두리 색" })).toBeNull();
+  act(() => { editor.dispatch({ type: "selection.set", objectIds: [] }); });
+  expect(screen.queryByRole("button", { name: "스타일" })).toBeNull();
+  expect(screen.queryByRole("dialog", { name: "스타일" })).toBeNull();
+});
+
+test("mixed color applies to the whole set once, preserves primary and leaves image data unchanged", () => {
+  const initial: CanvasDocument = { ...populated, objects: [...populated.objects, { id: "image", kind: "image", source: "data:image/png;base64,AQID", label: "Image", color: "transparent", x: 800, y: 100, width: 100, height: 100 }] };
+  const { editor, value, commits } = setup(initial);
+  act(() => { editor.dispatch({ type: "selection.set", objectIds: ["a", "b", "image"], primaryKey: "image" }); });
+  const selection = editor.snapshot.selection;
+  fireEvent.click(screen.getByRole("button", { name: "스타일" }));
+  expect((screen.getByRole("textbox", { name: "색상" }) as HTMLInputElement).placeholder).toBe("혼합");
+  fireEvent.click(screen.getByRole("button", { name: "색상: 빨강" }));
+  expect(value().objects.slice(0, 2).map((object) => object.color)).toEqual(["#ef4444", "#ef4444"]);
+  expect(value().objects[3]).toEqual(initial.objects[3]); expect(editor.snapshot.selection).toEqual(selection);
+  expect(commits).toHaveBeenCalledOnce();
+  fireEvent.click(screen.getByRole("button", { name: "색상: 빨강" })); expect(commits).toHaveBeenCalledOnce();
+  fireEvent.click(screen.getByRole("button", { name: "실행 취소" })); expect(value()).toEqual(initial);
+  expect(editor.snapshot.selection).toEqual(selection);
+  act(() => { editor.dispatch({ type: "selection.set", objectIds: ["image"] }); });
+  expect(screen.queryByRole("button", { name: "스타일" })).toBeNull();
+});
+
+test("text font size, bold and alignment render identically in display and native editing", () => {
+  const { container, value, commits } = setup(populated);
+  fireEvent.click(screen.getByRole("button", { name: "스타일" }));
+  const font = screen.getByRole("textbox", { name: "글자 크기" });
+  fireEvent.change(font, { target: { value: "48" } });
+  expect(value().objects[0]!.fontSize).toBe(24); expect(commits).not.toHaveBeenCalled();
+  fireEvent.submit(font.closest("form")!);
+  fireEvent.click(screen.getByRole("button", { name: "굵게" }));
+  fireEvent.click(screen.getByRole("button", { name: "가운데 정렬" }));
+  expect(value().objects[0]).toMatchObject({ fontSize: 48, fontWeight: 700, textAlign: "center" });
+  expect(commits).toHaveBeenCalledTimes(3);
+  const display = container.querySelector("foreignObject > div") as HTMLElement;
+  expect(display.style.fontSize).toBe("48px"); expect(display.style.fontWeight).toBe("700"); expect(display.style.textAlign).toBe("center");
+  fireEvent.keyDown(screen.getByRole("dialog", { name: "스타일" }), { key: "Escape" });
+  fireEvent.doubleClick(container.querySelector('[data-canvas-object="a"]')!);
+  const input = screen.getByRole("textbox", { name: "Canvas text" }) as HTMLTextAreaElement;
+  expect(input.style.fontSize).toBe(display.style.fontSize); expect(input.style.fontWeight).toBe("700"); expect(input.style.textAlign).toBe("center");
+  fireEvent.change(input, { target: { value: "Updated" } });
+  fireEvent.click(screen.getByRole("button", { name: "스타일" }));
+  expect(value().objects[0]!.label).toBe("Updated"); expect(commits).toHaveBeenCalledTimes(4);
+  fireEvent.click(screen.getByRole("button", { name: "굵게" }));
+  expect(value().objects[0]).toMatchObject({ label: "Updated", fontWeight: 400 });
+});
+
+test("shape outlines and path widths render without replacing geometry or primary selection", () => {
+  const path = { id: "p", kind: "path", label: "Line", color: "black", strokeWidth: 3, points: [{ x: 0, y: 0 }, { x: 1, y: 1 }], x: 100, y: 400, width: 100, height: 80 } as const;
+  const { container, editor, value } = setup({ ...populated, objects: [...populated.objects, path] });
+  pick(container, "b");
+  fireEvent.click(screen.getByRole("button", { name: "스타일" }));
+  fireEvent.click(screen.getByRole("button", { name: "테두리 색: 빨강" }));
+  expect(value().objects[1]).toMatchObject({ strokeColor: "#ef4444", strokeWidth: 2 });
+  expect(container.querySelector('rect[stroke="#ef4444"]')?.getAttribute("stroke-width")).toBe("2");
+  act(() => { editor.dispatch({ type: "selection.set", objectIds: ["b", "p"], primaryKey: "b" }); });
+  fireEvent.click(screen.getByRole("button", { name: "스타일" }));
+  const width = screen.getByRole("textbox", { name: "선 굵기" });
+  expect((width as HTMLInputElement).placeholder).toBe("혼합");
+  fireEvent.change(width, { target: { value: "8" } }); fireEvent.submit(width.closest("form")!);
+  expect(value().objects[3]).toEqual({ ...path, strokeWidth: 8 });
+  expect(container.querySelector("polyline")?.getAttribute("stroke-width")).toBe("8");
+  expect(editor.snapshot.selection).toMatchObject({ keys: ["b", "p"], primaryKey: "b" });
+});
+
+test("invalid style and cancelled field drafts do not create partial state or history", () => {
+  const { value, editor, commits } = setup(populated);
+  fireEvent.click(screen.getByRole("button", { name: "스타일" }));
+  const field = screen.getByRole("textbox", { name: "글자 크기" });
+  fireEvent.change(field, { target: { value: "-1" } }); fireEvent.submit(field.closest("form")!);
+  expect(screen.getByRole("alert")).toBeTruthy(); expect(value()).toEqual(populated); expect(commits).not.toHaveBeenCalled();
+  fireEvent.change(field, { target: { value: "99" } }); fireEvent.keyDown(field, { key: "Escape" });
+  expect(screen.queryByRole("dialog", { name: "스타일" })).toBeNull();
+  expect(editor.snapshot.canUndo).toBe(false); expect(value()).toEqual(populated);
+});
+
+test("opening style cancels a resize preview and stale pointer release cannot overwrite a style", () => {
+  const { container, value, commits } = setup(populated);
+  const handle = container.querySelector('[data-resize-edge="se"]')!;
+  fireEvent.pointerDown(handle, event(100, 100)); fireEvent.pointerMove(window, event(140, 140));
+  fireEvent.click(screen.getByRole("button", { name: "스타일" }));
+  fireEvent.click(screen.getByRole("button", { name: "색상: 빨강" }));
+  fireEvent.pointerUp(window, event(150, 150));
+  expect(value().objects[0]).toEqual({ ...populated.objects[0], color: "#ef4444" }); expect(commits).toHaveBeenCalledOnce();
+});
diff --git a/packages/json-document-editing/docs/object-selection.md b/packages/json-document-editing/docs/object-selection.md
index 5c4adc42..0536c64b 100644
--- a/packages/json-document-editing/docs/object-selection.md
+++ b/packages/json-document-editing/docs/object-selection.md
@@ -22,6 +22,24 @@ Intent를 사용합니다. Undo/Redo는 해당 문서 변경과 함께 원인 
 
 실제 public API 소비: [Canvas Usage와 Source](/demo/canvas).
 
+### 선택 스타일
+
+`selection.style`은 `{ style: Partial<ObjectStyle> }`을 받아 선택한 객체에 한 번 적용합니다.
+스타일의 값·기본값·종류별 지원 여부·검증은 [Object Document Type](/docs/api/object-document)의
+`style` 연산에 위임합니다. 예를 들어 글자·도형·이미지를 함께 선택한 뒤 fontSize를 바꾸면
+글자만 바뀌며 이미지와 선택 집합·primary는 유지됩니다.
+
+```ts
+editor.dispatch({ type: "selection.style", style: { color: "#3b82f6", fontSize: 48, fontWeight: 700 } });
+```
+
+한 번의 변경은 한 번의 commit/Undo입니다. Undo/Redo는 그때의 선택도 복원합니다.
+같은 유효값과 지원 대상이 없는 속성은 문서·History·redo branch를 바꾸지 않습니다.
+일반 Editing session의 관찰 revision 의미는 그대로이며 no-op publication을 금지하는
+계약은 아닙니다. 빈 선택은 `selection.empty`, 잘못된 스타일은 실패를 반환합니다.
+복제·Clipboard·JSON은 저장된 스타일 필드를 그대로 보존합니다. 기존 `selection.fill`은
+종류에 관계없이 color를 쓰는 호환 동작을 유지합니다.
+
 ### 복제와 Clipboard
 
 `object.duplicate`는 `objectIds` 집합을 문서 순서로 복제합니다. 생략한 `placement`는
diff --git a/packages/json-document-editing/src/object.ts b/packages/json-document-editing/src/object.ts
index e04654b2..21086846 100644
--- a/packages/json-document-editing/src/object.ts
+++ b/packages/json-document-editing/src/object.ts
@@ -17,7 +17,7 @@ import type { EditingHistoryOptions } from "./history.js";
 import { cutEditingClipboard, isClipboardRecord } from "./clipboard.js";
 import {
   assertObjectDocument, planObjectOperation, transformObject,
-  type DocumentObject, type ObjectDocument, type ObjectDraft, type ObjectOperation,
+  type DocumentObject, type ObjectDocument, type ObjectDraft, type ObjectOperation, type ObjectStyle,
 } from "@interactive-os/json-document-object-document";
 export type { DocumentObject, ObjectDocument } from "@interactive-os/json-document-object-document";
 
@@ -70,6 +70,7 @@ export type ObjectIntent =
     }
   | { readonly type: "selection.remove" }
   | { readonly type: "selection.fill"; readonly color: string }
+  | { readonly type: "selection.style"; readonly style: Partial<ObjectStyle> }
   | {
       readonly type: "object.translate";
       readonly objectIds: ReadonlyArray<string>;
@@ -209,6 +210,9 @@ export function createObjectEditor(
     if (intent.type === "selection.fill") {
       return apply({ type: "fill", objectIds: selected.map((object) => object.id), color: intent.color }, session.snapshot.selection, intent.type);
     }
+    if (intent.type === "selection.style") {
+      return apply({ type: "style", objectIds: selected.map((object) => object.id), style: intent.style }, session.snapshot.selection, intent.type);
+    }
 
     return intent.type === "selection.remove" ? removeSelected(selected.map((object) => object.id)) : failure("object.unsupported-intent");
   }
diff --git a/packages/json-document-editing/tests/object-style.test.ts b/packages/json-document-editing/tests/object-style.test.ts
new file mode 100644
index 00000000..7e1adaf2
--- /dev/null
+++ b/packages/json-document-editing/tests/object-style.test.ts
@@ -0,0 +1,66 @@
+import { expect, test, vi } from "vitest";
+import { createJSONDocument } from "@interactive-os/json-document";
+import { parseCanvasDocument, serializeCanvasDocument, type CanvasDocument } from "@interactive-os/json-document-object-document";
+import { createObjectEditor, objectClipboardFormat } from "../src/index.js";
+
+const bounds = { x: 10, y: 20, width: 100, height: 80, label: "Text", color: "blue" };
+const initial: CanvasDocument = { profile: "canvas/1", width: 1280, height: 720, objects: [
+  { ...bounds, id: "text", kind: "text", fontSize: 32 },
+  { ...bounds, id: "rect", kind: "rectangle" },
+  { ...bounds, id: "image", kind: "image", source: "data:image/png;base64,AQID", color: "transparent" },
+] };
+
+test("mixed selection styling is one commit and Undo restores the exact document and causal selection", () => {
+  const document = createJSONDocument(initial), commits = vi.fn(); document.subscribe(commits);
+  const editor = createObjectEditor(document);
+  editor.dispatch({ type: "selection.set", objectIds: ["text", "rect", "image"], primaryKey: "image" });
+  const selection = editor.snapshot.selection;
+  expect(editor.dispatch({ type: "selection.style", style: { color: "red", fontSize: 48, fontWeight: 700, textAlign: "center", strokeColor: "black", strokeWidth: 4 } }).ok).toBe(true);
+  expect(commits).toHaveBeenCalledOnce(); expect(editor.snapshot.selection).toEqual(selection);
+  const styled = editor.snapshot.value;
+  expect((styled as CanvasDocument).objects[2]).toEqual(initial.objects[2]);
+  editor.dispatch({ type: "selection.set", objectIds: ["rect"] });
+  editor.undo(); expect(editor.snapshot.value).toEqual(initial); expect(editor.snapshot.selection).toEqual(selection);
+  editor.redo(); expect(editor.snapshot.value).toEqual(styled); expect(editor.snapshot.selection).toEqual(selection);
+});
+
+test("style no-ops and rejected requests preserve history including a redo branch", () => {
+  const editor = createObjectEditor(initial);
+  editor.dispatch({ type: "selection.style", style: { color: "red" } }); editor.undo();
+  const before = editor.snapshot;
+  for (const style of [{ fontWeight: 400, textAlign: "left" }, { strokeWidth: 10 }, {}] as const) {
+    expect(editor.dispatch({ type: "selection.style", style }).ok).toBe(true);
+    expect(editor.snapshot).toMatchObject({ value: before.value, selection: before.selection, canUndo: false, canRedo: true });
+  }
+  const beforeReject = editor.snapshot;
+  expect(editor.dispatch({ type: "selection.style", style: { color: "red", fontSize: -1 } }).ok).toBe(false);
+  expect(editor.snapshot).toEqual(beforeReject); expect(editor.snapshot.canRedo).toBe(true);
+  editor.dispatch({ type: "selection.set", objectIds: [] });
+  expect(editor.dispatch({ type: "selection.style", style: { color: "red" } })).toMatchObject({ ok: false, code: "selection.empty" });
+});
+
+test("all style fields survive duplicate, native payload serialization, fresh-ID paste and JSON reopen", () => {
+  let id = 0;
+  const editor = createObjectEditor(initial, { createId: () => `new-${++id}` });
+  editor.dispatch({ type: "selection.set", objectIds: ["text", "rect"], primaryKey: "text" });
+  editor.dispatch({ type: "selection.style", style: { color: "red", fontWeight: 700, textAlign: "right", strokeColor: "black", strokeWidth: 2 } });
+  const originals = editor.selectedObjects;
+  editor.dispatch({ type: "object.duplicate", objectIds: ["text", "rect"] });
+  const clipboard = objectClipboardFormat.parse(JSON.parse(JSON.stringify(editor.copy())))!;
+  expect(clipboard).not.toBeNull();
+  editor.dispatch({ type: "clipboard.paste", clipboard });
+  editor.selectedObjects.forEach((object, index) => expect(object).toEqual({ ...originals[index], id: object.id, x: originals[index]!.x + 24, y: originals[index]!.y + 24 }));
+  const saved = serializeCanvasDocument(editor.snapshot.value as CanvasDocument);
+  expect(createObjectEditor(parseCanvasDocument(saved)).snapshot.value).toEqual(editor.snapshot.value);
+  editor.undo(); expect((editor.snapshot.value as CanvasDocument).objects).toHaveLength(5);
+});
+
+test("legacy fill keeps its contract and general style does not paint image metadata", () => {
+  const editor = createObjectEditor(initial);
+  editor.dispatch({ type: "selection.set", objectIds: ["image"] });
+  expect(editor.dispatch({ type: "selection.fill", color: "purple" }).ok).toBe(true);
+  expect(editor.selectedObjects[0]!.color).toBe("purple");
+  const before = editor.snapshot;
+  expect(editor.dispatch({ type: "selection.style", style: { color: "green" } }).ok).toBe(true);
+  expect(editor.snapshot).toMatchObject({ value: before.value, selection: before.selection, canUndo: before.canUndo, canRedo: before.canRedo });
+});
diff --git a/packages/json-document-object-document/docs/api.md b/packages/json-document-object-document/docs/api.md
index 6828fd75..4d66e2ca 100644
--- a/packages/json-document-object-document/docs/api.md
+++ b/packages/json-document-object-document/docs/api.md
@@ -20,9 +20,9 @@ Object도 계속 유효합니다. legacy Object의 생략된 color는 계속 수
 
 | kind | 추가 문서 값 | 표현 |
 | --- | --- | --- |
-| text | 양의 유한수 fontSize | label이 실제 내용인 plain text. 별도의 text 복사본 없음 |
-| rectangle | 없음 | color로 채운 사각형 |
-| ellipse | 없음 | 경계 상자에 내접하는 타원 |
+| text | 양의 유한수 fontSize, 선택적 fontWeight·textAlign | label이 실제 내용인 plain text. 별도의 text 복사본 없음 |
+| rectangle | 선택적 strokeColor·strokeWidth | color로 채운 사각형 |
+| ellipse | 선택적 strokeColor·strokeWidth | 경계 상자에 내접하는 타원 |
 | path | points, 양의 유한수 strokeWidth | color로 그린 열린 선 |
 | image | source | 문서에 포함한 PNG/JPEG/WebP의 base64 data URL |
 
@@ -53,7 +53,7 @@ path points는 최소 두 개의 `{ x, y }`이며 각 좌표는 `[0, 1]`입니
 
 ### 의미 연산과 projection
 
-`planObjectOperation(document, operation)`은 insert, transform, fill, remove,
+`planObjectOperation(document, operation)`은 insert, transform, fill, style, remove,
 text, replace를 검증된 JSON Patch로 계획합니다. 성공은 `{ ok: true, operations }`,
 실패는 `{ ok: false, code, reason? }`입니다. 계획은 입력을 변경하거나 commit하지
 않으며 선택과 History를 알지 못합니다. 없는 대상·중복 ID·유효하지 않은 결과는
@@ -64,6 +64,41 @@ text, replace를 검증된 JSON Patch로 계획합니다. 성공은 `{ ok: true,
 반대쪽을 통과해도 뒤집지 않습니다. 화면 바깥 좌표는 허용하며 Hand가 슬라이드 밖을
 clip합니다. 위치를 자동 보정하거나 snap하지 않습니다.
 
+### 객체 스타일
+
+`getObjectStyle(object)`는 적용 가능한 속성의 유효값을 반환합니다. 글자의 생략된
+`fontWeight`는 400, `textAlign`은 `left`입니다. 굵기는 400/700, 정렬은
+`left`/`center`/`right`를 지원합니다. 도형의 생략된 `strokeColor`는 `#000000`,
+`strokeWidth`는 0이므로 기존 문서는 테두리 없이 그대로 열립니다. 기본값을 읽는 것만으로
+문서를 바꾸지 않으며, 기존 kind 없는 Object는 color만 지원합니다.
+
+`ObjectStyle`의 color는 도형의 채우기·글자색·path의 선 색입니다. strokeColor는
+사각형·타원의 테두리색이며 strokeWidth는 도형과 path의 선 굵기입니다. 이미지에는
+스타일 속성이 없습니다. 새 스타일의 색 값은 비어 있지 않은 문자열이고, 도형의 굵기는
+0 이상, path의 굵기와 글자 크기는 양의 유한수여야 합니다. 색 문자열의 CSS 해석은
+렌더링 플랫폼의 책임입니다. 부분 문자열 서식이나 Rich Text 모델은 아닙니다.
+
+`readObjectStyle(objects)`는 속성을 지원하는 객체끼리만 비교합니다. 공통 값이면 그 값,
+서로 다르면 `null`, 지원하는 객체가 없으면 속성을 생략합니다. `null`은 저장값이 아니라
+혼합 선택의 읽기 결과입니다.
+
+```ts
+import { readObjectStyle, planObjectOperation } from "@interactive-os/json-document-object-document";
+
+const style = readObjectStyle(document.objects);
+const plan = planObjectOperation(document, {
+  type: "style", objectIds: ["title", "rectangle"],
+  style: { color: "#3b82f6", fontWeight: 700, strokeWidth: 2 },
+});
+```
+
+`style` 연산은 `Partial<ObjectStyle>`을 받아 지원하는 대상 필드에만 적용합니다.
+`assertObjectStyle`로 전체 요청을 먼저 검증하므로 지원하지 않는 속성도 잘못된 값이면
+전체 거절합니다. 없는 ID와 잘못된 결과도 전체 거절합니다. 특히 path가 섞인 집합에
+strokeWidth 0을 적용하면 도형만 바꾸지 않고 전체를 거절합니다. 같은 유효값, 빈 요청,
+지원 대상이 없는 요청은 빈 patch이며 생략된 기본값을 저장하지 않습니다.
+기존 `fill`은 이미지의 color 메타데이터를 포함한 기존 동작을 유지하는 호환 명령입니다.
+
 ### Usage와 남은 범위
 
 [Canvas Hand의 실제 Usage/Source](/docs/api/canvas)와 [Object Editing](/docs/object)가
diff --git a/packages/json-document-object-document/src/index.ts b/packages/json-document-object-document/src/index.ts
index 4e295ccb..6a13cbbe 100644
--- a/packages/json-document-object-document/src/index.ts
+++ b/packages/json-document-object-document/src/index.ts
@@ -2,3 +2,4 @@ export type { ObjectBounds, ObjectPoint, ObjectDraft, DocumentObject, ObjectDocu
 export { assertObjectDocument, assertCanvasDocument, assertCanvasImageSource, parseCanvasDocument, serializeCanvasDocument } from "./object-validation.js";
 export { createCanvasObject, createCanvasPath, createCanvasImage, projectObject, transformObject, type ObjectTransform } from "./object-projection.js";
 export { planObjectOperation, type ObjectOperation, type ObjectOperationPlan } from "./object-operation.js";
+export { getObjectStyle, readObjectStyle, assertObjectStyle, type ObjectStyle, type ObjectStyleSelection } from "./object-style.js";
diff --git a/packages/json-document-object-document/src/object-model.ts b/packages/json-document-object-document/src/object-model.ts
index 25becd97..6bbae248 100644
--- a/packages/json-document-object-document/src/object-model.ts
+++ b/packages/json-document-object-document/src/object-model.ts
@@ -29,8 +29,8 @@ export interface ObjectDocument extends Record<string, JSONValue> {
 export type CanvasObjectKind = "text" | "rectangle" | "ellipse" | "path" | "image";
 
 export type CanvasObjectDraft = ObjectDraft & (
-  | { readonly kind: "text"; readonly fontSize: number }
-  | { readonly kind: "rectangle" | "ellipse" }
+  | { readonly kind: "text"; readonly fontSize: number; readonly fontWeight?: 400 | 700; readonly textAlign?: "left" | "center" | "right" }
+  | { readonly kind: "rectangle" | "ellipse"; readonly strokeColor?: string; readonly strokeWidth?: number }
   | { readonly kind: "path"; readonly points: ReadonlyArray<ObjectPoint>; readonly strokeWidth: number }
   | { readonly kind: "image"; readonly source: string }
 );
diff --git a/packages/json-document-object-document/src/object-operation.ts b/packages/json-document-object-document/src/object-operation.ts
index e0aa6c9e..a95012e4 100644
--- a/packages/json-document-object-document/src/object-operation.ts
+++ b/packages/json-document-object-document/src/object-operation.ts
@@ -2,11 +2,13 @@ import { applyPatch, buildPointer, jsonEqual, type JSONPatchOperation } from "@i
 import type { DocumentObject, ObjectDocument } from "./object-model.js";
 import { transformObject, type ObjectTransform } from "./object-projection.js";
 import { assertObjectDocument } from "./object-validation.js";
+import { assertObjectStyle, getObjectStyle, type ObjectStyle } from "./object-style.js";
 
 export type ObjectOperation =
   | { readonly type: "insert"; readonly objects: ReadonlyArray<DocumentObject> }
   | { readonly type: "transform"; readonly objectIds: ReadonlyArray<string>; readonly transform: ObjectTransform }
   | { readonly type: "fill"; readonly objectIds: ReadonlyArray<string>; readonly color: string }
+  | { readonly type: "style"; readonly objectIds: ReadonlyArray<string>; readonly style: Partial<ObjectStyle> }
   | { readonly type: "remove"; readonly objectIds: ReadonlyArray<string> }
   | { readonly type: "text"; readonly objectId: string; readonly text: string }
   | { readonly type: "replace"; readonly document: ObjectDocument };
@@ -19,6 +21,7 @@ export type ObjectOperationPlan =
 export function planObjectOperation(document: ObjectDocument, operation: ObjectOperation): ObjectOperationPlan {
   try {
     assertObjectDocument(document);
+    if (operation.type === "style") assertObjectStyle(operation.style);
     const objects = document.objects;
     const operations: JSONPatchOperation[] = [];
     if (operation.type === "replace") {
@@ -42,6 +45,12 @@ export function planObjectOperation(document: ObjectDocument, operation: ObjectO
           }
         } else if (operation.type === "fill") {
           if (operation.color !== object.color) operations.push({ op: "replace", path: buildPointer(["objects", index, "color"]), value: operation.color });
+        } else if (operation.type === "style") {
+          const current = getObjectStyle(object);
+          for (const [key, value] of Object.entries(operation.style)) {
+            const effective = current[key as keyof ObjectStyle];
+            if (effective !== undefined && effective !== value) operations.push({ op: "add", path: buildPointer(["objects", index, key]), value });
+          }
         } else if (operation.type === "text") {
           if (object.kind !== "text") return { ok: false, code: "object.not-text" };
           if (operation.text !== object.label) operations.push({ op: "replace", path: buildPointer(["objects", index, "label"]), value: operation.text });
diff --git a/packages/json-document-object-document/src/object-style.ts b/packages/json-document-object-document/src/object-style.ts
new file mode 100644
index 00000000..d85beffe
--- /dev/null
+++ b/packages/json-document-object-document/src/object-style.ts
@@ -0,0 +1,50 @@
+import type { DocumentObject } from "./object-model.js";
+
+/** Object-level styles, not character-range formatting. Color is the kind's primary paint. */
+export interface ObjectStyle {
+  readonly color: string;
+  readonly fontSize: number;
+  readonly fontWeight: 400 | 700;
+  readonly textAlign: "left" | "center" | "right";
+  readonly strokeColor: string;
+  readonly strokeWidth: number;
+}
+
+/** Missing means unsupported by every target; null means mixed among supporting targets. */
+export type ObjectStyleSelection = { readonly [Key in keyof ObjectStyle]?: ObjectStyle[Key] | null };
+
+/** Effective values and capabilities have one owner, including legacy defaults. */
+export function getObjectStyle(object: DocumentObject): Partial<ObjectStyle> {
+  const color = object.color ?? "transparent";
+  switch (object.kind) {
+    case "image": return {};
+    case "text": return { color, fontSize: object.fontSize as number, fontWeight: (object.fontWeight ?? 400) as 400 | 700, textAlign: (object.textAlign ?? "left") as ObjectStyle["textAlign"] };
+    case "rectangle": case "ellipse": return { color, strokeColor: (object.strokeColor ?? "#000000") as string, strokeWidth: (object.strokeWidth ?? 0) as number };
+    case "path": return { color, strokeWidth: object.strokeWidth as number };
+    default: return { color };
+  }
+}
+
+export function readObjectStyle(objects: ReadonlyArray<DocumentObject>): ObjectStyleSelection {
+  const selection: Record<string, string | number | null> = {};
+  for (const object of objects) {
+    for (const [key, value] of Object.entries(getObjectStyle(object))) {
+      selection[key] = selection[key] === undefined ? value : selection[key] === value ? value : null;
+    }
+  }
+  return selection;
+}
+
+/** Validate the complete request before planning any target, even unsupported properties. */
+export function assertObjectStyle(value: unknown): asserts value is Partial<ObjectStyle> {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new TypeError("Object style must be a record.");
+  for (const [key, field] of Object.entries(value)) {
+    const valid = key === "color" || key === "strokeColor" ? typeof field === "string" && field.length > 0
+      : key === "fontSize" ? typeof field === "number" && Number.isFinite(field) && field > 0
+      : key === "strokeWidth" ? typeof field === "number" && Number.isFinite(field) && field >= 0
+      : key === "fontWeight" ? field === 400 || field === 700
+      : key === "textAlign" ? field === "left" || field === "center" || field === "right"
+      : false;
+    if (!valid) throw new TypeError(`Invalid Object style: ${key}.`);
+  }
+}
diff --git a/packages/json-document-object-document/src/object-validation.ts b/packages/json-document-object-document/src/object-validation.ts
index d2eedce8..b8f3b566 100644
--- a/packages/json-document-object-document/src/object-validation.ts
+++ b/packages/json-document-object-document/src/object-validation.ts
@@ -1,6 +1,7 @@
 import { createJSONDocument, type JSONValue } from "@interactive-os/json-document";
 import { assertRasterImageSource as assertCanvasImageSource } from "@interactive-os/json-document-file-intake";
 import type { CanvasDocument, ObjectDocument } from "./object-model.js";
+import { assertObjectStyle } from "./object-style.js";
 
 function record(value: unknown): value is Record<string, unknown> {
   return value !== null && typeof value === "object" && !Array.isArray(value);
@@ -29,6 +30,8 @@ export function assertObjectDocument(value: unknown): void {
       if (!["text", "rectangle", "ellipse", "path", "image"].includes(object.kind as string)) throw new TypeError("Unknown Object kind.");
       if (!positive(object.width) || !positive(object.height)) throw new TypeError("Canvas object dimensions must be positive.");
       if (object.kind === "text" && !positive(object.fontSize)) throw new TypeError("Text fontSize must be positive and finite.");
+      const styleKeys = object.kind === "text" ? ["fontWeight", "textAlign"] : object.kind === "rectangle" || object.kind === "ellipse" ? ["strokeColor", "strokeWidth"] : [];
+      assertObjectStyle(Object.fromEntries(styleKeys.filter((key) => Object.hasOwn(object, key)).map((key) => [key, object[key]])));
       if (object.kind === "image") assertCanvasImageSource(object.source);
       if (object.kind === "path") {
         if (!positive(object.strokeWidth) || !Array.isArray(object.points) || object.points.length < 2) throw new TypeError("Path requires a positive strokeWidth and at least two points.");
diff --git a/packages/json-document-object-document/tests/object-style.test.ts b/packages/json-document-object-document/tests/object-style.test.ts
new file mode 100644
index 00000000..59efd0b8
--- /dev/null
+++ b/packages/json-document-object-document/tests/object-style.test.ts
@@ -0,0 +1,68 @@
+import { expect, test } from "vitest";
+import { applyPatch } from "@interactive-os/json-document";
+import { assertCanvasDocument, assertObjectStyle, getObjectStyle, parseCanvasDocument, planObjectOperation, readObjectStyle, serializeCanvasDocument, type CanvasDocument, type ObjectStyle } from "../src/index.js";
+
+const bounds = { x: 10, y: 20, width: 100, height: 80, label: "", color: "blue" };
+const document: CanvasDocument = { profile: "canvas/1", width: 1280, height: 720, objects: [
+  { ...bounds, id: "text", kind: "text", fontSize: 32 },
+  { ...bounds, id: "rect", kind: "rectangle" },
+  { ...bounds, id: "ellipse", kind: "ellipse", color: "red", strokeColor: "green", strokeWidth: 4 },
+  { ...bounds, id: "path", kind: "path", strokeWidth: 4, points: [{ x: 0, y: 0 }, { x: 1, y: 1 }] },
+  { ...bounds, id: "image", kind: "image", source: "data:image/png;base64,AQID", color: "transparent" },
+] };
+
+test("effective styles preserve old documents and expose kind-specific capabilities", () => {
+  expect(getObjectStyle(document.objects[0]!)).toEqual({ color: "blue", fontSize: 32, fontWeight: 400, textAlign: "left" });
+  expect(getObjectStyle(document.objects[1]!)).toEqual({ color: "blue", strokeColor: "#000000", strokeWidth: 0 });
+  expect(getObjectStyle(document.objects[3]!)).toEqual({ color: "blue", strokeWidth: 4 });
+  expect(getObjectStyle(document.objects[4]!)).toEqual({});
+  expect(getObjectStyle({ ...bounds, id: "legacy" })).toEqual({ color: "blue" });
+  expect(parseCanvasDocument(serializeCanvasDocument(document))).toEqual(document);
+  expect(document.objects[0]).not.toHaveProperty("fontWeight");
+});
+
+test("mixed values only compare supporting targets and retain unsupported as absent", () => {
+  expect(readObjectStyle([])).toEqual({});
+  expect(readObjectStyle(document.objects)).toEqual({ color: null, fontSize: 32, fontWeight: 400, textAlign: "left", strokeColor: null, strokeWidth: null });
+  expect(readObjectStyle([document.objects[0]!, document.objects[4]!])).toEqual(getObjectStyle(document.objects[0]!));
+  expect(readObjectStyle([document.objects[0]!, { ...document.objects[0]!, id: "bold", fontWeight: 700, textAlign: "right" }])).toMatchObject({ fontWeight: null, textAlign: null });
+});
+
+test("one atomic style plan changes only applicable fields without replacing extension data or geometry", () => {
+  const style = { color: "purple", fontSize: 48, fontWeight: 700, textAlign: "center", strokeColor: "orange", strokeWidth: 6 } as const;
+  const plan = planObjectOperation(document, { type: "style", objectIds: document.objects.map((object) => object.id), style });
+  expect(plan.ok).toBe(true);
+  if (!plan.ok) return;
+  const result = applyPatch(document, plan.operations);
+  expect(result.ok).toBe(true);
+  if (!result.ok) return;
+  const next = result.value as CanvasDocument;
+  expect(next.objects[0]).toEqual({ ...document.objects[0], color: "purple", fontSize: 48, fontWeight: 700, textAlign: "center" });
+  expect(next.objects[1]).toEqual({ ...document.objects[1], color: "purple", strokeColor: "orange", strokeWidth: 6 });
+  expect(next.objects[3]).toEqual({ ...document.objects[3], color: "purple", strokeWidth: 6 });
+  expect(next.objects[4]).toEqual(document.objects[4]);
+  expect(parseCanvasDocument(serializeCanvasDocument(next))).toEqual(next);
+});
+
+test("effective default and unsupported properties are no-ops, while missing targets reject the whole plan", () => {
+  expect(planObjectOperation(document, { type: "style", objectIds: ["text"], style: { fontWeight: 400, textAlign: "left", strokeColor: "red" } })).toEqual({ ok: true, operations: [] });
+  expect(planObjectOperation(document, { type: "style", objectIds: ["rect"], style: { strokeWidth: 0, strokeColor: "#000000" } })).toEqual({ ok: true, operations: [] });
+  expect(planObjectOperation(document, { type: "style", objectIds: ["image"], style: { color: "red", fontSize: 42 } })).toEqual({ ok: true, operations: [] });
+  expect(planObjectOperation(document, { type: "style", objectIds: ["text", "missing"], style: { color: "red" } })).toMatchObject({ ok: false, code: "selection.object-not-found" });
+});
+
+test.each([null, [], { color: "" }, { color: 1 }, { strokeColor: "" }, { fontSize: 0 }, { fontSize: Infinity }, { fontSize: "32" }, { fontWeight: 500 }, { textAlign: "justify" }, { strokeWidth: -1 }, { strokeWidth: NaN }, { unknown: 1 }, { color: "red", fontSize: undefined }])("rejects malformed style requests before partial or unsupported updates %#", (style) => {
+  expect(() => assertObjectStyle(style)).toThrow();
+  expect(planObjectOperation(document, { type: "style", objectIds: ["rect", "image"], style: style as Partial<ObjectStyle> })).toMatchObject({ ok: false });
+});
+
+test.each([{ fontWeight: 500 }, { textAlign: "justify" }])("validates optional persisted text fields %#", (style) => {
+  expect(() => assertCanvasDocument({ ...document, objects: [{ ...document.objects[0], ...style }] })).toThrow();
+});
+
+test("stroke removal is valid for shapes but a path still requires positive width", () => {
+  expect(planObjectOperation(document, { type: "style", objectIds: ["ellipse"], style: { strokeWidth: 0 } }).ok).toBe(true);
+  expect(planObjectOperation(document, { type: "style", objectIds: ["ellipse", "path"], style: { strokeWidth: 0, color: "red" } })).toMatchObject({ ok: false });
+  expect(() => assertCanvasDocument({ ...document, objects: [{ ...document.objects[1], strokeWidth: -1 }] })).toThrow();
+  expect(() => assertCanvasDocument({ ...document, objects: [{ ...document.objects[1], strokeColor: 0 }] })).toThrow();
+});
diff --git a/packages/json-document-ui-primitives-react/docs/popover.md b/packages/json-document-ui-primitives-react/docs/popover.md
new file mode 100644
index 00000000..7ec92023
--- /dev/null
+++ b/packages/json-document-ui-primitives-react/docs/popover.md
@@ -0,0 +1,22 @@
+## Popover · 아이콘 trigger
+
+`Popover`는 `label`, `trigger`, `open`, `onOpenChange`와 panel 내용을 받습니다.
+`triggerPresentation="icon"`이면 trigger를 공통 `Command`의 아이콘·툴팁으로 표시합니다.
+label이 접근성 이름과 툴팁의 정본이며 icon은 `aria-hidden`으로 렌더링합니다.
+기본 trigger presentation은 기존 label 표현입니다.
+
+열 때 panel로 focus를 옮기고, Escape로 닫으면 trigger로 복귀합니다. 바깥 pointerdown과
+panel 밖으로의 focus 이동은 panel만 닫고 사용자의 새 focus를 가로채지 않습니다.
+panel 내부의 입력과 선택은 열린 상태를 유지합니다. Dialog와 달리 focus를 가두지 않습니다.
+입력 draft를 언제 확정할지는 소비하는 Hand가 정합니다.
+
+```tsx
+import { Popover } from "@interactive-os/json-document-ui-primitives-react";
+
+<Popover label="스타일" trigger={<Palette aria-hidden="true" size={16} />}
+  triggerPresentation="icon" open={open} onOpenChange={setOpen}>
+  {styleControls}
+</Popover>
+```
+
+[Canvas Usage/Source](/demo/canvas)의 선택 스타일이 이 API를 사용합니다.
diff --git a/packages/json-document-ui-primitives-react/package.json b/packages/json-document-ui-primitives-react/package.json
index 3009b343..04f58684 100644
--- a/packages/json-document-ui-primitives-react/package.json
+++ b/packages/json-document-ui-primitives-react/package.json
@@ -13,7 +13,7 @@
     "directory": "packages/json-document-ui-primitives-react"
   },
   "publishConfig": { "access": "public", "provenance": true, "tag": "next" },
-  "files": ["dist", "!dist/.tsbuildinfo", "README.md", "LICENSE"],
+  "files": ["dist", "!dist/.tsbuildinfo", "docs", "README.md", "LICENSE"],
   "exports": {
     ".": { "types": "./dist/index.d.ts", "import": "./dist/index.js" },
     "./content-interaction.css": "./dist/content-interaction.css"
diff --git a/packages/json-document-ui-primitives-react/src/presentations.tsx b/packages/json-document-ui-primitives-react/src/presentations.tsx
index 6642971d..4b532365 100644
--- a/packages/json-document-ui-primitives-react/src/presentations.tsx
+++ b/packages/json-document-ui-primitives-react/src/presentations.tsx
@@ -1,26 +1,39 @@
 import { useEffect, useId, useRef, type ReactNode } from "react";
+import { Command } from "./controls.js";
 
 export function Popover(props: {
   readonly label: string;
   readonly open: boolean;
   readonly onOpenChange: (open: boolean) => void;
   readonly trigger: ReactNode;
+  readonly triggerPresentation?: "label" | "icon";
   readonly children: ReactNode;
   readonly className?: string;
   readonly panelClassName?: string;
 }): ReactNode {
   const id = `json-document-popover-${useId().replaceAll(":", "")}`;
-  const triggerRef = useRef<HTMLButtonElement>(null);
+  const rootRef = useRef<HTMLSpanElement>(null);
   const panelRef = useRef<HTMLDivElement>(null);
   useEffect(() => { if (props.open) panelRef.current?.focus(); }, [props.open]);
+  useEffect(() => {
+    if (!props.open) return;
+    const dismissOutside = (event: PointerEvent) => {
+      if (event.target instanceof Node && !rootRef.current?.contains(event.target)) props.onOpenChange(false);
+    };
+    document.addEventListener("pointerdown", dismissOutside, true);
+    return () => document.removeEventListener("pointerdown", dismissOutside, true);
+  }, [props.open, props.onOpenChange]);
   const close = () => {
     props.onOpenChange(false);
-    queueMicrotask(() => triggerRef.current?.focus());
+    queueMicrotask(() => rootRef.current?.querySelector<HTMLButtonElement>("button")?.focus());
   };
+  const triggerProps = { "aria-label": props.label, "aria-haspopup": "dialog", "aria-controls": id, "aria-expanded": props.open, onClick: () => props.onOpenChange(!props.open) } as const;
   return (
-    <span className={props.className} data-ui-presentation="popover">
-      <button ref={triggerRef} type="button" aria-label={props.label} aria-haspopup="dialog" aria-controls={id} aria-expanded={props.open} onClick={() => props.onOpenChange(!props.open)}>{props.trigger}</button>
-      {props.open ? <div ref={panelRef} id={id} role="dialog" aria-label={props.label} tabIndex={-1} className={props.panelClassName} onKeyDown={(event) => { if (event.key === "Escape") { event.preventDefault(); close(); } }}>{props.children}</div> : null}
+    <span ref={rootRef} className={props.className} data-ui-presentation="popover" onBlur={(event) => {
+      if (props.open && event.relatedTarget instanceof Node && !event.currentTarget.contains(event.relatedTarget)) props.onOpenChange(false);
+    }}>
+      {props.triggerPresentation === "icon" ? <Command {...triggerProps} label={props.label}>{props.trigger}</Command> : <button type="button" {...triggerProps}>{props.trigger}</button>}
+      {props.open ? <div ref={panelRef} id={id} role="dialog" aria-label={props.label} tabIndex={-1} className={props.panelClassName} onKeyDown={(event) => { if (event.key === "Escape") { event.preventDefault(); event.stopPropagation(); close(); } }}>{props.children}</div> : null}
     </span>
   );
 }
diff --git a/packages/json-document-ui-primitives-react/tests/primitives.test.tsx b/packages/json-document-ui-primitives-react/tests/primitives.test.tsx
index 53728579..12c341bf 100644
--- a/packages/json-document-ui-primitives-react/tests/primitives.test.tsx
+++ b/packages/json-document-ui-primitives-react/tests/primitives.test.tsx
@@ -111,6 +111,25 @@ describe("UI Primitives", () => {
     expect(screen.queryByRole("dialog", { name: "Delete document" })).toBeNull();
   });
 
+  test("icon Popover reuses Command tooltips, dismisses outside, and restores focus only on Escape", async () => {
+    const user = userEvent.setup();
+    function Harness() {
+      const [open, setOpen] = useState(false);
+      return <><Popover label="Style" trigger={<span aria-hidden="true">◇</span>} triggerPresentation="icon" open={open} onOpenChange={setOpen}><button>Inside</button></Popover><button>Outside</button></>;
+    }
+    render(<Harness />);
+    const trigger = screen.getByRole("button", { name: "Style" });
+    expect(trigger.getAttribute("data-ui-control")).toBe("command");
+    expect(document.getElementById(trigger.getAttribute("aria-describedby")!)?.textContent).toBe("Style");
+    await user.click(trigger); await user.click(screen.getByRole("button", { name: "Inside" }));
+    expect(screen.getByRole("dialog", { name: "Style" })).toBeTruthy();
+    await user.keyboard("{Escape}"); expect(document.activeElement).toBe(trigger);
+    await user.click(trigger); const outside = screen.getByRole("button", { name: "Outside" }); await user.click(outside);
+    expect(screen.queryByRole("dialog", { name: "Style" })).toBeNull(); expect(document.activeElement).toBe(outside);
+    await user.click(trigger); await user.tab(); await user.tab();
+    expect(screen.queryByRole("dialog", { name: "Style" })).toBeNull(); expect(document.activeElement).toBe(outside);
+  });
+
   test("Dialog moves focus inside, traps Tab, and restores the invoking control", async () => {
     const user = userEvent.setup();
     function Harness() {
diff --git a/site/src/app/index.css b/site/src/app/index.css
index 847b8ee5..1ceb497f 100644
--- a/site/src/app/index.css
+++ b/site/src/app/index.css
@@ -295,6 +295,10 @@
     @apply absolute left-0 top-full z-20 mt-1 min-w-40;
   }
 
+  .canvas-style-panel {
+    @apply grid w-64 gap-3 rounded-control border border-line-subtle bg-background-canvas p-3 text-xs text-foreground-default shadow-overlay;
+  }
+
   [data-ui-presentation="dialog-backdrop"] {
     @apply fixed inset-0 z-40 grid place-items-center bg-foreground-strong/10;
   }
diff --git a/site/src/routes/canvas-demo/CanvasDemoRoute.tsx b/site/src/routes/canvas-demo/CanvasDemoRoute.tsx
index 1e4d3d8c..9e9bc107 100644
--- a/site/src/routes/canvas-demo/CanvasDemoRoute.tsx
+++ b/site/src/routes/canvas-demo/CanvasDemoRoute.tsx
@@ -11,7 +11,7 @@ export function CanvasDemoRoute() {
   const [editor] = useState(() => createObjectEditor(emptyCanvasDocument));
   const [selectProfile] = useState(() => createPlaneSelectProfile());
   return (
-    <DemoPage documentation={<PageHeader illustration="peek" title="Canvas">한 장에 글자·도형·그리기. Shift+클릭으로 다중 선택하고 Alt+드래그로 복제합니다. 복사한 텍스트·이미지도 붙여넣을 수 있으며, 글자는 더블클릭으로 편집합니다.</PageHeader>}>
+    <DemoPage documentation={<PageHeader illustration="peek" title="Canvas">한 장에 글자·도형·그리기. Shift+클릭으로 다중 선택하고 Alt+드래그로 복제합니다. 선택한 객체의 스타일 아이콘에서 색·글자 서식·테두리를 바꾸고, 복사한 텍스트·이미지를 붙여넣습니다.</PageHeader>}>
       <CanvasHand className={ui.product.embedded} editor={editor} selectProfile={selectProfile} creationStyle={canvasCreationStyle} slideStyle={{ background: "rgb(var(--color-background-canvas))" }} />
     </DemoPage>
   );
diff --git a/site/src/routes/docs/doc-pages.ts b/site/src/routes/docs/doc-pages.ts
index 6f62e9af..5b214a03 100644
--- a/site/src/routes/docs/doc-pages.ts
+++ b/site/src/routes/docs/doc-pages.ts
@@ -15,6 +15,7 @@ import planeSelectContractMarkdown from "../../../../packages/json-document-affo
 import resizeContractMarkdown from "../../../../packages/json-document-affordance/docs/resize.md?raw";
 import objectSelectionContractMarkdown from "../../../../packages/json-document-editing/docs/object-selection.md?raw";
 import uiPrimitivesApiMarkdown from "../../../../docs/api-reference/ui-primitives-react.md?raw";
+import uiPopoverContractMarkdown from "../../../../packages/json-document-ui-primitives-react/docs/popover.md?raw";
 import animationApiMarkdown from "../../../../docs/api-reference/animation-react.md?raw";
 import markdownReactApiMarkdown from "../../../../docs/api-reference/markdown-react.md?raw";
 import databaseApiMarkdown from "../../../../docs/api-reference/database.md?raw";
@@ -196,7 +197,7 @@ export const docPages = {
   zodApi: docPage("/docs/api/zod", zodApiMarkdown),
   tanStackTableApi: docPage("/docs/api/tanstack-table", tanStackTableApiMarkdown),
   affordanceApi: docPage("/docs/api/affordance", `${planeSelectContractMarkdown}\n\n${resizeContractMarkdown}\n\n${affordanceApiMarkdown}`),
-  uiPrimitivesApi: docPage("/docs/api/ui-primitives-react", uiPrimitivesApiMarkdown),
+  uiPrimitivesApi: docPage("/docs/api/ui-primitives-react", `${uiPopoverContractMarkdown}\n\n${uiPrimitivesApiMarkdown}`),
   animationApi: docPage("/docs/api/animation-react", animationApiMarkdown),
   markdownReactApi: docPage("/docs/api/markdown-react", markdownReactApiMarkdown),
   databaseApi: docPage("/docs/api/database", databaseApiMarkdown),
diff --git a/site/src/shared/demo-workbench/demo-sources.ts b/site/src/shared/demo-workbench/demo-sources.ts
index 59004a08..5ec33a07 100644
--- a/site/src/shared/demo-workbench/demo-sources.ts
+++ b/site/src/shared/demo-workbench/demo-sources.ts
@@ -1,11 +1,13 @@
 import type { CodeLanguage } from "../ui/code-tokens";
 import objectModelSource from "../../../../packages/json-document-object-document/src/object-model.ts?raw";
+import objectStyleSource from "../../../../packages/json-document-object-document/src/object-style.ts?raw";
 import objectValidationSource from "../../../../packages/json-document-object-document/src/object-validation.ts?raw";
 import objectOperationSource from "../../../../packages/json-document-object-document/src/object-operation.ts?raw";
 import objectProjectionSource from "../../../../packages/json-document-object-document/src/object-projection.ts?raw";
 import canvasHandSource from "../../../../packages/json-document-canvas/src/canvas-hand.tsx?raw";
 import canvasInteractionSource from "../../../../packages/json-document-canvas/src/use-canvas-hand.ts?raw";
 import canvasObjectViewSource from "../../../../packages/json-document-canvas/src/canvas-object-view.tsx?raw";
+import canvasStyleControlsSource from "../../../../packages/json-document-canvas/src/canvas-style-controls.tsx?raw";
 import canvasClipboardSource from "../../../../packages/json-document-canvas/src/canvas-clipboard.ts?raw";
 import canvasClipboardEditingSource from "../../../../packages/json-document-editing/src/canvas-clipboard.ts?raw";
 import objectPasteSessionSource from "../../../../packages/json-document-editing/src/object-paste-session.ts?raw";
@@ -218,12 +220,14 @@ const registeredUsageSources = new Map<string, string>([
   ["packages/json-document-file-intake/src/raster-content.ts", rasterContentSource],
   ["packages/json-document-composer-react/src/attachments.ts", composerAttachmentsSource],
   ["packages/json-document-object-document/src/object-model.ts", objectModelSource],
+  ["packages/json-document-object-document/src/object-style.ts", objectStyleSource],
   ["packages/json-document-object-document/src/object-validation.ts", objectValidationSource],
   ["packages/json-document-object-document/src/object-operation.ts", objectOperationSource],
   ["packages/json-document-object-document/src/object-projection.ts", objectProjectionSource],
   ["packages/json-document-canvas/src/canvas-hand.tsx", canvasHandSource],
   ["packages/json-document-canvas/src/use-canvas-hand.ts", canvasInteractionSource],
   ["packages/json-document-canvas/src/canvas-object-view.tsx", canvasObjectViewSource],
+  ["packages/json-document-canvas/src/canvas-style-controls.tsx", canvasStyleControlsSource],
   ["packages/json-document-canvas/src/canvas-clipboard.ts", canvasClipboardSource],
   ["packages/json-document-editing/src/canvas-clipboard.ts", canvasClipboardEditingSource],
   ["packages/json-document-editing/src/object-paste-session.ts", objectPasteSessionSource],
@@ -393,6 +397,11 @@ const registeredPublicUsages = [
     symbol: "CanvasHand",
     sourcePath: "packages/json-document-canvas/src/canvas-object-view.tsx",
   },
+  {
+    packageName: "@interactive-os/json-document-canvas",
+    symbol: "CanvasHand",
+    sourcePath: "packages/json-document-canvas/src/canvas-style-controls.tsx",
+  },
   {
     packageName: "@interactive-os/json-document-canvas",
     symbol: "useCanvasHand",
@@ -404,6 +413,7 @@ const registeredPublicUsages = [
     sourcePath: "packages/json-document-react/src/editing-snapshot.ts",
   },
   ...(["ObjectDocument", "CanvasDocument", "DocumentObject", "CanvasObject"] as const).map((symbol) => ({ packageName: "@interactive-os/json-document-object-document", symbol, sourcePath: "packages/json-document-object-document/src/object-model.ts" })),
+  ...(["getObjectStyle", "readObjectStyle", "assertObjectStyle", "ObjectStyle", "ObjectStyleSelection"] as const).map((symbol) => ({ packageName: "@interactive-os/json-document-object-document", symbol, sourcePath: "packages/json-document-object-document/src/object-style.ts" })),
   ...(["assertObjectDocument", "assertCanvasDocument", "assertCanvasImageSource", "parseCanvasDocument", "serializeCanvasDocument"] as const).map((symbol) => ({ packageName: "@interactive-os/json-document-object-document", symbol, sourcePath: "packages/json-document-object-document/src/object-validation.ts" })),
   ...(["createCanvasObject", "createCanvasPath", "createCanvasImage", "projectObject", "transformObject"] as const).map((symbol) => ({ packageName: "@interactive-os/json-document-object-document", symbol, sourcePath: "packages/json-document-object-document/src/object-projection.ts" })),
   {
diff --git a/site/tailwind.config.cjs b/site/tailwind.config.cjs
index 26bae9fb..9fd7578b 100644
--- a/site/tailwind.config.cjs
+++ b/site/tailwind.config.cjs
@@ -3,6 +3,7 @@ module.exports = {
   content: [
     "./index.html",
     "./src/**/*.{ts,tsx}",
+    "../packages/json-document-canvas/src/**/*.{ts,tsx}",
   ],
   theme: {
     extend: {
diff --git a/site/tests/unit/demo-workbench.test.tsx b/site/tests/unit/demo-workbench.test.tsx
index 42427305..cdc9d051 100644
--- a/site/tests/unit/demo-workbench.test.tsx
+++ b/site/tests/unit/demo-workbench.test.tsx
@@ -241,6 +241,7 @@ describe("Demo definition and source discovery", () => {
       "packages/json-document-web/src/clipboard.ts",
       "packages/json-document-editing/src/object.ts",
       "packages/json-document-object-document/src/object-model.ts",
+      "packages/json-document-object-document/src/object-style.ts",
       "packages/json-document-object-document/src/object-validation.ts",
       "packages/json-document-file-intake/src/raster-content.ts",
       "packages/json-document/src/application/document/create.ts",
@@ -352,9 +353,11 @@ describe("Demo definition and source discovery", () => {
       const paths = (await discoverDemoSources(entry)).map((file) => file.path);
       expect(paths).toEqual(expect.arrayContaining([
         "packages/json-document-canvas/src/canvas-hand.tsx",
+        "packages/json-document-canvas/src/canvas-style-controls.tsx",
         "packages/json-document-canvas/src/use-canvas-hand.ts",
         "packages/json-document-canvas/src/canvas-object-view.tsx",
         "packages/json-document-object-document/src/object-model.ts",
+        "packages/json-document-object-document/src/object-style.ts",
         "packages/json-document-object-document/src/object-validation.ts",
         "packages/json-document-object-document/src/object-operation.ts",
         "packages/json-document-object-document/src/object-projection.ts",
@@ -365,6 +368,9 @@ describe("Demo definition and source discovery", () => {
       ]));
       const hand = (await discoverDemoSources(entry)).find((file) => file.path === "packages/json-document-canvas/src/use-canvas-hand.ts")!;
       expect(await hand.load()).toContain("resizeAffordance(gesture.start, gesture.point, gesture.edge, gesture, gesture.object)");
+      const style = (await discoverDemoSources(entry)).find((file) => file.path === "packages/json-document-object-document/src/object-style.ts")!;
+      expect(style.referencePath).toBe("/docs/api/object-document");
+      expect(await style.load()).toContain("export function readObjectStyle");
     }
   });
 

From e8a1e47c56938711de62beed5cb08a33c9bb06b5 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E1=84=8B=E1=85=B2=E1=84=8B=E1=85=AD=E1=86=BC=E1=84=90?=
 =?UTF-8?q?=E1=85=A2?= <teo.v@navercorp.com>
Date: Thu, 10 Sep 2026 02:07:44 +0900
Subject: [PATCH 19/20] =?UTF-8?q?fix(canvas):=20=EC=8A=A4=ED=83=80?=
 =?UTF-8?q?=EC=9D=BC=20=ED=8C=94=EB=A0=88=ED=8A=B8=EC=9D=98=20=ED=88=AC?=
 =?UTF-8?q?=EB=AA=85=EC=83=89=EA=B3=BC=20=EB=B0=B0=EC=97=B4=EC=9D=84=20?=
 =?UTF-8?q?=EA=B5=AC=EB=B6=84=ED=95=9C=EB=8B=A4?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 packages/json-document-canvas/src/canvas-style-controls.tsx | 6 +++---
 site/src/app/index.css                                      | 2 +-
 2 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/packages/json-document-canvas/src/canvas-style-controls.tsx b/packages/json-document-canvas/src/canvas-style-controls.tsx
index d747cc23..83a5afc0 100644
--- a/packages/json-document-canvas/src/canvas-style-controls.tsx
+++ b/packages/json-document-canvas/src/canvas-style-controls.tsx
@@ -1,5 +1,5 @@
 import { useState } from "react";
-import { AlignCenter, AlignLeft, AlignRight, Bold, Check, Palette, Square, type LucideIcon } from "lucide-react";
+import { AlignCenter, AlignLeft, AlignRight, Bold, Check, Palette, Square, SquareDashed, type LucideIcon } from "lucide-react";
 import type { ObjectStyle, ObjectStyleSelection } from "@interactive-os/json-document-object-document";
 import { Command, Field, Popover, Toggle, ToolbarGroup } from "@interactive-os/json-document-ui-primitives-react";
 
@@ -51,9 +51,9 @@ function StyleValue(props: {
   }
   return <div style={{ display: "grid", gap: 4 }}>
     <span>{props.label}</span>
-    {props.color && <ToolbarGroup label={`${props.label} 팔레트`} style={{ flexWrap: "wrap" }}>
+    {props.color && <ToolbarGroup label={`${props.label} 팔레트`} style={{ display: "grid", gridTemplateColumns: "repeat(4, 1fr)" }}>
       {colors.map(([label, color]) => <Toggle key={color} label={`${props.label}: ${label}`} pressed={props.value === color} onClick={() => { props.onApply(color); setDraft(color); setError(null); }}>
-        <Square aria-hidden="true" size={16} fill={color} stroke={color === "transparent" || color === "#ffffff" ? "currentColor" : color} />
+        {color === "transparent" ? <SquareDashed aria-hidden="true" size={16} /> : <Square aria-hidden="true" size={16} fill={color} stroke={color === "#ffffff" ? "currentColor" : color} />}
       </Toggle>)}
     </ToolbarGroup>}
     <form style={{ display: "flex", gap: 4 }} onSubmit={(event) => { event.preventDefault(); apply(); }}>
diff --git a/site/src/app/index.css b/site/src/app/index.css
index 1ceb497f..496d63d3 100644
--- a/site/src/app/index.css
+++ b/site/src/app/index.css
@@ -296,7 +296,7 @@
   }
 
   .canvas-style-panel {
-    @apply grid w-64 gap-3 rounded-control border border-line-subtle bg-background-canvas p-3 text-xs text-foreground-default shadow-overlay;
+    @apply grid w-64 gap-3 rounded-control border border-line-subtle bg-background-canvas p-3 text-xs text-foreground-default shadow-overlay outline-none;
   }
 
   [data-ui-presentation="dialog-backdrop"] {

From 684919f0d76ab82dfbe519789e3e3abddc18c6aa Mon Sep 17 00:00:00 2001
From: "teo.v" <66650330+developer-1px@users.noreply.github.com>
Date: Thu, 10 Sep 2026 09:50:37 +0900
Subject: [PATCH 20/20] =?UTF-8?q?feat(canvas):=20=EC=8A=A4=ED=8B=B0?=
 =?UTF-8?q?=EC=BB=A4=20=EB=85=B8=ED=8A=B8=EC=99=80=20=EB=8F=84=ED=98=95=20?=
 =?UTF-8?q?=EB=B3=B8=EB=AC=B8=EC=9D=84=20=EA=B0=99=EC=9D=80=20=ED=8E=B8?=
 =?UTF-8?q?=EC=A7=91=20=EA=B3=84=EC=95=BD=EC=9C=BC=EB=A1=9C=20=EC=97=B0?=
 =?UTF-8?q?=EA=B2=B0=ED=95=9C=EB=8B=A4=20(#762)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-authored-by: 유용태 <teo.v@navercorp.com>
---
 audits/document-types.json                    | 16 ++--
 docs/api-reference/canvas.md                  |  2 +
 docs/api-reference/object-document.md         | 32 +++++++-
 docs/public/intent.md                         |  1 +
 docs/public/object.md                         |  3 +
 packages/json-document-canvas/README.md       |  5 +-
 packages/json-document-canvas/docs/api.md     | 19 ++++-
 .../json-document-canvas/src/canvas-hand.tsx  |  7 +-
 .../src/canvas-object-view.tsx                | 47 +++++++----
 .../src/canvas-style-controls.tsx             |  1 +
 .../src/use-canvas-hand.ts                    | 15 ++--
 .../tests/canvas-hand.test.tsx                | 78 ++++++++++++++++++-
 .../docs/object-selection.md                  |  8 +-
 .../tests/object-text.test.ts                 | 44 +++++++++++
 .../json-document-object-document/docs/api.md | 33 ++++++--
 .../src/index.ts                              |  4 +-
 .../src/object-model.ts                       | 12 ++-
 .../src/object-operation.ts                   |  4 +-
 .../src/object-projection.ts                  | 27 ++++++-
 .../src/object-style.ts                       |  9 ++-
 .../src/object-validation.ts                  |  8 +-
 .../tests/object-style.test.ts                |  6 +-
 .../tests/object-text.test.ts                 | 69 ++++++++++++++++
 site/src/app/index.css                        |  2 +-
 .../routes/canvas-demo/CanvasDemoRoute.tsx    |  2 +-
 .../demo-workbench/canvas-demo-document.ts    |  7 +-
 .../src/shared/demo-workbench/demo-sources.ts |  4 +-
 27 files changed, 385 insertions(+), 80 deletions(-)
 create mode 100644 packages/json-document-editing/tests/object-text.test.ts
 create mode 100644 packages/json-document-object-document/tests/object-text.test.ts

diff --git a/audits/document-types.json b/audits/document-types.json
index 422acb3b..f3723c67 100644
--- a/audits/document-types.json
+++ b/audits/document-types.json
@@ -32,16 +32,16 @@
     },
     "object": {
       "why": "캔버스 object는 identity, geometry와 presentation 값을 하나의 의미 단위로 유지해야 하기 때문입니다.",
-      "does": "object의 위치·크기·스타일 모델을 정의하고 translate·resize·fill·style의 원자적 연산을 제공합니다.",
-      "schema": "interface DocumentObject {\n  readonly id: string;\n  readonly label: string;\n  readonly x: number;\n  readonly y: number;\n  readonly width: number;\n  readonly height: number;\n  readonly color: string;\n}\n\ninterface ObjectDocument {\n  readonly objects: ReadonlyArray<DocumentObject>;\n}\n\ntype CanvasObject = DocumentObject & (\n  | { kind: \"text\"; fontSize: number; fontWeight?: 400 | 700; textAlign?: \"left\" | \"center\" | \"right\" }\n  | { kind: \"rectangle\" | \"ellipse\"; strokeColor?: string; strokeWidth?: number }\n  | { kind: \"path\"; points: ReadonlyArray<{ x: number; y: number }>; strokeWidth: number }\n  | { kind: \"image\"; source: string }\n);\ninterface CanvasDocument extends ObjectDocument {\n  readonly profile: \"canvas/1\";\n  readonly width: number; readonly height: number;\n  readonly objects: ReadonlyArray<CanvasObject>;\n}",
+      "does": "object의 위치·크기·본문·스타일 모델을 정의하고 translate·resize·fill·style·text의 원자적 연산을 제공합니다.",
+      "schema": "interface DocumentObject {\n  readonly id: string;\n  readonly label: string;\n  readonly x: number;\n  readonly y: number;\n  readonly width: number;\n  readonly height: number;\n  readonly color: string;\n}\n\ninterface ObjectDocument {\n  readonly objects: ReadonlyArray<DocumentObject>;\n}\n\ninterface CanvasTextFormat {\n  readonly fontSize?: number;\n  readonly fontWeight?: 400 | 700;\n  readonly textAlign?: \"left\" | \"center\" | \"right\";\n}\ntype CanvasObject = DocumentObject & (\n  | (CanvasTextFormat & { kind: \"text\"; fontSize: number })\n  | (CanvasTextFormat & { kind: \"rectangle\" | \"ellipse\" | \"sticky-note\"; textColor?: string; strokeColor?: string; strokeWidth?: number })\n  | { kind: \"path\"; points: ReadonlyArray<{ x: number; y: number }>; strokeWidth: number }\n  | { kind: \"image\"; source: string }\n);\ninterface CanvasDocument extends ObjectDocument {\n  readonly profile: \"canvas/1\";\n  readonly width: number; readonly height: number;\n  readonly objects: ReadonlyArray<CanvasObject>;\n}",
       "fields": [
         { "name": "objects", "description": "같은 공간에서 배치·선택되는 object의 ordered collection입니다." },
         { "name": "objects[].id", "description": "selection, transform과 clipboard가 object를 안정적으로 참조하는 identity입니다." },
-        { "name": "objects[].label", "description": "object의 사용자 가시 이름입니다." },
+        { "name": "objects[].label", "description": "text·도형·노트의 실제 본문이며 별도 text 복사본이 없습니다. image·path에서는 이름입니다." },
         { "name": "x / y", "description": "문서 좌표계에서 object 좌상단의 위치입니다." },
         { "name": "width / height", "description": "resize 이후에도 유효해야 하는 object의 공간 크기입니다." },
-        { "name": "color", "description": "도형의 채우기·글자색·path 선 색입니다." },
-        { "name": "fontSize / fontWeight / textAlign", "description": "글자의 크기·굵기·정렬입니다. 생략된 굵기는 400, 정렬은 left입니다." },
+        { "name": "color / textColor", "description": "color는 도형·노트 채우기·독립 글자색·path 선 색이고 textColor는 도형·노트 본문 색입니다." },
+        { "name": "fontSize / fontWeight / textAlign", "description": "본문의 크기·굵기·정렬입니다. 도형·노트의 생략된 크기는 24, 굵기는 400, 정렬은 도형 center·노트와 독립 글자 left입니다." },
         { "name": "strokeColor / strokeWidth", "description": "도형 테두리는 기본 #000000·0이며 path는 color와 양의 strokeWidth를 사용합니다." }
       ],
       "sourcePath": "packages/json-document-object-document/src/object-model.ts",
@@ -220,11 +220,11 @@
         {
           "id": "projection",
           "role": "Projection",
-          "knowledge": "Object bounds·path 정규화",
-          "decision": "preview와 commit의 동일한 기하",
+          "knowledge": "Object bounds·path 정규화·본문 capability와 배치",
+          "decision": "preview/commit의 동일한 기하와 표시/입력의 동일한 본문 projection",
           "changeReason": "기하 표현 변경",
           "stateLifecycle": "문서 값 또는 stateless 계산",
-          "inputsOutputs": "transformObject의 public 계약",
+          "inputsOutputs": "transformObject와 projectObjectText의 public 계약",
           "currentOwner": "@interactive-os/json-document-object-document",
           "canonicalEvidence": "packages/json-document-object-document/src/object-projection.ts와 공개 entrypoint·package API 문서·Canvas Usage/Source",
           "sourcePath": "packages/json-document-object-document/src/object-projection.ts",
diff --git a/docs/api-reference/canvas.md b/docs/api-reference/canvas.md
index 261f92b8..a469bca9 100644
--- a/docs/api-reference/canvas.md
+++ b/docs/api-reference/canvas.md
@@ -24,6 +24,8 @@ interface CanvasCreationStyle {
   readonly textColor: string;
   readonly fontSize: number;
   readonly strokeWidth: number;
+  /** Sticky-note fill; omitted hosts reuse their ordinary object fill. */
+  readonly stickyNoteColor?: string;
 }
 ```
 ## `CanvasHand`
diff --git a/docs/api-reference/object-document.md b/docs/api-reference/object-document.md
index e8ba6f5f..cf9975cf 100644
--- a/docs/api-reference/object-document.md
+++ b/docs/api-reference/object-document.md
@@ -45,8 +45,8 @@ type CanvasObject = CanvasObjectDraft & { readonly id: string };
 
 ```ts
 type CanvasObjectDraft = ObjectDraft & (
-  | { readonly kind: "text"; readonly fontSize: number; readonly fontWeight?: 400 | 700; readonly textAlign?: "left" | "center" | "right" }
-  | { readonly kind: "rectangle" | "ellipse"; readonly strokeColor?: string; readonly strokeWidth?: number }
+  | (CanvasTextFormat & { readonly kind: "text"; readonly fontSize: number })
+  | (CanvasTextFormat & { readonly kind: "rectangle" | "ellipse" | "sticky-note"; readonly textColor?: string; readonly strokeColor?: string; readonly strokeWidth?: number })
   | { readonly kind: "path"; readonly points: ReadonlyArray<ObjectPoint>; readonly strokeWidth: number }
   | { readonly kind: "image"; readonly source: string }
 );
@@ -54,7 +54,16 @@ type CanvasObjectDraft = ObjectDraft & (
 ## `CanvasObjectKind`
 
 ```ts
-type CanvasObjectKind = "text" | "rectangle" | "ellipse" | "path" | "image";
+type CanvasObjectKind = "text" | "rectangle" | "ellipse" | "sticky-note" | "path" | "image";
+```
+## `CanvasTextFormat`
+
+```ts
+interface CanvasTextFormat {
+  readonly fontSize?: number;
+  readonly fontWeight?: 400 | 700;
+  readonly textAlign?: "left" | "center" | "right";
+}
 ```
 ## `createCanvasImage`
 
@@ -64,7 +73,7 @@ createCanvasImage(image: { readonly source: string; readonly width: number; read
 ## `createCanvasObject`
 
 ```ts
-createCanvasObject(kind: Exclude<CanvasObjectKind, "path" | "image">, bounds: ObjectBounds, style: { readonly color: string; readonly label: string; readonly fontSize?: number; }): CanvasObjectDraft
+createCanvasObject(kind: Exclude<CanvasObjectKind, "path" | "image">, bounds: ObjectBounds, style: { readonly color: string; readonly label: string; readonly fontSize?: number; readonly textColor?: string; }): CanvasObjectDraft
 ```
 ## `createCanvasPath`
 
@@ -140,6 +149,8 @@ interface ObjectPoint extends Record<string, JSONValue> {
 ```ts
 interface ObjectStyle {
   readonly color: string;
+  /** Body text paint for filled objects; standalone text keeps its existing color field. */
+  readonly textColor: string;
   readonly fontSize: number;
   readonly fontWeight: 400 | 700;
   readonly textAlign: "left" | "center" | "right";
@@ -152,6 +163,14 @@ interface ObjectStyle {
 ```ts
 type ObjectStyleSelection = { readonly [Key in keyof ObjectStyle]?: ObjectStyle[Key] | null };
 ```
+## `ObjectTextProjection`
+
+```ts
+interface ObjectTextProjection extends ObjectBounds, Pick<ObjectStyle, "fontSize" | "fontWeight" | "textAlign" | "color"> {
+  readonly text: string;
+  readonly verticalAlign: "top" | "center";
+}
+```
 ## `ObjectTransform`
 
 ```ts
@@ -177,6 +196,11 @@ planObjectOperation(document: ObjectDocument, operation: ObjectOperation): Objec
 ```ts
 projectObject(object: DocumentObject): CanvasObject
 ```
+## `projectObjectText`
+
+```ts
+projectObjectText(object: DocumentObject): ObjectTextProjection | null
+```
 ## `readObjectStyle`
 
 ```ts
diff --git a/docs/public/intent.md b/docs/public/intent.md
index e28f05b4..9cfd24bf 100644
--- a/docs/public/intent.md
+++ b/docs/public/intent.md
@@ -117,6 +117,7 @@ commit은 되돌아가지 않습니다. Selection mapping/reconciliation callbac
 | `selection.remove` | | 선택한 객체 제거 |
 | `selection.fill` | `color` | 선택한 객체 색 변경 |
 | `selection.style` | `style` | 지원하는 선택 객체의 색·글자 서식·테두리를 한 번 변경 |
+| `object.text` | `objectId`, `text` | 글자·도형·스티커 노트의 label 본문 변경 |
 | `object.translate` | `objectIds`, `dx`, `dy` | 선택한 객체 위치 이동 |
 | `object.resize` | `objectIds`, `dx`, `dy`, `dw`, `dh` | 선택한 객체 크기 |
 | `clipboard.paste` | `clipboard` | 붙여넣기 |
diff --git a/docs/public/object.md b/docs/public/object.md
index 528d7f62..118b752c 100644
--- a/docs/public/object.md
+++ b/docs/public/object.md
@@ -7,6 +7,9 @@ Object는 안정된 ID를 가진 객체를 집는 편집기입니다. 줄 번호
 
 생성·글자 편집·색 채우기·이동·resize·삭제는 Intent로 들어갑니다. 문서의 기하
 규칙은 Document Type이, 화면 좌표와 hit target은 Adapter와 Hand가 소유합니다.
+Canvas의 스티커 노트와 도형 내부 글도 별도 편집기 없이 같은 `object.text`로
+label을 바꿉니다. 채워진 객체의 본문 글자색은 `selection.style`의 `style.textColor`로,
+채우기는 기존 `color`로 구분합니다.
 
 ## API Reference
 
diff --git a/packages/json-document-canvas/README.md b/packages/json-document-canvas/README.md
index bb780a3b..939643f6 100644
--- a/packages/json-document-canvas/README.md
+++ b/packages/json-document-canvas/README.md
@@ -1,7 +1,8 @@
 # Canvas Hand
 
 `@interactive-os/json-document-canvas`는 한 장의 Object Canvas 프로파일에서
-글자·사각형·타원·그리기를 완성하는 React Hand입니다. 별도 Canvas editor나
+글자·사각형·타원·스티커 노트·그리기를 완성하는 React Hand입니다. 도형과 노트의
+본문도 같은 plain-text 입력과 스타일 API로 편집합니다. 별도 Canvas editor나
 selection/history 구현을 만들지 않고 기존 `createObjectEditor`를 사용합니다.
 재사용 가능한 Plane Select profile로 다중 선택·Alt 복제·Shift 축 고정·방향키 이동을,
 Object Editing과 Web Clipboard로 선택 copy/cut/paste·Mod+D·Undo/Redo를 연결합니다.
@@ -15,7 +16,7 @@ import { CanvasHand } from "@interactive-os/json-document-canvas";
 
 function Slide() {
   const [editor] = useState(() => createObjectEditor({ profile: "canvas/1", width: 1280, height: 720, objects: [] }));
-  return <CanvasHand editor={editor} creationStyle={{ color: "#b6c8e8", textColor: "#253044", fontSize: 36, strokeWidth: 4 }} />;
+  return <CanvasHand editor={editor} creationStyle={{ color: "#b6c8e8", textColor: "#253044", stickyNoteColor: "#fff2a8", fontSize: 36, strokeWidth: 4 }} />;
 }
 ```
 
diff --git a/packages/json-document-canvas/docs/api.md b/packages/json-document-canvas/docs/api.md
index 13c87d2a..801a7176 100644
--- a/packages/json-document-canvas/docs/api.md
+++ b/packages/json-document-canvas/docs/api.md
@@ -1,6 +1,6 @@
 ## Canvas Hand 계약 · RC
 
-`CanvasHand`는 `ObjectEditor`와 `CanvasCreationStyle`을 받아 글자·사각형·타원·자유
+`CanvasHand`는 `ObjectEditor`와 `CanvasCreationStyle`을 받아 글자·사각형·타원·스티커 노트·자유
 그리기, 이미지·텍스트 붙여넣기, 다중 선택, 선택 스타일, 집합 이동·복제·삭제, native Clipboard, primary resize, Undo/Redo, JSON 재열기를 연결합니다.
 `useCanvasHand`는 같은 입력 조합을 custom UI에서 사용할 수 있게 공개합니다.
 
@@ -28,7 +28,7 @@ Host: 한 장 fixture, 크기·색상 정책, 레이아웃
 ### 입력과 History
 
 - 도구를 고르고 클릭하면 기본 크기, 드래그하면 지정한 크기로 생성합니다.
-  사각형·타원·글자는 누르거나 작게 흔들리는 동안 기본 크기를 미리 표시하지 않습니다.
+  사각형·타원·글자·노트는 누르거나 작게 흔들리는 동안 기본 크기를 미리 표시하지 않습니다.
   시작점에서 3 문서 단위 이상 움직이면 실제 드래그 상자만 표시하며, 다시 시작점 근처로
   돌아와도 클릭 크기로 바뀌지 않습니다. 클릭 기본 크기는 놓을 때 press 위치에만 생성합니다.
   드래그 후 시작점에 정확히 돌아와 놓으면 객체나 History를 만들지 않습니다.
@@ -40,11 +40,17 @@ Host: 한 장 fixture, 크기·색상 정책, 레이아웃
   선택 윤곽은 모두 그리지만 네 변·네 모서리 resize targets는 primary 하나에만 붙습니다.
   Delete는 집합 전체를 한 번 삭제하며 primary resize/text 편집은 기존 선택 집합을 보존합니다.
   Focus만으로 선택하지 않으며, focused 객체에서 Space/Shift+Space로 선택/toggle합니다.
-  focused 객체의 Enter는 그 객체를 선택하고 글자라면 편집합니다. 슬라이드 자체의
+  focused 객체의 Enter는 그 객체를 선택하고 본문이 있는 글자·도형·노트라면 편집합니다. 슬라이드 자체의
   Enter/F2는 현재 primary를 편집하며, F2는 객체에 focus가 있어도 primary를 대상으로 합니다.
-- 글자는 생성 직후 또는 더블클릭/F2/Enter로 편집합니다. 줄바꿈·IME·선택·native
+- 글자·노트는 생성 직후, 사각형·타원은 더블클릭/F2/Enter로 편집합니다.
+  기존 글자·노트도 같은 더블클릭/F2/Enter를 사용합니다. 줄바꿈·IME·선택·native
   입력 Undo는 textarea에 남습니다. blur 또는 Mod+Enter가 전체 draft를 한 번 commit하고
   Escape는 draft만 버립니다. 객체의 label이 실제 문자열 값입니다.
+  노트 클릭 기본 크기는 200×200이며 드래그로 자유 크기를 지정합니다. 생성과 이후
+  본문 확정은 각각 한 번의 Undo입니다. 새 노트에서 Escape하면 빈 노트는 남습니다.
+  도형은 내부 중앙, 노트는 여백을 둔 상단이며 `projectObjectText`를 표시와 입력이 공유합니다.
+  편집 중에도 채우기와 테두리는 유지합니다. 상자 밖 본문은 clip하며 입력 중에는 native
+  textarea 스크롤로 긴 내용을 편집할 수 있습니다. 자동 글자 축소나 상자 자동 확대는 하지 않습니다.
 - Alt/Option+drag는 선택 집합을 복제합니다. 원본을 남기고 사본 위치를 preview하며
   release에 새 ID를 할당합니다. Alt를 도중에 누르거나 놓으면 copy/move가 전환됩니다.
   Shift+drag는 큰 delta 축을 고정하며 Shift+click toggle과 구분합니다.
@@ -75,6 +81,9 @@ Select 도구에서 스타일을 지원하는 객체가 선택되면 팔레트 
 Enter 또는 적용 아이콘으로 확정하고, Escape·바깥 클릭으로 닫으면 미확정 입력은 버립니다.
 이미지만 선택한 경우에는 스타일 컨트롤이 없습니다.
 
+도형·노트에는 `색상`(채우기)과 `글자색`이 따로 나타납니다. 글자 크기·굵기·정렬도
+같은 선택 스타일 API로 적용합니다. 독립 글자는 기존 `색상`을 글자색으로 씁니다.
+
 혼합 선택은 `readObjectStyle`의 `null`을 `혼합`으로 드러냅니다. 색·크기·정렬을 임의의
 primary 값으로 표시하지 않습니다. 속성은 이를 지원하는 선택 객체에만 적용하고 전체
 선택과 primary를 보존합니다. 굵기가 모두 0인 도형에 테두리색을 고르면 2 단위로 함께
@@ -142,6 +151,8 @@ JSON 버튼은 현재 문서 문자열을 노출합니다. 이 문자열을 저
 단일 슬라이드를 컨테이너에 맞춰 표시합니다. 확대/축소·페이지·팬·다중 resize·그룹·회전·
 snap·레이어·PPTX·collaboration은 이번 Hand의 지원 범위가 아닙니다.
 `creationStyle`은 새 객체에만 적용하는 제품 기본값이며 저장 객체의 스타일을 덮어쓰지 않습니다.
+`stickyNoteColor`로 새 노트의 채우기를 지정하며 생략하면 `color`를 사용합니다.
+노트·도형의 본문은 `textColor`와 `fontSize` 생성 기본값을 받습니다.
 
 선택은 Affordance의 [평면 Select 프로파일](/docs/api/affordance)을 소비합니다.
 `selectProfile`을 주입하거나 생략하여 기본 instance를 만들 수 있습니다. instance는 Hand마다
diff --git a/packages/json-document-canvas/src/canvas-hand.tsx b/packages/json-document-canvas/src/canvas-hand.tsx
index 3f533ab7..9e7647a5 100644
--- a/packages/json-document-canvas/src/canvas-hand.tsx
+++ b/packages/json-document-canvas/src/canvas-hand.tsx
@@ -1,5 +1,5 @@
 import { useState, type CSSProperties } from "react";
-import { Braces, Circle, CopyPlus, MousePointer2, Pencil, RectangleHorizontal, Redo2, Trash2, Type, Undo2, type LucideIcon } from "lucide-react";
+import { Braces, Circle, CopyPlus, MousePointer2, Pencil, RectangleHorizontal, Redo2, StickyNote, Trash2, Type, Undo2, type LucideIcon } from "lucide-react";
 import type { ObjectEditor } from "@interactive-os/json-document-editing";
 import type { PlaneSelectProfile } from "@interactive-os/json-document-affordance";
 import { serializeCanvasDocument } from "@interactive-os/json-document-object-document";
@@ -20,6 +20,7 @@ export interface CanvasHandProps {
 
 const tools: ReadonlyArray<{ readonly id: CanvasTool; readonly label: string; readonly icon: LucideIcon }> = [
   { id: "select", label: "선택", icon: MousePointer2 }, { id: "text", label: "글자", icon: Type },
+  { id: "sticky-note", label: "스티커 노트", icon: StickyNote },
   { id: "rectangle", label: "사각형", icon: RectangleHorizontal }, { id: "ellipse", label: "타원", icon: Circle }, { id: "path", label: "그리기", icon: Pencil },
 ];
 
@@ -46,7 +47,7 @@ export function CanvasHand(props: CanvasHandProps) {
         data-canvas-slide="true" data-tool={hand.tool} viewBox={`0 0 ${hand.document.width} ${hand.document.height}`} preserveAspectRatio="none"
         style={{ display: "block", width: "100%", aspectRatio: `${hand.document.width} / ${hand.document.height}`, touchAction: "none", userSelect: "none", overflow: "hidden", ...props.slideStyle }}>
         {hand.objects.map((object) => <g key={object.id} data-canvas-copy-original={copyOriginals.has(object.id) ? object.id : undefined}>
-          {hand.draft?.id !== object.id && <CanvasObjectView object={copyOriginals.get(object.id) ?? object} />}
+          <CanvasObjectView object={copyOriginals.get(object.id) ?? object} hideText={hand.draft?.id === object.id} />
           <CanvasObjectTarget object={object} selected={selectedKeys.has(object.id)} enabled={hand.tool === "select" && hand.draft?.id !== object.id}
             copying={hand.copyOriginals.length > 0 && selectedKeys.has(object.id)}
             onSelect={(shiftKey) => hand.select(object.id, shiftKey)} onEdit={() => hand.editText(object.id)} onHandle={(interaction, event) => hand.interaction(interaction, event, object, "drag")} />
@@ -59,7 +60,7 @@ export function CanvasHand(props: CanvasHandProps) {
           {!hand.draft && (["n", "e", "s", "w", "nw", "ne", "se", "sw"] as const).map((edge) => <CanvasResizeTarget key={edge} object={selected} edge={edge} onHandle={(interaction, event) => hand.interaction(interaction, event, selected, "resize", edge)} />)}
         </g>}
         {hand.marquee && <rect data-canvas-marquee="" {...hand.marquee} fill="rgb(var(--color-border-accent) / 0.08)" stroke="rgb(var(--color-border-accent))" pointerEvents="none" />}
-        {selected?.kind === "text" && hand.draft?.id === selected.id && <CanvasTextInput object={selected} text={hand.draft.text} onChange={hand.changeText}
+        {selected && hand.draft?.id === selected.id && <CanvasTextInput object={selected} text={hand.draft.text} onChange={hand.changeText}
           onCommit={() => { hand.commitText(); hand.surface.current?.focus(); }} onCancel={() => { hand.cancel(); hand.surface.current?.focus(); }} />}
       </svg>
       {hand.pastePending && <p role="status">붙여넣는 중… Escape로 취소</p>}
diff --git a/packages/json-document-canvas/src/canvas-object-view.tsx b/packages/json-document-canvas/src/canvas-object-view.tsx
index da22823d..b683f20d 100644
--- a/packages/json-document-canvas/src/canvas-object-view.tsx
+++ b/packages/json-document-canvas/src/canvas-object-view.tsx
@@ -1,22 +1,35 @@
-import { useEffect, useRef, type PointerEvent, type ReactNode } from "react";
-import { getObjectStyle, type CanvasObject } from "@interactive-os/json-document-object-document";
+import { useEffect, useRef, type CSSProperties, type PointerEvent, type ReactNode } from "react";
+import { getObjectStyle, projectObjectText, type CanvasObject, type ObjectTextProjection } from "@interactive-os/json-document-object-document";
 import type { InteractionHandleEvent, ResizeEdge } from "@interactive-os/json-document-affordance";
 import { contentInteractionAttributes, Field, useInteractionHandle } from "@interactive-os/json-document-ui-primitives-react";
 
-export function CanvasObjectView({ object }: { readonly object: CanvasObject }): ReactNode {
+export function CanvasObjectView({ object, hideText = false }: { readonly object: CanvasObject; readonly hideText?: boolean }): ReactNode {
   const style = getObjectStyle(object);
   if (object.kind === "image") return <image href={object.source} x={object.x} y={object.y} width={object.width} height={object.height} preserveAspectRatio="none" />;
   if (object.kind === "path") {
     return <polyline points={object.points.map((point) => `${object.x + point.x * object.width},${object.y + point.y * object.height}`).join(" ")} fill="none" stroke={object.color} strokeWidth={object.strokeWidth} strokeLinecap="round" strokeLinejoin="round" />;
   }
-  if (object.kind === "text") return (
-    <foreignObject x={object.x} y={object.y} width={object.width} height={object.height}>
-      <div style={{ color: style.color, fontSize: style.fontSize, fontWeight: style.fontWeight, textAlign: style.textAlign, lineHeight: 1.2, whiteSpace: "pre-wrap", overflowWrap: "anywhere", width: "100%", height: "100%", overflow: "hidden" }}>{object.label}</div>
-    </foreignObject>
-  );
-  return object.kind === "ellipse"
-    ? <ellipse cx={object.x + object.width / 2} cy={object.y + object.height / 2} rx={object.width / 2} ry={object.height / 2} fill={object.color} stroke={style.strokeColor} strokeWidth={style.strokeWidth} />
-    : <rect x={object.x} y={object.y} width={object.width} height={object.height} fill={object.color} stroke={style.strokeColor} strokeWidth={style.strokeWidth} />;
+  const text = projectObjectText(object);
+  return <>
+    {object.kind === "ellipse"
+      ? <ellipse cx={object.x + object.width / 2} cy={object.y + object.height / 2} rx={object.width / 2} ry={object.height / 2} fill={object.color} stroke={style.strokeColor} strokeWidth={style.strokeWidth} />
+      : object.kind !== "text" && <rect x={object.x} y={object.y} width={object.width} height={object.height} fill={object.color} stroke={style.strokeColor} strokeWidth={style.strokeWidth} />}
+    {!hideText && text && <CanvasTextBox value={text}><div>{text.text + "\u200b"}</div></CanvasTextBox>}
+  </>;
+}
+
+function textPresentation(value: ObjectTextProjection): CSSProperties {
+  return { color: value.color, fontSize: value.fontSize, fontWeight: value.fontWeight, textAlign: value.textAlign,
+    fontFamily: "inherit", lineHeight: 1.2, whiteSpace: "pre-wrap", overflowWrap: "anywhere", letterSpacing: "normal" };
+}
+
+/** The same body box and line wrapping serve display and the native textarea. */
+function CanvasTextBox({ value, children }: { readonly value: ObjectTextProjection; readonly children: ReactNode }) {
+  return <foreignObject data-canvas-text-box="" x={value.x} y={value.y} width={value.width} height={value.height}>
+    <div style={{ ...textPresentation(value), display: "flex", flexDirection: "column", justifyContent: value.verticalAlign === "center" ? "safe center" : "flex-start", width: "100%", height: "100%", overflow: "hidden" }}>
+      <div style={{ position: "relative", flexShrink: 0, minHeight: value.fontSize * 1.2, maxHeight: "100%", overflow: "hidden" }}>{children}</div>
+    </div>
+  </foreignObject>;
 }
 
 export function CanvasObjectTarget(props: {
@@ -68,7 +81,7 @@ export function CanvasResizeTarget(props: {
 }
 
 export function CanvasTextInput(props: {
-  readonly object: Extract<CanvasObject, { readonly kind: "text" }>;
+  readonly object: CanvasObject;
   readonly text: string;
   readonly onChange: (text: string) => void;
   readonly onCommit: () => void;
@@ -77,11 +90,13 @@ export function CanvasTextInput(props: {
   const input = useRef<HTMLTextAreaElement>(null);
   useEffect(() => { input.current?.focus(); input.current?.select(); }, [props.object.id]);
   const { object } = props;
-  const style = getObjectStyle(object);
+  const text = projectObjectText(object);
+  if (!text) return null;
   return (
-    <foreignObject x={object.x} y={object.y} width={object.width} height={object.height}>
+    <CanvasTextBox value={text}>
+      <div aria-hidden="true" style={{ visibility: "hidden" }}>{props.text + "\u200b"}</div>
       <Field multiline presentation="seamless" label="Canvas text" controlRef={input} value={props.text} onValueChange={props.onChange}
-        style={{ color: style.color, fontSize: style.fontSize, fontWeight: style.fontWeight, textAlign: style.textAlign, lineHeight: 1.2, padding: 0, margin: 0, border: 0, width: "100%", height: "100%", resize: "none", background: "transparent", boxSizing: "border-box" }}
+        style={{ ...textPresentation(text), position: "absolute", inset: 0, minWidth: 0, minHeight: 0, padding: 0, margin: 0, border: 0, width: "100%", height: "100%", resize: "none", background: "transparent", boxSizing: "border-box", userSelect: "text" }}
         onBlur={props.onCommit}
         onKeyDown={(event) => {
           event.stopPropagation();
@@ -89,6 +104,6 @@ export function CanvasTextInput(props: {
           if (event.key === "Escape") { event.preventDefault(); props.onCancel(); }
           else if (event.key === "Enter" && (event.metaKey || event.ctrlKey)) { event.preventDefault(); props.onCommit(); }
         }} />
-    </foreignObject>
+    </CanvasTextBox>
   );
 }
diff --git a/packages/json-document-canvas/src/canvas-style-controls.tsx b/packages/json-document-canvas/src/canvas-style-controls.tsx
index 83a5afc0..00fde91b 100644
--- a/packages/json-document-canvas/src/canvas-style-controls.tsx
+++ b/packages/json-document-canvas/src/canvas-style-controls.tsx
@@ -24,6 +24,7 @@ export function CanvasStyleControls(props: {
   return <Popover label="스타일" trigger={<Palette aria-hidden="true" size={16} />} triggerPresentation="icon"
     open={open} onOpenChange={(next) => { if (next) props.onOpen(); setOpen(next); }} panelClassName="canvas-style-panel">
     {value.color !== undefined && <StyleValue key={`color:${value.color}`} label="색상" value={value.color} color onApply={(color) => apply({ color })} />}
+    {value.textColor !== undefined && <StyleValue key={`text:${value.textColor}`} label="글자색" value={value.textColor} color onApply={(textColor) => apply({ textColor })} />}
     {value.strokeColor !== undefined && <StyleValue key={`stroke:${value.strokeColor}`} label="테두리 색" value={value.strokeColor} color
       onApply={(strokeColor) => apply({ strokeColor, ...(value.strokeWidth === 0 && strokeColor !== "transparent" ? { strokeWidth: 2 } : {}) })} />}
     {value.fontSize !== undefined && <StyleValue key={`size:${value.fontSize}`} label="글자 크기" value={value.fontSize} onApply={(fontSize) => apply({ fontSize: Number(fontSize) })} />}
diff --git a/packages/json-document-canvas/src/use-canvas-hand.ts b/packages/json-document-canvas/src/use-canvas-hand.ts
index 07888876..f97cd0bc 100644
--- a/packages/json-document-canvas/src/use-canvas-hand.ts
+++ b/packages/json-document-canvas/src/use-canvas-hand.ts
@@ -1,6 +1,6 @@
 import { useEffect, useMemo, useReducer, useRef, useState, type ClipboardEvent, type KeyboardEvent, type PointerEvent } from "react";
 import { commitAffordance, createGestureSession, createPlaneSelectProfile, resizeAffordance, type InteractionHandleEvent, type PlaneSelectProfile, type PlaneSelectSelection, type ResizeEdge } from "@interactive-os/json-document-affordance";
-import { assertCanvasDocument, createCanvasObject, createCanvasPath, parseCanvasDocument, readObjectStyle, transformObject, type CanvasDocument, type CanvasObject, type CanvasObjectKind, type ObjectPoint, type ObjectStyle } from "@interactive-os/json-document-object-document";
+import { assertCanvasDocument, createCanvasObject, createCanvasPath, parseCanvasDocument, projectObjectText, readObjectStyle, transformObject, type CanvasDocument, type CanvasObject, type CanvasObjectKind, type ObjectPoint, type ObjectStyle } from "@interactive-os/json-document-object-document";
 import type { EditingResult, ObjectEditor, ObjectIntent, ObjectSelection } from "@interactive-os/json-document-editing";
 import { useEditingSnapshot } from "@interactive-os/json-document-react";
 import { createWebKeyboardAdapter, createWebPointerSession, isWebEditableTarget, projectWebClientPointToSVG, webSVGViewportFromElement } from "@interactive-os/json-document-web";
@@ -12,6 +12,8 @@ export interface CanvasCreationStyle {
   readonly textColor: string;
   readonly fontSize: number;
   readonly strokeWidth: number;
+  /** Sticky-note fill; omitted hosts reuse their ordinary object fill. */
+  readonly stickyNoteColor?: string;
 }
 
 type Gesture = { readonly base: CanvasDocument } & (
@@ -114,7 +116,7 @@ export function useCanvasHand(editor: ObjectEditor, style: CanvasCreationStyle,
   function editText(id: string) {
     const base = current();
     const object = base.objects.find((item) => item.id === id);
-    if (object?.kind !== "text") return;
+    if (!object || !projectObjectText(object)) return;
     cancel();
     if (editor.snapshot.selection.primaryKey !== id) applySelection(profile.select(selectContext(), id));
     draft.current = { id, text: object.label, base };
@@ -149,9 +151,10 @@ export function useCanvasHand(editor: ObjectEditor, style: CanvasCreationStyle,
     if (!click && start.x === point.x && start.y === point.y) return null;
     return createCanvasObject(gesture.tool, {
       x: click ? start.x : Math.min(start.x, point.x), y: click ? start.y : Math.min(start.y, point.y),
-      width: click ? (gesture.tool === "text" ? 280 : 160) : Math.abs(point.x - start.x),
-      height: click ? (gesture.tool === "text" ? 64 : 100) : Math.abs(point.y - start.y),
-    }, { color: gesture.tool === "text" ? style.textColor : style.color, label: gesture.tool === "text" ? "Text" : "", fontSize: style.fontSize });
+      width: click ? (gesture.tool === "text" ? 280 : gesture.tool === "sticky-note" ? 200 : 160) : Math.abs(point.x - start.x),
+      height: click ? (gesture.tool === "text" ? 64 : gesture.tool === "sticky-note" ? 200 : 100) : Math.abs(point.y - start.y),
+    }, { color: gesture.tool === "text" ? style.textColor : gesture.tool === "sticky-note" ? style.stickyNoteColor ?? style.color : style.color,
+      label: gesture.tool === "text" ? "Text" : "", fontSize: style.fontSize, textColor: style.textColor });
   }
 
   function transform(gesture: Extract<Gesture, { type: "resize" }>) {
@@ -170,7 +173,7 @@ export function useCanvasHand(editor: ObjectEditor, style: CanvasCreationStyle,
       if (result.ok) {
         setTool("select");
         const id = result.snapshot.selection.primaryKey;
-        if (active.type === "create" && active.tool === "text" && id) editText(id);
+        if (active.type === "create" && (active.tool === "text" || active.tool === "sticky-note") && id) editText(id);
       }
     } else {
       const delta = transform(active);
diff --git a/packages/json-document-canvas/tests/canvas-hand.test.tsx b/packages/json-document-canvas/tests/canvas-hand.test.tsx
index 8ebaf208..649a5fcc 100644
--- a/packages/json-document-canvas/tests/canvas-hand.test.tsx
+++ b/packages/json-document-canvas/tests/canvas-hand.test.tsx
@@ -232,7 +232,7 @@ test("Enter activates the focused object instead of editing an unrelated primary
   const box = container.querySelector('[data-canvas-object="b"]')!;
   fireEvent.focus(box); fireEvent.keyDown(box, { key: "Enter" });
   expect(editor.snapshot.selection.keys).toEqual(["b"]);
-  expect(screen.queryByRole("textbox", { name: "Canvas text" })).toBeNull();
+  expect((screen.getByRole("textbox", { name: "Canvas text" }) as HTMLTextAreaElement).value).toBe("Box");
   const text = container.querySelector('[data-canvas-object="a"]')!;
   fireEvent.focus(text); fireEvent.keyDown(text, { key: "Enter" });
   expect(editor.snapshot.selection.keys).toEqual(["a"]);
@@ -331,7 +331,7 @@ test("external selection changes supersede a pending preview without a stale sel
 test("every toolbar control shares icon, accessible name and canonical tooltip without losing state", () => {
   const { svg } = setup();
   const toolbar = within(screen.getByRole("toolbar", { name: "Canvas tools" }));
-  const labels = ["선택", "글자", "사각형", "타원", "그리기", "실행 취소", "다시 실행", "복제", "삭제", "JSON"];
+  const labels = ["선택", "글자", "스티커 노트", "사각형", "타원", "그리기", "실행 취소", "다시 실행", "복제", "삭제", "JSON"];
   expect(toolbar.getAllByRole("button")).toHaveLength(labels.length);
   for (const label of labels) {
     const button = toolbar.getByRole("button", { name: label });
@@ -353,6 +353,7 @@ const creationTools = [
   { tool: "사각형", kind: "rectangle", width: 160, height: 100 },
   { tool: "타원", kind: "ellipse", width: 160, height: 100 },
   { tool: "글자", kind: "text", width: 280, height: 64 },
+  { tool: "스티커 노트", kind: "sticky-note", width: 200, height: 200 },
 ] as const;
 
 function creationPreview(container: HTMLElement) {
@@ -391,7 +392,7 @@ test.each(creationTools)("$kind click creates its default size only on release a
   fireEvent.pointerUp(svg, event(39.5, 49.5));
   expect(value().objects[0]).toMatchObject({ kind, x: 80, y: 100, width, height });
   expect(commits).toHaveBeenCalledOnce();
-  expect(screen.queryByRole("textbox", { name: "Canvas text" }) !== null).toBe(kind === "text");
+  expect(screen.queryByRole("textbox", { name: "Canvas text" }) !== null).toBe(kind === "text" || kind === "sticky-note");
 });
 
 test.each(creationTools)("$kind stays a drag near the origin and an exact return creates nothing", ({ tool, width, height }) => {
@@ -509,7 +510,7 @@ test("resize switches Shift/Alt live and commits the release coordinates and mod
   expect(commits).toHaveBeenCalledOnce(); expect(value().objects).toHaveLength(1);
 });
 
-test.each(["rectangle", "ellipse", "text", "path", "image"] as const)("%s uses the same west-edge clamp without changing its content", (kind) => {
+test.each(["rectangle", "ellipse", "sticky-note", "text", "path", "image"] as const)("%s uses the same west-edge clamp without changing its content", (kind) => {
   const object = { id: "a", x: 100, y: 100, width: 200, height: 100, color: "blue", label: "Content", kind,
     ...(kind === "text" ? { fontSize: 24 } : kind === "path" ? { points: [{ x: 0, y: 0 }, { x: 1, y: 1 }], strokeWidth: 3 } : kind === "image" ? { source: "data:image/png;base64,AQID" } : {}) } as CanvasDocument["objects"][number];
   const { container, value } = setup({ ...blank, objects: [object] });
@@ -702,3 +703,72 @@ test("opening style cancels a resize preview and stale pointer release cannot ov
   fireEvent.pointerUp(window, event(150, 150));
   expect(value().objects[0]).toEqual({ ...populated.objects[0], color: "#ef4444" }); expect(commits).toHaveBeenCalledOnce();
 });
+
+test.each(["rectangle", "ellipse", "sticky-note"] as const)("%s edits inside the same body box, retains its fill and shares draft/IME/history behavior", (kind) => {
+  const object = { ...populated.objects[1]!, kind, label: "기존 본문", textColor: "purple", fontSize: 28, fontWeight: 700 as const, textAlign: "right" as const };
+  const { container, svg, editor, value, commits } = setup({ ...populated, objects: [populated.objects[0]!, object] });
+  act(() => { editor.dispatch({ type: "selection.set", objectIds: ["a", "b"], primaryKey: "b" }); });
+  const target = container.querySelector('[data-canvas-object="b"]')!;
+  const displayed = target.parentElement!.querySelector("[data-canvas-text-box]")!;
+  const bounds = ["x", "y", "width", "height"].map((key) => displayed.getAttribute(key));
+  fireEvent.doubleClick(target);
+  const input = screen.getByRole("textbox", { name: "Canvas text" }) as HTMLTextAreaElement;
+  expect(input.value).toBe(object.label); expect(document.activeElement).toBe(input);
+  expect(["x", "y", "width", "height"].map((key) => input.closest("[data-canvas-text-box]")!.getAttribute(key))).toEqual(bounds);
+  expect(target.parentElement!.querySelector(`${kind === "ellipse" ? "ellipse" : "rect"}[fill="blue"]`)).not.toBeNull();
+  expect(input.style.color).toBe("purple"); expect(input.style.fontSize).toBe("28px"); expect(input.style.fontWeight).toBe("700"); expect(input.style.textAlign).toBe("right");
+  fireEvent.change(input, { target: { value: "한글\n💡" } });
+  fireEvent.keyDown(input, { key: "Enter", metaKey: true, isComposing: true });
+  fireEvent.keyDown(input, { key: "Escape", isComposing: true });
+  expect(screen.getByRole("textbox", { name: "Canvas text" })).toBe(input); expect(commits).not.toHaveBeenCalled();
+  fireEvent.keyDown(input, { key: "Enter", metaKey: true });
+  expect(value().objects[1]).toEqual({ ...object, label: "한글\n💡" }); expect(commits).toHaveBeenCalledOnce();
+  expect(editor.snapshot.selection).toMatchObject({ keys: ["a", "b"], primaryKey: "b" });
+  fireEvent.keyDown(svg, { key: "F2" });
+  fireEvent.change(screen.getByRole("textbox", { name: "Canvas text" }), { target: { value: "버릴 내용" } });
+  fireEvent.keyDown(screen.getByRole("textbox", { name: "Canvas text" }), { key: "Escape" });
+  expect(value().objects[1]!.label).toBe("한글\n💡"); expect(commits).toHaveBeenCalledOnce();
+  act(() => { editor.undo(); }); expect(value().objects[1]).toEqual(object);
+  act(() => { editor.redo(); }); expect(value().objects[1]!.label).toBe("한글\n💡");
+});
+
+test("new sticky notes accept immediate text, use host fill policy and copy through the existing native binding", () => {
+  const { svg, container, value, rerender, editor } = setup();
+  rerender(<CanvasHand editor={editor} creationStyle={{ ...style, stickyNoteColor: "#fff2a8" }} />);
+  fireEvent.click(screen.getByRole("button", { name: "스티커 노트" }));
+  fireEvent.pointerDown(svg, event(40, 50)); fireEvent.pointerUp(svg, event(40, 50));
+  const input = screen.getByRole("textbox", { name: "Canvas text" });
+  expect(value().objects[0]).toMatchObject({ kind: "sticky-note", label: "", color: "#fff2a8", textColor: style.textColor });
+  fireEvent.change(input, { target: { value: "작은 아이디어\n한 장" } }); fireEvent.blur(input);
+  expect(container.querySelectorAll("[data-resize-edge]")).toHaveLength(8);
+  const data = clipboardData(); clipboardEvent(svg, "copy", data);
+  expect(data.getData("text/plain")).toBe("작은 아이디어\n한 장");
+  clipboardEvent(svg, "paste", data);
+  expect(value().objects[1]).toEqual({ ...value().objects[0], id: "object-2", x: 104, y: 124 });
+  fireEvent.click(screen.getByRole("button", { name: "실행 취소" })); expect(value().objects).toHaveLength(1);
+});
+
+test("filled objects expose independent body color without repainting their backgrounds", () => {
+  const { container, editor, value } = setup({ ...populated, objects: [...populated.objects, { ...populated.objects[1]!, id: "note", kind: "sticky-note", textColor: "red" }] });
+  act(() => { editor.dispatch({ type: "selection.set", objectIds: ["b", "note"], primaryKey: "note" }); });
+  fireEvent.click(screen.getByRole("button", { name: "스타일" }));
+  expect((screen.getByRole("textbox", { name: "글자색" }) as HTMLInputElement).placeholder).toBe("혼합");
+  fireEvent.click(screen.getByRole("button", { name: "글자색: 빨강" }));
+  expect(value().objects[1]).toMatchObject({ textColor: "#ef4444", color: "blue" });
+  expect(value().objects[3]).toMatchObject({ textColor: "#ef4444", color: "blue" });
+  fireEvent.keyDown(screen.getByRole("dialog", { name: "스타일" }), { key: "Escape" });
+  fireEvent.doubleClick(container.querySelector('[data-canvas-object="note"]')!);
+  expect((screen.getByRole("textbox", { name: "Canvas text" }) as HTMLTextAreaElement).style.color).toBe("rgb(239, 68, 68)");
+});
+
+test.each(["", "끝의 빈 줄\n", "줄\n\n"])("body display and native input measure the same terminal line without storing a layout marker: %j", (label) => {
+  const object = { ...populated.objects[1]!, label };
+  const { container, value, commits } = setup({ ...blank, objects: [object] });
+  const rendered = container.querySelector("[data-canvas-text-box]")!.textContent;
+  fireEvent.doubleClick(container.querySelector("[data-canvas-object]")!);
+  const input = screen.getByRole("textbox", { name: "Canvas text" }) as HTMLTextAreaElement;
+  expect(input.previousElementSibling!.textContent).toBe(rendered);
+  expect(input.value).toBe(label);
+  fireEvent.keyDown(input, { key: "Enter", metaKey: true });
+  expect(value().objects[0]).toEqual(object); expect(commits).not.toHaveBeenCalled();
+});
diff --git a/packages/json-document-editing/docs/object-selection.md b/packages/json-document-editing/docs/object-selection.md
index 0536c64b..8d994227 100644
--- a/packages/json-document-editing/docs/object-selection.md
+++ b/packages/json-document-editing/docs/object-selection.md
@@ -10,6 +10,11 @@
 선택합니다. 따라서 전체 선택 이동, primary만 resize/text 편집을 같은 ObjectEditor로
 실행할 수 있습니다. 문서 연산·검증은 Object Document Type이 소유합니다.
 
+`object.text`는 독립 text뿐 아니라 rectangle·ellipse·sticky-note의 `label` 본문을
+편집합니다. 지원 여부는 `projectObjectText`가 정의하며 image·path·legacy Object의
+메타데이터 label은 편집 대상으로 승격하지 않습니다. 같은 본문은 no-op, 빈 문자열은
+유효한 편집입니다. 도형/노트도 기존 선택·복제·Clipboard·History 경로를 그대로 씁니다.
+
 ```ts
 editor.dispatch({ type: "selection.set", objectIds: ["a", "b"], primaryKey: "a" });
 editor.dispatch({ type: "object.translate", objectIds: ["a", "b"], dx: 20, dy: 10 });
@@ -27,7 +32,8 @@ Intent를 사용합니다. Undo/Redo는 해당 문서 변경과 함께 원인 
 `selection.style`은 `{ style: Partial<ObjectStyle> }`을 받아 선택한 객체에 한 번 적용합니다.
 스타일의 값·기본값·종류별 지원 여부·검증은 [Object Document Type](/docs/api/object-document)의
 `style` 연산에 위임합니다. 예를 들어 글자·도형·이미지를 함께 선택한 뒤 fontSize를 바꾸면
-글자만 바뀌며 이미지와 선택 집합·primary는 유지됩니다.
+글자와 도형 본문이 바뀌며 이미지와 선택 집합·primary는 유지됩니다.
+`textColor`는 도형·노트의 본문 글자색이고 `color`는 기존대로 종류별 주 색상입니다.
 
 ```ts
 editor.dispatch({ type: "selection.style", style: { color: "#3b82f6", fontSize: 48, fontWeight: 700 } });
diff --git a/packages/json-document-editing/tests/object-text.test.ts b/packages/json-document-editing/tests/object-text.test.ts
new file mode 100644
index 00000000..095431c8
--- /dev/null
+++ b/packages/json-document-editing/tests/object-text.test.ts
@@ -0,0 +1,44 @@
+import { expect, test, vi } from "vitest";
+import { createJSONDocument } from "@interactive-os/json-document";
+import { createCanvasObject, parseCanvasDocument, serializeCanvasDocument, type CanvasDocument } from "@interactive-os/json-document-object-document";
+import { createObjectEditor, objectClipboardFormat } from "../src/index.js";
+
+const initial: CanvasDocument = { profile: "canvas/1", width: 1280, height: 720, objects: ["rectangle", "ellipse", "sticky-note"].map((kind, index) => ({
+  ...createCanvasObject(kind as "rectangle" | "ellipse" | "sticky-note", { x: index * 220, y: 100, width: 200, height: 180 }, { label: "", color: "#fff2a8" }), id: kind,
+})) };
+
+test.each(initial.objects)("$kind body editing is one commit and preserves a multi-selection through Undo/Redo", (object) => {
+  const source = createJSONDocument(initial), commits = vi.fn(); source.subscribe(commits);
+  const editor = createObjectEditor(source);
+  editor.dispatch({ type: "selection.set", objectIds: initial.objects.map((item) => item.id), primaryKey: object.id });
+  const selection = editor.snapshot.selection;
+  expect(editor.dispatch({ type: "object.text", objectId: object.id, text: "본문\n💡" }).ok).toBe(true);
+  const written = editor.snapshot.value;
+  expect(commits).toHaveBeenCalledOnce(); expect(editor.snapshot.selection).toEqual(selection);
+  editor.undo(); expect(editor.snapshot.value).toEqual(initial); expect(editor.snapshot.selection).toEqual(selection);
+  editor.redo(); expect(editor.snapshot.value).toEqual(written); expect(editor.snapshot.selection).toEqual(selection);
+  expect(editor.dispatch({ type: "object.text", objectId: object.id, text: "" }).ok).toBe(true);
+  expect(editor.snapshot.value).toEqual(initial);
+});
+
+test("filled body and styles survive resize, duplication, native Clipboard payload, paste, delete and JSON reopen", () => {
+  let id = 0;
+  const editor = createObjectEditor(initial, { createId: () => `copy-${++id}` });
+  initial.objects.forEach((object) => editor.dispatch({ type: "object.text", objectId: object.id, text: `${object.kind}\n한 장` }));
+  editor.dispatch({ type: "selection.set", objectIds: initial.objects.map((object) => object.id), primaryKey: "sticky-note" });
+  editor.dispatch({ type: "selection.style", style: { textColor: "purple", fontSize: 30, fontWeight: 700, textAlign: "right" } });
+  editor.dispatch({ type: "object.resize", objectIds: ["sticky-note"], dx: 0, dy: 0, dw: 40, dh: 20 });
+  const originals = editor.selectedObjects;
+  expect(editor.dispatch({ type: "object.duplicate", objectIds: editor.snapshot.selection.keys }).ok).toBe(true);
+  const copies = editor.selectedObjects;
+  copies.forEach((object, index) => expect(object).toEqual({ ...originals[index], id: object.id, x: originals[index]!.x + 24, y: originals[index]!.y + 24 }));
+  const clipboard = objectClipboardFormat.parse(JSON.parse(JSON.stringify(editor.copy())))!;
+  expect(clipboard.text).toBe("rectangle\n한 장\nellipse\n한 장\nsticky-note\n한 장");
+  expect(editor.dispatch({ type: "clipboard.paste", clipboard }).ok).toBe(true);
+  editor.selectedObjects.forEach((object, index) => expect(object).toEqual({ ...copies[index], id: object.id }));
+  const beforeDelete = editor.snapshot.value, selection = editor.snapshot.selection;
+  expect(editor.dispatch({ type: "selection.remove" }).ok).toBe(true);
+  editor.undo(); expect(editor.snapshot.value).toEqual(beforeDelete); expect(editor.snapshot.selection).toEqual(selection);
+  expect(new Set((beforeDelete as CanvasDocument).objects.map((object) => object.id)).size).toBe(9);
+  expect(createObjectEditor(parseCanvasDocument(serializeCanvasDocument(beforeDelete as CanvasDocument))).snapshot.value).toEqual(beforeDelete);
+});
diff --git a/packages/json-document-object-document/docs/api.md b/packages/json-document-object-document/docs/api.md
index 4d66e2ca..c2cef7b2 100644
--- a/packages/json-document-object-document/docs/api.md
+++ b/packages/json-document-object-document/docs/api.md
@@ -21,8 +21,9 @@ Object도 계속 유효합니다. legacy Object의 생략된 color는 계속 수
 | kind | 추가 문서 값 | 표현 |
 | --- | --- | --- |
 | text | 양의 유한수 fontSize, 선택적 fontWeight·textAlign | label이 실제 내용인 plain text. 별도의 text 복사본 없음 |
-| rectangle | 선택적 strokeColor·strokeWidth | color로 채운 사각형 |
-| ellipse | 선택적 strokeColor·strokeWidth | 경계 상자에 내접하는 타원 |
+| rectangle | 선택적 textColor·fontSize·fontWeight·textAlign·strokeColor·strokeWidth | color로 채운 사각형, label 본문 |
+| ellipse | 같은 선택적 서식 | 경계 상자에 내접하는 타원, label 본문 |
+| sticky-note | 같은 선택적 서식 | 여백을 둔 노트, color 채우기와 label 본문 |
 | path | points, 양의 유한수 strokeWidth | color로 그린 열린 선 |
 | image | source | 문서에 포함한 PNG/JPEG/WebP의 base64 data URL |
 
@@ -30,7 +31,10 @@ path points는 최소 두 개의 `{ x, y }`이며 각 좌표는 `[0, 1]`입니
 대한 정규화 좌표이므로 이동·resize는 상자만 바꾸고 점과 strokeWidth를 보존합니다.
 `createCanvasPath`는 슬라이드 좌표의 점을 이 표현으로 변환합니다. 수평·수직 선의
 퇴화한 축은 최소 1 단위의 상자로 표현합니다. `createCanvasObject`는 도형/글자 초안을
-만들며 ID는 Editing의 `object.create`에서 할당합니다.
+만들며 ID는 Editing의 `object.create`에서 할당합니다. `sticky-note`도 같은 생성 API를
+씁니다. 선택적인 `fontSize`와 `textColor`는 채워진 객체의 본문 서식으로 보존하며,
+독립 text는 기존대로 `color`를 글자색으로 사용합니다. `CanvasTextFormat`은 객체 전체의
+글자 크기·굵기·가로 정렬 계약이며 text만 fontSize가 필수입니다.
 
 `createCanvasImage({ source, width, height, label }, bounds)`는 decode된 자연 크기를
 주어진 상자에 비율을 유지해 맞추며 확대하지 않습니다. image의 color는 공통 모델 호환을
@@ -64,16 +68,33 @@ text, replace를 검증된 JSON Patch로 계획합니다. 성공은 `{ ok: true,
 반대쪽을 통과해도 뒤집지 않습니다. 화면 바깥 좌표는 허용하며 Hand가 슬라이드 밖을
 clip합니다. 위치를 자동 보정하거나 snap하지 않습니다.
 
+`projectObjectText(object): ObjectTextProjection | null`은 본문 편집 가능 여부와 표시·입력의
+공통 projection입니다. text·rectangle·ellipse·sticky-note는 `label`을 `text`로 읽고,
+유효한 글자색·크기·굵기·정렬, 본문 상자(x/y/width/height), `verticalAlign`을 반환합니다.
+image·path·kind 없는 legacy Object에는 null입니다. 확장 필드에 fontSize가 있어도
+본문 capability를 얻지 않습니다. 입력은 검증된 Object 값이어야 합니다.
+
+text는 전체 상자·상단, 사각형은 12단위 여백·중앙, 타원은 내접 사각형·중앙,
+노트는 16단위 여백·상단입니다. 사각형/노트의 여백은 각 축 크기의 1/4 이하로
+제한하여 작은 상자도 양수로 남습니다. resize는 글자 크기를 바꾸지 않으며 넘친 글은
+본문 상자에서 clip합니다. projection은 문서를 변경하지 않습니다.
+
+`text` 연산과 Editing의 `object.text`는 이 capability를 공유합니다. 도형과 노트에 별도
+문자열 필드나 자식 text 객체를 만들지 않습니다. 빈 문자열도 유효하며 지원하지 않는
+객체는 기존 `object.not-text`로 거절합니다.
+
 ### 객체 스타일
 
 `getObjectStyle(object)`는 적용 가능한 속성의 유효값을 반환합니다. 글자의 생략된
-`fontWeight`는 400, `textAlign`은 `left`입니다. 굵기는 400/700, 정렬은
+`fontWeight`는 400, `textAlign`은 `left`입니다. 도형·노트는 생략된 fontSize 24,
+textColor `#253044`, fontWeight 400을 사용하고 정렬은 도형 `center`, 노트 `left`입니다. 굵기는 400/700, 정렬은
 `left`/`center`/`right`를 지원합니다. 도형의 생략된 `strokeColor`는 `#000000`,
 `strokeWidth`는 0이므로 기존 문서는 테두리 없이 그대로 열립니다. 기본값을 읽는 것만으로
 문서를 바꾸지 않으며, 기존 kind 없는 Object는 color만 지원합니다.
 
-`ObjectStyle`의 color는 도형의 채우기·글자색·path의 선 색입니다. strokeColor는
-사각형·타원의 테두리색이며 strokeWidth는 도형과 path의 선 굵기입니다. 이미지에는
+`ObjectStyle`의 color는 도형·노트의 채우기·독립 글자색·path의 선 색입니다. textColor는
+도형·노트의 본문만 칠하며 채우기를 바꾸지 않습니다. 독립 text에 textColor를 적용하지
+않습니다. strokeColor는 사각형·타원·노트의 테두리색이며 strokeWidth는 도형과 path의 선 굵기입니다. 이미지에는
 스타일 속성이 없습니다. 새 스타일의 색 값은 비어 있지 않은 문자열이고, 도형의 굵기는
 0 이상, path의 굵기와 글자 크기는 양의 유한수여야 합니다. 색 문자열의 CSS 해석은
 렌더링 플랫폼의 책임입니다. 부분 문자열 서식이나 Rich Text 모델은 아닙니다.
diff --git a/packages/json-document-object-document/src/index.ts b/packages/json-document-object-document/src/index.ts
index 6a13cbbe..cdc88f23 100644
--- a/packages/json-document-object-document/src/index.ts
+++ b/packages/json-document-object-document/src/index.ts
@@ -1,5 +1,5 @@
-export type { ObjectBounds, ObjectPoint, ObjectDraft, DocumentObject, ObjectDocument, CanvasObjectKind, CanvasObjectDraft, CanvasObject, CanvasDocument } from "./object-model.js";
+export type { ObjectBounds, ObjectPoint, ObjectDraft, DocumentObject, ObjectDocument, CanvasObjectKind, CanvasTextFormat, CanvasObjectDraft, CanvasObject, CanvasDocument } from "./object-model.js";
 export { assertObjectDocument, assertCanvasDocument, assertCanvasImageSource, parseCanvasDocument, serializeCanvasDocument } from "./object-validation.js";
-export { createCanvasObject, createCanvasPath, createCanvasImage, projectObject, transformObject, type ObjectTransform } from "./object-projection.js";
+export { createCanvasObject, createCanvasPath, createCanvasImage, projectObject, projectObjectText, transformObject, type ObjectTransform, type ObjectTextProjection } from "./object-projection.js";
 export { planObjectOperation, type ObjectOperation, type ObjectOperationPlan } from "./object-operation.js";
 export { getObjectStyle, readObjectStyle, assertObjectStyle, type ObjectStyle, type ObjectStyleSelection } from "./object-style.js";
diff --git a/packages/json-document-object-document/src/object-model.ts b/packages/json-document-object-document/src/object-model.ts
index 6bbae248..662404c0 100644
--- a/packages/json-document-object-document/src/object-model.ts
+++ b/packages/json-document-object-document/src/object-model.ts
@@ -26,11 +26,17 @@ export interface ObjectDocument extends Record<string, JSONValue> {
   readonly objects: ReadonlyArray<DocumentObject>;
 }
 
-export type CanvasObjectKind = "text" | "rectangle" | "ellipse" | "path" | "image";
+export type CanvasObjectKind = "text" | "rectangle" | "ellipse" | "sticky-note" | "path" | "image";
+
+export interface CanvasTextFormat {
+  readonly fontSize?: number;
+  readonly fontWeight?: 400 | 700;
+  readonly textAlign?: "left" | "center" | "right";
+}
 
 export type CanvasObjectDraft = ObjectDraft & (
-  | { readonly kind: "text"; readonly fontSize: number; readonly fontWeight?: 400 | 700; readonly textAlign?: "left" | "center" | "right" }
-  | { readonly kind: "rectangle" | "ellipse"; readonly strokeColor?: string; readonly strokeWidth?: number }
+  | (CanvasTextFormat & { readonly kind: "text"; readonly fontSize: number })
+  | (CanvasTextFormat & { readonly kind: "rectangle" | "ellipse" | "sticky-note"; readonly textColor?: string; readonly strokeColor?: string; readonly strokeWidth?: number })
   | { readonly kind: "path"; readonly points: ReadonlyArray<ObjectPoint>; readonly strokeWidth: number }
   | { readonly kind: "image"; readonly source: string }
 );
diff --git a/packages/json-document-object-document/src/object-operation.ts b/packages/json-document-object-document/src/object-operation.ts
index a95012e4..3bb1143d 100644
--- a/packages/json-document-object-document/src/object-operation.ts
+++ b/packages/json-document-object-document/src/object-operation.ts
@@ -1,6 +1,6 @@
 import { applyPatch, buildPointer, jsonEqual, type JSONPatchOperation } from "@interactive-os/json-document";
 import type { DocumentObject, ObjectDocument } from "./object-model.js";
-import { transformObject, type ObjectTransform } from "./object-projection.js";
+import { projectObjectText, transformObject, type ObjectTransform } from "./object-projection.js";
 import { assertObjectDocument } from "./object-validation.js";
 import { assertObjectStyle, getObjectStyle, type ObjectStyle } from "./object-style.js";
 
@@ -52,7 +52,7 @@ export function planObjectOperation(document: ObjectDocument, operation: ObjectO
             if (effective !== undefined && effective !== value) operations.push({ op: "add", path: buildPointer(["objects", index, key]), value });
           }
         } else if (operation.type === "text") {
-          if (object.kind !== "text") return { ok: false, code: "object.not-text" };
+          if (!projectObjectText(object)) return { ok: false, code: "object.not-text" };
           if (operation.text !== object.label) operations.push({ op: "replace", path: buildPointer(["objects", index, "label"]), value: operation.text });
         }
       }
diff --git a/packages/json-document-object-document/src/object-projection.ts b/packages/json-document-object-document/src/object-projection.ts
index 79c9f61b..aa878226 100644
--- a/packages/json-document-object-document/src/object-projection.ts
+++ b/packages/json-document-object-document/src/object-projection.ts
@@ -1,5 +1,6 @@
 import type { CanvasObject, CanvasObjectDraft, CanvasObjectKind, DocumentObject, ObjectBounds, ObjectPoint } from "./object-model.js";
 import { assertCanvasImageSource } from "./object-validation.js";
+import { getObjectStyle, type ObjectStyle } from "./object-style.js";
 
 export interface ObjectTransform {
   readonly dx: number;
@@ -27,13 +28,35 @@ export function projectObject(object: DocumentObject): CanvasObject {
   return object.kind === undefined ? { ...object, color: object.color ?? "transparent", kind: "rectangle" } : object as CanvasObject;
 }
 
+/** Read-only body layout, shared by display, native editing, and text capability checks. */
+export interface ObjectTextProjection extends ObjectBounds, Pick<ObjectStyle, "fontSize" | "fontWeight" | "textAlign" | "color"> {
+  readonly text: string;
+  readonly verticalAlign: "top" | "center";
+}
+
+export function projectObjectText(object: DocumentObject): ObjectTextProjection | null {
+  const style = getObjectStyle(object);
+  if (style.fontSize === undefined) return null;
+  const shape = object.kind === "rectangle" || object.kind === "ellipse";
+  const padding = object.kind === "text" ? 0 : object.kind === "sticky-note" ? 16 : 12;
+  const insetX = object.kind === "ellipse" ? object.width * (1 - Math.SQRT1_2) / 2 : Math.min(padding, object.width / 4);
+  const insetY = object.kind === "ellipse" ? object.height * (1 - Math.SQRT1_2) / 2 : Math.min(padding, object.height / 4);
+  return {
+    x: object.x + insetX, y: object.y + insetY, width: object.width - 2 * insetX, height: object.height - 2 * insetY,
+    text: object.label, color: style.textColor ?? style.color!, fontSize: style.fontSize,
+    fontWeight: style.fontWeight!, textAlign: style.textAlign!, verticalAlign: shape ? "center" : "top",
+  };
+}
+
 export function createCanvasObject(
   kind: Exclude<CanvasObjectKind, "path" | "image">,
   bounds: ObjectBounds,
-  style: { readonly color: string; readonly label: string; readonly fontSize?: number },
+  style: { readonly color: string; readonly label: string; readonly fontSize?: number; readonly textColor?: string },
 ): CanvasObjectDraft {
   const base = { ...bounds, width: Math.max(1, bounds.width), height: Math.max(1, bounds.height), color: style.color, label: style.label };
-  return kind === "text" ? { ...base, kind, fontSize: style.fontSize ?? 32 } : { ...base, kind };
+  return kind === "text" ? { ...base, kind, fontSize: style.fontSize ?? 32 } : {
+    ...base, kind, ...(style.fontSize === undefined ? {} : { fontSize: style.fontSize }), ...(style.textColor === undefined ? {} : { textColor: style.textColor }),
+  };
 }
 
 /** Fits a decoded raster inside bounds without upscaling; persisted bytes survive JSON round trips. */
diff --git a/packages/json-document-object-document/src/object-style.ts b/packages/json-document-object-document/src/object-style.ts
index d85beffe..12cfa570 100644
--- a/packages/json-document-object-document/src/object-style.ts
+++ b/packages/json-document-object-document/src/object-style.ts
@@ -3,6 +3,8 @@ import type { DocumentObject } from "./object-model.js";
 /** Object-level styles, not character-range formatting. Color is the kind's primary paint. */
 export interface ObjectStyle {
   readonly color: string;
+  /** Body text paint for filled objects; standalone text keeps its existing color field. */
+  readonly textColor: string;
   readonly fontSize: number;
   readonly fontWeight: 400 | 700;
   readonly textAlign: "left" | "center" | "right";
@@ -16,10 +18,11 @@ export type ObjectStyleSelection = { readonly [Key in keyof ObjectStyle]?: Objec
 /** Effective values and capabilities have one owner, including legacy defaults. */
 export function getObjectStyle(object: DocumentObject): Partial<ObjectStyle> {
   const color = object.color ?? "transparent";
+  const text = { fontSize: (object.fontSize ?? 24) as number, fontWeight: (object.fontWeight ?? 400) as 400 | 700, textAlign: (object.textAlign ?? (object.kind === "rectangle" || object.kind === "ellipse" ? "center" : "left")) as ObjectStyle["textAlign"] };
   switch (object.kind) {
     case "image": return {};
-    case "text": return { color, fontSize: object.fontSize as number, fontWeight: (object.fontWeight ?? 400) as 400 | 700, textAlign: (object.textAlign ?? "left") as ObjectStyle["textAlign"] };
-    case "rectangle": case "ellipse": return { color, strokeColor: (object.strokeColor ?? "#000000") as string, strokeWidth: (object.strokeWidth ?? 0) as number };
+    case "text": return { color, ...text };
+    case "rectangle": case "ellipse": case "sticky-note": return { color, ...text, textColor: (object.textColor ?? "#253044") as string, strokeColor: (object.strokeColor ?? "#000000") as string, strokeWidth: (object.strokeWidth ?? 0) as number };
     case "path": return { color, strokeWidth: object.strokeWidth as number };
     default: return { color };
   }
@@ -39,7 +42,7 @@ export function readObjectStyle(objects: ReadonlyArray<DocumentObject>): ObjectS
 export function assertObjectStyle(value: unknown): asserts value is Partial<ObjectStyle> {
   if (!value || typeof value !== "object" || Array.isArray(value)) throw new TypeError("Object style must be a record.");
   for (const [key, field] of Object.entries(value)) {
-    const valid = key === "color" || key === "strokeColor" ? typeof field === "string" && field.length > 0
+    const valid = key === "color" || key === "textColor" || key === "strokeColor" ? typeof field === "string" && field.length > 0
       : key === "fontSize" ? typeof field === "number" && Number.isFinite(field) && field > 0
       : key === "strokeWidth" ? typeof field === "number" && Number.isFinite(field) && field >= 0
       : key === "fontWeight" ? field === 400 || field === 700
diff --git a/packages/json-document-object-document/src/object-validation.ts b/packages/json-document-object-document/src/object-validation.ts
index b8f3b566..adfc0bb7 100644
--- a/packages/json-document-object-document/src/object-validation.ts
+++ b/packages/json-document-object-document/src/object-validation.ts
@@ -1,7 +1,7 @@
 import { createJSONDocument, type JSONValue } from "@interactive-os/json-document";
 import { assertRasterImageSource as assertCanvasImageSource } from "@interactive-os/json-document-file-intake";
-import type { CanvasDocument, ObjectDocument } from "./object-model.js";
-import { assertObjectStyle } from "./object-style.js";
+import type { CanvasDocument, DocumentObject, ObjectDocument } from "./object-model.js";
+import { assertObjectStyle, getObjectStyle } from "./object-style.js";
 
 function record(value: unknown): value is Record<string, unknown> {
   return value !== null && typeof value === "object" && !Array.isArray(value);
@@ -27,10 +27,10 @@ export function assertObjectDocument(value: unknown): void {
     if ((object.width as number) < 0 || (object.height as number) < 0) throw new TypeError(`Object dimensions must not be negative: ${JSON.stringify(object.id)}.`);
     if (object.kind !== undefined) {
       if (typeof object.color !== "string") throw new TypeError("Canvas objects require a color string.");
-      if (!["text", "rectangle", "ellipse", "path", "image"].includes(object.kind as string)) throw new TypeError("Unknown Object kind.");
+      if (!["text", "rectangle", "ellipse", "sticky-note", "path", "image"].includes(object.kind as string)) throw new TypeError("Unknown Object kind.");
       if (!positive(object.width) || !positive(object.height)) throw new TypeError("Canvas object dimensions must be positive.");
       if (object.kind === "text" && !positive(object.fontSize)) throw new TypeError("Text fontSize must be positive and finite.");
-      const styleKeys = object.kind === "text" ? ["fontWeight", "textAlign"] : object.kind === "rectangle" || object.kind === "ellipse" ? ["strokeColor", "strokeWidth"] : [];
+      const styleKeys = Object.keys(getObjectStyle(object as unknown as DocumentObject)).filter((key) => key !== "color");
       assertObjectStyle(Object.fromEntries(styleKeys.filter((key) => Object.hasOwn(object, key)).map((key) => [key, object[key]])));
       if (object.kind === "image") assertCanvasImageSource(object.source);
       if (object.kind === "path") {
diff --git a/packages/json-document-object-document/tests/object-style.test.ts b/packages/json-document-object-document/tests/object-style.test.ts
index 59efd0b8..ebe0f000 100644
--- a/packages/json-document-object-document/tests/object-style.test.ts
+++ b/packages/json-document-object-document/tests/object-style.test.ts
@@ -13,7 +13,7 @@ const document: CanvasDocument = { profile: "canvas/1", width: 1280, height: 720
 
 test("effective styles preserve old documents and expose kind-specific capabilities", () => {
   expect(getObjectStyle(document.objects[0]!)).toEqual({ color: "blue", fontSize: 32, fontWeight: 400, textAlign: "left" });
-  expect(getObjectStyle(document.objects[1]!)).toEqual({ color: "blue", strokeColor: "#000000", strokeWidth: 0 });
+  expect(getObjectStyle(document.objects[1]!)).toEqual({ color: "blue", textColor: "#253044", fontSize: 24, fontWeight: 400, textAlign: "center", strokeColor: "#000000", strokeWidth: 0 });
   expect(getObjectStyle(document.objects[3]!)).toEqual({ color: "blue", strokeWidth: 4 });
   expect(getObjectStyle(document.objects[4]!)).toEqual({});
   expect(getObjectStyle({ ...bounds, id: "legacy" })).toEqual({ color: "blue" });
@@ -23,7 +23,7 @@ test("effective styles preserve old documents and expose kind-specific capabilit
 
 test("mixed values only compare supporting targets and retain unsupported as absent", () => {
   expect(readObjectStyle([])).toEqual({});
-  expect(readObjectStyle(document.objects)).toEqual({ color: null, fontSize: 32, fontWeight: 400, textAlign: "left", strokeColor: null, strokeWidth: null });
+  expect(readObjectStyle(document.objects)).toEqual({ color: null, textColor: "#253044", fontSize: null, fontWeight: 400, textAlign: null, strokeColor: null, strokeWidth: null });
   expect(readObjectStyle([document.objects[0]!, document.objects[4]!])).toEqual(getObjectStyle(document.objects[0]!));
   expect(readObjectStyle([document.objects[0]!, { ...document.objects[0]!, id: "bold", fontWeight: 700, textAlign: "right" }])).toMatchObject({ fontWeight: null, textAlign: null });
 });
@@ -38,7 +38,7 @@ test("one atomic style plan changes only applicable fields without replacing ext
   if (!result.ok) return;
   const next = result.value as CanvasDocument;
   expect(next.objects[0]).toEqual({ ...document.objects[0], color: "purple", fontSize: 48, fontWeight: 700, textAlign: "center" });
-  expect(next.objects[1]).toEqual({ ...document.objects[1], color: "purple", strokeColor: "orange", strokeWidth: 6 });
+  expect(next.objects[1]).toEqual({ ...document.objects[1], color: "purple", fontSize: 48, fontWeight: 700, strokeColor: "orange", strokeWidth: 6 });
   expect(next.objects[3]).toEqual({ ...document.objects[3], color: "purple", strokeWidth: 6 });
   expect(next.objects[4]).toEqual(document.objects[4]);
   expect(parseCanvasDocument(serializeCanvasDocument(next))).toEqual(next);
diff --git a/packages/json-document-object-document/tests/object-text.test.ts b/packages/json-document-object-document/tests/object-text.test.ts
new file mode 100644
index 00000000..95503ae2
--- /dev/null
+++ b/packages/json-document-object-document/tests/object-text.test.ts
@@ -0,0 +1,69 @@
+import { expect, test } from "vitest";
+import { applyPatch } from "@interactive-os/json-document";
+import { assertCanvasDocument, createCanvasObject, getObjectStyle, parseCanvasDocument, planObjectOperation, projectObjectText, readObjectStyle, serializeCanvasDocument, type CanvasDocument } from "../src/index.js";
+
+const bounds = { x: 40, y: 60, width: 200, height: 160 };
+const filledKinds = ["rectangle", "ellipse", "sticky-note"] as const;
+const objects = filledKinds.map((kind) => ({ ...createCanvasObject(kind, bounds, { color: "#fff2a8", label: "한 장\n💡" }), id: kind }));
+const document: CanvasDocument = { profile: "canvas/1", width: 1280, height: 720, objects };
+
+test.each(filledKinds)("%s shares label authoring, font defaults and separate fill/text paint", (kind) => {
+  const object = objects.find((item) => item.id === kind)!;
+  const before = serializeCanvasDocument(document);
+  expect(projectObjectText(object)).toMatchObject({ text: "한 장\n💡", color: "#253044", fontSize: 24, fontWeight: 400, textAlign: kind === "sticky-note" ? "left" : "center", verticalAlign: kind === "sticky-note" ? "top" : "center" });
+  const plan = planObjectOperation(document, { type: "text", objectId: kind, text: "새 본문\n" });
+  expect(plan).toEqual({ ok: true, operations: [{ op: "replace", path: `/objects/${objects.indexOf(object)}/label`, value: "새 본문\n" }] });
+  expect(planObjectOperation(document, { type: "text", objectId: kind, text: object.label })).toEqual({ ok: true, operations: [] });
+  expect(serializeCanvasDocument(document)).toBe(before);
+  expect(parseCanvasDocument(before)).toEqual(document);
+  expect(object).not.toHaveProperty("fontSize");
+});
+
+test("body bounds are inset, finite at minimum sizes and ellipse corners remain inside its curve", () => {
+  expect(projectObjectText(objects[0]!)).toMatchObject({ x: 52, y: 72, width: 176, height: 136 });
+  expect(projectObjectText(objects[2]!)).toMatchObject({ x: 56, y: 76, width: 168, height: 128 });
+  const ellipse = projectObjectText(objects[1]!)!;
+  expect(ellipse.width).toBeCloseTo(bounds.width * Math.SQRT1_2);
+  expect(ellipse.height).toBeCloseTo(bounds.height * Math.SQRT1_2);
+  for (const object of objects) {
+    const tiny = projectObjectText({ ...object, width: 1, height: 1 })!;
+    expect(tiny.width).toBeGreaterThan(0); expect(tiny.width).toBeLessThanOrEqual(1);
+    expect(tiny.height).toBeGreaterThan(0); expect(tiny.height).toBeLessThanOrEqual(1);
+  }
+});
+
+test("text keeps its color and uninset bounds; metadata-only labels do not acquire text capability", () => {
+  const text = { ...createCanvasObject("text", bounds, { color: "red", label: "Title", fontSize: 32 }), id: "text" };
+  expect(projectObjectText(text)).toEqual({ ...bounds, text: "Title", color: "red", fontSize: 32, fontWeight: 400, textAlign: "left", verticalAlign: "top" });
+  for (const object of [
+    { ...bounds, id: "legacy", color: "blue", label: "Legacy" },
+    { ...bounds, id: "image", color: "transparent", label: "Image", kind: "image", source: "data:image/png;base64,AQID" },
+    { ...bounds, id: "path", color: "blue", label: "Line", kind: "path", strokeWidth: 2, points: [{ x: 0, y: 0 }, { x: 1, y: 1 }] },
+  ]) {
+    expect(projectObjectText(object)).toBeNull();
+    expect(planObjectOperation({ objects: [object] }, { type: "text", objectId: object.id, text: "No" })).toMatchObject({ ok: false, code: "object.not-text" });
+  }
+});
+
+test("mixed body styles use one atomic plan and round-trip without painting the fill", () => {
+  expect(readObjectStyle(objects)).toMatchObject({ color: "#fff2a8", textColor: "#253044", fontSize: 24, textAlign: null });
+  const style = { textColor: "purple", fontSize: 40, fontWeight: 700, textAlign: "right" } as const;
+  const plan = planObjectOperation(document, { type: "style", objectIds: filledKinds, style });
+  expect(plan.ok).toBe(true); if (!plan.ok) return;
+  const result = applyPatch(document, plan.operations);
+  expect(result.ok).toBe(true); if (!result.ok) return;
+  const next = result.value as CanvasDocument;
+  next.objects.forEach((object, index) => {
+    expect(object).toEqual({ ...objects[index], ...style });
+    expect(getObjectStyle(object)).toMatchObject(style);
+  });
+  expect(parseCanvasDocument(serializeCanvasDocument(next))).toEqual(next);
+});
+
+test.each(filledKinds)("%s rejects invalid persisted body formatting and atomic style requests", (kind) => {
+  const object = objects.find((item) => item.id === kind)!;
+  for (const style of [{ fontSize: 0 }, { fontSize: "24" }, { fontWeight: 500 }, { textAlign: "justify" }, { textColor: "" }, { textColor: null }]) {
+    expect(() => assertCanvasDocument({ ...document, objects: [{ ...object, ...style }] })).toThrow();
+    expect(planObjectOperation(document, { type: "style", objectIds: filledKinds, style: { color: "red", ...style } as never }).ok).toBe(false);
+  }
+});
diff --git a/site/src/app/index.css b/site/src/app/index.css
index 496d63d3..eee460ea 100644
--- a/site/src/app/index.css
+++ b/site/src/app/index.css
@@ -296,7 +296,7 @@
   }
 
   .canvas-style-panel {
-    @apply grid w-64 gap-3 rounded-control border border-line-subtle bg-background-canvas p-3 text-xs text-foreground-default shadow-overlay outline-none;
+    @apply grid max-h-[60vh] w-64 gap-3 overflow-y-auto rounded-control border border-line-subtle bg-background-canvas p-3 text-xs text-foreground-default shadow-overlay outline-none;
   }
 
   [data-ui-presentation="dialog-backdrop"] {
diff --git a/site/src/routes/canvas-demo/CanvasDemoRoute.tsx b/site/src/routes/canvas-demo/CanvasDemoRoute.tsx
index 9e9bc107..ba100662 100644
--- a/site/src/routes/canvas-demo/CanvasDemoRoute.tsx
+++ b/site/src/routes/canvas-demo/CanvasDemoRoute.tsx
@@ -11,7 +11,7 @@ export function CanvasDemoRoute() {
   const [editor] = useState(() => createObjectEditor(emptyCanvasDocument));
   const [selectProfile] = useState(() => createPlaneSelectProfile());
   return (
-    <DemoPage documentation={<PageHeader illustration="peek" title="Canvas">한 장에 글자·도형·그리기. Shift+클릭으로 다중 선택하고 Alt+드래그로 복제합니다. 선택한 객체의 스타일 아이콘에서 색·글자 서식·테두리를 바꾸고, 복사한 텍스트·이미지를 붙여넣습니다.</PageHeader>}>
+    <DemoPage documentation={<PageHeader illustration="peek" title="Canvas">한 장에 글자·도형·스티커 노트·그리기. 도형 안에도 더블클릭으로 글을 적습니다. Shift+클릭으로 다중 선택하고 Alt+드래그로 복제합니다. 스타일 아이콘에서 색·글자 서식·테두리를 바꾸고, 복사한 텍스트·이미지를 붙여넣습니다.</PageHeader>}>
       <CanvasHand className={ui.product.embedded} editor={editor} selectProfile={selectProfile} creationStyle={canvasCreationStyle} slideStyle={{ background: "rgb(var(--color-background-canvas))" }} />
     </DemoPage>
   );
diff --git a/site/src/shared/demo-workbench/canvas-demo-document.ts b/site/src/shared/demo-workbench/canvas-demo-document.ts
index dbf9a81f..14b60ef3 100644
--- a/site/src/shared/demo-workbench/canvas-demo-document.ts
+++ b/site/src/shared/demo-workbench/canvas-demo-document.ts
@@ -4,13 +4,14 @@ import type { CanvasCreationStyle } from "@interactive-os/json-document-canvas";
 export const emptyCanvasDocument: CanvasDocument = { profile: "canvas/1", width: 1280, height: 720, objects: [] };
 
 // Persisted artwork colors are product data, not UI design tokens.
-export const canvasCreationStyle: CanvasCreationStyle = { color: "#b6c8e8", textColor: "#253044", fontSize: 36, strokeWidth: 4 };
+export const canvasCreationStyle: CanvasCreationStyle = { color: "#b6c8e8", textColor: "#253044", stickyNoteColor: "#fff2a8", fontSize: 36, strokeWidth: 4 };
 
 export const canvasProofDocument: CanvasDocument = {
   ...emptyCanvasDocument,
   objects: [
     { id: "title", kind: "text", x: 96, y: 96, width: 660, height: 96, label: "One slide. Your ideas.", color: "#253044", fontSize: 48 },
-    { id: "rectangle", kind: "rectangle", x: 96, y: 264, width: 400, height: 240, label: "", color: "#b6c8e8" },
-    { id: "ellipse", kind: "ellipse", x: 616, y: 264, width: 240, height: 240, label: "", color: "#e8bdab" },
+    { id: "rectangle", kind: "rectangle", x: 96, y: 264, width: 400, height: 240, label: "도형 안에도\n생각을 적어보세요", color: "#b6c8e8", fontSize: 32 },
+    { id: "ellipse", kind: "ellipse", x: 560, y: 264, width: 240, height: 240, label: "더블클릭\n편집", color: "#e8bdab" },
+    { id: "note", kind: "sticky-note", x: 880, y: 264, width: 240, height: 240, label: "작은 아이디어를\n한 장에", color: "#fff2a8", fontSize: 28 },
   ],
 };
diff --git a/site/src/shared/demo-workbench/demo-sources.ts b/site/src/shared/demo-workbench/demo-sources.ts
index 5ec33a07..4078c271 100644
--- a/site/src/shared/demo-workbench/demo-sources.ts
+++ b/site/src/shared/demo-workbench/demo-sources.ts
@@ -412,10 +412,10 @@ const registeredPublicUsages = [
     symbol: "useEditingSnapshot",
     sourcePath: "packages/json-document-react/src/editing-snapshot.ts",
   },
-  ...(["ObjectDocument", "CanvasDocument", "DocumentObject", "CanvasObject"] as const).map((symbol) => ({ packageName: "@interactive-os/json-document-object-document", symbol, sourcePath: "packages/json-document-object-document/src/object-model.ts" })),
+  ...(["ObjectDocument", "CanvasDocument", "DocumentObject", "CanvasObject", "CanvasObjectKind", "CanvasTextFormat"] as const).map((symbol) => ({ packageName: "@interactive-os/json-document-object-document", symbol, sourcePath: "packages/json-document-object-document/src/object-model.ts" })),
   ...(["getObjectStyle", "readObjectStyle", "assertObjectStyle", "ObjectStyle", "ObjectStyleSelection"] as const).map((symbol) => ({ packageName: "@interactive-os/json-document-object-document", symbol, sourcePath: "packages/json-document-object-document/src/object-style.ts" })),
   ...(["assertObjectDocument", "assertCanvasDocument", "assertCanvasImageSource", "parseCanvasDocument", "serializeCanvasDocument"] as const).map((symbol) => ({ packageName: "@interactive-os/json-document-object-document", symbol, sourcePath: "packages/json-document-object-document/src/object-validation.ts" })),
-  ...(["createCanvasObject", "createCanvasPath", "createCanvasImage", "projectObject", "transformObject"] as const).map((symbol) => ({ packageName: "@interactive-os/json-document-object-document", symbol, sourcePath: "packages/json-document-object-document/src/object-projection.ts" })),
+  ...(["createCanvasObject", "createCanvasPath", "createCanvasImage", "projectObject", "projectObjectText", "ObjectTextProjection", "transformObject"] as const).map((symbol) => ({ packageName: "@interactive-os/json-document-object-document", symbol, sourcePath: "packages/json-document-object-document/src/object-projection.ts" })),
   {
     packageName: "@interactive-os/json-document-object-document",
     symbol: "planObjectOperation",