cotutor 0.2.0 → 0.3.0

package/dist/board/lecture.d.ts

@@ -0,0 +1,100 @@
+/**
+ * 小课堂的纯函数:服务端(课长、上下文包 lecture: 的每句起点、画的地方盖着什么)与舞台包(播放器)共用。
+ *
+ * 课包的时钟、几何、圈住了什么(这里拿来说画的地方盖着什么)都在 src/chalk(纯计算,不带 React,服务端能 import):一段 = 一步,段长 = max(画, 配音),
+ * 课的 0 毫秒对着 SVG 的 START_MS;笔画按配音拉伸,和 buildAnimatedSvg 画出来的同一份时间。这里用小课堂的名字转出来
+ * (视频也有时钟,videoClock),外加小课堂自己的:时间怎么写、上下文包的每句、老师放的那一段、视频的 lecture.md。
+ */
+import { type LessonPicture } from '../chalk/index.ts';
+import type { LessonClock, LessonSegment } from '../chalk/index.ts';
+export { lessonClock as lectureClock, clockAt as lectureAt, START_MS as DRAW_START_MS } from '../chalk/index.ts';
+export type { ChalkSkeleton as LectureSkeleton, ChalkStep as LectureStep, ChalkBlock as LectureBlock, ChalkGroup as LectureGroup, LessonPicture as LecturePicture } from '../chalk/index.ts';
+/** 小课堂的时钟:课包的(src/chalk 的 lessonClock)或视频的(videoClock,没有画面元素) */
+export type LectureClock = LessonClock;
+export type LectureSegment = LessonSegment;
+/** 毫秒 → 「分:秒」;一小时以上「时:分:秒」 */
+export declare function clockLabel(ms: number): string;
+/** 上下文包 lecture.lines:每段一句「0:18 讲稿」 */
+export declare function lectureLines(clock: Pick<LectureClock, 'segments'>): string[];
+/** 换了 src 声音迟迟不出来,等多久就不等了,按墙上的钟走(毫秒) */
+export declare const VOICE_STALL_MS = 1500;
+/**
+ * 放着的时候时钟下一刻走到哪(课包):这一段的配音在放,跟着配音走——
+ * 「段起点 + 配音放到哪」,声音还没出来就停在原地等(不往回退);等过 VOICE_STALL_MS、配音放完了、没在放配音,按墙上的钟走 dt。
+ * voice:正在放的是第几段的配音、放到哪(毫秒)、位置多久没动了;没在放 = null。
+ */
+export declare function lectureNext(clock: Pick<LectureClock, 'segments' | 'total'>, cur: number, dt: number, voice: {
+    index: number;
+    posMs: number;
+    stalledMs: number;
+} | null): number;
+/** 一处画:课里的时刻 + 几笔(课包画面坐标,即 scene.json 的坐标系;视频是视频自己的像素坐标) */
+export interface LectureMark {
+    atMs: number;
+    strokes: [number, number][][];
+}
+/** 一堂课最多画几处(播放器与路由都拦):一处一张截图,和孩子拍的照片一共不过 9 张 */
+export declare const MARK_MAX = 6;
+/** 一处最多几笔、一共几个点;一笔的点抽到 MARK_STROKE_POINTS 以内 */
+export declare const MARK_MAX_STROKES = 60;
+export declare const MARK_MAX_POINTS = 1200;
+export declare const MARK_STROKE_POINTS = 300;
+/** 「0:26 画的,那时在讲『…』」:一处画给老师、家长的那段话的头 */
+export declare function markHead(clock: LectureClock, atMs: number): string;
+/**
+ * 几笔 → 给 src/chalk circleHits 的一圈:所有点的凸包(圈了一圈就是那一圈,没封口的也合上);
+ * 太细的(划一道、点一下)用外框,各边放宽到 MIN_RING。没有点 = []。
+ */
+export declare function inkRing(strokes: readonly (readonly [number, number][])[]): [number, number][];
+/**
+ * 画的地方盖着什么(只给课包,老师对着截图时的提示,用课里的叫法):「画的地方盖着:散的 3 根小棒;文字『3』」/「画在文字『3』旁边」/
+ * 「画的地方那时还没画东西」。认的是 src/chalk 的 circleHits(分组 > 命中块 > 带 label 的元素 > 文字 > 没字的按第几步、什么、颜色归堆),圈是 inkRing。
+ */
+export declare function inkHint(clock: LectureClock, mark: LectureMark, picture?: LessonPicture): {
+    text: string;
+    ids: string[];
+};
+/** 一处画说成一段话(不带截图那半):「0:26 画的,那时在讲『…』;画的地方盖着:…」 */
+export declare function describeMark(clock: LectureClock, mark: LectureMark, picture?: LessonPicture): {
+    text: string;
+    ids: string[];
+};
+/** 「分:秒」「时:分:秒」→ 毫秒;认不出来 null */
+export declare function parseClock(s: string): number | null;
+/**
+ * 卡上写的一段 → 真放的起止(毫秒)。lines: 里的时间是段起点取整到秒,老师照抄的「0:19」其实是 19.4 秒那段的开头:
+ * 起止落在某个段界前后一秒内,就对齐到那个段界(不多放前一段的尾巴、不切掉这一段的末字)。
+ * 不写止 = 放到起点所在那一段的末尾;都不写 = 整堂课。越界夹到课里;止不在起之后 = null。
+ */
+export declare function lectureRange(clock: Pick<LectureClock, 'segments' | 'total'>, from: number | undefined, to: number | undefined): {
+    start: number;
+    end: number;
+} | null;
+export declare const LECTURE_FILE = "lecture.md";
+export declare const LECTURE_VIDEO = "video.mp4";
+export interface LectureDocIssue {
+    level: 'fix' | 'note';
+    text: string;
+    line?: number;
+}
+export interface LectureDoc {
+    title: string;
+    subject: string | null;
+    /** 一句一条:在视频里的起点(毫秒)与原话 */
+    chapters: {
+        start: number;
+        line: string;
+        at: number;
+    }[];
+    issues: LectureDocIssue[];
+}
+/**
+ * lecture.md:frontmatter(subject 可写)+ `# 标题` + 一行一句「分:秒 原话」(这一句在视频里的起点)。
+ * 别的行不认(给人看的话写在注释里);永不抛,问题带行号。时长不在这里查(要读 mp4),由调用方对。
+ */
+export declare function parseLectureDoc(md: string): LectureDoc;
+/** 视频的时钟:一句一段(起点到下一句的起点,最后一句到视频末尾);没有画面元素,SVG 那几个数都是 0 */
+export declare function videoClock(chapters: readonly {
+    start: number;
+    line: string;
+}[], totalMs: number): LectureClock;

package/dist/board/lecture.js

@@ -0,0 +1,204 @@
+/**
+ * 小课堂的纯函数:服务端(课长、上下文包 lecture: 的每句起点、画的地方盖着什么)与舞台包(播放器)共用。
+ *
+ * 课包的时钟、几何、圈住了什么(这里拿来说画的地方盖着什么)都在 src/chalk(纯计算,不带 React,服务端能 import):一段 = 一步,段长 = max(画, 配音),
+ * 课的 0 毫秒对着 SVG 的 START_MS;笔画按配音拉伸,和 buildAnimatedSvg 画出来的同一份时间。这里用小课堂的名字转出来
+ * (视频也有时钟,videoClock),外加小课堂自己的:时间怎么写、上下文包的每句、老师放的那一段、视频的 lecture.md。
+ */
+import { circleHits, clockAt, hitPhrase } from "../chalk/index.js";
+export { lessonClock as lectureClock, clockAt as lectureAt, START_MS as DRAW_START_MS } from "../chalk/index.js";
+/** 毫秒 → 「分:秒」;一小时以上「时:分:秒」 */
+export function clockLabel(ms) {
+    const s = Math.max(0, Math.floor(ms / 1000));
+    const h = Math.floor(s / 3600);
+    const m = Math.floor((s % 3600) / 60);
+    const ss = String(s % 60).padStart(2, '0');
+    return h ? `${h}:${String(m).padStart(2, '0')}:${ss}` : `${m}:${ss}`;
+}
+/** 上下文包 lecture.lines:每段一句「0:18 讲稿」 */
+export function lectureLines(clock) {
+    return clock.segments.map((s) => `${clockLabel(s.start)} ${s.line.trim()}`);
+}
+/** 换了 src 声音迟迟不出来,等多久就不等了,按墙上的钟走(毫秒) */
+export const VOICE_STALL_MS = 1500;
+/**
+ * 放着的时候时钟下一刻走到哪(课包):这一段的配音在放,跟着配音走——
+ * 「段起点 + 配音放到哪」,声音还没出来就停在原地等(不往回退);等过 VOICE_STALL_MS、配音放完了、没在放配音,按墙上的钟走 dt。
+ * voice:正在放的是第几段的配音、放到哪(毫秒)、位置多久没动了;没在放 = null。
+ */
+export function lectureNext(clock, cur, dt, voice) {
+    const wall = Math.min(clock.total, cur + dt);
+    if (!voice)
+        return wall;
+    const s = clock.segments[voice.index];
+    if (!s || s.audioMs === null || voice.posMs >= s.audioMs || voice.stalledMs > VOICE_STALL_MS)
+        return wall;
+    // 声音是别的段的(刚拖过、刚换段):不跟
+    if (cur < s.start || cur >= s.start + s.len)
+        return wall;
+    return Math.min(clock.total, Math.max(cur, s.start + voice.posMs));
+}
+/** 一堂课最多画几处(播放器与路由都拦):一处一张截图,和孩子拍的照片一共不过 9 张 */
+export const MARK_MAX = 6;
+/** 一处最多几笔、一共几个点;一笔的点抽到 MARK_STROKE_POINTS 以内 */
+export const MARK_MAX_STROKES = 60;
+export const MARK_MAX_POINTS = 1200;
+export const MARK_STROKE_POINTS = 300;
+/** 「0:26 画的,那时在讲『…』」:一处画给老师、家长的那段话的头 */
+export function markHead(clock, atMs) {
+    const line = clock.segments[clockAt(clock, atMs).index]?.line.trim() ?? '';
+    return `${clockLabel(atMs)} 画的${line ? `,那时在讲『${line}』` : ''}`;
+}
+/** 太细的一处(一条线、一个点)给 circleHits 的框至少多宽(课包坐标) */
+const MIN_RING = 24;
+/**
+ * 几笔 → 给 src/chalk circleHits 的一圈:所有点的凸包(圈了一圈就是那一圈,没封口的也合上);
+ * 太细的(划一道、点一下)用外框,各边放宽到 MIN_RING。没有点 = []。
+ */
+export function inkRing(strokes) {
+    const pts = strokes.flat().slice().sort((a, b) => a[0] - b[0] || a[1] - b[1]);
+    if (!pts.length)
+        return [];
+    // 凸包(Andrew 单调链)
+    const cross = (o, a, b) => (a[0] - o[0]) * (b[1] - o[1]) - (a[1] - o[1]) * (b[0] - o[0]);
+    const half = (list) => {
+        const h = [];
+        for (const p of list) {
+            while (h.length >= 2 && cross(h[h.length - 2], h[h.length - 1], p) <= 0)
+                h.pop();
+            h.push(p);
+        }
+        h.pop();
+        return h;
+    };
+    const hull = [...half(pts), ...half(pts.slice().reverse())];
+    const xs = pts.map((p) => p[0]), ys = pts.map((p) => p[1]);
+    const [x0, x1, y0, y1] = [Math.min(...xs), Math.max(...xs), Math.min(...ys), Math.max(...ys)];
+    if (hull.length >= 3 && x1 - x0 >= MIN_RING && y1 - y0 >= MIN_RING)
+        return hull;
+    const cx = (x0 + x1) / 2, cy = (y0 + y1) / 2, hw = Math.max(x1 - x0, MIN_RING) / 2, hh = Math.max(y1 - y0, MIN_RING) / 2;
+    return [[cx - hw, cy - hh], [cx + hw, cy - hh], [cx + hw, cy + hh], [cx - hw, cy + hh]];
+}
+/**
+ * 画的地方盖着什么(只给课包,老师对着截图时的提示,用课里的叫法):「画的地方盖着:散的 3 根小棒;文字『3』」/「画在文字『3』旁边」/
+ * 「画的地方那时还没画东西」。认的是 src/chalk 的 circleHits(分组 > 命中块 > 带 label 的元素 > 文字 > 没字的按第几步、什么、颜色归堆),圈是 inkRing。
+ */
+export function inkHint(clock, mark, picture = {}) {
+    const ring = inkRing(mark.strokes);
+    if (!ring.length)
+        return { text: '', ids: [] };
+    const r = circleHits(clock, mark.atMs, ring, picture);
+    const say = (h) => hitPhrase(h).replace('(圈住了其中', '(盖着其中');
+    const text = r.kind === 'hit' ? `画的地方盖着:${r.hits.map(say).join(';')}` : r.kind === 'near' && r.near ? `画在${say(r.near)}旁边` : r.kind === 'empty' ? '画的地方那时还没画东西' : '';
+    return { text, ids: r.ids };
+}
+/** 一处画说成一段话(不带截图那半):「0:26 画的,那时在讲『…』;画的地方盖着:…」 */
+export function describeMark(clock, mark, picture = {}) {
+    const h = inkHint(clock, mark, picture);
+    return { text: `${markHead(clock, mark.atMs)}${h.text ? `;${h.text}` : ''}`, ids: h.ids };
+}
+// ---- 老师放课里的一段:lecture 卡写「<课包 id> 0:19-0:30」 ----
+/** 「分:秒」「时:分:秒」→ 毫秒;认不出来 null */
+export function parseClock(s) {
+    const m = /^(?:(\d{1,2}):)?(\d{1,3}):(\d{2})$/.exec(s.trim());
+    if (!m)
+        return null;
+    const [h, mm, ss] = [Number(m[1] ?? 0), Number(m[2]), Number(m[3])];
+    if (ss >= 60 || (m[1] !== undefined && mm >= 60))
+        return null;
+    return ((h * 60 + mm) * 60 + ss) * 1000;
+}
+/**
+ * 卡上写的一段 → 真放的起止(毫秒)。lines: 里的时间是段起点取整到秒,老师照抄的「0:19」其实是 19.4 秒那段的开头:
+ * 起止落在某个段界前后一秒内,就对齐到那个段界(不多放前一段的尾巴、不切掉这一段的末字)。
+ * 不写止 = 放到起点所在那一段的末尾;都不写 = 整堂课。越界夹到课里;止不在起之后 = null。
+ */
+export function lectureRange(clock, from, to) {
+    if (!clock.segments.length)
+        return null;
+    const bounds = [...clock.segments.map((s) => s.start), clock.total];
+    const snap = (ms) => bounds.find((b) => b >= ms && b - ms < 1000) ?? ms;
+    const start = from === undefined ? 0 : Math.min(snap(from), clock.total);
+    let end;
+    if (to !== undefined)
+        end = Math.min(snap(to), clock.total);
+    else if (from === undefined)
+        end = clock.total;
+    else {
+        const i = clockAt(clock, start).index;
+        end = clock.segments[i].start + clock.segments[i].len;
+    }
+    return end > start ? { start, end } : null;
+}
+// ---- 视频来源(第 4 步):lectures/<id>/lecture.md + video.mp4 ----
+export const LECTURE_FILE = 'lecture.md';
+export const LECTURE_VIDEO = 'video.mp4';
+/**
+ * lecture.md:frontmatter(subject 可写)+ `# 标题` + 一行一句「分:秒 原话」(这一句在视频里的起点)。
+ * 别的行不认(给人看的话写在注释里);永不抛,问题带行号。时长不在这里查(要读 mp4),由调用方对。
+ */
+export function parseLectureDoc(md) {
+    const lines = md.replace(/<!--[\s\S]*?-->/g, (c) => '\n'.repeat(c.split('\n').length - 1)).split(/\r?\n/);
+    const issues = [];
+    let start = 0;
+    let subject = null;
+    if (/^---\s*$/.test(lines[0] ?? '')) {
+        const close = lines.findIndex((l, i) => i > 0 && /^---\s*$/.test(l));
+        if (close < 0)
+            issues.push({ level: 'fix', line: 1, text: 'frontmatter 没闭合:key: value 那几行之后单独一行写 ---' });
+        else {
+            for (let i = 1; i < close; i++) {
+                const m = /^([A-Za-z][\w-]*):\s*(.*)$/.exec(lines[i]);
+                if (m?.[1] === 'subject' && m[2].trim())
+                    subject = m[2].trim();
+                else if (lines[i].trim())
+                    issues.push({ level: 'note', line: i + 1, text: `frontmatter 只认 subject:${lines[i].trim()}` });
+            }
+            start = close + 1;
+        }
+    }
+    let title = '';
+    const chapters = [];
+    for (let i = start; i < lines.length; i++) {
+        const l = lines[i].trim();
+        if (!l)
+            continue;
+        const h = /^#\s+(.+)$/.exec(l);
+        if (h && !title) {
+            title = h[1].trim();
+            continue;
+        }
+        const m = /^((?:\d{1,2}:)?\d{1,3}:\d{2})\s+(.+)$/.exec(l);
+        const ms = m ? parseClock(m[1]) : null;
+        if (m && ms !== null) {
+            const prev = chapters[chapters.length - 1];
+            if (prev && ms <= prev.start)
+                issues.push({ level: 'fix', line: i + 1, text: `时间要一句比一句晚:${m[1]} 不晚于上一句的 ${clockLabel(prev.start)}` });
+            else
+                chapters.push({ start: ms, line: m[2].trim(), at: i + 1 });
+        }
+        else
+            issues.push({ level: 'note', line: i + 1, text: `这行不认(一行一句写「分:秒 原话」,给人看的话写在 <!-- --> 里):${l.slice(0, 30)}` });
+    }
+    if (!title)
+        issues.push({ level: 'fix', line: start + 1, text: '要有一行 # 标题(孩子首页按钮上、老师上下文包里的课名)' });
+    if (!chapters.length)
+        issues.push({ level: 'fix', text: '一句都没有:一行一句写「分:秒 原话」,老师靠它知道课里讲了什么、孩子停在哪' });
+    else if (chapters[0].start !== 0)
+        issues.push({ level: 'note', line: chapters[0].at, text: `第一句从 ${clockLabel(chapters[0].start)} 起,前面那段老师不知道在讲什么` });
+    return { title, subject, chapters, issues };
+}
+/** 视频的时钟:一句一段(起点到下一句的起点,最后一句到视频末尾);没有画面元素,SVG 那几个数都是 0 */
+export function videoClock(chapters, totalMs) {
+    const cs = chapters.filter((c) => c.start < totalMs);
+    const segments = cs.map((c, i) => {
+        const end = i + 1 < cs.length ? cs[i + 1].start : totalMs;
+        return { index: i, start: c.start, len: Math.max(1, end - c.start), drawStart: 0, drawEnd: 0, audioMs: null, line: c.line };
+    });
+    // 第一句不从 0 起:前面补一段没有话的
+    if (segments.length && segments[0].start > 0) {
+        segments.unshift({ index: 0, start: 0, len: segments[0].start, drawStart: 0, drawEnd: 0, audioMs: null, line: '' });
+        segments.forEach((s, i) => { s.index = i; });
+    }
+    return { skeletons: [], segments, total: segments.length ? totalMs : 0, elements: new Map() };
+}

package/dist/board/paper.d.ts

@@ -0,0 +1,20 @@
+import type { Workspace } from '../schema/index.ts';
+import { type CanvasState } from './cards/canvas.ts';
+import type { ConversationMessage } from '../schema/index.ts';
+/** 纸的名字:话题 id(<HHMM>-<n>),或 new(话题还没有) */
+export declare const PAPER_KEY_RE: RegExp;
+/** 只交了画、没说话时这条消息的字(同「(拍了一张)」;孩子端不把它当孩子说的话,board/presentation.ts 的 DRAW_ONLY) */
+export declare const DRAW_ONLY_TEXT = "(\u753B\u4E86\u4E00\u5F20,\u6CA1\u8BF4\u8BDD)";
+export type PaperState = Pick<CanvasState, 'ink' | 'cleared'>;
+/** 读一张纸;没有、坏了都是空白的 */
+export declare function readPaper(ws: Workspace, tutor: string, date: string, key: string): Promise<PaperState>;
+/** 存一张纸(整份),另记一行实录 */
+export declare function writePaper(ws: Workspace, tutor: string, date: string, key: string, state: PaperState, now: Date): Promise<void>;
+/** 新话题的第一条发出去了:话题还没有时画的那张(new)归这个话题;这个话题已经有一张就不动 */
+export declare function adoptPaper(ws: Workspace, tutor: string, date: string, thread: string): Promise<void>;
+/** 删一张纸(测试、清场用) */
+export declare function dropPaper(ws: Workspace, tutor: string, date: string, key: string): Promise<void>;
+/** 交画:按纸上的笔迹算这条消息记的摘要(几笔、各颜色几笔、画了多久、清掉的那几版的图) */
+export declare function paperDrawing(state: PaperState, image: string): NonNullable<ConversationMessage['drawing']>;
+/** 上下文包 drawing: 那一句;first = 这张画在 photos 里是第几张(1 起),清掉的那几版紧跟在后面 */
+export declare function drawingPackLine(d: NonNullable<ConversationMessage['drawing']>, first: number): string;

package/dist/board/paper.js

@@ -0,0 +1,76 @@
+/**
+ * 左栏的纸:孩子在实时老师页左栏点「画板」打开的那张,一个话题一张,一直能改,关了不丢。
+ * 存 conversations/<老师>/<日期>.<话题>.paper.json(状态同画板卡:笔迹 + 清空前存的那几版),每次存另记一行 .paper.jsonl(以后录像现画用);
+ * 话题还没有(新话题、空板)时叫 new,这个话题的第一条发出去就改名成话题 id(adoptPaper)。删话题按 <日期>.<话题>.* 一起删。
+ * 「给老师看」时孩子端先把导出的图传进 captures/,消息带 {drawing: {key, image}};这里按纸上的笔迹算摘要(几笔、各颜色、多久、清掉的那几版),记进消息。
+ */
+import { appendFile, mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { CanvasStateSchema } from "./cards/canvas.js";
+import { canvasStrokes, canvasSummary, canvasMinutesText } from "./canvas-chat.js";
+/** 纸的名字:话题 id(<HHMM>-<n>),或 new(话题还没有) */
+export const PAPER_KEY_RE = /^(?:new|\d{4}-\d+)$/;
+/** 只交了画、没说话时这条消息的字(同「(拍了一张)」;孩子端不把它当孩子说的话,board/presentation.ts 的 DRAW_ONLY) */
+export const DRAW_ONLY_TEXT = '(画了一张,没说话)';
+const paperFile = (ws, tutor, date, key, ext) => join(ws.dirs.conversations, tutor, `${date}.${key}.paper.${ext}`);
+/** 读一张纸;没有、坏了都是空白的 */
+export async function readPaper(ws, tutor, date, key) {
+    if (!PAPER_KEY_RE.test(key))
+        return { ink: [] };
+    try {
+        const r = CanvasStateSchema.safeParse(JSON.parse(await readFile(paperFile(ws, tutor, date, key, 'json'), 'utf8')));
+        if (r.success)
+            return { ink: r.data.ink, ...(r.data.cleared?.length ? { cleared: r.data.cleared } : {}) };
+    }
+    catch { /* 没有 */ }
+    return { ink: [] };
+}
+/** 存一张纸(整份),另记一行实录 */
+export async function writePaper(ws, tutor, date, key, state, now) {
+    const st = { ink: state.ink, ...(state.cleared?.length ? { cleared: state.cleared } : {}) };
+    await mkdir(join(ws.dirs.conversations, tutor), { recursive: true });
+    await writeFile(paperFile(ws, tutor, date, key, 'json'), JSON.stringify(st));
+    await appendFile(paperFile(ws, tutor, date, key, 'jsonl'), `${JSON.stringify({ at: now.getTime(), k: 'paper', state: st })}\n`).catch(() => { });
+}
+/** 新话题的第一条发出去了:话题还没有时画的那张(new)归这个话题;这个话题已经有一张就不动 */
+export async function adoptPaper(ws, tutor, date, thread) {
+    if (!PAPER_KEY_RE.test(thread) || thread === 'new')
+        return;
+    const from = paperFile(ws, tutor, date, 'new', 'json');
+    if (!existsSync(from) || existsSync(paperFile(ws, tutor, date, thread, 'json')))
+        return;
+    await rename(from, paperFile(ws, tutor, date, thread, 'json')).catch(() => { });
+    await rename(paperFile(ws, tutor, date, 'new', 'jsonl'), paperFile(ws, tutor, date, thread, 'jsonl')).catch(() => { });
+}
+/** 删一张纸(测试、清场用) */
+export async function dropPaper(ws, tutor, date, key) {
+    for (const ext of ['json', 'jsonl'])
+        await rm(paperFile(ws, tutor, date, key, ext), { force: true });
+}
+/** 交画:按纸上的笔迹算这条消息记的摘要(几笔、各颜色几笔、画了多久、清掉的那几版的图) */
+export function paperDrawing(state, image) {
+    const sum = canvasSummary(canvasStrokes(state.ink));
+    const cleared = state.cleared ?? [];
+    const named = sum.colors.filter((c) => c.name !== '别的颜色');
+    const starts = [...cleared.map((c) => c.from ?? c.at), ...(sum.firstAt !== null ? [sum.firstAt] : [])].filter((x) => x > 0);
+    const end = sum.lastAt ?? (cleared.length ? cleared[cleared.length - 1].at : null);
+    const imgs = cleared.flatMap((c) => (c.image ? [c.image] : []));
+    return {
+        image,
+        strokes: sum.strokes,
+        ...(named.length ? { colors: named.map((c) => `${c.name} ${c.strokes}`).join('、') } : {}),
+        ...(starts.length && end !== null ? { ms: Math.max(0, end - Math.min(...starts)) } : {}),
+        ...(imgs.length ? { cleared: imgs } : {}),
+    };
+}
+/** 上下文包 drawing: 那一句;first = 这张画在 photos 里是第几张(1 起),清掉的那几版紧跟在后面 */
+export function drawingPackLine(d, first) {
+    const parts = [`孩子在纸上画的,photos 第 ${first} 张`, `画了 ${d.strokes} 笔${d.colors ? `(${d.colors})` : ''}`];
+    if (d.ms !== undefined)
+        parts.push(`画了${canvasMinutesText(d.ms)}`);
+    const n = d.cleared?.length ?? 0;
+    if (n)
+        parts.push(`清空重画过,清掉的那几版是 photos 第 ${n === 1 ? first + 1 : `${first + 1}–${first + n}`} 张`);
+    return parts.join(';');
+}

package/dist/board/parse.d.ts

@@ -0,0 +1,120 @@
+/**
+ * 板书解析器:老师的回复正文(已剥掉「记账」段)→ 一节 BoardSection。
+ * 三条规则(见 docs/卡片协议.md):围栏 = 卡(标签第一个词是 kind),普通行 = 讲稿一句,第一个 H2 起是给家长的尾巴。
+ * 讲稿句里 [词] 是标注(落到第一张含这个词的卡,整节找,卡在前在后都行),[[名 参数]] 是对上一张卡的动作(cue)。
+ * partial 模式给流式用:没闭合的围栏和没换行结束的最后一行压着不算,下次整段重解析自然补上。
+ * 永不抛错:围栏没闭合当到文末,卡解析不出退成文字卡并记一句 warning。
+ * spans 是「这张卡 / 这句话是原文哪几行」,家长端「看原文」据此在原文旁边标出解析器怎么读的;孩子端的 BoardSection 不带它。
+ */
+import { type CardPlace } from './cards/index.ts';
+import { type BoardCard, type BoardCue, type BoardLine, type BoardSection, type Device } from './presentation.ts';
+export interface ParseBoardOptions {
+    /** 文本还在长(流式):压住没闭合的围栏与没换行结束的最后一行 */
+    partial?: boolean;
+    /** 卡用在哪(缺省板书);首页文件同一个解析器,place = home */
+    place?: CardPlace;
+    /** 围栏行上写了排版修饰词(same)时,排出来的行是给哪个端的(layout.for);缺省平板横屏 */
+    device?: Device;
+    /** 实时的一轮:板是脑写的笔记与练习,末句的问话不补成提问卡(字幕上就是这句) */
+    live?: boolean;
+}
+/**
+ * 排版修饰词:写在围栏标签里种类后面,哪种卡都认,解析器先摘掉再按种类解析——
+ * `same` 和上一张并排(没写 = 孩子端按卡的宽度排,board/presentation.ts 的 rowsFor)、`tint=<底色槽>`、`look=<字形槽>`、`emoji=<一个>`。槽名没人对着主题查(解析器不认识主题),对不上的 CSS 落回缺省。
+ * 老师也写得出来:cotutor-board 技能不教,写了就当已定
+ */
+export interface CardMods {
+    same?: true;
+    tint?: string;
+    look?: string;
+    emoji?: string;
+}
+export declare function splitMods(tag: string): {
+    rest: string;
+    mods: CardMods;
+    warnings: string[];
+};
+/** 解析提醒;line = 出问题的那一行(0 起,相对传进来的文本),没有行的就不带 */
+export interface BoardWarning {
+    text: string;
+    line?: number;
+    /** 这张卡没照标签解析成(退了文字卡 / 代码卡) */
+    fallback?: boolean;
+}
+/** 行区间 [起, 止],含两端,0 起 */
+export type LineSpan = [number, number];
+export interface BoardSpans {
+    /** 与 section.cards 同序 */
+    cards: LineSpan[];
+    /** 与 section.lines 同序 */
+    lines: LineSpan[];
+    /** 第一个 H2 起到文末 */
+    tail: LineSpan | null;
+    /** 写成正文的工具调用(TOOL_OPEN 起到收尾行),不进板书 */
+    toolCalls: LineSpan[];
+}
+export interface ParsedBoard {
+    section: BoardSection;
+    /** 没解析成的卡等,家长视图转录里显示;孩子端不报 */
+    warnings: BoardWarning[];
+    /** 第一个 H2 起的尾巴(老师写的任何标题段,原文含标题行);没有 = 空串 */
+    tail: string;
+    spans: BoardSpans;
+}
+/** 讲稿一行的清洗:去掉老师不该写但常写的标题号、列表号、引用号、粗体号;整行的 HTML 注释不算话 */
+export declare function cleanSpeech(line: string): string;
+/** 一句讲稿交给嘴时要带的:[[play]] 到小课堂卡、热身的 echo / say、call(runner 的 line 事件、mock 的假嘴都用它) */
+export declare function lineFlags(line: {
+    cues?: readonly BoardCue[];
+    echo?: BoardLine['echo'];
+    call?: true;
+}, cards: readonly BoardCard[]): {
+    play?: true;
+    echo?: NonNullable<BoardLine['echo']>;
+    call?: true;
+};
+/** 这句的 [[play]] 锚着小课堂卡:念完放卡上那一段(实时时服务端在这句之后等孩子端放完再交讲稿,src/runtime/delivery/queue.ts) */
+export declare function playsLecture(line: {
+    cues?: readonly BoardCue[];
+}, cards: readonly BoardCard[]): boolean;
+export declare function parseBoard(text: string, opts?: ParseBoardOptions): ParsedBoard;
+/** 回复停在写成正文的工具调用上(后面只剩空行):老师在等工具的结果,这一轮其实没写完(runner 据此 resume 一次) */
+export declare function endsWithToolCall(text: string): boolean;
+/** 原文一行的角色:解析器把它当什么了 */
+export type SourceRole = 
+/** 讲稿一句(念出来) */
+'say'
+/** 卡的围栏(开头行 / 中间 / 结尾) */
+ | 'card'
+/** 第一个 H2 起给家长的尾巴 */
+ | 'tail'
+/** 被「## 记账」吃掉,不进板书 */
+ | 'section'
+/** 空行 */
+ | 'blank'
+/** 落在地上的行:清洗完是空的(整行注释等) */
+ | 'drop';
+export interface SourceRow {
+    /** 0 起 */
+    line: number;
+    text: string;
+    role: SourceRole;
+    /** 右边那句「卡 2 · text formula」「讲稿 1 · 播」 */
+    label?: string;
+    /** role=card 时是第几张卡(0 起);role=say 时是第几句 */
+    index?: number;
+    /** 围栏开头那行 */
+    open?: boolean;
+}
+export interface AnnotatedSource {
+    rows: SourceRow[];
+    /** 行号换算成原文的 */
+    warnings: BoardWarning[];
+    section: BoardSection;
+    tail: string;
+}
+/**
+ * 家长端「看原文」用:把老师原文的每一行标上解析器怎么读的。
+ * 不另写一套解析——真跑 parseSections + parseBoard,再把它们的行号映回原文,所以永远不会和真解析漂开。
+ */
+export declare function annotateSource(text: string, opts?: Pick<ParseBoardOptions, 'live'>): AnnotatedSource;