@ihabdevteam/core 0.142.0 → 0.143.0

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);

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

@@ -50,6 +50,11 @@ export declare function matchesChoseongSearch(text: string, search: string): boo
  * 검색어에 종성 겹자모·비한글 등 위 종류가 아닌 문자가 있으면 일반 부분 문자열로 폴백한다.
  */
 export declare function matchesWordQuery(word: string, query: string): boolean;
+/**
+ * @internal matchesWordQuery 의 검색어 쪽 준비(NFC·글자 분류)를 **한 번만** 해 두고 낱말마다 부르는 판별기.
+ * 목록 전체(2.3만 낱말)를 거를 때 낱말마다 검색어를 다시 펼치고 분류해, 키를 누를 때마다 14–36ms 걸렸다.
+ */
+export declare function makeWordQueryMatcher(query: string): (word: string) => boolean;
 /** @public 복합 종성 index → 구성 자모 배열 (예: 9(ㄺ) → ['ㄹ','ㄱ']) */
 export declare const JONG_DECOMPOSE: Record<number, string[]>;
 /** @public 단어가 특정 자모(음소)를 어디든 (초성/종성/복합종성) 포함하는지 */

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

@@ -100,6 +100,9 @@ export function isAllChoseong(search) {
 export function matchesChoseongSearch(text, search) {
     if (!search)
         return true;
+    /* 맥·PDF 에서 붙여넣은 글은 조각 한글(NFD, '가' = ᄀ+ᅡ)이라 완성 음절과 한 글자도 같지 않다 — 둘 다 NFC 로 맞춘다. */
+    text = text.normalize('NFC');
+    search = search.normalize('NFC');
     if (isAllChoseong(search))
         return toChoseong(text).includes(search);
     return text.toLowerCase().includes(search.toLowerCase());
@@ -112,55 +115,69 @@ export function matchesChoseongSearch(text, search) {
  * 검색어에 종성 겹자모·비한글 등 위 종류가 아닌 문자가 있으면 일반 부분 문자열로 폴백한다.
  */
 export function matchesWordQuery(word, query) {
+    return makeWordQueryMatcher(query)(word);
+}
+/**
+ * @internal matchesWordQuery 의 검색어 쪽 준비(NFC·글자 분류)를 **한 번만** 해 두고 낱말마다 부르는 판별기.
+ * 목록 전체(2.3만 낱말)를 거를 때 낱말마다 검색어를 다시 펼치고 분류해, 키를 누를 때마다 14–36ms 걸렸다.
+ */
+export function makeWordQueryMatcher(query) {
     if (!query)
-        return true;
+        return () => true;
+    // 조각 한글(NFD) 붙여넣기는 '기타 문자' 로 분류돼 부분 문자열 비교로 새고 0건이 됐다 — 둘 다 NFC 로
+    query = query.normalize('NFC');
     const q = [...query];
     const isCho = (ch) => CHOSEONG.includes(ch);
     const isJung = (ch) => JUNGSEONG.includes(ch);
     // 각 글자 분류: 'cho'(자음/초성) | 'jung'(모음/중성) | 'syl'(완성 음절) | 'other'(그 외)
     const kinds = q.map(ch => (isCho(ch) ? 'cho' : isJung(ch) ? 'jung' : parseSyllable(ch) ? 'syl' : 'other'));
+    const qSyl = q.map(ch => parseSyllable(ch));
     // 영문은 대소문자를 가리지 않는다 — 옆 matchesChoseongSearch 와 같게('apple' 로 'Apple' 을 찾는다)
-    if (kinds.includes('other'))
-        return word.toLowerCase().includes(query.toLowerCase());
-    const w = [...word];
-    for (let i = 0; i + q.length <= w.length; i++) {
-        let ok = true;
-        for (let j = 0; j < q.length; j++) {
-            const wc = w[i + j];
-            const k = kinds[j];
-            if (k === 'cho') {
-                if (firstChoseongOf(wc) !== q[j]) {
-                    ok = false;
-                    break;
-                }
-            }
-            else if (k === 'jung') {
-                const s = parseSyllable(wc);
-                if (!s || JUNGSEONG[s.jung] !== q[j]) {
-                    ok = false;
-                    break;
+    if (kinds.includes('other')) {
+        const lower = query.toLowerCase();
+        return (word) => word.normalize('NFC').toLowerCase().includes(lower);
+    }
+    return (word) => {
+        const w = [...word.normalize('NFC')];
+        for (let i = 0; i + q.length <= w.length; i++) {
+            let ok = true;
+            for (let j = 0; j < q.length; j++) {
+                const wc = w[i + j];
+                const k = kinds[j];
+                if (k === 'cho') {
+                    if (firstChoseongOf(wc) !== q[j]) {
+                        ok = false;
+                        break;
+                    }
                 }
-            }
-            else { // 'syl' — 완성 음절
-                const qs = parseSyllable(q[j]);
-                if (qs && qs.jong === 0) {
-                    // 받침 없는 글자는 초성+중성만 비교(받침 무관): '수' → 수·술·숙·순 …
-                    const ws = parseSyllable(wc);
-                    if (!ws || ws.cho !== qs.cho || ws.jung !== qs.jung) {
+                else if (k === 'jung') {
+                    const s = parseSyllable(wc);
+                    if (!s || JUNGSEONG[s.jung] !== q[j]) {
                         ok = false;
                         break;
                     }
                 }
-                else if (wc !== q[j]) {
-                    ok = false;
-                    break;
-                } // 받침 있으면 정확 일치
+                else { // 'syl' — 완성 음절
+                    const qs = qSyl[j];
+                    if (qs && qs.jong === 0) {
+                        // 받침 없는 글자는 초성+중성만 비교(받침 무관): '수' → 수·술·숙·순 …
+                        const ws = parseSyllable(wc);
+                        if (!ws || ws.cho !== qs.cho || ws.jung !== qs.jung) {
+                            ok = false;
+                            break;
+                        }
+                    }
+                    else if (wc !== q[j]) {
+                        ok = false;
+                        break;
+                    } // 받침 있으면 정확 일치
+                }
             }
+            if (ok)
+                return true;
         }
-        if (ok)
-            return true;
-    }
-    return false;
+        return false;
+    };
 }
 // 복합 종성 자모 분해 (예: ㄺ → ㄹ+ㄱ)
 /** @public 복합 종성 index → 구성 자모 배열 (예: 9(ㄺ) → ['ㄹ','ㄱ']) */
@@ -418,6 +435,8 @@ function matchesPatternAtom(ch, atom) {
  * 0건이 된다(조용히 무관 처리하지 않는다 — 제약이 무시된 채 결과가 나오는 오해를 막기 위해).
  */
 export function matchesSyllablePattern(word, pattern) {
+    word = word.normalize('NFC');
+    pattern = pattern.normalize('NFC'); // 조각 한글(NFD) 붙여넣기
     const atoms = pattern.split(',').flatMap(chunk => parseChunkToAtoms(chunk.trim()));
     if (atoms.length === 0)
         return true;
@@ -497,7 +516,8 @@ function isSearchAtomChar(ch) {
  * @returns 유효하면 `{ ok: true }`, 아니면 `{ ok: false }`(호출부가 안내 문구를 표시).
  */
 export function validateSyllableSearchInput(input) {
-    const trimmed = input.trim();
+    // 조각 한글(NFD) 붙여넣기가 '해석할 수 없는 글자' 로 입력 오류 안내를 띄웠다
+    const trimmed = input.normalize('NFC').trim();
     if (!trimmed)
         return { ok: true };
     for (const raw of trimmed.split(',')) {
@@ -643,16 +663,22 @@ export function countPhonemeDiff(a, b) {
  * @public
  */
 export function searchAndRankWords(items, query) {
-    const q = query.trim();
+    const q = query.normalize('NFC').trim(); // 조각 한글(NFD) 붙여넣기
     if (!q || !/[^\s,_]/.test(q))
         return items;
     if (isSyllablePattern(q))
         return items.filter(w => matchesSyllablePattern(w.word, q));
-    const hit = items.filter(w => matchesWordQuery(w.word, q) || matchesWordQuery(w.pronunciation ?? '', q));
+    // 검색어 준비는 한 번 — 낱말마다 다시 하면 키 한 번에 2.3만 번 펼치고 분류했다
+    const m = makeWordQueryMatcher(q);
     const headLen = [...q].length;
-    const startsWith = (s) => !!s && matchesWordQuery(s.slice(0, headLen), q);
-    return hit
-        .map(w => ({ w, rank: (startsWith(w.word) || startsWith(w.pronunciation ?? '')) ? 0 : 1 }))
-        .sort((a, b) => a.rank - b.rank)
-        .map(s => s.w);
+    const startsWith = (s) => !!s && m(s.normalize('NFC').slice(0, headLen));
+    // 순위는 두 갈래로 나눠 잇는다(안정 정렬과 같은 순서)
+    const 앞 = [];
+    const 뒤 = [];
+    for (const w of items) {
+        if (!(m(w.word) || m(w.pronunciation ?? '')))
+            continue;
+        (startsWith(w.word) || startsWith(w.pronunciation ?? '') ? 앞 : 뒤).push(w);
+    }
+    return 앞.concat(뒤);
 }

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

@@ -484,9 +484,26 @@ preferAsTarget) {
         for (let p = 0; p < target.syls.length; p++) {
             const key = makeKey(target.syls, p);
             const candidates = groups.get(key) ?? [];
+            const ts = target.syls[p];
             for (const candidate of candidates) {
                 if (candidate.entry.word === target.entry.word)
                     continue;
+                /* 같은 묶음은 p 자리 밖이 모두 같다 — p 자리에서 정확히 한 성분만 달라야 최소대립쌍이다. 1음절 낱말은 전부 한 묶음이라
+                   묶음이 커서, 쌍 문자열·발음 분해(analyzeMinimalPair) 전에 먼저 거른다(음소를 고를 때마다 110–320ms 걸렸다). */
+                {
+                    const cs = candidate.syls[p];
+                    let d = 0;
+                    if (ts.초성 !== cs.초성)
+                        d++;
+                    if (ts.모음 !== cs.모음)
+                        d++;
+                    if (ts.종성 !== cs.종성)
+                        d++;
+                    if ((ts.활음 ?? '') !== (cs.활음 ?? ''))
+                        d++;
+                    if (d !== 1)
+                        continue;
+                }
                 const dedupKey = target.entry.word < candidate.entry.word
                     ? `${target.entry.word}|${candidate.entry.word}`
                     : `${candidate.entry.word}|${target.entry.word}`;

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

@@ -0,0 +1,5 @@
+/**
+ * `ms` 뒤 끊기는 AbortSignal. `AbortSignal.timeout` 은 Safari 16 부터라 iOS/iPadOS 15 이하(치료실 구형 iPad)에서는
+ * 없어 fetch 를 부르기도 전에 TypeError 로 거절됐다 — 없으면 AbortController + setTimeout 으로 만든다.
+ */
+export declare function timeoutSignal(ms: number): AbortSignal;

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

@@ -0,0 +1,12 @@
+/**
+ * `ms` 뒤 끊기는 AbortSignal. `AbortSignal.timeout` 은 Safari 16 부터라 iOS/iPadOS 15 이하(치료실 구형 iPad)에서는
+ * 없어 fetch 를 부르기도 전에 TypeError 로 거절됐다 — 없으면 AbortController + setTimeout 으로 만든다.
+ */
+export function timeoutSignal(ms) {
+    const native = AbortSignal.timeout;
+    if (typeof native === 'function')
+        return native.call(AbortSignal, ms);
+    const c = new AbortController();
+    setTimeout(() => c.abort(), ms);
+    return c.signal;
+}

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

@@ -20,6 +20,7 @@
  *
  * @public
  */
+import { timeoutSignal } from './timeoutSignal';
 const GLOBAL_KEY = '__ihab_core_tts_config__';
 /**
  * TTS URL 리졸버를 전역으로 설정합니다.
@@ -84,7 +85,7 @@ export async function checkAudioExists(word) {
             audioExistsCache.delete(url);
         return false;
     };
-    const promise = fetch(url, { method: 'HEAD', signal: AbortSignal.timeout(8000) })
+    const promise = fetch(url, { method: 'HEAD', signal: timeoutSignal(8000) })
         .then(res => (res.status >= 500 ? 확인안됨() : res.ok), 확인안됨);
     audioExistsCache.set(url, promise);
     return promise;

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

@@ -141,15 +141,17 @@ position) {
                 answersByPos.set(i, [pw]);
         }
         for (const [pos, answers] of answersByPos) {
-            const maskedSlots = new Set(selParts.map(p => pos + ':' + p));
+            // 가릴 성분은 대립 자리(pos)의 것뿐 — 낱말·자리·성분마다 'i:part' 문자열을 만들어 Set 에서 찾던 것을 불리언으로(열쇠 모양은 같다)
+            const mC = selParts.includes('cho'), mJ = selParts.includes('jung'), mG = selParts.includes('jong');
             // 마스킹 템플릿은 '발음' 분해 기준 (대립 자리 외 발음이 전부 같은 단어끼리 묶음)
             const templateOf = (d) => {
                 let key = '';
                 for (let i = 0; i < L; i++) {
                     const s = d[i];
-                    for (const part of ['cho', 'jung', 'jong']) {
-                        key += (maskedSlots.has(i + ':' + part) ? '*' : s[part]) + '.';
-                    }
+                    if (i === pos)
+                        key += (mC ? '*' : s.cho) + '.' + (mJ ? '*' : s.jung) + '.' + (mG ? '*' : s.jong) + '.';
+                    else
+                        key += s.cho + '.' + s.jung + '.' + s.jong + '.';
                 }
                 return key;
             };