@ihabdevteam/core 0.128.0 → 0.131.0

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

@@ -5,18 +5,23 @@ export const TRAINING_TYPES = [
     { key: "LONG_STORY", label: "긴 이야기 듣기", icon: "message-square-text", desc: "긴 이야기를 듣고 기억하여 다수의 문제를 풀어봅니다." },
     { key: "ORDERING_SENTENCE", label: "문장 순서화 하기", icon: "align-start-vertical", desc: "여러개의 짧은 문장을 듣고 기억하여 그 순서에 맞게 배열합니다." },
 ];
-/** @public */
+/**
+ * 주제·세부 주제 목록(열쇠·이름·아이콘·색). **설명(desc)은 두지 않는다** — 코어·앱 어디에서도 주제 설명을
+ * 그리지 않고, 한때 7개 주제에 붙어 있던 '소음 환경 속 문장 이해 훈련' 은 훈련 유형(소음 하 문장 듣기)의
+ * 설명을 옮겨 붙인 값이었다(2026-09-14 걷음). 화면에 보이는 설명은 훈련 유형(`TRAINING_TYPES`)의 것이다.
+ * @public
+ */
 export const TOPIC_TYPES = [
-    { key: 'FOOD', label: '음식', icon: 'salad', color: '#FF8A65', subs: [{ key: 'TRKRFD', label: ' 한국 전통음식' }, { key: 'MDKRFD', label: '한국 현대음식' }, { key: 'WRLDFD', label: '세계의 음식' }, { key: 'MTRFRT', label: '식재료와 과일' }, { key: 'GEFDKL', label: '음식 상식' }] },
-    { key: 'HLTH', label: '건강', icon: 'heart', color: '#66BB6A', subs: [{ key: 'HTETHB', label: '건강한 식습관' }, { key: 'DISILL', label: '병과 질환' }, { key: 'EXCISE', label: '운동' }, { key: 'GEHTKL', label: '건상상식' }] },
+    { key: 'FOOD', label: '음식', icon: 'salad', color: '#FF8A65', subs: [{ key: 'TRKRFD', label: '한국 전통음식' }, { key: 'MDKRFD', label: '한국 현대음식' }, { key: 'WRLDFD', label: '세계의 음식' }, { key: 'MTRFRT', label: '식재료와 과일' }, { key: 'GEFDKL', label: '음식 상식' }] },
+    { key: 'HLTH', label: '건강', icon: 'heart', color: '#66BB6A', subs: [{ key: 'HTETHB', label: '건강한 식습관' }, { key: 'DISILL', label: '병과 질환' }, { key: 'EXCISE', label: '운동' }, { key: 'GEHTKL', label: '건강상식' }] },
     { key: 'WETH', label: '날씨', icon: 'sun-medium', color: '#42A5F5', subs: [{ key: 'GESSKL', label: '계절상식' }, { key: 'SNWRAN', label: '눈과 비' }, { key: 'WTHFCT', label: '일기예보' }, { key: 'GEWTKL', label: '날씨상식' }] },
-    { key: 'PRSN', label: '인물', icon: 'user-round', desc: '소음 환경 속 문장 이해 훈련', color: '#AB47BC', subs: [{ key: 'JODYPS', label: '조선시대' }, { key: 'MDKRPS', label: '한국 근현대' }, { key: 'THKDPS', label: '삼국시대' }, { key: 'WRLART', label: '세계의 예술가' }, { key: 'WRLPSN', label: '세계의 인물' }] },
-    { key: 'KRCT', label: '한국문화', icon: 'bow-arrow', desc: '소음 환경 속 문장 이해 훈련', color: '#EC407A', subs: [{ key: 'KRLANG', label: '우리말' }, { key: 'TRPLCT', label: '전통놀이' }, { key: 'HERITG', label: '문화재' }, { key: 'EVTFES', label: '행사와 축제' }, { key: 'GECTKL', label: '상식' }] },
-    { key: 'STRY', label: '이야기', icon: 'message-circle', desc: '소음 환경 속 문장 이해 훈련', color: '#8D6E63', subs: [{ key: 'FRYTAL', label: '동화' }, { key: 'AMZING', label: '신기한 이야기' }, { key: 'DAYSTR', label: '일상 속 이야기' }] },
-    { key: 'LOCA', label: '지역', icon: 'map-pin', desc: '소음 환경 속 문장 이해 훈련', color: '#26A69A', subs: [{ key: 'KRLDMK', label: '한국의 명소' }, { key: 'SELNMK', label: '서울의 명소' }, { key: 'WRDTRB', label: '세계여행' }, { key: 'NAVIGT', label: '길 찾기' }] },
-    { key: 'SOAR', label: '사회와 예술', icon: 'landmark', desc: '소음 환경 속 문장 이해 훈련', color: '#5C6BC0', subs: [{ key: 'KRSOCI', label: '한국' }, { key: 'ECONEW', label: '경제와 뉴스' }, { key: 'GENART', label: '예술' }, { key: 'GELFKL', label: '생활 상식' }] },
-    { key: 'NTSC', label: '자연과 과학', icon: 'leaf', desc: '소음 환경 속 문장 이해 훈련', color: '#9CCC65', subs: [{ key: 'ANIMAL', label: '동물' }, { key: 'PLANTS', label: '식물' }, { key: 'ETHPLT', label: '지구' }, { key: 'TOLELC', label: '도구와 전자제품' }, { key: 'GESCKL', label: '과학상식' }] },
-    { key: 'SPRT', label: '스포츠', icon: 'trophy', desc: '소음 환경 속 문장 이해 훈련', color: '#FFCA28', subs: [{ key: 'INVDSP', label: '개인경기' }, { key: 'MARART', label: '격투기' }, { key: 'TEAMSP', label: '단체경기' }, { key: 'FOOTBL', label: '축구' }, { key: 'GESPKL', label: '스포츠 상식' }] },
+    { key: 'PRSN', label: '인물', icon: 'user-round', color: '#AB47BC', subs: [{ key: 'JODYPS', label: '조선시대' }, { key: 'MDKRPS', label: '한국 근현대' }, { key: 'THKDPS', label: '삼국시대' }, { key: 'WRLART', label: '세계의 예술가' }, { key: 'WRLPSN', label: '세계의 인물' }] },
+    { key: 'KRCT', label: '한국문화', icon: 'bow-arrow', color: '#EC407A', subs: [{ key: 'KRLANG', label: '우리말' }, { key: 'TRPLCT', label: '전통놀이' }, { key: 'HERITG', label: '문화재' }, { key: 'EVTFES', label: '행사와 축제' }, { key: 'GECTKL', label: '상식' }] },
+    { key: 'STRY', label: '이야기', icon: 'message-circle', color: '#8D6E63', subs: [{ key: 'FRYTAL', label: '동화' }, { key: 'AMZING', label: '신기한 이야기' }, { key: 'DAYSTR', label: '일상 속 이야기' }] },
+    { key: 'LOCA', label: '지역', icon: 'map-pin', color: '#26A69A', subs: [{ key: 'KRLDMK', label: '한국의 명소' }, { key: 'SELNMK', label: '서울의 명소' }, { key: 'WRDTRB', label: '세계여행' }, { key: 'NAVIGT', label: '길 찾기' }] },
+    { key: 'SOAR', label: '사회와 예술', icon: 'landmark', color: '#5C6BC0', subs: [{ key: 'KRSOCI', label: '한국' }, { key: 'ECONEW', label: '경제와 뉴스' }, { key: 'GENART', label: '예술' }, { key: 'GELFKL', label: '생활 상식' }] },
+    { key: 'NTSC', label: '자연과 과학', icon: 'leaf', color: '#9CCC65', subs: [{ key: 'ANIMAL', label: '동물' }, { key: 'PLANTS', label: '식물' }, { key: 'ETHPLT', label: '지구' }, { key: 'TOLELC', label: '도구와 전자제품' }, { key: 'GESCKL', label: '과학상식' }] },
+    { key: 'SPRT', label: '스포츠', icon: 'trophy', color: '#FFCA28', subs: [{ key: 'INVDSP', label: '개인경기' }, { key: 'MARART', label: '격투기' }, { key: 'TEAMSP', label: '단체경기' }, { key: 'FOOTBL', label: '축구' }, { key: 'GESPKL', label: '스포츠 상식' }] },
 ];
 /** 훈련 유형 i18n 키 매핑 */
 export const TRAINING_TYPE_I18N_KEY = {

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

@@ -1,5 +1,8 @@
 const ABSOLUTE_URL_RE = /^(?:[a-z]+:)?\/\//i;
-let configuredAssetBaseUrl = '';
+// globalThis 싱글톤: 다른 설정(storage·ttsConfig·imageConfig)과 같은 방식.
+// 모듈 변수로 두면 CJS 묶음이 여럿일 때(utils.cjs 에서 설정, components.cjs 에서 읽기)
+// 묶음마다 한 벌씩 생겨 설정이 안 보였다.
+const ASSET_GLOBAL_KEY = '__ihab_core_asset_base_url__';
 function normalizeAssetBaseUrl(baseUrl) {
     const raw = String(baseUrl || '').trim();
     if (!raw)
@@ -30,11 +33,12 @@ function normalizeAssetBaseUrl(baseUrl) {
  * @public
  */
 export function setAssetBaseUrl(baseUrl) {
-    configuredAssetBaseUrl = normalizeAssetBaseUrl(baseUrl);
+    ;
+    globalThis[ASSET_GLOBAL_KEY] = normalizeAssetBaseUrl(baseUrl);
 }
 /** @public */
 export function getAssetBaseUrl() {
-    return configuredAssetBaseUrl;
+    return globalThis[ASSET_GLOBAL_KEY] ?? '';
 }
 /**
  * 에셋 경로를 절대 URL 또는 베이스 URL 기준의 경로로 변환합니다.

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

@@ -10,8 +10,12 @@
 export async function copyText(text) {
     // 1순위: execCommand (동기 — 제스처 유지, iframe 대응)
     if (typeof document !== 'undefined') {
+        // 숨긴 textarea 에 포커스를 옮기므로, 끝나면 원래 자리로 돌려준다 — 안 돌리면 복사 단추를
+        // 누른 뒤 키보드 포커스가 body 로 떨어져 스크린리더·Tab 이동이 처음부터 다시 시작된다.
+        const 원래포커스 = document.activeElement;
+        let ta = null;
         try {
-            const ta = document.createElement('textarea');
+            ta = document.createElement('textarea');
             ta.value = text;
             ta.setAttribute('readonly', '');
             ta.style.position = 'fixed';
@@ -24,13 +28,23 @@ export async function copyText(text) {
             ta.select();
             ta.setSelectionRange(0, text.length);
             const ok = document.execCommand('copy');
-            document.body.removeChild(ta);
             if (ok)
                 return true;
         }
         catch {
             /* 폴백으로 진행 */
         }
+        finally {
+            // 성공·실패·던짐 어느 길이든 textarea 를 거두고 포커스를 되돌린다
+            if (ta?.parentNode)
+                ta.parentNode.removeChild(ta);
+            if (원래포커스 && 원래포커스 !== document.activeElement && typeof 원래포커스.focus === 'function' && 원래포커스.isConnected) {
+                try {
+                    원래포커스.focus({ preventScroll: true });
+                }
+                catch { /* 무시 */ }
+            }
+        }
     }
     // 2순위: Async Clipboard API
     try {

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

@@ -11,7 +11,8 @@
  * 곳곳에 흩어져 있어 여기 한 벌로 모은다.
  *
  * 문자열도 그대로 쓴다 — `throw '문구'` 로 던지는 자리가 있다. 끝내 못 읽는
- * 값(숫자·null·빈 객체·빈 문구)일 때만 fallback 을 쓴다.
+ * 값(숫자·null·빈 객체·빈 문구)일 때만 fallback 을 쓴다. fallback 을 주지 않으면 지금
+ * 언어의 '알 수 없는 오류'(`common.unknownError`), 주면 그 문구 그대로.
  *
  * 회원 앱은 `src/libs/errorUtils.ts` 가 이것을 다시 내보낸다 — 한 벌만 둔다.
  * @public

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

@@ -1,3 +1,16 @@
+import i18n from 'i18next';
+/**
+ * 못 읽을 때의 기본 문구 — 지금 언어로. 사전에 없거나 i18n 이 아직 안 섰으면 한국어.
+ *
+ * `src/i18n` 이 초기화하는 것도 i18next 의 **기본 인스턴스**다(묶음에서 i18next 는 external).
+ * 여기서 `../i18n` 을 가져오면 utils 묶음이 사전 JSON 과 init 부작용을 끌어안으므로 기본
+ * 인스턴스를 직접 본다. 초기화 전의 `i18n.t` 는 undefined 를 돌려준다.
+ */
+const 알수없는오류 = () => {
+    const 기본 = '알 수 없는 오류';
+    const s = typeof i18n?.t === 'function' ? i18n.t('common.unknownError', { defaultValue: 기본 }) : undefined;
+    return typeof s === 'string' && s ? s : 기본;
+};
 /**
  * 잡은 값에서 **사람이 읽을 수 있는 원인**을 꺼낸다.
  *
@@ -11,12 +24,16 @@
  * 곳곳에 흩어져 있어 여기 한 벌로 모은다.
  *
  * 문자열도 그대로 쓴다 — `throw '문구'` 로 던지는 자리가 있다. 끝내 못 읽는
- * 값(숫자·null·빈 객체·빈 문구)일 때만 fallback 을 쓴다.
+ * 값(숫자·null·빈 객체·빈 문구)일 때만 fallback 을 쓴다. fallback 을 주지 않으면 지금
+ * 언어의 '알 수 없는 오류'(`common.unknownError`), 주면 그 문구 그대로.
  *
  * 회원 앱은 `src/libs/errorUtils.ts` 가 이것을 다시 내보낸다 — 한 벌만 둔다.
  * @public
  */
-export function getErrorMessage(e, fallback = '알 수 없는 오류') {
+export function getErrorMessage(e, fallback) {
+    // 기본 문구는 부를 때마다 지금 언어로 만든다(모듈 로드 때 한 번 정하면 언어 전환을 못 따른다)
+    if (fallback === undefined)
+        fallback = 알수없는오류();
     if (e instanceof Error)
         return e.message || fallback;
     if (typeof e === 'string')

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

@@ -26,7 +26,14 @@ export type ComputeDailySelectionOptions = {
     counts?: TrainingCounts;
     forceRefresh?: boolean;
 };
-/** @public */
+/**
+ * 오늘·어제 세트를 뽑아 `TODAY_SETS`·`YESTERDAY_SETS` 에 채운다(`loadTrainingData` 가 부른다).
+ *
+ * **어제 세트는 "어제 뽑힌 세트" 가 아니다** — 캐시가 메모리에만 있어, 날이 바뀌면 어제 몫도 따로 새로 뽑는다.
+ * 사용자에게 보이는 오늘·어제 세트는 사용자와 날짜로 시드를 정하는 `useDailyTrainingSelection` 을 쓴다
+ * (같은 날 같은 사용자면 늘 같은 세트, 어제 세트도 어제와 같다).
+ * @public
+ */
 export declare function computeDailySelection({ counts, forceRefresh }?: ComputeDailySelectionOptions): {
     today: {
         [k: string]: unknown[];

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

@@ -18,7 +18,14 @@ const DEFAULT_TRAINING_COUNTS = { LISTEN_IN_NOISE: 3, SHORT_STORY: 2, LONG_STORY
 let _cachedCountsKey = null;
 let _cachedTodayDate = null;
 let _cachedSelection = null;
-/** @public */
+/**
+ * 오늘·어제 세트를 뽑아 `TODAY_SETS`·`YESTERDAY_SETS` 에 채운다(`loadTrainingData` 가 부른다).
+ *
+ * **어제 세트는 "어제 뽑힌 세트" 가 아니다** — 캐시가 메모리에만 있어, 날이 바뀌면 어제 몫도 따로 새로 뽑는다.
+ * 사용자에게 보이는 오늘·어제 세트는 사용자와 날짜로 시드를 정하는 `useDailyTrainingSelection` 을 쓴다
+ * (같은 날 같은 사용자면 늘 같은 세트, 어제 세트도 어제와 같다).
+ * @public
+ */
 export function computeDailySelection({ counts, forceRefresh } = {}) {
     const c = Object.assign({}, DEFAULT_TRAINING_COUNTS, counts || {});
     // 오늘의 훈련은 KST 자정에 바뀌어야 한다 — UTC 날짜를 쓰면 오전 9시에 바뀐다

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

@@ -83,19 +83,21 @@ export declare function wordHasSyllableMatching(word: string, parts: {
  */
 export declare function isSyllablePattern(query: string): boolean;
 /**
- * @public 음절 패턴 미니 DSL 매칭. 쉼표(,)로 나눈 조각을 자리(음절) 단위로 자동 분해하며,
- * **분해된 총 자리 수는 반드시 단어의 음절 수와 같아야** 매칭된다. 한 자리는 다음 중 하나:
+ * @public 음절 패턴 미니 DSL 매칭. 쉼표(,)로 나눈 조각을 연속된 음절 자리들로 풀고, 그 자리들이 단어의
+ * **어느 위치에서든 연속으로** 맞으면 매칭된다(포함 매칭 — 단어 음절 수가 자리 수보다 많아도 된다).
+ * 한 자리는 다음 중 하나:
  *  - 빈 자리(쉼표 사이가 비어 있음) — 무관(아무 음절이나 허용).
- *  - 완성 음절 한 글자(예: '가') — 그 자리 음절이 정확히 이 글자와 같아야 함.
+ *  - 완성 음절 한 글자(예: '가', '강') — 받침 없는 글자는 초성·중성만 같으면 되고(받침 무관: '수' → 수·술·숙),
+ *    받침 있는 글자는 정확히 같아야 함.
  *  - 자음/모음 한 글자(예: 'ㄴ', 'ㅏ') — 자음이면 그 자리 초성이, 모음이면 그 자리 중성이 정확히 그
  *    자모여야 함(나머지는 무관).
- *  - 초성·중성·종성 3자모 템플릿(예: '__ㄱ', 쉼표로 나눈 조각이 정확히 3글자일 때만) — 각 자리가 '_'면
- *    무관, 자모면 그 위치(초성/중성/종성)가 정확히 그 자모여야 함. 종성 자리 '_'는 받침 유무 모두 허용.
- * 쉼표 사이에 완성 음절·자음·모음을 이어 붙이면(예: '가ㄴ') 한 글자씩 각각 한 음절 자리로 자동 분해된다
- * (3글자로 붙이면 템플릿과 구분이 안 되므로 예외 — 그 경우는 쉼표로 나눠 쓴다).
- * 예: '가,,다' → 3음절, 첫 음절 '가' · 가운데 무관 · 끝 음절 '다'.
- * 예: '__ㄱ,고' → 2음절, 첫 음절 종성이 'ㄱ'(초성·중성 무관) · 끝 음절 '고'.
- * 예: '가ㄴ,,다'(= '가,ㄴ,,다'와 동일) → 4음절, 첫 음절 '가' · 둘째 음절 초성 'ㄴ' · 셋째 무관 · 넷째 '다'.
+ *  - 한 음절 템플릿(조각에 '_'가 하나라도 있을 때, 1~4글자) — 초성·중성·종성 순으로 읽고, '_'나 생략한 뒤
+ *    자리는 무관, 자모면 그 위치가 정확히 그 자모여야 함. 종성은 겹받침 두 자모('ㄹㄱ' = ㄺ)까지.
+ *    예: '__ㄱ' = 종성 ㄱ, 'ㄱ_' = 초성 ㄱ, 'ㄱ_ㄱ' = 초성 ㄱ·종성 ㄱ.
+ * '_' 없이 완성 음절·자음·모음을 이어 붙이면(예: '가ㄴ') 한 글자씩 각각 한 음절 자리로 분해된다.
+ * 예: '가,,다' → 첫 음절 '가'(받침 무관) · 가운데 무관 · 끝 음절 '다'인 연속 3음절을 포함한 단어.
+ * 예: '__ㄱ,고' → 종성 'ㄱ'인 음절 바로 뒤에 '고'가 오는 단어(먹고·박고구마 …).
+ * 예: '가ㄴ,,다'(= '가,ㄴ,,다'와 동일) → 연속 4음절 '가' · 초성 'ㄴ' · 무관 · '다'.
  * 해석할 수 없는 글자(자음·모음·완성 음절이 아님)가 섞이면 그 자리는 항상 매칭 실패 처리되어 결과가
  * 0건이 된다(조용히 무관 처리하지 않는다 — 제약이 무시된 채 결과가 나오는 오해를 막기 위해).
  */
@@ -117,8 +119,9 @@ export declare function patternToComposition(pattern: string): {
 } | null;
 /**
  * @public 단어 검색 '글자 입력'의 형식 유효성 검사.
- * 허용: 완성 음절('가'), 초성/중성 자모('ㄱ'·'ㅏ'), 초성·중성·종성 3자모 템플릿('__ㄱ', 정확히 3글자),
- * 쉼표(,) 구분(빈 자리는 '무관'). 그 외(예: '_' 오용, 라틴 문자, 한 자리에 음소 4개 이상인 '___ㄱ')는 무효.
+ * 허용: 완성 음절('가'), 초성/중성 자모('ㄱ'·'ㅏ'), '_'가 든 한 음절 템플릿(1~4글자, 초성·중성·종성 순 —
+ * '__ㄱ'·'ㄱ_'·'ㄱ_ㄹㄱ'), 쉼표(,) 구분(빈 자리는 '무관'). 그 외(예: 5글자 이상 템플릿, 템플릿 자리에 맞지 않는
+ * 자모('ㅏ_'), 라틴 문자)는 무효.
  * @returns 유효하면 `{ ok: true }`, 아니면 `{ ok: false }`(호출부가 안내 문구를 표시).
  */
 export declare function validateSyllableSearchInput(input: string): {

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

@@ -398,19 +398,21 @@ function matchesPatternAtom(ch, atom) {
     }
 }
 /**
- * @public 음절 패턴 미니 DSL 매칭. 쉼표(,)로 나눈 조각을 자리(음절) 단위로 자동 분해하며,
- * **분해된 총 자리 수는 반드시 단어의 음절 수와 같아야** 매칭된다. 한 자리는 다음 중 하나:
+ * @public 음절 패턴 미니 DSL 매칭. 쉼표(,)로 나눈 조각을 연속된 음절 자리들로 풀고, 그 자리들이 단어의
+ * **어느 위치에서든 연속으로** 맞으면 매칭된다(포함 매칭 — 단어 음절 수가 자리 수보다 많아도 된다).
+ * 한 자리는 다음 중 하나:
  *  - 빈 자리(쉼표 사이가 비어 있음) — 무관(아무 음절이나 허용).
- *  - 완성 음절 한 글자(예: '가') — 그 자리 음절이 정확히 이 글자와 같아야 함.
+ *  - 완성 음절 한 글자(예: '가', '강') — 받침 없는 글자는 초성·중성만 같으면 되고(받침 무관: '수' → 수·술·숙),
+ *    받침 있는 글자는 정확히 같아야 함.
  *  - 자음/모음 한 글자(예: 'ㄴ', 'ㅏ') — 자음이면 그 자리 초성이, 모음이면 그 자리 중성이 정확히 그
  *    자모여야 함(나머지는 무관).
- *  - 초성·중성·종성 3자모 템플릿(예: '__ㄱ', 쉼표로 나눈 조각이 정확히 3글자일 때만) — 각 자리가 '_'면
- *    무관, 자모면 그 위치(초성/중성/종성)가 정확히 그 자모여야 함. 종성 자리 '_'는 받침 유무 모두 허용.
- * 쉼표 사이에 완성 음절·자음·모음을 이어 붙이면(예: '가ㄴ') 한 글자씩 각각 한 음절 자리로 자동 분해된다
- * (3글자로 붙이면 템플릿과 구분이 안 되므로 예외 — 그 경우는 쉼표로 나눠 쓴다).
- * 예: '가,,다' → 3음절, 첫 음절 '가' · 가운데 무관 · 끝 음절 '다'.
- * 예: '__ㄱ,고' → 2음절, 첫 음절 종성이 'ㄱ'(초성·중성 무관) · 끝 음절 '고'.
- * 예: '가ㄴ,,다'(= '가,ㄴ,,다'와 동일) → 4음절, 첫 음절 '가' · 둘째 음절 초성 'ㄴ' · 셋째 무관 · 넷째 '다'.
+ *  - 한 음절 템플릿(조각에 '_'가 하나라도 있을 때, 1~4글자) — 초성·중성·종성 순으로 읽고, '_'나 생략한 뒤
+ *    자리는 무관, 자모면 그 위치가 정확히 그 자모여야 함. 종성은 겹받침 두 자모('ㄹㄱ' = ㄺ)까지.
+ *    예: '__ㄱ' = 종성 ㄱ, 'ㄱ_' = 초성 ㄱ, 'ㄱ_ㄱ' = 초성 ㄱ·종성 ㄱ.
+ * '_' 없이 완성 음절·자음·모음을 이어 붙이면(예: '가ㄴ') 한 글자씩 각각 한 음절 자리로 분해된다.
+ * 예: '가,,다' → 첫 음절 '가'(받침 무관) · 가운데 무관 · 끝 음절 '다'인 연속 3음절을 포함한 단어.
+ * 예: '__ㄱ,고' → 종성 'ㄱ'인 음절 바로 뒤에 '고'가 오는 단어(먹고·박고구마 …).
+ * 예: '가ㄴ,,다'(= '가,ㄴ,,다'와 동일) → 연속 4음절 '가' · 초성 'ㄴ' · 무관 · '다'.
  * 해석할 수 없는 글자(자음·모음·완성 음절이 아님)가 섞이면 그 자리는 항상 매칭 실패 처리되어 결과가
  * 0건이 된다(조용히 무관 처리하지 않는다 — 제약이 무시된 채 결과가 나오는 오해를 막기 위해).
  */
@@ -423,7 +425,7 @@ export function matchesSyllablePattern(word, pattern) {
         return false;
     // '포함' 매칭 — 패턴(연속 음절 자리들)이 단어의 어느 위치에서든 연속으로 맞으면 통과.
     // (단어 음절수 == 패턴 자리수를 요구하지 않는다. 예: '__ㄱ,고' → 첫음절 종성ㄱ+둘째음절 '고'를
-    //  포함한 모든 단어 = 학교·박고구마… 길이 무관.)
+    //  포함한 모든 단어 = 먹고·박고구마… 길이 무관.)
     for (let i = 0; i + atoms.length <= chars.length; i++) {
         if (atoms.every((atom, j) => matchesPatternAtom(chars[i + j], atom)))
             return true;
@@ -488,8 +490,9 @@ function isSearchAtomChar(ch) {
 }
 /**
  * @public 단어 검색 '글자 입력'의 형식 유효성 검사.
- * 허용: 완성 음절('가'), 초성/중성 자모('ㄱ'·'ㅏ'), 초성·중성·종성 3자모 템플릿('__ㄱ', 정확히 3글자),
- * 쉼표(,) 구분(빈 자리는 '무관'). 그 외(예: '_' 오용, 라틴 문자, 한 자리에 음소 4개 이상인 '___ㄱ')는 무효.
+ * 허용: 완성 음절('가'), 초성/중성 자모('ㄱ'·'ㅏ'), '_'가 든 한 음절 템플릿(1~4글자, 초성·중성·종성 순 —
+ * '__ㄱ'·'ㄱ_'·'ㄱ_ㄹㄱ'), 쉼표(,) 구분(빈 자리는 '무관'). 그 외(예: 5글자 이상 템플릿, 템플릿 자리에 맞지 않는
+ * 자모('ㅏ_'), 라틴 문자)는 무효.
  * @returns 유효하면 `{ ok: true }`, 아니면 `{ ok: false }`(호출부가 안내 문구를 표시).
  */
 export function validateSyllableSearchInput(input) {

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

@@ -3,9 +3,10 @@ import type { ComponentType } from 'react';
  * 정적으로 번들되는 아이콘 목록.
  *
  * 이 목록은 speechear·kscan 소스의 icon 리터럴(`icon="..."`, `icon: '...'`)을
- * 훑어 만들었습니다. **여기 없는 이름은 지연 로드됩니다** — 화면에는 결국
- * 나오지만 첫 렌더에는 잠깐 비어 보입니다. 새 아이콘을 쓰기 시작했는데
- * 유독 그것만 늦게 뜬다면 이 목록에 추가하세요.
+ * 훑어 만들었습니다. **여기 없는 이름은 그려지지 않습니다** — 지연 로드도
+ * 하지 않고, 개발 모드에서 이름당 한 번 경고만 남깁니다(`lucideLoader.ts`).
+ * 새 아이콘을 쓰기 시작했는데 비어 보인다면 이 목록에 추가하세요.
+ * 소스의 icon 리터럴이 목록에 없으면 `test/lucideIconSet.test.tsx` 가 실패합니다.
  *
  * 왜 이렇게 하는가: 예전에는 `import * as lucide from 'lucide-react'` 로
  * 통째로 가져와 이름으로 조회했습니다. 그러면 어떤 이름이든 들어올 수 있으니

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

@@ -185,9 +185,10 @@ import ThumbsUpIcon from 'lucide-react/dist/esm/icons/thumbs-up.mjs';
  * 정적으로 번들되는 아이콘 목록.
  *
  * 이 목록은 speechear·kscan 소스의 icon 리터럴(`icon="..."`, `icon: '...'`)을
- * 훑어 만들었습니다. **여기 없는 이름은 지연 로드됩니다** — 화면에는 결국
- * 나오지만 첫 렌더에는 잠깐 비어 보입니다. 새 아이콘을 쓰기 시작했는데
- * 유독 그것만 늦게 뜬다면 이 목록에 추가하세요.
+ * 훑어 만들었습니다. **여기 없는 이름은 그려지지 않습니다** — 지연 로드도
+ * 하지 않고, 개발 모드에서 이름당 한 번 경고만 남깁니다(`lucideLoader.ts`).
+ * 새 아이콘을 쓰기 시작했는데 비어 보인다면 이 목록에 추가하세요.
+ * 소스의 icon 리터럴이 목록에 없으면 `test/lucideIconSet.test.tsx` 가 실패합니다.
  *
  * 왜 이렇게 하는가: 예전에는 `import * as lucide from 'lucide-react'` 로
  * 통째로 가져와 이름으로 조회했습니다. 그러면 어떤 이름이든 들어올 수 있으니

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

@@ -3,6 +3,11 @@ export 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>;

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

@@ -16,7 +16,7 @@ export declare function phonemePartsOf(word: string): string[];
 /**
  * @public 합치기 문제 **표시** 문장 — 미리보기·러너 공용. 음절/음소 모두 원문(자모는 자모 그대로: 'ㄱ','ㅏ')로 표시한다.
  * TTS로 읽을 땐 자모를 낱자 이름으로 바꿔야 하지만(그건 jamoToNamesForSpeech가 합성 경로에서 처리), 화면 표기는 자모 유지.
- * 예: ['아','냐'] → `"아"와 "냐"를 합치면 어떤 단어가 되나요?` / ['ㄱ','ㅏ'] → `"ㄱ"와 "ㅏ"를 합치면 어떤 소리가 되나요?`
+ * 예: ['아','냐'] → `"아"와 "냐"를 합치면 어떤 단어가 되나요?` / ['ㄱ','ㅏ'] → `"ㄱ"과 "ㅏ"를 합치면 어떤 소리가 되나요?`
  */
 export declare function mergeQuestionText(parts: string[], phoneme?: boolean): string;
 /**
@@ -54,7 +54,7 @@ declare function pronOf(word: string, pronMap: Map<string, string>): string;
 export declare function syllablePron(ch: string): string;
 /**
  * @public 음절의 실제 소리(표준발음). pronMap에 있으면 그것, 없으면(합성 음절) 끝소리 규칙 발음, 그래도 없으면 철자.
- * (예: '밡'·'밖'은 모두 [박] — 소리 기준 중복 판정에 쓴다.)
+ * (예: '밖'·'밗'은 모두 [박] — 소리 기준 중복 판정에 쓴다.)
  */
 export declare function soundOf(syll: string, pronMap: Map<string, string>): string;
 /** @public comp에서 실제로 선택된 파트 1개(초성 우선)를 반환. 없으면 null. */
@@ -68,7 +68,7 @@ export declare function syllMatchesComp(s: Syllable, comp: CompositionFilter): b
 export declare function matchSyllables(word: string, pronMap: Map<string, string>, phonemeView: 'char' | 'pron'): (Syllable | null)[];
 /**
  * @public 정답 음절(분해 cs)의 지정 파트를 다른 음소로 바꿔 대립쌍 음절 n개 생성.
- * 중복 배제는 '실제 발음(soundOf)' 기준 — 소리가 같은 오답(밡/밖→박)이 함께 나오지 않게 한다.
+ * 중복 배제는 '실제 발음(soundOf)' 기준 — 소리가 같은 오답(밖/밗→박)이 함께 나오지 않게 한다.
  */
 export declare function syllableContrasts(cs: Syllable, part: 'cho' | 'jung' | 'jong', correct: string, n: number, pronMap: Map<string, string>): string[];
 /** @public 훈련 문제 한 개(편집기·러너 공용). distractors[0]=정답, 이후=오답. */

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

@@ -78,7 +78,7 @@ export function phonemePartsOf(word) {
 /**
  * @public 합치기 문제 **표시** 문장 — 미리보기·러너 공용. 음절/음소 모두 원문(자모는 자모 그대로: 'ㄱ','ㅏ')로 표시한다.
  * TTS로 읽을 땐 자모를 낱자 이름으로 바꿔야 하지만(그건 jamoToNamesForSpeech가 합성 경로에서 처리), 화면 표기는 자모 유지.
- * 예: ['아','냐'] → `"아"와 "냐"를 합치면 어떤 단어가 되나요?` / ['ㄱ','ㅏ'] → `"ㄱ"와 "ㅏ"를 합치면 어떤 소리가 되나요?`
+ * 예: ['아','냐'] → `"아"와 "냐"를 합치면 어떤 단어가 되나요?` / ['ㄱ','ㅏ'] → `"ㄱ"과 "ㅏ"를 합치면 어떤 소리가 되나요?`
  */
 export function mergeQuestionText(parts, phoneme = false) {
     const p = parts.filter(Boolean);
@@ -190,7 +190,7 @@ export function syllablePron(ch) {
 }
 /**
  * @public 음절의 실제 소리(표준발음). pronMap에 있으면 그것, 없으면(합성 음절) 끝소리 규칙 발음, 그래도 없으면 철자.
- * (예: '밡'·'밖'은 모두 [박] — 소리 기준 중복 판정에 쓴다.)
+ * (예: '밖'·'밗'은 모두 [박] — 소리 기준 중복 판정에 쓴다.)
  */
 export function soundOf(syll, pronMap) {
     return pronMap.get(syll) || syllablePron(syll) || syll;
@@ -227,13 +227,17 @@ export function matchSyllables(word, pronMap, phonemeView) {
 }
 /**
  * @public 정답 음절(분해 cs)의 지정 파트를 다른 음소로 바꿔 대립쌍 음절 n개 생성.
- * 중복 배제는 '실제 발음(soundOf)' 기준 — 소리가 같은 오답(밡/밖→박)이 함께 나오지 않게 한다.
+ * 중복 배제는 '실제 발음(soundOf)' 기준 — 소리가 같은 오답(밖/밗→박)이 함께 나오지 않게 한다.
  */
 export function syllableContrasts(cs, part, correct, n, pronMap) {
     const arr = part === 'cho' ? CHOSEONG : part === 'jung' ? JUNGSEONG : JONGSEONG;
     const cur = cs[part];
     const out = [];
-    const usedSound = new Set([soundOf(correct, pronMap)]);
+    // 중성 대립은 발음 자료의 모음 병합(ㅔ→ㅐ·ㅖ→ㅒ·ㅚ/ㅞ→ㅙ)을 소리 열쇠에도 적용한다.
+    // 자료에 없는 만든 음절(예: '에')은 soundOf 가 철자 모음을 그대로 돌려줘, 정답 '애' 옆에 같은 소리 '에'가 오답으로 나왔다.
+    // (초성·종성 대립은 모음이 모두 같아 병합이 결과를 바꾸지 않으므로 손대지 않는다.)
+    const soundKey = (syll) => (part === 'jung' ? mergeVowelSound(soundOf(syll, pronMap)) : soundOf(syll, pronMap));
+    const usedSound = new Map([[soundKey(correct), -1]]); // 소리 → out 자리(-1 = 정답)
     const idxs = shuffled(arr.map((_, i) => i).filter(i => i !== cur
         && (part !== 'cho' || arr[i] !== 'ㅇ') // 초성 대립은 무음(ㅇ) 제외 — 구조가 바뀜
         && (part !== 'jong' || i !== 0))); // 종성 대립은 '받침 없음'(0) 제외 — 구조가 바뀜
@@ -243,14 +247,31 @@ export function syllableContrasts(cs, part, correct, n, pronMap) {
         const syll = part === 'cho' ? composeSyllable(idx, cs.jung, cs.jong)
             : part === 'jung' ? composeSyllable(cs.cho, idx, cs.jong)
                 : composeSyllable(cs.cho, cs.jung, idx);
-        const p = soundOf(syll, pronMap);
-        if (usedSound.has(p))
+        const p = soundKey(syll);
+        const prev = usedSound.get(p);
+        if (prev !== undefined) {
+            // 병합으로 같은 소리가 된 둘 중 자료에 없는 만든 음절이 먼저 자리를 차지했으면 자료에 있는 음절로 바꿔 끼운다
+            // — 실단어만 남기는 소비처(탈락 대립 등)가 병합 탓에 실단어를 잃지 않게.
+            if (part === 'jung' && prev >= 0 && pronMap.has(syll) && !pronMap.has(out[prev]))
+                out[prev] = syll;
             continue;
-        usedSound.add(p);
+        }
+        usedSound.set(p, out.length);
         out.push(syll);
     }
     return out;
 }
+/** 발음 자료의 모음 병합 규약 — ㅔ→ㅐ, ㅖ→ㅒ, ㅚ·ㅞ→ㅙ. 1음절 한글이 아니면 그대로. */
+const _VOWEL_MERGE = { 'ㅔ': 'ㅐ', 'ㅖ': 'ㅒ', 'ㅚ': 'ㅙ', 'ㅞ': 'ㅙ' };
+function mergeVowelSound(syll) {
+    if ([...syll].length !== 1)
+        return syll;
+    const s = parseSyllable(syll);
+    if (!s)
+        return syll;
+    const to = _VOWEL_MERGE[JUNGSEONG[s.jung]];
+    return to ? composeSyllable(s.cho, JUNGSEONG.indexOf(to), s.jong) : syll;
+}
 /**
  * @public 2음절 단어 → [문제단어, 남는 1음절(정답), 대립쌍 오답 2]. 정답·오답 모두 '실단어'(wordSet)만 인정.
  * 음소가 든 음절(T)을 남기고 다른 음절 탈락 → 남는 1음절이 실단어이고, 그 음절의 초성/중성/종성 대립 실단어가

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

@@ -46,4 +46,4 @@
  *
  * 값은 손으로 적고 `test/coreVersion.test.ts` 가 package.json 과 어긋나면 운다.
  */
-export declare const CORE_VERSION = "0.128.0";
+export declare const CORE_VERSION = "0.131.0";

package/dist/packages/core/src/version.js

@@ -46,4 +46,4 @@
  *
  * 값은 손으로 적고 `test/coreVersion.test.ts` 가 package.json 과 어긋나면 운다.
  */
-export const CORE_VERSION = '0.128.0';
+export const CORE_VERSION = '0.131.0';