@ihabdevteam/core 0.284.0 → 0.286.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.284.0";
+export declare const CORE_VERSION = "0.286.0";
 
 /** @public */
 declare const coreDefault: Record<string, unknown>;

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

@@ -139,24 +139,21 @@ export default function TrainingStepAudioPlayer({ btnLabel, soundSrc, bucketPath
        팝업을 닫아도 흐름이 계속 돌아, **떼어진 <audio> 에서 play()** 가 불려 이전 문장이 조작 단추 없이 끝까지
        울렸다. 재생 직전에 본다. */
     const mountedRef = useRef(true);
-    /* **시간표의 자리·의도·뜸 타이머는 진행기가 쥔다**((85) 2a, 2026-10-06).
-       아래 `뜸Ref`·`뜸취소`·`뜸기다리기` 는 그것을 읽는 **얇은 껍데기**로 남는다 — 부르는
-       자리가 아직 열 곳 넘어 한 번에 못 바꾼다. 2d 에서 걷는다. */
+    /* **시간표의 자리·의도·뜸 타이머·멈춘 자리는 진행기가 쥔다**((85) 2a~2c, 2026-10-06).
+       묻는 쪽(소음 · 틱 · 토글 · 자물쇠)은 **자리를 받아 제 손으로 셈하지 않고** 진행기에게
+       묻는다 — `isRunning()` 하나다. 그 셈이 세 벌로 흩어져 있던 것이 오늘 결함 여섯의 뿌리였다. */
     const 진행기 = usePlaybackSequencer({ mountedRef });
-    const 뜸Ref = 진행기.positionRef;
+    /* `onEnded` 가 적어 두는 "여기서부터 이어 간다" — 토글이 멈출 때 진행기에 넘긴다 */
+    const 이어가기RefBox = 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]);
-    /* 뒤뜸(소리가 끝난 뒤의 뜸)에서 멈췄나, 그리고 다시 누르면 어디서부터 이을 것인가 —
-       아래 `handleToggle` 이 쓴다(말귀 요청 (85) 0단계에서 찾은 결함, 2026-10-06). */
-    const 뒤뜸에서멈춤Ref = useRef(false);
-    const 이어가기Ref = useRef(null);
     /** 뜸만큼 기다린다 — 그 사이 **의도가 바뀌면 거짓**을 돌려 부르는 쪽이 그만둔다 */
     const 뜸기다리기 = 진행기.waitPad;
-    const { start: startTicker, stop: stopTicker, settleTo: settleTicker, } = useProgressTicker({ audioRef, fillRef, waveProgressRef, sourcesRef, currentIndexRef, padRef: 뜸Ref, leadInMs, tailMs });
+    const { start: startTicker, stop: stopTicker, settleTo: settleTicker, } = useProgressTicker({ audioRef, fillRef, waveProgressRef, sourcesRef, currentIndexRef, sequencer: 진행기, leadInMs, tailMs });
     /* 파형이 자리를 잡을 때까지 기다리는 규칙은 useWaveReady 가 들고 있다 —
        ref 둘·함수 둘에 "준비 안 됨으로 되돌리기"가 일곱 군데 흩어져 있던 것을 모았다. */
     const { onReadyChange: handleWaveReadyChange, waitForReady: waitForWaveReady, markNotReady: markWaveNotReady, } = useWaveReady({ showSoundWaveForm, showNoiseWaveForm });
@@ -183,7 +180,7 @@ export default function TrainingStepAudioPlayer({ btnLabel, soundSrc, bucketPath
         noisePlayer,
         audioRef,
         playbackStateRef,
-        padRef: 뜸Ref,
+        sequencer: 진행기,
     });
     const { startTTS: 합성시작, stopTTS } = useTTSPlayback({
         ttsText,
@@ -436,7 +433,6 @@ export default function TrainingStepAudioPlayer({ btnLabel, soundSrc, bucketPath
            다음 소리가 있으면 그 소리의 **앞 뜸**이 이어 붙어 사이가 둘을 더한 만큼이 된다 —
            누를 때의 뜸과 사이의 뜸을 가르는 자리가 여기다. */
         const onEnded = () => {
-            뒤뜸에서멈춤Ref.current = false;
             const 이어가기 = () => {
                 try {
                     const sref = sourcesRef.current;
@@ -476,8 +472,8 @@ export default function TrainingStepAudioPlayer({ btnLabel, soundSrc, bucketPath
                 }
                 catch (e) { }
             };
-            /* 토글이 뒤뜸에서 멈췄다가 다시 누를 때 **여기서부터** 잇는다 — 아래 `handleToggle` */
-            이어가기Ref.current = 이어가기;
+            /* 멈췄다 다시 누를 때 **여기서부터** 잇는다 — 진행기가 그 자리를 안다 */
+            이어가기RefBox.current = 이어가기;
             if (tailMsRef.current > 0) {
                 /* 기다리는 동안 진행바를 돌린다 — `pause` 가 이미 세웠을 수 있어 다시 켠다.
                    그 사이 멈추거나 떠나면 `뜸기다리기` 가 거짓을 주고 아무 일도 안 한다. */
@@ -889,8 +885,7 @@ export default function TrainingStepAudioPlayer({ btnLabel, soundSrc, bucketPath
            +1000ms 에 한 번, 원래 사슬이 닿는 +1500ms 에 또 한 번).
            감시 타이머가 0.268.0 에서 배운 것과 같은 것을 이 단추가 못 배우고 있었다 —
            뜸은 소리가 안 나는 구간이지 **멈춘 구간이 아니다.** */
-        const 뜸 = 뜸Ref.current;
-        const 뜸도는중 = 뜸.phase !== 'sound' && 뜸.at > 0;
+        const 뜸도는중 = 진행기.isRunning();
         if (a.paused && !뜸도는중) {
             if (completedByEndRef.current) {
                 await handleReplay();
@@ -899,17 +894,19 @@ export default function TrainingStepAudioPlayer({ btnLabel, soundSrc, bucketPath
             /* 뒤뜸에서 멈췄던 것이면 그 소리를 다시 틀지 않고 **그다음으로** 잇는다 — 끝난 요소에
                `play()` 를 걸면 방금 들은 소리가 처음부터 또 난다. 뜸은 이미 한 번 기다렸으니
                다시 세지 않는다. */
-            if (뒤뜸에서멈춤Ref.current && 이어가기Ref.current) {
-                뒤뜸에서멈춤Ref.current = false;
+            /* **멈춘 자리에서 이어 간다** — 어디서 멈췄는지는 진행기가 안다.
+               `'restart'`(앞뜸이었다)면 아래로 흘러 처음부터 다시 돈다. */
+            const 이어갈것 = 진행기.resume();
+            if (typeof 이어갈것 === 'function') {
                 setPlaybackState("playing");
-                이어가기Ref.current();
+                이어갈것();
                 return;
             }
             await tryPlayWithRetry(a);
             setPlaybackState("playing");
         }
         else {
-            뒤뜸에서멈춤Ref.current = 뜸도는중 && 뜸.phase === 'tail';
+            진행기.pause(이어가기RefBox.current);
             멈춤의도();
             a.pause();
             setPlaybackState("paused");
@@ -1139,8 +1136,6 @@ export default function TrainingStepAudioPlayer({ btnLabel, soundSrc, bucketPath
            `멈춤의도()` 가 재생 의도와 뜸 타이머를 함께 걷는다 — **토큰을 집기 전에** 부른다
            (그 안에서 `jumpTokenRef` 도 올리므로, 뒤에 부르면 제 토큰이 바로 낡는다). */
         멈춤의도();
-        뒤뜸에서멈춤Ref.current = false;
-        이어가기Ref.current = null;
         const myToken = ++jumpTokenRef.current;
         const a = audioRef.current;
         const sref = sourcesRef.current;

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

@@ -5,7 +5,7 @@ type PlaybackState = 'stopped' | 'playing' | 'paused';
  * TrainingStepAudioPlayer에서 분리 — 소음(noise) 오디오 엘리먼트 생성/페이드인/페이드아웃/워치독을
  * 전담한다. audioRef(메인 문장 오디오)·playbackStateRef는 메인 컴포넌트 소유라 그대로 전달받는다.
  */
-export declare function useNoiseFade({ noisePlayer, audioRef, playbackStateRef, padRef, }: {
+export declare function useNoiseFade({ noisePlayer, audioRef, playbackStateRef, sequencer, }: {
     noisePlayer: NoisePlayerContextValue | null;
     audioRef: RefObject<HTMLAudioElement | null>;
     playbackStateRef: RefObject<PlaybackState>;
@@ -17,10 +17,9 @@ export declare function useNoiseFade({ noisePlayer, audioRef, playbackStateRef,
      * 소음을 걷는다. 특히 아래 감시 타이머는 0.8초 뒤에 내리므로, 1000ms 뜸은 **800ms 에서
      * 소음이 꺼진다.** 뜸은 소리가 안 나는 구간이지 **재생이 끝난 구간이 아니다.**
      */
-    padRef?: RefObject<{
-        phase: 'lead' | 'sound' | 'tail';
-        at: number;
-    }>;
+    sequencer?: {
+        isRunning: () => boolean;
+    };
 }): {
     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, padRef, }) {
+export function useNoiseFade({ noisePlayer, audioRef, playbackStateRef, sequencer, }) {
     const registerAnalyserRef = useRef(noisePlayer?.registerAnalyser);
     registerAnalyserRef.current = noisePlayer?.registerAnalyser;
     const noiseAudioRef = useRef(null);
@@ -35,11 +35,10 @@ export function useNoiseFade({ noisePlayer, audioRef, playbackStateRef, padRef,
     // 판별해, 이미 다른 의도(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]);
+    /* **"지금 시간표가 도는가" 는 진행기에게 묻는다**((85) 2c, 2026-10-06). 전에는 자리를
+       받아 **제 손으로 셈했다**(`p.phase !== 'sound' && p.at > 0`) — 같은 셈이 틱·토글·여기
+       세 벌이었다. 셈이 한 자리에 있어야 "뜸이란 무엇인가" 가 갈라지지 않는다. */
+    const 뜸중 = useCallback(() => !!sequencer?.isRunning(), [sequencer]);
     const cancelNoiseFade = useCallback(() => {
         if (noiseFadeRafRef.current !== null) {
             cancelAnimationFrame(noiseFadeRafRef.current);

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

@@ -53,6 +53,23 @@ export interface PlaybackSequencer {
      * 자리다). 그 길을 **진짜로** 여는 문을 둔다.
      */
     __bumpGenerationForTest: () => void;
+    /**
+     * **멈춘 자리를 적어 둔다 — 다시 누르면 어디서부터인가.**
+     *
+     * 멈출 때 `pause(이어가기)` 로 적고, 다시 누를 때 `resume()` 으로 묻는다. 답은 둘이다:
+     *
+     *   `'restart'`  앞뜸에서 멈췄다 → **앞뜸부터 다시.** 앞뜸은 귀가 소음에 자리를 잡는
+     *                시간인데(0.268.0) 멈추면 소음도 멎으니, 남은 뜸만 채우면 그 시간이 잘린다.
+     *   `(함수)`     사이·뒤뜸에서 멈췄다 → **그 자리에서 이어 간다**(다음 소리로, 마지막이면
+     *                완료로). 끝난 요소에 `play()` 를 걸면 방금 들은 소리가 처음부터 또 난다.
+     *
+     * 전에는 재생기가 ref 둘(`뒤뜸에서멈춤Ref` · `이어가기Ref`)로 들고 **멈추는 자리마다** 그
+     * 둘을 맞춰 적어야 했다 — 네 자리 중 한 곳만 빠뜨려도 틀린 데서 이어 간다.
+     * 어느 구간에서 멈췄는지는 **자리를 쥔 쪽**이 안다.
+     */
+    pause: (resume: (() => void) | null) => void;
+    /** 멈춘 자리에서 이어 갈 방법. 멈춘 적이 없으면 `null` */
+    resume: () => 'restart' | (() => void) | null;
     /**
      * 뜸만큼 기다린다. 그 사이 세대가 바뀌거나 화면을 떠나면 **거짓**을 준다 —
      * 부르는 쪽은 거짓이면 아무 일도 하지 않고 돌아간다.

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

@@ -1,5 +1,5 @@
 'use client';
-import { useCallback, useEffect, useRef } from 'react';
+import { useCallback, useEffect, useMemo, useRef } from 'react';
 export function usePlaybackSequencer({ mountedRef }) {
     const positionRef = useRef({ phase: 'sound', at: 0 });
     const 세대Ref = useRef(0);
@@ -18,6 +18,22 @@ export function usePlaybackSequencer({ mountedRef }) {
      * (처음에는 걷는 쪽으로 썼다가, 그 때문에 **세대 비교가 죽은 코드**가 된 것을 뒤늦게 봤다 —
      * 걷어 버리면 세대를 볼 일이 없다. 둘 중 하나를 골라야 하는 자리였다.)
      */
+    /** 멈출 때의 자리 — `'restart'`(앞뜸이었다) 또는 이어 갈 함수, 안 멈췄으면 `null` */
+    const 멈춘자리Ref = useRef(null);
+    /* **`abort()` 보다 먼저 부른다** — `abort()` 는 자리를 비우므로 뒤에 부르면 "어느 구간에서
+       멈췄나" 를 이미 잃는다. `pause()` 가 그 자리를 보고 적고, 그다음에 `abort()` 가 걷는다.
+       (`abort()` 가 이 적바림까지 지우게 했다가 못이 울렸다 — 멈춘 자리를 바로 지워 버려
+       이을 때 앞 소리가 또 났다. `멈춤의도()` 안에서 둘이 잇따라 불린다.) */
+    const pause = useCallback((resume) => {
+        const p = positionRef.current;
+        const 뜸중 = p.phase !== 'sound' && p.at > 0;
+        멈춘자리Ref.current = !뜸중 ? null : p.phase === 'lead' ? 'restart' : resume;
+    }, []);
+    const resume = useCallback(() => {
+        const v = 멈춘자리Ref.current;
+        멈춘자리Ref.current = null;
+        return v;
+    }, []);
     const abort = useCallback(() => {
         세대Ref.current += 1;
         positionRef.current = { phase: 'sound', at: 0 };
@@ -56,5 +72,15 @@ export function usePlaybackSequencer({ mountedRef }) {
             뜸타이머Ref.current = null;
         }
     }, []);
-    return { positionRef, isRunning, generation, isCurrent, abort, waitPad, enterSound, leave, __bumpGenerationForTest };
+    /**
+     * **판마다 새 객체면 안 된다**((85) 2c 에서 겪었다, 2026-10-06).
+     *
+     * 묻는 쪽이 이것을 **효과의 입력으로** 받는다. 판마다 새로 지으면 그 효과가 매번 다시
+     * 돌고, 손잡이 효과의 치우기가 **재생 도중 진행 사슬을 끊는다** — 그러면 뜸 동안 재생바가
+     * 멈춰 보인다. 0.271.0 에 세워 둔 문(`audioProgressChainRerender`)이 그 자리를 바로 잡았다.
+     * 안 세웠으면 "앞뜸에 재생바가 안 움직인다" 를 또 사용자가 짚을 뻔했다.
+     *
+     * 안쪽 것들은 전부 `useRef`·`useCallback` 이라 이미 고정이다 — 겉만 고정하면 된다.
+     */
+    return useMemo(() => ({ positionRef, isRunning, generation, isCurrent, abort, waitPad, enterSound, leave, pause, resume, __bumpGenerationForTest }), [isRunning, generation, isCurrent, abort, waitPad, enterSound, leave, pause, resume, __bumpGenerationForTest]);
 }

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

@@ -1,6 +1,6 @@
 import { type RefObject } from 'react';
 import type { Source } from './trainingStepAudioPlayerTypes';
-export declare function useProgressTicker({ audioRef, fillRef, waveProgressRef, sourcesRef, currentIndexRef, padRef, leadInMs, tailMs, }: {
+export declare function useProgressTicker({ audioRef, fillRef, waveProgressRef, sourcesRef, currentIndexRef, sequencer, leadInMs, tailMs, }: {
     audioRef: RefObject<HTMLAudioElement | null>;
     /** 진행 마커 — `left` 를 퍼센트로 민다 */
     fillRef: RefObject<HTMLDivElement | null>;
@@ -14,10 +14,12 @@ export declare function useProgressTicker({ audioRef, fillRef, waveProgressRef,
      * 뜸을 주면 **소리가 안 나는 동안에도 재생바가 움직여야 한다** — 전에는 `currentTime` 을
      * 그대로 따라 멈춰 있었다(말귀 실측: 누른 뒤 2029ms 에 `play`, 그때까지 채움 0%).
      */
-    padRef?: RefObject<{
-        phase: 'lead' | 'sound' | 'tail';
-        at: number;
-    }>;
+    sequencer?: {
+        positionRef: RefObject<{
+            phase: 'lead' | 'sound' | 'tail';
+            at: number;
+        }>;
+    };
     leadInMs?: number;
     tailMs?: number;
 }): {

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

@@ -61,7 +61,7 @@ function audioDurationOf(a) {
  * 아무 일도 안 한다.
  */
 const 느린틀 = 400;
-export function useProgressTicker({ audioRef, fillRef, waveProgressRef, sourcesRef, currentIndexRef, padRef, leadInMs = 0, tailMs = 0, }) {
+export function useProgressTicker({ audioRef, fillRef, waveProgressRef, sourcesRef, currentIndexRef, sequencer, leadInMs = 0, tailMs = 0, }) {
     const rafRef = useRef(null);
     const stop = useCallback(() => {
         if (rafRef.current === null)
@@ -111,8 +111,8 @@ export function useProgressTicker({ audioRef, fillRef, waveProgressRef, sourcesR
                     const 뜸있다 = (leadInMs || 0) > 0 || (tailMs || 0) > 0;
                     const pos = 뜸있다
                         ? progressWithPad({
-                            phase: padRef?.current?.phase ?? 'sound',
-                            phaseElapsedMs: padRef?.current ? Math.max(0, Date.now() - padRef.current.at) : 0,
+                            phase: sequencer?.positionRef.current?.phase ?? 'sound',
+                            phaseElapsedMs: sequencer?.positionRef.current ? Math.max(0, Date.now() - sequencer.positionRef.current.at) : 0,
                             currentTime: a && typeof a.currentTime === 'number' ? a.currentTime : 0,
                             trackDurationSec: 트랙길이알아 ? 트랙.duration : (총길이 || 0),
                             leadInMs: leadInMs || 0,
@@ -142,7 +142,7 @@ export function useProgressTicker({ audioRef, fillRef, waveProgressRef, sourcesR
             rafRef.current = requestAnimationFrame(step);
         };
         rafRef.current = requestAnimationFrame(step);
-    }, [audioRef, fillRef, waveProgressRef, sourcesRef, currentIndexRef, padRef, leadInMs, tailMs]);
+    }, [audioRef, fillRef, waveProgressRef, sourcesRef, currentIndexRef, sequencer, leadInMs, tailMs]);
     /** 다 들었을 때처럼 끝에 붙여 놓아야 하는 자리 */
     const settleTo = useCallback((pos) => {
         stop();

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

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

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

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