paintress 0.5.2 → 0.7.0

package/dist/server-DBRmwE_v.js

@@ -0,0 +1,3462 @@
+import { A as genId, B as presetGroupsOf, C as update, E as saveDoc, F as splitFontStack, H as DocumentSchema, I as textFontGaps, L as PROP_TOKEN_KIND, M as isFontSourceKind, N as isGenericFamily, O as validateDoc, P as planFonts, R as isNumericPresetValue, S as remove, T as loadDoc, U as PEN_DOC_VERSION, b as move, g as batch, j as fontRegistryOf, k as collectIds, m as expandRefs, rn as VERSION, t as renderDocument, v as get, w as FileChangedError, x as query, y as insert, z as isPresetType } from "./render-DWs1iQ0v.js";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, realpathSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { pathToFileURL } from "node:url";
+import { basename, dirname, extname, join, relative, resolve, sep } from "node:path";
+import { z } from "zod";
+import { randomUUID } from "node:crypto";
+import { chromium } from "playwright-core";
+import { connect } from "node:net";
+import { spawn } from "node:child_process";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+// \0rolldown/runtime.js
+var __defProp = Object.defineProperty;
+var __exportAll = (all, flags) => {
+	let target = Object.setPrototypeOf({}, null);
+	for (var name in all) __defProp(target, name, {
+		get: all[name],
+		enumerable: true
+	});
+	if (!(flags & 1)) __defProp(target, Symbol.toStringTag, { value: "Module" });
+	return flags & 2 ? target : Object.preventExtensions(target);
+};
+// src/doc/create.ts
+function createDoc(opts = {}) {
+	const boardId = opts.boardId ?? genId(/* @__PURE__ */ new Set());
+	const board = {
+		type: "frame",
+		id: boardId,
+		name: opts.name ?? "Board",
+		x: 0,
+		y: 0,
+		width: opts.width ?? 900,
+		height: opts.height ?? 600,
+		fill: opts.fill ?? "#FFFFFF"
+	};
+	const layout = opts.layout ?? "vertical";
+	if (layout !== "none") {
+		board["layout"] = layout;
+		board["gap"] = opts.gap ?? 0;
+		board["padding"] = opts.padding ?? 0;
+	}
+	return {
+		doc: DocumentSchema.parse({
+			version: PEN_DOC_VERSION,
+			fileToken: opts.fileToken ?? randomUUID(),
+			variables: {},
+			children: [board]
+		}),
+		boardId
+	};
+}
+// src/doc/audit.ts
+const HEX_RE$1 = /^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$/;
+function isRecord$2(v) {
+	return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+function countOf(findings) {
+	const counts = {
+		literal: 0,
+		"orphan-token": 0,
+		"unused-preset": 0,
+		"dangling-preset": 0,
+		"preset-target": 0,
+		"preset-literal": 0,
+		"font-missing": 0,
+		"font-unregistered": 0
+	};
+	for (const f of findings) counts[f.kind] += 1;
+	return counts;
+}
+function summarize(report) {
+	const c = report.counts;
+	return [
+		`越界裸值 ${c.literal}`,
+		`孤儿 token ${c["orphan-token"]}`,
+		`未使用的 preset 组 ${c["unused-preset"]}`,
+		`悬空 preset 引用 ${c["dangling-preset"] + c["preset-target"]}`,
+		`preset 里的裸值 ${c["preset-literal"]}`,
+		`缺字体 ${c["font-missing"]}`,
+		`未登记字体 ${c["font-unregistered"]}`
+	].join(" · ");
+}
+function auditDoc(doc, input) {
+	const findings = [];
+	const colorTokens = /* @__PURE__ */ new Map();
+	const numberTokens = /* @__PURE__ */ new Map();
+	const familyTokens = /* @__PURE__ */ new Map();
+	for (const t of input.tokens) if (t.type === "color") colorTokens.set(t.value.toUpperCase(), t.key);
+	else if (t.type === "font") familyTokens.set(t.value, t.key);
+	else {
+		const n = Number(t.value);
+		if (Number.isFinite(n)) numberTokens.set(`${t.type}:${n}`, t.key);
+	}
+	const usedVars = /* @__PURE__ */ new Set();
+	const usedGroups = /* @__PURE__ */ new Set();
+	const walk = (nodes, inheritedAllowLiteral) => {
+		for (const raw of nodes) {
+			if (!isRecord$2(raw)) continue;
+			const node = raw;
+			const id = typeof node["id"] === "string" ? node["id"] : "?";
+			if (node["type"] === "text") {
+				const ff = node["fontFamily"];
+				if (typeof ff !== "string" || ff.trim() === "") findings.push({
+					kind: "font-missing",
+					where: id,
+					message: "text 没有 fontFamily，正在用默认字体"
+				});
+				else if (!ff.startsWith("$") && input.fonts !== void 0) {
+					for (const family of splitFontStack(ff)) if (!isGenericFamily(family) && input.fonts.families[family] === void 0) findings.push({
+						kind: "font-unregistered",
+						where: id,
+						message: `字体未登记：${family}`
+					});
+				}
+			}
+			const meta = node["metadata"];
+			const allowLiteral = inheritedAllowLiteral || isRecord$2(meta) && (meta["allowLiteral"] === true || meta["allowLiteral"] === "true");
+			const presetName = node["preset"];
+			if (typeof presetName === "string" && presetName !== "") {
+				const group = input.groups[presetName];
+				if (group === void 0) findings.push({
+					kind: "dangling-preset",
+					where: id,
+					message: `preset "${presetName}" 不存在`
+				});
+				else if (group.target !== node["type"]) findings.push({
+					kind: "preset-target",
+					where: id,
+					message: `preset "${presetName}" 适用于 ${group.target}，这里是 ${String(node["type"])}`
+				});
+				else usedGroups.add(presetName);
+			}
+			if (!allowLiteral) {
+				const suggestColor = (value, path) => {
+					if (typeof value === "string") {
+						if (!HEX_RE$1.test(value)) return;
+						const hit = colorTokens.get(value.toUpperCase());
+						if (hit !== void 0) findings.push({
+							kind: "literal",
+							where: id,
+							message: `${path} 写了裸色值 ${value}`,
+							suggestion: `$${hit}`
+						});
+						return;
+					}
+					if (Array.isArray(value)) {
+						value.forEach((entry, index) => suggestColor(entry, `${path}[${index}]`));
+						return;
+					}
+					if (isRecord$2(value)) for (const [key, entry] of Object.entries(value)) suggestColor(entry, `${path}.${key}`);
+				};
+				const suggestNumber = (value, path, kind) => {
+					if (typeof value === "number" && Number.isFinite(value)) {
+						const hit = numberTokens.get(`${kind}:${value}`);
+						if (hit !== void 0) findings.push({
+							kind: "literal",
+							where: id,
+							message: `${path} 写了裸值 ${value}`,
+							suggestion: `$${hit}`
+						});
+						return;
+					}
+					if (Array.isArray(value)) {
+						value.forEach((entry, index) => suggestNumber(entry, `${path}[${index}]`, kind));
+						return;
+					}
+					if (isRecord$2(value)) for (const [key, entry] of Object.entries(value)) suggestNumber(entry, `${path}.${key}`, kind);
+				};
+				const suggestString = (value, path) => {
+					if (typeof value !== "string" || value.startsWith("$")) return;
+					const hit = familyTokens.get(value);
+					if (hit !== void 0) findings.push({
+						kind: "literal",
+						where: id,
+						message: `${path} 写了字体族 "${value}"`,
+						suggestion: `$${hit}`
+					});
+				};
+				for (const [prop, value] of Object.entries(node)) {
+					if (prop === "children") continue;
+					const kind = PROP_TOKEN_KIND[prop];
+					if (kind === "color") suggestColor(value, prop);
+					else if (kind === "font") suggestString(value, prop);
+					else if (kind === "radius" || kind === "spacing" || kind === "fontSize") suggestNumber(value, prop, kind);
+				}
+			}
+			const scan = (v) => {
+				if (typeof v === "string" && v.startsWith("$") && v.length > 1) usedVars.add(v.slice(1));
+				else if (Array.isArray(v)) v.forEach(scan);
+				else if (isRecord$2(v)) Object.values(v).forEach(scan);
+			};
+			scan(node);
+			const kids = node["children"];
+			if (Array.isArray(kids)) walk(kids, allowLiteral);
+		}
+	};
+	walk(doc.children, false);
+	for (const [name, group] of Object.entries(input.groups)) {
+		for (const [prop, value] of Object.entries(group.props)) if (!value.startsWith("$")) findings.push({
+			kind: "preset-literal",
+			where: `<preset:${name}>`,
+			message: `${prop} 写的是字面量 "${value}"，应当引用 $token`
+		});
+		else usedVars.add(value.slice(1));
+		if (!usedGroups.has(name)) findings.push({
+			kind: "unused-preset",
+			where: `<preset:${name}>`,
+			message: `没有任何节点引用 preset "${name}"`
+		});
+	}
+	for (const t of input.tokens) if (!usedVars.has(t.key)) findings.push({
+		kind: "orphan-token",
+		where: `<token:${t.key}>`,
+		message: `token "$${t.key}" 从未被引用`
+	});
+	const report = {
+		findings,
+		counts: countOf(findings)
+	};
+	return {
+		...report,
+		summary: summarize(report)
+	};
+}
+/** MCP / CLI 入口用：从设计稿 + 项目文件凑出审计输入 */
+function auditInputFrom(doc, tokens, presetDoc) {
+	const projectFonts = fontRegistryOf(presetDoc);
+	const ownFonts = fontRegistryOf(doc);
+	return {
+		tokens,
+		groups: {
+			...presetGroupsOf(presetDoc),
+			...presetGroupsOf(doc)
+		},
+		fonts: {
+			...projectFonts,
+			families: {
+				...projectFonts.families,
+				...ownFonts.families
+			}
+		}
+	};
+}
+// src/doc/project.ts
+/**
+* 项目级预设与组件库（规格见 specs/project-presets.md、specs/components.md）。
+*
+* 约定：项目根 = 从设计稿所在目录向上找、最近的含 `__preset.ptr` / `__components.ptr` 的目录。
+* 两个文件都是**普通设计稿**：预设值走原生 `variables`，组件走 `reusable`；项目级语义只放在
+* `x-paintress` 扩展位里。因此 pen 读取器看到它们仍是合法文档。
+*/
+const PRESET_FILE = "__preset.ptr";
+const COMPONENTS_FILE = "__components.ptr";
+/** 拼出设计稿旁边那份笔记的绝对路径（只认 .ptr / .pen，其余扩展名返回 null） */
+function notePathFor(designAbsPath) {
+	if (!/\.(ptr|pen)$/i.test(designAbsPath)) return null;
+	return designAbsPath.replace(/\.(ptr|pen)$/i, ".md");
+}
+function isRecord$1(v) {
+	return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+/**
+* 已注册的项目根（`paintress web` / `paintress watch` 的目录）。
+*
+* **注册根优先于「向上找最近的文件」**：设计稿放在 `design/`、而 `design/` 里又有一份
+* 历史遗留的 `__preset.ptr` 时，向上找会命中错的那一份；watch 才是项目的权威定义。
+*/
+let registeredRoots = [];
+/** 由 daemon / CLI 注入注册根；传空数组等于清空（测试用） */
+function setProjectRoots(roots) {
+	registeredRoots = [...new Set(roots.map((root) => resolve(root)))];
+}
+function registeredRootOf(from) {
+	const abs = resolve(from);
+	let best = null;
+	for (const root of registeredRoots) if (abs === root || abs.startsWith(`${root}${sep}`)) {
+		if (best === null || root.length > best.length) best = root;
+	}
+	return best;
+}
+/** 从 from 向上收集所有「含预设/组件文件」的目录（近 → 远） */
+function ancestorRoots(from) {
+	let dir = resolve(from);
+	try {
+		if (!statSync(dir).isDirectory()) dir = dirname(dir);
+	} catch {
+		dir = dirname(dir);
+	}
+	const out = [];
+	for (;;) {
+		if (existsSync(join(dir, "__preset.ptr")) || existsSync(join(dir, "__components.ptr"))) out.push(dir);
+		const parent = dirname(dir);
+		if (parent === dir || !parent.startsWith(sep)) break;
+		dir = parent;
+	}
+	return out;
+}
+/** 目录 → 项目根（注册根优先；否则最近的含预设/组件文件的祖先）；找不到返回 null */
+function findProjectRoot(from) {
+	return registeredRootOf(from) ?? ancestorRoots(from)[0] ?? null;
+}
+/**
+* 写入用的严格解析：注册根 → 唯一的祖先根 → 显式目录；歧义或无处可写时**直接报错**。
+* 禁止替一个裸设计稿「就地」建项目文件——那正是 `design/__preset.ptr` 这类脏数据的来源。
+*/
+function findProjectRootStrict(from) {
+	const registered = registeredRootOf(from);
+	if (registered !== null) return registered;
+	const candidates = ancestorRoots(from);
+	if (candidates.length > 1) throw new Error(`项目根不唯一：${candidates.join("、")} 都含 ${PRESET_FILE} / ${COMPONENTS_FILE}。\n先运行 paintress web 注册项目（注册目录优先），或显式传入项目目录。`);
+	if (candidates.length === 1) return candidates[0];
+	const abs = resolve(from);
+	try {
+		if (statSync(abs).isDirectory()) return abs;
+	} catch {}
+	throw new Error(`找不到项目根：${from} 不在已注册项目里。\n先在该项目目录下运行 paintress web（会自动建立并返回这两个文件的路径），不要自己另建。`);
+}
+/** 传入文件 → 其所在目录；传入目录 → 自身 */
+function projectDirOf(from) {
+	const abs = resolve(from);
+	try {
+		return statSync(abs).isDirectory() ? abs : dirname(abs);
+	} catch {
+		return dirname(abs);
+	}
+}
+/** 从设计稿 / 目录定位预设文件（存在才算命中） */
+function presetPathFor(from) {
+	const root = findProjectRoot(from);
+	if (root === null) return null;
+	const p = join(root, PRESET_FILE);
+	return existsSync(p) ? p : null;
+}
+function componentsPathFor(from) {
+	const root = findProjectRoot(from);
+	if (root === null) return null;
+	const p = join(root, COMPONENTS_FILE);
+	return existsSync(p) ? p : null;
+}
+/** 根目录下**嵌套**的预设/组件目录（历史遗留或误建）；只报告，不吞掉 */
+const SKIP_DIRS = /* @__PURE__ */ new Set([
+	"node_modules",
+	".git",
+	"dist",
+	".agents",
+	".paintress",
+	"coverage"
+]);
+function findNestedProjectFiles(root, maxDepth = 4) {
+	const abs = resolve(root);
+	const out = [];
+	const walk = (dir, depth) => {
+		if (depth > maxDepth) return;
+		let entries;
+		try {
+			entries = readdirSync(dir, { withFileTypes: true });
+		} catch {
+			return;
+		}
+		for (const entry of entries) {
+			if (!entry.isDirectory() || entry.name.startsWith(".") || SKIP_DIRS.has(entry.name)) continue;
+			const child = join(dir, entry.name);
+			if (existsSync(join(child, "__preset.ptr")) || existsSync(join(child, "__components.ptr"))) out.push(child);
+			walk(child, depth + 1);
+		}
+	};
+	walk(abs, 1);
+	return out;
+}
+/** 项目里两个关键文件的现状；`ensure` 为 true 时先按需创建（只在项目根，绝不在子目录） */
+function projectFilesInfo(root, opts = {}) {
+	const abs = resolve(root);
+	if (opts.ensure === true) ensureProjectScaffold(abs);
+	const presetPath = join(abs, PRESET_FILE);
+	const componentsPath = join(abs, COMPONENTS_FILE);
+	const presetExists = existsSync(presetPath);
+	const componentsExists = existsSync(componentsPath);
+	const file = presetExists ? readPresetFile(presetPath) : null;
+	const groups = file === null ? {} : presetGroupsOf(file.doc);
+	return {
+		root: abs,
+		presetPath,
+		componentsPath,
+		presetExists,
+		componentsExists,
+		presetTokens: file?.items.length ?? 0,
+		presetGroups: Object.keys(groups).length,
+		components: componentsExists ? listComponents(componentsPath).length : 0,
+		conflicts: findNestedProjectFiles(abs)
+	};
+}
+function presetKindOf(key, doc) {
+	const meta = doc["x-paintress"];
+	const items = isRecord$1(meta) && isRecord$1(meta["presets"]) ? meta["presets"]["items"] : void 0;
+	const declared = isRecord$1(items) && isRecord$1(items[key]) ? items[key]["type"] : void 0;
+	const def = doc.variables?.[key];
+	const raw = isRecord$1(def) ? def["value"] : void 0;
+	if ((declared === "font" || declared === void 0) && isNumericPresetValue(raw)) return "fontSize";
+	if (isPresetType(declared)) return declared;
+	const t = isRecord$1(def) ? def["type"] : void 0;
+	if (t === "color") return "color";
+	if (t === "number") return "radius";
+	if (t === "string") return "font";
+	return null;
+}
+/** 读预设文件；不存在返回 null。结构错误直接抛出（带路径上下文） */
+function readPresetFile(path) {
+	if (!existsSync(path)) return null;
+	const loaded = loadDoc(path);
+	const items = [];
+	for (const [key, def] of Object.entries(loaded.doc.variables ?? {})) {
+		if (!isRecord$1(def)) continue;
+		const type = presetKindOf(key, loaded.doc);
+		if (type === null) continue;
+		const raw = def["value"];
+		if (Array.isArray(raw)) continue;
+		const meta = loaded.doc["x-paintress"];
+		const metaItems = isRecord$1(meta) && isRecord$1(meta["presets"]) ? meta["presets"]["items"] : void 0;
+		const declared = isRecord$1(metaItems) && isRecord$1(metaItems[key]) ? metaItems[key] : void 0;
+		items.push({
+			key,
+			type,
+			name: typeof declared?.["name"] === "string" && declared["name"] !== "" ? declared["name"] : key,
+			value: String(raw)
+		});
+	}
+	items.sort((a, b) => a.type === b.type ? a.key.localeCompare(b.key) : a.type.localeCompare(b.type));
+	return {
+		path,
+		doc: loaded.doc,
+		mtimeMs: loaded.mtimeMs,
+		items
+	};
+}
+/** 项目预设（从任意设计稿/目录出发）；没有项目或没有文件都返回空列表 */
+function listPresets(from) {
+	const path = presetPathFor(from);
+	if (path === null) return {
+		path: null,
+		items: []
+	};
+	return {
+		path,
+		items: readPresetFile(path)?.items ?? []
+	};
+}
+/**
+* 读取归一：老文件里 `font` + 数字值的 token 在**合并副本**里按 number 呈现，
+* 让 `resolveNum` 认得它。文件本身一个字都不改，面板与审计报 `fontSize`，
+* 第一次编辑时才落新类型。
+*/
+function normalizedPresetVariables(presetDoc) {
+	const vars = presetDoc?.variables;
+	if (vars === void 0) return void 0;
+	const meta = presetDoc["x-paintress"];
+	const items = isRecord$1(meta) && isRecord$1(meta["presets"]) ? meta["presets"]["items"] : void 0;
+	const out = { ...vars };
+	for (const [key, def] of Object.entries(vars)) {
+		if (!isRecord$1(def)) continue;
+		const declared = isRecord$1(items) && isRecord$1(items[key]) ? items[key]["type"] : void 0;
+		const raw = def["value"];
+		if ((declared === "font" || declared === void 0) && isNumericPresetValue(raw)) out[key] = {
+			...def,
+			type: "number",
+			value: Number(raw)
+		};
+	}
+	return out;
+}
+/**
+* 渲染/校验用的副本：预设打底，文档本地同名变量优先。
+* **绝不能拿去保存** —— 否则一次写入就把预设值烤进了设计稿。
+*/
+function withProjectPresets(doc, presetDoc) {
+	const vars = normalizedPresetVariables(presetDoc);
+	const presetGroups = presetGroupsOf(presetDoc);
+	const ownGroups = presetGroupsOf(doc);
+	const groups = {
+		...presetGroups,
+		...ownGroups
+	};
+	const hasVars = vars !== void 0 && Object.keys(vars).length > 0;
+	const hasGroups = Object.keys(groups).length > 0;
+	if (!hasVars && !hasGroups) return doc;
+	const merged = {
+		...doc,
+		...hasVars ? { variables: {
+			...vars,
+			...doc.variables ?? {}
+		} } : {}
+	};
+	if (!hasGroups) return merged;
+	const meta = doc["x-paintress"];
+	const metaObj = isRecord$1(meta) ? meta : {};
+	const presets = isRecord$1(metaObj["presets"]) ? metaObj["presets"] : {};
+	return {
+		...merged,
+		["x-paintress"]: {
+			...metaObj,
+			presets: {
+				...presets,
+				groups
+			}
+		}
+	};
+}
+/**
+* 渲染 / 校验用：按设计稿所在项目的预设补全变量，返回**副本**（绝不可拿去保存）。
+* 这是「预设只在项目里存一份」的唯一兑付点：渲染、截图、校验、写前检查都走这里。
+*/
+function applyProjectPresets(doc, filePath) {
+	const p = presetPathFor(filePath);
+	const presetDoc = p === null ? null : readPresetFile(p)?.doc ?? null;
+	return {
+		doc: withProjectPresets(doc, presetDoc),
+		presetNames: presetVarNames(presetDoc)
+	};
+}
+/** 项目预设提供的变量名（校验用；只读名字，不做合并） */
+function projectPresetNames(filePath) {
+	const p = presetPathFor(filePath);
+	if (p === null) return /* @__PURE__ */ new Set();
+	return presetVarNames(readPresetFile(p)?.doc ?? null);
+}
+/** 预设文件对应的变量名集合（校验时用来区分「未定义」与「来自项目预设」） */
+function presetVarNames(presetDoc) {
+	return new Set(Object.keys(presetDoc?.variables ?? {}));
+}
+const COLOR_RE = /^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$/;
+/** 值归一：对外字串 → 落盘值；类型不合法时抛出可读错误 */
+function normalizePresetValue(type, value) {
+	const raw = value.trim();
+	if (type === "color") {
+		if (!COLOR_RE.test(raw)) throw new Error(`颜色预设只接受 #RGB / #RRGGBB / #RRGGBBAA，收到：${value}`);
+		return raw.toUpperCase();
+	}
+	if (type === "font") {
+		if (raw === "") throw new Error("字体预设不能为空");
+		return raw;
+	}
+	const n = Number(raw);
+	if (!Number.isFinite(n) || n < 0) throw new Error(`${type === "spacing" ? "间距" : type === "fontSize" ? "字号" : "倒角"}预设只接受非负数，收到：${value}`);
+	return n;
+}
+/** 变量表里的 type：color→color，radius/spacing/fontSize→number，font→string */
+function varTypeOf(type) {
+	if (type === "color") return "color";
+	if (type === "font") return "string";
+	return "number";
+}
+/** x-paintress.presets 的两半：items（token 元数据）与 groups（谱式） */
+function presetsMeta(doc) {
+	const meta = doc["x-paintress"];
+	const presets = isRecord$1(meta) ? meta["presets"] : void 0;
+	const items = isRecord$1(presets) ? presets["items"] : void 0;
+	return {
+		items: isRecord$1(items) ? items : {},
+		groups: presetGroupsOf(doc)
+	};
+}
+/** 写回 __preset.ptr：items 与 groups 必须一起写，否则改一条 token 会把谱式抹掉 */
+function writePresets(path, doc, mtimeMs, items, groups) {
+	const meta = doc["x-paintress"];
+	const metaObj = isRecord$1(meta) ? meta : {};
+	const next = {
+		...doc,
+		["x-paintress"]: {
+			...metaObj,
+			spec: "1",
+			presets: {
+				version: 1,
+				items,
+				groups
+			}
+		}
+	};
+	saveDoc(path, next, {
+		flavor: "ptr",
+		...mtimeMs !== void 0 ? { expectedMtimeMs: mtimeMs } : {}
+	});
+}
+function emptyDoc() {
+	return {
+		version: PEN_DOC_VERSION,
+		fileToken: randomUUID(),
+		variables: {},
+		children: []
+	};
+}
+/** 注册项目时确保两个文件存在；已存在则一个字都不动 */
+function ensureProjectScaffold(root) {
+	const created = [];
+	const targets = [{
+		file: PRESET_FILE,
+		doc: {
+			...emptyDoc(),
+			["x-paintress"]: {
+				spec: "1",
+				presets: {
+					version: 1,
+					items: {}
+				}
+			}
+		}
+	}, {
+		file: COMPONENTS_FILE,
+		doc: {
+			...emptyDoc(),
+			["x-paintress"]: {
+				spec: "1",
+				components: { version: 1 }
+			}
+		}
+	}];
+	for (const t of targets) {
+		const path = join(root, t.file);
+		if (existsSync(path)) continue;
+		try {
+			saveDoc(path, t.doc, {
+				flavor: "ptr",
+				createOnly: true
+			});
+			created.push(path);
+		} catch (cause) {
+			if (existsSync(path)) continue;
+			throw cause;
+		}
+	}
+	return { created };
+}
+/** 写一条预设（新建或改值）；返回最新列表。from 可以是设计稿、预设文件或目录 */
+function setPreset(from, input) {
+	const key = input.key.trim();
+	if (key === "") throw new Error("预设 key 不能为空");
+	if (!/^[A-Za-z0-9._-]+$/.test(key)) throw new Error(`预设 key 只允许字母数字与 . _ -，收到：${key}`);
+	let path = presetPathFor(from);
+	if (path === null) {
+		const root = findProjectRootStrict(from);
+		ensureProjectScaffold(root);
+		path = join(root, PRESET_FILE);
+	}
+	const file = readPresetFile(path);
+	const doc = file?.doc ?? emptyDoc();
+	const value = normalizePresetValue(input.type, input.value);
+	const variables = { ...doc.variables ?? {} };
+	variables[key] = {
+		type: varTypeOf(input.type),
+		value
+	};
+	const { items, groups } = presetsMeta(doc);
+	const metaItems = { ...items };
+	metaItems[key] = {
+		type: input.type,
+		...input.name !== void 0 && input.name !== "" ? { name: input.name } : {}
+	};
+	const next = {
+		...doc,
+		variables
+	};
+	writePresets(path, next, file?.mtimeMs, metaItems, groups);
+	return readPresetFile(path)?.items ?? [];
+}
+/** 删一条预设；返回最新列表（不存在时什么都不做） */
+function removePreset(from, key) {
+	const path = presetPathFor(from);
+	if (path === null) return [];
+	const file = readPresetFile(path);
+	if (file === null) return [];
+	const variables = { ...file.doc.variables ?? {} };
+	if (!(key in variables)) return file.items;
+	delete variables[key];
+	const { items, groups } = presetsMeta(file.doc);
+	const metaItems = { ...items };
+	delete metaItems[key];
+	writePresets(path, {
+		...file.doc,
+		variables
+	}, file.mtimeMs, metaItems, groups);
+	return readPresetFile(path)?.items ?? [];
+}
+/** 预设组列表（谱式）；没有项目文件就返回空 */
+function listPresetGroups(from) {
+	const path = presetPathFor(from);
+	if (path === null) return {
+		path: null,
+		groups: {}
+	};
+	return {
+		path,
+		groups: presetGroupsOf(readPresetFile(path)?.doc ?? null)
+	};
+}
+/** 新建 / 覆盖一个预设组；返回最新列表。from 可以是设计稿、预设文件或目录 */
+function setPresetGroup(from, input) {
+	const name = input.name.trim();
+	if (name === "") throw new Error("预设组名字不能为空");
+	if (!/^[A-Za-z0-9._-]+$/.test(name)) throw new Error(`预设组名字只允许字母数字与 . _ -，收到：${name}`);
+	const target = input.target.trim();
+	if (target === "") throw new Error("预设组必须指定 target（节点类型，如 frame / text）");
+	const props = {};
+	for (const [key, value] of Object.entries(input.props)) {
+		if (typeof value !== "string" || value.trim() === "") continue;
+		props[key] = value.trim();
+	}
+	if (Object.keys(props).length === 0) throw new Error("预设组至少要有一个属性");
+	let path = presetPathFor(from);
+	if (path === null) {
+		const root = findProjectRootStrict(from);
+		ensureProjectScaffold(root);
+		path = join(root, PRESET_FILE);
+	}
+	const file = readPresetFile(path);
+	const doc = file?.doc ?? emptyDoc();
+	const { items, groups } = presetsMeta(doc);
+	const nextGroups = {
+		...groups,
+		[name]: {
+			target,
+			props
+		}
+	};
+	writePresets(path, doc, file?.mtimeMs, items, nextGroups);
+	return {
+		path,
+		groups: presetGroupsOf(readPresetFile(path)?.doc ?? null)
+	};
+}
+/** 删一个预设组（不存在时什么都不做） */
+function removePresetGroup(from, name) {
+	const path = presetPathFor(from);
+	if (path === null) return {
+		path: null,
+		groups: {}
+	};
+	const file = readPresetFile(path);
+	if (file === null) return {
+		path,
+		groups: {}
+	};
+	const { items, groups } = presetsMeta(file.doc);
+	if (!(name in groups)) return {
+		path,
+		groups
+	};
+	const nextGroups = { ...groups };
+	delete nextGroups[name];
+	writePresets(path, file.doc, file.mtimeMs, items, nextGroups);
+	return {
+		path,
+		groups: presetGroupsOf(readPresetFile(path)?.doc ?? null)
+	};
+}
+/** 全树按 id 找节点（组件库、复制插入、画廊都用这一处） */
+function findNodeIn(nodes, id) {
+	for (const n of nodes) {
+		if (!n || typeof n !== "object") continue;
+		const rec = n;
+		if (rec["id"] === id) return rec;
+		const kids = rec["children"];
+		if (Array.isArray(kids)) {
+			const hit = findNodeIn(kids, id);
+			if (hit !== null) return hit;
+		}
+	}
+	return null;
+}
+/** 组件库里的所有 reusable 节点（全树扫描） */
+function listComponents(componentsPath) {
+	const doc = readPresetFile(componentsPath)?.doc ?? loadDoc(componentsPath).doc;
+	const out = [];
+	const walk = (nodes) => {
+		for (const n of nodes) {
+			if (!isRecord$1(n)) continue;
+			if (n["reusable"] === true && typeof n["id"] === "string") out.push({
+				id: n["id"],
+				name: typeof n["name"] === "string" && n["name"] !== "" ? n["name"] : n["id"],
+				type: typeof n["type"] === "string" ? n["type"] : "?",
+				...typeof n["width"] === "number" ? { width: n["width"] } : {},
+				...typeof n["height"] === "number" ? { height: n["height"] } : {}
+			});
+			const kids = n["children"];
+			if (Array.isArray(kids)) walk(kids);
+		}
+	};
+	walk(doc.children ?? []);
+	return out;
+}
+/** 读组件库文件（含 mtime，供乐观并发写入用） */
+function readComponentsFile(path) {
+	if (!existsSync(path)) return null;
+	const loaded = loadDoc(path);
+	return {
+		doc: loaded.doc,
+		mtimeMs: loaded.mtimeMs
+	};
+}
+/** 备注：`readFileSync` 保留给调用方做小文件快读（笔记接口用） */
+function readTextIfExists(path, maxBytes = 524288) {
+	if (!existsSync(path)) return null;
+	const st = statSync(path);
+	if (!st.isFile()) return null;
+	if (st.size > maxBytes) throw new Error(`文件过大（${st.size} 字节，上限 ${maxBytes}）：${path}`);
+	return readFileSync(path, "utf8");
+}
+/** 项目字体注册表（`x-paintress.fonts`）；没有预设文件就是空表 */
+function projectFontRegistry(from) {
+	const path = presetPathFor(from);
+	if (path === null) return {
+		path: null,
+		registry: { families: {} }
+	};
+	return {
+		path,
+		registry: fontRegistryOf(readPresetFile(path)?.doc ?? null)
+	};
+}
+/** 定位/初始化预设文件（写字体与 seed 共用） */
+function presetFileForWrite(from) {
+	let path = presetPathFor(from);
+	if (path === null) {
+		const root = findProjectRootStrict(from);
+		ensureProjectScaffold(root);
+		path = join(root, PRESET_FILE);
+	}
+	return {
+		path,
+		file: readPresetFile(path)
+	};
+}
+function writeFontRegistry(path, doc, mtimeMs, registry) {
+	const meta = doc["x-paintress"];
+	const metaObj = isRecord$1(meta) ? meta : {};
+	saveDoc(path, {
+		...doc,
+		["x-paintress"]: {
+			...metaObj,
+			spec: "1",
+			fonts: registry
+		}
+	}, {
+		flavor: "ptr",
+		...mtimeMs !== void 0 ? { expectedMtimeMs: mtimeMs } : {}
+	});
+}
+/** 写一条字体登记；`system`/`bundle` 必须给 preview，`css`/`file` 的路径必须在项目内且存在 */
+function setFontEntry(from, input) {
+	const family = input.family.trim();
+	if (family === "") throw new Error("字体 family 不能为空");
+	if (family.startsWith("$")) throw new Error("family 写真实字体名，不要写 $token");
+	if (!isFontSourceKind(input.source.kind)) throw new Error("source.kind 必须是 web / css / file / system / bundle");
+	const kind = input.source.kind;
+	const target = input.source.target?.trim();
+	if (kind !== "system" && kind !== "bundle" && (target === void 0 || target === "")) throw new Error(`${kind} 来源必须给 target（web 写 CSS URL，css/file 写项目内相对路径）`);
+	if (kind === "web" && !/^https?:\/\//i.test(target ?? "")) throw new Error("web 来源的 target 必须是 http(s) URL");
+	if (kind === "css" || kind === "file") {
+		const root = findProjectRoot(from) ?? projectDirOf(from);
+		const abs = resolve(root, target);
+		const rel = relative(root, abs);
+		if (rel.startsWith("..") || rel.includes(`..${sep}`)) throw new Error(`字体路径越出项目：${target}`);
+		if (!existsSync(abs)) throw new Error(`字体文件不存在：${target}（相对项目根 ${root}）`);
+	}
+	const preview = input.preview?.trim();
+	if ((kind === "system" || kind === "bundle") && (preview === void 0 || preview === "")) throw new Error(`${kind} 来源必须给 preview（设计期替代字体）`);
+	const { path, file } = presetFileForWrite(from);
+	const registry = fontRegistryOf(file?.doc ?? null);
+	const entry = {
+		source: {
+			kind,
+			...target !== void 0 && target !== "" ? { target } : {}
+		},
+		...preview !== void 0 && preview !== "" ? { preview } : {},
+		...input.metrics !== void 0 ? { metrics: input.metrics } : {},
+		...input.note !== void 0 && input.note !== "" ? { note: input.note } : {}
+	};
+	const next = {
+		...registry,
+		families: {
+			...registry.families,
+			[family]: entry
+		}
+	};
+	writeFontRegistry(path, file?.doc ?? emptyDoc(), file?.mtimeMs, next);
+	return next;
+}
+/** 删一条字体登记（不动设计稿；引用它的节点会在 validate 出 warning） */
+function removeFontEntry(from, family) {
+	const path = presetPathFor(from);
+	if (path === null) return { families: {} };
+	const file = readPresetFile(path);
+	if (file === null) return { families: {} };
+	const registry = fontRegistryOf(file.doc);
+	if (registry.families[family] === void 0) return registry;
+	const families = { ...registry.families };
+	delete families[family];
+	const next = {
+		...registry,
+		families
+	};
+	writeFontRegistry(path, file.doc, file.mtimeMs, next);
+	return next;
+}
+/** 设项目默认字体（font token key 或 family） */
+function setDefaultFont(from, value) {
+	const v = value.trim();
+	if (v === "") throw new Error("默认字体不能为空");
+	const { path, file } = presetFileForWrite(from);
+	const next = {
+		...fontRegistryOf(file?.doc ?? null),
+		default: v
+	};
+	writeFontRegistry(path, file?.doc ?? emptyDoc(), file?.mtimeMs, next);
+	return next;
+}
+const SEED_TOKENS = [
+	{
+		key: "color-text",
+		type: "color",
+		value: "#111827"
+	},
+	{
+		key: "color-text-muted",
+		type: "color",
+		value: "#6B7280"
+	},
+	{
+		key: "color-surface",
+		type: "color",
+		value: "#FFFFFF"
+	},
+	{
+		key: "color-surface-muted",
+		type: "color",
+		value: "#F3F4F6"
+	},
+	{
+		key: "color-border",
+		type: "color",
+		value: "#E5E7EB"
+	},
+	{
+		key: "color-brand",
+		type: "color",
+		value: "#2563EB"
+	},
+	{
+		key: "color-danger",
+		type: "color",
+		value: "#DC2626"
+	},
+	{
+		key: "color-success",
+		type: "color",
+		value: "#059669"
+	},
+	{
+		key: "radius-4",
+		type: "radius",
+		value: "4"
+	},
+	{
+		key: "radius-8",
+		type: "radius",
+		value: "8"
+	},
+	{
+		key: "radius-12",
+		type: "radius",
+		value: "12"
+	},
+	{
+		key: "radius-full",
+		type: "radius",
+		value: "999"
+	},
+	{
+		key: "spacing-4",
+		type: "spacing",
+		value: "4"
+	},
+	{
+		key: "spacing-8",
+		type: "spacing",
+		value: "8"
+	},
+	{
+		key: "spacing-12",
+		type: "spacing",
+		value: "12"
+	},
+	{
+		key: "spacing-16",
+		type: "spacing",
+		value: "16"
+	},
+	{
+		key: "spacing-24",
+		type: "spacing",
+		value: "24"
+	},
+	{
+		key: "spacing-32",
+		type: "spacing",
+		value: "32"
+	},
+	{
+		key: "spacing-48",
+		type: "spacing",
+		value: "48"
+	},
+	{
+		key: "fontSize-12",
+		type: "fontSize",
+		value: "12"
+	},
+	{
+		key: "fontSize-14",
+		type: "fontSize",
+		value: "14"
+	},
+	{
+		key: "fontSize-16",
+		type: "fontSize",
+		value: "16"
+	},
+	{
+		key: "fontSize-20",
+		type: "fontSize",
+		value: "20"
+	},
+	{
+		key: "fontSize-24",
+		type: "fontSize",
+		value: "24"
+	},
+	{
+		key: "fontSize-32",
+		type: "fontSize",
+		value: "32"
+	},
+	{
+		key: "font-sans",
+		type: "font",
+		value: "Inter Variable, Noto Sans SC Variable"
+	},
+	{
+		key: "font-mono",
+		type: "font",
+		value: "ui-monospace, SFMono-Regular, monospace"
+	}
+];
+const SEED_GROUPS = [
+	{
+		name: "text.body",
+		target: "text",
+		props: {
+			fontSize: "$fontSize-16",
+			fill: "$color-text"
+		}
+	},
+	{
+		name: "text.muted",
+		target: "text",
+		props: {
+			fontSize: "$fontSize-14",
+			fill: "$color-text-muted"
+		}
+	},
+	{
+		name: "text.title",
+		target: "text",
+		props: {
+			fontSize: "$fontSize-24",
+			fill: "$color-text"
+		}
+	},
+	{
+		name: "button",
+		target: "frame",
+		props: {
+			fill: "$color-brand",
+			cornerRadius: "$radius-8"
+		}
+	},
+	{
+		name: "card",
+		target: "frame",
+		props: {
+			fill: "$color-surface",
+			cornerRadius: "$radius-12",
+			stroke: "$color-border"
+		}
+	},
+	{
+		name: "input",
+		target: "frame",
+		props: {
+			fill: "$color-surface",
+			cornerRadius: "$radius-8",
+			stroke: "$color-border"
+		}
+	}
+];
+const SEED_FONTS = {
+	"Inter Variable": {
+		source: {
+			kind: "web",
+			target: "https://cdn.jsdelivr.net/npm/@fontsource-variable/inter@5.3.0/wght.css"
+		},
+		preview: "system-ui"
+	},
+	"Noto Sans SC Variable": {
+		source: {
+			kind: "web",
+			target: "https://cdn.jsdelivr.net/npm/@fontsource-variable/noto-sans-sc@5.3.1/wght.css"
+		},
+		preview: "system-ui"
+	}
+};
+const SEED_DEFAULT_FONT = "font-sans";
+/**
+* 预设种子：一次给出颜色 / 倒角 / 间距 / 字号 / 字体 + 六个常用 preset 组。
+* **只补缺失、永不覆盖**；默认 dry-run（`apply: true` 才落盘），只写一次文件。
+*/
+function seedDesignSystem(from, opts = {}) {
+	const apply = opts.apply === true;
+	const path = presetPathFor(from) ?? (apply ? presetFileForWrite(from).path : null);
+	const file = path === null ? null : readPresetFile(path);
+	const doc = file?.doc ?? emptyDoc();
+	const items = file?.items ?? [];
+	const groups = presetGroupsOf(doc);
+	const registry = fontRegistryOf(doc);
+	const existingTokens = new Set(items.map((item) => item.key));
+	const existingGroups = new Set(Object.keys(groups));
+	const existingFonts = new Set(Object.keys(registry.families));
+	const created = {
+		tokens: [],
+		groups: [],
+		fonts: [],
+		defaultFont: false
+	};
+	const skipped = {
+		tokens: [],
+		groups: [],
+		fonts: [],
+		defaultFont: false
+	};
+	for (const token of SEED_TOKENS) (existingTokens.has(token.key) ? skipped.tokens : created.tokens).push(token.key);
+	for (const group of SEED_GROUPS) (existingGroups.has(group.name) ? skipped.groups : created.groups).push(group.name);
+	for (const family of Object.keys(SEED_FONTS)) (existingFonts.has(family) ? skipped.fonts : created.fonts).push(family);
+	if (registry.default === void 0) created.defaultFont = true;
+	else skipped.defaultFont = true;
+	if (!apply || path === null) return {
+		applied: false,
+		created,
+		skipped
+	};
+	const variables = { ...doc.variables ?? {} };
+	const metaItems = { ...presetsMeta(doc).items };
+	for (const token of SEED_TOKENS) {
+		if (!created.tokens.includes(token.key)) continue;
+		variables[token.key] = {
+			type: varTypeOf(token.type),
+			value: normalizePresetValue(token.type, token.value)
+		};
+		metaItems[token.key] = { type: token.type };
+	}
+	const nextGroups = { ...groups };
+	for (const group of SEED_GROUPS) if (created.groups.includes(group.name)) nextGroups[group.name] = {
+		target: group.target,
+		props: group.props
+	};
+	const families = { ...registry.families };
+	for (const [family, entry] of Object.entries(SEED_FONTS)) if (created.fonts.includes(family)) families[family] = entry;
+	const nextRegistry = {
+		...registry,
+		families,
+		...created.defaultFont ? { default: SEED_DEFAULT_FONT } : {}
+	};
+	const meta = doc["x-paintress"];
+	const metaObj = isRecord$1(meta) ? meta : {};
+	saveDoc(path, {
+		...doc,
+		variables,
+		["x-paintress"]: {
+			...metaObj,
+			spec: "1",
+			presets: {
+				version: 1,
+				items: metaItems,
+				groups: nextGroups
+			},
+			fonts: nextRegistry
+		}
+	}, {
+		flavor: "ptr",
+		...file?.mtimeMs !== void 0 ? { expectedMtimeMs: file.mtimeMs } : {}
+	});
+	return {
+		applied: true,
+		created,
+		skipped
+	};
+}
+// src/doc/album.ts
+/**
+* 画谱的两个操作：establish（从现有稿里提取 token / preset）与 adjust（改一处、看影响面）。
+*
+* 分工：本模块只做分析与改写计划；写盘走 `project.ts` 的 setPreset / setPresetGroup，
+* 设计稿改写走 `saveDoc`（带 mtime 防覆盖）。`apply=false` 时一个字节都不写。
+*/
+function isRecord(v) {
+	return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+/** 一次性设计的逃生舱：建立候选与改写都跳过，但继续检查后代 */
+function allowsLiteral(node) {
+	const meta = node["metadata"];
+	return isRecord(meta) && (meta["allowLiteral"] === true || meta["allowLiteral"] === "true");
+}
+const HEX_RE = /^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$/;
+/** 参与提取的属性：颜色（fill/stroke）与数值（圆角/间距/字号） */
+const COLOR_PROPS = ["fill", "stroke"];
+const NUM_PROPS = [
+	{
+		prop: "cornerRadius",
+		kind: "radius"
+	},
+	{
+		prop: "gap",
+		kind: "spacing"
+	},
+	{
+		prop: "fontSize",
+		kind: "fontSize"
+	}
+];
+/** 建议的 token key：由值推导，可重复运行；必须符合 VARIABLE_NAME（不允许小数点等字符） */
+function suggestTokenKey(type, value) {
+	const safe = (type === "color" ? value.replace(/^#/, "") : value).replace(/[^A-Za-z0-9_-]+/g, "-");
+	if (type === "color") return `color-${safe.toLowerCase()}`;
+	if (type === "radius") return `radius-${safe}`;
+	if (type === "spacing") return `spacing-${safe}`;
+	if (type === "fontSize") return `fontSize-${safe}`;
+	return `font-${safe}`;
+}
+/**
+* 从设计稿提取候选：同一字面量被 ≥ minUses 处使用 → 建议 token；
+* 同一类节点带同一组属性 ≥ minUses 次 → 建议 preset 组（属性值只引用已建议的 token）。
+*/
+function planEstablish(doc, opts = {}) {
+	const minUses = Math.max(2, opts.minUses ?? 2);
+	const colorUses = /* @__PURE__ */ new Map();
+	const numUses = /* @__PURE__ */ new Map();
+	const signatures = /* @__PURE__ */ new Map();
+	const walk = (nodes, inheritedAllowLiteral = false) => {
+		for (const raw of nodes) {
+			if (!isRecord(raw)) continue;
+			const node = raw;
+			const allowLiteral = inheritedAllowLiteral || allowsLiteral(node);
+			const id = typeof node["id"] === "string" ? node["id"] : "?";
+			const type = typeof node["type"] === "string" ? node["type"] : "?";
+			if (!allowLiteral) {
+				for (const prop of COLOR_PROPS) {
+					const v = node[prop];
+					if (typeof v === "string" && HEX_RE.test(v)) {
+						const list = colorUses.get(v.toUpperCase()) ?? [];
+						list.push({
+							id,
+							prop
+						});
+						colorUses.set(v.toUpperCase(), list);
+					}
+				}
+				for (const { prop, kind } of NUM_PROPS) {
+					const v = node[prop];
+					if (typeof v === "number" && Number.isFinite(v)) {
+						const mapKey = `${kind}:${v}`;
+						const hit = numUses.get(mapKey) ?? {
+							kind,
+							value: String(v),
+							uses: []
+						};
+						hit.uses.push({
+							id,
+							prop
+						});
+						numUses.set(mapKey, hit);
+					}
+				}
+				const styleProps = {};
+				for (const prop of [
+					"fill",
+					"stroke",
+					"cornerRadius",
+					"gap"
+				]) {
+					const v = node[prop];
+					if (typeof v === "string" && HEX_RE.test(v)) styleProps[prop] = v.toUpperCase();
+					else if (typeof v === "number" && Number.isFinite(v)) styleProps[prop] = String(v);
+				}
+				if (Object.keys(styleProps).length >= 2) {
+					const sig = `${type}|${JSON.stringify(styleProps)}`;
+					const hit = signatures.get(sig) ?? {
+						target: type,
+						props: styleProps,
+						ids: []
+					};
+					hit.ids.push(id);
+					signatures.set(sig, hit);
+				}
+			}
+			const kids = node["children"];
+			if (Array.isArray(kids)) walk(kids, allowLiteral);
+		}
+	};
+	walk(doc.children);
+	const tokens = [];
+	const tokenByValue = /* @__PURE__ */ new Map();
+	for (const [value, uses] of colorUses) {
+		if (uses.length < minUses) continue;
+		const key = suggestTokenKey("color", value);
+		tokens.push({
+			key,
+			type: "color",
+			value,
+			uses
+		});
+		tokenByValue.set(`color:${value}`, key);
+	}
+	for (const [, entry] of numUses) {
+		if (entry.uses.length < minUses) continue;
+		const key = suggestTokenKey(entry.kind, entry.value);
+		tokens.push({
+			key,
+			type: entry.kind,
+			value: entry.value,
+			uses: entry.uses
+		});
+		tokenByValue.set(`${entry.kind}:${entry.value}`, key);
+	}
+	const seen = /* @__PURE__ */ new Set();
+	const uniqueTokens = tokens.filter((t) => seen.has(t.key) ? false : (seen.add(t.key), true));
+	const groups = [];
+	const groupNames = /* @__PURE__ */ new Set();
+	for (const [, hit] of signatures) {
+		if (hit.ids.length < minUses) continue;
+		const props = {};
+		let complete = true;
+		for (const [prop, value] of Object.entries(hit.props)) {
+			const kind = HEX_RE.test(value) ? "color" : prop === "cornerRadius" ? "radius" : "spacing";
+			const key = tokenByValue.get(`${kind}:${value}`);
+			if (key === void 0) {
+				complete = false;
+				break;
+			}
+			props[prop] = `$${key}`;
+		}
+		if (!complete || Object.keys(props).length < 2) continue;
+		let name = `preset-${hit.target}`;
+		let i = 2;
+		while (groupNames.has(name)) name = `preset-${hit.target}-${i++}`;
+		groupNames.add(name);
+		groups.push({
+			name,
+			target: hit.target,
+			props,
+			uses: hit.ids
+		});
+	}
+	return {
+		tokens: uniqueTokens,
+		groups
+	};
+}
+/**
+* 应用提取结果：写 token / preset 组，并把命中的节点改写成引用。
+* 传 expectedMtimeMs 时，**先**检查设计稿再写预设，避免计划过期后留下半套变更。
+*/
+function applyEstablish(designPath, plan, opts = {}) {
+	if (opts.expectedMtimeMs !== void 0 && statSync(designPath).mtimeMs !== opts.expectedMtimeMs) throw new FileChangedError(designPath);
+	const presetPath = `${findProjectRootStrict(designPath)}/${PRESET_FILE}`;
+	const existingTokens = new Map(listPresets(presetPath).items.map((item) => [item.key, item]));
+	for (const token of plan.tokens) {
+		const existing = existingTokens.get(token.key);
+		if (existing !== void 0 && (existing.type !== token.type || existing.value !== token.value)) throw new Error(`token "${token.key}" 已存在且定义不同，拒绝覆盖（现有 ${existing.value}，候选 ${token.value}）`);
+	}
+	const existingGroups = listPresetGroups(presetPath).groups;
+	for (const group of plan.groups) {
+		const existing = existingGroups[group.name];
+		if (existing !== void 0 && (existing.target !== group.target || JSON.stringify(existing.props) !== JSON.stringify(group.props))) throw new Error(`preset 组 "${group.name}" 已存在且定义不同，拒绝覆盖；请先调整候选组名`);
+	}
+	const writtenTokens = [];
+	for (const t of plan.tokens) {
+		setPreset(presetPath, {
+			key: t.key,
+			type: t.type,
+			value: t.value
+		});
+		writtenTokens.push(t.key);
+	}
+	const writtenGroups = [];
+	for (const g of plan.groups) {
+		setPresetGroup(presetPath, {
+			name: g.name,
+			target: g.target,
+			props: g.props
+		});
+		writtenGroups.push(g.name);
+	}
+	const loaded = loadDoc(designPath);
+	const groupByNode = /* @__PURE__ */ new Map();
+	for (const g of plan.groups) for (const id of g.uses) groupByNode.set(id, g);
+	const tokenByValue = /* @__PURE__ */ new Map();
+	for (const t of plan.tokens) tokenByValue.set(`${t.type}:${t.value.toUpperCase()}`, t.key);
+	let updated = 0;
+	const rewrite = (nodes, inheritedAllowLiteral = false) => {
+		for (const raw of nodes) {
+			if (!isRecord(raw)) continue;
+			const node = raw;
+			if (inheritedAllowLiteral || allowsLiteral(node)) {
+				const kids = node["children"];
+				if (Array.isArray(kids)) rewrite(kids, true);
+				continue;
+			}
+			const id = typeof node["id"] === "string" ? node["id"] : "";
+			const group = groupByNode.get(id);
+			if (group !== void 0 && node["preset"] === void 0) {
+				for (const prop of Object.keys(group.props)) delete node[prop];
+				node["preset"] = group.name;
+				updated += 1;
+			} else {
+				let touched = false;
+				for (const prop of COLOR_PROPS) {
+					const value = node[prop];
+					if (typeof value !== "string" || !HEX_RE.test(value)) continue;
+					const key = tokenByValue.get(`color:${value.toUpperCase()}`);
+					if (key !== void 0) {
+						node[prop] = `$${key}`;
+						touched = true;
+					}
+				}
+				for (const { prop, kind } of NUM_PROPS) {
+					const value = node[prop];
+					if (typeof value !== "number" || !Number.isFinite(value)) continue;
+					const key = tokenByValue.get(`${kind}:${String(value)}`);
+					if (key !== void 0) {
+						node[prop] = `$${key}`;
+						touched = true;
+					}
+				}
+				if (touched) updated += 1;
+			}
+			const kids = node["children"];
+			if (Array.isArray(kids)) rewrite(kids);
+		}
+	};
+	rewrite(loaded.doc.children);
+	if (updated > 0) saveDoc(designPath, loaded.doc, {
+		expectedMtimeMs: loaded.mtimeMs,
+		flavor: loaded.flavor
+	});
+	return {
+		applied: true,
+		tokens: plan.tokens,
+		groups: plan.groups,
+		written: {
+			tokens: writtenTokens,
+			groups: writtenGroups,
+			nodes: updated
+		}
+	};
+}
+function resolveVars(doc, presetDoc) {
+	const out = {};
+	for (const src of [presetDoc?.variables, doc.variables]) for (const [k, def] of Object.entries(src ?? {})) {
+		const raw = isRecord(def) ? def["value"] : void 0;
+		const v = Array.isArray(raw) ? raw[0]?.["value"] : raw;
+		if (typeof v === "string" || typeof v === "number" || typeof v === "boolean") out[k] = String(v);
+	}
+	return out;
+}
+/**
+* 改一处的影响面（dry-run）：token 被哪些节点/组引用、preset 组被哪些节点引用，
+* 每条都给出 `before → after`。不写盘。
+*/
+function planAdjust(doc, presetDoc, req) {
+	const groups = {
+		...presetGroupsOf(presetDoc),
+		...presetGroupsOf(doc)
+	};
+	const vars = resolveVars(doc, presetDoc);
+	const changes = [];
+	if (req.key !== void 0 && req.key !== "") {
+		const ref = `$${req.key}`;
+		const before = vars[req.key] ?? "";
+		const walk = (nodes) => {
+			for (const raw of nodes) {
+				if (!isRecord(raw)) continue;
+				const id = typeof raw["id"] === "string" ? raw["id"] : "?";
+				const scan = (value, propPath) => {
+					if (value === ref) {
+						changes.push({
+							where: id,
+							prop: propPath,
+							before,
+							after: req.value
+						});
+						return;
+					}
+					if (Array.isArray(value)) {
+						value.forEach((entry, index) => scan(entry, `${propPath}[${index}]`));
+						return;
+					}
+					if (isRecord(value)) for (const [key, entry] of Object.entries(value)) scan(entry, `${propPath}.${key}`);
+				};
+				for (const [prop, value] of Object.entries(raw)) if (prop !== "children") scan(value, prop);
+				const kids = raw["children"];
+				if (Array.isArray(kids)) walk(kids);
+			}
+		};
+		walk(doc.children);
+		for (const [name, g] of Object.entries(groups)) for (const [prop, value] of Object.entries(g.props)) if (value === ref) changes.push({
+			where: `<preset:${name}>`,
+			prop,
+			before,
+			after: req.value
+		});
+		return {
+			kind: "token",
+			target: req.key,
+			value: req.value,
+			changes
+		};
+	}
+	if (req.group !== void 0 && req.group !== "" && req.prop !== void 0 && req.prop !== "") {
+		const group = groups[req.group];
+		if (group === void 0) throw new Error(`preset 组不存在：${req.group}`);
+		const groupProp = req.prop;
+		const beforeRef = group.props[groupProp] ?? "";
+		const before = beforeRef.startsWith("$") ? vars[beforeRef.slice(1)] ?? beforeRef : beforeRef;
+		const walk = (nodes) => {
+			for (const raw of nodes) {
+				if (!isRecord(raw)) continue;
+				const id = typeof raw["id"] === "string" ? raw["id"] : "?";
+				if (raw["preset"] === req.group && raw[groupProp] === void 0) changes.push({
+					where: id,
+					prop: groupProp,
+					before,
+					after: req.value
+				});
+				const kids = raw["children"];
+				if (Array.isArray(kids)) walk(kids);
+			}
+		};
+		walk(doc.children);
+		return {
+			kind: "group",
+			target: req.group,
+			prop: groupProp,
+			value: req.value,
+			changes
+		};
+	}
+	throw new Error("adjust 需要 key（改 token）或 group + prop（改 preset 组属性）");
+}
+/** 应用：只写 `__preset.ptr`；设计稿里的引用自动跟着变 */
+function applyAdjust(designPath, presetDoc, plan) {
+	if (plan.kind === "token") {
+		const existing = listPresets(designPath).items.find((p) => p.key === plan.target);
+		if (existing === void 0) throw new Error(`token 不存在：${plan.target}`);
+		setPreset(`${findProjectRootStrict(designPath)}/${PRESET_FILE}`, {
+			key: existing.key,
+			type: existing.type,
+			value: plan.value,
+			name: existing.name
+		});
+		return {
+			...plan,
+			applied: true
+		};
+	}
+	const group = presetGroupsOf(presetDoc)[plan.target];
+	if (group === void 0) throw new Error(`preset 组不存在：${plan.target}`);
+	const prop = plan.prop;
+	if (prop === void 0 || prop === "") throw new Error(`adjust 计划缺少组属性名：${plan.target}`);
+	const nextProps = {
+		...group.props,
+		[prop]: plan.value
+	};
+	setPresetGroup(`${findProjectRootStrict(designPath)}/${PRESET_FILE}`, {
+		name: plan.target,
+		target: group.target,
+		props: nextProps
+	});
+	return {
+		...plan,
+		applied: true
+	};
+}
+/** 读项目预设文档（没有就是 null） */
+function readPresetDoc(designPath) {
+	const root = findProjectRoot(designPath);
+	if (root === null) return null;
+	return readPresetFile(`${root}/__preset.ptr`)?.doc ?? null;
+}
+// src/shot/screenshot.ts
+/**
+* 截图层：渲染 → 临时 HTML → headless Chromium → PNG（决策 3：两个消费者分开，AI 要 PNG）。
+* 浏览器探测：PTR_BROWSER 环境变量 → 系统 chrome → playwright 浏览器缓存。
+*/
+function findBrowser() {
+	const env = process.env["PTR_BROWSER"];
+	if (env && existsSync(env)) return env;
+	for (const c of [
+		"/usr/bin/google-chrome",
+		"/usr/bin/google-chrome-stable",
+		"/usr/bin/chromium",
+		"/usr/bin/chromium-browser"
+	]) if (existsSync(c)) return c;
+	const cacheDir = join(homedir(), ".cache", "ms-playwright");
+	if (existsSync(cacheDir)) {
+		const dirs = readdirSync(cacheDir).filter((d) => d.startsWith("chromium-")).sort((a, b) => b.localeCompare(a));
+		for (const d of dirs) for (const rel of [
+			"chrome-linux/chrome",
+			"chrome-linux64/chrome",
+			"chrome-headless-shell-linux64/chrome-headless-shell"
+		]) {
+			const p = join(cacheDir, d, rel);
+			if (existsSync(p)) return p;
+		}
+	}
+	return null;
+}
+/** 单边像素上限：超出按比例压回，只为不把内存/临时文件吃爆 */
+const MAX_SHOT_EDGE = 8192;
+/** agent 自审图的默认倍率 */
+const DEFAULT_SHOT_SCALE = .8;
+/** 倍率下限：再小就看不清字了 */
+const MIN_SHOT_SCALE = .2;
+/**
+* 倍率决策：先夹进 [0.2, 2]，再按画布/画板的**设计尺寸**（1x 像素数）等比压进 8192。
+* 1x 的定义就是查看器里的 `1:1`——画板自身的像素尺寸，所以这里量的是 CSS px。
+*/
+function planShotScale(requested, width, height) {
+	const asked = requested !== void 0 && Number.isFinite(requested) ? requested : DEFAULT_SHOT_SCALE;
+	const clampedValue = Math.min(2, Math.max(MIN_SHOT_SCALE, asked));
+	const w = Math.max(1, width);
+	const h = Math.max(1, height);
+	const fit = Math.min(MAX_SHOT_EDGE / w, MAX_SHOT_EDGE / h);
+	const scale = Math.min(clampedValue, fit);
+	return {
+		scale,
+		clamped: clampedValue !== asked,
+		capped: scale < clampedValue
+	};
+}
+function boardLabel(b) {
+	return b.name !== void 0 && b.name !== "" ? `${b.name}(id=${b.id})` : b.id;
+}
+/**
+* 画板选择子：id 精确 → name 精确 → name/id 模糊（不区分大小写）。
+* 模糊命中多个时报歧义并列出候选，不猜——猜错会让 AI 以为看到了另一页。
+*/
+function selectBoard(boards, query) {
+	if (boards.length === 0) throw new Error("设计稿没有画板（顶层节点为空），无法按画板截图");
+	const q = query.trim();
+	if (q === "") throw new Error("board 参数不能为空");
+	const byId = boards.filter((b) => b.id === q);
+	if (byId.length === 1) return byId[0];
+	const byName = boards.filter((b) => b.name === q);
+	if (byName.length === 1) return byName[0];
+	const lower = q.toLowerCase();
+	const fuzzy = boards.filter((b) => b.id.toLowerCase().includes(lower) || (b.name ?? "").toLowerCase().includes(lower));
+	if (fuzzy.length === 1) return fuzzy[0];
+	const all = boards.map(boardLabel).join("、");
+	if (fuzzy.length === 0) throw new Error(`没有匹配「${q}」的画板；可选：${all}`);
+	throw new Error(`「${q}」命中 ${fuzzy.length} 个画板，请写更精确的名字或 id：${fuzzy.map(boardLabel).join("、")}`);
+}
+/** 渲染并截图整张画布；指定 board 时只裁该画板（走同一套渲染与浏览器） */
+async function screenshotPen(penPath, outPng, opts = {}) {
+	const browserPath = findBrowser();
+	if (!browserPath) throw new Error("未找到可用浏览器：安装 Chromium/Chrome，或设置 PTR_BROWSER 指向可执行文件");
+	const loaded = loadDoc(penPath);
+	const root = findProjectRoot(penPath) ?? dirname(resolve(penPath));
+	const { registry: fontRegistry } = projectFontRegistry(penPath);
+	const fontPlan = planFonts(fontRegistry, (source) => source.target === void 0 ? null : pathToFileURL(resolve(root, source.target)).href);
+	const rendered = renderDocument(applyProjectPresets(loaded.doc, penPath).doc, { fonts: fontPlan });
+	const probeFamilies = [.../* @__PURE__ */ new Set([...Object.keys(fontRegistry.families), ...splitFontStack(fontPlan.defaultStack).filter((family) => !isGenericFamily(family))])];
+	const target = opts.board !== void 0 ? selectBoard(rendered.boards, opts.board) : void 0;
+	const tmpDir = mkdtempSync(join(tmpdir(), "paintress-shot-"));
+	const htmlPath = join(tmpDir, "page.html");
+	writeFileSync(htmlPath, rendered.html, "utf8");
+	let clip;
+	let measuredBoard;
+	let usedScale = DEFAULT_SHOT_SCALE;
+	let fontsReport;
+	const extraWarnings = [];
+	const cacheDir = join(process.env["PAINTRESS_HOME"] ?? join(homedir(), ".paintress"), "chromium-cache");
+	try {
+		mkdirSync(cacheDir, { recursive: true });
+	} catch {}
+	try {
+		const browser = await chromium.launch({
+			executablePath: browserPath,
+			args: [
+				"--no-sandbox",
+				"--disable-dev-shm-usage",
+				`--disk-cache-dir=${cacheDir}`,
+				"--disk-cache-size=67108864"
+			]
+		});
+		try {
+			const initial = planShotScale(opts.scale, rendered.canvas.width || 1, rendered.canvas.height || 1);
+			const page = await browser.newPage({
+				viewport: {
+					width: Math.max(800, rendered.canvas.width, target !== void 0 ? Math.ceil(target.x + 3200) : 0),
+					height: Math.max(600, rendered.canvas.height, target !== void 0 ? Math.ceil(target.y + 3200) : 0)
+				},
+				deviceScaleFactor: initial.scale
+			});
+			await page.goto(`file://${htmlPath}`);
+			const fontsScript = `(async () => {
+        const families = ${JSON.stringify(probeFamilies)};
+        const wait = new Promise((r) => setTimeout(r, 3000));
+        if (window.__paintressFontsReady) await Promise.race([window.__paintressFontsReady, wait]);
+        else if (document.fonts && document.fonts.ready) await Promise.race([document.fonts.ready, wait]);
+        if (!document.fonts) return { status: 'n/a', checked: families, missing: [] };
+        const c = document.createElement('canvas').getContext('2d');
+        const text = '漢字Abc123 光伴';
+        const w = (f, b) => { c.font = '32px "' + f + '", ' + b; return c.measureText(text).width; };
+        const sb = w('__paintress_missing__', 'serif');
+        const mb = w('__paintress_missing__', 'monospace');
+        const missing = families.filter((f) => Math.abs(w(f, 'serif') - sb) < 0.5 && Math.abs(w(f, 'monospace') - mb) < 0.5);
+        return { status: document.fonts.status, checked: families, missing };
+      })()`;
+			fontsReport = await page.evaluate(fontsScript);
+			await page.waitForTimeout(opts.settleMs ?? 120);
+			const measured = await page.evaluate(`(() => {
+        const canvasEl = document.querySelector('.ptr-canvas');
+        const cr = canvasEl ? canvasEl.getBoundingClientRect() : null;
+        const nodes = Array.from(document.querySelectorAll('[data-board]'));
+        const boards = nodes.map((el) => {
+          const r = el.getBoundingClientRect();
+          return {
+            id: el.getAttribute('data-node-id') || '',
+            name: el.getAttribute('data-board-name') || undefined,
+            x: cr ? r.left - cr.left : 0,
+            y: cr ? r.top - cr.top : 0,
+            w: r.width,
+            h: r.height
+          };
+        });
+        // 自动尺寸的设计稿常常撑出 .ptr-canvas 的固定宽高：以真实内容盒为准
+        let contentW = cr ? cr.width : 0;
+        let contentH = cr ? cr.height : 0;
+        for (const b of boards) {
+          contentW = Math.max(contentW, b.x + b.w);
+          contentH = Math.max(contentH, b.y + b.h);
+        }
+        return { width: Math.ceil(contentW), height: Math.ceil(contentH), boards };
+      })()`);
+			const realTarget = target === void 0 ? void 0 : measured.boards.find((b) => b.id === target.id) ?? void 0;
+			if (realTarget !== void 0 && target !== void 0) {
+				if (realTarget.w <= 0 || realTarget.h <= 0) throw new Error(`画板 ${boardLabel(target)} 尺寸为 0（${realTarget.w}×${realTarget.h}），无法截图`);
+				measuredBoard = {
+					id: target.id,
+					...target.name !== void 0 ? { name: target.name } : {},
+					x: Math.round(realTarget.x),
+					y: Math.round(realTarget.y),
+					w: realTarget.w,
+					h: realTarget.h
+				};
+			} else if (target !== void 0) {
+				if (target.w <= 0 || target.h <= 0) throw new Error(`画板 ${boardLabel(target)} 尺寸为 0（${target.w}×${target.h}），无法截图`);
+				measuredBoard = {
+					id: target.id,
+					...target.name !== void 0 ? { name: target.name } : {},
+					x: target.x,
+					y: target.y,
+					w: target.w,
+					h: target.h
+				};
+			}
+			const box = measuredBoard ?? {
+				x: 0,
+				y: 0,
+				w: measured.width,
+				h: measured.height
+			};
+			clip = {
+				x: Math.max(0, Math.floor(box.x)),
+				y: Math.max(0, Math.floor(box.y)),
+				width: Math.max(1, Math.ceil(box.w)),
+				height: Math.max(1, Math.ceil(box.h))
+			};
+			const vp = page.viewportSize();
+			const needW = clip.x + clip.width;
+			const needH = clip.y + clip.height;
+			if (vp === null || vp.width < needW || vp.height < needH) {
+				await page.setViewportSize({
+					width: Math.max(vp?.width ?? 0, needW),
+					height: Math.max(vp?.height ?? 0, needH)
+				});
+				await page.waitForTimeout(20);
+			}
+			const plan = planShotScale(opts.scale, clip.width, clip.height);
+			usedScale = plan.scale;
+			if (plan.clamped) extraWarnings.push(`倍率 ${String(opts.scale)} 超出 0.2–2，已按 ${plan.scale}x 输出`);
+			if (plan.capped) extraWarnings.push(`画板 ${clip.width}×${clip.height}（1x）按 ${plan.scale.toFixed(2)}x 输出：单边超过 ${MAX_SHOT_EDGE} 上限，已等比压回`);
+			if (Math.abs(plan.scale - initial.scale) > 1e-6) {
+				const finalVp = page.viewportSize();
+				await page.close();
+				const fitted = await browser.newPage({
+					viewport: {
+						width: Math.max(1, Math.ceil(finalVp?.width ?? clip.x + clip.width)),
+						height: Math.max(1, Math.ceil(finalVp?.height ?? clip.y + clip.height))
+					},
+					deviceScaleFactor: plan.scale
+				});
+				try {
+					await fitted.goto(`file://${htmlPath}`);
+					await fitted.waitForTimeout(opts.settleMs ?? 120);
+					await fitted.screenshot({
+						path: outPng,
+						clip
+					});
+				} finally {
+					await fitted.close();
+				}
+			} else await page.screenshot({
+				path: outPng,
+				clip
+			});
+		} finally {
+			await browser.close();
+		}
+	} finally {
+		rmSync(tmpDir, {
+			recursive: true,
+			force: true
+		});
+	}
+	if (statSync(outPng).size === 0) throw new Error("截图产物为空文件");
+	const canvas = {
+		width: Math.max(rendered.canvas.width, clip.x + clip.width),
+		height: Math.max(rendered.canvas.height, clip.y + clip.height)
+	};
+	const substituted = (fontsReport?.missing ?? []).filter((family) => fontPlan.previews[family] !== void 0);
+	if (fontsReport !== void 0 && fontsReport.missing.length > 0) extraWarnings.push(`字体缺失：${fontsReport.missing.join("、")}${substituted.length > 0 ? `（用替代：${substituted.join("、")}）` : ""}`);
+	const result = {
+		out: outPng,
+		canvas,
+		scale: usedScale,
+		warnings: [...rendered.warnings, ...extraWarnings],
+		browser: browserPath,
+		...fontsReport !== void 0 ? { fonts: {
+			...fontsReport,
+			substituted
+		} } : {}
+	};
+	if (measuredBoard !== void 0) result.board = {
+		id: measuredBoard.id,
+		...measuredBoard.name !== void 0 ? { name: measuredBoard.name } : {},
+		x: measuredBoard.x,
+		y: measuredBoard.y,
+		width: measuredBoard.w,
+		height: measuredBoard.h
+	};
+	return result;
+}
+// src/web/protocol.ts
+function encodeLine(msg) {
+	return `${JSON.stringify(msg)}\n`;
+}
+/** 逐行解析器：处理流式分片，容忍尾部不完整行 */
+var LineDecoder = class {
+	buf = "";
+	push(chunk) {
+		this.buf += chunk;
+		const out = [];
+		for (;;) {
+			const idx = this.buf.indexOf("\n");
+			if (idx < 0) break;
+			const line = this.buf.slice(0, idx);
+			this.buf = this.buf.slice(idx + 1);
+			if (line.trim() !== "") out.push(line);
+		}
+		return out;
+	}
+};
+// src/web/paths.ts
+/** 运行期文件位置：默认 ~/.paintress/；可用 PAINTRESS_HOME 覆盖（测试隔离用） */
+function runtimeDir() {
+	const dir = process.env["PAINTRESS_HOME"] ?? join(homedir(), ".paintress");
+	mkdirSync(dir, {
+		recursive: true,
+		mode: 448
+	});
+	return dir;
+}
+function socketPath() {
+	return join(runtimeDir(), "web.sock");
+}
+function lockPath() {
+	return join(runtimeDir(), "web.lock");
+}
+function pidPath() {
+	return join(runtimeDir(), "web.pid");
+}
+/**
+* 项目名：URL 安全（字母数字点下划线连字符与 `/`），冲突时加短 hash 后缀。
+* 允许 `/` 表达目录层级：默认项目名就是 `父目录/自身`（如 `c-thun/raybend`）。
+*/
+function sanitizeProjectName(name) {
+	const cleaned = name.replace(/[^A-Za-z0-9._/-]/g, "-").replace(/\.{2,}/g, ".").replace(/\/{2,}/g, "/").replace(/^[./-]+|[./-]+$/g, "");
+	return cleaned === "" ? "project" : cleaned;
+}
+/**
+* 由目录推导默认项目名：`父目录/自身`（适配 repos/<org>/<project> 结构）。
+* key 里直接带 `/`，URL 与展示都无需再转义。
+*/
+function deriveProjectName(dir) {
+	const abs = resolve(dir);
+	const parent = basename(dirname(abs));
+	const self = basename(abs);
+	return sanitizeProjectName(parent && parent !== "/" ? `${parent}/${self}` : self);
+}
+/** 校验并解析注册目录：必须存在且是目录；返回真实路径（供穿越校验基准） */
+function resolveProjectDir(dir) {
+	const abs = resolve(dir);
+	if (!existsSync(abs)) throw new Error(`目录不存在：${abs}`);
+	if (!statSync(abs).isDirectory()) throw new Error(`不是目录：${abs}`);
+	return {
+		root: abs,
+		rootReal: realpathSync(abs)
+	};
+}
+/**
+* 路径穿越防护：把请求路径解析为真实绝对路径，并确认它仍在项目根内。
+* 失败返回 null（调用方回 404，不泄露真实路径）。
+*/
+function safeJoin(projectRootReal, requestPath) {
+	if (requestPath.includes("\0")) return null;
+	const normalized = requestPath.replace(/^\/+/, "");
+	const target = resolve(join(projectRootReal, normalized));
+	const relStr = relative(projectRootReal, target);
+	if (relStr === "" || relStr.startsWith("..") || relStr.includes(`..${sep}`)) return null;
+	if (!existsSync(target)) return null;
+	let real;
+	try {
+		real = realpathSync(target);
+	} catch {
+		return null;
+	}
+	const relReal = relative(projectRootReal, real);
+	if (relReal.startsWith("..") || relReal === "") return null;
+	return real;
+}
+// src/web/client.ts
+/** 控制面客户端：一次请求/响应，或保持长连接（attach 用） */
+function isDaemonRunning() {
+	return existsSync(socketPath());
+}
+/**
+* 查询运行中的 daemon：未运行、socket 残留、daemon 无响应都返回 null。
+* 调用方拿到 null 就可以安全地走「启动」分支 —— 幂等的判据只有这一处。
+*/
+async function queryDaemon(timeoutMs = 2e3) {
+	if (!isDaemonRunning()) return null;
+	try {
+		const res = await sendRequest({ kind: "ping" }, timeoutMs);
+		if (res.ok && "pong" in res) return {
+			pid: res.pid,
+			port: res.port,
+			uptimeMs: res.uptimeMs
+		};
+	} catch {}
+	return null;
+}
+function connectSocket() {
+	return new Promise((resolve, reject) => {
+		const sock = connect(socketPath());
+		const onError = (err) => {
+			sock.destroy();
+			reject(/* @__PURE__ */ new Error(`无法连接 paintress web（${socketPath()}）：${err.message}`));
+		};
+		sock.once("error", onError);
+		sock.once("connect", () => {
+			sock.off("error", onError);
+			sock.on("error", () => {});
+			resolve(sock);
+		});
+	});
+}
+/** 单次请求；超时默认 5s */
+async function sendRequest(req, timeoutMs = 5e3) {
+	const sock = await connectSocket();
+	return new Promise((resolve, reject) => {
+		const decoder = new LineDecoder();
+		const timer = setTimeout(() => {
+			sock.destroy();
+			reject(/* @__PURE__ */ new Error(`请求超时（${timeoutMs}ms）`));
+		}, timeoutMs);
+		sock.on("data", (chunk) => {
+			for (const line of decoder.push(chunk.toString("utf8"))) {
+				let parsed;
+				try {
+					parsed = JSON.parse(line);
+				} catch {
+					continue;
+				}
+				clearTimeout(timer);
+				sock.end();
+				resolve(parsed);
+				return;
+			}
+		});
+		sock.on("close", () => {
+			clearTimeout(timer);
+			reject(/* @__PURE__ */ new Error("daemon 在响应前关闭了连接"));
+		});
+		sock.on("error", (err) => {
+			clearTimeout(timer);
+			reject(err);
+		});
+		sock.write(encodeLine(req));
+	});
+}
+/**
+* 持久 attach：连接保持打开，进程退出时 OS 关闭连接 → daemon 立即感知。
+* 这取代了 PID 轮询（PID 会被内核复用，不可靠）。
+*/
+async function attachPersistent(project) {
+	const sock = await connectSocket();
+	const decoder = new LineDecoder();
+	let closed = false;
+	const closeCbs = [];
+	return new Promise((resolve, reject) => {
+		const timer = setTimeout(() => {
+			sock.destroy();
+			reject(/* @__PURE__ */ new Error("attach 超时"));
+		}, 5e3);
+		sock.on("data", (chunk) => {
+			for (const line of decoder.push(chunk.toString("utf8"))) {
+				let parsed;
+				try {
+					parsed = JSON.parse(line);
+				} catch {
+					continue;
+				}
+				if (parsed.ok && "attached" in parsed) {
+					clearTimeout(timer);
+					resolve({
+						close: () => {
+							if (closed) return;
+							closed = true;
+							sock.end();
+						},
+						isClosed: () => closed,
+						onClose: (cb) => closeCbs.push(cb)
+					});
+				} else if (!parsed.ok) {
+					clearTimeout(timer);
+					sock.destroy();
+					reject(new Error(parsed.error));
+				}
+			}
+		});
+		sock.on("close", () => {
+			closed = true;
+			for (const cb of closeCbs) cb();
+		});
+		sock.on("error", (err) => {
+			clearTimeout(timer);
+			reject(err);
+		});
+		sock.write(encodeLine({
+			kind: "attach",
+			project
+		}));
+	});
+}
+function daemonPid() {
+	try {
+		const raw = readFileSync(pidPath(), "utf8").trim();
+		const pid = Number(raw);
+		return Number.isInteger(pid) && pid > 0 ? pid : null;
+	} catch {
+		return null;
+	}
+}
+// src/web/spawn.ts
+const START_TIMEOUT_MS = 6e3;
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/**
+* 复用已在运行的 daemon；显式指定了端口且与运行中的不一致时抛错
+* （幂等不等于「悄悄忽略你的参数」：要换端口得先 `paintress stop`）。
+*/
+async function reuseDaemon(port) {
+	const info = await queryDaemon();
+	if (info === null) return null;
+	if (port !== void 0 && port !== info.port) throw new Error(`paintress web 已在运行（pid ${info.pid}，端口 ${info.port}），与请求的端口 ${port} 不同；如需换端口请先 paintress stop`);
+	return info;
+}
+/** 启动超时的诊断信息：区分「进程没起来」与「进程在但控制面不通」 */
+function timeoutHint() {
+	const pid = daemonPid();
+	if (pid !== null) try {
+		process.kill(pid, 0);
+		return `；进程 ${pid} 仍在运行但控制面无响应，先运行 paintress stop（或 kill ${pid}）后重试`;
+	} catch {}
+	return "；可能是锁或端口残留，先 paintress ping 看状态，或前台跑 paintress web 看报错";
+}
+async function ensureDaemon(opts = {}) {
+	const running = await reuseDaemon(opts.port);
+	if (running !== null) return {
+		started: false,
+		pid: running.pid,
+		port: running.port
+	};
+	const entry = process.argv[1];
+	if (!entry) throw new Error("无法确定 CLI 入口路径，不能后台启动 daemon");
+	const args = [
+		entry,
+		"web",
+		"--foreground"
+	];
+	if (opts.port !== void 0) args.push("--port", String(opts.port));
+	if (opts.idleTimeoutMs !== void 0) args.push("--idle", String(opts.idleTimeoutMs));
+	if (opts.noOpen === true) args.push("--no-open");
+	const child = spawn(process.execPath, args, {
+		detached: true,
+		stdio: "ignore"
+	});
+	child.unref();
+	let exitCode = null;
+	child.once("exit", (code) => {
+		exitCode = code;
+	});
+	const deadline = Date.now() + START_TIMEOUT_MS;
+	while (Date.now() < deadline) {
+		const info = await queryDaemon(500);
+		if (info !== null) {
+			if (opts.port !== void 0 && info.port !== opts.port) throw new Error(`daemon 起在端口 ${info.port} 而不是请求的 ${opts.port}；先 paintress stop 再重试`);
+			return {
+				started: true,
+				pid: info.pid,
+				port: info.port
+			};
+		}
+		if (exitCode !== null) throw new Error(`后台 daemon 启动失败（退出码 ${exitCode}）${timeoutHint()}`);
+		await sleep(100);
+	}
+	throw new Error(`后台启动 daemon 超时（${START_TIMEOUT_MS}ms）${timeoutHint()}`);
+}
+// src/web/open-browser.ts
+var open_browser_exports = /* @__PURE__ */ __exportAll({ openBrowser: () => openBrowser });
+/** 按 PATH 找可执行文件（不 shell out，避免和 shell 引号规则纠缠） */
+function onPath(cmd) {
+	if (cmd.includes("/")) return existsSync(cmd);
+	for (const dir of (process.env["PATH"] ?? "").split(":")) if (dir !== "" && existsSync(`${dir}/${cmd}`)) return true;
+	return false;
+}
+function readOsrelease() {
+	try {
+		return readFileSync("/proc/sys/kernel/osrelease", "utf8");
+	} catch {
+		return null;
+	}
+}
+/**
+* 是否跑在 WSL 里。环境变量优先（WSL_DISTRO_NAME / WSL_INTEROP），
+* 内核 release 里带 "microsoft" 是兜底（detached 子进程可能继承不到变量）。
+*/
+function isWsl(ctx = {}) {
+	if ((ctx.platform ?? process.platform) !== "linux") return false;
+	const env = ctx.env ?? process.env;
+	if ((env["WSL_DISTRO_NAME"] ?? "") !== "" || (env["WSL_INTEROP"] ?? "") !== "") return true;
+	const rel = ctx.osrelease !== void 0 ? ctx.osrelease : readOsrelease();
+	return rel !== null && /microsoft/i.test(rel);
+}
+/** Windows 侧打开 URL 的候选命令，按可靠度排序 */
+function windowsLaunchers(url) {
+	const ps = `Start-Process '${url.replace(/'/g, "''")}'`;
+	return [
+		{
+			cmd: "wslview",
+			args: [url]
+		},
+		{
+			cmd: "powershell.exe",
+			args: [
+				"-NoProfile",
+				"-NonInteractive",
+				"-Command",
+				ps
+			]
+		},
+		{
+			cmd: "cmd.exe",
+			args: [
+				"/c",
+				"start",
+				"",
+				url
+			]
+		},
+		{
+			cmd: "explorer.exe",
+			args: [url]
+		}
+	];
+}
+/**
+* 选出「在宿主浏览器里打开」的启动命令；返回 null 表示这台机器上没有可用的浏览器入口
+* （无图形环境、或 WSL 里一个 interop 命令都没有 —— 此时宁可不弹，也不要弹到错的浏览器）。
+*/
+function browserLauncher(url, ctx = {}) {
+	const platform = ctx.platform ?? process.platform;
+	const env = ctx.env ?? process.env;
+	const has = ctx.has ?? onPath;
+	if (isWsl(ctx)) return windowsLaunchers(url).find((l) => has(l.cmd)) ?? null;
+	if (platform === "darwin") return has("open") ? {
+		cmd: "open",
+		args: [url]
+	} : null;
+	if (platform === "win32") return {
+		cmd: "cmd",
+		args: [
+			"/c",
+			"start",
+			"",
+			url
+		]
+	};
+	if ((env["DISPLAY"] ?? "") === "" && (env["WAYLAND_DISPLAY"] ?? "") === "") return null;
+	return has("xdg-open") ? {
+		cmd: "xdg-open",
+		args: [url]
+	} : null;
+}
+function openBrowser(url, ctx = {}) {
+	const env = ctx.env ?? process.env;
+	if (env["PAINTRESS_NO_OPEN"] === "1") return false;
+	if (env["CI"] === "1" || env["CI"] === "true") return false;
+	const launcher = browserLauncher(url, ctx);
+	if (launcher === null) return false;
+	try {
+		const child = spawn(launcher.cmd, launcher.args, {
+			detached: true,
+			stdio: "ignore"
+		});
+		child.on("error", () => {});
+		child.unref();
+		return true;
+	} catch {
+		return false;
+	}
+}
+/** 顶层页面地址（项目列表）；项目深链见 projectUrl */
+function baseUrl(port) {
+	return `http://localhost:${port}/`;
+}
+/** 项目深链：项目 key 本身就带 `/`（`c-thun/raybend`），URL 里不需要转义 */
+function projectUrl(port, project, file) {
+	if (!project) return baseUrl(port);
+	return `http://localhost:${port}/${project.split("/").filter((s) => s !== "").map(encodeURIComponent).join("/")}${file ? `?file=${encodeURIComponent(file)}` : ""}`;
+}
+// src/web/autoregister.ts
+/**
+* 每个项目的 attach 连接必须被持有：daemon 用「连接是否还在」判定 agent 是否活着。
+* 连接一断，agent 自动注册的项目会在宽限期后退场。
+*/
+const handles = /* @__PURE__ */ new Map();
+/** 从 daemon 同步「注册根」，让 doc 层的 findProjectRoot 以 watch 为准 */
+let rootsSynced = false;
+async function syncProjectRoots() {
+	try {
+		const res = await sendRequest({ kind: "status" }, 2e3);
+		if (res.ok && "projects" in res && Array.isArray(res.projects)) {
+			setProjectRoots(res.projects.map((p) => p.root));
+			rootsSynced = true;
+		}
+	} catch {}
+}
+/** 进程退出时释放连接（daemon 立刻看到 agent 走了，比等 OS 回收快） */
+function closeViewerHandles() {
+	for (const handle of handles.values()) try {
+		handle.close();
+	} catch {}
+	handles.clear();
+}
+function autoWebDisabled() {
+	return process.env["PAINTRESS_NO_AUTO_WEB"] === "1";
+}
+/** 幂等入口：确保 daemon 在跑、项目已注册、本进程持有存活连接，返回可分享的 URL */
+async function ensureViewer(opts = {}) {
+	if (autoWebDisabled()) throw new Error("PAINTRESS_NO_AUTO_WEB=1：已关闭自动查看器，需要手动运行 paintress web");
+	const dir = resolve(opts.dir ?? process.cwd());
+	const project = opts.project !== void 0 ? sanitizeProjectName(opts.project) : deriveProjectName(dir);
+	const running = await queryDaemon();
+	const attached = handles.get(project);
+	if (running !== null && attached !== void 0 && !attached.isClosed()) {
+		if (!rootsSynced) await syncProjectRoots();
+		return {
+			project,
+			root: dir,
+			pid: running.pid,
+			port: running.port,
+			url: projectUrl(running.port, project),
+			startedDaemon: false
+		};
+	}
+	const { started, pid, port } = await ensureDaemon({ noOpen: true });
+	const watched = await sendRequest({
+		kind: "watch",
+		project,
+		dir,
+		owner: "agent",
+		...opts.depth !== void 0 ? { depth: opts.depth } : {}
+	}, 8e3);
+	if (!watched.ok) throw new Error(watched.error);
+	attached?.close();
+	handles.set(project, await attachPersistent(project));
+	rootsSynced = false;
+	await syncProjectRoots();
+	if (started) openBrowser(projectUrl(port, project));
+	return {
+		project,
+		root: dir,
+		pid,
+		port,
+		url: projectUrl(port, project),
+		startedDaemon: started
+	};
+}
+/**
+* MCP server 启动时自动注册自身（best-effort，失败不阻断 MCP）。
+* 与 ensureViewer 同一条路径 —— 启动时注册和「开始画之前补一次」是同一件事。
+*/
+async function autoRegister(cwd = process.cwd()) {
+	if (autoWebDisabled()) return null;
+	try {
+		return await ensureViewer({ dir: cwd });
+	} catch (cause) {
+		process.stderr.write(`paintress: web 自动注册失败（${cause instanceof Error ? cause.message : String(cause)}），MCP 工具不受影响\n`);
+		return null;
+	}
+}
+// src/mcp/tools.ts
+function reqStr(args, key) {
+	const v = args[key];
+	if (typeof v !== "string" || v === "") throw new Error(`缺少必填参数：${key}`);
+	return v;
+}
+function optStr(args, key) {
+	const v = args[key];
+	return typeof v === "string" && v !== "" ? v : void 0;
+}
+function optNum(args, key) {
+	const v = args[key];
+	return typeof v === "number" && Number.isFinite(v) ? v : void 0;
+}
+function optBool(args, key) {
+	const v = args[key];
+	return typeof v === "boolean" ? v : void 0;
+}
+function objArg(args, key) {
+	const v = args[key];
+	if (!v || typeof v !== "object" || Array.isArray(v)) throw new Error(`参数 ${key} 必须是对象`);
+	return v;
+}
+/** 读：load 后执行，直接返回负载 */
+function read(path, fn) {
+	return fn(loadDoc(path));
+}
+/**
+* 把「本次写操作动到的节点 id」告知 daemon，供前端做变更高亮。
+* 先转绝对路径：daemon 的 cwd 未必与调用方一致，不能让 daemon 替我们 resolve 相对路径。
+* 非阻塞发送（写路径性能语义不变）；socket 默认有 ref，进程不会在响应前提前退出。
+*/
+function notifyChanges(path, ids) {
+	if (ids.length === 0 || !isDaemonRunning()) return;
+	sendRequest({
+		kind: "changes",
+		path: resolve(path),
+		ids
+	}, 2e3).catch(() => {});
+}
+/** 最近一次字体探针报告（viewer + 截图都写进 daemon）；daemon 没跑就返回空 */
+async function fetchFontReports(path) {
+	if (!isDaemonRunning()) return [];
+	const name = (findProjectRoot(path) ?? resolve(path)).split("/").slice(-2).join("/");
+	try {
+		const res = await sendRequest({
+			kind: "fonts",
+			project: name
+		}, 2e3);
+		if (!res.ok) return [];
+		return (res.reports ?? []).map((r) => ({
+			path: r.path,
+			checked: r.checked,
+			missing: r.missing
+		}));
+	} catch {
+		return [];
+	}
+}
+/** 当前设计系统概览：token 计数、preset 组、字体、组件、字体缺口 */
+function designSystemFor(path, doc) {
+	const presets = listPresets(path);
+	const groups = listPresetGroups(path).groups;
+	const fonts = projectFontRegistry(path).registry;
+	const compPath = componentsPathFor(path);
+	const components = compPath === null ? [] : listComponents(compPath);
+	const gaps = textFontGaps(doc, fonts);
+	const tokens = {
+		color: 0,
+		radius: 0,
+		spacing: 0,
+		fontSize: 0,
+		font: 0
+	};
+	for (const item of presets.items) tokens[item.type] = (tokens[item.type] ?? 0) + 1;
+	const empty = presets.items.length === 0 && components.length === 0;
+	return {
+		presetPath: presets.path,
+		tokens,
+		groups: Object.entries(groups).map(([name, group]) => ({
+			name,
+			target: group.target,
+			props: group.props
+		})),
+		fonts: {
+			default: fonts.default ?? null,
+			families: Object.keys(fonts.families)
+		},
+		components: components.length,
+		gaps: {
+			textNodes: gaps.textNodes,
+			ids: gaps.ids,
+			unregistered: gaps.unregistered
+		},
+		...empty ? { next: "项目还没有设计系统：用 paintress_preset seed 建立尺度，再 paintress_font list 看字体" } : {}
+	};
+}
+/** 写完给 agent 的提示：等值 token、没写字体、未登记字体（最多 3 条，不阻断） */
+function collectHints(path, doc, ids) {
+	const items = listPresets(path).items;
+	const colorByValue = /* @__PURE__ */ new Map();
+	const numberByKind = /* @__PURE__ */ new Map();
+	const familyByValue = /* @__PURE__ */ new Map();
+	for (const item of items) if (item.type === "color") colorByValue.set(item.value.toUpperCase(), item.key);
+	else if (item.type === "font") familyByValue.set(item.value, item.key);
+	else numberByKind.set(`${item.type}:${item.value}`, item.key);
+	const registry = projectFontRegistry(path).registry;
+	const hints = [];
+	for (const id of [...new Set(ids)]) {
+		const node = findNodeIn(doc.children, id);
+		if (node === null) continue;
+		if (node["type"] === "text") {
+			const ff = node["fontFamily"];
+			if (typeof ff !== "string" || ff.trim() === "") hints.push(`${id}: text 没有 fontFamily，正在用默认字体；补一个 $font-* 或 family`);
+			else if (!ff.startsWith("$")) {
+				for (const family of splitFontStack(ff)) if (!isGenericFamily(family) && registry.families[family] === void 0) hints.push(`${id}: 字体 ${family} 未登记（paintress_font add）`);
+			}
+		}
+		for (const [prop, value] of Object.entries(node)) {
+			if (prop === "children") continue;
+			const kind = PROP_TOKEN_KIND[prop];
+			if (kind === void 0) continue;
+			if (typeof value === "string" && value.startsWith("$")) continue;
+			if (kind === "color" && typeof value === "string") {
+				const hit = colorByValue.get(value.toUpperCase());
+				if (hit !== void 0) hints.push(`${id}.${prop} 写了裸色值 ${value}，可写 $${hit}`);
+			} else if ((kind === "radius" || kind === "spacing" || kind === "fontSize") && typeof value === "number") {
+				const hit = numberByKind.get(`${kind}:${String(value)}`);
+				if (hit !== void 0) hints.push(`${id}.${prop} 写了裸值 ${value}，可写 $${hit}`);
+			} else if (kind === "font" && typeof value === "string") {
+				const hit = familyByValue.get(value);
+				if (hit !== void 0) hints.push(`${id}.${prop} 写了字体族 ${value}，可写 $${hit}`);
+			}
+		}
+	}
+	return [...new Set(hints)].slice(0, 3);
+}
+/**
+* 写：load → 变更 → 校验（结构错误不落盘）→ 原子保存（保持原风味）。
+* fn 可通过 mark() 登记受影响的节点 id，写成功后统一通知 daemon。
+*/
+async function write(path, fn) {
+	const loaded = loadDoc(path);
+	const touched = [];
+	const mark = (ids) => {
+		touched.push(...ids);
+	};
+	const result = fn(loaded.doc, mark);
+	const presetNames = projectPresetNames(path);
+	const v = validateDoc(loaded.doc, {
+		knownVars: presetNames,
+		presetVars: presetNames,
+		presetGroups: listPresetGroups(path).groups,
+		presetKinds: Object.fromEntries(listPresets(path).items.map((item) => [item.key, item.type])),
+		fontRegistry: projectFontRegistry(path).registry
+	});
+	if (!v.ok) throw new Error(`变更后结构校验失败，未落盘：\n${v.errors.map((e) => `  ${e.path}: ${e.message}`).join("\n")}`);
+	saveDoc(path, loaded.doc, {
+		expectedMtimeMs: loaded.mtimeMs,
+		flavor: loaded.flavor
+	});
+	notifyChanges(path, touched);
+	return {
+		ok: true,
+		result,
+		warnings: v.warnings,
+		hints: collectHints(path, loaded.doc, touched)
+	};
+}
+function countByType(children) {
+	const counts = {};
+	const walk = (nodes) => {
+		for (const n of nodes) {
+			if (!n || typeof n !== "object") continue;
+			const rec = n;
+			const t = typeof rec["type"] === "string" ? rec["type"] : "?";
+			counts[t] = (counts[t] ?? 0) + 1;
+			const kids = rec["children"];
+			if (Array.isArray(kids)) walk(kids);
+		}
+	};
+	walk(children);
+	return counts;
+}
+/**
+* 新建设计稿。path 不带扩展名时补默认扩展名；调用方显式写 `.pen` 时按兼容格式产出
+* （不替用户转换已有文件）。
+*/
+function newDoc(args) {
+	const raw = reqStr(args, "path");
+	const path = /\.(pen|ptr)$/i.test(raw) ? raw : `${raw}.ptr`;
+	const flavor = path.toLowerCase().endsWith(".pen") ? "pen" : "ptr";
+	if (existsSync(path) && optBool(args, "overwrite") !== true) throw new Error(`文件已存在，未覆盖：${path}（确需覆盖传 overwrite=true）`);
+	const width = optNum(args, "width");
+	const height = optNum(args, "height");
+	if (width !== void 0 && width <= 0) throw new Error(`width 必须大于 0，收到：${width}`);
+	if (height !== void 0 && height <= 0) throw new Error(`height 必须大于 0，收到：${height}`);
+	const layoutArg = optStr(args, "layout");
+	if (layoutArg !== void 0 && ![
+		"vertical",
+		"horizontal",
+		"none"
+	].includes(layoutArg)) throw new Error(`layout 仅支持 vertical / horizontal / none，收到：${layoutArg}`);
+	const { doc, boardId } = createDoc({
+		name: optStr(args, "name"),
+		width,
+		height,
+		fill: optStr(args, "fill"),
+		layout: layoutArg === "vertical" || layoutArg === "horizontal" || layoutArg === "none" ? layoutArg : void 0,
+		padding: optNum(args, "padding"),
+		gap: optNum(args, "gap")
+	});
+	const check = validateDoc(doc);
+	if (!check.ok) throw new Error(`新建文档结构校验失败，未落盘：\n${check.errors.map((e) => `  ${e.path}: ${e.message}`).join("\n")}`);
+	mkdirSync(dirname(path), { recursive: true });
+	saveDoc(path, doc, {
+		flavor,
+		createOnly: optBool(args, "overwrite") !== true
+	});
+	const board = doc.children[0];
+	return {
+		ok: true,
+		path,
+		flavor,
+		version: doc.version,
+		boardId,
+		canvas: {
+			width: Number(board?.["width"] ?? 0),
+			height: Number(board?.["height"] ?? 0)
+		},
+		designSystem: designSystemFor(path, doc),
+		warnings: check.warnings
+	};
+}
+/** 摘掉整棵子树的 `reusable`：复制件是实例，不是组件定义 */
+function stripReusableDeep(node) {
+	if (!node || typeof node !== "object") return;
+	const rec = node;
+	delete rec["reusable"];
+	const kids = rec["children"];
+	if (Array.isArray(kids)) for (const k of kids) stripReusableDeep(k);
+}
+/** 按 name 找节点（组件同名提示用）；返回前 5 个 */
+function findNodesByName(nodes, name) {
+	const out = [];
+	const walk = (list) => {
+		for (const raw of list) {
+			if (!raw || typeof raw !== "object") continue;
+			const rec = raw;
+			if (rec["name"] === name && typeof rec["id"] === "string") out.push({
+				id: rec["id"],
+				name
+			});
+			const kids = rec["children"];
+			if (Array.isArray(kids)) walk(kids);
+		}
+	};
+	walk(nodes);
+	return out.slice(0, 5);
+}
+/** 复制进设计稿前给整棵子树换新 id：组件库与目标文件的 id 空间互不相干 */
+function remapIds(node, taken) {
+	if (!node || typeof node !== "object") return;
+	const rec = node;
+	if (typeof rec["id"] === "string") {
+		const fresh = genId(taken);
+		taken.add(fresh);
+		rec["id"] = fresh;
+	}
+	const kids = rec["children"];
+	if (Array.isArray(kids)) for (const k of kids) remapIds(k, taken);
+}
+const TOOLS = {
+	paintress_viewer: {
+		description: "Ensure the local viewer is running and register the current project. Idempotent: reuse the running process (returns its pid/port, never starts a second one). Call it before drawing, editing or showing a design, without waiting to be asked.",
+		inputSchema: {
+			dir: z.string().optional().describe("Directory to register; defaults to the current working directory"),
+			project: z.string().optional().describe("Project name (the URL segment); defaults to parent/dir"),
+			depth: z.number().int().min(1).max(6).optional().describe("Max depth when listing designs; default 3")
+		},
+		run: async (a) => {
+			const dir = optStr(a, "dir");
+			const project = optStr(a, "project");
+			const depth = optNum(a, "depth");
+			const info = await ensureViewer({
+				...dir !== void 0 ? { dir } : {},
+				...project !== void 0 ? { project } : {},
+				...depth !== void 0 ? { depth } : {}
+			});
+			const designSystem = projectFilesInfo(info.root, { ensure: true });
+			return {
+				ok: true,
+				project: info.project,
+				root: info.root,
+				url: info.url,
+				pid: info.pid,
+				port: info.port,
+				started: info.startedDaemon,
+				designSystem
+			};
+		}
+	},
+	paintress_project: {
+		description: "Project design-system files: resolve the registered project root, create __preset.ptr and __components.ptr if missing, and report nested duplicates that would split the design system. Use this instead of creating these files yourself.",
+		inputSchema: {
+			path: z.string().optional().describe("Design file or project directory; defaults to the current working directory"),
+			ensure: z.boolean().optional().describe("Create the two files when missing (default true)")
+		},
+		run: async (a) => {
+			const from = resolve(optStr(a, "path") ?? process.cwd());
+			let project = null;
+			let root = null;
+			if (isDaemonRunning()) try {
+				const res = await sendRequest({ kind: "status" }, 2e3);
+				if (res.ok && "projects" in res && Array.isArray(res.projects)) {
+					setProjectRoots(res.projects.map((p) => p.root));
+					const abs = resolve(from);
+					const hit = res.projects.filter((p) => abs === p.root || abs.startsWith(`${p.root}${sep}`)).sort((x, y) => y.root.length - x.root.length)[0];
+					if (hit !== void 0) {
+						root = hit.root;
+						project = hit.name;
+					}
+				}
+			} catch {}
+			if (root === null) root = findProjectRoot(from) ?? findProjectRootStrict(from);
+			const info = projectFilesInfo(root, { ensure: optBool(a, "ensure") !== false });
+			return {
+				ok: true,
+				project,
+				...info
+			};
+		}
+	},
+	paintress_new: {
+		description: "Create a design file: a minimal document with one empty board, ready to render/screenshot and fill with insert. Refuses to overwrite unless overwrite=true. A path without an extension gets the default one.",
+		inputSchema: {
+			path: z.string().describe("New document path; a missing extension gets the default one"),
+			name: z.string().optional().describe("Board name (default Board)"),
+			width: z.number().positive().optional().describe("Board width (default 900)"),
+			height: z.number().positive().optional().describe("Board height (default 600)"),
+			fill: z.string().optional().describe("Board background (default #FFFFFF)"),
+			layout: z.enum([
+				"vertical",
+				"horizontal",
+				"none"
+			]).optional().describe("Child layout (default vertical)"),
+			padding: z.number().optional().describe("Board padding (default 0)"),
+			gap: z.number().optional().describe("Main-axis gap (default 0)"),
+			overwrite: z.boolean().optional().describe("Overwrite when the file exists (default false)")
+		},
+		run: (a) => newDoc(a)
+	},
+	paintress_doc_info: {
+		description: "Document summary: version, flavor, node counts, variables, top-level nodes, and a design-system overview including font gaps.",
+		inputSchema: { path: z.string().describe("Design file path") },
+		run: (a) => {
+			const path = reqStr(a, "path");
+			return read(path, (ctx) => ({
+				flavor: ctx.flavor,
+				version: ctx.doc.version,
+				fileToken: ctx.doc.fileToken,
+				variables: ctx.doc.variables ? Object.keys(ctx.doc.variables) : [],
+				projectPresets: (() => {
+					const { path: presetPath, items } = listPresets(path);
+					return {
+						path: presetPath,
+						count: items.length
+					};
+				})(),
+				topLevel: ctx.doc.children.map((c) => ({
+					id: c["id"],
+					name: c["name"],
+					type: c["type"]
+				})),
+				nodeCount: Object.values(countByType(ctx.doc.children)).reduce((s, n) => s + n, 0),
+				byType: countByType(ctx.doc.children),
+				designSystem: designSystemFor(path, ctx.doc),
+				warnings: ctx.validation.warnings
+			}));
+		}
+	},
+	paintress_query: {
+		description: "Find nodes by type / name (exact or regex) / id / reusable.",
+		inputSchema: {
+			path: z.string(),
+			type: z.string().optional(),
+			name: z.string().optional(),
+			nameRegex: z.boolean().optional().describe("Interpret name as a regex"),
+			id: z.string().optional(),
+			reusable: z.boolean().optional()
+		},
+		run: (a) => read(reqStr(a, "path"), (ctx) => query(ctx.doc, {
+			type: optStr(a, "type"),
+			name: optStr(a, "name"),
+			nameRegex: optBool(a, "nameRegex"),
+			id: optStr(a, "id"),
+			reusable: optBool(a, "reusable")
+		}))
+	},
+	paintress_get: {
+		description: "Read one node subtree; depth controls how far down (0 = this node only, children elided as ...).",
+		inputSchema: {
+			path: z.string(),
+			id: z.string(),
+			depth: z.number().int().min(0).optional()
+		},
+		run: (a) => read(reqStr(a, "path"), (ctx) => {
+			const filePath = reqStr(a, "path");
+			const res = get(ctx.doc, reqStr(a, "id"), optNum(a, "depth") ?? Infinity);
+			if (!res) throw new Error(`节点不存在：${reqStr(a, "id")}`);
+			if (res !== null && typeof res === "object" && !Array.isArray(res)) {
+				const rec = res;
+				if (rec["type"] === "text" && (typeof rec["fontFamily"] !== "string" || rec["fontFamily"].trim() === "")) {
+					const fonts = listPresets(filePath).items.filter((item) => item.type === "font").map((item) => item.key);
+					const suggest = fonts.length > 0 ? fonts.map((key) => `$${key}`).join(" / ") : "先 paintress_preset set 一个 font token";
+					return {
+						...rec,
+						hint: `这个 text 节点没有 fontFamily，正在用默认字体；补一个 ${suggest} 或 family`
+					};
+				}
+			}
+			return res;
+		})
+	},
+	paintress_update: {
+		description: "Shallow-merge attributes on one node (id and type are immutable).",
+		inputSchema: {
+			path: z.string(),
+			id: z.string(),
+			patch: z.record(z.unknown())
+		},
+		run: (a) => write(reqStr(a, "path"), (doc, mark) => {
+			const id = reqStr(a, "id");
+			const res = update(doc, id, objArg(a, "patch"));
+			mark([id]);
+			return res;
+		})
+	},
+	paintress_insert: {
+		description: "Insert a child node (an id is generated when missing; returns the new id).",
+		inputSchema: {
+			path: z.string(),
+			parent: z.string().describe("父节点 id，或 'root'"),
+			node: z.record(z.unknown()),
+			index: z.number().int().min(0).optional()
+		},
+		run: (a) => write(reqStr(a, "path"), (doc, mark) => {
+			const newId = insert(doc, reqStr(a, "parent"), objArg(a, "node"), optNum(a, "index"));
+			mark([newId]);
+			return newId;
+		})
+	},
+	paintress_delete: {
+		description: "Delete a node and its subtree.",
+		inputSchema: {
+			path: z.string(),
+			id: z.string()
+		},
+		run: (a) => write(reqStr(a, "path"), (doc, mark) => {
+			const id = reqStr(a, "id");
+			const node = remove(doc, id);
+			mark([id]);
+			return { deleted: {
+				id: node["id"],
+				name: node["name"],
+				type: node["type"]
+			} };
+		})
+	},
+	paintress_move: {
+		description: "Reparent or reorder a node (cycle-checked).",
+		inputSchema: {
+			path: z.string(),
+			id: z.string(),
+			parent: z.string(),
+			index: z.number().int().min(0).optional()
+		},
+		run: (a) => write(reqStr(a, "path"), (doc, mark) => {
+			const id = reqStr(a, "id");
+			move(doc, id, reqStr(a, "parent"), optNum(a, "index"));
+			mark([id]);
+			return {
+				moved: id,
+				to: reqStr(a, "parent")
+			};
+		})
+	},
+	paintress_batch: {
+		description: "Atomic batch: an array of update/insert/delete/move ops; one failure discards the whole batch.",
+		inputSchema: {
+			path: z.string(),
+			ops: z.array(z.record(z.unknown()))
+		},
+		run: (a) => write(reqStr(a, "path"), (doc, mark) => {
+			const raw = a["ops"];
+			if (!Array.isArray(raw)) throw new Error("ops 必须是数组");
+			const ops = raw.map((op, idx) => {
+				const rec = op;
+				const kind = rec["op"];
+				if (kind === "update") return {
+					op: "update",
+					id: String(rec["id"]),
+					patch: rec["patch"] ?? {}
+				};
+				if (kind === "insert") return {
+					op: "insert",
+					parent: String(rec["parent"]),
+					node: rec["node"],
+					index: typeof rec["index"] === "number" ? rec["index"] : void 0
+				};
+				if (kind === "delete") return {
+					op: "delete",
+					id: String(rec["id"])
+				};
+				if (kind === "move") return {
+					op: "move",
+					id: String(rec["id"]),
+					parent: String(rec["parent"]),
+					index: typeof rec["index"] === "number" ? rec["index"] : void 0
+				};
+				throw new Error(`ops[${idx}] 的 op 必须是 update|insert|delete|move`);
+			});
+			const before = new Set(collectIds(doc.children));
+			doc.children = batch(doc, ops).children;
+			const insertedIds = collectIds(doc.children).filter((id) => !before.has(id));
+			mark([...ops.flatMap((op) => op.op === "insert" ? [] : [op.id]), ...insertedIds]);
+			return {
+				applied: ops.length,
+				inserted: insertedIds.length
+			};
+		})
+	},
+	paintress_validate: {
+		description: "Validate a document: structural errors plus semantic warnings (duplicate ids, dangling refs, unknown types, undefined variables, wrong token kinds, font gaps). Project presets count as defined.",
+		inputSchema: { path: z.string() },
+		run: (a) => {
+			const path = reqStr(a, "path");
+			const loaded = loadDoc(path);
+			const presetNames = projectPresetNames(path);
+			return validateDoc(loaded.doc, {
+				knownVars: presetNames,
+				presetVars: presetNames,
+				presetGroups: listPresetGroups(path).groups,
+				presetKinds: Object.fromEntries(listPresets(path).items.map((item) => [item.key, item.type])),
+				fontRegistry: projectFontRegistry(path).registry
+			});
+		}
+	},
+	paintress_preset: {
+		description: "Project presets (album tokens and preset groups): colors, radii, spacing, font sizes and families that get tweaked repeatedly live in __preset.ptr; designs reference them as $key. action=list shows everything (including groups), set creates or updates a token, remove deletes it, seed fills a complete scale in one go (dry-run by default, only missing keys). set-group defines a type-targeted set of properties (values must be $token, e.g. {fill:\"$color-brand\"}); nodes opt in with preset:\"<group>\".",
+		inputSchema: {
+			action: z.enum([
+				"list",
+				"set",
+				"remove",
+				"seed",
+				"set-group",
+				"remove-group"
+			]),
+			apply: z.boolean().optional().describe("seed only: true writes; default false returns created/skipped only"),
+			path: z.string().optional().describe("Design file or project directory; defaults to the current working directory"),
+			key: z.string().optional().describe("Token key, referenced as $key; required for set/remove"),
+			type: z.enum([
+				"color",
+				"radius",
+				"spacing",
+				"fontSize",
+				"font"
+			]).optional().describe("Token type; required for set"),
+			name: z.string().optional().describe("Human-readable name; defaults to the key"),
+			value: z.string().optional().describe("值：颜色 #RRGGBB（或 #RGB / #RRGGBBAA），倒角/间距写非负数字，字体写字体族；set 必填"),
+			group: z.string().optional().describe("Preset group name; required for set-group/remove-group"),
+			target: z.string().optional().describe("Node type the group applies to (frame/text/rectangle...); required for set-group"),
+			props: z.record(z.string()).optional().describe("Group properties mapped to $tokens, e.g. {\"fill\":\"$color-brand\"}; required for set-group")
+		},
+		run: (a) => {
+			const from = resolve(optStr(a, "path") ?? process.cwd());
+			const action = optStr(a, "action") ?? "list";
+			if (action === "seed") return {
+				ok: true,
+				...seedDesignSystem(from, { apply: a["apply"] === true })
+			};
+			if (action === "list") {
+				const { path, items } = listPresets(from);
+				return {
+					ok: true,
+					path,
+					items,
+					groups: listPresetGroups(from).groups
+				};
+			}
+			if (action === "set-group") {
+				const props = a["props"];
+				if (props === null || typeof props !== "object" || Array.isArray(props)) throw new Error("props 必须是对象：属性 → $token 引用");
+				const clean = {};
+				for (const [k, v] of Object.entries(props)) {
+					if (typeof v !== "string") throw new Error(`props.${k} 必须是 $token 字符串`);
+					clean[k] = v;
+				}
+				return {
+					ok: true,
+					...setPresetGroup(from, {
+						name: reqStr(a, "group"),
+						target: reqStr(a, "target"),
+						props: clean
+					})
+				};
+			}
+			if (action === "remove-group") return {
+				ok: true,
+				...removePresetGroup(from, reqStr(a, "group"))
+			};
+			const key = reqStr(a, "key");
+			if (action === "remove") {
+				const items = removePreset(from, key);
+				return {
+					ok: true,
+					path: presetPathFor(from),
+					items,
+					groups: listPresetGroups(from).groups
+				};
+			}
+			const type = optStr(a, "type");
+			if (!isPresetType(type)) throw new Error("type 必须是 color / radius / spacing / fontSize / font");
+			const name = optStr(a, "name");
+			const items = setPreset(from, {
+				key,
+				type,
+				value: reqStr(a, "value"),
+				...name !== void 0 ? { name } : {}
+			});
+			return {
+				ok: true,
+				path: presetPathFor(from),
+				items,
+				groups: listPresetGroups(from).groups
+			};
+		}
+	},
+	paintress_font: {
+		description: "Project font registry (x-paintress.fonts in __preset.ptr): list shows sources, previews and the default; add registers a family; remove deletes it; default sets the default font. system/bundle require preview; css/file sources are project-relative paths that must exist; web sources are CSS URLs.",
+		inputSchema: {
+			action: z.enum([
+				"list",
+				"add",
+				"remove",
+				"default"
+			]),
+			path: z.string().optional().describe("Design file or project directory; defaults to the current working directory"),
+			family: z.string().optional().describe("Real font family name; required for add/remove"),
+			kind: z.enum([
+				"web",
+				"css",
+				"file",
+				"system",
+				"bundle"
+			]).optional().describe("Source kind; required for add"),
+			source: z.string().optional().describe("web: a CSS URL; css/file: a project-relative path"),
+			preview: z.string().optional().describe("Design-time substitute font; required for system/bundle"),
+			note: z.string().optional(),
+			metrics: z.object({
+				sizeAdjust: z.string().optional(),
+				ascentOverride: z.string().optional(),
+				descentOverride: z.string().optional(),
+				lineGapOverride: z.string().optional()
+			}).optional().describe("Metrics overrides for the substitute (CSS font metrics overrides)"),
+			value: z.string().optional().describe("For default: a font token key or a family")
+		},
+		run: async (a) => {
+			const from = resolve(optStr(a, "path") ?? process.cwd());
+			const action = optStr(a, "action") ?? "list";
+			if (action === "list") {
+				const { path, registry } = projectFontRegistry(from);
+				const reports = await fetchFontReports(from);
+				const missing = new Set(reports.flatMap((r) => r.missing));
+				const families = Object.fromEntries(Object.entries(registry.families).map(([family, entry]) => [family, {
+					...entry,
+					status: missing.has(family) ? "missing" : "loaded",
+					missingIn: reports.filter((r) => r.missing.includes(family)).map((r) => r.path)
+				}]));
+				return {
+					ok: true,
+					path,
+					...registry,
+					families,
+					reports
+				};
+			}
+			if (action === "remove") return {
+				ok: true,
+				...removeFontEntry(from, reqStr(a, "family"))
+			};
+			if (action === "default") return {
+				ok: true,
+				...setDefaultFont(from, reqStr(a, "value"))
+			};
+			const kind = reqStr(a, "kind");
+			const source = optStr(a, "source");
+			const preview = optStr(a, "preview");
+			const note = optStr(a, "note");
+			const metrics = a["metrics"];
+			return {
+				ok: true,
+				...setFontEntry(from, {
+					family: reqStr(a, "family"),
+					source: {
+						kind,
+						...source !== void 0 ? { target: source } : {}
+					},
+					...preview !== void 0 ? { preview } : {},
+					...note !== void 0 ? { note } : {},
+					...metrics !== null && typeof metrics === "object" ? { metrics } : {}
+				})
+			};
+		}
+	},
+	paintress_audit: {
+		description: "Read-only album audit: nodes whose colors/radii/spacing are literals that could be $token; orphan tokens; preset groups never referenced; dangling preset refs; literal values inside preset groups. You and the human decide what to change.",
+		inputSchema: { path: z.string().describe("Design file path (project presets are read from its project)") },
+		run: (a) => {
+			const path = reqStr(a, "path");
+			const loaded = loadDoc(path);
+			const { items } = listPresets(path);
+			const presetPath = presetPathFor(path);
+			const presetDoc = presetPath === null ? null : readPresetFile(presetPath)?.doc ?? null;
+			const input = auditInputFrom(loaded.doc, items.map((p) => ({
+				key: p.key,
+				type: p.type,
+				value: p.value
+			})), presetDoc);
+			return {
+				ok: true,
+				path,
+				...auditDoc(loaded.doc, input)
+			};
+		}
+	},
+	paintress_establish: {
+		description: "Album extraction: find repeated literals (colors/radii/spacing) and suggest $tokens, and suggest preset groups from same-type nodes carrying the same property set. Dry-run by default (apply=false); apply=true writes __preset.ptr and rewrites matched nodes to references (mtime guarded).",
+		inputSchema: {
+			path: z.string().describe("Design file path"),
+			apply: z.boolean().optional().describe("true writes the preset file and rewrites nodes; default false only suggests"),
+			minUses: z.number().int().min(2).optional().describe("Minimum occurrences for a candidate; default 2")
+		},
+		run: (a) => {
+			const path = reqStr(a, "path");
+			const loaded = loadDoc(path);
+			const minUses = typeof a["minUses"] === "number" ? a["minUses"] : void 0;
+			const plan = planEstablish(loaded.doc, { ...minUses !== void 0 ? { minUses } : {} });
+			if (a["apply"] !== true) return {
+				ok: true,
+				applied: false,
+				...plan
+			};
+			return {
+				ok: true,
+				...applyEstablish(path, plan, { expectedMtimeMs: loaded.mtimeMs })
+			};
+		}
+	},
+	paintress_adjust: {
+		description: "Album adjustment: change one value and see the blast radius first. key=change one token; group+prop=change one group property. Dry-run by default (apply=false) returns affected nodes with before->after; apply=true writes __preset.ptr only, so design references follow automatically.",
+		inputSchema: {
+			path: z.string().describe("Design file path (project presets are read from its project)"),
+			key: z.string().optional().describe("Token key to change"),
+			group: z.string().optional().describe("Preset group to change"),
+			prop: z.string().optional().describe("Group property to change (with group)"),
+			value: z.string().describe("New value: #RRGGBB for colors, a number for dimensions, a family for fonts"),
+			apply: z.boolean().optional().describe("true writes the preset file; default false only previews")
+		},
+		run: (a) => {
+			const path = reqStr(a, "path");
+			const value = reqStr(a, "value");
+			const loaded = loadDoc(path);
+			const presetDoc = readPresetDoc(path);
+			const key = optStr(a, "key");
+			const group = optStr(a, "group");
+			const prop = optStr(a, "prop");
+			if (key !== void 0 && (group !== void 0 || prop !== void 0)) throw new Error("key 与 group/prop 是两种调整方式，只能选一种");
+			if (group === void 0 !== (prop === void 0)) throw new Error("改 preset 组必须同时提供 group 与 prop");
+			const plan = planAdjust(loaded.doc, presetDoc, {
+				...key !== void 0 ? { key } : {},
+				...group !== void 0 ? { group } : {},
+				...prop !== void 0 ? { prop } : {},
+				value
+			});
+			if (a["apply"] !== true) return {
+				ok: true,
+				applied: false,
+				...plan
+			};
+			return {
+				ok: true,
+				...applyAdjust(path, presetDoc, plan)
+			};
+		}
+	},
+	paintress_component: {
+		description: "Project component library: look before you build. action=list lists reusable components (reusable nodes in __components.ptr); action=insert copies one into a design (fresh ids, internal refs expanded, standalone render; copy only, no live link); action=add registers a design subtree as a component (fresh ids, nested reusable stripped, optional rename).",
+		inputSchema: {
+			action: z.enum([
+				"list",
+				"insert",
+				"add"
+			]),
+			path: z.string().optional().describe("Design file or project directory; for insert this is the target design"),
+			id: z.string().optional().describe("Component id; required for insert"),
+			parent: z.string().optional().describe("插到哪个父节点，默认 'root'"),
+			index: z.number().int().min(0).optional()
+		},
+		run: (a) => {
+			const action = optStr(a, "action") ?? "list";
+			const from = resolve(optStr(a, "path") ?? process.cwd());
+			if (action === "list") {
+				const compPath = componentsPathFor(from);
+				if (compPath === null) return {
+					ok: true,
+					path: null,
+					items: [],
+					hint: "项目还没有组件库：先 paintress_viewer 注册项目（会自动创建 __components.ptr）"
+				};
+				return {
+					ok: true,
+					path: compPath,
+					items: listComponents(compPath)
+				};
+			}
+			if (action === "add") {
+				const sourcePath = reqStr(a, "path");
+				const sourceId = reqStr(a, "id");
+				const loaded = loadDoc(sourcePath);
+				const node = findNodeIn(expandRefs(applyProjectPresets(loaded.doc, sourcePath).doc, []), sourceId);
+				if (node === null) throw new Error(`节点不存在：${sourceId}（先 paintress_query 拿 id）`);
+				const copy = structuredClone(node);
+				const name = optStr(a, "name") ?? (typeof copy["name"] === "string" && copy["name"] !== "" ? copy["name"] : sourceId);
+				copy["name"] = name;
+				stripReusableDeep(copy);
+				copy["reusable"] = true;
+				const root = findProjectRootStrict(sourcePath);
+				ensureProjectScaffold(root);
+				const compPath = join(root, COMPONENTS_FILE);
+				return write(compPath, (doc, mark) => {
+					remapIds(copy, new Set(collectIds(doc.children)));
+					const newId = insert(doc, optStr(a, "parent") ?? "root", copy, optNum(a, "index"));
+					mark([newId]);
+					return {
+						id: newId,
+						name,
+						componentPath: compPath,
+						source: sourceId
+					};
+				});
+			}
+			const target = reqStr(a, "path");
+			const compId = reqStr(a, "id");
+			const compPath = componentsPathFor(resolve(target));
+			if (compPath === null) throw new Error("找不到项目组件库 __components.ptr（先在项目里注册）");
+			const compLoaded = readComponentsFile(compPath);
+			if (compLoaded === null) throw new Error(`组件库不可读：${compPath}`);
+			const warnings = [];
+			const node = findNodeIn(expandRefs(applyProjectPresets(compLoaded.doc, compPath).doc, warnings), compId);
+			if (node === null) throw new Error(`组件不存在：${compId}（先 paintress_component list 看有哪些）`);
+			const copy = structuredClone(node);
+			stripReusableDeep(copy);
+			const componentName = typeof node["name"] === "string" && node["name"] !== "" ? node["name"] : compId;
+			const existing = findNodesByName(loadDoc(target).doc.children, componentName);
+			return write(target, (doc, mark) => {
+				remapIds(copy, new Set(collectIds(doc.children)));
+				const newId = insert(doc, optStr(a, "parent") ?? "root", copy, optNum(a, "index"));
+				mark([newId]);
+				return {
+					id: newId,
+					from: compId,
+					componentPath: compPath,
+					warnings,
+					...existing.length > 0 ? { existing } : {}
+				};
+			});
+		}
+	},
+	paintress_convert: {
+		description: "Convert a .pen design file to .ptr (the paintress flavor): reads, validates and writes a new .ptr file with a fresh fileToken and x-paintress metadata. Does not modify the source; refuses to overwrite unless overwrite=true. The two flavors are identical today, but .ptr may evolve.",
+		inputSchema: {
+			path: z.string().describe("Source .pen path"),
+			out: z.string().optional().describe("Target .ptr path; defaults to the source with .ptr extension"),
+			overwrite: z.boolean().optional().describe("Overwrite an existing target (default false)")
+		},
+		run: (a) => {
+			const source = reqStr(a, "path");
+			if (!source.toLowerCase().endsWith(".pen")) throw new Error(`source must be a .pen file, got: ${source}`);
+			const target = optStr(a, "out") ?? source.replace(/\.pen$/i, ".ptr");
+			if (resolve(target) === resolve(source)) throw new Error("Target must differ from the source");
+			if (existsSync(target) && optBool(a, "overwrite") !== true) throw new Error(`Target exists, not overwritten: ${target} (pass overwrite=true to replace it)`);
+			const loaded = loadDoc(source);
+			if (!loaded.validation.ok) throw new Error(`Source fails validation, nothing written:\n${loaded.validation.errors.map((e) => `  ${e.path}: ${e.message}`).join("\n")}`);
+			const meta = loaded.doc["x-paintress"];
+			const doc = {
+				...loaded.doc,
+				fileToken: randomUUID(),
+				...meta !== void 0 ? {} : { ["x-paintress"]: { spec: "1" } }
+			};
+			saveDoc(target, doc, {
+				flavor: "ptr",
+				createOnly: optBool(a, "overwrite") !== true
+			});
+			return {
+				ok: true,
+				source,
+				out: target,
+				fileToken: doc.fileToken,
+				version: doc.version,
+				nodeCount: doc.children.length,
+				warnings: loaded.validation.warnings
+			};
+		}
+	},
+	paintress_render: {
+		description: "Render a design to an HTML file (each node carries data-node-id); returns the output path and canvas size. Project fonts are injected from the registry (web/css/file); embedFonts=true inlines file fonts as data URIs.",
+		inputSchema: {
+			path: z.string(),
+			out: z.string().describe("Output .html path"),
+			embedFonts: z.boolean().optional().describe("Inline file-source fonts as data URIs (default false)")
+		},
+		run: (a) => {
+			const out = reqStr(a, "out");
+			const path = reqStr(a, "path");
+			const merged = applyProjectPresets(loadDoc(path).doc, path).doc;
+			const { registry } = projectFontRegistry(path);
+			const root = findProjectRoot(path) ?? dirname(resolve(path));
+			const embed = a["embedFonts"] === true;
+			const plan = planFonts(registry, (source) => {
+				if (source.target === void 0) return null;
+				const abs = resolve(root, source.target);
+				if (embed && source.kind === "file") try {
+					const data = readFileSync(abs);
+					const ext = extname(abs).toLowerCase();
+					return `data:${ext === ".woff2" ? "font/woff2" : ext === ".woff" ? "font/woff" : ext === ".otf" ? "font/otf" : "font/ttf"};base64,${data.toString("base64")}`;
+				} catch {
+					return null;
+				}
+				return pathToFileURL(abs).href;
+			}, merged);
+			const r = renderDocument(merged, { fonts: plan });
+			if (embed && Object.values(registry.families).some((entry) => entry.source.kind === "css")) r.warnings.push("css 来源的字体未内联（分片 CSS 的 url 无法安全重写）；导出件仍需能访问那些文件");
+			writeFileSync(out, r.html, "utf8");
+			return {
+				ok: true,
+				out,
+				canvas: r.canvas,
+				warnings: r.warnings
+			};
+		}
+	},
+	paintress_screenshot: {
+		description: "Render and screenshot to PNG. Scale 0.2-2, default 0.8 (for agent review: legible without being huge); either edge over 8192px is scaled back proportionally. Needs local Chromium/Chrome or PTR_BROWSER. Pass board to capture one board (a top-level frame, i.e. one page) instead of the whole canvas.",
+		inputSchema: {
+			path: z.string(),
+			out: z.string().describe("Output .png path"),
+			scale: z.number().min(.2).max(2).optional().describe("Pixel scale 0.2-2, default 0.8; 1x = board design pixels (the viewer 1:1)"),
+			board: z.string().optional().describe("Capture one board by id or name; an ambiguous name errors and lists candidates")
+		},
+		run: async (a) => {
+			if (!findBrowser()) throw new Error("未找到可用浏览器：安装 Chromium/Chrome，或设置 PTR_BROWSER");
+			const board = typeof a["board"] === "string" ? a["board"] : "";
+			const res = await screenshotPen(reqStr(a, "path"), reqStr(a, "out"), {
+				...typeof a["scale"] === "number" ? { scale: a["scale"] } : {},
+				...board !== "" ? { board } : {}
+			});
+			return {
+				ok: true,
+				out: res.out,
+				canvas: res.canvas,
+				...res.board !== void 0 ? { board: res.board } : {},
+				scale: res.scale,
+				browser: res.browser,
+				...res.fonts !== void 0 ? { fonts: res.fonts } : {},
+				warnings: res.warnings
+			};
+		}
+	},
+	paintress_marks: {
+		description: "Read or clear the node marks for this session: clicking a node in the viewer assigns #1 #2...; returns the #N -> node id mapping so the conversation can refer to it (e.g. \"make #1 blue\").",
+		inputSchema: {
+			project: z.string().optional().describe("Project name; omit to return marks from all projects"),
+			action: z.enum(["list", "clear"]).optional().describe("Default: list")
+		},
+		run: async (a) => {
+			if (!isDaemonRunning()) throw new Error("paintress web 未运行，无法读取标记；先调用 paintress_viewer（或运行 paintress web）");
+			const project = optStr(a, "project") ?? "";
+			if ((optStr(a, "action") ?? "list") === "clear") return await sendRequest({
+				kind: "clear-marks",
+				project
+			});
+			return await sendRequest({
+				kind: "marks",
+				project
+			});
+		}
+	}
+};
+// src/mcp/server.ts
+const SERVER_NAME = "paintress";
+const SERVER_VERSION = VERSION;
+/**
+* 连接时交给客户端模型的使用说明（MCP initialize 的 instructions）。
+* 头号规则是「作画前把查看器拉起来」——人看不到进程状态，agent 不等提醒就该做。
+*
+* 写法纪律（operator 2026-11-14）：**只说「跑 `paintress web`」就结章**。
+* 不开窗、不指 URL、不让人去打开浏览器 —— 窗口是程序的事（openBrowser），
+* 提示词里多一句「你自己去开浏览器」就必然会在 WSL 里开到错的那一个。
+*/
+const INSTRUCTIONS = `paintress is a design tool for AI agents: design files are JSON, edited through tools and rendered by a local viewer.
+
+VIEWER — the human only sees your work in the viewer:
+- Run \`paintress web\` before the first write of a drawing session (creating, editing or showing a design) — do not wait to be asked. It ensures the viewer is running and returns immediately.
+- The window is the command's job, not yours: never launch a browser or start a process for it.
+- It is idempotent: if the viewer is already up it prints the existing pid/port/URL and exits; calling it again is safe and never starts a second process.
+- MCP equivalent: \`paintress_viewer\` returns the same URL. Append \`?file=<relative path>\` to deep-link one document.
+
+WORKFLOW: \`paintress_new\` → \`paintress_query\`/\`paintress_get\` for real node ids (never invent them) → \`paintress_update\`/\`insert\`/\`move\`/\`delete\` or \`paintress_batch\` → \`paintress_validate\` → \`paintress_screenshot\` to check the result with your own eyes.
+\`#1\` in the conversation is a click marker from the viewer: resolve it with \`paintress_marks\`.
+
+DESIGN SYSTEM — one source of truth; do not paste values:
+- Run \`paintress_project\` (or read \`designSystem\` from \`paintress_viewer\`) for the project root and the two files; never create \`__preset.ptr\` / \`__components.ptr\` yourself.
+- Before the first shape call \`paintress_preset list\`; if it is empty use \`paintress_preset seed\` (dry-run, then apply) or set tokens, and reference them as \`$key\`.
+- Before building a button, card or input call \`paintress_component list\`; insert one that fits. Use \`paintress_component add\` once the same shape is needed a second time.
+- \`paintress_font list\` shows the font registry; register families with a source and a preview. Text without a fontFamily uses the default and is reported on every read — close that gap.
+- After a batch run \`paintress_validate\`; it reports design-system drift, wrong token kinds and font gaps.`;
+/** 写操作前补一次查看器：这是「光画不开 web」的兜底网，不靠 agent 自觉 */
+const WRITE_TOOLS = /* @__PURE__ */ new Set([
+	"paintress_new",
+	"paintress_update",
+	"paintress_insert",
+	"paintress_delete",
+	"paintress_move",
+	"paintress_batch"
+]);
+/** 构建 MCP server：把共享工具注册到 stdio 协议上 */
+function createMcpServer(opts = {}) {
+	const server = new McpServer({
+		name: SERVER_NAME,
+		version: SERVER_VERSION
+	}, { instructions: INSTRUCTIONS });
+	for (const [name, def] of Object.entries(TOOLS)) server.registerTool(name, {
+		description: def.description,
+		inputSchema: def.inputSchema
+	}, async (args) => {
+		try {
+			if (opts.ensureViewerBeforeWrite === true && WRITE_TOOLS.has(name)) await ensureViewerQuiet();
+			const payload = await def.run(args);
+			return { content: [{
+				type: "text",
+				text: JSON.stringify(payload, null, 2)
+			}] };
+		} catch (cause) {
+			return {
+				content: [{
+					type: "text",
+					text: cause instanceof Error ? cause.message : String(cause)
+				}],
+				isError: true
+			};
+		}
+	});
+	return server;
+}
+/**
+* 父进程看门狗：stdio MCP server 必须随宿主死亡而退出，否则变成孤儿进程
+* （MCP 生态的已知问题）。两道保险：ppid 变化 + stdin EOF。
+*/
+function installParentWatchdog() {
+	const parentPid = process.ppid;
+	setInterval(() => {
+		if (process.ppid !== parentPid) exitClean(0);
+		try {
+			process.kill(parentPid, 0);
+		} catch {
+			exitClean(0);
+		}
+	}, 5e3).unref();
+	process.stdin.on("end", () => exitClean(0));
+	process.stdin.on("close", () => exitClean(0));
+}
+/**
+* attach 连接引用：由 autoregister 持有（ensureViewer 每次调用都会复用/刷新）。
+* 退出时显式关闭——比等 OS 回收更快让 daemon 看到 we're gone。
+*/
+function exitClean(code = 0) {
+	closeViewerHandles();
+	process.exit(code);
+}
+/** 写之前补一次查看器：best-effort，失败不阻断写入（人看不到图，但文件还是要改） */
+async function ensureViewerQuiet() {
+	try {
+		await ensureViewer();
+	} catch (cause) {
+		process.stderr.write(`paintress: 写操作前自动拉起查看器失败（${cause instanceof Error ? cause.message : String(cause)}）\n`);
+	}
+}
+/** 自动注册自身（best-effort，失败不阻断 MCP） */
+async function registerSelf() {
+	const res = await autoRegister();
+	if (res) process.stderr.write(`paintress: 已注册项目 "${res.project}"（${res.url}）\n`);
+}
+/** CLI `paintress mcp` 入口：stdio transport + 自动注册 */
+async function runStdioServer() {
+	const server = createMcpServer({ ensureViewerBeforeWrite: true });
+	const transport = new StdioServerTransport();
+	await server.connect(transport);
+	installParentWatchdog();
+	registerSelf();
+}
+export { presetPathFor as A, ensureProjectScaffold as C, listPresetGroups as D, listComponents as E, setProjectRoots as F, projectFontRegistry as M, readTextIfExists as N, listPresets as O, setPreset as P, componentsPathFor as S, findProjectRoot as T, LineDecoder as _, ensureDaemon as a, screenshotPen as b, isDaemonRunning as c, lockPath as d, pidPath as f, socketPath as g, sanitizeProjectName as h, open_browser_exports as i, projectFilesInfo as j, notePathFor as k, queryDaemon as l, safeJoin as m, runStdioServer as n, reuseDaemon as o, resolveProjectDir as p, TOOLS as r, attachPersistent as s, createMcpServer as t, sendRequest as u, encodeLine as v, findNodeIn as w, applyProjectPresets as x, findBrowser as y };