cotutor 0.1.0 → 0.3.0

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

package/dist/chalk/text-metrics.js

@@ -0,0 +1,156 @@
+/**
+ * 机器生成(scripts/gen-text-metrics.mjs),别手改:excalidraw 手写字体里每个字的宽(字号 1),用真播放器量的。
+ * 表里没有的:CJK 统一表意文字按 CJK_EM(量了 49 个常用字取平均,最宽最窄差 0.000),其余按 FALLBACK_EM。
+ */
+export const LINE_HEIGHT = 1.25;
+export const CJK_EM = 1;
+export const FALLBACK_EM = 0.55;
+export const CHAR_EM = {
+    "0": 0.664,
+    "1": 0.467,
+    "2": 0.7,
+    "3": 0.608,
+    "4": 0.585,
+    "5": 0.618,
+    "6": 0.64,
+    "7": 0.558,
+    "8": 0.636,
+    "9": 0.629,
+    " ": 0.4,
+    "!": 0.333,
+    "\"": 0.408,
+    "#": 0.783,
+    "$": 0.721,
+    "%": 0.928,
+    "&": 0.778,
+    "'": 0.218,
+    "(": 0.441,
+    ")": 0.402,
+    "*": 0.525,
+    "+": 0.564,
+    ",": 0.257,
+    "-": 0.411,
+    ".": 0.274,
+    "/": 0.381,
+    ":": 0.278,
+    ";": 0.298,
+    "<": 0.564,
+    "=": 0.564,
+    ">": 0.564,
+    "?": 0.466,
+    "@": 0.921,
+    "A": 0.722,
+    "B": 0.761,
+    "C": 0.667,
+    "D": 0.78,
+    "E": 0.707,
+    "F": 0.661,
+    "G": 0.78,
+    "H": 0.722,
+    "I": 0.545,
+    "J": 0.569,
+    "K": 0.722,
+    "L": 0.611,
+    "M": 0.889,
+    "N": 0.722,
+    "O": 0.767,
+    "P": 0.698,
+    "Q": 0.768,
+    "R": 0.736,
+    "S": 0.622,
+    "T": 0.857,
+    "U": 0.73,
+    "V": 0.722,
+    "W": 0.944,
+    "X": 0.722,
+    "Y": 0.722,
+    "Z": 0.832,
+    "[": 0.472,
+    "\\": 0.409,
+    "]": 0.497,
+    "^": 0.51,
+    "_": 0.67,
+    "`": 0.6,
+    "a": 0.576,
+    "b": 0.555,
+    "c": 0.504,
+    "d": 0.605,
+    "e": 0.537,
+    "f": 0.415,
+    "g": 0.555,
+    "h": 0.567,
+    "i": 0.278,
+    "j": 0.418,
+    "k": 0.533,
+    "l": 0.278,
+    "m": 0.778,
+    "n": 0.526,
+    "o": 0.6,
+    "p": 0.537,
+    "q": 0.539,
+    "r": 0.412,
+    "s": 0.543,
+    "t": 0.553,
+    "u": 0.548,
+    "v": 0.552,
+    "w": 0.722,
+    "x": 0.591,
+    "y": 0.53,
+    "z": 0.572,
+    "{": 0.504,
+    "|": 0.299,
+    "}": 0.544,
+    "~": 0.669,
+    "−": 0.564,
+    "×": 0.564,
+    "÷": 0.55,
+    "±": 0.55,
+    "→": 1,
+    "←": 1,
+    "↑": 1,
+    "↓": 1,
+    "·": 0.25,
+    "°": 0.412,
+    "²": 0.5,
+    "³": 0.5,
+    "√": 1,
+    "≈": 0.782,
+    "≠": 0.788,
+    "≤": 0.788,
+    "≥": 0.788,
+    "…": 1,
+    "—": 1,
+    "–": 0.702,
+    "○": 1,
+    "●": 1,
+    "□": 1,
+    "■": 1,
+    "△": 1,
+    "▲": 1,
+    "☆": 1,
+    "★": 1,
+    "✓": 0.764,
+    "✗": 0.571,
+    "①": 1,
+    "②": 1,
+    "③": 1,
+    "④": 1,
+    "⑤": 1,
+    "⑥": 1,
+    "⑦": 1,
+    "⑧": 1,
+    "⑨": 1,
+    "⑩": 1,
+    "。": 1,
+    "、": 1,
+    "「": 1,
+    "」": 1,
+    "『": 1,
+    "』": 1,
+    "《": 1,
+    "》": 1,
+    "“": 0.444,
+    "”": 0.444,
+    "‘": 0.267,
+    "’": 0.304
+};

package/dist/chalk/timeline.d.ts

@@ -0,0 +1,47 @@
+/**
+ * 步进时间轴:笔画按数组顺序串行,单笔时长 animateDuration(缺省 500ms),起点 START_MS(1000)。
+ * 最早是镜像 excalidraw-animate 的调度规则(0.7.2);播放改成烤好的画面 + 自己的时钟以后(drawtell 重新设计第 4 步),
+ * 这里就是时间的唯一来源:ChalkPlayer、core 的 lessonClock、应用的时钟都从这里算,规则没变,老课包的节奏不变。
+ * groupIds、id 里带 animate 指令仍然拒绝(老规矩,check 也拦)。
+ */
+import type { ChalkSkeleton, ChalkStep } from './types.ts';
+export declare const START_MS = 1000;
+/**
+ * 步尾定格不能停在 endMs 整点:SMIL 在 t == begin 时下一笔已经 active——
+ * round 线帽会露出下一笔起点的一个点,笔尖也跳到下一笔起点(第一批真题检验方反复报"下一步痕迹")。
+ * 退半毫秒:本步末笔 99.9% 以上已画完(肉眼不可辨),下一笔仍处于 opacity 0。
+ */
+export declare const FREEZE_EPS_MS = 0.5;
+/** 步尾定格时刻(秒),给 setCurrentTime 用 */
+export declare function freezeTimeSec(win: StepWindow): number;
+export declare function durationOf(el: ChalkSkeleton): number;
+export interface StepWindow {
+    startMs: number;
+    endMs: number;
+}
+/**
+ * 校验并计算每步的时间窗。
+ * 要求:steps 的 elementIds 恰好按顺序覆盖全部 skeleton(笔顺即步序)。
+ */
+export declare function computeStepWindows(skeletons: readonly ChalkSkeleton[], steps: readonly ChalkStep[]): StepWindow[];
+/** 拉伸后的每步账目:画多久、音多久、放大了几倍 */
+export interface StretchInfo {
+    step: number;
+    drawMs: number;
+    audioMs: number | null;
+    factor: number;
+}
+/**
+ * 按讲稿音频时长拉伸该步笔画(只拉不缩):有配音的步,若音频比画长,把该步全部笔画的
+ * animateDuration 等比放大到 ≈ 音频时长——"一边画一边数:1、2……14"时,14 个圈跟着数的节奏出现,
+ * 而不是 3 秒画完干等 8 秒。作者写的时长变成步内相对权重。音频短于画:照原速画完再等音。
+ * maxStretch 封顶:超过说明这步讲稿太长或画得太少,该回讲法层修,不该把一笔拖成十几秒。
+ * durations[i] 可覆盖 steps[i].audioDurationMs(播放器兜底探测到的时长)。
+ */
+export declare function stretchToAudio(skeletons: readonly ChalkSkeleton[], steps: readonly ChalkStep[], opts?: {
+    maxStretch?: number;
+    durations?: ReadonlyArray<number | null | undefined>;
+}): {
+    skeletons: ChalkSkeleton[];
+    info: StretchInfo[];
+};

package/dist/chalk/timeline.js

@@ -0,0 +1,84 @@
+/**
+ * 步进时间轴:笔画按数组顺序串行,单笔时长 animateDuration(缺省 500ms),起点 START_MS(1000)。
+ * 最早是镜像 excalidraw-animate 的调度规则(0.7.2);播放改成烤好的画面 + 自己的时钟以后(drawtell 重新设计第 4 步),
+ * 这里就是时间的唯一来源:ChalkPlayer、core 的 lessonClock、应用的时钟都从这里算,规则没变,老课包的节奏不变。
+ * groupIds、id 里带 animate 指令仍然拒绝(老规矩,check 也拦)。
+ */
+export const START_MS = 1000;
+const DEFAULT_DUR = 500;
+/**
+ * 步尾定格不能停在 endMs 整点:SMIL 在 t == begin 时下一笔已经 active——
+ * round 线帽会露出下一笔起点的一个点,笔尖也跳到下一笔起点(第一批真题检验方反复报"下一步痕迹")。
+ * 退半毫秒:本步末笔 99.9% 以上已画完(肉眼不可辨),下一笔仍处于 opacity 0。
+ */
+export const FREEZE_EPS_MS = 0.5;
+/** 步尾定格时刻(秒),给 setCurrentTime 用 */
+export function freezeTimeSec(win) {
+    return (win.endMs - FREEZE_EPS_MS) / 1000;
+}
+export function durationOf(el) {
+    return el.animateDuration ?? DEFAULT_DUR;
+}
+/**
+ * 校验并计算每步的时间窗。
+ * 要求:steps 的 elementIds 恰好按顺序覆盖全部 skeleton(笔顺即步序)。
+ */
+export function computeStepWindows(skeletons, steps) {
+    // 静态场景(steps 为空)没有时间窗;覆盖检查只对有步进的场景有意义
+    if (!steps.length)
+        return [];
+    const flat = steps.flatMap((s) => s.elementIds);
+    const ids = skeletons.map((e) => e.id);
+    if (flat.length !== ids.length || flat.some((id, i) => id !== ids[i])) {
+        throw new Error(`chalk-player: steps 未按顺序覆盖全部元素\n期望: ${ids.join(', ')}\n实际: ${flat.join(', ')}`);
+    }
+    for (const e of skeletons) {
+        if (e.groupIds && e.groupIds.length) {
+            throw new Error(`chalk-player: 元素 ${e.id} 带 groupIds,会破坏串行调度`);
+        }
+        if (/animate(Order|Duration):/.test(e.id)) {
+            throw new Error(`chalk-player: 元素 ${e.id} 的 id 携带 animate 指令;时长请写 animateDuration 字段,顺序只由数组决定`);
+        }
+    }
+    const end = new Map();
+    let cur = START_MS;
+    for (const e of skeletons) {
+        cur += durationOf(e);
+        end.set(e.id, cur);
+    }
+    let prev = START_MS;
+    return steps.map((s) => {
+        const startMs = prev;
+        const endMs = end.get(s.elementIds[s.elementIds.length - 1]);
+        prev = endMs;
+        return { startMs, endMs };
+    });
+}
+/**
+ * 按讲稿音频时长拉伸该步笔画(只拉不缩):有配音的步,若音频比画长,把该步全部笔画的
+ * animateDuration 等比放大到 ≈ 音频时长——"一边画一边数:1、2……14"时,14 个圈跟着数的节奏出现,
+ * 而不是 3 秒画完干等 8 秒。作者写的时长变成步内相对权重。音频短于画:照原速画完再等音。
+ * maxStretch 封顶:超过说明这步讲稿太长或画得太少,该回讲法层修,不该把一笔拖成十几秒。
+ * durations[i] 可覆盖 steps[i].audioDurationMs(播放器兜底探测到的时长)。
+ */
+export function stretchToAudio(skeletons, steps, opts = {}) {
+    const maxStretch = opts.maxStretch ?? 5;
+    const factorById = new Map();
+    const info = steps.map((s, i) => {
+        const byId = new Map(skeletons.map((e) => [e.id, e]));
+        const els = s.elementIds.map((id) => byId.get(id)).filter((e) => !!e);
+        const drawMs = els.reduce((a, e) => a + durationOf(e), 0);
+        const audioMs = opts.durations?.[i] ?? s.audioDurationMs ?? null;
+        let factor = 1;
+        if (audioMs && drawMs > 0 && audioMs > drawMs)
+            factor = Math.min(audioMs / drawMs, maxStretch);
+        for (const e of els)
+            factorById.set(e.id, factor);
+        return { step: s.step, drawMs, audioMs, factor };
+    });
+    const out = skeletons.map((e) => {
+        const f = factorById.get(e.id) ?? 1;
+        return f === 1 ? e : { ...e, animateDuration: Math.round(durationOf(e) * f) };
+    });
+    return { skeletons: out, info };
+}