@hjmds/design-contracts 1.10.0 → 1.11.0

package/dist/voice-note.d.ts

@@ -0,0 +1,20 @@
+export type VoiceNoteState = "paused" | "playing" | "loading" | "error";
+export type VoiceNoteDescriptor = Readonly<{
+    title: string;
+    state: VoiceNoteState;
+    /** null means metadata has not loaded. Zero is a known empty recording. */
+    duration: number | null;
+    position: number;
+    disabled?: boolean;
+}>;
+/** Normalize host media metadata without inventing playback or loading progress. */
+export declare function resolveVoiceNote(input: VoiceNoteDescriptor): {
+    position: number;
+    canPlay: boolean;
+    canSeek: boolean;
+    title: string;
+    state: VoiceNoteState;
+    duration: number | null;
+    disabled?: boolean;
+};
+//# sourceMappingURL=voice-note.d.ts.map

package/dist/voice-note.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"voice-note.d.ts","sourceRoot":"","sources":["../src/voice-note.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,cAAc,GAAG,QAAQ,GAAG,SAAS,GAAG,SAAS,GAAG,OAAO,CAAC;AACxE,MAAM,MAAM,mBAAmB,GAAG,QAAQ,CAAC;IACzC,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,cAAc,CAAC;IACtB,2EAA2E;IAC3E,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB,CAAC,CAAC;AACH,oFAAoF;AACpF,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,mBAAmB;;;;WARlD,MAAM;WACN,cAAc;cAEX,MAAM,GAAG,IAAI;eAEZ,OAAO;EAYnB"}

package/dist/voice-note.js

@@ -0,0 +1,16 @@
+/** Normalize host media metadata without inventing playback or loading progress. */
+export function resolveVoiceNote(input) {
+    if (!input.title.trim())
+        throw new TypeError("VoiceNote requires a title");
+    if (!["paused", "playing", "loading", "error"].includes(input.state))
+        throw new TypeError("Unknown VoiceNote state");
+    if (input.duration !== null && (!Number.isFinite(input.duration) || input.duration < 0))
+        throw new RangeError("VoiceNote duration must be finite and nonnegative");
+    if (!Number.isFinite(input.position) || input.position < 0)
+        throw new RangeError("VoiceNote position must be finite and nonnegative");
+    const hasDuration = input.duration !== null && input.duration > 0;
+    return { ...input, position: hasDuration ? Math.min(input.position, input.duration) : 0,
+        canPlay: !input.disabled && input.state !== "loading" && input.state !== "error" && hasDuration,
+        canSeek: !input.disabled && input.state !== "loading" && input.state !== "error" && hasDuration };
+}
+//# sourceMappingURL=voice-note.js.map

package/dist/voice-note.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"voice-note.js","sourceRoot":"","sources":["../src/voice-note.ts"],"names":[],"mappings":"AASA,oFAAoF;AACpF,MAAM,UAAU,gBAAgB,CAAC,KAA0B;IACzD,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,EAAE;QAAE,MAAM,IAAI,SAAS,CAAC,4BAA4B,CAAC,CAAC;IAC3E,IAAI,CAAC,CAAC,QAAQ,EAAE,SAAS,EAAE,SAAS,EAAE,OAAO,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,KAAK,CAAC;QAAE,MAAM,IAAI,SAAS,CAAC,yBAAyB,CAAC,CAAC;IACrH,IAAI,KAAK,CAAC,QAAQ,KAAK,IAAI,IAAI,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,QAAQ,CAAC,IAAI,KAAK,CAAC,QAAQ,GAAG,CAAC,CAAC;QAAE,MAAM,IAAI,UAAU,CAAC,mDAAmD,CAAC,CAAC;IACnK,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,QAAQ,CAAC,IAAI,KAAK,CAAC,QAAQ,GAAG,CAAC;QAAE,MAAM,IAAI,UAAU,CAAC,mDAAmD,CAAC,CAAC;IACtI,MAAM,WAAW,GAAG,KAAK,CAAC,QAAQ,KAAK,IAAI,IAAI,KAAK,CAAC,QAAQ,GAAG,CAAC,CAAC;IAClE,OAAO,EAAE,GAAG,KAAK,EAAE,QAAQ,EAAE,WAAW,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,QAAQ,EAAE,KAAK,CAAC,QAAS,CAAC,CAAC,CAAC,CAAC,CAAC;QACtF,OAAO,EAAE,CAAC,KAAK,CAAC,QAAQ,IAAI,KAAK,CAAC,KAAK,KAAK,SAAS,IAAI,KAAK,CAAC,KAAK,KAAK,OAAO,IAAI,WAAW;QAC/F,OAAO,EAAE,CAAC,KAAK,CAAC,QAAQ,IAAI,KAAK,CAAC,KAAK,KAAK,SAAS,IAAI,KAAK,CAAC,KAAK,KAAK,OAAO,IAAI,WAAW,EAAE,CAAC;AACtG,CAAC","sourcesContent":["export type VoiceNoteState = \"paused\" | \"playing\" | \"loading\" | \"error\";\nexport type VoiceNoteDescriptor = Readonly<{\n  title: string;\n  state: VoiceNoteState;\n  /** null means metadata has not loaded. Zero is a known empty recording. */\n  duration: number | null;\n  position: number;\n  disabled?: boolean;\n}>;\n/** Normalize host media metadata without inventing playback or loading progress. */\nexport function resolveVoiceNote(input: VoiceNoteDescriptor) {\n  if (!input.title.trim()) throw new TypeError(\"VoiceNote requires a title\");\n  if (![\"paused\", \"playing\", \"loading\", \"error\"].includes(input.state)) throw new TypeError(\"Unknown VoiceNote state\");\n  if (input.duration !== null && (!Number.isFinite(input.duration) || input.duration < 0)) throw new RangeError(\"VoiceNote duration must be finite and nonnegative\");\n  if (!Number.isFinite(input.position) || input.position < 0) throw new RangeError(\"VoiceNote position must be finite and nonnegative\");\n  const hasDuration = input.duration !== null && input.duration > 0;\n  return { ...input, position: hasDuration ? Math.min(input.position, input.duration!) : 0,\n    canPlay: !input.disabled && input.state !== \"loading\" && input.state !== \"error\" && hasDuration,\n    canSeek: !input.disabled && input.state !== \"loading\" && input.state !== \"error\" && hasDuration };\n}\n"]}

package/docs/action-session.md

@@ -0,0 +1,73 @@
+# 공통 실행과 실패 복구
+
+검토일: 2026-10-02 · 상태: 선택적 행동 API, Storybook 실험 단계
+
+## 문제와 기존 API의 관계
+
+2026-10-02 Atlas 검토와 사용자 요청에서 일반 저장·낙관적 반영의 실패 복구가 앱별로
+연결된다는 점을 확인했다. Button은 전달받은 loading 중 실행 차단, AlertDialogSession은
+확인창의 비동기 확인·닫기를 이미 소유한다. 이들을 새 버튼·확인창으로 복제하지 않는다.
+`createActionSession`은 확인창 밖 작업의 상태만 제공하며 기존 컴포넌트와 합성한다.
+AlertDialog.onConfirm에 연결할 때에는 기존 확인창 세션을 우선하고 이중 상태를 만들지 않는다.
+
+## 계약과 기본값
+
+```ts
+import { createActionSession } from '@hjmds/design-contracts/action-session';
+const save = createActionSession(''); // 제품의 화면 또는 작업 소유자가 한 번 생성
+const submitted = draft; // 재시도 중 바뀐 입력을 읽지 않도록 제출 시점의 값을 캡처
+await save.run(() => api.save(submitted), { retryable: true });
+```
+
+- 상태는 idle → pending → success/error. 서버 어댑터가 resolve하기 전 성공을 표시하지 않는다.
+- 같은 세션의 pending 중 새 run/retry는 blocked이며 작업 함수를 호출하지 않는다.
+- 실패는 throw 대신 error 결과와 snapshot.error로 전달한다. 오류 문구와 재시도 가능성은 제품이
+  정한다. raw exception을 사용자에게 직접 노출하지 않는다.
+- retryable 기본값은 false. 재시도가 안전하다고 제품이 명시한 경우에만 실패한 작업 함수를
+  다시 호출한다. 서버가 멱등 처리를 지원하면 **동일 제출의 재시도에는 동일 제품 요청 키**를
+  캡처해 사용한다. 이 helper의 operationId는 세션 안 응답 순서용 숫자이며 서버 멱등 키가 아니다.
+- optimisticValue는 저위험 변경에만 사용한다. 즉시 pending 값으로 보이고, 성공 시 서버가
+  반환한 값을 확정한다. 실패하면 직전 확인 값으로 돌아간다. 객체 값은 불변 데이터로 전달한다.
+- reset(value)는 세대를 바꿔 이전 응답과 재시도를 무효화한다. 실제 서버 작업을 취소하지 않는다.
+  제품은 계정·엔티티 변경 시 필요한 취소/재조회/캐시 무효화를 처리한다. 오래된 작업이 서버에
+  반영됐을 가능성이 있으면 이 helper만으로 정합성을 보장하지 않는다.
+- 자동 재시도·네트워크·타이머·저장소·전역 싱글턴은 없다. 세션을 엔티티별로 유지한다.
+  task 함수를 버리려면 reset을 호출하며 렌더 중 세션을 새로 생성하지 않는다.
+
+## 웹과 앱 연결
+
+React와 React Native 모두 `useSyncExternalStore(session.subscribe, session.getSnapshot,
+session.getSnapshot)`로 구독한다. SSR은 요청별 세션을 생성하고 hydration 초기값을 맞춘다.
+Button.loading은 pending, 오류 안내는 error에서 제품이 지역화한 문자열로 표시한다.
+웹은 status/alert, Native는 플랫폼 접근성 알림을 사용한다. HJM 모션·포커스·busy 처리는
+기존 renderer가 계속 맡는다. store는 별도 React 훅·UI 패키지를 요구하지 않는다.
+
+세션을 화면보다 오래 보존해야 하면 제품의 작업 소유자에 둔다. 화면 unmount 시 자동 reset은
+진행 중 작업 결과를 버릴 수 있어 기본값으로 넣지 않았다. 서버 캐시나 TanStack Query를 이미
+쓰는 앱은 기존 mutation 상태를 유지하고 중복 session을 추가하지 않는다. 이 계약의
+중복 방지·오류·복구 원칙을 기존 계층에 연결한다.
+
+## 초안과 실행 취소
+
+초안은 입력 state/제품 저장소의 소유다. 실패 시 지우지 않고 재시도에서는 캡처한 제출 값을
+사용한다. 현재보다 오래된 성공 응답으로 사용자가 새로 입력한 초안을 지우지 않는다.
+프로세스 종료 복구·로그아웃 정리·암호화·오프라인 outbox는 제품 저장소가 결정한다.
+
+실행 취소는 제품이 제공한 역연산을 run으로 실행해 성공 확인 후 복구한다. 토스트는 액션 진입점,
+세션은 진행·실패 상태만 소유한다. 권한·만료·대상 버전·복구 데이터는 제품이 검증한다.
+UI를 되돌렸다는 이유로 서버 취소 완료를 선언하거나 금융·영구 삭제에 가짜 Undo를 넣지 않는다.
+
+## 검증 화면과 범위
+
+Web/Native Storybook `실험/구성/공통 동작`의 저장과 재시도, 즉시 반영과 복구, 보관과 실행 취소.
+각각 기본·어두운 테마·큰 글자 상태. 데모만 350ms 인위 지연과 실패 주입을 제공하며 실제 API나
+영속 저장소는 연결하지 않는다. 보관 데모에 자동 만료는 없다. 실험의 스토리북 배포는 사용자 승인 후다.
+
+회귀 검사는 중복 실행 차단, sync throw, 명시적인 재시도 허용, 낙관적 rollback, 새 세대 이후
+역순 성공/실패 무시, 구독 해제, 실패한 역연산의 상태 보존을 검증한다. 실기기·소비 앱 채택과는 별개다.
+
+## 패키지 경계와 크기
+
+`./action-session` subpath만 추가하고 root/catalog에 새 컴포넌트를 만들지 않는다. manifest의
+새 경로 이유는 위의 일반 작업/확인창 역할 분리다. 초기 ESM 2504 bytes / gzip 889 bytes,
+1 module을 측정했고 신규 예산은 2900 / 1050 bytes로 설정했다. 기존 예산은 변경하지 않았다.

package/docs/activity-heatmap.md

@@ -0,0 +1,32 @@
+# Activity heatmap
+
+Reviewed: 2026-10-01. `/activity-heatmap` exports ActivityHeatmap on Web and Native.
+Use it for a year-sized activity overview; Calendar remains the date-picker owner.
+The showcase profile-activity fixture demonstrates its intended consumption. Values
+are local demonstration data, not evidence of user engagement or GitHub activity.
+
+The descriptor accepts inclusive ISO `startDate` and `endDate`, unique `days` entries
+`{date, value}`, optional increasing positive `thresholds` (default 1, 3, 7), and
+`weekStartsOn` (0 Sunday or 1 Monday, default Monday). Values must be finite and
+nonnegative. Duplicate/out-of-range dates, invalid calendar dates and inverted or
+longer-than-366-day ranges throw. Products paginate longer histories to keep the
+visual overview and Native accessibility traversal bounded.
+
+UTC calendar arithmetic avoids daylight-saving day shifts. Missing entries remain
+`null`; an explicit zero stays zero. Missing cells have a dashed outline. Nonzero
+values map to four intensities: up to the first threshold, then the second, then
+the third, then above it. Zero and unknown use the neutral surface. The semantic
+brand palette controls intensity; no provider-specific colors or fetching are built in.
+
+Pass localized `label` and `formatDay(date, value)`; handle null explicitly.
+Grid cells have those accessible labels and the Web also exposes hover titles.
+`view="list"` provides the same information as visible text, so color is not the
+only way to inspect values. The product supplies the view toggle using Button.
+Native hosts put long lists in their own vertical ScrollView. Grid rendering scrolls
+horizontally and is read-only; these small cells are not undersized tap targets.
+
+Both showcases register `컴포넌트/데이터 표시/Activity Heatmap` with Default, Dark and
+LargeText, including a functional list toggle. Contract and renderer tests verify
+leap dates, missing/zero semantics, invalid data and accessible values. Native host tests are supplemented by the [LargeText simulator flow audit](../../../docs/evidence/component-flows-2026-10-01/README.md):
+list/grid switching, unknown-data wording and readable date/value rows were verified.
+Physical-device rendering and manually heard VoiceOver traversal remain unverified.

package/docs/anchor.md

@@ -54,7 +54,7 @@ listener·observer·예약 frame을 해제합니다. CSS transform만으로 위
 Web 전용입니다. Native 라우팅·목록 위치 이동은 해당 플랫폼과 제품이 소유하며 빈 RN wrapper를
 추가하지 않습니다. 중첩 트리 목차·자동 제목 수집·오버레이 anchor positioning은 포함하지 않습니다.
 
-`Patterns/Anchor`는 세 부분으로 나눈 읽기 가이드와 별도 스크롤 영역을 제공합니다.
+`컴포넌트/탐색/Anchor`는 세 부분으로 나눈 읽기 가이드와 별도 스크롤 영역을 제공합니다.
 브라우저 테스트는 위치 동기화·짧은 마지막 부분·offset·reduced motion·임시 focus 복원·
 fragment 복구·나중에 삽입된 대상·좁은 목차의 긴 label 줄바꿈·Tab/Enter 활성화와 문서 스크롤을 검사합니다.
 실제 제품 문서 채택·보조기기 검증은 남아 있습니다.

package/docs/auth-screen.md

@@ -1,5 +1,7 @@
 # AuthScreenLayout — 로그인 화면의 두 영역 골격
 
+검토일: 2026-10-01
+
 ## 문제
 
 계정이 있는 제품들이 같은 화면을 각자 만들었고, 같은 실수를 각자 했다.
@@ -26,6 +28,37 @@
 `density`는 `compact`/`regular` 둘뿐이다. 제품이 화면 높이를 보고 고르며 HJM은 기기 종류를
 추측하지 않는다 — 같은 폭이라도 키보드가 올라오면 좁아진다.
 
+## 로그인 카드 진행 상태
+
+2026-10-01 사용자 요청에 따라 로그인 화면의 제공자 버튼은 이름만 표시한다
+(`카카오`, `네이버`, `Google`, `Apple`). HJM은 전달받은 label을 임의로 잘라내지 않으며
+제품이 지역화 카탈로그에서 문구를 바꾼다.
+
+Web·Native `AuthScreenLayout`의 `mainCard`는 주 행동을 공통 카드로 감싼다. 이미 제품이
+카드를 공급하는 기존 화면과 중첩되지 않도록 기본값은 false이며, 새 조합은 mainCard를 켜고
+main 슬롯에는 버튼 목록만 넣는다. 배경·padding·radius는 바깥 카드가 계속 소유한다.
+
+인증 시작 시 지역화된 `pendingLabel`(예: `로그인 중`)을 전달하면 모든 주 행동을 숨기고
+같은 카드의 정중앙에 하나의 로딩 표시를 띄운다. 내용은 크기와 폼 상태를 유지하기 위해
+mount된 채 남지만 Web inert와 Native touch/accessibility 제외로 조작할 수 없다.
+2026-10-01 추가 사용자 요청에 따라 pendingLabel은 스크린리더 안내로만 사용하며 로딩 아래에 문구를 표시하지 않는다.
+pendingLabel은 비어 있으면 거부한다. 취소·실패 시 이 prop을 제거하면 버튼이 돌아온다.
+hero와 footer는 진행 중에도 유지한다. 버튼별 busy spinner와 함께 쓰지 않는다.
+
+```tsx
+<AuthScreenLayout
+  mainCard
+  {...(loginPending ? { pendingLabel: t("auth.pending") } : {})}
+  hero={hero}
+  main={providerButtons}
+  footer={policyLinks}
+/>
+```
+
+제품은 pending 여부가 바뀌어도 같은 버튼 목록을 main에 전달해야 카드 크기가 유지된다.
+진행 중 버튼 목록을 조건부 제거하거나 다른 내용으로 교체하지 않는다. 로딩은 기존 로그인
+카드가 있는 상태에서 전환하는 계약이며 최초 제공자 목록 조회의 skeleton을 대신하지 않는다.
+
 ## HJM 기본값
 
 | 값 | 기본 | 근거 |
@@ -53,13 +86,20 @@
 
 | | Web | Native |
 | --- | --- | --- |
-| 뿌리 요소 | `<main class="hjm-auth-screen">` + 인라인 custom property | `ScrollView` + `contentContainerStyle.flexGrow: 1` |
+| 뿌리 요소 | 기본 `<main>`, 앱 셸이 main을 소유하면 `as="section"` + 인라인 custom property | `ScrollView` + `contentContainerStyle.flexGrow: 1` |
 | 세로 중앙 | `flex: 1` 블록의 `justify-content: center` | 같은 구조를 `View`의 `flex: 1`로 |
 | 스크롤 전환 | `min-block-size: 100dvh` + 자연 스크롤 | `ScrollView`가 내용이 길 때만 스크롤 |
 | 수치 전달 | 해석된 값을 CSS 변수로 — 스타일시트와 계약이 어긋날 수 없다 | 인라인 스타일 |
 
 ## 검증 화면
 
-아직 없음. 소비 제품(번뚝·다에리)의 로그인 화면을 이 골격으로 옮기는 작업이 남아 있고,
-Showcase canonical preview와 6종 evidence(default·dark·long copy·large text·RTL·reduced motion)도
-아직이다. 현재 상태는 **계약·렌더러·테스트까지**다.
+현재 catalog와 생성 evidence에서 Web·Native 모두 stable이며, canonical preview와
+default·dark·long copy·large text·RTL·reduced motion·accessibility 증거가 연결돼 있다.
+2026-10-01 문서 점검에서 초기 구현 시점의 “아직 없음” 설명이 현재 projection과 어긋나
+이를 정정했다. 근거는 [성숙도](generated/component-maturity.md)와
+[renderer evidence](generated/renderer-evidence.md)의 AuthScreenLayout 항목이다.
+
+이 증거는 HJM renderer 범위다. 소비 제품의 로그인 이관·실제 OAuth·기기 실행·게시 상태는
+제품별 검증으로 확인한다. [제품 채택 가이드](product-adoption-1.4.md)의 슬롯·키보드·
+중첩 main 처리 기준을 따른다. 포트폴리오 제품은 상위 로그인 화면 표준(LS)을 함께 적용하며,
+`hasFooter: false` 옵션이 필수 정책 링크 생략을 허용하는 것은 아니다.

package/docs/authoring-brief.md

@@ -86,3 +86,8 @@ pnpm typecheck && pnpm test
 - 판단이 갈렸던 자리: <대안과 택한 이유>
 - 게이트: typecheck <결과> / test <N passed>
 ```
+
+## 상호작용 저작 보완 · 2026-10-02
+
+[제품 상호작용 기준](../../../docs/INTERACTION_QUALITY.md)에 따라 동작 소유권·중단·복구와
+성능에 영향을 주는 변경의 측정 범위를 기록한다. 원본 영상만으로 동등한 성능을 주장하지 않는다.

package/docs/avatar-fallback.md

@@ -0,0 +1,74 @@
+# Avatar fallback and Blobatar
+
+Reviewed: 2026-10-01. Implemented locally; package publication and consumer adoption are separate.
+
+`Avatar` remains the sole canonical component. Both renderers accept
+`renderFallback({ size, decorative: true })`. The factory is called only while a
+photo is absent or has failed. Returning null/undefined preserves the existing
+Web `fallback` or Native initials. Existing consumers are unchanged.
+
+The Avatar owns the accessible name; custom fallback content is decorative and
+must not contain interactive controls. Native hides fallback descendants from
+accessibility. Photo source changes retry loading rather than retaining an old
+failure. Web continues forwarding the image error callback.
+
+## Optional adapter
+
+Import `createBlobatarFallback` from `@hjmds/react/avatar-blobatar` or
+`@hjmds/react-native/avatar-blobatar`. Neither root imports the adapter.
+Install `blobatar@2.7.0` and the matching `@blobatar/react@2.7.0` or
+`@blobatar/react-native@2.7.0`; Native additionally uses the existing supported
+`react-native-svg` peer. The static entry needs no Reanimated or Worklets import.
+
+```tsx
+const renderFallback = useMemo(
+  () => createBlobatarFallback({ seed: account.publicAvatarId, expression: 'idle' }),
+  [account.publicAvatarId],
+);
+// Web: <Avatar name={displayName} src={photo} renderFallback={renderFallback} />
+// Native: <Avatar name={displayName} source={photo} accessibilityLabel={displayName}
+//                 renderFallback={renderFallback} />
+```
+
+Only `idle` and `happy` static expressions are currently exposed. There is no
+`motion` option in this first implementation. Use the same public product seed on
+both platforms; names, emails, credentials and inferred emotions are not seeds.
+Normalization is explicitly disabled to preserve case-sensitive account identity.
+Generation is local (Web data URI, Native SVG paths). No avatar server is called.
+Pinned upstream versions prevent an incidental generator upgrade from changing
+existing faces. React adapters retain upstream generation rather than approximating
+its artwork with a second generator. MIT notices remain in the upstream packages.
+
+`패턴/프로필 편집` in both showcases demonstrates choosing a face,
+editing a display name, toggling notifications, applying and reverting local
+changes. Copy is keyed in the shared showcase fixture; it is not embedded in the
+renderer. This is a composition example, not an account API or new canonical screen.
+The original [integration plan](../../../docs/plans/visual-and-motion-integration-2026-10-01.md)
+tracks later animation, theme and marketing work.
+
+## Optional motion and expressions (2026-10-01)
+
+`/avatar-blobatar-motion` on each renderer exports `createAnimatedBlobatarFallback`.
+It accepts a stable public `seed`, `expression` (idle, happy, sad, surprised, wink,
+sleepy or thinking), `active` (default false), and `visible` (default true). Pass its
+result into the existing Avatar `renderFallback`. Avatar still owns naming and image
+fallback; the animated artwork remains decorative.
+
+The Web entry imports Blobatar's motion stylesheet and observes intersection/document
+visibility. Native uses the upstream optional AnimatedBlobatar entry, requiring the
+host's compatible Reanimated/Worklets, and observes AppState. Native hosts must pass
+route/list visibility explicitly. Native switches to the static upstream renderer when
+inactive, hidden, reduced or backgrounded: upstream 2.7.0 keeps its frame callback
+running with `animate=false`, as confirmed by device-host CPU sampling. Seed and
+expression are preserved, while the idle clock restarts when re-enabled.
+Both honor HJM reduced motion and never enable
+idle animation without `active`. Static `/avatar-blobatar` remains available without
+motion imports. The pinned Blobatar 2.7.0 generation and original license remain.
+
+컴포넌트/데이터 표시/Animated Blobatar provides Default, Dark and LargeText in both
+showcases, with explicit pose and motion controls. Native gating tests mock the
+upstream rendering boundary; the subsequent [Native integration audit](../../../docs/evidence/native-visual-integration-2026-10-01/README.md)
+adds installed iPhone 17 / iOS 27 simulator captures and active/stopped CPU samples
+from the real upstream runtime. The inactive frame-loop correction is backed by
+those samples. This does not establish physical-device GPU timing, battery use,
+or exhaustive geometry and screen-reader behavior.

package/docs/bottom-navigation.md

@@ -35,7 +35,7 @@ const descriptor = {
 
 시각·플랫폼 선택은 별도 `BottomNavigationConfiguration`으로 전달합니다.
 
-- `presentation`: `bar | floating`
+- `presentation`: `bar | floating | capsule`
 - `distribution`: `equal | center-gap`
 - `density`: `compact | regular`
 - `direction`: `ltr | rtl`
@@ -126,3 +126,18 @@ distribution을 선택하고 outer Dock frame에서 기존 Button/IconButton 기
 합성합니다. 이 action은 tab role, selected state, badge, `selectedKey`, destination count를
 가질 수 없습니다. Web은 button, RN은 button role과 activate action을 사용하며 제품 router나
 modal API를 직접 호출합니다.
+
+## Capsule presentation (2026-10-01)
+
+`configuration={{ presentation: "capsule" }}`는 둥근 route 표면과 선택된 항목의 가로형
+icon/label을 제공합니다. `primaryAction`은 컬렉션 밖의 별도 원형 행동으로 배치됩니다.
+`center-gap`과 함께 지정하면 오류입니다. 생성 행동이 route로 오인되거나 중앙에서 이름을
+가리는 것을 방지하기 위한 선택입니다.
+
+기본 크기에서 비선택 항목의 시각 label은 접히지만 전체 접근성 이름/배지/route intent는
+그대로 유지됩니다. 큰 글씨(1.5 이상) 또는 5–6개 목적지는 모든 이름을 세로 배치해 표시합니다.
+기존 bar/floating 및 router 소유 selectedKey는 바뀌지 않습니다.
+[사용자 레퍼런스 두 번째 이미지](https://www.instagram.com/p/Ddb8lXmjnV9/?img_index=2)의
+선택 캡슐과 분리된 추가 행동을 참고했으며, 원본 소스는 복제하지 않았습니다.
+
+Storybook: **컴포넌트 → 탐색 → 캡슐 네비게이션**, Default/Dark/LargeText.

package/docs/breadcrumb.md

@@ -74,7 +74,7 @@ Web에서는:
 경로도 유지합니다. 필수 props는 `label`, `items`이고 `ref`는 nav 요소를 가리킵니다.
 
 2026-09-16 사용자의 React/RN 라이브러리 확장 요청으로, 제품 채택 대기와 라이브러리 beta
-제공을 분리했습니다. `Patterns/WebNavigation`은 조상 링크로 보관함을 열고 다시 기록 목록으로
+제공을 분리했습니다. `갤러리/웹 탐색`은 조상 링크로 보관함을 열고 다시 기록 목록으로
 돌아오는 작동 예제입니다. 제품 채택이나 stable 증거로 계산하지 않습니다.
 
 [WAI Breadcrumb](https://www.w3.org/WAI/ARIA/apg/patterns/breadcrumb/)의 landmark·조상 링크·

package/docs/calendar.md

@@ -15,7 +15,7 @@
 
 과거 Yajalal 조사에서는 월 격자가 날짜 레일로 바뀌어 살아 있는 Calendar 소비 화면이 없었다.
 이번 구현의 근거는 React/RN 컴포넌트를 채우라는 명시 요청이며, 검증 화면은 Showcase의
-`Patterns/Calendar` 기록 탐색이다. 이를 Yajalal 채택으로 기록하지 않는다.
+`컴포넌트/입력/Calendar` 기록 탐색이다. 이를 Yajalal 채택으로 기록하지 않는다.
 
 ## 경계
 

package/docs/cascader.md

@@ -110,7 +110,7 @@ collection + tri-state 판정 모듈)으로 확정됐고, Tree renderer가 들
   않으므로 막아 둔 자리를 여는 새 축이 필요 없다.
 
 그래서 catalog의 Cascader 행은 `prerequisite`에서 `composed`(Popover·Tree)로 옮겼고,
-작동 예제는 Showcase `Patterns/Tree`의 Cascader 화면이다. "만들지 않는다"는 판정 자체는
+작동 예제는 Showcase `컴포넌트/데이터 표시/Tree`의 Cascader 화면이다. "만들지 않는다"는 판정 자체는
 그대로다 — 바뀐 것은 흡수하는 쪽이 컴포넌트가 아니라 조합이라는 점뿐이다.
 
 

package/docs/code-block.md

@@ -0,0 +1,32 @@
+# Code block
+
+Reviewed: 2026-10-01. Optional `/code-block` entries in both renderers expose
+`CodeBlock`. This is a source preview, not an editor or executable HTML renderer.
+The visual integration request required syntax presentation without another input
+or clipboard engine, so source validation belongs to contracts and actions are slots.
+
+Pass `code`, a localized `label`, optional `language`, `wrap` and `tokens`.
+Tokens have `{text, tone?}` where tone is plain, keyword, string, comment or number.
+Their text must concatenate to the original code exactly, including whitespace;
+invalid output throws. Use a product-selected highlighter to generate tokens.
+No parser, remote highlighting service, raw HTML or execution is included. The
+semantic palette supplies readable token colors; string/plain may share a color.
+
+Long lines scroll horizontally by default. `wrap` opts into wrapping. On Web the
+preformatted source is keyboard-focusable and selectable; on Native it uses a
+selectable Text inside the existing horizontal ScrollView. The Native accessible
+name includes the original source as well as its label, so naming does not hide code.
+
+`copyAction` accepts an existing product control. Web can pass HJM ClipboardButton
+with `value={code}`, localized idle/copied labels and a visible `onCopyError` response.
+Native can use system text selection directly or supply the product's clipboard
+button. No Expo clipboard peer is pulled into the generic renderer. The Native
+showcase demonstrates actual system selection; it does not fake a copied state.
+
+Both showcases register `컴포넌트/데이터 표시/Code Block`. Contract tests reject altered
+highlight text; browser tests check literal script text, focus and wrapping; Native
+host tests check selectable content and scroll/wrap composition. The
+[Native flow audit](../../../docs/evidence/component-flows-2026-10-01/README.md) verifies
+200% controlled text scaling and actual iOS simulator long-press Copy, with exact
+source/clipboard equality. Header and source use the common text-scale helper;
+token spans inherit once. Android clipboard and physical-device verification remain separate.

package/docs/command-palette.md

@@ -134,4 +134,4 @@ Native는 `unsupported`다. 전역 단축키는 제품 소유다.
 - **전역 단축키는 제품 소유다.** 이 renderer는 여는 키를 정하지 않는다.
 - 로컬 검증: `test/command-palette.browser.test.tsx` 5개(이름·초점·배경 inert, 활성 행과
   disabled 건너뜀·재필터, 실행 시 강제 종료와 사유, 종료 후 후속 명령 순서, Escape·바깥
-  pointer 종료)와 `Patterns/CommandPalette`.
+  pointer 종료)와 `컴포넌트/탐색/Command Palette`.

package/docs/compound-controls.md

@@ -0,0 +1,83 @@
+# Compound controls
+
+Reviewed: 2026-10-01. Web and React Native expose identical optional entry names:
+`/duration-field`, `/inline-confirm`, `/reaction-picker`, `/notification-bell`.
+These are compositions of existing canonical controls, not replacements for them.
+The 2026-10-01 visual integration request calls for reusable interactions as well as
+page examples; keeping the existing controls preserves their disabled, focus and
+loading behavior instead of introducing another control implementation.
+
+## DurationField
+
+Use for bounded elapsed time (integer seconds), not clock time or calendar dates.
+Pass `value`, `onValueChange`, required `max`, optional `min` (default 0), and
+`labels: {label, hours, minutes, seconds, increment(unit), decrement(unit)}`.
+All labels are localized by the product. Three existing NumberFields edit the
+hours/minutes/seconds representation. The shared `/duration-field` contract
+validates safe integers and clamps the *combined* duration to the configured range.
+Native field columns wrap according to the text scale so enlarged numeric values stay visible.
+Hours are disabled when the maximum is below one hour. `disabled` disables all
+inputs. Values outside the range throw rather than silently changing product state.
+
+## InlineConfirm
+
+Use for a local explicit confirmation when an overlay would interrupt the context.
+Pass `label`, `prompt`, `confirmLabel`, `cancelLabel`, `pendingLabel`,
+`successLabel`, `errorLabel`, and `onConfirm(): void | Promise<void>`.
+The existing AlertDialog session owns async deduplication, pending and retry.
+No action runs on the initial trigger. Pending disables both actions; rejection
+shows the supplied safe error text and permits retry. Web initially focuses cancel,
+Escape cancels, and cancellation restores trigger focus. Native exposes the
+controls and live error text through its host accessibility APIs.
+Native keeps the localized status text available to assistive technology. iOS
+receives one explicit announcement per prompt/pending/error/success transition;
+errors interrupt queued speech, other updates queue politely. Repeated rendering,
+completion's internal closing phase and background updates do not repeat the prompt.
+Android retains its live-region/alert semantics. Native bridge calls are lifecycle-tested;
+this is not a claim that VoiceOver audio was manually heard.
+
+Success remains visible. Remount with a new entity key to reset the interaction;
+the session captures the action and labels when opened. The product owns operation
+cancellation, authorization, persistence and server-side idempotency.
+
+## ReactionPicker
+
+Pass a nonempty list of `{id, emoji, label, count?, disabled?}`, controlled
+`value: string | null`, `onValueChange`, and the group `label`.
+The shared `/reactions` contract rejects duplicate IDs, invalid counts and unknown
+selected IDs. Selecting the current reaction clears it; selecting another replaces
+it. Existing Buttons own selection and disabled semantics. Counts are product data
+and never increment implicitly. Include counts in localized option labels when
+needed for screen readers; visible emoji/count artwork is decorative. Native passes
+one composed text label to Button so emoji and count use its Text wrapper; sibling
+raw strings bypass that wrapper and fail to render on a real device.
+
+## NotificationBell
+
+Pass `label`, nonnegative integer `count`, `icon`, `onPress`, and optionally
+`disabled` or `active`. Supply the localized unread information in `label` and a
+semantic Icon/Lucide glyph as `icon`. Existing IconButton and CounterBadge own the
+control and count presentation. Artwork and badge are hidden from accessibility
+so the button is announced once.
+A count increase triggers one 400ms pulse; mounting or decreasing does not ring.
+Reduced motion, inactive presentation and background document/AppState suppress
+motion. Native hosts should set `active={false}` for offscreen items. Pressing does
+not mark notifications read automatically; that operation belongs to the product.
+
+## Evidence and examples
+
+Both showcases register `컴포넌트/입력/Duration Field`,
+`컴포넌트/동작/Inline Confirm`, `컴포넌트/동작/Reaction Picker` and
+`컴포넌트/피드백/Notification Bell`, each with Default, Dark and LargeText.
+`갤러리/복합 입력` provides the comparison examples. Web browser and Native
+host-action tests exercise clamp, confirmation/retry/deduplication, controlled
+reactions and motion suspension. Native host tests are not device-render evidence;
+actual iPhone 17 / iOS 27 simulator LargeText cancel/error/retry/success/reset flows
+are recorded in the [component flow audit](../../../docs/evidence/component-flows-2026-10-01/README.md).
+Remaining device coverage stays tracked in the
+[implementation ledger](../../../docs/plans/visual-integration-progress.md).
+
+The same [Native flow audit](../../../docs/evidence/component-flows-2026-10-01/README.md)
+also verifies LargeText duration unit increments/decrements and total seconds, reaction
+selection/replacement/clearing, and local bell read/add state. These are actual simulator
+actions, distinct from backend notification delivery and physical-device screen-reader QA.

package/docs/confirm-popover.md

@@ -99,7 +99,7 @@ Component Explorer에서 이 문서로 연결한다.
 
 ## 2026-09-16 작동 예제
 
-React/RN 확장 요청에 따라 `Patterns/Popover/ReversibleConfirmation`을 제공한다.
+React/RN 확장 요청에 따라 `컴포넌트/오버레이/Popover/ReversibleConfirmation`을 제공한다.
 `@hjmds/react/popover`의 children 함수에서 `close()`와 HJM Button을 조합한다.
 취소 버튼을 초기 초점으로 지정하고, 보관 후 사라지는 트리거 대신 보관 취소 버튼에
 초점을 보낸다. 보관 취소는 실제 로컬 상태를 복원한다. 외부 서버 요청이나 배포 증거는 아니다.

package/docs/consumer-policy.md

@@ -1,13 +1,13 @@
 # HJM 소비 앱 정책
 
 상태: **Normative**
-정책 버전: **1.4.0**
+정책 버전: **2.0.0**
+검토일: 2026-10-02 · 전체 소비 이관에 따른 deprecated API 제거
 적용 대상: 신규 HJM Web·React Native 앱과 기존 앱의 새 화면
 
-이 정책 원문은 다음 package patch release부터
-`@hjmds/design-contracts/consumer-policy.md` export에 포함됩니다. 아직 그 export를 포함하지
-않는 `0.9.0` 소비자는 HJM-APP-STANDARD의 versioned profile과 catalog snapshot을 정책
-근거로 사용하고, 존재하지 않는 `v0.9.0` 정책 URL을 만들어 내면 안 됩니다.
+이 원문은 `@hjmds/design-contracts/consumer-policy.md`에서 제공한다. 소비 앱은 설치한
+패키지 버전의 정책과 HJM-APP-STANDARD release snapshot을 함께 확인한다. 이 checkout의
+1.11 소스 갱신을 아직 설치하지 않은 앱에 자동 적용된 것으로 판단하지 않는다.
 
 이 문서는 "HJM답게 보인다"를 특정 화면 복제로 정의하지 않습니다. 모든 제품이 공유해야
 하는 것은 정보 위계, semantic role, 상태 피드백, 접근성 품질과 플랫폼별 행동입니다.
@@ -93,23 +93,15 @@ foundation이 모두 stable이 됐으므로, 중앙 app profile의 다음 개정
 
 ### 3.1 React Native legacy style compatibility boundary
 
-`@hjmds/react-native` 0.9.x의 공개 타입에는 `style`, `labelStyle`, `inputStyle`,
-`containerStyle`과 여러 slot `*Style`처럼 전체 React Native style을 받는 호환 API가 남아
-있습니다. 이 타입 범위와 caller-last 렌더 순서는 기존 소비자를 위한 집행 공백이지, 앞 절의
-금지 속성을 제품이 덮어써도 된다는 허가가 아닙니다.
-
-- 신규 앱과 기존 앱의 새 화면은 legacy raw style prop을 새로 사용하면 안 됩니다(MUST NOT).
-  컴포넌트가 `layoutStyle`을 제공하면 배치에는 그것만 사용하고, 제공하지 않으면 바깥
-  composition wrapper를 사용하거나 HJM에 semantic axis를 먼저 추가해야 합니다(MUST).
-- `HjmCompositionStyle` / `layoutStyle`은 margin, width, flex 계열과 `alignSelf`만 노출하며
-  color, typography, padding, gap, border, radius, height, opacity, transform과 interaction
-  state key를 타입에서 제외합니다. 허용된 margin 값도 HJM spacing token 또는 검토된 제품
-  adapter에서 와야 합니다(MUST).
-- 기존 화면의 legacy prop은 migration 기간에만 유지할 수 있습니다(MAY). controlled visual
-  key가 남아 있으면 정책 항목, 소유자, 대체 semantic API와 제거 train을 ADR에 기록해야
-  하며, 신규 사용으로 복사해서는 안 됩니다(MUST NOT).
-- 0.9 호환 train에서는 등록 style ID와 배열을 런타임에서 필터링하거나 조용히 삭제하지
-  않습니다. 그러한 즉시 변경은 기존 앱의 레이아웃을 예측 불가능하게 깨뜨리기 때문입니다.
+2026-10-02 전체 소비 버전업 결정에 따라 deprecated 공개 스타일 통로는 1.11에서 제거합니다.
+정확한 제거 속성과 대체 API는 [1.11 이관표](migration-native-legacy-removal.md)를 따릅니다.
+1.x 설치본의 caller-last 호환 동작은 역사적 동작이며 현재 소스에 유지되지 않습니다.
+
+- 배치에는 `layoutStyle`을 쓰고, 제공하지 않는 컴포넌트는 외부 composition wrapper를 씁니다.
+- `HjmCompositionStyle` / `layoutStyle`은 margin, width, flex 계열과 `alignSelf`만 제공합니다. color,
+  typography, padding, gap, border, radius, height, opacity, transform은 recipe/semantic API 소유입니다.
+- 내부 조합의 스타일은 비공개 renderer에 두며 앱에서 해당 내부 파일을 import하지 않습니다.
+- 정식 플랫폼 host·제품 소유 슬롯·이미지 renderer 스타일을 deprecated 별칭과 혼동하지 않습니다.
 
 소비 앱의 legacy prop이 실제로 무엇을 덮어쓰고 있었는지 확인한 뒤, 배치가 아닌 값은
 semantic axis로 옮겼습니다. 아래는 그 축과 대체 대상입니다.
@@ -165,7 +157,7 @@ legacy raw style surface는 다음 조건이 모두 충족된 뒤 공지된 brea
 “1.0.0 이전 제거” 기한은 실제 release/API와 어긋나므로 폐기합니다. 이미 게시한 1.x의 타입과
 런타임을 minor에서 삭제하는 대신, 위 네 조건과 소비 앱별 이관 목록을 충족한 다음 major에서
 제거합니다. 1.4는 semantic API와 이관 경로를 추가하는 train이며, 기존 prop을 새 화면에 쓰는
-것은 계속 금지합니다. 제거 예정 major는 소비 이관 완료 후 Changeset에서 확정합니다.
+것은 계속 금지합니다. 2026-10-02 사용자의 전체 이관 결정으로 제거 train을 1.11로 확정했습니다.
 
 권장 구조는 다음과 같습니다. 실제 폴더명은 stack 관습에 맞춰도 역할은 유지합니다.
 
@@ -240,3 +232,18 @@ package로 승격하지 않습니다.
 ## 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.
+
+
+## 상호작용 채택과 성능 기록
+
+2026-10-02 사용자가 참고 인터랙션 수준의 제품 품질을 요청한 데 따른 구체 적용 기준이다.
+기존 상태 피드백·접근성 책임을 제품의 입력 → 반응 → 확정 → 복구 흐름까지 연결한다.
+
+- 제품은 설치된 HJM 버전의 API와 Storybook 배포/실험 상태를 확인하고 해당 범위에서 재사용한다.
+  새 동작이 필요한 경우 기존 Button·Sheet·Toast를 합성하며 같은 상태를 두 계층에서 관리하지 않는다.
+- 성공은 서버 또는 제품의 실제 확정 뒤에 표시한다. 연속 입력·실패·역순 응답·중간 이탈에서도
+  초안과 복구 경로를 보존한다. 웹·앱 입력 방식이 달라도 같은 사용자 의도를 유지한다.
+- 성능에 영향을 주는 제스처·전환·대량 렌더링 변경은 제품 조건의 변경 전후를 측정한다.
+  기기·OS·빌드·데이터·측정 방법과 미검증 범위를 기록하고 데모의 성공을 실기기 성능으로 쓰지 않는다.
+- 구체 예제·목표·기록 양식은 [상호작용 적용·품질 기준](../../../docs/INTERACTION_QUALITY.md)을 따른다.
+  이 소스 문서의 변경이 아직 게시되지 않은 API를 소비 앱에 설치하거나 자동 적용하지는 않는다.