@ihabdevteam/core 0.38.0 → 0.39.0

package/dist/packages/core/src/hooks/useAnchoredMenu.js

@@ -0,0 +1,72 @@
+'use client';
+import { useCallback, useEffect, useRef, useState } from 'react';
+/**
+ * 트리거 요소에 fixed 포지션으로 앵커링되는 메뉴/드롭다운/팝오버의 공용 로직.
+ * 열림상태 + 위치 계산 + 바깥클릭/스크롤/리사이즈 처리를 담당하고, 렌더링(포탈 등)은
+ * 사용하는 쪽에서 담당한다. Dropdown, DatePicker, BottomNav의 "더보기" 메뉴가 이 훅을 쓴다.
+ * @public
+ */
+export function useAnchoredMenu({ computeStyle, onScroll = 'close', onResize = 'close', ignoreOutsideClickSelector, }) {
+    const [open, setOpen] = useState(false);
+    const [style, setStyle] = useState({});
+    const triggerRef = useRef(null);
+    const menuRef = useRef(null);
+    const recalc = useCallback(() => {
+        if (!triggerRef.current)
+            return;
+        setStyle(computeStyle(triggerRef.current.getBoundingClientRect()));
+    }, [computeStyle]);
+    useEffect(() => {
+        if (!open)
+            return;
+        recalc();
+        const handleOutsideClick = (e) => {
+            const target = e.target;
+            if (ignoreOutsideClickSelector && target.closest?.(ignoreOutsideClickSelector))
+                return;
+            if (triggerRef.current?.contains(target))
+                return;
+            if (menuRef.current?.contains(target))
+                return;
+            setOpen(false);
+        };
+        document.addEventListener('mousedown', handleOutsideClick);
+        const handleScroll = (e) => {
+            if (menuRef.current?.contains(e.target))
+                return;
+            if (onScroll === 'reposition')
+                recalc();
+            else if (onScroll === 'close')
+                setOpen(false);
+        };
+        if (onScroll !== 'ignore')
+            window.addEventListener('scroll', handleScroll, true);
+        const handleResize = () => {
+            if (onResize === 'reposition')
+                recalc();
+            else if (onResize === 'close')
+                setOpen(false);
+        };
+        if (onResize !== 'ignore')
+            window.addEventListener('resize', handleResize);
+        // ESC로 닫기 — 이 훅을 쓰는 컴포넌트가 자체 키보드 핸들링(예: Dropdown의 화살표 탐색)을
+        // 따로 두더라도 무해하게 중복 호출될 뿐이므로, 여기서 공통으로 처리해 DatePicker/BottomNav
+        // 더보기 메뉴처럼 자체 ESC 처리가 없던 소비자도 함께 혜택을 받게 한다.
+        const handleKeyDown = (e) => {
+            if (e.key === 'Escape')
+                setOpen(false);
+        };
+        document.addEventListener('keydown', handleKeyDown);
+        return () => {
+            document.removeEventListener('mousedown', handleOutsideClick);
+            if (onScroll !== 'ignore')
+                window.removeEventListener('scroll', handleScroll, true);
+            if (onResize !== 'ignore')
+                window.removeEventListener('resize', handleResize);
+            document.removeEventListener('keydown', handleKeyDown);
+        };
+    }, [open, recalc, onScroll, onResize, ignoreOutsideClickSelector]);
+    const toggle = useCallback(() => setOpen(o => !o), []);
+    const close = useCallback(() => setOpen(false), []);
+    return { open, setOpen, toggle, close, style, triggerRef, menuRef };
+}

package/dist/packages/core/src/hooks/useSoundCompassExam.d.ts

@@ -0,0 +1,54 @@
+import type { SpeakerPos } from '../types/audio';
+/**
+ * @public
+ * SoundCompass 오케스트레이션 참조 훅.
+ *
+ * SoundCompass 자체는 제어형(표현) 컴포넌트라 순서·타이밍·점수·진행을 갖지 않는다.
+ * 이 훅이 그 "부모(검사 컨트롤러)" 역할의 기본 구현을 제공한다 —
+ * 큐 셔플, 문제 재생 타이밍, 선택 수집, 피드백, 진행/점수, 완료 콜백.
+ *
+ * 반환한 `bind`를 `<SoundCompass {...exam.bind} />`처럼 펼쳐 넣으면 된다.
+ * 다른 동작이 필요하면 이 훅을 복사·수정하거나, SoundCompass의 제어 props를
+ * 직접 구동해도 된다.
+ */
+export type SoundCompassMode = 'playback' | 'practice' | 'exam';
+export interface UseSoundCompassExamOptions {
+    /** 동작 모드. 기본 'playback' */
+    mode?: SoundCompassMode;
+    /** 마운트/리셋 시 자동 시작. 기본 false */
+    autoStart?: boolean;
+    /** 스피커 소리를 재생해야 할 때 호출 (오디오는 호출자 담당) */
+    onPlaySpeaker?: (speaker: SpeakerPos) => void;
+    /** 모든 문제/재생 완료 시 호출 */
+    onComplete?: (result: {
+        score: number;
+        total: number;
+    }) => void;
+    /** 문제당 소리 재생 후 선택 대기까지 지연(ms). 기본 1100 */
+    playMs?: number;
+    /** practice 모드 피드백 표시 시간(ms). 기본 1500 */
+    feedbackMs?: number;
+}
+export type SoundCompassPhase = 'idle' | 'playing' | 'waiting' | 'feedback' | 'done';
+export interface SoundCompassExam {
+    /** `<SoundCompass {...bind} />` 로 펼쳐 넣는 제어 props */
+    bind: {
+        activeSpeakerId: string | null;
+        playedIds: string[];
+        selectedId: string | null;
+        answerId: string | null;
+        showFeedback: boolean;
+        clickable: boolean;
+        onSelectSpeaker: (id: string) => void;
+    };
+    index: number;
+    total: number;
+    score: number;
+    phase: SoundCompassPhase;
+    done: boolean;
+    /** 시작(또는 재시작) */
+    start: () => void;
+    /** idle 상태로 리셋 */
+    reset: () => void;
+}
+export declare function useSoundCompassExam(speakers: SpeakerPos[], { mode, autoStart, onPlaySpeaker, onComplete, playMs, feedbackMs, }?: UseSoundCompassExamOptions): SoundCompassExam;

package/dist/packages/core/src/hooks/useSoundCompassExam.js

@@ -0,0 +1,128 @@
+'use client';
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { shuffle } from '../utils/array';
+export function useSoundCompassExam(speakers, { mode = 'playback', autoStart = false, onPlaySpeaker, onComplete, playMs = 1100, feedbackMs = 1500, } = {}) {
+    const [queue, setQueue] = useState([]);
+    const [index, setIndex] = useState(0);
+    const [phase, setPhase] = useState('idle');
+    const [activeId, setActiveId] = useState(null);
+    const [playedIds, setPlayedIds] = useState([]);
+    const [selectedId, setSelectedId] = useState(null);
+    const [score, setScore] = useState(0);
+    // updater 밖에서 최신 score를 읽기 위한 미러 — setState updater 안에서 onComplete를
+    // 호출하면(부수효과) StrictMode에서 updater가 2회 실행돼 완료 콜백(점수 기록)이 중복된다.
+    const scoreRef = useRef(0);
+    const setScoreTracked = useCallback((next) => {
+        scoreRef.current = typeof next === 'function' ? next(scoreRef.current) : next;
+        setScore(scoreRef.current);
+    }, []);
+    // 최신 콜백/타이머 참조 (effect 재실행 없이 사용)
+    const onPlayRef = useRef(onPlaySpeaker);
+    const onDoneRef = useRef(onComplete);
+    useEffect(() => { onPlayRef.current = onPlaySpeaker; onDoneRef.current = onComplete; }, [onPlaySpeaker, onComplete]);
+    const timers = useRef([]);
+    const clearTimers = () => { timers.current.forEach(clearTimeout); timers.current = []; };
+    const after = (ms, fn) => { timers.current.push(setTimeout(fn, ms)); };
+    useEffect(() => () => clearTimers(), []);
+    const answerId = queue[index]?.id ?? null;
+    // ── playback: 모든 스피커를 순서대로 ──────────────────────────────────
+    const runPlayback = useCallback(() => {
+        clearTimers();
+        setPhase('playing');
+        setPlayedIds([]);
+        setSelectedId(null);
+        setScoreTracked(0);
+        let acc = 0;
+        speakers.forEach((sp, i) => {
+            after(acc, () => { setIndex(i); setActiveId(sp.id); onPlayRef.current?.(sp); });
+            after(acc + 1000, () => { setActiveId(null); setPlayedIds(prev => [...prev, sp.id]); });
+            acc += 1300;
+        });
+        after(acc, () => { setPhase('done'); onDoneRef.current?.({ score: 0, total: speakers.length }); });
+    }, [speakers, setScoreTracked]);
+    // ── practice / exam: 문제 재생 → 선택 대기 ────────────────────────────
+    const playQuestion = useCallback((q, i) => {
+        if (i >= q.length) {
+            setPhase('done');
+            onDoneRef.current?.({ score: scoreRef.current, total: q.length });
+            return;
+        }
+        setIndex(i);
+        setSelectedId(null);
+        setPhase('playing');
+        setActiveId(q[i].id);
+        onPlayRef.current?.(q[i]);
+        after(playMs, () => { setActiveId(null); setPhase('waiting'); });
+    }, [playMs]);
+    const runExam = useCallback(() => {
+        clearTimers();
+        const q = shuffle(speakers);
+        setQueue(q);
+        setScoreTracked(0);
+        setPlayedIds([]);
+        playQuestion(q, 0);
+    }, [speakers, playQuestion, setScoreTracked]);
+    const start = useCallback(() => {
+        if (mode === 'playback') {
+            setQueue(speakers);
+            runPlayback();
+        }
+        else
+            runExam();
+    }, [mode, speakers, runPlayback, runExam]);
+    const reset = useCallback(() => {
+        clearTimers();
+        setPhase('idle');
+        setActiveId(null);
+        setPlayedIds([]);
+        setSelectedId(null);
+        setIndex(0);
+        setScoreTracked(0);
+        setQueue([]);
+    }, [setScoreTracked]);
+    // autoStart / 입력 변경 시 재시작 — start/reset이 여러 상태를 동기 초기화하지만 의도된 동작이다
+    /* eslint-disable react-hooks/set-state-in-effect */
+    useEffect(() => {
+        if (autoStart)
+            start();
+        else
+            reset();
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [mode, speakers.length, autoStart]);
+    /* eslint-enable react-hooks/set-state-in-effect */
+    const onSelectSpeaker = useCallback((id) => {
+        if (phase !== 'waiting' || mode === 'playback')
+            return;
+        setSelectedId(id);
+        const correct = id === queue[index]?.id;
+        if (correct)
+            setScoreTracked(s => s + 1);
+        if (mode === 'exam') {
+            setPhase('playing');
+            after(400, () => playQuestion(queue, index + 1));
+        }
+        else {
+            setPhase('feedback');
+            after(feedbackMs, () => playQuestion(queue, index + 1));
+        }
+    }, [phase, mode, queue, index, playQuestion, feedbackMs, setScoreTracked]);
+    const total = mode === 'playback' ? speakers.length : queue.length;
+    return {
+        bind: {
+            activeSpeakerId: activeId,
+            playedIds,
+            selectedId,
+            answerId,
+            showFeedback: phase === 'feedback',
+            clickable: phase === 'waiting',
+            onSelectSpeaker,
+        },
+        index,
+        total,
+        score,
+        phase,
+        done: phase === 'done',
+        start,
+        reset,
+    };
+}

package/dist/packages/core/src/hooks/useWordAttributeFilter.d.ts

@@ -26,6 +26,7 @@ export declare function useWordAttributeFilterKeys(): WordAttributeFilterKeys;
 export declare function buildGradeSection(t: TFunction, keys: WordAttributeFilterKeys, opts?: {
     allLabel?: string;
     labelAction?: ReactNode;
+    labelInfo?: FilterPanelSection['labelInfo'];
 }): FilterPanelSection;
 /** @public 품사 FilterPanelSection — 세 화면 공용. */
 export declare function buildPartOfSpeechSection(keys: WordAttributeFilterKeys): FilterPanelSection;
@@ -42,6 +43,7 @@ export declare function buildSyllableSection(t: TFunction, keys: WordAttributeFi
 export declare function buildSelectSection(t: TFunction, opts?: {
     includeStructure?: boolean;
     labelAction?: ReactNode;
+    labelInfo?: FilterPanelSection['labelInfo'];
 }): FilterPanelSection;
 /**
  * @public 위치(어두/어중/어말) FilterPanelSection 빌더 — WordSearchPage·단어훈련 만들기(메인 앱)가 공용.

package/dist/packages/core/src/hooks/useWordAttributeFilter.js

@@ -37,6 +37,7 @@ export function buildGradeSection(t, keys, opts) {
         allOption: true,
         allLabel: opts?.allLabel,
         labelAction: opts?.labelAction,
+        labelInfo: opts?.labelInfo,
     };
 }
 /** @public 품사 FilterPanelSection — 세 화면 공용. */
@@ -72,7 +73,7 @@ export function buildSelectSection(t, opts) {
     const items = [t('wordPairs.filter.onlyHasImage', '이미지 있는 단어만')];
     if (opts?.includeStructure)
         items.push(t('wordPairs.filter.onlySameStructure', '음소 구조 같은 단어만'));
-    return { label: t('wordPairs.filter.selectLabel', '선택'), items, multiple: true, labelAction: opts?.labelAction };
+    return { label: t('wordPairs.filter.selectLabel', '선택'), items, multiple: true, labelAction: opts?.labelAction, labelInfo: opts?.labelInfo };
 }
 /**
  * @public 위치(어두/어중/어말) FilterPanelSection 빌더 — WordSearchPage·단어훈련 만들기(메인 앱)가 공용.

package/dist/packages/core/src/hooks/useWordTrainingDataGeneration.d.ts

@@ -1,13 +1,8 @@
 import { type WordTrainingTypeKey } from '../utils/wordTrainingRuntime';
 import type { DifficultyLevel } from '../utils/koreanSyllable';
 import { type WordComposition } from './useWordTrainingFilter';
-export interface WordTrainingType {
-    key: WordTrainingTypeKey;
-    label: string;
-    icon: string;
-    color: string;
-    subTitle: string;
-}
+import type { WordTrainingType } from '../utils/wordTrainingRuntimeTypes';
+export type { WordTrainingType } from '../utils/wordTrainingRuntimeTypes';
 interface WordTrainingDataEntry {
     id: string;
     name: string;
@@ -31,4 +26,3 @@ export declare function useWordTrainingDataGeneration(types: WordTrainingType[],
     perTypeData: Record<string, WordTrainingDataEntry | null>;
     generating: boolean;
 };
-export {};

package/dist/packages/core/src/hooks/useWordTrainingFilter.js

@@ -1,10 +1,9 @@
 'use client';
-import { useCallback, useEffect, useMemo, useRef, useState, createElement } from 'react';
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import { useTranslation } from 'react-i18next';
 import { getViableComposition, countUsableWords } from '../utils/wordTrainingRuntime';
 import { FILTER_ALL_VALUE } from '../types/filterPanel';
 import { useWindowEvent } from './useWindowEvent';
-import FilterSectionInfo from '../components/FilterSectionInfo';
 import { useWordAttributeFilterKeys, buildGradeSection, buildPartOfSpeechSection, buildWordTypeSection } from './useWordAttributeFilter';
 import { matchesFilters } from '../utils/phonemePairSearch';
 import { hasSel } from '../utils/wordContrast';
@@ -327,7 +326,9 @@ export function useWordTrainingFilter(groupKey, caps, opts) {
     const partByLabel = useMemo(() => ({
         [LABELS.trainOnset]: 'cho', [LABELS.trainVowel]: 'jung', [LABELS.trainCoda]: 'jong',
     }), [LABELS]);
-    const infoAction = useCallback((items, title) => createElement(FilterSectionInfo, { title, items }), []);
+    /* 요소가 아니라 **서술**을 넘긴다 — 그리는 일은 FilterPanel 이 한다.
+       예전에는 여기서 createElement 로 만들었고, 그 탓에 훅이 컴포넌트를 올려다봤다. */
+    const infoAction = useCallback((items, title) => ({ title, items }), []);
     const selectInfoItems = useMemo(() => [
         t('training.filter.excludeImageInfo', { defaultValue: '이미지 있는 단어만: 단어 중에 이미지가 있는 단어만 결과에 보여줍니다.' }),
         t('training.filter.sameStructureInfo', { defaultValue: '음소 구조 같은 단어만: 정답과 오답의 음절 구조(글자 수·받침 유무 등)가 같은 결과만 남겨요.' }),
@@ -383,7 +384,7 @@ export function useWordTrainingFilter(groupKey, caps, opts) {
         // label만 오버라이드하고 나머지(items/allOption 등)는 공용 빌더 그대로 사용.
         sections.push({
             ...buildGradeSection(t, attrKeys, {
-                labelAction: infoAction([t('wordPairs.filter.difficultyInfo', { defaultValue: '국립국어원의 기초 어휘 등급이 결과에 반영됩니다.' })]),
+                labelInfo: infoAction([t('wordPairs.filter.difficultyInfo', { defaultValue: '국립국어원의 기초 어휘 등급이 결과에 반영됩니다.' })]),
             }),
             label: LABELS.gradeLabel,
         });
@@ -423,10 +424,10 @@ export function useWordTrainingFilter(groupKey, caps, opts) {
         // 선택 — choseong 타입은 긍정형 다중 토글(이미지 있는 단어만 / 음소 구조 같은 단어만),
         // 아니면 이미지 제외만 마지막에 노출. (받침 제외는 종성 섹션의 '제외' 버튼)
         if (caps.choseong) {
-            sections.push({ label: LABELS.exclude, displayLabel: LABELS.selectLabel, multiple: true, items: [LABELS.excludeImage, LABELS.sameStructure], labelAction: infoAction(selectInfoItems) });
+            sections.push({ label: LABELS.exclude, displayLabel: LABELS.selectLabel, multiple: true, items: [LABELS.excludeImage, LABELS.sameStructure], labelInfo: infoAction(selectInfoItems) });
         }
         else {
-            sections.push({ label: LABELS.exclude, displayLabel: LABELS.selectLabel, multiple: true, items: [LABELS.excludeImage], labelAction: infoAction([selectInfoItems[0]]) });
+            sections.push({ label: LABELS.exclude, displayLabel: LABELS.selectLabel, multiple: true, items: [LABELS.excludeImage], labelInfo: infoAction([selectInfoItems[0]]) });
         }
         return sections;
     }, [caps.choseong, caps.partOfSpeech, caps.wordType, caps.requireSyllable, caps.fixedSyllable, caps.fixedNoCoda, caps.requireCoda, minSyllables, partViable, viable, phonemeView, syllableViable, LABELS, t, infoAction, selectInfoItems, attrKeys]);

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

@@ -26,3 +26,7 @@ export * from './hooks/usePagedList';
 export * from './hooks/useToastState';
 export { useTrainingTypeLabels } from './hooks/useTrainingTypeLabels';
 export { CORE_VERSION } from './version';
+export { useAnchoredMenu } from './hooks/useAnchoredMenu';
+export type { UseAnchoredMenuOptions, UseAnchoredMenuResult } from './hooks/useAnchoredMenu';
+export { useSoundCompassExam } from './hooks/useSoundCompassExam';
+export type { SoundCompassMode, SoundCompassPhase, SoundCompassExam, UseSoundCompassExamOptions } from './hooks/useSoundCompassExam';

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

@@ -27,3 +27,9 @@ export * from './hooks/usePagedList';
 export * from './hooks/useToastState';
 export { useTrainingTypeLabels } from './hooks/useTrainingTypeLabels';
 export { CORE_VERSION } from './version';
+/* 컴포넌트 곁에 있다가 이리로 온 둘 — 옛 경로(`components/…`)도 껍데기로 살아 있다.
+   기준은 "몇 곳이 쓰는가" 다: useAnchoredMenu 는 네 컴포넌트가 함께 쓰고,
+   useSoundCompassExam 은 어느 컴포넌트도 안 쓴다(소비자가 쓰는 머리 없는 훅이다).
+   한 컴포넌트만 쓰는 훅 다섯은 그 곁에 그대로 두었다 — 옮기면 응집만 떨어진다. */
+export { useAnchoredMenu } from './hooks/useAnchoredMenu';
+export { useSoundCompassExam } from './hooks/useSoundCompassExam';

package/dist/packages/core/src/types/filterPanel.d.ts

@@ -45,6 +45,21 @@ export interface FilterPanelSection {
     /** 가로 배치에서 이 섹션을 한 줄 전체(자체 줄)로 배치 — 인라인 흐름에서 분리 */
     block?: boolean;
     labelAction?: ReactNode;
+    /**
+     * 라벨 옆 "?" 설명 버튼을 **서술로** 지정한다 — `labelAction` 에 요소를 직접 넣는 대신
+     * 내용만 준다. FilterPanel 이 `FilterSectionInfo` 로 그린다.
+     *
+     * 왜 두 갈래인가: 훅은 화면을 그리면 안 된다. 섹션을 만들어 주는 훅
+     * (`useWordTrainingFilter`)이 예전에는 `createElement(FilterSectionInfo, …)` 로
+     * 요소를 만들었는데, 그러려면 **훅이 컴포넌트를 올려다봐야** 했다. 이 슬롯을 쓰면
+     * 훅은 내용만 넘기고 그리는 일은 컴포넌트가 한다.
+     * `labelAction` 은 그대로 둔다 — 호출부가 제 요소를 넣고 싶을 때가 있다.
+     * 둘 다 있으면 `labelAction` 이 이긴다.
+     */
+    labelInfo?: {
+        title?: string;
+        items: string[];
+    };
     items?: (FilterPanelItem | string)[];
     groups?: (FilterPanelItem | string)[][];
     /** 'note': 선택 불가능한 안내 텍스트 섹션 — content를 그대로 렌더링한다(예: 입력 구문 사용법). */

package/dist/packages/core/src/types/training.d.ts

@@ -1,3 +1,23 @@
+/** 소음 음원 갈래. @public */
+export type CoreNoiseType = 'defaultNoise' | 'street' | 'restaurant' | 'buzz';
+/**
+ * 훈련 화면의 소음/재생 설정. `NoisePlayerContext` 가 들고 다니고
+ * `utils/noiseSettingsStore` 가 앱이 주입한 콜백으로 영속화한다.
+ * 두 계층이 함께 아는 모양이라 여기(아래 계층)에 둔다.
+ * @public
+ */
+export type CoreNoiseSettings = {
+    enabled: boolean;
+    type: CoreNoiseType;
+    /** 0–9. 0이면 소음 비활성화. (소음 음원을 +7dB 증폭한 뒤 상한을 4→9로 확장 — 실제 volume = level/9) */
+    level: number;
+    /** 소음 재생 속도(playbackRate). 0.75–1.25, 기본 1. */
+    speed: number;
+    /** 문장(메인) 재생 소리(볼륨). 0–1, 기본 1. 계정 설정("훈련" 패널)과 훈련 화면 툴팁이 함께 영속화한다. */
+    mainVolume: number;
+    /** 문장(메인) 재생 속도(playbackRate). 0.5–1.5, 기본 1. 계정 설정("훈련" 패널)과 훈련 화면 툴팁이 함께 영속화한다. */
+    mainSpeed: number;
+};
 /** @public */
 export interface Choice {
     id?: string | number;

package/dist/packages/core/src/types/training.js

@@ -1 +1,2 @@
+// Central domain types for training-related data
 export {};

package/dist/packages/core/src/utils/audioPeaks.d.ts

@@ -0,0 +1,2 @@
+/** 주소에서 소리를 받아 파형 막대 높이 배열을 낸다. 실패하면 null. @public */
+export declare function computePeaksFromUrl(url: string, bars: number, windowSeconds?: number): Promise<number[] | null>;

package/dist/packages/core/src/utils/audioPeaks.js

@@ -0,0 +1,67 @@
+import { getErrorMessage } from './errorMessage';
+/**
+ * 소리 파일에서 **파형 막대 높이**를 뽑는다 — 내려받기 · 디코딩 · 봉우리 계산.
+ *
+ * 왜 여기 있나: 이건 화면이 아니다. 예전에는 `components/Training/AudioPlayerWaveForm.tsx`
+ * 안에 있었는데, 그 파일은 그림을 그리는 컴포넌트다. 거기 있으면
+ * **컴포넌트가 직접 `fetch` 를 부르는** 꼴이 되고, 이 계산만 따로 시험하려 해도
+ * React 를 세워야 한다. 컴포넌트는 이제 결과만 받아 그린다.
+ *
+ * 값은 **절대 진폭(0~1, full-scale 기준)** 이다 — 문장과 소음이 같은 잣대를 써야
+ * dBFS 미터와 눈금이 맞는다.
+ */
+// windowSeconds: 지정 시 파일의 처음 N초만 사용(소음을 문장 재생시간만큼만 그릴 때).
+// 컴포넌트 상태를 참조하지 않는 순수 계산이라 모듈 스코프로 분리 — 매 렌더 재생성되지 않는다.
+/** 내려받은 바이트를 디코딩해 봉우리를 센다 — 아래 `computePeaksFromUrl` 만 쓴다. */
+async function decodeAndComputePeaks(arrayBuffer, bars, windowSeconds) {
+    try {
+        const AudioCtxConstructor = window.AudioContext || window.webkitAudioContext;
+        const audioCtx = new AudioCtxConstructor();
+        const decoded = await audioCtx.decodeAudioData(arrayBuffer.slice(0));
+        const channelData = decoded.numberOfChannels > 0 ? decoded.getChannelData(0) : null;
+        if (!channelData)
+            return null;
+        const total = (windowSeconds && windowSeconds > 0)
+            ? Math.min(channelData.length, Math.floor(windowSeconds * decoded.sampleRate))
+            : channelData.length;
+        const usableLen = Math.max(bars, total);
+        const blockSize = Math.floor(usableLen / bars) || 1;
+        const peaks = new Array(bars).fill(0).map((_, i) => {
+            const start = i * blockSize;
+            const end = Math.min(start + blockSize, usableLen);
+            let max = 0;
+            for (let j = start; j < end; j++) {
+                const v = Math.abs(channelData[j]);
+                if (v > max)
+                    max = v;
+            }
+            return max;
+        });
+        try {
+            audioCtx.close && audioCtx.close();
+        }
+        catch (e) { }
+        // 절대 진폭(0~1, full-scale 기준) 반환 — 문장/소음이 같은 기준을 쓰게 해 dBFS 미터와 일치.
+        return peaks;
+    }
+    catch (e) {
+        return null;
+    }
+}
+/** 주소에서 소리를 받아 파형 막대 높이 배열을 낸다. 실패하면 null. @public */
+export async function computePeaksFromUrl(url, bars, windowSeconds) {
+    try {
+        const resp = await fetch(url);
+        const arrayBuffer = await resp.arrayBuffer();
+        return await decodeAndComputePeaks(arrayBuffer, bars, windowSeconds);
+    }
+    catch (e) {
+        try {
+            const errMsg = getErrorMessage(e);
+            if (import.meta.env?.DEV)
+                console.log('WaveForm: computePeaksFromUrl failed', { url, err: errMsg });
+        }
+        catch (ee) { }
+        return null;
+    }
+}

package/dist/packages/core/src/utils/noiseSettingsStore.d.ts

@@ -6,7 +6,7 @@
  * core는 사용자/고객 식별자를 모른다 — 본인(profiles) vs 고객(managed_user) 분기는
  * 앱이 주입한 콜백 내부에서 현재 훈련 대상에 따라 결정한다.
  */
-import type { CoreNoiseSettings } from '../components/Training/NoisePlayerContext';
+import type { CoreNoiseSettings } from '../types/training';
 /** @public 소음설정 영속 저장소. 앱에서 Supabase 연결을 주입한다. */
 export interface NoiseSettingsStore {
     /** 현재 훈련 대상(본인 또는 고객)의 저장된 소음설정. 없으면 null. */

package/dist/packages/core/src/utils/wordTrainingGroups.d.ts

@@ -1,4 +1,4 @@
-import { type WordTrainingType } from '../hooks/useWordTrainingDataGeneration';
+import { type WordTrainingType } from './wordTrainingRuntimeTypes';
 export interface TrainingGroup {
     key: string;
     label: string;

package/dist/packages/core/src/utils/wordTrainingRuntimeTypes.d.ts

@@ -87,3 +87,17 @@ export declare function hasQuestionWordConstraint(typeKey: WordTrainingTypeKey):
 export declare function isValidQuestionWord(typeKey: WordTrainingTypeKey, word: string): boolean;
 /** @public 자동 문제생성 불가(수동 구성 전용) 타입인가. */
 export declare function isManualOnlyType(typeKey: WordTrainingTypeKey): boolean;
+/**
+ * 훈련 갈래 한 줄 — 열쇠와 화면에 보일 이름표.
+ * `hooks/useWordTrainingDataGeneration` 이 만들어 내보내고
+ * `utils/wordTrainingGroups` 가 묶을 때 읽는다. 두 계층이 함께 아는 모양이라
+ * 열쇠 타입이 있는 여기(아래 계층)에 둔다.
+ * @public
+ */
+export interface WordTrainingType {
+    key: WordTrainingTypeKey;
+    label: string;
+    icon: string;
+    color: string;
+    subTitle: string;
+}

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

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

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

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