Diagram representation navigation ================================= This contract derives from user issues `14: Text symbol usages `_ and `17: tree-to-diagram navigation `_. Implementation and acceptance status belong to those issues. The source language and identity rules remain in ``language.rst``. Identity and membership ----------------------- A result identifies the queried subject, a diagram destination, and a specific graphical representation. A destination is a saved diagram UUID, a process or functional-chain UUID, or a scenario UUID. Saved state diagrams retain their own diagram UUID; membership in the same state machine does not make their contents interchangeable. Representation identities are node placement, port plus owner placement, edge, state row plus owner placement, process occurrence plus qualified reference path, process link, or scenario lifeline/occurrence. Opening an owner itself is a separate whole-diagram target. Names and aliases describe these identities; they are never replacement identities. Repeated occurrences remain independently selectable even when they represent the same activity or exchange. The current renderer determines membership: * Saved node, port, and edge results come from the final projection, including folds, projection-kind rules, and view filters. A stored route or two placed endpoints does not establish a visible edge. * Process results use the displayed contribution graph. A contextual preview retains its full caller path and is included only while its actual tile is present. An inactive process uses the same initial preview policy as entering its canvas. Preview adjacency has no invented relation UUID. * Scenario results use the actual scene, preserving lifeline and message occurrence identities, nested fragment operands, and repeated messages. A scenario-reference box represents its called scenario. It does not also represent the called scenario's messages or lifelines. * State action and internal-transition rows retain their relation identity. Visible named references, such as a state action's work or a transition's trigger, can target the row or edge whose label displays that reference. Label-only membership must account for the renderer's shortening policy. An arbitrary semantic reference is insufficient. A description mentioning a name, an exchange item hidden by the selected label mode, or an unexpanded callee does not automatically add a diagram result. The result count describes currently rendered representations, not all semantic dependencies. Folded, filtered, and unexpanded representations are explicitly excluded by this version; an empty result must disclose this scope and must not claim that an object is unused everywhere. Semantic dependencies remain available through Connections. Two additional representation forms remain gaps in this branch: allocation relations expressed through nesting, and persisted sequence links drawn inside qualified caller previews. These must either receive precise grouping/qualified edge targets or remain explicitly disclosed limitations; a passing direct-edge test does not establish their coverage. Interaction and lifecycle ------------------------- ``Show in diagrams`` opens one searchable destination list from the Text caret, an object's context/Actions menu, or Connections. It identifies the subject by name and alias, groups targets by destination, reports counts, and presents a bounded page. A destination then exposes its individual representations. Search matches destination names, aliases, categories, representation names, and roles. Long descriptions remain available without replacing stable identities. The Text entry point uses the exact current caret and the source-symbol service's immutable snapshot. It requires a unique, validated, included declaration whose authored identity and alias still match the accepted model. It never substitutes the previously selected tree object. Unapplied source is retained with an explicit instruction to apply it before diagram lookup. Comment, prose, ambiguous, missing, detached, and stale symbols cannot trigger a diagram jump. Every open request captures the document instance, accepted revision, and subject. Every chooser action captures that chooser's unique token. Before opening a representation, re-resolve the full subject-to-target relationship and renderer geometry. If the model or presentation changed, refresh the list and require a fresh choice. Matching names, reused aliases, or surviving endpoints cannot make a stale target current. An asynchronous source response must also match its job, source session/revision, raw interaction, active file, and caret. Lookup and reveal do not execute model commands, Apply, Revert, or Save. They do not expand persisted folds, change filters, rewrite source, or alter undo/redo. Pending edits that would be displaced prevent the jump and remain intact. Successful reveal updates only the navigation owner/page, precise selection, tool lifetime, and camera. The camera centers the target at a readable scale; fitting a huge whole diagram is not sufficient evidence of locating one object. Escape closes the chooser and restores Text focus/caret when invoked there. Verification obligations ------------------------ Independent fixtures must cover actual versus filtered edges, folded children, ports, same-name distinct identities, repeated work/message/lifeline occurrences, qualified reuse paths, opaque scenario references, state rows and label references. For each activation, compare the complete accepted Project, SourceBundle, raw buffers, revision, dirty flags, and undo/redo reachability before and after. Exercise stale document/revision/token/subject relationships and retained drafts. Native acceptance additionally checks keyboard and pointer selection, exact visible target highlight, camera behavior after the destination's first layout, empty and multi-result states, readable long Unicode names, minimum-window layout, return to editing, and representative large-model latency. Unit tests and a successful build do not by themselves establish these interaction outcomes.