Reference

Comments & feedback

Comments attach to a specific element, on a specific state, within a specific snapshot or the live project. They support replies, resolution, and email or in-app notification to every thread participant.

Leaving a comment

With an element selected, click the Comment button in the toolbar, or press the comment shortcut. The cursor enters comment- placement mode; clicking anywhere on the element drops a pin and opens a thread composer.

comment-button-toolbar.png
comment-placement-mode.png

Comment composers support plain text. Cmd+Enter submits; Esc closes the composer without submitting.

comment-thread-composer.png

What a comment is attached to

A comment carries three pointers:

  • Target type — project, state, or element. Element comments are by far the most common.
  • State ID — which state the comment lives on.
  • Element pid — the persistent ID of the element the comment points at. Element pids survive JSX reformats and edits that leave the element in place.

Comments also carry a snapshot ID (or null for comments on the live project). Comments attached to a snapshot stay pointed at whatever the element looked like in that snapshot, even if the live project has moved on.

Threads, replies, and resolution

Each comment is the root of a thread. Replies are stored as child comments under the root; the UI shows them inline. Clicking Resolve on a thread marks it (and every reply) as resolved; resolved threads are hidden by default but can be surfaced from the Comments panel.

Unresolving restores a thread to the active list. Resolution is reversible — no state is lost.

The Comments panel

The Comments panel (open it from the dock) lists every thread in the current project scoped to the current snapshot (or the live project). Each row shows the thread author, the first comment, the reply count, and the resolve status.

comments-tab-list.png

Clicking a thread scrolls the canvas to the commented element and opens the thread inline. Threads on elements that no longer exist are shown as orphaned and can be read but not replied to.

comment-thread-inline.png

Orphaned comments

If the element a comment points at is deleted, or if its pid is lost through a JSX rewrite that does not preserve the pid, the comment becomes orphaned. Orphans remain in the Comments panel for reference but cannot be re-anchored.

orphaned-comment-badge.png

Avoiding orphans on an evolving project is mostly a matter of taking snapshots at review points (see Snapshots & version history). A snapshot freezes the element tree, so comments on that snapshot remain anchored regardless of what the live project does.

Notifications

Every reply to a thread notifies every prior participant, and every root comment notifies every workspace owner and editor. Notifications are delivered through two channels: the in-app bell (always on) and email (per-user toggle).

Workspace viewers never receive comment notifications — they are expected to be read-only stakeholders, not active collaborators. See Notifications & email for the full delivery rules and how to opt out of email.

Who can comment

Workspace owners and editors can post comments and replies. Viewers can read every thread but can't post — they're treated as read-only stakeholders. If you want a reviewer to leave feedback, invite them as an editor.

Both the snapshot and the comments live inside the workspace, so reviewers need to be invited before they can open the project at all.