@ihabdevteam/core 0.142.0 → 0.143.0

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

@@ -10,6 +10,7 @@ import { resumeAudioMeter, routeElementAudio, setElementVolume, getElementVolume
 import { useNoisePlayer, effectiveNoiseVolume, effectiveSpeechVolume, noiseRatioOf } from './NoisePlayerContext';
 import { useNoiseFade } from './useNoiseFade';
 import { useTTSPlayback } from './useTTSPlayback';
+import { claimSound, stopSoundIfOwner } from './currentSound';
 import './TrainingStepAudioPlayer.css';
 import WaveForm from './AudioPlayerWaveForm';
 import Toast from '../Toast';
@@ -157,7 +158,7 @@ export default function TrainingStepAudioPlayer({ btnLabel, soundSrc, bucketPath
         audioRef,
         playbackStateRef,
     });
-    const { startTTS, stopTTS } = useTTSPlayback({
+    const { startTTS: 합성시작, stopTTS } = useTTSPlayback({
         ttsText,
         playbackRate,
         // TTS 음성 = 문제 소리 = 전체 소리
@@ -173,6 +174,8 @@ export default function TrainingStepAudioPlayer({ btnLabel, soundSrc, bucketPath
         onDoneRef,
         handleEndRef,
     });
+    useEffect(() => { stopTTSRef.current = stopTTS; });
+    const startTTS = (text) => { 소리잡기('tts'); 합성시작(text); };
     const requestedSources = Array.isArray(soundSrc)
         ? soundSrc.filter(Boolean)
         : (soundSrc ? [soundSrc] : []);
@@ -192,12 +195,50 @@ export default function TrainingStepAudioPlayer({ btnLabel, soundSrc, bucketPath
        오류" 로만 보고 다시 부르면 **정지를 눌렀는데 소리가 다시 났다**. 시작할 때의 의도가 그대로일 때만 다시 시도한다. */
     const 재생의도Ref = useRef(0);
     const 멈춤의도 = () => { 재생의도Ref.current += 1; jumpTokenRef.current += 1; };
+    /* 스피커는 하나(currentSound.ts) — 한 화면의 다른 재생기(문장 듣기·문제 듣기)·낱말 카드·미리 듣기가 울리면 이 재생기는
+       멈춘다. 전에는 낱말 카드만 자물쇠를 잡아, 듣기 단계가 둘인 화면·듣기+카드 단계에서 두 소리가 함께 울렸다.
+       멈춤 단추와 같게 멈춘다(이어 듣기 가능). 함수는 한 벌이어야 자물쇠가 '내 것' 을 알아본다. */
+    const stopTTSRef = useRef(null);
+    const 소리종류Ref = useRef(null);
+    const 소리놓기Ref = useRef(null);
+    const 소리멈춤Ref = useRef(null);
+    if (!소리멈춤Ref.current) {
+        소리멈춤Ref.current = () => {
+            소리놓기Ref.current = null;
+            const a = audioRef.current;
+            if (소리종류Ref.current === 'audio' && a && !a.paused) {
+                재생의도Ref.current += 1;
+                jumpTokenRef.current += 1;
+                try {
+                    a.pause();
+                }
+                catch (e) { }
+                if (mountedRef.current)
+                    setPlaybackState('paused');
+            }
+            else if (소리종류Ref.current === 'tts') {
+                try {
+                    stopTTSRef.current?.();
+                }
+                catch (e) { }
+            }
+        };
+    }
+    const 소리잡기 = (종류) => {
+        소리종류Ref.current = 종류;
+        소리놓기Ref.current = claimSound(소리멈춤Ref.current);
+    };
+    // 멈춤·정지·완료 뒤에는 자리를 비운다 — 남이 울릴 때 끝난 재생기의 상태를 건드리지 않게
+    const 소리놓기 = () => { 소리놓기Ref.current?.(); 소리놓기Ref.current = null; };
+    useEffect(() => () => { if (소리멈춤Ref.current)
+        stopSoundIfOwner(소리멈춤Ref.current); }, []);
     const tryPlayWithRetry = useCallback(async (a, attempts = 3, delayMs = 50) => {
         const 의도 = 재생의도Ref.current;
         for (let i = 0; i < attempts; i++) {
             if (!mountedRef.current || 의도 !== 재생의도Ref.current)
                 return false;
             try {
+                소리잡기('audio');
                 await a.play();
                 return true;
             }
@@ -731,6 +772,7 @@ export default function TrainingStepAudioPlayer({ btnLabel, soundSrc, bucketPath
                 try {
                     if (synth && synth.paused) {
                         try {
+                            소리잡기('tts');
                             synth.resume();
                             setPlaybackState('playing');
                         }
@@ -847,6 +889,7 @@ export default function TrainingStepAudioPlayer({ btnLabel, soundSrc, bucketPath
     const handleStop = () => {
         // 기다리던 트랙 이동·재시도가 정지 뒤에 소리를 내지 않게
         멈춤의도();
+        소리놓기();
         if (ttsMode) {
             stopTTS();
             return;
@@ -949,6 +992,7 @@ export default function TrainingStepAudioPlayer({ btnLabel, soundSrc, bucketPath
         const outDelay = 340;
         markCompletedByEnd(true);
         멈춤의도();
+        소리놓기();
         try {
             setProgress(1);
         }
@@ -1094,6 +1138,9 @@ export default function TrainingStepAudioPlayer({ btnLabel, soundSrc, bucketPath
     const fillLeftPercent = Math.max(0, Math.min(100, (progress || 0) * 100));
     const fillClass = cx('audio-player__fill', fillVisibleFlag ? 'is-visible' : '', fillExpandedFlag ? 'is-expanded' : '', fillPausedFlag ? 'is-paused' : '', isFillOutAnimating ? 'is-out' : '');
     return (_jsxs("div", { className: `audio-player ${isDisabled ? 'is-disabled' : ''}${className ? ` ${className}` : ''}`, role: "group", "aria-label": typeof label === 'string' ? label : undefined, children: [_jsxs("div", { className: `audio-player__panel ${displayedPlaying ? "is-playing" : ""} ${isFetchingUrl ? "is-loading" : ""} ${stateLocal !== "default" ? "is-revealed" : ""}`, children: [isFetchingUrl ? (_jsxs("div", { className: "audio-player__loading", role: "status", "aria-live": "polite", children: [_jsx("span", { className: "audio-player__loading-spinner", "aria-hidden": "true" }), _jsx("span", { className: "audio-player__loading-text", children: t(`training.audioStatus.${fetchDebugStatus}`, { defaultValue: STATUS_MESSAGES[fetchDebugStatus] }) })] })) : null, stateLocal === "active" ? (_jsx("button", { className: "audio-player__button", type: "button", 
+                        /* 막힌 단계(아직 차례가 아닌 듣기·합성 주소를 받는 중)는 CSS pointer-events 로만 막아, Tab 으로 와서 Enter 를
+                           누르면 소리를 받으러 가거나 "가져오지 못했습니다" 를 띄웠다 — 마우스와 같게 키보드도 막는다 */
+                        disabled: isDisabled, 
                         // 키보드로 눌렀을 때만 초점을 옮긴다 — 마우스로 누른 사람에게 '재생 / 멈춤' 초점 툴팁이 뜨지 않게
                         onClick: () => { 듣기초점옮기기Ref.current = 키보드로눌렀나(); hideListenTip(); handleToggle(); }, "aria-label": typeof label === 'string' ? label : t('training.listen', '듣기'), onMouseEnter: showListenTip, onMouseLeave: hideListenTip, 
                         // 키보드로 이 버튼에 오면 마우스와 동일하게 안내를 띄운다

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

@@ -51,7 +51,15 @@ export default function WordTablePopup({ items, words, title, subtitle, emptyTex
        새 함수 → 알림 이 끝없이 돈다. 부모가 어떻게 짜든 안 돌게 한다. */
     const notifyRef = useRef(onScoreChange);
     useEffect(() => { notifyRef.current = onScoreChange; });
-    useEffect(() => { notifyRef.current?.(marksForSave(marks)); }, [marks]);
+    // 처음 열 때는 알리지 않는다 — 아무것도 안 매겼는데 onScoreChange({}) 가 나갔다
+    const 첫알림Ref = useRef(true);
+    useEffect(() => {
+        if (첫알림Ref.current) {
+            첫알림Ref.current = false;
+            return;
+        }
+        notifyRef.current?.(marksForSave(marks));
+    }, [marks]);
     /* 표에는 지운 칸(null)이 빠진 것만 넘긴다 — 표는 "매겨진 것"만 알면 된다. */
     const 표에줄채점 = useMemo(() => marksForSave(marks), [marks]);
     // 인쇄 — WordTable 내부 콘텐츠(.word-table 아래 그리드)를 격리 iframe으로 출력한다.

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

@@ -1,6 +1,7 @@
 'use client';
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import { resolveSoundPath, getSignedOrPublicUrl, downloadSound } from '../../utils/storage';
+import { claimSound, stopSoundIfOwner } from './currentSound';
 function derivePreviewMeta(trainingData, typeKey) {
     if (!trainingData)
         return { previewCodes: [], previewBucket: null };
@@ -51,6 +52,9 @@ export function useAudioPreview(trainingData, typeKey) {
     const [resolved, setResolved] = useState({ key: '', urls: [] });
     const previewAudioRef = useRef(null);
     const playingRef = useRef(false);
+    /* 지금 미리 듣기를 멈추는 함수 — 스피커 자물쇠(currentSound.ts)에 건다. 다른 블록 미리 듣기·훈련 소리가 울리면 이것이 불린다.
+       전에는 자물쇠에 참여하지 않아 바구니의 블록 둘을 잇달아 누르면 두 문장이 함께 울렸다. */
+    const 멈춤Ref = useRef(null);
     const previewBtnRef = useRef(null);
     const [previewHover, setPreviewHover] = useState(false);
     // downloadSound()로 만든 blob URL만 추적 — getSignedOrPublicUrl()이 반환하는 http(s) URL은
@@ -129,6 +133,8 @@ export function useAudioPreview(trainingData, typeKey) {
         e.stopPropagation();
         e.preventDefault();
         if (playingRef.current) {
+            if (멈춤Ref.current)
+                stopSoundIfOwner(멈춤Ref.current);
             playingRef.current = false;
             try {
                 previewAudioRef.current?.pause();
@@ -141,6 +147,18 @@ export function useAudioPreview(trainingData, typeKey) {
         const urls = previewUrls.filter(Boolean);
         if (!urls.length)
             return;
+        // pause() 만으로는 ended 가 오지 않아 기다리던 약속이 풀리지 않는다 — 멈출 때 풀어 반복을 끝낸다
+        let 기다림풀기 = null;
+        const 멈춤 = () => {
+            playingRef.current = false;
+            try {
+                previewAudioRef.current?.pause();
+            }
+            catch { }
+            기다림풀기?.();
+        };
+        멈춤Ref.current = 멈춤;
+        const release = claimSound(멈춤);
         playingRef.current = true;
         setPlaying(true);
         for (let i = 0; i < previewUrls.length; i++) {
@@ -152,6 +170,7 @@ export function useAudioPreview(trainingData, typeKey) {
             setPlayingIndex(i);
             try {
                 await new Promise((resolve, reject) => {
+                    기다림풀기 = resolve;
                     const audio = new Audio(url);
                     previewAudioRef.current = audio;
                     audio.onended = () => resolve();
@@ -163,13 +182,19 @@ export function useAudioPreview(trainingData, typeKey) {
                 break;
             }
         }
-        playingRef.current = false;
-        setPlaying(false);
-        setPlayingIndex(-1);
+        release();
+        if (멈춤Ref.current === 멈춤) {
+            멈춤Ref.current = null;
+            playingRef.current = false;
+            setPlaying(false);
+            setPlayingIndex(-1);
+        }
     }, [previewUrls]);
     // Pause and release audio on unmount
     useEffect(() => {
         return () => {
+            if (멈춤Ref.current)
+                stopSoundIfOwner(멈춤Ref.current);
             playingRef.current = false;
             try {
                 previewAudioRef.current?.pause();

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

@@ -11,7 +11,8 @@ import Dropdown from '../Dropdown';
 import Pagination from '../Pagination';
 import WordImageTooltip from '../Tooltip/WordImageTooltip';
 import { useHoverAnchor } from '../../hooks/useHoverAnchor';
-import { matchesWordQuery } from '../../utils/koreanSyllable';
+import { makeWordQueryMatcher } from '../../utils/koreanSyllable';
+const 가나다 = new Intl.Collator('ko');
 import { withIga, withEulReul } from '../../utils/josa';
 /** @public */
 export default function WordSearchResultBlock({ titleIcon, resultCount, resultUnit, searchQuery, items, groups, selected = [], onSelect, maxSelect, onClearSelection, onPrint, onPrintEmpty, className, emptyHint, sectionType = 'page', disc, notice, }) {
@@ -61,6 +62,21 @@ export default function WordSearchResultBlock({ titleIcon, resultCount, resultUn
         value: v, label: t('wordSearch.pageSize', { count: Number(v), defaultValue: `${v}개씩 보기` }),
     })), [t]);
     const firstWord = (it) => it.words[0];
+    /* '시작 우선' 순위는 검색어가 바뀔 때 판별기를 한 번 만들고 항목마다 한 번만 센다 — 비교할 때마다 검색어를 다시 펼치고
+       localeCompare 를 불러 결과가 바뀔 때 23k 개에 38ms 걸렸다. */
+    const 시작순위 = useMemo(() => {
+        const qLen = [...q].length;
+        const m = makeWordQueryMatcher(q);
+        const memo = new Map();
+        return (it) => {
+            let r = memo.get(it);
+            if (r === undefined) {
+                r = m((it.words[0]?.label ?? '').slice(0, qLen)) ? 0 : 1;
+                memo.set(it, r);
+            }
+            return r;
+        };
+    }, [q]);
     // 정렬 비교자 — flat/그룹 뷰가 공유한다.
     const sortCompare = useCallback((a, b) => {
         const label = (it) => firstWord(it)?.label ?? '';
@@ -70,9 +86,7 @@ export default function WordSearchResultBlock({ titleIcon, resultCount, resultUn
             // 시작 우선 — 검색어로 시작하는 단어를 위로. 앞 q 글자만 잘라 매칭하면 "첫 음절부터 일치"만
             // 남는다(초성 검색도 동일: 'ㄴ' → '나무'가 위). 동순위는 가나다.
             case 'match': {
-                const qLen = [...q].length;
-                const rank = (it) => matchesWordQuery(label(it).slice(0, qLen), q) ? 0 : 1;
-                return rank(a) - rank(b) || label(a).localeCompare(label(b), 'ko');
+                return 시작순위(a) - 시작순위(b) || 가나다.compare(label(a), label(b));
             }
             case 'ganada': return label(a).localeCompare(label(b), 'ko');
             case 'ganada_desc': return label(b).localeCompare(label(a), 'ko');
@@ -82,7 +96,7 @@ export default function WordSearchResultBlock({ titleIcon, resultCount, resultUn
             case 'grade_desc': return grade(b) - grade(a) || label(a).localeCompare(label(b), 'ko');
             default: return 0;
         }
-    }, [effectiveSortKey, q]);
+    }, [effectiveSortKey, 시작순위]);
     const sortedItems = useMemo(() => items.slice().sort(sortCompare), [items, sortCompare]);
     const pageSize = Number(pageSizeStr) || 10;
     // 그룹 뷰(대립쌍표 음소대립)도 flat과 동일하게 정렬·페이지네이션한다 — 그룹 순서를 유지하고 그룹 내부를

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

@@ -166,7 +166,7 @@ export default function WordTableBlock({ title, titleIcon, disc, items, onSaveCo
         Promise.all(imagePairs.map(([w, h]) => checkImageExists(w, h))).then(results => {
             if (!cancelled)
                 setImageFound(results.some(Boolean));
-        });
+        }, () => { }); // 확인이 거절돼도(리졸버 예외 등) 처리되지 않은 거절로 새지 않게 — 이미지 없음으로 둔다
         return () => { cancelled = true; };
     }, [imagePairs]);
     const hasImage = imagePairs.length > 0 && imageFound;
@@ -288,7 +288,10 @@ export default function WordTableBlock({ title, titleIcon, disc, items, onSaveCo
                             setActiveCell(null);
                         },
                         onClose: handleCloseWordSearch,
-                    }), !hideControls && (_jsx(TableFilterPanel, { hasImage: hasImage, hasColloquial: hasColloquial, contentTypes: contentTypes, orientation: orientation, showOutline: showOutline, cutLine: cutLine, showDivLine: showDivLine, setters: { setContentTypes, setOrientation, setShowOutline, setCutLine, setShowDivLine }, showCutLine: (pagesEnabled ? itemsPerPage : count) > 1, showDivLine2: hasPairs, middleSections: middleSections, extraSelected: middleSelected, onExtraSelect: handleMiddleSelect })), isPaginated && pages ? (_jsx("div", { className: "word-table-block__pages", children: pages.map((page, i) => (_jsx(WordTable, { orientation: orientation, contentTypes: contentTypes, cutLine: cutLine, showOutline: showOutline, showDivLine: showDivLine, count: itemsPerPage, items: page, onRemoveItem: onRemoveItem, 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 ? cells : undefined, activeCell: activeCell, onActivateCell: (isEditable || onAddItem) ? setActiveCell : undefined, onRemoveCell: isEditable ? handleRemove : undefined, onRemoveItem: !isEditable ? onRemoveItem : undefined, onReorder: !isEditable ? onReorder : undefined, 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', '이 단어표에 대한 제목을 입력하세요.'), 
+                    }), !hideControls && (_jsx(TableFilterPanel, { hasImage: hasImage, hasColloquial: hasColloquial, contentTypes: contentTypes, orientation: orientation, showOutline: showOutline, cutLine: cutLine, showDivLine: showDivLine, setters: { setContentTypes, setOrientation, setShowOutline, setCutLine, setShowDivLine }, showCutLine: (pagesEnabled ? itemsPerPage : count) > 1, showDivLine2: hasPairs, middleSections: middleSections, extraSelected: middleSelected, onExtraSelect: handleMiddleSelect })), isPaginated && pages ? (_jsx("div", { className: "word-table-block__pages", children: pages.map((page, i) => (_jsx(WordTable, { orientation: orientation, contentTypes: contentTypes, cutLine: cutLine, showOutline: showOutline, showDivLine: showDivLine, count: itemsPerPage, items: page, onRemoveItem: onRemoveItem, 
+                            /* 쪽이 나뉘면 끌어 옮기기가 통째로 꺼졌다(말귀 단어 찾기: 9개부터). 쪽 안의 자리를 전체 자리로 옮겨 넘긴다 —
+                               쪽을 넘는 이동은 하지 않는다. */
+                            onReorder: onReorder && ((from, to) => onReorder(from + i * itemsPerPage, to + i * itemsPerPage)), 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 ? cells : undefined, activeCell: activeCell, onActivateCell: (isEditable || onAddItem) ? setActiveCell : undefined, onRemoveCell: isEditable ? handleRemove : undefined, onRemoveItem: !isEditable ? onRemoveItem : undefined, onReorder: !isEditable ? onReorder : undefined, 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', '이 단어표에 대한 제목을 입력하세요.'), 
                                     /* PanelRow의 라벨은 시각적으로만 붙어 있고 입력과 연결돼 있지 않아, 낭독기에는
                                        이름 없는 입력으로 읽혔다. placeholder는 자동완성 안내문("Tab 또는 space…")이
                                        섞여 있어 이름으로 부적절하므로 같은 라벨 문구를 넘긴다. */

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

@@ -3,13 +3,13 @@ import type { WordSearchResultItem } from '../../types/wordSearch';
 import './WordTableButton.css';
 /** @public */
 export interface WordTableButtonProps {
-    /** 단어표 내용(썸네일 미리보기 + 개수) */
+    /** 단어표 내용(썸네일 미리보기) */
     items: WordSearchResultItem[];
     /** 단어표 이름 */
     name: string;
     /** 설명 — 제목 아래 body-3로 표시(있을 때만) */
     description?: string;
-    /** 생성일(ISO) — 메타(날짜)에 표시. 없으면 개수만. */
+    /** 생성일(ISO) — 메타(날짜)에 표시. */
     createdAt?: string;
     /** 스토어 발행 배지 표시 */
     published?: boolean;
@@ -43,6 +43,6 @@ export interface WordTableButtonProps {
 }
 /**
  * @public 단어표를 '문서형' 미리보기 카드로 표현하는 컴포넌트.
- * 내용 썸네일(WordTableThumbnail) + 이름 + 날짜·개수 + (발행 배지 / 더보기 / 스토어 푸터).
+ * 내용 썸네일(WordTableThumbnail) + 이름 + 날짜 + (발행 배지 / 더보기 / 스토어 푸터).
  */
 export default function WordTableButton({ items, name, description, createdAt, published, publishedLabel, shared, sharedLabel, isNew, publisherName, publishedAt, likeCount, downloadCount, onPublisherClick, selected, onClick, onMore, titleNode, className, }: WordTableButtonProps): import("react").JSX.Element;

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

@@ -9,7 +9,7 @@ import { formatRelativeTime } from '../../utils/date';
 import './WordTableButton.css';
 /**
  * @public 단어표를 '문서형' 미리보기 카드로 표현하는 컴포넌트.
- * 내용 썸네일(WordTableThumbnail) + 이름 + 날짜·개수 + (발행 배지 / 더보기 / 스토어 푸터).
+ * 내용 썸네일(WordTableThumbnail) + 이름 + 날짜 + (발행 배지 / 더보기 / 스토어 푸터).
  */
 export default function WordTableButton({ items, name, description, createdAt, published, publishedLabel, shared, sharedLabel, isNew, publisherName, publishedAt, likeCount, downloadCount, onPublisherClick, selected, onClick, onMore, titleNode, className, }) {
     const { t } = useTranslation();

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

@@ -43,7 +43,7 @@ export function useWordTableDisplaySettings(items) {
         }
         Promise.all(items.flatMap(item => item.words.map(w => checkImageExists(w.label, w.homonum))))
             .then(results => { if (!cancelled)
-            setHasImage(results.some(Boolean)); });
+            setHasImage(results.some(Boolean)); }, () => { }); // 거절은 이미지 없음으로 둔다
         return () => { cancelled = true; };
     }, [items]);
     /* eslint-enable react-hooks/set-state-in-effect */

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

@@ -23,7 +23,7 @@ export interface WordTableBlockProps {
     tableName?: string;
     /** 전달하면 외부 데이터 표시 모드, 없으면 편집 모드 */
     items?: WordSearchResultItem[];
-    /** 전달하면 저장 팝업을 내부에서 열고 확인 후 name·items·description을 전달.
+    /** 전달하면 저장하기가 저장 팝업(`renderSavePopup` 이 그림 — 없으면 아무것도 뜨지 않는다)을 열고 확인 후 name·items·description을 전달.
      *  saveAsNew=true면 '다른 이름으로 저장'(수정 대신 새 표 생성)을 뜻한다. */
     onSaveComplete?: (name: string, items: WordSearchResultItem[], description?: string, saveAsNew?: boolean) => void;
     onLoad?: () => void;
@@ -49,7 +49,7 @@ export interface WordTableBlockProps {
     editingName?: string;
     /** 지정하면 인쇄하기 왼쪽에 '취소' 버튼을 표시(PagePopup 닫기 등). */
     onCancel?: () => void;
-    /** 전달하면 카드 드래그로 순서 변경 가능 */
+    /** 전달하면 카드 드래그로 순서 변경 가능. 쪽이 나뉘면 같은 쪽 안에서만 옮기며, 자리는 전체 목록 기준이다. */
     onReorder?: (fromIndex: number, toIndex: number) => void;
     /** display 모드에서도 칸 수 조절 허용 */
     showCellCount?: boolean;

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

@@ -1,7 +1,3 @@
-/**
- * barChartData.ts
- * BarChart의 순수 데이터 계층 — 날짜→월/주/일 막대 데이터 집계 (React 무관).
- */
 /** 막대 하나의 데이터 — a/b 두 계열. a === -1 이면 미래(데이터 없음)로 표시하지 않음.
  *  parts: 다계열 stacked용 계열별 값(있으면 a는 합계로 사용). */
 export interface BarData {
@@ -19,7 +15,9 @@ export type MonthBarData = {
     weekly: BarData[];
     daily: BarData[];
 };
-/** 날짜별 카운트 포인트 — a/b 2계열 또는 parts(다계열 stacked, a는 합계) */
+/** 날짜별 카운트 포인트 — a/b 2계열 또는 parts(다계열 stacked, a는 합계).
+ *  `date` 는 **KST 달력 날짜를 기기 달력 자정 Date 로** 옮긴 것: 시각이면 `parseLocalYmd(toKstYmd(createdAt))`,
+ *  서버가 KST 로 집계한 'YYYY-MM-DD' 면 `parseLocalYmd(log_date)`. */
 export interface ChartPoint {
     date: Date;
     a: number;

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

@@ -1,7 +1,11 @@
 /**
  * barChartData.ts
  * BarChart의 순수 데이터 계층 — 날짜→월/주/일 막대 데이터 집계 (React 무관).
+ *
+ * **날은 KST 달력으로 센다.** 칸은 `getFullYear()/getMonth()/getDate()` 로 나누므로 '지금'도 KST 오늘을 기기 달력 Date 로
+ * 옮긴 것(`getTodayKstDate`)을 쓴다 — 전에는 기기 시각이라 해외 기기에서 오늘·이번 주·이번 달이 KST 와 하루 어긋났다.
  */
+import { getTodayKstDate } from '../utils/date';
 /** 해당 월(0-based)의 첫 월요일 날짜(1~7). 예: 2026-05(금요일 시작) → 4 */
 export function firstMondayOfMonth(year, month0) {
     const dow = new Date(year, month0, 1).getDay(); // 0=일 … 6=토
@@ -10,7 +14,7 @@ export function firstMondayOfMonth(year, month0) {
 /** 오늘이 속한 (월키, 주값) 계산 — 진입 시 기본 선택을 오늘 기준으로 맞춤.
  *  월요일 시작 버킷 기준이며, 첫 월요일 이전 날짜는 이전 달 마지막 주에 속한다. */
 export function todayWeekValue() {
-    const now = new Date();
+    const now = getTodayKstDate();
     let y = now.getFullYear(), m0 = now.getMonth(), date = now.getDate();
     if (date < firstMondayOfMonth(y, m0)) {
         const prevLast = new Date(y, m0, 0); // 이전 달 마지막 날
@@ -35,7 +39,7 @@ export function todayWeekValue() {
  * 다음 달의 오늘 뒤 날은 세지 않는다. 일별(`daily`)은 그 달 날만이다.
  */
 export function buildMonthChartData(points) {
-    const now = new Date();
+    const now = getTodayKstDate();
     const curKey = `${now.getFullYear()}년 ${now.getMonth() + 1}월`;
     const 달키 = (y, m0) => `${y}년 ${m0 + 1}월`;
     const byMonth = new Map();
@@ -142,7 +146,7 @@ export function buildMonthChartData(points) {
 }
 // 드롭다운에 노출할 월 옵션 (2024년 1월 ~ 현재, 최신순)
 function genMonthOptions() {
-    const now = new Date();
+    const now = getTodayKstDate();
     const curY = now.getFullYear();
     const curM = now.getMonth() + 1;
     const opts = [];

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

@@ -88,8 +88,21 @@ export interface BarChartProps {
     /** CSS 격자 칸 안에 세운다 — 아래 여백·최소 폭을 풀고 막대를 카드 바닥에 맞춘다. ChartSection `inGrid` 참고. */
     inGrid?: boolean;
 }
-/** 현재 컨트롤 선택(주/월)의 날짜 범위 — 상세보기(기간별 리스트)용 */
-export declare function getControlDateRange(control: BarChartControl): {
+/** @public getControlDateRange 의 결과 — 기간의 첫날 00:00 KST ~ 끝날 23:59:59.999 KST 순간과, 그 두 날의 KST 달력 날짜 */
+export interface ControlDateRange {
+    /** 첫날 00:00:00.000 KST 순간 — 서버에 물을 때 `from.toISOString()` */
     from: Date;
+    /** 끝날 23:59:59.999 KST 순간 */
     to: Date;
-};
+    /** 첫날 KST 'YYYY-MM-DD' — 이름표·달력 셈은 `parseLocalYmd(fromYmd)` 로(순간 `from` 을 기기 getter 로 읽으면 해외에서 하루 어긋난다) */
+    fromYmd: string;
+    /** 끝날 KST 'YYYY-MM-DD' */
+    toYmd: string;
+}
+/**
+ * 현재 컨트롤 선택(주/월)의 기간 — 상세보기(기간별 리스트)용. **KST 의 날로 자른다**(해외 기기도 같은 기간).
+ *
+ * @param offset 몇 기간 앞·뒤인가 — `-1` 이면 앞 달 한 달(달력 달 그대로, 30일 앞이 아니다) · 앞 주 한 주.
+ * @public
+ */
+export declare function getControlDateRange(control: BarChartControl, offset?: number): ControlDateRange;

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

@@ -1,23 +1,37 @@
 import { firstMondayOfMonth } from './barChartData';
-/** 현재 컨트롤 선택(주/월)의 날짜 범위 — 상세보기(기간별 리스트)용 */
-export function getControlDateRange(control) {
+import { getTodayKst, getTodayKstDate, kstStartOfDay } from '../utils/date';
+const ymdOf = (y, m0, d) => {
+    const t = new Date(Date.UTC(y, m0, d));
+    return `${t.getUTCFullYear()}-${String(t.getUTCMonth() + 1).padStart(2, '0')}-${String(t.getUTCDate()).padStart(2, '0')}`;
+};
+const 범위 = (y, m0, 첫날, 날수) => ({
+    from: kstStartOfDay(y, m0, 첫날),
+    // 끝은 그날의 **마지막 밀리초까지** — 23:59:59.000 이면 마지막 999ms 에 남은 기록이 목록에서 빠졌다
+    to: new Date(kstStartOfDay(y, m0, 첫날 + 날수).getTime() - 1),
+    fromYmd: ymdOf(y, m0, 첫날),
+    toYmd: ymdOf(y, m0, 첫날 + 날수 - 1),
+});
+/**
+ * 현재 컨트롤 선택(주/월)의 기간 — 상세보기(기간별 리스트)용. **KST 의 날로 자른다**(해외 기기도 같은 기간).
+ *
+ * @param offset 몇 기간 앞·뒤인가 — `-1` 이면 앞 달 한 달(달력 달 그대로, 30일 앞이 아니다) · 앞 주 한 주.
+ * @public
+ */
+export function getControlDateRange(control, offset = 0) {
     if (control.period === 'month') {
         const m = control.monthRange.match(/^(\d+)년 (\d+)월$/);
-        const now = new Date();
-        const y = m ? Number(m[1]) : now.getFullYear();
-        const mo = m ? Number(m[2]) : now.getMonth() + 1;
-        // 끝은 그날의 **마지막 밀리초까지** — 23:59:59.000 이면 마지막 999ms 에 남은 기록이 목록에서 빠졌다
-        return { from: new Date(y, mo - 1, 1, 0, 0, 0), to: new Date(y, mo, 0, 23, 59, 59, 999) };
+        const today = getTodayKstDate();
+        const y = m ? Number(m[1]) : today.getFullYear();
+        const m0 = (m ? Number(m[2]) : today.getMonth() + 1) - 1 + offset;
+        const 날수 = new Date(Date.UTC(y, m0 + 1, 0)).getUTCDate();
+        return 범위(y, m0, 1, 날수);
     }
     const opt = control.weekRanges.find(o => o.value === control.weekRange);
     if (!opt) {
         const n = new Date();
-        return { from: n, to: n };
+        const ymd = getTodayKst();
+        return { from: n, to: n, fromYmd: ymd, toYmd: ymd };
     }
     const firstMon = firstMondayOfMonth(opt.year, opt.month - 1);
-    const monday = new Date(opt.year, opt.month - 1, firstMon + opt.week * 7, 0, 0, 0);
-    const sunday = new Date(monday);
-    sunday.setDate(monday.getDate() + 6);
-    sunday.setHours(23, 59, 59, 999);
-    return { from: monday, to: sunday };
+    return 범위(opt.year, opt.month - 1, firstMon + (opt.week + offset) * 7, 7);
 }

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

@@ -142,6 +142,7 @@ export { default as BarChart, BarChartControls } from './components/BarChart';
 export { useBarChartControl } from './components/useBarChartControl';
 export { buildMonthChartData } from './components/barChartData';
 export { getControlDateRange } from './components/barChartTypes';
+export type { ControlDateRange } from './components/barChartTypes';
 export type { BarChartProps, BarChartControl, BarChartSize, BarData, MonthBarData, ChartPoint } from './components/BarChart';
 export { default as RingChart } from './components/RingChart';
 export type { RingChartProps, RingChartSize, RingChartSegment } from './components/RingChart';

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

@@ -0,0 +1,4 @@
+/** 창 판과, 그 창이 열릴 때 포커스였던 요소를 적는다 */
+export declare function rememberFocusReturn(panel: Element | null, previouslyFocused: HTMLElement | null): void;
+/** 실제로 돌려줄 곳 — 문서에 붙어 있으면 그대로, 떼어졌으면 그것을 품었던 창이 적어 둔 곳을 따라간다 */
+export declare function resolveFocusReturn(previouslyFocused: HTMLElement | null): HTMLElement | null;

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

@@ -0,0 +1,27 @@
+/**
+ * 창(Popup·Dialog·TrainingPagePopup)이 닫힐 때 포커스를 돌려줄 곳 — 창끼리 한 표를 쓴다.
+ *
+ * 창은 열릴 때 그때 포커스였던 요소를 기억했다가 닫힐 때 돌려준다. 그런데 **닫으면서 다음 창을 여는** 흐름
+ * (미리보기 → 삭제 확인)에서는 확인 창이 기억한 것이 미리보기 안의 삭제 단추이고, 그 단추는 260ms 뒤
+ * 미리보기와 함께 사라진다. 확인 창을 닫으면 떼어진 단추에 focus() 해 아무 일도 없이 body 에 떨어졌다.
+ * 각 창의 판(panel) → 그 창이 돌려줄 곳을 적어 두고, 돌려줄 곳이 떼어졌으면 그것을 품었던 창의 돌려줄 곳을 따라 올라간다.
+ */
+const 돌아갈곳표 = new WeakMap();
+/** 창 판과, 그 창이 열릴 때 포커스였던 요소를 적는다 */
+export function rememberFocusReturn(panel, previouslyFocused) {
+    if (panel)
+        돌아갈곳표.set(panel, previouslyFocused);
+}
+/** 실제로 돌려줄 곳 — 문서에 붙어 있으면 그대로, 떼어졌으면 그것을 품었던 창이 적어 둔 곳을 따라간다 */
+export function resolveFocusReturn(previouslyFocused) {
+    let 대상 = previouslyFocused;
+    for (let 번 = 0; 대상 && !대상.isConnected && 번 < 10; 번++) {
+        let 창 = 대상;
+        while (창 && !돌아갈곳표.has(창))
+            창 = 창.parentElement;
+        if (!창)
+            return 대상;
+        대상 = 돌아갈곳표.get(창) ?? null;
+    }
+    return 대상;
+}

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

@@ -47,9 +47,12 @@ export function useWordMeanings(rows, fetchMeanings) {
                 if (row.Meaning)
                     memCache.set(meaningKey(row.Word, row.Homonum ?? undefined), row.Meaning);
             }
-            for (const k of missing)
-                if (!memCache.has(k))
-                    noMeaning.add(k);
+            /* 한 줄도 못 받았으면 '뜻 없음' 으로 굳히지 않는다 — 조회 함수는 실패를 빈 배열로 돌려주는 약속이라, 잠깐 끊긴 망이
+               그 쪽 낱말들을 새로고침 전까지 '뜻 없음' 으로 묶었다. 받은 게 있으면 그 응답에 빠진 낱말만 없는 것으로 본다. */
+            if (got.length > 0)
+                for (const k of missing)
+                    if (!memCache.has(k))
+                        noMeaning.add(k);
             if (cancelled || got.length === 0)
                 return;
             setFetched(v => v + 1);

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

@@ -11,9 +11,9 @@ export interface WordFilterSnapshot {
     sameStructureOnly: boolean;
     phonemeView: 'char' | 'pron' | 'direct';
     gradeFilter: string[];
-    /** 품사 필터. 없으면(예전에 뜬 스냅샷) 되돌릴 때 지금 값을 그대로 둔다. */
+    /** 품사 필터 — 고정 코드(noun·verb·modifier). 라벨(옛 스냅샷)도 받는다. 없으면 되돌릴 때 지금 값을 그대로 둔다. */
     posFilter?: string[];
-    /** 어종 필터. 없으면(예전에 뜬 스냅샷) 되돌릴 때 지금 값을 그대로 둔다. */
+    /** 어종 필터 — 고정 코드(native·sino·foreign·mixed). 라벨(옛 스냅샷)도 받는다. 없으면 되돌릴 때 지금 값을 그대로 둔다. */
     wordTypeFilter?: string[];
 }
 /**