leglas-mcp 0.6.0 → 0.7.0

package/README.md

@@ -15,7 +15,7 @@
 </p>
 
 <p align="center">
-  <img src="https://raw.githubusercontent.com/FredAmartey/leglas/main/.github/assets/screenshots/rail-single.jpg" width="900" alt="The Leglas interface: a rail of three design directions on the left, and the selected one running as the real app filling the rest of the window" />
+  <img src="https://raw.githubusercontent.com/FredAmartey/leglas/main/.github/assets/screenshots/rail-single.jpg" width="900" alt="The Leglas interface: a rail of design directions on the left, one of them with a variant grouped under it, and the selected one running as the real app filling the rest of the window" />
 </p>
 
 <p align="center"><i>Every direction in the rail, the selected one running as your actual app. Arrow keys flip between them.</i></p>
@@ -46,7 +46,7 @@ and sessions that clean up after themselves.
 ## What you can do with Leglas
 
 <p align="center">
-  <img src="https://raw.githubusercontent.com/FredAmartey/leglas/main/.github/assets/screenshots/compare-artboards.jpg" width="900" alt="The Leglas interface: a rail of three design directions on the left, and two of them running side by side as the real app, each labelled with its name." />
+  <img src="https://raw.githubusercontent.com/FredAmartey/leglas/main/.github/assets/screenshots/compare-artboards.jpg" width="900" alt="The Leglas interface: the rail on the left, and two directions running side by side as the real app, each labelled with its name and the width it is drawn at." />
 </p>
 
 <p align="center"><i>Two directions for the same page, running side by side as the actual app.</i></p>
@@ -77,13 +77,35 @@ and sessions that clean up after themselves.
   once the agent uses a Leglas tool. Each run
   reports in a card above the field: who is working, what file they
   are touching, how long it has been, a stop button while it runs and
-  retry when it fails. Your agent, your subscription, no keys.
+  retry when it fails. Your agent, your subscription, no keys. Claude
+  Code, Codex and Cursor pick the conversation back up between
+  requests, so a run after the first goes straight to the change
+  instead of reading the project again. Claude Code and Codex warm up
+  while you type and let their process go once you have left Leglas
+  alone for a few minutes, so an open window is not holding one.
   Prefer a terminal? `npx leglas watch` is the same loop with the
   agent's own output scrolling by. In Claude Code, the Leglas MCP
   server can also push each request straight into your open session as
   a channel event (channels are a research preview: start Claude Code
   with `--dangerously-load-development-channels
   server:<your leglas server name>`).
+- A change makes a variant, not a rewrite. Ask for something on the
+  direction you are looking at and the result registers under it in the
+  rail, with the original still there to compare against. A chip beside
+  the send button switches to changing the direction itself, for when a
+  change really is a fix. Hover any direction to see what it was built
+  from and the change that was asked for, in the words that were typed.
+- Your agent sees what you see. Every change you send carries a screenshot
+  of the direction at the width you are looking at, a crop of whatever you
+  pointed at with a note, the other pane when you are comparing, and any
+  image you pasted into the composer as a reference. Leglas renders them
+  with a Chrome, Chromium, Brave or Edge already on your machine, nothing
+  to install; with none found, the request says so and goes anyway. Agents
+  can look for themselves too: `npx leglas show "Aurora" --screenshot`
+  writes a PNG of a direction (`--width 390` for the phone layout) and the
+  MCP `show` tool returns the image. The instructions Leglas writes for
+  agents ask for one look after each change, so a broken layout gets fixed
+  before you see it.
 - Keep the winner with one command. Leglas moves it into your source
   tree and clears the exploration away.
 - No app yet or want plain HTML comparisons? Some people want exactly that, and it works fine. Same comparison, no dev server.
@@ -99,6 +121,9 @@ npx leglas
 Leglas starts on port 4100, proxies your app, and opens
 `http://localhost:4100/leglas`. With no configuration you get a single
 preview of your app root. Add a config file to compare more than one thing.
+If that port turns out to be served from outside your project, Leglas
+says so and points at `devServer` and `--user-port` rather than quietly
+proxying the wrong app.
 
 It works with whatever you're building in. Leglas never imports or
 executes your framework, so the target can be Next, Vite, Remix,
@@ -166,9 +191,10 @@ edit the hero. The supporting commands:
   where switching is instant.
 - `npx leglas show "Aurora" --json` answers for one direction: its entry, the
   source file behind it, the variants based on it, what it is being compared
-  against, and anything still pending on it. Copying a direction from the
-  rail hands over a block that ends in this command, so an agent given the
-  block can go and get the rest.
+  against, and anything still pending on it. Add `--screenshot` and it
+  renders the direction too, so an agent can look at what it built. Copying
+  a direction from the rail hands over a block that ends in this command, so
+  an agent given the block can go and get the rest.
 - `npx leglas keep "Aurora" --to src/components/hero.tsx` moves the winner
   into real source and ends the exploration.
 
@@ -176,7 +202,9 @@ Asking for a change works from the interface too. Type what you want
 changed into the field under the rail (or press `R`) and Leglas composes a
 prompt naming the direction and the file behind it, copies it to your
 clipboard, and queues it. The direction it means is the one highlighted
-directly above the field. Your agent drains the queue with `npx leglas requests --json` and clears
+directly above the field. By default the request asks for a new variant
+beside that direction; the chip next to the send button switches it to a
+change in place. Your agent drains the queue with `npx leglas requests --json` and clears
 it with `--clear`. Leglas runs no model of its own; your agent already
 knows your conventions and your taste.
 
@@ -184,28 +212,30 @@ Most of what you would type into that field is the part describing where
 the problem is, so you can point at it instead. Press `A` and the preview
 becomes a picker: hovering outlines the element under the pointer,
 clicking drops a numbered pin that takes a note, and dragging marks an
-area and names every element inside it. The page still scrolls, so the
-thing three screens down is as easy to mark as the headline. Annotations
+area and names every element inside it. Click a pin again to reread what
+it says, reword it or drop it. The page still scrolls, so the thing three
+screens down is as easy to mark as the headline. Annotations
 are a request on their own, so the field can stay empty; leave three and
 send once. Each one carries the element's own words, its tag and classes,
 a path and the box it filled, and the request tells your agent which of
 those to trust first, because the design moves under them by design. One
 whose element has since gone turns amber rather than pointing confidently
-at the wrong thing.
+at the wrong thing, and one already sent with a change takes a ring until
+that change settles.
 
-The line under the field is the whole status: whether anything is
-listening, what you have queued, and when it has been picked up.
+The card above the field is the whole status: what you have queued, who
+has taken it and for how long, and what went wrong when a run fails.
 
 <p align="center">
-  <img src="https://raw.githubusercontent.com/FredAmartey/leglas/main/.github/assets/screenshots/field-idle.png" width="290" alt="The change field reading: Enter queues it for npx leglas requests" />
-  <img src="https://raw.githubusercontent.com/FredAmartey/leglas/main/.github/assets/screenshots/field-queued.png" width="290" alt="The change field reading: one change queued for your agent" />
-  <img src="https://raw.githubusercontent.com/FredAmartey/leglas/main/.github/assets/screenshots/field-pickedup.png" width="290" alt="The change field reading: Your agent is on it" />
+  <img src="https://raw.githubusercontent.com/FredAmartey/leglas/main/.github/assets/screenshots/field-idle.png" width="290" alt="The change field, empty, with its agent picker reading Choose an agent" />
+  <img src="https://raw.githubusercontent.com/FredAmartey/leglas/main/.github/assets/screenshots/field-queued.png" width="290" alt="A card above the change field reading: Change queued, pick who runs your changes" />
+  <img src="https://raw.githubusercontent.com/FredAmartey/leglas/main/.github/assets/screenshots/field-pickedup.png" width="290" alt="A card above the change field reading: Codex is on it, editing .leglas/variants/hero/poster.tsx, 56s, with a stop button" />
 </p>
 
 <p align="center"><i>Nothing waiting, then a request queued, then an agent that has taken it.</i></p>
 
-Pick an agent once and the same line shows it working: which file it is
-editing, a cancel if you change your mind, a retry when a run goes
+Pick an agent once and the same card shows it working: which file it is
+editing, a stop if you change your mind, a retry when a run goes
 wrong. `npx leglas watch` in another terminal is the same loop with the
 agent's own output in view, and it needs no flag once an agent has been
 picked in the interface.
@@ -298,9 +328,11 @@ export default {
 | `branch`         | no            | Preview a git branch instead of the running dev server                  |
 | `file`           | no            | An HTML file served by Leglas itself, instead of `url`                  |
 | `basedOn`        | no            | Title of the direction this is a variant of; the rail groups the family |
+| `askedFor`       | no            | The change that was asked for, in the words that were typed             |
 | `devServer`      | no            | Defaults to `http://localhost:3000`                                     |
 | `devCommand`     | with `branch` | How to start the app. Must contain `{port}`.                            |
 | `installCommand` | no            | Defaults to `npm install`                                               |
+| `scanPreviews`   | no            | Set `false` to skip background duplicate scans for expensive apps      |
 
 A broken config never stops the server. Leglas starts anyway and the
 interface reports what to fix, so you are not hunting through a stack
@@ -332,8 +364,8 @@ that is what the tools popover's "Scale each side to fit" switch is for.
 
 Arrows move between directions, `1` to `9` jump straight to one, `R` asks
 for a change to the one you are on, `A` annotates the design itself,
-`Cmd K` (`Ctrl K` elsewhere) searches and `B` collapses the rail. Press `?`
-for the whole keymap.
+`Cmd K` (`Ctrl K` elsewhere) searches, `T` opens the tools popover and `B`
+collapses the rail. Press `?` for the whole keymap.
 
 A small tools widget floats over the stage and can be dragged to any
 corner, because a floating control has a habit of sitting exactly where
@@ -348,36 +380,57 @@ the preview frame, never by altering what the proxy forwards.
 ## Command line
 
 ```text
-leglas init                Prepare a project and teach its agents
-leglas [options]           Start the server and open the interface
-leglas new <surface>       Scaffold a branch point for a surface
-leglas explore <surface>   Brief an agent's exploration of a surface
-leglas classify            Decide where a direction should live
-leglas add --title T --url U   Register a preview on this machine
-leglas list                Show every preview, shared and local
-leglas show <title>        Everything Leglas knows about one direction
-leglas requests            Collect change requests made from the interface
-leglas keep <title>        Keep a winner and end the exploration
-
-  --user-port <port>   Port your dev server is on
-  --port <port>        Port for Leglas (default 4100, next free if taken)
-  --config <path>      Use this config file instead of searching upward
+Usage
+  leglas init                Prepare a project and teach its agents
+  leglas [options]           Start the server and open the interface
+  leglas new <surface>       Scaffold a branch point for a surface
+  leglas explore <surface>   Brief an agent's exploration of a surface
+  leglas classify            Decide where a direction should live
+  leglas add --title T --url U   Register a preview on this machine
+  leglas list                Show every preview, shared and local
+  leglas show <title>        Everything Leglas knows about one direction
+  leglas requests            Show change requests made from the interface
+  leglas watch --run "<cmd>" Hand each request to your agent as it arrives
+  leglas keep <title> --to <path>  Keep a winner and end the exploration
+
+Options
+  --user-port <port>   Port your dev server is on (default: from config, or 3000)
+  --port <port>        Port for Leglas itself (default: 4100, next free if taken)
+  --config <path>      Config file to use instead of searching upward
   --no-open            Do not open the browser
-  --json               Print one machine-readable envelope
-
-  --print              (new) Print the scaffold instead of writing it
-  --from <path>        (new) Use an existing component as the baseline
-  --count <n>          (explore) How many directions, default 3
-  --based-on <title>     (explore) Variants of an existing direction instead of new ones
-  --based-on <title>     (add) The direction this preview is a variant of; groups the family
-  --asked-for <text>     (add) The change that was asked for, in the words that were typed
-  --change <path>      (classify) A file the direction creates or wires up
-  --rewrite <path>     (classify) An existing file whose behaviour must change
-  --note <text>        (add) Second line under the title
-  --tag <text>         (add) Repeatable
-  --branch <name>      (add) Back the preview with a checkout of this branch
-  --file <path>        (add) An HTML file served by Leglas itself
-  --to <path>          (keep) Where the winner should live
+  --json               Print a single machine-readable envelope
+  -h, --help           Show this
+  -v, --version        Show the version
+
+Options for new
+  --print              Print the scaffold instead of writing it
+  --from <path>        Use an existing component as the baseline
+
+Options for explore
+  --count <n>          How many directions (default 3)
+  --based-on <title>     Variants of an existing direction instead of new ones
+
+Options for watch
+  --run <command>      Your agent, with {prompt} where the request goes, for
+                       example "claude -p {prompt}". Remembered after first use
+  --port <port>        Port Leglas itself is on (default: 4100)
+
+Options for classify
+  --change <path>      A file the direction creates or wires up (repeatable)
+  --rewrite <path>     An existing file whose behaviour it must change (repeatable)
+
+Options for add
+  --note <text>        Second line under the title
+  --tag <text>         Repeatable
+  --branch <name>      Back the preview with a checkout of this git branch
+  --file <path>        Preview a plain HTML file served by Leglas itself
+  --based-on <title>   The direction this is a variant of; groups the family
+  --asked-for <text>   The change that was asked for, in the words that were typed
+
+Options for show
+  --screenshot         Render the direction and write a PNG
+  --width <n>          Capture width from 320 to 3840 (needs --screenshot)
+  --port <port>        Running Leglas port (needs --screenshot)
 ```
 
 `leglas.config.ts` is the shared description of a project: commit it and a
@@ -454,9 +507,9 @@ cross-origin previews, which the browser will not let it read.
 
 ## Limitations
 
-- Leglas shows directions; it does not create them. Comparing existing
-  routes costs nothing, but a new direction is still code you or your
-  agent writes.
+- Leglas runs no model of its own. Comparing existing routes costs
+  nothing, but a new direction is still code your agent writes; Leglas
+  hands it the request and shows the result.
 - The duplicate check compares rendered markup only, and only when the
   server renders some. Two previews that differ solely in a script are
   reported as identical, and in a fully client-rendered app the check
@@ -487,9 +540,12 @@ terminal and `pnpm --filter @leglas/shell dev` in another.
 
 Two packages are published, both unscoped: `leglas`, which bundles the
 server and the built interface, and `leglas-mcp`. Releases are
-tag-driven: bump both versions, push a `v<version>` tag, and CI runs the
-suite and publishes through npm trusted publishing. No npm token exists
-anywhere in the project.
+tag-driven: set the same version in both packages and `plugin.json`, turn
+the changelog's Unreleased section into that version, push a `v<version>`
+tag, and CI runs the suite and publishes through npm trusted publishing.
+A tag that disagrees with the manifests is refused, and so is a patch tag
+when `api-surface.txt` has moved since the previous one. No npm token
+exists anywhere in the project.
 
 ## License
 

package/dist/tools.js

@@ -1,4 +1,6 @@
-import { run, runAdd, runClassify, runExplore, runInit, runKeep, runList, runNew, runRequests, runShow, } from "leglas";
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { isOwnCapture, run, runAdd, runClassify, runExplore, runInit, runKeep, runList, runNew, runRequests, runShow, } from "leglas";
 import { z } from "zod";
 import { createEngagement } from "./engagement.js";
 async function capture(invoke) {
@@ -77,7 +79,8 @@ export function registerLeglasTools(server, options) {
         description: "Register a design direction on this machine so it appears in the rail. " +
             "The rail picks it up within seconds, so when building a set register " +
             "each direction as it lands rather than the whole set at the end. " +
-            "Use branch for a direction that lives on its own git branch.",
+            "Use branch for a direction that lives on its own git branch. " +
+            "Then call show with screenshot: true to look at what you registered.",
         inputSchema: {
             title: z.string().min(1).describe("Unique title; identifies the preview."),
             url: z.string().min(1).optional()
@@ -105,14 +108,60 @@ export function registerLeglasTools(server, options) {
         description: "Everything Leglas knows about one direction: its full entry, the source file behind " +
             "it, the variants based on it, the directions it is being compared against, and any " +
             "change requests still pending on it. Call this when handed a direction's reference " +
-            "block.",
+            "block. With screenshot: true, Leglas also renders the direction with a headless " +
+            "browser and returns the image, so you can see what you built. Do this after registering " +
+            "a direction and before saying it is done; width 390 shows the phone layout.",
         inputSchema: {
             title: z
                 .string()
                 .min(1)
                 .describe("The direction's title as the config spells it, not a renamed display name."),
+            screenshot: z.boolean().optional(),
+            width: z.number().int().min(320).max(3840).optional(),
         },
-    }, async ({ title }) => inProject(project, (cwd, deps) => runShow({ title, json: true, cwd }, deps)));
+    }, async ({ title, screenshot, width }) => {
+        const located = await project.locate();
+        if (!located.ok) {
+            return {
+                content: [{ type: "text", text: JSON.stringify({ ok: false, error: located.reason }) }],
+                isError: true,
+            };
+        }
+        const result = await capture((deps) => runShow({
+            title,
+            json: true,
+            screenshot: screenshot ?? false,
+            width: width ?? null,
+            port: null,
+            cwd: located.directory,
+        }, deps));
+        if (screenshot !== true || result.isError === true)
+            return result;
+        const text = result.content.find((entry) => entry.type === "text");
+        if (text === undefined || text.type !== "text")
+            return result;
+        try {
+            const envelope = JSON.parse(text.text);
+            const file = envelope.screenshot?.file;
+            // The path comes back over a loopback socket, which a stale record
+            // can point at something that is not Leglas. Only a real file inside
+            // this project's captures is read and handed to the host.
+            if (typeof file !== "string" || !(await isOwnCapture(located.directory, file))) {
+                return result;
+            }
+            const image = await readFile(resolve(located.directory, file));
+            return {
+                ...result,
+                content: [
+                    ...result.content,
+                    { type: "image", data: image.toString("base64"), mimeType: "image/png" },
+                ],
+            };
+        }
+        catch {
+            return result;
+        }
+    });
     server.registerTool("classify", {
         title: "Decide where a direction should live",
         description: "Before writing a direction, declare what it will touch and learn whether it can be " +

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "leglas-mcp",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Stdio MCP server exposing Leglas to agent hosts that cannot run a shell.",
   "type": "module",
   "bin": {
@@ -15,7 +15,7 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.30.0",
     "zod": "^3.25.76",
-    "leglas": "^0.6.0"
+    "leglas": "^0.7.0"
   },
   "license": "MIT",
   "repository": {