@ihabdevteam/core 0.8.0

package/dist/packages/core/src/context/WordDataContext.d.ts

@@ -0,0 +1,25 @@
+import type { WordEntry } from '../utils/phonemePairSearch';
+export type { WordEntry } from '../utils/phonemePairSearch';
+export type WordDataPhase = 'idle' | 'word-download' | 'image-list' | 'image-match' | 'pair-build' | 'done';
+export interface WordDataProgress {
+    phase: WordDataPhase;
+    error?: boolean;
+    wordCount?: number;
+    imagePage?: number;
+    imageDone?: number;
+    imageTotal?: number;
+    pairPercent?: number;
+}
+export interface WordDataContextValue {
+    words: WordEntry[];
+    loading: boolean;
+    error?: boolean;
+    statusMessage?: string;
+    localVersion?: string;
+    remoteVersion?: string;
+    progress?: WordDataProgress;
+    clearAndRefetch?: () => Promise<void>;
+    checkRemoteVersion?: () => Promise<void>;
+}
+export declare const WordDataContext: import("react").Context<WordDataContextValue>;
+export declare function useWordData(): WordDataContextValue;

package/dist/packages/core/src/context/WordDataContext.js

@@ -0,0 +1,6 @@
+'use client';
+import { createContext, useContext } from 'react';
+export const WordDataContext = createContext({ words: [], loading: false });
+export function useWordData() {
+    return useContext(WordDataContext);
+}

package/dist/packages/core/src/context/WordDataProvider.d.ts

@@ -0,0 +1,5 @@
+import type { ReactNode } from 'react';
+import { type WordDataContextValue } from './WordDataContext';
+export declare function WordDataProvider({ words, loading, error, statusMessage, localVersion, remoteVersion, progress, clearAndRefetch, checkRemoteVersion, children, }: WordDataContextValue & {
+    children: ReactNode;
+}): import("react").JSX.Element;

package/dist/packages/core/src/context/WordDataProvider.js

@@ -0,0 +1,5 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { WordDataContext } from './WordDataContext';
+export function WordDataProvider({ words, loading, error, statusMessage, localVersion, remoteVersion, progress, clearAndRefetch, checkRemoteVersion, children, }) {
+    return (_jsx(WordDataContext.Provider, { value: { words, loading, error, statusMessage, localVersion, remoteVersion, progress, clearAndRefetch, checkRemoteVersion }, children: children }));
+}

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

@@ -0,0 +1,5 @@
+/** 스크롤 잠금 1회 획득(overflow만). 해제 함수를 반환한다(반드시 정확히 한 번 호출). */
+export declare function lockBodyScroll(): () => void;
+/** 스크롤 잠금 1회 획득 — scrollbar-gutter:stable 여백까지 함께 제거(paddingRight:0px).
+ * TrainingPagePopup처럼 스크롤바 폭 보정이 필요한 전체화면 오버레이용. */
+export declare function lockBodyScrollWithPadding(): () => void;

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

@@ -0,0 +1,62 @@
+'use client';
+// 공유 body 스크롤 잠금 참조 카운터 — 여러 팝업이 각자 독립적으로
+// document.body.style.overflow를 on/off하면, closeWithAnimation()의 지연 언마운트(260ms)
+// 도중 형제 팝업이 열리는 흔한 패턴에서 다음 버그가 난다:
+//   1) 먼저 열린 팝업이 늦게 언마운트되며 "자신이 열릴 때의 원래값"으로 overflow를
+//      되돌려버려, 방금 새로 연 팝업이 떠 있는데도 배경 스크롤이 풀림.
+//   2) 반대로 나중에 연 팝업이 먼저 닫히면 자신이 캡처한 'hidden'을 복원해, 모든
+//      팝업이 닫힌 뒤에도 스크롤이 영구히 잠긴 채로 남을 수 있음.
+// 참조 카운트가 0→1로 처음 올라갈 때만 잠그고, 1→0으로 마지막에 내려갈 때만 풀어
+// 이 순서 문제를 근본적으로 없앤다. Popup/TrainingPagePopup처럼 서로 중첩될 수 있는
+// 오버레이는 모두 이 카운터를 공유해야 한다(각자 독립 카운터를 쓰면 카운터끼리도
+// 서로를 모르는 채 위 문제가 그대로 재발한다).
+let lockCount = 0;
+let prevOverflow = '';
+let prevPaddingRight = '';
+// withPadding 잠금(전체화면 오버레이)만 세는 별도 카운터. overflow와 달리 paddingRight는
+// withPadding 잠금이 하나도 남지 않은 시점에 바로 되돌려야 한다 — 전체 lockCount가 0이 될
+// 때까지 미루면, 훈련 팝업(withPadding)이 닫히고 결과 팝업(withPadding 아님)만 남은 구간에서
+// paddingRight:0px가 그대로 남아 scrollbar-gutter 여백이 사라진 채 레이아웃이 밀린다.
+let paddingLockCount = 0;
+/** 스크롤 잠금 1회 획득(overflow만). 해제 함수를 반환한다(반드시 정확히 한 번 호출). */
+export function lockBodyScroll() {
+    return lockBodyScrollImpl(false);
+}
+/** 스크롤 잠금 1회 획득 — scrollbar-gutter:stable 여백까지 함께 제거(paddingRight:0px).
+ * TrainingPagePopup처럼 스크롤바 폭 보정이 필요한 전체화면 오버레이용. */
+export function lockBodyScrollWithPadding() {
+    return lockBodyScrollImpl(true);
+}
+function lockBodyScrollImpl(withPadding) {
+    const hasDoc = typeof document !== 'undefined';
+    if (lockCount === 0 && hasDoc) {
+        prevOverflow = document.body.style.overflow;
+        document.body.style.overflow = 'hidden';
+    }
+    if (withPadding && hasDoc) {
+        // 첫 withPadding 잠금만 원래 paddingRight를 캡처한다(중첩 시 '0px'를 원래값으로
+        // 오인해 저장하지 않도록).
+        if (paddingLockCount === 0)
+            prevPaddingRight = document.body.style.paddingRight;
+        paddingLockCount++;
+        document.body.style.paddingRight = '0px';
+    }
+    lockCount++;
+    let released = false;
+    return () => {
+        if (released)
+            return;
+        released = true;
+        lockCount = Math.max(0, lockCount - 1);
+        if (withPadding && hasDoc) {
+            paddingLockCount = Math.max(0, paddingLockCount - 1);
+            // withPadding 오버레이가 모두 닫히면 즉시 여백을 복원한다 — 남아 있는 일반 팝업은
+            // scrollbar-gutter 여백을 없앨 이유가 없다.
+            if (paddingLockCount === 0)
+                document.body.style.paddingRight = prevPaddingRight;
+        }
+        if (lockCount === 0 && hasDoc) {
+            document.body.style.overflow = prevOverflow;
+        }
+    };
+}

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

@@ -0,0 +1,2 @@
+/** ESC 닫기 핸들러를 스택에 등록. 해제 함수를 반환한다. */
+export declare function pushEsc(handler: () => void): () => void;

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

@@ -0,0 +1,38 @@
+'use client';
+/** @public */
+// 공유 ESC 스택 — 여러 오버레이가 쌓여도 ESC는 "최상단 하나"만 닫는다.
+// Popup, useEscToClose 등이 모두 이 스택에 등록되어 중복 닫힘을 막는다.
+//
+// 내부 컨트롤(Dropdown/TextField의 suggestions 콤보박스 등)이 ESC를 자체 처리할 때 e.preventDefault()를 호출하면
+// (네이티브 event.defaultPrevented가 true가 되어) 이 핸들러는 건너뛴다 — 즉, 열린 드롭다운에서
+// ESC를 누르면 드롭다운만 닫히고 팝업은 닫히지 않는다.
+const stack = [];
+let listening = false;
+function onKey(e) {
+    if (e.key !== 'Escape')
+        return;
+    if (e.defaultPrevented)
+        return; // 내부 컨트롤이 이미 소비함
+    const top = stack[stack.length - 1];
+    if (!top)
+        return;
+    e.stopPropagation();
+    top();
+}
+/** ESC 닫기 핸들러를 스택에 등록. 해제 함수를 반환한다. */
+export function pushEsc(handler) {
+    stack.push(handler);
+    if (!listening && typeof document !== 'undefined') {
+        document.addEventListener('keydown', onKey); // bubble 단계 — React onKeyDown 이후에 실행돼 preventDefault를 존중
+        listening = true;
+    }
+    return () => {
+        const i = stack.lastIndexOf(handler);
+        if (i >= 0)
+            stack.splice(i, 1);
+        if (stack.length === 0 && listening && typeof document !== 'undefined') {
+            document.removeEventListener('keydown', onKey);
+            listening = false;
+        }
+    };
+}

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

@@ -0,0 +1,2 @@
+/** @public */
+export default function useBackgroundUrl(p_code?: string, code?: string): string;

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

@@ -0,0 +1,13 @@
+'use client';
+import { useMemo } from "react";
+import { resolveAssetUrl } from '../utils';
+/** @public */
+export default function useBackgroundUrl(p_code, code) {
+    const backgroundUrl = useMemo(() => {
+        if (!p_code || !code) {
+            return resolveAssetUrl('images/backgrounds/default/default.jpg');
+        }
+        return resolveAssetUrl(`images/backgrounds/${p_code.toLowerCase()}/${code.toLowerCase()}.jpg`);
+    }, [p_code, code]);
+    return backgroundUrl;
+}

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

@@ -0,0 +1,34 @@
+/**
+ * @public
+ */
+export declare const CACHE_GROUPS: readonly [{
+    readonly id: "wordData";
+    readonly labelKey: "settings.cache.group.wordData.label";
+    readonly subKey: "settings.cache.group.wordData.sub";
+    readonly keys: readonly ["word_data_cache", "word_data_version"];
+}, {
+    readonly id: "pairIndex";
+    readonly labelKey: "settings.cache.group.pairIndex.label";
+    readonly subKey: "settings.cache.group.pairIndex.sub";
+    readonly keys: readonly ["word_pair_index_v2", "word_pair_index_sig_v2"];
+}, {
+    readonly id: "imageCache";
+    readonly labelKey: "settings.cache.group.imageCache.label";
+    readonly subKey: "settings.cache.group.imageCache.sub";
+    readonly keys: readonly ["word_image_existence_map_v1"];
+}];
+export type CacheGroupId = typeof CACHE_GROUPS[number]['id'];
+export declare function lsBytes(keys: string[]): number;
+export declare function fmtBytes(n: number): string;
+export declare function useCacheManagement(onToast?: (msg: string) => void): {
+    cacheSizes: Record<string, number>;
+    clearingId: "wordData" | "pairIndex" | "imageCache" | null;
+    confirmCacheId: "wordData" | "pairIndex" | "imageCache" | null;
+    setConfirmCacheId: import("react").Dispatch<import("react").SetStateAction<"wordData" | "pairIndex" | "imageCache" | null>>;
+    storageEstimate: {
+        usage: number;
+        quota: number;
+    } | null;
+    refreshCacheSizes: () => void;
+    handleClearCache: (id: CacheGroupId) => Promise<void>;
+};

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

@@ -0,0 +1,107 @@
+'use client';
+import { useState, useCallback, useEffect } from 'react';
+import { useTranslation } from 'react-i18next';
+import { clearPairIndexCache } from '../utils/wordPairIndex';
+import { clearImageExistenceCache } from '../utils/imageConfig';
+// ─── 캐시 그룹 정의 ────────────────────────────────────────────────────────────
+/**
+ * @public
+ */
+export const CACHE_GROUPS = [
+    {
+        id: 'wordData',
+        labelKey: 'settings.cache.group.wordData.label',
+        subKey: 'settings.cache.group.wordData.sub',
+        keys: ['word_data_cache', 'word_data_version'],
+    },
+    {
+        id: 'pairIndex',
+        labelKey: 'settings.cache.group.pairIndex.label',
+        subKey: 'settings.cache.group.pairIndex.sub',
+        // wordPairIndex.ts가 v2로 캐시 키를 리네임(대립 비교 기준을 철자→표준발음으로 변경)했는데
+        // 여기는 구버전(v1) 키를 계속 참조하고 있어, 실제로는 수 MB에 달할 수 있는 대립쌍 인덱스가
+        // 항상 0바이트로 계산돼 "전체 캐시 용량" 표시가 과소 표시되던 문제 — v2로 갱신
+        keys: ['word_pair_index_v2', 'word_pair_index_sig_v2'],
+    },
+    {
+        id: 'imageCache',
+        labelKey: 'settings.cache.group.imageCache.label',
+        subKey: 'settings.cache.group.imageCache.sub',
+        keys: ['word_image_existence_map_v1'],
+    },
+    // (trainingRecord 캐시 그룹 제거됨 — 오늘의 듣기 선택/완료/일수는 모두 서버 정본으로 전환,
+    //  결정적 시드 + training_completion 사용. localStorage 저장 없음.)
+];
+// ─── 헬퍼 ──────────────────────────────────────────────────────────────────────
+export function lsBytes(keys) {
+    return keys.reduce((sum, k) => {
+        try {
+            const v = localStorage.getItem(k);
+            return sum + (v ? new Blob([v]).size : 0);
+        }
+        catch {
+            return sum;
+        }
+    }, 0);
+}
+export function fmtBytes(n) {
+    if (n === 0)
+        return '0 B';
+    if (n < 1024)
+        return `${n} B`;
+    if (n < 1024 * 1024)
+        return `${(n / 1024).toFixed(1)} KB`;
+    if (n < 1024 * 1024 * 1024)
+        return `${(n / (1024 * 1024)).toFixed(2)} MB`;
+    return `${(n / (1024 * 1024 * 1024)).toFixed(2)} GB`;
+}
+// ─── 훅 ────────────────────────────────────────────────────────────────────────
+export function useCacheManagement(onToast) {
+    const { t } = useTranslation();
+    const [cacheSizes, setCacheSizes] = useState({});
+    const [clearingId, setClearingId] = useState(null);
+    const [confirmCacheId, setConfirmCacheId] = useState(null);
+    const [storageEstimate, setStorageEstimate] = useState(null);
+    const refreshCacheSizes = useCallback(() => {
+        const sizes = {};
+        CACHE_GROUPS.forEach(g => { sizes[g.id] = lsBytes([...g.keys]); });
+        setCacheSizes(sizes);
+        if (typeof navigator !== 'undefined' && navigator.storage?.estimate) {
+            navigator.storage.estimate().then(e => {
+                setStorageEstimate({ usage: e.usage ?? 0, quota: e.quota ?? 0 });
+            }).catch(() => { });
+        }
+    }, []);
+    // refreshCacheSizes는 setSizes 등을 동기 호출하지만, 마운트 시 캐시 용량을 반영하는 의도된 fetch-kickoff이다
+    // eslint-disable-next-line react-hooks/set-state-in-effect
+    useEffect(() => { refreshCacheSizes(); }, [refreshCacheSizes]);
+    const handleClearCache = useCallback(async (id) => {
+        setClearingId(id);
+        try {
+            if (id === 'wordData') {
+                localStorage.removeItem('word_data_cache');
+                localStorage.removeItem('word_data_version');
+            }
+            else if (id === 'pairIndex') {
+                clearPairIndexCache();
+            }
+            else if (id === 'imageCache') {
+                clearImageExistenceCache();
+            }
+            refreshCacheSizes();
+            onToast?.(t('settings.cache.cleared', '캐시가 삭제되었습니다.'));
+        }
+        finally {
+            setClearingId(null);
+        }
+    }, [refreshCacheSizes, onToast, t]);
+    return {
+        cacheSizes,
+        clearingId,
+        confirmCacheId,
+        setConfirmCacheId,
+        storageEstimate,
+        refreshCacheSizes,
+        handleClearCache,
+    };
+}

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

@@ -0,0 +1,17 @@
+import type { TrainingItem } from '../types/training';
+/**
+ * 오늘/어제 훈련 선택을 (user, 날짜) 결정적 시드로 계산하는 훅(영속 저장 없음).
+ *
+ * - resolveSelection은 시드 기반이라 기기/세션 무관 동일 결과
+ * - 데이터 미로딩 시 ensureTrainingDataLoaded() 대기 후 재계산
+ * - 폴링(250ms): 훈련 데이터가 비동기로 채워질 때까지 재시도
+ */
+/**
+ * @public
+ */
+export declare function useDailyTrainingSelection(userId?: string): {
+    loaded: boolean;
+    showYesterday: boolean;
+    setShowYesterday: import("react").Dispatch<import("react").SetStateAction<boolean>>;
+    getTrainingPerType: (typeKey: string) => TrainingItem[] | undefined;
+};

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

@@ -0,0 +1,87 @@
+'use client';
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { ensureTrainingDataLoaded } from '../utils/getTrainingData';
+import { hasItems, resolveSelection, } from '../utils/dailySelectionUtils';
+// ─── 훅 ──────────────────────────────────────────────────────────────────────
+/**
+ * 오늘/어제 훈련 선택을 (user, 날짜) 결정적 시드로 계산하는 훅(영속 저장 없음).
+ *
+ * - resolveSelection은 시드 기반이라 기기/세션 무관 동일 결과
+ * - 데이터 미로딩 시 ensureTrainingDataLoaded() 대기 후 재계산
+ * - 폴링(250ms): 훈련 데이터가 비동기로 채워질 때까지 재시도
+ */
+/**
+ * @public
+ */
+export function useDailyTrainingSelection(userId) {
+    const todayRef = useRef({ LISTEN_IN_NOISE: [], SHORT_STORY: [], LONG_STORY: [], ORDERING_SENTENCE: [] });
+    const yesterdayRef = useRef(null);
+    const [loaded, setLoaded] = useState(false);
+    const [showYesterday, setShowYesterday] = useState(false);
+    useEffect(() => {
+        let cancelled = false;
+        let timer;
+        let attempts = 0;
+        const MAX_ATTEMPTS = 40; // 250ms * 40 = 10초 후 폴링 중단(풀이 영영 비는 경우 무한루프 방지)
+        const stop = () => { if (timer !== undefined) {
+            clearInterval(timer);
+            timer = undefined;
+        } };
+        let forceRefresh = false;
+        try {
+            const p = new URLSearchParams(window.location.search);
+            const v = p.get('forceRefresh') || p.get('force');
+            forceRefresh = v === '1' || v === 'true';
+        }
+        catch { }
+        const apply = (sel) => {
+            todayRef.current = sel.today;
+            yesterdayRef.current = sel.yesterday;
+            setLoaded(true);
+            cancelled = true;
+            stop();
+        };
+        const tryFill = async () => {
+            if (cancelled)
+                return;
+            // 캐시 hit → 즉시 적용
+            if (!forceRefresh) {
+                const hit = resolveSelection(false, undefined, userId);
+                if (hasItems(hit.today)) {
+                    apply(hit);
+                    return;
+                }
+            }
+            // 캐시 miss → 데이터 로드 후 새 선택
+            try {
+                await ensureTrainingDataLoaded(3000);
+            }
+            catch { }
+            if (cancelled)
+                return;
+            const sel = resolveSelection(forceRefresh, undefined, userId);
+            if (hasItems(sel.today)) {
+                apply(sel);
+                return;
+            }
+            // 데이터가 끝내 차지 않으면 일정 시도 후 중단(빈 선택이라도 로딩 종료)
+            if (++attempts >= MAX_ATTEMPTS) {
+                setLoaded(true);
+                cancelled = true;
+                stop();
+            }
+        };
+        tryFill();
+        timer = setInterval(tryFill, 250);
+        return () => { cancelled = true; stop(); };
+    }, [userId]);
+    const getTrainingPerType = useCallback((typeKey) => {
+        const src = showYesterday ? yesterdayRef.current : todayRef.current;
+        const fallback = showYesterday ? todayRef.current : yesterdayRef.current;
+        const pick = src?.[typeKey]?.length
+            ? src[typeKey]
+            : (fallback?.[typeKey]?.length ? fallback[typeKey] : undefined);
+        return pick;
+    }, [showYesterday]);
+    return { loaded, showYesterday, setShowYesterday, getTrainingPerType };
+}

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

@@ -0,0 +1,37 @@
+import type { DeviceForm } from '../types/device';
+type Side = '좌' | '우';
+/**
+ * 보청기 기기 등록 / 이력 관리 상태를 캡슐화한 훅.
+ */
+/**
+ * @public
+ */
+export declare function useDeviceManagement(): {
+    showDevice: boolean;
+    setShowDevice: import("react").Dispatch<import("react").SetStateAction<boolean>>;
+    deviceDirection: Side;
+    setDeviceDirection: import("react").Dispatch<import("react").SetStateAction<Side>>;
+    devices: {
+        좌: DeviceForm | null;
+        우: DeviceForm | null;
+    };
+    setDevices: import("react").Dispatch<import("react").SetStateAction<{
+        좌: DeviceForm | null;
+        우: DeviceForm | null;
+    }>>;
+    deviceHistory: {
+        좌: DeviceForm[];
+        우: DeviceForm[];
+    };
+    setDeviceHistory: import("react").Dispatch<import("react").SetStateAction<{
+        좌: DeviceForm[];
+        우: DeviceForm[];
+    }>>;
+    showDeviceList: boolean;
+    setShowDeviceList: import("react").Dispatch<import("react").SetStateAction<boolean>>;
+    listForSide: Side;
+    setListForSide: import("react").Dispatch<import("react").SetStateAction<Side>>;
+    handleDeviceSubmit: (form: DeviceForm) => void;
+    handleSelectFromList: (form: DeviceForm) => void;
+};
+export {};

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

@@ -0,0 +1,40 @@
+'use client';
+import { useCallback, useState } from 'react';
+/**
+ * 보청기 기기 등록 / 이력 관리 상태를 캡슐화한 훅.
+ */
+/**
+ * @public
+ */
+export function useDeviceManagement() {
+    const [showDevice, setShowDevice] = useState(false);
+    const [deviceDirection, setDeviceDirection] = useState('좌');
+    const [devices, setDevices] = useState({ 좌: null, 우: null });
+    const [deviceHistory, setDeviceHistory] = useState({ 좌: [], 우: [] });
+    const [showDeviceList, setShowDeviceList] = useState(false);
+    const [listForSide, setListForSide] = useState('좌');
+    // form.direction은 각 팝업(DeviceRegistrationPopup의 방향 드롭다운, DeviceListPopup의
+    // 좌/우 탭)에서 사용자가 실제로 고른 값이다 — deviceDirection/listForSide는 팝업을 열 때의
+    // 초기값일 뿐이라 팝업 내부에서 방향을 바꾸면 더 이상 실제 선택과 일치하지 않는다.
+    const handleDeviceSubmit = useCallback((form) => {
+        const side = form.direction;
+        setDevices(prev => ({ ...prev, [side]: form }));
+        setDeviceHistory(prev => ({ ...prev, [side]: [form, ...prev[side]] }));
+        setShowDevice(false);
+    }, []);
+    const handleSelectFromList = useCallback((form) => {
+        const side = form.direction;
+        setDevices(prev => ({ ...prev, [side]: form }));
+        setShowDeviceList(false);
+    }, []);
+    return {
+        showDevice, setShowDevice,
+        deviceDirection, setDeviceDirection,
+        devices, setDevices,
+        deviceHistory, setDeviceHistory,
+        showDeviceList, setShowDeviceList,
+        listForSide, setListForSide,
+        handleDeviceSubmit,
+        handleSelectFromList,
+    };
+}

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

@@ -0,0 +1,22 @@
+/**
+ * 문서 제목 설정을 억제하는 컨텍스트.
+ *
+ * 랜딩의 폰 목업처럼 **페이지 컴포넌트를 화면 일부로 끼워 넣는 곳**은 이 Provider로 감싼다.
+ * 그러지 않으면 목업 안의 페이지가 실제 탭 제목을 덮어쓴다(실제로 겪은 회귀).
+ *
+ * @public
+ */
+export declare const DocumentTitleSuppressContext: import("react").Context<boolean>;
+/**
+ * 현재 화면의 제목을 `document.title`에 반영한다 — `'<제목> · <앱 이름>'`.
+ *
+ * SPA는 라우트를 옮겨도 문서 제목이 그대로라, 브라우저 탭·히스토리·북마크로 위치를
+ * 구분할 수 없고 화면낭독기도 이동을 인지하지 못한다(WCAG 2.4.2).
+ * 언마운트하면 이전 제목으로 되돌린다.
+ *
+ * @param title 페이지 제목. 비어 있거나 문자열이 아니면 아무것도 하지 않는다.
+ *
+ * @public
+ */
+export declare function useDocumentTitle(title?: string | null): void;
+export default useDocumentTitle;

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

@@ -0,0 +1,49 @@
+'use client';
+import { useEffect, useContext, createContext } from 'react';
+const SEP = ' \u00b7 ';
+/**
+ * 앱 이름 — 페이지 제목의 접미사. 모듈 로드 시 한 번만 캡처한다.
+ *
+ * 이 모듈이 lazy 청크로 늦게 로드되거나 개발 중 HMR로 다시 평가되면, 캡처 시점의
+ * `document.title`이 이미 `'설정 · 아이해브 말귀'`처럼 가공된 값일 수 있다. 그대로 쓰면
+ * `'고객관리 · 설정 · 아이해브 말귀'`로 계속 늘어난다(실제로 관측됨) — 마지막 조각만 취한다.
+ */
+const BASE_TITLE = (() => {
+    if (typeof document === 'undefined')
+        return '';
+    const raw = document.title;
+    return raw.includes(SEP) ? raw.split(SEP).pop() ?? raw : raw;
+})();
+/**
+ * 문서 제목 설정을 억제하는 컨텍스트.
+ *
+ * 랜딩의 폰 목업처럼 **페이지 컴포넌트를 화면 일부로 끼워 넣는 곳**은 이 Provider로 감싼다.
+ * 그러지 않으면 목업 안의 페이지가 실제 탭 제목을 덮어쓴다(실제로 겪은 회귀).
+ *
+ * @public
+ */
+export const DocumentTitleSuppressContext = createContext(false);
+/**
+ * 현재 화면의 제목을 `document.title`에 반영한다 — `'<제목> · <앱 이름>'`.
+ *
+ * SPA는 라우트를 옮겨도 문서 제목이 그대로라, 브라우저 탭·히스토리·북마크로 위치를
+ * 구분할 수 없고 화면낭독기도 이동을 인지하지 못한다(WCAG 2.4.2).
+ * 언마운트하면 이전 제목으로 되돌린다.
+ *
+ * @param title 페이지 제목. 비어 있거나 문자열이 아니면 아무것도 하지 않는다.
+ *
+ * @public
+ */
+export function useDocumentTitle(title) {
+    const suppressed = useContext(DocumentTitleSuppressContext);
+    useEffect(() => {
+        if (suppressed)
+            return;
+        if (typeof title !== 'string' || !title)
+            return;
+        const prev = document.title;
+        document.title = BASE_TITLE ? `${title}${SEP}${BASE_TITLE}` : title;
+        return () => { document.title = prev; };
+    }, [title, suppressed]);
+}
+export default useDocumentTitle;

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

@@ -0,0 +1,20 @@
+/**
+ * 목록 + 선택 항목 + 편집 폼 상태를 통합하는 제네릭 훅.
+ *
+ * @public
+ */
+export declare function useEditableList<T>(emptyItem: T, initialList?: T[]): {
+    list: T[];
+    setList: import("react").Dispatch<import("react").SetStateAction<T[]>>;
+    selected: T | null;
+    setSelected: import("react").Dispatch<import("react").SetStateAction<T | null>>;
+    isEditing: boolean;
+    setIsEditing: import("react").Dispatch<import("react").SetStateAction<boolean>>;
+    editForm: T;
+    setEditForm: import("react").Dispatch<import("react").SetStateAction<T>>;
+    openDetail: (item: T) => void;
+    startEditing: () => void;
+    cancelEditing: () => void;
+    commitEdit: (updater: (prev: T[]) => T[], updated: T) => void;
+    remove: (item: T) => void;
+};