cotutor 0.2.0 → 0.4.0

package/dist/runtime/kid-view.d.ts

@@ -0,0 +1,124 @@
+import { type Bookkeeping, type ConversationMessage } from '../schema/index.ts';
+import { type CardAssets, type CardStates } from '../schema/index.ts';
+import type { BoardSection, KidDrawing, KidLecture } from '../board/presentation.ts';
+import type { Transcript } from '../brain/transcript.ts';
+export interface KidView {
+    /** 给孩子的话(讲稿各句,换行分隔);null = 这次运行没有(出错、还在跑、或最终文本剥完是空的) */
+    kidText: string | null;
+    truncated: boolean;
+    /** 记账任务的回答(「## 记账」段);应用按它写日记 */
+    bookkeeping: Bookkeeping | null;
+    /** 「## 记忆」段的条目;应用追加进 vault 的记忆文件 */
+    memory: string[];
+    /** 运行是否正常收尾 */
+    ok: boolean;
+    /** 板书节(卡 + 讲稿);没有卡也没有讲稿 = null */
+    section: BoardSection | null;
+    /** 解析时的提醒(卡没解析成等),家长视图转录里显示 */
+    warnings: string[];
+    /** 第一个 H2 起给家长的尾巴(老师写的任何标题段);没有 = 空串 */
+    parentText: string;
+}
+/** 按码点数截断;能在句末断就在句末断(不加省略号),否则硬截加 … */
+export declare function truncateReply(text: string, max: number): {
+    text: string;
+    truncated: boolean;
+};
+/**
+ * 孩子看的正文从哪来:`result.result` 只是这轮**最后一段**顶层文本——老师写完板书再用一次工具、再补一句,
+ * 板书和「## 记账」段就没了。所以正文 = 这轮里**带围栏(卡)或带 H2 固定段的顶层文本段** + **最后一段**(顺序不变,重复不算两次);
+ * 中间那些「我先看看账本」之类没卡没段的话不进。子代理的话本来就不在顶层。
+ */
+export declare function kidSource(t: Transcript): string | null;
+/** opts.live = 实时的一轮:解析器不补提问卡(src/board/parse.ts) */
+export declare function deriveKidView(t: Transcript, policy: {
+    replyMaxChars: number;
+}, opts?: {
+    live?: boolean;
+}): KidView;
+/** 孩子端的一条:自己问的话(别人问的不显示)+ 老师给孩子的话 + 配音;出错的运行什么都不出现(问句还在) */
+export interface KidMessage {
+    job: string;
+    /** 话题 id(话题第一条的 job) */
+    thread: string;
+    at: string;
+    /** 孩子自己说的;系统发的不给孩子看,为 null */
+    question: string | null;
+    /** 老师给孩子的话;还在跑或这轮没有 = null */
+    reply: string | null;
+    /** 老师还在想 */
+    pending: boolean;
+    /** 本次运行新增的产物 id */
+    artifacts: string[];
+    /** 板书节(卡 + 讲稿;答案等秘密已剥;配音在讲稿句上) */
+    section?: BoardSection | null;
+    /** 孩子这条带的作业照片(相对 workspace 根;页面经 /api/kid/image?p= 取);只在孩子自己的问句上 */
+    photos?: string[];
+    /** 这条是看完小课堂后的第一条:哪份课包、课名、画过的几处(节前的小课堂卡与画的卡从这里画);again = 再看一遍又画的那条,节前只画画的卡 */
+    lecture?: KidLecture;
+    /** 孩子从左栏的纸交的画:节前一张孩子的画卡 */
+    drawing?: KidDrawing;
+    /** 孩子的话怎么上板:交卡不写;首页按钮发的(正文就是按钮上的字)不写,从按钮进来后孩子自己说的照写 */
+    action?: 'submit';
+    fromHome?: true;
+    /** 这一轮是实时的:讲稿不配音、嘴照念;不出卡的一轮板上留讲稿的字,还在跑时有句就出节 */
+    live?: true;
+}
+/**
+ * 对话索引 → 孩子端条目(的机械过滤在服务端做):不带 result / error / 费用 / 家长尾巴;
+ * 卡上的答案剥掉,孩子自己做的状态(states)与已生成的资产(assets,都从 .cards/ 读)并到卡上。出错的运行:没有 question 的直接不出现;有 question 的只留问句(老师头像不灰,下一条照常)。
+ */
+export declare function kidConversation(index: {
+    messages: readonly ConversationMessage[];
+}, states?: CardStates, assets?: CardAssets): KidMessage[];
+/**
+ * 家长板书页的一条:形状同 KidMessage,家长多看到的都是可选字段;
+ * `section` **不剥答案**;`question` 不管谁发的都给;记账 / 整理记忆那两种轮也在(旁注写「已记进日记」「整理了记忆」)。
+ */
+export interface ParentMessage extends KidMessage {
+    from: ConversationMessage['from'];
+    via?: ConversationMessage['via'];
+    action?: ConversationMessage['action'];
+    /** 这条带给老师的卡(上一轮之后孩子改过状态的):「孩子在板书上做的」;took = 在弹窗里想了多久(毫秒,没改过 = null)、改过几次(有实录才有,app.ts parentDay 挂上) */
+    cards?: (NonNullable<ConversationMessage['cards']>[number] & {
+        took?: {
+            think: number | null;
+            changes: number;
+        };
+    })[];
+    parentText?: string;
+    remembered?: string[];
+    warnings?: string[];
+    /** 不 ok 时的原因;孩子端什么都不出现,家长页出一行 */
+    error?: string;
+    bookkeep?: ConversationMessage['bookkeep'];
+    tidy?: true;
+    /** 家长端多看到看的情况:看了多久、看完没、停过几次 */
+    lectureWatch?: Pick<NonNullable<ConversationMessage['lecture']>, 'watchedMs' | 'finished' | 'pauses'>;
+}
+/** 对话索引 → 家长板书页条目:和 kidConversation 同一个循环,差集恰好是 ParentMessage 里多出的字段与「答案不剥」 */
+export declare function parentConversation(index: {
+    messages: readonly ConversationMessage[];
+}, states?: CardStates, assets?: CardAssets): ParentMessage[];
+export interface KidThread {
+    thread: string;
+    /** 话题第一条的时间 */
+    at: string;
+    /** 话题名:孩子的第一句话截 20 字;没有孩子的话 → 「老师主动说的」 */
+    title: string;
+    /** 老师讲了几节 */
+    sections: number;
+    /** 一共几张卡 */
+    cards: number;
+}
+/**
+ * 「以前的」列表:一天的孩子端条目按话题分组。一句孩子的话都没有的话题不列;还在跑的、出错的轮不算节。
+ */
+export declare function kidThreads(messages: readonly KidMessage[]): KidThread[];
+/**
+ * 今天交给老师过的卡(`<job>/<n>`):交答案那条的 focus.card。交过的卡锁住——不能改、不能再交(2026-10-21,Jack:
+ * 孩子改了交过的卡的答案又交一次,老师再答一遍,孩子糊涂)。
+ */
+export declare function submittedCards(index: {
+    messages: readonly ConversationMessage[];
+}): Set<string>;

package/dist/runtime/kid-view.js

@@ -0,0 +1,157 @@
+/**
+ * 孩子视图(2026-09-10 改板书):最终文本剥掉「记账」段后,正文就是板书——
+ * 普通段落是讲稿(一行一句),围栏是卡(src/board/parse.ts 解析);kidText = 讲稿各句拼起来(家长视图的「孩子看到」摘要),
+ * 每句按 replyMaxChars 截;第一个 H2 起是给家长的尾巴(parentText),孩子看不到。出错什么都不出现。机械规则,不靠模型判断。
+ * 正文取自 kidSource:带卡 / 带固定段的顶层文本段 + 最后一段(老师板书之后又用了工具也不丢)。
+ */
+import { stripSecrets } from "../board/cards/index.js";
+import {} from "../schema/index.js";
+import { parseBoard } from "../board/parse.js";
+import { threads } from "../schema/index.js";
+import { parseSections } from "../board/sections.js";
+const SENTENCE_END = new Set(['。', '!', '!', '?', '?', ';', ';', '\n']);
+/** 按码点数截断;能在句末断就在句末断(不加省略号),否则硬截加 … */
+export function truncateReply(text, max) {
+    const cps = Array.from(text);
+    if (cps.length <= max)
+        return { text, truncated: false };
+    let cut = -1;
+    for (let i = Math.min(max, cps.length) - 1; i >= Math.floor(max * 0.4); i--) {
+        if (SENTENCE_END.has(cps[i])) {
+            cut = i + 1;
+            break;
+        }
+    }
+    if (cut > 0)
+        return { text: cps.slice(0, cut).join('').trim(), truncated: true };
+    return { text: `${cps.slice(0, max).join('').trim()}…`, truncated: true };
+}
+const none = (ok, bookkeeping = null) => ({ kidText: null, truncated: false, bookkeeping, memory: [], ok, section: null, warnings: [], parentText: '' });
+const FENCE_OR_H2 = /^\s*(?:```|~~~|## )/m;
+/**
+ * 孩子看的正文从哪来:`result.result` 只是这轮**最后一段**顶层文本——老师写完板书再用一次工具、再补一句,
+ * 板书和「## 记账」段就没了。所以正文 = 这轮里**带围栏(卡)或带 H2 固定段的顶层文本段** + **最后一段**(顺序不变,重复不算两次);
+ * 中间那些「我先看看账本」之类没卡没段的话不进。子代理的话本来就不在顶层。
+ */
+export function kidSource(t) {
+    if (!t.final?.text)
+        return null;
+    const last = t.final.text.trim();
+    const blocks = t.items.filter((i) => i.kind === 'text' && !i.sub).map((i) => i.text.trim());
+    // 已经拼在最后一段里的(工具调用写成正文那次的正文,runner 接在 resume 那次前面)不再算一次
+    const kept = blocks.filter((b) => !last.includes(b) && FENCE_OR_H2.test(b));
+    return [...kept, last].join('\n\n');
+}
+/** opts.live = 实时的一轮:解析器不补提问卡(src/board/parse.ts) */
+export function deriveKidView(t, policy, opts = {}) {
+    if (!t.final)
+        return none(false);
+    if (!t.final.ok || !t.final.text)
+        return none(t.final.ok);
+    const { body, bookkeeping, memory } = parseSections(kidSource(t) ?? t.final.text);
+    const board = parseBoard(body, { live: opts.live });
+    const { cards, lines } = board.section;
+    if (!cards.length && !lines.length)
+        return { ...none(true, bookkeeping), memory, warnings: board.warnings.map((w) => w.text), parentText: board.tail };
+    let truncated = false;
+    const cut = lines.map((l) => {
+        const r = truncateReply(l.text, policy.replyMaxChars);
+        truncated = truncated || r.truncated;
+        return { ...l, text: r.text };
+    });
+    const section = { ...board.section, lines: cut };
+    const kidText = cut.map((l) => l.text).join('\n');
+    return { kidText: kidText || null, truncated, bookkeeping, memory, ok: true, section, warnings: board.warnings.map((w) => w.text), parentText: board.tail };
+}
+/** 索引里的小课堂 → 孩子端(画不带那段话)/ 家长端(带) */
+/** 孩子的画卡要的:图、几笔、画了多久 */
+function drawingView(d) {
+    return { image: d.image, strokes: d.strokes, ...(d.ms !== undefined ? { ms: d.ms } : {}) };
+}
+function lectureView(l, parent) {
+    return { bundle: l.bundle, title: l.title, ...(l.again ? { again: true } : {}), ...(l.video ? { video: true } : {}), ...(l.marks?.length ? { marks: l.marks.map((m) => ({ atMs: m.atMs, svgMs: m.svgMs, strokes: m.strokes, ...(m.image ? { image: m.image } : {}), ...(parent && m.text ? { text: m.text } : {}) })) } : {}) };
+}
+/** 孩子做的状态(states)与已生成的资产(assets,都从 .cards/ 读)并到这轮的卡上;都没有就原样 */
+function cardsWithState(m, states, assets, submitted = new Set()) {
+    const per = states[m.job];
+    const files = assets[m.job];
+    const done = [...submitted].some((id) => id.startsWith(`${m.job}/`));
+    return m.section && (per || files || done) ? { ...m.section, cards: m.section.cards.map((c, n) => ({ ...c, ...(submitted.has(`${m.job}/${n}`) ? { submitted: true } : {}), ...(per?.[n] ? { state: per[n].state } : {}), ...(files?.[n]?.length ? { assets: files[n] } : {}) })) } : m.section;
+}
+/**
+ * 对话索引 → 孩子端条目(的机械过滤在服务端做):不带 result / error / 费用 / 家长尾巴;
+ * 卡上的答案剥掉,孩子自己做的状态(states)与已生成的资产(assets,都从 .cards/ 读)并到卡上。出错的运行:没有 question 的直接不出现;有 question 的只留问句(老师头像不灰,下一条照常)。
+ */
+export function kidConversation(index, states = {}, assets = {}) {
+    const out = [];
+    const ths = threads(index.messages);
+    const submitted = submittedCards(index);
+    for (const [i, m] of index.messages.entries()) {
+        // 记账那轮是家长晚上起的任务,老师回的「记好了」不是给孩子的话
+        if (m.bookkeep || m.tidy)
+            continue;
+        const question = m.from === 'kid' ? m.text : null;
+        const reply = m.result === 'ok' ? (m.kidText ?? null) : null;
+        const pending = m.result === 'running';
+        if (question === null && reply === null && !pending)
+            continue;
+        const withState = cardsWithState(m, states, assets, submitted);
+        const section = m.result === 'ok' && withState ? stripSecrets(withState) : undefined;
+        out.push({ job: m.job, thread: ths[i], at: m.at, question, reply, pending, artifacts: reply ? [...m.artifacts] : [], ...(section ? { section } : {}), ...(question !== null && m.photos?.length ? { photos: [...m.photos] } : {}), ...(question !== null && m.drawing ? { drawing: drawingView(m.drawing) } : {}), ...(m.lecture ? { lecture: lectureView(m.lecture, false) } : {}), ...(question !== null && m.action ? { action: m.action } : {}), ...(question !== null && m.via && question.trim() === m.via.label.trim() ? { fromHome: true } : {}), ...(m.live ? { live: true } : {}) });
+    }
+    return out;
+}
+/** 对话索引 → 家长板书页条目:和 kidConversation 同一个循环,差集恰好是 ParentMessage 里多出的字段与「答案不剥」 */
+export function parentConversation(index, states = {}, assets = {}) {
+    const out = [];
+    const ths = threads(index.messages);
+    for (const [i, m] of index.messages.entries()) {
+        const reply = m.result === 'ok' ? (m.kidText ?? null) : null;
+        const pending = m.result === 'running';
+        const withState = cardsWithState(m, states, assets);
+        const section = m.result === 'ok' && withState ? withState : undefined;
+        out.push({
+            job: m.job, thread: ths[i], at: m.at, from: m.from, question: m.text, reply, pending, artifacts: reply ? [...m.artifacts] : [],
+            ...(section ? { section } : {}),
+            ...(m.photos?.length ? { photos: [...m.photos] } : {}),
+            ...(m.drawing ? { drawing: drawingView(m.drawing) } : {}),
+            ...(m.via ? { via: m.via } : {}),
+            ...(m.action ? { action: m.action } : {}),
+            ...(m.cards?.length ? { cards: m.cards } : {}),
+            ...(m.parentText ? { parentText: m.parentText } : {}),
+            ...(m.remembered?.length ? { remembered: m.remembered } : {}),
+            ...(m.warnings?.length ? { warnings: m.warnings } : {}),
+            ...(m.result === 'error' ? { error: m.error ?? '没成' } : {}),
+            ...(m.bookkeep ? { bookkeep: m.bookkeep } : {}),
+            ...(m.tidy ? { tidy: true } : {}),
+            ...(m.lecture ? { lecture: lectureView(m.lecture, true), lectureWatch: { watchedMs: m.lecture.watchedMs, finished: m.lecture.finished, pauses: m.lecture.pauses } } : {}),
+        });
+    }
+    return out;
+}
+/**
+ * 「以前的」列表:一天的孩子端条目按话题分组。一句孩子的话都没有的话题不列;还在跑的、出错的轮不算节。
+ */
+export function kidThreads(messages) {
+    const by = new Map();
+    for (const m of messages) {
+        const t = by.get(m.thread) ?? { thread: m.thread, at: m.at, title: '', sections: 0, cards: 0, asked: false };
+        if (m.question && !t.asked) {
+            t.asked = true;
+            t.title = m.question.trim().slice(0, 20);
+        }
+        if (m.reply !== null || (m.section && !m.pending)) {
+            t.sections++;
+            t.cards += m.section?.cards.length ?? 0;
+        }
+        by.set(m.thread, t);
+    }
+    return [...by.values()].filter((t) => t.asked).map(({ asked: _a, ...t }) => t);
+}
+/**
+ * 今天交给老师过的卡(`<job>/<n>`):交答案那条的 focus.card。交过的卡锁住——不能改、不能再交(2026-10-21,Jack:
+ * 孩子改了交过的卡的答案又交一次,老师再答一遍,孩子糊涂)。
+ */
+export function submittedCards(index) {
+    return new Set(index.messages.flatMap((m) => (m.action === 'submit' && m.focus?.card ? [m.focus.card] : [])));
+}

package/dist/runtime/lecture.d.ts

@@ -0,0 +1,86 @@
+import { type LectureClock, type LectureMark, type LecturePicture } from '../board/lecture.ts';
+import type { ContextPack } from '../schema/index.ts';
+import type { BoardSection } from '../board/presentation.ts';
+export interface Lecture {
+    id: string;
+    title: string;
+    problem: string;
+    /** 课包的科目(scene.json 的 subject);没写 = null */
+    subject: string | null;
+    clock: LectureClock;
+    /** 画面的语义(课包的 groups、blocks 与 build 时量好的 bounds):画的地方盖着什么靠它说;视频没有 */
+    picture: LecturePicture;
+    /** 视频(lectures/<id>/video.mp4);false = 课包 */
+    video: boolean;
+    /** 课包烤过(bake.json 和画面对得上):孩子端不用 excalidraw 现画,缩略图服务端出 */
+    baked?: boolean;
+}
+/** 读小课堂要的目录:课包,与视频(没给就只认课包) */
+export interface LectureDirs {
+    dirs: {
+        bundles: string;
+        lectures?: string;
+    };
+}
+export declare function readLecture(ws: LectureDirs, id: string): Promise<Lecture | null>;
+/** 读一份小课堂:课包先,再视频;读不出来的,problems 说为什么(首页检查用) */
+export declare function inspectLecture(ws: LectureDirs, id: string): Promise<{
+    lecture: Lecture | null;
+    problems: string[];
+}>;
+/** 孩子看完带来的:看了多久、看完没、停过几次;again = 问过以后「再看一遍」又画了(这条只为带画的) */
+export interface LectureWatch {
+    watchedMs: number;
+    finished: boolean;
+    pauses: number;
+    again?: boolean;
+}
+/** 孩子带来的一处画;一处一张截好的图(captures/ 里,画面叠上这一刻的几笔;截不出来就没有) */
+export interface IncomingMark extends LectureMark {
+    image?: string;
+    /** 画的地方盖着什么,写死的(cotutor activity eval 的例子「画:」):不按笔画现算,时刻与那句讲稿照接 */
+    hit?: string;
+    /** 画下去的那一刻:离这条消息发出去多少毫秒(≤ 0;录像用) */
+    t?: number;
+}
+/** 落盘的一处画:时刻、SVG 停在哪(画缩略图用,毫秒)、几笔(课包坐标;视频是视频自己的像素坐标)、给老师的那段话(读不出来时没有)、截图 */
+export interface StoredMark extends IncomingMark {
+    svgMs: number;
+    text?: string;
+}
+/**
+ * 孩子带来的画 → 落盘的样子:那段话 = 时刻与那时在讲哪句 + 截图是上下文包 photos 的第几张(photoBase = 前面已经有几张孩子自己拍的)
+ * + 课包的再说画的地方盖着什么(按课包现算,用课里的叫法)。读不出来就只留时刻与笔画
+ */
+export declare function storedMarks(l: Lecture | null, marks: readonly IncomingMark[], photoBase?: number): StoredMark[];
+/** 上下文包 lecture: 段:标题、来源、课长、每句起点与原话、看的情况、画过的几处 */
+export declare function lecturePack(l: Lecture, w: LectureWatch, marks?: readonly StoredMark[]): NonNullable<ContextPack['lecture']>;
+/**
+ * 小课堂卡(cards/lecture)下发时补的快照:课名、真放的起止(对齐段界)、末帧停在 SVG 的哪一刻、能不能放。
+ * 课包每次现读(家长重做了课包,下一次下发就跟上);读不出来或起止对不上 → ready: false,讲稿 [[play]] 不停。
+ */
+export declare function enrichLectures(ws: LectureDirs, section: BoardSection): Promise<BoardSection>;
+/**
+ * 课包没烤过(或画面改过没重烤):起一次 cotutor chalk bake(同一份课包同时只烤一次;要本机的 Chrome,src/app/cli/chalk/)。
+ * 烤好 true;烤不了(没浏览器、课包坏了、超时)false,不抛。
+ */
+export declare function ensureBaked(bundlesDir: string, id: string): Promise<boolean>;
+/**
+ * 孩子端要用到的课包(首页的小课堂、lecture 卡)没烤过:后台烤一次,不等(下一次下发就是烤好的)。
+ * 一个服务进程里每份课包只看一次;烤不了照样放(孩子端在浏览器里现烤)。
+ */
+export declare function bakeSoon(bundlesDir: string, id: string): void;
+/** 一节板书里 lecture 卡用到的课包,没烤过的后台烤 */
+export declare function bakeSectionSoon(bundlesDir: string, section: BoardSection): void;
+/**
+ * 课包在 SVG 时刻 svgMs 的画面(画的卡、lecture 卡的缩略图,播放器截图的底):用烤好的画面(bake.json)在服务端现画成一张 SVG,
+ * 有画就叠上那几笔(课包坐标,加上导出时的平移)。没烤过、画面改过没重烤:给了 bake(路由给 ensureBaked)就先烤再画,烤不了 → null。
+ * 背景图内嵌成 data URI:SVG 当 <img> 用时不去取外面的文件。
+ */
+export declare function lectureFrameSvg(ws: Pick<LectureDirs, 'dirs'>, id: string, svgMs: number, ink?: readonly (readonly [number, number][])[], opts?: {
+    bake?: (bundlesDir: string, id: string) => Promise<boolean>;
+}): Promise<string | null>;
+/** frame.svg 的 svg 参数:SVG 时刻(毫秒);`end` = 最后一帧(小课堂卡的缩略图);认不出来 = 0 */
+export declare function parseSvgMs(s: string | null): number;
+/** frame.svg 的 ring 参数:一笔「x,y;x,y;…」,笔与笔之间「~」(课包坐标,取整;一共最多 MARK_MAX_POINTS 个点);认不出来 = 没有 */
+export declare function parseRing(s: string | null): [number, number][][];

package/dist/runtime/lecture.js

@@ -0,0 +1,237 @@
+/**
+ * 小课堂读盘的那一半:从 bundles/<id>/ 读课包,或从 lectures/<id>/ 读视频(lecture.md + video.mp4,第 4 步),拼时钟(src/board/lecture.ts),
+ * 给首页按钮的标题与课长、首页检查、上下文包 lecture: 用。同一个 id 两边都有,课包先。坏了、不在都回 null,不抛;为什么读不出来给首页检查(inspectLecture)。
+ */
+import { spawn } from 'node:child_process';
+import { readFile, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { BUNDLE_ID_RE } from "../board/cards/kind.js";
+import { mp4DurationMs } from "../media/mp4.js";
+import { LECTURE_FILE, LECTURE_VIDEO, MARK_MAX_POINTS, clockLabel, inkHint, lectureAt, lectureClock, lectureLines, lectureRange, markHead, parseLectureDoc, videoClock } from "../board/lecture.js";
+import { bakeMatches, BundleError, elementsAtSvgTime, parseBundle, renderFrameSvg } from "../chalk/index.js";
+export async function readLecture(ws, id) {
+    return (await inspectLecture(ws, id)).lecture;
+}
+/** 读一份小课堂:课包先,再视频;读不出来的,problems 说为什么(首页检查用) */
+export async function inspectLecture(ws, id) {
+    if (!BUNDLE_ID_RE.test(id))
+        return { lecture: null, problems: [`${id} 不是合规的 id(小写字母、数字、连字符)`] };
+    const bundle = await readBundleLecture(ws, id);
+    if (bundle.lecture)
+        return { lecture: bundle.lecture, problems: [] };
+    if (bundle.problem)
+        return { lecture: null, problems: [bundle.problem] };
+    if (!ws.dirs.lectures)
+        return { lecture: null, problems: [`bundles/${id}/ 不在或读不出来(要有 scene.json 与带步的 manifest.json)`] };
+    const dir = join(ws.dirs.lectures, id);
+    const md = await readFile(join(dir, LECTURE_FILE), 'utf8').catch(() => null);
+    const hasVideo = Boolean((await stat(join(dir, LECTURE_VIDEO)).catch(() => null))?.isFile());
+    if (md === null && !hasVideo)
+        return { lecture: null, problems: [`bundles/${id}/ 与 lectures/${id}/ 都没有(课包要有 scene.json 与带步的 manifest.json;视频要有 ${LECTURE_VIDEO} 与 ${LECTURE_FILE})`] };
+    const problems = [];
+    if (!hasVideo)
+        problems.push(`lectures/${id}/ 没有 ${LECTURE_VIDEO}`);
+    if (md === null)
+        problems.push(`lectures/${id}/ 没有 ${LECTURE_FILE}(# 标题,一行一句「分:秒 原话」)`);
+    const doc = parseLectureDoc(md ?? '');
+    if (md !== null)
+        for (const i of doc.issues.filter((x) => x.level === 'fix'))
+            problems.push(`lectures/${id}/${LECTURE_FILE}${i.line ? ` 第 ${i.line} 行` : ''}:${i.text}`);
+    const total = hasVideo ? await mp4DurationMs(join(dir, LECTURE_VIDEO)) : null;
+    if (hasVideo && total === null)
+        problems.push(`lectures/${id}/${LECTURE_VIDEO} 读不出时长(要是 mp4)`);
+    if (total !== null)
+        for (const c of doc.chapters.filter((x) => x.start >= total))
+            problems.push(`lectures/${id}/${LECTURE_FILE} 第 ${c.at} 行:${clockLabel(c.start)} 超过了视频的长度 ${clockLabel(total)}`);
+    if (problems.length || total === null)
+        return { lecture: null, problems };
+    return { lecture: { id, title: doc.title, problem: '', subject: doc.subject, clock: videoClock(doc.chapters, total), picture: {}, video: true }, problems: [] };
+}
+/** 读课包:拼法与校验是 src/chalk 的 parseBundle;读不出来时 problem 说为什么(不在 = 没有 problem,让给视频) */
+async function readBundleLecture(ws, id) {
+    const dir = join(ws.dirs.bundles, id);
+    let sceneJson;
+    let manifestJson;
+    try {
+        [sceneJson, manifestJson] = await Promise.all(['scene.json', 'manifest.json'].map(async (f) => JSON.parse(await readFile(join(dir, f), 'utf8'))));
+    }
+    catch {
+        return { lecture: null };
+    }
+    let bundle;
+    try {
+        bundle = parseBundle(sceneJson, manifestJson);
+    }
+    catch (e) {
+        return { lecture: null, problem: `bundles/${id}/ ${e instanceof BundleError ? e.message : String(e)};用源 TS 重新 cotutor chalk build` };
+    }
+    const { scene, picture } = bundle;
+    if (!scene.steps.length)
+        return { lecture: null, problem: `bundles/${id}/ 的 manifest.json 没有步(小课堂要逐步讲的课包)` };
+    const clock = lectureClock(scene.skeletons, scene.steps);
+    const baked = await readFile(join(dir, 'bake.json'), 'utf8').then((t) => bakeMatches(JSON.parse(t), sceneJson), () => false);
+    return { lecture: { id, title: scene.title, problem: scene.problem, subject: scene.subject ?? null, clock, picture, video: false, baked } };
+}
+/**
+ * 孩子带来的画 → 落盘的样子:那段话 = 时刻与那时在讲哪句 + 截图是上下文包 photos 的第几张(photoBase = 前面已经有几张孩子自己拍的)
+ * + 课包的再说画的地方盖着什么(按课包现算,用课里的叫法)。读不出来就只留时刻与笔画
+ */
+export function storedMarks(l, marks, photoBase = 0) {
+    let k = photoBase;
+    return marks.map((m) => {
+        const shot = m.image ? ++k : null;
+        const base = { atMs: m.atMs, svgMs: l && !l.video ? Math.round(lectureAt(l.clock, m.atMs).svgMs * 10) / 10 : 0, strokes: m.strokes, ...(m.image ? { image: m.image } : {}), ...(m.t !== undefined ? { t: m.t } : {}) };
+        if (!l)
+            return base;
+        const head = markHead(l.clock, m.atMs);
+        if (m.hit !== undefined)
+            return { ...base, text: `${head}${m.hit ? `;${m.hit}` : ''}` };
+        const pic = shot ? `画在截图上(photos 第 ${shot} 张)` : l.video ? '没有截图,看不出画的是什么' : '没有截图';
+        const hint = l.video ? '' : inkHint(l.clock, m, l.picture).text;
+        return { ...base, text: `${head};${pic}${hint ? `;${hint}` : ''}` };
+    });
+}
+/** 上下文包 lecture: 段:标题、来源、课长、每句起点与原话、看的情况、画过的几处 */
+export function lecturePack(l, w, marks = []) {
+    const seen = w.finished ? (w.again ? '又看完了一遍' : '看完了') : `${w.again ? '又看了一遍,' : ''}看到 ${clockLabel(w.watchedMs)}`;
+    const watched = `${seen}${w.pauses ? `,停过 ${w.pauses} 次` : ''}${marks.length ? `,画了 ${marks.length} 处` : ''}`;
+    return { title: l.title, source: `${l.video ? 'video' : 'bundle'} ${l.id}`, length: clockLabel(l.clock.total), lines: lectureLines(l.clock), watched, marks: marks.flatMap((m) => (m.text ? [m.text] : [])) };
+}
+/**
+ * 小课堂卡(cards/lecture)下发时补的快照:课名、真放的起止(对齐段界)、末帧停在 SVG 的哪一刻、能不能放。
+ * 课包每次现读(家长重做了课包,下一次下发就跟上);读不出来或起止对不上 → ready: false,讲稿 [[play]] 不停。
+ */
+export async function enrichLectures(ws, section) {
+    if (!section.cards.some((c) => c.kind === 'lecture'))
+        return section;
+    const seen = new Map();
+    const cards = [];
+    for (const c of section.cards) {
+        const p = c.props;
+        if (c.kind !== 'lecture' || typeof p.bundle !== 'string') {
+            cards.push(c);
+            continue;
+        }
+        if (!seen.has(p.bundle))
+            seen.set(p.bundle, readLecture(ws, p.bundle));
+        const l = await seen.get(p.bundle);
+        const r = l ? lectureRange(l.clock, typeof p.from === 'number' ? p.from : undefined, typeof p.to === 'number' ? p.to : undefined) : null;
+        // 视频没有 SVG:末帧的缩略图页面用 <video> 停在 end 前一点
+        cards.push({ ...c, props: { ...c.props, ...(l ? { title: l.title } : {}), ...(l?.video ? { video: true } : {}), ...(l && r ? { start: r.start, end: r.end, ...(l.video ? {} : { still: Math.round(lectureAt(l.clock, Math.max(r.start, r.end - 1)).svgMs * 10) / 10 }) } : {}), ready: Boolean(l && r) } });
+    }
+    return { ...section, cards };
+}
+const baking = new Map();
+/**
+ * 课包没烤过(或画面改过没重烤):起一次 cotutor chalk bake(同一份课包同时只烤一次;要本机的 Chrome,src/app/cli/chalk/)。
+ * 烤好 true;烤不了(没浏览器、课包坏了、超时)false,不抛。
+ */
+export function ensureBaked(bundlesDir, id) {
+    const key = join(bundlesDir, id);
+    let p = baking.get(key);
+    if (!p) {
+        p = new Promise((resolve) => {
+            const child = spawn(process.execPath, [COTUTOR_BIN, 'chalk', 'bake', id, '--bundles', bundlesDir, '--json'], { stdio: 'ignore' });
+            const timer = setTimeout(() => child.kill(), BAKE_TIMEOUT_MS);
+            child.on('error', () => { clearTimeout(timer); resolve(false); });
+            child.on('exit', (code) => { clearTimeout(timer); resolve(code === 0); });
+        }).finally(() => baking.delete(key));
+        baking.set(key, p);
+    }
+    return p;
+}
+const BAKE_TIMEOUT_MS = 120_000;
+/** 本包的命令入口(仓库里与 npm 装的都是包根 bin/cotutor.js;src/runtime 与 dist/runtime 到包根同样两级) */
+const COTUTOR_BIN = fileURLToPath(new URL('../../bin/cotutor.js', import.meta.url));
+const tried = new Set();
+/**
+ * 孩子端要用到的课包(首页的小课堂、lecture 卡)没烤过:后台烤一次,不等(下一次下发就是烤好的)。
+ * 一个服务进程里每份课包只看一次;烤不了照样放(孩子端在浏览器里现烤)。
+ */
+export function bakeSoon(bundlesDir, id) {
+    const key = join(bundlesDir, id);
+    if (tried.has(key) || !BUNDLE_ID_RE.test(id))
+        return;
+    tried.add(key);
+    void (async () => {
+        const [scene, baked] = await Promise.all(['scene.json', 'bake.json'].map((f) => readFile(join(key, f), 'utf8').then((t) => JSON.parse(t), () => null)));
+        if (scene && !bakeMatches(baked, scene))
+            await ensureBaked(bundlesDir, id);
+    })().catch(() => { });
+}
+/** 一节板书里 lecture 卡用到的课包,没烤过的后台烤 */
+export function bakeSectionSoon(bundlesDir, section) {
+    for (const c of section.cards)
+        if (c.kind === 'lecture' && typeof c.props.bundle === 'string' && !c.props.video)
+            bakeSoon(bundlesDir, c.props.bundle);
+}
+/**
+ * 课包在 SVG 时刻 svgMs 的画面(画的卡、lecture 卡的缩略图,播放器截图的底):用烤好的画面(bake.json)在服务端现画成一张 SVG,
+ * 有画就叠上那几笔(课包坐标,加上导出时的平移)。没烤过、画面改过没重烤:给了 bake(路由给 ensureBaked)就先烤再画,烤不了 → null。
+ * 背景图内嵌成 data URI:SVG 当 <img> 用时不去取外面的文件。
+ */
+export async function lectureFrameSvg(ws, id, svgMs, ink = [], opts = {}) {
+    if (!BUNDLE_ID_RE.test(id))
+        return null;
+    const dir = join(ws.dirs.bundles, id);
+    try {
+        const read = () => Promise.all(['scene.json', 'manifest.json', 'bake.json'].map((f) => readFile(join(dir, f), 'utf8').catch(() => '')));
+        const [sceneRaw, manifestRaw, bakedRaw] = await read();
+        if (!sceneRaw || !manifestRaw)
+            return null;
+        const scene = JSON.parse(sceneRaw);
+        const parse = (raw) => { try {
+            return JSON.parse(raw);
+        }
+        catch {
+            return null;
+        } };
+        let baked = parse(bakedRaw);
+        if (!bakeMatches(baked, scene) && opts.bake && (await opts.bake(ws.dirs.bundles, id)))
+            baked = parse(await readFile(join(dir, 'bake.json'), 'utf8').catch(() => ''));
+        if (!bakeMatches(baked, scene))
+            return null;
+        const { scene: parsed } = parseBundle(scene, JSON.parse(manifestRaw));
+        const clock = lectureClock(parsed.skeletons, parsed.steps);
+        const [dx, dy] = baked.offset;
+        const d = ink.filter((st) => st.length >= 2).map((st) => st.map((p, i) => `${i ? 'L' : 'M'}${p[0] + dx} ${p[1] + dy}`).join(' ')).join(' ');
+        const overlay = d ? `<path d="${d}" fill="none" stroke="#2f6fd6" stroke-width="3" stroke-linecap="round" stroke-linejoin="round" vector-effect="non-scaling-stroke"/>` : '';
+        // 背景图(换过画板的课每块板一张)内嵌成 data URI;画哪块板、淡没淡由 src/chalk 按那一刻算
+        const hrefs = new Map();
+        for (const b of (baked.boards ?? [baked]).map((x) => x.background)) {
+            if (!b || hrefs.has(b.src))
+                continue;
+            const ext = b.src.split('.').pop()?.toLowerCase() ?? 'png';
+            const mime = ext === 'jpg' || ext === 'jpeg' ? 'image/jpeg' : ext === 'webp' ? 'image/webp' : 'image/png';
+            const data = await readFile(join(dir, b.src)).catch(() => null);
+            if (data)
+                hrefs.set(b.src, `data:${mime};base64,${data.toString('base64')}`);
+        }
+        return renderFrameSvg(baked, { elements: elementsAtSvgTime(clock, svgMs) }, { overlay, assetHref: (src) => hrefs.get(src) });
+    }
+    catch {
+        return null;
+    }
+}
+/** frame.svg 的 svg 参数:SVG 时刻(毫秒);`end` = 最后一帧(小课堂卡的缩略图);认不出来 = 0 */
+export function parseSvgMs(s) {
+    return s === 'end' ? Infinity : Number(s) || 0;
+}
+/** frame.svg 的 ring 参数:一笔「x,y;x,y;…」,笔与笔之间「~」(课包坐标,取整;一共最多 MARK_MAX_POINTS 个点);认不出来 = 没有 */
+export function parseRing(s) {
+    if (!s)
+        return [];
+    let left = MARK_MAX_POINTS;
+    const strokes = [];
+    for (const one of s.split('~')) {
+        if (left <= 0)
+            break;
+        const pts = one.split(';').slice(0, left).map((p) => p.split(',').map(Number));
+        if (!pts.every((p) => p.length === 2 && p.every((x) => Number.isFinite(x) && Math.abs(x) < 1e5)))
+            return [];
+        left -= pts.length;
+        strokes.push(pts);
+    }
+    return strokes;
+}