@pro-vi/designer 0.3.0 → 0.3.1

package/README.md

@@ -1,106 +1,81 @@
 # designer
 
-MCP + CLI for iterating on **claude.ai/design** — Claude's web-based wireframe and high-fidelity design tool.
+MCP + CLI that lets your coding agent drive **[claude.ai/design](https://claude.ai/design)** (Claude's wireframe + hi-fi design tool, no API) with full context of your codebase — capabilities, data shape, existing tokens fed into every prompt.
 
-The human describes intent. The orchestrating agent translates intent into a minimal prompt, relays it to Claude Design, hands the URL back to the human, interprets their reaction, iterates. When the human says "yes", `designer_handoff` downloads a tar.gz bundle (README + chat transcripts + all design files + source JSX) so the implementing agent (Claude Code, typically) can build the design in a real repo.
+Human describes intent → agent surveys codebase and prompts Claude Design → hands you the URL → iterate → `designer_handoff` bundles the result (README + chats + HTML + JSX) back into your repo.
+
+> **Status:** v0.3.0, early. macOS only.
 
 ## Stance
 
-- **Single-vendor, single-purpose.** Only `claude.ai/design`. No kitchen sink.
-- **`agent-browser` is the substrate.** Attaches to your real Chrome via CDP — sidesteps Cloudflare + Google SSO.
-- **Human is the designer.** See `~/.claude/skills/designer-loop`. Orchestrator is translation + plumbing; Claude Design has the taste; human arbitrates.
-- **URL is the default taste path.** `designer_prompt` returns a live claude.ai/design URL where tweak sliders work and variants switch. Local tasting harness exists only for when IDE chrome gets in the way.
-- **Artifacts land on disk.** Every iteration + every handoff saves under `./artifacts/{key}/`.
+- **Single-vendor, single-purpose.** Only `claude.ai/design`.
+- **Real Chrome via CDP.** Sidesteps Cloudflare + Google SSO.
+- **Capabilities drive design.** Agent surveys the codebase (entities, operations, states, tokens) and feeds them into every prompt. Intent tells Claude Design *how*; the codebase tells it *what*. See the [designer-loop skill](skills/designer-loop/SKILL.md).
+- **URL is the default taste path.** `designer_prompt` returns a live claude.ai/design URL with working tweak sliders and variant switcher.
+- **Artifacts land on disk.** Every iteration + handoff saves under `./artifacts/{key}/`.
 
 ## Install
 
-One-call first-run:
-
-```bash
-git clone https://github.com/pro-vi/designer.git && cd designer
-npm install
-./bin/designer setup
-```
-
-Optional — make `designer` available globally:
-
-```bash
-npm link
-designer setup     # now works from any cwd
-```
-
-`designer setup` is idempotent and auto-progresses:
+### Prerequisites
 
-1. Installs deps if missing.
-2. Checks `agent-browser` is on PATH.
-3. Asks you to Cmd+Q Chrome if a non-debug Chrome is running (polls until quit).
-4. Launches a dedicated debug Chrome (`--remote-debugging-port=9222`, profile at `~/.chrome-designer-profile/`).
-5. Polls until you sign in to Claude and reach `/design`.
-6. Installs the `designer-loop` skill at `~/.claude/skills/designer-loop/` unless one is already present (respects bootstrap/dotfiles-managed symlinks).
-7. Registers the MCP with Claude Code at user scope.
+- macOS, Node 20+, Google Chrome at `/Applications/Google Chrome.app`.
+- `agent-browser` on PATH: `npm i -g agent-browser` (or `brew install agent-browser`).
 
-Re-run any time — every step no-ops when already satisfied.
+### Three paths
 
-### Why a dedicated profile?
+All land at `designer setup`.
 
-Since Chrome 136, `--remote-debugging-port` is blocked on the default profile for security. The dedicated `~/.chrome-designer-profile/` is a one-time login that persists across launches. Your normal Chrome is untouched.
+```bash
+# A. Trial — no install
+npx -y @pro-vi/designer setup
 
-### Auto-launch
+# B. Daily use
+npm i -g @pro-vi/designer && designer setup
 
-After first setup, the MCP auto-launches debug Chrome from the saved profile on the first tool call of any session. You don't have to think about Chrome state again. If a non-debug Chrome is running, auto-launch bails with an actionable error.
+# C. Hacking on it
+git clone https://github.com/pro-vi/designer.git && cd designer
+npm install && ./bin/designer setup
+```
 
-### Bot detection
+### What `designer setup` does
 
-Login is a real human typing into a real Chrome window. `--remote-debugging-port` alone doesn't set `navigator.webdriver` (only `--enable-automation` does); user-agent is identical to normal Chrome. Cloudflare and Google OAuth see a normal session. First login on the new profile may trigger Google's "new device" verification — that's a standard one-time prompt.
+1. Verify deps (lockfile-hash compare).
+2. Check `agent-browser` on PATH.
+3. Ask you to quit a non-debug Chrome (polls until done).
+4. Launch debug Chrome (`--remote-debugging-port=9222`, profile at `~/.chrome-designer-profile/`).
+5. Poll until you sign in and land on `/design`.
+6. Install the `designer-loop` skill at `~/.claude/skills/designer-loop/` (skipped if already present — respects dotfile symlinks).
+7. Register the MCP with Claude Code (user scope).
 
-### Manual setup
+Re-run anytime — idempotent. Verify with `designer doctor`.
 
-The MCP registration embeds `DESIGNER_CDP=9222`, so Claude sessions pick it up automatically. The shell export below only matters for direct CLI invocations (`designer session`, `designer prompt`, etc.) from an interactive terminal — add it to `~/.zshenv` or equivalent if you use the CLI directly.
+### MCP only (skip the CLI)
 
 ```bash
-./scripts/designer-chrome.sh              # launches debug Chrome
-# sign in to Claude, navigate to /design
-curl -s http://127.0.0.1:9222/json/version | head   # verify CDP
-export DESIGNER_CDP=9222                  # only needed for direct CLI use
-claude mcp add --transport stdio designer \
-  -- env DESIGNER_CDP=9222 "$PWD/bin/designer" mcp serve
+claude mcp add --scope user --transport stdio designer \
+  -- env DESIGNER_CDP=9222 npx -y @pro-vi/designer mcp serve
 ```
 
-## CLI
+Still needs debug Chrome running (`npx -y @pro-vi/designer setup` handles it).
 
-Top-level help leads with the typical loop:
+### Notes
 
-```
-$ designer --help
+- **Dedicated profile.** Chrome 136+ blocks `--remote-debugging-port` on the default profile. Login to `~/.chrome-designer-profile/` persists.
+- **Auto-launch.** MCP auto-launches debug Chrome on the first tool call if the profile exists.
+- **Bot detection.** Real Chrome + user-controlled login — not headless. Cloudflare + Google OAuth see a normal session. First login may trigger a Google new-device prompt.
+- **`DESIGNER_CDP=9222`** is embedded in the MCP registration. Only export it in your shell if you invoke the CLI directly.
 
-designer — CLI + MCP for iterating on claude.ai/design
+## CLI
 
-Typical loop:
-  designer setup                                       (once per machine)
-  designer session --action create --name "X" --key x  start a project
-  designer prompt "design the …" --key x               prints 'Taste here: <url>'  ← open that
-  designer prompt - --key x < follow-up.txt            iterate until human says yes
-  designer handoff --key x                             bundle for code implementation
 ```
-
-Verbs are grouped: session lifecycle, design operations, file introspection, exit/promotion, setup+ops, internal. Every verb supports `--help`:
-
-```bash
-designer prompt --help        # expanded docs: input modes, flags, output shape, examples
-designer help handoff         # same
+designer setup                                       (once per machine)
+designer session --action create --name "X" --key x  start a project
+designer prompt "design the …" --key x               prints 'Taste here: <url>'
+designer prompt - --key x < follow-up.txt            iterate
+designer handoff --key x                             bundle for code implementation
 ```
 
-All verbs take `--key <k>` to isolate parallel sessions (e.g., working on two features at once). Local state lives at `~/.designer/sessions.json`.
-
-Prompts accept three input modes:
-
-```bash
-designer prompt "short text" --key feat-x                # positional
-designer prompt --prompt-file ./brief.md --key feat-x    # from file
-cat follow-up.txt | designer prompt - --key feat-x       # stdin
-```
-
-Output of `prompt` and `snapshot` leads with `Taste here: <url>` above the JSON — the URL is the default taste path.
+Every verb has `--help`. `--key <k>` isolates parallel sessions (state at `~/.designer/sessions.json`). Prompts accept positional, `--prompt-file`, or stdin (`-`).
 
 ## MCP
 
@@ -108,103 +83,54 @@ Six tools, registered at user scope by `designer setup`:
 
 | Tool | Purpose |
 |---|---|
-| `designer_session` | Enter / inspect / transition. Actions: `status` (default, read-only), `ensure_ready`, `resume`, `create`. Always returns stored state + `currentUrl` + `availableFiles`. |
-| `designer_prompt` | Modify the design (HTML-diff wait). Auto-appends a flat-layout instruction. Returns `url` (hand to human), `newFiles`, `activeFile`, `failureMode`, `htmlPath`, `chatReply`. |
-| `designer_ask` | Q&A with the assistant (chat-panel wait). No file changes. Returns `reply`. |
-| `designer_list` | `scope: 'projects'` (scrapes home) or `'files'` (scrapes file panel — flat-only, see quirks). |
-| `designer_snapshot` | Capture current state. Optional `filename` to switch first. Default: paths + hash only; `includeHtml: true` inlines. |
-| `designer_handoff` | Export → Handoff → download + extract tar.gz. Returns README + paths. Auto-repairs Claude-side em-dash filename bugs. |
-
-Registration:
-
-```bash
-claude mcp add --transport stdio designer \
-  -- env DESIGNER_CDP=9222 \
-     /Users/provi/Development/_projs/designer/bin/designer mcp serve
-```
-
-(`designer setup` runs this. After `npm link` it collapses to `designer mcp serve`.)
+| `designer_session` | Enter / inspect / transition. Returns stored state + `currentUrl` + `availableFiles`. |
+| `designer_prompt` | Modify the design (HTML-diff wait). Returns `url`, `newFiles`, `activeFile`, `failureMode`, `htmlPath`, `chatReply`. |
+| `designer_ask` | Q&A with the assistant, no file changes. |
+| `designer_list` | `projects` or `files` (flat-only — see quirks). |
+| `designer_snapshot` | Capture current file. Paths + hash by default; `includeHtml: true` inlines. |
+| `designer_handoff` | Export → download + extract tar.gz. Auto-repairs em-dash filename bugs. |
 
 ## The loop
 
 ```
 1. Intent       → human describes what they want to feel / change
-2. Read         → designer_session returns currentUrl + availableFiles
-3. Relay        → designer_prompt with a terse, guide-not-constrain prompt
-4. Taste        → hand the human the url from the return; they react in their own words
+2. Survey       → agent reads the target repo: entities, operations, states,
+                  failure modes, existing tokens — capability facts, verbatim
+3. Relay        → designer_prompt = intent + capabilities, minimal faithful prompt
+4. Taste        → hand the human the returned URL; they react in their own words
 5. Interpret    → next designer_prompt (modify) or designer_ask (clarify)
 6. Repeat 3-5   → until human says "that's it"
 7. Promote      → designer_handoff — bundle is the decision record
 ```
 
-Full guidance in `~/.claude/skills/designer-loop/SKILL.md` (also in-repo at `skills/designer-loop/SKILL.md`).
+Full guidance in [`skills/designer-loop/SKILL.md`](skills/designer-loop/SKILL.md).
 
 ## Tasting harness
 
-Fallback for when claude.ai/design's IDE chrome (chat panel + toolbar) eats too much viewport to judge at real scale. Requires a prior `designer_handoff`.
+Fallback when the live URL's IDE chrome eats viewport. Requires a prior handoff.
 
 ```bash
 designer tasting --key <key>
 ```
 
-Walks the latest bundle's `project/` dir (recursively — handles nested layouts), writes `tasting.html` with variant tabs + keyboard shortcuts (1/2/3) + persistent notes (localStorage), starts a local `http.server`, opens the browser.
-
-Default path for tasting is the live URL. Use tasting when: full-viewport comparison matters, Claude didn't build its own `index.html` gallery, or the IDE chrome is distracting.
+Writes `tasting.html` with variant tabs + 1/2/3 shortcuts + persistent notes, serves locally, opens the browser.
 
 ## Operations
 
-- `designer doctor` — diagnose first-run setup state. Checks agent-browser, CDP, a /design tab is open, selectors present, skill installed, MCP registered. Exits 2 on failure.
-- `designer health` — probe every UI anchor this MCP depends on. 17 probes across home / session / share / pattern categories. Exits 2 on any fail. Wire into cron / CI to catch claude.ai UI regressions (it already moved Export under Share once mid-development).
-
-## Layout
-
-```
-designer/
-├── package.json
-├── tsconfig.json            # type-check only
-├── tsconfig.build.json      # tsc → dist/
-├── bin/designer             # bash wrapper, prefers dist/ then tsx
-├── mcp-server.ts            # MCP stdio server (exports startMcpServer)
-├── cli.ts                   # same verbs, directly runnable; rich --help
-├── designer-controller.ts   # core flow: session, prompt, ask, snapshot, handoff
-├── browser.ts               # thin wrapper over agent-browser subprocess
-├── cdp-ensure.ts            # auto-launches debug Chrome on first tool call
-├── tasting.ts               # tasting.html generator + http.server
-├── ui-anchors.ts            # every DOM / URL / structural dependency, enumerated
-├── setup.ts                 # designer setup verb
-├── session-store.ts         # per-session state at ~/.designer/
-├── artifact-store.ts        # writes HTML/PNG/JSON under ./artifacts/{key}/
-├── repo-root.ts             # package.json walk so source + compiled both resolve resources
-├── selectors.json           # DOM selectors for the claude.ai/design surface
-├── scripts/
-│   ├── designer-chrome.sh   # standalone Chrome launcher
-│   └── probe.ts             # manual DOM exploration helper
-├── skills/
-│   └── designer-loop/SKILL.md   # the skill, copied to ~/.claude/skills/ by setup
-├── artifacts/               # generated outputs (gitignored)
-└── dist/                    # tsc build output (gitignored; published on npm)
-```
+- `designer doctor` — diagnose setup state. Exits 2 on failure.
+- `designer health` — probe 17 UI anchors. Wire into cron to catch claude.ai UI regressions.
 
 ## Known quirks
 
-- **Folder-organized variants.** Claude Design sometimes organizes multi-file variants under a subfolder (`directions/sediment.html`). The live MCP's file-list scrape (`designer_list files`, `availableFiles` in session status, `newFiles` diff from `designer_prompt`) is flat-only; nested files are invisible until `designer_handoff`. Mitigation: `designer_prompt` auto-appends *"Keep all generated files at the project root; no subfolders."* Handoff bundle is folder-aware; `designer tasting` walks recursively.
-- **React-controlled inputs.** `agent-browser fill` doesn't fire React's synthetic input event. The controller uses the native `HTMLTextAreaElement` value-setter + `dispatchEvent(new Event('input', { bubbles: true }))`, plus JS `.click()` on Send and Create. Both are canonical React-compat patterns.
-- **Em-dash handoff filenames.** Claude's handoff pipeline wrote em-dash (`—`) into `index.html` hrefs but saved files with regular hyphens. `designer_handoff` detects and repairs (`repaired.renamed: [...]`). No-op when hrefs already resolve.
-- **Cross-origin iframe.** Served HTML lives on `claudeusercontent.com` with a signed `t=` token in the URL. Direct fetch from node works without cookies. The token is session-scoped, not per-iteration.
-- **UI regressions.** Claude has moved critical buttons mid-development (Export → Share dropdown). `designer health` is the early-warning system; run it periodically.
+- **Folder-organized variants.** The live file-list scrape is flat-only; nested files invisible until `designer_handoff`. `designer_prompt` auto-appends *"no subfolders."* Bundle + `designer tasting` are folder-aware.
+- **React-controlled inputs.** `agent-browser fill` doesn't fire React's synthetic `input` event; we use the native value-setter + `dispatchEvent` + JS `.click()`.
+- **Em-dash handoff filenames.** Claude's handoff pipeline sometimes writes `—` in hrefs but `-` in filenames. `designer_handoff` detects and repairs.
+- **UI regressions.** Claude has moved critical buttons mid-development (Export → Share). Run `designer health` periodically.
 
-## Publishing (future — not yet on npm)
+## Credits
 
-Prepped but not shipped. Prerequisites: npm account with scope `@pro-vi` (currently 404/available), 2FA, `npm login`. Then:
+Built on [`agent-browser`](https://github.com/ctate/agent-browser) by [@ctatedev](https://x.com/ctatedev).
 
-```bash
-npm publish --access public
-```
-
-`prepublishOnly` runs `tsc --noEmit` + `tsc -p tsconfig.build.json`. `files` whitelist in `package.json` keeps the tarball under 35KB. Published package will support:
+## License
 
-```bash
-npx @pro-vi/designer setup                                         # trial
-npm i -g @pro-vi/designer && designer setup                        # daily use
-claude mcp add --transport stdio designer -- designer mcp serve    # MCP
-```
+[MIT](LICENSE).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pro-vi/designer",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "type": "module",
   "description": "MCP + CLI for autonomous iteration of claude.ai/design — drives the design surface via agent-browser, downloads handoff bundles, and exposes a tasting harness for full-viewport variant comparison.",
   "license": "MIT",
@@ -33,7 +33,7 @@
     "check": "tsc --noEmit",
     "build": "tsc -p tsconfig.build.json",
     "prepublishOnly": "npm run check && npm run build",
-    "postinstall": "node -e \"if (!process.env.npm_config_global) process.exit(0); console.log('\\n  designer installed. Next: run `designer setup` to launch debug Chrome, sign in, and register the MCP.\\n')\"",
+    "postinstall": "node scripts/postinstall.mjs",
     "probe": "tsx scripts/probe.ts"
   },
   "dependencies": {
@@ -53,6 +53,7 @@
     "bin/",
     "skills/",
     "scripts/designer-chrome.sh",
+    "scripts/postinstall.mjs",
     "selectors.json",
     "README.md",
     "LICENSE"

package/scripts/postinstall.mjs

@@ -0,0 +1,4 @@
+// Runs on `npm i -g @pro-vi/designer`. Silent for local/dev installs.
+if (process.env.npm_config_global) {
+  console.log('\n  designer installed. Next: run "designer setup" to launch debug Chrome, sign in, and register the MCP.\n');
+}

package/skills/designer-loop/SKILL.md

@@ -53,7 +53,7 @@ Orient in the claude.ai/design surface:
 
 1. `designer_session({ key })` — returns stored state + `availableFiles`. If `stored.designUrl` exists, you're resuming; otherwise create one with a sensible default name derived from the intent (don't interview for a project name).
 2. For existing projects: `designer_snapshot({ filename })` per file of interest. You get `htmlPath` — read it only if deep inspection is warranted.
-3. If this is a frontend for an existing backend or codebase, read the backend's API shape and any existing design tokens in the target repo BEFORE prompting. Those are constraints to thread into the prompt verbatim, not aesthetic hypotheses to propose.
+3. **Survey capabilities — this is the primary source of design, not an afterthought.** Before relaying any intent, read the target repo for what the system actually DOES: entities and their fields, operations / endpoints, states (loading / empty / error / success), failure modes, hard constraints (auth, rate limits, offline cases), and existing design tokens. The design EXPRESSES these capabilities — the human's feeling-shaped intent only tells you *how*; the codebase tells you *what*. Transfer capability facts into the prompt verbatim; don't filter them down to what you think matters aesthetically. If there's no codebase yet (greenfield intake), say so in the prompt so Claude Design doesn't invent constraints.
 
 A one-line brief is fine ("I see X; here's the prompt I'm about to send"). Don't turn it into design-by-interview.
 
@@ -65,9 +65,9 @@ Guide, don't constrain. The prompt gives Claude enough to make good decisions, n
 
 | Guide (include) | Constrain (omit) |
 |---|---|
-| What the product does / data it renders | Color palette (unless it's a hard brand token) |
+| **Capability context**: what the product does, entities + fields, operations, states, failure modes | Color palette (unless it's a hard brand token) |
 | User's situation / primary action | Type treatment, font feel |
-| Entities, field names, copy that must appear | Layout direction, whitespace rules |
+| Entities, field names, copy that must appear verbatim | Layout direction, whitespace rules |
 | Adjacent surfaces / what must NOT change | Tone adjectives ("contemplative", "trustworthy") unless paired with a concrete lever |
 | Hard brand tokens (palette, type, existing component names) as non-negotiables | Visual hierarchy choices |
 | Quantity + shape of variants ("3 full-page files", "20 on a wrapping grid") | Variant names (let Claude pick) |
@@ -184,6 +184,7 @@ Never override with "but best practice says..." — capture the tension in the d
 ## Guardrails
 
 - **Read before relaying** (Phase 2). Call `designer_session` first — it returns `availableFiles`.
+- **Transfer capabilities, don't summarize them.** When the codebase has real endpoints / entities / states, drop them into the prompt unabridged. Summarizing is filtering — you're quietly making design decisions Claude Design should make.
 - **Guide, don't constrain.** Scope + data + hard brand tokens in; aesthetic choices out.
 - **Lock brand explicitly.** Claude won't guess your palette.
 - **Let Claude name variants** from the problem domain.
@@ -193,6 +194,7 @@ Never override with "but best practice says..." — capture the tension in the d
 
 ## Anti-Patterns
 
+- **Designing before reading capabilities.** Booting the loop without surveying the target repo produces designs that look good and don't fit the system. Phase 2 step 3 is load-bearing.
 - **Interviewing about aesthetics.** Scope questions are fine when intent is genuinely unclear; taste questions aren't yours to ask.
 - **Proposing variants of your own.** Claude Design proposes. You relay.
 - **Constraining where Claude should have room.** Brand tokens are constraints; palette feelings and layout hunches aren't.