visual-edit

# Visual Edit — Design Tweak request handling The **Design Tweak** app lets a designer visually pick element(s) in a live preview and attach natural-language comments. Comments accumulate into a **request**, and the designer sends the whole batch at once. One request file therefore contains **many comments as sub-items**: ``` <app data dir>/queue/<timestamp>-<id>.json ``` The app data dir defaults to `~/.kiro/crew/apps/design-tweak/data/`, but moves with `KIROCREW_HOME` or `KIROCREW_APP_DATA_DIR`. The request prompt quotes the payload's real path — use that path, not the default. **A request is a batch. Work every comment in it, and report per comment.** ## The loop 1. **Read the request file.** The prompt names the request id; if not, read the newest file in the queue dir above. `state` will be `"sent"` — a `"draft"` request has not been handed to you yet, so leave drafts alone. 2. **Work `comments[]` in order.** Each entry is an independent edit with its own `cid`, `comment`, `sourceFile`, and `selection`. Do not merge them into one change, even when two comments touch the same file. 3. **For each comment**, resolve the target, make the edit, and report against **that comment's `cid`** (see below). 4. When every comment is done, tell the user what changed, grouped by comment number. ## Reporting progress — always per comment Each comment has its own progress bubble in the preview, so notes must be addressed to a `cid`: ``` design_tweak_update_thread( request_id=<requestId>, comment_id=<commentId>, text="Editing styles.css — uppercasing .section-title", ) ``` Post one note when you start a comment, and one per meaningful step. Keep each to a single short line. When that comment is finished, send `status="done"` so its dot turns green: ``` design_tweak_update_thread( request_id=<requestId>, comment_id=<commentId>, text="Done — added text-transform: uppercase", status="done", ) ``` The request's own status is **derived**: it flips to `done` on its own once every comment is `done`. Never set it directly. > **Why a tool and not a raw request.** The app's `/thread` route needs a > dashboard credential your session does not hold, so a hand-rolled HTTP POST > would be refused and the dots would never change. `design_tweak_update_thread` > is the sanctioned path: the credential lives in the MCP server process and you > never see one. `status` accepts only `done` — there is no clear/dismiss here. > **Never write to the request file yourself.** Do not edit `state`, `status`, > `sentAt`, or any other field by writing the JSON — the panel derives the > request's badge from its comments, and a hand-written `state` desynchronises > them. Progress is reported *only* through `design_tweak_update_thread`. The > file is the app's state, not a scratchpad. - Omitting `comment_id` posts a request-level note. Use that only for something that spans the whole batch ("rebuilding, one moment"). - A request-level `status="done"` marks *every* comment done. It is a fallback, not the normal path — prefer per-comment reporting so the designer can see which specific edits landed. - Do **not** dismiss a request unless the user asks — dismissing removes the pins. The tool cannot do this; it only appends thread progress. ## Resolving each comment's target source Every comment carries its own project context stamped by the backend — prefer it over searching, and note that comments in one batch can point at **different files** (the designer may have navigated between pages mid-batch). - `projectId` / `projectRoot` (request level) — which project, and the absolute path to its root. - `sourceFile` (per comment) — absolute path to the file that was being previewed when that comment was made. **May be empty**, and that is not an error: it is only set when the preview was a served *file*. A project previewed from its own dev server has routes, not file paths (`/pricing` is not a path on disk), so there is nothing honest to put here. **Use the element's own `source` block first — it is the most precise signal, and the only one available when `sourceFile` is empty:** - `confidence: "high"` — `file:line:col` from the build-time plugin. Trust it. Resolve `file` against `projectRoot`. - `confidence: "medium"` — framework internal (React Fiber). Verify against `htmlSnippet`. - `confidence: "low"` — no source map. If `sourceFile` is set, locate the node inside that one file by `htmlSnippet`, `classes`, `id`, or text. If it is also empty, search `projectRoot` for the snippet and **confirm before editing**. If `projectRoot` is empty too, a dev-server URL (`devServer`) was used with no registered project; fall back to the active project directory + `htmlSnippet`. ## Follow-up comments A comment with a non-empty `followUpTo` refines an **earlier** comment, whose `cid` it names. That original comment usually lives in a *different, already-sent* request — look for it in the queue dir, then in `../handled/`. Read the origin comment and its `thread` before editing: the follow-up is phrased as a delta ("actually make it 32px"), so it only makes sense against what was already done. Report the follow-up against its **own** `cid`, not the original's — the original request is finished and must not be mutated. ## Comments that ADD or DELETE an element — stamp `data-kiro-cid` A comment's pin is anchored to the element it was filed against. Two kinds of comment break that anchor, and both need one extra step from you. **When your change CREATES the element the comment asked for**, put the comment's `cid` on it: ```html <!-- comment 4.2: "add a Cancel button next to Save" --> <button data-kiro-cid="c-8f2a91" class="btn-secondary">Cancel</button> ``` The overlay looks for `[data-kiro-cid="<cid>"]` **before** anything else, so the pin leaves the placeholder position it was floating at and re-homes onto the real element as soon as the preview reloads. Without the attribute the bubble stays stranded where the user clicked, pointing at nothing. Stamp exactly **one** element per cid — the outermost node you created for it. If a comment asked for several elements, stamp the container. **When your change DELETES an element**, do nothing extra. The pin falls back to that element's former parent on its own. Do not stamp a sibling to "keep the pin alive" — a bubble on the wrong element is worse than one on the parent. Leave the attribute in place. It is a durable link between the source and the comment that produced it, the same role `data-kiro-source` plays, and it is what lets the pin survive later reloads. Only remove one if the user asks. ## Request schema ```json { "type": "visual_edit_batch", "id": "1720560000000-a1b2c3", "number": 3, "state": "draft | sent", "projectId": "e4b4aa4c", "projectRoot": "/Users/me/Developer/my-site", "createdAt": "2026-07-29T23:00:00Z", "sentAt": "2026-07-29T23:04:00Z", "thread": [], "comments": [ { "cid": "1720560000111-d4e5f6", "index": 1, "status": "new | sent | done", "comment": "increase spacing between these cards", "createdAt": "2026-07-29T23:00:00Z", "projectId": "e4b4aa4c", "sourceFile": "/Users/me/Developer/my-site/pricing.html", "previewUrl": "http://127.0.0.1:52431/e4b4aa4c/pricing.html", "followUpTo": "", "selection": { "mode": "single | multi", "elements": [ { "tag": "div", "id": "", "classes": ["card", "card--pricing"], "locator": "main > section:nth-of-type(2) > div:nth-of-type(3)", "boundingRect": { "x": 120, "y": 340, "width": 280, "height": 180 }, "source": { "file": "src/components/PricingCard.tsx", "line": 42, "column": 6, "confidence": "high | medium | low" }, "htmlSnippet": "<div class=\"card card--pricing\">…</div>", "relevantStyles": { "display": "flex", "gap": "12px" } } ] }, "thread": [ { "role": "user", "text": "increase spacing between these cards", "ts": "2026-07-29T23:00:00Z" } ] } ] } ``` Comment numbering shown to the designer is `<request number>.<index>` — comment `index: 1` of request `number: 3` is **3.1**. Use that form when talking to them. ## Editing guidance - Scope each edit to the selected element(s). Do not refactor surrounding code. - For `mode: "multi"`, apply that comment to every element in `elements` — they were selected as a set (e.g. "increase spacing between these cards" applies to the shared container or gap). - The `file` path inside `source` is relative to the **project root**, not the Kiro Crew workspace. Combine it with `projectRoot`. - Prefer editing the exact `line:col`; use `htmlSnippet`, `classes`, and `id` to disambiguate when a component renders in a `.map()` loop (same source line, many instances). - Never guess a file when confidence is `low` — locate it first, then confirm. - Keep edits minimal and reversible. The panel reloads the preview automatically each time a comment flips to `done`, so the designer sees results as you go.