cotutor 0.2.0 → 0.4.0

package/dist/chalk/glyphs/skeleton.js

@@ -0,0 +1,126 @@
+/**
+ * 字形 → ChalkSkeleton(freedraw),一笔一个元素、数组顺序即笔顺。
+ *
+ * 这里封掉两个实测出来的坑,消费方不必知道:
+ * 1. freedraw 走 convertToExcalidrawElements 是**原样透传**的(不像 rectangle/text
+ *    走工厂补默认值),groupIds 等字段缺一个,animateSvg 的 createGroups 就会
+ *    在 NodeList.forEach 里炸 "Cannot read properties of undefined"。故 FREEDRAW_BASE
+ *    把整套字段给全。
+ * 2. freedraw 的 strokeWidth 会被 perfect-freehand 放大,视觉粗细约是 strokeWidth 的 4 倍。
+ *    默认 xHeight/30 是**量出来的**:Excalifont 的竖笔画粗细 = 0.20×x 高(canvas 像素扫描
+ *    取行游程中位数),字形包要与它同重量才不会在同一块黑板上一个轻一个重。
+ * 3. simulatePressure 必须关。开着时 perfect-freehand 拿点间距当书写速度反推压力,
+ *    于是**采样越密笔画越粗**——sampleStep 本该只是性能旋钮,却会改变字的视觉。
+ *    关掉并显式给一条恒定 pressures,字形粗细就只由 strokeWidth 决定。
+ */
+import { GLYPHS } from "./registry.js";
+import { sampleStroke, strokeLength } from "./sample.js";
+/** freedraw 透传所需的完整字段(见文件头坑 1) */
+const FREEDRAW_BASE = {
+    angle: 0,
+    backgroundColor: 'transparent',
+    fillStyle: 'solid',
+    strokeStyle: 'solid',
+    /** 字形要的是干净笔迹,不要 roughjs 抖动 */
+    roughness: 0,
+    opacity: 100,
+    roundness: null,
+    groupIds: [],
+    frameId: null,
+    boundElements: null,
+    updated: 1,
+    link: null,
+    locked: false,
+    isDeleted: false,
+    version: 1,
+    versionNonce: 1,
+    // 见文件头坑 3:压力恒定,笔画粗细与采样密度解耦
+    simulatePressure: false,
+};
+const DEFAULTS = { msPerUnit: 200, minStrokeMs: 90, letterSpacing: 0.22, idPrefix: 'g' };
+/** 空格的前进宽度(x 高为 1 单位):不产生笔画,只让光标走一段 */
+export const SPACE_ADVANCE = 0.55;
+/** 字形表未收录的字符:由调用方决定回退,这里不猜 */
+export class UnknownGlyphError extends Error {
+    /** node 的 strip-only 类型擦除不支持构造函数参数属性,字段显式声明 */
+    ch;
+    constructor(ch) {
+        super(`字形表未收录 '${ch}'。内置包只有 a–z 与 A–Z;别的字形做成同构的 Map 经 glyphs 选项传入。`);
+        this.ch = ch;
+    }
+}
+function strokeSkeleton(pts, id, ms, o) {
+    // excalidraw 的 freedraw 约定:x/y 是落笔点,points 相对它、首点 [0,0](可有负值),
+    // width/height 是 points 的 extent。照它的约定走,少踩版本升级的坑。
+    const [ox, oy] = pts[0];
+    const xs = pts.map((p) => p[0] - ox);
+    const ys = pts.map((p) => p[1] - oy);
+    return {
+        ...FREEDRAW_BASE,
+        type: 'freedraw',
+        id,
+        animateDuration: ms,
+        x: ox,
+        y: oy,
+        width: Math.max(...xs) - Math.min(...xs),
+        height: Math.max(...ys) - Math.min(...ys),
+        points: pts.map((_, i) => [xs[i], ys[i]]),
+        // 长度须与 points 对齐;恒定值 = 均匀笔迹(字形不要手写的粗细起伏)
+        pressures: pts.map(() => 0.5),
+        strokeColor: o.strokeColor ?? '#1e1e1e',
+        strokeWidth: o.strokeWidth ?? o.xHeight / 30,
+    };
+}
+/**
+ * 单个字母(大小写皆可)→ 一笔一个 freedraw 元素。
+ * 返回顺序即笔顺,可直接铺进 scene.skeletons / 交给 buildAnimatedSvg。
+ */
+export function glyphSkeletons(ch, o) {
+    const glyph = (o.glyphs ?? GLYPHS).get(ch);
+    if (!glyph)
+        throw new UnknownGlyphError(ch);
+    const msPerUnit = o.msPerUnit ?? DEFAULTS.msPerUnit;
+    const minMs = o.minStrokeMs ?? DEFAULTS.minStrokeMs;
+    const prefix = o.idPrefix ?? DEFAULTS.idPrefix;
+    return glyph.strokes.map((st, i) => {
+        const pts = sampleStroke(st, o.sampleStep).map(([nx, ny]) => [o.x + nx * o.xHeight, o.y + ny * o.xHeight]);
+        const ms = Math.max(minMs, Math.round(strokeLength(st) * msPerUnit));
+        return strokeSkeleton(pts, `${prefix}-${ch}-${i + 1}`, ms, o);
+    });
+}
+/** 一个词的排版宽度(px),含字间距,不含末尾空隙;空格按 SPACE_ADVANCE 计 */
+export function wordAdvance(word, o) {
+    const table = o.glyphs ?? GLYPHS;
+    const gap = o.letterSpacing ?? DEFAULTS.letterSpacing;
+    let w = 0;
+    [...word].forEach((ch, i) => {
+        if (ch !== ' ' && !table.has(ch))
+            throw new UnknownGlyphError(ch);
+        w += (i > 0 ? gap : 0) + (ch === ' ' ? SPACE_ADVANCE : table.get(ch).advance);
+    });
+    return w * o.xHeight;
+}
+/**
+ * 一串字母(大小写皆可)→ 全部笔画,从左到右按 advance + letterSpacing 排;
+ * 空格只让光标前进,不产生笔画(于是 'ram man' 能一次画完,不必调用方自己拆词)。
+ * id 形如 `<prefix>-<序号><字母>-<笔序>`,同字母重复出现也不撞。
+ */
+export function wordSkeletons(word, o) {
+    const gap = (o.letterSpacing ?? DEFAULTS.letterSpacing) * o.xHeight;
+    const prefix = o.idPrefix ?? DEFAULTS.idPrefix;
+    const out = [];
+    let cursor = o.x;
+    const table = o.glyphs ?? GLYPHS;
+    [...word].forEach((ch, i) => {
+        if (ch === ' ') {
+            cursor += SPACE_ADVANCE * o.xHeight + gap;
+            return;
+        }
+        const g = table.get(ch);
+        if (!g)
+            throw new UnknownGlyphError(ch);
+        out.push(...glyphSkeletons(ch, { ...o, x: cursor, idPrefix: `${prefix}-${i + 1}` }));
+        cursor += g.advance * o.xHeight + gap;
+    });
+    return out;
+}

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;
+};