@ihabdevteam/core 0.8.0

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

@@ -0,0 +1,61 @@
+/** 요금제 티어 */
+export type PlanTier = 'none' | 'free' | 'personal_standard' | 'mgr_free' | 'lite_word' | 'lite_sentence' | 'lite' | 'standard' | 'pro' | 'enterprise';
+export type DataLevel = 0 | 1 | 2 | 3;
+export interface PlanFeatures {
+    maxCustomers: number;
+    visitWord: boolean;
+    visitSentence: boolean;
+    homework: boolean;
+    customerStats: boolean;
+    managerCustomerSplit: boolean;
+    managerManagement: boolean;
+    sentenceTrainingSetting: boolean;
+    wordTrainingSetting: boolean;
+    myWordList: boolean;
+    wordListShare: boolean;
+    groupTrainingSetting: boolean;
+    minimalPairSearch: boolean;
+    wordTableSetting: boolean;
+    wordTablePrint: boolean;
+    addToMyList: boolean;
+    addToGroupList: boolean;
+    wordSearch: boolean;
+    wordSearchPrint: boolean;
+    wordSearchAddToMyList: boolean;
+    wordSearchAddToGroupList: boolean;
+    wordDataLevel: DataLevel;
+    sentenceDataLevel: DataLevel;
+    crossword: boolean;
+    crosswordMid: boolean;
+    crosswordHigh: boolean;
+    wordTrainingView: boolean;
+    sentenceTrainingView: boolean;
+}
+export declare const PLAN_FEATURES: Record<PlanTier, PlanFeatures>;
+/** 요금제 티어 순위 (높을수록 상위 요금제) */
+export declare const TIER_RANK: Record<PlanTier, number>;
+/**
+ * 요금제별 수량/횟수 제한.
+ *
+ * **이 표는 어드민 요금제 비교표를 그리는 데만 쓰인다 — 실제 제한을 걸지 않는다.**
+ * 고객 수·일일 횟수 같은 실제 enforcement 는 DB(트리거·RPC) 쪽이 담당하므로,
+ * 여기 숫자를 고쳐도 사용자가 실제로 쓸 수 있는 양은 달라지지 않는다.
+ * 정책을 바꾸려면 DB 쪽을 함께 고쳐야 하고, 이 표는 화면 표기를 맞추는 용도다.
+ *
+ * 값 규칙:
+ * - `number` : 제한 수치 (일일 횟수 또는 보유 개수)
+ * - `null`   : 무제한 (✓)
+ * - 키 없음  : 해당 플랜에서 미제공 (✗)
+ */
+export interface PlanLimits {
+    sentenceTrainingDaily?: number | null;
+    wordTrainingDaily?: number | null;
+    gameDaily?: number | null;
+    trainingItemMax?: number | null;
+    customerMax?: number | null;
+    homeworkSendDaily?: number | null;
+}
+/** @public 요금제 티어별 제한 (표시되지 않는 레거시 티어는 생략) */
+export declare const PLAN_LIMITS: Partial<Record<PlanTier, PlanLimits>>;
+/** product code → 요금제 티어 */
+export declare function getPlanTier(productCode: string): PlanTier;

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

@@ -0,0 +1,168 @@
+// O = true, X = false, Lv N = DataLevel
+export const PLAN_FEATURES = {
+    // ── 개인 플랜 (관리 기능 없음) ──────────────────────────────────
+    free: {
+        maxCustomers: 0, visitWord: false, visitSentence: false, homework: false,
+        customerStats: false, managerCustomerSplit: false, managerManagement: false,
+        sentenceTrainingSetting: false, wordTrainingSetting: false, myWordList: false,
+        wordListShare: false, groupTrainingSetting: false, minimalPairSearch: true,
+        wordTableSetting: false, wordTablePrint: false, addToMyList: false,
+        addToGroupList: false, wordSearch: true, wordSearchPrint: false,
+        wordSearchAddToMyList: false, wordSearchAddToGroupList: false,
+        wordDataLevel: 1, sentenceDataLevel: 0, crossword: false,
+        crosswordMid: false, crosswordHigh: false, wordTrainingView: false,
+        sentenceTrainingView: false,
+    },
+    personal_standard: {
+        maxCustomers: 0, visitWord: false, visitSentence: false, homework: false,
+        customerStats: false, managerCustomerSplit: false, managerManagement: false,
+        sentenceTrainingSetting: true, wordTrainingSetting: true, myWordList: true,
+        wordListShare: true, groupTrainingSetting: false, minimalPairSearch: true,
+        wordTableSetting: true, wordTablePrint: true, addToMyList: true,
+        addToGroupList: false, wordSearch: true, wordSearchPrint: true,
+        wordSearchAddToMyList: true, wordSearchAddToGroupList: false,
+        wordDataLevel: 2, sentenceDataLevel: 2, crossword: true,
+        crosswordMid: true, crosswordHigh: false, wordTrainingView: true,
+        sentenceTrainingView: true,
+    },
+    // ── 매니저 플랜 ─────────────────────────────────────────────────
+    mgr_free: {
+        maxCustomers: 5, visitWord: true, visitSentence: true, homework: false,
+        customerStats: false, managerCustomerSplit: false, managerManagement: false,
+        sentenceTrainingSetting: false, wordTrainingSetting: false, myWordList: false,
+        wordListShare: false, groupTrainingSetting: false, minimalPairSearch: true,
+        wordTableSetting: false, wordTablePrint: false, addToMyList: false,
+        addToGroupList: false, wordSearch: true, wordSearchPrint: false,
+        wordSearchAddToMyList: false, wordSearchAddToGroupList: false,
+        wordDataLevel: 1, sentenceDataLevel: 1, crossword: false,
+        crosswordMid: false, crosswordHigh: false, wordTrainingView: false,
+        sentenceTrainingView: false,
+    },
+    none: {
+        maxCustomers: 0, visitWord: false, visitSentence: false, homework: false,
+        customerStats: false, managerCustomerSplit: false, managerManagement: false,
+        sentenceTrainingSetting: false, wordTrainingSetting: false, myWordList: false,
+        wordListShare: false, groupTrainingSetting: false, minimalPairSearch: false,
+        wordTableSetting: false, wordTablePrint: false, addToMyList: false,
+        addToGroupList: false, wordSearch: false, wordSearchPrint: false,
+        wordSearchAddToMyList: false, wordSearchAddToGroupList: false,
+        wordDataLevel: 0, sentenceDataLevel: 0, crossword: false,
+        crosswordMid: false, crosswordHigh: false, wordTrainingView: false,
+        sentenceTrainingView: false,
+    },
+    lite_word: {
+        maxCustomers: 10, visitWord: true, visitSentence: false, homework: false,
+        customerStats: false, managerCustomerSplit: false, managerManagement: false,
+        sentenceTrainingSetting: false, wordTrainingSetting: false, myWordList: false,
+        wordListShare: false, groupTrainingSetting: false, minimalPairSearch: true,
+        wordTableSetting: true, wordTablePrint: true, addToMyList: false,
+        addToGroupList: false, wordSearch: true, wordSearchPrint: true,
+        wordSearchAddToMyList: false, wordSearchAddToGroupList: false,
+        wordDataLevel: 1, sentenceDataLevel: 0, crossword: true,
+        crosswordMid: false, crosswordHigh: false, wordTrainingView: true,
+        sentenceTrainingView: false,
+    },
+    lite_sentence: {
+        maxCustomers: 10, visitWord: false, visitSentence: true, homework: false,
+        customerStats: false, managerCustomerSplit: false, managerManagement: false,
+        sentenceTrainingSetting: false, wordTrainingSetting: false, myWordList: false,
+        wordListShare: false, groupTrainingSetting: false, minimalPairSearch: false,
+        wordTableSetting: false, wordTablePrint: true, addToMyList: false,
+        addToGroupList: false, wordSearch: false, wordSearchPrint: true,
+        wordSearchAddToMyList: false, wordSearchAddToGroupList: false,
+        wordDataLevel: 0, sentenceDataLevel: 1, crossword: true,
+        crosswordMid: false, crosswordHigh: false, wordTrainingView: false,
+        sentenceTrainingView: true,
+    },
+    lite: {
+        maxCustomers: 10, visitWord: true, visitSentence: true, homework: false,
+        customerStats: false, managerCustomerSplit: false, managerManagement: false,
+        sentenceTrainingSetting: false, wordTrainingSetting: false, myWordList: false,
+        wordListShare: false, groupTrainingSetting: false, minimalPairSearch: true,
+        wordTableSetting: true, wordTablePrint: true, addToMyList: false,
+        addToGroupList: false, wordSearch: true, wordSearchPrint: true,
+        wordSearchAddToMyList: false, wordSearchAddToGroupList: false,
+        wordDataLevel: 1, sentenceDataLevel: 1, crossword: true,
+        crosswordMid: false, crosswordHigh: false, wordTrainingView: true,
+        sentenceTrainingView: true,
+    },
+    standard: {
+        maxCustomers: 30, visitWord: true, visitSentence: true, homework: false,
+        customerStats: false, managerCustomerSplit: false, managerManagement: false,
+        sentenceTrainingSetting: true, wordTrainingSetting: true, myWordList: true,
+        wordListShare: true, groupTrainingSetting: false, minimalPairSearch: true,
+        wordTableSetting: true, wordTablePrint: true, addToMyList: true,
+        addToGroupList: false, wordSearch: true, wordSearchPrint: true,
+        wordSearchAddToMyList: true, wordSearchAddToGroupList: false,
+        wordDataLevel: 2, sentenceDataLevel: 2, crossword: true,
+        crosswordMid: true, crosswordHigh: false, wordTrainingView: true,
+        sentenceTrainingView: true,
+    },
+    pro: {
+        maxCustomers: 50, visitWord: true, visitSentence: true, homework: true,
+        customerStats: true, managerCustomerSplit: false, managerManagement: false,
+        sentenceTrainingSetting: true, wordTrainingSetting: true, myWordList: true,
+        wordListShare: true, groupTrainingSetting: false, minimalPairSearch: true,
+        wordTableSetting: true, wordTablePrint: true, addToMyList: true,
+        addToGroupList: false, wordSearch: true, wordSearchPrint: true,
+        wordSearchAddToMyList: true, wordSearchAddToGroupList: false,
+        wordDataLevel: 3, sentenceDataLevel: 3, crossword: true,
+        crosswordMid: true, crosswordHigh: true, wordTrainingView: true,
+        sentenceTrainingView: true,
+    },
+    enterprise: {
+        maxCustomers: Infinity, visitWord: true, visitSentence: true, homework: true,
+        customerStats: true, managerCustomerSplit: true, managerManagement: true,
+        sentenceTrainingSetting: true, wordTrainingSetting: true, myWordList: true,
+        wordListShare: true, groupTrainingSetting: true, minimalPairSearch: true,
+        wordTableSetting: true, wordTablePrint: true, addToMyList: true,
+        addToGroupList: true, wordSearch: true, wordSearchPrint: true,
+        wordSearchAddToMyList: true, wordSearchAddToGroupList: true,
+        wordDataLevel: 3, sentenceDataLevel: 3, crossword: true,
+        crosswordMid: true, crosswordHigh: true, wordTrainingView: true,
+        sentenceTrainingView: true,
+    },
+};
+/** 요금제 티어 순위 (높을수록 상위 요금제) */
+export const TIER_RANK = {
+    none: 0,
+    free: 1, personal_standard: 3,
+    mgr_free: 4,
+    lite_word: 5, lite_sentence: 5, lite: 6,
+    standard: 7, pro: 8, enterprise: 9,
+};
+/** @public 요금제 티어별 제한 (표시되지 않는 레거시 티어는 생략) */
+export const PLAN_LIMITS = {
+    // ── 개인 ──
+    free: { sentenceTrainingDaily: 2, wordTrainingDaily: 2, gameDaily: 1 },
+    personal_standard: { sentenceTrainingDaily: null, wordTrainingDaily: null, gameDaily: null },
+    // ── 매니저 ──
+    mgr_free: { sentenceTrainingDaily: 2, wordTrainingDaily: 2, gameDaily: 1, trainingItemMax: 5, customerMax: 5, homeworkSendDaily: 1 },
+    lite: { sentenceTrainingDaily: 5, wordTrainingDaily: 5, gameDaily: 5, trainingItemMax: 10, customerMax: 10, homeworkSendDaily: 10 },
+    standard: { sentenceTrainingDaily: null, wordTrainingDaily: null, gameDaily: null, trainingItemMax: 30, customerMax: 30, homeworkSendDaily: 30 },
+    pro: { sentenceTrainingDaily: null, wordTrainingDaily: null, gameDaily: null, trainingItemMax: null, customerMax: 50, homeworkSendDaily: 50 },
+    enterprise: { sentenceTrainingDaily: null, wordTrainingDaily: null, gameDaily: null, trainingItemMax: null, customerMax: null, homeworkSendDaily: null },
+};
+/** product code → 요금제 티어 */
+export function getPlanTier(productCode) {
+    const c = productCode.toLowerCase();
+    if (c.startsWith('manager_enterprise'))
+        return 'enterprise';
+    if (c.startsWith('manager_pro'))
+        return 'pro';
+    if (c.startsWith('manager_standard'))
+        return 'standard';
+    if (c.startsWith('manager_lite_word'))
+        return 'lite_word';
+    if (c.startsWith('manager_lite_sentence'))
+        return 'lite_sentence';
+    if (c.startsWith('manager_lite') || c.startsWith('mgr_lite'))
+        return 'lite';
+    if (c.startsWith('mgr_standard'))
+        return 'standard';
+    if (c.startsWith('mgr_pro'))
+        return 'pro';
+    if (c.startsWith('content_') || c.startsWith('speechear_') || c.startsWith('light_') || c === 'light')
+        return 'personal_standard';
+    return 'none';
+}

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

@@ -0,0 +1,7 @@
+declare global {
+    var __ihab_core_pronunciation_resolver__: ((word: string, homonum?: number) => string) | undefined;
+}
+/** @public */
+export declare function configurePronunciationResolver(resolver: (word: string, homonum?: number) => string): void;
+/** @public */
+export declare function getPronunciationResolver(): ((word: string, homonum?: number) => string) | null;

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

@@ -0,0 +1,21 @@
+/**
+ * 표준발음 텍스트 리졸버 설정
+ *
+ * 소비 앱에서 configurePronunciationResolver()로 리졸버를 등록하면,
+ * WordTable 셀이 항목에 발음(subLabel)이 없을 때 단어로 표준발음을 조회해 표시한다.
+ * imageConfig / ttsConfig 와 동일하게 globalThis 싱글톤을 사용한다.
+ *
+ * @example
+ * ```ts
+ * configurePronunciationResolver((word) => getPronunciationMap()?.get(word) ?? '')
+ * ```
+ */
+const GLOBAL_KEY = '__ihab_core_pronunciation_resolver__';
+/** @public */
+export function configurePronunciationResolver(resolver) {
+    globalThis[GLOBAL_KEY] = resolver;
+}
+/** @public */
+export function getPronunciationResolver() {
+    return globalThis[GLOBAL_KEY] ?? null;
+}

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

@@ -0,0 +1,18 @@
+import type { WordSearchResultItem, WordTableSearchConfig } from '../types/wordSearch';
+/** @public */
+export interface SavedWordTable {
+    id: string;
+    name: string;
+    savedAt: string;
+    items: WordSearchResultItem[];
+    group?: string | null;
+    description?: string;
+    /** 대립쌍표를 만든 검색 구성 — 저장 시 함께 남겨 수정 시 검색 패널을 복원한다. */
+    searchConfig?: WordTableSearchConfig;
+}
+export declare function getSavedTables(): SavedWordTable[];
+export declare function saveTable(name: string, items: WordSearchResultItem[], description?: string, searchConfig?: WordTableSearchConfig): SavedWordTable;
+/** 저장된 단어표를 갱신한다(수정 저장). 지정한 필드만 덮어쓴다. */
+export declare function updateSavedTable(id: string, patch: Partial<Pick<SavedWordTable, 'name' | 'items' | 'description' | 'searchConfig' | 'group'>>): void;
+export declare function deleteTable(id: string): void;
+export declare function duplicateTable(id: string): SavedWordTable | null;

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

@@ -0,0 +1,70 @@
+const STORAGE_KEY = 'speechear:saved_word_tables';
+// 저장된 값이 배열이 아니거나(과거 포맷/손상) 항목이 기대 형태(id/name/items)를 갖추지
+// 않으면, 이를 신뢰해 그대로 넘기는 소비 측(.map/.find 등)에서 런타임 에러로 번진다 —
+// 최소한의 구조 검증 후 어긋난 항목은 걸러낸다.
+function isSavedWordTable(v) {
+    if (typeof v !== 'object' || v === null)
+        return false;
+    const t = v;
+    return typeof t.id === 'string' && typeof t.name === 'string' && Array.isArray(t.items);
+}
+export function getSavedTables() {
+    try {
+        const raw = localStorage.getItem(STORAGE_KEY);
+        if (!raw)
+            return [];
+        const parsed = JSON.parse(raw);
+        return Array.isArray(parsed) ? parsed.filter(isSavedWordTable) : [];
+    }
+    catch {
+        return [];
+    }
+}
+export function saveTable(name, items, description, searchConfig) {
+    const tables = getSavedTables();
+    const newTable = {
+        id: `${Date.now()}-${Math.random().toString(36).slice(2, 7)}`,
+        name,
+        savedAt: new Date().toISOString(),
+        items,
+        description,
+        searchConfig,
+    };
+    try {
+        localStorage.setItem(STORAGE_KEY, JSON.stringify([newTable, ...tables]));
+    }
+    catch { /* noop */ }
+    return newTable;
+}
+/** 저장된 단어표를 갱신한다(수정 저장). 지정한 필드만 덮어쓴다. */
+export function updateSavedTable(id, patch) {
+    const tables = getSavedTables().map(t => t.id === id ? { ...t, ...patch } : t);
+    try {
+        localStorage.setItem(STORAGE_KEY, JSON.stringify(tables));
+    }
+    catch { /* noop */ }
+}
+export function deleteTable(id) {
+    const tables = getSavedTables().filter(t => t.id !== id);
+    try {
+        localStorage.setItem(STORAGE_KEY, JSON.stringify(tables));
+    }
+    catch { /* noop */ }
+}
+export function duplicateTable(id) {
+    const tables = getSavedTables();
+    const original = tables.find(t => t.id === id);
+    if (!original)
+        return null;
+    const copy = {
+        id: `${Date.now()}-${Math.random().toString(36).slice(2, 7)}`,
+        name: `${original.name} (복사)`,
+        savedAt: new Date().toISOString(),
+        items: original.items,
+    };
+    try {
+        localStorage.setItem(STORAGE_KEY, JSON.stringify([copy, ...tables]));
+    }
+    catch { /* noop */ }
+    return copy;
+}

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

@@ -0,0 +1,24 @@
+/**
+ * 정렬 상태를 드롭다운 **한 문자열**로 주고받는 부호 — `"name|asc"` 꼴.
+ *
+ * 화면의 "정렬" 드롭다운은 값 하나만 다룰 수 있는데 정렬은 두 가지(무엇으로·오름/내림)라,
+ * 둘을 `|` 로 붙여 하나로 만든다. 같은 부호를 MyWordTrainingPage 와 TrainingSettingsPage
+ * 가 **한 벌씩 따로** 적고 있었다(글자까지 같았다) — 한쪽만 고치면 두 화면의 정렬이
+ * 조용히 어긋나므로 여기 한 벌만 둔다.
+ *
+ * `'id'` 는 "정렬 안 함(원래 순서)" 을 뜻한다. 그때는 드롭다운에 고른 값이 없어야 하므로
+ * `undefined` 를 준다 — 빈 문자열을 주면 드롭다운이 "빈 항목이 선택된" 것처럼 보인다.
+ * @public
+ */
+export declare function sortToValue(key: string, asc: boolean): string | undefined;
+/**
+ * 드롭다운 값을 정렬 상태로 되돌린다.
+ *
+ * `asc` 는 **`'asc'` 일 때만 참**이다 — 값이 비었거나 모양이 깨졌을 때 오름차순으로
+ * 되던 것보다, 내림차순으로 떨어지는 편이 목록 첫머리(최신순)와 어긋나지 않는다.
+ * @public
+ */
+export declare function parseSortValue(v: string): {
+    key: string;
+    asc: boolean;
+};

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

@@ -0,0 +1,26 @@
+/**
+ * 정렬 상태를 드롭다운 **한 문자열**로 주고받는 부호 — `"name|asc"` 꼴.
+ *
+ * 화면의 "정렬" 드롭다운은 값 하나만 다룰 수 있는데 정렬은 두 가지(무엇으로·오름/내림)라,
+ * 둘을 `|` 로 붙여 하나로 만든다. 같은 부호를 MyWordTrainingPage 와 TrainingSettingsPage
+ * 가 **한 벌씩 따로** 적고 있었다(글자까지 같았다) — 한쪽만 고치면 두 화면의 정렬이
+ * 조용히 어긋나므로 여기 한 벌만 둔다.
+ *
+ * `'id'` 는 "정렬 안 함(원래 순서)" 을 뜻한다. 그때는 드롭다운에 고른 값이 없어야 하므로
+ * `undefined` 를 준다 — 빈 문자열을 주면 드롭다운이 "빈 항목이 선택된" 것처럼 보인다.
+ * @public
+ */
+export function sortToValue(key, asc) {
+    return key === 'id' ? undefined : `${key}|${asc ? 'asc' : 'desc'}`;
+}
+/**
+ * 드롭다운 값을 정렬 상태로 되돌린다.
+ *
+ * `asc` 는 **`'asc'` 일 때만 참**이다 — 값이 비었거나 모양이 깨졌을 때 오름차순으로
+ * 되던 것보다, 내림차순으로 떨어지는 편이 목록 첫머리(최신순)와 어긋나지 않는다.
+ * @public
+ */
+export function parseSortValue(v) {
+    const [key, dir] = v.split('|');
+    return { key, asc: dir === 'asc' };
+}

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

@@ -0,0 +1,7 @@
+/** @public */
+export declare function speak(text: string, { onEnd, rate }?: {
+    onEnd?: () => void;
+    rate?: number;
+}): void;
+/** @public */
+export declare function stopSpeaking(): void;

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

@@ -0,0 +1,35 @@
+/** @public */
+export function speak(text, { onEnd, rate = 0.9 } = {}) {
+    if (typeof window === 'undefined' || typeof SpeechSynthesisUtterance === 'undefined' || !('speechSynthesis' in window)) {
+        onEnd?.();
+        return;
+    }
+    const synth = window.speechSynthesis;
+    const doSpeak = () => {
+        synth.cancel();
+        const u = new SpeechSynthesisUtterance(text);
+        const voices = synth.getVoices();
+        const ko = voices.find(v => v.lang.startsWith('ko'));
+        if (ko)
+            u.voice = ko;
+        u.rate = rate;
+        u.onend = onEnd
+            ? function (_ev) {
+                try {
+                    onEnd();
+                }
+                catch (e) { }
+            }
+            : null;
+        synth.speak(u);
+    };
+    if (synth.getVoices().length > 0)
+        doSpeak();
+    else
+        synth.addEventListener('voiceschanged', doSpeak, { once: true });
+}
+/** @public */
+export function stopSpeaking() {
+    if (typeof window !== 'undefined' && 'speechSynthesis' in window)
+        window.speechSynthesis.cancel();
+}

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

@@ -0,0 +1,102 @@
+/**
+ * Storage resolver — 앱에서 주입하는 함수 기반 인터페이스.
+ *
+ * 패키지는 Supabase를 직접 참조하지 않습니다.
+ * 소비 앱이 configureStorage()로 resolver를 한 번 등록하면,
+ * 패키지 내부의 downloadSound / fileExists / getSignedOrPublicUrl이
+ * 해당 resolver를 통해 동작합니다.
+ *
+ * @example
+ * configureStorage resolveUrl/download 를 Supabase storage 에 연결하세요.
+ *
+ * @public
+ */
+export interface StorageResolvers {
+    /**
+     * 파일 경로를 받아 접근 가능한 URL을 반환합니다.
+     * 서명된 URL 또는 퍼블릭 URL 중 적합한 것을 반환하세요.
+     * 파일이 없거나 에러 시 null을 반환하세요.
+     */
+    resolveUrl: (path: string) => Promise<string | null>;
+    /**
+     * 파일 경로를 받아 Blob을 반환합니다.
+     * 실패 시 Error를 throw 하세요.
+     */
+    download: (path: string) => Promise<Blob>;
+    /**
+     * (선택) 파일 존재 여부를 확인합니다.
+     * 미제공 시 resolveUrl 결과(null 여부)로 대체합니다.
+     */
+    exists?: (path: string) => Promise<boolean>;
+    /**
+     * (선택) 사운드 코드(contextCode, questionCode 등)와 버킷 힌트로부터
+     * 실제 스토리지 경로를 반환합니다.
+     *
+     * 미제공 시 기본값: `${bucketHint}/${code}.mp3`
+     *
+     * 이 옵션을 활용하면 프로젝트마다 다른 디렉터리 구조, 파일 확장자,
+     * 코드 변환 규칙 등을 패키지 외부에서 완전히 제어할 수 있습니다.
+     *
+     * @param code - soundSrc 로 전달된 코드 문자열 (예: 'QQ01', 'ctx_01')
+     * @param bucketHint - TrainingStep 의 bucketPath prop 값 (예: 'LIN_D', 'SHORT_S')
+     * @returns 스토리지 경로 문자열 또는 null
+     *
+     * @example
+     * ```ts
+     * resolvePath: (code, bucketHint) => `audio/${bucketHint}/${code}.wav`
+     * ```
+     */
+    resolvePath?: (code: string, bucketHint?: string | null) => string | null;
+    /**
+     * (선택) 소음 오디오 파일들이 서빙되는 기본 경로.
+     * 기본값: '/sounds/noise'
+     *
+     * 앱의 public 디렉터리에 noise1.mp3 ~ noise4.mp3 등의 파일이
+     * 이 경로 아래에 위치해야 합니다.
+     *
+     * @example '/sounds/noise'
+     * @example 'https://cdn.example.com/sounds/noise'
+     */
+    noiseBaseUrl?: string;
+}
+/**
+ * Storage resolver를 런타임에 주입합니다.
+ * 앱 초기화 시점에 한 번만 호출하세요.
+ *
+ * @public
+ */
+export declare function configureStorage(resolvers: StorageResolvers): void;
+/**
+ * 사운드 코드와 버킷 힌트로부터 스토리지 경로를 결정합니다.
+ *
+ * 우선순위:
+ * 1. resolver에 resolvePath가 등록되어 있으면 그것을 사용합니다.
+ * 2. 없으면 기본 규칙: `${bucketHint}/${code}.mp3`
+ *
+ * TrainingStepAudioPlayer 내부에서 사용되며,
+ * 소비 앱이 configureStorage 의 resolvePath 옵션으로 재정의할 수 있습니다.
+ *
+ * @public
+ */
+export declare function resolveSoundPath(code: string, bucketHint?: string | null): string | null;
+/**
+ * 파일 존재 여부를 확인합니다.
+ * @public
+ */
+export declare function fileExists(filePath: string): Promise<boolean>;
+/**
+ * 파일의 접근 가능한 URL을 반환합니다.
+ * @public
+ */
+export declare function getSignedOrPublicUrl(filePath: string): Promise<string | null>;
+/**
+ * 파일을 Blob으로 다운로드합니다.
+ * @public
+ */
+export declare function downloadSound(filePath: string): Promise<Blob>;
+/**
+ * 소음 오디오 파일의 기본 URL을 반환합니다.
+ * configureStorage 의 noiseBaseUrl 이 설정되어 있으면 그 값을, 없으면 '/sounds/noise' 를 반환합니다.
+ * @public
+ */
+export declare function getNoiseBaseUrl(): string;

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

@@ -0,0 +1,118 @@
+// globalThis 싱글톤: 번들이 여러 개로 분리되어도 동일한 설정을 공유합니다.
+const STORAGE_GLOBAL_KEY = '__ihab_core_storage_resolvers__';
+function getResolvers() {
+    return globalThis[STORAGE_GLOBAL_KEY] ?? null;
+}
+function setResolvers(r) {
+    ;
+    globalThis[STORAGE_GLOBAL_KEY] = r;
+}
+// ─── configureStorage 미호출 시 친절한 에러 ──────────────────────────────────
+class StorageNotConfiguredError extends Error {
+    constructor(fnName) {
+        super('\n' +
+            `[ihabdevteam-core] ${fnName}() 호출 실패 — configureStorage()가 설정되지 않았습니다.\n\n` +
+            '  앱 초기화 시점(main.tsx 등)에 아래와 같이 한 번 호출하세요:\n\n' +
+            '    import { configureStorage } from \'@ihabdevteam/core\'\n\n' +
+            '    configureStorage({\n' +
+            '      resolveUrl: (path) =>\n' +
+            '        supabase.storage.from(BUCKET).createSignedUrl(path, 3600)\n' +
+            '          .then(({ data }) => data?.signedUrl ?? null),\n' +
+            '      download: (path) =>\n' +
+            '        supabase.storage.from(BUCKET).download(path)\n' +
+            '          .then(({ data, error }) => { if (error) throw error; return data }),\n' +
+            '    })\n\n' +
+            '  설치 명령어 (스토리지 SDK 미설치 시):\n' +
+            '    npm install @supabase/supabase-js\n' +
+            '    pnpm add @supabase/supabase-js\n');
+        this.name = 'StorageNotConfiguredError';
+    }
+}
+/**
+ * Storage resolver를 런타임에 주입합니다.
+ * 앱 초기화 시점에 한 번만 호출하세요.
+ *
+ * @public
+ */
+export function configureStorage(resolvers) {
+    setResolvers(resolvers);
+}
+/**
+ * 사운드 코드와 버킷 힌트로부터 스토리지 경로를 결정합니다.
+ *
+ * 우선순위:
+ * 1. resolver에 resolvePath가 등록되어 있으면 그것을 사용합니다.
+ * 2. 없으면 기본 규칙: `${bucketHint}/${code}.mp3`
+ *
+ * TrainingStepAudioPlayer 내부에서 사용되며,
+ * 소비 앱이 configureStorage 의 resolvePath 옵션으로 재정의할 수 있습니다.
+ *
+ * @public
+ */
+export function resolveSoundPath(code, bucketHint) {
+    if (!code)
+        return null;
+    const r = getResolvers();
+    if (r?.resolvePath)
+        return r.resolvePath(code, bucketHint);
+    if (!bucketHint)
+        return null;
+    return `${bucketHint}/${code}.mp3`;
+}
+/**
+ * 파일 존재 여부를 확인합니다.
+ * @public
+ */
+export async function fileExists(filePath) {
+    if (!filePath)
+        return false;
+    const r = getResolvers();
+    if (!r)
+        throw new StorageNotConfiguredError('fileExists');
+    if (r.exists) {
+        return r.exists(filePath);
+    }
+    // exists 미제공 시 resolveUrl null 여부로 대체
+    try {
+        const url = await r.resolveUrl(filePath);
+        return url !== null;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * 파일의 접근 가능한 URL을 반환합니다.
+ * @public
+ */
+export async function getSignedOrPublicUrl(filePath) {
+    if (!filePath)
+        return null;
+    const r = getResolvers();
+    if (!r)
+        throw new StorageNotConfiguredError('getSignedOrPublicUrl');
+    try {
+        return await r.resolveUrl(filePath);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * 파일을 Blob으로 다운로드합니다.
+ * @public
+ */
+export async function downloadSound(filePath) {
+    const r = getResolvers();
+    if (!r)
+        throw new StorageNotConfiguredError('downloadSound');
+    return r.download(filePath);
+}
+/**
+ * 소음 오디오 파일의 기본 URL을 반환합니다.
+ * configureStorage 의 noiseBaseUrl 이 설정되어 있으면 그 값을, 없으면 '/sounds/noise' 를 반환합니다.
+ * @public
+ */
+export function getNoiseBaseUrl() {
+    return getResolvers()?.noiseBaseUrl ?? '/sounds/noise';
+}