@ihabdevteam/core 0.321.0 → 0.323.0

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

@@ -1,13 +1,43 @@
 /**
- * 기기 종류(보청기·인공와우·기타)에 붙는 배지 색.
+ * 기기 종류(보청기·인공와우·기타) — **이름과 색을 한 자리에서 정한다.**
  *
- * 표(DeviceSideTable)와 '사용중인 기기' 패널(PanelRowDevice)이 같은 값을 각자
- * 그리므로 **규칙을 한 곳에 둔다** — 두 곳에서 따로 정하면 같은 인공와우가 한쪽은
- * 파랑, 한쪽은 초록으로 떠서 다른 것인 줄 알게 된다.
+ * 표(`DeviceSideTable`)와 '사용중인 기기' 패널(`PanelRowDevice`)이 같은 값을 각자 그리므로
+ * 규칙을 한 곳에 둔다 — 두 곳에서 따로 정하면 같은 인공와우가 한쪽은 파랑, 한쪽은 초록으로
+ * 떠서 다른 것인 줄 알게 된다.
  *
- * 값은 저장된 그대로의 한국어다(managed_device.type). 목록에 없는 값·빈 값은
- * 'default'(무채색)로 떨어뜨린다 — 모르는 종류를 아는 색으로 칠하지 않는다.
+ * **색만 모여 있고 이름은 안 모여 있었다** — `deviceTypeKeys`·`deviceTypeLabel` 이 그 두
+ * 파일에 **주석까지 똑같이 두 벌** 있었다(2026-10-13 말귀가 짚었다). 색에 적어 둔 그 까닭이
+ * 이름에도 그대로 들어맞는 자리다. 모았다.
  *
- * @public
+ * ## 값은 **코드**다 — 옛 한글 값도 받는다
+ *
+ * 저장값(`managed_device.type`)이 `'보청기'` 에서 `'hearingAid'` 로 옮겨 가는 중이다
+ * (사장님 지시 "저장된 한글 값도 다 영어로"). 앱이 판을 돌리는 때와 이 판이 깔리는 때가
+ * 어긋나고, 옛 자료를 보는 다른 기관이 있을 수 있어 **둘 다 받는다**.
+ *
+ * 받지 않으면 **터지지 않고 조용히 틀린다** — 배지에 `hearingAid` 가 날것으로 뜨고
+ * (`defaultValue: device` 로 떨어진다), 색이 둘 다 무채색이 되어 종류를 색으로 가르던 것이
+ * 사라진다. 눈으로만 잡히는 꼴이다.
+ */
+export type DeviceKind = 'hearingAid' | 'cochlearImplant' | 'other';
+/**
+ * 저장값을 종류 코드로 — 모르는 값은 `null`.
+ *
+ * **모르는 것을 `'other'` 로 접지 않는다.** 기타는 "기타" 라고 고른 값이고, 모르는 값은
+ * 아직 뜻을 모르는 것이다. 둘을 섞으면 새 종류가 생긴 날 조용히 '기타' 로 보인다.
+ */
+export declare function deviceKindOf(device: string | null | undefined): DeviceKind | null;
+/**
+ * 배지 색. 목록에 없는 값·빈 값은 `'default'`(무채색)로 떨어뜨린다 —
+ * **모르는 종류를 아는 색으로 칠하지 않는다.**
  */
 export declare function deviceKindVariant(device: string | null | undefined): string;
+/**
+ * 배지에 적을 이름 — **지금 언어로**. 사전(`device.type.*`)이 쥔다.
+ *
+ * 모르는 값은 **저장된 그대로** 보인다. 숨기지 않는다 — 화면에 날것이 보이면 자료에 무엇이
+ * 들어 있는지 알 수 있고, 빈칸이면 아무것도 알 수 없다.
+ */
+export declare function deviceKindLabel(device: string | null | undefined, t: (k: string, o: {
+    defaultValue: string;
+}) => string): string;

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

@@ -1,19 +1,62 @@
 /**
- * 기기 종류(보청기·인공와우·기타)에 붙는 배지 색.
+ * 기기 종류(보청기·인공와우·기타) — **이름과 색을 한 자리에서 정한다.**
  *
- * 표(DeviceSideTable)와 '사용중인 기기' 패널(PanelRowDevice)이 같은 값을 각자
- * 그리므로 **규칙을 한 곳에 둔다** — 두 곳에서 따로 정하면 같은 인공와우가 한쪽은
- * 파랑, 한쪽은 초록으로 떠서 다른 것인 줄 알게 된다.
+ * 표(`DeviceSideTable`)와 '사용중인 기기' 패널(`PanelRowDevice`)이 같은 값을 각자 그리므로
+ * 규칙을 한 곳에 둔다 — 두 곳에서 따로 정하면 같은 인공와우가 한쪽은 파랑, 한쪽은 초록으로
+ * 떠서 다른 것인 줄 알게 된다.
  *
- * 값은 저장된 그대로의 한국어다(managed_device.type). 목록에 없는 값·빈 값은
- * 'default'(무채색)로 떨어뜨린다 — 모르는 종류를 아는 색으로 칠하지 않는다.
+ * **색만 모여 있고 이름은 안 모여 있었다** — `deviceTypeKeys`·`deviceTypeLabel` 이 그 두
+ * 파일에 **주석까지 똑같이 두 벌** 있었다(2026-10-13 말귀가 짚었다). 색에 적어 둔 그 까닭이
+ * 이름에도 그대로 들어맞는 자리다. 모았다.
  *
- * @public
+ * ## 값은 **코드**다 — 옛 한글 값도 받는다
+ *
+ * 저장값(`managed_device.type`)이 `'보청기'` 에서 `'hearingAid'` 로 옮겨 가는 중이다
+ * (사장님 지시 "저장된 한글 값도 다 영어로"). 앱이 판을 돌리는 때와 이 판이 깔리는 때가
+ * 어긋나고, 옛 자료를 보는 다른 기관이 있을 수 있어 **둘 다 받는다**.
+ *
+ * 받지 않으면 **터지지 않고 조용히 틀린다** — 배지에 `hearingAid` 가 날것으로 뜨고
+ * (`defaultValue: device` 로 떨어진다), 색이 둘 다 무채색이 되어 종류를 색으로 가르던 것이
+ * 사라진다. 눈으로만 잡히는 꼴이다.
+ */
+/** 저장값 → 코드. 옛 한글 값도 받는다(위 머리말) */
+const TO_KIND = {
+    hearingAid: 'hearingAid', cochlearImplant: 'cochlearImplant', other: 'other',
+    // 열쇠가 **저장된 값**이라 따옴표를 쥐어 둔다 — 이름이 아니다(이름은 영어로 쓴다)
+    '보청기': 'hearingAid', '인공와우': 'cochlearImplant', '기타': 'other',
+};
+/**
+ * 저장값을 종류 코드로 — 모르는 값은 `null`.
+ *
+ * **모르는 것을 `'other'` 로 접지 않는다.** 기타는 "기타" 라고 고른 값이고, 모르는 값은
+ * 아직 뜻을 모르는 것이다. 둘을 섞으면 새 종류가 생긴 날 조용히 '기타' 로 보인다.
+ */
+export function deviceKindOf(device) {
+    /* `device && …` 를 `?? null` 로 받으면 **빈 글자가 새어 나간다** — `'' && x` 는 `''` 이고
+       `?? ` 는 `null`·`undefined` 만 받으므로 `deviceKindOf('')` 가 `''` 를 돌려줬다(tsc 가 잡았다).
+       빈 값은 "종류가 없다" 이지 "빈 이름의 종류" 가 아니다. */
+    if (!device)
+        return null;
+    return TO_KIND[device] ?? null;
+}
+/**
+ * 배지 색. 목록에 없는 값·빈 값은 `'default'`(무채색)로 떨어뜨린다 —
+ * **모르는 종류를 아는 색으로 칠하지 않는다.**
  */
 export function deviceKindVariant(device) {
-    switch (device) {
-        case '보청기': return 'main';
-        case '인공와우': return 'sub';
+    switch (deviceKindOf(device)) {
+        case 'hearingAid': return 'main';
+        case 'cochlearImplant': return 'sub';
         default: return 'default';
     }
 }
+/**
+ * 배지에 적을 이름 — **지금 언어로**. 사전(`device.type.*`)이 쥔다.
+ *
+ * 모르는 값은 **저장된 그대로** 보인다. 숨기지 않는다 — 화면에 날것이 보이면 자료에 무엇이
+ * 들어 있는지 알 수 있고, 빈칸이면 아무것도 알 수 없다.
+ */
+export function deviceKindLabel(device, t) {
+    const kind = deviceKindOf(device);
+    return kind ? t(`device.type.${kind}`, { defaultValue: device ?? '' }) : (device ?? '');
+}

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

@@ -6,10 +6,10 @@ import i18n from 'i18next';
  * 여기서 `../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 : 기본;
+const unknownError = () => {
+    const fallback = '알 수 없는 오류';
+    const s = typeof i18n?.t === 'function' ? i18n.t('common.unknownError', { defaultValue: fallback }) : undefined;
+    return typeof s === 'string' && s ? s : fallback;
 };
 /**
  * 잡은 값에서 **사람이 읽을 수 있는 원인**을 꺼낸다.
@@ -33,7 +33,7 @@ const 알수없는오류 = () => {
 export function getErrorMessage(e, fallback) {
     // 기본 문구는 부를 때마다 지금 언어로 만든다(모듈 로드 때 한 번 정하면 언어 전환을 못 따른다)
     if (fallback === undefined)
-        fallback = 알수없는오류();
+        fallback = unknownError();
     if (e instanceof Error)
         return e.message || fallback;
     if (typeof e === 'string')
@@ -58,7 +58,7 @@ export function getErrorMessage(e, fallback) {
 export const NETWORK_ERROR_MESSAGE = '네트워크 연결이 불안정합니다. 연결 상태를 확인한 뒤 다시 시도해 주세요.';
 /* 화면에 내는 것은 지금 언어로(`common.networkError`, 사전에 없으면 위 한국어) — 상수만 돌려줘 영어 화면 토스트도 한국어였다.
    상수는 옛 소비자가 견주는 값이라 그대로 둔다. */
-const 네트워크오류 = () => {
+const networkError = () => {
     const s = typeof i18n?.t === 'function' ? i18n.t('common.networkError', { defaultValue: NETWORK_ERROR_MESSAGE }) : undefined;
     return typeof s === 'string' && s ? s : NETWORK_ERROR_MESSAGE;
 };
@@ -82,5 +82,5 @@ export function isNetworkErrorMessage(msg) {
  * @public
  */
 export function toUserErrorMessage(msg) {
-    return isNetworkErrorMessage(msg) ? 네트워크오류() : msg;
+    return isNetworkErrorMessage(msg) ? networkError() : msg;
 }

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

@@ -11,4 +11,4 @@ import type { FilterPanelSection } from '../types/filterPanel';
  * 안 담는 절: `note`(고르는 절이 아니다) · `input`(빈 칸을 '전체'라 말하면 거짓이다) ·
  * 고른 것이 없는데 '전체' 보기도 없는 절(말할 것이 없다).
  */
-export declare function buildFilterSummary(sections: readonly FilterPanelSection[], selected: Record<string, string | string[]> | undefined, 전체말: string): string;
+export declare function buildFilterSummary(sections: readonly FilterPanelSection[], selected: Record<string, string | string[]> | undefined, allLabel: string): string;

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

@@ -11,36 +11,36 @@ import { FILTER_ALL_VALUE } from '../types/filterPanel';
  * 안 담는 절: `note`(고르는 절이 아니다) · `input`(빈 칸을 '전체'라 말하면 거짓이다) ·
  * 고른 것이 없는데 '전체' 보기도 없는 절(말할 것이 없다).
  */
-export function buildFilterSummary(sections, selected, 전체말) {
-    const 조각들 = [];
+export function buildFilterSummary(sections, selected, allLabel) {
+    const parts = [];
     for (const section of sections ?? []) {
         if (section.type === 'note' || section.type === 'input')
             continue;
-        const 이름 = section.displayLabel ?? section.label;
-        const 값 = 값말(section, selected?.[section.label], 전체말);
-        if (값 === null)
+        const name = section.displayLabel ?? section.label;
+        const value = valueText(section, selected?.[section.label], allLabel);
+        if (value === null)
             continue;
-        조각들.push(`${이름} ${값}`);
+        parts.push(`${name} ${value}`);
     }
-    return 조각들.join(' · ');
+    return parts.join(' · ');
 }
 /** 한 절이 무엇으로 정해져 있는지 — 말할 것이 없으면 `null` */
-function 값말(section, sel, 전체말) {
-    const 고른것 = Array.isArray(sel) ? sel : sel === undefined ? [] : [sel];
+function valueText(section, sel, allLabel) {
+    const picked = Array.isArray(sel) ? sel : sel === undefined ? [] : [sel];
     /* '전체' 는 두 꼴로 온다 — 아무것도 안 고른 것과 '전체' 보기를 고른 것. 같은 말로 읽는다. */
-    const 실제 = 고른것.filter(v => v !== FILTER_ALL_VALUE);
-    if (실제.length === 0) {
-        return section.allOption ? (section.allLabel ?? 전체말) : null;
+    const actual = picked.filter(v => v !== FILTER_ALL_VALUE);
+    if (actual.length === 0) {
+        return section.allOption ? (section.allLabel ?? allLabel) : null;
     }
-    return 실제.map(v => 보기말(section, v)).join(', ');
+    return actual.map(v => optionText(section, v)).join(', ');
 }
 /** 고른 값 하나를 사람이 읽는 말로 — 보기 목록에 없으면 값 그대로 */
-function 보기말(section, value) {
-    const 보기들 = [
+function optionText(section, value) {
+    const options = [
         ...(section.items ?? []),
         ...(section.groups ?? []).flat(),
     ];
-    for (const item of 보기들) {
+    for (const item of options) {
         if (item == null)
             continue;
         if (typeof item === 'string') {

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

@@ -67,10 +67,10 @@ export function formatPhone(raw) {
  * **사람에게 거는 번호** — 휴대폰 · 지역번호(02·0NN) · 050X 안심번호 · 0303 착신전환.
  * 새 대역은 여기에만 더하면 아래 둘이 함께 받는다.
  */
-const 개인번호 = String.raw `(?:0\d{1,2}|050\d|0303)-\d{3,4}-\d{4}`;
+const PERSONAL_PHONE = String.raw `(?:0\d{1,2}|050\d|0303)-\d{3,4}-\d{4}`;
 /** **대표번호**(1588 등) — 거는 곳이 사람이 아니라 기관이다 */
-const 대표번호 = String.raw `1[5-9]\d{2}-\d{4}`;
-export const PHONE_REGEX = new RegExp(`^(?:${개인번호}|${대표번호})$`);
+const SERVICE_PHONE = String.raw `1[5-9]\d{2}-\d{4}`;
+export const PHONE_REGEX = new RegExp(`^(?:${PERSONAL_PHONE}|${SERVICE_PHONE})$`);
 /**
  * **대표번호를 뺀 것만** 받는 자 — `PHONE_REGEX` 에서 대표번호 갈래를 뺀 것이다.
  *
@@ -81,7 +81,7 @@ export const PHONE_REGEX = new RegExp(`^(?:${개인번호}|${대표번호})$`);
  * 않는 대역이 하나 더 생기는 날 **두 앱이 조용히 그것을 받게 된다.** 뜻대로 적어 둔다.
  * @public
  */
-export const PERSONAL_PHONE_REGEX = new RegExp(`^${개인번호}$`);
+export const PERSONAL_PHONE_REGEX = new RegExp(`^${PERSONAL_PHONE}$`);
 /** 연락처가 `formatPhone` 이 끝까지 채워 낸 모양인가 — 규칙은 `PHONE_REGEX`. @public */
 export function isValidPhone(phone) {
     return PHONE_REGEX.test(phone);

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

@@ -106,7 +106,7 @@ export async function loadTrainingData() {
         }
         /* 다 읽은 뒤에 한꺼번에 넣는다 — 도중에 형식 오류로 멈추면 이미 넣은 것이 남은 채 재시도가 또 넣어, 부를 때마다 풀에
            중복이 쌓였다(하루 선택이 중복 문항을 뽑고 기기마다 세트가 달라짐). */
-        const 받음 = { noise: [], short: [], long: [], order: [] };
+        const received = { noise: [], short: [], long: [], order: [] };
         try {
             for (const key of Object.keys(map || {})) {
                 const groups = map[key] || [];
@@ -121,16 +121,16 @@ export async function loadTrainingData() {
                     // Preserve original group structure from allTrainingData.json
                     const groupObj = Object.assign({}, gr, { training_type: t, category_0: cat0, category_1: cat1 });
                     if (t === 'LISTEN_IN_NOISE') {
-                        받음.noise.push(groupObj);
+                        received.noise.push(groupObj);
                     }
                     else if (t === 'SHORT_STORY') {
-                        받음.short.push(groupObj);
+                        received.short.push(groupObj);
                     }
                     else if (t === 'LONG_STORY') {
-                        받음.long.push(groupObj);
+                        received.long.push(groupObj);
                     }
                     else if (t === 'ORDERING_SENTENCE') {
-                        받음.order.push(groupObj);
+                        received.order.push(groupObj);
                     }
                 }
             }
@@ -148,10 +148,10 @@ export async function loadTrainingData() {
             catch { /* SSR 등 */ }
             return;
         }
-        NOISE_DATAS.push(...받음.noise);
-        SHORT_STORIES.push(...받음.short);
-        LONG_STORIES.push(...받음.long);
-        ORDER_SETS.push(...받음.order);
+        NOISE_DATAS.push(...received.noise);
+        SHORT_STORIES.push(...received.short);
+        LONG_STORIES.push(...received.long);
+        ORDER_SETS.push(...received.order);
         // 다 채운 뒤 _loaded 를 먼저 세운다 — 'updated' 를 받은 쪽이 isTrainingDataLoaded() 로 확인하면 아직 false 였다
         _loaded = true;
         try {

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

@@ -13,11 +13,11 @@ const LS_KEY = 'word_image_existence_map_v1';
 let memMap = null;
 /* 캐시가 바뀔 때마다 오르는 판 번호 — 통계·'있음' 낱말 집합을 판마다 한 번만 센다(단어훈련 칩 한 번에 유형 수만큼
    2.3만 칸을 훑었다). 캐시를 바꾸는 곳(확인 결과 담기·일괄 주입·비우기)은 모두 판을 올린다. */
-let 캐시판 = 0;
-let 통계판 = -1;
-let 통계값 = null;
-let 있음판 = -1;
-let 있음집합 = new Set();
+let cacheVersion = 0;
+let statsVersion = -1;
+let statsValue = null;
+let okVersion = -1;
+let okSet = new Set();
 const inflight = new Map(); // 중복 fetch 방지
 function ensureLoaded() {
     if (memMap)
@@ -80,7 +80,7 @@ export async function checkImageExists(word, homonum) {
         if (ok === null)
             return false;
         map[k] = ok;
-        캐시판++;
+        cacheVersion++;
         scheduleSave();
         return ok;
     });
@@ -143,24 +143,24 @@ export async function prewarmImageCache(words, options = {}) {
  */
 export function getImageExistenceStats() {
     const map = ensureLoaded();
-    if (통계판 === 캐시판)
-        return 통계값 ? { ...통계값 } : null;
+    if (statsVersion === cacheVersion)
+        return statsValue ? { ...statsValue } : null;
     const values = Object.values(map);
-    통계값 = values.length === 0 ? null : { total: values.length, exists: values.filter(Boolean).length };
-    통계판 = 캐시판;
-    return 통계값 ? { ...통계값 } : null;
+    statsValue = values.length === 0 ? null : { total: values.length, exists: values.filter(Boolean).length };
+    statsVersion = cacheVersion;
+    return statsValue ? { ...statsValue } : null;
 }
 /** @internal 동음이의 번호 없이(=1) '이미지 있음' 으로 확인된 낱말 집합 — 캐시 판마다 한 번 만든다. 돌려받은 집합을 고치지 말 것. */
 export function getImageOkWordSet() {
     const map = ensureLoaded();
-    if (있음판 === 캐시판)
-        return 있음집합;
+    if (okVersion === cacheVersion)
+        return okSet;
     const s = new Set();
     for (const k in map)
         if (map[k] === true && k.endsWith('_1'))
             s.add(k.slice(0, -2));
-    있음집합 = s;
-    있음판 = 캐시판;
+    okSet = s;
+    okVersion = cacheVersion;
     return s;
 }
 /**
@@ -171,7 +171,7 @@ export function getImageOkWordSet() {
 export function bulkSetImageExistence(entries) {
     const map = ensureLoaded();
     Object.assign(map, entries);
-    캐시판++;
+    cacheVersion++;
     try {
         if (typeof localStorage !== 'undefined') {
             localStorage.setItem(LS_KEY, JSON.stringify(map));
@@ -182,7 +182,7 @@ export function bulkSetImageExistence(entries) {
 /** @public 캐시 초기화 (이미지 데이터 변경 시 호출) */
 export function clearImageExistenceCache() {
     memMap = {};
-    캐시판++;
+    cacheVersion++;
     try {
         if (typeof localStorage !== 'undefined')
             localStorage.removeItem(LS_KEY);

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

@@ -241,10 +241,10 @@ export function wordContainsJungseong(word, jamo) {
 }
 /** 음절의 종성이 고른 자모 하나와 맞는지 — 두 모드의 단일 출처. */
 function jongMatchesJamo(jong, jamo, mode) {
-    const 글자 = JONGSEONG[jong];
-    if (글자 === jamo)
+    const glyph = JONGSEONG[jong];
+    if (glyph === jamo)
         return true;
-    return mode === 'phoneme' && finalToPhoneme(글자) === finalToPhoneme(jamo);
+    return mode === 'phoneme' && finalToPhoneme(glyph) === finalToPhoneme(jamo);
 }
 /** @public 단어가 특정 자모를 종성(coda)으로 포함하는지.
  *  `jongMatch` 로 **글자 그대로**(기본) · **받침 소리**(`'phoneme'`)를 고른다 — `JongMatch` 설명을 본다. */
@@ -373,41 +373,41 @@ export function wordHasConsonantAt(word, parts, position,
 jongMatch = 'glyph') {
     if (!word)
         return false;
-    const 음절 = [...word].map(parseSyllable).filter((s) => !!s);
-    if (음절.length === 0)
+    const syllables = [...word].map(parseSyllable).filter((s) => !!s);
+    if (syllables.length === 0)
         return false;
-    const 끝 = 음절.length - 1;
+    const last = syllables.length - 1;
     if (position === 'head') {
         /* 어두는 **첫 음절의 초성**뿐이다. `ㅇ` 은 음가가 없어 자리를 안 가진다 —
            `아기` 의 어두초성은 **없다**(`cho: ['ㅇ']` 로 물으면 거짓). */
         if (!parts.cho)
             return false;
-        const c = CHOSEONG[음절[0].cho];
+        const c = CHOSEONG[syllables[0].cho];
         return c !== 'ㅇ' && parts.cho.includes(c);
     }
     if (position === 'tail') {
         /* 어말은 **마지막 받침**뿐이다. 받침이 없으면 자리가 없다. */
         if (parts.jongNone)
-            return 음절[끝].jong === 0;
+            return syllables[last].jong === 0;
         if (!parts.jong)
             return false;
-        return syllableJongMatches(음절[끝], parts.jong, jongMatch);
+        return syllableJongMatches(syllables[last], parts.jong, jongMatch);
     }
     /* 어중 — 첫 초성과 마지막 종성을 **뺀** 나머지 자음 전부. 2음절 `선물` 이면
        ㄴ(0번 종성) · ㅁ(1번 초성) 둘이 어중이다. */
-    const 초성맞나 = !parts.cho || 음절.some((s, i) => {
+    const onsetMatches = !parts.cho || syllables.some((s, i) => {
         if (i === 0)
             return false; // 첫 초성은 어두다
         const c = CHOSEONG[s.cho];
         return c !== 'ㅇ' && parts.cho.includes(c); // 음가 없는 ㅇ 은 자리를 안 가진다
     });
-    const 종성맞나 = parts.jongNone
-        ? 음절.some((s, i) => i !== 끝 && s.jong === 0)
-        : !parts.jong || 음절.some((s, i) => i !== 끝 && syllableJongMatches(s, parts.jong, jongMatch));
+    const codaMatches = parts.jongNone
+        ? syllables.some((s, i) => i !== last && s.jong === 0)
+        : !parts.jong || syllables.some((s, i) => i !== last && syllableJongMatches(s, parts.jong, jongMatch));
     /* 둘 다 줬으면 **둘 다** 있어야 한다(AND) — 하나만 줬으면 그쪽만 참이면 된다 */
     if (!parts.cho && !parts.jong && !parts.jongNone)
         return false;
-    return 초성맞나 && 종성맞나;
+    return onsetMatches && codaMatches;
 }
 /**
  * @public 문자열이 음절 패턴 DSL 문법인지 — 쉼표(,) 포함 여부로 판별한다.
@@ -749,12 +749,12 @@ export function searchAndRankWords(items, query) {
     const headLen = [...q].length;
     const startsWith = (s) => !!s && m(s.normalize('NFC').slice(0, headLen));
     // 순위는 두 갈래로 나눠 잇는다(안정 정렬과 같은 순서)
-    const 앞 = [];
-    const 뒤 = [];
+    const before = [];
+    const after = [];
     for (const w of items) {
         if (!(m(w.word) || m(w.pronunciation ?? '')))
             continue;
-        (startsWith(w.word) || startsWith(w.pronunciation ?? '') ? 앞 : 뒤).push(w);
+        (startsWith(w.word) || startsWith(w.pronunciation ?? '') ? before : after).push(w);
     }
-    return 앞.concat(뒤);
+    return before.concat(after);
 }

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

@@ -1,6 +1,6 @@
 import type { RefObject } from 'react';
 /** 소비자가 통을 안 알려 줄 때 찾아 보는 이름 — 옛 동작 유지(말귀 셸의 본문). @internal */
-export declare const 기본통고르개 = ".content-area";
+export declare const DEFAULT_SCROLL_SELECTOR = ".content-area";
 /**
  * 갈래를 고른 뒤 본문을 맨 위로 — 내비(SideNav·BottomNav)가 함께 쓴다. @internal
  *
@@ -8,4 +8,4 @@ export declare const 기본통고르개 = ".content-area";
  * 그것이 **아무 일도 하지 않는다** — 그때는 조용히 죽는 대신 개발 모드에 한 번 알린다.
  * 코어가 `.content-area`(소비자 클래스 이름)를 붙잡고 있던 자리라, 부르는 쪽이 통을 알려 주는 것이 정본이다.
  */
-export declare function scrollNavTargetToTop(scrollContainer?: string | RefObject<HTMLElement | null>, 어디서?: string): void;
+export declare function scrollNavTargetToTop(scrollContainer?: string | RefObject<HTMLElement | null>, from?: string): void;

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

@@ -1,6 +1,6 @@
 import { devWarnOnce } from './devWarn';
 /** 소비자가 통을 안 알려 줄 때 찾아 보는 이름 — 옛 동작 유지(말귀 셸의 본문). @internal */
-export const 기본통고르개 = '.content-area';
+export const DEFAULT_SCROLL_SELECTOR = '.content-area';
 /**
  * 갈래를 고른 뒤 본문을 맨 위로 — 내비(SideNav·BottomNav)가 함께 쓴다. @internal
  *
@@ -8,18 +8,18 @@ export const 기본통고르개 = '.content-area';
  * 그것이 **아무 일도 하지 않는다** — 그때는 조용히 죽는 대신 개발 모드에 한 번 알린다.
  * 코어가 `.content-area`(소비자 클래스 이름)를 붙잡고 있던 자리라, 부르는 쪽이 통을 알려 주는 것이 정본이다.
  */
-export function scrollNavTargetToTop(scrollContainer, 어디서 = 'Nav') {
+export function scrollNavTargetToTop(scrollContainer, from = 'Nav') {
     try {
         const el = typeof scrollContainer === 'string'
             ? document.querySelector(scrollContainer)
-            : scrollContainer?.current ?? document.querySelector(기본통고르개);
+            : scrollContainer?.current ?? document.querySelector(DEFAULT_SCROLL_SELECTOR);
         if (el) {
             el.scrollTop = 0;
             return;
         }
-        const 문서 = document.scrollingElement ?? document.documentElement;
-        if (문서 && 문서.scrollHeight <= 문서.clientHeight) {
-            devWarnOnce('nav-scroll-container', `[${어디서}] 본문을 맨 위로 되돌릴 통을 못 찾았다(기본 ${기본통고르개}) — 창도 구를 수 없어 아무 일도 하지 않는다. scrollContainer 로 통을 알려 준다.`);
+        const doc = document.scrollingElement ?? document.documentElement;
+        if (doc && doc.scrollHeight <= doc.clientHeight) {
+            devWarnOnce('nav-scroll-container', `[${from}] 본문을 맨 위로 되돌릴 통을 못 찾았다(기본 ${DEFAULT_SCROLL_SELECTOR}) — 창도 구를 수 없어 아무 일도 하지 않는다. scrollContainer 로 통을 알려 준다.`);
         }
         window.scrollTo({ top: 0 });
     }

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

@@ -15,4 +15,11 @@ export declare const VOWEL_TO_PHONEME: Record<string, {
 export declare function vowelGlidesDiffer(a: string, b: string): boolean;
 /** 종성 글자 → 음소(대표음) 변환. 매핑에 없으면 원본 유지. */
 export declare function finalToPhoneme(jong: string): string;
+/**
+ * 고른 글자를 음소 꼴로 — **열쇠는 코드로 낸다**(`onset`·`vowel`·`coda`·`glide`).
+ *
+ * **들어오는 것은 둘 다 받는다** — 저장된 단어표의 고른값은 옛 한글 열쇠(`{ 초성: 'ㄴ' }`)일
+ * 수 있다(2026-10-13 코드로 옮기며, 저장된 표를 밀지 않으려고 읽는 쪽을 너그럽게 뒀다).
+ * 값(자모·`'ㄴ'`)은 한국어 글자 그 자체라 그대로 둔다 — 바꿀 것은 **열쇠와 빔 값**이다.
+ */
 export declare function convertToPhoneme(sel: Record<string, string>): Record<string, string>;

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

@@ -1,3 +1,4 @@
+import { toPhonemeCodes, PHONEME_NONE } from './phonemeSectionCodes';
 export const VALID_GLIDES = {
     ㅏ: ['j', 'w'], ㅓ: ['j', 'w'], ㅗ: ['j'], ㅜ: ['j'],
     'ㅔ/ㅐ': ['j', 'w'], ㅣ: ['w', 'ɰ'], ㅡ: [],
@@ -44,21 +45,29 @@ export function vowelGlidesDiffer(a, b) {
 export function finalToPhoneme(jong) {
     return JONGSEONG_TO_PHONEME[jong] ?? jong;
 }
+/**
+ * 고른 글자를 음소 꼴로 — **열쇠는 코드로 낸다**(`onset`·`vowel`·`coda`·`glide`).
+ *
+ * **들어오는 것은 둘 다 받는다** — 저장된 단어표의 고른값은 옛 한글 열쇠(`{ 초성: 'ㄴ' }`)일
+ * 수 있다(2026-10-13 코드로 옮기며, 저장된 표를 밀지 않으려고 읽는 쪽을 너그럽게 뒀다).
+ * 값(자모·`'ㄴ'`)은 한국어 글자 그 자체라 그대로 둔다 — 바꿀 것은 **열쇠와 빔 값**이다.
+ */
 export function convertToPhoneme(sel) {
+    const coded = toPhonemeCodes(sel);
     const result = {};
-    if (sel['초성'])
-        result['초성'] = sel['초성'];
-    if (sel['모음']) {
-        const m = VOWEL_TO_PHONEME[sel['모음']];
-        // 활음을 항상 명시한다('없음' 포함). 단어 분해(decomposePhonemicSyllable)는 활음 없는 모음에도
-        // 활음:'없음'을 넣으므로, 선택 변환도 대칭으로 맞춰야 활음 대비(예: ㅐ↔ㅙ = 없음↔w)가 매칭된다.
+    if (coded.onset)
+        result.onset = coded.onset;
+    if (coded.vowel) {
+        const m = VOWEL_TO_PHONEME[coded.vowel];
+        // 활음을 항상 명시한다(빔 포함). 단어 분해(decomposePhonemicSyllable)는 활음 없는 모음에도
+        // glide: 빔을 넣으므로, 선택 변환도 대칭으로 맞춰야 활음 대비(예: ㅐ↔ㅙ = 빔↔w)가 매칭된다.
         // (안 넣으면 ㅐ/ㅔ↔ㅚ/ㅙ 대립이 모음(nucleus)만 같고 대비 섹션이 없어 0건이 됨.)
         if (m) {
-            result['모음'] = m.nucleus;
-            result['활음'] = m.glide ?? '없음';
+            result.vowel = m.nucleus;
+            result.glide = m.glide ?? PHONEME_NONE;
         }
     }
-    if (sel['종성'])
-        result['종성'] = JONGSEONG_TO_PHONEME[sel['종성']] ?? sel['종성'];
+    if (coded.coda)
+        result.coda = JONGSEONG_TO_PHONEME[coded.coda] ?? coded.coda;
     return result;
 }

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

@@ -50,8 +50,8 @@ export function phoneticLabel(t, f) {
     return f.glide ? `${v} · ${GLIDE_LABEL[f.glide](t)}` : v;
 }
 /** 기본값만 돌려주는 t — 옛 `tooltip`(한국어 고정)을 같은 표에서 만들어 두 글이 갈라지지 않게 한다. */
-const 한국어 = (_key, { defaultValue }) => defaultValue;
-const item = (jamos, phonetic) => ({ jamos, phonetic, tooltip: phoneticLabel(한국어, phonetic) });
+const koTranslate = (_key, { defaultValue }) => defaultValue;
+const item = (jamos, phonetic) => ({ jamos, phonetic, tooltip: phoneticLabel(koTranslate, phonetic) });
 /** 자음 행: 같은 조음 위치를 공유하는 단일 자모 버튼들. */
 const consonantRow = (place, jamos) => jamos.map(j => item([j], { place }));
 /** 모음/병합 아이템: `chars`가 여러 글자면 동음 병합 버튼(예: 'ㅔㅐ' → ['ㅔ','ㅐ']). */

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

@@ -1,5 +1,6 @@
 export type { WordEntry, PairFilterKeys, SearchPairsDebugReport } from './phonemePairSearchTypes';
 import type { WordSearchResultItem } from '../types/wordSearch';
+export { toPhonemeCodes, PHONEME_NONE, type PhonemeSectionCode } from './phonemeSectionCodes';
 import type { WordEntry } from './phonemePairSearchTypes';
 import type { PairFilterKeys } from './phonemePairSearchTypes';
 /** applyFilters/matchesFilters가 공통으로 판정하는 필드 — WordEntry와 WordSearchResultWord