@ihabdevteam/core 0.150.0 → 0.152.0

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

@@ -16,12 +16,27 @@
  * 알게 되므로 몇 건을 뺐는지 함께 돌려준다.
  */
 import { 한글순 } from '../../utils/textSort';
+/** 같은 시각 두 행의 차례 — 둘 다 id 가 있을 때만 가린다(숫자는 수 크기, 그 밖은 글자 사전순). 못 가리면 0. */
+function 같은시각차례(a, b) {
+    if (a == null || b == null || a === '' || b === '')
+        return 0;
+    if (typeof a === 'number' && typeof b === 'number')
+        return a - b;
+    // 기계 열쇠(행 id)라 로케일 없이 부호 단위로 견준다 — 사람이 읽는 글자가 아니다
+    const x = String(a), y = String(b);
+    return Number(x > y) - Number(x < y);
+}
 /**
  * @public 문항별로 모아 **약한 것부터** 늘어놓는다.
  *
  * 정렬은 세 겹이다. 정답률이 낮은 것이 먼저이되, **같은 정답률이면 여러 번 푼 것을
  * 앞에 둔다** — 한 번 틀린 것과 다섯 번 내리 틀린 것은 무게가 다르다. 그래도 같으면
  * 글자순으로 못 박는다(그러지 않으면 다시 읽을 때마다 차례가 흔들려 보던 줄을 놓친다).
+ *
+ * **"최근"(latestCorrect·latestAt·lastSelected·setIds 앞자리)은 `answeredAt` 으로 가린다.** 시각이 같은 행끼리는
+ * 둘 다 `id` 가 있으면 `id` 가 큰 쪽(숫자는 수 크기, 글은 사전순)이 최근이고, 그렇지 않으면 **넘어온 배열에서
+ * 뒤에 있는 쪽**이 최근이다 — 즉 `id` 없이 넘길 때는 **시간순(옛것 먼저)** 으로 넘겨야 같은 시각의 앞뒤가 맞다.
+ * (최신 먼저 넘기면 같은 시각 행의 최근이 뒤집힌다. 시각이 다른 행은 차례와 상관없이 맞다.)
  */
 export function summarizeMisses(records) {
     const 모음 = new Map();
@@ -29,7 +44,10 @@ export function summarizeMisses(records) {
     let skippedNoTitle = 0;
     /* 최근 것을 알려면 시간순으로 훑어야 한다. 서버는 최신순으로 주지만 여기서 다시
        정렬한다 — 부르는 쪽의 차례에 기대면 그쪽이 바뀔 때 조용히 어긋난다. */
-    const 시간순 = [...records].sort((a, b) => a.answeredAt.localeCompare(b.answeredAt));
+    const 시간순 = records
+        .map((r, 자리) => ({ r, 자리 }))
+        .sort((a, b) => a.r.answeredAt.localeCompare(b.r.answeredAt) || 같은시각차례(a.r.id, b.r.id) || a.자리 - b.자리)
+        .map(x => x.r);
     for (const r of 시간순) {
         // 요약·시간 행은 문항이 아니다. 틀림으로 세면 한 판마다 오답이 늘어난다.
         if (r.isCorrect == null)

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

@@ -0,0 +1,13 @@
+/**
+ * 훈련 창 안에서 여는 **떠 있는 창**(훈련 설정·문장 미리보기)에 초점을 넣고, 닫으면 연 단추로 돌려준다.
+ *
+ * 떠 있는 창(Tooltip)은 document.body 로 포털된다 — 훈련 판(panel) 밖이다. 판의 Tab 가둠(useFocusTrap)은
+ * 판 안의 칸만 돌아서, 창을 열어도 Tab 으로는 끝내 닿지 못했고(판 끝에서 첫 칸으로 되감김) 판의 aria-modal 이
+ * 낭독기에게서 창을 가렸다. 열릴 때 초점을 창의 첫 칸으로 넣으면 — 판 가둠은 판 안 keydown 만 들으므로 끼어들지
+ * 않고, 창 안 Tab 은 Tooltip 이 스스로 가두며, 낭독기는 초점이 든 창을 읽는다. 공용 파일은 건드리지 않는다.
+ *
+ * @param open     창이 열려 있나
+ * @param findRoot 열린 창의 뿌리(.tooltip-content)를 찾는다 — 포털이라 ref 대신 찾는다
+ * @param returnTo 닫힐 때 초점을 돌려줄 곳(연 단추). 초점이 이미 다른 칸으로 옮겨 갔으면 빼앗지 않는다.
+ */
+export declare function useFloatingFocus(open: boolean, findRoot: () => HTMLElement | null, returnTo: () => HTMLElement | null): void;

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

@@ -0,0 +1,59 @@
+'use client';
+import { useEffect, useRef } from 'react';
+import { FOCUSABLE_SELECTOR } from '../../hooks/useFocusTrap';
+/**
+ * 훈련 창 안에서 여는 **떠 있는 창**(훈련 설정·문장 미리보기)에 초점을 넣고, 닫으면 연 단추로 돌려준다.
+ *
+ * 떠 있는 창(Tooltip)은 document.body 로 포털된다 — 훈련 판(panel) 밖이다. 판의 Tab 가둠(useFocusTrap)은
+ * 판 안의 칸만 돌아서, 창을 열어도 Tab 으로는 끝내 닿지 못했고(판 끝에서 첫 칸으로 되감김) 판의 aria-modal 이
+ * 낭독기에게서 창을 가렸다. 열릴 때 초점을 창의 첫 칸으로 넣으면 — 판 가둠은 판 안 keydown 만 들으므로 끼어들지
+ * 않고, 창 안 Tab 은 Tooltip 이 스스로 가두며, 낭독기는 초점이 든 창을 읽는다. 공용 파일은 건드리지 않는다.
+ *
+ * @param open     창이 열려 있나
+ * @param findRoot 열린 창의 뿌리(.tooltip-content)를 찾는다 — 포털이라 ref 대신 찾는다
+ * @param returnTo 닫힐 때 초점을 돌려줄 곳(연 단추). 초점이 이미 다른 칸으로 옮겨 갔으면 빼앗지 않는다.
+ */
+export function useFloatingFocus(open, findRoot, returnTo) {
+    const findRootRef = useRef(findRoot);
+    const returnToRef = useRef(returnTo);
+    useEffect(() => { findRootRef.current = findRoot; returnToRef.current = returnTo; });
+    useEffect(() => {
+        if (!open || typeof document === 'undefined')
+            return;
+        let raf = null;
+        let 남은틀 = 10; // Tooltip 은 위치를 잰 뒤에야 보인다 — 보이기 전 focus() 는 먹지 않아 몇 틀 다시 해 본다
+        const 넣기 = () => {
+            raf = null;
+            const root = findRootRef.current();
+            const 첫칸 = root
+                ? Array.from(root.querySelectorAll(FOCUSABLE_SELECTOR)).find((el) => !el.closest('[aria-hidden="true"]'))
+                : undefined;
+            if (첫칸) {
+                try {
+                    첫칸.focus();
+                }
+                catch (e) { /* 떼어진 노드 */ }
+                if (document.activeElement === 첫칸)
+                    return;
+            }
+            if (--남은틀 > 0)
+                raf = requestAnimationFrame(넣기);
+        };
+        raf = requestAnimationFrame(넣기);
+        return () => {
+            if (raf !== null)
+                cancelAnimationFrame(raf);
+            // 닫혔다(또는 떠난다) — 초점이 창과 함께 사라져 body 로 떨어졌을 때만 연 단추로 돌려준다
+            const 지금 = document.activeElement;
+            if (!지금 || 지금 === document.body || !document.contains(지금) || !!지금.closest('.tooltip-content')) {
+                const 단추 = returnToRef.current();
+                if (단추) {
+                    try {
+                        단추.focus();
+                    }
+                    catch (e) { /* 떼어진 노드 */ }
+                }
+            }
+        };
+    }, [open]);
+}

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

@@ -215,25 +215,34 @@ export function useNoiseFade({ noisePlayer, audioRef, playbackStateRef, }) {
     }, [fadeOutNoise, noiseInUse, audioRef, playbackStateRef]);
     // 탭 백그라운드 전환 시 소음 즉시 정지 — 백그라운드 탭에서는 requestAnimationFrame이
     // 멈추거나 크게 스로틀돼 fadeOutNoise의 볼륨 램프가 완주하지 못할 수 있어, 페이드 없이
-    // 바로 pause한다. 탭 복귀 시 자동 재개는 하지 않는다 — 메인 오디오가 재생 중이면 기존
-    // 소음 설정 useEffect(레벨/타입 변경 등)가 다시 fadeInNoise를 트리거하고, 아니라면
-    // 사용자가 의도적으로 멈춘 것과 구분이 안 되므로 그대로 둔다.
+    // 바로 pause한다.
+    /* 탭으로 돌아왔을 때 **문장이 재생 중이고 소음 설정이 켜져 있으면** 소음을 다시 켠다. 전에는 자동 재개를 안 해서
+       문장은 계속 나오는데 소음만 꺼진 채로 남았다(설정 효과는 설정이 바뀌어야 다시 돈다 — 기대던 전제가 틀렸다).
+       문장이 멈춰 있으면(사용자가 멈춘 것) 켜지 않는다. 볼륨·켜짐은 지금 설정(noiseSettingsRef)으로 본다. */
     useEffect(() => {
         const handleVisibilityChange = () => {
-            if (!document.hidden)
-                return;
             const noiseEl = noiseAudioRef.current;
-            if (noiseEl && !noiseEl.paused) {
-                cancelNoiseFade();
-                try {
-                    noiseEl.pause();
+            if (document.hidden) {
+                if (noiseEl && !noiseEl.paused) {
+                    cancelNoiseFade();
+                    try {
+                        noiseEl.pause();
+                    }
+                    catch (e) { }
                 }
-                catch (e) { }
+                return;
             }
+            if (!noiseEl || !noiseEl.paused)
+                return;
+            const a = audioRef.current;
+            const mainPlaying = (!!a && !a.paused && !a.ended) || playbackStateRef.current === 'playing';
+            const 지금 = noiseSettingsRef.current;
+            if (mainPlaying && 지금?.enabled && 지금.volume > 0)
+                fadeInNoise(지금.volume);
         };
         document.addEventListener('visibilitychange', handleVisibilityChange);
         return () => document.removeEventListener('visibilitychange', handleVisibilityChange);
-    }, [cancelNoiseFade]);
+    }, [cancelNoiseFade, fadeInNoise, audioRef, playbackStateRef]);
     // noiseSettingsRef 최신화 (재생 이벤트 핸들러 클로저에서 사용)
     useEffect(() => {
         noiseSettingsRef.current = noisePlayer

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

@@ -1,23 +1,5 @@
 import { type RefObject } from 'react';
 import type { Source } from './trainingStepAudioPlayerTypes';
-/**
- * 재생 중 진행 표시를 매 프레임 갱신한다.
- *
- * 진행 마커와 파형의 채워진 부분은 **React 를 거치지 않고** DOM 스타일을 직접 쓴다.
- * 초당 예순 번 상태를 바꾸면 그때마다 컴포넌트 전체가 다시 그려져서, 파형 바 300개가
- * 매 프레임 재생성된다. 눈에 보이는 것은 두 값(마커 위치, 파형 진행률)뿐이라 그 둘만
- * 직접 만진다.
- *
- * **모아 놓은 진짜 이유는 멈추는 쪽이다.** 이 프레임 사슬은 재생·일시정지·종료·트랙
- * 이동·화면 떠나기 — 다섯 갈래에서 멈춰야 하는데, 원래는 그 취소 코드가 **아홉 군데**에
- * 똑같이 흩어져 있었다.
- *
- *     if (rafRef.current) { cancelAnimationFrame(rafRef.current); rafRef.current = null }
- *
- * 한 군데를 빠뜨리면 사슬이 살아남아 이미 끝난 소리의 진행률을 계속 그린다 — 마커가
- * 혼자 움직이는 상태다. 오류도 안 뜨고, 다음 재생이 시작되면 겹쳐서 두 배 속도로 움직인다.
- * `start()` / `stop()` 둘로 줄인다.
- */
 export declare function useProgressTicker({ audioRef, fillRef, waveProgressRef, sourcesRef, currentIndexRef, }: {
     audioRef: RefObject<HTMLAudioElement | null>;
     /** 진행 마커 — `left` 를 퍼센트로 민다 */

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

@@ -19,6 +19,30 @@ import { progressOf } from './audioPlaybackRules';
  * 혼자 움직이는 상태다. 오류도 안 뜨고, 다음 재생이 시작되면 겹쳐서 두 배 속도로 움직인다.
  * `start()` / `stop()` 둘로 줄인다.
  */
+/**
+ * `<audio>` 가 알려 주는 총 길이(초). 유한한 양수면 그것, Infinity·NaN(스트리밍·길이 머리 없음)이면
+ * 되감을 수 있는 구간(seekable)의 끝을 총 길이로 본다. 그것도 없으면 `null` — 진행을 모른다.
+ * 요소가 없으면 0(그릴 것 없음, 전과 같게 마커 0).
+ */
+function audioDurationOf(a) {
+    if (!a)
+        return 0;
+    const d = a.duration;
+    if (Number.isFinite(d) && d > 0)
+        return d;
+    if (d === 0)
+        return 0;
+    try {
+        const s = a.seekable;
+        if (s && s.length > 0) {
+            const 끝 = s.end(s.length - 1);
+            if (Number.isFinite(끝) && 끝 > 0)
+                return 끝;
+        }
+    }
+    catch { /* seekable 을 못 읽는 환경 */ }
+    return null;
+}
 export function useProgressTicker({ audioRef, fillRef, waveProgressRef, sourcesRef, currentIndexRef, }) {
     const rafRef = useRef(null);
     const stop = useCallback(() => {
@@ -34,21 +58,40 @@ export function useProgressTicker({ audioRef, fillRef, waveProgressRef, sourcesR
         const step = () => {
             try {
                 const a = audioRef.current;
-                const pos = progressOf({
-                    currentTime: a && typeof a.currentTime === 'number' ? a.currentTime : 0,
-                    sources: sourcesRef.current,
-                    index: currentIndexRef.current,
-                    audioDuration: a && a.duration ? a.duration : 0,
-                });
-                try {
-                    if (fillRef.current)
-                        fillRef.current.style.left = `${pos * 100}%`;
+                const 트랙 = Array.isArray(sourcesRef.current) ? sourcesRef.current[currentIndexRef.current || 0] : undefined;
+                const 트랙길이알아 = !!트랙 && Number.isFinite(트랙.duration) && (트랙.duration ?? 0) > 0;
+                // 트랙 길이를 알면 progressOf 가 그것을 쓴다 — <audio> 길이는 모를 때만 본다
+                const 총길이 = 트랙길이알아 ? 0 : audioDurationOf(a);
+                const fill = fillRef.current;
+                if (총길이 === null) {
+                    /* 길이를 모른다(스트리밍 등으로 duration 이 Infinity·NaN 이고 되감을 수 있는 끝도 없다) —
+                       마커를 0 에 붙여 두면 "안 움직이는 재생"으로 읽힌다. 진행을 모르니 마커를 숨긴다. */
+                    try {
+                        if (fill && fill.style.visibility !== 'hidden')
+                            fill.style.visibility = 'hidden';
+                    }
+                    catch { /* 떼어진 노드 */ }
                 }
-                catch { /* 떼어진 노드 */ }
-                try {
-                    waveProgressRef.current?.style.setProperty('--progress', String(pos));
+                else {
+                    const pos = progressOf({
+                        currentTime: a && typeof a.currentTime === 'number' ? a.currentTime : 0,
+                        sources: sourcesRef.current,
+                        index: currentIndexRef.current,
+                        audioDuration: 총길이,
+                    });
+                    try {
+                        if (fill) {
+                            if (fill.style.visibility)
+                                fill.style.visibility = '';
+                            fill.style.left = `${pos * 100}%`;
+                        }
+                    }
+                    catch { /* 떼어진 노드 */ }
+                    try {
+                        waveProgressRef.current?.style.setProperty('--progress', String(pos));
+                    }
+                    catch { /* 위와 같다 */ }
                 }
-                catch { /* 위와 같다 */ }
             }
             catch { /* 한 프레임이 실패해도 사슬은 이어 간다 */ }
             rafRef.current = requestAnimationFrame(step);
@@ -59,8 +102,10 @@ export function useProgressTicker({ audioRef, fillRef, waveProgressRef, sourcesR
     const settleTo = useCallback((pos) => {
         stop();
         try {
-            if (fillRef.current)
+            if (fillRef.current) {
+                fillRef.current.style.visibility = '';
                 fillRef.current.style.left = `${pos * 100}%`;
+            }
         }
         catch { /* 떼어진 노드 */ }
         try {

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

@@ -25,7 +25,7 @@ export declare function useTTSPlayback({ ttsText, playbackRate, mainVolume, fill
     onDoneRef: RefObject<((ok?: boolean) => void) | undefined>;
     handleEndRef: RefObject<(() => void) | null>;
 }): {
-    startTTS: (text?: string) => void;
+    startTTS: (text?: string | string[]) => void;
     stopTTS: () => void;
 };
 export {};

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

@@ -50,11 +50,19 @@ export function useTTSPlayback({ ttsText, playbackRate, mainVolume, fillRef, wav
             return 1200;
         }
     };
+    /**
+     * 말하기 시작. `text` 를 주면 설정(ttsText)보다 이긴다.
+     *
+     * - 글이 배열이면 **차례로 모두** 말하고 마지막 문장이 끝난 뒤에 한 번 끝 처리(handleEnd)를 부른다.
+     *   전에는 첫 문장만 말하고 문항이 끝났다(리졸버가 없거나 실패한 여러 문장 훈련).
+     * - 브라우저에 음성 합성이 없으면 곧바로 `onDone(false)` — **소리를 못 냈다**고 알린다.
+     *   전에는 `onDone(true)` 라 들은 것으로 셌다. 훈련 흐름(TrainingPagePopup)은 false 에도 다음 단계로 간다.
+     */
     const startTTS = useCallback((text) => {
         if (typeof window === 'undefined' || !window.speechSynthesis) {
             try {
                 if (typeof onDoneRef.current === 'function')
-                    onDoneRef.current(true);
+                    onDoneRef.current(false);
             }
             catch (e) { }
             return;
@@ -67,17 +75,11 @@ export function useTTSPlayback({ ttsText, playbackRate, mainVolume, fillRef, wav
             }
             catch (e) { }
             const rawTts = text ?? ttsText;
-            const t = (Array.isArray(rawTts) ? rawTts[0] ?? '' : rawTts) || '';
-            const utt = new SpeechSynthesisUtterance(t);
-            try {
-                utt.rate = Math.max(0.3, Math.min(3, playbackRate));
-            }
-            catch (e) { }
-            try {
-                utt.volume = Math.max(0, Math.min(1, mainVolume));
-            }
-            catch (e) { }
-            ttsEstimatedDurationRef.current = estimateTTSDuration(t, utt.rate || 1);
+            const 문장들 = (Array.isArray(rawTts) ? rawTts.filter((s) => !!s) : [rawTts || '']);
+            if (문장들.length === 0)
+                문장들.push('');
+            const rate = Math.max(0.3, Math.min(3, playbackRate));
+            ttsEstimatedDurationRef.current = 문장들.reduce((합, s) => 합 + estimateTTSDuration(s, rate || 1), 0);
             ttsStartRef.current = performance.now();
             setProgress(0);
             setPlaybackState('playing');
@@ -108,7 +110,7 @@ export function useTTSPlayback({ ttsText, playbackRate, mainVolume, fillRef, wav
                 }
                 catch (e) { }
             };
-            utt.onend = () => {
+            const 끝처리 = () => {
                 if (myToken !== ttsTokenRef.current)
                     return;
                 try {
@@ -131,23 +133,52 @@ export function useTTSPlayback({ ttsText, playbackRate, mainVolume, fillRef, wav
                 }
                 catch (e) { }
             };
-            /* 합성이 실패하면(synthesis-failed·not-allowed·language-unavailable) end 없이 error 만 온다 — 끝난 것과 같이 정리한다.
-               전에는 재생 상태·소음이 그대로 남고 handleEnd·onDone 이 안 불려 문항이 넘어가지 않았다. 정지·다시 시작이 올린 번호의
-               error(취소)는 위 onend 와 같이 넘긴다. */
-            utt.onerror = () => { utt.onend?.(new Event('end')); };
-            utt.onstart = () => {
+            const 말하기 = (i) => {
+                const utt = new SpeechSynthesisUtterance(문장들[i]);
                 try {
-                    if (ttsRafRef.current) {
-                        cancelAnimationFrame(ttsRafRef.current);
-                        ttsRafRef.current = null;
-                    }
-                    ttsRafRef.current = requestAnimationFrame(tick);
+                    utt.rate = rate;
                 }
                 catch (e) { }
-            };
-            try {
+                try {
+                    utt.volume = Math.max(0, Math.min(1, mainVolume));
+                }
+                catch (e) { }
+                utt.onend = () => {
+                    if (myToken !== ttsTokenRef.current)
+                        return;
+                    // 남은 문장이 있으면 이어 말한다 — 진행 표시는 전체 추정 길이로 계속 흐른다
+                    if (i < 문장들.length - 1) {
+                        try {
+                            말하기(i + 1);
+                        }
+                        catch (e) {
+                            끝처리();
+                        }
+                        return;
+                    }
+                    끝처리();
+                };
+                /* 합성이 실패하면(synthesis-failed·not-allowed·language-unavailable) end 없이 error 만 온다 — 끝난 것과 같이 정리한다.
+                   전에는 재생 상태·소음이 그대로 남고 handleEnd·onDone 이 안 불려 문항이 넘어가지 않았다. 정지·다시 시작이 올린 번호의
+                   error(취소)는 onend 와 같이 넘긴다. 중간 문장이 실패하면 남은 문장도 같은 까닭으로 실패하기 쉬워 거기서 끝낸다. */
+                utt.onerror = () => { 끝처리(); };
+                utt.onstart = () => {
+                    if (i > 0)
+                        return; // 진행 사슬은 첫 문장에서 한 번만 건다
+                    try {
+                        if (ttsRafRef.current) {
+                            cancelAnimationFrame(ttsRafRef.current);
+                            ttsRafRef.current = null;
+                        }
+                        ttsRafRef.current = requestAnimationFrame(tick);
+                    }
+                    catch (e) { }
+                };
                 말했나Ref.current = true;
                 synth.speak(utt);
+            };
+            try {
+                말하기(0);
             }
             catch (e) {
                 try {

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

@@ -15,6 +15,9 @@
  *  3. **트랙이 바뀌면 다시 기다려야 한다** — 이전 트랙의 '준비됨'을 물려받으면 안 된다.
  *     그래서 트랙을 갈아 끼우는 자리마다 `markNotReady()` 를 부른다.
  *
+ * `waitForReady()` 는 **`true`(계속 재생해도 된다)** 또는 **`false`(화면을 떠났다 — 재생을 이어 가지 말 것)** 로 풀린다.
+ * 준비 신호·상한·그릴 파형 없음은 모두 `true` 다.
+ *
  * 원래 `TrainingStepAudioPlayer` 안에 흩어져 있었다. ref 둘과 함수 둘, 그리고
  * `waveReadyRef.current = false` 가 **일곱 군데**에 직접 흩어져 있어서, 새 재생 경로를
  * 추가하는 사람이 그 한 줄을 빠뜨리기 쉬웠다. 이름을 준 함수 하나로 모은다.
@@ -31,6 +34,6 @@ timeoutMs, }: {
     timeoutMs?: number;
 }): {
     onReadyChange: (ready: boolean) => void;
-    waitForReady: () => Promise<void>;
+    waitForReady: () => Promise<boolean>;
     markNotReady: () => void;
 };

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

@@ -17,6 +17,9 @@ import { useCallback, useEffect, useRef } from 'react';
  *  3. **트랙이 바뀌면 다시 기다려야 한다** — 이전 트랙의 '준비됨'을 물려받으면 안 된다.
  *     그래서 트랙을 갈아 끼우는 자리마다 `markNotReady()` 를 부른다.
  *
+ * `waitForReady()` 는 **`true`(계속 재생해도 된다)** 또는 **`false`(화면을 떠났다 — 재생을 이어 가지 말 것)** 로 풀린다.
+ * 준비 신호·상한·그릴 파형 없음은 모두 `true` 다.
+ *
  * 원래 `TrainingStepAudioPlayer` 안에 흩어져 있었다. ref 둘과 함수 둘, 그리고
  * `waveReadyRef.current = false` 가 **일곱 군데**에 직접 흩어져 있어서, 새 재생 경로를
  * 추가하는 사람이 그 한 줄을 빠뜨리기 쉬웠다. 이름을 준 함수 하나로 모은다.
@@ -38,28 +41,34 @@ timeoutMs = 2500, }) {
         const 기다리던것 = resolversRef.current;
         resolversRef.current = [];
         for (const 깨우기 of 기다리던것)
-            깨우기();
+            깨우기(true);
     }, []);
     /** 새 트랙을 물렸다 — 이전 트랙의 '준비됨'을 물려받지 않는다 */
     const markNotReady = useCallback(() => { readyRef.current = false; }, []);
+    /** 파형이 준비되면(또는 상한이 지나면) `true`, 기다리는 사이 화면을 떠나면 `false` 로 풀린다. */
     const waitForReady = useCallback(() => {
         // 그릴 파형이 없으면 기다릴 것도 없다
         if (!showSoundWaveForm && !showNoiseWaveForm)
-            return Promise.resolve();
+            return Promise.resolve(true);
         if (readyRef.current)
-            return Promise.resolve();
+            return Promise.resolve(true);
         return new Promise((resolve) => {
-            const timer = setTimeout(resolve, timeoutMs);
-            resolversRef.current.push(() => { clearTimeout(timer); resolve(); });
+            const 풀기 = (계속) => {
+                clearTimeout(timer);
+                resolversRef.current = resolversRef.current.filter((r) => r !== 풀기);
+                resolve(계속);
+            };
+            const timer = setTimeout(() => 풀기(true), timeoutMs);
+            resolversRef.current.push(풀기);
         });
     }, [showSoundWaveForm, showNoiseWaveForm, timeoutMs]);
-    /* 화면을 떠날 때 기다리던 것들을 놓아 준다. 안 그러면 상한 타이머가 살아남아
-       이미 사라진 화면의 재생 흐름을 뒤늦게 깨운다. */
+    /* 화면을 떠날 때 기다리던 것들을 `false`(취소)로 놓아 준다. 매달린 약속·상한 타이머를 남기지 않되,
+       `true` 로 풀면 부르는 쪽이 사라진 화면의 재생을 이어 갔다(떼어진 <audio> 에 play). 부르는 쪽은 false 면 멈춘다. */
     useEffect(() => () => {
         const 남은것 = resolversRef.current;
         resolversRef.current = [];
         for (const 깨우기 of 남은것)
-            깨우기();
+            깨우기(false);
     }, []);
     return { onReadyChange, waitForReady, markNotReady };
 }

package/dist/packages/core/src/components/UpdateAlert.css

@@ -1,6 +1,7 @@
 .update-alert {
   position: fixed;
-  top: 16px;
+  /* 함께 뜬 다른 알림 자리 아래로 비킨다 — updateAlertStack.ts 가 앞 자리들의 높이를 넣는다 */
+  top: calc(16px + var(--update-alert-stack-offset, 0px));
   right: 16px;
   z-index: var(--z-alert);
   width: 380px;
@@ -27,7 +28,7 @@
  */
 .update-alert-stack {
   position: fixed;
-  top: 16px;
+  top: calc(16px + var(--update-alert-stack-offset, 0px));
   right: 16px;
   z-index: var(--z-alert);
   display: flex;
@@ -39,6 +40,7 @@
 /* relative — 흐름 배치로 돌리되 닫기 버튼(absolute)의 기준은 낱장으로 남긴다 */
 .update-alert-stack .update-alert {
   position: relative;
+  top: auto;
   z-index: auto;
 }
 

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

@@ -1,4 +1,4 @@
-import type { ReactNode } from 'react';
+import { type ReactNode } from 'react';
 import './UpdateAlert.css';
 /** @public */
 export interface UpdateAlertProps {
@@ -17,6 +17,8 @@ export interface UpdateAlertProps {
  *
  * 여러 장을 동시에 띄우려면 `.update-alert-stack`으로 감싼다 — 낱장은 스스로
  * fixed로 붙지만 스택 안에서는 흐름 배치가 되어 아래로 쌓인다.
+ * 따로 놓인 낱장과 스택(또는 낱장 여럿)이 함께 뜨면 문서 순서대로 서로 아래로 비켜 쌓인다(겹치지 않는다).
+ * 층은 창(Popup·Dialog) 위 — 창 위에서도 알림을 읽고 닫을 수 있다(`--z-alert`).
  *
  * @public
  */

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

@@ -6,6 +6,9 @@
 'use client';
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import Download from 'lucide-react/dist/esm/icons/download.mjs';
+import { useLayoutEffect, useRef } from 'react';
+import { moveFocusOutside } from '../hooks/focusReturn';
+import { registerUpdateAlertSlot } from './updateAlertStack';
 import { useTranslation } from 'react-i18next';
 import { cx } from '../utils/cx';
 import Button from './Button';
@@ -15,11 +18,28 @@ import './UpdateAlert.css';
  *
  * 여러 장을 동시에 띄우려면 `.update-alert-stack`으로 감싼다 — 낱장은 스스로
  * fixed로 붙지만 스택 안에서는 흐름 배치가 되어 아래로 쌓인다.
+ * 따로 놓인 낱장과 스택(또는 낱장 여럿)이 함께 뜨면 문서 순서대로 서로 아래로 비켜 쌓인다(겹치지 않는다).
+ * 층은 창(Popup·Dialog) 위 — 창 위에서도 알림을 읽고 닫을 수 있다(`--z-alert`).
  *
  * @public
  */
 export default function UpdateAlert({ title, message, actionLabel, onAction, icon, onClose, className = '', }) {
     const { t } = useTranslation();
     const resolvedActionLabel = actionLabel ?? t('common.update', '업데이트');
-    return (_jsxs("div", { className: cx('update-alert', className), role: "alert", children: [onClose && (_jsx("button", { type: "button", className: "update-alert__close", onClick: onClose, "aria-label": t('common.close', '닫기'), children: "\u00D7" })), _jsxs("div", { className: "update-alert__top", children: [_jsx("div", { className: "update-alert__icon", children: icon ?? _jsx(Download, { size: 20, strokeWidth: 2 }) }), _jsxs("div", { className: "update-alert__body", children: [_jsx("div", { className: "update-alert__title h4", children: title }), _jsx("div", { className: "update-alert__message body-3", children: message })] })] }), onAction && (_jsx(Button, { htmlType: "button", size: 32, variant: "main", shape: "pill", className: "update-alert__action", onClick: onAction, children: resolvedActionLabel }))] }));
+    /* 닫기(×)를 눌러 부모가 알림을 치우면 그 단추에 있던 포커스가 body 로 떨어졌다. 닫기로 떠날 때만(화면 전체가 내려갈 때는 아님)
+       떼기 직전(레이아웃 효과 정리 — 아직 문서에 붙어 있다) 알림 앞의 포커스 받을 곳으로 옮긴다. */
+    const rootRef = useRef(null);
+    const 닫기눌림Ref = useRef(false);
+    useLayoutEffect(() => {
+        const root = rootRef.current;
+        /* 낱장과 스택이 함께 뜨면 둘 다 우상단 16px 에 붙어 겹쳤다 — 자리(낱장 자신 또는 감싼 스택)를 올려 문서 순서대로 아래로 쌓는다 */
+        const 자리 = root?.parentElement?.closest('.update-alert-stack') ?? root;
+        const 내리기 = 자리 ? registerUpdateAlertSlot(자리) : null;
+        return () => {
+            내리기?.();
+            if (닫기눌림Ref.current && root && root.contains(document.activeElement))
+                moveFocusOutside(root);
+        };
+    }, []);
+    return (_jsxs("div", { ref: rootRef, className: cx('update-alert', className), role: "alert", children: [onClose && (_jsx("button", { type: "button", className: "update-alert__close", onClick: () => { 닫기눌림Ref.current = true; onClose(); }, "aria-label": t('common.close', '닫기'), children: "\u00D7" })), _jsxs("div", { className: "update-alert__top", children: [_jsx("div", { className: "update-alert__icon", children: icon ?? _jsx(Download, { size: 20, strokeWidth: 2 }) }), _jsxs("div", { className: "update-alert__body", children: [_jsx("div", { className: "update-alert__title h4", children: title }), _jsx("div", { className: "update-alert__message body-3", children: message })] })] }), onAction && (_jsx(Button, { htmlType: "button", size: 32, variant: "main", shape: "pill", className: "update-alert__action", onClick: onAction, children: resolvedActionLabel }))] }));
 }

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

@@ -24,8 +24,10 @@ export interface PhonemeSelectBlockProps {
     onSearchEmpty?: () => void;
     searchDisabled?: boolean;
     searchLabel?: string;
+    /** 검색 확인 중 — 검색 단추를 그대로 두고 스피너·aria-busy 로 알린다(누름은 막되 초점은 남는다). */
     searchChecking?: boolean;
     pairMode?: boolean;
+    /** 머리의 "유의사항" 단추(툴팁). **기본 true** — 늘 보이던 단추를 지킨다. false 를 주면 숨는다. */
     showInfoButton?: boolean;
     /** 검색 버튼 바로 위에 표시할 내용(예: 현재 검색 조건 요약 Badge) */
     beforeSearchContent?: ReactNode;

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

@@ -13,7 +13,7 @@ import Button from '../Button';
 import DescriptionTooltip from '../Tooltip/DescriptionTooltip';
 import { sectionValues } from './phonemeSelectBlockUtils';
 /** @public */
-export default function PhonemeSelectBlock({ sections, selectedList, count, onCountChange, maxCount = 4, minCount = 1, combinationSections, combinationSectionsForSlot, onSelect, placeholder = '-', className, title, titleIcon, disc, showInfoButton = false, onClearPhoneme, onSearch, onSearchEmpty, searchDisabled = false, searchLabel, searchChecking = false, pairMode = false, sectionType = 'page', beforeSearchContent, beforeContent, afterContent, hideCountControl = false, ordinal = false, }) {
+export default function PhonemeSelectBlock({ sections, selectedList, count, onCountChange, maxCount = 4, minCount = 1, combinationSections, combinationSectionsForSlot, onSelect, placeholder = '-', className, title, titleIcon, disc, showInfoButton = true, onClearPhoneme, onSearch, onSearchEmpty, searchDisabled = false, searchLabel, searchChecking = false, pairMode = false, sectionType = 'page', beforeSearchContent, beforeContent, afterContent, hideCountControl = false, ordinal = false, }) {
     const { t } = useTranslation();
     const infoNotes = useMemo(() => t('wordPairs.infoNotes', { returnObjects: true }), [t]);
     const countOptions = useMemo(() => Array.from({ length: maxCount - minCount + 1 }, (_, i) => {
@@ -47,8 +47,13 @@ export default function PhonemeSelectBlock({ sections, selectedList, count, onCo
     }), [sections, placeholder]);
     const infoButton = (_jsxs(_Fragment, { children: [_jsx("div", { "data-tooltip-ignore": true, children: _jsx(Button, { htmlType: "button", size: 40, type: isMobile ? 'dot' : undefined, icon: "info", label: isMobile ? undefined : t('wordPairs.caution', '유의사항'), 
                     // 좁은 화면에서는 아이콘만 남는다 — 이름을 늘 준다
-                    ariaLabel: t('wordPairs.caution', '유의사항'), selected: !!infoAnchorRect, onClick: (e) => toggleInfo(e.currentTarget) }) }), infoAnchorRect && (_jsx(DescriptionTooltip, { title: t('wordPairs.caution', '유의사항'), items: infoNotes, anchorRect: infoAnchorRect, onClose: handleCloseInfo }))] }));
-    return (_jsxs(Section, { type: sectionType, title: title, icon: titleIcon, disc: disc, action: infoButton, className: cx('phoneme-select-block', className), children: [beforeContent, (!hideCountControl || (showInfoButton && !(title || disc))) && (_jsxs("div", { className: "phoneme-select-block__controls", children: [!hideCountControl && (_jsx(SegmentedControl, { options: countOptions, value: String(count), onChange: handleCountChange, size: 40, className: "phoneme-select-block__count-control" })), showInfoButton && !(title || disc) && infoButton] })), _jsx("div", { className: "phoneme-select-block__cells", children: pairMode
+                    ariaLabel: t('wordPairs.caution', '유의사항'), 
+                    /* 여닫이 — aria-pressed(selected) 대신 aria-expanded. 보이는 선택 모양은 같은 클래스로 */
+                    className: infoAnchorRect ? 'is-selected' : undefined, "aria-expanded": !!infoAnchorRect, "aria-haspopup": "dialog", onClick: (e) => toggleInfo(e.currentTarget) }) }), infoAnchorRect && (_jsx(DescriptionTooltip, { title: t('wordPairs.caution', '유의사항'), items: infoNotes, anchorRect: infoAnchorRect, onClose: handleCloseInfo }))] }));
+    return (
+    /* showInfoButton 은 기본 true 였어야 했다 — 적힌 기본값은 false 인데 단추는 늘 머리(action)에 떴다. 이제 false 면 숨는다.
+       (예전에는 true + 제목·설명 없음이면 조절 줄에 같은 단추를 하나 더 그려 둘이 한 툴팁을 열었다 — 머리 하나로 둔다.) */
+    _jsxs(Section, { type: sectionType, title: title, icon: titleIcon, disc: disc, action: showInfoButton ? infoButton : undefined, className: cx('phoneme-select-block', className), children: [beforeContent, !hideCountControl && (_jsx("div", { className: "phoneme-select-block__controls", children: _jsx(SegmentedControl, { options: countOptions, value: String(count), onChange: handleCountChange, size: 40, className: "phoneme-select-block__count-control" }) })), _jsx("div", { className: "phoneme-select-block__cells", children: pairMode
                     ? (_jsxs(_Fragment, { children: [_jsx("div", { className: "phoneme-select-block__cell-group", children: Array.from({ length: count }).map((_, pairIdx) => {
                                     const sel = selectedList[pairIdx * 2] ?? {};
                                     return (_jsxs("div", { className: "phoneme-select-block__cell", children: [_jsx("div", { className: "phoneme-select-block__cell-circle", children: _jsx("div", { className: "phoneme-select-block__cell-jamo", children: renderJamoParts(sel) }) }), _jsx("span", { className: "phoneme-select-block__cell-index caption-1", children: phonemeLabel(pairIdx + 1) })] }, pairIdx));
@@ -68,6 +73,9 @@ export default function PhonemeSelectBlock({ sections, selectedList, count, onCo
                 // 종성 '제외'(없음)만 선택된 슬롯은 실제 음소를 고른 것으로 치지 않는다 —
                 // "받침 없음"은 단독으로는 검색 조건이 되기엔 너무 느슨한 보조 조건이라서다.
                 const isEmpty = selectedList.every(sel => Object.entries(sel).every(([k, v]) => !v || (k === '종성' && v === '없음')));
-                return (_jsxs("div", { className: "phoneme-select-block__search-row", onClick: isEmpty ? onSearchEmpty : undefined, children: [onClearPhoneme && (_jsx(Button, { htmlType: "button", size: "56", type: "bar", label: t('wordPairs.resetOptions', '검색 옵션 초기화'), selected: false, disabled: isEmpty, onClick: isEmpty ? undefined : onClearPhoneme })), searchChecking ? (_jsxs("div", { className: "phoneme-select-block__checking", children: [_jsx("div", { className: "phoneme-select-block__spinner" }), _jsx("span", { className: "button-1 phoneme-select-block__checking-label", children: searchLabel ?? t('wordSearch.searchButton', '검색하기') })] })) : onSearch && (_jsx(Button, { htmlType: "button", size: "56", type: "bar", variant: "main", label: searchLabel ?? t('wordSearch.searchButton', '검색하기'), disabled: isEmpty || searchDisabled, onClick: isEmpty || searchDisabled ? undefined : onSearch }))] }));
+                return (_jsxs("div", { className: "phoneme-select-block__search-row", onClick: isEmpty ? onSearchEmpty : undefined, children: [onClearPhoneme && (_jsx(Button, { htmlType: "button", size: "56", type: "bar", label: t('wordPairs.resetOptions', '검색 옵션 초기화'), selected: false, disabled: isEmpty, onClick: isEmpty ? undefined : onClearPhoneme })), onSearch ? (
+                        /* 확인 중에도 단추를 **바꿔 끼우지 않는다** — 전에는 스피너 칸으로 갈아 끼워, 키보드로 누른 단추가 사라지며 초점이
+                           body 로 빠졌다. 막힘은 aria-disabled(onDisabledClick)로만 걸어 초점을 남기고, aria-busy·스피너로 알린다. */
+                        _jsx(Button, { htmlType: "button", size: "56", type: "bar", variant: "main", icon: searchChecking ? _jsx("span", { className: "phoneme-select-block__spinner", "aria-hidden": "true" }) : undefined, label: searchLabel ?? t('wordSearch.searchButton', '검색하기'), disabled: isEmpty || searchDisabled || searchChecking, onDisabledClick: searchChecking ? () => { } : undefined, "aria-busy": searchChecking || undefined, onClick: onSearch })) : searchChecking ? (_jsxs("div", { className: "phoneme-select-block__checking", "aria-busy": "true", children: [_jsx("div", { className: "phoneme-select-block__spinner" }), _jsx("span", { className: "button-1 phoneme-select-block__checking-label", children: searchLabel ?? t('wordSearch.searchButton', '검색하기') })] })) : null] }));
             })(), afterContent] }));
 }