cotutor 0.2.0 → 0.4.0

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

package/dist/chalk/scene-schema.d.ts

@@ -0,0 +1,199 @@
+/**
+ * 场景契约的运行时校验(zod)。
+ * 类型真相在 src/player/types.ts,本 schema 与之对齐,文件底部用赋值断言在编译期锁住。
+ * 校验错误面向 agent:每条都要能指出改哪里(README「Design principles」)。
+ */
+import { z } from 'zod';
+/** 已在引擎(convertToExcalidrawElements + animateSvg)上验证过的元素类型 */
+export declare const KNOWN_ELEMENT_TYPES: readonly ["rectangle", "ellipse", "diamond", "line", "arrow", "text", "freedraw"];
+/** 笔顺里的动作:不画东西,改画面上已经有的(ChalkErase、ChalkBoard) */
+export declare const ACTION_TYPES: readonly ["erase", "board"];
+/** 背景图:画板 = 图片,场景坐标即图片像素 */
+export declare const backgroundSchema: z.ZodObject<{
+    src: z.ZodString;
+    width: z.ZodNumber;
+    height: z.ZodNumber;
+}, z.core.$strict>;
+/** 元素允许携带 excalidraw 的任意属性(strokeColor、points、text……),故 loose;画的元素缺 x / y 由 lint 报 */
+export declare const skeletonSchema: z.ZodObject<{
+    type: z.ZodString;
+    id: z.ZodString;
+    x: z.ZodOptional<z.ZodNumber>;
+    y: z.ZodOptional<z.ZodNumber>;
+    targets: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    background: z.ZodOptional<z.ZodObject<{
+        src: z.ZodString;
+        width: z.ZodNumber;
+        height: z.ZodNumber;
+    }, z.core.$strict>>;
+    animateDuration: z.ZodOptional<z.ZodNumber>;
+    label: z.ZodOptional<z.ZodString>;
+    customData: z.ZodOptional<z.ZodObject<{
+        layer: z.ZodOptional<z.ZodEnum<{
+            ink: "ink";
+            base: "base";
+            feedback: "feedback";
+        }>>;
+        tool: z.ZodOptional<z.ZodEnum<{
+            eraser: "eraser";
+        }>>;
+    }, z.core.$loose>>;
+}, z.core.$loose>;
+/** 步结构固定,strict 抓字段拼写错误(pauseAfer 这类) */
+export declare const stepSchema: z.ZodObject<{
+    step: z.ZodNumber;
+    elementIds: z.ZodArray<z.ZodString>;
+    line: z.ZodString;
+    pauseAfter: z.ZodBoolean;
+    audioSrc: z.ZodOptional<z.ZodString>;
+    audioDurationMs: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>;
+/** 命中块:锚在元素上(不存坐标副本);audioSrc / subsceneId 至少一个,lint 把关 */
+export declare const blockSchema: z.ZodObject<{
+    id: z.ZodString;
+    elementIds: z.ZodArray<z.ZodString>;
+    text: z.ZodString;
+    audioSrc: z.ZodOptional<z.ZodString>;
+    subsceneId: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+/** 弹窗子场景:独立坐标系的小场景,steps 可选(缺省一笔到底) */
+export declare const subsceneSchema: z.ZodObject<{
+    id: z.ZodString;
+    skeletons: z.ZodArray<z.ZodObject<{
+        type: z.ZodString;
+        id: z.ZodString;
+        x: z.ZodOptional<z.ZodNumber>;
+        y: z.ZodOptional<z.ZodNumber>;
+        targets: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        background: z.ZodOptional<z.ZodObject<{
+            src: z.ZodString;
+            width: z.ZodNumber;
+            height: z.ZodNumber;
+        }, z.core.$strict>>;
+        animateDuration: z.ZodOptional<z.ZodNumber>;
+        label: z.ZodOptional<z.ZodString>;
+        customData: z.ZodOptional<z.ZodObject<{
+            layer: z.ZodOptional<z.ZodEnum<{
+                ink: "ink";
+                base: "base";
+                feedback: "feedback";
+            }>>;
+            tool: z.ZodOptional<z.ZodEnum<{
+                eraser: "eraser";
+            }>>;
+        }, z.core.$loose>>;
+    }, z.core.$loose>>;
+    steps: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        step: z.ZodNumber;
+        elementIds: z.ZodArray<z.ZodString>;
+        line: z.ZodString;
+        pauseAfter: z.ZodBoolean;
+        audioSrc: z.ZodOptional<z.ZodString>;
+        audioDurationMs: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>>>;
+    audioSrc: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+/** 元素分组:语义,不影响画法;elementIds 都要在场景里(lint 把关) */
+export declare const groupSchema: z.ZodObject<{
+    id: z.ZodString;
+    label: z.ZodString;
+    elementIds: z.ZodArray<z.ZodString>;
+}, z.core.$strict>;
+export declare const sceneSchema: z.ZodObject<{
+    id: z.ZodString;
+    title: z.ZodString;
+    problem: z.ZodString;
+    model: z.ZodString;
+    template: z.ZodEnum<{
+        "paper-strict": "paper-strict";
+        "camera-free": "camera-free";
+        motion: "motion";
+        static: "static";
+    }>;
+    subject: z.ZodOptional<z.ZodString>;
+    background: z.ZodOptional<z.ZodObject<{
+        src: z.ZodString;
+        width: z.ZodNumber;
+        height: z.ZodNumber;
+    }, z.core.$strict>>;
+    skeletons: z.ZodArray<z.ZodObject<{
+        type: z.ZodString;
+        id: z.ZodString;
+        x: z.ZodOptional<z.ZodNumber>;
+        y: z.ZodOptional<z.ZodNumber>;
+        targets: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        background: z.ZodOptional<z.ZodObject<{
+            src: z.ZodString;
+            width: z.ZodNumber;
+            height: z.ZodNumber;
+        }, z.core.$strict>>;
+        animateDuration: z.ZodOptional<z.ZodNumber>;
+        label: z.ZodOptional<z.ZodString>;
+        customData: z.ZodOptional<z.ZodObject<{
+            layer: z.ZodOptional<z.ZodEnum<{
+                ink: "ink";
+                base: "base";
+                feedback: "feedback";
+            }>>;
+            tool: z.ZodOptional<z.ZodEnum<{
+                eraser: "eraser";
+            }>>;
+        }, z.core.$loose>>;
+    }, z.core.$loose>>;
+    groups: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        label: z.ZodString;
+        elementIds: z.ZodArray<z.ZodString>;
+    }, z.core.$strict>>>;
+    steps: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        step: z.ZodNumber;
+        elementIds: z.ZodArray<z.ZodString>;
+        line: z.ZodString;
+        pauseAfter: z.ZodBoolean;
+        audioSrc: z.ZodOptional<z.ZodString>;
+        audioDurationMs: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>>>;
+    blocks: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        elementIds: z.ZodArray<z.ZodString>;
+        text: z.ZodString;
+        audioSrc: z.ZodOptional<z.ZodString>;
+        subsceneId: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>>;
+    subscenes: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        skeletons: z.ZodArray<z.ZodObject<{
+            type: z.ZodString;
+            id: z.ZodString;
+            x: z.ZodOptional<z.ZodNumber>;
+            y: z.ZodOptional<z.ZodNumber>;
+            targets: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            background: z.ZodOptional<z.ZodObject<{
+                src: z.ZodString;
+                width: z.ZodNumber;
+                height: z.ZodNumber;
+            }, z.core.$strict>>;
+            animateDuration: z.ZodOptional<z.ZodNumber>;
+            label: z.ZodOptional<z.ZodString>;
+            customData: z.ZodOptional<z.ZodObject<{
+                layer: z.ZodOptional<z.ZodEnum<{
+                    ink: "ink";
+                    base: "base";
+                    feedback: "feedback";
+                }>>;
+                tool: z.ZodOptional<z.ZodEnum<{
+                    eraser: "eraser";
+                }>>;
+            }, z.core.$loose>>;
+        }, z.core.$loose>>;
+        steps: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            step: z.ZodNumber;
+            elementIds: z.ZodArray<z.ZodString>;
+            line: z.ZodString;
+            pauseAfter: z.ZodBoolean;
+            audioSrc: z.ZodOptional<z.ZodString>;
+            audioDurationMs: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strict>>>;
+        audioSrc: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>>;
+}, z.core.$strict>;

package/dist/chalk/scene-schema.js

@@ -0,0 +1,91 @@
+/**
+ * 场景契约的运行时校验(zod)。
+ * 类型真相在 src/player/types.ts,本 schema 与之对齐,文件底部用赋值断言在编译期锁住。
+ * 校验错误面向 agent:每条都要能指出改哪里(README「Design principles」)。
+ */
+import { z } from 'zod';
+/** 已在引擎(convertToExcalidrawElements + animateSvg)上验证过的元素类型 */
+export const KNOWN_ELEMENT_TYPES = [
+    'rectangle',
+    'ellipse',
+    'diamond',
+    'line',
+    'arrow',
+    'text',
+    'freedraw',
+];
+/** 笔顺里的动作:不画东西,改画面上已经有的(ChalkErase、ChalkBoard) */
+export const ACTION_TYPES = ['erase', 'board'];
+/** 背景图:画板 = 图片,场景坐标即图片像素 */
+export const backgroundSchema = z.strictObject({
+    src: z.string().min(1),
+    width: z.number().positive(),
+    height: z.number().positive(),
+});
+/** 元素允许携带 excalidraw 的任意属性(strokeColor、points、text……),故 loose;画的元素缺 x / y 由 lint 报 */
+export const skeletonSchema = z.looseObject({
+    type: z.string().min(1),
+    id: z.string().min(1),
+    x: z.number().optional(),
+    y: z.number().optional(),
+    // 动作的字段:erase 的 targets、board 的 background;用在别的类型上 lint 报
+    targets: z.array(z.string().min(1)).min(1).optional(),
+    background: backgroundSchema.optional(),
+    animateDuration: z.number().int().positive().optional(),
+    // customData 透传 excalidraw,协议认领 layer(三层墨迹契约)与 tool(橡皮)两个键
+    label: z.string().min(1).optional(),
+    customData: z
+        .looseObject({
+        layer: z.enum(['base', 'ink', 'feedback']).optional(),
+        tool: z.enum(['eraser']).optional(),
+    })
+        .optional(),
+});
+/** 步结构固定,strict 抓字段拼写错误(pauseAfer 这类) */
+export const stepSchema = z.strictObject({
+    step: z.number().int().min(1),
+    elementIds: z.array(z.string().min(1)).min(1),
+    line: z.string().min(1),
+    pauseAfter: z.boolean(),
+    audioSrc: z.string().min(1).optional(),
+    audioDurationMs: z.number().positive().optional(),
+});
+/** 命中块:锚在元素上(不存坐标副本);audioSrc / subsceneId 至少一个,lint 把关 */
+export const blockSchema = z.strictObject({
+    id: z.string().min(1),
+    elementIds: z.array(z.string().min(1)).min(1),
+    text: z.string().min(1),
+    audioSrc: z.string().min(1).optional(),
+    subsceneId: z.string().min(1).optional(),
+});
+/** 弹窗子场景:独立坐标系的小场景,steps 可选(缺省一笔到底) */
+export const subsceneSchema = z.strictObject({
+    id: z.string().min(1),
+    skeletons: z.array(skeletonSchema).min(1),
+    steps: z.array(stepSchema).optional(),
+    audioSrc: z.string().min(1).optional(),
+});
+/** 元素分组:语义,不影响画法;elementIds 都要在场景里(lint 把关) */
+export const groupSchema = z.strictObject({
+    id: z.string().min(1),
+    label: z.string().min(1),
+    elementIds: z.array(z.string().min(1)).min(1),
+});
+export const sceneSchema = z.strictObject({
+    id: z.string().regex(/^[a-z0-9][a-z0-9-]*$/, 'id 用作课包目录名,只允许小写字母、数字、连字符'),
+    title: z.string().min(1),
+    problem: z.string().min(1),
+    model: z.string().min(1),
+    template: z.enum(['paper-strict', 'camera-free', 'motion', 'static']),
+    subject: z.string().min(1).optional(),
+    background: backgroundSchema.optional(),
+    skeletons: z.array(skeletonSchema).min(1),
+    groups: z.array(groupSchema).optional(),
+    // 可省略 = 静态场景;规范形是空数组。「讲解三档必须非空、static 必须空」是语义,归 lint
+    steps: z.array(stepSchema).default([]),
+    blocks: z.array(blockSchema).optional(),
+    subscenes: z.array(subsceneSchema).optional(),
+});
+// 编译期断言:zod 推导结果可赋给播放器类型,两份契约不漂移
+const assertAligned = (s) => s;
+void assertAligned;

package/dist/chalk/seed.d.ts

@@ -0,0 +1,3 @@
+/** 无 seed 的元素按 id 派生一个稳定 seed(FNV-1a):手绘抖动不再每次渲染重新随机,
+ *  bake 与 snap 可复现(重烤字节不变);作者显式给了 seed 则尊重 */
+export declare function seedFromId(id: string): number;

package/dist/chalk/seed.js

@@ -0,0 +1,10 @@
+/** 无 seed 的元素按 id 派生一个稳定 seed(FNV-1a):手绘抖动不再每次渲染重新随机,
+ *  bake 与 snap 可复现(重烤字节不变);作者显式给了 seed 则尊重 */
+export function seedFromId(id) {
+    let h = 0x811c9dc5;
+    for (let i = 0; i < id.length; i++) {
+        h ^= id.charCodeAt(i);
+        h = Math.imul(h, 0x01000193) >>> 0;
+    }
+    return (h % 2147483647) + 1;
+}

package/dist/chalk/text-metrics.d.ts

@@ -0,0 +1,8 @@
+/**
+ * 机器生成(scripts/gen-text-metrics.mjs),别手改:excalidraw 手写字体里每个字的宽(字号 1),用真播放器量的。
+ * 表里没有的:CJK 统一表意文字按 CJK_EM(量了 49 个常用字取平均,最宽最窄差 0.000),其余按 FALLBACK_EM。
+ */
+export declare const LINE_HEIGHT = 1.25;
+export declare const CJK_EM = 1;
+export declare const FALLBACK_EM = 0.55;
+export declare const CHAR_EM: Readonly<Record<string, number>>;