dsh-visualkit 0.0.0-stage → 0.0.1

package/lib/layouts/index.js

@@ -0,0 +1,10 @@
+/**
+ * layouts/index.js — 排版体检三模式的门面。
+ *   auditSource(root)           UI 源码（HTML/CSS/Vue/JSX）
+ *   auditSvg(markup, {name})    成品 SVG 的文字几何
+ *   auditImage(buffer, {name})  渲染后的 PNG 构图
+ * 三者返回同一形状（common.js finalize），可同尺度比较与统一渲染。
+ */
+export { auditSource } from "./source.js";
+export { auditSvg } from "./svg.js";
+export { auditImage } from "./image.js";

package/lib/layouts/intent.js

@@ -0,0 +1,66 @@
+/**
+ * layouts/intent.js — `.design-intent.json` 声明豁免（与 taste_check taste 同一套语义）。
+ *
+ * 为什么需要：实测（2026-11-07，Flow-Pilot）里 h5/h6 被收敛到正文大小，CSS 里写得
+ * 很清楚「h5/h6 没有组件映射，收敛到正文大小，避免浏览器默认 0.83em 把字缩成脚注」——
+ * 这是有意的取舍，但体检只能看到「h5 与正文只差 1.13×」并报 error。
+ *
+ * 声明格式（与 taste 完全一致，一个项目只需一份）：
+ *   { "allow": ["S9", "structure-heading-first"], "reason": "h5/h6 未做组件映射" }
+ * `allow` 里的规则不计分、不出现在 findings，而是进 `exempted` 并保留原因——
+ * 让「有意偏离」可追溯，而不是把规则删掉。
+ */
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+const INTENT_FILE = ".design-intent.json";
+
+function normalize(value) {
+	return Array.isArray(value) ? value.filter((id) => typeof id === "string" && id !== "") : [];
+}
+
+/**
+ * 读声明文件。不存在 / JSON 坏掉都不报错（一个坏声明不该让整次体检失败）。
+ * @param {string|null|undefined} rootDir 扫描根目录（单文件时传它所在目录）
+ */
+export function readIntent(rootDir) {
+	if (typeof rootDir !== "string" || rootDir === "") return { found: false, allow: [] };
+	let raw;
+	try {
+		raw = readFileSync(join(rootDir, INTENT_FILE), "utf8");
+	} catch {
+		return { found: false, allow: [] };
+	}
+	try {
+		const parsed = JSON.parse(raw);
+		return {
+			found: true,
+			allow: normalize(parsed?.allow),
+			...(typeof parsed?.skin === "string" ? { skin: parsed.skin } : {}),
+			...(typeof parsed?.reason === "string" ? { reason: parsed.reason } : {})
+		};
+	} catch {
+		return { found: true, invalid: true, allow: [] };
+	}
+}
+
+/**
+ * 按 allow 名单过滤 findings。
+ * @returns {{kept: object[], exempted: string[], exemptionReason?: string}}
+ */
+export function applyAllow(findings, intent) {
+	const allow = new Set(normalize(intent?.allow));
+	if (allow.size === 0) return { kept: findings, exempted: [] };
+	const hit = new Set();
+	const kept = findings.filter((finding) => {
+		if (!allow.has(finding.rule)) return true;
+		hit.add(finding.rule);
+		return false;
+	});
+	return {
+		kept,
+		// 只报真实命中过的（声明了一个不存在的规则不算豁免，就不列）
+		exempted: [...hit].sort(),
+		...(typeof intent?.reason === "string" ? { exemptionReason: intent.reason } : {})
+	};
+}

package/lib/layouts/metrics-text.js

@@ -0,0 +1,91 @@
+/**
+ * layouts/metrics-text.js — 文字宽度度量（不引入字体引擎）。
+ *
+ * 为什么要这张表（实测数据，2026-11-07）：
+ *   旧的「汉字 1.0em / 拉丁 0.55em」模型在纯英文上误差 **10.0%**，中英混排 4.4%；
+ *   而 G4 行长、G1 边距、G6 重叠都靠宽度，10% 误差足以让「85% 画布宽」这类阈值判错。
+ *
+ * 为什么不用 HarfBuzz-WASM（436 KB，精度 0.4%）：
+ *   把 ASCII 32–126 的真实 advance width 离线抽一次做成表（下面 WIDTHS），
+ *   运行时只是查表 —— 与 HarfBuzz 精度差 **0.00–0.02%**，体积 383 字节，零依赖。
+ *   表从 Microsoft YaHei（msyh.ttc, upem 2048）抽取；换成别的字体拉丁字宽会差 ~3–6%，
+ *   仍比扁平 0.55 好一个数量级。
+ *
+ * 汉字与全角标点恒为 1.0em —— 不是假设，是字体约定：实测
+ *   「中 文 龘 ， 。 、 ： ；」全部 1.0000em，「（）」2.0000em。所以 CJK 不需要表。
+ */
+
+/** ASCII 32–126 的 advance width（×1000，相对 em）。离线取自 msyh.ttc。 */
+const WIDTHS = [
+	296, 313, 436, 638, 586, 890, 870, 256, 334, 334, 455, 742, 241, 433, 241, 427,
+	586, 586, 586, 586, 586, 586, 586, 586, 586, 586, 241, 241, 742, 742, 742, 483,
+	1031, 704, 627, 669, 762, 550, 531, 744, 773, 294, 396, 635, 513, 977, 813, 815,
+	612, 815, 653, 577, 573, 747, 676, 1018, 645, 604, 620, 334, 416, 334, 742, 448,
+	295, 553, 639, 501, 640, 567, 347, 640, 616, 266, 267, 544, 266, 937, 616, 636,
+	639, 640, 382, 463, 373, 616, 525, 790, 507, 529, 492, 334, 269, 334, 742
+];
+
+/** 全角区段：CJK / 假名 / 韩文 / 全角标点 / emoji —— advance 恒为 1em。 */
+const WIDE_RANGES = [
+	[0x1100, 0x115f],
+	[0x2e80, 0x303e],
+	[0x3041, 0x33ff],
+	[0x3400, 0x4dbf],
+	[0x4e00, 0x9fff],
+	[0xa000, 0xa4cf],
+	[0xac00, 0xd7a3],
+	[0xf900, 0xfaff],
+	[0xfe30, 0xfe4f],
+	[0xff00, 0xff60],
+	[0xffe0, 0xffe6],
+	[0x1f000, 0x1faff],
+	[0x20000, 0x3fffd]
+];
+
+/** 字母下伸部分/组合符等零宽字符（不推进行宽）。 */
+const ZERO_WIDTH = new Set([0x200b, 0x200c, 0x200d, 0xfeff, 0x00ad]);
+
+function isWide(codePoint) {
+	for (const [start, end] of WIDE_RANGES) if (codePoint >= start && codePoint <= end) return true;
+	return false;
+}
+
+/**
+ * 单字符 advance width（单位 em）。
+ * ASCII 查表；全宽区段 1.0；零宽字符 0；其余（拉丁扩展/符号）用 0.55 兜底。
+ */
+export function charWidth(char) {
+	const cp = typeof char === "string" ? char.codePointAt(0) : char;
+	if (cp === undefined) return 0;
+	if (cp >= 32 && cp <= 126) return WIDTHS[cp - 32] / 1000;
+	if (ZERO_WIDTH.has(cp)) return 0;
+	if (isWide(cp)) return 1;
+	return 0.55;
+}
+
+/**
+ * 一段文字的估算宽度（单位 = 字号倍数；乘 fontSize 得用户单位）。
+ * 非法输入（null/数字/对象）按空串处理 —— 体检不该因为一个怪值崩掉。
+ */
+export function measureText(text) {
+	let width = 0;
+	for (const char of String(text ?? "")) width += charWidth(char);
+	return width;
+}
+
+/** 同 measureText，但直接返回像素/用户单位。 */
+export function measureTextPx(text, fontSize) {
+	const size = Number(fontSize);
+	if (!Number.isFinite(size) || size <= 0) return 0;
+	return measureText(text) * size;
+}
+
+/** 一行里的全角字符数（G4 的「一行 45 字」上限用）。 */
+export function countWideChars(text) {
+	let count = 0;
+	for (const char of String(text ?? "")) if (isWide(char.codePointAt(0))) count += 1;
+	return count;
+}
+
+/** 表自检：长度必须是 95（ASCII 32–126 全段）。 */
+export const WIDTH_TABLE_SIZE = WIDTHS.length;

package/lib/layouts/png.js

@@ -0,0 +1,75 @@
+/**
+ * layouts/png.js — 最小 PNG 解码器（无依赖，lib 内部用）。
+ *
+ * 为什么要自己解：排版体检的 image 模式要看像素（内容包围盒/边距/重心/对齐），
+ * 而 resvg 只输出不会回读。引 sharp/pngjs 会破坏「零运行时依赖」的发布包约束。
+ * 只支持 resvg 实际产出的 8-bit 非隔行 PNG（colorType 0/2/4/6）——ours，不是通用库。
+ */
+import { inflateSync } from "node:zlib";
+
+const SIGNATURE = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+
+function paeth(a, b, c) {
+	const p = a + b - c;
+	const pa = Math.abs(p - a);
+	const pb = Math.abs(p - b);
+	const pc = Math.abs(p - c);
+	if (pa <= pb && pa <= pc) return a;
+	return pb <= pc ? b : c;
+}
+
+/** PNG buffer → { width, height, channels, data }（data 为 RGBA/RGB 解码后的行优先字节）。 */
+export function decodePng(input) {
+	const buf = Buffer.isBuffer(input) ? input : Buffer.from(input);
+	if (buf.length < 32 || !buf.subarray(0, 8).equals(SIGNATURE)) throw new Error("不是 PNG（签名不匹配）");
+	let offset = 8;
+	let ihdr = null;
+	const idat = [];
+	while (offset + 8 <= buf.length) {
+		const len = buf.readUInt32BE(offset);
+		const type = buf.toString("ascii", offset + 4, offset + 8);
+		const data = buf.subarray(offset + 8, offset + 8 + len);
+		if (type === "IHDR") ihdr = { width: data.readUInt32BE(0), height: data.readUInt32BE(4), depth: data[8], colorType: data[9], interlace: data[12] };
+		else if (type === "IDAT") idat.push(data);
+		offset += 12 + len;
+		if (type === "IEND") break;
+	}
+	if (ihdr === null) throw new Error("PNG 缺 IHDR");
+	if (ihdr.depth !== 8) throw new Error(`只支持 8-bit PNG（收到 ${ihdr.depth}-bit）`);
+	if (ihdr.interlace !== 0) throw new Error("不支持隔行 PNG");
+	const channels = { 0: 1, 2: 3, 4: 2, 6: 4 }[ihdr.colorType];
+	if (channels === undefined) throw new Error(`不支持的 colorType ${ihdr.colorType}`);
+	const raw = inflateSync(Buffer.concat(idat));
+	const stride = ihdr.width * channels;
+	const out = Buffer.alloc(stride * ihdr.height);
+	let pos = 0;
+	for (let y = 0; y < ihdr.height; y += 1) {
+		const filter = raw[pos++];
+		const row = y * stride;
+		for (let x = 0; x < stride; x += 1) {
+			const cur = raw[pos++];
+			const left = x >= channels ? out[row + x - channels] : 0;
+			const up = y > 0 ? out[row - stride + x] : 0;
+			const upLeft = y > 0 && x >= channels ? out[row - stride + x - channels] : 0;
+			let val;
+			if (filter === 0) val = cur;
+			else if (filter === 1) val = cur + left;
+			else if (filter === 2) val = cur + up;
+			else if (filter === 3) val = cur + ((left + up) >> 1);
+			else if (filter === 4) val = cur + paeth(left, up, upLeft);
+			else throw new Error(`未知 PNG 行滤波 ${filter}`);
+			out[row + x] = val & 0xff;
+		}
+	}
+	return { width: ihdr.width, height: ihdr.height, channels, data: out };
+}
+
+/** 取像素，统一返回 {r,g,b,a}。 */
+export function pixelAt(img, x, y) {
+	const i = (y * img.width + x) * img.channels;
+	const d = img.data;
+	if (img.channels === 4) return { r: d[i], g: d[i + 1], b: d[i + 2], a: d[i + 3] };
+	if (img.channels === 3) return { r: d[i], g: d[i + 1], b: d[i + 2], a: 255 };
+	if (img.channels === 2) return { r: d[i], g: d[i], b: d[i], a: d[i + 1] };
+	return { r: d[i], g: d[i], b: d[i], a: d[i] };
+}