paintress 0.7.0 → 0.7.1

package/README.md

@@ -81,7 +81,8 @@ paintress component list|insert|add ...                  project component libra
 paintress render <file> <out.html>                      write the canvas as HTML
 paintress shot <file> <out.png> [--scale 0.2..2] [--board id|name]  render to PNG (default 0.8)
 
-paintress web [--port n] [--idle ms] [--foreground]   ensure the viewer is running (idempotent, returns at once)
+paintress web [--port n] [--bind auto|loopback|all] [--idle ms] [--foreground]
+                                                        ensure the viewer is running (idempotent, returns at once)
 paintress ping | status | stop                          viewer control
 paintress watch <name> <dir> [--depth n] | unwatch <name>  register a directory to browse
 paintress attach <name>                                 keep the viewer alive while an agent works
@@ -96,12 +97,14 @@ paintress mcp-config <client>                           print the config snippet
 ```bash
 paintress web
 paintress watch demo ./demo
-# open http://localhost:3316/demo
+# open http://localhost:6033/demo
 ```
 
 `paintress web` is idempotent and returns immediately: if a viewer is already running it prints that process's `pid` / `port` / `http`, otherwise it starts one and opens the viewer window on it. Either way the command is safe to run before every drawing session — there is never a second instance, and the window is opened by the program, in the desktop browser (`--foreground` keeps the process attached to your shell when you want its log; `paintress stop` is how you replace a running viewer, e.g. on another port). Under WSL the window lands in the Windows browser, never in a browser inside the distro.
 
-Agents get the same guarantee from the MCP side: `paintress_viewer` ensures the viewer and registers the current project, and the MCP server re-checks it before every write, so the viewer is up before the first edit instead of after someone asks.
+The port is not a constant you should memorize: it is **chosen at startup and reported back**. The default is `6033`; if that port is unusable the viewer walks `6033 → 6133 → 6233` on `127.0.0.1`, and if none of them can be reached from the host it re-binds the same three ports on `0.0.0.0` (six candidates, first usable one wins, otherwise it fails with the full attempt table). Under WSL this matters: Windows can reserve a port for Hyper-V, in which case `localhost` forwarding is never created and the human's browser sees "connection refused" while everything inside the distro works — the fallback then hands you `http://<wsl-ip>:6033/` instead. The `http` / `access.url` field is authoritative: print it, do not rebuild it. `--port` pins one port and never jumps (a busy port is an error), `--bind loopback|all` pins the interface.
+
+Agents get the same guarantee from the MCP side: `paintress_viewer` ensures the viewer and registers the current project, and the MCP server re-checks it before every write, so the viewer is up before the first edit instead of after someone asks. Its result carries the same `url` / `access` block, so an agent that started the viewer on a fallback port tells the human the address that actually works.
 
 A design file that has a sibling Markdown file of the same name (`home.ptr` → `home.md`) gets a notes button in the top-left corner of the canvas. Click it and the canvas narrows to make room for the note: what the design is for, what is still open, which requirement it answers. The note is a plain Markdown file next to the design — write it yourself or let the agent write it; the panel is read-only.
 
@@ -109,7 +112,7 @@ The rail in the top-right corner holds the project's design system. **Presets**
 
 Canvas navigation: wheel zooms at the pointer, space / middle button / empty area drags to pan, `Ctrl/Cmd+0` returns to 100%, `Shift+1` fits the window, and `Ctrl/Cmd+K` quickly switches design files. Selecting a node opens a read-only inspector. Files with more than one board get a board strip; the active board can be exported as PNG at 0.5x / 1x / 2x (1x means its design pixels; the file is `<design>-<board>@<scale>x.png` and is scaled back when either edge exceeds 8192px). Edits made through the CLI or MCP are highlighted in the viewer, and clicks assign short ids that the agent can read back with `paintress_marks`; each mark carries the file and node id, so a shorthand resolves to one element in one file.
 
-Projects are named after their directory path (`c-thun/raybend`), so the URL reads like the path: `http://localhost:3316/c-thun/raybend?file=design/editor.pen`. Project rows have an **×** on hover that unbinds the project (design files are untouched; an agent re-registers on its next start), and **Stop server** in the sidebar footer shuts the viewer process down — both ask for confirmation first.
+Projects are named after their directory path (`c-thun/raybend`), so the URL reads like the path: `http://localhost:6033/c-thun/raybend?file=design/editor.pen`. Project rows have an **×** on hover that unbinds the project (design files are untouched; an agent re-registers on its next start), and **Stop server** in the sidebar footer shuts the viewer process down — both ask for confirmation first.
 
 The viewer follows the agent instead of asking you to manage it. When an agent starts the viewer it opens your browser on that agent's own project — nothing for the agent to run twice, nothing for you to open by hand; projects appear and leave with a short animation as agents come and go. When the last project is gone **or the server is stopped** (the sidebar's Stop server, an idle exit), the page counts down ten seconds and closes its own window — you never have to close the tab by hand. A browser that nobody is looking at no longer keeps the process alive.
 
@@ -137,6 +140,7 @@ One source of truth per project, so a change lands everywhere instead of on one
 | `PAINTRESS_NO_OPEN` | `1` never opens a browser window |
 | `PAINTRESS_NO_AUTO_WEB` | `1` stops the MCP server from ensuring the viewer before writes |
 | `PAINTRESS_NO_WEB_FONTS` | `1` skips the built-in web fonts (offline / CI) |
+| `PAINTRESS_PORT` | Port the `ui/` vite dev server proxies to (default `6033`); set it to the viewer's actual port when the port ladder jumped |
 | `CI` | `true` behaves like `PAINTRESS_NO_OPEN` |
 
 ## MCP clients

package/README.zh-CN.md

@@ -81,7 +81,8 @@ paintress component list|insert|add ...                 项目组件库
 paintress render <file> <out.html>                     渲染为 HTML
 paintress shot <file> <out.png> [--scale 0.2..2] [--board id|name]  渲染为 PNG（默认 0.8）
 
-paintress web [--port n] [--idle ms] [--foreground]  确保查看器在跑（幂等，立刻返回）
+paintress web [--port n] [--bind auto|loopback|all] [--idle ms] [--foreground]
+                                                       确保查看器在跑（幂等，立刻返回）
 paintress ping | status | stop                         查看器控制
 paintress watch <name> <dir> [--depth n] | unwatch <name>  注册/移除要浏览的目录
 paintress attach <name>                                agent 工作期间保持查看器存活
@@ -96,12 +97,14 @@ paintress mcp-config <client>                          打印单个客户端的
 ```bash
 paintress web
 paintress watch demo ./demo
-# 打开 http://localhost:3316/demo
+# 打开 http://localhost:6033/demo
 ```
 
 `paintress web` 是幂等的、且立刻返回：已经在跑就打印那个进程的 `pid` / `port` / `http`，没跑就拉起一个并把查看器窗口开在它上面。所以每次开始作画前无条件跑一遍都没问题——永远不会出现第二个实例；窗口由程序自己开在桌面浏览器里（`--foreground` 让进程占住终端、日志直接可见；要换端口/重启，用 `paintress stop`）。在 WSL 里窗口落在 Windows 的浏览器，不会是发行版里的那个浏览器。
 
-agent 从 MCP 侧拿到同样的保证：`paintress_viewer` 确保查看器在跑并把当前项目注册进去，MCP server 还会在每次写操作前再确认一遍——于是查看器是在第一次编辑之前就起来的，而不是等人开口。
+端口不是一个要背下来的常量：它在启动时**选好并报回来**。默认 `6033`；用不了就沿 `6033 → 6133 → 6233` 在 `127.0.0.1` 上跳级，三个都到不了宿主就改绑 `0.0.0.0` 再走一遍同样三个端口（共六个候选，第一个可用的胜出，全灭就带着完整尝试表报错）。WSL 里这条很重要：Windows 可能把端口划给 Hyper-V，此时 `localhost` 转发根本不会建立——发行版里一切正常，人在宿主浏览器里只看到「连接失败」；兜底会把 `http://<wsl-ip>:6033/` 交给你。`http` / `access.url` 字段是权威值：直接用它，不要自己拼。`--port` 钉死一个端口、绝不跳级（被占就是报错），`--bind loopback|all` 钉死绑定面。
+
+agent 从 MCP 侧拿到同样的保证：`paintress_viewer` 确保查看器在跑并把当前项目注册进去，MCP server 还会在每次操作前再确认一遍——于是查看器是在第一次编辑之前就起来的，而不是等人开口。它的返回值里带着同一份 `url` / `access`，所以就算查看器落在了兜底端口上，agent 也会把人引到真正能打开的地址。
 
 设计稿旁边放一份同名 Markdown（`home.ptr` → `home.md`），画布左上角就会出现「笔记」按钮。点开后画布向右收窄、左侧切出笔记：这份设计是干什么的、还有哪些待定、对应哪条需求。笔记就是设计稿旁边的一份普通 Markdown——您自己写，或者让 agent 写；面板本身只读。
 
@@ -133,6 +136,7 @@ agent 从 MCP 侧拿到同样的保证：`paintress_viewer` 确保查看器在
 | `PAINTRESS_NO_OPEN` | `1` 时不打开浏览器窗口 |
 | `PAINTRESS_NO_AUTO_WEB` | `1` 时 MCP 写操作前不再确保查看器在跑 |
 | `PAINTRESS_NO_WEB_FONTS` | `1` 时跳过内置网络字体（离线 / CI） |
+| `PAINTRESS_PORT` | `ui/` 开发服务器的代理目标端口（默认 `6033`）；端口阶梯跳级时设成查看器实际端口 |
 | `CI` | `true` 等价于 `PAINTRESS_NO_OPEN` |
 
 ## MCP 客户端

package/dist/cli.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { A as presetPathFor, C as ensureProjectScaffold, D as listPresetGroups, E as listComponents, F as setProjectRoots, M as projectFontRegistry, N as readTextIfExists, O as listPresets, P as setPreset, S as componentsPathFor, T as findProjectRoot, _ as LineDecoder, a as ensureDaemon, b as screenshotPen, c as isDaemonRunning, d as lockPath, f as pidPath, g as socketPath, h as sanitizeProjectName, j as projectFilesInfo, k as notePathFor, l as queryDaemon, m as safeJoin, n as runStdioServer, o as reuseDaemon, p as resolveProjectDir, r as TOOLS, s as attachPersistent, u as sendRequest, v as encodeLine, w as findNodeIn, x as applyProjectPresets, y as findBrowser } from "./server-DBRmwE_v.js";
+import { A as listComponents, C as findBrowser, D as ensureProjectScaffold, E as componentsPathFor, F as projectFilesInfo, I as projectFontRegistry, L as readTextIfExists, M as listPresets, N as notePathFor, O as findNodeIn, P as presetPathFor, R as setPreset, S as encodeLine, T as applyProjectPresets, _ as resolveProjectDir, a as defaultRouteIpv4, b as socketPath, c as windowsSystem32, d as attachPersistent, f as isDaemonRunning, g as pidPath, h as lockPath, j as listPresetGroups, k as findProjectRoot, l as ensureDaemon, m as sendRequest, n as runStdioServer, o as interopEnabled, p as queryDaemon, r as TOOLS, s as isWsl, u as reuseDaemon, v as safeJoin, w as screenshotPen, x as LineDecoder, y as sanitizeProjectName, z as setProjectRoots } from "./server-Buuoq3kq.js";
 import { P as planFonts, T as loadDoc, rn as VERSION, t as renderDocument, z as isPresetType } from "./render-DWs1iQ0v.js";
 import "./index.js";
 import { chmodSync, closeSync, copyFileSync, existsSync, mkdirSync, openSync, readFileSync, readdirSync, realpathSync, renameSync, statSync, unlinkSync, writeFileSync } from "node:fs";
@@ -8,6 +8,7 @@ import { fileURLToPath } from "node:url";
 import { dirname, extname, join, relative, resolve, sep } from "node:path";
 import { randomUUID } from "node:crypto";
 import { createServer } from "node:net";
+import { spawn } from "node:child_process";
 import { createServer as createServer$1 } from "node:http";
 import { readFile } from "node:fs/promises";
 import chokidar from "chokidar";
@@ -415,8 +416,368 @@ var VersionChecker = class {
 		};
 	}
 };
+// src/web/bind.ts
+/**
+* 监听地址的选取策略（端口阶梯）。
+*
+* 为什么需要它（2026-11-15 实测）：WSL2 的 `localhost` 转发由宿主侧 `wslrelay.exe`
+* 落地 —— Windows 上绑不上这个端口，转发就不存在，宿主浏览器只会看到「连接失败」。
+* 最常见的一类不可绑是 **Hyper-V 保留端口段**（`netsh int ipv4 show excludedportrange`），
+* 而保留段每次开机在动态端口范围内重新划分，位置会漂：同一个默认端口今天能开、明天不能开。
+* 这一类故障在 WSL 内部完全看不出来（daemon 自己 `curl 127.0.0.1` 永远是 200）。
+*
+* 因此顺序是「宿主预检、真正 listen、最后复核」：
+*   1. 宿主体检（一次 interop 调用）：哪些候选端口在 Windows 上绑得上；
+*   2. 真正 listen：WSL 内冲突在这里暴露，失败才换下一个候选；
+*   3. 端到端复核：从 Windows 侧取 `/api/ping`，校验 nonce —— 只信身份，不信 200。
+*
+* 阶梯：127.0.0.1 × [6033, 6133, 6233] → 0.0.0.0 × [6033, 6133, 6233]，最多 6 次。
+* 兜底的 0.0.0.0 之所以有效：Windows 直连 WSL 网卡地址不经过 wslrelay，端口被宿主保留也不影响
+* （实测保留端口上 localhost 连不通、WSL IP 返回 200）。
+*/
+/** 默认端口：60 号肉身成圣远征队 + 33 号远征队 */
+const DEFAULT_PORT = 6033;
+/** 跳级候选（顺序即优先级） */
+const PORT_CANDIDATES = [
+	DEFAULT_PORT,
+	6133,
+	6233
+];
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/** 单个候选的探测预算：loopback 要走 wslrelay 接管（实测 300ms–1.06s），all 是直连 */
+const PROBE_BUDGET_MS = {
+	loopback: 2e3,
+	all: 600
+};
+const PROBE_INTERVAL_MS = 150;
+/** 单次 Windows 进程调用的硬超时；端到端探测会按剩余预算收紧它 */
+const INTEROP_TIMEOUT_MS = 4e3;
+function inRange(ranges, port) {
+	return ranges.some(([start, end]) => port >= start && port <= end);
+}
+const hostOf = (mode) => mode === "loopback" ? "127.0.0.1" : "0.0.0.0";
+function candidatesFor(opts) {
+	const pref = opts.bind ?? "auto";
+	if (opts.requestedPort !== void 0) {
+		const mode = pref === "all" ? "all" : "loopback";
+		return [{
+			port: opts.requestedPort,
+			host: hostOf(mode),
+			bind: mode
+		}];
+	}
+	return (pref === "auto" ? ["loopback", "all"] : [pref]).flatMap((mode) => (opts.ports ?? PORT_CANDIDATES).map((port) => ({
+		port,
+		host: hostOf(mode),
+		bind: mode
+	})));
+}
+/** 运行一条 Windows 命令，收集 stdout（超时/不存在都返回 null） */
+async function runWindows(exe, args, timeoutMs = INTEROP_TIMEOUT_MS) {
+	return new Promise((resolve) => {
+		let out = "";
+		const child = spawn(exe, args, { stdio: [
+			"ignore",
+			"pipe",
+			"ignore"
+		] });
+		const timer = setTimeout(() => {
+			child.kill("SIGKILL");
+			resolve(null);
+		}, timeoutMs);
+		child.stdout?.on("data", (chunk) => {
+			out += chunk.toString("utf8");
+		});
+		child.once("error", () => {
+			clearTimeout(timer);
+			resolve(null);
+		});
+		child.once("close", () => {
+			clearTimeout(timer);
+			resolve(out);
+		});
+	});
+}
+function system32() {
+	if (!interopEnabled()) return null;
+	return windowsSystem32();
+}
+/**
+* 宿主体检：一次 PowerShell 调用同时拿回「保留段」与「候选端口可否独占绑定」。
+* 为什么不分开调：每次 interop 都是新进程（热 70–260ms，冷启动可达 2s），启动路径上能省则省。
+*/
+async function windowsReport(ports) {
+	const sys32 = system32();
+	if (sys32 === null) return null;
+	const ps = `${sys32}/WindowsPowerShell/v1.0/powershell.exe`;
+	if (!existsSync(ps)) return null;
+	const raw = await runWindows(ps, [
+		"-NoProfile",
+		"-NonInteractive",
+		"-Command",
+		[
+			"$ex = @()",
+			"$null = netsh.exe int ipv4 show excludedportrange protocol=tcp | ForEach-Object { if ($_ -match '^\\s*(\\d+)\\s+(\\d+)\\s*$') { $ex += ,@([int]$Matches[1],[int]$Matches[2]) } }",
+			"$b = @{}",
+			`foreach ($p in @(${ports.join(",")})) {`,
+			"  $s = New-Object System.Net.Sockets.Socket([System.Net.Sockets.AddressFamily]::InterNetwork,[System.Net.Sockets.SocketType]::Stream,[System.Net.Sockets.ProtocolType]::Tcp)",
+			"  try { $s.ExclusiveAddressUse = $true",
+			"        $s.Bind((New-Object System.Net.IPEndPoint([System.Net.IPAddress]::Loopback,$p)))",
+			"        $b[\"$p\"] = $true } catch { $b[\"$p\"] = $false } finally { $s.Close() }",
+			"}",
+			"@{ excluded = $ex; bindable = $b } | ConvertTo-Json -Compress -Depth 4"
+		].join("; ")
+	]);
+	if (raw === null) return null;
+	try {
+		const parsed = JSON.parse(raw.trim());
+		const excluded = Array.isArray(parsed.excluded) ? parsed.excluded.filter((r) => Array.isArray(r) && r.length === 2).map((r) => [Number(r[0]), Number(r[1])]) : [];
+		const bindable = {};
+		if (parsed.bindable !== null && typeof parsed.bindable === "object") for (const [k, v] of Object.entries(parsed.bindable)) bindable[k] = v === true;
+		return {
+			excluded: excluded.filter(([s, e]) => Number.isFinite(s) && Number.isFinite(e)),
+			bindable
+		};
+	} catch {
+		return null;
+	}
+}
+/**
+* 端到端探测：从 Windows 侧取 `/api/ping`，正文里必须出现本次 nonce。
+* 只认身份不认状态码 —— 端口上蹲着别的程序（甚至另一个 distro 的 paintress）时，200 也是假的。
+*/
+async function windowsProbe(url, budgetMs) {
+	const sys32 = system32();
+	if (sys32 === null) return false;
+	let nonce = "";
+	try {
+		nonce = new URL(url).searchParams.get("nonce") ?? "";
+	} catch {
+		return false;
+	}
+	if (nonce === "") return false;
+	const deadline = Date.now() + budgetMs;
+	const curl = `${sys32}/curl.exe`;
+	if (existsSync(curl)) {
+		while (Date.now() < deadline) {
+			const remaining = deadline - Date.now();
+			const out = await runWindows(curl, [
+				"-s",
+				"--noproxy",
+				"*",
+				"-m",
+				"2",
+				url
+			], Math.max(1, remaining));
+			if (out !== null && out.includes(nonce)) return true;
+			await sleep(PROBE_INTERVAL_MS);
+		}
+		return false;
+	}
+	const ps = `${sys32}/WindowsPowerShell/v1.0/powershell.exe`;
+	if (!existsSync(ps)) return false;
+	const script = `try { (Invoke-WebRequest -UseBasicParsing -TimeoutSec 2 -Uri '${url}').Content } catch { '' }`;
+	while (Date.now() < deadline) {
+		const remaining = deadline - Date.now();
+		const out = await runWindows(ps, [
+			"-NoProfile",
+			"-NonInteractive",
+			"-Command",
+			script
+		], Math.max(1, remaining));
+		if (out !== null && out.includes(nonce)) return true;
+		await sleep(PROBE_INTERVAL_MS);
+	}
+	return false;
+}
+function listenOn(server, endpoint) {
+	return new Promise((resolve, reject) => {
+		const onError = (err) => {
+			server.off("listening", onListening);
+			reject(err);
+		};
+		const onListening = () => {
+			server.off("error", onError);
+			resolve();
+		};
+		server.once("error", onError);
+		server.once("listening", onListening);
+		server.listen(endpoint.port, endpoint.host);
+	});
+}
+function closeQuietly(server) {
+	try {
+		server.closeAllConnections?.();
+		server.close();
+	} catch {}
+}
+function ladderError(attempts, explicit) {
+	const reason = {
+		ok: "ok",
+		"in-use": "端口已被占用",
+		"windows-reserved": "落在 Windows 保留端口段",
+		"windows-unreachable": "Windows 侧连不上（转发未建立）"
+	};
+	const rows = attempts.map((a) => `  ${a.bind === "all" ? "0.0.0.0" : "127.0.0.1"}:${a.port}  ${reason[a.result]}${a.detail ? `（${a.detail}）` : ""}`);
+	const hint = explicit ? "显式 --port 不跳级：换一个端口（--port <n>），或在 WSL 里用 --bind all 绑 0.0.0.0 让宿主直连。" : "可用 --port <n> 指定端口、--bind all 直接绑 0.0.0.0，或把 Windows 动态端口段恢复默认（见 README「端口与宿主访问」）。";
+	return /* @__PURE__ */ new Error(`paintress web 没有可用端口，${attempts.length} 个候选全部失败：\n${rows.join("\n")}\n${hint}`);
+}
+/** 宿主预检：能提前判死的就别去 listen（保留段 / 宿主占用）。返回 null = 继续尝试 */
+function predictSkip(cand, report, wsl, log) {
+	if (!wsl || cand.bind !== "loopback" || report === null) return null;
+	if (inRange(report.excluded, cand.port)) {
+		log(`${cand.port} 落在 Windows 保留端口段，跳过`);
+		return {
+			port: cand.port,
+			bind: cand.bind,
+			result: "windows-reserved"
+		};
+	}
+	if (report.bindable[String(cand.port)] === false) {
+		log(`${cand.port} 在 Windows 侧绑不上（已被占用或已被转发），跳过`);
+		return {
+			port: cand.port,
+			bind: cand.bind,
+			result: "in-use",
+			detail: "Windows 侧不可绑（已被占用或已转发）"
+		};
+	}
+	return null;
+}
+/**
+* 端到端复核：从宿主侧取 `/api/ping`，只认本次进程的 nonce。
+* 返回 'unreachable' 表示「本机起得来、宿主连不上」—— 正是 WSL 转发没落地的那种失败。
+*/
+async function verifyCandidate(cand, ctx) {
+	if (!ctx.wsl) return "skipped";
+	if (!ctx.canProbe) return "unavailable";
+	let target = null;
+	if (cand.bind === "loopback") target = `127.0.0.1:${cand.port}`;
+	else if (ctx.ipv4 !== null) target = `${ctx.ipv4}:${cand.port}`;
+	if (target === null) return "unreachable";
+	return await ctx.probe(`http://${target}/api/ping?nonce=${ctx.nonce}`, PROBE_BUDGET_MS[cand.bind]) ? "ok" : "unreachable";
+}
+/**
+* 走完阶梯并返回**已经 listen 成功且复核通过**的 server。
+* 调用方只需要接管返回值，不必关心中间换过几个候选。
+*/
+async function bindWithFallback(opts) {
+	const seams = opts.seams ?? {};
+	const log = opts.log ?? (() => {});
+	const explicit = opts.requestedPort !== void 0;
+	const ephemeral = opts.requestedPort === 0;
+	const wsl = !ephemeral && (seams.isWsl ?? isWsl)();
+	const requestedPort = opts.requestedPort ?? opts.ports?.[0] ?? 6033;
+	const plan = candidatesFor(opts);
+	const attempts = [];
+	const ipv4 = (seams.hostIpv4 ?? defaultRouteIpv4)();
+	const probe = seams.probe ?? windowsProbe;
+	const canProbe = wsl && (seams.probe !== void 0 || interopEnabled() && windowsSystem32() !== null);
+	let report = null;
+	if (canProbe && plan.some((c) => c.bind === "loopback")) {
+		report = await (seams.report ?? windowsReport)(plan.filter((c) => c.bind === "loopback").map((c) => c.port));
+		if (report === null) log("Windows 侧体检失败，跳过宿主预检（仍做端到端复核）");
+	} else if (wsl && !canProbe) log("Windows interop 不可用：跳过宿主预检与复核");
+	const probeCtx = {
+		wsl,
+		canProbe,
+		ipv4,
+		nonce: opts.nonce,
+		probe
+	};
+	for (const cand of plan) {
+		if (wsl && cand.bind === "all" && ipv4 === null) {
+			attempts.push({
+				port: cand.port,
+				bind: cand.bind,
+				result: "windows-unreachable",
+				detail: "找不到默认路由网卡的 IPv4 地址"
+			});
+			log(`${cand.port} (all) 没有可供宿主访问的网卡地址，换下一个`);
+			continue;
+		}
+		const skip = predictSkip(cand, report, wsl, log);
+		if (skip !== null) {
+			attempts.push(skip);
+			continue;
+		}
+		const server = opts.create();
+		try {
+			await listenOn(server, cand);
+		} catch (cause) {
+			const code = cause.code;
+			if (code === "EADDRINUSE" || code === "EACCES") {
+				attempts.push({
+					port: cand.port,
+					bind: cand.bind,
+					result: "in-use",
+					detail: String(code)
+				});
+				log(`${cand.port} (${cand.bind}) 本机不可用（${code}），换下一个`);
+				continue;
+			}
+			throw cause;
+		}
+		const verdict = await verifyCandidate(cand, probeCtx);
+		if (verdict === "unreachable") {
+			closeQuietly(server);
+			attempts.push({
+				port: cand.port,
+				bind: cand.bind,
+				result: "windows-unreachable"
+			});
+			log(`${cand.port} (${cand.bind}) 已监听但 Windows 侧连不上，换下一个`);
+			continue;
+		}
+		attempts.push({
+			port: cand.port,
+			bind: cand.bind,
+			result: "ok"
+		});
+		const resolved = server.address();
+		const actualPort = typeof resolved === "object" && resolved !== null ? resolved.port : cand.port;
+		const host = cand.bind === "loopback" ? "localhost" : ipv4 ?? cand.host;
+		const access = {
+			url: `http://${host}:${actualPort}/`,
+			host,
+			bind: cand.bind,
+			windows: verdict,
+			jumped: !ephemeral && actualPort !== requestedPort,
+			requestedPort: ephemeral ? actualPort : requestedPort,
+			attempts
+		};
+		if (access.jumped) log(`端口 ${requestedPort} 不可用，已改用 ${actualPort}`);
+		if (cand.bind === "all") log(`已绑定 0.0.0.0:${actualPort} —— 宿主浏览器用 ${access.url}（localhost 走不通）`);
+		return {
+			server,
+			endpoint: {
+				...cand,
+				port: actualPort
+			},
+			access
+		};
+	}
+	throw ladderError(attempts, explicit);
+}
+async function diagnoseNetwork(seams = {}) {
+	const wsl = (seams.isWsl ?? isWsl)();
+	const ports = [...PORT_CANDIDATES];
+	const report = wsl ? await (seams.report ?? windowsReport)(ports) : null;
+	return {
+		wsl,
+		interop: interopEnabled(),
+		system32: windowsSystem32(),
+		hostIpv4: (seams.hostIpv4 ?? defaultRouteIpv4)(),
+		defaultPort: DEFAULT_PORT,
+		candidates: ports.map((port) => ({
+			port,
+			excluded: report === null ? false : inRange(report.excluded, port),
+			windowsBindable: report === null ? null : report.bindable[String(port)] === true
+		})),
+		report
+	};
+}
 // src/web/daemon.ts
-const DEFAULT_PORT = 3316;
 const MIME = {
 	".html": "text/html; charset=utf-8",
 	".js": "text/javascript; charset=utf-8",
@@ -595,6 +956,12 @@ async function startDaemon(opts = {}) {
 	const watchers = new WatchManager();
 	const versions = new VersionChecker();
 	const startedAt = Date.now();
+	/** 身份串：宿主侧探测必须回显它，避免「端口上蹲着别的程序」被当成成功 */
+	const instanceNonce = randomUUID();
+	/** 绑定结果；ping 只能发生在 listen 之后（socket 服务更晚），先用占位值初始化 */
+	let port = 0;
+	let accessInfo = null;
+	let endpoint = null;
 	const idleTimeoutMs = opts.idleTimeoutMs ?? 6e4;
 	const emptyGraceMs = opts.emptyGraceMs ?? Math.min(idleTimeoutMs, 3e3);
 	const emptyBrowserMs = opts.emptyBrowserMs ?? 3e4;
@@ -731,7 +1098,8 @@ async function startDaemon(opts = {}) {
 								pid: process.pid,
 								port,
 								uptimeMs: Date.now() - startedAt,
-								projects: registry.all().length
+								projects: registry.all().length,
+								...accessInfo !== null ? { access: accessInfo } : {}
 							});
 							break;
 						case "status":
@@ -865,7 +1233,7 @@ async function startDaemon(opts = {}) {
 	};
 	const sockServer = createServer(handleClient);
 	const uiDist = findUiDist();
-	const httpServer = createServer$1(async (req, res) => {
+	const handleHttp = async (req, res) => {
 		lastHttpAt = Date.now();
 		const url = new URL(req.url ?? "/", "http://localhost");
 		const segments = url.pathname.split("/").filter((s) => s !== "");
@@ -891,6 +1259,17 @@ async function startDaemon(opts = {}) {
 		};
 		try {
 			if (segments[0] === "api") {
+				if (segments[1] === "ping" && segments.length === 2) {
+					sendJson(200, {
+						ok: true,
+						pong: true,
+						pid: process.pid,
+						nonce: instanceNonce,
+						port,
+						bind: endpoint === null ? "loopback" : endpoint.bind
+					});
+					return;
+				}
 				if (segments[1] === "projects" && segments.length === 2) {
 					sendJson(200, {
 						ok: true,
@@ -1608,7 +1987,8 @@ async function startDaemon(opts = {}) {
 					const info = registry.info(p);
 					return `<div class="card"><h2 style="margin:0 0 4px"><a href="${`/${p.name.split("/").map(encodeURIComponent).join("/")}`}">${esc(p.label)}</a></h2><div class="meta">${esc(info.root)} · ${info.fileCount} 个设计稿 · agent ${info.agentConns} · 浏览器 ${info.browserConns}</div></div>`;
 				}).join("");
-				send(200, layout("项目", `<h1>paintress</h1><div class="meta">pid ${process.pid} · 端口 ${opts.port ?? DEFAULT_PORT} · 运行 ${Math.round((Date.now() - startedAt) / 1e3)}s</div><p class="meta">前端未构建（<code>ui/dist</code> 不存在），当前为精简视图。</p>` + (items || "<p class=\"empty\">还没有注册任何项目。用 <code>paintress watch &lt;name&gt; &lt;dir&gt;</code> 注册。</p>")));
+				const boundHost = endpoint === null ? "127.0.0.1" : endpoint.host;
+				send(200, layout("项目", `<h1>paintress</h1><div class="meta">pid ${process.pid} · 端口 ${port} · 绑定 ${boundHost} · 运行 ${Math.round((Date.now() - startedAt) / 1e3)}s</div><p class="meta">前端未构建（<code>ui/dist</code> 不存在），当前为精简视图。</p>` + (items || "<p class=\"empty\">还没有注册任何项目。用 <code>paintress watch &lt;name&gt; &lt;dir&gt;</code> 注册。</p>")));
 				return;
 			}
 			const hit = resolveProjectPrefix(registry, segments);
@@ -1628,27 +2008,40 @@ async function startDaemon(opts = {}) {
 		} catch (cause) {
 			send(500, layout("错误", `<h1>500</h1><pre>${esc(cause instanceof Error ? cause.message : String(cause))}</pre>`));
 		}
-	});
-	const desiredPort = opts.port ?? DEFAULT_PORT;
-	const port = await new Promise((resolve, reject) => {
-		httpServer.once("error", (err) => {
-			reject(err.code === "EADDRINUSE" ? /* @__PURE__ */ new Error(`端口 ${desiredPort} 已被占用；可用 --port 指定其他端口`) : err);
-		});
-		httpServer.listen(desiredPort, "127.0.0.1", () => {
-			const addr = httpServer.address();
-			resolve(typeof addr === "object" && addr !== null ? addr.port : desiredPort);
+	};
+	let bound;
+	try {
+		bound = await bindWithFallback({
+			create: () => createServer$1(handleHttp),
+			nonce: instanceNonce,
+			...opts.port !== void 0 ? { requestedPort: opts.port } : {},
+			...opts.bind !== void 0 ? { bind: opts.bind } : {},
+			...opts.quiet === true ? {} : { log: (line) => process.stderr.write(`paintress web: ${line}\n`) }
 		});
-	});
+	} catch (cause) {
+		releaseLock();
+		throw cause;
+	}
+	const httpServer = bound.server;
+	port = bound.endpoint.port;
+	endpoint = bound.endpoint;
+	accessInfo = bound.access;
 	const sock = socketPath();
 	try {
 		if (existsSync(sock)) unlinkSync(sock);
 	} catch {}
-	await new Promise((resolve, reject) => {
-		sockServer.once("error", reject);
-		sockServer.listen(sock, () => {
-			resolve();
+	try {
+		await new Promise((resolve, reject) => {
+			sockServer.once("error", reject);
+			sockServer.listen(sock, () => {
+				resolve();
+			});
 		});
-	});
+	} catch (cause) {
+		httpServer.close();
+		releaseLock();
+		throw cause;
+	}
 	/**
 	* 生命周期策略：控制权在 agent 侧，人不需要管进程在不在。
 	*
@@ -1724,7 +2117,16 @@ async function startDaemon(opts = {}) {
 		port,
 		pid: process.pid,
 		close: () => shutdown("close"),
-		registry
+		registry,
+		access: accessInfo ?? {
+			url: `http://localhost:${port}/`,
+			host: "localhost",
+			bind: "loopback",
+			windows: "skipped",
+			jumped: false,
+			requestedPort: opts.port ?? 6033,
+			attempts: []
+		}
 	};
 }
 // src/integrations/clients.ts
@@ -2026,6 +2428,7 @@ const FLAG_KEYS = /* @__PURE__ */ new Set([
 	"index",
 	"scale",
 	"port",
+	"bind",
 	"idle",
 	"foreground",
 	"daemon",
@@ -2099,6 +2502,29 @@ function currentLaunchCommand() {
 		realpath: (p) => realpathSync(p)
 	});
 }
+/** CLI 输出的 `http` 字段保持历史形态（不带结尾斜杠）；`access.url` 仍带斜杠作为基地址 */
+function httpOf(access) {
+	return access.url.replace(/\/$/, "");
+}
+/** `paintress doctor` 的「当前 daemon 实况」：没跑就是 null，不拉起进程 */
+async function daemonSnapshot() {
+	const info = await queryDaemon(500);
+	if (info === null) return null;
+	return {
+		pid: info.pid,
+		port: info.port,
+		url: info.access.url,
+		bind: info.access.bind,
+		windows: info.access.windows,
+		jumped: info.access.jumped
+	};
+}
+/** `--bind` 只接受三种取值：auto（默认，走端口阶梯）、loopback、all */
+function parseBind(v) {
+	if (v === void 0) return void 0;
+	if (v === "auto" || v === "loopback" || v === "all") return v;
+	throw new Error(`--bind 只接受 auto|loopback|all，收到：${v}`);
+}
 function flagStr(f, key) {
 	const v = f[key];
 	return typeof v === "string" && v !== "" ? v : void 0;
@@ -2282,7 +2708,13 @@ async function main(argv) {
 					dryRun
 				});
 			}
-			console.log(JSON.stringify({
+			console.log(JSON.stringify(cmd === "doctor" ? {
+				ok: true,
+				launch,
+				results,
+				net: await diagnoseNetwork(),
+				daemon: await daemonSnapshot()
+			} : {
 				ok: true,
 				launch,
 				results
@@ -2312,9 +2744,9 @@ async function main(argv) {
 		if (cmd === "web") {
 			const port = flagNum(flags, "port");
 			const idle = flagNum(flags, "idle");
+			const bind = parseBind(flagStr(flags, "bind"));
 			const noOpen = flags[NO_OPEN_FLAG] === true || process.env["PAINTRESS_NO_OPEN"] === "1";
-			const url = (p) => `http://localhost:${p}`;
-			const running = await reuseDaemon(port);
+			const running = await reuseDaemon(port, bind);
 			if (running !== null) {
 				console.log(JSON.stringify({
 					ok: true,
@@ -2322,7 +2754,8 @@ async function main(argv) {
 					reused: true,
 					pid: running.pid,
 					port: running.port,
-					http: url(running.port),
+					http: httpOf(running.access),
+					access: running.access,
 					designSystem: cwdDesignSystem()
 				}, null, 2));
 				return 0;
@@ -2330,6 +2763,7 @@ async function main(argv) {
 			if (flags["foreground"] !== true) {
 				const res = await ensureDaemon({
 					...port !== void 0 ? { port } : {},
+					...bind !== void 0 ? { bind } : {},
 					...idle !== void 0 ? { idleTimeoutMs: idle } : {},
 					noOpen
 				});
@@ -2339,7 +2773,8 @@ async function main(argv) {
 					reused: !res.started,
 					pid: res.pid,
 					port: res.port,
-					http: url(res.port),
+					http: httpOf(res.access),
+					access: res.access,
 					designSystem: cwdDesignSystem()
 				}, null, 2));
 				return 0;
@@ -2348,6 +2783,7 @@ async function main(argv) {
 			try {
 				handle = await startDaemon({
 					...port !== void 0 ? { port } : {},
+					...bind !== void 0 ? { bind } : {},
 					...idle !== void 0 ? { idleTimeoutMs: idle } : {},
 					emptyGraceMs: 6e4,
 					updateCheck: true
@@ -2361,20 +2797,21 @@ async function main(argv) {
 					reused: true,
 					pid: again.pid,
 					port: again.port,
-					http: url(again.port)
+					http: httpOf(again.access),
+					access: again.access
 				}, null, 2));
 				return 0;
 			}
-			const http = url(handle.port);
 			console.log(JSON.stringify({
 				ok: true,
 				pid: handle.pid,
 				port: handle.port,
-				http
+				http: httpOf(handle.access),
+				access: handle.access
 			}, null, 2));
 			if (!noOpen) {
-				const { openBrowser } = await import("./server-DBRmwE_v.js").then((n) => n.i);
-				openBrowser(`${http}/`);
+				const { openBrowser } = await import("./server-Buuoq3kq.js").then((n) => n.i);
+				openBrowser(handle.access.url);
 			}
 			await new Promise((resolve) => {
 				process.once("SIGINT", () => void handle.close().then(() => resolve()));

package/dist/mcp/server.js

@@ -1 +1 @@
-export { t as createMcpServer, n as runStdioServer } from "../server-DBRmwE_v.js";
+export { t as createMcpServer, n as runStdioServer } from "../server-Buuoq3kq.js";

package/dist/{server-DBRmwE_v.js → server-Buuoq3kq.js}

@@ -1,6 +1,6 @@
 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 { homedir, networkInterfaces, tmpdir } from "node:os";
 import { pathToFileURL } from "node:url";
 import { basename, dirname, extname, join, relative, resolve, sep } from "node:path";
 import { z } from "zod";
@@ -1961,6 +1961,18 @@ function safeJoin(projectRootReal, requestPath) {
 function isDaemonRunning() {
 	return existsSync(socketPath());
 }
+/** 旧版 daemon（未上报 access）的兼容值：当作本机 loopback 可用 */
+function legacyAccess(port) {
+	return {
+		url: `http://localhost:${port}/`,
+		host: "localhost",
+		bind: "loopback",
+		windows: "skipped",
+		jumped: false,
+		requestedPort: port,
+		attempts: []
+	};
+}
 /**
 * 查询运行中的 daemon：未运行、socket 残留、daemon 无响应都返回 null。
 * 调用方拿到 null 就可以安全地走「启动」分支 —— 幂等的判据只有这一处。
@@ -1972,7 +1984,8 @@ async function queryDaemon(timeoutMs = 2e3) {
 		if (res.ok && "pong" in res) return {
 			pid: res.pid,
 			port: res.port,
-			uptimeMs: res.uptimeMs
+			uptimeMs: res.uptimeMs,
+			access: res.access ?? legacyAccess(res.port)
 		};
 	} catch {}
 	return null;
@@ -2090,16 +2103,17 @@ function daemonPid() {
 	}
 }
 // src/web/spawn.ts
-const START_TIMEOUT_MS = 6e3;
+const START_TIMEOUT_MS = 15e3;
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
 /**
-* 复用已在运行的 daemon；显式指定了端口且与运行中的不一致时抛错
-* （幂等不等于「悄悄忽略你的参数」：要换端口得先 `paintress stop`）。
+* 复用已在运行的 daemon；显式指定的端口/绑定与运行中的不一致时抛错
+* （幂等不等于「悄悄忽略你的参数」：要换端口或绑定得先 `paintress stop`）。
 */
-async function reuseDaemon(port) {
+async function reuseDaemon(port, bind) {
 	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`);
+	if (bind !== void 0 && bind !== "auto" && bind !== info.access.bind) throw new Error(`paintress web 已在运行（pid ${info.pid}，绑定 ${info.access.bind}），与请求的绑定 ${bind} 不同；如需换绑定请先 paintress stop`);
 	return info;
 }
 /** 启动超时的诊断信息：区分「进程没起来」与「进程在但控制面不通」 */
@@ -2112,11 +2126,12 @@ function timeoutHint() {
 	return "；可能是锁或端口残留，先 paintress ping 看状态，或前台跑 paintress web 看报错";
 }
 async function ensureDaemon(opts = {}) {
-	const running = await reuseDaemon(opts.port);
+	const running = await reuseDaemon(opts.port, opts.bind);
 	if (running !== null) return {
 		started: false,
 		pid: running.pid,
-		port: running.port
+		port: running.port,
+		access: running.access
 	};
 	const entry = process.argv[1];
 	if (!entry) throw new Error("无法确定 CLI 入口路径，不能后台启动 daemon");
@@ -2126,14 +2141,30 @@ async function ensureDaemon(opts = {}) {
 		"--foreground"
 	];
 	if (opts.port !== void 0) args.push("--port", String(opts.port));
+	if (opts.bind !== void 0) args.push("--bind", opts.bind);
 	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"
+		stdio: [
+			"ignore",
+			"ignore",
+			"pipe"
+		]
 	});
 	child.unref();
+	let startupStderr = "";
+	let ready = false;
+	child.stderr?.on("data", (chunk) => {
+		if (ready) return;
+		startupStderr = `${startupStderr}${chunk.toString("utf8")}`.slice(-32768);
+	});
+	child.stderr?.unref?.();
 	let exitCode = null;
+	child.once("error", (cause) => {
+		startupStderr = `${startupStderr}\n${cause.message}`;
+		exitCode = -1;
+	});
 	child.once("exit", (code) => {
 		exitCode = code;
 	});
@@ -2142,25 +2173,30 @@ async function ensureDaemon(opts = {}) {
 		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 再重试`);
+			if (opts.bind !== void 0 && opts.bind !== "auto" && info.access.bind !== opts.bind) throw new Error(`daemon 起在绑定 ${info.access.bind} 而不是请求的 ${opts.bind}；先 paintress stop 再重试`);
+			ready = true;
 			return {
-				started: true,
+				started: info.pid === child.pid,
 				pid: info.pid,
-				port: info.port
+				port: info.port,
+				access: info.access
 			};
 		}
-		if (exitCode !== null) throw new Error(`后台 daemon 启动失败（退出码 ${exitCode}）${timeoutHint()}`);
+		if (exitCode !== null) {
+			const detail = startupStderr.trim();
+			if (/已在运行|单实例锁/.test(detail)) {
+				await sleep(100);
+				continue;
+			}
+			const suffix = detail === "" ? timeoutHint() : `：\n${detail}`;
+			throw new Error(`后台 daemon 启动失败（退出码 ${exitCode}）${suffix}`);
+		}
 		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;
+	const detail = startupStderr.trim();
+	throw new Error(`后台启动 daemon 超时（${START_TIMEOUT_MS}ms）${detail === "" ? timeoutHint() : `：\n${detail}`}`);
 }
+// src/shared/wsl.ts
 function readOsrelease() {
 	try {
 		return readFileSync("/proc/sys/kernel/osrelease", "utf8");
@@ -2179,6 +2215,69 @@ function isWsl(ctx = {}) {
 	const rel = ctx.osrelease !== void 0 ? ctx.osrelease : readOsrelease();
 	return rel !== null && /microsoft/i.test(rel);
 }
+/**
+* Windows 侧系统目录（`/mnt/c/Windows/System32`）。找不到返回 null：
+* 这是「能不能调 Windows 程序」的前提，null 时所有宿主探测都跳过。
+*/
+function windowsSystem32() {
+	const drive = process.env["SystemDrive"]?.replace(/\0/g, "").toLowerCase();
+	const candidates = [];
+	if (drive !== void 0 && /^[a-z]:$/.test(drive)) candidates.push(`/mnt/${drive[0]}/Windows/System32`);
+	candidates.push("/mnt/c/Windows/System32");
+	for (const letter of "cdefg") candidates.push(`/mnt/${letter}/Windows/System32`);
+	for (const c of candidates) try {
+		if (existsSync(c)) return c;
+	} catch {}
+	return null;
+}
+/** binfmt 注册项在不在：在 = interop 可执行（比试运行一条命令便宜得多） */
+function interopEnabled() {
+	return existsSync("/proc/sys/fs/binfmt_misc/WSLInterop") || existsSync("/proc/sys/fs/binfmt_misc/WSLInterop-late");
+}
+/**
+* 默认路由所在网卡的 IPv4（WSL 里就是 eth0）。
+* 绑 0.0.0.0 时，Windows 要访问的就是这个地址 —— 不能随便取一张网卡，
+* 否则会拿到 docker0 之类的内网地址，给出去的 URL 直接不可用。
+*/
+function defaultRouteIpv4() {
+	const iface = defaultRouteInterface();
+	const ifaces = networkInterfaces();
+	const pick = (name) => {
+		if (name === null) return null;
+		for (const addr of ifaces[name] ?? []) if (addr.family === "IPv4" && !addr.internal) return addr.address;
+		return null;
+	};
+	const fromRoute = pick(iface);
+	if (fromRoute !== null) return fromRoute;
+	for (const name of Object.keys(ifaces)) {
+		const hit = pick(name);
+		if (hit !== null) return hit;
+	}
+	return null;
+}
+/** /proc/net/route：Destination 为 0 且带 RTF_GATEWAY 的那一行就是默认路由 */
+function defaultRouteInterface() {
+	try {
+		const lines = readFileSync("/proc/net/route", "utf8").split("\n").slice(1);
+		for (const line of lines) {
+			const cols = line.trim().split(/\s+/);
+			if (cols.length < 4) continue;
+			const [, dest, , flags] = cols;
+			if (dest !== "00000000") continue;
+			if ((Number.parseInt(flags ?? "", 16) & 2) === 0) continue;
+			return cols[0] ?? null;
+		}
+	} catch {}
+	return null;
+}
+// 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;
+}
 /** Windows 侧打开 URL 的候选命令，按可靠度排序 */
 function windowsLaunchers(url) {
 	const ps = `Start-Process '${url.replace(/'/g, "''")}'`;
@@ -2257,14 +2356,19 @@ function openBrowser(url, ctx = {}) {
 		return false;
 	}
 }
-/** 顶层页面地址（项目列表）；项目深链见 projectUrl */
-function baseUrl(port) {
-	return `http://localhost:${port}/`;
+const originOf = (o) => typeof o === "number" ? {
+	port: o,
+	host: "localhost"
+} : o;
+function baseUrl(o) {
+	const { port, host } = originOf(o);
+	return `http://${host}:${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)}` : ""}`;
+function projectUrl(o, project, file) {
+	const { port, host } = originOf(o);
+	if (!project) return baseUrl(o);
+	return `http://${host}:${port}/${project.split("/").filter((s) => s !== "").map(encodeURIComponent).join("/")}${file ? `?file=${encodeURIComponent(file)}` : ""}`;
 }
 // src/web/autoregister.ts
 /**
@@ -2307,11 +2411,15 @@ async function ensureViewer(opts = {}) {
 			root: dir,
 			pid: running.pid,
 			port: running.port,
-			url: projectUrl(running.port, project),
+			url: projectUrl({
+				port: running.port,
+				host: running.access.host
+			}, project),
+			access: running.access,
 			startedDaemon: false
 		};
 	}
-	const { started, pid, port } = await ensureDaemon({ noOpen: true });
+	const { started, pid, port, access } = await ensureDaemon({ noOpen: true });
 	const watched = await sendRequest({
 		kind: "watch",
 		project,
@@ -2324,13 +2432,18 @@ async function ensureViewer(opts = {}) {
 	handles.set(project, await attachPersistent(project));
 	rootsSynced = false;
 	await syncProjectRoots();
-	if (started) openBrowser(projectUrl(port, project));
+	const url = projectUrl({
+		port,
+		host: access.host
+	}, project);
+	if (started) openBrowser(url);
 	return {
 		project,
 		root: dir,
 		pid,
 		port,
-		url: projectUrl(port, project),
+		url,
+		access,
 		startedDaemon: started
 	};
 }
@@ -2637,6 +2750,9 @@ const TOOLS = {
 				...depth !== void 0 ? { depth } : {}
 			});
 			const designSystem = projectFilesInfo(info.root, { ensure: true });
+			let note;
+			if (info.access.bind === "all") note = `宿主 localhost 转发不可用，查看器已绑 0.0.0.0；给人打开的地址用返回的 url（${info.url}），不要用 localhost。`;
+			else if (info.access.jumped) note = `默认端口 ${info.access.requestedPort} 不可用，查看器起在 ${info.port}；给人打开的地址是 ${info.url}。`;
 			return {
 				ok: true,
 				project: info.project,
@@ -2644,6 +2760,8 @@ const TOOLS = {
 				url: info.url,
 				pid: info.pid,
 				port: info.port,
+				access: info.access,
+				...note !== void 0 ? { note } : {},
 				started: info.startedDaemon,
 				designSystem
 			};
@@ -3459,4 +3577,4 @@ async function runStdioServer() {
 	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 };
+export { listComponents as A, findBrowser as C, ensureProjectScaffold as D, componentsPathFor as E, projectFilesInfo as F, projectFontRegistry as I, readTextIfExists as L, listPresets as M, notePathFor as N, findNodeIn as O, presetPathFor as P, setPreset as R, encodeLine as S, applyProjectPresets as T, resolveProjectDir as _, defaultRouteIpv4 as a, socketPath as b, windowsSystem32 as c, attachPersistent as d, isDaemonRunning as f, pidPath as g, lockPath as h, open_browser_exports as i, listPresetGroups as j, findProjectRoot as k, ensureDaemon as l, sendRequest as m, runStdioServer as n, interopEnabled as o, queryDaemon as p, TOOLS as r, isWsl as s, createMcpServer as t, reuseDaemon as u, safeJoin as v, screenshotPen as w, LineDecoder as x, sanitizeProjectName as y, setProjectRoots as z };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "paintress",
-  "version": "0.7.0",
+  "version": "0.7.1",
   "description": "Design-document operation layer for AI agents: read, query, edit, render",
   "type": "module",
   "license": "MIT",

package/skills/paintress/SKILL.md

@@ -105,8 +105,10 @@ paintress web
 paintress watch <name> <dir>    # register a directory that lives outside the project
 ```
 
-- project list: `http://localhost:3316/`
-- one document: `http://localhost:3316/<name>?file=<relative/path>`
+- project list: `http://localhost:6033/`
+- one document: `http://localhost:6033/<name>?file=<relative/path>`
+
+**Never hardcode the port.** It is picked at startup and reported back in the `http` field (`paintress web`) and in `url` / `access.url` (`paintress_viewer`): print that field, do not rebuild the URL. The default is `6033`, but if the host cannot reach it the viewer falls back to `6133` / `6233`, and finally to `0.0.0.0` with the same three ports — in that last case the working address is `http://<wsl-ip>:6033/` and `localhost` will **not** work from the user's browser, so say so instead of handing them a dead link. `--port` pins one port and errors when busy; `--bind loopback|all` pins the interface.
 
 ## Bind the project yourself — do not wait to be asked