@hjmds/design-contracts 1.29.0 → 1.31.0

package/docs/usage/components/chat-date-separator.md

@@ -0,0 +1,86 @@
+# ChatDateSeparator
+
+- 단계: 컴포넌트
+- 상태: 실험
+- 지원: Web · Native
+- 적용: 미게시(1.30.0 이후)
+- 검토일: 2026-10-18
+- 근거: [반복 화면 조합](../../screen-patterns.md), `src/screen-patterns.ts`의 `chatDateSeparatorRecipe`; Web·Native `src/screens.tsx`
+- 스토리북: `실험/컴포넌트/데이터 표시/대화 날짜 구분`
+
+## 언제 쓰나
+
+대화 타임라인에서 날짜(또는 오래 쉰 뒤의 시각)가 바뀌는 자리에 가운데 정렬 구분 줄을 둘 때 쓴다. 문구 포맷("오늘", "10월 18일 토요일", "오후 3:04")과
+구분을 넣을 위치(날짜 변경·간격 기준)는 제품이 정하고, HJM은 줄의 배치·글자·간격을 맡는다.
+
+## 쓰지 않을 때
+
+| 상황 | 대신 쓸 것 |
+| --- | --- |
+| 일반 목록의 구획 제목 | [Section](section.md), [List](list.md) 묶음 제목 |
+| 선만 필요한 구분 | [Divider](divider.md) |
+| 메시지마다 붙는 시각 | [ChatMessage](chat-message.md) `timestamp` |
+
+## 공개 이름과 import
+
+| 이름 | 역할 | Web | Native |
+| --- | --- | --- | --- |
+| `ChatDateSeparator` | 기본 | `@hjmds/react/screens` | `@hjmds/react-native/screens` |
+
+루트 barrel에는 없다.
+
+## 최소 사용 예
+
+```tsx
+// Web
+import { ChatDateSeparator, ChatMessage } from "@hjmds/react/screens";
+
+{rows.map(row => <Fragment key={row.message.id}>
+  {row.dayChanged ? <ChatDateSeparator label={formatDay(row.message.sentAt)} dateTime={row.message.sentAt.slice(0, 10)} /> : null}
+  <ChatMessage {...toMessageProps(row.message)}>{row.message.text}</ChatMessage>
+</Fragment>)}
+```
+
+```tsx
+// Native
+import { ChatDateSeparator, ChatMessage } from "@hjmds/react-native/screens";
+
+const renderItem = ({ item }: { item: Row }) => <>
+  {item.dayChanged ? <ChatDateSeparator label={formatDay(item.message.sentAt)} /> : null}
+  <ChatMessage {...toMessageProps(item.message)}><Text>{item.message.text}</Text></ChatMessage>
+</>;
+```
+
+## 축과 기본값
+
+| prop | 값 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `label` | `string` | 필수 | 제품이 포맷한 날짜·시각. 빈 문자열은 `TypeError` |
+| `dateTime` | `string` | 없음 | Web `<time dateTime>` 값(예: `2026-10-18`). Native는 쓰지 않는다 |
+| `layoutStyle` | `HjmCompositionStyleProp` | 없음 | 행 배치 전용. 색·여백을 덮지 않는다 |
+
+## 배치
+
+| 항목 | 값 | 근거 |
+| --- | --- | --- |
+| 크기 | 타임라인 폭 전체 행, 글자 `textVariant` caption · `tone` muted | `chatDateSeparatorRecipe` |
+| 간격 | 위 `paddingTop`(`spacing.sm`) 12, 아래 `paddingBottom`(`spacing.xxs`) 4. 다음 메시지는 자기 `groupPosition` 위 여백(새 묶음 12)을 그대로 가진다 | `chatDateSeparatorRecipe`, `resolveChatMessageGroupDisplay` |
+| 순서·정렬 | 구분할 메시지 바로 앞, 가로 가운데 | Web·Native `ChatDateSeparator` |
+| 고정·스크롤 | 자체 고정 없음. 타임라인과 함께 스크롤한다 | — |
+| 좁은 폭·큰 글자 | 글자는 줄바꿈되고 자르지 않는다 | Web·Native `ChatDateSeparator` |
+
+## 꼭 지킬 것
+
+- 구분 줄 뒤의 메시지는 새 묶음으로 시작한다(`resolveChatMessageGroups`가 같은 시각 문자열이면 묶으므로, 날짜가 바뀌면 제품이 묶음을 끊는다).
+- 문구는 제품이 지역화·포맷한다. HJM은 날짜를 해석하지 않는다.
+- 읽기 순서상 메시지 사이 일반 글자로 읽힌다. 따로 live region이나 heading 역할을 주지 않는다.
+
+## 플랫폼 차이
+
+| 항목 | Web | Native |
+| --- | --- | --- |
+| 시각 의미 | `dateTime`이 있으면 `<time>` | 글자만 |
+
+## 근거
+
+- 공통 날짜 구분: 2026-10-18 유틸버스 채팅. ChatScreen에 시각 구분 줄이 없어 가운데 흐린 caption을 제품이 직접 그렸다(위 12·아래 8 여백). 아래 여백은 다음 메시지의 묶음 여백 12와 겹치지 않도록 4로 정했다.

package/docs/usage/components/chat-message.md

@@ -85,8 +85,11 @@ import { Text } from "@hjmds/react-native/primitives";
 | `replyQuote` | `{ title, excerpt }` | 없음 | 미게시. 말풍선 맨 위에 HJM이 인용을 그린다: 제목(예: "서연에게 답장", 본문 글자) → 원문 한 줄(흐린 글자, 넘치면 말줄임) → 구분선 1 → 답장 본문. 자유 노드 `reply`보다 우선 사용한다 |
 | `replyLink` | `{ label, onPress() }` | 없음 | 인용과 같이 주면 말풍선 안 인용을 눌러 원문으로 이동한다(Native는 말풍선의 "원문으로 이동" 접근성 동작도 제공). 이전에는 버블 밖 ghost 버튼이었다 |
 | `media` | `{ id, label, preview, aspectRatio?, onPress? }[]` | 없음 | 미게시. 보낸 사진. 폭 `chatMessageRecipe.mediaWidth` 210, 한 장은 `aspectRatio`(기본 1), 여러 장은 정사각 칸(`resolveChatMediaColumns`: 2·4장 2열, 그 외 3열, 간격 2), 바깥 radius 14. 글 없이 사진만 보내면 말풍선 표면·꼬리를 그리지 않는다. `onPress`가 있으면 사진마다 버튼(크게 보기는 제품) |
+| `mediaAlbum` | `{ count, renderPage(index), pageLabel(index, count), previousLabel, nextLabel, aspectRatio?, onPress?(index), index?·onIndexChange?·defaultIndex? }` | 없음 | 미게시. 한 장씩 넘기는 사진 묶음. `renderPage`는 화면에 보이는 장에만 호출되어 제품이 그 사진만 조회·디코딩한다(이미지 원본·권한·캐시는 제품). 폭 `mediaWidth` 210, 사진 칸 `aspectRatio`(기본 1)·radius 14, 그 아래 이전 아이콘 · 위치(예: 2/5) · 다음 아이콘 줄(작은 ghost IconButton, `mediaAlbumRecipe`). 글 없이 앨범만 보내면 `media`처럼 말풍선 표면·꼬리를 그리지 않는다. 넘김 버튼이 있어 말풍선은 `interactiveContent`로 다뤄진다. 넘긴 장은 길게 누르기 미리보기에서도 같다. `media`와 함께 주면 `TypeError` |
 | `replyAction` | `{ label, onPress(), disabled?, icon? }` | 없음 | `replySwipeDistance` 60px 이상이고 세로 이동의 2배를 넘는 가로 스와이프로 실행(`isReplySwipe`). `reactions`가 있으면 길게 누른 메뉴의 첫 항목으로도 보인다(미게시) |
 | `reactions` | `ReactionPickerProps & { closeLabel, menuActions?, reportAction?, menuAction? }` | 없음 | `reactionHoldMs` 450ms 길게 누르면 메뉴가 열린다: 반응 줄(이모지 `typography.title` 18/26, `more`면 +) → 메시지 미리보기 → 카드(맨 위 `timestamp` 정확한 시각 → `replyAction` → `menuActions` → `menuAction` → `reportAction` 빨간 글자). 항목은 높이 44, 아이콘 24 칸. 배치는 `holdMenuRecipe`(인스타그램 DM 실측): 화면 좌우 10 안쪽 전체 폭 반응 줄(높이 60, 48 원형 칸, 이모지 28, 넘칠 때만 가로 스크롤) → 12 → 누른 말풍선 그대로 미리보기(제 쪽 정렬) → 12 → 폭 200·radius 18 동작 카드(행 56, 아이콘 24, `submenu` 행은 ›)를 말풍선 쪽에 붙인다. 보이는 ×는 없고 배경 탭·Escape·VoiceOver 닫기로 닫는다(보조기술 첫 초점용 닫기 대상만 둔다). 같은 반응 재선택은 `null`. `label`은 Web에서 말풍선 이름·Popover 제목, Native에서 접근성 힌트·동작 이름. 시각·동작 카드와 `reportAction`·`menuActions`는 미게시(2026-10-16 인스타그램 DM 길게 누르기 실측 반영) |
+| `reactions.menuActions[].tone` | `"neutral"` · `"danger"` | `"neutral"` | 미게시(1.30.0 이후). 길게 누른 메뉴 행의 색. 삭제처럼 되돌릴 수 없는 행은 `danger`(빨간 글자). [Menu](menu.md) 항목 `tone`과 같은 어휘(`MenuItemTone`). `reportAction`은 항상 `danger`이고 맨 끝이다. 댓글(CommentThreadRow) 메뉴도 같다 |
+| `reactions.summary` | `{ label, items: { id, emoji, count }[] }` | 없음 | 미게시. 현재 반응 집계를 시각 옆 알약 버튼 하나로 그리고, 누르면 길게 누른 것과 같은 메뉴를 연다. `label`은 버튼의 지역화 접근성 이름(예: "반응 ❤️ 2개, 😂 1개. 반응 메뉴 열기"), `items`는 표시 순서. `count`가 `chatMessageRecipe.reactionSummary.minCount` 2 미만이면 이모지만 보인다. 내 반응(`value`)이 들어 있으면 brand 테두리. 높이 24(Native는 hitSlop으로 44 터치), 좌우 8, 항목 사이 4. 빈 `label`·중복 id·빈 이모지는 `TypeError`, 양의 정수가 아닌 count는 `RangeError`(`resolveChatReactionSummary`). `reactions.disabled`면 버튼도 비활성. 메뉴가 닫히면 Web 초점은 말풍선으로 돌아간다 |
 | `interactiveContent` | `boolean` | `false` | 사진 앨범·링크처럼 자식이 버튼을 가지면 `true`. 안쪽 버튼·링크의 누름과 Web Enter/Space는 그 컨트롤이 받는다 |
 | `actions` | `ReactNode` | 없음 | 시각 옆 슬롯. 반응 집계 배지·재시도는 제품이 넣는다 |
 | `children` | `ReactNode` | 필수 | 메시지 본문. Native는 말풍선이 이 텍스트로 읽힌다 |
@@ -111,7 +114,8 @@ import { Text } from "@hjmds/react-native/primitives";
   답장·반응은 접근성 동작(`reply`·`activate`)으로 남는다. 2026-10-06 리뷰에서 행 이름(`author`)과 반응 이름(`picker.label`)이
   본문을 가려 화면 낭독기가 메시지를 읽지 못했다.
 - 타임라인 전체를 live region으로 감싸지 않는다(과거 메시지 로딩 때 읽기 순서를 가로챈다).
-- 반응 **선택 메뉴**와 현재 반응 **집계 버튼**은 다른 행동이다. 집계를 눌러 메시지 메뉴를 열 때는
+- 반응 **선택 메뉴**와 현재 반응 **집계 버튼**은 다른 행동이다. 집계를 눌러 같은 메뉴를 열 때는
+  `reactions.summary`를 쓴다(미게시). 집계를 상태 표시용 Tag로 `actions`에 직접 그리지 않는다. 다른 행동(예: 반응한 사람 목록)을 여는 버튼은
   `actions` 슬롯에 Button을 공급할 수 있다. 본문 안에 집계 버튼을 넣는다면 사진·링크가 없어도
   `interactiveContent=true`가 필요하다. 2026-10-07 Utilverse 소스 대조에서 사진/도구만 검사해
   집계 버튼이 부모 접근성 그룹에 들어갈 수 있는 경로를 발견했다. `actions`에 둘 때도 긴 집계와
@@ -129,6 +133,8 @@ import { Text } from "@hjmds/react-native/primitives";
 
 ## 함정
 
+- 사진이 여러 장이고 장마다 권한 확인·조회가 필요하면 `media`에 모든 `preview`를 넘기지 말고 `mediaAlbum`을 쓴다. `media`의 미리보기는 한 번에 모두 마운트된다(2026-10-18 Utilverse 소셜 사진: 대화 행마다 원본 10장을 받지 않으려고 제품 앨범을 따로 만들었다).
+
 - Native는 반응 모달 안에서 `children`을 미리보기로 한 번 더 렌더한다. 자식은 표시용 콘텐츠로 준다
   (부작용·고유 ref를 두지 않는다).
 - `reactions`의 `options`와 `more.options`는 id가 합쳐서 유일하고 emoji·label이 비어 있지 않아야 한다. `value`가
@@ -147,4 +153,7 @@ import { Text } from "@hjmds/react-native/primitives";
 
 ## 근거
 
+- `reactions.summary`: 2026-10-18 번뚝 DM. 메뉴를 밖에서 열 수 없어 집계를 상태용 Tag로만 `actions`에 그렸다(제품 docs/DESIGN.md에 격차로 기록). 제어형 `open` 대신 HJM이 집계 버튼까지 그려 위치·접근성 이름·메뉴 연결을 공통으로 맡는다.
+- `menuActions[].tone`: 2026-10-18 유틸버스 채팅 길게 누르기 메뉴의 삭제 행. 빨간 글자가 `reportAction`에만 있어 삭제가 일반 행으로 보였다.
+
 - 아바타 32: 2026-10-17 정렬 실측. recipe·문서는 36이었지만 Web Avatar 단계(32/40/48/64)에 36이 없어 Web은 36 칸에 32 아바타를, Native는 36 아바타를 그렸다. 카카오톡 참고값 약 34에 가장 가까운 Avatar 단계 `small` 32를 recipe가 직접 읽게 해 두 플랫폼이 같은 값을 쓴다. 작성자 첫 줄과의 위쪽 맞춤(카카오톡 방식)은 유지한다.

package/docs/usage/components/chat-screen.md

@@ -29,6 +29,7 @@ DM·대화방처럼 헤더, 메시지 타임라인, 하단 작성창으로 이
 | --- | --- | --- | --- |
 | `ChatScreen` | 화면 조합 | `/screens` | `/screens` |
 | `ChatMessage`, `MessageComposer`, `ScreenLayout` | 함께 쓰는 조각 | `/screens` | `/screens` |
+| [`TypingIndicator`](typing-indicator.md), [`ChatDateSeparator`](chat-date-separator.md) | 타임라인 조각(입력 중 표시, 날짜 구분). 미게시(1.30.0 이후) | `/screens` | `/screens` |
 
 루트 barrel에는 없다. `/screens`는 optional native peer를 요구하지 않는다.
 
@@ -68,11 +69,11 @@ import { ChatScreen, MessageComposer } from "@hjmds/react-native/screens";
 | --- | --- | --- |
 | `title`(필수) | 지역화한 대화 제목 | `header`를 주면 Web은 `aria-label`로만 쓴다 |
 | `header` / `exit` / `actions` / `description` | 기존 navigation 헤더, 또는 헤더 시작 쪽 화면 나가기 아이콘(`exit`: 뒤로·닫기)·도구 슬롯 | `header`를 주면 기본 헤더를 그리지 않는다 |
-| `children` | 타임라인(가상화 목록 + `ChatMessage`) | 자동 스크롤·새 메시지 배지·이전 메시지 위치는 제품 |
+| `children` | 타임라인(가상화 목록 + `ChatMessage`) | 자동 스크롤·새 메시지 배지·이전 메시지 위치는 제품. 날짜·시각이 바뀌는 자리에는 `ChatDateSeparator`, 상대가 입력 중이면 마지막 메시지 뒤에 `TypingIndicator`를 둔다. 둘을 제품 caption·점 표시로 만들지 않는다 |
 | `composer`(필수) | `MessageComposer` 등 작성창 | `ready`와 `empty`에서 보인다(빈 대화의 첫 메시지 입력) |
 | `state` / `stateAction` | `loading`·`empty`·`error`·`restricted` + 지역화 `title` | ready 외에는 본문을 교체한다 |
 | `notice` | 새로고침 실패 같은 비차단 안내 | 초안 유지가 필요하면 `state` 대신 이것 |
-| `avatar` | 상대·방 사진 노드 | 미게시. 가운데 정렬 제목 앞에 놓는다. 단톡방은 인원 수를 `titleBadge`(흐린 글자)로 넘긴다 |
+| `avatar` | 상대·방 사진 노드 | 미게시. 가운데 정렬 제목 앞에 놓는다. 단톡방은 인원 수를 `titleBadge`(흐린 글자)로 넘긴다. ScreenLayout `titleLeading`과 같은 자리라 ChatScreen은 `titleLeading`을 따로 받지 않는다. 장식이라 보조기술에서 숨는다(제목이 이름) |
 | `jumpToLatest` | `{ label, icon, onPress() }` | 미게시. 독자가 최신 메시지에서 벗어났을 때만 넘긴다. 작성창 위 끝 쪽에 원형 `IconButton size="small"`(secondary)로 떠 있고, 스크롤 위치 판단은 제품이 한다 |
 
 ## 축과 기본값

package/docs/usage/components/comment-thread-row.md

@@ -64,6 +64,9 @@ import { CommentThreadRow } from "@hjmds/react-native/screen-flows";
 | --- | --- | --- |
 | `id`·`parentId`·`author`·`body`·`timeLabel`·`likeCountLabel`·`likeIcon`·`likeLabel` | 필수 | `parentId`가 `null`이면 최상위 댓글 |
 | `bodyText` | 없음 | 주면 `author`와 본문을 한 문장으로, 시각은 아래 행동 줄로 옮긴다 |
+| `timePlacement` | `"auto"` | 미게시. `"auto"`는 `bodyText`가 없으면 시각을 작성자 옆에 둔다. `"actions"`는 글이 아닌 본문(꽃 도장·카드)에서도 시각을 본문 아래 반응 요약·답글과 같은 줄 맨 앞으로 옮긴다 |
+| `panel` | 없음 | 미게시. 댓글별 인라인 패널(수정·신고·차단 양식). 답글 줄 아래, 길게 누르기 대상 밖에 `panelGap` 8 간격으로 놓인다. 열림 상태·초점·제출·닫기는 제품이 소유한다 |
+| `mediaAlbum` | 없음 | 미게시. 한 장씩 넘기는 사진 묶음 `{ count, renderPage(index), pageLabel(index, count), previousLabel, nextLabel, aspectRatio?, onPress?(index), index?·onIndexChange?·defaultIndex? }`. `renderPage`는 화면에 보이는 장에만 호출되어 제품이 그 사진만 조회·디코딩한다. `media`와 함께 주면 `TypeError`. 본문 아래, 길게 누르기 대상 밖에 놓인다 |
 | `avatar` | 없음 | 제품 아바타. 최상위 32·답글 24 폭 칸에 둔다 |
 | `canReply` | `parentId === null` | 답글 행동 표시 여부 |
 | `replyDisabled` | false | 답글 행동 비활성 |
@@ -75,9 +78,9 @@ import { CommentThreadRow } from "@hjmds/react-native/screen-flows";
 
 | 항목 | 값 | 근거 |
 | --- | --- | --- |
-| 크기 | 아바타 칸 최상위 32·답글 24, 좋아요 수 칸 폭 44, `media` 최대 폭 160·radius `radius.md` | `commentThreadRecipe` |
+| 크기 | 아바타 칸 최상위 32·답글 24, 좋아요 수 칸 폭 44, `media`·`mediaAlbum` 최대 폭 160·radius `radius.md`(앨범은 사진 칸에만 radius, 그 아래 이전 아이콘 · 위치(예: 2/5) · 다음 아이콘 줄, 작은 ghost IconButton) | `commentThreadRecipe`, `mediaAlbumRecipe` |
 | 간격 | 아바타·본문·좋아요 열 사이 `spacing.xs` 8, 본문 줄 사이 2, 행동 줄 항목 사이 `spacing.sm` 12, 작성자–시각 `spacing.xxs` 4, `media` 위 4 | `commentThreadRecipe.lineGap`, `Stack gap` |
-| 순서·정렬 | 아바타 → (작성자·시각 → 본문 → media → 시각/반응 요약/답글 행동) → 좋아요 버튼·`actions` 아래 좋아요 수. 위 정렬 단, 오른쪽 좋아요·`actions`·더보기 열은 44 터치 영역을 첫 줄(작성자 caption, `bodyText`면 본문 줄)의 가운데에 맞춘다: 열을 (첫 줄 높이 − 44) / 2만큼 올린다(`commentThreadRecipe.actionAnchor`). HJM의 좋아요·더보기가 마지막이면 열 전체가 IconButton 가장자리 오버행(10)만큼 끝으로 나가 아이콘 칸이 행 끝 여백 선(아바타 시작과 같은 선)에 온다. 제품 `actions`가 마지막이면 그 버튼에 `edge="end"`를 준다. 측정 전후(Web 402): 아바타 168 / 작성자 줄 162 / 아이콘 174 → 아이콘 160 = 작성자 줄, 더보기 칸 끝 28 → 16(2026-10-17 실측 감사, [IconButton `edge`](icon-button.md#배치)) | 양 renderer |
+| 순서·정렬 | 아바타 → (작성자·시각 → 본문 → media 또는 mediaAlbum → 시각/반응 요약/답글 행동 → panel) → 좋아요 버튼·`actions` 아래 좋아요 수. 위 정렬 단, 오른쪽 좋아요·`actions`·더보기 열은 44 터치 영역을 첫 줄(작성자 caption, `bodyText`면 본문 줄)의 가운데에 맞춘다: 열을 (첫 줄 높이 − 44) / 2만큼 올린다(`commentThreadRecipe.actionAnchor`). HJM의 좋아요·더보기가 마지막이면 열 전체가 IconButton 가장자리 오버행(10)만큼 끝으로 나가 아이콘 칸이 행 끝 여백 선(아바타 시작과 같은 선)에 온다. 제품 `actions`가 마지막이면 그 버튼에 `edge="end"`를 준다. 측정 전후(Web 402): 아바타 168 / 작성자 줄 162 / 아이콘 174 → 아이콘 160 = 작성자 줄, 더보기 칸 끝 28 → 16(2026-10-17 실측 감사, [IconButton `edge`](icon-button.md#배치)) | 양 renderer |
 | 고정·스크롤 | 행은 스크롤하지 않는다. 목록 스크롤·행 간격(`rowGap` 12)·답글 들여쓰기(`replyIndent` 40)는 host가 준다 | `CommentThreadScreen` |
 | 좁은 폭·큰 글자 | 본문 열이 `min-width: 0`으로 줄며 줄바꿈되고 작성자·행동 줄은 `flexWrap`. 좋아요 열은 줄지 않는다 | `.hjm-comment-row__text`, `flexShrink: 0` |
 
@@ -85,7 +88,8 @@ import { CommentThreadRow } from "@hjmds/react-native/screen-flows";
 
 - 가상화 host에서 행 사이 간격(`commentThreadRecipe.rowGap`)과 답글 들여쓰기(`replyIndent`)를 직접 줄 때도 recipe 값을 쓴다. 제품 숫자로 다시 정하지 않는다.
 - 답글 펼치기·정렬·권한·좋아요 저장은 제품이 소유한다. 행은 콜백만 호출한다.
-- 행 안에 두 번째 레이아웃을 만들지 말고 `actions`·`likeAction`·`media` 슬롯으로 추가한다.
+- 행 안에 두 번째 레이아웃을 만들지 말고 `actions`·`likeAction`·`media`·`mediaAlbum`·`panel` 슬롯으로 추가한다. 시각·답글 줄을 본문 노드 안에 다시 그리지 말고 `timePlacement: "actions"`와 `canReply`를 쓴다.
+- `mediaAlbum`의 사진 조회·권한 확인·캐시 수명은 제품이 `renderPage` 안에서 소유한다. HJM은 보이는 장만 마운트하고 넘김 상태를 행 안에 둔다(제어형은 `index`+`onIndexChange`).
 
 ## 상태와 상호작용
 
@@ -93,6 +97,10 @@ import { CommentThreadRow } from "@hjmds/react-native/screen-flows";
 `reactions`를 주면 작성자·본문만 길게 누르기 대상이 되고, 답글 가능하면 메뉴에 답글 항목이 자동으로 붙는다.
 답글 행동 버튼은 길게 누르기 대상 밖에 남아 자기 버튼 의미를 유지한다.
 
+## 근거
+
+- `timePlacement`·`panel`·`mediaAlbum`: 2026-10-18 HJM 1.30.0 채택 감사. Spint는 꽃 도장 본문에서 시각을 답글 줄에 두려고 시각·답글 행을 본문 안에 다시 그렸고, Utilverse는 수정·신고·차단 양식을 본문 노드 안(길게 누르기 대상 안)에 넣었으며, 사진 묶음은 선택한 장만 조회하는 제품 앨범을 따로 만들었다.
+
 ## 플랫폼 차이
 
 | 항목 | Web | Native |

package/docs/usage/components/comment-thread-screen.md

@@ -93,7 +93,7 @@ import { MessageComposer } from "@hjmds/react-native/screens";
 `likeIcon`, `likeLabel`은 필수. 선택은 `bodyText`(작성자와 본문을 한 줄 흐름으로), `avatar`, `likeAction`(기본
 좋아요 버튼 교체, `null`이면 생략), `actions`(하트 바로 옆의 더보기 메뉴 등), `canReply`(기본: 최상위만 true), `replyDisabled`.
 `reactions`(미게시)를 주면 작성자·본문을 길게 눌러 ChatMessage와 같은 메뉴(반응 줄 → 미리보기 → 시각 → 답글 달기 → `menuActions` → `reportAction` 신고)가 열린다. 답글 달기는 `canReply`일 때 `onReply`로 자동 연결되고, 아이콘은 `reactions.replyIcon`으로 넘긴다. `reactionSummary`는 답글 달기 앞에 놓는 선택된 반응 표시 슬롯이다. 댓글의 기본은 반응 옵션을 비운(`options: []`) 동작 목록 전용 메뉴다(답글 달기 → `menuActions` → 신고, 인스타그램 댓글 길게 누르기 실측). 댓글 이모지는 길게 누르기가 아니라 작성창의 `quickInserts` 이모지 줄로 입력한다. 반응 줄은 제품이 명시적으로 댓글 반응을 운영할 때만 옵션을 넣는다. 댓글 메뉴에는 시각 제목을 두지 않는다(행에 이미 보인다).
-`media`(미게시, 선택)는 본문 아래 사진·스티커이며 최대 폭 `commentThreadRecipe.mediaMaxWidth` 160, radius 12로 감싼다. `likeCountLabel`은 하트 아래 숫자만(예: "15") 넣고 0이면 빈 문자열로 숨긴다. 개수를 포함한 전체 문장은 `likeLabel`에 둔다.
+`media`(미게시, 선택)는 본문 아래 사진·스티커이며 최대 폭 `commentThreadRecipe.mediaMaxWidth` 160, radius 12로 감싼다. 사진 여러 장을 한 장씩 불러와야 하면 `media` 대신 `mediaAlbum`, 시각을 답글 줄로 옮기려면 `timePlacement: "actions"`, 수정·신고·차단 양식은 `panel`을 쓴다(미게시, [CommentThreadRow](comment-thread-row.md#축과-기본값)). `likeCountLabel`은 하트 아래 숫자만(예: "15") 넣고 0이면 빈 문자열로 숨긴다. 개수를 포함한 전체 문장은 `likeLabel`에 둔다.
 
 ## 배치
 

package/docs/usage/components/dialog.md

@@ -38,6 +38,7 @@
 | --- | --- | --- | --- |
 | `Dialog` | 기본 | `@hjmds/react`, `/overlays` | `@hjmds/react-native`, `/overlays` |
 | `OverlayStackProvider` | 확장 — 명령형 열기(`useDialog`·`useSheet`·`useOverlayStack`) | `@hjmds/react`, `/overlay-stack` | 없음 |
+| `ImmersiveOverlay` | 확장 — 카드·scrim·머리 없이 화면 전체를 채우는 표현(1.31.0). 아래 [전체 화면 표현](#전체-화면-표현-immersiveoverlay) | `@hjmds/react`, `/overlays` | `@hjmds/react-native`, `/overlays` |
 
 ## 최소 사용 예
 
@@ -127,6 +128,8 @@ await handle.closed; // portal 제거·초점 복구 뒤. 다음 오버레이는
 | `onActionError`(Native) | `(error: unknown) => void` | — | action 실패를 본문 오류·재시도로 연결한다. 오류를 처리하는 동안 초안을 보존한다. 없으면 개발 빌드에서 실패마다 `console.error`를 남긴다(중복 제거 없음). 1.13.0 변경 |
 | `children`(Native) | `ReactNode` | — | 고정된 제목 줄 아래 스크롤 본문(`ScrollView`) 안에 들어간다. `FlatList`·`SectionList`를 넣지 않는다 |
 | `contentStyle`(Native) | 배치 key만(`HjmCompositionStyleProp`) | — | 대화상자 상자의 배치. 높이는 `size`로 |
+| `overlayLayer` | `ReactNode` | 없음 | 1.31.0. 카드 **밖** 화면 전체 층에 그리는 장식(끌기 미리보기·특정 위치 강조). 카드보다 위에 그려지고 Web viewport/Native window 좌표(`clientX`·`pageX`·`measureInWindow`)를 그대로 쓴다. 누름을 받지 않고 보조기술에서 숨긴다(Web `inert`·`aria-hidden`, Native `pointerEvents="none"`·`no-hide-descendants`). 조작할 내용은 `children`에 둔다 |
+| `scrollEnabled` | `boolean` | `true` | 1.31.0. `false`면 사용자가 대화상자를 스크롤하지 못한다(현재 위치 유지). Web은 카드 `overflow: hidden`, Native는 본문 ScrollView `scrollEnabled`. 본문 안 끌기 제스처가 진행되는 동안만 끄고 끝나면 되돌린다. 내용을 자르는 용도로 쓰지 않는다 |
 | `useDialog()`(Web) | `(request) => { closed: Promise<void>, close(): void }` | — | request는 `open`·`defaultOpen`·`onOpenChange`·`trigger`를 뺀 DialogProps. `OverlayStackProvider` 안에서만 |
 
 - Dialog는 `layoutStyle`을 받지 않는다(Web 제외 15개 중 하나 — 포털로 가운데 그려져 배치할 흐름 안 루트가 없다).
@@ -178,6 +181,66 @@ Native, 큰 글자 또는 폭 < 480:   [      취소      ]
 - Native에서 저장처럼 실패할 수 있는 action은 `onActionError`를 넘긴다. 단발성 작업에 Promise를 반환하면 완료까지 닫히지 않으므로, 즉시 닫으려면 아무것도 반환하지 않는다.
 - 배치 변경은 Native `contentStyle`(layout 전용)만 쓴다. 높이는 `size`로 정한다. Web은 `className`만 받으며 시각 override에 쓰지 않는다.
 
+### 카드 밖 레이어 (`overlayLayer`)
+
+폴더 안 아이콘을 끌 때처럼 손가락·포인터를 따라가는 미리보기는 카드 안에 그리면 카드의 안쪽 여백·스크롤·잘림·열림
+변형 때문에 좌표가 어긋나고 카드에 갇힌다. `overlayLayer`는 카드와 같은 모달 안이지만 카드의 형제 층이라 이 문제가 없다.
+끌기 제스처와 드롭 대상 측정은 카드 안 `children`이 소유하고, 층에는 현재 좌표의 그림만 넘긴다.
+Native 입력 본문의 키보드 회피는 Dialog가 이미 맡는다(위 키보드 설명). 제품이 `KeyboardAvoidingView`를 다시 감싸지 않는다.
+끌기 중에는 `scrollEnabled={!dragging}`으로 본문 스크롤을 잠근다. 잠그지 않으면 Native ScrollView가 세로 움직임을 가져가 끌기가 끊기고, Web은 카드가 함께 스크롤된다.
+
+```tsx
+// Native
+<Dialog open={open} onOpenChange={setOpen} title={folder.name} closeLabel={t("common.close")}
+  scrollEnabled={drag === null}
+  overlayLayer={drag ? <DragGhost x={drag.pageX} y={drag.pageY} item={drag.item} /> : null}>
+  {grid /* 끌기 responder와 measureInWindow 등록은 여기 */}
+</Dialog>
+```
+
+<!-- usage-example: Web ../../../../../showcase/web/src/components/dialog-overlay-examples.tsx -->
+- [Web 실행 예제](https://github.com/jim1286/hjm-design-system/blob/8afe62bcf44b4ced063998bc9669b55704265f2d/showcase/web/src/components/dialog-overlay-examples.tsx): `DialogOverlayLayerPreview`·`ImmersiveOverlayPreview`(`배포/컴포넌트/오버레이/대화상자`의 카드 밖 레이어·전체 화면 표현).
+<!-- usage-example: Native ../../../../../showcase/native/src/dialog-overlay-preview.tsx -->
+- [Native 실행 예제](https://github.com/jim1286/hjm-design-system/blob/8afe62bcf44b4ced063998bc9669b55704265f2d/showcase/native/src/dialog-overlay-preview.tsx): 같은 이름의 Native preview.
+
+### 전체 화면 표현 (`ImmersiveOverlay`)
+
+전광판·발표 화면처럼 **화면 자체가 내용**인 표현에 쓴다. 카드·scrim·머리·안쪽 여백이 없고, 제품이 그린 무대가 화면 끝까지
+채운다. 아래에는 HJM 행동 줄(상태 문구 → 도구 행동 → 나가기 행동)이 safe area 안에 붙는다. 모달 스택·포커스 가두기·
+배경 격리·닫힌 뒤 포커스 복귀·아래 화면의 진입 포커스 대기는 Dialog와 같다.
+
+| prop | 값 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `open`·`onOpenChange` | `boolean`, `(open, { reason }) => void` | — | 제어형만. Web `reason`: `"exit-action"`·`"escape"`. Native: `"exit-action"`·`"back"` |
+| `label` | 현지화 문자열 | — | 표현 전체의 접근성 이름 |
+| `exitLabel` | 현지화 문자열 | — | 나가기 버튼에 보이는 문구(제품 문구) |
+| `children` | `ReactNode` | — | 무대. 남은 높이 전체를 채우고 넘치는 부분은 잘린다 |
+| `tools` | `ReactNode` | 없음 | 나가기 앞에 놓는 도구 행동(멈춤 등 `IconButton`) |
+| `status` | `ReactNode` | 없음 | 행동 줄 위 상태 문구·`Notice` |
+| `returnFocusRef` | ref | 없음 | 닫힌 뒤 돌아갈 대상 |
+| `initialFocusRef`(Web) | ref | 나가기 버튼 | 열릴 때 포커스 |
+| `modalPriority`·`portalContainer`·`className`(Web) | — | — | Dialog와 같다 |
+| `onShow`(Native) | RN `Modal` `onShow` | — | 표시 완료 |
+
+- Native는 `presentationStyle="fullScreen"` Modal에서 상태 표시줄을 숨기고 세로·가로 회전을 허용한다(`dialogRecipe.immersive.orientations`, 앱이 세로 고정이어도 이 표현은 회전한다). 무대는 화면 끝까지 그려지므로 읽어야 할 내용은 가운데 두거나 `useHjmNativeSafeAreaInsets`로 가장자리 절개를 피한다.
+- Web은 viewport 전체를 덮는 고정 층이다. 브라우저 Fullscreen API는 요청하지 않는다. 새 사용자 활성화가 필요하고, 그 Escape는 페이지가 받기 전에 전체 화면만 끝내 오버레이가 창 안에 남으며, iOS Safari는 요소 전체 화면을 지원하지 않는다.
+- 행동 줄 간격: 안쪽 `spacing.md` 16(아래·좌우는 safe area와 큰 값), 상태–행동 `spacing.xs` 8, 행동 사이 `spacing.sm` 12. 나가기 버튼은 `size="large"`로 남은 폭을 채운다.
+- 화면 꺼짐 방지·움직임 같은 무대 동작은 제품 소유다.
+
+```tsx
+// Native
+import { ImmersiveOverlay } from "@hjmds/react-native/overlays";
+
+<ImmersiveOverlay open={presenting} onOpenChange={(next) => { if (!next) setPresenting(false); }}
+  label={t("display.title")} exitLabel={t("displayClose")}
+  status={<Text variant="caption" tone="muted">{t("displayWakeActive")}</Text>}
+  tools={<IconButton tone="secondary" size="large" label={t("displayPause")} onPress={togglePause}><PauseGlyph /></IconButton>}>
+  {sign /* 제품이 그린 전광판 */}
+</ImmersiveOverlay>
+```
+
+실행 예제: 위 같은 파일의 `ImmersiveOverlayPreview`(`배포/컴포넌트/오버레이/대화상자` 전체 화면 표현).
+
 ## 플랫폼 차이
 
 | 항목 | Web | Native |
@@ -255,3 +318,9 @@ function RecordDetail() {
 실제 View의 `measureInWindow`로 활성화 시점의 영역을 얻고, 좌표를 얻지 못해도 일반 Dialog를 연다.
 측정 callback만 무기한 기다리면서 열기 행동을 막지 않는다. 버튼의 접근성 이름과 초점 복귀 대상을
 유지하고, 카드 전체를 누름 가능한 비의미적 View/div로 바꾸지 않는다.
+
+## 근거
+
+- `overlayLayer`: 2026-10-18 번뚝 폴더 팝업. 끌기 유령 아이콘을 창 좌표로 카드 밖에 그려야 해서 Dialog 대신 raw RN `Modal`과 `KeyboardAvoidingView`를 썼다. 키보드 회피는 2026-10-13부터 Dialog가 이미 갖고 있었고, 카드 밖 층만 없었다.
+- `scrollEnabled`: 2026-10-18 번뚝 폴더 팝업. 아이콘을 끄는 동안 본문 스크롤을 꺼야 해서(`scrollEnabled={!touchingIcon && !draggingId}`) raw `Modal`의 ScrollView를 유지했다.
+- `ImmersiveOverlay`: 2026-10-18 utilverse 전광판. Dialog·Sheet는 항상 카드·scrim(`full` Sheet도 위 safe area·모서리·머리)을 그려 상태 표시줄을 숨긴 가로 전광판을 표현하지 못해 raw RN `Modal`을 썼다. 표현만 다르고 모달 스택·포커스·닫기 계약은 Dialog와 같아 Dialog의 확장으로 둔다.

package/docs/usage/components/editor-screen.md

@@ -4,7 +4,7 @@
 - 상태: 배포
 - 지원: Web · Native
 - 적용: 1.17.1
-- 검토일: 2026-10-17
+- 검토일: 2026-10-18
 - 근거: [반복 화면 조합](../../screen-patterns.md), Web·Native `src/screens.tsx`·`src/screen-flows.tsx`; 기존 개별 지침을 새 규격으로 통합. 예제 스토리는 2026-10-06 사용자 승인으로 스토리북 배포([승인 기록](../../../../../docs/STORYBOOK_NAVIGATION.md#21-2026-10-06-전체-승격과-규격-확정)). 스토리북 배포는 API 게시가 아니다(`적용` 참고)
 - 스토리북: `배포/화면/콘텐츠/작성과 수정`, `배포/화면/계정/프로필`
 
@@ -95,6 +95,7 @@ import { TextField } from "@hjmds/react-native/inputs";
 | `dirty` | `boolean` | 필수 | `true`에서 닫기를 누르면 `discard` 확인창을 띄우고, 확인하면 `cancel.onAction`을 부른다. `false`면 바로 부른다 |
 | `submit` | `ScreenFlowAction`(`{ label, onAction(), disabled?, pending? }`) | 필수 | `pending`이면 loading·비활성. 그동안 닫기 버튼도 비활성. 본문 `state`가 `ready`가 아니면 저장 비활성 |
 | `cancel` | `ScreenFlowAction` | 필수 | 헤더 시작 쪽 × 아이콘 닫기 버튼(`ScreenLayout` `exit` `close`). `label`은 보조기술 이름이다. 2026-10-17부터 글자 버튼 대신 아이콘 |
+| `stepBack` | `ScreenFlowAction` | 없음 | 1.31.0. 단계형 작성에서 주는 동안 헤더 시작 쪽이 뒤로 화살표(`exit` `back`)가 되고 누르면 `stepBack.onAction`(앞 단계로)을 부른다. 단계를 되돌리는 일이라 `dirty`여도 `discard` 확인을 띄우지 않고, 이미 열린 버리기 확인도 닫는다. `disabled`·`pending` 또는 `submit.pending`이면 잠긴다. 첫 단계에서는 빼서 × 닫기로 돌아간다 |
 | `discard` | AlertDialog confirm 요청에서 `onConfirm`을 뺀 것 + `fallbackErrorMessage: string` | 필수 | `onConfirm`은 EditorScreen이 채운다 |
 | `submitPlacement` | `"footer"` · `"header"` | `"footer"` | `header`면 저장이 상단 `actions` 자리로 가고 footer에는 `draftStatus`만 남는다 |
 | `draftStatus` | `ReactNode` | 없음 | 초안 저장 상태 안내. footer에 놓인다 |
@@ -107,7 +108,7 @@ import { TextField } from "@hjmds/react-native/inputs";
 | --- | --- | --- |
 | 크기 | ScreenLayout 폭(최대 720) 안에 입력 본문; 저장은 `Button` 기본 크기, 닫기는 `IconButton` | `ScreenLayout`, `screen-flows.tsx` `Action` |
 | 간격 | 화면 padding `spacing.md` 16; footer 안 `draftStatus`–저장 `spacing.sm` 12(`Stack gap="sm"`); 본문 안 입력 간격은 제품(Form 등) 소유 | Web·Native `EditorScreen` |
-| 순서·정렬 | 헤더(닫기 → 제목 → [저장: header 배치]) → 본문 → footer(`draftStatus` → 저장) | `EditorScreen` 렌더 순서 |
+| 순서·정렬 | 헤더(닫기 또는 `stepBack` 뒤로 → 제목 → [저장: header 배치]) → 본문 → footer(`draftStatus` → 저장) | `EditorScreen` 렌더 순서 |
 | 고정·스크롤 | 헤더·footer 고정, 본문 스크롤(`scroll` 기본 `"screen"`); 이탈 확인은 AlertDialog 오버레이 | `ScreenLayout`, `AlertDialog` |
 | 좁은 폭·큰 글자 | 제목 열 최소 폭 120 × 글자 배율, 모자라면 header 저장 버튼이 다음 줄로 내려간다; 키보드·safe area는 host | `screenPatternRecipe.headerMinWidth` |
 
@@ -119,6 +120,8 @@ import { TextField } from "@hjmds/react-native/inputs";
 - 저장 시작 또는 `cancel.disabled`/`cancel.pending` 전환은 이미 열린 초안 버리기 확인도 종료한다. 잠금이 풀렸다고 확인창이 다시 열리지는 않는다.
 - 최초 조회·오류·권한 제한 등 본문 대체 상태에서는 저장을 잠근다. 새 문서의 빈 초안은 `state="empty"`가 아니라 `ready`와 빈 입력으로 표현하고 제품 validation은 `submit.disabled`에 연결한다.
 - 라우터 뒤로가기·Android back·브라우저 이탈은 이 컴포넌트가 막지 않는다. 제품이 `dirty`로 guard를 건다.
+- 단계형 작성의 헤더 뒤로는 `header`에 TopBar를 넣어 만들지 않고 `stepBack`을 쓴다. 지난 단계를 눌러 돌아가는 표시는 [Steps](steps.md) `onStepPress`다([단계형 작성](../screens/flow-editor.md#단계형-작성1310)).
+- 첫 단계에서 이탈하는 길은 `cancel`이다. `stepBack`으로 화면을 떠나게 만들면 `discard` 확인을 건너뛴다.
 - 저장 성공 판정·오류 표시는 제품 상태(`notice`, Toast 등)로 한다.
 
 ## 플랫폼 차이
@@ -130,4 +133,5 @@ import { TextField } from "@hjmds/react-native/inputs";
 
 ## 근거
 
+- `stepBack`(1.31.0): 2026-10-18 spint 작성(색 → 이모지 → 글)은 헤더 시작 쪽이 앞 단계로 가야 했는데 EditorScreen은 × 닫기만 있고 `exit`를 받지 않아, 제품이 `header`에 TopBar를 넣어 머리를 통째로 대체했다.
 - 저장 시작 시 열린 버리기 확인 종료: 2026-10-13 이전 확인창으로 저장 중 이탈 잠금을 우회할 수 있던 경로를 수정했다.

package/docs/usage/components/field.md

@@ -81,6 +81,19 @@ import { Field } from "@hjmds/react-native/forms";
 - 상태 테두리는 recipe가 정한다: 기본 `borderControl`, 포커스 `contentBrand`, 오류 `danger`.
 - 도움말은 오류가 생겨도 사라지지 않고 둘 다 보인다(Web은 `aria-describedby`로 둘 다 연결).
 - 비활성(`disabled`)은 라벨과 컨트롤만 흐리고 도움말·오류는 원래 대비 그대로 둔다(`fieldRecipe.disabledScope`).
+
+### 오류 알림
+
+`error`가 나타나거나 바뀌면 즉시(assertive) 한 번 알린다. Field·TextField·TextArea·Select·Combobox·NumberField·
+CheckboxGroup·RadioGroup과 그 위에 만든 컨트롤(MessageComposer 등)이 같은 계약을 쓴다(1.30.0 이후).
+
+- Web: 오류 전에 미리 mount된 `role="alert"` 영역 하나가 오류 id를 갖고, 컨트롤의 `aria-describedby`가 그 영역을 가리킨다.
+  보이는 오류 문구는 `aria-hidden`이라 탐색 모드에서도 한 번만 읽힌다. 영역은 시각적으로 숨겨져 칸 간격을 바꾸지 않는다.
+- Native: 오류 문구가 assertive live region(Android)이고, live region을 읽지 않는 iOS는 새 오류마다
+  `announceForAccessibility`로 한 번 알린다.
+- 제품은 같은 문구를 Notice나 별도 `role="alert"`로 다시 그리지 않는다.
+
+근거: 2026-10-18 번뚝 DM에서 Web 필드 오류가 describedby로만 연결돼 나타날 때 낭독되지 않았고, Native iOS도 작성창·FieldGroup 외 필드 오류를 알리지 않았다. 작성창에만 숨긴 alert를 더한 첫 수정은 같은 문구를 두 번 읽게 해 공용 계약(`react/src/internal/field-error.tsx`, `react-native/src/internal/field-frame.tsx`)으로 옮겼다.
   흐림 정도는 컴포넌트 recipe에 `states.disabledOpacity`가 있으면 그 값(SearchField·PasswordField·OtpField·NumberField·Select
   0.5), 없으면 `fieldRecipe.disabledOpacity` 0.6(TextField·TextArea·Mentions·Field·NativeSelect·Combobox·DatePicker·TagsInput)이다.
   2026-10-06 전에는 틀 전체가 흐려져 잠긴 이유를 적은 도움말까지 대비가 떨어졌다.

package/docs/usage/components/icon-button.md

@@ -39,6 +39,7 @@ Dialog·Sheet footer 행동, 목록 끝 "더 보기", 온보딩 다음·이전,
 | --- | --- | --- | --- |
 | `IconButton` | 기본 | `@hjmds/react`, `/actions` | `@hjmds/react-native`, `/actions`, `/bottom-cta` |
 | `NotificationBell` | 확장 — 미확인 수 배지 + 증가 시 한 번 흔들림 | `/notification-bell` | `/notification-bell` |
+| `ClipboardIconButton` | 동반(복사) — 아이콘만 있는 복사 도구 행동. `value`, `labels: { idle; copied }`(두 상태의 접근성 이름), `onCopy?`, `onCopyError?`, `feedbackDuration?`(ms), `tone` 기본 `ghost` | `@hjmds/react`, `/clipboard` | — |
 
 `NotificationBell`은 granular subpath로만 import 된다. 추가 peer는 없다.
 

package/docs/usage/components/icon-tile.md

@@ -54,6 +54,9 @@ import { IconTile } from "@hjmds/react-native/screens";
 | overlay | ReactNode | 없음 | 제품 배지 |
 | labelLines | 1 또는 2 | 1 | 제목 줄 수 |
 | ghost | boolean | false | 이동 대상 표시 |
+| frame | `"surface"` · `"none"` | `"surface"` | 미게시(1.30.0 이후). `surface`는 공통 틀(`surfaceAlt` 채움 + 테두리 1), `none`은 틀을 그리지 않는다. 아이콘 원본이 이미 완성된 런처 아이콘(모양·배경 포함)일 때 `none` |
+| shape | `"squircle"` · `"square"` · `"circle"` | `"squircle"` | 미게시. 틀(과 ghost 점선)의 모서리. 크기 대비 비율 `iconTileRecipe.shapes`(squircle 0.22 · square 0 · circle 0.5). 제품 아이콘 테마(아이폰 셸 squircle, Windows·Linux 셸 square)를 따른다 |
+| size | `"fixed"` · `"fill"` | `"fixed"` | 미게시. `fixed`는 64×64, `fill`은 격자 칸 폭을 채우되 `fillMinSize` 48 ~ `fillMaxSize` 68 사이로 제한한 정사각형. 열 수·칸 폭은 host Grid가 정하고 제품이 칸 크기를 계산해 넘기지 않는다 |
 
 `icon: ReactNode`, `label: string`, `overlay?: ReactNode`, `labelLines?: 1 | 2`(기본1), `ghost?: boolean`(기본false). 두 줄은 런처 제목 높이44를 예약하고 ghost는 이동 대상의 점선/반투명 표현이다. 아이콘 64, 제목 최대 폭72, 간격6을 공유 recipe가 정한다. overlay는 아이콘 기준 배지를 위한 슬롯이며 넘침을 자르지 않는다.
 
@@ -61,7 +64,7 @@ import { IconTile } from "@hjmds/react-native/screens";
 
 | 항목 | 값 | 근거 |
 | --- | --- | --- |
-| 크기 | 아이콘 64×64(radius 22%), 제목 최대 폭 72 · 두 줄이면 84와 최소 높이 44 | `iconTileRecipe` |
+| 크기 | 아이콘 64×64(radius 22%, `shape`에 따라 0%·50%), `size="fill"`이면 칸 폭 48~68 정사각형; 제목 최대 폭 72 · 두 줄이면 84와 최소 높이 44 | `iconTileRecipe` |
 | 간격 | 아이콘과 제목 사이 6 | `iconTileRecipe.gap` |
 | 순서·정렬 | 아이콘(overlay 포함) 위 → 제목 아래, 가로 가운데, 제목 가운데 정렬 | 양 renderer |
 | 고정·스크롤 | Grid나 가상 목록의 host가 열 수·외부 여백·스크롤을 정한다 | 별도 scroller 없음 |
@@ -73,6 +76,8 @@ import { IconTile } from "@hjmds/react-native/screens";
 
 아이콘 원본과 제품 배지만 전달한다. 같은 배치를 별도 View/div로 다시 만들지 않는다.
 
+- 완성된 아이콘 아트워크 위에 틀이 두 겹으로 그려지면 `frame="none"`, 아이콘 모양이 테마마다 다르면 `shape`, 칸 크기를 따라 커져야 하면 `size="fill"`을 쓴다. 이 이유로 런처 항목을 직접 만들지 않는다.
+
 ## 상태와 상호작용
 
 이 구성은 표시 전용이다. 링크/버튼/드래그 host가 disabled·포커스·키보드·길게 누르기와 라우팅을 소유하므로 기존 앱의 drag engine을 교체하지 않는다.
@@ -88,3 +93,7 @@ host에 전체 행동의 현지화 이름을 제공한다. 아이콘 내부 장
 ## 관련 지침
 
 [선택 기준](../SELECTION.md), [Grid](grid.md), [Card](card.md).
+
+## 근거
+
+- `frame`·`shape`·`size`: 2026-10-18 HJM 1.30.0 감사. 유틸버스 런처는 도구 아트워크가 완성된 아이콘(셸에 따라 iPhone squircle, Windows·Linux square)이고 크기가 격자를 따라 48~68로 변해, 고정 64 틀을 그리는 IconTile 대신 자체 타일을 유지했다. 범위 48~68은 그 런처의 실제 칸 계산값이다.

package/docs/usage/components/icon.md

@@ -10,8 +10,8 @@
 
 ## 언제 쓰나
 
-HJM semantic 이름(`search`, `back`, `chevronEnd`, `notifications` 등 43개)으로 고르는 그림 기호에 쓴다.
-크기·색·선 굵기·RTL 반전은 HJM이 정하고, 그림 자체는 내장 경로(Web)나 제품이 넘긴 glyph가 그린다.
+HJM semantic 이름(`search`, `back`, `chevronEnd`, `notifications` 등 47개)으로 고르는 그림 기호에 쓴다.
+크기·색·선 굵기·RTL 반전은 HJM이 정하고, 그림은 계약의 공용 경로(Web 내장, Native `/icon-svg`)나 제품이 넘긴 glyph가 그린다.
 
 ## 쓰지 않을 때
 
@@ -29,14 +29,17 @@ HJM semantic 이름(`search`, `back`, `chevronEnd`, `notifications` 등 43개)
 | --- | --- | --- | --- |
 | `Icon` | 기본 | `@hjmds/react`, `/display` | `@hjmds/react-native`, `/primitives` |
 | `createLucideGlyph` | 보조 — Lucide glyph 연결 helper(컴포넌트 아님) | `/icon-lucide` | `/icon-lucide` |
+| `renderSemanticGlyph` | 보조 — HJM 공용 경로를 그리는 `renderGlyph`(컴포넌트 아님, 1.31.0) | — (내장) | `/icon-svg` |
+| `semanticIconPaths` · `isSemanticIconName` | 공용 24 격자 경로 데이터와 이름 판별 | `@hjmds/design-contracts/components/icon` | 같음 |
 
 `/icon-lucide`는 optional peer가 필요하다. Web `lucide-react` 1.49.0,
-Native `lucide-react-native` 1.49.0. 루트 entry에서는 나오지 않는다.
+Native `lucide-react-native` 1.49.0. Native `/icon-svg`는 optional peer `react-native-svg` 15.15.5가 필요하다.
+둘 다 루트 entry에서는 나오지 않는다.
 
 ## 최소 사용 예
 
 ```tsx
-// Web — 내장 glyph
+// Web — built-in glyph
 import { Icon } from "@hjmds/react/display";
 
 <Icon name="search" />
@@ -54,6 +57,42 @@ const renderGlyph = createLucideGlyph({ search: Search, back: ArrowLeft });
 <Icon descriptor={{ name: "search" }} renderGlyph={renderGlyph} />
 ```
 
+```tsx
+// Native — Web과 같은 HJM 공용 그림(react-native-svg 필요)
+import { renderSemanticGlyph } from "@hjmds/react-native/icon-svg";
+
+<Icon descriptor={{ name: "arrowUp" }} renderGlyph={renderSemanticGlyph} />
+```
+
+### 공용 그림의 Native 제공 방식(1.31.0 추가)
+
+2026-10-18 utilverse가 사진 순서 변경·회전 IconButton을 위해 `arrowUp`·`arrowDown`·`rotate` 경로를 앱 adapter에 직접
+그렸다. Web만 HJM 경로를 내장하고 그 경로가 renderer 내부에 있어 Native는 같은 그림을 받을 수 없었기 때문이다.
+경로는 외형 값이므로 계약 `semanticIconPaths`로 옮겨 두 플랫폼이 같은 데이터를 읽는다.
+
+Native Icon은 `renderGlyph`를 필수로 유지한다. core 컨트롤이 `react-native-svg` 없이 동작하도록 SVG는 optional peer이고,
+내장 컨트롤의 몇 기호(셰브런·달력·삭제 등)는 내부에서 View로 그린다. 그래서 공용 그림은 `/icon-lucide`와 같은
+선택 entry `/icon-svg`의 `renderSemanticGlyph`로 연다. 앱 고유 이름을 함께 쓰면 판별 후 넘긴다.
+
+```tsx
+// Native — app glyph names mixed with HJM names
+import { isSemanticIconName } from "@hjmds/design-contracts/components/icon";
+
+const renderGlyph = (props: NativeIconRenderProps<AppGlyphName>) =>
+  isSemanticIconName(props.name) ? renderSemanticGlyph(props) : renderAppGlyph(props);
+```
+
+`react-native-svg`를 설치하지 않는 앱은 자기 adapter에서 `semanticIconPaths[name]`을 읽어 같은 경로를 그린다.
+
+### 이름 고르기
+
+| 목적 | 이름 | 비고 |
+| --- | --- | --- |
+| 순서를 위/아래로 옮기기 | `arrowUp` · `arrowDown` | 1.31.0 추가. 위아래는 물리 방향이라 RTL에서 반전하지 않는다 |
+| 이미지·페이지 90° 회전 | `rotate` | 1.31.0 추가. 시계 방향. RTL에서 반전하지 않는다. 다시 불러오기는 `refresh` |
+| 차단·잠금 해제 | `unblock` | 1.31.0 추가. `lock`의 고리가 열린 모양 |
+| 비밀번호 보기/숨기기(눈/가린 눈) | `visibility` · `visibilityOff` | 이미 있는 이름이다. `eye`라는 이름은 없다. 숨김 상태에서 `visibility`, 보임 상태에서 `visibilityOff`(누르면 될 상태). 비밀번호 입력 자체는 이 짝을 이미 내장한 [PasswordField](password-field.md)를 쓴다 |
+
 ## 축과 기본값
 
 | prop | 값 | 기본값 | 설명 |
@@ -93,7 +132,7 @@ const renderGlyph = createLucideGlyph({ search: Search, back: ArrowLeft });
 | 항목 | Web | Native |
 | --- | --- | --- |
 | API 모양 | 평평한 prop(`name`, `size`, `tone` …) | `descriptor` 객체 하나 |
-| glyph | 내장 SVG 경로, `renderGlyph`는 선택 | `renderGlyph` 필수(내장 그림 없음) |
+| glyph | 내장 SVG 경로(`semanticIconPaths`), `renderGlyph`는 선택 | `renderGlyph` 필수. 공용 경로는 `/icon-svg`의 `renderSemanticGlyph` |
 | 사용자 정의 이름 | `SemanticIconName`만 | `Icon<Name>` 제네릭으로 제품 이름 허용 |
 | 출력 | `<svg>`(장식이면 `aria-hidden`) | `View` 프레임(장식이면 `accessible={false}`) |
 | 배치 | `layoutStyle` | `layoutStyle`. `style`은 제거된 속성 — `layoutStyle` 또는 descriptor `size`·`tone` |
@@ -102,4 +141,4 @@ const renderGlyph = createLucideGlyph({ search: Search, back: ArrowLeft });
 
 - 아이콘은 자기 `tone` 색을 직접 칠한다. Web CSS가 `data-tone`으로 색을 지정하므로 부모 색을 상속하지 않는다.
   primary·danger IconButton 안에서 기본 tone(`secondary`)을 쓰면 채워진 면 위에 회색이 된다. 이때는 `tone="inverse"`.
-- `createLucideGlyph` 맵에 없는 이름을 그리면 실행 중 `TypeError`가 난다.
+- `createLucideGlyph` 맵에 없는 이름을 그리면 실행 중 `TypeError`가 난다. `renderSemanticGlyph`도 HJM 이름이 아니면 `TypeError`를 낸다.

package/docs/usage/components/image-choice-group.md

@@ -52,6 +52,7 @@ import { ImageChoiceGroup } from "@hjmds/react-native/image-choice";
 | --- | --- | --- | --- |
 | `label` | `string` | 필수 | 묶음의 접근성 이름 |
 | `showLabel` | `boolean` | `false` | 타일 위에 `label`을 보이는 글자로 둔다 |
+| `showItemLabels` | `boolean` | `false` | 미게시. 타일마다 항목 `label`을 그림 아래 한 줄(caption, 넘치면 말줄임)로 보인다. 같은 누름 영역 안에 있고 보조기술은 기존처럼 타일 이름 하나만 읽는다. 사람을 이름으로 알아봐야 하는 받는 사람 선택에 쓴다 |
 | `items` | `{ id, label, image, disabled? }[]` | 필수 | id 중복·빈 이름이면 `TypeError`. `image`는 칸을 채우는 그림 노드 |
 | `selectionMode` | `"single"` · `"multiple"` | 필수 | 단일은 radio, 다중은 checkbox로 읽힌다 |
 | `value`·`onValueChange` | 단일 `string \| null` / 다중 `string[]` | 필수 | 제어형. 다중은 누른 순서대로 추가·제거 |
@@ -62,7 +63,7 @@ import { ImageChoiceGroup } from "@hjmds/react-native/image-choice";
 | 항목 | 값 | 근거 |
 | --- | --- | --- |
 | 크기 | 그림 72 정사각, 바깥 고리 2 + 간격 2(터치 영역 80), radius `radius.md` 12, 체크 원 20 | `imageChoiceRecipe` |
-| 간격 | 타일 사이 `spacing.xs` 8, 라벨–타일 8 | `imageChoiceRecipe.gap` |
+| 간격 | 타일 사이 `spacing.xs` 8, 라벨–타일 8, 그림–항목 라벨 `spacing.xxs` 4 | `imageChoiceRecipe.gap`, `itemLabelGap` |
 | 순서·정렬 | `items` 순서대로 시작 쪽부터 줄바꿈 배치, 체크는 타일 끝 쪽 위 모서리 | 두 렌더러 |
 | 고정·스크롤 | 자체 스크롤 없음. 바깥 목록·화면이 스크롤 | 두 렌더러 |
 | 좁은 폭·큰 글자 | 남은 폭에서 줄바꿈, 타일 크기는 유지 | flex wrap |
@@ -78,4 +79,5 @@ import { ImageChoiceGroup } from "@hjmds/react-native/image-choice";
 
 ## 근거
 
+- `showItemLabels`: 2026-10-18 번뚝 공유 받는 사람 선택이 이름을 보이려고 링크 버튼에 아바타·체크·이름을 직접 조립했다.
 - 도입 계기: 2026-10-16 구성 예제 점검 — 제품들이 `selected`를 준 ghost 버튼으로 그림 선택을 흉내 내 선택 상태가 일관되지 않았다.

package/docs/usage/components/media-selection-screen.md

@@ -30,6 +30,7 @@
 | 이름 | 역할 | Web | Native |
 | --- | --- | --- | --- |
 | `MediaSelectionScreen` | 미디어 선택 검토 화면 | `/screen-flows` | `/screen-flows` |
+| `MediaSelectionCell` | 화면 격자가 그리는 항목 칸(미리보기 → UploadItem → 위로·아래로·회전·삭제). 가상화 목록에서 같은 칸을 그릴 때 쓴다. 미게시 | `/screen-flows` | `/screen-flows` |
 
 granular subpath로만 import 된다(루트 entry에 없음). 추가 peer는 없다.
 
@@ -96,6 +97,7 @@ Web의 `<img alt="">`는 장식용 미리보기다. 사진 이름은 `removeLabe
 | `removeLabel` · `moveUpLabel` · `moveDownLabel` | `(item: MediaSelectionItem) => string` | 필수 | 사진 이름을 포함한 접근성 이름 |
 | `onMove` | `(id: string, direction: -1 \| 1) => void` | 필수 | 첫 항목의 위로·마지막 항목의 아래로는 비활성 |
 | `onRemove` · `onRetry` · `onCancel` | `(id: string) => void` | 필수 | 삭제, UploadItem 재시도·취소 |
+| `rotate` | `{ label, itemLabel(item), onRotate(id) }` | 없음 | 미게시. 주면 아래로와 삭제 사이에 회전 버튼(`label` 표시 문구, `itemLabel` 사진 이름을 포함한 접근성 이름). 회전 값 저장과 `preview`·결과물 반영은 제품이 한다 |
 | 나머지 | `ScreenLayout`과 같음(`children`·`footer` 제외) | — | `actions`를 주면 `add` 앞에 같은 행으로 놓인다 |
 
 ## 배치
@@ -108,6 +110,21 @@ Web의 `<img alt="">`는 장식용 미리보기다. 사진 이름은 `removeLabe
 | 고정·스크롤 | 헤더·footer 고정, 격자는 본문 스크롤(`scroll` 기본 `"screen"`) | `ScreenLayout` |
 | 좁은 폭 | 좁은 폭에서도 2열 유지; 항목 버튼 줄은 줄바꿈(`flexWrap: "wrap"`)해 버튼을 자르지 않는다 | `screen-flows.tsx` |
 
+## 가상화 목록의 항목 칸
+
+사진이 많아 제품이 `VirtualList`·`FlatList`로 목록을 직접 그릴 때는 같은 칸 `MediaSelectionCell`을 `renderItem`에서 그린다. 미리보기와 행동 줄을 제품이 다시 조립하지 않는다(2026-10-18 Utilverse 사진→PDF·사진 띠 도구가 썸네일·순서·회전·삭제 칸을 직접 만들었다).
+
+```tsx
+// Native
+import { MediaSelectionCell } from "@hjmds/react-native/screen-flows";
+
+<FlatList data={photos} keyExtractor={photo => photo.id} renderItem={({ item, index }) =>
+  <MediaSelectionCell item={toMediaItem(item)} index={index} count={photos.length} {...itemActions}
+    rotate={{ label: t("photo.rotate"), itemLabel: entry => t("photo.rotateNamed", { name: entry.descriptor.name }), onRotate: rotatePhoto }} />} />
+```
+
+`index`·`count`는 전체 목록 기준이다(첫 항목 위로·마지막 항목 아래로 비활성). `itemActions`는 화면과 같은 `labels`·`actionLabels`·`removeLabel`·`moveUpLabel`·`moveDownLabel`·`onRemove`·`onMove`·`onRetry`·`onCancel`이다. 칸 사이 간격·열 수는 host가 준다. 삭제 후 Web 키보드 초점 복구는 화면 격자의 동작이므로 가상화 host는 자기 초점을 소유한다.
+
 ## 꼭 지킬 것
 
 - `actionLabels`는 짧은 표시 문구, `removeLabel`·`moveUpLabel`·`moveDownLabel`은 사진 이름을 포함한 접근성 이름이다.

package/docs/usage/components/message-composer.md

@@ -76,7 +76,7 @@ import { Image } from "react-native";
 | `value` | `string` | 필수 | 완전 제어형. HJM은 초안을 지우지 않는다 |
 | `label` | `string` | 필수 | 접근성 이름; placeholder 생략 시 같은 문구 |
 | `placeholder` | `string` | `label` | 짧은 시각 안내와 전체 접근성 이름을 분리 |
-| `description` · `error` · `invalid` | `string` · `string` · `boolean` | 없음 | TextArea의 안내·오류 연결. Web describedby/invalid, Native hint/오류 표면 |
+| `description` · `error` · `invalid` | `string` · `string` · `boolean` | 없음 | TextArea의 안내·오류 연결. Web describedby/invalid, Native hint/오류 표면. `error`는 나타나거나 바뀔 때 즉시(assertive) 알린다(1.30.0 이후 수정). 작성창 전용 알림은 없고 TextArea의 공용 Field 오류 계약([Field](field.md#오류-알림))을 그대로 쓴다 |
 | `onBlur` | `() => void` | 없음 | host의 입력 중 상태 해제 |
 | `submitMode` | `"newline"` · `"send"` | `"newline"` | Web Enter 전송은 Shift/IME/229 보호. Native send는 submit, newline은 기존 줄바꿈 |
 | `sendLabel` | `string` | 필수 | 전송 버튼 문구·접근성 이름 |
@@ -123,6 +123,7 @@ import { Image } from "react-native";
 - 입력 연결(blur/IME/검증)이 더 필요하면 제품이 내부 TextArea를 따로 조립하지 않고 기존 MessageComposer 엔진의 공개 축을 확장한다.
 - 로컬 준비 사진은 `attachments`로 표시하며 UploadItem의 서버 업로드 완료로 가장하지 않는다. 준비 중 해당 항목의 `disabled`와 attachmentAction.disabled를 연결해 편집 가능한 본문과 사진 제거를 분리한다. 서버 성공 전 초안을 지우지 않는다.
 - Web 배치는 `layoutStyle`로 한다. Native는 스타일 통로가 없어 감싸는 레이아웃에서 배치한다.
+- 전송 실패는 `error`로 넘긴다. 알림을 위해 같은 문구를 화면 `notice`의 Notice나 `context`의 `role="alert"` 문구로 한 번 더 그리지 않는다.
 
 ## 플랫폼 차이
 
@@ -140,6 +141,8 @@ Native 내장 삭제·메뉴 기호는 고정 아이콘 틀의 크기를 유지
 
 ## 근거
 
+- `error` 즉시 알림: 2026-10-18 번뚝 DM. 작성창 `error`가 입력 아래에 보이기만 하고 낭독되지 않아(Web 알림 없음, iOS live region 미지원) 전송 실패를 화면 notice의 Notice로 따로 알렸다. 첫 수정은 작성창에만 숨긴 alert를 더해 Web 탐색 모드에서 같은 문구를 두 번 읽었으므로, 같은 날 모든 Field 컨트롤의 공용 오류 계약으로 옮겼다.
+
 - 답장 중 카드 배치: 2026-10-16 카카오톡 실측.
 - `submitMode` 등 입력 공개 축: 2026-10-07 번뚝 채택에서 기존 blur/IME/검증 연결이 누락됐다.
 - Native 내장 기호 고정 크기: 2026-10-06 최근 검색 삭제 기호가 큰 글자에서 잘리는 것을 재현했다.