@ihabdevteam/core 0.8.0

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

@@ -0,0 +1,56 @@
+'use client';
+import { useCallback, useEffect, useRef } from 'react';
+/**
+ * 만들어 놓은 blob URL 을 빠짐없이 되돌려준다.
+ *
+ * 소리 파일을 직접 내려받아 재생하는 폴백 경로에서 `URL.createObjectURL` 로 임시 주소를
+ * 만든다. 이 주소는 **브라우저가 알아서 안 치운다** — 문서가 살아 있는 한 그 blob 이
+ * 메모리에 남는다. 훈련 화면은 한 세션에서 소리를 수십 개 갈아 끼우므로, 한 번 빠뜨리면
+ * 그만큼 그대로 쌓인다. 눈에 보이는 증상은 없고 탭이 점점 무거워질 뿐이라 **알아채기가
+ * 가장 어려운 종류의 새는 자리**다.
+ *
+ * 규칙은 둘뿐이다.
+ *
+ *  1. 만들면 **반드시** 여기에 맡긴다(`track`).
+ *  2. 소스 목록이 바뀌면 **남을 것만 남기고 나머지는 되돌려준다**(`keepOnly`).
+ *     화면을 떠날 때는 전부 되돌려준다.
+ *
+ * 원래 `TrainingStepAudioPlayer` 안에 ref 둘로 있었는데, 그중 하나(`objectUrlRef`,
+ * "지금 재생 중인 하나")는 **null 만 대입되고 URL 이 들어가는 곳이 없어서** 그 옆의
+ * `revokeObjectURL` 이 한 번도 실행된 적이 없었다. 다행히 실제 회수는 나머지 하나가
+ * 전부 하고 있어 새지는 않았다. 죽은 반쪽을 걷어내고 살아 있는 규칙만 남긴다.
+ */
+export function useObjectUrls() {
+    const urlsRef = useRef([]);
+    /** 새로 만든 주소를 맡긴다 */
+    const track = useCallback((url) => {
+        urlsRef.current.push(url);
+        return url;
+    }, []);
+    /** 계속 쓸 것만 남기고 나머지는 되돌려준다 */
+    const keepOnly = useCallback((keep) => {
+        const 남길것 = new Set([...keep].filter(Boolean));
+        urlsRef.current = urlsRef.current.filter(u => {
+            if (남길것.has(u))
+                return true;
+            try {
+                URL.revokeObjectURL(u);
+            }
+            catch { /* 이미 회수됐거나 만든 적 없는 주소 */ }
+            return false;
+        });
+    }, []);
+    /** 전부 되돌려준다 */
+    const revokeAll = useCallback(() => { keepOnly([]); }, [keepOnly]);
+    /* 화면을 떠날 때가 마지막 기회다 — 여기서 안 놓으면 탭을 닫을 때까지 남는다. */
+    useEffect(() => () => {
+        for (const u of urlsRef.current) {
+            try {
+                URL.revokeObjectURL(u);
+            }
+            catch { /* 위와 같다 */ }
+        }
+        urlsRef.current = [];
+    }, []);
+    return { track, keepOnly, revokeAll };
+}

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

@@ -0,0 +1,33 @@
+import { type RefObject } from 'react';
+import type { Source } from './trainingStepAudioPlayerTypes';
+/**
+ * 재생 중 진행 표시를 매 프레임 갱신한다.
+ *
+ * 진행 마커와 파형의 채워진 부분은 **React 를 거치지 않고** DOM 스타일을 직접 쓴다.
+ * 초당 예순 번 상태를 바꾸면 그때마다 컴포넌트 전체가 다시 그려져서, 파형 바 300개가
+ * 매 프레임 재생성된다. 눈에 보이는 것은 두 값(마커 위치, 파형 진행률)뿐이라 그 둘만
+ * 직접 만진다.
+ *
+ * **모아 놓은 진짜 이유는 멈추는 쪽이다.** 이 프레임 사슬은 재생·일시정지·종료·트랙
+ * 이동·화면 떠나기 — 다섯 갈래에서 멈춰야 하는데, 원래는 그 취소 코드가 **아홉 군데**에
+ * 똑같이 흩어져 있었다.
+ *
+ *     if (rafRef.current) { cancelAnimationFrame(rafRef.current); rafRef.current = null }
+ *
+ * 한 군데를 빠뜨리면 사슬이 살아남아 이미 끝난 소리의 진행률을 계속 그린다 — 마커가
+ * 혼자 움직이는 상태다. 오류도 안 뜨고, 다음 재생이 시작되면 겹쳐서 두 배 속도로 움직인다.
+ * `start()` / `stop()` 둘로 줄인다.
+ */
+export declare function useProgressTicker({ audioRef, fillRef, waveProgressRef, sourcesRef, currentIndexRef, }: {
+    audioRef: RefObject<HTMLAudioElement | null>;
+    /** 진행 마커 — `left` 를 퍼센트로 민다 */
+    fillRef: RefObject<HTMLDivElement | null>;
+    /** 파형 — `--progress` 사용자 정의 속성으로 채운다 */
+    waveProgressRef: RefObject<HTMLDivElement | null>;
+    sourcesRef: RefObject<Source[] | null>;
+    currentIndexRef: RefObject<number>;
+}): {
+    start: () => void;
+    stop: () => void;
+    settleTo: (pos: number) => void;
+};

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

@@ -0,0 +1,74 @@
+'use client';
+import { useCallback, useEffect, useRef } from 'react';
+import { progressOf } from './audioPlaybackRules';
+/**
+ * 재생 중 진행 표시를 매 프레임 갱신한다.
+ *
+ * 진행 마커와 파형의 채워진 부분은 **React 를 거치지 않고** DOM 스타일을 직접 쓴다.
+ * 초당 예순 번 상태를 바꾸면 그때마다 컴포넌트 전체가 다시 그려져서, 파형 바 300개가
+ * 매 프레임 재생성된다. 눈에 보이는 것은 두 값(마커 위치, 파형 진행률)뿐이라 그 둘만
+ * 직접 만진다.
+ *
+ * **모아 놓은 진짜 이유는 멈추는 쪽이다.** 이 프레임 사슬은 재생·일시정지·종료·트랙
+ * 이동·화면 떠나기 — 다섯 갈래에서 멈춰야 하는데, 원래는 그 취소 코드가 **아홉 군데**에
+ * 똑같이 흩어져 있었다.
+ *
+ *     if (rafRef.current) { cancelAnimationFrame(rafRef.current); rafRef.current = null }
+ *
+ * 한 군데를 빠뜨리면 사슬이 살아남아 이미 끝난 소리의 진행률을 계속 그린다 — 마커가
+ * 혼자 움직이는 상태다. 오류도 안 뜨고, 다음 재생이 시작되면 겹쳐서 두 배 속도로 움직인다.
+ * `start()` / `stop()` 둘로 줄인다.
+ */
+export function useProgressTicker({ audioRef, fillRef, waveProgressRef, sourcesRef, currentIndexRef, }) {
+    const rafRef = useRef(null);
+    const stop = useCallback(() => {
+        if (rafRef.current === null)
+            return;
+        cancelAnimationFrame(rafRef.current);
+        rafRef.current = null;
+    }, []);
+    const start = useCallback(() => {
+        // 이미 돌고 있으면 겹쳐 걸지 않는다 — 두 사슬이 같은 값을 다투면 마커가 떤다
+        if (rafRef.current !== null)
+            return;
+        const step = () => {
+            try {
+                const a = audioRef.current;
+                const pos = progressOf({
+                    currentTime: a && typeof a.currentTime === 'number' ? a.currentTime : 0,
+                    sources: sourcesRef.current,
+                    index: currentIndexRef.current,
+                    audioDuration: a && a.duration ? a.duration : 0,
+                });
+                try {
+                    if (fillRef.current)
+                        fillRef.current.style.left = `${pos * 100}%`;
+                }
+                catch { /* 떼어진 노드 */ }
+                try {
+                    waveProgressRef.current?.style.setProperty('--progress', String(pos));
+                }
+                catch { /* 위와 같다 */ }
+            }
+            catch { /* 한 프레임이 실패해도 사슬은 이어 간다 */ }
+            rafRef.current = requestAnimationFrame(step);
+        };
+        rafRef.current = requestAnimationFrame(step);
+    }, [audioRef, fillRef, waveProgressRef, sourcesRef, currentIndexRef]);
+    /** 다 들었을 때처럼 끝에 붙여 놓아야 하는 자리 */
+    const settleTo = useCallback((pos) => {
+        stop();
+        try {
+            if (fillRef.current)
+                fillRef.current.style.left = `${pos * 100}%`;
+        }
+        catch { /* 떼어진 노드 */ }
+        try {
+            waveProgressRef.current?.style.setProperty('--progress', String(pos));
+        }
+        catch { /* 위와 같다 */ }
+    }, [stop, fillRef, waveProgressRef]);
+    /* 화면을 떠나면 반드시 멈춘다 — 여기가 마지막 그물이다. */
+    useEffect(() => stop, [stop]);
+    return { start, stop, settleTo };
+}

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

@@ -0,0 +1,30 @@
+import { type RefObject } from 'react';
+type PlaybackState = 'stopped' | 'playing' | 'paused';
+/**
+ * TrainingStepAudioPlayer에서 분리 — speechSynthesis 기반 TTS 재생(추정 길이 산출, 진행률 RAF,
+ * 소음 동기화, 종료 처리)을 전담한다. handleEndRef는 handleEnd()가 정의된 이후에 채워지는
+ * 기존 패턴(native 'ended' 이벤트와 동일)을 그대로 재사용해 순환 의존을 피한다.
+ */
+export declare function useTTSPlayback({ ttsText, playbackRate, mainVolume, fillRef, waveProgressRef, setProgress, setPlaybackState, setStateLocal, fadeInNoise, fadeOutNoise, noiseSettingsRef, onDoneRef, handleEndRef, }: {
+    ttsText?: string | string[] | null;
+    playbackRate: number;
+    mainVolume: number;
+    fillRef: RefObject<HTMLDivElement | null>;
+    waveProgressRef: RefObject<HTMLDivElement | null>;
+    setProgress: (p: number) => void;
+    setPlaybackState: (s: PlaybackState) => void;
+    setStateLocal: (s: string) => void;
+    fadeInNoise: (targetVolume: number, durationMs?: number) => void;
+    fadeOutNoise: (durationMs?: number, onComplete?: () => void) => void;
+    noiseSettingsRef: RefObject<{
+        enabled: boolean;
+        level: number;
+        type: string;
+    } | null>;
+    onDoneRef: RefObject<((ok?: boolean) => void) | undefined>;
+    handleEndRef: RefObject<(() => void) | null>;
+}): {
+    startTTS: (text?: string) => void;
+    stopTTS: () => void;
+};
+export {};

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

@@ -0,0 +1,172 @@
+'use client';
+import { useCallback, useEffect, useRef } from 'react';
+/**
+ * TrainingStepAudioPlayer에서 분리 — speechSynthesis 기반 TTS 재생(추정 길이 산출, 진행률 RAF,
+ * 소음 동기화, 종료 처리)을 전담한다. handleEndRef는 handleEnd()가 정의된 이후에 채워지는
+ * 기존 패턴(native 'ended' 이벤트와 동일)을 그대로 재사용해 순환 의존을 피한다.
+ */
+export function useTTSPlayback({ ttsText, playbackRate, mainVolume, fillRef, waveProgressRef, setProgress, setPlaybackState, setStateLocal, fadeInNoise, fadeOutNoise, noiseSettingsRef, onDoneRef, handleEndRef, }) {
+    /* 남은 셋만 실제로 쓰인다. 한때 일곱이었는데 넷은 아무도 안 읽었다 —
+       utterance·finished·utterEnd 는 넣기만 하고 읽는 곳이 없었고,
+       speakTimer 는 **타이머를 넣는 곳이 아예 없어** 늘 null 이라 그 clearTimeout 도
+       한 번도 실행된 적이 없다. 다음 사람이 "무언가를 지키는 값"으로 오해하지 않도록 걷어낸다. */
+    const ttsStartRef = useRef(null);
+    const ttsEstimatedDurationRef = useRef(0);
+    const ttsRafRef = useRef(null);
+    useEffect(() => {
+        // cleanup TTS resources on unmount
+        return () => {
+            try {
+                if (ttsRafRef.current) {
+                    cancelAnimationFrame(ttsRafRef.current);
+                    ttsRafRef.current = null;
+                }
+                if (window.speechSynthesis) {
+                    try {
+                        window.speechSynthesis.cancel();
+                    }
+                    catch (e) { }
+                }
+            }
+            catch (e) { }
+        };
+    }, []);
+    const estimateTTSDuration = (text, rate = 1) => {
+        try {
+            const words = (text || '').trim().split(/\s+/).filter(Boolean).length || Math.max(1, (text || '').length);
+            const msPerWord = 300; // heuristic
+            const est = Math.max(700, Math.round((words * msPerWord) / Math.max(0.25, rate)));
+            return est;
+        }
+        catch (e) {
+            return 1200;
+        }
+    };
+    const startTTS = useCallback((text) => {
+        if (typeof window === 'undefined' || !window.speechSynthesis) {
+            try {
+                if (typeof onDoneRef.current === 'function')
+                    onDoneRef.current(true);
+            }
+            catch (e) { }
+            return;
+        }
+        const synth = window.speechSynthesis;
+        try {
+            try {
+                synth.cancel();
+            }
+            catch (e) { }
+            const rawTts = text ?? ttsText;
+            const t = (Array.isArray(rawTts) ? rawTts[0] ?? '' : rawTts) || '';
+            const utt = new SpeechSynthesisUtterance(t);
+            try {
+                utt.rate = Math.max(0.3, Math.min(3, playbackRate));
+            }
+            catch (e) { }
+            try {
+                utt.volume = Math.max(0, Math.min(1, mainVolume));
+            }
+            catch (e) { }
+            ttsEstimatedDurationRef.current = estimateTTSDuration(t, utt.rate || 1);
+            ttsStartRef.current = performance.now();
+            setProgress(0);
+            setPlaybackState('playing');
+            setStateLocal('playMode');
+            // TTS 시작 시 소음 동기 재생
+            const ns = noiseSettingsRef.current;
+            if (ns?.enabled && (ns?.level ?? 0) > 0) {
+                fadeInNoise(ns.level / 9);
+            }
+            const tick = () => {
+                try {
+                    const start = ttsStartRef.current || performance.now();
+                    const elapsed = performance.now() - start;
+                    const est = ttsEstimatedDurationRef.current || 1200;
+                    const p = Math.min(1, elapsed / est);
+                    setProgress(p);
+                    try {
+                        if (fillRef.current)
+                            fillRef.current.style.left = `${p * 100}%`;
+                        if (waveProgressRef.current)
+                            waveProgressRef.current.style.setProperty('--progress', String(p));
+                    }
+                    catch (e) { }
+                    if (p < 1) {
+                        ttsRafRef.current = requestAnimationFrame(tick);
+                    }
+                }
+                catch (e) { }
+            };
+            utt.onend = () => {
+                try {
+                    if (ttsRafRef.current) {
+                        cancelAnimationFrame(ttsRafRef.current);
+                        ttsRafRef.current = null;
+                    }
+                    setProgress(1);
+                    setPlaybackState('stopped');
+                    try {
+                        handleEndRef.current?.();
+                    }
+                    catch (e) {
+                        try {
+                            if (typeof onDoneRef.current === 'function')
+                                onDoneRef.current(true);
+                        }
+                        catch (err) { }
+                    }
+                }
+                catch (e) { }
+            };
+            utt.onstart = () => {
+                try {
+                    if (ttsRafRef.current) {
+                        cancelAnimationFrame(ttsRafRef.current);
+                        ttsRafRef.current = null;
+                    }
+                    ttsRafRef.current = requestAnimationFrame(tick);
+                }
+                catch (e) { }
+            };
+            try {
+                synth.speak(utt);
+            }
+            catch (e) {
+                try {
+                    if (typeof onDoneRef.current === 'function')
+                        onDoneRef.current(true);
+                }
+                catch (err) { }
+            }
+        }
+        catch (e) {
+            try {
+                if (typeof onDoneRef.current === 'function')
+                    onDoneRef.current(true);
+            }
+            catch (err) { }
+        }
+    }, [ttsText, playbackRate, mainVolume, fadeInNoise, fillRef, waveProgressRef, setProgress, setPlaybackState, setStateLocal, noiseSettingsRef, onDoneRef, handleEndRef]);
+    const stopTTS = useCallback(() => {
+        try {
+            if (window.speechSynthesis) {
+                try {
+                    window.speechSynthesis.cancel();
+                }
+                catch (e) { }
+            }
+            if (ttsRafRef.current) {
+                cancelAnimationFrame(ttsRafRef.current);
+                ttsRafRef.current = null;
+            }
+            fadeOutNoise();
+            ttsStartRef.current = null;
+        }
+        catch (e) { }
+        setPlaybackState('stopped');
+        setStateLocal('active');
+        setProgress(0);
+    }, [fadeOutNoise, setPlaybackState, setStateLocal, setProgress]);
+    return { startTTS, stopTTS };
+}

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

@@ -0,0 +1,36 @@
+/**
+ * 파형이 자리를 잡을 때까지 기다린다.
+ *
+ * 피크 계산(내려받기 + 디코딩)은 오디오의 `canplay` 보다 늦게 끝날 수 있다. 그대로 두면
+ * **파형이 비어 있는 채로 소리가 먼저 난다** — 사용자는 "소리는 나는데 그림이 없는" 한
+ * 박자를 본다. 그래서 재생 직전에 여기서 기다린다.
+ *
+ * 세 가지를 이 훅이 책임진다.
+ *
+ *  1. **영영 안 끝날 수 있다** — 디코딩이 실패하면 준비 신호가 아예 안 온다. 그래서
+ *     기다림에는 반드시 상한이 있고, 넘으면 그냥 통과시킨다. *못 그리는 것보다 소리라도
+ *     나는 편이 낫다.*
+ *  2. **기다릴 대상이 없을 수 있다** — 파형을 아예 안 그리는 화면에서는 즉시 통과한다.
+ *     여기서 안 걸러 내면 그런 화면은 매번 상한만큼 늦게 재생된다.
+ *  3. **트랙이 바뀌면 다시 기다려야 한다** — 이전 트랙의 '준비됨'을 물려받으면 안 된다.
+ *     그래서 트랙을 갈아 끼우는 자리마다 `markNotReady()` 를 부른다.
+ *
+ * 원래 `TrainingStepAudioPlayer` 안에 흩어져 있었다. ref 둘과 함수 둘, 그리고
+ * `waveReadyRef.current = false` 가 **일곱 군데**에 직접 흩어져 있어서, 새 재생 경로를
+ * 추가하는 사람이 그 한 줄을 빠뜨리기 쉬웠다. 이름을 준 함수 하나로 모은다.
+ */
+export declare function useWaveReady({ 
+/** 문장 파형을 그리는가 */
+showSoundWaveForm, 
+/** 소음 파형을 그리는가 */
+showNoiseWaveForm, 
+/** 기다림 상한(ms) */
+timeoutMs, }: {
+    showSoundWaveForm: boolean;
+    showNoiseWaveForm: boolean;
+    timeoutMs?: number;
+}): {
+    onReadyChange: (ready: boolean) => void;
+    waitForReady: () => Promise<void>;
+    markNotReady: () => void;
+};

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

@@ -0,0 +1,65 @@
+'use client';
+import { useCallback, useEffect, useRef } from 'react';
+/**
+ * 파형이 자리를 잡을 때까지 기다린다.
+ *
+ * 피크 계산(내려받기 + 디코딩)은 오디오의 `canplay` 보다 늦게 끝날 수 있다. 그대로 두면
+ * **파형이 비어 있는 채로 소리가 먼저 난다** — 사용자는 "소리는 나는데 그림이 없는" 한
+ * 박자를 본다. 그래서 재생 직전에 여기서 기다린다.
+ *
+ * 세 가지를 이 훅이 책임진다.
+ *
+ *  1. **영영 안 끝날 수 있다** — 디코딩이 실패하면 준비 신호가 아예 안 온다. 그래서
+ *     기다림에는 반드시 상한이 있고, 넘으면 그냥 통과시킨다. *못 그리는 것보다 소리라도
+ *     나는 편이 낫다.*
+ *  2. **기다릴 대상이 없을 수 있다** — 파형을 아예 안 그리는 화면에서는 즉시 통과한다.
+ *     여기서 안 걸러 내면 그런 화면은 매번 상한만큼 늦게 재생된다.
+ *  3. **트랙이 바뀌면 다시 기다려야 한다** — 이전 트랙의 '준비됨'을 물려받으면 안 된다.
+ *     그래서 트랙을 갈아 끼우는 자리마다 `markNotReady()` 를 부른다.
+ *
+ * 원래 `TrainingStepAudioPlayer` 안에 흩어져 있었다. ref 둘과 함수 둘, 그리고
+ * `waveReadyRef.current = false` 가 **일곱 군데**에 직접 흩어져 있어서, 새 재생 경로를
+ * 추가하는 사람이 그 한 줄을 빠뜨리기 쉬웠다. 이름을 준 함수 하나로 모은다.
+ */
+export function useWaveReady({ 
+/** 문장 파형을 그리는가 */
+showSoundWaveForm, 
+/** 소음 파형을 그리는가 */
+showNoiseWaveForm, 
+/** 기다림 상한(ms) */
+timeoutMs = 2500, }) {
+    const readyRef = useRef(false);
+    const resolversRef = useRef([]);
+    /** 파형 쪽에서 준비 상태가 바뀌었다고 알려 온다 */
+    const onReadyChange = useCallback((ready) => {
+        readyRef.current = ready;
+        if (!ready || !resolversRef.current.length)
+            return;
+        const 기다리던것 = resolversRef.current;
+        resolversRef.current = [];
+        for (const 깨우기 of 기다리던것)
+            깨우기();
+    }, []);
+    /** 새 트랙을 물렸다 — 이전 트랙의 '준비됨'을 물려받지 않는다 */
+    const markNotReady = useCallback(() => { readyRef.current = false; }, []);
+    const waitForReady = useCallback(() => {
+        // 그릴 파형이 없으면 기다릴 것도 없다
+        if (!showSoundWaveForm && !showNoiseWaveForm)
+            return Promise.resolve();
+        if (readyRef.current)
+            return Promise.resolve();
+        return new Promise((resolve) => {
+            const timer = setTimeout(resolve, timeoutMs);
+            resolversRef.current.push(() => { clearTimeout(timer); resolve(); });
+        });
+    }, [showSoundWaveForm, showNoiseWaveForm, timeoutMs]);
+    /* 화면을 떠날 때 기다리던 것들을 놓아 준다. 안 그러면 상한 타이머가 살아남아
+       이미 사라진 화면의 재생 흐름을 뒤늦게 깨운다. */
+    useEffect(() => () => {
+        const 남은것 = resolversRef.current;
+        resolversRef.current = [];
+        for (const 깨우기 of 남은것)
+            깨우기();
+    }, []);
+    return { onReadyChange, waitForReady, markNotReady };
+}

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

@@ -0,0 +1,116 @@
+.update-alert {
+  position: fixed;
+  top: 16px;
+  right: 16px;
+  z-index: var(--z-alert);
+  width: 380px;
+  max-width: calc(100vw - 32px);
+  background: rgba(248, 248, 248, 0.92);
+  backdrop-filter: blur(20px) saturate(180%);
+  -webkit-backdrop-filter: blur(20px) saturate(180%);
+  border: 1px solid var(--color-main);
+  border-radius: var(--radius-m);
+  box-shadow:
+    0 4px 24px rgba(0, 0, 0, 0.14),
+    0 1px 4px rgba(0, 0, 0, 0.08),
+    inset 0 0 0 0.5px rgba(0, 0, 0, 0.1);
+  display: flex;
+  flex-direction: column;
+  gap: 12px;
+  padding: var(--spacing-l);
+  animation: update-alert-slide-in 0.32s cubic-bezier(0.34, 1.56, 0.64, 1) both;
+}
+
+/*
+ * 여러 장을 쌓는 컨테이너. 낱장은 스스로 fixed로 우상단에 붙으므로 그대로 두면
+ * 서로 완전히 겹친다 — 스택 안에서는 흐름 배치로 되돌려 아래로 이어 붙인다.
+ */
+.update-alert-stack {
+  position: fixed;
+  top: 16px;
+  right: 16px;
+  z-index: var(--z-alert);
+  display: flex;
+  flex-direction: column;
+  align-items: flex-end;
+  gap: 12px;
+  max-width: calc(100vw - 32px);
+}
+/* relative — 흐름 배치로 돌리되 닫기 버튼(absolute)의 기준은 낱장으로 남긴다 */
+.update-alert-stack .update-alert {
+  position: relative;
+  z-index: auto;
+}
+
+/* 닫기 버튼이 있을 때만 제목이 그 아래로 파고들지 않게 여백을 준다 */
+.update-alert:has(.update-alert__close) .update-alert__title {
+  padding-right: 24px;
+}
+
+.update-alert__close {
+  position: absolute;
+  top: 8px;
+  right: 8px;
+  width: 24px;
+  height: 24px;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  border: none;
+  background: none;
+  color: #888;
+  font-size: 20px;
+  line-height: 1;
+  cursor: pointer;
+  border-radius: var(--radius-s, 6px);
+}
+.update-alert__close:hover { color: #333; background: rgba(0, 0, 0, 0.06); }
+
+.update-alert__top {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+}
+
+@keyframes update-alert-slide-in {
+  from {
+    opacity: 0;
+    transform: translateX(calc(100% + 24px));
+  }
+  to {
+    opacity: 1;
+    transform: translateX(0);
+  }
+}
+
+
+.update-alert__icon {
+  flex-shrink: 0;
+  width: 40px;
+  height: 40px;
+  color: var(--color-main);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  font-size: 20px;
+}
+
+.update-alert__body {
+  flex: 1;
+  min-width: 0;
+}
+
+.update-alert__title {
+  color: #1a1a1a;
+  text-align: left;
+}
+
+.update-alert__message {
+  color: #555;
+  margin-top: 2px;
+  text-align: left;
+}
+
+.update-alert__action {
+  width: 100%;
+}

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

@@ -0,0 +1,23 @@
+import type { ReactNode } from 'react';
+import './UpdateAlert.css';
+/** @public */
+export interface UpdateAlertProps {
+    title: string;
+    message: string;
+    actionLabel?: string;
+    onAction?: () => void;
+    /** 좌측 아이콘. 생략하면 다운로드 아이콘(단어 데이터 업데이트 기본형). */
+    icon?: ReactNode;
+    /** 넘기면 우상단에 닫기(×) 버튼이 생긴다. */
+    onClose?: () => void;
+    className?: string;
+}
+/**
+ * macOS 스타일 우측 상단 고정 알림.
+ *
+ * 여러 장을 동시에 띄우려면 `.update-alert-stack`으로 감싼다 — 낱장은 스스로
+ * fixed로 붙지만 스택 안에서는 흐름 배치가 되어 아래로 쌓인다.
+ *
+ * @public
+ */
+export default function UpdateAlert({ title, message, actionLabel, onAction, icon, onClose, className, }: UpdateAlertProps): import("react").JSX.Element;

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

@@ -0,0 +1,25 @@
+/// <reference path="../types/lucide-deep-imports.d.ts" />
+// ↑ deep import 에 타입을 붙이는 앰비언트 선언. 이 파일에 붙여 두는 이유:
+// 소비 앱은 tsconfig 의 paths 로 core 소스를 직접 보는데, 그 include 에는
+// core 의 types/ 가 안 걸려 선언이 로드되지 않는다(관측: speechear TS7016 159개).
+// 참조를 쓰는 파일에 두면 import 를 타고 따라온다.
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import Download from 'lucide-react/dist/esm/icons/download.mjs';
+import { useTranslation } from 'react-i18next';
+import { cx } from '../utils/cx';
+import Button from './Button';
+import './UpdateAlert.css';
+/**
+ * macOS 스타일 우측 상단 고정 알림.
+ *
+ * 여러 장을 동시에 띄우려면 `.update-alert-stack`으로 감싼다 — 낱장은 스스로
+ * fixed로 붙지만 스택 안에서는 흐름 배치가 되어 아래로 쌓인다.
+ *
+ * @public
+ */
+export default function UpdateAlert({ title, message, actionLabel, onAction, icon, onClose, className = '', }) {
+    const { t } = useTranslation();
+    const resolvedActionLabel = actionLabel ?? t('common.update', '업데이트');
+    return (_jsxs("div", { className: cx('update-alert', className), role: "alert", children: [onClose && (_jsx("button", { type: "button", className: "update-alert__close", onClick: onClose, "aria-label": t('common.close', '닫기'), children: "\u00D7" })), _jsxs("div", { className: "update-alert__top", children: [_jsx("div", { className: "update-alert__icon", children: icon ?? _jsx(Download, { size: 20, strokeWidth: 2 }) }), _jsxs("div", { className: "update-alert__body", children: [_jsx("div", { className: "update-alert__title h4", children: title }), _jsx("div", { className: "update-alert__message body-3", children: message })] })] }), onAction && (_jsx(Button, { size: 32, variant: "main", shape: "pill", className: "update-alert__action", onClick: onAction, children: resolvedActionLabel }))] }));
+}

package/dist/packages/core/src/components/Word/ContrastFilterPanel.d.ts

@@ -0,0 +1,25 @@
+import type { ReactNode } from 'react';
+/** @public */
+export interface ContrastFilterPanelProps {
+    /** 패널 제목. 미지정 시 i18n(wordPairs.filter.searchOptionsTitle) 기본값 사용. */
+    title?: ReactNode;
+    /** 대립 방식 — 음소 포함(include) / 음소 대립(pick) / 음소 대립 지정(explicit). */
+    mode: 'include' | 'pick' | 'explicit';
+    onModeChange: (mode: 'include' | 'pick' | 'explicit') => void;
+    /** 입력 음절 위치 — 무관(unordered) / 일치(ordered). */
+    matchMode: 'ordered' | 'unordered';
+    onMatchModeChange: (matchMode: 'ordered' | 'unordered') => void;
+    /** 입력 음절 갯수 — 1 또는 2. */
+    positionCount: number;
+    onPositionCountChange: (count: number) => void;
+    /** 입력 방식 — 글자 입력(word) / 발음 입력(phoneme). */
+    inputMode: 'word' | 'phoneme';
+    onInputModeChange: (mode: 'word' | 'phoneme') => void;
+    className?: string;
+}
+/**
+ * 대립쌍(최소대립쌍) 검색 방식을 고르는 FilterPanel — 대립 방식/입력 음절 위치/입력 음절 갯수/입력 방식,
+ * 4개 모두 단일 선택 세그먼트. WordPairsPage의 [대립 설정] 패널이 원 출처.
+ * @public
+ */
+export default function ContrastFilterPanel({ title, mode, onModeChange, matchMode, onMatchModeChange, positionCount, onPositionCountChange, inputMode, onInputModeChange, className, }: ContrastFilterPanelProps): import("react").JSX.Element;