cotutor 0.1.0 → 0.3.0

package/dist/chalk/glyphs/letters.js

@@ -0,0 +1,280 @@
+/**
+ * 26 个小写拉丁字母的笔顺(print 分写体,英美小学通行写法)。大写在 capitals.ts。
+ *
+ * 一个字形一条记录,strokes 顺序 = 教学笔顺;圈类字母(a c d e g o q)逆时针,
+ * 拱类(h m n r)先竖后拱,点(i j)最后落。选型口径见 docs/glyphs.md。
+ *
+ * 坐标是归一化的四线三格(metrics.ts):x 高 = 1,基线 = 0,升部 -2,降部 +1。
+ * 数值经 snap 逐字调过;改动请重跑 `node --experimental-strip-types tests/letters.test.ts`
+ * 与字母表 snap,几何断言(升降部到位、笔画连续、墨迹不越界)会挡住手滑。
+ */
+import { ASC, XT, BASE, DESC } from "./metrics.js";
+/** 圈类字母的碗:圆心 (0.5, -0.5)、半径 0.5,从右上 -30° 逆时针整圈 */
+const bowl = (a0 = -30, a1 = -390) => ({ k: 'A', cx: 0.5, cy: -0.5, rx: 0.5, ry: 0.5, a0, a1 });
+const LETTERS = [
+    {
+        ch: 'a',
+        advance: 1,
+        strokes: [
+            // 碗:从右上起逆时针一整圈,收回起点
+            { start: [0.5 + 0.5 * Math.cos((-30 * Math.PI) / 180), -0.5 + 0.5 * Math.sin((-30 * Math.PI) / 180)], segs: [bowl()] },
+            // 右竖
+            { start: [1, XT], segs: [{ k: 'L', to: [1, BASE] }] },
+        ],
+    },
+    {
+        ch: 'b',
+        advance: 1,
+        strokes: [
+            { start: [0, ASC], segs: [{ k: 'L', to: [0, BASE] }] },
+            // 碗:与 a/d/g/o/q 同一个圆(圆心 0.5,-0.5 半径 0.5),从竖线腰顺时针绕满一圈
+            { start: [0, -0.5], segs: [{ k: 'A', cx: 0.5, cy: -0.5, rx: 0.5, ry: 0.5, a0: 180, a1: 540 }] },
+        ],
+    },
+    {
+        ch: 'c',
+        advance: 0.83,
+        strokes: [
+            // 开口朝右的弧;圆与 a/d/g/o/q 同一个,只是不闭合
+            { start: [0.5 + 0.5 * Math.cos((-50 * Math.PI) / 180), -0.5 + 0.5 * Math.sin((-50 * Math.PI) / 180)],
+                segs: [{ k: 'A', cx: 0.5, cy: -0.5, rx: 0.5, ry: 0.5, a0: -50, a1: -310 }] },
+        ],
+    },
+    {
+        ch: 'd',
+        advance: 1,
+        strokes: [
+            { start: [0.5 + 0.5 * Math.cos((-30 * Math.PI) / 180), -0.5 + 0.5 * Math.sin((-30 * Math.PI) / 180)], segs: [bowl()] },
+            { start: [1, ASC], segs: [{ k: 'L', to: [1, BASE] }] },
+        ],
+    },
+    {
+        ch: 'e',
+        advance: 0.95,
+        strokes: [
+            // 一笔:先向右画横,再顺着圈逆时针绕回,收口在右下
+            { start: [0, -0.5], segs: [
+                    { k: 'L', to: [0.95, -0.5] },
+                    { k: 'A', cx: 0.475, cy: -0.5, rx: 0.475, ry: 0.5, a0: 0, a1: -310 },
+                ] },
+        ],
+    },
+    {
+        ch: 'f',
+        advance: 0.8,
+        strokes: [
+            // 顶钩向右上翘,回到竖线顶后直下
+            { start: [0.72, ASC], segs: [
+                    { k: 'A', cx: 0.72, cy: -1.7, rx: 0.34, ry: 0.3, a0: -90, a1: -180 },
+                    { k: 'L', to: [0.38, BASE] },
+                ] },
+            { start: [0.02, XT], segs: [{ k: 'L', to: [0.8, XT] }] },
+        ],
+    },
+    {
+        ch: 'g',
+        advance: 1,
+        strokes: [
+            { start: [0.5 + 0.5 * Math.cos((-30 * Math.PI) / 180), -0.5 + 0.5 * Math.sin((-30 * Math.PI) / 180)], segs: [bowl()] },
+            // 右竖下探降部,末端向左钩
+            { start: [1, XT], segs: [
+                    { k: 'L', to: [1, 0.55] },
+                    { k: 'A', cx: 0.55, cy: 0.55, rx: 0.45, ry: 0.45, a0: 0, a1: 140 },
+                ] },
+        ],
+    },
+    {
+        ch: 'h',
+        advance: 1,
+        strokes: [
+            { start: [0, ASC], segs: [{ k: 'L', to: [0, BASE] }] },
+            // 肩:上半圆从左到右,再直下
+            { start: [0, -0.5], segs: [
+                    { k: 'A', cx: 0.5, cy: -0.5, rx: 0.5, ry: 0.5, a0: 180, a1: 360 },
+                    { k: 'L', to: [1, BASE] },
+                ] },
+        ],
+    },
+    {
+        ch: 'i',
+        advance: 0.32,
+        strokes: [
+            { start: [0.16, XT], segs: [{ k: 'L', to: [0.16, BASE] }] },
+            // 点:极短一笔,freedraw 的圆端渲染成点
+            { start: [0.16, -1.42], segs: [{ k: 'L', to: [0.16, -1.32] }] },
+        ],
+    },
+    {
+        ch: 'j',
+        advance: 0.6,
+        strokes: [
+            { start: [0.6, XT], segs: [
+                    { k: 'L', to: [0.6, 0.55] },
+                    // rx 放宽、ry 压扁:尾巴伸得开,又不越过降部底线
+                    { k: 'A', cx: 0.05, cy: 0.55, rx: 0.55, ry: 0.45, a0: 0, a1: 95 },
+                ] },
+            { start: [0.6, -1.42], segs: [{ k: 'L', to: [0.6, -1.32] }] },
+        ],
+    },
+    {
+        ch: 'k',
+        advance: 1.1,
+        strokes: [
+            { start: [0, ASC], segs: [{ k: 'L', to: [0, BASE] }] },
+            // 一笔进出:右上斜进到竖线腰,再右下斜出
+            { start: [1.1, XT], segs: [
+                    { k: 'L', to: [0.05, -0.35] },
+                    { k: 'L', to: [1.1, BASE] },
+                ] },
+        ],
+    },
+    {
+        ch: 'l',
+        advance: 0.3,
+        strokes: [{ start: [0.15, ASC], segs: [{ k: 'L', to: [0.15, BASE] }] }],
+    },
+    {
+        ch: 'm',
+        advance: 1.68,
+        strokes: [
+            { start: [0, XT], segs: [{ k: 'L', to: [0, BASE] }] },
+            { start: [0, -0.55], segs: [
+                    { k: 'A', cx: 0.42, cy: -0.55, rx: 0.42, ry: 0.45, a0: 180, a1: 360 },
+                    { k: 'L', to: [0.84, BASE] },
+                ] },
+            { start: [0.84, -0.55], segs: [
+                    { k: 'A', cx: 1.26, cy: -0.55, rx: 0.42, ry: 0.45, a0: 180, a1: 360 },
+                    { k: 'L', to: [1.68, BASE] },
+                ] },
+        ],
+    },
+    {
+        ch: 'n',
+        advance: 1,
+        strokes: [
+            { start: [0, XT], segs: [{ k: 'L', to: [0, BASE] }] },
+            { start: [0, -0.55], segs: [
+                    { k: 'A', cx: 0.5, cy: -0.55, rx: 0.5, ry: 0.45, a0: 180, a1: 360 },
+                    { k: 'L', to: [1, BASE] },
+                ] },
+        ],
+    },
+    {
+        ch: 'o',
+        advance: 1,
+        strokes: [
+            // 从正上起,逆时针一整圈
+            { start: [0.5, XT], segs: [{ k: 'A', cx: 0.5, cy: -0.5, rx: 0.5, ry: 0.5, a0: -90, a1: -450 }] },
+        ],
+    },
+    {
+        ch: 'p',
+        advance: 1,
+        strokes: [
+            { start: [0, XT], segs: [{ k: 'L', to: [0, DESC] }] },
+            { start: [0, -0.5], segs: [{ k: 'A', cx: 0.5, cy: -0.5, rx: 0.5, ry: 0.5, a0: 180, a1: 540 }] },
+        ],
+    },
+    {
+        ch: 'q',
+        advance: 1,
+        strokes: [
+            { start: [0.5 + 0.5 * Math.cos((-30 * Math.PI) / 180), -0.5 + 0.5 * Math.sin((-30 * Math.PI) / 180)], segs: [bowl()] },
+            { start: [1, XT], segs: [{ k: 'L', to: [1, DESC] }] },
+        ],
+    },
+    {
+        ch: 'r',
+        advance: 0.74,
+        strokes: [
+            { start: [0, XT], segs: [{ k: 'L', to: [0, BASE] }] },
+            // 小肩:从竖线腰向右上挑出
+            { start: [0, -0.6], segs: [{ k: 'C', c1: [0.06, -0.96], c2: [0.42, -0.93], to: [0.74, -0.85] }] },
+        ],
+    },
+    {
+        ch: 's',
+        advance: 0.85,
+        strokes: [
+            { start: [0.72, -0.82], segs: [
+                    { k: 'C', c1: [0.6, -1.06], c2: [0.18, -1.06], to: [0.12, -0.78] },
+                    { k: 'C', c1: [0.05, -0.5], c2: [0.8, -0.55], to: [0.72, -0.22] },
+                    { k: 'C', c1: [0.66, 0.05], c2: [0.24, 0.06], to: [0.1, -0.12] },
+                ] },
+        ],
+    },
+    {
+        ch: 't',
+        advance: 0.68,
+        strokes: [
+            // 竖到底后向右挑一个小钩
+            { start: [0.3, -1.7], segs: [
+                    { k: 'L', to: [0.3, 0] },
+                    // 钩从基线起向右上挑:控制点都压在 y=0,曲线既不越线也不悬空
+                    { k: 'C', c1: [0.36, 0], c2: [0.5, 0], to: [0.62, -0.09] },
+                ] },
+            { start: [0.02, XT], segs: [{ k: 'L', to: [0.62, XT] }] },
+        ],
+    },
+    {
+        ch: 'u',
+        advance: 1,
+        strokes: [
+            // 左竖下来接底弧,拐上去
+            { start: [0, XT], segs: [
+                    { k: 'L', to: [0, -0.4] },
+                    { k: 'A', cx: 0.5, cy: -0.4, rx: 0.5, ry: 0.4, a0: 180, a1: 0 },
+                ] },
+            { start: [1, XT], segs: [{ k: 'L', to: [1, BASE] }] },
+        ],
+    },
+    {
+        ch: 'v',
+        advance: 1.03,
+        strokes: [
+            { start: [0, XT], segs: [{ k: 'L', to: [0.515, BASE] }, { k: 'L', to: [1.03, XT] }] },
+        ],
+    },
+    {
+        ch: 'w',
+        advance: 1.49,
+        strokes: [
+            { start: [0, XT], segs: [
+                    { k: 'L', to: [0.3725, BASE] },
+                    { k: 'L', to: [0.745, -0.78] },
+                    { k: 'L', to: [1.1175, BASE] },
+                    { k: 'L', to: [1.49, XT] },
+                ] },
+        ],
+    },
+    {
+        ch: 'x',
+        advance: 1.03,
+        strokes: [
+            { start: [0, XT], segs: [{ k: 'L', to: [1.03, BASE] }] },
+            { start: [1.03, XT], segs: [{ k: 'L', to: [0, BASE] }] },
+        ],
+    },
+    {
+        ch: 'y',
+        advance: 1.03,
+        strokes: [
+            { start: [0, XT], segs: [{ k: 'L', to: [0.54, BASE] }] },
+            // 右斜一路探到降部
+            { start: [1.03, XT], segs: [{ k: 'L', to: [0.28, DESC] }] },
+        ],
+    },
+    {
+        ch: 'z',
+        advance: 0.85,
+        strokes: [
+            { start: [0, XT], segs: [
+                    { k: 'L', to: [0.85, XT] },
+                    { k: 'L', to: [0, BASE] },
+                    { k: 'L', to: [0.85, BASE] },
+                ] },
+        ],
+    },
+];
+/** a–z → 字形;查不到的字符由调用方决定怎么办(本包不猜) */
+export const LOWERCASE = new Map(LETTERS.map((g) => [g.ch, g]));

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

@@ -0,0 +1,33 @@
+/**
+ * 四线三格的度量(大小写共用)。
+ *
+ * 归一化到 x 高 = 1、基线 = 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)
+ *
+ * 实测 Excalifont:升部 2.005、降部 0.948——ASC/DESC 与之吻合。
+ * 大写另有一说:Excalifont 的 cap height 只有 1.653(排版惯例,大写略低于升部),
+ * 但四线三格的教学惯例是**大写顶第一线**,孩子照着写才有参照线。
+ * 字形包是示范字,故取 CAP = ASC = -2(y 向上为负);代价是与字体混排时大写偏大约 21%。
+ * 要改成排版惯例,把 CAP 改成 -1.65 即可,字形按比例自适应。
+ */
+/** 升部顶 / 大写顶 */
+export declare const ASC = -2;
+/** 大写顶(教学惯例:与升部同高、顶第一线) */
+export declare const CAP = -2;
+/** x 高顶 */
+export declare const XT = -1;
+/** 基线 */
+export declare const BASE = 0;
+/** 降部底 */
+export declare const DESC = 1;
+/** 四线三格的归一化线位,消费方画格子用 */
+export declare const GUIDES: {
+    readonly top: -2;
+    readonly xTop: -1;
+    readonly base: 0;
+    readonly bottom: 1;
+};

package/dist/chalk/glyphs/metrics.js

@@ -0,0 +1,28 @@
+/**
+ * 四线三格的度量(大小写共用)。
+ *
+ * 归一化到 x 高 = 1、基线 = 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)
+ *
+ * 实测 Excalifont:升部 2.005、降部 0.948——ASC/DESC 与之吻合。
+ * 大写另有一说:Excalifont 的 cap height 只有 1.653(排版惯例,大写略低于升部),
+ * 但四线三格的教学惯例是**大写顶第一线**,孩子照着写才有参照线。
+ * 字形包是示范字,故取 CAP = ASC = -2(y 向上为负);代价是与字体混排时大写偏大约 21%。
+ * 要改成排版惯例,把 CAP 改成 -1.65 即可,字形按比例自适应。
+ */
+/** 升部顶 / 大写顶 */
+export const ASC = -2;
+/** 大写顶(教学惯例:与升部同高、顶第一线) */
+export const CAP = ASC;
+/** x 高顶 */
+export const XT = -1;
+/** 基线 */
+export const BASE = 0;
+/** 降部底 */
+export const DESC = 1;
+/** 四线三格的归一化线位,消费方画格子用 */
+export const GUIDES = { top: ASC, xTop: XT, base: BASE, bottom: DESC };

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

@@ -0,0 +1,7 @@
+/**
+ * 全部收录字形的查找入口:小写 + 大写。
+ * 排版与骨架生成一律走这里,不直接查 LOWERCASE / UPPERCASE,
+ * 免得加了一类字形却漏改某条查找路径。
+ */
+import type { Glyph } from './types.ts';
+export declare const GLYPHS: ReadonlyMap<string, Glyph>;

package/dist/chalk/glyphs/registry.js

@@ -0,0 +1,8 @@
+/**
+ * 全部收录字形的查找入口:小写 + 大写。
+ * 排版与骨架生成一律走这里,不直接查 LOWERCASE / UPPERCASE,
+ * 免得加了一类字形却漏改某条查找路径。
+ */
+import { LOWERCASE } from "./letters.js";
+import { UPPERCASE } from "./capitals.js";
+export const GLYPHS = new Map([...LOWERCASE, ...UPPERCASE]);

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

@@ -0,0 +1,32 @@
+/**
+ * 段 → 点序列的采样器(纯几何,无浏览器依赖)。
+ *
+ * 点密度直接决定两件事:笔迹曲线的平滑度,以及 bake.json 的体积(freedraw 的路径按点长)。
+ * 按弧长自适应:每 STEP 个单位(x 高的几分之一)落一个点,直段少、圆弧多。
+ */
+import type { Glyph, GlyphStroke, Seg } from './types.ts';
+/**
+ * 默认采样步长(归一化单位):x 高 100px 时约 10px 一个点。
+ *
+ * 这个值同时决定曲线平滑度和体积。当年定它时播放靠 excalidraw-animate,每个点生成一条完整路径的 animate,
+ * 体积 ≈ O(点数²),0.05 时一个词上兆、iPad 卡;0.1 视觉几无差别。现在播放是描边揭示(体积随点数线性),
+ * 值没动,要更平滑可以按需调小。
+ */
+export declare const SAMPLE_STEP = 0.1;
+export type Pt = [number, number];
+/** 段的终点(弧的终点由参数式算出,不由作者另写,避免两处不一致) */
+export declare function segEnd(s: Seg): Pt;
+/**
+ * 一笔 → 点序列(含起点,相邻点不重复)。
+ * 段与段在接缝处共用一个点:后一段跳过 i=0。
+ */
+export declare function sampleStroke(stroke: GlyphStroke, step?: number): Pt[];
+/** 一笔的总弧长(归一化单位):用来按"手写速度"分配动画时长 */
+export declare function strokeLength(stroke: GlyphStroke): number;
+/** 字形的墨迹包围盒(归一化单位):校验与排版用 */
+export declare function glyphBBox(glyph: Glyph, step?: number): {
+    x0: number;
+    y0: number;
+    x1: number;
+    y1: number;
+};

package/dist/chalk/glyphs/sample.js

@@ -0,0 +1,102 @@
+/**
+ * 段 → 点序列的采样器(纯几何,无浏览器依赖)。
+ *
+ * 点密度直接决定两件事:笔迹曲线的平滑度,以及 bake.json 的体积(freedraw 的路径按点长)。
+ * 按弧长自适应:每 STEP 个单位(x 高的几分之一)落一个点,直段少、圆弧多。
+ */
+/**
+ * 默认采样步长(归一化单位):x 高 100px 时约 10px 一个点。
+ *
+ * 这个值同时决定曲线平滑度和体积。当年定它时播放靠 excalidraw-animate,每个点生成一条完整路径的 animate,
+ * 体积 ≈ O(点数²),0.05 时一个词上兆、iPad 卡;0.1 视觉几无差别。现在播放是描边揭示(体积随点数线性),
+ * 值没动,要更平滑可以按需调小。
+ */
+export const SAMPLE_STEP = 0.1;
+/** 一段至少给几个点(短到不足一步的段也要有形) */
+const MIN_PER_SEG = 2;
+/** 一段最多给几个点(防止长弧把 DOM 撑爆) */
+const MAX_PER_SEG = 64;
+const rad = (deg) => (deg * Math.PI) / 180;
+function arcAt(s, t) {
+    const a = rad(s.a0 + (s.a1 - s.a0) * t);
+    return [s.cx + s.rx * Math.cos(a), s.cy + s.ry * Math.sin(a)];
+}
+function cubicAt(from, s, t) {
+    const u = 1 - t;
+    const b0 = u * u * u;
+    const b1 = 3 * u * u * t;
+    const b2 = 3 * u * t * t;
+    const b3 = t * t * t;
+    return [
+        b0 * from[0] + b1 * s.c1[0] + b2 * s.c2[0] + b3 * s.to[0],
+        b0 * from[1] + b1 * s.c1[1] + b2 * s.c2[1] + b3 * s.to[1],
+    ];
+}
+/** 段的近似弧长:直线精确,曲线用 16 段折线量 */
+function segLength(from, s) {
+    if (s.k === 'L')
+        return Math.hypot(s.to[0] - from[0], s.to[1] - from[1]);
+    let len = 0;
+    let prev = from;
+    for (let i = 1; i <= 16; i++) {
+        const p = s.k === 'A' ? arcAt(s, i / 16) : cubicAt(from, s, i / 16);
+        len += Math.hypot(p[0] - prev[0], p[1] - prev[1]);
+        prev = p;
+    }
+    return len;
+}
+/** 段的终点(弧的终点由参数式算出,不由作者另写,避免两处不一致) */
+export function segEnd(s) {
+    if (s.k === 'L' || s.k === 'C')
+        return [s.to[0], s.to[1]];
+    return arcAt(s, 1);
+}
+/**
+ * 一笔 → 点序列(含起点,相邻点不重复)。
+ * 段与段在接缝处共用一个点:后一段跳过 i=0。
+ */
+export function sampleStroke(stroke, step = SAMPLE_STEP) {
+    const pts = [[stroke.start[0], stroke.start[1]]];
+    let from = pts[0];
+    for (const seg of stroke.segs) {
+        const n = Math.min(MAX_PER_SEG, Math.max(MIN_PER_SEG, Math.ceil(segLength(from, seg) / step)));
+        for (let i = 1; i <= n; i++) {
+            pts.push(seg.k === 'A' ? arcAt(seg, i / n) : seg.k === 'C' ? cubicAt(from, seg, i / n) : [
+                from[0] + (seg.to[0] - from[0]) * (i / n),
+                from[1] + (seg.to[1] - from[1]) * (i / n),
+            ]);
+        }
+        from = pts[pts.length - 1];
+    }
+    return pts;
+}
+/** 一笔的总弧长(归一化单位):用来按"手写速度"分配动画时长 */
+export function strokeLength(stroke) {
+    let len = 0;
+    let from = [stroke.start[0], stroke.start[1]];
+    for (const seg of stroke.segs) {
+        len += segLength(from, seg);
+        from = segEnd(seg);
+    }
+    return len;
+}
+/** 字形的墨迹包围盒(归一化单位):校验与排版用 */
+export function glyphBBox(glyph, step = SAMPLE_STEP) {
+    let x0 = Infinity;
+    let y0 = Infinity;
+    let x1 = -Infinity;
+    let y1 = -Infinity;
+    for (const st of glyph.strokes) {
+        for (const [x, y] of sampleStroke(st, step)) {
+            if (x < x0)
+                x0 = x;
+            if (y < y0)
+                y0 = y;
+            if (x > x1)
+                x1 = x;
+            if (y > y1)
+                y1 = y;
+        }
+    }
+    return { x0, y0, x1, y1 };
+}

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

@@ -0,0 +1,64 @@
+/**
+ * 字形 → 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 type { ChalkSkeleton } from '../types.ts';
+import type { Glyph } from './types.ts';
+export interface GlyphPenOptions {
+    /** x 高(px):字形的度量基准,四线三格的一格 */
+    xHeight: number;
+    /** 基线左端的画布坐标 */
+    x: number;
+    y: number;
+    strokeColor?: string;
+    /** 缺省 xHeight/30 —— 对齐 Excalifont 的笔画重量(见文件头坑 2) */
+    strokeWidth?: number;
+    /** 每 1 个 x 高单位弧长的毫秒数,决定"手写速度";缺省 200 */
+    msPerUnit?: number;
+    /** 单笔时长下限(i/j 的点只有 0.1 单位);缺省 90 */
+    minStrokeMs?: number;
+    /** 元素 id 前缀,同一场景里要唯一 */
+    idPrefix?: string;
+    /** 字间距(x 高为 1 单位);缺省 0.22 */
+    letterSpacing?: number;
+    /** 采样步长(归一化单位);缺省 SAMPLE_STEP。调小更平滑,但动画 DOM 体积约按平方涨 */
+    sampleStep?: number;
+    /**
+     * 字形表(provider):缺省内置拉丁包(a–z / A–Z)。扩展字形数据包
+     * (如 drawtell-glyphs-hanzi)导出同构的 Map,从这里传入即共用同一支笔——
+     * 归一化约定由各包自定并写明(拉丁 = 四线三格;汉字 = 格子高 1、底线 y=0、顶 y=-1)。
+     */
+    glyphs?: ReadonlyMap<string, Glyph>;
+}
+/** 空格的前进宽度(x 高为 1 单位):不产生笔画,只让光标走一段 */
+export declare const SPACE_ADVANCE = 0.55;
+/** 字形表未收录的字符:由调用方决定回退,这里不猜 */
+export declare class UnknownGlyphError extends Error {
+    /** node 的 strip-only 类型擦除不支持构造函数参数属性,字段显式声明 */
+    ch: string;
+    constructor(ch: string);
+}
+/**
+ * 单个字母(大小写皆可)→ 一笔一个 freedraw 元素。
+ * 返回顺序即笔顺,可直接铺进 scene.skeletons / 交给 buildAnimatedSvg。
+ */
+export declare function glyphSkeletons(ch: string, o: GlyphPenOptions): ChalkSkeleton[];
+/** 一个词的排版宽度(px),含字间距,不含末尾空隙;空格按 SPACE_ADVANCE 计 */
+export declare function wordAdvance(word: string, o: Pick<GlyphPenOptions, 'xHeight' | 'letterSpacing' | 'glyphs'>): number;
+/**
+ * 一串字母(大小写皆可)→ 全部笔画,从左到右按 advance + letterSpacing 排;
+ * 空格只让光标前进,不产生笔画(于是 'ram man' 能一次画完,不必调用方自己拆词)。
+ * id 形如 `<prefix>-<序号><字母>-<笔序>`,同字母重复出现也不撞。
+ */
+export declare function wordSkeletons(word: string, o: GlyphPenOptions): ChalkSkeleton[];

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;汉字等扩展字形经 glyphs 选项传入(如 drawtell-glyphs-hanzi)。`);
+        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;
+}