@ihabdevteam/core 0.318.0 → 0.321.0

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

@@ -1,10 +1,16 @@
 /**
  * **지금 답을 고칠 수 있나** — 단계 상태 하나로 가른다.
  *
- * 이 결정이 여섯 자리에 `currentState !== 'active'` 로 적혀 있었다(`TrainingStepCard` ·
- * `TrainingStepConfirm`×2 · `TrainingStepConfirmWithText`×3 · `TrainingStepCardOrder` ·
- * `TrainingStepOrderList`). 그 막이는 **까닭이 있어 들어왔다** — 단추는 `!== 'disabled'` 로 열려
- * 있는데 기록은 `=== 'active'` 일 때만 나가서, **화면 선택은 바뀌는데 점수는 그대로**였다.
+ * 이 결정은 **네 조각**에 `currentState !== 'active'` 로 적혀 있었다(`TrainingStepCard` ·
+ * `TrainingStepConfirm` · `TrainingStepConfirmWithText` · `TrainingStepCardOrder`). 그 막이는
+ * **까닭이 있어 들어왔다** — 단추는 `!== 'disabled'` 로 열려 있는데 기록은 `=== 'active'` 일 때만
+ * 나가서, **화면 선택은 바뀌는데 점수는 그대로**였다.
+ *
+ * > **처음에 여섯으로 셌는데 틀렸다**(말귀 실측이 바로잡음 2026-10-12). `TrainingStepOrderList` 의
+ * > `!== 'active'` 는 **조작 막이가 아니라** `useEffect` 안의 **첫 보고 문**이다((103) 의 `initial`).
+ * > 글자가 같아서 같은 꼴로 세어졌다 — **글로 자리를 집을 때는 그 글이 하나인지 먼저 센다** 를
+ * > 내가 적어 두고 내 셈에서 밟았다. `OrderList` 의 `move` 는 **원래 안 막혀 있다**(말귀가 끝낸
+ * > 단계에서 또 옮겨 차례가 바뀌는 것을 확인했다) — 이 집안이 아니다.
  *
  * 그런데 그 막이가 **자기 첫 고름에 자기를 막는다**(말귀 요청 (201), QA 버그 보고 2026-10-12):
  * 고르면 `onDone` 이 나가고 단계가 넘어가 `currentState` 가 `'done'` 이 된다 — 그 뒤로는
@@ -22,10 +28,54 @@
  * 알려도 차례는 그대로다(`TrainingPagePopup.tsx`). 재지 않고 고쳤으면 **고친 답이 다음 단계를
  * 한 칸 더 밀** 수도 있었다.
  *
- * **지금 쓰는 곳은 `TrainingStepCard` 하나다** — QA 가 올린 그 자리다. 나머지 넷도 같은 꼴로
- * 보이지만(고르면 넘어가고 그 뒤 못 고친다) **화면에서 재 보지 않고 넷을 함께 바꾸지 않는다** —
- * 순서 매기기(`CardOrder`·`OrderList`)는 "고침" 의 뜻이 다를 수 있고, 여럿 고르기(`Confirm`)는
- * `확인` 단추가 이미 그 틈을 메운다. 셈은 적어 두었으니 그 넷은 **재고 나서** 옮긴다.
+ * **옮긴 곳 넷**(말귀가 **화면에서 다 재고** 나서 옮겼다 — 2026-10-12):
+ *
+ *     Card              변별훈련 › 같은소리고르기        QA 버그 보고
+ *     ConfirmWithText   오늘의 듣기 › 소음 하 문장 듣기   `disabled:false` 라 막혀 보이지도 않았다
+ *     Confirm(한 개)     오늘의 듣기 › 짧은 이야기        고르는 순간이 곧 답
+ *     CardOrder         단어훈련 › 듣고 순서대로 기억하기  **마지막 한 장만 못 푸는** 꼴
+ *
+ * **한때 안 옮긴 곳이 하나 있었다** — `Confirm` 의 **여럿 고르기** 갈래다. 말귀가 재현했다
+ * (2026-10-12): `오늘의 듣기 › 긴 이야기 듣기 › 페트라`, *"기억나는 단어를 나열해 보세요."* —
+ * 둘을 골라 `확인` 을 누른 뒤에는 **선택도 안 바뀌고 `확인` 도 다시 안 눌렸다.** 그 갈래가
+ * 켜지는 자리는 앱에 하나이고 **정답이 둘 이상인 문항에서만** 켠다
+ * (`multiSelect={_corrects.length > 1}`) — 같은 훈련 안에서도 문항마다 갈려서 찾기 어려웠다.
+ *
+ * **그 까닭이 세 번 바뀌었고, 네 번째에 갈래가 없어졌다:**
+ *
+ *     ① 못 쟀다              여럿 고르기를 쓰는 화면을 못 찾았다
+ *     ② 뜻을 기다린다        재현됐다 — 낸 뒤에도 고치게 할지는 **뜻**에 달렸다
+ *     ③ 내는 자리가 다르다   `확인` 이 곧 냄이다 → 그대로 둔다 (코드는 안 바뀜)
+ *     ④ 내는 자리가 하나다   **`확인` 이 걷혔다** → 여럿 고르기도 열린다
+ *
+ * ## 규칙은 하나다 — **내기 전까지는 고칠 수 있다**
+ *
+ * ③ 때는 *내는 자리*가 갈래마다 달라서 가름이 섰다(사장님 지시를 말귀가 전함, 2026-10-12 —
+ * *"확인, 결과보기 누르기 전까지는 수정할 수 있어야 해. UX 바꾸지 마."*):
+ *
+ *     여럿 고르기    내는 자리 = **`확인`**      → 낸 뒤 잠긴다
+ *     그 밖 모두     내는 자리 = **`결과보기`**   → 그 전까지 고칠 수 있다
+ *
+ * 그런데 같은 날 사장님이 **그 `확인` 단추를 걷으라** 하셨다((206) — *"확인버튼 제거 하라고
+ * 했어"* · *"UX 바꾸지 마"*, 뒤 말은 **고치는 방식**을 바꾸지 말라는 뜻이다). 내는 자리가
+ * `결과보기` 하나가 되었으니 **가를 까닭도 같이 없어졌다.** 이제 **다섯 자리가 이 하나를
+ * 쓴다** — `Card` · `ConfirmWithText` · `Confirm`(두 갈래 다) · `CardOrder`.
+ *
+ * `확인` 을 걷을 때 `multiSelect && currentState !== 'active'` 막이를 **함께** 열었다.
+ * 하나만 하면 **반대쪽 어긋남**이 난다 — 단추만 걷으면 고름이 **첫 한 번에 얼어붙어**,
+ * 지키라 하신 *"수정할 수 있어야 해"* 를 **단추를 걷어서 어기는** 꼴이 된다.
+ *
+ * `canAnswerStep` 이 *"닿지 않은 단계만 막는다"* 로 적힌 것보다 **내는 자리**가 까닭이다 —
+ * 다음에 갈래가 늘면 *"이 갈래는 무엇으로 내는가"* 를 먼저 묻는다.
+ *
+ * > **까닭이 바뀐 자취를 지우지 않는다.** ③에서 ④로 간 것은 **재서가 아니라 뜻이 바뀌어서**다.
+ * > 그 둘을 섞지 않는다 — 다시 볼 때 묻는 물음이 다르다(실측이 뒤집은 가름은 *"또 재 보자"*,
+ * > 결정이 뒤집은 가름은 *"아직 그 뜻인가"*).
+ * >
+ * > (206) 은 하루에 **청함 → 철회 → 되살림**으로 세 번 흔들렸다. 두 번째 때 *"지시의
+ * > 뒷문장이 까닭인지 지시인지"* 가 갈렸고, 세 번째는 *"UX 바꾸지 마"* 가 **단추**를 말하는지
+ * > **고치는 방식**을 말하는지가 갈렸다. 그 세 번 동안 전해 받은 말로 짓지 않은 덕에
+ * > **되돌릴 것이 없었다.**
  */
 export type 단계상태 = 'disabled' | 'done' | 'active';
 /** 답을 고를 수 있나 — 닿지 않은 단계(`disabled`)만 막는다. @public */

package/dist/packages/core/src/components/Word/WordTableBlock.css

@@ -7,6 +7,19 @@
     background: transparent;
 }
 
+/* ── 표를 손보는 단추들 (표 바로 아래) — (210) ───────────
+   간격은 Section 의 flex gap 이 맡는다(`__meta` 와 같은 규칙 — 제 margin 을 더하면 이중 여백).
+   아래 `__actions` 와 같은 꼴로 선다: 모자라면 아랫줄로, 폰에서는 두 칸 격자. */
+.word-table-block__table-actions {
+    display: flex;
+    gap: var(--spacing-xs);
+    flex-wrap: wrap;
+    /* **가운데**((211), 사장님 지시 *"가운데 배치"*). 종이(표)는 가운데 서는데 그 아래 줄만
+       왼쪽 끝에 붙어 한 덩이로 안 읽혔다(말귀 실측 1403 폭: 줄 폭 1272, 단추 둘이 왼끝).
+       아래 액션 줄은 `space-between` 이라 그대로 둔다 — 거기는 양끝에 갈라 세우는 줄이다. */
+    justify-content: center;
+}
+
 /* ── 액션 버튼 ─────────────────────────────────────────── */
 .word-table-block__actions {
     display: flex;
@@ -53,6 +66,18 @@
     min-width: 0;
     width: 100%;
   }
+  /* (210) 표 밑 줄도 같은 꼴 — **@media 를 따로 열지 않는다.** 처음 위에 따로 열었다가
+     `wordTableBlockActionsLeftExtra` 가 울었다: 그 못은 `css.slice(0, indexOf('@media'))` 로
+     넓은 쪽을 자르는데, 앞에 `@media` 가 하나 더 생기면 **자르는 자리가 앞당겨져** 넓은 쪽
+     규칙을 못 찾는다. 못이 글의 차례에 기대고 있었고, 내가 그 차례를 바꿨다. */
+  .word-table-block__table-actions {
+    display: grid;
+    grid-template-columns: repeat(2, 1fr);
+  }
+  .word-table-block__table-actions .button {
+    min-width: 0;
+    width: 100%;
+  }
 }
 
 /* ── 팝업 내 미리보기 ───────────────────────────────────── */

package/dist/packages/core/src/components/Word/WordTableBlock.js

@@ -334,7 +334,7 @@ export default function WordTableBlock({ title, titleIcon, disc, filterTitle, fi
                                (위 `onReorder` 와 같은 셈이다. 쪽이 몇으로 나뉘었는지는 부르는 쪽 일이 아니다). */
                             renderCellAction: renderCellAction && ((n, item) => renderCellAction(n + i * itemsPerPage, item)), brand: 띠, code: code, contentRef: el => { pageRefs.current[i] = el; }, pageNumber: { current: i + 1, total: pages.length }, pageNumberPosition: pageNumberPosition }, i))) })) : (_jsx(WordTable, { orientation: orientation, contentTypes: contentTypes, cutLine: cutLine, showOutline: showOutline, showDivLine: showDivLine, count: count, items: isEditable ? undefined : (items ?? []), editCells: isEditable ? visibleCells : undefined, activeCell: activeCell, onActivateCell: (isEditable || onAddItem) ? setActiveCell : undefined, onRemoveCell: isEditable ? handleRemove : undefined, onRemoveItem: !isEditable ? onRemoveItem : undefined, onReorder: !isEditable ? onReorder : undefined, 
                         /* 편집 모드에는 얹을 항목이 없다 — 칸을 손으로 채우는 꼴이다 */
-                        renderCellAction: !isEditable ? renderCellAction : undefined, brand: 띠, code: code, showFillerAdd: !!onAddItem, contentRef: contentRef })), inlineNameFields && !hideControls && (_jsxs(Panel, { size: "medium", labelWidth: 64, useBorder: false, useRowBorder: false, className: "word-table-block__meta", children: [_jsx(PanelRow, { variant: "custom", label: t('wordTable.save.nameLabel', '이름'), required: true, align: "vertical", useFullWidth: true, children: _jsx(TextField, { required: true, value: nameValue ?? '', onChange: onNameChange, placeholder: namePlaceholder ? namePlaceholder + t('wordTable.save.autoFillHint', ' (Tab 또는 space 입력시 자동 입력)') : t('wordTable.save.placeholder', '이 단어표에 대한 제목을 입력하세요.'), 
+                        renderCellAction: !isEditable ? renderCellAction : undefined, brand: 띠, code: code, showFillerAdd: !!onAddItem, contentRef: contentRef })), !hideControls && !saveOnly && (onReset || actionsLeftExtra != null) && (_jsxs("div", { className: "word-table-block__table-actions", children: [onReset && (_jsx(Button, { htmlType: "button", size: 48, type: "bar", label: resolvedResetLabel, onClick: onReset })), actionsLeftExtra] })), inlineNameFields && !hideControls && (_jsxs(Panel, { size: "medium", labelWidth: 64, useBorder: false, useRowBorder: false, className: "word-table-block__meta", children: [_jsx(PanelRow, { variant: "custom", label: t('wordTable.save.nameLabel', '이름'), required: true, align: "vertical", useFullWidth: true, children: _jsx(TextField, { required: true, value: nameValue ?? '', onChange: onNameChange, placeholder: namePlaceholder ? namePlaceholder + t('wordTable.save.autoFillHint', ' (Tab 또는 space 입력시 자동 입력)') : t('wordTable.save.placeholder', '이 단어표에 대한 제목을 입력하세요.'), 
                                     /* PanelRow의 라벨은 시각적으로만 붙어 있고 입력과 연결돼 있지 않아, 낭독기에는
                                        이름 없는 입력으로 읽혔다. placeholder는 자동완성 안내문("Tab 또는 space…")이
                                        섞여 있어 이름으로 부적절하므로 같은 라벨 문구를 넘긴다. */
@@ -349,5 +349,5 @@ export default function WordTableBlock({ title, titleIcon, disc, filterTitle, fi
                                             e.preventDefault();
                                             onDescriptionChange?.(descriptionPlaceholder ?? '');
                                         }
-                                    } }) })] }))] }), !hideControls && (_jsxs("div", { className: "word-table-block__actions", children: [_jsxs("div", { className: "word-table-block__actions-left", children: [!saveOnly && onReset && (_jsx(Button, { htmlType: "button", size: 40, type: "bar", label: resolvedResetLabel, onClick: onReset })), !saveOnly && actionsLeftExtra, !saveOnly && onLoad && (_jsx(Button, { htmlType: "button", size: 40, type: "bar", label: t('wordTable.load', '불러오기'), onClick: onLoad })), !saveOnly && _jsx(Button, { htmlType: "button", size: 40, type: "bar", label: t('wordTable.openNewWindow', '새 창으로 보기'), onClick: handleOpenNewWindow })] }), _jsxs("div", { className: "word-table-block__actions-right", children: [onCancel && _jsx(Button, { htmlType: "button", size: "56", type: "bar", label: t('common.cancel', '취소'), onClick: onCancel }), !saveOnly && _jsx(Button, { htmlType: "button", size: "56", type: "bar", label: t('wordTable.print', '인쇄하기'), onClick: handlePrint }), secondarySaveButtonLabel && (_jsx(Button, { htmlType: "button", size: "56", type: "bar", label: secondarySaveButtonLabel, onClick: () => inlineNameFields ? openSaveAsPopup() : handleSave(true), disabled: noItems, onDisabledClick: () => { showWarning(t('wordTable.emptyItems', '단어를 1개 이상 추가해주세요.')); } })), _jsx(Button, { htmlType: "button", size: "56", type: "bar", variant: "main", label: saveButtonLabel ?? t('wordTable.saveButton', '저장하기'), onClick: () => handleSave(false), disabled: mainSaveDisabled, onDisabledClick: handleMainDisabledClick })] })] })), _jsx(Toast, { message: toastMessage, type: toastType, onClose: clearToast })] }));
+                                    } }) })] }))] }), !hideControls && (_jsxs("div", { className: "word-table-block__actions", children: [_jsxs("div", { className: "word-table-block__actions-left", children: [!saveOnly && onLoad && (_jsx(Button, { htmlType: "button", size: 40, type: "bar", label: t('wordTable.load', '불러오기'), onClick: onLoad })), !saveOnly && _jsx(Button, { htmlType: "button", size: 40, type: "bar", label: t('wordTable.openNewWindow', '새 창으로 보기'), onClick: handleOpenNewWindow })] }), _jsxs("div", { className: "word-table-block__actions-right", children: [onCancel && _jsx(Button, { htmlType: "button", size: "56", type: "bar", label: t('common.cancel', '취소'), onClick: onCancel }), !saveOnly && _jsx(Button, { htmlType: "button", size: "56", type: "bar", label: t('wordTable.print', '인쇄하기'), onClick: handlePrint }), secondarySaveButtonLabel && (_jsx(Button, { htmlType: "button", size: "56", type: "bar", label: secondarySaveButtonLabel, onClick: () => inlineNameFields ? openSaveAsPopup() : handleSave(true), disabled: noItems, onDisabledClick: () => { showWarning(t('wordTable.emptyItems', '단어를 1개 이상 추가해주세요.')); } })), _jsx(Button, { htmlType: "button", size: "56", type: "bar", variant: "main", label: saveButtonLabel ?? t('wordTable.saveButton', '저장하기'), onClick: () => handleSave(false), disabled: mainSaveDisabled, onDisabledClick: handleMainDisabledClick })] })] })), _jsx(Toast, { message: toastMessage, type: toastType, onClose: clearToast })] }));
 }

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

@@ -24,7 +24,16 @@ export interface WordAttributeFilterKeys {
  * 이 훅을 함께 호출해 라벨 문구와 posMap/typeMap(품사·어종 판정 규칙)을 어긋나지 않게 공유한다.
  */
 export declare function useWordAttributeFilterKeys(): WordAttributeFilterKeys;
-/** @public 등급(1~4등급) FilterPanelSection — 세 화면 공용. labelAction/allLabel은 호출부가 자신의 i18n으로 구성해 넘긴다. */
+/**
+ * @public 등급 FilterPanelSection — 세 화면 공용. labelAction/allLabel은 호출부가 자신의 i18n으로 구성해 넘긴다.
+ *
+ * **맨 끝에 `없음` 이 선다**((205), 2026-10-12) — 등급이 비어 있는 단어도 고를 수 있어야 한다.
+ * 맨 끝인 까닭은 **1~4 가 센 순서**이고 `없음` 은 그 줄 밖이기 때문이다(앞에 두면 `1등급` 앞에
+ * 숫자 아닌 것이 끼어 읽는 차례가 흔들린다).
+ *
+ * 이 줄의 글자는 `wordAttributeFilterCodes` 의 사전과 **같아야** 한다 — 거기서 코드로 못 읽으면
+ * 필터는 켜져 보이는데 한 단어도 안 걸린다. `test/gradeNoneOption.test.ts` 가 둘을 맞춰 센다.
+ */
 export declare function buildGradeSection(t: TFunction, keys: WordAttributeFilterKeys, opts?: {
     allLabel?: string;
     labelAction?: ReactNode;

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

@@ -31,11 +31,20 @@ export function useWordAttributeFilterKeys() {
         },
     }), [t]);
 }
-/** @public 등급(1~4등급) FilterPanelSection — 세 화면 공용. labelAction/allLabel은 호출부가 자신의 i18n으로 구성해 넘긴다. */
+/**
+ * @public 등급 FilterPanelSection — 세 화면 공용. labelAction/allLabel은 호출부가 자신의 i18n으로 구성해 넘긴다.
+ *
+ * **맨 끝에 `없음` 이 선다**((205), 2026-10-12) — 등급이 비어 있는 단어도 고를 수 있어야 한다.
+ * 맨 끝인 까닭은 **1~4 가 센 순서**이고 `없음` 은 그 줄 밖이기 때문이다(앞에 두면 `1등급` 앞에
+ * 숫자 아닌 것이 끼어 읽는 차례가 흔들린다).
+ *
+ * 이 줄의 글자는 `wordAttributeFilterCodes` 의 사전과 **같아야** 한다 — 거기서 코드로 못 읽으면
+ * 필터는 켜져 보이는데 한 단어도 안 걸린다. `test/gradeNoneOption.test.ts` 가 둘을 맞춰 센다.
+ */
 export function buildGradeSection(t, keys, opts) {
     return {
         label: keys.difficulty,
-        items: [1, 2, 3, 4].map(n => t('wordSearch.filter.grade', { n })),
+        items: [...[1, 2, 3, 4].map(n => t('wordSearch.filter.grade', { n })), t('wordSearch.filter.gradeNone', '없음')],
         multiple: true,
         allOption: true,
         allLabel: opts?.allLabel,

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

@@ -1,3 +1,4 @@
+import type { TFunction } from 'i18next';
 import { type FilterPanelSection } from '../types/filterPanel';
 import { type WordComposition } from './wordTrainingFilterModel';
 export { valueToJamos, NO_CODA, SYLLABLE_MIN, syllableToFilter, charToPronValue, pronToCharValue, convertComposition, EMPTY_COMPOSITION, } from './wordTrainingFilterModel';
@@ -52,11 +53,12 @@ export interface WordTrainingFilterCaps {
     requireCoda?: boolean;
 }
 /**
- * 단어 훈련 그룹별 필터 상태.
- * @param groupKey  그룹 식별자 (localStorage 키 및 상태 격리에 사용)
- * @param caps      그룹이 노출할 설정 (난이도/단어구성). 제외 필터는 항상 노출.
- * @public
+ * 등급 고르개의 설명 줄들 — 지금 언어로. 사전에 배열이 없으면 한국어 원문.
+ *
+ * **공개 API 가 아니다**(대응표에 `internal`) — 코어 안에서만 쓰고, 내보내는 것은 못이 읽기 때문이다.
+ * 앱은 제 열쇠(`wordSearch.filter.gradeInfo`)와 제 받는 함수를 따로 갖는다.
  */
+export declare function 등급설명(t: TFunction): string[];
 export declare function useWordTrainingFilter(groupKey: string, caps: WordTrainingFilterCaps, opts?: {
     resetOnMount?: boolean;
     resetKey?: string;

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

@@ -6,6 +6,9 @@ import { FILTER_ALL_VALUE } from '../types/filterPanel';
 import { useWindowEvent } from './useWindowEvent';
 import { useWordAttributeFilterKeys, buildGradeSection, buildPartOfSpeechSection, buildWordTypeSection } from './useWordAttributeFilter';
 import { matchesFilters } from '../utils/phonemePairSearch';
+import { wordAttributeValueCodeOf, wordAttributeValueLabelOf, isGradeCode } from '../utils/wordAttributeFilterCodes';
+/** 저장된 등급을 되읽을 때 코드 아닌 것은 버린다 — 0.320.0 작업본이 잠깐 `['']` 를 저장했다 */
+const 등급코드만 = (v) => (Array.isArray(v) ? v.filter(isGradeCode) : []);
 import { hasSel } from '../utils/wordContrast';
 import { phoneticLabel } from '../utils/phonemeGroups';
 /* 글자↔발음 변환과 음절 상수는 wordTrainingFilterModel.ts 로 옮겼다(React 없는 순수 계층).
@@ -74,6 +77,24 @@ function readComposition(saved) {
  * @param caps      그룹이 노출할 설정 (난이도/단어구성). 제외 필터는 항상 노출.
  * @public
  */
+/** 사전이 배열을 안 주면 한국어 원문으로 물러선다 — 빈 줄을 띄우지 않는다((205)) */
+const 등급설명기본 = [
+    '1등급 : 학령전기에 습득하여 평생에 걸쳐 일상 언어생활을 하는 데 사용되는 어휘',
+    '2등급 : 초등학교 1-2학년 난이도 어휘',
+    '3등급 : 초등학교 3-4학년 난이도 어휘',
+    '4등급 : 초등학교 5-6학년 난이도 어휘',
+    '등급없음 : 국립국어원 표준 어휘 외 고빈도 생활 어휘, 신조어 및 외래어',
+];
+/**
+ * 등급 고르개의 설명 줄들 — 지금 언어로. 사전에 배열이 없으면 한국어 원문.
+ *
+ * **공개 API 가 아니다**(대응표에 `internal`) — 코어 안에서만 쓰고, 내보내는 것은 못이 읽기 때문이다.
+ * 앱은 제 열쇠(`wordSearch.filter.gradeInfo`)와 제 받는 함수를 따로 갖는다.
+ */
+export function 등급설명(t) {
+    const v = t('wordPairs.filter.difficultyInfo', { returnObjects: true, defaultValue: 등급설명기본 });
+    return Array.isArray(v) && v.length > 0 && v.every(x => typeof x === 'string') ? v : 등급설명기본;
+}
 export function useWordTrainingFilter(groupKey, caps, opts) {
     const { t, i18n } = useTranslation();
     // resetOnMount(단어훈련 만들기 등): 진입 시 항상 기본값에서 시작하도록 저장값을 불러오지 않는다.
@@ -122,7 +143,7 @@ export function useWordTrainingFilter(groupKey, caps, opts) {
     // 음소 구조 같은 단어만(초성 ㅇ 유무·받침 유무 대립 제외) — 기본 true (reset 시 OFF)
     const [sameStructureOnly, setSameStructureOnly] = useState(opts?.resetOnMount ? false : (saved?.sameStructureOnly ?? true));
     // 난이도 등급('1'~'4') 필터 — 배열(다중 선택), 빈 배열은 전체(무제약)
-    const [gradeFilter, setGradeFilter] = useState(Array.isArray(saved?.gradeFilter) ? saved.gradeFilter : []);
+    const [gradeFilter, setGradeFilter] = useState(등급코드만(saved?.gradeFilter));
     // 품사/어종 필터 — 단어표·대립쌍표와 동일 라벨 배열(다중 선택). caps로 노출 여부 결정(기본 미노출).
     const 라벨언어들 = Array.from(new Set([i18n.language, 'ko', 'en'].filter(Boolean)));
     const labelOf = (lng, key) => i18n.getFixedT(lng)(key);
@@ -190,7 +211,7 @@ export function useWordTrainingFilter(groupKey, caps, opts) {
             setSameStructureOnly(s?.sameStructureOnly ?? true);
             // 마운트 때와 같은 규칙 — 여기서만 'direct' 를 'char' 로 떨구고 있었다
             setPhonemeView(readPhonemeView(s));
-            setGradeFilter(Array.isArray(s?.gradeFilter) ? s.gradeFilter : []);
+            setGradeFilter(등급코드만(s?.gradeFilter));
             setPosCodes(posCodesOf(s?.posFilter));
             setTypeCodes(typeCodesOf(s?.wordTypeFilter));
         }
@@ -418,8 +439,18 @@ export function useWordTrainingFilter(groupKey, caps, opts) {
                    *"국립국어원의 기초 어휘 등급이 결과에 반영됩니다"* 한 줄이라, 1등급이 쉬운 쪽인지
                    어려운 쪽인지도 알 수 없었다. 앱 두 화면에는 이미 이 다섯 줄이 들어가 있어
                    (앱 열쇠 `wordSearch.filter.gradeInfo`), 이 자리만 한 줄로 남아 **세 화면이 다른 말**을
-                   하고 있었다 — 글자까지 같은 것을 쓴다. */
-                labelInfo: infoAction([1, 2, 3, 4, 5].map(n => t(`wordPairs.filter.difficultyInfo${n}`))),
+                   하고 있었다 — 글자까지 같은 것을 쓴다.
+        
+                   **한 열쇠에 배열로 둔다**(말귀 요청, 2026-10-12). 처음엔 `difficultyInfo1`~`5` 로 나눴는데
+                   그러면 ① 말귀 못(`deadI18nKeys`)이 **산 열쇠를 죽은 것으로** 센다 — 그 못은 `a.b.${x}` 처럼
+                   **점 자리에서 잘린 앞머리**를 쓰는 것으로 세는데, 이것은 *마지막 마디 뒤에 숫자를 붙여*
+                   안 걸린다. ② **줄 수가 다섯에 못 박힌다** — 배열이면 언어마다 줄 수가 달라도 된다.
+                   ③ 앱이 같은 꼴(`returnObjects`)을 이미 쓴다.
+        
+                   사전이 배열을 안 주면(옛 사전을 덮어쓴 소비자 등) **한국어 원문으로 물러선다** — 빈 줄을
+                   띄우지 않는다. 재 보고 적는다: `returnObjects` 는 배열을 그대로 주고 `defaultValue` 도
+                   배열로 물러선다(i18next 26.4.1). */
+                labelInfo: infoAction(등급설명(t)),
             }),
             label: LABELS.gradeLabel,
         });
@@ -479,7 +510,7 @@ export function useWordTrainingFilter(groupKey, caps, opts) {
             ...(sameStructureOnly ? [LABELS.sameStructure] : []),
         ],
         // 난이도 등급 — 선택된 등급들의 라벨 배열('1등급' 등)
-        [LABELS.gradeLabel]: gradeFilter.map(g => t('wordSearch.filter.grade', { n: Number(g), defaultValue: '{{n}}등급' })),
+        [LABELS.gradeLabel]: gradeFilter.map(g => wordAttributeValueLabelOf('grade', g)),
         // 품사/어종 — 단어표·대립쌍표와 동일하게 선택된 라벨 배열 그대로 노출
         ...(caps.partOfSpeech ? { [attrKeys.partOfSpeech]: posFilter } : {}),
         ...(caps.wordType ? { [attrKeys.wordType]: wordTypeFilter } : {}),
@@ -509,7 +540,11 @@ export function useWordTrainingFilter(groupKey, caps, opts) {
                 setGradeFilter([]);
                 return;
             }
-            const n = value.replace(/\D/g, '');
+            /* 라벨 → 코드는 사전으로 — 숫자만 남기면 `없음` 이 `''` 가 되어 저장되고 칩은 영영 안 켜졌다
+               (말귀_1 실측 2026-10-12). 못 읽는 라벨은 무시한다. */
+            const n = wordAttributeValueCodeOf('grade', value);
+            if (n == null)
+                return;
             setGradeFilter(prev => prev.includes(n) ? prev.filter(g => g !== n) : [...prev, n]);
         }
         else if (sectionLabel === attrKeys.partOfSpeech) {
@@ -584,7 +619,7 @@ export function useWordTrainingFilter(groupKey, caps, opts) {
         setExcludeNoImage(s.excludeNoImage);
         setSameStructureOnly(s.sameStructureOnly ?? true);
         setPhonemeView(s.phonemeView);
-        setGradeFilter(Array.isArray(s.gradeFilter) ? s.gradeFilter : []);
+        setGradeFilter(등급코드만(s.gradeFilter));
         if (Array.isArray(s.posFilter))
             setPosCodes(posCodesOf(s.posFilter));
         if (Array.isArray(s.wordTypeFilter))

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

@@ -901,6 +901,7 @@
             "positionTail": "End",
             "difficulty": "Grade",
             "grade": "Grade {{n}}",
+            "gradeNone": "None",
             "syllables": "Syllables",
             "syllable": "{{n}} Syll.",
             "syllable5plus": "5+ Syllables",
@@ -1145,11 +1146,13 @@
             ],
             "orderAny": "Any",
             "orderMatch": "Match",
-            "difficultyInfo1": "Level 1 — everyday vocabulary acquired before school age and used for life",
-            "difficultyInfo2": "Level 2 — difficulty of grades 1–2",
-            "difficultyInfo3": "Level 3 — difficulty of grades 3–4",
-            "difficultyInfo4": "Level 4 — difficulty of grades 5–6",
-            "difficultyInfo5": "No level — frequent everyday words outside the national standard list, plus coinages and loanwords",
+            "difficultyInfo": [
+                "Level 1 — everyday vocabulary acquired before school age and used for life",
+                "Level 2 — difficulty of grades 1–2",
+                "Level 3 — difficulty of grades 3–4",
+                "Level 4 — difficulty of grades 5–6",
+                "No level — frequent everyday words outside the national standard list, plus coinages and loanwords"
+            ],
             "selectLabel": "Select",
             "onlyHasImage": "Only words with images",
             "onlySameStructure": "Only same phoneme structure"

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/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/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` 가 아니라
+ * `빈등급인가(word.grade)` 로 본다(`phonemePairSearch.matchesFilters`). 같은 꼴로 재면
+ * 한 단어도 안 걸리고, 그런데 **필터는 멀쩡히 켜져 보인다.**
+ *
+ * **숫자 길에도 안 걸린다** — 아래 `wordAttributeValueCodeOf` 가 등급을 숫자로도 읽는데
+ * (`'3등급'` → `'3'`), `'없음'` 은 숫자가 없어 `NaN` 이 되어 그 길에서 `null` 로 떨어진다.
+ * 그러니 **사전에 라벨이 있어야** 읽힌다. 사전에서 빠지면 조용히 안 읽힌다 —
+ * `test/gradeNoneOption.test.ts` 가 그 자리를 센다.
+ */
+export declare const GRADE_NONE = "none";
+/** 등급이 비었나 — `'none'` 이 가리키는 그 **빔**을 한 자리에서 판정한다. 공백만 든 것도 빔이다. */
+export declare function 빈등급인가(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` 가 아니라
+ * `빈등급인가(word.grade)` 로 본다(`phonemePairSearch.matchesFilters`). 같은 꼴로 재면
+ * 한 단어도 안 걸리고, 그런데 **필터는 멀쩡히 켜져 보인다.**
+ *
+ * **숫자 길에도 안 걸린다** — 아래 `wordAttributeValueCodeOf` 가 등급을 숫자로도 읽는데
+ * (`'3등급'` → `'3'`), `'없음'` 은 숫자가 없어 `NaN` 이 되어 그 길에서 `null` 로 떨어진다.
+ * 그러니 **사전에 라벨이 있어야** 읽힌다. 사전에서 빠지면 조용히 안 읽힌다 —
+ * `test/gradeNoneOption.test.ts` 가 그 자리를 센다.
+ */
+export const GRADE_NONE = 'none';
+/** 등급이 비었나 — `'none'` 이 가리키는 그 **빔**을 한 자리에서 판정한다. 공백만 든 것도 빔이다. */
+export function 빈등급인가(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 (빈등급인가(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.321.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.321.0';