@hjmds/design-contracts 1.7.0 → 1.9.0

package/docs/catalog-freeze.json

@@ -1,23 +1,27 @@
 {
-  "$comment": "카탈로그 확장 동결. 이 목록에 없는 이름을 catalog.ts에 추가하면 test/catalog-freeze.test.ts가 실패한다.",
+  "$comment": "카탈로그 확장 동결. 이 목록에 없는 이름을 catalog.ts에 추가하면 test/catalog-freeze.test.ts가 실패한다. 2026-09-29 사용자 요청으로 도입 제외 후보 네 개 삭제; 기존 dataviz/provider API는 유지.",
   "frozenAt": "2026-09-26",
-  "reason": "2026-09-26 설계 점검: 111개 중 stable 4개였고, 세 제품 이상이 쓰는 약 30개가 beta에 묶여 있었다. 1.5.0에서 13개를 실제 증거로 승격했지만 keyboard·platform-parity 증거가 필요한 핵심(Checkbox, Switch, Dialog, Sheet, SegmentedControl, RadioGroup, Link, PasswordField 등)은 아직 beta다. 폭을 넓히기 전에 이것들을 먼저 올린다.",
+  "reason": "2026-09-26 설계 점검: 111개 중 stable 4개였고, 세 제품 이상이 쓰는 약 30개가 beta에 묶여 있었다. 1.5.0에서 13개를 실제 증거로 승격했지만 입력·접근성 동작 증거가 필요한 핵심(Checkbox, Switch, Dialog, Sheet, SegmentedControl, RadioGroup, Link, PasswordField 등)은 아직 beta다. 폭을 넓히기 전에 이것들을 먼저 올린다.",
   "unfreezeWhen": "위 핵심 beta가 stable이 되면 동결을 푼다. 그 전에 추가가 필요하면 이 파일의 exceptions에 이름·날짜·근거(ADR 또는 이슈)를 적는다.",
-  "exceptions": [],
+  "exceptions": [
+    {
+      "name": "ThinkingOrb",
+      "date": "2026-09-29",
+      "rationale": "사용자가 Thinking Orbs의 HJM 흡수를 명시적으로 요청함. 기존 Spinner를 교체하지 않는 AI 상태 표시이며 선택형 경로로 격리. docs/thinking-orb.md"
+    }
+  ],
   "names": [
     "Accordion",
     "Affix",
     "Agreement",
     "AlertDialog",
     "Anchor",
-    "AppProvider",
     "AspectRatio",
     "Asset",
     "AuthProviderButton",
     "AuthScreenLayout",
     "Avatar",
     "Badge",
-    "BorderBeam",
     "BottomCTA",
     "BottomInfo",
     "BottomNavigation",
@@ -27,7 +31,6 @@
     "Card",
     "Carousel",
     "Cascader",
-    "Chart",
     "Checkbox",
     "CheckboxGroup",
     "Chip",
@@ -112,7 +115,6 @@
     "Tree",
     "TreeSelect",
     "UploadItem",
-    "Utility",
     "VirtualList",
     "VisuallyHidden",
     "Watermark"

package/docs/collapsible.md

@@ -17,3 +17,15 @@ chrome이 따라오고 그걸 다시 CSS로 지우게 된다. 그래서 별도
 가리키지 않으면 사용자는 방금 나타난 것을 찾아야 한다.
 
 **Web·Native 공통.** 네이티브도 `button` role에 expanded 상태를 그대로 쓴다.
+
+## Renderer evidence
+
+- Web keyboard proof tabs to the native button, toggles with Enter, then closes with Space;
+  it checks `aria-expanded`, the controlled region relationship, and that closed content leaves
+  the tree. The narrow long-copy case places a long unbroken label in the trigger to verify that
+  disclosure chrome does not widen its container.
+- Native renderer tests inspect the `button` role and expanded state, invoke the rendered
+  `Pressable` action, and verify that opening and closing adds and removes the content. This is
+  host-renderer evidence; it does not claim physical keyboard, VoiceOver, or TalkBack verification.
+- Native and Web long-copy fixtures put the long label in the trigger itself. The child body stays
+  short so the scenario tests the constrained interactive label rather than arbitrary content.

package/docs/color-picker.md

@@ -1,72 +1,30 @@
-# ColorPicker — 지금은 만들지 않는다
-
-## 문제로 제기된 것
-
-임의의 색을 고른다(hex/RGB/HSB 입력, 팔레트, 최근 사용 색). Ant Design `ColorPicker`와
-`direct` crosswalk를 따른다. catalog에는 이미 `{ name: "ColorPicker", category: "input",
-platform: "web", status: "planned" }` 자리가 예약돼 있다.
-
-## 판정: 실사용처 근거 없이 만들지 않는다
-
-먼저 가정하지 말라는 지시대로 두 제품에 색을 고르는 화면이 있는지 확인했다.
-
-- **Yajalal RN**(`modules/app-rn/src`): `grep -rli "colorpicker\|color picker\|color-picker"`가
-  0건이다. 코드베이스 전체에 색을 고르는 화면이 없다.
-- **BurnTok Web**: 이 머신에 저장소가 없어 코드로 직접 확인할 수 없었다. 로드맵
-  (`docs/expansion-roadmap.md`)의 제품 적용 순서·완료 슬라이스 기록 어디에도 색 선택
-  화면이 등장하지 않는다 — 언급되는 색 관련 작업은 전부 "제품이 이미 고정한 semantic
-  color를 렌더러가 어떻게 적용하는가"(Toast tone mark, Statistic trend mark, 구단 색
-  adapter)이고, "사용자가 임의의 색을 고르는" 문제는 한 번도 나오지 않는다.
-
-측정된 vertical slice가 없다는 뜻이다. `docs/expansion-roadmap.md`의 maturity gate는
-"실제 제품 vertical slice 없이 승격하지 않는다"고 정하고 있고, 이 원칙은 계약을 쓸지
-말지에도 그대로 적용된다 — `docs/notification.md`·`docs/dropdown.md`·
-`docs/virtual-list.md`가 이미 "측정된 요구가 없으면 만들지 않는다"로 판정한 것과 같은
-근거다.
-
-## 이 판정을 더 무겁게 만드는 이유
-
-ColorPicker는 만들면 가벼운 계약이 아니다. 로드맵의 상태 축 표 어디에도 없는 완전히
-새로운 세 갈래 문제를 한 번에 열어야 한다.
-
-1. **색 공간 표현.** hex/RGB/HSB/alpha 중 무엇을 공개 API로 삼을지, 변환 규칙을 어디
-   소유할지부터 새로 정해야 한다 — 이 저장소의 어떤 기존 컴포넌트도 색 값 자체를
-   입력 데이터로 다루지 않는다(`semanticColors`/`ColorReference`는 전부 제품이 아니라
-   시스템이 미리 고정한 토큰이다).
-2. **대비·접근성.** 사용자가 고른 색이 텍스트/배경 대비 4.5:1을 만족하는지, 선택 UI
-   자체의 포커스 인디케이터가 색상 스와치 배경과 충분한 대비를 유지하는지를 계약이
-   보장해야 한다 — Statistic의 trend, UploadItem의 상태처럼 이 저장소는 "색으로만
-   말하지 않는다"를 지켜왔는데, ColorPicker는 그 규칙과 정반대로 색 자체가 선택 결과인
-   컴포넌트라 이 원칙을 어떻게 지킬지부터 새로 설계해야 한다(스와치에 값 텍스트를
-   병기하는 것 정도는 쉽지만, 색맹 사용자를 위한 팔레트 순서·명도 대비 규칙은 가볍지
-   않다).
-3. **입력 방식.** 팔레트 탭, 텍스트 hex 입력, 슬라이더(hue/saturation/brightness) 최소
-   셋을 하나의 컴포넌트가 조율해야 하고, 셋 사이의 값 동기화(hex 입력 중 오타 상태를
-   팔레트에 어떻게 반영하는지)는 NumberField/Slider보다 훨씬 큰 상태 기계다.
-
-수요 없이 이 세 갈래를 먼저 짜면 다음 사람이 "실제로 무엇을 위해 이렇게 무거운가"를
-또 물어야 하는 계약이 된다. 반대로 실사용처가 나오면, 그 화면이 실제로 필요한 것은
-이 셋 중 일부뿐일 가능성이 높다(예: 구단 색 하나를 브랜드 팔레트에서만 고르는 화면이면
-색 공간 변환도 hex 입력도 필요 없다) — 지금 전체를 설계하면 그 실제 요구보다 큰 계약이
-된다.
-
-## 만들지 않은 것
-
-`src/color-picker.ts`, `test/color-picker.test.ts`는 없다. catalog의
-`{ name: "ColorPicker", category: "input", platform: "web", status: "planned" }` row와
-`antDesignReferenceComponents`의 `ColorPicker → ColorPicker` crosswalk(`relationship:
-"direct"`)는 건드리지 않는다 — 이름 자리를 지우는 것이 아니라, 지금 채울 계약이 없다는
-것이다.
-
-## 뒤집힐 조건
-
-다음 중 하나가 실제로 측정되면 이 판정을 다시 연다.
-
-1. BurnTok 또는 Yajalal에 사용자가 임의의 색을 고르는 실제 화면 요구가 나온다(예: 커스텀
-   테마, 사용자 지정 하이라이트 색).
-2. 요구가 팔레트에서 미리 정의된 색 중 하나만 고르는 좁은 범위로 확인되면, ColorPicker
-   전체가 아니라 `Chip` 또는 `RadioGroup`의 시각 변형으로 더 가볍게 흡수될 수 있는지부터
-   먼저 검토한다 — hex 입력·색 공간 변환이 필요 없는 한 별도 컴포넌트를 열 이유가
-   약해진다.
-3. 요구가 hex/RGB 자유 입력까지 포함하면, 이 문서의 세 갈래(색 공간/대비/입력 방식)를
-   실제 화면의 좁은 요구에 맞춰 하나씩만 계약하고 나머지는 열지 않는다.
+# ColorPicker — Web sRGB 색상 입력
+
+2026-09-30: 사용자가 남은 세 후보의 개발을 명시적으로 요청하여 기존 수요 대기 결정을 대체했다.
+React Native와 Flutter 구현은 포함하지 않는다. 계약은 HEX sRGB를 저장값으로 선택했다.
+HSV/RGB 입력기를 동시에 만드는 대신 브라우저 색상 선택기와 HEX 입력을 연결해 값 표현을 하나로 유지한다.
+
+`@hjmds/react/color-picker`의 `ColorPicker`는 controlled `value`와 `onValueChange`를 받는다.
+`label`과 `labels.color`, `labels.hex`, `labels.opacity`, `labels.invalid`는 제품에서 번역하여 전달한다.
+`alpha`가 false면 `#rrggbb`, true면 `#rrggbbaa`를 내보낸다. 3·4자리 축약 HEX도 입력할 수 있다. alpha가 켜진 상태에서 3·6자리 HEX를 입력하면 색만 바꾸고 현재 투명도를 유지한다(네이티브 색상 입력과 같다).
+alpha를 끈 상태에서 불투명하지 않은 값을 전달하면 투명도를 조용히 버리지 않고 거부한다.
+
+- HEX는 Enter/blur에 확정한다. 잘못된 입력은 오류를 보여주고 외부 값은 유지한다.
+  Escape는 마지막 controlled 값으로 복구하며 Enter가 상위 폼을 제출하지 않게 한다.
+- 브라우저 색상 선택기는 RGB를 선택하고 기존 alpha를 보존한다. 정확한 선택기 모양은 OS 소유다.
+- 불투명도 range는 0–100%이며 키보드 화살표/Home/End를 지원한다. 8비트 alpha로 반올림한다.
+- `presets`는 HEX 배열이며 색상값을 읽을 수 있는 버튼이다. 중복값은 정규화 후 제거한다.
+- `disabled`는 fieldset을 통해 모든 입력과 팔레트를 비활성화한다.
+- 제어부는 HJM canvas·border·focus 토큰을 사용한다. 견본의 사용자 색상은 콘텐츠 데이터다.
+  선택색을 제품의 본문/배경으로 사용할 때의 대비는 제품이 확인한다.
+
+```tsx
+<ColorPicker label={t('color.title')} labels={{
+  color: t('color.choose'), hex: t('color.hex'), opacity: t('color.opacity'), invalid: t('color.invalid'),
+}} value={color} onValueChange={setColor} alpha presets={['#b94627ff', '#338844ff']} />
+```
+
+계약: [color-picker.ts](../src/color-picker.ts). UI: [renderer](../../react/src/color-picker.tsx).
+사용 예제: [Web additions](../../../showcase/web/src/patterns/WebAdditions.stories.tsx).
+검증: [계약 회귀](../test/web-additions.test.ts), [브라우저 동작](../../react/test/web-additions.browser.test.tsx),
+[환경 행렬](../../react/test/scenario-matrix.browser.test.tsx). 브라우저/OS 색상 팝업 자체의 내부 UI는 HJM 검증 대상이 아니다.

package/docs/command-palette.md

@@ -113,12 +113,14 @@ heading을 가지므로) — CommandPalette는 다르다: `role="dialog"` 표면
 
 ## 검증 화면
 
-아직 없음. `planned → beta` 승격은 실제 제품 vertical slice 이후 리드가 진행한다.
+이 조사 당시 제품 채택은 미확인이었다. 2026-09-29부터 제품 채택은 관측으로 분리하며,
+현재 성숙도는 catalog와 [승격 기준](stable-promotion.md)을 따른다.
 
 ## Web renderer (2026-09-18)
 
-`@hjmds/react/command-palette`의 `CommandPalette`가 이 계약을 실행한다. catalog는
-Web `beta`, Native `unsupported`다.
+`@hjmds/react/command-palette`의 `CommandPalette`가 이 계약을 실행한다. Web은 키보드 검색·
+실행·dismiss와 320px의 긴 한글 명령 설명 proof를 통과해 2026-09-29 stable로 승격한다.
+Native는 `unsupported`다. 전역 단축키는 제품 소유다.
 
 - **모달 takeover다.** Dialog·Sheet·SidePanel과 같은 모달 스택·스크롤 락·배경 격리를
   공유한다(`packages/react/src/modal.tsx`). 별도 `modal` 축은 없다.

package/docs/confirm-popover.md

@@ -1,5 +1,10 @@
 # ConfirmPopover — Popover 위의 확인 조합
 
+> 2026-09-30 정리: 구현된 조합을 미구현으로 집계하지 않도록 독립 Planned 행과 catalog ID를 제거했다.
+> 기존 조합 예제와 공개 helper는 유지하며, 참조표는 실제 구성 컴포넌트로 연결한다.
+> 아래 날짜별 설계 기록의 행 유지 지시는 당시 판단이며 이 결정으로 대체한다.
+
+
 ## 문제로 제기된 것
 
 Ant Design `Popconfirm`은 "삭제하시겠습니까?" 같은 확인을 Modal보다 가벼운

package/docs/consumer-policy.md

@@ -1,7 +1,7 @@
 # HJM 소비 앱 정책
 
 상태: **Normative**
-정책 버전: **1.3.0**
+정책 버전: **1.4.0**
 적용 대상: 신규 HJM Web·React Native 앱과 기존 앱의 새 화면
 
 이 정책 원문은 다음 package patch release부터
@@ -26,25 +26,38 @@
 
 ## 2. 성숙도별 채택
 
-| Catalog 상태 | 신규 앱 기본 정책 | 추가 조건 |
+| 사용할 surface 상태 | 신규 앱 기본 정책 | 추가 조건 |
 | --- | --- | --- |
 | `stable` | 사용 가능 | 제품 흐름·copy 검증 |
-| `beta` | 기본 비활성 | ADR, 앱 테스트, 실제 기기/브라우저 evidence |
+| `beta` | 필요에 따라 선택 가능 | 사용 표면·미완료 항목 확인, 채택 기록과 관련 회귀 검사 |
 | `planned` | 사용 금지 | HJM package에서 구현·승격한 뒤 채택 |
 | `deprecated` | 신규 사용 금지 | 공지된 migration 기한 안에 제거 |
 
-신규 앱 scaffold는 Stable Core만 기본 surface로 채택해야 합니다(MUST). Beta를 사용하려면
-앱의 `docs/decisions/` 아래 ADR에 채택 이유, 대체안, 소유자, 검증 환경과 재검토 날짜를
-기록해야 합니다(MUST).
+`surfaceStatus`가 사용 플랫폼의 채택 기준입니다. contract `status`가 stable이어도
+다른 renderer까지 안정화됐다는 뜻은 아닙니다. 예를 들어 TopBar는 Web stable / Native beta입니다.
+
+신규 앱 scaffold의 기본 선택은 Stable Core입니다(SHOULD). Beta 사용은 정책 예외가 아닙니다.
+앱의 기존 contract 또는 TASKS 한 곳에 컴포넌트·표면, 사용하는 이유, 담당자와 관련 회귀
+검사를 기록해야 합니다(MUST). 여러 Beta를 한 기록으로 묶을 수 있고, 별도 ADR·대안 비교·
+재검토 날짜는 요구하지 않습니다. 실제 기기·브라우저 QA는 바뀐 사용자 흐름과 플랫폼 위험에
+맞춰 앱 릴리스에서 수행합니다. Beta라는 이유만으로 제품 전체 QA를 반복하지 않습니다.
+
+2026-09-29 점검에서 HJM 자체 검증을 통과한 표시 컴포넌트도 제품 수·배포 이력 때문에
+승격이 막혔습니다. 1.4.0은 컴포넌트 호환성 약속과 제품 릴리스 검증을 분리합니다.
+[승격 기준](stable-promotion.md)을 따르며 기존 versioned app profile의 검사 요건은 그
+profile을 명시적으로 갱신하기 전까지 유지합니다.
 
 ### 2.1 Stable Core와 필수 foundation bridge
 
-1.5.0부터 Stable Core는 17개 surface입니다. 1.4까지의 `Surface`, `Button`, `Field`, `TextArea`에
+1.5.0에서 Stable Core는 17개 컴포넌트였습니다. 1.4까지의 `Surface`, `Button`, `Field`, `TextArea`에
 더해, 첫 제품 화면에 필요한 foundation인 `Text`, `Icon`, `Stack`, `Container`,
 `DesignSystemProvider`와 세 제품 이상이 쓰는 `IconButton`, `Badge`, `Card`, `Tag`, `Notice`,
 `Progress`, `Spinner`, `Skeleton`이 stable로 승격됐습니다. 승격 근거는 이름뿐이던 시나리오 증거를
 실제 계산 스타일 검사로 바꾼 뒤 두 renderer에서 요구 시나리오가 모두 통과한 것입니다
-([Stable Core](stable-core.md)). 그 밖의 컴포넌트는 여전히 `beta`이며, beta를 `stable`로
+([Stable Core](stable-core.md)). 이번 개정에서는 `Divider`, `Section`, `ListRow`, `Statistic`,
+`DescriptionList`, `EmptyState`, `Result`, `Heading`, `Top`, `BottomCTA`를 양쪽에서 승격하고,
+`TopBar`는 계약·Web만 승격했습니다. 계약/Web stable은 28개, Native stable은 27개입니다.
+배포된 패키지의 catalog가 소비 앱의 기준입니다. 남은 beta를 `stable`로
 간주하거나 `betaAdoptions: []`로 기록하는 것은 허용하지 않습니다(MUST NOT).
 
 HJM-APP-STANDARD가 versioned `requiredFoundations` 목록을 선언한 경우 다음 bridge를
@@ -55,8 +68,8 @@ HJM-APP-STANDARD가 versioned `requiredFoundations` 목록을 선언한 경우
 - 각 앱은 실제 adapter와 사용 환경에 대한 evidence를 소유합니다(MUST). `draft` /
   `incubating` contract에서는 evidence가 `planned`일 수 있지만, `active` 또는 release gate는
   timestamp가 있는 `verified` evidence 없이는 통과하면 안 됩니다(MUST NOT).
-- 중앙 필수 목록 밖의 `beta`는 계속 제품별 optional adoption입니다. 제품 ADR, 대안,
-  제거·승격 조건과 verified app evidence가 모두 필요합니다(MUST).
+- 중앙 필수 목록 밖의 `beta`는 제품별 optional adoption이며 §2의 간단한 채택 기록을
+  사용합니다. 예전 profile이 ADR·verified evidence를 요구하면 해당 profile 갱신 때 이관합니다.
 - foundation이 catalog에서 `stable`로 승격되면 기존 표준의 의미를 조용히 바꾸지 않고
   다음 versioned app profile에서 bridge 목록을 줄입니다(MUST).
 
@@ -194,7 +207,7 @@ on-color 대비, 색에 의존하지 않는 상태 표지, reduce-motion을 제
 4. 원시 색·간격·radius의 화면 레이어 유입 방지 검사
 5. typecheck, unit/component test, production build
 6. light/dark, 100–200% 글자 크기, LTR/RTL, reduce motion 중 앱이 지원한다고 선언한 환경
-7. optional Beta component를 쓴다면 ADR과 해당 component·환경의 versioned consumer evidence
+7. optional Beta component를 쓴다면 §2의 채택 기록과 변경한 사용자 흐름의 회귀 검사
 
 앱이 지원하지 않는 플랫폼이나 환경은 가짜 통과 script로 만들지 않고 app contract에서
 `not-applicable`과 이유를 선언해야 합니다(MUST).
@@ -218,8 +231,12 @@ package로 승격하지 않습니다.
 
 - exact fixed-train dependency와 Provider가 CI에서 검증되는가?
 - Stable은 기본 사용하고(1.5.0 이전 profile이면 필수 foundation은 중앙 목록+앱 evidence로),
-  optional Beta는 제품 ADR+evidence로 구분되어 있는가?
+  optional Beta는 채택 기록과 관련 회귀 검사로 추적되는가?
 - screen 코드가 semantic token·component를 우회하지 않는가?
 - 같은 상태가 Web/RN에서 같은 의미와 자연스러운 플랫폼 행동을 갖는가?
 - 로고를 제거해도 제품의 핵심 콘텐츠와 정보 구조가 다른 제품과 구분되는가?
 - 제품 고유 표현을 제거해도 정보 위계·피드백·접근성에서는 HJM의 결이 남는가?
+
+## Optional presentation adapters
+
+The [optional adapter contract](optional-adapters.md) lists platform-specific entries and exact peer requirements. These extensions do not promote the canonical component or establish consumer/device compatibility. Native adapters require separately verified development clients; base imports retain their existing dependency contract.

package/docs/context-menu.md

@@ -12,12 +12,22 @@
 
 **키보드로 열 때의 앵커는 초점 요소의 상자다.** 좌표가 없다고 (0,0)에 띄우면 메뉴가 방금
 초점이 있던 항목과 무관해 보인다. `resolveContextMenuAnchor`가 이 판단을 갖고 있고,
-좌표도 초점 상자도 없으면 렌더링 대신 던진다.
+좌표도 초점 상자도 없으면 렌더링 대신 던진다. 실제 메뉴가 포털에 마운트된 뒤 메뉴에 초점을
+옮기고 `aria-activedescendant`로 활성 항목을 알린다. 열기 직전의 초점 요소는 보관한다.
 
-**닫으면 열었던 자리로 초점을 돌린다.** 좌표에서 열렸다고 초점까지 떠 있으면 다음 Tab이
+**Escape 또는 항목 실행으로 닫으면 열었던 요소에 초점을 돌린다.** 바깥을 눌러 닫을 때는
+사용자가 누른 바깥 요소의 초점을 유지한다. 좌표에서 열렸다고 초점까지 떠 있으면 다음 Tab이
 문서 처음으로 간다.
 
+**화면 가장자리와 긴 항목도 다룬다.** 메뉴가 포털에 표시된 다음 실제 크기로 위치를 화면 안에
+맞춘다. 긴 한글·공백 없는 항목명은 줄바꿈해 전체 명령을 읽을 수 있게 한다. 임의의 고정 크기
+추정은 글꼴과 줄바꿈에 따라 메뉴가 다시 화면 밖으로 나갈 수 있어 사용하지 않는다.
+
 **브라우저 기본 메뉴를 제품이 소유한 표면에서만 대체한다.** 텍스트 선택·링크·이미지 위의
 기본 메뉴를 빼앗으면 복사·새 탭 열기를 사용자에게서 뺏는 것이다.
 
 **Web 전용.** 네이티브의 길게 누르기 메뉴는 OS가 제공하는 표면이라 같은 계약이 아니다.
+
+React 구현은 `packages/react/test/context-menu.interactions.browser.test.tsx`에서 Chromium으로
+포인터 좌표 열기, 키보드 열기, 활성 항목 안내, Escape·실행 후 초점 복귀, 작은 화면에서의 긴
+항목 배치를 검증한다.

package/docs/data-table.md

@@ -28,7 +28,7 @@
   `id`와 `disabled?`만 가진 훨씬 좁은 타입이다 — Collection 기본 계약 중 실제로
   행에 맞는 부분만 가져오고, 맞지 않는 부분(label/textValue/typeahead)은 그대로
   두었다.
-- `Pagination`(다른 저작자가 이번 배치에서 계약)과 `LoadMore`(이미 beta)는 DataTable이
+- `Pagination`(다른 저작자가 이번 배치에서 계약)과 `LoadMore`(이미 stable)는 DataTable이
   **소유하지 않고 합성**한다. `asyncState`가 `loadingMore`일 때 그 아래 어느
   컴포넌트를 두는지는 제품 선택이다 — Native 긴 목록에 LoadMore를 쓰듯 Web 표에도
   같은 패턴이 통한다.
@@ -75,13 +75,14 @@
   `native` 필드는 breadcrumb·form 같은 다른 Web 전용 계약과 같은 빈 배열
   자리표시자다.
 
-**검증 화면.** 아직 실제 제품 vertical slice가 없다 — catalog는 `planned`으로
-남고, `beta` 승격은 로드맵 gate(실제 화면 검증)를 통과한 뒤 리드가 진행한다.
+**검증 화면.** 제품 vertical slice는 필요하지 않다. Renderer 계약을 정렬·tri-state selection·
+async 상태와 narrow long-copy 회귀로 확인하고, 소비 제품의 데이터 정렬·페이지네이션은 계속
+제품 소유로 둔다. 채택 여부는 [stable 승격 기준](stable-promotion.md)과 별도다.
 
 ## Web renderer (2026-09-18)
 
-`@hjmds/react/data-table`의 `DataTable`이 이 계약을 실행한다. catalog는 Web `beta`,
-Native `unsupported`다.
+`@hjmds/react/data-table`의 `DataTable`이 이 계약을 실행한다. Web renderer는 전용 keyboard·
+selection·320px long-copy proof를 통과해 2026-09-29 stable로 승격한다. Native는 `unsupported`다.
 
 - **기존 `Table`과 겹치지 않는다.** `@hjmds/react`의 `Table`(advanced-display)은 열·행을
   그려 주는 표시용이고 선택·tri-state·async 상태·정렬 상태 순환이 없다. DataTable은 그
@@ -96,6 +97,10 @@ Native `unsupported`다.
 - **셀 하나에 focusable 컨트롤은 최대 하나다.** roving tabindex grid 탐색을 도입하지 않고
   기본 tab 순서를 쓴다.
 - **페이지네이션은 표 아래에 조합한다.** `footer` slot은 제품이 채우고 표가 소유하지 않는다.
+- 키보드는 표 전체를 하나의 ARIA grid로 만들지 않고 native Tab 순서를 쓴다. 실제 브라우저 입력으로
+  select-all·정렬·행 선택 버튼이 Tab 순서에 있고 Space/Enter로 동작하는지 확인한다. 방향키 셀 탐색은
+  계약에 없다 — 제품 수요가 확인되지 않은 full grid interaction은 별도 계약으로 다룬다.
 - 로컬 검증: `test/data-table.browser.test.tsx` 5개(header 안 정렬 버튼과 aria-sort 3단계,
   tri-state 선택과 disabled 제외, 단일 선택 radio 의미, 셀당 컨트롤 하나와 기본 tab 순서,
-  async 상태 발표와 footer 조합)와 `Patterns/CommandPalette`의 표 화면.
+  async 상태 발표와 footer 조합), `test/data-table.keyboard.browser.test.tsx` 1개(실제 Tab·Enter·Space
+  입력), 그리고 `Patterns/CommandPalette`의 표 화면.

package/docs/date-picker.md

@@ -78,7 +78,9 @@ Select의 축과 동일하되 `content`(idle/loading/loadingMore/error)는 없
 
 ## 검증 화면
 
-first-party Web dialog·Native Sheet renderer, 환경 matrix, 기본 실행 증거는 연결되어 surface는
-`beta`다. 다만 `docs/calendar.md`가 밝힌 대로 Yajalal에는 이 문제의 살아있는 vertical
-slice가 아직 없다. 값 하나를 고르는 새 폼 필드가 실제 제품에 생기고 보조기기 증거까지
-쌓이기 전에는 `stable`로 승격하지 않는다.
+first-party Web dialog·Native Sheet renderer의 필수 시나리오가 연결되어 양쪽 surface가
+`stable`이다. Web Chromium 검사는 트리거 열기, 실제 날짜 셀 키보드 이동·선택, 닫힘과 focus
+복귀를 확인한다. Native renderer 검사는 날짜 host action에 따른 선택·닫힘을 확인한다.
+두 renderer 모두 접근성 이름, 긴 label, 환경 matrix 검사를 통과한다. 실제 iOS/Android 기기와
+제품 폼의 스크린 리더 검증은 소비 앱 릴리스 QA에 속하며, Yajalal vertical slice나 제품 채택
+수는 이 공개 API 성숙도 판단의 조건으로 두지 않는다([Stable 승격 기준](stable-promotion.md)).

package/docs/date-range.md

@@ -27,5 +27,7 @@
 확정된 구간과 hover 미리보기를 함께 처리한다 — renderer가 두 벌의 칠하기 규칙을 만들지
 않게 한다.
 
-**Native.** renderer는 아직 없다(catalog `planned`). 구간 선택은 제스처·스크롤과 함께
-검증해야 해서 Web 먼저 낸다.
+**Native.** 같은 Calendar 격자에서 날짜 host action이 범위의 시작·중간·끝으로 반영되고,
+접근성 이름에도 해당 상태가 포함된다. 시각 범위는 Web에서 band와 hover preview로, Native에서
+날짜 아래 점과 이름으로 표현한다. 두 renderer의 환경·접근성 matrix와 날짜 선택 회귀가 통과해
+각 지원 surface의 계약은 stable이다. 기기·VoiceOver·TalkBack 검증은 소비 제품 QA에서 한다.

package/docs/description-list.md

@@ -62,14 +62,13 @@ Web/Native 모두 `resolveDescriptionListColumnCount`가 돌려준 열 수로 CS
 flex wrap 레이아웃을 만듭니다. 실제 측정된 컨테이너 폭과 시스템 폰트 배율은 renderer가
 공급하고, 이 계약은 그 두 입력을 받아 열 수만 결정합니다.
 
-## 현재 검증과 남은 증거
+## 현재 검증과 제품 채택
 
-first-party Web/RN renderer가 공통 descriptor와
-`resolveDescriptionListColumnCount`를 직접 소비하므로 contract와 두 surface를 `beta`로
-승격했다. Web은 `<dl>/<dt>/<dd>` 구조와 측정 폭 기반 열 전환을, Native는 독립된 라벨-값
-접근성 노드와 window/text-scale 기반 flex 열 전환을 기본 실행 test로 검증한다.
+공통 descriptor와 `resolveDescriptionListColumnCount`를 소비하는 Web/RN renderer는
+[2026-09-29 승격](stable-core.md)의 대상이다. Web의 `<dl>/<dt>/<dd>`와 폭 기반 열 전환,
+Native의 라벨-값 접근성 노드와 text-scale 기반 열 전환은 renderer 회귀로 검증한다.
+필수 환경 시나리오가 모두 연결됐으며 계약·양쪽 surface를 stable로 올린다.
 
-이전 판정이 후보로 든 야잘알 화면은 여전히 승격의 제품 근거로 세지 않는다. 해당 화면은
-단일 열 `List`/`ListRow` 조합이며 DescriptionList의 1/2열 문제와 다르기 때문이다. 실제 소비
-앱에서 이 renderer를 쓰는 1/2열 화면과 200% 글자 크기 실기기 증거는 stable 승격 전까지
-명시적인 debt로 남는다.
+과거 후보로 든 야잘알 화면은 단일 열 List/ListRow 조합이므로 DescriptionList 채택으로
+세지 않는다. 제품의 1/2열 화면과 실제 기기 QA는 해당 앱 릴리스에서 확인하며,
+[승격 기준](stable-promotion.md)에 따라 제품 채택 부재를 성숙도 관문으로 쓰지 않는다.

package/docs/dialog.md

@@ -0,0 +1,39 @@
+# Dialog
+
+Dialog provides a modal boundary for a task that needs the user's attention. This
+contract was recorded during the 2026-09-29 promotion audit because Web and Native
+already had different title APIs and dismissal sources, while there was no single
+component guide describing their shared behavior.
+
+## Accessible name and modal boundary
+
+- Web renders `role="dialog"`, `aria-modal="true"`, a title reference, and an
+  optional description reference. When opened, focus enters the dialog, stays in
+  the active modal, and returns to the trigger (or the explicit return-focus
+  target) after dismissal.
+- Native renders a `role="dialog"` modal boundary with
+  `accessibilityViewIsModal`. A string `title` names the dialog. If `title` is a
+  React element, pass `accessibilityTitle`; native renderers cannot derive a
+  reliable accessible name from arbitrary element children.
+- The close action uses the required localized `closeLabel` on both renderers.
+  Dialog titles, descriptions, and body copy wrap instead of being clipped to one
+  line. Web constrains the dialog to the viewport and allows its content to
+  scroll.
+
+## Dismissal behavior
+
+Dismiss requests are ignored while `busy` is true or `dismissible` is false.
+Web reports `escape`, `outside`, or `close-action`; Native reports `back`,
+`outside`, or `close-action`. A Native primary or secondary action runs its
+callback and requests `close-action`; controlled Dialog owners decide when the
+dialog actually closes. While an async operation is pending, keep `open` true and
+set `busy` so repeated action and dismissal attempts are disabled.
+
+## Renderer proof
+
+The React browser tests cover focus entry, Tab containment, Escape dismissal,
+focus restoration, busy dismissal guards, and long title/description/body copy in
+a narrow viewport. React Native renderer tests cover modal role/name/state,
+action labels and close requests, back/outside dismissal, busy guards, and long
+title/description copy. These tests exercise renderer contracts; device and
+screen-reader behavior remains a separate consumer validation concern.

package/docs/expansion-roadmap.md

@@ -194,8 +194,9 @@ semantic tone은 독립이고 arrow/minus와 visible copy를 함께 사용합니
 
 Yajalal의 선수·FA 기록 vertical slice에서 기존 StatGrid 호환 adapter와 새 Statistic renderer를
 함께 검증했습니다. 좁은 폭에서는 1열까지 reflow하고 큰 글자에서도 값을 줄 수로 자르지 않으며,
-각 통계의 label/value/hint/trend를 독립된 접근성 이름으로 유지하므로 Statistic을 beta로
-승격합니다.
+각 통계의 label/value/hint/trend를 독립된 접근성 이름으로 유지해 Statistic을 첫 beta
+renderer로 도입했습니다. 현재 maturity는 [Stable Core](stable-core.md)의 surface 목록을
+따릅니다.
 
 Select/Combobox는 Menu의 collection contract를 공유하지만 role과 dismiss behavior는 별도입니다.
 Web은 listbox popup, Native는 Sheet를 사용합니다. Native 긴 목록에는 페이지 번호보다
@@ -209,15 +210,18 @@ manual fallback을 유지합니다.
 BurnTok 홈 피드 vertical slice에서 Web IntersectionObserver와 항상 보이는 manual fallback,
 Native FlatList onEndReached와 footer fallback을 같은 controller에 연결했습니다. 두 renderer 모두
 탭과 다음 offset으로 requestKey를 만들고 실제 페이지 요청 Promise가 끝날 때까지 중복 호출을
-차단하며 loading/error/complete 접근성 상태를 검증했으므로 LoadMore를 beta로 승격합니다.
+차단하며 loading/error/complete 접근성 상태를 검증해 LoadMore를 beta renderer로 도입했습니다.
+현재 Web·Native stable evidence와 소비 앱 경계는 [stable promotion log](stable-core.md)에
+기록합니다.
 
 BottomNavigation은 route source-of-truth를 복제하지 않고 `selectedKey`를 input으로만 받습니다.
 Web renderer는 실제 link와 `aria-current`, Native renderer는 navigator의 preventable tabPress와
 long press를 보존합니다. 숫자 badge는 visual subtree를 접근성에서 숨기고 item root에 합성된
 이름을 한 번만 전달합니다. BurnTok 중앙 생성 action은 `center-gap`에 놓이는 sibling primary
 action이며 destination collection에는 들어가지 않습니다. BurnTok Web/RN과 Yajalal RN 실제
-navigation에 적용해 route state·disabled/reselect·긴 글자·safe area·RTL 계약을 검증했으므로
-BottomNavigation을 beta로 승격합니다.
+navigation에 적용해 route state·disabled/reselect·긴 글자·safe area·RTL 계약을 검증해
+BottomNavigation을 beta renderer로 도입했습니다. 현재 Web·Native stable evidence는
+[stable promotion log](stable-core.md)에 기록합니다.
 
 선행 타입은 Select의 nullable stable key와 Combobox의 `selectedKey`/`inputValue` 분리를
 고정합니다. local filtering과 server-driven external filtering도 구분해 선택 상태와 비동기
@@ -233,7 +237,7 @@ state도 selection state와 별도 controlled/uncontrolled 축으로 유지합
 
 surface별 `planned → beta` gate는 public renderer export와 package CI가 실행하는 canonical
 `default` proof를 요구합니다. 실제 제품 vertical slice는 별도의 adoption evidence이며,
-없다면 beta의 환경 debt와 함께 공개되고 stable 승격을 막습니다. 제품 채택을 검토하는
+없다면 채택 관측으로 남기며 stable 승격을 막지 않습니다(2026-09-29 [기준 개정](stable-promotion.md)). 제품 채택을 검토하는
 과정에서 **전제가 이미 바뀌어 있던 사례**도 나왔습니다.
 
 `Calendar`·`DatePicker`를 위임할 때 "야잘알 일정 찾기가 월 달력 격자를 자체 구현 중"이라는
@@ -244,7 +248,7 @@ surface별 `planned → beta` gate는 public renderer export와 package CI가
 
 이후 DatePicker와 Calendar에는 first-party Web·Native renderer와 canonical 환경 증거가 추가되어
 `beta`로 승격됐다. 다만 위 실측은 여전히 유효하다. **제품 adoption evidence는 없고**,
-Yajalal의 날짜 레일을 DatePicker 채택으로 세지 않는다. 따라서 `stable` 승격 근거는 없다.
+Yajalal의 날짜 레일을 DatePicker 채택으로 세지 않는다. 성숙도는 제품 채택 여부 대신 현재 renderer 필수 증거로 판정한다.
 
 **교훈**: 위임할 때 준 실사용처 전제를 저작자가 **확인하게** 해야 한다. 리드의 기억은
 커밋 하나로 낡는다.

package/docs/file-picker.md

@@ -54,6 +54,8 @@ FilePicker는 파일 선택 의도만 소유하고, 진행·성공·실패 표
 - 거부 발표는 색에 의존하지 않는다 — `reason`과 한계값으로 제품이 만든 문장을
   live 영역/에러 카피로 보여준다.
 
-**검증 화면.** first-party Web input/dropzone과 Native picker-adapter renderer, 선택 판정
-상호작용 테스트는 연결되어 surface는 `beta`다. 실제 제품 vertical slice와 플랫폼 picker
-실기기 증거는 아직 없으므로 `stable` 승격 gate는 닫혀 있다.
+**검증 범위.** Web의 native file input/dropzone과 Native의 이름 있는 제품 adapter action,
+양쪽의 같은 선택 판정 resolver를 renderer 회귀로 검증한다. Native adapter가 실제 OS
+document/image picker를 여는지는 제품 통합 책임이며 이 패키지는 이를 구현하거나 기기에서
+검증했다고 주장하지 않는다. 소비 앱은 해당 adapter를 연결하고 제품별 릴리스 QA에서 OS
+동작을 확인한다.

package/docs/form.md

@@ -98,10 +98,22 @@ dispose()가 submitting 중 호출되면 그 attempt는 interrupted로 한 번
   live-region 동등물(`AccessibilityInfo.announceForAccessibility` 또는 동등 API)로
   발표. `submitting` 중에는 제출 버튼이 `accessibilityState.busy`를 얻습니다.
 
+Native 소비자는 제품 검증 결과로 `resolveFirstInvalidFieldFocusTarget`을 호출해
+선택한 입력의 ref를 `Form.firstInvalidFieldRef`에 전달합니다. ref가 있으면 제출 버튼은
+`TextInput.focus()`와 `AccessibilityInfo.setAccessibilityFocus()`를 실행하고 `onSubmit`을
+호출하지 않습니다. ref가 없으면 기존 제출 경로를 따릅니다. Form은 필드 순서·오류 상태를
+등록하거나 추론하지 않습니다.
+
 ## 검증 화면
 
-Form은 이제 `beta`입니다. BurnTok Web의
-`apps/web/src/app/ideas/page.tsx`가 실제 2필드 생성 흐름에서 아래 계약을 소비합니다.
+Form은 surface별 상태를 갖습니다. Web은 실제 Chromium 입력·Enter 제출, 비동기 중복 제출 방지,
+필드·form 오류 semantics와 긴 자식 콘텐츠·환경 matrix 검증을 통과해 stable입니다. Native는
+현재 값 입력·제출·busy 상태와, 제품이 선택한 첫 무효 필드로 Native 키보드 및 accessibility
+focus를 전달하는 host-action 회귀까지 검증합니다. 테스트는 React Native host 동작을 확인하며,
+실기기 VoiceOver/TalkBack 경험은 별도 검증 근거로 기록해야 합니다.
+
+BurnTok Web의 `apps/web/src/app/ideas/page.tsx`는 2필드 생성 흐름에서 제품 소유 검증과 첫 오류
+필드 focus를 연결한 소비 사례입니다.
 
 - `apps/web/src/lib/form-contract.ts`: `formRecipe` 간격, `createFormSubmitSession`,
   `resolveFirstInvalidFieldFocusTarget`을 제품 validation과 React lifecycle에 연결합니다.
@@ -111,8 +123,8 @@ Form은 이제 `beta`입니다. BurnTok Web의
 - `apps/web/src/components/ui/AppTextField.tsx`: input/textarea ref를 실제 control까지
   전달해 focus 계약이 설명에 그치지 않게 합니다.
 
-Web 한 제품의 vertical slice만으로 `stable`을 주장하지 않습니다. Native renderer의
-accessibility focus와 busy 발표 증거가 추가되기 전까지 `beta`를 유지합니다.
+제품 채택 수는 stable blocker가 아닙니다. 실기기 VoiceOver/TalkBack 확인은 제품 QA 범위이며,
+HJM renderer의 Native action 회귀와 사용 가능한 자동 검증을 기준으로 surface 성숙도를 평가합니다.
 
 ## 공개하지 않기로 한 것