dsh-visualkit 0.0.0-stage → 0.0.1

package/lib/morphcore.js

@@ -0,0 +1,139 @@
+/**
+ * morphcore.js — 在 Node 侧装载 vendored morphicons 核心（可选能力）。
+ *
+ * vendor/morphicons.iife.js 是 morphicons 2.0.2 的浏览器 IIFE（var MorphIcons = ...），没有 ESM
+ * 导出；这里读取其源码、追加 default 导出后经 data: URL 动态 import。
+ * 核心是纯计算（弹簧/重采样/canonical 序列化），加载期不触 DOM ——
+ * createMorph 只需要一个带 setAttribute 的对象（本模块提供假元素），
+ * 因此 canonicalD / 中间态 seek 在 Node 里可直接算。
+ *
+ * 任何一步失败都静默降级（返回 null），调用方按能力缺失处理，
+ * 绝不让预览/体检工具因 vendor 问题而不可用。
+ *
+ * 信任边界（codereview #490）：下方 data: URL 动态 import 等价于执行读入的字符串
+ * （eval 类模式），其安全性完全依赖「VENDOR_PATH / ADAPTERS_PATH 是模块相对的
+ * 构建期固定产物」这一前提——路径与源码内容都不得受用户/插件输入影响，后续
+ * 维护不得把这两个来源改成可注入的（若改为打包器分发，需同步补构建期
+ * checksum 校验并重审 dirname(import.meta.url) 的解析）。
+ */
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const VENDOR_PATH = join(dirname(fileURLToPath(import.meta.url)), "..", "vendor", "morphicons.iife.js");
+const ADAPTERS_PATH = join(dirname(fileURLToPath(import.meta.url)), "..", "vendor", "morphicons-adapters.iife.js");
+
+let api = undefined; // undefined=未尝试; null=不可用; object=可用
+let adaptersApi = undefined; // 同上三态；adapters（svgToIcon/fitIcon），v0.3.0 起
+// 审查修复 #285：装载中的 Promise（单飞缓存）——模块 import 即触发 adaptersWarmup，
+// 工具在完成前再调用会重复 readFileSync 与动态 import（三态判断发生在任何
+// await 之前，竞态窗口真实存在）；缓存进行中的 Promise 并在体内同步回写结果
+let corePromise = null;
+let adaptersPromise = null;
+
+/** 后台预热 adapters（import 本模块即触发；工具执行时基本已就绪）。 */
+const adaptersWarmup = (async () => {
+	await loadAdapters();
+})();
+
+/** 假 <path> 元素：记录最后一次 setAttribute('d')，供离线采样中间态。 */
+class FakePathEl {
+	constructor() {
+		this.lastD = "";
+	}
+	setAttribute(name, value) {
+		if (name === "d") this.lastD = String(value);
+	}
+}
+
+/**
+ * codereview #489：装载 vendored IIFE 的公共步骤（读取 → 追加 default 导出 →
+ * data: URL 动态 import → 形状校验）。loadMorphCore 与 loadAdapters 原先各自
+ * 手写一遍，补丁串格式（尾换行、charset）这类细节只改一处就会悄然分叉。
+ * 读取/导入/校验失败直接抛错，降级与三态缓存仍留在各自调用方。
+ */
+async function importVendedIife(path, globalName, validate) {
+	const source = readFileSync(path, "utf8");
+	const patched = `${source}\nexport default ${globalName};\n`;
+	const mod = await import(`data:text/javascript;charset=utf-8,${encodeURIComponent(patched)}`);
+	const value = mod.default;
+	if (!validate(value)) throw new Error(`unexpected vendor shape: ${globalName}`);
+	return value;
+}
+
+/** 单例装载；失败缓存（null），不反复重试 IO。 */
+async function loadMorphCore() {
+	if (api !== undefined) return api;
+	if (corePromise === null) {
+		corePromise = (async () => {
+			try {
+				const M = await importVendedIife(VENDOR_PATH, "MorphIcons", (v) => v !== undefined && typeof v.canonicalD === "function" && typeof v.createMorph === "function");
+				api = {
+					/** canonical path 字符串（morphicons 的静止态快照） */
+					canonicalD: (node) => M.canonicalD(node),
+					/** fill 图标形变前需要 region 可见表面数据（2.0 新增）；stroke 图标无事发生。 */
+					preloadRegion: async () => {
+						if (typeof M.preloadRegion === "function") await M.preloadRegion();
+					},
+					/** 离线采样：从 from 形变到 to，在进度 t 处的 path d 字符串（无弹簧、无 DOM） */
+					sampleD(from, to, t) {
+						const el = new FakePathEl();
+						const inst = M.createMorph(el, from, { reducedMotion: "always" });
+						try {
+							inst.seek(to, Math.min(Math.max(t, 0), 1));
+							// 审查修复 #286：删除「progress 兜底再 seek」死分支——vendor 的
+							// createMorph 构造时即写入 canonical d、seek→render 同步执行，
+							// lastD 为空只可能是渲染失败：按目标静止态返回对 t<1 是完全
+							// 错误的中间态数据，宁可响亮失败也不静默降级给错值
+							if (el.lastD === "") throw new Error("sampleD: seek 未产出中间态路径（vendor 行为变化？）");
+							return el.lastD;
+						} finally {
+							inst.destroy?.();
+						}
+					}
+				};
+			} catch (error) {
+				// 审查修复 #287：静默降级保留，但留一行可检索诊断——vendor 缺失/
+				// 权限错误/形状不符时能从宿主日志区分「装载失败」与「预热未完成」
+				console.warn(`[uilab] morphicons core 不可用（按能力缺失降级）：${error?.message ?? error}`);
+				api = null;
+			}
+			return api;
+		})();
+	}
+	return corePromise;
+}
+
+/** 同法装载 adapters IIFE（svgToIcon + fitIcon，均无 DOM 依赖）。2.0 把 fitIcon
+ * 移到核心导出（adapters 子路径只剩 svgToIcon/canvasTarget/maskTarget），构建 entry
+ * 一并再导出 fitIcon，保持本模块「svgToIcon + fitIcon」的既有装载契约。 */
+async function loadAdapters() {
+	if (adaptersApi !== undefined) return adaptersApi;
+	// 审查修复 #285：单飞缓存——adaptersWarmup 进行中的竞态调用原先会重复装载
+	if (adaptersPromise === null) {
+		adaptersPromise = (async () => {
+			try {
+				const A = await importVendedIife(ADAPTERS_PATH, "MorphIconsAdapters", (v) => typeof v?.svgToIcon === "function" && typeof v?.fitIcon === "function");
+				adaptersApi = { svgToIcon: A.svgToIcon, fitIcon: A.fitIcon };
+			} catch (error) {
+				// 审查修复 #287：静默降级保留，但留一行可检索诊断（理由同 core 侧）
+				console.warn(`[uilab] morphicons adapters 不可用（引擎层判定降级为跳过）：${error?.message ?? error}`);
+				adaptersApi = null;
+			}
+			return adaptersApi;
+		})();
+	}
+	return adaptersPromise;
+}
+
+/** 同步取已缓存的 adapters；未就绪/不可用返回 undefined（调用方按能力缺失处理）。
+ * codereview #488（取舍记录）：这里刻意把「预热中」与「确认不可用」坍缩为同一个
+ * undefined——唯一需要区分二者的场景是「装载未完成 ≠ 能力缺失」，而那类调用方的
+ * 正确姿势是先 `await adaptersWarmup` 再判定（selftest 即此写法；adaptersWarmup 在
+ * 模块 import 时即触发，工具实际执行时早已 settle）。再导出 adaptersState() 之类
+ * 三态探针在本仓库没有消费者，只会新增死 API；需要时以此为锚补导出。 */
+function adaptersSync() {
+	return adaptersApi === null ? undefined : adaptersApi;
+}
+
+export { adaptersSync, adaptersWarmup, loadAdapters, loadMorphCore };

package/lib/preview.js

@@ -0,0 +1,225 @@
+/**
+ * preview.js — morph action=preview 的实现核心：生成自包含 HTML 动效预览页。
+ *
+ * 页面内嵌 vendored morphicons 2.0.2 IIFE 与两端
+ * 图标的 IconNode 数据，离线可开：单文件、无外链、无构建。
+ * 交互：点击切换（弹簧动画，snappy/smooth/bouncy 可选）+ 进度条拖动
+ * （seek 受控模式）+ 端点参照图。若 Node 侧 morphcore 可用，还服务端烘焙
+ * 一排中间态静帧（t=0…1），不点不动也能看形变过程。
+ */
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { readFileSync } from "node:fs";
+import { basename, dirname, isAbsolute, join } from "node:path";
+import { tmpdir } from "node:os";
+import { fileURLToPath } from "node:url";
+import { loadAdapters, loadMorphCore } from "./morphcore.js";
+import { checkIcon, extractInner, iconToInnerSvg, parseIconNodes } from "./svg.js";
+import { getIcon } from "./icondb.js";
+
+const VENDOR_PATH = join(dirname(fileURLToPath(import.meta.url)), "..", "vendor", "morphicons.iife.js");
+const SPRINGS = ["snappy", "smooth", "bouncy"];
+
+/** fill 风格图标（包数据里的品牌/实心图标）：2.0 的 region 数据需先 preload，
+ * 否则服务端烘焙的静帧会停留在起点形状（浏览器侧点击 morph 不受影响）。 */
+function isFillDrawn(node) {
+	return node.some(([, attrs]) => typeof attrs?.fill === "string" && attrs.fill !== "none");
+}
+
+function readVendor() {
+	return readFileSync(VENDOR_PATH, "utf8");
+}
+
+/** JSON → 可内嵌 <script> 的字面量（防 </script> 提前闭合）。 */
+function embedJson(value) {
+	return JSON.stringify(value).replace(/<\//g, "<\\/");
+}
+
+function frameSvg(d, size, label) {
+	return (
+		`<div class="frame"><svg width="${size}" height="${size}" viewBox="0 0 24 24" fill="none" stroke="currentColor" ` +
+		`stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="${d}"/></svg>` +
+		(label ? `<span>${label}</span>` : "") + `</div>`
+	);
+}
+
+function sideSvg(inner, size, label) {
+	return (
+		`<div class="side"><svg width="${size}" height="${size}" viewBox="0 0 24 24" fill="none" stroke="currentColor" ` +
+		`stroke-width="2" stroke-linecap="round" stroke-linejoin="round">${inner}</svg><span>${label}</span></div>`
+	);
+}
+
+/**
+ * 生成预览页 HTML。
+ * @param {object} p
+ * @param {{name:string,node:object[]}} p.from 起始图标
+ * @param {{name:string,node:object[]}} p.to 目标图标
+ */
+async function buildPreviewHtml({ from, to, spring = "snappy", size = 120 }) {
+	const preset = SPRINGS.includes(spring) ? spring : "snappy";
+	// 舞台尺寸：给边界（40–800），非法值回落 120；声明了就不能无效
+	const stageSize = typeof size === "number" && Number.isFinite(size) && size >= 40 && size <= 800 ? Math.round(size) : 120;
+	const vendor = readVendor();
+	const core = await loadMorphCore();
+
+	// 服务端烘焙中间态静帧（morphcore 不可用则整段省略）。
+	// 这里只算 **帧内容**，不拼 <section>/<h2> —— 标记写在主模板里，
+	// 否则源码顺序会变成「h2 在 h1 之前」：自测（layout_check ui）就报过
+	// structure-heading-first，虽然浏览器里渲染顺序是对的，但源码层确实误导人。
+	let framesHtml = "";
+	if (core !== null) {
+		if (isFillDrawn(from.node) || isFillDrawn(to.node)) {
+			try {
+				await core.preloadRegion?.();
+			} catch {
+				/* region 不可用：仍出静帧，但可能停在起点形状 */
+			}
+		}
+		const marks = [0, 0.25, 0.5, 0.75, 1];
+		const frames = marks.map((t) => frameSvg(core.sampleD(from.node, to.node, t), 44, t === 0 ? "t=0" : `t=${t}`));
+		framesHtml = `<div class="frames">${frames.join("")}</div>`;
+	}
+
+	const title = `${from.name} ⇄ ${to.name}`;
+	return `<!doctype html>
+<html lang="zh-CN">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>morph 预览 · ${title}</title>
+<style>
+  :root { color-scheme: light dark; }
+  /* 字阶 4 档：24 / 18 / 14 / 12（T 梯级 24/14 = 1.71×，过 1.6 线）。
+     原稿是 18 / 13 / 12，被自测（layout_check ui S1/S9）判为「梯级跮断、
+     h2 与正文分不开」——2px 的差在 100% 缩放下看不出来。 */
+  body { font: 14px/1.6 system-ui, "Segoe UI", sans-serif; margin: 0; padding: 24px; max-width: 640px; margin-inline: auto; }
+  h1 { font-size: 24px; line-height: 1.25; margin: 0 0 6px; }
+  h2 { font-size: 18px; line-height: 1.3; opacity: .7; margin: 22px 0 8px; }
+  .meta { opacity: .6; font-size: 12px; margin-bottom: 16px; }
+  .stage-wrap { display: flex; align-items: center; gap: 28px; flex-wrap: wrap; }
+  /* 用 #2563eb 而不是 #3b82f6：白字在 #3b82f6 上只有 3.68:1（低于 WCAG AA 4.5:1），
+     #2563eb 是 5.17:1，过 AA。这是自测（layout_check ui）在我们的自己的代码里查出来的。 */
+  .stage { color: #2563eb; }
+  .side { display: flex; flex-direction: column; align-items: center; gap: 4px; font-size: 12px; opacity: .75; }
+  .controls { display: flex; gap: 12px; align-items: center; flex-wrap: wrap; margin-top: 16px; }
+  button { font: inherit; padding: 6px 18px; border-radius: 8px; border: 1px solid currentColor; background: transparent; cursor: pointer; }
+  button.primary { background: #2563eb; border-color: #2563eb; color: #fff; }
+  input[type=range] { width: 240px; }
+  fieldset { border: none; padding: 0; margin: 0; display: flex; gap: 8px; font-size: 14px; }
+  .strip .frames { display: flex; gap: 14px; flex-wrap: wrap; }
+  .frame { display: flex; flex-direction: column; align-items: center; gap: 2px; font-size: 12px; opacity: .85; }
+  .hint { margin-top: 18px; font-size: 12px; opacity: .55; }
+</style>
+</head>
+<body>
+<h1>morph 预览 · ${title}</h1>
+<div class="meta">morphicons 2.0.2（vendored 上游）· spring=${preset} · 点击按钮看弹簧动画，拖动进度条看受控形变</div>
+
+<div class="stage-wrap">
+  ${sideSvg(iconToInnerSvg(from.node), 40, from.name)}
+  <svg id="stage" class="stage" width="${stageSize}" height="${stageSize}" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path/></svg>
+  ${sideSvg(iconToInnerSvg(to.node), 40, to.name)}
+</div>
+
+<div class="controls">
+  <button id="toggle" class="primary">morph → ${to.name}</button>
+  <label>进度 <input id="scrub" type="range" min="0" max="1" step="0.001" value="0"></label>
+  <fieldset id="springs">
+    <label><input type="radio" name="spring" value="snappy" ${preset === "snappy" ? "checked" : ""}>snappy</label>
+    <label><input type="radio" name="spring" value="smooth" ${preset === "smooth" ? "checked" : ""}>smooth</label>
+    <label><input type="radio" name="spring" value="bouncy" ${preset === "bouncy" ? "checked" : ""}>bouncy</label>
+  </fieldset>
+</div>
+
+${framesHtml === "" ? "" : `<section class="strip"><h2>中间态静帧（服务端烘焙）</h2>${framesHtml}</section>`}
+
+<p class="hint">进度条对应 seek（受控模式，无弹簧）；按钮对应 morphTo（可中断弹簧，中途再点会从中间形重新规划）。reducedMotion 跟随系统设置。</p>
+
+<script>
+${vendor}
+</script>
+<script>
+const FROM = ${embedJson(from.node)};
+const TO = ${embedJson(to.node)};
+const stageEl = document.querySelector('#stage path');
+const inst = MorphIcons.createMorph(stageEl, FROM, { reducedMotion: 'user' });
+let atFrom = true;
+let spring = ${JSON.stringify(preset)};
+const toggleBtn = document.querySelector('#toggle');
+toggleBtn.addEventListener('click', () => {
+  atFrom = !atFrom;
+  inst.morphTo(atFrom ? FROM : TO, spring);
+  toggleBtn.textContent = 'morph → ' + (atFrom ? ${JSON.stringify(to.name)} : ${JSON.stringify(from.name)});
+});
+document.querySelector('#scrub').addEventListener('input', (e) => {
+  inst.seek(TO, Number(e.target.value)); // t=0 即 FROM、t=1 即 TO
+});
+document.querySelector('#springs').addEventListener('change', (e) => { spring = e.target.value; });
+</script>
+</body>
+</html>
+`;
+}
+
+/** 默认输出目录：config.previewDir → 系统临时目录下的 dsh-uilab。 */
+function defaultPreviewDir(configured) {
+	if (configured && configured.trim() !== "") return configured;
+	return join(tmpdir(), "dsh-uilab");
+}
+
+/** 生成并落盘预览页；返回 { path, sizeBytes, spring }。 */
+async function writePreview({ from, to, spring, outPath, previewDir, cwd, size }) {
+	const html = await buildPreviewHtml({ from, to, spring, size });
+	const target = outPath && outPath.trim() !== ""
+		? (isAbsolute(outPath) ? outPath : join(cwd ?? process.cwd(), outPath))
+		: join(defaultPreviewDir(previewDir), `morph-${from.name}-to-${to.name}.html`);
+	await mkdir(dirname(target), { recursive: true });
+	await writeFile(target, html, "utf8");
+	return { path: target, sizeBytes: Buffer.byteLength(html, "utf8"), file: basename(target), spring: SPRINGS.includes(spring) ? spring : "snappy" };
+}
+
+/** SVG 标记 → { name, node }；非 24 网格用 vendored 引擎 fitIcon 归一化。 */
+async function fromMarkup(raw, name, checkOnRaw) {
+	if (!checkOnRaw) return { name, node: [] };
+	const { inner, viewBox } = extractInner(raw);
+	let node = parseIconNodes(inner);
+	if (node === null) {
+		const check = checkIcon(raw);
+		throw new Error(`输入 SVG 未通过 morph 兼容体检：${check.issues.join("；") || "解析不出基本形节点"}（详见 morph action=check）`);
+	}
+	// 非 24 网格：preview 的舞台是 24 viewBox，不归一化会直接裁切（实测 48 网格矩形被框外切掉）
+	if (viewBox !== undefined && viewBox.replace(/\s+/g, "") !== "002424") {
+		try {
+			const adapters = await loadAdapters();
+			const fitted = adapters.fitIcon(node, viewBox, 24);
+			if (typeof fitted === "string" && fitted.length > 0) node = [["path", { d: fitted }]];
+		} catch {
+			/* 引擎不可用：保留原节点（check 会提示需归一化） */
+		}
+	}
+	return { name, node };
+}
+
+/** 把「图标名 / .svg 文件路径 / 内联标记」解析为 { name, node }；SVG 输入必须先过 morph action=check。 */
+async function resolveIconInput(input, { checkOnRaw = true, cwd } = {}) {
+	const raw = String(input ?? "").trim();
+	if (raw === "") throw new Error("empty icon input");
+	if (!raw.includes("<")) {
+		const icon = getIcon(raw);
+		if (icon !== undefined) return { name: icon.name, node: icon.node };
+		if (raw.toLowerCase().endsWith(".svg")) {
+			const file = isAbsolute(raw) ? raw : join(cwd ?? process.cwd(), raw);
+			let svg;
+			try {
+				svg = await readFile(file, "utf8");
+			} catch {
+				throw new Error(`.svg 文件读不到：${raw}（解析为 ${file}；相对路径按会话目录）`);
+			}
+			return fromMarkup(svg, basename(file), checkOnRaw);
+		}
+		throw new Error(`unknown lucide icon "${raw}"（可先用 icon action=find 检索；也可传 .svg 文件路径或直接粘贴 SVG 标记）`);
+	}
+	return fromMarkup(raw, "custom-svg", checkOnRaw);
+}
+
+export { SPRINGS, buildPreviewHtml, writePreview, resolveIconInput };

package/lib/render-html.js

@@ -0,0 +1,255 @@
+/**
+ * render-html.js — HTML → PNG（调用本机已安装的浏览器无头模式）。
+ *
+ * **为什么必须有**：很多桌面软件的内部 UI 本身就是 web 版；不能渲染 HTML 就等于
+ * “看不到自己的输出”，排版/间距/密度的问题根本无法发现。实测：参照稿在静态体检
+ * 拿到 clean 之后，一渲染就看出头像权重、行高、字号全线偏大。
+ *
+ * **对“零外部进程”承诺的取舍**：核心渲染（SVG）依旧完全自包含（vendored resvg）；
+ * 只有 HTML 这一项需要本机浏览器。这是有意为之：
+ *   - 自己写 HTML/CSS 布局引擎去“验证”用户界面的布局，等于用可能错的尺子量东西，
+ *     结论不可信；真实浏览器的引擎才是唯一可信的参照；
+ *   - 探测不到浏览器时**明确报错并给方案**，绝不静默回退成“看起来对”的假渲染。
+ */
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdtempSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+
+/** 常见安装位置（Windows 优先，macOS/Linux 也列上）。按可靠性排序。 */
+const CANDIDATES = [
+	// Windows
+	"C:/Program Files (x86)/Microsoft/Edge/Application/msedge.exe",
+	"C:/Program Files/Microsoft/Edge/Application/msedge.exe",
+	"C:/Program Files/Google/Chrome/Application/chrome.exe",
+	"C:/Program Files (x86)/Google/Chrome/Application/chrome.exe",
+	// macOS
+	"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
+	"/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge",
+	// Linux
+	"/usr/bin/google-chrome",
+	"/usr/bin/chromium",
+	"/usr/bin/chromium-browser",
+	"/usr/bin/microsoft-edge"
+];
+
+/**
+ * 找一个可用的 Chromium 系浏览器。
+ * @param {string} [explicit] 配置里明确指定的路径（优先级最高）
+ * @returns {{path: string, source: "config"|"detected"}|null}
+ */
+export function findBrowser(explicit) {
+	if (typeof explicit === "string" && explicit.trim() !== "") {
+		const p = resolve(explicit.trim());
+		return existsSync(p) ? { path: p, source: "config" } : null;
+	}
+	for (const candidate of CANDIDATES) {
+		if (existsSync(candidate)) return { path: candidate, source: "detected" };
+	}
+	return null;
+}
+
+/** 探测不到时的错误文案：给可执行的下一步，而不是只说“没找到”。 */
+export function missingBrowserError() {
+	return new Error(
+		"没有找到可用于渲染 HTML 的浏览器。\n" +
+			"HTML 渲染需要本机已安装 Chromium 系浏览器（Edge / Chrome / Chromium）。\n" +
+			"可选做法：1) 安装 Edge 或 Chrome；2) 在插件配置里指定 browserPath 指向浏览器可执行文件；" +
+			"3) 改用 action=render 处理 SVG（完全离线，不依赖浏览器）。"
+	);
+}
+
+/**
+ * 量出页面真实内容高（CSS px）。
+ *
+ * 为什么不用 `--screenshot` 自己“整页”：Chromium 无头模式的所有截图都只覆盖视口
+ * （`--screenshot` 不传 `--window-size` 时用默认窗口），拿不到内容高就必须先算出来。
+ * 这里在副本里插一段脚本，让**页面自己**把 scrollHeight 写进 title，用 `--dump-dom`
+ * 读回来——全程不依赖 CDP，也不依赖页面配合。
+ *
+ * 副本里同时插 `<base href>`：副本在临时目录，不补 base 的话相对路径的 CSS/图片全部
+ * 404，量到的是裸文本高度（会偏小得离谱）。
+ */
+function measureHeight({ browser, pageUrl, html, baseUrl, width, timeoutMs }) {
+	const dir = mkdtempSync(join(tmpdir(), "dsh-measure-"));
+	const profileDir = mkdtempSync(join(tmpdir(), "dsh-chrome-"));
+	const file = join(dir, "measure.html");
+	const inject =
+		`<base href="${baseUrl}"><script>addEventListener("load",()=>{` +
+		`const d=document.documentElement;` +
+		`document.title="H:"+Math.max(d.scrollHeight,d.getBoundingClientRect().height)});</script>`;
+	// 插在 <head> 后面（base 必须先于其它相对 URL 出现）；没有 head 就塞到 <html> 后
+	let copy = String(html);
+	const headAt = copy.search(/<head[^>]*>/i);
+	if (headAt === -1) copy = inject + copy;
+	else {
+		const end = headAt + copy.slice(headAt).indexOf(">") + 1;
+		copy = copy.slice(0, end) + inject + copy.slice(end);
+	}
+	writeFileSync(file, copy, "utf8");
+
+	try {
+		const run = spawnSync(
+			browser.path,
+			[
+				"--headless=new",
+				"--disable-gpu",
+				"--hide-scrollbars",
+				"--no-first-run",
+				"--no-default-browser-check",
+				"--disable-extensions",
+				"--disable-lcd-text",
+				`--window-size=${width},800`,
+				"--virtual-time-budget=3000",
+				"--dump-dom",
+				`--user-data-dir=${profileDir}`,
+				pathToFileURL(file).href
+			],
+			{ windowsHide: true, timeout: timeoutMs, encoding: "utf8" }
+		);
+		const hit = /H:(\d+)/.exec(String(run.stdout ?? ""));
+		if (hit === null) {
+			throw new Error(
+				"整页截图需要先量内容高，但页面没有回报高度（--dump-dom 输出里没有 H: 标记，页面可能报了 JS 错）。\n" +
+					`改成给明确 height 的视口截图，或手动跑：\n  "${browser.path}" --headless=new --dump-dom "${pageUrl}"`
+			);
+		}
+		// 卡上限：防止某层 height:100vh 把“整页”拉成几万像素而截不出来
+		return Math.min(30_000, Math.max(1, Number.parseInt(hit[1], 10)));
+	} finally {
+		for (const d of [dir, profileDir]) rmSync(d, { recursive: true, force: true });
+	}
+}
+
+/** 读 PNG 的 IHDR 取真实像素尺寸；解析失败返回 0（不因回报失败而连渲染一起报错）。 */
+function pngSize(file) {
+	try {
+		const buf = readFileSync(file);
+		const sig = buf.subarray(0, 8).toString("hex");
+		if (sig !== "89504e470d0a1a0a") return { width: 0, height: 0 };
+		return { width: buf.readUInt32BE(16), height: buf.readUInt32BE(20) };
+	} catch {
+		return { width: 0, height: 0 };
+	}
+}
+
+/**
+ * 把 HTML 渲染成 PNG。
+ * @param {object} opts
+ * @param {string} opts.html  HTML 文件路径，或内联 HTML 标记
+ * @param {string} opts.out   输出 .png 绝对路径
+ * @param {number} [opts.width]  视口宽（默认 1280）
+ * @param {number} [opts.height] 视口高（默认 800）；传 "full" 语义用整页截图
+ * @param {number} [opts.scale]  设备像素比（默认 1；2 = 两倍图）
+ * @param {boolean} [opts.fullPage] 整页截图（两趟：先量出内容高，再按该高截图）
+ * @param {string} [opts.browserPath] 浏览器可执行文件
+ * @param {number} [opts.timeoutMs] 超时（默认 45s）
+ */
+export function renderHtml(opts) {
+	const browser = findBrowser(opts.browserPath);
+	if (browser === null) throw missingBrowserError();
+
+	const width = Number.isFinite(opts.width) ? Math.max(1, Math.round(opts.width)) : 1280;
+	const height = Number.isFinite(opts.height) ? Math.max(1, Math.round(opts.height)) : 800;
+	const scale = Number.isFinite(opts.scale) ? Math.min(4, Math.max(0.5, opts.scale)) : 1;
+	const timeoutMs = Number.isFinite(opts.timeoutMs) ? opts.timeoutMs : 45_000;
+
+	// 内联 HTML 先落到临时文件（浏览器只接受 URL/路径）
+	let pageUrl;
+	let tempDir = null;
+	const raw = String(opts.html ?? "");
+	const looksLikePath = /[\\/]|\.html?$/i.test(raw) && !/[<>]/.test(raw);
+	if (looksLikePath && existsSync(resolve(raw))) {
+		pageUrl = pathToFileURL(resolve(raw)).href;
+	} else {
+		tempDir = mkdtempSync(join(tmpdir(), "dsh-html-"));
+		const file = join(tempDir, "page.html");
+		writeFileSync(file, raw, "utf8");
+		pageUrl = pathToFileURL(file).href;
+	}
+
+	// 输出路径必须**绝对化**：浏览器以临时目录为 cwd 启动，相对路径会落到别处
+	// （实测报“Failed to write file ... 系统找不到指定的路径”）。
+	const outAbs = resolve(opts.out);
+	const profileDir = mkdtempSync(join(tmpdir(), "dsh-chrome-"));
+
+	// 整页截图必须**两趟**。
+	//
+	// 曾经直接写成 `--screenshot`（不带 --window-size）就当成整页——实际上浏览器会按
+	// 自己的默认窗口（实测 750×485）截，既不是整页也不是调用方传的宽高，
+	// 但返回值里又把 width/height 原样回填，于是“报 1100×1500、实际 750×485”，
+	// 看上去成功、图却是残的（靠人眼看图才发现）。
+	//
+	// 正确做法：先用 `--dump-dom` 让页面自己把 scrollHeight 写进 title，读出真实内容高，
+	// 再用 `--window-size=W,内容高` 截第二趟。测高副本里插 `<base>`，保证相对路径的
+	// CSS/图片仍按原目录解析（否则测高页面是裸文本，高度全错）。
+	let shotHeight = height;
+	let measured = false;
+	if (opts.fullPage === true) {
+		shotHeight = measureHeight({
+			browser, pageUrl, width, timeoutMs,
+			html: looksLikePath && existsSync(resolve(raw)) ? readFileSync(resolve(raw), "utf8") : raw,
+			baseUrl: new URL(".", pageUrl).href
+		});
+		measured = true;
+	}
+
+	const args = [
+		"--headless=new",
+		"--disable-gpu",
+		"--hide-scrollbars",
+		"--no-first-run",
+		"--no-default-browser-check",
+		"--disable-extensions",
+		// 关掉 LCD 子像素渲染：否则文字边缘会出现橙/蓝彩色条纹，
+		// 按像素量对比度时会把它们当成“低对比文字”（实测报出 1.97:1 的假结果）。
+		// 灰度抗锯齿下边缘像素与文字同色，量出来的才是真正的对比度。
+		"--disable-lcd-text",
+		`--force-device-scale-factor=${scale}`,
+		`--window-size=${width},${shotHeight}`,
+		"--virtual-time-budget=3000",
+		`--screenshot=${outAbs}`,
+		`--user-data-dir=${profileDir}`,
+		pageUrl
+	];
+
+	try {
+		const run = spawnSync(browser.path, args, {
+			windowsHide: true,
+			timeout: timeoutMs,
+			encoding: "utf8",
+			cwd: tempDir ?? undefined
+		});
+		// Chromium 系即使成功也常往 stderr 写噪音（如 QQBrowser 导入器），不能用 stderr 判成败
+		if (!existsSync(outAbs)) {
+			const stderr = String(run.stderr ?? "").trim().split("\n").slice(-4).join("\n");
+			throw new Error(
+				`HTML 渲染未产出文件（浏览器退出码 ${run.status ?? "null"}）。\n` +
+					`可能的下一步：1) 确认路径可写；2) 加大 timeoutMs；3) 手动跑一次：\n` +
+					`  "${browser.path}" ${args.join(" ")}\n` +
+					(stderr === "" ? "" : `浏览器输出：\n${stderr}`)
+			);
+		}
+		// 回报**实测**尺寸而不是请求尺寸：读 PNG 的 IHDR，报假数字比报错更坏
+		const actual = pngSize(outAbs);
+		return {
+			path: outAbs,
+			bytes: statSync(outAbs).size,
+			width: actual.width === 0 ? width : Math.round(actual.width / scale),
+			height: actual.height === 0 ? shotHeight : Math.round(actual.height / scale),
+			pixelWidth: actual.width,
+			pixelHeight: actual.height,
+			scale,
+			fullPage: opts.fullPage === true,
+			measured,
+			browser: browser.path,
+			browserSource: browser.source
+		};
+	} finally {
+		for (const dir of [tempDir, profileDir]) {
+			if (dir !== null) rmSync(dir, { recursive: true, force: true });
+		}
+	}
+}
+