@ihabdevteam/core 0.141.0 → 0.143.0

package/dist/packages/core/src/components/barChartData.js

@@ -1,7 +1,11 @@
 /**
  * barChartData.ts
  * BarChart의 순수 데이터 계층 — 날짜→월/주/일 막대 데이터 집계 (React 무관).
+ *
+ * **날은 KST 달력으로 센다.** 칸은 `getFullYear()/getMonth()/getDate()` 로 나누므로 '지금'도 KST 오늘을 기기 달력 Date 로
+ * 옮긴 것(`getTodayKstDate`)을 쓴다 — 전에는 기기 시각이라 해외 기기에서 오늘·이번 주·이번 달이 KST 와 하루 어긋났다.
  */
+import { getTodayKstDate } from '../utils/date';
 /** 해당 월(0-based)의 첫 월요일 날짜(1~7). 예: 2026-05(금요일 시작) → 4 */
 export function firstMondayOfMonth(year, month0) {
     const dow = new Date(year, month0, 1).getDay(); // 0=일 … 6=토
@@ -10,7 +14,7 @@ export function firstMondayOfMonth(year, month0) {
 /** 오늘이 속한 (월키, 주값) 계산 — 진입 시 기본 선택을 오늘 기준으로 맞춤.
  *  월요일 시작 버킷 기준이며, 첫 월요일 이전 날짜는 이전 달 마지막 주에 속한다. */
 export function todayWeekValue() {
-    const now = new Date();
+    const now = getTodayKstDate();
     let y = now.getFullYear(), m0 = now.getMonth(), date = now.getDate();
     if (date < firstMondayOfMonth(y, m0)) {
         const prevLast = new Date(y, m0, 0); // 이전 달 마지막 날
@@ -35,7 +39,7 @@ export function todayWeekValue() {
  * 다음 달의 오늘 뒤 날은 세지 않는다. 일별(`daily`)은 그 달 날만이다.
  */
 export function buildMonthChartData(points) {
-    const now = new Date();
+    const now = getTodayKstDate();
     const curKey = `${now.getFullYear()}년 ${now.getMonth() + 1}월`;
     const 달키 = (y, m0) => `${y}년 ${m0 + 1}월`;
     const byMonth = new Map();
@@ -142,7 +146,7 @@ export function buildMonthChartData(points) {
 }
 // 드롭다운에 노출할 월 옵션 (2024년 1월 ~ 현재, 최신순)
 function genMonthOptions() {
-    const now = new Date();
+    const now = getTodayKstDate();
     const curY = now.getFullYear();
     const curM = now.getMonth() + 1;
     const opts = [];

package/dist/packages/core/src/components/barChartTypes.d.ts

@@ -88,8 +88,21 @@ export interface BarChartProps {
     /** CSS 격자 칸 안에 세운다 — 아래 여백·최소 폭을 풀고 막대를 카드 바닥에 맞춘다. ChartSection `inGrid` 참고. */
     inGrid?: boolean;
 }
-/** 현재 컨트롤 선택(주/월)의 날짜 범위 — 상세보기(기간별 리스트)용 */
-export declare function getControlDateRange(control: BarChartControl): {
+/** @public getControlDateRange 의 결과 — 기간의 첫날 00:00 KST ~ 끝날 23:59:59.999 KST 순간과, 그 두 날의 KST 달력 날짜 */
+export interface ControlDateRange {
+    /** 첫날 00:00:00.000 KST 순간 — 서버에 물을 때 `from.toISOString()` */
     from: Date;
+    /** 끝날 23:59:59.999 KST 순간 */
     to: Date;
-};
+    /** 첫날 KST 'YYYY-MM-DD' — 이름표·달력 셈은 `parseLocalYmd(fromYmd)` 로(순간 `from` 을 기기 getter 로 읽으면 해외에서 하루 어긋난다) */
+    fromYmd: string;
+    /** 끝날 KST 'YYYY-MM-DD' */
+    toYmd: string;
+}
+/**
+ * 현재 컨트롤 선택(주/월)의 기간 — 상세보기(기간별 리스트)용. **KST 의 날로 자른다**(해외 기기도 같은 기간).
+ *
+ * @param offset 몇 기간 앞·뒤인가 — `-1` 이면 앞 달 한 달(달력 달 그대로, 30일 앞이 아니다) · 앞 주 한 주.
+ * @public
+ */
+export declare function getControlDateRange(control: BarChartControl, offset?: number): ControlDateRange;

package/dist/packages/core/src/components/barChartTypes.js

@@ -1,23 +1,37 @@
 import { firstMondayOfMonth } from './barChartData';
-/** 현재 컨트롤 선택(주/월)의 날짜 범위 — 상세보기(기간별 리스트)용 */
-export function getControlDateRange(control) {
+import { getTodayKst, getTodayKstDate, kstStartOfDay } from '../utils/date';
+const ymdOf = (y, m0, d) => {
+    const t = new Date(Date.UTC(y, m0, d));
+    return `${t.getUTCFullYear()}-${String(t.getUTCMonth() + 1).padStart(2, '0')}-${String(t.getUTCDate()).padStart(2, '0')}`;
+};
+const 범위 = (y, m0, 첫날, 날수) => ({
+    from: kstStartOfDay(y, m0, 첫날),
+    // 끝은 그날의 **마지막 밀리초까지** — 23:59:59.000 이면 마지막 999ms 에 남은 기록이 목록에서 빠졌다
+    to: new Date(kstStartOfDay(y, m0, 첫날 + 날수).getTime() - 1),
+    fromYmd: ymdOf(y, m0, 첫날),
+    toYmd: ymdOf(y, m0, 첫날 + 날수 - 1),
+});
+/**
+ * 현재 컨트롤 선택(주/월)의 기간 — 상세보기(기간별 리스트)용. **KST 의 날로 자른다**(해외 기기도 같은 기간).
+ *
+ * @param offset 몇 기간 앞·뒤인가 — `-1` 이면 앞 달 한 달(달력 달 그대로, 30일 앞이 아니다) · 앞 주 한 주.
+ * @public
+ */
+export function getControlDateRange(control, offset = 0) {
     if (control.period === 'month') {
         const m = control.monthRange.match(/^(\d+)년 (\d+)월$/);
-        const now = new Date();
-        const y = m ? Number(m[1]) : now.getFullYear();
-        const mo = m ? Number(m[2]) : now.getMonth() + 1;
-        // 끝은 그날의 **마지막 밀리초까지** — 23:59:59.000 이면 마지막 999ms 에 남은 기록이 목록에서 빠졌다
-        return { from: new Date(y, mo - 1, 1, 0, 0, 0), to: new Date(y, mo, 0, 23, 59, 59, 999) };
+        const today = getTodayKstDate();
+        const y = m ? Number(m[1]) : today.getFullYear();
+        const m0 = (m ? Number(m[2]) : today.getMonth() + 1) - 1 + offset;
+        const 날수 = new Date(Date.UTC(y, m0 + 1, 0)).getUTCDate();
+        return 범위(y, m0, 1, 날수);
     }
     const opt = control.weekRanges.find(o => o.value === control.weekRange);
     if (!opt) {
         const n = new Date();
-        return { from: n, to: n };
+        const ymd = getTodayKst();
+        return { from: n, to: n, fromYmd: ymd, toYmd: ymd };
     }
     const firstMon = firstMondayOfMonth(opt.year, opt.month - 1);
-    const monday = new Date(opt.year, opt.month - 1, firstMon + opt.week * 7, 0, 0, 0);
-    const sunday = new Date(monday);
-    sunday.setDate(monday.getDate() + 6);
-    sunday.setHours(23, 59, 59, 999);
-    return { from: monday, to: sunday };
+    return 범위(opt.year, opt.month - 1, firstMon + (opt.week + offset) * 7, 7);
 }

package/dist/packages/core/src/components.d.ts

@@ -142,6 +142,7 @@ export { default as BarChart, BarChartControls } from './components/BarChart';
 export { useBarChartControl } from './components/useBarChartControl';
 export { buildMonthChartData } from './components/barChartData';
 export { getControlDateRange } from './components/barChartTypes';
+export type { ControlDateRange } from './components/barChartTypes';
 export type { BarChartProps, BarChartControl, BarChartSize, BarData, MonthBarData, ChartPoint } from './components/BarChart';
 export { default as RingChart } from './components/RingChart';
 export type { RingChartProps, RingChartSize, RingChartSegment } from './components/RingChart';

package/dist/packages/core/src/hooks/focusReturn.d.ts

@@ -0,0 +1,4 @@
+/** 창 판과, 그 창이 열릴 때 포커스였던 요소를 적는다 */
+export declare function rememberFocusReturn(panel: Element | null, previouslyFocused: HTMLElement | null): void;
+/** 실제로 돌려줄 곳 — 문서에 붙어 있으면 그대로, 떼어졌으면 그것을 품었던 창이 적어 둔 곳을 따라간다 */
+export declare function resolveFocusReturn(previouslyFocused: HTMLElement | null): HTMLElement | null;

package/dist/packages/core/src/hooks/focusReturn.js

@@ -0,0 +1,27 @@
+/**
+ * 창(Popup·Dialog·TrainingPagePopup)이 닫힐 때 포커스를 돌려줄 곳 — 창끼리 한 표를 쓴다.
+ *
+ * 창은 열릴 때 그때 포커스였던 요소를 기억했다가 닫힐 때 돌려준다. 그런데 **닫으면서 다음 창을 여는** 흐름
+ * (미리보기 → 삭제 확인)에서는 확인 창이 기억한 것이 미리보기 안의 삭제 단추이고, 그 단추는 260ms 뒤
+ * 미리보기와 함께 사라진다. 확인 창을 닫으면 떼어진 단추에 focus() 해 아무 일도 없이 body 에 떨어졌다.
+ * 각 창의 판(panel) → 그 창이 돌려줄 곳을 적어 두고, 돌려줄 곳이 떼어졌으면 그것을 품었던 창의 돌려줄 곳을 따라 올라간다.
+ */
+const 돌아갈곳표 = new WeakMap();
+/** 창 판과, 그 창이 열릴 때 포커스였던 요소를 적는다 */
+export function rememberFocusReturn(panel, previouslyFocused) {
+    if (panel)
+        돌아갈곳표.set(panel, previouslyFocused);
+}
+/** 실제로 돌려줄 곳 — 문서에 붙어 있으면 그대로, 떼어졌으면 그것을 품었던 창이 적어 둔 곳을 따라간다 */
+export function resolveFocusReturn(previouslyFocused) {
+    let 대상 = previouslyFocused;
+    for (let 번 = 0; 대상 && !대상.isConnected && 번 < 10; 번++) {
+        let 창 = 대상;
+        while (창 && !돌아갈곳표.has(창))
+            창 = 창.parentElement;
+        if (!창)
+            return 대상;
+        대상 = 돌아갈곳표.get(창) ?? null;
+    }
+    return 대상;
+}

package/dist/packages/core/src/hooks/inputModality.d.ts

@@ -0,0 +1,2 @@
+/** 마지막 입력이 키보드였으면 true(모르면 false) */
+export declare function 키보드로눌렀나(): boolean;

package/dist/packages/core/src/hooks/inputModality.js

@@ -0,0 +1,31 @@
+'use client';
+/*
+ * 마지막 입력이 **키보드였나** — 누른 단추가 사라지는 자리에서 초점을 옮길지 가를 때 쓴다.
+ *
+ * "초점이 누른 단추에 있었나" 로만 보면 Chrome·Edge·안드로이드는 마우스로 눌러도 단추에 초점이 가서, 마우스 사용자에게도
+ * 초점을 옮겨 그 단추의 초점 툴팁이 떴다(듣기 → '재생 / 멈춤', 문장 미리보기 → '글자 크기 감소'). Safari 는 누른 단추에 초점을
+ * 안 줘 body 에 남는다. 문서 전체에서 키 누름·포인터 누름을 들어 마지막 것을 기억한다(캡처 단계, 한 번만 붙인다).
+ */
+let 마지막 = null;
+let 붙음 = false;
+function 붙이기() {
+    if (붙음 || typeof document === 'undefined')
+        return;
+    붙음 = true;
+    document.addEventListener('keydown', (e) => {
+        if (e.metaKey || e.ctrlKey || e.altKey)
+            return;
+        마지막 = 'keyboard';
+    }, true);
+    const 포인터 = () => { 마지막 = 'pointer'; };
+    document.addEventListener('pointerdown', 포인터, true);
+    document.addEventListener('mousedown', 포인터, true);
+    document.addEventListener('touchstart', 포인터, { capture: true, passive: true });
+}
+// 불러오는 즉시 듣는다 — 첫 누름부터 알아야 한다
+붙이기();
+/** 마지막 입력이 키보드였으면 true(모르면 false) */
+export function 키보드로눌렀나() {
+    붙이기();
+    return 마지막 === 'keyboard';
+}

package/dist/packages/core/src/hooks/useDocumentTitle.d.ts

@@ -7,5 +7,17 @@
  * @public
  */
 export declare const DocumentTitleSuppressContext: import("react").Context<boolean>;
+/**
+ * 현재 화면의 제목을 `document.title`에 반영한다 — `'<제목> · <앱 이름>'`.
+ *
+ * SPA는 라우트를 옮겨도 문서 제목이 그대로라, 브라우저 탭·히스토리·북마크로 위치를
+ * 구분할 수 없고 화면낭독기도 이동을 인지하지 못한다(WCAG 2.4.2).
+ * 여러 화면이 함께 걸면 제목이 쌓여 가장 나중에 건 것이 보이고, 언마운트하면
+ * 남은 것 중 가장 나중에 건 제목으로(남은 것이 없으면 처음 제목으로) 되돌린다.
+ *
+ * @param title 페이지 제목. 비어 있거나 문자열이 아니면 아무것도 하지 않는다.
+ *
+ * @public
+ */
 export declare function useDocumentTitle(title?: string | null): void;
 export default useDocumentTitle;

package/dist/packages/core/src/hooks/useDocumentTitle.js

@@ -23,22 +23,23 @@ const BASE_TITLE = (() => {
  * @public
  */
 export const DocumentTitleSuppressContext = createContext(false);
+/* 제목을 건 화면들 — 나중에 건 것이 위. 떠날 때 **남은 맨 위 제목**으로 돌린다.
+   전에는 저마다 건 순간의 제목(prev)을 기억했다가 되돌려, A 가 떠 있는 동안 B 가 붙고 A 가 나중에 떠나면
+   A 의 prev 로 돌아가 B 의 제목이 지워졌다(말귀 CustomersPage 가 겪고 우회해 둠). */
+const 걸린제목 = [];
+let 처음제목 = null;
 /**
  * 현재 화면의 제목을 `document.title`에 반영한다 — `'<제목> · <앱 이름>'`.
  *
  * SPA는 라우트를 옮겨도 문서 제목이 그대로라, 브라우저 탭·히스토리·북마크로 위치를
  * 구분할 수 없고 화면낭독기도 이동을 인지하지 못한다(WCAG 2.4.2).
- * 언마운트하면 이전 제목으로 되돌린다.
+ * 여러 화면이 함께 걸면 제목이 쌓여 가장 나중에 건 것이 보이고, 언마운트하면
+ * 남은 것 중 가장 나중에 건 제목으로(남은 것이 없으면 처음 제목으로) 되돌린다.
  *
  * @param title 페이지 제목. 비어 있거나 문자열이 아니면 아무것도 하지 않는다.
  *
  * @public
  */
-/* 제목을 건 화면들 — 나중에 건 것이 위. 떠날 때 **남은 맨 위 제목**으로 돌린다.
-   전에는 저마다 건 순간의 제목(prev)을 기억했다가 되돌려, A 가 떠 있는 동안 B 가 붙고 A 가 나중에 떠나면
-   A 의 prev 로 돌아가 B 의 제목이 지워졌다(말귀 CustomersPage 가 겪고 우회해 둠). */
-const 걸린제목 = [];
-let 처음제목 = null;
 export function useDocumentTitle(title) {
     const suppressed = useContext(DocumentTitleSuppressContext);
     useEffect(() => {

package/dist/packages/core/src/hooks/useEditableList.js

@@ -27,9 +27,9 @@ export function useEditableList(emptyItem, initialList = []) {
     // 값만 캡처하므로 이 effect가 없으면 이후 prop 변경이 화면에 전혀 반영되지 않는다.
     // 단, 사용자가 이 목록의 항목을 수정 중(isEditing)일 때 리셋하면 아직 list에 반영되지
     // 않은 진행 중인 편집(editForm)이 저장 시 조용히 무시될 수 있으므로 그 사이엔 건너뛴다.
-    // isEditing은 ref로만 참조해 effect가 initialList 변경 시에만 실행되게 한다 — 편집을
-    // 끝내는 순간(isEditing만 바뀌는 렌더)에는 재실행되지 않아, 방금 커밋된 편집 결과가
-    // 곧바로 stale한 initialList로 덮어써지는 것도 막는다.
+    // effect 는 initialList 와 isEditing 둘 다에 걸려 있어 편집이 끝나는 렌더에서도 돈다 —
+    // 취소(cancelEditing)로 끝났으면 그 사이 건너뛴 목록을 받고, commitEdit 으로 끝났으면
+    // 방금 커밋한 편집을 옛 initialList 로 덮지 않도록 한 번 건너뛴다(아래 커밋으로끝남Ref).
     //
     // 비교는 참조가 아니라 **내용**으로 한다. 호출부가 배열을 인라인으로 넘기면
     // (useEditableList(EMPTY, [a, b]) — 가장 자연스러운 호출 방식이고, 인자를 생략해

package/dist/packages/core/src/hooks/useWordMeanings.js

@@ -47,9 +47,12 @@ export function useWordMeanings(rows, fetchMeanings) {
                 if (row.Meaning)
                     memCache.set(meaningKey(row.Word, row.Homonum ?? undefined), row.Meaning);
             }
-            for (const k of missing)
-                if (!memCache.has(k))
-                    noMeaning.add(k);
+            /* 한 줄도 못 받았으면 '뜻 없음' 으로 굳히지 않는다 — 조회 함수는 실패를 빈 배열로 돌려주는 약속이라, 잠깐 끊긴 망이
+               그 쪽 낱말들을 새로고침 전까지 '뜻 없음' 으로 묶었다. 받은 게 있으면 그 응답에 빠진 낱말만 없는 것으로 본다. */
+            if (got.length > 0)
+                for (const k of missing)
+                    if (!memCache.has(k))
+                        noMeaning.add(k);
             if (cancelled || got.length === 0)
                 return;
             setFetched(v => v + 1);

package/dist/packages/core/src/hooks/useWordTrainingFilter.d.ts

@@ -11,9 +11,9 @@ export interface WordFilterSnapshot {
     sameStructureOnly: boolean;
     phonemeView: 'char' | 'pron' | 'direct';
     gradeFilter: string[];
-    /** 품사 필터. 없으면(예전에 뜬 스냅샷) 되돌릴 때 지금 값을 그대로 둔다. */
+    /** 품사 필터 — 고정 코드(noun·verb·modifier). 라벨(옛 스냅샷)도 받는다. 없으면 되돌릴 때 지금 값을 그대로 둔다. */
     posFilter?: string[];
-    /** 어종 필터. 없으면(예전에 뜬 스냅샷) 되돌릴 때 지금 값을 그대로 둔다. */
+    /** 어종 필터 — 고정 코드(native·sino·foreign·mixed). 라벨(옛 스냅샷)도 받는다. 없으면 되돌릴 때 지금 값을 그대로 둔다. */
     wordTypeFilter?: string[];
 }
 /**

package/dist/packages/core/src/hooks/useWordTrainingFilter.js

@@ -15,6 +15,25 @@ export { valueToJamos, NO_CODA, SYLLABLE_MIN, syllableToFilter, charToPronValue,
 // ─── localStorage 지속성 ────────────────────────────────────────────────────
 const LEGACY_STORAGE_KEY = 'wt_filter';
 const storageKey = (groupKey) => `wt_filter_${groupKey}`;
+/* 품사·어종은 **고정 코드**로 든다(상태·저장소·스냅샷). 전에는 번역된 라벨('체언(명사, 수사)')을 그대로 담아, 화면을 연 채
+   언어가 바뀌면(말귀: 고객 세션 시작·종료가 그 사람의 표시 언어를 적용) 영어 posMap 에 옛 한국어 값이 없어 **모든 단어가
+   떨어졌고** 칩은 꺼진 채로 보였다. 순서는 useWordAttributeFilterKeys 의 posMap·typeMap 열쇠 순서와 같다. */
+const POS_CODES = ['noun', 'verb', 'modifier'];
+const TYPE_CODES = ['native', 'sino', 'foreign', 'mixed'];
+/** 코드 또는 (옛 저장값·스냅샷의) 어느 언어 라벨이든 코드 배열로 */
+function toAttrCodes(values, codes, kind, labelOf, lngs) {
+    if (!Array.isArray(values))
+        return [];
+    const out = [];
+    for (const v of values) {
+        if (typeof v !== 'string')
+            continue;
+        const code = codes.includes(v) ? v : codes.find(c => lngs.some(lng => labelOf(lng, `wordSearch.filter.${kind}.${c}`) === v));
+        if (code && !out.includes(code))
+            out.push(code);
+    }
+    return out;
+}
 function loadSavedFilter(groupKey) {
     try {
         // 그룹별 저장값 우선, 없으면 레거시 공통 저장값으로 폴백
@@ -102,8 +121,12 @@ export function useWordTrainingFilter(groupKey, caps, opts) {
     // 난이도 등급('1'~'4') 필터 — 배열(다중 선택), 빈 배열은 전체(무제약)
     const [gradeFilter, setGradeFilter] = useState(Array.isArray(saved?.gradeFilter) ? saved.gradeFilter : []);
     // 품사/어종 필터 — 단어표·대립쌍표와 동일 라벨 배열(다중 선택). caps로 노출 여부 결정(기본 미노출).
-    const [posFilter, setPosFilter] = useState(Array.isArray(saved?.posFilter) ? saved.posFilter : []);
-    const [wordTypeFilter, setWordTypeFilter] = useState(Array.isArray(saved?.wordTypeFilter) ? saved.wordTypeFilter : []);
+    const 라벨언어들 = Array.from(new Set([i18n.language, 'ko', 'en'].filter(Boolean)));
+    const labelOf = (lng, key) => i18n.getFixedT(lng)(key);
+    const posCodesOf = (v) => toAttrCodes(v, POS_CODES, 'pos', labelOf, 라벨언어들);
+    const typeCodesOf = (v) => toAttrCodes(v, TYPE_CODES, 'type', labelOf, 라벨언어들);
+    const [posCodes, setPosCodes] = useState(() => posCodesOf(saved?.posFilter));
+    const [typeCodes, setTypeCodes] = useState(() => typeCodesOf(saved?.wordTypeFilter));
     // 훈련 타입(resetKey) 변경 시 필터를 그 타입 기본값으로 초기화 — 이전 타입의 고정값(음절수/받침/한음절 시드)이
     // 새 타입으로 새어들어 엉뚱한 결과(예: 3음절 훈련에 1음절 필터가 남아 0건)가 나오는 것을 막는다.
     // 초기 마운트는 useState 기본값이 이미 처리하므로 ref로 첫 발화를 건너뛴다.
@@ -117,12 +140,17 @@ export function useWordTrainingFilter(groupKey, caps, opts) {
         setExcludeNoImage(!!opts?.defaultImageOnly);
         setSameStructureOnly(false);
         setGradeFilter([]);
-        setPosFilter([]);
-        setWordTypeFilter([]);
+        setPosCodes([]);
+        setTypeCodes([]);
         // seedComposition은 caps에서 파생 — resetKey와 함께 갱신되므로 deps는 resetKey만 둔다.
         // eslint-disable-next-line react-hooks/exhaustive-deps
     }, [opts?.resetKey]);
     const attrKeys = useWordAttributeFilterKeys();
+    // 밖으로는(판 선택값·반환값·판정) 지금 언어의 라벨로 보인다
+    const posLabels = useMemo(() => Object.keys(attrKeys.posMap), [attrKeys]);
+    const typeLabels = useMemo(() => Object.keys(attrKeys.typeMap), [attrKeys]);
+    const posFilter = useMemo(() => posCodes.map(c => posLabels[POS_CODES.indexOf(c)]).filter(Boolean), [posCodes, posLabels]);
+    const wordTypeFilter = useMemo(() => typeCodes.map(c => typeLabels[TYPE_CODES.indexOf(c)]).filter(Boolean), [typeCodes, typeLabels]);
     const [viable, setViable] = useState({ cho: new Set(), jung: new Set(), jong: new Set(), syllable: new Set() });
     // viable 자모 데이터가 최초 로드되기 전에는 저장된 선택을 해제하지 않는다
     const [viableReady, setViableReady] = useState(false);
@@ -160,8 +188,8 @@ export function useWordTrainingFilter(groupKey, caps, opts) {
             // 마운트 때와 같은 규칙 — 여기서만 'direct' 를 'char' 로 떨구고 있었다
             setPhonemeView(readPhonemeView(s));
             setGradeFilter(Array.isArray(s?.gradeFilter) ? s.gradeFilter : []);
-            setPosFilter(Array.isArray(s?.posFilter) ? s.posFilter : []);
-            setWordTypeFilter(Array.isArray(s?.wordTypeFilter) ? s.wordTypeFilter : []);
+            setPosCodes(posCodesOf(s?.posFilter));
+            setTypeCodes(typeCodesOf(s?.wordTypeFilter));
         }
         setHydratedKey(groupKey);
         // seedComposition 은 caps 파생이라 groupKey 와 함께 갱신된다
@@ -175,10 +203,10 @@ export function useWordTrainingFilter(groupKey, caps, opts) {
         if (hydratedKey !== groupKey)
             return; // 새 열쇠를 아직 안 얹었다 — 지금 쓰면 앞 그룹 값을 덮는다
         try {
-            localStorage.setItem(storageKey(groupKey), JSON.stringify({ contrastCount, composition, excludeNoImage, sameStructureOnly, phonemeView, gradeFilter, posFilter, wordTypeFilter }));
+            localStorage.setItem(storageKey(groupKey), JSON.stringify({ contrastCount, composition, excludeNoImage, sameStructureOnly, phonemeView, gradeFilter, posFilter: posCodes, wordTypeFilter: typeCodes }));
         }
         catch { }
-    }, [opts?.resetOnMount, groupKey, hydratedKey, contrastCount, composition, excludeNoImage, sameStructureOnly, phonemeView, gradeFilter, posFilter, wordTypeFilter]);
+    }, [opts?.resetOnMount, groupKey, hydratedKey, contrastCount, composition, excludeNoImage, sameStructureOnly, phonemeView, gradeFilter, posCodes, typeCodes]);
     const [poolVersion, setPoolVersion] = useState(0);
     // 단어 풀 갱신 이벤트 구독
     useWindowEvent('wordpool:update', () => setPoolVersion(v => v + 1));
@@ -479,18 +507,24 @@ export function useWordTrainingFilter(groupKey, caps, opts) {
         else if (sectionLabel === attrKeys.partOfSpeech) {
             // 품사 — 다중 토글(단어표·대립쌍표와 동일 방식: 라벨 배열)
             if (!value || value === FILTER_ALL_VALUE) {
-                setPosFilter([]);
+                setPosCodes([]);
                 return;
             }
-            setPosFilter(prev => prev.includes(value) ? prev.filter(v => v !== value) : [...prev, value]);
+            const code = POS_CODES[posLabels.indexOf(value)] ?? posCodesOf([value])[0];
+            if (!code)
+                return;
+            setPosCodes(prev => prev.includes(code) ? prev.filter(v => v !== code) : [...prev, code]);
         }
         else if (sectionLabel === attrKeys.wordType) {
             // 어종 — 다중 토글(단어표·대립쌍표와 동일 방식: 라벨 배열)
             if (!value || value === FILTER_ALL_VALUE) {
-                setWordTypeFilter([]);
+                setTypeCodes([]);
                 return;
             }
-            setWordTypeFilter(prev => prev.includes(value) ? prev.filter(v => v !== value) : [...prev, value]);
+            const code = TYPE_CODES[typeLabels.indexOf(value)] ?? typeCodesOf([value])[0];
+            if (!code)
+                return;
+            setTypeCodes(prev => prev.includes(code) ? prev.filter(v => v !== code) : [...prev, code]);
         }
         else {
             const part = partByLabel[sectionLabel];
@@ -506,7 +540,9 @@ export function useWordTrainingFilter(groupKey, caps, opts) {
                 return { ...prev, [part]: value };
             });
         }
-    }, [LABELS, partByLabel, attrKeys, caps.requireSyllable]);
+        // posCodesOf·typeCodesOf 는 i18n 에서만 파생 — 라벨 목록과 함께 바뀐다
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [LABELS, partByLabel, attrKeys, posLabels, typeLabels, caps.requireSyllable]);
     // 품사/어종 판정 — 단어표·대립쌍표가 쓰는 공용 predicate(matchesFilters)를 재사용한다.
     // filterSelected엔 품사/어종 key만 채워 넘기므로(등급·음절수는 undefined) 그 두 축만 판정한다.
     // 호출부(TrainingSetPage)는 이 함수로 자신의 후보 단어 필터링(filteredWords)에 품사/어종을 반영한다.
@@ -533,8 +569,8 @@ export function useWordTrainingFilter(groupKey, caps, opts) {
     // 품사·어종도 함께 뜬다 — 빠져 있어서 설정 팝업에서 취소해도 그 둘만 되돌아가지 않았다.
     // contrastCount 는 composition 에서 파생되므로 되돌릴 때 따로 세우지 않는다.
     const getFilterSnapshot = useCallback(() => ({
-        composition, contrastCount, excludeNoImage, sameStructureOnly, phonemeView, gradeFilter, posFilter, wordTypeFilter,
-    }), [composition, contrastCount, excludeNoImage, sameStructureOnly, phonemeView, gradeFilter, posFilter, wordTypeFilter]);
+        composition, contrastCount, excludeNoImage, sameStructureOnly, phonemeView, gradeFilter, posFilter: posCodes, wordTypeFilter: typeCodes,
+    }), [composition, contrastCount, excludeNoImage, sameStructureOnly, phonemeView, gradeFilter, posCodes, typeCodes]);
     const restoreFilterSnapshot = useCallback((s) => {
         setComposition(s.composition);
         setExcludeNoImage(s.excludeNoImage);
@@ -542,9 +578,10 @@ export function useWordTrainingFilter(groupKey, caps, opts) {
         setPhonemeView(s.phonemeView);
         setGradeFilter(Array.isArray(s.gradeFilter) ? s.gradeFilter : []);
         if (Array.isArray(s.posFilter))
-            setPosFilter(s.posFilter);
+            setPosCodes(posCodesOf(s.posFilter));
         if (Array.isArray(s.wordTypeFilter))
-            setWordTypeFilter(s.wordTypeFilter);
+            setTypeCodes(typeCodesOf(s.wordTypeFilter));
+        // eslint-disable-next-line react-hooks/exhaustive-deps
     }, []);
     return {
         difficulty,

package/dist/packages/core/src/utils/date.d.ts

@@ -28,11 +28,29 @@ export declare function formatDatetimeKo(iso: string): string;
 export declare function toKstHm(when?: string | number | Date | null): string;
 /** KST(Asia/Seoul) 기준 오늘 날짜를 'YYYY-MM-DD'로 반환. DB 날짜 비교 기준선으로 사용. */
 export declare function getTodayKst(): string;
+/**
+ * KST 오늘을 **기기 달력의 자정 Date** 로 — 연·월·일 칸을 `getFullYear()/getMonth()/getDate()` 로 세는 곳(BarChart)의
+ * '지금'. 칸에 넣는 자료도 같은 모양(`parseLocalYmd(toKstYmd(시각))`)이어야 해외 기기에서도 KST 의 날에 선다.
+ *
+ * @public
+ */
+export declare function getTodayKstDate(): Date;
+/**
+ * KST 달력 날짜(연, 0부터 세는 월, 일)의 **00:00 KST 순간.** 일·월은 넘쳐도 된다(`Date.UTC` 처럼 — 32일은 다음 달 1일).
+ * 서버에 기간을 물을 때(`toISOString()`) 기기 시간대가 아니라 KST 의 하루로 자르려고 쓴다.
+ *
+ * @public
+ */
+export declare function kstStartOfDay(year: number, month0: number, day: number): Date;
 /**
  * 'YYYY-MM-DD' 날짜 전용 문자열(예: 서버가 KST 기준으로 집계해 내려주는 log_date)을
  * 로컬 타임존 자정 Date로 파싱한다. new Date('YYYY-MM-DD')는 UTC 자정으로 해석되어,
  * UTC보다 서쪽 시간대(예: 미국)에서 getDate()/getMonth() 같은 로컬 getter로 읽으면
  * 하루 전으로 밀린다 — 차트를 날짜별로 버킷팅할 때 특히 문제가 된다.
+ *
+ * 시각(ISO)에서 KST 의 날을 달력 Date 로 얻으려면 `parseLocalYmd(toKstYmd(시각))`.
+ *
+ * @public
  */
 export declare function parseLocalYmd(ymd: string): Date;
 /**

package/dist/packages/core/src/utils/date.js

@@ -98,11 +98,34 @@ export function toKstHm(when) {
 export function getTodayKst() {
     return toKstYmd(new Date());
 }
+/**
+ * KST 오늘을 **기기 달력의 자정 Date** 로 — 연·월·일 칸을 `getFullYear()/getMonth()/getDate()` 로 세는 곳(BarChart)의
+ * '지금'. 칸에 넣는 자료도 같은 모양(`parseLocalYmd(toKstYmd(시각))`)이어야 해외 기기에서도 KST 의 날에 선다.
+ *
+ * @public
+ */
+export function getTodayKstDate() {
+    return parseLocalYmd(getTodayKst());
+}
+const KST_OFFSET_MS = 9 * 60 * 60 * 1000; // KST 는 일광 절약 시간이 없다
+/**
+ * KST 달력 날짜(연, 0부터 세는 월, 일)의 **00:00 KST 순간.** 일·월은 넘쳐도 된다(`Date.UTC` 처럼 — 32일은 다음 달 1일).
+ * 서버에 기간을 물을 때(`toISOString()`) 기기 시간대가 아니라 KST 의 하루로 자르려고 쓴다.
+ *
+ * @public
+ */
+export function kstStartOfDay(year, month0, day) {
+    return new Date(Date.UTC(year, month0, day) - KST_OFFSET_MS);
+}
 /**
  * 'YYYY-MM-DD' 날짜 전용 문자열(예: 서버가 KST 기준으로 집계해 내려주는 log_date)을
  * 로컬 타임존 자정 Date로 파싱한다. new Date('YYYY-MM-DD')는 UTC 자정으로 해석되어,
  * UTC보다 서쪽 시간대(예: 미국)에서 getDate()/getMonth() 같은 로컬 getter로 읽으면
  * 하루 전으로 밀린다 — 차트를 날짜별로 버킷팅할 때 특히 문제가 된다.
+ *
+ * 시각(ISO)에서 KST 의 날을 달력 Date 로 얻으려면 `parseLocalYmd(toKstYmd(시각))`.
+ *
+ * @public
  */
 export function parseLocalYmd(ymd) {
     const [y, m, d] = ymd.split('-').map(Number);

package/dist/packages/core/src/utils/format.js

@@ -9,7 +9,8 @@ import { toKstYmd } from './date';
  * 입력에 대시가 있든 없든, 어떤 포맷이든 처리.
  */
 export function formatPhone(raw) {
-    const all = raw.replace(/\D/g, '');
+    // 전각 숫자(한글 IME 전각 모드 '０１０')는 \D 에 걸려 통째로 사라졌다 — NFKC 로 반각으로 바꾼 뒤 걸러낸다
+    const all = raw.normalize('NFKC').replace(/\D/g, '');
     /* **앞자리가 네 자리인 번호.** 050X 안심번호·0303 착신전환은 열두 자리까지 가고, 앞자리를 세 자리로 보면
        `0507-1234-5678` 이 `050-7123-4567` 이 되어 **마지막 한 자리가 사라진 채** 멀쩡한 모양으로 저장됐다
        (말귀가 formatPhoneKr 로 감싸 두었다 — 이제 걷어도 된다). */

package/dist/packages/core/src/utils/imageConfig.d.ts

@@ -38,6 +38,8 @@ export declare function getImageExistenceStats(): {
     total: number;
     exists: number;
 } | null;
+/** @internal 동음이의 번호 없이(=1) '이미지 있음' 으로 확인된 낱말 집합 — 캐시 판마다 한 번 만든다. 돌려받은 집합을 고치지 말 것. */
+export declare function getImageOkWordSet(): ReadonlySet<string>;
 /**
  * @public
  * 이미지 존재 여부를 일괄 주입 (storage.list() 결과 등 외부에서 미리 계산한 경우).

package/dist/packages/core/src/utils/imageConfig.js

@@ -1,3 +1,4 @@
+import { timeoutSignal } from './timeoutSignal';
 const GLOBAL_KEY = '__ihab_core_image_config__';
 /** @public */
 export function configureImageResolver(resolver) {
@@ -10,13 +11,23 @@ export function getImageResolver() {
 // ─── 로컬 캐싱 (localStorage + 메모리) ───────────────────────────────────────
 const LS_KEY = 'word_image_existence_map_v1';
 let memMap = null;
+/* 캐시가 바뀔 때마다 오르는 판 번호 — 통계·'있음' 낱말 집합을 판마다 한 번만 센다(단어훈련 칩 한 번에 유형 수만큼
+   2.3만 칸을 훑었다). 캐시를 바꾸는 곳(확인 결과 담기·일괄 주입·비우기)은 모두 판을 올린다. */
+let 캐시판 = 0;
+let 통계판 = -1;
+let 통계값 = null;
+let 있음판 = -1;
+let 있음집합 = new Set();
 const inflight = new Map(); // 중복 fetch 방지
 function ensureLoaded() {
     if (memMap)
         return memMap;
     try {
         const raw = (typeof localStorage !== 'undefined') ? localStorage.getItem(LS_KEY) : null;
-        memMap = raw ? JSON.parse(raw) : {};
+        const v = raw ? JSON.parse(raw) : null;
+        /* 객체가 아닌 JSON(null·"x"·42·배열)이 들어 있으면 `k in map`·Object.values 가 부를 때마다 던지고 memMap 이 null 로 남아
+           매번 다시 파싱했다 — 확장 프로그램·손으로 고친 값이라도 캐시 비우기 전까지 이미지 확인·훈련 생성이 막혔다. */
+        memMap = v && typeof v === 'object' && !Array.isArray(v) ? v : {};
     }
     catch {
         memMap = {};
@@ -62,13 +73,14 @@ export async function checkImageExists(word, homonum) {
     // 검색 버튼(이미지 있음 필터)이 영구 비활성화된다
     /* **확인이 안 된 것은 캐시하지 않는다.** 망 끊김·타임아웃·5xx 까지 '이미지 없음' 으로 영구 저장해, 한 번 끊긴 단어는 망이
        돌아와도 '이미지 있음' 필터에서 계속 빠졌다(ttsConfig.checkAudioExists 와 같게). 있음(2xx)·없음(4xx)만 담는다. */
-    const p = fetch(url, { method: 'HEAD', signal: AbortSignal.timeout(8000) })
+    const p = fetch(url, { method: 'HEAD', signal: timeoutSignal(8000) })
         .then(res => (res.status >= 500 ? null : res.ok), () => null)
         .then(ok => {
         inflight.delete(k);
         if (ok === null)
             return false;
         map[k] = ok;
+        캐시판++;
         scheduleSave();
         return ok;
     });
@@ -131,10 +143,25 @@ export async function prewarmImageCache(words, options = {}) {
  */
 export function getImageExistenceStats() {
     const map = ensureLoaded();
+    if (통계판 === 캐시판)
+        return 통계값 ? { ...통계값 } : null;
     const values = Object.values(map);
-    if (values.length === 0)
-        return null;
-    return { total: values.length, exists: values.filter(Boolean).length };
+    통계값 = values.length === 0 ? null : { total: values.length, exists: values.filter(Boolean).length };
+    통계판 = 캐시판;
+    return 통계값 ? { ...통계값 } : null;
+}
+/** @internal 동음이의 번호 없이(=1) '이미지 있음' 으로 확인된 낱말 집합 — 캐시 판마다 한 번 만든다. 돌려받은 집합을 고치지 말 것. */
+export function getImageOkWordSet() {
+    const map = ensureLoaded();
+    if (있음판 === 캐시판)
+        return 있음집합;
+    const s = new Set();
+    for (const k in map)
+        if (map[k] === true && k.endsWith('_1'))
+            s.add(k.slice(0, -2));
+    있음집합 = s;
+    있음판 = 캐시판;
+    return s;
 }
 /**
  * @public
@@ -144,6 +171,7 @@ export function getImageExistenceStats() {
 export function bulkSetImageExistence(entries) {
     const map = ensureLoaded();
     Object.assign(map, entries);
+    캐시판++;
     try {
         if (typeof localStorage !== 'undefined') {
             localStorage.setItem(LS_KEY, JSON.stringify(map));
@@ -154,6 +182,7 @@ export function bulkSetImageExistence(entries) {
 /** @public 캐시 초기화 (이미지 데이터 변경 시 호출) */
 export function clearImageExistenceCache() {
     memMap = {};
+    캐시판++;
     try {
         if (typeof localStorage !== 'undefined')
             localStorage.removeItem(LS_KEY);

package/dist/packages/core/src/utils/josa.js

@@ -5,6 +5,8 @@ const VOWEL_JAMO = /[ㅏ-ㅣ]/;
 // 문자열 끝의 실제 한글(음절 또는 낱자모) 글자를 찾는다 — 따옴표 등 뒤에 붙는
 // 문장부호는 건너뛴다(예: "'ㄹ'"의 마지막 문자는 "'"지만 판정에 쓸 글자는 "ㄹ").
 function lastHangulChar(text) {
+    // 조각 한글(NFD) 끝 받침(U+11A8~)은 음절 범위에도 호환 자모에도 안 들어 기본값('가'·'를')으로 떨어졌다
+    text = text.normalize('NFC');
     for (let i = text.length - 1; i >= 0; i--) {
         const ch = text[i];
         const code = ch.charCodeAt(0);