ai-growth 1.1.0

package/dist/device/card.js

@@ -0,0 +1,257 @@
+const ESC = {
+    '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;',
+};
+/** 目标/任务标题来自用户输入，进 HTML 前必须转义 */
+export function esc(s) {
+    return String(s).replace(/[&<>"']/g, (c) => ESC[c]);
+}
+const CSS = `
+*{margin:0;padding:0;box-sizing:border-box}
+html,body{width:240px;height:320px;background:#000;overflow:hidden;
+  font-family:"PingFang SC","Hiragino Sans GB","Heiti SC","Microsoft YaHei",sans-serif;
+  -webkit-font-smoothing:antialiased;font-variant-numeric:tabular-nums}
+.card{position:relative;width:240px;height:320px;border-radius:30px;overflow:hidden;color:#eaf4ff;
+  background:radial-gradient(130% 85% at 18% -5%,#13324b 0%,#0c1c2b 52%,#060d15 100%)}
+.card::after{content:"";position:absolute;inset:0;border-radius:30px;
+  box-shadow:inset 0 0 0 1px rgba(140,190,225,.13)}
+.hd{display:flex;justify-content:space-between;align-items:center;
+  padding:15px 18px 0 18px;font-size:11px;color:#7fa8c4;letter-spacing:.2px}
+.bat{display:flex;align-items:center;gap:3px}
+.bat .b{width:22px;height:10px;border:1.5px solid #6f97b2;border-radius:3px;padding:1.5px}
+.bat .b i{display:block;height:100%;border-radius:1px;background:#4ade80}
+.bat .b i.low{background:#f87171}
+.bat .b i.mid{background:#fbbf24}
+.bat .c{width:2px;height:5px;background:#6f97b2;border-radius:0 1px 1px 0;margin-left:-3px}
+.bat .n{font-size:10px;color:#89aec6}
+.wrap{padding:14px 18px 0 18px}
+.track{display:flex;align-items:center;gap:5px}
+.nd{width:11px;height:11px;border-radius:3px;flex:none}
+.nd.done{background:#4ade80}
+.nd.cur{background:#ffd166;box-shadow:0 0 9px rgba(255,209,102,.55)}
+.nd.todo{border:1.5px solid #35566b}
+.stg{margin-top:9px;font-size:11.5px;color:#8fb6cf;white-space:nowrap;overflow:hidden;text-overflow:ellipsis}
+.kick{font-size:9.5px;letter-spacing:1.6px;color:#ffd166;font-weight:500}
+.kick.dim{color:#6f97b2}
+.ttl{margin-top:9px;font-weight:600;line-height:1.34;word-break:break-word;
+  display:-webkit-box;-webkit-box-orient:vertical;-webkit-line-clamp:3;overflow:hidden}
+.ttl.s1{font-size:23px}
+.ttl.s2{font-size:19px}
+.ttl.s3{font-size:16px}
+.meta{margin-top:11px;font-size:11px;color:#7fa8c4;line-height:1.6;word-break:break-word;
+  display:-webkit-box;-webkit-box-orient:vertical;-webkit-line-clamp:4;overflow:hidden}
+.ft{position:absolute;left:0;right:0;bottom:0;padding:0 18px 15px 18px}
+.bar{height:4px;border-radius:2px;background:#1c3547;overflow:hidden}
+.bar i{display:block;height:100%;background:linear-gradient(90deg,#4ade80,#a3e635)}
+.bar i.full{background:linear-gradient(90deg,#4ade80,#86efac)}
+.hint{margin-top:9px;display:flex;justify-content:space-between;font-size:10px;color:#5d7f96}
+.list{margin-top:13px;display:flex;flex-direction:column;gap:8px}
+.row{display:flex;align-items:flex-start;gap:8px;font-size:12px;line-height:1.35}
+.tick{width:15px;height:15px;border-radius:5px;flex:none;margin-top:1px;position:relative;
+  border:1.5px solid #3d6277}
+.row.ok .tick{background:#4ade80;border-color:#4ade80}
+.row.ok .tick::after{content:"";position:absolute;left:4.5px;top:1.5px;width:4px;height:8px;
+  border:2px solid #062417;border-top:0;border-left:0;transform:rotate(42deg)}
+.row.ok .tx{color:#5d7f96;text-decoration:line-through}
+.row.now .tick{border-color:#ffd166}
+.tx{flex:1;word-break:break-word;display:-webkit-box;-webkit-box-orient:vertical;
+  -webkit-line-clamp:2;overflow:hidden}
+.tag{margin-left:6px;font-size:9px;padding:1px 5px;border-radius:4px;
+  background:rgba(255,209,102,.16);color:#ffd166;vertical-align:1px}
+.big{position:absolute;left:0;right:0;top:74px;text-align:center;padding:0 22px}
+.ring{width:76px;height:76px;margin:0 auto;border-radius:50%;position:relative;
+  background:radial-gradient(circle at 50% 40%,rgba(74,222,128,.22),rgba(74,222,128,.04) 70%)}
+.ring::after{content:"";position:absolute;left:26px;top:20px;width:19px;height:34px;
+  border:4px solid #4ade80;border-top:0;border-left:0;transform:rotate(42deg);border-radius:2px}
+.big h2{margin-top:16px;font-size:22px;font-weight:600}
+.big p{margin-top:9px;font-size:11.5px;color:#7fa8c4;line-height:1.7}
+.facts{margin:16px 20px 0;display:flex;gap:8px;position:absolute;left:0;right:0;top:196px}
+.fact{flex:1;text-align:center;background:rgba(120,180,220,.07);border-radius:10px;padding:9px 4px}
+.fact b{display:block;font-size:17px;font-weight:600;color:#eaf4ff}
+.fact span{font-size:9.5px;color:#7fa8c4}
+/* 完成页：用 flex 纵向排布，避免绝对定位的统计卡把上面的文字压住（实测会重叠）。
+   ⚠ 容器类名【不能】叫 .done —— 阶段节点轨道里的已完成格子是 .nd.done，
+     两个 .done 会互相命中：所有已完成的节点会被这条 position:absolute 抓住，
+     全部叠成卡片左上角的一个绿点，轨道上的进度就看不见了。
+     所以页级容器统一用与「状态」不重名的词（finish / big / facts）。 */
+.finish{position:absolute;left:0;right:0;top:38px;bottom:44px;display:flex;flex-direction:column;
+  justify-content:space-between}
+.finish .dc{display:flex;flex-direction:column;align-items:center;text-align:center;padding:0 22px}
+.finish .dc h2{margin-top:16px;font-size:22px;font-weight:600}
+.finish .dc p{margin-top:9px;font-size:11.5px;color:#7fa8c4;line-height:1.7}
+.finish .facts{position:static;left:auto;right:auto;top:auto;margin:0 20px;display:flex;gap:8px}
+.icon{width:60px;height:60px;margin:0 auto;position:relative;opacity:.95}
+.icon.warn{border-radius:50%;background:rgba(251,191,36,.14)}
+.icon.warn::after{content:"";position:absolute;left:28px;top:14px;width:4px;height:20px;
+  border-radius:2px;background:#fbbf24}
+.icon.warn::before{content:"";position:absolute;left:28px;top:40px;width:4px;height:4px;
+  border-radius:50%;background:#fbbf24}
+.icon.sync{border-radius:50%;background:rgba(127,168,196,.12)}
+.icon.sync::after{content:"";position:absolute;left:17px;top:17px;width:26px;height:26px;
+  border-radius:50%;border:3px solid #7fa8c4;border-right-color:transparent;border-bottom-color:transparent;
+  transform:rotate(-45deg)}
+.icon.sync::before{content:"";position:absolute;left:16px;top:11px;width:0;height:0;
+  border:6px solid transparent;border-bottom-color:#7fa8c4;border-top:0}
+.spin{animation:none}
+`;
+function battery(soc) {
+    if (soc === null || soc < 0) {
+        return '<div class="bat"><div class="b"><i style="width:0"></i></div><div class="c"></div></div>';
+    }
+    const pct = Math.max(0, Math.min(100, Math.round(soc)));
+    const cls = pct < 20 ? 'low' : pct < 50 ? 'mid' : '';
+    return `<div class="bat"><div class="b"><i class="${cls}" style="width:${pct}%"></i></div><div class="c"></div><span class="n">${pct}%</span></div>`;
+}
+/** 节点轨道最多画这么多格，超了就只画当前阶段附近的窗口（真值看下面的文字） */
+const TRACK_MAX = 12;
+function track(stage) {
+    if (!stage)
+        return '';
+    const { total, order } = stage;
+    // 阶段数过多时轨道会横向溢出（240px 放不下）；此时窗口化显示，
+    // 权威数字始终由下面那行「阶段 order/total · 标题」给出。
+    const shown = Math.min(total, TRACK_MAX);
+    const start = total > TRACK_MAX
+        ? Math.min(Math.max(order - Math.floor(TRACK_MAX / 2), 1), total - TRACK_MAX + 1)
+        : 1;
+    const nodes = [];
+    for (let i = 0; i < shown; i++) {
+        const n = start + i;
+        const cls = n < order ? 'done' : n === order ? 'cur' : 'todo';
+        nodes.push(`<div class="nd ${cls}"></div>`);
+    }
+    return `<div class="wrap"><div class="track">${nodes.join('')}</div>
+    <div class="stg">阶段 ${order}/${total} · ${esc(stage.title)}</div></div>`;
+}
+/** 标题越长字号越小，保证一定放得下 */
+function titleClass(t) {
+    const n = [...t].length;
+    if (n <= 12)
+        return 's1';
+    if (n <= 20)
+        return 's2';
+    return 's3';
+}
+/**
+ * 卡壳。
+ * ⚠ dateLabel 为空时【不画日期】：固件内置兜底卡（未配置/离线/开机）是构建期渲染的，
+ *   而设备没有备电 RTC。把构建那天的日期画进图里，等于让设备天天说"今天是构建日"——
+ *   这正是铁律 8 要禁的伪造时间。时间只能来自服务端。
+ */
+function shell(inner, st) {
+    return `<!DOCTYPE html><html lang="zh-CN"><head><meta charset="utf-8">
+<style>${CSS}</style></head><body><div class="card">
+<div class="hd"><div>${st.dateLabel ? esc(st.dateLabel) : ''}</div>${battery(st.battery)}</div>
+${inner}
+</div></body></html>`;
+}
+/** 今日总览：阶段轨道 + 条目列表 + 进度 */
+function overview(st) {
+    const rows = st.items.map((it) => {
+        const cls = it.done ? 'ok' : it.kind === 'MAIN_QUEST' ? 'now' : '';
+        const tag = it.kind === 'MAIN_QUEST' ? '<span class="tag">主线</span>' : '';
+        return `<div class="row ${cls}"><div class="tick"></div><div class="tx">${esc(it.title)}${tag}</div></div>`;
+    }).join('');
+    const pct = st.total ? Math.round((st.doneCount / st.total) * 100) : 0;
+    return shell(`${track(st.stage)}
+    <div class="wrap"><div class="kick">今天要做的事</div>
+    <div class="list">${rows || '<div class="row"><div class="tx" style="color:#5d7f96">今天没有安排</div></div>'}</div></div>
+    <div class="ft"><div class="bar"><i style="width:${pct}%"></i></div>
+    <div class="hint"><span>完成 ${st.doneCount} / ${st.total}</span><span>上下键切换 · 确定查看</span></div></div>`, st);
+}
+/** 单条任务：大字标题 + 为什么今天 + 完成标准 */
+function task(st, spec) {
+    const it = st.items[spec.itemIndex ?? 0];
+    if (!it)
+        return overview(st);
+    const isMain = it.kind === 'MAIN_QUEST';
+    const metaBits = [];
+    if (it.minutes)
+        metaBits.push(`约 ${it.minutes} 分钟`);
+    if (it.why)
+        metaBits.push(esc(it.why));
+    if (it.completionCriteria)
+        metaBits.push(`完成标准：${esc(it.completionCriteria)}`);
+    const pct = st.total ? Math.round((st.doneCount / st.total) * 100) : 0;
+    return shell(`${track(st.stage)}
+    <div class="wrap"><div class="kick${isMain ? '' : ' dim'}">${isMain ? '今天这一件事' : '今天的小事'}</div>
+    <div class="ttl ${titleClass(it.title)}">${esc(it.title)}</div>
+    ${metaBits.length ? `<div class="meta">${metaBits.join('<br>')}</div>` : ''}</div>
+    <div class="ft"><div class="bar"><i style="width:${pct}%"></i></div>
+    <div class="hint"><span>完成 ${st.doneCount} / ${st.total}</span><span>${it.done ? '已完成' : '确定 = 完成'}</span></div></div>`, st);
+}
+/** 全部完成 */
+function alldone(st) {
+    const ev = st.facts?.evidence ?? 0;
+    const mainDone = st.facts?.mainDone ?? 0;
+    return shell(`<div class="finish">
+    <div class="dc">
+      <div class="ring"></div>
+      <h2>今天做完了</h2>
+      <p>${esc(st.dateLabel)}${st.stage ? `<br>阶段推进到 ${st.stage.order}/${st.stage.total}` : '<br>继续保持'}</p>
+    </div>
+    <div class="facts">
+      <div class="fact"><b>${st.doneCount}/${st.total}</b><span>今日任务</span></div>
+      <div class="fact"><b>${ev}</b><span>累积证据</span></div>
+      <div class="fact"><b>${mainDone}</b><span>主线完成</span></div>
+    </div>
+  </div>
+  <div class="ft"><div class="bar"><i class="full" style="width:100%"></i></div>
+  <div class="hint"><span>全部完成</span><span>上下键回看</span></div></div>`, st);
+}
+/** 今天还没排计划（能连上电脑，但 Agent 还没排） */
+function noplan(st) {
+    return shell(`<div class="big">
+    <div class="icon warn"></div>
+    <h2>今天还没排计划</h2>
+    <p>回家跟 Agent 说一声<br>「开启今日任务」<br>它会把今天安排到这张卡上</p>
+  </div>
+  <div class="ft"><div class="hint" style="justify-content:center"><span>${esc(st.dateLabel)}</span></div></div>`, st);
+}
+/**
+ * 连不上电脑（固件内置兜底卡）。
+ * 这里刻意不写"上次同步：xx"——构建期渲染的卡不知道用户哪天开机，写死一个时间就是假的。
+ */
+function offline(st) {
+    return shell(`<div class="big">
+    <div class="icon sync"></div>
+    <h2>暂时连不上电脑</h2>
+    <p>回到家里同一个 Wi-Fi 就会自动同步<br>按「确定」可以立刻重试</p>
+  </div>
+  <div class="ft"><div class="hint"><span>确定 = 重试</span><span>上下键 = 翻卡</span></div></div>`, st);
+}
+/** 正在连接（固件内置兜底卡） */
+function booting(st) {
+    return shell(`<div class="big" style="top:96px">
+    <p style="font-size:14px;font-weight:600;color:#eaf4ff;letter-spacing:.3px">FoloToy AI Passport</p>
+    <p style="font-size:11px;color:#7fa8c4;margin-top:8px">自驱动成长工具</p>
+    <div class="bar" style="margin:22px 14px 0 14px"><i style="width:38%"></i></div></div>
+  <div class="ft"><div class="hint" style="justify-content:center"><span>正在连接电脑…</span></div></div>`, st);
+}
+/**
+ * 未配置（固件内置兜底卡）——告诉用户下一步做什么，而不是报错。
+ *
+ * ⚠ 文案必须指向**一条命令**：这条卡是刷完固件后开机第一眼看到的东西，
+ *   如果写"用串口把 Wi-Fi 填进来"，用户就得装工具链、找串口、还躲不过
+ *   "串口只能输 ASCII、中文 Wi-Fi 名填不进去"这个坑 —— 那就不是能发布的应用了。
+ *   所以直接给出 `ai-growth device setup`，那条命令会自动处理 hex 与验证。
+ */
+function setup(st) {
+    return shell(`<div class="big">
+    <div class="icon warn"></div>
+    <h2>还没连上电脑</h2>
+    <p>在电脑上跑一条命令就配好：<br>ai-growth device setup<br>--ssid "Wi-Fi名" --pass "密码"</p>
+  </div>
+  <div class="ft"><div class="hint" style="justify-content:center"><span>配好后会自动重启并取卡</span></div></div>`, st);
+}
+export function buildCardHtml(st, spec) {
+    switch (spec.kind) {
+        case 'overview': return overview(st);
+        case 'task': return task(st, spec);
+        case 'alldone': return alldone(st);
+        case 'noplan': return noplan(st);
+        case 'offline': return offline(st);
+        case 'booting': return booting(st);
+        case 'setup': return setup(st);
+        default: return overview(st);
+    }
+}

package/dist/device/deck.js

@@ -0,0 +1,157 @@
+/**
+ * 设备「今日卡」的牌组模型与二进制载荷编码。
+ *
+ * 设计要点：
+ *   - 牌组由**服务端**决定（几张卡、每张是什么）。设备是纯显示器 + 遥控器，
+ *     只按 index 取图，不需要理解"什么是今日主线"。这样设备端逻辑极小、
+ *     也不会和电脑产生理解偏差。
+ *   - meta 段是小的 JSON（固件用 cJSON 解析），像素段是裸 RGB565 小端，
+ *     固件按 band 流式读取、逐段 blit，不需要在 RAM 里装下整张 153KB 图。
+ */
+import { createHash } from 'node:crypto';
+import { getActiveGoals, getCurrentStage, listStages } from '../core/goals.js';
+import { getTodayPlan } from '../core/actions.js';
+import { resolveTimezone } from '../core/profile.js';
+export const MAGIC = Buffer.from('AGCD', 'ascii');
+export const PAYLOAD_VERSION = 1;
+export const PIXEL_FORMAT_RGB565_LE = 1;
+export const CARD_W = 240;
+export const CARD_H = 320;
+export const HEADER_SIZE = 14;
+/** "9月20日 周日" —— 一律按配置时区算（铁律 8：绝不按 UTC 截断） */
+export function dateLabelIn(tz, at = new Date()) {
+    const parts = new Intl.DateTimeFormat('zh-CN', {
+        timeZone: tz, month: 'numeric', day: 'numeric', weekday: 'short',
+    }).formatToParts(at);
+    const get = (t) => parts.find((p) => p.type === t)?.value ?? '';
+    return `${get('month')}月${get('day')}日 ${get('weekday')}`;
+}
+function countRows(ctx, from) {
+    return ctx.db.prepare(`SELECT COUNT(*) AS n FROM ${from}`).get().n;
+}
+/** 从 Core 汇总出设备卡的展示状态。只读，不改任何状态。 */
+export function buildCardState(ctx, opts = {}) {
+    const tz = resolveTimezone(ctx);
+    const { plan, actions } = getTodayPlan(ctx);
+    const goals = getActiveGoals(ctx);
+    const primary = goals[0];
+    const stages = primary ? listStages(ctx, primary.id) : [];
+    const current = primary ? getCurrentStage(ctx, primary.id) : null;
+    const items = actions.map((a) => ({
+        id: a.id,
+        kind: a.kind,
+        title: a.title,
+        status: a.status,
+        done: a.status === 'COMPLETED',
+        minutes: a.estimatedMinutes ?? undefined,
+        why: a.whyToday ?? undefined,
+        completionCriteria: a.completionCriteria ?? undefined,
+    }));
+    const doneCount = items.filter((i) => i.done).length;
+    return {
+        dateLabel: dateLabelIn(tz),
+        dateKey: plan?.dateKey ?? dateLabelIn(tz),
+        stage: current && stages.length ? { title: current.title, order: current.order, total: stages.length } : null,
+        items,
+        doneCount,
+        total: items.length,
+        battery: opts.battery ?? null,
+        facts: {
+            evidence: countRows(ctx, 'evidence'),
+            mainDone: countRows(ctx, `actions WHERE kind='MAIN_QUEST' AND status='COMPLETED' AND deleted_at IS NULL`),
+        },
+        offlineSince: opts.offlineSince,
+    };
+}
+/** 牌组内容指纹：条目状态变了（比如完成了一件）就换 id，设备据此判断要重取 */
+export function deckIdOf(state) {
+    const key = [state.dateKey, state.items.map((i) => `${i.id}:${i.status}`).join(','), state.total].join('|');
+    return createHash('sha256').update(key).digest('hex').slice(0, 12);
+}
+/**
+ * 排牌组。
+ * 有任务：总览 → 每条任务各一张 →（全部完成时）完成页
+ * 没任务：单张「今天还没排计划」
+ */
+export function buildDeck(state) {
+    if (state.items.length === 0) {
+        return [{ kind: 'noplan', title: '今天还没排计划' }];
+    }
+    const cards = [{ kind: 'overview', title: '今日总览' }];
+    state.items.forEach((it, i) => {
+        cards.push({
+            kind: 'task',
+            itemIndex: i,
+            title: `${it.kind === 'MAIN_QUEST' ? '主线' : '小事'}：${it.title}`,
+        });
+    });
+    if (state.doneCount === state.total && state.total > 0) {
+        cards.push({ kind: 'alldone', title: '今天做完了' });
+    }
+    return cards;
+}
+/** 这张卡上按「确定」应当执行的动作（只有未完成的任务卡有） */
+export function actionIdFor(state, spec) {
+    if (spec.kind !== 'task' || spec.itemIndex === undefined)
+        return null;
+    const it = state.items[spec.itemIndex];
+    if (!it || it.done)
+        return null;
+    return it.id;
+}
+export function buildCardMeta(state, spec, index, count) {
+    return {
+        v: PAYLOAD_VERSION,
+        deckId: deckIdOf(state),
+        index,
+        count,
+        kind: spec.kind,
+        actionId: actionIdFor(state, spec),
+        doneCount: state.doneCount,
+        total: state.total,
+        battery: state.battery,
+        dateKey: state.dateKey,
+        dateLabel: state.dateLabel,
+    };
+}
+/** 头部 + meta JSON + 裸 RGB565 —— 固件流式解析，不需要整图进 RAM */
+export function encodeCardPayload(meta, pixels) {
+    if (pixels.length !== CARD_W * CARD_H * 2) {
+        throw new Error(`CARD_PAYLOAD: 像素长度 ${pixels.length}，期望 ${CARD_W * CARD_H * 2}`);
+    }
+    const metaBuf = Buffer.from(JSON.stringify(meta), 'utf8');
+    const head = Buffer.alloc(HEADER_SIZE);
+    MAGIC.copy(head, 0);
+    head.writeUInt8(PAYLOAD_VERSION, 4);
+    head.writeUInt8(PIXEL_FORMAT_RGB565_LE, 5);
+    head.writeUInt16LE(CARD_W, 6);
+    head.writeUInt16LE(CARD_H, 8);
+    head.writeUInt32LE(metaBuf.length, 10);
+    return Buffer.concat([head, metaBuf, pixels]);
+}
+/** 与固件对称的解析实现，用于测试与模拟器 */
+export function decodeCardPayload(buf) {
+    if (buf.length < HEADER_SIZE)
+        throw new Error('CARD_PAYLOAD: 太短');
+    if (!buf.subarray(0, 4).equals(MAGIC))
+        throw new Error('CARD_PAYLOAD: magic 不匹配');
+    const version = buf.readUInt8(4);
+    if (version !== PAYLOAD_VERSION)
+        throw new Error(`CARD_PAYLOAD: 版本 ${version} 不支持`);
+    if (buf.readUInt8(5) !== PIXEL_FORMAT_RGB565_LE)
+        throw new Error('CARD_PAYLOAD: 像素格式不支持');
+    const w = buf.readUInt16LE(6);
+    const h = buf.readUInt16LE(8);
+    const metaLen = buf.readUInt32LE(10);
+    if (w !== CARD_W || h !== CARD_H)
+        throw new Error(`CARD_PAYLOAD: 尺寸 ${w}x${h} 不符`);
+    const metaEnd = HEADER_SIZE + metaLen;
+    if (buf.length < metaEnd)
+        throw new Error('CARD_PAYLOAD: meta 被截断');
+    const meta = JSON.parse(buf.toString('utf8', HEADER_SIZE, metaEnd));
+    const pixels = buf.subarray(metaEnd);
+    if (pixels.length !== CARD_W * CARD_H * 2) {
+        throw new Error(`CARD_PAYLOAD: 像素段 ${pixels.length} 字节不符`);
+    }
+    return { meta, pixels: Buffer.from(pixels) };
+}

package/dist/device/fontCoverage.js

@@ -0,0 +1,162 @@
+/**
+ * 中文字形覆盖检查（宿主侧）。
+ *
+ * 为什么设备端的字体问题要在宿主侧解决：
+ *   AI Passport 固件里能用的中文字体是「子集」——官方文档 lvgl-chinese-fonts.md 明确说
+ *   内置的 Source Han Sans 只是部分字形，而默认 Montserrat 一个汉字都没有。
+ *   我们的做法是让【卡片的每一个字都变成像素】（服务端 Chrome 出图 → RGB565 → 设备直写屏幕），
+ *   设备端不调用任何文本绘制。于是「字体覆盖」这件事整体搬到了宿主：
+ *   只要宿主渲染时没画出豆腐块，设备上就不可能出现豆腐块。
+ *
+ * 这个文件就是那条保证的检查器。它不用任何新依赖：直接让同一套 Chrome 渲染一张
+ * 「每格一个字符」的网格图，再把每格与【已知缺字】的参考格做位图比对。
+ *
+ * 方法边界（必须说清，不要夸大）：
+ *   - 它检测的是「宿主实际画出来的结果」，不是字体 cmap。缺字在 Chrome 里会落成
+ *     .notdef（豆腐块）或者空白，这两种都能被抓到；但如果某个 fallback 字体把缺字
+ *     画成了另一个形状，本检查会漏判。
+ *   - 所以内置了一个【负对照】：U+E010（私用区，任何字体都没有映射）必须被判为缺字，
+ *     并且与已知存在的 'A' 必须判为不同。负对照不成立就直接报 detector 失效，
+ *     而不是「全部通过」——否则这个检查就是摆设。
+ */
+import { decodePng } from './png.js';
+import { screenshotPng } from './render.js';
+/** 单元格边长。28px 字号的中文在这个尺寸里不会贴边，留出抗锯齿余量。 */
+export const CELL = 40;
+const FONT_SIZE = 28;
+const COLS = 16;
+/** 单次渲染的最大行数：再高就分批，避免一张巨图。 */
+const MAX_ROWS = 24;
+/** 私用区码点，任何常见字体都不提供映射 —— 用它当"缺字长相"的参考。 */
+export const CTRL_MISSING = '\uE010';
+/** 已知存在的中文字（"爱"）与拉丁字母，用来确认检查器确实能区分"有字形"。 */
+export const CTRL_PRESENT = 'A';
+export const CTRL_PRESENT_CJK = '\u7231';
+const FONT_STACK = '"PingFang SC","Hiragino Sans GB","Heiti SC","Microsoft YaHei",sans-serif';
+/** 位图完全一致（含长度）*/
+export function masksEqual(a, b) {
+    if (a.length !== b.length)
+        return false;
+    for (let i = 0; i < a.length; i++)
+        if (a[i] !== b[i])
+            return false;
+    return true;
+}
+function hasInk(mask) {
+    for (let i = 0; i < mask.length; i++)
+        if (mask[i])
+            return true;
+    return false;
+}
+/**
+ * 纯函数：给定「字符 → 单元格墨迹位图」，判定哪些字符缺字形。
+ * 与 Chrome 解耦，因此可以在单元测试里用合成位图覆盖（含负对照失效的分支）。
+ */
+export function classifyCoverage(masks) {
+    const refMissing = masks.get(CTRL_MISSING);
+    const refLatin = masks.get(CTRL_PRESENT);
+    const refCjk = masks.get(CTRL_PRESENT_CJK);
+    // 负对照必须三个方向都比：参考"缺字"要区别于拉丁真字形、也要区别于中文真字形，
+    // 并且两个真字形彼此可区分。少比 refMissing↔refCjk 这一条，就会出现
+    // 「参考缺字其实画的是中文真字形」而检查照样"通过"的假阳性 —— 那样整个检查就是摆设。
+    const detectorOk = !!refMissing && !!refLatin && !!refCjk &&
+        !masksEqual(refMissing, refLatin) &&
+        !masksEqual(refMissing, refCjk) &&
+        !masksEqual(refLatin, refCjk);
+    // 对照不成立就一个字符都不判：宁可报"检查无效"，也不给出一份不可信的结论。
+    if (!detectorOk) {
+        return {
+            ok: false,
+            missing: [],
+            noInk: [],
+            detectorOk: false,
+            checked: 0,
+            message: `字形覆盖检查不可信：负对照失效（U+E010 与 'A'/爱 的渲染结果相同或缺失），未判定任何字符`,
+        };
+    }
+    const missing = [];
+    const noInk = [];
+    let checked = 0;
+    for (const [ch, mask] of masks) {
+        if (ch === CTRL_MISSING || ch === CTRL_PRESENT || ch === CTRL_PRESENT_CJK)
+            continue;
+        if (/^\s$/.test(ch))
+            continue; // 空格不参与判定
+        checked++;
+        if (!hasInk(mask)) {
+            noInk.push(ch);
+            continue;
+        }
+        // 与参考豆腐块位图一致 = 这个字符没有字形
+        if (refMissing && masksEqual(mask, refMissing))
+            missing.push(ch);
+    }
+    const ok = missing.length === 0 && noInk.length === 0;
+    const message = ok
+        ? `字形覆盖：${checked} 个字符全部有字形（负对照有效）`
+        : `字形覆盖失败：缺字形 ${missing.length} 个${missing.length ? `（${missing.slice(0, 20).join('')}）` : ''}` +
+            `${noInk.length ? `，无墨迹 ${noInk.length} 个（${noInk.slice(0, 20).join('')}）` : ''}`;
+    return { ok, missing, noInk, detectorOk, checked, message };
+}
+function escapeHtmlChar(ch) {
+    const c = ch.codePointAt(0) ?? 0;
+    return `&#x${c.toString(16).toUpperCase()};`;
+}
+/** 生成一屏绝对定位的字符网格；绝对定位是为了让单元格与像素坐标严格对齐。 */
+function buildGridHtml(chars) {
+    const rows = Math.ceil(chars.length / COLS);
+    const width = COLS * CELL;
+    const height = rows * CELL;
+    const cells = chars.map((ch, i) => {
+        const x = (i % COLS) * CELL;
+        const y = Math.floor(i / COLS) * CELL;
+        return `<span style="position:absolute;left:${x}px;top:${y}px;width:${CELL}px;height:${CELL}px;` +
+            `line-height:${CELL}px;text-align:center;font-size:${FONT_SIZE}px;overflow:hidden">${escapeHtmlChar(ch)}</span>`;
+    }).join('');
+    const html = `<!DOCTYPE html><html lang="zh-CN"><head><meta charset="utf-8"><style>
+*{margin:0;padding:0;box-sizing:border-box}
+html,body{width:${width}px;height:${height}px;background:#ffffff;overflow:hidden;
+  font-family:${FONT_STACK};-webkit-font-smoothing:antialiased;color:#000000}
+</style></head><body>${cells}</body></html>`;
+    return { html, width, height };
+}
+/**
+ * 渲染网格并抽出每个字符的墨迹位图。
+ * 返回的 Map 一定包含三个对照字符，调用方不必自己补。
+ */
+export async function renderGlyphMasks(text) {
+    const uniq = [...new Set([...text])].filter((c) => c !== '\n' && c !== '\r' && c !== '\t');
+    // 只保留「可打印」字符？不：把全部字符都测一遍更保险，制表符等已在上面剔除。
+    const all = [CTRL_MISSING, CTRL_PRESENT, CTRL_PRESENT_CJK, ...uniq];
+    const masks = new Map();
+    for (let start = 0; start < all.length; start += COLS * MAX_ROWS) {
+        const batch = all.slice(start, start + COLS * MAX_ROWS);
+        const { html, width, height } = buildGridHtml(batch);
+        const png = await screenshotPng(html, { width, height });
+        const img = decodePng(png);
+        if (img.width !== width || img.height !== height) {
+            throw new Error(`FONT_COVERAGE_SIZE: 网格渲染出 ${img.width}x${img.height}，期望 ${width}x${height}`);
+        }
+        for (let i = 0; i < batch.length; i++) {
+            const cx = (i % COLS) * CELL;
+            const cy = Math.floor(i / COLS) * CELL;
+            const mask = new Uint8Array(CELL * CELL);
+            for (let y = 0; y < CELL; y++) {
+                for (let x = 0; x < CELL; x++) {
+                    // cell 内坐标 (x, y) → 图像坐标
+                    const px = cx + x;
+                    const py = cy + y;
+                    const s = (py * img.width + px) * img.channels;
+                    const lum = (img.data[s] * 299 + img.data[s + 1] * 587 + img.data[s + 2] * 114) / 1000;
+                    mask[y * CELL + x] = lum < 160 ? 1 : 0;
+                }
+            }
+            masks.set(batch[i], mask);
+        }
+    }
+    return masks;
+}
+/** 端到端：给一段文本，返回覆盖检查结论。 */
+export async function checkGlyphCoverage(text) {
+    return classifyCoverage(await renderGlyphMasks(text));
+}