8.0 KiB
Small-diagram reading and editing
Experiment contract for issue 38, derived from the user's requirement for intuitive graphical modeling with low cognitive load in PROJECT_GOAL.md. This is a bounded investigation, not acceptance of the application or a routing replacement. Live ownership and dependencies remain in the issue.
Evidence and uncertainty
The user's image contains eight cards and crowded connection corridors despite substantial free space. A selected path is already highlighted. Correctly selecting an edge therefore cannot, by itself, establish that the reported usability problem is solved.
All displayed names occur in the released examples/release1 teaching project, but its five saved views do not contain that eight-card arrangement. The original projection, layer identities, positions and authored route overrides are unavailable. Any reconstruction must be labeled representative, with its assumptions stated. It must not be called the user's exact model.
The existing router already penalizes crossings/shared segments and avoids some label collisions. The editor already highlights selected paths/labels and provides route editing. The investigation must compare actual workflows against these existing capabilities, rather than advertise their presence as a new solution.
An independently audited historical full-scene witness from the published #32 corpus has ten nodes and fourteen real exchanges. Two edges share a run beyond a common port lead, without node, label or port occlusion at the sampled point. Both have distinct labels and unshared segments elsewhere. This establishes an ambiguous target at that point, not a globally inaccessible relation. Regeneration and input through the current application remain necessary; recorded geometry and a picking-helper test are insufficient.
The probe, fixtures and independent source review make those assumptions executable. Review corrected an initial port-hit radius assumption, a five-edge omission from the representative answer key and an incomplete warning baseline. Current-router execution passes five tests and reproduces the historical overlap without changing the model. The mixed-layer eight-card view has twelve actual relationships and uses Traceability, which flattens visual parents; it is not evidence for nested/folded controls. Native reading/editing workflows remain a separate gate.
Alternatives and decision boundary
Criteria are correct relationship identity, useful direct editing, readable paths and labels at working scale, preserved authored intent, predictable latency, and maintainable scope.
| Candidate | Useful outcome | Reason to reject or defer |
|---|---|---|
| Explicit choice at ambiguous connection hits | Deliberately target an overlapping edge without moving the model | Ordinary clicks become cumbersome; selected-edge bend/label editing is intercepted; it merely prints answers while the diagram remains unreadable |
| Local route/label separation | Trace connections without confusing shared runs or detached labels | Authored pins/ports change, unrelated routes regress, occupied area makes Fit unreadable, or expensive rerouting harms interaction |
| Existing focused views | Answer a scoped engineering question with fewer unrelated lines | Hides a required relation or substitutes filtering for the ability to edit the complete small view |
| Selected-label association cue | Associate a displaced label with its highlighted edge | Adds visual noise, conceals nearby content, or fails to address the demonstrated tracing errors |
No implementation candidate is accepted yet. First perform a complete-scene identify/select/repair/undo task and a create-connection task. If targetability is already adequate but tracing fails, prioritize association/separation evidence over additional selection machinery. Any narrow improvement leaves the wider readability gate open until measured directly.
Capella supports local label alignment/reset and a selected edge-to-label attachment cue (official layout guide). Sirius distinguishes crossing jump marks from label attachment links (official diagram guide). These provide comparable local repair tools; neither establishes that a chooser or jump mark solves long coincident paths in this application.
Evaluator
Freeze fixture bytes, source/build, semantic IDs and endpoint answer key, projection, authored routes, camera/window size and an untouched sentinel view before the run. Preserve failed attempts. Include disjoint, crossing, coincident/opposed, near-coincident, shared-endpoint, long/identical-label, fixed-port and nested/folded controls. Do not silently simplify a scene until its failure disappears.
- Read: trace requested relations and identify their endpoints in the complete diagram before showing an answer-bearing Inspector/chooser. Record wrong turns, ambiguous labels/arrowheads, time and recovery actions. Keep this separate from lookup accuracy.
- Select: deliberately reach each competing actual relation at the ambiguous location. Check positive controls at its unique label/unshared segment. Ordinary one-target points stay direct. Selection and cancellation preserve model, history, view and layer. Exercise left click, context targeting and group admission independently.
- Draw: create an intended valid relationship in the populated scene, then identify and edit the new connection. Check refused endpoints and cancellation with no unintended relation or history transaction.
- Repair: move one label, add/move/remove a bend and adjust an eligible attachment. Compare the complete Project against independently declared changes. Semantic endpoints, port ownership, other authored routes and sentinel views remain exact. A gesture commits once; Undo/Redo and save/reopen recover exact authored state.
- Recover: Escape, Help, focus departure, view/projection changes and stale queued input must not commit unintended geometry or retain a held gesture. Failed source/model validation preserves the prior state and redo.
- Measure: report shared-run length per distinct edge pair, nonincident contacts, crossings, node penetrations, label/node/stroke overlap, label association distance, occupied area, Fit scale and action latency separately. Include screen-space near overlaps; world-coordinate separation alone can remain unreadable. Do not hide regressions in one weighted score.
The router deliberately freezes other edges during a route preview, then allows automatic paths/labels to settle on commit. Preserve semantic and authored-field equality; record and assess that visual settlement instead of assuming whole-scene preview equality. Evaluate translation and UUID variants so a favorable identity/order does not become the claimed algorithmic result.
Implementation boundaries
Ports, nodes, selected attachments/bends/labels and group selection can intercept input before ordinary edge picking. A helper-only change does not cover the production workflow. Any candidates must deduplicate by semantic edge identity, distinguish semantic endpoints from folded visual endpoints, retain captured document/diagram/revision validation, and remain observational until an explicit model or geometry edit.
The existing selected-edge tie preference supports direct dragging; do not replace it with unconditional cycling. A transient ambiguity preview must not create a bend or apply a pending property draft. Coordinate contextual selection with #43 and performance with #44. This investigation does not resume the paused #32 planner or absorb the separate #40 allocation-drag and #41 palette contributions.