@pi-flash-plugins/pf-wxbot 0.0.0-stage → 0.1.3

package/pi/qr.mjs

@@ -0,0 +1,454 @@
+// qr —— 零依赖 QR 编码器（pi ext 自持），对位 wxprobe src/qr.rs 用的 `qrcode` crate。
+//
+// 范围（协议实际需要）：字节模式、EC 级别 M（qrcode 0.14 `QrCode::new` 的默认，
+// 已核对其 lib.rs:76）、版本 1–40 自动选择、掩码按规范 penalty 自动选优。
+// 正确实现的矩阵是规范确定的——测试用临时 cargo 项目生成的 golden 矩阵
+// 逐字节对拍（同版本同 EC 同掩码 ⇒ 矩阵必须一致）。
+//
+// 产物：
+// - qr_grid(url, quiet) → QrGrid（含静默区矩阵 + runs() 行程压缩）—— canvas
+// 原语画方块用（J2 绑定页；半块字符在抗锯齿下有细缝，部分手机解不出）
+// - qr_svg(url) → 320×320 SVG（浏览器打开备用通路）
+
+// ---------------------------------------------------------------- Reed–Solomon
+
+const EXP = new Uint8Array(256);
+const LOG = new Uint8Array(256);
+(() => {
+  let x = 1;
+  for (let i = 0; i < 255; i += 1) {
+    EXP[i] = x;
+    LOG[x] = i;
+    x <<= 1;
+    if (x & 0x100) x ^= 0x11d;
+  }
+})();
+
+const gmul = (a, b) => (a === 0 || b === 0 ? 0 : EXP[(LOG[a] + LOG[b]) % 255]);
+
+// 生成多项式 log 表（对位 qrcode crate GENERATOR_POLYNOMIALS）:
+// GEN_LOG[n] = (x-α^0)(x-α^1)…(x-α^(n-1)) 展开的**去最高项**降幂 log 系数。
+// 运行时从升幂值系数逐次 ×(x + α^(d-1)) 展开（与 crate 表逐项对拍验证）。
+const GEN_LOG = (() => {
+  const tbl = [[], [0]]; // degree 1: g = x + 1 → 去首项 = [常数 log 0]
+  let vals = [1, 1]; // g_1 升幂值系数（常数→高次）
+  for (let d = 2; d <= 68; d++) {
+    const r = EXP[(d - 1) % 255];
+    const next = [];
+    for (let j = 0; j <= d; j++) {
+      const byX = vals[j - 1] ?? 0; // ×x
+      const byA = gmul(r, vals[j] ?? 0); // ×α^(d-1)
+      next.push(byX ^ byA);
+    }
+    vals = next;
+    tbl[d] = vals
+      .slice()
+      .reverse()
+      .slice(1)
+      .map((v) => (v === 0 ? 0 : LOG[v]));
+  }
+  return tbl;
+})();
+
+/** 数据多项式的 ECC 码字（多项式除法取余数，语义与 qrcode crate ec.rs 逐行对齐）。 */
+export function rs_compute_ecc(data, degree) {
+  const log_den = GEN_LOG[degree];
+  const res = [...data, ...new Array(degree).fill(0)];
+  for (let i = 0; i < data.length; i += 1) {
+    const lead = res[i];
+    if (lead === 0) continue;
+    const logLead = LOG[lead];
+    for (let j = 0; j < degree; j += 1) {
+      res[i + 1 + j] ^= EXP[(log_den[j] + logLead) % 255];
+    }
+  }
+  return Uint8Array.from(res.slice(data.length));
+}
+
+// ---------------------------------------------------------------- 版本表（规范附录，M 级）
+
+const ECC_CODEWORDS_PER_BLOCK = {
+ // nayuki 权威表：版本 1..40，Medium 级 ECC 码字数/块
+  M: [-1, 10, 16, 26, 18, 24, 16, 18, 22, 22, 26, 30, 22, 22, 24, 24,
+      28, 28, 26, 26, 26, 28, 28, 28, 28, 28, 28, 28, 28, 28, 28,
+      28, 28, 28, 28, 28, 28, 28, 28, 28, 28],
+};
+const NUM_ERROR_CORRECTION_BLOCKS = {
+  M: [-1, 1, 1, 1, 2, 2, 4, 4, 4, 5, 5, 5, 8, 9, 9, 10,
+      10, 11, 13, 14, 16, 17, 17, 18, 20, 21, 23, 25, 26, 28, 29,
+      31, 33, 35, 37, 38, 40, 43, 45, 47, 49],
+};
+
+const num_raw_data_modules = (ver) => {
+  let result = (16 * ver + 128) * ver + 64;
+  if (ver >= 2) {
+    const numAlign = Math.floor(ver / 7) + 2;
+    result -= (25 * numAlign - 10) * numAlign - 55;
+    if (ver >= 7) result -= 36;
+  }
+  return result;
+};
+
+/** 字节模式**字符计数指示符**位宽（规范表 3）：v1-9 = 8 位，v10-40 = 16 位。
+ * 漏了这条会把 v10+ 的码流整体写错 —— 版本表/capacity 都对、码却解不出来。 */
+export const count_bits = (ver) => (ver <= 9 ? 8 : 16);
+
+/** 该版本字节模式容量（字节数）= 数据码字 × 8 − 4 位模式 − 计数位 的下取整。 */
+export function byte_capacity(ver) {
+  const total = ECC_CODEWORDS_PER_BLOCK.M[ver] * NUM_ERROR_CORRECTION_BLOCKS.M[ver];
+  const dataCodewords = Math.floor(num_raw_data_modules(ver) / 8) - total;
+  const usable = dataCodewords * 8 - 4 - count_bits(ver);
+  return usable < 0 ? 0 : Math.floor(usable / 8);
+}
+
+function pick_version(byteLen) {
+  for (let ver = 1; ver <= 40; ver += 1) {
+    if (byteLen <= byte_capacity(ver)) return ver;
+  }
+  throw new Error(`二维码编码失败: 数据超出 QR 容量（${byteLen} 字节）`);
+}
+
+// ---------------------------------------------------------------- 编码 → 码字序列
+
+export function encode_codewords(bytes, ver) {
+  const totalCodewords = Math.floor(num_raw_data_modules(ver) / 8);
+  const eccLen = ECC_CODEWORDS_PER_BLOCK.M[ver];
+  const numBlocks = NUM_ERROR_CORRECTION_BLOCKS.M[ver];
+  const dataLen = totalCodewords - eccLen * numBlocks;
+
+ // 比特流：模式 0100 + 计数（v≤9 = 8 位 / v≥10 = 16 位）+ 数据 + 终止符 + padding
+  const bits = [];
+  const push = (val, n) => { for (let i = n - 1; i >= 0; i -= 1) bits.push((val >>> i) & 1); };
+  push(0b0100, 4);
+  push(bytes.length, count_bits(ver));
+  for (const b of bytes) push(b, 8);
+  const capacityBits = dataLen * 8;
+  push(0, Math.min(4, capacityBits - bits.length)); // 终止符
+  push(0, (8 - (bits.length % 8)) % 8);             // 字节对齐
+  const pad = [0xEC, 0x11];
+  for (let i = 0; bits.length < capacityBits; i += 1) push(pad[i % 2], 8);
+
+  const data = new Uint8Array(dataLen);
+  for (let i = 0; i < dataLen; i += 1) {
+    data[i] = (bits[i * 8] << 7) | (bits[i * 8 + 1] << 6) | (bits[i * 8 + 2] << 5) |
+      (bits[i * 8 + 3] << 4) | (bits[i * 8 + 4] << 3) | (bits[i * 8 + 5] << 2) |
+      (bits[i * 8 + 6] << 1) | bits[i * 8 + 7];
+  }
+
+ // 分块 ECC + 交错（规范 8.5：短块先补一个数据码字）
+  const blocks = [];
+  const eccBlocks = [];
+  const shortBlockLen = Math.floor(dataLen / numBlocks);
+  const numShortBlocks = numBlocks - (dataLen % numBlocks);
+  let offset = 0;
+  for (let i = 0; i < numBlocks; i += 1) {
+    const dataLenI = shortBlockLen + (i < numShortBlocks ? 0 : 1);
+    const dat = data.subarray(offset, offset + dataLenI);
+    offset += dataLenI;
+    blocks.push(dat);
+    eccBlocks.push(rs_compute_ecc(dat, eccLen));
+  }
+  const out = [];
+  const maxDataLen = shortBlockLen + 1;
+  for (let i = 0; i < maxDataLen; i += 1) {
+    for (let b = 0; b < numBlocks; b += 1) {
+      if (i < blocks[b].length) out.push(blocks[b][i]);
+    }
+  }
+  for (let i = 0; i < eccLen; i += 1) {
+    for (let b = 0; b < numBlocks; b += 1) out.push(eccBlocks[b][i]);
+  }
+  return out;
+}
+
+// ---------------------------------------------------------------- 矩阵绘制
+
+export function make_matrix(ver) {
+  const size = ver * 4 + 17;
+  const modules = Array.from({ length: size }, () => new Array(size).fill(false));
+  const isFunction = Array.from({ length: size }, () => new Array(size).fill(false));
+
+  const setFn = (x, y, dark) => {
+    modules[y][x] = dark;
+    isFunction[y][x] = true;
+  };
+
+ // 时序图案
+  for (let i = 0; i < size; i += 1) {
+    setFn(6, i, i % 2 === 0);
+    setFn(i, 6, i % 2 === 0);
+  }
+ // 定位图案 + 分隔符（三角色）
+  const drawFinder = (cx, cy) => {
+    for (let dy = -4; dy <= 4; dy += 1) {
+      for (let dx = -4; dx <= 4; dx += 1) {
+        const x = cx + dx, y = cy + dy;
+        if (x < 0 || x >= size || y < 0 || y >= size) continue;
+        const dist = Math.max(Math.abs(dx), Math.abs(dy));
+        setFn(x, y, dist !== 2 && dist !== 4);
+      }
+    }
+  };
+  drawFinder(3, 3);
+  drawFinder(size - 4, 3);
+  drawFinder(3, size - 4);
+ // 校正图案（规范附录坐标表，nayuki 同表；**index = 版本号**，v1 无）
+  const ALIGN = [
+    undefined,                                        // index 0 不用（版本从 1 起）
+    [], [6, 18], [6, 22], [6, 26], [6, 30], [6, 34], [6, 22, 38], [6, 24, 42],
+    [6, 26, 46], [6, 28, 50], [6, 30, 54], [6, 32, 58], [6, 34, 62], [6, 26, 46, 66],
+    [6, 26, 48, 70], [6, 26, 50, 74], [6, 30, 54, 78], [6, 30, 56, 82], [6, 30, 58, 86],
+    [6, 34, 62, 90], [6, 28, 50, 72, 94], [6, 26, 50, 74, 98], [6, 30, 54, 78, 102],
+    [6, 28, 54, 80, 106], [6, 32, 58, 84, 110], [6, 30, 58, 86, 114], [6, 34, 62, 90, 118],
+    [6, 26, 50, 74, 98, 122], [6, 30, 54, 78, 102, 126], [6, 26, 52, 78, 104, 130],
+    [6, 30, 56, 82, 108, 134], [6, 34, 60, 86, 112, 138], [6, 30, 58, 86, 114, 142],
+    [6, 34, 62, 90, 118, 146], [6, 30, 54, 78, 102, 126, 150], [6, 24, 50, 76, 102, 128, 154],
+    [6, 28, 54, 80, 106, 132, 158], [6, 32, 58, 84, 110, 136, 162], [6, 26, 54, 82, 110, 138, 166],
+    [6, 30, 58, 86, 114, 142, 170],
+  ];
+  const pos = ALIGN[ver];
+  for (let i = 0; i < pos.length; i += 1) {
+    for (let j = 0; j < pos.length; j += 1) {
+ // 三个 finder 角不画（左上/右上/左下）
+      if ((i === 0 && j === 0) || (i === 0 && j === pos.length - 1) || (i === pos.length - 1 && j === 0)) continue;
+      const cy = pos[i], cx = pos[j];
+      for (let dy = -2; dy <= 2; dy += 1) {
+        for (let dx = -2; dx <= 2; dx += 1) {
+          setFn(cx + dx, cy + dy, Math.max(Math.abs(dx), Math.abs(dy)) !== 1);
+        }
+      }
+    }
+  }
+ // 版本信息（版本 ≥ 7）
+  if (ver >= 7) {
+    let rem = ver;
+    for (let i = 0; i < 12; i += 1) rem = (rem << 1) ^ ((rem >>> 11) * 0x1F25);
+    const bits = (ver << 12) | rem;
+    for (let i = 0; i < 18; i += 1) {
+      const dark = ((bits >>> i) & 1) !== 0;
+      const a = size - 11 + (i % 3);
+      const b = Math.floor(i / 3);
+      setFn(a, b, dark);
+      setFn(b, a, dark);
+    }
+  }
+ // format 区（第 8 行/列 + 恒黑）预标 function —— crate draw_all_functional_patterns
+ // 同构：数据填入必须跳过这些格。只标 isFunction，**不动 modules**（其中
+ // (8,6)/(6,8) 是 timing 交叉点，已画交替色；format bits 由 draw_format 覆写）
+  for (let i = 0; i <= 8; i += 1) {
+    isFunction[i][8] = true;
+    isFunction[8][i] = true;
+  }
+  for (let i = size - 8; i < size; i += 1) {
+    isFunction[i][8] = true;
+    isFunction[8][i] = true;
+  }
+  return { modules, isFunction, size };
+}
+
+/** 格式信息（EC M = 0b00，掩码 mask），BCH(15,5)。 */
+function format_bits(mask) {
+  const data = (0b00 << 3) | mask;
+  let rem = data;
+  for (let i = 0; i < 10; i += 1) rem = (rem << 1) ^ ((rem >>> 9) * 0x537);
+  return ((data << 10) | rem) ^ 0x5412;
+}
+
+function draw_format(modules, isFunction, size, mask) {
+  const bits = format_bits(mask);
+  for (let i = 0; i <= 5; i += 1) modules[i][8] = ((bits >>> i) & 1) !== 0;
+  modules[7][8] = ((bits >>> 6) & 1) !== 0;
+  modules[8][8] = ((bits >>> 7) & 1) !== 0;
+  modules[8][7] = ((bits >>> 8) & 1) !== 0;
+  for (let i = 9; i < 15; i += 1) modules[8][14 - i] = ((bits >>> i) & 1) !== 0;
+  for (let i = 0; i < 8; i += 1) modules[8][size - 1 - i] = ((bits >>> i) & 1) !== 0;
+  for (let i = 8; i < 15; i += 1) modules[size - 15 + i][8] = ((bits >>> i) & 1) !== 0;
+  modules[size - 8][8] = true; // 恒黑模块（x=8, y=size-8，format 列底部）
+  for (let y = 0; y < size; y += 1) {
+    for (let x = 0; x < size; x += 1) {
+      if ((x === 8 && (y <= 8 || y >= size - 8)) || (y === 8 && (x <= 8 || x >= size - 8))) {
+        isFunction[y][x] = true;
+      }
+    }
+  }
+}
+
+// 掩码函数（规范 8.8.2）
+export const MASKS = [
+  (x, y) => (x + y) % 2 === 0,
+  (x, y) => y % 2 === 0,
+  (x, y) => x % 3 === 0,
+  (x, y) => (x + y) % 3 === 0,
+  (x, y) => (Math.floor(x / 3) + Math.floor(y / 2)) % 2 === 0,
+  (x, y) => ((x * y) % 2) + ((x * y) % 3) === 0,
+  (x, y) => (((x * y) % 2) + ((x * y) % 3)) % 2 === 0,
+  (x, y) => (((x + y) % 2) + ((x * y) % 3)) % 2 === 0,
+];
+
+function draw_codewords(modules, isFunction, size, codewords) {
+  let i = 0;
+  for (let right = size - 1; right >= 1; right -= 2) {
+    if (right === 6) right = 5;
+    for (let vert = 0; vert < size; vert += 1) {
+      for (let j = 0; j < 2; j += 1) {
+        const x = right - j;
+        const upward = ((right + 1) & 2) === 0;
+        const y = upward ? size - 1 - vert : vert;
+        if (!isFunction[y][x] && i < codewords.length * 8) {
+          modules[y][x] = ((codewords[i >>> 3] >>> (7 - (i & 7))) & 1) !== 0;
+          i += 1;
+        }
+      }
+    }
+  }
+}
+
+/** penalty 评分 —— **逐行复刻 qrcode crate** canvas.rs（非标准 ISO 版，差异：
+ *  finder 分含 −360 抵消项、深色比线性无阶梯）。掩码选择与 crate 一致的前提。 */
+export function penalty(modules, size) {
+ // 入口规范化为 0/1：调用方可能传 boolean 矩阵（encode_matrix）或 number 矩阵
+ // （诊断/测试），S3 的 PATTERN 严格比较对 true!==1 必须先归一
+  const m = modules.map((row) => Array.from(row, (v) => (v ? 1 : 0)));
+  let total = 0;
+  const at = (x, y) => m[y][x];
+
+ // S1 adjacent：run≥5 → +run−2（crate 的行尾虚拟 Empty 仅作哨兵，等价标准 N1）
+  const scanRuns = (isH, i) => {
+    const get = (j) => (isH ? at(j, i) : at(i, j));
+    let cur = get(0);
+    let len = 1;
+    for (let j = 1; j <= size; j += 1) {
+ // j == size → 反色哨兵，强制结算真实末段
+      const c = j < size ? get(j) : (cur === 1 ? 0 : 1);
+      if (c === cur) len += 1;
+      else {
+        if (len >= 5) total += len - 2;
+        cur = c;
+        len = 1;
+      }
+    }
+  };
+  for (let i = 0; i < size; i += 1) {
+    scanRuns(true, i);
+    scanRuns(false, i);
+  }
+
+ // S2 block：每 2×2 同色 +3
+  for (let y = 0; y < size - 1; y += 1) {
+    for (let x = 0; x < size - 1; x += 1) {
+      const c = at(x, y);
+      if (c === at(x + 1, y) && c === at(x, y + 1) && c === at(x + 1, y + 1)) total += 3;
+    }
+  }
+
+ // S3 finder：#.###.# 且前4格/后4格内无深色（出界视浅）→ +40；每方向 −360
+ //（抵消三个真 finder 的固有命中，只留数据区假 pattern）
+  const PATTERN = [1, 0, 1, 1, 1, 0, 1];
+  const scanFinder = (isH, i) => {
+    const get = (k) => (isH ? at(k, i) : at(i, k));
+    let sub = 0;
+    for (let j = 0; j + 7 <= size; j += 1) {
+      let ok = true;
+      for (let k = 0; k < 7; k += 1) {
+        if (get(j + k) !== PATTERN[k]) { ok = false; break; }
+      }
+      if (!ok) continue;
+      const hasDark = (lo, hi) => {
+        for (let k = lo; k < hi; k += 1) {
+          if (k >= 0 && k < size && get(k)) return true;
+        }
+        return false;
+      };
+      if (!hasDark(j - 4, j) || !hasDark(j + 7, j + 11)) sub += 40;
+    }
+    return sub;
+  };
+  for (let i = 0; i < size; i += 1) total += scanFinder(true, i) - 360 + scanFinder(false, i) - 360;
+
+ // S4 balance：深色比线性偏差（crate 非标准版：无 5% 阶梯）
+  let dark = 0;
+  for (const row of m) for (const c of row) if (c) dark += 1;
+  const ratio = Math.floor((dark * 200) / (size * size));
+  total += ratio >= 100 ? ratio - 100 : 100 - ratio;
+
+  return total;
+}
+
+export function encode_matrix(text, forceMask = null) {
+  const bytes = Buffer.from(text, "utf8");
+  const ver = pick_version(bytes.length);
+  const codewords = encode_codewords(bytes, ver);
+  const { modules: base, isFunction: fnBase, size } = make_matrix(ver);
+  let best = null;
+  let bestScore = Infinity;
+  for (let mask = 0; mask < 8; mask += 1) {
+    if (forceMask !== null && mask !== forceMask) continue;
+    const modules = base.map((r) => r.slice());
+    const isFunction = fnBase.map((r) => r.slice());
+    draw_codewords(modules, isFunction, size, codewords);
+    for (let y = 0; y < size; y += 1) {
+      for (let x = 0; x < size; x += 1) {
+        if (!isFunction[y][x] && MASKS[mask](x, y)) modules[y][x] = !modules[y][x];
+      }
+    }
+    draw_format(modules, isFunction, size, mask);
+    const score = penalty(modules, size);
+    if (score < bestScore) {
+      bestScore = score;
+      best = modules;
+    }
+  }
+  return { modules: best, size };
+}
+
+// ---------------------------------------------------------------- 对外产物（对位 qr.rs）
+
+export class QrGrid {
+  constructor(size, cells) {
+    this.size = size;
+    this.cells = cells;
+  }
+
+  at(x, y) {
+    return this.cells[y * this.size + x] ?? false;
+  }
+
+  /** 每行连续深色段 `(x, len)` —— canvas run-length rect 用的行程。 */
+  runs(y) {
+    const out = [];
+    let x = 0;
+    while (x < this.size) {
+      if (!this.at(x, y)) { x += 1; continue; }
+      const start = x;
+      while (x < this.size && this.at(x, y)) x += 1;
+      out.push([start, x - start]);
+    }
+    return out;
+  }
+}
+
+/** 渲染成矩阵；`quiet` 四周静默区模块数（规范 4）。opts.forceMask = 对拍/调试。 */
+export function qr_grid(url, quiet = 4, opts = {}) {
+  const { modules, size } = encode_matrix(url, opts.forceMask ?? null);
+  const total = size + quiet * 2;
+  const cells = new Array(total * total).fill(false);
+  for (let y = 0; y < size; y += 1) {
+    for (let x = 0; x < size; x += 1) {
+      if (modules[y][x]) cells[(y + quiet) * total + (x + quiet)] = true;
+    }
+  }
+  return new QrGrid(total, cells);
+}
+
+/** SVG 文本（浏览器打开备用通路）。viewBox 用模块整数坐标，零舍入损失，
+ *  显示尺寸由 width/height 控制缩放。 */
+export function qr_svg(url, dim = 320) {
+  const grid = qr_grid(url, 4);
+  const parts = [];
+  for (let y = 0; y < grid.size; y += 1) {
+    for (const [x, len] of grid.runs(y)) {
+      parts.push(`M${x},${y}h${len}v1h-${len}z`);
+    }
+  }
+  return `<?xml version="1.0" encoding="UTF-8"?>\n<svg xmlns="http://www.w3.org/2000/svg" width="${dim}" height="${dim}" viewBox="0 0 ${grid.size} ${grid.size}"><rect width="100%" height="100%" fill="#ffffff"/><path d="${parts.join("")}" fill="#000000"/></svg>`;
+}

package/pi/qr.test.mjs

@@ -0,0 +1,101 @@
+// qr 单测 —— 与 Rust `qrcode` crate（0.14.1，EC M）golden 矩阵**逐字节对拍**。
+// golden 生成：临时 cargo 项目跑 qrcode crate 输出 cells JSON（对拍后即弃，
+// golden 已落 pi/fixtures/qr-golden.json）。另含 qr.rs 单测同款断言
+// （静默区/定位图案/runs 语义/确定性）。
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+
+import { byte_capacity, count_bits, qr_grid, qr_svg, QrGrid } from "./qr.mjs";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const golden = JSON.parse(readFileSync(join(here, "fixtures", "qr-golden.json"), "utf8"));
+const URL1 = "https://ilinkai.weixin.qq.com/ilink/bot/qr?x=1234567890";
+
+test("matrix_matches_rust_golden_byte_for_byte", () => {
+  for (const g of golden.grids) {
+    const js = qr_grid(g.url, g.quiet);
+    assert.equal(js.size, g.size, `${g.url} 边长`);
+    assert.equal(js.cells.length, g.cells.length);
+    let diff = -1;
+    for (let i = 0; i < g.cells.length; i += 1) {
+      if (js.cells[i] !== g.cells[i]) { diff = i; break; }
+    }
+    assert.equal(diff, -1, `${g.url} 矩阵与 Rust qrcode crate 不一致（首个差异 cell ${diff}）`);
+  }
+});
+
+test("grid_matches_source_matrix_and_has_quiet_zone", () => {
+ // qr.rs 单测同款断言（左上定位图案/静默区）
+  const g = qr_grid(URL1, 4);
+  for (let i = 0; i < g.size; i += 1) {
+    assert.ok(!g.at(i, 0) && !g.at(i, 1), "上静默区必须为空");
+    assert.ok(!g.at(0, i) && !g.at(1, i), "左静默区必须为空");
+  }
+  assert.ok(g.at(4, 4), "定位图案左上角应为深色");
+  assert.ok(g.at(10, 4) && g.at(4, 10) && g.at(10, 10), "定位图案三角");
+  assert.ok(!g.at(5, 5), "定位图案中心应为空");
+});
+
+test("runs_cover_exactly_the_dark_cells_of_each_row", () => {
+  const g = qr_grid(URL1, 4);
+  for (let y = 0; y < g.size; y += 1) {
+    let prevEnd = 0;
+    for (const [x, len] of g.runs(y)) {
+      assert.ok(x >= prevEnd, "段重叠");
+      assert.ok(len > 0, "空段");
+      assert.ok(g.at(x, y) && g.at(x + len - 1, y), "段两端必须深色");
+      prevEnd = x + len;
+    }
+    assert.ok(prevEnd <= g.size);
+  }
+ // runs 还原 = 原 cells（行程完整性）
+  for (let y = 0; y < g.size; y += 1) {
+    const rebuilt = new Array(g.size).fill(false);
+    for (const [x, len] of g.runs(y)) rebuilt.fill(true, x, x + len);
+    for (let x = 0; x < g.size; x += 1) assert.equal(rebuilt[x], g.at(x, y));
+  }
+});
+
+test("same_input_is_deterministic", () => {
+  const a = qr_grid(URL1, 4);
+  const b = qr_grid(URL1, 4);
+  assert.deepEqual(a.cells, b.cells);
+});
+
+test("svg_output_looks_like_svg", () => {
+  const svg = qr_svg(URL1);
+  assert.ok(svg.startsWith("<?xml") || svg.includes("<svg"), "不是 SVG");
+  assert.ok(svg.includes("path") || svg.includes("rect"));
+});
+
+test("absurdly_long_input_is_rejected_not_panicking", () => {
+  assert.throws(() => qr_grid("x".repeat(6000), 4), /超出 QR 容量/);
+});
+
+test("svg_round_trip_equals_grid", () => {
+ // SVG 的 path 面积还原 = 矩阵深色数（run-length 无损的另一种验证）
+  const svg = qr_svg(URL1);
+  const d = /d="([^"]+)"/.exec(svg)[1];
+  let area = 0;
+  for (const m of d.matchAll(/h([\d.]+)v([\d.]+)/g)) area += Number(m[1]) * Number(m[2]);
+  const grid = qr_grid(URL1, 4);
+  const dark = grid.cells.filter(Boolean).length;
+ // viewBox = 模块整数坐标 → 面积应精确等于深色模块数（零舍入）
+  assert.ok(
+    Math.abs(area - dark) < 1e-9,
+    `SVG 面积 ${area} ≠ 深色模块数 ${dark}`,
+  );
+});
+
+test("byte_capacity_v10_plus_uses_16_bit_count", () => {
+ // v≤9 计数 8 位、v≥10 16 位（规范表 3）。写错的话码流整体偏移：版本表对、
+ // 码却解不出来 —— 2026-10-28 真机「二维码生成错误」根因（长 URL 落到 v10+）。
+  assert.equal(count_bits(9), 8);
+  assert.equal(count_bits(10), 16);
+  const want = { 1: 14, 5: 84, 9: 180, 10: 213, 11: 251, 15: 412, 20: 666 };
+  for (const [v, n] of Object.entries(want)) assert.equal(byte_capacity(Number(v)), n, `v${v} 字节容量`);
+});