@readerseye2/cr_type 1.0.115 → 1.0.117

package/dist/book/child-reading-progress.type.d.ts

@@ -0,0 +1,154 @@
+/** 읽은 구간 (globalIndex 범위, inclusive) */
+export interface ReadRange {
+    from: number;
+    to: number;
+}
+/** 캘리브레이션 종류 */
+export type CalibrationType = 'quick' | 'full';
+/** 섹션 읽기 중 발생한 캘리브레이션 기간 */
+export interface CalibrationPeriod {
+    type: CalibrationType;
+    /** 사용한 포인트 수 (quick: 1~2, full: 5) */
+    points: number;
+    startedAt: string;
+    endedAt: string;
+    durationMs: number;
+    /** 캘리브레이션 결과 품질 (0~1, 기기 제공) */
+    quality?: number;
+}
+export interface ReadingProgressReport {
+    bookIdx: number;
+    sectionId: string;
+    /** 섹션 전체 GI 수 (ViewerSnapshot.totalItems) */
+    sectionGIMax: number;
+    /** 이 구간에서 뷰포트에 표시된 GI 범위의 최소값 */
+    scrolledFrom: number;
+    /** 이 구간에서 뷰포트에 표시된 GI 범위의 최대값 */
+    scrolledTo: number;
+    /**
+     * GI별 시선 dwell time (ms)
+     * - 키: globalIndex (string), 값: 해당 5초 윈도우 내 누적 dwell ms
+     * - 임계값 필터링 없이 전체 포함 (서버에서 threshold 적용)
+     * - 시선 추적 기기 없으면 빈 객체 {}
+     *
+     * 예: { "101": 300, "102": 450, "103": 67 }
+     */
+    gazeDwellMap: Record<string, number>;
+    /** 이 구간 내 눈 깜빡임 횟수 (Tobii valid 전환 감지) */
+    blinkCount: number;
+    /** 소요 시간 ms */
+    durationMs: number;
+}
+export interface ChildSectionProgress {
+    childIdx: number;
+    bookIdx: number;
+    sectionId: string;
+    sectionGIMax: number;
+    scrolledRanges: ReadRange[];
+    scrolledCount: number;
+    scrolledCoverage: number;
+    gazeReadRanges: ReadRange[];
+    gazeReadCount: number;
+    gazeReadCoverage: number;
+    totalReadMs: number;
+    lastGlobalIndex: number;
+    lastReadAt: string;
+    totalBlinks: number;
+    calibrations: CalibrationPeriod[];
+    createdAt: string;
+    updatedAt: string;
+}
+export interface ChildBookBookmark {
+    childIdx: number;
+    bookIdx: number;
+    lastReadSectionId: string;
+    lastGlobalIndex: number;
+    totalGIMax: number;
+    totalScrolledCount: number;
+    totalScrolledCoverage: number;
+    totalGazeReadCount: number;
+    totalGazeReadCoverage: number;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface ChildReadingLog {
+    childIdx: number;
+    bookIdx: number;
+    sectionId: string;
+    scrolledFrom: number;
+    scrolledTo: number;
+    /** 전체 dwell map 그대로 보존 */
+    gazeDwellMap: Record<string, number>;
+    blinkCount: number;
+    durationMs: number;
+    createdAt: string;
+}
+export interface ChildCalibrationLog {
+    childIdx: number;
+    /** 읽기 세션 중 발생 시 세션 ID */
+    sessionId?: string;
+    /** 읽기 중이었던 섹션 */
+    sectionId?: string;
+    type: CalibrationType;
+    /** 사용한 포인트 수 */
+    points: number;
+    startedAt: string;
+    endedAt: string;
+    durationMs: number;
+    quality?: number;
+    createdAt: string;
+}
+export interface SegmentReadingSummary {
+    sectionId: string;
+    bookIdx: number;
+    sectionGIMax: number;
+    startedAt: string;
+    endedAt: string;
+    durationMs: number;
+    scrolledFrom: number;
+    scrolledTo: number;
+    scrolledGICount: number;
+    gazeReadGICount: number;
+    /** gazeReadGICount / scrolledGICount (시선 없으면 null) */
+    focusRatio: number | null;
+    /** 평균 읽기 속도 (GI per minute) */
+    readingSpeedGPM: number;
+    /** 평균 dwell time (ms per GI) */
+    avgDwellMs: number | null;
+    totalBlinks: number;
+    /** 분당 깜빡임 횟수 */
+    blinksPerMinute: number;
+    calibrations: CalibrationPeriod[];
+}
+export interface ChildReadingSessionSummary {
+    childIdx: number;
+    sessionId: string;
+    startedAt: string;
+    endedAt: string;
+    totalDurationMs: number;
+    segments: SegmentReadingSummary[];
+    totalScrolledGICount: number;
+    totalGazeReadGICount: number;
+    overallFocusRatio: number | null;
+    avgReadingSpeedGPM: number;
+    totalBlinks: number;
+    avgBlinksPerMinute: number;
+}
+/** GET /api/reading-progress/:bookIdx */
+export interface ChildBookProgressResponse {
+    bookmark: ChildBookBookmark | null;
+    sections: ChildSectionProgress[];
+}
+/** 일별 읽기 통계 (aggregation 결과) */
+export interface DailyReadingStat {
+    date: string;
+    totalMs: number;
+    books: number[];
+}
+/** GET /api/reading-progress/daily-stats */
+export interface DailyReadingStatsResponse {
+    childIdx: number;
+    from: string;
+    to: string;
+    stats: DailyReadingStat[];
+}

package/dist/book/child-reading-progress.type.js

@@ -0,0 +1,4 @@
+"use strict";
+// src/book/child-reading-progress.type.ts
+// 자녀 읽기 진행 데이터 — MongoDB 5컬렉션 + WS/REST 타입
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/book/index.d.ts

@@ -2,3 +2,5 @@ export * from './book.type';
 export * from './book-sections.type';
 export * from './book-status-request.type';
 export * from './tag.type';
+export * from './child-reading-progress.type';
+export * from './read-range.util';

package/dist/book/index.js

@@ -18,3 +18,5 @@ __exportStar(require("./book.type"), exports);
 __exportStar(require("./book-sections.type"), exports);
 __exportStar(require("./book-status-request.type"), exports);
 __exportStar(require("./tag.type"), exports);
+__exportStar(require("./child-reading-progress.type"), exports);
+__exportStar(require("./read-range.util"), exports);

package/dist/book/read-range.util.d.ts

@@ -0,0 +1,11 @@
+import type { ReadRange } from './child-reading-progress.type';
+/** 정렬된 ranges 배열에 newRange를 머지 (겹침/인접 합산) */
+export declare function mergeReadRange(ranges: ReadRange[], newRange: ReadRange): ReadRange[];
+/** 여러 newRanges를 기존 ranges에 순차 머지 */
+export declare function mergeReadRanges(existing: ReadRange[], newRanges: ReadRange[]): ReadRange[];
+/** ranges 내 고유 GI 총 개수 (각 구간 길이 합) */
+export declare function sumReadRanges(ranges: ReadRange[]): number;
+/** 개별 GI 배열 → 정렬된 ReadRange[] 변환 */
+export declare function gisToRanges(gis: number[]): ReadRange[];
+/** gazeDwellMap에서 threshold 이상인 GI만 추출하여 ReadRange[] 변환 */
+export declare function filterDwellToRanges(gazeDwellMap: Record<string, number>, thresholdMs: number): ReadRange[];

package/dist/book/read-range.util.js

@@ -0,0 +1,79 @@
+"use strict";
+// src/book/read-range.util.ts
+// ReadRange 유틸리티 함수 (서버/클라이언트 공용)
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mergeReadRange = mergeReadRange;
+exports.mergeReadRanges = mergeReadRanges;
+exports.sumReadRanges = sumReadRanges;
+exports.gisToRanges = gisToRanges;
+exports.filterDwellToRanges = filterDwellToRanges;
+/** 정렬된 ranges 배열에 newRange를 머지 (겹침/인접 합산) */
+function mergeReadRange(ranges, newRange) {
+    if (ranges.length === 0)
+        return [newRange];
+    const result = [];
+    let merged = { ...newRange };
+    let inserted = false;
+    for (const r of ranges) {
+        if (inserted) {
+            result.push(r);
+            continue;
+        }
+        if (r.to + 1 < merged.from) {
+            result.push(r);
+        }
+        else if (r.from > merged.to + 1) {
+            result.push(merged);
+            result.push(r);
+            inserted = true;
+        }
+        else {
+            merged = { from: Math.min(merged.from, r.from), to: Math.max(merged.to, r.to) };
+        }
+    }
+    if (!inserted)
+        result.push(merged);
+    return result;
+}
+/** 여러 newRanges를 기존 ranges에 순차 머지 */
+function mergeReadRanges(existing, newRanges) {
+    let result = existing;
+    for (const nr of newRanges)
+        result = mergeReadRange(result, nr);
+    return result;
+}
+/** ranges 내 고유 GI 총 개수 (각 구간 길이 합) */
+function sumReadRanges(ranges) {
+    let sum = 0;
+    for (const r of ranges)
+        sum += r.to - r.from + 1;
+    return sum;
+}
+/** 개별 GI 배열 → 정렬된 ReadRange[] 변환 */
+function gisToRanges(gis) {
+    if (gis.length === 0)
+        return [];
+    const sorted = [...new Set(gis)].sort((a, b) => a - b);
+    const ranges = [];
+    let from = sorted[0], to = sorted[0];
+    for (let i = 1; i < sorted.length; i++) {
+        if (sorted[i] === to + 1)
+            to = sorted[i];
+        else {
+            ranges.push({ from, to });
+            from = sorted[i];
+            to = sorted[i];
+        }
+    }
+    ranges.push({ from, to });
+    return ranges;
+}
+/** gazeDwellMap에서 threshold 이상인 GI만 추출하여 ReadRange[] 변환 */
+function filterDwellToRanges(gazeDwellMap, thresholdMs) {
+    const passedGIs = [];
+    for (const [gi, ms] of Object.entries(gazeDwellMap)) {
+        if (ms >= thresholdMs)
+            passedGIs.push(Number(gi));
+    }
+    return gisToRanges(passedGIs);
+}

package/dist/gaze/eye-tracker.types.d.ts

@@ -0,0 +1,11 @@
+/** 지원하는 시선추적 프로바이더 타입 */
+export type EyeTrackerType = 'eyedid' | 'seeso' | 'custom' | 'fake';
+/** 단일 시선 샘플 (0~1 정규화 좌표) */
+export interface GazeData {
+    /** 정규화된 X 좌표 (0~1, 좌→우) */
+    x: number;
+    /** 정규화된 Y 좌표 (0~1, 상→하) */
+    y: number;
+    /** 타임스탬프 (ms, Date.now()) */
+    timestamp: number;
+}

package/dist/gaze/eye-tracker.types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/gaze/index.d.ts

@@ -0,0 +1 @@
+export * from './eye-tracker.types';

package/dist/gaze/index.js

@@ -0,0 +1,17 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./eye-tracker.types"), exports);

package/dist/index.d.ts

@@ -2,3 +2,4 @@ export * from './session/session.type';
 export * from './socket';
 export * from './book';
 export * from './ast';
+export * from './gaze';

package/dist/index.js

@@ -19,3 +19,4 @@ __exportStar(require("./session/session.type"), exports);
 __exportStar(require("./socket"), exports);
 __exportStar(require("./book"), exports);
 __exportStar(require("./ast"), exports);
+__exportStar(require("./gaze"), exports);

package/dist/socket/socket-clientToServerEvents.type.d.ts

@@ -1,6 +1,7 @@
 import { ChatMessageReadRequest, ChatMessageRefreshRequest, MessageRequest } from "./socket-message.types";
 import { SessionProgressPayload, SessionEventPayload, SessionSubscribePayload } from "./reading-section.types";
 import { ViewerOpenPayload, ViewerClosePayload, GazeDataPayload, SessionHistoryListPayload, SessionHistoryGetPayload, SessionHistoryDeletePayload, UnifiedChunksGetPayload, UnifiedSegmentGetPayload } from "./unified-session.types";
+import { ReadingProgressReport } from "../book/child-reading-progress.type";
 export interface ClientToServerEvents {
     'chat-message:send': (msg: MessageRequest) => void;
     'chat-message:refresh': (msg: ChatMessageRefreshRequest) => void;
@@ -19,6 +20,8 @@ export interface ClientToServerEvents {
     'session:subscribe': (payload: SessionSubscribePayload) => void;
     /** 세션 구독 해제 */
     'session:unsubscribe': (payload: SessionSubscribePayload) => void;
+    /** 읽기 진행 보고 (5초 주기 자동저장) */
+    'progress:reading-save': (payload: ReadingProgressReport) => void;
 }
 export interface NoticeToServerEvents {
     'notice-message:send': (msg: MessageRequest) => void;

package/dist/socket/viewer-events.types.d.ts

@@ -29,7 +29,7 @@ export type CRViewerState = {
     viewportHeight: number;
 };
 /** 뷰어 이벤트 타입 */
-export type ViewerEventType = 'global_index_change' | 'scroll' | 'page_change' | 'section_change' | 'mode_change' | 'settings_change' | 'render_start' | 'loading_start' | 'loading_end' | 'viewport_resize' | 'audio_control' | 'range_select' | 'range_change' | 'range_clear' | 'translate_request' | 'translate_loading_start' | 'translate_loading_end' | 'translate_modal_close';
+export type ViewerEventType = 'global_index_change' | 'scroll' | 'page_change' | 'section_change' | 'mode_change' | 'settings_change' | 'render_start' | 'loading_start' | 'loading_end' | 'viewport_resize' | 'audio_control' | 'range_select' | 'range_change' | 'range_clear' | 'translate_request' | 'translate_loading_start' | 'translate_loading_end' | 'translate_modal_close' | 'calibration_start' | 'calibration_end' | 'show_gaze_change' | 'ask_calibration' | 'calibration_progress';
 /** 오디오 상태 스냅샷 */
 export type AudioSnapshot = {
     status: 'idle' | 'loading' | 'playing' | 'paused' | 'ended' | 'error';
@@ -124,8 +124,28 @@ export type TranslateLoadingEndEvent = ViewerEventBase<'translate_loading_end',
     translatedText: string;
 }>;
 export type TranslateModalCloseEvent = ViewerEventBase<'translate_modal_close', Record<string, never>>;
+export type CalibrationStartEvent = ViewerEventBase<'calibration_start', {
+    type: 'quick' | 'full';
+    points: number;
+}>;
+export type CalibrationEndEvent = ViewerEventBase<'calibration_end', {
+    type: 'quick' | 'full';
+    points: number;
+    durationMs: number;
+    quality?: number;
+}>;
+export type ShowGazeChangeEvent = ViewerEventBase<'show_gaze_change', {
+    showGaze: boolean;
+}>;
+export type AskCalibrationEvent = ViewerEventBase<'ask_calibration', {
+    requestedAt: number;
+}>;
+export type CalibrationProgressEvent = ViewerEventBase<'calibration_progress', {
+    current: number;
+    total: number;
+}>;
 /** 모든 뷰어 이벤트 타입 (Union) */
-export type ViewerEvent = GlobalIndexChangeEvent | ScrollEvent | PageChangeEvent | SectionChangeEvent | ModeChangeEvent | SettingsChangeEvent | RenderStartEvent | LoadingStartEvent | LoadingEndEvent | ViewportResizeEvent | AudioControlEvent | RangeSelectEvent | RangeChangeEvent | RangeClearEvent | TranslateRequestEvent | TranslateLoadingStartEvent | TranslateLoadingEndEvent | TranslateModalCloseEvent;
+export type ViewerEvent = GlobalIndexChangeEvent | ScrollEvent | PageChangeEvent | SectionChangeEvent | ModeChangeEvent | SettingsChangeEvent | RenderStartEvent | LoadingStartEvent | LoadingEndEvent | ViewportResizeEvent | AudioControlEvent | RangeSelectEvent | RangeChangeEvent | RangeClearEvent | TranslateRequestEvent | TranslateLoadingStartEvent | TranslateLoadingEndEvent | TranslateModalCloseEvent | CalibrationStartEvent | CalibrationEndEvent | ShowGazeChangeEvent | AskCalibrationEvent | CalibrationProgressEvent;
 export type ViewerEventCallback = (event: ViewerEvent) => void;
 /** 저장용 이벤트 (any type) */
 export type StoredEvent = StoredViewerEvent<ViewerEventType, unknown>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@readerseye2/cr_type",
-  "version": "1.0.115",
+  "version": "1.0.117",
   "description": "CheckReading shared TypeScript types",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",