@ihabdevteam/core 0.8.0

package/dist/packages/core/src/types/geometry.js

@@ -0,0 +1 @@
+export {};

package/dist/packages/core/src/types/training.d.ts

@@ -0,0 +1,131 @@
+/** @public */
+export interface Choice {
+    id?: string | number;
+    label?: string;
+    value?: string | number;
+    [k: string]: unknown;
+}
+/** @public */
+export interface Question {
+    id?: string | number;
+    text?: string;
+    prompt?: string;
+    questionItems?: Record<string, unknown>[];
+    choices?: (string | Choice)[];
+    correctAnswers?: (string | number)[];
+    [k: string]: unknown;
+}
+/** @public */
+export interface TrainingItem {
+    id?: string | number;
+    title?: string;
+    context?: string;
+    sentence?: string;
+    contextCode?: string;
+    context_code?: string;
+    questionCode?: string;
+    question_code?: string;
+    questions?: Question[];
+    questionItems?: Question[];
+    choices?: (string | Choice)[];
+    [k: string]: unknown;
+}
+/** @public */
+export interface TrainingGroup {
+    training_type?: string;
+    items?: TrainingItem[];
+    [k: string]: unknown;
+}
+/**
+ * 훈련 데이터의 최상위 구조입니다.
+ *
+ * ### contexts vs items
+ * - **`contexts`** (`NoiseContext[]`): 소음 훈련(`NoiseTrainingPagePopup`) 전용.
+ *   각 항목은 재생할 문장(`sentence`)과 오디오 파일 코드(`contextCode`)로 구성됩니다.
+ *   소음 훈련은 `items` 대신 이 필드를 사용합니다.
+ *
+ * - **`items`** (`TrainingItem[]`): 일반 훈련(`TrainingPagePopup`, `OrderTrainingPagePopup` 등) 전용.
+ *   각 항목은 문장, 선택지, 정답 정보를 포함하며 단계별 훈련에 사용됩니다.
+ *
+ * @public
+ */
+export interface TrainingData {
+    id?: string | number;
+    key?: string;
+    title?: string;
+    name?: string;
+    /**
+     * 일반/순서 훈련 등에서 사용하는 훈련 문항 배열.
+     * 소음 훈련(`NoiseTrainingPagePopup`)에서는 사용되지 않습니다. → {@link NoiseContext} 참고
+     */
+    items?: TrainingItem[];
+    sentences?: (string | {
+        sentence?: string;
+        context?: string;
+        contextCode?: string;
+    })[];
+    /**
+     * 소음 훈련(`NoiseTrainingPagePopup`) 전용 문장 목록.
+     * 각 항목의 `contextCode`는 Supabase Storage의 오디오 파일 경로 코드입니다.
+     * 일반 훈련에서는 사용되지 않습니다. → {@link TrainingItem} 참고
+     */
+    contexts?: NoiseContext[];
+    /** 기본 오디오 컨텍스트 코드. contexts 미지정 시 폴백으로 사용됩니다. */
+    contextCode?: string;
+    category_0?: string;
+    category_main_code?: string;
+    category_1?: string;
+    category_sub_code?: string;
+    variants?: Record<string, unknown> | undefined;
+    meta?: Record<string, unknown> | undefined;
+    [k: string]: unknown;
+}
+/** @public */
+export type TrainingPayload = {
+    selectedValues?: (string | number)[];
+    selectedValue?: string | number;
+    selectedIndex?: number;
+    value?: unknown;
+    correct?: boolean;
+    __ts?: number;
+    [k: string]: unknown;
+};
+/** @public */
+export interface NoiseContext {
+    sentence: string;
+    contextCode?: string;
+}
+/** @public */
+export type SelectedItem = {
+    trainingType: string;
+    topicKey: string;
+    subKey: string;
+    subLabel: string;
+    itemId?: string;
+    itemTitle?: string;
+};
+/** @public */
+export type SelectedCustomer = {
+    id: string;
+    name: string;
+};
+/** @public */
+export type TrainingPlan = {
+    id?: string;
+    name: string;
+    description?: string | null;
+    group?: string | null;
+    customers?: SelectedCustomer[];
+    items: SelectedItem[];
+    createdAt?: string;
+};
+/** @public */
+export type CustomerOption = {
+    id: string;
+    name: string;
+    phone?: string;
+    gender?: string;
+    birthDate?: string;
+    joinDate?: string;
+    age?: number;
+};

package/dist/packages/core/src/types/training.js

@@ -0,0 +1 @@
+export {};

package/dist/packages/core/src/types/wordSearch.d.ts

@@ -0,0 +1,49 @@
+/** @public */
+export interface WordSearchResultWord {
+    label: string;
+    subLabel?: string;
+    colloquialLabel?: string;
+    homonum?: number;
+    grade?: string;
+    syllables?: number;
+    pos?: string;
+    wordType?: string;
+    /**
+     * 사용자가 '단어 관리'에서 직접 추가한 개인 단어인지. 사전(SpeechEar_WordData)에 없는 단어라
+     * 다른 사람에게는 존재하지 않으므로, 이 값이 true인 단어가 든 단어표·훈련은 공유·발행할 수 없다.
+     * 저장된 단어표에 함께 기록해, 나중에 열었을 때도 대조 없이 판정할 수 있게 한다.
+     */
+    isCustom?: boolean;
+}
+/** @public */
+export interface WordSearchResultItem {
+    id: string;
+    words: WordSearchResultWord[];
+    diffSection?: string;
+    diffHasEmpty?: boolean;
+}
+/**
+ * 대립쌍 검색(WordPairsPage)의 구성 스냅샷 — 저장된 대립쌍표를 다시 열 때 검색 패널을 그대로
+ * 복원하기 위해 함께 저장한다. 결과(items)와 별개로, "어떻게 검색했는지"를 담는다.
+ * @public
+ */
+export interface WordTableSearchConfig {
+    searchMode: 'contrast' | 'contain';
+    matchMode: 'ordered' | 'unordered';
+    phonemeMatchMode: 'contain' | 'contrast';
+    inputMode: 'word' | 'phoneme';
+    positionCount: number;
+    filterScope: 'all' | 'searchWordOnly';
+    filterSelected: Record<string, string[]>;
+    phonemeSelected: Record<string, string>[];
+}
+/** 단어표(단일)의 검색 구성 — 수정 시 필터 패널을 복원하기 위해 저장한다. */
+export interface WordSearchFilterConfig {
+    filterSelected: Record<string, string | string[]>;
+    /**
+     * 입력 방식 — 'char'(글자 선택, 기본) | 'pron'(발음 선택) | 'direct'(글자 입력·직접입력).
+     * 'char'/'pron'은 초성/중성/종성+위치 버튼 선택 모드로 UI는 동일하고 매칭 대상만 철자(word)/표준발음(pronunciation)으로 다르다.
+     * 'direct'는 단어를 텍스트로 직접 입력하는 기존 검색 모드. 미지정 시 'char'로 취급.
+     */
+    inputMode?: 'char' | 'pron' | 'direct';
+}

package/dist/packages/core/src/types/wordSearch.js

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,3 @@
+export type { Choice, Question, TrainingItem, TrainingGroup, TrainingData, TrainingPayload, NoiseContext, SelectedItem, SelectedCustomer, TrainingPlan, CustomerOption, } from './types/training';
+export type { WordSearchResultWord, WordSearchResultItem, WordTableSearchConfig, WordSearchFilterConfig } from './types/wordSearch';
+export type { DeviceForm } from './types/device';

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

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,91 @@
+import type { TFunction } from 'i18next';
+/** @public */
+export declare const TRAINING_TYPES: {
+    key: string;
+    label: string;
+    icon: string;
+    desc: string;
+}[];
+/** @public */
+export declare const TOPIC_TYPES: ({
+    key: string;
+    label: string;
+    icon: string;
+    color: string;
+    subs: {
+        key: string;
+        label: string;
+    }[];
+    desc?: undefined;
+} | {
+    key: string;
+    label: string;
+    icon: string;
+    desc: string;
+    color: string;
+    subs: {
+        key: string;
+        label: string;
+    }[];
+})[];
+/** 훈련 유형 i18n 키 매핑 */
+export declare const TRAINING_TYPE_I18N_KEY: Record<string, string>;
+/** 번역된 훈련 유형 레이블/설명 반환 */
+export declare function translateTrainingTypes(t: TFunction): {
+    key: string;
+    label: string;
+    icon: string;
+    desc: string;
+}[];
+/** 번역된 토픽/서브토픽 레이블 반환 — 컴포넌트에서 useMemo와 함께 사용 */
+export declare function translateTopicTypes(t: TFunction): ({
+    label: string;
+    subs: {
+        label: string;
+        key: string;
+    }[];
+    key: string;
+    icon: string;
+    color: string;
+    desc?: undefined;
+} | {
+    label: string;
+    subs: {
+        label: string;
+        key: string;
+    }[];
+    key: string;
+    icon: string;
+    desc: string;
+    color: string;
+})[];
+declare const _default: {
+    TRAINING_TYPES: {
+        key: string;
+        label: string;
+        icon: string;
+        desc: string;
+    }[];
+    TOPIC_TYPES: ({
+        key: string;
+        label: string;
+        icon: string;
+        color: string;
+        subs: {
+            key: string;
+            label: string;
+        }[];
+        desc?: undefined;
+    } | {
+        key: string;
+        label: string;
+        icon: string;
+        desc: string;
+        color: string;
+        subs: {
+            key: string;
+            label: string;
+        }[];
+    })[];
+};
+export default _default;

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

@@ -0,0 +1,57 @@
+/** @public */
+export const TRAINING_TYPES = [
+    { key: "LISTEN_IN_NOISE", label: "소음 하 문장 듣기", icon: "party-popper", desc: "다양한 소음 환경에서 문장 청력을 훈련합니다." },
+    { key: "SHORT_STORY", label: "짧은 이야기 듣기", icon: "message-square", desc: "짧은 이야기를 듣고 기억하여 문제를 풀어봅니다." },
+    { key: "LONG_STORY", label: "긴 이야기 듣기", icon: "message-square-text", desc: "긴 이야기를 듣고 기억하여 다수의 문제를 풀어봅니다." },
+    { key: "ORDERING_SENTENCE", label: "문장 순서화 하기", icon: "align-start-vertical", desc: "여러개의 짧은 문장을 듣고 기억하여 그 순서에 맞게 배열합니다." },
+];
+/** @public */
+export const TOPIC_TYPES = [
+    { key: 'FOOD', label: '음식', icon: 'salad', color: '#FF8A65', subs: [{ key: 'TRKRFD', label: ' 한국 전통음식' }, { key: 'MDKRFD', label: '한국 현대음식' }, { key: 'WRLDFD', label: '세계의 음식' }, { key: 'MTRFRT', label: '식재료와 과일' }, { key: 'GEFDKL', label: '음식 상식' }] },
+    { key: 'HLTH', label: '건강', icon: 'heart', color: '#66BB6A', subs: [{ key: 'HTETHB', label: '건강한 식습관' }, { key: 'DISILL', label: '병과 질환' }, { key: 'EXCISE', label: '운동' }, { key: 'GEHTKL', label: '건상상식' }] },
+    { key: 'WETH', label: '날씨', icon: 'sun-medium', color: '#42A5F5', subs: [{ key: 'GESSKL', label: '계절상식' }, { key: 'SNWRAN', label: '눈과 비' }, { key: 'WTHFCT', label: '일기예보' }, { key: 'GEWTKL', label: '날씨상식' }] },
+    { key: 'PRSN', label: '인물', icon: 'user-round', desc: '소음 환경 속 문장 이해 훈련', color: '#AB47BC', subs: [{ key: 'JODYPS', label: '조선시대' }, { key: 'MDKRPS', label: '한국 근현대' }, { key: 'THKDPS', label: '삼국시대' }, { key: 'WRLART', label: '세계의 예술가' }, { key: 'WRLPSN', label: '세계의 인물' }] },
+    { key: 'KRCT', label: '한국문화', icon: 'bow-arrow', desc: '소음 환경 속 문장 이해 훈련', color: '#EC407A', subs: [{ key: 'KRLANG', label: '우리말' }, { key: 'TRPLCT', label: '전통놀이' }, { key: 'HERITG', label: '문화재' }, { key: 'EVTFES', label: '행사와 축제' }, { key: 'GECTKL', label: '상식' }] },
+    { key: 'STRY', label: '이야기', icon: 'message-circle', desc: '소음 환경 속 문장 이해 훈련', color: '#8D6E63', subs: [{ key: 'FRYTAL', label: '동화' }, { key: 'AMZING', label: '신기한 이야기' }, { key: 'DAYSTR', label: '일상 속 이야기' }] },
+    { key: 'LOCA', label: '지역', icon: 'map-pin', desc: '소음 환경 속 문장 이해 훈련', color: '#26A69A', subs: [{ key: 'KRLDMK', label: '한국의 명소' }, { key: 'SELNMK', label: '서울의 명소' }, { key: 'WRDTRB', label: '세계여행' }, { key: 'NAVIGT', label: '길 찾기' }] },
+    { key: 'SOAR', label: '사회와 예술', icon: 'landmark', desc: '소음 환경 속 문장 이해 훈련', color: '#5C6BC0', subs: [{ key: 'KRSOCI', label: '한국' }, { key: 'ECONEW', label: '경제와 뉴스' }, { key: 'GENART', label: '예술' }, { key: 'GELFKL', label: '생활 상식' }] },
+    { key: 'NTSC', label: '자연과 과학', icon: 'leaf', desc: '소음 환경 속 문장 이해 훈련', color: '#9CCC65', subs: [{ key: 'ANIMAL', label: '동물' }, { key: 'PLANTS', label: '식물' }, { key: 'ETHPLT', label: '지구' }, { key: 'TOLELC', label: '도구와 전자제품' }, { key: 'GESCKL', label: '과학상식' }] },
+    { key: 'SPRT', label: '스포츠', icon: 'trophy', desc: '소음 환경 속 문장 이해 훈련', color: '#FFCA28', subs: [{ key: 'INVDSP', label: '개인경기' }, { key: 'MARART', label: '격투기' }, { key: 'TEAMSP', label: '단체경기' }, { key: 'FOOTBL', label: '축구' }, { key: 'GESPKL', label: '스포츠 상식' }] },
+];
+/** 훈련 유형 i18n 키 매핑 */
+export const TRAINING_TYPE_I18N_KEY = {
+    LISTEN_IN_NOISE: 'listenInNoise',
+    SHORT_STORY: 'shortStory',
+    LONG_STORY: 'longStory',
+    ORDERING_SENTENCE: 'orderingSentence',
+};
+/** 번역된 훈련 유형 레이블/설명 반환 */
+export function translateTrainingTypes(t) {
+    return TRAINING_TYPES.map(type => {
+        const i18nKey = TRAINING_TYPE_I18N_KEY[type.key];
+        return i18nKey
+            ? { ...type, label: t(`trainingType.${i18nKey}.title`), desc: t(`trainingType.${i18nKey}.desc`) }
+            : type;
+    });
+}
+/*
+ * 이름에 '번역된'을 박아 둔다. 같은 utils 폴더의 categories.ts 에도
+ * getTopicTypes/getTrainingTypes 가 있는데 그쪽은 등록된 원본을 인자 없이 돌려준다.
+ * 이름이 같아서, 코어 안에서 두 가지가 나란히 쓰이는 화면(TrainingPlanCard 는 원본,
+ * TodayPage 는 번역본)을 읽을 때 인자 유무만으로 구분해야 했다.
+ */
+/** 번역된 토픽/서브토픽 레이블 반환 — 컴포넌트에서 useMemo와 함께 사용 */
+export function translateTopicTypes(t) {
+    return TOPIC_TYPES.map(topic => ({
+        ...topic,
+        label: t(`topic.${topic.key}`, { defaultValue: topic.label }),
+        subs: topic.subs?.map(sub => ({
+            ...sub,
+            label: t(`topic.sub.${sub.key}`, { defaultValue: sub.label }),
+        })),
+    }));
+}
+export default {
+    TRAINING_TYPES,
+    TOPIC_TYPES,
+};

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

@@ -0,0 +1,20 @@
+/**
+ * 작은 배열 헬퍼 모음. 여러 훅/컴포넌트/게임이 각자 인라인으로 복제하던 순수 로직을 한곳으로 모은다.
+ */
+/** @public 배열에서 from 위치 요소를 to 위치로 옮긴 새 배열을 반환한다(원본 불변). 드래그 재정렬 등에 사용. */
+export declare function reorderArray<T>(arr: readonly T[], from: number, to: number): T[];
+/**
+ * @public Fisher-Yates 셔플 — 새 배열을 반환한다(원본 불변). rng 미지정 시 Math.random.
+ * rng를 주면(시드 PRNG 등) 결정적 셔플이 되어 기기/세션 무관 동일 순서를 만들 수 있다.
+ */
+export declare function shuffle<T>(arr: readonly T[], rng?: () => number): T[];
+/**
+ * @public 배열에서 무작위로 최대 n개를 뽑아 새 배열로 반환(원본 불변).
+ * n이 길이 이상이면 전체를 셔플해 반환한다.
+ *
+ * 예전엔 그 경우 `arr.slice()`로 **원본 순서를 그대로** 돌려줬다. 주석은 "셔플해
+ * 반환"이라 적혀 있었는데 구현만 달랐던 것이고, 풀이 요청 개수보다 작거나 같으면
+ * 훈련 문항이 늘 같은 순서로 나왔다 — 정렬된 후보 풀에서는 "항상 앞 단어만 뽑히는"
+ * 모습이 된다(WordTrainingTypePreview 가 그 증상 때문에 직접 추출로 우회해 뒀다).
+ */
+export declare function sample<T>(arr: readonly T[], n: number, rng?: () => number): T[];

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

@@ -0,0 +1,36 @@
+/**
+ * 작은 배열 헬퍼 모음. 여러 훅/컴포넌트/게임이 각자 인라인으로 복제하던 순수 로직을 한곳으로 모은다.
+ */
+/** @public 배열에서 from 위치 요소를 to 위치로 옮긴 새 배열을 반환한다(원본 불변). 드래그 재정렬 등에 사용. */
+export function reorderArray(arr, from, to) {
+    const next = arr.slice();
+    const [moved] = next.splice(from, 1);
+    next.splice(to, 0, moved);
+    return next;
+}
+/**
+ * @public Fisher-Yates 셔플 — 새 배열을 반환한다(원본 불변). rng 미지정 시 Math.random.
+ * rng를 주면(시드 PRNG 등) 결정적 셔플이 되어 기기/세션 무관 동일 순서를 만들 수 있다.
+ */
+export function shuffle(arr, rng = Math.random) {
+    const a = arr.slice();
+    for (let i = a.length - 1; i > 0; i--) {
+        const j = Math.floor(rng() * (i + 1));
+        [a[i], a[j]] = [a[j], a[i]];
+    }
+    return a;
+}
+/**
+ * @public 배열에서 무작위로 최대 n개를 뽑아 새 배열로 반환(원본 불변).
+ * n이 길이 이상이면 전체를 셔플해 반환한다.
+ *
+ * 예전엔 그 경우 `arr.slice()`로 **원본 순서를 그대로** 돌려줬다. 주석은 "셔플해
+ * 반환"이라 적혀 있었는데 구현만 달랐던 것이고, 풀이 요청 개수보다 작거나 같으면
+ * 훈련 문항이 늘 같은 순서로 나왔다 — 정렬된 후보 풀에서는 "항상 앞 단어만 뽑히는"
+ * 모습이 된다(WordTrainingTypePreview 가 그 증상 때문에 직접 추출로 우회해 뒀다).
+ */
+export function sample(arr, n, rng = Math.random) {
+    if (!Array.isArray(arr) || arr.length === 0 || n <= 0)
+        return [];
+    return n >= arr.length ? shuffle(arr, rng) : shuffle(arr, rng).slice(0, n);
+}

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

@@ -0,0 +1,41 @@
+/**
+ * 패키지 에셋(로고 등)의 베이스 URL을 설정합니다.
+ *
+ * Vite 등 번들러는 `public/` 에셋에 콘텐츠 해시를 붙이지 않으므로,
+ * 소비자 앱의 `public/` 디렉토리에 패키지 에셋을 복사한 뒤 앱 초기화 시
+ * 이 함수로 베이스 URL을 등록하면 `resolveAssetUrl`이 올바른 경로를 반환합니다.
+ *
+ * ### Vite 소비자 앱 연동 예시
+ * ```ts
+ * // vite.config.ts: 빌드 시 패키지 로고를 public으로 복사
+ * // cp node_modules/@ihabdevteam/core/dist/logo/* public/logo/
+ *
+ * // main.tsx: 앱 시작 시 베이스 URL 등록
+ * import { setAssetBaseUrl } from '@ihabdevteam/core'
+ * setAssetBaseUrl(import.meta.env.BASE_URL) // 예: '/' 또는 '/app/'
+ * ```
+ *
+ * CDN을 사용하는 경우 CDN 오리진을 전달하세요:
+ * ```ts
+ * setAssetBaseUrl('https://cdn.example.com')
+ * ```
+ * @public
+ */
+export declare function setAssetBaseUrl(baseUrl?: string | null): void;
+/** @public */
+export declare function getAssetBaseUrl(): string;
+/**
+ * 에셋 경로를 절대 URL 또는 베이스 URL 기준의 경로로 변환합니다.
+ *
+ * - 이미 절대 URL(`http://`, `//`)이거나 `data:` / `blob:` 형식이면 그대로 반환합니다.
+ * - `setAssetBaseUrl`로 베이스 URL이 등록된 경우 해당 URL을 prefix로 붙입니다.
+ * - 베이스 URL이 없으면 `/logo/Logo_speechear.svg` 형태의 루트 상대 경로를 반환합니다.
+ *
+ * @example
+ * setAssetBaseUrl('https://cdn.example.com')
+ * resolveAssetUrl('logo/Logo_speechear.svg')
+ * // → 'https://cdn.example.com/logo/Logo_speechear.svg'
+ *
+ * @public
+ */
+export declare function resolveAssetUrl(assetPath?: string | null): string;

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

@@ -0,0 +1,62 @@
+const ABSOLUTE_URL_RE = /^(?:[a-z]+:)?\/\//i;
+let configuredAssetBaseUrl = '';
+function normalizeAssetBaseUrl(baseUrl) {
+    const raw = String(baseUrl || '').trim();
+    if (!raw)
+        return '';
+    return raw.replace(/\/+$/, '');
+}
+/**
+ * 패키지 에셋(로고 등)의 베이스 URL을 설정합니다.
+ *
+ * Vite 등 번들러는 `public/` 에셋에 콘텐츠 해시를 붙이지 않으므로,
+ * 소비자 앱의 `public/` 디렉토리에 패키지 에셋을 복사한 뒤 앱 초기화 시
+ * 이 함수로 베이스 URL을 등록하면 `resolveAssetUrl`이 올바른 경로를 반환합니다.
+ *
+ * ### Vite 소비자 앱 연동 예시
+ * ```ts
+ * // vite.config.ts: 빌드 시 패키지 로고를 public으로 복사
+ * // cp node_modules/@ihabdevteam/core/dist/logo/* public/logo/
+ *
+ * // main.tsx: 앱 시작 시 베이스 URL 등록
+ * import { setAssetBaseUrl } from '@ihabdevteam/core'
+ * setAssetBaseUrl(import.meta.env.BASE_URL) // 예: '/' 또는 '/app/'
+ * ```
+ *
+ * CDN을 사용하는 경우 CDN 오리진을 전달하세요:
+ * ```ts
+ * setAssetBaseUrl('https://cdn.example.com')
+ * ```
+ * @public
+ */
+export function setAssetBaseUrl(baseUrl) {
+    configuredAssetBaseUrl = normalizeAssetBaseUrl(baseUrl);
+}
+/** @public */
+export function getAssetBaseUrl() {
+    return configuredAssetBaseUrl;
+}
+/**
+ * 에셋 경로를 절대 URL 또는 베이스 URL 기준의 경로로 변환합니다.
+ *
+ * - 이미 절대 URL(`http://`, `//`)이거나 `data:` / `blob:` 형식이면 그대로 반환합니다.
+ * - `setAssetBaseUrl`로 베이스 URL이 등록된 경우 해당 URL을 prefix로 붙입니다.
+ * - 베이스 URL이 없으면 `/logo/Logo_speechear.svg` 형태의 루트 상대 경로를 반환합니다.
+ *
+ * @example
+ * setAssetBaseUrl('https://cdn.example.com')
+ * resolveAssetUrl('logo/Logo_speechear.svg')
+ * // → 'https://cdn.example.com/logo/Logo_speechear.svg'
+ *
+ * @public
+ */
+export function resolveAssetUrl(assetPath) {
+    const raw = String(assetPath || '').trim();
+    if (!raw)
+        return '';
+    if (ABSOLUTE_URL_RE.test(raw) || raw.startsWith('data:') || raw.startsWith('blob:'))
+        return raw;
+    const normalizedPath = raw.startsWith('/') ? raw : `/${raw}`;
+    const baseUrl = getAssetBaseUrl();
+    return baseUrl ? `${baseUrl}${normalizedPath}` : normalizedPath;
+}

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

@@ -0,0 +1,19 @@
+/**
+ * 오디오 레벨 미터용 Web Audio 유틸.
+ *
+ * HTMLMediaElement를 AnalyserNode에 연결해 실시간 레벨(RMS)을 읽을 수 있게 한다.
+ * - createMediaElementSource는 엘리먼트당 1회만 가능 → WeakMap으로 캐싱.
+ * - 분석을 위해 라우팅하면 destination 연결이 끊기면 무음이 되므로,
+ *   source를 analyser와 destination 양쪽에 연결한다.
+ * - cross-origin 소스는 엘리먼트에 crossOrigin="anonymous"가 설정되고
+ *   서버가 CORS를 허용해야 분석이 가능하다(아니면 0으로 읽힘, 재생은 정상).
+ */
+/** 미터 AudioContext를 사용자 제스처 이후 resume(자동재생 정책 대응). */
+export declare function resumeAudioMeter(): void;
+/**
+ * 엘리먼트에 연결된 AnalyserNode를 반환(없으면 생성·캐싱).
+ * 실패 시 null(미지원/이미 다른 그래프에 소스됨 등).
+ */
+export declare function getElementAnalyser(el: HTMLMediaElement | null | undefined): AnalyserNode | null;
+/** AnalyserNode의 현재 레벨(RMS, 0~1). */
+export declare function readLevel(analyser: AnalyserNode, buffer: Float32Array<ArrayBuffer>): number;

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

@@ -0,0 +1,70 @@
+/**
+ * 오디오 레벨 미터용 Web Audio 유틸.
+ *
+ * HTMLMediaElement를 AnalyserNode에 연결해 실시간 레벨(RMS)을 읽을 수 있게 한다.
+ * - createMediaElementSource는 엘리먼트당 1회만 가능 → WeakMap으로 캐싱.
+ * - 분석을 위해 라우팅하면 destination 연결이 끊기면 무음이 되므로,
+ *   source를 analyser와 destination 양쪽에 연결한다.
+ * - cross-origin 소스는 엘리먼트에 crossOrigin="anonymous"가 설정되고
+ *   서버가 CORS를 허용해야 분석이 가능하다(아니면 0으로 읽힘, 재생은 정상).
+ */
+let _ctx = null;
+const _analysers = new WeakMap();
+function getContext() {
+    if (_ctx)
+        return _ctx;
+    try {
+        const Ctor = window.AudioContext || window.webkitAudioContext;
+        if (!Ctor)
+            return null;
+        _ctx = new Ctor();
+        return _ctx;
+    }
+    catch {
+        return null;
+    }
+}
+/** 미터 AudioContext를 사용자 제스처 이후 resume(자동재생 정책 대응). */
+export function resumeAudioMeter() {
+    try {
+        void _ctx?.resume();
+    }
+    catch { /* noop */ }
+}
+/**
+ * 엘리먼트에 연결된 AnalyserNode를 반환(없으면 생성·캐싱).
+ * 실패 시 null(미지원/이미 다른 그래프에 소스됨 등).
+ */
+export function getElementAnalyser(el) {
+    if (!el)
+        return null;
+    const cached = _analysers.get(el);
+    if (cached)
+        return cached;
+    const ctx = getContext();
+    if (!ctx)
+        return null;
+    try {
+        const source = ctx.createMediaElementSource(el);
+        const analyser = ctx.createAnalyser();
+        analyser.fftSize = 1024;
+        analyser.smoothingTimeConstant = 0.6;
+        source.connect(analyser);
+        source.connect(ctx.destination);
+        _analysers.set(el, analyser);
+        return analyser;
+    }
+    catch {
+        return null;
+    }
+}
+/** AnalyserNode의 현재 레벨(RMS, 0~1). */
+export function readLevel(analyser, buffer) {
+    analyser.getFloatTimeDomainData(buffer);
+    let sum = 0;
+    for (let i = 0; i < buffer.length; i++) {
+        const v = buffer[i];
+        sum += v * v;
+    }
+    return Math.sqrt(sum / buffer.length);
+}

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

@@ -0,0 +1,67 @@
+/**
+ * 훈련 카테고리 데이터 DI — 앱에서 주입하는 함수 기반 인터페이스.
+ *
+ * 패키지는 특정 앱의 카테고리 데이터를 직접 참조하지 않습니다.
+ * configureTrainingCategories()로 한 번 등록하면,
+ * 패키지 내부의 getTopicTypes() / getTrainingTypes()가 해당 데이터를 사용합니다.
+ *
+ * 등록하지 않으면 패키지 내장 기본값(SpeechEar 기본 카테고리)을 사용합니다.
+ *
+ * @example
+ * ```ts
+ * // main.tsx
+ * import { configureTrainingCategories } from '\@ihabdevteam/core'
+ * import { TOPIC_TYPES, TRAINING_TYPES } from './data/categories'
+ *
+ * configureTrainingCategories({ topicTypes: TOPIC_TYPES, trainingTypes: TRAINING_TYPES })
+ * ```
+ *
+ * @public
+ */
+export interface TopicSubType {
+    key: string;
+    label: string;
+}
+/** @public */
+export interface TopicType {
+    key: string;
+    label: string;
+    icon?: string;
+    color?: string;
+    desc?: string;
+    subs?: TopicSubType[];
+}
+/** @public */
+export interface TrainingType {
+    key: string;
+    label: string;
+    icon?: string;
+    desc?: string;
+}
+/** @public */
+export interface TrainingCategoryConfig {
+    topicTypes?: TopicType[];
+    trainingTypes?: TrainingType[];
+}
+/**
+ * 훈련 카테고리 데이터를 런타임에 주입합니다.
+ * 앱 초기화 시점에 한 번만 호출하세요.
+ * 호출하지 않으면 패키지 내장 기본값을 사용합니다.
+ *
+ * @public
+ */
+export declare function configureTrainingCategories(config: TrainingCategoryConfig): void;
+/**
+ * 등록된 주제 카테고리 목록을 반환합니다.
+ * configureTrainingCategories() 미호출 시 기본값을 반환합니다.
+ *
+ * @public
+ */
+export declare function getTopicTypes(): TopicType[];
+/**
+ * 등록된 훈련 타입 목록을 반환합니다.
+ * configureTrainingCategories() 미호출 시 기본값을 반환합니다.
+ *
+ * @public
+ */
+export declare function getTrainingTypes(): TrainingType[];