@ihabdevteam/core 0.8.0

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

@@ -0,0 +1,163 @@
+/**
+ * 대면 훈련에서 **무엇을 틀렸는지** 모아 읽는다. 화면도 통신도 없다.
+ *
+ * 단어표 채점(`wordScoreStats`)이 종이로 한 것을 세는 자리라면, 여기는 아이가 앱에서
+ * 푼 것을 세는 자리다. 치료사가 묻는 것은 같다 — *계속 걸리는 것이 무엇인가*,
+ * *다음 시간에 무엇을 볼까*. 그래서 셈의 결도 같게 맞췄다.
+ *
+ * ── 문항 행만 센다 ──
+ * `customer_training_result` 에는 세 가지가 섞여 있다. 문항 하나(`kind:'item'`),
+ * 판 전체 요약(`kind:'summary'`), 세션 시간(`kind:'time'`). 뒤의 둘은 `is_correct` 가
+ * 비어 있다. 그것을 '틀림' 으로 세면 한 판 할 때마다 오답이 두 개씩 늘어난다.
+ *
+ * ── 글자가 없으면 빼되, 뺐다고 말한다 ──
+ * 문항에 식별자를 남기기 시작한 것은 2026-08-30 부터다. 그 전 기록은 `item_title` 이
+ * 비어 있어 **무엇을 틀렸는지 보여 줄 수가 없다.** 조용히 빼면 화면의 수가 전부인 줄
+ * 알게 되므로 몇 건을 뺐는지 함께 돌려준다.
+ */
+/**
+ * @public 문항별로 모아 **약한 것부터** 늘어놓는다.
+ *
+ * 정렬은 세 겹이다. 정답률이 낮은 것이 먼저이되, **같은 정답률이면 여러 번 푼 것을
+ * 앞에 둔다** — 한 번 틀린 것과 다섯 번 내리 틀린 것은 무게가 다르다. 그래도 같으면
+ * 글자순으로 못 박는다(그러지 않으면 다시 읽을 때마다 차례가 흔들려 보던 줄을 놓친다).
+ */
+export function summarizeMisses(records) {
+    const 모음 = new Map();
+    let counted = 0;
+    let skippedNoTitle = 0;
+    /* 최근 것을 알려면 시간순으로 훑어야 한다. 서버는 최신순으로 주지만 여기서 다시
+       정렬한다 — 부르는 쪽의 차례에 기대면 그쪽이 바뀔 때 조용히 어긋난다. */
+    const 시간순 = [...records].sort((a, b) => a.answeredAt.localeCompare(b.answeredAt));
+    for (const r of 시간순) {
+        // 요약·시간 행은 문항이 아니다. 틀림으로 세면 한 판마다 오답이 늘어난다.
+        if (r.isCorrect == null)
+            continue;
+        const title = r.itemTitle?.trim();
+        if (!title) {
+            skippedNoTitle++;
+            continue;
+        }
+        counted++;
+        const id = r.itemId?.trim() || title;
+        const key = `${r.trainingType}|${id}`;
+        const cur = 모음.get(key) ?? {
+            trainingType: r.trainingType, itemId: id, title,
+            tried: 0, wrong: 0,
+            latestCorrect: r.isCorrect, latestAt: r.answeredAt, lastSelected: r.selected,
+            setIds: [],
+        };
+        cur.tried++;
+        if (!r.isCorrect)
+            cur.wrong++;
+        cur.title = title; // 지문이 고쳐졌으면 마지막에 보인 글자를 쓴다
+        cur.latestCorrect = r.isCorrect;
+        cur.latestAt = r.answeredAt;
+        cur.lastSelected = r.selected;
+        /* 세트는 **최근 것이 앞**이어야 한다 — 다음 훈련을 짤 때 옛 세트를 먼저 집으면
+           그 사이 세트가 바뀌었을 수 있다. 시간순으로 훑고 있으니 앞에 넣는다. */
+        if (r.setId && !cur.setIds.includes(r.setId))
+            cur.setIds.unshift(r.setId);
+        모음.set(key, cur);
+    }
+    const items = [...모음.entries()].map(([key, v]) => ({
+        key,
+        trainingType: v.trainingType,
+        itemId: v.itemId,
+        title: v.title,
+        tried: v.tried,
+        wrong: v.wrong,
+        rate: v.tried === 0 ? 0 : (v.tried - v.wrong) / v.tried,
+        latestCorrect: v.latestCorrect,
+        latestAt: v.latestAt,
+        lastSelected: v.lastSelected,
+        setIds: v.setIds,
+    }));
+    items.sort((a, b) => a.rate - b.rate || b.tried - a.tried || a.title.localeCompare(b.title));
+    return { items, counted, skippedNoTitle };
+}
+/**
+ * @public 다음에 무엇을 볼지.
+ *
+ * **아직 잡히지 않은 문항**을 고른다 — 마지막에 틀린 것들. 정답률이 낮아도 지난번에
+ * 맞혔다면 지금 급한 것이 아니고, 정답률이 높아도 방금 틀렸으면 다시 봐야 한다.
+ * "지난번에 어땠나"가 "여태 어땠나"보다 다음 시간을 정한다.
+ *
+ * `limit` 은 한 시간에 다룰 만한 양이다. 스무 개를 늘어놓으면 고르는 일이 다시 숙제가 된다.
+ *
+ * **이 저장소는 더 이상 이것으로 화면을 그리지 않는다.** 잘라 주는 편리함이 그대로
+ * '조용한 축소'가 됐기 때문이다 — 스물다섯 개가 밀려 있어도 화면에는 여덟만 뜨고,
+ * 세는 수까지 여덟로 적히면 나머지는 없는 것이 된다(실제로 그렇게 있었다). 지금은
+ * 못 잡은 것을 **전부** 표로 늘어놓고 쪽넘김을 둔다. 다음 훈련에 담을 양을 고르는
+ * 셈에는 여전히 쓸 수 있지만, **늘어놓는 데에는 쓰지 않는다.**
+ */
+export function nextMisses(items, limit = 8) {
+    return items.filter(i => !i.latestCorrect).slice(0, limit);
+}
+/**
+ * @public 유형별로 가른다 — 다음 훈련 세트는 **한 유형 안에서** 짜야 하기 때문이다.
+ *
+ * 못 잡은 것이 많은 유형이 먼저. 같으면 유형 키로 갈라 차례를 못 박는다.
+ */
+export function missesByType(items) {
+    const 모음 = new Map();
+    for (const i of items) {
+        const arr = 모음.get(i.trainingType) ?? [];
+        arr.push(i);
+        모음.set(i.trainingType, arr);
+    }
+    const out = [...모음.entries()].map(([trainingType, list]) => ({
+        trainingType,
+        items: list,
+        pending: list.filter(i => !i.latestCorrect).length,
+    }));
+    out.sort((a, b) => b.pending - a.pending || a.trainingType.localeCompare(b.trainingType));
+    return out;
+}
+/**
+ * @public 훈련 플랜(`managed_training_set`)의 `part1~4` 에 자리가 있는 유형.
+ *
+ * 플랜은 문장 훈련 넷만 담는다. **단어 유형은 여기 자리가 없고** 그릇이 아예 다르다
+ * (`word_training_card.set_ids`). 그래서 다음 훈련을 짤 때 둘을 갈라야 한다.
+ */
+export const SENTENCE_TRAINING_TYPES = ['LISTEN_IN_NOISE', 'SHORT_STORY', 'LONG_STORY', 'ORDERING_SENTENCE'];
+/**
+ * @public 못 잡은 문항들이 **어느 세트에 들어 있었는지** 모아 다음 훈련거리를 짠다.
+ * 단어표의 복습표와 같은 결이다 — 틀린 것만 다시 돌린다.
+ *
+ * ── 세트는 **가장 최근 것 하나만** ──
+ * 같은 문항이 여러 세트에 있을 수 있는데 전부 담으면, 그 세트들에 든 *맞힌* 문항까지
+ * 딸려 와 결국 원래 훈련을 통째로 다시 하게 된다. 치료사가 마지막에 쓴 세트가 지금
+ * 아이에게 맞춰진 것이므로 그것을 쓴다(`setIds[0]` 이 최근 것이다).
+ *
+ * ── 세트가 안 남은 문항은 담지 못한다 ──
+ * 진입점이 세트 uuid 를 넘기기 시작한 것은 2026-08-30 부터다. 그 전 기록은 문항은
+ * 남았는데 **어느 세트였는지가 없어** 다시 꺼낼 방법이 없다. 조용히 빼면 "다섯 개가
+ * 밀렸다"고 해 놓고 두 개짜리 세트가 나온다 — 몇 개를 못 담았는지 함께 돌려준다.
+ */
+export function reviewSetPlan(items) {
+    const 모음 = new Map();
+    let noSet = 0;
+    for (const i of items) {
+        if (i.latestCorrect)
+            continue; // 지난번에 잡혔으면 다시 낼 것이 아니다
+        const setId = i.setIds[0];
+        if (!setId) {
+            noSet++;
+            continue;
+        }
+        const key = `${i.trainingType}|${setId}`;
+        const cur = 모음.get(key) ?? { setId, trainingType: i.trainingType, pending: 0 };
+        cur.pending++;
+        모음.set(key, cur);
+    }
+    /* 못 잡은 것이 많은 세트가 먼저. 같으면 유형·uuid 로 갈라 차례를 못 박는다 —
+       같은 자료에 두 번 물어 순서가 다르면 사람은 값이 바뀐 줄 안다. */
+    const 정렬 = (a, b) => b.pending - a.pending || a.trainingType.localeCompare(b.trainingType) || a.setId.localeCompare(b.setId);
+    const all = [...모음.values()];
+    return {
+        sentence: all.filter(r => SENTENCE_TRAINING_TYPES.includes(r.trainingType)).sort(정렬),
+        word: all.filter(r => !SENTENCE_TRAINING_TYPES.includes(r.trainingType)).sort(정렬),
+        noSet,
+    };
+}

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

@@ -0,0 +1,108 @@
+/** @public */
+export declare function normalizeCats(item: unknown): {
+    c0: string;
+    c1: string;
+};
+/** @public */
+export declare function closeTrainingPopup(): void;
+/**
+ * Resolves the onBack handler from spread props.
+ * Falls back: props.onBack → props.onClose → closeTrainingPopup
+ * @public
+ */
+export declare function resolveOnBack(rest: Record<string, unknown>): () => void;
+/** @public */
+export declare function splitTrainingVariants(value: unknown): string[];
+/** @public */
+export declare function resolveTrainingPopupMeta(trainingData: Record<string, unknown> | null | undefined, depth: string | string[] | null | undefined, fallbackTitle: string): {
+    title: string;
+    label: string;
+    depth: string | string[] | null | undefined;
+    icon: string | undefined;
+    wrapperStyle: {
+        "--t-item-fg": string;
+    } | undefined;
+    iconTooltip: string | undefined;
+};
+/** @public */
+export declare function getPayloadTimestamp(payload: unknown): number;
+/** @public */
+export declare function resolveTrainingItems(trainingData: unknown): unknown[];
+interface CreateTrainingScenarioParams {
+    idPrefix: string;
+    trainingData?: Record<string, unknown> | null;
+    depth?: string | string[] | null;
+    fallbackTitle?: string;
+    pages?: unknown[];
+    emptyMessage?: string;
+    buildResults?: (pageAnswers: Record<string, unknown>) => unknown;
+    metaPatch?: ((meta: ReturnType<typeof resolveTrainingPopupMeta>) => Partial<ReturnType<typeof resolveTrainingPopupMeta>>) | Partial<ReturnType<typeof resolveTrainingPopupMeta>>;
+}
+/** @public */
+export declare function createTrainingScenario({ idPrefix, trainingData, depth, fallbackTitle, pages, emptyMessage, buildResults, metaPatch, }: CreateTrainingScenarioParams): {
+    id: string;
+    meta: {
+        title: string;
+        label: string;
+        depth: string | string[] | null | undefined;
+        icon: string | undefined;
+        wrapperStyle: {
+            "--t-item-fg": string;
+        } | undefined;
+        iconTooltip: string | undefined;
+    };
+    pages: unknown[];
+    emptyMessage: string | undefined;
+    buildResults: ((pageAnswers: Record<string, unknown>) => unknown) | undefined;
+};
+/** @public */
+export declare function toTrainingText(value: unknown): string;
+/** @public */
+export declare function getSelectedFromPayload(payload: unknown): unknown;
+/** @public */
+export declare function getSelectedText(selected: unknown, choices?: unknown[]): string | undefined;
+/** @public */
+export declare function getStepPayload(pageAnswers: unknown, stepIndex: number | string): unknown;
+/** @public */
+export declare function getSteppedPayload(pageAnswers: unknown, itemIndex: number, stride: number, offset: number): unknown;
+interface IsSelectionCorrectParams {
+    payload?: unknown;
+    selected?: unknown;
+    choices?: unknown[];
+    correctAnswers?: unknown[];
+}
+/** @public */
+export declare function isSelectionCorrect({ payload, selected, choices, correctAnswers }: IsSelectionCorrectParams): boolean | undefined;
+interface NoiseContext {
+    sentence?: string;
+    contextCode?: string;
+}
+/** @public */
+export declare function deriveNoiseContexts(trainingData: Record<string, unknown> | null | undefined): NoiseContext[];
+/** {@link buildTwoStepPickResults} 가 내는 한 문제의 채점 결과. */
+interface TwoStepPickResult {
+    question: unknown;
+    choices: unknown[];
+    selected: unknown;
+    selectedText: unknown;
+    correct: boolean | undefined;
+    answer: unknown;
+}
+/**
+ * @public "듣고 → 보기 카드 고르기" 두 단계짜리 훈련의 채점.
+ *
+ * 일치하는 단어 맞히기·한 음절 포함 단어 맞히기·첫 음절이 같은 단어 맞히기 셋이
+ * 한 글자도 다르지 않은 채점을 한 벌씩 들고 있었다. 정말 다른 것은 **결과지에 무엇을
+ * 문제로 적을 것인가** 하나뿐이라(들려준 낱말이냐, 음절이냐, 원본 낱말이냐), 그것만
+ * 밖에서 받는다.
+ *
+ * 정답은 answerIndex 가 있으면 보기에서 그 자리를 쓰고, 없으면 item.answer 를 쓴다.
+ *
+ * @param questionOf - 결과지의 '문제' 칸에 적을 것을 항목에서 뽑는다
+ */
+export declare function buildTwoStepPickResults(items: unknown[] | undefined, pageAnswers: Record<string, unknown>, questionOf: (item: Record<string, unknown>) => unknown): {
+    score: number;
+    results: TwoStepPickResult[];
+    answers: TwoStepPickResult[];
+};
+export {};

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

@@ -0,0 +1,226 @@
+'use client';
+import { getTopicTypes } from "../../utils/categories";
+/** @public */
+export function normalizeCats(item) {
+    if (!item || typeof item !== 'object')
+        return { c0: '', c1: '' };
+    const it = item;
+    const grp = it.group;
+    const raw = it.raw;
+    const c0 = (it.category_0 || it.category_main_code || it.category_main ||
+        grp?.category_0 || grp?.category_main_code || raw?.category_main_code || '').toString().toUpperCase();
+    const c1 = (it.category_1 || it.category_sub_code || it.category_sub ||
+        grp?.category_1 || grp?.category_sub_code || raw?.category_sub_code || '').toString().toUpperCase();
+    return { c0, c1 };
+}
+/** @public */
+export function closeTrainingPopup() {
+    if (typeof window !== "undefined") {
+        window.dispatchEvent(new CustomEvent("speechear.popup.close"));
+    }
+}
+/**
+ * Resolves the onBack handler from spread props.
+ * Falls back: props.onBack → props.onClose → closeTrainingPopup
+ * @public
+ */
+export function resolveOnBack(rest) {
+    return (rest.onBack ?? rest.onClose ?? closeTrainingPopup);
+}
+/** @public */
+export function splitTrainingVariants(value) {
+    if (!value && value !== 0)
+        return [];
+    if (Array.isArray(value)) {
+        return value.flatMap((entry) => typeof entry === "string"
+            ? entry.split("|").map((item) => item.trim()).filter(Boolean)
+            : entry || entry === 0
+                ? [String(entry)]
+                : []);
+    }
+    if (typeof value === "string") {
+        return value.split("|").map((item) => item.trim()).filter(Boolean);
+    }
+    return [String(value)];
+}
+/** @public */
+export function resolveTrainingPopupMeta(trainingData, depth, fallbackTitle) {
+    const td = trainingData;
+    const title = td?.title ||
+        td?.name ||
+        (Array.isArray(depth) ? depth[depth.length - 1] : undefined) ||
+        fallbackTitle ||
+        "훈련";
+    const topicTypes = getTopicTypes();
+    const category = topicTypes.find((entry) => entry.key === (td?.category_0 || td?.category_main_code));
+    const subCategory = category?.subs?.find((entry) => entry.key === (td?.category_1 || td?.category_sub_code));
+    return {
+        title,
+        label: td?.title || title,
+        depth,
+        icon: category?.icon,
+        wrapperStyle: category?.color
+            ? { "--t-item-fg": category.color }
+            : undefined,
+        iconTooltip: [category?.label, subCategory?.label].filter(Boolean).join(" / ") || undefined,
+    };
+}
+/** @public */
+export function getPayloadTimestamp(payload) {
+    if (payload && typeof payload === "object" && typeof payload.__ts === "number") {
+        return payload.__ts;
+    }
+    return 0;
+}
+/** @public */
+export function resolveTrainingItems(trainingData) {
+    const td = trainingData;
+    if (Array.isArray(td?.items))
+        return td.items;
+    if (Array.isArray(trainingData))
+        return trainingData;
+    return trainingData ? [trainingData] : [];
+}
+/** @public */
+export function createTrainingScenario({ idPrefix, trainingData, depth, fallbackTitle = "훈련", pages = [], 
+/* 기본값을 두지 않는다. 화면은 `scenario?.emptyMessage || t('training.noQuestions',
+   '문제가 없습니다.')` 로 그리는데, 여기서 한국어를 채워 두면 그 뒤 갈래가 **한 번도
+   안 쓰인다** — (이 예시도 한때 관문을 빨갛게 만들었다. 이제 i18n 지킴이가 주석을
+   걷어 내므로 그대로 적어 둔다.)
+   영어로 쓰는 사람도 그 자리만 한국어를 본다. 주면 그것을 쓰고, 안 주면 비워 둬
+   무슨 말로 보여 줄지는 화면이 정하게 한다. */
+emptyMessage, buildResults, metaPatch, }) {
+    const baseMeta = resolveTrainingPopupMeta(trainingData, depth, fallbackTitle);
+    const extraMeta = typeof metaPatch === "function" ? (metaPatch(baseMeta) || {}) : (metaPatch || {});
+    const suffix = trainingData?.id || trainingData?.title || pages.length;
+    return {
+        id: `${idPrefix}:${suffix}`,
+        meta: {
+            ...baseMeta,
+            ...extraMeta,
+        },
+        pages,
+        emptyMessage,
+        buildResults,
+    };
+}
+/** @public */
+export function toTrainingText(value) {
+    if (typeof value === "string")
+        return value;
+    if (value && typeof value === "object") {
+        const v = value;
+        return (v.context || v.sentence || v.question || "") || "";
+    }
+    return "";
+}
+/** @public */
+export function getSelectedFromPayload(payload) {
+    if (payload && typeof payload === "object") {
+        const p = payload;
+        if (Array.isArray(p.selectedValues))
+            return p.selectedValues;
+        if (p.selectedValue !== undefined)
+            return p.selectedValue;
+        if (p.selectedIndex !== undefined)
+            return p.selectedIndex;
+        if (p.value !== undefined)
+            return p.value;
+    }
+    return payload;
+}
+/** @public */
+export function getSelectedText(selected, choices = []) {
+    if (Array.isArray(selected))
+        return selected.join(", ");
+    if (typeof selected === "number" && Array.isArray(choices))
+        return String(choices[selected] ?? '');
+    if (typeof selected === "string")
+        return selected;
+    return undefined;
+}
+/** @public */
+export function getStepPayload(pageAnswers, stepIndex) {
+    if (!pageAnswers || typeof pageAnswers !== "object")
+        return undefined;
+    return pageAnswers[`step-${stepIndex}`];
+}
+/** @public */
+export function getSteppedPayload(pageAnswers, itemIndex, stride, offset) {
+    return getStepPayload(pageAnswers, itemIndex * stride + offset);
+}
+/** @public */
+export function isSelectionCorrect({ payload, selected, choices = [], correctAnswers = [] }) {
+    if (payload && typeof payload === "object") {
+        const p = payload;
+        if (Array.isArray(p.selectedValues)) {
+            return (correctAnswers.every((entry) => p.selectedValues.includes(entry)) &&
+                p.selectedValues.every((entry) => correctAnswers.includes(entry)));
+        }
+        if (typeof p.correct === "boolean")
+            return p.correct;
+    }
+    if (!correctAnswers.length)
+        return undefined;
+    if (typeof selected === "number" && Array.isArray(choices) && choices.length) {
+        return correctAnswers.some((entry) => String(entry) === String(choices[selected]));
+    }
+    if (typeof selected !== "undefined") {
+        return correctAnswers.some((entry) => String(entry) === String(selected));
+    }
+    return undefined;
+}
+/** @public */
+export function deriveNoiseContexts(trainingData) {
+    if (!trainingData)
+        return [];
+    if (Array.isArray(trainingData.items)) {
+        return trainingData.items.map((item) => {
+            const it = item;
+            return typeof item === "string"
+                ? { sentence: item }
+                : { sentence: (it.context || it.sentence || ""), contextCode: (it.contextCode || it.context_code) };
+        });
+    }
+    if (Array.isArray(trainingData.sentences)) {
+        return trainingData.sentences.map((sentence) => {
+            const s = sentence;
+            return typeof sentence === "string"
+                ? { sentence }
+                : { sentence: (s.sentence || s.context || ""), contextCode: s.contextCode };
+        });
+    }
+    if (Array.isArray(trainingData.contexts))
+        return trainingData.contexts;
+    if (trainingData.contextCode)
+        return [{ contextCode: trainingData.contextCode }];
+    return [];
+}
+/**
+ * @public "듣고 → 보기 카드 고르기" 두 단계짜리 훈련의 채점.
+ *
+ * 일치하는 단어 맞히기·한 음절 포함 단어 맞히기·첫 음절이 같은 단어 맞히기 셋이
+ * 한 글자도 다르지 않은 채점을 한 벌씩 들고 있었다. 정말 다른 것은 **결과지에 무엇을
+ * 문제로 적을 것인가** 하나뿐이라(들려준 낱말이냐, 음절이냐, 원본 낱말이냐), 그것만
+ * 밖에서 받는다.
+ *
+ * 정답은 answerIndex 가 있으면 보기에서 그 자리를 쓰고, 없으면 item.answer 를 쓴다.
+ *
+ * @param questionOf - 결과지의 '문제' 칸에 적을 것을 항목에서 뽑는다
+ */
+export function buildTwoStepPickResults(items = [], pageAnswers, questionOf) {
+    const results = items.map((raw, index) => {
+        const item = (raw ?? {});
+        const payload = getSteppedPayload(pageAnswers, index, 2, 1);
+        const selected = getSelectedFromPayload(payload);
+        const choices = (Array.isArray(item.choices) ? item.choices : []);
+        const selectedText = getSelectedText(selected, choices);
+        const answerIndex = typeof item.answerIndex === 'number' ? item.answerIndex : undefined;
+        const answer = typeof answerIndex === 'number' ? choices[answerIndex] : item.answer;
+        const correct = isSelectionCorrect({
+            payload, selected, choices, correctAnswers: answer ? [answer] : [],
+        });
+        return { question: questionOf(item), choices, selected, selectedText, correct, answer };
+    });
+    return { score: results.filter(r => r.correct).length, results, answers: results };
+}

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

@@ -0,0 +1,42 @@
+import type { ReactNode } from 'react';
+/**
+ * 훈련 시나리오를 **읽는 규칙** — 쪽·단계에 이름을 붙이고, 단계가 받을 props 를 푼다.
+ *
+ * TrainingPagePopup 이 1,023줄이고 그중 화면과 무관한 이 넷이 앞머리에 섞여 있었다.
+ * 넷 다 순수 함수다 — 리액트도, 상태도 모르고, 같은 입력에 늘 같은 값을 준다.
+ *
+ * 이름을 붙이는 두 함수가 중요한 이유: 여기서 나오는 문자열이 그대로 리스트의 key 가
+ * 된다. id 나 key 가 없으면 자리 번호로 대신하는데, 그러면 쪽·단계가 재배치될 때
+ * 리액트가 다른 것을 같은 것으로 보고 상태를 잘못 물려준다. 그래서 **주어진 이름이
+ * 있으면 반드시 그것을 쓴다**는 게 이 함수들의 약속이다.
+ */
+/** @public */
+export type ScenarioPage = {
+    id?: string;
+    steps?: ReactNode[];
+    pageTop?: ReactNode | null;
+    pageBottom?: ReactNode | null;
+} & Record<string, unknown>;
+/** @public */
+export type ScenarioStep = {
+    key?: string;
+    props?: ((context: Record<string, unknown>) => Record<string, unknown>) | Record<string, unknown>;
+    type?: string;
+} & Record<string, unknown>;
+/** @public 한 판(page)의 진행 상태 — 몇 쪽 몇 단계인지와, 쪽마다 담아 둔 답. */
+export type FlowState = {
+    pageIndex: number;
+    stepIndex: number;
+    answersByPage: Record<string, Record<string, unknown>>;
+};
+/** 쪽 이름 — 주어진 id 가 있으면 그것을, 없으면 자리 번호로. */
+export declare function getScenarioPageId(page: ScenarioPage | null | undefined, index?: number): string;
+/** 단계 이름 — 주어진 key 가 있으면 그것을, 없으면 자리 번호로. */
+export declare function getScenarioStepKey(step: ScenarioStep | null | undefined, index?: number): string;
+/** 처음 상태 — 첫 쪽 첫 단계, 담아 둔 답 없음. */
+export declare function createScenarioFlowState(): FlowState;
+/**
+ * 단계가 받을 props 를 푼다. 함수로 주어졌으면 그때의 문맥을 넘겨 부른다 —
+ * 앞 단계의 답에 따라 달라지는 단계를 그렇게 쓴다. 무엇을 주든 객체를 돌려준다.
+ */
+export declare function resolveScenarioStepProps(step: ScenarioStep | null | undefined, context: Record<string, unknown>): Record<string, unknown>;

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

@@ -0,0 +1,25 @@
+/** 쪽 이름 — 주어진 id 가 있으면 그것을, 없으면 자리 번호로. */
+export function getScenarioPageId(page, index) {
+    return (page && page.id) || `page-${index ?? 0}`;
+}
+/** 단계 이름 — 주어진 key 가 있으면 그것을, 없으면 자리 번호로. */
+export function getScenarioStepKey(step, index) {
+    return (step && step.key) || `step-${index ?? 0}`;
+}
+/** 처음 상태 — 첫 쪽 첫 단계, 담아 둔 답 없음. */
+export function createScenarioFlowState() {
+    return {
+        pageIndex: 0,
+        stepIndex: 0,
+        answersByPage: {},
+    };
+}
+/**
+ * 단계가 받을 props 를 푼다. 함수로 주어졌으면 그때의 문맥을 넘겨 부른다 —
+ * 앞 단계의 답에 따라 달라지는 단계를 그렇게 쓴다. 무엇을 주든 객체를 돌려준다.
+ */
+export function resolveScenarioStepProps(step, context) {
+    if (typeof step?.props === 'function')
+        return step.props(context) || {};
+    return step?.props || {};
+}

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

@@ -0,0 +1,37 @@
+import type { ReactNode } from 'react';
+/** @public */
+export type SoundSource = string | {
+    src?: string;
+    code?: string;
+} | null;
+export interface Source {
+    code?: string | number | null | undefined;
+    src?: string | null;
+    objectUrl?: string | null;
+    duration?: number;
+    resolvedPath?: string;
+}
+export interface Segment {
+    src?: string | null;
+    label?: string;
+    color?: string | undefined;
+    duration?: number;
+}
+export type FetchDebugStatus = 'idle' | 'resolving' | 'checking_exists' | 'getting_signed_url' | 'downloading' | 'measuring_duration' | 'ready' | 'error';
+/** @public */
+export interface TrainingStepAudioPlayerProps {
+    btnLabel?: ReactNode;
+    soundSrc?: SoundSource | SoundSource[];
+    bucketPath?: string | null;
+    onDone?: (ok?: boolean) => void;
+    disabled?: boolean;
+    ttsText?: string | string[] | null;
+    className?: string;
+    /** 문장(재생 소리) waveform 표시 여부. 기본 true — 두 소리를 비교해 같음/다름을 판단하는
+     *  훈련처럼 waveform 모양으로 답이 드러나면 안 되는 화면에서는 false로 끈다. */
+    showSoundWaveForm?: boolean;
+    /** 소음 waveform 표시 여부. 기본 true. */
+    showNoiseWaveForm?: boolean;
+}
+export declare const STATUS_MESSAGES: Record<FetchDebugStatus, string>;
+export declare const STATUS_COLORS: Record<FetchDebugStatus, string>;

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

@@ -0,0 +1,20 @@
+export const STATUS_MESSAGES = {
+    idle: '대기',
+    resolving: '리소스 매핑 중…',
+    checking_exists: '파일 존재 확인…',
+    getting_signed_url: '서명 URL 조회…',
+    downloading: '다운로드 중…',
+    measuring_duration: '오디오 길이 측정…',
+    ready: '준비 완료',
+    error: '오류 발생',
+};
+export const STATUS_COLORS = {
+    idle: '#757575',
+    resolving: '#1e90ff',
+    checking_exists: '#1e90ff',
+    getting_signed_url: '#1e90ff',
+    downloading: '#ff9800',
+    measuring_duration: '#9c27b0',
+    ready: '#4caf50',
+    error: '#f44336',
+};

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

@@ -0,0 +1,34 @@
+/**
+ * trainingStepOrderListTypes.ts
+ * TrainingStepOrderList의 순수 타입 정의.
+ */
+/** @public */
+export type TrainingContextItem = string | {
+    context?: string;
+    sentence?: string;
+    question?: string;
+    [key: string]: unknown;
+};
+/** @public */
+export type ShuffledItem = {
+    id: number;
+    text: string;
+};
+/** @public */
+export interface ChangeResult {
+    shuffled: ShuffledItem[];
+    score: number;
+    total: number;
+    initial?: boolean;
+    __ts: number;
+}
+/** @public */
+export interface TrainingStepOrderListProps {
+    index?: number;
+    stepIndex?: number;
+    isLast?: boolean;
+    title?: string;
+    onDone?: (res: ChangeResult) => void;
+    onChange?: (res: ChangeResult) => void;
+    context?: TrainingContextItem[];
+}

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

@@ -0,0 +1,5 @@
+/**
+ * trainingStepOrderListTypes.ts
+ * TrainingStepOrderList의 순수 타입 정의.
+ */
+export {};