npm - @ihabdevteam/core - Versions diffs - 0.8.0 - Mend

@ihabdevteam/core 0.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (848) hide show

package/dist/packages/core/src/utils/theme.d.ts ADDED Viewed

@@ -0,0 +1,11 @@
+/**
+ * 테마 유틸리티
+ * - 'light' | 'dark' | 'auto'
+ * - localStorage 키: 'ihab_theme'
+ * - 적용: <html data-theme="light|dark|auto">
+ */
+export type ThemeMode = 'light' | 'dark' | 'auto';
+export declare function getSavedTheme(): ThemeMode;
+export declare function applyTheme(mode: ThemeMode): void;
+/** 앱 시작 시 저장된 테마 즉시 적용 */
+export declare function initTheme(): void;

package/dist/packages/core/src/utils/theme.js ADDED Viewed

@@ -0,0 +1,28 @@
+/**
+ * 테마 유틸리티
+ * - 'light' | 'dark' | 'auto'
+ * - localStorage 키: 'ihab_theme'
+ * - 적용: <html data-theme="light|dark|auto">
+ */
+const STORAGE_KEY = 'ihab_theme';
+const DEFAULT_THEME = 'light';
+export function getSavedTheme() {
+    try {
+        const saved = localStorage.getItem(STORAGE_KEY);
+        if (saved === 'light' || saved === 'dark' || saved === 'auto')
+            return saved;
+    }
+    catch { }
+    return DEFAULT_THEME;
+}
+export function applyTheme(mode) {
+    try {
+        document.documentElement.setAttribute('data-theme', mode);
+        localStorage.setItem(STORAGE_KEY, mode);
+    }
+    catch { }
+}
+/** 앱 시작 시 저장된 테마 즉시 적용 */
+export function initTheme() {
+    applyTheme(getSavedTheme());
+}

package/dist/packages/core/src/utils/trainingItemResults.d.ts ADDED Viewed

@@ -0,0 +1,60 @@
+/**
+ * 훈련 한 판의 **문항 하나하나**를 기록할 수 있는 모양으로 추린다.
+ *
+ * 08-26 회의에서 치료사가 "음소별 오류를 보고 싶다"고 했다. 그러려면 어느 낱말을
+ * 틀렸는지가 남아야 하는데, 지금은 안 남는다 — `customer_training_result` 의
+ * `item_id`·`item_title` 이 전부 null 이다.
+ *
+ * 정보가 없어서가 아니다. 훈련이 끝나는 순간 화면은 문항마다
+ * `{ question, choices, selected, selectedText, correct, answer }` 를 들고 있다
+ * (trainingPopupUtils 의 build*Results). 그걸 `correct/total` 두 숫자로 접어서 버리고
+ * 있었다. 접기 전에 한 번 추려 둔다.
+ *
+ * **음소를 여기서 뽑지 않는다.** 낱말을 남기는 것과 그 낱말에서 음소를 세는 것은 다른
+ * 일이고, 뒤엣것은 아직 규칙이 정해지지 않았다(어두/어중/어말 위치 모델도 바뀌는 중이다).
+ * 지금 섣불리 음소를 박아 두면, 규칙이 바뀔 때 이미 쌓인 기록이 옛 규칙으로 남는다.
+ * 낱말은 사실이고 음소는 해석이다 — 사실만 남긴다.
+ */
+/** @public 훈련 한 문항의 결과 — 서버에 남길 만큼만 추린 것 */
+export interface TrainingItemResult {
+    /** 몇 번째 문항인가(0부터) — 같은 낱말이 두 번 나와도 구별된다 */
+    index: number;
+    /**
+     * 이 문항의 **식별자** — 글자가 아니라 코드다.
+     *
+     * 글자만 남기면 그 문항을 되찾는 길이 글자 맞춰 보기뿐이다. 같은 문장이 여러 세트에
+     * 들어 있거나 지문이 한 글자 고쳐지면 곧바로 어긋난다 — 그걸로 다음 훈련을 짜면
+     * 엉뚱한 것이 담긴다. 훈련 데이터가 문항마다 들고 있는 코드(`contextCode`)를 그대로 남긴다.
+     *
+     * 코드가 없는 유형도 있다(낱말 훈련은 낱말 자체가 식별자다). 그때는 `null` 이고,
+     * 부르는 쪽은 `question` 으로 갈음한다 — **없는 것을 지어내지 않는다.**
+     */
+    itemId: string | null;
+    /** 무엇을 물었나 — 낱말·음절이거나 문장. 음소는 여기서 뽑지 않는다 */
+    question: string | null;
+    /** 정답 */
+    answer: string | null;
+    /** 고른 것 — 안 골랐으면 null */
+    selected: string | null;
+    /** 맞았나. 정오답 개념이 없는 유형이면 null */
+    correct: boolean | null;
+}
+/** 문항 결과 배열이 들고 있을 법한 모양 — 훈련 유형마다 조금씩 다르다 */
+type RawResult = Record<string, unknown>;
+/**
+ * 맞았는지 — 훈련 유형마다 칸 이름이 다르다.
+ *
+ * 소음 하 듣기·문장 순서화는 `correct` 대신 `heard`·`judgement` 를 채운다
+ * (TrainingPagePopup 이 정답 수를 셀 때 쓰는 기준과 같아야 한다 — 여기가 다르면 한
+ * 화면에서 '정답 3개'라 해 놓고 문항 넷이 맞았다고 남는다).
+ */
+export declare function itemCorrectness(r: RawResult): boolean | null;
+/** @public 화면이 들고 있는 문항 결과 배열을 기록용으로 추린다 */
+export declare function toItemResults(raw: unknown): TrainingItemResult[];
+/**
+ * @public 틀린 문항만 — 음소별 오류를 세는 쪽이 먼저 볼 것이다.
+ *
+ * '아직 안 푼 것'(correct === null)은 틀린 것이 아니다. 섞으면 오류율이 부풀려진다.
+ */
+export declare function wrongItems(items: readonly TrainingItemResult[]): TrainingItemResult[];
+export {};

package/dist/packages/core/src/utils/trainingItemResults.js ADDED Viewed

@@ -0,0 +1,72 @@
+/**
+ * 훈련 한 판의 **문항 하나하나**를 기록할 수 있는 모양으로 추린다.
+ *
+ * 08-26 회의에서 치료사가 "음소별 오류를 보고 싶다"고 했다. 그러려면 어느 낱말을
+ * 틀렸는지가 남아야 하는데, 지금은 안 남는다 — `customer_training_result` 의
+ * `item_id`·`item_title` 이 전부 null 이다.
+ *
+ * 정보가 없어서가 아니다. 훈련이 끝나는 순간 화면은 문항마다
+ * `{ question, choices, selected, selectedText, correct, answer }` 를 들고 있다
+ * (trainingPopupUtils 의 build*Results). 그걸 `correct/total` 두 숫자로 접어서 버리고
+ * 있었다. 접기 전에 한 번 추려 둔다.
+ *
+ * **음소를 여기서 뽑지 않는다.** 낱말을 남기는 것과 그 낱말에서 음소를 세는 것은 다른
+ * 일이고, 뒤엣것은 아직 규칙이 정해지지 않았다(어두/어중/어말 위치 모델도 바뀌는 중이다).
+ * 지금 섣불리 음소를 박아 두면, 규칙이 바뀔 때 이미 쌓인 기록이 옛 규칙으로 남는다.
+ * 낱말은 사실이고 음소는 해석이다 — 사실만 남긴다.
+ */
+/** 사람이 읽을 수 있는 글자만 남긴다. 객체·빈 문자열은 없는 것으로 본다 */
+function text(v) {
+    if (typeof v === 'string')
+        return v.trim() || null;
+    if (typeof v === 'number')
+        return String(v);
+    return null;
+}
+/**
+ * 맞았는지 — 훈련 유형마다 칸 이름이 다르다.
+ *
+ * 소음 하 듣기·문장 순서화는 `correct` 대신 `heard`·`judgement` 를 채운다
+ * (TrainingPagePopup 이 정답 수를 셀 때 쓰는 기준과 같아야 한다 — 여기가 다르면 한
+ * 화면에서 '정답 3개'라 해 놓고 문항 넷이 맞았다고 남는다).
+ */
+export function itemCorrectness(r) {
+    for (const k of ['correct', 'isCorrect', 'heard', 'judgement']) {
+        if (typeof r[k] === 'boolean')
+            return r[k];
+    }
+    if (r.score === 1)
+        return true;
+    if (r.score === 0)
+        return false;
+    return null;
+}
+/** @public 화면이 들고 있는 문항 결과 배열을 기록용으로 추린다 */
+export function toItemResults(raw) {
+    if (!Array.isArray(raw))
+        return [];
+    return raw.map((v, index) => {
+        const r = (v ?? {});
+        return {
+            index,
+            /* 문항 코드가 담긴 칸 이름도 유형마다 다르다. 훈련 데이터의 문장 항목은
+               `contextCode` 를 쓴다(`{index, contextCode, context}`). */
+            itemId: text(r.contextCode) ?? text(r.itemId) ?? text(r.itemCode) ?? text(r.id),
+            /* 물음이 담긴 칸 이름이 유형마다 다르다 — 문장 훈련 넷(소음 하 듣기·문장 순서화·
+               짧은/긴 이야기)은 `sentence` 에, 낱말 훈련은 `word` 에 담는다. `sentence` 를
+               빠뜨렸더니 대면 세션 기록의 item_id 가 전부 null 이었다(2026-08-27 실측). */
+            question: text(r.question) ?? text(r.sentence) ?? text(r.word) ?? text(r.targetSyllable),
+            answer: text(r.answer),
+            selected: text(r.selectedText) ?? text(r.selected),
+            correct: itemCorrectness(r),
+        };
+    });
+}
+/**
+ * @public 틀린 문항만 — 음소별 오류를 세는 쪽이 먼저 볼 것이다.
+ *
+ * '아직 안 푼 것'(correct === null)은 틀린 것이 아니다. 섞으면 오류율이 부풀려진다.
+ */
+export function wrongItems(items) {
+    return items.filter(i => i.correct === false);
+}

package/dist/packages/core/src/utils/trainingLogger.d.ts ADDED Viewed

@@ -0,0 +1,58 @@
+/**
+ * 훈련 시간/게임 기록 로거 — TTS/Storage 리졸버와 동일한 전역 주입 패턴.
+ * 앱(src)에서 set*Logger 로 Supabase RPC 콜백을 등록하면
+ * core 컴포넌트들이 fire-and-forget 으로 호출합니다.
+ */
+/** @public */
+export interface TrainingTimeLogEntry {
+    /** LISTEN_IN_NOISE | SHORT_STORY | LONG_STORY | ORDERING_SENTENCE 등 */
+    trainingType: string;
+    startedAt: string;
+    endedAt: string;
+}
+/** @public */
+export interface CrosswordLogEntry {
+    crosswordIdx: number;
+    cleared: boolean;
+    startedAt: string;
+    endedAt: string;
+}
+/** @public 훈련 항목 완료 정본 기록 — 문장/단어/오늘의 듣기 공통 */
+import type { TrainingItemResult } from './trainingItemResults';
+export interface TrainingCompletionEntry {
+    category: 'sentence' | 'word';
+    trainingType: string;
+    /** 'daily'(오늘의 듣기) | 'sentence' | 'word' */
+    entryPoint: string;
+    itemRef?: string | null;
+    correct?: number | null;
+    total?: number | null;
+    score?: number | null;
+    durationSeconds?: number | null;
+    /** entry_point='daily'일 때 그날 전체 항목 수(완료율 분모) */
+    dailyTotal?: number | null;
+    /**
+     * 문항 하나하나의 결과 — 어느 낱말을 틀렸는지.
+     *
+     * 08-26 회의의 '음소별 오류'가 이걸 원재료로 쓴다. 한때 correct/total 두 숫자로 접어
+     * 버렸는데, 접고 나면 어느 낱말이었는지 되찾을 길이 없다. 음소는 여기서 뽑지 않는다 —
+     * 낱말은 사실이고 음소는 해석이라, 해석 규칙이 바뀌면 다시 세면 된다.
+     */
+    items?: TrainingItemResult[] | null;
+}
+type TrainingTimeLogger = (entry: TrainingTimeLogEntry) => Promise<void> | void;
+type CrosswordLogger = (entry: CrosswordLogEntry) => Promise<void> | void;
+type TrainingCompletionLogger = (entry: TrainingCompletionEntry) => Promise<void> | void;
+/** @public */
+export declare function setTrainingTimeLogger(fn: TrainingTimeLogger | null): void;
+/** @public */
+export declare function logTrainingTime(entry: TrainingTimeLogEntry): void;
+/** @public */
+export declare function setTrainingCompletionLogger(fn: TrainingCompletionLogger | null): void;
+/** @public */
+export declare function logTrainingCompletion(entry: TrainingCompletionEntry): void;
+/** @public */
+export declare function setCrosswordLogger(fn: CrosswordLogger | null): void;
+/** @public */
+export declare function logCrossword(entry: CrosswordLogEntry): void;
+export {};

package/dist/packages/core/src/utils/trainingLogger.js ADDED Viewed

@@ -0,0 +1,50 @@
+/**
+ * 훈련 시간/게임 기록 로거 — TTS/Storage 리졸버와 동일한 전역 주입 패턴.
+ * 앱(src)에서 set*Logger 로 Supabase RPC 콜백을 등록하면
+ * core 컴포넌트들이 fire-and-forget 으로 호출합니다.
+ */
+const g = globalThis;
+/**
+ * 로거 호출을 감싼다 — 등록된 로거는 대개 async(Supabase RPC)다.
+ *
+ * try/catch 만으로는 **동기 예외만** 잡힌다. `void fn()` 으로 던진 프라미스가 reject 하면
+ * unhandled rejection 이 되고, 앱의 errorReporter 가 그걸 후킹해 실제 크래시처럼 보고한다.
+ * 훈련 시간 기록은 세션이 끝날 때마다 나가므로 네트워크가 불안정하면 오류 보고가 이걸로
+ * 뒤덮인다 — 정작 훈련 자체는 멀쩡한데도. fire-and-forget 은 여기서 닫는다.
+ */
+function runLogger(name, call) {
+    const warn = (e) => { if (import.meta.env?.DEV)
+        console.warn(`[trainingLogger:${name}]`, e); };
+    try {
+        const r = call();
+        if (r && typeof r.catch === 'function')
+            r.catch(warn);
+    }
+    catch (e) {
+        warn(e);
+    }
+}
+/** @public */
+export function setTrainingTimeLogger(fn) {
+    g.__ihabTrainingTimeLogger = fn;
+}
+/** @public */
+export function logTrainingTime(entry) {
+    runLogger('time', () => g.__ihabTrainingTimeLogger?.(entry));
+}
+/** @public */
+export function setTrainingCompletionLogger(fn) {
+    g.__ihabTrainingCompletionLogger = fn;
+}
+/** @public */
+export function logTrainingCompletion(entry) {
+    runLogger('completion', () => g.__ihabTrainingCompletionLogger?.(entry));
+}
+/** @public */
+export function setCrosswordLogger(fn) {
+    g.__ihabCrosswordLogger = fn;
+}
+/** @public */
+export function logCrossword(entry) {
+    runLogger('crossword', () => g.__ihabCrosswordLogger?.(entry));
+}

package/dist/packages/core/src/utils/trainingPalette.d.ts ADDED Viewed

@@ -0,0 +1,12 @@
+/**
+ * 훈련 통계·단어훈련 차트에서 공용으로 쓰는 5색 팔레트 (단일 소스).
+ * 이전에는 TrainingStatusPage / WordTrainingPage 등에 동일 hex가 흩어져 중복 정의됨.
+ * 색을 바꿀 땐 이 한 곳만 수정한다.
+ */
+export declare const TRAINING_PALETTE: {
+    readonly blue: "#60A5FA";
+    readonly green: "#4ADE80";
+    readonly amber: "#FBBF24";
+    readonly purple: "#A78BFA";
+    readonly pink: "#F472B6";
+};

package/dist/packages/core/src/utils/trainingPalette.js ADDED Viewed

@@ -0,0 +1,12 @@
+/**
+ * 훈련 통계·단어훈련 차트에서 공용으로 쓰는 5색 팔레트 (단일 소스).
+ * 이전에는 TrainingStatusPage / WordTrainingPage 등에 동일 hex가 흩어져 중복 정의됨.
+ * 색을 바꿀 땐 이 한 곳만 수정한다.
+ */
+export const TRAINING_PALETTE = {
+    blue: '#60A5FA',
+    green: '#4ADE80',
+    amber: '#FBBF24',
+    purple: '#A78BFA',
+    pink: '#F472B6',
+};

package/dist/packages/core/src/utils/ttsConfig.d.ts ADDED Viewed

@@ -0,0 +1,78 @@
+/**
+ * TTS URL 리졸버 설정
+ *
+ * 소비 앱에서 configureTTS()로 리졸버를 한 번 등록하면,
+ * TrainingStepAudioPlayer가 TTS 텍스트를 오디오 URL로 변환하여
+ * 일반 오디오 소스와 동일하게 waveform을 표시합니다.
+ *
+ * globalThis를 싱글톤 저장소로 사용합니다.
+ * rollup이 각 entry point마다 별도 번들을 생성해도
+ * 동일한 전역 객체를 통해 설정이 공유됩니다.
+ *
+ * @example
+ * ```ts
+ * // App.tsx 또는 supabaseClient.ts 초기화 시점
+ * import { configureTTS } from '\@ihabdevteam/core/utils';
+ * import { getTTSUrl } from '\@libs/ttsUrl';
+ *
+ * configureTTS({ urlResolver: (text) => getTTSUrl(text) });
+ * ```
+ *
+ * @public
+ */
+export interface TTSConfig {
+    /**
+     * TTS 텍스트를 오디오 URL로 변환하는 함수.
+     * 동기(string) 또는 비동기(Promise<string>) 모두 지원합니다.
+     *
+     * @param text - 발음할 텍스트
+     * @returns 오디오 파일 URL
+     */
+    urlResolver: (text: string) => string | Promise<string>;
+    /**
+     * (선택) 정식 음원이 없어 재생에 실패했을 때의 폴백 — 재생 가능한 오디오 URL을 만들어 반환합니다.
+     * 미등록이거나 빈 문자열을 반환하면 브라우저 기본 speechSynthesis로 최종 폴백합니다.
+     *
+     * 앱에서 런타임 TTS 합성(예: Gemini-TTS Edge Function)을 붙이는 자리입니다 — core는
+     * 합성 수단을 알 필요 없이 "폴백 URL을 얻는다"는 계약만 가집니다.
+     *
+     * @param text - 발음할 텍스트
+     * @returns 오디오 파일 URL (없으면 '')
+     */
+    fallbackUrlResolver?: (text: string) => string | Promise<string>;
+}
+declare global {
+    var __ihab_core_tts_config__: TTSConfig | undefined;
+}
+/**
+ * TTS URL 리졸버를 전역으로 설정합니다.
+ * @public
+ */
+export declare function configureTTS(config: TTSConfig): void;
+/**
+ * 설정된 TTS URL 리졸버를 반환합니다.
+ * @public
+ */
+export declare function getTTSUrlResolver(): ((text: string) => string | Promise<string>) | null;
+/**
+ * 설정된 TTS 폴백 URL 리졸버를 반환합니다(미등록이면 null).
+ * 정식 음원 재생이 실패했을 때만 쓰입니다.
+ * @public
+ */
+export declare function getTTSFallbackUrlResolver(): ((text: string) => string | Promise<string>) | null;
+/**
+ * 음원 존재 확인 캐시를 비운다.
+ * @public
+ *
+ * 단어 데이터를 새로 받거나 음원을 새로 만든 뒤에 부른다 — 이미지·대립쌍 인덱스와
+ * 같은 자리(앱의 invalidateCaches)에서 함께 비워야, 방금 만든 음원이 '음성 없음'으로
+ * 남지 않는다.
+ */
+export declare function clearAudioExistsCache(): void;
+/**
+ * 단어의 오디오 파일이 실제로 존재하는지 확인합니다.
+ * TTS URL 리졸버가 반환하는 URL로 HEAD 요청을 보냅니다.
+ * 결과는 내부적으로 캐싱됩니다.
+ * @public
+ */
+export declare function checkAudioExists(word: string): Promise<boolean>;

package/dist/packages/core/src/utils/ttsConfig.js ADDED Viewed

@@ -0,0 +1,89 @@
+/**
+ * TTS URL 리졸버 설정
+ *
+ * 소비 앱에서 configureTTS()로 리졸버를 한 번 등록하면,
+ * TrainingStepAudioPlayer가 TTS 텍스트를 오디오 URL로 변환하여
+ * 일반 오디오 소스와 동일하게 waveform을 표시합니다.
+ *
+ * globalThis를 싱글톤 저장소로 사용합니다.
+ * rollup이 각 entry point마다 별도 번들을 생성해도
+ * 동일한 전역 객체를 통해 설정이 공유됩니다.
+ *
+ * @example
+ * ```ts
+ * // App.tsx 또는 supabaseClient.ts 초기화 시점
+ * import { configureTTS } from '\@ihabdevteam/core/utils';
+ * import { getTTSUrl } from '\@libs/ttsUrl';
+ *
+ * configureTTS({ urlResolver: (text) => getTTSUrl(text) });
+ * ```
+ *
+ * @public
+ */
+const GLOBAL_KEY = '__ihab_core_tts_config__';
+/**
+ * TTS URL 리졸버를 전역으로 설정합니다.
+ * @public
+ */
+export function configureTTS(config) {
+    globalThis[GLOBAL_KEY] = config;
+}
+/**
+ * 설정된 TTS URL 리졸버를 반환합니다.
+ * @public
+ */
+export function getTTSUrlResolver() {
+    return globalThis[GLOBAL_KEY]?.urlResolver ?? null;
+}
+/**
+ * 설정된 TTS 폴백 URL 리졸버를 반환합니다(미등록이면 null).
+ * 정식 음원 재생이 실패했을 때만 쓰입니다.
+ * @public
+ */
+export function getTTSFallbackUrlResolver() {
+    return globalThis[GLOBAL_KEY]?.fallbackUrlResolver ?? null;
+}
+const audioExistsCache = new Map();
+/**
+ * 음원 존재 확인 캐시를 비운다.
+ * @public
+ *
+ * 단어 데이터를 새로 받거나 음원을 새로 만든 뒤에 부른다 — 이미지·대립쌍 인덱스와
+ * 같은 자리(앱의 invalidateCaches)에서 함께 비워야, 방금 만든 음원이 '음성 없음'으로
+ * 남지 않는다.
+ */
+export function clearAudioExistsCache() {
+    audioExistsCache.clear();
+}
+/**
+ * 단어의 오디오 파일이 실제로 존재하는지 확인합니다.
+ * TTS URL 리졸버가 반환하는 URL로 HEAD 요청을 보냅니다.
+ * 결과는 내부적으로 캐싱됩니다.
+ * @public
+ */
+export async function checkAudioExists(word) {
+    const resolver = getTTSUrlResolver();
+    if (!resolver)
+        return false;
+    // resolver(word) 를 Promise.resolve() 안에서 부른다. 밖에서 부르면 동기적으로 던지는
+    // 리졸버의 예외가 .catch() 에 닿기 전에 새어 나가, 이 확인을 기다리는 '음성 있음'
+    // 필터가 통째로 깨진다(비동기 거절만 잡히던 상태였다).
+    const url = await Promise.resolve().then(() => resolver(word)).catch(() => '');
+    if (!url)
+        return false;
+    if (audioExistsCache.has(url))
+        return audioExistsCache.get(url);
+    // 타임아웃 없으면 HEAD 요청 하나가 응답 없이 걸릴 때 이 확인을 기다리는
+    // 검색 버튼(음성 있음 필터)이 영구 비활성화된다
+    // 서버가 답을 준 경우(200/404)만 캐시에 남긴다. 네트워크 실패·타임아웃까지 캐시하면
+    // 한 번의 통신 끊김이 그 단어를 세션 내내 '음성 없음'으로 고정해, '음성 있음' 필터에서
+    // 통째로 빠진다. 실패는 지워서 다음 호출이 다시 물어보게 한다.
+    const promise = fetch(url, { method: 'HEAD', signal: AbortSignal.timeout(8000) })
+        .then(res => res.ok)
+        .catch(() => {
+        audioExistsCache.delete(url);
+        return false;
+    });
+    audioExistsCache.set(url, promise);
+    return promise;
+}

package/dist/packages/core/src/utils/ttsResolver.d.ts ADDED Viewed

@@ -0,0 +1,17 @@
+/** @public */
+export interface CreateTTSResolverOptions {
+    storagePrefix?: string;
+    voice?: string;
+    speed?: number;
+    pitch?: number;
+    /** Optional function to generate/upload TTS audio when missing. Should return a public URL when done. */
+    generator?: (text: string, destPath: string, opts?: CreateTTSResolverOptions) => Promise<string | null>;
+    filenameSanitizer?: (text: string) => string;
+}
+/**
+ * Create a TTS URL resolver that first checks storage, and if missing
+ * invokes a generator (or falls back to /api/tts) to create the file.
+ *
+ * @public
+ */
+export declare function createTTSUrlResolver(opts?: CreateTTSResolverOptions): (text: string) => Promise<string>;

package/dist/packages/core/src/utils/ttsResolver.js ADDED Viewed

@@ -0,0 +1,56 @@
+import { fileExists, getSignedOrPublicUrl } from './storage';
+import { toStorageName } from './encoding';
+/**
+ * Create a TTS URL resolver that first checks storage, and if missing
+ * invokes a generator (or falls back to /api/tts) to create the file.
+ *
+ * @public
+ */
+export function createTTSUrlResolver(opts = {}) {
+    const storagePrefix = opts.storagePrefix ?? 'audio-cache';
+    const voice = opts.voice ?? 'ko-f';
+    const speed = typeof opts.speed === 'number' ? opts.speed : 1.0;
+    const sanitize = opts.filenameSanitizer ?? toStorageName;
+    return async function ttsResolver(text) {
+        const t = String(text || '').trim();
+        if (!t)
+            return '';
+        const safe = sanitize(t);
+        const filename = `${safe}_${voice}.mp3`;
+        const filePath = `${storagePrefix}/${filename}`;
+        // 1) If storage resolvers are configured and file exists, return signed/public URL
+        try {
+            if (await fileExists(filePath)) {
+                const url = await getSignedOrPublicUrl(filePath);
+                if (url)
+                    return url;
+            }
+        }
+        catch (e) {
+            // Storage might not be configured — fall through to generator
+        }
+        // 2) Try app-provided generator callback
+        if (opts.generator) {
+            try {
+                const gen = await opts.generator(t, filePath, opts);
+                if (gen)
+                    return gen;
+            }
+            catch (e) {
+                // ignore generator error and fallback
+            }
+        }
+        // 3) Fallback: call /api/tts (dev middleware) to create file under public/audio-cache
+        //    then return the static path. This works for the included dev middleware.
+        try {
+            const apiUrl = `/api/tts?word=${encodeURIComponent(t)}&voice=${encodeURIComponent(voice)}&speed=${encodeURIComponent(String(speed))}`;
+            // trigger generation on server; we don't strictly need response body
+            await fetch(apiUrl, { method: 'GET' });
+            return `/audio-cache/${filename}`;
+        }
+        catch (e) {
+            // As a last resort, return the expected static path — caller may still try to fetch it.
+            return `/audio-cache/${filename}`;
+        }
+    };
+}

package/dist/packages/core/src/utils/wordContrast.d.ts ADDED Viewed

@@ -0,0 +1,54 @@
+/**
+ * 대립(오답) 엔진 — 단어훈련 런타임과 훈련/단어표 만들기(프리뷰)가 공유하는 공용 로직.
+ *
+ * 핵심 원칙: 대립 비교는 항상 '표준발음' 기준(호출부가 pronOf/발음 분해를 제공).
+ * - minimalPairDistractors: 발음 기반 pairIndex에서 최소대립쌍 오답 후보.
+ * - filterContrastCandidates: 후보군에서 okSet·동음이의어·구조대립을 제외하는 공용 필터.
+ * - buildMultiPartPosContrast: 초성/모음/종성 선택 시 '선택 위치 대립' 오답 사전계산.
+ */
+import { parseSyllable } from './koreanSyllable';
+import type { CompositionFilter } from './wordTrainingRuntimeTypes';
+import type { PairIndex } from './wordPairIndex';
+type Decomp = (ReturnType<typeof parseSyllable>)[];
+/** 선택 값(단일/배열)이 실제로 지정됐는지 */
+export declare const hasSel: (v: string | string[] | null | undefined) => boolean;
+/**
+ * 두 (표준발음) 분해배열 A·B가 '음절 구조'에서 달라지는 자리가 있는지.
+ * 초성 ㅇ(무음)은 '초성 없음', 종성 0은 '받침 없음'(둘 다 구조상 '비움')으로 본다.
+ * 어떤 자리에서 초성 ㅇ 유무 또는 받침 유무가 뒤바뀌면, 자음 '교체'가 아니라 음절 '구조' 차이이므로
+ * 청각 변별 오답으로 부적절 → true(제외 대상). 자음↔자음, 모음↔모음 교체는 false.
+ */
+export declare function hasStructureContrast(A: Decomp, B: Decomp): boolean;
+/** 표준발음 기준 오답 필터에 필요한 의존성 */
+export interface ContrastFilterOpts {
+    /** 허용 단어 집합(이미지 필터 등). 없거나 null이면 전체 허용. */
+    okSet?: Set<string> | null;
+    /** 단어 → 표준발음. */
+    pronOf: (w: string) => string;
+    /** 표준발음 문자열 → 음절 분해(캐시 권장). sameStructureOnly일 때만 필요. */
+    decompOf?: (pron: string) => Decomp;
+    /** true면 구조 대립(초성 ㅇ 유무·받침 유무)도 제외(decompOf 필요). */
+    sameStructureOnly?: boolean;
+}
+/**
+ * 후보군에서 정답 대비 (a) okSet 밖, (b) 발음 동음이의어, (c) 구조 대립을 제외.
+ * 비교는 전부 표준발음 기준.
+ */
+export declare function filterContrastCandidates(answer: string, candidates: Iterable<string>, opts: ContrastFilterOpts): string[];
+/**
+ * 최소대립쌍 오답 — 발음 기반 pairIndex에서 정답의 대립쌍을 가져와 공용 필터 적용.
+ * kind 지정 시 그 종류(cho/jung/jong)만, 없으면 전 종류.
+ */
+export declare function minimalPairDistractors(answer: string, pairIndex: PairIndex | null, opts: ContrastFilterOpts & {
+    kind?: 'cho' | 'jung' | 'jong';
+}): string[];
+/**
+ * 다중 파트(초성+모음/종성 선택) 위치 대립 오답을 전체 풀에서 완전·고속으로 사전계산.
+ * 선택 파트가 여럿이면 '같은 음절'에서 결합해 하나의 패턴으로 본다(초성ㄱ+ㅏ+종성ㄱ = '각') —
+ * 정답은 그 패턴 음절이 든 단어, 오답은 그 자리에서 선택한 모든 파트가 다르고(선택 음소가 하나도
+ * 안 남음) 나머지 발음은 전부 같은 단어. 같은 (발음)음절수·같은 패턴 위치끼리 묶어 마스킹 템플릿
+ * 인덱스를 1회 구성하고 O(1) 조회한다. 비교는 표준발음 분해로. 패턴 음절 탐색은 발음입력=발음 /
+ * 글자입력=철자. 반환: 정답 단어 → 위치 대립 오답 목록.
+ */
+export declare function buildMultiPartPosContrast(composition: CompositionFilter, okArr: string[], decomp: (w: string) => Decomp, sameStructureOnly: boolean, phonemeView: 'char' | 'pron', pronOf: (w: string) => string, position?: 'head' | 'mid' | 'tail' | null): Map<string, string[]>;
+export {};