cotutor 0.1.0 → 0.3.0

package/dist/board/cards/dictation.js

@@ -0,0 +1,105 @@
+/**
+ * 听写卡(kind 名 dictation,只用在首页):家长写一串词,孩子在首页点开,老师一个一个念、孩子在田字格里写,写完自己对。
+ * 英文单词也行:词都是英文单词时 props.lang = 'en',孩子在四线三格里写整个单词。
+ * 标签修饰 = 念的老师(cotutor.json 的键,用他的音色;不写用语文老师或第一位配了音色的);正文一行一个词,词后面空一格可以跟「怎么念」。
+ * 英文单词前面可以配一个 emoji:只在孩子写完对一对时出,写的时候看不到。
+ * 词就是答案:strip 只留几个词,孩子端首页 JSON 里没有字;听写页写完交了才拿到(src/app/dictation/route.ts)。
+ */
+import { z } from 'zod';
+import { HAN } from "./tianzige.js";
+import { bodyLines } from "./kind.js";
+/** 一个词最多几个字(一个字一个田字格,同田字格卡) */
+export const DICTATION_WORD_MAX = 4;
+/** 英文单词最多几个字母(一个单词一个四线三格) */
+export const DICTATION_EN_MAX = 20;
+/** 英文单词:字母开头,可以带连字符与撇号(ice-cream、don't);不带空格,一行一个单词 */
+export const EN_WORD_RE = /^[A-Za-z][A-Za-z'-]*$/;
+/** 能不能听写、是哪种:一到四个汉字 = zh;一个英文单词(≤ 20 个字母)= en;都不是 null */
+export function dictationWordLang(text) {
+    const cs = Array.from(text);
+    if (cs.length && cs.length <= DICTATION_WORD_MAX && cs.every((c) => HAN.test(c)))
+        return 'zh';
+    if (EN_WORD_RE.test(text) && text.length <= DICTATION_EN_MAX)
+        return 'en';
+    return null;
+}
+/** 一张卡最多几个词 */
+export const DICTATION_WORDS_MAX = 20;
+/** 念法最多几个字 */
+export const DICTATION_SAY_MAX = 40;
+const NAME_RE = /^[a-z0-9][a-z0-9-]*$/;
+/** 一个 emoji:图形字符开头,后面只跟修饰符、连接符(👨‍👩‍👧、👍🏽、🇨🇳) */
+const EMOJI_RE = /^(?:\p{Extended_Pictographic}|\p{Regional_Indicator})(?:\p{Extended_Pictographic}|\p{Regional_Indicator}|\p{Emoji_Modifier}|\u200d|\ufe0f)*$/u;
+/** 是一个 emoji 就回它(去掉两头空白),不是 undefined;英文单词配的图 */
+export function dictationEmoji(v) {
+    const t = typeof v === 'string' ? v.trim() : '';
+    return t && t.length <= 16 && EMOJI_RE.test(t) ? t : undefined;
+}
+const LIST_PREFIX = /^(?:[-*+]|\d+[.)、])\s*/;
+export const DictationWordSchema = z.object({
+    /** 要写的字,1–4 个汉字 */
+    chars: z.string().min(1),
+    /** 老师怎么念(「鼓励,老师鼓励我的鼓励」);没写就念词本身 */
+    say: z.string().min(1).optional(),
+    /** 英文单词配的 emoji(能画出来的东西才有);只在对一对时出 */
+    emoji: z.string().min(1).max(16).optional(),
+});
+export const DictationPropsSchema = z.object({
+    /** 念的老师(cotutor.json 的键) */
+    tutor: z.string().regex(NAME_RE).optional(),
+    /** 英文单词听写(词都是英文单词);汉字的不写 */
+    lang: z.literal('en').optional(),
+    /** 词;孩子端剥成空的 */
+    words: z.array(DictationWordSchema).max(DICTATION_WORDS_MAX),
+    /** 几个词(strip 时补,孩子端首页卡上显示) */
+    count: z.number().int().nonnegative().optional(),
+});
+export const dictation = {
+    name: 'dictation',
+    where: ['home'],
+    props: DictationPropsSchema,
+    parse(body, mods) {
+        const who = mods[0];
+        if (who !== undefined && !NAME_RE.test(who))
+            throw new Error(`「${who}」不像老师的键(cotutor.json tutors 里的英文名)`);
+        if (mods.length > 1)
+            throw new Error('标签后面只写一位老师');
+        const words = [];
+        for (const raw of bodyLines(body)) {
+            let line = raw.replace(LIST_PREFIX, '');
+            // 前面可以配一个 emoji(同单词卡的「🍎 apple」)
+            const lead = /^(\S+)\s+(.+)$/.exec(line);
+            const emoji = lead ? dictationEmoji(lead[1]) : undefined;
+            if (emoji && lead)
+                line = lead[2];
+            const m = /^(\S+)(?:\s+(.+))?$/.exec(line);
+            if (!m)
+                continue;
+            const lang = dictationWordLang(m[1]);
+            if (!lang) {
+                const chars = Array.from(m[1]);
+                if (/^[A-Za-z]/.test(m[1]))
+                    throw new Error(`「${m[1]}」不像一个英文单词(只要字母,最多 ${DICTATION_EN_MAX} 个;一行一个单词,念法空一格写在后面)`);
+                const bad = chars.find((c) => !HAN.test(c));
+                if (bad)
+                    throw new Error(`「${m[1]}」里的「${bad}」不是汉字;一行一个词,念法空一格写在后面`);
+                throw new Error(`「${m[1]}」超过 ${DICTATION_WORD_MAX} 个字,拆开写`);
+            }
+            if (words.length && (dictationWordLang(words[0].chars) ?? 'zh') !== lang)
+                throw new Error(`「${m[1]}」:一张听写卡只写一种,汉字的词和英文单词分两张`);
+            const say = m[2]?.trim();
+            if (say && Array.from(say).length > DICTATION_SAY_MAX)
+                throw new Error(`「${m[1]}」的念法超过 ${DICTATION_SAY_MAX} 个字`);
+            words.push({ chars: m[1], ...(say ? { say } : {}), ...(emoji ? { emoji } : {}) });
+        }
+        if (!words.length)
+            throw new Error('要听写的词呢(一行一个)');
+        if (words.length > DICTATION_WORDS_MAX)
+            throw new Error(`一张卡最多 ${DICTATION_WORDS_MAX} 个词(给了 ${words.length} 个),拆成两张`);
+        const en = dictationWordLang(words[0].chars) === 'en';
+        return { ...(who ? { tutor: who } : {}), ...(en ? { lang: 'en' } : {}), words };
+    },
+    strip(p) {
+        return { ...(p.tutor ? { tutor: p.tutor } : {}), ...(p.lang ? { lang: p.lang } : {}), words: [], count: p.count ?? p.words.length };
+    },
+};

package/dist/board/cards/docs.d.ts

@@ -0,0 +1,47 @@
+import { type CardPlace } from './index.ts';
+/** 本包自带的卡协议目录(仓库检出与 npm 安装都在包根 cards/) */
+export declare const PACKAGE_CARDS_DIR: string;
+export interface CardDoc {
+    kind: string;
+    /** 整份 card.md */
+    md: string;
+    /** 各栏目正文(按 ## 标题切;没有的栏目是空串) */
+    sections: Record<string, string>;
+    /** 标题行后面那句(「text — 一段字」) */
+    headline: string;
+}
+/** md 按 `## ` 切栏目;`# ` 标题行单独取 */
+export declare function splitSections(md: string): {
+    headline: string;
+    sections: Record<string, string>;
+};
+export declare function readCardDoc(kind: string, dir?: string): CardDoc;
+/** 能用在某处的种类的协议(按注册表的顺序);缺省板书——cotutor-board 技能只列这些;给了 only 就只要这几种(按老师裁,boardGuideFor) */
+export declare function cardDocs(dir?: string, place?: CardPlace, only?: readonly string[]): CardDoc[];
+/** 板书写法的手写部分(开头的规矩、一节的例子、作业照片),人改的就是这一篇;`{{卡的种类}}` 那一行由下面拼的各种卡替换 */
+export declare const BOARD_GUIDE_SOURCE = "\u677F\u4E66\u600E\u4E48\u5199.md";
+/**
+ * 给老师看的语法表(SKILL.md 的正文):cards/板书怎么写.md(剥掉给人看的注释,按卡裁段落)+ 各 card.md 的「是什么 / 写法 / 例子」。
+ * kinds 不给 = 板书的全部种类(出厂的 SKILL.md);给了就只拼这几种(按老师裁,boardGuideFor)。
+ */
+export declare function boardSyntaxDoc(dir?: string, kinds?: readonly string[]): string;
+/** 板书写法以外多带的几种卡(activity 要用、老师的清单里没有的),同板书写法里那一段的样子;递给老师前剥掉给人看的注释 */
+export declare function cardGuidesFor(kinds: readonly string[], dir?: string): string;
+/** 按老师裁的板书写法(递给老师的正文,同 boardGuideBody(SKILL.md) 的形状:没有 frontmatter、没有给人看的注释) */
+export declare function boardGuideFor(kinds: readonly string[], dir?: string): string;
+/** references/README.md:一行一种——名字、一句是什么、何时用;老师按需 @ 单张 */
+export declare function cardsIndexDoc(dir?: string): string;
+/** 技能名;目录 .agents/skills/cotutor-board/ */
+export declare const BOARD_SKILL = "cotutor-board";
+/** SKILL.md:frontmatter(name / description)+ 语法表;description 列出卡的种类,让模型不读正文也知道有哪几种 */
+export declare function boardSkillDoc(dir?: string): string;
+/** 技能目录的全部文件(相对技能根):SKILL.md + references/README.md + references/<kind>.md;scripts/gen-skills.ts 写进包根 skills/cotutor-board/,tests/skills.test.ts 断言入库的和它一致 */
+export declare function boardSkillFiles(dir?: string): Record<string, string>;
+/** 各种卡的结构样式(cards/<kind>/card.css)拼成一段,放在主题 css 前面(主题能盖) */
+export declare function cardsCss(dir?: string): string;
+/** 例子即测试用:md 里每个围栏 + 它前面的 expect 注释 */
+export declare function docExamples(md: string): {
+    tag: string;
+    body: string;
+    expect: Record<string, unknown> | null;
+}[];

package/dist/board/cards/docs.js

@@ -0,0 +1,152 @@
+/**
+ * 卡的协议文件:每种能力型卡在包根 cards/<kind>/ 下有 card.md(协议:是什么 / 何时用 / 写法 / 例子 / 反例 /
+ * 孩子看到什么 / 你会收回什么 / 状态的形状)与 card.css(这种卡的结构样式,只用主题变量)。
+ * md 是可以单独 @ 的文件:init / upgrade 出厂成 workspace 里的**一个技能** .agents/skills/cotutor-board/:SKILL.md = 语法表(frontmatter + 各 md 的「是什么 / 写法 / 例子」拼),references/<kind>.md 逐张协议,
+ * references/README.md 索引;老师按需 @ 单张。写盘的在 app/cli/skills.ts `writeBoardSkill`。
+ * 例子即测试:tests/cards-doc.test.ts 把每个 card.md 里的围栏喂 parseCard,`<!-- expect {…} -->` 注释是期望。
+ */
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { CARD_KINDS, kindsFor } from "./index.js";
+import { stripHumanNotes } from "../../shared/human-notes.js";
+import { applyCardGuards } from "../card-guards.js";
+/** 本包自带的卡协议目录(仓库检出与 npm 安装都在包根 cards/) */
+export const PACKAGE_CARDS_DIR = fileURLToPath(new URL('../../../cards/', import.meta.url));
+/** md 按 `## ` 切栏目;`# ` 标题行单独取 */
+export function splitSections(md) {
+    const lines = md.split('\n');
+    // 标题行 = 第一个 ## 之前的那行 `# …`;栏目里的 `# 认边`(例子围栏里的)照收
+    let headline = '';
+    const sections = {};
+    let cur = null;
+    const buf = [];
+    const flush = () => {
+        if (cur !== null)
+            sections[cur] = buf.join('\n').trim();
+        buf.length = 0;
+    };
+    for (const l of lines) {
+        if (l.startsWith('## ')) {
+            flush();
+            cur = l.slice(3).trim();
+        }
+        else if (cur === null) {
+            if (!headline && l.startsWith('# '))
+                headline = l.slice(2).trim();
+        }
+        else
+            buf.push(l);
+    }
+    flush();
+    return { headline, sections };
+}
+export function readCardDoc(kind, dir = PACKAGE_CARDS_DIR) {
+    const md = readFileSync(join(dir, kind, 'card.md'), 'utf8');
+    const { headline, sections } = splitSections(md);
+    return { kind, md, sections, headline };
+}
+/** 能用在某处的种类的协议(按注册表的顺序);缺省板书——cotutor-board 技能只列这些;给了 only 就只要这几种(按老师裁,boardGuideFor) */
+export function cardDocs(dir = PACKAGE_CARDS_DIR, place = 'board', only) {
+    return kindsFor(place)
+        .filter((k) => !only || only.includes(k.name))
+        .map((k) => readCardDoc(k.name, dir));
+}
+/** 例子里的 `<!-- expect {…} -->` 注释:给老师看的版本要去掉 */
+const EXPECT_RE = /^\s*<!--\s*expect\b.*?-->\s*\n?/gm;
+/** 板书写法的手写部分(开头的规矩、一节的例子、作业照片),人改的就是这一篇;`{{卡的种类}}` 那一行由下面拼的各种卡替换 */
+export const BOARD_GUIDE_SOURCE = '板书怎么写.md';
+const KINDS_SLOT = /^\{\{卡的种类\}\}$/m;
+/**
+ * 给老师看的语法表(SKILL.md 的正文):cards/板书怎么写.md(剥掉给人看的注释,按卡裁段落)+ 各 card.md 的「是什么 / 写法 / 例子」。
+ * kinds 不给 = 板书的全部种类(出厂的 SKILL.md);给了就只拼这几种(按老师裁,boardGuideFor)。
+ */
+export function boardSyntaxDoc(dir = PACKAGE_CARDS_DIR, kinds) {
+    const all = kindsFor('board').map((k) => k.name);
+    const want = kinds ? all.filter((k) => kinds.includes(k)) : all;
+    const docs = cardDocs(dir, 'board', want).map(cardGuide).join('\n\n');
+    const guide = applyCardGuards(stripHumanNotes(readFileSync(join(dir, BOARD_GUIDE_SOURCE), 'utf8')), want);
+    if (!KINDS_SLOT.test(guide))
+        throw new Error(`cards/${BOARD_GUIDE_SOURCE} 里没有「{{卡的种类}}」那一行`);
+    return `${guide.replace(KINDS_SLOT, () => docs)}\n`;
+}
+/** 一种卡给老师看的那段:标题 + 是什么 / 写法 / 例子(去掉 expect);板书写法里「卡的种类」一节就是一张张拼的它 */
+function cardGuide(d) {
+    const parts = [`### ${d.headline}`, d.sections['是什么'], d.sections['写法'], d.sections['例子']?.replace(EXPECT_RE, '')].filter((x) => x && x.trim());
+    return parts.join('\n\n').trim();
+}
+/** 板书写法以外多带的几种卡(activity 要用、老师的清单里没有的),同板书写法里那一段的样子;递给老师前剥掉给人看的注释 */
+export function cardGuidesFor(kinds, dir = PACKAGE_CARDS_DIR) {
+    return stripHumanNotes(cardDocs(dir, 'board', kinds).map(cardGuide).join('\n\n'));
+}
+/** 按老师裁的板书写法(递给老师的正文,同 boardGuideBody(SKILL.md) 的形状:没有 frontmatter、没有给人看的注释) */
+export function boardGuideFor(kinds, dir = PACKAGE_CARDS_DIR) {
+    return stripHumanNotes(boardSyntaxDoc(dir, kinds));
+}
+/** references/README.md:一行一种——名字、一句是什么、何时用;老师按需 @ 单张 */
+export function cardsIndexDoc(dir = PACKAGE_CARDS_DIR) {
+    const rows = cardDocs(dir).map((d) => {
+        const what = (d.sections['是什么'] ?? '').split('\n').find((l) => l.trim()) ?? '';
+        const when = (d.sections['什么时候用 / 别用'] ?? '').split('\n').filter((l) => l.startsWith('- 用:')).map((l) => `\n  - 用在:${l.slice(4).trim()}`).join('');
+        return `- **${d.kind}**(${d.kind}.md)—— ${what}${when}`;
+    });
+    return `# 卡的种类(索引)
+
+每种卡一份协议:是什么、什么时候用 / 别用、写法、例子、反例、孩子看到什么、你会收回什么、状态的形状。讲解前只读需要的那一两张;总表在 ../SKILL.md。机器文件,init / upgrade 刷新。
+
+${rows.join('\n')}
+`;
+}
+/** 技能名;目录 .agents/skills/cotutor-board/ */
+export const BOARD_SKILL = 'cotutor-board';
+/** SKILL.md:frontmatter(name / description)+ 语法表;description 列出卡的种类,让模型不读正文也知道有哪几种 */
+export function boardSkillDoc(dir = PACKAGE_CARDS_DIR) {
+    const kinds = kindsFor('board').map((k) => k.name).join(' / ');
+    const description = `cotutor 的板书怎么写:讲稿一行一句,围栏是卡(种类:${kinds})。应用已经递给老师,老师不用读;家长查阅用。每种卡完整的协议在 references/<种类>.md。机器生成,源在 cotutor 仓的 cards/,别在这里改。`;
+    return `---\nname: ${BOARD_SKILL}\ndescription: ${description}\n---\n\n${boardSyntaxDoc(dir)}`;
+}
+/** 技能目录的全部文件(相对技能根):SKILL.md + references/README.md + references/<kind>.md;scripts/gen-skills.ts 写进包根 skills/cotutor-board/,tests/skills.test.ts 断言入库的和它一致 */
+export function boardSkillFiles(dir = PACKAGE_CARDS_DIR) {
+    const out = { 'SKILL.md': boardSkillDoc(dir), 'references/README.md': cardsIndexDoc(dir) };
+    for (const d of cardDocs(dir))
+        out[`references/${d.kind}.md`] = d.md;
+    return out;
+}
+/** 各种卡的结构样式(cards/<kind>/card.css)拼成一段,放在主题 css 前面(主题能盖) */
+export function cardsCss(dir = PACKAGE_CARDS_DIR) {
+    return CARD_KINDS.map((k) => {
+        try {
+            return `/* ---- ${k.name}(cards/${k.name}/card.css)---- */\n${readFileSync(join(dir, k.name, 'card.css'), 'utf8').trim()}`;
+        }
+        catch {
+            return '';
+        }
+    })
+        .filter(Boolean)
+        .join('\n\n');
+}
+/** 例子即测试用:md 里每个围栏 + 它前面的 expect 注释 */
+export function docExamples(md) {
+    const out = [];
+    const lines = md.split('\n');
+    let expect = null;
+    for (let i = 0; i < lines.length; i++) {
+        const l = lines[i];
+        const ex = /^<!--\s*expect\s+(\{.*\})\s*-->$/.exec(l.trim());
+        if (ex) {
+            expect = JSON.parse(ex[1]);
+            continue;
+        }
+        const open = /^```(.*)$/.exec(l);
+        if (open && !l.startsWith('````')) {
+            const body = [];
+            let j = i + 1;
+            for (; j < lines.length && !/^```\s*$/.test(lines[j]); j++)
+                body.push(lines[j]);
+            out.push({ tag: open[1].trim(), body: body.join('\n'), expect });
+            expect = null;
+            i = j;
+        }
+    }
+    return out;
+}

package/dist/board/cards/image.d.ts

@@ -0,0 +1,13 @@
+/**
+ * 图片卡:第一行是图(workspace 里的相对路径——产物、孩子拍的照片;或 http(s) 地址),后面几行是图注。
+ * 路径由 /api/kid/image?p= 供图,只认 workspace 根以内的图片文件;舞台里双指缩放。
+ */
+import { z } from 'zod';
+import { type CardKind } from './kind.ts';
+export declare const ImagePropsSchema: z.ZodObject<{
+    src: z.ZodString;
+    caption: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type ImageProps = z.infer<typeof ImagePropsSchema>;
+export declare const IMAGE_EXT: RegExp;
+export declare const image: CardKind<ImageProps>;

package/dist/board/cards/image.js

@@ -0,0 +1,26 @@
+/**
+ * 图片卡:第一行是图(workspace 里的相对路径——产物、孩子拍的照片;或 http(s) 地址),后面几行是图注。
+ * 路径由 /api/kid/image?p= 供图,只认 workspace 根以内的图片文件;舞台里双指缩放。
+ */
+import { z } from 'zod';
+import { bodyLines } from "./kind.js";
+export const ImagePropsSchema = z.object({
+    /** 相对 workspace 根的路径,或 http(s):// 地址 */
+    src: z.string().min(1),
+    caption: z.string().optional(),
+});
+export const IMAGE_EXT = /\.(png|jpe?g|webp|gif|svg)$/i;
+export const image = {
+    name: 'image',
+    where: ['board', 'home'],
+    props: ImagePropsSchema,
+    parse(body) {
+        const [src, ...rest] = bodyLines(body);
+        if (!src)
+            throw new Error('第一行要是图片路径或地址');
+        if (!/^https?:\/\//.test(src) && !IMAGE_EXT.test(src))
+            throw new Error('要是 png / jpg / webp / gif / svg 图片');
+        const caption = rest.join('\n');
+        return { src, ...(caption ? { caption } : {}) };
+    },
+};

package/dist/board/cards/index.d.ts

@@ -0,0 +1,62 @@
+import type { BoardCard, BoardSection } from '../presentation.ts';
+import type { CardKind, CardPlace } from './kind.ts';
+export { BUNDLE_ID_RE, type CardKind, type CardPlace } from './kind.ts';
+export { text, TEXT_STYLES, type TextProps, type TextStyle } from './text.ts';
+export { read, type ReadProps } from './read.ts';
+export { choice, type ChoiceProps } from './choice.ts';
+export { code, type CodeProps } from './code.ts';
+export { image, IMAGE_EXT, type ImageProps } from './image.ts';
+export { lecture, type LectureProps, type LectureState } from './lecture.ts';
+export { canvas, type CanvasProps, type CanvasState } from './canvas.ts';
+export { paint, PaintPropsSchema, PAINT_PANELS_MAX, type PaintCast, type PaintProps } from './paint.ts';
+export { tianzige, HAN, TIANZIGE_MAX, type TianzigeProps } from './tianzige.ts';
+export { word, wordChunks, WORD_MAX, WORD_MAX_WORDS, WORD_RE, type WordProps } from './word.ts';
+export { tutor, BUTTON_LABEL_MAX, TUTOR_BUTTONS_MAX, TutorButtonSchema, type TutorButton, type TutorProps } from './tutor.ts';
+export { dictation, dictationEmoji, dictationWordLang, DictationPropsSchema, DICTATION_EN_MAX, DICTATION_SAY_MAX, DICTATION_WORD_MAX, DICTATION_WORDS_MAX, EN_WORD_RE, type DictationLang, type DictationProps, type DictationWord } from './dictation.ts';
+/** 全部种类:先板书的十一种(注册表顺序即技能里的顺序),再首页专属的 */
+export declare const CARD_KINDS: readonly CardKind<any>[];
+export declare function cardKind(name: string): CardKind | undefined;
+/** 这种卡能不能用在这里(没写 where 的只板书) */
+export declare function usableIn(kind: Pick<CardKind, 'where'>, place: CardPlace): boolean;
+/** 能用在某处的种类(注册表顺序) */
+export declare function kindsFor(place: CardPlace): readonly CardKind<any>[];
+/**
+ * 这位老师的板书写法里讲哪几种卡(cotutor.json tutors.<老师>.cards,《卡片协议.md》「谁拿到哪些卡」):
+ * 没写 = null(全部,递出厂的 cotutor-board SKILL.md);写了 = 板书能用的、按注册表顺序,text 总在(写坏的卡退成它)。
+ */
+export declare function tutorCardKinds(cards: readonly string[] | undefined): string[] | null;
+export interface ParsedCard {
+    card: BoardCard;
+    /** 没解析成时的一句(家长视图转录里显示);孩子端什么也不报 */
+    warning?: string;
+    /** 没照标签解析成(退成了文字卡 / 代码卡);首页检查据此判「要改」 */
+    fallback?: boolean;
+}
+/**
+ * 围栏 → 卡。标签第一个词是 kind,其余是修饰;不认识的标签:板书里当代码卡原样显示,首页里退文字卡;
+ * 认识但正文解析不出、或这种卡不能用在这里(place)→ 文字卡显示原文 + warning。永不抛错。
+ */
+export declare function parseCard(tag: string, body: string, place?: CardPlace): ParsedCard;
+/** 孩子端的一节:每张卡过本种卡的 strip(答案不下发);不认识的 kind 原样;孩子自己的状态与已生成的资产照给 */
+export declare function stripSecrets(section: BoardSection): BoardSection;
+/** 一张卡的标题(舞台顶栏、给老师的描述里用):文字卡的 title / text,选择题的问题,其余第一段有字的,田字格的字,单词卡的词,听写卡的词表 */
+export declare function cardLabel(card: BoardCard): string;
+/** 这张卡要后台预生成的配音(文件名相对它的资产目录);没有的种类 → [] */
+export declare function cardAssets(card: BoardCard): {
+    file: string;
+    text: string;
+}[];
+export type CardStateResult = {
+    ok: true;
+    state: unknown;
+} | {
+    ok: false;
+    why: string;
+};
+/** 孩子端 PUT 上来的状态过本种卡的契约;这种卡没有状态、或不认识的 kind → 不收 */
+export declare function parseCardState(card: BoardCard, raw: unknown): CardStateResult;
+/**
+ * 给老师的一句:「choice「问题」 选了「B …」(答案:「…」)」。props 用索引里的(带答案),状态是孩子的;
+ * 没有 describe 的种类把状态原样 JSON。id 由调用方拼在前面(<job>/<n>)。
+ */
+export declare function describeCard(card: BoardCard, state: unknown): string;

package/dist/board/cards/index.js

@@ -0,0 +1,144 @@
+/**
+ * 卡的注册表:加一种卡 = 加一个文件 + 这里一行;解析器、语法表、孩子端剥秘密都从这里走。
+ * 页面那一半在 kid-page.ts(渲染)与 board/presentation.ts(标注落点),按 kind 名对上。协议文档与结构样式在包根 cards/<kind>/(src/board/cards/docs.ts)。
+ */
+import { z } from 'zod';
+import { canvas } from "./canvas.js";
+import { choice } from "./choice.js";
+import { code } from "./code.js";
+import { tianzige } from "./tianzige.js";
+import { word } from "./word.js";
+import { image } from "./image.js";
+import { read } from "./read.js";
+import { paint } from "./paint.js";
+import { photo } from "./photo.js";
+import { lecture } from "./lecture.js";
+import { text } from "./text.js";
+import { tutor } from "./tutor.js";
+import { dictation } from "./dictation.js";
+export { BUNDLE_ID_RE } from "./kind.js";
+export { text, TEXT_STYLES } from "./text.js";
+export { read } from "./read.js";
+export { choice } from "./choice.js";
+export { code } from "./code.js";
+export { image, IMAGE_EXT } from "./image.js";
+export { lecture } from "./lecture.js";
+export { canvas } from "./canvas.js";
+export { paint, PaintPropsSchema, PAINT_PANELS_MAX } from "./paint.js";
+export { tianzige, HAN, TIANZIGE_MAX } from "./tianzige.js";
+export { word, wordChunks, WORD_MAX, WORD_MAX_WORDS, WORD_RE } from "./word.js";
+export { tutor, BUTTON_LABEL_MAX, TUTOR_BUTTONS_MAX, TutorButtonSchema } from "./tutor.js";
+export { dictation, dictationEmoji, dictationWordLang, DictationPropsSchema, DICTATION_EN_MAX, DICTATION_SAY_MAX, DICTATION_WORD_MAX, DICTATION_WORDS_MAX, EN_WORD_RE } from "./dictation.js";
+/** 全部种类:先板书的十一种(注册表顺序即技能里的顺序),再首页专属的 */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export const CARD_KINDS = [text, read, choice, image, tianzige, word, lecture, canvas, paint, photo, code, tutor, dictation];
+export function cardKind(name) {
+    return CARD_KINDS.find((k) => k.name === name);
+}
+/** 这种卡能不能用在这里(没写 where 的只板书) */
+export function usableIn(kind, place) {
+    return (kind.where ?? ['board']).includes(place);
+}
+/** 能用在某处的种类(注册表顺序) */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function kindsFor(place) {
+    return CARD_KINDS.filter((k) => usableIn(k, place));
+}
+/**
+ * 这位老师的板书写法里讲哪几种卡(cotutor.json tutors.<老师>.cards,《卡片协议.md》「谁拿到哪些卡」):
+ * 没写 = null(全部,递出厂的 cotutor-board SKILL.md);写了 = 板书能用的、按注册表顺序,text 总在(写坏的卡退成它)。
+ */
+export function tutorCardKinds(cards) {
+    if (!cards)
+        return null;
+    return kindsFor('board').map((k) => k.name).filter((k) => k === 'text' || cards.includes(k));
+}
+/** 正文是「字」的卡:老师把讲稿的 [词] 标注语法写进这些卡时,把括号剥掉(2026-09-11 真跑:孩子看到了「[直角边]」);choice 的 - [ ] / - [x] 不动 */
+const TEXTUAL = new Set(['text', 'read', 'choice', 'image', 'word', 'paint']);
+const MARK_IN_CARD = /\[([^\[\]\n]+)\]/g;
+function unmark(body) {
+    let had = false;
+    const out = body.replace(MARK_IN_CARD, (m, inner) => {
+        if (/^[ xX]$/.test(inner))
+            return m;
+        had = true;
+        return inner;
+    });
+    return { body: out, had };
+}
+/**
+ * 围栏 → 卡。标签第一个词是 kind,其余是修饰;不认识的标签:板书里当代码卡原样显示,首页里退文字卡;
+ * 认识但正文解析不出、或这种卡不能用在这里(place)→ 文字卡显示原文 + warning。永不抛错。
+ */
+export function parseCard(tag, body, place = 'board') {
+    const [name, ...mods] = tag.trim().split(/\s+/).filter(Boolean);
+    const asText = (why) => ({ card: { kind: 'text', props: { text: body.trim() || name || '…' } }, warning: why, fallback: true });
+    if (!name)
+        return place === 'board' ? { card: { kind: 'code', props: code.parse(body, []) } } : asText('围栏没写种类');
+    const kind = cardKind(name.toLowerCase());
+    if (!kind)
+        return place === 'board' ? { card: { kind: 'code', props: code.parse(body, [name]) } } : asText(`不认识的卡:${name}`);
+    if (!usableIn(kind, place))
+        return asText(place === 'board' ? `${name} 是首页的卡,板书里不能用` : `首页放不了 ${name} 卡(它要交给某位老师,只能在板书里)`);
+    const um = TEXTUAL.has(kind.name) ? unmark(body) : { body, had: false };
+    try {
+        const props = kind.props.parse(kind.parse(um.body, mods));
+        const notes = [um.had ? `卡里的方括号去掉了:${name} — [词] 标注只写在讲稿句里,不写在卡里` : null, kind.note?.(um.body, props) ?? null].filter((x) => Boolean(x));
+        return { card: { kind: kind.name, props }, ...(notes.length ? { warning: notes.join(';') } : {}) };
+    }
+    catch (err) {
+        const why = err instanceof z.ZodError ? err.issues.map((i) => `${i.path.join('.')}:${i.message}`).join(';') : err instanceof Error ? err.message : String(err);
+        return asText(`卡片没解析成:${name} — ${why}`);
+    }
+}
+/** 孩子端的一节:每张卡过本种卡的 strip(答案不下发);不认识的 kind 原样;孩子自己的状态与已生成的资产照给 */
+export function stripSecrets(section) {
+    return {
+        ...section,
+        cards: section.cards.map((c) => {
+            // 认不出的种类(删掉的卡:场景 10-07、填空 10-22):老对话里存下的退成一段字,只留它的那句,别的字段(答案、题面)不下发
+            const k = cardKind(c.kind);
+            if (!k)
+                return { ...c, kind: 'text', props: { text: typeof c.props.text === 'string' ? c.props.text : cardLabel(c) } };
+            return k.strip ? { ...c, props: k.strip(c.props) } : c;
+        }),
+    };
+}
+/** 一张卡的标题(舞台顶栏、给老师的描述里用):文字卡的 title / text,选择题的问题,其余第一段有字的,田字格的字,单词卡的词,听写卡的词表 */
+export function cardLabel(card) {
+    const p = card.props;
+    const s = (v) => (typeof v === 'string' ? v.trim() : '');
+    const first = s(p.title) || s(p.question) || s(p.show) || s(p.text) || s(p.caption) || s(p.prompt) || (Array.isArray(p.segments) ? s(p.segments[0]) : '') || s(p.chars) || s(p.word) || (Array.isArray(p.words) ? p.words.map((w) => s(w?.chars)).filter(Boolean).join('、') : '');
+    const cps = Array.from(first.replace(/\s+/g, ' '));
+    return cps.length > 40 ? `${cps.slice(0, 40).join('')}…` : cps.join('');
+}
+/** 这张卡要后台预生成的配音(文件名相对它的资产目录);没有的种类 → [] */
+export function cardAssets(card) {
+    const k = cardKind(card.kind);
+    if (!k?.assets)
+        return [];
+    const r = k.props.safeParse(card.props);
+    return r.success ? k.assets(r.data) : [];
+}
+/** 孩子端 PUT 上来的状态过本种卡的契约;这种卡没有状态、或不认识的 kind → 不收 */
+export function parseCardState(card, raw) {
+    const k = cardKind(card.kind);
+    if (!k?.state)
+        return { ok: false, why: `${card.kind} 卡没有状态` };
+    const r = k.state.safeParse(raw);
+    if (!r.success)
+        return { ok: false, why: r.error.issues.map((i) => `${i.path.join('.')}:${i.message}`).join(';') };
+    return { ok: true, state: r.data };
+}
+/**
+ * 给老师的一句:「choice「问题」 选了「B …」(答案:「…」)」。props 用索引里的(带答案),状态是孩子的;
+ * 没有 describe 的种类把状态原样 JSON。id 由调用方拼在前面(<job>/<n>)。
+ */
+export function describeCard(card, state) {
+    const k = cardKind(card.kind);
+    const head = `${card.kind}「${cardLabel(card)}」`;
+    if (!k?.describe || !k.state)
+        return `${head} ${JSON.stringify(state)}`;
+    const r = k.state.safeParse(state);
+    return `${head} ${r.success ? k.describe(card.props, r.data) : JSON.stringify(state)}`;
+}

package/dist/board/cards/kind.d.ts

@@ -0,0 +1,33 @@
+/**
+ * 一种卡的服务端定义(见 docs/卡片协议.md):props 契约、围栏正文怎么解析、哪些字段不下发孩子端;给老师看的写法在包根 cards/<kind>/card.md(src/board/cards/docs.ts 读它);
+ * 有交互的卡再加 state 契约(孩子在卡上做的事,PUT 进来先过它)与 describe(把 props + state 说成给老师看的一句,进上下文包)。
+ * 页面那一半(紧凑态怎么画、舞台里怎么交互、标注落在哪些字上)在 kid-page.ts / board/presentation.ts;两边靠 kind 名对上。
+ */
+import type { z } from 'zod';
+/** 卡用在哪:板书(老师的回复)/ 首页(家长批准的那页) */
+export type CardPlace = 'board' | 'home';
+export interface CardKind<P = Record<string, unknown>, S = unknown> {
+    name: string;
+    /** 能用在哪;缺省只板书。首页专属的卡(tutor 等)不进 cotutor-board 技能,老师写了退文字卡 */
+    where?: readonly CardPlace[];
+    props: z.ZodType<P>;
+    /** 围栏正文 + 标签后的修饰词 → props;抛错 = 没解析成(退成文字卡显示原文,家长视图报一行) */
+    parse(body: string, mods: readonly string[]): P;
+    /** 解析成了、但正文有一部分没用上(田字格的拼音对不上字数):给家长视图的一句;没有 / null = 不报 */
+    note?(body: string, props: P): string | null;
+    /** 剥掉不下发孩子端的字段(答案);没有 = 全给 */
+    strip?(props: P): P;
+    /** 孩子在卡上做的事的形状;没有 = 这种卡没有状态,PUT 一律 400 */
+    state?: z.ZodType<S>;
+    /** props + state → 给老师看的一句(不含卡的标题,那句由注册表拼);没有 = 状态原样 JSON */
+    describe?(props: P, state: S): string;
+    /** 这张卡要在后台预生成的配音资产(点读的段):文件名相对这张卡的资产目录 <日期>.<job>.cards/<n>/,text 是要念的字 */
+    assets?(props: P): {
+        file: string;
+        text: string;
+    }[];
+}
+/** 课包 / 视频小课堂的 id(bundles/<id>/、lectures/<id>/):lecture 卡、画板的底、首页的小课堂按钮共用 */
+export declare const BUNDLE_ID_RE: RegExp;
+/** 围栏正文 → 非空行(各自 trim) */
+export declare function bodyLines(body: string): string[];

package/dist/board/cards/kind.js

@@ -0,0 +1,9 @@
+/** 课包 / 视频小课堂的 id(bundles/<id>/、lectures/<id>/):lecture 卡、画板的底、首页的小课堂按钮共用 */
+export const BUNDLE_ID_RE = /^[a-z0-9][a-z0-9-]{0,80}$/;
+/** 围栏正文 → 非空行(各自 trim) */
+export function bodyLines(body) {
+    return body
+        .split('\n')
+        .map((l) => l.trim())
+        .filter(Boolean);
+}

package/dist/board/cards/lecture.d.ts

@@ -0,0 +1,26 @@
+/**
+ * 小课堂卡:老师答孩子时放课里的一段,不另讲一遍。正文第一行「<课包或视频的 id> 0:19-0:30」,第二行可以写一句给孩子的话。
+ * 拿现成的课包或视频(家长做的);时间照上下文包 lecture.lines 抄。
+ * 课名、真放的起止(对齐到段界,board/lecture.ts lectureRange)、能不能放(ready)、末帧停在 SVG 的哪一刻,都是服务端下发时从课包现算的快照(src/runtime/lecture.ts 的 enrichLectures)。
+ * 状态 = 那一段看完没;讲稿 [[play]] 锚到它:念到那句,铺满放那一段(课里原来的声音),放完停在末帧接着念。
+ */
+import { z } from 'zod';
+import { type CardKind } from './kind.ts';
+export declare const LecturePropsSchema: z.ZodObject<{
+    bundle: z.ZodString;
+    from: z.ZodOptional<z.ZodNumber>;
+    to: z.ZodOptional<z.ZodNumber>;
+    text: z.ZodOptional<z.ZodString>;
+    title: z.ZodOptional<z.ZodString>;
+    start: z.ZodOptional<z.ZodNumber>;
+    end: z.ZodOptional<z.ZodNumber>;
+    still: z.ZodOptional<z.ZodNumber>;
+    ready: z.ZodOptional<z.ZodBoolean>;
+    video: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export type LectureProps = z.infer<typeof LecturePropsSchema>;
+export declare const LectureStateSchema: z.ZodObject<{
+    done: z.ZodBoolean;
+}, z.core.$strip>;
+export type LectureState = z.infer<typeof LectureStateSchema>;
+export declare const lecture: CardKind<LectureProps, LectureState>;