paintress 0.5.2 → 0.6.0

package/dist/{server-ssrAxbTR.js → server-DZRNNWac.js}

@@ -1,14 +1,14 @@
-import { A as genId, C as update, E as saveDoc, M as DocumentSchema, N as PEN_DOC_VERSION, O as validateDoc, S as remove, T as loadDoc, b as move, g as batch, k as collectIds, qt as VERSION, t as renderDocument, v as get, x as query, y as insert } from "./render-CCxYNL6A.js";
-import { existsSync, mkdirSync, mkdtempSync, readdirSync, realpathSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { A as genId, C as update, E as saveDoc, M as DocumentSchema, N as PEN_DOC_VERSION, O as validateDoc, S as remove, T as loadDoc, b as move, g as batch, k as collectIds, m as expandRefs, qt as VERSION, t as renderDocument, v as get, x as query, y as insert } from "./render-BSf62388.js";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, realpathSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { homedir, tmpdir } from "node:os";
 import { basename, dirname, 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";
-import { spawn } from "node:child_process";
 // \0rolldown/runtime.js
 var __defProp = Object.defineProperty;
 var __exportAll = (all, flags) => {
@@ -49,6 +49,347 @@ function createDoc(opts = {}) {
 		boardId
 	};
 }
+// 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";
+function isPresetType(v) {
+	return v === "color" || v === "radius";
+}
+/** 拼出设计稿旁边那份笔记的绝对路径（只认 .ptr / .pen，其余扩展名返回 null） */
+function notePathFor(designAbsPath) {
+	if (!/\.(ptr|pen)$/i.test(designAbsPath)) return null;
+	return designAbsPath.replace(/\.(ptr|pen)$/i, ".md");
+}
+function isRecord(v) {
+	return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+/** 目录 → 项目根（最近的含预设/组件文件的祖先目录）；找不到返回 null */
+function findProjectRoot(from) {
+	let dir = resolve(from);
+	try {
+		if (!statSync(dir).isDirectory()) dir = dirname(dir);
+	} catch {
+		dir = dirname(dir);
+	}
+	for (;;) {
+		if (existsSync(join(dir, "__preset.ptr")) || existsSync(join(dir, "__components.ptr"))) return dir;
+		const parent = dirname(dir);
+		if (parent === dir || !parent.startsWith(sep)) return null;
+		dir = parent;
+	}
+}
+/** 传入文件 → 其所在目录；传入目录 → 自身 */
+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;
+}
+function presetKindOf(key, doc) {
+	const meta = doc["x-paintress"];
+	const items = isRecord(meta) && isRecord(meta["presets"]) ? meta["presets"]["items"] : void 0;
+	const declared = isRecord(items) && isRecord(items[key]) ? items[key]["type"] : void 0;
+	if (isPresetType(declared)) return declared;
+	const def = doc.variables?.[key];
+	const t = isRecord(def) ? def["type"] : void 0;
+	if (t === "color") return "color";
+	if (t === "number") return "radius";
+	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(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(meta) && isRecord(meta["presets"]) ? meta["presets"]["items"] : void 0;
+		const declared = isRecord(metaItems) && isRecord(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 ?? []
+	};
+}
+/**
+* 渲染/校验用的副本：预设打底，文档本地同名变量优先。
+* **绝不能拿去保存** —— 否则一次写入就把预设值烤进了设计稿。
+*/
+function withProjectPresets(doc, presetDoc) {
+	const vars = presetDoc?.variables;
+	if (!vars || Object.keys(vars).length === 0) return doc;
+	return {
+		...doc,
+		variables: {
+			...vars,
+			...doc.variables ?? {}
+		}
+	};
+}
+/**
+* 渲染 / 校验用：按设计稿所在项目的预设补全变量，返回**副本**（绝不可拿去保存）。
+* 这是「预设只在项目里存一份」的唯一兑付点：渲染、截图、校验、写前检查都走这里。
+*/
+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();
+	}
+	const n = Number(raw);
+	if (!Number.isFinite(n) || n < 0) throw new Error(`倒角预设只接受非负数，收到：${value}`);
+	return n;
+}
+/** 变量表里的 type：color → color，radius → number */
+function varTypeOf(type) {
+	return type === "color" ? "color" : "number";
+}
+function presetMetaItems(doc) {
+	const meta = doc["x-paintress"];
+	const presets = isRecord(meta) ? meta["presets"] : void 0;
+	const items = isRecord(presets) ? presets["items"] : void 0;
+	return isRecord(items) ? items : {};
+}
+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 = findProjectRoot(from) ?? projectDirOf(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 metaItems = { ...presetMetaItems(doc) };
+	metaItems[key] = {
+		type: input.type,
+		...input.name !== void 0 && input.name !== "" ? { name: input.name } : {}
+	};
+	const next = {
+		...doc,
+		variables,
+		["x-paintress"]: {
+			...doc["x-paintress"],
+			spec: "1",
+			presets: {
+				version: 1,
+				items: metaItems
+			}
+		}
+	};
+	saveDoc(path, next, {
+		flavor: "ptr",
+		...file !== null ? { expectedMtimeMs: file.mtimeMs } : {}
+	});
+	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 metaItems = { ...presetMetaItems(file.doc) };
+	delete metaItems[key];
+	const next = {
+		...file.doc,
+		variables,
+		["x-paintress"]: {
+			...file.doc["x-paintress"],
+			spec: "1",
+			presets: {
+				version: 1,
+				items: metaItems
+			}
+		}
+	};
+	saveDoc(path, next, {
+		flavor: "ptr",
+		expectedMtimeMs: file.mtimeMs
+	});
+	return readPresetFile(path)?.items ?? [];
+}
+/** 全树按 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(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");
+}
 // src/shot/screenshot.ts
 /**
 * 截图层：渲染 → 临时 HTML → headless Chromium → PNG（决策 3：两个消费者分开，AI 要 PNG）。
@@ -104,7 +445,7 @@ async function screenshotPen(penPath, outPng, opts = {}) {
 	const browserPath = findBrowser();
 	if (!browserPath) throw new Error("未找到可用浏览器：安装 Chromium/Chrome，或设置 PTR_BROWSER 指向可执行文件");
 	const loaded = loadDoc(penPath);
-	const rendered = renderDocument(loaded.doc);
+	const rendered = renderDocument(applyProjectPresets(loaded.doc, penPath).doc);
 	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");
@@ -320,6 +661,22 @@ function safeJoin(projectRootReal, requestPath) {
 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());
@@ -399,6 +756,7 @@ async function attachPersistent(project) {
 							closed = true;
 							sock.end();
 						},
+						isClosed: () => closed,
 						onClose: (cb) => closeCbs.push(cb)
 					});
 				} else if (!parsed.ok) {
@@ -422,6 +780,184 @@ async function attachPersistent(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"];
+	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 });
+/**
+* 在宿主机上打开浏览器。
+*
+* 设计前提（operator 2026-11-13）：界面状态由 agent 侧驱动，
+* 人不需要去记「进程起没起、项目绑没绑」—— agent 第一次把项目交给 web 时，
+* 浏览器就该自己弹出来，并且直接落在那个项目上。
+*
+* 关闭方式：`PAINTRESS_NO_OPEN=1`（CI、远程服务器、或在 SSH 里跑 agent 时用）。
+* 无图形环境（Linux 无 DISPLAY / WAYLAND_DISPLAY）自动跳过，不报错。
+*/
+function openBrowser(url) {
+	if (process.env["PAINTRESS_NO_OPEN"] === "1") return false;
+	if (process.env["CI"] === "1" || process.env["CI"] === "true") return false;
+	const platform = process.platform;
+	if (platform === "linux" && !process.env["DISPLAY"] && !process.env["WAYLAND_DISPLAY"]) return false;
+	const [cmd, args] = platform === "darwin" ? ["open", [url]] : platform === "win32" ? ["cmd", [
+		"/c",
+		"start",
+		"",
+		url
+	]] : ["xdg-open", [url]];
+	try {
+		const child = spawn(cmd, 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 立刻看到 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()) return {
+		project,
+		pid: running.pid,
+		port: running.port,
+		url: projectUrl(running.port, project),
+		startedDaemon: false,
+		openedBrowser: false
+	};
+	const { started, pid, port } = await ensureDaemon();
+	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));
+	const openedBrowser = started && openBrowser(projectUrl(port, project));
+	return {
+		project,
+		pid,
+		port,
+		url: projectUrl(port, project),
+		startedDaemon: started,
+		openedBrowser
+	};
+}
+/**
+* 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];
@@ -473,7 +1009,11 @@ async function write(path, fn) {
 		touched.push(...ids);
 	};
 	const result = fn(loaded.doc, mark);
-	const v = validateDoc(loaded.doc);
+	const presetNames = projectPresetNames(path);
+	const v = validateDoc(loaded.doc, {
+		knownVars: presetNames,
+		presetVars: presetNames
+	});
 	if (!v.ok) throw new Error(`变更后结构校验失败，未落盘：\n${v.errors.map((e) => `  ${e.path}: ${e.message}`).join("\n")}`);
 	saveDoc(path, loaded.doc, {
 		expectedMtimeMs: loaded.mtimeMs,
@@ -502,8 +1042,8 @@ function countByType(children) {
 	return counts;
 }
 /**
-* 新建文档。path 不带扩展名时补 `.ptr`：新建一律默认标准格式，
-* `.pen` 只有在调用方显式写扩展名时才产出（兼容旧工具链）。
+* 新建设计稿。path 不带扩展名时补默认扩展名；调用方显式写 `.pen` 时按兼容格式产出
+* （不替用户转换已有文件）。
 */
 function newDoc(args) {
 	const raw = reqStr(args, "path");
@@ -550,11 +1090,51 @@ function newDoc(args) {
 		warnings: check.warnings
 	};
 }
+/** 复制进设计稿前给整棵子树换新 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: "确保本地查看器在运行，并把当前项目注册进去，返回人可以打开的 URL。幂等：已在运行就直接复用（返回现有 pid/端口，绝不起第二个进程），可以在开始画/改/展示设计稿之前无条件调用。**开始作画前先调它，不要等人提醒**",
+		inputSchema: {
+			dir: z.string().optional().describe("要注册的目录，默认当前工作目录"),
+			project: z.string().optional().describe("项目名（URL 里那一段），默认取「父目录/目录名」"),
+			depth: z.number().int().min(1).max(6).optional().describe("列举设计稿的最大深度，默认 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 } : {}
+			});
+			return {
+				ok: true,
+				project: info.project,
+				url: info.url,
+				pid: info.pid,
+				port: info.port,
+				started: info.startedDaemon,
+				openedBrowser: info.openedBrowser,
+				hint: `把人指向 ${info.url}（单份设计稿加深链 ?file=<相对路径>）`
+			};
+		}
+	},
 	paintress_new: {
-		description: "新建文档（.ptr 是 paintress 的标准格式；.pen 仅作兼容）。创建一个带空 board 的最小可用文档，可直接 render/screenshot 再逐层 insert；已存在同名文件时报错，除非 overwrite=true。path 不带扩展名时自动补 .ptr",
+		description: "新建一份设计稿：创建一个带空 board 的最小可用文档，可直接 render/screenshot 再逐层 insert；已存在同名文件时报错，除非 overwrite=true。path 不带扩展名时自动补默认扩展名",
 		inputSchema: {
-			path: z.string().describe("新文档路径；不带扩展名时自动补 .ptr"),
+			path: z.string().describe("新文档路径；不带扩展名时自动补默认扩展名"),
 			name: z.string().optional().describe("board 名称（默认 Board）"),
 			width: z.number().positive().optional().describe("board 宽（默认 900）"),
 			height: z.number().positive().optional().describe("board 高（默认 600）"),
@@ -578,6 +1158,13 @@ const TOOLS = {
 			version: ctx.doc.version,
 			fileToken: ctx.doc.fileToken,
 			variables: ctx.doc.variables ? Object.keys(ctx.doc.variables) : [],
+			projectPresets: (() => {
+				const { path: presetPath, items } = listPresets(reqStr(a, "path"));
+				return {
+					path: presetPath,
+					count: items.length
+				};
+			})(),
 			topLevel: ctx.doc.children.map((c) => ({
 				id: c["id"],
 				name: c["name"],
@@ -728,9 +1315,120 @@ const TOOLS = {
 		})
 	},
 	paintress_validate: {
-		description: "校验文档：结构错误 + 语义警告（重复 id、悬空 ref、未知类型、未定义变量）",
+		description: "校验文档：结构错误 + 语义警告（重复 id、悬空 ref、未知类型、未定义变量）。项目预设里的变量算已定义",
 		inputSchema: { path: z.string() },
-		run: (a) => read(reqStr(a, "path"), (ctx) => ctx.validation)
+		run: (a) => {
+			const path = reqStr(a, "path");
+			const loaded = loadDoc(path);
+			const presetNames = projectPresetNames(path);
+			return validateDoc(loaded.doc, {
+				knownVars: presetNames,
+				presetVars: presetNames
+			});
+		}
+	},
+	paintress_preset: {
+		description: "项目预设：颜色 / 倒角这类会反复微调的值在项目里存一份（__preset.ptr），设计稿里写 $key 引用。作画前先把颜色与倒角定下来注册成预设；人在查看器里改预设值，画布实时变，不用一句句说「红一点」。action=list 查看，set 新建/改值，remove 删除",
+		inputSchema: {
+			action: z.enum([
+				"list",
+				"set",
+				"remove"
+			]),
+			path: z.string().optional().describe("设计稿或项目目录，默认当前工作目录"),
+			key: z.string().optional().describe("变量名，设计稿里写 $key；set / remove 必填"),
+			type: z.enum(["color", "radius"]).optional().describe("预设类型；set 必填"),
+			name: z.string().optional().describe("人看的名称，默认同 key"),
+			value: z.string().optional().describe("值：颜色写 #RRGGBB（或 #RGB / #RRGGBBAA），倒角写非负数字，如 '8'；set 必填")
+		},
+		run: (a) => {
+			const from = resolve(optStr(a, "path") ?? process.cwd());
+			const action = optStr(a, "action") ?? "list";
+			if (action === "list") {
+				const { path, items } = listPresets(from);
+				return {
+					ok: true,
+					path,
+					items
+				};
+			}
+			const key = reqStr(a, "key");
+			if (action === "remove") return {
+				ok: true,
+				path: presetPathFor(from),
+				items: removePreset(from, key)
+			};
+			const type = optStr(a, "type");
+			if (!isPresetType(type)) throw new Error("type 必须是 color 或 radius");
+			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
+			};
+		}
+	},
+	paintress_component: {
+		description: "项目组件库：先查已有组件再动手，避免重复造轮子。action=list 列出可复用组件（__components.ptr 里 reusable 节点）；action=insert 把某个组件复制进设计稿——复制件自带新 id、内部 ref 已展开，可独立渲染（只复制，不做联动编辑）",
+		inputSchema: {
+			action: z.enum(["list", "insert"]),
+			path: z.string().optional().describe("设计稿或项目目录；insert 时是目标设计稿"),
+			id: z.string().optional().describe("组件 id；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: []
+				};
+				return {
+					ok: true,
+					path: compPath,
+					items: listComponents(compPath)
+				};
+			}
+			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);
+			const stripReusable = (n) => {
+				if (!n || typeof n !== "object") return;
+				const rec = n;
+				delete rec["reusable"];
+				const kids = rec["children"];
+				if (Array.isArray(kids)) for (const k of kids) stripReusable(k);
+			};
+			stripReusable(copy);
+			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
+				};
+			});
+		}
 	},
 	paintress_render: {
 		description: "渲染设计稿为 HTML 文件（每节点带 data-node-id）；返回输出路径与画布尺寸",
@@ -740,8 +1438,9 @@ const TOOLS = {
 		},
 		run: (a) => {
 			const out = reqStr(a, "out");
-			const loaded = loadDoc(reqStr(a, "path"));
-			const r = renderDocument(loaded.doc);
+			const path = reqStr(a, "path");
+			const loaded = loadDoc(path);
+			const r = renderDocument(applyProjectPresets(loaded.doc, path).doc);
 			writeFileSync(out, r.html, "utf8");
 			return {
 				ok: true,
@@ -783,7 +1482,7 @@ const TOOLS = {
 			action: z.enum(["list", "clear"]).optional().describe("默认 list")
 		},
 		run: async (a) => {
-			if (!isDaemonRunning()) throw new Error("paintress web 未运行，无法读取标记；先运行 paintress web --daemon");
+			if (!isDaemonRunning()) throw new Error("paintress web 未运行，无法读取标记；先调用 paintress_viewer（或运行 paintress web --daemon）");
 			const project = optStr(a, "project") ?? "";
 			if ((optStr(a, "action") ?? "list") === "clear") return await sendRequest({
 				kind: "clear-marks",
@@ -796,123 +1495,44 @@ const TOOLS = {
 		}
 	}
 };
-// src/web/spawn.ts
-const START_TIMEOUT_MS = 6e3;
-const DEFAULT_PORT = 3316;
-async function ensureDaemon(opts = {}) {
-	if (isDaemonRunning()) {
-		const res = await sendRequest({ kind: "ping" });
-		if (res.ok && "pong" in res) return {
-			started: false,
-			pid: res.pid,
-			port: opts.port ?? DEFAULT_PORT
-		};
-	}
-	const entry = process.argv[1];
-	if (!entry) throw new Error("无法确定 CLI 入口路径，不能后台启动 daemon");
-	const args = [entry, "web"];
-	if (opts.port !== void 0) args.push("--port", String(opts.port));
-	if (opts.idleTimeoutMs !== void 0) args.push("--idle", String(opts.idleTimeoutMs));
-	spawn(process.execPath, args, {
-		detached: true,
-		stdio: "ignore"
-	}).unref();
-	const deadline = Date.now() + START_TIMEOUT_MS;
-	while (Date.now() < deadline) {
-		if (isDaemonRunning()) {
-			const res = await sendRequest({ kind: "ping" });
-			if (res.ok && "pong" in res) return {
-				started: true,
-				pid: res.pid,
-				port: opts.port ?? DEFAULT_PORT
-			};
-		}
-		await new Promise((r) => setTimeout(r, 100));
-	}
-	throw new Error(`后台启动 daemon 超时（${START_TIMEOUT_MS}ms）`);
-}
-// src/web/open-browser.ts
-var open_browser_exports = /* @__PURE__ */ __exportAll({ openBrowser: () => openBrowser });
-/**
-* 在宿主机上打开浏览器。
-*
-* 设计前提（operator 2026-11-13）：界面状态由 agent 侧驱动，
-* 人不需要去记「进程起没起、项目绑没绑」—— agent 第一次把项目交给 web 时，
-* 浏览器就该自己弹出来，并且直接落在那个项目上。
-*
-* 关闭方式：`PAINTRESS_NO_OPEN=1`（CI、远程服务器、或在 SSH 里跑 agent 时用）。
-* 无图形环境（Linux 无 DISPLAY / WAYLAND_DISPLAY）自动跳过，不报错。
-*/
-function openBrowser(url) {
-	if (process.env["PAINTRESS_NO_OPEN"] === "1") return false;
-	if (process.env["CI"] === "1" || process.env["CI"] === "true") return false;
-	const platform = process.platform;
-	if (platform === "linux" && !process.env["DISPLAY"] && !process.env["WAYLAND_DISPLAY"]) return false;
-	const [cmd, args] = platform === "darwin" ? ["open", [url]] : platform === "win32" ? ["cmd", [
-		"/c",
-		"start",
-		"",
-		url
-	]] : ["xdg-open", [url]];
-	try {
-		const child = spawn(cmd, 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
-async function autoRegister(cwd = process.cwd()) {
-	if (process.env["PAINTRESS_NO_AUTO_WEB"] === "1") return null;
-	try {
-		const { started, port } = await ensureDaemon();
-		const project = deriveProjectName(cwd);
-		const watched = await sendRequest({
-			kind: "watch",
-			project,
-			dir: cwd,
-			owner: "agent"
-		}, 8e3);
-		if (!watched.ok) throw new Error(watched.error);
-		return {
-			handle: await attachPersistent(project),
-			project,
-			startedDaemon: started,
-			openedBrowser: started && port !== void 0 ? openBrowser(projectUrl(port, project)) : false
-		};
-	} catch (cause) {
-		process.stderr.write(`paintress: web 自动注册失败（${cause instanceof Error ? cause.message : String(cause)}），MCP 工具不受影响\n`);
-		return null;
-	}
-}
 // src/mcp/server.ts
 const SERVER_NAME = "paintress";
 const SERVER_VERSION = VERSION;
+/**
+* 连接时交给客户端模型的使用说明（MCP initialize 的 instructions）。
+* 头号规则是「作画前把查看器拉起来」——人看不到进程状态，agent 不等提醒就该做。
+*/
+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, so keep it running:
+- Call \`paintress_viewer\` before the first write of a drawing session (creating, editing or showing a design) — do not wait to be asked.
+- It is idempotent: if the viewer is already up it returns the existing pid/port/URL and starts nothing; calling it again is always safe and never starts a second process.
+- CLI equivalent, same idempotence: \`paintress web --daemon\` returns immediately with the URL. Never block on plain \`paintress web\`.
+- Hand the returned URL to the human (append \`?file=<relative path>\` to deep-link one document). Never ask them to start the viewer or run \`watch\`.
+
+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\`.`;
+/** 写操作前补一次查看器：这是「光画不开 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() {
+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",
@@ -948,29 +1568,32 @@ function installParentWatchdog() {
 	process.stdin.on("close", () => exitClean(0));
 }
 /**
-* attach 连接引用：必须持有，否则 GC 关闭后 daemon 会误判 agent 已退出。
+* attach 连接引用：由 autoregister 持有（ensureViewer 每次调用都会复用/刷新）。
 * 退出时显式关闭——比等 OS 回收更快让 daemon 看到 we're gone。
 */
-let registrar = null;
-/** 干净退出：断开 attach 连接后退出 */
 function exitClean(code = 0) {
-	try {
-		registrar?.handle.close();
-	} catch {}
+	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();
-	registrar = res;
-	if (res) process.stderr.write(`paintress: 已注册项目 "${res.project}"，浏览器打开 http://localhost:3316/${encodeURIComponent(res.project)}\n`);
+	if (res) process.stderr.write(`paintress: 已注册项目 "${res.project}"，浏览器打开 ${res.url}\n`);
 }
 /** CLI `paintress mcp` 入口：stdio transport + 自动注册 */
 async function runStdioServer() {
-	const server = createMcpServer();
+	const server = createMcpServer({ ensureViewerBeforeWrite: true });
 	const transport = new StdioServerTransport();
 	await server.connect(transport);
 	installParentWatchdog();
 	registerSelf();
 }
-export { attachPersistent as a, lockPath as c, safeJoin as d, sanitizeProjectName as f, encodeLine as h, TOOLS as i, pidPath as l, LineDecoder as m, runStdioServer as n, isDaemonRunning as o, socketPath as p, open_browser_exports as r, sendRequest as s, createMcpServer as t, resolveProjectDir as u };
+export { isPresetType as C, presetPathFor as D, notePathFor as E, readTextIfExists as O, findNodeIn as S, listPresets as T, LineDecoder as _, ensureDaemon as a, componentsPathFor as b, isDaemonRunning as c, lockPath as d, pidPath as f, socketPath as g, sanitizeProjectName as h, open_browser_exports as i, setPreset 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, listComponents as w, ensureProjectScaffold as x, applyProjectPresets as y };