@ihabdevteam/core 0.330.0 → 0.332.0

package/dist/ihabdevteam-core.d.ts

@@ -1678,7 +1678,7 @@ export declare function copyText(text: string): Promise<boolean>;
  *
  * 값은 손으로 적고 `test/coreVersion.test.ts` 가 package.json 과 어긋나면 운다.
  */
-export declare const CORE_VERSION = "0.330.0";
+export declare const CORE_VERSION = "0.332.0";
 
 /** @public */
 declare const coreDefault: Record<string, unknown>;
@@ -3916,6 +3916,12 @@ export declare type MonthBarData = {
     daily: BarData[];
 };
 
+/** @public */
+export declare const monthKeyOf: (year: number, month1: number) => string;
+
+/** @public */
+export declare const monthKeyOfDate: (d: Date) => string;
+
 /** @public */
 export declare type NavItem = {
     key?: string;
@@ -4497,6 +4503,18 @@ declare type PanelSize = 'small' | 'medium' | 'large';
  */
 export declare function parseLocalYmd(ymd: string): Date;
 
+/**
+ * `"2026-10"` → `{ year: 2026, month1: 10 }`. 꼴이 아니면 `null`.
+ *
+ * **두 자리만 받는다.** `"2026-9"` 를 받아 주면 짓는 쪽과 뜯는 쪽이 어긋나도 조용하고,
+ * 그 어긋남이 바로 열쇠가 안 맞는 결함이다.
+ */
+/** @public */
+export declare function parseMonthKey(key: string): {
+    year: number;
+    month1: number;
+} | null;
+
 /**
  * 드롭다운 값을 정렬 상태로 되돌린다.
  *
@@ -10589,6 +10607,9 @@ export declare interface WeakItem {
  */
 export declare function weakItems(records: readonly ScoreRecord[]): WeakItem[];
 
+/** @public */
+export declare const weekValueOf: (monthKey: string, week: number) => string;
+
 /** text 뒤에 문맥에 맞는 을/를을 붙여 반환한다. */
 export declare function withEulReul(text: string): string;
 

package/dist/packages/core/src/components/Popup/TrainingResultPopup.css

@@ -122,16 +122,20 @@
 .result-table__row:hover { background: var(--color-deepWhite); }
 .result-table__row:last-child { border-bottom: 0; }
 
+/* **가운데로 맞춘다 — `baseline` 이 아니다**((307)①, 2026-10-14 사장님 지적).
+   `baseline` 이면 `display:flex` 인 단추의 **제 안 아이콘 바닥**이 기준선이 된다. 그래서
+   32px 단추가 줄 높이를 정하고 26px 낱말이 **3px 위로** 밀렸다(말귀_1 실측:
+   줄 mid 664 · 낱말 mid 661). 단추에만 `align-self: center` 를 걸던 앞 고침은 **안 움직였다**
+   — 단추가 이미 줄을 꽉 채우니 제 안에서 가운데로 가도 그대로다. 줄을 맞춰야 한다.
+   단추 없는 줄은 26px 하나뿐이라 달라지는 것이 없다. */
 .trp-row__problem {
   display: flex;
-  align-items: baseline;
+  align-items: center;
   gap: 10px;
 }
-/* **다시 듣기** — 문제 글 옆((303), 2026-10-14). 글이 길면 줄바꿈으로 밀리므로 안 줄인다.
-   `align-self` 로 올려 붙인다 — 줄이 `baseline` 이라 그대로 두면 단추가 글자 밑줄에 걸린다. */
+/* **다시 듣기** — 문제 글 옆((303), 2026-10-14). 글이 길면 줄바꿈으로 밀리므로 안 줄인다. */
 .trp-row__replay {
   flex-shrink: 0;
-  align-self: center;
 }
 .trp-row__no {
   flex-shrink: 0;

package/dist/packages/core/src/components/Popup/TrainingResultPopup.js

@@ -5,6 +5,8 @@ import { useTranslation } from 'react-i18next';
 import Button from '../Button';
 import Badge from '../Badge';
 import { playOneShot } from '../Training/oneShotSound';
+import { questionSoundCandidates, canSpeak, playableUrl } from '../Training/questionSoundRoute';
+import { speak, stopSpeaking } from '../../utils/speak';
 import Popup from './Popup';
 import "./TrainingResultPopup.css";
 function pickFirstString(...vals) {
@@ -46,10 +48,7 @@ function resolveProblem(it) {
  * **못 찾으면 `null` 이고, 그러면 단추를 안 그린다** — 안 넘기는 쪽은 지금과 똑같다.
  */
 function resolveSound(it) {
-    const v = pickFirstString(it?.questionSound, it?.soundSrc, it?.audioSrc, it?.sound, it?.audio, it?.src);
-    /* 글자이기만 하면 되는 게 아니다 — `pickFirstString` 은 아무 글이나 돌려준다.
-       소리 자리에 제목이 들어 있는 꼴을 틀려고 하면 조용히 아무 일도 안 난다. */
-    return v && /^(https?:|blob:|data:audio|\/|\.\/)/.test(v) ? v : null;
+    return playableUrl(pickFirstString(it?.questionSound, it?.soundSrc, it?.audioSrc, it?.sound, it?.audio, it?.src));
 }
 function resolveDecision(it) {
     if (!it)
@@ -112,11 +111,66 @@ export default function TrainingResultPopup(props) {
         setPlayingRow(null);
     }, []);
     useEffect(() => stopPlaying, [stopPlaying]);
-    const replay = useCallback((i, url) => {
+    /*
+     * **코어가 그 문항을 읽을 때 쓴 길을 그대로 탄다**((307)③, 2026-10-14).
+     *
+     * 0.328.0 은 부르는 쪽이 넘긴 주소 하나만 봤다. 그래서 **정식 음원이 없는 낱말에는 단추가
+     * 아예 안 섰다** — 말귀_1 실측으로 다섯 줄 중 둘이 그랬다. 그런데 **훈련 중에는 다섯 다
+     * 들렸다**: 코어가 리졸버와 합성으로 읽어 주고 있었다. 같은 길을 여기서도 탄다
+     * (차례는 `questionSoundRoute` 한 자리가 안다).
+     *
+     * **임자 셈으로 "못 틀었다" 와 "사람이 멈췄다" 를 가른다.** `done` 은 둘 다 `false` 다 —
+     * 그것만 보고 다음 주소로 넘어가면, 멈춤 단추를 누른 사람이 **다음 소리를 듣는다.**
+     * 그래서 누를 때마다 표를 하나 만들고, 표가 바뀌었으면 길을 끊는다(카드가 쓰는 꼴과 같다).
+     */
+    const turnRef = useRef(0);
+    const replay = useCallback((i, text, rawUrl) => {
         stopPlaying();
-        const s = playOneShot(url, () => { playingRef.current = null; setPlayingRow(null); });
-        playingRef.current = s.stop;
+        const turn = ++turnRef.current;
+        const mine = () => turnRef.current === turn;
         setPlayingRow(i);
+        /* 이 줄이 아직 제 차례인 동안만 상태를 되돌린다 — 늦게 온 끝이 남의 줄을 끈다 */
+        playingRef.current = () => { turnRef.current++; stopSpeaking(); };
+        /** 한 주소를 틀고 **끝까지 들었나**를 돌려준다. 멈추개도 그 소리로 바꿔 둔다. */
+        const tryUrl = (url) => {
+            const s = playOneShot(url, (played) => { if (played && mine()) {
+                playingRef.current = null;
+                setPlayingRow(null);
+            } });
+            playingRef.current = () => { turnRef.current++; s.stop(); stopSpeaking(); };
+            return s.done;
+        };
+        /* **날 주소는 누름 그 자리에서 튼다.**
+           차례를 다 모으고 나서 틀도록 짰더니 `await` 가 하나 끼었고, 그러면 자동재생 막음이
+           `play()` 를 거절할 수 있다 — 누름의 표가 `await` 를 못 넘는 브라우저가 있다. 시험 셋이
+           그 바뀜을 잡았다(누르자마자 안 울렸다). 있는 주소는 바로, 없을 때만 더듬는다. */
+        const raw = playableUrl(rawUrl);
+        const firstDone = raw ? tryUrl(raw) : Promise.resolve(false);
+        void (async () => {
+            if (await firstDone)
+                return;
+            if (!mine())
+                return;
+            /* 날 주소는 위에서 이미 썼으니 다시 넘기지 않는다 */
+            for (const url of await questionSoundCandidates(text, null)) {
+                if (!mine())
+                    return;
+                if (await tryUrl(url))
+                    return;
+                if (!mine())
+                    return;
+            }
+            if (!mine())
+                return;
+            /* 주소로는 못 냈다 — 브라우저가 읽는다. 여기까지 와야 음원 없는 낱말도 들린다.
+               멈추개를 **말소리용으로 바꿔 둔다** — 안 바꾸면 끝난 `<audio>` 의 `stop` 이 남아,
+               멈춤 단추가 말을 끊는 것처럼 보이면서 실제로 끊는 것은 `stopSpeaking` 뿐이게 된다. */
+            playingRef.current = () => { turnRef.current++; stopSpeaking(); };
+            speak(text, { onEnd: () => { if (mine()) {
+                    playingRef.current = null;
+                    setPlayingRow(null);
+                } } });
+        })();
     }, [stopPlaying]);
     const rows = useMemo(() => list.map((it) => {
         const itr = it ?? {};
@@ -128,7 +182,10 @@ export default function TrainingResultPopup(props) {
         const selectedText = typeof itr.selectedText === 'string' ? itr.selectedText : null;
         const isCorrect = resolveDecision(itr) === true;
         const sound = resolveSound(itr);
-        return { problem, variant, label, answer, selectedText, isCorrect, sound };
+        /* **단추는 길이 하나라도 있으면 선다** — 주소가 있거나, 코어가 글자를 읽을 수 있으면.
+           주소만 보던 때는 음원 없는 낱말에서 단추가 통째로 사라졌다((307)③). */
+        const canHear = !!sound || canSpeak(problem);
+        return { problem, variant, label, answer, selectedText, isCorrect, sound, canHear };
     }), [list, getJudge, t]);
     const hasAnswerCols = useMemo(() => rows.some(r => r.answer !== null || r.selectedText !== null), [rows]);
     // 스크롤은 Popup의 .popup-content 하나만 담당한다 — 예전엔 결과 카드가 자체 스크롤
@@ -149,11 +206,15 @@ export default function TrainingResultPopup(props) {
         // 결과 계산 중에는 Esc 로도 완료(닫기)하지 않는다 — '완료' 단추와 같은 까닭
         beforeClose: blockWhilePending, footerClassName: "trp-result__foot", footer: ({ animateThen, closeWithAnimation }) => (_jsxs(_Fragment, { children: [pending && _jsx("p", { id: reasonId, className: "trp-actions__reason caption-1", role: "status", children: t('training.result.pendingDone', '결과를 계산하는 중이라 아직 완료할 수 없습니다.') }), _jsxs("div", { className: "trp-actions", children: [_jsx(Button, { htmlType: "button", size: 56, type: "bar", label: t('training.result.replay', '다시하기'), onClick: () => animateThen(onReplay) }), _jsx(Button, { htmlType: "button", size: 56, type: "bar", label: t('training.result.done', '완료'), variant: "main", onClick: closeWithAnimation, 
                             /* 막되 초점은 남긴다(onDisabledClick 이 있으면 native disabled 대신 aria-disabled) — 키보드·낭독기가 까닭을 들을 수 있게 */
-                            disabled: pending, onDisabledClick: pending ? () => { } : undefined, "aria-describedby": pending ? reasonId : undefined })] })] })), children: () => (_jsxs("div", { className: "trp-result is-on", children: [_jsxs("header", { className: "trp-result__head", children: [_jsx("p", { className: "trp-result__eyebrow caption-1", children: t('training.result.eyebrow', '훈련 완료') }), _jsx("h1", { className: "trp-result__title h2", children: t('training.result.title', '훈련을 모두 마쳤습니다.') }), subtitle && _jsx("p", { className: "trp-result__subtitle body-3", children: subtitle }), _jsx("div", { className: "trp-score", children: _jsxs("div", { className: "trp-score__figure", "aria-label": t('training.result.scoreAria', { correct, total }), children: [_jsx("span", { className: "trp-score__big", children: correct }), _jsx("span", { className: "trp-score__sep", children: "/" }), _jsx("span", { className: "trp-score__total", children: total })] }) })] }), rows.length > 0 && (_jsx("section", { className: "trp-result__body", children: _jsxs("div", { className: `result-table${hasAnswerCols ? ' result-table--answer' : ''}`, role: "table", "aria-label": t('training.result.tableAriaLabel', '문항별 판정'), children: [_jsxs("div", { className: "result-table__head caption-1", role: "row", children: [_jsx("span", { role: "columnheader", children: t('common.col.problem', '문제') }), hasAnswerCols && _jsx("span", { role: "columnheader", children: t('training.result.colAnswerSelected', '정답 · 선택') }), _jsx("span", { className: "col-right", role: "columnheader", children: t('training.result.colJudge', '판정') })] }), rows.map((r, i) => (_jsxs("div", { className: "result-table__row", role: "row", children: [_jsxs("div", { className: "trp-row__problem", children: [_jsx("span", { className: "trp-row__no caption-1", children: String(i + 1).padStart(2, '0') }), _jsx("div", { className: "trp-row__q body-2", children: r.problem }), r.sound && (_jsx(Button, { htmlType: "button", size: 32, type: "dot", variant: "transparent-gray", useBorder: false, icon: playingRow === i ? 'square' : 'volume-2', className: "trp-row__replay", 
+                            disabled: pending, onDisabledClick: pending ? () => { } : undefined, "aria-describedby": pending ? reasonId : undefined })] })] })), children: () => (_jsxs("div", { className: "trp-result is-on", children: [_jsxs("header", { className: "trp-result__head", children: [_jsx("p", { className: "trp-result__eyebrow caption-1", children: t('training.result.eyebrow', '훈련 완료') }), _jsx("h1", { className: "trp-result__title h2", children: t('training.result.title', '훈련을 모두 마쳤습니다.') }), subtitle && _jsx("p", { className: "trp-result__subtitle body-3", children: subtitle }), _jsx("div", { className: "trp-score", children: _jsxs("div", { className: "trp-score__figure", "aria-label": t('training.result.scoreAria', { correct, total }), children: [_jsx("span", { className: "trp-score__big", children: correct }), _jsx("span", { className: "trp-score__sep", children: "/" }), _jsx("span", { className: "trp-score__total", children: total })] }) })] }), rows.length > 0 && (_jsx("section", { className: "trp-result__body", children: _jsxs("div", { className: `result-table${hasAnswerCols ? ' result-table--answer' : ''}`, role: "table", "aria-label": t('training.result.tableAriaLabel', '문항별 판정'), children: [_jsxs("div", { className: "result-table__head caption-1", role: "row", children: [_jsx("span", { role: "columnheader", children: t('common.col.problem', '문제') }), hasAnswerCols && _jsx("span", { role: "columnheader", children: t('training.result.colAnswerSelected', '정답 · 선택') }), _jsx("span", { className: "col-right", role: "columnheader", children: t('training.result.colJudge', '판정') })] }), rows.map((r, i) => (_jsxs("div", { className: "result-table__row", role: "row", children: [_jsxs("div", { className: "trp-row__problem", children: [_jsx("span", { className: "trp-row__no caption-1", children: String(i + 1).padStart(2, '0') }), _jsx("div", { className: "trp-row__q body-2", children: r.problem }), r.canHear && (_jsx(Button, { htmlType: "button", size: 32, type: "dot", 
+                                                /* **변형을 주지 않는다 — 기본이다**((307)②, 사장님이 두 번 짚으셨다).
+                                                   앱은 이것을 못 바꾼다 — 코어가 넘기는 prop 이고, 앱 CSS 로 코어를
+                                                   겨누지 않는 것이 이 집 규약이다. 그래서 코어가 떼어 낸다. */
+                                                useBorder: false, icon: playingRow === i ? 'square' : 'volume-2', className: "trp-row__replay", 
                                                 /* **줄 번호를 이름에 넣는다** — 줄마다 같은 단추가 서므로, 낭독기로
                                                    단추 목록을 훑으면 `다시 듣기` 가 문항 수만큼 서서 못 가린다
                                                    (`TrainingCardGroup` 의 `접기` 와 같은 꼴). */
                                                 ariaLabel: playingRow === i
                                                     ? t('training.result.replaySoundStop', { no: i + 1, defaultValue: '{{no}}번 듣기 멈춤' })
-                                                    : t('training.result.replaySound', { no: i + 1, defaultValue: '{{no}}번 다시 듣기' }), onClick: () => (playingRow === i ? stopPlaying() : replay(i, r.sound)) }))] }), hasAnswerCols && (_jsxs("div", { className: "trp-row__answers", children: [r.answer !== null && (_jsxs("div", { className: "trp-row__answer-line", children: [_jsx("span", { className: "trp-row__answer-label answer-correct caption-1", children: t('training.result.colAnswer', '정답') }), _jsx("span", { className: "trp-row__answer-value body-2", children: r.answer })] })), _jsxs("div", { className: "trp-row__answer-line", children: [_jsx("span", { className: `trp-row__answer-label answer-selected caption-1 ${r.isCorrect ? 'is-correct' : 'is-wrong'}`, children: t('training.result.colSelected', '선택') }), _jsx("span", { className: `trp-row__answer-value body-2 ${r.isCorrect ? 'is-correct' : 'is-wrong'}`, children: r.selectedText ?? '—' })] })] })), _jsx("div", { className: "trp-row__judge", children: _jsx(Badge, { variant: r.variant, label: r.label, fill: "soft", minWidth: 80 }) })] }, i)))] }) }))] })) }));
+                                                    : t('training.result.replaySound', { no: i + 1, defaultValue: '{{no}}번 다시 듣기' }), onClick: () => (playingRow === i ? stopPlaying() : replay(i, r.problem, r.sound)) }))] }), hasAnswerCols && (_jsxs("div", { className: "trp-row__answers", children: [r.answer !== null && (_jsxs("div", { className: "trp-row__answer-line", children: [_jsx("span", { className: "trp-row__answer-label answer-correct caption-1", children: t('training.result.colAnswer', '정답') }), _jsx("span", { className: "trp-row__answer-value body-2", children: r.answer })] })), _jsxs("div", { className: "trp-row__answer-line", children: [_jsx("span", { className: `trp-row__answer-label answer-selected caption-1 ${r.isCorrect ? 'is-correct' : 'is-wrong'}`, children: t('training.result.colSelected', '선택') }), _jsx("span", { className: `trp-row__answer-value body-2 ${r.isCorrect ? 'is-correct' : 'is-wrong'}`, children: r.selectedText ?? '—' })] })] })), _jsx("div", { className: "trp-row__judge", children: _jsx(Badge, { variant: r.variant, label: r.label, fill: "soft", minWidth: 80 }) })] }, i)))] }) }))] })) }));
 }

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

@@ -0,0 +1,11 @@
+/** 틀 수 있는 주소면 그대로, 아니면 `null` */
+export declare function playableUrl(v: unknown): string | null;
+/** 코어가 글자를 소리로 바꿀 길을 하나라도 들고 있나 — 없으면 단추를 세울 뜻이 없다 */
+export declare function canSpeak(text: string | null | undefined): boolean;
+/**
+ * 더듬을 주소를 **차례대로** 모은다(①②③). ④ 는 주소가 아니므로 여기 없다 —
+ * 다 실패하면 부르는 쪽이 `speechSynthesis` 로 간다.
+ *
+ * 리졸버가 던지거나 빈 글자를 주면 그 자리만 건너뛴다 — 한 자리의 실패로 길이 끊기지 않는다.
+ */
+export declare function questionSoundCandidates(text: string | null | undefined, rawUrl: unknown): Promise<string[]>;

package/dist/packages/core/src/components/Training/questionSoundRoute.js

@@ -0,0 +1,66 @@
+/**
+ * **코어가 한 문항을 읽을 때 타는 길 — 그 차례를 아는 자리.**
+ *
+ * 차례는 넷이다.
+ *   ① 부르는 쪽이 넘긴 날 주소(정식 음원)
+ *   ② `configureTTS({ urlResolver })` — 저장소에 있는 정식 음원을 찾는다
+ *   ③ `configureTTS({ fallbackUrlResolver })` — 없으면 그때 합성한다(앱의 런타임 TTS)
+ *   ④ 브라우저 `speechSynthesis`
+ *
+ * **왜 모으나.** 이 차례가 `TrainingWordCard` 와 `TrainingStepAudioPlayer` 에 **두 벌**로
+ * 적혀 있었다. 0.328.0 의 결과 팝업 다시 듣기는 ①만 보고 — ②③④ 를 안 봐서 **정식 음원이
+ * 없는 낱말에는 단추가 아예 안 섰다.** 말귀_1 이 실측했다(2026-10-14): 다섯 줄 중 둘이
+ * 정식 400 · 자동 캐시 400 이라 단추가 없었는데, **훈련 중에는 다섯 다 들렸다** — 코어가
+ * ③④ 로 읽어 주고 있었다. 셋째 벌을 또 쓰지 않으려고 차례만 여기 둔다.
+ *
+ * **재생과 임자(자물쇠)는 여기서 다루지 않는다.** 그쪽은 부르는 쪽마다 쥐는 법이 다르고
+ * (카드는 `claimSound`, 팝업은 제 줄 하나), 그 다름이 각자의 내력에 적혀 있다. 여기서 하는
+ * 일은 **"어느 주소를 어느 차례로 더듬나"** 뿐이다.
+ */
+import { getTTSUrlResolver, getTTSFallbackUrlResolver } from '../../utils/ttsConfig';
+/**
+ * 틀 수 있는 주소의 꼴.
+ *
+ * 글자이기만 하면 되는 게 아니다 — 소리 자리에 제목이 들어 있는 꼴을 틀려고 하면
+ * 조용히 아무 일도 안 난다.
+ */
+const PLAYABLE = /^(https?:|blob:|data:audio|\/|\.\/)/;
+/** 틀 수 있는 주소면 그대로, 아니면 `null` */
+export function playableUrl(v) {
+    return typeof v === 'string' && PLAYABLE.test(v) ? v : null;
+}
+/** 코어가 글자를 소리로 바꿀 길을 하나라도 들고 있나 — 없으면 단추를 세울 뜻이 없다 */
+export function canSpeak(text) {
+    if (!text)
+        return false;
+    if (getTTSUrlResolver() || getTTSFallbackUrlResolver())
+        return true;
+    return typeof window !== 'undefined' && !!window.speechSynthesis;
+}
+/**
+ * 더듬을 주소를 **차례대로** 모은다(①②③). ④ 는 주소가 아니므로 여기 없다 —
+ * 다 실패하면 부르는 쪽이 `speechSynthesis` 로 간다.
+ *
+ * 리졸버가 던지거나 빈 글자를 주면 그 자리만 건너뛴다 — 한 자리의 실패로 길이 끊기지 않는다.
+ */
+export async function questionSoundCandidates(text, rawUrl) {
+    const out = [];
+    const raw = playableUrl(rawUrl);
+    if (raw)
+        out.push(raw);
+    const t = (text ?? '').trim();
+    if (!t)
+        return out;
+    for (const resolver of [getTTSUrlResolver(), getTTSFallbackUrlResolver()]) {
+        if (!resolver)
+            continue;
+        try {
+            const url = playableUrl(await Promise.resolve(resolver(t)));
+            /* 같은 주소를 두 번 더듬지 않는다 — 리졸버 둘이 같은 저장소를 가리키는 일이 있다 */
+            if (url && !out.includes(url))
+                out.push(url);
+        }
+        catch { /* 이 자리만 건너뛴다 */ }
+    }
+    return out;
+}

package/dist/packages/core/src/components/barChartData.d.ts

@@ -56,7 +56,6 @@ export declare function todayWeekValue(): {
 export declare function buildMonthChartData(points: ChartPoint[]): Record<string, MonthBarData>;
 export declare const MONTH_OPTIONS: {
     value: string;
-    label: string;
     year: number;
     month: number;
 }[];
@@ -64,7 +63,6 @@ export declare const MONTH_OPTIONS: {
  *  옵션에서 빠졌다. 컨트롤 훅은 자료가 바뀔 때마다 이것으로 다시 만든다. */
 export declare function monthOptionsNow(): {
     value: string;
-    label: string;
     year: number;
     month: number;
 }[];

package/dist/packages/core/src/components/barChartData.js

@@ -166,12 +166,14 @@ function genMonthOptions() {
     const now = getTodayKstDate();
     const curY = now.getFullYear();
     const curM = now.getMonth() + 1;
+    /* **이름표를 여기서 짓지 않는다.** 한때 `label: v` 로 **열쇠를 그대로** 넣어 뒀다 —
+       아무도 안 읽어 조용했지만, 읽는 날 화면에 자리표가 그대로 뜬다(0.325.0 이 그 꼴이었다).
+       보이는 글은 말을 아는 쪽(`useBarChartControl`)이 `yearMonthLabel` 로 짓는다. */
     const opts = [];
     for (let y = 2024; y <= curY; y++) {
         const end = y === curY ? curM : 12;
         for (let m = 1; m <= end; m++) {
-            const v = monthKeyOf(y, m);
-            opts.push({ value: v, label: v, year: y, month: m });
+            opts.push({ value: monthKeyOf(y, m), year: y, month: m });
         }
     }
     return opts.reverse();

package/dist/packages/core/src/components/barChartMonthKey.d.ts

@@ -1,27 +1,51 @@
 /**
  * **막대판 달 열쇠의 꼴을 아는 유일한 자리.**
  *
- * 달 열쇠는 `"2026년 10월"` 이다. 그 꼴이 **열 자리에 흩어져 있었다** — 짓는 데 다섯,
- * 정규식으로 뜯는 데 다섯(`barChartData` · `barChartTypes` · `BarChart` · `useBarChartControl`).
- * 하나를 고치고 아홉을 놓치면 **열쇠가 안 맞아 달이 통째로 빈 칸**이 된다. 0.325.0 에서
- * 같은 결함을 밟았다 — 두 자리에 적힌 결정 하나를 글자로 바꾸다 한 자리가 조용히 안 바뀌었다.
- *
- * **이 꼴은 이름표가 아니라 자리표다.** 한국어처럼 생겼지만 화면에 그대로 내면 안 된다 —
- * 보이는 글은 `yearMonthLabel(t, lang, year, month)` 이 Intl 로 짓는다(`October 2026`).
- * `monthOptionsNow()` 의 `label` 도 `useBarChartControl` 이 그렇게 덮어쓴다.
- *
- * **꼴을 왜 안 바꾸나.** 로케일에 안 매인 `"2026-10"` 이 옳지만, 소비자(`speechear-v2`)의
- * 시험이 이 꼴을 열 군데서 못 박고 있다(`toContain('2026년 3월')`). 열쇠 꼴을 바꾸는 일은
- * 소비자를 함께 고쳐야 하므로 따로 한다. 지금 고치는 것은 **아는 자리를 하나로 모으는 것**이다.
+ * 달 열쇠는 `"2026-10"` 이다. **로케일에 안 매인 자리표다.**
+ *
+ * 0.329.0 까지는 `"2026년 10월"` 이었다. 그 꼴이 **열 자리에 흩어져 있었고**(짓는 데 다섯,
+ * 정규식으로 뜯는 데 다섯 — `barChartData` · `barChartTypes` · `BarChart` · `useBarChartControl`)
+ * 하나를 고치고 아홉을 놓치면 **달이 통째로 빈 칸**이 됐다. 0.325.0 에서 실제로 밟았다.
+ * 먼저 이 파일 하나로 모았고(0.329.0), 이제 꼴을 바꾼다.
+ *
+ * **왜 바꾸나.** 한국어처럼 생긴 자리표라 **이름표와 섞였다.** 0.325.0 의 결함이 바로 그
+ * 섞임이었다 — 달 드롭다운에 열쇠 글자가 그대로 떴고, 한국어 화면에서는 **그럴듯해 보여**
+ * 영어 화면에서만 티가 났다. `"2026-10"` 은 누가 봐도 이름표가 아니다.
+ *
+ * 보이는 글은 `yearMonthLabel(t, lang, year, month)` 이 Intl 로 짓는다
+ * (`2026년 10월` · `October 2026`). 그쪽은 이번에 **안 바뀐다.**
+ *
+ * **내보낸다.** `buildMonthChartData` 가 돌려주는 꾸러미를 소비자가 **열쇠로 찾아야** 하는데,
+ * 꼴을 알 길이 없으면 제 손으로 짓는다 — 실제로 2026-10-14 에 소비자 쪽에 `monthKeyShape.ts`
+ * 가 생길 뻔했다. 그러면 꼴을 아는 자리가 **저장소를 건너 둘**이 되고, 이 파일이 막으려던
+ * 바로 그 결함이 더 먼 자리에서 난다. 짓는 것도 뜯는 것도 여기 것을 쓰게 한다.
+ *
+ * **함께 한 일** — 소비자(`speechear-v2`)가 이 꼴을 글자로 박은 자리 **열일곱**(파일 일곱)을
+ * 말귀_1 이 먼저 느슨하게 했다. 담아 두는 자리는 양쪽 다 없어(`localStorage` 등) 옛 열쇠가
+ * 남아 빈 칸이 되는 길은 없다 — 훑어서 셌다.
  */
-/** `(2026, 10)` → `"2026년 10월"`. 달은 **1 부터** 센다. */
+/**
+ * `(2026, 10)` → `"2026-10"`. 달은 **1 부터** 세고, **두 자리로 채운다**(`2026-01`).
+ *
+ * 채우는 까닭은 글자 차례가 달 차례와 같아지기 때문이다 — 안 채우면 `"2026-9"` 가
+ * `"2026-10"` 뒤에 선다(단어표 칸순이 10 을 9 앞에 세우던 것과 같은 꼴).
+ */
+/** @public */
 export declare const monthKeyOf: (year: number, month1: number) => string;
 /** 날에서 바로 — `Date.getMonth()` 가 0 부터인 것을 여기서만 더한다 */
+/** @public */
 export declare const monthKeyOfDate: (d: Date) => string;
-/** `"2026년 10월"` → `{ year: 2026, month1: 10 }`. 꼴이 아니면 `null`. */
+/**
+ * `"2026-10"` → `{ year: 2026, month1: 10 }`. 꼴이 아니면 `null`.
+ *
+ * **두 자리만 받는다.** `"2026-9"` 를 받아 주면 짓는 쪽과 뜯는 쪽이 어긋나도 조용하고,
+ * 그 어긋남이 바로 열쇠가 안 맞는 결함이다.
+ */
+/** @public */
 export declare function parseMonthKey(key: string): {
     year: number;
     month1: number;
 } | null;
-/** 주 값은 달 열쇠에 주 번호를 붙인 것 — `"2026년 10월#2"`. 주는 0 부터. */
+/** 주 값은 달 열쇠에 주 번호를 붙인 것 — `"2026-10#2"`. 주는 0 부터. */
+/** @public */
 export declare const weekValueOf: (monthKey: string, week: number) => string;

package/dist/packages/core/src/components/barChartMonthKey.js

@@ -1,27 +1,55 @@
 /**
  * **막대판 달 열쇠의 꼴을 아는 유일한 자리.**
  *
- * 달 열쇠는 `"2026년 10월"` 이다. 그 꼴이 **열 자리에 흩어져 있었다** — 짓는 데 다섯,
- * 정규식으로 뜯는 데 다섯(`barChartData` · `barChartTypes` · `BarChart` · `useBarChartControl`).
- * 하나를 고치고 아홉을 놓치면 **열쇠가 안 맞아 달이 통째로 빈 칸**이 된다. 0.325.0 에서
- * 같은 결함을 밟았다 — 두 자리에 적힌 결정 하나를 글자로 바꾸다 한 자리가 조용히 안 바뀌었다.
- *
- * **이 꼴은 이름표가 아니라 자리표다.** 한국어처럼 생겼지만 화면에 그대로 내면 안 된다 —
- * 보이는 글은 `yearMonthLabel(t, lang, year, month)` 이 Intl 로 짓는다(`October 2026`).
- * `monthOptionsNow()` 의 `label` 도 `useBarChartControl` 이 그렇게 덮어쓴다.
- *
- * **꼴을 왜 안 바꾸나.** 로케일에 안 매인 `"2026-10"` 이 옳지만, 소비자(`speechear-v2`)의
- * 시험이 이 꼴을 열 군데서 못 박고 있다(`toContain('2026년 3월')`). 열쇠 꼴을 바꾸는 일은
- * 소비자를 함께 고쳐야 하므로 따로 한다. 지금 고치는 것은 **아는 자리를 하나로 모으는 것**이다.
+ * 달 열쇠는 `"2026-10"` 이다. **로케일에 안 매인 자리표다.**
+ *
+ * 0.329.0 까지는 `"2026년 10월"` 이었다. 그 꼴이 **열 자리에 흩어져 있었고**(짓는 데 다섯,
+ * 정규식으로 뜯는 데 다섯 — `barChartData` · `barChartTypes` · `BarChart` · `useBarChartControl`)
+ * 하나를 고치고 아홉을 놓치면 **달이 통째로 빈 칸**이 됐다. 0.325.0 에서 실제로 밟았다.
+ * 먼저 이 파일 하나로 모았고(0.329.0), 이제 꼴을 바꾼다.
+ *
+ * **왜 바꾸나.** 한국어처럼 생긴 자리표라 **이름표와 섞였다.** 0.325.0 의 결함이 바로 그
+ * 섞임이었다 — 달 드롭다운에 열쇠 글자가 그대로 떴고, 한국어 화면에서는 **그럴듯해 보여**
+ * 영어 화면에서만 티가 났다. `"2026-10"` 은 누가 봐도 이름표가 아니다.
+ *
+ * 보이는 글은 `yearMonthLabel(t, lang, year, month)` 이 Intl 로 짓는다
+ * (`2026년 10월` · `October 2026`). 그쪽은 이번에 **안 바뀐다.**
+ *
+ * **내보낸다.** `buildMonthChartData` 가 돌려주는 꾸러미를 소비자가 **열쇠로 찾아야** 하는데,
+ * 꼴을 알 길이 없으면 제 손으로 짓는다 — 실제로 2026-10-14 에 소비자 쪽에 `monthKeyShape.ts`
+ * 가 생길 뻔했다. 그러면 꼴을 아는 자리가 **저장소를 건너 둘**이 되고, 이 파일이 막으려던
+ * 바로 그 결함이 더 먼 자리에서 난다. 짓는 것도 뜯는 것도 여기 것을 쓰게 한다.
+ *
+ * **함께 한 일** — 소비자(`speechear-v2`)가 이 꼴을 글자로 박은 자리 **열일곱**(파일 일곱)을
+ * 말귀_1 이 먼저 느슨하게 했다. 담아 두는 자리는 양쪽 다 없어(`localStorage` 등) 옛 열쇠가
+ * 남아 빈 칸이 되는 길은 없다 — 훑어서 셌다.
  */
-/** `(2026, 10)` → `"2026년 10월"`. 달은 **1 부터** 센다. */
-export const monthKeyOf = (year, month1) => `${year}년 ${month1}월`;
+/**
+ * `(2026, 10)` → `"2026-10"`. 달은 **1 부터** 세고, **두 자리로 채운다**(`2026-01`).
+ *
+ * 채우는 까닭은 글자 차례가 달 차례와 같아지기 때문이다 — 안 채우면 `"2026-9"` 가
+ * `"2026-10"` 뒤에 선다(단어표 칸순이 10 을 9 앞에 세우던 것과 같은 꼴).
+ */
+/** @public */
+export const monthKeyOf = (year, month1) => `${year}-${String(month1).padStart(2, '0')}`;
 /** 날에서 바로 — `Date.getMonth()` 가 0 부터인 것을 여기서만 더한다 */
+/** @public */
 export const monthKeyOfDate = (d) => monthKeyOf(d.getFullYear(), d.getMonth() + 1);
-/** `"2026년 10월"` → `{ year: 2026, month1: 10 }`. 꼴이 아니면 `null`. */
+/**
+ * `"2026-10"` → `{ year: 2026, month1: 10 }`. 꼴이 아니면 `null`.
+ *
+ * **두 자리만 받는다.** `"2026-9"` 를 받아 주면 짓는 쪽과 뜯는 쪽이 어긋나도 조용하고,
+ * 그 어긋남이 바로 열쇠가 안 맞는 결함이다.
+ */
+/** @public */
 export function parseMonthKey(key) {
-    const m = /^(\d+)년 (\d+)월$/.exec(key);
-    return m ? { year: Number(m[1]), month1: Number(m[2]) } : null;
+    const m = /^(\d{4})-(\d{2})$/.exec(key);
+    if (!m)
+        return null;
+    const month1 = Number(m[2]);
+    /* `2026-13` 은 달이 아니다 — 꼴만 맞다고 받아 주면 엉뚱한 달을 집는다 */
+    return month1 >= 1 && month1 <= 12 ? { year: Number(m[1]), month1 } : null;
 }
-/** 주 값은 달 열쇠에 주 번호를 붙인 것 — `"2026년 10월#2"`. 주는 0 부터. */
+/** 주 값은 달 열쇠에 주 번호를 붙인 것 — `"2026-10#2"`. 주는 0 부터. */
+/** @public */
 export const weekValueOf = (monthKey, week) => `${monthKey}#${week}`;

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

@@ -145,6 +145,7 @@ export { default as LineChart, LINE_CHART_HOVER_DELAY_MS } from './components/Li
 export { default as GameIntro } from './components/GameIntro';
 export { useBarChartControl } from './components/useBarChartControl';
 export { buildMonthChartData } from './components/barChartData';
+export { monthKeyOf, monthKeyOfDate, parseMonthKey, weekValueOf } from './components/barChartMonthKey';
 export { getControlDateRange } from './components/barChartTypes';
 export type { ControlDateRange } from './components/barChartTypes';
 export type { BarChartProps, BarChartControl, BarChartSize, BarData, MonthBarData, ChartPoint } from './components/BarChart';

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

@@ -95,6 +95,9 @@ export { default as LineChart, LINE_CHART_HOVER_DELAY_MS } from './components/Li
 export { default as GameIntro } from './components/GameIntro';
 export { useBarChartControl } from './components/useBarChartControl';
 export { buildMonthChartData } from './components/barChartData';
+/* 달 열쇠의 꼴 — `buildMonthChartData` 의 꾸러미를 찾으려면 부르는 쪽도 이 꼴을 알아야 한다.
+   안 내보내면 소비자가 제 손으로 짓고, 꼴을 아는 자리가 저장소를 건너 둘이 된다. */
+export { monthKeyOf, monthKeyOfDate, parseMonthKey, weekValueOf } from './components/barChartMonthKey';
 export { getControlDateRange } from './components/barChartTypes';
 export { default as RingChart } from './components/RingChart';
 export { default as ChartSection, ChartTotal, ChartLegend } from './components/ChartSection';

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

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

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

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