Skip to content

feat(frontend): anchor comment boxes to operators - #9278

Open
sshiv012 wants to merge 7 commits into
apache:mainfrom
sshiv012:feat/anchored-comments
Open

sshiv012 wants to merge 7 commits into
apache:mainfrom
sshiv012:feat/anchored-comments

Conversation

@sshiv012

@sshiv012 sshiv012 commented Nov 4, 2026 •

Copy link
Copy Markdown
Contributor

What changes were proposed in this PR?

Comments on the canvas can now be anchored to an operator, the way a Google Docs comment is tied to its text. An anchored comment moves with its operator, whether you drag the operator or run auto-layout. Comments that aren't anchored still float freely, as before.

floating:  operator moves  ->  comment stays where it was
anchored:  operator moves  ->  comment moves with it, same offset
How What happens
Right-click an operator, then add comment A comment is created above the operator's top-right corner, clear of its buttons, already anchored to it
Select comments and one operator, right-click, then anchor to operator The comments anchor to that operator. Offered only when every selected comment is within 160px of it
Select anchored comments, right-click, then detach from operator They float again
Drag a comment onto an operator The operator is outlined while you drag, and the comment anchors on drop if it is within 40px
Drag an anchored comment more than 160px away It detaches and floats
  • An anchored comment has a dashed blue outline and a dashed line to its operator.
  • Auto-layout keeps each anchored comment beside its operator, evenly spaced.
  • Copy/paste keeps the anchor when the operator is copied too. A comment copied without its operator pastes as floating.
  • Dragging several selected comments anchors or detaches each one by where it lands, in one undo step.
  • Anchors stay in sync between co-editors, and anchor changes (including undo and redo) are autosaved.
  • Undoing an operator drag also puts its anchored comments back.
  • Fixes an upstream bug where a comment's first move did not reach co-editors: the first move enters the shared position map as an add, which was ignored.
  • Fixes calculateTopLeftOperatorPosition leaving joint-command listening switched off on an empty workflow: it now returns before turning listening off.

Screenshots (before = main, after = this PR)

Before After
Drag an operator before-1-drag-operator after-1-drag-operator
Auto-layout before-2-auto-layout after-2-auto-layout
Right-click an operator before-context-menu after-context-menu

Compatibility. The anchor is a single optional field, anchoredOperatorID, on each comment box in the workflow content. Nothing outside the frontend reads comment boxes, so no migration is needed.

Case Result
A workflow saved before this PR Loads with every comment floating, unchanged
This PR's workflow opened in an older build Comments float. The older build keeps the field when it saves, so the anchor comes back after upgrading
An anchor whose operator is gone (for example, deleted by an older client) Drawn and treated as floating

Export/import round trip between this branch and main:

migration-round-trip

Any related issues, documentation, discussions?

Closes #9274

How was this PR tested?

Unit tests, written before each change:

  • workflow-action.service.spec.ts:
    • anchoring, detaching and undo;
    • auto-layout spacing;
    • reload;
    • the connector line;
    • the snap and detach limits (40/41px and 160/161px);
    • tie-breaks between equally near operators;
    • anchors to a missing operator;
    • a live second editor whose Y.js document is linked to the first, checking that both converge.
  • workflow-editor.component.spec.ts: drags driven by the paper's real pointer events, covering a single comment, several selected comments, dragging with an operator selected, and a click that doesn't move.
  • operator-menu.service.spec.ts: paste with and without the anchored operator.
  • Context menu: the "add comment", "anchor to operator" and "detach from operator" items, including when each is offered.

All frontend tests pass, and type-check, prettier and eslint are clean.

Manual check in Chrome, on a local dev stack:

  1. Right-click an operator, choose add comment, and confirm the comment appears with an outline and a line to the operator.
  2. Drag the operator and confirm the comment follows. Run auto-layout and confirm it stays beside the operator.
  3. Drag the comment far away and confirm it detaches. Drag it back onto the operator and confirm it re-anchors.
  4. Shift-select two anchored comments and drag them away: both detach.
  5. Shift-select a comment and an operator, right-click, choose anchor to operator; then select the comment alone, right-click, choose detach from operator.
  6. Drag an operator with an anchored comment, then press Ctrl+Z: both return.
  7. Export the workflow and upload it into a main build (it loads, with comments floating). Edit it there, export it again, and upload it back into this branch: the anchor returns.

Was this PR authored or co-authored using generative AI tooling?

Generated-by: Claude Code (Claude Opus 5.5)

🤖 Generated with Claude Code

sshiv012 and others added 4 commits November 3, 2026 17:07
A comment box can now be anchored to an operator from the canvas
context menu ("anchor to operator" / "detach from operator"). Anchored
comments follow the operator when it is dragged and keep their offset
through auto-layout, which sizes each operator together with its
anchored comments so nothing overlaps. Anchored comments get a dashed
blue outline; unanchored comments float as before. Deleting an
operator detaches its comments instead of deleting them.

Also fixes:
- auto-layout never persisted comment box positions, so they jumped
  back on reload;
- dragging a selection persisted selected comments' positions before
  they moved;
- calculateTopLeftOperatorPosition() returned early on an empty
  workflow with joint-command listening still off, so every later drag
  on a new workflow went unsynced until reload.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Anchoring no longer needs a multi-selection and a context-menu item:

- Dragging a comment box next to an operator (within 40px) anchors it;
  the operator it will anchor to is outlined while dragging. Dropping
  an anchored box more than 160px from its operator detaches it; in
  between, a nudge keeps the anchor.
- "add comment" on an operator's context menu adds a comment box beside
  it, already anchored, as one undoable action.
- An anchored comment box draws a dashed connector line to the nearest
  edge of its operator, redrawn whenever either moves, including moves
  from auto-layout and co-editors.

The "anchor to operator" / "detach from operator" menu items stay as a
fallback.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…editing

- Paste re-anchors a comment to the pasted copy of its operator at the
  same offset, and pastes it floating when the operator wasn't copied.
- Dragging several selected comment boxes anchors or detaches each one
  by where it lands, in a single undo step.
- Apply "add" events from the shared position map so a comment box's
  first move reaches co-editors.
- Add pointer-event, paste, co-editor convergence, boundary and
  tie-break tests.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
An editor that predates anchoring can delete an operator without
detaching its comment boxes. Style the outline by whether the anchored
operator is on the canvas, and refresh it when an operator is removed.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@github-actions github-actions Bot added feature frontend Changes related to the frontend GUI labels Nov 4, 2026
@github-actions

github-actions Bot commented Nov 4, 2026 •

Copy link
Copy Markdown
Contributor

Automated Reviewer Suggestions

Based on the git blame history of the changed files, we recommend the following reviewers:

  • Contributors with relevant context: @kz930, @aglinxinyuan, @yangzhang75
    You can notify them by mentioning @kz930, @aglinxinyuan, @yangzhang75 in a comment.

@codecov-commenter

codecov-commenter commented Nov 4, 2026 •

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 97.20930% with 6 lines in your changes missing coverage. Please review.
✅ Project coverage is 91.59%. Comparing base (f020980) to head (cb2f856).

Files with missing lines Patch % Lines
...ontext-menu/context-menu/context-menu.component.ts 75.00% 3 Missing and 3 partials ⚠️
Additional details and impacted files
@@             Coverage Diff              @@
##               main    #9278      +/-   ##
============================================
+ Coverage     91.56%   91.59%   +0.03%     
+ Complexity     5157     5132      -25     
============================================
  Files          1300     1296       -4     
  Lines         58092    58176      +84     
  Branches       7615     7634      +19     
============================================
+ Hits          53194    53289      +95     
+ Misses         2959     2948      -11     
  Partials       1939     1939              
Flag Coverage Δ *Carryforward flag
access-control-service 77.44% <ø> (ø) Carriedforward from ab9ec50
agent-service 99.56% <ø> (ø) Carriedforward from ab9ec50
amber 85.42% <ø> (-0.01%) ⬇️ Carriedforward from ab9ec50
computing-unit-managing-service 63.88% <ø> (ø) Carriedforward from ab9ec50
config-service 87.50% <ø> (ø) Carriedforward from ab9ec50
file-service 82.16% <ø> (ø) Carriedforward from ab9ec50
frontend 96.46% <97.20%> (+<0.01%) ⬆️
notebook-migration-service 83.77% <ø> (ø) Carriedforward from ab9ec50
pyamber 98.38% <ø> (ø) Carriedforward from ab9ec50
result-service ?
workflow-compiling-service 78.30% <ø> (ø) Carriedforward from ab9ec50

*This pull request uses carry forward flags. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

@sshiv012

sshiv012 commented Nov 4, 2026

Copy link
Copy Markdown
Contributor Author

/request-review @bobbai00

@github-actions
github-actions Bot requested a review from bobbai00 November 4, 2026 21:04

@bobbai00 bobbai00 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔴 1 must-fix · 2 advisory · 1 polish: a careful, well-tested feature; undoing an operator drag strands its anchored comments.

Correctness (1)

  • shared-model-change-handler.ts:243: undoing an operator drag leaves never-moved anchored comments behind (must-fix, see inline)

Design & architecture (1)

  • context-menu.component.ts:205: a menu anchor can create a state the drop rule undoes (advisory, see inline)

Conventions (1)

  • context-menu.component.html:176: description omits the anchor/detach menu items and the top-left listening fix (advisory, see inline)

Polish: 1 quick touch-up (see inline comments).

Verification trace

Ran a throwaway spec against the PR head: add an operator at (100,100) and a comment box at (170,100), anchor it, select the operator, drag it to (300,250), then undo. Result: the operator is back at (100,100), the box stays at (370,250) on the canvas, and its commentBoxPosition reads (170,100). A control box that had been moved once before the drag (so its position key already existed) returns to (170,100).

@bobbai00 bobbai00 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔴 0 resolved · 4 open · 3 new (3 new = 0 newly introduced · 3 late catches)

The three new findings are in code that was already there in the last round. I missed them then. The four threads from Nov 7 are still open and are not repeated here.

Design & architecture (1)

  • shared-model-change-handler.ts:519: an anchor or detach from the menu, and undo of an anchor, is never autosaved (advisory, see inline)

Correctness (2)

  • workflow-action.service.ts:537: "add comment" lands on the operator's delete and chat buttons (must-fix, see inline)
  • workflow-editor.component.ts:1314: a drop also settles selected comments that did not move (must-fix, see inline)
Verification trace

Three throwaway specs against the PR head. (1) Chromium, through the test-browser target: operator at (200, 200), the right-click events, then addCommentBoxToOperator. The delete button renders at (260, 180) 24x24, the chat button at (285, 180) 20x20 and the comment body at (272, 184) 32x32, with both buttons visible. (2) Editor spec: two selected comments, shift-press one and drag it away. The other one never moves, sits 10 px from the operator, and ends up anchored. (3) Service spec counting workflowChanged() emissions: adding a comment 1, anchor 0, detach 0, undo of an anchor 0, dragging a comment 1.

sshiv012 and others added 2 commits November 18, 2026 21:27
- Undoing a comment box's first move (e.g. an operator drag that took an
  anchored comment along) returns it to its saved position.
- "anchor to operator" is offered only for comment boxes within the
  detach distance, so the next drop does not detach them again.
- "add comment" places the new box above the operator's delete and chat
  buttons instead of on top of them.
- A drop settles only the comment boxes the drag actually moved.
- Anchor changes, including undo and redo, now count as workflow changes,
  so they are autosaved.
- Correct the auto-layout comment on what comment offsets are relative to.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@sshiv012

Copy link
Copy Markdown
Contributor Author

/request-review @bobbai00

@github-actions
github-actions Bot requested a review from bobbai00 November 19, 2026 07:17

@bobbai00 bobbai00 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔴 7 resolved · 0 open · 5 new (5 new = 1 newly introduced · 4 late catches)

All seven earlier threads are fixed and verified, so I left them closed. The four late catches were in code earlier rounds already had; I missed them.

Design & architecture (1)

  • joint-graph-wrapper.ts:613: the agent's copy of this layout still leaves anchored comments behind (must-fix, see inline)

Correctness (2)

  • workflow-editor.component.ts:1574: a shift-dragged comment's anchor is saved but its move is not (must-fix, see inline)
  • workflow-action.service.ts:518: a nudge detaches a comment that is already out of reach (must-fix, see inline)

Simplifications (1)

  • workflow-action.service.ts:484: getAllOperatorIDs() is enough on this per-pointermove path (advisory, see inline)

Polish: 1 quick touch-up (see inline comments).

Verification trace

Two throwaway specs in the PR's "dragging comment boxes onto operators" block, run against the PR head. (1) A selected comment shift-dragged from (400, 400) to beside the operator ends anchored, with no elementPositionMap entry and a saved position of (400, 400). (2) A comment anchored at (170, 100), dragged 300px down together with another operator, ends 240px away and still anchored; a 5px solo drag then detaches it. The agent finding comes from reading the code, not from a run.

*
* @param anchoredCommentBoxIDs the IDs of the comment boxes anchored to each operator, by operator ID
*/
public autoLayoutJoint(anchoredCommentBoxIDs: ReadonlyMap<string, readonly string[]> = new Map()): void {

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Must fix:

The agent has its own copy of this layout, and it still moves operators without their anchored comments. autoLayoutWorkflow runs after every agent add_operator, and the canvas then reloads the result (agent-chat.component.ts:287). Each anchored comment comes back at its old spot, still anchored, with its connector stretched to the moved operator: the "comment stays behind" case from #9274. I'd shift anchored boxes by their operator's displacement there (its CommentBox type needs the saved shape); a linked follow-up also works, but then drop "Nothing outside the frontend reads comment boxes" from the description.

drag = undefined;
return;
}
const commentBoxIDs = movedCommentBoxIDs();

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Must fix:

A shift-dragged selected comment gets its anchor saved but not its move. The shift-press deselects it (line 1170), and handleJointElementDrag only syncs selected elements (workflow-action.service.ts:1344), but this drop still settles it. In a probe, a box shift-dragged from (400, 400) to the operator came out anchored while its saved position stayed (400, 400). Co-editors and the next load then see it anchored 340px away, so I'd settle only the boxes still selected at drop.

} else if (
anchoredOperatorID !== undefined &&
(!this.texeraGraph.hasOperator(anchoredOperatorID) ||
distanceBetween(this.getElementBBox(commentBoxID), this.getElementBBox(anchoredOperatorID)) >

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Must fix:

This also detaches a comment that was already beyond COMMENT_BOX_DETACH_DISTANCE when the drag began, so a 5px nudge detaches it, against "a small nudge changes nothing" at line 505. Comments get that far without being dragged away: dragged along with another operator, or moved by the agent's layout or an older build. In a probe, a 5px nudge detached a comment that a group drag had left 240px away, the case you called unintended in r4500466032. I'd skip the detach for boxes that were already out of reach at pointerdown.

Comment on lines +484 to +490
.getAllOperators()
.map(operator => {
const operatorBBox = this.getElementBBox(operator.operatorID);
return {
operatorID: operator.operatorID,
distance: distanceBetween(commentBoxBBox, operatorBBox),
isAnchor: operator.operatorID === anchoredOperatorID,

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Advisory:

This runs on every pointermove, and getAllOperators() builds each operator's JSON just to read its ID. getAllOperatorIDs() exists for per-update paths like this. In a yjs micro-benchmark with 300 operators it took 0.01 ms versus 0.6 ms.

Suggested change
.getAllOperators()
.map(operator => {
const operatorBBox = this.getElementBBox(operator.operatorID);
return {
operatorID: operator.operatorID,
distance: distanceBetween(commentBoxBBox, operatorBBox),
isAnchor: operator.operatorID === anchoredOperatorID,
.getAllOperatorIDs()
.map(operatorID => {
const operatorBBox = this.getElementBBox(operatorID);
return {
operatorID,
distance: distanceBetween(commentBoxBBox, operatorBBox),
isAnchor: operatorID === anchoredOperatorID,

});

it("leaves the anchor alone on a click that does not move the comment box", () => {
// Anchored far from its operator (as the anchor menu item allows), then only clicked.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Polish:

The menu item now requires the comment to be within reach (canAnchorCommentBoxes), so only anchorCommentBox can anchor from here.

Suggested change
// Anchored far from its operator (as the anchor menu item allows), then only clicked.
// Anchored far from its operator (anchorCommentBox sets no distance limit), then only clicked.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

feature frontend Changes related to the frontend GUI

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Allow comments to be anchored to operators on the canvas

3 participants