@ihabdevteam/core 0.8.0

package/dist/packages/core/src/hooks/useVisitHistory.js

@@ -0,0 +1,59 @@
+import { useState } from 'react';
+import { useEditableList } from './useEditableList';
+/**
+ * @public
+ */
+export const today = () => {
+    const now = new Date();
+    return {
+        year: String(now.getFullYear()),
+        month: String(now.getMonth() + 1).padStart(2, '0'),
+        day: String(now.getDate()).padStart(2, '0'),
+    };
+};
+const emptyVisitItem = { year: '', month: '', day: '', hour: '09', minute: '00', memo: '' };
+export function useVisitHistory(initialHistory = []) {
+    const { list: visitHistory, setList: setVisitHistory, selected: selectedVisit, setSelected: setSelectedVisit, isEditing: isEditingVisit, setIsEditing: setIsEditingVisit, editForm: editVisitForm, setEditForm: setEditVisitForm, openDetail: openVisitDetail, commitEdit, } = useEditableList(emptyVisitItem, initialHistory);
+    const { year: ty, month: tm, day: td } = today();
+    const [visitForm, setVisitForm] = useState({ year: ty, month: tm, day: td, hour: '09', minute: '00', memo: '' });
+    const setVisit = (key) => (value) => setVisitForm(prev => ({ ...prev, [key]: value }));
+    const handleVisitSave = (closeSubPopup) => {
+        setVisitHistory(prev => [visitForm, ...prev]);
+        const { year: ny, month: nm, day: nd } = today();
+        setVisitForm({ year: ny, month: nm, day: nd, hour: '09', minute: '00', memo: '' });
+        closeSubPopup?.();
+    };
+    const handleVisitEditSave = () => {
+        commitEdit(prev => prev.map(v => v === selectedVisit ? editVisitForm : v), editVisitForm);
+    };
+    /** 외부(스케줄 훅 등)에서 방문이력에 항목을 추가할 때 사용 */
+    const addVisit = (item) => {
+        setVisitHistory(prev => [item, ...prev]);
+    };
+    /** 외부에서 낙관적으로 추가한 항목을 되돌릴 때 사용(예: 서버 저장 실패 롤백).
+     *  선택 상태는 건드리지 않는다 — remove()와 달리 사용자가 보고 있는 다른 항목의 상세뷰를
+     *  건드리면 안 되는 백그라운드 정정이기 때문. addVisit에 넘긴 것과 동일 참조로 호출해야 한다. */
+    const removeVisit = (item) => {
+        setVisitHistory(prev => prev.filter(v => v !== item));
+    };
+    /** 낙관적으로 반영한 수정을 되돌릴 때 사용(예: 서버 수정 실패 롤백) — edited로 바뀐 항목을
+     *  original로 복원한다. handleVisitEditSave가 commitEdit으로 이미 edited를 반영한 뒤라,
+     *  이번엔 selected도 함께 되돌려야 사용자가 보고 있던 상세뷰가 옛 값으로 남는다. */
+    const revertVisitEdit = (original, edited) => {
+        setVisitHistory(prev => prev.map(v => v === edited ? original : v));
+        setSelectedVisit(prev => prev === edited ? original : prev);
+    };
+    return {
+        visitHistory,
+        visitForm, setVisitForm, setVisit,
+        selectedVisit, setSelectedVisit,
+        isEditingVisit, setIsEditingVisit,
+        editVisitForm, setEditVisitForm,
+        openVisitDetail,
+        handleVisitSave,
+        handleVisitEditSave,
+        addVisit,
+        removeVisit,
+        revertVisitEdit,
+    };
+}

package/dist/packages/core/src/hooks/useVisitSchedule.d.ts

@@ -0,0 +1,31 @@
+import { type VisitItem } from './useVisitHistory';
+export type ScheduleItem = VisitItem;
+/**
+ * @public
+ */
+export declare function useVisitSchedule(
+/** 방문 완료 시 방문이력 추가 콜백 (useVisitHistory의 addVisit) */
+addVisit: (item: VisitItem) => void, 
+/** 초기 예약 목록(서버 실데이터 등) */
+initialSchedule?: ScheduleItem[]): {
+    scheduleList: VisitItem[];
+    noShowList: VisitItem[];
+    addSchedule: (item: ScheduleItem) => void;
+    removeSchedule: (item: ScheduleItem) => void;
+    revertScheduleEdit: (original: ScheduleItem, edited: ScheduleItem) => void;
+    scheduleForm: VisitItem;
+    setScheduleForm: import("react").Dispatch<import("react").SetStateAction<VisitItem>>;
+    setSchedule: (key: keyof ScheduleItem) => (value: string) => void;
+    selectedSchedule: VisitItem | null;
+    setSelectedSchedule: import("react").Dispatch<import("react").SetStateAction<VisitItem | null>>;
+    isEditingSchedule: boolean;
+    setIsEditingSchedule: import("react").Dispatch<import("react").SetStateAction<boolean>>;
+    editScheduleForm: VisitItem;
+    setEditScheduleForm: import("react").Dispatch<import("react").SetStateAction<VisitItem>>;
+    openScheduleDetail: (item: VisitItem) => void;
+    handleScheduleSave: (closeSubPopup?: () => void) => void;
+    handleScheduleEditSave: () => void;
+    handleScheduleDelete: (item: ScheduleItem) => void;
+    handleScheduleToVisit: (item: ScheduleItem) => void;
+    handleScheduleNoVisit: (item: ScheduleItem) => void;
+};

package/dist/packages/core/src/hooks/useVisitSchedule.js

@@ -0,0 +1,101 @@
+'use client';
+import { useCallback, useMemo, useState } from 'react';
+import { today } from './useVisitHistory';
+import { useEditableList } from './useEditableList';
+/**
+ * 차례를 정하는 열쇠 — **가까운 것이 위**.
+ *
+ * 세 가지가 어긋나 있었다.
+ *  · 날짜까지만 봤다. 같은 날 09시와 15시가 아무렇게나 놓였다.
+ *  · 월·일을 채우지 않고 글자로 견줬다. '2026-9-2' 는 '2026-12-31' 보다 **뒤로** 간다
+ *    (9 > 1). 지금 오는 값은 채워져 있지만, 열쇠가 그것에 기대고 있을 이유가 없다.
+ * 같을 때 0 대신 1 을 돌려주던 것도 3방향으로 고쳤다. 다만 **눈에 보이는 차이는
+ * 없었다** — V8 의 TimSort 는 같은 값 구간에서 비교를 아예 안 불러, 뒤섞인 자료로
+ * 재 봐도 결과가 같았다(실측). 그래서 이 한 가지는 시험으로 못 박는다.
+ */
+const 정렬키 = (v) => `${v.year.padStart(4, '0')}-${v.month.padStart(2, '0')}-${v.day.padStart(2, '0')}` +
+    ` ${v.hour.padStart(2, '0')}:${v.minute.padStart(2, '0')}`;
+const sortByDate = (list) => [...list].sort((a, b) => {
+    const x = 정렬키(a), y = 정렬키(b);
+    return x < y ? -1 : x > y ? 1 : 0;
+});
+const emptyScheduleItem = { year: '', month: '', day: '', hour: '09', minute: '00', memo: '' };
+/**
+ * @public
+ */
+export function useVisitSchedule(
+/** 방문 완료 시 방문이력 추가 콜백 (useVisitHistory의 addVisit) */
+addVisit, 
+/** 초기 예약 목록(서버 실데이터 등) */
+initialSchedule = []) {
+    /* **처음 받은 목록도 정렬한다.** 예전에는 넣고 고칠 때만 정렬해서, 팝업을 열면
+       서버가 준 차례(visited_at 내림차순) 그대로 먼 날짜가 위에 있다가 예정을 하나
+       등록하는 순간 목록이 통째로 뒤집혔다.
+       useMemo 로 묶는 것은 성능 때문이 아니라 **되돌이를 막기 위해서다** —
+       useEditableList 는 초기 목록을 원소 참조로 견주는데, 렌더마다 새 배열을 만들면
+       원소는 같아도 매번 setList 가 돌아 무한 렌더가 된다. */
+    const 정렬된초기목록 = useMemo(() => sortByDate(initialSchedule), [initialSchedule]);
+    const { list: scheduleList, setList: setScheduleList, selected: selectedSchedule, setSelected: setSelectedSchedule, isEditing: isEditingSchedule, setIsEditing: setIsEditingSchedule, editForm: editScheduleForm, setEditForm: setEditScheduleForm, openDetail: openScheduleDetail, commitEdit, remove, } = useEditableList(emptyScheduleItem, 정렬된초기목록);
+    /** 미방문 처리된 예약 — 삭제하지 않고 보존해 통합 방문 목록에서 뱃지로 표시 */
+    const [noShowList, setNoShowList] = useState([]);
+    const { year: ty, month: tm, day: td } = today();
+    const [scheduleForm, setScheduleForm] = useState({ year: ty, month: tm, day: td, hour: '09', minute: '00', memo: '' });
+    const setSchedule = (key) => (value) => setScheduleForm(prev => ({ ...prev, [key]: value }));
+    const handleScheduleSave = (closeSubPopup) => {
+        setScheduleList(prev => sortByDate([...prev, scheduleForm]));
+        const { year: ny, month: nm, day: nd } = today();
+        setScheduleForm({ year: ny, month: nm, day: nd, hour: '09', minute: '00', memo: '' });
+        closeSubPopup?.();
+    };
+    const handleScheduleEditSave = () => {
+        commitEdit(prev => sortByDate(prev.map(v => v === selectedSchedule ? editScheduleForm : v)), editScheduleForm);
+    };
+    const handleScheduleDelete = useCallback((item) => {
+        remove(item);
+    }, [remove]);
+    const handleScheduleToVisit = useCallback((item) => {
+        addVisit({ year: item.year, month: item.month, day: item.day, hour: item.hour, minute: item.minute, memo: item.memo });
+        remove(item);
+    }, [addVisit, remove]);
+    const handleScheduleNoVisit = useCallback((item) => {
+        setScheduleList(prev => prev.filter(v => v !== item));
+        setNoShowList(prev => [item, ...prev]);
+        setSelectedSchedule(null);
+    }, [setScheduleList, setSelectedSchedule]);
+    /** 외부에서 예약을 직접 추가할 때 사용 (통합 방문 등록 폼의 미래 날짜 분기) */
+    const addSchedule = useCallback((item) => {
+        setScheduleList(prev => sortByDate([...prev, item]));
+    }, [setScheduleList]);
+    /** 외부에서 낙관적으로 추가한 예약을 되돌릴 때 사용(예: 서버 저장 실패 롤백).
+     *  handleScheduleDelete(=remove)와 달리 선택 상태는 건드리지 않는다 — 사용자가 보고 있는
+     *  다른 항목의 상세뷰를 건드리면 안 되는 백그라운드 정정이기 때문. addSchedule에 넘긴 것과
+     *  동일 참조로 호출해야 한다. */
+    const removeSchedule = useCallback((item) => {
+        setScheduleList(prev => prev.filter(v => v !== item));
+    }, [setScheduleList]);
+    /** 낙관적으로 반영한 수정을 되돌린다 — 서버가 거절했을 때.
+     *  방문 쪽 revertVisitEdit 과 같은 규칙이다: 목록의 그 항목을 옛 것으로 되돌리고,
+     *  보고 있던 상세도 함께 되돌린다(안 되돌리면 상세에는 새 값이 남는다).
+     *  handleScheduleEditSave 가 이미 edited 를 반영한 뒤에 부른다. */
+    const revertScheduleEdit = useCallback((original, edited) => {
+        setScheduleList(prev => prev.map(v => v === edited ? original : v));
+        setSelectedSchedule(prev => prev === edited ? original : prev);
+    }, [setScheduleList, setSelectedSchedule]);
+    return {
+        scheduleList,
+        noShowList,
+        addSchedule,
+        removeSchedule,
+        revertScheduleEdit,
+        scheduleForm, setScheduleForm, setSchedule,
+        selectedSchedule, setSelectedSchedule,
+        isEditingSchedule, setIsEditingSchedule,
+        editScheduleForm, setEditScheduleForm,
+        openScheduleDetail,
+        handleScheduleSave,
+        handleScheduleEditSave,
+        handleScheduleDelete,
+        handleScheduleToVisit,
+        handleScheduleNoVisit,
+    };
+}

package/dist/packages/core/src/hooks/useWindowEvent.d.ts

@@ -0,0 +1,11 @@
+/**
+ * window 커스텀 이벤트를 구독하는 훅.
+ * handler는 ref로 래핑하므로 매번 새 함수를 넘겨도 재구독하지 않음.
+ *
+ * @example
+ * useWindowEvent('speechear.data.updated', () => setTick(t => t + 1))
+ */
+/**
+ * @public
+ */
+export declare function useWindowEvent(eventName: string, handler: () => void): void;

package/dist/packages/core/src/hooks/useWindowEvent.js

@@ -0,0 +1,27 @@
+'use client';
+import { useEffect } from 'react';
+import { useLatestRef } from './useLatestRef';
+/**
+ * window 커스텀 이벤트를 구독하는 훅.
+ * handler는 ref로 래핑하므로 매번 새 함수를 넘겨도 재구독하지 않음.
+ *
+ * @example
+ * useWindowEvent('speechear.data.updated', () => setTick(t => t + 1))
+ */
+/**
+ * @public
+ */
+export function useWindowEvent(eventName, handler) {
+    const handlerRef = useLatestRef(handler);
+    useEffect(() => {
+        const fn = () => handlerRef.current();
+        try {
+            window.addEventListener(eventName, fn);
+        }
+        catch (_e) { }
+        return () => { try {
+            window.removeEventListener(eventName, fn);
+        }
+        catch (_e) { } };
+    }, [eventName, handlerRef]);
+}

package/dist/packages/core/src/hooks/useWordAttributeFilter.d.ts

@@ -0,0 +1,70 @@
+import { type ReactNode } from 'react';
+import type { TFunction } from 'i18next';
+import { type FilterPanelSection } from '../types/filterPanel';
+/**
+ * 등급/음절수/품사/어종 필터의 공용 i18n 키+맵.
+ * 단어표(useWordSearch)·대립쌍표(useWordPairsSearch)·단어훈련(useWordTrainingFilter)이
+ * 모두 이 키로 섹션 라벨을 만들어 세 화면에서 동일한 표시 문구·매칭 규칙(posMap/typeMap)을 쓴다.
+ * @public
+ */
+export interface WordAttributeFilterKeys {
+    difficulty: string;
+    syllables: string;
+    syllable5plus: string;
+    partOfSpeech: string;
+    wordType: string;
+    posMap: Record<string, string[]>;
+    typeMap: Record<string, string>;
+}
+/**
+ * @public
+ * 등급/음절수/품사/어종 필터의 공용 라벨+매핑을 만든다. 세 화면(단어표/대립쌍표/단어훈련)이
+ * 이 훅을 함께 호출해 라벨 문구와 posMap/typeMap(품사·어종 판정 규칙)을 어긋나지 않게 공유한다.
+ */
+export declare function useWordAttributeFilterKeys(): WordAttributeFilterKeys;
+/** @public 등급(1~4등급) FilterPanelSection — 세 화면 공용. labelAction/allLabel은 호출부가 자신의 i18n으로 구성해 넘긴다. */
+export declare function buildGradeSection(t: TFunction, keys: WordAttributeFilterKeys, opts?: {
+    allLabel?: string;
+    labelAction?: ReactNode;
+}): FilterPanelSection;
+/** @public 품사 FilterPanelSection — 세 화면 공용. */
+export declare function buildPartOfSpeechSection(keys: WordAttributeFilterKeys): FilterPanelSection;
+/** @public 어종 FilterPanelSection — 세 화면 공용. */
+export declare function buildWordTypeSection(keys: WordAttributeFilterKeys): FilterPanelSection;
+/** @public 음절 수(1~4·5음절 이상) FilterPanelSection — 단어표·대립쌍표 공용(항목·라벨 완전 동일). */
+export declare function buildSyllableSection(t: TFunction, keys: WordAttributeFilterKeys): FilterPanelSection;
+/**
+ * @public '선택' 섹션(긍정형 다중 토글) FilterPanelSection — 단어표·대립쌍표 공용.
+ * 기본은 '이미지 있는 단어만' 1개. includeStructure면 '음소 구조 같은 단어만'을 추가한다(대립쌍표).
+ * 라벨/항목 문구는 wordPairs.filter.* 키로 통일(단어표의 wordSearch.filter.* 키와 문구가 동일).
+ * labelAction(정보 툴팁)은 호출부가 자신의 안내 문구로 구성해 넘긴다.
+ */
+export declare function buildSelectSection(t: TFunction, opts?: {
+    includeStructure?: boolean;
+    labelAction?: ReactNode;
+}): FilterPanelSection;
+/**
+ * @public 위치(어두/어중/어말) FilterPanelSection 빌더 — WordSearchPage·단어훈련 만들기(메인 앱)가 공용.
+ * 라벨 문구(무관/어두/어중/어말)는 wordSearch.filter.position* 키로 통일해 여러 화면에서 항상 같게 나온다.
+ * value는 호출부가 넘긴다 — 선택 상태 키로 그대로 쓰이는 경우가 많아 호출부 사정에 맞춰야 하기 때문이다.
+ */
+export declare function buildPositionSection(t: TFunction, opts: {
+    label: string;
+    headValue: string;
+    midValue: string;
+    tailValue: string;
+    /** 어중(가운데) 항목 노출 여부 — 정답이 항상 2음절인 타입 등에서 제외. 기본 true. */
+    includeMid?: boolean;
+    headDisabled?: boolean;
+    midDisabled?: boolean;
+    tailDisabled?: boolean;
+    allOptionDisabled?: boolean;
+    groupLabel?: string;
+    labelAction?: ReactNode;
+}): FilterPanelSection;
+/**
+ * @public 긍정형 다중 토글 섹션의 filterSelected 갱신 헬퍼 — 단어표·대립쌍표 공용.
+ * '전체'(FILTER_ALL_VALUE)면 해당 섹션 해제, 그 외엔 값 토글, 남은 값이 없으면 key 자체를 제거한다.
+ * (FilterPanel은 로케일과 무관하게 FILTER_ALL_VALUE를 방출하므로 t('common.all', '전체')과 비교하면 안 된다.)
+ */
+export declare function toggleAttributeFilter(prev: Record<string, string[]>, value: string, sectionLabel: string): Record<string, string[]>;

package/dist/packages/core/src/hooks/useWordAttributeFilter.js

@@ -0,0 +1,115 @@
+'use client';
+import { useMemo } from 'react';
+import { useTranslation } from 'react-i18next';
+import { FILTER_ALL_VALUE } from '../types/filterPanel';
+/**
+ * @public
+ * 등급/음절수/품사/어종 필터의 공용 라벨+매핑을 만든다. 세 화면(단어표/대립쌍표/단어훈련)이
+ * 이 훅을 함께 호출해 라벨 문구와 posMap/typeMap(품사·어종 판정 규칙)을 어긋나지 않게 공유한다.
+ */
+export function useWordAttributeFilterKeys() {
+    const { t } = useTranslation();
+    return useMemo(() => ({
+        difficulty: t('wordSearch.filter.difficulty', '등급'),
+        syllables: t('wordSearch.filter.syllables', '음절 수'),
+        syllable5plus: t('wordSearch.filter.syllable5plus', '5음절 이상'),
+        partOfSpeech: t('wordSearch.filter.partOfSpeech', '품사'),
+        wordType: t('wordSearch.filter.wordType', '유형'),
+        posMap: {
+            [t('wordSearch.filter.pos.noun', '체언(명사, 수사)')]: ['명', '수'],
+            [t('wordSearch.filter.pos.verb', '용언(동사, 형용사)')]: ['동', '형'],
+            [t('wordSearch.filter.pos.modifier', '수식언(부사, 관형사)')]: ['부', '관'],
+        },
+        typeMap: {
+            [t('wordSearch.filter.type.native', '고유어')]: '고유',
+            [t('wordSearch.filter.type.sino', '한자어')]: '한자',
+            [t('wordSearch.filter.type.foreign', '외래어')]: '외래',
+            [t('wordSearch.filter.type.mixed', '혼종어')]: '혼종',
+        },
+    }), [t]);
+}
+/** @public 등급(1~4등급) FilterPanelSection — 세 화면 공용. labelAction/allLabel은 호출부가 자신의 i18n으로 구성해 넘긴다. */
+export function buildGradeSection(t, keys, opts) {
+    return {
+        label: keys.difficulty,
+        items: [1, 2, 3, 4].map(n => t('wordSearch.filter.grade', { n })),
+        multiple: true,
+        allOption: true,
+        allLabel: opts?.allLabel,
+        labelAction: opts?.labelAction,
+    };
+}
+/** @public 품사 FilterPanelSection — 세 화면 공용. */
+export function buildPartOfSpeechSection(keys) {
+    return { label: keys.partOfSpeech, items: Object.keys(keys.posMap), multiple: true, allOption: true };
+}
+/** @public 어종 FilterPanelSection — 세 화면 공용. */
+export function buildWordTypeSection(keys) {
+    return { label: keys.wordType, items: Object.keys(keys.typeMap), multiple: true, allOption: true };
+}
+/** @public 음절 수(1~4·5음절 이상) FilterPanelSection — 단어표·대립쌍표 공용(항목·라벨 완전 동일). */
+export function buildSyllableSection(t, keys) {
+    return {
+        label: keys.syllables,
+        items: [
+            t('wordSearch.filter.syllable', { n: 1 }),
+            t('wordSearch.filter.syllable', { n: 2 }),
+            t('wordSearch.filter.syllable', { n: 3 }),
+            t('wordSearch.filter.syllable', { n: 4 }),
+            keys.syllable5plus,
+        ],
+        multiple: true,
+        allOption: true,
+    };
+}
+/**
+ * @public '선택' 섹션(긍정형 다중 토글) FilterPanelSection — 단어표·대립쌍표 공용.
+ * 기본은 '이미지 있는 단어만' 1개. includeStructure면 '음소 구조 같은 단어만'을 추가한다(대립쌍표).
+ * 라벨/항목 문구는 wordPairs.filter.* 키로 통일(단어표의 wordSearch.filter.* 키와 문구가 동일).
+ * labelAction(정보 툴팁)은 호출부가 자신의 안내 문구로 구성해 넘긴다.
+ */
+export function buildSelectSection(t, opts) {
+    const items = [t('wordPairs.filter.onlyHasImage', '이미지 있는 단어만')];
+    if (opts?.includeStructure)
+        items.push(t('wordPairs.filter.onlySameStructure', '음소 구조 같은 단어만'));
+    return { label: t('wordPairs.filter.selectLabel', '선택'), items, multiple: true, labelAction: opts?.labelAction };
+}
+/**
+ * @public 위치(어두/어중/어말) FilterPanelSection 빌더 — WordSearchPage·단어훈련 만들기(메인 앱)가 공용.
+ * 라벨 문구(무관/어두/어중/어말)는 wordSearch.filter.position* 키로 통일해 여러 화면에서 항상 같게 나온다.
+ * value는 호출부가 넘긴다 — 선택 상태 키로 그대로 쓰이는 경우가 많아 호출부 사정에 맞춰야 하기 때문이다.
+ */
+export function buildPositionSection(t, opts) {
+    const { label, headValue, midValue, tailValue, includeMid = true, headDisabled, midDisabled, tailDisabled, allOptionDisabled, groupLabel, labelAction } = opts;
+    return {
+        label,
+        ...(groupLabel ? { groupLabel } : {}),
+        ...(labelAction ? { labelAction } : {}),
+        allOption: true,
+        allLabel: t('wordSearch.filter.positionAny', { defaultValue: '무관' }),
+        ...(allOptionDisabled ? { allOptionDisabled } : {}),
+        items: [
+            { value: headValue, displayLabel: t('wordSearch.filter.positionHead', { defaultValue: '어두' }), disabled: headDisabled },
+            ...(includeMid ? [{ value: midValue, displayLabel: t('wordSearch.filter.positionMid', { defaultValue: '어중' }), disabled: midDisabled }] : []),
+            { value: tailValue, displayLabel: t('wordSearch.filter.positionTail', { defaultValue: '어말' }), disabled: tailDisabled },
+        ],
+    };
+}
+/**
+ * @public 긍정형 다중 토글 섹션의 filterSelected 갱신 헬퍼 — 단어표·대립쌍표 공용.
+ * '전체'(FILTER_ALL_VALUE)면 해당 섹션 해제, 그 외엔 값 토글, 남은 값이 없으면 key 자체를 제거한다.
+ * (FilterPanel은 로케일과 무관하게 FILTER_ALL_VALUE를 방출하므로 t('common.all', '전체')과 비교하면 안 된다.)
+ */
+export function toggleAttributeFilter(prev, value, sectionLabel) {
+    if (value === FILTER_ALL_VALUE) {
+        const { [sectionLabel]: _omit, ...rest } = prev;
+        return rest;
+    }
+    const cur = prev[sectionLabel] ?? [];
+    const next = cur.includes(value) ? cur.filter(v => v !== value) : [...cur, value];
+    if (next.length === 0) {
+        const { [sectionLabel]: _omit, ...rest } = prev;
+        return rest;
+    }
+    return { ...prev, [sectionLabel]: next };
+}

package/dist/packages/core/src/hooks/useWordDataStats.d.ts

@@ -0,0 +1,22 @@
+export interface PairStats {
+    matched: number;
+    total: number;
+}
+export interface ImgStats {
+    exists: number;
+    total: number;
+}
+/**
+ * 단어쌍 인덱스와 이미지 캐시 현황을 읽어 반환하는 훅.
+ * `words` 의존성이 변경될 때마다 1초 뒤 갱신 (비동기 빌드 완료 대기).
+ */
+/**
+ * @public
+ */
+export declare function useWordDataStats(words?: unknown[]): {
+    pairStats: PairStats | null;
+    imgStats: ImgStats | null;
+    setPairStats: import("react").Dispatch<import("react").SetStateAction<PairStats | null>>;
+    setImgStats: import("react").Dispatch<import("react").SetStateAction<ImgStats | null>>;
+    refreshStats: () => void;
+};

package/dist/packages/core/src/hooks/useWordDataStats.js

@@ -0,0 +1,40 @@
+'use client';
+import { useCallback, useEffect, useState } from 'react';
+import { getPairIndex } from '../utils/wordPairIndex';
+import { getImageExistenceStats } from '../utils/imageConfig';
+/**
+ * 단어쌍 인덱스와 이미지 캐시 현황을 읽어 반환하는 훅.
+ * `words` 의존성이 변경될 때마다 1초 뒤 갱신 (비동기 빌드 완료 대기).
+ */
+/**
+ * @public
+ */
+export function useWordDataStats(words) {
+    const [pairStats, setPairStats] = useState(null);
+    const [imgStats, setImgStats] = useState(null);
+    const refreshStats = useCallback(() => {
+        const idx = getPairIndex();
+        if (idx) {
+            const entries = Object.values(idx);
+            const matched = entries.filter(e => e.cho.length + e.jung.length + e.jong.length > 0).length;
+            setPairStats({ matched, total: entries.length });
+        }
+        else {
+            setPairStats(null);
+        }
+        const img = getImageExistenceStats();
+        if (img)
+            setImgStats({ exists: img.exists, total: img.total });
+        else
+            setImgStats(null);
+    }, []);
+    // refreshStats는 외부(모듈 레벨) 인덱스/캐시 상태를 동기 반영하는 의도된 fetch-kickoff이다
+    /* eslint-disable react-hooks/set-state-in-effect */
+    useEffect(() => {
+        refreshStats();
+        const t = setTimeout(refreshStats, 1000);
+        return () => clearTimeout(t);
+    }, [words, refreshStats]);
+    /* eslint-enable react-hooks/set-state-in-effect */
+    return { pairStats, imgStats, setPairStats, setImgStats, refreshStats };
+}

package/dist/packages/core/src/hooks/useWordImage.d.ts

@@ -0,0 +1,19 @@
+/**
+ * @public 단어 이미지 로딩 상태 훅 — 단어표 셀·단어 이미지 툴팁·훈련 카드가 공용으로 쓴다.
+ * imageUrl은 호출부에서 해석해 넘긴다(resolver + item.image 등 fallback 규칙이 화면마다 달라서).
+ *
+ * 반환한 `imgRef`를 `<img>`에 달고 `onLoad`/`onError`를 연결한 뒤, `loading`으로 스피너를,
+ * `hasImage`로 이미지/텍스트 fallback을 분기한다.
+ *
+ * 캐시된 이미지는 마운트 시 이미 complete라 onLoad가 안 떠 스피너가 멈추는 문제가 있어,
+ * imageUrl 변경 effect에서 imgRef의 complete를 직접 확인해 이미 로드됐으면 스피너를 켜지 않는다
+ * (예: 저장 팝업 미리보기처럼 이미 그려진 표의 이미지를 다시 그릴 때).
+ */
+export declare function useWordImage(imageUrl: string): {
+    imgRef: import("react").RefObject<HTMLImageElement | null>;
+    loading: boolean;
+    failed: boolean;
+    hasImage: boolean;
+    onLoad: () => void;
+    onError: () => void;
+};

package/dist/packages/core/src/hooks/useWordImage.js

@@ -0,0 +1,28 @@
+'use client';
+import { useCallback, useEffect, useRef, useState } from 'react';
+/**
+ * @public 단어 이미지 로딩 상태 훅 — 단어표 셀·단어 이미지 툴팁·훈련 카드가 공용으로 쓴다.
+ * imageUrl은 호출부에서 해석해 넘긴다(resolver + item.image 등 fallback 규칙이 화면마다 달라서).
+ *
+ * 반환한 `imgRef`를 `<img>`에 달고 `onLoad`/`onError`를 연결한 뒤, `loading`으로 스피너를,
+ * `hasImage`로 이미지/텍스트 fallback을 분기한다.
+ *
+ * 캐시된 이미지는 마운트 시 이미 complete라 onLoad가 안 떠 스피너가 멈추는 문제가 있어,
+ * imageUrl 변경 effect에서 imgRef의 complete를 직접 확인해 이미 로드됐으면 스피너를 켜지 않는다
+ * (예: 저장 팝업 미리보기처럼 이미 그려진 표의 이미지를 다시 그릴 때).
+ */
+export function useWordImage(imageUrl) {
+    const imgRef = useRef(null);
+    const [loading, setLoading] = useState(!!imageUrl);
+    const [failed, setFailed] = useState(false);
+    /* eslint-disable react-hooks/set-state-in-effect */
+    useEffect(() => {
+        setFailed(false);
+        const img = imgRef.current;
+        setLoading(!!imageUrl && !(img?.complete && img.naturalWidth > 0));
+    }, [imageUrl]);
+    /* eslint-enable react-hooks/set-state-in-effect */
+    const onLoad = useCallback(() => setLoading(false), []);
+    const onError = useCallback(() => { setLoading(false); setFailed(true); }, []);
+    return { imgRef, loading, failed, hasImage: !!imageUrl && !failed, onLoad, onError };
+}

package/dist/packages/core/src/hooks/useWordMeanings.d.ts

@@ -0,0 +1,39 @@
+/**
+ * 화면에 보이는 단어들의 뜻(Meaning)만 조회한다.
+ *
+ * 뜻 전체는 ~1.3MB 라 단어 목록 캐시에 함께 넣으면 localStorage 한도(5MB)에 바로 닿는다.
+ * 그래서 목록에는 넣지 않고 **지금 그려질 행만** 그때그때 받아 메모리에만 둔다.
+ *
+ * ── 왜 여기 있나 ──
+ * 어드민과 회원 앱이 같은 것을 각자 한 벌씩 들고 있었다. 로직은 한 글자도 다르지 않았고
+ * 다른 것은 어느 Supabase 클라이언트를 쓰느냐 하나뿐이었다(회원 앱은 supabaseSub).
+ * 그것만 다르면 될 일에 파일을 둘 두면, 한쪽만 고쳐 놓고 다른 쪽은 옛 규칙으로 남는
+ * 날이 온다.
+ *
+ * 캐시는 **모듈 스코프**다. 한 앱 안에서 공유되고, 어드민과 회원 앱은 애초에 다른
+ * 번들이라 섞이지 않는다.
+ *
+ * 클라이언트 자체가 아니라 **조회 함수**를 받는다. 클라이언트를 받으면 core 가
+ * supabase-js 의 제네릭을 끌어안게 되고(실제로 타입 검사가 '너무 깊다'며 터졌다),
+ * 무엇보다 core 가 저장소가 무엇인지 알 이유가 없다.
+ */
+/** 단어+동음이의어 번호 → 뜻 조회 키 */
+export declare const meaningKey: (word: string, homonum?: number) => string;
+/** 뜻을 실어 오는 한 줄 */
+export interface WordMeaningRow {
+    Word: string;
+    Homonum?: number | null;
+    Meaning?: string | null;
+}
+/**
+ * 낱말들의 뜻을 받아 오는 함수. 실패는 빈 배열로 — 뜻은 있으면 좋은 것이라,
+ * 못 받았다고 화면을 멈출 이유가 없다.
+ *
+ * **매 렌더 새로 만들지 말 것.** 아래 useEffect 의 의존성이라, 새 함수가 오면
+ * 같은 낱말을 계속 다시 받는다. 모듈 스코프 상수나 useCallback 으로 둔다.
+ */
+export type WordMeaningFetcher = (words: string[]) => Promise<WordMeaningRow[]>;
+export declare function useWordMeanings(rows: {
+    word: string;
+    homonum?: number;
+}[], fetchMeanings: WordMeaningFetcher): Map<string, string>;

package/dist/packages/core/src/hooks/useWordMeanings.js

@@ -0,0 +1,62 @@
+'use client';
+import { useState, useEffect, useMemo } from 'react';
+/**
+ * 화면에 보이는 단어들의 뜻(Meaning)만 조회한다.
+ *
+ * 뜻 전체는 ~1.3MB 라 단어 목록 캐시에 함께 넣으면 localStorage 한도(5MB)에 바로 닿는다.
+ * 그래서 목록에는 넣지 않고 **지금 그려질 행만** 그때그때 받아 메모리에만 둔다.
+ *
+ * ── 왜 여기 있나 ──
+ * 어드민과 회원 앱이 같은 것을 각자 한 벌씩 들고 있었다. 로직은 한 글자도 다르지 않았고
+ * 다른 것은 어느 Supabase 클라이언트를 쓰느냐 하나뿐이었다(회원 앱은 supabaseSub).
+ * 그것만 다르면 될 일에 파일을 둘 두면, 한쪽만 고쳐 놓고 다른 쪽은 옛 규칙으로 남는
+ * 날이 온다.
+ *
+ * 캐시는 **모듈 스코프**다. 한 앱 안에서 공유되고, 어드민과 회원 앱은 애초에 다른
+ * 번들이라 섞이지 않는다.
+ *
+ * 클라이언트 자체가 아니라 **조회 함수**를 받는다. 클라이언트를 받으면 core 가
+ * supabase-js 의 제네릭을 끌어안게 되고(실제로 타입 검사가 '너무 깊다'며 터졌다),
+ * 무엇보다 core 가 저장소가 무엇인지 알 이유가 없다.
+ */
+/** 단어+동음이의어 번호 → 뜻 조회 키 */
+export const meaningKey = (word, homonum) => `${word}:${homonum ?? 1}`;
+// 세션 동안 유지되는 메모리 캐시 — 페이지를 오가도 재조회하지 않는다
+const memCache = new Map();
+export function useWordMeanings(rows, fetchMeanings) {
+    /* 캐시는 모듈 스코프 Map 이라 갱신이 렌더에 자동 반영되지 않는다 — 조회가 끝나면 이 값을
+       올려 아래 스냅샷을 다시 계산시킨다(캐시 히트만으로 리렌더가 연쇄되지 않도록 분리). */
+    const [fetched, setFetched] = useState(0);
+    // rows 는 매 렌더 새 배열이라 의존성으로 쓸 수 없다 — 조회 키만 뽑아 문자열로 비교한다
+    const wantedKey = rows.map(r => meaningKey(r.word, r.homonum)).join('|');
+    useEffect(() => {
+        const wanted = wantedKey ? wantedKey.split('|') : [];
+        const missing = wanted.filter(k => !memCache.has(k));
+        if (missing.length === 0)
+            return; // 전부 캐시에 있음 — 네트워크·상태 갱신 불필요
+        let cancelled = false;
+        const words = Array.from(new Set(missing.map(k => k.slice(0, k.lastIndexOf(':')))));
+        void fetchMeanings(words).then(got => {
+            if (cancelled || got.length === 0)
+                return;
+            for (const row of got) {
+                if (row.Meaning)
+                    memCache.set(meaningKey(row.Word, row.Homonum ?? undefined), row.Meaning);
+            }
+            setFetched(v => v + 1);
+        });
+        return () => { cancelled = true; };
+    }, [wantedKey, fetchMeanings]);
+    return useMemo(() => {
+        const wanted = wantedKey ? wantedKey.split('|') : [];
+        const out = new Map();
+        for (const k of wanted) {
+            const v = memCache.get(k);
+            if (v != null)
+                out.set(k, v);
+        }
+        return out;
+        // fetched 는 캐시 갱신 신호 — 값 자체는 쓰지 않지만 재계산 트리거로 필요하다
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [wantedKey, fetched]);
+}