paintress 0.3.1 → 0.5.0

package/README.md

@@ -8,13 +8,13 @@
 
 ## What it is
 
-paintress reads and writes structured design documents — JSON files with a documented schema (`.pen`, and its own `.ptr` for anything it writes). It renders them to HTML, serves a local viewer, and exposes the same operations as MCP tools and as a CLI.
+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.
 
 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.
 
 | Part | Purpose |
 | --- | --- |
-| MCP tools | query, read, update, insert, delete, move, batch, validate, render, screenshot |
+| MCP tools | 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 |
@@ -43,6 +43,9 @@ paintress install pi cursor # or only the ones you name
 
 ```text
 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)
 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
@@ -53,7 +56,7 @@ 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 render <file> <out.html>                      write the canvas as HTML
-paintress shot <file> <out.png> [--scale n]             render to PNG
+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 ping | status | stop                          viewer control
@@ -75,6 +78,12 @@ paintress watch demo ./demo
 
 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.
+
+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.
+
 ## MCP clients
 
 `paintress install` writes these; the same entries can be added by hand.
@@ -101,9 +110,25 @@ paintress mcp-config cursor   # print the exact snippet instead of editing files
 
 - `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
 - `.agents/memory/ARCHITECTURE.md` — design decisions and their rationale
 - `.agents/implementations/` — per-change records with measurements
 
+## Release (maintainers)
+
+Publishing is tag-driven: a `v*` tag makes `.github/workflows/publish.yml` build, test and `npm publish --provenance` through OIDC trusted publishing. Do not publish from a laptop.
+
+```bash
+pnpm release patch             # 0.3.1 → 0.3.2
+pnpm release minor             # 0.3.1 → 0.4.0
+pnpm release major             # 0.3.1 → 1.0.0
+pnpm release patch --dry-run   # print the plan only
+```
+
+The script refuses to run on a dirty worktree or a non-default branch, verifies the tag is free, runs typecheck (server + ui), the test suite, the build and the package-contents check, then commits `chore(release): vX.Y.Z`, tags it, pushes branch + tag, and finally waits until the version is actually on npm (a green run that published nothing is reported as a failure, not a success).
+
+`--prepare-only` stops after the local commit and tag; `--no-wait` returns right after the push; `--local` publishes from this machine as an emergency path and skips the CI checks.
+
 ## License
 
 MIT
@@ -205,7 +230,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 `.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 `.ptr` or `.pen` file is the end-to-end check.
 
 ### 5. Multi-agent rules
 

package/README.zh-CN.md

@@ -8,13 +8,13 @@
 
 ## 这是什么
 
-paintress 读写结构化的设计稿——带公开 schema 的 JSON 文件（`.pen`，以及它自己写出的 `.ptr`）。它把设计稿渲染成 HTML，起一个本地查看器，并把同一套操作同时暴露为 MCP 工具和 CLI。
+paintress 读写结构化的设计稿——带公开 schema 的 JSON 文件。**`.ptr` 是 paintress 的标准格式**：paintress 创建的一切都是 `.ptr`。**`.pen` 兼容**：读取、编辑、渲染完全一致，绝不在背后悄悄转换。它把设计稿渲染成 HTML，起一个本地查看器，并把同一套操作同时暴露为 MCP 工具和 CLI。
 
 它不是编辑器：没有画布、没有拖拽、没有属性面板。人在浏览器里看设计稿并点击节点指认目标，agent 负责读写。
 
 | 组成 | 作用 |
 | --- | --- |
-| MCP 工具 | 查询、读取、更新、插入、删除、移动、批量、校验、渲染、截图 |
+| MCP 工具 | 新建、查询、读取、更新、插入、删除、移动、批量、校验、渲染、截图 |
 | CLI | 同样的操作，外加查看器进程；不接 agent 也能用 |
 | 查看器 | 本地 web 服务：渲染设计稿、高亮变更、把点击的节点变成 `#1`、`#2`… |
 | 截图 | 整张画布的 PNG，给能看图的 agent 用 |
@@ -43,6 +43,9 @@ paintress install pi cursor # 或只写指定的客户端
 
 ```text
 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]                  读取节点子树
@@ -75,6 +78,8 @@ paintress watch demo ./demo
 
 画布操作：滚轮以指针为锚点缩放，空格 / 中键 / 空白处拖拽平移，`Ctrl/Cmd+0` 回到 100%，`Shift+1` 适应窗口。多画板文件会显示画板条。通过 CLI 或 MCP 做的修改会在查看器里高亮，点击会让节点获得短号，agent 用 `paintress_marks` 读回。
 
+工具条右侧有两个只影响查看的开关。**画布背景**切 Light / Gray / Dark，只改画布区底色，不动界面其它部分（点档位或拖滑块）。**界面语言**在中 / EN 之间切；首次打开跟随浏览器语言，不是中文就是英文。两者都按浏览器记住。注册新项目、或往已跟踪目录里放一个新的 `.ptr` / `.pen`，所有已打开的查看器都会自动刷新，不需要手按 F5。
+
 ## MCP 客户端
 
 `paintress install` 会写入下面这些位置，也可以手动添加。
@@ -101,9 +106,25 @@ paintress mcp-config cursor   # 只打印片段，不改文件
 
 - `specs/PLAN.md` —— 路线与未决问题
 - `format/spec.yaml` —— 文件格式规格（`.pen` 层冻结，`.ptr` 层演进）
+- `format/README.md` —— 两层关系，以及为什么 `.ptr` 是标准格式
 - `.agents/memory/ARCHITECTURE.md` —— 设计决策与理由
 - `.agents/implementations/` —— 每次变更的记录与实测数据
 
+## 发版（维护者）
+
+发布由 tag 驱动：`v*` tag 会让 `.github/workflows/publish.yml` 构建、测试并通过 OIDC trusted publishing 执行 `npm publish --provenance`。不要在笔记本上直接发布。
+
+```bash
+pnpm release patch      # 0.3.1 → 0.3.2
+pnpm release minor      # 0.3.1 → 0.4.0
+pnpm release major      # 0.3.1 → 1.0.0
+pnpm release patch --dry-run   # 只打印计划
+```
+
+脚本会拒绝在脏工作区或非默认分支上发版，确认 tag 未被占用，跑类型检查（服务端 + ui）、测试、构建与包内容自检，然后提交 `chore(release): vX.Y.Z`、打 tag、推分支与 tag，最后等到版本真的出现在 npm 上才算完（CI 绿了但什么都没发出去，会如实报成失败）。
+
+`--prepare-only` 停在本地提交与 tag；`--no-wait` 推完就返回；`--local` 本机直接发布，是应急路径，会跳过 CI 的检查。
+
 ## 许可
 
 MIT
@@ -205,7 +226,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`。会话重启后，对任意 `.pen` 文件调用 `paintress_doc_info` 是一次端到端验证。
+第二条命令应当返回包含 `"serverInfo": {"name": "paintress", …}` 的 `result`。会话重启后，对任意 `.ptr` 或 `.pen` 文件调用 `paintress_doc_info` 是一次端到端验证。
 
 ### 5. 多 agent 规则