@hjmds/design-contracts 1.6.0 → 1.8.0

package/docs/layout.md

@@ -7,7 +7,7 @@
 
 **먼저 뺀 것 — 이미 다른 컴포넌트가 소유한다.** 헤더 크롬은 이미
 `TopBar`(adaptive, beta), 푸터 내비게이션은 이미 `BottomNavigation`(adaptive,
-beta)이다. `Layout`이 그 콘텐츠나 상태를 다시 계약하면 두 곳이 같은 것을
+stable)이다. `Layout`이 그 콘텐츠나 상태를 다시 계약하면 두 곳이 같은 것을
 소유하게 된다 — DataTable이 Pagination/LoadMore를 소유하지 않고 합성하기로 한
 것과 같은 실수를 피한다. `Layout`은 **header/footer가 있다는 사실**만 알고
 (`hasHeader?`/`hasFooter?`), 그 안의 내용은 모른다.
@@ -73,11 +73,10 @@ Web의 `footer` slot은 `Layout`이 `<footer>` contentinfo를 정확히 한 번
 렌더링하거나 요구하지 않는다. `skipLinkLabel` Native prop은 이전 호출부 호환을
 위해 deprecated 상태로만 남아 있다.
 
-**현재 검증과 남은 증거.** 공통 descriptor를 직접 소비하는 first-party Web/RN renderer가
-추가되어 catalog와 두 surface를 `beta`로 승격했다. Web renderer는 실제
-`header`/`nav|aside`/`main`/`footer` landmark, BottomNavigation과의 단일-landmark 합성,
-skip-link focus 이동, persistent/overlay sidebar 합성을 SSR·browser test로 검증한다.
-Native renderer는 같은 region 순서와 overlay
-adapter를 유지하되 존재하지 않는 landmark role을 만들지 않는 기본 실행 증거를 제공한다.
-실제 product shell의 브라우저·VoiceOver·TalkBack 검증과 200% 글자 크기 증거는 stable
-승격 전까지 명시적인 debt로 남는다.
+**현재 검증.** 공통 descriptor를 직접 소비하는 first-party Web/RN renderer가 실제
+landmark, source order, overlay adapter를 검증한다. Web Chromium test는 skip-link가 첫
+Tab 대상이고 Enter로 `main`에 초점을 옮기는지 확인하며, 두 renderer의 scenario matrix는
+긴 본문·접근성·dark·200% 글자·RTL·reduced-motion을 검사한다. Native는 skip-link를
+렌더링하지 않고 region 순서·접근성 속성을 검사한다. 따라서 keyboard proof는 Web에만
+요구한다. 실제 제품 shell의 VoiceOver/TalkBack 및 기기 검증은 제품 릴리스 QA에서 다루며
+공용 Layout의 stable 상태를 막지 않는다.

package/docs/library-gap-analysis.md

@@ -77,7 +77,7 @@ control의 `accessibilityLabel`/`accessibilityHint`가 canonical 번역이다.
   된다. `Section` + `List` 조합으로 충분하고, 그 조합이 부족하다는 실측이 나오면 그때
   `Section`의 축으로 검토한다.
 - `Chart`: **토큰만 채택한다.** 렌더러는 만들지 않고 계열 팔레트·축·격자·범례 토큰만
-  고정한다. 근거는 [chart.md](./chart.md).
+  고정한다. 근거는 [catalog-cleanup.md](./catalog-cleanup.md).
 
 ## 후속 검토
 

package/docs/masonry.md

@@ -0,0 +1,11 @@
+# Masonry
+
+2026-09-29: 사용자가 미구현 기능 완성을 요청해 높이가 다른 카드를 배치하는 Web/Native
+렌더러를 추가했다. `width`, `columns`, `gap`, `getItemHeight(item, itemWidth)`를 명시한다.
+컨테이너 측정과 콘텐츠 높이는 소비 화면이 소유한다. 임의 높이 콘텐츠를 추정해 겹치게
+만드는 대신 확정한 높이로 가장 짧은 열에 순서대로 배치한다. DOM/Native 읽기 순서는
+입력 순서 그대로이며 RTL은 위치만 반전한다. 긴 문구·큰 글자를 사용할 때 높이도 함께
+재계산해야 한다. 빈 목록은 `empty`로 표현하고 중복 키·잘못된 크기는 거부한다.
+
+진입점: `@hjmds/react/masonry`, `@hjmds/react-native/masonry`.
+공통 geometry: `@hjmds/design-contracts/components/masonry`.

package/docs/mentions.md

@@ -79,12 +79,13 @@ popover가 이미 겪는 것과 같은 종류의 렌더러 문제다.
 
 ## 검증 화면
 
-아직 없음. `planned → beta` 승격은 실제 제품 vertical slice 이후 리드가 진행한다.
+이 조사 당시 제품 채택은 미확인이었다. 2026-09-29부터 제품 채택은 관측으로 분리하며,
+현재 성숙도는 catalog와 [승격 기준](stable-promotion.md)을 따른다.
 
-## Web renderer (2026-09-18)
+## Renderer 성숙도 (2026-09-29)
 
-`@hjmds/react/mentions`의 `Mentions`가 이 모듈을 실행한다. catalog는 Web `beta`,
-Native `planned`다.
+`@hjmds/react/mentions`와 `@hjmds/react-native/mentions`의 `Mentions`가 이 모듈을
+실행하며 양 surface 모두 stable이다.
 
 - **새 목록 계약을 만들지 않았다.** 팝업은 Combobox의 listbox 어휘(`role="listbox"`/
   `option`, `aria-activedescendant`, 방향키·Enter·Escape)를 그대로 쓰고, 이 모듈은
@@ -95,6 +96,12 @@ Native `planned`다.
   캐럿 위치가 이미 사라진다.
 - **필터·로딩은 제품 소유다.** 후보 목록과 빈 문구를 제품이 넘기고, renderer는 활성 match를
   `onMentionQueryChange`로 알린다.
-- 로컬 검증: `test/mentions.browser.test.tsx` 5개(토큰 시작 trigger만 열림·공백이 닫음·
-  단어에 붙은 trigger 무시, Enter 확정의 치환 범위와 캐럿, 방향키 순환과 Escape가 본문을
-  건드리지 않음, 포인터 확정, 빈 문구)와 `Patterns/TransferList`의 Mentions 화면.
+- Native `onMentionQueryChange`는 commit effect 이후 호출해, 부모가 후보 상태를 갱신해도
+  render-phase update를 일으키지 않는다. 후보 영역은 `list` 역할과 제품 제공 label을 갖고,
+  각 press action은 후보 이름으로 노출된다.
+- Web과 Native 모두 긴 visible field label을 실제 renderer matrix에서 검증한다. Web은
+  component browser test에서 토큰 탐지, 중간 커서 삽입, Arrow 순환, Enter/Escape, pointer,
+  empty state를 확인한다. Native host-action test는 중간 커서 범위 치환, trailing text 보존,
+  query callback이 commit 이후 전달되는 것과 이름 있는 후보 action을 확인한다.
+- IME 조합과 후보 필터링/loading은 플랫폼·제품 소유 흐름이다. 이 package 검증은 실제
+  iOS/Android IME, VoiceOver/TalkBack 동작 또는 제품 adapter를 실행했다고 주장하지 않는다.

package/docs/optional-adapters.md

@@ -0,0 +1,106 @@
+# Optional presentation adapters
+
+2026-09-29: the user requested all six shortlisted libraries, explicitly allowing platform-specific
+adoption. These are opt-in extensions, not six new canonical components or a stable promotion.
+The canonical Statistic/Menu/Sheet/KeyboardAvoiding APIs remain available without additional peers.
+ContextMenu's canonical Native status remains unsupported until the OS adapter has device evidence.
+ImageViewer and all native adapters are experimental pending device/assistive-technology checks.
+
+## Entry points and ownership
+
+| Package entry | Exports | Platform | Upstream MIT dependency |
+| --- | --- | --- | --- |
+| `@hjmds/react/statistic-motion` | AnimatedStatistic | Web | @number-flow/react 0.6.2 |
+| `@hjmds/react/menu-morph` | MorphingMenu | Web | bloom-menu 0.1.0, framer-motion 13.4.4 |
+| `@hjmds/react-native/image-viewer` | ImageViewer | Native | react-native-zoom-toolkit 5.1.1 |
+| `@hjmds/react-native/keyboard-controller` | KeyboardMotionProvider, KeyboardDock, KeyboardFormScrollView | Native | react-native-keyboard-controller 1.22.5 |
+| `@hjmds/react-native/sheet-gesture` | GestureSheetProvider, GestureSheet, GestureSheetInput | Native | @gorhom/bottom-sheet 5.2.14 |
+| `@hjmds/react-native/context-menu-native` | NativeContextMenu | Native | zeego 3.0.6 |
+
+All upstream code remains in versioned dependencies with its original notices. No upstream source
+was copied into HJM. Fixed optional peer versions match the inspected npm tarballs, rather than
+claiming compatibility with untested major releases. Typecheck dependencies and showcase dependencies
+are exact too. The upstream source repositories are:
+[NumberFlow](https://github.com/barvian/number-flow), [Bloom](https://github.com/joshpuckett/bloom),
+[Zoom Toolkit](https://github.com/Glazzes/react-native-zoom-toolkit),
+[Keyboard Controller](https://github.com/kirillzyusko/react-native-keyboard-controller),
+[Bottom Sheet](https://github.com/gorhom/react-native-bottom-sheet), [Zeego](https://github.com/nandorojo/zeego).
+
+## Installation
+
+Import only the optional entry you use; none is re-exported from the root. Install the matching
+optional peer(s) from the table in that consuming app. The base entries do not require them.
+For native zoom/sheet, also install Gesture Handler 2.32.0, Reanimated 4.5.1 and Worklets 0.10.1
+and configure the host's GestureHandlerRootView/Reanimated setup. Keyboard Controller requires
+Reanimated and a KeyboardMotionProvider at the app root. Do not nest providers per field.
+
+The Expo 57/RN 0.86 showcase uses Zeego 3.0.6 with menu 1.2.2,
+ios-context-menu 3.2.1 and ios-utilities 5.2.0. Same-major iOS overrides avoid the
+old Folly pin; the checked-in Android Kotlin API and iOS Fabric/availability patches
+are required for this host. Installing HJM does not apply workspace patches to a
+consumer. Copy the patches shipped in `@hjmds/react-native/docs/patches/` into the
+consumer and register them with its package manager before rebuilding its native
+client. See that directory's README for exact versions and configuration.
+Expo Go cannot verify these linked native modules.
+
+## Behavior boundaries
+
+- AnimatedStatistic uses the existing Statistic shell and accessible descriptor. `value` must be
+  finite, and `locale` is explicit for deterministic hydration. Intl owns the final visible and
+  spoken text. RTL, non-Latin digits, exponent notation and reduced motion use static output.
+  `Statistic.renderValue` changes only its aria-hidden visual value; it must not change meaning.
+- MorphingMenu is an action-only alternative. Full selection, async loading and nested menu behavior
+  stay in canonical Menu. Bloom owns morph geometry; HJM owns actual button items, disabled guards,
+  arrow/Home/End/typeahead, Escape/Tab and focus restoration. RTL and reduced motion use Menu.
+  Trigger/menu dimensions are bounded defaults inherited from the upstream button-to-menu pattern;
+  very long labels, narrow-screen collision and large-text behavior require further visual evidence.
+- ImageViewer is controlled by `open`, requires localized image/control/failure labels, supports
+  paging without a swipe, and unmounts on close to reset its session. Failed images offer retry.
+  Host-provided safe-area insets are required when placing it edge-to-edge. Remote image permission,
+  URL lifetime and caching remain product responsibilities; the adapter does not fetch metadata.
+- KeyboardDock translates with the keyboard. `clearance` is an additional nonnegative gap above it;
+  the host retains bottom safe-area ownership. Do not combine this with another keyboard avoidance
+  wrapper around the same content. KeyboardFormScrollView handles focused form fields.
+- GestureSheet uses controlled `open`; host must apply onOpenChange. Wrap a screen in
+  GestureSheetProvider inside GestureHandlerRootView. Fixed snap points preserve index semantics;
+  dynamic sizing would insert points and is deliberately disabled. Busy blocks user dismissal;
+  the host can still close programmatically. GestureSheetInput wires sheet keyboard tracking.
+  Android back, backdrop and pan dismissal converge on onOpenChange(false). Consumers remain
+  responsible for focus restoration to the opener and avoiding simultaneous modal sheets.
+- NativeContextMenu delegates long-press behavior and menu appearance to the OS. Supply an
+  accessible native child; item IDs are unique, labels localized, danger maps to OS destructive
+  intent and disabled actions are guarded. Arbitrary custom native menu colors are unsupported.
+
+## Evidence and promotion
+
+Web stories: Patterns/Optional Motion. Native stories: Experimental/Optional Adapters.
+Tests cover adaptation logic and web browser behavior; native mocks cannot prove OS gestures,
+keyboard animation, accessibility focus, native linking or installed-device health. Keep native
+adapters experimental until iOS/Android device evidence exists. No consumer migration or publication
+is implied by adding these entries. The prior Motion Primitives candidate remains reference-only.
+
+A removal replaces the optional imports with canonical Statistic/Menu/Sheet/KeyboardAvoiding or
+product image/menu behavior and removes the matching peers. There is no persisted-state migration.
+
+## Checkout verification — 2026-09-29
+
+- Contracts: 883 tests plus type/build/contract bundle checks passed.
+- Web: 776 Chromium tests passed; the three new browser cases were rerun after focus/direction
+  changes. Existing 172 SSR tests and two new adapter SSR tests passed. Export-boundary test
+  rerun after final manifest ordering passed. Web typecheck/build and showcase tests/token checks,
+  production Storybook build and static verification passed.
+- Native: 735 mock tests passed; the four new adapter cases were rerun after viewport sizing
+  changes. Native typecheck/build and showcase typecheck/test passed. Base Metro production
+  fixture still has 614 modules and excludes optional peers. Final iOS/Android showcase Hermes
+  exports passed; they are JavaScript bundle evidence, not installed native binary evidence.
+- Renderer graph budgets and an additional base-entry optional-peer isolation guard passed.
+  Package tarballs contain all six JS/declaration entries with optional peer metadata.
+  Workspace/evidence/docs/governance and central library-policy static checks passed.
+- Browser UI: light/dark, number update, morph opening, ArrowDown/Enter action selection and
+  restored trigger focus were observed. Device Hub access returned timeoutReached again;
+  native visual/gesture/keyboard/assistive-technology and linking verification remain pending.
+- Peer warnings remain: the base RN 0.81 development fixture is below the Reanimated/Worklets
+  0.83–0.86 range; the optional showcase uses RN 0.86.2. The native Storybook 10.4.4 fixture also
+  reports transitive UI packages expecting Storybook 10.6 and safe-area-context 5.8 versus 5.7.
+  Builds passing do not erase these warnings or prove device compatibility.
+- No npm publication, consumer migration, native binary build, commit or push was performed.

package/docs/otp-field.md

@@ -100,4 +100,5 @@ Backspace → 앞 칸으로)도 이 모델에서는 별도 로직이 필요 없
 
 ## 검증 화면
 
-아직 없음. `planned → beta` 승격은 실제 제품 vertical slice 이후 리드가 진행한다.
+이 조사 당시 제품 채택은 미확인이었다. 2026-09-29부터 제품 채택은 관측으로 분리하며,
+현재 성숙도는 catalog와 [승격 기준](stable-promotion.md)을 따른다.

package/docs/pagination.md

@@ -144,4 +144,7 @@ Steps와 같은 이유다: 순서를 나타내는 문장의 어순과 조사는
 [MUI Pagination](https://mui.com/material-ui/react-pagination/)의 명시적 페이지 탐색과
 outlined 위치 표시를 비교했습니다. HJM은 기존 content-brand outline과 평평한 목록을 유지합니다.
 브라우저 테스트는 현재 페이지 의미, 마지막 페이지 focus 유지·중복 요청 차단, 빈 결과,
-320px·2배 글자·4자리 페이지·RTL을 다룹니다. 실제 제품과 보조기기 검증은 남아 있습니다.
+320px·2배 글자·4자리 페이지·RTL을 다룹니다. Web renderer는 default·접근성·환경 matrix와
+실제 Tab/Space/Enter 페이지 전환·경계 focus proof를 통과해 stable입니다. Pagination에는
+소비자 문장을 그리는 visible text slot이 없어 long-copy proof는 요구하지 않습니다. 제품 URL·목록
+갱신과 실기기/보조기기 QA는 소비 앱 소유입니다.

package/docs/password-field.md

@@ -95,4 +95,5 @@ Field가 이미 가진 `description`/`hint` 슬롯에 자기 문구를 채우면
 
 ## 검증 화면
 
-아직 없음. `planned → beta` 승격은 실제 제품 vertical slice 이후 리드가 진행한다.
+이 조사 당시 제품 채택은 미확인이었다. 2026-09-29부터 제품 채택은 관측으로 분리하며,
+현재 성숙도는 catalog와 [승격 기준](stable-promotion.md)을 따른다.

package/docs/popover.md

@@ -18,7 +18,7 @@ control이 섞인 레이아웃)를 보여줘야 하는 자리가 있다. `docs/d
 | 콘텐츠 | 현지화된 plain text 한 문장 | stable id를 가진 action/선택 항목 목록 | 임의의 interactive 콘텐츠(폼, 링크, 혼합 레이아웃) |
 | focus가 surface 안으로 들어가는가 | **아니오** — `docs/tooltip.md`: "tabbable descendant가 없다" | 예 — 항목에 roving/activate focus | **예** — 결정적 차이 |
 | dismiss 계기 | hover/focus 해제, Escape, sibling 전환 | 선택, Escape/back, outside | close action, outside pointer, **outside-focus**(Tab이 surface 밖으로 나감), Escape |
-| trigger 상호작용 | hover(지연) + focus(즉시) | click/Enter/Space로 열림, 방향키로 탐색 | **click/Enter/Space만** — content가 interactive라 hover로 열고 hover로 유지하는 Tooltip 모델을 재사용하면 키보드·터치 사용자가 content에 도달하기 전에 닫히는 경쟁이 생긴다 |
+| trigger 상호작용 | hover(지연) + focus(즉시) | click/Enter/Space로 열림, 방향키로 탐색 | **click/Enter/Space 기본**; `openOn="hover"`는 지연된 포인터 진입을 추가하지만 click 경로를 유지해 키보드·터치도 같은 콘텐츠에 도달한다 |
 | positioning | 제품 renderer의 비공개 `AnchoredOverlay` | 같은 anatomy(`menuRecipe`)가 이미 소유 | Tooltip과 동일하게 비공개 `AnchoredOverlay`에 위임 — 새 portal/flip/shift API를 만들지 않는다 |
 
 `docs/tooltip.md`가 그은 경계("interactive Popover로 확장하지 않는다")를
@@ -89,8 +89,9 @@ flip/shift, RTL 논리 방향 변환은 제품 Web renderer의 비공개 `Anchor
   명시적으로 공급한다 — 기본값을 발명하지 않는다(Tooltip이 `content`를 필수로
   요구하는 것과 반대로, Popover는 콘텐츠 자체를 타입으로 갖지 않으므로 대신
   이 escape hatch만 둔다).
-- trigger는 click/Enter/Space로만 연다. hover는 열지 않는다 — 위 삼각 경계
-  표의 이유와 동일하다.
+- trigger는 click/Enter/Space로 연다. `openOn="hover"`를 선택하면 pointer hover도
+  지연 후 열리지만, click 경로는 계속 사용할 수 있다. hover가 없는 키보드·터치
+  환경에서도 동작을 제공해야 하므로 hover만으로 열리는 전용 경로는 만들지 않는다.
 
 ## 플랫폼 번역
 
@@ -114,7 +115,7 @@ flip/shift, RTL 논리 방향 변환은 제품 Web renderer의 비공개 `Anchor
 | dismiss reason(`close-action`/`outside-pointer`/`outside-focus`/`escape`/`programmatic`) | 공개 |
 | `placement`/`align` | 공개(Tooltip과 같은 값 집합) |
 | `busy`(모든 dismiss 차단) | **배제** — 비모달이라 전역 차단 상태가 성립하지 않는다 |
-| hover trigger | **배제** — focus가 콘텐츠 안으로 들어가는 계약과 hover 열기/유지가 경쟁한다 |
+| hover trigger | 선택형 추가 입력으로 공개(`openOn="hover"`) — 기본 press 동작을 대체하지 않으며 open/close 지연으로 포인터 이동 간 표면을 유지한다 |
 | portal/flip/shift 공개 API | **배제** — Tooltip의 `AnchoredOverlay` 경계를 그대로 상속 |
 | content 데이터 모델 | **배제** — 런타임 의존성 금지 원칙상 React 콘텐츠 타입을 이 패키지가 가질 수 없다. 콘텐츠 자체는 항상 제품/렌더러 소유다 |
 
@@ -139,7 +140,8 @@ flip·shift를 담당하고, 옆 공간이 부족한 넓은 콘텐츠는 block
 Dialog 안의 Popover는 첫 Escape를 소유한다. 내부 Menu가 Escape를 처리했다면 부모는
 그 이벤트를 다시 처리하지 않는다. 모달의 초점 목록은 hidden/inert/disabled 자손을 제외한다.
 
-2026-09-16 사용자의 확장 요청으로 라이브러리 beta를 제공한다. 제품 채택은 별도다.
+2026-09-16 사용자의 확장 요청으로 Web beta를 제공했다. 2026-09-29 focus/keyboard·hover/touch·
+320px long-copy browser proof를 확인해 stable로 승격한다. Native는 `unsupported`; 제품 채택은 별도다.
 `Patterns/Popover/Filters`는 제목·즐겨찾기 조건 적용/취소/초기화와 실제 목록 교체를 제공한다.
 `ReversibleConfirmation`은 보관 후 취소 버튼으로 초점을 옮기며 실제로 복원한다.
 
@@ -149,5 +151,6 @@ Dialog 안의 Popover는 첫 Escape를 소유한다. 내부 Menu가 Escape를
 되돌릴 수 있는 제품 행동의 조합에 적용한다. API 호환을 약속하지 않는다.
 
 브라우저 검증은 초기 focus, Escape 복귀, 바깥 클릭 유지, Tab 양방향 이탈, controlled 거절 후
-재시도, dismiss 정책, 중첩 modal/menu, 320px·2배 글자·RTL·충돌 배치, exit 격리를 다룬다.
+재시도, dismiss 정책, 중첩 modal/menu, 선택형 hover 지연과 touch/keyboard press 경로,
+320px·2배 글자·RTL·충돌 배치, exit 격리를 다룬다.
 제품 채택·실제 보조기기 검증은 남아 있다.

package/docs/promotion-candidates.md

@@ -13,7 +13,8 @@ BurnTok(`/Users/jimin/Desktop/BurnTok`) 양쪽에서 **같은 문제를 이미
 
 > 2026-08-27 후속: 이 문서는 제품 adoption 실측 기록으로 보존한다. 이후 first-party
 > renderer와 canonical evidence만으로 beta가 된 항목이 있어 현재 catalog status와 표의
-> “실제품 승격 판단”은 의도적으로 다를 수 있다. 실제 제품 증거 없음은 stable gate의 debt다.
+> “실제품 승격 판단”은 의도적으로 다를 수 있다. 당시에는 실제 제품 증거도 stable gate로 보았다.
+> 2026-09-29: 현재 승격은 [승격 기준](stable-promotion.md)을 따른다. 이 문서는 과거 채택 조사이며 제품 수·배포는 더 이상 승격 관문이 아니다.
 
 ## 요약
 

package/docs/qr-code.md

@@ -1,69 +1,15 @@
-# QRCode — 계약을 만들지 않는다
+# QRCode
 
-## 문제로 제기된 것
+2026-09-29: 사용자의 미구현 기능 완성 요청으로 문자열을 실제 스캔 가능한 QR로 인코딩하는
+Web/Native 렌더러를 추가했다. `value`, 현지화된 `label`, QR을 쓰지 않아도 같은 목적을
+달성하는 `fallback` 콘텐츠가 필수다. `level`은 L/M/Q/H, 기본 M이다.
 
-Ant Design `QRCode`는 문자열을 스캔 가능한 격자로 그리고, 오류 정정 레벨(`level`)과
-만료/로딩 상태(`status: active | loading | expired`)를 함께 다룹니다. 이 컴포넌트를
-검토하며 나온 관찰은 다음과 같았습니다 — 오류 정정 레벨, **스캔이 가능한 최소 렌더
-크기**, 대비 요구(밝은 배경 위 어두운 모듈), 그리고 **QR을 읽을 수 없는 사용자를 위한
-대체 경로**(같은 목적지의 링크·텍스트)가 계약할 거리로 보인다는 것이었습니다. 다만
-인코딩 자체(문자열 → 격자 픽셀)는 이 패키지가 하지 않고 제품이 라이브러리로 그린다는
-전제도 함께 있었습니다.
+qrcode-generator 2.0.4(MIT)를 renderer의 선택형 진입점에서만 가져온다. contracts는 인코더를
+주입받아 dependency-free를 유지한다. Native SVG 렌더링은 react-native-svg 15.15.5가 필요하다.
+한글·이모지는 UTF-8로 인코딩하고 jsQR 1.4.0으로 실제 디코딩 왕복 테스트를 수행한다.
 
-## 판정: 만들지 않는다
+스캔 대비를 유지하려고 테마와 무관하게 검정 모듈·흰 배경·4모듈 여백을 사용한다. 최소
+모듈 크기 2px를 충족하지 못하는 `size`는 거부하고 정수 모듈 크기로 맞춘다. 입력 용량
+초과는 오류로 알린다. 서버가 소유한 만료·인증·목적지 권한은 QR 컴포넌트가 보증하지 않는다.
 
-### 1. 두 제품 중 어디에도 실사용처가 없다
-
-`Yajalal RN`(`modules/app-rn/src`)과 `BurnTok`(`apps/web/src`, `packages/design-system/src`)
-양쪽을 `qr`/`QRCode`로 전수 검색했지만 실제 화면 코드에서 QR을 그리거나 스캔하는 곳은
-없었습니다. 유일한 매치는 웹팩 빌드 산출물의 우연한 해시 문자열(`0qr3`, `1qr_kgj`)뿐으로
-제품 코드가 아닙니다. 티켓·프로필 공유·앱 다운로드 유도 등 QR이 흔히 쓰이는 흐름 자체가
-두 제품 어디에도 아직 없습니다.
-
-### 2. 진짜 계약처럼 보이는 부분은 이미 다른 컴포넌트가 소유한다
-
-관찰에서 유일하게 "새 상태 축"처럼 보였던 것 — **QR만으로는 도달할 수 없는 사용자를 위한
-대체 경로가 함께 있어야 한다** — 는 사실 새로운 개념이 아닙니다. `src/image.ts`의
-`ImageDescriptor`가 이미 정확히 같은 모양(`Icon`과 동일한 decorative/informative
-discriminated union)으로 이 문제를 풀어 두었습니다: 사진 자체가 유일한 정보 전달
-수단이면 `decorative: false` + 현지화된 `accessibilityLabel`이 함께 필요합니다
-(`docs/image.md` "대체 텍스트의 의무 — Icon과 같은 모양"). QR 코드를 `decorative: false`
-`Image`로 취급하고 그 옆에 같은 목적지를 가리키는 `Link`를 나란히 두면, "대체 경로 없이
-QR만 보여주지 않는다"는 계약은 새 컴포넌트 없이 이미 성립합니다. antd가 갖는
-`status: active | loading | expired`도 `Image`의 `idle | loading | loaded | error` 콘텐츠
-상태를 그대로 쓰면 되는 문제입니다.
-
-남는 것 — 최소 렌더 크기, 모듈 대비 — 은 상태 축이 아니라 **인코딩 라이브러리가 실제
-모듈 크기를 알아야 계산할 수 있는 렌더링 파라미터**입니다. 이 패키지는 인코딩을 하지
-않기로 이미 전제했으므로, 이 값을 검증할 입력 자체가 이 계층에 없습니다. Statistic이
-포맷된 문자열만 받듯, QR 크기·대비도 그 값을 실제로 계산하는 제품/렌더러의 몫입니다.
-
-### 3. 결론
-
-새 상태 축도, 새 접근성 개념도 남지 않습니다 — 유일하게 유효했던 부분(대체 경로 의무)은
-`Image` + `Link` 조합으로 이미 표현 가능하고, 나머지는 렌더러가 소유하는 인코딩
-파라미터입니다. 측정된 제품 요구도 없습니다. `docs/authoring-brief.md`와
-`docs/expansion-roadmap.md`가 명시한 대로 이 저장소는 측정되지 않은 표면을 미리 만들지
-않습니다.
-
-## 만들지 않은 것
-
-`src/qrcode.ts`, `test/qrcode.test.ts`는 없습니다. `componentCatalog`의
-`{ name: "QRCode", category: "data-display", platform: "shared", status: "planned" }` 행과
-crosswalk의 `QRCode → QRCode` direct 관계(`src/component-references.ts:103`)는 건드리지
-않습니다 — 이름 자리를 지우자는 것이 아니라, 지금 채울 새 계약이 없다는 것입니다.
-
-## 뒤집힐 조건
-
-다음 중 하나가 실제로 측정되면 이 판정을 다시 엽니다.
-
-1. Yajalal 또는 BurnTok에 QR이 실제로 필요한 vertical slice(예: 오프라인 티켓, 프로필
-   공유 QR, 앱 설치 유도)가 나온다.
-2. 그 슬라이스에서 `Image` + `Link` 조합으로는 표현할 수 없는 새 요구(예: 코드 자체의
-   유효 기간을 컴포넌트가 알아야 하고, 만료를 `Image`의 `error` 상태와 다르게 발표해야
-   하는 경우)가 나온다.
-
-## catalog 배선 명세 제안 (리드 적용, 참고용)
-
-지금은 변경할 것이 없습니다. 실제로 QR이 필요해지면 새 recipe를 만들기보다
-`imageRecipe` + `linkRecipe` 조합으로 시작할 것을 권합니다.
+진입점: `@hjmds/react/qr-code`, `@hjmds/react-native/qr-code`.

package/docs/react-native-completion.md

@@ -311,7 +311,7 @@ formatters, RN 키보드 회피·햅틱 계약.
 - **Asset**(Web/RN): 아이콘·이미지·Lottie·비디오를 같은 액자에 넣는다. **재생기는 슬롯으로
   받아** 이 패키지가 의존하지 않는다. [asset.md](./asset.md).
 - **Chart**: 렌더러를 만들지 않는다. 계열 팔레트·축·격자·범례 토큰(`dataviz`)만 고정하고
-  그리기는 제품 라이브러리에 위임한다. 실제로 어긋난 것은 색이었다. [chart.md](./chart.md).
+  그리기는 제품 라이브러리에 위임한다. 실제로 어긋난 것은 색이었다. [catalog-cleanup.md](./catalog-cleanup.md).
 - **전역 density**: Provider의 한 축이 목록·메뉴·표의 기본 밀도가 된다. 컴포넌트 prop이
   언제나 이긴다. 어휘는 통일하지 않고 매핑 함수를 한 곳에 뒀다. [density.md](./density.md).
 - **버튼 라벨 wrap**: 자르지 않고 두 줄까지 접는다. 큰 글자에서는 상한을 푼다(WCAG 1.4.4).

package/docs/result.md

@@ -1,5 +1,8 @@
 # Result contract
 
+현재 계약·Web·Native는 [표시 컴포넌트 승격](stable-core.md)에 따라 stable이다.
+아래 실측은 과거 요구 조사 기록이며 제품 채택 수는 [현재 승격 조건](stable-promotion.md)이 아니다.
+
 **문제.** 흐름이 끝나는 화면 — 결제 성공, 제출 실패, 존재하지 않는 페이지 — 을 하나의
 상태와 최대 두 개의 다음 행동으로 보여줍니다.
 
@@ -26,7 +29,7 @@ const saved = {
 
 ## EmptyState와의 경계
 
-이 시스템에는 이미 `EmptyState`(beta)가 있습니다. 둘 다 "콘텐츠 대신 보여주는 화면"이라는
+이 시스템에는 이미 `EmptyState`가 있습니다. 둘 다 "콘텐츠 대신 보여주는 화면"이라는
 점은 같지만 의미가 정반대입니다.
 
 - `EmptyState`는 **아직 없음**입니다 — 검색 결과가 없거나 목록이 비었을 뿐, 조건이
@@ -89,8 +92,8 @@ Web/Native 모두 아이콘 + 제목 + 설명 + action 슬롯을 세로로 쌓
 그대로 조합합니다 — Result 자체의 recipe는 아이콘 tone, 타이포그래피 위계, 슬롯 사이
 gap만 제공합니다.
 
-## 검증 화면 (예정)
+## 제품 화면 검증
 
-야잘알 결제/제출 흐름의 성공·실패 화면을 첫 vertical slice 후보로 남깁니다.
-`planned → beta` 승격에는 primary-only, primary+secondary, action-없음 세 조합의 실제
-화면 검증이 포함되어야 합니다.
+제품에서 채택할 때는 primary-only, primary+secondary, action-없음 중 실제 사용하는
+조합의 다음 행동과 navigation을 확인합니다. 과거 야잘알 결제/제출 후보는 채택 완료
+증거가 아니며, 제품 배포 여부는 HJM renderer 승격 관문에 포함하지 않습니다.

package/docs/screen-chrome.md

@@ -49,4 +49,5 @@ LTR/RTL, light/dark에서 hit target, 글자 범위, overflow, 제목 분리와
 Web List의 indented 구분선은 행 margin이 아닌 별도 선으로 그린다. 320px 조합에서
 두 번째 제목부터 들여쓰기되던 재현을 고쳤고 Native의 기존 선 전용 inset과 맞췄다.
 Storybook의 조작과 브라우저 검사는 Native 기기의 VoiceOver/TalkBack 검증을 대체하지 않는다.
-catalog beta는 구현 지원 범위이며 stable 또는 앱 배포 완료 선언이 아니다.
+2026-09-29 기준 BottomCTA, TopBar, AuthScreenLayout은 계약·Web·Native stable이다. TopBar Native compact title은
+한 줄 clamp를 제거해 이 문서의 제목 줄바꿈 계약을 따르며, 긴 제목 matrix proof가 연결돼 있다.

package/docs/sheet.md

@@ -6,9 +6,15 @@
 ReactNode를 `as unknown as string`으로 전달했다. Web도 `.hjm-sheet__header`를 덮어썼다.
 같은 어댑터가 키보드 높이, top inset, 본문 maxHeight를 별도로 보정하고 있었다.
 
-1.4는 제목·닫기 컨트롤을 헤더 중앙에 정렬한다. 제목은 여전히 문자열이다. 임의의 제목 slot을
+1.4는 제목·닫기 컨트롤을 헤더 중앙에 정렬한다. 1.4에서는 제목을 문자열로 유지했다. 임의의 제목 slot을
 추가하면 접근성 이름과 표시가 서로 어긋날 수 있어 기본 renderer 정렬을 고치는 쪽을 택했다.
 
+1.7은 Native `Sheet`·`Dialog`의 `title`을 `string | ReactElement`로 넓힌다(`OverlayTitleProps`).
+정렬을 고친 뒤에도 강조·아이콘이 든 제목을 위해 캐스트가 남았기 때문이다(2026-09-27 감사).
+어긋남은 타입으로 막는다: element 제목이면 `accessibilityTitle: string`이 필수이고 modal의
+`accessibilityLabel`은 그 문자열(+description)로만 만든다. 문자열 제목은 그대로 이름이 되고
+`accessibilityTitle`은 선택이다. Web은 `aria-labelledby`가 렌더된 DOM을 읽으므로 ReactNode 그대로다.
+
 Native Sheet는 `keyboardAvoidance`와 `scrollable`을 제공한다. 둘 다 기본 false다.
 이미 키보드를 처리하거나 FlatList를 넣는 소비자를 minor에서 이중 처리하지 않기 위한 선택이다.
 입력 폼은 두 옵션을 함께 켜고 제품의 키보드 listener·강제 maxHeight·중첩 ScrollView를 제거한다.
@@ -40,11 +46,18 @@ Native Sheet는 `keyboardAvoidance`와 `scrollable`을 제공한다. 둘 다 기
 ## 증거와 남은 확인
 
 - `packages/react-native/test/sheet-viewport.test.tsx`: 키보드 사전 표시, frame 변경, resize,
-  floating keyboard, listener 해제, footer/body 경계, safe area와 title 이름.
+  floating keyboard, listener 해제, footer/body 경계, safe area와 title 이름, element 제목의
+  `accessibilityTitle` 쌍(타입·accessibilityLabel), close action/busy 차단, 200% 긴 제목·설명.
 - `packages/react-native/test/modal-lifecycle-fallback.test.tsx`: 종료/후속 surface/focus 회귀.
-- `packages/react/test/sheet-layout.browser.test.tsx`: 320px의 제목/닫기 기하와 100/200% 글자.
+- `packages/react/test/sheet-layout.browser.test.tsx`: 320px의 제목/닫기 기하와 100/200% 글자,
+  긴 제목·설명 줄바꿈, Tab focus containment, Escape 종료와 trigger focus 복원.
 - 위 Native proof는 host mock이다. 소비 앱 Device Hub 및 Android의 실제 키보드 동작은
   별도로 기록하며 mock 통과를 기기 증거로 삼지 않는다.
 
+2026-09-29 renderer 증거 보완: 기존 Sheet renderer proof에는 layout·환경 matrix는 있었지만
+behavior contract의 Web key 동작과 Native host action, 긴 제목·설명 회귀가 별도 interaction test로
+등록되어 있지 않았다. 제품별 기기 영수증을 공통 성숙도 조건으로 만들지 않고, renderer가 소유한
+focus/dismiss와 텍스트 배치 회귀를 직접 확인하도록 위 테스트를 추가했다.
+
 참조: [React Native Keyboard](https://reactnative.dev/docs/keyboard),
 [ScrollView](https://reactnative.dev/docs/scrollview).

package/docs/showcase.md

@@ -39,8 +39,16 @@ Web과 Native가 같은 DOM/view tree를 만드는 것이 아니라, 같은 의
 문서만 유지합니다. `beta`는 first-party renderer export와 최소 default evidence가 있어야
 하며, 아직 통과하지 못한 dark·긴 문구·큰 글자·RTL·reduced motion·접근성 scenario를
 generated evidence debt로 공개합니다. `stable`은 이 required scenario를 모두 통과해야
-합니다. behavior가 있는 컴포넌트는 keyboard interaction, adaptive 컴포넌트는 두 surface가
-모두 beta 이상일 때 Web/Native parity가 승격 debt에 추가됩니다.
+합니다. 입력 행동이 있는 컴포넌트는 keyboard/host-action 증거를 추가합니다.
+Heading처럼 keyboard와 Native action이 모두 없는 의미 계약에는 이를 요구하지 않습니다.
+`keyboard` scenario는 Web 키보드 동작과 Native host/accessibility action을 가리키는 기존 ID이며,
+모든 Native 컴포넌트의 외장 키보드 지원을 뜻하지 않습니다.
+
+2026-09-29부터 `adaptive` 분류만으로 별도 `platform-parity` 시나리오를 강제하지 않습니다.
+각 renderer가 같은 계약을 검증하는 것에 더해 일괄 비교 영수증까지 요구하던 중복을 없앴습니다.
+플랫폼별 완료·취소·선택 의미가 달라질 위험은 해당 동작 회귀 검사에서 확인합니다.
+기존 parity 시나리오와 evidence는 유지되며 필요한 기능에서 추가 실행할 수 있습니다.
+제품 배포·기기·보조기기 QA는 [승격 절차](stable-promotion.md)의 별도 제품 검증 범위입니다.
 
 `beta`의 구현 source of truth는 `@hjmds/react/evidence`와
 `@hjmds/react-native/evidence`입니다. 제품 story는 채택 evidence이지 first-party 구현을

package/docs/side-panel.md

@@ -67,10 +67,11 @@ target은 `control.minTouchTarget`(44) 이상을 유지한다.
 버튼 클릭(`close-action`)은 renderer가 직접 `requestClose`를 호출하는 일반
 동작이라 "플랫폼이 감지하는 중단 벡터" 목록에 넣지 않는다.
 
-## Web renderer (2026-09-18)
+## Web renderer (2026-09-29)
 
-`@hjmds/react/side-panel`의 `SidePanel`이 위 계약을 실행한다. catalog는 Web `beta`,
-Native `unsupported`다. 제품 채택·보조기기 실측은 아직 없으므로 `stable`이 아니다.
+`@hjmds/react/side-panel`의 `SidePanel`이 위 계약을 실행한다. Web은 2026-09-29에 전용 keyboard·
+long-copy proof를 등록하고 stable로 승격한다. Native는 `unsupported`다. 제품 채택과 보조기기
+실측은 별도 소비자 릴리스 QA다.
 
 - **modal만 모달이다.** `modal: true`는 Dialog·Sheet와 **같은** 모달 스택에 들어가
   초점을 가두고 body 스크롤을 잠근다. 이를 위해 그 기계장치를 `packages/react/src/modal.tsx`로
@@ -87,6 +88,11 @@ Native `unsupported`다. 제품 채택·보조기기 실측은 아직 없으므
 - **`onDismissComplete`는 한 번만 부른다.** Sheet의 lifecycle counter는 두지 않았다(위 4번).
   Web에서는 닫은 render와 함께 unmount되므로 reduced motion에서도 기다릴 exit transition이
   없다. 사용자 동작 없이 owner가 닫으면 `programmatic`으로 보고한다.
-- 로컬 검증: `test/side-panel.browser.test.tsx` 6개(도킹·초점 가둠·스크롤 락, RTL `start`
-  미러링과 폭, 비모달의 살아 있는 페이지와 내부 Escape, 사유별 단일 보고와 busy 차단,
-  controlled owner의 busy 종료와 1회 완료, 320px·2배 글자 배치)와 `Patterns/SidePanel`.
+- 렌더러 테스트는 `test/side-panel.browser.test.tsx`의 다섯 흐름에서 모달 도킹·초점 가둠·스크롤 락,
+  RTL `start` 미러링과 폭, 비모달 페이지 상호작용과 Escape 범위, 사유별 단일 보고와 busy 차단,
+  controlled owner의 busy 종료와 1회 완료, 320px·2배 글자 배치를 확인한다.
+- 승격 검토 기준은 [Stable 승격 기준](stable-promotion.md)이다. `test/side-panel.browser.test.tsx`의
+  `keyboard`와 `long-copy` 검증을 중앙 renderer evidence 및 실행 시나리오에 등록했다. 생성된
+  evidence가 모든 필수 시나리오를 보고하고 canonical `pnpm ci:check`가 통과한 뒤 catalog를 올린다.
+- SidePanel은 contract상 Web 전용이고 Native는 `unsupported`다. 제품 채택 수나 VoiceOver/TalkBack,
+  실제 제품 기기 검증은 소비자 릴리스 QA이며 Web renderer 성숙도의 별도 gate가 아니다.

package/docs/sidebar.md

@@ -25,6 +25,9 @@
 **현재 위치는 색이 아니라 `aria-current="page"`가 말한다.**
 
 **tab stop.** 각 항목이 링크이고 문서 순서대로 놓인다. 화살표 grid 탐색을 도입하지 않는다.
+접기 버튼이 있으면 링크 앞에 일반 버튼 tab stop으로 놓인다. 긴 항목명과 그룹 제목은 고정 폭 레일을
+넓히거나 내용을 자르지 않고 줄바꿈한다. 특히 공백 없는 로컬라이즈 문자열도 그룹의 의미가 보이도록
+같은 규칙을 적용한다.
 
 **Web 전용.** 폰은 BottomNavigation을 쓰고, 네이티브 태블릿의 split view는 navigator의
 문제다.

package/docs/splitter.md

@@ -53,8 +53,8 @@ PageUp/PageDown(10배 이동)은 넣지 않았다 — 분할 패널 크기 조
 
 ## Web renderer (2026-09-18)
 
-`@hjmds/react/splitter`의 `Splitter`가 이 계약을 실행한다. catalog는 Web `beta`,
-Native `unsupported`다. 제품 채택·보조기기 실측은 아직 없다.
+`@hjmds/react/splitter`의 `Splitter`가 이 계약을 실행한다. catalog는 Web `stable`,
+Native `unsupported`다. 제품 채택과 실제 보조기기 실측은 승격 범위에 포함하지 않는다.
 
 - **드래그와 키보드가 같은 값을 만든다.** 둘 다 계약의 `resolveSplitterDragValue`/
   `getNextSplitterValue`를 호출하므로 renderer에 별도 숫자 산술이 없다.
@@ -67,9 +67,9 @@ Native `unsupported`다. 제품 채택·보조기기 실측은 아직 없다.
   크기를 저장하는 owner가 의미 없는 쓰기를 하지 않도록.
 - 구현 중 실제 결함을 하나 잡았다: `onValueChangeEnd?.(commit(next))`는 handler가 없으면
   인자 평가까지 통째로 건너뛰어 키보드 조절이 조용히 죽는다. commit을 먼저 하고 알린다.
-- 로컬 검증: `test/splitter.browser.test.tsx` 5개(separator 의미·수직 방향과 44px hit
+- 로컬 검증: `test/splitter.browser.test.tsx` 6개(separator 의미·수직 방향과 44px hit
   target, 방향키 step과 Home/End 경계, 드래그 스냅과 드래그당 1회 end, RTL 드래그·키보드,
-  disabled)와 `Patterns/Splitter`.
+  disabled, 실제 Tab focus와 focused keyboard resize)와 `Patterns/Splitter`.
 
-**검증 화면.** 제품 vertical slice는 아직 없다. `beta`는 renderer 수준 증거를 뜻하며
-실제 화면 채택은 별도로 기록한다.
+**검증 범위.** Web Chromium renderer matrix가 긴 pane 콘텐츠·환경·접근성 증거를 제공한다.
+제품 vertical slice, screen reader 실측, 모든 OS 조합은 보증하지 않으며 소비 앱 릴리스 QA에서 확인한다.