@cychien/ezdesign 0.8.1 → 0.9.1

package/README.md

@@ -1,4 +1,9 @@
-# ezdesign
+<h1>
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="docs/brand/ezdesign-dark.svg">
+    <img alt="ezdesign" src="docs/brand/ezdesign-light.svg" height="32">
+  </picture>
+</h1>
 
 > Point at your live app. Your agent fixes it.
 
@@ -6,12 +11,15 @@ ezdesign turns any locally running dev server into an annotatable review surface
 agent iteration. The user marks up the **real page** - click an element, frame a region, select
 some text, leave a comment - and the feedback flows to a local coding agent (Claude Code, Codex,
 anything that can run a CLI) as structured items that resolve to **exact source locations**. The
-agent edits the code, HMR updates the page in place, the user reviews the next round.
+agent edits the code, HMR updates the page in place, the user reviews the next round. Beside the
+app, **canvases** hold HTML designs the agent draws, for exploring ideas before (or instead of)
+changing the real thing.
 
 ```
 $ npx -y @cychien/ezdesign@latest http://localhost:5173/pricing --agent claude  # managed ACP agent
 $ npx -y @cychien/ezdesign@latest http://localhost:5173/pricing                 # portable poll mode
-$ npx -y @cychien/ezdesign@latest poll http://localhost:5173/                   # agent waits for feedback
+$ npx -y @cychien/ezdesign@latest poll                                          # agent waits for feedback
+$ npx -y @cychien/ezdesign@latest --agent claude                                # no dev server: canvases only
 ```
 
 - **Zero config.** A local daemon reverse-proxies your dev server and injects the annotation
@@ -21,9 +29,12 @@ $ npx -y @cychien/ezdesign@latest poll http://localhost:5173/
   guessing which part of the page you meant. Paste or drop a screenshot into any comment and the
   agent gets a path to it; `/element` points a comment at a second element, so "make this match
   that one" arrives as a `file:line` too.
-- **Every screen at once.** Review on one device or lay all three out on a canvas - desktop,
+- **Every screen at once.** Review on one device or lay all three out on a grid - desktop,
   iPad and iPhone side by side at their real viewports, scrolling together. An annotation stays on
   the screen it was made on, and reaches the agent tagged with the width it was made at.
+- **Canvases beside the app.** Tabs next to the App hold boards of frames - complete HTML pages
+  at real viewport widths that the agent adds, you arrange, and both of you annotate. `/element`
+  crosses tabs, so "build [ref 1] into the app" points at a frame from an App comment.
 - **Built for the loop.** In ACP mode, ezdesign owns the agent and keeps its live work, questions,
   and permission prompts in the review shell. Poll mode keeps the blocking structured-JSON contract
   for any external agent or automation. HMR keeps iterations in place; the review chrome lives
@@ -103,7 +114,7 @@ Two modes, and the toolbar shows which one is armed. Both leave the page live un
   which is what tells two instances of the same component apart. This is the mode for "this whole
   block", "these four cards", "the spacing through here".
 
-One comment is composed at a time - across every preview on the canvas, not just the one you are
+One comment is composed at a time - across every preview on the grid, not just the one you are
 in - so a box drawn in one screen cannot open a second comment box behind the one you are writing.
 
 ## The comment box
@@ -220,36 +231,36 @@ half of what a responsive review is looking at:
 | `3` | 電腦 | 1440×788 - a 1440×900 laptop screen, less the menu bar and the browser's own |
 
 The sizes are the **page area** a browser leaves on that device, not the screen it leaves it on -
-so a card on the canvas stops showing the page exactly where the real thing stops showing it. On
+so a card on the grid stops showing the page exactly where the real thing stops showing it. On
 its own a size takes only its width from the table and the height from your screen: one preview
-gets the whole stage to show the page in, and the canvas is where the fold is what you are
+gets the whole stage to show the page in, and the grid is where the fold is what you are
 checking.
 
 The names are shelves, not machines - a 手機 row naming a handset would claim a precision the
 row does not have, when phone widths run from 360 up past 430. The sizes are still taken from
 real machines; the comments in `devices.ts` say which.
 
-**`4` lays them out on one canvas** - phone and tablet side by side, the desktop on the row below.
+**`4` lays them out on one grid** - phone and tablet side by side, the desktop on the row below.
 The control in the stage's top corner picks which sizes are on it: the three above, plus a portrait
 tablet (834×1018) that is off by default.
 
-The canvas is drawn at **true size**, always. A 375 card is 375 pixels whether it is standing alone
+The grid is drawn at **true size**, always. A 375 card is 375 pixels whether it is standing alone
 or with three others beside it - a scaled 375 is not 375 to a media query, and a page measured at a
 size nobody browses at is not a measurement. Turning a size off does not resize or rearrange the
 ones that are left. What does not fit is what the dragging is for.
 
-Every card is the device it names, at its own height. What keeps the canvas short enough to work
+Every card is the device it names, at its own height. What keeps the grid short enough to work
 on is the two-row layout, not a cap on the cards - a card cut to a shared height would be lying
 about where the fold falls, which is half of what the preview is for.
 
-**Drag a card by its label to rearrange the canvas.** A card cannot stop just anywhere: it lands
+**Drag a card by its label to rearrange the grid.** A card cannot stop just anywhere: it lands
 top-aligned in an existing row, or on a row of its own, and a line marks where it would go -
 upright between two cards, flat between two rows. The arrangement is remembered, and a size turned
 on later joins as its own row at the bottom rather than reshuffling what you laid out.
 
-**Drag the background to move the canvas.** The frames are the app: a press inside one belongs to
-the page, so the backdrop and the gaps are what the canvas is panned by. That is also why the
-canvas does not have to fit - what is off the edge is a drag away.
+**Drag the background to move the grid.** The frames are the app: a press inside one belongs to
+the page, so the backdrop and the gaps are what the grid is panned by. That is also why the
+grid does not have to fit - what is off the edge is a drag away.
 
 Scrolling inside any one preview scrolls the others to the same point in the page, and navigating
 one - a link, back, forward - takes all of them: annotations are filtered by path, and three
@@ -258,7 +269,60 @@ previews on three pages is three separate reviews.
 An annotation belongs to the screen it was made on: mark up the iPhone card and the pin lives
 there, not on all three. The agent gets `@mobile 390x844` in the anchor either way. Everything the
 overlay draws - the comment box, the element label, the pins - is drawn back up to full size, so a
-canvas scaled to 60% is still one you can read and type into.
+grid scaled to 60% is still one you can read and type into.
+
+## Canvases
+
+A canvas is an infinite board of frames. Each frame is one complete, self-contained HTML document -
+its own `<head>`, its own styles, scripts and CDN assets allowed - rendered in its own iframe at a
+real viewport width, so a 390 frame is a phone to its media queries however far the board is zoomed
+out. No CSS is shared between frames: exploration directions diverge, and that is the point.
+
+**Tabs.** The strip above the stage has an **App** tab while a dev server is attached, then one tab
+per open canvas. `+` makes a new one, a double-click on a tab renames it, and closing a tab
+archives the canvas: the tab goes, the files stay. **Canvas** lists every canvas, open and
+archived, and reopens one; hover a row for **刪除**, which removes the canvas and all its frames
+(after asking). A session has one active tab:
+two shell windows follow each other, and every batch tells the agent which tab you sent it from.
+
+Run `ezdesign` with no url in a project without a dev server and the shell opens on that
+project's canvases - one empty `未命名 canvas` the first time. Run `ezdesign <url>` later and the
+App tab joins the same shell; the conversation carries on.
+
+**The board.** Drag the background or hold Space to pan, scroll to pan, pinch or Cmd/Ctrl+scroll to
+zoom around the pointer, `-`/`+` in the corner to step, `⇧1` to fit everything, `⇧0` to go back to
+100%. Click a frame to select it, Shift+click to add, `⌘A` for all; drag to move, with guides that
+snap to other frames' edges and centres; `⌘D` duplicates, `⌫` deletes, arrows nudge (`⇧` for 10). A
+frame keeps the size it was added at: it is a viewport, so it is never resized. Every step undoes
+and redoes (`⌘Z`, `⌘⇧Z`). Double-click a frame to scroll it or click through its controls; Escape
+hands the pointer back. Positions, the open tabs, the active tab and each canvas's camera survive a
+reload and a daemon restart.
+
+**Annotating.** `元素` and `範圍` work inside frames as they do on the app, and an annotation in a
+frame reaches the agent as a line of that frame's file -
+`.ezdesign/canvases/<canvas>/frames/<frame>.html:14 · [canvas frame "Hero A" on canvas "首頁探索"]`.
+`/element` crosses tabs both ways: start it in an App comment, switch to a canvas, Cmd+click the
+frame you mean, and the comment comes back with the ref in it - or the reverse.
+
+**The agent.** An ACP agent gets the `ezdesign-canvas` tools - `list_canvases`, `create_canvas`,
+`read_canvas`, `reopen_canvas`, `add_frame`, `update_frame`, `remove_frame` - from its first turn,
+granted without asking. New frames go on the canvas you sent from, or else the newest open one; the
+agent starts a new canvas only when none is open or you ask for one. A canvas it creates becomes the
+active tab and its frames appear as each call returns. A frame's HTML is the agent's: it changes it
+through the tools or by editing the file, and the open shell reloads that frame either way. The agent
+picks a frame's size when it adds it; after that, where the frame sits is yours, and the tools
+refuse geometry on a frame that exists. Poll mode has no canvas tools.
+
+**On disk.** Canvases live in the project, in `.ezdesign/canvases/<canvas>/`: `canvas.json` (name,
+frames), `layout.json` (where each frame is) and `frames/<frame>.html`. ezdesign writes the two
+JSON files and never reads back an edit made to them by hand; frame files are yours to edit. It
+does not touch your `.gitignore`: committing canvases is your call.
+
+**Isolation.** Frame documents are agent-written pages running third-party scripts, so they are
+served from `http://localhost:<port>` while the shell stays on `http://127.0.0.1:<port>` - another
+site. A frame cannot read the shell's storage, script it, or call the session's api, and the
+overlay inside it reaches the review through the shell. Two shortcuts do not fire while focus is
+inside a frame: send (`⌘↵`) and stop (`⌘.`).
 
 ## Configuration
 
@@ -267,26 +331,43 @@ canvas scaled to 60% is still one you can read and type into.
 | `EZDESIGN_DATA_DIR` | `~/.ezdesign` | Session state, the daemon registry and log, versions installed by the in-shell update, and the update-check cache |
 | `EZDESIGN_CONTROL_PORT` | `4400` | First port of the ten-port range the daemon searches for its control server |
 | `EZDESIGN_NO_UPDATE_CHECK` | unset | Set to `1` and the daemon never asks the npm registry for the latest version, so the shell never offers an update |
+| `EZDESIGN_NO_IDLE_STOP` | unset | Set to `1` and the daemon never stops itself for being idle; something else, like `npm run dev`, owns its lifetime |
+| `EZDESIGN_DESIGN_HARNESS` | unset (off) | Set to `1` in the environment the daemon starts from and the experimental 增強設計 design harness is available; unset, the shell has no switch and no agent is asked to use it |
 | `EZDESIGN_INSPIRE_URL` | `https://inspire.ezdesign.dev` | The inspiration database the `inspire` commands query |
+| `EZDESIGN_API_URL` | `https://api.ezdesign.dev` | The ezdesign backend the review shell signs in through |
 
-Set both together to run a second, fully isolated instance: a starting daemon adopts any live
-daemon it finds inside its own control range, so moving the data dir alone still lands you on the
-shared daemon. `npm run dev` sets both.
+Set `EZDESIGN_DATA_DIR` to run a second, fully isolated instance: a starting daemon only adopts a
+live daemon that serves its own data dir, so instances sharing a control range each take their own
+port in it. `npm run dev` sets both.
 
 Sessions outlive the daemon that served them. On start, the daemon picks each session back up
 from disk and re-binds it to the port it last held, so a review shell tab you already have open
-only needs a reload, and feedback you queued before the restart is still waiting. If that port has
-since been taken, the session moves to a free one and the CLI re-resolves it. A session that was
-driving an ACP agent starts that agent again **and asks it to resume the conversation they were
-having**, so the review carries on where it stopped. Whether that works is the agent's answer to
-give - a transcript it no longer has, or an agent that cannot resume at all, leaves the review in a
-fresh context, and only then does the thread say so.
-
-A session belongs to one project on one origin, not to the origin alone. Dev servers all default
-to the same port, so reviewing a second project on `localhost:5173` would otherwise inherit the
-first one's conversation and hand its undelivered feedback to the wrong agent. The project is the
-nearest `.git` or `package.json` ancestor of the directory you run `ezdesign` from, so switching
-projects on a port starts a clean review and switching back finds the old one intact.
+reconnects by itself, and feedback you queued before the restart is still waiting. If that port
+has since been taken, the session moves to a free one and the CLI re-resolves it. A daemon brings
+back the sessions that were live when it went down; one that stopped itself after half an hour
+with no shell open brings back none, and the next `ezdesign` or `poll` in a project wakes that
+project's session. Only time awake counts toward that half hour, so a laptop that sleeps with a
+shell open wakes to a review that is still there. A shell left open while its daemon is gone says
+so, and the `ezdesign` that brings the session back finds it reconnecting instead of opening a
+second window. A session that was driving an ACP agent starts that agent again **and asks it to
+resume the conversation they were having**, so the review carries on where it stopped. Whether
+that works is the agent's answer to give - a transcript it no longer has, or an agent that cannot
+resume at all, leaves the review in a fresh context, and only then does the thread say so.
+
+A session belongs to a project, not to a dev-server origin. The project is the nearest `.git` or
+`package.json` ancestor of the directory you run `ezdesign` from. A dev server that comes back on
+another port keeps the review: `ezdesign http://localhost:5174/` in the same project points the
+open shell at the new port, with the conversation and the queue intact. Dev servers all default to
+the same port, so one origin is attached to one project at a time: opening a second project on
+`localhost:5173` moves the origin to it, and the first project keeps its conversation and queue and
+only loses its app until you attach one again. `poll`, `progress` and `end` find the session by the
+project they run from; a url passed to them is only checked against the attached app, with a note
+when it differs.
+
+Sessions from versions before this one were per origin. The first daemon of this version folds them
+into project sessions, keeping every queued annotation, batch and conversation, and moves the old
+directories to `sessions-legacy/` in the data dir, never deleting them. A daemon older than this
+version does not read the new format, so going back to one starts with no sessions.
 
 ## Agent modes
 
@@ -358,8 +439,11 @@ other's - so there is no way to hand a conversation over. Nothing ezdesign owns
 conversation stays in the thread's own picker with the agent that had it, and switching back finds it
 again, resumable by the agent that remembers it.
 
-The agent can design the way a designer works, through a five-step harness in the bundled skill:
-product, stack, design, components, make. It is opt-in, experimental - the switch says 實驗 - and a
+The agent can design the way a designer works, through a five-step harness shipped with the daemon:
+product, stack, design, components, make. It is off by default: set `EZDESIGN_DESIGN_HARNESS=1` in the
+environment the daemon starts from to enable it, and until then the shell has no switch, no agent is asked
+to use it, and the remembered choice for each project is kept untouched for when it is on. With
+the flag on it is opt-in, experimental - the switch says 實驗 - and a
 premium feature: the **增強設計** switch on its own line above the agent and the model, marked with a
 gold sparkle, turns it on, and the choice is remembered for the project - across sessions, a dev
 server that moved ports, `/new` and daemon restarts - except that it starts off when the project's
@@ -377,8 +461,8 @@ agent may go past it. An ordinary change edits code only. The two files change
 when you ask for it, when a correction has come twice, or when you state a rule - only on what you
 actually said, never on what the agent reads into a send-back; a change that only leaves a line stale is mentioned in the reply, not edited. Between them,
 `.ezdesign/config.json` records the stack and the browser tool the agent looks at the page with. The
-skill needs no ezdesign session to run: installed in Claude Code or Codex and invoked on its own, it
-walks the same steps against the project and the dev server.
+installed skill does not carry the harness: it opens reviews, and the harness is reached only
+through the daemon with the flag on.
 
 Turning the switch on in a project that lacks either file asks first, in the card above the
 composer: 啟用增強設計 - 增強設計會建立 PRODUCT.md 與 DESIGN.md，是否繼續？ 取消 leaves the switch off,
@@ -423,10 +507,11 @@ Without `--agent`, the review uses the existing CLI contract:
 
 ```
 npx -y @cychien/ezdesign@latest http://localhost:5173/
-npx -y @cychien/ezdesign@latest poll http://localhost:5173/
+npx -y @cychien/ezdesign@latest poll
 ```
 
-`poll` blocks until the user sends feedback, prints the structured batch as JSON, and exits. This
+`poll` blocks until the user sends feedback, prints the structured batch as JSON, and exits. Run it
+from the project, like the command that opened the session. This
 mode remains available for scripts and integrations that consume the CLI contract directly.
 
 ## Inspiration
@@ -456,6 +541,46 @@ results belong in the agent's reply, not in your repository. A search that finds
 with one line, and one that cannot run - no token, a refused token, a service that cannot be
 reached - exits 2 with one line, so the agent says so and carries on.
 
+## Saving references from Chrome
+
+The capture extension saves an image, a video or a region of any page into one design library
+under `~/.ezdesign/library/`, shared by every project, with your tags and a note. Saving needs no
+dev server, no session and no daemon: Chrome talks to a small native host that ezdesign installs.
+
+```
+npx -y @cychien/ezdesign@latest extension install
+```
+
+`install` copies the host into `~/.ezdesign/native-host/`, registers it with every Chromium browser
+it finds (Chrome and its channels, Chromium, Arc, Brave, Edge, Vivaldi; macOS and Linux), and
+prints the folder to load once: open `chrome://extensions`, turn on **Developer mode**, choose
+**Load unpacked** and pick `~/.ezdesign/extension`. The folder stays put across ezdesign updates,
+and the daemon brings the host and the extension up to its own version when it starts. The host
+needs Node 22.13 or newer. `--user-data-dir <dir>` installs into one browser profile only.
+
+- **Right-click an image or a video** and choose **儲存至 ezdesign**. A dialog opens over the page
+  with a preview, tags (suggested by how often you use them) and a note; **儲存** or Cmd+Enter saves,
+  Esc or a click outside leaves nothing behind. Saving the same bytes again shows **已收藏過** and
+  adds to the item you already have.
+- **The toolbar icon or Alt+Shift+S** starts a region capture: drag a rectangle, or click once for
+  the whole visible page. On pages an extension cannot draw on, such as `chrome://` pages, the
+  visible page is captured at once and the dialog opens in its own window.
+- Images and plain video files keep their original bytes. A streaming video (YouTube, Instagram,
+  anything playing through MediaSource) and a video over 200 MB are saved as a link with the time
+  you were at and the frame on screen. An image the host is refused for (a signed-in CDN) offers
+  **允許讀取** for that site, then is read with your cookies.
+
+`ezdesign extension status` lists each browser and any problem, and exits 1 when there is one.
+`ezdesign extension uninstall` removes the host and the extension folder; the library stays.
+
+## Signing in
+
+Some features will run on the ezdesign backend, and those need you signed in. The icon at the foot of the review shell's right-hand bar then signs you in, with Google or an
+email and a password. It opens the sign-in page in a new tab. When you are through, the tab closes
+itself and the icon shows your initial. Its menu shows the account and signs you out. One sign-in
+covers every review the daemon is serving. The token is kept in `~/.ezdesign/credentials.json`,
+mode 600, beside the inspiration token, and signing out revokes it.
+
 ## Development
 
 Working on ezdesign itself takes one command:
@@ -466,6 +591,7 @@ npm run dev                 # watch src/, serve the playground fixture, start an
 npm run dev -- --no-plugin  # the same page without ezdesignSource(), to see fallback-only anchors
 npm run dev:agent           # a stand-in poll-mode agent, for working on the poll contract itself
 npm run dev:cli status      # the ezdesign CLI, pointed at the dev daemon instead of the real one
+npm run brand               # regenerate the logo's PNG and SVG copies after editing src/brand.ts
 ```
 
 `npm run dev` opens the review in ACP mode, scoped to the fixture - the agent's working directory
@@ -474,7 +600,10 @@ is only for the poll contract.
 
 A client rebuild (`src/client/**`) only needs a browser reload; a rebuild the daemon loads
 restarts it, and in-flight polls reconnect on their own. Dev mode keeps its daemon registry and
-sessions in `.dev/`, so your own `~/.ezdesign` is never touched. The review target is
+sessions in `.dev/`, so your own `~/.ezdesign` is never touched. Each checkout runs its own stack:
+its daemon takes a control range in 4100-4199 and the fixture a port from 5173, both picked from
+the checkout's path and recorded in `.dev/dev.json`, so worktrees run `npm run dev` side by side
+and `npm run dev:cli` reaches its own checkout's daemon. The review target is
 [`fixtures/playground`](fixtures/playground/README.md).
 
 ## Status

package/dist/announcements/template-ERNKAKI5.svg

@@ -0,0 +1,33 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="640" height="400" viewBox="0 0 640 400">
+  <defs>
+    <linearGradient id="ground" x1="0" y1="0" x2="1" y2="1">
+      <stop offset="0" stop-color="#3a3632"/>
+      <stop offset="0.55" stop-color="#5c4a3d"/>
+      <stop offset="1" stop-color="#c9825a"/>
+    </linearGradient>
+    <radialGradient id="glow" cx="0.85" cy="0.9" r="0.7">
+      <stop offset="0" stop-color="#f2b48c" stop-opacity="0.55"/>
+      <stop offset="1" stop-color="#f2b48c" stop-opacity="0"/>
+    </radialGradient>
+    <filter id="lift" x="-20%" y="-20%" width="140%" height="160%">
+      <feDropShadow dx="0" dy="12" stdDeviation="18" flood-color="#000" flood-opacity="0.28"/>
+    </filter>
+  </defs>
+  <rect width="640" height="400" fill="url(#ground)"/>
+  <rect width="640" height="400" fill="url(#glow)"/>
+  <g filter="url(#lift)">
+    <rect x="96" y="72" width="448" height="296" rx="16" fill="#faf9f6"/>
+  </g>
+  <rect x="96" y="72" width="448" height="40" rx="16" fill="#f2f0e9"/>
+  <rect x="96" y="96" width="448" height="16" fill="#f2f0e9"/>
+  <circle cx="122" cy="92" r="5" fill="#d9d5ca"/>
+  <circle cx="140" cy="92" r="5" fill="#d9d5ca"/>
+  <circle cx="158" cy="92" r="5" fill="#d9d5ca"/>
+  <rect x="128" y="144" width="200" height="18" rx="9" fill="#171717"/>
+  <rect x="128" y="176" width="292" height="10" rx="5" fill="#e9e6dd"/>
+  <rect x="128" y="196" width="248" height="10" rx="5" fill="#e9e6dd"/>
+  <rect x="128" y="236" width="112" height="32" rx="8" fill="#171717"/>
+  <rect x="320" y="228" width="192" height="108" rx="10" fill="#f2f0e9" stroke="#e56d41" stroke-width="2" stroke-dasharray="6 5"/>
+  <circle cx="320" cy="228" r="13" fill="#e56d41"/>
+  <text x="320" y="233" font-family="-apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif" font-size="14" font-weight="700" fill="#fff" text-anchor="middle">1</text>
+</svg>