@ihabdevteam/core 0.8.0

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

@@ -0,0 +1,26 @@
+/**
+ * 툴팁이 붙을 자리를 잡아 준다.
+ *
+ * 가리키거나(hover) 초점이 닿으면(focus) 그 요소의 화면 좌표를 재서 들고 있고, 벗어나면
+ * 놓는다. 화면 아무 데나 누르면 함께 닫힌다 — 툴팁이 떠 있는 채로 다른 것을 조작하면
+ * 툴팁이 그 위를 덮은 채로 남기 때문이다.
+ *
+ * **초점도 함께 받는 것이 중요하다.** 가리키기만 다루면 마우스 없이 Tab 으로 넘어온
+ * 사람에게는 그 설명이 영영 안 보인다.
+ *
+ * `offsetY` 는 눈속임 보정이다. 잰 좌표 그대로 붙이면 툴팁 꼭지가 단추에 딱 붙어
+ * 답답해 보여서 아래로 조금 민다. 원래 이 값이 `r.top + 8` 처럼 식 한가운데 숫자로
+ * 박혀 있어서, 왜 8인지도 어디서 왔는지도 읽는 사람이 알 길이 없었다.
+ */
+export declare function useAnchorRect({ offsetY }?: {
+    offsetY?: number;
+}): {
+    /** 기준이 될 요소에 붙인다 */
+    ref: import("react").RefObject<HTMLSpanElement | null>;
+    /** 지금 잡아 둔 자리 — 없으면 툴팁을 안 그린다 */
+    rect: DOMRect | null;
+    /** 가리키기·초점 진입 */
+    show: () => void;
+    /** 벗어남·초점 이탈 */
+    hide: () => void;
+};

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

@@ -0,0 +1,52 @@
+'use client';
+import { useCallback, useEffect, useRef, useState } from 'react';
+/**
+ * 툴팁이 붙을 자리를 잡아 준다.
+ *
+ * 가리키거나(hover) 초점이 닿으면(focus) 그 요소의 화면 좌표를 재서 들고 있고, 벗어나면
+ * 놓는다. 화면 아무 데나 누르면 함께 닫힌다 — 툴팁이 떠 있는 채로 다른 것을 조작하면
+ * 툴팁이 그 위를 덮은 채로 남기 때문이다.
+ *
+ * **초점도 함께 받는 것이 중요하다.** 가리키기만 다루면 마우스 없이 Tab 으로 넘어온
+ * 사람에게는 그 설명이 영영 안 보인다.
+ *
+ * `offsetY` 는 눈속임 보정이다. 잰 좌표 그대로 붙이면 툴팁 꼭지가 단추에 딱 붙어
+ * 답답해 보여서 아래로 조금 민다. 원래 이 값이 `r.top + 8` 처럼 식 한가운데 숫자로
+ * 박혀 있어서, 왜 8인지도 어디서 왔는지도 읽는 사람이 알 길이 없었다.
+ */
+export function useAnchorRect({ offsetY = 8 } = {}) {
+    const ref = useRef(null);
+    const [rect, setRect] = useState(null);
+    const hide = useCallback(() => setRect(null), []);
+    const show = useCallback(() => {
+        try {
+            const r = ref.current?.getBoundingClientRect();
+            if (!r)
+                return;
+            setRect({
+                left: r.left, right: r.right, width: r.width, height: r.height, x: r.x,
+                top: r.top + offsetY, bottom: r.bottom + offsetY, y: r.y + offsetY,
+                toJSON: r.toJSON.bind(r),
+            });
+        }
+        catch { /* 아직 화면에 안 붙은 요소 */ }
+    }, [offsetY]);
+    /* 다른 곳을 누르면 닫는다. 떠 있을 때만 듣는다 — 늘 듣고 있으면 이 화면에서 일어나는
+       모든 mousedown 에 쓸데없이 끼어든다. */
+    useEffect(() => {
+        if (!rect)
+            return;
+        document.addEventListener('mousedown', hide);
+        return () => document.removeEventListener('mousedown', hide);
+    }, [rect, hide]);
+    return {
+        /** 기준이 될 요소에 붙인다 */
+        ref,
+        /** 지금 잡아 둔 자리 — 없으면 툴팁을 안 그린다 */
+        rect,
+        /** 가리키기·초점 진입 */
+        show,
+        /** 벗어남·초점 이탈 */
+        hide,
+    };
+}

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

@@ -0,0 +1,11 @@
+import { type MouseEvent } from 'react';
+import type { TrainingItem } from '../../types/training';
+export declare function useAudioPreview(trainingData: TrainingItem | null | undefined, typeKey: string | undefined): {
+    playing: boolean;
+    playingIndex: number;
+    previewUrls: string[];
+    previewHover: boolean;
+    setPreviewHover: import("react").Dispatch<import("react").SetStateAction<boolean>>;
+    previewBtnRef: import("react").RefObject<HTMLDivElement | null>;
+    handlePreview: (e: MouseEvent) => Promise<void>;
+};

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

@@ -0,0 +1,178 @@
+'use client';
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { resolveSoundPath, getSignedOrPublicUrl, downloadSound } from '../../utils/storage';
+function derivePreviewMeta(trainingData, typeKey) {
+    if (!trainingData)
+        return { previewCodes: [], previewBucket: null };
+    const td = trainingData;
+    const pickAll = (arr) => arr
+        .map(item => item?.contextCode || item?.context_code)
+        .filter(Boolean)
+        .map(String);
+    if (typeKey === 'LISTEN_IN_NOISE') {
+        const arr = td.sentences || td.items || [];
+        const codes = Array.isArray(arr) && arr.length > 0 ? pickAll(arr) : [];
+        if (codes.length === 0 && (td.contextCode || td.context_code))
+            codes.push(String(td.contextCode || td.context_code));
+        return { previewCodes: codes, previewBucket: 'LIN_D' };
+    }
+    if (typeKey === 'SHORT_STORY') {
+        const arr = td.items || td.sentences || [];
+        const codes = Array.isArray(arr) && arr.length > 0 ? pickAll(arr) : [];
+        if (codes.length === 0 && (td.contextCode || td.context_code))
+            codes.push(String(td.contextCode || td.context_code));
+        return { previewCodes: codes, previewBucket: 'SHORT_S' };
+    }
+    if (typeKey === 'LONG_STORY') {
+        const arr = td.items || td.sentences || [];
+        const codes = Array.isArray(arr) && arr.length > 0 ? pickAll(arr) : [];
+        if (codes.length === 0 && (td.contextCode || td.context_code))
+            codes.push(String(td.contextCode || td.context_code));
+        return { previewCodes: codes, previewBucket: 'LONG' };
+    }
+    if (typeKey === 'ORDERING_SENTENCE') {
+        const arr = td.sentences || td.items || [];
+        const codes = Array.isArray(arr) && arr.length > 0 ? pickAll(arr) : [];
+        if (codes.length === 0 && (td.contextCode || td.context_code))
+            codes.push(String(td.contextCode || td.context_code));
+        return { previewCodes: codes, previewBucket: 'LIN_D' };
+    }
+    const arr = td.sentences || td.items || [];
+    const codes = pickAll(Array.isArray(arr) ? arr : []);
+    if (codes.length === 0 && (td.contextCode || td.context_code))
+        codes.push(String(td.contextCode || td.context_code));
+    return { previewCodes: codes, previewBucket: null };
+}
+export function useAudioPreview(trainingData, typeKey) {
+    const [playing, setPlaying] = useState(false);
+    const [playingIndex, setPlayingIndex] = useState(-1);
+    const [previewUrls, setPreviewUrls] = useState([]);
+    const previewAudioRef = useRef(null);
+    const playingRef = useRef(false);
+    const previewBtnRef = useRef(null);
+    const [previewHover, setPreviewHover] = useState(false);
+    // downloadSound()로 만든 blob URL만 추적 — getSignedOrPublicUrl()이 반환하는 http(s) URL은
+    // 우리가 만든 게 아니므로 revoke 대상이 아니다
+    const ownedBlobUrlsRef = useRef([]);
+    const { previewCodes, previewBucket } = derivePreviewMeta(trainingData, typeKey);
+    // Resolve audio URLs upfront when training data changes
+    useEffect(() => {
+        if (!previewCodes.length)
+            return;
+        let cancelled = false;
+        (async () => {
+            const resolvedUrls = [];
+            const newBlobUrls = [];
+            for (const code of previewCodes) {
+                try {
+                    const path = resolveSoundPath(code, previewBucket);
+                    if (!path) {
+                        resolvedUrls.push('');
+                        continue;
+                    }
+                    let url = null;
+                    try {
+                        url = await getSignedOrPublicUrl(path);
+                    }
+                    catch (_e) { }
+                    if (!url) {
+                        try {
+                            const blob = await downloadSound(path);
+                            if (blob) {
+                                url = URL.createObjectURL(blob);
+                                newBlobUrls.push(url);
+                            }
+                        }
+                        catch (_e) { }
+                    }
+                    resolvedUrls.push(url ?? '');
+                }
+                catch (_e) {
+                    resolvedUrls.push('');
+                }
+            }
+            if (!cancelled) {
+                // 이전 배치의 blob URL들을 교체 시점에 해제
+                ownedBlobUrlsRef.current.forEach(u => { try {
+                    URL.revokeObjectURL(u);
+                }
+                catch { } });
+                ownedBlobUrlsRef.current = newBlobUrls;
+                setPreviewUrls(resolvedUrls);
+            }
+            else {
+                // 이 effect가 취소된 사이 새로 만든 blob은 ref에 등록되지 못하므로 즉시 해제
+                newBlobUrls.forEach(u => { try {
+                    URL.revokeObjectURL(u);
+                }
+                catch { } });
+            }
+        })();
+        return () => { cancelled = true; };
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [previewCodes.join(','), previewBucket]);
+    // 언마운트 시 마지막 배치의 blob URL 해제
+    useEffect(() => {
+        return () => {
+            ownedBlobUrlsRef.current.forEach(u => { try {
+                URL.revokeObjectURL(u);
+            }
+            catch { } });
+            ownedBlobUrlsRef.current = [];
+        };
+    }, []);
+    const handlePreview = useCallback(async (e) => {
+        e.stopPropagation();
+        e.preventDefault();
+        if (playingRef.current) {
+            playingRef.current = false;
+            try {
+                previewAudioRef.current?.pause();
+            }
+            catch { }
+            setPlaying(false);
+            setPlayingIndex(-1);
+            return;
+        }
+        const urls = previewUrls.filter(Boolean);
+        if (!urls.length)
+            return;
+        playingRef.current = true;
+        setPlaying(true);
+        for (let i = 0; i < previewUrls.length; i++) {
+            if (!playingRef.current)
+                break;
+            const url = previewUrls[i];
+            if (!url)
+                continue;
+            setPlayingIndex(i);
+            try {
+                await new Promise((resolve, reject) => {
+                    const audio = new Audio(url);
+                    previewAudioRef.current = audio;
+                    audio.onended = () => resolve();
+                    audio.onerror = () => reject();
+                    audio.play().catch(reject);
+                });
+            }
+            catch {
+                break;
+            }
+        }
+        playingRef.current = false;
+        setPlaying(false);
+        setPlayingIndex(-1);
+    }, [previewUrls]);
+    // Pause and release audio on unmount
+    useEffect(() => {
+        return () => {
+            playingRef.current = false;
+            try {
+                previewAudioRef.current?.pause();
+            }
+            catch { }
+            previewAudioRef.current = null;
+        };
+    }, []);
+    return { playing, playingIndex, previewUrls, previewHover, setPreviewHover, previewBtnRef, handlePreview };
+}

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

@@ -0,0 +1,24 @@
+import { type RefObject } from 'react';
+import type { NoisePlayerContextValue } from './NoisePlayerContext';
+type PlaybackState = 'stopped' | 'playing' | 'paused';
+/**
+ * TrainingStepAudioPlayer에서 분리 — 소음(noise) 오디오 엘리먼트 생성/페이드인/페이드아웃/워치독을
+ * 전담한다. audioRef(메인 문장 오디오)·playbackStateRef는 메인 컴포넌트 소유라 그대로 전달받는다.
+ */
+export declare function useNoiseFade({ noisePlayer, audioRef, playbackStateRef, }: {
+    noisePlayer: NoisePlayerContextValue | null;
+    audioRef: RefObject<HTMLAudioElement | null>;
+    playbackStateRef: RefObject<PlaybackState>;
+}): {
+    noiseAudioRef: RefObject<HTMLAudioElement | null>;
+    activeNoiseUrl: string | null;
+    noiseSettingsRef: RefObject<{
+        enabled: boolean;
+        level: number;
+        type: string;
+    } | null>;
+    cancelNoiseFade: () => void;
+    fadeInNoise: (targetVolume: number, durationMs?: number) => void;
+    fadeOutNoise: (durationMs?: number, onComplete?: () => void) => void;
+};
+export {};

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

@@ -0,0 +1,303 @@
+'use client';
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { noiseAssets } from '../../sounds/noiseAssets';
+import { getElementAnalyser, resumeAudioMeter } from '../../utils/audioMeter';
+function generateNoiseUrl(type) {
+    const rand = Math.floor(Math.random() * 10);
+    switch (type) {
+        case 'defaultNoise': return noiseAssets.defaultNoise;
+        case 'street': return noiseAssets.street[rand];
+        case 'restaurant': return noiseAssets.restaurant[rand];
+        case 'buzz': return noiseAssets.buzz;
+        default: return null;
+    }
+}
+/**
+ * TrainingStepAudioPlayer에서 분리 — 소음(noise) 오디오 엘리먼트 생성/페이드인/페이드아웃/워치독을
+ * 전담한다. audioRef(메인 문장 오디오)·playbackStateRef는 메인 컴포넌트 소유라 그대로 전달받는다.
+ */
+export function useNoiseFade({ noisePlayer, audioRef, playbackStateRef, }) {
+    const registerAnalyserRef = useRef(noisePlayer?.registerAnalyser);
+    registerAnalyserRef.current = noisePlayer?.registerAnalyser;
+    const noiseAudioRef = useRef(null);
+    // 실제 로드된(재생되는) 소음 파일 URL — waveform이 화면=청취 일치하도록 이 src를 그린다.
+    const [activeNoiseUrl, setActiveNoiseUrl] = useState(null);
+    const noiseTypeLoadedRef = useRef(null);
+    const noiseSettingsRef = useRef(null);
+    const noiseFadeRafRef = useRef(null);
+    // 페이드 세대 토큰 — 하드스톱 타이머가 발화 시점에 "그 사이 새 페이드가 시작됐는지"를
+    // 판별해, 이미 다른 의도(fadeIn 등)로 대체된 정지를 실행하지 않게 한다.
+    const noiseFadeTokenRef = useRef(0);
+    const noiseHardStopTimerRef = useRef(null);
+    const cancelNoiseFade = useCallback(() => {
+        if (noiseFadeRafRef.current !== null) {
+            cancelAnimationFrame(noiseFadeRafRef.current);
+            noiseFadeRafRef.current = null;
+        }
+        if (noiseHardStopTimerRef.current !== null) {
+            clearTimeout(noiseHardStopTimerRef.current);
+            noiseHardStopTimerRef.current = null;
+        }
+    }, []);
+    const fadeInNoise = useCallback((targetVolume, durationMs = 250) => {
+        const noiseEl = noiseAudioRef.current;
+        if (!noiseEl || !noiseEl.src)
+            return;
+        noiseFadeTokenRef.current += 1;
+        cancelNoiseFade();
+        // 미터: 소음 재생 시점에 context resume 후 소음 analyser 등록
+        try {
+            resumeAudioMeter();
+            registerAnalyserRef.current?.('noise', getElementAnalyser(noiseEl));
+        }
+        catch (e) { }
+        // 이미 재생 중이면(멀티소스 연달아 재생 — 단어1→단어2 전환마다 onPlay가 다시 호출됨)
+        // 볼륨을 0으로 리셋하지 않고 현재 볼륨에서 목표까지 부드럽게 이어간다 — 트랙 전환 때마다
+        // 소음이 뚝 끊겼다 다시 차오르던 문제 방지. 이미 목표 볼륨이면 램프가 사실상 no-op이다.
+        const startVol = noiseEl.paused ? 0 : noiseEl.volume;
+        if (noiseEl.paused)
+            noiseEl.volume = 0;
+        noiseEl.play().catch(() => { });
+        const startTime = performance.now();
+        const step = () => {
+            const t = Math.min(1, (performance.now() - startTime) / durationMs);
+            try {
+                noiseEl.volume = Math.max(0, Math.min(1, startVol + (targetVolume - startVol) * t));
+            }
+            catch (e) { }
+            if (t < 1) {
+                noiseFadeRafRef.current = requestAnimationFrame(step);
+            }
+            else {
+                noiseFadeRafRef.current = null;
+            }
+        };
+        noiseFadeRafRef.current = requestAnimationFrame(step);
+    }, [cancelNoiseFade]);
+    const fadeOutNoise = useCallback((durationMs = 250, onComplete) => {
+        const noiseEl = noiseAudioRef.current;
+        if (!noiseEl || noiseEl.paused) {
+            onComplete?.();
+            return;
+        }
+        const token = ++noiseFadeTokenRef.current;
+        cancelNoiseFade();
+        const startTime = performance.now();
+        const startVol = noiseEl.volume;
+        const step = () => {
+            const t = Math.min(1, (performance.now() - startTime) / durationMs);
+            try {
+                noiseEl.volume = Math.max(0, startVol * (1 - t));
+            }
+            catch (e) { }
+            if (t < 1) {
+                noiseFadeRafRef.current = requestAnimationFrame(step);
+            }
+            else {
+                noiseFadeRafRef.current = null;
+                if (noiseHardStopTimerRef.current !== null) {
+                    clearTimeout(noiseHardStopTimerRef.current);
+                    noiseHardStopTimerRef.current = null;
+                }
+                try {
+                    noiseEl.pause();
+                }
+                catch (e) { }
+                onComplete?.();
+            }
+        };
+        noiseFadeRafRef.current = requestAnimationFrame(step);
+        // 하드스톱 보장 — 볼륨 램프는 RAF 체인이라 백그라운드 탭(RAF 정지)이나 다른 페이드의
+        // 개입(cancelNoiseFade)으로 완주하지 못하면 pause()가 영영 실행되지 않는다. 램프와
+        // 무관하게 타이머로 정지를 보장하되, 이후 새 페이드(fadeInNoise 등)가 시작됐다면
+        // (토큰 변경) 그 의도를 존중해 건너뛴다.
+        noiseHardStopTimerRef.current = setTimeout(() => {
+            noiseHardStopTimerRef.current = null;
+            if (noiseFadeTokenRef.current !== token)
+                return;
+            if (noiseFadeRafRef.current !== null) {
+                cancelAnimationFrame(noiseFadeRafRef.current);
+                noiseFadeRafRef.current = null;
+            }
+            try {
+                if (!noiseEl.paused) {
+                    noiseEl.volume = 0;
+                    noiseEl.pause();
+                    onComplete?.();
+                }
+            }
+            catch (e) { }
+        }, durationMs + 150);
+    }, [cancelNoiseFade]);
+    // 소음 audio element 생성/정리
+    useEffect(() => {
+        const noiseEl = document.createElement('audio');
+        noiseEl.loop = true;
+        // 메인 <audio>와 동일하게 crossOrigin 필수 — 소음도 레벨 미터용 Web Audio 그래프
+        // (getElementAnalyser)에 연결되는데, cross-origin 미디어를 crossOrigin 없이 연결하면
+        // 브라우저가 보안상 그래프 출력을 강제 무음 처리해 재생은 되는데 소리가 안 난다.
+        noiseEl.crossOrigin = 'anonymous';
+        noiseAudioRef.current = noiseEl;
+        return () => {
+            cancelNoiseFade();
+            try {
+                noiseEl.pause();
+                noiseEl.src = '';
+            }
+            catch (e) { }
+            noiseAudioRef.current = null;
+        };
+    }, [cancelNoiseFade]);
+    // 소음 감시(watchdog) — 메인이 재생 중이 아닌데 소음만 재생 중이면 강제로 정지한다.
+    // fadeOutNoise는 250ms 볼륨 램프가 "끝난 뒤"에야 pause()를 호출하는 구조라, 램프 도중
+    // 다른 페이드(fadeInNoise 등)가 cancelNoiseFade로 끊으면 볼륨만 낮아진 채 영영 정지되지
+    // 않는 상태가 남을 수 있다(재생 종료/일시정지 이벤트의 온갖 인터리빙에서 재현됨).
+    // 개별 레이스를 전부 틀어막는 대신, 잘못된 상태를 주기적으로 감지해 회수한다.
+    // 두 번 연속(약 0.8초) 확인 후에 정지 — 멀티소스 트랙 전환처럼 메인이 잠깐 멈추는
+    // 정상 구간에서 소음이 출렁이지 않게 하기 위한 유예다.
+    const noiseInUse = !!noisePlayer?.settings.enabled && (noisePlayer?.settings.level ?? 0) > 0;
+    useEffect(() => {
+        // 소음이 이번 재생 세션에서 아예 꺼져 있으면(noiseInUse=false) noiseEl은 절대
+        // 재생되지 않으므로(모든 fadeInNoise 호출부가 동일한 enabled/level 조건으로 감싸져
+        // 있음) 이 감시 자체가 no-op이다 — 타이머를 아예 돌리지 않는다.
+        if (!noiseInUse)
+            return;
+        let misses = 0;
+        const iv = setInterval(() => {
+            const noiseEl = noiseAudioRef.current;
+            if (!noiseEl || noiseEl.paused) {
+                misses = 0;
+                return;
+            }
+            const a = audioRef.current;
+            const mainPlaying = !!a && !a.paused && !a.ended;
+            // speechSynthesis TTS 경로는 main <audio> 없이 재생되므로 playbackState도 함께 본다
+            if (mainPlaying || playbackStateRef.current === 'playing') {
+                misses = 0;
+                return;
+            }
+            misses += 1;
+            if (misses >= 2) {
+                misses = 0;
+                fadeOutNoise();
+            }
+        }, 400);
+        return () => clearInterval(iv);
+    }, [fadeOutNoise, noiseInUse, audioRef, playbackStateRef]);
+    // 탭 백그라운드 전환 시 소음 즉시 정지 — 백그라운드 탭에서는 requestAnimationFrame이
+    // 멈추거나 크게 스로틀돼 fadeOutNoise의 볼륨 램프가 완주하지 못할 수 있어, 페이드 없이
+    // 바로 pause한다. 탭 복귀 시 자동 재개는 하지 않는다 — 메인 오디오가 재생 중이면 기존
+    // 소음 설정 useEffect(레벨/타입 변경 등)가 다시 fadeInNoise를 트리거하고, 아니라면
+    // 사용자가 의도적으로 멈춘 것과 구분이 안 되므로 그대로 둔다.
+    useEffect(() => {
+        const handleVisibilityChange = () => {
+            if (!document.hidden)
+                return;
+            const noiseEl = noiseAudioRef.current;
+            if (noiseEl && !noiseEl.paused) {
+                cancelNoiseFade();
+                try {
+                    noiseEl.pause();
+                }
+                catch (e) { }
+            }
+        };
+        document.addEventListener('visibilitychange', handleVisibilityChange);
+        return () => document.removeEventListener('visibilitychange', handleVisibilityChange);
+    }, [cancelNoiseFade]);
+    // noiseSettingsRef 최신화 (재생 이벤트 핸들러 클로저에서 사용)
+    useEffect(() => {
+        noiseSettingsRef.current = noisePlayer
+            ? { enabled: noisePlayer.settings.enabled, level: noisePlayer.settings.level, type: noisePlayer.settings.type }
+            : null;
+    }, [noisePlayer, noisePlayer?.settings.enabled, noisePlayer?.settings.level, noisePlayer?.settings.type]);
+    // 소음 설정 변경 → 오디오 반영
+    useEffect(() => {
+        const ns = noisePlayer?.settings;
+        const noiseEl = noiseAudioRef.current;
+        if (!noiseEl)
+            return;
+        if (!ns || !ns.enabled || ns.level === 0) {
+            fadeOutNoise();
+            return;
+        }
+        const volume = Math.min(1, ns.level / 9);
+        if (noiseTypeLoadedRef.current !== ns.type) {
+            // 타입 변경: 새 파일 로드
+            const url = generateNoiseUrl(ns.type);
+            if (url) {
+                noiseTypeLoadedRef.current = ns.type;
+                setActiveNoiseUrl(url); // waveform이 실제 재생 파일을 그리도록
+                fadeOutNoise(150, () => {
+                    noiseEl.src = url;
+                    noiseEl.load();
+                    const mainAudio = audioRef.current;
+                    if (mainAudio && !mainAudio.paused) {
+                        noiseEl.addEventListener('canplay', function h() {
+                            noiseEl.removeEventListener('canplay', h);
+                            // 파일 로드가 끝난 "이 시점"에 메인이 여전히 재생 중인지 재확인 —
+                            // 로드가 느리면 예약 시점과 실행 시점 사이에 메인이 끝났을 수 있다.
+                            const cur = audioRef.current;
+                            if (cur && !cur.paused && !cur.ended)
+                                fadeInNoise(volume);
+                        });
+                    }
+                });
+            }
+        }
+        else {
+            // 레벨만 변경(또는 mainVolume/mainSpeed 변경으로 settings 객체 참조만 바뀐 경우):
+            // 볼륨 반영은 메인이 실제로 재생 중일 때만. 재생 소리/속도가 같은 noiseSettings 객체에
+            // 저장되면서, 문장 재생이 끝난 뒤 이 슬라이더만 바꿔도 이 useEffect가 재실행되는데
+            // — 그때 noiseEl이 아직(레이스 등으로) paused가 아니면 볼륨만 올려버려 소음이 계속
+            // 나오는 버그가 있었다. 메인이 재생 중이 아니면 무조건 정지시킨다.
+            const mainAudio = audioRef.current;
+            const mainPlaying = !!mainAudio && !mainAudio.paused && !mainAudio.ended;
+            if (mainPlaying && noiseEl.paused && noiseEl.src) {
+                fadeInNoise(volume);
+            }
+            else if (!noiseEl.paused) {
+                if (!mainPlaying) {
+                    // 메인이 재생 중이 아닌데 소음만 재생 중이면(레이스 등으로) 정지
+                    fadeOutNoise();
+                }
+                else {
+                    // 이미 재생 중 — 볼륨만 부드럽게 조절
+                    cancelNoiseFade();
+                    const startVol = noiseEl.volume;
+                    const startTime = performance.now();
+                    const ramp = () => {
+                        const t = Math.min(1, (performance.now() - startTime) / 150);
+                        try {
+                            noiseEl.volume = startVol + (volume - startVol) * t;
+                        }
+                        catch (e) { }
+                        if (t < 1)
+                            noiseFadeRafRef.current = requestAnimationFrame(ramp);
+                        else
+                            noiseFadeRafRef.current = null;
+                    };
+                    noiseFadeRafRef.current = requestAnimationFrame(ramp);
+                }
+            }
+        }
+    }, [noisePlayer?.settings, noisePlayer?.settings.enabled, noisePlayer?.settings.level, noisePlayer?.settings.type, cancelNoiseFade, fadeInNoise, fadeOutNoise, audioRef]);
+    // 소음 재생 속도(playbackRate) 반영 — 0.75~1.25. 엘리먼트 속성이라 src 변경에도 유지됨
+    useEffect(() => {
+        const el = noiseAudioRef.current;
+        if (el) {
+            try {
+                el.playbackRate = Math.min(1.25, Math.max(0.75, noisePlayer?.settings.speed ?? 1));
+            }
+            catch (e) { }
+        }
+    }, [noisePlayer?.settings.speed]);
+    return {
+        noiseAudioRef,
+        activeNoiseUrl,
+        noiseSettingsRef,
+        cancelNoiseFade,
+        fadeInNoise,
+        fadeOutNoise,
+    };
+}

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

@@ -0,0 +1,25 @@
+/**
+ * 만들어 놓은 blob URL 을 빠짐없이 되돌려준다.
+ *
+ * 소리 파일을 직접 내려받아 재생하는 폴백 경로에서 `URL.createObjectURL` 로 임시 주소를
+ * 만든다. 이 주소는 **브라우저가 알아서 안 치운다** — 문서가 살아 있는 한 그 blob 이
+ * 메모리에 남는다. 훈련 화면은 한 세션에서 소리를 수십 개 갈아 끼우므로, 한 번 빠뜨리면
+ * 그만큼 그대로 쌓인다. 눈에 보이는 증상은 없고 탭이 점점 무거워질 뿐이라 **알아채기가
+ * 가장 어려운 종류의 새는 자리**다.
+ *
+ * 규칙은 둘뿐이다.
+ *
+ *  1. 만들면 **반드시** 여기에 맡긴다(`track`).
+ *  2. 소스 목록이 바뀌면 **남을 것만 남기고 나머지는 되돌려준다**(`keepOnly`).
+ *     화면을 떠날 때는 전부 되돌려준다.
+ *
+ * 원래 `TrainingStepAudioPlayer` 안에 ref 둘로 있었는데, 그중 하나(`objectUrlRef`,
+ * "지금 재생 중인 하나")는 **null 만 대입되고 URL 이 들어가는 곳이 없어서** 그 옆의
+ * `revokeObjectURL` 이 한 번도 실행된 적이 없었다. 다행히 실제 회수는 나머지 하나가
+ * 전부 하고 있어 새지는 않았다. 죽은 반쪽을 걷어내고 살아 있는 규칙만 남긴다.
+ */
+export declare function useObjectUrls(): {
+    track: (url: string) => string;
+    keepOnly: (keep: Iterable<string | undefined | null>) => void;
+    revokeAll: () => void;
+};