@ihabdevteam/core 0.8.0

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

@@ -0,0 +1,125 @@
+/**
+ * 재생 중에 내리는 **판단**들 — 화면도 오디오도 건드리지 않는 순수 계산.
+ *
+ * 원래 `attachAudioListeners` 안에 `try { } catch (e) {}` 로 겹겹이 싸인 채 들어 있었다.
+ * 거기서는 시험을 쓸 방법이 없다 — 진짜 `<audio>` 와 진짜 이벤트가 있어야 도달하고,
+ * 게다가 무엇이 틀려도 catch 가 삼켜서 **틀린 채로 조용히 지나간다.**
+ *
+ * 판단만 떼어 내면 표로 확인할 수 있다. 나머지(이벤트 붙이기, DOM 스타일 쓰기)는
+ * 원래 자리에 그대로 둔다 — 그쪽은 옮겨도 나아지는 것이 없다.
+ */
+/**
+ * 지금 트랙에서 얼마나 왔는가 — 0~1.
+ *
+ * **여러 소리를 이어 붙인 훈련**에서는 `<audio>` 의 duration 이 아니라 **그 트랙의
+ * 길이**로 재야 한다. 이어 붙인 것을 통짜로 재면 두 번째 트랙이 늘 절반 뒤에서
+ * 시작하는 것처럼 보인다.
+ *
+ * 길이를 모르면(0이거나 아직 메타데이터 전) 0을 준다 — 모르는 것을 100%로 그리면
+ * 마커가 끝에 붙어 있다가 튄다.
+ */
+export function progressOf({ currentTime, sources, index, audioDuration, }) {
+    /* `index || 0` 은 원본에서 옮겨 온 그대로다 — 아직 번호를 못 정한 상태(undefined·NaN)를
+       0번으로 본다는 뜻이다. 음수는 그대로 통과하지만 그러면 `sources[음수]` 가 없어서
+       아래 else 쪽으로 떨어진다. 부르는 쪽이 음수를 줄 일은 없다. */
+    const 지금 = index || 0;
+    const 이번트랙 = Array.isArray(sources) && sources.length > 0 ? sources[지금] : undefined;
+    const 길이 = 이번트랙
+        ? (이번트랙.duration || audioDuration || 0)
+        : (audioDuration || 0);
+    if (!(길이 > 0))
+        return 0;
+    const t = Number.isFinite(currentTime) ? currentTime : 0;
+    return Math.max(0, Math.min(1, t / 길이));
+}
+/**
+ * 한 트랙이 끝났다 — 이어서 틀 것이 있는가.
+ *
+ * `null` 이면 훈련의 한 문항이 끝난 것이고, 숫자면 다음 트랙으로 넘어간다.
+ * 목록이 없거나 마지막이면 `null`.
+ */
+export function nextTrackIndex(sources, index) {
+    if (!Array.isArray(sources))
+        return null;
+    const 지금 = index || 0; // progressOf 와 같은 규칙 — 원본에서 옮겨 왔다
+    return 지금 < sources.length - 1 ? 지금 + 1 : null;
+}
+/**
+ * `pause` 이벤트를 흘려보내야 하는가.
+ *
+ * 두 경우는 **사용자가 멈춘 것이 아니다.**
+ *
+ *  1. 소리가 자연히 끝났을 때 — 브라우저는 `ended` **직전에 `pause` 를 먼저 낸다.**
+ *  2. 끝 처리(handleEnd)가 스스로 `pause()` 를 부른 뒤.
+ *
+ * 이걸 안 거르면 화면이 '일시정지'로 잠깐 바뀌었다가 '정지'로 다시 바뀐다 —
+ * 문항이 끝날 때마다 단추가 한 번씩 깜빡인다.
+ */
+export function shouldIgnorePause({ ended, completedByEnd, }) {
+    return !!ended || !!completedByEnd;
+}
+/**
+ * 소스 목록을 화면이 쓸 **구간(segment)** 목록으로 바꾼다.
+ *
+ * 구간은 파형 아래에 번호 단추로 그려진다 — 여러 소리를 이어 붙인 훈련에서 "2번으로
+ * 건너뛰기"를 할 수 있게 하는 것.
+ *
+ * 세 갈래(단일 TTS·복수 TTS·저장소 소스)가 각자 이 변환을 한 벌씩 들고 있었고,
+ * 그중 하나는 미묘하게 달랐다 — 길이를 `duration: dur` 로 그냥 넘겨 **길이를 모를 때
+ * `undefined` 가 흘러 들어갔다**(나머지 둘은 `|| 0`). 한 벌로 모으면서 0으로 맞춘다.
+ * 길이를 모르는 것과 0인 것은 여기서 같은 뜻이다 — 어차피 그릴 폭이 없다.
+ */
+export function buildSegments(sources) {
+    return sources.map((f, i) => ({
+        src: f.src,
+        label: String(i + 1),
+        color: undefined,
+        duration: f.duration || 0,
+    }));
+}
+/** 소스들의 길이를 다 더한다 — 모르는 것은 0으로 친다 */
+export function totalDurationOf(sources) {
+    return sources.reduce((acc, f) => acc + (f.duration || 0), 0);
+}
+/**
+ * 넘어온 소리 지정을 **한 가지 모양으로** 편다.
+ *
+ * 부르는 쪽이 세 가지로 준다 — 이미 주소를 아는 객체, 주소나 경로처럼 생긴 문자열,
+ * 그리고 그냥 **코드**(예: `QQ01`). 코드는 저장소 규칙을 거쳐야 경로가 되므로
+ * `resolvePath` 를 통과시킨다.
+ *
+ * 두 가지를 조용히 버린다 — 빈 값과, 경로를 못 정한 코드다. 버린 것을 오류로 올리지
+ * 않는 이유는 **한 소리가 없다고 훈련 전체를 못 하게 만들 수는 없어서**다. 대신 몇 개를
+ * 버렸는지는 부르는 쪽이 길이를 비교하면 알 수 있다.
+ *
+ * 원래 `fetchAndPrepare` 안의 40줄짜리 for 문이었다. 거기서는 시험을 쓸 수 없었다 —
+ * 이 판단에 닿으려면 네트워크와 오디오 요소가 먼저 필요했다.
+ */
+export function normalizeSources(soundSrc, bucketPath, resolvePath) {
+    const candidates = Array.isArray(soundSrc) ? soundSrc : (soundSrc ? [soundSrc] : []);
+    const out = [];
+    for (const c of candidates) {
+        if (!c)
+            continue;
+        // (가) 주소를 이미 들고 있는 객체
+        if (typeof c === 'object' && c !== null && 'src' in c && c.src) {
+            const o = c;
+            out.push({ code: o.code ?? null, src: o.src });
+            continue;
+        }
+        // (나) 주소이거나 경로처럼 생긴 문자열 — 'https://…' 또는 'LIN_D/QQ01.mp3'
+        if (typeof c === 'string' && (c.startsWith('http') || c.includes('/'))) {
+            out.push({ code: null, src: c });
+            continue;
+        }
+        // (다) 그냥 코드 — 저장소 규칙으로 경로를 정한다
+        if (typeof c === 'string' || typeof c === 'number') {
+            const codeStr = String(c);
+            const resolvedPath = resolvePath(codeStr, bucketPath);
+            // 경로를 못 정하면 버린다 — 여기서 만들 수 있는 것이 없다
+            if (resolvedPath)
+                out.push({ code: codeStr, resolvedPath });
+        }
+    }
+    return out;
+}

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

@@ -0,0 +1,27 @@
+/**
+ * 오디오를 **기다리는 두 가지** — 길이를 재는 일과, 들을 준비가 되기를 기다리는 일.
+ *
+ * TrainingStepAudioPlayer 앞머리에 있었는데, 화면이 어떻게 생겼는지와는 다른 이야기다.
+ * 둘 다 브라우저의 <audio> 이벤트를 기다리되 **영영 기다리지 않는다**는 점이 핵심이라
+ * 함께 둔다 — canplay 도 error 도 오지 않는 경우가 실제로 있어서(형식을 못 읽거나
+ * 네트워크가 멎거나), 그때 화면이 스피너인 채로 멈추면 안 된다.
+ */
+/**
+ * 임시 <audio>로 오디오 길이(초)를 측정한다 — 세 로드 경로(TTS 단일/TTS 다중/일반 소스)에
+ * 복붙돼 있던 동일 로직의 단일화.
+ * rejectOnError=false(기본)면 오류·타임아웃 시 0으로 resolve(부분 실패 허용 경로),
+ * true면 reject해 호출부 catch로 전달(단일 TTS는 로드 실패를 사용자에게 알려야 하는 경로).
+ */
+export declare function measureAudioDuration(url: string, opts: {
+    timeoutMs: number;
+    rejectOnError?: boolean;
+}): Promise<number>;
+/**
+ * 들을 준비가 될 때까지 기다린다.
+ *
+ * canplay 도 error 도 안 오는 경우가 있다(형식을 못 읽거나, 네트워크가 멎거나). 그때
+ * 영영 기다리면 스피너가 남은 채로 화면이 멈추므로, 이 시간이 지나면 포기하고 넘어간다 —
+ * 재생이 안 되더라도 화면은 살아 있는 편이 낫다.
+ */
+export declare const CANPLAY_WAIT_MS = 2000;
+export declare function waitForCanPlay(a: HTMLAudioElement, timeoutMs?: number): Promise<void>;

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

@@ -0,0 +1,64 @@
+/**
+ * 오디오를 **기다리는 두 가지** — 길이를 재는 일과, 들을 준비가 되기를 기다리는 일.
+ *
+ * TrainingStepAudioPlayer 앞머리에 있었는데, 화면이 어떻게 생겼는지와는 다른 이야기다.
+ * 둘 다 브라우저의 <audio> 이벤트를 기다리되 **영영 기다리지 않는다**는 점이 핵심이라
+ * 함께 둔다 — canplay 도 error 도 오지 않는 경우가 실제로 있어서(형식을 못 읽거나
+ * 네트워크가 멎거나), 그때 화면이 스피너인 채로 멈추면 안 된다.
+ */
+/**
+ * 임시 <audio>로 오디오 길이(초)를 측정한다 — 세 로드 경로(TTS 단일/TTS 다중/일반 소스)에
+ * 복붙돼 있던 동일 로직의 단일화.
+ * rejectOnError=false(기본)면 오류·타임아웃 시 0으로 resolve(부분 실패 허용 경로),
+ * true면 reject해 호출부 catch로 전달(단일 TTS는 로드 실패를 사용자에게 알려야 하는 경로).
+ */
+export function measureAudioDuration(url, opts) {
+    return new Promise((resolve, reject) => {
+        const ta = document.createElement('audio');
+        let done = false;
+        const cleanup = () => { try {
+            ta.src = '';
+        }
+        catch (_) { } };
+        const finishOk = () => {
+            if (done)
+                return;
+            done = true;
+            const d = isFinite(ta.duration) ? (ta.duration || 0) : 0;
+            cleanup();
+            resolve(d);
+        };
+        const finishFail = (msg) => {
+            if (done)
+                return;
+            done = true;
+            cleanup();
+            if (opts.rejectOnError)
+                reject(new Error(msg));
+            else
+                resolve(0);
+        };
+        ta.addEventListener('loadedmetadata', finishOk);
+        ta.addEventListener('error', () => finishFail('audio load failed'));
+        setTimeout(() => finishFail('audio load timeout'), opts.timeoutMs);
+        ta.src = url;
+    });
+}
+/**
+ * 들을 준비가 될 때까지 기다린다.
+ *
+ * canplay 도 error 도 안 오는 경우가 있다(형식을 못 읽거나, 네트워크가 멎거나). 그때
+ * 영영 기다리면 스피너가 남은 채로 화면이 멈추므로, 이 시간이 지나면 포기하고 넘어간다 —
+ * 재생이 안 되더라도 화면은 살아 있는 편이 낫다.
+ */
+export const CANPLAY_WAIT_MS = 2000;
+export function waitForCanPlay(a, timeoutMs = CANPLAY_WAIT_MS) {
+    return new Promise((resolve) => {
+        let resolved = false;
+        const done = () => { if (resolved)
+            return; resolved = true; resolve(); };
+        a.addEventListener('canplay', done, { once: true });
+        a.addEventListener('error', done, { once: true });
+        setTimeout(done, timeoutMs);
+    });
+}

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

@@ -0,0 +1,26 @@
+/**
+ * 지금 울리는 소리는 하나뿐이다 — 그 하나를 여기서 붙든다.
+ *
+ * 스피커는 한 개다. 그런데 소리를 내는 코드는 여럿이고(훈련 단계 재생기·낱말 카드·게임),
+ * 저마다 제 오디오 객체를 갖는다. 그래서 "겹치지 않게 하겠다"고 쓴 코드가 **제 것만**
+ * 멈춘다 — 실제로 TrainingWordCard 는 `audioRef.current?.pause()` 로 겹침을 막는다고
+ * 적어 두었는데, 그 ref 는 그 카드의 것이라 옆 카드가 울리는 것은 못 멈췄다.
+ *
+ * 변별 훈련에서 1번·2번 소리를 잇달아 누르면 둘이 함께 울린 것이 이것이다(08-26 회의에서
+ * 치료사가 보고). speechSynthesis 만은 전역이라 `cancel()` 이 남의 것도 멈췄고, 그래서
+ * 음원이 없는 낱말에서는 멀쩡해 보였다 — 증상이 반만 나타나 원인을 찾기 어려웠다.
+ *
+ * 소유권을 모듈 하나에 둔다. React 문맥에 두지 않는 이유는, 소리를 내는 쪽이 그 문맥
+ * 안에 있으리라는 보장이 없어서다(게임·낱말표는 훈련 문맥 밖이다). 스피커가 전역이니
+ * 그것을 지키는 자물쇠도 전역인 편이 사실에 맞는다.
+ */
+/**
+ * 내가 울리겠다고 알린다 — 앞서 울리던 것은 여기서 멈춘다.
+ *
+ * @param stop 내 소리를 멈추는 함수. 다음 사람이 이걸 부른다.
+ * @returns 내가 끝났을 때 부를 함수. 내가 아직 주인일 때만 자리를 비운다 —
+ *          이미 다음 사람이 가져갔으면 그 사람 것을 지우면 안 된다.
+ */
+export declare function claimSound(stop: () => void): () => void;
+/** 지금 울리는 것을 멈춘다 — 화면을 떠날 때처럼, 새로 울릴 것이 없을 때 쓴다 */
+export declare function stopCurrentSound(): void;

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

@@ -0,0 +1,46 @@
+/**
+ * 지금 울리는 소리는 하나뿐이다 — 그 하나를 여기서 붙든다.
+ *
+ * 스피커는 한 개다. 그런데 소리를 내는 코드는 여럿이고(훈련 단계 재생기·낱말 카드·게임),
+ * 저마다 제 오디오 객체를 갖는다. 그래서 "겹치지 않게 하겠다"고 쓴 코드가 **제 것만**
+ * 멈춘다 — 실제로 TrainingWordCard 는 `audioRef.current?.pause()` 로 겹침을 막는다고
+ * 적어 두었는데, 그 ref 는 그 카드의 것이라 옆 카드가 울리는 것은 못 멈췄다.
+ *
+ * 변별 훈련에서 1번·2번 소리를 잇달아 누르면 둘이 함께 울린 것이 이것이다(08-26 회의에서
+ * 치료사가 보고). speechSynthesis 만은 전역이라 `cancel()` 이 남의 것도 멈췄고, 그래서
+ * 음원이 없는 낱말에서는 멀쩡해 보였다 — 증상이 반만 나타나 원인을 찾기 어려웠다.
+ *
+ * 소유권을 모듈 하나에 둔다. React 문맥에 두지 않는 이유는, 소리를 내는 쪽이 그 문맥
+ * 안에 있으리라는 보장이 없어서다(게임·낱말표는 훈련 문맥 밖이다). 스피커가 전역이니
+ * 그것을 지키는 자물쇠도 전역인 편이 사실에 맞는다.
+ */
+/** 지금 울리는 것을 멈추는 함수. 아무도 안 울리면 null */
+let stopCurrent = null;
+/**
+ * 내가 울리겠다고 알린다 — 앞서 울리던 것은 여기서 멈춘다.
+ *
+ * @param stop 내 소리를 멈추는 함수. 다음 사람이 이걸 부른다.
+ * @returns 내가 끝났을 때 부를 함수. 내가 아직 주인일 때만 자리를 비운다 —
+ *          이미 다음 사람이 가져갔으면 그 사람 것을 지우면 안 된다.
+ */
+export function claimSound(stop) {
+    if (stopCurrent && stopCurrent !== stop) {
+        try {
+            stopCurrent();
+        }
+        catch { /* 남의 실패로 내 재생을 막지 않는다 */ }
+    }
+    stopCurrent = stop;
+    return () => { if (stopCurrent === stop)
+        stopCurrent = null; };
+}
+/** 지금 울리는 것을 멈춘다 — 화면을 떠날 때처럼, 새로 울릴 것이 없을 때 쓴다 */
+export function stopCurrentSound() {
+    if (!stopCurrent)
+        return;
+    try {
+        stopCurrent();
+    }
+    catch { /* 무시 */ }
+    stopCurrent = null;
+}

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

@@ -0,0 +1,17 @@
+/**
+ * 전체 화면 팝업이 사라지는 데 걸리는 시간(ms).
+ *
+ * **CSS 와 맞아야 하는 숫자다.** 화면은 `opacity` 를 이 시간 동안 줄이고, 코드는 그만큼
+ * 기다렸다가 실제로 떼어 낸다. 코드 쪽이 짧으면 사라지다 만 채 툭 끊기고, 길면 다 사라진
+ * 빈 자리를 그만큼 붙들고 있는다.
+ *
+ * 짝이 되는 CSS —
+ *   src/app/PagePopup/PagePopup.css               `transition: opacity 160ms`
+ *   packages/core/src/components/Training/TrainingPagePopup.css `transition: opacity 160ms`
+ *
+ * 한때 이 숫자가 세 파일에 따로 적혀 있었다. 어긋나도 화면이 조금 어색해질 뿐이라
+ * 아무도 알아채지 못하는 종류다 — pagePopupTiming.test.ts 가 CSS 와 대조한다.
+ *
+ * (일반 팝업 Popup.tsx 의 ANIM_MS=260 은 다른 애니메이션이라 별개다.)
+ */
+export declare const PAGE_POPUP_CLOSE_MS = 160;

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

@@ -0,0 +1,17 @@
+/**
+ * 전체 화면 팝업이 사라지는 데 걸리는 시간(ms).
+ *
+ * **CSS 와 맞아야 하는 숫자다.** 화면은 `opacity` 를 이 시간 동안 줄이고, 코드는 그만큼
+ * 기다렸다가 실제로 떼어 낸다. 코드 쪽이 짧으면 사라지다 만 채 툭 끊기고, 길면 다 사라진
+ * 빈 자리를 그만큼 붙들고 있는다.
+ *
+ * 짝이 되는 CSS —
+ *   src/app/PagePopup/PagePopup.css               `transition: opacity 160ms`
+ *   packages/core/src/components/Training/TrainingPagePopup.css `transition: opacity 160ms`
+ *
+ * 한때 이 숫자가 세 파일에 따로 적혀 있었다. 어긋나도 화면이 조금 어색해질 뿐이라
+ * 아무도 알아채지 못하는 종류다 — pagePopupTiming.test.ts 가 CSS 와 대조한다.
+ *
+ * (일반 팝업 Popup.tsx 의 ANIM_MS=260 은 다른 애니메이션이라 별개다.)
+ */
+export const PAGE_POPUP_CLOSE_MS = 160;

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

@@ -0,0 +1,79 @@
+import type { CSSProperties, ReactNode } from 'react';
+import type { TrainingItem } from '../../types/training';
+/** @public */
+export interface TrainingBlockButtonPopupProps {
+    trainingData: TrainingItem | null;
+    typeKey: string;
+    onClose: () => void;
+    /** 완료 시 호출. TrainingPagePopup이 계산한 정답/전체 문항 수가 실려온다(옵셔널 — 무시해도 무방). */
+    onComplete?: (result?: {
+        correct: number | null;
+        total: number | null;
+    }) => void;
+    popupTitle: string;
+    popupSubTitle?: string;
+    depth?: string;
+    popupIcon?: string;
+    popupIconTooltip?: string;
+    popupWrapperStyle?: CSSProperties;
+    /** 완료 정본 기록 진입점 — 'daily' | 'sentence' | 'word' (TrainingPagePopup으로 전달) */
+    entryPoint?: string;
+    /** entry_point='daily'일 때 그날 전체 항목 수 */
+    dailyTotal?: number;
+    /** 완료 정본의 항목 식별자(item_ref) — 기기 간 완료표시 동기화에 사용 */
+    itemRef?: string;
+}
+/** @public */
+export interface TrainingBlockButtonProps {
+    index: number;
+    type?: {
+        key?: string;
+        label?: string;
+        icon?: string;
+    };
+    trainingData?: TrainingItem | null;
+    ariaLabel?: string;
+    depth?: unknown;
+    completed?: boolean;
+    /**
+     * 버튼 레이아웃 크기.
+     * - `square` (기본값): 200×200px 정사각형 카드
+     * - `small`: 120×120px 축소 카드 (행 펼치기 영역 등 좁은 공간용)
+     * - `list`: 전체 너비 × 60px 가로형 리스트 항목
+     * - `compact`: 툴팁 등 좁은 공간용 소형 리스트 항목 (44px, 아이콘 24px)
+     */
+    size?: 'square' | 'small' | 'list' | 'compact';
+    renderPopup?: (props: TrainingBlockButtonPopupProps) => ReactNode;
+    completedIds?: Set<string>;
+    /** 선택 상태 ID Set. 완료 뱃지 없이 테두리 강조만 표시. */
+    selectedIds?: Set<string>;
+    /** 호버 시 표시할 문제/문장 텍스트. 제공 시 DescriptionTooltip 으로 렌더. */
+    tooltipText?: string | string[];
+    /** true 이면 호버 시 DescriptionTooltip 으로 문제 텍스트를 표시. 기본값 false. */
+    useDescriptionTooltip?: boolean;
+    /** 제공 시 hover 중 뱃지 자리에 X 버튼 표시 — 클릭하면 호출됨. */
+    onRemove?: () => void;
+    /** true 이면 완료/선택 체크 뱃지를 표시하지 않음 */
+    hideCheckBadge?: boolean;
+    /** true 이면 카드 우측 상단에 훈련 타입명 칩을 표시 */
+    showTypeLabel?: boolean;
+    /** 완료 시 호출. 결과 팝업이 계산한 정답/전체 문항 수가 실려온다(옵셔널 — 무시해도 무방). */
+    onComplete?: (result?: {
+        correct: number | null;
+        total: number | null;
+    }) => void;
+    /**
+     * 제공 시 카드를 "선택형"으로 동작시킨다. 클릭/Enter/Space 시 팝업을 여는 대신
+     * 이 콜백을 호출한다(키보드 접근성 유지). 미제공 시 기본대로 팝업을 연다.
+     */
+    onSelect?: () => void;
+    /**
+     * 제공 시 카드 우측 상단에 '더보기(⋯)' 버튼을 표시한다. 클릭하면 카드 활성화와
+     * 분리되어 이 콜백만 호출된다(`e.currentTarget` = 더보기 버튼 = 메뉴 anchor).
+     * 미제공 시 버튼을 표시하지 않는다.
+     */
+    onMore?: (e: React.MouseEvent) => void;
+    /** 카운트 라벨을 직접 지정 (지정 시 내부 계산 대신 사용). 예: 카드 묶음 "N개" */
+    countLabelOverride?: ReactNode;
+}
+export declare const extractProblemText: (td: Record<string, unknown> | null | undefined) => string[];

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

@@ -0,0 +1,27 @@
+// trainingData 에서 문제/문장 텍스트 추출 (호버 tooltip 용)
+export const extractProblemText = (td) => {
+    if (!td)
+        return [];
+    const direct = (typeof td.context === 'string' && td.context.trim()) ||
+        (typeof td.sentence === 'string' && td.sentence.trim()) ||
+        (typeof td.text === 'string' && td.text.trim()) ||
+        '';
+    if (direct)
+        return [String(direct)];
+    const arr = td.sentences || td.items || td.questions || [];
+    if (Array.isArray(arr) && arr.length > 0) {
+        return arr
+            .map((x) => {
+            if (typeof x === 'string')
+                return x;
+            if (x && typeof x === 'object') {
+                const xr = x;
+                return xr.sentence || xr.text || xr.context || xr.question || xr.title || '';
+            }
+            return '';
+        })
+            .filter((s) => typeof s === 'string' && s.trim().length > 0)
+            .map((s) => s.trim());
+    }
+    return [];
+};

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

@@ -0,0 +1,148 @@
+/**
+ * 대면 훈련에서 **무엇을 틀렸는지** 모아 읽는다. 화면도 통신도 없다.
+ *
+ * 단어표 채점(`wordScoreStats`)이 종이로 한 것을 세는 자리라면, 여기는 아이가 앱에서
+ * 푼 것을 세는 자리다. 치료사가 묻는 것은 같다 — *계속 걸리는 것이 무엇인가*,
+ * *다음 시간에 무엇을 볼까*. 그래서 셈의 결도 같게 맞췄다.
+ *
+ * ── 문항 행만 센다 ──
+ * `customer_training_result` 에는 세 가지가 섞여 있다. 문항 하나(`kind:'item'`),
+ * 판 전체 요약(`kind:'summary'`), 세션 시간(`kind:'time'`). 뒤의 둘은 `is_correct` 가
+ * 비어 있다. 그것을 '틀림' 으로 세면 한 판 할 때마다 오답이 두 개씩 늘어난다.
+ *
+ * ── 글자가 없으면 빼되, 뺐다고 말한다 ──
+ * 문항에 식별자를 남기기 시작한 것은 2026-08-30 부터다. 그 전 기록은 `item_title` 이
+ * 비어 있어 **무엇을 틀렸는지 보여 줄 수가 없다.** 조용히 빼면 화면의 수가 전부인 줄
+ * 알게 되므로 몇 건을 뺐는지 함께 돌려준다.
+ */
+/**
+ * @public 저장된 기록 한 줄(서버가 주는 모양 중 필요한 것만).
+ *
+ * 한 줄은 셋 중 하나다 — **문항**(정오답이 있다) · **판 전체 요약**(맞힌 수·문항 수·
+ * 소요가 있다) · **세션 시간**(둘 다 없다). 무엇을 볼지는 읽는 쪽이 정한다.
+ */
+export interface TrainingResultRecord {
+    answeredAt: string;
+    trainingType: string;
+    /** 문항 식별자 — 코드가 있는 유형은 코드, 없는 유형(낱말)은 낱말 자체 */
+    itemId: string | null;
+    /** 화면에 보였던 글자 */
+    itemTitle: string | null;
+    /** 문항 행만 참/거짓이다. 요약·시간 행은 null */
+    isCorrect: boolean | null;
+    /** 이 문항이 든 훈련 세트 uuid — 다음 훈련을 짤 때 쓴다 */
+    setId: string | null;
+    /** 아이가 고른 것 — 무엇으로 헷갈리는지 */
+    selected: string | null;
+    /** 판 전체 요약 행에만 있다 — 그 판에서 맞힌 문항 수 */
+    correct?: number | null;
+    /** 판 전체 요약 행에만 있다 — 그 판의 문항 수 */
+    total?: number | null;
+    /** 판 전체 요약 행에만 있다 — 그 판에 걸린 시간(초) */
+    durationSeconds?: number | null;
+}
+/** @public 문항 하나에 대해 쌓인 성적. */
+export interface MissedItem {
+    /** `유형|식별자`. 같은 낱말이라도 유형이 다르면 다른 문항이다 */
+    key: string;
+    trainingType: string;
+    itemId: string;
+    /** 화면에 보일 글자 */
+    title: string;
+    /** 이 문항을 푼 횟수 */
+    tried: number;
+    wrong: number;
+    /** 정답률(0~1) */
+    rate: number;
+    /** 마지막에 맞혔나 */
+    latestCorrect: boolean;
+    latestAt: string;
+    /** 마지막으로 고른 것 — 틀렸을 때만 뜻이 있다 */
+    lastSelected: string | null;
+    /** 이 문항이 나온 세트들(최근 것부터). 다음 훈련 자동 생성이 쓴다 */
+    setIds: string[];
+}
+/** @public */
+export interface MissSummary {
+    /** 약한 것부터 */
+    items: MissedItem[];
+    /** 셈에 든 문항 행 수 */
+    counted: number;
+    /** 글자가 안 남아 뺀 행 수 — 화면이 이 사실을 말해야 한다 */
+    skippedNoTitle: number;
+}
+/**
+ * @public 문항별로 모아 **약한 것부터** 늘어놓는다.
+ *
+ * 정렬은 세 겹이다. 정답률이 낮은 것이 먼저이되, **같은 정답률이면 여러 번 푼 것을
+ * 앞에 둔다** — 한 번 틀린 것과 다섯 번 내리 틀린 것은 무게가 다르다. 그래도 같으면
+ * 글자순으로 못 박는다(그러지 않으면 다시 읽을 때마다 차례가 흔들려 보던 줄을 놓친다).
+ */
+export declare function summarizeMisses(records: readonly TrainingResultRecord[]): MissSummary;
+/**
+ * @public 다음에 무엇을 볼지.
+ *
+ * **아직 잡히지 않은 문항**을 고른다 — 마지막에 틀린 것들. 정답률이 낮아도 지난번에
+ * 맞혔다면 지금 급한 것이 아니고, 정답률이 높아도 방금 틀렸으면 다시 봐야 한다.
+ * "지난번에 어땠나"가 "여태 어땠나"보다 다음 시간을 정한다.
+ *
+ * `limit` 은 한 시간에 다룰 만한 양이다. 스무 개를 늘어놓으면 고르는 일이 다시 숙제가 된다.
+ *
+ * **이 저장소는 더 이상 이것으로 화면을 그리지 않는다.** 잘라 주는 편리함이 그대로
+ * '조용한 축소'가 됐기 때문이다 — 스물다섯 개가 밀려 있어도 화면에는 여덟만 뜨고,
+ * 세는 수까지 여덟로 적히면 나머지는 없는 것이 된다(실제로 그렇게 있었다). 지금은
+ * 못 잡은 것을 **전부** 표로 늘어놓고 쪽넘김을 둔다. 다음 훈련에 담을 양을 고르는
+ * 셈에는 여전히 쓸 수 있지만, **늘어놓는 데에는 쓰지 않는다.**
+ */
+export declare function nextMisses(items: readonly MissedItem[], limit?: number): MissedItem[];
+/** @public 훈련 유형 하나에 모인 오답. */
+export interface MissGroup {
+    trainingType: string;
+    items: MissedItem[];
+    /** 이 유형에서 아직 못 잡은 문항 수 */
+    pending: number;
+}
+/**
+ * @public 유형별로 가른다 — 다음 훈련 세트는 **한 유형 안에서** 짜야 하기 때문이다.
+ *
+ * 못 잡은 것이 많은 유형이 먼저. 같으면 유형 키로 갈라 차례를 못 박는다.
+ */
+export declare function missesByType(items: readonly MissedItem[]): MissGroup[];
+/**
+ * @public 훈련 플랜(`managed_training_set`)의 `part1~4` 에 자리가 있는 유형.
+ *
+ * 플랜은 문장 훈련 넷만 담는다. **단어 유형은 여기 자리가 없고** 그릇이 아예 다르다
+ * (`word_training_card.set_ids`). 그래서 다음 훈련을 짤 때 둘을 갈라야 한다.
+ */
+export declare const SENTENCE_TRAINING_TYPES: readonly string[];
+/** @public 세트 하나와 그 안에 남아 있는 오답 수. */
+export interface ReviewSetRef {
+    setId: string;
+    trainingType: string;
+    /** 이 세트 안에서 아직 못 잡은 문항 수 */
+    pending: number;
+}
+/** @public 다음 훈련으로 무엇을 만들 수 있나. */
+export interface ReviewSetPlan {
+    /** 훈련 플랜에 담을 것 — 문장 유형 */
+    sentence: ReviewSetRef[];
+    /** 단어훈련 묶음에 담을 것 — 단어 유형 */
+    word: ReviewSetRef[];
+    /** 어느 세트에서 나온 것인지 안 남아 담지 못한 문항 수 */
+    noSet: number;
+}
+/**
+ * @public 못 잡은 문항들이 **어느 세트에 들어 있었는지** 모아 다음 훈련거리를 짠다.
+ * 단어표의 복습표와 같은 결이다 — 틀린 것만 다시 돌린다.
+ *
+ * ── 세트는 **가장 최근 것 하나만** ──
+ * 같은 문항이 여러 세트에 있을 수 있는데 전부 담으면, 그 세트들에 든 *맞힌* 문항까지
+ * 딸려 와 결국 원래 훈련을 통째로 다시 하게 된다. 치료사가 마지막에 쓴 세트가 지금
+ * 아이에게 맞춰진 것이므로 그것을 쓴다(`setIds[0]` 이 최근 것이다).
+ *
+ * ── 세트가 안 남은 문항은 담지 못한다 ──
+ * 진입점이 세트 uuid 를 넘기기 시작한 것은 2026-08-30 부터다. 그 전 기록은 문항은
+ * 남았는데 **어느 세트였는지가 없어** 다시 꺼낼 방법이 없다. 조용히 빼면 "다섯 개가
+ * 밀렸다"고 해 놓고 두 개짜리 세트가 나온다 — 몇 개를 못 담았는지 함께 돌려준다.
+ */
+export declare function reviewSetPlan(items: readonly MissedItem[]): ReviewSetPlan;