@ihabdevteam/core 0.321.0 → 0.323.0

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

@@ -19,7 +19,7 @@ import Button from '../Button';
 import Icon from '../Icon';
 import InfoTooltip from '../Tooltip/InfoTooltip';
 import { STATUS_MESSAGES, ANNOUNCED_STATUSES } from './trainingStepAudioPlayerTypes';
-import { 키보드로눌렀나 } from '../../hooks/inputModality';
+import { wasKeyboardPress } from '../../hooks/inputModality';
 import { measureAudioDuration, waitForCanPlay } from './audioWaits';
 import { useWaveReady } from './useWaveReady';
 import { useObjectUrls } from './useObjectUrls';
@@ -83,17 +83,17 @@ export default function TrainingStepAudioPlayer({ btnLabel, soundSrc, bucketPath
     const [stateLocal, setStateLocal] = useState('active');
     /* 초점을 가진 큰 '듣기' 단추를 누르면 그 단추가 사라진다 — 재생 모드가 되면 초점을 '재생 / 멈춤' 으로 옮긴다
        (옮기지 않으면 초점이 body 로 떨어져 키보드 사용자가 멈출 단추를 다시 찾아야 했다). */
-    const 듣기초점옮기기Ref = useRef(false);
+    const moveFocusToListenRef = useRef(false);
     useEffect(() => {
-        if (stateLocal !== 'playMode' || !듣기초점옮기기Ref.current)
+        if (stateLocal !== 'playMode' || !moveFocusToListenRef.current)
             return;
-        듣기초점옮기기Ref.current = false;
-        const 지금 = typeof document !== 'undefined' ? document.activeElement : null;
-        if (지금 && 지금 !== document.body)
+        moveFocusToListenRef.current = false;
+        const active = typeof document !== 'undefined' ? document.activeElement : null;
+        if (active && active !== document.body)
             return;
-        const 재생멈춤 = btnsRef.current?.querySelectorAll('button')[1];
+        const playPauseBtn = btnsRef.current?.querySelectorAll('button')[1];
         try {
-            재생멈춤?.focus();
+            playPauseBtn?.focus();
         }
         catch (e) { }
     }, [stateLocal]);
@@ -107,7 +107,7 @@ export default function TrainingStepAudioPlayer({ btnLabel, soundSrc, bucketPath
      * 그래서 번호는 `currentIndex` 에서 읽고, 여기서는 **밝힐지 말지만** 든다.
      * 둘을 따로 들면 언젠가 한쪽만 갱신되는 자리가 생긴다(실제로 `goToTrack` 이
      * 번호만 바꾸고 이 값은 효과에 기대고 있었다). */
-    const [구간표시, set구간표시] = useState(false);
+    const [showRange, setShowRange] = useState(false);
     const [totalDuration, setTotalDuration] = useState(0);
     // 문장(메인) 재생 속도·볼륨 — 하단 소음설정 툴팁과 공유(NoisePlayerContext)
     const playbackRate = noisePlayer?.playbackRate ?? 1.0;
@@ -138,16 +138,16 @@ export default function TrainingStepAudioPlayer({ btnLabel, soundSrc, bucketPath
     /* **시간표의 자리·의도·뜸 타이머·멈춘 자리는 진행기가 쥔다**((85) 2a~2c, 2026-10-06).
        묻는 쪽(소음 · 틱 · 토글 · 자물쇠)은 **자리를 받아 제 손으로 셈하지 않고** 진행기에게
        묻는다 — `isRunning()` 하나다. 그 셈이 세 벌로 흩어져 있던 것이 오늘 결함 여섯의 뿌리였다. */
-    const 진행기 = usePlaybackSequencer({ mountedRef });
+    const sequencer = usePlaybackSequencer({ mountedRef });
     /* `onEnded` 가 적어 두는 "여기서부터 이어 간다" — 토글이 멈출 때 진행기에 넘긴다 */
-    const 이어가기RefBox = useRef(null);
+    const continueRef = useRef(null);
     /* 이벤트 손잡이는 한 번만 붙으므로 prop 을 ref 로 들고 본다 — 안 그러면 낡은 값을 쓴다
        (이 파일이 `disabledRef`·`noiseSettingsRef` 에 쓰는 것과 같은 결). */
     const leadInMsRef = useRef(leadInMs);
     const tailMsRef = useRef(tailMs);
     useEffect(() => { leadInMsRef.current = Math.max(0, leadInMs || 0); }, [leadInMs]);
     useEffect(() => { tailMsRef.current = Math.max(0, tailMs || 0); }, [tailMs]);
-    const { start: startTicker, stop: stopTicker, settleTo: settleTicker, } = useProgressTicker({ audioRef, fillRef, waveProgressRef, sourcesRef, currentIndexRef, sequencer: 진행기, leadInMs, tailMs });
+    const { start: startTicker, stop: stopTicker, settleTo: settleTicker, } = useProgressTicker({ audioRef, fillRef, waveProgressRef, sourcesRef, currentIndexRef, sequencer: sequencer, leadInMs, tailMs });
     /* 파형이 자리를 잡을 때까지 기다리는 규칙은 useWaveReady 가 들고 있다 —
        ref 둘·함수 둘에 "준비 안 됨으로 되돌리기"가 일곱 군데 흩어져 있던 것을 모았다. */
     const { onReadyChange: handleWaveReadyChange, waitForReady: waitForWaveReady, markNotReady: markWaveNotReady, } = useWaveReady({ showSoundWaveForm, showNoiseWaveForm });
@@ -174,9 +174,9 @@ export default function TrainingStepAudioPlayer({ btnLabel, soundSrc, bucketPath
         noisePlayer,
         audioRef,
         playbackStateRef,
-        sequencer: 진행기,
+        sequencer: sequencer,
     });
-    const { startTTS: 합성시작, stopTTS } = useTTSPlayback({
+    const { startTTS: beginTTS, stopTTS } = useTTSPlayback({
         ttsText,
         playbackRate,
         // TTS 음성 = 문제 소리 = 전체 소리
@@ -201,11 +201,11 @@ export default function TrainingStepAudioPlayer({ btnLabel, soundSrc, bucketPath
                 setNoticeMessage(t('training.ttsUnavailable', '이 기기에서는 음성을 들려줄 수 없습니다.'));
             }
             catch (_) { }
-            합성시작(text);
+            beginTTS(text);
             return;
         }
-        소리잡기('tts');
-        합성시작(text);
+        acquireSound('tts');
+        beginTTS(text);
     };
     const requestedSources = Array.isArray(soundSrc)
         ? soundSrc.filter(Boolean)
@@ -228,17 +228,17 @@ export default function TrainingStepAudioPlayer({ btnLabel, soundSrc, bucketPath
      *
      * 이제 세대 하나다. `멈춤의도()` 는 세대를 올리고 자리를 비운다.
      */
-    const 멈춤의도 = () => { 진행기.abort(); };
+    const abortIntent = () => { sequencer.abort(); };
     /* 스피커는 하나(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 soundKindRef = useRef(null);
+    const releaseSoundRef = useRef(null);
+    const stopSoundRef = useRef(null);
+    if (!stopSoundRef.current) {
+        stopSoundRef.current = () => {
+            releaseSoundRef.current = null;
             const a = audioRef.current;
             /* **뜸 중이면 요소는 멈춰 있다** — `!a.paused` 만 보면 이 문을 안 지나, 남이 스피커를
                가져가도 **뜸은 제 것인 줄 알고 깨어나 소리를 냈다**(가짜 시계 실측, 두 길 다:
@@ -247,8 +247,8 @@ export default function TrainingStepAudioPlayer({ btnLabel, soundSrc, bucketPath
                울린다" 고 보고한 그 자리의 **뜸 판**이다.
                오늘 같은 꼴을 여섯 번째 만난다(소음 감시 · 재생판 · 토글 · 그 토글의 두 번째 벌 ·
                번호 단추 · 여기). 이제 `isRunning()` 하나로 묻는다. */
-            if (소리종류Ref.current === 'audio' && a && (!a.paused || 진행기.isRunning())) {
-                멈춤의도();
+            if (soundKindRef.current === 'audio' && a && (!a.paused || sequencer.isRunning())) {
+                abortIntent();
                 try {
                     a.pause();
                 }
@@ -259,7 +259,7 @@ export default function TrainingStepAudioPlayer({ btnLabel, soundSrc, bucketPath
                     fadeOutNoise();
                 }
             }
-            else if (소리종류Ref.current === 'tts') {
+            else if (soundKindRef.current === 'tts') {
                 try {
                     stopTTSRef.current?.();
                 }
@@ -267,14 +267,14 @@ export default function TrainingStepAudioPlayer({ btnLabel, soundSrc, bucketPath
             }
         };
     }
-    const 소리잡기 = (종류) => {
-        소리종류Ref.current = 종류;
-        소리놓기Ref.current = claimSound(소리멈춤Ref.current);
+    const acquireSound = (kind) => {
+        soundKindRef.current = kind;
+        releaseSoundRef.current = claimSound(stopSoundRef.current);
     };
     // 멈춤·정지·완료 뒤에는 자리를 비운다 — 남이 울릴 때 끝난 재생기의 상태를 건드리지 않게
-    const 소리놓기 = () => { 소리놓기Ref.current?.(); 소리놓기Ref.current = null; };
-    useEffect(() => () => { if (소리멈춤Ref.current)
-        stopSoundIfOwner(소리멈춤Ref.current); }, []);
+    const releaseSound = () => { releaseSoundRef.current?.(); releaseSoundRef.current = null; };
+    useEffect(() => () => { if (stopSoundRef.current)
+        stopSoundIfOwner(stopSoundRef.current); }, []);
     /* 이벤트 손잡이·비동기 흐름 안에서 **지금 값**을 읽어야 한다 — 효과가 다시 돌 때까지
        기다리면 이미 실은 소리에 옛 빠르기가 걸린다(이 파일의 `disabledRef`·`leadInMsRef` 와 같은 결). */
     const playbackRateRef = useRef(playbackRate);
@@ -285,7 +285,7 @@ export default function TrainingStepAudioPlayer({ btnLabel, soundSrc, bucketPath
      * `load()` 는 명세대로 `playbackRate` 를 **`defaultPlaybackRate` 로 되돌린다.** 기본값을
      * 안 세워 두면 그 되돌림이 늘 1 이라, 소리를 실을 때마다 사용자가 고른 빠르기가 지워진다.
      */
-    const 빠르기걸기 = useCallback((a) => {
+    const applyPlaybackRate = useCallback((a) => {
         const r = playbackRateRef.current || 1.0;
         try {
             a.defaultPlaybackRate = r;
@@ -309,12 +309,12 @@ export default function TrainingStepAudioPlayer({ btnLabel, soundSrc, bucketPath
      * 자리를 하나로 모은다 — 흩어진 다섯을 글로 단속하지 않고 **셈으로 막는다**
      * (`test/audioPlaybackRateSurvivesLoad.test.tsx` 가 `load()` 자리 수를 센다).
      */
-    const 소리싣기 = useCallback((a, src) => {
+    const loadSound = useCallback((a, src) => {
         a.src = src;
-        빠르기걸기(a); // defaultPlaybackRate 를 먼저 세워 둔다 — load() 가 그것으로 되돌린다
+        applyPlaybackRate(a); // defaultPlaybackRate 를 먼저 세워 둔다 — load() 가 그것으로 되돌린다
         a.load();
-        빠르기걸기(a); // 되돌린 뒤 한 번 더 — 기본값을 못 세우는 환경에서도 선다
-    }, [빠르기걸기]);
+        applyPlaybackRate(a); // 되돌린 뒤 한 번 더 — 기본값을 못 세우는 환경에서도 선다
+    }, [applyPlaybackRate]);
     /**
      * **완료 연출을 걷는다** — 새 재생이 서면 지난 완료의 자취가 그 위에 남아선 안 된다.
      *
@@ -332,17 +332,17 @@ export default function TrainingStepAudioPlayer({ btnLabel, soundSrc, bucketPath
      * 부른다(다시듣기 · ▶ · 번호 단추 · 불러오기가 다 그 길이다). 걷는 곳이 여럿이면
      * **한 곳이 안 따라간다** — 오늘 밤 내내 그 결이었다.
      */
-    const 완료연출걷기 = useCallback(() => {
+    const clearDoneEffect = useCallback(() => {
         if (fillOutResetRef.current) {
             clearTimeout(fillOutResetRef.current);
             fillOutResetRef.current = null;
         }
         setFillCompletionPhase('idle');
     }, []);
-    const tryPlayWithRetry = useCallback(async (a, attempts = 3, delayMs = 50, 앞뜸흐른 = 0) => {
+    const tryPlayWithRetry = useCallback(async (a, attempts = 3, delayMs = 50, leadElapsed = 0) => {
         /* 지난 완료의 접는 연출을 먼저 걷는다 — 위 설명 참고 */
-        완료연출걷기();
-        const 내세대 = 진행기.generation();
+        clearDoneEffect();
+        const myGeneration = sequencer.generation();
         /* **이어 트는 것에는 앞뜸을 다시 안 준다**(사용자 신고, 2026-10-06).
            앞뜸은 *소리 앞*의 구간이다. 소리가 **이미 시작된** 것을 이어 트는데 앞뜸을 또 주면
            소리는 멈춘 자리(`currentTime`)에서 이어 가는데 **진행은 0 부터 다시 센다** — 말귀
@@ -356,16 +356,16 @@ export default function TrainingStepAudioPlayer({ btnLabel, soundSrc, bucketPath
            > 소리 중에 멈췄다 이을 때도 귀를 다시 채비시키려 **앞뜸을 주는** 쪽이 나을 수도
            > 있다. 그러면 시간표를 *앞뜸 + 남은 소리 + 뒤뜸* 으로 다시 그려야 어긋나지 않는다.
            > 그것은 **사장님께 여쭐 일**이라 지금은 "앞뜸은 소리 앞" 이라는 뜻 그대로 둔다. */
-        const 이어틀기 = !!a && a.currentTime > 0 && !a.ended;
+        const resuming = !!a && a.currentTime > 0 && !a.ended;
         /* 앞뜸에서 멈췄다 이으면 **남은 만큼만** 채운다 — 뜸도 시간표의 일부라 처음부터 다시
            세면 그 자리에서 이어지지 않는다(사용자 결정, 2026-10-06). */
-        const 남은앞뜸 = Math.max(0, leadInMsRef.current - Math.max(0, 앞뜸흐른));
-        if (남은앞뜸 > 0 && !이어틀기) {
+        const leadRemaining = Math.max(0, leadInMsRef.current - Math.max(0, leadElapsed));
+        if (leadRemaining > 0 && !resuming) {
             /* **스피커는 뜸이 시작될 때 잡는다**((85) 2b, 2026-10-06). 전에는 `await a.play()` 바로
                앞에서 잡았는데, 그러면 **앞뜸 내내 주인이 없다** — 그 사이 남이 소리를 내도 이쪽을
                못 멈추고, 뜸이 끝나면 둘이 함께 울린다. 소음은 이미 뜸부터 깔리니(0.268.0)
                **소리를 내고 있는 것이 맞다.** */
-            소리잡기('audio');
+            acquireSound('audio');
             startTicker();
             /* 앞뜸부터 **재생 중**이다 — 재생판이 이제 앞뜸부터 보이므로((86)) 단추도 ⏸ 로 서야
                누르는 뜻과 맞는다. ▶ 로 두면 "멈추려고 ▶ 를 누르는" 꼴이 된다. */
@@ -383,24 +383,24 @@ export default function TrainingStepAudioPlayer({ btnLabel, soundSrc, bucketPath
                 }
                 catch (e) { }
             }
-            if (!(await 진행기.waitPad(남은앞뜸, 'lead', 앞뜸흐른)))
+            if (!(await sequencer.waitPad(leadRemaining, 'lead', leadElapsed)))
                 return false;
-            if (!mountedRef.current || !진행기.isCurrent(내세대))
+            if (!mountedRef.current || !sequencer.isCurrent(myGeneration))
                 return false;
         }
-        진행기.enterSound();
+        sequencer.enterSound();
         for (let i = 0; i < attempts; i++) {
-            if (!mountedRef.current || !진행기.isCurrent(내세대))
+            if (!mountedRef.current || !sequencer.isCurrent(myGeneration))
                 return false;
             try {
-                소리잡기('audio');
+                acquireSound('audio');
                 await a.play();
                 return true;
             }
             catch (err) {
                 const errName = err instanceof Error ? err.name : (typeof err === 'object' && err && 'name' in err ? err.name : undefined);
                 if (errName === 'AbortError') {
-                    if (!진행기.isCurrent(내세대))
+                    if (!sequencer.isCurrent(myGeneration))
                         return false;
                     await new Promise((res) => setTimeout(res, delayMs));
                     continue;
@@ -424,7 +424,7 @@ export default function TrainingStepAudioPlayer({ btnLabel, soundSrc, bucketPath
         }
         catch (_) { }
         return false;
-    }, [t, startTicker, 진행기, fadeInNoise, noiseSettingsRef, 완료연출걷기]);
+    }, [t, startTicker, sequencer, fadeInNoise, noiseSettingsRef, clearDoneEffect]);
     /**
      * **뒤뜸(사이 뜸)에서 멈췄다 이을 때** — 남은 만큼 돌고 하던 일을 잇는다.
      *
@@ -432,9 +432,9 @@ export default function TrainingStepAudioPlayer({ btnLabel, soundSrc, bucketPath
      * 짧아지고 재생바가 그 순간 튄다 — 사용자가 짚은 것이 그 자리다. `onEnded` 의 사슬과
      * **같은 모양**이어야 하므로(진행바 켜기 · 소음 · 세대 가림 · `leave()`) 여기도 그대로 둔다.
      */
-    const 뒤뜸이어가기 = useCallback((흐른) => {
-        const 내세대 = 진행기.generation();
-        const 남은 = Math.max(0, tailMsRef.current - Math.max(0, 흐른));
+    const continueAfterTail = useCallback((elapsed) => {
+        const myGeneration = sequencer.generation();
+        const remaining = Math.max(0, tailMsRef.current - Math.max(0, elapsed));
         startTicker();
         const ns = noiseSettingsRef.current;
         if (ns?.enabled && (ns.volume ?? 0) > 0) {
@@ -443,21 +443,21 @@ export default function TrainingStepAudioPlayer({ btnLabel, soundSrc, bucketPath
             }
             catch (e) { }
         }
-        const 잇기 = () => { try {
-            이어가기RefBox.current?.();
+        const resume = () => { try {
+            continueRef.current?.();
         }
         catch (e) { } };
-        if (남은 <= 0) {
-            진행기.leave();
-            잇기();
+        if (remaining <= 0) {
+            sequencer.leave();
+            resume();
             return;
         }
-        진행기.waitPad(남은, 'tail', 흐른).then((이어도되나) => {
-            진행기.leave();
-            if (이어도되나 && 진행기.isCurrent(내세대))
-                잇기();
+        sequencer.waitPad(remaining, 'tail', elapsed).then((mayContinue) => {
+            sequencer.leave();
+            if (mayContinue && sequencer.isCurrent(myGeneration))
+                resume();
         }).catch(() => { });
-    }, [진행기, startTicker, fadeInNoise, noiseSettingsRef]);
+    }, [sequencer, startTicker, fadeInNoise, noiseSettingsRef]);
     const attachAudioListeners = useCallback(() => {
         const a = audioRef.current;
         if (!a)
@@ -465,7 +465,7 @@ export default function TrainingStepAudioPlayer({ btnLabel, soundSrc, bucketPath
         const onPlay = () => {
             setPlaybackState("playing");
             setStateLocal("playMode");
-            set구간표시(true);
+            setShowRange(true);
             startTicker();
             // 문장을 Web Audio 그래프(gain·미터)에 태운다 — 재생 제스처 시점에 resume, 컨텍스트가 달리고 나서야
             // 태우므로 그 전엔 요소가 제 볼륨으로 직접 울린다(무음 방지). 태운 뒤 볼륨은 GainNode 로 걸린다.
@@ -501,17 +501,17 @@ export default function TrainingStepAudioPlayer({ btnLabel, soundSrc, bucketPath
            다음 소리가 있으면 그 소리의 **앞 뜸**이 이어 붙어 사이가 둘을 더한 만큼이 된다 —
            누를 때의 뜸과 사이의 뜸을 가르는 자리가 여기다. */
         const onEnded = () => {
-            const 이어가기 = () => {
+            const continuePlay = () => {
                 try {
                     const sref = sourcesRef.current;
                     const next = nextTrackIndex(sref, currentIndexRef.current);
                     if (next !== null) {
                         currentIndexRef.current = next;
                         setCurrentIndex(next);
-                        set구간표시(true);
+                        setShowRange(true);
                         const nextSrc = sref?.[next] && sref[next].src;
                         if (nextSrc && a) {
-                            소리싣기(a, nextSrc);
+                            loadSound(a, nextSrc);
                             tryPlayWithRetry(a).catch(() => { });
                             return;
                         }
@@ -529,7 +529,7 @@ export default function TrainingStepAudioPlayer({ btnLabel, soundSrc, bucketPath
                 }
                 catch (e) { }
                 stopTicker();
-                set구간표시(false);
+                setShowRange(false);
                 // 마지막 트랙 종료 시 소음 정지
                 fadeOutNoise();
                 // Route through handleEnd (via ref) so stateLocal transitions to 'active' before onDone fires.
@@ -541,21 +541,21 @@ export default function TrainingStepAudioPlayer({ btnLabel, soundSrc, bucketPath
                 catch (e) { }
             };
             /* 멈췄다 다시 누를 때 **여기서부터** 잇는다 — 진행기가 그 자리를 안다 */
-            이어가기RefBox.current = 이어가기;
+            continueRef.current = continuePlay;
             if (tailMsRef.current > 0) {
                 /* 기다리는 동안 진행바를 돌린다 — `pause` 가 이미 세웠을 수 있어 다시 켠다.
                    그 사이 멈추거나 떠나면 `waitPad` 가 거짓을 주고 아무 일도 안 한다. */
                 startTicker();
-                진행기.waitPad(tailMsRef.current, 'tail').then((이어도되나) => {
+                sequencer.waitPad(tailMsRef.current, 'tail').then((mayContinue) => {
                     /* 뒤뜸이 끝났다 — 자리는 비우되 **세대는 안 올린다**(`abort` 가 아니다). 올리면
                        바로 아래에서 이어 갈 사슬까지 제가 버린 것이 된다. */
-                    진행기.leave();
-                    if (이어도되나)
-                        이어가기();
+                    sequencer.leave();
+                    if (mayContinue)
+                        continuePlay();
                 }).catch(() => { });
                 return;
             }
-            이어가기();
+            continuePlay();
         };
         a.addEventListener("play", onPlay);
         a.addEventListener("pause", onPause);
@@ -569,7 +569,7 @@ export default function TrainingStepAudioPlayer({ btnLabel, soundSrc, bucketPath
             }
             catch (e) { }
         };
-    }, [fadeInNoise, fadeOutNoise, tryPlayWithRetry, noiseSettingsRef, startTicker, stopTicker, 진행기]);
+    }, [fadeInNoise, fadeOutNoise, tryPlayWithRetry, noiseSettingsRef, startTicker, stopTicker, sequencer]);
     useEffect(() => {
         const cleanup = attachAudioListeners();
         return cleanup;
@@ -735,21 +735,21 @@ export default function TrainingStepAudioPlayer({ btnLabel, soundSrc, bucketPath
      *
      * 차례는 이렇다: 돌림판 → 준비 끝 → **재생판·파형·재생바가 보임** → 앞뜸(소음) → 소리.
      */
-    const 재생판켜기 = () => {
+    const openPlayPanel = () => {
         setStateLocal('playMode');
         setCurrentIndex(0);
-        set구간표시(true);
+        setShowRange(true);
     };
     const loadAndPlay = async (a, src) => {
         markCompletedByEnd(false);
         fetchingRef.current = false;
-        소리싣기(a, src);
+        loadSound(a, src);
         await waitForCanPlay(a);
         // 기다리는 사이 떠났으면(false) 이어 가지 않는다 — 떼어진 <audio> 를 틀던 것
         if ((await waitForWaveReady()) === false)
             return;
         setIsFetchingUrl(false);
-        재생판켜기(); // 앞뜸이 시작되기 **전에** — 뜸 동안 판이 비지 않게
+        openPlayPanel(); // 앞뜸이 시작되기 **전에** — 뜸 동안 판이 비지 않게
         await tryPlayWithRetry(a);
     };
     const fetchAndPrepareFromTTSUrl = async (ttsUrl, playAfterLoad = false) => {
@@ -896,7 +896,7 @@ export default function TrainingStepAudioPlayer({ btnLabel, soundSrc, bucketPath
                 fetchingRef.current = false;
                 if (first.src && a) {
                     try {
-                        소리싣기(a, first.src);
+                        loadSound(a, first.src);
                         // canplay 이벤트 대기 — load() 직후 play() 호출 시 발생하는 AbortError 방지.
                         // 짧은 파일도 canplay가 빠르게 발생하므로 재생 지연 없음.
                         // (같은 기다림이 이 파일 위쪽에 waitForCanPlay 로 이미 있었다. 여기에 한 벌
@@ -909,7 +909,7 @@ export default function TrainingStepAudioPlayer({ btnLabel, soundSrc, bucketPath
                         // 뒤늦게 나타나는 빈 화면 구간도 생기지 않도록 한다.
                         if (showSpinner)
                             setIsFetchingUrl(false);
-                        재생판켜기(); // 앞뜸이 시작되기 **전에** — 뜸 동안 판이 비지 않게
+                        openPlayPanel(); // 앞뜸이 시작되기 **전에** — 뜸 동안 판이 비지 않게
                         if (a)
                             await tryPlayWithRetry(a);
                     }
@@ -924,7 +924,7 @@ export default function TrainingStepAudioPlayer({ btnLabel, soundSrc, bucketPath
                 }
                 setStateLocal('playMode');
                 setCurrentIndex(0);
-                set구간표시(true);
+                setShowRange(true);
             }
             return finalSources.length > 0;
         }
@@ -944,7 +944,7 @@ export default function TrainingStepAudioPlayer({ btnLabel, soundSrc, bucketPath
      * 300ms 에 ⏸ → 소음 `play()` 가 또 불리고 **같은 단어가 두 번 틀어졌다**(2622ms · 2945ms).
      * 내 못은 저장소 소리로만 돌려서 통과했다 — **고친 벌만 재고 있었다.**
      */
-    const 요소토글 = async (a) => {
+    const toggleElement = async (a) => {
         /* **뜸 중이면 재생 중이다**(말귀 요청 (85) 0단계에서 찾은 결함, 2026-10-06).
            전에는 `a.paused` 만 봤다. 그런데 뜸 동안 메인 요소는 **멈춰 있다** — 앞뜸에는 아직
            `play()` 전이고 사이·뒤뜸에는 이미 `ended` 다. 그래서 ⏸ 로 보이는 단추를 뜸 중에
@@ -953,8 +953,8 @@ export default function TrainingStepAudioPlayer({ btnLabel, soundSrc, bucketPath
            +1000ms 에 한 번, 원래 사슬이 닿는 +1500ms 에 또 한 번).
            감시 타이머가 0.268.0 에서 배운 것과 같은 것을 이 단추가 못 배우고 있었다 —
            뜸은 소리가 안 나는 구간이지 **멈춘 구간이 아니다.** */
-        const 뜸도는중 = 진행기.isRunning();
-        if (a.paused && !뜸도는중) {
+        const padRunning = sequencer.isRunning();
+        if (a.paused && !padRunning) {
             if (completedByEndRef.current) {
                 await handleReplay();
                 return;
@@ -964,26 +964,26 @@ export default function TrainingStepAudioPlayer({ btnLabel, soundSrc, bucketPath
                다시 세지 않는다. */
             /* **멈춘 자리에서 이어 간다** — 어디서 몇 ms 였는지는 진행기가 안다.
                뜸도 시간표의 일부라 **남은 만큼만** 채운다(사용자 결정, 2026-10-06). */
-            const 멈췄던곳 = 진행기.resume();
-            if (멈췄던곳) {
+            const resumedAt = sequencer.resume();
+            if (resumedAt) {
                 setPlaybackState("playing");
-                if (멈췄던곳.phase === 'tail') {
-                    뒤뜸이어가기(멈췄던곳.흐른);
+                if (resumedAt.phase === 'tail') {
+                    continueAfterTail(resumedAt.elapsed);
                     return;
                 }
-                await tryPlayWithRetry(a, 3, 50, 멈췄던곳.흐른);
+                await tryPlayWithRetry(a, 3, 50, resumedAt.elapsed);
                 return;
             }
             await tryPlayWithRetry(a);
             setPlaybackState("playing");
         }
         else {
-            진행기.pause();
-            멈춤의도();
+            sequencer.pause();
+            abortIntent();
             a.pause();
             setPlaybackState("paused");
             /* 뜸 중에는 `pause` 사건이 안 온다(요소가 이미 멈춰 있다) — 그 사건이 하던 일을 여기서 한다 */
-            if (뜸도는중) {
+            if (padRunning) {
                 stopTicker();
                 fadeOutNoise();
             }
@@ -1044,16 +1044,16 @@ export default function TrainingStepAudioPlayer({ btnLabel, soundSrc, bucketPath
             if (stateLocal === 'playMode') {
                 /* 오디오 파일로 변환된 경우 audioRef로 제어. <audio> 는 늘 있으므로 그것만 보면 음성 합성으로 말하는 중(리졸버 없음·실패)에도
                    이 길로 들어가 소리 없는 <audio> 를 재생하려 들고 말은 멈추지 않았다 — 합성기가 말하는 중이고 <audio> 에 소리가 없으면 합성기를 멈춘다. */
-                const 합성으로말함 = !!synth && (synth.speaking || synth.paused) && !(a && (a.currentSrc || a.getAttribute('src')));
-                if (a && !합성으로말함) {
-                    await 요소토글(a); // 저장소 소리 갈래와 **같은 한 벌**
+                const speakingByTTS = !!synth && (synth.speaking || synth.paused) && !(a && (a.currentSrc || a.getAttribute('src')));
+                if (a && !speakingByTTS) {
+                    await toggleElement(a); // 저장소 소리 갈래와 **같은 한 벌**
                     return;
                 }
                 // speechSynthesis fallback
                 try {
                     if (synth && synth.paused) {
                         try {
-                            소리잡기('tts');
+                            acquireSound('tts');
                             synth.resume();
                             setPlaybackState('playing');
                         }
@@ -1079,30 +1079,30 @@ export default function TrainingStepAudioPlayer({ btnLabel, soundSrc, bucketPath
                 try {
                     if (first.src && a) {
                         try {
-                            소리싣기(a, first.src);
-                            재생판켜기(); // 앞뜸이 시작되기 **전에**
+                            loadSound(a, first.src);
+                            openPlayPanel(); // 앞뜸이 시작되기 **전에**
                             if (a)
                                 await tryPlayWithRetry(a);
                         }
                         catch (e) { }
                     }
-                    재생판켜기();
+                    openPlayPanel();
                     return;
                 }
                 catch (e) { }
             }
             setStateLocal("load");
             // 앱이 준 경로 규칙(resolvePath 등)이 던져도 못 얻은 것과 같이 다룬다 — 거절이 흘러 'load' 에 갇혔다
-            let 얻음;
+            let got;
             try {
-                얻음 = await fetchAndPrepare(true);
+                got = await fetchAndPrepare(true);
             }
             catch (e) {
-                얻음 = false;
+                got = false;
             }
             /* 쓸 소스를 하나도 못 얻으면(경로를 못 정한 코드뿐 등) 'load' 에 갇혀 듣기 단추가 사라지고 아무 조작도
                안 됐다 — 알리고 누를 수 있는 상태로 되돌린다. */
-            if (얻음 === false && mountedRef.current) {
+            if (got === false && mountedRef.current) {
                 try {
                     setNoticeMessage(t('training.audioFetchError', '사운드 소스를 가져오지 못했습니다.'));
                 }
@@ -1116,7 +1116,7 @@ export default function TrainingStepAudioPlayer({ btnLabel, soundSrc, bucketPath
         if (stateLocal === "playMode" || stateLocal === "active") {
             try {
                 if (a)
-                    await 요소토글(a);
+                    await toggleElement(a);
             }
             catch (e) {
                 const errName = e instanceof Error ? e.name : (typeof e === 'object' && e && 'name' in e ? e.name : undefined);
@@ -1153,8 +1153,8 @@ export default function TrainingStepAudioPlayer({ btnLabel, soundSrc, bucketPath
     };
     const handleStop = () => {
         // 기다리던 트랙 이동·재시도가 정지 뒤에 소리를 내지 않게
-        멈춤의도();
-        소리놓기();
+        abortIntent();
+        releaseSound();
         /* **`ttsMode` 라고 `<audio>` 를 안 멈추면 안 된다**(2026-10-06). 전에는 여기서 `stopTTS()`
            만 하고 **일찍 돌아갔다.** 그런데 TTS 에는 길이 둘이다 — 리졸버가 있으면 **주소를 받아
            `<audio>` 로 튼다**(그 길에 뜸·파형·번호 단추가 다 달려 있다). 기기 목소리로 말할 때만
@@ -1182,7 +1182,7 @@ export default function TrainingStepAudioPlayer({ btnLabel, soundSrc, bucketPath
         setPlaybackState('stopped');
         setStateLocal('active');
         setProgress(0);
-        set구간표시(false);
+        setShowRange(false);
     };
     /**
      * 트랙을 갈아 끼우고 재생한다 — 이전·다음·번호 단추가 모두 이 한 벌을 쓴다.
@@ -1207,28 +1207,28 @@ export default function TrainingStepAudioPlayer({ btnLabel, soundSrc, bucketPath
            `a.src` 를 다음 소리로 바꿔 놓아서다.
            그 토큰은 **세대와 같은 일**이었다((85) 2d) — `멈춤의도()` 가 둘 다 올리고 여기서
            둘 다 집었다. 세대 하나로 합친다: `abort()` 로 걷고, **그 뒤에** 제 세대를 집는다. */
-        멈춤의도();
-        const 내세대 = 진행기.generation();
+        abortIntent();
+        const myGeneration = sequencer.generation();
         const a = audioRef.current;
         const sref = sourcesRef.current;
         const src = sref?.[index]?.src;
         try {
             markCompletedByEnd(false);
             setCurrentIndex(index);
-            set구간표시(true); // 재생이 시작되기 전에도 밝힌다 — 예전엔 효과가 해 주던 일
+            setShowRange(true); // 재생이 시작되기 전에도 밝힌다 — 예전엔 효과가 해 주던 일
             currentIndexRef.current = index;
             if (!src || !a)
                 return;
             // 같은 구간을 다시 트는 것이면 파형은 그대로다 — 괜히 기다리지 않는다.
             if (!sameSegment)
                 markWaveNotReady();
-            소리싣기(a, src);
+            loadSound(a, src);
             if (!sameSegment && (await waitForWaveReady()) === false)
                 return;
-            if (!진행기.isCurrent(내세대))
+            if (!sequencer.isCurrent(myGeneration))
                 return;
             await tryPlayWithRetry(a);
-            if (!진행기.isCurrent(내세대))
+            if (!sequencer.isCurrent(myGeneration))
                 return;
             setPlaybackState('playing');
             setStateLocal('playMode');
@@ -1269,8 +1269,8 @@ export default function TrainingStepAudioPlayer({ btnLabel, soundSrc, bucketPath
         const holdDelay = 200;
         const outDelay = 340;
         markCompletedByEnd(true);
-        멈춤의도();
-        소리놓기();
+        abortIntent();
+        releaseSound();
         try {
             setProgress(1);
         }
@@ -1305,7 +1305,7 @@ export default function TrainingStepAudioPlayer({ btnLabel, soundSrc, bucketPath
             setPlaybackState('stopped');
         }
         catch (e) { }
-        set구간표시(false);
+        setShowRange(false);
         if (disabledRef.current)
             return;
         try {
@@ -1360,10 +1360,10 @@ export default function TrainingStepAudioPlayer({ btnLabel, soundSrc, bucketPath
         try {
             const a = audioRef.current;
             if (a && typeof a.playbackRate === 'number')
-                빠르기걸기(a);
+                applyPlaybackRate(a);
         }
         catch (e) { }
-    }, [playbackRate, 빠르기걸기]);
+    }, [playbackRate, applyPlaybackRate]);
     // 문장(메인) 볼륨 반영 — 문제 소리 볼륨(effectiveSpeechVolume = 전체 소리). setElementVolume 이 그래프에 태운
     // 요소면 GainNode, 아니면 요소 volume 에 건다(iOS 실기기는 요소 volume 이 안 먹는다). 재생 중이면 소음과 같은 150ms 램프로 옮기고, 멈춰 있으면 바로 건다.
     // 백그라운드 탭에서는 RAF 가 멈춰 램프가 중간에 설 수 있으므로 끝값을 타이머로 한 번 더 박는다.
@@ -1374,7 +1374,7 @@ export default function TrainingStepAudioPlayer({ btnLabel, soundSrc, bucketPath
             return;
         const target = Math.max(0, Math.min(1, speechVolume));
         const ramp = speechRampRef.current;
-        const 끊기 = () => {
+        const detach = () => {
             if (ramp.raf !== null) {
                 cancelAnimationFrame(ramp.raf);
                 ramp.raf = null;
@@ -1384,7 +1384,7 @@ export default function TrainingStepAudioPlayer({ btnLabel, soundSrc, bucketPath
                 ramp.timer = null;
             }
         };
-        끊기();
+        detach();
         const from = getElementVolume(a);
         if (a.paused || Math.abs(from - target) < 0.001 || typeof requestAnimationFrame !== 'function') {
             try {
@@ -1403,11 +1403,11 @@ export default function TrainingStepAudioPlayer({ btnLabel, soundSrc, bucketPath
             ramp.raf = t < 1 ? requestAnimationFrame(step) : null;
         };
         ramp.raf = requestAnimationFrame(step);
-        ramp.timer = setTimeout(() => { 끊기(); try {
+        ramp.timer = setTimeout(() => { detach(); try {
             setElementVolume(a, target);
         }
         catch (e) { } }, 200);
-        return 끊기;
+        return detach;
     }, [speechVolume]);
     // fill (진행 마커) 클래스 및 초기 위치 계산 — RAF 루프에서 .style.left를 직접 갱신합니다.
     const isFillHolding = fillCompletionPhase === 'hold';
@@ -1426,12 +1426,12 @@ export default function TrainingStepAudioPlayer({ btnLabel, soundSrc, bucketPath
                            누르면 소리를 받으러 가거나 "가져오지 못했습니다" 를 띄웠다 — 마우스와 같게 키보드도 막는다 */
                         disabled: isDisabled, 
                         // 키보드로 눌렀을 때만 초점을 옮긴다 — 마우스로 누른 사람에게 '재생 / 멈춤' 초점 툴팁이 뜨지 않게
-                        onClick: () => { 듣기초점옮기기Ref.current = 키보드로눌렀나(); hideListenTip(); handleToggle(); }, "aria-label": typeof label === 'string' ? label : t('training.listen', '듣기'), onMouseEnter: showListenTip, onMouseLeave: hideListenTip, 
+                        onClick: () => { moveFocusToListenRef.current = wasKeyboardPress(); hideListenTip(); handleToggle(); }, "aria-label": typeof label === 'string' ? label : t('training.listen', '듣기'), onMouseEnter: showListenTip, onMouseLeave: hideListenTip, 
                         // 키보드로 이 버튼에 오면 마우스와 동일하게 안내를 띄운다
                         onFocus: showListenTip, onBlur: hideListenTip, children: _jsx("span", { ref: listenBtnRef, className: "audio-player__button-triangle-wrap", children: _jsx("svg", { className: "audio-player__button-triangle", viewBox: "0 0 24 24", "aria-hidden": "true", children: _jsx("path", { ref: triPathRef, d: "M13.2 7.7 L16.5 9.85 Q20.2 12 16.5 14.15 L10 18.3 Q7 19.7 7 16.3 L7 7.7 Q7 4.3 10 5.7 L13.2 7.7" }) }) }) })) : null, listenBtnRect && (_jsx(InfoTooltip, { anchorRect: listenBtnRect, text: typeof label === 'string' && label ? label : t('training.listenLabel', '문장 듣기'), offset: 8 })), _jsxs("div", { className: `audio-player__play ${stateLocal === "playMode" || displayedPlaying ? "is-visible" : ""}`, inert: !(stateLocal === "playMode" || displayedPlaying) || undefined, children: [_jsxs("div", { ref: btnsRef, className: "audio-player__buttons", children: [_jsx(Button, { htmlType: "button", size: 32, showTooltipInfo: true, type: "dot", shape: "pill", useBorder: false, icon: "skip-back", onClick: handlePrev, ariaLabel: t('training.prev', '이전'), width: "60px", variant: "transparent-white", "aria-hidden": "true", tabIndex: -1, disabled: stateLocal !== 'playMode' }), _jsx(Button, { htmlType: "button", size: 32, showTooltipInfo: true, type: "dot", shape: "pill", useBorder: false, icon: displayedPlaying ? "pause" : "play", onClick: handleToggle, ariaLabel: t('common.playPause', '재생 / 멈춤'), "aria-pressed": displayedPlaying, width: "60px", variant: "transparent-white", disabled: stateLocal !== 'playMode' }), _jsx(Button, { htmlType: "button", size: 32, showTooltipInfo: true, type: "dot", shape: "pill", useBorder: false, icon: "square", onClick: handleStop, ariaLabel: t('training.stop', '정지'), width: "60px", variant: "transparent-white", "aria-hidden": "true", tabIndex: -1, disabled: stateLocal !== 'playMode' }), sourceButtonCount > 1 ? (_jsx("div", { ref: sourceButtonsRef, className: "audio-player__source-buttons", children: Array.from({ length: sourceButtonCount }).map((_, idx) => (_jsx(Button, { htmlType: "button", size: 32, type: "dot", shape: "pill", useBorder: false, label: String(idx + 1), onClick: () => { try {
                                                 handleJumpTo(idx);
                                             }
-                                            catch (e) { } }, ariaLabel: t('training.sourcePlay', { n: idx + 1 }), variant: "transparent-white", selected: 구간표시 && currentIndex === idx, disabled: stateLocal !== 'playMode' || !(Array.isArray(sources) && sources[idx]), showTooltipInfo: true }, idx))) })) : null, (!Array.isArray(sources) || sources.length <= 1) ? (_jsx(Button, { htmlType: "button", size: 32, showTooltipInfo: true, type: "dot", shape: "pill", useBorder: false, icon: "repeat", onClick: handleReplay, ariaLabel: t('common.replay', '다시듣기'), width: "60px", variant: "transparent-white", disabled: stateLocal !== 'playMode' })) : null, _jsx(Button, { htmlType: "button", size: 32, showTooltipInfo: true, type: "dot", shape: "pill", useBorder: false, icon: "skip-forward", onClick: handleNext, ariaLabel: t('training.next', '다음'), width: "60px", variant: "transparent-white", "aria-hidden": true, tabIndex: -1, disabled: stateLocal !== 'playMode' }), _jsx(Button, { htmlType: "button", size: 32, showTooltipInfo: true, type: "dot", shape: "pill", useBorder: false, icon: "check", onClick: handleEnd, ariaLabel: t('common.done', '완료'), width: "60px", variant: "transparent-white", disabled: stateLocal !== 'playMode' })] }), _jsxs("div", { className: "audio-player__slider", children: [_jsx("div", { className: fillClass, ref: fillRef, style: { left: `${fillLeftPercent}%` }, "aria-hidden": "true" }), (showSoundWaveForm || showNoiseWaveForm) && (_jsx(WaveForm, { segments: currentSegments, progress: progress, totalDuration: totalDuration, waveProgressRef: waveProgressRef, showSoundWaveForm: showSoundWaveForm, 
+                                            catch (e) { } }, ariaLabel: t('training.sourcePlay', { n: idx + 1 }), variant: "transparent-white", selected: showRange && currentIndex === idx, disabled: stateLocal !== 'playMode' || !(Array.isArray(sources) && sources[idx]), showTooltipInfo: true }, idx))) })) : null, (!Array.isArray(sources) || sources.length <= 1) ? (_jsx(Button, { htmlType: "button", size: 32, showTooltipInfo: true, type: "dot", shape: "pill", useBorder: false, icon: "repeat", onClick: handleReplay, ariaLabel: t('common.replay', '다시듣기'), width: "60px", variant: "transparent-white", disabled: stateLocal !== 'playMode' })) : null, _jsx(Button, { htmlType: "button", size: 32, showTooltipInfo: true, type: "dot", shape: "pill", useBorder: false, icon: "skip-forward", onClick: handleNext, ariaLabel: t('training.next', '다음'), width: "60px", variant: "transparent-white", "aria-hidden": true, tabIndex: -1, disabled: stateLocal !== 'playMode' }), _jsx(Button, { htmlType: "button", size: 32, showTooltipInfo: true, type: "dot", shape: "pill", useBorder: false, icon: "check", onClick: handleEnd, ariaLabel: t('common.done', '완료'), width: "60px", variant: "transparent-white", disabled: stateLocal !== 'playMode' })] }), _jsxs("div", { className: "audio-player__slider", children: [_jsx("div", { className: fillClass, ref: fillRef, style: { left: `${fillLeftPercent}%` }, "aria-hidden": "true" }), (showSoundWaveForm || showNoiseWaveForm) && (_jsx(WaveForm, { segments: currentSegments, progress: progress, totalDuration: totalDuration, waveProgressRef: waveProgressRef, showSoundWaveForm: showSoundWaveForm, 
                                         /* 뜸도 파형에 그린다((74)) — 2초 단어에 앞뒤 1초면 4초가 한 폭에 들어간다 */
                                         leadInMs: leadInMs, tailMs: tailMs, trackDurationSec: sources?.[currentIndex]?.duration ?? 0, noiseSrc: (showNoiseWaveForm && noisePlayer?.settings.enabled && noiseVolume > 0) ? activeNoiseUrl : null, noiseRatio: noisePlayer ? noiseRatioOf(noisePlayer.settings) : 0, noiseSpeed: noisePlayer?.settings.speed ?? 1, 
                                         /* 그림은 "문장 = 기준" — 문제 소리(M÷R)가 아니라 전체 소리 M 으로 문장을 그리고 소음을 R 배로 키운다 */