cotutor 0.1.0 → 0.3.0

package/dist/ui/kid/reel.d.ts

@@ -0,0 +1,419 @@
+import type { RunEvent } from '../../schema/index.ts';
+import type { CardStates } from '../../schema/index.ts';
+import type { ConversationMessage } from '../../schema/conversation.ts';
+/** 嘴念一句的时段;audio = 那次通话的声音(相对 conversations/<老师>/),seek = 这句在里面从哪开始(毫秒) */
+export interface ReelSay {
+    job: string;
+    line: number;
+    from: number;
+    to: number;
+    audio: string;
+    seek?: number;
+}
+/** 按住说话收尾时孩子看到的:sent 发出去了 · unclear「没听清,再按住说一次」· cancel 上滑取消 */
+export type ReelHoldResult = 'sent' | 'unclear' | 'cancel';
+/**
+ * 实录(第二期):孩子端记下的一条,落 <日期>.<job>.play.jsonl。at 是服务端的墙钟(路由按发来时两边的钟差校过)。
+ * stage = 弹窗开 / 关;
+ * visible = 页面切到后台 / 回来;card = 卡的一次存(服务端在 putCardState 里记,孩子端不发)。
+ * 改版(孩子看到什么记什么):view = 孩子屏幕的 CSS 尺寸、键盘高、页面版本;
+ * hold = 按住说话的一步(down 按下 / audio 话筒开了 / slide 上滑取消 on 或滑回来 / up 松手,cancel = 不是孩子松的手、是系统抢走了触摸(pointercancel,iPadOS 底部手势),照旧当松手 / end 收尾,r 见 ReelHoldResult,lv = 按下起每 100 毫秒一位的音量 0–9);
+ * type = 打字(focus 点进输入框 / v 值变了 / send 发了 / blur 收起);ps = 发照片屏(open / tool:crop 裁剪 · pen 圈画 · rot 转 / send / cancel);
+ * scroll = 孩子自己翻到哪(锚在卡上:那张卡的上沿离板书上沿 dy 像素)
+ */
+export type PlayRecord = {
+    at: number;
+} & ({
+    k: 'stage';
+    job: string;
+    card: number;
+    open: boolean;
+} | {
+    k: 'visible';
+    on: boolean;
+} | {
+    k: 'card';
+    job: string;
+    card: number;
+    state: unknown;
+} | {
+    k: 'view';
+    w: number;
+    h: number;
+    kb: number;
+    v: string;
+} | {
+    k: 'hold';
+    e: 'down' | 'audio' | 'slide' | 'up' | 'end';
+    on?: boolean;
+    r?: ReelHoldResult;
+    lv?: string;
+    cancel?: true;
+} | {
+    k: 'type';
+    e: 'focus' | 'v' | 'send' | 'blur';
+    v?: string;
+} | {
+    k: 'ps';
+    e: 'open' | 'tool' | 'send' | 'cancel';
+    tool?: string;
+} | {
+    k: 'scroll';
+    job: string;
+    card: number;
+    dy: number;
+});
+/** 一条实录的形状对不对(服务端收、读 play.jsonl 时用;坏的丢掉) */
+export declare function playRecordOk(x: unknown): x is PlayRecord;
+/** 弹窗开着的一段(实录) */
+export interface ReelStage {
+    job: string;
+    card: number;
+    from: number;
+    to: number;
+}
+/**
+ * 一段不是讲稿的声音(都在实时那次通话的录音里):voice = 孩子按住说的那一段(text 是嘴认成的字);mouth = 嘴接住的那句(text 是它说的)。
+ * audio 相对 conversations/<老师>/;seek = 这段在 audio 里从哪开始(整次通话是一条声音)
+ */
+export interface ReelClip {
+    kind: 'voice' | 'mouth';
+    job: string;
+    from: number;
+    to: number;
+    audio: string;
+    text?: string;
+    seek?: number;
+}
+/** 一节:什么时候出来、露几张卡的台阶(at 升序)、讲稿什么时候念完、末句是不是问句;streamed = 老师现讲(一拍一拍铺卡) */
+export interface ReelTrack {
+    job: string;
+    at: number;
+    streamed: boolean;
+    cards: {
+        at: number;
+        n: number;
+    }[];
+    doneAt: number;
+    ask: boolean;
+}
+/** 一条消息的旁注:节前的(谁说的、做了什么)在 at 出,节尾的(给家长的、记住了、没成)在 postAt 出 */
+export interface ReelNote {
+    job: string;
+    at: number;
+    postAt: number;
+}
+export interface ReelCardChange {
+    job: string;
+    card: number;
+    at: number;
+    state: unknown;
+}
+/** 可压缩的空白:wait = 开口之后老师还没出声(前 REEL_WAIT_KEEP_MS 照放,压的是其余);think = 老师说完到下一次开口。ms = 整段真实时长(标签上写的) */
+export interface ReelGap {
+    kind: 'wait' | 'think';
+    from: number;
+    to: number;
+    ms: number;
+    /** think 被孩子中途的动作(改卡、开关弹窗)切开的后一段:字幕写「又过了」,不是又想了一回 */
+    cont?: true;
+}
+/**
+ * 进度条上的点:said 孩子 / 家长开口、card 孩子改了一张卡、ask 老师停下等孩子、error 这轮没成、lecture 开始看小课堂、ink 在小课堂上画了一处、
+ * miss 按住说话没发出去(淡,偶尔一两次不算事)、misses 连着 REEL_MISS_STREAK 次以上没发出去(to 是这一串的末尾)
+ */
+export interface ReelMark {
+    kind: 'said' | 'card' | 'ask' | 'error' | 'lecture' | 'ink' | 'miss' | 'misses';
+    to?: number;
+    at: number;
+    job: string;
+    label: string;
+}
+/**
+ * 看小课堂的一段(第 5 步):孩子开口那条消息带来的看的过程,换成墙钟。log 每条:那一刻停在课里的哪儿、之后在不在放;
+ * marks:画下去的那一刻(at)、画在课里的哪一刻(atMs)与几笔(没记 t 的当在这段末尾)
+ */
+export interface ReelLecture {
+    job: string;
+    bundle: string;
+    title: string;
+    video: boolean;
+    from: number;
+    to: number;
+    log: {
+        at: number;
+        pos: number;
+        play: boolean;
+    }[];
+    marks: {
+        at: number;
+        atMs: number;
+        svgMs: number;
+        strokes: [number, number][][];
+        image?: string;
+    }[];
+}
+/** 按住说话的一次:按下 → 话筒开 → 松手 → 收尾 */
+export interface ReelHold {
+    from: number;
+    to: number;
+    audioAt: number | null;
+    upAt: number | null;
+    slides: {
+        at: number;
+        on: boolean;
+    }[];
+    result: ReelHoldResult | null;
+    lv: string;
+}
+/** 打字的一段:点进输入框到发了 / 收起;vals = 每次值变了 */
+export interface ReelType {
+    from: number;
+    to: number;
+    vals: {
+        at: number;
+        v: string;
+    }[];
+    sent: boolean;
+}
+/** 发照片屏开着的一段;photo = 发出去的那条的第一张照片(相对 workspace;取消了没有) */
+export interface ReelPhotoScreen {
+    from: number;
+    to: number;
+    tools: {
+        at: number;
+        tool: string;
+    }[];
+    sent: boolean;
+    photo: string | null;
+}
+export interface Reel {
+    startAt: number;
+    endAt: number;
+    tracks: ReelTrack[];
+    says: ReelSay[];
+    clips: ReelClip[];
+    cards: ReelCardChange[];
+    notes: ReelNote[];
+    /** 开口 → 老师第一声(字幕行「等老师 N 秒」) */
+    waits: {
+        job: string;
+        from: number;
+        to: number;
+    }[];
+    gaps: ReelGap[];
+    marks: ReelMark[];
+    /** 实录:弹窗开着的段、页面切到后台的段 */
+    stages: ReelStage[];
+    aways: {
+        from: number;
+        to: number;
+    }[];
+    /** 看小课堂的几段(没有 = 这个话题不是从小课堂开始的,或那时还不记) */
+    lectures: ReelLecture[];
+    /** 改版补记的:孩子屏幕尺寸、按住说话、打字、发照片屏、自己翻板书;连着没发出去的几串 */
+    views: {
+        at: number;
+        w: number;
+        h: number;
+        kb: number;
+        v: string;
+    }[];
+    holds: ReelHold[];
+    types: ReelType[];
+    photoScreens: ReelPhotoScreen[];
+    scrolls: {
+        at: number;
+        job: string;
+        card: number;
+        dy: number;
+    }[];
+    misses: {
+        from: number;
+        to: number;
+        n: number;
+    }[];
+}
+/** 开口后老师多久没出声以内照真实时间放(这就是孩子感受到的慢) */
+export declare const REEL_WAIT_KEEP_MS = 10000;
+/** 老师说完到下一次开口,超过这么久就压 */
+export declare const REEL_THINK_MIN_MS = 5000;
+/** 压过的一段空白放多久 */
+export declare const REEL_GAP_PLAY_MS = 1500;
+/** 最后一件事之后再留一会儿 */
+export declare const REEL_TAIL_MS = 1500;
+/** 按住说话连着几次没发出去(中间一句也没发成)才标出来(待定,真看几个话题再调) */
+export declare const REEL_MISS_STREAK = 3;
+/** 「没听清,再按住说一次」在输入条上留多久(同孩子端) */
+export declare const REEL_UNCLEAR_MS = 2500;
+/**
+ * 实时老师的一次通话(src/runtime/live/call.ts 落的 <日期>.live/<时分秒>.reel.json + .wav):实时的轮照它放,不推算。audio = 两边混好的那一条(相对 conversations/<老师>/);
+ * startAt = 通话开始的墙钟毫秒;msgs 的时刻、playing(嘴的声音在孩子端放的时段)都是离开始的毫秒(同 src/runtime/journal/recorder.ts 的 CallReel)
+ */
+export interface ReelCall {
+    audio: string;
+    startAt: number;
+    msgs: readonly (readonly [number, 'o' | 'i', Record<string, unknown>])[];
+    playing: readonly (readonly [number, number])[];
+}
+export interface ReelInput {
+    /** 这个话题的消息,索引顺序 */
+    messages: readonly ConversationMessage[];
+    /** job → 那轮的事件(没有 events.jsonl 的轮不在) */
+    events: Readonly<Record<string, readonly RunEvent[]>>;
+    cards: CardStates;
+    now: number;
+    /** 实录(第二期):这个话题各轮的 play.jsonl 合在一起 */
+    plays?: readonly PlayRecord[];
+    /** 实时的轮所在的通话;没有通话录像的实时轮当不是实时的(写完那一刻铺上) */
+    calls?: readonly ReelCall[];
+}
+/** 孩子(或家长)这句在进度条上写成什么:交给老师(从首页按钮进来又交卡的,交卡更要紧)、首页按钮字、原话 */
+export declare function reelSaid(m: Pick<ConversationMessage, 'text' | 'via' | 'action'>): string;
+/** 按住说话的几次:照 hold 实录分段(按下起、收尾止) */
+export declare function reelHolds(plays: readonly PlayRecord[]): ReelHold[];
+/** 前奏一段接一段:后一段开始前多久以内结束的前一段算连着(按住说话没认出来、马上又按一次) */
+export declare const REEL_LEAD_GAP_MS = 1500;
+/**
+ * 每章的章尾:上一章 / 下一章落在这里,不落章头。章尾 = 下一章的前奏开始之前;最后一章是 endAt。
+ * starts = 每章开头(墙钟,升序);leads = 孩子为开口做的动作的时段(按住说话、打字、发照片屏);前奏 = 跨过下一章开头、或在它前面
+ * REEL_LEAD_GAP_MS 以内结束的那一段,再一段段往前连。章尾不早于这一章的开头
+ */
+export declare function reelChapterEnds(starts: readonly number[], leads: readonly {
+    from: number;
+    to: number;
+}[], endAt: number): number[];
+/** 连着没发出去的几串:按时间走,发出去的一次或中间孩子发成了一句(sentAt:开口、打字发出去的时刻)就断开;够 REEL_MISS_STREAK 次才算 */
+export declare function reelMissRuns(holds: readonly ReelHold[], sentAt: readonly number[]): {
+    from: number;
+    to: number;
+    n: number;
+}[];
+/**
+ * 一个话题的录像;话题里一轮都没有 → null。实时的轮照通话放(callTrack);不是实时的轮(家长端试发、cotutor send、没有通话录像的)
+ * 写完那一刻整节铺上、不念(staticTrack)。孩子第一次开口之前的轮(系统起的)也一样,从它自己的时刻起。
+ */
+export declare function buildReel(input: ReelInput): Reel | null;
+/** 播放时钟:压过的空白各放 REEL_GAP_PLAY_MS,其余 1:1。real = 按真实时间(不压)。p = 从 0 起的播放毫秒 */
+export interface ReelClock {
+    total: number;
+    toWall: (p: number) => number;
+    toPlay: (w: number) => number;
+}
+export declare function reelClock(reel: Pick<Reel, 'startAt' | 'endAt' | 'gaps'>, real: boolean): ReelClock;
+/** 某一刻的样子 */
+export interface ReelFrame {
+    /** 出来了的节(按出来的先后):露几张卡(标注随卡露出来画) */
+    sections: {
+        job: string;
+        cards: number;
+    }[];
+    /** 正在念的一句:offset = 从这句开头过了多久 */
+    saying: {
+        job: string;
+        line: number;
+        offset: number;
+        audio: string | null;
+        seek?: number;
+    } | null;
+    /** 正在放的一段:孩子按住说的、嘴接住的那句(都在通话的录音里) */
+    clip: {
+        kind: ReelClip['kind'];
+        job: string;
+        offset: number;
+        audio: string;
+        text?: string;
+        seek?: number;
+    } | null;
+    /** 最近开始念的一句(不在念时字幕留着它) */
+    last: {
+        job: string;
+        line: number;
+    } | null;
+    /** `<job>/<卡>` → 这一刻的状态;不在 = 还没做 */
+    cards: Record<string, unknown>;
+    notes: {
+        job: string;
+        post: boolean;
+    }[];
+    /** 开口了、老师还没出声:等了多久 */
+    wait: {
+        job: string;
+        ms: number;
+    } | null;
+    gap: ReelGap | null;
+    /** 老师停下等孩子(末句问句念完了) */
+    asking: boolean;
+    /** 弹窗开着(实录):哪一张 */
+    stage: {
+        job: string;
+        card: number;
+    } | null;
+    /** 弹窗开着、这张卡孩子还没动:想了多久(切到后台的时间不算) */
+    thinking: {
+        job: string;
+        card: number;
+        ms: number;
+    } | null;
+    /** 孩子切到别处了(页面在后台) */
+    away: boolean;
+    /** 在看小课堂:看的是哪一课、停在课里的哪一刻、在不在放、到这一刻画过的几处 */
+    lecture: {
+        job: string;
+        bundle: string;
+        title: string;
+        video: boolean;
+        pos: number;
+        playing: boolean;
+        marks: ReelLecture['marks'];
+    } | null;
+    /**
+     * 孩子按着说话:wait = 话筒还没开(「等一下…」)、live = 在听、tail = 松手了在收尾(「正在听清…」);text = 到这一刻认出的字;
+     * slide = 手上滑到了取消区;lv = 到这一刻为止最近 25 个 100 毫秒的音量(0–9;没记 = null,页面用假波形);diag = 老话题推的
+     */
+    hold: {
+        phase: 'wait' | 'live' | 'tail';
+        slide: boolean;
+        lv: string | null;
+    } | null;
+    /** 输入条上「没听清,再按住说一次」那 2.5 秒 */
+    unclear: boolean;
+    /** 在打字:输入框里这一刻的字 */
+    typing: {
+        v: string;
+    } | null;
+    /** 发照片屏开着:最近用的工具、发出去的那张照片 */
+    photoScreen: {
+        tool: string;
+        photo: string | null;
+    } | null;
+    /** 孩子屏幕这一刻的尺寸与键盘高(还没记 = null) */
+    view: {
+        w: number;
+        h: number;
+        kb: number;
+    } | null;
+    /** 孩子自己最近一次翻到哪(at 是那一刻) */
+    scroll: {
+        at: number;
+        job: string;
+        card: number;
+        dy: number;
+    } | null;
+    /** 在一串连着没发出去的按住里:一共几次、这是第几次(还在两次之间也算) */
+    miss: {
+        n: number;
+        k: number;
+    } | null;
+}
+export declare function reelFrameAt(reel: Reel, t: number): ReelFrame;
+/**
+ * 一张卡孩子在弹窗里想了多久、改了几次:[after, before) 里这张卡的弹窗加在一起——
+ * 第一次打开到第一次改动(切到后台的不算)= 想了多久;改动的次数。没打开过弹窗 → null;打开了没改 → think = null
+ */
+export declare function reelCardTook(plays: readonly PlayRecord[], job: string, card: number, after: number, before: number): {
+    think: number | null;
+    changes: number;
+} | null;
+/** 「2 分 10 秒」「23 秒」「1 小时 5 分」 */
+export declare function reelDuration(ms: number): string;