cotutor 0.2.0 → 0.3.0

package/dist/chalk/glyphs/types.d.ts

@@ -0,0 +1,58 @@
+/**
+ * 字形资源包的数据面(小写拉丁字母,print 分写体)。
+ *
+ * 归一化坐标系与四线三格严格对齐(kid-canvas Write.tsx 的采集面同一套):
+ * x 高 = 1 个单位,基线 y = 0,y 向上为负。
+ *
+ *   y = -2   top      升部顶(b d f h k l t)
+ *   y = -1   xTop     x 高顶
+ *   y =  0   base     基线
+ *   y = +1   bottom   降部底(g j p q y)
+ *
+ * 每个字形自己的左边界是 x = 0,advance 是墨迹宽度(不含字间距,
+ * 字间距由排版方按 letterSpacing 给)。消费方乘 xHeight 换算成 px。
+ *
+ * 笔画顺序 = 数组顺序 = 教学笔顺;一笔之内的段首尾相接。
+ */
+/** 直线到 (x, y) */
+export interface SegLine {
+    k: 'L';
+    to: readonly [number, number];
+}
+/**
+ * 椭圆弧。参数式 x = cx + rx·cos θ、y = cy + ry·sin θ(角度制)。
+ * 屏幕坐标 y 向下为正,故 θ 递增 = 顺时针,θ 递减 = 逆时针
+ * (写 o、a、c 的圈都是逆时针,即 a1 < a0)。
+ * 弧的起点必须与前一段的终点重合,由 letters.test.ts 的连续性断言把关。
+ */
+export interface SegArc {
+    k: 'A';
+    cx: number;
+    cy: number;
+    rx: number;
+    ry: number;
+    /** 起始角(度) */
+    a0: number;
+    /** 终止角(度) */
+    a1: number;
+}
+/** 三次贝塞尔到 to,控制点 c1、c2(s、r、t 的钩这类不规则曲线用) */
+export interface SegCubic {
+    k: 'C';
+    c1: readonly [number, number];
+    c2: readonly [number, number];
+    to: readonly [number, number];
+}
+export type Seg = SegLine | SegArc | SegCubic;
+/** 一笔:从 start 起,依次走完 segs */
+export interface GlyphStroke {
+    start: readonly [number, number];
+    segs: readonly Seg[];
+}
+export interface Glyph {
+    ch: string;
+    /** 墨迹宽度(x 高为 1 单位),排版按此前进 */
+    advance: number;
+    /** 笔画序列,数组顺序即笔顺 */
+    strokes: readonly GlyphStroke[];
+}

package/dist/chalk/glyphs/types.js

@@ -0,0 +1,17 @@
+/**
+ * 字形资源包的数据面(小写拉丁字母,print 分写体)。
+ *
+ * 归一化坐标系与四线三格严格对齐(kid-canvas Write.tsx 的采集面同一套):
+ * x 高 = 1 个单位,基线 y = 0,y 向上为负。
+ *
+ *   y = -2   top      升部顶(b d f h k l t)
+ *   y = -1   xTop     x 高顶
+ *   y =  0   base     基线
+ *   y = +1   bottom   降部底(g j p q y)
+ *
+ * 每个字形自己的左边界是 x = 0,advance 是墨迹宽度(不含字间距,
+ * 字间距由排版方按 letterSpacing 给)。消费方乘 xHeight 换算成 px。
+ *
+ * 笔画顺序 = 数组顺序 = 教学笔顺;一笔之内的段首尾相接。
+ */
+export {};

package/dist/chalk/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * chalk —— 画面引擎(2026-10-31 从 drawtell 并进来,历史在 git log 里):纯计算,不碰 DOM、不带 React,服务端、命令、舞台都能 import。
+ * 时钟(课的第 t 毫秒是什么样)、几何(包围盒,文字按量好的字宽)、圈住了什么、擦掉与换画板、烤好的画面怎么逐笔露出来。
+ * 课包怎么读(parseBundle)、元素交给 excalidraw 前怎么预处理(prepareSkeletons)也在这里;场景检查在 check.ts,字母笔顺在 glyphs/。
+ * 只能在浏览器里跑的(画烤好的画面 mountBaked、用 excalidraw 烤)在 src/ui/stage/chalk/;做课包的命令在 src/app/cli/chalk/(cotutor chalk)。
+ */
+export { lessonClock, clockAt, frameAt, elementsAtSvgTime, boardAtSvgTime } from './clock.ts';
+export type { LessonClock, LessonSegment, LessonFrame, FrameElement, ElementWindow } from './clock.ts';
+export { isAction, resolveActions, finalBoard } from './actions.ts';
+export type { ResolvedActions, ResolvedBoard } from './actions.ts';
+export { charEm, measureText, elementBounds, sceneBounds, unionBounds, boundsGap, samplePoints, insidePolygon, boundsOfPoints, pointsOf } from './geometry.ts';
+export type { Bounds, BoundsTuple } from './geometry.ts';
+export { circleHits, describeCircle, hitPhrase, colorWord } from './circle.ts';
+export type { CircleHit, CircleResult, LessonPicture } from './circle.ts';
+export { BAKE_VERSION, actionState, boardOf, paintElement, renderFrameSvg, bakedPaths, strokeGroups, progressMap, pointerBox, pictureHash, bakeMatches } from './paint.ts';
+export type { ActionState, BakedBoard, BakedLesson, BakedPicture, BakedElement, BakedNode, ElementPaint, PathPaint, FrameProgress, RenderOptions } from './paint.ts';
+export { parseBundle, assembleBundle, BundleError } from './bundle.ts';
+export type { LessonBundle } from './bundle.ts';
+export { prepareSkeletons, isEraser } from './prepare.ts';
+export { CHAR_EM, CJK_EM, FALLBACK_EM, LINE_HEIGHT } from './text-metrics.ts';
+export { computeStepWindows, durationOf, freezeTimeSec, FREEZE_EPS_MS, START_MS, stretchToAudio } from './timeline.ts';
+export type { StretchInfo, StepWindow } from './timeline.ts';
+export type { ChalkScene, ChalkSkeleton, ChalkErase, ChalkBoard, ChalkStep, ChalkBlock, ChalkGroup, ChalkSubscene, ChalkBackground } from './types.ts';

package/dist/chalk/index.js

@@ -0,0 +1,15 @@
+/**
+ * chalk —— 画面引擎(2026-10-31 从 drawtell 并进来,历史在 git log 里):纯计算,不碰 DOM、不带 React,服务端、命令、舞台都能 import。
+ * 时钟(课的第 t 毫秒是什么样)、几何(包围盒,文字按量好的字宽)、圈住了什么、擦掉与换画板、烤好的画面怎么逐笔露出来。
+ * 课包怎么读(parseBundle)、元素交给 excalidraw 前怎么预处理(prepareSkeletons)也在这里;场景检查在 check.ts,字母笔顺在 glyphs/。
+ * 只能在浏览器里跑的(画烤好的画面 mountBaked、用 excalidraw 烤)在 src/ui/stage/chalk/;做课包的命令在 src/app/cli/chalk/(cotutor chalk)。
+ */
+export { lessonClock, clockAt, frameAt, elementsAtSvgTime, boardAtSvgTime } from "./clock.js";
+export { isAction, resolveActions, finalBoard } from "./actions.js";
+export { charEm, measureText, elementBounds, sceneBounds, unionBounds, boundsGap, samplePoints, insidePolygon, boundsOfPoints, pointsOf } from "./geometry.js";
+export { circleHits, describeCircle, hitPhrase, colorWord } from "./circle.js";
+export { BAKE_VERSION, actionState, boardOf, paintElement, renderFrameSvg, bakedPaths, strokeGroups, progressMap, pointerBox, pictureHash, bakeMatches } from "./paint.js";
+export { parseBundle, assembleBundle, BundleError } from "./bundle.js";
+export { prepareSkeletons, isEraser } from "./prepare.js";
+export { CHAR_EM, CJK_EM, FALLBACK_EM, LINE_HEIGHT } from "./text-metrics.js";
+export { computeStepWindows, durationOf, freezeTimeSec, FREEZE_EPS_MS, START_MS, stretchToAudio } from "./timeline.js";

package/dist/chalk/manifest.d.ts

@@ -0,0 +1,41 @@
+/**
+ * 课包(lesson bundle)输出契约 —— build 的产物,serve/播放器的输入。
+ * 自包含目录:scene.json + manifest.json(+ audio/,TTS 就绪后)。
+ * 前身是 growth-apps packages/schema 的 LessonManifestDraft,随架构重设计迁入并定版 v1。
+ */
+import type { ChalkBlock, ChalkGroup, ChalkScene, ChalkStep, ChalkSubscene } from './types.ts';
+export interface SceneJson {
+    schema: 'chalk-scene';
+    version: 1;
+    id: string;
+    title: string;
+    problem: string;
+    model: string;
+    template: ChalkScene['template'];
+    subject?: string;
+    /** 背景图;src 相对课包目录(build 拷进来的 background.<ext>) */
+    background?: ChalkScene['background'];
+    skeletons: ChalkScene['skeletons'];
+    /** 元素分组(语义);画面的一部分,所以在 scene.json 不在 manifest */
+    groups?: ChalkGroup[];
+    /**
+     * build 时量好的每个元素的包围盒(场景坐标,[minX, minY, maxX, maxY]):文字按 core/text-metrics 的字宽算,
+     * 线按点、框按宽高。浏览器外的消费方(应用的服务端、检验)不用再估;播放器不读它。
+     */
+    bounds?: Record<string, [number, number, number, number]>;
+}
+/**
+ * 切分线:scene.json = 静态画面(家长在编辑器看到的),manifest = 怎么播、怎么交互。
+ * v2 新增的 blocks(圈词命中)与 subscenes(弹窗)都是交互,随 steps 落 manifest;
+ * 子场景连几何一起整体落这里——弹窗不属于主画面,拆两半反而破坏自包含。
+ * v1 课包(无 blocks/subscenes,steps 恒非空)读取路径不变,照常可播。
+ */
+export interface LessonManifest {
+    schema: 'lesson-manifest';
+    version: 2;
+    steps: LessonStep[];
+    blocks?: ChalkBlock[];
+    subscenes?: ChalkSubscene[];
+}
+/** line 兼作字幕;audioSrc 指向课包内 audio/ 文件,audioDurationMs 是它的时长(dub 写入,与 audioSrc 同生命周期) */
+export type LessonStep = Pick<ChalkStep, 'step' | 'elementIds' | 'line' | 'pauseAfter' | 'audioSrc' | 'audioDurationMs'>;

package/dist/chalk/manifest.js

@@ -0,0 +1,6 @@
+/**
+ * 课包(lesson bundle)输出契约 —— build 的产物,serve/播放器的输入。
+ * 自包含目录:scene.json + manifest.json(+ audio/,TTS 就绪后)。
+ * 前身是 growth-apps packages/schema 的 LessonManifestDraft,随架构重设计迁入并定版 v1。
+ */
+export {};

package/dist/chalk/paint.d.ts

@@ -0,0 +1,180 @@
+/**
+ * 烤好的课包画面(bake.json,drawtell 重新设计的第 4 步):excalidraw 在 build 之后、在浏览器里只跑一次(cotutor chalk bake),
+ * 把每个元素的静态 SVG 节点、每条路径的长度、笔尖走的轨迹、内嵌字体存下来;播放时不再有 excalidraw 与 SMIL,
+ * 某一刻的画面 = 每个元素画了多少(frameAt 的 progress)→ 描边画到哪(stroke-dashoffset)、字露到哪(裁剪框)。
+ * 时长不进 bake:配音、拉伸只改时钟,画面变了才要重烤(source.hash 对不上)。
+ *
+ * 本文件纯计算:类型、一个元素在 progress p 时怎么画(paintElement)、整幅画面拼成 SVG 字符串(renderFrameSvg,服务端出缩略图用)。
+ * 浏览器里的增量渲染在 src/ui/stage/chalk/render.ts(同一份 paintElement)。
+ */
+import type { LessonFrame } from './clock.ts';
+/** 一个 SVG 节点(元素静态导出的样子,原样存属性);路径多存长度,好按描边揭示 */
+export interface BakedNode {
+    tag: string;
+    attrs: Record<string, string>;
+    /** text / tspan 的字 */
+    text?: string;
+    children?: BakedNode[];
+    /** path 的总长(SVG 坐标):有描边的路径按它揭示 */
+    len?: number;
+    /**
+     * 同一笔的第几遍:手绘(rough.js)每一笔描两遍,bake 把两遍拆成两条 path,pass 相同的一起画(同 excalidraw-animate);
+     * 没有 = 自己一拨
+     */
+    pass?: number;
+}
+export interface BakedElement {
+    id: string;
+    /** 顶层节点(excalidraw 每个元素导出成一个 <g>) */
+    node: BakedNode;
+    /** 文字的揭示框(元素局部坐标,即 <g> transform 之内):从左往右露 */
+    reveal?: {
+        width: number;
+        height: number;
+    };
+    /** 笔尖走的轨迹(SVG 坐标):[x, y, 走到这里是全程的几分之几] */
+    track: [number, number, number][];
+    /** 橡皮那一笔:笔尖换成橡皮(擦除、换画板这两种动作也是) */
+    eraser?: boolean;
+    /**
+     * 笔顺里的动作(core/actions.ts):不画东西(node 是空的 <g>),轨迹是橡皮来回走的路。
+     * erase 做的时候 targets 渐渐淡掉、做完不见;board 一样擦掉 targets(旧板上的全部),做完换到下一块画板
+     */
+    action?: 'erase' | 'board';
+    targets?: string[];
+}
+/** 一块画板:自己的视口(SVG 坐标)与背景图 */
+export interface BakedBoard {
+    viewBox: [number, number, number, number];
+    background?: {
+        src: string;
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+}
+/**
+ * bake.json 的格式版本;画法变了就加一,旧的一律当没烤(应用后台重烤、snap 顺手重烤)。
+ * 2(2026-10-07):手绘一笔的两遍拆成两条 path、记 pass,一起画——1 的两遍先后画,笔画完一遍跳回起点再画,看着像抖
+ */
+export declare const BAKE_VERSION = 2;
+export interface BakedLesson {
+    /** 格式名照旧(并进 cotutor 之前就是它):改了已经烤好的课包全都要重烤 */
+    schema: 'drawtell-bake';
+    version: typeof BAKE_VERSION;
+    /** 烤它的 excalidraw 版本、画面的 hash(scene.json 的 skeletons 与 background;变了要重烤) */
+    source: {
+        excalidraw: string;
+        hash: string;
+    };
+    viewBox: [number, number, number, number];
+    /** 场景坐标 → SVG 坐标的平移(导出时留了白、整体挪过) */
+    offset: [number, number];
+    /** 导出时内嵌的字体(@font-face,data URI) */
+    fonts: string;
+    /** <defs> 里字体以外的东西(箭头的遮罩之类),原样 */
+    defs: string;
+    /** 背景图:src 相对课包目录,x/y/width/height 是 SVG 坐标 */
+    background?: {
+        src: string;
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    /**
+     * 换过画板的课才有:每块画板的视口与背景图(第 0 块 = 上面的 viewBox / background)。
+     * 所有画板的元素在同一个 SVG 坐标里(同一个 offset),换板只换视口与背景
+     */
+    boards?: BakedBoard[];
+    elements: BakedElement[];
+}
+/**
+ * 画面的指纹:scene.json 里决定画面的那几样(skeletons、background),按 JSON 原样算(FNV-1a,两路 32 位拼 16 位十六进制)。
+ * 纯 JS:播放页拿到 scene.json 与 bake.json 自己对一下,对不上(画面改过、没重烤)就别用这份烤好的。
+ */
+export declare function pictureHash(sceneJson: {
+    skeletons?: unknown;
+    background?: unknown;
+}): string;
+/** 这份烤好的画面是不是这份 scene.json 的 */
+export declare function bakeMatches(baked: unknown, sceneJson: {
+    skeletons?: unknown;
+    background?: unknown;
+}): baked is BakedLesson;
+/** 只要画面(不管是哪个 excalidraw 烤的、对的哪份画面):播放与出图只用到这些 */
+export type BakedPicture = Omit<BakedLesson, 'source'>;
+/** 一条路径在 progress p 时的样子 */
+export interface PathPaint {
+    /** 描边揭示:dasharray = len,dashoffset = len × (1 − 画了多少);全画完 = 不设 */
+    dash?: {
+        len: number;
+        offset: number;
+    };
+    /** 没法描边揭示的(实心填充、虚线):淡入 */
+    opacity?: number;
+}
+/** 一个元素在 progress p 时的样子:visible = 开始画了;paths 按深度优先的顺序对着元素里的每条 path;clip = 文字露出的宽 */
+export interface ElementPaint {
+    visible: boolean;
+    done: boolean;
+    paths: PathPaint[];
+    clip?: number;
+    /** 笔尖在哪(SVG 坐标);没在画 = 没有 */
+    pointer?: [number, number];
+}
+/** 元素里的 path,深度优先;stroke 继承父节点 */
+export declare function bakedPaths(node: BakedNode): {
+    node: BakedNode;
+    stroke: boolean;
+    dashed: boolean;
+}[];
+/** 有描边的路径分拨:pass 相同、挨着的一拨一起画,拨与拨首尾相接;一拨的长度取最长的那条 */
+export declare function strokeGroups(paths: readonly {
+    node: BakedNode;
+    stroke: boolean;
+}[]): {
+    idx: number[];
+    len: number;
+}[];
+export declare function paintElement(el: BakedElement, p: number): ElementPaint;
+/** 一刻的进度:frameAt 的结果(或只有 elements 的,如 { elements: elementsAtSvgTime(…) }),或 id → progress */
+export type FrameProgress = Pick<LessonFrame, 'elements'> | ReadonlyMap<string, number>;
+export declare function progressMap(frame: FrameProgress): ReadonlyMap<string, number>;
+/**
+ * 动作做到哪,画面就怎样(只看 progress,渲染端各自算,和 core 的时钟同一个规矩):
+ * 在第几块画板(做完了几个换画板);谁正在被擦(还剩几成)、谁擦完了(0);旧板的背景图跟着淡掉。
+ */
+export interface ActionState {
+    board: number;
+    /** 当前画板背景图的不透明度(换画板做着的时候 1 → 0) */
+    backgroundOpacity: number;
+    /** 被擦的元素 → 还剩几成(0 = 擦完了,不画);不在里面 = 没在擦 */
+    fade: Map<string, number>;
+}
+export declare function actionState(baked: Pick<BakedPicture, 'elements'>, prog: ReadonlyMap<string, number>): ActionState;
+/** 第 k 块画板的视口与背景图(没换过画板的课只有第 0 块) */
+export declare function boardOf(baked: Pick<BakedPicture, 'viewBox' | 'background' | 'boards'>, k: number): BakedBoard;
+export interface RenderOptions {
+    /** 背景图的 URL(bake 里存的是相对课包目录的 src;服务端给 /api/bundles/<id>/…);只管第 0 块画板,换过画板的课用 assetHref */
+    backgroundHref?: string;
+    /** 课包里的文件(背景图的 src)→ URL;给了就用它,每块画板的背景图都能出 */
+    assetHref?: (src: string) => string | undefined;
+    /** 再叠一层(圈的卡:孩子的圈);SVG 坐标 */
+    overlay?: string;
+    /** 画不画笔尖(铅笔;橡皮那一笔是橡皮);缺省不画 */
+    pointer?: boolean;
+}
+/**
+ * 整幅画面在这一刻的 SVG 字符串(服务端出缩略图、测试用):没开始画的元素不出,画到一半的按 paintElement 揭示。
+ * 字体原样内嵌,<img> 里也显示得对。
+ */
+export declare function renderFrameSvg(baked: BakedPicture, frame: FrameProgress, opts?: RenderOptions): string;
+/** 笔尖:铅笔的尖在图片 (0,0);橡皮的擦除端在 (5,5)(pointer.ts) */
+export declare function pointerBox(at: readonly [number, number], eraser: boolean): {
+    href: string;
+    x: number;
+    y: number;
+    size: number;
+};

package/dist/chalk/paint.js

@@ -0,0 +1,210 @@
+/**
+ * 烤好的课包画面(bake.json,drawtell 重新设计的第 4 步):excalidraw 在 build 之后、在浏览器里只跑一次(cotutor chalk bake),
+ * 把每个元素的静态 SVG 节点、每条路径的长度、笔尖走的轨迹、内嵌字体存下来;播放时不再有 excalidraw 与 SMIL,
+ * 某一刻的画面 = 每个元素画了多少(frameAt 的 progress)→ 描边画到哪(stroke-dashoffset)、字露到哪(裁剪框)。
+ * 时长不进 bake:配音、拉伸只改时钟,画面变了才要重烤(source.hash 对不上)。
+ *
+ * 本文件纯计算:类型、一个元素在 progress p 时怎么画(paintElement)、整幅画面拼成 SVG 字符串(renderFrameSvg,服务端出缩略图用)。
+ * 浏览器里的增量渲染在 src/ui/stage/chalk/render.ts(同一份 paintElement)。
+ */
+import { DEFAULT_POINTER_IMG, ERASER_POINTER_IMG } from "./pointer.js";
+/**
+ * bake.json 的格式版本;画法变了就加一,旧的一律当没烤(应用后台重烤、snap 顺手重烤)。
+ * 2(2026-10-07):手绘一笔的两遍拆成两条 path、记 pass,一起画——1 的两遍先后画,笔画完一遍跳回起点再画,看着像抖
+ */
+export const BAKE_VERSION = 2;
+/**
+ * 画面的指纹:scene.json 里决定画面的那几样(skeletons、background),按 JSON 原样算(FNV-1a,两路 32 位拼 16 位十六进制)。
+ * 纯 JS:播放页拿到 scene.json 与 bake.json 自己对一下,对不上(画面改过、没重烤)就别用这份烤好的。
+ */
+export function pictureHash(sceneJson) {
+    const s = JSON.stringify({ skeletons: sceneJson.skeletons ?? [], background: sceneJson.background ?? null });
+    let a = 0x811c9dc5;
+    let b = 0x01000193 ^ s.length;
+    for (let i = 0; i < s.length; i++) {
+        const c = s.charCodeAt(i);
+        a = Math.imul(a ^ c, 0x01000193) >>> 0;
+        b = Math.imul(b ^ c, 0x5bd1e995) >>> 0;
+    }
+    return a.toString(16).padStart(8, '0') + b.toString(16).padStart(8, '0');
+}
+/** 这份烤好的画面是不是这份 scene.json 的 */
+export function bakeMatches(baked, sceneJson) {
+    const b = baked;
+    return Boolean(b && b.schema === 'drawtell-bake' && b.version === BAKE_VERSION && b.source?.hash === pictureHash(sceneJson));
+}
+const isNone = (v) => v === undefined || v === 'none' || v === 'transparent' || v === '';
+/** 元素里的 path,深度优先;stroke 继承父节点 */
+export function bakedPaths(node) {
+    const out = [];
+    const walk = (n, stroke, dash) => {
+        const s = n.attrs.stroke ?? stroke;
+        const d = n.attrs['stroke-dasharray'] ?? dash;
+        if (n.tag === 'path')
+            out.push({ node: n, stroke: !isNone(s) && (n.len ?? 0) > 0, dashed: !isNone(d) });
+        for (const c of n.children ?? [])
+            walk(c, s, d);
+    };
+    walk(node, undefined, undefined);
+    return out;
+}
+/** 有描边的路径分拨:pass 相同、挨着的一拨一起画,拨与拨首尾相接;一拨的长度取最长的那条 */
+export function strokeGroups(paths) {
+    const out = [];
+    paths.forEach((x, i) => {
+        if (!x.stroke)
+            return;
+        const last = out[out.length - 1];
+        const prev = last ? paths[last.idx[last.idx.length - 1]] : undefined;
+        if (last && x.node.pass !== undefined && last.pass === x.node.pass && prev && last.idx[last.idx.length - 1] === i - 1) {
+            last.idx.push(i);
+            last.len = Math.max(last.len, x.node.len ?? 0);
+        }
+        else
+            out.push({ idx: [i], len: x.node.len ?? 0, ...(x.node.pass !== undefined ? { pass: x.node.pass } : {}) });
+    });
+    return out.map(({ idx, len }) => ({ idx, len }));
+}
+/** 实心填充(没法描边揭示)从 progress 多少开始淡入 */
+const FILL_FROM = 0.7;
+/** 画到多少以后笔尖收起 */
+const POINTER_UNTIL = 0.99;
+const clamp01 = (x) => Math.max(0, Math.min(1, x));
+export function paintElement(el, p) {
+    const paths = bakedPaths(el.node);
+    if (!(p > 0))
+        return { visible: false, done: false, paths: paths.map(() => ({})) };
+    const done = p >= 1;
+    if (done)
+        return { visible: true, done: true, paths: paths.map(() => ({})), ...(el.reveal ? { clip: el.reveal.width } : {}) };
+    // 有描边的路径(虚线也算)一拨一拨首尾相接,同一拨(同一笔的两遍)一起画;虚线没法描边揭示,轮到它就整条出现;
+    // 还没轮到的整条藏起来(round 线帽画零长的虚线会露一个点);实心填充最后一段淡入
+    const groups = strokeGroups(paths);
+    const total = groups.reduce((a, g) => a + g.len, 0);
+    const drawn = p * total;
+    const paints = paths.map(() => ({ opacity: total > 0 ? clamp01((p - FILL_FROM) / (1 - FILL_FROM)) : p }));
+    let at = 0;
+    for (const g of groups) {
+        const q = g.len > 0 ? clamp01((drawn - at) / g.len) : 1;
+        at += g.len;
+        for (const i of g.idx) {
+            const len = paths[i].node.len;
+            paints[i] = q <= 0 ? { opacity: 0 } : paths[i].dashed ? {} : q >= 1 ? {} : { dash: { len, offset: len * (1 - q) } };
+        }
+    }
+    // 笔尖只在真画着的时候出现:步尾定格停在画完前半毫秒(p ≈ 0.999),笔不该杵在那儿
+    return { visible: true, done: false, paths: paints, ...(el.reveal ? { clip: el.reveal.width * p } : {}), ...(p < POINTER_UNTIL ? (trackAt(el.track, p) ?? {}) : {}) };
+}
+/** 笔尖:轨迹上走到 p 的那一点 */
+function trackAt(track, p) {
+    if (!track.length)
+        return null;
+    let i = track.findIndex((t) => t[2] >= p);
+    if (i < 0)
+        i = track.length - 1;
+    if (i === 0)
+        return { pointer: [track[0][0], track[0][1]] };
+    const [x0, y0, f0] = track[i - 1];
+    const [x1, y1, f1] = track[i];
+    const k = f1 > f0 ? (p - f0) / (f1 - f0) : 1;
+    return { pointer: [x0 + (x1 - x0) * k, y0 + (y1 - y0) * k] };
+}
+export function progressMap(frame) {
+    return 'elements' in frame ? new Map(frame.elements.map((e) => [e.id, e.progress])) : frame;
+}
+export function actionState(baked, prog) {
+    let board = 0;
+    let backgroundOpacity = 1;
+    const fade = new Map();
+    for (const el of baked.elements) {
+        if (!el.action)
+            continue;
+        const p = prog.get(el.id) ?? 0;
+        if (!(p > 0))
+            continue;
+        const left = p >= 1 ? 0 : 1 - p;
+        for (const id of el.targets ?? [])
+            fade.set(id, Math.min(fade.get(id) ?? 1, left));
+        if (el.action === 'board') {
+            if (p >= 1) {
+                board++;
+                backgroundOpacity = 1;
+            }
+            else
+                backgroundOpacity = left;
+        }
+    }
+    return { board, backgroundOpacity, fade };
+}
+/** 第 k 块画板的视口与背景图(没换过画板的课只有第 0 块) */
+export function boardOf(baked, k) {
+    const b = baked.boards?.[k];
+    if (b)
+        return b;
+    return { viewBox: baked.viewBox, ...(baked.background ? { background: baked.background } : {}) };
+}
+const esc = (s) => s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+const attrText = (attrs) => Object.entries(attrs).map(([k, v]) => ` ${k}="${esc(v)}"`).join('');
+function nodeSvg(n, paintOf) {
+    const pp = paintOf.get(n);
+    const extra = {};
+    if (pp?.dash) {
+        extra['stroke-dasharray'] = `${round(pp.dash.len)} ${round(pp.dash.len)}`;
+        extra['stroke-dashoffset'] = String(round(pp.dash.offset));
+    }
+    if (pp?.opacity !== undefined && pp.opacity < 1)
+        extra.opacity = String(round(pp.opacity));
+    const inner = `${n.text !== undefined ? esc(n.text) : ''}${(n.children ?? []).map((c) => nodeSvg(c, paintOf)).join('')}`;
+    return `<${n.tag}${attrText({ ...n.attrs, ...extra })}>${inner}</${n.tag}>`;
+}
+const round = (n) => Math.round(n * 100) / 100;
+/**
+ * 整幅画面在这一刻的 SVG 字符串(服务端出缩略图、测试用):没开始画的元素不出,画到一半的按 paintElement 揭示。
+ * 字体原样内嵌,<img> 里也显示得对。
+ */
+export function renderFrameSvg(baked, frame, opts = {}) {
+    const prog = progressMap(frame);
+    const act = actionState(baked, prog);
+    const board = boardOf(baked, act.board);
+    const [vx, vy, vw, vh] = board.viewBox;
+    const clips = [];
+    const body = [];
+    let pointer;
+    for (const el of baked.elements) {
+        const left = act.fade.get(el.id) ?? 1;
+        if (!(left > 0))
+            continue;
+        const pnt = paintElement(el, prog.get(el.id) ?? 0);
+        if (!pnt.visible)
+            continue;
+        const at = body.length;
+        const paths = bakedPaths(el.node);
+        const paintOf = new Map(paths.map((x, i) => [x.node, pnt.paths[i]]));
+        if (pnt.clip !== undefined && !pnt.done && el.reveal) {
+            const cid = `clip-${el.id}`;
+            clips.push(`<clipPath id="${esc(cid)}"><rect x="-2" y="${round(-el.reveal.height * 0.5)}" width="${round(pnt.clip + 2)}" height="${round(el.reveal.height * 2)}"/></clipPath>`);
+            const { tag, attrs, children, text } = el.node;
+            body.push(`<${tag}${attrText(attrs)}><g clip-path="url(#${esc(cid)})">${text !== undefined ? esc(text) : ''}${(children ?? []).map((c) => nodeSvg(c, paintOf)).join('')}</g></${tag}>`);
+        }
+        else
+            body.push(nodeSvg(el.node, paintOf));
+        if (left < 1)
+            body[at] = `<g opacity="${round(left)}">${body[at]}</g>`;
+        if (pnt.pointer && !pnt.done)
+            pointer = { at: pnt.pointer, eraser: Boolean(el.eraser) };
+    }
+    const b = board.background;
+    const href = b ? (opts.assetHref ? opts.assetHref(b.src) : act.board === 0 ? opts.backgroundHref : undefined) : undefined;
+    const bgOpacity = act.backgroundOpacity < 1 ? ` opacity="${round(act.backgroundOpacity)}"` : '';
+    const bg = b && href ? `<image href="${esc(href)}" x="${b.x}" y="${b.y}" width="${b.width}" height="${b.height}" preserveAspectRatio="none"${bgOpacity}/>` : '';
+    const pen = opts.pointer && pointer ? pointerSvg(pointer.at, pointer.eraser) : '';
+    return `<svg xmlns="http://www.w3.org/2000/svg" viewBox="${vx} ${vy} ${vw} ${vh}"><defs><style>${baked.fonts}</style>${baked.defs}${clips.join('')}</defs>${bg}${body.join('')}${opts.overlay ?? ''}${pen}</svg>`;
+}
+/** 笔尖:铅笔的尖在图片 (0,0);橡皮的擦除端在 (5,5)(pointer.ts) */
+export function pointerBox(at, eraser) {
+    return eraser ? { href: ERASER_POINTER_IMG, x: at[0] - 5, y: at[1] - 5, size: 36 } : { href: DEFAULT_POINTER_IMG, x: at[0], y: at[1], size: 30 };
+}
+function pointerSvg(at, eraser) {
+    const b = pointerBox(at, eraser);
+    return `<image href="${esc(b.href)}" x="${round(b.x)}" y="${round(b.y)}" width="${b.size}" height="${b.size}"/>`;
+}

package/dist/chalk/pointer.d.ts

@@ -0,0 +1,8 @@
+/**
+ * 默认笔尖:内联 SVG 铅笔,笔尖落在图片 (0,0)——animateMotion 沿路径移动的是图片原点。
+ * 视觉与 kid-canvas 的铅笔单工具呼应;粉笔味交给纸面配色。
+ */
+export declare const ERASER_POINTER_IMG: string;
+/** 纸面底色:与 chalk-player.css 的 .chalk-stage 同值;橡皮笔画缺省用它盖住旧笔迹 */
+export declare const PAPER_COLOR = "#fffdf7";
+export declare const DEFAULT_POINTER_IMG: string;

package/dist/chalk/pointer.js

@@ -0,0 +1,21 @@
+/**
+ * 默认笔尖:内联 SVG 铅笔,笔尖落在图片 (0,0)——animateMotion 沿路径移动的是图片原点。
+ * 视觉与 kid-canvas 的铅笔单工具呼应;粉笔味交给纸面配色。
+ */
+const PENCIL_SVG = `<svg xmlns="http://www.w3.org/2000/svg" width="30" height="30" viewBox="0 0 30 30">
+  <g>
+    <polygon points="0,0 9,3 3,9" fill="#4a4a4a"/>
+    <rect x="5" y="1" width="22" height="8" rx="2" fill="#f2b634" stroke="#b98a2e" stroke-width="1" transform="rotate(45 5 1)"/>
+  </g>
+</svg>`;
+/** 橡皮:擦除端的中点落在图片 (5,5),由 excalidraw-io 用 x/y = -5 对回路径 */
+const ERASER_SVG = `<svg xmlns="http://www.w3.org/2000/svg" width="36" height="36" viewBox="0 0 36 36">
+  <g transform="translate(5 5) rotate(45)">
+    <rect x="0" y="-6" width="30" height="12" rx="2.5" fill="#f6a5b4" stroke="#c2687a" stroke-width="1"/>
+    <rect x="11" y="-6" width="19" height="12" rx="1.5" fill="#4c7fd0" stroke="#345a9c" stroke-width="1"/>
+  </g>
+</svg>`;
+export const ERASER_POINTER_IMG = `data:image/svg+xml,${encodeURIComponent(ERASER_SVG)}`;
+/** 纸面底色:与 chalk-player.css 的 .chalk-stage 同值;橡皮笔画缺省用它盖住旧笔迹 */
+export const PAPER_COLOR = '#fffdf7';
+export const DEFAULT_POINTER_IMG = `data:image/svg+xml,${encodeURIComponent(PENCIL_SVG)}`;

package/dist/chalk/prepare.d.ts

@@ -0,0 +1,11 @@
+/**
+ * 场景元素交给 excalidraw 之前的预处理(纯函数,不 import excalidraw):
+ * 没给 seed 的按 id 派生(手绘抖动每次一样),橡皮笔画补纸色、不抖。
+ * bake 用它;应用把课包放进 excalidraw 编辑器(画板的底图)也该先过它,否则橡皮成了一道黑线、抖动每次不一样。
+ */
+import type { ChalkSkeleton } from './types.ts';
+export declare const isEraser: (el: {
+    customData?: unknown;
+}) => boolean;
+/** 稳定 seed + 橡皮的缺省外观;作者显式给的值优先 */
+export declare function prepareSkeletons<T extends ChalkSkeleton>(skeletons: readonly T[]): T[];

package/dist/chalk/prepare.js

@@ -0,0 +1,15 @@
+/**
+ * 场景元素交给 excalidraw 之前的预处理(纯函数,不 import excalidraw):
+ * 没给 seed 的按 id 派生(手绘抖动每次一样),橡皮笔画补纸色、不抖。
+ * bake 用它;应用把课包放进 excalidraw 编辑器(画板的底图)也该先过它,否则橡皮成了一道黑线、抖动每次不一样。
+ */
+import { PAPER_COLOR } from "./pointer.js";
+import { seedFromId } from "./seed.js";
+export const isEraser = (el) => el.customData?.tool === 'eraser';
+/** 稳定 seed + 橡皮的缺省外观;作者显式给的值优先 */
+export function prepareSkeletons(skeletons) {
+    return skeletons.map((el) => {
+        const withSeed = typeof el.seed === 'number' ? el : { ...el, seed: seedFromId(el.id) };
+        return isEraser(el) ? { strokeColor: PAPER_COLOR, roughness: 0, ...withSeed } : withSeed;
+    });
+}