cotutor 0.1.0 → 0.3.0

package/dist/board/parse.js

@@ -0,0 +1,330 @@
+/**
+ * 板书解析器:老师的回复正文(已剥掉「记账」段)→ 一节 BoardSection。
+ * 三条规则(见 docs/卡片协议.md):围栏 = 卡(标签第一个词是 kind),普通行 = 讲稿一句,第一个 H2 起是给家长的尾巴。
+ * 讲稿句里 [词] 是标注(落到第一张含这个词的卡,整节找,卡在前在后都行),[[名 参数]] 是对上一张卡的动作(cue)。
+ * partial 模式给流式用:没闭合的围栏和没换行结束的最后一行压着不算,下次整段重解析自然补上。
+ * 永不抛错:围栏没闭合当到文末,卡解析不出退成文字卡并记一句 warning。
+ * spans 是「这张卡 / 这句话是原文哪几行」,家长端「看原文」据此在原文旁边标出解析器怎么读的;孩子端的 BoardSection 不带它。
+ */
+import { parseCard } from "./cards/index.js";
+import { anchorMarks, hasState, isAskCard, isHeading, isQuestion, lineTarget, MAX_CARDS_PER_ROW, phrasesIn, plainLine, standsAlone } from "./presentation.js";
+import { parseSections } from "./sections.js";
+const MOD_RE = /^(tint|look|emoji)=(.+)$/i;
+export function splitMods(tag) {
+    const mods = {};
+    const warnings = [];
+    const rest = [];
+    for (const w of tag.trim().split(/\s+/).filter(Boolean)) {
+        if (w.toLowerCase() === 'same') {
+            mods.same = true;
+            continue;
+        }
+        const m = MOD_RE.exec(w);
+        if (!m) {
+            rest.push(w);
+            continue;
+        }
+        const key = m[1].toLowerCase();
+        const v = m[2];
+        if (key === 'emoji' && (Array.from(v).length > 2 || /[A-Za-z0-9]/.test(v))) {
+            warnings.push(`emoji=${v} 不像一个 emoji,不要了`);
+            continue;
+        }
+        mods[key] = v;
+    }
+    return { rest: rest.join(' '), mods, warnings };
+}
+/** 尾巴的末行:掐掉后面的空行,免得「看原文」把末尾空行也染成家长段 */
+function tailTo(lines, from) {
+    let k = lines.length - 1;
+    while (k > from && !lines[k].trim())
+        k--;
+    return k;
+}
+const FENCE_OPEN = /^ {0,3}(`{3,}|~{3,})(.*)$/;
+const H2 = /^##\s+\S/;
+const CUE = /\[\[([^\[\]]+)\]\]/g;
+function fenceClose(line, fence) {
+    const m = /^ {0,3}(`{3,}|~{3,})\s*$/.exec(line);
+    return Boolean(m && m[1][0] === fence[0] && m[1].length >= fence.length);
+}
+/**
+ * 写成正文的工具调用:这轮没有那个工具时,qwen 照它自己的格式把调用写进正文——`<tool_call>` 独占一行起、`</tool_call>` 止
+ * (中间是 `<function=Read>` `<parameter=…>` 几行或一行 JSON),也见过不带外层的 `<function=名>` … `</function>`。
+ * 整块不是讲稿:板上不出、嘴不念(10-21 Ray 交画那轮,这 7 行在板上、嘴念了 25 秒)
+ */
+const TOOL_OPEN = /^\s*<(tool_call|function=[^>\s]+)>\s*$/;
+const toolClose = (open) => (open === 'tool_call' ? /^\s*<\/tool_call>\s*$/ : /^\s*<\/function>\s*$/);
+/** 块里调的是哪个工具:`<function=名>` 或 JSON 的 "name" */
+function toolName(block) {
+    for (const l of block) {
+        const m = /<function=([^>\s]+)>/.exec(l) ?? /"name"\s*:\s*"([^"]+)"/.exec(l);
+        if (m)
+            return m[1];
+    }
+    return '?';
+}
+/** 讲稿一行的清洗:去掉老师不该写但常写的标题号、列表号、引用号、粗体号;整行的 HTML 注释不算话 */
+export function cleanSpeech(line) {
+    const t = line.trim();
+    if (/^<!--.*-->$/.test(t))
+        return '';
+    return t
+        .replace(/^#{1,6}\s+/, '')
+        .replace(/^(?:[-*+]|\d+[.)])\s+/, '')
+        .replace(/^>\s*/, '')
+        .replace(/\*\*/g, '')
+        .trim();
+}
+/**
+ * 热身的记号:不锚卡,记在这句上。[[echo 词]] 跟我说、[[say 词]] 你先说(念完等孩子说「词」),[[call]] 念完进打电话。
+ * echo 没写词就取这句里的英文;一句写了几个,算最后一个
+ */
+const LINE_MARKS = new Set(['echo', 'say', 'call']);
+const englishIn = (text) => (text.match(/[A-Za-z][A-Za-z']*/g) ?? []).join(' ');
+/** 句子锚到上一张卡;小节标题行不算卡,跳过它 */
+function lastCard(cards) {
+    for (let k = cards.length - 1; k >= 0; k--)
+        if (!isHeading(cards[k]))
+            return k;
+    return null;
+}
+function rawLine(line, cards, at) {
+    const anchor = lastCard(cards);
+    const cues = [];
+    let mark = null;
+    const text = line
+        .replace(CUE, (_, inner) => {
+        const [name, ...rest] = inner.trim().split(/\s+/);
+        const n = (name ?? '').toLowerCase();
+        if (LINE_MARKS.has(n))
+            mark = { name: n, arg: rest.join(' ') };
+        else if (name && anchor !== null)
+            cues.push({ card: anchor, name: n, ...(rest.length ? { arg: rest.join(' ') } : {}) });
+        return '';
+    })
+        .replace(/\s{2,}/g, ' ')
+        .trim();
+    const m = mark;
+    if (!m)
+        return { text, anchor, cues, line: at };
+    if (m.name === 'call')
+        return { text, anchor, cues, line: at, call: true };
+    const word = m.arg || (m.name === 'echo' ? englishIn(text) : '');
+    return { text, anchor, cues, line: at, echo: { word, ...(m.name === 'say' ? { say: true } : {}) } };
+}
+/** 一句讲稿交给嘴时要带的:[[play]] 到小课堂卡、热身的 echo / say、call(runner 的 line 事件、mock 的假嘴都用它) */
+export function lineFlags(line, cards) {
+    return { ...(playsLecture(line, cards) ? { play: true } : {}), ...(line.echo ? { echo: line.echo } : {}), ...(line.call ? { call: true } : {}) };
+}
+/** 这句的 [[play]] 锚着小课堂卡:念完放卡上那一段(实时时服务端在这句之后等孩子端放完再交讲稿,src/runtime/delivery/queue.ts) */
+export function playsLecture(line, cards) {
+    return (line.cues ?? []).some((c) => c.name === 'play' && cards[c.card]?.kind === 'lecture');
+}
+export function parseBoard(text, opts = {}) {
+    const partial = opts.partial === true;
+    const all = text.split('\n');
+    const lines = partial && !text.endsWith('\n') ? all.slice(0, -1) : all;
+    const cards = [];
+    const cardSpans = [];
+    /** 每张卡围栏行上的排版修饰词(与 cards 同序;没写就是空对象) */
+    const mods = [];
+    const raws = [];
+    const warnings = [];
+    const toolCalls = [];
+    let tail = null;
+    let tailFrom = -1;
+    let i = 0;
+    while (i < lines.length) {
+        const line = lines[i];
+        if (tail) {
+            tail.push(line);
+            i++;
+            continue;
+        }
+        const call = TOOL_OPEN.exec(line);
+        if (call) {
+            const close = toolClose(call[1]);
+            let j = i + 1;
+            while (j < lines.length && !close.test(lines[j]))
+                j++;
+            // 和围栏一样:流式时没收尾的块压着,后面的也不出
+            if (j >= lines.length && partial)
+                break;
+            const end = Math.min(j, lines.length - 1);
+            toolCalls.push([i, end]);
+            warnings.push({ text: `老师把工具调用写成了正文(${toolName(lines.slice(i, end + 1))}),不进板书`, line: i });
+            i = end + 1;
+            continue;
+        }
+        const open = FENCE_OPEN.exec(line);
+        if (open) {
+            const fence = open[1];
+            const tag = open[2].trim();
+            const body = [];
+            let j = i + 1;
+            let closed = false;
+            for (; j < lines.length; j++) {
+                if (fenceClose(lines[j], fence)) {
+                    closed = true;
+                    break;
+                }
+                body.push(lines[j]);
+            }
+            if (!closed && partial)
+                break;
+            if (!closed)
+                warnings.push({ text: `围栏没闭合(${tag || '无标签'}),当到文末`, line: i });
+            const sm = splitMods(tag);
+            const r = parseCard(sm.rest, body.join('\n'), opts.place);
+            const look = { ...(sm.mods.tint ? { tint: sm.mods.tint } : {}), ...(sm.mods.look ? { look: sm.mods.look } : {}), ...(sm.mods.emoji ? { emoji: sm.mods.emoji } : {}) };
+            cards.push(Object.keys(look).length && !isHeading(r.card) ? { ...r.card, look } : r.card);
+            mods.push(sm.mods);
+            cardSpans.push([i, closed ? j : Math.max(i, j - 1)]);
+            for (const w of sm.warnings)
+                warnings.push({ text: w, line: i });
+            if (r.warning)
+                warnings.push({ text: r.warning, line: i, ...(r.fallback ? { fallback: true } : {}) });
+            i = closed ? j + 1 : j;
+            continue;
+        }
+        if (H2.test(line)) {
+            tail = [line];
+            tailFrom = i;
+            i++;
+            continue;
+        }
+        const speech = cleanSpeech(line);
+        if (speech)
+            raws.push(rawLine(speech, cards, i));
+        i++;
+    }
+    // 标注整节找(老师把卡写在句子后面也认),所以卡收齐了再落
+    const kept = raws.filter((r) => r.text);
+    const out = kept.map((r) => {
+        const marks = anchorMarks(cards, phrasesIn(r.text));
+        const plain = plainLine(r.text);
+        return { text: plain, audio: null, marks, ask: isQuestion(plain), anchor: r.anchor, cues: r.cues, ...(r.echo ? { echo: r.echo } : {}), ...(r.call ? { call: true } : {}) };
+    });
+    // 排版:有卡写了 same 才排行(明写的并排,其余孩子端按宽度排);接不上(上一行满了、有独占一行的卡)就另起一行并提醒。提问卡(下面补的)不在行里,rowsFor 认前缀
+    let layout;
+    if (mods.some((m) => m.same)) {
+        const rows = [];
+        cards.forEach((c, n) => {
+            const last = rows[rows.length - 1];
+            const join = mods[n].same && last !== undefined && last.length < MAX_CARDS_PER_ROW && !standsAlone(c) && !last.some((i) => standsAlone(cards[i]));
+            if (mods[n].same && !join)
+                warnings.push({ text: `卡 ${n + 1} 写了 same,接不上上一行(${last === undefined ? '它是第一张' : last.length >= MAX_CARDS_PER_ROW ? `上一行已有 ${MAX_CARDS_PER_ROW} 张` : '有独占一行的卡'}),另起一行`, line: cardSpans[n][0] });
+            if (join)
+                last.push(n);
+            else
+                rows.push([n]);
+        });
+        layout = { for: opts.device ?? 'tablet-landscape', rows };
+    }
+    // 提问卡(2026-09-21):末句问句是孩子要答的那句,念完不能只剩字幕——没配能答的卡(choice / fill / canvas)就在节尾补一张文字卡写着这句。
+    // 末句的锚点不动(还在它讲的那张卡的拍里);提问卡自己一拍、没有讲稿。
+    // 老师还在写(partial)时不补:这时的末句不一定是最后一句。首页没有讲稿,不管;实时不补(板上放什么由脑定)
+    const lastLine = out[out.length - 1];
+    if (!partial && !opts.live && (opts.place ?? 'board') === 'board' && lastLine?.ask && !lastLine.cues.length && !lastLine.echo && !lastLine.call) {
+        const t = lineTarget(lastLine);
+        // 拍给我看卡也算能答:孩子拍来的照片进它的答案栏(board/presentation.ts 的 askCard)
+        const answerable = (c) => Boolean(c && (hasState(c) || c.kind === 'photo'));
+        if (!cards.some((c) => c.kind === 'photo') && !answerable(t === null ? undefined : cards[t]) && !answerable(cards[cards.length - 1])) {
+            cards.push({ kind: 'text', props: { text: lastLine.text, ask: true } });
+            cardSpans.push([kept[kept.length - 1].line, kept[kept.length - 1].line]);
+        }
+    }
+    return {
+        section: { cards, lines: out, ...(partial ? { partial: true } : {}), ...(layout ? { layout } : {}) },
+        warnings,
+        tail: tail ? tail.join('\n').trim() : '',
+        spans: {
+            cards: cardSpans,
+            lines: kept.map((r) => [r.line, r.line]),
+            tail: tail ? [tailFrom, tailTo(lines, tailFrom)] : null,
+            toolCalls,
+        },
+    };
+}
+/** 回复停在写成正文的工具调用上(后面只剩空行):老师在等工具的结果,这一轮其实没写完(runner 据此 resume 一次) */
+export function endsWithToolCall(text) {
+    const { spans } = parseBoard(text);
+    const last = spans.toolCalls[spans.toolCalls.length - 1];
+    return Boolean(last) && text.split('\n').slice(last[1] + 1).every((l) => !l.trim());
+}
+const SECTION_HEAD = /^##\s+(.+?)\s*$/;
+/**
+ * 家长端「看原文」用:把老师原文的每一行标上解析器怎么读的。
+ * 不另写一套解析——真跑 parseSections + parseBoard,再把它们的行号映回原文,所以永远不会和真解析漂开。
+ */
+export function annotateSource(text, opts = {}) {
+    const src = text.split('\n');
+    const { body, lineMap } = parseSections(text);
+    const board = parseBoard(body, opts);
+    const rows = src.map((t, line) => ({ line, text: t, role: t.trim() ? 'drop' : 'blank' }));
+    // 固定段吃掉的行:不在 lineMap 里的非空行,标题从上面最近的那个 H2 取
+    const keptSet = new Set(lineMap);
+    let head = '';
+    for (let i = 0; i < src.length; i++) {
+        const m = SECTION_HEAD.exec(src[i]);
+        if (m)
+            head = m[1];
+        if (keptSet.has(i) || !src[i].trim())
+            continue;
+        rows[i].role = 'section';
+        rows[i].label = head ? `段「${head}」· 不进板书` : '不进板书';
+    }
+    const at = (bodyLine) => lineMap[bodyLine];
+    board.spans.cards.forEach((span, n) => {
+        const card = board.section.cards[n];
+        // 提问卡是解析器补的,原文里没有它的围栏
+        if (isAskCard(card))
+            return;
+        for (let b = span[0]; b <= span[1]; b++) {
+            const i = at(b);
+            if (i === undefined)
+                continue;
+            rows[i].role = 'card';
+            rows[i].index = n;
+            if (b === span[0]) {
+                rows[i].open = true;
+                const style = typeof card.props.style === 'string' ? ` ${card.props.style}` : '';
+                rows[i].label = `卡 ${n + 1} · ${card.kind}${style}`;
+            }
+        }
+    });
+    board.spans.lines.forEach((span, n) => {
+        const i = at(span[0]);
+        if (i === undefined)
+            return;
+        rows[i].role = 'say';
+        rows[i].index = n;
+        const l = board.section.lines[n];
+        const waits = l.ask && n === board.section.lines.length - 1;
+        const asked = waits && board.section.cards.some(isAskCard);
+        rows[i].label = `讲稿 ${n + 1}${waits ? ` · 问句,停下等${asked ? '(补提问卡)' : ''}` : ' · 播'}`;
+    });
+    // 整块照旧是 drop,开头那行点名
+    for (const span of board.spans.toolCalls) {
+        const i = at(span[0]);
+        if (i !== undefined)
+            rows[i].label = '写成正文的工具调用 · 不进板书';
+    }
+    if (board.spans.tail) {
+        for (let b = board.spans.tail[0]; b <= board.spans.tail[1]; b++) {
+            const i = at(b);
+            if (i === undefined)
+                continue;
+            rows[i].role = 'tail';
+            if (b === board.spans.tail[0])
+                rows[i].label = '家长尾巴 · 孩子看不到';
+        }
+    }
+    return {
+        rows,
+        warnings: board.warnings.map((w) => ({ text: w.text, ...(w.line !== undefined && at(w.line) !== undefined ? { line: at(w.line) } : {}) })),
+        section: board.section,
+        tail: board.tail,
+    };
+}

package/dist/board/presentation.d.ts

@@ -0,0 +1,295 @@
+/**
+ * 板书(孩子端老师页)的纯逻辑:卡片 JSON 契约、标注锚点、播放状态机、字幕行与输入条的状态。
+ * 这份文件两处共用:服务端(解析器、测试)与孩子端页面——kid-page.ts 把它剥掉类型内联进 <script>,
+ * 所以**不能有运行时 import、不能碰 DOM、不能用 enum / namespace**(Node 的 stripTypeScriptTypes 只剥类型)。
+ *
+ * 契约的分工(见 docs/卡片协议.md):老师写「段落 = 讲稿,围栏 = 卡」的正文,服务端(src/board/parse.ts + src/board/cards/)解析成
+ * 下面的 BoardSection JSON 放进对话索引;孩子端只认 JSON。卡 = {kind, props},每种卡的 props 契约在 src/board/cards/<kind>.ts;
+ * 这里只知道每种卡「哪些字能被标注、笔是什么样」,不认识的 kind 也有兜底。
+ */
+import type { BoardCard, CardLook, PenName, Device, BoardLayout, BoardMark, BoardCue, BoardLine, BoardSection } from '../schema/board.ts';
+export type { BoardCard, CardLook, PenName, Device, BoardLayout, BoardMark, BoardCue, BoardLine, BoardSection };
+export declare const LINE_PENS: readonly PenName[];
+/**
+ * 拍:一张卡 + 它后面直到下一张卡之前的讲稿句;第一张卡之前的句子是没有卡的一拍。
+ * 不进契约,从卡与句的顺序现算——句子锚到上一张卡(anchor),所以按 anchor 分组。
+ */
+export interface Beat {
+    card: number | null;
+    lines: number[];
+}
+export declare function beatsOf(section: Pick<BoardSection, 'cards' | 'lines'>): Beat[];
+/**
+ * 流式时前几拍就绪了:一拍要「关了」(后面已经有下一张卡,或老师写完了)。讲稿不配音,不等配音。
+ * 返回就绪的拍数(前缀:第 k 拍就绪的前提是前面都就绪)。
+ */
+export declare function readyBeats(section: Pick<BoardSection, 'cards' | 'lines'>, opts: {
+    done: boolean;
+}): number;
+/** 一张卡上所有能被标注的文字;不认识的 kind 拿 props 里所有字符串 */
+export declare function cardTexts(card: BoardCard): string[];
+/**
+ * 词在一段字里的位置,数字与拉丁词按整词算(「5」不落在「25」里、「an」不落在「and」里),中文照子串;没有 → -1。
+ * 标注锚点(anchorMarks)与页面画笔的落点都用它,两处一条规则。
+ */
+export declare function findPhrase(text: string, phrase: string): number;
+/** 讲稿里方括号的词落到哪张卡:第一张含这个词(整词,见 findPhrase)的卡;找不到的词丢掉(只出字幕,不报错) */
+export declare function anchorMarks(cards: readonly BoardCard[], phrases: readonly string[]): BoardMark[];
+/** 讲稿一句里的 [词] → 词列表;顺序保留 */
+export declare function phrasesIn(line: string): string[];
+/** 去掉讲稿一句里的方括号(念的时候不念括号) */
+export declare function plainLine(line: string): string;
+/** 小节标题(text 卡只有一行 `# 标题`):渲染成无底加粗一行,不算一张卡——不选中、不标注、不并排 */
+export declare function isHeading(card: BoardCard): boolean;
+/** 提问卡:末句问句没配能答的卡时解析器补的那张文字卡(《卡片协议.md》);字就是那句问话,独占一行 */
+export declare function isAskCard(card: BoardCard): boolean;
+/**
+ * 底色槽(机械规则;卡上写了 look.tint 就用它):做题的卡紫(plum),定义 / 结论蓝(sky),方法绿(moss),事实 / 例子 / 引言米(sand),
+ * 公式 / 图 / 代码白(paper)。名字对不上主题清单的,CSS 落回 paper。
+ */
+export declare function tintFor(card: BoardCard): string;
+/** 字形槽(机械规则;卡上写了 look.look 就用它):formula → formula(衬线),其余 plain */
+export declare function lookFor(card: BoardCard): string;
+/**
+ * 笔(机械规则;标注带了 pen 就用它):选项 → 方框;填空、数字与拉丁词 → 下划线;点读段、公式、大字 → 荧光;
+ * 标题位上的词 → 圈;其余(正文里正在定义的词)→ 术语底。
+ */
+export declare function penFor(card: BoardCard, phrase: string): PenName;
+/** 一行最多几张:明写的并排(课文件 / 老师的 same)能到 3 张;按宽度排的最多 2 张(半宽 + 半宽) */
+export declare const MAX_CARDS_PER_ROW = 3;
+/** 独占一行的卡:标题行、提问卡、画板、小课堂、画图、拍给我看(选择题量得下就能半宽,2026-10-01) */
+export declare function standsAlone(card: BoardCard): boolean;
+/** 能半宽的种类:文字、点读、代码、田字格、单词卡、选择题、填空题。字形(大字等)不算:字大放不下,量出来自然是全宽 */
+export declare function canHalf(card: BoardCard): boolean;
+/** 半宽时文字卡与点读最多几行(小标题也算一行);手机的半宽只有 170 来像素,一行七八个字,只放得下标题加一行 */
+export declare const HALF_LINES: Record<Device, number>;
+/** 页面把卡放进量具量出来的数:半宽 / 全宽时卡的高(像素)、半宽时文字有几行、半宽时有没有横着溢出 */
+export interface CardFit {
+    half: number;
+    full: number;
+    lines: number;
+    overflow: boolean;
+}
+/**
+ * 量出来的卡能不能半宽:文字卡与点读看行数,不超过 HALF_LINES;
+ * 公式、代码、田字格、单词卡、选择题、填空题半宽时不能比全宽高(折了行就是挤了:公式从中间断开没法看,选项挤成两行)。横着溢出的都不行
+ */
+export declare function fitsHalf(card: BoardCard, device: Device, m: CardFit): boolean;
+/** 量不了时的估计(测试;页面还没有宽度时):文字卡,字数 ≤ 20 */
+export declare function isShortCard(card: BoardCard): boolean;
+/**
+ * 一节的行(2026-10-01 起排版归代码):每张卡半宽还是全宽,看它自己量出来的样子
+ * (half(i),页面在量具里量;没给就按 isShortCard 估)。从左往右排,只看前面的卡:
+ * - 相邻两张半宽的并一行;一张半宽后面跟的不是半宽,它自己一行、占左半(右边空着)
+ * - 全宽的一行一张;标题行、提问卡、画板、小课堂永远独占
+ * - 明写的并排(section.layout 里不止一张的行:课文件 / 老师写的 same)照办,最多 3 张;
+ *   别的端排的到了手机上,超过 2 张或有不能半宽的就拆开,再按宽度排
+ * 流式一张张来时,前面的行不会因为后来的卡变。
+ */
+export declare function rowsFor(section: BoardSection, device: Device, half?: (i: number) => boolean): number[][];
+/** 一行几列:并排几张就几列;只有一张时,半宽的两列(占左半),全宽的一列 */
+export declare function rowCols(section: BoardSection, row: readonly number[], half?: (i: number) => boolean): number;
+/** 端:宽 ≥ 900 且横 → 平板横屏;短边 ≥ 600 → 平板竖屏;其余手机 */
+export declare function deviceFor(width: number, height: number): Device;
+/** 当前卡(选中态):播到这句该在的那张(lineTarget);句子没锚就是本节第一张不是标题行的卡;没在播 → null */
+export declare function nowCard(sections: readonly BoardSection[], state: PlayerState): number | null;
+export interface PenBox {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
+/** 笔画的框:相对被标注文字的一行矩形(宽 w、高 h),笔要伸出去多少 */
+export declare function penBox(pen: PenName, w: number, h: number): PenBox;
+/** 笔画的路径(viewBox 0 0 w h):下划线一笔、方框一圈、圈一圈多一点;seed 定抖动 */
+export declare function penPath(pen: PenName, w: number, h: number, seed: string): string;
+/** 有舞台交互(能改状态、能「交给老师」)的种类;其余点开只是放大看 */
+export declare function hasState(card: BoardCard): boolean;
+/** 画板上画了几笔(状态里的 ink 元素数) */
+export declare function inkCount(card: BoardCard): number;
+/** 重卡:舞台在 iframe 里的舞台包(/stage/)开,页面只管顶栏、字幕行、输入条 */
+export declare function isHeavy(card: BoardCard): boolean;
+/** 小课堂卡能不能放:课包读得出来,下发时服务端填 ready 与那一段的起止 */
+export declare function lectureReady(card: BoardCard): boolean;
+/** 点读第 k 段(0 起)的配音文件(相对 conversations/<老师>/);没生成好 → null(孩子端等它到,等不到不出声) */
+export declare function segmentAudio(card: BoardCard, k: number): string | null;
+/** 孩子在这张卡上做了什么(「交给老师」能不能按):选择题是选项;没做 → [] */
+export declare function stateSummary(card: BoardCard): string[];
+/** shi4 → shì:调号标在 a / e 上,ou 标在 o 上,否则标在最后一个元音上;5 是轻声不标;认不出的原样 */
+export declare function toneMark(syl: string): string;
+/** 舞台顶栏的名字:文字卡的标题 / 正文、选择题的问题、其余第一段有字的;截 24 字 */
+export declare function cardTitle(card: BoardCard): string;
+/** 选择题:点第 i 项后的选中集合——单选换成它(再点取消),多选切换 */
+export declare function togglePick(picked: readonly number[], i: number, multi: boolean): number[];
+/** 选择题当前选了什么(回显与紧凑态用):「B 三个」 */
+export declare function pickedLabels(card: BoardCard): string[];
+export declare function isQuestion(text: string): boolean;
+/** 孩子端条目里页面用到的字段(与 kid-view 的 KidMessage 兼容) */
+/** 孩子端一条带的小课堂:画的卡是截下来的图(没截图的课包现画那一刻再叠那几笔);家长端的画多一段老师拿到的话(text);again = 再看一遍又画的那条 */
+export interface KidLecture {
+    bundle: string;
+    title: string;
+    again?: true;
+    video?: true;
+    marks?: {
+        atMs: number;
+        svgMs: number;
+        strokes: [number, number][][];
+        text?: string;
+        image?: string;
+    }[];
+}
+/** 孩子从纸上交的画在板上那张卡:图(相对 workspace 根)、几笔、画了多久 */
+export interface KidDrawing {
+    image: string;
+    strokes: number;
+    ms?: number;
+}
+export interface BoardMessage {
+    job: string;
+    at?: string;
+    question: string | null;
+    reply: string | null;
+    pending: boolean;
+    section?: BoardSection | null;
+    /** 孩子这条带的作业照片(相对 workspace 根;R5):节头上回显缩略图 */
+    photos?: string[];
+    /** 看完小课堂后的第一条:这一节前面是小课堂卡 */
+    lecture?: KidLecture;
+    /** 孩子从左栏的纸交的画:这一节前面是孩子的画卡 */
+    drawing?: KidDrawing;
+    /** 孩子这条不是说的话:submit = 交卡(答案在卡上) */
+    action?: 'submit';
+    /** 按住说话的(索引里带 voice):板上去口头禅、一行截断 */
+    /** 首页按钮发的:按钮上的字,不是孩子说的 */
+    fromHome?: boolean;
+    /** 实时的一轮(讲稿嘴照念,不配音) */
+    live?: boolean;
+}
+/** 板上孩子的一句话:text 是显示的(语音去了口头禅),full 是原话 */
+export interface KidSaid {
+    text: string;
+    full: string;
+    /** 答拍给我看卡时拍来的照片:进那张卡的答案栏,节头不再回显 */
+    photos?: string[];
+}
+export interface BoardEntry extends BoardSection {
+    job: string;
+    at?: string;
+    /** 老师还在说:卡只增不改;前 ready 拍就绪了就能播(2026-09-13 之前是整轮跑完才播);整轮跑完换成正式的一节 */
+    partial?: boolean;
+    /** 孩子问这节时拍的照片(节头上回显) */
+    photos?: string[];
+    /** 这一节答的是看完小课堂后的第一问:节前画小课堂卡 */
+    lecture?: KidLecture;
+    /** 这一节答的是孩子从纸上交的画:节前一张孩子的画卡 */
+    drawing?: KidDrawing;
+    /** 孩子引出这一节的那句话;saidOn = 它答的是哪一节的哪张问题卡(写进那张卡的答案栏),没有 = 在这一节开头单独一行。实时的节头不是它(看 head),它只给左栏用 */
+    said?: KidSaid;
+    saidOn?: {
+        job: string;
+        card: number;
+    };
+    /** 实时的一轮:卡闭合了就铺(不按拍);不出卡的板上留讲稿的字 */
+    live?: true;
+    /** 实时:这一轮开头是脑写的节头(只有一行 # 标题的文字卡),从这里起新的一件事,head 是它的标题(liveHead) */
+    head?: string;
+    /** 实时:这一轮开头没写节头,接着上一节画 */
+    cont?: true;
+}
+/**
+ * 实时的一节怎么接:新一节的开头由脑定,不再机械是孩子那句。
+ * 这一轮第一张卡是节头 → head;没写(只有讲稿、开头是别的卡、还没写出卡)→ cont,接着上一节。一轮中间的节头卡,是从那张卡起新一节
+ */
+export declare function liveHead(s: Pick<BoardSection, 'cards'>): {
+    head: string;
+} | {
+    cont: true;
+};
+/**
+ * 一节的问题卡:孩子下一条答的写进它的答案栏;没有 = null。
+ * 有拍给我看卡就是它(最后那张),末句问不问都算:老师要的是照片;
+ * 否则末句是问句(不交给小课堂)、它锚着的是文字卡(不是小节标题),或解析器补的提问卡。
+ */
+export declare function askCard(section: Pick<BoardSection, 'cards' | 'lines' | 'partial'>): number | null;
+/**
+ * 每条孩子的话放在板上哪:交卡、首页按钮、空的不放;答的是上一节的问题卡就进那张卡的答案栏(on),
+ * 否则在它引出的那一节开头单独一行(on = null)。看完小课堂后的第一问不算答卡。按 job 给,还在跑的那条也有(刚发出去先挂上)。
+ */
+export declare function kidSaid(messages: readonly BoardMessage[]): Map<string, {
+    said: KidSaid;
+    on: {
+        job: string;
+        card: number;
+    } | null;
+}>;
+/**
+ * 孩子端条目 → 板书节(没有 section 的条目不出节);
+ * 孩子的话挂在它引出的那一节上(said / saidOn,kidSaid);还在跑的只有带 partial 板书(流式,已有卡或已有配好的句;实时的有句就算)才出节且标 partial,其余不出。
+ */
+export declare function sectionsFromMessages(messages: readonly BoardMessage[]): BoardEntry[];
+/** 一节在目录里的名字:小节标题 > 有名字的文字卡 > 第一张有字的卡 > 第一句讲稿;截到 14 个字 */
+export declare function sectionTitle(s: BoardSection): string;
+/** 板上的位置。孩子端不念讲稿了:讲稿由嘴照念(runtime/delivery/player.ts 的 liveStep),这里的状态只剩
+ *  thinking = 老师还在写 · waiting = 写完了、末句是问句 · done = 写完了 · idle = 板上还没东西。
+ *  playing 只出现在录像里孩子的屏幕(嘴在念这一句),孩子端自己不会进 */
+export type PlayStatus = 'idle' | 'playing' | 'waiting' | 'done' | 'thinking';
+export interface PlayerState {
+    section: number;
+    line: number;
+    status: PlayStatus;
+}
+/** 打开页面时的位置:停在最后一节末尾;末句是问句就等着 */
+export declare function playerAtEnd(sections: readonly BoardSection[]): PlayerState;
+/** 播到这句该滚到哪张卡:标注所在的卡优先,其次锚点卡,再没有就 null(页面滚到本节第一张) */
+export declare function lineTarget(line: BoardLine): number | null;
+export interface PlayerModel {
+    state: PlayerState;
+}
+/** step 要读的页面状态(只读) */
+export interface PlayerCtx {
+    sections: readonly BoardSection[];
+}
+export type PlayerEvent = {
+    type: 'reset';
+} | {
+    type: 'halt';
+} | {
+    type: 'liveStart';
+    section: number;
+} | {
+    type: 'liveBeat';
+    section: number;
+} | {
+    type: 'liveFinal';
+    section: number;
+} | {
+    type: 'liveDropped';
+} | {
+    type: 'fresh';
+    sections: number[];
+};
+/** stop 只停声音(卡的点读、单词);paint = 把某节的标注画齐;showNow = 选中态照现在的位置;scrollLast = 滚到最后一节 */
+export type PlayerEffect = {
+    kind: 'stop';
+} | {
+    kind: 'render';
+} | {
+    kind: 'showNow';
+} | {
+    kind: 'paint';
+    section: number;
+} | {
+    kind: 'scrollLast';
+};
+export declare function initialPlayer(): PlayerModel;
+export declare function step(model: PlayerModel, ev: PlayerEvent, ctx: PlayerCtx): {
+    model: PlayerModel;
+    effects: PlayerEffect[];
+};
+export type BarMode = 'idle' | 'typing' | 'holding';
+export type BarEvent = 'tap' | 'holdStart' | 'holdEnd' | 'holdCancel' | 'sent' | 'blur';
+/** 输入条中间那段:点 → 打字;按住 → 说话;松手 / 上滑取消 / 发出 / 失焦 → 回到闲置 */
+export declare function barNext(mode: BarMode, ev: BarEvent): BarMode;
+/** 一句念多久(毫秒):按字数估(mock 的假嘴、录像) */
+export declare function lineDurationMs(text: string): number;