Desde

Editor guide

Comments

Comments in the Editor: how to place them, where they are stored on disk, and what happens when the repo is connected to a Viewer. Notes are a related but dormant feature.

The Comments tab in the right rail holds sticky remarks you can attach to a specific element in your running prototype. A comment is pinned to a DOM element on a particular page, supports replies and a resolved state, and appears in a list ordered by when it was created. The tab can also hold notes, a second, structurally identical kind of remark that is off by default; see Notes are off by default below.

Comments exist because the useful thing to say about a prototype is usually about one particular thing on one particular screen, and a message in a chat thread loses that.

Comments versus notes#

Comments and notes are structurally identical types. The difference is what they are for, where they can travel, and (as of 2026-08-14) whether they ship at all:

  • Comments are the shared kind, and the only one on by default. When your repo is connected to a Viewer, comments sync both ways. You see what reviewers wrote, they see what you wrote.
  • Notes never leave the repo, and are off by default. See Notes are off by default below.

In the list a comment carries a speech-bubble icon and a note a sticky-note icon. When Notes are turned on, that icon is the only visual difference between the two rows.

Inside the prototype they also render differently: a comment is a small pin, while a note renders as a card that can be minimized. The list's ⋮ menu offers Minimize all notes / Expand all notes once Notes are on and you have any.

Notes are off by default#

Notes used to be the second kind of sticky remark alongside comments: a working note only you can see, pinned to an element the same way a comment is. They went dormant by product decision on 2026-08-14, the same day this tab was renamed from Annotations to Comments. Comments and notes had always behaved identically at the UI layer, which is what made "Comments" an honest name once notes stopped shipping by default: with notes off, the list holds one kind of thing, so the tab says what it holds.

Turn notes back on in .desde/config.json at your prototype's root:

{
  "editor": {
    "notes": true
  }
}

or set EDITOR_NOTES=1. Either restores the Note button next to Comment, note rows in the list, the note thread popup, and the "Minimize all notes" / "Expand all notes" items. Nothing was deleted: the stores, hooks, handlers and their tests all stay intact, gated at both ends, so a stale client cannot reach /api/editor/notes/* while notes are off.

Placing one#

At the top of the Comments tab there is a Comment button. Clicking it (or picking Comment from the toolbar's tool picker, which is the exact same control reading the exact same state) puts the prototype into placement mode; your next click inside the prototype picks the element to anchor to, and a popup opens for you to type. A second Note button appears next to it only once you turn notes on.

The anchor is stored as a CSS selector plus the page path (not as an x/y position), so it survives the layout moving. Document-relative coordinates are stored alongside as a fallback only.

If the selector no longer matches anything on the current build, the comment is flagged off-target in the list with a struck-through map-pin icon and a tooltip. It is shown at the fallback position, or with no pin at all if there are no coordinates. This is deliberate: a stale anchor is never allowed to make a comment silently invisible.

Clicking a pin (or a note card, once notes are on) inside the prototype switches the right rail to Comments for you, whichever tab you were on.

The list has a Hide switch that hides every pin (and note card, once on) inside the prototype without deleting anything, and a Show resolved toggle in the ⋮ menu. Resolved comments are hidden by default.

There is one small delay you may notice right after the panel loads: for a moment, Editor does not yet know whether this repo syncs to a Viewer. Asking for the Comment tool in that window is refused with a toast, "Checking the viewer connection, try again in a moment.", so a comment placed in the gap can never be written to the local file for a repo the team actually reads in a Viewer. If the check itself fails, placement stays refused with a different toast instead: "Can't tell where comments should be saved, so they're paused rather than saved to the wrong place. Reload to retry."

Fix with AI#

A comment thread offers Fix with AI, which hands the comment to the chat agent as a prompt carrying the comment's text, the element it is anchored to, and the page. It is a shortcut from "someone asked for this" to "the agent is looking at it", not an automatic fix. The agent still has to do the work and you still see everything it does in the chat panel.

Where they are stored#

By default both live as JSON files inside your repo (notes.json only fills up once you turn notes on):

.desde/comments.json
.desde/notes.json

Writes are atomic (the file is written to a temporary sibling and renamed over the original), so a crash mid-write cannot leave you with a corrupt file.

.desde/ is added to .git/info/exclude at startup, so these files do not show up in git status and are not committed. That is a local ignore in your clone only. If you want notes to travel with the repo you would have to commit them deliberately.

Every annotation is stamped with an author. In the Editor that is the CLI's machine identity, falling back to a generic "Local user" when none can be derived.

Note The Editor is single-user, on one machine. Two people cannot annotate the same running Editor. Sharing annotations with other people is what the Viewer is for.

Syncing comments to a Viewer#

At a high level: if this repo is connected to a Viewer project, and this machine holds an access token for that Viewer, comments are read from and written to the Viewer instead of the local file. Notes are not affected either way; they never sync.

All three conditions have to hold for syncing to be on: a Viewer configured for this repo, a token stored on this machine, and being online. Miss any one and comments fall back to the local file.

There is no badge for this any more. Instead, when the list is empty and comments are not syncing, the empty state explains why in place of a plain "no comments" message:

  • "Connect a viewer to share comments", when no Viewer is configured for this repo at all. The description explains that anything written here stays on this machine, with a link to the setup docs.
  • "This machine has no access token", when a Viewer is configured but this machine has no token for it. The description tells you to add one from the project menu.

You add a token through Change viewer… in the project menu in the breadcrumb.

The token never reaches the browser. The Editor's own local process holds it and proxies comment traffic to the Viewer, and that proxy will only talk to the one configured Viewer, only on its API paths, and only about the one configured project. A bug in it therefore cannot reach further than the project you connected.

For the full setup (minting a write-scoped token, picking the project, and exactly what does and does not sync), see Editor and Viewer together.

Next#