@ihabdevteam/core 0.8.0

package/dist/packages/core/src/components/TopBanner.css

@@ -0,0 +1,100 @@
+/* ── TopBanner ────────────────────────────────────────────────────────── */
+.top-banner {
+  position: relative;
+  display: flex;
+  flex-direction: column;
+  padding-bottom: var(--spacing-page);
+}
+
+/* 높이를 120px로 고정하고 overflow:hidden이라, 제목이 두 줄로 늘어나는 배너에서
+   설명 문구가 잘려 나갔다. 최소 높이만 보장하고 내용에 따라 늘어나게 둔다
+   (슬라이드는 아래 align-items로 서로 높이를 맞춘다).
+   트랙에도 같은 최소치가 필요한데, 부모 높이가 min-height라 %가 해석되지 않는다
+   (확정 높이가 아니므로). 변수로 묶어 두 곳이 같은 값을 쓰게 한다. */
+.top-banner {
+  --top-banner-min-h: 120px;
+}
+
+.top-banner__viewport {
+  overflow: hidden;
+  border-radius: var(--radius-m);
+  min-height: var(--top-banner-min-h);
+}
+
+.top-banner__track {
+  display: flex;
+  /* height:100%였을 땐 내용이 많아도 트랙이 늘지 못해 배너가 잘렸고, 그렇다고 빼버리면
+     내용이 적을 때 트랙이 줄어 뷰포트 아래가 비었다. 최소치를 뷰포트와 같은 변수로 맞춘다. */
+  min-height: var(--top-banner-min-h);
+  /* stretch — 슬라이드들이 가장 높은 배너에 맞춰 같은 높이를 갖는다(전환 시 들썩임 방지) */
+  align-items: stretch;
+  transition: transform 0.4s ease;
+}
+
+.top-banner__slide {
+  flex: 0 0 100%;
+  min-width: 0;
+}
+
+/* 슬라이드 내용물이 viewport를 꽉 채우도록 — 높이는 고정하지 않고 최소치만 맞춘다 */
+.top-banner__slide > * {
+  width: 100%;
+  min-height: 100%;
+  box-sizing: border-box;
+}
+
+/* Dots — 배너 안쪽 하단에 오버레이 */
+.top-banner__dots {
+  position: absolute;
+  left: 50%;
+  transform: translateX(-50%);
+  bottom: calc(var(--spacing-page) + 12px);
+  display: flex;
+  gap: 6px;
+}
+
+/* 점은 6px로 보이지만 손가락으로 짚기엔 너무 작다. 패딩으로 넓히면 점 사이 간격까지
+   벌어지므로(6px → 18px, 실측), 레이아웃에 영향이 없는 **투명 의사요소**로 히트 영역만
+   키운다.
+   ※ 가로 폭은 반드시 `점 폭 + 점 사이 간격` 이하여야 한다. 예전엔 24px 고정이었는데
+     비활성 점은 중심 간 거리가 12px(6+6)뿐이라 옆 점의 중심까지 덮었고, 겹친 자리에서는
+     DOM 상 뒤에 오는 형제가 이겨 **점을 정확히 눌러도 오른쪽 배너로 넘어갔다**
+     (실측: elementFromPoint 로 1·2번 점의 정중앙을 찍으면 각각 2·3번 점이 잡혔다).
+     아래 calc 는 비활성 12px / 활성 24px 로 커져, 옆 점의 히트 영역과 맞닿기만 하고
+     겹치지 않는다.
+   세로 24px 은 위아래로 여유가 있어 그대로 둔다. */
+.top-banner__dot {
+  position: relative;
+  width: 6px;
+  height: 6px;
+  padding: 0;
+  border: none;
+  border-radius: 3px;
+  background: var(--color-white-a30);
+  cursor: pointer;
+  transition: width 0.25s ease, background-color 0.25s ease;
+}
+.top-banner__dot::after {
+  content: '';
+  position: absolute;
+  top: 50%;
+  left: 50%;
+  transform: translate(-50%, -50%);
+  /* 6px 은 .top-banner__dots 의 gap 과 같은 값이다 — 둘을 함께 바꿔야 한다. */
+  width: calc(100% + 6px);
+  height: 24px;
+}
+
+.top-banner__dot--active {
+  width: 18px;
+  background: var(--color-white);
+}
+
+/* 밝은 배경 슬라이드용 톤 */
+.top-banner__dots--dark .top-banner__dot {
+  background: var(--color-lightGray-a80);
+}
+
+.top-banner__dots--dark .top-banner__dot--active {
+  background: var(--color-main);
+}

package/dist/packages/core/src/components/TopBanner.d.ts

@@ -0,0 +1,25 @@
+import { type ReactNode } from 'react';
+import './TopBanner.css';
+/** @public */
+export interface TopBannerProps {
+    /** 로테이션할 슬라이드들 — 각 자식이 슬라이드 한 장 */
+    children: ReactNode;
+    /** 자동 롤링 간격(ms). `0`이면 자동 롤링 안 함 */
+    interval?: number;
+    /**
+     * 슬라이드별 인디케이터 톤. 슬라이드 배경이 어두우면 `'light'`(흰 점),
+     * 밝으면 `'dark'`(회색/브랜드색 점). 생략 시 전부 `'light'`.
+     */
+    dotTone?: Array<'light' | 'dark'>;
+    className?: string;
+    /** 스크린리더용 영역 라벨. 생략하면 번역된 기본값('배너')을 쓴다. */
+    'aria-label'?: string;
+}
+/**
+ * 페이지 상단 롤링 배너 컨테이너.
+ * 슬라이드 전환·인디케이터·자동 롤링만 책임지고 내용물은 children으로 받는다.
+ * 슬라이드 내용이 "텍스트+버튼" 형태면 PromoBanner를 그대로 끼워 넣으면 된다.
+ *
+ * @public
+ */
+export default function TopBanner({ children, interval, dotTone, className, 'aria-label': ariaLabelProp, }: TopBannerProps): import("react").JSX.Element | null;

package/dist/packages/core/src/components/TopBanner.js

@@ -0,0 +1,36 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { cx } from '../utils/cx';
+import { Children, useEffect, useState } from 'react';
+import { useTranslation } from 'react-i18next';
+import './TopBanner.css';
+/**
+ * 페이지 상단 롤링 배너 컨테이너.
+ * 슬라이드 전환·인디케이터·자동 롤링만 책임지고 내용물은 children으로 받는다.
+ * 슬라이드 내용이 "텍스트+버튼" 형태면 PromoBanner를 그대로 끼워 넣으면 된다.
+ *
+ * @public
+ */
+export default function TopBanner({ children, interval = 5000, dotTone, className = '', 'aria-label': ariaLabelProp, }) {
+    /* 이 배너는 회원앱 첫 화면(오늘의 듣기)에 뜨고 호출부가 aria-label 을 주지 않는다.
+       한국어를 기본값으로 박아 두면 영어 화면에서도 스크린리더가 "배너"라고 읽는다. */
+    const { t } = useTranslation();
+    const ariaLabel = ariaLabelProp ?? t('topBanner.ariaLabel', '배너');
+    const slides = Children.toArray(children);
+    const count = slides.length;
+    const [index, setIndex] = useState(0);
+    const [paused, setPaused] = useState(false);
+    // 슬라이드 수가 줄어도 범위를 벗어나지 않도록
+    const current = count > 0 ? index % count : 0;
+    useEffect(() => {
+        if (count < 2 || interval <= 0 || paused)
+            return;
+        const id = window.setInterval(() => setIndex(i => (i + 1) % count), interval);
+        return () => window.clearInterval(id);
+    }, [count, interval, paused]);
+    if (count === 0)
+        return null;
+    return (_jsxs("section", { className: cx('top-banner', className), "aria-label": ariaLabel, "aria-roledescription": "carousel", onMouseEnter: () => setPaused(true), onMouseLeave: () => setPaused(false), onFocus: () => setPaused(true), onBlur: () => setPaused(false), children: [_jsx("div", { className: "top-banner__viewport", children: _jsx("div", { className: "top-banner__track", style: { transform: `translateX(-${current * 100}%)` }, children: slides.map((slide, i) => (_jsx("div", { className: "top-banner__slide", "aria-hidden": i !== current, ...(i !== current ? { inert: true } : {}), children: slide }, i))) }) }), count > 1 && (_jsx("div", { className: `top-banner__dots${(dotTone?.[current] ?? 'light') === 'dark' ? ' top-banner__dots--dark' : ''}`, children: slides.map((_, i) => (_jsx("button", { type: "button", className: `top-banner__dot${i === current ? ' top-banner__dot--active' : ''}`, "aria-label": t('topBanner.dotAriaLabel', {
+                        count, index: i + 1, defaultValue: `${count}개 중 ${i + 1}번째 배너`,
+                    }), "aria-current": i === current, onClick: () => setIndex(i) }, i))) }))] }));
+}

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

@@ -0,0 +1,17 @@
+import { type MutableRefObject } from 'react';
+import type { Segment } from './trainingStepAudioPlayerTypes';
+import './TrainingStepAudioPlayer.css';
+export default function WaveForm(props: {
+    src?: string;
+    segments?: Segment[] | null;
+    progress?: number;
+    totalDuration?: number;
+    onSegmentClick?: (idx: number) => void;
+    waveProgressRef?: MutableRefObject<HTMLDivElement | null>;
+    noiseSrc?: string | null;
+    noiseLevel?: number;
+    noiseSpeed?: number;
+    mainVolume?: number;
+    onReadyChange?: (ready: boolean) => void;
+    showSoundWaveForm?: boolean;
+}): import("react").JSX.Element;

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

@@ -0,0 +1,237 @@
+'use client';
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { getErrorMessage } from '../../utils/errorMessage';
+import './TrainingStepAudioPlayer.css';
+/**
+ * waveform 바 최소 픽셀 — 렌더 높이가 이 값 이하이면 바를 그리지 않는다(문장·소음 공통).
+ * 그려지는 바는 항상 이 값을 넘는 높이만 표시하며(가로 폭은 BAR_WIDTH=3px), 그 이하는 숨긴다.
+ */
+const MIN_BAR_PX = 4;
+// windowSeconds: 지정 시 파일의 처음 N초만 사용(소음을 문장 재생시간만큼만 그릴 때).
+// 컴포넌트 상태를 참조하지 않는 순수 계산이라 모듈 스코프로 분리 — 매 렌더 재생성되지 않는다.
+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;
+    }
+}
+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;
+    }
+}
+export default function WaveForm(props) {
+    const { src, segments, progress = 0, waveProgressRef, noiseSrc, noiseLevel = 0, noiseSpeed = 1, totalDuration = 0, mainVolume = 1, onReadyChange, showSoundWaveForm = true } = props;
+    const waveformRef = useRef(null);
+    const outerRef = useRef(null);
+    const [wavePeaks, setWavePeaks] = useState(null);
+    const [waveReady, setWaveReady] = useState(false);
+    const [barsTotal, setBarsTotal] = useState(null);
+    const [barGap, setBarGap] = useState(2);
+    // waveform 영역 높이(px) — 바 픽셀 높이 임계(최소 2px) 판정에 사용
+    const [waveHeightPx, setWaveHeightPx] = useState(0);
+    // 문장 뒤에 깔리는 소음 waveform 피크 (소음 켜짐 시)
+    const [noisePeaks, setNoisePeaks] = useState(null);
+    // 최초 1회 문장·소음 바가 동시에 드러난 뒤로는 true로 래치 — 이후 소음을 껐다 켜서
+    // noisePeaks가 재연산되는 동안에도 문장 바는 계속 보여야 하므로(소음 토글은 소음 레이어에만
+    // 영향을 줘야 함) 문장 바의 표시 여부를 bothReady 대신 자신의 waveReady로 되돌린다.
+    const [hasSyncedOnce, setHasSyncedOnce] = useState(false);
+    const BAR_WIDTH = 3;
+    const BAR_GAP = 3;
+    const MIN_BARS = 1;
+    const MAX_BARS = 300;
+    // 이전/다음 연타로 트랙이 연속 변경되면 fetch+decode가 병렬로 떠서, 늦게 도착한
+    // 이전 트랙의 피크가 최신 파형을 덮어쓸 수 있다 — 세대 토큰으로 마지막 요청만 반영한다.
+    const peaksGenRef = useRef(0);
+    const computePeaks = useCallback(async (url, barsParam) => {
+        const gen = ++peaksGenRef.current;
+        const fresh = () => peaksGenRef.current === gen;
+        try {
+            setWaveReady(false);
+            if (!url) {
+                if (fresh())
+                    setWavePeaks(null);
+                return;
+            }
+            let bars = barsParam;
+            if (!bars) {
+                try {
+                    for (let i = 0; i < 4; i++) {
+                        if (waveformRef.current || outerRef.current)
+                            break;
+                        await new Promise((r) => requestAnimationFrame(r));
+                    }
+                    await new Promise((r) => requestAnimationFrame(r));
+                    const el = waveformRef.current;
+                    const parentEl = outerRef && outerRef.current ? outerRef.current : (el ? el.closest('.audio-player__wave') : null);
+                    const rect = parentEl ? parentEl.getBoundingClientRect() : (el ? el.getBoundingClientRect() : null);
+                    const width = rect ? Math.max(100, rect.width) : 320;
+                    const height = rect ? rect.height : 0;
+                    if (height > 0)
+                        setWaveHeightPx(height);
+                    bars = Math.max(MIN_BARS, Math.min(MAX_BARS, Math.floor((width + BAR_GAP) / (BAR_WIDTH + BAR_GAP))));
+                    const usedBarWidth = bars * BAR_WIDTH;
+                    const gapCount = Math.max(0, bars - 1);
+                    const computedGap = gapCount > 0 ? (width - usedBarWidth) / gapCount : BAR_GAP;
+                    setBarGap(Math.max(0, computedGap));
+                }
+                catch (e) {
+                    bars = 120;
+                }
+            }
+            const peaks = await computePeaksFromUrl(url, bars);
+            if (!fresh())
+                return;
+            /* **못 받아 왔으면 준비됐다고 하지 않는다.** computePeaksFromUrl 은 실패를 던지지
+               않고 null 을 돌려준다 — 그래서 여기서 걸러 내지 않으면 아래 catch 로도 안 가고
+               그대로 ready 가 되어, 자리표시자(0.15) 바가 **진짜 파형인 척** 그려졌다.
+               기다리는 쪽(useWaveReady)도 "실패하면 준비 신호가 안 온다"를 전제로 상한
+               2.5초를 두고 있다 — 그 전제와도 어긋나 있었다. */
+            if (!peaks) {
+                setWavePeaks(null);
+                setWaveReady(false);
+                return;
+            }
+            setWavePeaks(peaks);
+            setBarsTotal(bars);
+            setWaveReady(true);
+        }
+        catch (e) {
+            if (!fresh())
+                return;
+            setWavePeaks(null);
+            setWaveReady(false);
+        }
+    }, [setWaveReady, setWavePeaks, setWaveHeightPx, setBarGap, setBarsTotal]);
+    // src/segments 변경 시 파형을 다시 계산하는 의도된 fetch-kickoff이다
+    /* eslint-disable react-hooks/set-state-in-effect */
+    useEffect(() => {
+        const url = (segments && segments[0] && segments[0].src) || src || (segments && segments.length === 1 && segments[0] && segments[0].src);
+        const safeUrl = typeof url === 'string' ? url : undefined;
+        computePeaks(safeUrl).catch(() => { });
+        setHasSyncedOnce(false); // 새 문장 — 최초 동시 등장 연출을 다시 적용한다
+    }, [src, segments, computePeaks]);
+    /* eslint-enable react-hooks/set-state-in-effect */
+    // 소음 waveform 피크 — 문장 재생시간만큼만(×소음속도) 그려 시간축을 문장과 정렬.
+    // 소음은 루프되므로 실제로 들리는 건 파일의 처음 (문장길이 × 속도)초 구간이다.
+    /* eslint-disable react-hooks/set-state-in-effect */
+    useEffect(() => {
+        let cancelled = false;
+        if (!noiseSrc || !barsTotal) {
+            setNoisePeaks(null);
+            return;
+        }
+        const windowSec = totalDuration > 0 ? totalDuration * (noiseSpeed || 1) : undefined;
+        computePeaksFromUrl(noiseSrc, barsTotal, windowSec)
+            .then((peaks) => { if (!cancelled)
+            setNoisePeaks(peaks); })
+            .catch(() => { if (!cancelled)
+            setNoisePeaks(null); });
+        return () => { cancelled = true; };
+    }, [noiseSrc, barsTotal, totalDuration, noiseSpeed]);
+    /* eslint-enable react-hooks/set-state-in-effect */
+    // 문장: 자기 최고치로 정규화해 세로 영역을 다 씀 × 재생 소리(볼륨).
+    // 소음은 이 문장 최고치(sentenceMaxPeak)를 공통 분모로 써서 서로 비율이 유지된다.
+    const mainAmp = Math.max(0, Math.min(1, mainVolume));
+    const sentenceMaxPeak = useMemo(() => (wavePeaks && wavePeaks.length) ? (Math.max(...wavePeaks) || 1) : 1, [wavePeaks]);
+    const barsCountForMix = barsTotal || 40;
+    // 최대 300개 바가 재생/미재생 두 레이어에 그려지므로, 볼륨 슬라이더 드래그 등으로 부모가
+    // 연속 재렌더될 때 매번 전체 JSX를 재생성하지 않도록 입력값이 바뀔 때만 다시 만든다.
+    const bars = useMemo(() => Array.from({ length: barsCountForMix }).map((_, i) => {
+        const peak = wavePeaks && wavePeaks[i] != null ? wavePeaks[i] : null;
+        const eff = peak == null ? null : Math.min(1, (peak / sentenceMaxPeak) * mainAmp);
+        // 로딩 시 placeholder(0.15); 계산 후엔 렌더 높이(eff×waveHeightPx)가 MIN_BAR_PX 이하면 숨김(0)
+        const belowMin = eff != null && waveHeightPx > 0 && eff * waveHeightPx <= MIN_BAR_PX;
+        const val = eff == null ? 0.15 : (belowMin ? 0 : eff);
+        // 가로 위치 비율(0=왼쪽 lightMain ~ 1=오른쪽 lightSub) — 바 색을 위치에 따라 믹스
+        const mix = barsCountForMix > 1 ? i / (barsCountForMix - 1) : 0;
+        const style = { ['--val']: val, ['--i']: i, ['--mix']: mix };
+        // MIN_BAR_PX 이하로 숨겨지는 바는 최초 등장 애니메이션에서도 잠깐 비쳐 보이지 않도록 애니메이션 자체를 건너뛴다
+        const className = belowMin ? 'audio-player__bar audio-player__bar--hidden' : 'audio-player__bar';
+        return _jsx("div", { className: className, style: style }, i);
+    }), [barsCountForMix, wavePeaks, sentenceMaxPeak, mainAmp, waveHeightPx]);
+    // 초기 progress CSS 변수 값 (React 상태 기준 — RAF 루프가 이후 직접 갱신합니다)
+    const progressStyle = { '--progress': String(Math.max(0, Math.min(1, progress))) };
+    // 컨테이너 실제 폭에 맞춰 정밀 계산한 바 간격 — outer에 걸어 .audio-player__wave-inner 등
+    // 하위 요소들의 CSS 변수(--bar-gap, 기본 3px)로 상속시킨다. 계산은 하되 값을 어디에도
+    // 바인딩하지 않아 항상 하드코딩된 기본값(3px)으로만 그려지던 문제 — 실제로 적용한다.
+    const outerStyle = { '--bar-gap': `${barGap}px` };
+    // 소음 바 높이 = (절대진폭 / 문장 최고치) × 실제 재생 볼륨(level/9 — TrainingStepAudioPlayer와 동일 공식).
+    // 문장과 같은 분모(sentenceMaxPeak)를 써서 문장 대비 소음 비율이 미터와 일치.
+    const noiseAmp = Math.max(0, Math.min(9, noiseLevel)) / 9;
+    const noiseReady = !!noisePeaks;
+    // 소음 연산은 문장 연산(barsTotal 확정) 이후에 시작돼 항상 더 늦게 끝난다 — 문장 바가 먼저 나타났다가
+    // 소음 바만 뒤늦게 팝인하는 것을 막기 위해, 최초 등장 시엔 두 계산이 모두 끝난 뒤 함께 드러낸다.
+    const bothReady = waveReady && (noiseSrc ? noiseReady : true);
+    // 최초로 함께 드러난 뒤에는 래치 — 이후 소음 토글/재계산으로 noiseReady가 잠깐 false가 되어도
+    // 문장 바(mainReady)는 계속 waveReady만 따르게 해 소음 토글이 문장 바까지 가리지 않게 한다.
+    /* eslint-disable react-hooks/set-state-in-effect */
+    useEffect(() => {
+        if (bothReady)
+            setHasSyncedOnce(true);
+    }, [bothReady]);
+    /* eslint-enable react-hooks/set-state-in-effect */
+    const mainReady = hasSyncedOnce ? waveReady : bothReady;
+    // 부모(TrainingStepAudioPlayer)가 이 값을 보고 "waveform이 화면에 배치되기 전에는
+    // 재생을 시작하지 않도록" 대기할 수 있게 준비 상태를 그대로 알려준다.
+    useEffect(() => {
+        onReadyChange?.(mainReady);
+    }, [mainReady, onReadyChange]);
+    const noiseCount = barsTotal || 40;
+    // 문장 바와 같은 이유로 메모 — 입력값이 바뀔 때만 재생성
+    const noiseBars = useMemo(() => Array.from({ length: noiseCount }).map((_, i) => {
+        const peak = noisePeaks && noisePeaks[i] != null ? noisePeaks[i] : null;
+        const eff = peak == null ? 0 : Math.min(1, (peak / sentenceMaxPeak) * noiseAmp);
+        // 렌더 높이(eff×waveHeightPx)가 MIN_BAR_PX 이하면 숨김(0)
+        const belowMin = waveHeightPx > 0 && eff * waveHeightPx <= MIN_BAR_PX;
+        const val = belowMin ? 0 : eff;
+        // 가로 위치 비율(0=왼쪽 deepMain ~ 1=오른쪽 deepSub) — 바 색을 위치에 따라 믹스
+        const mix = noiseCount > 1 ? i / (noiseCount - 1) : 0;
+        const style = { ['--val']: val, ['--i']: i, ['--mix']: mix };
+        // MIN_BAR_PX 이하로 숨겨지는 바는 최초 등장 애니메이션에서도 잠깐 비쳐 보이지 않도록 애니메이션 자체를 건너뛴다
+        const className = belowMin ? 'audio-player__bar audio-player__bar--hidden' : 'audio-player__bar';
+        return _jsx("div", { className: className, style: style }, i);
+    }), [noiseCount, noisePeaks, sentenceMaxPeak, noiseAmp, waveHeightPx]);
+    return (_jsxs("div", { className: "audio-player__wave", ref: outerRef, style: outerStyle, children: [noiseSrc && (_jsx("div", { className: `audio-player__wave-noise ${bothReady ? 'is-ready' : ''}`, "aria-hidden": "true", children: noiseBars })), showSoundWaveForm && (_jsxs(_Fragment, { children: [_jsx("div", { className: `audio-player__wave-inner audio-player__wave-unplayed ${mainReady ? 'is-ready' : ''}`, ref: waveformRef, children: bars }), _jsx("div", { className: `audio-player__wave-inner audio-player__wave-played ${mainReady ? 'is-ready' : ''}`, ref: waveProgressRef, style: progressStyle, children: bars })] }))] }));
+}

package/dist/packages/core/src/components/Training/CategoryIcon.css

@@ -0,0 +1,85 @@
+/* ── CategoryIcon ─────────────────────────────── */
+
+/* Default: card-sized icon (40×40) */
+.category-icon {
+  width: 40px;
+  height: 40px;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  border-radius: var(--radius-s);
+  /* 배경색은 아이콘 색(--t-item-fg)의 10% 투명도로 자동 파생 — --t-item-bg 지정 시 그 값이 우선 */
+  background: var(--t-item-bg, color-mix(in srgb, var(--t-item-fg, var(--color-lightGray)) 10%, transparent));
+  color: var(--t-item-fg, var(--color-lightGray));
+  font-size: 18px;
+  flex-shrink: 0;
+}
+
+/* Small variant: 28×28 box */
+.category-icon--small {
+  width: 28px;
+  height: 28px;
+  border-radius: var(--radius-sm);
+}
+
+/* ── Inner renderers ──────────────────────────────────── */
+.category-icon__mask {
+  display: inline-block;
+  background-color: var(--t-item-fg, currentColor);
+  -webkit-mask-image: var(--icon-url);
+  -webkit-mask-repeat: no-repeat;
+  -webkit-mask-position: center;
+  -webkit-mask-size: contain;
+  mask-image: var(--icon-url);
+  mask-repeat: no-repeat;
+  mask-position: center;
+  mask-size: contain;
+  border-radius: var(--radius-sm);
+}
+
+.category-icon__image {
+  display: block;
+  object-fit: contain;
+  border-radius: var(--radius-sm);
+}
+
+.category-icon__svg svg {
+  display: block;
+  fill: currentColor;
+}
+
+/* ── Wrapper (for hover target) ───────────────────────── */
+.category-icon__wrap {
+  display: inline-flex;
+  position: relative;
+  cursor: default;
+}
+
+/* When used inside a training card, position the wrapper at the
+   card's top-left and render the inner icon without a second offset. */
+.training-list__item .category-icon__wrap {
+  position: absolute;
+  top: 18px;
+  left: 18px;
+}
+.training-list__item .category-icon {
+  position: static;   /* 크기는 iconSize prop(CategoryIcon --small/기본)이 결정 */
+}
+
+/* ── Hover tooltip ────────────────────────────────────── */
+.category-icon__tooltip {
+  white-space: nowrap;
+  pointer-events: none;
+  
+}
+
+.category-icon__tooltip-text {
+  display: block;
+  padding: 6px 12px;
+  font-size: 13px;
+  line-height: 1.4;
+  color: #ffffff;
+  background: var(--color-darkGray);
+  border-radius: var(--radius-sm);
+  box-shadow: var(--shadow-tooltip);
+}

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

@@ -0,0 +1,16 @@
+import { type CSSProperties, type ReactNode } from "react";
+import "./CategoryIcon.css";
+/** @public */
+export type CategoryIconProps = {
+    icon?: ReactNode | string;
+    label?: ReactNode;
+    tooltip?: ReactNode;
+    wrapperStyle?: CSSProperties;
+    color?: string;
+    bgColor?: string;
+    useHover?: boolean;
+    /** 아이콘 크기. medium(기본): 박스 40px·아이콘 20px / small: 박스 28px·아이콘 16px */
+    iconSize?: 'medium' | 'small';
+};
+/** @public */
+export default function CategoryIcon({ icon, label, tooltip, wrapperStyle, color, bgColor, useHover, iconSize }: CategoryIconProps): import("react").JSX.Element;

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

@@ -0,0 +1,79 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { cx } from '../../utils/cx';
+import { useCallback, useRef, useState, useEffect, useLayoutEffect, useMemo } from "react";
+import InfoTooltip from "../Tooltip/InfoTooltip";
+import Icon from '../Icon';
+import "./CategoryIcon.css";
+/** @public */
+export default function CategoryIcon({ icon, label, tooltip, wrapperStyle, color, bgColor, useHover = true, iconSize = 'medium' }) {
+    const isSmallIcon = iconSize === 'small';
+    const cls = cx('category-icon', isSmallIcon ? 'category-icon--small' : '');
+    const svgSize = isSmallIcon ? 16 : 20;
+    const ref = useRef(null);
+    const [hover, setHover] = useState(false);
+    const resolvedWrapperStyle = useMemo(() => {
+        const base = wrapperStyle && typeof wrapperStyle === 'object' ? { ...wrapperStyle } : {};
+        if (!color && !bgColor)
+            return base;
+        return {
+            ...base,
+            ...(color ? { color, '--t-item-fg': color } : {}),
+            ...(bgColor ? { '--t-item-bg': bgColor } : {}),
+        };
+    }, [wrapperStyle, color, bgColor]);
+    const tipText = tooltip || label;
+    const [anchorRect, setAnchorRect] = useState(null);
+    useLayoutEffect(() => {
+        if (hover)
+            setAnchorRect(ref.current?.getBoundingClientRect() ?? null);
+    }, [hover]);
+    // useHover가 false로 바뀌면 열려 있던 hover 상태를 강제로 닫는 의도된 동기화다
+    /* eslint-disable react-hooks/set-state-in-effect */
+    useEffect(() => {
+        if (!useHover && hover) {
+            try {
+                setHover(false);
+            }
+            catch (e) { }
+        }
+    }, [useHover, hover]);
+    /* eslint-enable react-hooks/set-state-in-effect */
+    useEffect(() => {
+        if (!hover)
+            return;
+        const handler = (e) => {
+            const el = ref.current;
+            if (!el)
+                return;
+            const t = e.target;
+            if (t && !el.contains(t))
+                setHover(false);
+        };
+        document.addEventListener('pointerdown', handler, true);
+        return () => document.removeEventListener('pointerdown', handler, true);
+    }, [hover]);
+    const handleHoverOn = useCallback(() => { if (useHover)
+        setHover(true); }, [useHover]);
+    const handleHoverOff = useCallback(() => { if (useHover)
+        setHover(false); }, [useHover]);
+    const handleTooltipClose = useCallback(() => setHover(false), []);
+    const handleKeyDown = useCallback((e) => {
+        if (e.key === 'Escape') {
+            setHover(false);
+            return;
+        }
+        /* **Enter·Space 로도 열고 닫힌다.**
+           이 span 은 `role="button"` 에 `aria-expanded` 까지 달고 있다 — 낭독기는 그것을 보고
+           "눌러서 펼치는 것"이라고 읽어 준다. 그런데 여는 길이 마우스 올리기와 초점 받기뿐이라,
+           **읽어 준 대로 눌러도 아무 일이 없었다.** 초점만으로 열리는 것에 기대면 Tab 으로
+           지나칠 때마다 툴팁이 따라 열리고, 한번 닫은 뒤에는 다시 열 방법이 없다.
+           Space 는 기본 동작(페이지 스크롤)을 막는다 — 안 막으면 눌 때마다 화면이 내려간다.
+           `useHover` 는 마우스 동작을 끄는 스위치라 여기서는 보지 않는다(키보드는 별개다). */
+        if (e.key === 'Enter' || e.key === ' ') {
+            e.preventDefault();
+            setHover(v => !v);
+        }
+    }, []);
+    return (_jsxs("span", { ref: ref, className: "category-icon__wrap", onPointerEnter: handleHoverOn, onPointerLeave: handleHoverOff, onFocus: handleHoverOn, onBlur: handleHoverOff, onKeyDown: handleKeyDown, role: "button", tabIndex: 0, "aria-label": typeof tipText === 'string' ? tipText : undefined, "aria-haspopup": !!tipText, "aria-expanded": hover, "data-tooltip-ignore": true, children: [_jsx(Icon, { icon: icon, label: label, className: cls, imgClassName: "category-icon__image", maskClassName: "category-icon__mask", svgClassName: "category-icon__svg", wrapperStyle: resolvedWrapperStyle, size: svgSize }), hover && tipText && (_jsx(InfoTooltip, { anchorRect: anchorRect, text: typeof tipText === 'string' ? tipText : undefined, offset: 8, onClose: handleTooltipClose, className: "category-icon__tooltip", ariaLabel: typeof tipText === 'string' ? tipText : undefined }))] }));
+}

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

@@ -0,0 +1,43 @@
+/** @public */
+export type CoreNoiseType = 'defaultNoise' | 'street' | 'restaurant' | 'buzz';
+/** @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 declare const LEVEL_MAX = 9;
+/** @public */
+export declare const levelToPct: (level: number) => number;
+/** @public */
+export declare const pctToLevel: (pct: number) => number;
+/** @public */
+export type NoisePlayerContextValue = {
+    settings: CoreNoiseSettings;
+    setSettings: (next: Partial<CoreNoiseSettings>) => void;
+    /** 오디오 레벨 미터용 AnalyserNode 등록(오디오 플레이어가 호출). */
+    registerAnalyser?: (which: 'main' | 'noise', analyser: AnalyserNode | null) => void;
+    /** 문장(메인) 오디오 미터용 AnalyserNode. */
+    mainAnalyser?: AnalyserNode | null;
+    /** 소음 오디오 미터용 AnalyserNode. */
+    noiseAnalyser?: AnalyserNode | null;
+    /** 문장(메인) 재생 속도(playbackRate). 0.5–1.5, 기본 1. */
+    playbackRate: number;
+    setPlaybackRate: (rate: number) => void;
+    /** 문장(메인) 재생 소리(볼륨). 0–1, 기본 1. */
+    mainVolume: number;
+    setMainVolume: (v: number) => void;
+};
+export declare const DEFAULT_NOISE_SETTINGS: CoreNoiseSettings;
+/** @public */
+export declare const NoisePlayerContext: import("react").Context<NoisePlayerContextValue | null>;
+/** @public */
+export declare function useNoisePlayer(): NoisePlayerContextValue | null;