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

[developer-1px]

배경

/widgets는 Toolbar·Listbox·Tree 같은 화면 데모 선반이다. 손의 문법은 Adapter keymap과 useEditing에 흩어져 있고, 둘 다 정책을 호스트에 남긴다. 제품이 json-document를 만지는 최전선은 화면 위젯이 아니라 30년짜리 키보드·마우스 어포던스다. 입구는 데모가 아니라 API와 쓰는 법이다.

Goal Anchor

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

Canonical Mapping

• 고르기 = select (pointer replace/extend/toggle, 키보드 이웃 이동)
• 접기 = fold (나무 왼쪽 접힘, 오른쪽 펼침)
• 드래그 = drag (고른 대상을 포인터로 옮김)
• 되돌리기 = undo/redo

Canonical Vocabulary

• 어포던스: 제품과 json-document 사이 최전선의 키보드·마우스 손. 화면 컴포넌트가 아니다.
• 위젯: 호스트가 그리는 화면. 이 층의 상품이 아니다.

Target Structure

Affordance
|-- 고르기
|-- 접기
|-- 드래그
`-- 되돌리기

Guardrails

• 호스트는 마크업과 장르 Intent만 가진다.
• 단축키와 마우스 문법은 패키지가 닫는다. 제품별 keymap을 열지 않는다.
• 라이브 화면은 usage가 맞는지 확인하는 증명이다.
• Keyboard Adapter는 chord → command 번역을 유지한다. React Connector는 구독·질의를 유지한다.

[developer-1px]

Working plan

Goal Anchor

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

Scope

• 키보드·마우스 어포던스 패키지
• 공개 문서와 사이트 층을 고르기·접기·드래그·되돌리기 usage로 연다
• /widgets 데모 선반은 입구가 아니고 증명으로 남긴다

Exclusions

• Listbox/Tree 컴포넌트 상품
• Adapter chord 번역 이전
• Connector 구독 이전
• Hands 완성 편집기 대체

Verification

• package tests
• docs evaluate
• site unit / typecheck
• affordance 문서 라우트와 /widgets 리다이렉트 browser 확인

[developer-1px]

PR: #457 (base #455)

Completed

• @interactive-os/json-document-affordance: pointerSelect, resolveAffordanceKey, treeAffordance, dragOffset/dragShouldCommit, historyAffordance
• 공개 입구 /docs/affordance, 선반 고르기·접기·드래그·되돌리기
• /widgets는 어포던스 사용법으로 리다이렉트. 라이브는 증명 링크

Verification

• package tests, docs evaluate, site unit/typecheck
• Playwright widgets + site-shell + legacy redirects

Remaining

• merge는 이 이슈 밖. #455가 먼저 들어가고 이 PR이 그 위에 쌓인다.

[developer-1px]

사용법 입구의 본문 링크가 사이트 경로로 이어지고, Grid·Document 고르기 증명이 pointerSelect / resolveAffordanceKey를 쓴다. /widgets는 /docs/affordance로 보낸다.

[developer-1px]

사이드 그룹 이름을 Affordance로 맞추고, 키보드·마우스·커서 손을 CSS UI 커서 집합·Pointer Events·APG 키보드 관례로 닫아 TBD 사용법 페이지를 채웠다. API 구현은 아직 없다.

[developer-1px]

Working plan: same-shape live proofs

Goal Anchor (unchanged)

• Outcome: 제품이 json-document를 만지는 최전선이 어포던스다. 입구는 API와 쓰는 법이고, 이름은 손동작이다.
• Done: 라이브는 usage의 증명이다. 호스트는 마크업과 장르 Intent만 가진다.
• Don't: Listbox/Tree를 상품으로 두지 않는다. Adapter chord 번역과 Connector 구독을 어포던스에 합치지 않는다. Hands 완전 편집기를 바꾸지 않는다. useAffordance / affordance-react를 열지 않는다.

This phase

Connect the already-closed hands with the same applyAffordance({ hand, cursor, commit }) in every widget proof. Research is reference only.

host event
  -> affordance fn
    -> applyAffordance
      -> editor.dispatch | host view (cursor / fold / viewport)

In:

• Listbox / Grid / Document / Toolbar / Tree / Board pointer select via applyAffordance(pointerSelect)
• Tree expand/collapse via applyAffordance(treeAffordance)
• Toolbar history via applyAffordance(historyAffordance)
• Canvas marquee + escape via marqueeAffordance / escapeAffordance
• Board card move via the same dragAffordance / dropAffordance as Canvas

Out:

• Connector useEditing internals
• Hands demos (keep optionProps / historyCommands)
• Resize / Rename / Context menu / Caret chrome
• New React hook or package

Verify

• Playwright widget proofs including tree fold, board toggle+drag, canvas escape
• existing listbox typeahead / shift-select
• site typecheck

[developer-1px]

Live proofs now use the same applyAffordance shape

Widget proofs connect host events with applyAffordance({ hand, cursor, commit }). Hands demos and Connector subscribe/query are unchanged.

Verified:

• Listbox click select + typeahead
• Tree ArrowLeft collapse / ArrowRight expand
• Board modifier toggle + drag card to Done (same dragAffordance as Canvas)
• Canvas Escape cancels marquee
• Playwright site/tests/browser/widgets.spec.ts 13 passed
• affordance package tests, site typecheck, docs:evaluate

PR: #457

[developer-1px]

Contract delta (user: 1.3까지 작업해)

Authorized: v1.1–1.3 of the affordance usage shape. Original Goal Anchor stands; this closes the call path found in dogfood.

Goal Anchor (delta)

• Outcome: 호스트는 시점을 고르고, 패키지는 읽는 법을 하나만 허용한다. 가방 낱말은 어포던스 것. preview ≠ commit.
• Done: applyAffordance가 commit 포트를 적용한다. 위젯 증명이 result.commit과 공개 unwrap을 쓰지 않는다. 없는 손(place/open-menu/rename/scroll/zoom)이 유니온에서 빠진다. AffordanceHand가 WebKeyboardCommand를 유니온하지 않는다. preview 결과에 commit 포트를 넘기면 타입이 거부한다.
• Don't: 위젯 키트, useAffordance, Adapter/Connector 합병, useEditing.keyboard.resolve 시그니처 변경, TBD 화면 크롬 구현, Hands 완전 편집기 교체, 히스토리 버튼 조회를 어포던스 책임으로 승격.

Phases

1. result.ts: Preview/Commit, apply overloads, commitAffordance, own keyboard hands
2. drag/select/fold/history return types; marquee rect and pan dx/dy on the hand
3. widget proofs + widget-binding keyboard fill
4. docs + tests

Hands historyCommandsFrom stays as binding-internal unwrap.

[developer-1px]

v1.1–1.3 landed on the PR

Authorized delta: host picks WHEN; package allows one HOW. Preview ≠ commit.

Completed

• AffordancePreview { hand, cursor? } and AffordanceCommit { hand, cursor?, commit: true }
• applyAffordance overloads; commitAffordance(preview)
• Dead hands (place / open-menu / rename / scroll / zoom) left the union. AffordanceHand does not union WebKeyboardCommand.
• Widget proofs apply the bag; they do not peek result.commit or public unwraps. Keyboard ports fill through editingCommandFromStroke.
• Usage docs show preview on move and { commit } after commitAffordance.

Verification

• affordance tests 12, package typecheck
• docs:evaluate
• site typecheck + unit 32
• Playwright widgets.spec.ts 13 passed

PR: #457

Remaining

• Merge is outside this issue until authorized.
• TBD chrome (rename UI, context menu, zoom, caret) stays unimplemented.
• One real TBD hand per later issue.

[developer-1px]

Contract delta (user: 1.5까지 만들고 제품 데모에 전부 소급 적용)

Authorized: close the usage-grammar axis at 1.5 and retrofit product demos. Original Goal Anchor and the 1.1–1.3 delta stand; this finishes leftover HOW.

Goal Anchor (delta)

• Outcome: 공개 HOW 잔여가 0이다. 제품 데모가 그 한 줄만 쓴다.
• Done: 어포던스 함수는 Preview만 반환한다. commit: true는 commitAffordance만 민트한다. 공개 export에 unwrap이 없다. 위젯 증명과 Hands 바인딩이 result.commit·공개 unwrap·함수 mint를 쓰지 않는다.
• Don't: 위젯 키트, useAffordance, Adapter/Connector 합병, useEditing.keyboard.resolve 시그니처, TBD 화면 크롬, Hands 완전 편집기 교체, 히트테스트·히스토리 조회 승격, apply에 phase를 넣기.

Phases

1. 1.4: dropAffordance 포함 모든 손 함수는 Preview. mint는 commitAffordance만
2. 1.5: keyboardCommandFrom / selectOperationFrom / dragOffset / dragShouldCommit / marqueeRect / historyCommandsFrom을 공개 문법에서 뺀다
3. 위젯 증명·docs·historyCommands 바인딩을 그 한 줄로 소급한다

Hands 화면 API(optionProps / historyCommands)는 유지하고, 바인딩 구현만 applyAffordance를 쓴다.

[developer-1px]

v1.4–1.5 landed on the PR

This axis ends here. Public HOW residue is 0. Product demos read one sentence.

Completed

• Every hand function returns Preview. dropAffordance no longer mints commit: true.
• Public unwraps left the index: keyboardCommandFrom, selectOperationFrom, dragOffset, dragShouldCommit, marqueeRect, historyCommandsFrom.
• Board, Canvas demo, Kanban demo write through commitAffordance then { commit }.
• Hands historyCommands keeps its API and fills through applyAffordance.

Verification

• affordance tests 12, package typecheck
• docs:evaluate
• site typecheck + unit 32
• Playwright widgets + editor-slice-demos 16 passed

PR: #457

Remaining

• Merge is outside this issue until authorized.
• TBD hands stay one issue each. This usage-grammar axis does not continue to 1.6.

[developer-1px]

Contract delta (user: 제품 데모에 소급 적용 못한거 전부)

Remaining Hands product demos still select through Connector optionProps / Adapter keyboard.resolve, not applyAffordance.

Goal Anchor (delta)

• Outcome: 남은 제품 데모도 그 한 줄만 쓴다.
• Done: Order, Object, Tree, Document, Sheet, Database가 고르기를 applyAffordance(pointerSelect)로 읽는다. Document·Sheet 키보드는 editingCommandFromStroke다. Tree 접기는 treeAffordance다. Database 칸 끌기는 dropAffordance + commitAffordance다.
• Don't: Hands 화면 API(optionProps / historyCommands) 제거, Selection 데모의 모드 토글 교체, Clipboard 데모의 replace-only 교체, rich-text caret 크롬, Connector/Adapter 랩, useEditing.resolve 시그니처, TBD 크롬.

Out

• /demo/selection (모드 버튼이 데모)
• /demo/clipboard (replace-only가 데모)
• rich-text caret
• Connector / Adapter labs

[developer-1px]

Remaining product demos now read applyAffordance

Order, Object, Tree, Document, Sheet, Database, History, and Topology select through applyAffordance(pointerSelect). Tree fold keyboard uses treeAffordance. Document and Sheet keyboard fill editingCommandFromStroke. Database column drag writes through commitAffordance.

Left on purpose (Don't):

• Selection demo mode toggles
• Clipboard demo replace-only
• rich-text caret chrome
• Connector / Adapter labs

Verified: site typecheck, unit 32, Playwright document/sheet/database/editing/editor-slice 19 passed.

PR: #457

[developer-1px]

PR is current at 386f2aa: #457

Usage-grammar axis closed at 1.5. Remaining product demos read applyAffordance. Merge not requested.

[developer-1px]

Contract delta (user: 그렇게 하자 — site IA)

Authorized: pipeline layers only, Affordance last as host frontier. Hands is a shelf after Affordance. Proofs stay off the sidebar; drop Widget from proof copy.

Goal Anchor (delta)

• Outcome: 사이트가 커널에서 최전선 순으로 읽히고, Hands는 그 다음 선반이다.
• Done: siteLayers와 홈 인덱스가 Document → Collaboration → Editing → Adapter → Connector → Affordance → Hands. "제품 화면" 타입이 없다. overview가 Adapter/Connector와 호스트 화면을 동급으로 두지 않는다. 증명 카피에 Widget이 없다.
• Don't: /widgets 증명 URL 이전, widget-binding 파일 이사, Hands 삭제, Adapter/Connector 합병, TBD 크롬.