cotutor 0.2.0 → 0.3.0

package/dist/chalk/check.js

@@ -0,0 +1,291 @@
+/**
+ * 阶梯层 2–3:schema 校验、语义 lint、确定性布局检查。
+ * 纯函数,不碰文件系统;错误信息 = 修复指南(README「Design principles」)。
+ * 层 1(类型,内嵌 tsc)在 typecheck.ts,模块求值在 load-scene.ts;层 4(keyframe 截图)归 snap。
+ */
+import { KNOWN_ELEMENT_TYPES, sceneSchema } from "./scene-schema.js";
+import { elementBounds } from "./geometry.js";
+import { isAction, resolveActions } from "./actions.js";
+export function checkScene(raw) {
+    const findings = [];
+    const parsed = sceneSchema.safeParse(raw);
+    if (!parsed.success) {
+        for (const issue of parsed.error.issues) {
+            findings.push({ level: 'error', rule: 'schema', message: `${formatPath(issue.path)}:${issue.message}` });
+        }
+        return { scene: null, findings };
+    }
+    const scene = parsed.data;
+    lintSemantics(scene, findings);
+    lintLayout(scene, findings);
+    return { scene, findings };
+}
+function formatPath(path) {
+    if (!path.length)
+        return '(场景根)';
+    return path.reduce((acc, seg) => (typeof seg === 'number' ? `${acc}[${seg}]` : acc ? `${acc}.${String(seg)}` : String(seg)), '');
+}
+// ---- 层 2:语义 lint ----
+function relativeAudioOk(src) {
+    return !src.startsWith('/') && !/^[a-z]+:/i.test(src);
+}
+/**
+ * 一幅画面(skeletons + steps)的语义 lint,主场景与每个子场景各跑一遍。
+ * ctx 是消息前缀(主场景为空,子场景形如「子场景 'blend-ram' 」)。
+ * steps 为空 = 静态画面,跳过覆盖检查;「空得合不合法」由 template 一致性规则单独判。
+ */
+function lintDrawing(skeletons, steps, findings, ctx = '') {
+    const idSeq = skeletons.map((e) => e.id);
+    const seen = new Set();
+    for (const id of idSeq) {
+        if (seen.has(id)) {
+            findings.push({ level: 'error', rule: 'unique-id', message: `${ctx}元素 id '${id}' 重复;id 是步与元素的对齐键,必须唯一` });
+        }
+        seen.add(id);
+    }
+    for (const el of skeletons) {
+        if (isAction(el)) {
+            if (ctx)
+                findings.push({ level: 'error', rule: 'subscene-action', message: `${ctx}里有动作 '${el.id}'(${el.type});弹窗子场景不擦、不换画板,去掉它` });
+            continue;
+        }
+        if (typeof el.x !== 'number' || typeof el.y !== 'number') {
+            findings.push({ level: 'error', rule: 'xy', message: `${ctx}元素 '${el.id}' 缺 x / y(数字,场景坐标);只有动作(erase、board)不用写位置` });
+        }
+        if (el.targets !== undefined || el.background !== undefined) {
+            findings.push({ level: 'warning', rule: 'action-field', message: `${ctx}元素 '${el.id}'(${el.type})带了 ${el.targets !== undefined ? 'targets' : 'background'},那是动作的字段(erase 的 targets、board 的 background),画的元素用不上` });
+        }
+        if (/animate(Duration|Order):/.test(el.id)) {
+            findings.push({ level: 'error', rule: 'clean-id', message: `${ctx}元素 '${el.id}' 的 id 携带 animate 指令;时长写成 animateDuration 字段,顺序由数组位置决定` });
+        }
+        if (Array.isArray(el.groupIds) && el.groupIds.length) {
+            findings.push({ level: 'error', rule: 'no-group', message: `${ctx}元素 '${el.id}' 带 groupIds,会破坏逐笔串行调度;去掉 groupIds,顺序用数组表达` });
+        }
+        if (!KNOWN_ELEMENT_TYPES.includes(el.type)) {
+            findings.push({ level: 'warning', rule: 'element-type', message: `${ctx}元素 '${el.id}' 的类型 '${el.type}' 未经引擎验证;已验证类型:${KNOWN_ELEMENT_TYPES.join('、')}` });
+        }
+        if (el.type === 'text') {
+            if (typeof el.text !== 'string' || !el.text) {
+                findings.push({ level: 'error', rule: 'text-content', message: `${ctx}text 元素 '${el.id}' 缺 text 内容(字符串)` });
+            }
+            if (typeof el.fontSize !== 'number') {
+                findings.push({ level: 'error', rule: 'text-content', message: `${ctx}text 元素 '${el.id}' 缺 fontSize(数字,px)` });
+            }
+            else if (el.fontSize < 16) {
+                findings.push({ level: 'warning', rule: 'text-size', message: `${ctx}text 元素 '${el.id}' 的 fontSize ${el.fontSize} 偏小;iPad 上建议 ≥16` });
+            }
+        }
+    }
+    steps.forEach((s, i) => {
+        if (s.step !== i + 1) {
+            findings.push({ level: 'error', rule: 'step-order', message: `${ctx}第 ${i + 1} 个步的 step 是 ${s.step};step 必须从 1 连续递增` });
+        }
+    });
+    // 笔顺覆盖:steps 的 elementIds 依次拼接后须与 skeletons 顺序完全一致(静态画面无 steps,跳过)
+    if (steps.length) {
+        const flat = steps.flatMap((s) => s.elementIds);
+        const n = Math.max(flat.length, idSeq.length);
+        for (let i = 0; i < n; i++) {
+            if (flat[i] !== idSeq[i]) {
+                findings.push({
+                    level: 'error',
+                    rule: 'stroke-cover',
+                    message: `${ctx}steps 必须按 skeletons 顺序连续覆盖全部元素(笔顺即步序):` +
+                        `第 ${i + 1} 笔期望 '${idSeq[i] ?? '(无:skeletons 已用尽,steps 多出元素)'}',steps 给的是 '${flat[i] ?? '(缺:steps 提前结束)'}'`,
+                });
+                break;
+            }
+        }
+    }
+    for (const s of steps) {
+        if (s.audioSrc && !relativeAudioOk(s.audioSrc)) {
+            findings.push({ level: 'warning', rule: 'audio-path', message: `${ctx}step ${s.step} 的 audioSrc '${s.audioSrc}' 不是相对路径;课包自包含,音频放课包目录内(如 audio/step1.mp3)` });
+        }
+    }
+}
+function lintSemantics(scene, findings) {
+    lintDrawing(scene.skeletons, scene.steps, findings);
+    // 模板与 steps 一致性:static 必空,讲解三档必非空
+    if (scene.template === 'static' && scene.steps.length) {
+        findings.push({ level: 'error', rule: 'static-steps', message: `template 'static' 是无时间轴的静态场景,steps 必须为空;要逐步讲解请换讲解模板(paper-strict / camera-free / motion)` });
+    }
+    if (scene.template !== 'static' && !scene.steps.length) {
+        findings.push({ level: 'error', rule: 'steps-required', message: `template '${scene.template}' 是讲解模板,steps 不能为空;静态点读/圈读页请用 template 'static'` });
+    }
+    if (scene.background && !relativeAudioOk(scene.background.src)) {
+        findings.push({ level: 'warning', rule: 'background-path', message: `background.src '${scene.background.src}' 不是相对路径;写成相对场景文件的路径,build 会把图拷进课包` });
+    }
+    lintActions(scene, findings);
+    lintInteractions(scene, findings);
+    lintGroups(scene, findings);
+}
+/** 笔顺里的动作(擦掉、换画板):引用对不对、放的地方对不对 */
+function lintActions(scene, findings) {
+    const acts = scene.skeletons.filter(isAction);
+    if (!acts.length)
+        return;
+    if (scene.template === 'static') {
+        findings.push({ level: 'error', rule: 'static-action', message: `静态场景(template 'static')没有时间轴,不能有动作(${acts.map((a) => a.id).join('、')});要擦、换画板请换讲解模板` });
+    }
+    for (const p of resolveActions(scene.skeletons, scene.background).problems) {
+        findings.push({ level: 'error', rule: 'erase-target', message: p.message });
+    }
+    if (scene.skeletons[0]?.type === 'board') {
+        findings.push({ level: 'error', rule: 'board-first', message: `第一笔 '${scene.skeletons[0].id}' 就换画板;第一块画板的背景图写在场景的 background 上,board 只用来换到下一块` });
+    }
+    for (const a of acts) {
+        if (a.type === 'board' && a.targets !== undefined) {
+            findings.push({ level: 'warning', rule: 'action-field', message: `换画板 '${a.id}' 不用写 targets:旧板上的东西都会擦掉` });
+        }
+        if (a.type === 'erase' && a.background !== undefined) {
+            findings.push({ level: 'warning', rule: 'action-field', message: `擦除 '${a.id}' 带了 background;换背景图要用 { type: 'board', background }` });
+        }
+        const bg = a.background;
+        if (a.type === 'board' && bg && typeof bg.src === 'string' && !relativeAudioOk(bg.src)) {
+            findings.push({ level: 'warning', rule: 'background-path', message: `换画板 '${a.id}' 的 background.src '${bg.src}' 不是相对路径;写成相对场景文件的路径,build 会把图拷进课包` });
+        }
+    }
+}
+/** groups 的引用完整性:id 不重、成员都在场景里、一组里不重复 */
+function lintGroups(scene, findings) {
+    const els = new Set(scene.skeletons.map((e) => e.id));
+    const seen = new Set();
+    for (const g of scene.groups ?? []) {
+        if (seen.has(g.id))
+            findings.push({ level: 'error', rule: 'group-id', message: `groups 里 id '${g.id}' 重复;每组一个 id` });
+        seen.add(g.id);
+        const missing = g.elementIds.filter((id) => !els.has(id));
+        if (missing.length)
+            findings.push({ level: 'error', rule: 'group-ref', message: `group '${g.id}'(${g.label})引用了不存在的元素 ${missing.join(', ')};elementIds 写 skeletons 里的 id` });
+        if (new Set(g.elementIds).size !== g.elementIds.length)
+            findings.push({ level: 'warning', rule: 'group-dup', message: `group '${g.id}' 的 elementIds 有重复` });
+    }
+}
+/** blocks / subscenes 的引用完整性与触发语义 */
+function lintInteractions(scene, findings) {
+    const blocks = scene.blocks ?? [];
+    const subscenes = scene.subscenes ?? [];
+    const elById = new Map(scene.skeletons.map((e) => [e.id, e]));
+    const subIds = new Set();
+    for (const sub of subscenes) {
+        if (subIds.has(sub.id)) {
+            findings.push({ level: 'error', rule: 'unique-id', message: `子场景 id '${sub.id}' 重复;blocks[].subsceneId 靠它寻址,必须唯一` });
+        }
+        subIds.add(sub.id);
+        lintDrawing(sub.skeletons, sub.steps ?? [], findings, `子场景 '${sub.id}' `);
+        if (sub.audioSrc && !relativeAudioOk(sub.audioSrc)) {
+            findings.push({ level: 'warning', rule: 'audio-path', message: `子场景 '${sub.id}' 的 audioSrc '${sub.audioSrc}' 不是相对路径;课包自包含,音频放课包目录内` });
+        }
+    }
+    const blockIds = new Set();
+    const referencedSubs = new Set();
+    for (const b of blocks) {
+        if (blockIds.has(b.id)) {
+            findings.push({ level: 'error', rule: 'unique-id', message: `块 id '${b.id}' 重复;事件记录靠它区分词条,必须唯一` });
+        }
+        blockIds.add(b.id);
+        for (const id of b.elementIds) {
+            if (!elById.has(id)) {
+                findings.push({ level: 'error', rule: 'block-element', message: `块 '${b.id}' 引用元素 '${id}',skeletons 中不存在;块锚在底层元素上,先修元素 id` });
+            }
+        }
+        if (b.subsceneId) {
+            referencedSubs.add(b.subsceneId);
+            if (!subIds.has(b.subsceneId)) {
+                findings.push({ level: 'error', rule: 'block-subscene', message: `块 '${b.id}' 引用子场景 '${b.subsceneId}',subscenes 中不存在;现有:${[...subIds].join('、') || '(无)'}` });
+            }
+        }
+        if (!b.audioSrc && !b.subsceneId) {
+            findings.push({ level: 'warning', rule: 'block-trigger', message: `块 '${b.id}' 既无 audioSrc 也无 subsceneId,圈中后无事发生;给一个触发,或删掉这个块` });
+        }
+        if (b.audioSrc && !relativeAudioOk(b.audioSrc)) {
+            findings.push({ level: 'warning', rule: 'audio-path', message: `块 '${b.id}' 的 audioSrc '${b.audioSrc}' 不是相对路径;课包自包含,音频放课包目录内(如 audio/tokens/ram.mp3)` });
+        }
+        // 词条文本与元素文本一致性(重点字母色拆分后 r + am 拼回 ram)
+        const joined = b.elementIds
+            .map((id) => elById.get(id))
+            .filter((e) => !!e && e.type === 'text' && typeof e.text === 'string')
+            .map((e) => e.text)
+            .join('');
+        if (joined && joined !== b.text) {
+            findings.push({ level: 'warning', rule: 'block-text', message: `块 '${b.id}' 的 text 是 '${b.text}',但所引 text 元素拼起来是 '${joined}';两者应一致,否则事件记录与画面脱节` });
+        }
+    }
+    for (const sub of subscenes) {
+        if (!referencedSubs.has(sub.id)) {
+            findings.push({ level: 'warning', rule: 'subscene-orphan', message: `子场景 '${sub.id}' 没有任何块引用,永远不会被触发;接到某个 blocks[].subsceneId,或删掉它` });
+        }
+    }
+}
+/**
+ * 包围盒:core/geometry 的 elementBounds(文字按真播放器量出来的字宽表;元素带的 width 更宽以它为准)。
+ * snap 的元素清单、build 落进 scene.json 的 bounds 都是这一份。
+ */
+export function bboxOf(el) {
+    return { id: el.id, ...elementBounds(el) };
+}
+/** 近似测量留 2px 容差 */
+function intersects(a, b, margin = 2) {
+    return a.minX + margin < b.maxX - margin && b.minX + margin < a.maxX - margin && a.minY + margin < b.maxY - margin && b.minY + margin < a.maxY - margin;
+}
+/**
+ * 一幅画面的布局检查;主场景与每个子场景各自独立的坐标系,分开跑,互不误报。
+ * together(i, j):两个元素同时在画面上过没有(擦掉一个再写另一个、在两块画板上,叠在一处不算错);缺省 = 总在一起
+ */
+function lintLayoutOf(skeletons, findings, ctx = '', together = () => true) {
+    const textBoxes = skeletons.filter((e) => e.type === 'text').map(bboxOf);
+    for (let i = 0; i < textBoxes.length; i++) {
+        for (let j = i + 1; j < textBoxes.length; j++) {
+            if (intersects(textBoxes[i], textBoxes[j]) && together(textBoxes[i].id, textBoxes[j].id)) {
+                findings.push({
+                    level: 'error',
+                    rule: 'text-overlap',
+                    message: `${ctx}文本 '${textBoxes[i].id}' 与 '${textBoxes[j].id}' 包围盒重叠;移开其一或缩小 fontSize(近似测量,最终以 snap 截图为准)`,
+                });
+            }
+        }
+    }
+    const all = skeletons.map(bboxOf);
+    const minX = Math.min(...all.map((b) => b.minX));
+    const maxX = Math.max(...all.map((b) => b.maxX));
+    const minY = Math.min(...all.map((b) => b.minY));
+    const maxY = Math.max(...all.map((b) => b.maxY));
+    const w = maxX - minX;
+    const h = maxY - minY;
+    if (h > 0 && w / h > 5) {
+        findings.push({ level: 'warning', rule: 'aspect', message: `${ctx}画面过宽(${Math.round(w)}×${Math.round(h)});播放器等比缩放后笔画会变小,考虑分行` });
+    }
+    if (w > 0 && h / w > 3) {
+        findings.push({ level: 'warning', rule: 'aspect', message: `${ctx}画面过高(${Math.round(w)}×${Math.round(h)});播放器等比缩放后笔画会变小,考虑并列` });
+    }
+}
+function lintLayout(scene, findings) {
+    const acts = resolveActions(scene.skeletons, scene.background);
+    const drawn = scene.skeletons.filter((e) => !isAction(e));
+    // 每块画板各查各的(各自的视口);同一块上,擦掉以后才写的不算和它叠
+    const order = new Map(scene.skeletons.map((e, i) => [e.id, i]));
+    const life = (id) => [order.get(id) ?? 0, order.get(acts.erasedBy.get(id) ?? '') ?? Infinity];
+    const together = (a, b) => {
+        const [a0, a1] = life(a);
+        const [b0, b1] = life(b);
+        return a0 < b1 && b0 < a1;
+    };
+    acts.boards.forEach((board, k) => {
+        const on = drawn.filter((e) => (acts.boardOf.get(e.id) ?? 0) === k);
+        if (!on.length)
+            return;
+        lintLayoutOf(on, findings, acts.boards.length > 1 ? `画板 ${k + 1}:` : '', together);
+        // 有背景图时画板 = 图片,出界的笔迹会被裁掉
+        const bg = board.background;
+        if (bg) {
+            for (const b of on.map(bboxOf)) {
+                if (b.minX < 0 || b.minY < 0 || b.maxX > bg.width || b.maxY > bg.height) {
+                    findings.push({ level: 'warning', rule: 'background-bounds', message: `元素 '${b.id}' 超出背景图范围(0,0)–(${bg.width},${bg.height});画板即图片,图外的笔迹会被裁掉` });
+                }
+            }
+        }
+    });
+    for (const sub of scene.subscenes ?? []) {
+        lintLayoutOf(sub.skeletons, findings, `子场景 '${sub.id}' `);
+    }
+}

package/dist/chalk/circle.d.ts

@@ -0,0 +1,64 @@
+/**
+ * 圈住了什么(纯函数,浏览器外可用):孩子在课的某一刻停下,在画面上圈了一圈(场景坐标的一串点)→ 那一刻画面上已经有的东西里,哪些被圈住了。
+ * 认的顺序:分组(groups,圈住大半就说组名)> 命中块(blocks,说块的字)> 带 label 的元素 > 文字(说字)> 其余按第几步、什么、颜色归堆。
+ * circleHits 给数据,describeCircle 把它说成一句中文(「散的 3 根小棒;文字『3』」),给老师、家长看。
+ */
+import type { ChalkBlock, ChalkGroup } from './types.ts';
+import { type LessonClock } from './clock.ts';
+import { type BoundsTuple } from './geometry.ts';
+/** 画面的语义:分组、命中块、build 时量好的包围盒(都可缺) */
+export interface LessonPicture {
+    groups?: readonly ChalkGroup[];
+    blocks?: readonly ChalkBlock[];
+    bounds?: Readonly<Record<string, BoundsTuple>>;
+}
+/** 圈住的一样东西 */
+export type CircleHit = {
+    kind: 'group';
+    id: string;
+    label: string;
+    ids: string[];
+    of: number;
+} | {
+    kind: 'block';
+    id: string;
+    text: string;
+    ids: string[];
+} | {
+    kind: 'label';
+    label: string;
+    ids: string[];
+} | {
+    kind: 'text';
+    text: string;
+    ids: string[];
+} | {
+    kind: 'shapes';
+    step: number;
+    type: string;
+    color: string;
+    ids: string[];
+    nearText?: string;
+};
+export interface CircleResult {
+    /** 那一刻在第几段(0 起)、念哪句 */
+    index: number;
+    line: string;
+    /** tiny = 圈得太小看不出;hit = 圈住了东西;near = 没圈住,旁边有东西;empty = 那一带还没画东西 */
+    kind: 'tiny' | 'hit' | 'near' | 'empty';
+    hits: CircleHit[];
+    /** 没圈住时离圈最近的那样东西 */
+    near?: CircleHit;
+    /** 圈住的元素 id(全部,不论归到哪一样) */
+    ids: string[];
+}
+/** 笔画颜色 → 一个字(黑、灰、太浅的不说) */
+export declare function colorWord(hex: unknown): string;
+export declare function circleHits(clock: LessonClock, ms: number, path: readonly [number, number][], picture?: LessonPicture): CircleResult;
+/** 一样东西说成几个字 */
+export declare function hitPhrase(h: CircleHit): string;
+/**
+ * 圈住了什么,说成一句:「散的 3 根小棒;文字『3』」/「没圈住东西,圈在文字『3』旁边」/「圈的地方那时还没画东西」/「圈得太小,看不出圈的是什么」。
+ * 不带时刻与讲稿(应用自己拼:「0:26 圈的,那时在讲『…』;」)。
+ */
+export declare function describeCircle(r: CircleResult): string;

package/dist/chalk/circle.js

@@ -0,0 +1,193 @@
+/**
+ * 圈住了什么(纯函数,浏览器外可用):孩子在课的某一刻停下,在画面上圈了一圈(场景坐标的一串点)→ 那一刻画面上已经有的东西里,哪些被圈住了。
+ * 认的顺序:分组(groups,圈住大半就说组名)> 命中块(blocks,说块的字)> 带 label 的元素 > 文字(说字)> 其余按第几步、什么、颜色归堆。
+ * circleHits 给数据,describeCircle 把它说成一句中文(「散的 3 根小棒;文字『3』」),给老师、家长看。
+ */
+import { clockAt } from "./clock.js";
+import { isAction } from "./actions.js";
+import { boundsGap, boundsOfPoints, elementBounds, insidePolygon, pointsOf, samplePoints, unionBounds } from "./geometry.js";
+/** 样点有多少在圈里算圈住了 */
+const HIT_SHARE = 0.5;
+/** 一组里圈住多少算圈住了这一组 */
+const GROUP_SHARE = 0.5;
+/** 没圈住时,离圈多近的东西算「旁边」;没字的东西「旁边写着」的字要多近(场景坐标) */
+const NEAR = 80;
+const flat = (s) => s.replace(/\s*\n\s*/g, ' ').trim();
+/** 笔画颜色 → 一个字(黑、灰、太浅的不说) */
+export function colorWord(hex) {
+    const m = typeof hex === 'string' ? /^#?([0-9a-f]{6})$/i.exec(hex.trim()) : null;
+    if (!m)
+        return '';
+    const [r, g, b] = [0, 2, 4].map((i) => parseInt(m[1].slice(i, i + 2), 16) / 255);
+    const max = Math.max(r, g, b);
+    const min = Math.min(r, g, b);
+    const l = (max + min) / 2;
+    const d = max - min;
+    const s = d === 0 ? 0 : d / (1 - Math.abs(2 * l - 1));
+    if (s < 0.3 || l < 0.15 || l > 0.92)
+        return '';
+    const h = (max === r ? ((g - b) / d + 6) % 6 : max === g ? (b - r) / d + 2 : (r - g) / d + 4) * 60;
+    return h < 15 || h >= 340 ? '红' : h < 40 ? '橙' : h < 70 ? '黄' : h < 170 ? '绿' : h < 255 ? '蓝' : '紫';
+}
+/** 点到线段的距离 */
+function segmentGap([px, py], [ax, ay], [bx, by]) {
+    const dx = bx - ax;
+    const dy = by - ay;
+    const len = dx * dx + dy * dy;
+    const t = len ? Math.max(0, Math.min(1, ((px - ax) * dx + (py - ay) * dy) / len)) : 0;
+    return Math.hypot(px - (ax + t * dx), py - (ay + t * dy));
+}
+/** 橡皮那一笔擦完了这个元素:元素画在橡皮之前,样点大半落在橡皮的笔迹里(离橡皮的线不到半个笔宽) */
+function erasedBy(eraser, e, start, clock, boundsOf) {
+    const ew = clock.elements.get(eraser.id);
+    const line = pointsOf(eraser);
+    if (!ew || start >= ew.start || !line || !line.length)
+        return false;
+    const half = (typeof eraser.strokeWidth === 'number' ? eraser.strokeWidth : 1) / 2 + 1;
+    const s = samplePoints(e, boundsOf(e));
+    const covered = (p) => (line.length === 1 ? Math.hypot(p[0] - line[0][0], p[1] - line[0][1]) <= half : line.slice(1).some((b, i) => segmentGap(p, line[i], b) <= half));
+    return s.length > 0 && s.filter(covered).length / s.length >= HIT_SHARE;
+}
+export function circleHits(clock, ms, path, picture = {}) {
+    const at = clockAt(clock, ms);
+    const base = { index: at.index, line: clock.segments[at.index]?.line ?? '' };
+    if (path.length < 3)
+        return { ...base, kind: 'tiny', hits: [], ids: [] };
+    const boundsOf = (e) => {
+        const t = picture.bounds?.[e.id];
+        return t ? { minX: t[0], minY: t[1], maxX: t[2], maxY: t[3] } : elementBounds(e);
+    };
+    // 那一刻画面上已经有的(开始画了就算;动作与橡皮笔画不算东西;擦掉了的不算:擦除动作擦完的、换画板换走的,橡皮笔画盖住大半的)
+    const erasers = clock.skeletons.filter((e) => e.customData?.tool === 'eraser' && (clock.elements.get(e.id)?.end ?? Infinity) <= at.svgMs);
+    const shown = clock.skeletons.filter((e) => {
+        const w = clock.elements.get(e.id);
+        if (w === undefined || w.start >= at.svgMs || isAction(e) || e.customData?.tool === 'eraser')
+            return false;
+        if (w.erased && w.erased.end <= at.svgMs)
+            return false;
+        return !erasers.some((x) => erasedBy(x, e, w.start, clock, boundsOf));
+    });
+    const shownIds = new Set(shown.map((e) => e.id));
+    const ring = boundsOfPoints(path);
+    const hit = shown.filter((e) => {
+        const b = boundsOf(e);
+        const s = samplePoints(e, b);
+        if (s.length && s.filter((p) => insidePolygon(path, p)).length / s.length >= HIT_SHARE)
+            return true;
+        // 长的一行字里圈了几个字:圈整个落在这行字里
+        return e.type === 'text' && ring.minX >= b.minX - 8 && ring.maxX <= b.maxX + 8 && ring.minY >= b.minY - 8 && ring.maxY <= b.maxY + 8;
+    });
+    const stepOf = (e) => clock.elements.get(e.id)?.step ?? -1;
+    const describeOne = (e) => {
+        const g = (picture.groups ?? []).find((x) => x.elementIds.includes(e.id));
+        if (typeof e.label === 'string' && e.label)
+            return { kind: 'label', label: e.label, ids: [e.id] };
+        if (g)
+            return { kind: 'group', id: g.id, label: g.label, ids: [e.id], of: g.elementIds.length };
+        if (e.type === 'text')
+            return { kind: 'text', text: flat(String(e.text ?? '')), ids: [e.id] };
+        return { kind: 'shapes', step: stepOf(e), type: String(e.type), color: colorWord(e.strokeColor), ids: [e.id] };
+    };
+    if (!hit.length) {
+        const center = { minX: (ring.minX + ring.maxX) / 2, maxX: (ring.minX + ring.maxX) / 2, minY: (ring.minY + ring.maxY) / 2, maxY: (ring.minY + ring.maxY) / 2 };
+        const near = shown
+            .map((e) => ({ e, d: boundsGap(boundsOf(e), ring), c: boundsGap(boundsOf(e), center) }))
+            .filter((x) => x.d <= NEAR)
+            .sort((a, b) => a.d - b.d || a.c - b.c)[0];
+        return near ? { ...base, kind: 'near', hits: [], near: describeOne(near.e), ids: [] } : { ...base, kind: 'empty', hits: [], ids: [] };
+    }
+    const hits = [];
+    const taken = new Set();
+    // 1. 分组:这一组画面上已经有的成员,圈住了大半 → 说组名;圈得更满的组先认,一样满先认小的(「13 根小棒」不吞掉圈满了的「散的 3 根」)
+    const hitIds = new Set(hit.map((e) => e.id));
+    const groups = (picture.groups ?? [])
+        .map((g) => {
+        const members = g.elementIds.filter((id) => shownIds.has(id));
+        const got = members.filter((id) => hitIds.has(id));
+        return { g, members, got, share: members.length ? got.length / members.length : 0 };
+    })
+        .filter((x) => x.got.length && x.share >= GROUP_SHARE)
+        .sort((a, b) => b.share - a.share || a.members.length - b.members.length);
+    for (const x of groups) {
+        const fresh = x.got.filter((id) => !taken.has(id));
+        if (!fresh.length)
+            continue;
+        fresh.forEach((id) => taken.add(id));
+        hits.push({ kind: 'group', id: x.g.id, label: x.g.label, ids: x.got, of: x.members.length });
+    }
+    // 2. 命中块:圈住了块里的字就说整个块
+    for (const b of picture.blocks ?? []) {
+        const got = b.elementIds.filter((id) => hitIds.has(id) && !taken.has(id));
+        if (!got.length)
+            continue;
+        got.forEach((id) => taken.add(id));
+        hits.push({ kind: 'block', id: b.id, text: b.text, ids: got });
+    }
+    const rest = hit.filter((e) => !taken.has(e.id));
+    // 3. 带 label 的元素(同一个 label 归一样)、文字
+    const labels = new Map();
+    for (const e of rest)
+        if (typeof e.label === 'string' && e.label)
+            labels.set(e.label, [...(labels.get(e.label) ?? []), e.id]);
+    for (const [label, ids] of labels) {
+        ids.forEach((id) => taken.add(id));
+        hits.push({ kind: 'label', label, ids });
+    }
+    for (const e of rest)
+        if (!taken.has(e.id) && e.type === 'text') {
+            taken.add(e.id);
+            hits.push({ kind: 'text', text: flat(String(e.text ?? '')), ids: [e.id] });
+        }
+    // 4. 没字的:按(第几步、什么、颜色)归堆,附上离这一堆最近、没被圈住的字
+    const piles = new Map();
+    for (const e of rest) {
+        if (taken.has(e.id))
+            continue;
+        const k = `${stepOf(e)}|${String(e.type)}|${colorWord(e.strokeColor)}`;
+        piles.set(k, [...(piles.get(k) ?? []), e]);
+    }
+    const texts = shown.filter((e) => e.type === 'text' && !hitIds.has(e.id));
+    for (const [k, els] of piles) {
+        const [step, type, color] = k.split('|');
+        const gb = unionBounds(els.map(boundsOf));
+        const label = texts.map((t) => ({ t, d: boundsGap(boundsOf(t), gb) })).filter((x) => x.d <= NEAR / 2).sort((a, b) => a.d - b.d)[0];
+        hits.push({ kind: 'shapes', step: Number(step), type, color, ids: els.map((e) => e.id), ...(label ? { nearText: flat(String(label.t.text ?? '')) } : {}) });
+    }
+    return { ...base, kind: 'hit', hits, ids: hit.map((e) => e.id) };
+}
+const SHAPE_WORD = { line: ['条', '线'], arrow: ['个', '箭头'], rectangle: ['个', '框'], ellipse: ['个', '圈'], diamond: ['个', '菱形'], freedraw: ['处', '笔画'], image: ['张', '图'] };
+/** 一样东西说成几个字 */
+export function hitPhrase(h) {
+    switch (h.kind) {
+        case 'group':
+            return h.ids.length < h.of ? `${h.label}(圈住了其中 ${h.ids.length} 个)` : h.label;
+        case 'block':
+            return `『${h.text}』`;
+        case 'label':
+            return h.label;
+        case 'text':
+            return `文字『${h.text}』`;
+        case 'shapes': {
+            const [m, noun] = SHAPE_WORD[h.type] ?? ['样', '东西'];
+            const n = h.ids.length;
+            const step = h.step >= 0 ? `第 ${h.step + 1} 步画的` : '';
+            return `${step}${n > 1 ? ` ${n} ${m}` : ''}${h.color ? `${h.color}色的` : ''}${noun}${h.nearText ? `(旁边写着『${h.nearText}』)` : ''}`.trim();
+        }
+    }
+}
+/**
+ * 圈住了什么,说成一句:「散的 3 根小棒;文字『3』」/「没圈住东西,圈在文字『3』旁边」/「圈的地方那时还没画东西」/「圈得太小,看不出圈的是什么」。
+ * 不带时刻与讲稿(应用自己拼:「0:26 圈的,那时在讲『…』;」)。
+ */
+export function describeCircle(r) {
+    switch (r.kind) {
+        case 'tiny':
+            return '圈得太小,看不出圈的是什么';
+        case 'empty':
+            return '圈的地方那时还没画东西';
+        case 'near':
+            return `没圈住东西,圈在${hitPhrase(r.near)}旁边`;
+        case 'hit':
+            return `圈住了:${r.hits.map(hitPhrase).join(';')}`;
+    }
+}

package/dist/chalk/clock.d.ts

@@ -0,0 +1,84 @@
+/**
+ * 一堂课的时钟(纯函数,浏览器外可用):课包的每一步首尾相接成一条时间线,像视频一样能问「第 t 毫秒是什么样」。
+ * ChalkPlayer 是接力式(一步画完停在气口);这里不停气口——停不停是播放器的事,时钟只管时间。
+ *
+ * 一段 = 一步,段长 = max(这步画多久, 这步配音多久):画完了定格、声音接着讲;声音先完,等画完。
+ * 课的 0 毫秒对着 SVG 时间线的 START_MS(开头那一秒空白不算进课里)。笔画按配音拉伸(stretchToAudio,只拉不缩、封顶 5 倍)。
+ * 笔顺里的动作(擦掉、换画板,core/actions.ts)和画一笔一样占时间;被擦的元素记下擦它的那段时间,擦完就不在画面上了。
+ */
+import type { ChalkSkeleton, ChalkStep } from './types.ts';
+export interface LessonSegment {
+    /** 第几步(0 起,与 steps 同序) */
+    index: number;
+    /** 这一段在课里的起点与长度(毫秒) */
+    start: number;
+    len: number;
+    /** 这一步笔画在 SVG 时间线上的窗(毫秒,含 START_MS) */
+    drawStart: number;
+    drawEnd: number;
+    /** 配音时长;没有配音 = null */
+    audioMs: number | null;
+    line: string;
+    audioSrc?: string;
+}
+/** 一个元素(或动作)在 SVG 时间线上的账 */
+export interface ElementWindow {
+    /** 什么时候开始画、画完(毫秒) */
+    start: number;
+    end: number;
+    /** 第几步画的(0 起;没进任何一步 = -1) */
+    step: number;
+    /** 在第几块画板上(0 起;换画板的动作算在旧板上) */
+    board: number;
+    /** 被擦掉的那段时间(擦它的动作的窗);没被擦 = 没有 */
+    erased?: {
+        start: number;
+        end: number;
+    };
+}
+export interface LessonClock {
+    /** 拉伸后的元素(时长和这条时钟同一份数) */
+    skeletons: ChalkSkeleton[];
+    segments: LessonSegment[];
+    /** 课长(毫秒) */
+    total: number;
+    elements: Map<string, ElementWindow>;
+    /** 换画板的动作什么时候换完(毫秒,按笔顺);第 k 个换完以后是第 k + 1 块画板。可缺(应用自己拼的时钟,如视频)= 没换过 */
+    boardSwitches?: number[];
+}
+/**
+ * 课包 → 时钟。steps 的 elementIds 应按顺序覆盖全部元素(场景的约定,check 把关);
+ * 这里不抛:没对上的元素照样排进 SVG 时间线,只是不属于任何一步。durations 同 stretchToAudio(播放器探测到的配音时长)。
+ */
+export declare function lessonClock(skeletons: readonly ChalkSkeleton[], steps: readonly ChalkStep[], opts?: {
+    durations?: ReadonlyArray<number | null | undefined>;
+    maxStretch?: number;
+}): LessonClock;
+/** 课里的某一刻 → 第几段、段内多少、SVG 该停在哪(毫秒;画完了定格在窗终点前半毫秒)。越界夹到 0..total;没有步 index = -1 */
+export declare function clockAt(clock: Pick<LessonClock, 'segments' | 'total'>, ms: number): {
+    index: number;
+    offset: number;
+    svgMs: number;
+};
+/** 某一刻的元素:画了多少(0–1,开始画了就算有);正在被擦的,fade = 还剩几成(1 → 0) */
+export interface FrameElement {
+    id: string;
+    progress: number;
+    fade?: number;
+}
+/**
+ * 某一刻的画面(数据,不是图):在第几段、念哪句、SVG 停在哪、在第几块画板、画面上已经有的元素与每个画了多少。
+ * 擦完了的元素不在里面;动作(擦掉、换画板)也在里面(progress 是动作做到哪,渲染端画橡皮、算淡出用)。
+ */
+export interface LessonFrame {
+    index: number;
+    line: string;
+    svgMs: number;
+    board: number;
+    elements: FrameElement[];
+}
+export declare function frameAt(clock: LessonClock, ms: number): LessonFrame;
+/** SVG 时间线上的某一刻在第几块画板 */
+export declare function boardAtSvgTime(clock: Pick<LessonClock, 'boardSwitches'>, svgMs: number): number;
+/** SVG 时间线上的某一刻(毫秒,含 START_MS)画面上有哪些元素、各画了多少:存的是 SVG 时刻的(圈的卡的缩略图)直接用它 */
+export declare function elementsAtSvgTime(clock: Pick<LessonClock, 'elements'>, svgMs: number): FrameElement[];