@ihabdevteam/core 0.318.0 → 0.322.0

package/dist/packages/core/src/i18n/locales/ko.json

@@ -888,6 +888,7 @@
             "positionTail": "어말",
             "difficulty": "등급",
             "grade": "{{n}}등급",
+            "gradeNone": "없음",
             "syllables": "음절 수",
             "syllable": "{{n}}음절",
             "syllable5plus": "5음절 이상",
@@ -1134,11 +1135,13 @@
             ],
             "orderAny": "무관",
             "orderMatch": "일치",
-            "difficultyInfo1": "1등급 : 학령전기에 습득하여 평생에 걸쳐 일상 언어생활을 하는 데 사용되는 어휘",
-            "difficultyInfo2": "2등급 : 초등학교 1-2학년 난이도 어휘",
-            "difficultyInfo3": "3등급 : 초등학교 3-4학년 난이도 어휘",
-            "difficultyInfo4": "4등급 : 초등학교 5-6학년 난이도 어휘",
-            "difficultyInfo5": "등급없음 : 국립국어원 표준 어휘 외 고빈도 생활 어휘, 신조어 및 외래어",
+            "difficultyInfo": [
+                "1등급 : 학령전기에 습득하여 평생에 걸쳐 일상 언어생활을 하는 데 사용되는 어휘",
+                "2등급 : 초등학교 1-2학년 난이도 어휘",
+                "3등급 : 초등학교 3-4학년 난이도 어휘",
+                "4등급 : 초등학교 5-6학년 난이도 어휘",
+                "등급없음 : 국립국어원 표준 어휘 외 고빈도 생활 어휘, 신조어 및 외래어"
+            ],
             "selectLabel": "선택",
             "onlyHasImage": "이미지 있는 단어만",
             "onlySameStructure": "음소 구조 같은 단어만"

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

@@ -1,5 +1,5 @@
 export declare const isDev: boolean;
-/** `키` 하나당 한 번만 찍는다. 운영 빌드에서는 아무 일도 하지 않는다. */
-export declare function devWarnOnce(키: string, ...말: unknown[]): void;
+/** `key` 하나당 한 번만 찍는다. 운영 빌드에서는 아무 일도 하지 않는다. */
+export declare function devWarnOnce(key: string, ...args: unknown[]): void;
 /** 시험용 — 기록을 비운다. 운영 코드에서 부를 일은 없다. */
 export declare function __resetDevWarnOnce(): void;

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

@@ -27,12 +27,12 @@ export const isDev = (() => {
         return false;
     }
 })();
-/** `키` 하나당 한 번만 찍는다. 운영 빌드에서는 아무 일도 하지 않는다. */
-export function devWarnOnce(키, ...말) {
-    if (!isDev || 찍은것.has(키))
+/** `key` 하나당 한 번만 찍는다. 운영 빌드에서는 아무 일도 하지 않는다. */
+export function devWarnOnce(key, ...args) {
+    if (!isDev || 찍은것.has(key))
         return;
-    찍은것.add(키);
-    console.warn(...말);
+    찍은것.add(key);
+    console.warn(...args);
 }
 /** 시험용 — 기록을 비운다. 운영 코드에서 부를 일은 없다. */
 export function __resetDevWarnOnce() {

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,13 +11,13 @@ import { FILTER_ALL_VALUE } from '../types/filterPanel';
  * 안 담는 절: `note`(고르는 절이 아니다) · `input`(빈 칸을 '전체'라 말하면 거짓이다) ·
  * 고른 것이 없는데 '전체' 보기도 없는 절(말할 것이 없다).
  */
-export function buildFilterSummary(sections, selected, 전체말) {
+export function buildFilterSummary(sections, selected, allLabel) {
     const 조각들 = [];
     for (const section of sections ?? []) {
         if (section.type === 'note' || section.type === 'input')
             continue;
         const 이름 = section.displayLabel ?? section.label;
-        const 값 = 값말(section, selected?.[section.label], 전체말);
+        const 값 = 값말(section, selected?.[section.label], allLabel);
         if (값 === null)
             continue;
         조각들.push(`${이름} ${값}`);
@@ -25,12 +25,12 @@ export function buildFilterSummary(sections, selected, 전체말) {
     return 조각들.join(' · ');
 }
 /** 한 절이 무엇으로 정해져 있는지 — 말할 것이 없으면 `null` */
-function 값말(section, sel, 전체말) {
+function 값말(section, sel, allLabel) {
     const 고른것 = Array.isArray(sel) ? sel : sel === undefined ? [] : [sel];
     /* '전체' 는 두 꼴로 온다 — 아무것도 안 고른 것과 '전체' 보기를 고른 것. 같은 말로 읽는다. */
     const 실제 = 고른것.filter(v => v !== FILTER_ALL_VALUE);
     if (실제.length === 0) {
-        return section.allOption ? (section.allLabel ?? 전체말) : null;
+        return section.allOption ? (section.allLabel ?? allLabel) : null;
     }
     return 실제.map(v => 보기말(section, v)).join(', ');
 }

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 로 통을 알려 준다.`);
+            devWarnOnce('nav-scroll-container', `[${from}] 본문을 맨 위로 되돌릴 통을 못 찾았다(기본 ${DEFAULT_SCROLL_SELECTOR}) — 창도 구를 수 없어 아무 일도 하지 않는다. scrollContainer 로 통을 알려 준다.`);
         }
         window.scrollTo({ top: 0 });
     }

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

@@ -115,7 +115,7 @@ const POS_GROUP_MAP_KO = {
     '용언(동사,형용사)': ['동', '형'],
     '수식언(부사,관형사)': ['부', '관'],
 };
-import { POS_CODE_TARGETS, WORD_TYPE_CODE_VALUES, wordAttributeSectionOf, wordAttributeValueCodeOf } from './wordAttributeFilterCodes';
+import { POS_CODE_TARGETS, WORD_TYPE_CODE_VALUES, wordAttributeSectionOf, wordAttributeValueCodeOf, matchesGradeCodes } from './wordAttributeFilterCodes';
 const DEFAULT_PAIR_FILTER_KEYS = {
     difficulty: '난이도 등급',
     syllables: '음절 수',
@@ -155,8 +155,15 @@ function 모으기(filterSelected, keys) {
  */
 export function matchesFilters(word, filterSelected, keys = DEFAULT_PAIR_FILTER_KEYS) {
     const { grades, syls, poses, types } = 모으기(filterSelected, keys);
-    if (grades.length && !grades.some(g => word.grade === (wordAttributeValueCodeOf('grade', g) ?? g.replace(/\D/g, ''))))
-        return false;
+    if (grades.length) {
+        /* **`없음` 은 값이 아니라 빔이다**((205), 2026-10-12) — 거르는 결정은 `matchesGradeCodes` **하나**다
+           (단어훈련 풀도 같은 것을 부른다). 여기서는 라벨을 코드로만 바꾼다.
+           되거름(숫자만 남기기)이 `''` 를 내면 **버린다** — 빈 되거름이 그대로 가면 빈 등급 단어가 **우연히**
+           걸려, 사전에서 라벨이 빠진 날 `없음` 이 겉보기엔 되는 꼴이 된다. 그 흠은 제일 늦게 들킨다. */
+        const codes = grades.map(g => wordAttributeValueCodeOf('grade', g) ?? g.replace(/\D/g, '')).filter(c => c !== '');
+        if (codes.length === 0 || !matchesGradeCodes(codes, word.grade))
+            return false;
+    }
     if (syls.length) {
         const len = word.syllables ?? 0;
         const match = syls.some(syl => {

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

@@ -17,7 +17,7 @@
 export declare function pressable<E extends {
     key: string;
     preventDefault: () => void;
-}>(onPress?: (e: E) => void, 옵션?: {
+}>(onPress?: (e: E) => void, options?: {
     role?: 'button' | 'option';
     selected?: boolean;
 }): {};

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

@@ -14,13 +14,13 @@
  * 진짜 `<button>` 을 쓸 수 있으면 그쪽이 낫다. 이건 이미 `<div>`·`<li>` 로 짜인
  * 자리를 **모양을 안 바꾸고** 눌리게 만드는 길이다.
  */
-export function pressable(onPress, 옵션) {
+export function pressable(onPress, options) {
     if (!onPress)
         return {};
     return {
-        role: 옵션?.role ?? 'button',
+        role: options?.role ?? 'button',
         tabIndex: 0,
-        ...(옵션?.selected === undefined ? {} : { 'aria-selected': 옵션.selected }),
+        ...(options?.selected === undefined ? {} : { 'aria-selected': options.selected }),
         onKeyDown: (e) => {
             /* **이 자리 자신에서 난 키만** 받는다. 안에 든 진짜 단추(랜딩 띠의 action 등)에서 누른 Enter 가 올라오면
                전에는 여기서 preventDefault 해 그 단추의 click 을 막고 이 자리의 onPress 를 대신 불렀다. */

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

@@ -20,17 +20,17 @@ export interface TabSessionLike {
  * 여기서 막으면 이 탭이 로그인된 채로 남는다 — 막는 것보다 나쁜 쪽이다.
  *
  * ```ts
- * onAuthStateChange((event, 받은것) => {
+ * onAuthStateChange((event, incoming) => {
  *   getSession().then(({ data }) => {
- *     const 이탭것 = data.session
- *     if (!isSessionForThisTab(받은것, 이탭것)) return   // 다른 탭에서 온 것 — 무시
- *     …이탭것 으로 상태를 맞춘다
+ *     const thisTab = data.session
+ *     if (!isSessionForThisTab(incoming, thisTab)) return   // 다른 탭에서 온 것 — 무시
+ *     …thisTab 으로 상태를 맞춘다
  *   })
  * })
  * ```
  *
- * @param 받은것 이벤트가 실어 온 세션(없을 수 있다)
- * @param 이탭것 `getSession()` 이 이 탭 저장소에서 다시 읽은 세션
+ * @param incoming 이벤트가 실어 온 세션(없을 수 있다)
+ * @param thisTab `getSession()` 이 이 탭 저장소에서 다시 읽은 세션
  * @public
  */
-export declare function isSessionForThisTab(받은것: TabSessionLike | null | undefined, 이탭것: TabSessionLike | null | undefined): boolean;
+export declare function isSessionForThisTab(incoming: TabSessionLike | null | undefined, thisTab: TabSessionLike | null | undefined): boolean;

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

@@ -16,21 +16,21 @@
  * 여기서 막으면 이 탭이 로그인된 채로 남는다 — 막는 것보다 나쁜 쪽이다.
  *
  * ```ts
- * onAuthStateChange((event, 받은것) => {
+ * onAuthStateChange((event, incoming) => {
  *   getSession().then(({ data }) => {
- *     const 이탭것 = data.session
- *     if (!isSessionForThisTab(받은것, 이탭것)) return   // 다른 탭에서 온 것 — 무시
- *     …이탭것 으로 상태를 맞춘다
+ *     const thisTab = data.session
+ *     if (!isSessionForThisTab(incoming, thisTab)) return   // 다른 탭에서 온 것 — 무시
+ *     …thisTab 으로 상태를 맞춘다
  *   })
  * })
  * ```
  *
- * @param 받은것 이벤트가 실어 온 세션(없을 수 있다)
- * @param 이탭것 `getSession()` 이 이 탭 저장소에서 다시 읽은 세션
+ * @param incoming 이벤트가 실어 온 세션(없을 수 있다)
+ * @param thisTab `getSession()` 이 이 탭 저장소에서 다시 읽은 세션
  * @public
  */
-export function isSessionForThisTab(받은것, 이탭것) {
-    if (!받은것)
+export function isSessionForThisTab(incoming, thisTab) {
+    if (!incoming)
         return true;
-    return !!이탭것 && 이탭것.access_token === 받은것.access_token;
+    return !!thisTab && thisTab.access_token === incoming.access_token;
 }

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

@@ -1,5 +1,5 @@
 /** 글자 둘을 한국어 차례로 견준다 */
-export declare function 한글순(a: string, b: string): number;
+export declare function compareKorean(a: string, b: string): number;
 /**
  * 표의 한 칸끼리 견준다 — **숫자는 숫자로, 글자 속 숫자도 수로.**
  *
@@ -13,10 +13,20 @@ export declare function 한글순(a: string, b: string): number;
  * 비어 있는 값(`null`·`undefined`·NaN)은 빈 글자로 본다 — 부르는 쪽이 이미
  * `?? ''` 로 채워 넘기던 것과 같은 뜻이다.
  */
-export declare function 칸순(a: unknown, b: unknown): number;
+export declare function compareCell(a: unknown, b: unknown): number;
 /**
- * 표 정렬 한 번의 비교 — 칸순에 방향을 입히되 **빈 값은 오름·내림 모두 맨 뒤.**
- * 방향을 `-칸순` 으로 뒤집기만 하면 빈 값이 오름차순 맨 앞·내림차순 맨 뒤로 오가, 표마다 빈 줄이 다른 끝에 섰다.
+ * @deprecated **`compareCell` 을 쓴다 — 같은 함수다.**
+ *
+ * 2026-10-13 공개 이름을 영어로 옮기며(사장님 지시) 옛 이름을 남겼다. 말귀가
+ * `import { 칸순 } from '@ihabdevteam/core/utils/textSort'` 를 **다섯 줄**에서
+ * 쓰고 있어 한 번에 걷으면 그쪽이 통째로 빨개진다. 옮긴 뒤 알려 주면 걷는다.
+ *
+ * 같은 꼴로 남겨 둔 것이 또 있다 — `useTableSort()` 의 `정렬`·`칸`.
+ */
+export declare const 칸순: typeof compareCell;
+/**
+ * 표 정렬 한 번의 비교 — compareCell에 방향을 입히되 **빈 값은 오름·내림 모두 맨 뒤.**
+ * 방향을 `-compareCell` 으로 뒤집기만 하면 빈 값이 오름차순 맨 앞·내림차순 맨 뒤로 오가, 표마다 빈 줄이 다른 끝에 섰다.
  * ListPopup 과 useTableSort().sortRows 가 함께 쓴다.
  */
-export declare function 칸순빈값뒤(a: unknown, b: unknown, asc: boolean): number;
+export declare function compareCellBlankLast(a: unknown, b: unknown, asc: boolean): number;

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

@@ -19,7 +19,7 @@ const 콜레이터 = (() => {
     };
 })();
 /** 글자 둘을 한국어 차례로 견준다 */
-export function 한글순(a, b) {
+export function compareKorean(a, b) {
     return 콜레이터().compare(a, b);
 }
 const 조각열쇠 = new Map();
@@ -77,7 +77,7 @@ function 전화열쇠(s) {
  * 비어 있는 값(`null`·`undefined`·NaN)은 빈 글자로 본다 — 부르는 쪽이 이미
  * `?? ''` 로 채워 넘기던 것과 같은 뜻이다.
  */
-export function 칸순(a, b) {
+export function compareCell(a, b) {
     const 글 = (v) => (v == null || (typeof v === 'number' && Number.isNaN(v)) ? '' : String(v).trim());
     const sa = 글(a), sb = 글(b);
     if (sa === sb)
@@ -102,25 +102,35 @@ export function 칸순(a, b) {
             return -1;
         if (typeof y === 'number')
             return 1;
-        const c = 한글순(x, y);
+        const c = compareKorean(x, y);
         if (c !== 0)
             return c;
     }
     if (ka.length !== kb.length)
         return ka.length - kb.length;
-    return 한글순(sa, sb);
+    return compareKorean(sa, sb);
 }
-/* 빈 값 — null·undefined·NaN·빈 글자(빈칸만 있는 글자 포함). 칸순이 '' 로 보는 것과 같은 범위. */
+/**
+ * @deprecated **`compareCell` 을 쓴다 — 같은 함수다.**
+ *
+ * 2026-10-13 공개 이름을 영어로 옮기며(사장님 지시) 옛 이름을 남겼다. 말귀가
+ * `import { 칸순 } from '@ihabdevteam/core/utils/textSort'` 를 **다섯 줄**에서
+ * 쓰고 있어 한 번에 걷으면 그쪽이 통째로 빨개진다. 옮긴 뒤 알려 주면 걷는다.
+ *
+ * 같은 꼴로 남겨 둔 것이 또 있다 — `useTableSort()` 의 `정렬`·`칸`.
+ */
+export const 칸순 = compareCell;
+/* 빈 값 — null·undefined·NaN·빈 글자(빈칸만 있는 글자 포함). compareCell이 '' 로 보는 것과 같은 범위. */
 const 빈칸값 = (v) => v == null || (typeof v === 'number' && Number.isNaN(v)) || (typeof v === 'string' && v.trim() === '');
 /**
- * 표 정렬 한 번의 비교 — 칸순에 방향을 입히되 **빈 값은 오름·내림 모두 맨 뒤.**
- * 방향을 `-칸순` 으로 뒤집기만 하면 빈 값이 오름차순 맨 앞·내림차순 맨 뒤로 오가, 표마다 빈 줄이 다른 끝에 섰다.
+ * 표 정렬 한 번의 비교 — compareCell에 방향을 입히되 **빈 값은 오름·내림 모두 맨 뒤.**
+ * 방향을 `-compareCell` 으로 뒤집기만 하면 빈 값이 오름차순 맨 앞·내림차순 맨 뒤로 오가, 표마다 빈 줄이 다른 끝에 섰다.
  * ListPopup 과 useTableSort().sortRows 가 함께 쓴다.
  */
-export function 칸순빈값뒤(a, b, asc) {
+export function compareCellBlankLast(a, b, asc) {
     const ea = 빈칸값(a), eb = 빈칸값(b);
     if (ea || eb)
         return ea === eb ? 0 : ea ? 1 : -1;
-    const c = 칸순(a, b);
+    const c = compareCell(a, b);
     return asc ? c : -c;
 }

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

@@ -1,5 +1,40 @@
 /** @public 공용 속성 필터 섹션 코드 */
 export type WordAttributeSectionCode = 'grade' | 'syllables' | 'pos' | 'wordType';
+/**
+ * **등급이 빈 단어를 가리키는 코드** — `'none'`((205), 사장님 지시 2026-10-12).
+ *
+ * ## 이것은 **값이 아니라 빔**이다
+ *
+ * `'1'`~`'4'` 는 단어의 `grade` 에 **그 글자가 들어 있다.** `'none'` 은 다르다 — 어느 단어의
+ * `grade` 도 `'none'` 이 아니고, 가리키는 것은 **`grade` 가 비어 있다**는 사실이다
+ * (`undefined` · `null` · `''`, 그리고 공백만 든 것도).
+ *
+ * 그래서 **맞추개가 이 코드만은 다른 길로 간다** — `word.grade === code` 가 아니라
+ * `isBlankGrade(word.grade)` 로 본다(`phonemePairSearch.matchesFilters`). 같은 꼴로 재면
+ * 한 단어도 안 걸리고, 그런데 **필터는 멀쩡히 켜져 보인다.**
+ *
+ * **숫자 길에도 안 걸린다** — 아래 `wordAttributeValueCodeOf` 가 등급을 숫자로도 읽는데
+ * (`'3등급'` → `'3'`), `'없음'` 은 숫자가 없어 `NaN` 이 되어 그 길에서 `null` 로 떨어진다.
+ * 그러니 **사전에 라벨이 있어야** 읽힌다. 사전에서 빠지면 조용히 안 읽힌다 —
+ * `test/gradeNoneOption.test.ts` 가 그 자리를 센다.
+ */
+export declare const GRADE_NONE = "none";
+/** 등급이 비었나 — `'none'` 이 가리키는 그 **빔**을 한 자리에서 판정한다. 공백만 든 것도 빔이다. */
+export declare function isBlankGrade(grade: string | null | undefined): boolean;
+/** 등급 코드인가 — `'1'`~`'4'`·`'none'`. 저장된 값을 되읽을 때 **아닌 것은 버린다**(한때 `''` 가 저장됐다). */
+export declare function isGradeCode(v: unknown): v is string;
+/**
+ * **등급 코드 집합으로 단어 하나를 거른다 — 이 결정은 여기 하나다.**
+ *
+ * (205) 를 지을 때 맞추개를 `phonemePairSearch.matchesFilters` 하나로 알고 넷을 고쳤는데,
+ * **단어훈련 풀**(`wordTrainingPool`)이 같은 결정을 **두 줄로 따로** 갖고 있었다
+ * (`!w.grade || !gradeSet.has(w.grade)`). 그 둘은 빈 등급을 **늘 떨어뜨리므로** `없음` 을 골라도
+ * 0개였다(말귀_1 실측 2026-10-12: 매니저 단어표는 맞고 단어훈련 페이지는 틀렸다).
+ *
+ * **같은 결정이 세 자리에 적혀 있으면 하나는 안 따라온다.** 그래서 세 자리가 이 하나를 부른다.
+ * `codes` 가 비면 거르지 않는다(전체).
+ */
+export declare function matchesGradeCodes(codes: ReadonlySet<string> | readonly string[] | null | undefined, grade: string | null | undefined): boolean;
 /**
  * @public 공용 속성 필터를 **언어와 무관한 코드**로 담은 모양 — 저장(DB config·로컬 저장소)용.
  * 예: `{ grade: ['1', '2'], syllables: ['5+'], pos: ['noun'], wordType: ['sino'] }`
@@ -12,6 +47,8 @@ export declare const WORD_TYPE_CODE_VALUES: Record<string, string>;
 export declare function wordAttributeSectionOf(label: string): WordAttributeSectionCode | null;
 /** 한 섹션의 값(코드·어느 언어 라벨·옛 라벨) → 값 코드. 못 읽으면 null. */
 export declare function wordAttributeValueCodeOf(section: WordAttributeSectionCode, value: string): string | null;
+/** 코드 → 지금 언어의 라벨. `'none'` 도 사전 꼴로 나온다(숫자 틀 `{{n}}등급` 에 넣으면 `NaN등급` 이 된다). 모르는 코드는 그대로. */
+export declare function wordAttributeValueLabelOf(section: WordAttributeSectionCode, code: string, lng?: string): string;
 /**
  * @public filterSelected(라벨 열쇠·라벨 값, 어느 언어든 섞여 있어도) → **코드 모양**. 저장할 때 쓴다.
  * 속성 섹션(등급·음절 수·품사·어종)만 담고, 그 밖의 섹션(초성·선택·단어 입력 등)은 뺀다. 못 읽는 값은 버린다.

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

@@ -6,13 +6,62 @@
  * 영어 열쇠('Part of Speech')로는 한국어 값이 안 읽혀 **필터가 풀리거나**, 품사 값이 posMap 에 없어 **모든 단어가 떨어졌다**.
  * 여기서 섹션·값을 언어와 무관한 코드로 읽는다 — 코드, 지금 언어·ko·en 라벨, 옛 라벨('난이도 등급'·'체언(명사,수사)') 모두.
  *
- * 코드: 섹션 `grade`·`syllables`·`pos`·`wordType`, 값 등급 `'1'`~`'4'` · 음절 `'1'`~`'4'`·`'5+'` ·
+ * 코드: 섹션 `grade`·`syllables`·`pos`·`wordType`, 값 등급 `'1'`~`'4'`·`'none'` · 음절 `'1'`~`'4'`·`'5+'` ·
  * 품사 `noun`·`verb`·`modifier` · 어종 `native`·`sino`·`foreign`·`mixed`.
  * (useWordTrainingFilter 의 POS_CODES·toAttrCodes 와 같은 코드다.)
  */
 import i18n from '../i18n';
+/**
+ * **등급이 빈 단어를 가리키는 코드** — `'none'`((205), 사장님 지시 2026-10-12).
+ *
+ * ## 이것은 **값이 아니라 빔**이다
+ *
+ * `'1'`~`'4'` 는 단어의 `grade` 에 **그 글자가 들어 있다.** `'none'` 은 다르다 — 어느 단어의
+ * `grade` 도 `'none'` 이 아니고, 가리키는 것은 **`grade` 가 비어 있다**는 사실이다
+ * (`undefined` · `null` · `''`, 그리고 공백만 든 것도).
+ *
+ * 그래서 **맞추개가 이 코드만은 다른 길로 간다** — `word.grade === code` 가 아니라
+ * `isBlankGrade(word.grade)` 로 본다(`phonemePairSearch.matchesFilters`). 같은 꼴로 재면
+ * 한 단어도 안 걸리고, 그런데 **필터는 멀쩡히 켜져 보인다.**
+ *
+ * **숫자 길에도 안 걸린다** — 아래 `wordAttributeValueCodeOf` 가 등급을 숫자로도 읽는데
+ * (`'3등급'` → `'3'`), `'없음'` 은 숫자가 없어 `NaN` 이 되어 그 길에서 `null` 로 떨어진다.
+ * 그러니 **사전에 라벨이 있어야** 읽힌다. 사전에서 빠지면 조용히 안 읽힌다 —
+ * `test/gradeNoneOption.test.ts` 가 그 자리를 센다.
+ */
+export const GRADE_NONE = 'none';
+/** 등급이 비었나 — `'none'` 이 가리키는 그 **빔**을 한 자리에서 판정한다. 공백만 든 것도 빔이다. */
+export function isBlankGrade(grade) {
+    return grade == null || String(grade).trim() === '';
+}
+/** 등급 코드인가 — `'1'`~`'4'`·`'none'`. 저장된 값을 되읽을 때 **아닌 것은 버린다**(한때 `''` 가 저장됐다). */
+export function isGradeCode(v) {
+    return typeof v === 'string' && 등급값.includes(v);
+}
+/**
+ * **등급 코드 집합으로 단어 하나를 거른다 — 이 결정은 여기 하나다.**
+ *
+ * (205) 를 지을 때 맞추개를 `phonemePairSearch.matchesFilters` 하나로 알고 넷을 고쳤는데,
+ * **단어훈련 풀**(`wordTrainingPool`)이 같은 결정을 **두 줄로 따로** 갖고 있었다
+ * (`!w.grade || !gradeSet.has(w.grade)`). 그 둘은 빈 등급을 **늘 떨어뜨리므로** `없음` 을 골라도
+ * 0개였다(말귀_1 실측 2026-10-12: 매니저 단어표는 맞고 단어훈련 페이지는 틀렸다).
+ *
+ * **같은 결정이 세 자리에 적혀 있으면 하나는 안 따라온다.** 그래서 세 자리가 이 하나를 부른다.
+ * `codes` 가 비면 거르지 않는다(전체).
+ */
+export function matchesGradeCodes(codes, grade) {
+    if (!codes)
+        return true;
+    const set = codes instanceof Set ? codes : new Set(codes);
+    if (set.size === 0)
+        return true;
+    if (isBlankGrade(grade))
+        return set.has(GRADE_NONE);
+    return set.has(String(grade));
+}
 const 섹션들 = ['grade', 'syllables', 'pos', 'wordType'];
-const 등급값 = ['1', '2', '3', '4'];
+/** 등급 코드 — `'none'` 은 **등급이 빈 단어**다(값이 아니라 **빔**이다. GRADE_NONE 주석을 볼 것) */
+const 등급값 = ['1', '2', '3', '4', 'none'];
 const 음절값 = ['1', '2', '3', '4', '5+'];
 const 품사값 = ['noun', 'verb', 'modifier'];
 const 어종값 = ['native', 'sino', 'foreign', 'mixed'];
@@ -44,7 +93,11 @@ function 사전(lng) {
             wordType: t('wordSearch.filter.wordType', '유형'),
         },
         값: {
-            grade: Object.fromEntries(등급값.map((n) => [n, t('wordSearch.filter.grade', { n: Number(n), defaultValue: `${n}등급` })])),
+            grade: {
+                ...Object.fromEntries(등급값.filter(n => n !== GRADE_NONE).map((n) => [n, t('wordSearch.filter.grade', { n: Number(n), defaultValue: `${n}등급` })])),
+                /* **`없음` 은 숫자 틀을 안 쓴다** — `t('…grade', { n: Number('none') })` 은 `NaN등급` 이 된다 */
+                [GRADE_NONE]: t('wordSearch.filter.gradeNone', '없음'),
+            },
             syllables: {
                 ...Object.fromEntries(['1', '2', '3', '4'].map((n) => [n, t('wordSearch.filter.syllable', { n: Number(n), defaultValue: `${n}음절` })])),
                 '5+': t('wordSearch.filter.syllable5plus', '5음절 이상'),
@@ -105,6 +158,10 @@ export function wordAttributeValueCodeOf(section, value) {
     }
     return null;
 }
+/** 코드 → 지금 언어의 라벨. `'none'` 도 사전 꼴로 나온다(숫자 틀 `{{n}}등급` 에 넣으면 `NaN등급` 이 된다). 모르는 코드는 그대로. */
+export function wordAttributeValueLabelOf(section, code, lng = i18n.language) {
+    return 사전(lng).값[section][code] ?? code;
+}
 const 배열로 = (v) => (Array.isArray(v) ? v.filter((x) => typeof x === 'string') : typeof v === 'string' && v ? [v] : []);
 /**
  * @public filterSelected(라벨 열쇠·라벨 값, 어느 언어든 섞여 있어도) → **코드 모양**. 저장할 때 쓴다.

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

@@ -11,6 +11,7 @@
  */
 import { getImageExistenceStats, getImageOkWordSet } from './imageConfig';
 import { getWordPool } from './wordPool';
+import { matchesGradeCodes } from './wordAttributeFilterCodes';
 import { shuffle } from './array';
 import { getPairIndex } from './wordPairIndex';
 import { classifyPairDifficulty, wordContainsPhoneme, wordHasNoCoda, wordHasSyllableMatching, syllableLength, findTypedContrastWords, countPhonemeDiff, createDecompCache } from './koreanSyllable';
@@ -259,7 +260,7 @@ export function answerWordFilter(opts) {
         return null;
     const pron = opts.phonemeView === 'pron';
     return (w) => {
-        if (gradeSet && (!w.grade || !gradeSet.has(w.grade)))
+        if (!matchesGradeCodes(gradeSet, w.grade))
             return false;
         if (preds.length === 0)
             return true;
@@ -308,7 +309,7 @@ async function _buildUsablePool(opts) {
     let candidates = MVP.filter(w => {
         if (!w.w)
             return false;
-        if (gradeSet && (!w.grade || !gradeSet.has(w.grade)))
+        if (!matchesGradeCodes(gradeSet, w.grade))
             return false;
         if (useAllCandidates)
             return true;

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

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

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

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