@ihabdevteam/core 0.149.0 → 0.151.0

package/dist/ihabdevteam-core.d.ts

@@ -13,6 +13,7 @@ import { KeyboardEvent as KeyboardEvent_2 } from 'react';
 import { MouseEvent as MouseEvent_2 } from 'react';
 import { default as React_2 } from 'react';
 import * as React_3 from 'react';
+import { ReactElement } from 'react';
 import { ReactNode } from 'react';
 import { ReactPortal } from 'react';
 import { Ref } from 'react';
@@ -29,6 +30,12 @@ export declare interface AccordionItem {
     title: ReactNode;
     body: ReactNode;
     avatar?: ReactNode;
+    /**
+     * 항목의 변하지 않는 이름. 주면 펼침 상태가 **자리 번호가 아니라 이 id 에** 묶인다 —
+     * 목록 앞에 항목이 더해지거나 빠져도(새 공지가 맨 위에 붙는 등) 펼친 항목이 그대로 펼쳐져 있다.
+     * 안 주면 지금처럼 자리 번호로 묶인다. 같은 목록 안에서 겹치지 않아야 한다.
+     */
+    id?: string;
 }
 
 /** @public */
@@ -76,7 +83,7 @@ export declare interface ActionCardProps {
 }
 
 /** @public */
-export declare function Alert({ tone, title, message, children, dismissible, onDismiss, className, }: AlertProps): JSX.Element | null;
+export declare function Alert({ tone, title, message, children, dismissible, onDismiss, live, className, }: AlertProps): JSX.Element | null;
 
 /** @public */
 export declare interface AlertProps {
@@ -88,6 +95,12 @@ export declare interface AlertProps {
     /** 닫기(×) 버튼 표시 여부 */
     dismissible?: boolean;
     onDismiss?: () => void;
+    /**
+     * 낭독기에 알리는 방식. 안 주면 톤이 정한다 — `danger`·`warning` 은 `'assertive'`(`role="alert"`, 하던 말을 끊고 읽음),
+     * `info`·`success` 는 `'polite'`(`role="status"`, 하던 말 뒤에 읽음).
+     * `'off'` 는 live 역할을 두지 않는다 — 화면에 늘 놓인 안내(설정 화면 머리의 주의 글 등)가 열 때마다 끼어들어 읽히지 않게.
+     */
+    live?: 'assertive' | 'polite' | 'off';
     className?: string;
 }
 
@@ -345,7 +358,7 @@ export declare interface BarChartProps {
      *
      * 굵기만 줄이고 싶을 때 `small` 로 가면 높이·헤더 컨트롤·합계 라벨까지 같이
      * 줄어든다(2026-09-10 말귀 실측). 이 값은 굵기만 바꾼다. 막대가 많아지면 여기
-     * 적은 값을 **위 한계**로 두고 점진 축소하는 것은 그대로다.
+     * 적은 값을 **위 한계**로 두고 점진 축소하는 것은 그대로다. 아래 한계는 2px(그보다 작은 값은 2 로).
      *
      * CSS 로 덮고 싶으면 `.manager-bar-chart-bar`·`-stack` 의 `--bar-width` 를 쓴다 —
      * 굵기는 인라인이 아니라 그 변수로 박혀 있다.
@@ -361,7 +374,7 @@ export declare interface BarChartProps {
     /** 계열 A/B 레이블 i18n 키. labelBKey 미지정 시 단일 계열 */
     labelAKey: string;
     labelBKey?: string;
-    /** 선택된 구간의 합계(a+b)를 헤더 아래 히어로로 표시 */
+    /** 선택된 구간의 합계(a+b)를 헤더 아래 히어로로 표시. 월 보기는 그 달 날짜만 센다(주 막대가 달 경계를 넘어도 합계는 달력 달 — 상세 목록과 같은 범위) */
     showTotal?: boolean;
     /** 합계 단위 i18n 키 (예: 'trainingStatus.weekly.unit' → '회') */
     totalUnitKey?: string;
@@ -432,7 +445,10 @@ declare type Base = {
 
 /**
  * 게시판형 목록 표. 상태를 갖지 않는 표현 컴포넌트이므로 검색·페이지네이션은
- * `toolbar`로 주입하고 필터링된 `rows`를 넘긴다. 서버 렌더링 환경에서도 그대로 쓸 수 있다.
+ * `toolbar`로 주입하고 필터링된 `rows`를 넘긴다.
+ *
+ * 기본 빈 문구는 i18n(`board.empty`)을 따른다 — 전에는 한국어가 박혀 영어 화면에서도 한국어였다. 그래서 i18n 훅을 쓰는
+ * 클라이언트 컴포넌트('use client')다(서버 렌더링(SSR)은 그대로 된다).
  * @public
  */
 export declare function Board<T>({ columns, rows, rowKey, title, toolbar, empty, loading, caption, className, }: BoardProps<T>): JSX.Element;
@@ -461,7 +477,7 @@ export declare interface BoardProps<T> {
     title?: ReactNode;
     /** 우측 상단 영역 — 검색 입력 등. 상태는 소비자가 소유한다 */
     toolbar?: ReactNode;
-    /** rows가 비었을 때 표시할 내용 */
+    /** rows가 비었을 때 표시할 내용. 기본은 i18n `board.empty`(ko '등록된 항목이 없습니다.') */
     empty?: ReactNode;
     /** 로딩 중 표시할 내용 — 지정 시 rows 대신 렌더 */
     loading?: ReactNode;
@@ -500,13 +516,24 @@ export declare function BrandIdentity({ appMode }: {
     appMode?: 'malgwi' | 'manager';
 }): JSX.Element;
 
-/** @public */
+/**
+ * 이동 경로. 마지막 항목은 지금 쪽(`aria-current="page"`, 누를 수 없는 글자 — onClick·href 무시).
+ * 앞 항목은 `href` 가 있으면 링크, `onClick` 만 있으면 단추, 둘 다 없으면 글자다.
+ * @public
+ */
 export declare function Breadcrumb({ items, className }: BreadcrumbProps): JSX.Element;
 
 /** @public */
 export declare interface BreadcrumbItem {
     label: string;
+    /** 누르면 부른다 — 주면 단추(`href` 도 주면 링크에 건다). 마지막 항목(지금 쪽)에서는 무시한다. */
     onClick?: () => void;
+    /** 주면 링크(`<a>`)로 그린다. 마지막 항목(지금 쪽)에서는 무시한다. `onClick`·`href` 가 둘 다 없는 중간 항목은 누를 수 없는 글자다. */
+    href?: string;
+    /** 선택. 링크의 target(`href` 와 함께). */
+    target?: string;
+    /** 선택. 링크의 rel. `target="_blank"` 이고 안 주면 `noopener noreferrer`. */
+    rel?: string;
 }
 
 /** @public */
@@ -524,7 +551,8 @@ export declare function buildChangeWholeSyllableProblem(word: string, compFrom:
 
 /**
  * @public 합성어 부분 탈락 → [문제단어(합성어), 남는 실단어(정답), 그 단어의 대립쌍 실단어 오답 2].
- * 합성어 근사: 앞/뒤로 나눈 두 조각이 '둘 다 실단어'(wordSet)인 첫 조합을 채택(예: 손수건=손+수건).
+ * 합성어 근사: 앞/뒤로 나눈 두 조각이 '둘 다 실단어'(wordSet)이고 **적어도 한 조각이 2음절 이상**인 조합을 채택(예: 손수건=손+수건).
+ * 1음절 조각 둘(하품=하+품)은 합성어로 보지 않는다 — 그래서 2음절 낱말은 늘 null.
  * 정답·오답 전부 실단어라 발음이 그대로. comp(훈련음소) 지정 시 남는 단어의 그 자리를 대립, 없으면 전 음절.
  * dropPos: 0=어두 어근(앞) 탈락, 1=어말 어근(뒤) 탈락. 결과의 `dropped` 에 뺀 조각을 담는다. 편집기·런타임 공용.
  */
@@ -679,8 +707,17 @@ export declare interface BulkBarProps {
  */
 export declare function bulkSetImageExistence(entries: Record<string, boolean>): void;
 
-/** @public */
-export declare function Button(props: ButtonProps): JSX.Element;
+export declare const Button: ButtonComponent;
+
+/**
+ * 단추(또는 `href` 가 있으면 링크). `ref` 를 주면 그 요소(`HTMLButtonElement`, 링크면 `HTMLAnchorElement`)에 닿는다 —
+ * forwardRef 라 React 16.8~18 에서도 된다.
+ * @public
+ */
+declare type ButtonComponent = {
+    (props: ButtonProps & RefAttributes<HTMLButtonElement | HTMLAnchorElement>): ReactElement | null;
+    displayName?: string;
+};
 
 declare type ButtonItem = {
     label: ReactNode;
@@ -749,6 +786,14 @@ export declare interface ButtonProps {
     align?: 'center' | 'left' | 'right' | 'grid';
     selected?: boolean;
     toggleable?: boolean;
+    /**
+     * 여닫이 단추(설정 판·미리보기·유의사항 펼치기)의 열림 상태. 주면 `aria-expanded` 로 알리고 **`aria-pressed` 는 달지 않는다** —
+     * `selected={열림}` 만 주면 "눌림" 으로 읽혀 무엇이 열렸는지 알 수 없었다. 켜진 모양(`is-selected`)은 `selected` 로 따로 준다.
+     * @example <Button label="훈련 설정" selected={open} ariaExpanded={open} ariaControls={panelId} />
+     */
+    ariaExpanded?: boolean;
+    /** 이 단추가 여닫는 영역의 id — `aria-controls` 로 단다(`ariaExpanded` 와 함께 쓴다) */
+    ariaControls?: string;
     disabled?: boolean;
     /** label을 숨기려면 false로 설정 */
     useLabel?: boolean;
@@ -824,7 +869,7 @@ export declare const CACHE_GROUPS: readonly [{
 export declare type CacheGroupId = typeof CACHE_GROUPS[number]['id'];
 
 /** @public */
-export declare function Calendar({ visits, onVisitClick, onVisitMove, onDayClick, }: {
+export declare function Calendar({ visits, onVisitClick, onVisitMove, onDayClick, today, }: {
     visits?: Visit[];
     onVisitClick?: (visit: Visit) => void;
     onVisitMove?: (visitId: string | number, newDate: string) => void;
@@ -833,6 +878,11 @@ export declare function Calendar({ visits, onVisitClick, onVisitMove, onDayClick
      * 주지 않으면 칸은 눌리지 않고 손 모양도 뜨지 않는다(못 하는 일을 내밀지 않는다).
      */
     onDayClick?: (date: string) => void;
+    /**
+     * 선택. '오늘' 로 쓸 날 'YYYY-MM-DD' — 처음 여는 달과 오늘 표시가 이 날을 따른다.
+     * 로컬 앱·SSR 처럼 부르는 쪽이 오늘을 정하는 자리에서 넘긴다. 없거나 꼴이 틀리면 KST 오늘(기본).
+     */
+    today?: string;
 }): JSX.Element;
 
 /** 카테고리별 capability 메타 + 소속 그룹. group은 유형↔카드 스텝 계열 판정의 단일 소스. */
@@ -855,6 +905,19 @@ export declare function cardQuestionTitle(typeKey: string | undefined, item: Rec
 /** @public */
 export declare function CardStep({ _stepIndex, _totalSteps, ...rest }: StepWrapperProps): JSX.Element;
 
+/**
+ * 한 칸의 낱말들을 **동형어 번호까지** 한 줄로 — `배#2 / 패`. 번호가 없는 낱말은 {@link cellLabel} 과 같다.
+ *
+ * 채점과 함께 저장하는 칸 낱말(`labelsForSave` 에 넘길 것)로 쓰면 `weakItems` 가 '배'(1)·'배'(2) 를 따로 센다.
+ * 글자만(`cellLabel`) 저장하면 둘의 성적이 한 줄로 합쳐진다. 화면에 보일 글자는 {@link labelOfCellKey} 로 되돌린다.
+ *
+ * @public
+ */
+export declare function cellKey(words: readonly {
+    label: string;
+    homonum?: number | null;
+}[]): string;
+
 /** 한 칸의 낱말들을 한 줄로 — 대립쌍은 `가게 / 가재`. */
 export declare function cellLabel(words: readonly {
     label: string;
@@ -1254,15 +1317,24 @@ export declare interface ConfirmPopupProps {
     };
     /**
      * 확인 클릭 시 실행. `close`로 직접 닫을 수 있음(async 지원).
-     * 기본은 onConfirm 완료 후 자동으로 닫힘(closeOnConfirm). 받은 `close()` 를 부르면 그것도 닫힘으로 센다(닫히는 동안 잠금 유지).
+     * 기본은 onConfirm 완료 후 자동으로 닫힘(closeOnConfirm) — **닫히면 onClose 도 불린다**(확인으로 닫혀도).
+     * 받은 `close()` 를 부르면 그것도 닫힘으로 센다(닫히는 동안 잠금 유지).
      * 던지거나 거절되면 창이 남고 잠금이 풀린다 — 거절은 console.error 로 받는다.
      * 안에서 부모가 창을 치우면 그 뒤 onClose 는 불리지 않는다.
      */
     onConfirm: (close: () => void) => void | Promise<void>;
     /** false면 자동으로 닫지 않음 — onConfirm이 전달받은 close로 닫힘 시점을 제어 (성공 시에만 닫기 등). 기본 true */
     closeOnConfirm?: boolean;
-    /** 취소/닫기 시 호출 (보통 상태 초기화) */
+    /**
+     * 창이 닫힌 뒤 호출(보통 열림 상태 끄기). 취소·X·ESC·바탕으로 닫을 때뿐 아니라 **확인(또는 곁 단추)으로 닫힐 때도 불린다** —
+     * 확인 뒤의 일은 onConfirm 에서 하고, 여기서는 "창이 사라졌다" 만 처리한다. 확인과 취소를 가르려면 onConfirm 에서 표시해 둔다.
+     */
     onClose: () => void;
+    /**
+     * 선택. 열릴 때 포커스를 둘 단추 — `'close'`(머리의 X, 기본·지금 동작) · `'confirm'`(확인) · `'cancel'`(취소).
+     * 되돌릴 수 없는 일(삭제)은 기본이나 `'cancel'` 로 두어 Enter 한 번에 실행되지 않게 한다. 그 단추가 없거나 꺼져 있으면 기본 자리.
+     */
+    initialFocus?: 'close' | 'confirm' | 'cancel';
     /** portal 없이 부모 컨테이너에 제자리 렌더 (목업/데모용) */
     inline?: boolean;
     /** 패널 최대 가로폭. 확인창 기본은 'small'(480px) */
@@ -1284,7 +1356,7 @@ export declare interface ContrastFilterOpts {
     pronOf: (w: string) => string;
     /** 표준발음 문자열 → 음절 분해(캐시 권장). sameStructureOnly일 때만 필요. */
     decompOf?: (pron: string) => Decomp;
-    /** true면 구조 대립(초성 ㅇ 유무·받침 유무)도 제외(decompOf 필요). */
+    /** true면 구조 대립(초성 ㅇ 유무·활음 유무·종류·받침 유무)도 제외(decompOf 필요). */
     sameStructureOnly?: boolean;
 }
 
@@ -1388,7 +1460,7 @@ export declare function copyText(text: string): Promise<boolean>;
  *
  * 값은 손으로 적고 `test/coreVersion.test.ts` 가 package.json 과 어긋나면 운다.
  */
-export declare const CORE_VERSION = "0.149.0";
+export declare const CORE_VERSION = "0.151.0";
 
 /** @public */
 declare const coreDefault: Record<string, unknown>;
@@ -1590,7 +1662,7 @@ export declare function cx(...parts: (string | false | null | undefined)[]): str
 
 export declare type DataLevel = 0 | 1 | 2 | 3;
 
-export declare function DatePicker({ value, onChange, size, min, max, disabled, placeholder: placeholderProp, className, }: DatePickerProps): JSX.Element;
+export declare function DatePicker({ value, onChange, size, min, max, disabled, placeholder: placeholderProp, className, today, }: DatePickerProps): JSX.Element;
 
 /** @public */
 export declare interface DatePickerProps {
@@ -1603,6 +1675,12 @@ export declare interface DatePickerProps {
     /** 값이 없을 때 보이는 문구. 기본은 사전의 `datePicker.chooseDate`('날짜 선택') */
     placeholder?: string;
     className?: string;
+    /**
+     * 선택. '오늘' 로 쓸 날 'YYYY-MM-DD' — 오늘 표시, 값 없이 열 때의 달·포커스가 이 날을 따른다.
+     * 로컬 앱·SSR 처럼 부르는 쪽이 오늘을 정하는 자리에서 넘긴다. 없거나 꼴이 틀리면 KST 오늘(기본).
+     * (min·max 는 이 값과 따로다 — '오늘부터' 를 막으려면 min 에도 같은 날을 넘긴다.)
+     */
+    today?: string;
 }
 
 /**
@@ -1800,7 +1878,8 @@ export declare const DocumentTitleSuppressContext: Context<boolean>;
 
 /**
  * 브라우저에서 CSV 파일을 내려받게 한다. 앞에 BOM 을 붙인다 — 없으면 엑셀이 한글을
- * 깨뜨린다.
+ * 깨뜨린다. **이미 BOM 으로 시작하는 글에는 또 붙이지 않는다**(두 번 붙으면 엑셀 첫 칸 머리에 보이지 않는 글자가 낀다).
+ * Blob 주소는 누르고 조금 뒤에 회수한다.
  */
 export declare function downloadCsvText(filename: string, csv: string): void;
 
@@ -1860,6 +1939,7 @@ export declare interface DropdownOption {
 export declare interface DropdownProps {
     options: DropdownOption[];
     value?: string;
+    /** 고른 값으로 불린다. **값이 바뀔 때만** — 이미 고른 항목을 다시 고르면 부르지 않고 메뉴만 닫는다. */
     onChange?: (value: string) => void;
     placeholder?: string;
     disabled?: boolean;
@@ -1902,9 +1982,20 @@ export declare function EffectPartyPopper({ active, count, duration, strength, /
     trigger?: number;
 }): JSX.Element | null;
 
-/** @public */
+/**
+ * @public 앱에 한 번 붙여 두는 폭죽 자리.
+ *
+ * - `active`·`trigger` 를 주면 그대로 `EffectPartyPopper` 에 넘긴다(전과 같다).
+ * - **`window` 의 `party:trigger` 이벤트를 듣는다** — `TrainingResultPopup` 이 정답률 50% 초과일 때 보낸다.
+ *   `detail` 의 `count`·`strength`·`duration` 으로 한 번 터뜨리고, 다 사라지면 걷는다. 전에는 아무도 이 이벤트를
+ *   안 들어 결과 창의 폭죽이 한 번도 안 났다. 움직임 최소화(prefers-reduced-motion: reduce)면
+ *   `EffectPartyPopper` 가 그리지 않는다. 보내는 쪽이 한 틱 미뤄 보내 StrictMode 에서도 한 번만 온다.
+ * - 이 자리가 앱에 없으면 이벤트는 아무 일도 안 한다.
+ */
 export declare function EffectPartyPopperHost({ trigger, active }: {
+    /** 값이 바뀌면 다시 터진다 — EffectPartyPopper 에 그대로 넘긴다. */
     trigger?: number;
+    /** true 인 동안 그린다 — EffectPartyPopper 에 그대로 넘긴다. 이벤트로 터지는 폭죽과는 따로다. */
     active?: boolean;
 }): JSX.Element;
 
@@ -1921,10 +2012,14 @@ export declare interface EmptyStateProps {
     message?: string;
     /** 메시지 아래 보조 안내(선택). message와 별도 문단으로 렌더 — 문자열 접합 오용 방지. */
     hint?: string;
+    /**
+     * 메시지 아래 단추(다시 시도 등). `onClick` 이 **약속(Promise)을 돌려주면 끝날 때까지(성공·실패 모두) 단추를 막는다** —
+     * 두 번 눌러 요청이 두 번 나가지 않게.
+     */
     action?: {
         label: string;
         icon?: string;
-        onClick: () => void;
+        onClick: () => void | Promise<unknown>;
     };
     /** 표 안의 빈 행처럼 좁은 자리에 넣을 때 위아래 여백을 줄인다. */
     compact?: boolean;
@@ -1948,8 +2043,11 @@ export declare interface ErrorStateProps {
     /** 보조 안내(선택). */
     hint?: string;
     icon?: string;
-    /** 다시 시도 콜백 — 지정 시 '다시 시도' 버튼 노출. */
-    onRetry?: () => void;
+    /**
+     * 다시 시도 콜백 — 지정 시 '다시 시도' 버튼 노출.
+     * **약속(Promise)을 돌려주면 끝날 때까지(성공·실패 모두) 단추를 막는다** — 느린 다시 불러오기에서 두 번 눌러 요청이 두 번 나가지 않게.
+     */
+    onRetry?: () => void | Promise<unknown>;
     /** 재시도 버튼 라벨(미지정 시 공용 기본). */
     retryLabel?: string;
     className?: string;
@@ -1966,7 +2064,11 @@ export declare interface ErrorStateProps {
  *    뒤 열이 통째로 밀린다.
  * 2. **수식으로 실행되지 않게.** `=`·`+`·`-`·`@` 로 시작하는 값을 엑셀·시트가 수식으로
  *    실행한다(CSV Injection). 탭이나 CR 로 시작하는 경우도 파서가 앞의 공백문자를 버리고
- *    그다음 글자를 첫 글자로 읽으므로 같은 결과가 된다(OWASP 권고).
+ *    그다음 글자를 첫 글자로 읽으므로 같은 결과가 된다. 앞에 **작은따옴표 `'`** 를 세운다(OWASP 권고) —
+ *    전에는 탭을 세웠는데, 탭도 앞 공백으로 버리는 판에서는 수식이 그대로 살아났다.
+ *
+ * 선행 0(`007`·`010-…`)은 건드리지 않는다(결정 2026-09-15) — 엑셀이 숫자로 읽어 0 을 떼는 것은 여는 쪽의 일이고,
+ * 여기서 글자로 박으면 그 값을 다시 읽는 프로그램이 따옴표를 떠안는다.
  *
  * 이 규칙이 두 군데에 따로 적혀 있었고, 고객 목록 쪽 사본이 `\r` 둘 다를 빠뜨린 채
  * "어드민과 동일한 규칙"이라고 주석까지 달고 있었다.
@@ -1996,7 +2098,15 @@ export declare function FileUpload({ onFilesSelected, accept, multiple, disabled
 
 /** @public */
 export declare interface FileUploadProps {
-    /** 파일 선택(드래그·드롭·클릭) 시 호출. 선택된 File[]을 그대로 전달 — 업로드/네트워크는 호출부 책임 */
+    /**
+     * 파일 선택(드래그·드롭·클릭) 시 호출 — 업로드/네트워크는 호출부 책임. accept·multiple 로 거른 뒤 부른다.
+     *
+     * - **비제어(`files` 없음)**: 늘 **지금 보이는 전체 목록**을 넘긴다 — multiple 이면 앞서 고른 것 + 새로 고른 것,
+     *   아니면 새로 고른 하나. `onRemove` 가 없으면 목록에서 뺄 때도 줄어든 전체 목록으로 부른다.
+     * - **제어(`files` 줌)**: **새로 고른 것만** 넘긴다 — 목록에 합치는 일은 부모가 한다(뺄 때는 `onRemove`).
+     *
+     * 이 함수가 던져도 같은 파일을 다시 고를 수 있다(입력 값은 늘 비운다).
+     */
     onFilesSelected?: (files: File[]) => void;
     /** input accept 속성 (예: "image/*", ".pdf,.docx") */
     accept?: string;
@@ -2239,6 +2349,7 @@ export declare function formatPhone(raw: string): string;
 
 /**
  * ISO 문자열을 'store.time.*' i18n 키 기반 상대시간 문자열로 변환.
+ * 시간대 없는 시각 글자는 KST 벽시계 시각으로 읽는다.
  * (예: 방금 전 / N분 전 / N시간 전 / N일 전 …)
  * 빈/유효하지 않은 입력은 빈 문자열을 반환한다.
  */
@@ -2456,7 +2567,9 @@ export declare const hasSel: (v: string | string[] | null | undefined) => boolea
  * 두 (표준발음) 분해배열 A·B가 '음절 구조'에서 달라지는 자리가 있는지.
  * 초성 ㅇ(무음)은 '초성 없음', 종성 0은 '받침 없음'(둘 다 구조상 '비움')으로 본다.
  * 어떤 자리에서 초성 ㅇ 유무 또는 받침 유무가 뒤바뀌면, 자음 '교체'가 아니라 음절 '구조' 차이이므로
- * 청각 변별 오답으로 부적절 → true(제외 대상). 자음↔자음, 모음↔모음 교체는 false.
+ * 청각 변별 오답으로 부적절 → true(제외 대상). 자음↔자음 교체는 false.
+ * 모음은 **활음이 갈리면**(ㅏ↔ㅘ·ㅐ↔ㅙ·ㅑ↔ㅘ) 구조 차이, 활음이 같으면(ㅏ↔ㅓ·ㅑ↔ㅕ) 모음 교체라 false —
+ * 대립쌍 표('음소 구조 같은 단어만', phonemePairSearch)와 같은 함수(vowelGlidesDiffer)로 판정한다.
  */
 export declare function hasStructureContrast(A: Decomp, B: Decomp): boolean;
 
@@ -2546,6 +2659,7 @@ export declare interface IconProps {
      * 아이콘 이름(lucide 이름 또는 파일 경로), 또는 그려 넣을 노드.
      *
      * 이름은 `icon` 이다 — `name` 이 아니다. 주지 않으면 아무것도 그리지 않는다.
+     * `.svg` 경로는 파일 이름이 lucide 이름이면 lucide 로 그린다(`'/images/brand/check.svg'` → lucide `check`, 의도한 동작 — useLucideIcon 참고).
      */
     icon?: ReactNode | string;
     label?: ReactNode;
@@ -2573,7 +2687,7 @@ export declare interface IconProps {
     svgClassName?: string;
     /** 감싸는 `<span>` 의 인라인 스타일. */
     wrapperStyle?: CSSProperties;
-    /** 한 변 픽셀. 크기는 클래스가 아니라 이것으로 정한다. */
+    /** 한 변 픽셀. 크기는 클래스가 아니라 이것으로 정한다. lucide·마스크·이미지(파일 경로) 모두에 적용된다. */
     size?: number;
 }
 
@@ -2683,6 +2797,13 @@ export declare const JUNGSEONG: readonly ["ㅏ", "ㅐ", "ㅑ", "ㅒ", "ㅓ", "
  */
 export declare function kstStartOfDay(year: number, month0: number, day: number): Date;
 
+/**
+ * {@link cellKey} 로 만든 칸 낱말에서 동형어 번호를 뗀 보이는 글자 — `배#2 / 패` → `배 / 패`. 번호가 없으면 그대로.
+ *
+ * @public
+ */
+export declare function labelOfCellKey(key: string): string;
+
 /**
  * 칸 번호 → 그때 보인 낱말. 채점과 **함께 저장한다.**
  *
@@ -2829,7 +2950,11 @@ export declare interface LoaderProps {
     variant?: 'spinner' | 'bar';
     /** 스피너 크기(px 또는 CSS 값). `variant='spinner'`일 때 적용됩니다. */
     size?: number | string;
-    /** 진행률(0–100). `variant='bar'`일 때 적용됩니다. */
+    /**
+     * 진행률(0–100). `variant='bar'`일 때 적용됩니다.
+     * 주지 않거나 `null` 이면 **얼마나 됐는지 모르는(indeterminate)** 막대 — 짧은 채움이 오가고, 낭독기에는 값(aria-valuenow) 없이
+     * "진행 중" 으로만 알린다('동작 줄이기' 에서는 움직이지 않는 전체 폭 막대).
+     */
     progress?: number | null;
     /** 접근성 이름(aria-label). 화면에 글자로 나오지는 않는다. 안 주면 i18n 의 `loader.loading`(기본 'Loading'). */
     label?: string;
@@ -3178,8 +3303,9 @@ export declare type NoisePlayerContextValue = {
 
 /**
  * @public 설정의 소음 비율(배). `noiseRatio` 가 있으면 그것(0~2 로 자름), 없으면 **옛 값에서
- * 들리던 그대로** 옮긴다 — (level/9) ÷ mainVolume 을 0~2 로 자르고 0.1 단위 반올림.
- * mainVolume 이 0 이면 옛 값으로는 비율을 알 수 없어 1.
+ * 들리던 그대로** 옮긴다 — (level/9) ÷ mainVolume 을 **반올림 없이** 0.1~2 로 조인다(말귀 `noiseRatioOfPct` 와 같은 범위).
+ * 전에는 0.1 칸으로 반올림해 옛 소리와 최대 0.05배 달라졌다(2026-09-15 결정). level 0(옛날에 소음이 안 들리던 기록)은
+ * 0 그대로 — 0.1 로 올리면 없던 소음이 생긴다. mainVolume 이 0 이면 옛 값으로는 비율을 알 수 없어 1.
  */
 export declare function noiseRatioOf(settings: Pick<CoreNoiseSettings, 'level' | 'mainVolume'> & {
     noiseRatio?: number;
@@ -3189,11 +3315,14 @@ export declare function noiseRatioOf(settings: Pick<CoreNoiseSettings, 'level' |
 export declare interface NoiseSettingsStore {
     /** 현재 훈련 대상(본인 또는 고객)의 저장된 소음설정. 없으면 null. */
     load: () => Promise<Partial<CoreNoiseSettings> | null>;
-    /** 현재 훈련 대상의 소음설정을 저장(fire-and-forget). */
+    /**
+     * 현재 훈련 대상의 소음설정을 저장(fire-and-forget).
+     * 훈련 팝업은 판 중 변경(슬라이더 끌기 등)을 **멈춘 뒤 300ms 에 마지막 값만** 넘기고, 떠날 때·pagehide 에 남은 값을 즉시 넘긴다.
+     */
     save: (settings: CoreNoiseSettings) => Promise<void> | void;
     /**
      * **판에 실제로 걸린 설정**이 정해지거나 바뀔 때마다 부른다 — 저장 병합 직후,
-     * `noiseOverride` 적용 직후, 판 중 변경마다. 선택.
+     * `noiseOverride` 적용 직후, 판 중 변경마다(저장과 달리 기다리지 않는다). 선택.
      *
      * `save` 와 따로 두는 까닭: `noiseOverride` 가 걸린 판은 저장을 건너뛴다. 앱이 결과마다
      * 그 판의 소음 조건을 함께 기록한다면 `save` 로는 그 값을 못 받는다 — 저장값으로
@@ -3224,10 +3353,17 @@ export declare interface NoiseSettingsTooltipProps {
  * 그대로 잘랐는데(`2026-08-19T16:00:00Z` → `2026.08.19`), 그건 UTC 날짜라 KST 자정~
  * 아침 아홉 시 사이의 값이 전부 하루 전으로 보였다. 이 함수를 쓰는 곳이 전부 그랬다 —
  * 회원의 문의 등록일, 고객 등록일. 날짜만 있는 값(YYYY-MM-DD)은 시각이 없으니
- * 옮길 것도 없어 그대로 둔다.
+ * 옮길 것도 없어 그대로 둔다. 시간대 없는 시각('2026-09-30 20:00:00')은 KST 벽시계 시각으로 읽는다.
  */
 export declare function normalizeDate(input: string | null | undefined): string | undefined;
 
+/**
+ * @public filterSelected 의 속성 섹션을 **지정한 언어(기본: 지금 언어)의 라벨**로 다시 적는다 — 다른 언어·옛 라벨로 저장된 구성을
+ * 열 때, 언어가 바뀐 뒤 상태를 맞출 때 쓴다(칩이 꺼진 채로 보이던 것). 속성 밖의 섹션은 그대로 둔다. 같은 섹션이 두 언어로
+ * 들어 있으면 합친다.
+ */
+export declare function normalizeWordAttributeFilter<T extends Record<string, unknown>>(selected: T, lng?: string): T;
+
 /** @public */
 export declare function NoticeBox({ title, lines, notices, children, variant, dismissible, className, }: NoticeBoxProps): JSX.Element | null;
 
@@ -3249,7 +3385,7 @@ export declare interface NoticeBoxProps {
     children?: ReactNode;
     /** 스타일 변형. `'default'` | `'dashed'` | `'important'` */
     variant?: 'default' | 'dashed' | 'important' | string;
-    /** 닫기(×) 버튼 표시 여부 */
+    /** 닫기(×) 버튼 표시 여부 — `notices` 모드에서도 상자 전체를 닫는다 */
     dismissible?: boolean;
     className?: string;
 }
@@ -3614,7 +3750,7 @@ export declare const PASS_CARD_BG_VARS: {
 };
 
 /** @public */
-export declare function PassCard({ product, showPrice, plan, type, endDate, remainingSeconds, state, bg, bgOnly, textColor, subColor, copyrightColor, logoSrc, label, price, originalPrice, discountLabel, onUse, onRefund, onDelete }: PassCardProps): JSX.Element;
+export declare function PassCard({ product, showPrice, plan, type, endDate, remainingSeconds, endInclusive, state, bg, bgOnly, textColor, subColor, copyrightColor, logoSrc, label, price, originalPrice, discountLabel, onUse, onRefund, onDelete }: PassCardProps): JSX.Element;
 
 /** @public */
 export declare function PassCardBg({ variant }: PassCardBgProps): JSX.Element;
@@ -3701,7 +3837,7 @@ export declare interface PassCardProduct {
     name?: string;
     /** 기간(일). 지정 시 code/name보다 우선. */
     durationDays?: number;
-    /** 가격. 숫자(원 단위) 또는 이미 포맷된 문자열. */
+    /** 가격. 숫자(원 단위) 또는 문자열 — 숫자만 든 문자열('12000')은 '₩12,000' 으로, 이미 포맷된 글자('7,500원')는 '₩7,500' 으로. */
     price?: string | number;
     /** 원가(취소선). 숫자(원 단위) 또는 문자열. */
     originalPrice?: string | number;
@@ -3732,11 +3868,17 @@ export declare interface PassCardProps {
     endDate?: string;
     /**
      * 전환으로 일시정지되어 남은 시간(초)이 알려진 경우에만 지정.
-     * 지정하면 우측 하단에 "사용량%·남은 시간"을 이 값 기준으로 표시하고,
+     * 지정하면 우측 하단에 "사용량%·남은 시간"을 이 값 기준으로 표시하고(`product` 가 없어 전체 기간을 모르면 남은 시간만),
      * 지정 없이 state==='active'면 endDate에서 카드가 스스로 계산한다(pending인데
      * 이 값도 없으면 = 한 번도 안 쓴 새 이용권 → 전체 기간이 그대로 남은 것으로 표시).
      */
     remainingSeconds?: number;
+    /**
+     * 선택. true 면 종료일 **당일(KST)까지** 쓸 수 있는 이용권으로 보고 남은 날에 그 날을 넣는다 — 마지막 날이 "0초 남음·0%" 가
+     * 아니라 "1일 남음" 이 된다(말귀 개인 이용권: 종료일까지 이용). 기본 false(종료일 0시에 끝나는 것으로 센다 — 지금 동작).
+     * `endDate` 로 셀 때만 쓴다(`remainingSeconds` 를 주면 그 값 그대로).
+     */
+    endInclusive?: boolean;
     state?: PassCardState;
     /** @deprecated 읽지 않는다 — 대기 순서는 카드에 그리지 않는다. 넘겨도 화면은 같다. */
     queueIndex?: number;
@@ -3952,8 +4094,10 @@ export declare interface PhonemeSelectBlockProps {
     onSearchEmpty?: () => void;
     searchDisabled?: boolean;
     searchLabel?: string;
+    /** 검색 확인 중 — 검색 단추를 그대로 두고 스피너·aria-busy 로 알린다(누름은 막되 초점은 남는다). */
     searchChecking?: boolean;
     pairMode?: boolean;
+    /** 머리의 "유의사항" 단추(툴팁). **기본 true** — 늘 보이던 단추를 지킨다. false 를 주면 숨는다. */
     showInfoButton?: boolean;
     /** 검색 버튼 바로 위에 표시할 내용(예: 현재 검색 조건 요약 Badge) */
     beforeSearchContent?: ReactNode;
@@ -4154,6 +4298,14 @@ export declare interface PopupListProps<T extends {
 
 /** @public */
 export declare type PopupOptions = {
+    /**
+     * 닫힘 애니메이션(260ms, '동작 줄이기' 면 0)을 시작하고 끝나면 `cb` 를 부른다.
+     *
+     * **창이 그 사이 떠나도(부모가 치워도) `cb` 는 부른다** — `cb` 가 삭제·저장 확정일 수 있어서다(결정 2026-09-15).
+     * 떠난 뒤에 부르면 곤란한 일(상태 되돌리기 등)은 `cb` 안에서 스스로 확인한다.
+     * 닫기(X·ESC·바탕)의 `onClose` 는 이와 달리 떠나면 부르지 않는다.
+     * `cb` 가 던지거나 돌려준 약속이 거절되면(또는 끝난 뒤에도 창이 남아 있으면) 창을 되살린다.
+     */
     animateThen: (cb?: () => void) => void;
     closeWithAnimation: () => void;
 };
@@ -4274,6 +4426,10 @@ export declare function primarySelPart(comp: CompositionFilter | null): 'cho' |
 /**
  * 화면에 렌더된 단어표(.word-table)를 인쇄한다.
  * @page 방향/크기를 임시 주입한 뒤 window.print()를 호출하고, 인쇄 후 정리한다.
+ *
+ * @deprecated WordTablePopup 의 `renderButtons` 가 넘기는 `print`(또는 `useWordTablePrint().print`)를 쓴다.
+ * 이 함수는 앱 화면 전체를 인쇄하며 전역 print CSS 로 `.word-table` 만 남기는데, 화면에 표가 둘이면 둘 다 찍히고
+ * 창·팝업 스타일이 섞인다 — 그쪽은 넘긴 표만 격리 iframe 에서 인쇄한다. 동작은 그대로 두고 개발 모드에서 한 번 알린다.
  * @public
  */
 export declare function printWordTable(orientation?: WordTableOrientation): void;
@@ -4372,11 +4528,13 @@ export declare interface ProgressIndicatorProps {
      */
     variant?: 'numbered' | 'dot';
     /**
-     * 단계가 바뀔 때 낭독기가 스스로 알리게 한다(`role="status"`).
+     * 단계가 바뀔 때 낭독기가 스스로 알리게 한다(`role="status"`). **모든 variant 에서** 된다.
      *
      * 기본은 알리지 않는다 — 점 모드는 그림에 가까워 `role="img"` + 이름표로
      * 두는 편이 조용하다. 사용자가 넘기는 것이 아니라 화면이 저절로 넘어가는
      * 자리(검사 안내)에서는 켜는 편이 낫다.
+     * 점 모드는 뿌리가 알리는 자리가 되고, 번호·모바일 모드는 목록(`role="list"`)을 그대로 두고
+     * 곁에 눈에 안 보이는 알리는 자리를 하나 둔다(목록 안에 두면 목록의 짜임이 깨진다).
      */
     announce?: boolean;
     /**
@@ -4390,7 +4548,10 @@ export declare interface ProgressIndicatorProps {
  *  텍스트 테마(PromoBannerBgTheme)를 부모에 주입하므로 props 없이 렌더하면 된다. @public */
 export declare const PROMO_BANNER_BG_COMPONENTS: Record<PromoBannerBgKey, ComponentType<Record<string, never>>>;
 
-/** @public */
+/**
+ * 배경 고르개 보기 목록. `label` 은 읽는 때의 i18n 언어를 따른다(`promoBannerBg.<key>`, ko 는 한국어 이름 그대로).
+ * @public
+ */
 export declare const PROMO_BANNER_BG_OPTIONS: PromoBannerBgOption[];
 
 /** CSS 커스텀 프로퍼티 키 목록 */
@@ -4698,9 +4859,15 @@ export declare function Rating({ value, onChange, max, readOnly, size, ariaLabel
 
 /** @public */
 export declare interface RatingProps {
-    /** 현재 별점 (0 ~ max). 읽기 전용 모드에서는 소수점(예: 4.5) 허용 */
+    /**
+     * 현재 별점 (0 ~ max). 읽기 전용 모드에서는 소수점(예: 4.5)을 그대로 그린다.
+     * 고르는 모드에서는 **가장 가까운 정수로 반올림해** 그리고 키보드도 그 값에서 옮긴다(3.4 → 별 셋).
+     */
     value: number;
-    /** 값 변경 콜백. 생략 시 읽기 전용 모드로 동작 */
+    /**
+     * 값 변경 콜백. 생략 시 읽기 전용 모드로 동작.
+     * **값이 바뀔 때만** 부른다 — 지금 값과 같은 별을 다시 누르거나 끝에서 화살표를 눌러 머물면 부르지 않는다.
+     */
     onChange?: (value: number) => void;
     /** 별 개수. 기본값 5 */
     max?: number;
@@ -4797,7 +4964,8 @@ export declare interface ReportBlock {
     /**
      * 쪽을 나눌 때 한 덩어리로 다룰 묶음. 표 머리와 그 행들처럼 갈라지면 읽을 수
      * 없는 것들에 같은 값을 준다 — 남은 자리가 모자라면 통째로 다음 장으로 간다.
-     * 묶음 하나가 한 장보다 크면 어쩔 수 없이 블록 단위로 쪼갠다. `section` 이 다르면 같은 값이어도 한 묶음이 아니다.
+     * 묶음 하나가 한 장보다 크면 어쩔 수 없이 블록 단위로 쪼갠다 — 이때는 앞 장에 남은 자리부터 이어 채운다.
+     * `section` 이 다르면 같은 값이어도 한 묶음이 아니다.
      */
     group?: string;
 }
@@ -4809,12 +4977,14 @@ export declare interface ReportBlock {
  * 순서대로 채우다 넘치면 다음 장으로 넘긴다. 장마다 머리(제목 + 로고)와
  * 바닥(로고·저작권 + 쪽 번호)이 반복된다.
  *
- * 재는 방식이라 글꼴이 늦게 오거나 이미지가 나중에 뜨면 쪽이 밀릴 수 있다.
- * 다시 재는 때는 블록들의 `id`·`section`·`group` 구성이나 장 규격(`pageWidth`·`pageHeight`·`margin`)이 바뀔 때와
- * 처음 그릴 때(숨겨져 있다 보이게 될 때 포함)뿐이다 —
- * 같은 구성으로 다시 그리거나 `content` 만 바뀌어서는 다시 재지 않는다(렌더마다 재면
- * 재기 → 쪽 나눔 → 렌더가 끝없이 돈다). 글꼴·이미지가 다 온 뒤 다시 재야 하면
- * `key` 를 바꿔 새로 붙인다.
+ * 다시 재는 때는 블록들의 `id`·`section`·`group` 구성이나 장 규격(`pageWidth`·`pageHeight`·`margin`)이 바뀔 때,
+ * 처음 그릴 때(숨겨져 있다 보이게 될 때 포함), 그리고 **블록의 높이가 바뀔 때**다 — 재기 사본 블록마다
+ * ResizeObserver 를 걸어 `content` 가 바뀌어 높이가 달라지거나 글꼴·이미지가 늦게 와 커지면 다시 나눈다
+ * (여러 번 울려도 다음 틀(rAF)에 한 번). 렌더마다 재지는 않는다(재기 → 쪽 나눔 → 렌더가 끝없이 돈다).
+ * ResizeObserver 가 없는 환경에서는 높이만 바뀐 것은 못 알아채므로 `key` 를 바꿔 새로 붙인다.
+ *
+ * 쪽 나눔: 블록을 순서대로 채우다 넘치면 다음 장. `group` 이 남은 자리에 안 들어가면 통째로 다음 장으로 가는데,
+ * 묶음이 **한 장보다 크면** 어차피 쪼개야 하므로 앞 장에 남은 자리부터 이어 채운다.
  *
  * 화면에 그린 쪽 수는 다른 도구로 만든 PDF 와 다를 수 있다. 같은 내용을 그리는
  * 높이가 서로 달라서인데, 쪽 수까지 맞춰야 하면 양쪽 본문 높이를 견줘야 한다.
@@ -4971,6 +5141,19 @@ export declare function resumeAudioMeter(): void;
  */
 export declare function reviewCells<T>(items: readonly T[], marks: Record<string, ScoreMark | null | undefined>): T[];
 
+/**
+ * 새로 만들 복습표에 **함께 저장할 메타** — 맨 처음 원본 표 id 와 이번이 몇 번째 복습인지.
+ *
+ * `reviewOf` 는 원래 표가 복습표면 그 표의 `reviewOf` 를, 아니면 원래 표의 `id` 를 잇는다(둘 다 없으면 `undefined`).
+ * `reviewRound` 는 {@link reviewTableName} 이 이름에 적는 회차와 같다(1 = 첫 복습).
+ *
+ * @public
+ */
+export declare function reviewMeta(source: ReviewSource): {
+    reviewOf: string | undefined;
+    reviewRound: number;
+};
+
 /** @public 다음 훈련으로 무엇을 만들 수 있나. */
 export declare interface ReviewSetPlan {
     /** 훈련 플랜에 담을 것 — 문장 유형 */
@@ -5005,14 +5188,42 @@ export declare interface ReviewSetRef {
     pending: number;
 }
 
+/**
+ * 복습할 원래 표 — 이름과, 있으면 **복습 메타**.
+ *
+ * 이름만으로는 회차를 틀리게 읽을 때가 있다. `수업 3차` 라는 표의 복습(`수업 3차 복습 09.15`)과
+ * `수업` 의 3차 복습(`수업 3차 복습 09.15`)이 **같은 이름**이라, 다시 복습하면 둘 다 `수업 4차 복습` 이 됐다.
+ * 복습표를 저장할 때 {@link reviewMeta} 의 값을 함께 남겨 두면 이름을 파싱하지 않고 그 값을 쓴다.
+ * 메타가 없는 옛 표는 지금처럼 이름을 파싱한다.
+ *
+ * @public
+ */
+export declare interface ReviewSource {
+    /** 표 이름 */
+    name: string;
+    /** 표 id — 이 표가 원본이면 복습표의 `reviewOf` 가 된다 */
+    id?: string;
+    /** 이 표가 복습표면 **맨 처음 원본 표**의 id */
+    reviewOf?: string | null;
+    /**
+     * 이 표가 몇 번째 복습인가(1부터). `0` 은 "복습표가 아니다" — 이름이 `… 복습 09.01` 꼴이어도 꼬리로 떼지 않는다.
+     * 없으면(`undefined`·`null`) 옛 표로 보고 이름을 파싱한다.
+     */
+    reviewRound?: number | null;
+}
+
 /**
  * 복습표 이름.
  *
  * 원래 이름을 앞에 두어 **목록에서 나란히 붙어 보이게** 한다(대개 이름순·최신순으로 본다).
  * 날짜를 붙이는 것은 같은 표를 여러 번 돌리기 때문이다 — 없으면 같은 이름이 쌓여
  * 어느 것이 이번 것인지 알 수 없다.
+ *
+ * 이름 형식(`바탕 [N차 ]복습 MM.DD`)은 저장된 이름·파싱과 맞추느라 바꾸지 않는다.
+ * 원래 표를 {@link ReviewSource} 로 넘기면 복습 메타(`reviewRound`)를 이름 파싱보다 먼저 쓴다 —
+ * 새 복습표를 저장할 때는 {@link reviewMeta} 의 값을 함께 남긴다. 글자만 넘기면 지금처럼 이름을 파싱한다.
  */
-export declare function reviewTableName(original: string, today: Date): string;
+export declare function reviewTableName(original: string | ReviewSource, today: Date): string;
 
 /**
  * 도넛 링 차트 — 전체 대비 완료 비율을 원형 호로 표현.
@@ -5048,7 +5259,7 @@ export declare interface RingChartProps {
     strokeWidth?: number;
     /** 중앙 숫자 아래 라벨 (기본: "%") */
     label?: string;
-    /** 중앙 텍스트(숫자+라벨) 전체 숨김 (기본: false) */
+    /** 중앙 텍스트(숫자+라벨) 전체 숨김 (기본: false — 단 `titleKey` 섹션의 `size="small"` 은 기본 숨김이고, `false` 를 명시하면 그린다) */
     hideCenter?: boolean;
     /** 중앙 숫자는 유지하고 아래 라벨("%")만 숨김 (기본: false) */
     hideLabel?: boolean;
@@ -5184,7 +5395,10 @@ export declare interface ScoreRecord {
     tableId: string | null;
     /** 칸 번호 → 표시 */
     marks: Record<string, ScoreMark>;
-    /** 칸 번호 → 그때 보인 낱말. 옛 기록에는 없을 수 있다 */
+    /**
+     * 칸 번호 → 그때 보인 낱말. 옛 기록에는 없을 수 있다.
+     * `cellKey` 로 동형어 번호까지 적어 두면(`배#2`) `weakItems` 가 동형어를 따로 센다.
+     */
     labels: Record<string, string>;
 }
 
@@ -5334,6 +5548,10 @@ export declare function SegmentedControl(props: SegmentedControlProps): JSX.Elem
 export declare interface SegmentedControlProps {
     options?: SegmentedOption[];
     value?: string;
+    /**
+     * 누른 칸의 key 로 불린다. **이미 고른 칸을 다시 눌러도 부른다**(화살표가 같은 칸에 머물 때도) — 다시 누름을
+     * "새로 고침" 으로 쓰는 자리가 있어 지금 동작을 지킨다. Dropdown·Rating·Tabs 는 값이 바뀔 때만 부른다.
+     */
     onChange?: (v: string) => void;
     className?: string;
     /** 버튼 높이 — Button과 동일한 숫자 size (32 / 40 / 48) */
@@ -5473,6 +5691,7 @@ export declare interface ShortcutBadgeProps {
      * **`transform` 으로 키우지 말 것** — 배지가 모서리에 걸치는 `translate` 와 같은
      * 속성이라 한쪽이 다른 쪽을 통째로 지운다. 이 prop 은 `--shortcut-badge-scale` 로
      * 내려가고, 자리와 배율은 CSS 한 곳에서 합쳐 적힌다.
+     * `anchor="static"` 에서는 키캡 크기·글자에 곱해 흐름 안에서 차지하는 자리도 함께 커진다.
      */
     scale?: number;
     className?: string;
@@ -6018,13 +6237,18 @@ export declare function summarize(marks: Record<string, ScoreMark | null | undef
  * 정렬은 세 겹이다. 정답률이 낮은 것이 먼저이되, **같은 정답률이면 여러 번 푼 것을
  * 앞에 둔다** — 한 번 틀린 것과 다섯 번 내리 틀린 것은 무게가 다르다. 그래도 같으면
  * 글자순으로 못 박는다(그러지 않으면 다시 읽을 때마다 차례가 흔들려 보던 줄을 놓친다).
+ *
+ * **"최근"(latestCorrect·latestAt·lastSelected·setIds 앞자리)은 `answeredAt` 으로 가린다.** 시각이 같은 행끼리는
+ * 둘 다 `id` 가 있으면 `id` 가 큰 쪽(숫자는 수 크기, 글은 사전순)이 최근이고, 그렇지 않으면 **넘어온 배열에서
+ * 뒤에 있는 쪽**이 최근이다 — 즉 `id` 없이 넘길 때는 **시간순(옛것 먼저)** 으로 넘겨야 같은 시각의 앞뒤가 맞다.
+ * (최신 먼저 넘기면 같은 시각 행의 최근이 뒤집힌다. 시각이 다른 행은 차례와 상관없이 맞다.)
  */
 export declare function summarizeMisses(records: readonly TrainingResultRecord[]): MissSummary;
 
 /**
  * 화면 위쪽에 놓이는 한 줄 요약 — "지금 다루고 있는 대상"을 이름표와 값으로 늘어놓는다.
  *
- * 값 길이가 제각각이라 균등 그리드에 앉힌다. 긴 값은 칸을 밀어내지 않고 말줄임된다.
+ * 값 길이가 제각각이라 균등 그리드에 앉힌다. 긴 값은 칸을 밀어내지 않고 말줄임된다 — 글자·수 값이면 `title` 로 전체 값을 단다.
  *
  * 값의 서식은 부르는 쪽이 정해 넘긴다 — 빈 값을 `-` 로 적을지, 날짜를 어떻게 쓸지,
  * 여러 값을 한 칸에 묶을지(`오른손 / NC / 연구실 내`)는 화면마다 다르다.
@@ -6325,7 +6549,7 @@ export declare type TableProps<T extends {
     onDrop?: (e: DragEvent_2<HTMLDivElement>) => void;
     /** 펼쳐진 행에 렌더할 콘텐츠. expandedId와 함께 사용 */
     renderExpandedRow?: (item: T) => ReactNode;
-    /** 현재 펼쳐진 행의 id */
+    /** 현재 펼쳐진 행의 id(여럿이면 Set). 글자로 견준다 — '5' 와 5 는 같은 줄. */
     expandedId?: string | number | Set<string | number> | null;
 };
 
@@ -6338,6 +6562,15 @@ declare interface TableSettingsSetters {
     setShowDivLine: (v: boolean) => void;
 }
 
+/** `useTableSort` 의 선택 인자. @public */
+export declare interface TableSortOptions<K extends string> {
+    /** 머리를 눌러 정렬이 바뀔 때 바뀐 정렬로 불린다 — 쪽을 따로 들고 있는 표가 첫 쪽으로 돌아가는 자리 등. */
+    onSortChange?: (sort: {
+        key: K;
+        asc: boolean;
+    }) => void;
+}
+
 /** 표 한 개에 대한 흐름 — 같은 표를 여러 번 돌렸을 때 나아지고 있는가. */
 export declare interface TableTrend {
     tableName: string;
@@ -6374,6 +6607,7 @@ export declare function Tabs({ items, value, onChange, className, size }: TabsPr
 export declare interface TabsProps {
     items?: TabItem[];
     value?: string;
+    /** 고른 탭의 key 로 불린다. **값이 바뀔 때만** — 지금 탭을 다시 누르거나 화살표가 지금 탭에 머물면 부르지 않는다. */
     onChange?: (key: string) => void;
     className?: string;
     /** 탭 버튼 높이 — SegmentedControl과 동일 체계 (32 / 40 / 48) */
@@ -6554,6 +6788,11 @@ export declare function Toggle({ checked, onChange, disabled, label, ariaLabel,
  * @public 긍정형 다중 토글 섹션의 filterSelected 갱신 헬퍼 — 단어표·대립쌍표 공용.
  * '전체'(FILTER_ALL_VALUE)면 해당 섹션 해제, 그 외엔 값 토글, 남은 값이 없으면 key 자체를 제거한다.
  * (FilterPanel은 로케일과 무관하게 FILTER_ALL_VALUE를 방출하므로 t('common.all', '전체')과 비교하면 안 된다.)
+ *
+ * **속성 섹션(등급·음절 수·품사·어종)은 값을 코드로 견준다** — prev 에 다른 언어·옛 라벨로 든 같은 섹션이 있으면 그것을 읽어
+ * `sectionLabel` 의 언어 라벨로 합쳐 적는다. 전에는 한국어로 저장된 '품사' 가 영어 화면의 'Part of Speech' 옆에 따로 남아,
+ * 칩은 꺼진 채로 보이는데 필터는 걸려 있었고 끌 길이 없었다. 반환 모양(라벨 열쇠·라벨 값)은 그대로다.
+ * 저장할 때는 `toWordAttributeFilterCodes` 로 코드 모양을 함께 담는다.
  */
 export declare function toggleAttributeFilter(prev: Record<string, string[]>, value: string, sectionLabel: string): Record<string, string[]>;
 
@@ -6600,6 +6839,7 @@ export declare function toKstHm(when?: string | number | Date | null): string;
  * 문자열을 낸다 — 연·월·일 경계 표본으로 대조했다.)
  *
  * 빈 값·못 읽는 값은 빈 문자열이다. 0(epoch)은 유효한 값이라 그대로 옮긴다.
+ * 시간대 없는 시각 글자('2026-09-30 20:00:00')는 KST 벽시계 시각으로 읽는다(날짜만 있는 글자는 그대로).
  */
 export declare function toKstYmd(when?: string | number | Date | null): string;
 
@@ -6771,7 +7011,7 @@ export declare function TopBanner({ children, interval, dotTone, className, 'ari
 export declare interface TopBannerProps {
     /** 로테이션할 슬라이드들 — 각 자식이 슬라이드 한 장 */
     children: ReactNode;
-    /** 자동 롤링 간격(ms). `0`이면 자동 롤링 안 함 */
+    /** 자동 롤링 간격(ms). `0`이면 자동 롤링 안 함. OS '동작 줄이기' 가 켜져 있어도 자동 롤링하지 않는다(점으로 넘긴다). */
     interval?: number;
     /**
      * 슬라이드별 인디케이터 톤. 슬라이드 배경이 어두우면 `'light'`(흰 점),
@@ -6881,6 +7121,12 @@ export declare function toTrainingText(value: unknown): string;
  */
 export declare function toUserErrorMessage(msg: string): string;
 
+/**
+ * @public filterSelected(라벨 열쇠·라벨 값, 어느 언어든 섞여 있어도) → **코드 모양**. 저장할 때 쓴다.
+ * 속성 섹션(등급·음절 수·품사·어종)만 담고, 그 밖의 섹션(초성·선택·단어 입력 등)은 뺀다. 못 읽는 값은 버린다.
+ */
+export declare function toWordAttributeFilterCodes(selected: Record<string, unknown> | null | undefined): WordAttributeFilterCodes;
+
 /** 타입 칩 호버 → TrainingTooltip 표시까지의 지연(ms). 말귀자료실 카드와
  *  훈련설정 페이지가 동일한 호버 프리뷰 동작을 각자 구현하고 있어 공유한다.
  *  @public */
@@ -6953,11 +7199,11 @@ export declare interface TrainingBlockButtonProps {
     completedIds?: Set<string>;
     /** 선택 상태 ID Set. 포함된 항목(완료가 아닌 것)에 체크 배지를 표시 — 완료와 같은 배지이고, `hideCheckBadge` 면 숨는다. */
     selectedIds?: Set<string>;
-    /** 호버 시 표시할 문제/문장 텍스트. 제공 시 DescriptionTooltip 으로 렌더. */
+    /** 호버 시 표시할 문제/문장 텍스트. `useDescriptionTooltip` 이면 DescriptionTooltip 으로, 아니면 블록의 `title`(가리키면 뜨고 낭독기엔 설명)로 준다. */
     tooltipText?: string | string[];
     /** true 이면 호버 시 DescriptionTooltip 으로 문제 텍스트를 표시. 기본값 false. */
     useDescriptionTooltip?: boolean;
-    /** 제공 시 hover 중 뱃지 자리에 X 버튼 표시 — 클릭하면 호출됨. */
+    /** 제공 시 뱃지 자리에 X 버튼 표시 — 가리킬 수 있는 기기는 hover 중에만, 터치 기기(hover: none)는 늘. 클릭하면 호출됨. */
     onRemove?: () => void;
     /** true 이면 완료/선택 체크 뱃지를 표시하지 않음 */
     hideCheckBadge?: boolean;
@@ -7111,6 +7357,19 @@ export declare interface TrainingCategoryConfig {
     trainingTypes?: TrainingType[];
 }
 
+/** @public TrainingPagePopup `onComplete` 인자 */
+export declare type TrainingCompleteResult = {
+    correct: number | null;
+    total: number | null;
+    /** 이 창에서 몇 번째 판인지(1부터) */
+    attempt?: number;
+    /** 다시하기 전 판들의 결과(앞 판부터) */
+    previousAttempts?: Array<{
+        correct: number | null;
+        total: number | null;
+    }>;
+};
+
 export declare interface TrainingCompletionEntry {
     category: 'sentence' | 'word';
     trainingType: string;
@@ -7281,6 +7540,7 @@ export declare type TrainingPagePopupBottomProps = {
     stepIndex?: number;
     stepCount?: number;
     pageIndex?: number;
+    /** 쪽 수. 0(쪽이 없음)이어도 '결과보기'(완료) 단추는 보이고, '다음 문제'(쪽 이동)만 숨는다. 기본 1. */
     pageCount?: number;
 };
 
@@ -7309,11 +7569,9 @@ export declare type TrainingPagePopupProps = {
     stepIndex?: number;
     stepCount?: number;
     onBack?: () => void;
-    /** 완료 시 호출. 결과 팝업이 계산한 정답/전체 문항 수를 함께 전달(호출부가 무시해도 무방하도록 옵셔널 인자). */
-    onComplete?: (result?: {
-        correct: number | null;
-        total: number | null;
-    }) => void;
+    /** 완료 시 호출. 결과 팝업이 계산한 정답/전체 문항 수를 함께 전달(호출부가 무시해도 무방하도록 옵셔널 인자).
+     *  `attempt` 는 이 창에서 몇 번째 판인지(1부터, 다시하기마다 +1), `previousAttempts` 는 다시하기 전 판들의 정답/전체 — 전에는 1회차 결과가 어디에도 남지 않았다. */
+    onComplete?: (result?: TrainingCompleteResult) => void;
     onNext?: () => void;
     onSettings?: () => void;
     /** 좌측 하단 훈련 설정 버튼 + 오디오 미터 토글 표시 여부. 기본 true — 모든 훈련에서 노출되며,
@@ -7325,6 +7583,7 @@ export declare type TrainingPagePopupProps = {
         panelRef: RefObject<PanelElement | null>;
         setResultOverlay: Dispatch<SetStateAction<unknown>>;
     }) => ReactNode);
+    /** 대화상자 이름(낭독기가 읽는 이름). 주면 title·label·시나리오 제목보다 이긴다 — 보이는 제목과 다른 이름이 필요할 때. 없으면 보이는 제목. */
     ariaLabel?: string;
     label?: string;
     buildResults?: (answers: Record<string, unknown>, meta?: Record<string, unknown>) => unknown;
@@ -7355,6 +7614,8 @@ export declare type TrainingPagePopupProps = {
         contextsLength?: number | null;
         onReplay?: () => void;
         onClose?: () => void;
+        /** 결과를 아직 계산하는 중(비동기 buildResults 등) — true 인 동안 '완료' 를 막아야 한다. 기본 결과 창(TrainingResultPopup)은 그대로 받아 막는다. */
+        pending?: boolean;
     }) => ReactNode;
 };
 
@@ -7421,6 +7682,11 @@ declare interface TrainingResultPopupProps {
     onClose?: () => void;
     /** true면 portal 없이 부모 컨테이너 안에 제자리 렌더 (목업/데모용) */
     inline?: boolean;
+    /**
+     * 결과를 아직 계산하는 중인가. true 인 동안 '완료' 단추를 막고(aria-disabled, 누르거나 Esc 로 닫아도 기록하지 않음)
+     * 까닭 문구를 보인다 — 결과 없이 완료하면 문항 수(total)가 비어 기록됐다. TrainingPagePopup 이 넘긴다. 기본 false.
+     */
+    pending?: boolean;
 }
 
 /**
@@ -7447,6 +7713,11 @@ declare interface TrainingResultPopupProps {
  * 소요가 있다) · **세션 시간**(둘 다 없다). 무엇을 볼지는 읽는 쪽이 정한다.
  */
 export declare interface TrainingResultRecord {
+    /**
+     * 행 식별자(선택). `answeredAt` 이 같은 행(한 판을 한꺼번에 저장해 시각이 같은 행)의 **앞뒤를 가르는 데만** 쓴다 —
+     * 숫자면 수가 큰 쪽, 글이면 사전순으로 뒤인 쪽이 최근이다. 없으면 넘어온 배열에서 뒤에 있는 쪽이 최근이다.
+     */
+    id?: string | number | null;
     answeredAt: string;
     trainingType: string;
     /** 문항 식별자 — 코드가 있는 유형은 코드, 없는 유형(낱말)은 낱말 자체 */
@@ -7716,6 +7987,12 @@ export declare type TrainingWordCardItem = {
     subLabel?: string;
     colloquialLabel?: string;
     homonum?: number;
+    /**
+     * 이미지 없이 **글자 카드**로 보인다(이미지를 청하지 않고, `hideLabel` 이어도 글자를 그림 자리에 크게 보인다).
+     * 안 주면 단어 풀(setWordPool)이 불려 있고 그 풀에 없는 낱말일 때 저절로 글자 카드다 — 받침·자음 탈락의 만든 음절('다'·'애')처럼
+     * 사전에 없는 글자는 이미지가 있을 수 없다. `false` 면 풀에 없어도 이미지를 청한다. `image` 를 직접 주면 그것을 쓴다.
+     */
+    textOnly?: boolean;
     [k: string]: unknown;
 };
 
@@ -7799,6 +8076,8 @@ export declare function uncoveredLabels(recommendations: readonly Recommendation
  *
  * 여러 장을 동시에 띄우려면 `.update-alert-stack`으로 감싼다 — 낱장은 스스로
  * fixed로 붙지만 스택 안에서는 흐름 배치가 되어 아래로 쌓인다.
+ * 따로 놓인 낱장과 스택(또는 낱장 여럿)이 함께 뜨면 문서 순서대로 서로 아래로 비켜 쌓인다(겹치지 않는다).
+ * 층은 창(Popup·Dialog) 위 — 창 위에서도 알림을 읽고 닫을 수 있다(`--z-alert`).
  *
  * @public
  */
@@ -7826,11 +8105,11 @@ declare interface UpdateAlertProps {
 export declare function useAnchoredMenu<Trigger extends HTMLElement = HTMLElement, Menu extends HTMLElement = HTMLElement>({ computeStyle, onScroll, onResize, ignoreOutsideClickSelector, }: UseAnchoredMenuOptions): UseAnchoredMenuResult<Trigger, Menu>;
 
 export declare interface UseAnchoredMenuOptions {
-    /** 트리거의 getBoundingClientRect()로부터 메뉴에 적용할 style을 계산 */
-    computeStyle: (triggerRect: DOMRect) => CSSProperties;
+    /** 트리거의 getBoundingClientRect()로부터 메뉴에 적용할 style을 계산. 둘째 인자는 트리거 요소(층 계산 `anchoredMenuZIndex` 등에 쓴다) */
+    computeStyle: (triggerRect: DOMRect, trigger: HTMLElement) => CSSProperties;
     /** 열려있는 동안 스크롤 발생 시 동작 (메뉴 내부 스크롤은 항상 무시) — 기본 'close' */
     onScroll?: 'close' | 'reposition' | 'ignore';
-    /** 열려있는 동안 윈도우 리사이즈 발생 시 동작 — 기본 'close' */
+    /** 열려있는 동안 윈도우 리사이즈·기기 회전(orientationchange) 발생 시 동작 — 기본 'close' */
     onResize?: 'close' | 'reposition' | 'ignore';
     /** 바깥클릭 판정에서 제외할 CSS selector (예: 메뉴 안에 중첩 포탈되는 다른 드롭다운) */
     ignoreOutsideClickSelector?: string;
@@ -7869,9 +8148,12 @@ export declare function useCacheManagement(onToast?: (msg: string) => void): {
 
 /**
  * "현재 보고 있는 연/월" 상태 + 이전/다음 달 이동. DatePicker의 달력 네비게이션에서 쓴다.
+ *
+ * @param value 고른 날 'YYYY-MM-DD'. 비었으면 오늘의 달을 본다.
+ * @param today 선택. '오늘' 로 쓸 'YYYY-MM-DD'(로컬 앱·SSR). 없거나 꼴이 틀리면 KST 오늘.
  * @public
  */
-export declare function useCalendarMonth(value: string): UseCalendarMonthResult;
+export declare function useCalendarMonth(value: string, today?: string): UseCalendarMonthResult;
 
 export declare interface UseCalendarMonthResult {
     viewY: number;
@@ -7885,6 +8167,9 @@ export declare interface UseCalendarMonthResult {
  * TextField의 `suggestions` 옵션이 쓰는 자동완성 콤보박스 상태/키보드 로직.
  * 순수 입력(값 관리)과 분리해서, 자동완성이 필요 없는 TextField 사용처는
  * 이 훅의 상태가 전혀 관여하지 않는다(항상 호출되지만 open은 기본 false로 시작).
+ *
+ * 한글 조합 중에는 걸리는 후보가 0 건이 되어도 직전 목록을 유지한다 — 입력칸에 `handleCompositionStart`·
+ * `handleCompositionEnd` 를 걸어야 한다(TextField 는 건다). 걸지 않으면 지금처럼 매 값마다 다시 거른다.
  * @public
  */
 export declare function useComboboxSuggestions({ value, onChange, suggestions, openOnFocus, }: {
@@ -7902,13 +8187,19 @@ export declare function useComboboxSuggestions({ value, onChange, suggestions, o
     handleInput: () => void;
     handleKeyDown: (e: KeyboardEvent_2<HTMLInputElement | HTMLTextAreaElement>) => void;
     handleSelect: (item: string) => void;
+    /** 입력칸의 onCompositionStart 에 건다 — 조합 중에는 걸리는 후보가 0 건이 되어도 직전 목록을 둔다 */
+    handleCompositionStart: () => void;
+    /** 입력칸의 onCompositionEnd 에 건다 — 조합이 끝나면 목록을 다시 계산한다 */
+    handleCompositionEnd: () => void;
 };
 
 /**
  * 오늘/어제 훈련 선택을 (user, 날짜) 결정적 시드로 계산하는 훅(영속 저장 없음).
  *
- * - resolveSelection은 시드 기반이라 기기/세션 무관 동일 결과
- * - 데이터 미로딩 시 ensureTrainingDataLoaded() 대기 후 재계산
+ * - resolveSelection은 (사용자, 날짜, 유형) 시드 기반이라 기기/세션 무관 동일 결과. 유형마다 시드가 따로라 한 유형 자료가
+ *   바뀌어도 다른 유형 세트는 그대로
+ * - 오늘 세트는 후보가 충분하면 어제 세트와 겹치지 않는다(어제 보기는 어제 실제로 뜬 세트와 같다)
+ * - 데이터 미로딩 시 ensureTrainingDataLoaded() 대기 후 재계산(받는 중에는 새로 부르지 않는다)
  * - 폴링(250ms): 훈련 데이터가 비동기로 채워질 때까지 재시도
  */
 /**
@@ -8125,8 +8416,8 @@ export declare function usePasswordChange(onChangePassword?: (current: string, n
  * 한곳에 둔다 — 두 곳에 따로 두면 한쪽만 고쳐져 같은 숙제가 화면마다 다른 날짜로
  * 읽히게 된다.
  *
- * 날짜 경계가 아니라 24시간 단위로 센다(어제 23시는 오늘 01시에 "0일 전"). 숙제는
- * "며칠쯤 됐나"를 가늠하는 용도라 이 정도로 충분하고, 시간대 처리도 들어가지 않는다.
+ * **KST 달력날** 로 센다(사용자 결정 2026-09-15) — 어제 23시(KST)에 온 숙제는 오늘 01시에 "어제". 기기 시간대와 무관하다
+ * (해외 기기도 한국 날짜). 전에는 24시간 단위라 같은 숙제가 "오늘"로 읽혔다. 앞날(시계 차이)은 "오늘".
  */
 export declare function useRelativeDay(): (iso?: string | null) => string;
 
@@ -8190,8 +8481,24 @@ export declare function useTablePaging<T>(rows: readonly T[], resetOn?: unknown,
     setPage: Dispatch<SetStateAction<number>>;
 };
 
-/** 머리행 정렬 상태 — 같은 칸을 다시 누르면 방향이 뒤집힌다 @public */
-export declare function useTableSort<K extends string>(): {
+/**
+ * 머리행 정렬 상태 — 같은 칸을 다시 누르면 방향이 뒤집힌다.
+ *
+ * **정렬이 바뀌면 첫 쪽으로** — `useTablePaging` 의 `resetOn` 에 돌려받은 `정렬` 을 그대로 넣는다.
+ * `정렬` 은 누를 때만 새 객체가 되므로(렌더마다 새로 만들지 않는다) 그 자체가 열쇠다. 쪽을 따로 들고 있으면 `onSortChange` 에서 되돌린다.
+ *
+ * `sortRows(rows, 값)` 은 지금 정렬로 줄을 세운 **새 배열**을 준다(정렬이 없으면 받은 배열 그대로) — `칸순`(숫자는 수로,
+ * 한글·영문은 사람 차례) 으로 견주고 **빈 값(null·undefined·'')은 오름·내림 모두 맨 뒤**(ListPopup 과 같은 규칙).
+ *
+ * @example
+ * const { 정렬, 칸, sortRows } = useTableSort<'name' | 'joined'>()
+ * const 세운줄 = useMemo(() => sortRows(rows, (r, key) => r[key]), [rows, sortRows])
+ * const { pageRows, pageSizeProps, paginationProps } = useTablePaging(세운줄, 정렬)   // 정렬이 바뀌면 첫 쪽
+ * <Table fields={[칸('이름', 'name'), 칸('가입일', 'joined')]} … />
+ *
+ * @public
+ */
+export declare function useTableSort<K extends string>(opts?: TableSortOptions<K>): {
     정렬: {
         key: K;
         asc: boolean;
@@ -8201,6 +8508,7 @@ export declare function useTableSort<K extends string>(): {
         sortDir: "desc" | "asc" | null;
         onClick: () => void;
     };
+    sortRows: <R>(rows: readonly R[], 값: (row: R, key: K) => unknown) => readonly R[];
 };
 
 /**
@@ -8439,7 +8747,7 @@ export declare interface UseWordTablePrintResult {
     print: () => void;
     /** 새 탭에 단어표를 열어 사용자가 직접 인쇄/저장하게 한다. */
     openNewWindow: () => void;
-    /** 단어표를 정적 HTML 파일로 다운로드한다. */
+    /** 단어표를 정적 HTML 파일로 다운로드한다. 파일명이 비면(걸러 내고 남는 글자가 없으면) 기본 이름('단어표'). */
     downloadHtml: () => void;
 }
 
@@ -8568,7 +8876,14 @@ export declare function waveBarVal(a: number): number;
 
 /** 낱말 하나에 대해 쌓인 성적. */
 export declare interface WeakItem {
+    /** 보이는 낱말 — 동형어 번호를 뗀 글자(`배`, `배 / 패`) */
     label: string;
+    /**
+     * 묶은 열쇠 — 저장된 칸 낱말 그대로. 동형어 번호가 저장된 기록이면 `배#2` 처럼 번호가 붙고,
+     * 없는 옛 기록이면 `label` 과 같다. 같은 `label` 이 둘 이상 나올 수 있으니 줄 열쇠로는 이것을 쓴다.
+     * `weakItems` 는 늘 채운다 — 선택 필드인 것은 이 모양을 손으로 짓는 쪽(시험 등)을 깨지 않으려는 것뿐이다.
+     */
+    key?: string;
     /** 이 낱말을 매긴 횟수 */
     tried: number;
     o: number;
@@ -8591,6 +8906,9 @@ export declare interface WeakItem {
  *
  * **낱말이 안 남은 옛 기록은 건너뛴다.** 칸 번호로 표를 되짚으면 그 표가 그동안 바뀌었을 때
  * 엉뚱한 낱말의 기록이 된다 — 조용히 틀리느니 빼는 편이 낫다.
+ *
+ * **동형어는 저장된 낱말에 번호가 있을 때만 따로 묶는다**(`배#1`·`배#2`, `cellKey`). 번호 없이 저장된 옛 기록은
+ * 지금처럼 글자로 묶는다 — 그래서 같은 '배' 가 옛 기록 한 줄·번호 있는 기록 한 줄로 나뉘어 보일 수 있다.
  */
 export declare function weakItems(records: readonly ScoreRecord[]): WeakItem[];
 
@@ -8653,6 +8971,17 @@ export declare const WORD_TABLE_PAPER: Record<WordTableOrientation, {
 /** 어종(단어 유형) 약호 → 전체 표기. 데이터의 Class 컬럼은 축약형('고유'/'한자'/'외래'/'혼종')을 쓴다. */
 export declare const WORD_TYPE_LABEL: Record<string, string>;
 
+/**
+ * @public 공용 속성 필터를 **언어와 무관한 코드**로 담은 모양 — 저장(DB config·로컬 저장소)용.
+ * 예: `{ grade: ['1', '2'], syllables: ['5+'], pos: ['noun'], wordType: ['sino'] }`
+ */
+export declare type WordAttributeFilterCodes = Partial<Record<WordAttributeSectionCode, string[]>>;
+
+/**
+ * @public 코드 모양 → 지정한 언어(기본: 지금 i18n 언어)의 **라벨 filterSelected**. FilterPanel 의 selected 로 그대로 쓴다.
+ */
+export declare function wordAttributeFilterFromCodes(codes: WordAttributeFilterCodes | null | undefined, lng?: string): Record<string, string[]>;
+
 /**
  * 등급/음절수/품사/어종 필터의 공용 i18n 키+맵.
  * 단어표(useWordSearch)·대립쌍표(useWordPairsSearch)·단어훈련(useWordTrainingFilter)이
@@ -8669,6 +8998,9 @@ export declare interface WordAttributeFilterKeys {
     typeMap: Record<string, string>;
 }
 
+/** @public 공용 속성 필터 섹션 코드 */
+export declare type WordAttributeSectionCode = 'grade' | 'syllables' | 'pos' | 'wordType';
+
 /** 정답 단어 구성 선택 상태 (정답 단어에만 적용 — 오답은 대립 관계로 결정) */
 export declare interface WordComposition {
     cho: string | null;
@@ -8869,9 +9201,15 @@ export declare function WordSearchResultBlock({ titleIcon, resultCount, resultUn
 /** @public */
 export declare interface WordSearchResultBlockProps {
     titleIcon?: string;
+    /**
+     * 검색 결과 수 — 제목 "총 N개" 에 쓴다. **검색 화면이라는 표시이기도 하다**: 이것도 `searchQuery` 도 주지 않으면
+     * 저장된 목록을 보여 주는 것으로 보고(공유 열람) 받은 순서를 기본 정렬로 둔다('받은 순서' 선택지가 생긴다).
+     */
     resultCount?: number;
     resultUnit?: string;
+    /** 검색어 — 한 낱말이면 '시작 우선' 을 기본 정렬로 쓴다 */
     searchQuery?: string;
+    /** 보일 항목. 검색어·결과 수 없이 이것만 주면 받은 순서 그대로가 기본이다 */
     items: WordSearchResultItem[];
     groups?: WordSearchResultGroup[];
     selected?: string[];