Publish in-progress navigation source and independent canvas reviews

docs/diagram-navigation.rst

@@ -0,0 +1,106 @@
+Diagram representation navigation
+=================================
+
+This contract derives from user issues `14: Text symbol usages
+<http://217.177.34.108:3000/sorokin.oleg.edu/ARCADIA-Studio/issues/14>`_
+and `17: tree-to-diagram navigation
+<http://217.177.34.108:3000/sorokin.oleg.edu/ARCADIA-Studio/issues/17>`_.
+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.

docs/language.html

@@ -2642,6 +2642,23 @@ trace links, occurrence identity, comments and file ownership. Each open file
 retains its own unapplied draft across file navigation. Located lint diagnostics
 refer to the raw draft bytes rather than an identity-stabilized intermediate.
 Property editing MUST NOT silently discard a pending source draft.</p>
+<p>In Textual model, place the caret on a declaration alias or an <span class="docutils literal">&#64;reference</span>
+and choose <strong>Definition</strong> (<span class="docutils literal">F12</span>) or <strong>References</strong> (<span class="docutils literal">Shift+F12</span>).
+<strong>Back</strong> (<span class="docutils literal">Alt+Left</span>) returns to the previous source location in this
+workspace. These shortcuts act while the source editor has focus; the Text
+toolbar also exposes the actions. If the previous draft changed, Back restores
+its current cursor rather than reusing an obsolete selection.</p>
+<p>Symbol navigation reads bounded snapshots of the currently loaded source
+drafts. It does not apply drafts or load missing included files. The results
+identify partial scope, draft evidence, detached or unverified files, alias
+ambiguity and authored-ID collisions. Draft, detached and ambiguous definition
+candidates require an explicit row choice. References are lexical uses of an
+alias, not a list of resolved typed relationships; comments and strings are
+excluded. Declaration and use counts include any rows omitted by the result
+limits. If sources change, stale rows cannot navigate: run the query again.
+Navigation MUST preserve the accepted model and every source draft, and select
+locations in the original UTF-8 bytes. Displayed locations use one-based lines
+and UTF-8 byte columns.</p>
 <p>Changing a graphical UUID must atomically update map keys and every reference.
 Alias changes preserve UUID identity. Deletion must account for owned elements,
 incident relationships, ordered occurrences, and diagram placements without

docs/language.rst

@@ -2064,6 +2064,25 @@ retains its own unapplied draft across file navigation. Located lint diagnostics
 refer to the raw draft bytes rather than an identity-stabilized intermediate.
 Property editing MUST NOT silently discard a pending source draft.
 
+In Textual model, place the caret on a declaration alias or an ``@reference``
+and choose **Definition** (``F12``) or **References** (``Shift+F12``).
+**Back** (``Alt+Left``) returns to the previous source location in this
+workspace. These shortcuts act while the source editor has focus; the Text
+toolbar also exposes the actions. If the previous draft changed, Back restores
+its current cursor rather than reusing an obsolete selection.
+
+Symbol navigation reads bounded snapshots of the currently loaded source
+drafts. It does not apply drafts or load missing included files. The results
+identify partial scope, draft evidence, detached or unverified files, alias
+ambiguity and authored-ID collisions. Draft, detached and ambiguous definition
+candidates require an explicit row choice. References are lexical uses of an
+alias, not a list of resolved typed relationships; comments and strings are
+excluded. Declaration and use counts include any rows omitted by the result
+limits. If sources change, stale rows cannot navigate: run the query again.
+Navigation MUST preserve the accepted model and every source draft, and select
+locations in the original UTF-8 bytes. Displayed locations use one-based lines
+and UTF-8 byte columns.
+
 Changing a graphical UUID must atomically update map keys and every reference.
 Alias changes preserve UUID identity. Deletion must account for owned elements,
 incident relationships, ordered occurrences, and diagram placements without