@ihabdevteam/core 0.266.0 → 0.268.0

package/dist/ihabdevteam-core.d.ts

@@ -1651,7 +1651,7 @@ export declare function copyText(text: string): Promise<boolean>;
  *
  * 값은 손으로 적고 `test/coreVersion.test.ts` 가 package.json 과 어긋나면 운다.
  */
-export declare const CORE_VERSION = "0.266.0";
+export declare const CORE_VERSION = "0.268.0";
 
 /** @public */
 declare const coreDefault: Record<string, unknown>;
@@ -9039,7 +9039,7 @@ export declare type TrainingStepConfirmWithTextProps = {
 };
 
 /** @public */
-export declare function TrainingStepListen({ index, stepIndex, isLast, title, onDone, btnLabel, soundSrc, bucketPath, usePreviewTextBtn, previewText, onPreviewTextBtn, disabled, _pageIndex, showSoundWaveForm, showNoiseWaveForm }: TrainingStepListenProps): JSX.Element;
+export declare function TrainingStepListen({ index, stepIndex, isLast, title, onDone, btnLabel, soundSrc, bucketPath, usePreviewTextBtn, previewText, onPreviewTextBtn, disabled, _pageIndex, showSoundWaveForm, showNoiseWaveForm, leadInMs, tailMs }: TrainingStepListenProps): JSX.Element;
 
 /** @public */
 export declare type TrainingStepListenProps = {
@@ -9063,6 +9063,19 @@ export declare type TrainingStepListenProps = {
     showSoundWaveForm?: boolean;
     /** 소음 waveform 표시 여부. 기본 true. */
     showNoiseWaveForm?: boolean;
+    /**
+     * **소리 앞에 두는 뜸**(밀리초). 기본 0 — 안 주면 전과 똑같이 돈다.
+     * 그대로 `TrainingStepAudioPlayer` 로 간다.
+     *
+     * 앱은 재생기를 직접 세우지 않는다 — 훈련 러너 여섯이 전부
+     * `TrainingPagePopup.ListenStep` 으로 짓고 그 길이 여기를 지난다. 그래서 재생기에만
+     * 더하면 **앱까지 닿지 않는다**(말귀 실측, 2026-10-05: (74) 가 0.266.0 으로 나갔는데
+     * 앱은 임시 자를 못 걷었다). 재생기에 프롭을 더하면 여기도 함께 더한다 —
+     * `test/trainingStepListenForwards.test.ts` 가 빠진 것을 센다.
+     */
+    leadInMs?: number;
+    /** **소리가 끝난 뒤 뜸**(밀리초). 기본 0. 위 `leadInMs` 와 같은 자리에서 왔다. */
+    tailMs?: number;
 };
 
 export declare function TrainingStepOrderList({ index, stepIndex, isLast, title, onDone, onChange, context, }: TrainingStepOrderListProps): JSX.Element;

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

@@ -190,6 +190,7 @@ export default function TrainingStepAudioPlayer({ btnLabel, soundSrc, bucketPath
         noisePlayer,
         audioRef,
         playbackStateRef,
+        padRef: 뜸Ref,
     });
     const { startTTS: 합성시작, stopTTS } = useTTSPlayback({
         ttsText,
@@ -286,6 +287,19 @@ export default function TrainingStepAudioPlayer({ btnLabel, soundSrc, bucketPath
            먼저 켠다(소리가 날 때 오는 `play` 이벤트가 아니라 **여기**가 시작이다). */
         if (leadInMsRef.current > 0) {
             startTicker();
+            /* **소음은 뜸부터 깔린다.** 사용자가 (74) 를 말할 때 기준으로 삼은 것이 "노이즈가
+               나오는 순간" 이었다 — 그 순간이 단어와 같이 오면 뜸을 둔 뜻이 없다. 소리가 터지지
+               않게 하려고 둔 구간인데 거기가 **완전한 무음**이면, 단어가 소음과 함께 들이닥치는
+               것은 그대로다. 뜸 동안 소음만 깔려 있어야 귀가 먼저 자리를 잡는다.
+               `onPlay` 에도 같은 호출이 있다 — 이미 돌고 있으면 `fadeInNoise` 는 지금 볼륨에서
+               목표까지 이어 가므로(멀티소스 전환 때문에 그렇게 돼 있다) 두 번 불려도 끊기지 않는다. */
+            const ns = noiseSettingsRef.current;
+            if (ns?.enabled && (ns.volume ?? 0) > 0) {
+                try {
+                    fadeInNoise(ns.volume);
+                }
+                catch (e) { }
+            }
             if (!(await 뜸기다리기(leadInMsRef.current, 'lead')))
                 return false;
             if (!mountedRef.current || 의도 !== 재생의도Ref.current)
@@ -327,7 +341,7 @@ export default function TrainingStepAudioPlayer({ btnLabel, soundSrc, bucketPath
         }
         catch (_) { }
         return false;
-    }, [t, startTicker, 뜸기다리기]);
+    }, [t, startTicker, 뜸기다리기, fadeInNoise, noiseSettingsRef]);
     const attachAudioListeners = useCallback(() => {
         const a = audioRef.current;
         if (!a)

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

@@ -22,6 +22,19 @@ export type TrainingStepListenProps = {
     showSoundWaveForm?: boolean;
     /** 소음 waveform 표시 여부. 기본 true. */
     showNoiseWaveForm?: boolean;
+    /**
+     * **소리 앞에 두는 뜸**(밀리초). 기본 0 — 안 주면 전과 똑같이 돈다.
+     * 그대로 `TrainingStepAudioPlayer` 로 간다.
+     *
+     * 앱은 재생기를 직접 세우지 않는다 — 훈련 러너 여섯이 전부
+     * `TrainingPagePopup.ListenStep` 으로 짓고 그 길이 여기를 지난다. 그래서 재생기에만
+     * 더하면 **앱까지 닿지 않는다**(말귀 실측, 2026-10-05: (74) 가 0.266.0 으로 나갔는데
+     * 앱은 임시 자를 못 걷었다). 재생기에 프롭을 더하면 여기도 함께 더한다 —
+     * `test/trainingStepListenForwards.test.ts` 가 빠진 것을 센다.
+     */
+    leadInMs?: number;
+    /** **소리가 끝난 뒤 뜸**(밀리초). 기본 0. 위 `leadInMs` 와 같은 자리에서 왔다. */
+    tailMs?: number;
 };
 /** @public */
-export default function TrainingStepListen({ index, stepIndex, isLast, title, onDone, btnLabel, soundSrc, bucketPath, usePreviewTextBtn, previewText, onPreviewTextBtn, disabled, _pageIndex, showSoundWaveForm, showNoiseWaveForm }: TrainingStepListenProps): import("react").JSX.Element;
+export default function TrainingStepListen({ index, stepIndex, isLast, title, onDone, btnLabel, soundSrc, bucketPath, usePreviewTextBtn, previewText, onPreviewTextBtn, disabled, _pageIndex, showSoundWaveForm, showNoiseWaveForm, leadInMs, tailMs }: TrainingStepListenProps): import("react").JSX.Element;

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

@@ -5,9 +5,9 @@ import TrainingStepAudioPlayer from './TrainingStepAudioPlayer';
 import "./TrainingStep.css";
 import TrainingStep from "./TrainingStep";
 /** @public */
-export default function TrainingStepListen({ index, stepIndex, isLast = false, title, onDone, btnLabel, soundSrc, bucketPath, usePreviewTextBtn, previewText = null, onPreviewTextBtn, disabled, _pageIndex, showSoundWaveForm, showNoiseWaveForm }) {
+export default function TrainingStepListen({ index, stepIndex, isLast = false, title, onDone, btnLabel, soundSrc, bucketPath, usePreviewTextBtn, previewText = null, onPreviewTextBtn, disabled, _pageIndex, showSoundWaveForm, showNoiseWaveForm, leadInMs, tailMs }) {
     const { t } = useTranslation();
     const resolvedTitle = title ?? t('training.listenTitle', '제시하는 문장을 들어주세요.');
     const effectiveDisabled = disabled ?? (typeof stepIndex === 'number' && typeof index === 'number' ? index > stepIndex : false);
-    return (_jsx(TrainingStep, { index: index, stepIndex: stepIndex, isLast: isLast, title: resolvedTitle, onDone: onDone, titleProps: { usePreviewTextBtn, previewText, onPreviewTextBtn }, children: _jsx(TrainingStepAudioPlayer, { soundSrc: soundSrc, ttsText: !soundSrc ? (previewText ?? resolvedTitle) : null, bucketPath: bucketPath, btnLabel: btnLabel || t('training.listenButton', '문장 듣기'), disabled: effectiveDisabled, className: "training-step__listen-sticky", showSoundWaveForm: showSoundWaveForm, showNoiseWaveForm: showNoiseWaveForm }, `audio-p${_pageIndex ?? 0}-s${index}`) }));
+    return (_jsx(TrainingStep, { index: index, stepIndex: stepIndex, isLast: isLast, title: resolvedTitle, onDone: onDone, titleProps: { usePreviewTextBtn, previewText, onPreviewTextBtn }, children: _jsx(TrainingStepAudioPlayer, { soundSrc: soundSrc, ttsText: !soundSrc ? (previewText ?? resolvedTitle) : null, bucketPath: bucketPath, btnLabel: btnLabel || t('training.listenButton', '문장 듣기'), disabled: effectiveDisabled, className: "training-step__listen-sticky", showSoundWaveForm: showSoundWaveForm, showNoiseWaveForm: showNoiseWaveForm, leadInMs: leadInMs, tailMs: tailMs }, `audio-p${_pageIndex ?? 0}-s${index}`) }));
 }

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

@@ -5,10 +5,22 @@ type PlaybackState = 'stopped' | 'playing' | 'paused';
  * TrainingStepAudioPlayer에서 분리 — 소음(noise) 오디오 엘리먼트 생성/페이드인/페이드아웃/워치독을
  * 전담한다. audioRef(메인 문장 오디오)·playbackStateRef는 메인 컴포넌트 소유라 그대로 전달받는다.
  */
-export declare function useNoiseFade({ noisePlayer, audioRef, playbackStateRef, }: {
+export declare function useNoiseFade({ noisePlayer, audioRef, playbackStateRef, padRef, }: {
     noisePlayer: NoisePlayerContextValue | null;
     audioRef: RefObject<HTMLAudioElement | null>;
     playbackStateRef: RefObject<PlaybackState>;
+    /**
+     * **앞뒤 뜸 구간인가**(말귀 요청 (74), 2026-10-05).
+     *
+     * 뜸 동안 메인 `<audio>` 는 **멈춰 있다** — 앞 뜸에는 아직 `play()` 전이고, 뒤 뜸에는
+     * 이미 `ended` 다. 그래서 "메인이 도나" 만 보는 자리들이 **뜸을 재생이 끝난 것으로 읽어**
+     * 소음을 걷는다. 특히 아래 감시 타이머는 0.8초 뒤에 내리므로, 1000ms 뜸은 **800ms 에서
+     * 소음이 꺼진다.** 뜸은 소리가 안 나는 구간이지 **재생이 끝난 구간이 아니다.**
+     */
+    padRef?: RefObject<{
+        phase: 'lead' | 'sound' | 'tail';
+        at: number;
+    }>;
 }): {
     noiseAudioRef: RefObject<HTMLAudioElement | null>;
     activeNoiseUrl: string | null;

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

@@ -17,7 +17,7 @@ function generateNoiseUrl(type) {
  * TrainingStepAudioPlayer에서 분리 — 소음(noise) 오디오 엘리먼트 생성/페이드인/페이드아웃/워치독을
  * 전담한다. audioRef(메인 문장 오디오)·playbackStateRef는 메인 컴포넌트 소유라 그대로 전달받는다.
  */
-export function useNoiseFade({ noisePlayer, audioRef, playbackStateRef, }) {
+export function useNoiseFade({ noisePlayer, audioRef, playbackStateRef, padRef, }) {
     const registerAnalyserRef = useRef(noisePlayer?.registerAnalyser);
     registerAnalyserRef.current = noisePlayer?.registerAnalyser;
     const noiseAudioRef = useRef(null);
@@ -35,6 +35,11 @@ export function useNoiseFade({ noisePlayer, audioRef, playbackStateRef, }) {
     // 판별해, 이미 다른 의도(fadeIn 등)로 대체된 정지를 실행하지 않게 한다.
     const noiseFadeTokenRef = useRef(0);
     const noiseHardStopTimerRef = useRef(null);
+    /** 지금 뜸 구간인가 — `at` 이 0 이면 뜸이 아니다(소리 구간으로 돌려놓은 표시) */
+    const 뜸중 = useCallback(() => {
+        const p = padRef?.current;
+        return !!p && p.phase !== 'sound' && p.at > 0;
+    }, [padRef]);
     const cancelNoiseFade = useCallback(() => {
         if (noiseFadeRafRef.current !== null) {
             cancelAnimationFrame(noiseFadeRafRef.current);
@@ -201,7 +206,8 @@ export function useNoiseFade({ noisePlayer, audioRef, playbackStateRef, }) {
             const a = audioRef.current;
             const mainPlaying = !!a && !a.paused && !a.ended;
             // speechSynthesis TTS 경로는 main <audio> 없이 재생되므로 playbackState도 함께 본다
-            if (mainPlaying || playbackStateRef.current === 'playing') {
+            // 뜸 구간은 메인이 멈춰 있어도 **재생 중**이다 — 안 보면 1000ms 뜸의 800ms 에 소음이 꺼진다
+            if (mainPlaying || 뜸중() || playbackStateRef.current === 'playing') {
                 misses = 0;
                 return;
             }
@@ -212,7 +218,7 @@ export function useNoiseFade({ noisePlayer, audioRef, playbackStateRef, }) {
             }
         }, 400);
         return () => clearInterval(iv);
-    }, [fadeOutNoise, noiseInUse, audioRef, playbackStateRef]);
+    }, [fadeOutNoise, noiseInUse, audioRef, playbackStateRef, 뜸중]);
     // 탭 백그라운드 전환 시 소음 즉시 정지 — 백그라운드 탭에서는 requestAnimationFrame이
     // 멈추거나 크게 스로틀돼 fadeOutNoise의 볼륨 램프가 완주하지 못할 수 있어, 페이드 없이
     // 바로 pause한다.
@@ -235,14 +241,14 @@ export function useNoiseFade({ noisePlayer, audioRef, playbackStateRef, }) {
             if (!noiseEl || !noiseEl.paused)
                 return;
             const a = audioRef.current;
-            const mainPlaying = (!!a && !a.paused && !a.ended) || playbackStateRef.current === 'playing';
+            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, fadeInNoise, audioRef, playbackStateRef]);
+    }, [cancelNoiseFade, fadeInNoise, audioRef, playbackStateRef, 뜸중]);
     // noiseSettingsRef 최신화 (재생 이벤트 핸들러 클로저에서 사용)
     useEffect(() => {
         noiseSettingsRef.current = noisePlayer
@@ -278,7 +284,7 @@ export function useNoiseFade({ noisePlayer, audioRef, playbackStateRef, }) {
                     noiseEl.src = url;
                     noiseEl.load();
                     const mainAudio = audioRef.current;
-                    if (mainAudio && !mainAudio.paused) {
+                    if ((mainAudio && !mainAudio.paused) || 뜸중()) {
                         canplay떼기Ref.current?.();
                         const h = () => {
                             noiseEl.removeEventListener('canplay', h);
@@ -290,7 +296,8 @@ export function useNoiseFade({ noisePlayer, audioRef, playbackStateRef, }) {
                                껐어도 canplay 에서 1 로 다시 켜져 끝까지 났다(난이도가 뜻보다 어려워지고 기록과 들린 소리가 어긋남). */
                             const cur = audioRef.current;
                             const 지금 = noiseSettingsRef.current;
-                            if (cur && !cur.paused && !cur.ended && 지금?.enabled && 지금.volume > 0)
+                            const 도나 = (!!cur && !cur.paused && !cur.ended) || 뜸중();
+                            if (도나 && 지금?.enabled && 지금.volume > 0)
                                 fadeInNoise(지금.volume);
                         };
                         const 떼기 = () => noiseEl.removeEventListener('canplay', h);
@@ -308,7 +315,7 @@ export function useNoiseFade({ noisePlayer, audioRef, playbackStateRef, }) {
             // 나오는 버그가 있었다. 메인이 재생 중이 아니면 무조건 정지시킨다.
             const mainAudio = audioRef.current;
             // speechSynthesis TTS 경로는 메인 <audio> 없이 재생된다 — 감시 타이머처럼 playbackState 도 본다(안 보면 비율만 바꿔도 소음이 멈췄다)
-            const mainPlaying = (!!mainAudio && !mainAudio.paused && !mainAudio.ended) || playbackStateRef.current === 'playing';
+            const mainPlaying = (!!mainAudio && !mainAudio.paused && !mainAudio.ended) || 뜸중() || playbackStateRef.current === 'playing';
             if (mainPlaying && pendingNoiseUrlRef.current) {
                 /* 종류를 바꾼 뒤 150ms 페이드아웃 안에 다른 설정을 바꾸면, 아래 볼륨만 옮기는 갈래가 파일을 바꿀 페이드를 지워 화면의 종류와
                    들리는 종류가 문장 끝까지 달랐다 — 기다리는 파일이 있으면 fadeInNoise 가 그것을 끼운다. */
@@ -342,7 +349,7 @@ export function useNoiseFade({ noisePlayer, audioRef, playbackStateRef, }) {
                 }
             }
         }
-    }, [noisePlayer?.settings, noisePlayer?.settings.enabled, noiseVolume, noisePlayer?.settings.type, cancelNoiseFade, fadeInNoise, fadeOutNoise, audioRef, playbackStateRef, noiseSettingsRef]);
+    }, [noisePlayer?.settings, noisePlayer?.settings.enabled, noiseVolume, noisePlayer?.settings.type, cancelNoiseFade, fadeInNoise, fadeOutNoise, audioRef, playbackStateRef, noiseSettingsRef, 뜸중]);
     // 소음 재생 속도(playbackRate) 반영 — 0.75~1.25. 엘리먼트 속성이라 src 변경에도 유지됨
     useEffect(() => {
         const el = noiseAudioRef.current;

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

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

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

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