paintress 0.5.1 → 0.6.0

package/README.md

@@ -1,6 +1,6 @@
 <div align="center">
   <img src="assets/icon-512-wordmark.webp" width="200" alt="paintress">
-  <p>Design-document operation layer for AI agents</p>
+  <p>A UI design tool for AI agents</p>
   <p><a href="README.zh-CN.md">中文</a></p>
 </div>
 
@@ -8,13 +8,17 @@
 
 ## What it is
 
-paintress reads and writes structured design documents — JSON files with a documented schema. **`.ptr` is paintress's standard format**: everything paintress creates is `.ptr`. **`.pen` is compatible**: read, edited and rendered the same way, never converted behind your back. It renders documents to HTML, serves a local viewer, and exposes the same operations as MCP tools and as a CLI.
+paintress is a UI design tool for AI agents. You describe a screen in chat, the agent draws it into a design file, and you watch it appear in your browser — no canvas to drag, no design app to learn.
 
-It is not an editor. There is no canvas, no drag-and-drop, no property panel. A human looks at the design in a browser and clicks nodes to point at them; the agent does the reading and writing.
+You point instead of describing: click any element in the viewer and it gets a short number (`#1`), so "make #1 blue" changes exactly that element.
+
+Designs are plain JSON files inside your project, so they diff and commit like code.
+
+The agent does the reading and writing, through MCP tools or the CLI. The browser viewer is for looking, clicking and marking.
 
 | Part | Purpose |
 | --- | --- |
-| MCP tools | create, query, read, update, insert, delete, move, batch, validate, render, screenshot |
+| MCP tools | ensure the viewer, create, query, read, update, insert, delete, move, batch, validate, render, screenshot |
 | CLI | the same operations plus the viewer process, for use without an agent |
 | Viewer | local web server: renders a document, highlights changes, hands back clicked nodes as `#1`, `#2`, … |
 | Screenshot | PNG of a whole canvas, for agents that can look at images |
@@ -45,7 +49,7 @@ paintress install pi cursor # or only the ones you name
 paintress mcp                                              start the stdio MCP server
 paintress new <file> [--name n] [--width n] [--height n] [--fill c]
                       [--layout vertical|horizontal|none] [--padding n] [--gap n] [--force]
-                                                           create a .ptr (one empty board)
+                                                           create a design file (one empty board)
 paintress info <file>                                      document summary
 paintress query <file> [--type t] [--name n|--regex]    find nodes
 paintress get <file> <id> [--depth n]                   read a node subtree
@@ -55,10 +59,12 @@ paintress delete <file> <id>                            remove a node
 paintress move <file> <id> <parent> [--index n]         reparent a node
 paintress batch <file> '<ops-json>'                     several operations at once
 paintress validate <file>                               check against the format spec
+paintress preset list|set|remove ...                    project presets (colors / radii)
+paintress component list|insert ...                     project component library
 paintress render <file> <out.html>                      write the canvas as HTML
 paintress shot <file> <out.png> [--scale n] [--board id|name]  render to PNG (one board or the whole canvas)
 
-paintress web [--port n] [--idle ms] [--daemon]         start the viewer
+paintress web [--port n] [--idle ms] [--daemon]         ensure the viewer is running (idempotent)
 paintress ping | status | stop                          viewer control
 paintress watch <name> <dir> | unwatch <name>           register a directory to browse
 paintress attach <name>                                 keep the viewer alive while an agent works
@@ -71,18 +77,28 @@ paintress mcp-config <client>                           print the config snippet
 ## Viewer
 
 ```bash
-paintress web --daemon --idle 3600000
+paintress web --daemon
 paintress watch demo ./demo
-# open http://localhost:3316/?project=demo&file=hello.ptr
+# open http://localhost:3316/demo
 ```
 
+`paintress web --daemon` is idempotent: if a viewer is already running it prints that process's `pid` / `port` / `http` and exits, so it is safe to run before every drawing session — there is never a second instance. The foreground form (`paintress web`) reuses a running viewer the same way instead of erroring; it only blocks when it had to start one. `paintress stop` is how you replace a running viewer (e.g. on another port).
+
+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.
+
+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, read-only: what the design is for, what is still open, which requirement it answers.
+
+The rail in the top-right corner holds the project's design system. **Presets** are the project's colors and corner radii: the agent references them (`$color-brand`) instead of pasting values, and you can change one here and watch the canvas update — no more "a bit bluer". **Components** is a read-only gallery of everything reusable the agent has built so far, so you can see progress and the agent can look before rebuilding something that already exists.
+
 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. Files with more than one board get a board strip. 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`.
 
-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: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.
+
+The viewer follows the agent instead of asking you to manage it. When an agent starts the viewer it opens the browser on its own project; projects appear and leave with a short animation as agents come and go; when the last project is gone a 10-second countdown closes the window and the process. A browser that nobody is looking at no longer keeps the process alive.
 
 When npm has a newer release than the running one, the version badge in the header grows a second line in rust red; clicking it opens the upgrade prompt (one copyable sentence) and the GitHub link. The check is client-optional on the daemon side: if npm is unreachable, the badge simply stays as it is.
 
-The toolbar's right side has two viewer-only controls. **Canvas background** switches Light / Gray / Dark for the design surface without touching the rest of the UI (click a stop or drag the knob). **Language** switches the interface between 中文 and EN; on first load it follows the browser, and anything that is not Chinese gets English. Both are per-browser and remembered locally. Registering a project, or dropping a new `.ptr` / `.pen` into a watched directory, updates every open viewer without a reload.
+The toolbar's right side has two viewer-only controls. **Canvas background** switches Light / Gray / Dark for the design surface without touching the rest of the UI. **Language** switches the interface between 中文 and EN; on first load it follows the browser, and anything that is not Chinese gets English. Both are per-browser and remembered locally. Registering a project, or dropping a new design file into a watched directory, updates every open viewer without a reload.
 
 ## MCP clients
 
@@ -104,16 +120,18 @@ paintress mcp-config cursor   # print the exact snippet instead of editing files
 
 ## Skill
 
-`skills/paintress/SKILL.md` is a short instruction file for agents: when to reach for these tools, how `#1` markers map to node ids, and which tool to use for what. Copy it into your agent's skill directory if it supports one.
+`skills/paintress/SKILL.md` is a short instruction file for agents: when to reach for these tools, **to bring the viewer up before drawing** (idempotently), how `#1` markers map to node ids, and which tool to use for what. Copy it into your agent's skill directory if it supports one.
 
 ## Documentation
 
 - `specs/PLAN.md` — roadmap and open questions
-- `format/spec.yaml` — the document format spec (the `.pen` profile is frozen; `.ptr` evolves)
-- `format/README.md` — how the two layers relate, and why `.ptr` is the standard format
+- `format/spec.yaml` — the design file format spec
+- `format/README.md` — how the format layers relate
 - `.agents/memory/ARCHITECTURE.md` — design decisions and their rationale
 - `.agents/implementations/` — per-change records with measurements
 
+paintress also opens existing `.pen` design files as-is.
+
 ## Release (maintainers)
 
 Publishing is tag-driven: a `v*` tag makes `.github/workflows/publish.yml` first check that **ci passed for the same commit**, then build, verify the package contents and run `npm publish --provenance` through OIDC trusted publishing. Tests run once, in `ci.yml`; publishing does not re-run them. Do not publish from a laptop.
@@ -231,7 +249,7 @@ paintress doctor                                        # entry present, command
 printf '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"check","version":"0"}}}\n' | paintress mcp
 ```
 
-The second command must answer with a `result` containing `"serverInfo": {"name": "paintress", …}`. After a session restart, `paintress_doc_info` on any `.ptr` or `.pen` file is the end-to-end check.
+The second command must answer with a `result` containing `"serverInfo": {"name": "paintress", …}`. After a session restart, `paintress_doc_info` on any design file is the end-to-end check.
 
 ### 5. Multi-agent rules
 

package/README.zh-CN.md

@@ -1,6 +1,6 @@
 <div align="center">
   <img src="assets/icon-512-wordmark.webp" width="200" alt="paintress">
-  <p>面向 AI agent 的设计稿操作层</p>
+  <p>给 AI agent 用的界面设计工具</p>
   <p><a href="README.md">English</a></p>
 </div>
 
@@ -8,13 +8,17 @@
 
 ## 这是什么
 
-paintress 读写结构化的设计稿——带公开 schema 的 JSON 文件。**`.ptr` 是 paintress 的标准格式**：paintress 创建的一切都是 `.ptr`。**`.pen` 兼容**：读取、编辑、渲染完全一致，绝不在背后悄悄转换。它把设计稿渲染成 HTML，起一个本地查看器，并把同一套操作同时暴露为 MCP 工具和 CLI。
+paintress 是一个给 AI agent 用的界面设计工具。你在对话里说要什么界面，agent 把它画进设计文件，你在浏览器里看到结果——没有画布要拖，也没有设计软件要学。
 
-它不是编辑器：没有画布、没有拖拽、没有属性面板。人在浏览器里看设计稿并点击节点指认目标，agent 负责读写。
+你点，它改：在查看器里点一下元素，它就得到一个短号（`#1`），说「#1 改成蓝色」改的就是那一个。
+
+设计稿是项目里的普通 JSON 文件，能 diff、能评审、能提交。
+
+读写由 agent 通过 MCP 工具或命令行完成；浏览器里的查看器只负责看、点、标。
 
 | 组成 | 作用 |
 | --- | --- |
-| MCP 工具 | 新建、查询、读取、更新、插入、删除、移动、批量、校验、渲染、截图 |
+| MCP 工具 | 确保查看器在跑、新建、查询、读取、更新、插入、删除、移动、批量、校验、渲染、截图 |
 | CLI | 同样的操作，外加查看器进程；不接 agent 也能用 |
 | 查看器 | 本地 web 服务：渲染设计稿、高亮变更、把点击的节点变成 `#1`、`#2`… |
 | 截图 | 整张画布的 PNG，给能看图的 agent 用 |
@@ -45,7 +49,7 @@ paintress install pi cursor # 或只写指定的客户端
 paintress mcp                                             启动 stdio MCP server
 paintress new <file> [--name n] [--width n] [--height n] [--fill c]
                     [--layout vertical|horizontal|none] [--padding n] [--gap n] [--force]
-                                                          新建 .ptr（一个空画板）
+                                                          新建设计稿（一个空画板）
 paintress info <file>                                     文档摘要
 paintress query <file> [--type t] [--name n|--regex]   条件查询节点
 paintress get <file> <id> [--depth n]                  读取节点子树
@@ -55,10 +59,12 @@ paintress delete <file> <id>                           删除节点
 paintress move <file> <id> <parent> [--index n]        移动节点
 paintress batch <file> '<ops-json>'                    一次执行多个操作
 paintress validate <file>                              按格式规格校验
+paintress preset list|set|remove ...                   项目预设（颜色 / 倒角）
+paintress component list|insert ...                    项目组件库
 paintress render <file> <out.html>                     渲染为 HTML
 paintress shot <file> <out.png> [--scale n]            渲染为 PNG
 
-paintress web [--port n] [--idle ms] [--daemon]        启动查看器
+paintress web [--port n] [--idle ms] [--daemon]        确保查看器在跑（幂等）
 paintress ping | status | stop                         查看器控制
 paintress watch <name> <dir> | unwatch <name>          注册/移除要浏览的目录
 paintress attach <name>                                agent 工作期间保持查看器存活
@@ -71,14 +77,22 @@ paintress mcp-config <client>                          打印单个客户端的
 ## 查看器
 
 ```bash
-paintress web --daemon --idle 3600000
+paintress web --daemon
 paintress watch demo ./demo
-# 打开 http://localhost:3316/?project=demo&file=hello.ptr
+# 打开 http://localhost:3316/demo
 ```
 
+`paintress web --daemon` 是幂等的：已经在跑就打印那个进程的 `pid` / `port` / `http` 后退出，所以每次开始作画前无条件跑一遍都没问题——永远不会出现第二个实例。前台形式（`paintress web`）同样复用正在跑的查看器，而不是报错；只有它自己真去启动时才会占住终端。要换端口/重启，用 `paintress stop`。
+
+agent 从 MCP 侧拿到同样的保证：`paintress_viewer` 确保查看器在跑并把当前项目注册进去，MCP server 还会在每次写操作前再确认一遍——于是查看器是在第一次编辑之前就起来的，而不是等人开口。
+
+设计稿旁边放一份同名 Markdown（`home.ptr` → `home.md`），画布左上角就会出现「笔记」按钮。点开后画布向右收窄、左侧切出笔记——只读：这份设计是干什么的、还有哪些待定、对应哪条需求。
+
+右上角的浮动工具条放的是这个项目的设计系统。**预设**是项目里的颜色和倒角：agent 只写引用（`$color-brand`），不贴裸值；你在这里改一个值，画布立刻变——不用再说「红一点、再蓝一点」。**组件**是只读画廊，把 agent 已经做好的可复用组件摊开给你看进度，也让 agent 动手前先来这儿找。
+
 画布操作：滚轮以指针为锚点缩放，空格 / 中键 / 空白处拖拽平移，`Ctrl/Cmd+0` 回到 100%，`Shift+1` 适应窗口。多画板文件会显示画板条。通过 CLI 或 MCP 做的修改会在查看器里高亮，点击会让节点获得短号，agent 用 `paintress_marks` 读回。
 
-工具条右侧有两个只影响查看的开关。**画布背景**切 Light / Gray / Dark，只改画布区底色，不动界面其它部分（点档位或拖滑块）。**界面语言**在中 / EN 之间切；首次打开跟随浏览器语言，不是中文就是英文。两者都按浏览器记住。注册新项目、或往已跟踪目录里放一个新的 `.ptr` / `.pen`，所有已打开的查看器都会自动刷新，不需要手按 F5。
+工具条右侧有两个只影响查看的开关。**画布背景**切 Light / Gray / Dark，只改画布区底色，不动界面其它部分（点档位或拖滑块）。**界面语言**在中 / EN 之间切；首次打开跟随浏览器语言，不是中文就是英文。两者都按浏览器记住。注册新项目、或往已跟踪目录里放一个新的设计稿，所有已打开的查看器都会自动刷新，不需要手按 F5。
 
 ## MCP 客户端
 
@@ -100,16 +114,18 @@ paintress mcp-config cursor   # 只打印片段，不改文件
 
 ## Skill
 
-`skills/paintress/SKILL.md` 是给 agent 的简短说明：什么时候用这些工具、`#1` 怎么映射到节点 id、哪个工具做什么。支持 skill 机制的客户端把它复制进对应目录即可。
+`skills/paintress/SKILL.md` 是给 agent 的简短说明：什么时候用这些工具、**作画前先把查看器拉起来（幂等）**、`#1` 怎么映射到节点 id、哪个工具做什么。支持 skill 机制的客户端把它复制进对应目录即可。
 
 ## 文档
 
 - `specs/PLAN.md` —— 路线与未决问题
-- `format/spec.yaml` —— 文件格式规格（`.pen` 层冻结，`.ptr` 层演进）
-- `format/README.md` —— 两层关系，以及为什么 `.ptr` 是标准格式
+- `format/spec.yaml` —— 设计稿文件格式规格
+- `format/README.md` —— 格式分层之间是什么关系
 - `.agents/memory/ARCHITECTURE.md` —— 设计决策与理由
 - `.agents/implementations/` —— 每次变更的记录与实测数据
 
+已有的 `.pen` 设计稿也能直接打开，原样渲染。
+
 ## 发版（维护者）
 
 发布由 tag 驱动：`v*` tag 会让 `.github/workflows/publish.yml` 先校验**同一提交的 ci 已通过**，再构建、自检包内容并通过 OIDC trusted publishing 执行 `npm publish --provenance`。测试只在 `ci.yml` 跑一次，发布不重跑。不要在笔记本上直接发布。
@@ -227,7 +243,7 @@ paintress doctor                                        # 条目存在、命令
 printf '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"check","version":"0"}}}\n' | paintress mcp
 ```
 
-第二条命令应当返回包含 `"serverInfo": {"name": "paintress", …}` 的 `result`。会话重启后，对任意 `.ptr` 或 `.pen` 文件调用 `paintress_doc_info` 是一次端到端验证。
+第二条命令应当返回包含 `"serverInfo": {"name": "paintress", …}` 的 `result`。会话重启后，对任意设计稿调用 `paintress_doc_info` 是一次端到端验证。
 
 ### 5. 多 agent 规则