@ihabdevteam/core 0.128.0 → 0.131.0

package/dist/ihabdevteam-core.d.ts

@@ -225,6 +225,10 @@ export declare interface BadgeProps {
      */
     size?: 'small' | 'medium' | 'large' | BadgeDotSize;
     className?: string;
+    /**
+     * 접근성 이름. dot 은 주지 않으면 모양에 따라 '선택됨'·'제거'·'제외'·'N번째 선택' 으로 짓고,
+     * bar 는 주면 그 이름으로 읽힌다(안 주면 글자 그대로 읽힌다).
+     */
     'aria-label'?: string;
     label?: string;
     children?: ReactNode;
@@ -252,7 +256,7 @@ export declare interface BadgeProps {
     /** 우측 아이콘 (bar 전용). Lucide 아이콘 이름 또는 ReactNode */
     iconRight?: ReactNode | string;
     /**
-     * 아이콘 종류 (dot 전용)
+     * 아이콘 종류 (dot 전용). `number` 가 없고 이것도 없으면 `check` 로 그린다.
      * - `check`  — 선택/완료 (파란 체크)
      * - `remove` — 제거 (빨간 ×)
      * - `minus`  — 비활성/제외 (회색 —)
@@ -648,12 +652,13 @@ export declare interface BulkAction {
     onClick: () => void;
 }
 
-export declare function BulkBar({ count, actions, onClear, clearLabel, visible, content, max, }: BulkBarProps): JSX.Element;
+export declare function BulkBar({ count, actions, onClear, clearLabel: clearLabelProp, visible, content, max, }: BulkBarProps): JSX.Element;
 
 export declare interface BulkBarProps {
     count: number;
     actions: BulkAction[];
     onClear: () => void;
+    /** 선택 해제 단추 글자. 기본은 사전의 `bulkBar.clearSelection`('선택 해제') */
     clearLabel?: string;
     /** count > 0 일 때 자동으로 visible */
     visible?: boolean;
@@ -1063,7 +1068,7 @@ export declare interface CodeBoxProps {
 }
 
 /** @public */
-export declare function ColorPicker({ value, onChange, palette, size, className, }: ColorPickerProps): JSX.Element;
+export declare function ColorPicker({ value, onChange, palette, size, className, ariaLabel, }: ColorPickerProps): JSX.Element;
 
 /** @public */
 export declare interface ColorPickerProps {
@@ -1076,6 +1081,8 @@ export declare interface ColorPickerProps {
     /** 스와치 크기 — Button과 동일한 체계 (32 / 40 / 48), radius도 Button rounded와 동일하게 맞춤 */
     size?: ColorPickerSize;
     className?: string;
+    /** 묶음의 이름(예: '글자 색') — 낭독기가 무엇의 색을 고르는지 읽는다 */
+    ariaLabel?: string;
 }
 
 /** @public */
@@ -1115,7 +1122,14 @@ export declare interface CompositionFilter {
 /** @public 단어 구성요소 종류 (초성/중성/종성) */
 declare type CompositionPart = 'cho' | 'jung' | 'jong';
 
-/** @public */
+/**
+ * 오늘·어제 세트를 뽑아 `TODAY_SETS`·`YESTERDAY_SETS` 에 채운다(`loadTrainingData` 가 부른다).
+ *
+ * **어제 세트는 "어제 뽑힌 세트" 가 아니다** — 캐시가 메모리에만 있어, 날이 바뀌면 어제 몫도 따로 새로 뽑는다.
+ * 사용자에게 보이는 오늘·어제 세트는 사용자와 날짜로 시드를 정하는 `useDailyTrainingSelection` 을 쓴다
+ * (같은 날 같은 사용자면 늘 같은 세트, 어제 세트도 어제와 같다).
+ * @public
+ */
 export declare function computeDailySelection({ counts, forceRefresh }?: ComputeDailySelectionOptions): {
     today: {
         [k: string]: unknown[];
@@ -1230,7 +1244,7 @@ export declare interface ConfirmPopupProps {
     onClose: () => void;
     /** portal 없이 부모 컨테이너에 제자리 렌더 (목업/데모용) */
     inline?: boolean;
-    /** 패널 최대 가로폭. 확인창 기본은 'small'(640px) */
+    /** 패널 최대 가로폭. 확인창 기본은 'small'(480px) */
     size?: 'small' | 'medium' | 'large';
     className?: string;
 }
@@ -1341,7 +1355,7 @@ export declare function copyText(text: string): Promise<boolean>;
  *
  * 값은 손으로 적고 `test/coreVersion.test.ts` 가 package.json 과 어긋나면 운다.
  */
-export declare const CORE_VERSION = "0.128.0";
+export declare const CORE_VERSION = "0.131.0";
 
 /** @public */
 declare const coreDefault: Record<string, unknown>;
@@ -1493,6 +1507,11 @@ export declare interface CreateTTSResolverOptions {
     storagePrefix?: string;
     voice?: string;
     speed?: number;
+    /**
+     * @deprecated 리졸버가 쓰지 않는다 — 파일 이름에도, `/api/tts` 요청에도 들어가지 않는다
+     * (그 개발 서버도 pitch 를 받지 않는다). `generator` 에 넘기는 opts 에 그대로 실려 갈 뿐이라,
+     * 음높이가 필요하면 generator 가 직접 다룬다. 쓰는 곳이 없어 구현하지 않았다.
+     */
     pitch?: number;
     /** Optional function to generate/upload TTS audio when missing. Should return a public URL when done. */
     generator?: (text: string, destPath: string, opts?: CreateTTSResolverOptions) => Promise<string | null>;
@@ -1538,7 +1557,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, className, }: DatePickerProps): JSX.Element;
+export declare function DatePicker({ value, onChange, size, min, max, disabled, placeholder: placeholderProp, className, }: DatePickerProps): JSX.Element;
 
 /** @public */
 export declare interface DatePickerProps {
@@ -1548,6 +1567,7 @@ export declare interface DatePickerProps {
     min?: string;
     max?: string;
     disabled?: boolean;
+    /** 값이 없을 때 보이는 문구. 기본은 사전의 `datePicker.chooseDate`('날짜 선택') */
     placeholder?: string;
     className?: string;
 }
@@ -1561,12 +1581,7 @@ export declare function dateToDb(app: string | null | undefined): string | undef
 /**
  * 결과 팝업을 실제 훈련 없이 열어보는 개발용 단추 넷.
  *
- * 예전에는 파일 안의 `const DEBUG = false` 로만 켤 수 있었다. 모노레포 시절에는
- * packages/core 를 그 자리에서 고칠 수 있었으니 말이 됐는데, **패키지로 분리되면서
- * 켤 방법이 사라졌다** — 소비자가 node_modules 를 고치지 않는 한 언제나 null 이다.
- * 실제로 speechear-v2 가 이것을 렌더하고 있고, 아무것도 그려지지 않는다.
- *
- * 그래서 스위치를 밖으로 낸다. 기본값은 그대로 꺼짐이라 지금 쓰는 곳은 안 바뀐다.
+ * `enabled` 를 주어야 단추가 선다. 기본은 꺼짐이다.
  *
  * @example
  * <DebugResultLauncher enabled={import.meta.env.DEV} renderResultPopup={…} />
@@ -1589,6 +1604,8 @@ declare type Decomp = (ReturnType<typeof parseSyllable>)[];
 
 export declare const DEFAULT_LOCALE = "ko";
 
+export declare const DEFAULT_NOISE_SETTINGS: CoreNoiseSettings;
+
 /** @public */
 export declare function deriveNoiseContexts(trainingData: Record<string, unknown> | null | undefined): NoiseContext_2[];
 
@@ -1821,14 +1838,32 @@ export declare interface DropdownProps {
     ariaLabel?: string;
 }
 
+/**
+ * @public 소음이 **들리는 크기**(0~2, 원본 소음 파일 기준) = mainVolume × 비율. 켜짐 여부는 보지
+ * 않는다. 결과 기록·파형이 쓴다. 소음 `<audio>` 에 거는 값은 `noiseElementVolume`.
+ */
+export declare function effectiveNoiseVolume(settings: 비율설정): number;
+
+/** @public 문제 소리 볼륨(0~1) = mainVolume. 비율과 상관없다. */
+export declare function effectiveSpeechVolume(settings: 비율설정): number;
+
 /** @public */
 export declare function EffectPartyPopper({ active, count, duration, strength, // multiplier for speed/spread
     onComplete, trigger, }: {
+    /** true 인 동안 그린다. false 면 아무것도 안 그린다. */
     active?: boolean;
+    /** 조각 수. 좌우로 반씩 나눈다. 기본 40. */
     count?: number;
+    /**
+     * 조각 수명의 기준(ms). 값에 비례해 모든 조각이 더 오래 또는 더 짧게 날다 사라진다 — 기본 2000 에서
+     * 조각 하나는 약 1.5~5.5초 난다(조각마다 다르고, strength 가 크면 조금 길다).
+     */
     duration?: number;
+    /** 속도·퍼짐 배율. 기본 1. */
     strength?: number;
+    /** 모든 조각이 사라지면 부른다(움직임 최소화 설정이면 바로 부른다). */
     onComplete?: () => void;
+    /** 값이 바뀌면 다시 터진다. */
     trigger?: number;
 }): JSX.Element | null;
 
@@ -2149,8 +2184,13 @@ export declare function formatDateLongLocale(iso: string, lang: string): string;
 /** "2024. 01. 15. 오후 03:30" (2-digit month + time) */
 export declare function formatDatetimeKo(iso: string): string;
 
-/** 초 → "M분 S초"(또는 "S초") */
-export declare function formatDuration(sec: number | null | undefined): string;
+/**
+ * 초 → "M분 S초"(또는 "M분"·"S초"). 없거나 0 이하면 '-'.
+ *
+ * 문구는 지금 언어로(`customers.duration.*`, 사전에 없으면 한국어). `durationStr` 를 주면
+ * 그 함수가 만든 글을 그대로 쓴다 — `calcAge` 의 `ageStr` 와 같은 결.
+ */
+export declare function formatDuration(sec: number | null | undefined, durationStr?: (m: number, s: number) => string): string;
 
 /**
  * 한국 연락처를 010-1234-5678 형식으로 정규화.
@@ -2245,7 +2285,8 @@ export declare function getElementVolume(el: HTMLMediaElement): number;
  * 곳곳에 흩어져 있어 여기 한 벌로 모은다.
  *
  * 문자열도 그대로 쓴다 — `throw '문구'` 로 던지는 자리가 있다. 끝내 못 읽는
- * 값(숫자·null·빈 객체·빈 문구)일 때만 fallback 을 쓴다.
+ * 값(숫자·null·빈 객체·빈 문구)일 때만 fallback 을 쓴다. fallback 을 주지 않으면 지금
+ * 언어의 '알 수 없는 오류'(`common.unknownError`), 주면 그 문구 그대로.
  *
  * 회원 앱은 `src/libs/errorUtils.ts` 가 이것을 다시 내보낸다 — 한 벌만 둔다.
  * @public
@@ -2386,8 +2427,14 @@ export declare function hasStructureContrast(A: Decomp, B: Decomp): boolean;
 export declare function Header({ activeKey, onChange, items, malgwiItems: _malgwiItems, managerItems: _managerItems, unreadCount, onDebug, onNotification, onAccount, onSetting, onHelp, appMode, onAppModeChange }: {
     activeKey?: string | null;
     onChange?: (key?: string) => void;
+    /** 지금 모드의 내비 항목. 데스크톱은 SideNav, 모바일은 BottomNav 가 이 목록을 그린다. */
     items?: SideNavItem[];
+    /**
+     * @deprecated 읽지 않는다 — 지금 모드의 목록을 `items` 로 넘긴다.
+     * 모드 전환 때 부르는 쪽이 `items` 를 바꿔 넣으므로 헤더가 두 목록을 따로 들고 있을 까닭이 없다.
+     */
     malgwiItems?: SideNavItem[];
+    /** @deprecated 읽지 않는다 — 지금 모드의 목록을 `items` 로 넘긴다(`malgwiItems` 와 같다). */
     managerItems?: SideNavItem[];
     unreadCount?: number;
     onDebug?: () => void;
@@ -2437,7 +2484,7 @@ export declare interface IconGridMenuCategory {
 /** @public */
 export declare interface IconGridMenuProps {
     categories?: IconGridMenuCategory[];
-    /** 현재 선택된 카테고리 key (controlled) */
+    /** 현재 선택된 카테고리 key (controlled). `null` 이면 아무것도 고르지 않은 상태, 주지 않으면 첫 카테고리로 시작한다 */
     selected?: string | null;
     onSelect?: (key: string | null) => void;
     /** 버튼 크기 — `medium`(기본, 68px) / `small`(48px) */
@@ -2456,8 +2503,8 @@ export declare interface IconProps {
     /**
      * 감싸는 `<span>` 의 클래스. 주면 기본 이름을 **갈아치운다** — 덧붙이지 않는다.
      *
-     * 기본값 `iconRenderer-icon` 을 비롯한 네 `iconRenderer-*` 이름은 **패키지에
-     * 제 규칙이 하나도 없다**(실측: 자기 규칙 0개). 붙잡을 이름일 뿐이고 크기는
+     * 기본값 `iconRenderer-icon` 을 비롯한 `iconRenderer-*` 이름은 마스크(`-mask`)를 빼면
+     * **패키지에 제 규칙이 없다**. 붙잡을 이름일 뿐이고 크기는
      * `size`, 그 밖의 모양은 `wrapperStyle` 이나 소비자 CSS 로 간다. 그래서
      * `className="iconRenderer-icon"` 이라고 적어도 아무 모양도 따라오지 않는다.
      *
@@ -2468,7 +2515,10 @@ export declare interface IconProps {
     className?: string;
     /** `<img>` 로 그릴 때의 클래스. 기본 `iconRenderer-icon-image` — 규칙 없음. */
     imgClassName?: string;
-    /** 마스크로 그릴 때의 클래스. 기본 `iconRenderer-icon-mask` — 규칙 없음. */
+    /**
+     * 마스크로 그릴 때의 클래스. 기본 `iconRenderer-icon-mask` — 글자색으로 칠하고 크기는 `size`(없으면 20px).
+     * 주면 기본 이름을 갈아치우므로 마스크 규칙(`mask-image: var(--icon-url)` 등)도 그 클래스가 대야 한다.
+     */
     maskClassName?: string;
     /** 인라인 SVG 로 그릴 때의 클래스. 기본 `iconRenderer-icon-svg` — 규칙 없음. */
     svgClassName?: string;
@@ -2699,6 +2749,12 @@ export declare interface LeaderboardRow {
     isMe: boolean;
 }
 
+/** @public */
+export declare const LEVEL_MAX = 9;
+
+/** @public */
+export declare const levelToPct: (level: number) => number;
+
 /** @public */
 export declare function ListenStep({ _stepIndex, _totalSteps, ...rest }: StepWrapperProps): JSX.Element;
 
@@ -2718,7 +2774,7 @@ export declare interface LoaderProps {
     size?: number | string;
     /** 진행률(0–100). `variant='bar'`일 때 적용됩니다. */
     progress?: number | null;
-    /** aria-label 및 시각적 레이블 */
+    /** 접근성 이름(aria-label). 화면에 글자로 나오지는 않는다. 안 주면 i18n 의 `loader.loading`(기본 'Loading'). */
     label?: string;
 }
 
@@ -2763,7 +2819,10 @@ export declare function lsBytes(keys: string[]): number;
 export declare const MARK_ICON: Record<ScoreMark, string>;
 
 /**
- * 고른 표시의 단추 변형.
+ * 고른 표시의 단추 변형(○ main · △ warn · ✕ danger).
+ *
+ * **모양(아이콘)이 이미 셋을 가르고 색은 거들 뿐이다** — 색만으로 구분하게 두면
+ * 색을 잘 못 가리는 사람에게는 세 표시가 같아진다.
  *
  * △ 는 `sub`(청록)였는데 **파랑 옆에서 '좋음' 계열로 읽혔다** — ○ 와 △ 가 나란히
  * 있으면 둘 다 통과한 것처럼 보인다. 애매함은 주의색이 맞다.
@@ -2803,19 +2862,21 @@ export declare function marksForSave(marks: Record<string, ScoreMark | null | un
 export declare function matchesChoseongSearch(text: string, search: string): boolean;
 
 /**
- * @public 음절 패턴 미니 DSL 매칭. 쉼표(,)로 나눈 조각을 자리(음절) 단위로 자동 분해하며,
- * **분해된 총 자리 수는 반드시 단어의 음절 수와 같아야** 매칭된다. 한 자리는 다음 중 하나:
+ * @public 음절 패턴 미니 DSL 매칭. 쉼표(,)로 나눈 조각을 연속된 음절 자리들로 풀고, 그 자리들이 단어의
+ * **어느 위치에서든 연속으로** 맞으면 매칭된다(포함 매칭 — 단어 음절 수가 자리 수보다 많아도 된다).
+ * 한 자리는 다음 중 하나:
  *  - 빈 자리(쉼표 사이가 비어 있음) — 무관(아무 음절이나 허용).
- *  - 완성 음절 한 글자(예: '가') — 그 자리 음절이 정확히 이 글자와 같아야 함.
+ *  - 완성 음절 한 글자(예: '가', '강') — 받침 없는 글자는 초성·중성만 같으면 되고(받침 무관: '수' → 수·술·숙),
+ *    받침 있는 글자는 정확히 같아야 함.
  *  - 자음/모음 한 글자(예: 'ㄴ', 'ㅏ') — 자음이면 그 자리 초성이, 모음이면 그 자리 중성이 정확히 그
  *    자모여야 함(나머지는 무관).
- *  - 초성·중성·종성 3자모 템플릿(예: '__ㄱ', 쉼표로 나눈 조각이 정확히 3글자일 때만) — 각 자리가 '_'면
- *    무관, 자모면 그 위치(초성/중성/종성)가 정확히 그 자모여야 함. 종성 자리 '_'는 받침 유무 모두 허용.
- * 쉼표 사이에 완성 음절·자음·모음을 이어 붙이면(예: '가ㄴ') 한 글자씩 각각 한 음절 자리로 자동 분해된다
- * (3글자로 붙이면 템플릿과 구분이 안 되므로 예외 — 그 경우는 쉼표로 나눠 쓴다).
- * 예: '가,,다' → 3음절, 첫 음절 '가' · 가운데 무관 · 끝 음절 '다'.
- * 예: '__ㄱ,고' → 2음절, 첫 음절 종성이 'ㄱ'(초성·중성 무관) · 끝 음절 '고'.
- * 예: '가ㄴ,,다'(= '가,ㄴ,,다'와 동일) → 4음절, 첫 음절 '가' · 둘째 음절 초성 'ㄴ' · 셋째 무관 · 넷째 '다'.
+ *  - 한 음절 템플릿(조각에 '_'가 하나라도 있을 때, 1~4글자) — 초성·중성·종성 순으로 읽고, '_'나 생략한 뒤
+ *    자리는 무관, 자모면 그 위치가 정확히 그 자모여야 함. 종성은 겹받침 두 자모('ㄹㄱ' = ㄺ)까지.
+ *    예: '__ㄱ' = 종성 ㄱ, 'ㄱ_' = 초성 ㄱ, 'ㄱ_ㄱ' = 초성 ㄱ·종성 ㄱ.
+ * '_' 없이 완성 음절·자음·모음을 이어 붙이면(예: '가ㄴ') 한 글자씩 각각 한 음절 자리로 분해된다.
+ * 예: '가,,다' → 첫 음절 '가'(받침 무관) · 가운데 무관 · 끝 음절 '다'인 연속 3음절을 포함한 단어.
+ * 예: '__ㄱ,고' → 종성 'ㄱ'인 음절 바로 뒤에 '고'가 오는 단어(먹고·박고구마 …).
+ * 예: '가ㄴ,,다'(= '가,ㄴ,,다'와 동일) → 연속 4음절 '가' · 초성 'ㄴ' · 무관 · '다'.
  * 해석할 수 없는 글자(자음·모음·완성 음절이 아님)가 섞이면 그 자리는 항상 매칭 실패 처리되어 결과가
  * 0건이 된다(조용히 무관 처리하지 않는다 — 제약이 무시된 채 결과가 나오는 오해를 막기 위해).
  */
@@ -2869,10 +2930,23 @@ export declare type MergedVisit = {
     status: VisitAllStatus;
 };
 
+/**
+ * @public 설정에 조각을 덮는다 — `{ ...base, ...patch }` 에 비율 규칙 하나를 더한 것.
+ *
+ * **조각에 `level` 은 있는데 `noiseRatio` 가 없으면** 그 조각은 옛 모양이다(저장된 옛 기록,
+ * 옛 `noiseOverride`). 그대로 덮으면 base 의 `noiseRatio`(기본값 1 등)가 남아 level 을 가려
+ * 버리므로, 덮은 결과의 level·mainVolume 으로 비율을 셈해 **그 자리에서 박아 둔다** —
+ * 박지 않고 비워 두면 뒤에 전체 소리만 바꿀 때 비율이 따라 변해 소음이 옛날처럼 제자리에 선다.
+ * `mainVolume` 은 그대로다 — 옛 뜻(문제 소리 = mainVolume, 소음 = level/9)이 새 셈(문제 = M, 소음 = M×R)
+ * 에서 들리던 크기 그대로 남는다(0.123.0 의 "R>1 이면 mainVolume = level/9" 는 0.125.0 에서 걷음).
+ * `{ ...DEFAULT_NOISE_SETTINGS, ...saved }` 대신 이것을 쓴다.
+ */
+export declare function mergeNoiseSettings(base: CoreNoiseSettings, patch?: Partial<CoreNoiseSettings> | null): CoreNoiseSettings;
+
 /**
  * @public 합치기 문제 **표시** 문장 — 미리보기·러너 공용. 음절/음소 모두 원문(자모는 자모 그대로: 'ㄱ','ㅏ')로 표시한다.
  * TTS로 읽을 땐 자모를 낱자 이름으로 바꿔야 하지만(그건 jamoToNamesForSpeech가 합성 경로에서 처리), 화면 표기는 자모 유지.
- * 예: ['아','냐'] → `"아"와 "냐"를 합치면 어떤 단어가 되나요?` / ['ㄱ','ㅏ'] → `"ㄱ"와 "ㅏ"를 합치면 어떤 소리가 되나요?`
+ * 예: ['아','냐'] → `"아"와 "냐"를 합치면 어떤 단어가 되나요?` / ['ㄱ','ㅏ'] → `"ㄱ"과 "ㅏ"를 합치면 어떤 소리가 되나요?`
  */
 export declare function mergeQuestionText(parts: string[], phoneme?: boolean): string;
 
@@ -2943,6 +3017,12 @@ export declare type NavItem = {
     label?: string;
     icon?: string;
     state?: string;
+    /**
+     * 단추 우상단 원형 숫자 배지(SideNav 항목 배지와 같은 모양). 0/undefined 면 숨기고, 99 에서 자른다.
+     * 배지는 낭독기에서 숨기고 개수는 단추 이름에 붙인다. 넘쳐 "…" 메뉴로 가면 메뉴 항목의 배지가 되고,
+     * "…" 단추에는 넘친 항목 개수의 합이 선다.
+     */
+    badgeCount?: number;
 };
 
 /**
@@ -2995,6 +3075,12 @@ export declare const NO_CODA = "__NO_CODA__";
 /** @public */
 export declare const NOISE_DATAS: unknown[];
 
+/** @public 소음 비율 상한(배). */
+export declare const NOISE_RATIO_MAX = 2;
+
+/** @public 소음 비율 칸(배). */
+export declare const NOISE_RATIO_STEP = 0.1;
+
 /** @public */
 export declare interface NoiseContext {
     sentence: string;
@@ -3006,6 +3092,42 @@ declare interface NoiseContext_2 {
     contextCode?: string;
 }
 
+/**
+ * @public 소음 `<audio>` 볼륨(0~1) = min(1, 들리는 크기 ÷ gain). gain 은 소음 파일이 원본보다 몇 배
+ * 큰지 — 기본은 `configureStorage({ noiseFileGain })`(없으면 1).
+ */
+export declare function noiseElementVolume(settings: 비율설정, gain?: number): number;
+
+/** @public */
+export declare const NoisePlayerContext: Context<NoisePlayerContextValue | null>;
+
+/** @public */
+export declare type NoisePlayerContextValue = {
+    settings: CoreNoiseSettings;
+    setSettings: (next: Partial<CoreNoiseSettings>) => void;
+    /** 오디오 레벨 미터용 AnalyserNode 등록(오디오 플레이어가 호출). */
+    registerAnalyser?: (which: 'main' | 'noise', analyser: AnalyserNode | null) => void;
+    /** 문장(메인) 오디오 미터용 AnalyserNode. */
+    mainAnalyser?: AnalyserNode | null;
+    /** 소음 오디오 미터용 AnalyserNode. */
+    noiseAnalyser?: AnalyserNode | null;
+    /** 문장(메인) 재생 속도(playbackRate). 0.5–1.5, 기본 1. */
+    playbackRate: number;
+    setPlaybackRate: (rate: number) => void;
+    /** 전체 소리 = 문제 소리 볼륨. 0–1, 기본 1. 소음은 이 값 × 소음 비율(noiseElementVolume 참고). */
+    mainVolume: number;
+    setMainVolume: (v: number) => void;
+};
+
+/**
+ * @public 설정의 소음 비율(배). `noiseRatio` 가 있으면 그것(0~2 로 자름), 없으면 **옛 값에서
+ * 들리던 그대로** 옮긴다 — (level/9) ÷ mainVolume 을 0~2 로 자르고 0.1 단위 반올림.
+ * mainVolume 이 0 이면 옛 값으로는 비율을 알 수 없어 1.
+ */
+export declare function noiseRatioOf(settings: Pick<CoreNoiseSettings, 'level' | 'mainVolume'> & {
+    noiseRatio?: number;
+}): number;
+
 /** @public 소음설정 영속 저장소. 앱에서 Supabase 연결을 주입한다. */
 export declare interface NoiseSettingsStore {
     /** 현재 훈련 대상(본인 또는 고객)의 저장된 소음설정. 없으면 null. */
@@ -3056,9 +3178,14 @@ export declare function NoticeBox({ title, lines, notices, children, variant, di
 export declare interface NoticeBoxProps {
     title?: string;
     lines?: string[];
+    /** 여러 안내를 한 상자에 차례로 싣는다. 주면 `title`·`lines`·`children` 대신 이것을 그린다. */
     notices?: Array<{
         title?: string;
         lines?: string[];
+        /**
+         * 효과 없음 — 상자 모양은 바깥 `variant` 하나로만 정해진다.
+         * @deprecated 읽히지 않는 값이다. 항목마다 모양을 달리 그리는 스타일이 없다 — 모양이 다른 안내는 NoticeBox 를 따로 둔다.
+         */
         variant?: string;
         children?: ReactNode;
     }> | null;
@@ -3153,8 +3280,8 @@ declare type PageTitleProps = {
 };
 
 /**
- * 페이지네이션 컨트롤 (‹ 현재/전체 ›).
- * CustomersPage·TrainingSettingsPage 등 테이블 페이지에서 공유.
+ * 페이지네이션 컨트롤 (‹ 현재/전체 ›). 표 아래에 두고 `page`·`totalPages` 를 넘기면
+ * 이전·다음 단추가 `onChange` 로 1~`totalPages` 안의 쪽 번호를 돌려준다. 끝에서는 그쪽 단추가 꺼진다.
  *
  * @public
  */
@@ -3509,7 +3636,12 @@ export declare interface PassCardProps {
     /** 기간 토큰(예: '30일'). 미지정 시 product에서 도출. */
     plan?: string;
     type?: PassCardType;
+    /**
+     * @deprecated 읽지 않는다 — 카드는 시작일을 그리지 않고, 남은 기간은 `endDate`(또는 `remainingSeconds`)로만 센다.
+     * 넘겨도 화면은 같다.
+     */
     startDate?: string;
+    /** 끝나는 날(YYYY-MM-DD). `state` 가 active·expired 이고 `remainingSeconds` 가 없으면 이 날까지 남은 날수로 사용량을 센다. */
     endDate?: string;
     /**
      * 전환으로 일시정지되어 남은 시간(초)이 알려진 경우에만 지정.
@@ -3519,8 +3651,12 @@ export declare interface PassCardProps {
      */
     remainingSeconds?: number;
     state?: PassCardState;
+    /** @deprecated 읽지 않는다 — 대기 순서는 카드에 그리지 않는다. 넘겨도 화면은 같다. */
     queueIndex?: number;
-    /** 배경 컴포넌트. 기본값: PassCardBgTwoCircle */
+    /**
+     * 배경 컴포넌트. 안 주면 종류·기간·라벨로 고른다 — 말귀(`speechear`)는 늘 PassCardBgTwoCircle,
+     * 말귀 매니저(`manager`)는 1년이면 PassCardBgTalk, 라벨이 오픈특가면 PassCardBgSoundMoveV1, 그 밖에는 PassCardBgSoundMove.
+     */
     bg?: ReactNode;
     /** true면 배경만 표시하고 콘텐츠(로고·플랜·카피라이트)를 숨김 */
     bgOnly?: boolean;
@@ -3580,8 +3716,15 @@ export declare function PaymentPlan(props: PaymentPlanProps): JSX.Element;
 export declare interface PaymentPlanData {
     id: string | number;
     title?: string;
-    /** 서비스명(말귀/말귀매니저). 카드 로고·표기용. title에서 파싱하지 않고 별도 저장. */
+    /**
+     * 서비스명(말귀/말귀매니저). 이 컴포넌트는 읽지 않는다 — 카드 로고는 `group` 으로 고른다.
+     * 부르는 쪽이 상품 목록을 나누거나 표기할 때 쓰도록 자리만 둔 칸이다.
+     */
     service?: string;
+    /**
+     * 상품 묶음. `'org'` 면 이용권 카드를 말귀 매니저 모양으로, 그 밖(`'personal'` 등)이면 말귀 모양으로 그린다.
+     */
+    group?: 'personal' | 'org' | (string & {});
     /** 플랜 티어명(스탠다드/라이트/프로 등). 카드 헤드라인용. */
     tier?: string;
     subtitle?: string;
@@ -3632,6 +3775,9 @@ export declare interface PaymentPlanTier {
     [k: string]: unknown;
 }
 
+/** @public */
+export declare const pctToLevel: (pct: number) => number;
+
 /**
  * 인물 소개 카드 — 원형 사진 위에 이름·직함, 아래에 경력 목록을 세로로 쌓는다.
  * 회사 소개의 운영진 섹션, 연구진 목록 등에 사용.
@@ -3876,7 +4022,14 @@ export declare interface PopupListProps<T extends {
     selectedId?: string | number;
     /** 현재 선택된 아이템 id Set — 다중 선택 강조 (`selectedId`보다 우선) */
     selectedIds?: Set<string | number>;
-    /** 행 클릭 후에도 팝업을 닫지 않음 (다중 선택용). 기본 false */
+    /**
+     * 효과 없음 — ListPopup 은 행을 골라도 **스스로 닫지 않는다**(닫기는 늘 `onSelect`·`onClose` 를
+     * 받은 쪽이 정한다). 그래서 이 값은 읽지 않는다.
+     *
+     * @deprecated 읽히지 않는 값이다. 예전 JSDoc 은 "기본 false = 고르면 닫힘" 이라 했지만 그렇게
+     * 동작한 적이 없고, 그 뜻대로 고치면 행 클릭이 아무것도 안 하는 화면(행 안 단추로만 보내는 창 등)이
+     * 누르는 순간 닫힌다. 고른 뒤 닫으려면 `onSelect` 안에서 직접 닫는다.
+     */
     keepOpenOnSelect?: boolean;
     /** 행 선택 콜백 */
     onSelect: (item: T) => void;
@@ -3968,7 +4121,7 @@ export declare interface PopupProps {
      * 패널 최대 가로폭 제한. 미지정 시 기본(820px) 유지.
      * - `small`  480px (확인/알림류)
      * - `medium` 680px (입력 폼)
-     * - `large`  880px (리스트/다중 콘텐츠)
+     * - `large`  1080px (리스트/다중 콘텐츠)
      * 더 넓거나 무제한이 필요하면 className으로 `.popup-panel` max-width를 직접 override.
      */
     size?: 'small' | 'medium' | 'large';
@@ -4112,11 +4265,8 @@ export declare interface ProgressIndicatorProps {
      */
     announce?: boolean;
     /**
-     * 이름표를 직접 준다. 안 주면 i18n 의 `progress.steps` 로 짓는다.
-     *
-     * i18n 을 쓰지 않는 앱에서는 그 값이 한글 기본값으로 떨어진다 —
-     * 화면은 영문인데 이름표만 한글이 되는 자리가 실제로 있었다
-     * (sound-localization-system 의 병원용 빌드).
+     * 이름표를 직접 준다. 안 주면 i18n 의 `progress.steps`('진행 단계 N / M')로 짓는다 —
+     * i18n 사전을 싣지 않는 앱은 이름표가 한글 기본값으로 떨어지므로 번역한 글을 여기 넘긴다.
      */
     ariaLabel?: string;
 }
@@ -4392,7 +4542,7 @@ export declare interface Question {
 export declare function Radio({ checked, onChange, name, value, disabled, label, className }: RadioProps): JSX.Element;
 
 /** @public */
-export declare function RadioGroup({ options, value, onChange, name, disabled, direction, className, }: RadioGroupProps): JSX.Element;
+export declare function RadioGroup({ options, value, onChange, name, disabled, direction, className, ariaLabel, }: RadioGroupProps): JSX.Element;
 
 /** @public */
 export declare type RadioGroupDirection = 'vertical' | 'horizontal';
@@ -4413,6 +4563,8 @@ export declare interface RadioGroupProps {
     disabled?: boolean;
     direction?: RadioGroupDirection;
     className?: string;
+    /** 묶음의 이름 — 낭독기가 "무엇을 고르는 라디오 묶음" 인지 읽는다. 보이는 제목이 따로 있어도 이어지지 않으면 준다. */
+    ariaLabel?: string;
 }
 
 /** @public */
@@ -4543,7 +4695,10 @@ export declare interface ReportBlock {
  * 바닥(로고·저작권 + 쪽 번호)이 반복된다.
  *
  * 재는 방식이라 글꼴이 늦게 오거나 이미지가 나중에 뜨면 쪽이 밀릴 수 있다.
- * 그 경우 `blocks` 를 그대로 두고 다시 그리면 다시 잰다.
+ * 다시 재는 때는 블록들의 `id`·`section`·`group` 구성이 바뀔 때와 처음 그릴 때뿐이다 —
+ * 같은 구성으로 다시 그리거나 `content` 만 바뀌어서는 다시 재지 않는다(렌더마다 재면
+ * 재기 → 쪽 나눔 → 렌더가 끝없이 돈다). 글꼴·이미지가 다 온 뒤 다시 재야 하면
+ * `key` 를 바꿔 새로 붙인다.
  *
  * 화면에 그린 쪽 수는 다른 도구로 만든 PDF 와 다를 수 있다. 같은 내용을 그리는
  * 높이가 서로 달라서인데, 쪽 수까지 맞춰야 하면 양쪽 본문 높이를 견줘야 한다.
@@ -4848,10 +5003,14 @@ export declare function saveNoiseSettings(settings: CoreNoiseSettings): void;
  * 리액트가 다른 것을 같은 것으로 보고 상태를 잘못 물려준다. 그래서 **주어진 이름이
  * 있으면 반드시 그것을 쓴다**는 게 이 함수들의 약속이다.
  */
-/** @public */
+/**
+ * @public 시나리오의 한 쪽. `steps` 는 시나리오(`scenario.pages`)에서는 **ScenarioStep 객체**다 — 팝업이
+ * 그것을 `ScenarioStep` 으로 읽는다(key·type·props). 자식 요소(`<Page>`)로 쪽을 짠 경우에만 팝업이 안에서
+ * 단계 요소(ReactNode)를 담는다.
+ */
 export declare type ScenarioPage = {
     id?: string;
-    steps?: ReactNode[];
+    steps?: ScenarioStep[] | ReactNode[];
     pageTop?: ReactNode | null;
     pageBottom?: ReactNode | null;
 } & Record<string, unknown>;
@@ -4996,7 +5155,7 @@ export declare interface SearchSummaryProps {
 export declare type SearchSummaryStatus = 'ready' | 'guide' | 'error';
 
 /** @public */
-export declare function Section({ type, title, icon, action, disc, children, className, style }: SectionProps): JSX.Element;
+export declare function Section({ type, title, headingLevel, icon, action, disc, children, className, style }: SectionProps): JSX.Element;
 
 /**
  * 섹션·페이지의 머리 — 머리말 · 제목 · 설명.
@@ -5034,6 +5193,12 @@ export declare type SectionHeaderTone = 'dark' | 'light';
 export declare interface SectionProps {
     type?: SectionType;
     title?: ReactNode;
+    /**
+     * 제목을 이 단계의 제목 태그(`h1`~`h6`)로 그린다 — **주는 것을 권한다.** 페이지 제목 아래 구획이면 2, 그 아래면 3 처럼 문서의 제목 순서에 맞춰 주면 낭독기의 제목 목록으로 이 구획에 바로 갈 수 있다.
+     *
+     * 주지 않으면 `div` 로 그려 제목 목록에 안 나온다. 글자 모양은 어느 쪽이든 `type` 이 정한다.
+     */
+    headingLevel?: 1 | 2 | 3 | 4 | 5 | 6;
     icon?: string;
     action?: ReactNode;
     disc?: ReactNode;
@@ -5510,7 +5675,7 @@ export declare interface SoundCompassProps {
 
 /**
  * @public 음절의 실제 소리(표준발음). pronMap에 있으면 그것, 없으면(합성 음절) 끝소리 규칙 발음, 그래도 없으면 철자.
- * (예: '밡'·'밖'은 모두 [박] — 소리 기준 중복 판정에 쓴다.)
+ * (예: '밖'·'밗'은 모두 [박] — 소리 기준 중복 판정에 쓴다.)
  */
 export declare function soundOf(syll: string, pronMap: Map<string, string>): string;
 
@@ -5821,7 +5986,7 @@ export declare const SYLLABLE_MIN = 5;
 
 /**
  * @public 정답 음절(분해 cs)의 지정 파트를 다른 음소로 바꿔 대립쌍 음절 n개 생성.
- * 중복 배제는 '실제 발음(soundOf)' 기준 — 소리가 같은 오답(밡/밖→박)이 함께 나오지 않게 한다.
+ * 중복 배제는 '실제 발음(soundOf)' 기준 — 소리가 같은 오답(밖/밗→박)이 함께 나오지 않게 한다.
  */
 export declare function syllableContrasts(cs: Syllable, part: 'cho' | 'jung' | 'jong', correct: string, n: number, pronMap: Map<string, string>): string[];
 
@@ -6017,7 +6182,7 @@ export declare type TableProps<T extends {
     headerActions?: ReactNode;
     /** 행이 없을 때 body 영역에 표시할 콘텐츠 */
     empty?: ReactNode;
-    /** true면 rows/empty 대신 스피너 표시 (fields 헤더도 숨김) */
+    /** true면 rows/empty 대신 스피너 표시. 제목 머리와 fields 머리는 그대로 둔다. */
     loading?: boolean;
     /** 드래그 오버 강조 */
     dragOver?: boolean;
@@ -6482,28 +6647,22 @@ export declare interface TopBannerProps {
     'aria-label'?: string;
 }
 
-/** @public */
-export declare const TOPIC_TYPES: ({
-    key: string;
-    label: string;
-    icon: string;
-    color: string;
-    subs: {
-        key: string;
-        label: string;
-    }[];
-    desc?: undefined;
-} | {
+/**
+ * 주제·세부 주제 목록(열쇠·이름·아이콘·색). **설명(desc)은 두지 않는다** — 코어·앱 어디에서도 주제 설명을
+ * 그리지 않고, 한때 7개 주제에 붙어 있던 '소음 환경 속 문장 이해 훈련' 은 훈련 유형(소음 하 문장 듣기)의
+ * 설명을 옮겨 붙인 값이었다(2026-09-14 걷음). 화면에 보이는 설명은 훈련 유형(`TRAINING_TYPES`)의 것이다.
+ * @public
+ */
+export declare const TOPIC_TYPES: {
     key: string;
     label: string;
     icon: string;
-    desc: string;
     color: string;
     subs: {
         key: string;
         label: string;
     }[];
-})[];
+}[];
 
 /**
  * 훈련 카테고리 데이터 DI — 앱에서 주입하는 함수 기반 인터페이스.
@@ -6646,15 +6805,15 @@ export declare interface TrainingBlockButtonProps {
     completed?: boolean;
     /**
      * 버튼 레이아웃 크기.
-     * - `square` (기본값): 200×200px 정사각형 카드
+     * - `square` (기본값): 200×200px 정사각형 카드(좁은 화면에선 190px·반 폭으로 줄어든다)
      * - `small`: 120×120px 축소 카드 (행 펼치기 영역 등 좁은 공간용)
-     * - `list`: 전체 너비 × 60px 가로형 리스트 항목
-     * - `compact`: 툴팁 등 좁은 공간용 소형 리스트 항목 (44px, 아이콘 24px)
+     * - `list`: 너비 200px · 최소 높이 68px 가로형 항목
+     * - `compact`: 툴팁 등 좁은 공간용 소형 리스트 항목 (전체 너비 × 높이 40px, 작은 아이콘)
      */
     size?: 'square' | 'small' | 'list' | 'compact';
     renderPopup?: (props: TrainingBlockButtonPopupProps) => ReactNode;
     completedIds?: Set<string>;
-    /** 선택 상태 ID Set. 완료 뱃지 없이 테두리 강조만 표시. */
+    /** 선택 상태 ID Set. 포함된 항목(완료가 아닌 것)에 체크 배지를 표시 — 완료와 같은 배지이고, `hideCheckBadge` 면 숨는다. */
     selectedIds?: Set<string>;
     /** 호버 시 표시할 문제/문장 텍스트. 제공 시 DescriptionTooltip 으로 렌더. */
     tooltipText?: string | string[];
@@ -6691,19 +6850,24 @@ export declare interface TrainingBlockProps {
     type?: TrainingTypeDescriptor;
     trainingDatas?: TrainingItem[] | unknown[];
     depth?: string | string[];
+    /**
+     * @deprecated 쓰이지 않는다 — 한 번에 보이는 카드 수는 20개로 고정이고 나머지는 '더보기'로 20개씩 늘린다.
+     * 소비처가 항목 수(`trainingDatas.length`)를 넘기고 있어, 이 값을 페이지 크기로 살리면 20개 끊기가 사라진다.
+     */
     count?: number;
     /** 버튼 클릭 시 열릴 팝업 렌더링 함수. TrainingBlockButton의 renderPopup과 동일. */
     renderPopup?: (props: TrainingBlockButtonPopupProps) => ReactNode;
     /** 오늘 완료된 훈련 항목 ID Set. completedIds에 포함된 항목은 완료 상태로 표시됩니다. */
     completedIds?: Set<string>;
-    /** 선택 상태 ID Set. 완료 뱃지 없이 테두리 강조만 표시. */
+    /** 선택 상태 ID Set. 포함된 항목(완료가 아닌 것)에 체크 배지를 표시 — 완료와 같은 배지다. */
     selectedIds?: Set<string>;
     /** 훈련 항목 완료 시 호출되는 콜백. itemId는 완료된 TrainingItem의 id입니다. */
     onItemComplete?: (itemId: string) => void;
     /**
      * 버튼 레이아웃 크기.
-     * - `square` (기본값): 200×200px 정사각형 카드
-     * - `list`: 전체 너비 × 80px 가로형 리스트 항목
+     * - `square` (기본값): 200×200px 정사각형 카드(좁은 화면에선 190px·반 폭으로 줄어든다)
+     * - `small`: 120×120px 축소 카드
+     * - `list`: 너비 200px · 최소 높이 68px 가로형 항목
      */
     size?: 'square' | 'list' | 'small';
     /** true 이면 버튼 호버 시 DescriptionTooltip 으로 문제 텍스트를 표시. 기본값 false. */
@@ -7761,6 +7925,9 @@ export declare function useI18n(): I18nContextValue;
 /** @public */
 export declare function useMediaQuery(query: string): boolean;
 
+/** @public */
+export declare function useNoisePlayer(): NoisePlayerContextValue | null;
+
 /**
  * 클라이언트 페이지네이션 — 목록·페이지크기·현재 페이지로 현재 쪽 항목·총 쪽수·보정된
  * 현재 쪽을 낸다. 목록이 줄어 page 가 총 쪽수를 넘으면 마지막 쪽으로 조인다(curPage).
@@ -7964,6 +8131,11 @@ export declare function useVisitAllPanel(mergedVisits: MergedVisit[]): {
     setVapSearch: Dispatch<SetStateAction<string>>;
     vapPageSize: string;
     setVapPageSize: Dispatch<SetStateAction<string>>;
+    /** 번역된 개수 보기 옵션 — `VAP_PAGE_SIZE_OPTIONS` 와 값은 같고 라벨만 지금 언어로 */
+    vapPageSizeOptions: {
+        label: string;
+        value: string;
+    }[];
     vapStatus: string;
     setVapStatus: Dispatch<SetStateAction<string>>;
     vapPage: number;
@@ -8187,8 +8359,9 @@ export declare function useWordTrainingFilter(groupKey: string, caps: WordTraini
 
 /**
  * @public 단어 검색 '글자 입력'의 형식 유효성 검사.
- * 허용: 완성 음절('가'), 초성/중성 자모('ㄱ'·'ㅏ'), 초성·중성·종성 3자모 템플릿('__ㄱ', 정확히 3글자),
- * 쉼표(,) 구분(빈 자리는 '무관'). 그 외(예: '_' 오용, 라틴 문자, 한 자리에 음소 4개 이상인 '___ㄱ')는 무효.
+ * 허용: 완성 음절('가'), 초성/중성 자모('ㄱ'·'ㅏ'), '_'가 든 한 음절 템플릿(1~4글자, 초성·중성·종성 순 —
+ * '__ㄱ'·'ㄱ_'·'ㄱ_ㄹㄱ'), 쉼표(,) 구분(빈 자리는 '무관'). 그 외(예: 5글자 이상 템플릿, 템플릿 자리에 맞지 않는
+ * 자모('ㅏ_'), 라틴 문자)는 무효.
  * @returns 유효하면 `{ ok: true }`, 아니면 `{ ok: false }`(호출부가 안내 문구를 표시).
  */
 export declare function validateSyllableSearchInput(input: string): {
@@ -8199,6 +8372,8 @@ export declare function validateSyllableSearchInput(input: string): {
 export declare const valueToJamos: (v: string) => string[];
 
 /**
+ * 개수 보기 옵션의 값 목록. 라벨은 한국어 고정이다 — 화면에는 훅이 돌려주는
+ * 번역된 `vapPageSizeOptions` 를 쓴다.
  * @public
  */
 export declare const VAP_PAGE_SIZE_OPTIONS: {
@@ -8234,6 +8409,21 @@ export declare type VisitItem = {
 /** @public */
 export declare type VisitStatus = 'visited' | 'scheduled' | 'noVisit';
 
+/** @public 눈금 끝(배). */
+export declare const WAVE_A_MAX = 2;
+
+/** @public 1배 막대 높이(px) — 지금까지의 파형 칸 높이. */
+export declare const WAVE_H1_PX = 45;
+
+/** @public 2배 막대 높이(px) — 카드 윗변·조작 줄을 넘지 않는 최대. */
+export declare const WAVE_HMAX_PX = 74;
+
+/** @public 막대 크기 a(0~2, 넘으면 자름) → 픽셀 높이. */
+export declare function waveBarPx(a: number): number;
+
+/** @public 막대 `--val` — 1배 높이(H1)에 대한 배율. 막대 ::after 는 H1 높이를 scaleY(--val) 한다. */
+export declare function waveBarVal(a: number): number;
+
 /** 낱말 하나에 대해 쌓인 성적. */
 export declare interface WeakItem {
     label: string;
@@ -8385,13 +8575,16 @@ export declare function WordDataProvider({ words, loading, error, statusMessage,
 }): JSX.Element;
 
 /** @public */
-export declare function WordDataUpdatePopup({ title, progress, onDone, onRetry, inline }: WordDataUpdatePopupProps): JSX.Element;
+export declare function WordDataUpdatePopup({ title, progress, onDone, onRetry, onClose, inline }: WordDataUpdatePopupProps): JSX.Element;
 
 declare interface WordDataUpdatePopupProps {
     title: string;
     progress: WordDataProgress;
     onDone: () => void;
+    /** 오류 때 '다시 시도' 단추가 부른다. 없으면 그 자리에 '닫기' 단추가 선다. */
     onRetry?: () => void;
+    /** 오류인데 `onRetry` 가 없을 때 '닫기' 단추가 부른다. 없으면 `onDone` 을 부른다. */
+    onClose?: () => void;
     inline?: boolean;
 }
 
@@ -8429,11 +8622,16 @@ declare interface WordEntry_2 {
 /** 설정 팝업 취소 시 되돌릴 필터 스냅샷 */
 export declare interface WordFilterSnapshot {
     composition: WordComposition;
+    /** 뜰 때의 대립 갯수. composition 에서 파생되므로 되돌릴 때는 읽지 않는다. */
     contrastCount: number;
     excludeNoImage: boolean;
     sameStructureOnly: boolean;
     phonemeView: 'char' | 'pron' | 'direct';
     gradeFilter: string[];
+    /** 품사 필터. 없으면(예전에 뜬 스냅샷) 되돌릴 때 지금 값을 그대로 둔다. */
+    posFilter?: string[];
+    /** 어종 필터. 없으면(예전에 뜬 스냅샷) 되돌릴 때 지금 값을 그대로 둔다. */
+    wordTypeFilter?: string[];
 }
 
 /** @public 단어의 모든 한글 음절에 종성(받침)이 없는지 (열린 음절로만 구성) */
@@ -8645,7 +8843,7 @@ export declare interface WordTableBlockProps {
     onReorder?: (fromIndex: number, toIndex: number) => void;
     /** display 모드에서도 칸 수 조절 허용 */
     showCellCount?: boolean;
-    /** display 모드에서 빈 슬롯에 추가하기 버튼 표시 */
+    /** display 모드에서 칸 수 안의 빈 칸에 추가하기 버튼 표시 → `renderWordSearch` 로 고른 첫 낱말을 새 항목으로 넘긴다. 칸 수는 `showCellCount` 로만 늘릴 수 있어 **함께 줘야** 빈 칸이 생긴다(없으면 칸 수 = 항목 수라 단추가 뜰 자리가 없다). */
     onAddItem?: (item: WordSearchResultItem) => void;
     className?: string;
     /** 저장 팝업 렌더러 */
@@ -8691,11 +8889,11 @@ export declare interface WordTableButtonProps {
     createdAt?: string;
     /** 스토어 발행 배지 표시 */
     published?: boolean;
-    /** 발행 배지 라벨(i18n 주입) */
+    /** 발행 배지 라벨. 없으면 사전 `myWordTable.publishedBadge`(기본 '발행됨'). */
     publishedLabel?: string;
     /** 활성 공유 링크 존재 배지 표시(썸네일 우상단) */
     shared?: boolean;
-    /** 공유 배지 라벨(i18n 주입) */
+    /** 공유 배지 라벨. 없으면 사전 `myWordTable.sharedBadge`(기본 '공유 중'). */
     sharedLabel?: string;
     /** 최근 생성·미열람 표 표시 — 우상단 원형 배지(circle badge) */
     isNew?: boolean;
@@ -8831,7 +9029,7 @@ export declare interface WordTableProps {
     onRemoveItem?: (id: string) => void;
     /** 표시 항목 드래그 재정렬 */
     onReorder?: (fromIndex: number, toIndex: number) => void;
-    /** 표시 모드 빈칸에 '추가' 버튼 노출 */
+    /** 표시 모드에서 `count` 안의 빈칸(항목 수 뒤 ~ count)에 '추가' 버튼 노출. count 가 항목 수와 같으면 그런 칸이 없다. `onActivateCell` 필요. */
     showFillerAdd?: boolean;
     /** 그리드 콘텐츠 DOM ref — 인쇄/캡처용 */
     contentRef?: Ref<HTMLDivElement>;
@@ -8954,4 +9152,8 @@ export declare type WordTrainingTypeKey = 'SAME_SOUND_PICK' | 'SAME_OR_DIFF' | '
  */
 export declare function wrongItems(items: readonly TrainingItemResult[]): TrainingItemResult[];
 
+declare type 비율설정 = Pick<CoreNoiseSettings, 'level' | 'mainVolume'> & {
+    noiseRatio?: number;
+};
+
 export { }