#6108 - Relation support for the Apache Annotator HTML editor mode

[reckart]

What's in the PR

• Add relation rendering to the Apache Annotator HTML editor: relations with both endpoints inside the effect-range band are drawn as full arcs, band-crossing relations as directional up/down stubs whose clickable tip jumps to the far endpoint, and pass-through relations are not drawn (RelationVisualizer)
• Add relation-creation by dragging from a span: a drag state machine (IDLE -> ARMED -> DRAGGING -> COMMIT/CANCEL) with window-level capture listeners so a release outside the iframe still resolves and does not leak into span creation (RelationDragController)
• Add hover-surfaced relation-creation "grips": a small drag affordance anchored above a hovered span's start that proxies the span without competing with the native text-selection gesture (RelationGripLayer)
• Add a target-disambiguation popup ("relation-target" mode) so a relation drag ending on overlapping spans lets the user pick which span is the target; dismissing cancels the relation (ApacheAnnotatorSelector.pickRelationTarget)
• Add a pooled per-color SVG arrowhead marker registry plus an svgEl element-creation helper (ArrowMarkerPool)
• Add a relation-labels preference and toolbar toggle: labels shown at rest vs. on hover, applied as a pure CSS mode flip without re-rendering
• Add line-spacing presets (low/mid/high/xhigh) with toolbar S/M/L/X buttons, applied as a class on the editor root; cap the arc bow scale so xhigh stacking matches the high preset
• Re-band the relation overlay around the current viewport on manual scroll, coalesced to one redraw per frame
• Fix overlay sizing so it collapses to zero before measuring content extent, preventing scrolling past the text into a blank region with no arcs (Relation support for the Apache Annotator HTML editor mode #6108)
• Add showRelationLabels and lineSpacing to the editor user-preferences schema
• Document ViewportTracker's visible range as a superset (recomputed only when elements are added), and remove dead display-style probing code
• Add distinctHighlightStack and fanAngle helpers (Utilities)
• Remove the invalid bugs URL from inception-assistant-ui package.json

How to test manually

• Try using relations in the Apache Annotator HTML editor

Automatic testing

• PR includes unit tests

Documentation

• PR updates documentation

[Copilot]

Pull request overview

Note

Copilot couldn't run its full agentic review because no GitHub Actions runner was available. Make sure your repository has a runner available to run Copilot's review, or add a copilot-setup-steps.yml file specifying one with the runs-on attribute. See the docs for more details.

Adds relation visualization and creation support to the Apache Annotator HTML editor mode, including interactive overlays (arcs, stubs, grips), preference-driven display options, and scroll/viewport optimizations.

Changes:

• Introduces relation rendering (arcs/stubs) and relation-creation interactions (grips + drag controller + target disambiguation popup).
• Adds user preferences and toolbar controls for relation label visibility and line-spacing presets.
• Improves viewport/range documentation and fixes overlay sizing/scroll-extent behavior.

Reviewed changes

Copilot reviewed 16 out of 16 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
inception/inception-js-api/src/main/ts/src/util/ViewportTracker.ts	Documents currentRange semantics (superset) and removes dead debug code.
inception/inception-html-apache-annotator-editor/src/main/ts/src/apache-annotator/Utilities.ts	Adds helpers for distinct highlight stacks and fan angle calculations.
inception/inception-html-apache-annotator-editor/src/main/ts/src/apache-annotator/RelationVisualizer.ts	New SVG-based relation overlay renderer (arcs/stubs), including clustering and interaction.
inception/inception-html-apache-annotator-editor/src/main/ts/src/apache-annotator/RelationVisualizer.scss	Styling for relation overlays, labels, hit targets, and drag rubber-band.
inception/inception-html-apache-annotator-editor/src/main/ts/src/apache-annotator/RelationGripLayer.ts	New hover-driven grip overlay for relation creation.
inception/inception-html-apache-annotator-editor/src/main/ts/src/apache-annotator/RelationGripLayer.scss	Styling for grips and grip-driven highlight echo.
inception/inception-html-apache-annotator-editor/src/main/ts/src/apache-annotator/RelationDragController.ts	New drag state machine for creating relations, including Escape cancel and disambiguation handoff.
inception/inception-html-apache-annotator-editor/src/main/ts/src/apache-annotator/ArrowMarkerPool.ts	New per-color SVG arrowhead marker pooling and SVG element helper.
inception/inception-html-apache-annotator-editor/src/main/ts/src/apache-annotator/ApacheAnnotatorVisualizer.svelte.ts	Integrates relation renderer/grips/drag controller and adds scroll re-banding + rerender helpers.
inception/inception-html-apache-annotator-editor/src/main/ts/src/apache-annotator/ApacheAnnotatorToolbar.svelte	Adds toolbar toggles for relation labels and line spacing; updates preference save behavior.
inception/inception-html-apache-annotator-editor/src/main/ts/src/apache-annotator/ApacheAnnotatorState.svelte.ts	Adds defaults/types for new preferences (lineSpacing, showRelationLabels).
inception/inception-html-apache-annotator-editor/src/main/ts/src/apache-annotator/ApacheAnnotatorSelector.ts	Adds relation-target popup mode and pick callback plumbing.
inception/inception-html-apache-annotator-editor/src/main/ts/src/apache-annotator/ApacheAnnotatorEditor.ts	Loads/applies new preferences; wires toolbar events for line-spacing rerender and label-mode refresh.
inception/inception-html-apache-annotator-editor/src/main/ts/src/apache-annotator/ApacheAnnotatorEditor.scss	Adds line-spacing preset classes.
inception/inception-html-apache-annotator-editor/src/main/java/...UserPreferences.schema.json	Extends preferences schema with showRelationLabels and lineSpacing.
inception/inception-assistant-ui/src/main/ts_template/package.json	Removes invalid bugs.url.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.