어포던스: 제품 최전선을 API와 사용법으로 연다

[developer-1px]

Closes #456

기반: #455

제품이 json-document를 만지는 최전선이 어포던스다. 입구는 API와 쓰는 법이고, 이름은 손동작이다.

Goal Anchor

• Outcome: 제품이 json-document를 만지는 최전선이 어포던스다. 입구는 API와 쓰는 법이고, 이름은 손동작이다.
• Done: 어포던스 사용법·API가 공개 입구다. 선반이 고르기·접기·드래그·되돌리기처럼 행동으로 설명된다. 라이브는 usage의 증명이다. 호스트는 마크업과 장르 Intent만 가진다. 키보드·마우스 문법은 제품마다 열리지 않는다.
• Don't: Listbox/Tree를 가져가는 상품으로 두지 않는다. 데모 카탈로그를 입구로 두지 않는다. Adapter의 chord 번역과 Connector의 구독을 어포던스에 합치지 않는다. 손의 문법을 호스트 정책으로 남겨 두지 않는다.

Canonical Mapping

• 고르기 = select
• 접기 = fold
• 드래그 = drag
• 되돌리기 = undo/redo

Usage grammar (v1.1–1.5)

호스트는 시점을 고른다. 패키지는 읽는 법을 하나만 허용한다.

applyAffordance(pointerSelect(event), {
  hand: (hand) => {
    if (hand.type === "select") editor.dispatch({ type: "selection.set", itemId, mode: hand.operation });
  },
});

const committed = commitAffordance(dragAffordance(origin, point));
if (committed) {
  applyAffordance(committed, {
    commit: (hand) => { /* write */ },
  });
}

• Preview는 { hand, cursor? }. commit: true는 commitAffordance만 민트한다.
• 공개 export에 unwrap이 없다.
• 위젯 증명과 Hands 제품 데모(Order, Object, Canvas, Tree, Document, Sheet, Board/Kanban, Database, History, Topology)가 그 한 줄을 쓴다.

Don't

위젯 키트, useAffordance, Adapter/Connector 합병, useEditing.keyboard.resolve 시그니처 변경, TBD 화면 크롬, Hands 완전 편집기 교체, apply에 phase를 넣기.

Selection 데모의 모드 토글, Clipboard 데모의 replace-only, rich-text caret, Connector/Adapter 랩은 이 PR 밖이다.

검증

• npm test -w @interactive-os/json-document-affordance (12 passed)
• npm run typecheck -w @interactive-os/json-document-affordance
• npm run docs:evaluate
• npm run typecheck -w @interactive-os/json-document-site
• npm test -w @interactive-os/json-document-site (32 passed)
• npx playwright test --config site/playwright.config.ts site/tests/browser/widgets.spec.ts site/tests/browser/editor-slice-demos.spec.ts (16 passed)
• npx playwright test --config site/playwright.config.ts site/tests/browser/document-demo.spec.ts site/tests/browser/sheet-demo.spec.ts site/tests/browser/database-demo.spec.ts site/tests/browser/editing-demos.spec.ts (included in later 19-pass run with editor-slice)