Migrate frontend workflow editor from JointJS 3.5.4 to @joint/core v4

[aglinxinyuan]

Task Summary

Migrate the frontend workflow editor from jointjs@3.5.4 to @joint/core@4.2.4 (JointJS v4, the rebranded successor package).

This was surfaced while triaging the closed Dependabot PR #5064 (bump lodash 4.17.23 → 4.18.1). That bump could not complete because jointjs@3.5.4 pins lodash: ~4.17.21 (>=4.17.21 <4.18.0), which forces a second, stale lodash@4.17.23 copy to remain in frontend/yarn.lock alongside the 4.18.1 everything else uses. Every stable 3.x jointjs release (through 3.7.7) keeps that same ~4.17.21 pin — only v4 (@joint/core) drops the runtime lodash (and jQuery/Backbone) dependency entirely. So consolidating lodash to a single 4.18.1 requires the v4 migration.

Motivation

• De-duplicate lodash — removing jointjs's ~4.17.21 pin lets the tree resolve to a single lodash@4.18.1.
• Drop transitive jQuery and Backbone — v4 removed both; @types/backbone can be dropped from devDependencies.
• Modernize — v4 is ESM-first, actively maintained, and ships its own TypeScript types.

Breaking-change inventory

v3 API in use	Where	v4 status	Migration
pkg jointjs@3.5.4	all 12 importers	renamed → @joint/core@4.2.4	swap dep; import * as joint from "jointjs" → "@joint/core"
joint.shapes.devs.Model	operator + comment box base, joint-ui.service.ts	removed	re-base TexeraCustomJointElement / TexeraCustomCommentElement on dia.Element + explicit ports API
joint.shapes.devs.ModelSelectors	type, joint-ui.service.ts (×2)	removed	replace with v4 selectors / dia.Cell.Selectors type
joint.shapes.basic.Rect	workflow-editor.component.spec.ts (×4)	removed	joint.shapes.standard.Rectangle
joint.layout.DirectedGraph	autoLayoutJoint(), joint-graph-wrapper.ts	moved to @joint/layout-directed-graph@4.2.3	add dep; import from new package
SVG-string markup	operator/comment markup	v4 prefers JSON markup	convert markup; verify rendering
joint.attributes.SVGAttributes	joint-ui.service.ts (×1)	exists (path may differ)	verify type import
bundled jQuery ($)	internal paper events; 1 spec	removed	rework spec event simulation; re-verify paper pointer events
Backbone + @types/backbone@1.4.15	types only (no direct src use)	removed	drop @types/backbone

Affected files (12)

frontend/package.json                         (deps)
frontend/yarn.lock                            (regenerate → lodash dedupes to 4.18.1)
service/joint-ui/joint-ui.service.ts          (devs.Model rewrite — core)
service/joint-ui/joint-ui.service.spec.ts
service/workflow-graph/model/joint-graph-wrapper.ts          (DirectedGraph layout)
service/workflow-graph/model/joint-graph-wrapper.spec.ts
service/workflow-graph/model/workflow-action.service.ts
service/workflow-graph/model/shared-model-change-handler.ts
service/workflow-graph/model/coeditor-presence.service.ts
service/workflow-graph/model/sync-texera-model.spec.ts
service/drag-drop/drag-drop.service.ts
component/workflow-editor/workflow-editor.component.ts
component/workflow-editor/workflow-editor.component.spec.ts
component/workflow-editor/mini-map/mini-map.component.ts

Plan / checklist

• Swap jointjs → @joint/core@4.2.4; add @joint/layout-directed-graph@4.2.3; drop @types/backbone; regenerate lockfile with vendored Yarn 4.14.1.
• Update all import * as joint from "jointjs" → "@joint/core" (12 files).
• Rewrite TexeraCustomJointElement / TexeraCustomCommentElement off devs.Model onto dia.Element + ports API; convert SVG-string markup to v4 markup.
• Re-point joint.layout.DirectedGraph.layout(...) to @joint/layout-directed-graph.
• Replace shapes.basic.Rect / devs.ModelSelectors usages in specs and service.
• Audit other v4 API changes (paper options, setTheme, event signatures, highlighters, linkTools, ToolsView).
• Type-check + unit tests green.
• Manual visual QA of the workflow editor (below).

Risks & required QA

This touches the core rendering of the workflow canvas, so type-checking alone is insufficient. Manual QA must confirm:
operator boxes render with correct size/icons/labels · input/output ports (incl. dynamic add/remove port buttons) · link drawing & connection validation · delete/chat buttons & link tools · highlighters/selection · drag-drop from the operator panel · auto-layout · mini-map · co-editor presence rendering.

Task Type

Refactor / Cleanup · DevOps / Deployment / CI (dependency upgrade)

[aglinxinyuan]

Migration recipe — ground-truthed against @joint/core v4

Captured while scoping the work. The verification harness and the exact v4 API deltas are confirmed below so this is execution-ready.

Verification harness (confirmed working)

Suite	Command	Baseline result (jointjs 3.5.4)
jsdom joint specs	npx ng test --include="**/joint-ui.service.spec.ts" (also joint-graph-wrapper.spec, sync-texera-model.spec)	✅ 56 tests pass
browser spec (real Chromium)	npx ng run gui:test-browser (Playwright, runs workflow-editor.component.spec.ts)	to baseline before migrating
type-check	npx ng build (default config)	green on main

Note: jsdom lacks HTMLCanvasElement.getContext, so JointUIService.getMeasureContext() returns null and the name-width measurement falls back to an approximation. Pre-existing, harmless, unrelated to v4.

Confirmed v4 API deltas

1. ref* attributes → calc() native attributes (used heavily in operator markup, port styles, comment attrs):

v3	v4
refX / ref-x	x: 'calc(w)' (fraction → calc(0.5*w)) or numeric
refY / ref-y	y: 'calc(h)'
refWidth: '100%'	width: 'calc(w)'
refHeight: '100%'	height: 'calc(h)'
x-alignment	textAnchor (start/middle/end)
y-alignment	textVerticalAnchor (top/middle/bottom)
ref: 'rect.body'	ref: 'rect.body' still supported; positioning now via calc() relative to ref bbox

2. shapes.devs.Model removed → dia.Element.define() with explicit ports config. The in/out port groups that devs.Model provided by default must be declared on the element (ports.groups.in / ports.groups.out with position + port markup/attrs). Reference implementation: joint-core demo/devs. Affects TexeraCustomJointElement, TexeraCustomCommentElement, and the as joint.shapes.devs.Model casts + devs.ModelSelectors types in joint-ui.service.ts.

3. dia.Link markup/tools rewrite — .connection, .connection-wrap, .marker-source, .marker-target, .marker-arrowheads, and toolMarkup no longer drive rendering/interactivity. Migrate getDefaultLinkCell() to shapes.standard.Link and attach tools dynamically:

const lv = paper.findViewByModel(link);
lv.addTools(new linkTools.Remove({ ... }));   // replaces the toolMarkup "tool-remove"

Custom arrowheads (sourceOperatorHandle/targetOperatorHandle) move to attrs.line.sourceMarker/targetMarker.

4. Port markup — .port-body / .port-label styling moves to native attributes; verify against v4 port markup defaults.

5. String SVG markup → JSON markup — recommended util.svg\<rect @selector="body"/>`withattrs: { body: {...} }. Class selectors still resolve, but ref*` positioning inside them must be converted (see #1).

Build wiring (besides deps)

• angular.json styles[]: repoint node_modules/jointjs/css/{layout,themes/material,themes/default}.css → the CSS shipped by @joint/core (verify file layout in the installed package).
• allowedCommonJsDependencies already lists dagre, graphlib (needed by @joint/layout-directed-graph).
• deps: jointjs@3.5.4 → @joint/core@4.2.4; add @joint/layout-directed-graph@4.2.3; drop @types/backbone@1.4.15.

Effort

This is a multi-day rewrite of behavior-critical canvas internals (operator/comment element markup + ports, link rendering + tools, every ref* attribute), not a mechanical bump. Type-check-green is necessary but not sufficient — the ref*/markup/link changes fail at render time, so each milestone needs the editor running for visual QA (operators, ports, dynamic add/remove-port buttons, link draw + validation, delete/chat tools, highlighters, drag-drop, auto-layout, mini-map).