@ihabdevteam/core 0.125.0 → 0.126.0

package/dist/ihabdevteam-core.d.ts

@@ -1341,7 +1341,7 @@ export declare function copyText(text: string): Promise<boolean>;
  *
  * 값은 손으로 적고 `test/coreVersion.test.ts` 가 package.json 과 어긋나면 운다.
  */
-export declare const CORE_VERSION = "0.125.0";
+export declare const CORE_VERSION = "0.126.0";
 
 /** @public */
 declare const coreDefault: Record<string, unknown>;
@@ -2223,11 +2223,15 @@ export declare function getDailySelection(): {
 };
 
 /**
- * 엘리먼트에 연결된 AnalyserNode를 반환(없으면 생성·캐싱).
- * 실패 시 null(미지원/이미 다른 그래프에 소스됨 등).
+ * 엘리먼트에 연결된 AnalyserNode 를 반환(달리는 컨텍스트면 지금 태워서).
+ * 컨텍스트가 suspended 면 **지금은 null** 을 주고 resume 뒤 태우기를 걸어 둔다 — 나중 값이 필요하면
+ * `routeElementAudio` 를 기다린다. 실패 시 null(미지원/이미 다른 그래프에 소스됨 등).
  */
 export declare function getElementAnalyser(el: HTMLMediaElement | null | undefined): AnalyserNode | null;
 
+/** @public 요소에 걸려고 한 볼륨(0~1) — 램프 출발점. 건 적이 없으면 요소 volume. */
+export declare function getElementVolume(el: HTMLMediaElement): number;
+
 /**
  * 잡은 값에서 **사람이 읽을 수 있는 원인**을 꺼낸다.
  *
@@ -4654,14 +4658,20 @@ export declare function resolveTrainingPopupMeta(trainingData: Record<string, un
 };
 
 /**
- * 오디오 레벨 미터용 Web Audio 유틸.
+ * 오디오 레벨 미터 + 볼륨용 Web Audio 유틸.
  *
- * HTMLMediaElement를 AnalyserNode에 연결해 실시간 레벨(RMS)을 읽을 수 있게 한다.
- * - createMediaElementSource는 엘리먼트당 1회만 가능 → WeakMap으로 캐싱.
- * - 분석을 위해 라우팅하면 destination 연결이 끊기면 무음이 되므로,
- *   source를 analyser와 destination 양쪽에 연결한다.
- * - cross-origin 소스는 엘리먼트에 crossOrigin="anonymous"가 설정되고
- *   서버가 CORS를 허용해야 분석이 가능하다(아니면 0으로 읽힘, 재생은 정상).
+ * HTMLMediaElement 를 한 그래프에 태운다: `source → GainNode → (AnalyserNode, destination)`.
+ * - createMediaElementSource 는 엘리먼트당 1회만 가능 → WeakMap 으로 캐싱.
+ * - **볼륨은 GainNode 로 건다**(0.126.0). 실제 iPhone·iPad 에서는 `HTMLMediaElement.volume` 을
+ *   스크립트로 바꿔도 소리에 안 먹는다(Apple 문서 — 늘 1). 그래프에 태운 요소는 volume 을 1 로
+ *   두고 `gain` 으로 크기를 정하므로 기기와 상관없이 먹는다. 미터(analyser)는 gain 뒤라 들리는
+ *   크기를 읽는다(요소 volume 이 소스 출력에 걸리던 전과 같은 결).
+ * - **달리는(running) AudioContext 에만 태운다.** 태운 순간부터 요소 소리는 destination 연결로만
+ *   나가므로, suspended(자동재생 정책) 컨텍스트에 태우면 resume 전까지 무음이다. 그래서 suspended
+ *   이면 resume 이 끝난 뒤에 태우고, 그 전에는 요소가 제 볼륨으로 직접 울린다.
+ * - Web Audio 가 없거나 태우기에 실패하면(미지원·이미 다른 그래프에 소스됨 등) 요소 volume 으로 물러선다.
+ * - cross-origin 소스는 엘리먼트에 crossOrigin="anonymous" 가 있고 서버가 CORS 를 허용해야 그래프
+ *   출력이 무음이 되지 않는다(코어의 문장·소음 요소는 둘 다 붙인다).
  */
 /** 미터 AudioContext를 사용자 제스처 이후 resume(자동재생 정책 대응). */
 export declare function resumeAudioMeter(): void;
@@ -4794,6 +4804,14 @@ export declare interface RingChartSegment {
 /** 시맨틱 사이즈 → 지름(px)·링 두께(px) 프리셋 */
 export declare type RingChartSize = 'small' | 'medium' | 'large';
 
+/**
+ * 엘리먼트를 그래프에 태우고 AnalyserNode 를 준다(이미 태웠으면 그것).
+ * 컨텍스트가 suspended 면 resume 을 기다린 뒤 태운다 — resume 이 안 되면(제스처 없음) null 이고
+ * 요소는 제 볼륨으로 계속 울린다. Web Audio 미지원·실패도 null.
+ * @public
+ */
+export declare function routeElementAudio(el: HTMLMediaElement | null | undefined): Promise<AnalyserNode | null>;
+
 /**
  * @public 배열에서 무작위로 최대 n개를 뽑아 새 배열로 반환(원본 불변).
  * n이 길이 이상이면 전체를 셔플해 반환한다.
@@ -5097,6 +5115,13 @@ export declare function setAssetBaseUrl(baseUrl?: string | null): void;
 /** @public */
 export declare function setCrosswordLogger(fn: CrosswordLogger | null): void;
 
+/**
+ * @public 요소 볼륨(0~1)을 건다. 그래프에 태운 요소면 요소 volume 은 1 로 두고 GainNode 에
+ * (짧은 시정수로 매끄럽게) 걸고 'gain', 아니면 요소 volume 에 걸고 'element'. 부르는 쪽이 매 프레임
+ * 불러 램프를 만들어도 된다.
+ */
+export declare function setElementVolume(el: HTMLMediaElement, volume: number): 'gain' | 'element';
+
 /** @public */
 export declare function setGameLeaderboardLoader(fn: LeaderboardFn): void;
 

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

@@ -1,8 +1,8 @@
 'use client';
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { cx } from '../utils/cx';
-import { useEffect, useRef } from 'react';
-import { getElementAnalyser, resumeAudioMeter, readLevel } from '../utils/audioMeter';
+import { useEffect, useRef, useState } from 'react';
+import { getElementAnalyser, resumeAudioMeter, readLevel, routeElementAudio } from '../utils/audioMeter';
 import './AudioMeter.css';
 // 레벨 표시 평활화(빠른 어택 / 느린 릴리스)
 const RELEASE = 0.86;
@@ -27,14 +27,22 @@ export default function AudioMeter({ analyser, audioElement, orientation = 'hori
     const fillRef = useRef(null);
     const valueRef = useRef(null);
     const rafRef = useRef(null);
+    /* 컨텍스트가 아직 suspended 면 getElementAnalyser 는 지금 null 을 준다(달리는 컨텍스트에만 태운다 —
+       audioMeter 머리말). resume 뒤 태워지면 그 노드로 다시 돈다. */
+    const [routed, setRouted] = useState(null);
     useEffect(() => {
-        const node = analyser ?? getElementAnalyser(audioElement);
+        const node = analyser ?? getElementAnalyser(audioElement) ?? (routed && routed.el === audioElement ? routed.node : null);
         const fill = fillRef.current;
         if (!node || !fill) {
             fill?.style.setProperty('--meter-level', '0');
             if (valueRef.current)
                 valueRef.current.textContent = formatRelDb(floorDb, refDb, displayMin, displayMax);
-            return;
+            let cancelled = false;
+            if (!analyser && audioElement) {
+                void routeElementAudio(audioElement).then((n) => { if (!cancelled && n)
+                    setRouted({ el: audioElement, node: n }); });
+            }
+            return () => { cancelled = true; };
         }
         resumeAudioMeter();
         const buffer = new Float32Array(node.fftSize);
@@ -78,7 +86,7 @@ export default function AudioMeter({ analyser, audioElement, orientation = 'hori
                 cancelAnimationFrame(rafRef.current);
             rafRef.current = null;
         };
-    }, [analyser, audioElement, floorDb, refDb, displayMin, displayMax]);
+    }, [analyser, audioElement, routed, floorDb, refDb, displayMin, displayMax]);
     const lengthCss = typeof length === 'number' ? `${length}px` : length;
     const isVertical = orientation === 'vertical';
     const trackStyle = lengthCss

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

@@ -6,7 +6,7 @@ import { useTranslation } from "react-i18next";
 // TrainingItem, TrainingGroup import 제거됨 (resolveMapping 제거로 불필요)
 import { downloadSound, getSignedOrPublicUrl, resolveSoundPath } from '../../utils/storage';
 import { getTTSUrlResolver } from '../../utils/ttsConfig';
-import { getElementAnalyser, resumeAudioMeter } from '../../utils/audioMeter';
+import { resumeAudioMeter, routeElementAudio, setElementVolume, getElementVolume } from '../../utils/audioMeter';
 import { useNoisePlayer, effectiveNoiseVolume, effectiveSpeechVolume, noiseRatioOf } from './NoisePlayerContext';
 import { useNoiseFade } from './useNoiseFade';
 import { useTTSPlayback } from './useTTSPlayback';
@@ -204,10 +204,14 @@ export default function TrainingStepAudioPlayer({ btnLabel, soundSrc, bucketPath
             setStateLocal("playMode");
             set구간표시(true);
             startTicker();
-            // 미터: 재생 제스처 시점에 context resume 후 메인 analyser 등록(무음 방지)
+            // 문장을 Web Audio 그래프(gain·미터)에 태운다 — 재생 제스처 시점에 resume, 컨텍스트가 달리고 나서야
+            // 태우므로 그 전엔 요소가 제 볼륨으로 직접 울린다(무음 방지). 태운 뒤 볼륨은 GainNode 로 걸린다.
             try {
                 resumeAudioMeter();
-                registerAnalyserRef.current?.('main', getElementAnalyser(a));
+                void routeElementAudio(a).then((an) => { try {
+                    registerAnalyserRef.current?.('main', an);
+                }
+                catch (e) { } });
             }
             catch (e) { }
             // 소음 동기 시작
@@ -950,7 +954,8 @@ export default function TrainingStepAudioPlayer({ btnLabel, soundSrc, bucketPath
         }
         catch (e) { }
     }, [playbackRate]);
-    // 문장(메인) 볼륨 반영 — 문제 소리 볼륨(effectiveSpeechVolume = 전체 소리). 재생 중이면 소음과 같은 150ms 램프로 옮기고, 멈춰 있으면 바로 건다.
+    // 문장(메인) 볼륨 반영 — 문제 소리 볼륨(effectiveSpeechVolume = 전체 소리). setElementVolume 이 그래프에 태운
+    // 요소면 GainNode, 아니면 요소 volume 에 건다(iOS 실기기는 요소 volume 이 안 먹는다). 재생 중이면 소음과 같은 150ms 램프로 옮기고, 멈춰 있으면 바로 건다.
     // 백그라운드 탭에서는 RAF 가 멈춰 램프가 중간에 설 수 있으므로 끝값을 타이머로 한 번 더 박는다.
     const speechRampRef = useRef({ raf: null, timer: null });
     useEffect(() => {
@@ -970,10 +975,10 @@ export default function TrainingStepAudioPlayer({ btnLabel, soundSrc, bucketPath
             }
         };
         끊기();
-        const from = a.volume;
+        const from = getElementVolume(a);
         if (a.paused || Math.abs(from - target) < 0.001 || typeof requestAnimationFrame !== 'function') {
             try {
-                a.volume = target;
+                setElementVolume(a, target);
             }
             catch (e) { }
             return;
@@ -982,14 +987,14 @@ export default function TrainingStepAudioPlayer({ btnLabel, soundSrc, bucketPath
         const step = () => {
             const t = Math.min(1, (performance.now() - start) / 150);
             try {
-                a.volume = from + (target - from) * t;
+                setElementVolume(a, from + (target - from) * t);
             }
             catch (e) { }
             ramp.raf = t < 1 ? requestAnimationFrame(step) : null;
         };
         ramp.raf = requestAnimationFrame(step);
         ramp.timer = setTimeout(() => { 끊기(); try {
-            a.volume = target;
+            setElementVolume(a, target);
         }
         catch (e) { } }, 200);
         return 끊기;

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

@@ -1,7 +1,7 @@
 'use client';
 import { useCallback, useEffect, useRef, useState } from 'react';
 import { noiseAssets } from '../../sounds/noiseAssets';
-import { getElementAnalyser, resumeAudioMeter } from '../../utils/audioMeter';
+import { resumeAudioMeter, routeElementAudio, setElementVolume, getElementVolume } from '../../utils/audioMeter';
 import { noiseElementVolume } from './NoisePlayerContext';
 function generateNoiseUrl(type) {
     const rand = Math.floor(Math.random() * 10);
@@ -47,24 +47,28 @@ export function useNoiseFade({ noisePlayer, audioRef, playbackStateRef, }) {
             return;
         noiseFadeTokenRef.current += 1;
         cancelNoiseFade();
-        // 미터: 소음 재생 시점에 context resume 후 소음 analyser 등록
+        // 소음을 Web Audio 그래프(gain·미터)에 태운다 — 컨텍스트가 달리고 나서야 태우므로 그 전엔 요소가 직접 울린다.
+        // 볼륨은 setElementVolume 이 그래프면 GainNode, 아니면 요소 volume 에 건다(iOS 실기기는 요소 volume 이 안 먹는다).
         try {
             resumeAudioMeter();
-            registerAnalyserRef.current?.('noise', getElementAnalyser(noiseEl));
+            void routeElementAudio(noiseEl).then((an) => { try {
+                registerAnalyserRef.current?.('noise', an);
+            }
+            catch (e) { } });
         }
         catch (e) { }
         // 이미 재생 중이면(멀티소스 연달아 재생 — 단어1→단어2 전환마다 onPlay가 다시 호출됨)
         // 볼륨을 0으로 리셋하지 않고 현재 볼륨에서 목표까지 부드럽게 이어간다 — 트랙 전환 때마다
         // 소음이 뚝 끊겼다 다시 차오르던 문제 방지. 이미 목표 볼륨이면 램프가 사실상 no-op이다.
-        const startVol = noiseEl.paused ? 0 : noiseEl.volume;
+        const startVol = noiseEl.paused ? 0 : getElementVolume(noiseEl);
         if (noiseEl.paused)
-            noiseEl.volume = 0;
+            setElementVolume(noiseEl, 0);
         noiseEl.play().catch(() => { });
         const startTime = performance.now();
         const step = () => {
             const t = Math.min(1, (performance.now() - startTime) / durationMs);
             try {
-                noiseEl.volume = Math.max(0, Math.min(1, startVol + (targetVolume - startVol) * t));
+                setElementVolume(noiseEl, startVol + (targetVolume - startVol) * t);
             }
             catch (e) { }
             if (t < 1) {
@@ -85,11 +89,11 @@ export function useNoiseFade({ noisePlayer, audioRef, playbackStateRef, }) {
         const token = ++noiseFadeTokenRef.current;
         cancelNoiseFade();
         const startTime = performance.now();
-        const startVol = noiseEl.volume;
+        const startVol = getElementVolume(noiseEl);
         const step = () => {
             const t = Math.min(1, (performance.now() - startTime) / durationMs);
             try {
-                noiseEl.volume = Math.max(0, startVol * (1 - t));
+                setElementVolume(noiseEl, startVol * (1 - t));
             }
             catch (e) { }
             if (t < 1) {
@@ -123,7 +127,7 @@ export function useNoiseFade({ noisePlayer, audioRef, playbackStateRef, }) {
             }
             try {
                 if (!noiseEl.paused) {
-                    noiseEl.volume = 0;
+                    setElementVolume(noiseEl, 0);
                     noiseEl.pause();
                     onComplete?.();
                 }
@@ -267,12 +271,12 @@ export function useNoiseFade({ noisePlayer, audioRef, playbackStateRef, }) {
                 else {
                     // 이미 재생 중 — 볼륨만 부드럽게 조절
                     cancelNoiseFade();
-                    const startVol = noiseEl.volume;
+                    const startVol = getElementVolume(noiseEl);
                     const startTime = performance.now();
                     const ramp = () => {
                         const t = Math.min(1, (performance.now() - startTime) / 150);
                         try {
-                            noiseEl.volume = startVol + (volume - startVol) * t;
+                            setElementVolume(noiseEl, startVol + (volume - startVol) * t);
                         }
                         catch (e) { }
                         if (t < 1)

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

@@ -1,19 +1,41 @@
 /**
- * 오디오 레벨 미터용 Web Audio 유틸.
+ * 오디오 레벨 미터 + 볼륨용 Web Audio 유틸.
  *
- * HTMLMediaElement를 AnalyserNode에 연결해 실시간 레벨(RMS)을 읽을 수 있게 한다.
- * - createMediaElementSource는 엘리먼트당 1회만 가능 → WeakMap으로 캐싱.
- * - 분석을 위해 라우팅하면 destination 연결이 끊기면 무음이 되므로,
- *   source를 analyser와 destination 양쪽에 연결한다.
- * - cross-origin 소스는 엘리먼트에 crossOrigin="anonymous"가 설정되고
- *   서버가 CORS를 허용해야 분석이 가능하다(아니면 0으로 읽힘, 재생은 정상).
+ * HTMLMediaElement 를 한 그래프에 태운다: `source → GainNode → (AnalyserNode, destination)`.
+ * - createMediaElementSource 는 엘리먼트당 1회만 가능 → WeakMap 으로 캐싱.
+ * - **볼륨은 GainNode 로 건다**(0.126.0). 실제 iPhone·iPad 에서는 `HTMLMediaElement.volume` 을
+ *   스크립트로 바꿔도 소리에 안 먹는다(Apple 문서 — 늘 1). 그래프에 태운 요소는 volume 을 1 로
+ *   두고 `gain` 으로 크기를 정하므로 기기와 상관없이 먹는다. 미터(analyser)는 gain 뒤라 들리는
+ *   크기를 읽는다(요소 volume 이 소스 출력에 걸리던 전과 같은 결).
+ * - **달리는(running) AudioContext 에만 태운다.** 태운 순간부터 요소 소리는 destination 연결로만
+ *   나가므로, suspended(자동재생 정책) 컨텍스트에 태우면 resume 전까지 무음이다. 그래서 suspended
+ *   이면 resume 이 끝난 뒤에 태우고, 그 전에는 요소가 제 볼륨으로 직접 울린다.
+ * - Web Audio 가 없거나 태우기에 실패하면(미지원·이미 다른 그래프에 소스됨 등) 요소 volume 으로 물러선다.
+ * - cross-origin 소스는 엘리먼트에 crossOrigin="anonymous" 가 있고 서버가 CORS 를 허용해야 그래프
+ *   출력이 무음이 되지 않는다(코어의 문장·소음 요소는 둘 다 붙인다).
  */
 /** 미터 AudioContext를 사용자 제스처 이후 resume(자동재생 정책 대응). */
 export declare function resumeAudioMeter(): void;
 /**
- * 엘리먼트에 연결된 AnalyserNode를 반환(없으면 생성·캐싱).
- * 실패 시 null(미지원/이미 다른 그래프에 소스됨 등).
+ * 엘리먼트를 그래프에 태우고 AnalyserNode 를 준다(이미 태웠으면 그것).
+ * 컨텍스트가 suspended 면 resume 을 기다린 뒤 태운다 — resume 이 안 되면(제스처 없음) null 이고
+ * 요소는 제 볼륨으로 계속 울린다. Web Audio 미지원·실패도 null.
+ * @public
+ */
+export declare function routeElementAudio(el: HTMLMediaElement | null | undefined): Promise<AnalyserNode | null>;
+/**
+ * 엘리먼트에 연결된 AnalyserNode 를 반환(달리는 컨텍스트면 지금 태워서).
+ * 컨텍스트가 suspended 면 **지금은 null** 을 주고 resume 뒤 태우기를 걸어 둔다 — 나중 값이 필요하면
+ * `routeElementAudio` 를 기다린다. 실패 시 null(미지원/이미 다른 그래프에 소스됨 등).
  */
 export declare function getElementAnalyser(el: HTMLMediaElement | null | undefined): AnalyserNode | null;
+/**
+ * @public 요소 볼륨(0~1)을 건다. 그래프에 태운 요소면 요소 volume 은 1 로 두고 GainNode 에
+ * (짧은 시정수로 매끄럽게) 걸고 'gain', 아니면 요소 volume 에 걸고 'element'. 부르는 쪽이 매 프레임
+ * 불러 램프를 만들어도 된다.
+ */
+export declare function setElementVolume(el: HTMLMediaElement, volume: number): 'gain' | 'element';
+/** @public 요소에 걸려고 한 볼륨(0~1) — 램프 출발점. 건 적이 없으면 요소 volume. */
+export declare function getElementVolume(el: HTMLMediaElement): number;
 /** AnalyserNode의 현재 레벨(RMS, 0~1). */
 export declare function readLevel(analyser: AnalyserNode, buffer: Float32Array<ArrayBuffer>): number;

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

@@ -1,15 +1,40 @@
 /**
- * 오디오 레벨 미터용 Web Audio 유틸.
+ * 오디오 레벨 미터 + 볼륨용 Web Audio 유틸.
  *
- * HTMLMediaElement를 AnalyserNode에 연결해 실시간 레벨(RMS)을 읽을 수 있게 한다.
- * - createMediaElementSource는 엘리먼트당 1회만 가능 → WeakMap으로 캐싱.
- * - 분석을 위해 라우팅하면 destination 연결이 끊기면 무음이 되므로,
- *   source를 analyser와 destination 양쪽에 연결한다.
- * - cross-origin 소스는 엘리먼트에 crossOrigin="anonymous"가 설정되고
- *   서버가 CORS를 허용해야 분석이 가능하다(아니면 0으로 읽힘, 재생은 정상).
+ * HTMLMediaElement 를 한 그래프에 태운다: `source → GainNode → (AnalyserNode, destination)`.
+ * - createMediaElementSource 는 엘리먼트당 1회만 가능 → WeakMap 으로 캐싱.
+ * - **볼륨은 GainNode 로 건다**(0.126.0). 실제 iPhone·iPad 에서는 `HTMLMediaElement.volume` 을
+ *   스크립트로 바꿔도 소리에 안 먹는다(Apple 문서 — 늘 1). 그래프에 태운 요소는 volume 을 1 로
+ *   두고 `gain` 으로 크기를 정하므로 기기와 상관없이 먹는다. 미터(analyser)는 gain 뒤라 들리는
+ *   크기를 읽는다(요소 volume 이 소스 출력에 걸리던 전과 같은 결).
+ * - **달리는(running) AudioContext 에만 태운다.** 태운 순간부터 요소 소리는 destination 연결로만
+ *   나가므로, suspended(자동재생 정책) 컨텍스트에 태우면 resume 전까지 무음이다. 그래서 suspended
+ *   이면 resume 이 끝난 뒤에 태우고, 그 전에는 요소가 제 볼륨으로 직접 울린다.
+ * - Web Audio 가 없거나 태우기에 실패하면(미지원·이미 다른 그래프에 소스됨 등) 요소 volume 으로 물러선다.
+ * - cross-origin 소스는 엘리먼트에 crossOrigin="anonymous" 가 있고 서버가 CORS 를 허용해야 그래프
+ *   출력이 무음이 되지 않는다(코어의 문장·소음 요소는 둘 다 붙인다).
  */
 let _ctx = null;
-const _analysers = new WeakMap();
+const _graphs = new WeakMap();
+/** 요소에 걸려고 한 볼륨(0~1) — 그래프에 태울 때 gain 초깃값, 읽을 때 기준값 */
+const _desired = new WeakMap();
+const _pending = new WeakMap();
+let _unlockInstalled = false;
+const 자르기 = (v) => Math.max(0, Math.min(1, Number.isFinite(v) ? v : 0));
+/** 첫 사용자 제스처(및 이후 제스처)마다 멈춘 컨텍스트를 깨운다 — iOS 는 제스처 안에서만 resume 이 먹는다 */
+function installGestureUnlock() {
+    if (_unlockInstalled || typeof document === 'undefined')
+        return;
+    _unlockInstalled = true;
+    const 깨우기 = () => { try {
+        if (_ctx && _ctx.state !== 'running')
+            void _ctx.resume();
+    }
+    catch { /* noop */ } };
+    for (const type of ['pointerdown', 'touchend', 'keydown']) {
+        document.addEventListener(type, 깨우기, { capture: true, passive: true });
+    }
+}
 function getContext() {
     if (_ctx)
         return _ctx;
@@ -18,6 +43,7 @@ function getContext() {
         if (!Ctor)
             return null;
         _ctx = new Ctor();
+        installGestureUnlock();
         return _ctx;
     }
     catch {
@@ -31,33 +57,119 @@ export function resumeAudioMeter() {
     }
     catch { /* noop */ }
 }
-/**
- * 엘리먼트에 연결된 AnalyserNode를 반환(없으면 생성·캐싱).
- * 실패 시 null(미지원/이미 다른 그래프에 소스됨 등).
- */
-export function getElementAnalyser(el) {
-    if (!el)
-        return null;
-    const cached = _analysers.get(el);
+function build(ctx, el) {
+    const cached = _graphs.get(el);
     if (cached)
         return cached;
-    const ctx = getContext();
-    if (!ctx)
-        return null;
     try {
         const source = ctx.createMediaElementSource(el);
+        const gain = ctx.createGain();
         const analyser = ctx.createAnalyser();
         analyser.fftSize = 1024;
         analyser.smoothingTimeConstant = 0.6;
-        source.connect(analyser);
-        source.connect(ctx.destination);
-        _analysers.set(el, analyser);
-        return analyser;
+        // 태우기 직전의 요소 볼륨을 gain 으로 옮기고 요소는 1 로 — 순서가 바뀌면 한 순간 두 번 곱해진다
+        gain.gain.value = 자르기(_desired.get(el) ?? el.volume);
+        source.connect(gain);
+        gain.connect(analyser);
+        gain.connect(ctx.destination);
+        try {
+            el.volume = 1;
+        }
+        catch { /* noop */ }
+        const graph = { gain, analyser };
+        _graphs.set(el, graph);
+        return graph;
     }
     catch {
         return null;
     }
 }
+/**
+ * 엘리먼트를 그래프에 태우고 AnalyserNode 를 준다(이미 태웠으면 그것).
+ * 컨텍스트가 suspended 면 resume 을 기다린 뒤 태운다 — resume 이 안 되면(제스처 없음) null 이고
+ * 요소는 제 볼륨으로 계속 울린다. Web Audio 미지원·실패도 null.
+ * @public
+ */
+export function routeElementAudio(el) {
+    if (!el)
+        return Promise.resolve(null);
+    const cached = _graphs.get(el);
+    if (cached)
+        return Promise.resolve(cached.analyser);
+    const ctx = getContext();
+    if (!ctx)
+        return Promise.resolve(null);
+    if (ctx.state === 'running')
+        return Promise.resolve(build(ctx, el)?.analyser ?? null);
+    const pending = _pending.get(el);
+    if (pending)
+        return pending;
+    const p = Promise.resolve()
+        .then(() => ctx.resume())
+        .then(() => (ctx.state === 'running' ? build(ctx, el)?.analyser ?? null : null))
+        .catch(() => null)
+        .finally(() => { _pending.delete(el); });
+    _pending.set(el, p);
+    return p;
+}
+/**
+ * 엘리먼트에 연결된 AnalyserNode 를 반환(달리는 컨텍스트면 지금 태워서).
+ * 컨텍스트가 suspended 면 **지금은 null** 을 주고 resume 뒤 태우기를 걸어 둔다 — 나중 값이 필요하면
+ * `routeElementAudio` 를 기다린다. 실패 시 null(미지원/이미 다른 그래프에 소스됨 등).
+ */
+export function getElementAnalyser(el) {
+    if (!el)
+        return null;
+    const cached = _graphs.get(el);
+    if (cached)
+        return cached.analyser;
+    const ctx = getContext();
+    if (!ctx)
+        return null;
+    if (ctx.state === 'running')
+        return build(ctx, el)?.analyser ?? null;
+    void routeElementAudio(el);
+    return null;
+}
+/**
+ * @public 요소 볼륨(0~1)을 건다. 그래프에 태운 요소면 요소 volume 은 1 로 두고 GainNode 에
+ * (짧은 시정수로 매끄럽게) 걸고 'gain', 아니면 요소 volume 에 걸고 'element'. 부르는 쪽이 매 프레임
+ * 불러 램프를 만들어도 된다.
+ */
+export function setElementVolume(el, volume) {
+    const v = 자르기(volume);
+    _desired.set(el, v);
+    const graph = _graphs.get(el);
+    if (graph) {
+        try {
+            if (el.volume !== 1)
+                el.volume = 1;
+        }
+        catch { /* noop */ }
+        const param = graph.gain.gain;
+        try {
+            const now = graph.gain.context.currentTime;
+            param.cancelScheduledValues(now);
+            param.setTargetAtTime(v, now, 0.01);
+        }
+        catch {
+            try {
+                param.value = v;
+            }
+            catch { /* noop */ }
+        }
+        return 'gain';
+    }
+    try {
+        el.volume = v;
+    }
+    catch { /* noop */ }
+    return 'element';
+}
+/** @public 요소에 걸려고 한 볼륨(0~1) — 램프 출발점. 건 적이 없으면 요소 volume. */
+export function getElementVolume(el) {
+    return _desired.get(el) ?? el.volume;
+}
 /** AnalyserNode의 현재 레벨(RMS, 0~1). */
 export function readLevel(analyser, buffer) {
     analyser.getFloatTimeDomainData(buffer);

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

@@ -4,7 +4,7 @@ export { configureStorage, downloadSound, fileExists, getSignedOrPublicUrl, reso
 export type { StorageResolvers } from './utils/storage';
 export { configureTTS, getTTSUrlResolver, getTTSFallbackUrlResolver, clearAudioExistsCache } from './utils/ttsConfig';
 export { configurePronunciationResolver, getPronunciationResolver } from './utils/pronunciationConfig';
-export { getElementAnalyser, resumeAudioMeter, readLevel } from './utils/audioMeter';
+export { getElementAnalyser, resumeAudioMeter, readLevel, routeElementAudio, setElementVolume, getElementVolume } from './utils/audioMeter';
 export { configureImageResolver, getImageResolver, checkImageExists, getImageExistsCached, prewarmImageCache, bulkSetImageExistence, clearImageExistenceCache, getImageExistenceStats } from './utils/imageConfig';
 export { buildPairIndex, getPairIndex, clearPairIndexCache } from './utils/wordPairIndex';
 export type { PairIndex, PairIndexEntry, PairInput } from './utils/wordPairIndex';

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

@@ -3,7 +3,7 @@ export { getAssetBaseUrl, resolveAssetUrl, setAssetBaseUrl } from './utils/asset
 export { configureStorage, downloadSound, fileExists, getSignedOrPublicUrl, resolveSoundPath, getNoiseBaseUrl, getNoiseFileGain } from './utils/storage';
 export { configureTTS, getTTSUrlResolver, getTTSFallbackUrlResolver, clearAudioExistsCache } from './utils/ttsConfig';
 export { configurePronunciationResolver, getPronunciationResolver } from './utils/pronunciationConfig';
-export { getElementAnalyser, resumeAudioMeter, readLevel } from './utils/audioMeter';
+export { getElementAnalyser, resumeAudioMeter, readLevel, routeElementAudio, setElementVolume, getElementVolume } from './utils/audioMeter';
 export { configureImageResolver, getImageResolver, checkImageExists, getImageExistsCached, prewarmImageCache, bulkSetImageExistence, clearImageExistenceCache, getImageExistenceStats } from './utils/imageConfig';
 export { buildPairIndex, getPairIndex, clearPairIndexCache } from './utils/wordPairIndex';
 export { minimalPairDistractors, filterContrastCandidates, hasStructureContrast, buildMultiPartPosContrast, hasSel } from './utils/wordContrast';

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

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

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

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