cotutor 0.1.0 → 0.3.0

package/dist/board/canvas-chat.d.ts

@@ -0,0 +1,97 @@
+/**
+ * 画板:孩子的笔迹怎么数(各色几笔、大致在哪、画了多久),边画边聊时嘴什么时候主动说一句、说哪个颜色。纯函数。
+ * 剥类型内联进孩子端页面(同 runtime/delivery/player.ts),名字都带 canvas 前缀;服务端的画板卡 describe、纸交画时的摘要也用它。
+ * 改「什么时候说」先改的规矩,再改 tests/canvas-chat.test.ts,最后改这里(CANVAS_CHAT 是调参表)。
+ */
+/** 舞台的三支笔(src/ui/stage/canvas.tsx 的 INK_COLORS)叫什么;别的颜色(以后加的)叫「别的颜色」 */
+export declare const CANVAS_COLOR_NAMES: Readonly<Record<string, string>>;
+/** 一笔:颜色名、画完的时刻(excalidraw 元素的 updated,毫秒)、外框(画布坐标) */
+export interface CanvasStroke {
+    color: string;
+    at: number;
+    x0: number;
+    y0: number;
+    x1: number;
+    y1: number;
+}
+/** 一种颜色:几笔、在整张画里大致哪儿(上边偏右、中间、铺满大半张) */
+export interface CanvasColor {
+    name: string;
+    strokes: number;
+    where: string;
+}
+export interface CanvasSummary {
+    strokes: number;
+    /** 笔多的在前 */
+    colors: CanvasColor[];
+    /** 第一笔、最后一笔画完的时刻;没画是 null */
+    firstAt: number | null;
+    lastAt: number | null;
+}
+/** 笔迹(舞台存回来的 excalidraw 元素,customData.layer = 'ink')→ 一笔一行;删掉的、不是线条的不算 */
+export declare function canvasStrokes(ink: readonly Record<string, unknown>[]): CanvasStroke[];
+/** 整张画的摘要:几笔、各颜色几笔在哪、第一笔与最后一笔的时刻 */
+export declare function canvasSummary(strokes: readonly CanvasStroke[]): CanvasSummary;
+/** 「红 40 笔、蓝 51 笔」;只有一种颜色就只写几笔 */
+export declare function canvasColorsText(s: CanvasSummary): string;
+/** 画了多久(第一笔到最后一笔,加上清空前画的那几版):不到 1 分钟写「不到 1 分钟」 */
+export declare function canvasMinutesText(ms: number): string;
+/**
+ * 边画边聊的规矩(10-22 :先这样,跑一周再调)。毫秒。
+ * 换色:一种颜色从上一句到现在新画了 ≥ colorStrokes 笔、孩子换了颜色 → 说刚画完的那种;
+ * 久停:这一张 ≥ pauseStrokes 笔以后停笔 ≥ pauseMs → 说整张(上一句之后又画过才算);
+ * 不说:点开后 openQuietMs 内、上一笔不到 drawingMs(正在画)、清空后 clearQuietMs 内、孩子按头像说过 kidQuietMs 内、离上一句不到 gapMs、一张已经说了 maxLines 句;
+ * 不追:上一句问了没回 → 这句只说不问;连着 stopUnanswered 句没回 → 这一张不说了(他画得入神)
+ */
+export declare const CANVAS_CHAT: {
+    colorStrokes: number;
+    pauseStrokes: number;
+    pauseMs: number;
+    openQuietMs: number;
+    drawingMs: number;
+    clearQuietMs: number;
+    kidQuietMs: number;
+    gapMs: number;
+    maxLines: number;
+    stopUnanswered: number;
+};
+/** 嘴主动说过的一句:时刻、说的哪种颜色(null = 整张)、问没问、孩子回了没有、那时各颜色几笔 */
+export interface CanvasChatLine {
+    at: number;
+    color: string | null;
+    ask: boolean;
+    answered: boolean;
+    counts: Record<string, number>;
+    strokes: number;
+}
+/** 这一张纸(清空算新的一张)上边画边聊到哪了;kidAt = 孩子最近一次按头像说话 */
+export interface CanvasChatState {
+    openedAt: number;
+    clearedAt: number | null;
+    kidAt: number | null;
+    lines: CanvasChatLine[];
+}
+/** 要不要说:say = false 带为什么(测试、录像看);说的话带说哪种颜色(null = 整张)、问不问 */
+export type CanvasChatDue = {
+    say: false;
+    why: string;
+} | {
+    say: true;
+    color: string | null;
+    ask: boolean;
+    why: 'color' | 'pause';
+};
+export declare function canvasChatInit(now: number): CanvasChatState;
+/** 清空了:新的一张,计数重来 */
+export declare function canvasChatCleared(st: CanvasChatState, now: number): CanvasChatState;
+/** 孩子按着头像说了话(边画边聊):最近一句算回了;嘴刚接住他,一会儿内不再主动说 */
+export declare function canvasChatAnswered(st: CanvasChatState, now: number): CanvasChatState;
+/**
+ * 这一刻要不要说。busy = 孩子按着说话、嘴或卡在出声、脑在写(页面凑);strokes = 这一刻的笔(画完的时刻是 at)。
+ * 换色比久停先:刚画完的那种颜色具体,好问
+ */
+export declare function canvasChatDue(st: CanvasChatState, now: number, strokes: readonly CanvasStroke[], busy: boolean): CanvasChatDue;
+/** 说了:记下这一句(那时各颜色几笔,下次算「新画了几笔」) */
+export declare function canvasChatSaid(st: CanvasChatState, now: number, due: Extract<CanvasChatDue, {
+    say: true;
+}>, strokes: readonly CanvasStroke[]): CanvasChatState;

package/dist/board/canvas-chat.js

@@ -0,0 +1,175 @@
+/**
+ * 画板:孩子的笔迹怎么数(各色几笔、大致在哪、画了多久),边画边聊时嘴什么时候主动说一句、说哪个颜色。纯函数。
+ * 剥类型内联进孩子端页面(同 runtime/delivery/player.ts),名字都带 canvas 前缀;服务端的画板卡 describe、纸交画时的摘要也用它。
+ * 改「什么时候说」先改的规矩,再改 tests/canvas-chat.test.ts,最后改这里(CANVAS_CHAT 是调参表)。
+ */
+/** 舞台的三支笔(src/ui/stage/canvas.tsx 的 INK_COLORS)叫什么;别的颜色(以后加的)叫「别的颜色」 */
+export const CANVAS_COLOR_NAMES = { '#2b2b2b': '黑', '#d9482b': '红', '#2f6fd6': '蓝' };
+const canvasNum = (v, d = 0) => (typeof v === 'number' && Number.isFinite(v) ? v : d);
+/** 笔迹(舞台存回来的 excalidraw 元素,customData.layer = 'ink')→ 一笔一行;删掉的、不是线条的不算 */
+export function canvasStrokes(ink) {
+    const out = [];
+    for (const el of ink) {
+        if (!el || el.isDeleted === true)
+            continue;
+        const x = canvasNum(el.x), y = canvasNum(el.y);
+        const pts = Array.isArray(el.points) ? el.points.filter((p) => Array.isArray(p) && p.length >= 2 && typeof p[0] === 'number' && typeof p[1] === 'number') : [];
+        let x0 = x, y0 = y, x1 = x + canvasNum(el.width), y1 = y + canvasNum(el.height);
+        if (pts.length) {
+            x0 = Infinity;
+            y0 = Infinity;
+            x1 = -Infinity;
+            y1 = -Infinity;
+            for (const p of pts) {
+                x0 = Math.min(x0, x + p[0]);
+                y0 = Math.min(y0, y + p[1]);
+                x1 = Math.max(x1, x + p[0]);
+                y1 = Math.max(y1, y + p[1]);
+            }
+        }
+        const raw = typeof el.strokeColor === 'string' ? el.strokeColor.toLowerCase() : '';
+        out.push({ color: CANVAS_COLOR_NAMES[raw] ?? '别的颜色', at: canvasNum(el.updated), x0, y0, x1, y1 });
+    }
+    return out;
+}
+/** 一块外框在整张画的外框里大致哪儿:占了一半以上 = 铺满大半张;不然按中心落在九宫格哪格 */
+function canvasWhere(b, all) {
+    const W = Math.max(1, all.x1 - all.x0), H = Math.max(1, all.y1 - all.y0);
+    const area = (Math.max(0, b.x1 - b.x0) * Math.max(0, b.y1 - b.y0)) / (W * H);
+    if (area >= 0.5)
+        return '铺满大半张';
+    const cx = ((b.x0 + b.x1) / 2 - all.x0) / W, cy = ((b.y0 + b.y1) / 2 - all.y0) / H;
+    const v = cy < 1 / 3 ? '上边' : cy > 2 / 3 ? '下边' : '中间';
+    const hz = cx < 1 / 3 ? '偏左' : cx > 2 / 3 ? '偏右' : '';
+    return v === '中间' && hz ? (hz === '偏左' ? '左边' : '右边') : v + hz;
+}
+/** 整张画的摘要:几笔、各颜色几笔在哪、第一笔与最后一笔的时刻 */
+export function canvasSummary(strokes) {
+    if (!strokes.length)
+        return { strokes: 0, colors: [], firstAt: null, lastAt: null };
+    const all = { x0: Infinity, y0: Infinity, x1: -Infinity, y1: -Infinity };
+    const by = new Map();
+    let firstAt = Infinity, lastAt = -Infinity;
+    strokes.forEach((s, i) => {
+        all.x0 = Math.min(all.x0, s.x0);
+        all.y0 = Math.min(all.y0, s.y0);
+        all.x1 = Math.max(all.x1, s.x1);
+        all.y1 = Math.max(all.y1, s.y1);
+        if (s.at > 0) {
+            firstAt = Math.min(firstAt, s.at);
+            lastAt = Math.max(lastAt, s.at);
+        }
+        const c = by.get(s.color) ?? { n: 0, first: i, b: { x0: Infinity, y0: Infinity, x1: -Infinity, y1: -Infinity } };
+        c.n++;
+        c.b = { x0: Math.min(c.b.x0, s.x0), y0: Math.min(c.b.y0, s.y0), x1: Math.max(c.b.x1, s.x1), y1: Math.max(c.b.y1, s.y1) };
+        by.set(s.color, c);
+    });
+    const colors = [...by.entries()].sort((a, b) => b[1].n - a[1].n || a[1].first - b[1].first).map(([name, c]) => ({ name, strokes: c.n, where: canvasWhere(c.b, all) }));
+    return { strokes: strokes.length, colors, firstAt: Number.isFinite(firstAt) ? firstAt : null, lastAt: Number.isFinite(lastAt) ? lastAt : null };
+}
+/** 「红 40 笔、蓝 51 笔」;只有一种颜色就只写几笔 */
+export function canvasColorsText(s) {
+    if (!s.strokes)
+        return '还没画';
+    if (s.colors.length <= 1)
+        return `${s.strokes} 笔${s.colors[0] ? `(${s.colors[0].name})` : ''}`;
+    return s.colors.map((c) => `${c.name} ${c.strokes} 笔`).join('、');
+}
+/** 画了多久(第一笔到最后一笔,加上清空前画的那几版):不到 1 分钟写「不到 1 分钟」 */
+export function canvasMinutesText(ms) {
+    if (!(ms >= 60_000))
+        return '不到 1 分钟';
+    return `约 ${Math.round(ms / 60_000)} 分钟`;
+}
+/**
+ * 边画边聊的规矩(10-22 :先这样,跑一周再调)。毫秒。
+ * 换色:一种颜色从上一句到现在新画了 ≥ colorStrokes 笔、孩子换了颜色 → 说刚画完的那种;
+ * 久停:这一张 ≥ pauseStrokes 笔以后停笔 ≥ pauseMs → 说整张(上一句之后又画过才算);
+ * 不说:点开后 openQuietMs 内、上一笔不到 drawingMs(正在画)、清空后 clearQuietMs 内、孩子按头像说过 kidQuietMs 内、离上一句不到 gapMs、一张已经说了 maxLines 句;
+ * 不追:上一句问了没回 → 这句只说不问;连着 stopUnanswered 句没回 → 这一张不说了(他画得入神)
+ */
+export const CANVAS_CHAT = {
+    colorStrokes: 5,
+    pauseStrokes: 10,
+    pauseMs: 12_000,
+    openQuietMs: 20_000,
+    drawingMs: 2_000,
+    clearQuietMs: 30_000,
+    kidQuietMs: 15_000,
+    gapMs: 45_000,
+    maxLines: 4,
+    stopUnanswered: 2,
+};
+export function canvasChatInit(now) {
+    return { openedAt: now, clearedAt: null, kidAt: null, lines: [] };
+}
+/** 清空了:新的一张,计数重来 */
+export function canvasChatCleared(st, now) {
+    return { ...st, clearedAt: now, lines: [] };
+}
+/** 孩子按着头像说了话(边画边聊):最近一句算回了;嘴刚接住他,一会儿内不再主动说 */
+export function canvasChatAnswered(st, now) {
+    const lines = st.lines.slice();
+    if (lines.length)
+        lines[lines.length - 1] = { ...lines[lines.length - 1], answered: true };
+    return { ...st, kidAt: now, lines };
+}
+const canvasCounts = (strokes) => {
+    const c = {};
+    for (const s of strokes)
+        c[s.color] = (c[s.color] ?? 0) + 1;
+    return c;
+};
+/**
+ * 这一刻要不要说。busy = 孩子按着说话、嘴或卡在出声、脑在写(页面凑);strokes = 这一刻的笔(画完的时刻是 at)。
+ * 换色比久停先:刚画完的那种颜色具体,好问
+ */
+export function canvasChatDue(st, now, strokes, busy) {
+    const T = CANVAS_CHAT;
+    if (busy)
+        return { say: false, why: 'busy' };
+    if (now - st.openedAt < T.openQuietMs)
+        return { say: false, why: 'opened' };
+    if (st.clearedAt !== null && now - st.clearedAt < T.clearQuietMs)
+        return { say: false, why: 'cleared' };
+    if (st.kidAt !== null && now - st.kidAt < T.kidQuietMs)
+        return { say: false, why: 'kid' };
+    if (!strokes.length)
+        return { say: false, why: 'empty' };
+    const lines = st.lines;
+    if (lines.length >= T.maxLines)
+        return { say: false, why: 'max' };
+    const tail = lines.slice(-T.stopUnanswered);
+    if (tail.length === T.stopUnanswered && tail.every((l) => !l.answered))
+        return { say: false, why: 'unanswered' };
+    const last = lines[lines.length - 1];
+    if (last && now - last.at < T.gapMs)
+        return { say: false, why: 'gap' };
+    const lastAt = strokes.reduce((m, s) => Math.max(m, s.at), 0);
+    if (now - lastAt < T.drawingMs)
+        return { say: false, why: 'drawing' };
+    const ask = !(last && last.ask && !last.answered);
+    // 换色:按画完的先后排,最后一段同色之前那段的颜色;它从上一句到现在新画了够多
+    const seq = strokes.slice().sort((a, b) => a.at - b.at);
+    const now0 = seq[seq.length - 1].color;
+    let k = seq.length - 1;
+    while (k >= 0 && seq[k].color === now0)
+        k--;
+    const counts = canvasCounts(strokes);
+    if (k >= 0) {
+        const prev = seq[k].color;
+        const fresh = (counts[prev] ?? 0) - (last?.counts[prev] ?? 0);
+        if (fresh >= T.colorStrokes)
+            return { say: true, color: prev, ask, why: 'color' };
+    }
+    // 还没换色、这一种已经画了很多(一整张都是一种颜色):停笔够久也说它
+    if (strokes.length >= T.pauseStrokes && now - lastAt >= T.pauseMs && (!last || lastAt > last.at)) {
+        const only = Object.keys(counts).length === 1 ? now0 : null;
+        return { say: true, color: only, ask, why: 'pause' };
+    }
+    return { say: false, why: 'wait' };
+}
+/** 说了:记下这一句(那时各颜色几笔,下次算「新画了几笔」) */
+export function canvasChatSaid(st, now, due, strokes) {
+    return { ...st, lines: [...st.lines, { at: now, color: due.color, ask: due.ask, answered: false, counts: canvasCounts(strokes), strokes: strokes.length }] };
+}

package/dist/board/card-guards.d.ts

@@ -0,0 +1,15 @@
+/**
+ * 按卡裁的段落(《卡片协议.md》「谁拿到哪些卡」):板书写法的手写部分(cards/板书怎么写.md)与守则(cotutor-tutor)里,
+ * 只对某几种卡有用的段落用 `{{有 x y}}` … `{{/有}}` 包起来,递给某位老师时按他的卡留或去。纯函数,不读文件。
+ * activity 文件的「老师怎么带」也用它,名字还可以是参数(填了才留,src/runtime/activity.ts)。
+ */
+/** 守卫行;名字是卡的种类(英文小写),或 activity 的参数名(汉字,src/runtime/activity.ts) */
+export declare const GUARD_OPEN: RegExp;
+export declare const GUARD_CLOSE: RegExp;
+/**
+ * 按卡裁的段落:`{{有 x y}}` 到 `{{/有}}` 之间的行,x、y 都在 kinds 里才留;守卫行本身不留,能套。
+ * 删掉一段留下的连续空行并成一行。守卫不配对就抛(gen:skills 与测试先红)。
+ */
+export declare function applyCardGuards(text: string, kinds: readonly string[]): string;
+/** 同上,「有没有」由 has 定:activity 递给老师时,名字是参数就看填没填,是卡就看这个话题有没有 */
+export declare function applyGuards(text: string, has: (name: string) => boolean): string;

package/dist/board/card-guards.js

@@ -0,0 +1,38 @@
+/**
+ * 按卡裁的段落(《卡片协议.md》「谁拿到哪些卡」):板书写法的手写部分(cards/板书怎么写.md)与守则(cotutor-tutor)里,
+ * 只对某几种卡有用的段落用 `{{有 x y}}` … `{{/有}}` 包起来,递给某位老师时按他的卡留或去。纯函数,不读文件。
+ * activity 文件的「老师怎么带」也用它,名字还可以是参数(填了才留,src/runtime/activity.ts)。
+ */
+/** 守卫行;名字是卡的种类(英文小写),或 activity 的参数名(汉字,src/runtime/activity.ts) */
+export const GUARD_OPEN = /^\{\{有((?:\s+[^\s{}]+)+)\}\}\s*$/;
+export const GUARD_CLOSE = /^\{\{\/有\}\}\s*$/;
+/**
+ * 按卡裁的段落:`{{有 x y}}` 到 `{{/有}}` 之间的行,x、y 都在 kinds 里才留;守卫行本身不留,能套。
+ * 删掉一段留下的连续空行并成一行。守卫不配对就抛(gen:skills 与测试先红)。
+ */
+export function applyCardGuards(text, kinds) {
+    return applyGuards(text, (name) => kinds.includes(name));
+}
+/** 同上,「有没有」由 has 定:activity 递给老师时,名字是参数就看填没填,是卡就看这个话题有没有 */
+export function applyGuards(text, has) {
+    const keep = [];
+    const out = [];
+    for (const line of text.split('\n')) {
+        const open = GUARD_OPEN.exec(line);
+        if (open) {
+            keep.push(open[1].trim().split(/\s+/).every(has));
+            continue;
+        }
+        if (GUARD_CLOSE.test(line)) {
+            if (!keep.length)
+                throw new Error('{{/有}} 多了一个');
+            keep.pop();
+            continue;
+        }
+        if (keep.every(Boolean))
+            out.push(line);
+    }
+    if (keep.length)
+        throw new Error('{{有 …}} 没有配对的 {{/有}}');
+    return out.join('\n').replace(/\n{3,}/g, '\n\n');
+}

package/dist/board/cards/canvas.d.ts

@@ -0,0 +1,41 @@
+/**
+ * 画板卡:孩子在上面画。底图四种——课包 id(整幅终帧做底层)、行内小骨架 JSON、一张图(孩子拍的作业
+ * captures/… 或别的 workspace 里的图片,R5:在自己的作业照片上圈错题、写答案)、空白 + 题目;
+ * 舞台是舞台包里的 excalidraw 编辑器(底层锁定,孩子的笔打 customData.layer = 'ink');「给老师看」→ 导出 png 存 .cards/<n>.png,
+ * 状态存 ink 元素;清空前那一版存一张图(cleared);describe 给笔数、各颜色几笔、画了多久、清空过几次与图的路径,
+ * 老师 Read 看图(进上下文包时 runner 换成绝对路径、这轮带只读工具;看不了图就靠笔数)。
+ */
+import { z } from 'zod';
+import { type CardKind } from './kind.ts';
+export declare const CanvasPropsSchema: z.ZodObject<{
+    base: z.ZodNullable<z.ZodUnion<readonly [z.ZodObject<{
+        bundle: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        skeletons: z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$strip>, z.ZodObject<{
+        image: z.ZodString;
+    }, z.core.$strip>]>>;
+    prompt: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type CanvasProps = z.infer<typeof CanvasPropsSchema>;
+/** 清空过的一版(页面记):清空的时刻、那一版第一笔画完的时刻、几笔、清空前导出的那张图(captures/…,先 POST photos 拿到的路径) */
+export declare const CanvasClearedSchema: z.ZodObject<{
+    at: z.ZodNumber;
+    from: z.ZodOptional<z.ZodNumber>;
+    strokes: z.ZodNumber;
+    image: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const CanvasStateSchema: z.ZodObject<{
+    ink: z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    image: z.ZodOptional<z.ZodString>;
+    cleared: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        at: z.ZodNumber;
+        from: z.ZodOptional<z.ZodNumber>;
+        strokes: z.ZodNumber;
+        image: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export type CanvasState = z.infer<typeof CanvasStateSchema>;
+/** 「画了 103 笔(黑 12、红 40、蓝 51),画了约 7 分钟,清空重画过 4 次,清掉的那几版:…(用 Read 看)」;图另写 */
+export declare function canvasInkText(s: Pick<CanvasState, 'ink' | 'cleared'>): string;
+export declare const canvas: CardKind<CanvasProps, CanvasState>;

package/dist/board/cards/canvas.js

@@ -0,0 +1,83 @@
+/**
+ * 画板卡:孩子在上面画。底图四种——课包 id(整幅终帧做底层)、行内小骨架 JSON、一张图(孩子拍的作业
+ * captures/… 或别的 workspace 里的图片,R5:在自己的作业照片上圈错题、写答案)、空白 + 题目;
+ * 舞台是舞台包里的 excalidraw 编辑器(底层锁定,孩子的笔打 customData.layer = 'ink');「给老师看」→ 导出 png 存 .cards/<n>.png,
+ * 状态存 ink 元素;清空前那一版存一张图(cleared);describe 给笔数、各颜色几笔、画了多久、清空过几次与图的路径,
+ * 老师 Read 看图(进上下文包时 runner 换成绝对路径、这轮带只读工具;看不了图就靠笔数)。
+ */
+import { z } from 'zod';
+import { BUNDLE_ID_RE, bodyLines } from "./kind.js";
+import { IMAGE_EXT } from "./image.js";
+import { canvasMinutesText, canvasStrokes, canvasSummary } from "../canvas-chat.js";
+export const CanvasPropsSchema = z.object({
+    /** 底图:课包 id / 行内骨架 / 一张图(相对 workspace 根,如 captures/2026-09-14/1620-1.jpg)/ 没有(空白) */
+    base: z.union([z.object({ bundle: z.string().regex(BUNDLE_ID_RE) }), z.object({ skeletons: z.array(z.record(z.string(), z.unknown())).min(1).max(40) }), z.object({ image: z.string().min(1) })]).nullable(),
+    /** 题目(空白画板必须有;有底图时可选,画在顶栏) */
+    prompt: z.string().optional(),
+});
+/** 清空过的一版(页面记):清空的时刻、那一版第一笔画完的时刻、几笔、清空前导出的那张图(captures/…,先 POST photos 拿到的路径) */
+export const CanvasClearedSchema = z.object({ at: z.number(), from: z.number().optional(), strokes: z.number().int().nonnegative(), image: z.string().optional() });
+export const CanvasStateSchema = z.object({
+    /** 孩子画的 excalidraw 元素(customData.layer = 'ink') */
+    ink: z.array(z.record(z.string(), z.unknown())).max(2000),
+    /** 「给老师看」时导出的 png(相对 workspace 根,如 conversations/math-tutor/2026-09-10.1620-1.cards/2.png);服务端写,页面不填 */
+    image: z.string().optional(),
+    /** 清空过的几版(清空前自动存一张图,脑和家长都看得到) */
+    cleared: z.array(CanvasClearedSchema).max(50).optional(),
+});
+/** 「画了 103 笔(黑 12、红 40、蓝 51),画了约 7 分钟,清空重画过 4 次,清掉的那几版:…(用 Read 看)」;图另写 */
+export function canvasInkText(s) {
+    const sum = canvasSummary(canvasStrokes(s.ink));
+    const cleared = s.cleared ?? [];
+    if (!sum.strokes && !cleared.length)
+        return '还没画';
+    const named = sum.colors.filter((c) => c.name !== '别的颜色');
+    const parts = [`画了 ${sum.strokes} 笔${named.length ? `(${named.map((c) => `${c.name} ${c.strokes}`).join('、')})` : ''}`];
+    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);
+    if (starts.length && end !== null)
+        parts.push(`画了${canvasMinutesText(end - Math.min(...starts))}`);
+    if (cleared.length) {
+        const imgs = cleared.flatMap((c) => (c.image ? [c.image] : []));
+        parts.push(`清空重画过 ${cleared.length} 次${imgs.length ? `,清掉的那几版:${imgs.join('、')}(用 Read 看)` : ''}`);
+    }
+    return parts.join(',');
+}
+export const canvas = {
+    name: 'canvas',
+    props: CanvasPropsSchema,
+    parse(body, mods) {
+        const lines = bodyLines(body);
+        const first = lines[0] ?? '';
+        const rest = lines.slice(1).join(' ').trim();
+        const promptFromTag = mods.join(' ').trim();
+        if (first.startsWith('{')) {
+            let obj;
+            try {
+                obj = JSON.parse(lines.join('\n'));
+            }
+            catch (err) {
+                throw new Error(`行内骨架不是合法 JSON:${err instanceof Error ? err.message : String(err)}`);
+            }
+            const sk = obj.skeletons;
+            if (!Array.isArray(sk) || !sk.length)
+                throw new Error('行内骨架要有 skeletons 数组');
+            return { base: { skeletons: sk }, ...(promptFromTag ? { prompt: promptFromTag } : {}) };
+        }
+        if (first && IMAGE_EXT.test(first) && !/^https?:\/\//.test(first))
+            return { base: { image: first }, ...(rest || promptFromTag ? { prompt: rest || promptFromTag } : {}) };
+        if (first && BUNDLE_ID_RE.test(first) && !/[一-鿿]/.test(first))
+            return { base: { bundle: first }, ...(rest || promptFromTag ? { prompt: rest || promptFromTag } : {}) };
+        const prompt = [promptFromTag, ...lines].filter(Boolean).join(' ').trim();
+        if (!prompt)
+            throw new Error('空白画板要有题目(写在正文或标签后面)');
+        return { base: null, prompt };
+    },
+    state: CanvasStateSchema,
+    describe(_p, s) {
+        const ink = canvasInkText(s);
+        if (ink === '还没画')
+            return ink;
+        return `${ink}${s.image ? `,图:${s.image}(用 Read 看)` : ''}`;
+    },
+};

package/dist/board/cards/choice.d.ts

@@ -0,0 +1,20 @@
+/**
+ * 选择题卡:问题 + 选项;答案(哪几项对)只有老师知道,不下发孩子端。
+ * 状态 = 孩子选了哪几项(舞台里点大按钮);「交给老师」时 describe 成「选了「B 三个」(答案:「三个」)」进上下文包——对错只在老师嘴里。
+ */
+import { z } from 'zod';
+import { type CardKind } from './kind.ts';
+export declare const ChoicePropsSchema: z.ZodObject<{
+    question: z.ZodString;
+    options: z.ZodArray<z.ZodString>;
+    answer: z.ZodOptional<z.ZodArray<z.ZodNumber>>;
+    multi: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export type ChoiceProps = z.infer<typeof ChoicePropsSchema>;
+export declare const ChoiceStateSchema: z.ZodObject<{
+    picked: z.ZodArray<z.ZodNumber>;
+}, z.core.$strip>;
+export type ChoiceState = z.infer<typeof ChoiceStateSchema>;
+/** 「B 三个」;下标越界只写字母 */
+export declare function optionLabel(options: readonly string[], i: number): string;
+export declare const choice: CardKind<ChoiceProps, ChoiceState>;

package/dist/board/cards/choice.js

@@ -0,0 +1,64 @@
+/**
+ * 选择题卡:问题 + 选项;答案(哪几项对)只有老师知道,不下发孩子端。
+ * 状态 = 孩子选了哪几项(舞台里点大按钮);「交给老师」时 describe 成「选了「B 三个」(答案:「三个」)」进上下文包——对错只在老师嘴里。
+ */
+import { z } from 'zod';
+import { bodyLines } from "./kind.js";
+export const ChoicePropsSchema = z.object({
+    question: z.string().min(1),
+    options: z.array(z.string().min(1)).min(1),
+    /** 对的选项下标(可多个);老师没标就没有 */
+    answer: z.array(z.number().int().nonnegative()).optional(),
+    /** 多选(老师标了多个 [x]);孩子端靠它决定能不能多选,答案剥掉它还在 */
+    multi: z.boolean().optional(),
+});
+export const ChoiceStateSchema = z.object({
+    /** 选了的下标,按点的顺序 */
+    picked: z.array(z.number().int().nonnegative()).max(26),
+});
+const OPTION = /^[-*+]\s+(?:\[([ xX])\]\s*)?(.+)$/;
+const LETTER = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ';
+/** 「B 三个」;下标越界只写字母 */
+export function optionLabel(options, i) {
+    const letter = LETTER[i] ?? String(i + 1);
+    return options[i] ? `${letter} ${options[i]}` : letter;
+}
+export const choice = {
+    name: 'choice',
+    props: ChoicePropsSchema,
+    parse(body) {
+        const question = [];
+        const options = [];
+        const answer = [];
+        for (const line of bodyLines(body)) {
+            const m = OPTION.exec(line);
+            if (!m) {
+                if (options.length)
+                    continue; // 选项后面的散话不要
+                question.push(line);
+                continue;
+            }
+            if (m[1] && m[1] !== ' ')
+                answer.push(options.length);
+            options.push(m[2].trim());
+        }
+        if (!question.length)
+            throw new Error('第一行要是问题');
+        if (!options.length)
+            throw new Error('没有选项行(- [ ] 选项)');
+        return { question: question.join(' '), options, ...(answer.length ? { answer } : {}), ...(answer.length > 1 ? { multi: true } : {}) };
+    },
+    strip(p) {
+        const { answer: _drop, ...rest } = p;
+        return rest;
+    },
+    state: ChoiceStateSchema,
+    describe(p, s) {
+        const picked = s.picked.filter((i) => i < p.options.length);
+        if (!picked.length)
+            return '没选';
+        const chosen = picked.map((i) => `「${optionLabel(p.options, i)}」`).join('');
+        const key = p.answer?.length ? `(答案:${p.answer.map((i) => `「${optionLabel(p.options, i)}」`).join('')})` : '';
+        return `选了${chosen}${key}`;
+    },
+};

package/dist/board/cards/code.d.ts

@@ -0,0 +1,9 @@
+/** 代码卡:原样显示。不认识的围栏标签也落到这里(老师教编程写 ```python 就正好是它)。 */
+import { z } from 'zod';
+import type { CardKind } from './kind.ts';
+export declare const CodePropsSchema: z.ZodObject<{
+    lang: z.ZodNullable<z.ZodString>;
+    text: z.ZodString;
+}, z.core.$strip>;
+export type CodeProps = z.infer<typeof CodePropsSchema>;
+export declare const code: CardKind<CodeProps>;

package/dist/board/cards/code.js

@@ -0,0 +1,10 @@
+/** 代码卡:原样显示。不认识的围栏标签也落到这里(老师教编程写 ```python 就正好是它)。 */
+import { z } from 'zod';
+export const CodePropsSchema = z.object({ lang: z.string().nullable(), text: z.string() });
+export const code = {
+    name: 'code',
+    props: CodePropsSchema,
+    parse(body, mods) {
+        return { lang: mods[0] ?? null, text: body.replace(/\s+$/, '') };
+    },
+};

package/dist/board/cards/dictation.d.ts

@@ -0,0 +1,42 @@
+/**
+ * 听写卡(kind 名 dictation,只用在首页):家长写一串词,孩子在首页点开,老师一个一个念、孩子在田字格里写,写完自己对。
+ * 英文单词也行:词都是英文单词时 props.lang = 'en',孩子在四线三格里写整个单词。
+ * 标签修饰 = 念的老师(cotutor.json 的键,用他的音色;不写用语文老师或第一位配了音色的);正文一行一个词,词后面空一格可以跟「怎么念」。
+ * 英文单词前面可以配一个 emoji:只在孩子写完对一对时出,写的时候看不到。
+ * 词就是答案:strip 只留几个词,孩子端首页 JSON 里没有字;听写页写完交了才拿到(src/app/dictation/route.ts)。
+ */
+import { z } from 'zod';
+import { type CardKind } from './kind.ts';
+/** 一个词最多几个字(一个字一个田字格,同田字格卡) */
+export declare const DICTATION_WORD_MAX = 4;
+/** 英文单词最多几个字母(一个单词一个四线三格) */
+export declare const DICTATION_EN_MAX = 20;
+/** 英文单词:字母开头,可以带连字符与撇号(ice-cream、don't);不带空格,一行一个单词 */
+export declare const EN_WORD_RE: RegExp;
+export type DictationLang = 'zh' | 'en';
+/** 能不能听写、是哪种:一到四个汉字 = zh;一个英文单词(≤ 20 个字母)= en;都不是 null */
+export declare function dictationWordLang(text: string): DictationLang | null;
+/** 一张卡最多几个词 */
+export declare const DICTATION_WORDS_MAX = 20;
+/** 念法最多几个字 */
+export declare const DICTATION_SAY_MAX = 40;
+/** 是一个 emoji 就回它(去掉两头空白),不是 undefined;英文单词配的图 */
+export declare function dictationEmoji(v: unknown): string | undefined;
+export declare const DictationWordSchema: z.ZodObject<{
+    chars: z.ZodString;
+    say: z.ZodOptional<z.ZodString>;
+    emoji: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type DictationWord = z.infer<typeof DictationWordSchema>;
+export declare const DictationPropsSchema: z.ZodObject<{
+    tutor: z.ZodOptional<z.ZodString>;
+    lang: z.ZodOptional<z.ZodLiteral<"en">>;
+    words: z.ZodArray<z.ZodObject<{
+        chars: z.ZodString;
+        say: z.ZodOptional<z.ZodString>;
+        emoji: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    count: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type DictationProps = z.infer<typeof DictationPropsSchema>;
+export declare const dictation: CardKind<DictationProps>;